@acms-subir/core 0.3.9 → 0.3.11

package/src/layouts/Admin.astro

@@ -4,8 +4,10 @@ import { getRepo } from '../lib/repo';
 import { BRAND } from '../lib/brand';
 import { CONTENT } from '../lib/content';
 import { CALENDAR, bookingsEnabled } from '../lib/calendar/config';
-import { PUSH } from '../lib/push/config';
-import { validateSession, SESSION_COOKIE, OWNER_ENV } from '../lib/auth';
+import { OWNER_ENV } from '../lib/auth';
+import { validateRequestSession } from '../lib/auth/request';
+import { AUTH } from '../lib/auth/config';
+import ClerkSession from '../components/auth/ClerkSession.astro';
 import ThemeScript from '../components/ThemeScript.astro';
 import CommandPalette from '../components/CommandPalette';
 import '../styles/admin.css';
@@ -20,7 +22,7 @@ interface Props {
 const { title, section, wide = false } = Astro.props;
 
 const repo = await getRepo(Astro.locals);
-const sessionUserId = (await validateSession(Astro.cookies.get(SESSION_COOKIE)?.value, Astro.locals));
+const sessionUserId = await validateRequestSession(Astro.request, Astro.cookies, Astro.locals);
 const [pages, posts, links, home, settings, sessionUser] = await Promise.all([
   repo.listPages(),
   repo.listPosts(),
@@ -64,6 +66,7 @@ const icons: Record<string, string> = {
   out: 'M15 3h4a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2h-4M10 17l5-5-5-5M15 12H3',
   more: 'M5 12h.01M12 12h.01M19 12h.01',
   user: 'M12 12a4 4 0 1 0 0-8 4 4 0 0 0 0 8zM4 21a8 8 0 0 1 16 0',
+  shield: 'M12 3l7 3v5c0 4.5-3 8.3-7 10-4-1.7-7-5.5-7-10V6zM9 12l2 2 4-4',
   calendar: 'M3 5.5h18v15H3zM3 10h18M8 3v4M16 3v4',
   calendars: 'M4 6h.01M4 12h.01M4 18h.01M8 6h12M8 12h12M8 18h12',
   bookings: 'M12 21a9 9 0 1 0 0-18 9 9 0 0 0 0 18zM12 7v5l3 2',
@@ -128,8 +131,8 @@ const groups: { id: string; label: string; items: Item[] }[] = [
       { key: 'design', label: 'Design', href: '/admin/design', icon: icons.design, count: null },
       { key: 'navigation', label: 'Navigation', href: '/admin/navigation', icon: icons.navigation, count: null },
       { key: 'links', label: 'Links page', href: '/admin/links', icon: icons.links, count: links.length },
-      // push notifications: only when acms({ mobile: { push } }) is on, owners only
-      ...(PUSH.enabled && me.role === 'Owner' ? [{ key: 'mobile', label: 'Mobile app', href: '/admin/mobile', icon: icons.phone, count: null }] : []),
+      // app access switches (+ push notifications when acms({ mobile: { push } }) is on), owners only
+      ...(me.role === 'Owner' ? [{ key: 'mobile', label: 'Mobile app', href: '/admin/mobile', icon: icons.phone, count: null }] : []),
     ],
   },
   {
@@ -163,6 +166,7 @@ const themeOpts = [
     <meta name="robots" content="noindex" />
     <title>{title} · {BRAND.name} admin</title>
     <ThemeScript />
+    <ClerkSession keepAlive />
     <script is:inline>
       // restore the collapsed rail before paint
       try { if (localStorage.getItem('acms-rail') === '1') document.documentElement.classList.add('rail-pending'); } catch {}
@@ -171,6 +175,8 @@ const themeOpts = [
     <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet" />
   </head>
   <body>
+    {/* Clerk sign-out is a same-origin POST; the Sign out buttons submit this */}
+    {AUTH.provider === 'clerk' && <form id="acms-logout" method="post" action="/admin/logout" hidden></form>}
     <div class="shell" id="acms-shell">
       <aside class="sidebar" aria-label="Admin navigation">
         <div class="brand">
@@ -231,9 +237,20 @@ const themeOpts = [
             <a class="menu-item" href="/" target="_blank" rel="noopener" role="menuitem">
               <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d={icons.globe} /></svg>View site
             </a>
-            <a class="menu-item" href="/admin/logout" role="menuitem">
-              <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d={icons.out} /></svg>Sign out
-            </a>
+            {AUTH.provider === 'clerk' && (
+              <button class="menu-item" type="button" role="menuitem" data-clerk-profile hidden>
+                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d={icons.shield} /></svg>Sign-in &amp; security
+              </button>
+            )}
+            {AUTH.provider === 'clerk' ? (
+              <button class="menu-item" type="submit" form="acms-logout" role="menuitem">
+                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d={icons.out} /></svg>Sign out
+              </button>
+            ) : (
+              <a class="menu-item" href="/admin/logout" role="menuitem">
+                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d={icons.out} /></svg>Sign out
+              </a>
+            )}
           </div>
         </div>
       </aside>
@@ -313,10 +330,23 @@ const themeOpts = [
             <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d={icons.globe} /></svg>
             <span class="grow">View site</span>
           </a>
-          <a href="/admin/logout" class="danger">
-            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d={icons.out} /></svg>
-            <span class="grow">Sign out</span>
-          </a>
+          {AUTH.provider === 'clerk' && (
+            <a href="#" data-clerk-profile hidden>
+              <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d={icons.shield} /></svg>
+              <span class="grow">Sign-in &amp; security</span>
+            </a>
+          )}
+          {AUTH.provider === 'clerk' ? (
+            <button type="submit" form="acms-logout" class="danger">
+              <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d={icons.out} /></svg>
+              <span class="grow">Sign out</span>
+            </button>
+          ) : (
+            <a href="/admin/logout" class="danger">
+              <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d={icons.out} /></svg>
+              <span class="grow">Sign out</span>
+            </a>
+          )}
         </div>
       </div>
     </dialog>

package/src/layouts/Site.astro

@@ -16,6 +16,7 @@ import { analyticsHead, analyticsBody } from '../lib/analytics';
 import { socialIconPath, socialIconSvg } from '../lib/socialIcons';
 import type { SiteChrome } from '../lib/site-chrome';
 import SiteLogo from '../components/site/SiteLogo.astro';
+import ClerkSession from '../components/auth/ClerkSession.astro';
 import '../styles/site.css';
 import '../styles/cards.css';
 import '../styles/live.css';
@@ -37,10 +38,13 @@ interface Props {
   authorName?: string;
   jsonLd?: Record<string, unknown>;
   noindex?: boolean;
+  // a signed-in staff member is viewing a draft or preview: keep their Clerk
+  // session cookie fresh so reloads and actions still work after a while
+  staffPreview?: boolean;
 }
 const {
   title, description, bare = false, exactTitle = false,
-  image, imageAlt, type = 'website', publishedAt, modifiedAt, authorName, jsonLd, noindex = false,
+  image, imageAlt, type = 'website', publishedAt, modifiedAt, authorName, jsonLd, noindex = false, staffPreview = false,
 } = Astro.props;
 
 const repo = await getRepo(Astro.locals);
@@ -237,6 +241,7 @@ const homeJsonLd =
     <Fragment set:html={`<style>${design.css}</style>`} />
     {analyticsHtml && <Fragment set:html={analyticsHtml} />}
     {settings.headCode && <Fragment set:html={settings.headCode} />}
+    {(staffPreview || preview.role === 'admin') && <ClerkSession keepAlive signedOutUrl="" freshPosts={false} />}
   </head>
   <body>
     {liveSignals?.bar && (

package/src/lib/api.ts

@@ -1,10 +1,12 @@
 import type { Role } from './schema';
 import { z } from 'zod';
-import { validateSession, OWNER_ENV, SESSION_COOKIE } from './auth';
+import { OWNER_ENV } from './auth';
+import { getRequestAuth, validateRequestSession } from './auth/request';
 import type { ContentRepository } from './repo/types';
 
 export class ApiError extends Error {
-  constructor(public status: number, message: string) { super(message); }
+  /** retryAfter: seconds a 429 should wait (mobile API Retry-After; default 60) */
+  constructor(public status: number, message: string, public retryAfter?: number) { super(message); }
 }
 export const json = (body: unknown, status = 200) => Response.json(body, {
   status, headers: { 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff' },
@@ -48,7 +50,7 @@ export async function sessionRole(
   request: Request, cookies: { get(name: string): { value: string } | undefined }, repo: ContentRepository,
 ): Promise<{ id: string; role: Role }> {
   await requireSession(request, cookies, repo);
-  const id = (await validateSession(cookies.get(SESSION_COOKIE)?.value, repo))!;
+  const id = (await validateRequestSession(request, cookies, repo))!;
   if (id === OWNER_ENV) return { id, role: 'owner' };
   const user = await repo.getUser(id);
   return { id, role: user!.role };
@@ -57,7 +59,9 @@ export async function sessionRole(
 export async function requireSession(
   request: Request, cookies: { get(name: string): { value: string } | undefined }, repo: ContentRepository, ownerOnly = false,
 ) {
-  const id = (await validateSession(cookies.get(SESSION_COOKIE)?.value, repo));
+  const auth = await getRequestAuth(request, cookies, repo);
+  if (auth.error === 'unavailable' || auth.error === 'configuration') throw new ApiError(503, 'Sign-in is temporarily unavailable. Please retry.');
+  const id = auth.userId;
   if (!id) throw new ApiError(401, 'Sign in to continue.');
   const user = id === OWNER_ENV ? null : await repo.getUser(id);
   if (id !== OWNER_ENV && (!user || (ownerOnly && user.role !== 'owner'))) throw new ApiError(403, 'Owner access is required.');

package/src/lib/auth/accounts.ts

@@ -0,0 +1,94 @@
+import type { ContentRepository } from '../repo/types';
+import { Role } from '../schema';
+import { AUTH, clerkConfig } from './config';
+import { clerkClient, clerkOperation } from './request';
+import { validAddress } from '../email/config';
+
+export async function inviteClerkUser(repo: ContentRepository, data: { email: string; name: string; role: unknown }, locals?: unknown) {
+  if (AUTH.provider !== 'clerk') throw new Error('Clerk authentication is not enabled.');
+  const config = clerkConfig(locals), email = data.email.trim().toLowerCase(), role = Role.parse(data.role);
+  if (!validAddress(email)) throw new Error('Enter a valid email address.');
+  if (await repo.getUserAuth(email)) throw new Error('This account already exists. Link its Clerk user ID instead.');
+  const client = await clerkClient(locals);
+  const existing = await clerkOperation(() => client.users.getUserList({ emailAddress: [email], limit: 1 }));
+  if (existing.data.length) throw new Error('This email already has a Clerk account. Link its Clerk user ID to an existing ACMS user instead of sending a new-account invitation.');
+  const id = crypto.randomUUID();
+  // Expired/failed invitations do not prevent a deliberate retry.
+  for (const old of await repo.auth.invitations(config.issuer)) if (old.email === email && old.state === 'expired') await repo.auth.invitationState(old.id, 'expired');
+  await repo.auth.reserveInvitation(config.issuer, { id, email, name: data.name.trim().slice(0, 120) || email, role });
+  try {
+    const invitation = await clerkOperation(() => client.invitations.createInvitation({ emailAddress: email, expiresInDays: 7, ignoreExisting: false,
+      redirectUrl: `${config.authorizedParties[0]}/admin/login?signUp=1`, publicMetadata: { acmsInvitationId: id } }));
+    await repo.auth.invitationState(id, 'pending', invitation.id);
+  } catch {
+    await repo.auth.invitationState(id, 'failed');
+    throw new Error('Clerk could not complete the invitation. Check its dashboard before retrying.');
+  }
+}
+export async function revokeClerkInvitation(repo: ContentRepository, id: string, locals?: unknown) {
+  const config = clerkConfig(locals), invitation = await repo.auth.invitation(config.issuer, id);
+  if (!invitation || invitation.state === 'accepted') throw new Error('This invitation cannot be revoked.');
+  // Remove local authority first, even if the remote service is unavailable.
+  await repo.auth.invitationState(id, 'revoked');
+  if (invitation.remoteId) {
+    try { const client = await clerkClient(locals); await clerkOperation(() => client.invitations.revokeInvitation(invitation.remoteId)); }
+    catch { throw new Error('ACMS access was revoked. Clerk delivery could not be cancelled; check the Clerk dashboard.'); }
+  }
+}
+export async function linkClerkUser(repo: ContentRepository, userId: string, subject: string, locals?: unknown) {
+  if (AUTH.provider !== 'clerk' || !/^user_[A-Za-z0-9]+$/.test(subject)) throw new Error('Enter a valid Clerk user ID.');
+  if (!await repo.getUser(userId)) throw new Error('The ACMS account no longer exists.');
+  const config = clerkConfig(locals), client = await clerkClient(locals);
+  const external = await clerkOperation(() => client.users.getUser(subject));
+  if (external.banned || external.locked || !external.emailAddresses.some(e => e.id === external.primaryEmailAddressId && e.verification?.status === 'verified')) throw new Error('The Clerk account needs an active, verified email address.');
+  try { await repo.auth.link(config.issuer, subject, userId); }
+  catch { throw new Error('This Clerk identity or ACMS user is already linked. Active accounts cannot be reassigned.'); }
+  await repo.editor.revokeUserDevices(userId, 'authentication provider linked', Date.now());
+}
+/**
+ * Owner-initiated email change. Clerk-linked accounts sign in by Clerk user
+ * ID, so their email belongs to Clerk (see syncClerkEmails). Elsewhere it's
+ * stored here; with built-in sign-in it is the login, so a change signs the
+ * person out everywhere and can notify the previous address.
+ */
+export async function changeAccountEmail(repo: ContentRepository, userId: string, value: string, opts: { notify?: boolean } = {}, locals?: unknown) {
+  const email = value.trim().toLowerCase();
+  if (!validAddress(email)) throw new Error('Enter a valid email address.');
+  const user = await repo.getUser(userId);
+  if (!user) throw new Error('The ACMS account no longer exists.');
+  if (user.email === email) return false;
+  if (AUTH.provider === 'clerk') {
+    const linked = (await repo.auth.identities(clerkConfig(locals).issuer)).some((r) => String(r.userId) === userId);
+    if (linked) throw new Error('This account signs in with Clerk. Change its email in Clerk; ACMS picks it up automatically.');
+  }
+  const taken = await repo.getUserAuth(email);
+  if (taken && taken.user.id !== userId) throw new Error('Another account already uses this email.');
+  const builtin = AUTH.provider === 'builtin';
+  await repo.changeUserEmail(userId, email, { signOut: builtin, notify: builtin && opts.notify !== false });
+  return true;
+}
+/**
+ * Copy each linked account's verified primary Clerk email into ACMS so the
+ * users list, bylines and notifications follow changes made in Clerk. Runs
+ * when owners open the users page; failures leave the stored email as is.
+ */
+export async function syncClerkEmails(repo: ContentRepository, locals?: unknown) {
+  if (AUTH.provider !== 'clerk') return 0;
+  const config = clerkConfig(locals);
+  const links = new Map((await repo.auth.identities(config.issuer)).map((r) => [String(r.subject), String(r.userId)]));
+  if (!links.size) return 0;
+  const client = await clerkClient(locals);
+  const { data } = await clerkOperation(() => client.users.getUserList({ userId: [...links.keys()].slice(0, 100), limit: 100 }));
+  let changed = 0;
+  for (const external of data) {
+    const userId = links.get(external.id);
+    const email = external.emailAddresses.find(e => e.id === external.primaryEmailAddressId && e.verification?.status === 'verified')?.emailAddress.toLowerCase();
+    if (!userId || !email || !validAddress(email)) continue;
+    const user = await repo.getUser(userId);
+    if (!user || user.email === email) continue;
+    // never take an address another ACMS account holds; leave both untouched
+    if (await repo.getUserAuth(email)) continue;
+    try { await repo.changeUserEmail(userId, email, { signOut: false, notify: false }); changed++; } catch { /* concurrent change */ }
+  }
+  return changed;
+}

package/src/lib/auth/config.ts

@@ -0,0 +1,22 @@
+import { userConfig } from 'virtual:acms-config';
+import { runtimeValue } from '../email/config';
+
+export const AUTH = { provider: (userConfig as { auth?: { provider: 'builtin' | 'clerk' } }).auth?.provider ?? 'builtin' };
+export function clerkPublicConfig(locals?: unknown) {
+  const publishableKey = runtimeValue('PUBLIC_CLERK_PUBLISHABLE_KEY', locals).trim();
+  if (!/^pk_(test|live)_[A-Za-z0-9=]+$/.test(publishableKey)) throw new Error('Configure PUBLIC_CLERK_PUBLISHABLE_KEY.');
+  const host = Buffer.from(publishableKey.replace(/^pk_(test|live)_/, ''), 'base64').toString('utf8');
+  if (!/^[a-zA-Z0-9](?:[a-zA-Z0-9.-]*[a-zA-Z0-9])?\$$/.test(host) || !host.includes('.')) throw new Error('Invalid Clerk publishable key.');
+  return { publishableKey, frontendApi: host.slice(0, -1) };
+}
+export function clerkConfig(locals?: unknown) {
+  const publicConfig = clerkPublicConfig(locals);
+  const secretKey = runtimeValue('CLERK_SECRET_KEY', locals).trim();
+  if (!/^sk_(test|live)_/.test(secretKey)) throw new Error('Configure CLERK_SECRET_KEY.');
+  const authorizedParties = runtimeValue('CLERK_AUTHORIZED_PARTIES', locals).split(',').map(s => s.trim()).filter(Boolean);
+  if (!authorizedParties.length || authorizedParties.some(s => {
+    try { const u = new URL(s); return u.origin !== s || (u.protocol !== 'https:' && !(u.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(u.hostname))); } catch { return true; }
+  })) throw new Error('Configure CLERK_AUTHORIZED_PARTIES with comma-separated trusted site origins.');
+  return { ...publicConfig, secretKey, jwtKey: runtimeValue('CLERK_JWT_KEY', locals) || undefined, authorizedParties, issuer: `https://${publicConfig.frontendApi}`,
+    ownerSubject: runtimeValue('CLERK_OWNER_USER_ID', locals).trim(), ownerLocalId: runtimeValue('CLERK_OWNER_LOCAL_USER_ID', locals).trim() };
+}

package/src/lib/auth/login-limit.ts

@@ -0,0 +1,15 @@
+import type { ContentRepository } from '../repo/types';
+import { sha256Hex } from '../api-keys';
+
+// Builtin password sign-in throttle, in the same store and 15-minute windows
+// as password reset. Counted before the password is checked, so it also caps
+// hashing work. 20 per address leaves room for a shared office/church NAT; 10
+// per account (the owner password is one account) stops spreading guesses for
+// one login across many addresses. Windows expire, so a flood aimed at an
+// account only delays its owner by minutes.
+const WINDOW = 15 * 60_000;
+export async function allowLogin(repo: ContentRepository, address: string, email: string): Promise<boolean> {
+  const ip = await repo.email.rateLimit(`login:ip:${await sha256Hex(address)}`, 20, WINDOW);
+  const account = await repo.email.rateLimit(`login:account:${await sha256Hex(email.trim().toLowerCase() || 'owner')}`, 10, WINDOW);
+  return ip && account;
+}

package/src/lib/auth/request.ts

@@ -0,0 +1,161 @@
+import type { ClerkClient } from '@clerk/backend';
+import type { ContentRepository } from '../repo/types';
+import { validateSession, SESSION_COOKIE } from '../auth';
+import { AUTH, clerkConfig } from './config';
+import type { ClerkBinding } from './store';
+
+type Cookies = { get(name: string): { value: string } | undefined };
+export interface RequestAuth {
+  userId: string | null;
+  provider: 'builtin' | 'clerk';
+  clerk: ClerkBinding | null;
+  headers: Headers;
+  error: 'configuration' | 'unavailable' | 'access_denied' | null;
+  reverified: boolean;
+}
+const requests = new WeakMap<Request, Promise<RequestAuth>>();
+const environments = new WeakMap<Request, unknown>();
+const contexts = new WeakMap<object, Promise<RequestAuth>>();
+const liveSessions = new Map<string, { until: number; active: boolean }>();
+const operations = new Map<object, number>();
+/** Bound caller wait time and concurrent callers, including cancelled Worker requests. */
+export async function clerkOperation<T>(start: () => Promise<T>): Promise<T> {
+  // Expiring leases also recover when a Worker cancels the whole request
+  // before either its timer or promise continuation can run.
+  const now = Date.now();
+  for (const [slot, until] of operations) if (until <= now) operations.delete(slot);
+  if (operations.size >= 64) throw new Error('Authentication service is busy.');
+  const slot = {}; operations.set(slot, now + 8000);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const pending = Promise.resolve().then(start);
+  try {
+    return await Promise.race([pending, new Promise<never>((_, reject) => { timer = setTimeout(() => reject(new Error('Authentication service timed out.')), 8000); })]);
+  } finally { clearTimeout(timer); operations.delete(slot); }
+}
+export function invalidateClerkSession(binding: ClerkBinding) { liveSessions.delete(`${binding.issuer}:${binding.subject}:${binding.sessionId}`); }
+export function bindAuthEnvironment(request: Request, locals: unknown) { environments.set(request, locals); }
+export function shouldResolveClerk(request: Request): boolean {
+  const path = new URL(request.url).pathname;
+  if (/^\/(media|embed)(\/|$)/.test(path) || path.startsWith('/api/v1/')) return false;
+  return path.startsWith('/admin') || /(?:^|;\s*)__session(?:_[^=;]+)?=/.test(request.headers.get('cookie') ?? '');
+}
+export function withClerkHeaders(response: Response, auth: RequestAuth | null, request: Request): Response {
+  if (!auth) return response;
+  const output = new Response(response.body, response);
+  for (const value of auth.headers.getSetCookie()) output.headers.append('Set-Cookie', value);
+  if (auth.clerk || auth.headers.has('set-cookie') || /(?:^|;\s*)__session(?:_[^=;]+)?=/.test(request.headers.get('cookie') ?? '') || new URL(request.url).pathname.startsWith('/admin')) {
+    output.headers.set('Cache-Control', 'private, no-store');
+    output.headers.append('Vary', 'Cookie');
+  }
+  return output;
+}
+export function authEnvironment(request: Request, locals?: unknown) { return environments.get(request) ?? locals; }
+export async function clerkClient(locals?: unknown): Promise<ClerkClient> {
+  const config = clerkConfig(locals);
+  const { createClerkClient } = await import('@clerk/backend');
+  return createClerkClient({ secretKey: config.secretKey, publishableKey: config.publishableKey, jwtKey: config.jwtKey });
+}
+function clerkStatus(client: ClerkClient, binding: ClerkBinding) {
+  return clerkOperation(() => Promise.all([client.sessions.getSession(binding.sessionId), client.users.getUser(binding.subject)]));
+}
+export async function activeClerkSession(client: ClerkClient, binding: ClerkBinding, fresh = true): Promise<boolean> {
+  const key = `${binding.issuer}:${binding.subject}:${binding.sessionId}`;
+  const cached = liveSessions.get(key);
+  if (!fresh && cached && cached.until > Date.now()) return cached.active;
+  let status: Awaited<ReturnType<typeof clerkStatus>>;
+  try { status = await clerkStatus(client, binding); }
+  catch (error) {
+    const { isClerkAPIResponseError } = await import('@clerk/backend/errors');
+    if (isClerkAPIResponseError(error) && error.status === 404) { liveSessions.delete(key); return false; }
+    throw error;
+  }
+  const [session, user] = status;
+  const active = session.userId === binding.subject && session.status === 'active' && session.expireAt > Date.now() && !user.banned && !user.locked;
+  for (const [k,v] of liveSessions) if (v.until <= Date.now()) liveSessions.delete(k);
+  if (liveSessions.size >= 256) liveSessions.delete(liveSessions.keys().next().value!);
+  liveSessions.set(key, { active, until: Math.min(Date.now() + 10000, session.expireAt) });
+  return active;
+}
+export function getRequestAuth(request: Request, cookies: Cookies, localsOrRepo?: unknown): Promise<RequestAuth> {
+  if (AUTH.provider === 'builtin') return validateSession(cookies.get(SESSION_COOKIE)?.value, localsOrRepo).then(userId => ({ userId, provider: 'builtin', clerk: null, headers: new Headers(), error: null, reverified: false }));
+  let cached = requests.get(request);
+  if (!cached) {
+    if (!(localsOrRepo && typeof localsOrRepo === 'object' && 'email' in localsOrRepo)) environments.set(request, localsOrRepo);
+    cached = resolveClerk(request, localsOrRepo);
+    requests.set(request, cached);
+    if (localsOrRepo && typeof localsOrRepo === 'object' && !('email' in localsOrRepo)) contexts.set(localsOrRepo, cached);
+  }
+  return cached;
+}
+export async function validatePreviewSession(cookies: Cookies, locals?: unknown) {
+  if (AUTH.provider === 'builtin') return validateSession(cookies.get(SESSION_COOKIE)?.value, locals);
+  return locals && typeof locals === 'object' ? (await contexts.get(locals))?.userId ?? null : null;
+}
+async function resolveClerk(request: Request, localsOrRepo?: unknown): Promise<RequestAuth> {
+  const result: RequestAuth = { userId: null, provider: 'clerk', clerk: null, headers: new Headers(), error: null, reverified: false };
+  if (!shouldResolveClerk(request)) return result;
+  let config: ReturnType<typeof clerkConfig>;
+  try { config = clerkConfig(authEnvironment(request, localsOrRepo)); } catch { return { ...result, error: 'configuration' }; }
+  if (!config.authorizedParties.includes(new URL(request.url).origin)) return { ...result, error: 'configuration' };
+  try {
+    const client = await clerkClient(authEnvironment(request, localsOrRepo));
+    // Admin web routes accept cookie sessions only; mobile uses its separate
+    // device-token API. Never let a bearer header override a browser cookie.
+    const headers = new Headers(request.headers); headers.delete('authorization');
+    const authUrl = new URL(request.url);
+    // OAuth callback codes and other API query secrets must not enter Clerk's
+    // handshake redirect URL. APIs fail closed instead of redirecting.
+    if (authUrl.pathname.startsWith('/api/')) authUrl.search = '';
+    const state = await clerkOperation(() => client.authenticateRequest(new Request(authUrl, { method: request.method, headers }), { authorizedParties: config.authorizedParties, acceptsToken: 'session_token' }));
+    result.headers = state.headers;
+    const auth = state.toAuth();
+    if (!auth || !auth.userId || !auth.sessionId || !state.isAuthenticated) return result;
+    if (auth.sessionClaims.iss !== config.issuer || typeof auth.sessionClaims.azp !== 'string' || !config.authorizedParties.includes(auth.sessionClaims.azp)) return result;
+    const binding = { issuer: config.issuer, subject: auth.userId, sessionId: auth.sessionId };
+    if (!await activeClerkSession(client, binding, !['GET','HEAD'].includes(request.method))) return result;
+    result.clerk = binding;
+    result.reverified = auth.has({ reverification: 'strict' });
+    const { getRepo } = await import('../repo');
+    const repo = localsOrRepo && typeof localsOrRepo === 'object' && 'email' in localsOrRepo ? localsOrRepo as ContentRepository : await getRepo(localsOrRepo);
+    let id = await repo.auth.identity(config.issuer, auth.userId);
+    if (!id) {
+      const user = await clerkOperation(() => client.users.getUser(auth.userId));
+      const email = user.emailAddresses.find(e => e.id === user.primaryEmailAddressId && e.verification?.status === 'verified')?.emailAddress.toLowerCase();
+      if (email) {
+        try {
+          if (config.ownerSubject && config.ownerSubject === user.id) {
+            if (config.ownerLocalId && (await repo.getUser(config.ownerLocalId))?.role !== 'owner') return { ...result, error: 'access_denied' };
+            await repo.auth.bootstrap(config.issuer, user.id, { email, name: [user.firstName, user.lastName].filter(Boolean).join(' ') || email, localId: config.ownerLocalId });
+          } else if (typeof user.publicMetadata.acmsInvitationId === 'string') {
+            await repo.auth.acceptInvitation(config.issuer, user.id, user.publicMetadata.acmsInvitationId, email);
+          }
+        } catch { /* Concurrent provisioning or a conflicting identity: re-read, never merge. */ }
+        id = await repo.auth.identity(config.issuer, auth.userId);
+      }
+    }
+    result.userId = id && await repo.getUser(id) ? id : null;
+    if (!result.userId) result.error = 'access_denied';
+    return result;
+  } catch { return { ...result, userId: null, error: 'unavailable' }; }
+}
+export async function validateRequestSession(request: Request, cookies: Cookies, localsOrRepo?: unknown) {
+  return (await getRequestAuth(request, cookies, localsOrRepo)).userId;
+}
+/** Stable browser-session binding for consent and third-party OAuth state. */
+export async function requestSessionBinding(request: Request, cookies: Cookies, localsOrRepo?: unknown) {
+  const auth = await getRequestAuth(request, cookies, localsOrRepo);
+  if (!auth.userId) return '';
+  return auth.clerk ? `${auth.clerk.issuer}:${auth.clerk.sessionId}:${auth.userId}` : cookies.get(SESSION_COOKIE)?.value ?? '';
+}
+export class ClerkUnavailableError extends Error {
+  constructor() { super('Sign-in is temporarily unavailable. Please retry.'); }
+}
+export async function validateMobileBinding(repo: ContentRepository, kind: 'code' | 'device', id: string, userId: string, locals?: unknown, fresh = true) {
+  const binding = await repo.auth.mobile(kind, id);
+  if (AUTH.provider === 'builtin') return !binding;
+  if (!binding) return false;
+  try {
+    if (binding.issuer !== clerkConfig(locals).issuer || await repo.auth.identity(binding.issuer, binding.subject) !== userId) return false;
+    return await activeClerkSession(await clerkClient(locals), binding, fresh);
+  } catch { throw new ClerkUnavailableError(); }
+}

package/src/lib/auth/store.ts

@@ -0,0 +1,72 @@
+import type { SqlDriver } from '../repo/sql';
+import type { Role } from '../schema';
+
+export interface ClerkBinding { issuer: string; subject: string; sessionId: string }
+export interface AuthInvitation { id: string; email: string; name: string; role: Role; remoteId: string; state: string; expiresAt: number }
+function invitation(r: Record<string, unknown>): AuthInvitation {
+  return { id: String(r.id), email: String(r.email), name: String(r.name), role: r.role as Role, remoteId: String(r.remote_id), state: r.state === 'pending' && Number(r.expires_at) <= Date.now() ? 'expired' : String(r.state), expiresAt: Number(r.expires_at) };
+}
+export class AuthStore {
+  constructor(private driver: () => Promise<SqlDriver>) {}
+  async identity(issuer: string, subject: string): Promise<string | null> {
+    const r = await (await this.driver()).all('SELECT user_id FROM auth_identities WHERE issuer=? AND subject=? AND disabled=0', [issuer, subject]);
+    return r[0] ? String(r[0].user_id) : null;
+  }
+  async identities(issuer: string) {
+    return (await this.driver()).all('SELECT user_id AS userId, subject FROM auth_identities WHERE issuer=? AND disabled=0', [issuer]);
+  }
+  async link(issuer: string, subject: string, userId: string) {
+    // Explicit owner-approved links may replace disabled tombstones only.
+    // Active identities are immutable; uniqueness conflicts roll back the batch.
+    await (await this.driver()).batch([
+      { sql: 'DELETE FROM auth_identities WHERE issuer=? AND disabled=1 AND (subject=? OR user_id=?)', args: [issuer, subject, userId] },
+      { sql: 'INSERT INTO auth_identities(issuer,subject,user_id) SELECT ?,?,id FROM users WHERE id=?', args: [issuer, subject, userId] },
+      { sql: 'UPDATE users SET session_version=session_version+1 WHERE id=?', args: [userId] },
+    ]);
+    if (await this.identity(issuer, subject) !== userId) throw new Error('This Clerk identity is already linked to another account.');
+  }
+  async bootstrap(issuer: string, subject: string, data: { email: string; name: string; localId: string }) {
+    const db = await this.driver(), id = data.localId || crypto.randomUUID();
+    const exists = await db.all('SELECT 1 FROM auth_bootstrap WHERE issuer=?', [issuer]);
+    if (exists.length) return;
+    await db.batch([
+      { sql: 'INSERT INTO auth_bootstrap(issuer) VALUES (?)', args: [issuer] },
+      ...(data.localId ? [] : [{ sql: "INSERT INTO users(id,name,email,role,pass_hash,created_at) VALUES (?,?,?,'owner','',?)", args: [id, data.name, data.email, Date.now()] }]),
+      { sql: "INSERT INTO auth_identities(issuer,subject,user_id) SELECT ?,?,id FROM users WHERE id=? AND role='owner'", args: [issuer, subject, id] },
+      { sql: 'UPDATE users SET session_version=session_version+1 WHERE id=?', args: [id] },
+    ]);
+  }
+  async invitations(issuer: string): Promise<AuthInvitation[]> {
+    return (await (await this.driver()).all('SELECT * FROM auth_invitations WHERE issuer=? ORDER BY created_at DESC LIMIT 200', [issuer])).map(invitation);
+  }
+  async invitation(issuer: string, id: string) {
+    const rows = await (await this.driver()).all('SELECT * FROM auth_invitations WHERE issuer=? AND id=?', [issuer, id]);
+    return rows[0] ? invitation(rows[0]) : null;
+  }
+  async reserveInvitation(issuer: string, data: { id: string; email: string; name: string; role: Role }) {
+    await (await this.driver()).run("UPDATE auth_invitations SET state='expired' WHERE issuer=? AND email=? AND state='pending' AND expires_at<=?", [issuer,data.email,Date.now()]);
+    await (await this.driver()).run("INSERT INTO auth_invitations(id,issuer,email,name,role,state,remote_id,expires_at,created_at) VALUES (?,?,?,?,?,'sending','',?,?)", [data.id, issuer, data.email, data.name, data.role, Date.now() + 7 * 86400000, Date.now()]);
+  }
+  async invitationState(id: string, state: string, remoteId = '') {
+    const guard = state === 'pending' || state === 'failed' ? " AND state='sending'" : " AND state<>'accepted'";
+    await (await this.driver()).run(`UPDATE auth_invitations SET state=?,remote_id=CASE WHEN ?='' THEN remote_id ELSE ? END WHERE id=?${guard}`, [state, remoteId, remoteId, id]);
+  }
+  async acceptInvitation(issuer: string, subject: string, id: string, email: string): Promise<void> {
+    const userId = crypto.randomUUID(), db = await this.driver();
+    // The metadata ID came from Clerk's server-controlled publicMetadata;
+    // verified email plus the live local invitation are both required.
+    await db.batch([
+      { sql: `INSERT INTO users(id,name,email,role,pass_hash,created_at) SELECT ?,name,email,role,'',? FROM auth_invitations
+          WHERE id=? AND issuer=? AND email=? AND state='pending' AND expires_at>?`, args: [userId, Date.now(), id, issuer, email, Date.now()] },
+      { sql: 'INSERT INTO auth_identities(issuer,subject,user_id) SELECT ?,?,id FROM users WHERE id=?', args: [issuer, subject, userId] },
+      { sql: "UPDATE auth_invitations SET state='accepted' WHERE id=? AND EXISTS(SELECT 1 FROM users WHERE id=?)", args: [id, userId] },
+    ]);
+  }
+  async bindMobile(kind: 'code' | 'device', id: string, binding: ClerkBinding) {
+    await (await this.driver()).run('INSERT INTO auth_mobile(kind,id,issuer,subject,session_id) VALUES (?,?,?,?,?)', [kind, id, binding.issuer, binding.subject, binding.sessionId]);
+  }
+  async mobile(kind: 'code' | 'device', id: string): Promise<ClerkBinding | null> {
+    const r = await (await this.driver()).all('SELECT * FROM auth_mobile WHERE kind=? AND id=?', [kind, id]);
+    return r[0] ? { issuer: String(r[0].issuer), subject: String(r[0].subject), sessionId: String(r[0].session_id) } : null;
+  }
+}

package/src/lib/auth.ts

@@ -1,3 +1,4 @@
+import { AUTH } from './auth/config';
 import { createHmac, timingSafeEqual } from 'node:crypto';
 import { env } from './env';
 
@@ -60,6 +61,7 @@ export function verifySessionToken(token: string | undefined): string | null {
 
 // The env master password — bootstrap owner login, kept for backward compat.
 export function checkPassword(input: string): boolean {
+  if (AUTH.provider !== 'builtin') return false;
   const pw = env('ADMIN_PASSWORD');
   if (!pw) return false;
   return safeEqual(input, pw);
@@ -103,6 +105,7 @@ export const SESSION_COOKIE = COOKIE;
 
 // All authorization paths must consult the database, not just the signature.
 export async function validateSession(token: string | undefined, localsOrRepo?: unknown): Promise<string | null> {
+  if (AUTH.provider !== 'builtin') return null;
   const id = verifySessionToken(token);
   if (!id || id === OWNER_ENV) return id;
   const { getRepo } = await import('./repo');

package/src/lib/backup/archive.ts

@@ -0,0 +1,26 @@
+import type { ContentRepository } from '../repo/types';
+import { getMediaStore } from '../media/store';
+import { exportContent } from './content';
+import { zipStream, type ZipEntry } from './zip';
+
+// The full-site backup ZIP: content.json with every table, fetched through
+// the repo so sqlite and D1 both export the same shape, plus the media
+// binaries (originals + variants) under media/<key>. Password hashes never
+// leave the repo layer, so user accounts export without them. Shared by the
+// download (Admin → Backup) and scheduled off-site backups.
+export async function backupArchive(repo: ContentRepository, locals: unknown, now = Date.now()): Promise<ReadableStream<Uint8Array>> {
+  const content = await exportContent(repo, now);
+  const { media } = content;
+  const store = getMediaStore(locals);
+  async function* entries(): AsyncGenerator<ZipEntry> {
+    yield { name: 'content.json', data: new TextEncoder().encode(JSON.stringify(content, null, 2)) };
+    for (const m of media) {
+      for (const key of [m.key, ...m.variants.map((v) => v.key)]) {
+        const obj = await store.get(key);
+        if (!obj) throw new Error('Backup incomplete: a media object is missing.');
+        yield { name: `media/${key}`, data: new Uint8Array(await new Response(obj.body).arrayBuffer()) };
+      }
+    }
+  }
+  return zipStream(entries(), now);
+}

package/src/lib/backup/content.ts

@@ -38,7 +38,7 @@ export async function exportContent(repo: ContentRepository, now = Date.now()) {
   ]);
   return {
     format: 'acms-backup' as const, version: 6, exportedAt: new Date(now).toISOString(),
-    settings: { ...settings, live: { ...settings.live, mode: 'off' as const, manual: { watchUrl: '', title: 'We’re live', until: 0 } }, ai: { ...settings.ai, enabled: false, encryptedKey: '' }, agent: { ...settings.agent, enabled: false, keyHash: '', keyPrefix: '', allowPublish: false } },
+    settings: { ...settings, live: { ...settings.live, mode: 'off' as const, manual: { watchUrl: '', title: 'We’re live', until: 0 } }, ai: { ...settings.ai, enabled: false, encryptedKey: '' }, agent: { ...settings.agent, enabled: false, keyHash: '', keyPrefix: '', allowPublish: false }, monitoring: { ...settings.monitoring, pushUrl: '' } },
     pages, posts, media, links, tags, navItems, users, redirects,
     calendars: calendars.map(c => ({ ...c, feedToken: '' })), events,
     resources: resources.map(r => ({ ...r, feedToken: '' })), bookingLinks, ...bookingState, places, forms, formSubmissions,