@glw907/cairn-cms 0.35.0 → 0.37.0

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to this project are recorded here, most recent first.
 
+## 0.37.0
+
+The magic-link sign-in confirmation is now a branded panel in place of the flat success bar. After an
+editor requests a link, the page shows a mail icon in a soft success tile, a "Check your email"
+heading, and the ten-minute expiry note, all in the admin's Warm Stone styling. Below a divider it
+adds guidance for the link that never arrives: check the spam folder first, then confirm the address
+matches the one the site owner added. This covers the common fat-finger case, where a mistyped address
+gets the same neutral confirmation and no email. A "Use a different email" action returns to the form
+so the address gets corrected without a reload. The confirmation copy stays identical whether or not
+the email is on the allowlist, so the page still never leaks membership.
+
+The change is internal to the `LoginPage` component and needs no action.
+
+## 0.36.0
+
+cairn now emits structured diagnostic events. The engine had three bare `console.error` calls and no
+queryable diagnostics. An internal logger assembles a JSON record for each event, with an envelope
+(`level`, `event`, `timestamp`) and event-specific fields, and writes it to `console`. Cloudflare
+Workers Logs ingests and indexes those records when a site sets `observability.enabled = true`, so
+each field filters. The event vocabulary covers the auth flow, the commit pipeline, and the admin
+guard's pre-resolve refusals. The records carry an editor's email for attribution and never carry a
+magic-link token, a session id, or a magic-link's contents; a standing redaction test pins that.
+
+The event names are a stable contract, so renaming one is a breaking change later. The full list, with
+each event's level, trigger, and fields, is in the new [log events reference](docs/reference/log-events.md),
+and the [read cairn's logs guide](docs/guides/read-cairn-logs.md) covers the one setup line and the
+dashboard query.
+
+Consumers may: set `observability.enabled = true` in `wrangler.jsonc` to read the events in Workers
+Logs. The change is otherwise additive and needs no action.
+
 ## 0.35.0
 
 cairn now owns CSRF for the admin. A consuming site disables SvelteKit's global `checkOrigin`, and

package/dist/components/LoginPage.svelte

@@ -7,6 +7,7 @@ the allowlist, so the page never leaks membership (spec §7.1).
 <script lang="ts">
   import './cairn-admin.css';
   import { onMount } from 'svelte';
+  import MailCheckIcon from '@lucide/svelte/icons/mail-check';
   import CairnLogo from './CairnLogo.svelte';
   import CsrfField from './CsrfField.svelte';
   import { cairnFaviconHref } from './cairn-favicon.js';
@@ -22,6 +23,9 @@ the allowlist, so the page never leaks membership (spec §7.1).
   let { data, form }: Props = $props();
 
   let rootEl = $state<HTMLElement>();
+  // Lets a mistyped address go back to the form without a reload, even though the server still
+  // reports `sent`. The success copy never reveals whether the email was on the allowlist.
+  let dismissed = $state(false);
   onMount(() => {
     if (rootEl) warnIfChromeWrapped(rootEl);
   });
@@ -44,13 +48,35 @@ the allowlist, so the page never leaks membership (spec §7.1).
     </div>
 
     <h1 class="text-lg font-semibold">Sign in to {data.siteName}</h1>
-    <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 form?.sent}
-      <div role="status" class="alert alert-success text-sm">
-        Check your email for a sign-in link. It expires in 10 minutes.
+    {#if form?.sent && !dismissed}
+      <div role="status" class="mt-5 flex flex-col items-center text-center">
+        <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);"
+        >
+          <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)]">
+          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.
+          </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>
       </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 role="alert" class="alert alert-error mb-3 text-sm">That link expired. Request a new one below.</div>
       {/if}

package/dist/components/cairn-admin.css

@@ -3337,6 +3337,10 @@
     margin-top: calc(var(--spacing) * 4);
   }
 
+  :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .mt-5 {
+    margin-top: calc(var(--spacing) * 5);
+  }
+
   :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .mt-6 {
     margin-top: calc(var(--spacing) * 6);
   }
@@ -3394,6 +3398,10 @@
     margin-bottom: calc(var(--spacing) * 6);
   }
 
+  :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .-ml-2 {
+    margin-left: calc(var(--spacing) * -2);
+  }
+
   :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .ml-1 {
     margin-left: calc(var(--spacing) * 1);
   }
@@ -3786,6 +3794,10 @@
     height: calc(var(--spacing) * 5);
   }
 
+  :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .h-6 {
+    height: calc(var(--spacing) * 6);
+  }
+
   :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .h-7 {
     height: calc(var(--spacing) * 7);
   }
@@ -3794,6 +3806,10 @@
     height: calc(var(--spacing) * 8);
   }
 
+  :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .h-11 {
+    height: calc(var(--spacing) * 11);
+  }
+
   :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .h-12 {
     height: calc(var(--spacing) * 12);
   }
@@ -3852,6 +3868,10 @@
     width: calc(var(--spacing) * 5);
   }
 
+  :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .w-6 {
+    width: calc(var(--spacing) * 6);
+  }
+
   :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .w-7 {
     width: calc(var(--spacing) * 7);
   }
@@ -3864,6 +3884,10 @@
     width: calc(var(--spacing) * 9);
   }
 
+  :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .w-11 {
+    width: calc(var(--spacing) * 11);
+  }
+
   :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .w-12 {
     width: calc(var(--spacing) * 12);
   }
@@ -4420,6 +4444,10 @@
     padding-top: calc(var(--spacing) * 3);
   }
 
+  :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .pt-4 {
+    padding-top: calc(var(--spacing) * 4);
+  }
+
   :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .pr-3 {
     padding-right: calc(var(--spacing) * 3);
   }
@@ -4432,6 +4460,10 @@
     text-align: center;
   }
 
+  :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .text-left {
+    text-align: left;
+  }
+
   :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .text-right {
     text-align: right;
   }
@@ -4561,6 +4593,10 @@
     color: var(--color-subtle);
   }
 
+  :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .text-\[var\(--color-success\)\] {
+    color: var(--color-success);
+  }
+
   :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .text-base-content {
     color: var(--color-base-content);
   }

package/dist/log/emit.d.ts

@@ -0,0 +1,14 @@
+import type { CairnLogEvent } from './events.js';
+export type LogLevel = 'info' | 'warn' | 'error';
+export interface LogRecord {
+    level: LogLevel;
+    event: CairnLogEvent;
+    timestamp: string;
+    [field: string]: unknown;
+}
+export interface Logger {
+    info(event: CairnLogEvent, fields?: Record<string, unknown>): void;
+    warn(event: CairnLogEvent, fields?: Record<string, unknown>): void;
+    error(event: CairnLogEvent, fields?: Record<string, unknown>): void;
+}
+export declare const log: Logger;

package/dist/log/emit.js

@@ -0,0 +1,18 @@
+const sinkByLevel = {
+    info: (record) => console.log(record),
+    warn: (record) => console.warn(record),
+    error: (record) => console.error(record),
+};
+function buildRecord(level, event, fields) {
+    // The envelope keys are written last, so a stray field named level/event/timestamp cannot
+    // corrupt the record shape a subscriber relies on.
+    return { ...fields, level, event, timestamp: new Date().toISOString() };
+}
+function emit(level, event, fields = {}) {
+    sinkByLevel[level](buildRecord(level, event, fields));
+}
+export const log = {
+    info: (event, fields) => emit('info', event, fields),
+    warn: (event, fields) => emit('warn', event, fields),
+    error: (event, fields) => emit('error', event, fields),
+};

package/dist/log/events.d.ts

@@ -0,0 +1 @@
+export type CairnLogEvent = 'auth.link.requested' | 'auth.link.send_failed' | 'auth.token.minted' | 'auth.token.confirmed' | 'auth.session.created' | 'auth.session.destroyed' | 'commit.succeeded' | 'commit.failed' | 'guard.rejected';

package/dist/log/events.js

@@ -0,0 +1 @@
+export {};

package/dist/log/index.d.ts

@@ -0,0 +1,3 @@
+export { log } from './emit.js';
+export type { Logger, LogLevel, LogRecord } from './emit.js';
+export type { CairnLogEvent } from './events.js';

package/dist/log/index.js

@@ -0,0 +1 @@
+export { log } from './emit.js';

package/dist/sveltekit/auth-routes.js

@@ -7,6 +7,7 @@ import { generateToken, generateSessionId, hashToken, TOKEN_TTL_MS, SESSION_TTL_
 import { findEditor, issueToken, consumeToken, createSession, deleteSession, recentlyIssued } from '../auth/store.js';
 import { buildMagicLinkMessage, cloudflareSend } from '../email.js';
 import { issueCsrfToken } from './csrf.js';
+import { log } from '../log/index.js';
 export function createAuthRoutes(config) {
     const send = config.send ?? cloudflareSend;
     /**
@@ -20,6 +21,10 @@ export function createAuthRoutes(config) {
         const db = requireDb(env);
         const form = await event.request.formData();
         const email = String(form.get('email') ?? '').trim().toLowerCase();
+        // `email` here is unvalidated request input logged before the allowlist check, so bound the
+        // logged value to the RFC 5321 maximum to cap an abusive record's size. A real editor's address
+        // 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();
@@ -29,12 +34,13 @@ export function createAuthRoutes(config) {
             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) => console.error('cairn: magic-link send failed', err));
+                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;
@@ -83,8 +89,10 @@ export function createAuthRoutes(config) {
         const email = await consumeToken(db, await hashToken(token), now);
         if (!email)
             throw redirect(303, '/admin/login?error=expired');
+        log.info('auth.token.confirmed', { email });
         const id = generateSessionId();
         await createSession(db, id, email, now + SESSION_TTL_MS, now);
+        log.info('auth.session.created', { email });
         const secure = event.url.protocol === 'https:';
         event.cookies.set(sessionCookieName(secure), id, {
             path: '/',
@@ -101,8 +109,10 @@ export function createAuthRoutes(config) {
         const db = requireDb(event.platform?.env ?? {});
         const name = sessionCookieName(event.url.protocol === 'https:');
         const id = event.cookies.get(name);
-        if (id)
+        if (id) {
             await deleteSession(db, id);
+            log.info('auth.session.destroyed');
+        }
         event.cookies.delete(name, { path: '/' });
         throw redirect(303, '/admin/login');
     }

package/dist/sveltekit/content-routes.js

@@ -13,6 +13,7 @@ import { listMarkdown, readRaw, commitFiles } from '../github/repo.js';
 import { cachedInstallationToken } from '../github/signing.js';
 import { emptyManifest, manifestEntryFromFile, parseManifest, serializeManifest, upsertEntry, removeEntry, inboundLinks } from '../content/manifest.js';
 import { CommitConflictError } from '../github/types.js';
+import { log } from '../log/index.js';
 import { issueCsrfToken } from './csrf.js';
 /** The signed-in editor the guard resolved, or a login redirect. Kept local to decouple event shapes. */
 function sessionOf(event) {
@@ -192,6 +193,17 @@ export function createContentRoutes(runtime, deps = {}) {
     function isConflict(err) {
         return err instanceof CommitConflictError || err?.name === 'CommitConflictError';
     }
+    /** Log a failed commit: a conflict is the expected last-writer-wins outcome, so it warns with a
+     *  reason; any other error is unexpected and logs at error with the stringified cause. The caller
+     *  still owns the redirect or rethrow, so control flow stays at the call site. */
+    function logCommitFailed(fields, err) {
+        if (isConflict(err)) {
+            log.warn('commit.failed', { ...fields, reason: 'conflict' });
+        }
+        else {
+            log.error('commit.failed', { ...fields, error: String(err) });
+        }
+    }
     /** Save an edit: validate, then commit with the session editor as author. Fails safe on 409. */
     async function saveAction(event) {
         const editor = sessionOf(event);
@@ -245,13 +257,16 @@ export function createContentRoutes(runtime, deps = {}) {
         if (absent.length) {
             return fail(400, { brokenLinks: absent, body });
         }
+        const commitFields = { concept: concept.id, id, editor: editor.email };
         try {
             await commitFiles(runtime.backend, [
                 { path, content: markdown },
                 { path: runtime.manifestPath, content: nextManifest },
             ], { message: `Update ${concept.label.toLowerCase()}: ${id}`, author: { name: editor.displayName, email: editor.email } }, token);
+            log.info('commit.succeeded', commitFields);
         }
         catch (err) {
+            logCommitFailed(commitFields, err);
             if (isConflict(err)) {
                 const message = 'This file changed since you opened it. Reload and reapply your edits.';
                 throw redirect(303, `/admin/${concept.id}/${id}?error=${encodeURIComponent(message)}${suffix}`);
@@ -278,13 +293,16 @@ export function createContentRoutes(runtime, deps = {}) {
             return fail(409, { inboundLinks: inbound, id });
         }
         const nextManifest = serializeManifest(removeEntry(manifest, concept.id, id));
+        const commitFields = { concept: concept.id, id, editor: editor.email };
         try {
             await commitFiles(runtime.backend, [
                 { path, content: null },
                 { path: runtime.manifestPath, content: nextManifest },
             ], { message: `Delete ${concept.label.toLowerCase()}: ${id}`, author: { name: editor.displayName, email: editor.email } }, token);
+            log.info('commit.succeeded', commitFields);
         }
         catch (err) {
+            logCommitFailed(commitFields, err);
             if (isConflict(err)) {
                 const message = 'This file changed since you opened it. Reload and try again.';
                 throw redirect(303, `/admin/${concept.id}/${id}?error=${encodeURIComponent(message)}`);
@@ -378,10 +396,13 @@ export function createContentRoutes(runtime, deps = {}) {
             next = upsertEntry(next, manifestEntryFromFile(linkerConcept, { path: linkerPath, raw: rewritten }));
         }
         changes.push({ path: runtime.manifestPath, content: serializeManifest(next) });
+        const commitFields = { concept: concept.id, id: newId, editor: editor.email };
         try {
             await commitFiles(runtime.backend, changes, { message: `Rename ${concept.label.toLowerCase()}: ${id} to ${newId}`, author: { name: editor.displayName, email: editor.email } }, token);
+            log.info('commit.succeeded', commitFields);
         }
         catch (err) {
+            logCommitFailed(commitFields, err);
             if (isConflict(err)) {
                 const message = 'This file changed since you opened it. Reload and try again.';
                 throw redirect(303, `/admin/${concept.id}/${id}?error=${encodeURIComponent(message)}`);

package/dist/sveltekit/guard.js

@@ -7,6 +7,7 @@ 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 { log } from '../log/index.js';
 /** The login page and the auth endpoints are public; everything else under /admin is gated. */
 function isPublicAdminPath(pathname) {
     return pathname === '/admin/login' || pathname.startsWith('/admin/auth/');
@@ -69,8 +70,10 @@ export function createAuthGuard() {
         // Rule 2 - non-admin: restore the framework's strict Origin check the consumer disabled when
         // they set checkOrigin: false to hand cairn the admin CSRF authority.
         if (!isAdminPath(pathname)) {
-            if (isUnsafeFormRequest(event.request) && !originMatches(event))
+            if (isUnsafeFormRequest(event.request) && !originMatches(event)) {
+                log.warn('guard.rejected', { reason: 'origin', path: pathname });
                 return csrfForbidden();
+            }
             return resolve(event);
         }
         // A deployed admin request over http never works: the magic-link form POST would fail the
@@ -78,11 +81,13 @@ export function createAuthGuard() {
         // runs that check. This covers the public login/auth paths too, since that is where the form
         // 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);
         }
         // 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();
         }
         if (!isPublicAdminPath(pathname)) {

package/dist/sveltekit/nav-routes.js

@@ -6,6 +6,7 @@ import { appCredentials } from '../github/credentials.js';
 import { cachedInstallationToken } from '../github/signing.js';
 import { listMarkdown, readRaw, commitFile } from '../github/repo.js';
 import { CommitConflictError } from '../github/types.js';
+import { log } from '../log/index.js';
 import { parseSiteConfig, extractMenu, validateNavTree, setMenu } from '../nav/site-config.js';
 /** The signed-in editor the guard resolved, or a login redirect. */
 function sessionOf(event) {
@@ -87,14 +88,18 @@ export function createNavRoutes(runtime, deps = {}) {
         const raw = await readRaw(runtime.backend, config.configPath, token);
         if (raw === null)
             throw error(404, 'Site config not found');
+        const commitFields = { concept: 'nav', id: 'site-config', editor: editor.email };
         try {
             await commitFile(runtime.backend, config.configPath, setMenu(raw, config.menuName, tree), { message: `Update ${config.label.toLowerCase()}`, author: { name: editor.displayName, email: editor.email } }, token);
+            log.info('commit.succeeded', commitFields);
         }
         catch (err) {
             if (isConflict(err)) {
+                log.warn('commit.failed', { ...commitFields, reason: 'conflict' });
                 const message = 'The site config changed since you opened it. Reload and reapply your edits.';
                 throw redirect(303, `/admin/nav?error=${encodeURIComponent(message)}`);
             }
+            log.error('commit.failed', { ...commitFields, error: String(err) });
             throw err;
         }
         throw redirect(303, '/admin/nav?saved=1');

package/package.json

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

package/src/lib/components/LoginPage.svelte

@@ -7,6 +7,7 @@ the allowlist, so the page never leaks membership (spec §7.1).
 <script lang="ts">
   import './cairn-admin.css';
   import { onMount } from 'svelte';
+  import MailCheckIcon from '@lucide/svelte/icons/mail-check';
   import CairnLogo from './CairnLogo.svelte';
   import CsrfField from './CsrfField.svelte';
   import { cairnFaviconHref } from './cairn-favicon.js';
@@ -22,6 +23,9 @@ the allowlist, so the page never leaks membership (spec §7.1).
   let { data, form }: Props = $props();
 
   let rootEl = $state<HTMLElement>();
+  // Lets a mistyped address go back to the form without a reload, even though the server still
+  // reports `sent`. The success copy never reveals whether the email was on the allowlist.
+  let dismissed = $state(false);
   onMount(() => {
     if (rootEl) warnIfChromeWrapped(rootEl);
   });
@@ -44,13 +48,35 @@ the allowlist, so the page never leaks membership (spec §7.1).
     </div>
 
     <h1 class="text-lg font-semibold">Sign in to {data.siteName}</h1>
-    <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 form?.sent}
-      <div role="status" class="alert alert-success text-sm">
-        Check your email for a sign-in link. It expires in 10 minutes.
+    {#if form?.sent && !dismissed}
+      <div role="status" class="mt-5 flex flex-col items-center text-center">
+        <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);"
+        >
+          <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)]">
+          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.
+          </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>
       </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 role="alert" class="alert alert-error mb-3 text-sm">That link expired. Request a new one below.</div>
       {/if}

package/src/lib/log/emit.ts

@@ -0,0 +1,42 @@
+// The engine's one logger and the single console chokepoint. Every diagnostic routes through
+// `log`; today each call writes a structured JSON object to console, which Workers Logs ingests
+// and indexes when a consumer sets observability.enabled. A future admin-extension pass adds a
+// subscriber fan-out inside this module, leaving every call site unchanged.
+import type { CairnLogEvent } from './events.js';
+
+export type LogLevel = 'info' | 'warn' | 'error';
+
+export interface LogRecord {
+  level: LogLevel;
+  event: CairnLogEvent;
+  timestamp: string;
+  [field: string]: unknown;
+}
+
+export interface Logger {
+  info(event: CairnLogEvent, fields?: Record<string, unknown>): void;
+  warn(event: CairnLogEvent, fields?: Record<string, unknown>): void;
+  error(event: CairnLogEvent, fields?: Record<string, unknown>): void;
+}
+
+const sinkByLevel: Record<LogLevel, (record: LogRecord) => void> = {
+  info: (record) => console.log(record),
+  warn: (record) => console.warn(record),
+  error: (record) => console.error(record),
+};
+
+function buildRecord(level: LogLevel, event: CairnLogEvent, fields: Record<string, unknown>): LogRecord {
+  // The envelope keys are written last, so a stray field named level/event/timestamp cannot
+  // corrupt the record shape a subscriber relies on.
+  return { ...fields, level, event, timestamp: new Date().toISOString() };
+}
+
+function emit(level: LogLevel, event: CairnLogEvent, fields: Record<string, unknown> = {}): void {
+  sinkByLevel[level](buildRecord(level, event, fields));
+}
+
+export const log: Logger = {
+  info: (event, fields) => emit('info', event, fields),
+  warn: (event, fields) => emit('warn', event, fields),
+  error: (event, fields) => emit('error', event, fields),
+};

package/src/lib/log/events.ts

@@ -0,0 +1,13 @@
+// The cairn engine's diagnostic event vocabulary. Each name is the stable `type` a future
+// admin-extension subscriber switches on, so it is public-observable API: renaming one is a
+// breaking change. See docs/reference/log-events.md, kept in step with this union.
+export type CairnLogEvent =
+  | 'auth.link.requested'
+  | 'auth.link.send_failed'
+  | 'auth.token.minted'
+  | 'auth.token.confirmed'
+  | 'auth.session.created'
+  | 'auth.session.destroyed'
+  | 'commit.succeeded'
+  | 'commit.failed'
+  | 'guard.rejected';

package/src/lib/log/index.ts

@@ -0,0 +1,3 @@
+export { log } from './emit.js';
+export type { Logger, LogLevel, LogRecord } from './emit.js';
+export type { CairnLogEvent } from './events.js';

package/src/lib/sveltekit/auth-routes.ts

@@ -15,6 +15,7 @@ import {
 import { findEditor, issueToken, consumeToken, createSession, deleteSession, recentlyIssued } from '../auth/store.js';
 import { buildMagicLinkMessage, cloudflareSend, type AuthBranding, type SendMagicLink } from '../email.js';
 import { issueCsrfToken } from './csrf.js';
+import { log } from '../log/index.js';
 import type { RequestContext } from './types.js';
 
 export interface AuthRoutesConfig {
@@ -36,6 +37,10 @@ export function createAuthRoutes(config: AuthRoutesConfig) {
     const db = requireDb(env);
     const form = await event.request.formData();
     const email = String(form.get('email') ?? '').trim().toLowerCase();
+    // `email` here is unvalidated request input logged before the allowlist check, so bound the
+    // logged value to the RFC 5321 maximum to cap an abusive record's size. A real editor's address
+    // 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) {
@@ -46,13 +51,14 @@ export function createAuthRoutes(config: AuthRoutesConfig) {
       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) => console.error('cairn: magic-link send failed', err),
+          (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.
@@ -104,9 +110,11 @@ export function createAuthRoutes(config: AuthRoutesConfig) {
     const now = Date.now();
     const email = await consumeToken(db, await hashToken(token), now);
     if (!email) throw redirect(303, '/admin/login?error=expired');
+    log.info('auth.token.confirmed', { email });
 
     const id = generateSessionId();
     await createSession(db, id, email, now + SESSION_TTL_MS, now);
+    log.info('auth.session.created', { email });
     const secure = event.url.protocol === 'https:';
     event.cookies.set(sessionCookieName(secure), id, {
       path: '/',
@@ -124,7 +132,10 @@ export function createAuthRoutes(config: AuthRoutesConfig) {
     const db = requireDb(event.platform?.env ?? {});
     const name = sessionCookieName(event.url.protocol === 'https:');
     const id = event.cookies.get(name);
-    if (id) await deleteSession(db, id);
+    if (id) {
+      await deleteSession(db, id);
+      log.info('auth.session.destroyed');
+    }
     event.cookies.delete(name, { path: '/' });
     throw redirect(303, '/admin/login');
   }

package/src/lib/sveltekit/content-routes.ts

@@ -13,6 +13,7 @@ import { listMarkdown, readRaw, commitFiles, type FileChange } from '../github/r
 import { cachedInstallationToken } from '../github/signing.js';
 import { emptyManifest, manifestEntryFromFile, parseManifest, serializeManifest, upsertEntry, removeEntry, inboundLinks, type LinkTarget, type InboundLink } from '../content/manifest.js';
 import { CommitConflictError } from '../github/types.js';
+import { log } from '../log/index.js';
 import { issueCsrfToken } from './csrf.js';
 import type { CookieJar } from './types.js';
 import type { CairnRuntime, ConceptDescriptor, FrontmatterField } from '../content/types.js';
@@ -283,6 +284,17 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
     return err instanceof CommitConflictError || (err as { name?: string } | null)?.name === 'CommitConflictError';
   }
 
+  /** Log a failed commit: a conflict is the expected last-writer-wins outcome, so it warns with a
+   *  reason; any other error is unexpected and logs at error with the stringified cause. The caller
+   *  still owns the redirect or rethrow, so control flow stays at the call site. */
+  function logCommitFailed(fields: { concept: string; id: string; editor: string }, err: unknown): void {
+    if (isConflict(err)) {
+      log.warn('commit.failed', { ...fields, reason: 'conflict' });
+    } else {
+      log.error('commit.failed', { ...fields, error: String(err) });
+    }
+  }
+
   /** Save an edit: validate, then commit with the session editor as author. Fails safe on 409. */
   async function saveAction(event: ContentEvent): Promise<ReturnType<typeof fail> | never> {
     const editor = sessionOf(event);
@@ -338,6 +350,7 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
       return fail(400, { brokenLinks: absent, body });
     }
 
+    const commitFields = { concept: concept.id, id, editor: editor.email };
     try {
       await commitFiles(
         runtime.backend,
@@ -348,7 +361,9 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
         { message: `Update ${concept.label.toLowerCase()}: ${id}`, author: { name: editor.displayName, email: editor.email } },
         token,
       );
+      log.info('commit.succeeded', commitFields);
     } catch (err) {
+      logCommitFailed(commitFields, err);
       if (isConflict(err)) {
         const message = 'This file changed since you opened it. Reload and reapply your edits.';
         throw redirect(303, `/admin/${concept.id}/${id}?error=${encodeURIComponent(message)}${suffix}`);
@@ -383,6 +398,7 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
     }
 
     const nextManifest = serializeManifest(removeEntry(manifest, concept.id, id));
+    const commitFields = { concept: concept.id, id, editor: editor.email };
     try {
       await commitFiles(
         runtime.backend,
@@ -393,7 +409,9 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
         { message: `Delete ${concept.label.toLowerCase()}: ${id}`, author: { name: editor.displayName, email: editor.email } },
         token,
       );
+      log.info('commit.succeeded', commitFields);
     } catch (err) {
+      logCommitFailed(commitFields, err);
       if (isConflict(err)) {
         const message = 'This file changed since you opened it. Reload and try again.';
         throw redirect(303, `/admin/${concept.id}/${id}?error=${encodeURIComponent(message)}`);
@@ -492,6 +510,7 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
 
     changes.push({ path: runtime.manifestPath, content: serializeManifest(next) });
 
+    const commitFields = { concept: concept.id, id: newId, editor: editor.email };
     try {
       await commitFiles(
         runtime.backend,
@@ -499,7 +518,9 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
         { message: `Rename ${concept.label.toLowerCase()}: ${id} to ${newId}`, author: { name: editor.displayName, email: editor.email } },
         token,
       );
+      log.info('commit.succeeded', commitFields);
     } catch (err) {
+      logCommitFailed(commitFields, err);
       if (isConflict(err)) {
         const message = 'This file changed since you opened it. Reload and try again.';
         throw redirect(303, `/admin/${concept.id}/${id}?error=${encodeURIComponent(message)}`);

package/src/lib/sveltekit/guard.ts

@@ -7,6 +7,7 @@ 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 { log } from '../log/index.js';
 import type { Editor } from '../auth/types.js';
 import type { HandleInput, RequestContext } from './types.js';
 
@@ -83,7 +84,10 @@ export function createAuthGuard() {
     // Rule 2 - non-admin: restore the framework's strict Origin check the consumer disabled when
     // they set checkOrigin: false to hand cairn the admin CSRF authority.
     if (!isAdminPath(pathname)) {
-      if (isUnsafeFormRequest(event.request) && !originMatches(event)) return csrfForbidden();
+      if (isUnsafeFormRequest(event.request) && !originMatches(event)) {
+        log.warn('guard.rejected', { reason: 'origin', path: pathname });
+        return csrfForbidden();
+      }
       return resolve(event);
     }
 
@@ -92,12 +96,14 @@ export function createAuthGuard() {
     // runs that check. This covers the public login/auth paths too, since that is where the form
     // 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);
     }
 
     // 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();
     }
 

package/src/lib/sveltekit/nav-routes.ts

@@ -6,6 +6,7 @@ import { appCredentials, type GithubKeyEnv } from '../github/credentials.js';
 import { cachedInstallationToken } from '../github/signing.js';
 import { listMarkdown, readRaw, commitFile } from '../github/repo.js';
 import { CommitConflictError } from '../github/types.js';
+import { log } from '../log/index.js';
 import { parseSiteConfig, extractMenu, validateNavTree, setMenu, type NavNode } from '../nav/site-config.js';
 import type { CairnRuntime } from '../content/types.js';
 import type { ContentEvent } from './content-routes.js';
@@ -116,6 +117,7 @@ export function createNavRoutes(runtime: CairnRuntime, deps: NavRoutesDeps = {})
     const raw = await readRaw(runtime.backend, config.configPath, token);
     if (raw === null) throw error(404, 'Site config not found');
 
+    const commitFields = { concept: 'nav', id: 'site-config', editor: editor.email };
     try {
       await commitFile(
         runtime.backend,
@@ -124,11 +126,14 @@ export function createNavRoutes(runtime: CairnRuntime, deps: NavRoutesDeps = {})
         { message: `Update ${config.label.toLowerCase()}`, author: { name: editor.displayName, email: editor.email } },
         token,
       );
+      log.info('commit.succeeded', commitFields);
     } catch (err) {
       if (isConflict(err)) {
+        log.warn('commit.failed', { ...commitFields, reason: 'conflict' });
         const message = 'The site config changed since you opened it. Reload and reapply your edits.';
         throw redirect(303, `/admin/nav?error=${encodeURIComponent(message)}`);
       }
+      log.error('commit.failed', { ...commitFields, error: String(err) });
       throw err;
     }