@oxyhq/core 12.6.0 → 12.8.0

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/__tests__/serviceAuth.test.ts

@@ -30,6 +30,7 @@ interface ServiceTokenClaims {
   scopes?: string[];
   aud?: string | string[];
   iss?: string;
+  environment?: string;
   exp?: number;
   iat?: number;
   [key: string]: unknown;
@@ -49,6 +50,7 @@ const signServiceToken = (claims: ServiceTokenClaims, secret: string): string =>
     aud: 'oxy-api',
     iss: 'oxy-auth',
     credentialId: 'cred-1',
+    environment: 'production',
     ...claims,
   };
   const headerB64 = b64url(JSON.stringify(header));
@@ -183,6 +185,7 @@ describe('C3: service-token acting-as enforcement', () => {
       appName: 'trusted-service',
       credentialId: 'cred-1',
       scopes: ['user:read'],
+      environment: 'production',
     });
   });
 
@@ -762,3 +765,65 @@ describe('requireScope() middleware', () => {
     expect(() => oxy.requireScope(undefined as unknown as string)).toThrow('requireScope');
   });
 });
+
+// ---------------------------------------------------------------------------
+// service-token environment claim (F2.0 task 1b) — test/live isolation.
+// ---------------------------------------------------------------------------
+
+describe('service-token environment claim (F2.0 task 1b)', () => {
+  let oxy: OxyServices;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+  });
+
+  it('populates req.serviceApp.environment from the token claim', async () => {
+    const token = signServiceToken(
+      { appId: 'app-1', appName: 'svc', environment: 'development' },
+      SERVICE_SECRET,
+    );
+    const req = makeReq({ headers: { authorization: `Bearer ${token}` } });
+    const res = makeRes();
+    const next = jest.fn();
+
+    const mw = oxy.auth({ jwtSecret: SERVICE_SECRET });
+    await mw(req as unknown as never, res as unknown as never, next as unknown as never);
+
+    expect(next).toHaveBeenCalledTimes(1);
+    expect(req.serviceApp).toMatchObject({ appId: 'app-1', environment: 'development' });
+  });
+
+  it('rejects a service token missing the environment claim (401)', async () => {
+    const token = signServiceToken(
+      { appId: 'app-1', appName: 'svc', environment: undefined },
+      SERVICE_SECRET,
+    );
+    const req = makeReq({ headers: { authorization: `Bearer ${token}` } });
+    const res = makeRes();
+    const next = jest.fn();
+
+    const mw = oxy.auth({ jwtSecret: SERVICE_SECRET });
+    await mw(req as unknown as never, res as unknown as never, next as unknown as never);
+
+    expect(next).not.toHaveBeenCalled();
+    expect(res.statusCode).toBe(401);
+    expect(res.body).toMatchObject({ code: 'INVALID_SERVICE_TOKEN' });
+  });
+
+  it('rejects a service token with an environment value outside the known set (401)', async () => {
+    const token = signServiceToken(
+      { appId: 'app-1', appName: 'svc', environment: 'bogus' },
+      SERVICE_SECRET,
+    );
+    const req = makeReq({ headers: { authorization: `Bearer ${token}` } });
+    const res = makeRes();
+    const next = jest.fn();
+
+    const mw = oxy.auth({ jwtSecret: SERVICE_SECRET });
+    await mw(req as unknown as never, res as unknown as never, next as unknown as never);
+
+    expect(next).not.toHaveBeenCalled();
+    expect(res.statusCode).toBe(401);
+    expect(res.body).toMatchObject({ code: 'INVALID_SERVICE_TOKEN' });
+  });
+});

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,
 ];

package/src/server/auth.ts

@@ -1,5 +1,9 @@
 import type { NextFunction, Request, RequestHandler, Response } from 'express';
 import type { OxyServices } from '../OxyServices';
+import { OXY_SERVICE_ENVIRONMENTS, type OxyServiceEnvironment } from '../utils/oxyServiceEnvironment';
+
+export { OXY_SERVICE_ENVIRONMENTS };
+export type { OxyServiceEnvironment };
 
 export interface OxyRequestUser {
   id: string;
@@ -15,6 +19,7 @@ export interface OxyServiceAppContext {
   appName: string;
   scopes: string[];
   credentialId: string;
+  environment: OxyServiceEnvironment;
 }
 
 export interface OxyServiceActingAsContext {

package/src/server/index.ts

@@ -22,6 +22,7 @@ export {
   getRequiredOxyUserId,
   isOxyAuthenticated,
   requireOxyAuth,
+  OXY_SERVICE_ENVIRONMENTS,
 } from './auth';
 export type {
   OxyAuthenticatedRequest,
@@ -30,6 +31,7 @@ export type {
   OxyRequestUser,
   OxyServiceActingAsContext,
   OxyServiceAppContext,
+  OxyServiceEnvironment,
 } from './auth';
 export { createOxyRateLimit } from './rateLimit';
 export type { OxyRateLimitOptions } from './rateLimit';

package/src/utils/__tests__/oxyServiceEnvironment.test.ts

@@ -0,0 +1,7 @@
+import { OXY_SERVICE_ENVIRONMENTS } from '../oxyServiceEnvironment';
+
+describe('OXY_SERVICE_ENVIRONMENTS', () => {
+  it('lists exactly development, staging, production, in that order', () => {
+    expect(OXY_SERVICE_ENVIRONMENTS).toEqual(['development', 'staging', 'production']);
+  });
+});

package/src/utils/oxyServiceEnvironment.ts

@@ -0,0 +1,17 @@
+/**
+ * Environment segregation for Oxy service-token JWTs (test/live isolation).
+ * Mirrors `ApplicationCredentialEnvironment` on the API's `ApplicationCredential`
+ * model (`packages/api/src/models/ApplicationCredential.ts`) as an INDEPENDENT
+ * literal union — `@oxyhq/core` has zero dependency on `@oxyhq/api`, so this is
+ * kept in sync by hand, not by import.
+ *
+ * Defined here (not in `server/auth.ts` or `mixins/OxyServices.utility.ts`
+ * directly) because BOTH of those files need it and neither may import from
+ * the other: `server/` types import `express` (Node-only, a peer dependency
+ * `mixins/` deliberately avoids so it stays safe to bundle into RN/browser
+ * consumers — see the "Local request/response/socket typing" comment in
+ * `OxyServices.utility.ts`). This file has zero imports, so both sides can
+ * depend on it without crossing that boundary.
+ */
+export const OXY_SERVICE_ENVIRONMENTS = ['development', 'staging', 'production'] as const;
+export type OxyServiceEnvironment = (typeof OXY_SERVICE_ENVIRONMENTS)[number];