hivehq 2.0.0

package/dist/src/server/remote-gateway-client.d.ts

@@ -0,0 +1,14 @@
+export interface PostPairConfirmDeps {
+    gatewayUrl: string;
+    daemonToken: string;
+    /** Inject a fetch for tests; defaults to the global fetch. */
+    fetchImpl?: typeof fetch;
+}
+export interface PairConfirmBody {
+    deviceId: string;
+    /** The device's X25519 public key, base64url — opaque to the gateway. */
+    devicePubkey: string;
+    name: string;
+    boundJti: string;
+}
+export declare const postPairConfirm: (deps: PostPairConfirmDeps, body: PairConfirmBody) => Promise<void>;

package/dist/src/server/remote-gateway-client.js

@@ -0,0 +1,36 @@
+// Daemon → gateway HTTP client (plan D5). The pairing data-plane rides the wss
+// tunnel, but the device-row creation is a separate, daemon-token-authed HTTPS
+// call: only a real daemon (post-desktop-confirm) may create the gateway's device
+// row, which is what later lets the phone's /pair/session mint a device-bound
+// cookie. A phone has no daemon token, so it can never self-promote.
+//
+// Wire contract mirrors gateway/src/pair.ts POST /pair/confirm and the shape the
+// gateway tests exercise (gateway/test/pairing-relay.test.ts postConfirm):
+//   POST ${gatewayUrl}/pair/confirm
+//   Authorization: Bearer <daemonToken>
+//   { deviceId, devicePubkey, name, boundJti }   (devicePubkey is base64url)
+// The gateway 200s on create-or-idempotent; any non-2xx is a hard failure here so
+// the confirm path can refuse to tell the phone "confirmed" (see remote-pairing).
+//
+// trimSlash + the header/body shape deliberately match src/cli/hive-remote.ts so
+// the daemon and CLI speak the gateway identically.
+const trimSlash = (url) => url.replace(/\/+$/, '');
+export const postPairConfirm = async (deps, body) => {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const res = await fetchImpl(`${trimSlash(deps.gatewayUrl)}/pair/confirm`, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+            authorization: `Bearer ${deps.daemonToken}`,
+        },
+        body: JSON.stringify({
+            deviceId: body.deviceId,
+            devicePubkey: body.devicePubkey,
+            name: body.name,
+            boundJti: body.boundJti,
+        }),
+    });
+    if (!res.ok) {
+        throw new Error(`gateway /pair/confirm failed: ${res.status}`);
+    }
+};

package/dist/src/server/remote-loopback-auth.d.ts

@@ -0,0 +1,6 @@
+export declare const HIVE_REMOTE_SECRET_HEADER = "x-hive-remote-secret";
+export declare const HIVE_REMOTE_DEVICE_HEADER = "x-hive-remote-device";
+export declare function isTunnelDroppedRequestHeader(name: string): boolean;
+export declare function stampLoopbackHeaders(headers: Array<[string, string]> | Record<string, string>, secret: string, deviceId: string): Record<string, string>;
+export declare function isTunnelStrippedResponseHeader(name: string): boolean;
+export declare function sanitizeTunnelResponseHeaders(headers: Array<[string, string]>): Array<[string, string]>;

package/dist/src/server/remote-loopback-auth.js

@@ -0,0 +1,112 @@
+// Per-boot internal-secret header plumbing for the loopback bridge (invariant 2).
+//
+// The secret VALUE lives in UiAuth (the single token authority) — it is
+// generated at boot, held only in-process, NEVER persisted, NEVER logged. This
+// file holds only the wire-header names and the request/response header
+// helpers the bridge uses. A 127.0.0.1 request carrying the live secret is
+// authorized as tunnel-originated; absent/forged secret => normal UI-token
+// treatment (rejected). This is the ONLY escalation to tunnel authority, and it
+// is unforgeable from outside the runtime process.
+// Tunnel-originated loopback requests carry these. They are also audit-tagging:
+// x-hive-remote-device identifies the paired device for the audit trail. Both
+// are stripped from any client-supplied copy before we stamp our own, so a
+// phone can neither spoof the device tag nor smuggle a guessed secret.
+export const HIVE_REMOTE_SECRET_HEADER = 'x-hive-remote-secret';
+export const HIVE_REMOTE_DEVICE_HEADER = 'x-hive-remote-device';
+// VULN-LOOPBACK-1: the request side needs the same posture as the response side. The phone fully
+// controls the Open meta header list, and Node's http client copies any header we hand it verbatim
+// (it only synthesises Host when none is present). A strip-2 blocklist let a phone smuggle
+// Host/Origin/Cookie/X-Forwarded-*/Content-Length/Transfer-Encoding onto the 127.0.0.1 request,
+// contradicting this file's "a phone can neither spoof nor smuggle" invariant. So we DROP every
+// header that doesn't belong on a tunnel-originated loopback request and only let through the few
+// the local runtime actually reads.
+//
+// Dropped, by reason:
+//   - the 2 tunnel headers (always — we re-stamp our own copy last so it wins)
+//   - host / origin — would defeat the daemon's fail-closed local-request guard (self-DoS) and have
+//     no business being phone-controlled
+//   - cookie — the phone never holds hive_ui_token; a guessed cookie is inert but doesn't belong here
+//   - content-length / transfer-encoding — the bridge frames the body itself; a phone-declared length
+//     is a request-smuggling primitive
+//   - all hop-by-hop headers (meaningless across the mux boundary)
+//   - any x-forwarded-* (the daemon is the origin; a forged forwarded chain is never trusted)
+const REQUEST_HOP_BY_HOP_HEADERS = new Set([
+    'connection',
+    'keep-alive',
+    'proxy-authenticate',
+    'proxy-authorization',
+    'te',
+    'trailer',
+    'transfer-encoding',
+    'upgrade',
+]);
+const REQUEST_DROPPED_HEADERS = new Set([
+    'host',
+    'origin',
+    'cookie',
+    'content-length',
+    HIVE_REMOTE_SECRET_HEADER,
+    HIVE_REMOTE_DEVICE_HEADER,
+]);
+export function isTunnelDroppedRequestHeader(name) {
+    const lk = name.toLowerCase();
+    if (REQUEST_DROPPED_HEADERS.has(lk))
+        return true;
+    if (REQUEST_HOP_BY_HOP_HEADERS.has(lk))
+        return true;
+    if (lk.startsWith('x-forwarded-'))
+        return true;
+    return false;
+}
+// Stamp the loopback request/upgrade headers for a tunnel-originated request:
+// drop every smuggling-prone / tunnel-only header (isTunnelDroppedRequestHeader), then set ours.
+// Accepts the M1 header list ([name, value] pairs, which keep order + duplicates) or a plain record
+// — the bridge passes meta.http.headers (a list) directly.
+export function stampLoopbackHeaders(headers, secret, deviceId) {
+    const entries = Array.isArray(headers) ? headers : Object.entries(headers);
+    const out = {};
+    for (const [k, v] of entries) {
+        if (isTunnelDroppedRequestHeader(k))
+            continue;
+        out[k] = v;
+    }
+    out[HIVE_REMOTE_SECRET_HEADER] = secret;
+    out[HIVE_REMOTE_DEVICE_HEADER] = deviceId;
+    return out;
+}
+// HARDEN (response-header policy, invariant alongside 1/2): the bridge seals the
+// loopback HTTP response head (status + headers) back to the phone. Some /api
+// responses carry headers meant only for the local browser/runtime boundary —
+// most dangerously Set-Cookie (the master hive_ui_token), but also any internal
+// x-hive-* header now or in the future. The bridge MUST strip these before
+// encodeHttpHead for tunnel-originated responses, so no auth/identity header
+// ever crosses the trust boundary onto a remote device.
+//
+// Strips: hop-by-hop headers (meaningless across the mux boundary), Set-Cookie
+// (any casing), and any x-hive-* internal header. Header NAMES are matched
+// case-insensitively against the response head's [name, value] pairs.
+const HOP_BY_HOP_HEADERS = new Set([
+    'connection',
+    'keep-alive',
+    'proxy-authenticate',
+    'proxy-authorization',
+    'te',
+    'trailer',
+    'transfer-encoding',
+    'upgrade',
+]);
+const AUTH_BEARING_RESPONSE_HEADERS = new Set(['set-cookie', 'set-cookie2']);
+export function isTunnelStrippedResponseHeader(name) {
+    const lk = name.toLowerCase();
+    if (HOP_BY_HOP_HEADERS.has(lk))
+        return true;
+    if (AUTH_BEARING_RESPONSE_HEADERS.has(lk))
+        return true;
+    // Any internal x-hive-* header is daemon<->local-boundary only; never relay it.
+    if (lk.startsWith('x-hive-'))
+        return true;
+    return false;
+}
+export function sanitizeTunnelResponseHeaders(headers) {
+    return headers.filter(([name]) => !isTunnelStrippedResponseHeader(name));
+}

package/dist/src/server/remote-pairing-tunnel.d.ts

@@ -0,0 +1,59 @@
+import type { PostPairConfirmDeps } from './remote-gateway-client.js';
+import type { RemotePairing } from './remote-pairing.js';
+export interface PairingHelloFrame {
+    t: 'hello';
+    devicePublicKey: string;
+    sessionSalt: string;
+    proposedName?: string;
+}
+export type PairingInboundFrame = PairingHelloFrame;
+export interface PairAckFrame {
+    t: 'pair-ack';
+    daemonPublicKey: string;
+    daemonId: string;
+    deviceId: string;
+    protocolVersion: number;
+}
+export interface ConfirmedFrame {
+    t: 'confirmed';
+    deviceId: string;
+}
+export interface RejectedFrame {
+    t: 'rejected';
+    reason: 'expired';
+}
+export type PairingOutboundFrame = PairAckFrame | ConfirmedFrame | RejectedFrame;
+export interface RemotePairingTunnelDeps {
+    pairing: RemotePairing;
+    /** Emit a JSON text frame over the live tunnel socket (the relay fans it to the pair socket). */
+    send: (frame: PairingOutboundFrame) => void;
+    /** D5 seam: POST /pair/confirm to the gateway. Injected so tests don't hit the real fetch path. */
+    postPairConfirm: (deps: PostPairConfirmDeps, body: PairConfirmArgs) => Promise<void>;
+    getGatewayUrl: () => string | null;
+    getDaemonToken: () => string | null;
+}
+export interface PairConfirmArgs {
+    deviceId: string;
+    devicePubkey: string;
+    name: string;
+    boundJti: string;
+}
+export interface RemotePairingTunnel {
+    /**
+     * The gateway told us a pair socket attached for this daemon, carrying the pairing session's jti
+     * (D2). A NEW peer-online RESETS the active pairing (D1 replace race — the relay swapped the pair
+     * socket, so any half-done handshake is now stale and must not be confirmable) and records the jti
+     * so the next hello binds to it.
+     */
+    onPeerOnline(jti: string | undefined): void;
+    /** A TEXT frame arrived on the tunnel. Parse + route; on `hello`, run the daemon handshake half. */
+    onPairingFrame(text: string): void;
+    /**
+     * Desktop confirm (D3). Insert the local row (trust root), POST /pair/confirm, then send
+     * `confirmed`. Returns the local RemoteDeviceRecord (or null if the engine wouldn't confirm).
+     * Throws if the gateway POST fails or boundJti is missing — the route surfaces it and the phone is
+     * NOT told confirmed.
+     */
+    confirm(pairingId: string, name?: string): Promise<ReturnType<RemotePairing['confirmPairing']>>;
+}
+export declare const createRemotePairingTunnel: (deps: RemotePairingTunnelDeps) => RemotePairingTunnel;

package/dist/src/server/remote-pairing-tunnel.js

@@ -0,0 +1,146 @@
+// Daemon-side pairing-over-tunnel glue (plan steps 2 + 4, decisions D1/D2/D3).
+//
+// Pairing rides the SAME outbound gateway socket as the data tunnel, but as JSON TEXT frames (the
+// data plane is binary). The relay forwards them opaque between the unpaired phone's `/relay/pair`
+// socket and this daemon's `/relay/daemon` socket. This driver is the daemon half of the wire:
+//
+//   phone  -> daemon : {"t":"hello", devicePublicKey, sessionSalt, proposedName?}   (b64url keys)
+//   daemon -> phone  : {"t":"pair-ack", daemonPublicKey, daemonId, deviceId, protocolVersion}
+//      ... the human compares the 6-digit SAS on phone vs desktop and confirms ON THE DESKTOP ...
+//   daemon -> phone  : {"t":"confirmed", deviceId}
+//
+// The driver does NOT own the socket — the tunnel injects `send(obj)` (JSON-stringify + socket.send)
+// and routes inbound text frames here. It DOES own the active-pairing association (D1: one at a time
+// per daemon — the relay allows a single pair socket, replacing the older with 4409) plus the boundJti
+// the gateway conveys (D2: the phone can't read its own HttpOnly-cookie jti, so the relay's pair
+// `peer-online` carries it; the daemon captures it and uses it as boundJti for /pair/confirm).
+//
+// confirm() is the desktop-confirm sequence (D3): local row insert (the trust-root write, owned by the
+// engine) -> AWAIT POST /pair/confirm (creates the gateway device row keyed by boundJti) -> only THEN
+// tell the phone `confirmed`. Ordering guarantees the phone's subsequent /pair/session finds the row
+// (no 403 race). If the gateway POST fails OR boundJti never arrived, we do NOT send `confirmed` — the
+// phone is left to re-scan rather than told a half-finished pairing succeeded.
+import { fromBase64Url, SESSION_SALT_LEN, toBase64Url, X25519_KEY_LEN, } from '../shared/remote-crypto.js';
+const isHello = (v) => typeof v === 'object' &&
+    v !== null &&
+    v.t === 'hello' &&
+    typeof v.devicePublicKey === 'string' &&
+    typeof v.sessionSalt === 'string';
+export const createRemotePairingTunnel = (deps) => {
+    // At most one active pairing per daemon (D1). A null boundJti means the gateway peer-online either
+    // hasn't arrived yet or didn't carry a jti — confirm() refuses in that case.
+    let active = null;
+    // The jti the most recent pair peer-online carried. Captured separately from `active` because the
+    // peer-online arrives BEFORE the hello (the relay emits it on pair-socket attach); the hello then
+    // adopts it. A new peer-online overwrites this and resets `active`.
+    let pendingBoundJti = null;
+    const onPeerOnline = (jti) => {
+        // D1 replace race: a new pair socket (possibly a different phone) supersedes any in-flight
+        // handshake. Drop the stale active pairing so a confirm on it can never go through.
+        active = null;
+        pendingBoundJti = jti ?? null;
+    };
+    const onPairingFrame = (text) => {
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            return;
+        }
+        if (!isHello(parsed))
+            return;
+        let devicePublicKey;
+        let sessionSalt;
+        try {
+            devicePublicKey = fromBase64Url(parsed.devicePublicKey);
+            sessionSalt = fromBase64Url(parsed.sessionSalt);
+        }
+        catch {
+            return;
+        }
+        if (devicePublicKey.length !== X25519_KEY_LEN || sessionSalt.length !== SESSION_SALT_LEN) {
+            return;
+        }
+        // D1: map the hello to the daemon's single awaiting_handshake pending pairing. The relay only
+        // lets one pair socket attach, so there is at most one pending the inbound hello can belong to.
+        // (The phone's hello carries no pairingId — that handle lives only on the desktop.)
+        const pairingId = deps.pairing.findAwaitingHandshake();
+        if (!pairingId) {
+            deps.send({ t: 'rejected', reason: 'expired' });
+            return;
+        }
+        const view = deps.pairing.submitDeviceHello({
+            pairingId,
+            devicePublicKey,
+            sessionSalt,
+            ...(parsed.proposedName !== undefined ? { proposedName: parsed.proposedName } : {}),
+        });
+        if (!view) {
+            deps.send({ t: 'rejected', reason: 'expired' });
+            return;
+        }
+        const reply = deps.pairing.getHandshakeReply(pairingId);
+        if (!reply) {
+            deps.send({ t: 'rejected', reason: 'expired' });
+            return;
+        }
+        active = {
+            pairingId,
+            deviceId: reply.deviceId,
+            devicePublicKey,
+            boundJti: pendingBoundJti,
+            name: parsed.proposedName ?? null,
+        };
+        deps.send({
+            t: 'pair-ack',
+            daemonPublicKey: toBase64Url(reply.daemonPublicKey),
+            daemonId: reply.daemonId,
+            deviceId: reply.deviceId,
+            protocolVersion: reply.protocolVersion,
+        });
+    };
+    const confirm = async (pairingId, name) => {
+        // Atomicity (issue: confirm wasn't atomic). The OLD order wrote the device row + consumed the
+        // pending FIRST, then checked boundJti/token and POSTed the gateway — so a missing boundJti, a
+        // logged-out daemon, or a failed gateway POST left a GHOST local device + a dead (consumed) pairing
+        // code, while the desktop reported failure. The device list changed under a "failed" confirm.
+        //
+        // New order: every pre-write check + the gateway row come FIRST; the local trust-root write happens
+        // ONLY after the gateway succeeds. Any pre-write failure leaves the pending pairing fully intact —
+        // the desktop can retry, the phone can rescan, nothing half-finished is persisted.
+        // Non-consuming gone/expired check: keep the null-return contract for a pairing that's no longer
+        // confirmable (so the route still answers "not found" instead of throwing).
+        if (!deps.pairing.getPending(pairingId))
+            return null;
+        // The active handshake carries the devicePublicKey + boundJti (D2) the gateway row is keyed by.
+        if (active?.pairingId !== pairingId || !active.boundJti || !active.devicePublicKey) {
+            throw new Error('pairing confirm: missing boundJti for gateway registration');
+        }
+        const gatewayUrl = deps.getGatewayUrl();
+        const daemonToken = deps.getDaemonToken();
+        if (!gatewayUrl || !daemonToken) {
+            throw new Error('pairing confirm: remote not logged in');
+        }
+        // Resolve the name the SAME way the engine's confirmPairing will (operator override → phone's
+        // proposedName → default) so the gateway row and the local row agree on it.
+        const deviceName = name ?? active.name ?? 'New device';
+        // Gateway row FIRST. If this throws, NOTHING local changed — the pending pairing is still alive.
+        await deps.postPairConfirm({ gatewayUrl, daemonToken }, {
+            deviceId: active.deviceId,
+            devicePubkey: toBase64Url(active.devicePublicKey),
+            name: deviceName,
+            boundJti: active.boundJti,
+        });
+        // Trust-root local write happens ONLY now (gateway row exists → the phone's later /pair/session
+        // finds it, no 403 race). confirmPairing consumes the pending.
+        const record = deps.pairing.confirmPairing(pairingId, name === undefined ? undefined : { name });
+        if (!record)
+            return null; // vanished in the tiny window since the POST (expired) — nothing to relay
+        deps.send({ t: 'confirmed', deviceId: record.id });
+        active = null;
+        pendingBoundJti = null;
+        return record;
+    };
+    return { onPeerOnline, onPairingFrame, confirm };
+};

package/dist/src/server/remote-pairing.d.ts

@@ -0,0 +1,58 @@
+import { type DeviceKeyPair } from '../shared/remote-crypto.js';
+import type { RemoteAuditStore } from './remote-audit-store.js';
+import type { RemoteDeviceRecord, RemoteDeviceStore } from './remote-device-store.js';
+export type PairingState = 'awaiting_handshake' | 'awaiting_confirm' | 'confirmed' | 'rejected' | 'expired';
+export declare const PAIRING_TTL_MS: number;
+export type PairingRejectReason = 'pairing_expired' | 'pairing_replay' | 'pairing_unknown' | 'pairing_bad_input' | 'pairing_confirm_forbidden';
+export interface PairingTicket {
+    pairingId: string;
+    qr: string;
+    code: string;
+    expiresAt: number;
+}
+export interface PendingPairingView {
+    pairingId: string;
+    deviceName: string | null;
+    sas: string;
+    expiresAt: number;
+}
+export interface HandshakeReply {
+    daemonPublicKey: Uint8Array;
+    daemonId: string;
+    deviceId: string;
+    protocolVersion: number;
+}
+export interface DevicePairingHello {
+    pairingId: string;
+    devicePublicKey: Uint8Array;
+    sessionSalt: Uint8Array;
+    proposedName?: string;
+}
+export interface RemotePairingDeps {
+    deviceStore: RemoteDeviceStore;
+    audit: RemoteAuditStore;
+    getGatewayUrl: () => string | null;
+    getDaemonId: () => string | null;
+    now?: () => number;
+    ttlMs?: number;
+    newDaemonKeyPair?: () => DeviceKeyPair;
+    randomPairingSecret?: () => Uint8Array;
+    randomPairingCode?: () => string;
+    newId?: () => string;
+    setTimer?: (fn: () => void, ms: number) => NodeJS.Timeout;
+    clearTimer?: (h: NodeJS.Timeout) => void;
+}
+export interface RemotePairing {
+    beginPairing(): PairingTicket;
+    submitDeviceHello(hello: DevicePairingHello): PendingPairingView | null;
+    getHandshakeReply(pairingId: string): HandshakeReply | null;
+    confirmPairing(pairingId: string, opts?: {
+        name?: string;
+    }): RemoteDeviceRecord | null;
+    rejectPairing(pairingId: string, reason?: string): void;
+    getPending(pairingId: string): PendingPairingView | null;
+    listPending(): PendingPairingView[];
+    findAwaitingHandshake(): string | null;
+    dispose(): void;
+}
+export declare const createRemotePairing: (deps: RemotePairingDeps) => RemotePairing;

package/dist/src/server/remote-pairing.js

@@ -0,0 +1,237 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { randomBytes } from '@noble/ciphers/utils.js';
+import { deriveDaemonSession, encodePairingPayload, generateDeviceKeyPair, PAIRING_SECRET_LEN, REMOTE_CRYPTO_VERSION, SESSION_SALT_LEN, toBase64Url, X25519_KEY_LEN, } from '../shared/remote-crypto.js';
+import { formatPairingCode, generatePairingCode, normalizePairingCode, PAIRING_CODE_SECRET_CONTEXT, } from '../shared/remote-pairing-code.js';
+// Short TTL: a leaked pairing code is useless within five minutes (invariant 2), while real
+// phone/OAuth/manual-entry paths have enough time to complete without racing the clock.
+export const PAIRING_TTL_MS = 5 * 60_000;
+const defaultName = () => 'New device';
+const pairingSecretFromCode = (code) => {
+    const normalized = normalizePairingCode(code);
+    if (!normalized)
+        throw new RangeError('invalid pairing code');
+    return new Uint8Array(createHash('sha256').update(PAIRING_CODE_SECRET_CONTEXT).update(normalized).digest());
+};
+const toView = (p) => ({
+    pairingId: p.pairingId,
+    deviceName: p.proposedName,
+    sas: p.sas ?? '',
+    expiresAt: p.expiresAt,
+});
+export const createRemotePairing = (deps) => {
+    const now = deps.now ?? Date.now;
+    const ttlMs = deps.ttlMs ?? PAIRING_TTL_MS;
+    const newDaemonKeyPair = deps.newDaemonKeyPair ?? generateDeviceKeyPair;
+    const randomPairingSecret = deps.randomPairingSecret;
+    const randomPairingCode = deps.randomPairingCode ?? (() => generatePairingCode((length) => randomBytes(length)));
+    const newId = deps.newId ?? randomUUID;
+    const setTimer = deps.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+    const clearTimer = deps.clearTimer ?? ((h) => clearTimeout(h));
+    const pending = new Map();
+    // Zero the in-memory secrets the moment a pairing leaves a pre-terminal state. The key bytes are
+    // owned by us (never aliased into the store except via a copy on insert), so wiping them here is
+    // belt-and-suspenders against a heap dump.
+    const wipe = (p) => {
+        p.pairingSecret.fill(0);
+        p.daemonKeyPair.secretKey.fill(0);
+        if (p.sessionKeys) {
+            p.sessionKeys.d2p.fill(0);
+            p.sessionKeys.p2d.fill(0);
+        }
+        if (p.timer !== null) {
+            clearTimer(p.timer);
+            p.timer = null;
+        }
+    };
+    const auditReject = (reason, deviceId = null) => {
+        deps.audit.enqueue({ action: 'reject', result: 'rejected', rejectReason: reason, deviceId });
+    };
+    // Drop a pending pairing, wipe its secrets, mark terminal. Used by reject + expire + confirm.
+    const discard = (pairingId, state) => {
+        const p = pending.get(pairingId);
+        if (!p)
+            return null;
+        p.state = state;
+        wipe(p);
+        pending.delete(pairingId);
+        return p;
+    };
+    const expire = (pairingId) => {
+        const p = pending.get(pairingId);
+        if (!p)
+            return;
+        discard(pairingId, 'expired');
+        auditReject('pairing_expired', p.deviceId);
+    };
+    // Lazy expiry on every access: TTL is enforced even if the timer never fired (and unit tests never
+    // rely on a real setTimeout). A pairing whose deadline passed is treated as gone.
+    const sweep = () => {
+        const t = now();
+        for (const [id, p] of [...pending]) {
+            if (t >= p.expiresAt)
+                expire(id);
+        }
+    };
+    return {
+        beginPairing() {
+            const gatewayUrl = deps.getGatewayUrl();
+            const daemonId = deps.getDaemonId();
+            if (!gatewayUrl || !daemonId) {
+                throw new Error('remote not logged in: cannot start pairing');
+            }
+            const code = randomPairingCode();
+            const pairingSecret = randomPairingSecret?.() ?? pairingSecretFromCode(code);
+            if (pairingSecret.length !== PAIRING_SECRET_LEN) {
+                throw new RangeError(`pairing secret must be ${PAIRING_SECRET_LEN} bytes`);
+            }
+            const daemonKeyPair = newDaemonKeyPair();
+            const pairingId = newId();
+            const deviceId = newId();
+            const expiresAt = now() + ttlMs;
+            const entry = {
+                pairingId,
+                deviceId,
+                state: 'awaiting_handshake',
+                expiresAt,
+                pairingSecret,
+                daemonKeyPair,
+                sessionKeys: null,
+                devicePublicKey: null,
+                sas: null,
+                proposedName: null,
+                timer: null,
+            };
+            entry.timer = setTimer(() => expire(pairingId), ttlMs);
+            pending.set(pairingId, entry);
+            const qr = encodePairingPayload({
+                v: REMOTE_CRYPTO_VERSION,
+                gatewayUrl,
+                daemonId,
+                pairingSecret: toBase64Url(pairingSecret),
+            });
+            return { pairingId, qr, code: formatPairingCode(code), expiresAt };
+        },
+        submitDeviceHello(hello) {
+            sweep();
+            const p = pending.get(hello.pairingId);
+            if (!p) {
+                // Unknown OR already consumed (a replay deletes/advances the entry).
+                auditReject('pairing_unknown');
+                return null;
+            }
+            if (p.state !== 'awaiting_handshake') {
+                // One-time: a second hello on a token that already produced a pending is a replay.
+                auditReject('pairing_replay', p.deviceId);
+                return null;
+            }
+            if (now() >= p.expiresAt) {
+                expire(hello.pairingId);
+                return null;
+            }
+            if (hello.devicePublicKey.length !== X25519_KEY_LEN ||
+                hello.sessionSalt.length !== SESSION_SALT_LEN) {
+                discard(hello.pairingId, 'rejected');
+                auditReject('pairing_bad_input', p.deviceId);
+                return null;
+            }
+            const daemonId = deps.getDaemonId();
+            if (!daemonId) {
+                // Logged out between begin and hello — treat as unusable, drop the pairing.
+                discard(hello.pairingId, 'rejected');
+                auditReject('pairing_unknown', p.deviceId);
+                return null;
+            }
+            const ids = {
+                daemonId,
+                deviceId: p.deviceId,
+                protocolVersion: REMOTE_CRYPTO_VERSION,
+            };
+            const keys = deriveDaemonSession({
+                daemonSecretKey: p.daemonKeyPair.secretKey,
+                devicePublicKey: hello.devicePublicKey,
+                daemonPublicKey: p.daemonKeyPair.publicKey,
+                pairingSecret: p.pairingSecret,
+                sessionSalt: hello.sessionSalt,
+                ids,
+            });
+            p.sessionKeys = { d2p: keys.d2p, p2d: keys.p2d };
+            p.sas = keys.sas;
+            p.devicePublicKey = hello.devicePublicKey;
+            p.proposedName = hello.proposedName ?? null;
+            p.state = 'awaiting_confirm';
+            // Still NOT persisted, NOT in the provider — a relay attempt now gets provider.get === null.
+            return toView(p);
+        },
+        getHandshakeReply(pairingId) {
+            sweep();
+            const p = pending.get(pairingId);
+            if (!p || p.state !== 'awaiting_confirm')
+                return null;
+            const daemonId = deps.getDaemonId();
+            if (!daemonId)
+                return null;
+            // daemonPublicKey is PUBLIC — fine to emit so the phone can run deriveDeviceSession.
+            return {
+                daemonPublicKey: p.daemonKeyPair.publicKey,
+                daemonId,
+                deviceId: p.deviceId,
+                protocolVersion: REMOTE_CRYPTO_VERSION,
+            };
+        },
+        // THE trust root. The route layer guarantees this only runs for a local desktop request.
+        confirmPairing(pairingId, opts) {
+            sweep();
+            const p = pending.get(pairingId);
+            if (!p || p.state !== 'awaiting_confirm' || !p.sessionKeys || !p.devicePublicKey) {
+                return null;
+            }
+            const rec = deps.deviceStore.insert({
+                id: p.deviceId,
+                name: opts?.name ?? p.proposedName ?? defaultName(),
+                keys: { d2p: p.sessionKeys.d2p, p2d: p.sessionKeys.p2d },
+                devicePublicKey: p.devicePublicKey,
+            });
+            deps.audit.enqueue({ action: 'session_open', deviceId: rec.id, result: 'ok' });
+            // The store INSERT copied the key bytes via toBase64Url, so wiping our in-memory copy is safe.
+            discard(pairingId, 'confirmed');
+            return rec;
+        },
+        rejectPairing(pairingId, reason) {
+            sweep();
+            const p = pending.get(pairingId);
+            if (!p)
+                return;
+            discard(pairingId, 'rejected');
+            auditReject(reason ?? 'pairing_replay', p.deviceId);
+        },
+        getPending(pairingId) {
+            sweep();
+            const p = pending.get(pairingId);
+            if (!p || p.state !== 'awaiting_confirm')
+                return null;
+            return toView(p);
+        },
+        listPending() {
+            sweep();
+            return [...pending.values()].filter((p) => p.state === 'awaiting_confirm').map(toView);
+        },
+        findAwaitingHandshake() {
+            sweep();
+            // At most one in practice (D1). If two ever coexist, take the freshest (latest deadline) so a
+            // re-minted token wins over a stale one the user abandoned.
+            let best = null;
+            for (const p of pending.values()) {
+                if (p.state !== 'awaiting_handshake')
+                    continue;
+                if (!best || p.expiresAt > best.expiresAt)
+                    best = p;
+            }
+            return best?.pairingId ?? null;
+        },
+        dispose() {
+            for (const id of [...pending.keys()]) {
+                discard(id, 'rejected');
+            }
+        },
+    };
+};