@rapidmx/web-client 0.21.0 → 0.22.0

package/lib/crypto/passwordUnlock.ts

@@ -0,0 +1,98 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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";
+
+export interface Argon2idParams {
+    /** Memory cost, in KiB. */
+    memorySize: number;
+    iterations: number;
+    parallelism: number;
+}
+
+/** 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: Argon2idParams = { 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: Argon2idParams): string {
+    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: string): Argon2idParams | undefined {
+    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): Uint8Array {
+    return crypto.getRandomValues(new Uint8Array(lengthBytes));
+}
+
+export interface PasswordDerivation {
+    /** Base64-encoded. See this module's own doc comment — not yet sent anywhere, reserved for a future
+     * server-side verification endpoint. */
+    authProof: string;
+    /** Never leaves the device. Passed directly to `masterKey.ts`'s `sealWithKey`/`openWithKey`. */
+    wrappingKey: Uint8Array;
+}
+
+/**
+ * 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: string,
+    salt: Uint8Array,
+    params: Argon2idParams = DEFAULT_ARGON2ID_PARAMS,
+): Promise<PasswordDerivation> {
+    // 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: Uint8Array = 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/lib/crypto/recoveryCode.ts

@@ -0,0 +1,93 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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: Uint8Array): string {
+    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(): string {
+    const bytes = crypto.getRandomValues(new Uint8Array(RECOVERY_CODE_ENTROPY_BYTES));
+    const encoded = base32Encode(bytes);
+    const groups: string[] = [];
+    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: string): string {
+    const compact = code
+        .replace(/[\s-]+/g, "")
+        .toUpperCase()
+        .replace(/O/g, "0")
+        .replace(/[IL]/g, "1");
+    const groups: string[] = [];
+    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: string, salt: Uint8Array): Promise<Uint8Array> {
+    const ikm = new TextEncoder().encode(normalizeRecoveryCode(code));
+    return hkdfDerive(ikm, salt, "wrap");
+}

package/lib/crypto/signingProviderApi.ts

@@ -0,0 +1,135 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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 { ApiClient, apiUrl, withClient } 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 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;
+}
+
+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?: ApiClient): Promise<SigningEnrollmentInfo> {
+    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?: ApiClient): Promise<AdminSigningEnrollment[]> {
+    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: string): string {
+    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: string,
+    certificate: string,
+    client?: ApiClient,
+): Promise<CertificateUploadResult> {
+    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: string, reason: string, client?: ApiClient): Promise<RejectEnrollmentResult> {
+    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: string): boolean {
+    return /-----BEGIN CERTIFICATE-----[\s\S]+-----END CERTIFICATE-----/.test(text);
+}