@rapidmx/web-client 0.21.0 → 0.23.0

package/dist/lib/contacts/vcard.js

@@ -0,0 +1,179 @@
+/** Escapes a text value (RFC 6350 §3.4): backslash, comma and semicolon are backslash-escaped, and every
+ * line break - CRLF, bare CR or bare LF - becomes `\n`, so a value can never break the content line. */
+function escapeVCardValue(value) {
+    return value
+        .replace(/\\/g, "\\\\")
+        .replace(/,/g, "\\,")
+        .replace(/;/g, "\\;")
+        .replace(/\r\n|\r|\n/g, "\\n");
+}
+/** Unescapes a text value in a single pass, so an escaped backslash followed by `n` (`\\n`) stays a
+ * literal backslash + `n` instead of becoming a newline. `\n`/`\N` is a newline; any other escaped
+ * character is itself. */
+function unescapeVCardValue(value) {
+    return value.replace(/\\([\s\S])/g, (_match, ch) => (ch === "n" || ch === "N" ? "\n" : ch));
+}
+/** Splits a structured value (`N`, `ADR`) on its unescaped `;` separators, then unescapes each component. */
+function splitStructuredValue(value) {
+    const components = [];
+    let current = "";
+    for (let i = 0; i < value.length; i++) {
+        const ch = value[i];
+        if (ch === "\\" && i + 1 < value.length) {
+            current += ch + value[++i];
+        }
+        else if (ch === ";") {
+            components.push(unescapeVCardValue(current));
+            current = "";
+        }
+        else {
+            current += ch;
+        }
+    }
+    components.push(unescapeVCardValue(current));
+    return components;
+}
+/** Builds a single vCard 3.0 record for one contact. */
+export function contactToVCard(contact) {
+    const lines = ["BEGIN:VCARD", "VERSION:3.0"];
+    lines.push(`N:${escapeVCardValue(contact.surname ?? "")};${escapeVCardValue(contact.givenName ?? "")};;;`);
+    lines.push(`FN:${escapeVCardValue(contact.displayName)}`);
+    if (contact.company) {
+        lines.push(`ORG:${escapeVCardValue(contact.company)}`);
+    }
+    if (contact.jobTitle) {
+        lines.push(`TITLE:${escapeVCardValue(contact.jobTitle)}`);
+    }
+    for (const email of contact.emails) {
+        lines.push(`EMAIL;TYPE=${email.type.toUpperCase()}:${escapeVCardValue(email.address)}`);
+    }
+    for (const phone of contact.phones) {
+        lines.push(`TEL;TYPE=${phone.type.toUpperCase()}:${escapeVCardValue(phone.phoneNumber)}`);
+    }
+    for (const address of contact.addresses) {
+        const parts = [
+            "",
+            "",
+            address.street ?? "",
+            address.city ?? "",
+            address.state ?? "",
+            address.postalCode ?? "",
+            address.country ?? "",
+        ];
+        lines.push(`ADR;TYPE=${address.type.toUpperCase()}:${parts.map(escapeVCardValue).join(";")}`);
+    }
+    if (contact.notes) {
+        lines.push(`NOTE:${escapeVCardValue(contact.notes)}`);
+    }
+    lines.push("END:VCARD");
+    return lines.join("\r\n");
+}
+/** Builds a single `.vcf` file's text content from multiple contacts (one `BEGIN:VCARD`/`END:VCARD` block
+ * per contact — the standard way multiple vCards share one file). */
+export function contactsToVCardFile(contacts) {
+    return contacts.map(contactToVCard).join("\r\n");
+}
+/** Index of the content line's name/value separator: the first `:` outside a quoted parameter value. */
+function valueSeparatorIndex(line) {
+    let inQuotes = false;
+    for (let i = 0; i < line.length; i++) {
+        if (line[i] === '"') {
+            inQuotes = !inQuotes;
+        }
+        else if (line[i] === ":" && !inQuotes) {
+            return i;
+        }
+    }
+    return -1;
+}
+/**
+ * Maps a property's type parameters onto `ContactAddressKind`: every `TYPE=` value (vCard 3/4, including
+ * comma lists and quoted lists like `TYPE="work,voice"`) plus vCard 2.1's bare parameters (`EMAIL;WORK:`)
+ * are collected case-insensitively; `work` wins, then `home`, and anything else (`internet`, `cell`,
+ * `pref`, no type at all) is `other`.
+ */
+function normalizeType(params) {
+    const tokens = new Set();
+    for (const param of params) {
+        const eq = param.indexOf("=");
+        const name = eq === -1 ? "TYPE" : param.slice(0, eq).trim().toUpperCase();
+        if (name !== "TYPE") {
+            continue;
+        }
+        for (const token of param.slice(eq + 1).replace(/"/g, "").split(",")) {
+            tokens.add(token.trim().toLowerCase());
+        }
+    }
+    return tokens.has("work") ? "work" : tokens.has("home") ? "home" : "other";
+}
+/**
+ * Parses one or more vCard 2.1/3.0/4.0 records from a `.vcf` file's text content. Deliberately tolerant of
+ * fields this app doesn't model (PHOTO, BDAY, etc. — silently ignored) and of the `TYPE=` parameter being
+ * absent (defaults to "other") — real-world exported vCards vary a lot in exactly which optional parameters
+ * they include. Folded lines (a line break followed by a space or tab) are unfolded first; property group
+ * prefixes (`item1.EMAIL`, as Apple Contacts writes) are ignored; `TYPE` values are normalized (see
+ * `normalizeType()`); structured values are split on unescaped `;` only.
+ */
+export function parseVCards(text) {
+    // Unfold first, then split only on a line that is exactly BEGIN:VCARD - a NOTE (or a folded line) that
+    // merely contains the text "BEGIN:VCARD" must not start a bogus record.
+    const unfolded = text.replace(/(?:\r\n|\r|\n)[ \t]/g, "");
+    const cards = unfolded.split(/^[ \t]*BEGIN:VCARD[ \t]*$/im).slice(1);
+    return cards.map((card) => {
+        const contact = { displayName: "", emails: [], phones: [], addresses: [] };
+        const lines = card.split(/\r\n|\r|\n/);
+        for (const rawLine of lines) {
+            const line = rawLine.trim();
+            const colonIndex = valueSeparatorIndex(line);
+            if (colonIndex === -1) {
+                continue;
+            }
+            const key = line.slice(0, colonIndex);
+            const rawValue = line.slice(colonIndex + 1);
+            const value = unescapeVCardValue(rawValue);
+            const [groupedName, ...params] = key.split(";");
+            const name = groupedName.slice(groupedName.lastIndexOf(".") + 1).toUpperCase();
+            const type = normalizeType(params);
+            switch (name) {
+                case "FN":
+                    contact.displayName = value;
+                    break;
+                case "N": {
+                    const [surname, given] = splitStructuredValue(rawValue);
+                    if (surname)
+                        contact.surname = surname;
+                    if (given)
+                        contact.givenName = given;
+                    break;
+                }
+                case "ORG":
+                    // ORG is structured too (organization;unit;...) - only the organization name is modeled.
+                    contact.company = splitStructuredValue(rawValue)[0];
+                    break;
+                case "TITLE":
+                    contact.jobTitle = value;
+                    break;
+                case "EMAIL":
+                    contact.emails.push({ address: value, type });
+                    break;
+                case "TEL":
+                    contact.phones.push({ phoneNumber: value, type });
+                    break;
+                case "ADR": {
+                    const [, , street, city, state, postalCode, country] = splitStructuredValue(rawValue);
+                    contact.addresses.push({ street, city, state, postalCode, country, type });
+                    break;
+                }
+                case "NOTE":
+                    contact.notes = value;
+                    break;
+                default:
+                    break;
+            }
+        }
+        if (!contact.displayName) {
+            contact.displayName = [contact.givenName, contact.surname].filter(Boolean).join(" ") || "Unnamed contact";
+        }
+        return contact;
+    });
+}

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

@@ -0,0 +1,67 @@
+/**
+ * Compose-time decision logic for `specs/end-to-end_encryption.md`'s Digital Signatures and Encryption
+ * sections — kept as pure, side-effect-free functions (no `fetch`, no crypto) precisely so the actual
+ * discovery round trip (`keyvaultApi.ts`'s `lookupKeys()`) and MIME assembly (`smimeMessage.ts`) stay in
+ * the caller (`ComposeWindow.tsx`), which owns the async orchestration and error handling; this module
+ * only decides *what* a compose window should do once it has the facts.
+ *
+ * **Recipient tier classification is a client-side approximation.** The spec's three tiers
+ * (`specs/end-to-end_encryption.md`'s "Terminology": same-organisation / federated peer / external) are
+ * a server-side administrative concept - "the specific RapidMX server and the domains it controls" - that
+ * `@rapidmx/restapi` 0.6.0 does not actually expose to the client (`KeyLookupResult`/`KeyringUpdate`
+ * carry no tier field; confirmed by reading `util/KeyringUtils.ts`). `classifyRecipientTier()` below
+ * approximates it as "same domain as the sender's own address" vs. "a domain discovery found keys for"
+ * vs. "everything else" - the same domain-suffix heuristic used elsewhere for this class of judgment,
+ * not a guarantee. A real fix would be a restapi endpoint exposing which domains a server actually
+ * controls; until then this is a disclosed approximation, not a silent one.
+ */
+import { type EncryptionPolicy, type KeyLookupResult, type PublicKey } from "./keyvaultApi.js";
+export type RecipientTier = "sameOrg" | "federated" | "external";
+/** See this module's own doc comment for why this is an approximation, not an authoritative classification. */
+export declare function classifyRecipientTier(ownAddress: string, recipientAddress: string, hasDiscoveredKeys: boolean): RecipientTier;
+export interface RecipientEncryptionStatus {
+    address: string;
+    tier: RecipientTier;
+    /** The recipient's currently-active encryption certificate, if they have published (and this device
+     * has discovered) one. */
+    encryptCert?: PublicKey;
+    /** Whether this recipient *can* be encrypted to at all right now - false when there's no usable key,
+     * or the tier's policy is `prohibited`. */
+    canEncrypt: boolean;
+    /** Whether encryption should default ON for this recipient specifically: per spec, "MUST default to
+     * on only when both parties advertise mutual" AND the tier's policy is `automatic`. */
+    autoEncrypt: boolean;
+    /** Set (non-undefined) exactly when policy blocks encryption outright for this recipient's tier - the
+     * spec: "the client MUST explain why encryption is unavailable rather than silently omitting the
+     * control." `undefined` in every other case, including "no key found," which is not a policy block. */
+    prohibitedReason?: string;
+}
+/** Per-recipient encryption eligibility, given this device's own encryption preference and the
+ * system-wide policy. One entry per (address, lookup result) pair the caller already resolved via
+ * `lookupKeys()` - this function does no discovery itself. */
+export declare function resolveRecipientEncryption(ownAddress: string, ownPrefersMutual: boolean, policy: EncryptionPolicy, recipientAddress: string, lookup: KeyLookupResult | undefined): RecipientEncryptionStatus;
+export interface MessageEncryptionDecision {
+    /** Whether the compose window's encryption toggle should default to checked - true only when every
+     * recipient independently defaults to encrypted. Seeds the toggle's *initial* state only; the user
+     * can still turn it on manually even when this is false, subject to `canEncryptAll`. */
+    autoEncrypt: boolean;
+    /** Every recipient the message *could* be encrypted to right now. */
+    canEncryptAll: boolean;
+    /** Recipients that cannot currently be encrypted to (no key, or policy-prohibited) - the spec's
+     * "Multiple Recipients" all-or-nothing case: when this is non-empty and the user still wants
+     * encryption, the client MUST offer to send in plaintext or remove these recipients, never split. */
+    blockedRecipients: RecipientEncryptionStatus[];
+}
+/** Combines every recipient's individual status into the one decision a compose window's UI actually
+ * needs: whether to default the toggle on, and whether an all-or-nothing prompt is required. */
+export declare function decideMessageEncryption(recipients: RecipientEncryptionStatus[]): MessageEncryptionDecision;
+/** Detects list traffic per the spec's "Mailing lists" note under Digital Signatures: a footer a list
+ * appends after signing invalidates the signature, so the client MAY suppress signing for it. `headers`
+ * is whatever the caller already has on hand (e.g. a `Contact`'s known list-membership flag) - this
+ * module has no way to inspect list membership itself, so it just applies the rule to inputs the caller
+ * supplies. Currently unused by any caller (no UI surfaces distribution-list membership to compose yet -
+ * a disclosed gap, not a silent one; see this module's own file-level doc comment). */
+export declare function isLikelyMailingList(headers: {
+    listId?: string;
+    listUnsubscribe?: string;
+}): boolean;

package/dist/lib/crypto/composeSecurity.js

@@ -0,0 +1,93 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Compose-time decision logic for `specs/end-to-end_encryption.md`'s Digital Signatures and Encryption
+ * sections — kept as pure, side-effect-free functions (no `fetch`, no crypto) precisely so the actual
+ * discovery round trip (`keyvaultApi.ts`'s `lookupKeys()`) and MIME assembly (`smimeMessage.ts`) stay in
+ * the caller (`ComposeWindow.tsx`), which owns the async orchestration and error handling; this module
+ * only decides *what* a compose window should do once it has the facts.
+ *
+ * **Recipient tier classification is a client-side approximation.** The spec's three tiers
+ * (`specs/end-to-end_encryption.md`'s "Terminology": same-organisation / federated peer / external) are
+ * a server-side administrative concept - "the specific RapidMX server and the domains it controls" - that
+ * `@rapidmx/restapi` 0.6.0 does not actually expose to the client (`KeyLookupResult`/`KeyringUpdate`
+ * carry no tier field; confirmed by reading `util/KeyringUtils.ts`). `classifyRecipientTier()` below
+ * approximates it as "same domain as the sender's own address" vs. "a domain discovery found keys for"
+ * vs. "everything else" - the same domain-suffix heuristic used elsewhere for this class of judgment,
+ * not a guarantee. A real fix would be a restapi endpoint exposing which domains a server actually
+ * controls; until then this is a disclosed approximation, not a silent one.
+ */
+import { findActivePublicKey } from "./keyvaultApi.js";
+/** See this module's own doc comment for why this is an approximation, not an authoritative classification. */
+export function classifyRecipientTier(ownAddress, recipientAddress, hasDiscoveredKeys) {
+    const ownDomain = ownAddress.split("@")[1]?.toLowerCase();
+    const recipientDomain = recipientAddress.split("@")[1]?.toLowerCase();
+    if (ownDomain && recipientDomain && ownDomain === recipientDomain) {
+        return "sameOrg";
+    }
+    return hasDiscoveredKeys ? "federated" : "external";
+}
+function policyStateForTier(policy, tier) {
+    switch (tier) {
+        case "sameOrg":
+            return policy.encryptSameOrg;
+        case "federated":
+            return policy.encryptFederated;
+        case "external":
+            return policy.encryptExternal;
+    }
+}
+/** Per-recipient encryption eligibility, given this device's own encryption preference and the
+ * system-wide policy. One entry per (address, lookup result) pair the caller already resolved via
+ * `lookupKeys()` - this function does no discovery itself. */
+export function resolveRecipientEncryption(ownAddress, ownPrefersMutual, policy, recipientAddress, lookup) {
+    const encryptCert = lookup ? findActivePublicKey(lookup.keys, "encrypt") : undefined;
+    const tier = classifyRecipientTier(ownAddress, recipientAddress, !!lookup && lookup.keys.length > 0);
+    const policyState = policyStateForTier(policy, tier);
+    if (policyState === "prohibited") {
+        return {
+            address: recipientAddress,
+            tier,
+            encryptCert,
+            canEncrypt: false,
+            autoEncrypt: false,
+            prohibitedReason: "Your organization's encryption policy does not allow encrypting messages to this recipient.",
+        };
+    }
+    if (!encryptCert) {
+        return { address: recipientAddress, tier, canEncrypt: false, autoEncrypt: false };
+    }
+    const recipientPrefersMutual = lookup?.encryptPreference?.preferEncrypt === "mutual";
+    const mutual = ownPrefersMutual && recipientPrefersMutual;
+    return {
+        address: recipientAddress,
+        tier,
+        encryptCert,
+        canEncrypt: true,
+        autoEncrypt: policyState === "automatic" && mutual,
+    };
+}
+/** Combines every recipient's individual status into the one decision a compose window's UI actually
+ * needs: whether to default the toggle on, and whether an all-or-nothing prompt is required. */
+export function decideMessageEncryption(recipients) {
+    if (recipients.length === 0) {
+        return { autoEncrypt: false, canEncryptAll: false, blockedRecipients: [] };
+    }
+    const blockedRecipients = recipients.filter((r) => !r.canEncrypt);
+    return {
+        autoEncrypt: recipients.every((r) => r.autoEncrypt),
+        canEncryptAll: blockedRecipients.length === 0,
+        blockedRecipients,
+    };
+}
+/** Detects list traffic per the spec's "Mailing lists" note under Digital Signatures: a footer a list
+ * appends after signing invalidates the signature, so the client MAY suppress signing for it. `headers`
+ * is whatever the caller already has on hand (e.g. a `Contact`'s known list-membership flag) - this
+ * module has no way to inspect list membership itself, so it just applies the rule to inputs the caller
+ * supplies. Currently unused by any caller (no UI surfaces distribution-list membership to compose yet -
+ * a disclosed gap, not a silent one; see this module's own file-level doc comment). */
+export function isLikelyMailingList(headers) {
+    return !!(headers.listId || headers.listUnsubscribe);
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Plain base64/base64url <-> `Uint8Array` conversions shared by every `crypto/*` module. Deliberately
+ * `Buffer`-free — this code runs in a browser tab and an Electron renderer alike, and `Buffer` is not
+ * guaranteed to exist in either without a bundler polyfill.
+ */
+export declare function toBase64(bytes: Uint8Array): string;
+export declare function fromBase64(base64: string): Uint8Array;
+export declare function toBase64Url(bytes: Uint8Array): string;
+export declare function fromBase64Url(base64url: string): Uint8Array;

package/dist/lib/crypto/encoding.js

@@ -0,0 +1,32 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Plain base64/base64url <-> `Uint8Array` conversions shared by every `crypto/*` module. Deliberately
+ * `Buffer`-free — this code runs in a browser tab and an Electron renderer alike, and `Buffer` is not
+ * guaranteed to exist in either without a bundler polyfill.
+ */
+export function toBase64(bytes) {
+    let binary = "";
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary);
+}
+export function fromBase64(base64) {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+export function toBase64Url(bytes) {
+    return toBase64(bytes).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+export function fromBase64Url(base64url) {
+    const padded = base64url.replace(/-/g, "+").replace(/_/g, "/");
+    const padding = padded.length % 4 === 0 ? "" : "=".repeat(4 - (padded.length % 4));
+    return fromBase64(padded + padding);
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Generates an escrow scope's key pair in the browser, for an administrator setting up escrow without an existing
+ * PKI. The certificate goes to the server (as the scope's public key, which mailbox master keys are wrapped to);
+ * the private key never does - the administrator must download it and hand it to the scope's holders, whose
+ * offline tooling is the only thing that can ever unwrap an escrowed master key. Losing it makes every escrow
+ * wrap made to this scope permanently unusable.
+ *
+ * The key is P-256, like every other key in this app: the certificate is signed with it as ECDSA, and holders
+ * re-import the same key material as ECDH to decrypt (see `keys.ts`'s `importPrivateKeyPkcs8()`).
+ */
+import "reflect-metadata";
+import type { EscrowScopePublicKey } from "../admin/escrowScopesApi.js";
+export interface GeneratedEscrowKeys {
+    certificateDer: Uint8Array;
+    certificatePem: string;
+    /** PKCS#8, PEM encoded. */
+    privateKeyPem: string;
+    /** Ready to pass as `createEscrowScope()`'s `publicKey`. */
+    publicKey: EscrowScopePublicKey;
+}
+export declare function generateEscrowKeyPair(options: {
+    name: string;
+    validDays: number;
+    now?: Date;
+}): Promise<GeneratedEscrowKeys>;

package/dist/lib/crypto/escrowKeys.js

@@ -0,0 +1,59 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Generates an escrow scope's key pair in the browser, for an administrator setting up escrow without an existing
+ * PKI. The certificate goes to the server (as the scope's public key, which mailbox master keys are wrapped to);
+ * the private key never does - the administrator must download it and hand it to the scope's holders, whose
+ * offline tooling is the only thing that can ever unwrap an escrowed master key. Losing it makes every escrow
+ * wrap made to this scope permanently unusable.
+ *
+ * The key is P-256, like every other key in this app: the certificate is signed with it as ECDSA, and holders
+ * re-import the same key material as ECDH to decrypt (see `keys.ts`'s `importPrivateKeyPkcs8()`).
+ */
+import "reflect-metadata";
+import * as x509 from "@peculiar/x509";
+import { toBase64 } from "./encoding.js";
+import { computeCertFingerprint } from "./smime.js";
+x509.cryptoProvider.set(crypto);
+const DAY_MS = 24 * 60 * 60 * 1000;
+function toPem(label, der) {
+    const lines = toBase64(der).match(/.{1,64}/g) ?? [];
+    return `-----BEGIN ${label}-----\n${lines.join("\n")}\n-----END ${label}-----\n`;
+}
+/** A random, positive certificate serial number, hex encoded. */
+function randomSerial() {
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    bytes[0] &= 0x7f;
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+export async function generateEscrowKeyPair(options) {
+    const notBefore = options.now ?? new Date();
+    const notAfter = new Date(notBefore.getTime() + options.validDays * DAY_MS);
+    const keys = (await crypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, true, ["sign", "verify"]));
+    const certificate = await x509.X509CertificateGenerator.createSelfSigned({
+        serialNumber: randomSerial(),
+        // Structural name, never string-interpolated - see keys.ts's identical note on RDN injection.
+        name: [{ CN: [options.name] }],
+        notBefore,
+        notAfter,
+        signingAlgorithm: { name: "ECDSA", hash: "SHA-256" },
+        keys,
+        extensions: [new x509.KeyUsagesExtension(x509.KeyUsageFlags.keyAgreement | x509.KeyUsageFlags.digitalSignature, true)],
+    });
+    const certificateDer = new Uint8Array(certificate.rawData);
+    const privateKeyDer = new Uint8Array(await crypto.subtle.exportKey("pkcs8", keys.privateKey));
+    return {
+        certificateDer,
+        certificatePem: toPem("CERTIFICATE", certificateDer),
+        privateKeyPem: toPem("PRIVATE KEY", privateKeyDer),
+        publicKey: {
+            publicKey: toBase64(certificateDer),
+            type: "x509",
+            fingerprint: await computeCertFingerprint(certificateDer),
+            notBefore: notBefore.getTime(),
+            notAfter: notAfter.getTime(),
+        },
+    };
+}

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

@@ -0,0 +1,16 @@
+/** The default for a device that has never set a preference - conservative enough for a shared/public
+ * machine without being disruptive on a personal one. */
+export declare const DEFAULT_IDLE_TIMEOUT_MINUTES = 30;
+/** `0` means "never" - the idle timer is disabled entirely. */
+export declare const IDLE_TIMEOUT_OPTIONS_MINUTES: readonly [5, 15, 30, 60, 0];
+/**
+ * Reads this device's configured idle-timeout duration, in minutes. Falls back to
+ * `DEFAULT_IDLE_TIMEOUT_MINUTES` for a never-configured device, a corrupted/non-numeric stored value,
+ * or a `localStorage` access that throws (private-browsing/storage-blocked contexts) - never throws
+ * itself, since a broken read here must not be able to prevent the app from rendering at all.
+ */
+export declare function getIdleTimeoutMinutes(): number;
+/** Persists this device's idle-timeout preference. A `localStorage` write failure is swallowed, not
+ * thrown - the setting just doesn't survive a reload in that case, same fallback-to-default behavior
+ * `getIdleTimeoutMinutes()` already has for a storage-blocked context. */
+export declare function setIdleTimeoutMinutes(minutes: number): void;

package/dist/lib/crypto/idleTimeout.js

@@ -0,0 +1,47 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The configured idle-timeout duration behind `useIdleKeyTimeout()` — the spec's own "configurable
+ * idle period" trigger for `keySession.ts`'s `destroyUnlockedKeys()`. Stored in `localStorage`, not
+ * synced to the server: it's a per-device preference about *this browser's* own in-memory key cache,
+ * the same "never persisted anywhere durable" posture `keySession.ts` itself takes for the keys this
+ * setting protects.
+ */
+const STORAGE_KEY = "rapidmx:idle-timeout-minutes";
+/** The default for a device that has never set a preference - conservative enough for a shared/public
+ * machine without being disruptive on a personal one. */
+export const DEFAULT_IDLE_TIMEOUT_MINUTES = 30;
+/** `0` means "never" - the idle timer is disabled entirely. */
+export const IDLE_TIMEOUT_OPTIONS_MINUTES = [5, 15, 30, 60, 0];
+/**
+ * Reads this device's configured idle-timeout duration, in minutes. Falls back to
+ * `DEFAULT_IDLE_TIMEOUT_MINUTES` for a never-configured device, a corrupted/non-numeric stored value,
+ * or a `localStorage` access that throws (private-browsing/storage-blocked contexts) - never throws
+ * itself, since a broken read here must not be able to prevent the app from rendering at all.
+ */
+export function getIdleTimeoutMinutes() {
+    try {
+        const stored = localStorage.getItem(STORAGE_KEY);
+        if (stored === null) {
+            return DEFAULT_IDLE_TIMEOUT_MINUTES;
+        }
+        const parsed = Number(stored);
+        return Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_IDLE_TIMEOUT_MINUTES;
+    }
+    catch {
+        return DEFAULT_IDLE_TIMEOUT_MINUTES;
+    }
+}
+/** Persists this device's idle-timeout preference. A `localStorage` write failure is swallowed, not
+ * thrown - the setting just doesn't survive a reload in that case, same fallback-to-default behavior
+ * `getIdleTimeoutMinutes()` already has for a storage-blocked context. */
+export function setIdleTimeoutMinutes(minutes) {
+    try {
+        localStorage.setItem(STORAGE_KEY, String(minutes));
+    }
+    catch {
+        // Best-effort - see this function's own doc comment.
+    }
+}