@oxy.so/core 1.5.0 → 1.6.0

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

@@ -1,96 +1,138 @@
 /**
- * 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.
+ * Giving a root to Commons (ADR 0024 D6): both sides derive the same key and code;
+ * the responder receives exactly the declared identity; the initiator's key is
+ * committed before the responder's is chosen, so a relay cannot steer both codes
+ * together; and the receipt binds the move, root, both keys and the relayed
+ * ciphertext.
  */
 
+import { generateSecp256k1KeyPair } from '@oxy.so/protocol/secp256k1';
+import { signMessage } from '@oxy.so/protocol';
 import {
   buildMoveQrPayload,
+  createMoveCommitment,
   deriveMoveKey,
   deriveMoveSas,
+  digestMoveCiphertext,
   generateMoveEphemeralKeyPair,
-  IDENTITY_MOVE_ACTIONS,
   openMovedIdentity,
   parseMoveQrPayload,
   sealIdentityForMove,
-  signMoveAction,
+  signMoveReceipt,
+  verifyMoveCommitment,
   verifyMoveReceipt,
 } from '../identityMove';
-import { generateWebIdentity } from '../webIdentityCarrier';
+import { deriveIdentityFromMnemonic, 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);
+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';
+
+function code(initiator: string, responder: string, commitment: string, moveId = MOVE_ID): string {
+  return deriveMoveSas({ moveId, initiatorEphemeralPublicKey: initiator, responderEphemeralPublicKey: responder, initiatorCommitment: commitment });
+}
+
+describe('a move between two honest sides', () => {
+  it('delivers the declared identity — 12 or 24 words — and both screens show the same code', () => {
+    for (const identity of [generateWebIdentity(), deriveIdentityFromMnemonic(MNEMONIC_24)]) {
+      const web = generateMoveEphemeralKeyPair();
+      const commons = generateMoveEphemeralKeyPair();
+      const { commitment, nonce } = createMoveCommitment(web.publicKey);
+      expect(verifyMoveCommitment(web.publicKey, nonce, commitment)).toBe(true);
+
+      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(code(web.publicKey, commons.publicKey, commitment)).toMatch(/^\d{6}$/);
+      expect(code(web.publicKey, commons.publicKey, commitment, MOVE_ID.toUpperCase())).toBe(code(web.publicKey, commons.publicKey, commitment));
+
+      const sealed = sealIdentityForMove(identity, webKey, MOVE_ID);
+      expect(JSON.stringify(sealed)).not.toContain(identity.privateKey);
+      expect(openMovedIdentity(sealed, commonsKey, MOVE_ID, identity.publicKey)).toEqual(identity);
+    }
   });
 });
 
-describe('a relay that substitutes a key', () => {
+describe('a relay that substitutes keys', () => {
+  it('cannot reveal a key the commitment does not open', () => {
+    const web = generateSecp256k1KeyPair();
+    const { commitment, nonce } = createMoveCommitment(web.publicKey);
+    expect(verifyMoveCommitment(generateSecp256k1KeyPair().publicKey, nonce, commitment)).toBe(false);
+    expect(verifyMoveCommitment(web.publicKey, 'ab'.repeat(32), commitment)).toBe(false);
+  });
+
   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();
+    const { commitment } = createMoveCommitment(web.publicKey);
+    const attackerCommitment = createMoveCommitment(attacker.publicKey).commitment;
 
-    // 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);
+    expect(code(web.publicKey, attacker.publicKey, commitment)).not.toBe(code(attacker.publicKey, commons.publicKey, attackerCommitment));
 
-    // 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('changes the code when any input changes, including the commitment', () => {
+    const web = generateSecp256k1KeyPair();
+    const commons = generateSecp256k1KeyPair();
+    const { commitment } = createMoveCommitment(web.publicKey);
+    const base = code(web.publicKey, commons.publicKey, commitment);
+    expect(code(web.publicKey, commons.publicKey, createMoveCommitment(web.publicKey).commitment)).not.toBe(base);
+    expect(code(web.publicKey, generateSecp256k1KeyPair().publicKey, commitment)).not.toBe(base);
+    expect(code(commons.publicKey, web.publicKey, commitment)).not.toBe(base);
   });
 
-  it('binds the ciphertext to its move id', () => {
-    const identity = generateWebIdentity();
+  it('refuses a sealed identity that is not the one the move declared, or another move’s ciphertext', () => {
+    const declared = 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();
+    expect(() => openMovedIdentity(sealIdentityForMove(generateWebIdentity(), key, MOVE_ID), key, MOVE_ID, declared.publicKey)).toThrow();
+    expect(() => openMovedIdentity(sealIdentityForMove(declared, key, MOVE_ID), key, 'ffffffffffffffffffffffffffffffff', declared.publicKey)).toThrow();
   });
 });
 
 describe('receipts', () => {
-  it('verify only when signed by the moved identity for this move', async () => {
+  function transfer() {
     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 web = generateMoveEphemeralKeyPair();
+    const commons = generateMoveEphemeralKeyPair();
+    const sealed = sealIdentityForMove(identity, deriveMoveKey(web.privateKey, commons.publicKey, MOVE_ID), MOVE_ID);
+    const claims = {
+      moveId: MOVE_ID,
+      rootPublicKey: identity.publicKey,
+      initiatorEphemeralPublicKey: web.publicKey,
+      responderEphemeralPublicKey: commons.publicKey,
+      ciphertextDigest: digestMoveCiphertext(sealed),
+    };
+    return { identity, sealed, claims };
+  }
+
+  it('verify for exactly the move, root, keys and ciphertext they were made over', async () => {
+    const { identity, sealed, claims } = transfer();
+    const receipt = await signMoveReceipt((message) => signMessage(message, identity.privateKey), claims);
+    expect(await verifyMoveReceipt(claims, receipt.signature)).toBe(true);
+
+    const other = { ...sealed, ciphertext: `${sealed.ciphertext.slice(0, -2)}00` };
+    for (const changed of [
+      { ...claims, moveId: 'ffffffffffffffffffffffffffffffff' },
+      { ...claims, responderEphemeralPublicKey: generateSecp256k1KeyPair().publicKey },
+      { ...claims, initiatorEphemeralPublicKey: generateSecp256k1KeyPair().publicKey },
+      { ...claims, ciphertextDigest: digestMoveCiphertext(other) },
+    ]) {
+      expect(await verifyMoveReceipt(changed, receipt.signature)).toBe(false);
+    }
+  });
 
-    const sealProof = await signMoveAction(identity, IDENTITY_MOVE_ACTIONS.seal, MOVE_ID);
-    expect(await verifyMoveReceipt(identity.publicKey, MOVE_ID, sealProof)).toBe(false);
+  it('are not the root’s if another key signed them', async () => {
+    const { claims } = transfer();
+    const forged = await signMoveReceipt((message) => signMessage(message, generateWebIdentity().privateKey), claims);
+    expect(await verifyMoveReceipt(claims, forged.signature)).toBe(false);
   });
 });
 

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);
+  });
+});