Pairing and device trust
Pairing attaches an Orca client to a desktop runtime through a short-lived access offer. The offer binds a reachable endpoint to a per-device credential and the desktop's encryption identity. Pairing therefore establishes both a connection path and a trust record that the desktop can later limit or revoke.
Pairing model
Pairing offers
The pairing offer is the portable invitation that moves from the desktop to the client. It has a scope that defines the access family: runtime is for another Orca client or browser runtime connection, while mobile is for the mobile client. It also carries the WebSocket endpoint, a device token, the desktop public key, and an optional device identity. Mobile offers can include Relay routing data.
Relay data is a separate, short-lived invitation for the mobile path. It names a Relay director and cell, carries an assignment version and Relay host identity, and expires within a bounded time. The offer rules reject Relay data on runtime-scoped offers and require a canonical desktop public key for Relay offers. src/…/mobile-relay-pairing-offer.ts src/…/mobile-relay-pairing-offer.ts
The desktop encodes the validated offer as an orca://pair?code=... link. The mobile client and the desktop client also accept the bare encoded value, which supports QR scans, deep links, and paste flows without changing the trust rules. The decoder rejects unknown routes, malformed data, and offers that exceed the safe input size. src/…/pairing.ts
The offer is an access grant, not a name for a host. A copied or exposed offer can be used until its pending device grant is replaced or revoked. The desktop keeps the token in its device registry and can rotate a never-used pending grant when the user regenerates a link. src/…/device-registry.ts
References: src/…/mobile-relay-pairing-offer.ts• L9-17 src/…/mobile-relay-pairing-offer.ts• L46-105 src/…/pairing.ts• L14-37 src/…/device-registry.ts• L78-140
Pairing sequence
The pairing sequence turns a user's reach choice into a scoped credential, then checks the remote identity before saving the connection. Direct and Relay paths use the same offer identity and encrypted session rules.
This diagram shows the common path for desktop-to-desktop and desktop-to-mobile attachment.
flowchart LR
A[Desktop selects scope and reach] --> B[Desktop creates pending device grant]
B --> C[Desktop builds and displays access offer]
C --> D[Client scans or pastes offer]
D --> E[Client validates scope, endpoint, and offer shape]
E --> F[Client tries an allowed connection path]
F --> G[Encrypted handshake binds desktop identity]
G --> H[Desktop checks token, scope, and protocol]
H --> I[Client saves trusted host and credentials]
For a runtime client, verification requests remote status before the environment is saved. For a mobile client, the client first resolves a stable host identity from the desktop key. It records a pairing journal before Relay work begins, then installs and confirms a durable resume credential before it saves the Relay host profile. Re-pairing updates the existing host identity instead of creating a second host card. src/…/runtime-environment-pairing-verification.ts, mobile/…/pre-profile-pairing-coordinator.ts, mobile/…/pre-profile-pairing-coordinator.ts
References: src/…/runtime-environment-pairing-verification.ts• L21-82 mobile/…/pre-profile-pairing-coordinator.ts• L128-153 mobile/…/pre-profile-pairing-coordinator.ts• L200-245 src/…/remote-runtime-client.ts• L121-177
Serve readiness
The serve readiness output gives a user or a script the endpoint and pairing state after a desktop runtime starts. It reports a pairing URL when an offer is available and gives a reason and guidance when the endpoint cannot support pairing. Human, JSON, and recipe output use the same pairing availability decision. src/…/serve-readiness.ts src/…/serve-readiness.ts
The readiness contract keeps the bound endpoint separate from the advertised endpoint. This distinction lets an operator see what the server listens on and what a remote client should use. A readiness publication is written once, so a partial or failed publication is not silently retried as if it were a new pairing grant. src/…/serve-readiness.ts, src/…/serve-readiness.test.ts
References: src/…/serve-readiness.ts• L4-20 src/…/serve-readiness.ts• L44-125 src/…/serve-readiness.test.ts• L44-111
Address selection
Advertised endpoints
An endpoint is the address and WebSocket scheme that a client uses to reach the desktop. The desktop converts a bound listener plus the user's address choice into a connectable ws: or wss: endpoint. It does not advertise wildcard listeners such as 0.0.0.0; without an explicit address, a wildcard listener resolves to loopback and stays local.
The address picker presents the user's intended reach rather than only the text of the address. Runtime sharing has three intents:
- Another device selects a discovered address for a LAN, Tailscale, or other reachable client.
- This computer only selects loopback and records a local-only reach policy.
- Custom address accepts a host, a host and port, or a full
ws(s)://URL for an SSH tunnel, reverse proxy, or other front end.
HTTP and HTTPS custom URLs are normalized to WebSocket schemes. Wildcard hosts, port zero, credentials embedded in the URL, fragments, and malformed destinations are rejected. src/…/pairing-endpoint.ts, src/…/pairing-url.ts
References: src/…/pairing-endpoint.ts• L16-40 src/…/pairing-endpoint.ts• L60-129 src/…/pairing-url.ts• L3-29 src/…/RuntimePairingGeneratorForm.tsx• L62-105
Address discovery
Automatic discovery chooses a usable host address for the selected reach. It prefers a Tailscale IPv4 address, then another usable interface address. It excludes loopback, link-local IPv6, proxy-only addresses, and known virtual bridge interfaces from the automatic choice. A user can still select a bridge or enter a custom address when that is the intended route.
The same selection rule is shared by the main process and the UI. This keeps the address shown in the picker aligned with the address placed in the generated offer. If a refresh removes an automatically selected address, the UI selects a new safe default and invalidates the old QR. An explicit custom address is preserved across a refresh. src/…/pairing-address-auto-selection.ts, src/…/mobile-network-interface-selection.ts
References: src/…/pairing-network-interfaces.ts• L17-79 src/…/pairing-address-auto-selection.ts• L17-40 src/…/mobile-network-interface-selection.ts• L12-41 src/…/use-mobile-pairing-address-preference.ts• L53-75
Reach policy
Reach policy describes where a pending grant is allowed to expose the runtime. this-computer means loopback only. network permits the listener to serve an off-host client. The policy travels with the grant because a custom address can look like loopback while still fronting an SSH tunnel or reverse proxy.
The desktop widens the listener only for an explicit network-reach choice. A local-only grant does not cause a later reconnect to publish the runtime on every interface. This protects the boundary between “the address happens to be local” and “the user allowed off-host access.” src/…/runtime-pairing-reach.ts, src/…/runtime-pairing-link-state.ts, src/…/device-registry.ts
References: src/…/runtime-pairing-reach.ts• L1-5 src/…/runtime-pairing-link-state.ts• L5-11 src/…/runtime-rpc.ts• L664-731 src/…/device-registry.ts• L17-29
Network proxy boundary
The desktop can reach pairing services through an explicit proxy setting, an environment proxy, or the system proxy. Explicit settings take priority. Proxy credentials stay in memory per network session and are supplied only to a matching proxy challenge, so they do not become part of the advertised endpoint or pairing metadata. src/…/proxy-policy-resolution.ts, src/…/electron-proxy-credentials.ts, src/…/electron-proxy-credentials.ts
Proxy changes are ordered per session. Requests wait until the newest change settles and are cancelled when the change fails or the session is retired. This keeps a pairing or Relay request from crossing a half-applied network policy. src/…/proxy-settings.ts, src/…/proxy-settings.ts, src/…/electron-proxy-request-guard.ts
References: src/…/proxy-policy-resolution.ts• L15-43 src/…/electron-proxy-credentials.ts• L37-51 src/…/electron-proxy-credentials.ts• L89-114 src/…/proxy-settings.ts• L168-237 src/…/proxy-settings.ts• L241-283 src/…/bounded-proxy-application.ts• L1-19 src/…/electron-proxy-request-guard.ts• L4-14
Connection modes
Mobile connection modes
Mobile pairing offers have two connection modes. Automatic means Anywhere: the desktop must be signed in so it can create a Relay invite. Local-only means direct access through the selected LAN, Tailscale, or custom endpoint. The default is Automatic unless the user has saved a local-only preference.
The desktop fails closed when Automatic cannot obtain Relay data. It does not label a direct-only QR as Anywhere. The UI can then offer a LAN path or a retry. A mode change invalidates the displayed offer because the old QR carries a different access policy. src/…/mobile-pairing-connection-mode.ts, src/…/runtime-rpc.ts
References: src/…/mobile-pairing-connection-mode.ts• L1-40 src/…/runtime-rpc.ts• L800-862
Direct and Relay paths
Automatic mobile pairing starts direct and Relay candidates when both are available. The first healthy candidate wins; a direct result wins an exact tie. Local-only starts only the direct path. Both paths then use the desktop public key and the device token from the offer.
The mobile client authenticates to a Relay cell with either the short-lived invite or a later resume credential. The Relay must accept that credential before the encrypted channel starts, and the client rejects a response that names the wrong credential kind. The encrypted channel then carries the pairing status request and later RPC traffic. mobile/…/mobile-relay-physical-client.ts, mobile/…/mobile-relay-physical-client.ts, mobile/…/mobile-relay-e2ee-link.ts, src/…/mobile-relay-phone-protocol.ts
If a Relay cell moves, the client asks the configured director for an authenticated assignment with a strictly newer epoch. It persists that move before dialing the new cell. A non-newer response leaves the stored cell authoritative and causes a bounded retry instead of adopting an untrusted location. Only failures that can be relieved by a new assignment enter this recovery path. mobile/…/mobile-relay-invite-director.ts, mobile/…/pairing-relay-candidate.ts, mobile/…/pairing-relay-candidate.ts
The pairing log labels every entry as Direct or Relay at the candidate boundary. This lets the scan screen show which path failed without exposing invite material. mobile/…/pairing-log-path.ts, mobile/…/mobile-relay-physical-client.ts
Relay adds an invite that is short-lived and bound to a Relay host identity. After the initial authenticated connection, the client requests a durable resume credential and the desktop returns the Relay endpoint. The mobile client keeps that credential in the native secure store and uses only unexpired, non-rejected credentials for later connections. mobile/…/pre-profile-pairing-coordinator.ts, mobile/…/mobile-relay-credential-bundle.ts
References: src/…/mobile-pairing-connection-mode.ts• L10-40 src/…/runtime-rpc.ts• L800-938 mobile/…/pairing-candidate-race.ts• L10-59 mobile/…/mobile-relay-physical-client.ts• L91-180 mobile/…/mobile-relay-invite-director.ts• L25-109 mobile/…/pairing-relay-candidate.ts• L47-169 mobile/…/pairing-log-path.ts• L9-27 mobile/…/pre-profile-pairing-coordinator.ts• L218-245 mobile/…/mobile-relay-credential-bundle.ts• L22-109
Trust boundaries
Encrypted identity checks
The offer pins the desktop public key. During connection, the client derives a shared encryption key from its temporary key pair and that pinned key. The encrypted handshake then proves that the endpoint is speaking for the desktop identity named by the offer rather than only proving that a socket is open. src/…/remote-runtime-client.ts, src/…/e2ee-crypto.ts
The mobile protocol makes the transport part of the handshake context. A direct session and a Relay session must agree on the protocol, participants, framing, and Relay host identity when present. The Relay outer handshake runs before E2EE and reports typed close codes, so an endpoint rejection is not confused with a cryptographic failure. src/…/mobile-e2ee-v2-contract.ts, src/…/mobile-e2ee-v2-contract.ts, mobile/…/mobile-relay-e2ee-link.ts
References: src/…/remote-runtime-client.ts• L146-177 src/…/e2ee-crypto.ts• L11-27 src/…/mobile-e2ee-v2-contract.ts• L7-31 src/…/mobile-e2ee-v2-contract.ts• L45-107 mobile/…/mobile-relay-e2ee-link.ts• L86-169
Scope and authorization
After the encrypted channel is established, the desktop resolves the device token to a registry entry. The entry supplies the stable device identity and the access scope. A mobile-scoped token can call only the mobile method set; a runtime-scoped token can use the runtime client surface. The desktop ignores a conflicting token repeated inside an authenticated request.
The runtime client verifies the returned status before it saves a host. It rejects a mobile-only offer, a bad status shape, and incompatible protocol versions. It also reports a host identity mismatch when the reached endpoint does not match the public key in the offer. src/…/runtime-rpc.ts, src/…/remote-pairing-verification.ts
Removing a device deletes its desktop grant and terminates its active connections. Removing a mobile host also schedules deletion of its stored device and Relay credentials. A persistent mobile rejection eventually becomes a re-pair state, while a plain Relay outage remains an unreachable state. This keeps an invalid grant distinct from a temporary network failure. src/…/runtime-rpc.ts, mobile/…/host-store.ts, mobile/…/mobile-relay-pairing-rejection-escalation.test.ts, mobile/…/mobile-relay-pairing-rejection-escalation.test.ts
References: src/…/runtime-rpc.ts• L1637-1723 src/…/remote-pairing-verification.ts• L54-113 src/…/runtime-rpc.ts• L640-656 mobile/…/host-store.ts• L257-287 mobile/…/mobile-relay-pairing-rejection-escalation.test.ts• L72-112 mobile/…/mobile-relay-pairing-rejection-escalation.test.ts• L223-237
Local UI state
Runtime attachment fields
The desktop runtime sharing UI lets the owner choose how a link will be opened and where it will point. The generated link and its display state remain available while the user moves through Settings, but the credential material remains owned by the main process.
The runtime sharing surface exposes these important fields:
| Field | Purpose |
|---|---|
| Link intent | Chooses another device, this computer only, or a custom address. |
| Connection address | Shows the selected discovered address or the custom endpoint. |
| Name in Orca | Sets the local label for the attached computer. |
| Access link | Accepts the link or bare pairing value from the other host. |
| Link destination | Shows the parsed endpoint and its loopback, Tailscale, LAN, public, or custom class before connection. |
| SSH tunnel override | Allows a loopback endpoint when the user keeps an SSH tunnel active. |
The add-host form blocks a loopback link by default. The override is explicit because loopback normally means “this device,” while an SSH tunnel makes it a deliberate local front end for another host. src/…/RuntimeHostAccessForm.tsx, src/…/RuntimeHostAccessForm.tsx
References: src/…/RuntimePairingGeneratorForm.tsx• L62-105 src/…/RuntimePairingGeneratorForm.tsx• L139-191 src/…/RuntimeHostAccessForm.tsx• L43-67 src/…/RuntimeHostAccessForm.tsx• L98-171
Mobile attachment fields
The mobile settings surface controls the path and address used to mint a QR. It remembers the selected mode and custom addresses, refreshes discovered interfaces, and removes a shown QR when its endpoint or policy changes. A paired-device list gives the owner a place to revoke mobile grants.
The mobile surface exposes these important fields:
- Connection path: Automatic or Local-only.
- Connection address: A discovered interface or saved custom address.
- Generate QR: Creates the offer for the current path and address.
- Pairing code and endpoint: Shows the QR payload and the endpoint that it represents.
- Paired devices: Shows attached mobile identities and supports revocation.
Automatic generation is disabled while the desktop is signed out. Sign-out also clears a displayed Automatic QR so a stale Relay invite is not left on screen. src/…/MobilePane.tsx, src/…/MobilePane.tsx, src/…/MobilePane.tsx
References: src/…/MobilePane.tsx• L77-114 src/…/MobilePane.tsx• L116-126 src/…/MobilePane.tsx• L170-232 src/…/MobilePane.tsx• L390-460
Mobile scan surface
The mobile scan surface is the receiving entry point for a desktop offer. It accepts a QR code or a pasted orca://pair?code=... value, validates the offer before connecting, and shows a bounded connection state with a path-aware pairing log when the attempt fails.
Camera permission is not required for paste pairing. A scan attempt has a 25-second overall limit, and leaving the screen disposes the active attempt so a late result cannot navigate a new screen. A successful pairing refreshes the cached host client and continues to mobile onboarding. mobile/…/pair-scan.tsx, mobile/…/pair-scan.tsx, mobile/…/pair-scan.tsx
The screen keeps the camera area stable while the paste sheet is open and uses a square scan guide across rectangular camera views. These choices keep the QR action clear without changing the offer or trust rules. mobile/…/pair-scan.tsx, mobile/…/pair-scan-styles.ts
References: mobile/…/pair-scan.tsx• L48-111 mobile/…/pair-scan.tsx• L126-184 mobile/…/pair-scan.tsx• L217-257 mobile/…/pair-scan.tsx• L274-355 mobile/…/pair-scan-styles.ts• L4-57 mobile/…/pair-scan-styles.ts• L103-184
Pairing-local UI fields
Some UI state belongs to the client that displays it and must not cross the pairing boundary. These fields describe local workspace visibility, local ordering, and local automation filtering. The paired UI exchange strips them on the way to a host and keeps the receiving client's own values on the way back.
The protected fields are:
automationHostFilterhideWorkspacesFromOtherDevicesmanualRepoOrderworkspaceHostOrder
This separation lets a paired client share host-backed UI data without allowing one device to overwrite another device's local layout or automation choices. src/…/pairing-local-ui-fields.ts
References: src/…/pairing-local-ui-fields.ts• L3-30 src/…/pairing-local-ui-fields.test.ts• L5-41 src/…/web-preload-api.ts• L4160-4185 src/…/client-ui-pairing-local-fields.test.ts• L13-89
Related pages
- Remote connectivity — parent overview of remote access.
- Remote runtime transport — connection behavior after pairing succeeds.
- Mobile client — mobile-side product behavior and host use.
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the offer schema and both Node and mobile decoders aligned. QR, deep-link, and paste flows must accept the same shapes.
- Keep endpoint normalization, address discovery, and UI address defaults aligned. A changed default can make the displayed address differ from the address in a new offer.
- Treat scope, connection mode, and reach as one grant contract. Changing one without rotating or invalidating the pending offer can widen access under an old policy.
- Keep the desktop public-key check and the runtime status check in the same verification path. Saving a host before both checks pass weakens the identity boundary.
- Keep Relay invite installation, endpoint publication, and secure credential promotion ordered. A host record must not point to Relay access that was not durably installed.
- Persist a newer Relay assignment before dialing it. Do not adopt a non-newer director response or route endpoint errors into director recovery when a new assignment cannot help.
- Keep direct and Relay log attribution at the candidate boundary. A new log-producing path must not appear to belong to the wrong network path or expose credential material.
- Keep proxy credentials session-scoped and request readiness closed during failed or retired proxy transitions. Pairing must not use a half-applied network policy.
- Add new client-local UI fields to the pairing-local field census before exposing them through paired UI RPCs.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Automatic mobile pairing while the desktop is signed out | No Anywhere QR is created. | Require sign-in for Relay minting and offer Local-only instead. |
| Relay invite is expired or a cell rejects it after reservation | Pairing cannot complete, and repeated attempts may consume the invite budget. | Validate expiry and do not send cell-load refusals through director recovery. |
| Relay director returns a same or older assignment | The client must not move to an untrusted or stale cell. | Accept only a strictly newer authenticated assignment and keep the stored cell authoritative otherwise. |
| A runtime link points to loopback on the receiving device | The add-host action is blocked because it may point back to the wrong computer. | Require a Tailscale/LAN link or an explicit SSH tunnel override. |
| The endpoint is wildcard, port zero, malformed, or not WebSocket-based | The offer cannot produce a usable connection. | Normalize and validate the advertised endpoint before encoding it. |
| The reached host has a different public key or incompatible protocol | Pairing stops before the host is saved. | Verify host identity and runtime compatibility from authenticated status. |
| A Relay socket error has no close event | The pairing attempt could remain pending. | Convert the missing close into a bounded typed transport failure. |
| A device token is revoked, expired, or rejected | New requests fail and the old connection is terminated. | Validate the registry entry or Relay credential on every connection path. |
| Proxy application fails or a proxy session is retired | Requests are cancelled instead of crossing an unknown network state. | Hold requests through the newest transition and fail closed after bounded retries. |
| A paired UI field is exchanged as host state | One client can overwrite another client's local layout or automation filter. | Strip every field in the shared pairing-local census in both directions. |
Key files
| File | Why to read it |
|---|---|
| src/…/pairing.ts | Defines the portable access-link format and parse rules. |
| src/…/mobile-relay-pairing-offer.ts | Defines offer scope, Relay invite shape, and expiry rules. |
| src/…/runtime-rpc.ts | Shows how the desktop creates grants and chooses mobile pairing modes. |
| src/…/device-registry.ts | Shows per-device credentials, scope, reach, rotation, and revocation. |
| src/…/remote-pairing-address.ts | Classifies destinations and rejects unsafe access-link endpoints. |
| src/…/remote-pairing-verification.ts | Defines the checks made before a runtime host is accepted. |
| src/…/runtime-environment-pairing-verification.ts | Connects link parsing, remote verification, and local host saving. |
| src/…/serve-readiness.ts | Defines the pairing information exposed to users and scripts when a server starts. |
| mobile/…/pre-profile-pairing-coordinator.ts | Shows the mobile pairing sequence across direct and Relay paths. |
| mobile/…/mobile-relay-physical-client.ts | Shows Relay credential acceptance and encrypted pairing RPCs. |
| mobile/…/mobile-relay-invite-director.ts | Shows authenticated Relay assignment changes. |
| mobile/…/pairing-relay-candidate.ts | Shows bounded Relay recovery and durable move ordering. |
| mobile/…/mobile-relay-credential-bundle.ts | Shows where durable mobile Relay credentials are kept and promoted. |
| mobile/…/pair-scan.tsx | Illustrates QR and paste intake, timeout, logs, and post-pair navigation. |
| src/…/proxy-settings.ts | Shows how the desktop applies and orders proxy policy for network sessions. |
| src/…/electron-proxy-credentials.ts | Shows the session boundary for proxy credentials. |
| src/…/RuntimePairingGeneratorForm.tsx | Illustrates the runtime sharing choices and address fields. |
| src/…/RuntimeHostAccessForm.tsx | Illustrates the receiving form and loopback safeguard. |
| src/…/MobilePane.tsx | Illustrates mobile mode, address, QR, and revocation controls. |
| src/…/pairing-local-ui-fields.ts | Defines UI state that must remain local to each paired client. |