@glw907/cairn-cms 0.5.1 → 0.6.0-rc.0

package/src/lib/render/remark-directives.ts

@@ -1,20 +1,20 @@
 import type { Paragraph, PhrasingContent, Root, Text } from 'mdast';
 import type { ContainerDirective, LeafDirective, TextDirective } from 'mdast-util-directive';
 import { visit } from 'unist-util-visit';
-import type { ComponentRegistry } from './registry';
+import type { ComponentRegistry } from './registry.js';
 
 // Reconstruct a directive's authored attribute block (`{#id .class key="value"}`).
 // Accidental prose directives carry none, so this is almost always empty.
 function serializeAttributes(attributes?: Record<string, string | null | undefined> | null): string {
-	if (!attributes) return '';
-	const tokens: string[] = [];
-	for (const [key, value] of Object.entries(attributes)) {
-		if (value == null) tokens.push(key);
-		else if (key === 'id') tokens.push(`#${value}`);
-		else if (key === 'class') for (const c of value.split(/\s+/).filter(Boolean)) tokens.push(`.${c}`);
-		else tokens.push(`${key}="${value}"`);
-	}
-	return tokens.length ? `{${tokens.join(' ')}}` : '';
+  if (!attributes) return '';
+  const tokens: string[] = [];
+  for (const [key, value] of Object.entries(attributes)) {
+    if (value == null) tokens.push(key);
+    else if (key === 'id') tokens.push(`#${value}`);
+    else if (key === 'class') for (const c of value.split(/\s+/).filter(Boolean)) tokens.push(`.${c}`);
+    else tokens.push(`${key}="${value}"`);
+  }
+  return tokens.length ? `{${tokens.join(' ')}}` : '';
 }
 
 // The vocabulary is container-only (`:::name`). A text directive (`:name`) or
@@ -22,14 +22,14 @@ function serializeAttributes(attributes?: Record<string, string | null | undefin
 // ("4:00", "9:30", "ratio 16:9") that micromark tokenized as a directive.
 // Restore it to its literal source text so prose renders verbatim.
 function restoreLiteral(node: TextDirective | LeafDirective): PhrasingContent[] {
-	const marker = node.type === 'leafDirective' ? '::' : ':';
-	const attrs = serializeAttributes(node.attributes);
-	if (node.children.length === 0) {
-		return [{ type: 'text', value: marker + node.name + attrs }];
-	}
-	const open: Text = { type: 'text', value: `${marker}${node.name}[` };
-	const close: Text = { type: 'text', value: `]${attrs}` };
-	return [open, ...(node.children as PhrasingContent[]), close];
+  const marker = node.type === 'leafDirective' ? '::' : ':';
+  const attrs = serializeAttributes(node.attributes);
+  if (node.children.length === 0) {
+    return [{ type: 'text', value: marker + node.name + attrs }];
+  }
+  const open: Text = { type: 'text', value: `${marker}${node.name}[` };
+  const close: Text = { type: 'text', value: `]${attrs}` };
+  return [open, ...(node.children as PhrasingContent[]), close];
 }
 
 // Stamp each registered container directive with data-* markers carrying its
@@ -37,35 +37,35 @@ function restoreLiteral(node: TextDirective | LeafDirective): PhrasingContent[]
 // dispatcher rewrites the marked elements once their children are hast.
 // Text and leaf directives are restored to literal text (accidental prose colons).
 export function remarkDirectiveStamp(registry: ComponentRegistry) {
-	const known = new Set(registry.names);
-	return (tree: Root) => {
-		visit(tree, 'containerDirective', (node: ContainerDirective) => {
-			if (!known.has(node.name)) return;
-			const attrs = node.attributes ?? {};
-			const role = attrs.role || undefined;
-			let icon = attrs.icon || undefined;
-			if (!icon && role) icon = registry.defaultIcon(node.name, role);
+  const known = new Set(registry.names);
+  return (tree: Root) => {
+    visit(tree, 'containerDirective', (node: ContainerDirective) => {
+      if (!known.has(node.name)) return;
+      const attrs = node.attributes ?? {};
+      const role = attrs.role || undefined;
+      let icon = attrs.icon || undefined;
+      if (!icon && role) icon = registry.defaultIcon(node.name, role);
 
-			const properties: Record<string, string> = { dataPrimitive: node.name };
-			if (icon) properties.dataIcon = icon;
-			if (role) properties.dataRole = role;
+      const properties: Record<string, string> = { dataPrimitive: node.name };
+      if (icon) properties.dataIcon = icon;
+      if (role) properties.dataRole = role;
 
-			const data = node.data ?? (node.data = {});
-			data.hName = 'div';
-			data.hProperties = properties;
-		});
+      const data = node.data ?? (node.data = {});
+      data.hName = 'div';
+      data.hProperties = properties;
+    });
 
-		visit(tree, ['textDirective', 'leafDirective'], (node, index, parent) => {
-			if (!parent || index == null) return;
-			const literal = restoreLiteral(node as TextDirective | LeafDirective);
-			if (node.type === 'leafDirective') {
-				// Leaf directives sit at block level; wrap the restored text in a paragraph.
-				const paragraph: Paragraph = { type: 'paragraph', children: literal };
-				parent.children.splice(index, 1, paragraph);
-			} else {
-				parent.children.splice(index, 1, ...literal);
-			}
-			return index;
-		});
-	};
+    visit(tree, ['textDirective', 'leafDirective'], (node, index, parent) => {
+      if (!parent || index == null) return;
+      const literal = restoreLiteral(node as TextDirective | LeafDirective);
+      if (node.type === 'leafDirective') {
+        // Leaf directives sit at block level; wrap the restored text in a paragraph.
+        const paragraph: Paragraph = { type: 'paragraph', children: literal };
+        parent.children.splice(index, 1, paragraph);
+      } else {
+        parent.children.splice(index, 1, ...literal);
+      }
+      return index;
+    });
+  };
 }

package/src/lib/render/sanitize.ts

@@ -0,0 +1,27 @@
+// The live preview's sanitize floor. Carta runs with `sanitizer: false` behind the MarkdownEditor
+// seam, so the admin preview pane is the one barrier between editor-authored markdown and the DOM.
+// DOMPurify needs a DOM, and the preview renders only in the browser after mount, so DOMPurify
+// loads through a dynamic import: the module never evaluates a DOM library on the Worker, and a
+// server import of this file pulls in nothing.
+let purify: { sanitize(html: string, config?: Record<string, unknown>): string; addHook(event: string, cb: (node: Element) => void): void } | null = null;
+
+/**
+ * Sanitize rendered preview HTML before it reaches `{@html}`. Strips scripts, inline event
+ * handlers, and dangerous URL schemes (`javascript:`, `data:`) while keeping ordinary formatting.
+ * Also forces `rel="noopener noreferrer"` on any anchor with `target="_blank"` to prevent
+ * reverse-tabnabbing. Browser-only; resolves the same string DOMPurify would return.
+ */
+export async function sanitizePreviewHtml(html: string): Promise<string> {
+  if (!purify) {
+    const mod = await import('dompurify');
+    purify = mod.default;
+    purify.addHook('afterSanitizeAttributes', (node) => {
+      if (node.tagName === 'A' && node.getAttribute('target') === '_blank') {
+        node.setAttribute('rel', 'noopener noreferrer');
+      }
+    });
+  }
+  // ADD_ATTR: ['target'] allows target="_blank" through so the afterSanitizeAttributes hook
+  // can enforce rel="noopener noreferrer" on those anchors before they reach the DOM.
+  return purify.sanitize(html, { ADD_ATTR: ['target'] });
+}

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

@@ -0,0 +1,107 @@
+// The SvelteKit handlers for the magic-link flow, consumed by a site's thin route shims.
+// The factory takes per-site branding and an injected send, so tests run the real handlers
+// against a sink. The confirm-load, confirm, and logout handlers arrive in Task 6.
+import { redirect } from '@sveltejs/kit';
+import { requireOrigin, requireDb } from '../env.js';
+import {
+  generateToken,
+  generateSessionId,
+  hashToken,
+  TOKEN_TTL_MS,
+  SESSION_TTL_MS,
+  COOKIE_NAME,
+} from '../auth/crypto.js';
+import { findEditor, issueToken, consumeToken, createSession, deleteSession } from '../auth/store.js';
+import { buildMagicLinkMessage, cloudflareSend, type AuthBranding, type SendMagicLink } from '../email.js';
+import type { RequestContext } from './types.js';
+
+export interface AuthRoutesConfig {
+  branding: AuthBranding;
+  send?: SendMagicLink;
+}
+
+export function createAuthRoutes(config: AuthRoutesConfig) {
+  const send = config.send ?? cloudflareSend;
+
+  /**
+   * POST /admin/auth/request. Looks the email up in the allowlist; on a match, issues a token
+   * and emails the confirmation link. The response is identical whether or not the email is
+   * allow-listed, so the endpoint never leaks membership.
+   */
+  async function requestAction(event: RequestContext): Promise<{ sent: true }> {
+    const env = event.platform?.env ?? {};
+    const origin = requireOrigin(env);
+    const db = requireDb(env);
+    const form = await event.request.formData();
+    const email = String(form.get('email') ?? '').trim().toLowerCase();
+
+    const editor = email ? await findEditor(db, email) : null;
+    if (editor) {
+      const token = generateToken();
+      const now = Date.now();
+      await issueToken(db, email, await hashToken(token), now + TOKEN_TTL_MS, now);
+      const link = `${origin}/admin/auth/confirm?token=${encodeURIComponent(token)}`;
+      await send(env, buildMagicLinkMessage({ to: email, branding: config.branding, link }));
+    }
+    return { sent: true };
+  }
+
+  /** GET /admin/login. Public. Carries the site name and an optional `?error` for the form. */
+  function loginLoad(event: RequestContext): { siteName: string; error: string | null } {
+    return { siteName: config.branding.siteName, error: event.url.searchParams.get('error') };
+  }
+
+  /**
+   * GET /admin/auth/confirm. Renders the confirm page and consumes nothing; only the POST
+   * verifies. Sets Referrer-Policy: no-referrer so the token does not leak to a referrer.
+   */
+  function confirmLoad(
+    event: RequestContext,
+  ): { token: string; siteName: string; error: string | null } {
+    event.setHeaders({ 'Referrer-Policy': 'no-referrer' });
+    return {
+      token: event.url.searchParams.get('token') ?? '',
+      siteName: config.branding.siteName,
+      error: event.url.searchParams.get('error'),
+    };
+  }
+
+  /**
+   * POST /admin/auth/confirm. Hashes the submitted token and consumes it atomically. A valid
+   * token yields the email; the handler creates a session, sets the cookie, and redirects to
+   * /admin. An invalid, replayed, or expired token redirects to the login page.
+   */
+  async function confirmAction(event: RequestContext): Promise<never> {
+    const db = requireDb(event.platform?.env ?? {});
+    const form = await event.request.formData();
+    const token = String(form.get('token') ?? '');
+    if (!token) throw redirect(303, '/admin/login?error=expired');
+
+    const now = Date.now();
+    const email = await consumeToken(db, await hashToken(token), now);
+    if (!email) throw redirect(303, '/admin/login?error=expired');
+
+    const id = generateSessionId();
+    await createSession(db, id, email, now + SESSION_TTL_MS, now);
+    event.cookies.set(COOKIE_NAME, id, {
+      path: '/',
+      httpOnly: true,
+      // Secure on HTTPS (every real deploy); off on local http dev so the cookie sticks.
+      secure: event.url.protocol === 'https:',
+      sameSite: 'lax',
+      maxAge: Math.floor(SESSION_TTL_MS / 1000),
+    });
+    throw redirect(303, '/admin');
+  }
+
+  /** POST /admin/auth/logout. Deletes the session row and clears the cookie. */
+  async function logoutAction(event: RequestContext): Promise<never> {
+    const db = requireDb(event.platform?.env ?? {});
+    const id = event.cookies.get(COOKIE_NAME);
+    if (id) await deleteSession(db, id);
+    event.cookies.delete(COOKIE_NAME, { path: '/' });
+    throw redirect(303, '/admin/login');
+  }
+
+  return { loginLoad, requestAction, confirmLoad, confirmAction, logoutAction };
+}

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

@@ -0,0 +1,261 @@
+// The admin content routes: the load and action functions a site's /admin/** shims call.
+// A factory closes over the composed runtime and the GitHub token mint, so the read and
+// commit paths are unit-testable against a fetch double with an injected token, mirroring the
+// email `send` injection in auth-routes. A shim stays one line: `export const load = routes.editLoad`.
+import { redirect, error } from '@sveltejs/kit';
+import { findConcept } from '../content/concepts.js';
+import { frontmatterFromForm, parseMarkdown, dateInputValue, serializeMarkdown } from '../content/frontmatter.js';
+import { isValidId, slugify, filenameFromId } from '../content/ids.js';
+import { appCredentials, type GithubKeyEnv } from '../github/credentials.js';
+import { listMarkdown, readRaw, commitFile } from '../github/repo.js';
+import { installationToken } from '../github/signing.js';
+import { CommitConflictError } from '../github/types.js';
+import type { CairnRuntime, ConceptDescriptor, FrontmatterField } from '../content/types.js';
+import type { Editor, Role } from '../auth/types.js';
+
+/** A sidebar concept entry: just enough to render the nav without shipping validators to the client. */
+export interface NavConcept {
+  id: string;
+  label: string;
+}
+
+/** The admin layout's data: site identity, the signed-in user, the nav, and the active path. */
+export interface LayoutData {
+  siteName: string;
+  user: { displayName: string; role: Role };
+  concepts: NavConcept[];
+  pathname: string;
+  canManageEditors: boolean;
+  /** The nav menu's label when the site configures one; gates the Navigation nav entry. Null otherwise. */
+  navLabel: string | null;
+}
+
+/** One row in a concept's list view. */
+export interface EntrySummary {
+  id: string;
+  title: string;
+  date: string | null;
+  draft: boolean;
+}
+
+/** The concept list view's data. */
+export interface ListData {
+  conceptId: string;
+  label: string;
+  /** Posts carry a date in the new-entry form; pages do not (concept routing, spec §7.2). */
+  dated: boolean;
+  entries: EntrySummary[];
+  /** A listing failure degrades to an inline message rather than a thrown 500. */
+  error: string | null;
+  /** A create-form bounce error read from `?error`. */
+  formError: string | null;
+}
+
+/** The editor's data. `frontmatter` holds form-ready values (dates already `YYYY-MM-DD`). */
+export interface EditData {
+  conceptId: string;
+  id: string;
+  label: string;
+  fields: FrontmatterField[];
+  frontmatter: Record<string, unknown>;
+  body: string;
+  title: string;
+  isNew: boolean;
+  saved: boolean;
+  error: string | null;
+}
+
+/** The structural event the content routes read; a real SvelteKit RequestEvent satisfies it. */
+export interface ContentEvent {
+  url: URL;
+  params: Record<string, string>;
+  request: Request;
+  locals: { editor?: Editor | null };
+  platform?: { env?: GithubKeyEnv };
+}
+
+/** Injectable dependencies; tests stub the token mint to avoid signing a real key. */
+export interface ContentRoutesDeps {
+  /** Mint a GitHub App installation token from the Worker env. Defaults to the real signer. */
+  mintToken?: (env: GithubKeyEnv) => Promise<string>;
+}
+
+/** The signed-in editor the guard resolved, or a login redirect. Kept local to decouple event shapes. */
+function sessionOf(event: ContentEvent): Editor {
+  const editor = event.locals.editor;
+  if (!editor) throw redirect(303, '/admin/login');
+  return editor;
+}
+
+/** Look up the concept named by the `[concept]` route param, or a 404. */
+function conceptOf(runtime: CairnRuntime, params: Record<string, string>): ConceptDescriptor {
+  const concept = findConcept(runtime.concepts, params.concept ?? '');
+  if (!concept) throw error(404, `Unknown content type: ${params.concept ?? ''}`);
+  return concept;
+}
+
+export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDeps = {}) {
+  const mintToken =
+    deps.mintToken ?? ((env: GithubKeyEnv) => installationToken(appCredentials(runtime.backend, env)));
+
+  /** Layout load for every admin page: the nav, the user, and the active path. */
+  function layoutLoad(event: ContentEvent): LayoutData {
+    const editor = sessionOf(event);
+    return {
+      siteName: runtime.siteName,
+      user: { displayName: editor.displayName, role: editor.role },
+      concepts: runtime.concepts.map((c) => ({ id: c.id, label: c.label })),
+      pathname: event.url.pathname,
+      canManageEditors: editor.role === 'owner',
+      navLabel: runtime.navMenu?.label ?? null,
+    };
+  }
+
+  /** Redirect /admin to the first concept's list (spec §7.6: land on the first concept). */
+  function indexRedirect(): never {
+    const first = runtime.concepts[0];
+    if (!first) throw error(404, 'No content types configured');
+    throw redirect(307, `/admin/${first.id}`);
+  }
+
+  /** Read a file's frontmatter for its list row, degrading to the id on any read failure. */
+  async function summarize(file: { id: string; path: string }, token: string): Promise<EntrySummary> {
+    try {
+      const raw = await readRaw(runtime.backend, file.path, token);
+      if (raw === null) return { id: file.id, title: file.id, date: null, draft: false };
+      const { frontmatter } = parseMarkdown(raw);
+      const title = typeof frontmatter.title === 'string' && frontmatter.title.trim() ? frontmatter.title : file.id;
+      const date = dateInputValue(frontmatter.date) || null;
+      return { id: file.id, title, date, draft: frontmatter.draft === true };
+    } catch {
+      return { id: file.id, title: file.id, date: null, draft: false };
+    }
+  }
+
+  /** List a concept's entries. A listing failure degrades to an inline error, not a thrown 500. */
+  async function listLoad(event: ContentEvent): Promise<ListData> {
+    sessionOf(event);
+    const concept = conceptOf(runtime, event.params);
+    const formError = event.url.searchParams.get('error');
+    const base = { conceptId: concept.id, label: concept.label, dated: concept.routing.dated, formError };
+    let token: string;
+    try {
+      token = await mintToken(event.platform?.env ?? {});
+    } catch {
+      return { ...base, entries: [], error: 'Could not authenticate with GitHub.' };
+    }
+    try {
+      const files = await listMarkdown(runtime.backend, concept.dir, token);
+      const entries = await Promise.all(files.map((f) => summarize(f, token)));
+      return { ...base, entries, error: null };
+    } catch {
+      return { ...base, entries: [], error: 'Could not load this content type from GitHub.' };
+    }
+  }
+
+  /** Create a new entry: validate the slug, refuse to clobber, and redirect to the editor. */
+  async function createAction(event: ContentEvent): Promise<never> {
+    sessionOf(event);
+    const concept = conceptOf(runtime, event.params);
+    const form = await event.request.formData();
+    const raw = String(form.get('slug') ?? '').trim() || slugify(String(form.get('title') ?? ''));
+    const bounce = (msg: string): never => {
+      throw redirect(303, `/admin/${concept.id}?error=${encodeURIComponent(msg)}`);
+    };
+    if (!isValidId(raw)) bounce('Enter a valid slug: lowercase letters, numbers, and hyphens.');
+
+    const token = await mintToken(event.platform?.env ?? {});
+    const existing = await readRaw(runtime.backend, `${concept.dir}/${filenameFromId(raw)}`, token);
+    if (existing !== null) bounce('An entry with that slug already exists.');
+
+    throw redirect(303, `/admin/${concept.id}/${raw}?new=1`);
+  }
+
+  /** Coerce parsed frontmatter to the form-ready values the editor inputs expect. */
+  function formValues(fields: FrontmatterField[], frontmatter: Record<string, unknown>): Record<string, unknown> {
+    const out: Record<string, unknown> = {};
+    for (const field of fields) {
+      const value = frontmatter[field.name];
+      if (field.type === 'date') out[field.name] = dateInputValue(value);
+      else if (field.type === 'boolean') out[field.name] = value === true;
+      else if (field.type === 'tags' || field.type === 'freetags') out[field.name] = Array.isArray(value) ? value.map(String) : [];
+      else out[field.name] = typeof value === 'string' ? value : value == null ? '' : String(value);
+    }
+    return out;
+  }
+
+  /** Open a file for editing. A `?new=1` miss yields a blank document; any other miss is a 404. */
+  async function editLoad(event: ContentEvent): Promise<EditData> {
+    sessionOf(event);
+    const concept = conceptOf(runtime, event.params);
+    const id = event.params.id ?? '';
+    if (!isValidId(id)) throw error(400, 'Invalid entry id');
+    const isNew = event.url.searchParams.get('new') === '1';
+    const token = await mintToken(event.platform?.env ?? {});
+    const raw = await readRaw(runtime.backend, `${concept.dir}/${filenameFromId(id)}`, token);
+    if (raw === null && !isNew) throw error(404, 'Entry not found');
+
+    const parsed = raw === null ? { frontmatter: {}, body: '' } : parseMarkdown(raw);
+    const title = typeof parsed.frontmatter.title === 'string' && parsed.frontmatter.title.trim() ? parsed.frontmatter.title : id;
+    return {
+      conceptId: concept.id,
+      id,
+      label: concept.label,
+      fields: concept.fields,
+      frontmatter: formValues(concept.fields, parsed.frontmatter),
+      body: parsed.body,
+      title,
+      isNew,
+      saved: event.url.searchParams.get('saved') === '1',
+      error: event.url.searchParams.get('error'),
+    };
+  }
+
+  /** Match a commit conflict by class and by name (bundling can alias the class identity). */
+  function isConflict(err: unknown): boolean {
+    return err instanceof CommitConflictError || (err as { name?: string } | null)?.name === 'CommitConflictError';
+  }
+
+  /** Save an edit: validate, then commit with the session editor as author. Fails safe on 409. */
+  async function saveAction(event: ContentEvent): Promise<never> {
+    const editor = sessionOf(event);
+    const concept = conceptOf(runtime, event.params);
+    const id = event.params.id ?? '';
+    // Confine the commit path to the concept dir, built from a validated id (the App token can
+    // write anywhere in the repo). Reject before touching GitHub.
+    if (!isValidId(id)) throw error(400, 'Invalid entry id');
+    const path = `${concept.dir}/${filenameFromId(id)}`;
+
+    const form = await event.request.formData();
+    const body = String(form.get('body') ?? '');
+    const isNew = form.get('new') === '1';
+    const suffix = isNew ? '&new=1' : '';
+
+    const result = concept.validate(frontmatterFromForm(concept.fields, form), body);
+    if (!result.ok) {
+      const message = Object.values(result.errors)[0] ?? 'Invalid frontmatter';
+      throw redirect(303, `/admin/${concept.id}/${id}?error=${encodeURIComponent(message)}${suffix}`);
+    }
+
+    const markdown = serializeMarkdown(result.data, body);
+    const token = await mintToken(event.platform?.env ?? {});
+    try {
+      await commitFile(
+        runtime.backend,
+        path,
+        markdown,
+        { message: `Update ${concept.label.toLowerCase()}: ${id}`, author: { name: editor.displayName, email: editor.email } },
+        token,
+      );
+    } catch (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}`);
+      }
+      throw err;
+    }
+    throw redirect(303, `/admin/${concept.id}/${id}?saved=1`);
+  }
+
+  return { layoutLoad, indexRedirect, listLoad, createAction, editLoad, saveAction, mintToken };
+}

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

@@ -0,0 +1,82 @@
+// Owner-gated editor management. The editor table is the allowlist, so add and remove are
+// insert and delete. The anti-lockout rule is the last remaining owner: the system refuses to
+// drop below one owner (spec 7.1), enforced in the store by an atomic guarded write rather
+// than a separate count, so concurrent removals cannot strand the allowlist at zero owners.
+import { fail } from '@sveltejs/kit';
+import { requireOwner } from './guard.js';
+import { requireDb } from '../env.js';
+import {
+  listEditors,
+  findEditor,
+  insertEditor,
+  deleteEditor,
+  setEditorRole,
+  removeOwnerIfNotLast,
+  demoteOwnerIfNotLast,
+} from '../auth/store.js';
+import type { Editor, Role } from '../auth/types.js';
+import type { RequestContext } from './types.js';
+
+const EMAIL_RE = /^[^@\s]+@[^@\s]+\.[^@\s]+$/;
+
+function parseRole(value: FormDataEntryValue | null): Role {
+  return value === 'owner' ? 'owner' : 'editor';
+}
+
+export function createEditorRoutes() {
+  /** GET /admin/editors. Owner-only. Returns the allowlist and the acting owner's email. */
+  async function editorsLoad(event: RequestContext): Promise<{ editors: Editor[]; self: string }> {
+    const owner = requireOwner(event);
+    const editors = await listEditors(requireDb(event.platform?.env ?? {}));
+    return { editors, self: owner.email };
+  }
+
+  /** POST add an editor. Owner-only. */
+  async function addEditorAction(event: RequestContext) {
+    requireOwner(event);
+    const db = requireDb(event.platform?.env ?? {});
+    const form = await event.request.formData();
+    const email = String(form.get('email') ?? '').trim().toLowerCase();
+    const name = String(form.get('name') ?? '').trim();
+    const role = parseRole(form.get('role'));
+    if (!EMAIL_RE.test(email) || !name) return fail(400, { error: 'Enter a valid email and name' });
+    if (await findEditor(db, email)) return fail(400, { error: 'That editor already exists' });
+    await insertEditor(db, email, name, role, Date.now());
+    return { ok: true as const };
+  }
+
+  /** POST remove an editor. Owner-only. Refuses the last owner, atomically. */
+  async function removeEditorAction(event: RequestContext) {
+    requireOwner(event);
+    const db = requireDb(event.platform?.env ?? {});
+    const form = await event.request.formData();
+    const email = String(form.get('email') ?? '').trim().toLowerCase();
+    const target = await findEditor(db, email);
+    if (!target) return fail(400, { error: 'No such editor' });
+    if (target.role === 'owner') {
+      if (!(await removeOwnerIfNotLast(db, email))) return fail(400, { error: 'You cannot remove the last owner' });
+    } else {
+      await deleteEditor(db, email);
+    }
+    return { ok: true as const };
+  }
+
+  /** POST change an editor's role. Owner-only. Refuses demoting the last owner, atomically. */
+  async function setRoleAction(event: RequestContext) {
+    requireOwner(event);
+    const db = requireDb(event.platform?.env ?? {});
+    const form = await event.request.formData();
+    const email = String(form.get('email') ?? '').trim().toLowerCase();
+    const role = parseRole(form.get('role'));
+    const target = await findEditor(db, email);
+    if (!target) return fail(400, { error: 'No such editor' });
+    if (role === 'editor' && target.role === 'owner') {
+      if (!(await demoteOwnerIfNotLast(db, email))) return fail(400, { error: 'You cannot demote the last owner' });
+    } else {
+      await setEditorRole(db, email, role);
+    }
+    return { ok: true as const };
+  }
+
+  return { editorsLoad, addEditorAction, removeEditorAction, setRoleAction };
+}

package/src/lib/sveltekit/guard.ts

@@ -0,0 +1,47 @@
+// The /admin guard, plus the per-load owner/session gates. A site's hooks.server.ts sets
+// `export const handle = createAuthGuard()`. Events are typed structurally, so the engine
+// stays free of a site's App.* ambient types.
+import { redirect, error } from '@sveltejs/kit';
+import { resolveSession } from '../auth/store.js';
+import { COOKIE_NAME } from '../auth/crypto.js';
+import type { Editor } from '../auth/types.js';
+import type { HandleInput, RequestContext } from './types.js';
+
+/** The login page and the auth endpoints are public; everything else under /admin is gated. */
+function isPublicAdminPath(pathname: string): boolean {
+  return pathname === '/admin/login' || pathname.startsWith('/admin/auth/');
+}
+
+function isAdminPath(pathname: string): boolean {
+  return pathname === '/admin' || pathname.startsWith('/admin/');
+}
+
+/** The SvelteKit `Handle` that guards `/admin/**`. */
+export function createAuthGuard() {
+  return async function handle({ event, resolve }: HandleInput): Promise<Response> {
+    const { pathname } = event.url;
+    if (!isAdminPath(pathname) || isPublicAdminPath(pathname)) {
+      return resolve(event);
+    }
+    const env = event.platform?.env ?? {};
+    const id = event.cookies.get(COOKIE_NAME);
+    const editor = id && env.AUTH_DB ? await resolveSession(env.AUTH_DB, id, Date.now()) : null;
+    if (!editor) throw redirect(303, '/admin/login');
+    event.locals.editor = editor;
+    return resolve(event);
+  };
+}
+
+/** For a protected load/action: the session the guard already resolved, or a login redirect. */
+export function requireSession(event: RequestContext): Editor {
+  const editor = event.locals.editor;
+  if (!editor) throw redirect(303, '/admin/login');
+  return editor;
+}
+
+/** For the management surface: a signed-in owner, or 403 for an editor. */
+export function requireOwner(event: RequestContext): Editor {
+  const editor = requireSession(event);
+  if (editor.role !== 'owner') throw error(403, 'Owner access required');
+  return editor;
+}

package/src/lib/sveltekit/health.ts

@@ -0,0 +1,24 @@
+// GET /admin/healthz. Signs a dummy JWT through the real App-signing path so a broken
+// PKCS#1-to-PKCS#8 conversion is caught early (spec §7.8). The payload is pass/fail and a
+// coarse detail only; it never carries the key or a token.
+import { signingSelfTest } from '../github/signing.js';
+import type { CairnRuntime } from '../content/types.js';
+import type { GithubKeyEnv } from '../github/credentials.js';
+
+/** The `/admin/healthz` payload. */
+export interface HealthData {
+  ok: boolean;
+  checks: { githubAppSigning: { ok: boolean; detail?: string } };
+}
+
+/** Run the signing self-test against the configured App id and the Worker's key secret. */
+export async function healthLoad(
+  event: { platform?: { env?: GithubKeyEnv } },
+  runtime: CairnRuntime,
+): Promise<HealthData> {
+  const key = event.platform?.env?.GITHUB_APP_PRIVATE_KEY_B64;
+  const githubAppSigning = key
+    ? await signingSelfTest(runtime.backend.appId, key)
+    : { ok: false, detail: 'GITHUB_APP_PRIVATE_KEY_B64 is not configured' };
+  return { ok: githubAppSigning.ok, checks: { githubAppSigning } };
+}