@oxy.so/core 1.0.0

package/dist/esm/mixins/OxyServices.connectedApps.js

@@ -0,0 +1,75 @@
+import { CACHE_TIMES } from './mixinHelpers.js';
+export function OxyServicesConnectedAppsMixin(Base) {
+    return class extends Base {
+        constructor(...args) {
+            super(...args);
+        }
+        /**
+         * Resolve an OAuth client identifier to the owning application's PUBLIC
+         * identity. No authentication required — the API returns only sanitized,
+         * display-safe metadata ({@link PublicApplication}). Use this to render the
+         * requesting application's name/icon in consent, authorize, and device-flow
+         * approval UIs before any session exists.
+         *
+         * @param clientId - The OAuth `client_id` (an active credential's public
+         *   key). URL-encoded before being placed in the path.
+         */
+        async getPublicApplication(clientId) {
+            try {
+                const res = await this.makeRequest('GET', `/auth/oauth/client/${encodeURIComponent(clientId)}`, undefined, {
+                    cache: true,
+                    cacheTTL: CACHE_TIMES.MEDIUM,
+                    // Public client metadata (pre-session consent UI) — skip the bearer preflight.
+                    skipAuth: true,
+                });
+                return res.application;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * List the OAuth-authorized applications the current user has connected —
+         * the third-party apps the user granted access to via the consent flow.
+         * Each entry is a {@link ConnectedApp} carrying the application's display
+         * identity, the granted scopes, and when the grant was first made and last
+         * exercised. Requires an authenticated session.
+         *
+         * Backed by `GET /auth/grants`. The response is briefly cached
+         * (identity-scoped); {@link revokeAppGrant} busts that cache so a revoke is
+         * reflected on the next read.
+         */
+        async listConnectedApps() {
+            try {
+                return await this.makeRequest('GET', '/auth/grants', undefined, { cache: true, cacheTTL: CACHE_TIMES.SHORT });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Revoke the current user's grant for a connected application, identified by
+         * its application `_id` (a {@link ConnectedApp.applicationId}, NOT a
+         * credential/client id — keyed by application so the revocation survives
+         * credential rotation). After this the application can no longer act on the
+         * user's behalf until it is re-authorized.
+         *
+         * Backed by `DELETE /auth/grants/:applicationId`. On success the cached
+         * connected-apps list (`GET:/auth/grants`) is invalidated so the next
+         * {@link listConnectedApps} read reflects the removal.
+         *
+         * @param applicationId - The connected application's Mongo `_id`.
+         */
+        async revokeAppGrant(applicationId) {
+            try {
+                await this.makeRequest('DELETE', `/auth/grants/${applicationId}`, undefined, { cache: false });
+                // A revoke removes an entry from the user's connected-apps list; bust
+                // the cached `GET /auth/grants` so the next read re-fetches.
+                this.clearCacheEntry('GET:/auth/grants');
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+    };
+}

package/dist/esm/mixins/OxyServices.contacts.js

@@ -0,0 +1,47 @@
+/**
+ * Contact Discovery Mixin
+ *
+ * Privacy-preserving discovery of which address-book contacts are on Oxy.
+ *
+ * The client hashes emails and phones locally before calling the API.
+ * The server responds with only Oxy user IDs and the hashes that matched,
+ * so the consumer can map each match back to the local contact that
+ * produced it.
+ *
+ * Hashing rules (must match the server `utils/contactHash.ts` exactly):
+ *   - SHA-256, hex-encoded, lowercase
+ *   - Email: `value.trim().toLowerCase()` then digest
+ *   - Phone: trim → keep a single leading "+" → strip non-digits → prepend "+"
+ *     if missing → digest
+ *
+ * Mobile clients can compute these digests with `expo-crypto`'s
+ * `digestStringAsync(SHA256, value, { encoding: HEX })`. Web clients should
+ * use `SubtleCrypto.digest('SHA-256', ...)`.
+ */
+export function OxyServicesContactsMixin(Base) {
+    return class extends Base {
+        constructor(...args) {
+            super(...args);
+        }
+        /**
+         * Discover which of the caller's contacts are on Oxy.
+         *
+         * @param hashedEmails - SHA-256 hex digests of normalized emails.
+         * @param hashedPhones - SHA-256 hex digests of normalized phone numbers.
+         * @returns Matches mapping each hashed identifier to the Oxy user ID it
+         *   resolved to. Empty arrays are valid for either parameter, but at
+         *   least one must be non-empty.
+         *
+         * The server enforces a 200-hash cap per channel per request — callers
+         * should batch larger address books client-side.
+         */
+        async discoverContacts(hashedEmails, hashedPhones) {
+            try {
+                return await this.makeRequest('POST', '/contacts/discover', { hashedEmails, hashedPhones }, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+    };
+}

package/dist/esm/mixins/OxyServices.deviceBoot.js

@@ -0,0 +1,186 @@
+/**
+ * Device-first token mint mixin.
+ *
+ * The client half of the zero-cookie device transport: the single network call
+ * the cold boot (`sessionColdBoot`) and the unified re-mint handler (`refresh.ts`)
+ * make to turn a first-party `deviceId` + `deviceSecret` into a fresh access
+ * token. The response is validated against the `@oxy.so/contracts`
+ * `deviceTokenMintResponseSchema`, so producer (oxy-api) and consumer cannot
+ * drift — an unexpected shape throws here rather than silently corrupting the
+ * persisted store.
+ *
+ * This method carries NO persistence or token-planting side effects of its own;
+ * the cold boot / re-mint handler own persistence and `setTokens`, so the same
+ * primitive can be reused from either without double-planting.
+ *
+ * `provisionBackgroundCredential` is the mixin's second, adjacent call: it hands
+ * native background code (no JS runtime) its own non-rotating credential so that
+ * code never has to mint from — and therefore never rotates — the device secret
+ * JS depends on.
+ */
+import { deviceBackgroundCredentialResponseSchema, deviceTokenMintResponseSchema, safeParseContract, } from '@oxy.so/contracts';
+import { extractErrorStatus } from '../utils/errorUtils.js';
+/**
+ * The server's `401 account_not_on_device` for a PINNED mint: the requested
+ * `accountId` is not (or is no longer) a live account of this device session.
+ *
+ * Distinguished from every other mint 401 because the remedy is different: the
+ * device secret is FINE — it is the identity binding that went stale (the
+ * account was signed out on this device, or revoked). An identity-bound caller
+ * must re-establish its session from the local key rather than drop/clear the
+ * device credential.
+ */
+export class AccountNotOnDeviceError extends Error {
+    constructor(accountId, cause) {
+        super(`account_not_on_device: ${accountId} is not a live account of this device session`);
+        this.accountId = accountId;
+        this.cause = cause;
+        this.name = 'AccountNotOnDeviceError';
+        /** HTTP status of the originating response; mirrors the ApiError shape. */
+        this.status = 401;
+    }
+}
+/**
+ * Structural (never `instanceof`) read of a normalized mint error: the thrown
+ * value may be a plain ApiError-shaped object or come from another realm.
+ */
+function isAccountNotOnDevice(error) {
+    if (!error || typeof error !== 'object') {
+        return false;
+    }
+    const { status, message } = error;
+    if (status !== 401) {
+        return false;
+    }
+    return typeof message === 'string' && message.includes('account_not_on_device');
+}
+export function OxyServicesDeviceBootMixin(Base) {
+    return class extends Base {
+        /**
+         * Zero-cookie mint. Present the first-party `deviceId` + `deviceSecret` to
+         * `POST /session/device/token` — NO bearer, NO cookies: possession of the
+         * secret IS the device-ownership proof. Returns a fresh short access token
+         * for the device's active account plus `nextDeviceSecret` (on mint, the same
+         * proven secret echoed back — rotation happens on sign-in, not mint) and
+         * the projected device-session `state`.
+         *
+         * `skipAuth`: this call carries no bearer, so a 401 must surface DIRECTLY —
+         * never trigger `HttpService`'s 401→refresh→retry dance. The cold boot / re-
+         * mint handler read the 401 body (`invalid_device_secret` vs
+         * `no_active_session`) to decide whether to drop the secret and fall back or
+         * resolve signed-out.
+         *
+         * `retry: false`: the mint is a single logical attempt. The proactive
+         * token-refresh scheduler and the reactive 401 lane already own backoff and
+         * re-arm, so `HttpService`'s inner retry loop here would only multiply the
+         * mint's latency on a slow/black-hole network (3 retries × 5s timeout ≈ 20s
+         * per lane) with no correctness benefit — it is the dominant term in the cold
+         * boot's worst-case time-to-route. A transient failure surfaces once and the
+         * scheduler/401 path retries it later.
+         *
+         * `options.accountId` PINS the mint to one account of the device instead of
+         * whichever account is currently active. It exists for identity-bound
+         * clients (Commons), whose authenticated user is fixed by a local
+         * cryptographic key and must never follow an account switch made by another
+         * app on the same device. The server never mutates `activeAccountId` for a
+         * pinned mint — the returned `state` still reports the device's true active
+         * account — and rejects a non-member/dead account with
+         * `401 account_not_on_device`, surfaced here as {@link AccountNotOnDeviceError}.
+         *
+         * @throws {AccountNotOnDeviceError} when a pinned mint's account is not on the device.
+         * @throws if the response does not match {@link deviceTokenMintResponseSchema}.
+         */
+        async mintFromDeviceSecret(deviceId, deviceSecret, options) {
+            const accountId = options?.accountId;
+            try {
+                const res = await this.makeRequest('POST', '/session/device/token', { deviceId, deviceSecret, ...(accountId ? { accountId } : {}) }, 
+                // `bypassQueue`: this mint is the control-plane call the auth lane
+                // depends on — it must run even when every RequestQueue slot is parked
+                // awaiting it, or the whole client deadlocks. See RequestOptions.bypassQueue.
+                { cache: false, skipAuth: true, retry: false, bypassQueue: true });
+                const parsed = safeParseContract(deviceTokenMintResponseSchema, res);
+                if (!parsed) {
+                    throw new Error('session/device/token returned an unexpected response shape');
+                }
+                return parsed;
+            }
+            catch (error) {
+                const normalized = this.handleError(error);
+                if (accountId && isAccountNotOnDevice(normalized)) {
+                    throw new AccountNotOnDeviceError(accountId, normalized);
+                }
+                throw normalized;
+            }
+        }
+        /**
+         * Provision a NON-rotating background credential for the caller's account on
+         * this device — the credential native background code (an Android widget
+         * worker, which runs with no JS runtime) presents to mint its own access
+         * tokens without any JS involvement.
+         *
+         * It exists precisely so background code never touches the device secret:
+         * `POST /session/device/token` ROTATES that secret on every mint (the
+         * presented one stays valid only for a short grace), so a worker minting
+         * from it would become a second writer of the value JS depends on and could
+         * silently sign the user out. The background credential is a separate,
+         * non-rotating value minted server-side, so the two lanes never contend.
+         *
+         * Bearer required and NO body: the server derives both the `deviceId` and
+         * the account from the validated bearer. This is the only way a background
+         * credential comes into existence, so background code can EXTEND a session
+         * the user established in-app but can never bootstrap one from nothing.
+         *
+         * Unlike the mint above this is NOT a control-plane call — it runs while a
+         * session is already live — so it takes the normal authenticated path: no
+         * `skipAuth` (a 401 should go through the ordinary re-mint lane) and no
+         * `bypassQueue` (nothing in the auth lane is parked awaiting it).
+         *
+         * There is deliberately no JS counterpart that MINTS from the returned
+         * credential: the native side owns that call, and a symmetric-looking JS
+         * method would be dead code plus a second implementation of the failure
+         * rules. The asymmetry is the design.
+         *
+         * **Call this from NATIVE only.** There is no background worker on web to
+         * consume the credential, and handing a browser origin a long-lived
+         * non-rotating secret to persist is strictly weaker than the rotating device
+         * secret it already holds. The 404 degrade below is also native-shaped: a
+         * browser attaches `Origin`, which a server predating this route answers
+         * `403 BAD_ORIGIN` from its router-wide same-site guard rather than 404, so
+         * the quiet degrade would not fire there. A native client sends no `Origin`
+         * and gets the 404. Gate the caller by platform; do not widen the degrade to
+         * 403, which would also swallow a genuine origin misconfiguration.
+         *
+         * That paragraph is LOAD-BEARING, not belt-and-braces: the route sits above
+         * oxy-api's router-wide origin guard (deliberately, so a native client with
+         * no `Origin` is not rejected). oxy-api additionally refuses callers that
+         * carry browser context signals (`Origin` or `Sec-Fetch-Site`) with
+         * `403 browser_not_allowed` — native HTTP clients send neither. Gate the
+         * caller by platform on the client as well; do not widen the 404 degrade to
+         * 403, which would also swallow a genuine origin misconfiguration.
+         *
+         * @returns the provisioned credential, or `null` when the endpoint is absent
+         * (404). The API deploy leads the SDK release, so a client on a newer SDK
+         * than the server degrades to "no background session" quietly instead of
+         * surfacing an error. The status is read off the RAW rejection because
+         * `handleError` only preserves it for errors carrying `HttpService`'s
+         * annotations.
+         * @throws if the response does not match {@link deviceBackgroundCredentialResponseSchema}.
+         */
+        async provisionBackgroundCredential() {
+            try {
+                const res = await this.makeRequest('POST', '/session/device/background-credential', undefined, { cache: false });
+                const parsed = safeParseContract(deviceBackgroundCredentialResponseSchema, res);
+                if (!parsed) {
+                    throw new Error('session/device/background-credential returned an unexpected response shape');
+                }
+                return parsed;
+            }
+            catch (error) {
+                if (extractErrorStatus(error) === 404) {
+                    return null;
+                }
+                throw this.handleError(error);
+            }
+        }
+    };
+}

package/dist/esm/mixins/OxyServices.deviceTransfer.js

@@ -0,0 +1,311 @@
+/**
+ * Device-to-device Identity Transfer Mixin (b3 Feature 2 — "add a device")
+ *
+ * Clones an existing device's secp256k1 identity onto a fresh device over a
+ * short-lived, unauthenticated relay, WITHOUT the server ever holding a
+ * decryption key. Both devices end up holding the SAME private key.
+ *
+ * The two devices agree on a symmetric key via an ephemeral secp256k1 ECDH
+ * handshake (Phase-0 crypto): `deriveSharedSecret` → `hkdfSha256` → a per-pairing
+ * transfer key, used with `encryptAead`/`decryptAead` (XChaCha20-Poly1305) to
+ * seal `{ privateKey, publicKey }`. The relay carries only ephemeral public keys
+ * plus opaque ciphertext — a passive/at-rest-compromised backend cannot decrypt.
+ *
+ * Roles:
+ *  - NEW device (no identity): {@link initDeviceTransfer} (generate ephemeral
+ *    pair, register the pairing, render `pairingId` as a QR) then
+ *    {@link subscribeDeviceTransfer} (await approval over the `/device-pair`
+ *    socket with a poll fallback, decrypt, and import the key).
+ *  - OLD device (has identity): {@link getDeviceTransferInfo} (resolve the
+ *    scanned `pairingId` server-side — the QR is NOT self-contained) then
+ *    {@link approveDeviceTransfer} (biometric-gate in the UI, seal the key
+ *    material, and post it with a fresh signature over the CURRENT identity key).
+ *
+ * SECURITY: E2E against a passive relay only. Explicitly NOT hardened against an
+ * actively-malicious backend MITM'ing the ephemeral keys (same trust boundary as
+ * the existing QR sign-in; SAS compare deferred per owner decision). Approve
+ * requires BOTH a bearer token AND a fresh identity-key signature.
+ */
+import { bytesToHex, hexToBytes, utf8ToBytes, bytesToUtf8 } from '@noble/hashes/utils';
+import { generateSecp256k1KeyPair } from '@oxy.so/protocol/secp256k1';
+import { deriveSharedSecret } from '../crypto/ecdh.js';
+import { hkdfSha256 } from '../crypto/kdf.js';
+import { encryptAead, decryptAead } from '../crypto/aead.js';
+import { KeyManager } from '../crypto/keyManager.js';
+import { SignatureService } from '../crypto/signatureService.js';
+import { getSocketIO } from '../session/socketLoader.js';
+import { logger } from '../logger/index.js';
+/**
+ * Ephemeral private keys for pairings an instance INITIATED, keyed by pairingId,
+ * held per OxyServices instance. In-memory ONLY (never persisted — single-use),
+ * cleared once the transfer settles. A module-level WeakMap (rather than a class
+ * field) keeps it off the mixin's emitted `.d.ts` (avoids TS4094 on the exported
+ * anonymous class) and lets the GC drop it with the instance.
+ */
+const ephemeralKeyStore = new WeakMap();
+function getEphemeralKeys(instance) {
+    let keys = ephemeralKeyStore.get(instance);
+    if (!keys) {
+        keys = new Map();
+        ephemeralKeyStore.set(instance, keys);
+    }
+    return keys;
+}
+/** HKDF `info` binding — MUST match the server/other-device byte-for-byte. */
+const DEVICE_TRANSFER_HKDF_INFO = 'oxy-device-transfer-v1';
+/** Socket.IO namespace the API pushes device-pair approval events on. */
+const DEVICE_PAIR_NAMESPACE = '/device-pair';
+/** Fallback poll cadence — the socket delivers approval instantly; this covers
+ *  the case where the socket can't connect. */
+const DEVICE_TRANSFER_POLL_INTERVAL_MS = 2500;
+/** Action string signed on approve (mirrors `link_identity`'s scheme). */
+const DEVICE_TRANSFER_APPROVE_ACTION = 'approve_device_transfer';
+/**
+ * Derive the per-pairing symmetric transfer key from an ECDH shared secret.
+ * Identical on both devices: `HKDF(ECDH, salt=pairingId, info=v1)`.
+ */
+function deriveTransferKey(sharedSecret, pairingId) {
+    return hkdfSha256(sharedSecret, utf8ToBytes(pairingId), utf8ToBytes(DEVICE_TRANSFER_HKDF_INFO), 32);
+}
+export function OxyServicesDeviceTransferMixin(Base) {
+    return class extends Base {
+        constructor(...args) {
+            super(...args);
+        }
+        /**
+         * NEW device — begin an "add a device" transfer. Generates a single-use
+         * ephemeral secp256k1 pair, registers the pairing, and returns the
+         * `pairingId` to render as a QR. The ephemeral private key is held in memory
+         * (keyed by `pairingId`) for the subsequent {@link subscribeDeviceTransfer}.
+         *
+         * @param label - Optional human-readable label for this new device.
+         */
+        async initDeviceTransfer(label) {
+            try {
+                const { privateKey: ephPrivateKey, publicKey: ephPublicKey } = generateSecp256k1KeyPair();
+                const res = await this.makeRequest('POST', '/identity/device-transfer/init', { newEphPub: ephPublicKey, ...(label ? { newDeviceLabel: label } : {}) }, { cache: false });
+                getEphemeralKeys(this).set(res.pairingId, ephPrivateKey);
+                return {
+                    pairingId: res.pairingId,
+                    expiresAt: res.expiresAt,
+                    newEphemeralPublicKey: ephPublicKey,
+                };
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Resolve a pairing server-side (the QR carries only `pairingId`). The OLD
+         * device calls this after scanning to read the new device's ephemeral public
+         * key + label; the NEW device polls it to fetch the sealed material once
+         * approved. Public — no auth required.
+         */
+        async getDeviceTransferInfo(pairingId) {
+            try {
+                return await this.makeRequest('GET', `/identity/device-transfer/${encodeURIComponent(pairingId)}`, undefined, { cache: false, retry: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * OLD device — approve a scanned transfer. Reads the new device's ephemeral
+         * public key, derives the shared transfer key, AEAD-seals
+         * `{ privateKey, publicKey }`, and posts it PLUS a fresh signature over
+         * `{ action:'approve_device_transfer', pairingId, timestamp }` made with the
+         * CURRENT identity key (dual-proof alongside the bearer token).
+         *
+         * NATIVE-ONLY: requires a stored identity (throws otherwise). The UI must
+         * biometric-gate before calling this — a key clone leaves the device.
+         */
+        async approveDeviceTransfer(pairingId) {
+            try {
+                const info = await this.getDeviceTransferInfo(pairingId);
+                if (info.status !== 'pending') {
+                    throw new Error(`This transfer can no longer be approved (status: ${info.status}).`);
+                }
+                const privateKey = await KeyManager.getPrivateKey();
+                const publicKey = await KeyManager.getPublicKey();
+                if (!privateKey || !publicKey) {
+                    throw new Error('No identity found on this device. Create or import an identity first.');
+                }
+                // Ephemeral ECDH → per-pairing transfer key.
+                const { privateKey: oldEphPrivateKey, publicKey: oldEphPublicKey } = generateSecp256k1KeyPair();
+                const sharedSecret = deriveSharedSecret(oldEphPrivateKey, info.newDeviceEphemeralPublicKey);
+                const transferKey = deriveTransferKey(sharedSecret, pairingId);
+                // Seal the identity key material.
+                const plaintext = utf8ToBytes(JSON.stringify({ privateKey, publicKey }));
+                const { nonce, ciphertext } = encryptAead(transferKey, plaintext);
+                // Dual-proof: prove control of the CURRENT identity key (a bearer alone
+                // must not be able to exfiltrate the private key).
+                const timestamp = Date.now();
+                const message = JSON.stringify({
+                    action: DEVICE_TRANSFER_APPROVE_ACTION,
+                    pairingId,
+                    timestamp,
+                });
+                const signature = await SignatureService.sign(message);
+                return await this.makeRequest('POST', `/identity/device-transfer/${encodeURIComponent(pairingId)}/approve`, {
+                    oldEphPub: oldEphPublicKey,
+                    ciphertext: bytesToHex(ciphertext),
+                    nonce: bytesToHex(nonce),
+                    signature,
+                    timestamp,
+                }, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * OLD device — deny (cancel) a scanned transfer so the waiting new device
+         * stops. Public — no auth required.
+         */
+        async denyDeviceTransfer(pairingId) {
+            try {
+                return await this.makeRequest('POST', `/identity/device-transfer/${encodeURIComponent(pairingId)}/deny`, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * NEW device — await approval for a pairing started with
+         * {@link initDeviceTransfer}, then decrypt and import the transferred
+         * identity key. Primary path is an instant `device_pair_update` push over the
+         * `/device-pair` socket; a poll backstops a socket that can't connect.
+         *
+         * On `approved`: re-derives the shared transfer key from the old device's
+         * ephemeral public key, decrypts `{ privateKey, publicKey }`, imports it via
+         * `KeyManager.importKeyPair(privateKey, { overwrite: false })`, and invokes
+         * `onOutcome({ status:'approved', publicKey })`. The caller then runs the
+         * NORMAL challenge/verify sign-in — this method does not mint a session.
+         *
+         * @returns An unsubscribe function; call it to stop waiting (also called
+         *   automatically once the transfer settles).
+         */
+        subscribeDeviceTransfer(pairingId, onOutcome) {
+            const ephemeralKeys = getEphemeralKeys(this);
+            const ephPrivateKey = ephemeralKeys.get(pairingId);
+            if (!ephPrivateKey) {
+                throw new Error('No pending device transfer for this pairing id. Call initDeviceTransfer first.');
+            }
+            let settled = false;
+            let inFlight = false;
+            let socket = null;
+            let pollTimer = null;
+            const cleanup = () => {
+                if (pollTimer !== null) {
+                    clearInterval(pollTimer);
+                    pollTimer = null;
+                }
+                if (socket) {
+                    try {
+                        socket.off('device_pair_update');
+                        socket.off('connect');
+                        socket.disconnect();
+                    }
+                    catch (error) {
+                        logger.debug('[DeviceTransfer] socket close failed', { component: 'DeviceTransfer' }, error);
+                    }
+                    socket = null;
+                }
+                ephemeralKeys.delete(pairingId);
+            };
+            const finish = (outcome) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                onOutcome(outcome);
+            };
+            // Re-check authoritative status; on `approved`, decrypt + import.
+            const check = async () => {
+                if (settled || inFlight)
+                    return;
+                inFlight = true;
+                try {
+                    const info = await this.getDeviceTransferInfo(pairingId);
+                    if (settled)
+                        return;
+                    if (info.status === 'denied') {
+                        finish({ status: 'denied' });
+                        return;
+                    }
+                    if (info.status === 'expired') {
+                        finish({ status: 'expired' });
+                        return;
+                    }
+                    if (info.status === 'approved' &&
+                        info.oldDeviceEphemeralPublicKey &&
+                        info.ciphertext &&
+                        info.nonce) {
+                        const sharedSecret = deriveSharedSecret(ephPrivateKey, info.oldDeviceEphemeralPublicKey);
+                        const transferKey = deriveTransferKey(sharedSecret, pairingId);
+                        const plaintext = decryptAead(transferKey, hexToBytes(info.nonce), hexToBytes(info.ciphertext));
+                        const parsed = JSON.parse(bytesToUtf8(plaintext));
+                        // Import WITHOUT overwrite: a fresh device has no identity, and we
+                        // must never silently clobber an existing one.
+                        const importedPublicKey = await KeyManager.importKeyPair(parsed.privateKey, {
+                            overwrite: false,
+                        });
+                        finish({ status: 'approved', publicKey: importedPublicKey });
+                    }
+                }
+                catch (error) {
+                    // Transient (a poll tick that raced the approve write, a decrypt on a
+                    // half-written row) — keep waiting; the next tick/push retries.
+                    logger.debug('[DeviceTransfer] status check failed', { component: 'DeviceTransfer' }, error);
+                }
+                finally {
+                    inFlight = false;
+                }
+            };
+            // Primary: instant socket wake. Fall back to polling if unavailable.
+            void (async () => {
+                const io = await getSocketIO();
+                if (settled || !io)
+                    return;
+                try {
+                    const s = io(`${this.getBaseURL()}${DEVICE_PAIR_NAMESPACE}`, {
+                        transports: ['websocket'],
+                        autoConnect: true,
+                        reconnection: true,
+                        reconnectionAttempts: Number.POSITIVE_INFINITY,
+                        reconnectionDelay: 1000,
+                        reconnectionDelayMax: 10000,
+                    });
+                    const join = () => {
+                        try {
+                            s.emit('join', pairingId);
+                        }
+                        catch (error) {
+                            logger.debug('[DeviceTransfer] join failed', { component: 'DeviceTransfer' }, error);
+                        }
+                    };
+                    s.on('connect', join);
+                    if (s.connected)
+                        join();
+                    s.on('device_pair_update', () => {
+                        void check();
+                    });
+                    socket = s;
+                }
+                catch (error) {
+                    logger.debug('[DeviceTransfer] socket create failed (poll fallback)', { component: 'DeviceTransfer' }, error);
+                }
+            })();
+            // Fallback poll (also covers the already-approved-before-subscribe case via
+            // the immediate first tick below). unref so it never holds a Node event
+            // loop / test runner open.
+            pollTimer = setInterval(() => {
+                void check();
+            }, DEVICE_TRANSFER_POLL_INTERVAL_MS);
+            pollTimer.unref?.();
+            // Immediate first check — the transfer may already be approved/denied.
+            void check();
+            return cleanup;
+        }
+    };
+}