@rapidmx/web-client 0.10.0 → 0.12.0

package/dist/apps/shared/signing/enrollmentTracker.js

@@ -0,0 +1,307 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useSyncExternalStore } from "react";
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import { checkNowRetryAfterSeconds, checkSignEnrollmentNow, checkSignEnrollmentStatus, } from "@rapidmx/react-shared/crypto/keyvaultApi.js";
+import { SIGNING_ENROLLMENT_UNKNOWN } from "@rapidmx/react-shared/crypto/signingProviderApi.js";
+import { storeSignEnrollment } from "./enrollmentStorage.js";
+import { resetSigningInfo } from "./signingInfo.js";
+/** The code of the 404 the server answers for an enrollment id it does not know (another provider after a configuration change, one long gone).
+ * Re-exported from react-shared's `signingProviderApi.js` (R6's) rather than a second copy of the literal. */
+export const UNKNOWN_ENROLLMENT_CODE = SIGNING_ENROLLMENT_UNKNOWN;
+/**
+ * Follows the signing-certificate enrollments this browser knows about, one per mailbox, for everyone who wants to show or react to one:
+ * the Settings > Encryption card and the app frame's watcher share it, so an enrollment is asked about once however many look at it.
+ *
+ * An enrollment is a real e-mail round trip with a public CA (minutes), so it is read - not hammered: after the first answer it asks again
+ * after 15 s, then 30 s, then every 60 s, **only while the page is visible** (a hidden tab asks nothing; coming back to the front, or the
+ * window taking focus, asks at once and starts the backoff over), and it stops for good when the enrollment is issued or failed.
+ * `checkNow()` is the user's "Check status": it asks the server to re-check with the CA, with a cooldown so it can't be spammed.
+ *
+ * Framework-free apart from the `useSyncExternalStore` hook at the bottom; safe where there is no window (nothing runs until `watch()`).
+ */
+/** The wait before each re-read of a pending enrollment: the last value repeats. */
+export const ENROLLMENT_POLL_DELAYS_MS = [15000, 30000, 60000];
+/** How long "Check status" stays unavailable after a check (the server refuses one within about ten seconds of the last). */
+export const ENROLLMENT_CHECK_COOLDOWN_MS = 10000;
+const entries = new Map();
+const listeners = new Set();
+const terminalListeners = new Set();
+let environmentBound = false;
+function isVisible() {
+    return typeof document === "undefined" || document.visibilityState === "visible";
+}
+function isTerminal(result) {
+    return result?.status === "issued" || result?.status === "failed";
+}
+function emit() {
+    listeners.forEach((listener) => listener());
+}
+function update(entry, patch) {
+    entry.snapshot = { ...entry.snapshot, ...patch };
+    emit();
+}
+function isCurrent(entry) {
+    return entries.get(entry.snapshot.mailboxUid) === entry;
+}
+function stop(entry) {
+    clearTimeout(entry.timer);
+    entry.timer = undefined;
+    entry.paused = false;
+}
+function schedule(entry) {
+    stop(entry);
+    const delay = ENROLLMENT_POLL_DELAYS_MS[Math.min(entry.attempt, ENROLLMENT_POLL_DELAYS_MS.length - 1)];
+    entry.attempt += 1;
+    entry.timer = setTimeout(() => {
+        entry.timer = undefined;
+        // (Whatever replaces or ends an entry clears its timer first, so this one is always for the entry as it is.)
+        if (!isVisible()) {
+            entry.paused = true;
+            return;
+        }
+        void read(entry);
+    }, delay);
+}
+/** Puts an answer on the entry and decides what happens next: keep asking, or end (and tell the watchers once). */
+function apply(entry, result, patch = {}) {
+    if (!isCurrent(entry)) {
+        return;
+    }
+    update(entry, { result, answeredAt: Date.now(), offline: false, gone: false, checking: false, ...patch });
+    if (!isTerminal(result)) {
+        schedule(entry);
+        return;
+    }
+    stop(entry);
+    // The enrollment is over: nothing is pending, so the id is not kept (it is what blocks a rotation across a reload).
+    storeSignEnrollment(entry.snapshot.mailboxUid, null);
+    if (entry.expectPending && !entry.announced) {
+        entry.announced = true;
+        terminalListeners.forEach((listener) => listener(entry.snapshot));
+    }
+}
+/** A failed read: the server no longer has the enrollment (nothing is pending), or it could not be reached (assume it is still going). */
+function fail(entry, err, patch = {}) {
+    if (!isCurrent(entry)) {
+        return;
+    }
+    if (err instanceof ApiRequestError && err.status === 404) {
+        stop(entry);
+        storeSignEnrollment(entry.snapshot.mailboxUid, null);
+        update(entry, { gone: true, offline: false, checking: false, ...patch });
+        return;
+    }
+    update(entry, { offline: true, checking: false, ...patch });
+    schedule(entry);
+}
+async function read(entry) {
+    update(entry, { checking: true });
+    try {
+        apply(entry, await checkSignEnrollmentStatus(entry.snapshot.mailboxUid, entry.snapshot.enrollmentId));
+    }
+    catch (err) {
+        fail(entry, err);
+    }
+}
+function resume() {
+    if (!isVisible()) {
+        return;
+    }
+    entries.forEach((entry) => {
+        if (entry.paused && !isTerminal(entry.snapshot.result)) {
+            entry.paused = false;
+            entry.attempt = 0;
+            void read(entry);
+        }
+    });
+}
+function bindEnvironment() {
+    if (!environmentBound && typeof document !== "undefined") {
+        environmentBound = true;
+        document.addEventListener("visibilitychange", resume);
+        window.addEventListener("focus", resume);
+        window.addEventListener("online", resume);
+    }
+}
+function unbindEnvironment() {
+    if (environmentBound && entries.size === 0) {
+        environmentBound = false;
+        document.removeEventListener("visibilitychange", resume);
+        window.removeEventListener("focus", resume);
+        window.removeEventListener("online", resume);
+    }
+}
+/**
+ * Starts following `enrollmentId` for `mailboxUid` (one enrollment per mailbox; a different id replaces the old one) and returns the
+ * function that lets go. Reads it now unless `initial` says what it is, then keeps reading with backoff while it is pending. Following is
+ * shared, and a pending enrollment stays followed after everyone has let go (until it ends); an ended one is forgotten.
+ */
+export function watchEnrollment(mailboxUid, enrollmentId, options = {}) {
+    const { initial, expectPending = true } = options;
+    let entry = entries.get(mailboxUid);
+    if (entry && entry.snapshot.enrollmentId !== enrollmentId) {
+        stop(entry);
+        entry = undefined;
+    }
+    if (entry) {
+        entry.refs += 1;
+        entry.expectPending || (entry.expectPending = expectPending && !isTerminal(entry.snapshot.result));
+        if (initial && !entry.snapshot.result) {
+            apply(entry, initial);
+        }
+    }
+    else {
+        const created = {
+            snapshot: {
+                mailboxUid,
+                enrollmentId,
+                result: null,
+                answeredAt: null,
+                checking: false,
+                checkingNow: false,
+                retryAt: 0,
+                offline: false,
+                gone: false,
+                lastCheck: null,
+            },
+            refs: 1,
+            timer: undefined,
+            attempt: 0,
+            paused: false,
+            expectPending,
+            announced: false,
+        };
+        entries.set(mailboxUid, created);
+        bindEnvironment();
+        emit();
+        if (initial) {
+            apply(created, initial);
+        }
+        else {
+            void read(created);
+        }
+    }
+    const held = entries.get(mailboxUid);
+    let released = false;
+    return () => {
+        if (released) {
+            return;
+        }
+        released = true;
+        held.refs -= 1;
+        // A pending enrollment is followed on with nobody looking - that is what lets the frame tell the user it finished wherever they are, and
+        // what the next visit to the page shows at once. One that ended (or that the server no longer knows) has nothing left to follow.
+        if (held.refs <= 0 && isCurrent(held) && (isTerminal(held.snapshot.result) || held.snapshot.gone)) {
+            stop(held);
+            entries.delete(mailboxUid);
+            unbindEnvironment();
+            emit();
+        }
+    };
+}
+/** Whether a manual check changed what the user sees: the step, the state or the progress. */
+function differs(before, after) {
+    return !before || before.status !== after.status || before.stage !== after.stage || before.progress !== after.progress;
+}
+/** "Check status": asks the server to re-check with the CA now. Does nothing while one is under way or within the cooldown. */
+export async function checkEnrollmentNow(mailboxUid) {
+    const entry = entries.get(mailboxUid);
+    if (!entry || entry.snapshot.checkingNow || entry.snapshot.retryAt > Date.now() || isTerminal(entry.snapshot.result)) {
+        return;
+    }
+    const before = entry.snapshot.result;
+    update(entry, { checkingNow: true, checking: true });
+    entry.attempt = 0;
+    const done = (outcome, patch = {}) => ({
+        checkingNow: false,
+        lastCheck: { at: Date.now(), outcome },
+        ...patch,
+    });
+    try {
+        const result = await checkSignEnrollmentNow(mailboxUid, entry.snapshot.enrollmentId);
+        apply(entry, result, done(differs(before, result) ? "changed" : "unchanged", { retryAt: Date.now() + ENROLLMENT_CHECK_COOLDOWN_MS }));
+        return;
+    }
+    catch (err) {
+        const seconds = checkNowRetryAfterSeconds(err);
+        if (seconds !== undefined) {
+            update(entry, done("limited", { retryAt: Date.now() + seconds * 1000, checking: false }));
+            return;
+        }
+        if (err instanceof ApiRequestError && err.status === 404 && err.code === UNKNOWN_ENROLLMENT_CODE) {
+            // The server says this enrollment does not exist: there is nothing to fall back to.
+            fail(entry, err, done("failed"));
+            return;
+        }
+        if (!(err instanceof ApiRequestError && [404, 405, 501].includes(err.status))) {
+            if (isCurrent(entry)) {
+                update(entry, done("failed", { checking: false }));
+            }
+            return;
+        }
+    }
+    // A server without the check endpoint: a plain read is the "check" it has - and a 404 there says the enrollment itself is gone.
+    try {
+        const result = await checkSignEnrollmentStatus(mailboxUid, entry.snapshot.enrollmentId);
+        apply(entry, result, done(differs(before, result) ? "changed" : "unchanged", { retryAt: Date.now() + ENROLLMENT_CHECK_COOLDOWN_MS }));
+    }
+    catch (err) {
+        fail(entry, err, done("failed"));
+    }
+}
+/** Adopts an enrollment the server reported (`getCurrentSignEnrollment()`) - see `watchEnrollment()`. */
+export function watchCurrentEnrollment(mailboxUid, current, expectPending = true) {
+    const { enrollmentId, ...result } = current;
+    return watchEnrollment(mailboxUid, enrollmentId, { initial: result, expectPending });
+}
+/** Puts an answer the caller got itself (the reply to a cancel that found the certificate already issued) on `mailboxUid`'s enrollment, if it is the one followed. */
+export function recordEnrollmentResult(mailboxUid, enrollmentId, result) {
+    const entry = entries.get(mailboxUid);
+    if (entry && entry.snapshot.enrollmentId === enrollmentId) {
+        apply(entry, result);
+    }
+}
+/** Stops following `mailboxUid`'s enrollment altogether (it was cancelled): nothing is kept, whoever else was watching. */
+export function forgetEnrollment(mailboxUid) {
+    const entry = entries.get(mailboxUid);
+    if (entry) {
+        stop(entry);
+        entries.delete(mailboxUid);
+        unbindEnvironment();
+        emit();
+    }
+}
+/** The current state of `mailboxUid`'s followed enrollment, or `undefined` when none is followed. */
+export function getEnrollmentSnapshot(mailboxUid) {
+    return entries.get(mailboxUid)?.snapshot;
+}
+export function subscribeToEnrollments(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+/** Called once when an enrollment this browser was following ends (issued or failed) - the frame's watcher raises the pop-up. */
+export function onEnrollmentEnded(listener) {
+    terminalListeners.add(listener);
+    return () => {
+        terminalListeners.delete(listener);
+    };
+}
+/** `mailboxUid`'s followed enrollment, kept current (`undefined` when none is followed). */
+export function useEnrollmentSnapshot(mailboxUid) {
+    return useSyncExternalStore(subscribeToEnrollments, () => (mailboxUid ? getEnrollmentSnapshot(mailboxUid) : undefined), () => undefined);
+}
+/** Forgets everything and stops every timer: for tests, which share the module. */
+export function resetEnrollmentTracker() {
+    resetSigningInfo();
+    entries.forEach(stop);
+    entries.clear();
+    listeners.clear();
+    terminalListeners.clear();
+    unbindEnvironment();
+    environmentBound = false;
+}

package/dist/apps/shared/signing/enrollmentView.d.ts

@@ -0,0 +1,57 @@
+import type { EnrollmentResult, SignEnrollmentStep } from "@rapidmx/react-shared/crypto/keyvaultApi.js";
+import type { SigningEnrollmentInfo } from "./signingInfo.js";
+/** Warn about an expiring certificate this many days ahead. */
+export declare const EXPIRY_WARNING_DAYS = 30;
+/** Epoch ms of a date the server sent, or `undefined` for a missing or unparseable one. */
+export declare function timeOf(value: string | number | undefined): number | undefined;
+/** "just now", "20 s ago", "3 min ago", "2 h ago", "4 days ago" - `undefined` when there is no date. A time slightly in the future (clock skew) is "just now". */
+export declare function relativeTime(value: string | number | undefined, now: number): string | undefined;
+/** A calendar date in the reader's language ("21 Sep 2027"); the raw text if it is not a date. */
+export declare function formatDate(value: string | number | undefined): string;
+/** A date and time for a step's timestamp. */
+export declare function formatDateTime(value: string | number | undefined): string;
+/** A long serial number as `0A1B2C3D...9F8E7D` (the whole value is what gets copied). */
+export declare function truncateSerial(serial: string, keep?: number): string;
+export type ExpiryState = "ok" | "soon" | "expired" | "unknown";
+/** How long a certificate has left: `soon` inside `EXPIRY_WARNING_DAYS`, `expired` once past. */
+export declare function expiryOf(notAfter: string | number | undefined, now: number): {
+    state: ExpiryState;
+    daysLeft?: number;
+};
+/**
+ * The steps to draw: the server's own `stages` when it sent them, else - for a server that only says which `stage` it is at - the usual five
+ * with everything before it done and it active, else none (an older server: the card falls back to a plain sentence).
+ */
+export declare function stepsOf(result: EnrollmentResult | null | undefined): SignEnrollmentStep[];
+/** The percentage the bar shows: the server's `progress`, else what the steps say (done steps out of all), else `undefined` - unknown. */
+export declare function progressOf(result: EnrollmentResult | null | undefined): number | undefined;
+/** The step doing the work now, if any. */
+export declare function activeStepOf(result: EnrollmentResult | null | undefined): SignEnrollmentStep | undefined;
+/**
+ * A certificate that is issued but not in the mailbox yet: the server installs it with a job a few minutes after the CA issues it, and says when it
+ * has (`installedAt`). An older server sends neither date, so its issued certificates are never "installing".
+ */
+export declare function isInstalling(result: EnrollmentResult | null | undefined): boolean;
+/** What the server says about a CA it could not reach: still pending, to be retried - not a failure. */
+export declare const CA_UNREACHABLE_TEXT = "The certificate authority could not be reached just now - it will be asked again.";
+/** The plain-language line: what the enrollment is waiting for, when it was issued, why it failed. `undefined` when the server said nothing to go on. */
+export declare function statusLineOf(result: EnrollmentResult | null | undefined): string | undefined;
+/** What a pending request says when the server has not said how it issues certificates (an older server): nothing that is only true of one way of issuing them. */
+export declare const PENDING_FALLBACK_TEXT = "Requested - waiting for the certificate. Use Check status to see where the request is.";
+/** A manual deployment: nobody but an administrator can make the certificate. Never "takes effect automatically". */
+export declare const MANUAL_ISSUE_TEXT = "This server issues signing certificates manually: an administrator has to upload the certificate for your request. Contact your administrator.";
+/** The enrollment id the browser kept is one the server does not know any more (another provider after a configuration change, a cancelled request). */
+export declare const STALE_REQUEST_TEXT = "This request is no longer active - request a new certificate.";
+/** How a request is being turned into a certificate: by a public CA on its own, by an administrator, or not known. The enrollment's own `provider` wins over what the deployment says now. */
+export type IssueMode = "automatic" | "manual" | "unknown";
+export declare function issueModeOf(result: EnrollmentResult | null | undefined, info: SigningEnrollmentInfo | null | undefined): IssueMode;
+/** "Requested from ca.example. The CA sends a verification e-mail to jane@example.com; this usually takes about 5 minutes." - each part only as far as it is known. */
+export declare function requestedFromText(info: SigningEnrollmentInfo | null | undefined, address: string | undefined): string;
+/** What to say before anyone has asked for a certificate: how this deployment will issue it (or that it does not). `undefined` when nothing is known. */
+export declare function beforeRequestText(info: SigningEnrollmentInfo | null | undefined, address: string | undefined): string | undefined;
+/** The warning when the CA has been reporting a problem: what it said and when it last worked. `undefined` when it has not. */
+export declare function healthWarning(info: SigningEnrollmentInfo | null | undefined): string | undefined;
+/** A pending request is "taking longer than expected" after this long without a change. */
+export declare const OVERDUE_AFTER_MS: number;
+/** Whether a pending request was made more than an hour ago and nothing has changed in the last hour: say so instead of staying silent. */
+export declare function isOverdue(result: EnrollmentResult | null | undefined, now: number): boolean;

package/dist/apps/shared/signing/enrollmentView.js

@@ -0,0 +1,214 @@
+/** Warn about an expiring certificate this many days ahead. */
+export const EXPIRY_WARNING_DAYS = 30;
+const DAY_MS = 86400000;
+/** Epoch ms of a date the server sent, or `undefined` for a missing or unparseable one. */
+export function timeOf(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const time = typeof value === "number" ? value : Date.parse(value);
+    return Number.isFinite(time) ? time : undefined;
+}
+/** "just now", "20 s ago", "3 min ago", "2 h ago", "4 days ago" - `undefined` when there is no date. A time slightly in the future (clock skew) is "just now". */
+export function relativeTime(value, now) {
+    const time = timeOf(value);
+    if (time === undefined) {
+        return undefined;
+    }
+    const seconds = Math.max(0, Math.floor((now - time) / 1000));
+    if (seconds < 5) {
+        return "just now";
+    }
+    if (seconds < 60) {
+        return `${seconds} s ago`;
+    }
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60) {
+        return `${minutes} min ago`;
+    }
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24) {
+        return `${hours} h ago`;
+    }
+    const days = Math.floor(hours / 24);
+    return `${days} ${days === 1 ? "day" : "days"} ago`;
+}
+/** A calendar date in the reader's language ("21 Sep 2027"); the raw text if it is not a date. */
+export function formatDate(value) {
+    const time = timeOf(value);
+    if (time === undefined) {
+        return typeof value === "string" ? value : "";
+    }
+    return new Date(time).toLocaleDateString(undefined, { year: "numeric", month: "short", day: "numeric" });
+}
+/** A date and time for a step's timestamp. */
+export function formatDateTime(value) {
+    const time = timeOf(value);
+    if (time === undefined) {
+        return typeof value === "string" ? value : "";
+    }
+    return new Date(time).toLocaleString(undefined, { month: "short", day: "numeric", hour: "numeric", minute: "2-digit" });
+}
+/** A long serial number as `0A1B2C3D...9F8E7D` (the whole value is what gets copied). */
+export function truncateSerial(serial, keep = 8) {
+    return serial.length > keep * 2 + 3 ? `${serial.slice(0, keep)}...${serial.slice(-keep)}` : serial;
+}
+/** How long a certificate has left: `soon` inside `EXPIRY_WARNING_DAYS`, `expired` once past. */
+export function expiryOf(notAfter, now) {
+    const time = timeOf(notAfter);
+    if (time === undefined) {
+        return { state: "unknown" };
+    }
+    if (time <= now) {
+        return { state: "expired", daysLeft: 0 };
+    }
+    const daysLeft = Math.ceil((time - now) / DAY_MS);
+    return { state: daysLeft <= EXPIRY_WARNING_DAYS ? "soon" : "ok", daysLeft };
+}
+/** The order the server's steps normally go in, with the words for a server that names a stage but not the steps. */
+const STAGE_STEPS = [
+    { stage: "submitted", label: "Request sent to the certificate authority" },
+    { stage: "awaiting-challenge", label: "Verification e-mail from the CA" },
+    { stage: "challenge-answered", label: "Verification answered" },
+    { stage: "validating", label: "CA validates the answer" },
+    { stage: "issuing", label: "Certificate issued and installed" },
+];
+/** What each stage means, for the line under the bar. */
+const STAGE_TEXT = {
+    submitted: "Request sent - waiting for the certificate authority to answer",
+    "awaiting-challenge": "Waiting for the CA's verification e-mail",
+    "challenge-answered": "Verification answered - waiting for the certificate",
+    validating: "The CA is validating the answer",
+    issuing: "The certificate is being issued",
+    issued: "Issued",
+    failed: "Failed",
+};
+/**
+ * The steps to draw: the server's own `stages` when it sent them, else - for a server that only says which `stage` it is at - the usual five
+ * with everything before it done and it active, else none (an older server: the card falls back to a plain sentence).
+ */
+export function stepsOf(result) {
+    if (!result) {
+        return [];
+    }
+    if (result.stages && result.stages.length > 0) {
+        return result.stages;
+    }
+    if (!result.stage) {
+        return [];
+    }
+    const index = STAGE_STEPS.findIndex((step) => step.stage === result.stage);
+    const failed = result.stage === "failed" || result.status === "failed";
+    const issued = result.stage === "issued" || result.status === "issued";
+    // An issued enrollment has done every step; a failed one stopped at an unknown step, so none is claimed done or active.
+    return STAGE_STEPS.map((step, position) => {
+        if (issued) {
+            return { id: step.stage, label: step.label, state: "done" };
+        }
+        if (failed || index === -1) {
+            return { id: step.stage, label: step.label, state: "pending" };
+        }
+        return { id: step.stage, label: step.label, state: position < index ? "done" : position === index ? "active" : "pending" };
+    });
+}
+/** The percentage the bar shows: the server's `progress`, else what the steps say (done steps out of all), else `undefined` - unknown. */
+export function progressOf(result) {
+    if (!result) {
+        return undefined;
+    }
+    if (typeof result.progress === "number") {
+        return Math.round(result.progress);
+    }
+    if (result.status === "issued") {
+        return 100;
+    }
+    const steps = stepsOf(result);
+    return steps.length > 0 ? Math.round((steps.filter((step) => step.state === "done").length / steps.length) * 100) : undefined;
+}
+/** The step doing the work now, if any. */
+export function activeStepOf(result) {
+    return stepsOf(result).find((step) => step.state === "active");
+}
+/**
+ * A certificate that is issued but not in the mailbox yet: the server installs it with a job a few minutes after the CA issues it, and says when it
+ * has (`installedAt`). An older server sends neither date, so its issued certificates are never "installing".
+ */
+export function isInstalling(result) {
+    return result?.status === "issued" && !!result.issuedAt && !result.installedAt;
+}
+/** What the server says about a CA it could not reach: still pending, to be retried - not a failure. */
+export const CA_UNREACHABLE_TEXT = "The certificate authority could not be reached just now - it will be asked again.";
+/** The plain-language line: what the enrollment is waiting for, when it was issued, why it failed. `undefined` when the server said nothing to go on. */
+export function statusLineOf(result) {
+    if (!result) {
+        return undefined;
+    }
+    if (result.status === "issued") {
+        if (isInstalling(result)) {
+            return "Issued - installing it on your mailbox (this takes a few minutes)";
+        }
+        return result.notAfter ? `Issued - valid until ${formatDate(result.notAfter)}` : "Issued";
+    }
+    if (result.status === "failed") {
+        return `Failed: ${result.error ?? "the certificate authority did not issue a certificate."}`;
+    }
+    return result.stage ? STAGE_TEXT[result.stage] : undefined;
+}
+/** What a pending request says when the server has not said how it issues certificates (an older server): nothing that is only true of one way of issuing them. */
+export const PENDING_FALLBACK_TEXT = "Requested - waiting for the certificate. Use Check status to see where the request is.";
+/** A manual deployment: nobody but an administrator can make the certificate. Never "takes effect automatically". */
+export const MANUAL_ISSUE_TEXT = "This server issues signing certificates manually: an administrator has to upload the certificate for your request. Contact your administrator.";
+/** The enrollment id the browser kept is one the server does not know any more (another provider after a configuration change, a cancelled request). */
+export const STALE_REQUEST_TEXT = "This request is no longer active - request a new certificate.";
+export function issueModeOf(result, info) {
+    const provider = result?.provider;
+    if (provider === "manual" || (!provider && info?.backend === "manual")) {
+        return "manual";
+    }
+    if (provider === "rfc8823" || (!provider && info?.automatic)) {
+        return "automatic";
+    }
+    return "unknown";
+}
+function minutes(count) {
+    return `${count} ${count === 1 ? "minute" : "minutes"}`;
+}
+/** "Requested from ca.example. The CA sends a verification e-mail to jane@example.com; this usually takes about 5 minutes." - each part only as far as it is known. */
+export function requestedFromText(info, address) {
+    const host = info?.ca?.host ? `Requested from ${info.ca.host}.` : "Requested from the certificate authority.";
+    const sentence = `The CA sends a verification e-mail to ${address ?? "this mailbox"}`;
+    const duration = info?.typicalDurationMinutes ? `; this usually takes about ${minutes(info.typicalDurationMinutes)}` : "";
+    return `${host} ${sentence}${duration}.`;
+}
+/** What to say before anyone has asked for a certificate: how this deployment will issue it (or that it does not). `undefined` when nothing is known. */
+export function beforeRequestText(info, address) {
+    if (!info || info.backend === "none") {
+        return info ? "This server does not issue signing certificates." : undefined;
+    }
+    if (info.backend === "manual") {
+        return MANUAL_ISSUE_TEXT;
+    }
+    const from = info.ca?.host ?? "a public certificate authority";
+    const duration = info.typicalDurationMinutes ? `, usually within about ${minutes(info.typicalDurationMinutes)}` : "";
+    return `A certificate is issued automatically by ${from}: it sends a verification e-mail to ${address ?? "this mailbox"}${duration}.`;
+}
+/** The warning when the CA has been reporting a problem: what it said and when it last worked. `undefined` when it has not. */
+export function healthWarning(info) {
+    const error = info?.health?.lastError;
+    if (!error) {
+        return undefined;
+    }
+    const last = info.health.lastSuccessAt ? formatDateTime(info.health.lastSuccessAt) : "never";
+    return `The certificate authority reported a problem: ${error} (last successful contact ${last})`;
+}
+/** A pending request is "taking longer than expected" after this long without a change. */
+export const OVERDUE_AFTER_MS = 60 * 60000;
+/** Whether a pending request was made more than an hour ago and nothing has changed in the last hour: say so instead of staying silent. */
+export function isOverdue(result, now) {
+    if (result?.status !== "pending") {
+        return false;
+    }
+    const requested = timeOf(result.requestedAt);
+    const changed = timeOf(result.updatedAt) ?? requested;
+    return requested !== undefined && changed !== undefined && now - requested > OVERDUE_AFTER_MS && now - changed > OVERDUE_AFTER_MS;
+}

package/dist/apps/shared/signing/signingInfo.d.ts

@@ -0,0 +1,11 @@
+import { SigningEnrollmentInfo } from "@rapidmx/react-shared/crypto/signingProviderApi.js";
+export type { SigningEnrollmentInfo };
+/** How long an answer is reused: the page asks once when it opens, and again after this if it is opened again. */
+export declare const SIGNING_INFO_CACHE_MS: number;
+/** The deployment's signing-enrollment description, or `null` when it cannot be had (an older server with no such endpoint, offline,
+ * anything) - never rejects. One request at a time, reused for five minutes. */
+export declare function fetchSigningEnrollmentInfo(now?: number): Promise<SigningEnrollmentInfo | null>;
+/** Forgets the remembered answer: for tests, which share the module. */
+export declare function resetSigningInfo(): void;
+/** The deployment's description, once it is known: `undefined` while it is being asked for, `null` when there is none. Asks only while `enabled`. */
+export declare function useSigningEnrollmentInfo(enabled: boolean): SigningEnrollmentInfo | null | undefined;

package/dist/apps/shared/signing/signingInfo.js

@@ -0,0 +1,48 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useState } from "react";
+import { getSigningEnrollmentInfo } from "@rapidmx/react-shared/crypto/signingProviderApi.js";
+/** How long an answer is reused: the page asks once when it opens, and again after this if it is opened again. */
+export const SIGNING_INFO_CACHE_MS = 5 * 60000;
+let cached;
+/** The deployment's signing-enrollment description, or `null` when it cannot be had (an older server with no such endpoint, offline,
+ * anything) - never rejects. One request at a time, reused for five minutes. */
+export function fetchSigningEnrollmentInfo(now = Date.now()) {
+    if (cached && now - cached.at < SIGNING_INFO_CACHE_MS) {
+        return cached.promise;
+    }
+    const promise = getSigningEnrollmentInfo().catch(() => null);
+    cached = { at: now, promise };
+    // An answer that could not be had is not worth remembering: the next visit asks again.
+    void promise.then((info) => {
+        if (info === null && cached?.promise === promise) {
+            cached = undefined;
+        }
+    });
+    return promise;
+}
+/** Forgets the remembered answer: for tests, which share the module. */
+export function resetSigningInfo() {
+    cached = undefined;
+}
+/** The deployment's description, once it is known: `undefined` while it is being asked for, `null` when there is none. Asks only while `enabled`. */
+export function useSigningEnrollmentInfo(enabled) {
+    const [info, setInfo] = useState(undefined);
+    useEffect(() => {
+        if (!enabled) {
+            return;
+        }
+        let cancelled = false;
+        void fetchSigningEnrollmentInfo().then((answer) => {
+            if (!cancelled) {
+                setInfo(answer);
+            }
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [enabled]);
+    return info;
+}

package/dist/apps/shared/signing/useNow.d.ts

@@ -0,0 +1,2 @@
+/** The current time in epoch ms, re-read every `intervalMs` while `enabled` - for "3 min ago" texts and countdowns that keep themselves right. */
+export declare function useNow(intervalMs: number, enabled?: boolean): number;

package/dist/apps/shared/signing/useNow.js

@@ -0,0 +1,18 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useState } from "react";
+/** The current time in epoch ms, re-read every `intervalMs` while `enabled` - for "3 min ago" texts and countdowns that keep themselves right. */
+export function useNow(intervalMs, enabled = true) {
+    const [now, setNow] = useState(() => Date.now());
+    useEffect(() => {
+        if (!enabled) {
+            return;
+        }
+        setNow(Date.now());
+        const timer = setInterval(() => setNow(Date.now()), intervalMs);
+        return () => clearInterval(timer);
+    }, [intervalMs, enabled]);
+    return now;
+}