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

package/dist/email.js

@@ -1,25 +1,25 @@
-// 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.
-export async function sendMagicLink(sender, to, link, siteName, from) {
-    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;
-    }
+/** Escape the five HTML-significant characters. */
+function escapeHtml(value) {
+    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) {
+    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 = async (env, message) => {
+    if (!env.EMAIL)
+        throw new Error('EMAIL binding is not configured');
+    await env.EMAIL.send(message);
+};

package/dist/env.d.ts

@@ -0,0 +1,24 @@
+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 declare function requireOrigin(env: {
+    PUBLIC_ORIGIN?: string;
+}): string;
+/**
+ * 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 declare function requireDb(env: {
+    AUTH_DB?: D1Database;
+}): D1Database;
+//# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/lib/env.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAMrE;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE;IAAE,OAAO,CAAC,EAAE,UAAU,CAAA;CAAE,GAAG,UAAU,CAKnE"}

package/dist/env.js

@@ -0,0 +1,29 @@
+/**
+ * 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) {
+    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) {
+    if (!env.AUTH_DB) {
+        throw new Error('AUTH_DB binding is not configured');
+    }
+    return env.AUTH_DB;
+}

package/dist/github/credentials.d.ts

@@ -0,0 +1,12 @@
+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 declare function appCredentials(backend: Pick<BackendConfig, 'appId' | 'installationId'>, env: GithubKeyEnv): AppCredentials;
+//# sourceMappingURL=credentials.d.ts.map

package/dist/github/credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../../src/lib/github/credentials.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,4FAA4F;AAC5F,MAAM,WAAW,YAAY;IAC3B,0BAA0B,CAAC,EAAE,MAAM,CAAC;CACrC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,OAAO,GAAG,gBAAgB,CAAC,EACxD,GAAG,EAAE,YAAY,GAChB,cAAc,CAMhB"}

package/dist/github/credentials.js

@@ -0,0 +1,11 @@
+/**
+ * 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, env) {
+    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/dist/github/repo.d.ts

@@ -0,0 +1,49 @@
+import type { CommitAuthor, RepoFile, RepoRef } from './types.js';
+/** The recursive Git Trees API URL for the configured branch. */
+export declare function treeUrl(repo: RepoRef): string;
+/** A Git Trees API entry: a full repo path and whether it is a blob or a subtree. */
+interface TreeEntry {
+    path: string;
+    type: string;
+}
+/**
+ * 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 declare function markdownFilesIn(dir: string, tree: TreeEntry[]): RepoFile[];
+/**
+ * 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 declare function listMarkdown(repo: RepoRef, dir: string, token?: string): Promise<RepoFile[]>;
+/** The contents-API URL for a repo path, pinned to the configured branch. */
+export declare function contentsUrl(repo: RepoRef, path: string): string;
+/**
+ * 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 declare function readRaw(repo: RepoRef, path: string, token?: string): Promise<string | null>;
+/** The current blob sha for a path, or null if the file does not yet exist. */
+export declare function fileSha(repo: RepoRef, path: string, token: string): Promise<string | null>;
+/**
+ * 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 declare function commitFile(repo: RepoRef, path: string, content: string, opts: {
+    message: string;
+    author: CommitAuthor;
+}, token: string): Promise<string>;
+export {};
+//# sourceMappingURL=repo.d.ts.map

package/dist/github/repo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo.d.ts","sourceRoot":"","sources":["../../src/lib/github/repo.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAelE,iEAAiE;AACjE,wBAAgB,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAE7C;AAED,qFAAqF;AACrF,UAAU,SAAS;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAOD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,QAAQ,EAAE,CAW1E;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAMlG;AAED,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAG/D;AAED;;;;GAIG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAKjG;AAOD,+EAA+E;AAC/E,wBAAsB,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAKhG;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,EAC/C,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,CAiBjB"}

package/dist/github/repo.js

@@ -0,0 +1,123 @@
+// 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';
+const API = 'https://api.github.com';
+/** Standard GitHub API headers, with a bearer token when one is supplied. */
+function ghHeaders(accept, token) {
+    const headers = {
+        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) {
+    return `${API}/repos/${repo.owner}/${repo.repo}/git/trees/${encodeURIComponent(repo.branch)}?recursive=1`;
+}
+/** The basename of a repo path: the segment after the last slash. */
+function basename(path) {
+    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, tree) {
+    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, dir, token) {
+    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());
+    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, path) {
+    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, path, token) {
+    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) {
+    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, path, token) {
+    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()).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, path, content, opts, token) {
+    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()).commit.sha;
+}

package/dist/github/signing.d.ts

@@ -0,0 +1,17 @@
+import type { AppCredentials } from './types.js';
+/** Mint a GitHub App JWT (RS256), valid ~9 min, with `iat` backdated for clock skew. */
+export declare function appJwt(appId: string, privateKeyPem: string): Promise<string>;
+/** Exchange the App JWT for a short-lived installation access token. */
+export declare function installationToken(creds: AppCredentials): Promise<string>;
+/**
+ * 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 declare function signingSelfTest(appId: string, privateKeyB64: string): Promise<{
+    ok: boolean;
+    detail?: string;
+}>;
+//# sourceMappingURL=signing.d.ts.map

package/dist/github/signing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signing.d.ts","sourceRoot":"","sources":["../../src/lib/github/signing.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AA0CjD,wFAAwF;AACxF,wBAAsB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAclF;AAED,wEAAwE;AACxE,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAa9E;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAQrH"}

package/dist/github/signing.js

@@ -0,0 +1,79 @@
+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) {
+    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) {
+    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}
+/** DER length octets for a value of `n` bytes (short form < 128, else long form). */
+function derLength(n) {
+    if (n < 0x80)
+        return [n];
+    const out = [];
+    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) {
+    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) {
+    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, privateKeyPem) {
+    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) {
+    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()).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, privateKeyB64) {
+    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' };
+    }
+}

package/dist/github/types.d.ts

@@ -0,0 +1,35 @@
+/** Repo coordinates pinned to a branch: the structural subset of `BackendConfig` the read and commit paths need. */
+export interface RepoRef {
+    owner: string;
+    repo: string;
+    branch: string;
+}
+/** A markdown file in a concept directory. `id` is the filename without `.md`. */
+export interface RepoFile {
+    id: string;
+    name: string;
+    path: string;
+}
+/** A commit author: the signed-in editor (spec §7.4). The committer is left to the App. */
+export interface CommitAuthor {
+    name: string;
+    email: string;
+}
+/** What the App signer needs: the app id, the installation, and the base64 PEM secret. */
+export interface AppCredentials {
+    appId: string;
+    installationId: string;
+    /** The stored `GITHUB_APP_PRIVATE_KEY_B64`: base64 of the PEM, single line. */
+    privateKeyB64: string;
+}
+/**
+ * A concurrent edit lost the SHA race: the file changed between the read and the PUT, from
+ * another editor or the site's own CI. Thrown so the save fails 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, unlike kit's `redirect`/`error` across the peer boundary.
+ */
+export declare class CommitConflictError extends Error {
+    readonly path: string;
+    constructor(path: string);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/github/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lib/github/types.ts"],"names":[],"mappings":"AAMA,oHAAoH;AACpH,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,kFAAkF;AAClF,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,2FAA2F;AAC3F,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,0FAA0F;AAC1F,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;aAChB,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM;CAIzC"}

package/dist/github/types.js

@@ -0,0 +1,19 @@
+// src/lib/github/types.ts
+// cairn-cms: the GitHub backend's plain data types and its one typed error. The backend
+// reads repo coordinates from the adapter's `BackendConfig` (spec §8); `RepoRef` is the
+// `{ owner, repo, branch }` subset, so `backend` is assignable wherever a `RepoRef` is
+// wanted with no conversion.
+/**
+ * A concurrent edit lost the SHA race: the file changed between the read and the PUT, from
+ * another editor or the site's own CI. Thrown so the save fails 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, unlike kit's `redirect`/`error` across the peer boundary.
+ */
+export class CommitConflictError extends Error {
+    path;
+    constructor(path) {
+        super(`Commit conflict on ${path}: it changed since it was opened`);
+        this.path = path;
+        this.name = 'CommitConflictError';
+    }
+}

package/dist/index.d.ts

@@ -1,9 +1,28 @@
-export * from './email';
-export * from './github';
-export * from './carta';
-export * from './content';
-export * from './adapter';
-export * from './slug';
-export * from './render';
-export * from './nav';
+export { requireOrigin } from './env.js';
+export type { Role, Editor, AuthEnv } from './auth/types.js';
+export type { AuthBranding, MagicLinkMessage, SendMagicLink } from './email.js';
+export { buildMagicLinkMessage, cloudflareSend } from './email.js';
+export type { CairnAdapter, ConceptConfig, FrontmatterField, TextField, TextareaField, DateField, BooleanField, TagsField, FreeTagsField, ValidationResult, BackendConfig, SenderConfig, NavMenuConfig, AssetConfig, RoutingRule, ConceptDescriptor, CairnExtension, CairnRuntime, AdminPanel, FieldTypeDef, } from './content/types.js';
+export { CONCEPT_ROUTING, normalizeConcepts, findConcept } from './content/concepts.js';
+export { composeRuntime } from './content/compose.js';
+export { frontmatterFromForm, dateInputValue, serializeMarkdown, parseMarkdown, } from './content/frontmatter.js';
+export { validateFields } from './content/validate.js';
+export { isValidId, idFromFilename, filenameFromId, slugify } from './content/ids.js';
+export { defineRegistry } from './render/registry.js';
+export type { ComponentDef, ComponentRegistry } from './render/registry.js';
+export { glyph } from './render/glyph.js';
+export type { IconSet } from './render/glyph.js';
+export { remarkDirectiveStamp } from './render/remark-directives.js';
+export { rehypeDispatch, isElement, strProp, iconSpan, splitHead, cardShell, markFirstList, } from './render/rehype-dispatch.js';
+export type { MakeIcon } from './render/rehype-dispatch.js';
+export { createRenderer } from './render/pipeline.js';
+export type { RendererOptions } from './render/pipeline.js';
+export type { RepoRef, RepoFile, CommitAuthor, AppCredentials } from './github/types.js';
+export { CommitConflictError } from './github/types.js';
+export { appJwt, installationToken, signingSelfTest } from './github/signing.js';
+export { treeUrl, markdownFilesIn, listMarkdown, contentsUrl, readRaw, fileSha, commitFile, } from './github/repo.js';
+export { appCredentials } from './github/credentials.js';
+export type { GithubKeyEnv } from './github/credentials.js';
+export { parseSiteConfig, extractMenu, setMenu, validateNavTree, MAX_NAV_NODES, NavValidationError, SiteConfigError, } from './nav/site-config.js';
+export type { NavNode, SiteConfig } from './nav/site-config.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/lib/index.ts"],"names":[],"mappings":"AAEA,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,OAAO,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/lib/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC7D,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChF,OAAO,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGnE,YAAY,EACV,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,SAAS,EACT,aAAa,EACb,SAAS,EACT,YAAY,EACZ,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,aAAa,EACb,WAAW,EACX,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,YAAY,EACZ,UAAU,EACV,YAAY,GACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACxF,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,aAAa,GACd,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAEtF,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC5E,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1C,YAAY,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,EACL,cAAc,EACd,SAAS,EACT,OAAO,EACP,QAAQ,EACR,SAAS,EACT,SAAS,EACT,aAAa,GACd,MAAM,6BAA6B,CAAC;AACrC,YAAY,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAG5D,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACzF,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACjF,OAAO,EACL,OAAO,EACP,eAAe,EACf,YAAY,EACZ,WAAW,EACX,OAAO,EACP,OAAO,EACP,UAAU,GACX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,YAAY,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAG5D,OAAO,EACL,eAAe,EACf,WAAW,EACX,OAAO,EACP,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -1,10 +1,21 @@
-// 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 './slug';
-export * from './render';
-export * from './nav';
+// Engine entry. Auth landed in Plan 01, the content model and adapter in Plan 02, and the
+// GitHub read-and-commit backend in Plan 03; render and nav follow.
+export { requireOrigin } from './env.js';
+export { buildMagicLinkMessage, cloudflareSend } from './email.js';
+export { CONCEPT_ROUTING, normalizeConcepts, findConcept } from './content/concepts.js';
+export { composeRuntime } from './content/compose.js';
+export { frontmatterFromForm, dateInputValue, serializeMarkdown, parseMarkdown, } from './content/frontmatter.js';
+export { validateFields } from './content/validate.js';
+export { isValidId, idFromFilename, filenameFromId, slugify } from './content/ids.js';
+// Render engine (Plan 04): generic directive pipeline; sites own the component registry.
+export { defineRegistry } from './render/registry.js';
+export { glyph } from './render/glyph.js';
+export { remarkDirectiveStamp } from './render/remark-directives.js';
+export { rehypeDispatch, isElement, strProp, iconSpan, splitHead, cardShell, markFirstList, } from './render/rehype-dispatch.js';
+export { createRenderer } from './render/pipeline.js';
+export { CommitConflictError } from './github/types.js';
+export { appJwt, installationToken, signingSelfTest } from './github/signing.js';
+export { treeUrl, markdownFilesIn, listMarkdown, contentsUrl, readRaw, fileSha, commitFile, } from './github/repo.js';
+export { appCredentials } from './github/credentials.js';
+// Nav tree and site-config helpers (Plan 06).
+export { parseSiteConfig, extractMenu, setMenu, validateNavTree, MAX_NAV_NODES, NavValidationError, SiteConfigError, } from './nav/site-config.js';

package/dist/{nav.d.ts → nav/site-config.d.ts}

@@ -1,4 +1,4 @@
-/** One navigation node. `url` omitted/empty is a label-only grouping header; `children` omitted is a leaf. */
+/** One navigation node. An omitted or empty `url` is a label-only grouping header; no `children` is a leaf. */
 export interface NavNode {
     label: string;
     url?: string;
@@ -6,18 +6,22 @@ export interface NavNode {
 }
 /** Total node cap across the whole tree, a guard against a runaway payload. */
 export declare const MAX_NAV_NODES = 200;
+/** Maximum character length for a node label. */
+export declare const MAX_LABEL_LENGTH = 500;
+/** Maximum character length for a node URL. */
+export declare const MAX_URL_LENGTH = 2048;
 export declare class NavValidationError extends Error {
     constructor(message: string);
 }
 /**
- * Validate and normalize an untrusted value into a NavNode[]: arrays only, non-empty labels,
- * depth within `maxDepth` (1 = flat), bounded node count, and only the three known keys kept.
- * Throws NavValidationError on any violation. Used by `navSave` before writing.
+ * Validate and normalize an untrusted value into a NavNode[]: arrays only, non-empty labels, depth
+ * within `maxDepth` (1 is flat), a bounded node count, and only the three known keys kept. Throws
+ * NavValidationError on any violation. Used by navSave before writing.
  */
 export declare function validateNavTree(value: unknown, maxDepth: number): NavNode[];
 /**
- * Shape of the YAML site-config file. Unknown keys are ignored so the file can grow without
- * an engine change. Read at build time by the public site.
+ * Shape of the YAML site-config file. Unknown keys are ignored so the file can grow without an
+ * engine change. Read at build time by the public site.
  */
 export interface SiteConfig {
     siteName: string;
@@ -27,19 +31,7 @@ export interface SiteConfig {
     locale?: string;
     /** Named navigation menus, each a NavNode[] (normalized by extractMenu). */
     menus?: Record<string, unknown>;
-    email?: {
-        sender?: string;
-        senderName?: string;
-    };
-    footer?: {
-        copyrightName?: string;
-    };
-    settings?: {
-        feedMaxItems?: number;
-        homepageFeaturedCount?: number;
-        postTags?: string[];
-        [key: string]: unknown;
-    };
+    [key: string]: unknown;
 }
 export declare class SiteConfigError extends Error {
     constructor(message: string);
@@ -49,10 +41,10 @@ export declare function parseSiteConfig(raw: string): SiteConfig;
 /** Extract one named menu from a parsed config and validate it. Returns [] when the menu is absent. */
 export declare function extractMenu(config: SiteConfig, name: string, maxDepth: number): NavNode[];
 /**
- * Replace one named menu in the YAML site-config text and re-serialize, preserving every other
- * top-level key (siteName, other menus, settings, ...). The `/admin/nav` editor commits the result.
- * Parses into a Document so the rest of the file round-trips; YAML comments are not preserved
- * (an accepted trade), but data keys are. A leaf node serializes without `url`/`children` keys.
+ * Replace one named menu in the YAML site-config text and reserialize, preserving every other
+ * top-level key (siteName, other menus, settings). Parses into a Document so the rest of the file
+ * round-trips. YAML comments are not preserved (an accepted trade); data keys are. A leaf node
+ * serializes without `url`/`children` keys.
  */
 export declare function setMenu(raw: string, name: string, tree: NavNode[]): string;
-//# sourceMappingURL=nav.d.ts.map
+//# sourceMappingURL=site-config.d.ts.map

package/dist/nav/site-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"site-config.d.ts","sourceRoot":"","sources":["../../src/lib/nav/site-config.ts"],"names":[],"mappings":"AAMA,+GAA+G;AAC/G,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;CACtB;AAED,+EAA+E;AAC/E,eAAO,MAAM,aAAa,MAAM,CAAC;AAEjC,iDAAiD;AACjD,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,+CAA+C;AAC/C,eAAO,MAAM,cAAc,OAAO,CAAC;AAKnC,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,EAAE,CA6B3E;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AAED,uGAAuG;AACvG,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAUvD;AAED,uGAAuG;AACvG,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,EAAE,CAIzF;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,CAO1E"}