@oxy.so/core 1.5.1 → 1.6.0

package/dist/cjs/HttpService.js

@@ -83,6 +83,33 @@ const TOKEN_REFRESH_COOLDOWN_MS = 15000;
  * ~15× faster without weakening the storm guard.
  */
 const EXPIRED_TOKEN_REFRESH_COOLDOWN_MS = 1000;
+/**
+ * Cooldown (ms) applied after the refresh endpoint answered 429 Too Many
+ * Requests. Overrides BOTH cooldowns above, because neither of them is about
+ * this failure.
+ *
+ * The other two ask "is the current token still usable?" and answer a server
+ * that is unreachable or erroring. A 429 is the opposite situation: the server
+ * is perfectly reachable and is telling this client, specifically, that it is
+ * asking too often. `EXPIRED_TOKEN_REFRESH_COOLDOWN_MS` then becomes actively
+ * harmful — an expired token drives the request-time preflight and the 401
+ * retry lanes at one mint per second (60/min) against a mint budget of 30/min,
+ * so the client's own retries hold the limiter tripped and it can never fall
+ * back under the ceiling. The limit stops being self-clearing and becomes
+ * self-sustaining for as long as the app keeps issuing requests.
+ *
+ * Sized to the mint limiter's own window (60s, `packages/api/src/routes/sessionDevice.ts`)
+ * so ONE attempt lands per window: enough to discover the moment the budget has
+ * drained, never enough to consume it. The per-device lockout answers 429 for
+ * far longer (15 min), and that is fine — one probe a minute against it is
+ * negligible traffic and the session recovers the instant the lockout lifts.
+ *
+ * NOT routed through the scheduler's exponential backoff: that backoff is
+ * effect-local to `startTokenRefreshScheduler` and governs only the scheduled
+ * lane, while the lanes that actually produce the storm here (preflight, 401
+ * retry) are request-driven and are throttled solely by this cooldown.
+ */
+const RATE_LIMITED_REFRESH_COOLDOWN_MS = 60000;
 /**
  * Lead time (seconds) before access-token expiry at which a preflight refresh
  * is triggered. A token within this window of `exp` is treated as effectively
@@ -164,6 +191,17 @@ class HttpService {
          * fixed deadline that could not shrink once the token expired mid-cooldown.
          */
         this.lastRefreshFailureAt = 0;
+        /**
+         * Whether the last refresh failure was the server answering 429. Selects
+         * {@link RATE_LIMITED_REFRESH_COOLDOWN_MS} over the two token-state cooldowns
+         * for the NEXT attempt, and is cleared by any success or any other failure.
+         *
+         * A boolean beside {@link lastRefreshFailureAt} rather than a stored deadline,
+         * for the same reason that field gives: the cooldown stays a function of the
+         * current state, so it can still shorten if the situation changes underneath
+         * it, and there is exactly one timestamp to reason about.
+         */
+        this.lastRefreshWasRateLimited = false;
         this.authRefreshHandler = null;
         this.accessTokenProvider = null;
         this.deviceSecretMintInFlight = null;
@@ -887,19 +925,28 @@ class HttpService {
         if (!this.authRefreshHandler) {
             return null;
         }
-        // Post-failure cooldown. A genuinely EXPIRED current token uses a much
-        // shorter cooldown than a still-valid (proactive, near-expiry) one: an
-        // expired token is unusable, so re-mint as soon as the endpoint is reachable
-        // again rather than waiting out the full window while requests carry a stale
-        // bearer. Both cooldowns are measured from the last failure, so the moment a
-        // still-valid token crosses `exp` mid-cooldown the shorter window applies.
-        const cooldownMs = this.isAccessTokenExpired()
-            ? EXPIRED_TOKEN_REFRESH_COOLDOWN_MS
-            : TOKEN_REFRESH_COOLDOWN_MS;
+        // Post-failure cooldown. A 429 names its own window regardless of token
+        // state — the server is reachable and is rationing this client, so retrying
+        // at the expired-token rate would spend the very budget being waited on.
+        // Otherwise a genuinely EXPIRED current token uses a much shorter cooldown
+        // than a still-valid (proactive, near-expiry) one: an expired token is
+        // unusable, so re-mint as soon as the endpoint is reachable again rather
+        // than waiting out the full window while requests carry a stale bearer. All
+        // three are measured from the last failure, so the moment a still-valid
+        // token crosses `exp` mid-cooldown the shorter window applies.
+        const cooldownMs = this.lastRefreshWasRateLimited
+            ? RATE_LIMITED_REFRESH_COOLDOWN_MS
+            : this.isAccessTokenExpired()
+                ? EXPIRED_TOKEN_REFRESH_COOLDOWN_MS
+                : TOKEN_REFRESH_COOLDOWN_MS;
         if (Date.now() - this.lastRefreshFailureAt < cooldownMs) {
             return null;
         }
         if (!this.tokenRefreshPromise) {
+            // Cleared before the attempt, never after it: the handler reports a 429
+            // by calling `noteRefreshRateLimited()` from INSIDE this call, so clearing
+            // on the way out would discard the flag it just set.
+            this.lastRefreshWasRateLimited = false;
             this.tokenRefreshPromise = this.authRefreshHandler(reason)
                 .then((newToken) => {
                 if (!newToken) {
@@ -913,6 +960,7 @@ class HttpService {
                 // A success clears the failure timestamp so the next refresh is never
                 // throttled by a stale cooldown.
                 this.lastRefreshFailureAt = 0;
+                this.lastRefreshWasRateLimited = false;
                 this.logger.debug('Token refreshed via the auth refresh handler');
                 return newToken;
             })
@@ -927,6 +975,21 @@ class HttpService {
         }
         return this.tokenRefreshPromise;
     }
+    /**
+     * Report that the refresh/mint endpoint answered 429 Too Many Requests, so the
+     * next attempt waits {@link RATE_LIMITED_REFRESH_COOLDOWN_MS} instead of one of
+     * the token-state cooldowns.
+     *
+     * Called by the refresh handler (`refreshDeviceSecretArm`) from inside the
+     * `authRefreshHandler` call, because the handler's `Promise<string | null>`
+     * contract cannot carry WHY a refresh failed and 429 is the one failure whose
+     * correct retry interval is set by the server rather than by the token.
+     *
+     * Public because the handler lives in `session/refresh.ts`, not on this class.
+     */
+    noteRefreshRateLimited() {
+        this.lastRefreshWasRateLimited = true;
+    }
     /**
      * Whether the CURRENT stored access token is already past its `exp`. Drives
      * the shorter post-failure refresh cooldown ({@link EXPIRED_TOKEN_REFRESH_COOLDOWN_MS}):

package/dist/cjs/crypto/identityMove.js

@@ -1,29 +1,34 @@
 "use strict";
 /**
- * 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`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.IDENTITY_MOVE_ACTIONS = void 0;
 exports.generateMoveEphemeralKeyPair = generateMoveEphemeralKeyPair;
 exports.deriveMoveKey = deriveMoveKey;
+exports.createMoveCommitment = createMoveCommitment;
+exports.verifyMoveCommitment = verifyMoveCommitment;
 exports.deriveMoveSas = deriveMoveSas;
+exports.digestMoveCiphertext = digestMoveCiphertext;
+exports.signMoveReceipt = signMoveReceipt;
+exports.verifyMoveReceipt = verifyMoveReceipt;
 exports.sealIdentityForMove = sealIdentityForMove;
 exports.openMovedIdentity = openMovedIdentity;
-exports.buildMoveMessage = buildMoveMessage;
-exports.signMoveAction = signMoveAction;
-exports.verifyMoveReceipt = verifyMoveReceipt;
 exports.buildMoveQrPayload = buildMoveQrPayload;
 exports.parseMoveQrPayload = parseMoveQrPayload;
 require("./polyfill");
 const bip39_1 = require("@scure/bip39");
 const english_1 = require("@scure/bip39/wordlists/english");
+const sha256_1 = require("@noble/hashes/sha256");
 const utils_1 = require("@noble/hashes/utils");
 const protocol_1 = require("@oxy.so/protocol");
 const secp256k1_1 = require("@oxy.so/protocol/secp256k1");
@@ -33,11 +38,9 @@ const ecdh_1 = require("./ecdh");
 const kdf_1 = require("./kdf");
 const webIdentityCarrier_1 = require("./webIdentityCarrier");
 const MOVE_KDF_INFO = (0, utils_1.utf8ToBytes)('oxy-identity-move-v1');
-/** Actions the identity key signs during a move. */
-exports.IDENTITY_MOVE_ACTIONS = {
-    seal: 'identity_move_seal',
-    received: 'identity_move_received',
-};
+function sha256Hex(input) {
+    return (0, utils_1.bytesToHex)((0, sha256_1.sha256)((0, utils_1.utf8ToBytes)(input)));
+}
 /** A fresh ephemeral key pair for one move. Keep the private key in memory only. */
 function generateMoveEphemeralKeyPair() {
     return (0, secp256k1_1.generateSecp256k1KeyPair)();
@@ -52,15 +55,47 @@ function deriveMoveKey(ownEphemeralPrivateKey, otherEphemeralPublicKey, moveId)
         (0, webIdentityCarrier_1.wipeBytes)(shared);
     }
 }
-/** The 6-digit code both screens show, bound to the move and both ephemeral keys in their roles. */
-function deriveMoveSas(moveId, initiatorEphemeralPublicKey, responderEphemeralPublicKey) {
-    return (0, webIdentityCarrier_1.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. */
+function createMoveCommitment(initiatorEphemeralPublicKey) {
+    const nonceBytes = new Uint8Array(32);
+    globalThis.crypto.getRandomValues(nonceBytes);
+    const nonce = (0, utils_1.bytesToHex)(nonceBytes);
+    return { commitment: sha256Hex((0, contracts_1.buildMoveCommitmentInput)(initiatorEphemeralPublicKey, nonce)), nonce };
+}
+/** Responder: does the revealed key match the commitment read before joining? */
+function verifyMoveCommitment(initiatorEphemeralPublicKey, nonce, commitment) {
+    return sha256Hex((0, contracts_1.buildMoveCommitmentInput)(initiatorEphemeralPublicKey, nonce)) === commitment.toLowerCase();
+}
+/** The 6-digit code, bound to the move, both keys in their roles, and the commitment. */
+function deriveMoveSas(input) {
+    const digest = (0, sha256_1.sha256)((0, utils_1.utf8ToBytes)((0, contracts_1.buildMoveSasInput)(input)));
+    const value = ((digest[0] << 24) | (digest[1] << 16) | (digest[2] << 8) | digest[3]) >>> 0;
+    return String(value % 1000000).padStart(6, '0');
+}
+/** The digest a receipt binds: what was actually relayed. */
+function digestMoveCiphertext(sealed) {
+    return sha256Hex((0, contracts_1.buildMoveCiphertextDigestInput)(sealed));
+}
+/**
+ * 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.
+ */
+async function signMoveReceipt(sign, claims) {
+    return { signature: await sign((0, contracts_1.buildMoveReceiptMessage)(claims)) };
+}
+/** Initiator: is this receipt the root's, for exactly this move and ciphertext? */
+function verifyMoveReceipt(claims, signature) {
+    return (0, protocol_1.verifySignature)((0, contracts_1.buildMoveReceiptMessage)(claims), signature, claims.rootPublicKey);
 }
 function moveAad(moveId, publicKey) {
     return (0, utils_1.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. */
 function sealIdentityForMove(identity, moveKey, moveId) {
+    if (typeof identity.mnemonic !== 'string' || !identity.mnemonic) {
+        throw new Error('Only an identity with a recovery phrase can be moved this way');
+    }
     const entropy = (0, bip39_1.mnemonicToEntropy)(identity.mnemonic, english_1.wordlist);
     try {
         const { nonce, ciphertext } = (0, aead_1.encryptAead)(moveKey, entropy, moveAad(moveId, identity.publicKey));
@@ -93,22 +128,6 @@ function openMovedIdentity(sealed, moveKey, moveId, expectedPublicKey) {
         (0, webIdentityCarrier_1.wipeBytes)(entropy);
     }
 }
-/** The exact bytes a move proof or receipt signs. */
-function buildMoveMessage(action, moveId, timestamp) {
-    return JSON.stringify({ action, moveId: moveId.toLowerCase(), timestamp });
-}
-/** Sign a move action with the identity key. */
-async function signMoveAction(identity, action, moveId, timestamp = Date.now()) {
-    return { signature: await (0, protocol_1.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.
- */
-function verifyMoveReceipt(publicKey, moveId, receipt) {
-    return (0, protocol_1.verifySignature)(buildMoveMessage(exports.IDENTITY_MOVE_ACTIONS.received, moveId, receipt.timestamp), receipt.signature, publicKey);
-}
 /** The QR payload for a move. */
 function buildMoveQrPayload(moveId) {
     return `${contracts_1.IDENTITY_MOVE_QR_PREFIX}${moveId.toLowerCase()}`;

package/dist/cjs/crypto/identityProof.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.digestIdentityPayload = digestIdentityPayload;
+exports.signIdentityProof = signIdentityProof;
+require("./polyfill");
+const sha256_1 = require("@noble/hashes/sha256");
+const utils_1 = require("@noble/hashes/utils");
+const protocol_1 = require("@oxy.so/protocol");
+const contracts_1 = require("@oxy.so/contracts");
+/** SHA-256 hex of the canonical JSON of `payload` — the `payloadDigest` claim. */
+function digestIdentityPayload(payload) {
+    return (0, utils_1.bytesToHex)((0, sha256_1.sha256)((0, utils_1.utf8ToBytes)((0, contracts_1.canonicalJson)(payload))));
+}
+/** Sign `claims` with the root, producing the proof as it travels. */
+async function signIdentityProof(identity, claims) {
+    if (claims.rootPublicKey !== identity.publicKey.toLowerCase()) {
+        throw new Error('identity proof: the claims name a different root');
+    }
+    const signature = await (0, protocol_1.signMessage)((0, contracts_1.buildIdentityProofMessage)(claims), identity.privateKey);
+    return { v: contracts_1.IDENTITY_PROOF_VERSION, challenge: claims.challenge, expiresAt: claims.expiresAt, signature };
+}

package/dist/cjs/crypto/webIdentityCarrier.js

@@ -1,19 +1,19 @@
 "use strict";
 /**
- * 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
@@ -23,28 +23,30 @@
  * Contract: `WebIdentityEnvelope` in `@oxy.so/contracts`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WebIdentityUnlockError = exports.WEB_IDENTITY_PRF_INPUT = void 0;
+exports.WebIdentityUnlockError = exports.WEB_IDENTITY_PRF_OUTPUT_LENGTH = exports.WEB_IDENTITY_PRF_INPUT = void 0;
 exports.wipeBytes = wipeBytes;
+exports.wipeOpenedIdentity = wipeOpenedIdentity;
+exports.normalizeMnemonic = normalizeMnemonic;
 exports.deriveIdentityFromMnemonic = deriveIdentityFromMnemonic;
+exports.deriveIdentityFromPrivateKey = deriveIdentityFromPrivateKey;
+exports.parseRecoveryMaterial = parseRecoveryMaterial;
+exports.deriveIdentityFromRecoveryMaterial = deriveIdentityFromRecoveryMaterial;
 exports.generateWebIdentity = generateWebIdentity;
 exports.generateDataKey = generateDataKey;
+exports.isUsablePrfOutput = isUsablePrfOutput;
 exports.deriveKeyEncryptionKey = deriveKeyEncryptionKey;
-exports.wrapDataKey = wrapDataKey;
 exports.sealWebIdentity = sealWebIdentity;
 exports.unwrapDataKey = unwrapDataKey;
 exports.openWebIdentity = openWebIdentity;
 exports.unlockWebIdentity = unlockWebIdentity;
 exports.addWrap = addWrap;
+exports.markWrapVerified = markWrapVerified;
 exports.removeWrap = removeWrap;
-exports.buildIdentityActionMessage = buildIdentityActionMessage;
-exports.signIdentityAction = signIdentityAction;
-exports.deriveTransferSas = deriveTransferSas;
 require("./polyfill");
 const bip39_1 = require("@scure/bip39");
 const english_1 = require("@scure/bip39/wordlists/english");
 const sha256_1 = require("@noble/hashes/sha256");
 const utils_1 = require("@noble/hashes/utils");
-const protocol_1 = require("@oxy.so/protocol");
 const secp256k1_1 = require("@oxy.so/protocol/secp256k1");
 const contracts_1 = require("@oxy.so/contracts");
 const aead_1 = require("./aead");
@@ -57,10 +59,10 @@ const kdf_1 = require("./kdf");
  * scheme change bumps the label — and with it every KEK — instead of mutating it.
  */
 exports.WEB_IDENTITY_PRF_INPUT = (0, sha256_1.sha256)((0, utils_1.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 = (0, utils_1.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. */
+exports.WEB_IDENTITY_PRF_OUTPUT_LENGTH = 32;
 class WebIdentityUnlockError extends Error {
     constructor(failure, message) {
         super(message);
@@ -72,22 +74,34 @@ exports.WebIdentityUnlockError = WebIdentityUnlockError;
 function aadFor(parts) {
     return (0, utils_1.utf8ToBytes)(JSON.stringify(parts));
 }
-function entropyAad(publicKey) {
-    return aadFor({ v: contracts_1.WEB_IDENTITY_ENVELOPE_VERSION, purpose: 'entropy', publicKey });
+function secretAad(publicKey, secretKind) {
+    return aadFor({ v: contracts_1.WEB_IDENTITY_ENVELOPE_VERSION, purpose: 'secret', secretKind, publicKey });
 }
-function wrapAad(publicKey, credentialId) {
-    return aadFor({ v: contracts_1.WEB_IDENTITY_ENVELOPE_VERSION, purpose: 'wrap', publicKey, credentialId });
+function wrapAad(publicKey, credentialId, rpId) {
+    return aadFor({ v: contracts_1.WEB_IDENTITY_ENVELOPE_VERSION, purpose: 'wrap', publicKey, credentialId, rpId });
 }
 /** Overwrite a buffer holding secret material. Best effort — JS gives no stronger guarantee. */
 function wipeBytes(bytes) {
     bytes.fill(0);
 }
+/** Best-effort removal of secret strings from an opened identity. */
+function wipeOpenedIdentity(identity) {
+    identity.privateKey = '';
+    if (identity.kind === 'mnemonic')
+        identity.mnemonic = '';
+}
+/** Normalize a typed phrase: trimmed, lowercase, single spaces. */
+function normalizeMnemonic(mnemonic) {
+    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.
  */
 function deriveIdentityFromMnemonic(mnemonic) {
-    const normalized = mnemonic.trim().toLowerCase().split(/\s+/).join(' ');
+    const normalized = normalizeMnemonic(mnemonic);
     if (!(0, bip39_1.validateMnemonic)(normalized, english_1.wordlist)) {
         throw new Error('Invalid recovery phrase');
     }
@@ -96,7 +110,41 @@ function deriveIdentityFromMnemonic(mnemonic) {
     wipeBytes(seed);
     const privateKey = (0, utils_1.bytesToHex)(privateKeyBytes);
     wipeBytes(privateKeyBytes);
-    return { mnemonic: normalized, privateKey, publicKey: (0, secp256k1_1.deriveSecp256k1PublicKey)(privateKey) };
+    return { kind: 'mnemonic', mnemonic: normalized, privateKey, publicKey: (0, secp256k1_1.deriveSecp256k1PublicKey)(privateKey) };
+}
+/** A raw 32-byte private key (hex, optional `0x`) as an identity. Never gains a phrase. */
+function deriveIdentityFromPrivateKey(privateKey) {
+    const normalized = privateKey.trim().toLowerCase().replace(/^0x/, '');
+    if (!/^[0-9a-f]{64}$/.test(normalized)) {
+        throw new Error('Invalid private key');
+    }
+    let publicKey;
+    try {
+        publicKey = (0, secp256k1_1.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.
+ */
+function parseRecoveryMaterial(input) {
+    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 && (0, bip39_1.validateMnemonic)(words, english_1.wordlist))
+        return { kind: 'mnemonic', mnemonic: words };
+    throw new Error('Invalid recovery material');
+}
+/** Derive the identity recovery material names. */
+function deriveIdentityFromRecoveryMaterial(material) {
+    return material.kind === 'mnemonic'
+        ? deriveIdentityFromMnemonic(material.mnemonic)
+        : deriveIdentityFromPrivateKey(material.privateKey);
 }
 /** A brand-new 12-word identity. Nothing is persisted. */
 function generateWebIdentity() {
@@ -108,29 +156,40 @@ function generateDataKey() {
     globalThis.crypto.getRandomValues(key);
     return key;
 }
+/** Whether `bytes` is a usable PRF output: exactly 32 bytes. */
+function isUsablePrfOutput(bytes) {
+    return bytes instanceof Uint8Array && bytes.byteLength === exports.WEB_IDENTITY_PRF_OUTPUT_LENGTH;
+}
 /** The key-encryption key a passkey's PRF output yields for its own wrap. */
 function deriveKeyEncryptionKey(prfOutput, credentialId) {
-    if (prfOutput.length !== PRF_OUTPUT_LENGTH) {
-        throw new Error(`PRF output must be ${PRF_OUTPUT_LENGTH} bytes, got ${prfOutput.length}`);
+    if (prfOutput.length !== exports.WEB_IDENTITY_PRF_OUTPUT_LENGTH) {
+        throw new Error(`PRF output must be ${exports.WEB_IDENTITY_PRF_OUTPUT_LENGTH} bytes, got ${prfOutput.length}`);
     }
     return (0, kdf_1.hkdfSha256)(prfOutput, KEK_SALT, (0, utils_1.utf8ToBytes)(credentialId), aead_1.AEAD_KEY_LENGTH);
 }
-/** Wrap `dataKey` for one passkey. */
-function wrapDataKey(dataKey, prfOutput, credentialId, publicKey, now = new Date()) {
-    const kek = deriveKeyEncryptionKey(prfOutput, credentialId);
+function wrapFor(publicKey, dataKey, input, now) {
+    const kek = deriveKeyEncryptionKey(input.prfOutput, input.credentialId);
     try {
-        const { nonce, ciphertext } = (0, aead_1.encryptAead)(kek, dataKey, wrapAad(publicKey, credentialId));
+        const { nonce, ciphertext } = (0, aead_1.encryptAead)(kek, dataKey, wrapAad(publicKey, input.credentialId, input.rpId));
         return {
-            credentialId,
+            credentialId: input.credentialId,
             nonce: (0, utils_1.bytesToHex)(nonce),
             wrappedKey: (0, utils_1.bytesToHex)(ciphertext),
             createdAt: now.toISOString(),
+            rpId: input.rpId,
+            ...(input.verifiedAt ? { verifiedAt: input.verifiedAt } : {}),
         };
     }
     finally {
         wipeBytes(kek);
     }
 }
+function secretOf(identity) {
+    if (identity.kind === 'mnemonic') {
+        return { kind: 'mnemonic-entropy', bytes: (0, bip39_1.mnemonicToEntropy)(identity.mnemonic, english_1.wordlist) };
+    }
+    return { kind: 'raw-private-key', bytes: (0, utils_1.hexToBytes)(identity.privateKey) };
+}
 /**
  * Seal an identity into a new envelope that opens with the given passkey.
  *
@@ -138,26 +197,34 @@ function wrapDataKey(dataKey, prfOutput, credentialId, publicKey, now = new Date
  * session; wipe it when done.
  */
 function sealWebIdentity(identity, firstWrap, now = new Date()) {
-    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 = 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 = (0, bip39_1.mnemonicToEntropy)(derived.mnemonic, english_1.wordlist);
     try {
-        const { nonce, ciphertext } = (0, aead_1.encryptAead)(dataKey, entropy, entropyAad(derived.publicKey));
+        const { nonce, ciphertext } = (0, aead_1.encryptAead)(dataKey, secret.bytes, secretAad(publicKey, secret.kind));
         const envelope = {
             version: contracts_1.WEB_IDENTITY_ENVELOPE_VERSION,
             algorithm: 'xchacha20poly1305',
-            publicKey: derived.publicKey,
-            entropyNonce: (0, utils_1.bytesToHex)(nonce),
-            sealedEntropy: (0, utils_1.bytesToHex)(ciphertext),
-            wraps: [wrapDataKey(dataKey, firstWrap.prfOutput, firstWrap.credentialId, derived.publicKey, now)],
+            publicKey,
+            secretKind: secret.kind,
+            secretNonce: (0, utils_1.bytesToHex)(nonce),
+            sealedSecret: (0, utils_1.bytesToHex)(ciphertext),
+            wraps: [wrapFor(publicKey, dataKey, firstWrap, now)],
         };
         return { envelope, dataKey };
     }
+    catch (error) {
+        wipeBytes(dataKey);
+        throw error;
+    }
     finally {
-        wipeBytes(entropy);
+        wipeBytes(secret.bytes);
     }
 }
 /** Recover the data key with one passkey's PRF output. */
@@ -168,7 +235,7 @@ function unwrapDataKey(envelope, prfOutput, credentialId) {
     }
     const kek = deriveKeyEncryptionKey(prfOutput, credentialId);
     try {
-        return (0, aead_1.decryptAead)(kek, (0, utils_1.hexToBytes)(wrap.nonce), (0, utils_1.hexToBytes)(wrap.wrappedKey), wrapAad(envelope.publicKey, credentialId));
+        return (0, aead_1.decryptAead)(kek, (0, utils_1.hexToBytes)(wrap.nonce), (0, utils_1.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');
@@ -180,26 +247,38 @@ function unwrapDataKey(envelope, prfOutput, credentialId) {
 /**
  * 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.
  */
 function openWebIdentity(envelope, dataKey) {
-    let entropy;
+    const publicKey = envelope.publicKey.toLowerCase();
+    const kind = envelope.secretKind;
+    let secret;
     try {
-        entropy = (0, aead_1.decryptAead)(dataKey, (0, utils_1.hexToBytes)(envelope.entropyNonce), (0, utils_1.hexToBytes)(envelope.sealedEntropy), entropyAad(envelope.publicKey));
+        secret = (0, aead_1.decryptAead)(dataKey, (0, utils_1.hexToBytes)(envelope.secretNonce), (0, utils_1.hexToBytes)(envelope.sealedSecret), secretAad(envelope.publicKey, kind));
     }
     catch {
         throw new WebIdentityUnlockError('corrupt', 'The sealed identity could not be opened');
     }
     try {
-        const identity = deriveIdentityFromMnemonic((0, bip39_1.entropyToMnemonic)(entropy, english_1.wordlist));
-        if (identity.publicKey !== envelope.publicKey.toLowerCase()) {
+        let identity;
+        try {
+            identity =
+                kind === 'mnemonic-entropy'
+                    ? deriveIdentityFromMnemonic((0, bip39_1.entropyToMnemonic)(secret, english_1.wordlist))
+                    : deriveIdentityFromPrivateKey((0, utils_1.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);
     }
 }
 /** Unwrap and open in one step. */
@@ -213,13 +292,27 @@ function unlockWebIdentity(envelope, prfOutput, credentialId) {
     }
 }
 /** Add (or replace) one passkey's wrap. Requires the data key of an unlocked envelope. */
-function addWrap(envelope, dataKey, prfOutput, credentialId, now = new Date()) {
+function addWrap(envelope, dataKey, wrapInput, now = new Date()) {
     // 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, 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.
+ */
+function markWrapVerified(envelope, credentialId, now = new Date()) {
+    if (!envelope.wraps.some((entry) => entry.credentialId === credentialId)) {
+        throw new WebIdentityUnlockError('unknown-credential', 'This passkey cannot open this identity');
+    }
     return {
         ...envelope,
-        wraps: [...others, wrapDataKey(dataKey, prfOutput, credentialId, envelope.publicKey, now)],
+        wraps: envelope.wraps.map((entry) => entry.credentialId === credentialId ? { ...entry, verifiedAt: now.toISOString() } : entry),
     };
 }
 /** Remove one passkey's wrap. The last wrap can never be removed — an envelope nobody can open is a loss. */
@@ -230,33 +323,3 @@ function removeWrap(envelope, credentialId) {
     }
     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.
- */
-function buildIdentityActionMessage(action, userId, timestamp) {
-    return JSON.stringify({ action, userId, timestamp });
-}
-/** Sign an identity-action message with an opened identity's key. */
-async function signIdentityAction(identity, action, userId, timestamp = Date.now()) {
-    const signature = await (0, protocol_1.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.
- */
-function deriveTransferSas(input) {
-    const digest = (0, sha256_1.sha256)((0, utils_1.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 % 1000000).padStart(6, '0');
-}