@oxy.so/core 1.5.1 → 1.6.0

package/dist/esm/HttpService.js

@@ -80,6 +80,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
@@ -161,6 +188,17 @@ export 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;
@@ -884,19 +922,28 @@ export 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) {
@@ -910,6 +957,7 @@ export 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;
             })
@@ -924,6 +972,21 @@ export 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/esm/crypto/identityMove.js

@@ -1,30 +1,32 @@
 /**
- * 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`.
  */
 import './polyfill.js';
 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.js';
 import { deriveSharedSecret } from './ecdh.js';
 import { hkdfSha256 } from './kdf.js';
-import { deriveIdentityFromMnemonic, deriveTransferSas, wipeBytes } from './webIdentityCarrier.js';
+import { deriveIdentityFromMnemonic, wipeBytes } from './webIdentityCarrier.js';
 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',
-};
+function sha256Hex(input) {
+    return bytesToHex(sha256(utf8ToBytes(input)));
+}
 /** A fresh ephemeral key pair for one move. Keep the private key in memory only. */
 export function generateMoveEphemeralKeyPair() {
     return generateSecp256k1KeyPair();
@@ -39,15 +41,47 @@ export function deriveMoveKey(ownEphemeralPrivateKey, otherEphemeralPublicKey, m
         wipeBytes(shared);
     }
 }
-/** The 6-digit code both screens show, bound to the move and both ephemeral keys in their roles. */
-export function deriveMoveSas(moveId, initiatorEphemeralPublicKey, responderEphemeralPublicKey) {
-    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) {
+    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, nonce, commitment) {
+    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) {
+    const digest = sha256(utf8ToBytes(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. */
+export function digestMoveCiphertext(sealed) {
+    return sha256Hex(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.
+ */
+export async function signMoveReceipt(sign, claims) {
+    return { signature: await sign(buildMoveReceiptMessage(claims)) };
+}
+/** Initiator: is this receipt the root's, for exactly this move and ciphertext? */
+export function verifyMoveReceipt(claims, signature) {
+    return verifySignature(buildMoveReceiptMessage(claims), signature, claims.rootPublicKey);
 }
 function moveAad(moveId, publicKey) {
     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, 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 = mnemonicToEntropy(identity.mnemonic, wordlist);
     try {
         const { nonce, ciphertext } = encryptAead(moveKey, entropy, moveAad(moveId, identity.publicKey));
@@ -80,22 +114,6 @@ export function openMovedIdentity(sealed, moveKey, moveId, expectedPublicKey) {
         wipeBytes(entropy);
     }
 }
-/** The exact bytes a move proof or receipt signs. */
-export function buildMoveMessage(action, moveId, timestamp) {
-    return JSON.stringify({ action, moveId: moveId.toLowerCase(), timestamp });
-}
-/** Sign a move action with the identity key. */
-export async function signMoveAction(identity, action, moveId, timestamp = Date.now()) {
-    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, moveId, receipt) {
-    return verifySignature(buildMoveMessage(IDENTITY_MOVE_ACTIONS.received, moveId, receipt.timestamp), receipt.signature, publicKey);
-}
 /** The QR payload for a move. */
 export function buildMoveQrPayload(moveId) {
     return `${IDENTITY_MOVE_QR_PREFIX}${moveId.toLowerCase()}`;

package/dist/esm/crypto/identityProof.js

@@ -0,0 +1,24 @@
+/**
+ * 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.js';
+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, } from '@oxy.so/contracts';
+/** SHA-256 hex of the canonical JSON of `payload` — the `payloadDigest` claim. */
+export function digestIdentityPayload(payload) {
+    return bytesToHex(sha256(utf8ToBytes(canonicalJson(payload))));
+}
+/** Sign `claims` with the root, producing the proof as it travels. */
+export 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 signMessage(buildIdentityProofMessage(claims), identity.privateKey);
+    return { v: IDENTITY_PROOF_VERSION, challenge: claims.challenge, expiresAt: claims.expiresAt, signature };
+}

package/dist/esm/crypto/webIdentityCarrier.js

@@ -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
@@ -26,7 +26,6 @@ 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, } from '@oxy.so/contracts';
 import { AEAD_KEY_LENGTH, decryptAead, encryptAead } from './aead.js';
@@ -39,10 +38,10 @@ import { hkdfSha256 } from './kdf.js';
  * scheme change bumps the label — and with it every KEK — instead of mutating it.
  */
 export const WEB_IDENTITY_PRF_INPUT = 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;
 export class WebIdentityUnlockError extends Error {
     constructor(failure, message) {
         super(message);
@@ -53,22 +52,34 @@ export class WebIdentityUnlockError extends Error {
 function aadFor(parts) {
     return utf8ToBytes(JSON.stringify(parts));
 }
-function entropyAad(publicKey) {
-    return aadFor({ v: WEB_IDENTITY_ENVELOPE_VERSION, purpose: 'entropy', publicKey });
+function secretAad(publicKey, secretKind) {
+    return aadFor({ v: WEB_IDENTITY_ENVELOPE_VERSION, purpose: 'secret', secretKind, publicKey });
 }
-function wrapAad(publicKey, credentialId) {
-    return aadFor({ v: WEB_IDENTITY_ENVELOPE_VERSION, purpose: 'wrap', publicKey, credentialId });
+function wrapAad(publicKey, credentialId, rpId) {
+    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. */
 export function wipeBytes(bytes) {
     bytes.fill(0);
 }
+/** Best-effort removal of secret strings from an opened identity. */
+export function wipeOpenedIdentity(identity) {
+    identity.privateKey = '';
+    if (identity.kind === 'mnemonic')
+        identity.mnemonic = '';
+}
+/** Normalize a typed phrase: trimmed, lowercase, single spaces. */
+export 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.
  */
 export function deriveIdentityFromMnemonic(mnemonic) {
-    const normalized = mnemonic.trim().toLowerCase().split(/\s+/).join(' ');
+    const normalized = normalizeMnemonic(mnemonic);
     if (!validateMnemonic(normalized, wordlist)) {
         throw new Error('Invalid recovery phrase');
     }
@@ -77,7 +88,41 @@ export function deriveIdentityFromMnemonic(mnemonic) {
     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) {
+    const normalized = privateKey.trim().toLowerCase().replace(/^0x/, '');
+    if (!/^[0-9a-f]{64}$/.test(normalized)) {
+        throw new Error('Invalid private key');
+    }
+    let publicKey;
+    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) {
+    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) {
+    return material.kind === 'mnemonic'
+        ? deriveIdentityFromMnemonic(material.mnemonic)
+        : deriveIdentityFromPrivateKey(material.privateKey);
 }
 /** A brand-new 12-word identity. Nothing is persisted. */
 export function generateWebIdentity() {
@@ -89,29 +134,40 @@ export function generateDataKey() {
     globalThis.crypto.getRandomValues(key);
     return key;
 }
+/** Whether `bytes` is a usable PRF output: exactly 32 bytes. */
+export function isUsablePrfOutput(bytes) {
+    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, credentialId) {
-    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, 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 } = 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) {
+    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.
  *
@@ -119,26 +175,34 @@ export function wrapDataKey(dataKey, prfOutput, credentialId, publicKey, now = n
  * session; wipe it when done.
  */
 export 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 = 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 = {
             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);
     }
 }
 /** Recover the data key with one passkey's PRF output. */
@@ -149,7 +213,7 @@ export function unwrapDataKey(envelope, prfOutput, credentialId) {
     }
     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');
@@ -161,26 +225,38 @@ export 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.
  */
 export function openWebIdentity(envelope, dataKey) {
-    let entropy;
+    const publicKey = envelope.publicKey.toLowerCase();
+    const kind = envelope.secretKind;
+    let secret;
     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;
+        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);
     }
 }
 /** Unwrap and open in one step. */
@@ -194,13 +270,27 @@ export function unlockWebIdentity(envelope, prfOutput, credentialId) {
     }
 }
 /** Add (or replace) one passkey's wrap. Requires the data key of an unlocked envelope. */
-export function addWrap(envelope, dataKey, prfOutput, credentialId, now = new Date()) {
+export 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.
+ */
+export 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. */
@@ -211,33 +301,3 @@ export 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.
- */
-export function buildIdentityActionMessage(action, userId, timestamp) {
-    return JSON.stringify({ action, userId, timestamp });
-}
-/** Sign an identity-action message with an opened identity's key. */
-export async function signIdentityAction(identity, action, userId, timestamp = Date.now()) {
-    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) {
-    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 % 1000000).padStart(6, '0');
-}

package/dist/esm/i18n/locales/ar-SA.json

@@ -108,6 +108,7 @@
         "loading": "جارٍ تحميل الحسابات...",
         "qrHeadline": "سجّل الدخول بهوية Oxy الخاصة بك",
         "signInWithOxy": "تسجيل الدخول باستخدام Oxy",
+        "signUpWithOxy": "التسجيل باستخدام Oxy",
         "useIdentityOnDevice": "لا تملك Commons؟ استخدم مفتاح مرور على هذا الجهاز بدلاً من ذلك",
         "getCommons": "احصل على Commons",
         "commonsNotInstalled": "لا تملك Commons؟ احصل على التطبيق لتسجيل الدخول بمعرّف Oxy الخاص بك.",

package/dist/esm/i18n/locales/ca-ES.json

@@ -108,6 +108,7 @@
         "loading": "S'estan carregant els comptes...",
         "qrHeadline": "Inicia sessió amb la teva identitat d'Oxy",
         "signInWithOxy": "Inicia sessió amb Oxy",
+        "signUpWithOxy": "Registra't amb Oxy",
         "useIdentityOnDevice": "No tens Commons? Fes servir una clau d'accés en aquest dispositiu",
         "getCommons": "Descarrega Commons",
         "commonsNotInstalled": "No tens Commons? Descarrega l'app per iniciar sessió amb el teu Oxy ID.",

package/dist/esm/i18n/locales/de-DE.json

@@ -108,6 +108,7 @@
         "loading": "Konten werden geladen...",
         "qrHeadline": "Melden Sie sich mit Ihrer Oxy-Identität an",
         "signInWithOxy": "Mit Oxy anmelden",
+        "signUpWithOxy": "Mit Oxy registrieren",
         "useIdentityOnDevice": "Kein Commons? Verwenden Sie stattdessen einen Passkey auf diesem Gerät",
         "getCommons": "Commons herunterladen",
         "commonsNotInstalled": "Kein Commons? Holen Sie sich die App, um sich mit Ihrer Oxy-ID anzumelden.",

package/dist/esm/i18n/locales/en-US.json

@@ -416,6 +416,7 @@
         "scanQr": "Scan QR code",
         "qrHeadline": "Sign in with your Oxy identity",
         "signInWithOxy": "Sign in with Oxy",
+        "signUpWithOxy": "Sign up with Oxy",
         "useIdentityOnDevice": "No Commons? Use a passkey on this device instead",
         "getCommons": "Get Commons",
         "commonsNotInstalled": "Don't have Commons? Get the app to sign in with your Oxy ID.",