@glw907/cairn-cms 0.1.0

package/src/lib/github.ts

@@ -0,0 +1,188 @@
+// cairn-core: read and write repository content through the GitHub API.
+//
+// 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
+// App (cairn-cms[bot]). The same token also lifts reads to the authenticated rate limit
+// and unlocks private repos (e.g. 907-life).
+
+import { bytesToB64url } from './utils';
+
+export interface RepoRef {
+  owner: string;
+  repo: string;
+  branch: string;
+}
+
+/** A markdown file in a collection directory. `id` is the slug (filename without `.md`). */
+export interface RepoFile {
+  id: string;
+  name: string;
+  path: string;
+}
+
+const API = 'https://api.github.com';
+
+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;
+}
+
+/** Build 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)}`;
+}
+
+interface ContentsEntry {
+  name: string;
+  path: string;
+  type: string;
+}
+
+/** Keep only markdown files from a contents-API directory listing, newest id first. */
+export function markdownFiles(entries: ContentsEntry[]): RepoFile[] {
+  return entries
+    .filter((entry) => entry.type === 'file' && entry.name.endsWith('.md'))
+    .map((entry) => ({ id: entry.name.replace(/\.md$/, ''), name: entry.name, path: entry.path }))
+    .sort((a, b) => b.id.localeCompare(a.id));
+}
+
+/** List the markdown files in a collection directory. */
+export async function listMarkdown(repo: RepoRef, dir: string, token?: string): Promise<RepoFile[]> {
+  const res = await fetch(contentsUrl(repo, dir), { headers: ghHeaders('application/vnd.github+json', token) });
+  if (!res.ok) throw new Error(`GitHub list ${dir} failed: ${res.status}`);
+  return markdownFiles((await res.json()) as ContentsEntry[]);
+}
+
+/** Fetch a file's raw markdown, or null if it does not exist. */
+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();
+}
+
+// --- Write path: GitHub App auth + commit (Pass C) -------------------------------------
+
+const encoder = new TextEncoder();
+
+// 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))}`;
+}
+
+export interface AppCredentials {
+  appId: string;
+  installationId: string;
+  /** The stored GITHUB_APP_PRIVATE_KEY_B64 — base64 of the PEM, single line. */
+  privateKeyB64: string;
+}
+
+/** 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: ghHeaders('application/vnd.github+json', jwt),
+  });
+  if (!res.ok) throw new Error(`GitHub installation token failed: ${res.status}`);
+  return ((await res.json()) as { token: string }).token;
+}
+
+/** Standard (padded) base64 of UTF-8 text — the encoding the contents API expects. */
+function toBase64(text: string): string {
+  return btoa(Array.from(encoder.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;
+}
+
+export interface CommitAuthor {
+  name: string;
+  email: string;
+}
+
+/**
+ * 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.
+ */
+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.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/index.ts

@@ -0,0 +1,7 @@
+// cairn-cms public API. Consumers import everything from 'cairn-cms'.
+export * from './auth';
+export * from './email';
+export * from './github';
+export * from './carta';
+export * from './content';
+export * from './adapter';

package/src/lib/sveltekit/index.ts

@@ -0,0 +1,272 @@
+// 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)`).
+//
+// 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).
+import { redirect, error, type Cookies } from '@sveltejs/kit';
+import type { KVNamespace } from '@cloudflare/workers-types';
+import matter from 'gray-matter';
+import {
+  createMagicLink,
+  redeemMagicToken,
+  createSession,
+  lookupEditor,
+  SESSION_COOKIE,
+  SESSION_MAX_AGE,
+  type Editor,
+} from '../auth';
+import { sendMagicLink, type EmailSender } from '../email';
+import { listMarkdown, readRaw, commitFile, installationToken, type RepoFile } from '../github';
+import { serializeMarkdown } from '../content';
+import { findCollection, frontmatterFromForm, type CairnAdapter, type CairnField } from '../adapter';
+
+/** The `platform.env` bindings the admin routes read. All optional — the handlers guard. */
+export interface AdminEnv {
+  AUTH_KV?: KVNamespace;
+  MAGIC_LINK_SECRET?: string;
+  SESSION_SECRET?: string;
+  EMAIL?: EmailSender;
+  /** Overrides `url.origin` for the magic-link base (set in dev, unset in prod). */
+  PUBLIC_ORIGIN?: string;
+  GITHUB_APP_ID?: string;
+  GITHUB_APP_INSTALLATION_ID?: string;
+  GITHUB_APP_PRIVATE_KEY_B64?: string;
+}
+
+interface PlatformEvent {
+  platform?: { env?: AdminEnv };
+}
+
+const EMAIL_RE = /^[^@\s]+@[^@\s]+\.[^@\s]+$/;
+
+// ── /admin layout ──────────────────────────────────────────────────────────
+
+export interface AdminLayoutData {
+  editor: Editor | null;
+  siteName: string;
+}
+
+/**
+ * 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.
+ */
+export function adminLayoutLoad(
+  event: { locals: { editor: Editor | null } },
+  adapter: CairnAdapter,
+): AdminLayoutData {
+  return { editor: event.locals.editor, siteName: adapter.siteName };
+}
+
+// ── /admin (content list) ────────────────────────────────────────────────────
+
+export interface AdminCollectionList {
+  type: string;
+  label: string;
+  files: RepoFile[];
+  error?: string;
+}
+
+/** List every collection's markdown files. A failed listing degrades to an inline error. */
+export async function adminListLoad(adapter: CairnAdapter): Promise<{ collections: AdminCollectionList[] }> {
+  const collections = await Promise.all(
+    adapter.collections.map(async ({ type, label, dir }): Promise<AdminCollectionList> => {
+      try {
+        return { type, label, files: await listMarkdown(adapter.backend, dir) };
+      } catch (err) {
+        // A failed listing (rate limit, network) shouldn't 500 the whole admin.
+        return { type, label, files: [], error: err instanceof Error ? err.message : 'Failed to load' };
+      }
+    }),
+  );
+  return { collections };
+}
+
+// ── /admin/login ──────────────────────────────────────────────────────────────
+
+export interface LoginData {
+  sent: boolean;
+  error: string | null;
+}
+
+export function loginLoad(event: { url: URL }): LoginData {
+  return {
+    sent: event.url.searchParams.get('sent') === '1',
+    error: event.url.searchParams.get('error'),
+  };
+}
+
+// ── /admin/edit/[type]/[id] ─────────────────────────────────────────────────
+
+export interface EditData {
+  type: string;
+  id: string;
+  label: string;
+  fields: CairnField[];
+  path: string;
+  body: string;
+  frontmatter: Record<string, unknown>;
+  title: string;
+  saved: boolean;
+  error: string | null;
+}
+
+export async function editLoad(
+  event: { params: { type: string; id: string }; url: URL },
+  adapter: CairnAdapter,
+): Promise<EditData> {
+  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 path = `${collection.dir}/${event.params.id}.md`;
+  const raw = await readRaw(adapter.backend, path);
+  if (raw === null) throw error(404, 'Content not found');
+
+  // Split frontmatter from body server-side; the editor form binds to the frontmatter and
+  // the Carta editor binds to the body, and /admin/save reassembles them on commit.
+  const { data: frontmatter, content: body } = matter(raw);
+
+  return {
+    type: event.params.type,
+    id: event.params.id,
+    label: collection.label,
+    fields: collection.fields,
+    path,
+    body,
+    frontmatter,
+    title: typeof frontmatter.title === 'string' ? frontmatter.title : event.params.id,
+    saved: event.url.searchParams.get('saved') === '1',
+    error: event.url.searchParams.get('error'),
+  };
+}
+
+// ── /admin/auth/request (POST) ──────────────────────────────────────────────
+
+export async function authRequest(
+  event: PlatformEvent & { request: Request; url: URL },
+  adapter: CairnAdapter,
+): Promise<never> {
+  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: PlatformEvent & { url: URL; cookies: Cookies },
+): Promise<never> {
+  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: { cookies: Cookies }): never {
+  event.cookies.delete(SESSION_COOKIE, { path: '/' });
+  throw redirect(303, '/admin/login');
+}
+
+// ── /admin/save (POST) ──────────────────────────────────────────────────────
+
+export async function saveCommit(
+  event: PlatformEvent & { request: Request; locals: { editor: Editor | null } },
+  adapter: CairnAdapter,
+): Promise<never> {
+  const editor = event.locals.editor;
+  if (!editor) 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) {
+    throw error(500, 'GitHub App is not configured');
+  }
+
+  const form = await event.request.formData();
+  const type = String(form.get('type') ?? '');
+  const id = String(form.get('id') ?? '');
+  const body = String(form.get('body') ?? '');
+  const collection = findCollection(adapter, type);
+  if (!collection || !id) throw error(400, 'Bad request');
+
+  // Build frontmatter from the posted fields and validate against the collection's schema; a
+  // bad field bounces back to the editor with the validator's message rather than 500ing.
+  let frontmatter: object;
+  try {
+    frontmatter = collection.validate(frontmatterFromForm(collection, form), `${id}.md`);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : 'Invalid frontmatter';
+    throw redirect(303, `/admin/edit/${type}/${id}?error=${encodeURIComponent(message)}`);
+  }
+
+  const markdown = serializeMarkdown(frontmatter, body);
+  const token = await installationToken({
+    appId: env.GITHUB_APP_ID,
+    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,
+  );
+
+  throw redirect(303, `/admin/edit/${type}/${id}?saved=1`);
+}

package/src/lib/utils.ts

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