@glw907/cairn-cms 0.41.0 → 0.51.0

package/src/lib/doctor/check-probe.ts

@@ -0,0 +1,138 @@
+// The doctor's opt-in live probe (--probe): one GET and one POST against a deployed admin,
+// asserting the envelope a working sign-in presents. Zero side effects by construction: the
+// POST submits a random non-editor address, and the engine's non-leak design answers a
+// non-editor with the identical sent body while sending no email and minting no token, so the
+// probe leaves nothing behind on the site. A factory rather than a check constant, the same
+// shape as the live send: the check exists only when the bin receives --probe.
+import { fail, pass, skip } from './types.js';
+import type { CheckResult, DoctorCheck, DoctorContext } from './types.js';
+import { csrfCookieName } from '../auth/crypto.js';
+import { readWranglerConfig } from './wrangler-config.js';
+
+const NO_URL: CheckResult = skip(
+	'pass --probe <url>, set PUBLIC_ORIGIN in the wrangler vars, or set PUBLIC_ORIGIN in the environment'
+);
+
+/** Build the live-probe check. A missing url falls back to the PUBLIC_ORIGIN input at run time. */
+export function liveProbeCheck(url?: string): DoctorCheck {
+	return {
+		id: 'admin.login-probe',
+		conditionId: 'admin.login-probe-failed',
+		title: 'Live admin login probe',
+		async run(ctx: DoctorContext): Promise<CheckResult> {
+			// The wrangler vars hold the value the deployed Worker reads, so they beat the local
+			// environment, the same precedence the public-origin check applies.
+			const base =
+				url ?? (await readWranglerConfig(ctx.readFile))?.publicOrigin ?? ctx.publicOrigin;
+			if (base === undefined) return NO_URL;
+			let origin: URL;
+			try {
+				origin = new URL(base);
+			} catch {
+				return fail(`probe URL does not parse: ${base}`);
+			}
+			try {
+				return await probe(ctx, origin);
+			} catch (err) {
+				return fail(String(err));
+			}
+		},
+	};
+}
+
+/** GET /admin/login and assert the sign-in envelope, then hand the harvested token pair on. */
+async function probe(ctx: DoctorContext, origin: URL): Promise<CheckResult> {
+	const res = await ctx.fetch(String(new URL('/admin/login', origin)));
+	if (res.status !== 200) {
+		return fail(`GET /admin/login returned ${res.status}, expected 200`);
+	}
+	const cookieName = csrfCookieName(origin.protocol === 'https:');
+	const cookieValue = setCookieValue(res.headers.getSetCookie(), cookieName);
+	if (cookieValue === undefined) {
+		return fail(`GET /admin/login set no ${cookieName} cookie`);
+	}
+	const html = await res.text();
+	const field = csrfFieldValue(html);
+	if (field === undefined) {
+		return fail('the login page carries no name="csrf" hidden field with a value');
+	}
+	if (!/<form[^>]*action="[^"]*\?\/request"/.test(html)) {
+		return fail('the login page carries no form posting the ?/request action');
+	}
+	return postRequestAction(ctx, origin, `${cookieName}=${cookieValue}`, field);
+}
+
+/** The named cookie's value from the Set-Cookie lines, or undefined when no line names it. */
+function setCookieValue(lines: string[], name: string): string | undefined {
+	for (const line of lines) {
+		const eq = line.indexOf('=');
+		if (eq === -1 || line.slice(0, eq).trim() !== name) continue;
+		const rest = line.slice(eq + 1);
+		const semi = rest.indexOf(';');
+		return semi === -1 ? rest : rest.slice(0, semi);
+	}
+	return undefined;
+}
+
+/** The csrf hidden field's value, tolerant of attribute order, or undefined when absent or empty. */
+function csrfFieldValue(html: string): string | undefined {
+	const input = (html.match(/<input[^>]*>/g) ?? []).find((tag) => /name="csrf"/.test(tag));
+	if (input === undefined) return undefined;
+	return /value="([^"]+)"/.exec(input)?.[1];
+}
+
+/**
+ * POST the request action and read its serialized result. The address is random and non-editor
+ * at the reserved example.invalid domain, so even a delivery bug could send nothing anywhere,
+ * and the engine's non-leak design makes the response indistinguishable from a real send.
+ */
+async function postRequestAction(
+	ctx: DoctorContext,
+	origin: URL,
+	cookie: string,
+	csrf: string
+): Promise<CheckResult> {
+	const email = `cairn-doctor-probe-${Math.random().toString(36).slice(2, 10)}@example.invalid`;
+	const res = await ctx.fetch(String(new URL('/admin/login?/request', origin)), {
+		method: 'POST',
+		headers: {
+			'content-type': 'application/x-www-form-urlencoded',
+			cookie,
+		},
+		body: new URLSearchParams({ email, csrf }).toString(),
+	});
+	if (res.status !== 200) {
+		return fail(`POST ?/request returned ${res.status}, expected 200`);
+	}
+	// A no-Accept action POST answers with SvelteKit's serialized form-action JSON, shaped
+	// {"type":"success","status":200,"data":"<devalue array string>"}. The data field is a
+	// devalue encoding the probe reads by containment for the status literals, tolerant of
+	// encoding details it does not own, instead of pulling in a devalue parser.
+	let envelope: { type?: unknown; data?: unknown };
+	try {
+		envelope = (await res.json()) as { type?: unknown; data?: unknown };
+	} catch {
+		return fail('POST ?/request did not answer with the serialized action JSON');
+	}
+	if (envelope.type !== 'success') {
+		return fail(`POST ?/request answered type ${String(envelope.type)}, expected success`);
+	}
+	const data = typeof envelope.data === 'string' ? envelope.data : '';
+	if (data.includes('"send_error"')) {
+		return fail(
+			'the request action answered send_error; the magic-link send path is failing (see the email checks and the auth.link.send_failed log records)'
+		);
+	}
+	// Every payload carries the "sent" field name, so the distinct status spellings go first.
+	if (data.includes('"throttled"')) {
+		return pass(
+			`sign-in envelope verified at ${origin.origin}; the request action answered throttled (a real cooldown window is active), which still proves the path`
+		);
+	}
+	if (data.includes('"sent"')) {
+		return pass(
+			`sign-in envelope verified at ${origin.origin}; the request action answered sent for a non-editor probe address`
+		);
+	}
+	return fail('POST ?/request answered success with an unrecognized payload');
+}

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

@@ -22,7 +22,9 @@ export const githubApp: DoctorCheck = {
 			);
 		}
 		if (!ctx.repo) {
-			return skip('pass --repo or set GITHUB_REPO to run this check');
+			return skip(
+				'pass --repo, set GITHUB_REPO, or configure the cairnManifest plugin so the doctor can read the adapter'
+			);
 		}
 		const creds = appCredentials(
 			{ appId: ctx.github.appId, installationId: ctx.github.installationId },

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

@@ -1,9 +1,10 @@
 // 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.
+// svelte.config CSRF handoff, the site-config validation, and the public origin. 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 { requireOrigin } from '../env.js';
 import { parseSiteConfig, urlPolicyFrom } from '../nav/site-config.js';
 import { normalizeConcepts } from '../content/concepts.js';
 import { defineFields } from '../content/schema.js';
@@ -85,6 +86,31 @@ export const configCsrfDisable: DoctorCheck = {
 	},
 };
 
+export const configPublicOrigin: DoctorCheck = {
+	id: 'config.public-origin',
+	conditionId: 'config.public-origin-invalid',
+	title: 'Public origin',
+	async run(ctx: DoctorContext): Promise<CheckResult> {
+		// The wrangler vars hold the value the deployed Worker reads, so they beat the local
+		// environment; the env fallback covers a dashboard-set var the file never carries.
+		const facts = await readWranglerConfig(ctx.readFile);
+		const fromVars = facts?.publicOrigin;
+		const origin = fromVars ?? ctx.publicOrigin;
+		if (facts === null && origin === undefined) {
+			return skip('no wrangler config found and PUBLIC_ORIGIN is not in the environment');
+		}
+		// requireOrigin is the runtime rule (unset, not a URL, http off localhost); reusing it
+		// keeps the doctor and the Worker on one judgment.
+		try {
+			requireOrigin({ PUBLIC_ORIGIN: origin });
+		} catch (err) {
+			return fail(err instanceof Error ? err.message : String(err));
+		}
+		const source = fromVars !== undefined ? 'wrangler vars' : 'environment';
+		return pass(`PUBLIC_ORIGIN is ${origin} (${source})`);
+	},
+};
+
 // 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).

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

@@ -9,10 +9,12 @@ 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_FROM: CheckResult = skip(
+	'pass --from, set CAIRN_FROM, or configure the cairnManifest plugin so the doctor can read the adapter'
+);
 
 export const NO_ACCOUNT: CheckResult = skip(
-	'set CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID to run this check'
+	'set CLOUDFLARE_API_TOKEN, and CLOUDFLARE_ACCOUNT_ID or a wrangler account_id, to run this check'
 );
 
 export function cfGet(ctx: DoctorContext, path: string): Promise<Response> {

package/src/lib/doctor/index.ts

@@ -7,22 +7,28 @@ import {
 	configObservability,
 	configCsrfDisable,
 	configSiteConfig,
+	configPublicOrigin,
 } from './checks-local.js';
+import { configDependencyFloors } from './check-floors.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>]';
+const USAGE =
+	'Usage: cairn-doctor [--from <address>] [--repo <owner/name>] [--send-test <address>] [--probe [url]]';
 
 export interface DoctorArgs {
 	from?: string;
 	repo?: string;
 	sendTest?: string;
+	/** The live admin probe: a URL when --probe carried one, true for the bare flag (probe the
+	 *  PUBLIC_ORIGIN input), absent when the flag never appeared (the probe does not run). */
+	probe?: string | true;
 }
 
-const FLAGS: Record<string, keyof DoctorArgs> = {
+const FLAGS: Record<string, 'from' | 'repo' | 'sendTest'> = {
 	'--from': 'from',
 	'--repo': 'repo',
 	'--send-test': 'sendTest',
@@ -31,8 +37,16 @@ const FLAGS: Record<string, keyof DoctorArgs> = {
 /** 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) {
+	for (let i = 0; i < argv.length; ) {
 		const flag = argv[i];
+		// --probe alone is meaningful (probe the PUBLIC_ORIGIN input), so its value is optional.
+		if (flag === '--probe') {
+			const value = argv[i + 1];
+			const bare = value === undefined || value.startsWith('--');
+			args.probe = bare ? true : value;
+			i += bare ? 1 : 2;
+			continue;
+		}
 		const key = FLAGS[flag];
 		if (!key) throw new Error(`unknown argument ${flag}\n${USAGE}`);
 		const value = argv[i + 1];
@@ -40,6 +54,7 @@ export function parseArgs(argv: string[]): DoctorArgs {
 			throw new Error(`${flag} needs a value\n${USAGE}`);
 		}
 		args[key] = value;
+		i += 2;
 	}
 	return args;
 }
@@ -62,6 +77,7 @@ export function contextFromEnv(
 		repo: args.repo ?? env.GITHUB_REPO,
 		cfToken: env.CLOUDFLARE_API_TOKEN,
 		cfAccountId: env.CLOUDFLARE_ACCOUNT_ID,
+		publicOrigin: env.PUBLIC_ORIGIN,
 		github:
 			GITHUB_APP_ID && GITHUB_APP_INSTALLATION_ID && GITHUB_APP_PRIVATE_KEY_B64
 				? {
@@ -73,10 +89,53 @@ export function contextFromEnv(
 	};
 }
 
+/** The lazy derivation sources the bin wires up: the adapter read through the consumer's own
+ *  Vite resolution and the wrangler config's account_id. Each runs only when an input it feeds
+ *  is still missing, so a doctor run with full flags touches neither. */
+export interface DerivationSources {
+	/** Returns { owner, repo, from } off the adapter, or null when nothing is derivable. */
+	adapterFacts: () => Promise<{ owner?: string; repo?: string; from?: string } | null>;
+	/** Returns the wrangler config's account_id, or undefined when none is declared. */
+	wranglerAccountId: () => Promise<string | undefined>;
+}
+
+/**
+ * Fill the context's missing inputs from the repo the doctor runs in: from and repo off the
+ * adapter, the account id off the wrangler config. An explicit flag or env value always wins
+ * (contextFromEnv already resolved those into ctx), each source runs lazily and only for
+ * inputs still missing, and a derivation failure leaves the input absent so its check skips
+ * with the usual remediation line instead of the doctor crashing. The API token is never
+ * derived; it stays env-only.
+ */
+export async function deriveMissingInputs(
+	ctx: Omit<DoctorContext, 'fetch' | 'readFile'>,
+	sources: DerivationSources
+): Promise<Omit<DoctorContext, 'fetch' | 'readFile'>> {
+	const out = { ...ctx };
+	if (out.from === undefined || out.repo === undefined) {
+		const facts = await sources.adapterFacts().catch(() => null);
+		if (out.from === undefined && typeof facts?.from === 'string') {
+			out.from = facts.from;
+		}
+		if (
+			out.repo === undefined &&
+			typeof facts?.owner === 'string' &&
+			typeof facts?.repo === 'string'
+		) {
+			out.repo = `${facts.owner}/${facts.repo}`;
+		}
+	}
+	if (out.cfAccountId === undefined) {
+		const accountId = await sources.wranglerAccountId().catch(() => undefined);
+		if (typeof accountId === 'string') out.cfAccountId = accountId;
+	}
+	return out;
+}
+
 /**
- * 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.
+ * The default registry: the six local 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 [
@@ -84,6 +143,8 @@ export function defaultChecks(): DoctorCheck[] {
 		configObservability,
 		configCsrfDisable,
 		configSiteConfig,
+		configPublicOrigin,
+		configDependencyFloors,
 		emailSenderOnboarded,
 		edgeHttpsForced,
 		edgeHsts,

package/src/lib/doctor/types.ts

@@ -43,6 +43,8 @@ export interface DoctorContext {
 	cfToken?: string;
 	/** CLOUDFLARE_ACCOUNT_ID. */
 	cfAccountId?: string;
+	/** PUBLIC_ORIGIN, the env fallback when the wrangler vars carry none. */
+	publicOrigin?: 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. */

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

@@ -12,6 +12,10 @@ export interface WranglerFacts {
 	authDbId?: string;
 	/** observability.enabled is true. */
 	observabilityEnabled: boolean;
+	/** vars.PUBLIC_ORIGIN, when declared; the public-origin check validates it. */
+	publicOrigin?: string;
+	/** The top-level account_id, when declared; a fallback for CLOUDFLARE_ACCOUNT_ID. */
+	accountId?: string;
 }
 
 export async function readWranglerConfig(
@@ -91,6 +95,9 @@ function factsFromJsonc(text: string): WranglerFacts {
 		observabilityEnabled: observability?.enabled === true,
 	};
 	if (typeof authDb?.database_id === 'string') facts.authDbId = authDb.database_id;
+	const vars = config.vars as { PUBLIC_ORIGIN?: unknown } | undefined;
+	if (typeof vars?.PUBLIC_ORIGIN === 'string') facts.publicOrigin = vars.PUBLIC_ORIGIN;
+	if (typeof config.account_id === 'string') facts.accountId = config.account_id;
 	return facts;
 }
 
@@ -135,6 +142,10 @@ function factsFromToml(text: string): WranglerFacts {
 			if (key === 'database_id') d1Id = str;
 		} else if (section === '[observability]' && key === 'enabled' && value.startsWith('true')) {
 			facts.observabilityEnabled = true;
+		} else if (section === '[vars]' && key === 'PUBLIC_ORIGIN' && str !== undefined) {
+			facts.publicOrigin = str;
+		} else if (section === '' && key === 'account_id' && str !== undefined) {
+			facts.accountId = str;
 		}
 	}
 	flushD1();

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.
@@ -6,25 +7,30 @@ import type { D1Database } from '@cloudflare/workers-types';
  * The origin is always config-derived, never read from a request header, so a
  * forged Host header cannot redirect a magic link (spec 7.1, risk H3).
  *
- * @throws Error when `PUBLIC_ORIGIN` is unset or empty.
+ * @throws CairnError (`config.public-origin-invalid`) when `PUBLIC_ORIGIN` is unset or
+ * empty, fails to parse as a URL, or uses http on a non-local host.
  */
 export function requireOrigin(env: { PUBLIC_ORIGIN?: string }): string {
   const origin = env.PUBLIC_ORIGIN;
   if (!origin) {
-    throw new Error('PUBLIC_ORIGIN is not configured');
+    throw new CairnError('config.public-origin-invalid', { message: 'PUBLIC_ORIGIN is not configured' });
   }
   let hostname: string;
   try {
     hostname = new URL(origin).hostname;
   } catch {
-    throw new Error(`PUBLIC_ORIGIN is not a valid URL, got ${origin}`);
+    throw new CairnError('config.public-origin-invalid', {
+      message: `PUBLIC_ORIGIN is not a valid URL, got ${origin}`,
+    });
   }
   // The magic-link origin must be https in production so the link and the __Host- cookie are
   // origin-bound. http is allowed only for local dev on localhost or 127.0.0.1, matched exactly so
   // a lookalike host like localhost.example.com cannot skip the https requirement.
   const isLocal = hostname === 'localhost' || hostname === '127.0.0.1';
   if (!origin.startsWith('https://') && !isLocal) {
-    throw new Error(`PUBLIC_ORIGIN must be https in production, got ${origin}`);
+    throw new CairnError('config.public-origin-invalid', {
+      message: `PUBLIC_ORIGIN must be https in production, got ${origin}`,
+    });
   }
   return origin;
 }
@@ -35,11 +41,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 };
 }

package/src/lib/github/types.ts

@@ -43,3 +43,8 @@ export class CommitConflictError extends Error {
     this.name = 'CommitConflictError';
   }
 }
+
+/** Match a commit conflict by class and by name (bundling can alias the class identity). */
+export function isConflict(err: unknown): boolean {
+  return err instanceof CommitConflictError || (err as { name?: string } | null)?.name === 'CommitConflictError';
+}

package/src/lib/index.ts

@@ -20,6 +20,8 @@ export type {
   BackendConfig,
   SenderConfig,
   NavMenuConfig,
+  PreviewConfig,
+  ResolvedPreview,
   AssetConfig,
   RoutingRule,
   ConceptDescriptor,

package/src/lib/log/events.ts

@@ -10,6 +10,7 @@ export type CairnLogEvent =
   | 'auth.session.destroyed'
   | 'commit.succeeded'
   | 'commit.failed'
+  | 'config.invalid'
   | 'entry.published'
   | 'entry.discarded'
   | 'publish.failed'

package/src/lib/nav/site-config.ts

@@ -85,6 +85,9 @@ export interface SiteConfig {
 }
 
 export class SiteConfigError extends Error {
+  /** The registered diagnostic condition a malformed site config maps to (mirrors CairnError). */
+  readonly conditionId = 'config.site-config-invalid';
+
   constructor(message: string) {
     super(message);
     this.name = 'SiteConfigError';

package/src/lib/sveltekit/admin-dispatch.ts

@@ -0,0 +1,75 @@
+// cairn-cms: the single path authority for the single-mount admin dispatcher. The dispatcher
+// mounts one catch-all route under /admin and asks this parser which view a raw pathname
+// names; every admin URL shape is decided here and nowhere else. The parser is pure: it
+// returns a discriminated AdminView, or null for any shape it does not recognize, and the
+// caller maps null to a 404.
+import type { ConceptDescriptor } from '../content/types.js';
+import { findConcept } from '../content/concepts.js';
+import { isValidId } from '../content/ids.js';
+
+/** The views the single-mount admin can render, discriminated for the dispatcher's switch. */
+export type AdminView =
+  | { view: 'index' }
+  | { view: 'login' }
+  | { view: 'confirm' }
+  | { view: 'list'; concept: ConceptDescriptor }
+  | { view: 'edit'; concept: ConceptDescriptor; id: string }
+  | { view: 'editors' }
+  | { view: 'nav' };
+
+/**
+ * Fixed first segments that never resolve as concepts. The engine only allows posts and pages
+ * today, so no collision is possible, but the parser does not depend on that: a reserved
+ * segment wins before concept lookup. `settings` has no view yet; AdminLayout already links
+ * the sidebar to /admin/settings, so the URL is spoken for.
+ */
+const RESERVED_SEGMENTS = new Set(['login', 'auth', 'editors', 'nav', 'settings']);
+
+/**
+ * Parse a raw `URL.pathname` (the caller passes `event.url.pathname`, never a SvelteKit rest
+ * param) into the admin view it names. A single trailing slash is tolerated everywhere; empty
+ * internal segments are not. Each segment is percent-decoded individually, so an encoded slash
+ * stays inside its segment, where it can never match a concept id or pass `isValidId` and so
+ * falls through to null.
+ */
+export function parseAdminPath(
+  pathname: string,
+  concepts: ConceptDescriptor[],
+): AdminView | null {
+  if (pathname !== '/admin' && !pathname.startsWith('/admin/')) return null;
+  let rest = pathname.slice('/admin'.length);
+  // Tolerate exactly one trailing slash; a doubled one leaves an empty segment behind.
+  if (rest.endsWith('/')) rest = rest.slice(0, -1);
+  if (rest === '') return { view: 'index' };
+
+  const rawSegments = rest.slice(1).split('/');
+  if (rawSegments.includes('')) return null;
+  let segments: string[];
+  try {
+    segments = rawSegments.map((segment) => decodeURIComponent(segment));
+  } catch {
+    // Malformed percent encoding is an unrecognized shape, not a server error.
+    return null;
+  }
+
+  if (segments.length === 1) {
+    const [head] = segments;
+    if (head === 'login') return { view: 'login' };
+    if (head === 'editors') return { view: 'editors' };
+    if (head === 'nav') return { view: 'nav' };
+    if (RESERVED_SEGMENTS.has(head)) return null;
+    const concept = findConcept(concepts, head);
+    return concept ? { view: 'list', concept } : null;
+  }
+
+  if (segments.length === 2) {
+    const [head, tail] = segments;
+    if (head === 'auth') return tail === 'confirm' ? { view: 'confirm' } : null;
+    if (RESERVED_SEGMENTS.has(head)) return null;
+    const concept = findConcept(concepts, head);
+    if (!concept || !isValidId(tail)) return null;
+    return { view: 'edit', concept, id: tail };
+  }
+
+  return null;
+}