openchamber/docs/pairing-v2-implementation-plan.md

Pairing v2 Trusted-Device Issuance Backend Plan

Scope

Implement the Pairing v2 mechanism without UI.

Included:

• Backend pairing session runtime.
• Pairing create/redeem/cancel routes.
• Trusted-device token issuance through the existing remote client auth runtime.
• Backward-compatible remote client metadata extension.
• Password/passkey issuance metadata alignment.
• Shared v2 openchamber://connect payload helpers.

Not included:

• Settings page.
• QR modal.
• Pair Device button.
• Device list UI.
• Translations/copy.
• Relay implementation.
• LAN discovery.
• End-user polished mobile/desktop screens.

Naming

Use the existing client-auth domain.

New module:

packages/web/server/lib/client-auth/pairing.js

Existing durable token module remains:

packages/web/server/lib/client-auth/remote-clients.js

Conceptual names:

Remote client
Trusted-device client token
Pairing session
Pairing secret
Pairing redeem

Deep link stays:

openchamber://connect

Versions:

v=1 => legacy server + long-lived token import
v=2 => one-time pairing handshake

New Files

1. packages/web/server/lib/client-auth/pairing.js

Create a new backend runtime module for short-lived pairing sessions.

Responsibilities:

createPairingSession
getPairingSession
cancelPairingSession
redeemPairingSession
sweepExpiredSessions

Store file:

OPENCHAMBER_DATA_DIR/client-pairing-sessions.json

Suggested store shape:

{
  "version": 1,
  "sessions": [
    {
      "id": "pair_...",
      "secretHash": "...",
      "createdAt": "...",
      "expiresAt": "...",
      "usedAt": null,
      "cancelledAt": null,
      "clientId": null,
      "label": "Pair new device",
      "fingerprint": "ABCD-1234",
      "allowedClientKinds": ["mobile", "desktop"],
      "createdByClientId": null
    }
  ]
}

Security requirements:

Persist only secretHash.
Return plaintext secret only from createPairingSession.
Redeem is one-time.
Redeem is expiry-aware.
Redeem is cancellation-aware.
Redeem must be mutation-serialized to avoid double issuance.
No raw token/secret logging.

Public methods should accept injected dependencies, following remote-clients.js style:

createClientPairingRuntime({
  fsPromises,
  path,
  crypto,
  storePath,
  remoteClientAuthRuntime,
})

Existing Files To Update

2. packages/web/server/lib/client-auth/remote-clients.js

Extend trusted-device metadata backward-compatibly.

Current createClient input:

{
  label,
  expiresAt,
  clientKind,
  dedupeKey,
}

Extend to:

{
  label,
  expiresAt,
  clientKind,
  dedupeKey,
  authMethod,
  pairingId,
  deviceName,
  devicePlatform,
  deviceModel,
  appVersion,
}

Add normalized public fields:

authMethod
pairingId
deviceName
devicePlatform
deviceModel
appVersion

Backward compatibility rules:

Existing remote-clients.json remains valid.
Missing new fields normalize to null.
Existing tokens continue authenticating.
Public client output never exposes tokenHash.
Raw token is returned only from createClient.

Recommended authMethod values:

pairing
password
passkey
desktop-local
manual
legacy

Do not force migration for old records. Treat missing authMethod as legacy/null.

3. packages/web/server/index.js

Instantiate the new pairing runtime next to remoteClientAuthRuntime.

Existing:

const remoteClientAuthRuntime = createRemoteClientAuthRuntime({
  fsPromises,
  path,
  crypto,
  storePath: REMOTE_CLIENTS_FILE_PATH,
});

Add:

const CLIENT_PAIRING_SESSIONS_FILE_PATH = path.join(
  OPENCHAMBER_DATA_DIR,
  'client-pairing-sessions.json',
);

Then:

const clientPairingRuntime = createClientPairingRuntime({
  fsPromises,
  path,
  crypto,
  storePath: CLIENT_PAIRING_SESSIONS_FILE_PATH,
  remoteClientAuthRuntime,
});

Pass clientPairingRuntime into registerAuthAndAccessRoutes dependencies.

4. packages/web/server/lib/opencode/core-routes.js

Add pairing routes near existing client-auth routes:

/api/client-auth/clients

Add:

POST   /api/client-auth/pairing/sessions
DELETE /api/client-auth/pairing/sessions/:id
POST   /api/client-auth/pairing/redeem

Optional, can be deferred:

GET /api/client-auth/pairing/sessions/:id

Since UI polling is out of scope, GET is not required for this phase.

Route: POST /api/client-auth/pairing/sessions

Purpose:

Create one short-lived pairing session and return data needed to build QR/deep link.

Auth:

Require UI session auth.
Allow desktop-local client only if consistent with existing client-create exception.
Reject arbitrary remote client tokens.
Reject url-token auth.

Request:

{
  "label": "Pair new device",
  "allowedClientKinds": ["mobile", "desktop"]
}

Response:

{
  "pairing": {
    "id": "pair_...",
    "secret": "one_time_secret",
    "expiresAt": "...",
    "fingerprint": "ABCD-1234",
    "label": "Pair new device"
  },
  "server": {
    "label": "OpenChamber",
    "candidates": [
      {
        "type": "lan",
        "url": "http://192.168.1.20:4096",
        "priority": 10
      },
      {
        "type": "tunnel",
        "url": "https://abc.ngrok.app",
        "priority": 20
      }
    ]
  }
}

Headers:

Cache-Control: no-store

Note:

This route does not render QR.
UI can later encode the returned data into openchamber://connect?v=2&p=...

Route: DELETE /api/client-auth/pairing/sessions/:id

Purpose:

Cancel an unused pairing session.

Auth:

Require owner/session auth.

Behavior:

Set cancelledAt.
Do not delete immediately.
If already used, cancellation should not revoke the issued client.

Response:

{
  "cancelled": true
}

Route: POST /api/client-auth/pairing/redeem

Purpose:

Exchange pairingId + one-time secret for a trusted-device client token.

Auth:

No existing auth required.
The one-time pairing secret is the authentication factor.

Request:

{
  "pairingId": "pair_...",
  "secret": "one_time_secret",
  "clientLabel": "Iryna iPhone",
  "clientKind": "mobile",
  "deviceName": "Iryna iPhone",
  "devicePlatform": "ios",
  "deviceModel": "iPhone",
  "appVersion": "1.12.0",
  "dedupeKey": "optional-stable-device-key"
}

Server behavior:

Validate pairing exists.
Validate secret using constant-time comparison.
Validate not expired.
Validate not cancelled.
Validate not used.
Validate clientKind is allowed.
Mark pairing used.
Create remote client through remoteClientAuthRuntime.createClient.
Return clientToken once.

Create client with:

{
  label: clientLabel || deviceName || 'Remote client',
  clientKind,
  dedupeKey,
  authMethod: 'pairing',
  pairingId,
  deviceName,
  devicePlatform,
  deviceModel,
  appVersion,
}

Response:

{
  "ok": true,
  "server": {
    "label": "OpenChamber",
    "url": "https://selected-or-current-url",
    "fingerprint": "ABCD-1234"
  },
  "client": {
    "id": "device_...",
    "label": "Iryna iPhone",
    "clientKind": "mobile",
    "authMethod": "pairing",
    "createdAt": "..."
  },
  "clientToken": "oc_client_..."
}

Headers:

Cache-Control: no-store

Failure response should be generic:

{
  "error": "Invalid or expired pairing session"
}

Do not reveal whether id, secret, expiry, used, or cancellation caused failure.

5. packages/web/server/lib/ui-auth/ui-auth.js

Preserve existing password/passkey behavior.

Only add metadata to client token issuance when issueClientToken === true.

Password issuance should pass:

authMethod: 'password'
clientKind: req.body?.clientKind
dedupeKey: req.body?.dedupeKey
deviceName: req.body?.deviceName
devicePlatform: req.body?.devicePlatform
deviceModel: req.body?.deviceModel
appVersion: req.body?.appVersion

Passkey issuance should pass:

authMethod: 'passkey'
clientKind: req.body?.clientKind
dedupeKey: req.body?.dedupeKey
deviceName: req.body?.deviceName
devicePlatform: req.body?.devicePlatform
deviceModel: req.body?.deviceModel
appVersion: req.body?.appVersion

Backward compatibility:

Existing POST /auth/session payload still works.
Existing response shape still works.
Existing clientToken issuance still works.
Password login remains disabled for tunnel/public scope.

6. packages/ui/src/lib/connectionPayload.ts

Extend existing connect payload helpers.

Keep current v1 behavior:

openchamber://connect?v=1&server=...&token=...&label=...

Add v2 payload types and helpers.

Suggested types:

export type ClientConnectionPayloadV1 = {
  v: 1;
  serverUrl: string;
  token: string;
  label?: string;
};

export type PairingEndpointCandidate = {
  type: 'lan' | 'tunnel' | 'relay';
  url: string;
  priority?: number;
};

export type PairingConnectionPayloadV2 = {
  v: 2;
  pairingId: string;
  secret: string;
  label?: string;
  fingerprint?: string;
  expiresAt?: string;
  candidates: PairingEndpointCandidate[];
};

Suggested helpers:

encodePairingConnectionPayload(payload: PairingConnectionPayloadV2): string
parsePairingConnectionPayload(value: string): PairingConnectionPayloadV2 | null

Use deep link format:

openchamber://connect?v=2&p=<base64url-json>

Validation:

Require v=2.
Require pairingId.
Require secret.
Require at least one valid http/https candidate.
Reject malformed URL.
Reject oversized payload.
Reject expired payload locally if expiresAt is clearly in the past.

Do not break current exports used by mobile QR/manual connect.

7. packages/ui/src/apps/mobileQrScan.ts

Update parser only.

Current scan parser recognizes legacy fields like:

server
label

Add support for v2 connect links.

Output should be able to distinguish:

legacy v1 token import
pairing v2 payload
plain URL

Do not implement full mobile UI flow in this scope unless there is already a non-UI callable path.

8. packages/ui/src/apps/mobileConnections.ts

Add non-visual callable mechanism for redeeming pairing payload.

Add a function conceptually like:

redeemPairingConnection(payload: PairingConnectionPayloadV2): Promise<void>

Responsibilities:

Try endpoint candidates.
POST /api/client-auth/pairing/redeem.
Persist issued token securely.
Persist connection metadata.
Switch runtime only after token write succeeds.

No new screens/buttons.

Existing password flow remains unchanged.

Candidate selection:

Normalize candidates.
Probe /health with timeout.
Try candidates by priority.
Prefer HTTPS when priority ties.
If network failure, try next candidate.
If server says invalid/expired/used, stop.

Mobile native should reuse existing native HTTP fallback path for LAN HTTP.

9. packages/electron/main.mjs

Extend existing connect deep-link handling.

Current v1 behavior:

openchamber://connect?v=1&server=...&token=...

Keep it.

Add v2 branch:

openchamber://connect?v=2&p=...

Behavior:

Parse v2 payload.
Show confirmation before redeem/write/switch.
Probe candidates.
Redeem pairing secret.
Store returned clientToken in desktop hosts config.
Ask/switch according to existing remote host behavior.
Never show token.
Never write config before confirmation.

If this phase is strictly backend-only, this file can be deferred. But if desktop app as client must be functionally supported by deep link in this phase, include this change.

10. packages/electron/preload.mjs

No change expected unless a renderer-side desktop API is needed for pairing redeem.

Prefer keeping pairing redeem in main process only for deep-link handling if desktop v2 is implemented there.

11. packages/web/server/lib/ui-auth/DOCUMENTATION.md

Update module documentation to reflect the unified issuance model:

Password, passkey, and pairing are issuance methods.
Trusted-device client token is the durable credential.
Pairing v2 uses one-time secrets and issues remote client tokens.

Optionally add:

packages/web/server/lib/client-auth/DOCUMENTATION.md

if the client-auth module needs ownership docs.

Route Registration Summary

Add to registerAuthAndAccessRoutes:

POST   /api/client-auth/pairing/sessions
DELETE /api/client-auth/pairing/sessions/:id
POST   /api/client-auth/pairing/redeem

Optional later:

GET /api/client-auth/pairing/sessions/:id

Route placement:

Register before generic OpenCode proxy.
Place near existing /api/client-auth/clients routes.

Execution Sequence

Step 1: Extend Remote Client Metadata

Files:

packages/web/server/lib/client-auth/remote-clients.js

Do:

Add metadata normalization.
Extend createClient input.
Extend publicClient output.
Keep old records valid.
Do not change token generation/authentication behavior.

Step 2: Add Password/Passkey Metadata Issuance

Files:

packages/web/server/lib/ui-auth/ui-auth.js

Do:

When issueClientToken is true, pass authMethod='password' from password login.
When issueClientToken is true, pass authMethod='passkey' from passkey auth.
Pass optional device metadata through.
Preserve response shape.

Step 3: Create Pairing Runtime Module

Files:

packages/web/server/lib/client-auth/pairing.js

Do:

Implement session creation.
Implement hashed secret storage.
Implement cancel.
Implement redeem.
Implement expiry/used/cancelled checks.
Integrate remoteClientAuthRuntime.createClient in redeem.

Step 4: Instantiate Pairing Runtime

Files:

packages/web/server/index.js

Do:

Define CLIENT_PAIRING_SESSIONS_FILE_PATH.
Instantiate createClientPairingRuntime.
Pass clientPairingRuntime to registerAuthAndAccessRoutes.

Step 5: Add Pairing Routes

Files:

packages/web/server/lib/opencode/core-routes.js

Do:

Destructure clientPairingRuntime from dependencies.
Add POST /api/client-auth/pairing/sessions.
Add DELETE /api/client-auth/pairing/sessions/:id.
Add POST /api/client-auth/pairing/redeem.
Use correct auth gates.
Set Cache-Control: no-store where secrets/tokens are returned.
Keep error responses generic for redeem.

Step 6: Add v2 Payload Helpers

Files:

packages/ui/src/lib/connectionPayload.ts

Do:

Keep v1 helpers unchanged.
Add v2 payload type.
Add encode v2 helper.
Add parse v2 helper.
Use openchamber://connect?v=2&p=<base64url-json>.
Validate candidates.
Reject malformed/expired/oversized payloads.

Step 7: Update QR Scan Parser Shape

Files:

packages/ui/src/apps/mobileQrScan.ts

Do:

Recognize v2 connect payload.
Return structured v2 result.
Do not add new UI.
Do not break v1/manual URL behavior.

Step 8: Add Non-UI Mobile Redeem Plumbing

Files:

packages/ui/src/apps/mobileConnections.ts

Do:

Add callable redeem pairing function.
Try endpoint candidates.
Redeem via /api/client-auth/pairing/redeem.
Persist token before runtime switch.
Reuse existing storage model.
Keep password/manual connect unchanged.

Step 9: Add Desktop Deep-Link v2 Handling If In Scope

Files:

packages/electron/main.mjs

Do:

Extend connect deep-link parser to recognize v2.
Confirm before redeem.
Redeem against candidate endpoint.
Store remote host config with returned token.
Switch only after confirmation and successful storage.
Keep v1 behavior unchanged.

If desktop client deep-link support is deferred, skip this step and document that v2 backend/shared payload exists but desktop consumer is not wired yet.

Step 10: Update Documentation

Files:

packages/web/server/lib/ui-auth/DOCUMENTATION.md

Optionally add:

packages/web/server/lib/client-auth/DOCUMENTATION.md

Document:

Unified trusted-device token issuance.
Pairing v2 flow.
Password/passkey/pairing authMethod values.
Security rules.
Backward compatibility guarantees.

Important Non-Goals

Do not implement:

Settings page
Pair Device button
QR modal
Device list UI
Translations
Visual design
Relay transport
LAN discovery
Account/cloud sync
Token migration to OS keychain on desktop

Backward Compatibility Requirements

Must remain true:

Existing v1 openchamber://connect links keep working.
Existing password login with issueClientToken keeps working.
Existing passkey issueClientToken keeps working.
Existing remote-clients.json keeps loading.
Existing client tokens keep authenticating.
Existing mobile saved connections keep working.
Existing desktop remote hosts keep working.

Security Requirements

Must hold:

No long-lived token in v2 link.
Pairing secret persisted only as hash.
Pairing secret returned only once.
Client token returned only once.
Token hash persisted server-side.
Redeem is one-time.
Redeem is expiry-aware.
Redeem is cancellation-aware.
Redeem errors are generic.
Password login remains disabled for tunnel/public scope.
Pairing session creation requires owner/session auth.
Pairing redeem requires no prior auth but requires valid one-time secret.
Desktop v2 connect confirms before writing host config or switching runtime.