@oxyhq/core 12.5.4 → 12.7.0

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

@@ -0,0 +1,317 @@
+/**
+ * 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 _cjs_elliptic from 'elliptic';
+const { ec: EC } = _cjs_elliptic;
+import { bytesToHex, hexToBytes, utf8ToBytes, bytesToUtf8 } from '@noble/hashes/utils';
+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';
+const ecCurve = new EC('secp256k1');
+/**
+ * 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 ephKeyPair = ecCurve.genKeyPair();
+                const ephPrivateKey = ephKeyPair.getPrivate('hex');
+                const ephPublicKey = ephKeyPair.getPublic('hex');
+                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 oldEphKeyPair = ecCurve.genKeyPair();
+                const oldEphPrivateKey = oldEphKeyPair.getPrivate('hex');
+                const oldEphPublicKey = oldEphKeyPair.getPublic('hex');
+                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;
+        }
+    };
+}

package/dist/esm/mixins/index.js

@@ -29,6 +29,7 @@ import { OxyServicesCivicMixin } from './OxyServices.civic.js';
 import { OxyServicesNodesMixin } from './OxyServices.nodes.js';
 import { OxyServicesLinksMixin } from './OxyServices.links.js';
 import { OxyServicesDeviceBootMixin } from './OxyServices.deviceBoot.js';
+import { OxyServicesDeviceTransferMixin } from './OxyServices.deviceTransfer.js';
 /**
  * Mixin pipeline - applied in order from first to last.
  *
@@ -82,6 +83,9 @@ const MIXIN_PIPELINE = [
     // Device-first token mint: the client half of the zero-cookie transport
     // (`mintFromDeviceSecret` → `POST /session/device/token`).
     OxyServicesDeviceBootMixin,
+    // Device-to-device identity transfer ("add a device"): E2E-encrypted key
+    // clone over a short-lived relay (b3 Feature 2).
+    OxyServicesDeviceTransferMixin,
     // Utility (last, can use all above)
     OxyServicesUtilityMixin,
 ];

package/dist/esm/session/SessionClient.js

@@ -1,5 +1,6 @@
 import { deviceSessionStateSchema, deviceSessionSyncSchema, safeParseContract, SESSION_ACCOUNTS_CHANGED_EVENT, sessionAccountsChangedEventSchema, } from '@oxyhq/contracts';
 import { logger } from '../logger/index.js';
+import { computeIdentityTag } from '../utils/cacheKey.js';
 import { getSocketIO } from './socketLoader.js';
 /**
  * Same-origin `BroadcastChannel` name for instant, network-free session-state
@@ -80,8 +81,25 @@ export class SessionClient {
             }
         }
     }
-    /** Validate + last-writer-wins by revision. Returns true if applied. */
-    applyState(raw, origin = 'push') {
+    /**
+     * Validate + last-writer-wins by revision. Returns true if applied.
+     *
+     * `activeToken` (sync path only) is the server-issued access token for
+     * `raw.activeAccountId`. When present and the state is applied, it is planted
+     * BEFORE any subscriber is notified so the bearer already belongs to the new
+     * active account — the local switch/bootstrap path then needs no redundant
+     * device-secret mint. Push-origin applies carry no token and rely on the
+     * mint-before-notify gate below.
+     *
+     * ORDERING INVARIANT: a subscriber must NEVER observe a newly-active account
+     * while the planted bearer still identifies the PREVIOUS one — otherwise a
+     * `useCurrentUser`-style refetch fires under the wrong account's token (the
+     * account-switch 404 race). So when a transport is available and the planted
+     * bearer does not already belong to `next.activeAccountId`, minting is awaited
+     * BEFORE `notify()`. This covers EVERY notify source (a switch push, a
+     * cross-device push, a cold mint), not just the initial "no bearer yet" case.
+     */
+    applyState(raw, origin = 'push', activeToken) {
         const next = safeParseContract(deviceSessionStateSchema, raw);
         if (!next) {
             logger.warn('[SessionClient] discarded invalid session state');
@@ -98,9 +116,26 @@ export class SessionClient {
             next.revision <= this.state.revision) {
             return false;
         }
+        const previousState = this.state;
         this.state = next;
+        // Plant the sync-supplied active token (it is for `next.activeAccountId`)
+        // now — before the notify below — so the bearer matches the new active
+        // account when subscribers observe it. Guarded on difference to avoid a
+        // redundant token-change notification on an unchanged token (bootstrap
+        // restate).
+        if (activeToken && next.activeAccountId !== null && activeToken !== this.host.getAccessToken()) {
+            this.host.setTokens(activeToken);
+        }
         const transport = this.options.transport;
-        const needsMintBeforeNotify = transport != null && next.accounts.length > 0 && !this.host.getAccessToken();
+        const activeAccountId = next.activeAccountId;
+        // Mint before notifying when the bearer does not already belong to the new
+        // active account: no bearer at all, an opaque bearer, OR a bearer for a
+        // DIFFERENT account. `computeIdentityTag` yields the token's `userId`/`id`
+        // for a real JWT (comparable to the account id) and a non-account sentinel
+        // otherwise, so a mismatch always resolves to "mint".
+        const needsMintBeforeNotify = transport != null &&
+            next.accounts.length > 0 &&
+            (activeAccountId === null || computeIdentityTag(this.host.getAccessToken()) !== activeAccountId);
         const finishApply = () => {
             this.notify();
             if (next.accounts.length === 0 && this.options.onUnauthenticated) {
@@ -114,8 +149,10 @@ export class SessionClient {
         };
         if (needsMintBeforeNotify) {
             void transport.ensureActiveToken(next).then(finishApply).catch((error) => {
-                logger.warn('[SessionClient] ensureActiveToken failed', { component: 'SessionClient' }, error);
-                finishApply();
+                logger.warn('[SessionClient] ensureActiveToken failed — reverting session state', { component: 'SessionClient' }, error);
+                // Do NOT notify under a mismatched bearer. Revert to the last applied
+                // state so subscribers keep observing the account whose token is planted.
+                this.state = previousState ?? null;
             });
         }
         else {
@@ -153,9 +190,21 @@ export class SessionClient {
         }
         // A `sync` is always the response to a direct REST call this client made
         // (bootstrap / switch / signOut / add) → a `request`-origin, authoritative
-        // verdict.
-        this.applyState(sync.state, 'request');
-        if (sync.activeToken && this.state && sync.state.activeAccountId === this.state.activeAccountId) {
+        // verdict. Hand the active token to `applyState`: in the applied path it is
+        // planted BEFORE notify (bearer matches the new active account when
+        // subscribers observe it, and no redundant device-secret mint is triggered).
+        const applied = this.applyState(sync.state, 'request', sync.activeToken?.accessToken);
+        // Equal-revision restate (this revision was already applied by a preceding
+        // socket push): `applyState` no-ops without planting, but the token still
+        // needs planting. Guard on the sync's active account STILL being the current
+        // active account so a stale response cannot adopt a token for an account a
+        // newer state already switched away from.
+        if (!applied &&
+            sync.activeToken &&
+            this.state &&
+            sync.state.activeAccountId !== null &&
+            sync.state.activeAccountId === this.state.activeAccountId &&
+            sync.activeToken.accessToken !== this.host.getAccessToken()) {
             this.host.setTokens(sync.activeToken.accessToken);
         }
     }

package/dist/esm/utils/redactUrl.js

@@ -0,0 +1,26 @@
+/**
+ * URL redaction for logging.
+ *
+ * Asset URLs the API hands back for private assets carry a scoped, short-lived
+ * media token (`mt=…`) in their query string. That token is a bearer credential
+ * for the underlying object, so it must never land in a log line, breadcrumb,
+ * or metric — a captured log would otherwise grant read access until the token
+ * expires. Query strings on API URLs can also carry other sensitive params, so
+ * we redact the whole query rather than allow-listing one key.
+ *
+ * `redactUrlQuery` returns the URL's path portion with a `?<redacted>` marker
+ * when a query string is present, and the input unchanged otherwise. It is
+ * defensive: any input that does not parse as a URL is passed through as-is,
+ * except that a bare `?query` tail is still stripped so a relative path with a
+ * query never leaks.
+ */
+export function redactUrlQuery(url) {
+    if (typeof url !== 'string' || url.length === 0) {
+        return url;
+    }
+    const queryIndex = url.indexOf('?');
+    if (queryIndex === -1) {
+        return url;
+    }
+    return `${url.slice(0, queryIndex)}?<redacted>`;
+}