@glw907/cairn-cms 0.40.0 → 0.50.0

package/src/lib/{sveltekit → delivery}/public-routes.ts

@@ -1,20 +1,20 @@
-// cairn-cms: public route loaders (dated-slug design). The factory closes over the site-level
-// index, the runtime render, and the origin. entryLoad and entries are site-wide: one catch-all
+// cairn-cms: public route loaders (dated-slug design). The factory closes over the site
+// resolver, the runtime render, and the origin. entryLoad and entries are site-wide: one catch-all
 // `[...path]` route resolves any concept by request path through `byPermalink`. The archive, tag,
-// and tag-index loaders stay concept-scoped, keyed by concept id. The index is built in site code
-// from globs, so it stays in the prerender graph and out of the runtime Worker.
+// and tag-index loaders stay concept-scoped, keyed by concept id. The resolver is built in site
+// code from globs, so it stays in the prerender graph and out of the runtime Worker.
 import { error } from '@sveltejs/kit';
-import type { ContentSummary, ContentEntry } from '../delivery/content-index.js';
-import type { SiteIndex } from '../delivery/site-index.js';
-import { buildSeoMeta } from '../delivery/seo.js';
-import type { SeoMeta } from '../delivery/seo.js';
-import { readSeoFields, resolveImageUrl } from '../delivery/seo-fields.js';
-import { buildLinkResolver } from '../delivery/manifest.js';
+import type { ContentSummary, ContentEntry } from './content-index.js';
+import type { SiteResolver } from './site-resolver.js';
+import { buildSeoMeta } from './seo.js';
+import type { SeoMeta } from './seo.js';
+import { readSeoFields, resolveImageUrl } from './seo-fields.js';
+import { buildLinkResolver } from './site-resolver.js';
 import type { LinkResolve } from '../content/links.js';
 
 /** Injected dependencies for the public loaders. */
 export interface PublicRoutesDeps {
-  site: SiteIndex;
+  site: SiteResolver;
   render: (md: string, opts?: { stagger?: boolean; resolve?: LinkResolve }) => string | Promise<string>;
   origin: string;
   /** Site name for og:site_name and the SEO head. */

package/src/lib/delivery/site-indexes.ts

@@ -1,7 +1,7 @@
 // cairn-cms: the full-auto typed site index (schema-source-of-truth design). It maps over a
 // defineAdapter-typed adapter to give one typed per-concept index, with frontmatter typed as the
 // concept's inferred schema type, plus a site resolver for the catch-all route. It is the typed
-// convenience over createContentIndex and createSiteIndex, not a replacement: both stay the
+// convenience over createContentIndex and createSiteResolver, not a replacement: both stay the
 // lower-level escape hatch. It imports only pure content and delivery code, so the delivery
 // bundle stays backend-free.
 import type { CairnAdapter, ConceptConfig } from '../content/types.js';
@@ -9,9 +9,9 @@ import type { Infer } from '../content/schema.js';
 import type { SiteConfig } from '../nav/site-config.js';
 import { siteDescriptors } from './site-descriptors.js';
 import { createContentIndex, fromGlob } from './content-index.js';
-import { createSiteIndex } from './site-index.js';
+import { createSiteResolver } from './site-resolver.js';
 import type { ContentIndex } from './content-index.js';
-import type { ConceptIndex, SiteIndex } from './site-index.js';
+import type { ConceptIndex, SiteResolver } from './site-resolver.js';
 
 /** A per-concept raw glob record (`{ path: raw }`) keyed by concept id, from `import.meta.glob`. */
 export type SiteGlobs<A extends CairnAdapter> = {
@@ -24,13 +24,13 @@ export type SiteIndexes<A extends CairnAdapter> = {
   [K in keyof A['content']]: ContentIndex<
     NonNullable<A['content'][K]> extends ConceptConfig<infer S> ? Infer<S> : Record<string, unknown>
   >;
-} & { readonly site: SiteIndex };
+} & { readonly site: SiteResolver };
 
 /**
  * Build typed per-concept indexes and a site resolver from one adapter. Pass the per-concept raw
  * globs as `{ posts: import.meta.glob('...?raw', { eager: true }), ... }`; Vite needs the literal
  * glob at the call site, so the engine cannot glob on the site's behalf. `validate: false` opts out
- * of the build gate, exactly as on `createSiteIndex`.
+ * of the build gate, exactly as on `createSiteResolver`.
  */
 export function createSiteIndexes<const A extends CairnAdapter>(
   adapter: A,
@@ -59,6 +59,6 @@ export function createSiteIndexes<const A extends CairnAdapter>(
     byConcept[descriptor.id] = index;
     conceptIndexes.push({ descriptor, index });
   }
-  const site = createSiteIndex(conceptIndexes, opts);
+  const site = createSiteResolver(conceptIndexes, opts);
   return { ...byConcept, site } as SiteIndexes<A>;
 }

package/src/lib/delivery/{site-index.ts → site-resolver.ts}

@@ -1,9 +1,11 @@
-// cairn-cms: the site-level content index (dated-slug design). It unions every concept's
-// per-concept index into one cross-concept resolver: a single byPermalink map a catch-all route
-// matches a request path against, one entries() list the prerenderer walks, and the per-concept
-// indexes for concept-scoped archive, tag, and feed loaders. A duplicate permalink throws at build.
+// cairn-cms: the cross-concept site resolver (dated-slug design). It unions every concept's
+// per-concept index into one resolver: a single byPermalink map a catch-all route matches a
+// request path against, one entries() list the prerenderer walks, and the per-concept indexes
+// for concept-scoped archive, tag, and feed loaders. A duplicate permalink throws at build.
+// buildLinkResolver lives here too, since it closes over the resolver.
 import type { ConceptDescriptor } from '../content/types.js';
 import type { ContentEntry, ContentIndex, ContentSummary } from './content-index.js';
+import type { LinkResolve } from '../content/links.js';
 
 /** One concept's descriptor paired with its built index. */
 export interface ConceptIndex {
@@ -12,7 +14,7 @@ export interface ConceptIndex {
 }
 
 /** The cross-concept query surface a catch-all route and the sitemap read. */
-export interface SiteIndex {
+export interface SiteResolver {
   /** Resolve a request path (with or without a trailing slash) to its entry, or undefined. */
   byPermalink(path: string): ContentEntry | undefined;
   /** Newer/older neighbors within the entry's own concept, for prev/next links. */
@@ -49,11 +51,11 @@ function siteProblems(concepts: ConceptIndex[]): string[] {
  * unless `validate` is `false`, on any non-draft entry whose frontmatter fails its concept's
  * validator, so malformed content fails the build instead of shipping.
  */
-export function createSiteIndex(concepts: ConceptIndex[], opts: { validate?: boolean } = {}): SiteIndex {
+export function createSiteResolver(concepts: ConceptIndex[], opts: { validate?: boolean } = {}): SiteResolver {
   if (opts.validate !== false) {
     const problems = siteProblems(concepts);
     if (problems.length > 0) {
-      throw new Error(`site index: ${problems.length} invalid frontmatter field(s):\n  ${problems.join('\n  ')}`);
+      throw new Error(`site resolver: ${problems.length} invalid frontmatter field(s):\n  ${problems.join('\n  ')}`);
     }
   }
   const byPath = new Map<string, { index: ContentIndex; id: string }>();
@@ -64,7 +66,7 @@ export function createSiteIndex(concepts: ConceptIndex[], opts: { validate?: boo
       const existing = byPath.get(summary.permalink);
       if (existing) {
         throw new Error(
-          `site index: "${existing.id}" and "${summary.id}" both resolve to "${summary.permalink}"`,
+          `site resolver: "${existing.id}" and "${summary.id}" both resolve to "${summary.permalink}"`,
         );
       }
       byPath.set(summary.permalink, { index, id: summary.id });
@@ -90,3 +92,13 @@ export function createSiteIndex(concepts: ConceptIndex[], opts: { validate?: boo
     },
   };
 }
+
+/** A resolver backed by the site resolver, for the build. A miss throws, so a dangling cairn: token
+ *  fails the prerender (the build backstop). The preview uses manifestLinkResolver, which marks. */
+export function buildLinkResolver(site: SiteResolver): LinkResolve {
+  return (ref) => {
+    const url = site.concept(ref.concept)?.byId(ref.id)?.permalink;
+    if (!url) throw new Error(`cairn link target not found: cairn:${ref.concept}/${ref.id}`);
+    return url;
+  };
+}

package/src/lib/delivery/sitemap.ts

@@ -1,5 +1,6 @@
 // cairn-cms: sitemap builder (public-delivery design). Pure over a URL list; the caller
 // derives the list from the content index and the routable concepts.
+import { escapeXml } from './xml.js';
 
 /** One sitemap URL. `lastmod` is a YYYY-MM-DD date. */
 export interface SitemapUrl {
@@ -7,10 +8,6 @@ export interface SitemapUrl {
   lastmod?: string;
 }
 
-function escapeXml(value: string): string {
-  return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
-}
-
 /** Build a sitemap XML document from a list of URLs. */
 export function buildSitemap(urls: SitemapUrl[]): string {
   const entries = urls

package/src/lib/delivery/xml.ts

@@ -0,0 +1,12 @@
+// cairn-cms: the one XML text escape the feed and sitemap builders share. The strongest of the
+// two copies it replaced (the old sitemap copy skipped quotes), so both documents stay safe in
+// element text and double-quoted attributes.
+
+/** Escape the XML-significant characters for element text and double-quoted attribute values. */
+export function escapeXml(value: string): string {
+  return value
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;');
+}

package/src/lib/diagnostics/conditions.ts

@@ -18,19 +18,27 @@ export interface CairnCondition {
 	why: string;
 	/** The fix, often a command. */
 	remediation: string;
-	/** Anchor into the readiness checklist doc, filled in when that doc lands (Pass 3). */
+	/**
+	 * The condition's section in the readiness checklist, written as
+	 * 'cloudflare-readiness.md#<heading-slug>' so a doc can link it relative to docs/guides/.
+	 * The check:readiness gate parses the part after '#' and asserts the heading exists; two
+	 * conditions may share a section. Every entry carries one unless the gate's allowlist
+	 * excuses it.
+	 */
 	docsAnchor?: string;
 	/** The log vocabulary event this condition correlates with, if any. */
 	logEvent?: CairnLogEvent;
 }
 
-const REGISTRY: Record<string, CairnCondition> = {
+// Exported for the freeze test only; resolve entries through condition() everywhere else.
+export const REGISTRY: Record<string, CairnCondition> = {
 	'edge.https-not-forced': {
 		id: 'edge.https-not-forced',
 		severity: 'blocker',
 		title: 'Always Use HTTPS is off',
 		why: 'The JS-free admin sign-in posts a form, and the framework CSRF guard rejects a form POST whose origin scheme does not match, so an admin reached over http hits an opaque 403.',
 		remediation: 'Turn on Always Use HTTPS for the zone under SSL/TLS, Edge Certificates, and keep HSTS on.',
+		docsAnchor: 'cloudflare-readiness.md#force-https-at-the-edge',
 		logEvent: 'guard.rejected',
 	},
 	'auth.csrf-token-invalid': {
@@ -39,6 +47,7 @@ const REGISTRY: Record<string, CairnCondition> = {
 		title: 'Admin CSRF token check failed',
 		why: 'An admin form POST carried no valid __Host-cairn_csrf double-submit token, usually a stale tab or blocked cookies.',
 		remediation: 'Open the sign-in page fresh, allow cookies for the site, and request a new link.',
+		docsAnchor: 'cloudflare-readiness.md#admin-csrf-token-rejected',
 		logEvent: 'guard.rejected',
 	},
 	'auth.csrf-origin-mismatch': {
@@ -47,6 +56,7 @@ const REGISTRY: Record<string, CairnCondition> = {
 		title: 'Non-admin form Origin rejected',
 		why: "A non-admin unsafe form POST carried an Origin that did not match the site, so cairn's restored framework Origin check rejected it.",
 		remediation: 'Post the form from the same origin, or check a proxy that strips or rewrites the Origin header.',
+		docsAnchor: 'cloudflare-readiness.md#non-admin-origin-rejected',
 		logEvent: 'guard.rejected',
 	},
 	'email.sender-not-onboarded': {
@@ -55,6 +65,7 @@ const REGISTRY: Record<string, CairnCondition> = {
 		title: 'Email sending domain is not onboarded',
 		why: 'The from-address domain has no enabled Cloudflare sending subdomain, so env.EMAIL.send has no aligned sender and the magic-link send throws E_SENDER_NOT_VERIFIED. No editor can sign in.',
 		remediation: 'Onboard the sending domain with `wrangler email sending enable <domain>`, then re-deploy. The domain must match branding.from.',
+		docsAnchor: 'cloudflare-readiness.md#onboard-the-sending-domain',
 		logEvent: 'auth.link.send_failed',
 	},
 	'email.send-failed': {
@@ -63,10 +74,72 @@ const REGISTRY: Record<string, CairnCondition> = {
 		title: 'Magic-link email send failed',
 		why: 'The magic-link send threw for a reason other than a missing sender onboarding (a delivery error, a binding misconfiguration, or a custom sender failure), so the editor never received a link.',
 		remediation: 'Read the auth.link.send_failed log record (the code and error fields) in Workers Logs, and check the EMAIL binding and the sender configuration.',
+		docsAnchor: 'cloudflare-readiness.md#onboard-the-sending-domain',
 		logEvent: 'auth.link.send_failed',
 	},
+	'config.bindings-missing': {
+		id: 'config.bindings-missing',
+		severity: 'blocker',
+		title: 'Wrangler bindings are missing',
+		why: 'The wrangler config declares no send_email binding named EMAIL or no D1 binding named AUTH_DB, so the magic-link send or the session store has nothing to call and no editor can sign in.',
+		remediation: 'Declare the send_email binding as EMAIL and the d1_databases binding as AUTH_DB in wrangler.jsonc (or wrangler.toml), then re-deploy.',
+		docsAnchor: 'cloudflare-readiness.md#deploy-the-worker-with-its-bindings',
+	},
+	'config.observability-off': {
+		id: 'config.observability-off',
+		severity: 'warning',
+		title: 'Workers Logs has no sink',
+		why: 'observability.enabled is not true in the wrangler config, so the structured log records go nowhere and a runtime failure leaves nothing to read.',
+		remediation: 'Set observability.enabled to true in wrangler.jsonc, then re-deploy.',
+		docsAnchor: 'cloudflare-readiness.md#turn-on-observability',
+	},
+	'config.csrf-disable-missing': {
+		id: 'config.csrf-disable-missing',
+		severity: 'warning',
+		title: 'Framework CSRF check is not handed off',
+		why: "The CSRF authority is not handed to cairn cleanly. Either svelte.config.js does not carry csrf: { checkOrigin: false }, so SvelteKit's own Origin check runs ahead of cairn's guard and rejects an admin form POST that arrives without an Origin header, or the disable is present with no cairn guard wired in src/hooks.server.ts, which leaves the site with no CSRF protection at all.",
+		remediation: "Set csrf: { checkOrigin: false } in svelte.config.js and wire createAuthGuard into src/hooks.server.ts; cairn's guard owns the Origin and double-submit token checks.",
+		docsAnchor: 'cloudflare-readiness.md#hand-cairn-the-csrf-authority',
+	},
+	'config.site-config-invalid': {
+		id: 'config.site-config-invalid',
+		severity: 'blocker',
+		title: 'Site config does not validate',
+		why: 'site.config.yaml fails to parse or fails the URL-policy validation, so the build and the admin cannot resolve the content concepts.',
+		remediation: 'Correct site.config.yaml; the parse or validation error names the failing field or URL-policy rule.',
+		docsAnchor: 'cloudflare-readiness.md#validate-the-site-config',
+	},
+	'edge.hsts-off': {
+		id: 'edge.hsts-off',
+		severity: 'warning',
+		title: 'HSTS is off',
+		why: 'The zone sends no Strict-Transport-Security header with a meaningful max-age, so browsers do not pin https and a later http visit can still hit the admin guard rejection.',
+		remediation: 'Turn on HSTS for the zone under SSL/TLS, Edge Certificates, with a max-age of at least six months.',
+		docsAnchor: 'cloudflare-readiness.md#turn-on-hsts',
+	},
+	'auth.store-unreachable': {
+		id: 'auth.store-unreachable',
+		severity: 'blocker',
+		title: 'Auth store is unreachable',
+		why: 'The AUTH_DB D1 database is missing, lacks the auth schema, or holds no owner row, so no magic-link token can be minted and nobody can sign in.',
+		remediation: 'Create the database, apply the auth schema with `wrangler d1 execute <db> --remote --file ./migrations/0000_auth.sql`, seed the owner row, and check the AUTH_DB binding id in wrangler.jsonc.',
+		docsAnchor: 'cloudflare-readiness.md#provision-the-auth-store',
+	},
+	'github.app-unreachable': {
+		id: 'github.app-unreachable',
+		severity: 'blocker',
+		title: 'GitHub App is unreachable',
+		why: 'The App key fails to parse, the App fails to authenticate, the installation token fails to mint, or the repository refuses a read, so saves and publishes cannot commit.',
+		remediation: 'Check GITHUB_APP_ID, GITHUB_APP_INSTALLATION_ID, and GITHUB_APP_PRIVATE_KEY_B64 against the App settings, and confirm the App is installed on the repository.',
+		docsAnchor: 'cloudflare-readiness.md#install-the-github-app',
+		logEvent: 'github.unreachable',
+	},
 };
 
+// The registry is shared identity, never working state; freeze every entry and the map itself.
+for (const entry of Object.values(REGISTRY)) Object.freeze(entry);
+Object.freeze(REGISTRY);
+
 /** Resolve a condition by id. Throws on an unknown id, since ids are compile-time constants. */
 export function condition(id: string): CairnCondition {
 	const found = REGISTRY[id];

package/src/lib/doctor/bin.ts

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// cairn-doctor: the environment preflight. A thin shell over index.ts (where the unit tests
+// reach the logic): parse the flags, assemble the context with the real fetch and filesystem,
+// run the default registry plus the opt-in live send, print the report. Bad flags go to
+// stderr with exit 2; a failed check exits 1; a clean or all-skip run exits 0. The codes go
+// through process.exitCode, never process.exit, so a piped stdout flushes the whole report
+// before the process ends.
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { liveSendCheck } from './check-send.js';
+import { contextFromEnv, defaultChecks, formatReport, parseArgs, runDoctor } from './index.js';
+
+async function main(): Promise<void> {
+	let args: ReturnType<typeof parseArgs>;
+	try {
+		args = parseArgs(process.argv.slice(2));
+	} catch (err) {
+		console.error(err instanceof Error ? err.message : String(err));
+		process.exitCode = 2;
+		return;
+	}
+
+	const cwd = process.cwd();
+	const ctx = {
+		...contextFromEnv(process.env, args, cwd),
+		fetch: globalThis.fetch,
+		readFile: async (relPath: string): Promise<string | null> => {
+			try {
+				return await readFile(resolve(cwd, relPath), 'utf8');
+			} catch (err) {
+				if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null;
+				throw err;
+			}
+		},
+	};
+
+	const checks = defaultChecks();
+	if (args.sendTest) checks.push(liveSendCheck(args.sendTest));
+
+	const { results, failed } = await runDoctor(checks, ctx);
+	console.log(formatReport(results));
+	process.exitCode = failed > 0 ? 1 : 0;
+}
+
+await main();

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

@@ -0,0 +1,43 @@
+// The doctor's opt-in live send (--send-test): one real message through the Email Sending
+// REST API, since the Worker EMAIL binding is unreachable from a CLI. A factory rather than
+// a check constant, so the check exists only when the bin receives an address; no default
+// registry carries it.
+//
+// Endpoint and payload verified against the Cloudflare API reference, 2026-06-11:
+//   POST /accounts/{account_id}/email/sending/send with { from, to, subject, text },
+//   where from and to take a plain address string.
+//   https://developers.cloudflare.com/api/resources/email_sending/
+import { fail, pass } from './types.js';
+import type { CheckResult, DoctorCheck, DoctorContext } from './types.js';
+import { cfPost, NO_ACCOUNT, NO_FROM } from './cloudflare-api.js';
+
+// Enough of an error body to act on without flooding the one-line report.
+const EXCERPT_MAX = 200;
+
+/** Build the live-send check for one recipient address. */
+export function liveSendCheck(to: string): DoctorCheck {
+	return {
+		id: 'email.live-send',
+		conditionId: 'email.send-failed',
+		title: 'Live test send',
+		async run(ctx: DoctorContext): Promise<CheckResult> {
+			if (!ctx.cfToken || !ctx.cfAccountId) return NO_ACCOUNT;
+			if (!ctx.from) return NO_FROM;
+			try {
+				const res = await cfPost(ctx, `/accounts/${ctx.cfAccountId}/email/sending/send`, {
+					from: ctx.from,
+					to,
+					subject: 'cairn doctor test send',
+					text: 'This is a cairn doctor test send. Receiving it proves the sending path.',
+				});
+				if (!res.ok) {
+					const excerpt = (await res.text()).slice(0, EXCERPT_MAX);
+					return fail(`send returned ${res.status}: ${excerpt}`);
+				}
+				return pass(`sent to ${to}; check the inbox`);
+			} catch (err) {
+				return fail(String(err));
+			}
+		},
+	};
+}

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

@@ -0,0 +1,222 @@
+// The doctor's Cloudflare API checks: the onboarded sending domain, the zone HTTPS posture,
+// and the D1 auth store, over the shared cloudflare-api plumbing.
+//
+// Endpoints verified against the Cloudflare API reference, 2026-06-11:
+// - Email Sending subdomains (zone-scoped; this is the namespace `wrangler email sending
+//   enable` feeds, and the listing carries `{ result: [{ name, enabled, tag }] }`):
+//   GET /zones/{zone_id}/email/sending/subdomains
+//   https://developers.cloudflare.com/api/resources/email_sending/
+// - Zone lookup, `{ result: [{ id }] }`: GET /zones?name=<domain>
+//   https://developers.cloudflare.com/api/resources/zones/
+// - Zone settings, `{ result: { value } }` where always_use_https carries 'on' | 'off' and
+//   security_header nests `value.strict_transport_security.{enabled,max_age}`:
+//   GET /zones/{zone_id}/settings/{setting_id}
+//   https://developers.cloudflare.com/api/resources/zones/subresources/settings/
+// - D1 query, `{ sql }` in, `{ result: [{ results: [...] }] }` out:
+//   POST /accounts/{account_id}/d1/database/{database_id}/query
+//   https://developers.cloudflare.com/api/resources/d1/subresources/database/
+import { fail, pass, skip } from './types.js';
+import type { CheckResult, DoctorCheck, DoctorContext } from './types.js';
+import { cfGet, cfPost, NO_ACCOUNT, NO_FROM, NO_TOKEN } from './cloudflare-api.js';
+import { readWranglerConfig } from './wrangler-config.js';
+
+// 30 days. The production zones run two years; anything under a month is a trivial pin.
+const MIN_HSTS_MAX_AGE = 2592000;
+
+function fromDomain(from: string): string {
+	return from.slice(from.indexOf('@') + 1);
+}
+
+// The registrable domain is taken as the last two labels of the from-domain. A deliberate
+// simplification: correct for the single-label public suffixes cairn targets (.ski, .life),
+// wrong for multi-part suffixes like .co.uk, which would need a public-suffix list the
+// doctor does not carry.
+function registrableDomain(domain: string): string {
+	return domain.split('.').slice(-2).join('.');
+}
+
+// A 401/403 means the token cannot make this read at all, so the product condition's
+// remediation (onboard the domain, fix the binding) would point the operator at the wrong fix.
+// The conditionId stays; the detail carries the scope truth.
+function permissionFail(status: number, scope: string): CheckResult | null {
+	if (status !== 401 && status !== 403) return null;
+	return fail(
+		`the API token lacks permission for this read (HTTP ${status}); grant the token ${scope} access`
+	);
+}
+
+async function resolveZoneId(
+	ctx: DoctorContext,
+	domain: string
+): Promise<{ zoneId: string } | { fail: CheckResult }> {
+	// The from-domain may be its own Cloudflare zone (mail.example.com registered directly), so
+	// the exact name is tried first and the registrable domain is the fallback.
+	const apex = registrableDomain(domain);
+	const names = domain === apex ? [domain] : [domain, apex];
+	for (const name of names) {
+		const res = await cfGet(ctx, `/zones?name=${encodeURIComponent(name)}`);
+		if (!res.ok) {
+			return { fail: fail(`zone lookup for ${name} returned ${res.status}`) };
+		}
+		const body = (await res.json()) as { result?: { id?: string }[] };
+		const id = body.result?.[0]?.id;
+		if (typeof id === 'string') return { zoneId: id };
+	}
+	return { fail: fail(`no zone named ${names.join(' or ')} is visible to this token`) };
+}
+
+/** Resolve the domain's zone and read one of its settings, returning `result.value`. */
+async function readZoneSetting<T>(
+	ctx: DoctorContext,
+	domain: string,
+	settingId: string
+): Promise<{ value: T | undefined } | { fail: CheckResult }> {
+	const zone = await resolveZoneId(ctx, domain);
+	if ('fail' in zone) return zone;
+	const res = await cfGet(ctx, `/zones/${zone.zoneId}/settings/${settingId}`);
+	if (!res.ok) {
+		return { fail: fail(`${settingId} read returned ${res.status}`) };
+	}
+	const body = (await res.json()) as { result?: { value?: T } };
+	return { value: body.result?.value };
+}
+
+export const emailSenderOnboarded: DoctorCheck = {
+	id: 'email.sender-onboarded',
+	conditionId: 'email.sender-not-onboarded',
+	title: 'Email sending domain',
+	async run(ctx: DoctorContext): Promise<CheckResult> {
+		if (!ctx.cfToken) return NO_TOKEN;
+		if (!ctx.from) return NO_FROM;
+		const domain = fromDomain(ctx.from);
+		try {
+			const zone = await resolveZoneId(ctx, domain);
+			if ('fail' in zone) return zone.fail;
+			const res = await cfGet(ctx, `/zones/${zone.zoneId}/email/sending/subdomains`);
+			if (!res.ok) {
+				return (
+					permissionFail(res.status, 'Email Sending: Read') ??
+					fail(`sending subdomain list returned ${res.status}`)
+				);
+			}
+			const body = (await res.json()) as { result?: { name?: string; enabled?: boolean }[] };
+			const entry = body.result?.find((s) => s.name === domain);
+			if (entry?.enabled === true) {
+				return pass(`${domain} has an enabled sending subdomain`);
+			}
+			if (entry) {
+				return fail(`${domain} is onboarded but sending is disabled`);
+			}
+			return fail(`${domain} has no sending subdomain on the zone`);
+		} catch (err) {
+			return fail(String(err));
+		}
+	},
+};
+
+export const edgeHttpsForced: DoctorCheck = {
+	id: 'edge.https-forced',
+	conditionId: 'edge.https-not-forced',
+	title: 'Always Use HTTPS',
+	async run(ctx: DoctorContext): Promise<CheckResult> {
+		if (!ctx.cfToken) return NO_TOKEN;
+		if (!ctx.from) return NO_FROM;
+		try {
+			const setting = await readZoneSetting<string>(ctx, fromDomain(ctx.from), 'always_use_https');
+			if ('fail' in setting) return setting.fail;
+			if (setting.value === 'on') {
+				return pass('Always Use HTTPS is on');
+			}
+			return fail(`always_use_https is ${setting.value ?? 'unreadable'}`);
+		} catch (err) {
+			return fail(String(err));
+		}
+	},
+};
+
+interface SecurityHeaderValue {
+	strict_transport_security?: { enabled?: boolean; max_age?: number };
+}
+
+export const edgeHsts: DoctorCheck = {
+	id: 'edge.hsts',
+	conditionId: 'edge.hsts-off',
+	title: 'HSTS',
+	async run(ctx: DoctorContext): Promise<CheckResult> {
+		if (!ctx.cfToken) return NO_TOKEN;
+		if (!ctx.from) return NO_FROM;
+		try {
+			const setting = await readZoneSetting<SecurityHeaderValue>(
+				ctx,
+				fromDomain(ctx.from),
+				'security_header'
+			);
+			if ('fail' in setting) return setting.fail;
+			const sts = setting.value?.strict_transport_security;
+			if (sts?.enabled !== true) {
+				return fail('HSTS is disabled on the zone');
+			}
+			const maxAge = sts.max_age ?? 0;
+			if (maxAge < MIN_HSTS_MAX_AGE) {
+				return fail(`HSTS max-age ${maxAge} is under the ${MIN_HSTS_MAX_AGE} (30 day) floor`);
+			}
+			return pass(`HSTS enabled with max-age ${maxAge}`);
+		} catch (err) {
+			return fail(String(err));
+		}
+	},
+};
+
+const AUTH_TABLES = ['editor', 'magic_token', 'session'];
+
+async function d1Query(
+	ctx: DoctorContext,
+	databaseId: string,
+	sql: string
+): Promise<{ rows: Record<string, unknown>[] } | { fail: CheckResult }> {
+	const res = await cfPost(
+		ctx,
+		`/accounts/${ctx.cfAccountId}/d1/database/${encodeURIComponent(databaseId)}/query`,
+		{ sql }
+	);
+	if (!res.ok) {
+		return {
+			fail:
+				permissionFail(res.status, 'D1: Read') ??
+				fail(`AUTH_DB is unreachable: the query returned ${res.status}`),
+		};
+	}
+	const body = (await res.json()) as { result?: { results?: Record<string, unknown>[] }[] };
+	return { rows: body.result?.[0]?.results ?? [] };
+}
+
+export const authStore: DoctorCheck = {
+	id: 'auth.store',
+	conditionId: 'auth.store-unreachable',
+	title: 'Auth store (D1)',
+	async run(ctx: DoctorContext): Promise<CheckResult> {
+		if (!ctx.cfToken || !ctx.cfAccountId) return NO_ACCOUNT;
+		const facts = await readWranglerConfig(ctx.readFile);
+		if (typeof facts?.authDbId !== 'string') {
+			return skip('no AUTH_DB database_id in wrangler.jsonc or wrangler.toml');
+		}
+		try {
+			const tables = await d1Query(ctx, facts.authDbId, "SELECT name FROM sqlite_master WHERE type='table'");
+			if ('fail' in tables) return tables.fail;
+			const names = new Set(tables.rows.map((row) => row.name));
+			const missing = AUTH_TABLES.filter((table) => !names.has(table));
+			if (missing.length) {
+				return fail(`auth schema is missing: ${missing.join(', ')}`);
+			}
+			const owners = await d1Query(ctx, facts.authDbId, "SELECT count(*) AS n FROM editor WHERE role='owner'");
+			if ('fail' in owners) return owners.fail;
+			const n = owners.rows[0]?.n;
+			if (typeof n === 'number' && n >= 1) {
+				return pass(`auth schema present with ${n} owner row(s)`);
+			}
+			return fail('the editor table holds no owner row');
+		} catch (err) {
+			return fail(String(err));
+		}
+	},
+};