@oxy.so/core 1.2.1 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -86,7 +86,7 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "build": "bun run --filter @oxy.so/telemetry build && bun run build:cjs && bun run build:esm && bun run build:types && bun run copy-assets && node scripts/mark-module-formats.mjs",
+    "build": "node scripts/build-workspace-deps.mjs @oxy.so/telemetry && bun run build:cjs && bun run build:esm && bun run build:types && bun run copy-assets && node scripts/mark-module-formats.mjs",
     "copy-assets": "cp -r src/i18n/locales dist/cjs/i18n/locales && cp -r src/i18n/locales dist/esm/i18n/locales",
     "build:cjs": "tsc -p tsconfig.cjs.json",
     "build:esm": "tsc -p tsconfig.esm.json && node scripts/fix-esm-imports.mjs",

package/src/crypto/__tests__/identityMove.test.ts

@@ -0,0 +1,104 @@
+/**
+ * Moving an identity: both sides derive the same key and code; the responder
+ * receives exactly the identity that was declared; a relay that swaps a key
+ * gets a different code and cannot open the identity; receipts cannot be forged.
+ */
+
+import {
+  buildMoveQrPayload,
+  deriveMoveKey,
+  deriveMoveSas,
+  generateMoveEphemeralKeyPair,
+  IDENTITY_MOVE_ACTIONS,
+  openMovedIdentity,
+  parseMoveQrPayload,
+  sealIdentityForMove,
+  signMoveAction,
+  verifyMoveReceipt,
+} from '../identityMove';
+import { generateWebIdentity } from '../webIdentityCarrier';
+
+const MOVE_ID = '0123456789abcdef0123456789abcdef';
+
+describe('a move between two honest carriers', () => {
+  it('delivers the declared identity and both screens show the same code', () => {
+    const identity = generateWebIdentity();
+    const web = generateMoveEphemeralKeyPair();
+    const commons = generateMoveEphemeralKeyPair();
+
+    const webKey = deriveMoveKey(web.privateKey, commons.publicKey, MOVE_ID);
+    const commonsKey = deriveMoveKey(commons.privateKey, web.publicKey, MOVE_ID);
+    expect(Buffer.from(webKey).equals(Buffer.from(commonsKey))).toBe(true);
+
+    expect(deriveMoveSas(MOVE_ID, web.publicKey, commons.publicKey)).toMatch(/^\d{6}$/);
+
+    const sealed = sealIdentityForMove(identity, webKey, MOVE_ID);
+    expect(JSON.stringify(sealed)).not.toContain(identity.privateKey);
+
+    const received = openMovedIdentity(sealed, commonsKey, MOVE_ID, identity.publicKey);
+    expect(received).toEqual(identity);
+  });
+});
+
+describe('a relay that substitutes a key', () => {
+  it('shows a different code on each screen and cannot open the identity', () => {
+    const identity = generateWebIdentity();
+    const web = generateMoveEphemeralKeyPair();
+    const commons = generateMoveEphemeralKeyPair();
+    const attacker = generateMoveEphemeralKeyPair();
+
+    // Web talks to the attacker thinking it is Commons; Commons talks to the attacker thinking it is the web.
+    const webSas = deriveMoveSas(MOVE_ID, web.publicKey, attacker.publicKey);
+    const commonsSas = deriveMoveSas(MOVE_ID, attacker.publicKey, commons.publicKey);
+    expect(webSas).not.toBe(commonsSas);
+
+    // Even sealed to the attacker, Commons' own key cannot open it.
+    const sealedToAttacker = sealIdentityForMove(identity, deriveMoveKey(web.privateKey, attacker.publicKey, MOVE_ID), MOVE_ID);
+    expect(() =>
+      openMovedIdentity(sealedToAttacker, deriveMoveKey(commons.privateKey, web.publicKey, MOVE_ID), MOVE_ID, identity.publicKey),
+    ).toThrow('could not be opened');
+  });
+
+  it('refuses a sealed identity that is not the one the move declared', () => {
+    const declared = generateWebIdentity();
+    const other = generateWebIdentity();
+    const web = generateMoveEphemeralKeyPair();
+    const commons = generateMoveEphemeralKeyPair();
+    const key = deriveMoveKey(web.privateKey, commons.publicKey, MOVE_ID);
+
+    const sealedOther = sealIdentityForMove(other, key, MOVE_ID);
+    expect(() => openMovedIdentity(sealedOther, key, MOVE_ID, declared.publicKey)).toThrow();
+  });
+
+  it('binds the ciphertext to its move id', () => {
+    const identity = generateWebIdentity();
+    const web = generateMoveEphemeralKeyPair();
+    const commons = generateMoveEphemeralKeyPair();
+    const key = deriveMoveKey(web.privateKey, commons.publicKey, MOVE_ID);
+    const sealed = sealIdentityForMove(identity, key, MOVE_ID);
+    expect(() => openMovedIdentity(sealed, key, 'ffffffffffffffffffffffffffffffff', identity.publicKey)).toThrow();
+  });
+});
+
+describe('receipts', () => {
+  it('verify only when signed by the moved identity for this move', async () => {
+    const identity = generateWebIdentity();
+    const receipt = await signMoveAction(identity, IDENTITY_MOVE_ACTIONS.received, MOVE_ID);
+
+    expect(await verifyMoveReceipt(identity.publicKey, MOVE_ID, receipt)).toBe(true);
+    expect(await verifyMoveReceipt(identity.publicKey, 'ffffffffffffffffffffffffffffffff', receipt)).toBe(false);
+    expect(await verifyMoveReceipt(generateWebIdentity().publicKey, MOVE_ID, receipt)).toBe(false);
+
+    const sealProof = await signMoveAction(identity, IDENTITY_MOVE_ACTIONS.seal, MOVE_ID);
+    expect(await verifyMoveReceipt(identity.publicKey, MOVE_ID, sealProof)).toBe(false);
+  });
+});
+
+describe('QR payload', () => {
+  it('round-trips and rejects anything else', () => {
+    expect(parseMoveQrPayload(buildMoveQrPayload(MOVE_ID))).toBe(MOVE_ID);
+    expect(parseMoveQrPayload(`  ${buildMoveQrPayload(MOVE_ID).toUpperCase()} `)).toBe(MOVE_ID);
+    expect(parseMoveQrPayload('oxycommons://approve?code=abc')).toBeNull();
+    expect(parseMoveQrPayload('oxycommons://move?id=123')).toBeNull();
+  });
+});

package/src/crypto/__tests__/keyManager.sharedSlotSync.test.ts

@@ -0,0 +1,150 @@
+/**
+ * The two identity slots must never disagree, because the disagreement is
+ * silent and it is money.
+ *
+ * Cross-app readers take the SHARED slot first — `deriveScopedSeed`, which is
+ * where Peable's FairCoin wallet comes from — while signing and the server take
+ * the PRIMARY. A key rotation used to write only the primary, so the shared slot
+ * kept the replaced key: the recipient's wallet watched addresses derived from a
+ * key the DID no longer published, and payers sent to addresses it never
+ * watched. Nothing errored on either side.
+ */
+
+import { setPlatformOS } from '../../utils/platform';
+
+jest.mock(
+  'expo-secure-store',
+  () => {
+    const store = new Map<string, string>();
+    return {
+      __esModule: true,
+      WHEN_UNLOCKED_THIS_DEVICE_ONLY: 'WHEN_UNLOCKED_THIS_DEVICE_ONLY',
+      WHEN_UNLOCKED: 'WHEN_UNLOCKED',
+      setItemAsync: jest.fn(async (k: string, v: string) => { store.set(k, v); }),
+      getItemAsync: jest.fn(async (k: string) => store.get(k) ?? null),
+      deleteItemAsync: jest.fn(async (k: string) => { store.delete(k); }),
+      __resetStore__: () => store.clear(),
+    };
+  },
+  { virtual: true },
+);
+
+jest.mock(
+  'expo-crypto',
+  () => ({
+    __esModule: true,
+    getRandomBytes: (length: number) => {
+      const out = new Uint8Array(length);
+      for (let i = 0; i < length; i++) out[i] = (Math.random() * 256) & 0xff;
+      return out;
+    },
+    digestStringAsync: async () => '0'.repeat(64),
+    CryptoDigestAlgorithm: { SHA256: 'SHA-256' },
+  }),
+  { virtual: true },
+);
+
+jest.mock('@oxy.so/protocol', () => ({
+  __esModule: true,
+  ...jest.requireActual('@oxy.so/protocol'),
+  loadExpoCrypto: async () => require('expo-crypto'),
+  loadSecureStore: async () => require('expo-secure-store'),
+  loadNodeCrypto: async () => require('node:crypto'),
+  loadSharedIdentityBridge: async () => null,
+}));
+
+const KEY_A = 'aa'.repeat(32);
+const KEY_B = 'bb'.repeat(32);
+const toHex = (b: Uint8Array): string => Buffer.from(b).toString('hex');
+
+describe('identity slots stay in sync', () => {
+  let KeyManager: typeof import('../keyManager').KeyManager;
+
+  beforeEach(async () => {
+    jest.resetModules();
+    setPlatformOS('ios');
+    const secureStore = (await import('expo-secure-store' as string)) as unknown as {
+      __resetStore__: () => void;
+    };
+    secureStore.__resetStore__();
+    ({ KeyManager } = await import('../keyManager'));
+  });
+
+  /** The shape a rotation used to leave behind: each slot on a different key. */
+  async function makeSlotsDisagree(): Promise<{ publicA: string; publicB: string }> {
+    const publicA = await KeyManager.importSharedIdentity(KEY_A);
+    await KeyManager.importKeyPair(KEY_B, { overwrite: true });
+    const publicB = KeyManager.derivePublicKey(KEY_B);
+    return { publicA, publicB };
+  }
+
+  it('reports both slots, and which one money derives from', async () => {
+    const { publicA, publicB } = await makeSlotsDisagree();
+
+    const state = await KeyManager.getIdentityKeyState();
+
+    expect(state.sharedPublicKey).toBe(KeyManager.canonicalPublicKey(publicA));
+    expect(state.primaryPublicKey).toBe(KeyManager.canonicalPublicKey(publicB));
+    // The shared slot wins, which is exactly why a disagreement is dangerous.
+    expect(state.activePublicKey).toBe(state.sharedPublicKey);
+    expect(state.inSync).toBe(false);
+  });
+
+  it('is in sync when both slots hold the same key', async () => {
+    await KeyManager.importSharedIdentity(KEY_A);
+    await KeyManager.importKeyPair(KEY_A, { overwrite: true });
+
+    const state = await KeyManager.getIdentityKeyState();
+
+    expect(state.inSync).toBe(true);
+    expect(state.activePublicKey).toBe(state.primaryPublicKey);
+  });
+
+  // A device with one slot populated has nothing to contradict, so it must not
+  // read as a disagreement — otherwise every fresh install would report one.
+  it('is in sync when only one slot is populated', async () => {
+    await KeyManager.importKeyPair(KEY_A, { overwrite: true });
+
+    const state = await KeyManager.getIdentityKeyState();
+
+    expect(state.sharedPublicKey).toBeNull();
+    expect(state.activePublicKey).toBe(state.primaryPublicKey);
+    expect(state.inSync).toBe(true);
+  });
+
+  it('repairs a disagreeing shared slot from the primary instead of skipping', async () => {
+    const { publicB } = await makeSlotsDisagree();
+
+    const migrated = await KeyManager.syncSharedIdentity();
+
+    expect(migrated).toBe(true);
+    const state = await KeyManager.getIdentityKeyState();
+    expect(state.inSync).toBe(true);
+    expect(state.sharedPublicKey).toBe(KeyManager.canonicalPublicKey(publicB));
+  });
+
+  // The wallet is the reason any of this matters: the seed must follow the
+  // repaired key, not the one the stale slot was still handing out.
+  it('moves the derived wallet seed onto the repaired key', async () => {
+    await makeSlotsDisagree();
+    const strandedSeed = await KeyManager.deriveScopedSeed('peable/faircoin/v1');
+
+    await KeyManager.syncSharedIdentity();
+    const repairedSeed = await KeyManager.deriveScopedSeed('peable/faircoin/v1');
+
+    if (!strandedSeed || !repairedSeed) throw new Error('expected seeds');
+    expect(toHex(repairedSeed)).not.toBe(toHex(strandedSeed));
+
+    // And it is the seed a device holding only that one key would derive.
+    jest.resetModules();
+    const secureStore = (await import('expo-secure-store' as string)) as unknown as {
+      __resetStore__: () => void;
+    };
+    secureStore.__resetStore__();
+    const { KeyManager: Fresh } = await import('../keyManager');
+    await Fresh.importSharedIdentity(KEY_B);
+    const expected = await Fresh.deriveScopedSeed('peable/faircoin/v1');
+    if (!expected) throw new Error('expected a seed');
+    expect(toHex(repairedSeed)).toBe(toHex(expected));
+  });
+});

package/src/crypto/__tests__/webIdentityCarrier.test.ts

@@ -0,0 +1,211 @@
+/**
+ * Web identity carrier — the envelope must carry EXACTLY the Commons identity,
+ * open only with a registered passkey's PRF output, and refuse (with a reason a
+ * UI can act on) anything else.
+ */
+
+import { webIdentityEnvelopeSchema } from '@oxy.so/contracts';
+import { verifySignature } from '@oxy.so/protocol';
+import { RecoveryPhraseService } from '../recoveryPhrase';
+import {
+  addWrap,
+  buildIdentityActionMessage,
+  deriveIdentityFromMnemonic,
+  deriveTransferSas,
+  generateWebIdentity,
+  openWebIdentity,
+  removeWrap,
+  sealWebIdentity,
+  signIdentityAction,
+  unlockWebIdentity,
+  unwrapDataKey,
+  WEB_IDENTITY_PRF_INPUT,
+  WebIdentityUnlockError,
+  wipeBytes,
+} from '../webIdentityCarrier';
+
+/** The BIP-39 reference mnemonic (all-zero entropy). */
+const MNEMONIC = 'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about';
+
+const prf = (fill: number): Uint8Array => new Uint8Array(32).fill(fill);
+const CREDENTIAL_A = 'credential-aaaaaaaaaaaaaaaa';
+const CREDENTIAL_B = 'credential-bbbbbbbbbbbbbbbb';
+
+const failureOf = (fn: () => unknown): string | undefined => {
+  try {
+    fn();
+  } catch (error) {
+    return error instanceof WebIdentityUnlockError ? error.failure : 'other';
+  }
+  return undefined;
+};
+
+describe('the identity itself', () => {
+  it('derives the SAME key Commons derives from a phrase — one identity, not a second kind', async () => {
+    const identity = deriveIdentityFromMnemonic(MNEMONIC);
+
+    expect(identity.privateKey).toBe(await RecoveryPhraseService.derivePrivateKeyFromPhrase(MNEMONIC));
+    expect(identity.publicKey).toBe(await RecoveryPhraseService.derivePublicKeyFromPhrase(MNEMONIC));
+  });
+
+  it('normalizes case and spacing the way a person types a phrase', () => {
+    const typed = `  ${MNEMONIC.toUpperCase().split(' ').join('   ')} `;
+    expect(deriveIdentityFromMnemonic(typed).publicKey).toBe(deriveIdentityFromMnemonic(MNEMONIC).publicKey);
+  });
+
+  it('rejects an invalid phrase', () => {
+    expect(() => deriveIdentityFromMnemonic('abandon abandon abandon')).toThrow('Invalid recovery phrase');
+  });
+
+  it('generates a fresh 12-word identity in canonical public-key form', () => {
+    const identity = generateWebIdentity();
+    expect(identity.mnemonic.split(' ')).toHaveLength(12);
+    expect(identity.publicKey).toMatch(/^04[0-9a-f]{128}$/);
+    expect(generateWebIdentity().publicKey).not.toBe(identity.publicKey);
+  });
+
+  it('uses a fixed 32-byte PRF input', () => {
+    expect(WEB_IDENTITY_PRF_INPUT).toHaveLength(32);
+  });
+});
+
+describe('sealing and unlocking', () => {
+  it('round-trips: the passkey that sealed it opens it into the same identity', () => {
+    const identity = deriveIdentityFromMnemonic(MNEMONIC);
+    const { envelope, dataKey } = sealWebIdentity(identity, { prfOutput: prf(7), credentialId: CREDENTIAL_A });
+    wipeBytes(dataKey);
+
+    // The stored shape is exactly the published contract.
+    expect(webIdentityEnvelopeSchema.parse(envelope)).toEqual(envelope);
+    // Nothing identifying the secret is visible in the envelope.
+    expect(JSON.stringify(envelope)).not.toContain(identity.privateKey);
+
+    const opened = unlockWebIdentity(envelope, prf(7), CREDENTIAL_A);
+    expect(opened).toEqual(identity);
+  });
+
+  it('refuses to seal a phrase under a public key it does not belong to', () => {
+    const other = generateWebIdentity();
+    expect(() =>
+      sealWebIdentity({ mnemonic: MNEMONIC, publicKey: other.publicKey }, { prfOutput: prf(1), credentialId: CREDENTIAL_A }),
+    ).toThrow('does not belong');
+  });
+
+  it('reports an unregistered passkey as unknown-credential', () => {
+    const { envelope } = sealWebIdentity(deriveIdentityFromMnemonic(MNEMONIC), { prfOutput: prf(7), credentialId: CREDENTIAL_A });
+    expect(failureOf(() => unlockWebIdentity(envelope, prf(7), CREDENTIAL_B))).toBe('unknown-credential');
+  });
+
+  it('reports a registered passkey returning a different PRF value as prf-mismatch (recoverable)', () => {
+    const { envelope } = sealWebIdentity(deriveIdentityFromMnemonic(MNEMONIC), { prfOutput: prf(7), credentialId: CREDENTIAL_A });
+    expect(failureOf(() => unlockWebIdentity(envelope, prf(8), CREDENTIAL_A))).toBe('prf-mismatch');
+  });
+
+  it('refuses a wrap transplanted onto another credential id', () => {
+    const { envelope } = sealWebIdentity(deriveIdentityFromMnemonic(MNEMONIC), { prfOutput: prf(7), credentialId: CREDENTIAL_A });
+    const transplanted = { ...envelope, wraps: [{ ...envelope.wraps[0], credentialId: CREDENTIAL_B }] };
+    // The associated data binds each wrap to its credential.
+    expect(failureOf(() => unlockWebIdentity(transplanted, prf(7), CREDENTIAL_B))).toBe('prf-mismatch');
+  });
+
+  it('refuses an envelope re-labelled with another identity public key', () => {
+    const { envelope, dataKey } = sealWebIdentity(deriveIdentityFromMnemonic(MNEMONIC), {
+      prfOutput: prf(7),
+      credentialId: CREDENTIAL_A,
+    });
+    const relabelled = { ...envelope, publicKey: generateWebIdentity().publicKey };
+    expect(failureOf(() => openWebIdentity(relabelled, dataKey))).toBe('corrupt');
+  });
+
+  it('treats tampered sealed entropy as corrupt, never as a different identity', () => {
+    const { envelope, dataKey } = sealWebIdentity(deriveIdentityFromMnemonic(MNEMONIC), {
+      prfOutput: prf(7),
+      credentialId: CREDENTIAL_A,
+    });
+    const flipped = envelope.sealedEntropy.startsWith('0') ? `1${envelope.sealedEntropy.slice(1)}` : `0${envelope.sealedEntropy.slice(1)}`;
+    expect(failureOf(() => openWebIdentity({ ...envelope, sealedEntropy: flipped }, dataKey))).toBe('corrupt');
+  });
+});
+
+describe('more than one passkey', () => {
+  it('opens with every registered passkey and keeps a single sealed identity', () => {
+    const identity = deriveIdentityFromMnemonic(MNEMONIC);
+    const sealed = sealWebIdentity(identity, { prfOutput: prf(1), credentialId: CREDENTIAL_A });
+    const withTwo = addWrap(sealed.envelope, sealed.dataKey, prf(2), CREDENTIAL_B);
+
+    expect(withTwo.wraps.map((wrap) => wrap.credentialId)).toEqual([CREDENTIAL_A, CREDENTIAL_B]);
+    expect(withTwo.sealedEntropy).toBe(sealed.envelope.sealedEntropy);
+    expect(unlockWebIdentity(withTwo, prf(1), CREDENTIAL_A).publicKey).toBe(identity.publicKey);
+    expect(unlockWebIdentity(withTwo, prf(2), CREDENTIAL_B).publicKey).toBe(identity.publicKey);
+  });
+
+  it('replaces a passkey’s wrap instead of duplicating it', () => {
+    const sealed = sealWebIdentity(deriveIdentityFromMnemonic(MNEMONIC), { prfOutput: prf(1), credentialId: CREDENTIAL_A });
+    const rewrapped = addWrap(sealed.envelope, sealed.dataKey, prf(9), CREDENTIAL_A);
+    expect(rewrapped.wraps).toHaveLength(1);
+    expect(failureOf(() => unlockWebIdentity(rewrapped, prf(1), CREDENTIAL_A))).toBe('prf-mismatch');
+    expect(unlockWebIdentity(rewrapped, prf(9), CREDENTIAL_A).mnemonic).toBe(MNEMONIC);
+  });
+
+  it('will not add a wrap with a data key from a different envelope', () => {
+    const first = sealWebIdentity(deriveIdentityFromMnemonic(MNEMONIC), { prfOutput: prf(1), credentialId: CREDENTIAL_A });
+    const second = sealWebIdentity(generateWebIdentity(), { prfOutput: prf(1), credentialId: CREDENTIAL_A });
+    expect(() => addWrap(first.envelope, second.dataKey, prf(2), CREDENTIAL_B)).toThrow();
+  });
+
+  it('removes a passkey, but never the last one', () => {
+    const sealed = sealWebIdentity(deriveIdentityFromMnemonic(MNEMONIC), { prfOutput: prf(1), credentialId: CREDENTIAL_A });
+    const withTwo = addWrap(sealed.envelope, sealed.dataKey, prf(2), CREDENTIAL_B);
+    const withOne = removeWrap(withTwo, CREDENTIAL_A);
+
+    expect(withOne.wraps.map((wrap) => wrap.credentialId)).toEqual([CREDENTIAL_B]);
+    expect(() => removeWrap(withOne, CREDENTIAL_B)).toThrow('at least one passkey');
+  });
+
+  it('keeps the data key usable only until it is wiped', () => {
+    const sealed = sealWebIdentity(deriveIdentityFromMnemonic(MNEMONIC), { prfOutput: prf(1), credentialId: CREDENTIAL_A });
+    const recovered = unwrapDataKey(sealed.envelope, prf(1), CREDENTIAL_A);
+    wipeBytes(recovered);
+    expect(failureOf(() => openWebIdentity(sealed.envelope, recovered))).toBe('corrupt');
+  });
+});
+
+describe('identity actions', () => {
+  it('signs the exact message the API reconstructs, verifiable with the public key', async () => {
+    const identity = deriveIdentityFromMnemonic(MNEMONIC);
+    const { signature, timestamp } = await signIdentityAction(identity, 'link_identity', 'user-1', 1_700_000_000_000);
+
+    const message = buildIdentityActionMessage('link_identity', 'user-1', timestamp);
+    expect(message).toBe('{"action":"link_identity","userId":"user-1","timestamp":1700000000000}');
+    expect(await verifySignature(message, signature, identity.publicKey)).toBe(true);
+    expect(await verifySignature(buildIdentityActionMessage('web_envelope_delete', 'user-1', timestamp), signature, identity.publicKey)).toBe(false);
+  });
+});
+
+describe('transfer short authentication string', () => {
+  const base = {
+    pairingId: 'ab'.repeat(16),
+    initiatorEphemeralPublicKey: generateWebIdentity().publicKey,
+    responderEphemeralPublicKey: generateWebIdentity().publicKey,
+  };
+
+  it('is six digits and identical on both sides', () => {
+    const sas = deriveTransferSas(base);
+    expect(sas).toMatch(/^\d{6}$/);
+    expect(deriveTransferSas({ ...base, pairingId: base.pairingId.toUpperCase() })).toBe(sas);
+  });
+
+  it('changes when the relay substitutes either ephemeral key, or swaps the roles', () => {
+    const sas = deriveTransferSas(base);
+    const attacker = generateWebIdentity().publicKey;
+    expect(deriveTransferSas({ ...base, responderEphemeralPublicKey: attacker })).not.toBe(sas);
+    expect(deriveTransferSas({ ...base, initiatorEphemeralPublicKey: attacker })).not.toBe(sas);
+    expect(
+      deriveTransferSas({
+        ...base,
+        initiatorEphemeralPublicKey: base.responderEphemeralPublicKey,
+        responderEphemeralPublicKey: base.initiatorEphemeralPublicKey,
+      }),
+    ).not.toBe(sas);
+  });
+});

package/src/crypto/identityMove.ts

@@ -0,0 +1,133 @@
+/**
+ * Identity move — the crypto of taking a web identity into Commons.
+ *
+ * Both carriers run this: `id.oxy.so` (the initiator, holding the identity) and
+ * Commons (the responder, receiving it). The relay in between sees two ephemeral
+ * public keys and ciphertext; the 6-digit SAS both screens show is what makes a
+ * relay that swapped a key visible to the person.
+ *
+ * PURE: no storage, no network. Contract: `@oxy.so/contracts` `identityMove`.
+ */
+
+import './polyfill';
+import { entropyToMnemonic, mnemonicToEntropy } from '@scure/bip39';
+import { wordlist } from '@scure/bip39/wordlists/english';
+import { bytesToHex, hexToBytes, utf8ToBytes } from '@noble/hashes/utils';
+import { signMessage, verifySignature } from '@oxy.so/protocol';
+import { generateSecp256k1KeyPair } from '@oxy.so/protocol/secp256k1';
+import { IDENTITY_MOVE_QR_PREFIX } from '@oxy.so/contracts';
+import { decryptAead, encryptAead, AEAD_KEY_LENGTH } from './aead';
+import { deriveSharedSecret } from './ecdh';
+import { hkdfSha256 } from './kdf';
+import { deriveIdentityFromMnemonic, deriveTransferSas, wipeBytes, type OpenedWebIdentity } from './webIdentityCarrier';
+
+const MOVE_KDF_INFO = utf8ToBytes('oxy-identity-move-v1');
+
+/** Actions the identity key signs during a move. */
+export const IDENTITY_MOVE_ACTIONS = {
+  seal: 'identity_move_seal',
+  received: 'identity_move_received',
+} as const;
+
+/** A fresh ephemeral key pair for one move. Keep the private key in memory only. */
+export function generateMoveEphemeralKeyPair(): { privateKey: string; publicKey: string } {
+  return generateSecp256k1KeyPair();
+}
+
+/** The symmetric key both sides derive: HKDF(ECDH, salt = moveId). */
+export function deriveMoveKey(ownEphemeralPrivateKey: string, otherEphemeralPublicKey: string, moveId: string): Uint8Array {
+  const shared = deriveSharedSecret(ownEphemeralPrivateKey, otherEphemeralPublicKey);
+  try {
+    return hkdfSha256(shared, utf8ToBytes(moveId.toLowerCase()), MOVE_KDF_INFO, AEAD_KEY_LENGTH);
+  } finally {
+    wipeBytes(shared);
+  }
+}
+
+/** The 6-digit code both screens show, bound to the move and both ephemeral keys in their roles. */
+export function deriveMoveSas(moveId: string, initiatorEphemeralPublicKey: string, responderEphemeralPublicKey: string): string {
+  return deriveTransferSas({ pairingId: moveId, initiatorEphemeralPublicKey, responderEphemeralPublicKey });
+}
+
+function moveAad(moveId: string, publicKey: string): Uint8Array {
+  return utf8ToBytes(JSON.stringify({ v: 1, purpose: 'identity-move', moveId: moveId.toLowerCase(), publicKey: publicKey.toLowerCase() }));
+}
+
+/** Initiator: seal the identity's entropy for the responder. */
+export function sealIdentityForMove(
+  identity: Pick<OpenedWebIdentity, 'mnemonic' | 'publicKey'>,
+  moveKey: Uint8Array,
+  moveId: string,
+): { nonce: string; ciphertext: string } {
+  const entropy = mnemonicToEntropy(identity.mnemonic, wordlist);
+  try {
+    const { nonce, ciphertext } = encryptAead(moveKey, entropy, moveAad(moveId, identity.publicKey));
+    return { nonce: bytesToHex(nonce), ciphertext: bytesToHex(ciphertext) };
+  } finally {
+    wipeBytes(entropy);
+  }
+}
+
+/**
+ * Responder: open the sealed identity. The derived public key must be the one
+ * the move declared — anything else is refused, never imported.
+ */
+export function openMovedIdentity(
+  sealed: { nonce: string; ciphertext: string },
+  moveKey: Uint8Array,
+  moveId: string,
+  expectedPublicKey: string,
+): OpenedWebIdentity {
+  let entropy: Uint8Array;
+  try {
+    entropy = decryptAead(moveKey, hexToBytes(sealed.nonce), hexToBytes(sealed.ciphertext), moveAad(moveId, expectedPublicKey));
+  } catch {
+    throw new Error('The identity could not be opened. The codes may not have matched — start again.');
+  }
+  try {
+    const identity = deriveIdentityFromMnemonic(entropyToMnemonic(entropy, wordlist));
+    if (identity.publicKey !== expectedPublicKey.toLowerCase()) {
+      throw new Error('The received identity is not the one being moved');
+    }
+    return identity;
+  } finally {
+    wipeBytes(entropy);
+  }
+}
+
+/** The exact bytes a move proof or receipt signs. */
+export function buildMoveMessage(action: string, moveId: string, timestamp: number): string {
+  return JSON.stringify({ action, moveId: moveId.toLowerCase(), timestamp });
+}
+
+/** Sign a move action with the identity key. */
+export async function signMoveAction(
+  identity: Pick<OpenedWebIdentity, 'privateKey'>,
+  action: string,
+  moveId: string,
+  timestamp: number = Date.now(),
+): Promise<{ signature: string; timestamp: number }> {
+  return { signature: await signMessage(buildMoveMessage(action, moveId, timestamp), identity.privateKey), timestamp };
+}
+
+/**
+ * Initiator: is this receipt really from the identity? Checked locally with the
+ * identity's public key, so a server that claims "completed" without Commons
+ * having the key cannot make the web destroy its copy.
+ */
+export function verifyMoveReceipt(publicKey: string, moveId: string, receipt: { signature: string; timestamp: number }): Promise<boolean> {
+  return verifySignature(buildMoveMessage(IDENTITY_MOVE_ACTIONS.received, moveId, receipt.timestamp), receipt.signature, publicKey);
+}
+
+/** The QR payload for a move. */
+export function buildMoveQrPayload(moveId: string): string {
+  return `${IDENTITY_MOVE_QR_PREFIX}${moveId.toLowerCase()}`;
+}
+
+/** The move id in a scanned payload, or `null` when it is not a move QR. */
+export function parseMoveQrPayload(raw: string): string | null {
+  const value = raw.trim();
+  if (!value.toLowerCase().startsWith(IDENTITY_MOVE_QR_PREFIX)) return null;
+  const id = value.slice(IDENTITY_MOVE_QR_PREFIX.length).toLowerCase();
+  return /^[0-9a-f]{32}$/.test(id) ? id : null;
+}