@glw907/cairn-cms 0.3.1 → 0.5.0

package/dist/sveltekit/index.js

@@ -1,25 +1,23 @@
-// cairn-core: the SvelteKit route server logic, extracted so each site's `admin/**` route
-// files are thin shims (`export const load = (event) => editLoad(event, cairn)`).
+// cairn-core: the SvelteKit content-route server logic, extracted so each site's `admin/**`
+// route files are thin shims (`export const load = (event) => editLoad(event, cairn)`).
 //
 // SvelteKit's filesystem routing requires the route *files* to live in each site's
-// `src/routes/`, but their bodies are identical across sites — only the adapter differs.
+// `src/routes/`, but their bodies are identical across sites. Only the adapter differs.
 // These functions take the SvelteKit event (typed structurally, to avoid depending on the
 // site-generated `App.*` ambient types) plus the site `CairnAdapter`, and throw
-// `redirect`/`error` from `@sveltejs/kit`. That `@sveltejs/kit` is a peer dependency so the
-// thrown objects share class identity with the host's runtime (else the redirect 500s).
+// `redirect`/`error` from `@sveltejs/kit` (a peer dependency, so the thrown objects share
+// class identity with the host's runtime; otherwise the redirect 500s). Auth/session/manage-editors
+// logic lives under `@glw907/cairn-cms/auth`; this module is content-only (list/edit/save).
 import { redirect, error } from '@sveltejs/kit';
 import matter from 'gray-matter';
-import { createMagicLink, redeemMagicToken, createSession, lookupEditor, listEditors, setEditor, removeEditor, SESSION_COOKIE, SESSION_MAX_AGE, } from '../auth';
-import { sendMagicLink } from '../email';
-import { listMarkdown, readRaw, commitFile, installationToken } from '../github';
+import { listMarkdown, readRaw, commitFile, installationToken, signingSelfTest, CommitConflictError, } from '../github';
 import { serializeMarkdown } from '../content';
 import { findCollection, frontmatterFromForm } from '../adapter';
-const EMAIL_RE = /^[^@\s]+@[^@\s]+\.[^@\s]+$/;
 /**
  * Mint a GitHub App installation token for *reads* when the App is configured, else undefined
  * (reads then fall back to anonymous). Authenticated reads get the 5000/hr limit; anonymous
  * reads share GitHub's 60/hr-per-IP budget across Cloudflare's egress IPs, so they 403 in prod.
- * A mint failure degrades gracefully to anonymous rather than 500ing — unlike the commit path,
+ * A mint failure degrades gracefully to anonymous rather than 500ing. Unlike the commit path,
  * where a missing App is fatal, a read can still succeed unauthenticated.
  */
 async function readToken(env) {
@@ -40,13 +38,13 @@ async function readToken(env) {
 }
 /**
  * Branding + session for every admin page. `siteName` flows from the adapter without pulling
- * its plugin graph into client bundles — the import stays server-side in the layout load.
+ * its plugin graph into client bundles; the import stays server-side in the layout load.
  * `pathname` lets the shared shell highlight the active nav item without a `$app/*` import
  * (those kit virtual modules have no types outside a kit app, so they can't live in the
  * package); reading `event.url` here also opts the layout load into rerunning on navigation.
  */
 export function adminLayoutLoad(event, adapter) {
-    return { editor: event.locals.editor, siteName: adapter.siteName, pathname: event.url.pathname };
+    return { user: event.locals.user, siteName: adapter.siteName, pathname: event.url.pathname };
 }
 /** List every collection's markdown files. A failed listing degrades to an inline error. */
 export async function adminListLoad(event, adapter) {
@@ -62,12 +60,6 @@ export async function adminListLoad(event, adapter) {
     }));
     return { collections };
 }
-export function loginLoad(event) {
-    return {
-        sent: event.url.searchParams.get('sent') === '1',
-        error: event.url.searchParams.get('error'),
-    };
-}
 export async function editLoad(event, adapter) {
     const collection = findCollection(adapter, event.params.type);
     if (!collection)
@@ -93,70 +85,10 @@ export async function editLoad(event, adapter) {
         error: event.url.searchParams.get('error'),
     };
 }
-// ── /admin/auth/request (POST) ──────────────────────────────────────────────
-export async function authRequest(event, adapter) {
-    const env = event.platform?.env;
-    if (!env?.AUTH_KV || !env.MAGIC_LINK_SECRET || !env.EMAIL) {
-        throw redirect(303, '/admin/login?error=config');
-    }
-    const form = await event.request.formData();
-    const email = String(form.get('email') ?? '').trim().toLowerCase();
-    if (!EMAIL_RE.test(email)) {
-        throw redirect(303, '/admin/login?error=invalid');
-    }
-    const editor = await lookupEditor(email, env.AUTH_KV);
-    if (!editor) {
-        throw redirect(303, '/admin/login?error=denied');
-    }
-    const token = await createMagicLink(email, env.MAGIC_LINK_SECRET, env.AUTH_KV);
-    // PUBLIC_ORIGIN overrides url.origin for local dev (where wrangler's custom-domain
-    // route makes url.origin the production host); unset in prod → url.origin is correct.
-    const origin = env.PUBLIC_ORIGIN || event.url.origin;
-    const link = `${origin}/admin/auth/callback?token=${encodeURIComponent(token)}`;
-    try {
-        await sendMagicLink(env.EMAIL, email, link, adapter.siteName, adapter.sender);
-    }
-    catch (err) {
-        console.error('magic-link send failed:', err);
-        throw redirect(303, '/admin/login?error=config');
-    }
-    throw redirect(303, '/admin/login?sent=1');
-}
-// ── /admin/auth/callback (GET) ──────────────────────────────────────────────
-export async function authCallback(event) {
-    const env = event.platform?.env;
-    if (!env?.AUTH_KV || !env.MAGIC_LINK_SECRET || !env.SESSION_SECRET) {
-        throw redirect(303, '/admin/login?error=config');
-    }
-    const token = event.url.searchParams.get('token') ?? '';
-    const email = await redeemMagicToken(token, env.MAGIC_LINK_SECRET, env.AUTH_KV);
-    if (!email) {
-        throw redirect(303, '/admin/login?error=expired');
-    }
-    // Re-check the allowlist at redemption — membership may have changed since issue.
-    const editor = await lookupEditor(email, env.AUTH_KV);
-    if (!editor) {
-        throw redirect(303, '/admin/login?error=denied');
-    }
-    const session = await createSession(editor, env.SESSION_SECRET);
-    event.cookies.set(SESSION_COOKIE, session, {
-        path: '/',
-        httpOnly: true,
-        secure: event.url.protocol === 'https:',
-        sameSite: 'lax',
-        maxAge: SESSION_MAX_AGE,
-    });
-    throw redirect(303, '/admin');
-}
-// ── /admin/auth/logout (POST) ───────────────────────────────────────────────
-export function logout(event) {
-    event.cookies.delete(SESSION_COOKIE, { path: '/' });
-    throw redirect(303, '/admin/login');
-}
 // ── /admin/save (POST) ──────────────────────────────────────────────────────
 export async function saveCommit(event, adapter) {
-    const editor = event.locals.editor;
-    if (!editor)
+    const user = event.locals.user;
+    if (!user)
         throw error(401, 'Not signed in');
     const env = event.platform?.env;
     if (!env?.GITHUB_APP_ID || !env.GITHUB_APP_INSTALLATION_ID || !env.GITHUB_APP_PRIVATE_KEY_B64) {
@@ -185,82 +117,33 @@ export async function saveCommit(event, adapter) {
         installationId: env.GITHUB_APP_INSTALLATION_ID,
         privateKeyB64: env.GITHUB_APP_PRIVATE_KEY_B64,
     });
-    await commitFile(adapter.backend, `${collection.dir}/${id}.md`, markdown, { message: `Update ${collection.label.toLowerCase()}: ${id}`, author: { name: editor.name, email: editor.email } }, token);
+    try {
+        await commitFile(adapter.backend, `${collection.dir}/${id}.md`, markdown, { message: `Update ${collection.label.toLowerCase()}: ${id}`, author: { name: user.name, email: user.email } }, token);
+    }
+    catch (err) {
+        // Concurrent-edit 409 (C3): fail safe. Bounce back with a reload prompt; the editor reloads
+        // the current version and reapplies. Any other error is unexpected, so rethrow.
+        if (err instanceof CommitConflictError) {
+            const message = 'This file changed since you opened it. Reload and reapply your edits.';
+            throw redirect(303, `/admin/edit/${type}/${id}?error=${encodeURIComponent(message)}`);
+        }
+        throw err;
+    }
     throw redirect(303, `/admin/edit/${type}/${id}?saved=1`);
 }
-// ── /admin/admins (owner-gated editor management) ────────────────────────────
 /**
- * The privilege-escalation gate for the manage-admins surface: only `owner`s may load it or
- * run its actions. Returns the acting owner (so callers can guard self-targeted mutations).
+ * Deploy-time health check (M2): signs a dummy App JWT to prove the GitHub App key loads and
+ * the PKCS#1→PKCS#8 conversion still works, before an editor hits it on save. Behind the
+ * `/admin` guard (signed-in editors only); returns ok/fail with no secret in the body.
  */
-function requireOwner(event) {
-    const editor = event.locals.editor;
-    if (!editor)
-        throw error(401, 'Not signed in');
-    if (editor.role !== 'owner')
-        throw error(403, 'Owner access required');
-    return editor;
-}
-/** Resolve AUTH_KV or fail loudly — the management surface is useless without it. */
-function ownerKv(event) {
-    const kv = event.platform?.env?.AUTH_KV;
-    if (!kv)
-        throw error(500, 'Editor allowlist is not configured');
-    return kv;
-}
-/** List the allowlist for the manage-admins page. Owner-only. */
-export async function adminsLoad(event) {
-    const owner = requireOwner(event);
-    const admins = await listEditors(ownerKv(event));
-    return {
-        admins,
-        self: owner.email,
-        saved: event.url.searchParams.get('saved') === '1',
-        error: event.url.searchParams.get('error'),
-    };
-}
-function parseRole(value) {
-    return value === 'owner' ? 'owner' : 'editor';
-}
-/** Add (or update) an allowlist entry. Owner-only. */
-export async function addAdmin(event) {
-    requireOwner(event);
-    const kv = ownerKv(event);
-    const form = await event.request.formData();
-    const email = String(form.get('email') ?? '').trim().toLowerCase();
-    const name = String(form.get('name') ?? '').trim();
-    if (!EMAIL_RE.test(email) || !name) {
-        throw redirect(303, `/admin/admins?error=${encodeURIComponent('Enter a valid email and name')}`);
-    }
-    await setEditor(email, name, parseRole(form.get('role')), kv);
-    throw redirect(303, '/admin/admins?saved=1');
-}
-/** Remove an allowlist entry. Owner-only; owners can't remove themselves (anti-lockout). */
-export async function removeAdmin(event) {
-    const owner = requireOwner(event);
-    const kv = ownerKv(event);
-    const form = await event.request.formData();
-    const email = String(form.get('email') ?? '').trim().toLowerCase();
-    if (email === owner.email) {
-        throw redirect(303, `/admin/admins?error=${encodeURIComponent("You can't remove yourself")}`);
-    }
-    await removeEditor(email, kv);
-    throw redirect(303, '/admin/admins?saved=1');
-}
-/** Change an editor's role. Owner-only; owners can't demote themselves (anti-lockout). */
-export async function setAdminRole(event) {
-    const owner = requireOwner(event);
-    const kv = ownerKv(event);
-    const form = await event.request.formData();
-    const email = String(form.get('email') ?? '').trim().toLowerCase();
-    const role = parseRole(form.get('role'));
-    if (email === owner.email && role !== 'owner') {
-        throw redirect(303, `/admin/admins?error=${encodeURIComponent("You can't demote yourself")}`);
+export async function healthLoad(event) {
+    const env = event.platform?.env;
+    let githubAppSigning;
+    if (env?.GITHUB_APP_ID && env.GITHUB_APP_PRIVATE_KEY_B64) {
+        githubAppSigning = await signingSelfTest(env.GITHUB_APP_ID, env.GITHUB_APP_PRIVATE_KEY_B64);
     }
-    const existing = await lookupEditor(email, kv);
-    if (!existing) {
-        throw redirect(303, `/admin/admins?error=${encodeURIComponent('No such editor')}`);
+    else {
+        githubAppSigning = { ok: false, detail: 'GitHub App not configured' };
     }
-    await setEditor(email, existing.name, role, kv);
-    throw redirect(303, '/admin/admins?saved=1');
+    return { ok: githubAppSigning.ok, checks: { githubAppSigning } };
 }

package/dist/utils.d.ts

@@ -1,3 +1,3 @@
-/** Encode bytes as unpadded base64url (RFC 4648 §5) — the JWT/token wire format. */
+/** Encode bytes as unpadded base64url (RFC 4648 §5), the JWT/token wire format. */
 export declare function bytesToB64url(bytes: Uint8Array): string;
 //# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/lib/utils.ts"],"names":[],"mappings":"AAOA,oFAAoF;AACpF,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAGvD"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/lib/utils.ts"],"names":[],"mappings":"AAOA,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAGvD"}

package/dist/utils.js

@@ -1,10 +1,10 @@
 // cairn-core: internal encoding helpers shared across modules.
 //
-// Deliberately NOT re-exported from index.ts — these are implementation details of the
+// Deliberately NOT re-exported from index.ts. These are implementation details of the
 // auth/github crypto, not part of the public API (auth.ts signs tokens, github.ts builds
 // the App JWT; both need base64url). Keeping them here stops bytesToB64url leaking through
 // the `export *` barrel.
-/** Encode bytes as unpadded base64url (RFC 4648 §5) — the JWT/token wire format. */
+/** Encode bytes as unpadded base64url (RFC 4648 §5), the JWT/token wire format. */
 export function bytesToB64url(bytes) {
     const binary = Array.from(bytes, (b) => String.fromCharCode(b)).join('');
     return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glw907/cairn-cms",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Embedded, magic-link, GitHub-committing CMS for SvelteKit/Cloudflare sites.",
   "type": "module",
   "license": "MIT",
@@ -9,13 +9,22 @@
     "type": "git",
     "url": "git+https://github.com/glw907/cairn-cms.git"
   },
-  "keywords": ["cms", "sveltekit", "cloudflare", "github", "magic-link", "markdown"],
+  "keywords": [
+    "cms",
+    "sveltekit",
+    "cloudflare",
+    "github",
+    "magic-link",
+    "markdown"
+  ],
   "scripts": {
     "package": "svelte-package",
     "package:watch": "svelte-package --watch",
     "prepublishOnly": "svelte-package",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "auth:schema": "better-auth generate --config auth.cli.ts --output src/lib/auth/schema.ts -y",
+    "auth:sql": "drizzle-kit generate"
   },
   "exports": {
     ".": {
@@ -33,6 +42,11 @@
       "svelte": "./src/lib/components/index.ts",
       "default": "./src/lib/components/index.ts"
     },
+    "./auth": {
+      "types": "./src/lib/auth/index.ts",
+      "svelte": "./src/lib/auth/index.ts",
+      "default": "./src/lib/auth/index.ts"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -52,28 +66,56 @@
         "svelte": "./dist/components/index.js",
         "default": "./dist/components/index.js"
       },
+      "./auth": {
+        "types": "./dist/auth/index.d.ts",
+        "svelte": "./dist/auth/index.js",
+        "default": "./dist/auth/index.js"
+      },
       "./package.json": "./package.json"
     }
   },
-  "files": ["dist", "src/lib"],
+  "files": [
+    "dist",
+    "src/lib"
+  ],
   "peerDependencies": {
     "@sveltejs/kit": "^2",
+    "better-auth": "^1.6",
     "carta-md": "^4.11",
+    "drizzle-orm": ">=0.40 <1",
     "svelte": "^5.0.0"
   },
   "dependencies": {
-    "gray-matter": "^4"
+    "@types/hast": "^3.0.4",
+    "@types/mdast": "^4.0.4",
+    "gray-matter": "^4",
+    "hastscript": "^9.0.1",
+    "mdast-util-directive": "^3.1.0",
+    "rehype-raw": "^7.0.0",
+    "rehype-slug": "^6.0.0",
+    "rehype-stringify": "^10.0.1",
+    "remark-directive": "^4.0.0",
+    "remark-gfm": "^4",
+    "remark-parse": "^11.0.0",
+    "remark-rehype": "^11.1.2",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.1.0"
   },
   "devDependencies": {
+    "@better-auth/cli": "^1.4.21",
     "@cloudflare/workers-types": "^4.20260405.1",
     "@sveltejs/kit": "^2",
     "@sveltejs/package": "^2",
     "@sveltejs/vite-plugin-svelte": "^7",
+    "@types/better-sqlite3": "^7.6.13",
+    "better-auth": "^1.6.11",
+    "better-sqlite3": "^12.10.0",
     "carta-md": "^4.11",
+    "drizzle-kit": "^0.31.10",
+    "drizzle-orm": "^0.45.2",
     "svelte": "^5",
     "svelte-check": "^4",
     "typescript": "^6.0.3",
-    "unified": "^11.0.5",
     "vitest": "^4.1.6"
   }
 }

package/src/lib/adapter.ts

@@ -3,11 +3,12 @@
 // This is the single seam that lets one admin surface serve different designs. A site
 // supplies a `CairnAdapter` (see `src/lib/cairn.config.ts`) describing its backend repo,
 // its editable collections (folder + form fields + frontmatter validator), and its preview
-// plugin set. cairn-core never hard-codes a collection, tag, or directive — it reads them
+// plugin set. cairn-core never hard-codes a collection, tag, or directive; it reads them
 // from the adapter. Field descriptors are plain data so a load function can hand them to
-// the editor form across the server→client boundary.
+// the editor form across the server-to-client boundary.
 import type { PreviewPlugins } from './carta';
 import type { RepoRef } from './github';
+import type { ComponentRegistry } from './render';
 
 interface FieldBase {
   /** Frontmatter key and form input name. */
@@ -63,13 +64,21 @@ export interface CairnCollection {
 export interface CairnAdapter {
   /** Branding + magic-link email copy. */
   siteName: string;
-  /** From: address for magic-link email — a domain-authenticated sender. */
+  /** From: address for magic-link email (must be a domain-authenticated sender). */
   sender: string;
   /** The repository the admin reads content from and commits to. */
   backend: RepoRef;
   /** Site plugin set for the Carta preview (parity with the live render). */
   preview: PreviewPlugins;
   collections: CairnCollection[];
+  /**
+   * The site's component registry: the single declaration of its directive
+   * components (R10a). Rendering parity already flows through `preview`; this
+   * exposes the same registry so the editor's insert-component palette can read
+   * `registry.defs`. Optional: a site with no rich components (e.g. 907.life) may
+   * omit it or supply an empty registry.
+   */
+  registry?: ComponentRegistry;
 }
 
 /** Look up a collection by its route segment, or undefined if the segment is unknown. */

package/src/lib/auth/admins.ts

@@ -0,0 +1,106 @@
+// cairn-core: owner-gated editor management, on better-auth's admin API. The `user` table IS
+// the allowlist (disableSignUp ⇒ only listed emails can sign in), so add/remove editor = create/
+// remove user; role flips go through the admin plugin's access-control roles (owner/editor).
+// These run as SvelteKit form actions; each verifies the acting user is an owner first.
+import { redirect, error } from '@sveltejs/kit';
+import type { Auth } from './config';
+import type { CairnUser } from './guard';
+
+export interface AdminsData {
+  admins: CairnUser[];
+  /** Acting owner's email, so the UI can disable self-targeted remove/demote. */
+  self: string;
+  saved: boolean;
+  error: string | null;
+}
+
+const EMAIL_RE = /^[^@\s]+@[^@\s]+\.[^@\s]+$/;
+
+/**
+ * The privilege-escalation gate. better-auth's admin API also enforces this server-side (only
+ * `owner` holds the admin statements), but checking `locals.user` here gives clean redirect/403
+ * UX and lets the mutations guard self-lockout before calling the API. Returns the acting owner.
+ */
+export function requireOwner(user: CairnUser | null): CairnUser {
+  if (!user) throw error(401, 'Not signed in');
+  if (user.role !== 'owner') throw error(403, 'Owner access required');
+  return user;
+}
+
+type Ev = { locals: { auth: Auth; user: CairnUser | null }; request: Request; url: URL };
+
+function asCairnUser(u: { id: string; email: string; name: string; role?: string | null }): CairnUser {
+  return { id: u.id, email: u.email, name: u.name, role: u.role === 'owner' ? 'owner' : 'editor' };
+}
+
+/** Find an editor by exact (lowercased) email, or undefined. */
+async function findByEmail(event: Ev, email: string): Promise<CairnUser | undefined> {
+  const res = await event.locals.auth.api.listUsers({
+    query: { searchValue: email, searchField: 'email', limit: 100 },
+    headers: event.request.headers,
+  });
+  const match = (res.users ?? []).find((u) => u.email.toLowerCase() === email);
+  return match ? asCairnUser(match) : undefined;
+}
+
+/** List the allowlist for the manage-editors page. Owner-only. */
+export async function adminsLoad(event: Ev): Promise<AdminsData> {
+  const owner = requireOwner(event.locals.user);
+  const res = await event.locals.auth.api.listUsers({
+    query: { limit: 200 },
+    headers: event.request.headers,
+  });
+  const admins = (res.users ?? []).map(asCairnUser).sort((a, b) => a.email.localeCompare(b.email));
+  return {
+    admins,
+    self: owner.email,
+    saved: event.url.searchParams.get('saved') === '1',
+    error: event.url.searchParams.get('error'),
+  };
+}
+
+/** Add an editor (create the user). Owner-only. */
+export async function addAdmin(event: Ev): Promise<never> {
+  requireOwner(event.locals.user);
+  const form = await event.request.formData();
+  const email = String(form.get('email') ?? '').trim().toLowerCase();
+  const name = String(form.get('name') ?? '').trim();
+  const role = form.get('role') === 'owner' ? 'owner' : 'editor';
+  if (!EMAIL_RE.test(email) || !name) {
+    throw redirect(303, `/admin/admins?error=${encodeURIComponent('Enter a valid email and name')}`);
+  }
+  // No password: a magic-link-only user (no credential account), per better-auth's createUser.
+  await event.locals.auth.api.createUser({ body: { email, name, role }, headers: event.request.headers });
+  throw redirect(303, '/admin/admins?saved=1');
+}
+
+/** Remove an editor (delete the user). Owner-only; owners can't remove themselves (anti-lockout). */
+export async function removeAdmin(event: Ev): Promise<never> {
+  const owner = requireOwner(event.locals.user);
+  const form = await event.request.formData();
+  const email = String(form.get('email') ?? '').trim().toLowerCase();
+  if (email === owner.email) {
+    throw redirect(303, `/admin/admins?error=${encodeURIComponent("You can't remove yourself")}`);
+  }
+  const target = await findByEmail(event, email);
+  if (!target) throw redirect(303, `/admin/admins?error=${encodeURIComponent('No such editor')}`);
+  await event.locals.auth.api.removeUser({ body: { userId: target.id }, headers: event.request.headers });
+  throw redirect(303, '/admin/admins?saved=1');
+}
+
+/** Change an editor's role. Owner-only; owners can't demote themselves (anti-lockout). */
+export async function setAdminRole(event: Ev): Promise<never> {
+  const owner = requireOwner(event.locals.user);
+  const form = await event.request.formData();
+  const email = String(form.get('email') ?? '').trim().toLowerCase();
+  const role = form.get('role') === 'owner' ? 'owner' : 'editor';
+  if (email === owner.email && role !== 'owner') {
+    throw redirect(303, `/admin/admins?error=${encodeURIComponent("You can't demote yourself")}`);
+  }
+  const target = await findByEmail(event, email);
+  if (!target) throw redirect(303, `/admin/admins?error=${encodeURIComponent('No such editor')}`);
+  await event.locals.auth.api.setRole({ body: { userId: target.id, role }, headers: event.request.headers });
+  // M3: revoke a demoted editor's live sessions so the privilege drop takes effect immediately.
+  await event.locals.auth.api.revokeUserSessions({ body: { userId: target.id }, headers: event.request.headers });
+  throw redirect(303, '/admin/admins?saved=1');
+}

package/src/lib/auth/config.ts

@@ -0,0 +1,108 @@
+// cairn-core: the better-auth instance. Auth is engine code (engine-fat rule), so the whole
+// config lives here: Drizzle/D1 adapter, magic-link (POST-confirm-shaped send), admin roles.
+// Instantiated PER REQUEST in hooks.server.ts (the D1 binding is request-scoped); the factory
+// is cheap (no I/O at construction).
+import { betterAuth } from 'better-auth';
+import { drizzleAdapter } from 'better-auth/adapters/drizzle';
+import { drizzle } from 'drizzle-orm/d1';
+import { magicLink, admin } from 'better-auth/plugins';
+import { createAccessControl } from 'better-auth/plugins/access';
+import { defaultStatements } from 'better-auth/plugins/admin/access';
+import type { D1Database } from '@cloudflare/workers-types';
+import { sendMagicLink, type EmailSender } from '../email';
+import * as schema from './schema';
+
+// Two-tier roles on the admin plugin's access-control system: `owner` holds every admin
+// statement (manage editors, revoke sessions); `editor` holds none (content-only). `adminRoles`
+// must name a role defined here, so owner (not the plugin's built-in `admin`) is the gate.
+const ac = createAccessControl(defaultStatements);
+const owner = ac.newRole(defaultStatements);
+const editor = ac.newRole({});
+
+/** Worker bindings + vars the auth layer reads (a structural subset of `Platform.env`). */
+export interface AuthEnv {
+  AUTH_DB?: D1Database;
+  AUTH_SECRET?: string;
+  /** Canonical origin; `BETTER_AUTH_URL` is accepted as a legacy alias. */
+  PUBLIC_ORIGIN?: string;
+  /** Legacy alias for `PUBLIC_ORIGIN`; `PUBLIC_ORIGIN` takes precedence when both are set. */
+  BETTER_AUTH_URL?: string;
+  EMAIL?: EmailSender;
+}
+
+/** Branding the magic-link email needs; threaded from the site adapter via hooks. */
+export interface AuthBranding {
+  siteName: string;
+  /** The `From:` address used when sending magic-link emails. */
+  sender: string;
+}
+
+/** The drizzle adapter result `betterAuth` consumes (same provider/schema everywhere). */
+type DrizzleDb = Parameters<typeof drizzleAdapter>[0];
+
+/**
+ * The shared better-auth config. Kept separate from `createAuth` so the test harness can run
+ * the EXACT plugin set (allowlist semantics, expiry, POST-confirm send) over an in-memory
+ * SQLite instead of D1. `disableSignUp:true` makes the `user` table the editor allowlist:
+ * magic-link never auto-creates, so the only way in is the owner-gated admin `createUser`
+ * (see auth/admins.ts). `adminRoles:['owner']` lets owners (not the default `admin` role)
+ * drive the admin API. Tokens are stored hashed and consumed atomically on first verify
+ * (better-auth GHSA-hc7v-rggr-4hvx), single-use by construction (C1).
+ */
+export function buildAuth(opts: {
+  database: DrizzleDb;
+  baseURL: string;
+  secret: string | undefined;
+  branding: AuthBranding;
+  sendLink: (email: string, token: string) => Promise<void>;
+}) {
+  return betterAuth({
+    appName: opts.branding.siteName,
+    secret: opts.secret,
+    baseURL: opts.baseURL,
+    trustedOrigins: [opts.baseURL],
+    database: opts.database,
+    plugins: [
+      magicLink({
+        disableSignUp: true,
+        expiresIn: 600,
+        storeToken: 'hashed',
+        sendMagicLink: async ({ email, token }, ctx) => {
+          // Allowlist gate: better-auth always fires this callback (even for unknown emails, to
+          // avoid enumeration) and only blocks user creation at verify. So gate the actual send
+          // here. Never email a non-editor. The login UI shows neutral copy either way, so this
+          // leaks nothing; it just stops strangers receiving a dead link.
+          const existing = await ctx?.context.internalAdapter.findUserByEmail(email);
+          if (!existing?.user) return;
+          await opts.sendLink(email, token);
+        },
+      }),
+      admin({ ac, roles: { owner, editor }, defaultRole: 'editor', adminRoles: ['owner'] }),
+    ],
+  });
+}
+
+/**
+ * Build the per-request better-auth instance over the site's D1 binding. The magic-link email
+ * points at OUR confirm page carrying only the token; consumption happens when the user clicks
+ * "Confirm sign-in" there (a POST), never on a scanner GET (C2 / POST-confirm). The origin is
+ * config-derived (`PUBLIC_ORIGIN`/`BETTER_AUTH_URL`), never request-derived (H3).
+ */
+export function createAuth(env: AuthEnv, branding: AuthBranding) {
+  if (!env.AUTH_DB) throw new Error('AUTH_DB (D1) binding is required');
+  const origin = env.PUBLIC_ORIGIN || env.BETTER_AUTH_URL || 'http://localhost';
+  const db = drizzle(env.AUTH_DB, { schema });
+  return buildAuth({
+    database: drizzleAdapter(db, { provider: 'sqlite', schema }),
+    baseURL: origin,
+    secret: env.AUTH_SECRET,
+    branding,
+    sendLink: async (email, token) => {
+      if (!env.EMAIL) throw new Error('EMAIL binding is required to send magic links');
+      const link = `${origin}/admin/auth/confirm?token=${encodeURIComponent(token)}`;
+      await sendMagicLink(env.EMAIL, email, link, branding.siteName, branding.sender);
+    },
+  });
+}
+
+export type Auth = ReturnType<typeof createAuth>;