@glw907/cairn-cms 0.14.0 → 0.18.0

package/src/lib/render/resolve-links.ts

@@ -0,0 +1,42 @@
+// cairn-cms: the cairn: link resolver, an mdast step in the render pipeline (content-graph design).
+// It runs before remark-rehype, so the rewritten href passes through the sanitize floor exactly as
+// any other anchor. The per-call resolver is read off the VFile (set by renderMarkdown), so the
+// processor is still built once. A miss either marks the link broken (preview) or throws (build),
+// decided by the injected resolver.
+import { visit } from 'unist-util-visit';
+import type { VFile } from 'vfile';
+import { parseCairnToken, type LinkResolve } from '../content/links.js';
+
+/** The VFile data key the renderer sets the per-call resolver under. */
+export const CAIRN_RESOLVE = 'cairnResolve';
+
+interface LinkNode {
+  url: string;
+  data?: { hProperties?: Record<string, unknown> };
+}
+
+/** Resolve cairn: link nodes against the VFile's resolver. A non-cairn href and a malformed token
+ *  pass through. A missing target is marked with the cairn-broken-link class (the resolver returns
+ *  undefined) or, when the resolver throws, the error propagates and fails the build. */
+export function remarkResolveCairnLinks() {
+  return (tree: unknown, file: VFile): void => {
+    const resolve = file.data[CAIRN_RESOLVE] as LinkResolve | undefined;
+    if (!resolve) return;
+    visit(tree as Parameters<typeof visit>[0], 'link', (node: LinkNode) => {
+      const ref = parseCairnToken(node.url);
+      if (!ref) return;
+      const url = resolve(ref); // may throw (build backstop); propagates out of render
+      if (url) {
+        node.url = url;
+        return;
+      }
+      // Missing target in the preview: mark it broken and neutralize the href, keeping the text.
+      node.url = '#';
+      node.data = node.data ?? {};
+      const props = (node.data.hProperties = node.data.hProperties ?? {});
+      const existing = Array.isArray(props.className) ? (props.className as string[]) : [];
+      props.className = [...existing, 'cairn-broken-link'];
+      props.title = 'Broken internal link';
+    });
+  };
+}

package/src/lib/render/sanitize-schema.ts

@@ -0,0 +1,66 @@
+import { defaultSchema, type Schema } from 'hast-util-sanitize';
+import type { Root, Element } from 'hast';
+import { visit } from 'unist-util-visit';
+import { dataAttrProp, type ComponentRegistry } from './registry.js';
+
+// The fixed directive markers the stamp writes and the dispatch reads. They are inert data
+// attributes, never a script vector, and must survive the floor so the dispatch still runs.
+const FIXED_MARKERS = ['dataPrimitive', 'dataSlot', 'dataIcon', 'dataRole', 'dataRise'];
+
+/**
+ * Build the delivery sanitize schema. Starts from hast-util-sanitize's defaultSchema, the
+ * GitHub-lineage allowlist that strips scripts, inline event handlers, and javascript:/data: URLs,
+ * then adds exactly what cairn's render needs. The directive markers (the fixed ones plus the
+ * dataAttr<Key> markers derived from the registry) survive so the dispatch reads its stamps after
+ * the floor. The benign author tags real content uses (nav, details, summary) and class/target/rel
+ * on anchors are admitted. A site extends the result through `extend`, always starting from this
+ * safe base, so it can add to the allowlist but not weaken the core strip.
+ */
+export function buildSanitizeSchema(
+  registry: ComponentRegistry,
+  extend?: (defaults: Schema) => Schema,
+): Schema {
+  const attrMarkers = registry.defs.flatMap((d) => (d.attributes ?? []).map((a) => dataAttrProp(a.key)));
+  const markers = [...FIXED_MARKERS, ...attrMarkers];
+  const attributes = defaultSchema.attributes ?? {};
+  // defaultSchema's `a` entry carries a className tuple (`['className', 'data-footnote-backref']`)
+  // that restricts a link's class to that one value. A per-tag tuple wins over a bare `*` entry, so
+  // it would strip an author's link class. Drop that tuple before admitting a free-form `className`.
+  const anchorAttrs = (attributes.a ?? []).filter(
+    (entry) => !(Array.isArray(entry) && entry[0] === 'className'),
+  );
+  // Admit the inert `cairn:` href scheme on top of the default protocol allowlist. The render
+  // resolver rewrites a `cairn:` link to a live permalink before delivery; an unresolved one
+  // survives the floor in its inert token form (a visible unresolved-link signal), never as an
+  // executable vector. The dangerous-protocol strip (javascript:, data:) is preserved.
+  const protocols = defaultSchema.protocols ?? {};
+  const schema: Schema = {
+    ...defaultSchema,
+    tagNames: [...(defaultSchema.tagNames ?? []), 'nav', 'details', 'summary'],
+    attributes: {
+      ...attributes,
+      '*': [...(attributes['*'] ?? []), 'className', ...markers],
+      a: [...anchorAttrs, 'className', 'target', 'rel'],
+    },
+    protocols: {
+      ...protocols,
+      href: [...(protocols.href ?? []), 'cairn'],
+    },
+  };
+  return extend ? extend(schema) : schema;
+}
+
+/**
+ * Force rel="noopener noreferrer" on every target="_blank" anchor, to prevent reverse-tabnabbing.
+ * hast-util-sanitize runs no per-node hook, so this small transform carries the behavior the old
+ * DOMPurify preview pass enforced, now on the delivered output as well.
+ */
+export function rehypeAnchorRel() {
+  return (tree: Root) => {
+    visit(tree, 'element', (node: Element) => {
+      if (node.tagName === 'a' && node.properties?.target === '_blank') {
+        node.properties.rel = 'noopener noreferrer';
+      }
+    });
+  };
+}

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

@@ -9,9 +9,10 @@ import {
   hashToken,
   TOKEN_TTL_MS,
   SESSION_TTL_MS,
-  COOKIE_NAME,
+  SEND_COOLDOWN_MS,
+  sessionCookieName,
 } from '../auth/crypto.js';
-import { findEditor, issueToken, consumeToken, createSession, deleteSession } from '../auth/store.js';
+import { findEditor, issueToken, consumeToken, createSession, deleteSession, recentlyIssued } from '../auth/store.js';
 import { buildMagicLinkMessage, cloudflareSend, type AuthBranding, type SendMagicLink } from '../email.js';
 import type { RequestContext } from './types.js';
 
@@ -37,11 +38,27 @@ export function createAuthRoutes(config: AuthRoutesConfig) {
 
     const editor = email ? await findEditor(db, email) : null;
     if (editor) {
-      const token = generateToken();
       const now = Date.now();
-      await issueToken(db, email, await hashToken(token), now + TOKEN_TTL_MS, now);
-      const link = `${origin}/admin/auth/confirm?token=${encodeURIComponent(token)}`;
-      await send(env, buildMagicLinkMessage({ to: email, branding: config.branding, link }));
+      // Per-email cooldown: skip the reissue and send when a token for this email was issued within
+      // the window, so the endpoint cannot flood an editor's inbox. The response is unchanged, so
+      // the non-leak property holds.
+      if (!(await recentlyIssued(db, email, now - SEND_COOLDOWN_MS))) {
+        const token = generateToken();
+        await issueToken(db, email, await hashToken(token), now + TOKEN_TTL_MS, now);
+        const link = `${origin}/admin/auth/confirm?token=${encodeURIComponent(token)}`;
+        // The token row is the security-critical write the email depends on, so it is awaited. The
+        // send is a post-response side effect, handed to waitUntil so a slow email provider does not
+        // hold the response. An absent waitUntil (local dev, tests) falls back to await. A send
+        // failure is logged so observability survives a backgrounded send.
+        const sending = send(env, buildMagicLinkMessage({ to: email, branding: config.branding, link })).catch(
+          (err) => console.error('cairn: magic-link send failed', err),
+        );
+        // adapter-cloudflare exposes the ExecutionContext as platform.ctx; platform.context is a
+        // deprecated alias kept as a fallback so an adapter that drops it keeps backgrounding.
+        const ctx = event.platform?.ctx ?? event.platform?.context;
+        if (ctx?.waitUntil) ctx.waitUntil(sending);
+        else await sending;
+      }
     }
     return { sent: true };
   }
@@ -83,11 +100,12 @@ export function createAuthRoutes(config: AuthRoutesConfig) {
 
     const id = generateSessionId();
     await createSession(db, id, email, now + SESSION_TTL_MS, now);
-    event.cookies.set(COOKIE_NAME, id, {
+    const secure = event.url.protocol === 'https:';
+    event.cookies.set(sessionCookieName(secure), id, {
       path: '/',
       httpOnly: true,
-      // Secure on HTTPS (every real deploy); off on local http dev so the cookie sticks.
-      secure: event.url.protocol === 'https:',
+      // __Host- needs Secure unconditionally on https; local http dev drops the prefix and Secure.
+      secure,
       sameSite: 'lax',
       maxAge: Math.floor(SESSION_TTL_MS / 1000),
     });
@@ -97,9 +115,10 @@ export function createAuthRoutes(config: AuthRoutesConfig) {
   /** POST /admin/auth/logout. Deletes the session row and clears the cookie. */
   async function logoutAction(event: RequestContext): Promise<never> {
     const db = requireDb(event.platform?.env ?? {});
-    const id = event.cookies.get(COOKIE_NAME);
+    const name = sessionCookieName(event.url.protocol === 'https:');
+    const id = event.cookies.get(name);
     if (id) await deleteSession(db, id);
-    event.cookies.delete(COOKIE_NAME, { path: '/' });
+    event.cookies.delete(name, { path: '/' });
     throw redirect(303, '/admin/login');
   }
 

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

@@ -7,8 +7,9 @@ import { findConcept } from '../content/concepts.js';
 import { frontmatterFromForm, parseMarkdown, dateInputValue, serializeMarkdown } from '../content/frontmatter.js';
 import { isValidId, slugify, filenameFromId, composeDatedId } from '../content/ids.js';
 import { appCredentials, type GithubKeyEnv } from '../github/credentials.js';
-import { listMarkdown, readRaw, commitFile } from '../github/repo.js';
-import { installationToken } from '../github/signing.js';
+import { listMarkdown, readRaw, commitFiles } from '../github/repo.js';
+import { cachedInstallationToken } from '../github/signing.js';
+import { emptyManifest, manifestEntryFromFile, parseManifest, serializeManifest, upsertEntry, type LinkTarget } from '../content/manifest.js';
 import { CommitConflictError } from '../github/types.js';
 import type { CairnRuntime, ConceptDescriptor, FrontmatterField } from '../content/types.js';
 import type { Editor, Role } from '../auth/types.js';
@@ -63,6 +64,8 @@ export interface EditData {
   isNew: boolean;
   saved: boolean;
   error: string | null;
+  /** The site's link targets, for the preview resolver and the link picker; from the committed manifest. */
+  linkTargets: LinkTarget[];
 }
 
 /** The structural event the content routes read; a real SvelteKit RequestEvent satisfies it. */
@@ -96,7 +99,7 @@ function conceptOf(runtime: CairnRuntime, params: Record<string, string>): Conce
 
 export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDeps = {}) {
   const mintToken =
-    deps.mintToken ?? ((env: GithubKeyEnv) => installationToken(appCredentials(runtime.backend, env)));
+    deps.mintToken ?? ((env: GithubKeyEnv) => cachedInstallationToken(appCredentials(runtime.backend, env)));
 
   /** Layout load for every admin page: the nav, the user, and the active path. */
   function layoutLoad(event: ContentEvent): LayoutData {
@@ -207,6 +210,20 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
 
     const parsed = raw === null ? { frontmatter: {}, body: '' } : parseMarkdown(raw);
     const title = typeof parsed.frontmatter.title === 'string' && parsed.frontmatter.title.trim() ? parsed.frontmatter.title : id;
+
+    let linkTargets: LinkTarget[] = [];
+    const manifestRaw = await readRaw(runtime.backend, runtime.manifestPath, token);
+    if (manifestRaw !== null) {
+      linkTargets = parseManifest(manifestRaw).entries.map((e) => ({
+        concept: e.concept,
+        id: e.id,
+        permalink: e.permalink,
+        title: e.title,
+        date: e.date,
+        draft: e.draft,
+      }));
+    }
+
     return {
       conceptId: concept.id,
       id,
@@ -218,6 +235,7 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
       isNew,
       saved: event.url.searchParams.get('saved') === '1',
       error: event.url.searchParams.get('error'),
+      linkTargets,
     };
   }
 
@@ -249,11 +267,25 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
 
     const markdown = serializeMarkdown(result.data, body);
     const token = await mintToken(event.platform?.env ?? {});
+
+    // Read the committed manifest, upsert this entry's row, and commit content and manifest in one
+    // commit. A missing manifest starts empty (first save on a fresh repo). The build regenerates
+    // and verifies the manifest, so this incremental patch is the cheap request-time path. On a
+    // 422 retry commitFiles re-sends this manifest blob last-writer-wins. A concurrent save can then
+    // leave the committed manifest stale, which the next build rejects via verifyManifest; regenerate
+    // it with npm run cairn:manifest to recover.
+    const manifestRaw = await readRaw(runtime.backend, runtime.manifestPath, token);
+    const manifest = manifestRaw === null ? emptyManifest() : parseManifest(manifestRaw);
+    const row = manifestEntryFromFile(concept, { path, raw: markdown });
+    const nextManifest = serializeManifest(upsertEntry(manifest, row));
+
     try {
-      await commitFile(
+      await commitFiles(
         runtime.backend,
-        path,
-        markdown,
+        [
+          { path, content: markdown },
+          { path: runtime.manifestPath, content: nextManifest },
+        ],
         { message: `Update ${concept.label.toLowerCase()}: ${id}`, author: { name: editor.displayName, email: editor.email } },
         token,
       );

package/src/lib/sveltekit/guard.ts

@@ -3,7 +3,7 @@
 // stays free of a site's App.* ambient types.
 import { redirect, error } from '@sveltejs/kit';
 import { resolveSession } from '../auth/store.js';
-import { COOKIE_NAME } from '../auth/crypto.js';
+import { sessionCookieName } from '../auth/crypto.js';
 import type { Editor } from '../auth/types.js';
 import type { HandleInput, RequestContext } from './types.js';
 
@@ -16,19 +16,34 @@ function isAdminPath(pathname: string): boolean {
   return pathname === '/admin' || pathname.startsWith('/admin/');
 }
 
-/** The SvelteKit `Handle` that guards `/admin/**`. */
+/**
+ * Attach the baseline security headers to an admin response. No full CSP; see the auth-hardening
+ * design. frame-ancestors is the modern clickjacking control and the one CSP directive included.
+ */
+function applySecurityHeaders(headers: Headers): void {
+  headers.set('X-Content-Type-Options', 'nosniff');
+  headers.set('X-Frame-Options', 'DENY');
+  headers.set('Content-Security-Policy', "frame-ancestors 'none'");
+  headers.set('Referrer-Policy', 'no-referrer');
+  headers.set('Strict-Transport-Security', 'max-age=63072000; includeSubDomains');
+  headers.set('Permissions-Policy', 'camera=(), microphone=(), geolocation=()');
+}
+
+/** The SvelteKit `Handle` that guards `/admin/**` and hardens admin responses. */
 export function createAuthGuard() {
   return async function handle({ event, resolve }: HandleInput): Promise<Response> {
     const { pathname } = event.url;
-    if (!isAdminPath(pathname) || isPublicAdminPath(pathname)) {
-      return resolve(event);
+    if (!isAdminPath(pathname)) return resolve(event);
+    if (!isPublicAdminPath(pathname)) {
+      const env = event.platform?.env ?? {};
+      const id = event.cookies.get(sessionCookieName(event.url.protocol === 'https:'));
+      const editor = id && env.AUTH_DB ? await resolveSession(env.AUTH_DB, id, Date.now()) : null;
+      if (!editor) throw redirect(303, '/admin/login');
+      event.locals.editor = editor;
     }
-    const env = event.platform?.env ?? {};
-    const id = event.cookies.get(COOKIE_NAME);
-    const editor = id && env.AUTH_DB ? await resolveSession(env.AUTH_DB, id, Date.now()) : null;
-    if (!editor) throw redirect(303, '/admin/login');
-    event.locals.editor = editor;
-    return resolve(event);
+    const response = await resolve(event);
+    applySecurityHeaders(response.headers);
+    return response;
   };
 }
 

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

@@ -3,7 +3,7 @@
 // and commit paths are unit-testable against a fetch double with an injected token.
 import { redirect, error } from '@sveltejs/kit';
 import { appCredentials, type GithubKeyEnv } from '../github/credentials.js';
-import { installationToken } from '../github/signing.js';
+import { cachedInstallationToken } from '../github/signing.js';
 import { listMarkdown, readRaw, commitFile } from '../github/repo.js';
 import { CommitConflictError } from '../github/types.js';
 import { parseSiteConfig, extractMenu, validateNavTree, setMenu, type NavNode } from '../nav/site-config.js';
@@ -45,7 +45,7 @@ function isConflict(err: unknown): boolean {
 
 export function createNavRoutes(runtime: CairnRuntime, deps: NavRoutesDeps = {}) {
   const mintToken =
-    deps.mintToken ?? ((env: GithubKeyEnv) => installationToken(appCredentials(runtime.backend, env)));
+    deps.mintToken ?? ((env: GithubKeyEnv) => cachedInstallationToken(appCredentials(runtime.backend, env)));
 
   /** List page-like concepts (routable, not dated) for the URL picker. Best-effort per concept. */
   async function pageOptions(token: string): Promise<NavPageOption[]> {

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

@@ -9,11 +9,13 @@ import type { SiteIndex } from '../delivery/site-index.js';
 import { buildSeoMeta } from '../delivery/seo.js';
 import type { SeoMeta } from '../delivery/seo.js';
 import { readSeoFields, resolveImageUrl } from '../delivery/seo-fields.js';
+import { buildLinkResolver } from '../delivery/manifest.js';
+import type { LinkResolve } from '../content/links.js';
 
 /** Injected dependencies for the public loaders. */
 export interface PublicRoutesDeps {
   site: SiteIndex;
-  render: (md: string, opts?: { stagger?: boolean }) => string | Promise<string>;
+  render: (md: string, opts?: { stagger?: boolean; resolve?: LinkResolve }) => string | Promise<string>;
   origin: string;
   /** Site name for og:site_name and the SEO head. */
   siteName: string;
@@ -83,9 +85,9 @@ export function createPublicRoutes(deps: PublicRoutesDeps) {
       ...(image ? { image } : {}),
       ...(fields.robots ? { robots: fields.robots } : {}),
       ...(fields.author ? { author: fields.author } : {}),
-      feeds,
+      ...(entry.date ? { feeds } : {}),
     });
-    return { entry, html: await render(entry.body, { stagger: true }), canonicalUrl, seo, newer, older };
+    return { entry, html: await render(entry.body, { stagger: true, resolve: buildLinkResolver(site) }), canonicalUrl, seo, newer, older };
   }
 
   /** The chronological archive for one concept: every non-draft summary, newest-first. */

package/src/lib/sveltekit/types.ts

@@ -21,7 +21,11 @@ export interface RequestContext {
   request: Request;
   cookies: CookieJar;
   locals: { editor?: Editor | null };
-  platform?: { env?: AuthEnv };
+  platform?: {
+    env?: AuthEnv;
+    ctx?: { waitUntil(promise: Promise<unknown>): void };
+    context?: { waitUntil(promise: Promise<unknown>): void };
+  };
   // Required so a site cannot silently drop the confirm page's Referrer-Policy header
   // (spec 7.1). A real SvelteKit RequestEvent always supplies it.
   setHeaders(headers: Record<string, string>): void;

package/dist/render/sanitize.d.ts

@@ -1,8 +0,0 @@
-/**
- * Sanitize rendered preview HTML before it reaches `{@html}`. Strips scripts, inline event
- * handlers, and dangerous URL schemes (`javascript:`, `data:`) while keeping ordinary formatting.
- * Also forces `rel="noopener noreferrer"` on any anchor with `target="_blank"` to prevent
- * reverse-tabnabbing. Browser-only; resolves the same string DOMPurify would return.
- */
-export declare function sanitizePreviewHtml(html: string): Promise<string>;
-//# sourceMappingURL=sanitize.d.ts.map

package/dist/render/sanitize.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../../src/lib/render/sanitize.ts"],"names":[],"mappings":"AAOA;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAavE"}

package/dist/render/sanitize.js

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

package/src/lib/render/sanitize.ts

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