Trezor Bridge — Browser to Device Connector

Overview

What is Trezor Bridge, why it existed, and how it fits into the Trezor ecosystem

Why a Bridge?

Benefits and historical motivations

Motivation

• Browser constraints: Not all browsers had the same level of USB support; Bridge provided a consistent cross-browser interface.
• Security gating: By using a local service with strict origins and CORS, the interaction could be limited to approved web apps.
• Backward compatibility: Applications built before widespread WebUSB adoption could still work reliably.

Functional responsibilities

• Enumerate connected Trezor devices.
• Open secure USB channels and translate low-level USB messages into JSON-RPC.
• Provide user-friendly installers and auto-updates on some platforms (historically).

Architecture

Component-level view and dataflow

Security model

Threat model, guarantees, and limitations

What Bridge protects

• Improves UX and reduces developer complexity when dealing with cross-browser USB differences.
• Allows detailed permission prompts and possibility to restrict access to specific origins.

What it does not do — immutable device guarantees

• Bridge never learns private keys or seed phrases; all signing occurs on-device.
• Compromise of Bridge affects availability and could potentially allow unscrupulous apps to try to speak to the device — but user confirmation on-device remains the critical final gate.

Installation & lifecycle

How users install Bridge historically and migration to Suite/WebUSB

Installation (historical)

• Download platform-specific installer from Trezor website.
• Run installer, which installs a small background service and a localhost endpoint.
• Browsers connect to localhost when web DApps request device access.

Migration & deprecation

Trezor's official guidance notes that a standalone Bridge has been deprecated in favor of Trezor Suite and WebUSB-based integrations. If you still run a standalone Bridge, consult the official removal/uninstall guidance before upgrading. :contentReference[oaicite:2]{index=2}

Developer integration

How web apps historically integrated with Bridge and modern alternatives

Legacy integration pattern

1. Detect Bridge on localhost using expected ports and endpoints.
2. Send JSON-RPC connection requests to enumerate devices.
3. Relay user actions to the device via RPC calls and handle responses.

Modern alternatives

• WebUSB: Browser-level API (Chrome/Edge) that enables direct USB access with explicit user gesture and origin checks.
• Trezor Suite SDK / Bridge API: Use officially supported SDKs for best compatibility.

// Pseudocode: detect Bridge or fallback to WebUSB
if (await detectBridge()) {
  await bridge.connect();
} else if (navigator.usb) {
  const device = await navigator.usb.requestDevice({ filters: [{ vendorId: 0x1209 }] });
  // use WebUSB flow
}

UX & user flow examples

Suggested UX flows to reduce user errors and increase security

Recommended flow for web wallets

• Initiate connect: User clicks “Connect hardware wallet”.
• Detect options: Show whether WebUSB is available or Bridge is required.
• Install prompt if needed: Provide an in-page guided link to the official installer.
• On-device confirmation: Always present transaction summary on the device screen and instruct the user to verify it.

Troubleshooting & FAQs

Common issues and practical troubleshooting steps

Common problems

• Browser cannot find device — check that Bridge or Suite is installed, USB cable is known-good, and device is unlocked.
• Permissions error — ensure you used an official installer and that no corporate firewall blocks localhost ports.
• Conflicting drivers — uninstall old Bridge if upgrading to Suite integration (official docs explain removal procedures). :contentReference[oaicite:3]{index=3}

Quick checklist

• Use official trezor.io resources only.
• Try a different USB cable or port (avoid hub when possible).
• Update device firmware via Trezor Suite (if available and necessary).

Migration plan for organizations

From Bridge-based integrations to modern WebUSB / Suite-based architecture

1. Inventory: Find all product features that rely on Bridge-dependent flows.
2. Compatibility mapping: Create support matrix for browsers and OSes.
3. Refactor: Replace Bridge RPC calls with WebUSB or vendor SDK plus graceful fallback.
4. Testing: Create integration tests that simulate device responses and edge cases.
5. Communicate: Notify end users about recommended upgrades and uninstall instructions.

Deep dive — protocol & message flow

Technical message formats and error handling (conceptual)

JSON-RPC structure (conceptual)

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "applySettings",
  "params": {
    "label": "My Trezor",
    "language": "en-US"
  }
}

Error handling

• Transport errors: Reconnect and surface friendly messages like “Device not found”.
• Device errors: Present device-provided error codes verbatim to logs while showing user-friendly guidance.
• Security warnings: If origin mismatches or unexpected requests occur, cancel them and require manual re-confirmation.

Compliance & privacy considerations

Personal data, telemetry, and legal considerations

• Minimize telemetry from Bridge to essentials only; provide opt-outs in installers.
• Document data flows for audits: which network endpoints are used, what local files are stored.
• Encourage using Trezor Suite signed releases to reduce supply-chain risk.

Appendix & Resources

Useful links and references (official docs recommended)

• Trezor official site: trezor.io — start and suite pages. :contentReference[oaicite:4]{index=4}
• Trezor Suite & Install Guides: Official install and removal docs for Bridge and Suite. :contentReference[oaicite:5]{index=5}
• Browser WebUSB docs — consult browser vendor documentation when integrating WebUSB.

Prepared code snippets

// Detecting Bridge: conceptual only
async function detectBridge() {
  try {
    const resp = await fetch('http://localhost:21325/version', {mode: 'cors'});
    return resp.ok;
  } catch(e) {
    return false;
  }
}