@oxyhq/core 12.6.0 → 12.7.0

package/src/mixins/OxyServices.deviceTransfer.ts

@@ -0,0 +1,397 @@
+/**
+ * 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 { ec as EC } from 'elliptic';
+import { bytesToHex, hexToBytes, utf8ToBytes, bytesToUtf8 } from '@noble/hashes/utils';
+import type { OxyServicesBase } from '../OxyServices.base';
+import type {
+  DeviceTransferInfoResponse,
+  DeviceTransferInitResponse,
+  DeviceTransferApproveResponse,
+  DeviceTransferDenyResponse,
+} from '@oxyhq/contracts';
+import { deriveSharedSecret } from '../crypto/ecdh';
+import { hkdfSha256 } from '../crypto/kdf';
+import { encryptAead, decryptAead } from '../crypto/aead';
+import { KeyManager } from '../crypto/keyManager';
+import { SignatureService } from '../crypto/signatureService';
+import { getSocketIO } from '../session/socketLoader';
+import type { MinimalSocket } from '../session/socketLoader';
+import { logger } from '../logger';
+
+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<object, Map<string, string>>();
+
+function getEphemeralKeys(instance: object): Map<string, string> {
+  let keys = ephemeralKeyStore.get(instance);
+  if (!keys) {
+    keys = new Map<string, string>();
+    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';
+
+/** Result of {@link OxyServicesDeviceTransferMixin.initDeviceTransfer}. */
+export interface InitDeviceTransferResult {
+  /** 128-bit single-use handle to render in the QR (also the HKDF salt). */
+  pairingId: string;
+  /** ISO-8601 expiry (3 minutes). */
+  expiresAt: string;
+  /** The new device's ephemeral public key registered with the relay. */
+  newEphemeralPublicKey: string;
+}
+
+/** Terminal outcome delivered to {@link subscribeDeviceTransfer}'s callback. */
+export type DeviceTransferOutcome =
+  | { status: 'approved'; publicKey: string }
+  | { status: 'denied' }
+  | { status: 'expired' };
+
+/**
+ * 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: Uint8Array, pairingId: string): Uint8Array {
+  return hkdfSha256(
+    sharedSecret,
+    utf8ToBytes(pairingId),
+    utf8ToBytes(DEVICE_TRANSFER_HKDF_INFO),
+    32,
+  );
+}
+
+export function OxyServicesDeviceTransferMixin<T extends typeof OxyServicesBase>(Base: T) {
+  return class extends Base {
+    constructor(...args: any[]) {
+      super(...(args as [any]));
+    }
+
+    /**
+     * 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?: string): Promise<InitDeviceTransferResult> {
+      try {
+        const ephKeyPair = ecCurve.genKeyPair();
+        const ephPrivateKey = ephKeyPair.getPrivate('hex');
+        const ephPublicKey = ephKeyPair.getPublic('hex');
+
+        const res = await this.makeRequest<DeviceTransferInitResponse>(
+          '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: string): Promise<DeviceTransferInfoResponse> {
+      try {
+        return await this.makeRequest<DeviceTransferInfoResponse>(
+          '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: string): Promise<DeviceTransferApproveResponse> {
+      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<DeviceTransferApproveResponse>(
+          '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: string): Promise<DeviceTransferDenyResponse> {
+      try {
+        return await this.makeRequest<DeviceTransferDenyResponse>(
+          '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: string,
+      onOutcome: (outcome: DeviceTransferOutcome) => void,
+    ): () => void {
+      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: MinimalSocket | null = null;
+      let pollTimer: ReturnType<typeof setInterval> | null = null;
+
+      const cleanup = (): void => {
+        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: DeviceTransferOutcome): void => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        onOutcome(outcome);
+      };
+
+      // Re-check authoritative status; on `approved`, decrypt + import.
+      const check = async (): Promise<void> => {
+        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)) as {
+              privateKey: string;
+              publicKey: string;
+            };
+            // 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 = (): void => {
+            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 as { unref?: () => void }).unref?.();
+
+      // Immediate first check — the transfer may already be approved/denied.
+      void check();
+
+      return cleanup;
+    }
+  };
+}

package/src/mixins/__tests__/OxyServices.deviceTransfer.test.ts

@@ -0,0 +1,270 @@
+/**
+ * Device-to-device identity transfer mixin tests (b3 Feature 2 — "add a device").
+ *
+ * Exercises the E2E crypto path THROUGH the mixins with two independent
+ * OxyServices instances (old device + new device) wired to a shared in-memory
+ * "relay" that never sees a decryption key:
+ *   - ECDH symmetry: the old device seals with `ECDH(oldEphPriv, newEphPub)` and
+ *     the new device opens with `ECDH(newEphPriv, oldEphPub)` — same transfer key.
+ *   - full round-trip: the private key the old device holds is recovered and
+ *     imported byte-for-byte on the new device.
+ *   - tamper: a flipped ciphertext byte fails authentication (never imports).
+ *
+ * The socket is forced OFF (getSocketIO → null) so the deterministic poll path
+ * drives the flow; KeyManager + SignatureService.sign are stubbed (the identity
+ * key material and the approval signature are not the unit under test here — the
+ * server-side signature verification is covered in the api service tests).
+ */
+
+jest.mock('../../session/socketLoader', () => ({
+  getSocketIO: jest.fn(async () => null),
+}));
+
+import { ec as EC } from 'elliptic';
+import { OxyServices } from '../../OxyServices';
+import { KeyManager } from '../../crypto/keyManager';
+import { SignatureService } from '../../crypto/signatureService';
+import { deriveSharedSecret } from '../../crypto/ecdh';
+import { hkdfSha256 } from '../../crypto/kdf';
+import { encryptAead, decryptAead } from '../../crypto/aead';
+import { bytesToHex, hexToBytes, utf8ToBytes, bytesToUtf8 } from '@noble/hashes/utils';
+import type { DeviceTransferInfoResponse } from '@oxyhq/contracts';
+
+const ec = new EC('secp256k1');
+
+/** A shared in-memory relay: a single pairing row, mirroring the API's shape. */
+interface RelayState {
+  pairingId: string;
+  newDeviceEphemeralPublicKey: string;
+  newDeviceLabel: string | null;
+  status: 'pending' | 'approved' | 'denied' | 'expired';
+  expiresAt: string;
+  oldDeviceEphemeralPublicKey: string | null;
+  ciphertext: string | null;
+  nonce: string | null;
+}
+
+function makeRelay() {
+  const state: { row: RelayState | null } = { row: null };
+  const infoDto = (): DeviceTransferInfoResponse => {
+    const row = state.row!;
+    const approved = row.status === 'approved';
+    return {
+      pairingId: row.pairingId,
+      newDeviceEphemeralPublicKey: row.newDeviceEphemeralPublicKey,
+      newDeviceLabel: row.newDeviceLabel,
+      status: row.status,
+      expiresAt: row.expiresAt,
+      oldDeviceEphemeralPublicKey: approved ? row.oldDeviceEphemeralPublicKey : null,
+      ciphertext: approved ? row.ciphertext : null,
+      nonce: approved ? row.nonce : null,
+    };
+  };
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const handle = (method: string, url: string, data?: any): Promise<unknown> => {
+    if (method === 'POST' && url === '/identity/device-transfer/init') {
+      state.row = {
+        pairingId: 'a'.repeat(32),
+        newDeviceEphemeralPublicKey: data.newEphPub,
+        newDeviceLabel: data.newDeviceLabel ?? null,
+        status: 'pending',
+        expiresAt: new Date(Date.now() + 180_000).toISOString(),
+        oldDeviceEphemeralPublicKey: null,
+        ciphertext: null,
+        nonce: null,
+      };
+      return Promise.resolve({ pairingId: state.row.pairingId, expiresAt: state.row.expiresAt });
+    }
+    if (method === 'GET' && url.startsWith('/identity/device-transfer/')) {
+      return Promise.resolve(infoDto());
+    }
+    if (method === 'POST' && url.endsWith('/approve')) {
+      state.row!.oldDeviceEphemeralPublicKey = data.oldEphPub;
+      state.row!.ciphertext = data.ciphertext;
+      state.row!.nonce = data.nonce;
+      state.row!.status = 'approved';
+      return Promise.resolve({ success: true, pairingId: state.row!.pairingId, status: 'approved' });
+    }
+    if (method === 'POST' && url.endsWith('/deny')) {
+      state.row!.status = 'denied';
+      return Promise.resolve({ success: true, pairingId: state.row!.pairingId, status: 'denied' });
+    }
+    return Promise.reject(new Error(`unexpected request ${method} ${url}`));
+  };
+  return { state, handle };
+}
+
+describe('OxyServices.deviceTransfer', () => {
+  let identityPriv: string;
+  let identityPub: string;
+  let importedPrivateKey: string | null;
+
+  beforeEach(() => {
+    const idKey = ec.genKeyPair();
+    identityPriv = idKey.getPrivate('hex');
+    identityPub = idKey.getPublic('hex');
+    importedPrivateKey = null;
+
+    // Old device HOLDS the identity; new device IMPORTS it. One KeyManager is
+    // shared, but the two roles call disjoint methods (get* vs import).
+    jest.spyOn(KeyManager, 'getPrivateKey').mockResolvedValue(identityPriv);
+    jest.spyOn(KeyManager, 'getPublicKey').mockResolvedValue(identityPub);
+    jest.spyOn(KeyManager, 'importKeyPair').mockImplementation(async (priv: string) => {
+      importedPrivateKey = priv;
+      return ec.keyFromPrivate(priv, 'hex').getPublic('hex');
+    });
+    // The server (api service test) verifies the signature; here it is opaque.
+    jest.spyOn(SignatureService, 'sign').mockResolvedValue('sig-hex');
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('clones the identity end-to-end (ECDH symmetry + full round-trip via the mixins)', async () => {
+    const relay = makeRelay();
+    const newDevice = new OxyServices({ baseURL: 'http://relay.invalid' });
+    const oldDevice = new OxyServices({ baseURL: 'http://relay.invalid' });
+    jest.spyOn(newDevice, 'makeRequest').mockImplementation(relay.handle as never);
+    jest.spyOn(oldDevice, 'makeRequest').mockImplementation(relay.handle as never);
+
+    // 1. New device registers a pairing (generates + stores its ephemeral key).
+    const init = await newDevice.initDeviceTransfer('New iPhone');
+    expect(init.pairingId).toHaveLength(32);
+    expect(relay.state.row?.newDeviceEphemeralPublicKey).toBe(init.newEphemeralPublicKey);
+
+    // 2. Old device resolves the QR handle and approves (seals the identity key).
+    const approveResult = await oldDevice.approveDeviceTransfer(init.pairingId);
+    expect(approveResult).toEqual({ success: true, pairingId: init.pairingId, status: 'approved' });
+    // The relay stored ONLY ephemeral pubkeys + opaque ciphertext — never the key.
+    expect(relay.state.row?.ciphertext).toBeTruthy();
+    expect(relay.state.row?.ciphertext).not.toContain(identityPriv);
+
+    // 3. New device awaits approval, decrypts, and imports the SAME private key.
+    const outcome = await new Promise<{ status: string; publicKey?: string }>((resolve) => {
+      newDevice.subscribeDeviceTransfer(init.pairingId, resolve);
+    });
+
+    expect(outcome).toEqual({ status: 'approved', publicKey: identityPub });
+    // The recovered private key is byte-for-byte the old device's identity key.
+    expect(importedPrivateKey).toBe(identityPriv);
+    // Imported WITHOUT overwrite — a fresh device must never clobber an identity.
+    expect(KeyManager.importKeyPair).toHaveBeenCalledWith(identityPriv, { overwrite: false });
+  });
+
+  it('reports a denied transfer to the subscriber without importing', async () => {
+    const relay = makeRelay();
+    const newDevice = new OxyServices({ baseURL: 'http://relay.invalid' });
+    jest.spyOn(newDevice, 'makeRequest').mockImplementation(relay.handle as never);
+
+    await newDevice.initDeviceTransfer();
+    relay.state.row!.status = 'denied';
+
+    const outcome = await new Promise<{ status: string }>((resolve) => {
+      newDevice.subscribeDeviceTransfer(relay.state.row!.pairingId, resolve);
+    });
+
+    expect(outcome).toEqual({ status: 'denied' });
+    expect(KeyManager.importKeyPair).not.toHaveBeenCalled();
+  });
+
+  it('throws if subscribing to a pairing this instance never initiated', () => {
+    const newDevice = new OxyServices({ baseURL: 'http://relay.invalid' });
+    expect(() => newDevice.subscribeDeviceTransfer('unknown-pair', () => {})).toThrow(
+      /initDeviceTransfer first/i,
+    );
+  });
+
+  it('refuses to approve a non-pending pairing', async () => {
+    const relay = makeRelay();
+    const newDevice = new OxyServices({ baseURL: 'http://relay.invalid' });
+    const oldDevice = new OxyServices({ baseURL: 'http://relay.invalid' });
+    jest.spyOn(newDevice, 'makeRequest').mockImplementation(relay.handle as never);
+    jest.spyOn(oldDevice, 'makeRequest').mockImplementation(relay.handle as never);
+
+    const init = await newDevice.initDeviceTransfer();
+    relay.state.row!.status = 'denied';
+
+    await expect(oldDevice.approveDeviceTransfer(init.pairingId)).rejects.toThrow(
+      /can no longer be approved/i,
+    );
+  });
+});
+
+/**
+ * The exact crypto derivation the mixin uses, pinned independently: two ephemeral
+ * pairs agree on a symmetric key, seal/open a JSON key blob, and any tampering
+ * with the ciphertext fails authentication.
+ */
+describe('device-transfer crypto derivation', () => {
+  const HKDF_INFO = 'oxy-device-transfer-v1';
+  const deriveTransferKey = (shared: Uint8Array, pairingId: string): Uint8Array =>
+    hkdfSha256(shared, utf8ToBytes(pairingId), utf8ToBytes(HKDF_INFO), 32);
+
+  it('is symmetric and round-trips the sealed identity key', () => {
+    const pairingId = 'b'.repeat(32);
+    const oldEph = ec.genKeyPair();
+    const newEph = ec.genKeyPair();
+
+    const sharedOld = deriveSharedSecret(oldEph.getPrivate('hex'), newEph.getPublic('hex'));
+    const sharedNew = deriveSharedSecret(newEph.getPrivate('hex'), oldEph.getPublic('hex'));
+    expect(bytesToHex(sharedOld)).toBe(bytesToHex(sharedNew));
+
+    const keyOld = deriveTransferKey(sharedOld, pairingId);
+    const keyNew = deriveTransferKey(sharedNew, pairingId);
+    expect(bytesToHex(keyOld)).toBe(bytesToHex(keyNew));
+
+    const identity = { privateKey: 'ff'.repeat(32), publicKey: '04' + 'ab'.repeat(64) };
+    const { nonce, ciphertext } = encryptAead(keyOld, utf8ToBytes(JSON.stringify(identity)));
+
+    const opened = JSON.parse(bytesToUtf8(decryptAead(keyNew, nonce, ciphertext)));
+    expect(opened).toEqual(identity);
+  });
+
+  it('fails authentication when the ciphertext is tampered', () => {
+    const pairingId = 'c'.repeat(32);
+    const oldEph = ec.genKeyPair();
+    const newEph = ec.genKeyPair();
+    const key = deriveTransferKey(
+      deriveSharedSecret(oldEph.getPrivate('hex'), newEph.getPublic('hex')),
+      pairingId,
+    );
+    const { nonce, ciphertext } = encryptAead(key, utf8ToBytes('{"privateKey":"deadbeef"}'));
+
+    const tampered = Uint8Array.from(ciphertext);
+    tampered[0] ^= 0x01; // flip one bit
+    const keyNew = deriveTransferKey(
+      deriveSharedSecret(newEph.getPrivate('hex'), oldEph.getPublic('hex')),
+      pairingId,
+    );
+    expect(() => decryptAead(keyNew, nonce, tampered)).toThrow();
+    // And a wrong pairingId (wrong HKDF salt) also fails — binds to the pairing.
+    const wrongSaltKey = deriveTransferKey(
+      deriveSharedSecret(newEph.getPrivate('hex'), oldEph.getPublic('hex')),
+      'd'.repeat(32),
+    );
+    expect(() => decryptAead(wrongSaltKey, nonce, ciphertext)).toThrow();
+  });
+
+  it('re-derives from hex the way the wire transports the material', () => {
+    const pairingId = 'e'.repeat(32);
+    const oldEph = ec.genKeyPair();
+    const newEph = ec.genKeyPair();
+    const keyOld = deriveTransferKey(
+      deriveSharedSecret(oldEph.getPrivate('hex'), newEph.getPublic('hex')),
+      pairingId,
+    );
+    const { nonce, ciphertext } = encryptAead(keyOld, utf8ToBytes('{"k":1}'));
+
+    // Wire form: hex strings (exactly what the mixin sends/receives).
+    const nonceHex = bytesToHex(nonce);
+    const ciphertextHex = bytesToHex(ciphertext);
+
+    const keyNew = deriveTransferKey(
+      deriveSharedSecret(newEph.getPrivate('hex'), oldEph.getPublic('hex')),
+      pairingId,
+    );
+    const opened = bytesToUtf8(decryptAead(keyNew, hexToBytes(nonceHex), hexToBytes(ciphertextHex)));
+    expect(opened).toBe('{"k":1}');
+  });
+});

package/src/mixins/index.ts

@@ -30,6 +30,7 @@ import { OxyServicesCivicMixin } from './OxyServices.civic';
 import { OxyServicesNodesMixin } from './OxyServices.nodes';
 import { OxyServicesLinksMixin } from './OxyServices.links';
 import { OxyServicesDeviceBootMixin } from './OxyServices.deviceBoot';
+import { OxyServicesDeviceTransferMixin } from './OxyServices.deviceTransfer';
 
 /**
  * Instance shape of every mixin in the pipeline, intersected. The runtime
@@ -64,6 +65,7 @@ type AllMixinInstances =
   & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesLinksMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesDeviceBootMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesDeviceTransferMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
 
 /**
@@ -138,6 +140,10 @@ const MIXIN_PIPELINE: MixinFunction[] = [
     // (`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,
 ];