@glw907/cairn-cms 0.40.0 → 0.50.0

package/src/lib/doctor/checks-github.ts

@@ -0,0 +1,63 @@
+// The doctor's GitHub App check: the full reachability chain (the key parses and signs, the
+// installation token mints, the repository answers a read), built from the engine's own
+// credential and signing path so the doctor proves the exact code the save action runs. The
+// signing chain is Web Crypto plus atob/btoa, all Node 20+ globals, so it runs in a CLI
+// unchanged. One wrinkle the tests mirror: installationToken fetches through the global
+// fetch, so only the repo read routes through ctx.fetch.
+import { appCredentials } from '../github/credentials.js';
+import { installationToken, signingSelfTest } from '../github/signing.js';
+import { fail, pass, skip } from './types.js';
+import type { CheckResult, DoctorCheck, DoctorContext } from './types.js';
+
+const API = 'https://api.github.com';
+
+export const githubApp: DoctorCheck = {
+	id: 'github.app',
+	conditionId: 'github.app-unreachable',
+	title: 'GitHub App',
+	async run(ctx: DoctorContext): Promise<CheckResult> {
+		if (!ctx.github) {
+			return skip(
+				'set GITHUB_APP_ID, GITHUB_APP_INSTALLATION_ID, and GITHUB_APP_PRIVATE_KEY_B64 to run this check'
+			);
+		}
+		if (!ctx.repo) {
+			return skip('pass --repo or set GITHUB_REPO to run this check');
+		}
+		const creds = appCredentials(
+			{ appId: ctx.github.appId, installationId: ctx.github.installationId },
+			{ GITHUB_APP_PRIVATE_KEY_B64: ctx.github.privateKeyB64 }
+		);
+		// Stage 1: the key parse and sign, through the deploy-time self-test. Its detail is a
+		// fixed classifier, so a bad key can never echo key bytes into the report.
+		const signed = await signingSelfTest(creds.appId, creds.privateKeyB64);
+		if (!signed.ok) {
+			return fail(`the App key failed to parse or sign: ${signed.detail}`);
+		}
+		// Stage 2: the token mint, through the uncached primitive. A one-shot CLI gains nothing
+		// from the Worker-lifecycle cache, and the probe should reach GitHub for real.
+		let token: string;
+		try {
+			token = await installationToken(creds);
+		} catch (err) {
+			return fail(`App authentication failed: ${String(err)}`);
+		}
+		// Stage 3: the repo read, with the engine's standard GitHub headers.
+		try {
+			const res = await ctx.fetch(`${API}/repos/${ctx.repo}`, {
+				headers: {
+					Accept: 'application/vnd.github+json',
+					Authorization: `Bearer ${token}`,
+					'User-Agent': 'cairn-cms',
+					'X-GitHub-Api-Version': '2022-11-28',
+				},
+			});
+			if (!res.ok) {
+				return fail(`repo ${ctx.repo} returned ${res.status}`);
+			}
+			return pass(`the App reads ${ctx.repo}`);
+		} catch (err) {
+			return fail(String(err));
+		}
+	},
+};

package/src/lib/doctor/checks-local.ts

@@ -0,0 +1,119 @@
+// The doctor's local-config checks: the wrangler bindings, the observability sink, the
+// svelte.config CSRF handoff, and the site-config validation. Every read goes through the
+// injected ctx.readFile, so the tests pass fixtures and the bin passes node:fs.
+import { fail, pass, skip } from './types.js';
+import type { CheckResult, DoctorCheck, DoctorContext } from './types.js';
+import { readWranglerConfig } from './wrangler-config.js';
+import { parseSiteConfig, urlPolicyFrom } from '../nav/site-config.js';
+import { normalizeConcepts } from '../content/concepts.js';
+import { defineFields } from '../content/schema.js';
+import type { ConceptConfig } from '../content/types.js';
+
+const NO_WRANGLER: CheckResult = skip('no wrangler.jsonc or wrangler.toml found');
+
+export const configBindings: DoctorCheck = {
+	id: 'config.bindings',
+	conditionId: 'config.bindings-missing',
+	title: 'Wrangler bindings',
+	async run(ctx: DoctorContext): Promise<CheckResult> {
+		const facts = await readWranglerConfig(ctx.readFile);
+		if (facts === null) return NO_WRANGLER;
+		const missing: string[] = [];
+		if (!facts.hasEmailBinding) missing.push('EMAIL (send_email)');
+		if (!facts.hasAuthDb) missing.push('AUTH_DB (d1_databases)');
+		if (missing.length) return fail(`missing ${missing.join(' and ')}`);
+		return pass('EMAIL and AUTH_DB are declared');
+	},
+};
+
+export const configObservability: DoctorCheck = {
+	id: 'config.observability',
+	conditionId: 'config.observability-off',
+	title: 'Workers Logs sink',
+	async run(ctx: DoctorContext): Promise<CheckResult> {
+		const facts = await readWranglerConfig(ctx.readFile);
+		if (facts === null) return NO_WRANGLER;
+		if (!facts.observabilityEnabled) {
+			return fail('observability.enabled is not true');
+		}
+		return pass('observability.enabled is true');
+	},
+};
+
+// A line whose trimmed start is a comment marker cannot disable anything, so a commented-out
+// checkOrigin: false never green-lights the handoff.
+function hasUncommentedDisable(text: string): boolean {
+	return text.split('\n').some((line) => {
+		const trimmed = line.trimStart();
+		if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*')) {
+			return false;
+		}
+		return /checkOrigin\s*:\s*false/.test(trimmed);
+	});
+}
+
+// The guard-wiring heuristic. The tutorial's hooks file imports createAuthGuard from
+// @glw907/cairn-cms/sveltekit and hands it the exported handle, which the first clause matches
+// directly; a site that wraps the guard in its own module still mentions cairn beside a handle.
+function wiresCairnGuard(text: string): boolean {
+	if (text.includes('@glw907/cairn-cms')) return true;
+	return /cairn/i.test(text) && /handle/.test(text);
+}
+
+export const configCsrfDisable: DoctorCheck = {
+	id: 'config.csrf-disable',
+	conditionId: 'config.csrf-disable-missing',
+	title: 'Framework CSRF handoff',
+	async run(ctx: DoctorContext): Promise<CheckResult> {
+		const text = await ctx.readFile('svelte.config.js');
+		if (text === null) return skip('svelte.config.js not found');
+		if (!hasUncommentedDisable(text)) {
+			return fail('no checkOrigin: false found (heuristic text read)');
+		}
+		// The disable alone proves nothing: with the framework check off and no cairn guard in
+		// the hooks, the admin form POSTs have no CSRF protection at all. The pair is the check.
+		const hooks =
+			(await ctx.readFile('src/hooks.server.ts')) ?? (await ctx.readFile('src/hooks.server.js'));
+		if (hooks === null || !wiresCairnGuard(hooks)) {
+			return fail(
+				'checkOrigin is off but no cairn guard found in src/hooks.server.ts; the site may have no CSRF protection'
+			);
+		}
+		return pass(
+			'checkOrigin: false found and the hooks file wires the cairn guard (heuristic text read)'
+		);
+	},
+};
+
+// Where sites keep site.config.yaml. The adapter's configPath is TypeScript the CLI cannot
+// evaluate, so the check probes the conventional spots instead (the repo root and the two
+// src locations the production sites use).
+const SITE_CONFIG_PATHS = ['site.config.yaml', 'src/lib/site.config.yaml', 'src/site.config.yaml'];
+
+export const configSiteConfig: DoctorCheck = {
+	id: 'config.site-config',
+	conditionId: 'config.site-config-invalid',
+	title: 'Site config',
+	async run(ctx: DoctorContext): Promise<CheckResult> {
+		let text: string | null = null;
+		for (const path of SITE_CONFIG_PATHS) {
+			text = await ctx.readFile(path);
+			if (text !== null) break;
+		}
+		if (text === null) return skip(`no site.config.yaml found (looked in ${SITE_CONFIG_PATHS.join(', ')})`);
+		try {
+			const policy = urlPolicyFrom(parseSiteConfig(text));
+			// Run the engine's own URL-policy validation by declaring a synthetic empty concept
+			// per policy key. Routing is concept-fixed in the engine (CONCEPT_ROUTING, never the
+			// adapter), so the dated rules apply faithfully here. What a CLI cannot check without
+			// evaluating the adapter is whether each policy key names a concept the site declares.
+			const synthetic = Object.fromEntries(
+				Object.keys(policy).map((id): [string, ConceptConfig] => [id, { dir: '', schema: defineFields([]) }])
+			);
+			normalizeConcepts(synthetic, policy);
+			return pass('parsed and URL policy validated (the adapter concept set is not checkable from the CLI)');
+		} catch (err) {
+			return fail(err instanceof Error ? err.message : String(err));
+		}
+	},
+};

package/src/lib/doctor/cloudflare-api.ts

@@ -0,0 +1,33 @@
+// Shared plumbing for the doctor's Cloudflare API probes: the API base, the bearer-token
+// request helpers, and the skip results for the credentials the checks share. Every request
+// goes through ctx.fetch with the operator's CLOUDFLARE_API_TOKEN, so the tests script the
+// API and the bin passes global fetch.
+import { skip } from './types.js';
+import type { CheckResult, DoctorContext } from './types.js';
+
+export const CF_API = 'https://api.cloudflare.com/client/v4';
+
+export const NO_TOKEN: CheckResult = skip('set CLOUDFLARE_API_TOKEN to run this check');
+
+export const NO_FROM: CheckResult = skip('pass --from or set CAIRN_FROM to run this check');
+
+export const NO_ACCOUNT: CheckResult = skip(
+	'set CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID to run this check'
+);
+
+export function cfGet(ctx: DoctorContext, path: string): Promise<Response> {
+	return ctx.fetch(`${CF_API}${path}`, {
+		headers: { authorization: `Bearer ${ctx.cfToken}` },
+	});
+}
+
+export function cfPost(ctx: DoctorContext, path: string, body: unknown): Promise<Response> {
+	return ctx.fetch(`${CF_API}${path}`, {
+		method: 'POST',
+		headers: {
+			authorization: `Bearer ${ctx.cfToken}`,
+			'content-type': 'application/json',
+		},
+		body: JSON.stringify(body),
+	});
+}

package/src/lib/doctor/index.ts

@@ -0,0 +1,93 @@
+// cairn-doctor's assembly: the flag parser, the context builder, and the default check
+// registry, all pure functions so the bin shell stays a thin wrapper like cairn-manifest's.
+// The module is internal; no public subpath exports it, and the bin is its only consumer.
+import type { DoctorCheck, DoctorContext } from './types.js';
+import {
+	configBindings,
+	configObservability,
+	configCsrfDisable,
+	configSiteConfig,
+} from './checks-local.js';
+import { emailSenderOnboarded, edgeHttpsForced, edgeHsts, authStore } from './checks-cloudflare.js';
+import { githubApp } from './checks-github.js';
+
+export { runDoctor } from './run.js';
+export { formatReport } from './report.js';
+
+const USAGE = 'Usage: cairn-doctor [--from <address>] [--repo <owner/name>] [--send-test <address>]';
+
+export interface DoctorArgs {
+	from?: string;
+	repo?: string;
+	sendTest?: string;
+}
+
+const FLAGS: Record<string, keyof DoctorArgs> = {
+	'--from': 'from',
+	'--repo': 'repo',
+	'--send-test': 'sendTest',
+};
+
+/** Parse the bin's argv (long flags only). Throws with a usage line on anything unexpected. */
+export function parseArgs(argv: string[]): DoctorArgs {
+	const args: DoctorArgs = {};
+	for (let i = 0; i < argv.length; i += 2) {
+		const flag = argv[i];
+		const key = FLAGS[flag];
+		if (!key) throw new Error(`unknown argument ${flag}\n${USAGE}`);
+		const value = argv[i + 1];
+		if (value === undefined || value.startsWith('--')) {
+			throw new Error(`${flag} needs a value\n${USAGE}`);
+		}
+		args[key] = value;
+	}
+	return args;
+}
+
+/**
+ * Build the doctor's context from the environment and the parsed flags. A flag beats its env
+ * variable, and github assembles only when the whole credential trio is present, so the GitHub
+ * check skips with one remediation line instead of failing on a partial setup. fetch and
+ * readFile stay with the bin, which injects the real ones.
+ */
+export function contextFromEnv(
+	env: Record<string, string | undefined>,
+	args: DoctorArgs,
+	cwd: string
+): Omit<DoctorContext, 'fetch' | 'readFile'> {
+	const { GITHUB_APP_ID, GITHUB_APP_INSTALLATION_ID, GITHUB_APP_PRIVATE_KEY_B64 } = env;
+	return {
+		cwd,
+		from: args.from ?? env.CAIRN_FROM,
+		repo: args.repo ?? env.GITHUB_REPO,
+		cfToken: env.CLOUDFLARE_API_TOKEN,
+		cfAccountId: env.CLOUDFLARE_ACCOUNT_ID,
+		github:
+			GITHUB_APP_ID && GITHUB_APP_INSTALLATION_ID && GITHUB_APP_PRIVATE_KEY_B64
+				? {
+						appId: GITHUB_APP_ID,
+						installationId: GITHUB_APP_INSTALLATION_ID,
+						privateKeyB64: GITHUB_APP_PRIVATE_KEY_B64,
+					}
+				: undefined,
+	};
+}
+
+/**
+ * The default registry: the four local-config checks, the four Cloudflare checks, and the
+ * GitHub App chain. The live send is opt-in (--send-test) and never sits here; the bin appends
+ * it. A fresh array per call, so that append mutates nothing shared.
+ */
+export function defaultChecks(): DoctorCheck[] {
+	return [
+		configBindings,
+		configObservability,
+		configCsrfDisable,
+		configSiteConfig,
+		emailSenderOnboarded,
+		edgeHttpsForced,
+		edgeHsts,
+		authStore,
+		githubApp,
+	];
+}

package/src/lib/doctor/report.ts

@@ -0,0 +1,30 @@
+// The doctor's report: one aligned line per check, then a why/remediation block per failure
+// resolved from the condition registry, then a count summary. Plain text, no ANSI color, so the
+// output reads the same in a terminal and a CI log. An unknown conditionId is a programming
+// error; condition() throws and the report does not paper over it.
+import { condition } from '../diagnostics/index.js';
+import type { CheckResult, DoctorCheck } from './types.js';
+
+const TAG: Record<CheckResult['status'], string> = {
+	pass: 'PASS',
+	fail: 'FAIL',
+	skip: 'SKIP',
+};
+
+export function formatReport(results: { check: DoctorCheck; result: CheckResult }[]): string {
+	const lines = results.map(
+		({ check, result }) => `${TAG[result.status]}  ${check.title}: ${result.detail}`
+	);
+
+	const failures = results.filter(({ result }) => result.status === 'fail');
+	for (const { check } of failures) {
+		const entry = condition(check.conditionId);
+		lines.push('', `${check.title} failed.`, `  Why: ${entry.why}`, `  Fix: ${entry.remediation}`);
+	}
+
+	const count = (status: CheckResult['status']) =>
+		results.filter(({ result }) => result.status === status).length;
+	lines.push('', `${count('pass')} passed, ${count('fail')} failed, ${count('skip')} skipped`);
+
+	return lines.join('\n');
+}

package/src/lib/doctor/run.ts

@@ -0,0 +1,23 @@
+// The doctor's runner: every check executes, every result lands in the table. A throwing check
+// records a fail and the run continues, so one broken probe never hides the rest of the picture.
+import { fail } from './types.js';
+import type { CheckResult, DoctorCheck, DoctorContext } from './types.js';
+
+export async function runDoctor(
+	checks: DoctorCheck[],
+	ctx: DoctorContext
+): Promise<{ results: { check: DoctorCheck; result: CheckResult }[]; failed: number }> {
+	const results: { check: DoctorCheck; result: CheckResult }[] = [];
+	let failed = 0;
+	for (const check of checks) {
+		let result: CheckResult;
+		try {
+			result = await check.run(ctx);
+		} catch (err) {
+			result = fail(String(err));
+		}
+		if (result.status === 'fail') failed += 1;
+		results.push({ check, result });
+	}
+	return { results, failed };
+}

package/src/lib/doctor/types.ts

@@ -0,0 +1,52 @@
+// The doctor's check model (diagnostics spec, Arm B). Each check is isolated: no check reads
+// another's result. The conditionId ties the check to the registry entry whose why/remediation
+// the report prints, keeping the doctor, the runtime errors, and the checklist on one identity.
+export type CheckStatus = 'pass' | 'fail' | 'skip';
+
+export interface CheckResult {
+	status: CheckStatus;
+	/** One line of evidence ("sending subdomain enabled", "wrangler.jsonc not found"). */
+	detail: string;
+}
+
+/** Result constructors, so a check body reads one outcome per line instead of object literals. */
+export function pass(detail: string): CheckResult {
+	return { status: 'pass', detail };
+}
+
+export function fail(detail: string): CheckResult {
+	return { status: 'fail', detail };
+}
+
+export function skip(detail: string): CheckResult {
+	return { status: 'skip', detail };
+}
+
+export interface DoctorCheck {
+	/** Stable id, e.g. 'email.sender-onboarded'. */
+	id: string;
+	/** The registry condition this check probes; the report prints its remediation on failure. */
+	conditionId: string;
+	title: string;
+	run: (ctx: DoctorContext) => Promise<CheckResult>;
+}
+
+/** Everything a check may read, resolved once by the bin. Absent fields make checks skip. */
+export interface DoctorContext {
+	/** The site directory the doctor runs in. */
+	cwd: string;
+	/** The from-address (--from / CAIRN_FROM). */
+	from?: string;
+	/** owner/name (--repo / GITHUB_REPO). */
+	repo?: string;
+	/** CLOUDFLARE_API_TOKEN. */
+	cfToken?: string;
+	/** CLOUDFLARE_ACCOUNT_ID. */
+	cfAccountId?: string;
+	/** GITHUB_APP_ID / GITHUB_APP_INSTALLATION_ID / GITHUB_APP_PRIVATE_KEY_B64. */
+	github?: { appId: string; installationId: string; privateKeyB64: string };
+	/** Injected fetch for tests; defaults to global fetch. */
+	fetch: typeof fetch;
+	/** Read a file under cwd, or null when absent. Injected for tests. */
+	readFile: (relPath: string) => Promise<string | null>;
+}

package/src/lib/doctor/wrangler-config.ts

@@ -0,0 +1,142 @@
+// A tolerant reader for the few wrangler-config facts the local checks need. It reads
+// wrangler.jsonc or wrangler.toml through the injected readFile (jsonc wins when both exist)
+// and returns null when neither file is present, which the checks report as a skip.
+import type { DoctorContext } from './types.js';
+
+export interface WranglerFacts {
+	/** A send_email binding named EMAIL is declared. */
+	hasEmailBinding: boolean;
+	/** A d1_databases binding named AUTH_DB is declared. */
+	hasAuthDb: boolean;
+	/** The AUTH_DB database_id, when declared; the D1 check queries it. */
+	authDbId?: string;
+	/** observability.enabled is true. */
+	observabilityEnabled: boolean;
+}
+
+export async function readWranglerConfig(
+	readFile: DoctorContext['readFile']
+): Promise<WranglerFacts | null> {
+	const jsonc = await readFile('wrangler.jsonc');
+	if (jsonc !== null) return factsFromJsonc(jsonc);
+	const toml = await readFile('wrangler.toml');
+	if (toml !== null) return factsFromToml(toml);
+	return null;
+}
+
+// Strip // and /* */ comments outside string literals, character by character, so a URL
+// inside a string survives. Trailing commas go by regex afterward; a string containing
+// ",}" would be mangled, an accepted gap in a tolerant reader.
+function stripJsonc(text: string): string {
+	let out = '';
+	let inString = false;
+	let i = 0;
+	while (i < text.length) {
+		const ch = text[i];
+		if (inString) {
+			out += ch;
+			if (ch === '\\') {
+				out += text[i + 1] ?? '';
+				i += 2;
+				continue;
+			}
+			if (ch === '"') inString = false;
+			i += 1;
+			continue;
+		}
+		if (ch === '"') {
+			inString = true;
+			out += ch;
+			i += 1;
+			continue;
+		}
+		if (ch === '/' && text[i + 1] === '/') {
+			const end = text.indexOf('\n', i);
+			i = end === -1 ? text.length : end;
+			continue;
+		}
+		if (ch === '/' && text[i + 1] === '*') {
+			const end = text.indexOf('*/', i + 2);
+			i = end === -1 ? text.length : end + 2;
+			continue;
+		}
+		out += ch;
+		i += 1;
+	}
+	return out.replace(/,(\s*[}\]])/g, '$1');
+}
+
+function factsFromJsonc(text: string): WranglerFacts {
+	let config: Record<string, unknown>;
+	try {
+		config = JSON.parse(stripJsonc(text)) as Record<string, unknown>;
+	} catch {
+		// V8's SyntaxError embeds a source snippet, which would land verbatim in the report;
+		// a file that exists but does not parse is a fail with a clean message instead.
+		throw new Error('wrangler.jsonc did not parse');
+	}
+	const sendEmail = Array.isArray(config.send_email) ? config.send_email : [];
+	const hasEmailBinding = sendEmail.some(
+		(entry) => typeof entry === 'object' && entry !== null && (entry as { name?: unknown }).name === 'EMAIL'
+	);
+	const databases = Array.isArray(config.d1_databases) ? config.d1_databases : [];
+	const authDb = databases.find(
+		(entry): entry is { binding: string; database_id?: unknown } =>
+			typeof entry === 'object' && entry !== null && (entry as { binding?: unknown }).binding === 'AUTH_DB'
+	);
+	const observability = config.observability as { enabled?: unknown } | undefined;
+	const facts: WranglerFacts = {
+		hasEmailBinding,
+		hasAuthDb: authDb !== undefined,
+		observabilityEnabled: observability?.enabled === true,
+	};
+	if (typeof authDb?.database_id === 'string') facts.authDbId = authDb.database_id;
+	return facts;
+}
+
+// The toml read is deliberately shallow: line-anchored matching for the three facts, not a
+// TOML parser. The remediation tells the operator exactly what to add, so full fidelity
+// buys nothing here. A table header opens a section; the relevant key lines are matched
+// within it and the d1 table flushes on the next header.
+function factsFromToml(text: string): WranglerFacts {
+	const facts: WranglerFacts = {
+		hasEmailBinding: false,
+		hasAuthDb: false,
+		observabilityEnabled: false,
+	};
+	let section = '';
+	let d1Binding: string | undefined;
+	let d1Id: string | undefined;
+
+	const flushD1 = () => {
+		if (d1Binding === 'AUTH_DB') {
+			facts.hasAuthDb = true;
+			if (d1Id !== undefined) facts.authDbId = d1Id;
+		}
+		d1Binding = undefined;
+		d1Id = undefined;
+	};
+
+	for (const line of text.split('\n')) {
+		const header = line.match(/^\s*(\[\[?[\w.]+\]?\])\s*(?:#.*)?$/);
+		if (header) {
+			flushD1();
+			section = header[1];
+			continue;
+		}
+		const kv = line.match(/^\s*(\w+)\s*=\s*(.+?)\s*$/);
+		if (!kv) continue;
+		const [, key, value] = kv;
+		const str = value.match(/^["'](.*)["']/)?.[1];
+		if (section === '[[send_email]]' && key === 'name' && str === 'EMAIL') {
+			facts.hasEmailBinding = true;
+		} else if (section === '[[d1_databases]]') {
+			if (key === 'binding') d1Binding = str;
+			if (key === 'database_id') d1Id = str;
+		} else if (section === '[observability]' && key === 'enabled' && value.startsWith('true')) {
+			facts.observabilityEnabled = true;
+		}
+	}
+	flushD1();
+	return facts;
+}

package/src/lib/email.ts

@@ -3,6 +3,7 @@
 // (Cloudflare Email Sending, arbitrary recipients).
 import type { AuthEnv } from './auth/types.js';
 import { CairnError } from './diagnostics/index.js';
+import { escapeHtml } from './escape.js';
 
 export type { AuthEnv };
 
@@ -27,16 +28,6 @@ export interface AuthBranding {
  *  the message body or the magic link in what it throws. */
 export type SendMagicLink = (env: AuthEnv, message: MagicLinkMessage) => Promise<void>;
 
-/** Escape the five HTML-significant characters. */
-function escapeHtml(value: string): string {
-  return value
-    .replaceAll('&', '&amp;')
-    .replaceAll('<', '&lt;')
-    .replaceAll('>', '&gt;')
-    .replaceAll('"', '&quot;')
-    .replaceAll("'", '&#39;');
-}
-
 /** Build the confirmation email. The link is the only action; the copy stays plain. */
 export function buildMagicLinkMessage(input: {
   to: string;
@@ -54,7 +45,9 @@ export function buildMagicLinkMessage(input: {
 
 /** The production send: Cloudflare Email Sending through the EMAIL binding. */
 export const cloudflareSend: SendMagicLink = async (env, message) => {
-  if (!env.EMAIL) throw new Error('EMAIL binding is not configured');
+  if (!env.EMAIL) {
+    throw new CairnError('config.bindings-missing', { message: 'EMAIL binding is not configured' });
+  }
   await env.EMAIL.send(message);
 };
 

package/src/lib/env.ts

@@ -1,4 +1,5 @@
 import type { D1Database } from '@cloudflare/workers-types';
+import { CairnError } from './diagnostics/index.js';
 
 /**
  * Returns the site's public origin from configuration.
@@ -35,11 +36,11 @@ export function requireOrigin(env: { PUBLIC_ORIGIN?: string }): string {
  * The handlers read D1 off `event.platform.env`; without this a misconfigured binding
  * surfaces as a raw `TypeError` deep in a store call. This gives the failure a name.
  *
- * @throws Error when `AUTH_DB` is missing.
+ * @throws CairnError (`config.bindings-missing`) when `AUTH_DB` is missing.
  */
 export function requireDb(env: { AUTH_DB?: D1Database }): D1Database {
   if (!env.AUTH_DB) {
-    throw new Error('AUTH_DB binding is not configured');
+    throw new CairnError('config.bindings-missing', { message: 'AUTH_DB binding is not configured' });
   }
   return env.AUTH_DB;
 }

package/src/lib/escape.ts

@@ -0,0 +1,12 @@
+// cairn-cms: the one HTML text escape. A leaf module with no imports, so the email builder and
+// the edge-served admin pages share it without either arm reaching into the other.
+
+/** Escape the five HTML-significant characters for text and quoted attribute values. */
+export function escapeHtml(value: string): string {
+  return value
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+}

package/src/lib/github/credentials.ts

@@ -2,6 +2,7 @@
 // App signer's input. One tested place owns the join and the missing-secret failure, so the
 // save action (Plan 05) stays thin and a misconfigured Worker fails by name, not with a deep
 // TypeError. Mirrors requireDb/requireOrigin in env.ts.
+import { CairnError } from '../diagnostics/index.js';
 import type { BackendConfig } from '../content/types.js';
 import type { AppCredentials } from './types.js';
 
@@ -12,7 +13,8 @@ export interface GithubKeyEnv {
 
 /**
  * Assemble the `AppCredentials` the signer needs from the adapter's `backend` (app id,
- * installation) and the Worker's private-key secret. Throws when the secret is unset.
+ * installation) and the Worker's private-key secret. Throws a CairnError naming
+ * `github.app-unreachable` when the secret is unset, since the App cannot authenticate without it.
  */
 export function appCredentials(
   backend: Pick<BackendConfig, 'appId' | 'installationId'>,
@@ -20,7 +22,9 @@ export function appCredentials(
 ): AppCredentials {
   const privateKeyB64 = env.GITHUB_APP_PRIVATE_KEY_B64;
   if (!privateKeyB64) {
-    throw new Error('GITHUB_APP_PRIVATE_KEY_B64 is not configured');
+    throw new CairnError('github.app-unreachable', {
+      message: 'GITHUB_APP_PRIVATE_KEY_B64 is not configured',
+    });
   }
   return { appId: backend.appId, installationId: backend.installationId, privateKeyB64 };
 }