@rapidmx/web-client 0.20.0 → 0.22.0

package/dist/lib/crypto/masterKeyWraps.js

@@ -0,0 +1,228 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Builds a fresh `MasterKeyWrap` for the password and recovery-code unlock methods, given an
+ * already-generated (or already-unwrapped) master key (MK). Extracted from `web-client`'s
+ * `KeyEnrollmentGate.tsx` (first-sign-in provisioning) so its Settings page's "add a password
+ * method"/"regenerate recovery codes" actions - which wrap the *same* MK a second time, not a freshly
+ * generated one - can reuse the exact same wrap-construction logic rather than a second, potentially
+ * drifting copy of it.
+ *
+ * Every builder throws `KeysLockedError` (`masterKey.ts`) when `mk` is a destroyed (all-zero) master key -
+ * wrapping one would upload a wrap that "unlocks" to a useless key.
+ */
+import { toBase64 } from "./encoding.js";
+import { KeysLockedError, assertKeyMaterialUsable, buildAad, sealWithKey } from "./masterKey.js";
+import { MASTER_KEY_AAD_PURPOSE } from "./keySession.js";
+import { addMasterKeyWrap, getKeyVault, removeMasterKeyWrap } from "./keyvaultApi.js";
+import { DEFAULT_ARGON2ID_PARAMS, argon2idKdfLabel, deriveFromPassword, generateSalt } from "./passwordUnlock.js";
+import { RECOVERY_KDF_LABEL, deriveFromRecoveryCode, generateRecoveryCode } from "./recoveryCode.js";
+export { RECOVERY_KDF_LABEL };
+export const WRAP_SCHEME_VERSION = 1;
+export 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 async function buildPasswordWrap(mailboxUid, mk, password, params = DEFAULT_ARGON2ID_PARAMS) {
+    assertKeyMaterialUsable(mk);
+    const salt = generateSalt();
+    const { wrappingKey } = await deriveFromPassword(password, salt, params);
+    const sealed = await sealWithKey(wrappingKey, mk, buildAad(mailboxUid, MASTER_KEY_AAD_PURPOSE));
+    return {
+        method: "password",
+        ciphertext: sealed.ciphertext,
+        nonce: sealed.nonce,
+        salt: toBase64(salt),
+        kdf: argon2idKdfLabel(params),
+        schemeVersion: WRAP_SCHEME_VERSION,
+        createdAt: Date.now(),
+    };
+}
+/** 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 async function buildRecoveryWraps(mailboxUid, mk, count = RECOVERY_CODE_COUNT) {
+    assertKeyMaterialUsable(mk);
+    const aad = buildAad(mailboxUid, MASTER_KEY_AAD_PURPOSE);
+    const codes = [];
+    const wraps = [];
+    for (let i = 0; i < count; i++) {
+        const code = generateRecoveryCode();
+        const salt = generateSalt();
+        const wrappingKey = await deriveFromRecoveryCode(code, salt);
+        const sealed = await sealWithKey(wrappingKey, mk, aad);
+        codes.push(code);
+        wraps.push({
+            method: "recovery",
+            methodId: `recovery-${i + 1}`,
+            ciphertext: sealed.ciphertext,
+            nonce: sealed.nonce,
+            salt: toBase64(salt),
+            kdf: RECOVERY_KDF_LABEL,
+            schemeVersion: WRAP_SCHEME_VERSION,
+            createdAt: Date.now(),
+        });
+    }
+    return { wraps, codes };
+}
+/** `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 const ESCROW_KDF_LABEL = "cms-enveloped-data";
+const ESCROW_NONCE_PLACEHOLDER = "n/a";
+const ESCROW_SALT_PLACEHOLDER = "n/a";
+/**
+ * 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 async function buildEscrowWrap(mk, escrowScopeId, scopePublicKeyCertDer) {
+    assertKeyMaterialUsable(mk);
+    // Loaded here, the one place it is used: `smime.ts` carries PKI.js and the ASN.1/X.509 libraries (over half a megabyte),
+    // and this module is imported by every shell that can unlock keys.
+    const { encryptForRecipients } = await import("./smime.js");
+    const envelopedDer = await encryptForRecipients(mk, [scopePublicKeyCertDer]);
+    return {
+        method: "escrow",
+        escrowScopeId,
+        ciphertext: toBase64(envelopedDer),
+        nonce: ESCROW_NONCE_PLACEHOLDER,
+        salt: ESCROW_SALT_PLACEHOLDER,
+        kdf: ESCROW_KDF_LABEL,
+        schemeVersion: WRAP_SCHEME_VERSION,
+        createdAt: Date.now(),
+    };
+}
+/**
+ * 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 function consumeRecoveryCode(mailboxUid, methodId) {
+    if (!methodId) {
+        return Promise.reject(new Error("A recovery wrap's methodId is required to consume it."));
+    }
+    return removeMasterKeyWrap(mailboxUid, "recovery", methodId);
+}
+/**
+ * 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 class PasswordWrapReplaceError extends Error {
+    constructor(reason, message, options = {}) {
+        super(message);
+        this.name = "PasswordWrapReplaceError";
+        this.reason = reason;
+        this.restored = options.restored;
+        this.cause = options.cause;
+    }
+}
+/** Copies only `MasterKeyWrap`'s own fields, so a wrap read back from the server can be re-posted as-is. */
+function wireWrap(wrap) {
+    const { method, methodId, escrowScopeId, ciphertext, nonce, salt, kdf, schemeVersion, createdAt } = wrap;
+    return {
+        method,
+        ...(methodId !== undefined ? { methodId } : {}),
+        ...(escrowScopeId !== undefined ? { escrowScopeId } : {}),
+        ciphertext,
+        nonce,
+        salt,
+        kdf,
+        schemeVersion,
+        createdAt,
+    };
+}
+/**
+ * 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 async function replacePasswordWrap(mailboxUid, unlocked, newPassword, expectedMasterKeyGeneration, params = DEFAULT_ARGON2ID_PARAMS) {
+    if (unlocked.destroyed) {
+        throw new KeysLockedError();
+    }
+    const newWrap = await buildPasswordWrap(mailboxUid, unlocked.masterKey, newPassword, params);
+    const vault = await getKeyVault(mailboxUid);
+    if (expectedMasterKeyGeneration !== undefined && (vault.masterKeyGeneration ?? 0) !== expectedMasterKeyGeneration) {
+        throw new PasswordWrapReplaceError("master_key_rotated", "This mailbox's master key was rotated since it was unlocked - unlock it again before changing the password.");
+    }
+    const passwordWraps = vault.masterKeyWraps.filter((w) => w.method === "password");
+    if (passwordWraps.length > 1) {
+        throw new PasswordWrapReplaceError("multiple_password_wraps", "This mailbox has more than one password wrap, so the old one can't be removed safely.");
+    }
+    const oldWrap = passwordWraps[0];
+    if (oldWrap && !vault.masterKeyWraps.some((w) => w.method !== "password" && w.method !== "escrow")) {
+        throw new PasswordWrapReplaceError("no_other_unlock_method", "The password is this mailbox's only unlock method - add another one (e.g. recovery codes) before replacing it.");
+    }
+    if (unlocked.destroyed) {
+        throw new KeysLockedError();
+    }
+    if (oldWrap) {
+        await removeMasterKeyWrap(mailboxUid, "password");
+    }
+    try {
+        return await addMasterKeyWrap(mailboxUid, newWrap, expectedMasterKeyGeneration);
+    }
+    catch (err) {
+        if (!oldWrap) {
+            throw err;
+        }
+        const restored = await addMasterKeyWrap(mailboxUid, wireWrap(oldWrap), vault.masterKeyGeneration).then(() => true, () => false);
+        throw new PasswordWrapReplaceError("add_failed", "The new password couldn't be saved.", { restored, cause: err });
+    }
+}

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

@@ -0,0 +1,248 @@
+/**
+ * Evaluates a *received* message's raw MIME source into one of `specs/end-to-end_encryption.md`'s
+ * "Message Security Indicators" states, and recovers the plaintext body when applicable. Reads the
+ * outer envelope's own `Content-Type` (via `mime.ts`'s `parseMimeEntity()`) to decide whether the message
+ * is `multipart/signed`, `application/pkcs7-mime; smime-type="enveloped-data"`, or neither.
+ *
+ * **What a verified state means.** `"signed_verified"`/`"encrypted_verified"` require ALL of: (1) a
+ * cryptographically valid CMS signature (`smime.ts` - detached signatures carrying their own eContent are
+ * rejected, the signer certificate is the one matched to the SignerInfo, never simply the first embedded
+ * certificate, and a `multipart/signed` body must hold exactly the signed part and the signature); (2) the
+ * signer certificate's fingerprint is one the reader already trusts - a pinned `Contact` signing key passed
+ * as `pinnedSignerFingerprints`, or the unlocked mailbox's own `signingFingerprint`; (3) the signer
+ * certificate names the sender: one of its email addresses (SAN rfc822Name, else subject emailAddress /
+ * email-shaped CN) equals the single address in the protected `From` (or the outer `From` when the signed
+ * content carries no protected headers, as with non-RFC 9788 senders); (4) the protected `From`/`To`/`Cc`
+ * address sets (when present) equal the outer envelope's, a signed-only message's protected `Subject` equals
+ * its outer one (what the mail list shows), and neither header block carries more than one
+ * `From`/`To`/`Cc`/`Sender` field.
+ *
+ * **No trust anchor, no verified badge.** Certificates aren't chain-validated (there is no trust store), so
+ * checks 1, 3 and 4 alone prove only that *someone* holding a certificate naming the sender signed it - a
+ * self-issued certificate with SAN `ceo@victim.com` passes them. Without a matching pin the result is
+ * `"signed_unverified_signer"`/`"encrypted_unverified_signer"` instead, carrying `signerFingerprint` and
+ * `signerEmails` so a UI can show "signed by an unverified certificate" and offer to trust it. A failure of checks 1, 3
+ * or 4 is `"signature_failed"` with `signatureFailureReason` saying which check failed.
+ *
+ * **Pinned, but a different key.** When pins were supplied and checks 1, 3 and 4 pass but the signer matches no pin, the
+ * result is `"signature_failed"` with `signatureFailureReason: "signer_key_changed"`: the sender's certificate names
+ * them and the message is intact, but it isn't the key the reader pinned (a rotation the reader hasn't accepted, or an
+ * impersonation). Only this failure also carries `signerCertificate`, so a UI can compare it with the pinned keys
+ * (`contactsApi.ts`'s `fetchSignerKeyState()`) and let the user accept or reject it (`keyvaultApi.ts`'s
+ * `resolveKeyConflict()`). A pin mismatch whose certificate also fails check 3 or 4 (or couldn't be resolved) stays
+ * `untrusted_signer`. Previously pinned keys count as pins (see `signingKeyFingerprints()`), so mail signed before an
+ * accepted or automatic rotation still verifies.
+ */
+import { MimeAttachment, MimeHeaderField } from "./mime.js";
+import { ProtectedHeaders } from "./smimeMessage.js";
+import { type PublicKey } from "./keyvaultApi.js";
+import { type SealKeyMaterial, type SealedVerificationState } from "./verificationSeal.js";
+export { signingKeyFingerprints } from "./keyvaultApi.js";
+/** `"signed_unverified_signer"`/`"encrypted_unverified_signer"`: the signature is valid and its certificate
+ * names the sender, but the certificate isn't one the reader trusts (no pinned key matched) - see this module's
+ * doc comment. The encrypted variant's content was decrypted like `"encrypted_verified"`'s.
+ *
+ * `"verified_at_first_open"`: only ever returned by `evaluateMessageSecurityWithSeal()`. The live check now fails only
+ * because of the signer key's status (`signer_key_changed`, or `*_unverified_signer` - the pins are gone or no longer
+ * trust the key), but the message carries a valid verification seal (`verificationSeal.ts`) for this exact raw MIME and
+ * this same signer certificate, recording that it verified when first opened. The result carries `verifiedAt`,
+ * `sealedState`, `signerFingerprint`, the recovered content, `liveState`/`liveSignatureFailureReason`, and
+ * `laterCompromised` when the signer key has since been revoked as compromised. A UI should show it as "verified when
+ * first opened" - distinct from the live verified states, and with a warning when `laterCompromised` is set. */
+export type MessageSecurityState = "encrypted" | "signed_verified" | "encrypted_verified" | "signed_unverified_signer" | "encrypted_unverified_signer" | "signature_failed" | "verified_at_first_open" | "unprotected";
+/** Why a message is `"signature_failed"`. `invalid_signature`: the CMS signature itself is malformed or
+ * doesn't verify over the content (or a `multipart/signed` body doesn't hold exactly two parts).
+ * `signer_key_changed`: pinned fingerprints were supplied and the signer certificate matches none of them, but it
+ * names the sender and every header check passes - the sender appears to use a new key (see this module's doc
+ * comment); the result carries `signerCertificate`. `untrusted_signer`: pinned fingerprints were supplied and the signer
+ * certificate matches none of them and also fails the identity or header checks (or no signer certificate could be
+ * resolved at all). `signer_identity_mismatch`: the signer certificate doesn't name the message's `From` address (or
+ * `From` doesn't hold exactly one address). `header_mismatch`: the signed/protected `From`/`To`/`Cc` (or a signed-only
+ * message's `Subject`) disagree with the outer envelope's, or either header block repeats a `From`/`To`/`Cc`/`Sender`
+ * field. */
+export type SignatureFailureReason = "invalid_signature" | "signer_key_changed" | "untrusted_signer" | "signer_identity_mismatch" | "header_mismatch";
+/** The header fields recovered from inside the signed/encrypted entity (RFC 9788 header protection), decoded
+ * for display where they are text. */
+export interface MessageProtectedHeaders {
+    from: string;
+    to: string;
+    cc?: string;
+    subject: string;
+}
+export interface MessageSecurityResult {
+    state: MessageSecurityState;
+    /** The verified/decrypted content as HTML - still needs client-side sanitization before touching the
+     * DOM (this module does none itself; see `MessageDetailPane.tsx`). For a `text/html` body this is that
+     * HTML; for a `text/plain` body it is the text HTML-escaped inside a whitespace-preserving `<pre>`
+     * (never plain text passed through as markup), with the raw text in `text`. Absent for
+     * `"unprotected"` (the caller should keep using the server's own sanitized `/content` body) and for an
+     * encrypted message this device couldn't open (see `decryptError`). */
+    html?: string;
+    /** The raw plain text, present only when the recovered body was `text/plain` (not `text/html`). */
+    text?: string;
+    /** `true` when `evaluateMessageSecurity()` was given a `readerAddress` and recovered protected `To`/`Cc`
+     * headers that don't include it - e.g. a genuinely signed message re-sent verbatim to someone it was
+     * never addressed to. Informational, orthogonal to `state` (a Bcc recipient legitimately sees this
+     * too), so a UI can say "this message wasn't addressed to you" next to an otherwise valid signature.
+     * `undefined` when no reader address was given or nothing protected was recovered. */
+    notAddressedToReader?: boolean;
+    /** Present only for `"signature_failed"`: which verification step failed. */
+    signatureFailureReason?: SignatureFailureReason;
+    /** Present only when the message was encrypted but this device couldn't decrypt it (a wrong or
+     * since-rotated key, non-AEAD content encryption, or corrupt/foreign data) - the caller should keep
+     * showing whatever `GET /:id/content` already produced alongside this explanation. */
+    decryptError?: string;
+    /** See `ParsedEncryptedMessage.headerTamperDetected`'s own doc comment - a deliberately separate,
+     * orthogonal signal from `state`, since RFC 9788's `HP-Outer` is written on every encrypted message
+     * regardless of whether it's also signed. `undefined` for anything that isn't an encrypted message
+     * this device could decrypt. */
+    headerTamperDetected?: boolean;
+    /** The real subject recovered from the message's protected headers - RFC 9788 header protection
+     * obscures the outer envelope's own `Subject` to `"[...]"`. Populated only when content was actually
+     * recovered and it carried a protected Subject. */
+    subject?: string;
+    /** Every protected header recovered from inside the signed/decrypted entity - present only when that entity
+     * carries RFC 9788 protected headers (a protected `From`). Absent for a legacy S/MIME sender's signed-only
+     * message: its outer Subject/To/Cc were then never signed, and a UI should not present them as verified. */
+    protectedHeaders?: MessageProtectedHeaders;
+    /** The attachments inside the verified/decrypted entity - for a signed-only message the only attachments the
+     * signature covers, so a UI showing a verified badge should list these rather than the server's attachment
+     * records (which include anything outside the signed part). Present whenever content was recovered. */
+    attachments?: MimeAttachment[];
+    /** SHA-256 fingerprint (hex) of the certificate that produced a cryptographically valid signature - present
+     * for `"signed_verified"`, `"encrypted_verified"`, the `*_unverified_signer` states and a `"signature_failed"`
+     * whose signature itself was valid. Compare against / pin as a `PublicKey.fingerprint`. */
+    signerFingerprint?: string;
+    /** The email addresses that signer certificate asserts (lowercased), alongside `signerFingerprint`. */
+    signerEmails?: string[];
+    /** Base64 DER of the certificate that verified the signature - what `keyvaultApi.ts`'s `trustSigner()` pins for
+     * a "trust this signer" action. Present alongside `signerFingerprint` for `"signed_verified"`,
+     * `"encrypted_verified"`, the `*_unverified_signer` states, and `"signature_failed"` with reason
+     * `"signer_key_changed"` (for a key-changed comparison and `resolveKeyConflict()`'s `certificate`). Never for any
+     * other `"signature_failed"`, even when its signature itself was valid (a failed binding is not something to offer
+     * trusting). */
+    signerCertificate?: string;
+    /** Only from `evaluateMessageSecurityWithSeal()`: a seal for a live `"signed_verified"`/`"encrypted_verified"` result
+     * when no stored seal opens under the current master key generation, or the stored seal is from an older generation.
+     * Persist it best effort with `mailApi.ts`'s `setMessageVerificationSeal(messageUid, sealToWrite.seal,
+     * sealToWrite.masterKeyGeneration)` (a `VerificationSealConflictError` means the server kept the stored seal - ignore
+     * it). */
+    sealToWrite?: SealToWrite;
+    /** For `"verified_at_first_open"`: when the sealed verification happened (epoch ms). */
+    verifiedAt?: number;
+    /** For `"verified_at_first_open"`: the verified state the seal recorded. */
+    sealedState?: SealedVerificationState;
+    /** For `"verified_at_first_open"`: the live state the seal overrode (`"signature_failed"` or `*_unverified_signer`). */
+    liveState?: MessageSecurityState;
+    /** For `"verified_at_first_open"` over a live `"signature_failed"`: its reason (always `"signer_key_changed"`). */
+    liveSignatureFailureReason?: SignatureFailureReason;
+    /** For `"verified_at_first_open"`: `true` when the caller's `signerKeys` show the signer key is now revoked as
+     * compromised (or revoked with no reason) - the seal proves it verified then, not that the key was safe then. */
+    laterCompromised?: boolean;
+}
+/** A seal for the caller to store, with the master key generation it was written under. */
+export interface SealToWrite {
+    seal: string;
+    masterKeyGeneration: number;
+}
+export interface SignerBindingInput {
+    /** The certificate matched to the verified SignerInfo; `undefined` fails closed. */
+    signerCertificateDer: Uint8Array | undefined;
+    /** Headers recovered from inside the signed content (RFC 9788), if any. */
+    protectedHeaders: (Pick<ProtectedHeaders, "from" | "to"> & Partial<Pick<ProtectedHeaders, "cc" | "subject">>) | undefined;
+    /** The received message's outer header map (lowercased names), as `parseMimeEntity()` returns it. */
+    outerHeaders: Record<string, string>;
+    /** Every outer header field in order (`parseMimeEntity()`'s `fields`) - checked for repeated
+     * `From`/`To`/`Cc`/`Sender`. Omitted, only the first-occurrence map above is available. */
+    outerFields?: MimeHeaderField[];
+    /** Every protected header field in order - checked for repeats the same way. */
+    protectedFields?: MimeHeaderField[];
+    /** One trusted fingerprint or several (any match is accepted). An empty array counts as none supplied. */
+    pinnedSignerFingerprint?: string | string[];
+    /** Also require the protected `Subject` (when protected headers are present) to equal the outer one - right for
+     * a signed-only (`hp="clear"`) message, wrong for an encrypted one whose outer Subject is obscured. */
+    compareSubject?: boolean;
+}
+/** Checks 2-4 from this module's doc comment for an already cryptographically verified signature.
+ * Returns `undefined` when the signer is accepted, otherwise the failure reason. A pin mismatch is
+ * `"signer_key_changed"` when checks 3 and 4 pass for the certificate, and `"untrusted_signer"` when they don't (or no
+ * certificate was resolved).
+ *
+ * With no `pinnedSignerFingerprint` (or an empty array), check 2 is skipped and `undefined` means only that the
+ * certificate names the sender consistently - NOT that the signer is trusted. Use `evaluateMessageSecurity()`
+ * (which reports that case as `*_unverified_signer`) unless you enforce a pin yourself. */
+export declare function checkSignerBinding(input: SignerBindingInput): Promise<SignatureFailureReason | undefined>;
+/**
+ * Evaluates one received message's raw MIME source (see `mailApi.ts`'s `getMessageRawContent()`) into
+ * a security state + recovered plaintext. Never throws — a parse failure, wrong key, or unrecognized
+ * content type all degrade to a result the caller can render directly.
+ *
+ * `pinnedSignerFingerprints` - the sender's trusted signing-key fingerprint(s): `signingKeyFingerprints()` of the
+ * sender's `Contact.keys` and `Contact.previousKeys` (see `contactsApi.ts`'s `fetchPinnedSigningFingerprints()`). A
+ * supplied pin that the signer doesn't match is `signer_key_changed` or `untrusted_signer`. The unlocked mailbox's own
+ * `signingFingerprint` is always trusted too (mail this mailbox signed itself). Omitted or empty, a valid signature
+ * from any other certificate is `*_unverified_signer`, never verified. `readerAddress` - the unlocked mailbox's own
+ * address - enables `notAddressedToReader`.
+ *
+ * An encrypted message is decrypted with `unlocked`'s active encryption key or any of its `retainedEncryptionKeys` (the
+ * older keys a rotation replaced - see `keySession.ts`), matched by recipient identifier first.
+ */
+export declare function evaluateMessageSecurity(rawMime: string, unlocked: MessageSecurityKeys | undefined, pinnedSignerFingerprints?: string | string[], readerAddress?: string): Promise<MessageSecurityResult>;
+/** The keys `evaluateMessageSecurity()` reads from an unlocked session (`keySession.ts`'s `UnlockedKeys`). */
+export interface MessageSecurityKeys {
+    encryptionPrivateKey?: CryptoKey;
+    encryptionCertDer?: Uint8Array;
+    retainedEncryptionKeys?: {
+        certDer: Uint8Array;
+        privateKey: CryptoKey;
+    }[];
+    signingFingerprint?: string;
+}
+/** Options for `evaluateMessageSecurityWithSeal()`. */
+export interface VerificationSealOptions {
+    mailboxUid: string;
+    messageUid: string;
+    /** The message's stored `Message.verificationSeal`, if any. */
+    seal?: string;
+    /** The vault's current `KeyVault.masterKeyGeneration` (`0` when it reports none): the generation a stored seal must
+     * carry to be honoured, and the one a new `sealToWrite` is written under. */
+    masterKeyGeneration: number;
+    /** The message's stored `Message.verificationSealGeneration`, if any. When it is older than `masterKeyGeneration`, a
+     * live verified message is re-sealed (after a `rekey()`). */
+    sealGeneration?: number;
+    /** The signer's key records the caller knows about, to tell whether the sealed signer key has since been revoked as
+     * compromised: e.g. `[...state.pinned, ...state.previous]` from `contactsApi.ts`'s `fetchSignerKeyState()` for the
+     * sender, plus the mailbox's own `keys` for mail from its own address. A record whose fingerprint equals the signer's
+     * and fails `isTrustedForVerification()` sets `laterCompromised`. Omitted, `laterCompromised` is never set. */
+    signerKeys?: readonly PublicKey[];
+    /** The `verifiedAt` recorded in a new `sealToWrite`. Defaults to `Date.now()`. */
+    now?: number;
+}
+/**
+ * `evaluateMessageSecurity()` with verification seals (`verificationSeal.ts`). The live evaluation always runs first,
+ * with the same arguments; then:
+ *
+ * **Live verified** (`"signed_verified"`/`"encrypted_verified"`, no HP-Outer tampering), and either no seal opens for this
+ * mailbox, message, raw MIME and `options.masterKeyGeneration`, or `options.sealGeneration` is older than
+ * `options.masterKeyGeneration`: the result gains `sealToWrite` (`{ seal, masterKeyGeneration }`), sealing the live
+ * `signerFingerprint` and state at `options.now` under the current generation. The caller persists it best effort
+ * (`setMessageVerificationSeal()`). This is how messages are re-sealed, lazily, after a `rekey()`: seals are never
+ * carried across a master key rotation (see `verificationSeal.ts`).
+ *
+ * **Live failure caused only by key status** (`signer_key_changed`, `signed_unverified_signer`,
+ * `encrypted_unverified_signer` - which also covers a signer key since revoked, since `signingKeyFingerprints()` drops
+ * such pins): when the seal opens, its `signerFingerprint` equals the live one and its state matches the message kind
+ * (signed-only vs. encrypted), the result is `"verified_at_first_open"` with `verifiedAt`, `sealedState`,
+ * `signerFingerprint`, the recovered content (for a signed-only `signer_key_changed` message too), `liveState`,
+ * `liveSignatureFailureReason` and `laterCompromised` (see `VerificationSealOptions.signerKeys`).
+ * `signatureFailureReason` is dropped.
+ *
+ * **Everything else** returns the live result unchanged: an invalid signature, identity or header mismatch,
+ * `untrusted_signer`, HP-Outer tampering, a seal whose MAC fails or whose hash, uids, generation or signer fingerprint differ, and
+ * every unsigned state.
+ *
+ * With `unlocked` undefined (no master key) the seal is ignored and no seal is built. Throws `KeysLockedError` when
+ * `unlocked` was destroyed (`keySession.ts`), before evaluating anything, or if it is destroyed while sealing; otherwise
+ * never throws - a seal that can't be built (e.g. uids too long for the size limit) just leaves `sealToWrite` unset.
+ */
+export declare function evaluateMessageSecurityWithSeal(rawMime: string, unlocked: (MessageSecurityKeys & SealKeyMaterial) | undefined, pinnedSignerFingerprints: string | string[] | undefined, readerAddress: string | undefined, options: VerificationSealOptions): Promise<MessageSecurityResult>;