@semics-tech/emdash-esign 0.0.0-stage → 1.0.0-rc.0

package/src/astro/lib/sign.ts

@@ -0,0 +1,421 @@
+import { type MessageKey, t, translator } from "../../i18n/index.ts";
+import { callPublicRoute, type PublicRouteContext } from "./call.ts";
+
+/**
+ * The signing page's logic (SU-FR-01), kept out of the `.astro` file so it is testable. The token is
+ * the page path; here it only ever goes into POST bodies. `public/session` is always called first. A
+ * GET only looks (mail scanners prefetch emailed links, T117); the first POST, sign or decline, asks it
+ * to `open` the envelope, which records the first view (R31). A submit is bound to the document hash
+ * and the consent wording's hash that session returned.
+ */
+
+export interface SessionData {
+	ok: true;
+	state: "ready" | "closed";
+	status?: string;
+	title?: string;
+	pdf?: "pending" | "ready";
+	download?: { url: string; expiresAt: string };
+	envelope?: { id: string; title: string; status: string; docSha256: string | null; expiresAt: string | null };
+	signer?: { name: string; as?: string; participant?: string };
+	snapshot?: string;
+	/** An uploaded PDF (E-sign Pro, T094): what it is, and a short-lived link to it (none when the core cannot serve it). */
+	document?: {
+		kind: "pdf";
+		name?: string;
+		bytes?: number;
+		pages?: number;
+		view?: { url?: unknown; expiresAt?: string };
+	};
+	/** An emailed one-time code is needed before signing (E-sign Pro, T091); `verified` once it has been entered. */
+	otp?: "required" | "verified";
+	/** `sha256` is the SHA-256 of `wording`, posted back with the signature (T117). */
+	consent?: { version: string; wording: string; sha256?: string };
+	/** Values the signer fills in (`fieldValues` on submit). */
+	fields?: SessionField[];
+	/** A closed integration envelope: where to return, and its signed receipt (T062). */
+	returnUrl?: string;
+	receipt?: string;
+}
+
+/** What submit and decline answer with besides `ok` (T062: `receipt` for an integration's envelope). */
+interface Done {
+	/** `completed`, or still open (`in_progress`) while other signers have to sign (T090). */
+	status?: string;
+	returnUrl?: string;
+	receipt?: string;
+}
+
+export interface SessionField {
+	key: string;
+	label: string;
+	required?: boolean;
+}
+
+/** Field keys as `public/submit` accepts them; others are never rendered or sent. */
+export const FIELD_KEY = /^[A-Za-z0-9_]{1,64}$/;
+
+/** The form control name of a session field. */
+export const fieldName = (key: string) => `field.${key}`;
+
+/** The session's fields that can be rendered and posted. */
+export const sessionFields = (session: SessionData): SessionField[] =>
+	(Array.isArray(session.fields) ? session.fields : []).filter(
+		(f) => f && typeof f.key === "string" && FIELD_KEY.test(f.key) && typeof f.label === "string",
+	);
+
+/** What the ceremony shows of an uploaded PDF (T094). */
+export interface PdfDocumentView {
+	name: string;
+	pages: number;
+	/** The page count for people (`3 pages`). */
+	pagesLabel: string;
+	/** The file size for people (`47 KB`, `2.4 MB`). */
+	size: string;
+	/** The site's own link to the PDF; absent when the core cannot serve it (then it cannot be signed here). */
+	url?: string;
+}
+
+// biome-ignore lint/suspicious/noControlCharactersInRegex: control characters are removed from a file name before it is shown.
+const CONTROLS = /[\u0000-\u001f\u007f]/g;
+
+const sizeOf = (bytes: number, locale: string) => {
+	const number = (n: number, digits: number) =>
+		new Intl.NumberFormat(locale, { minimumFractionDigits: digits, maximumFractionDigits: digits }).format(n);
+	return bytes >= 1024 * 1024
+		? t(locale, "sign.pdf.mb", { n: number(bytes / (1024 * 1024), 1) })
+		: t(locale, "sign.pdf.kb", { n: number(Math.max(1, Math.round(bytes / 1024)), 0) });
+};
+
+/**
+ * The session's uploaded PDF, if it is one: name (control characters dropped, at most 120 characters), pages, size,
+ * and the link only when it is a path on this site (never `//host`, a scheme or another origin).
+ */
+export function pdfDocumentView(session: SessionData, locale = "en-GB"): PdfDocumentView | undefined {
+	const doc = session.document;
+	if (!doc || doc.kind !== "pdf") return undefined;
+	const url = doc.view?.url;
+	const name = (typeof doc.name === "string" ? doc.name.replace(CONTROLS, "").trim() : "").slice(0, 120);
+	const pages = Number.isSafeInteger(doc.pages) ? (doc.pages as number) : 0;
+	return {
+		name: name || "document.pdf",
+		pages,
+		pagesLabel: translator(locale).plural("sign.pdf.pages", pages),
+		size: sizeOf(Number.isFinite(doc.bytes) ? (doc.bytes as number) : 0, locale),
+		url: typeof url === "string" && /^\/(?![/\\])/.test(url) ? url : undefined,
+	};
+}
+
+/** Limits of `public/submit` (T024): at most 64 strokes, at most 32 KB of stroke JSON. */
+export const MAX_STROKES = 64;
+export const MAX_STROKES_JSON_BYTES = 32 * 1024;
+/** Raw pad JSON larger than this is not even parsed. */
+const MAX_PAD_JSON = 512 * 1024;
+
+const toPoint = (p: unknown): [number, number] | undefined => {
+	let x: unknown;
+	let y: unknown;
+	if (Array.isArray(p)) [x, y] = p;
+	else if (p !== null && typeof p === "object") ({ x, y } = p as { x?: unknown; y?: unknown });
+	return typeof x === "number" && typeof y === "number" && Number.isFinite(x) && Number.isFinite(y)
+		? [x, y]
+		: undefined;
+};
+
+const unit = (n: number, size: number) => Math.round(Math.min(1, Math.max(0, n / size)) * 1000) / 1000;
+
+/**
+ * The signature pad's `{ v, w, h, strokes }` (pad coordinates, y down; T031) as `public/submit`
+ * takes it: `[x, y]` points normalised to 0-1 (the PDF draws them in a 1 x 1 box), three decimals.
+ */
+export function normaliseStrokes(
+	pad: unknown,
+): { ok: true; strokes: number[][][] } | { ok: false; code: "INVALID_SIGNATURE" | "STROKES_TOO_LARGE" } {
+	const invalid = { ok: false, code: "INVALID_SIGNATURE" } as const;
+	if (pad === null || typeof pad !== "object") return invalid;
+	const { w, h, strokes } = pad as { w?: unknown; h?: unknown; strokes?: unknown };
+	if (typeof w !== "number" || typeof h !== "number" || !(w > 0) || !(h > 0) || !Number.isFinite(w * h)) return invalid;
+	if (!Array.isArray(strokes)) return invalid;
+	const out: number[][][] = [];
+	for (const stroke of strokes) {
+		const points = (Array.isArray(stroke) ? stroke : [])
+			.map(toPoint)
+			.filter((p): p is [number, number] => p !== undefined)
+			.map(([x, y]) => [unit(x, w), unit(y, h)]);
+		if (points.length > 0) out.push(points);
+	}
+	if (out.length === 0 || out.length > MAX_STROKES) return invalid;
+	if (JSON.stringify(out).length > MAX_STROKES_JSON_BYTES) return { ok: false, code: "STROKES_TOO_LARGE" };
+	return { ok: true, strokes: out };
+}
+
+/** The drawn signature in the form, if any: `undefined` for none, else the normalised strokes or why not. */
+function formStrokes(form: FormData): ReturnType<typeof normaliseStrokes> | undefined {
+	const raw = form.get("signatureStrokes");
+	if (typeof raw !== "string" || raw.trim() === "") return undefined;
+	if (raw.length > MAX_PAD_JSON) return { ok: false, code: "STROKES_TOO_LARGE" };
+	try {
+		return normaliseStrokes(JSON.parse(raw));
+	} catch {
+		return { ok: false, code: "INVALID_SIGNATURE" };
+	}
+}
+
+/** Where the core's submit issues show on the form. */
+const ISSUE_FIELD: Record<string, string> = {
+	intent: "agree",
+	"signature.strokes": "signature",
+	fieldValues: "fields",
+};
+
+export type SignView =
+	| { kind: "error"; code: string; message: string }
+	| {
+			kind: "ready";
+			session: SessionData;
+			/** Form fields to fix (`typedName`, `consent`, `agree`). */
+			fields?: string[];
+			errorCode?: string;
+			message?: string;
+			/** A one-time code was just emailed (T091). */
+			otpSent?: true;
+	  }
+	| { kind: "closed"; status: string; title?: string; pdf?: "pending" | "ready"; download?: string; returnUrl?: string }
+	| { kind: "signed"; returnUrl?: string; download?: string; pdf?: "pending" | "ready"; waiting?: true }
+	/** SU-FR-11: this signer has signed; the envelope waits for the other signers (T090). */
+	| { kind: "waiting"; title?: string }
+	| { kind: "declined"; returnUrl?: string };
+
+const CODES = [
+	"SIGNING_TOKEN_INVALID",
+	"SIGNING_TOKEN_EXPIRED",
+	"ENVELOPE_CLOSED",
+	"ENVELOPE_NOT_FOUND",
+	"RATE_LIMITED",
+	"TOKEN_IN_QUERY",
+	"SESSION_REQUIRED",
+	"BAD_REQUEST",
+	"SIGNING_OUT_OF_TURN",
+	"OTP_REQUIRED",
+	"OTP_INVALID",
+	"OTP_EXPIRED",
+	"OTP_LOCKED",
+	"OTP_WAIT",
+	"OTP_SEND_FAILED",
+	"STROKES_TOO_LARGE",
+];
+
+/** A refusal's message in the locale's language (T102); an unknown code gets `INTERNAL`'s. */
+export const signMessage = (code: string, locale?: string) =>
+	t(locale, `error.${CODES.includes(code) ? code : "INTERNAL"}` as MessageKey);
+
+/**
+ * English messages by code (the 1.0 API). Views carry the code beside an English `message`; the
+ * components show `signMessage(code, locale)` in the page's language.
+ */
+export const MESSAGES: Record<string, string> = Object.fromEntries(
+	CODES.map((code) => [code, signMessage(code, "en")]),
+);
+
+const message = (code: string) => signMessage(code, "en");
+
+/** A receipt token as the protocol defines it (§4): two base64url segments, a 43-character signature. */
+const RECEIPT_TOKEN = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]{43}$/;
+
+/**
+ * The link back to the sender's site (protocol §8.2): the return URL, with `#receipt=<token>` when
+ * the core issued a receipt. The receipt only ever goes in the fragment, which browsers never send to
+ * a server or put in a Referer; a return URL that already has a fragment is left as it is.
+ */
+export function receiptReturnUrl(done: Done): string | undefined {
+	const returnUrl = safeReturnUrl(done.returnUrl);
+	if (!returnUrl) return undefined;
+	const { receipt } = done;
+	if (typeof receipt !== "string" || !RECEIPT_TOKEN.test(receipt) || returnUrl.includes("#")) return returnUrl;
+	return `${returnUrl}#receipt=${receipt}`;
+}
+
+/**
+ * Where the sign page redirects (303) once a sign or decline ended the ceremony with a receipt, so
+ * the browser lands on the sender's site with it (§8.2). A plain visit to a closed envelope only
+ * shows the link.
+ */
+export function ceremonyRedirect(view: SignView): string | undefined {
+	if (view.kind !== "signed" && view.kind !== "declined") return undefined;
+	return view.returnUrl?.includes("#receipt=") ? view.returnUrl : undefined;
+}
+
+/** Only http(s) URLs may be offered as a link back to the sender's site. */
+export function safeReturnUrl(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	try {
+		const url = new URL(value);
+		return url.protocol === "https:" || url.protocol === "http:" ? url.href : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+const text = (form: FormData, key: string) => {
+	const value = form.get(key);
+	return typeof value === "string" ? value.trim() : "";
+};
+
+function closedView(session: SessionData): SignView {
+	// Signed, but the envelope is still open for the other signers (SU-FR-11).
+	if (session.status === "sent" || session.status === "in_progress") {
+		return { kind: "waiting", ...(session.title ? { title: session.title } : {}) };
+	}
+	const returnUrl = receiptReturnUrl(session);
+	return {
+		...(returnUrl ? { returnUrl } : {}),
+		kind: "closed",
+		status: session.status ?? "closed",
+		...(session.title ? { title: session.title } : {}),
+		...(session.pdf ? { pdf: session.pdf } : {}),
+		...(session.download ? { download: session.download.url } : {}),
+	};
+}
+
+/** Loads the session, and when `form` is a POST, performs the sign or decline it asks for. */
+export async function handleSign(ctx: PublicRouteContext, token: string, form: FormData | null): Promise<SignView> {
+	// Only a form post (a person acting) opens the envelope; a GET may be a mail scanner (T117).
+	const first = await callPublicRoute<SessionData>(ctx, {
+		method: "POST",
+		path: "public/session",
+		body: form ? { token, open: true } : { token },
+	});
+	if (!first.ok) return { kind: "error", code: first.error.code, message: message(first.error.code) };
+	const session = first.data;
+	if (session.state !== "ready") return closedView(session);
+	if (!form) return { kind: "ready", session };
+
+	const intent = text(form, "intent");
+	if (intent === "otp-send" || intent === "otp-verify") {
+		const verify = intent === "otp-verify";
+		const result = await callPublicRoute<{ ok: true }>(ctx, {
+			method: "POST",
+			path: verify ? "public/otp/verify" : "public/otp/send",
+			body: verify ? { token, code: text(form, "code") } : { token },
+		});
+		if (!result.ok)
+			return { kind: "ready", session, errorCode: result.error.code, message: message(result.error.code) };
+		// A verified code changes what the session offers: load it again.
+		const again = verify
+			? await callPublicRoute<SessionData>(ctx, { method: "POST", path: "public/session", body: { token } })
+			: undefined;
+		return { kind: "ready", session: again?.ok ? again.data : session, ...(verify ? {} : { otpSent: true as const }) };
+	}
+	if (intent === "decline") {
+		const reason = text(form, "reason");
+		const result = await callPublicRoute<Done>(ctx, {
+			method: "POST",
+			path: "public/decline",
+			body: { token, ...(reason ? { reason } : {}) },
+		});
+		if (!result.ok)
+			return { kind: "ready", session, errorCode: result.error.code, message: message(result.error.code) };
+		const returnUrl = receiptReturnUrl(result.data);
+		return returnUrl ? { kind: "declined", returnUrl } : { kind: "declined" };
+	}
+
+	const typedName = text(form, "typedName");
+	const strokes = formStrokes(form);
+	const fieldValues: Record<string, string> = {};
+	const missingFields: string[] = [];
+	for (const field of sessionFields(session)) {
+		const value = text(form, fieldName(field.key));
+		if (value) fieldValues[field.key] = value;
+		else if (field.required) missingFields.push(fieldName(field.key));
+	}
+	const fields = [
+		...missingFields,
+		...(typedName ? [] : ["typedName"]),
+		...(strokes && !strokes.ok ? ["signature"] : []),
+		...(form.get("consent") === "on" ? [] : ["consent"]),
+		...(form.get("agree") === "on" ? [] : ["agree"]),
+	];
+	if (fields.length > 0) {
+		const code = strokes && !strokes.ok && strokes.code === "STROKES_TOO_LARGE" ? strokes.code : "BAD_REQUEST";
+		return { kind: "ready", session, fields, errorCode: code, message: message(code) };
+	}
+	const result = await callPublicRoute<Done>(ctx, {
+		method: "POST",
+		path: "public/submit",
+		body: {
+			token,
+			docSha256: session.envelope?.docSha256 ?? "",
+			consentSha256: session.consent?.sha256 ?? "",
+			consent: true,
+			intent: true,
+			signature: strokes?.ok ? { kind: "drawn", typedName, strokes: strokes.strokes } : { kind: "typed", typedName },
+			fieldValues,
+		},
+	});
+	if (!result.ok) {
+		const issues = [...new Set((result.error.issues ?? []).map((i) => ISSUE_FIELD[i.path] ?? i.path))];
+		return {
+			kind: "ready",
+			session,
+			...(issues.length ? { fields: issues } : {}),
+			errorCode: result.error.code,
+			message: message(result.error.code),
+		};
+	}
+	// The signed PDF is built by a job just after; the session shows its link once it is stored.
+	const after = await callPublicRoute<SessionData>(ctx, { method: "POST", path: "public/session", body: { token } });
+	const done = after.ok ? after.data : undefined;
+	const returnUrl = receiptReturnUrl(result.data);
+	return {
+		kind: "signed",
+		...(result.data.status && result.data.status !== "completed" ? { waiting: true as const } : {}),
+		...(returnUrl ? { returnUrl } : {}),
+		...(done?.download ? { download: done.download.url } : {}),
+		pdf: done?.pdf ?? "pending",
+	};
+}
+
+export type SignedCopyView = SignView | { kind: "unsigned" };
+
+/**
+ * The stable "get my signed copy" page (ES-US-6): the emailed signing token in the path, POSTed to
+ * `public/session`, which hands a signer of a completed envelope a fresh download link each time.
+ * The token is never logged or put in a URL.
+ */
+export async function handleSignedCopy(ctx: PublicRouteContext, token: string): Promise<SignedCopyView> {
+	const result = await callPublicRoute<SessionData>(ctx, { method: "POST", path: "public/session", body: { token } });
+	if (!result.ok) return { kind: "error", code: result.error.code, message: message(result.error.code) };
+	return result.data.state === "ready" ? { kind: "unsigned" } : closedView(result.data);
+}
+
+export interface VerifyData {
+	ok: true;
+	matched: boolean;
+	status?: string;
+	completedAt?: string | null;
+	finalHash?: string | null;
+	chainVerified?: boolean | null;
+}
+
+export type VerifyView =
+	| { kind: "form" }
+	| { kind: "error"; code: string; message: string }
+	| { kind: "result"; sha256: string; data: VerifyData };
+
+/** A SHA-256 in hex, as `public/verify` takes it. */
+export const SHA256_HEX = /^[0-9a-f]{64}$/i;
+
+export async function handleVerify(ctx: PublicRouteContext, form: FormData | null): Promise<VerifyView> {
+	if (!form) return { kind: "form" };
+	const sha256 = text(form, "sha256").toLowerCase();
+	if (!SHA256_HEX.test(sha256)) {
+		return {
+			kind: "error",
+			code: "BAD_REQUEST",
+			message: t("en", "verify.error.BAD_REQUEST"),
+		};
+	}
+	const result = await callPublicRoute<VerifyData>(ctx, { method: "POST", path: "public/verify", body: { sha256 } });
+	if (!result.ok) return { kind: "error", code: result.error.code, message: message(result.error.code) };
+	return { kind: "result", sha256, data: result.data };
+}

package/src/astro/self-serve-endpoint.ts

@@ -0,0 +1,11 @@
+// Injected at `/_esign/start` by the integration. A plain form post (no JavaScript needed).
+// Cross-site posts get a 403 before anything runs (`isCrossSiteRequest`).
+import { pluginId } from "virtual:semics-esign/config";
+
+import { handleStartRequest, type StartEndpointContext } from "./lib/self-serve.ts";
+
+export const prerender = false;
+
+export function POST(ctx: StartEndpointContext): Promise<Response> {
+	return handleStartRequest(ctx, { pluginId });
+}

package/src/astro/virtual.d.ts

@@ -0,0 +1,10 @@
+// Provided by the integration's Vite plugin (`esignIntegration({ pluginId })`).
+declare module "virtual:semics-esign/config" {
+	export const pluginId: string;
+}
+
+// Vite's `?raw` imports: the file's text, untransformed.
+declare module "*?raw" {
+	const text: string;
+	export default text;
+}

package/src/client/ceremony.d.ts

@@ -0,0 +1,31 @@
+// Types for ceremony.js, which is plain JavaScript so the page can inline its exact text (CSP hash).
+export interface FieldState {
+	name: string;
+	required: boolean;
+	value: string;
+}
+
+export interface SignState {
+	typedName: string;
+	consent: boolean;
+	intent: boolean;
+	fields: FieldState[];
+}
+
+export interface CeremonyOptions {
+	fetch?: typeof fetch;
+	intervalMs?: number;
+	attempts?: number;
+}
+
+export function missingForSign(state: SignState): string[];
+/** The live "To sign, please ..." note, from the ceremony's messages (T102). */
+export function missingNote(
+	missing: string[],
+	messages: Record<string, string>,
+	labels: Record<string, string | undefined>,
+	lang?: string,
+): string;
+export function safeDownloadHref(value: unknown, origin: string): string | undefined;
+export function pdfLinkFrom(reply: unknown, origin: string): string | undefined;
+export function enhanceCeremony(root: Document, options?: CeremonyOptions): void;

package/src/client/ceremony.js

@@ -0,0 +1,218 @@
+// @ts-check
+/**
+ * Progressive enhancement for <SigningCeremony> (SU-FR-04, SU-FR-07). The ceremony works without
+ * this script: the form posts to the page and the server checks it. With it, the signer gets:
+ *
+ * - Sign disabled until the consent box, the intent box, the typed name and every required field
+ *   are complete, with a live note of what is still missing;
+ * - a guard against double submits;
+ * - after signing, `public/session` polled until the signed PDF is stored, then its download link.
+ *
+ * Plain JavaScript, no imports: the page inlines this file's exact text and allows it by its
+ * SHA-256 in the Content-Security-Policy (src/astro/lib/csp.ts), so it must not be transformed.
+ * Text only ever goes in through `textContent`; links only through a checked `href`.
+ */
+
+/**
+ * @typedef {{ name: string; required: boolean; value: string }} FieldState
+ * @typedef {{ typedName: string; consent: boolean; intent: boolean; fields: FieldState[] }} SignState
+ */
+
+/**
+ * The form controls still to complete before signing, in form order.
+ * @param {SignState} state
+ * @returns {string[]}
+ */
+export function missingForSign(state) {
+	const missing = state.fields.filter((f) => f.required && f.value.trim() === "").map((f) => f.name);
+	if (state.typedName.trim() === "") missing.push("typedName");
+	if (!state.consent) missing.push("consent");
+	if (!state.intent) missing.push("agree");
+	return missing;
+}
+
+/**
+ * A same-origin URL for the signed PDF, or `undefined` for anything else.
+ * @param {unknown} value
+ * @param {string} origin
+ * @returns {string | undefined}
+ */
+export function safeDownloadHref(value, origin) {
+	if (typeof value !== "string" || !value.startsWith("/") || value.startsWith("//")) return undefined;
+	try {
+		const url = new URL(value, origin);
+		return url.origin === origin ? url.href : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * The download link in a `public/session` reply once the PDF is ready.
+ * @param {unknown} reply the route's JSON envelope (`{ success, data }`)
+ * @param {string} origin
+ * @returns {string | undefined}
+ */
+export function pdfLinkFrom(reply, origin) {
+	const data =
+		reply && typeof reply === "object" && /** @type {{ success?: unknown }} */ (reply).success === true
+			? /** @type {{ data?: any }} */ (reply).data
+			: undefined;
+	if (!data || data.ok === false || data.pdf !== "ready") return undefined;
+	return safeDownloadHref(data.download?.url, origin);
+}
+
+/**
+ * The ceremony's messages in the page's language: the component renders them as JSON in the
+ * `data-messages` attribute of its root (T102), so this script holds no text of its own.
+ * @param {Element} el
+ * @returns {Record<string, string>}
+ */
+function messagesOf(el) {
+	try {
+		return JSON.parse(/** @type {HTMLElement | null} */ (el.closest("[data-messages]"))?.dataset.messages ?? "{}");
+	} catch {
+		return {};
+	}
+}
+
+/**
+ * @param {Record<string, string>} m
+ * @param {string} key
+ * @param {Record<string, string>} [vars]
+ */
+function say(m, key, vars = {}) {
+	return (m[key] ?? key).replace(/\{(\w+)\}/g, (whole, name) => vars[name] ?? whole);
+}
+
+/** @type {Record<string, string>} */
+const NEEDS = { typedName: "need.typedName", consent: "need.consent", agree: "need.agree" };
+
+/**
+ * The live note of what is still missing before signing ("To sign, please type your full name, ...").
+ * @param {string[]} missing control names, from `missingForSign`
+ * @param {Record<string, string>} m the ceremony's messages (keys without `ceremony.`)
+ * @param {Record<string, string | undefined>} labels a signer field's label by control name
+ * @param {string} [_lang] the page's language (kept for list formatting)
+ * @returns {string}
+ */
+export function missingNote(missing, m, labels, _lang) {
+	if (missing.length === 0) return "";
+	const items = missing.map((name) => {
+		const need = NEEDS[name];
+		if (need) return say(m, need);
+		return say(m, "need.field", { label: labels[name] ?? say(m, "need.fields") });
+	});
+	return say(m, "missing", { items: items.join(m.separator ?? ", ") });
+}
+
+/**
+ * @param {HTMLFormElement} form
+ * @returns {SignState}
+ */
+function readState(form) {
+	const control = (/** @type {string} */ name) =>
+		/** @type {HTMLInputElement | null} */ (form.elements.namedItem(name));
+	return {
+		typedName: control("typedName")?.value ?? "",
+		consent: control("consent")?.checked ?? false,
+		intent: control("agree")?.checked ?? false,
+		fields: [...form.querySelectorAll("[data-esign-field]")].map((el) => {
+			const input = /** @type {HTMLInputElement} */ (el);
+			return { name: input.name, required: input.required, value: input.value };
+		}),
+	};
+}
+
+/**
+ * @param {HTMLFormElement} form
+ */
+function enhanceSignForm(form) {
+	const button = /** @type {HTMLButtonElement | null} */ (form.querySelector("[data-esign-sign]"));
+	const note = /** @type {HTMLElement | null} */ (form.querySelector("[data-esign-missing]"));
+	if (!button) return;
+	const m = messagesOf(form);
+	let sending = false;
+	const update = () => {
+		const missing = missingForSign(readState(form));
+		button.disabled = sending || missing.length > 0;
+		if (!note) return;
+		note.hidden = missing.length === 0;
+		/** @type {Record<string, string | undefined>} */
+		const labels = {};
+		for (const name of missing) {
+			const field = /** @type {HTMLElement | null} */ (form.querySelector(`[name="${CSS.escape(name)}"]`));
+			labels[name] = field?.dataset.label;
+		}
+		note.textContent = missingNote(missing, m, labels, document.documentElement.lang);
+	};
+	form.addEventListener("input", update);
+	form.addEventListener("change", update);
+	form.addEventListener("submit", (event) => {
+		if (sending || missingForSign(readState(form)).length > 0) {
+			event.preventDefault();
+			return;
+		}
+		sending = true;
+		button.setAttribute("aria-busy", "true");
+		// After the submit is under way, so the button's own name and value are still sent.
+		setTimeout(update, 0);
+	});
+	update();
+}
+
+/**
+ * @param {HTMLElement} box
+ * @param {{ fetch?: typeof fetch; intervalMs?: number; attempts?: number }} options
+ */
+function pollForPdf(box, options) {
+	const token = box.dataset.token ?? "";
+	const plugin = box.dataset.plugin ?? "";
+	const target = /** @type {HTMLElement | null} */ (box.querySelector("[data-esign-pdf]"));
+	if (!token || !plugin || !target) return;
+	const m = messagesOf(box);
+	const doFetch = options.fetch ?? fetch.bind(globalThis);
+	const interval = options.intervalMs ?? 3000;
+	let left = options.attempts ?? 60;
+	const route = `/_emdash/api/plugins/${encodeURIComponent(plugin)}/public/session`;
+	const tick = async () => {
+		left--;
+		let href;
+		try {
+			const response = await doFetch(route, {
+				method: "POST",
+				headers: { "content-type": "application/json", "X-EmDash-Request": "1" },
+				body: JSON.stringify({ token }),
+				credentials: "same-origin",
+				cache: "no-store",
+				referrerPolicy: "no-referrer",
+			});
+			href = pdfLinkFrom(await response.json(), location.origin);
+		} catch {
+			href = undefined;
+		}
+		if (href) {
+			const link = document.createElement("a");
+			link.href = href;
+			link.textContent = say(m, "download");
+			target.replaceChildren(link);
+			return;
+		}
+		if (left > 0) setTimeout(tick, interval);
+		else target.textContent = say(m, "slow");
+	};
+	void tick();
+}
+
+/**
+ * Wires every ceremony on the page.
+ * @param {Document} root
+ * @param {{ fetch?: typeof fetch; intervalMs?: number; attempts?: number }} [options]
+ */
+export function enhanceCeremony(root, options = {}) {
+	for (const form of root.querySelectorAll("form[data-esign-sign-form]"))
+		enhanceSignForm(/** @type {HTMLFormElement} */ (form));
+	for (const box of root.querySelectorAll("[data-esign-poll]")) pollForPdf(/** @type {HTMLElement} */ (box), options);
+}
+
+if (typeof document !== "undefined") enhanceCeremony(document);