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

package/src/astro/lib/assets.ts

@@ -0,0 +1,156 @@
+/**
+ * The ceremony's only script and stylesheet (SU-NFR-02). Both are inlined into the page and
+ * allowed by their SHA-256 in its Content-Security-Policy, so the page needs no `'unsafe-inline'`
+ * and loads nothing else. They are the package's own constants, never data.
+ */
+import CEREMONY_SCRIPT from "../../client/ceremony.js?raw";
+import PAD_SCRIPT from "../../client/pad.js?raw";
+import VERIFY_SCRIPT from "../../client/verify.js?raw";
+
+export { CEREMONY_SCRIPT, PAD_SCRIPT, VERIFY_SCRIPT };
+
+/** The verify page's only stylesheet (hashed into its CSP like the ceremony's). */
+export const VERIFY_CSS = `.semics-verify {
+	--_fg: var(--esign-fg, #1a1a1a);
+	--_muted: var(--esign-muted, #4a4a4a);
+	--_bg: var(--esign-bg, #ffffff);
+	--_border: var(--esign-border, #6b6b6b);
+	--_accent: var(--esign-accent, #0b57d0);
+	--_accent-fg: var(--esign-accent-fg, #ffffff);
+	--_error: var(--esign-error, #b3261e);
+	--_radius: var(--esign-radius, 6px);
+	box-sizing: border-box;
+	max-width: 44rem;
+	color: var(--_fg);
+	background: var(--_bg);
+	font: 1rem/1.5 system-ui, sans-serif;
+	overflow-wrap: anywhere;
+}
+.semics-verify *, .semics-verify *::before, .semics-verify *::after { box-sizing: inherit; }
+.semics-verify input[type="text"] {
+	width: 100%;
+	max-width: 36rem;
+	padding: 0.5rem;
+	font: 0.9em ui-monospace, monospace;
+	color: var(--_fg);
+	background: var(--_bg);
+	border: 1px solid var(--_border);
+	border-radius: var(--_radius);
+}
+.semics-verify .semics-drop {
+	margin: 1rem 0;
+	padding: 1rem;
+	border: 2px dashed var(--_border);
+	border-radius: var(--_radius);
+}
+.semics-verify .semics-drop.is-over { border-color: var(--_accent); background: color-mix(in srgb, var(--_accent) 8%, var(--_bg)); }
+.semics-verify .semics-note { color: var(--_muted); }
+.semics-verify .semics-error { color: var(--_error); font-weight: 600; }
+.semics-verify button {
+	font: inherit;
+	padding: 0.6rem 1.2rem;
+	border-radius: var(--_radius);
+	border: 1px solid var(--_accent);
+	background: var(--_accent);
+	color: var(--_accent-fg);
+	cursor: pointer;
+	min-height: 2.75rem;
+}
+.semics-verify button:focus-visible, .semics-verify input:focus-visible {
+	outline: 3px solid var(--_accent);
+	outline-offset: 2px;
+}
+.semics-verify .semics-result { margin-top: 1.5rem; padding-top: 1rem; border-top: 1px solid var(--_border); }
+`;
+
+export const CEREMONY_CSS = `.semics-ceremony {
+	--_fg: var(--esign-fg, #1a1a1a);
+	--_muted: var(--esign-muted, #4a4a4a);
+	--_bg: var(--esign-bg, #ffffff);
+	--_paper: var(--esign-paper, #fafafa);
+	--_border: var(--esign-border, #6b6b6b);
+	--_accent: var(--esign-accent, #0b57d0);
+	--_accent-fg: var(--esign-accent-fg, #ffffff);
+	--_error: var(--esign-error, #b3261e);
+	--_radius: var(--esign-radius, 6px);
+	box-sizing: border-box;
+	max-width: 44rem;
+	color: var(--_fg);
+	background: var(--_bg);
+	font: 1rem/1.5 system-ui, sans-serif;
+	overflow-wrap: anywhere;
+}
+.semics-ceremony *, .semics-ceremony *::before, .semics-ceremony *::after { box-sizing: inherit; }
+.semics-ceremony .semics-doc {
+	border: 1px solid var(--_border);
+	border-radius: var(--_radius);
+	background: var(--_paper);
+	padding: 1rem;
+	margin: 0 0 1rem;
+}
+.semics-ceremony .semics-doc > :first-child { margin-top: 0; }
+.semics-ceremony .semics-doc > :last-child { margin-bottom: 0; }
+.semics-ceremony pre {
+	white-space: pre-wrap;
+	overflow-wrap: anywhere;
+	font: 0.9em/1.4 ui-monospace, monospace;
+	margin: 0.75rem 0;
+}
+.semics-ceremony blockquote { margin: 0.75rem 0; padding-inline-start: 0.75rem; border-inline-start: 3px solid var(--_border); }
+.semics-ceremony a { color: var(--_accent); }
+.semics-ceremony details { margin: 0 0 1rem; }
+.semics-ceremony summary { cursor: pointer; color: var(--_muted); }
+.semics-ceremony .semics-hash { font-family: ui-monospace, monospace; font-size: 0.85em; }
+.semics-ceremony fieldset { border: 0; padding: 0; margin: 0 0 1rem; min-width: 0; }
+.semics-ceremony legend { font-weight: 600; padding: 0; margin-bottom: 0.5rem; }
+.semics-ceremony .semics-field { margin: 0 0 0.75rem; }
+.semics-ceremony .semics-field > label { display: block; margin-bottom: 0.25rem; }
+.semics-ceremony input[type="text"] {
+	width: 100%;
+	max-width: 28rem;
+	padding: 0.5rem;
+	font: inherit;
+	color: var(--_fg);
+	background: var(--_bg);
+	border: 1px solid var(--_border);
+	border-radius: var(--_radius);
+}
+.semics-ceremony .semics-check { display: flex; gap: 0.5rem; align-items: flex-start; margin: 0 0 0.75rem; }
+.semics-ceremony .semics-check input { margin-top: 0.3rem; flex: none; width: 1.1rem; height: 1.1rem; }
+.semics-ceremony [aria-invalid="true"] { outline: 2px solid var(--_error); outline-offset: 1px; }
+.semics-ceremony .semics-error { color: var(--_error); font-weight: 600; }
+.semics-ceremony .semics-note { color: var(--_muted); }
+.semics-ceremony button {
+	font: inherit;
+	padding: 0.6rem 1.2rem;
+	border-radius: var(--_radius);
+	border: 1px solid var(--_accent);
+	background: var(--_accent);
+	color: var(--_accent-fg);
+	cursor: pointer;
+	min-height: 2.75rem;
+}
+.semics-ceremony button[data-esign-decline] { background: var(--_bg); color: var(--_accent); }
+.semics-ceremony button:disabled { opacity: 0.6; cursor: not-allowed; }
+.semics-ceremony button:focus-visible, .semics-ceremony input:focus-visible, .semics-ceremony a:focus-visible, .semics-ceremony summary:focus-visible {
+	outline: 3px solid var(--_accent);
+	outline-offset: 2px;
+}
+.semics-ceremony .semics-decline { margin-top: 1.5rem; padding-top: 1rem; border-top: 1px solid var(--_border); }
+.semics-ceremony .semics-pad { margin: 0 0 1rem; }
+.semics-ceremony .semics-pad-canvas {
+	display: block;
+	width: 100%;
+	max-width: 36rem;
+	aspect-ratio: 3 / 1;
+	color: var(--_fg);
+	background: var(--_bg);
+	border: 1px solid var(--_border);
+	border-radius: var(--_radius);
+	touch-action: none;
+	cursor: crosshair;
+	user-select: none;
+}
+.semics-ceremony .semics-pad-bar { display: flex; gap: 0.5rem; margin: 0.5rem 0; }
+.semics-ceremony .semics-pad-bar button { background: var(--_bg); color: var(--_accent); }
+`;

package/src/astro/lib/call.ts

@@ -0,0 +1,205 @@
+// i18n-ignore-file: these errors are for developers (the UI shows its own text by error code, T102).
+import { getPublicPluginApiRouteHandler, type PublicPluginRuntimeLocals } from "emdash/plugin-utils";
+
+/** Plugin ID (manifest slug) of the sandboxed E-sign core. */
+export const ESIGN_PLUGIN_ID = "semics-esign";
+
+export type PublicRouteMethod = "GET" | "POST";
+
+export interface PublicRouteCall {
+	/** Route name as declared in the core, e.g. `public/events`. A leading slash is ignored. */
+	path: string;
+	/** Defaults to GET. */
+	method?: PublicRouteMethod;
+	/** JSON body for POST; query parameters for GET. */
+	body?: unknown;
+	/** Defaults to the context's plugin id, then the E-sign core. */
+	pluginId?: string;
+}
+
+/** The parts of the Astro global the helper needs; pass `Astro` itself. */
+export interface PublicRouteContext {
+	locals: PublicPluginRuntimeLocals | null | undefined;
+	url: URL;
+	/**
+	 * The visitor's request (`Astro.request`). Its user agent, client-IP headers and `cf` object are
+	 * carried onto the in-process call, so the core's `requestMeta` (audit IP and user agent, per-IP
+	 * rate limits) sees the visitor as a direct call would. Cookies, credentials and the Referer never are.
+	 */
+	request?: Request;
+	/** The core's plugin id when it is not the default slug (the integration's `pluginId`). */
+	pluginId?: string;
+	/** Injected for tests. Defaults to the global `fetch`. */
+	fetch?: typeof fetch;
+}
+
+export interface PublicRouteIssue {
+	path: string;
+	code: string;
+}
+
+export interface PublicRouteError {
+	code: string;
+	message: string;
+	/** Input validation issues, when the route reported them (`BAD_REQUEST`). */
+	issues?: PublicRouteIssue[];
+}
+
+export type PublicRouteResult<T> =
+	| { ok: true; data: T; via: "in-process" | "fetch" }
+	| { ok: false; error: PublicRouteError; via: "in-process" | "fetch" };
+
+interface Envelope {
+	success?: boolean;
+	data?: unknown;
+	error?: { code?: unknown; message?: unknown };
+}
+
+/**
+ * The only way UI code calls the core. Dispatches in-process through
+ * `getPublicPluginApiRouteHandler(Astro.locals)` (Spike S2: reaches sandboxed public routes on the
+ * workerd runner), and falls back to `fetch(Astro.url.origin + route)` when the in-process handler
+ * isn't on `locals`. Never throws: every failure comes back as `{ ok: false, error }` so components
+ * can render a defined error state.
+ */
+export async function callPublicRoute<T = unknown>(
+	ctx: PublicRouteContext,
+	call: PublicRouteCall,
+): Promise<PublicRouteResult<T>> {
+	const method = call.method ?? "GET";
+	const path = call.path.replace(/^\/+/, "");
+	const pluginId = call.pluginId ?? ctx.pluginId ?? ESIGN_PLUGIN_ID;
+	const handler = getPublicPluginApiRouteHandler(ctx.locals);
+	const via = handler ? "in-process" : "fetch";
+
+	const unsafeKey = method === "GET" ? tokenLikeKey(call.body) : undefined;
+	if (unsafeKey !== undefined) {
+		return {
+			ok: false,
+			error: {
+				code: "TOKEN_IN_QUERY",
+				message: `"${unsafeKey}" looks like a token; send it with POST, never in a URL`,
+			},
+			via,
+		};
+	}
+	const request = buildRequest(ctx.url.origin, pluginId, method, path, call.body, ctx.request);
+
+	if (handler) {
+		try {
+			return toResult<T>(await handler(pluginId, method, path, request), "in-process");
+		} catch (error) {
+			return failure(error, "in-process");
+		}
+	}
+
+	try {
+		const response = await (ctx.fetch ?? fetch)(request);
+		const envelope = (await response.json().catch(() => ({}))) as Envelope;
+		if (!response.ok && envelope.success !== false) {
+			return {
+				ok: false,
+				error: { code: `HTTP_${response.status}`, message: response.statusText || "Request failed" },
+				via: "fetch",
+			};
+		}
+		return toResult<T>(envelope, "fetch");
+	} catch (error) {
+		return failure(error, "fetch");
+	}
+}
+
+/** Tokens must never travel in URLs (BUILD-PLAN R10), so GET bodies may not carry token-like keys. */
+const TOKEN_LIKE = /^(t|.*token.*|.*receipt.*|.*secret.*|.*otp.*)$/i;
+
+function tokenLikeKey(body: unknown): string | undefined {
+	if (!body || typeof body !== "object") return undefined;
+	return Object.keys(body).find((key) => TOKEN_LIKE.test(key));
+}
+
+/**
+ * Headers never copied from the visitor's request: credentials (a public route has no use for them),
+ * the Referer (the sign page's own URL holds the token), and the framing of the page's own body.
+ */
+const NOT_FORWARDED = new Set([
+	"authorization",
+	"connection",
+	"content-length",
+	"content-type",
+	"cookie",
+	"expect",
+	"host",
+	"keep-alive",
+	"proxy-authorization",
+	"referer",
+	"transfer-encoding",
+	"upgrade",
+	"x-emdash-request",
+]);
+
+function forwardedHeaders(incoming: Request | undefined): Headers {
+	const headers = new Headers();
+	incoming?.headers.forEach((value, key) => {
+		if (!NOT_FORWARDED.has(key.toLowerCase())) headers.set(key, value);
+	});
+	return headers;
+}
+
+/** On Cloudflare the host trusts `cf-connecting-ip` only on a request that carries a `cf` object. */
+function withCf(request: Request, incoming: Request | undefined): Request {
+	const cf = (incoming as { cf?: unknown } | undefined)?.cf;
+	if (cf !== undefined && cf !== null) Object.defineProperty(request, "cf", { value: cf, enumerable: true });
+	return request;
+}
+
+function buildRequest(
+	origin: string,
+	pluginId: string,
+	method: string,
+	path: string,
+	body: unknown,
+	incoming?: Request,
+): Request {
+	const headers = forwardedHeaders(incoming);
+	const url = new URL(`/_emdash/api/plugins/${encodeURIComponent(pluginId)}/${path}`, origin);
+	if (method === "GET") {
+		if (body && typeof body === "object") {
+			for (const [key, value] of Object.entries(body)) {
+				for (const item of Array.isArray(value) ? value : [value]) {
+					if (item !== undefined && item !== null) url.searchParams.append(key, String(item));
+				}
+			}
+		}
+		return withCf(new Request(url, { method, headers }), incoming);
+	}
+	headers.set("content-type", "application/json");
+	const json = body === undefined ? undefined : JSON.stringify(body);
+	return withCf(new Request(url, { method, headers, body: json }), incoming);
+}
+
+/** A sandboxed route's own refusal (`{ ok: false, error, issues? }`), which the host wraps as a success. */
+function refusal(data: unknown): PublicRouteError | undefined {
+	if (!data || typeof data !== "object") return undefined;
+	const body = data as { ok?: unknown; error?: { code?: unknown; message?: unknown }; issues?: unknown };
+	if (body.ok !== false || typeof body.error?.code !== "string") return undefined;
+	return {
+		code: body.error.code,
+		message: typeof body.error.message === "string" ? body.error.message : "Request failed",
+		...(Array.isArray(body.issues) ? { issues: body.issues as PublicRouteIssue[] } : {}),
+	};
+}
+
+function toResult<T>(envelope: Envelope, via: "in-process" | "fetch"): PublicRouteResult<T> {
+	if (envelope.success === true) {
+		const refused = refusal(envelope.data);
+		return refused ? { ok: false, error: refused, via } : { ok: true, data: envelope.data as T, via };
+	}
+	const code = typeof envelope.error?.code === "string" ? envelope.error.code : "ROUTE_CALL_FAILED";
+	const message = typeof envelope.error?.message === "string" ? envelope.error.message : "Request failed";
+	return { ok: false, error: { code, message }, via };
+}
+
+function failure<T>(error: unknown, via: "in-process" | "fetch"): PublicRouteResult<T> {
+	const message = error instanceof Error ? error.message : "Request failed";
+	return { ok: false, error: { code: "ROUTE_CALL_FAILED", message }, via };
+}

package/src/astro/lib/csp.ts

@@ -0,0 +1,57 @@
+// i18n-ignore-file: Content-Security-Policy directives, no text for people (T102).
+import { CEREMONY_CSS, CEREMONY_SCRIPT, PAD_SCRIPT, VERIFY_CSS, VERIFY_SCRIPT } from "./assets.ts";
+
+/**
+ * The signing page's Content-Security-Policy (SU-NFR-02): nothing loads or runs but the package's
+ * own inlined scripts (ceremony, signature pad) and stylesheet, each allowed by its SHA-256. Forms post only to the site,
+ * scripts fetch only from it (the `public/session` poll), and the page cannot be framed.
+ */
+
+/** The CSP source expression for inline text: `'sha256-<base64 of SHA-256(UTF-8 text)>'`. */
+export async function cspSource(text: string): Promise<string> {
+	const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text)));
+	let binary = "";
+	for (const byte of digest) binary += String.fromCharCode(byte);
+	return `'sha256-${btoa(binary)}'`;
+}
+
+let cached: Promise<string> | undefined;
+
+/** The header value for any page that renders <SigningCeremony> and nothing else inline. */
+export function ceremonyCsp(): Promise<string> {
+	cached ??= Promise.all([cspSource(CEREMONY_SCRIPT), cspSource(PAD_SCRIPT), cspSource(CEREMONY_CSS)]).then(
+		([script, pad, style]) =>
+			[
+				"default-src 'none'",
+				`script-src ${script} ${pad}`,
+				`style-src ${style}`,
+				"img-src 'self' data:",
+				"connect-src 'self'",
+				"form-action 'self'",
+				"base-uri 'none'",
+				"frame-ancestors 'none'",
+			].join("; "),
+	);
+	return cached;
+}
+
+let cachedVerify: Promise<string> | undefined;
+
+/**
+ * The header value for the `/verify` page: only its own hashed script and style. The script has no
+ * network code, so there is no `connect-src` (it falls back to `default-src 'none'`); the form posts
+ * to the site, and the page cannot be framed.
+ */
+export function verifyCsp(): Promise<string> {
+	cachedVerify ??= Promise.all([cspSource(VERIFY_SCRIPT), cspSource(VERIFY_CSS)]).then(([script, style]) =>
+		[
+			"default-src 'none'",
+			`script-src ${script}`,
+			`style-src ${style}`,
+			"form-action 'self'",
+			"base-uri 'none'",
+			"frame-ancestors 'none'",
+		].join("; "),
+	);
+	return cachedVerify;
+}

package/src/astro/lib/csrf.ts

@@ -0,0 +1,33 @@
+/**
+ * The UI pages' own CSRF check (T034). EmDash 1.2 turns Astro's `security.checkOrigin` off and its
+ * own check covers only `/_emdash/api`, so `/sign/[token]` (sign and decline) and `/verify` refuse a
+ * form post another site made. The browser says so in `Sec-Fetch-Site`; older browsers send an
+ * `Origin`, compared with the page's origin or, because Astro builds `url` from `localhost` unless
+ * the host is in `security.allowedDomains`, with the `Host` the browser sent (another site cannot set
+ * it). Safe methods and clients that send neither header (not browsers) pass. Written locally: the
+ * UI never imports `@semics-tech/shared` (R35) or Events.
+ */
+export function isCrossSiteRequest(request: Request, url: URL): boolean {
+	if (request.method === "GET" || request.method === "HEAD" || request.method === "OPTIONS") return false;
+	const site = request.headers.get("sec-fetch-site");
+	if (site) return site !== "same-origin" && site !== "none";
+	const origin = request.headers.get("origin");
+	if (origin === null || origin === url.origin) return false;
+	try {
+		return new URL(origin).host !== request.headers.get("host");
+	} catch {
+		return true;
+	}
+}
+
+/** The answer to a refused cross-site post (another site's form, not a page a visitor reads). */
+export const crossSiteResponse = () =>
+	// i18n-ignore
+	new Response("Cross-site form submissions are not allowed.", {
+		status: 403,
+		headers: {
+			"content-type": "text/plain; charset=utf-8",
+			"cache-control": "no-store",
+			"referrer-policy": "no-referrer",
+		},
+	});