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

package/src/lib/content/types.ts

@@ -0,0 +1,235 @@
+// cairn-cms: the adapter contract a site implements, and the engine-internal descriptors
+// the contract normalizes into.
+//
+// The adapter is the single seam the engine consumes (spec §8). A site supplies a
+// `CairnAdapter` at `src/lib/cairn.config.ts` declaring its backend repo, the content
+// concepts it enables, its magic-link sender, and a design-accurate `renderPreview`. The
+// engine never hard-codes a concept, directory, or field; it reads them here. Field
+// descriptors are plain data so a `load` function can hand them across the server-to-client
+// boundary to the editor form.
+import type { ComponentRegistry } from '../render/registry.js';
+
+/** Common to every frontmatter field: the frontmatter key, the form label, and whether it is required. */
+interface FieldBase {
+  /** Frontmatter key and form input name. */
+  name: string;
+  /** Form label. */
+  label: string;
+  /** A required field fails validation when empty (spec §7.4). */
+  required?: boolean;
+}
+
+/** A single-line text input. */
+export interface TextField extends FieldBase {
+  type: 'text';
+}
+/** A multi-line text input. */
+export interface TextareaField extends FieldBase {
+  type: 'textarea';
+  /** Visible rows; the editor picks a default when omitted. */
+  rows?: number;
+}
+/** A `YYYY-MM-DD` date input. */
+export interface DateField extends FieldBase {
+  type: 'date';
+}
+/** A checkbox; absent means false. */
+export interface BooleanField extends FieldBase {
+  type: 'boolean';
+}
+/** A closed-vocabulary tag set, rendered as checkboxes (ecnordic). */
+export interface TagsField extends FieldBase {
+  type: 'tags';
+  /** The controlled vocabulary. */
+  options: readonly string[];
+}
+/** Free-form tags, edited as one comma-separated input (907). */
+export interface FreeTagsField extends FieldBase {
+  type: 'freetags';
+  placeholder?: string;
+}
+
+/**
+ * The discriminated union the per-concept frontmatter form is generated from. Adding a
+ * field type is one variant here plus one decode arm in `frontmatterFromForm` and one in
+ * `validateFields`.
+ */
+export type FrontmatterField =
+  | TextField
+  | TextareaField
+  | DateField
+  | BooleanField
+  | TagsField
+  | FreeTagsField;
+
+/**
+ * A validator's verdict. On success it carries the normalized frontmatter to commit; on
+ * failure it carries field-keyed error messages (the empty key is a form-level error).
+ * Invalid input bounces to the form and never reaches git (spec §7.4).
+ */
+export type ValidationResult =
+  | { ok: true; data: Record<string, unknown> }
+  | { ok: false; errors: Record<string, string> };
+
+/**
+ * Per-site configuration for one content concept (spec §8). Concept-fixed behavior such as
+ * routability is not here; it lives in the engine's routing table (`CONCEPT_ROUTING`).
+ */
+export interface ConceptConfig {
+  /** Repo-relative content directory, e.g. "src/content/posts". */
+  dir: string;
+  /** Sidebar label; defaults from the concept id when omitted. */
+  label?: string;
+  /** Drives the per-concept frontmatter form, in order. */
+  fields: FrontmatterField[];
+  /** Validate submitted frontmatter before any commit. */
+  validate(frontmatter: Record<string, unknown>, body: string): ValidationResult;
+}
+
+/** The GitHub App backend a site reads from and commits to (spec §8). Plain data the GitHub engine (Plan 03) consumes. */
+export interface BackendConfig {
+  owner: string;
+  repo: string;
+  /** Commit target, e.g. "main". */
+  branch: string;
+  appId: string;
+  installationId: string;
+}
+
+/** Magic-link sender identity for Cloudflare Email Sending. */
+export interface SenderConfig {
+  from: string;
+  replyTo?: string;
+}
+
+/** A git-committed YAML menu this site's nav editor manages (Plan 06). */
+export interface NavMenuConfig {
+  /** Repo-relative path to the site-config YAML, e.g. "src/lib/site.config.yaml". */
+  configPath: string;
+  /** Key within the file's menus map, e.g. "primary". */
+  menuName: string;
+  /** Sidebar label for the menu. */
+  label: string;
+  /** Max nesting depth allowed in the editor; defaults to 2. */
+  maxDepth?: number;
+}
+
+/** Reserved asset slot (seam 4). Typed and unused in the rebuild; R7/R9 read it later with no contract change. */
+export interface AssetConfig {
+  /** Repo-relative asset roots, e.g. ["static/images"]. */
+  roots: string[];
+  /** Public URL base, e.g. "/images". */
+  publicBase: string;
+}
+
+/** The single seam the engine consumes. A site implements this at `src/lib/cairn.config.ts`. */
+export interface CairnAdapter {
+  siteName: string;
+  /**
+   * Which content concepts this site enables. A future `fragments?` key attaches here with
+   * no reshape of the contract (seam 1). A site never has two of the same concept.
+   */
+  content: {
+    posts?: ConceptConfig;
+    pages?: ConceptConfig;
+  };
+  backend: BackendConfig;
+  sender: SenderConfig;
+  /** Design-accurate preview: the same render pipeline the site ships. */
+  renderPreview(md: string): string | Promise<string>;
+  /** Directive component registry; the renderer and the future palette derive from it (seam 3). */
+  registry?: ComponentRegistry;
+  navMenu?: NavMenuConfig;
+  assets?: AssetConfig;
+}
+
+/**
+ * Concept-fixed routing for a normalized concept (spec §7.2). Posts are dated feed entries;
+ * pages are plain navigable structure. Not in adapter config.
+ */
+export interface RoutingRule {
+  /** Routable as a standalone URL. A future Fragments concept is embedded, not routable. */
+  routable: boolean;
+  /** Carries a date (posts). */
+  dated: boolean;
+  /** Appears in feeds and the sitemap (posts). */
+  inFeeds: boolean;
+}
+
+/**
+ * The engine-internal, uniform view of one concept after normalization (seam 1). The admin
+ * nav, the list views, and the editor all read this, never the raw config.
+ */
+export interface ConceptDescriptor {
+  /** Concept id, the key under `content`, e.g. "posts". */
+  id: string;
+  label: string;
+  dir: string;
+  routing: RoutingRule;
+  fields: FrontmatterField[];
+  validate(frontmatter: Record<string, unknown>, body: string): ValidationResult;
+}
+
+/**
+ * A site-defined admin screen contributed by an extension (Mode 2). It gains a sidebar entry, the
+ * `/admin` guard, and the session, and may commit through the same GitHub pipeline. The dispatch
+ * route is built in Plan 09; the `load`/`actions`/`component` members are typed loosely here and
+ * tightened when the machinery lands.
+ */
+export interface AdminPanel {
+  /** Routes under `/admin/<id>`; also the sidebar key. */
+  id: string;
+  /** Sidebar label. */
+  label: string;
+  /** Owner-gated, like editor management. */
+  owner?: boolean;
+  /** Server load, behind the guard. Typed in Plan 09. */
+  load?: (event: unknown) => unknown;
+  /** Named form actions, which may use the commit pipeline. Typed in Plan 09. */
+  actions?: Record<string, (event: unknown) => Promise<unknown>>;
+  /** The panel UI, rendered inside the admin shell. Typed as a component in Plan 09. */
+  component: unknown;
+}
+
+/**
+ * A custom frontmatter field type contributed by an extension (Mode 2): a renderer plus a validator
+ * dispatched alongside the built-in field union. The renderer and validator are typed in Plan 09
+ * when the form dispatch becomes a registry; the `type` key reserves the discriminator now.
+ */
+export interface FieldTypeDef {
+  /** The field-type discriminator, e.g. "color". */
+  type: string;
+}
+
+/**
+ * A future build-time extension (seam 2). It folds in the same way the adapter does and
+ * contributes the same kinds of things. Reserved and unused in the rebuild; the shape is
+ * fixed now so the extension contract is additive later.
+ */
+export interface CairnExtension {
+  /** Additional concepts, merged after the adapter's. */
+  content?: Record<string, ConceptConfig>;
+  /** Site-defined admin panels (Mode 2). Carried onto the runtime now; dispatched in Plan 09. */
+  adminPanels?: AdminPanel[];
+  /** Custom field types (Mode 2). Carried onto the runtime now; dispatched in Plan 09. */
+  fieldTypes?: FieldTypeDef[];
+}
+
+/**
+ * The composed runtime the engine serves from (seam 2 output). The single aggregation point
+ * (`composeRuntime`) folds the adapter and any extensions into this shape.
+ */
+export interface CairnRuntime {
+  siteName: string;
+  concepts: ConceptDescriptor[];
+  backend: BackendConfig;
+  sender: SenderConfig;
+  renderPreview(md: string): string | Promise<string>;
+  registry?: ComponentRegistry;
+  navMenu?: NavMenuConfig;
+  assets?: AssetConfig;
+  /** Admin panels contributed by extensions (Mode 2). Empty until Plan 09 wires the dispatch route. */
+  adminPanels?: AdminPanel[];
+  /** Field types contributed by extensions (Mode 2). Empty until Plan 09 wires the form dispatch. */
+  fieldTypes?: FieldTypeDef[];
+}

package/src/lib/content/validate.ts

@@ -0,0 +1,51 @@
+// cairn-cms: the field-driven baseline validator. A site's `validate` calls this for the
+// required-and-coerce baseline, then layers any bespoke rules on top, so the per-site
+// validator stays thin (engine-fat rule). Saving runs the concept's validator on the
+// server before any commit; invalid input bounces to the form (spec §7.4).
+import type { FrontmatterField, ValidationResult } from './types.js';
+import { dateInputValue } from './frontmatter.js';
+
+/**
+ * Validate raw frontmatter against a field list. Required text and date fields must be
+ * non-empty; required tag fields must be non-empty lists. Booleans coerce to `true`/`false`
+ * and tag fields to string arrays. Returns the normalized data, or field-keyed errors when
+ * any required field is empty.
+ *
+ * Frontmatter may arrive from the edit form (all string values) or from `parseMarkdown`,
+ * where gray-matter turns an unquoted YAML date into a JS `Date`. The `date` case coerces a
+ * `Date` to `YYYY-MM-DD` so a valid parsed date is not mistaken for an empty one.
+ */
+export function validateFields(
+  fields: FrontmatterField[],
+  frontmatter: Record<string, unknown>,
+): ValidationResult {
+  const data: Record<string, unknown> = {};
+  const errors: Record<string, string> = {};
+  for (const field of fields) {
+    const value = frontmatter[field.name];
+    switch (field.type) {
+      case 'boolean':
+        data[field.name] = value === true;
+        break;
+      case 'tags':
+      case 'freetags': {
+        const list = Array.isArray(value) ? value.map(String) : [];
+        if (field.required && list.length === 0) errors[field.name] = `${field.label} is required`;
+        data[field.name] = list;
+        break;
+      }
+      case 'date': {
+        const text = value instanceof Date ? dateInputValue(value) : typeof value === 'string' ? value.trim() : '';
+        if (field.required && text === '') errors[field.name] = `${field.label} is required`;
+        data[field.name] = text;
+        break;
+      }
+      default: {
+        const text = typeof value === 'string' ? value.trim() : '';
+        if (field.required && text === '') errors[field.name] = `${field.label} is required`;
+        data[field.name] = text;
+      }
+    }
+  }
+  return Object.keys(errors).length > 0 ? { ok: false, errors } : { ok: true, data };
+}

package/src/lib/email.ts

@@ -1,42 +1,56 @@
-// cairn-core: pluggable magic-link email sender.
-//
-// 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.
+// The email boundary. The send is injected so tests capture links in a sink with no
+// send_email binding; production passes `cloudflareSend`, which calls env.EMAIL.send
+// (Cloudflare Email Sending, arbitrary recipients).
+import type { AuthEnv } from './auth/types.js';
 
-/** Cloudflare Email Sending binding surface (the object-form `send`, not the MIME form). */
-export interface EmailSender {
-  send(message: {
-    to: string;
-    from: string;
-    subject: string;
-    text?: string;
-    html?: string;
-  }): Promise<{ messageId: string }>;
+export type { AuthEnv };
+
+/** The message a built magic-link email carries. */
+export interface MagicLinkMessage {
+  to: string;
+  from: string;
+  subject: string;
+  html: string;
+  text: string;
+}
+
+/** Per-site identity for the magic-link email, sourced from the adapter. */
+export interface AuthBranding {
+  siteName: string;
+  from: string;
+  replyTo?: string;
 }
 
-export async function sendMagicLink(
-  sender: EmailSender,
-  to: string,
-  link: string,
-  siteName: string,
-  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.";
-  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;
-  }
+/** The injected send. Production uses `cloudflareSend`; tests pass a sink. */
+export type SendMagicLink = (env: AuthEnv, message: MagicLinkMessage) => Promise<void>;
+
+/** Escape the five HTML-significant characters. */
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
 }
+
+/** Build the confirmation email. The link is the only action; the copy stays plain. */
+export function buildMagicLinkMessage(input: {
+  to: string;
+  branding: AuthBranding;
+  link: string;
+}): MagicLinkMessage {
+  const { to, branding, link } = input;
+  const subject = `Sign in to ${branding.siteName}`;
+  const text = `Open this link to sign in to ${branding.siteName}:\n\n${link}\n\nThe link expires in 10 minutes. If you did not request it, ignore this email.`;
+  // `link` is engine-built and url-safe; `siteName` is site config, so escape it for HTML.
+  const name = escapeHtml(branding.siteName);
+  const html = `<p>Open this link to sign in to ${name}:</p><p><a href="${link}">Sign in</a></p><p>The link expires in 10 minutes. If you did not request it, ignore this email.</p>`;
+  return { to, from: branding.from, subject, html, text };
+}
+
+/** The production send: Cloudflare Email Sending through the EMAIL binding. */
+export const cloudflareSend: SendMagicLink = async (env, message) => {
+  if (!env.EMAIL) throw new Error('EMAIL binding is not configured');
+  await env.EMAIL.send(message);
+};

package/src/lib/env.ts

@@ -0,0 +1,32 @@
+import type { D1Database } from '@cloudflare/workers-types';
+
+/**
+ * Returns the site's public origin from configuration.
+ *
+ * The origin is always config-derived, never read from a request header, so a
+ * forged Host header cannot redirect a magic link (spec 7.1, risk H3).
+ *
+ * @throws Error when `PUBLIC_ORIGIN` is unset or empty.
+ */
+export function requireOrigin(env: { PUBLIC_ORIGIN?: string }): string {
+  const origin = env.PUBLIC_ORIGIN;
+  if (!origin) {
+    throw new Error('PUBLIC_ORIGIN is not configured');
+  }
+  return origin;
+}
+
+/**
+ * Returns the `AUTH_DB` binding, or throws a clear error when a site has not wired it.
+ *
+ * The handlers read D1 off `event.platform.env`; without this a misconfigured binding
+ * surfaces as a raw `TypeError` deep in a store call. This gives the failure a name.
+ *
+ * @throws Error when `AUTH_DB` is missing.
+ */
+export function requireDb(env: { AUTH_DB?: D1Database }): D1Database {
+  if (!env.AUTH_DB) {
+    throw new Error('AUTH_DB binding is not configured');
+  }
+  return env.AUTH_DB;
+}

package/src/lib/github/credentials.ts

@@ -0,0 +1,27 @@
+// src/lib/github/credentials.ts
+// cairn-cms: the bridge from the adapter's backend config and the Worker's secret to the
+// App signer's input. One tested place owns the join and the missing-secret failure, so the
+// save action (Plan 05) stays thin and a misconfigured Worker fails by name, not with a deep
+// TypeError. Mirrors requireDb/requireOrigin in env.ts.
+import type { BackendConfig } from '../content/types.js';
+import type { AppCredentials } from './types.js';
+
+/** The Worker secret holding the GitHub App private key: base64 of the PEM, single line. */
+export interface GithubKeyEnv {
+  GITHUB_APP_PRIVATE_KEY_B64?: string;
+}
+
+/**
+ * Assemble the `AppCredentials` the signer needs from the adapter's `backend` (app id,
+ * installation) and the Worker's private-key secret. Throws when the secret is unset.
+ */
+export function appCredentials(
+  backend: Pick<BackendConfig, 'appId' | 'installationId'>,
+  env: GithubKeyEnv,
+): AppCredentials {
+  const privateKeyB64 = env.GITHUB_APP_PRIVATE_KEY_B64;
+  if (!privateKeyB64) {
+    throw new Error('GITHUB_APP_PRIVATE_KEY_B64 is not configured');
+  }
+  return { appId: backend.appId, installationId: backend.installationId, privateKeyB64 };
+}

package/src/lib/github/repo.ts

@@ -0,0 +1,138 @@
+// src/lib/github/repo.ts
+// cairn-cms: repo reads and the commit, over the GitHub REST API. Listing a concept
+// directory uses the Git Trees API (the contents API silently truncates at 1,000 entries,
+// spec §7.3); a single-file read uses the contents API. An optional token lifts reads to
+// the authenticated rate limit and unlocks private repos; ecnordic's repo is public, 907's
+// is not.
+import { idFromFilename } from '../content/ids.js';
+import { CommitConflictError } from './types.js';
+import type { CommitAuthor, RepoFile, RepoRef } from './types.js';
+
+const API = 'https://api.github.com';
+
+/** Standard GitHub API headers, with a bearer token when one is supplied. */
+function ghHeaders(accept: string, token?: string): Record<string, string> {
+  const headers: Record<string, string> = {
+    Accept: accept,
+    'User-Agent': 'cairn-cms',
+    'X-GitHub-Api-Version': '2022-11-28',
+  };
+  if (token) headers.Authorization = `Bearer ${token}`;
+  return headers;
+}
+
+/** The recursive Git Trees API URL for the configured branch. */
+export function treeUrl(repo: RepoRef): string {
+  return `${API}/repos/${repo.owner}/${repo.repo}/git/trees/${encodeURIComponent(repo.branch)}?recursive=1`;
+}
+
+/** A Git Trees API entry: a full repo path and whether it is a blob or a subtree. */
+interface TreeEntry {
+  path: string;
+  type: string;
+}
+
+/** The basename of a repo path: the segment after the last slash. */
+function basename(path: string): string {
+  return path.slice(path.lastIndexOf('/') + 1);
+}
+
+/**
+ * Markdown files directly in `dir`, newest id first. Tree entries carry full repo paths, so
+ * the directory prefix is stripped to a basename before deriving the id. Nested files, non
+ * markdown, and other directories are dropped.
+ */
+export function markdownFilesIn(dir: string, tree: TreeEntry[]): RepoFile[] {
+  const clean = dir.replace(/^\/+|\/+$/g, '');
+  const prefix = `${clean}/`;
+  return tree
+    .filter((entry) => entry.type === 'blob' && entry.path.startsWith(prefix) && entry.path.endsWith('.md'))
+    .filter((entry) => !entry.path.slice(prefix.length).includes('/'))
+    .map((entry) => {
+      const name = basename(entry.path);
+      return { id: idFromFilename(name), name, path: entry.path };
+    })
+    .sort((a, b) => b.id.localeCompare(a.id));
+}
+
+/**
+ * List the markdown files in a concept directory through the Git Trees API. A truncated tree
+ * (GitHub caps the recursive listing near 100,000 entries) throws rather than returning a
+ * silent partial list; a concept directory sits far below that, and sharding is deferred
+ * until one approaches it (spec §7.3).
+ */
+export async function listMarkdown(repo: RepoRef, dir: string, token?: string): Promise<RepoFile[]> {
+  const res = await fetch(treeUrl(repo), { headers: ghHeaders('application/vnd.github+json', token) });
+  if (!res.ok) throw new Error(`GitHub tree ${repo.branch} failed: ${res.status}`);
+  const body = (await res.json()) as { tree: TreeEntry[]; truncated: boolean };
+  if (body.truncated) throw new Error(`GitHub tree ${repo.branch} is truncated; ${dir} exceeds the listing cap`);
+  return markdownFilesIn(dir, body.tree);
+}
+
+/** The contents-API URL for a repo path, pinned to the configured branch. */
+export function contentsUrl(repo: RepoRef, path: string): string {
+  const clean = path.replace(/^\/+|\/+$/g, '');
+  return `${API}/repos/${repo.owner}/${repo.repo}/contents/${clean}?ref=${encodeURIComponent(repo.branch)}`;
+}
+
+/**
+ * Fetch a file's raw markdown, or null if it does not exist. The contents API caps a raw
+ * read at 1 MB; a concept's files sit far below that, and sharding is deferred until one
+ * approaches it (spec §7.3).
+ */
+export async function readRaw(repo: RepoRef, path: string, token?: string): Promise<string | null> {
+  const res = await fetch(contentsUrl(repo, path), { headers: ghHeaders('application/vnd.github.raw', token) });
+  if (res.status === 404) return null;
+  if (!res.ok) throw new Error(`GitHub read ${path} failed: ${res.status}`);
+  return res.text();
+}
+
+/** Standard (padded) base64 of UTF-8 text, the form the contents API expects. */
+function toBase64(text: string): string {
+  return btoa(Array.from(new TextEncoder().encode(text), (b) => String.fromCharCode(b)).join(''));
+}
+
+/** The current blob sha for a path, or null if the file does not yet exist. */
+export async function fileSha(repo: RepoRef, path: string, token: string): Promise<string | null> {
+  const res = await fetch(contentsUrl(repo, path), { headers: ghHeaders('application/vnd.github+json', token) });
+  if (res.status === 404) return null;
+  if (!res.ok) throw new Error(`GitHub stat ${path} failed: ${res.status}`);
+  return ((await res.json()) as { sha: string }).sha;
+}
+
+/**
+ * Commit `content` to `path` on the configured branch through the contents API. The author is
+ * the editor; the 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. A stale-sha 409 (someone committed in between) becomes a `CommitConflictError`,
+ * so the save fails safe: re-fetch and ask the editor to reapply, never a merge.
+ *
+ * Caller preconditions this layer cannot enforce, and the save action (Plan 05) must:
+ * `path` is confined to the concept's configured directory (the App token can write anywhere
+ * in the repo, so an unvalidated path could overwrite CI config or source), and `author` is
+ * derived from the verified server-side session, never from request input.
+ */
+export async function commitFile(
+  repo: RepoRef,
+  path: string,
+  content: string,
+  opts: { message: string; author: CommitAuthor },
+  token: string,
+): Promise<string> {
+  const sha = await fileSha(repo, path, token);
+  const url = `${API}/repos/${repo.owner}/${repo.repo}/contents/${path.replace(/^\/+|\/+$/g, '')}`;
+  const res = await fetch(url, {
+    method: 'PUT',
+    headers: { ...ghHeaders('application/vnd.github+json', token), 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      message: opts.message,
+      content: toBase64(content),
+      branch: repo.branch,
+      author: opts.author,
+      ...(sha ? { sha } : {}),
+    }),
+  });
+  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;
+}

package/src/lib/github/signing.ts

@@ -0,0 +1,97 @@
+// src/lib/github/signing.ts
+// cairn-cms: the GitHub App auth path. Mint an RS256 App JWT signed in-Worker with Web
+// Crypto, exchange it for a short-lived installation access token, and self-test the
+// brittle key conversion. GitHub issues PKCS#1 private keys and Web Crypto's importKey
+// takes only PKCS#8, so the key is wrapped in-process. No octokit: it is heavy and pulls
+// Node built-ins the Worker bundle should not carry.
+import type { AppCredentials } from './types.js';
+
+const API = 'https://api.github.com';
+const encoder = new TextEncoder();
+
+/** Encode bytes as unpadded base64url (RFC 4648 §5), the JWT wire format. */
+function bytesToB64url(bytes: Uint8Array): string {
+  const binary = Array.from(bytes, (b) => String.fromCharCode(b)).join('');
+  return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', '');
+}
+
+// TextEncoder/atob produce Uint8Arrays whose generic buffer type no longer satisfies Web
+// Crypto's BufferSource under strict lib types; hand the underlying ArrayBuffer over.
+function buf(bytes: Uint8Array): ArrayBuffer {
+  return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
+}
+
+/** DER length octets for a value of `n` bytes (short form < 128, else long form). */
+function derLength(n: number): number[] {
+  if (n < 0x80) return [n];
+  const out: number[] = [];
+  for (let v = n; v > 0; v >>= 8) out.unshift(v & 0xff);
+  return [0x80 | out.length, ...out];
+}
+
+// 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). */
+function pkcs1ToPkcs8(pkcs1: Uint8Array): Uint8Array {
+  const octet = [0x04, ...derLength(pkcs1.length), ...pkcs1];
+  const body = [0x02, 0x01, 0x00, ...RSA_ALG_ID, ...octet];
+  return Uint8Array.from([0x30, ...derLength(body.length), ...body]);
+}
+
+/** Decode a PEM private key to PKCS#8 DER, converting from PKCS#1 (GitHub's format) if needed. */
+function pemToPkcs8(pem: string): Uint8Array {
+  const b64 = pem.replace(/-----[^-]+-----/g, '').replace(/\s+/g, '');
+  const der = Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
+  return pem.includes('RSA PRIVATE KEY') ? pkcs1ToPkcs8(der) : der;
+}
+
+/** Mint a GitHub App JWT (RS256), valid ~9 min, with `iat` backdated for clock skew. */
+export async function appJwt(appId: string, privateKeyPem: string): Promise<string> {
+  const now = Math.floor(Date.now() / 1000);
+  const header = bytesToB64url(encoder.encode(JSON.stringify({ alg: 'RS256', typ: 'JWT' })));
+  const payload = bytesToB64url(encoder.encode(JSON.stringify({ iat: now - 60, exp: now + 540, iss: appId })));
+  const signingInput = `${header}.${payload}`;
+  const key = await crypto.subtle.importKey(
+    'pkcs8',
+    buf(pemToPkcs8(privateKeyPem)),
+    { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' },
+    false,
+    ['sign'],
+  );
+  const sig = await crypto.subtle.sign('RSASSA-PKCS1-v1_5', key, buf(encoder.encode(signingInput)));
+  return `${signingInput}.${bytesToB64url(new Uint8Array(sig))}`;
+}
+
+/** Exchange the App JWT for a short-lived installation access token. */
+export async function installationToken(creds: AppCredentials): Promise<string> {
+  const jwt = await appJwt(creds.appId, atob(creds.privateKeyB64));
+  const res = await fetch(`${API}/app/installations/${creds.installationId}/access_tokens`, {
+    method: 'POST',
+    headers: {
+      Accept: 'application/vnd.github+json',
+      Authorization: `Bearer ${jwt}`,
+      'User-Agent': 'cairn-cms',
+      'X-GitHub-Api-Version': '2022-11-28',
+    },
+  });
+  if (!res.ok) throw new Error(`GitHub installation token failed: ${res.status}`);
+  return ((await res.json()) as { token: string }).token;
+}
+
+/**
+ * Deploy-time self-test for the App signer: sign a dummy JWT with the configured key. It
+ * exercises the brittle PKCS#1-to-PKCS#8 conversion and the Web Crypto import and sign with
+ * no network call and no secret in the result, so `/admin/healthz` (Plan 05) catches a bad
+ * or rotated key before an editor's save fails. The `detail` is a fixed classifier, never the
+ * raw crypto error, so the surfaced health result cannot echo key bytes. Never throws.
+ */
+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 {
+    return { ok: false, detail: 'key import or sign failed' };
+  }
+}