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

package/src/astro/lib/markdown.ts

@@ -0,0 +1,363 @@
+/**
+ * The snapshot renderer's sanitiser (SU-FR-03, SU-NFR-01). A snapshot is sender-written,
+ * Markdown-ish template text whose `{{field}}` values were escaped by shared `renderTemplate`
+ * (`&<>"'` as entities, Markdown punctuation with a backslash). It is what `docSha256` covers, so
+ * it is shown as it is, never rewritten.
+ *
+ * Rather than producing HTML and cleaning it, this parses the text into a tree of a few allowed
+ * node kinds (headings, paragraphs, lists, quotes, code, rules; strong, emphasis, code spans, line
+ * breaks, links) holding plain strings. The Astro components render the tree through `{text}`
+ * interpolation, which escapes, so raw HTML in the text can only ever show up as text. The only
+ * attribute that comes from the text is a link's `href`, and only an absolute http(s) or mailto
+ * URL passes `safeHref`; anything else, images included, stays literal text. Work is linear in the
+ * input: failed delimiter searches are remembered and nesting is capped.
+ */
+
+export type Inline =
+	| { type: "text"; text: string }
+	| { type: "strong"; children: Inline[] }
+	| { type: "em"; children: Inline[] }
+	| { type: "code"; text: string }
+	| { type: "link"; href: string; children: Inline[] }
+	| { type: "break" };
+
+export type Block =
+	| { type: "heading"; level: 2 | 3 | 4 | 5 | 6; children: Inline[] }
+	| { type: "paragraph"; children: Inline[] }
+	| { type: "list"; ordered: boolean; start?: number; items: Inline[][] }
+	| { type: "quote"; children: Block[] }
+	| { type: "code"; text: string }
+	| { type: "rule" };
+
+const MAX_INLINE_DEPTH = 6;
+const MAX_QUOTE_DEPTH = 4;
+const ENTITIES: Record<string, string> = { amp: "&", lt: "<", gt: ">", quot: '"', "#39": "'" };
+const ENTITY = /^&(amp|lt|gt|quot|#39);/;
+const PUNCT = /[!-/:-@[-`{-~]/;
+const WORD = /[\p{L}\p{N}]/u;
+// biome-ignore lint/suspicious/noControlCharactersInRegex: control characters never belong in a link.
+const UNSAFE_URL_CHARS = /[\s"'<>`\\\u0000-\u001F\u007F]/;
+const SAFE_URL_START = /^(https?:\/\/|mailto:)/i;
+/** Every character the inline parser treats specially; anything else is plain text. */
+const SPECIAL_CHARS = new Set(["\\", "&", "\n", "`", "*", "_", "[", "!", "<"]);
+const SPECIAL = /[\\&\n`*_[!<]/g;
+
+/** An absolute http, https or mailto URL, normalised; anything else is `undefined`. */
+export function safeHref(raw: string): string | undefined {
+	if (raw.length === 0 || UNSAFE_URL_CHARS.test(raw) || !SAFE_URL_START.test(raw)) return undefined;
+	try {
+		// The scheme is the checked prefix, so the parsed protocol is http:, https: or mailto:.
+		return new URL(raw).href;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Undoes `escapeValue`: the five entities it writes and backslash-escaped punctuation. */
+export function decodeText(text: string): string {
+	return text.replace(/\\([!-/:-@[-`{-~])|&(amp|lt|gt|quot|#39);/g, (_all, punct?: string, entity?: string) =>
+		punct !== undefined ? punct : (ENTITIES[entity as string] as string),
+	);
+}
+
+// --- inline ---
+
+type Found = { inline?: Inline; text?: string; end: number };
+
+/** Index of the partner of every bracket (stack matching, escapes honoured), for `[]` and `()`. */
+function pairs(src: string): Map<number, number> {
+	const out = new Map<number, number>();
+	const stacks: Record<string, number[]> = { "]": [], ")": [] };
+	const openerOf: Record<string, string> = { "[": "]", "(": ")" };
+	// Only brackets and backslashes matter: jump between them rather than walking every character.
+	const marks = /[\\[\]()]/g;
+	for (let found = marks.exec(src); found; found = marks.exec(src)) {
+		const j = found.index;
+		const c = found[0];
+		if (c === "\\") marks.lastIndex = j + 2;
+		else if (c in openerOf) stacks[openerOf[c] as string]?.push(j);
+		else {
+			const open = stacks[c]?.pop();
+			if (open !== undefined) out.set(open, j);
+		}
+	}
+	return out;
+}
+
+class InlineParser {
+	private readonly partner: Map<number, number>;
+	/** Per closer kind, the last search: closers do not depend on their opener, so it can be reused. */
+	private readonly memo = new Map<string, { from: number; at: number }>();
+
+	constructor(private readonly src: string) {
+		this.partner = pairs(src);
+	}
+
+	parse(from: number, to: number, depth: number): Inline[] {
+		const { src } = this;
+		const out: Inline[] = [];
+		let buf = "";
+		const flush = () => {
+			if (buf) out.push({ type: "text", text: buf });
+			buf = "";
+		};
+		let i = from;
+		while (i < to) {
+			const ch = src[i] as string;
+			if (!SPECIAL_CHARS.has(ch)) {
+				// Plain text up to the next character any rule below looks at, in one slice (the signed PDF
+				// job parses whole documents, so this keeps it linear with a small constant; T117).
+				SPECIAL.lastIndex = i;
+				const next = SPECIAL.exec(src);
+				const stop = next && next.index < to ? next.index : to;
+				buf += src.slice(i, stop);
+				i = stop;
+				continue;
+			}
+			if (ch === "\\" && i + 1 < to && PUNCT.test(src[i + 1] as string)) {
+				buf += src[i + 1];
+				i += 2;
+				continue;
+			}
+			const entity = ch === "&" ? ENTITY.exec(src.slice(i, Math.min(to, i + 6))) : null;
+			if (entity) {
+				buf += ENTITIES[entity[1] as string];
+				i += entity[0].length;
+				continue;
+			}
+			if (ch === "\n") {
+				flush();
+				out.push({ type: "break" });
+				i++;
+				continue;
+			}
+			const found = depth < MAX_INLINE_DEPTH ? this.markup(i, to, depth) : undefined;
+			if (found?.inline) {
+				flush();
+				out.push(found.inline);
+			} else buf += found ? found.text : ch;
+			i = found ? found.end : i + 1;
+		}
+		flush();
+		return out;
+	}
+
+	/** The markup starting at `i`, if any: a node, or literal text to keep (an image's alt text). */
+	private markup(i: number, to: number, depth: number): Found | undefined {
+		const ch = this.src[i];
+		if (ch === "`") return this.codeSpan(i, to);
+		if (ch === "*" || ch === "_") return this.emphasis(i, to, depth);
+		if (ch === "[") return this.link(i, to, depth, false);
+		if (ch === "!" && this.src[i + 1] === "[") return this.link(i + 1, to, depth, true);
+		if (ch === "<") return this.autolink(i, to);
+		return undefined;
+	}
+
+	/**
+	 * The first index at or after `from` where `valid` holds, or -1. `valid` must not depend on the
+	 * opener, so a search for the same `key` from inside the last answered range has the same answer.
+	 */
+	private next(key: string, from: number, step: (at: number) => number, valid: (at: number) => boolean): number {
+		const last = this.memo.get(key);
+		if (last && from >= last.from && (last.at === -1 || from <= last.at)) return last.at;
+		let at = step(from);
+		while (at !== -1 && !valid(at)) at = step(at + 1);
+		this.memo.set(key, { from, at });
+		return at;
+	}
+
+	private escaped(at: number): boolean {
+		let slashes = 0;
+		for (let j = at - 1; j >= 0 && this.src[j] === "\\"; j--) slashes++;
+		return slashes % 2 === 1;
+	}
+
+	private codeSpan(i: number, to: number): Found {
+		const { src } = this;
+		let n = 1;
+		while (src[i + n] === "`") n++;
+		const fence = "`".repeat(n);
+		// A closer is a run of exactly n backticks.
+		const close = this.next(
+			`code${n}`,
+			i + n,
+			(at) => src.indexOf(fence, at),
+			(at) => src[at - 1] !== "`" && src[at + n] !== "`",
+		);
+		if (close === -1 || close + n > to) return { text: fence, end: i + n };
+		return { inline: { type: "code", text: decodeText(src.slice(i + n, close)) }, end: close + n };
+	}
+
+	private emphasis(i: number, to: number, depth: number): Found {
+		const { src } = this;
+		const ch = src[i] as string;
+		const delim = src[i + 1] === ch ? ch + ch : ch;
+		const start = i + delim.length;
+		const word = (at: number) => at >= 0 && at < src.length && WORD.test(src[at] as string);
+		const intraword = (at: number) => ch === "_" && word(at);
+		const literal = { text: delim, end: start };
+		if (intraword(i - 1) || start >= to || /\s/.test(src[start] as string)) return literal;
+		const close = this.next(
+			delim,
+			start + 1,
+			(at) => src.indexOf(delim, at),
+			(at) => !this.escaped(at) && !/\s/.test(src[at - 1] as string) && !intraword(at + delim.length),
+		);
+		if (close === -1 || close + delim.length > to) return literal;
+		const children = this.parse(start, close, depth + 1);
+		return { inline: { type: delim.length === 2 ? "strong" : "em", children }, end: close + delim.length };
+	}
+
+	/** `[text](url)`; with `image`, `![alt](url)`, of which only the alt text is shown. */
+	private link(i: number, to: number, depth: number, image: boolean): Found {
+		const { src } = this;
+		const literal = { text: image ? "![" : "[", end: i + 1 };
+		const closeText = this.partner.get(i);
+		if (closeText === undefined || closeText >= to || src[closeText + 1] !== "(") return literal;
+		const closeUrl = this.partner.get(closeText + 1);
+		if (closeUrl === undefined || closeUrl >= to) return literal;
+		const end = closeUrl + 1;
+		if (image) return { text: decodeText(src.slice(i + 1, closeText)), end };
+		const href = safeHref(decodeText(src.slice(closeText + 2, closeUrl)));
+		if (!href) return { text: decodeText(src.slice(i, end)), end };
+		return { inline: { type: "link", href, children: this.parse(i + 1, closeText, depth + 1) }, end };
+	}
+
+	private autolink(i: number, to: number): Found | undefined {
+		const match = /^<([A-Za-z][A-Za-z0-9+.-]*:[^\s<>]*)>/.exec(this.src.slice(i, Math.min(to, i + 2048)));
+		const href = match ? safeHref(match[1] as string) : undefined;
+		if (!match || !href) return undefined;
+		return {
+			inline: { type: "link", href, children: [{ type: "text", text: match[1] as string }] },
+			end: i + match[0].length,
+		};
+	}
+}
+
+function inline(text: string): Inline[] {
+	return new InlineParser(text).parse(0, text.length, 0);
+}
+
+// --- blocks ---
+
+const FENCE = /^ {0,3}(`{3,}|~{3,})/;
+const HEADING = /^ {0,3}(#{1,6})(?:[ \t]+(.*?))?(?:[ \t]+#+)?[ \t]*$/;
+const RULE = /^ {0,3}([-*_])(?:[ \t]*\1){2,}[ \t]*$/;
+const QUOTE = /^ {0,3}> ?(.*)$/;
+const BULLET = /^ {0,3}[-*+][ \t]+(.*)$/;
+const ORDERED = /^ {0,3}(\d{1,9})[.)][ \t]+(.*)$/;
+
+const blank = (line: string) => line.trim() === "";
+const startsBlock = (line: string) =>
+	FENCE.test(line) ||
+	HEADING.test(line) ||
+	RULE.test(line) ||
+	QUOTE.test(line) ||
+	BULLET.test(line) ||
+	ORDERED.test(line);
+
+function blocks(lines: string[], depth: number): Block[] {
+	const out: Block[] = [];
+	let i = 0;
+	while (i < lines.length) {
+		const line = lines[i] as string;
+		if (blank(line)) {
+			i++;
+			continue;
+		}
+		const fence = FENCE.exec(line);
+		if (fence) {
+			const marker = fence[1] as string;
+			const closer = new RegExp(`^ {0,3}${marker[0]}{${marker.length},}[ \\t]*$`);
+			const body: string[] = [];
+			i++;
+			while (i < lines.length && !closer.test(lines[i] as string)) {
+				body.push(lines[i] as string);
+				i++;
+			}
+			i++;
+			out.push({ type: "code", text: decodeText(body.join("\n")) });
+			continue;
+		}
+		if (RULE.test(line)) {
+			out.push({ type: "rule" });
+			i++;
+			continue;
+		}
+		const heading = HEADING.exec(line);
+		if (heading) {
+			const level = Math.min(6, (heading[1] as string).length + 1) as 2 | 3 | 4 | 5 | 6;
+			out.push({ type: "heading", level, children: inline(heading[2] ?? "") });
+			i++;
+			continue;
+		}
+		if (QUOTE.test(line) && depth < MAX_QUOTE_DEPTH) {
+			const inner: string[] = [];
+			while (i < lines.length && QUOTE.test(lines[i] as string)) {
+				inner.push((QUOTE.exec(lines[i] as string) as RegExpExecArray)[1] as string);
+				i++;
+			}
+			out.push({ type: "quote", children: blocks(inner, depth + 1) });
+			continue;
+		}
+		const bullet = BULLET.test(line);
+		const ordered = ORDERED.exec(line);
+		if (bullet || ordered) {
+			const pattern = bullet ? BULLET : ORDERED;
+			const items: string[][] = [];
+			while (i < lines.length) {
+				const current = lines[i] as string;
+				const item = pattern.exec(current);
+				if (item) items.push([(bullet ? item[1] : item[2]) as string]);
+				else if (!blank(current) && /^ {2,}\S/.test(current) && !startsBlock(current.trimStart())) {
+					(items.at(-1) as string[]).push(current.trim());
+				} else break;
+				i++;
+			}
+			out.push({
+				type: "list",
+				ordered: !bullet,
+				...(ordered && ordered[1] !== "1" ? { start: Number(ordered[1]) } : {}),
+				items: items.map((item) => inline(item.join("\n"))),
+			});
+			continue;
+		}
+		const para: string[] = [line.trim()];
+		i++;
+		while (i < lines.length && !blank(lines[i] as string) && !startsBlock(lines[i] as string)) {
+			para.push((lines[i] as string).trim());
+			i++;
+		}
+		out.push({ type: "paragraph", children: inline(para.join("\n")) });
+	}
+	return out;
+}
+
+/** The snapshot as a tree of allowed nodes. Line endings are normalised; nothing else is changed. */
+export function parseSnapshot(text: string): Block[] {
+	return blocks(text.replace(/\r\n?/g, "\n").split("\n"), 0);
+}
+
+/** The visible text of a tree (blocks separated by blank lines, breaks as newlines). */
+export function textOf(tree: Block[]): string {
+	const ofInline = (nodes: Inline[]): string =>
+		nodes
+			.map((n) => (n.type === "text" || n.type === "code" ? n.text : n.type === "break" ? "\n" : ofInline(n.children)))
+			.join("");
+	return tree
+		.map((b) => {
+			switch (b.type) {
+				case "quote":
+					return textOf(b.children);
+				case "list":
+					return b.items.map(ofInline).join("\n");
+				case "code":
+					return b.text;
+				case "rule":
+					return "";
+				default:
+					return ofInline(b.children);
+			}
+		})
+		.join("\n\n");
+}

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

@@ -0,0 +1,149 @@
+import { type MessageKey, t } from "../../i18n/index.ts";
+import { callPublicRoute, type PublicRouteContext } from "./call.ts";
+import { crossSiteResponse, isCrossSiteRequest } from "./csrf.ts";
+
+/**
+ * The `esign-request` block's logic (ES-FR-18, SU-FR-12), kept out of the `.astro` file so it is testable.
+ * It only calls `public/self-serve/start`, which is a NOT_FOUND stub on Free: there the block renders its
+ * unavailable state and no form. The signing link goes to the visitor's inbox and is never in a response.
+ */
+
+export const START_PATH = "/_esign/start";
+const ROUTE = "public/self-serve/start";
+const STATE_PARAM = "esign_start";
+const TEMPLATE_PARAM = "esign_t";
+const FIELD_PREFIX = "field:";
+
+export interface SelfServeTemplate {
+	id: string;
+	name: string;
+	description?: string;
+	/** Placeholders the visitor fills in (name and email are always asked). */
+	fields: string[];
+}
+
+export type SelfServeView =
+	| { state: "ready"; template: SelfServeTemplate; turnstileSiteKey?: string }
+	| { state: "unavailable" };
+
+/** Describes the block's template through the core; any refusal (Free's stub, no licence, not offered) is `unavailable`. */
+export async function loadSelfServe(
+	ctx: PublicRouteContext,
+	options: { templateId: string; pluginId?: string },
+): Promise<SelfServeView> {
+	const templateId = options.templateId.trim();
+	if (!templateId) return { state: "unavailable" };
+	const res = await callPublicRoute<{ template?: SelfServeTemplate; turnstileSiteKey?: string }>(ctx, {
+		method: "POST",
+		path: ROUTE,
+		body: { templateId, describe: true },
+		...(options.pluginId ? { pluginId: options.pluginId } : {}),
+	});
+	if (!res.ok || !res.data.template) return { state: "unavailable" };
+	const { template, turnstileSiteKey } = res.data;
+	return { state: "ready", template, ...(turnstileSiteKey ? { turnstileSiteKey } : {}) };
+}
+
+const text = (form: FormData, key: string): string => {
+	const v = form.get(key);
+	return typeof v === "string" ? v.trim() : "";
+};
+
+/** A same-site path, so a post can never redirect elsewhere. */
+function safeReturnTo(raw: string, origin: string): string | undefined {
+	if (!raw.startsWith("/") || raw.startsWith("//") || raw.startsWith("/\\")) return undefined;
+	try {
+		const url = new URL(raw, origin);
+		if (url.origin !== origin || url.pathname.startsWith("//") || url.pathname.startsWith("/_esign/")) return undefined;
+		url.searchParams.delete(STATE_PARAM);
+		url.searchParams.delete(TEMPLATE_PARAM);
+		return `${url.pathname}${url.search}`;
+	} catch {
+		return undefined;
+	}
+}
+
+export const anchorOf = (templateId: string) => `esign-request-${templateId}`;
+
+function backTo(returnTo: string, templateId: string, state: string): string {
+	const url = new URL(returnTo, "https://x.invalid");
+	url.searchParams.set(STATE_PARAM, state);
+	url.searchParams.set(TEMPLATE_PARAM, templateId);
+	return `${url.pathname}${url.search}#${anchorOf(templateId)}`;
+}
+
+export type StartResult = { location: string } | { status: number; message: string };
+
+/** Posts the visitor's details to the core and says where to go next. Values are never put in the location. */
+export async function handleSelfServeForm(
+	ctx: PublicRouteContext,
+	form: FormData,
+	options: { pluginId?: string },
+): Promise<StartResult> {
+	const templateId = text(form, "templateId");
+	// i18n-ignore: a malformed post (not the block's form) gets a plain refusal.
+	if (!templateId) return { status: 400, message: "Missing template." };
+	const returnTo = safeReturnTo(text(form, "returnTo"), ctx.url.origin) ?? "/";
+	const fields: Record<string, string> = {};
+	for (const [key, value] of form.entries()) {
+		if (key.startsWith(FIELD_PREFIX) && typeof value === "string") fields[key.slice(FIELD_PREFIX.length)] = value;
+	}
+	const res = await callPublicRoute(ctx, {
+		method: "POST",
+		path: ROUTE,
+		...(options.pluginId ? { pluginId: options.pluginId } : {}),
+		body: {
+			templateId,
+			name: text(form, "name"),
+			email: text(form, "email"),
+			fields,
+			turnstileToken: text(form, "cf-turnstile-response"),
+			website: text(form, "website"),
+		},
+	});
+	return { location: backTo(returnTo, templateId, res.ok ? "sent" : res.error.code) };
+}
+
+/** What `POST /_esign/start` gets from Astro. */
+export interface StartEndpointContext {
+	request: Request;
+	url: URL;
+	locals: PublicRouteContext["locals"];
+	redirect(location: string, status?: number): Response;
+}
+
+/** `POST /_esign/start`: refuse cross-site posts first, then run the form and redirect (303). */
+export async function handleStartRequest(
+	{ request, url, locals, redirect }: StartEndpointContext,
+	options: { pluginId?: string },
+): Promise<Response> {
+	if (isCrossSiteRequest(request, url)) return crossSiteResponse();
+	const form = await request.formData().catch(() => new FormData());
+	const result = await handleSelfServeForm({ locals, url, request }, form, options);
+	if ("location" in result) return redirect(result.location, 303);
+	return new Response(result.message, {
+		status: result.status,
+		headers: { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" },
+	});
+}
+
+/** The state the block reads back from its page URL, for its own template only. */
+export function readStartState(url: URL, templateId: string): { sent: boolean; code?: string } {
+	if (url.searchParams.get(TEMPLATE_PARAM) !== templateId) return { sent: false };
+	const state = url.searchParams.get(STATE_PARAM);
+	if (state === "sent") return { sent: true };
+	return state ? { sent: false, code: state } : { sent: false };
+}
+
+const CODES = [
+	"TURNSTILE_FAILED",
+	"RATE_LIMITED",
+	"SELF_SERVE_FULL",
+	"BAD_REQUEST",
+	"TEMPLATE_NOT_FOUND",
+	"SITE_URL_MISSING",
+];
+
+/** What the block says about a refused start, in the locale's language (T102). */
+export const startMessage = (code: string, locale?: string): string =>
+	t(locale, `selfServe.error.${CODES.includes(code) ? code : "INTERNAL"}` as MessageKey);