@acms-subir/core 0.3.10 → 0.3.11

package/src/lib/backup/offsite.ts

@@ -0,0 +1,173 @@
+import { createHash, createHmac } from 'node:crypto';
+import type { ContentRepository } from '../repo/types';
+import { runtimeValue } from '../email/config';
+import { backupArchive } from './archive';
+
+// Scheduled off-site backups: the scheduler writes the same ZIP as Admin →
+// Backup to object storage every BACKUP_EVERY_HOURS (default 24) and keeps
+// the newest BACKUP_KEEP (default 14). Targets, first match wins:
+//   - an R2 bucket bound as BACKUPS (Cloudflare Workers)
+//   - any S3-compatible bucket: BACKUP_S3_ENDPOINT, BACKUP_S3_BUCKET,
+//     BACKUP_S3_ACCESS_KEY_ID, BACKUP_S3_SECRET_ACCESS_KEY, BACKUP_S3_REGION
+//     (R2's S3 API, Oracle Object Storage, AWS S3, MinIO…)
+// The archive is built in memory, so on Workers the site (content + media)
+// must fit well inside the isolate's memory limit.
+
+export interface BackupTarget {
+  describe: string;
+  put(key: string, body: Uint8Array): Promise<void>;
+  list(prefix: string): Promise<string[]>;
+  delete(key: string): Promise<void>;
+}
+type Fetch = (url: string, init: RequestInit) => Promise<Response>;
+
+const LEASE_MS = 30 * 60_000;
+const RETRY_MS = 15 * 60_000;
+export const BACKUP_NAME = /^acms-backup-\d{8}T\d{6}Z\.zip$/;
+export const backupKey = (prefix: string, now: number) =>
+  `${prefix}acms-backup-${new Date(now).toISOString().replace(/[:-]|\.\d{3}/g, '')}.zip`;
+
+// ---- S3 (SigV4, path-style: works for R2, Oracle and AWS alike) ----------
+
+const sha256 = (data: string | Uint8Array) => createHash('sha256').update(data).digest('hex');
+const hmac = (key: string | Buffer, data: string) => createHmac('sha256', key).update(data).digest();
+const rfc3986 = (s: string) => encodeURIComponent(s).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+
+export interface S3Credentials { accessKeyId: string; secretAccessKey: string; region: string }
+/** SigV4 headers for one S3 request (host, x-amz-date, x-amz-content-sha256, authorization). */
+export function signS3(method: string, url: URL, payloadHash: string, creds: S3Credentials, now = new Date(), extra: Record<string, string> = {}): Headers {
+  const amzDate = now.toISOString().replace(/[:-]|\.\d{3}/g, ''), day = amzDate.slice(0, 8);
+  const values: Record<string, string> = { host: url.host, 'x-amz-content-sha256': payloadHash, 'x-amz-date': amzDate };
+  for (const [k, v] of Object.entries(extra)) values[k.toLowerCase()] = v;
+  const names = Object.keys(values).sort(), signed = names.join(';');
+  const path = url.pathname.split('/').map((p) => rfc3986(decodeURIComponent(p))).join('/');
+  const query = [...url.searchParams].map(([k, v]) => [rfc3986(k), rfc3986(v)]).sort(([a, av], [b, bv]) => a < b ? -1 : a > b ? 1 : av < bv ? -1 : 1).map(([k, v]) => `${k}=${v}`).join('&');
+  const canonical = [method, path, query, names.map((n) => `${n}:${values[n].trim()}\n`).join(''), signed, payloadHash].join('\n');
+  const scope = `${day}/${creds.region}/s3/aws4_request`;
+  const key = hmac(hmac(hmac(hmac(`AWS4${creds.secretAccessKey}`, day), creds.region), 's3'), 'aws4_request');
+  const signature = hmac(key, `AWS4-HMAC-SHA256\n${amzDate}\n${scope}\n${sha256(canonical)}`).toString('hex');
+  const headers = new Headers(values);
+  headers.delete('host'); // fetch sets it
+  headers.set('authorization', `AWS4-HMAC-SHA256 Credential=${creds.accessKeyId}/${scope}, SignedHeaders=${signed}, Signature=${signature}`);
+  return headers;
+}
+
+const xmlText = (s: string) => s.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, '&');
+
+export function s3Target(endpoint: string, bucket: string, creds: S3Credentials, fetcher: Fetch = fetch): BackupTarget {
+  const base = endpoint.replace(/\/+$/, '');
+  const objectUrl = (key: string) => new URL(`${base}/${rfc3986(bucket)}/${key.split('/').map(rfc3986).join('/')}`);
+  async function send(method: string, url: URL, body?: Uint8Array, extra: Record<string, string> = {}) {
+    const headers = signS3(method, url, sha256(body ?? ''), creds, new Date(), extra);
+    const res = await fetcher(url.href, { method, headers, body: body as BodyInit | undefined, signal: AbortSignal.timeout(10 * 60_000) });
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      const code = text.match(/<Code>([^<]*)<\/Code>/)?.[1];
+      throw new Error(`S3 ${method} failed (${res.status}${code ? ` ${code}` : ''})`);
+    }
+    return res;
+  }
+  return {
+    describe: `${new URL(base).host}/${bucket}`,
+    async put(key, body) { await send('PUT', objectUrl(key), body, { 'content-type': 'application/zip' }); },
+    async list(prefix) {
+      const keys: string[] = [];
+      let token = '';
+      for (let page = 0; page < 100; page++) {
+        const url = new URL(`${base}/${rfc3986(bucket)}`);
+        url.searchParams.set('list-type', '2');
+        url.searchParams.set('prefix', prefix);
+        if (token) url.searchParams.set('continuation-token', token);
+        const xml = await (await send('GET', url)).text();
+        for (const m of xml.matchAll(/<Key>([^<]*)<\/Key>/g)) keys.push(xmlText(m[1]));
+        token = /<IsTruncated>true<\/IsTruncated>/.test(xml) ? xmlText(xml.match(/<NextContinuationToken>([^<]*)<\/NextContinuationToken>/)?.[1] ?? '') : '';
+        if (!token) break;
+      }
+      return keys;
+    },
+    async delete(key) { await send('DELETE', objectUrl(key)); },
+  };
+}
+
+// ---- R2 binding ------------------------------------------------------------
+
+interface R2Like {
+  put(key: string, body: Uint8Array, opts?: unknown): Promise<unknown>;
+  list(opts: { prefix: string; cursor?: string }): Promise<{ objects: Array<{ key: string }>; truncated: boolean; cursor?: string }>;
+  delete(key: string): Promise<void>;
+}
+export function r2Target(bucket: R2Like): BackupTarget {
+  return {
+    describe: 'R2 binding BACKUPS',
+    async put(key, body) { await bucket.put(key, body, { httpMetadata: { contentType: 'application/zip' } }); },
+    async list(prefix) {
+      const keys: string[] = [];
+      let cursor: string | undefined;
+      for (let page = 0; page < 100; page++) {
+        const r = await bucket.list({ prefix, cursor });
+        keys.push(...r.objects.map((o) => o.key));
+        if (!r.truncated) break;
+        cursor = r.cursor;
+      }
+      return keys;
+    },
+    async delete(key) { await bucket.delete(key); },
+  };
+}
+
+// ---- configuration + the scheduler job --------------------------------------
+
+export interface OffsiteConfig { target: BackupTarget; prefix: string; keep: number; everyMs: number }
+export function offsiteConfig(locals?: unknown, fetcher?: Fetch): OffsiteConfig | null {
+  const v = (k: string) => runtimeValue(k, locals).trim();
+  const binding = (locals as { runtime?: { env?: { BACKUPS?: R2Like } } } | undefined)?.runtime?.env?.BACKUPS;
+  const s3 = { endpoint: v('BACKUP_S3_ENDPOINT'), bucket: v('BACKUP_S3_BUCKET'), accessKeyId: v('BACKUP_S3_ACCESS_KEY_ID'), secretAccessKey: v('BACKUP_S3_SECRET_ACCESS_KEY') };
+  const anyS3 = Object.values(s3).some(Boolean);
+  if (!binding?.put && !anyS3) return null;
+  const keep = Number(v('BACKUP_KEEP') || 14), hours = Number(v('BACKUP_EVERY_HOURS') || 24);
+  if (!Number.isInteger(keep) || keep < 1 || keep > 1000) throw new Error('BACKUP_KEEP must be a whole number from 1 to 1000.');
+  if (!Number.isFinite(hours) || hours < 1 || hours > 24 * 31) throw new Error('BACKUP_EVERY_HOURS must be between 1 and 744.');
+  let prefix = v('BACKUP_PREFIX') || 'acms-backups/';
+  if (!prefix.endsWith('/')) prefix += '/';
+  let target: BackupTarget;
+  if (binding?.put) target = r2Target(binding);
+  else {
+    const missing = Object.entries(s3).filter(([, x]) => !x).map(([k]) => `BACKUP_S3_${k.replace(/[A-Z]/g, (c) => `_${c}`).toUpperCase()}`);
+    if (missing.length) throw new Error(`Off-site backups need ${missing.join(', ')}.`);
+    let url: URL;
+    try { url = new URL(s3.endpoint); } catch { throw new Error('BACKUP_S3_ENDPOINT must be an https:// URL.'); }
+    if (url.protocol !== 'https:' && !['localhost', '127.0.0.1'].includes(url.hostname)) throw new Error('BACKUP_S3_ENDPOINT must be an https:// URL.');
+    target = s3Target(url.origin, s3.bucket, { accessKeyId: s3.accessKeyId, secretAccessKey: s3.secretAccessKey, region: v('BACKUP_S3_REGION') || 'auto' }, fetcher);
+  }
+  return { target, prefix, keep, everyMs: hours * 3_600_000 };
+}
+
+/**
+ * Scheduler job. Returns 1 when it wrote a backup, 0 when none was due or
+ * nothing is configured. Throws when a backup failed; the lease then holds
+ * retries off for 15 minutes so a broken bucket isn't hammered every minute.
+ */
+export async function runOffsiteBackup(repo: ContentRepository, locals?: unknown, opts: { now?: number; fetch?: Fetch } = {}): Promise<number> {
+  const config = offsiteConfig(locals, opts.fetch);
+  if (!config) return 0;
+  const now = opts.now ?? Date.now();
+  if (!await repo.backups.claim(now, config.everyMs, LEASE_MS)) return 0;
+  const key = backupKey(config.prefix, now);
+  try {
+    const body = new Uint8Array(await new Response(await backupArchive(repo, locals, now)).arrayBuffer());
+    await config.target.put(key, body);
+  } catch (e) {
+    await repo.backups.fail(now, e instanceof Error ? e.message : 'Backup failed', RETRY_MS).catch(() => {});
+    throw e;
+  }
+  await repo.backups.succeed(now, key);
+  // keep the newest N of our own files; anything else under the prefix stays
+  try {
+    const ours = (await config.target.list(config.prefix)).filter((k) => BACKUP_NAME.test(k.slice(config.prefix.length))).sort();
+    for (const old of ours.slice(0, Math.max(0, ours.length - config.keep))) await config.target.delete(old);
+  } catch (e) {
+    // the backup itself landed; the next run prunes again
+    console.error('acms backup: pruning old backups failed', e);
+  }
+  return 1;
+}

package/src/lib/backup/store.ts

@@ -0,0 +1,28 @@
+import type { SqlDriver } from '../repo/sql';
+
+// Scheduled off-site backups: when the last one ran, and a lease so two
+// overlapping scheduler runs (a slow upload, two containers) never upload
+// the same backup twice.
+export interface BackupStatus { lastAt: number; leaseUntil: number; lastKey: string; lastError: string; failedAt: number }
+export class BackupStore {
+  constructor(private driver: () => Promise<SqlDriver>) {}
+  async status(): Promise<BackupStatus> {
+    const r = (await (await this.driver()).all('SELECT * FROM backup_state WHERE id = 1'))[0] ?? {};
+    return { lastAt: Number(r.last_at ?? 0), leaseUntil: Number(r.lease_until ?? 0), lastKey: String(r.last_key ?? ''), lastError: String(r.last_error ?? ''), failedAt: Number(r.failed_at ?? 0) };
+  }
+  /** take the lease when a backup is due (last success older than everyMs, no live lease) */
+  async claim(now: number, everyMs: number, leaseMs: number): Promise<boolean> {
+    const rows = await (await this.driver()).all(
+      'UPDATE backup_state SET lease_until = ? WHERE id = 1 AND lease_until <= ? AND last_at <= ? RETURNING id',
+      [now + leaseMs, now, now - everyMs],
+    );
+    return rows.length > 0;
+  }
+  async succeed(now: number, key: string) {
+    await (await this.driver()).run("UPDATE backup_state SET last_at = ?, last_key = ?, lease_until = 0, last_error = '' WHERE id = 1", [now, key]);
+  }
+  /** keep the failure, and hold the lease until the retry time */
+  async fail(now: number, error: string, retryMs: number) {
+    await (await this.driver()).run('UPDATE backup_state SET lease_until = ?, last_error = ?, failed_at = ? WHERE id = 1', [now + retryMs, error.slice(0, 500), now]);
+  }
+}

package/src/lib/cache/config.ts

@@ -0,0 +1,7 @@
+import { userConfig } from 'virtual:acms-config';
+
+// acms({ cache }) resolved by integration.mjs. Mutable so tests can flip it.
+export const CACHE: { enabled: boolean; maxAge: number; staleWhileRevalidate: number; memory: boolean } = {
+  enabled: true, maxAge: 60, staleWhileRevalidate: 86400, memory: true,
+  ...((userConfig as { cache?: Partial<typeof CACHE> }).cache ?? {}),
+};

package/src/lib/cache/memory.ts

@@ -0,0 +1,39 @@
+// In-process cache of public app API bodies (Node: one long-lived server).
+// Keys carry the content version, so a change makes old entries unreachable;
+// the purge loop also drops them all. Bounded by entries and bytes, oldest
+// out first — the sustained memory workload must stay flat.
+
+const MAX_ENTRIES = 500;
+const MAX_BYTES = 8 * 1024 * 1024;
+const store = new Map<string, string>();
+let bytes = 0;
+
+export function memoryGet(key: string): string | undefined {
+  const hit = store.get(key);
+  if (hit === undefined) return undefined;
+  // refresh recency
+  store.delete(key);
+  store.set(key, hit);
+  return hit;
+}
+
+export function memorySet(key: string, body: string) {
+  const size = body.length * 2;
+  if (size > MAX_BYTES / 8) return; // one huge body must not flush everything else
+  const old = store.get(key);
+  if (old !== undefined) { bytes -= old.length * 2; store.delete(key); }
+  store.set(key, body);
+  bytes += size;
+  for (const [k, v] of store) {
+    if (store.size <= MAX_ENTRIES && bytes <= MAX_BYTES) break;
+    store.delete(k);
+    bytes -= v.length * 2;
+  }
+}
+
+export function clearMemoryCache() {
+  store.clear();
+  bytes = 0;
+}
+
+export const memoryStats = () => ({ entries: store.size, bytes });

package/src/lib/cache/policy.ts

@@ -0,0 +1,89 @@
+import { CACHE } from './config';
+import { CALENDAR } from '../calendar/config';
+import { I18N } from '../i18n';
+
+// The one place that decides whether a response may be stored by a shared
+// cache (Cloudflare, a CDN). Public GET pages and the public app API are
+// cacheable; anything personal, interactive or staff-only is private.
+
+export const PRIVATE_CACHE_CONTROL = 'private, no-store';
+export const publicCacheControl = () => `public, s-maxage=${CACHE.maxAge}, stale-while-revalidate=${CACHE.staleWhileRevalidate}`;
+// publicResponse's own header: browsers/apps always revalidate by ETag. The
+// policy upgrades it with s-maxage so a CDN can share it.
+export const API_REVALIDATE = 'public, max-age=0, must-revalidate';
+
+// Sign-in state lives in these cookies (built-in session, Clerk, design
+// preview). Any of them means the page may be personalized.
+const PRIVATE_COOKIE = /(?:^|;\s*)(?:acms_session|acms_preview|__session(?:_[^=;]+)?|__client_uat(?:_[^=;]+)?|__clerk_db_jwt(?:_[^=;]+)?)=/;
+const CACHEABLE_STATUS = new Set([200, 203, 301, 308, 404, 410]);
+// Paths that set their own long-lived headers (hashed media, built assets).
+const OWN_HEADERS = /^\/(?:media|_astro)\//;
+
+function privatePrefixes() {
+  return [
+    '/admin', '/preview', '/account', '/go', '/forms', '/_actions', '/_server-islands', '/embed/book',
+    ...(CALENDAR.enabled ? [CALENDAR.bookBase] : []),
+  ];
+}
+// Public app API routes that are personal, transactional or write-only.
+const PRIVATE_API = /^\/api\/v1\/(?:admin|auth|guest|bookings|availability|devices|push|forms)(?:\/|$)/;
+
+const under = (path: string, prefix: string) => path === prefix || path.startsWith(`${prefix}/`) || path.startsWith(`${prefix}.`);
+
+/** strip a non-default locale prefix: /es/events/x is cached like /events/x */
+function barePath(pathname: string) {
+  if (!I18N.enabled) return pathname;
+  for (const l of I18N.locales) {
+    if (l !== I18N.defaultLocale && (pathname === `/${l}` || pathname.startsWith(`/${l}/`))) return pathname.slice(l.length + 1) || '/';
+  }
+  return pathname;
+}
+
+export function isPrivateRequest(request: Request, pathname = new URL(request.url).pathname): boolean {
+  if (request.method !== 'GET' && request.method !== 'HEAD') return true;
+  if (request.headers.has('authorization')) return true;
+  if (PRIVATE_COOKIE.test(request.headers.get('cookie') ?? '')) return true;
+  const path = barePath(pathname);
+  if (path.startsWith('/api/')) return !path.startsWith('/api/v1/') || PRIVATE_API.test(path);
+  return privatePrefixes().some((p) => under(path, p));
+}
+
+const warned = new Set<string>();
+function warnCookie(pathname: string) {
+  if (warned.has(pathname) || warned.size >= 100) return;
+  warned.add(pathname);
+  console.warn(`acms cache: ${pathname} set a cookie on a public page, so it was served private (not cached)`);
+}
+
+/**
+ * Set Cache-Control on a finished response. Routes that already chose a
+ * private/no-store policy, or their own public one, are left alone; the
+ * policy only fills the default and never loosens a route's choice.
+ */
+export function applyCachePolicy(request: Request, response: Response, pathname = new URL(request.url).pathname): Response {
+  if (!CACHE.enabled) return response;
+  if (OWN_HEADERS.test(pathname)) return response;
+  const current = response.headers.get('cache-control');
+  const set = (value: string) => {
+    try { response.headers.set('Cache-Control', value); return response; }
+    catch {
+      // immutable headers (a proxied/fetched response): copy it
+      const copy = new Response(response.body, response);
+      copy.headers.set('Cache-Control', value);
+      return copy;
+    }
+  };
+  if (isPrivateRequest(request, pathname)) {
+    if (current && /no-store/.test(current) && !/public/.test(current)) return response;
+    return set(PRIVATE_CACHE_CONTROL);
+  }
+  // a route that decided for itself (no-store live status, immutable files)
+  if (current && current !== API_REVALIDATE) return response;
+  if (!CACHEABLE_STATUS.has(response.status)) return current ? response : set(PRIVATE_CACHE_CONTROL);
+  // one stray cookie would hand one visitor's cookie to everyone
+  if (response.headers.has('set-cookie')) {
+    warnCookie(pathname);
+    return set(PRIVATE_CACHE_CONTROL);
+  }
+  return set(publicCacheControl());
+}

package/src/lib/cache/purge.ts

@@ -0,0 +1,89 @@
+import type { ContentRepository } from '../repo/types';
+import { runtimeValue } from '../email/config';
+import { CACHE } from './config';
+import { clearMemoryCache } from './memory';
+
+// Clearing shared caches when content changes. Each install is one site, so
+// a change clears everything. The database records the last version cleared
+// (cache_purged_version); anything newer is cleared on the next pass:
+//   - right after a write request (middleware, in the background)
+//   - the once-a-minute traffic sweep and every scheduler run, which retry a
+//     purge that failed (Cloudflare API down, rate limited)
+// Targets: Workers Cache (ctx.cache, Cloudflare deployments) and the
+// Cloudflare zone API (CLOUDFLARE_ZONE_ID + CLOUDFLARE_API_TOKEN, Docker
+// behind the Cloudflare proxy). The Node memory cache is keyed by version
+// and simply dropped.
+
+type Locals = { runtime?: { scheduled?: boolean; ctx?: { cache?: { purge(o: { purgeEverything?: boolean }): Promise<{ success: boolean; errors?: Array<{ message: string }> }> } } } };
+export type PurgeFetch = (url: string, init: RequestInit) => Promise<Response>;
+
+// A burst of saves clears once; the scheduler (≤ 1 min) picks up the rest.
+const MIN_INTERVAL_MS = 10_000;
+let lastAttempt = 0;
+let inflight: Promise<number> | null = null;
+
+// The adapter gives pages a wrapper ctx with only waitUntil. worker.ts tags
+// each request with the real ExecutionContext; the middleware copies its
+// Workers Cache handle onto locals.runtime.ctx for the purge.
+export const EXECUTION_CONTEXT = Symbol.for('acms.executionContext');
+export function bindExecutionContext(request: Request, locals: unknown) {
+  const exec = Reflect.get(request, EXECUTION_CONTEXT) as { cache?: unknown } | undefined;
+  const ctx = (locals as { runtime?: { ctx?: Record<string, unknown> } } | undefined)?.runtime?.ctx;
+  if (exec?.cache && ctx && !ctx.cache) ctx.cache = exec.cache;
+}
+
+export function purgeTargets(locals?: unknown) {
+  const workers = (locals as Locals | undefined)?.runtime?.ctx?.cache;
+  const zone = runtimeValue('CLOUDFLARE_ZONE_ID', locals).trim();
+  const token = runtimeValue('CLOUDFLARE_API_TOKEN', locals).trim();
+  return { workers: workers && typeof workers.purge === 'function' ? workers : null, zone: zone && token ? { zone, token } : null };
+}
+
+async function purgeZone(zone: string, token: string, fetcher: PurgeFetch) {
+  const res = await fetcher(`https://api.cloudflare.com/client/v4/zones/${encodeURIComponent(zone)}/purge_cache`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ purge_everything: true }),
+    signal: AbortSignal.timeout(10_000),
+  });
+  const body = await res.json().catch(() => null) as { success?: boolean; errors?: Array<{ message?: string }> } | null;
+  if (!res.ok || !body?.success) throw new Error(`Cloudflare purge failed (${res.status}${body?.errors?.[0]?.message ? `: ${body.errors[0].message}` : ''})`);
+}
+
+/**
+ * Clear caches if content changed since the last successful purge. Returns
+ * 1 when it purged, 0 when nothing was due (or throttled). Throws when a
+ * purge failed, so the scheduler job reports it and the next run retries.
+ */
+export function syncCachePurge(repo: ContentRepository, locals?: unknown, opts: { force?: boolean; fetch?: PurgeFetch; now?: number } = {}): Promise<number> {
+  if (!CACHE.enabled) return Promise.resolve(0);
+  const now = opts.now ?? Date.now();
+  // another request is already purging; never await its promise (Workers
+  // forbid I/O across requests) — a newer version is picked up next pass
+  if (inflight) return Promise.resolve(0);
+  if (!opts.force && now - lastAttempt < MIN_INTERVAL_MS) return Promise.resolve(0);
+  const run = (async () => {
+    const { version, purged } = await repo.getCacheState();
+    if (version <= purged) return 0;
+    lastAttempt = now;
+    clearMemoryCache();
+    const targets = purgeTargets(locals);
+    // A Workers cron run may not carry ctx.cache even when Workers Cache is
+    // on. Leave the version unpurged so the next page request (which has
+    // the fetch context) clears it, instead of recording a purge that
+    // never reached the cache.
+    if (!targets.workers && (locals as Locals | undefined)?.runtime?.scheduled) return 0;
+    if (targets.workers) {
+      const result = await targets.workers.purge({ purgeEverything: true });
+      if (!result.success) throw new Error(`Workers Cache purge failed${result.errors?.[0]?.message ? `: ${result.errors[0].message}` : ''}`);
+    }
+    if (targets.zone) await purgeZone(targets.zone.zone, targets.zone.token, opts.fetch ?? fetch);
+    await repo.markCachePurged(version);
+    return 1;
+  })();
+  inflight = run;
+  return run.finally(() => { if (inflight === run) inflight = null; });
+}
+
+/** test hook: forget the throttle between cases */
+export function resetPurgeThrottle() { lastAttempt = 0; }

package/src/lib/designPreview.ts

@@ -1,7 +1,7 @@
 import type { AstroCookies } from 'astro';
 import type { NavItem, Settings } from './schema';
 import { draftNavItems, pickDesignDraft, shareEpoch, toNavItems } from './drafts';
-import { validateSession, SESSION_COOKIE } from './auth';
+import { validatePreviewSession } from './auth/request';
 import { verifyDesignToken } from './preview';
 import { getRepo } from './repo';
 
@@ -86,7 +86,7 @@ async function compute(url: URL, cookies: AstroCookies, locals: unknown, liveSet
     return { role: 'reviewer', source: 'draft', active: !showLive, showLive, ended: false, draft, expiresAt: exp };
   }
 
-  if (!(await validateSession(cookies.get(SESSION_COOKIE)?.value, locals))) return NONE;
+  if (!(await validatePreviewSession(cookies, locals))) return NONE;
   if (c.startsWith('v.')) {
     const v = await repo.getDesignVersion(c.slice(2));
     if (!v) return { ...NONE, role: 'admin' };

package/src/lib/dynamicBlocks.ts

@@ -162,7 +162,7 @@ export async function expandDynamicBlocks(html: string, repo: ContentRepository)
   }
 
   if (hasForms) {
-    const tags = [...new Set((html.match(PLACEHOLDER) ?? []).filter(t => t.includes('data-dyn="form"')))];
+    const tags = [...new Set((html.match(PLACEHOLDER) ?? ([] as string[])).filter(t => t.includes('data-dyn="form"')))];
     await Promise.all(tags.map(async tag => {
       const form = await repo.forms.get(attr(tag, 'form'));
       // A same-origin frame gives each visitor an uncached form/receipt even

package/src/lib/editor/auth.ts

@@ -1,3 +1,6 @@
+import { AUTH } from '../auth/config';
+import { validateMobileBinding, authEnvironment, ClerkUnavailableError } from '../auth/request';
+import type { ClerkBinding } from '../auth/store';
 import { Role } from '../schema';
 import { createHmac } from 'node:crypto';
 import { env } from '../env';
@@ -129,10 +132,12 @@ export function checkConsentTicket(ticket: string, session: string, p: Authorize
 }
 
 /** approve: a one-time code bound to the user, app, return address and challenge */
-export async function issueCode(repo: ContentRepository, user: { id: string; sessionVersion: number }, p: AuthorizeParams, deviceName: string, now = Date.now()): Promise<string> {
+export async function issueCode(repo: ContentRepository, user: { id: string; sessionVersion: number }, p: AuthorizeParams, deviceName: string, now = Date.now(), binding?: ClerkBinding): Promise<string> {
+  if (AUTH.provider === 'clerk' && !binding) throw new ApiError(401, 'Clerk sign-in is required.');
   const code = randomToken(CODE_PREFIX);
   await repo.editor.createCode({ hash: await sha256Hex(code), userId: user.id, clientId: p.clientId, redirectUri: p.redirectUri,
-    challenge: p.codeChallenge, deviceName: cleanDeviceName(deviceName) || 'Phone', sessionVersion: user.sessionVersion, expiresAt: now + EDITOR.codeMs }, now);
+    challenge: p.codeChallenge, authProvider: AUTH.provider, deviceName: cleanDeviceName(deviceName) || 'Phone', sessionVersion: user.sessionVersion, expiresAt: now + EDITOR.codeMs }, now);
+  if (binding) await repo.auth.bindMobile('code', await sha256Hex(code), binding);
   return code;
 }
 
@@ -164,13 +169,28 @@ function tokenResponse(t: { access: string; refresh: string }, user: { id: strin
     user: { id: user.id, name: user.name, email: user.email, role: Role.parse(user.role) }, device };
 }
 
-export async function tokenGrant(repo: ContentRepository, form: Record<string, string>, now = Date.now()): Promise<TokenResponse> {
+async function mobileBindingActive(...args: Parameters<typeof validateMobileBinding>) {
+  try { return await validateMobileBinding(...args); }
+  catch (error) {
+    if (error instanceof ClerkUnavailableError) throw new ApiError(503, error.message);
+    throw error;
+  }
+}
+
+export async function tokenGrant(repo: ContentRepository, form: Record<string, string>, now = Date.now(), locals?: unknown): Promise<TokenResponse> {
   const grant = form.grant_type;
   if (grant === 'authorization_code') {
     const { code = '', code_verifier: verifier = '', redirect_uri: redirectUri = '', client_id: clientId = '' } = form;
     if (!code || !verifier || !redirectUri || !clientId) throw new OAuthError(400, 'invalid_request', 'code, code_verifier, redirect_uri and client_id are required.');
     if (!wellFormed(code, CODE_PREFIX)) throw invalidGrant('The sign-in code is invalid or expired.');
-    const spent = await repo.editor.consumeCode(await sha256Hex(code), now);
+    const hash = await sha256Hex(code);
+    // Provider outages must not burn a usable one-time credential. The later
+    // atomic consume still enforces single use and detects concurrent replays.
+    if (AUTH.provider === 'clerk') {
+      const candidate = await repo.editor.getCode(hash);
+      if (!candidate || candidate.authProvider !== AUTH.provider || !await mobileBindingActive(repo, 'code', hash, candidate.userId, locals)) throw invalidGrant('The original sign-in is no longer active. Sign in again.');
+    }
+    const spent = await repo.editor.consumeCode(hash, now);
     if (!spent) throw invalidGrant('The sign-in code is invalid or expired.');
     const c = spent.code;
     if (spent.reused) {
@@ -182,11 +202,14 @@ export async function tokenGrant(repo: ContentRepository, form: Record<string, s
     // every check runs; the code is already burned whatever the outcome
     const checks = [safeEqual(clientId, c.clientId), safeEqual(redirectUri, c.redirectUri), VERIFIER.test(verifier) && safeEqual(await s256(verifier), c.challenge), allowedRedirect(c.redirectUri)];
     if (checks.includes(false)) throw invalidGrant('The sign-in code doesn’t match this app, return address or verifier.');
+    if (c.authProvider !== AUTH.provider) throw invalidGrant('The original sign-in is no longer active. Sign in again.');
     const user = await liveUser(repo, c.userId, c.sessionVersion);
     if (!user) throw invalidGrant('This account changed since sign-in. Sign in again.');
     const device = { id: crypto.randomUUID(), name: c.deviceName };
     const t = await pair(now);
-    await repo.editor.createDevice({ id: device.id, userId: user.id, name: device.name, clientId: c.clientId, sessionVersion: c.sessionVersion }, t.hashed, now);
+    await repo.editor.createDevice({ id: device.id, userId: user.id, name: device.name, clientId: c.clientId, sessionVersion: c.sessionVersion, authProvider: c.authProvider }, t.hashed, now);
+    const binding = AUTH.provider === 'clerk' ? await repo.auth.mobile('code', c.hash) : null;
+    if (binding) await repo.auth.bindMobile('device', device.id, binding);
     await repo.editor.bindCode(c.hash, device.id);
     await repo.editor.prune(now).catch(() => {});
     return tokenResponse(t.plain, user, device);
@@ -196,6 +219,11 @@ export async function tokenGrant(repo: ContentRepository, form: Record<string, s
     if (!token) throw new OAuthError(400, 'invalid_request', 'refresh_token is required.');
     if (!wellFormed(token, REFRESH_PREFIX)) throw invalidGrant('The refresh token is invalid or expired.');
     const hash = await sha256Hex(token);
+    if (AUTH.provider === 'clerk') {
+      const deviceId = await repo.editor.deviceForToken(hash);
+      const candidate = deviceId ? await repo.editor.getDevice(deviceId) : null;
+      if (!candidate || candidate.revokedAt !== null || candidate.authProvider !== AUTH.provider || !await mobileBindingActive(repo, 'device', candidate.id, candidate.userId, locals)) throw invalidGrant('The original sign-in is no longer active. Sign in again.');
+    }
     const spent = await repo.editor.spendRefresh(hash, now);
     if (!spent) throw invalidGrant('The refresh token is invalid or expired.');
     // A rotated token presented again is theft, except for a short grace: the
@@ -209,6 +237,7 @@ export async function tokenGrant(repo: ContentRepository, form: Record<string, s
     const device = await repo.editor.getDevice(spent.deviceId);
     if (!device || device.revokedAt !== null) throw invalidGrant('This device was signed out. Sign in again.');
     if (form.client_id && !safeEqual(form.client_id, device.clientId)) throw invalidGrant('The refresh token belongs to another app.');
+    if (device.authProvider !== AUTH.provider) throw invalidGrant('The original sign-in is no longer active. Sign in again.');
     const user = await liveUser(repo, device.userId, device.sessionVersion);
     if (!user) {
       await repo.editor.revokeDevice(device.id, 'account changed', now);
@@ -254,6 +283,7 @@ export async function authenticateDevice(request: Request, repo: ContentReposito
     await repo.editor.revokeDevice(access.device.id, 'password changed', now);
     throw new ApiError(401, 'This account changed. Sign in again.');
   }
+  if (access.device.authProvider !== AUTH.provider || (AUTH.provider === 'clerk' && !await mobileBindingActive(repo, 'device', access.device.id, access.user.id, authEnvironment(request), !['GET','HEAD'].includes(request.method)))) throw new ApiError(401, 'The original sign-in is no longer active. Sign in again.');
   await repo.editor.touch(access.device.id, now);
   const { user, device } = access;
   return {

package/src/lib/editor/http.ts

@@ -25,6 +25,7 @@ export function editorRoute(handler: (c: EditorContext) => Promise<unknown>, opt
       let who: EditorPrincipal;
       try { who = await authenticateDevice(context.request, repo, now); }
       catch (error) {
+        if (error instanceof ApiError && error.status === 503) throw error;
         // failed bearer attempts are throttled per client address
         if (!await repo.email.rateLimit(`editor:fail:${await sha256Hex(address(context))}`, 30, 60_000)) throw new ApiError(429, 'Too many requests. Try again in a minute.');
         throw error;
@@ -37,7 +38,9 @@ export function editorRoute(handler: (c: EditorContext) => Promise<unknown>, opt
     } catch (error) {
       // expected failures carry a status (ApiError, BookingError) or zod issues; only surprises are logged (never request data)
       if (typeof (error as { status?: unknown })?.status !== 'number' && !(error instanceof Error && 'issues' in error)) console.error('acms editor api: request failed:', error instanceof Error ? error.message : error);
-      return failure(error);
+      const result = failure(error);
+      if (result.status === 503) result.headers.set('Retry-After', '10');
+      return result;
     }
   };
 }

package/src/lib/editor/store.ts

@@ -4,10 +4,12 @@ import type { SqlDriver } from '../repo/sql';
 type Row = Record<string, unknown>;
 
 export interface EditorDevice {
+  authProvider?: string;
   id: string; userId: string; name: string; clientId: string; sessionVersion: number;
   createdAt: number; lastUsedAt: number; revokedAt: number | null; revokedReason: string;
 }
 export interface EditorCode {
+  authProvider?: string;
   hash: string; userId: string; clientId: string; redirectUri: string; challenge: string;
   deviceName: string; sessionVersion: number; createdAt: number; expiresAt: number; usedAt: number | null; deviceId: string | null;
 }
@@ -19,11 +21,11 @@ export interface EditorAccess {
 export interface EditorActivity { id: string; createdAt: number; userId: string; deviceId: string; action: string; target: string }
 
 function device(r: Row): EditorDevice {
-  return { id: String(r.id), userId: String(r.user_id), name: String(r.name), clientId: String(r.client_id), sessionVersion: Number(r.session_version),
+  return { authProvider: String(r.auth_provider ?? 'builtin'), id: String(r.id), userId: String(r.user_id), name: String(r.name), clientId: String(r.client_id), sessionVersion: Number(r.session_version),
     createdAt: Number(r.created_at), lastUsedAt: Number(r.last_used_at), revokedAt: r.revoked_at == null ? null : Number(r.revoked_at), revokedReason: String(r.revoked_reason ?? '') };
 }
 function code(r: Row): EditorCode {
-  return { hash: String(r.hash), userId: String(r.user_id), clientId: String(r.client_id), redirectUri: String(r.redirect_uri), challenge: String(r.challenge),
+  return { authProvider: String(r.auth_provider ?? 'builtin'), hash: String(r.hash), userId: String(r.user_id), clientId: String(r.client_id), redirectUri: String(r.redirect_uri), challenge: String(r.challenge),
     deviceName: String(r.device_name), sessionVersion: Number(r.session_version), createdAt: Number(r.created_at), expiresAt: Number(r.expires_at),
     usedAt: r.used_at == null ? null : Number(r.used_at), deviceId: r.device_id == null ? null : String(r.device_id) };
 }
@@ -38,8 +40,12 @@ export class EditorStore {
 
   // ---- authorization codes ----
   async createCode(c: Omit<EditorCode, 'usedAt' | 'deviceId' | 'createdAt'>, now: number) {
-    await this.run(`INSERT INTO editor_codes (hash,user_id,client_id,redirect_uri,challenge,device_name,session_version,created_at,expires_at,used_at,device_id)
-      VALUES (?,?,?,?,?,?,?,?,?,NULL,NULL)`, [c.hash, c.userId, c.clientId, c.redirectUri, c.challenge, c.deviceName, c.sessionVersion, now, c.expiresAt]);
+    await this.run(`INSERT INTO editor_codes (hash,user_id,client_id,redirect_uri,challenge,device_name,session_version,created_at,expires_at,used_at,device_id,auth_provider)
+      VALUES (?,?,?,?,?,?,?,?,?,NULL,NULL,?)`, [c.hash, c.userId, c.clientId, c.redirectUri, c.challenge, c.deviceName, c.sessionVersion, now, c.expiresAt, c.authProvider ?? 'builtin']);
+  }
+  async getCode(hash: string): Promise<EditorCode | null> {
+    const rows = await this.all('SELECT * FROM editor_codes WHERE hash=?', [hash]);
+    return rows[0] ? code(rows[0]) : null;
   }
   /**
    * Burn a code (single use, even when the rest of the exchange fails).
@@ -55,10 +61,10 @@ export class EditorStore {
 
   // ---- devices + tokens ----
   /** a new device and its first token pair, atomically */
-  async createDevice(d: Pick<EditorDevice, 'id' | 'userId' | 'name' | 'clientId' | 'sessionVersion'>, tokens: { access: string; accessExpires: number; refresh: string; refreshExpires: number }, now: number) {
+  async createDevice(d: Pick<EditorDevice, 'id' | 'userId' | 'name' | 'clientId' | 'sessionVersion' | 'authProvider'>, tokens: { access: string; accessExpires: number; refresh: string; refreshExpires: number }, now: number) {
     await (await this.driver()).batch([
-      { sql: `INSERT INTO editor_devices (id,user_id,name,client_id,session_version,created_at,last_used_at,revoked_at,revoked_reason) VALUES (?,?,?,?,?,?,?,NULL,'')`,
-        args: [d.id, d.userId, d.name, d.clientId, d.sessionVersion, now, now] },
+      { sql: `INSERT INTO editor_devices (id,user_id,name,client_id,session_version,created_at,last_used_at,revoked_at,revoked_reason,auth_provider) VALUES (?,?,?,?,?,?,?,NULL,'',?)`,
+        args: [d.id, d.userId, d.name, d.clientId, d.sessionVersion, now, now, d.authProvider ?? 'builtin'] },
       ...this.tokenRows(d.id, tokens, now),
     ]);
   }