@rapidmx/web-client 0.20.0 → 0.22.0

package/dist/lib/crypto/smimeMessage.js

@@ -0,0 +1,341 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * MIME assembly around `smime.ts`'s CMS primitives, implementing `specs/end-to-end_encryption.md`'s
+ * "Header Protection" requirement — RFC 9788, not the older, spec-forbidden RFC 8551 §3.1
+ * `message/rfc822`-wrapping approach.
+ *
+ * RFC 9788's actual mechanism (verified against the RFC text directly, not assumed from memory,
+ * given how easy it is to get a narrow/recent spec wrong from recollection alone): protected header
+ * fields are **not** wrapped in a `multipart/mixed` gutter part. They become literal header lines
+ * prepended directly to the MIME entity that is signed/encrypted (the "Cryptographic Payload"),
+ * whose own `Content-Type` gains an `hp="clear"` (signed-only) or `hp="cipher"` (encrypted) parameter.
+ * For encrypted messages, `HP-Outer: <Field>: <value>` lines carry a copy of the outer envelope's
+ * headers inside the protected payload, so a recipient can detect outer-header tampering. The outer,
+ * unprotected envelope keeps real `From`/`To`/`Cc`/`Date` values but MUST obscure `Subject` to the
+ * literal `"[...]"` under `hcp_baseline` — RFC 9788's own required minimum default policy (a
+ * conformant MUA "MUST have a default HCP that offers confidentiality for the Subject Header Field at
+ * least" — Section 3.3); this module implements exactly that baseline, not the more ambitious
+ * `hcp_shy` policy (which also strips display names and normalizes Date to UTC).
+ *
+ * Combined sign-then-encrypt uses **opaque** signing (`smime.ts`'s `signOpaque()`), embedding the
+ * `hp="cipher"`-tagged content inside an `application/pkcs7-mime; smime-type="signed-data"` entity,
+ * which is then itself the plaintext encrypted into the final `enveloped-data` — matching the nesting
+ * RFC 9788's own worked example uses (outer enveloped-data → decrypts to signed-data → unwraps to the
+ * real `hp="cipher"` content), not a `multipart/signed` structure encrypted as a whole.
+ */
+import { toBase64 } from "./encoding.js";
+import { binaryStringToBytes, bytesToBinaryString, decodeBase64Text, decodeBodyText, decodeHeaderText, encodeAddressListHeaderValue, encodeUnstructuredHeaderValue, isBinaryString, extractAttachments, extractDisplayBody, parseMimeEntity, parseParameterizedHeader, splitMultipart, } from "./mime.js";
+import { decryptEnvelopedDataWithKeys, encryptForRecipients, signDetached, signOpaque, UnsupportedContentEncryptionError, verifyDetached, verifyOpaque, } from "./smime.js";
+const CRLF = "\r\n";
+/** RFC 2045's own line-length limit for base64-encoded body content. */
+const BASE64_LINE_WIDTH = 76;
+/** RFC 9788's `hcp_baseline` Header Confidentiality Policy — the RFC's own required minimum default
+ * (Section 3.3). Applied to produce the OUTER, unprotected envelope's headers from the real
+ * (protected) ones; `From`/`To`/`Cc`/`Date` pass through unchanged, `Subject` is obscured. */
+export function applyBaselineOuterHeaders(headers) {
+    return { ...headers, subject: "[...]" };
+}
+function base64Wrapped(bytes) {
+    const encoded = toBase64(bytes);
+    const lines = [];
+    for (let i = 0; i < encoded.length; i += BASE64_LINE_WIDTH) {
+        lines.push(encoded.slice(i, i + BASE64_LINE_WIDTH));
+    }
+    return lines.join(CRLF);
+}
+function generateBoundary() {
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    return `----=_RapidMX_${Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("")}`;
+}
+/** Strips CR/LF/NUL from a header value that has no further encoding (Date, Message-ID, Content-Type). */
+function flattenHeaderValue(value) {
+    return value.replace(/[\r\n\0]+/g, " ");
+}
+/**
+ * Serializes `headers` as RFC 5322 header lines, safely: CR/LF/NUL in any value become a space (so a
+ * caller-supplied Subject or display name can never inject an extra header or end the header block), and
+ * non-ASCII Subject text / display names are RFC 2047-encoded (`mime.ts`'s `encode*HeaderValue()`). The
+ * protected copy, the `HP-Outer` copy and the outer envelope all go through this same deterministic
+ * encoding, so the receive-side comparisons between them still compare like with like.
+ */
+function headerLines(headers, prefix = "") {
+    return [
+        `${prefix}From: ${encodeAddressListHeaderValue(headers.from)}`,
+        `${prefix}To: ${encodeAddressListHeaderValue(headers.to)}`,
+        ...(headers.cc ? [`${prefix}Cc: ${encodeAddressListHeaderValue(headers.cc)}`] : []),
+        `${prefix}Date: ${flattenHeaderValue(headers.date)}`,
+        `${prefix}Subject: ${encodeUnstructuredHeaderValue(headers.subject)}`,
+        ...(prefix ? [] : [`Message-ID: ${flattenHeaderValue(headers.messageId)}`]),
+    ];
+}
+function protectedHeaderLines(headers, hpOuter) {
+    const lines = headerLines(headers);
+    if (hpOuter) {
+        // RFC 9788 Section 2.2.1's `hp-outer` field: the literal string "HP-Outer:" followed by the
+        // original field name and its (outer, possibly-obscured) value. Written on every encrypted
+        // message per the spec, and compared against the actual outer envelope on receipt by
+        // parseEncryptedMessage() (see ParsedEncryptedMessage.headerTamperDetected).
+        lines.push(...headerLines(hpOuter, "HP-Outer: "));
+    }
+    return lines.join(CRLF);
+}
+/**
+ * Builds a detached `multipart/signed` message with RFC 9788 header protection (`hp="clear"`) — per
+ * the spec, the only form signature-only messages may use (opaque signing is reserved for the
+ * sign-then-encrypt case in `buildEncryptedMessage()`, where no legacy client is ever exposed to it).
+ */
+export async function buildSignedOnlyMessage(bodyContentType, bodyText, protectedHeaders, signingCertDer, signingPrivateKey) {
+    const boundary = generateBoundary();
+    // Base64 so the signed bytes survive transport unchanged: a raw UTF-8 body is usually one long line, which
+    // MTAs rewrap past 998 characters and so break the detached signature.
+    const innerEntity = [
+        protectedHeaderLines(protectedHeaders),
+        `Content-Type: ${flattenHeaderValue(bodyContentType)}; hp="clear"`,
+        `Content-Transfer-Encoding: base64`,
+        "",
+        base64Wrapped(new TextEncoder().encode(bodyText)),
+    ].join(CRLF);
+    const signature = await signDetached(new TextEncoder().encode(innerEntity), signingCertDer, signingPrivateKey);
+    const body = [
+        `--${boundary}`,
+        innerEntity,
+        `--${boundary}`,
+        `Content-Type: application/pkcs7-signature; name="smime.p7s"`,
+        `Content-Transfer-Encoding: base64`,
+        `Content-Disposition: attachment; filename="smime.p7s"`,
+        "",
+        base64Wrapped(signature),
+        `--${boundary}--`,
+    ].join(CRLF);
+    return { contentType: `multipart/signed; protocol="application/pkcs7-signature"; micalg=sha-256; boundary="${boundary}"`, body };
+}
+const SIGNATURE_CONTENT_TYPES = new Set(["application/pkcs7-signature", "application/x-pkcs7-signature"]);
+const PKCS7_MIME_CONTENT_TYPES = new Set(["application/pkcs7-mime", "application/x-pkcs7-mime"]);
+/** Parses and verifies a `multipart/signed` message (RFC 1847/8551). Returns `{ verified: false }` (never
+ * throws) for anything malformed — same "degrade to a failed-signature state, don't crash" contract as
+ * `smime.ts`'s own verify functions. Accepts foreign-MUA framing: unquoted/case-varied parameters,
+ * preamble/epilogue, transport padding, and a signed part stored with bare-LF line endings (retried in
+ * canonical CRLF form, which is what RFC 8551 §3.1.1 says was actually signed). The body must hold exactly two
+ * parts (RFC 1847 §2.1): a third part isn't covered by the signature, so a message carrying one is rejected
+ * rather than shown - partly unsigned - under a verified badge. */
+export async function parseSignedOnlyMessage(contentType, body) {
+    const boundary = parseParameterizedHeader(contentType).params["boundary"];
+    if (!boundary) {
+        return { verified: false };
+    }
+    const parts = splitMultipart(body, boundary);
+    if (parts.length !== 2) {
+        return { verified: false };
+    }
+    const [innerText, signaturePartText] = parts;
+    const signaturePart = parseMimeEntity(signaturePartText);
+    if (!SIGNATURE_CONTENT_TYPES.has(parseParameterizedHeader(signaturePart.headers["content-type"]).value)) {
+        return { verified: false };
+    }
+    // The signature part is always base64 in practice (binary DER can't survive a text transport); a
+    // missing Content-Transfer-Encoding header is treated as base64 too, matching common senders.
+    const signatureDer = decodeBase64Text(signaturePart.body);
+    if (!signatureDer || signatureDer.length === 0) {
+        return { verified: false };
+    }
+    // The signed part's exact bytes: a binary string (see `mime.ts`) maps back to them one code unit per
+    // byte; a string that was already decoded as text is UTF-8 encoded instead. A binary string holding
+    // non-ASCII is also tried as UTF-8 text, for a caller that decoded an all-Latin-1 message itself. Each
+    // form is retried in canonical CRLF form. Trying several byte forms is safe: each must still verify.
+    const canonical = innerText.replace(/\r?\n/g, CRLF);
+    const candidates = [];
+    for (const text of canonical === innerText ? [innerText] : [innerText, canonical]) {
+        candidates.push(binaryStringToBytes(text));
+        if (isBinaryString(text) && /[\x80-\xff]/.test(text)) {
+            candidates.push(new TextEncoder().encode(text));
+        }
+    }
+    let result = { valid: false };
+    for (const candidate of candidates) {
+        result = await verifyDetached(candidate, signatureDer);
+        if (result.valid) {
+            break;
+        }
+    }
+    if (!result.valid) {
+        return { verified: false };
+    }
+    const inner = parseMimeEntity(innerText);
+    return {
+        verified: true,
+        signerCertificateDer: result.signerCertificateDer,
+        protectedHeaders: headersToProtectedHeaders(inner.headers),
+        protectedHeaderFields: inner.fields,
+        bodyContentType: inner.headers["content-type"],
+        bodyText: decodeBodyText(inner),
+        displayBody: extractDisplayBody(inner),
+        attachments: extractAttachments(inner),
+    };
+}
+/**
+ * Builds an `application/pkcs7-mime; smime-type="enveloped-data"` message with RFC 9788 header
+ * protection (`hp="cipher"`), optionally sign-then-encrypt when `signing` is supplied (opaque
+ * signing — see this module's own doc comment for why). Per the spec's "Encrypt to Self"
+ * requirement, `recipientCertDers` MUST include the sender's own encryption certificate.
+ */
+export async function buildEncryptedMessage(bodyContentType, bodyText, protectedHeaders, outerHeaders, recipientCertDers, signing) {
+    const plaintextEntity = [
+        protectedHeaderLines(protectedHeaders, outerHeaders),
+        `Content-Type: ${flattenHeaderValue(bodyContentType)}; hp="cipher"`,
+        "",
+        bodyText,
+    ].join(CRLF);
+    let contentToEncrypt;
+    if (signing) {
+        const signedDer = await signOpaque(new TextEncoder().encode(plaintextEntity), signing.certDer, signing.privateKey);
+        contentToEncrypt = new TextEncoder().encode([
+            `Content-Type: application/pkcs7-mime; smime-type="signed-data"; name="smime.p7m"`,
+            `Content-Transfer-Encoding: base64`,
+            "",
+            base64Wrapped(signedDer),
+        ].join(CRLF));
+    }
+    else {
+        contentToEncrypt = new TextEncoder().encode(plaintextEntity);
+    }
+    const envelopedDer = await encryptForRecipients(contentToEncrypt, recipientCertDers);
+    return {
+        contentType: `application/pkcs7-mime; smime-type="enveloped-data"; name="smime.p7m"`,
+        additionalHeaders: { "Content-Transfer-Encoding": "base64", "Content-Disposition": 'attachment; filename="smime.p7m"' },
+        body: base64Wrapped(envelopedDer),
+    };
+}
+/**
+ * Combines a `MimePart` (from `buildSignedOnlyMessage()`/`buildEncryptedMessage()`) with the outer
+ * envelope's own headers into one complete RFC 5322 message source, ready for `mailApi.ts`'s
+ * `assembleDraftRaw()`. `outerHeaders` MUST be the already-obscured headers for an encrypted message
+ * (`applyBaselineOuterHeaders()`'s output) - this function does no obscuring itself, it only serializes
+ * whatever headers it's given. Deliberately excludes `Bcc`: that recipient list is submission-only and
+ * must never appear as a message header (see `AssembleDraftRawInput`'s own doc comment - `bcc` is passed
+ * to that call separately, never baked into `rawMime`). Header values are sanitized and RFC 2047-encoded
+ * the same way as the protected headers (see `headerLines()`).
+ */
+export function assembleOutboundMime(outerHeaders, part) {
+    const lines = [
+        ...headerLines(outerHeaders),
+        `MIME-Version: 1.0`,
+        `Content-Type: ${flattenHeaderValue(part.contentType)}`,
+        ...Object.entries(part.additionalHeaders ?? {}).map(([key, value]) => `${flattenHeaderValue(key)}: ${flattenHeaderValue(value)}`),
+        "",
+        part.body,
+    ];
+    return lines.join(CRLF);
+}
+/** Extracts the outer-envelope header values RFC 9788's `HP-Outer: <Field>: <value>` mechanism embeds
+ * inside an encrypted message's protected content - one line per outer header, all sharing the literal
+ * field name `HP-Outer`, which `splitHeadersAndBody()`'s own flat header map can hold only the last of
+ * (a real bug if reused for this - JSON/`Record` keys aren't multi-valued). Scans the raw header block
+ * text directly instead. Returns `undefined` when no `HP-Outer:` lines are present at all, so a caller
+ * can distinguish "nothing to compare" from "compared and everything matched". */
+function extractHpOuterHeaders(fields) {
+    const result = {};
+    let found = false;
+    for (const { name, value } of fields) {
+        const match = name.toLowerCase() === "hp-outer" ? /^(From|To|Cc|Date|Subject):\s*(.*)$/i.exec(value) : null;
+        if (!match) {
+            continue;
+        }
+        found = true;
+        result[match[1].toLowerCase()] = match[2].trim();
+    }
+    return found ? result : undefined;
+}
+/** `true` when every field `hpOuter` actually carries matches `actualOuterHeaders`' value for that same
+ * field - a field `hpOuter` doesn't carry (e.g. no `Cc` on this message) is not compared, since RFC
+ * 9788 never claims coverage for it either way. */
+function outerHeadersMatch(hpOuter, actualOuterHeaders) {
+    return Object.keys(hpOuter).every((field) => hpOuter[field] === actualOuterHeaders[field]);
+}
+/** Decrypts (and, if present, verifies the inner signature of) a message built by
+ * `buildEncryptedMessage()`. Returns `{ decrypted: false }` (never throws) for anything malformed or
+ * undecryptable with the given key — the caller's own concern is distinguishing "wrong key" from
+ * "corrupt message," neither of which this function treats as exceptional.
+ *
+ * `actualOuterHeaders` — the received message's real, unprotected outer envelope headers (as the
+ * caller itself read them, before ever calling this function) — enables the RFC 9788 `HP-Outer`
+ * comparison (see `ParsedEncryptedMessage.headerTamperDetected`); omit it to skip that check entirely.
+ */
+export async function parseEncryptedMessage(base64Body, recipientCertDer, recipientPrivateKey, actualOuterHeaders) {
+    return parseEncryptedMessageWithKeys(base64Body, [{ certDer: recipientCertDer, privateKey: recipientPrivateKey }], actualOuterHeaders);
+}
+/** `parseEncryptedMessage()` with several candidate keys - the active encryption key first, then retained older ones -
+ * decrypted by `smime.ts`'s `decryptEnvelopedDataWithKeys()` (recipient-identifier matching first, then a bounded
+ * trial). Same never-throws contract. */
+export async function parseEncryptedMessageWithKeys(base64Body, keys, actualOuterHeaders) {
+    const envelopedDer = decodeBase64Text(base64Body);
+    if (!envelopedDer) {
+        return { decrypted: false };
+    }
+    let decrypted;
+    try {
+        decrypted = await decryptEnvelopedDataWithKeys(envelopedDer, keys);
+    }
+    catch (err) {
+        return err instanceof UnsupportedContentEncryptionError ? { decrypted: false, unsupportedContentEncryption: true } : { decrypted: false };
+    }
+    function compareTamper(fields) {
+        const hpOuter = extractHpOuterHeaders(fields);
+        if (!hpOuter || !actualOuterHeaders) {
+            return undefined;
+        }
+        return !outerHeadersMatch(hpOuter, actualOuterHeaders);
+    }
+    // Binary strings (see `mime.ts`), so an 8bit body's charset is applied to its real bytes.
+    let entity = parseMimeEntity(bytesToBinaryString(decrypted));
+    const wrapper = parseParameterizedHeader(entity.headers["content-type"]);
+    let signature = {};
+    if (PKCS7_MIME_CONTENT_TYPES.has(wrapper.value) && wrapper.params["smime-type"]?.toLowerCase() === "signed-data") {
+        const signedDer = decodeBase64Text(entity.body);
+        if (!signedDer) {
+            return { decrypted: false };
+        }
+        const verifyResult = await verifyOpaque(signedDer);
+        if (!verifyResult.valid) {
+            return { decrypted: true, signatureVerified: false };
+        }
+        // verifyOpaque() always returns `content` alongside `valid: true`.
+        entity = parseMimeEntity(bytesToBinaryString(verifyResult.content));
+        signature = { signatureVerified: true, signerCertificateDer: verifyResult.signerCertificateDer };
+    }
+    return {
+        decrypted: true,
+        ...signature,
+        protectedHeaders: headersToProtectedHeaders(entity.headers),
+        protectedHeaderFields: entity.fields,
+        bodyContentType: entity.headers["content-type"],
+        bodyText: decodeBodyText(entity),
+        displayBody: extractDisplayBody(entity),
+        attachments: extractAttachments(entity),
+        headerTamperDetected: compareTamper(entity.fields),
+    };
+}
+/** Splits a MIME entity's raw text into its header lines (lowercased-key map, first occurrence of each
+ * name, unfolded) and raw body, plus the entity's own Content-Type value for convenience. Kept for
+ * backward compatibility - new code should use `mime.ts`'s `parseMimeEntity()`, which also exposes every
+ * repeated field in order. Tolerates bare-LF line endings. */
+export function splitHeadersAndBody(entity) {
+    const { headers, body, rawHeaderBlock } = parseMimeEntity(entity);
+    return { headers, contentType: headers["content-type"], body, rawHeaderBlock };
+}
+function headersToProtectedHeaders(headers) {
+    return {
+        from: headers["from"] ?? "",
+        to: headers["to"] ?? "",
+        cc: headers["cc"],
+        date: headers["date"] ?? "",
+        // Display text: RFC 2047 encoded-words / raw UTF-8 decoded. The address fields stay raw - they are
+        // only ever compared (via `extractAddresses()`), never shown.
+        subject: decodeHeaderText(headers["subject"] ?? ""),
+        messageId: headers["message-id"] ?? "",
+    };
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Safe to mount unconditionally, even before any mailbox has been unlocked this session -
+ * `destroyUnlockedKeys()` is a no-op against an empty session store, so an idle period elapsing with
+ * nothing unlocked yet has no observable effect. Reads the configured duration once, at mount - the
+ * host component (`AppShell.tsx`) remounts on every navigation in this framework's own no-client-
+ * router design (see that component's own doc comment), so a preference change made on the Settings
+ * page takes effect the next time the user goes anywhere, without needing this hook to poll for
+ * changes itself.
+ */
+export declare function useIdleKeyTimeout(): void;

package/dist/lib/crypto/useIdleKeyTimeout.js

@@ -0,0 +1,163 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Destroys every unlocked mailbox's in-memory keys after this device's configured idle period
+ * (`idleTimeout.ts`) with no user activity — `specs/end-to-end_encryption.md`'s "destroyed on ...
+ * a configurable idle period" trigger for `keySession.ts`'s `destroyUnlockedKeys()`.
+ *
+ * Listened at the `document` level (not scoped to any one app's own content area) specifically so
+ * activity in *any* app — Contacts, Calendar, Tasks, not just Mail/Settings, where the unlocked keys
+ * are actually read/used — resets the clock. A user reading a long document in Tasks for 40 minutes
+ * without touching Mail again is still an actively-attended device, not an idle one; scoping this to
+ * only the app(s) that touch key material would time it out from underneath a session that was never
+ * actually unattended.
+ *
+ * **Iframes.** Events inside an iframe never reach the parent `document`, so activity is also listened
+ * for inside every *same-origin* iframe's own document (attached as iframes appear or (re)load, found via
+ * a `MutationObserver` plus a capture-phase `load` listener). A sandboxed/cross-origin iframe's document
+ * is inaccessible by design — notably `MessageDetailPane`'s `sandbox=""` message body — so for those the
+ * one observable signal is used instead: the parent window blurring *because focus moved into an iframe*
+ * (a click inside it) counts as activity. Scrolling such an iframe without clicking is not observable.
+ *
+ * **Sleep/suspend.** Timers don't run while a laptop sleeps, so a `setTimeout` alone could fire long after
+ * the idle deadline has passed by wall clock. Whenever the page becomes visible or the window regains
+ * focus, elapsed wall-clock time since the last activity is checked and keys are destroyed immediately if
+ * the deadline already passed (otherwise the timer is re-armed for just the remaining time).
+ */
+import { useEffect } from "react";
+import { destroyUnlockedKeys } from "./keySession.js";
+import { getIdleTimeoutMinutes } from "./idleTimeout.js";
+const ACTIVITY_EVENTS = ["mousedown", "keydown", "scroll", "touchstart"];
+/** Reads an iframe's document if (and only if) this origin may access it — `null` for a cross-origin or
+ * `sandbox`ed (opaque-origin) frame, whichever way the browser reports that (a `null` or a throw). */
+function accessibleFrameDocument(frame) {
+    try {
+        return frame.contentDocument;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Safe to mount unconditionally, even before any mailbox has been unlocked this session -
+ * `destroyUnlockedKeys()` is a no-op against an empty session store, so an idle period elapsing with
+ * nothing unlocked yet has no observable effect. Reads the configured duration once, at mount - the
+ * host component (`AppShell.tsx`) remounts on every navigation in this framework's own no-client-
+ * router design (see that component's own doc comment), so a preference change made on the Settings
+ * page takes effect the next time the user goes anywhere, without needing this hook to poll for
+ * changes itself.
+ */
+export function useIdleKeyTimeout() {
+    useEffect(() => {
+        const minutes = getIdleTimeoutMinutes();
+        if (!minutes) {
+            return;
+        }
+        const timeoutMs = minutes * 60000;
+        let timer;
+        let blurCheck;
+        let lastActivity = Date.now();
+        function arm(delayMs) {
+            clearTimeout(timer);
+            timer = setTimeout(() => destroyUnlockedKeys(), delayMs);
+        }
+        function reset() {
+            lastActivity = Date.now();
+            arm(timeoutMs);
+        }
+        /** Wall-clock check on resume - see this module's doc comment. */
+        function checkElapsed() {
+            if (document.visibilityState === "hidden") {
+                return;
+            }
+            const remaining = timeoutMs - (Date.now() - lastActivity);
+            if (remaining <= 0) {
+                clearTimeout(timer);
+                destroyUnlockedKeys();
+            }
+            else {
+                arm(remaining);
+            }
+        }
+        function handleWindowBlur() {
+            // `document.activeElement` isn't reliably updated to the iframe until after the blur event
+            // itself has finished dispatching, so check on the next tick.
+            clearTimeout(blurCheck);
+            blurCheck = setTimeout(() => {
+                if (document.activeElement instanceof HTMLIFrameElement) {
+                    reset();
+                }
+            }, 0);
+        }
+        const frameDocs = new Map();
+        function attachFrame(frame) {
+            const doc = accessibleFrameDocument(frame);
+            const previous = frameDocs.get(frame);
+            if (previous === doc) {
+                return;
+            }
+            if (previous) {
+                removeActivityListeners(previous);
+                frameDocs.delete(frame);
+            }
+            if (doc) {
+                addActivityListeners(doc);
+                frameDocs.set(frame, doc);
+            }
+        }
+        function scanFrames() {
+            const current = new Set(document.querySelectorAll("iframe"));
+            for (const [frame, doc] of frameDocs) {
+                if (!current.has(frame)) {
+                    removeActivityListeners(doc);
+                    frameDocs.delete(frame);
+                }
+            }
+            for (const frame of current) {
+                attachFrame(frame);
+            }
+        }
+        function handleLoad(e) {
+            if (e.target instanceof HTMLIFrameElement) {
+                attachFrame(e.target);
+            }
+        }
+        function addActivityListeners(target) {
+            for (const event of ACTIVITY_EVENTS) {
+                target.addEventListener(event, reset, { passive: true });
+            }
+        }
+        function removeActivityListeners(target) {
+            for (const event of ACTIVITY_EVENTS) {
+                target.removeEventListener(event, reset);
+            }
+        }
+        reset();
+        addActivityListeners(document);
+        document.addEventListener("visibilitychange", checkElapsed);
+        document.addEventListener("load", handleLoad, true);
+        window.addEventListener("focus", checkElapsed);
+        window.addEventListener("pageshow", checkElapsed);
+        window.addEventListener("blur", handleWindowBlur);
+        const observer = new MutationObserver(scanFrames);
+        observer.observe(document.documentElement, { childList: true, subtree: true });
+        scanFrames();
+        return () => {
+            clearTimeout(timer);
+            clearTimeout(blurCheck);
+            observer.disconnect();
+            removeActivityListeners(document);
+            document.removeEventListener("visibilitychange", checkElapsed);
+            document.removeEventListener("load", handleLoad, true);
+            window.removeEventListener("focus", checkElapsed);
+            window.removeEventListener("pageshow", checkElapsed);
+            window.removeEventListener("blur", handleWindowBlur);
+            for (const doc of frameDocs.values()) {
+                removeActivityListeners(doc);
+            }
+            frameDocs.clear();
+        };
+    }, []);
+}

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

@@ -0,0 +1,56 @@
+/** The longest seal restapi stores (`Message.verificationSeal`). */
+export declare const MAX_VERIFICATION_SEAL_LENGTH = 2048;
+/** The characters restapi allows in a seal. */
+export declare const VERIFICATION_SEAL_CHARSET: RegExp;
+/** The HKDF label the seal key is derived under (suffixed with `:<mailboxUid>`). */
+export declare const VERIFICATION_SEAL_HKDF_LABEL = "rapidmx:verification-seal:v1";
+/** The verified states a seal can record. */
+export type SealedVerificationState = "signed_verified" | "encrypted_verified";
+/** What `buildVerificationSeal()` seals. */
+export interface VerificationSealInput {
+    messageUid: string;
+    /** SHA-256 (hex) of the message's raw MIME - `rawMimeSha256()`. */
+    rawSha256: string;
+    /** The live signer certificate fingerprint (`MessageSecurityResult.signerFingerprint`). */
+    signerFingerprint: string;
+    state: SealedVerificationState;
+    /** UTC timestamp (epoch ms) at which the signature verified. */
+    verifiedAt: number;
+    /** The vault's `masterKeyGeneration` the seal is written under (`0` when the vault reports none). */
+    masterKeyGeneration: number;
+}
+/** What `openVerificationSeal()` recovers from a valid seal. */
+export interface OpenedVerificationSeal {
+    /** Lowercased hex. */
+    signerFingerprint: string;
+    state: SealedVerificationState;
+    verifiedAt: number;
+    masterKeyGeneration: number;
+}
+/** The part of `keySession.ts`'s `UnlockedKeys` a seal needs. */
+export interface SealKeyMaterial {
+    masterKey: Uint8Array;
+    destroyed?: boolean;
+}
+/** SHA-256 (lowercase hex) of a message's raw MIME, as `evaluateMessageSecurity()` receives it: a binary string
+ * (`mailApi.ts`'s `getMessageRawContent()`, one code unit per byte) or the bytes themselves. A string that can't be a
+ * binary string (a code unit above 0xFF) is hashed as its UTF-8 encoding, like `mime.ts`'s `binaryStringToBytes()`. */
+export declare function rawMimeSha256(raw: string | Uint8Array): Promise<string>;
+/**
+ * Seals a verification result for `mailboxUid`'s message `input.messageUid` - see this module's doc comment for the
+ * format. Throws `KeysLockedError` for destroyed keys, and a plain `Error` for input that can't be sealed: empty uids or
+ * fingerprint, a `rawSha256` that isn't 64 hex digits, an unknown `state`, a `verifiedAt` or `masterKeyGeneration` that isn't a non-negative
+ * integer, or a seal that would exceed `MAX_VERIFICATION_SEAL_LENGTH` (very long uids).
+ */
+export declare function buildVerificationSeal(mailboxUid: string, unlocked: SealKeyMaterial, input: VerificationSealInput): Promise<string>;
+/**
+ * Opens a seal written by `buildVerificationSeal()`. Resolves `{ signerFingerprint, state, verifiedAt, masterKeyGeneration }`
+ * only when the version is known, the tag verifies (constant-time comparison) under this mailbox's seal key, the sealed mailbox and
+ * message uids equal `mailboxUid`/`messageUid`, and the sealed hash equals `rawSha256` (the current raw MIME's
+ * `rawMimeSha256()`), and - when `expectedMasterKeyGeneration` is given - the sealed generation equals it (the vault's
+ * current `masterKeyGeneration`; a seal from another generation wouldn't open under that master key anyway, but this
+ * checks it explicitly). Anything else - a malformed, truncated, tampered, foreign or oversized seal, or a seal sealed
+ * under a different master key - resolves `undefined`; this never throws for the seal's content. Throws
+ * `KeysLockedError` for destroyed keys, whatever the seal.
+ */
+export declare function openVerificationSeal(mailboxUid: string, unlocked: SealKeyMaterial, messageUid: string, seal: string | undefined, rawSha256: string, expectedMasterKeyGeneration?: number): Promise<OpenedVerificationSeal | undefined>;