@rapidmx/web-client 0.21.0 → 0.22.0

package/dist/lib/crypto/keyvaultApi.js

@@ -0,0 +1,350 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s E2E encryption endpoints (`BaseKeyVaultRoute`,
+ * `BaseKeyLookupRoute`, `BaseEncryptionPolicyRoute` — mounted in `server` at `mail/mailboxes` and
+ * `system/encryption-policy`, see `src/{mongo,sql}/routes/{KeyVaultRoute,KeyLookupRoute,
+ * EncryptionPolicyRoute}.ts`). These calls carry only wrapped/ciphertext key material and public
+ * certificates — the server never sees an unwrapped private key or master key; see `crypto/masterKey.ts`
+ * and `crypto/keys.ts` for the client-side cryptography that produces the values passed here.
+ */
+import { ApiRequestError, withClient } from "../util/api.js";
+/** `client`, given by every function below that calls the network, is an explicit `ApiClient` from `createApiClient()`
+ * (e.g. one account of a multi-account app) to call instead of the default global `apiFetch()` - see `withClient()`'s
+ * own doc comment in `util/api.ts`. Omitted (the default), every function here behaves exactly as before. */
+export function getKeyVault(mailboxUid, client) {
+    return withClient(client, `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/keyvault`);
+}
+/** The most recently issued, currently-valid (non-revoked, non-expired) published key of the given use
+ * type — the one that should actually be used to sign/encrypt going forward. A mailbox or contact may
+ * have several of the same `useType` on file after a rotation; older ones are kept for decrypting old
+ * mail, never removed, per the spec's own key-lifecycle rules. Every revoked key is skipped, whatever its
+ * `revocationReason` - a superseded key may still verify old mail (`isTrustedForVerification()`) but is never used for
+ * new mail. Shared by `crypto/keySession.ts` (the
+ * mailbox's own keys) and `crypto/composeSecurity.ts` (a recipient's discovered keys). */
+export function findActivePublicKey(keys, useType) {
+    const now = Date.now();
+    return keys
+        .filter((k) => k.useType === useType && !k.revokedAt && k.notAfter > now)
+        .sort((a, b) => b.notBefore - a.notBefore)[0];
+}
+/**
+ * Whether `key` may still be trusted to *verify* existing signatures - never whether to sign or encrypt with it (that is
+ * `findActivePublicKey()`, which skips every revoked key). Expired keys are trusted: mail signed while a key was valid
+ * stays verifiable after it expires. A key revoked with `revocationReason: "superseded"` (a routine rotation) is trusted
+ * for the same reason. A key revoked as `"compromised"`, or revoked with no reason (legacy data, treated as
+ * compromised), is never trusted, because a message's claimed signing time can't show it was signed before the
+ * compromise.
+ */
+export function isTrustedForVerification(key) {
+    return !key.revokedAt || key.revocationReason === "superseded";
+}
+/**
+ * The fingerprints (lowercased, de-duplicated) of every signing key in `keys` and `previousKeys` that is still trusted
+ * for verification (`isTrustedForVerification()`) - the trusted pins to pass to `messageSecurity.ts`'s
+ * `evaluateMessageSecurity()` for a `Contact` (its TOFU-pinned `keys` plus its `previousKeys`, which only key
+ * discovery, "trust this signer" and conflict resolution write) or a `Mailbox` (its own `keys`, so the user's own mail
+ * signed before their rotation still verifies).
+ *
+ * Key rotation continuity: a `PreviousKey` was pinned before it was replaced - by the user accepting a conflict
+ * (`replacement: "user"`) or by restapi's same-issuer renewal of an expired or revoked key (`"automatic"`, which moves
+ * the superseded key here with `revocationReason: "superseded"`) - so it is trusted for verification exactly like a
+ * current pin, and mail it signed before the rotation still verifies. Both replacement kinds are trusted alike, and the
+ * revocation rule is the same for current and previous keys: expired and superseded keys are trusted, compromised and
+ * reasonless revoked keys are not.
+ */
+export function signingKeyFingerprints(keys, previousKeys) {
+    const fingerprints = [...(keys ?? []), ...(previousKeys ?? [])]
+        .filter((key) => key.useType === "sign" && isTrustedForVerification(key))
+        .map((key) => key.fingerprint.toLowerCase());
+    return [...new Set(fingerprints)];
+}
+/**
+ * Thrown by `enrollKey()` when `masterKeyWraps` were supplied (a first-time vault setup) but the mailbox's vault
+ * already has master-key wraps - e.g. another device or tab finished setting it up first. restapi answers `409`;
+ * this subclass (still an `ApiRequestError` with `status` 409) is only used once a re-read of the vault confirms it
+ * really has wraps, so an unrelated `409` (a lost optimistic-lock race) isn't mistaken for it. A caller should
+ * unlock the existing vault instead of enrolling a new master key.
+ */
+export class VaultAlreadyInitializedError extends ApiRequestError {
+    constructor(message, code) {
+        super(message, 409, code);
+        this.name = "VaultAlreadyInitializedError";
+    }
+}
+/** Enrolls a new signing or encryption key. See `EnrollKeyInput`'s own doc comments for which fields
+ * matter for which `useType`. Rejects with `VaultAlreadyInitializedError` when `masterKeyWraps` were supplied
+ * but the vault is already set up (see that class). */
+export async function enrollKey(mailboxUid, input, client) {
+    try {
+        return await withClient(client, `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/keyvault/keys`, {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+    }
+    catch (err) {
+        if (err instanceof ApiRequestError && err.status === 409 && input.masterKeyWraps?.length) {
+            const vault = await getKeyVault(mailboxUid, client).catch(() => undefined);
+            if (vault && vault.masterKeyWraps.length > 0) {
+                throw new VaultAlreadyInitializedError(err.message, err.code);
+            }
+        }
+        throw err;
+    }
+}
+const SIGN_ENROLLMENT_STAGES = [
+    "submitted",
+    "awaiting-challenge",
+    "challenge-answered",
+    "validating",
+    "issuing",
+    "issued",
+    "failed",
+];
+const ENROLLMENT_STATUSES = new Set(["pending", "issued", "failed"]);
+const STEP_STATES = new Set(["done", "active", "pending", "failed"]);
+const ENROLLMENT_TEXT_FIELDS = [
+    "certificate",
+    "error",
+    "requestedAt",
+    "updatedAt",
+    "lastCheckedAt",
+    "nextCheckAt",
+    "errorCode",
+    "note",
+    "issuedAt",
+    "installedAt",
+    "notAfter",
+    "serialNumber",
+    "issuer",
+    "subject",
+];
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Reads an enrollment status from the network: keeps `status` (an unknown value counts as still `pending`, the safe reading) and
+ * whichever optional fields have the right type, drops the rest - an older server's answer comes through as it always did, and a
+ * newer one's malformed field cannot break the page. `progress` is clamped to 0-100; a step needs an id, a label and a known state.
+ */
+export function normalizeEnrollmentResult(raw) {
+    const source = isRecord(raw) ? raw : {};
+    const result = {
+        status: ENROLLMENT_STATUSES.has(source.status) ? source.status : "pending",
+    };
+    for (const field of ENROLLMENT_TEXT_FIELDS) {
+        if (typeof source[field] === "string") {
+            result[field] = source[field];
+        }
+    }
+    if (source.provider === "manual" || source.provider === "rfc8823") {
+        result.provider = source.provider;
+    }
+    if (typeof source.stage === "string" && SIGN_ENROLLMENT_STAGES.includes(source.stage)) {
+        result.stage = source.stage;
+    }
+    if (Array.isArray(source.stages)) {
+        result.stages = source.stages
+            .filter((step) => isRecord(step) && typeof step.id === "string" && typeof step.label === "string" && STEP_STATES.has(step.state))
+            .map((step) => ({
+            id: step.id,
+            label: step.label,
+            state: step.state,
+            ...(typeof step.at === "string" ? { at: step.at } : {}),
+        }));
+    }
+    if (typeof source.progress === "number" && Number.isFinite(source.progress)) {
+        result.progress = Math.min(100, Math.max(0, source.progress));
+    }
+    if (typeof source.retryable === "boolean") {
+        result.retryable = source.retryable;
+    }
+    return result;
+}
+/** Starts an automated (RFC 8823 email-reply-00 ACME) public-CA signing-certificate enrollment —
+ * only meaningful when the deployment has `mail:pki:signing_enrollment:backend` set to `"rfc8823"`
+ * (a `"manual"`-backend deployment's `SigningCertificateEnrollment` throws instead). Genuinely
+ * asynchronous — the CA issues the certificate via a real email round-trip, likely minutes away, not
+ * synchronous the way `enrollKey()`'s encryption-key path is — poll `checkSignEnrollmentStatus()`
+ * rather than expecting an immediate result. `wrappedKey` is submitted upfront (this server never sees
+ * an unwrapped private key) so the eventual install needs no further client action at all. */
+export function startSignEnrollment(mailboxUid, input, client) {
+    return withClient(client, `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/keyvault/keys/sign-enrollment`, {
+        method: "POST",
+        body: JSON.stringify(input),
+    });
+}
+/** Reports the current status of a previously started automated enrollment — see
+ * `startSignEnrollment()`. Answers from what the server already knows; `checkSignEnrollmentNow()` asks the CA. */
+export async function checkSignEnrollmentStatus(mailboxUid, enrollmentId, client) {
+    return normalizeEnrollmentResult(await withClient(client, `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/keyvault/keys/sign-enrollment/${encodeURIComponent(enrollmentId)}`));
+}
+/** The mailbox's current (most recent) signing-certificate enrollment, or `null` when it has never had one - so a second device or
+ * a fresh page learns of one started elsewhere. Needs no stored enrollment id. */
+export async function getCurrentSignEnrollment(mailboxUid, client) {
+    let raw;
+    try {
+        raw = await withClient(client, `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/keyvault/keys/sign-enrollment`);
+    }
+    catch (err) {
+        if (err instanceof ApiRequestError && err.status === 404) {
+            return null;
+        }
+        throw err;
+    }
+    const enrollmentId = isRecord(raw) && typeof raw.enrollmentId === "string" ? raw.enrollmentId : undefined;
+    return enrollmentId ? { ...normalizeEnrollmentResult(raw), enrollmentId } : null;
+}
+/** How long a "check now" is refused for after a `429`, when the server doesn't say (it answers `Retry-After`, which `apiFetch()` does not surface). */
+export const CHECK_NOW_DEFAULT_RETRY_SECONDS = 10;
+/** How many seconds to wait before asking again after `checkSignEnrollmentNow()` was refused with `429`: the body's `retryAfter` (seconds)
+ * when the server put one there, else `CHECK_NOW_DEFAULT_RETRY_SECONDS`. `undefined` for any other error. */
+export function checkNowRetryAfterSeconds(err) {
+    if (!(err instanceof ApiRequestError) || err.status !== 429) {
+        return undefined;
+    }
+    const retryAfter = isRecord(err.details) ? err.details.retryAfter : undefined;
+    return typeof retryAfter === "number" && Number.isFinite(retryAfter) && retryAfter > 0
+        ? Math.ceil(retryAfter)
+        : CHECK_NOW_DEFAULT_RETRY_SECONDS;
+}
+/** Forces an immediate re-check of an enrollment with the CA (instead of waiting for the server's own schedule) and returns its
+ * status. The server refuses with `429` when asked again within about ten seconds - see `checkNowRetryAfterSeconds()`. */
+export async function checkSignEnrollmentNow(mailboxUid, enrollmentId, client) {
+    return normalizeEnrollmentResult(await withClient(client, `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/keyvault/keys/sign-enrollment/${encodeURIComponent(enrollmentId)}/check`, { method: "POST" }));
+}
+/** Cancels a pending automated enrollment of this mailbox, so no key is installed from it afterwards, and returns its
+ * resulting status. Owner-only. `rekey()` is refused (409) while an enrollment holding a wrapped key is in flight, so
+ * this is how an owner with an enrollment stuck at the CA gets to rotate their keys. */
+export function cancelSignEnrollment(mailboxUid, enrollmentId, client) {
+    return withClient(client, `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/keyvault/keys/sign-enrollment/${encodeURIComponent(enrollmentId)}`, { method: "DELETE" });
+}
+/** Fetches `{escrowScopeId, publicKey}` for the `EscrowScope` this mailbox is currently assigned to
+ * (`Mailbox.escrowScopeId`, an admin-only assignment - see `EscrowInfo`'s own doc comment). 404s if the
+ * mailbox has no escrow scope assigned, the scope no longer exists, or the caller can't access this
+ * mailbox. Used by `crypto/masterKeyWraps.ts`'s `buildEscrowWrap()` to get the certificate MK is wrapped
+ * against. */
+export function getEscrowInfo(mailboxUid, client) {
+    return withClient(client, `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/escrow-info`);
+}
+/** Adds a wrapped copy of the master key for a new unlock method (e.g. registering a new passkey),
+ * independent of key enrollment. Requires an already-initialized vault. `expectedMasterKeyGeneration`, when given, is
+ * sent alongside the wrap (see `ExpectedMasterKeyGeneration`): a `409` then means the master key was rotated since. */
+export function addMasterKeyWrap(mailboxUid, wrap, expectedMasterKeyGeneration, client) {
+    const body = expectedMasterKeyGeneration === undefined ? wrap : { ...wrap, expectedMasterKeyGeneration };
+    return withClient(client, `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/keyvault/wraps`, {
+        method: "POST",
+        body: JSON.stringify(body),
+    });
+}
+/** Removes a wrapped copy of the master key for one unlock method. `methodId` is required whenever more
+ * than one wrap could share the same `method` (e.g. multiple passkeys). This alone does NOT revoke
+ * access for anyone who already captured the wrapped blob — see `rekey()`. */
+export function removeMasterKeyWrap(mailboxUid, method, methodId, client) {
+    const query = methodId ? `?methodId=${encodeURIComponent(methodId)}` : "";
+    return withClient(client, `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/keyvault/wraps/${encodeURIComponent(method)}${query}`, {
+        method: "DELETE",
+    });
+}
+/** Full, atomic replacement of the mailbox's key-vault contents — the only real revocation mechanism
+ * for a captured wrap. Restricted server-side to the mailbox's actual owner. Refused (409) while a signing enrollment
+ * holding a wrapped key is in flight (see `cancelSignEnrollment()`), or when an escrowed mailbox's request carries no
+ * replacement escrow wrap. */
+export function rekey(mailboxUid, input, client) {
+    return withClient(client, `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/keyvault/rekey`, {
+        method: "PUT",
+        body: JSON.stringify(input),
+    });
+}
+/** Server-side Discovery: the server itself performs the `_rapidmx` DNS lookup and remote key-endpoint
+ * fetch (browsers can't do DNS TXT lookups, and a direct cross-origin fetch would hit CORS), persisting
+ * the result onto a `Contact` in the caller's own address book. MUST be called lazily at compose time,
+ * never on message receipt (see `specs/end-to-end_encryption.md`'s "Discovery is Server-Side"). */
+export function lookupKeys(mailboxUid, addr, client) {
+    const query = new URLSearchParams({ addr });
+    return withClient(client, `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/keys/lookup?${query.toString()}`);
+}
+/**
+ * Thrown by `trustSigner()` when restapi answers `409`: a different signing key is already pinned for that address, so
+ * trusting this one would silently replace it. Still an `ApiRequestError` (`status` 409). A UI should show this as a
+ * key conflict for the user to resolve deliberately, not retry.
+ */
+export class SignerKeyConflictError extends ApiRequestError {
+    constructor(message, code) {
+        super(message, 409, code);
+        this.name = "SignerKeyConflictError";
+    }
+}
+/**
+ * "Trust this signer": pins `certificate` as `address`'s signing key on the caller's contact for that address
+ * (`POST /mail/mailboxes/:id/keys/trust`), after which `evaluateMessageSecurity()` given that contact's pins reports
+ * the sender's signed mail as verified. Resolves with the contact's resulting key state, the same shape as
+ * `lookupKeys()`. Rejects with `SignerKeyConflictError` on `409` (a different signing key is already pinned), and a
+ * plain `ApiRequestError` for `400` (an invalid certificate, or one that doesn't name `address`) and `403`/`404`.
+ */
+export async function trustSigner(mailboxUid, input, client) {
+    try {
+        return await withClient(client, `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/keys/trust`, {
+            method: "POST",
+            body: JSON.stringify({ address: input.address, certificate: input.certificate }),
+        });
+    }
+    catch (err) {
+        if (err instanceof ApiRequestError && err.status === 409) {
+            throw new SignerKeyConflictError(err.message, err.code);
+        }
+        throw err;
+    }
+}
+/**
+ * Thrown by `resolveKeyConflict()` when restapi answers `409`: the contact's pinned key is no longer
+ * `expectedPinnedFingerprint` (another device or an automatic renewal changed it meanwhile). Still an `ApiRequestError`
+ * (`status` 409). A UI should reload the key state and ask again rather than retry.
+ */
+export class PinnedKeyChangedError extends ApiRequestError {
+    constructor(message, code) {
+        super(message, 409, code);
+        this.name = "PinnedKeyChangedError";
+    }
+}
+/**
+ * Resolves a contact's key conflict (`POST /mail/mailboxes/:id/keys/resolve`) - see `ResolveKeyConflictInput` for what
+ * each action does. Resolves with the contact's resulting key state. Rejects with `PinnedKeyChangedError` on `409`, and
+ * a plain `ApiRequestError` for `400` (an invalid body or certificate), `403` (no rights) and `404` (no such contact, no
+ * pinned key, or no recorded conflict when one is needed).
+ */
+export async function resolveKeyConflict(mailboxUid, input, client) {
+    const body = {
+        address: input.address,
+        useType: input.useType,
+        action: input.action,
+        expectedPinnedFingerprint: input.expectedPinnedFingerprint,
+        ...(input.certificate !== undefined ? { certificate: input.certificate } : {}),
+    };
+    try {
+        return await withClient(client, `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/keys/resolve`, {
+            method: "POST",
+            body: JSON.stringify(body),
+        });
+    }
+    catch (err) {
+        if (err instanceof ApiRequestError && err.status === 409) {
+            throw new PinnedKeyChangedError(err.message, err.code);
+        }
+        throw err;
+    }
+}
+/** The system-wide encryption policy (readable by any authenticated user, used to decide what encryption
+ * controls a compose UI should offer). */
+export function getEncryptionPolicy(client) {
+    return withClient(client, `/system/encryption-policy`);
+}
+/** Admin-only (`RequiresTrustedRole`) — updates the system-wide encryption policy. */
+export function updateEncryptionPolicy(patch, client) {
+    return withClient(client, `/system/encryption-policy`, {
+        method: "PUT",
+        body: JSON.stringify(patch),
+    });
+}

package/dist/lib/crypto/masterKey.d.ts

@@ -0,0 +1,59 @@
+/** MK is always 32 random bytes (AES-256), per the spec. */
+export declare const MASTER_KEY_LENGTH_BYTES = 32;
+/** The one AEAD construction used everywhere in this scheme, per the spec's "MUST use an AEAD
+ * construction (AES-256-GCM or XChaCha20-Poly1305)" — this codebase uses AES-256-GCM specifically,
+ * since it's natively available via WebCrypto with no additional library on any target platform
+ * (browser, Electron renderer). */
+export declare const AEAD_ALGORITHM = "AES-256-GCM";
+/** Generates a fresh master key. Never persisted directly — only ever used to derive an AES-GCM
+ * `CryptoKey` in-process (see `sealWithKey`/`openWithKey`) or wrapped via `wrapMasterKey.ts`-style
+ * helpers before being sent anywhere. */
+export declare function generateMasterKey(): Uint8Array;
+/**
+ * Thrown when key material handed to this module has already been destroyed - `keySession.ts`'s
+ * `destroyUnlockedKeys()` zeroes a master key in place, so a caller still holding a stale `UnlockedKeys`
+ * object (captured before an idle lock or logout) would otherwise keep sealing/opening under an all-zero
+ * AES key *without any error*: AES-GCM accepts any 32 bytes, so a zeroed key "works" and silently produces
+ * ciphertext anyone can open. Callers should catch this and re-read `getUnlockedKeys()` (prompting for the
+ * unlock credential again when that returns `undefined`) rather than retrying with the same object.
+ */
+export declare class KeysLockedError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Throws `KeysLockedError` for key material that can't be a live key: empty, or every byte zero (what a
+ * destroyed master key looks like). A genuine 32-byte random key or KDF output is all-zero with
+ * probability 2^-256, so this never rejects real key material.
+ */
+export declare function assertKeyMaterialUsable(rawKey: Uint8Array): void;
+/** The wire shape stored/sent for any AEAD-sealed value — matches `WrappedPrivateKey`/`MasterKeyWrap`'s
+ * own `ciphertext`/`nonce` fields in `keyvaultApi.ts`. */
+export interface Sealed {
+    ciphertext: string;
+    nonce: string;
+}
+/**
+ * Binds a wrap to the account and purpose it was created for, per the spec: "The user ID and the wrap
+ * purpose MUST be bound as additional authenticated data, preventing a blob from being replayed against
+ * another account." Passed as AES-GCM's `additionalData` — authenticated but never encrypted, so
+ * `openWithKey()` fails closed (throws) if either value doesn't match what `sealWithKey()` was given.
+ */
+export declare function buildAad(mailboxUid: string, purpose: string): Uint8Array;
+/** AEAD-encrypts `plaintext` under `rawKey` (32 bytes — MK when sealing a private key, or a
+ * KDF-derived wrapping key when sealing MK itself). A fresh random nonce is generated per call — GCM
+ * requires a unique nonce per key, never reused. Throws `KeysLockedError` for a destroyed (all-zero) key,
+ * and also for an all-zero `plaintext` of master-key length - that is a destroyed master key being
+ * re-wrapped (e.g. by `masterKeyWraps.ts`), which would otherwise persist a wrap of a useless key. */
+export declare function sealWithKey(rawKey: Uint8Array, plaintext: Uint8Array, aad: Uint8Array): Promise<Sealed>;
+/** Inverse of `sealWithKey()`. Throws (WebCrypto's own `OperationError`) if `rawKey`/`aad` don't match
+ * what the value was sealed under, or if the ciphertext was tampered with — GCM's authentication tag
+ * covers both the ciphertext and the AAD. Throws `KeysLockedError` for a destroyed (all-zero) key. */
+export declare function openWithKey(rawKey: Uint8Array, sealed: Sealed, aad: Uint8Array): Promise<Uint8Array>;
+/**
+ * HKDF-SHA256, used throughout this scheme to turn raw input keying material (an Argon2id output, a
+ * WebAuthn PRF secret, a recovery code) into an independent key for a specific purpose — never the raw
+ * material directly. `info` binds the derived key to what it's for (e.g. `"wrap"` vs. an auth proof),
+ * so the same input material never accidentally produces the same output for two different purposes.
+ * Throws `KeysLockedError` for empty or all-zero `ikm` (destroyed/zeroed input material).
+ */
+export declare function hkdfDerive(ikm: Uint8Array, salt: Uint8Array, info: string, lengthBytes?: number): Promise<Uint8Array>;

package/dist/lib/crypto/masterKey.js

@@ -0,0 +1,104 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The master-key (MK) wrapping scheme from `specs/end-to-end_encryption.md`'s "Master Key Wrapping":
+ * a random 32-byte MK is generated once, private keys are AEAD-encrypted under MK directly, and MK
+ * itself is wrapped once per unlock method (password/passkey/recovery — see the sibling `*Unlock.ts`
+ * modules) using a key derived via HKDF. MK never leaves this module unwrapped except in memory, and
+ * this module never talks to the network — see `keyvaultApi.ts` for what gets sent to the server (only
+ * ciphertext, nonces, salts and KDF parameters, all opaque to it).
+ */
+import { fromBase64, toBase64 } from "./encoding.js";
+/** MK is always 32 random bytes (AES-256), per the spec. */
+export const MASTER_KEY_LENGTH_BYTES = 32;
+/** The one AEAD construction used everywhere in this scheme, per the spec's "MUST use an AEAD
+ * construction (AES-256-GCM or XChaCha20-Poly1305)" — this codebase uses AES-256-GCM specifically,
+ * since it's natively available via WebCrypto with no additional library on any target platform
+ * (browser, Electron renderer). */
+export const AEAD_ALGORITHM = "AES-256-GCM";
+const GCM_NONCE_LENGTH_BYTES = 12;
+/** Generates a fresh master key. Never persisted directly — only ever used to derive an AES-GCM
+ * `CryptoKey` in-process (see `sealWithKey`/`openWithKey`) or wrapped via `wrapMasterKey.ts`-style
+ * helpers before being sent anywhere. */
+export function generateMasterKey() {
+    return crypto.getRandomValues(new Uint8Array(MASTER_KEY_LENGTH_BYTES));
+}
+/**
+ * Thrown when key material handed to this module has already been destroyed - `keySession.ts`'s
+ * `destroyUnlockedKeys()` zeroes a master key in place, so a caller still holding a stale `UnlockedKeys`
+ * object (captured before an idle lock or logout) would otherwise keep sealing/opening under an all-zero
+ * AES key *without any error*: AES-GCM accepts any 32 bytes, so a zeroed key "works" and silently produces
+ * ciphertext anyone can open. Callers should catch this and re-read `getUnlockedKeys()` (prompting for the
+ * unlock credential again when that returns `undefined`) rather than retrying with the same object.
+ */
+export class KeysLockedError extends Error {
+    constructor(message = "The encryption keys for this mailbox are locked. Unlock them again to continue.") {
+        super(message);
+        this.name = "KeysLockedError";
+    }
+}
+/**
+ * Throws `KeysLockedError` for key material that can't be a live key: empty, or every byte zero (what a
+ * destroyed master key looks like). A genuine 32-byte random key or KDF output is all-zero with
+ * probability 2^-256, so this never rejects real key material.
+ */
+export function assertKeyMaterialUsable(rawKey) {
+    if (rawKey.length === 0 || rawKey.every((byte) => byte === 0)) {
+        throw new KeysLockedError();
+    }
+}
+async function importAeadKey(rawKey) {
+    assertKeyMaterialUsable(rawKey);
+    return crypto.subtle.importKey("raw", rawKey, "AES-GCM", false, ["encrypt", "decrypt"]);
+}
+/**
+ * Binds a wrap to the account and purpose it was created for, per the spec: "The user ID and the wrap
+ * purpose MUST be bound as additional authenticated data, preventing a blob from being replayed against
+ * another account." Passed as AES-GCM's `additionalData` — authenticated but never encrypted, so
+ * `openWithKey()` fails closed (throws) if either value doesn't match what `sealWithKey()` was given.
+ */
+export function buildAad(mailboxUid, purpose) {
+    return new TextEncoder().encode(`${mailboxUid}:${purpose}`);
+}
+/** AEAD-encrypts `plaintext` under `rawKey` (32 bytes — MK when sealing a private key, or a
+ * KDF-derived wrapping key when sealing MK itself). A fresh random nonce is generated per call — GCM
+ * requires a unique nonce per key, never reused. Throws `KeysLockedError` for a destroyed (all-zero) key,
+ * and also for an all-zero `plaintext` of master-key length - that is a destroyed master key being
+ * re-wrapped (e.g. by `masterKeyWraps.ts`), which would otherwise persist a wrap of a useless key. */
+export async function sealWithKey(rawKey, plaintext, aad) {
+    const key = await importAeadKey(rawKey);
+    if (plaintext.length === MASTER_KEY_LENGTH_BYTES) {
+        assertKeyMaterialUsable(plaintext);
+    }
+    const nonce = crypto.getRandomValues(new Uint8Array(GCM_NONCE_LENGTH_BYTES));
+    const ciphertext = await crypto.subtle.encrypt({ name: "AES-GCM", iv: nonce, additionalData: aad }, key, plaintext);
+    return { ciphertext: toBase64(new Uint8Array(ciphertext)), nonce: toBase64(nonce) };
+}
+/** Inverse of `sealWithKey()`. Throws (WebCrypto's own `OperationError`) if `rawKey`/`aad` don't match
+ * what the value was sealed under, or if the ciphertext was tampered with — GCM's authentication tag
+ * covers both the ciphertext and the AAD. Throws `KeysLockedError` for a destroyed (all-zero) key. */
+export async function openWithKey(rawKey, sealed, aad) {
+    const key = await importAeadKey(rawKey);
+    const plaintext = await crypto.subtle.decrypt({ name: "AES-GCM", iv: fromBase64(sealed.nonce), additionalData: aad }, key, fromBase64(sealed.ciphertext));
+    return new Uint8Array(plaintext);
+}
+/**
+ * HKDF-SHA256, used throughout this scheme to turn raw input keying material (an Argon2id output, a
+ * WebAuthn PRF secret, a recovery code) into an independent key for a specific purpose — never the raw
+ * material directly. `info` binds the derived key to what it's for (e.g. `"wrap"` vs. an auth proof),
+ * so the same input material never accidentally produces the same output for two different purposes.
+ * Throws `KeysLockedError` for empty or all-zero `ikm` (destroyed/zeroed input material).
+ */
+export async function hkdfDerive(ikm, salt, info, lengthBytes = 32) {
+    assertKeyMaterialUsable(ikm);
+    const baseKey = await crypto.subtle.importKey("raw", ikm, "HKDF", false, ["deriveBits"]);
+    const bits = await crypto.subtle.deriveBits({
+        name: "HKDF",
+        hash: "SHA-256",
+        salt: salt,
+        info: new TextEncoder().encode(info),
+    }, baseKey, lengthBytes * 8);
+    return new Uint8Array(bits);
+}

package/dist/lib/crypto/masterKeyWraps.d.ts

@@ -0,0 +1,108 @@
+import { type UnlockedKeys } from "./keySession.js";
+import { type KeyVault, type MasterKeyWrap } from "./keyvaultApi.js";
+import { Argon2idParams } from "./passwordUnlock.js";
+import { RECOVERY_KDF_LABEL } from "./recoveryCode.js";
+export { RECOVERY_KDF_LABEL };
+export declare const WRAP_SCHEME_VERSION = 1;
+export declare const RECOVERY_CODE_COUNT = 8;
+/** Wraps `mk` under `password` (fresh Argon2id salt every time, even when replacing an existing
+ * password wrap). `params` defaults to this module's own recommended parameters - overridable only so
+ * tests can substitute cheaper ones; production callers should omit it and let the default (which can
+ * be raised over time, per `passwordUnlock.ts`'s own doc comment on why each wrap stores the exact
+ * parameters it was created with) apply. */
+export declare function buildPasswordWrap(mailboxUid: string, mk: Uint8Array, password: string, params?: Argon2idParams): Promise<MasterKeyWrap>;
+/** Generates `count` fresh recovery codes and wraps `mk` under each, returning both the wraps (to
+ * upload) and the plaintext codes (to show the user exactly once - callers must never persist these
+ * themselves). Each wrap's `methodId` is a sequence label, deliberately not derived from the code
+ * itself - that would let anyone who saw a wrap's `methodId` narrow down which physical code it
+ * corresponds to. */
+export declare function buildRecoveryWraps(mailboxUid: string, mk: Uint8Array, count?: number): Promise<{
+    wraps: MasterKeyWrap[];
+    codes: string[];
+}>;
+/** `nonce`/`salt` labels for an escrow wrap - see `buildEscrowWrap()`'s own doc comment for why these
+ * are fixed placeholders rather than freshly generated values, unlike every other wrap method.
+ * Deliberately NOT valid base64 (`fromBase64("n/a")` decodes to 2 arbitrary bytes rather than throwing,
+ * since only a length of `4n+1` makes `atob()` reject its input) - any future generic
+ * `fromBase64(wrap.salt)`/`fromBase64(wrap.nonce)` refactor across every wrap method MUST special-case
+ * (or simply skip) `method === "escrow"` first, or it will silently "succeed" with garbage bytes instead
+ * of failing loudly. Nothing in this codebase does that generically today (`keySession.ts` only ever
+ * reads `.salt`/`.nonce` after already filtering to `method === "password"` or `method === "recovery"`), but it's exactly the kind
+ * of innocent-looking refactor that would reintroduce this as a real bug. */
+export declare const ESCROW_KDF_LABEL = "cms-enveloped-data";
+/**
+ * Wraps `mk` for the `escrow` unlock method: encrypts it as a CMS `EnvelopedData` structure to the
+ * escrow scope's own X.509 public-key certificate (`keyvaultApi.ts`'s `getEscrowInfo()` return value) -
+ * the exact same "encrypt to a recipient's certificate" operation `smime.ts`'s `encryptForRecipients()`
+ * already implements for message bodies, just applied to MK instead. Matches
+ * `specs/end-to-end_encryption.md`'s `wrap_escrow = AEAD(escrow scope public key, MK)` pseudocode.
+ *
+ * Unlike `buildPasswordWrap()`/`buildRecoveryWraps()`, there is no separately-generated salt or nonce
+ * here - CMS `EnvelopedData` already embeds everything a holder's own offline tooling needs to unwrap
+ * (the content-encryption algorithm, its IV, and the ECDH key-agreement material) inside the ciphertext
+ * itself. `nonce`/`salt` are still populated with a fixed, documented placeholder rather than left empty
+ * because restapi's own `validateMasterKeyWrap()` requires every `MasterKeyWrap` field to be a non-empty
+ * string regardless of method - they carry no cryptographic meaning for this method and a holder's
+ * unwrap tooling must never read them.
+ *
+ * This client never has (and this function never touches) the scope's *private* key - only a holder's
+ * own external tooling can ever unwrap the result. `escrowScopeId` is required so `resolveAllowEscrow()`
+ * (server-side) can confirm it matches the mailbox's actually-assigned scope before persisting.
+ */
+export declare function buildEscrowWrap(mk: Uint8Array, escrowScopeId: string, scopePublicKeyCertDer: Uint8Array): Promise<MasterKeyWrap>;
+/**
+ * Removes the recovery wrap a recovery code just opened (`unlockWithRecoveryCode()`'s `recoveryMethodId`) - recovery
+ * codes are single-use. A thin, intention-revealing wrapper over `removeMasterKeyWrap(mailboxUid, "recovery",
+ * methodId)`; `methodId` is required, so a missing id can never make the server pick "the" recovery wrap itself.
+ *
+ * restapi (`BaseKeyVaultRoute.removeMasterKeyWrap()`) refuses with `409` when this wrap is the vault's last non-escrow
+ * wrap (the owner's last own unlock method) - e.g. the last recovery code of a vault whose password wrap is gone. A
+ * caller replacing a forgotten password should therefore call `replacePasswordWrap()` *before* this, never after:
+ * while the code's wrap still exists it is the other unlock method that makes replacing the password safe. A `404`
+ * means the wrap is already gone (e.g. consumed from another tab) and is safe to treat as done.
+ */
+export declare function consumeRecoveryCode(mailboxUid: string, methodId: string): Promise<KeyVault>;
+/** Why `replacePasswordWrap()` failed - see that function. */
+export type PasswordWrapReplaceFailure = "master_key_rotated" | "multiple_password_wraps" | "no_other_unlock_method" | "add_failed";
+/**
+ * Thrown by `replacePasswordWrap()`. For every `reason` except `"add_failed"` nothing was written. `"add_failed"` means
+ * the old password wrap was removed but the new one couldn't be added: `restored` says whether the old wrap was put
+ * back (the vault is then as it was), and `cause` holds the add's own error (e.g. an `ApiRequestError` `409` for a
+ * master key rotated in the meantime). Either way the mailbox still has the other unlock method checked beforehand.
+ */
+export declare class PasswordWrapReplaceError extends Error {
+    readonly reason: PasswordWrapReplaceFailure;
+    readonly restored?: boolean;
+    readonly cause?: unknown;
+    constructor(reason: PasswordWrapReplaceFailure, message: string, options?: {
+        restored?: boolean;
+        cause?: unknown;
+    });
+}
+/**
+ * Replaces the mailbox's password wrap with one for `newPassword`, wrapping the session's master key
+ * (`unlocked.masterKey`, e.g. after `unlockWithRecoveryCode()` for a forgotten password). Resolves with the vault after
+ * the new wrap was added.
+ *
+ * Why remove-then-add: `unlockWithPassword()` only ever tries the first password wrap, and password wraps carry no
+ * `methodId`, so restapi can't remove one of two (a `DELETE .../wraps/password` without `methodId` matching two wraps is
+ * a `400`). Adding first would leave an unremovable, unused second wrap. The safest order is therefore:
+ *
+ * 1. Build the new wrap (Argon2id) - fails, e.g. with `KeysLockedError` for destroyed keys, before any request.
+ * 2. Read the vault and refuse, writing nothing, with `PasswordWrapReplaceError` when: `expectedMasterKeyGeneration` was
+ * given and isn't the vault's (`"master_key_rotated"` - the remove endpoint doesn't check it, so it is checked here);
+ * the vault holds more than one password wrap (`"multiple_password_wraps"`); or removing the password wrap would
+ * leave no other own unlock wrap, i.e. no non-escrow, non-password wrap (`"no_other_unlock_method"` - restapi's
+ * remove endpoint refuses that with `409` too, since it counts only non-escrow wraps as the owner's own; checking
+ * here first gives a typed reason without a write attempt).
+ * 3. Remove the old password wrap (skipped when there is none: the new wrap is simply added). A failure here is
+ * rethrown as-is; nothing changed.
+ * 4. Add the new wrap, sending `expectedMasterKeyGeneration` when given (restapi answers `409` if the master key was
+ * rotated since). If this fails, the removed wrap is re-added (with the generation read in step 2) and
+ * `PasswordWrapReplaceError` `"add_failed"` is thrown with `restored`. If even that fails the mailbox has no password
+ * wrap, but step 2 guaranteed another own unlock method remains - the user can unlock with it and retry.
+ *
+ * Because step 2 needs another own unlock method, a caller replacing a password after a recovery-code unlock must call
+ * this *before* `consumeRecoveryCode()`: the not-yet-consumed code's wrap is that other method.
+ */
+export declare function replacePasswordWrap(mailboxUid: string, unlocked: Pick<UnlockedKeys, "masterKey" | "destroyed">, newPassword: string, expectedMasterKeyGeneration?: number, params?: Argon2idParams): Promise<KeyVault>;