@glw907/cairn-cms 0.3.0 → 0.4.0

package/dist/sveltekit/index.js

@@ -1,20 +1,41 @@
-// 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.
 // 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 — else 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 { 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,
+ * where a missing App is fatal, a read can still succeed unauthenticated.
+ */
+async function readToken(env) {
+    if (!env?.GITHUB_APP_ID || !env.GITHUB_APP_INSTALLATION_ID || !env.GITHUB_APP_PRIVATE_KEY_B64) {
+        return undefined;
+    }
+    try {
+        return await installationToken({
+            appId: env.GITHUB_APP_ID,
+            installationId: env.GITHUB_APP_INSTALLATION_ID,
+            privateKeyB64: env.GITHUB_APP_PRIVATE_KEY_B64,
+        });
+    }
+    catch (err) {
+        console.error('read token mint failed; falling back to anonymous read:', err);
+        return undefined;
+    }
+}
 /**
  * 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.
@@ -23,13 +44,14 @@ const EMAIL_RE = /^[^@\s]+@[^@\s]+\.[^@\s]+$/;
  * 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(adapter) {
+export async function adminListLoad(event, adapter) {
+    const token = await readToken(event.platform?.env);
     const collections = await Promise.all(adapter.collections.map(async ({ type, label, dir }) => {
         try {
-            return { type, label, files: await listMarkdown(adapter.backend, dir) };
+            return { type, label, files: await listMarkdown(adapter.backend, dir, token) };
         }
         catch (err) {
             // A failed listing (rate limit, network) shouldn't 500 the whole admin.
@@ -38,19 +60,13 @@ export async function adminListLoad(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)
         throw error(404, 'Unknown collection');
-    // Anonymous read — repos are public; the GitHub App token is commit-only (see saveCommit).
+    const token = await readToken(event.platform?.env);
     const path = `${collection.dir}/${event.params.id}.md`;
-    const raw = await readRaw(adapter.backend, path);
+    const raw = await readRaw(adapter.backend, path, token);
     if (raw === null)
         throw error(404, 'Content not found');
     // Split frontmatter from body server-side; the editor form binds to the frontmatter and
@@ -69,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) {
@@ -161,82 +117,6 @@ 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);
+    await commitFile(adapter.backend, `${collection.dir}/${id}.md`, markdown, { message: `Update ${collection.label.toLowerCase()}: ${id}`, author: { name: user.name, email: user.email } }, token);
     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).
- */
-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")}`);
-    }
-    const existing = await lookupEditor(email, kv);
-    if (!existing) {
-        throw redirect(303, `/admin/admins?error=${encodeURIComponent('No such editor')}`);
-    }
-    await setEditor(email, existing.name, role, kv);
-    throw redirect(303, '/admin/admins?saved=1');
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glw907/cairn-cms",
-  "version": "0.3.0",
+  "version": "0.4.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,24 +66,40 @@
         "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"
   },
   "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",

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 — Drizzle/D1 adapter, magic-link (POST-confirm-shaped send), admin roles — lives here.
+// 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 — the 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>;

package/src/lib/auth/guard.ts

@@ -0,0 +1,60 @@
+// cairn-core: server-side auth helpers the site route shims delegate to. Each takes the
+// SvelteKit event (typed structurally, so the package never depends on a site's generated
+// `App.*` ambient types) plus the per-request `Auth` from `locals`.
+import { redirect } from '@sveltejs/kit';
+import type { Auth } from './config';
+
+/** The session shape the whole admin reads — layout, guards, content fns, manage-editors. */
+export interface CairnUser {
+  id: string;
+  email: string;
+  name: string;
+  role: 'owner' | 'editor';
+}
+
+/** Read the better-auth session into a cairn user (or null). */
+export async function loadSession(auth: Auth, request: Request): Promise<CairnUser | null> {
+  const session = await auth.api.getSession({ headers: request.headers });
+  if (!session?.user) return null;
+  const u = session.user as { id: string; email: string; name: string; role?: string | null };
+  return { id: u.id, email: u.email, name: u.name, role: u.role === 'owner' ? 'owner' : 'editor' };
+}
+
+export function requireSession(user: CairnUser | null): CairnUser {
+  if (!user) throw redirect(303, '/admin/login');
+  return user;
+}
+
+type ConfirmEvent = { request: Request; locals: { auth: Auth }; url: URL };
+
+/**
+ * POST-confirm verification (C2). Invoked from the confirm page's POST action: proxies the
+ * token to better-auth's GET verify endpoint via the per-request handler, then forwards the
+ * resulting Set-Cookie(s) onto a 303 to /admin. Scanners GET the confirm *page* (nothing is
+ * consumed); only this explicit POST consumes the token.
+ */
+export async function confirmSignIn(event: ConfirmEvent): Promise<Response> {
+  const form = await event.request.formData();
+  const token = String(form.get('token') ?? '');
+  if (!token) throw redirect(303, '/admin/login?error=expired');
+
+  const verifyUrl = `${event.url.origin}/api/auth/magic-link/verify?token=${encodeURIComponent(token)}&callbackURL=/admin`;
+  const res = await event.locals.auth.handler(new Request(verifyUrl, { headers: event.request.headers }));
+  const cookies = res.headers.getSetCookie();
+  if (cookies.length === 0) throw redirect(303, '/admin/login?error=expired');
+
+  const headers = new Headers({ location: '/admin' });
+  for (const cookie of cookies) headers.append('set-cookie', cookie);
+  return new Response(null, { status: 303, headers });
+}
+
+/** Sign out via better-auth, forwarding the session-clearing cookies, then 303 to login. */
+export async function signOut(event: { request: Request; locals: { auth: Auth } }): Promise<Response> {
+  const origin = new URL(event.request.url).origin;
+  const res = await event.locals.auth.handler(
+    new Request(`${origin}/api/auth/sign-out`, { method: 'POST', headers: event.request.headers }),
+  );
+  const headers = new Headers({ location: '/admin/login' });
+  for (const cookie of res.headers.getSetCookie()) headers.append('set-cookie', cookie);
+  return new Response(null, { status: 303, headers });
+}

package/src/lib/auth/index.ts

@@ -0,0 +1,6 @@
+// Public surface of `@glw907/cairn-cms/auth`: the per-request factory + server-side helpers
+// the site route shims and hooks delegate to. The browser client is intentionally NOT here
+// (it lives component-local in LoginPage to keep better-auth's deep client types out of dist).
+export { createAuth, type Auth, type AuthEnv, type AuthBranding } from './config';
+export { loadSession, requireSession, confirmSignIn, signOut, type CairnUser } from './guard';
+export { adminsLoad, addAdmin, removeAdmin, setAdminRole, requireOwner, type AdminsData } from './admins';