@glw907/cairn-cms 0.3.1 → 0.5.0

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';

package/src/lib/auth/schema.ts

@@ -0,0 +1,112 @@
+import { relations, sql } from "drizzle-orm";
+import { sqliteTable, text, integer, index } from "drizzle-orm/sqlite-core";
+
+export const user = sqliteTable("user", {
+  id: text("id").primaryKey(),
+  name: text("name").notNull(),
+  email: text("email").notNull().unique(),
+  emailVerified: integer("email_verified", { mode: "boolean" })
+    .default(false)
+    .notNull(),
+  image: text("image"),
+  createdAt: integer("created_at", { mode: "timestamp_ms" })
+    .default(sql`(cast(unixepoch('subsecond') * 1000 as integer))`)
+    .notNull(),
+  updatedAt: integer("updated_at", { mode: "timestamp_ms" })
+    .default(sql`(cast(unixepoch('subsecond') * 1000 as integer))`)
+    .$onUpdate(() => /* @__PURE__ */ new Date())
+    .notNull(),
+  role: text("role"),
+  banned: integer("banned", { mode: "boolean" }).default(false),
+  banReason: text("ban_reason"),
+  banExpires: integer("ban_expires", { mode: "timestamp_ms" }),
+});
+
+export const session = sqliteTable(
+  "session",
+  {
+    id: text("id").primaryKey(),
+    expiresAt: integer("expires_at", { mode: "timestamp_ms" }).notNull(),
+    token: text("token").notNull().unique(),
+    createdAt: integer("created_at", { mode: "timestamp_ms" })
+      .default(sql`(cast(unixepoch('subsecond') * 1000 as integer))`)
+      .notNull(),
+    updatedAt: integer("updated_at", { mode: "timestamp_ms" })
+      .$onUpdate(() => /* @__PURE__ */ new Date())
+      .notNull(),
+    ipAddress: text("ip_address"),
+    userAgent: text("user_agent"),
+    userId: text("user_id")
+      .notNull()
+      .references(() => user.id, { onDelete: "cascade" }),
+    impersonatedBy: text("impersonated_by"),
+  },
+  (table) => [index("session_userId_idx").on(table.userId)],
+);
+
+export const account = sqliteTable(
+  "account",
+  {
+    id: text("id").primaryKey(),
+    accountId: text("account_id").notNull(),
+    providerId: text("provider_id").notNull(),
+    userId: text("user_id")
+      .notNull()
+      .references(() => user.id, { onDelete: "cascade" }),
+    accessToken: text("access_token"),
+    refreshToken: text("refresh_token"),
+    idToken: text("id_token"),
+    accessTokenExpiresAt: integer("access_token_expires_at", {
+      mode: "timestamp_ms",
+    }),
+    refreshTokenExpiresAt: integer("refresh_token_expires_at", {
+      mode: "timestamp_ms",
+    }),
+    scope: text("scope"),
+    password: text("password"),
+    createdAt: integer("created_at", { mode: "timestamp_ms" })
+      .default(sql`(cast(unixepoch('subsecond') * 1000 as integer))`)
+      .notNull(),
+    updatedAt: integer("updated_at", { mode: "timestamp_ms" })
+      .$onUpdate(() => /* @__PURE__ */ new Date())
+      .notNull(),
+  },
+  (table) => [index("account_userId_idx").on(table.userId)],
+);
+
+export const verification = sqliteTable(
+  "verification",
+  {
+    id: text("id").primaryKey(),
+    identifier: text("identifier").notNull(),
+    value: text("value").notNull(),
+    expiresAt: integer("expires_at", { mode: "timestamp_ms" }).notNull(),
+    createdAt: integer("created_at", { mode: "timestamp_ms" })
+      .default(sql`(cast(unixepoch('subsecond') * 1000 as integer))`)
+      .notNull(),
+    updatedAt: integer("updated_at", { mode: "timestamp_ms" })
+      .default(sql`(cast(unixepoch('subsecond') * 1000 as integer))`)
+      .$onUpdate(() => /* @__PURE__ */ new Date())
+      .notNull(),
+  },
+  (table) => [index("verification_identifier_idx").on(table.identifier)],
+);
+
+export const userRelations = relations(user, ({ many }) => ({
+  sessions: many(session),
+  accounts: many(account),
+}));
+
+export const sessionRelations = relations(session, ({ one }) => ({
+  user: one(user, {
+    fields: [session.userId],
+    references: [user.id],
+  }),
+}));
+
+export const accountRelations = relations(account, ({ one }) => ({
+  user: one(user, {
+    fields: [account.userId],
+    references: [user.id],
+  }),
+}));

package/src/lib/carta.ts

@@ -1,6 +1,6 @@
 // cairn-core: pure Carta options/transformer wiring for render-only preview.
 //
-// Plugins are passed in, not imported — that seam is what the Pass D adapter formalises.
+// Plugins are passed in rather than imported; that seam is what the Pass D adapter formalises.
 // No `carta-md` import: its index re-exports Svelte components that the node test env
 // can't load. The Svelte component calls `new Carta(previewCartaOptions(...))` directly.
 import type { Pluggable, Processor } from 'unified';
@@ -37,7 +37,7 @@ export function previewTransformers({ remarkPlugins, rehypePlugins }: PreviewPlu
   return [...phase(remarkPlugins, 'remark'), ...phase(rehypePlugins, 'rehype')];
 }
 
-/** Minimal Options subset we populate — avoids importing carta-md (Svelte re-exports). */
+/** Minimal Options subset we populate (avoids importing carta-md, which re-exports Svelte components). */
 interface PreviewCartaOptions {
   sanitizer: false;
   rehypeOptions: { allowDangerousHtml: boolean };

package/src/lib/components/AdminLayout.svelte

@@ -1,19 +1,19 @@
 <script lang="ts">
   // Neutral admin chrome, shared across sites so the tool looks identical everywhere (only the
   // adapter's siteName varies). When signed in it's a responsive DaisyUI drawer+navbar shell
-  // (`drawer lg:drawer-open` — sidebar pinned on desktop, slide-over + hamburger on mobile),
+  // (`drawer lg:drawer-open`, sidebar pinned on desktop, slide-over + hamburger on mobile),
   // patterned on scosman/CMSaasStarter's `(admin)/(menu)` layout. The nav is data-driven and
   // role-gated, so a new surface is one entry in `nav` (plus its route + component). Signed out
   // (the login page lives under this layout) it falls back to a minimal centered shell.
   // Each site's `admin/+layout.svelte` is a one-line shim that forwards `data` + `children`.
   import type { Snippet } from 'svelte';
-  import type { Editor } from '../auth';
+  import type { CairnUser } from '../auth';
 
   let {
     data,
     children,
   }: {
-    data: { siteName: string; editor: Editor | null; pathname: string };
+    data: { siteName: string; user: CairnUser | null; pathname: string };
     children: Snippet;
   } = $props();
 
@@ -22,7 +22,7 @@
     label: string;
     icon: Snippet;
     active: boolean;
-    /** Owner-only surface — hidden from regular editors. */
+    /** Owner-only surface; hidden from regular editors. */
     owner?: boolean;
   }
 
@@ -41,7 +41,7 @@
       active: data.pathname.startsWith('/admin/admins'),
     },
   ]);
-  const visibleNav = $derived(nav.filter((item) => !item.owner || data.editor?.role === 'owner'));
+  const visibleNav = $derived(nav.filter((item) => !item.owner || data.user?.role === 'owner'));
 
   // Close the slide-over after a nav tap on mobile (no-op on desktop where it's pinned open).
   function closeDrawer(): void {
@@ -68,12 +68,12 @@
   <meta name="robots" content="noindex, nofollow" />
 </svelte:head>
 
-{#if data.editor}
+{#if data.user}
   <div class="drawer min-h-screen bg-base-200 lg:drawer-open" data-pagefind-ignore>
     <input id="admin-drawer" type="checkbox" class="drawer-toggle" />
 
     <div class="drawer-content">
-      <!-- Mobile top bar — the desktop sidebar replaces this at lg. -->
+      <!-- Mobile top bar; the desktop sidebar replaces this at lg. -->
       <div class="navbar bg-base-100 lg:hidden">
         <div class="flex-1">
           <span class="px-2 text-xl font-bold">{data.siteName} CMS</span>
@@ -111,8 +111,8 @@
         </ul>
 
         <div class="border-t border-base-300 p-4">
-          <p class="text-sm font-medium">{data.editor.name}</p>
-          <p class="text-xs opacity-60">{data.editor.email}</p>
+          <p class="text-sm font-medium">{data.user.name}</p>
+          <p class="text-xs opacity-60">{data.user.email}</p>
           <form method="POST" action="/admin/auth/logout" class="mt-3">
             <button type="submit" class="btn btn-ghost btn-sm btn-block justify-start">Sign out</button>
           </form>

package/src/lib/components/AdminList.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
   // The /admin content list: every collection's files, linking into the editor. Data comes
   // from `adminListLoad` (collections) merged with `adminLayoutLoad` (siteName). The shell
-  // (AdminLayout) owns the chrome — site title, signed-in identity, nav, sign out — so this
+  // (AdminLayout) owns the chrome (site title, signed-in identity, nav, sign out), so this
   // page renders only the content body.
   import type { AdminCollectionList } from '../sveltekit';
 

package/src/lib/components/ConfirmPage.svelte

@@ -0,0 +1,31 @@
+<script lang="ts">
+  // The scanner-safe confirm surface (C2). A GET renders this static page and consumes nothing.
+  // The token rides in a hidden field; only the explicit form POST (the route's default action,
+  // confirmSignIn) verifies it. Mail scanners GET URLs but don't submit forms, so prefetch can't
+  // burn the link. JS-free by design.
+  interface Props {
+    data: { token: string; siteName: string; error: string | null };
+  }
+  let { data }: Props = $props();
+</script>
+
+<svelte:head>
+  <title>Confirm sign-in · {data.siteName} CMS</title>
+</svelte:head>
+
+<div class="mx-auto mt-16 max-w-md rounded-box border border-base-300 bg-base-100 p-8">
+  <h1 class="text-2xl font-bold">Confirm sign-in</h1>
+  <p class="mt-1 text-sm opacity-70">to {data.siteName} CMS</p>
+
+  {#if data.error || !data.token}
+    <div class="alert alert-error mt-6">
+      <span>This sign-in link is invalid or expired. Request a new one.</span>
+    </div>
+    <a href="/admin/login" class="btn btn-primary mt-6">Back to sign-in</a>
+  {:else}
+    <form method="POST" class="mt-6 flex flex-col gap-3">
+      <input type="hidden" name="token" value={data.token} />
+      <button type="submit" class="btn btn-primary">Confirm sign-in</button>
+    </form>
+  {/if}
+</div>

package/src/lib/components/EditPage.svelte

@@ -13,21 +13,21 @@
 
   // Body is editable state; the Carta editor's preview runs the exact site plugin set, so it
   // matches the live page. A hidden input carries the current value into the form.
-  // svelte-ignore state_referenced_locally — seeding from the initial load is intended.
+  // svelte-ignore state_referenced_locally (seeding from the initial load is intended)
   let body = $state(data.body);
 
-  // svelte-ignore state_referenced_locally — the preview plugin set is fixed for the load.
+  // svelte-ignore state_referenced_locally (the preview plugin set is fixed for the load)
   const carta = new Carta(previewCartaOptions(preview));
 
   // Carta's MarkdownEditor must not render on the worker (it pulls Shiki). onMount fires only
-  // in the browser, so SSR renders the plain textarea and the client swaps in the editor —
-  // the kit-free equivalent of the per-site route's `$app/environment` `browser` guard.
+  // in the browser, so SSR renders the plain textarea and the client swaps in the editor.
+  // This is the kit-free equivalent of the per-site route's `$app/environment` `browser` guard.
   let mounted = $state(false);
   onMount(() => {
     mounted = true;
   });
 
-  // svelte-ignore state_referenced_locally — form defaults from the initial load.
+  // svelte-ignore state_referenced_locally (form defaults from the initial load)
   const fm = data.frontmatter as Record<string, unknown>;
 
   function fmString(key: string): string {

package/src/lib/components/LoginPage.svelte

@@ -1,17 +1,33 @@
 <script lang="ts">
-  // The magic-link sign-in page. Posts the email to /admin/auth/request; `sent`/`error` come
-  // from `loginLoad` (querystring) merged with `adminLayoutLoad` (siteName).
+  // The magic-link sign-in page. Requests a link via the better-auth client (client-side, same
+  // origin). To avoid enumeration the UI shows the same neutral copy whether or not the email is
+  // on the allowlist. The server only emails actual editors (see auth/config.ts send gate).
+  import { createAuthClient } from 'better-auth/svelte';
+  import { magicLinkClient } from 'better-auth/client/plugins';
+
+  // The browser client lives in the one component that needs it (requesting a link). Sign-out
+  // and editor management go through server endpoints, so no shared client module is needed.
+  // A component-local const keeps better-auth's deep client types out of the packaged .d.ts.
+  const authClient = createAuthClient({ plugins: [magicLinkClient()] });
+
   interface Props {
-    data: { siteName: string; sent: boolean; error: string | null };
+    data: { siteName: string };
   }
   let { data }: Props = $props();
 
-  const errorMessages: Record<string, string> = {
-    invalid: 'Please enter a valid email address.',
-    denied: 'That email is not on the editor allowlist.',
-    expired: 'That sign-in link has expired or was already used. Request a new one.',
-    config: 'Sign-in is not configured. Contact the site admin.',
-  };
+  let email = $state('');
+  let requested = $state(false);
+  let busy = $state(false);
+
+  async function request(event: SubmitEvent) {
+    event.preventDefault();
+    busy = true;
+    // The magic-link email points at our /admin/auth/confirm page (built in config.ts), not a
+    // GET-verify URL, so the result is the same regardless of allowlist membership.
+    await authClient.signIn.magicLink({ email });
+    busy = false;
+    requested = true;
+  }
 </script>
 
 <svelte:head>
@@ -22,26 +38,27 @@
   <h1 class="text-2xl font-bold">{data.siteName} CMS</h1>
   <p class="mt-1 text-sm opacity-70">Sign in with your editor email.</p>
 
-  {#if data.sent}
+  {#if requested}
     <div class="alert alert-success mt-6">
-      <span>Check your inbox — a sign-in link is on its way. It expires in 10 minutes.</span>
+      <span>
+        If that address is on the editor list, a sign-in link is on its way. It expires in 10
+        minutes.
+      </span>
     </div>
   {:else}
-    {#if data.error}
-      <div class="alert alert-error mt-6">
-        <span>{errorMessages[data.error] ?? 'Something went wrong. Try again.'}</span>
-      </div>
-    {/if}
-    <form method="POST" action="/admin/auth/request" class="mt-6 flex flex-col gap-3">
+    <form onsubmit={request} class="mt-6 flex flex-col gap-3">
       <input
         type="email"
         name="email"
+        bind:value={email}
         required
         autocomplete="email"
         placeholder="you@example.com"
         class="input w-full"
       />
-      <button type="submit" class="btn btn-primary">Email me a sign-in link</button>
+      <button type="submit" class="btn btn-primary" disabled={busy}>
+        {busy ? 'Sending…' : 'Email me a sign-in link'}
+      </button>
     </form>
   {/if}
 </div>

package/src/lib/components/ManageAdmins.svelte

@@ -3,7 +3,7 @@
   // ones. Reuses the same neutral DaisyUI chrome as the rest of the admin (panels, alerts,
   // table, buttons). Data comes from `adminsLoad` merged with `adminLayoutLoad` (siteName);
   // mutations post to the page's named form actions (`?/add`, `?/remove`, `?/setRole`).
-  import type { AdminsData } from '../sveltekit';
+  import type { AdminsData } from '../auth';
 
   interface Props {
     data: AdminsData & { siteName: string };

package/src/lib/components/index.ts

@@ -3,5 +3,6 @@
 export { default as AdminLayout } from './AdminLayout.svelte';
 export { default as AdminList } from './AdminList.svelte';
 export { default as LoginPage } from './LoginPage.svelte';
+export { default as ConfirmPage } from './ConfirmPage.svelte';
 export { default as EditPage } from './EditPage.svelte';
 export { default as ManageAdmins } from './ManageAdmins.svelte';

package/src/lib/email.ts

@@ -1,9 +1,9 @@
 // cairn-core: pluggable magic-link email sender.
 //
-// Default adapter is Cloudflare Email Service → Email Sending (transactional, arbitrary
-// recipients) — distinct from Email Routing's recipient-restricted `EmailMessage` flow.
-// It is reached through the same `send_email` binding (configured without a
-// destination_address) but a different call shape: `binding.send({ to, from, ... })`.
+// The default adapter targets Cloudflare Email Service (Email Sending, transactional,
+// arbitrary recipients), distinct from Email Routing's recipient-restricted `EmailMessage`
+// flow. Both share the same `send_email` binding (configured without a destination_address)
+// but use a different call shape: `binding.send({ to, from, ... })`.
 // Resend can slot in behind the same `sendMagicLink` signature if needed.
 
 /** Cloudflare Email Sending binding surface (the object-form `send`, not the MIME form). */
@@ -25,11 +25,18 @@ export async function sendMagicLink(
   from: string,
 ): Promise<void> {
   const expiry = "This link expires in 10 minutes and works only once. If you didn't request it, ignore this email.";
-  await sender.send({
-    to,
-    from,
-    subject: `Your ${siteName} sign-in link`,
-    text: `Sign in to ${siteName}:\n\n${link}\n\n${expiry}`,
-    html: `<p>Sign in to ${siteName}:</p><p><a href="${link}">Sign in</a></p><p style="color:#666;font-size:0.9em">${expiry}</p>`,
-  });
+  try {
+    await sender.send({
+      to,
+      from,
+      subject: `Your ${siteName} sign-in link`,
+      text: `Sign in to ${siteName}:\n\n${link}\n\n${expiry}`,
+      html: `<p>Sign in to ${siteName}:</p><p><a href="${link}">Confirm sign-in</a></p><p style="color:#666;font-size:0.9em">${expiry}</p>`,
+    });
+  } catch (err) {
+    // H6: Email Sending is beta + the sole auth channel. Surface + audit; a Resend fallback
+    // can slot in behind this same signature if Sending proves unreliable.
+    console.error(`magic-link email send failed for ${to}:`, err);
+    throw err;
+  }
 }

package/src/lib/github.ts

@@ -2,8 +2,8 @@
 //
 // Reads (Pass B) list a collection directory and fetch a file's raw markdown; the token
 // is optional because ecnordic's repo is public. Writes (Pass C) mint a short-lived
-// GitHub App installation token — App JWT (RS256) signed with Web Crypto, no octokit
-// dependency — and commit through the contents API with author = editor, committer = the
+// GitHub App installation token (App JWT, RS256 signed with Web Crypto, no octokit
+// dependency) and commit through the contents API with author = editor, committer = the
 // App (cairn-cms[bot]). The same token also lifts reads to the authenticated rate limit
 // and unlocks private repos (e.g. 907-life).
 
@@ -90,7 +90,7 @@ function derLength(n: number): number[] {
 // AlgorithmIdentifier for rsaEncryption (OID 1.2.840.113549.1.1.1) with NULL parameters.
 const RSA_ALG_ID = [0x30, 0x0d, 0x06, 0x09, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x01, 0x01, 0x01, 0x05, 0x00];
 
-/** Wrap a PKCS#1 RSAPrivateKey (DER) as PKCS#8 — the only RSA form Web Crypto importKey takes. */
+/** Wrap a PKCS#1 RSAPrivateKey (DER) as PKCS#8 (the only RSA form Web Crypto importKey takes). */
 function pkcs1ToPkcs8(pkcs1: Uint8Array): Uint8Array {
   const octet = [0x04, ...derLength(pkcs1.length), ...pkcs1];
   const body = [0x02, 0x01, 0x00, ...RSA_ALG_ID, ...octet];
@@ -124,7 +124,7 @@ export async function appJwt(appId: string, privateKeyPem: string): Promise<stri
 export interface AppCredentials {
   appId: string;
   installationId: string;
-  /** The stored GITHUB_APP_PRIVATE_KEY_B64 — base64 of the PEM, single line. */
+  /** The stored GITHUB_APP_PRIVATE_KEY_B64: base64 of the PEM, single line. */
   privateKeyB64: string;
 }
 
@@ -139,7 +139,7 @@ export async function installationToken(creds: AppCredentials): Promise<string>
   return ((await res.json()) as { token: string }).token;
 }
 
-/** Standard (padded) base64 of UTF-8 text — the encoding the contents API expects. */
+/** Standard (padded) base64 of UTF-8 text, as the contents API expects. */
 function toBase64(text: string): string {
   return btoa(Array.from(encoder.encode(text), (b) => String.fromCharCode(b)).join(''));
 }
@@ -157,11 +157,24 @@ export interface CommitAuthor {
   email: string;
 }
 
+/**
+ * A concurrent edit lost the SHA race (C3): the file changed between the read and the PUT,
+ * from another editor or the site's own CI. Thrown so callers can fail safe (re-fetch and ask
+ * the editor to reapply) instead of surfacing a raw 409. Defined and caught inside the package
+ * so `instanceof` is reliable (no peer-boundary identity split, unlike kit's `redirect`/`error`).
+ */
+export class CommitConflictError extends Error {
+  constructor(public readonly path: string) {
+    super(`Commit conflict on ${path}: it changed since it was opened`);
+    this.name = 'CommitConflictError';
+  }
+}
+
 /**
  * Commit `content` to `path` on the configured branch via the contents API. Author is the
  * editor; committer is omitted so GitHub attributes it to the App (cairn-cms[bot]). Updates
  * the file in place when it exists (passing its sha), creates it otherwise. Returns the
- * commit sha.
+ * commit sha. A stale-sha 409 (someone committed in between) becomes a `CommitConflictError`.
  */
 export async function commitFile(
   repo: RepoRef,
@@ -183,6 +196,25 @@ export async function commitFile(
       ...(sha ? { sha } : {}),
     }),
   });
+  // 409 = the blob sha we read is no longer current. Fail safe: the caller re-fetches and the
+  // editor reapplies. (Full three-way merge stays out of scope; see ARCHITECTURE §5.)
+  if (res.status === 409) throw new CommitConflictError(path);
   if (!res.ok) throw new Error(`GitHub commit ${path} failed: ${res.status} ${await res.text()}`);
   return ((await res.json()) as { commit: { sha: string } }).commit.sha;
 }
+
+/**
+ * Deploy-time self-test for the GitHub App signer (M2): sign a dummy JWT with the configured
+ * private key. Exercises the brittle PKCS#1→PKCS#8 conversion + Web Crypto import/sign without
+ * any network call or secret in the result, so `/admin/healthz` catches a bad/rotated key
+ * before an editor's save fails. Returns `{ ok: false, detail }` rather than throwing.
+ */
+export async function signingSelfTest(appId: string, privateKeyB64: string): Promise<{ ok: boolean; detail?: string }> {
+  try {
+    const jwt = await appJwt(appId, atob(privateKeyB64));
+    if (jwt.split('.').length !== 3) return { ok: false, detail: 'malformed JWT' };
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, detail: err instanceof Error ? err.message : 'sign failed' };
+  }
+}

package/src/lib/index.ts

@@ -1,7 +1,8 @@
-// cairn-cms public API. Consumers import everything from 'cairn-cms'.
-export * from './auth';
+// cairn-cms public API. Consumers import content/email/github/adapter from 'cairn-cms';
+// auth (better-auth factory, guards, manage-editors) lives at the 'cairn-cms/auth' subpath.
 export * from './email';
 export * from './github';
 export * from './carta';
 export * from './content';
 export * from './adapter';
+export * from './render';

package/src/lib/render/glyph.ts

@@ -0,0 +1,14 @@
+import { s } from 'hastscript';
+import type { Element } from 'hast';
+
+/** A glyph name → SVG path-data map (the site owns the icon set). */
+export type IconSet = Record<string, string>;
+
+/** Inline SVG glyph as a real hast node: class ec-glyph, 256 viewBox, currentColor fill. */
+export function glyph(name: string, icons: IconSet): Element {
+	return s(
+		'svg',
+		{ className: ['ec-glyph'], viewBox: '0 0 256 256', fill: 'currentColor', ariaHidden: 'true' },
+		[s('path', { d: icons[name] })],
+	);
+}

package/src/lib/render/index.ts

@@ -0,0 +1,8 @@
+// cairn-cms render engine: a directive-driven markdown → HTML pipeline whose
+// component vocabulary is supplied by a site's component registry. The site owns the
+// component builders, class names, icon set, and CSS; the engine owns the machinery.
+export * from './registry';
+export * from './glyph';
+export * from './remark-directives';
+export * from './rehype-dispatch';
+export * from './pipeline';

package/src/lib/render/pipeline.ts

@@ -0,0 +1,37 @@
+import { unified, type PluggableList } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkGfm from 'remark-gfm';
+import remarkDirective from 'remark-directive';
+import remarkRehype from 'remark-rehype';
+import rehypeRaw from 'rehype-raw';
+import rehypeSlug from 'rehype-slug';
+import rehypeStringify from 'rehype-stringify';
+import { remarkDirectiveStamp } from './remark-directives';
+import { rehypeDispatch } from './rehype-dispatch';
+import type { ComponentRegistry } from './registry';
+
+export interface RendererOptions {
+	/** A site's per-index motion formula for the top-level rise stagger
+	 *  (e.g. ecnordic's `(i) => '--rise:' + …`). Omit for no stagger. */
+	rise?: (idx: number) => string;
+}
+
+/** Compose a site's render pipeline from its component registry: directive syntax →
+ *  stamped markers → registry-built hast. Returns `renderMarkdown` plus the remark/
+ *  rehype plugin arrays (so the Carta editor preview can reuse the exact same set). */
+export function createRenderer(registry: ComponentRegistry, options: RendererOptions = {}) {
+	const remarkPlugins: PluggableList = [remarkDirective, [remarkDirectiveStamp, registry]];
+	const rehypePlugins: PluggableList = [rehypeRaw, [rehypeDispatch, registry, options.rise], rehypeSlug];
+	const processor = unified()
+		.use(remarkParse)
+		.use(remarkGfm)
+		.use(remarkPlugins)
+		.use(remarkRehype, { allowDangerousHtml: true })
+		.use(rehypePlugins)
+		.use(rehypeStringify);
+	return {
+		remarkPlugins,
+		rehypePlugins,
+		renderMarkdown: async (content: string): Promise<string> => String(await processor.process(content)),
+	};
+}