@glw907/cairn-cms 0.37.0 → 0.38.0

package/dist/render/component-grammar.js

@@ -47,7 +47,7 @@ export function serializeComponent(def, values) {
         if (!content)
             continue;
         if (lines.length > 1)
-            lines.push(''); // blank line before this block
+            lines.push('');
         lines.push(`${COLON.repeat(3)}${slot.name}`, content, COLON.repeat(3));
     }
     lines.push(fence);

package/dist/sveltekit/admin-response.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Attach the baseline security headers to an admin response. No full CSP; see the auth-hardening
+ * design. frame-ancestors is the modern clickjacking control and the one CSP directive included.
+ */
+export declare function applySecurityHeaders(headers: Headers): void;
+/** A branded full-document admin page, hardened with the baseline headers and never cached. */
+export declare function brandedAdminPage(status: number, body: string): Response;

package/dist/sveltekit/admin-response.js

@@ -0,0 +1,21 @@
+// Shared response helpers for cairn's admin pages: the baseline security headers and a branded
+// full-document response. Extracted from guard.ts so the guard's resolve path and the condition
+// renderer share one definition.
+/**
+ * Attach the baseline security headers to an admin response. No full CSP; see the auth-hardening
+ * design. frame-ancestors is the modern clickjacking control and the one CSP directive included.
+ */
+export function applySecurityHeaders(headers) {
+    headers.set('X-Content-Type-Options', 'nosniff');
+    headers.set('X-Frame-Options', 'DENY');
+    headers.set('Content-Security-Policy', "frame-ancestors 'none'");
+    headers.set('Referrer-Policy', 'no-referrer');
+    headers.set('Strict-Transport-Security', 'max-age=63072000; includeSubDomains');
+    headers.set('Permissions-Policy', 'camera=(), microphone=(), geolocation=()');
+}
+/** A branded full-document admin page, hardened with the baseline headers and never cached. */
+export function brandedAdminPage(status, body) {
+    const headers = new Headers({ 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' });
+    applySecurityHeaders(headers);
+    return new Response(body, { status, headers });
+}

package/dist/sveltekit/auth-routes.d.ts

@@ -4,15 +4,28 @@ export interface AuthRoutesConfig {
     branding: AuthBranding;
     send?: SendMagicLink;
 }
+/**
+ * The request-action result. `status` is the discriminant; `sent` is kept for a site rendering its
+ * own form against `form.sent`, so the field is additive. The neutral and send-ok paths return the
+ * identical `{ status: 'sent', sent: true }`, so the common case never leaks allowlist membership.
+ */
+export type RequestResult = {
+    status: 'sent';
+    sent: true;
+} | {
+    status: 'send_error';
+    sent: false;
+} | {
+    status: 'throttled';
+    sent: false;
+};
 export declare function createAuthRoutes(config: AuthRoutesConfig): {
     loginLoad: (event: RequestContext) => {
         siteName: string;
         error: string | null;
         csrf: string;
     };
-    requestAction: (event: RequestContext) => Promise<{
-        sent: true;
-    }>;
+    requestAction: (event: RequestContext) => Promise<RequestResult>;
     confirmLoad: (event: RequestContext) => {
         token: string;
         siteName: string;

package/dist/sveltekit/auth-routes.js

@@ -5,15 +5,26 @@ import { redirect } from '@sveltejs/kit';
 import { requireOrigin, requireDb } from '../env.js';
 import { generateToken, generateSessionId, hashToken, TOKEN_TTL_MS, SESSION_TTL_MS, SEND_COOLDOWN_MS, sessionCookieName, } from '../auth/crypto.js';
 import { findEditor, issueToken, consumeToken, createSession, deleteSession, recentlyIssued } from '../auth/store.js';
-import { buildMagicLinkMessage, cloudflareSend } from '../email.js';
+import { buildMagicLinkMessage, cloudflareSend, emailSendFailure, errorCode } from '../email.js';
 import { issueCsrfToken } from './csrf.js';
 import { log } from '../log/index.js';
+/**
+ * The loggable form of a send failure. The engine's own senders throw clean errors, but `send` is
+ * an injection seam, and a custom sender's thrown error may embed the failed message and with it
+ * the magic link. Scrub any token query value and cap the length, so the documented "records never
+ * carry a token" guarantee holds for the seam too.
+ */
+function scrubSendError(err) {
+    return String(err)
+        .replace(/([?&]token=)[^&\s"'<]+/g, '$1[redacted]')
+        .slice(0, 300);
+}
 export function createAuthRoutes(config) {
     const send = config.send ?? cloudflareSend;
     /**
-     * POST /admin/auth/request. Looks the email up in the allowlist; on a match, issues a token
-     * and emails the confirmation link. The response is identical whether or not the email is
-     * allow-listed, so the endpoint never leaks membership.
+     * POST /admin/auth/request. Looks the email up in the allowlist; on a match, issues a token,
+     * emails the confirmation link, and awaits the send so the status reflects its outcome. The
+     * neutral and send-ok responses are identical, so the common case never leaks membership.
      */
     async function requestAction(event) {
         const env = event.platform?.env ?? {};
@@ -26,31 +37,39 @@ export function createAuthRoutes(config) {
         // fits well under this; only a junk payload is truncated.
         log.info('auth.link.requested', { email: email.slice(0, 320) });
         const editor = email ? await findEditor(db, email) : null;
-        if (editor) {
-            const now = Date.now();
-            // Per-email cooldown: skip the reissue and send when a token for this email was issued within
-            // the window, so the endpoint cannot flood an editor's inbox. The response is unchanged, so
-            // the non-leak property holds.
-            if (!(await recentlyIssued(db, email, now - SEND_COOLDOWN_MS))) {
-                const token = generateToken();
-                await issueToken(db, email, await hashToken(token), now + TOKEN_TTL_MS, now);
-                log.info('auth.token.minted', { email, expiresAt: now + TOKEN_TTL_MS });
-                const link = `${origin}/admin/auth/confirm?token=${encodeURIComponent(token)}`;
-                // The token row is the security-critical write the email depends on, so it is awaited. The
-                // send is a post-response side effect, handed to waitUntil so a slow email provider does not
-                // hold the response. An absent waitUntil (local dev, tests) falls back to await. A send
-                // failure is logged so observability survives a backgrounded send.
-                const sending = send(env, buildMagicLinkMessage({ to: email, branding: config.branding, link })).catch((err) => log.error('auth.link.send_failed', { email, error: String(err) }));
-                // adapter-cloudflare exposes the ExecutionContext as platform.ctx; platform.context is a
-                // deprecated alias kept as a fallback so an adapter that drops it keeps backgrounding.
-                const ctx = event.platform?.ctx ?? event.platform?.context;
-                if (ctx?.waitUntil)
-                    ctx.waitUntil(sending);
-                else
-                    await sending;
-            }
+        // Non-editor: byte-identical to the editor send-ok path, so the response body never leaks
+        // membership. Response timing still differs (the editor path awaits the send), the side-channel
+        // the design accepts as strictly weaker than the explicit throttled signal below.
+        if (!editor)
+            return { status: 'sent', sent: true };
+        const now = Date.now();
+        // Per-email cooldown: an editor who requested within the window gets the throttled signal rather
+        // than a second email. This reveals editor membership, the deliberate relaxed-non-leak posture.
+        if (await recentlyIssued(db, email, now - SEND_COOLDOWN_MS)) {
+            return { status: 'throttled', sent: false };
+        }
+        const token = generateToken();
+        await issueToken(db, email, await hashToken(token), now + TOKEN_TTL_MS, now);
+        log.info('auth.token.minted', { email, expiresAt: now + TOKEN_TTL_MS });
+        const link = `${origin}/admin/auth/confirm?token=${encodeURIComponent(token)}`;
+        // The token row is the security-critical write the email depends on, so it is awaited first.
+        // The send is now awaited too (no waitUntil backgrounding), so its outcome drives the response:
+        // confirm the link went out before telling an editor to check their inbox. The cost is one
+        // email-API round trip on the login POST, the right trade for a login flow.
+        try {
+            await send(env, buildMagicLinkMessage({ to: email, branding: config.branding, link }));
+        }
+        catch (err) {
+            // Map the binding failure to its registered condition (carried as a CairnError with the
+            // original as cause), and log the greppable code plus the conditionId so the next onboarding
+            // gap reads straight to its fix. The editor sees only a generic message, never this detail.
+            const failure = emailSendFailure(err);
+            log.error('auth.link.send_failed', { email, error: scrubSendError(err), code: errorCode(err), conditionId: failure.conditionId });
+            // A plain 200 with a status field, not fail(): the result stays one uniform union for the
+            // page, and the failure is already observable through the error-level log record.
+            return { status: 'send_error', sent: false };
         }
-        return { sent: true };
+        return { status: 'sent', sent: true };
     }
     /** GET /admin/login. Public. Carries the site name, an optional `?error`, and the CSRF token. */
     function loginLoad(event) {

package/dist/sveltekit/condition-response.d.ts

@@ -0,0 +1,11 @@
+/** The guard.rejected reasons, each mapped to its registered condition id. */
+export declare const REASON_CONDITION: {
+    readonly https: "edge.https-not-forced";
+    readonly csrf: "auth.csrf-token-invalid";
+    readonly origin: "auth.csrf-origin-mismatch";
+};
+export type GuardReason = keyof typeof REASON_CONDITION;
+/** Render the Response the guard serves for a rejection, by its condition id. */
+export declare function renderConditionResponse(id: string, ctx?: {
+    url?: URL;
+}): Response;

package/dist/sveltekit/condition-response.js

@@ -0,0 +1,34 @@
+// The runtime renderer leg of the diagnostics model: map a condition to the Response the guard
+// serves. Re-homes the three rejection responses guard.ts built inline, keyed by condition id, so
+// the guard's reason, the registered condition, and the served page stay in step.
+import { brandedAdminPage } from './admin-response.js';
+import { httpsRequiredPage } from './https-required-page.js';
+import { csrfRequiredPage } from './csrf-required-page.js';
+import { condition } from '../diagnostics/index.js';
+/** The guard.rejected reasons, each mapped to its registered condition id. */
+export const REASON_CONDITION = {
+    https: 'edge.https-not-forced',
+    csrf: 'auth.csrf-token-invalid',
+    origin: 'auth.csrf-origin-mismatch',
+};
+/** Render the Response the guard serves for a rejection, by its condition id. */
+export function renderConditionResponse(id, ctx = {}) {
+    // Assert the id is registered before rendering, keeping the renderer in 1:1 with the registry.
+    condition(id);
+    switch (id) {
+        case REASON_CONDITION.https: {
+            const httpsUrl = new URL(ctx.url);
+            httpsUrl.protocol = 'https:';
+            return brandedAdminPage(400, httpsRequiredPage(httpsUrl.toString()));
+        }
+        case REASON_CONDITION.csrf:
+            return brandedAdminPage(403, csrfRequiredPage());
+        case REASON_CONDITION.origin:
+            return new Response('Cross-site POST form submissions are forbidden', {
+                status: 403,
+                headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+            });
+        default:
+            throw new Error(`no runtime renderer for condition: ${id}`);
+    }
+}

package/dist/sveltekit/guard.js

@@ -4,9 +4,9 @@
 import { redirect, error } from '@sveltejs/kit';
 import { resolveSession } from '../auth/store.js';
 import { sessionCookieName } from '../auth/crypto.js';
-import { httpsRequiredPage } from './https-required-page.js';
 import { isUnsafeFormRequest, originMatches, validateCsrfToken } from './csrf.js';
-import { csrfRequiredPage } from './csrf-required-page.js';
+import { applySecurityHeaders } from './admin-response.js';
+import { renderConditionResponse } from './condition-response.js';
 import { log } from '../log/index.js';
 /** The login page and the auth endpoints are public; everything else under /admin is gated. */
 function isPublicAdminPath(pathname) {
@@ -28,41 +28,6 @@ function isLocalHost(hostname) {
         hostname === '[::1]' ||
         hostname.endsWith('.localhost'));
 }
-/**
- * Attach the baseline security headers to an admin response. No full CSP; see the auth-hardening
- * design. frame-ancestors is the modern clickjacking control and the one CSP directive included.
- */
-function applySecurityHeaders(headers) {
-    headers.set('X-Content-Type-Options', 'nosniff');
-    headers.set('X-Frame-Options', 'DENY');
-    headers.set('Content-Security-Policy', "frame-ancestors 'none'");
-    headers.set('Referrer-Policy', 'no-referrer');
-    headers.set('Strict-Transport-Security', 'max-age=63072000; includeSubDomains');
-    headers.set('Permissions-Policy', 'camera=(), microphone=(), geolocation=()');
-}
-/** A branded full-document admin page, hardened with the baseline headers and never cached. */
-function brandedAdminPage(status, body) {
-    const headers = new Headers({ 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' });
-    applySecurityHeaders(headers);
-    return new Response(body, { status, headers });
-}
-/** The hardened 400 help page for a deployed admin request that arrived over http. */
-function httpsRequiredResponse(url) {
-    const httpsUrl = new URL(url);
-    httpsUrl.protocol = 'https:';
-    return brandedAdminPage(400, httpsRequiredPage(httpsUrl.toString()));
-}
-/** A plain 403 for a non-admin cross-origin form POST, matching the framework's wording. */
-function csrfForbidden() {
-    return new Response('Cross-site POST form submissions are forbidden', {
-        status: 403,
-        headers: { 'Content-Type': 'text/plain; charset=utf-8' },
-    });
-}
-/** The branded 403 for a failed admin double-submit token check. */
-function csrfRequiredResponse() {
-    return brandedAdminPage(403, csrfRequiredPage());
-}
 /** The SvelteKit `Handle` that guards `/admin/**` and hardens admin responses. */
 export function createAuthGuard() {
     return async function handle({ event, resolve }) {
@@ -72,7 +37,7 @@ export function createAuthGuard() {
         if (!isAdminPath(pathname)) {
             if (isUnsafeFormRequest(event.request) && !originMatches(event)) {
                 log.warn('guard.rejected', { reason: 'origin', path: pathname });
-                return csrfForbidden();
+                return renderConditionResponse('auth.csrf-origin-mismatch');
             }
             return resolve(event);
         }
@@ -82,13 +47,13 @@ export function createAuthGuard() {
         // posts. Local http (wrangler dev) is exempt.
         if (event.url.protocol === 'http:' && !isLocalHost(event.url.hostname)) {
             log.warn('guard.rejected', { reason: 'https', path: pathname });
-            return httpsRequiredResponse(event.url);
+            return renderConditionResponse('edge.https-not-forced', { url: event.url });
         }
         // Rule 1 - admin: every unsafe form POST carries a valid double-submit token, else the branded
         // 403 before resolve() runs. This covers the public login/auth posts too.
         if (isUnsafeFormRequest(event.request) && !(await validateCsrfToken(event))) {
             log.warn('guard.rejected', { reason: 'csrf', path: pathname });
-            return csrfRequiredResponse();
+            return renderConditionResponse('auth.csrf-token-invalid');
         }
         if (!isPublicAdminPath(pathname)) {
             const env = event.platform?.env ?? {};

package/dist/sveltekit/index.d.ts

@@ -1,5 +1,5 @@
 export { createAuthGuard, requireSession, requireOwner } from './guard.js';
-export { createAuthRoutes, type AuthRoutesConfig } from './auth-routes.js';
+export { createAuthRoutes, type AuthRoutesConfig, type RequestResult } from './auth-routes.js';
 export { createEditorRoutes } from './editors-routes.js';
 export { createContentRoutes } from './content-routes.js';
 export type { NavConcept, LayoutData, EntrySummary, ListData, EditData, ContentEvent, ContentRoutesDeps, } from './content-routes.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glw907/cairn-cms",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "description": "Embedded, magic-link, GitHub-committing CMS for SvelteKit/Cloudflare sites.",
   "type": "module",
   "sideEffects": [

package/src/lib/components/LoginPage.svelte

@@ -8,6 +8,7 @@ the allowlist, so the page never leaks membership (spec §7.1).
   import './cairn-admin.css';
   import { onMount } from 'svelte';
   import MailCheckIcon from '@lucide/svelte/icons/mail-check';
+  import InfoIcon from '@lucide/svelte/icons/info';
   import CairnLogo from './CairnLogo.svelte';
   import CsrfField from './CsrfField.svelte';
   import { cairnFaviconHref } from './cairn-favicon.js';
@@ -16,8 +17,9 @@ the allowlist, so the page never leaks membership (spec §7.1).
   interface Props {
     /** The login load's data: the site name, an optional error, and the CSRF token. */
     data: { siteName: string; error: string | null; csrf: string };
-    /** The action result: `sent` is true once a request was accepted. */
-    form: { sent?: boolean } | null;
+    /** The action result. `sent` is true once a request was accepted; `status` discriminates the
+     * neutral, send-error, and throttled outcomes. */
+    form: { sent?: boolean; status?: 'sent' | 'send_error' | 'throttled' } | null;
   }
 
   let { data, form }: Props = $props();
@@ -37,47 +39,66 @@ the allowlist, so the page never leaks membership (spec §7.1).
   <meta name="robots" content="noindex, nofollow" />
 </svelte:head>
 
+<!-- The brand mark renders in both states; the parent container sets its alignment (left for the
+     form, centered for the confirmation), so one snippet covers both. -->
+{#snippet brand()}
+  <div class="flex items-center gap-2">
+    <CairnLogo class="h-8 w-8 text-primary" />
+    <span class="text-xl font-bold tracking-[-0.01em] font-[family-name:var(--font-display)]">Cairn</span>
+  </div>
+{/snippet}
+
 <!-- data-theme on a bare wrapper: the scoped sheet styles descendants, so the layout classes go one
      level in (a class on the theme element itself would not match). -->
 <div data-theme="cairn-admin" bind:this={rootEl}>
   <div class="flex min-h-screen flex-col items-center justify-center gap-6 bg-base-200 p-4 text-base-content">
   <div class="w-full max-w-sm rounded-box border border-[var(--cairn-card-border)] bg-base-100 p-7 shadow-[var(--cairn-shadow)]">
-    <div class="mb-6 flex items-center gap-2">
-      <CairnLogo class="h-8 w-8 text-primary" />
-      <span class="text-xl font-bold tracking-[-0.01em] font-[family-name:var(--font-display)]">Cairn</span>
-    </div>
-
-    <h1 class="text-lg font-semibold">Sign in to {data.siteName}</h1>
-
-    {#if form?.sent && !dismissed}
-      <div role="status" class="mt-5 flex flex-col items-center text-center">
+    {#if (form?.status === 'sent' || form?.sent) && !dismissed}
+      <!-- The confirmation is a centered moment: brand, then the mail mark, heading, and one line of
+           instruction. The fallback help sits in a gentle inset note below. -->
+      <div role="status" class="flex flex-col items-center text-center">
+        <div class="mb-7">{@render brand()}</div>
         <div
-          class="mb-4 flex h-11 w-11 items-center justify-center rounded-xl text-[var(--color-success)]"
-          style="background-color: color-mix(in oklch, var(--color-success) 16%, transparent);"
+          class="flex h-12 w-12 items-center justify-center rounded-xl text-[var(--color-success)]"
+          style="background-color: color-mix(in oklch, var(--color-success) 15%, transparent); box-shadow: inset 0 0 0 1px color-mix(in oklch, var(--color-success) 22%, transparent);"
         >
           <MailCheckIcon class="h-6 w-6" />
         </div>
-        <h2 class="text-lg font-semibold">Check your email</h2>
-        <p class="mt-1 text-sm text-[var(--color-muted)]">
+        <h1 class="mt-5 text-xl font-semibold tracking-tight">Check your email</h1>
+        <p class="mt-2 text-sm leading-relaxed text-[var(--color-muted)]">
           We sent a sign-in link to your inbox. Open it within 10 minutes to finish signing in.
         </p>
-        <div class="mt-5 w-full border-t border-[var(--cairn-card-border)] pt-4 text-left">
-          <p class="text-sm text-[var(--color-muted)]">
-            No link after a minute or two? Check your spam folder first. If it still hasn't arrived,
-            double-check the address. It has to match the one your site owner added.
+        <div class="mt-6 flex w-full items-start gap-2.5 rounded-[var(--radius-field)] bg-base-content/[0.04] p-3.5 text-left">
+          <InfoIcon class="mt-px h-4 w-4 shrink-0 text-[var(--color-muted)]" />
+          <p class="text-[0.8125rem] leading-relaxed text-[var(--color-subtle)]">
+            No link after a minute or two? Check your spam folder first. If it still hasn't arrived, the
+            address may not match the one your site owner added.
           </p>
-          <button
-            type="button"
-            class="btn btn-ghost btn-sm mt-3 -ml-2 text-primary"
-            onclick={() => (dismissed = true)}
-          >
-            Use a different email
-          </button>
         </div>
+        <button
+          type="button"
+          class="mt-5 cursor-pointer appearance-none border-none bg-transparent p-0 text-sm font-medium text-primary hover:underline"
+          onclick={() => (dismissed = true)}
+        >
+          Use a different email
+        </button>
       </div>
     {:else}
-      <p class="mt-1 mb-5 text-sm text-[var(--color-muted)]">Enter your email. We'll send a one-time sign-in link.</p>
-      {#if data.error}
+      <div class="mb-6 flex justify-center">{@render brand()}</div>
+      <h1 class="text-center text-lg font-semibold">Sign in to {data.siteName}</h1>
+      <p class="mt-1 mb-5 text-center text-sm text-[var(--color-muted)]">Enter your email. We'll send a one-time sign-in link.</p>
+      {#if form?.status === 'send_error'}
+        <div role="alert" class="alert alert-warning mb-3 text-sm">
+          We're having trouble sending sign-in links right now. Please contact the site owner.
+        </div>
+      {:else if form?.status === 'throttled'}
+        <div role="status" class="alert mb-3 text-sm">
+          You requested a link recently. Check your inbox, or wait a minute and try again.
+        </div>
+      {/if}
+      <!-- A fresh action result supersedes the GET-time error, so a resubmit into a throttle or a
+           send failure never shows the stale expired-link alert alongside the new state. -->
+      {#if data.error && !form?.status}
         <div role="alert" class="alert alert-error mb-3 text-sm">That link expired. Request a new one below.</div>
       {/if}
       <form method="POST" class="flex flex-col gap-3">

package/src/lib/diagnostics/conditions.ts

@@ -0,0 +1,80 @@
+// The cairn condition registry: one entry per known environment or operational failure mode. It is
+// the shared identity the readiness checklist, the doctor probe, and the runtime renderer all draw
+// from, so the three surfaces agree (the 1:1:1). Internal: exported from no public package subpath,
+// so the shape stays free to grow, the same stance as src/lib/log/. Renaming an id is a breaking
+// change to the observable contract. See
+// docs/superpowers/specs/2026-06-08-cairn-diagnostics-initiative-design.md.
+import type { CairnLogEvent } from '../log/index.js';
+
+export type ConditionSeverity = 'blocker' | 'warning';
+
+export interface CairnCondition {
+	/** Stable, greppable id, e.g. 'edge.https-not-forced'. */
+	id: string;
+	severity: ConditionSeverity;
+	/** Short human label. */
+	title: string;
+	/** One or two sentences on why the condition bites. */
+	why: string;
+	/** The fix, often a command. */
+	remediation: string;
+	/** Anchor into the readiness checklist doc, filled in when that doc lands (Pass 3). */
+	docsAnchor?: string;
+	/** The log vocabulary event this condition correlates with, if any. */
+	logEvent?: CairnLogEvent;
+}
+
+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.',
+		logEvent: 'guard.rejected',
+	},
+	'auth.csrf-token-invalid': {
+		id: 'auth.csrf-token-invalid',
+		severity: 'blocker',
+		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.',
+		logEvent: 'guard.rejected',
+	},
+	'auth.csrf-origin-mismatch': {
+		id: 'auth.csrf-origin-mismatch',
+		severity: 'blocker',
+		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.',
+		logEvent: 'guard.rejected',
+	},
+	'email.sender-not-onboarded': {
+		id: 'email.sender-not-onboarded',
+		severity: 'blocker',
+		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.',
+		logEvent: 'auth.link.send_failed',
+	},
+	'email.send-failed': {
+		id: 'email.send-failed',
+		severity: 'blocker',
+		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.',
+		logEvent: 'auth.link.send_failed',
+	},
+};
+
+/** 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];
+	if (!found) throw new Error(`unknown cairn condition: ${id}`);
+	return found;
+}
+
+/** Every registered condition, for the checklist generator and coverage tests. */
+export function allConditions(): CairnCondition[] {
+	return Object.values(REGISTRY);
+}

package/src/lib/diagnostics/error.ts

@@ -0,0 +1,20 @@
+// CairnError: a thrown failure that names a known condition. A catch site narrows on it, logs from
+// the condition, and renders the condition's message in place of an opaque string. Its first
+// throw-site is Pass 2 (the email send mapping); Pass 1 lands and tests the primitive.
+import { condition, type CairnCondition } from './conditions.js';
+
+export class CairnError extends Error {
+	readonly conditionId: string;
+	readonly condition: CairnCondition;
+
+	constructor(conditionId: string, options?: { cause?: unknown; message?: string }) {
+		const resolved = condition(conditionId);
+		super(
+			options?.message ?? resolved.title,
+			options?.cause !== undefined ? { cause: options.cause } : undefined
+		);
+		this.name = 'CairnError';
+		this.conditionId = conditionId;
+		this.condition = resolved;
+	}
+}

package/src/lib/diagnostics/index.ts

@@ -0,0 +1,4 @@
+// Internal barrel for the diagnostics model. Not re-exported from any public package subpath.
+export { condition, allConditions } from './conditions.js';
+export type { CairnCondition, ConditionSeverity } from './conditions.js';
+export { CairnError } from './error.js';

package/src/lib/email.ts

@@ -2,6 +2,7 @@
 // send_email binding; production passes `cloudflareSend`, which calls env.EMAIL.send
 // (Cloudflare Email Sending, arbitrary recipients).
 import type { AuthEnv } from './auth/types.js';
+import { CairnError } from './diagnostics/index.js';
 
 export type { AuthEnv };
 
@@ -21,7 +22,9 @@ export interface AuthBranding {
   replyTo?: string;
 }
 
-/** The injected send. Production uses `cloudflareSend`; tests pass a sink. */
+/** The injected send. Production uses `cloudflareSend`; tests pass a sink. A thrown error's
+ *  text reaches the structured log (scrubbed and truncated), so a custom sender must not embed
+ *  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. */
@@ -54,3 +57,30 @@ export const cloudflareSend: SendMagicLink = async (env, message) => {
   if (!env.EMAIL) throw new Error('EMAIL binding is not configured');
   await env.EMAIL.send(message);
 };
+
+/**
+ * Read the E_* code a Cloudflare Email Sending binding error carries (E_SENDER_NOT_VERIFIED,
+ * E_DELIVERY_FAILED, and the rest of the set). The structured `code` property is the documented
+ * shape, but it is unproven against the live binding, so a code embedded in the message is read as
+ * a fallback. A custom injected sender that throws a plain Error has neither, so this returns
+ * undefined and the record still logs cleanly.
+ */
+export function errorCode(err: unknown): string | undefined {
+  if (typeof err === 'object' && err !== null && 'code' in err && typeof err.code === 'string') {
+    return err.code;
+  }
+  return String(err).match(/\bE_[A-Z][A-Z_]*\b/)?.[0];
+}
+
+/**
+ * Map a magic-link send failure to its registered diagnostic condition, carrying the original error
+ * as the cause. The not-verified code is the onboarding gap (the ecxc fault); the live binding has
+ * also been observed throwing the bare "not a verified address" string with no code, so that
+ * message maps to the same condition. Everything else is the generic send failure. The caller logs
+ * the conditionId and code, and returns a send_error status.
+ */
+export function emailSendFailure(err: unknown): CairnError {
+  const onboarding =
+    errorCode(err) === 'E_SENDER_NOT_VERIFIED' || String(err).includes('not a verified address');
+  return new CairnError(onboarding ? 'email.sender-not-onboarded' : 'email.send-failed', { cause: err });
+}

package/src/lib/github/credentials.ts

@@ -1,4 +1,3 @@
-// src/lib/github/credentials.ts
 // cairn-cms: the bridge from the adapter's backend config and the Worker's secret to the
 // 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

package/src/lib/github/repo.ts

@@ -1,4 +1,3 @@
-// src/lib/github/repo.ts
 // cairn-cms: repo reads and the commit, over the GitHub REST API. Listing a concept
 // directory uses the Git Trees API (the contents API silently truncates at 1,000 entries,
 // spec §7.3); a single-file read uses the contents API. An optional token lifts reads to

package/src/lib/github/signing.ts

@@ -1,4 +1,3 @@
-// src/lib/github/signing.ts
 // cairn-cms: the GitHub App auth path. Mint an RS256 App JWT signed in-Worker with Web
 // Crypto, exchange it for a short-lived installation access token, and self-test the
 // brittle key conversion. GitHub issues PKCS#1 private keys and Web Crypto's importKey

package/src/lib/github/types.ts

@@ -1,4 +1,3 @@
-// src/lib/github/types.ts
 // cairn-cms: the GitHub backend's plain data types and its one typed error. The backend
 // reads repo coordinates from the adapter's `BackendConfig` (spec §8); `RepoRef` is the
 // `{ owner, repo, branch }` subset, so `backend` is assignable wherever a `RepoRef` is

package/src/lib/render/component-grammar.ts

@@ -54,7 +54,7 @@ export function serializeComponent(def: ComponentDef, values: ComponentValues):
         ? (Array.isArray(raw) ? raw : []).filter((i) => i !== '').map((i) => `- ${i}`).join('\n')
         : ((raw as string | undefined) ?? '');
     if (!content) continue;
-    if (lines.length > 1) lines.push(''); // blank line before this block
+    if (lines.length > 1) lines.push('');
     lines.push(`${COLON.repeat(3)}${slot.name}`, content, COLON.repeat(3));
   }