@oxy.so/core 1.5.1 → 1.6.1

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

@@ -0,0 +1,81 @@
+/**
+ * The one identity-proof format (ADR 0024 D7): the signed bytes name every
+ * claim, so a signature for one operation verifies for nothing else.
+ */
+
+import { buildIdentityProofMessage, canonicalJson, type IdentityProofClaims } from '@oxy.so/contracts';
+import { verifySignature } from '@oxy.so/protocol';
+import { digestIdentityPayload, signIdentityProof } from '../identityProof';
+import { deriveIdentityFromMnemonic } from '../webIdentityCarrier';
+
+const identity = deriveIdentityFromMnemonic('abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about');
+
+const claims = (overrides: Partial<IdentityProofClaims> = {}): IdentityProofClaims => ({
+  action: 'web_envelope_put',
+  subject: 'user-1',
+  actor: 'user-1',
+  rootPublicKey: identity.publicKey,
+  payloadDigest: digestIdentityPayload({ b: 1, a: [1, 'x'] }),
+  expectedRevision: 3,
+  audience: 'oxy-api/identity',
+  challenge: 'ab'.repeat(32),
+  expiresAt: 1_800_000_000_000,
+  ...overrides,
+});
+
+describe('canonical JSON', () => {
+  it('sorts keys at every depth and drops undefined members', () => {
+    expect(canonicalJson({ b: 1, a: { d: [3, { z: 1, y: 2 }], c: undefined } })).toBe('{"a":{"d":[3,{"y":2,"z":1}]},"b":1}');
+  });
+
+  it('digests the same payload identically whatever its key order', () => {
+    expect(digestIdentityPayload({ a: 1, b: 2 })).toBe(digestIdentityPayload({ b: 2, a: 1 }));
+    expect(digestIdentityPayload({ a: 1, b: 2 })).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  it('refuses values JSON cannot represent exactly', () => {
+    expect(() => canonicalJson({ a: Number.NaN })).toThrow('non-finite');
+    expect(() => canonicalJson({ a: () => 1 })).toThrow('unsupported');
+  });
+});
+
+describe('the signed bytes', () => {
+  it('are a fixed, versioned, domain-separated shape', () => {
+    expect(buildIdentityProofMessage(claims())).toBe(
+      `{"action":"web_envelope_put","actor":"user-1","audience":"oxy-api/identity","challenge":"${'ab'.repeat(32)}","domain":"oxy-identity-proof","expectedRevision":3,"expiresAt":1800000000000,"payloadDigest":"${claims().payloadDigest}","rootPublicKey":"${identity.publicKey}","subject":"user-1","v":2}`,
+    );
+  });
+
+  it('refuse malformed claims instead of signing something ambiguous', () => {
+    expect(() => buildIdentityProofMessage(claims({ action: 'anything' as never }))).toThrow('unknown action');
+    expect(() => buildIdentityProofMessage(claims({ payloadDigest: 'AB'.repeat(32) }))).toThrow('payloadDigest');
+    expect(() => buildIdentityProofMessage(claims({ challenge: 'short' }))).toThrow('challenge');
+    expect(() => buildIdentityProofMessage(claims({ rootPublicKey: identity.publicKey.toUpperCase() }))).toThrow('rootPublicKey');
+  });
+});
+
+describe('signing', () => {
+  it('verifies for exactly the claims it was made for', async () => {
+    const proof = await signIdentityProof(identity, claims());
+    expect(proof).toMatchObject({ v: 2, challenge: 'ab'.repeat(32), expiresAt: 1_800_000_000_000 });
+
+    expect(await verifySignature(buildIdentityProofMessage(claims()), proof.signature, identity.publicKey)).toBe(true);
+    for (const changed of [
+      claims({ action: 'web_envelope_delete' }),
+      claims({ subject: 'user-2' }),
+      claims({ actor: 'user-2' }),
+      claims({ payloadDigest: digestIdentityPayload({ b: 2 }) }),
+      claims({ expectedRevision: 4 }),
+      claims({ audience: 'somewhere-else' }),
+      claims({ challenge: 'cd'.repeat(32) }),
+      claims({ expiresAt: 1_800_000_000_001 }),
+    ]) {
+      expect(await verifySignature(buildIdentityProofMessage(changed), proof.signature, identity.publicKey)).toBe(false);
+    }
+  });
+
+  it('will not sign claims naming a different root', async () => {
+    const other = deriveIdentityFromMnemonic('legal winner thank year wave sausage worth useful legal winner thank yellow');
+    await expect(signIdentityProof(identity, claims({ rootPublicKey: other.publicKey }))).rejects.toThrow('different root');
+  });
+});

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

@@ -5,18 +5,14 @@
  */
 
 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,
@@ -72,7 +68,7 @@ describe('the identity itself', () => {
 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 });
+    const { envelope, dataKey } = sealWebIdentity(identity, { prfOutput: prf(7), credentialId: CREDENTIAL_A, rpId: 'oxy.so' });
     wipeBytes(dataKey);
 
     // The stored shape is exactly the published contract.
@@ -87,22 +83,22 @@ describe('sealing and unlocking', () => {
   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 }),
+      sealWebIdentity({ ...deriveIdentityFromMnemonic(MNEMONIC), publicKey: other.publicKey }, { prfOutput: prf(1), credentialId: CREDENTIAL_A, rpId: 'oxy.so' }),
     ).toThrow('does not belong');
   });
 
   it('reports an unregistered passkey as unknown-credential', () => {
-    const { envelope } = sealWebIdentity(deriveIdentityFromMnemonic(MNEMONIC), { prfOutput: prf(7), credentialId: CREDENTIAL_A });
+    const { envelope } = sealWebIdentity(deriveIdentityFromMnemonic(MNEMONIC), { prfOutput: prf(7), credentialId: CREDENTIAL_A, rpId: 'oxy.so' });
     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 });
+    const { envelope } = sealWebIdentity(deriveIdentityFromMnemonic(MNEMONIC), { prfOutput: prf(7), credentialId: CREDENTIAL_A, rpId: 'oxy.so' });
     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 { envelope } = sealWebIdentity(deriveIdentityFromMnemonic(MNEMONIC), { prfOutput: prf(7), credentialId: CREDENTIAL_A, rpId: 'oxy.so' });
     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');
@@ -112,50 +108,52 @@ describe('sealing and unlocking', () => {
     const { envelope, dataKey } = sealWebIdentity(deriveIdentityFromMnemonic(MNEMONIC), {
       prfOutput: prf(7),
       credentialId: CREDENTIAL_A,
+      rpId: 'oxy.so',
     });
     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', () => {
+  it('treats a tampered sealed secret as corrupt, never as a different identity', () => {
     const { envelope, dataKey } = sealWebIdentity(deriveIdentityFromMnemonic(MNEMONIC), {
       prfOutput: prf(7),
       credentialId: CREDENTIAL_A,
+      rpId: 'oxy.so',
     });
-    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');
+    const flipped = envelope.sealedSecret.startsWith('0') ? `1${envelope.sealedSecret.slice(1)}` : `0${envelope.sealedSecret.slice(1)}`;
+    expect(failureOf(() => openWebIdentity({ ...envelope, sealedSecret: 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);
+    const sealed = sealWebIdentity(identity, { prfOutput: prf(1), credentialId: CREDENTIAL_A, rpId: 'oxy.so' });
+    const withTwo = addWrap(sealed.envelope, sealed.dataKey, { prfOutput: prf(2), credentialId: CREDENTIAL_B, rpId: 'oxy.so' });
 
     expect(withTwo.wraps.map((wrap) => wrap.credentialId)).toEqual([CREDENTIAL_A, CREDENTIAL_B]);
-    expect(withTwo.sealedEntropy).toBe(sealed.envelope.sealedEntropy);
+    expect(withTwo.sealedSecret).toBe(sealed.envelope.sealedSecret);
     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);
+    const sealed = sealWebIdentity(deriveIdentityFromMnemonic(MNEMONIC), { prfOutput: prf(1), credentialId: CREDENTIAL_A, rpId: 'oxy.so' });
+    const rewrapped = addWrap(sealed.envelope, sealed.dataKey, { prfOutput: prf(9), credentialId: CREDENTIAL_A, rpId: 'oxy.so' });
     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();
+    const first = sealWebIdentity(deriveIdentityFromMnemonic(MNEMONIC), { prfOutput: prf(1), credentialId: CREDENTIAL_A, rpId: 'oxy.so' });
+    const second = sealWebIdentity(generateWebIdentity(), { prfOutput: prf(1), credentialId: CREDENTIAL_A, rpId: 'oxy.so' });
+    expect(() => addWrap(first.envelope, second.dataKey, { prfOutput: prf(2), credentialId: CREDENTIAL_B, rpId: 'oxy.so' })).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 sealed = sealWebIdentity(deriveIdentityFromMnemonic(MNEMONIC), { prfOutput: prf(1), credentialId: CREDENTIAL_A, rpId: 'oxy.so' });
+    const withTwo = addWrap(sealed.envelope, sealed.dataKey, { prfOutput: prf(2), credentialId: CREDENTIAL_B, rpId: 'oxy.so' });
     const withOne = removeWrap(withTwo, CREDENTIAL_A);
 
     expect(withOne.wraps.map((wrap) => wrap.credentialId)).toEqual([CREDENTIAL_B]);
@@ -163,49 +161,9 @@ describe('more than 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 sealed = sealWebIdentity(deriveIdentityFromMnemonic(MNEMONIC), { prfOutput: prf(1), credentialId: CREDENTIAL_A, rpId: 'oxy.so' });
     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/__tests__/webIdentityRecoveryMaterial.test.ts

@@ -0,0 +1,117 @@
+/**
+ * Envelopes (ADR 0024 D2, D5): one root, whatever material it came from — a 12-
+ * or 24-word phrase, or a raw key that must never gain a phrase — and wraps bound
+ * to the RP ID their passkey lives under.
+ */
+
+import { webIdentityEnvelopeSchema } from '@oxy.so/contracts';
+import { mnemonicToSeedSync } from '@scure/bip39';
+import { bytesToHex } from '@noble/hashes/utils';
+import { deriveSecp256k1PublicKey } from '@oxy.so/protocol/secp256k1';
+import {
+  addWrap,
+  deriveIdentityFromMnemonic,
+  deriveIdentityFromPrivateKey,
+  deriveIdentityFromRecoveryMaterial,
+  isUsablePrfOutput,
+  markWrapVerified,
+  parseRecoveryMaterial,
+  sealWebIdentity,
+  unlockWebIdentity,
+  unwrapDataKey,
+  WebIdentityUnlockError,
+  wipeBytes,
+} from '../webIdentityCarrier';
+
+const MNEMONIC_12 = 'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about';
+/** BIP-39 reference vector: 32 bytes of zero entropy. */
+const MNEMONIC_24 =
+  'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon art';
+const RAW_KEY = '1f'.repeat(32);
+const prf = (fill: number): Uint8Array => new Uint8Array(32).fill(fill);
+const CREDENTIAL = 'credential-aaaaaaaaaaaaaaaa';
+
+const failureOf = (fn: () => unknown): string | undefined => {
+  try {
+    fn();
+  } catch (error) {
+    return error instanceof WebIdentityUnlockError ? error.failure : 'other';
+  }
+  return undefined;
+};
+
+describe('recovery material', () => {
+  it('derives a 24-word root exactly as seed[0:32], unchanged from the 12-word rule', () => {
+    const identity = deriveIdentityFromMnemonic(MNEMONIC_24);
+    const expected = bytesToHex(mnemonicToSeedSync(MNEMONIC_24).slice(0, 32));
+    expect(identity.kind).toBe('mnemonic');
+    expect(identity.privateKey).toBe(expected);
+    expect(identity.publicKey).toBe(deriveSecp256k1PublicKey(expected));
+  });
+
+  it('reads a phrase or a raw key, and nothing else', () => {
+    expect(parseRecoveryMaterial(`  ${MNEMONIC_24.toUpperCase()} `)).toEqual({ kind: 'mnemonic', mnemonic: MNEMONIC_24 });
+    expect(parseRecoveryMaterial(`0x${RAW_KEY.toUpperCase()}`)).toEqual({ kind: 'raw-key', privateKey: `0x${RAW_KEY.toUpperCase()}` });
+    expect(() => parseRecoveryMaterial('abandon abandon')).toThrow('Invalid recovery material');
+    expect(() => parseRecoveryMaterial('zz'.repeat(32))).toThrow('Invalid recovery material');
+  });
+
+  it('keeps a raw key a raw key: no phrase is ever derived for it', () => {
+    const identity = deriveIdentityFromRecoveryMaterial({ kind: 'raw-key', privateKey: `0x${RAW_KEY}` });
+    expect(identity).toEqual({ kind: 'raw-key', mnemonic: null, privateKey: RAW_KEY, publicKey: deriveSecp256k1PublicKey(RAW_KEY) });
+    expect(() => deriveIdentityFromPrivateKey('00'.repeat(32))).toThrow('Invalid private key');
+  });
+
+  it('treats only an actual 32-byte PRF output as usable', () => {
+    expect(isUsablePrfOutput(prf(1))).toBe(true);
+    expect(isUsablePrfOutput(new Uint8Array(31))).toBe(false);
+    expect(isUsablePrfOutput(null)).toBe(false);
+  });
+});
+
+describe('envelopes', () => {
+  it.each([
+    ['12 words', () => deriveIdentityFromMnemonic(MNEMONIC_12)],
+    ['24 words', () => deriveIdentityFromMnemonic(MNEMONIC_24)],
+    ['a raw key', () => deriveIdentityFromPrivateKey(RAW_KEY)],
+  ])('seals and reopens the same root from %s', (_label, make) => {
+    const identity = make();
+    const { envelope, dataKey } = sealWebIdentity(identity, { prfOutput: prf(7), credentialId: CREDENTIAL, rpId: 'oxy.so' });
+    wipeBytes(dataKey);
+
+    expect(webIdentityEnvelopeSchema.safeParse(envelope).success).toBe(true);
+    expect(envelope.version).toBe(2);
+    expect(envelope.wraps[0].rpId).toBe('oxy.so');
+    const opened = unlockWebIdentity(envelope, prf(7), CREDENTIAL);
+    expect(opened).toEqual(make());
+  });
+
+  it('binds the RP ID into the wrap, so a relabelled wrap does not open', () => {
+    const { envelope, dataKey } = sealWebIdentity(deriveIdentityFromMnemonic(MNEMONIC_12), { prfOutput: prf(3), credentialId: CREDENTIAL, rpId: 'oxy.so' });
+    wipeBytes(dataKey);
+    const relabelled = { ...envelope, wraps: envelope.wraps.map((wrap) => ({ ...wrap, rpId: 'auth.oxy.so' })) };
+    expect(failureOf(() => unwrapDataKey(relabelled, prf(3), CREDENTIAL))).toBe('prf-mismatch');
+  });
+
+  it('refuses a secret kind that was swapped after sealing', () => {
+    const { envelope, dataKey } = sealWebIdentity(deriveIdentityFromMnemonic(MNEMONIC_24), { prfOutput: prf(3), credentialId: CREDENTIAL });
+    const swapped = { ...envelope, secretKind: 'raw-private-key' as const };
+    expect(failureOf(() => unlockWebIdentity(swapped, prf(3), CREDENTIAL))).toBe('corrupt');
+    wipeBytes(dataKey);
+  });
+
+  it('adds a second passkey and records which wraps have proven they open the root', () => {
+    const identity = deriveIdentityFromMnemonic(MNEMONIC_12);
+    const { envelope, dataKey } = sealWebIdentity(identity, { prfOutput: prf(1), credentialId: CREDENTIAL, rpId: 'oxy.so' });
+    const second = 'credential-bbbbbbbbbbbbbbbb';
+    const both = addWrap(envelope, dataKey, { prfOutput: prf(2), credentialId: second, rpId: 'oxy.so' });
+    wipeBytes(dataKey);
+
+    expect(unlockWebIdentity(both, prf(2), second).publicKey).toBe(identity.publicKey);
+    const verified = markWrapVerified(both, second, new Date('2026-09-16T00:00:00.000Z'));
+    expect(verified.wraps.find((wrap) => wrap.credentialId === second)?.verifiedAt).toBe('2026-09-16T00:00:00.000Z');
+    expect(verified.wraps.find((wrap) => wrap.credentialId === CREDENTIAL)?.verifiedAt).toBeUndefined();
+    // Holder metadata is not part of the AEAD: marking does not change what opens.
+    expect(unlockWebIdentity(verified, prf(1), CREDENTIAL).publicKey).toBe(identity.publicKey);
+  });
+});

package/src/crypto/identityMove.ts

@@ -1,10 +1,13 @@
 /**
- * Identity move — the crypto of taking a web identity into Commons.
+ * Identity move — the crypto of giving a web root to Commons (ADR 0024 D6).
  *
- * 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.
+ * Both sides run this: the web holder (the initiator, holding the root) and
+ * Commons (the responder, receiving it). The relay in between sees a commitment,
+ * two ephemeral public keys and ciphertext. The initiator commits to its key
+ * before the responder chooses one and reveals it only afterwards, so the 6-digit
+ * code both screens show exposes a relay that substituted a key — it cannot grind
+ * one until the codes agree. The receipt binds the move, the root, both keys and
+ * the ciphertext actually relayed.
  *
  * PURE: no storage, no network. Contract: `@oxy.so/contracts` `identityMove`.
  */
@@ -12,22 +15,27 @@
 import './polyfill';
 import { entropyToMnemonic, mnemonicToEntropy } from '@scure/bip39';
 import { wordlist } from '@scure/bip39/wordlists/english';
+import { sha256 } from '@noble/hashes/sha256';
 import { bytesToHex, hexToBytes, utf8ToBytes } from '@noble/hashes/utils';
-import { signMessage, verifySignature } from '@oxy.so/protocol';
+import { verifySignature } from '@oxy.so/protocol';
 import { generateSecp256k1KeyPair } from '@oxy.so/protocol/secp256k1';
-import { IDENTITY_MOVE_QR_PREFIX } from '@oxy.so/contracts';
+import {
+  IDENTITY_MOVE_QR_PREFIX,
+  buildMoveCiphertextDigestInput,
+  buildMoveCommitmentInput,
+  buildMoveReceiptMessage,
+  buildMoveSasInput,
+} 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';
+import { deriveIdentityFromMnemonic, wipeBytes, type OpenedMnemonicIdentity } 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;
+function sha256Hex(input: string): string {
+  return bytesToHex(sha256(utf8ToBytes(input)));
+}
 
 /** A fresh ephemeral key pair for one move. Keep the private key in memory only. */
 export function generateMoveEphemeralKeyPair(): { privateKey: string; publicKey: string } {
@@ -44,21 +52,71 @@ export function deriveMoveKey(ownEphemeralPrivateKey: string, otherEphemeralPubl
   }
 }
 
-/** 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 });
+/** Initiator: commit to the ephemeral key before anyone else's key is known. The nonce stays in memory until the reveal. */
+export function createMoveCommitment(initiatorEphemeralPublicKey: string): { commitment: string; nonce: string } {
+  const nonceBytes = new Uint8Array(32);
+  globalThis.crypto.getRandomValues(nonceBytes);
+  const nonce = bytesToHex(nonceBytes);
+  return { commitment: sha256Hex(buildMoveCommitmentInput(initiatorEphemeralPublicKey, nonce)), nonce };
+}
+
+/** Responder: does the revealed key match the commitment read before joining? */
+export function verifyMoveCommitment(initiatorEphemeralPublicKey: string, nonce: string, commitment: string): boolean {
+  return sha256Hex(buildMoveCommitmentInput(initiatorEphemeralPublicKey, nonce)) === commitment.toLowerCase();
+}
+
+/** The 6-digit code, bound to the move, both keys in their roles, and the commitment. */
+export function deriveMoveSas(input: {
+  moveId: string;
+  initiatorEphemeralPublicKey: string;
+  responderEphemeralPublicKey: string;
+  initiatorCommitment: string;
+}): string {
+  const digest = sha256(utf8ToBytes(buildMoveSasInput(input)));
+  const value = ((digest[0] << 24) | (digest[1] << 16) | (digest[2] << 8) | digest[3]) >>> 0;
+  return String(value % 1_000_000).padStart(6, '0');
+}
+
+/** The digest a receipt binds: what was actually relayed. */
+export function digestMoveCiphertext(sealed: { nonce: string; ciphertext: string }): string {
+  return sha256Hex(buildMoveCiphertextDigestInput(sealed));
+}
+
+export interface MoveReceiptClaims {
+  moveId: string;
+  rootPublicKey: string;
+  initiatorEphemeralPublicKey: string;
+  responderEphemeralPublicKey: string;
+  ciphertextDigest: string;
+}
+
+/**
+ * Responder: sign the receipt with a signer that reads the root back from durable
+ * storage (Commons passes its keychain signer), so a receipt exists only for a
+ * root that was actually stored.
+ */
+export async function signMoveReceipt(sign: (message: string) => Promise<string>, claims: MoveReceiptClaims): Promise<{ signature: string }> {
+  return { signature: await sign(buildMoveReceiptMessage(claims)) };
+}
+
+/** Initiator: is this receipt the root's, for exactly this move and ciphertext? */
+export function verifyMoveReceipt(claims: MoveReceiptClaims, signature: string): Promise<boolean> {
+  return verifySignature(buildMoveReceiptMessage(claims), signature, claims.rootPublicKey);
 }
 
 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. */
+/** Initiator: seal the phrase entropy (12–24 words) for the responder. */
 export function sealIdentityForMove(
-  identity: Pick<OpenedWebIdentity, 'mnemonic' | 'publicKey'>,
+  identity: Pick<OpenedMnemonicIdentity, 'mnemonic' | 'publicKey'>,
   moveKey: Uint8Array,
   moveId: string,
 ): { nonce: string; ciphertext: string } {
+  if (typeof identity.mnemonic !== 'string' || !identity.mnemonic) {
+    throw new Error('Only an identity with a recovery phrase can be moved this way');
+  }
   const entropy = mnemonicToEntropy(identity.mnemonic, wordlist);
   try {
     const { nonce, ciphertext } = encryptAead(moveKey, entropy, moveAad(moveId, identity.publicKey));
@@ -77,7 +135,7 @@ export function openMovedIdentity(
   moveKey: Uint8Array,
   moveId: string,
   expectedPublicKey: string,
-): OpenedWebIdentity {
+): OpenedMnemonicIdentity {
   let entropy: Uint8Array;
   try {
     entropy = decryptAead(moveKey, hexToBytes(sealed.nonce), hexToBytes(sealed.ciphertext), moveAad(moveId, expectedPublicKey));
@@ -95,30 +153,6 @@ export function openMovedIdentity(
   }
 }
 
-/** 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()}`;

package/src/crypto/identityProof.ts

@@ -0,0 +1,36 @@
+/**
+ * Signing the one identity-proof format (ADR 0024 D7).
+ *
+ * The bytes come from `@oxy.so/contracts` `buildIdentityProofMessage`, which the
+ * API verifies against; payload digests hash `canonicalJson`. Nothing here builds
+ * its own JSON.
+ */
+
+import './polyfill';
+import { sha256 } from '@noble/hashes/sha256';
+import { bytesToHex, utf8ToBytes } from '@noble/hashes/utils';
+import { signMessage } from '@oxy.so/protocol';
+import {
+  IDENTITY_PROOF_VERSION,
+  buildIdentityProofMessage,
+  canonicalJson,
+  type IdentityProof,
+  type IdentityProofClaims,
+} from '@oxy.so/contracts';
+
+/** SHA-256 hex of the canonical JSON of `payload` — the `payloadDigest` claim. */
+export function digestIdentityPayload(payload: unknown): string {
+  return bytesToHex(sha256(utf8ToBytes(canonicalJson(payload))));
+}
+
+/** Sign `claims` with the root, producing the proof as it travels. */
+export async function signIdentityProof(
+  identity: { privateKey: string; publicKey: string },
+  claims: IdentityProofClaims,
+): Promise<IdentityProof> {
+  if (claims.rootPublicKey !== identity.publicKey.toLowerCase()) {
+    throw new Error('identity proof: the claims name a different root');
+  }
+  const signature = await signMessage(buildIdentityProofMessage(claims), identity.privateKey);
+  return { v: IDENTITY_PROOF_VERSION, challenge: claims.challenge, expiresAt: claims.expiresAt, signature };
+}