@rapidmx/web-client 0.20.0 → 0.22.0

package/dist/lib/crypto/passwordUnlock.js

@@ -0,0 +1,73 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The "password" unlock method from `specs/end-to-end_encryption.md`'s "Master Key Wrapping": derives a
+ * single Argon2id output from the user's password, then HKDF-splits it into two independent values so
+ * the plaintext password (and the Argon2id output itself) never has to be transmitted or reused for two
+ * purposes — an authentication proof and a device-only wrapping key.
+ *
+ * `wrappingKey` is used with `masterKey.ts`'s `sealWithKey`/`openWithKey` to wrap/unwrap MK, and is never
+ * sent anywhere. `authProof` is derived for a future server-side "does this look like the right password"
+ * online-guess-rate-limiting check (distinct from `wrappingKey`, so the server can never derive the
+ * wrapping key even if it learns the proof) — no such verification endpoint exists in `@rapidmx/restapi`
+ * yet, so today only `wrappingKey` is actually consumed; `authProof` is produced now so the wire format
+ * (`kdf` string on `MasterKeyWrap`) doesn't need to change when that endpoint is added.
+ */
+import { toBase64 } from "./encoding.js";
+import { hkdfDerive } from "./masterKey.js";
+/** Matches the `kdf` string format `MasterKeyWrap.kdf` documents (`argon2id:m=65536,t=3,p=4`) — OWASP's
+ * current recommended minimum for Argon2id (m=19MiB is the OWASP floor; this is deliberately higher,
+ * matching the doc comment on `EncryptionCertificateAuthority`'s own conservative defaults elsewhere in
+ * this system). */
+export const DEFAULT_ARGON2ID_PARAMS = { memorySize: 65536, iterations: 3, parallelism: 4 };
+const ARGON2ID_HASH_LENGTH_BYTES = 32;
+/** Builds the `kdf` string stored alongside a password-method `MasterKeyWrap`, so parameters can be
+ * upgraded over time without breaking existing accounts (each wrap records the parameters it was
+ * actually created with). */
+export function argon2idKdfLabel(params) {
+    return `argon2id:m=${params.memorySize},t=${params.iterations},p=${params.parallelism}`;
+}
+/** Inverse of `argon2idKdfLabel()` — reads back the exact parameters a `MasterKeyWrap.kdf` string was
+ * created with, so unlocking always re-derives with the *original* parameters even if
+ * `DEFAULT_ARGON2ID_PARAMS` has since changed (the spec's own "KDF parameters ... MUST be stored
+ * alongside each wrap, so costs can be raised over time without breaking existing accounts"). Returns
+ * `undefined` for anything that isn't a well-formed `argon2id:m=...,t=...,p=...` label — including a
+ * different KDF entirely (e.g. recovery codes' own `"hkdf-sha256"` label), which callers must not
+ * attempt to unlock as if it were password-derived.
+ */
+export function parseArgon2idKdfLabel(label) {
+    const match = /^argon2id:m=(\d+),t=(\d+),p=(\d+)$/.exec(label);
+    if (!match) {
+        return undefined;
+    }
+    return { memorySize: Number(match[1]), iterations: Number(match[2]), parallelism: Number(match[3]) };
+}
+/** A fresh random salt for a new password enrollment. 16 bytes is Argon2id's own recommended minimum. */
+export function generateSalt(lengthBytes = 16) {
+    return crypto.getRandomValues(new Uint8Array(lengthBytes));
+}
+/**
+ * Runs Argon2id once against `password`/`salt`, then HKDF-splits the result into `authProof` and
+ * `wrappingKey` (see this module's doc comment for why two independent values, not one reused for both
+ * purposes). The plaintext password itself never leaves this function.
+ */
+export async function deriveFromPassword(password, salt, params = DEFAULT_ARGON2ID_PARAMS) {
+    // Loaded on first use: `hash-wasm` carries the Argon2 WebAssembly and is only needed once a password is derived.
+    const { argon2id } = await import("hash-wasm");
+    const argonOutput = await argon2id({
+        password,
+        salt,
+        memorySize: params.memorySize,
+        iterations: params.iterations,
+        parallelism: params.parallelism,
+        hashLength: ARGON2ID_HASH_LENGTH_BYTES,
+        outputType: "binary",
+    });
+    const [authProofBytes, wrappingKey] = await Promise.all([
+        hkdfDerive(argonOutput, salt, "auth-proof"),
+        hkdfDerive(argonOutput, salt, "wrap"),
+    ]);
+    return { authProof: toBase64(authProofBytes), wrappingKey };
+}

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

@@ -0,0 +1,28 @@
+/** KDF label for a recovery-code wrap - there's no Argon2id step for these (the code itself is already
+ * high-entropy), just a direct HKDF derivation. Re-exported from `masterKeyWraps.ts`, which writes it; defined here
+ * so `keySession.ts` can read it without importing `masterKeyWraps.ts` (which imports `keySession.ts`). */
+export declare const RECOVERY_KDF_LABEL = "hkdf-sha256";
+/** Exported for direct unit testing of the padding/remainder-bits path — `generateRecoveryCode()` always
+ * calls this with a fixed 20-byte input (160 bits), which happens to divide evenly into 5-bit groups
+ * with no remainder, so that path is otherwise unreachable through the public recovery-code API alone. */
+export declare function base32Encode(bytes: Uint8Array): string;
+/** Generates one recovery code, e.g. `"XQ4M-8K2P-7RTN-JY3H-VC9D-WA6F-2E5S"`. Callers should generate
+ * several (the spec: "a set of ... codes") and display them once, with explicit user confirmation that
+ * they've been saved — losing every unlock method makes the mailbox's encrypted content permanently
+ * unreadable (see the spec's "Recovery" section). */
+export declare function generateRecoveryCode(): string;
+/**
+ * Canonicalizes user-typed recovery code input into the exact form `generateRecoveryCode()` emits (and
+ * therefore the exact string `buildRecoveryWraps()` hashed at enrolment): every whitespace character and
+ * dash is stripped, letters are uppercased, Crockford's own decode aliases are applied (`O` → `0`, `I`/`L`
+ * → `1` — none of which the generation alphabet ever emits, so a generated code is unchanged by this
+ * mapping), and the result is re-grouped into dash-separated `GROUP_SIZE` blocks. The re-grouping is
+ * load-bearing, not cosmetic: the dashes were always part of the HKDF input, so stripping them without
+ * re-inserting them in the canonical grouping would derive a different key than every existing wrap.
+ */
+export declare function normalizeRecoveryCode(code: string): string;
+/** Derives the wrapping key for one recovery code. `salt` is per-wrap, generated at enrolment and stored
+ * alongside the resulting `MasterKeyWrap` (never secret — HKDF's salt need not be). `code` is normalized
+ * first (see `normalizeRecoveryCode()`), so lowercase, spacing/dash variations, and O/I/L transcription
+ * slips all derive the same key as the code exactly as displayed. */
+export declare function deriveFromRecoveryCode(code: string, salt: Uint8Array): Promise<Uint8Array>;

package/dist/lib/crypto/recoveryCode.js

@@ -0,0 +1,86 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The "recovery codes" unlock method from `specs/end-to-end_encryption.md`'s "Master Key Wrapping": a
+ * set of high-entropy, single-use codes generated client-side and displayed to the user once, at
+ * enrolment. Unlike the password method (see `passwordUnlock.ts`), there is no separate auth-proof split
+ * — the spec's own wrapping pseudocode derives the wrapping key directly: `wrap_recovery =
+ * AEAD(HKDF(recovery_code, salt), MK)`.
+ */
+import { hkdfDerive } from "./masterKey.js";
+/** KDF label for a recovery-code wrap - there's no Argon2id step for these (the code itself is already
+ * high-entropy), just a direct HKDF derivation. Re-exported from `masterKeyWraps.ts`, which writes it; defined here
+ * so `keySession.ts` can read it without importing `masterKeyWraps.ts` (which imports `keySession.ts`). */
+export const RECOVERY_KDF_LABEL = "hkdf-sha256";
+/** Crockford base32 alphabet — excludes I/L/O/U to avoid transcription ambiguity with 1/0/V, the same
+ * reasoning as TOTP/backup-code schemes elsewhere. */
+const CROCKFORD_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+/** 20 random bytes (160 bits) — well above the ~20-bit entropy the spec explicitly calls TOTP out for
+ * being too weak (`specs/end-to-end_encryption.md`: "A 6-digit code additionally carries only ~20 bits
+ * of entropy"). Encoded as Crockford base32 and grouped into 4-character blocks for transcription. */
+const RECOVERY_CODE_ENTROPY_BYTES = 20;
+const GROUP_SIZE = 4;
+/** Exported for direct unit testing of the padding/remainder-bits path — `generateRecoveryCode()` always
+ * calls this with a fixed 20-byte input (160 bits), which happens to divide evenly into 5-bit groups
+ * with no remainder, so that path is otherwise unreachable through the public recovery-code API alone. */
+export function base32Encode(bytes) {
+    let bits = 0;
+    let value = 0;
+    let output = "";
+    for (const byte of bytes) {
+        value = (value << 8) | byte;
+        bits += 8;
+        while (bits >= 5) {
+            output += CROCKFORD_ALPHABET[(value >>> (bits - 5)) & 0x1f];
+            bits -= 5;
+        }
+    }
+    if (bits > 0) {
+        output += CROCKFORD_ALPHABET[(value << (5 - bits)) & 0x1f];
+    }
+    return output;
+}
+/** Generates one recovery code, e.g. `"XQ4M-8K2P-7RTN-JY3H-VC9D-WA6F-2E5S"`. Callers should generate
+ * several (the spec: "a set of ... codes") and display them once, with explicit user confirmation that
+ * they've been saved — losing every unlock method makes the mailbox's encrypted content permanently
+ * unreadable (see the spec's "Recovery" section). */
+export function generateRecoveryCode() {
+    const bytes = crypto.getRandomValues(new Uint8Array(RECOVERY_CODE_ENTROPY_BYTES));
+    const encoded = base32Encode(bytes);
+    const groups = [];
+    for (let i = 0; i < encoded.length; i += GROUP_SIZE) {
+        groups.push(encoded.slice(i, i + GROUP_SIZE));
+    }
+    return groups.join("-");
+}
+/**
+ * Canonicalizes user-typed recovery code input into the exact form `generateRecoveryCode()` emits (and
+ * therefore the exact string `buildRecoveryWraps()` hashed at enrolment): every whitespace character and
+ * dash is stripped, letters are uppercased, Crockford's own decode aliases are applied (`O` → `0`, `I`/`L`
+ * → `1` — none of which the generation alphabet ever emits, so a generated code is unchanged by this
+ * mapping), and the result is re-grouped into dash-separated `GROUP_SIZE` blocks. The re-grouping is
+ * load-bearing, not cosmetic: the dashes were always part of the HKDF input, so stripping them without
+ * re-inserting them in the canonical grouping would derive a different key than every existing wrap.
+ */
+export function normalizeRecoveryCode(code) {
+    const compact = code
+        .replace(/[\s-]+/g, "")
+        .toUpperCase()
+        .replace(/O/g, "0")
+        .replace(/[IL]/g, "1");
+    const groups = [];
+    for (let i = 0; i < compact.length; i += GROUP_SIZE) {
+        groups.push(compact.slice(i, i + GROUP_SIZE));
+    }
+    return groups.join("-");
+}
+/** Derives the wrapping key for one recovery code. `salt` is per-wrap, generated at enrolment and stored
+ * alongside the resulting `MasterKeyWrap` (never secret — HKDF's salt need not be). `code` is normalized
+ * first (see `normalizeRecoveryCode()`), so lowercase, spacing/dash variations, and O/I/L transcription
+ * slips all derive the same key as the code exactly as displayed. */
+export async function deriveFromRecoveryCode(code, salt) {
+    const ikm = new TextEncoder().encode(normalizeRecoveryCode(code));
+    return hkdfDerive(ikm, salt, "wrap");
+}

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

@@ -0,0 +1,95 @@
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s signing-certificate backend endpoints:
+ *
+ * - `getSigningEnrollmentInfo()` — `GET /system/signing-enrollment` (any signed-in user): which backend issues
+ * signing certificates in this deployment (`manual`, `rfc8823` or `none`), whether it's automatic, the
+ * certificate authority's host, a typical duration, whether an administrator can upload a certificate by hand,
+ * and how the background job's last contacts with the CA went. `@rapidmx/web-client`'s Encryption settings page
+ * uses this to word a request's status truthfully instead of assuming automatic issuance.
+ * - The administrator functions — `BaseSigningEnrollmentAdminRoute` (mounted at `admin/signing-enrollments`,
+ * trusted role AND an elevated token): list pending requests, download a request's CSR, upload the certificate a
+ * CA issued, or reject a request with a reason its owner sees. This is the manual-issuance workflow, and an
+ * escape hatch to inspect an automatic (`rfc8823`) request that has stalled.
+ */
+import { ApiClient } from "../util/api.js";
+/** Mirrors `@rapidmx/restapi`'s `SigningProviderKind`. */
+export type SigningProviderKind = "manual" | "rfc8823";
+/** Mirrors `@rapidmx/restapi`'s `SigningBackendKind`. */
+export type SigningBackendKind = SigningProviderKind | "none";
+/** The code a stale enrollment id (left over from a backend this deployment no longer runs) answers with - a client
+ * that sees this on a status check or a "check now" should clear the id and let the user request again. */
+export declare const SIGNING_ENROLLMENT_UNKNOWN = "signing-enrollment-unknown";
+/** How the background job's last contacts with the certificate authority went. Absent fields mean "never contacted yet". */
+export interface SigningEnrollmentHealth {
+    ok: boolean;
+    checkedAt?: string;
+    lastSuccessAt?: string;
+    /** Sanitized (no URLs, tokens or key material) and length-capped - safe to show as-is. */
+    lastError?: string;
+}
+/** Mirrors `@rapidmx/restapi`'s `SigningBackendInfo` - what `GET /system/signing-enrollment` answers. */
+export interface SigningEnrollmentInfo {
+    backend: SigningBackendKind;
+    automatic: boolean;
+    ca?: {
+        host: string;
+    };
+    contactEmail?: string;
+    typicalDurationMinutes?: number;
+    adminUpload: boolean;
+    health?: SigningEnrollmentHealth;
+}
+/** Mirrors `@rapidmx/restapi`'s `AdminEnrollmentSummary` - one row of `GET /admin/signing-enrollments`. Never a CSR, key or certificate. */
+export interface AdminSigningEnrollment {
+    enrollmentId: string;
+    identity: string;
+    mailboxUid?: string;
+    requestedAt: string;
+    status: "pending" | "issued" | "failed";
+    provider: SigningProviderKind;
+    stage?: string;
+    lastError?: string;
+    /** Whether an administrator can upload a certificate for this request right now. */
+    canUpload: boolean;
+    /** When `canUpload` is `false`: why (e.g. the automatic provider issues this one itself, or it predates the mailbox's key being kept with it). */
+    uploadBlockedReason?: string;
+}
+/** What `POST /admin/signing-enrollments/:id/certificate` answers once the upload is accepted. */
+export interface CertificateUploadResult {
+    enrollmentId: string;
+    identity: string;
+    status: "issued";
+    chainLength: number;
+    subject: string;
+    issuer: string;
+    serialNumber: string;
+    notBefore: string;
+    notAfter: string;
+    message: string;
+}
+/** What `POST /admin/signing-enrollments/:id/reject` answers. */
+export interface RejectEnrollmentResult {
+    enrollmentId: string;
+    status: "failed";
+    error: string;
+}
+/** `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 declare function getSigningEnrollmentInfo(client?: ApiClient): Promise<SigningEnrollmentInfo>;
+/** The pending (and issued-but-not-yet-installed) signing-certificate requests, metadata only. Trusted role + elevated token required server-side. */
+export declare function listSigningEnrollments(client?: ApiClient): Promise<AdminSigningEnrollment[]>;
+/** A plain URL, not a fetch wrapper — the server streams the CSR back as a PEM file with its own `content-disposition:
+ * attachment` header, so a caller renders this directly as `<a href={...}>` (the browser's own native download) —
+ * same pattern `dataExportApi.ts`'s `exportRequestDownloadUrl()` already establishes. */
+export declare function signingEnrollmentCsrUrl(enrollmentId: string): string;
+/** Uploads the certificate (or PEM chain, leaf first) a certificate authority issued for a request. Refused (400) with a message to act
+ * on when it doesn't fit the request (wrong key, not for e-mail, wrong address, expired); (409) when the request can no longer be
+ * completed (already issued/failed, or made before its mailbox's key was kept with it). */
+export declare function uploadSigningEnrollmentCertificate(enrollmentId: string, certificate: string, client?: ApiClient): Promise<CertificateUploadResult>;
+/** Refuses a pending request; `reason` is shown to the mailbox's owner. */
+export declare function rejectSigningEnrollment(enrollmentId: string, reason: string, client?: ApiClient): Promise<RejectEnrollmentResult>;
+/** A quick client-side sanity check of pasted/uploaded certificate text before it is sent to the server: at least one PEM certificate
+ * block. The server does the real validation (key match, e-mail usage, address, expiry) - this only catches an empty paste or an
+ * obviously wrong file (e.g. a private key) before a round trip. */
+export declare function looksLikePemCertificate(text: string): boolean;

package/dist/lib/crypto/signingProviderApi.js

@@ -0,0 +1,60 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s signing-certificate backend endpoints:
+ *
+ * - `getSigningEnrollmentInfo()` — `GET /system/signing-enrollment` (any signed-in user): which backend issues
+ * signing certificates in this deployment (`manual`, `rfc8823` or `none`), whether it's automatic, the
+ * certificate authority's host, a typical duration, whether an administrator can upload a certificate by hand,
+ * and how the background job's last contacts with the CA went. `@rapidmx/web-client`'s Encryption settings page
+ * uses this to word a request's status truthfully instead of assuming automatic issuance.
+ * - The administrator functions — `BaseSigningEnrollmentAdminRoute` (mounted at `admin/signing-enrollments`,
+ * trusted role AND an elevated token): list pending requests, download a request's CSR, upload the certificate a
+ * CA issued, or reject a request with a reason its owner sees. This is the manual-issuance workflow, and an
+ * escape hatch to inspect an automatic (`rfc8823`) request that has stalled.
+ */
+import { apiUrl, withClient } from "../util/api.js";
+/** The code a stale enrollment id (left over from a backend this deployment no longer runs) answers with - a client
+ * that sees this on a status check or a "check now" should clear the id and let the user request again. */
+export const SIGNING_ENROLLMENT_UNKNOWN = "signing-enrollment-unknown";
+const ADMIN_BASE = "/admin/signing-enrollments";
+/** `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 getSigningEnrollmentInfo(client) {
+    return withClient(client, `/system/signing-enrollment`);
+}
+/** The pending (and issued-but-not-yet-installed) signing-certificate requests, metadata only. Trusted role + elevated token required server-side. */
+export function listSigningEnrollments(client) {
+    return withClient(client, ADMIN_BASE);
+}
+/** A plain URL, not a fetch wrapper — the server streams the CSR back as a PEM file with its own `content-disposition:
+ * attachment` header, so a caller renders this directly as `<a href={...}>` (the browser's own native download) —
+ * same pattern `dataExportApi.ts`'s `exportRequestDownloadUrl()` already establishes. */
+export function signingEnrollmentCsrUrl(enrollmentId) {
+    return apiUrl(`${ADMIN_BASE}/${encodeURIComponent(enrollmentId)}/csr`);
+}
+/** Uploads the certificate (or PEM chain, leaf first) a certificate authority issued for a request. Refused (400) with a message to act
+ * on when it doesn't fit the request (wrong key, not for e-mail, wrong address, expired); (409) when the request can no longer be
+ * completed (already issued/failed, or made before its mailbox's key was kept with it). */
+export function uploadSigningEnrollmentCertificate(enrollmentId, certificate, client) {
+    return withClient(client, `${ADMIN_BASE}/${encodeURIComponent(enrollmentId)}/certificate`, {
+        method: "POST",
+        body: JSON.stringify({ certificate }),
+    });
+}
+/** Refuses a pending request; `reason` is shown to the mailbox's owner. */
+export function rejectSigningEnrollment(enrollmentId, reason, client) {
+    return withClient(client, `${ADMIN_BASE}/${encodeURIComponent(enrollmentId)}/reject`, {
+        method: "POST",
+        body: JSON.stringify({ reason }),
+    });
+}
+/** A quick client-side sanity check of pasted/uploaded certificate text before it is sent to the server: at least one PEM certificate
+ * block. The server does the real validation (key match, e-mail usage, address, expiry) - this only catches an empty paste or an
+ * obviously wrong file (e.g. a private key) before a round trip. */
+export function looksLikePemCertificate(text) {
+    return /-----BEGIN CERTIFICATE-----[\s\S]+-----END CERTIFICATE-----/.test(text);
+}

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

@@ -0,0 +1,128 @@
+/**
+ * The CMS (S/MIME) engine behind `specs/end-to-end_encryption.md`'s "Message Format" requirement
+ * ("RapidMX MUST use S/MIME (CMS) as the on-the-wire message format for both signatures and
+ * encryption"). This module operates on raw CMS structures (`SignedData`/`EnvelopedData`) via
+ * `pkijs` — the actual MIME assembly (`multipart/signed`, RFC 9788 header protection, the
+ * `application/pkcs7-mime` wrapping) is a distinct, mechanical layer built on top of these
+ * primitives, not implemented here.
+ *
+ * Certificates are always the base64-decoded DER bytes — the same wire format
+ * `keyvaultApi.ts`'s `PublicKey.publicKey` already uses — never PEM, so this module composes
+ * directly with values read from a `Mailbox`/`Contact`'s `keys` array with no reformatting.
+ */
+import "reflect-metadata";
+/**
+ * Thrown by `decryptEnvelopedData()` for content encrypted with a non-AEAD algorithm (e.g. AES-CBC, 3DES).
+ * Unauthenticated CBC content is malleable - an attacker who can't read the message can still flip
+ * plaintext bits or mount EFAIL-style exfiltration gadgets against the decrypted HTML - so it is rejected
+ * outright rather than rendered with a weaker indicator.
+ *
+ * Interop note: many legacy S/MIME clients still send AES-CBC `EnvelopedData`; those messages are
+ * undecryptable in RapidMX clients by design. Everything RapidMX itself sends uses AES-256-GCM.
+ */
+export declare class UnsupportedContentEncryptionError extends Error {
+    readonly algorithmOid: string;
+    constructor(algorithmOid: string);
+}
+/**
+ * Builds a detached CMS `SignedData` structure over `content`, per the spec's "Digital Signatures"
+ * section — detached, never opaque, so clients that don't understand S/MIME still render the
+ * message body. The signer's own certificate is embedded in the `certificates` field (never sent
+ * separately — unlike the encryption key, which travels in the `RapidMX-Key` header).
+ */
+export declare function signDetached(content: Uint8Array, signingCertDer: Uint8Array, signingPrivateKey: CryptoKey): Promise<Uint8Array>;
+export interface VerifyResult {
+    valid: boolean;
+    /** The certificate pkijs matched to the verified SignerInfo's `sid` (never merely the first embedded
+     * certificate) - present whenever `valid` is true. Callers
+     * compare its fingerprint against the pinned `Contact` key per the spec's Trust Model (TOFU);
+     * this function only proves the signature is mathematically valid over `content`, not that the
+     * certificate belongs to who the message claims. */
+    signerCertificateDer?: Uint8Array;
+}
+/** Verifies a detached CMS signature (as produced by `signDetached()`) against `content`. A parse
+ * failure or content-type mismatch is treated as an invalid signature (`valid: false`), not a thrown
+ * error - a malformed/foreign CMS blob is exactly the "signature failed" case the spec's Message
+ * Security Indicators table requires being able to render. */
+export declare function verifyDetached(content: Uint8Array, signatureDer: Uint8Array): Promise<VerifyResult>;
+/**
+ * Extracts every email address a certificate asserts, lowercased: SAN `rfc822Name` entries when the
+ * certificate has any (RFC 5280 §4.2.1.6 - SAN is authoritative when present), otherwise the subject's
+ * legacy `emailAddress` attributes plus a `CN` that is itself an email address (how this deployment's
+ * own self-signed/test certificates and many older CAs name a mailbox). Used by `messageSecurity.ts` to
+ * bind a signer certificate to the message's claimed sender. Returns `[]` for unparseable input -
+ * including a certificate whose SubjectAlternativeName extension pkijs couldn't parse (no `parsedValue`),
+ * which then fails the identity check (`signature_failed`) rather than throwing out of message evaluation.
+ */
+export declare function extractCertificateEmails(certDer: Uint8Array): string[];
+/**
+ * Builds an *opaque* (content embedded, not detached) CMS `SignedData` structure over `content`.
+ * Used only when the signed message is going to be encrypted immediately afterward (`buildMessage()`
+ * in `smimeMessage.ts` composes this with `encryptForRecipients()` for the combined sign-then-encrypt
+ * case) — the spec's "Digital Signatures" section requires *detached* signing only "for
+ * signature-only messages"; once the whole thing is being encrypted regardless, there is no legacy
+ * client ever exposed to this intermediate opaque layer, so embedding the content here (simpler than
+ * building a second detached `multipart/signed` entity solely to immediately encrypt it) is
+ * conformant, not a shortcut around that requirement.
+ */
+export declare function signOpaque(content: Uint8Array, signingCertDer: Uint8Array, signingPrivateKey: CryptoKey): Promise<Uint8Array>;
+export interface VerifyOpaqueResult extends VerifyResult {
+    /** The embedded content, recovered from the SignedData structure - only present when `valid`. */
+    content?: Uint8Array;
+}
+/** Verifies an opaque CMS signature (as produced by `signOpaque()`) and recovers its embedded
+ * content — unlike `verifyDetached()`, the content isn't supplied separately by the caller, since the
+ * whole point of an opaque signature is that it carries its own content. */
+export declare function verifyOpaque(signedDer: Uint8Array): Promise<VerifyOpaqueResult>;
+/**
+ * Builds a CMS `EnvelopedData` structure encrypting `content` to every certificate in
+ * `recipientCertDers` — per the spec's "Encrypt to Self" requirement, callers MUST include the
+ * sender's own encryption certificate in this list alongside the actual recipients' certificates, or
+ * the sender's own Sent-folder copy becomes unreadable to them.
+ */
+export declare function encryptForRecipients(content: Uint8Array, recipientCertDers: Uint8Array[]): Promise<Uint8Array>;
+/**
+ * Decrypts a CMS `EnvelopedData` structure using one recipient's own certificate/private key.
+ * `EnvelopedData` doesn't label which `RecipientInfo` belongs to which recipient in a way this
+ * function's own caller already knows in advance, so it tries every recipient slot in turn with the
+ * one keypair it has, succeeding on whichever slot was actually built for it and discarding the rest
+ * — the same shape as trying every wrapped-key entry in `KeyVault.masterKeyWraps` until one unwraps.
+ * A slot whose recipient identifier names this certificate is tried first. See
+ * `decryptEnvelopedDataWithKeys()` for several candidate keys.
+ */
+export declare function decryptEnvelopedData(envelopedDer: Uint8Array, recipientCertDer: Uint8Array, recipientPrivateKey: CryptoKey): Promise<Uint8Array>;
+/** One candidate decryption keypair for `decryptEnvelopedDataWithKeys()`. */
+export interface DecryptionKey {
+    /** Base64-decoded DER certificate of the key. */
+    certDer: Uint8Array;
+    privateKey: CryptoKey;
+}
+/** At most this many candidate keys are considered by `decryptEnvelopedDataWithKeys()` (further ones are ignored) - the
+ * active encryption key plus `keySession.ts`'s `MAX_RETAINED_ENCRYPTION_KEYS` retained ones. */
+export declare const MAX_DECRYPTION_KEYS = 21;
+/** Trial decryptions (a key tried against a slot whose recipient identifier doesn't name it) allowed for every key
+ * after the first, together. The first key keeps the unbounded every-slot trial `decryptEnvelopedData()` always did;
+ * this budget stops a message with many recipient slots from costing `slots x keys` ECDH operations. */
+export declare const MAX_TRIAL_DECRYPTIONS = 64;
+/**
+ * Decrypts a CMS `EnvelopedData` structure with whichever of several candidate keys it was encrypted to - the mailbox's
+ * active encryption key followed by the retained older ones (`keySession.ts`'s `retainedEncryptionKeys`), so mail
+ * encrypted to a key since replaced stays readable.
+ *
+ * **Matching first:** every recipient slot whose identifier (issuer and serial number, or subject key identifier) names
+ * a candidate's certificate is tried with that key, in candidate order - normally one decryption, no guessing.
+ * **Trial otherwise** (e.g. the sender encrypted to a reissued certificate for the same key): the first candidate is
+ * tried against every remaining slot, then the others in order, sharing `MAX_TRIAL_DECRYPTIONS`.
+ *
+ * Only the first `MAX_DECRYPTION_KEYS` candidates are considered. A candidate whose certificate can't be parsed is
+ * skipped (the parse error is thrown only when no candidate is usable). Throws `UnsupportedContentEncryptionError` for
+ * non-AEAD content, and the last decryption error when no key opens any slot.
+ */
+export declare function decryptEnvelopedDataWithKeys(envelopedDer: Uint8Array, keys: DecryptionKey[]): Promise<Uint8Array>;
+/** SHA-256 fingerprint of a DER certificate, hex encoded — matches `keyvaultApi.ts`'s own `PublicKey.
+ * fingerprint` format exactly, so a value computed here is directly comparable against one already on
+ * a `Mailbox`/`Contact` record. Used by `messageSecurity.ts` to compare a received message's embedded
+ * signer certificate against a pinned `Contact` key per the spec's Trust Model (TOFU) — `verifyDetached()`/
+ * `verifyOpaque()` only prove a signature is mathematically valid, never that the certificate belongs to
+ * who the message claims (see `VerifyResult`'s own doc comment). */
+export declare function computeCertFingerprint(certDer: Uint8Array): Promise<string>;