@oxy.so/core 1.5.0 → 1.6.0

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

package/src/crypto/webIdentityCarrier.ts

@@ -1,18 +1,18 @@
 /**
- * Web identity carrier — the crypto of "one identity, two carriers".
+ * Web identity holder — the crypto of a browser holding a personal root (ADR 0024).
  *
- * An Oxy identity is a BIP-39 mnemonic; its seed's first 32 bytes are the
- * secp256k1 key (`recoveryPhrase.ts`). Commons keeps that key in the device
- * keychain. This module lets a browser carry the SAME identity without Oxy ever
- * being able to use it:
+ * An Oxy root is usually a BIP-39 mnemonic whose seed's first 32 bytes are the
+ * secp256k1 key (`recoveryPhrase.ts`), and for a few imported identities a raw
+ * private key with no phrase. Commons keeps it in the device keychain. This
+ * module lets a browser hold the SAME root without Oxy ever being able to use it:
  *
- *   entropy ──AEAD(DEK)──▶ sealedEntropy
+    secret  ──AEAD(DEK)──▶ sealed secret        (phrase entropy or raw key)
  *   DEK     ──AEAD(KEK_i)─▶ wraps[i]            KEK_i = HKDF(PRF output of passkey i)
  *
  * The PRF output is produced inside the user's authenticator, behind user
  * verification, and never leaves the page that asked for it. The envelope is
- * therefore safe to store anywhere — the identity origin's IndexedDB and the
- * server copy alike — and opens only with a registered passkey or the phrase.
+ * therefore safe to store anywhere — the holder host's IndexedDB and the server
+ * copy alike — and opens only with a registered passkey or the recovery material.
  *
  * PURE: no storage, no network, no WebAuthn call, no platform globals beyond the
  * CSPRNG the AEAD polyfill guarantees. The caller runs the ceremony and hands the
@@ -27,11 +27,11 @@ import { entropyToMnemonic, generateMnemonic, mnemonicToEntropy, mnemonicToSeedS
 import { wordlist } from '@scure/bip39/wordlists/english';
 import { sha256 } from '@noble/hashes/sha256';
 import { bytesToHex, hexToBytes, utf8ToBytes } from '@noble/hashes/utils';
-import { signMessage } from '@oxy.so/protocol';
 import { deriveSecp256k1PublicKey } from '@oxy.so/protocol/secp256k1';
 import {
   WEB_IDENTITY_ENVELOPE_VERSION,
   type WebIdentityEnvelope,
+  type WebIdentitySecretKind,
   type WebIdentityWrap,
 } from '@oxy.so/contracts';
 import { AEAD_KEY_LENGTH, decryptAead, encryptAead } from './aead';
@@ -46,11 +46,11 @@ import { hkdfSha256 } from './kdf';
  */
 export const WEB_IDENTITY_PRF_INPUT: Uint8Array = sha256(utf8ToBytes('oxy-web-identity-carrier/prf/v1'));
 
-/** HKDF salt of the key-encryption-key schedule. Versioned with the envelope. */
+/** HKDF salt of the key-encryption-key schedule. Shared by envelope versions 1 and 2. */
 const KEK_SALT = utf8ToBytes('oxy-web-identity-carrier/kek/v1');
 
-/** A WebAuthn PRF output is 32 bytes (HMAC-SHA-256). */
-const PRF_OUTPUT_LENGTH = 32;
+/** A WebAuthn PRF output is 32 bytes (HMAC-SHA-256). Nothing shorter or longer is usable. */
+export const WEB_IDENTITY_PRF_OUTPUT_LENGTH = 32;
 
 /** Why an envelope did not open. Every value is a normal outcome a UI can explain. */
 export type WebIdentityUnlockFailure =
@@ -59,7 +59,7 @@ export type WebIdentityUnlockFailure =
   /**
    * The passkey IS listed but its PRF output does not open its wrap — a synced
    * copy returning a different PRF value, or a provider that silently changed it.
-   * Recoverable with another passkey or the phrase.
+   * Recoverable with another passkey or the recovery material.
    */
   | 'prf-mismatch'
   /** The envelope itself is malformed or tampered with. */
@@ -72,25 +72,45 @@ export class WebIdentityUnlockError extends Error {
   }
 }
 
-/** The identity in usable form. Hold it for one operation, then {@link wipeBytes}. */
-export interface OpenedWebIdentity {
+/** A root that came from a BIP-39 phrase (12–24 words). Hold it for one operation, then wipe. */
+export interface OpenedMnemonicIdentity {
+  kind: 'mnemonic';
   mnemonic: string;
-  /** 32-byte secp256k1 private key, lowercase hex. */
+  /** 32-byte secp256k1 private key, lowercase hex (`seed[0:32]`). */
   privateKey: string;
   /** Uncompressed SEC1 public key, lowercase hex (Oxy's canonical form). */
   publicKey: string;
 }
 
-function aadFor(parts: Record<string, string | number>): Uint8Array {
+/**
+ * A root that was imported as a raw private key and never had a phrase. It has
+ * no mnemonic, and nothing may ever derive or display one for it (ADR 0024 D5).
+ */
+export interface OpenedRawKeyIdentity {
+  kind: 'raw-key';
+  mnemonic: null;
+  privateKey: string;
+  publicKey: string;
+}
+
+/** The identity in usable form. Hold it for one operation, then wipe it. */
+export type OpenedWebIdentity = OpenedMnemonicIdentity | OpenedRawKeyIdentity;
+
+/** Material a person can recover a root from. */
+export type WebIdentityRecoveryMaterial =
+  | { kind: 'mnemonic'; mnemonic: string }
+  | { kind: 'raw-key'; privateKey: string };
+
+function aadFor(parts: Record<string, string | number | null>): Uint8Array {
   return utf8ToBytes(JSON.stringify(parts));
 }
 
-function entropyAad(publicKey: string): Uint8Array {
-  return aadFor({ v: WEB_IDENTITY_ENVELOPE_VERSION, purpose: 'entropy', publicKey });
+function secretAad(publicKey: string, secretKind: WebIdentitySecretKind): Uint8Array {
+  return aadFor({ v: WEB_IDENTITY_ENVELOPE_VERSION, purpose: 'secret', secretKind, publicKey });
 }
 
-function wrapAad(publicKey: string, credentialId: string): Uint8Array {
-  return aadFor({ v: WEB_IDENTITY_ENVELOPE_VERSION, purpose: 'wrap', publicKey, credentialId });
+function wrapAad(publicKey: string, credentialId: string, rpId: string): Uint8Array {
+  return aadFor({ v: WEB_IDENTITY_ENVELOPE_VERSION, purpose: 'wrap', publicKey, credentialId, rpId });
 }
 
 /** Overwrite a buffer holding secret material. Best effort — JS gives no stronger guarantee. */
@@ -98,12 +118,25 @@ export function wipeBytes(bytes: Uint8Array): void {
   bytes.fill(0);
 }
 
+/** Best-effort removal of secret strings from an opened identity. */
+export function wipeOpenedIdentity(identity: OpenedWebIdentity): void {
+  (identity as { privateKey: string }).privateKey = '';
+  if (identity.kind === 'mnemonic') (identity as { mnemonic: string }).mnemonic = '';
+}
+
+/** Normalize a typed phrase: trimmed, lowercase, single spaces. */
+export function normalizeMnemonic(mnemonic: string): string {
+  return mnemonic.trim().toLowerCase().split(/\s+/).join(' ');
+}
+
 /**
  * Derive the identity from a mnemonic exactly as Commons does
- * (`RecoveryPhraseService`): seed → first 32 bytes → secp256k1.
+ * (`RecoveryPhraseService`): seed → first 32 bytes → secp256k1. Any standard
+ * BIP-39 length (12, 15, 18, 21, 24 words) is accepted; the derivation does not
+ * depend on the length.
  */
-export function deriveIdentityFromMnemonic(mnemonic: string): OpenedWebIdentity {
-  const normalized = mnemonic.trim().toLowerCase().split(/\s+/).join(' ');
+export function deriveIdentityFromMnemonic(mnemonic: string): OpenedMnemonicIdentity {
+  const normalized = normalizeMnemonic(mnemonic);
   if (!validateMnemonic(normalized, wordlist)) {
     throw new Error('Invalid recovery phrase');
   }
@@ -112,11 +145,45 @@ export function deriveIdentityFromMnemonic(mnemonic: string): OpenedWebIdentity
   wipeBytes(seed);
   const privateKey = bytesToHex(privateKeyBytes);
   wipeBytes(privateKeyBytes);
-  return { mnemonic: normalized, privateKey, publicKey: deriveSecp256k1PublicKey(privateKey) };
+  return { kind: 'mnemonic', mnemonic: normalized, privateKey, publicKey: deriveSecp256k1PublicKey(privateKey) };
+}
+
+/** A raw 32-byte private key (hex, optional `0x`) as an identity. Never gains a phrase. */
+export function deriveIdentityFromPrivateKey(privateKey: string): OpenedRawKeyIdentity {
+  const normalized = privateKey.trim().toLowerCase().replace(/^0x/, '');
+  if (!/^[0-9a-f]{64}$/.test(normalized)) {
+    throw new Error('Invalid private key');
+  }
+  let publicKey: string;
+  try {
+    publicKey = deriveSecp256k1PublicKey(normalized);
+  } catch {
+    throw new Error('Invalid private key');
+  }
+  return { kind: 'raw-key', mnemonic: null, privateKey: normalized, publicKey };
+}
+
+/**
+ * Read what a person typed as recovery material: a BIP-39 phrase, or a 64-hex
+ * private key. Throws `Invalid recovery material` for anything else.
+ */
+export function parseRecoveryMaterial(input: string): WebIdentityRecoveryMaterial {
+  const trimmed = input.trim();
+  if (/^(0x)?[0-9a-fA-F]{64}$/.test(trimmed)) return { kind: 'raw-key', privateKey: trimmed };
+  const words = normalizeMnemonic(trimmed);
+  if (words && validateMnemonic(words, wordlist)) return { kind: 'mnemonic', mnemonic: words };
+  throw new Error('Invalid recovery material');
+}
+
+/** Derive the identity recovery material names. */
+export function deriveIdentityFromRecoveryMaterial(material: WebIdentityRecoveryMaterial): OpenedWebIdentity {
+  return material.kind === 'mnemonic'
+    ? deriveIdentityFromMnemonic(material.mnemonic)
+    : deriveIdentityFromPrivateKey(material.privateKey);
 }
 
 /** A brand-new 12-word identity. Nothing is persisted. */
-export function generateWebIdentity(): OpenedWebIdentity {
+export function generateWebIdentity(): OpenedMnemonicIdentity {
   return deriveIdentityFromMnemonic(generateMnemonic(wordlist, 128));
 }
 
@@ -127,36 +194,58 @@ export function generateDataKey(): Uint8Array {
   return key;
 }
 
+/** Whether `bytes` is a usable PRF output: exactly 32 bytes. */
+export function isUsablePrfOutput(bytes: Uint8Array | null | undefined): bytes is Uint8Array {
+  return bytes instanceof Uint8Array && bytes.byteLength === WEB_IDENTITY_PRF_OUTPUT_LENGTH;
+}
+
 /** The key-encryption key a passkey's PRF output yields for its own wrap. */
 export function deriveKeyEncryptionKey(prfOutput: Uint8Array, credentialId: string): Uint8Array {
-  if (prfOutput.length !== PRF_OUTPUT_LENGTH) {
-    throw new Error(`PRF output must be ${PRF_OUTPUT_LENGTH} bytes, got ${prfOutput.length}`);
+  if (prfOutput.length !== WEB_IDENTITY_PRF_OUTPUT_LENGTH) {
+    throw new Error(`PRF output must be ${WEB_IDENTITY_PRF_OUTPUT_LENGTH} bytes, got ${prfOutput.length}`);
   }
   return hkdfSha256(prfOutput, KEK_SALT, utf8ToBytes(credentialId), AEAD_KEY_LENGTH);
 }
 
-/** Wrap `dataKey` for one passkey. */
-export function wrapDataKey(
-  dataKey: Uint8Array,
-  prfOutput: Uint8Array,
-  credentialId: string,
+/** One passkey's contribution to an envelope. */
+export interface WrapInput {
+  prfOutput: Uint8Array;
+  credentialId: string;
+  /** The RP ID the passkey lives under; bound into the wrap. */
+  rpId: string;
+  /** Set when this PRF output came from a ceremony separate from the one that created the wrap. */
+  verifiedAt?: string;
+}
+
+function wrapFor(
   publicKey: string,
-  now: Date = new Date(),
+  dataKey: Uint8Array,
+  input: WrapInput,
+  now: Date,
 ): WebIdentityWrap {
-  const kek = deriveKeyEncryptionKey(prfOutput, credentialId);
+  const kek = deriveKeyEncryptionKey(input.prfOutput, input.credentialId);
   try {
-    const { nonce, ciphertext } = encryptAead(kek, dataKey, wrapAad(publicKey, credentialId));
+    const { nonce, ciphertext } = encryptAead(kek, dataKey, wrapAad(publicKey, input.credentialId, input.rpId));
     return {
-      credentialId,
+      credentialId: input.credentialId,
       nonce: bytesToHex(nonce),
       wrappedKey: bytesToHex(ciphertext),
       createdAt: now.toISOString(),
+      rpId: input.rpId,
+      ...(input.verifiedAt ? { verifiedAt: input.verifiedAt } : {}),
     };
   } finally {
     wipeBytes(kek);
   }
 }
 
+function secretOf(identity: OpenedWebIdentity): { kind: WebIdentitySecretKind; bytes: Uint8Array } {
+  if (identity.kind === 'mnemonic') {
+    return { kind: 'mnemonic-entropy', bytes: mnemonicToEntropy(identity.mnemonic, wordlist) };
+  }
+  return { kind: 'raw-private-key', bytes: hexToBytes(identity.privateKey) };
+}
+
 /**
  * Seal an identity into a new envelope that opens with the given passkey.
  *
@@ -164,29 +253,37 @@ export function wrapDataKey(
  * session; wipe it when done.
  */
 export function sealWebIdentity(
-  identity: Pick<OpenedWebIdentity, 'mnemonic' | 'publicKey'>,
-  firstWrap: { prfOutput: Uint8Array; credentialId: string },
+  identity: OpenedWebIdentity,
+  firstWrap: WrapInput,
   now: Date = new Date(),
 ): { envelope: WebIdentityEnvelope; dataKey: Uint8Array } {
-  const derived = deriveIdentityFromMnemonic(identity.mnemonic);
-  if (derived.publicKey !== identity.publicKey.toLowerCase()) {
-    throw new Error('The recovery phrase does not belong to this identity');
+  const derived: OpenedWebIdentity =
+    identity.kind === 'raw-key' ? deriveIdentityFromPrivateKey(identity.privateKey) : deriveIdentityFromMnemonic(identity.mnemonic);
+  const publicKey = identity.publicKey.toLowerCase();
+  if (derived.publicKey !== publicKey) {
+    wipeOpenedIdentity(derived);
+    throw new Error('The recovery material does not belong to this identity');
   }
+  const secret = secretOf(derived);
+  wipeOpenedIdentity(derived);
   const dataKey = generateDataKey();
-  const entropy = mnemonicToEntropy(derived.mnemonic, wordlist);
   try {
-    const { nonce, ciphertext } = encryptAead(dataKey, entropy, entropyAad(derived.publicKey));
+    const { nonce, ciphertext } = encryptAead(dataKey, secret.bytes, secretAad(publicKey, secret.kind));
     const envelope: WebIdentityEnvelope = {
       version: WEB_IDENTITY_ENVELOPE_VERSION,
       algorithm: 'xchacha20poly1305',
-      publicKey: derived.publicKey,
-      entropyNonce: bytesToHex(nonce),
-      sealedEntropy: bytesToHex(ciphertext),
-      wraps: [wrapDataKey(dataKey, firstWrap.prfOutput, firstWrap.credentialId, derived.publicKey, now)],
+      publicKey,
+      secretKind: secret.kind,
+      secretNonce: bytesToHex(nonce),
+      sealedSecret: bytesToHex(ciphertext),
+      wraps: [wrapFor(publicKey, dataKey, firstWrap, now)],
     };
     return { envelope, dataKey };
+  } catch (error) {
+    wipeBytes(dataKey);
+    throw error;
   } finally {
-    wipeBytes(entropy);
+    wipeBytes(secret.bytes);
   }
 }
 
@@ -202,7 +299,7 @@ export function unwrapDataKey(
   }
   const kek = deriveKeyEncryptionKey(prfOutput, credentialId);
   try {
-    return decryptAead(kek, hexToBytes(wrap.nonce), hexToBytes(wrap.wrappedKey), wrapAad(envelope.publicKey, credentialId));
+    return decryptAead(kek, hexToBytes(wrap.nonce), hexToBytes(wrap.wrappedKey), wrapAad(envelope.publicKey, credentialId, wrap.rpId));
   } catch {
     throw new WebIdentityUnlockError('prf-mismatch', 'This passkey returned a different secret than when it was registered');
   } finally {
@@ -213,29 +310,35 @@ export function unwrapDataKey(
 /**
  * Open an envelope with its data key.
  *
- * The derived public key is checked against the envelope's own: a sealed entropy
+ * The derived public key is checked against the envelope's own: a sealed secret
  * that decrypts into a different identity is treated as corruption, never used.
  */
 export function openWebIdentity(envelope: WebIdentityEnvelope, dataKey: Uint8Array): OpenedWebIdentity {
-  let entropy: Uint8Array;
+  const publicKey = envelope.publicKey.toLowerCase();
+  const kind = envelope.secretKind;
+  let secret: Uint8Array;
   try {
-    entropy = decryptAead(
-      dataKey,
-      hexToBytes(envelope.entropyNonce),
-      hexToBytes(envelope.sealedEntropy),
-      entropyAad(envelope.publicKey),
-    );
+    secret = decryptAead(dataKey, hexToBytes(envelope.secretNonce), hexToBytes(envelope.sealedSecret), secretAad(envelope.publicKey, kind));
   } catch {
     throw new WebIdentityUnlockError('corrupt', 'The sealed identity could not be opened');
   }
   try {
-    const identity = deriveIdentityFromMnemonic(entropyToMnemonic(entropy, wordlist));
-    if (identity.publicKey !== envelope.publicKey.toLowerCase()) {
+    let identity: OpenedWebIdentity;
+    try {
+      identity =
+        kind === 'mnemonic-entropy'
+          ? deriveIdentityFromMnemonic(entropyToMnemonic(secret, wordlist))
+          : deriveIdentityFromPrivateKey(bytesToHex(secret));
+    } catch {
+      throw new WebIdentityUnlockError('corrupt', 'The sealed identity is malformed');
+    }
+    if (identity.publicKey !== publicKey) {
+      wipeOpenedIdentity(identity);
       throw new WebIdentityUnlockError('corrupt', 'The sealed identity does not match its public key');
     }
     return identity;
   } finally {
-    wipeBytes(entropy);
+    wipeBytes(secret);
   }
 }
 
@@ -254,19 +357,30 @@ export function unlockWebIdentity(
 }
 
 /** Add (or replace) one passkey's wrap. Requires the data key of an unlocked envelope. */
-export function addWrap(
-  envelope: WebIdentityEnvelope,
-  dataKey: Uint8Array,
-  prfOutput: Uint8Array,
-  credentialId: string,
-  now: Date = new Date(),
-): WebIdentityEnvelope {
+export function addWrap(envelope: WebIdentityEnvelope, dataKey: Uint8Array, wrapInput: WrapInput, now: Date = new Date()): WebIdentityEnvelope {
   // Proves `dataKey` belongs to THIS envelope before anything new can open it.
-  openWebIdentity(envelope, dataKey);
-  const others = envelope.wraps.filter((entry) => entry.credentialId !== credentialId);
+  wipeOpenedIdentity(openWebIdentity(envelope, dataKey));
+  const others = envelope.wraps.filter((entry) => entry.credentialId !== wrapInput.credentialId);
   return {
     ...envelope,
-    wraps: [...others, wrapDataKey(dataKey, prfOutput, credentialId, envelope.publicKey, now)],
+    wraps: [...others, wrapFor(envelope.publicKey, dataKey, wrapInput, now)],
+  };
+}
+
+/**
+ * Record that a wrap's passkey opened the envelope in a ceremony of its own. The
+ * AEAD does not cover `verifiedAt`; it is holder metadata the owner writes with a
+ * root proof, not a cryptographic claim.
+ */
+export function markWrapVerified(envelope: WebIdentityEnvelope, credentialId: string, now: Date = new Date()): WebIdentityEnvelope {
+  if (!envelope.wraps.some((entry) => entry.credentialId === credentialId)) {
+    throw new WebIdentityUnlockError('unknown-credential', 'This passkey cannot open this identity');
+  }
+  return {
+    ...envelope,
+    wraps: envelope.wraps.map((entry) =>
+      entry.credentialId === credentialId ? { ...entry, verifiedAt: now.toISOString() } : entry,
+    ),
   };
 }
 
@@ -278,49 +392,3 @@ export function removeWrap(envelope: WebIdentityEnvelope, credentialId: string):
   }
   return { ...envelope, wraps: remaining };
 }
-
-/**
- * The message an identity key signs to authorize an account action
- * (`link_identity`, `web_envelope_delete`, …): `JSON.stringify({ action, userId,
- * timestamp })`, byte-identical to what the API reconstructs.
- */
-export function buildIdentityActionMessage(action: string, userId: string, timestamp: number): string {
-  return JSON.stringify({ action, userId, timestamp });
-}
-
-/** Sign an identity-action message with an opened identity's key. */
-export async function signIdentityAction(
-  identity: Pick<OpenedWebIdentity, 'privateKey'>,
-  action: string,
-  userId: string,
-  timestamp: number = Date.now(),
-): Promise<{ signature: string; timestamp: number }> {
-  const signature = await signMessage(buildIdentityActionMessage(action, userId, timestamp), identity.privateKey);
-  return { signature, timestamp };
-}
-
-/**
- * The 6-digit short authentication string both sides of an identity transfer show.
- *
- * Bound to the pairing and to BOTH ephemeral public keys in their roles, so a relay
- * that substitutes either key produces a different code on each screen. The user
- * comparing the two codes is what makes the transfer safe against the relay itself.
- */
-export function deriveTransferSas(input: {
-  pairingId: string;
-  initiatorEphemeralPublicKey: string;
-  responderEphemeralPublicKey: string;
-}): string {
-  const digest = sha256(
-    utf8ToBytes(
-      JSON.stringify({
-        v: 'oxy-identity-transfer-sas-v1',
-        pairingId: input.pairingId.toLowerCase(),
-        initiator: input.initiatorEphemeralPublicKey.toLowerCase(),
-        responder: input.responderEphemeralPublicKey.toLowerCase(),
-      }),
-    ),
-  );
-  const value = ((digest[0] << 24) | (digest[1] << 16) | (digest[2] << 8) | digest[3]) >>> 0;
-  return String(value % 1_000_000).padStart(6, '0');
-}