shraga 0.0.3 → 0.1.1

package/src/server/artifacts/artifacts.export.ts

@@ -0,0 +1,85 @@
+import { writeFileSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { dataPath } from '../paths.ts';
+
+const PREFIX = '[artifacts:export]';
+
+let browserInstance: any = null;
+let idleTimer: ReturnType<typeof setTimeout> | null = null;
+const IDLE_TIMEOUT = 60_000;
+
+async function getBrowser() {
+  if (browserInstance) {
+    resetIdleTimer();
+    return browserInstance;
+  }
+
+  let puppeteer: any;
+  try {
+    puppeteer = await import('puppeteer');
+  } catch {
+    throw new Error('puppeteer not installed. Run: bun add puppeteer');
+  }
+
+  console.log(PREFIX, 'launching browser');
+  browserInstance = await puppeteer.default.launch({
+    headless: true,
+    args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage'],
+  });
+
+  browserInstance.on('disconnected', () => { browserInstance = null; });
+  resetIdleTimer();
+  return browserInstance;
+}
+
+function resetIdleTimer() {
+  if (idleTimer) clearTimeout(idleTimer);
+  idleTimer = setTimeout(async () => {
+    if (browserInstance) {
+      console.log(PREFIX, 'closing idle browser');
+      await browserInstance.close().catch(() => {});
+      browserInstance = null;
+    }
+  }, IDLE_TIMEOUT);
+}
+
+export async function exportToPng(
+  html: string,
+  dimensions: [number, number],
+): Promise<Buffer> {
+  const [width, height] = dimensions;
+  const browser = await getBrowser();
+  const page = await browser.newPage();
+
+  try {
+    await page.setViewport({ width, height, deviceScaleFactor: 2 });
+    await page.setContent(html, { waitUntil: 'networkidle0', timeout: 15_000 });
+    const png = await page.screenshot({ type: 'png', clip: { x: 0, y: 0, width, height } });
+    return Buffer.from(png);
+  } finally {
+    await page.close();
+  }
+}
+
+export async function exportAndSave(
+  sessionId: string,
+  artifactId: string,
+  html: string,
+  dimensions: [number, number],
+): Promise<string> {
+  const png = await exportToPng(html, dimensions);
+  const dir = dataPath(`sessions/${sessionId}/artifacts`);
+  mkdirSync(dir, { recursive: true });
+  const filePath = path.join(dir, `${artifactId}.png`);
+  writeFileSync(filePath, png);
+  console.log(PREFIX, `saved ${filePath} (${png.length} bytes)`);
+  return filePath;
+}
+
+export async function closeBrowser() {
+  if (idleTimer) clearTimeout(idleTimer);
+  if (browserInstance) {
+    await browserInstance.close().catch(() => {});
+    browserInstance = null;
+  }
+}

package/src/server/artifacts/artifacts.handler.ts

@@ -0,0 +1,93 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { createArtifact, updateArtifact, findByFilePath } from './artifacts.service.ts';
+
+const PREFIX = '[artifacts:handler]';
+const ARTIFACT_META_RE = /<!--\s*artifact:\s*(\{[^}]+\})\s*-->/;
+
+interface ArtifactMeta {
+  title?: string;
+  dimensions?: [number, number];
+  id?: string;
+}
+
+function parseMeta(html: string): ArtifactMeta | null {
+  const match = html.match(ARTIFACT_META_RE);
+  if (!match) return null;
+  try { return JSON.parse(match[1]); }
+  catch (err) { console.error(PREFIX, 'failed to parse artifact meta:', err); return null; }
+}
+
+function emitEvent(sessionId: string, a: { id: string; title: string; dimensions: [number, number]; version: number }) {
+  return { type: 'artifact', id: a.id, sessionId, title: a.title, dimensions: a.dimensions, version: a.version };
+}
+
+/**
+ * Intercepts Write and Edit tool calls to detect artifact creation/updates.
+ * - Write: full content available in input, parsed directly
+ * - Edit: file already modified on disk by SDK; re-read to detect artifact + refresh
+ */
+export function handleArtifactToolUse(sessionId: string, tool: string, input: unknown): object | null {
+  if (tool === 'Write') return handleWrite(sessionId, input);
+  if (tool === 'Edit') return handleEdit(sessionId, input);
+  return null;
+}
+
+function handleWrite(sessionId: string, input: unknown): object | null {
+  const inp = input as { file_path?: string; content?: string };
+  if (!inp.file_path || !inp.content) return null;
+
+  const meta = parseMeta(inp.content);
+  if (!meta) return null;
+
+  const title = meta.title || 'Untitled';
+  const dimensions = meta.dimensions || [1080, 1080];
+
+  if (meta.id) {
+    const updated = updateArtifact(sessionId, meta.id, { html: inp.content, title, dimensions });
+    if (updated) return emitEvent(sessionId, updated);
+  }
+
+  const artifact = createArtifact(sessionId, { title, html: inp.content, dimensions, filePath: inp.file_path });
+  return emitEvent(sessionId, artifact);
+}
+
+function handleEdit(sessionId: string, input: unknown): object | null {
+  const inp = input as { file_path?: string };
+  if (!inp.file_path) return null;
+
+  // Check if this file path belongs to a known artifact
+  const existing = findByFilePath(sessionId, inp.file_path);
+  if (!existing) {
+    // Could be an Edit on a file that happens to have artifact meta (rare)
+    // We'd need the file to already exist on disk — SDK applies the edit before we see it
+    if (!existsSync(inp.file_path)) return null;
+    try {
+      const html = readFileSync(inp.file_path, 'utf-8');
+      const meta = parseMeta(html);
+      if (!meta) return null;
+      const artifact = createArtifact(sessionId, {
+        title: meta.title || 'Untitled',
+        html,
+        dimensions: meta.dimensions || [1080, 1080],
+        filePath: inp.file_path,
+      });
+      return emitEvent(sessionId, artifact);
+    } catch { return null; }
+  }
+
+  // Known artifact — re-read from disk to get updated content
+  if (!existsSync(inp.file_path)) return null;
+  try {
+    const html = readFileSync(inp.file_path, 'utf-8');
+    const meta = parseMeta(html);
+    const updated = updateArtifact(sessionId, existing.id, {
+      html,
+      title: meta?.title || existing.title,
+      dimensions: meta?.dimensions || existing.dimensions,
+    });
+    if (updated) return emitEvent(sessionId, updated);
+  } catch (err) {
+    console.error(PREFIX, 'failed to re-read edited artifact:', err);
+  }
+  return null;
+}

package/src/server/artifacts/artifacts.routes.ts

@@ -0,0 +1,43 @@
+import { Router, type Request } from 'express';
+import { requireAuth } from '../auth.ts';
+import { getArtifact, getArtifactHtml, listArtifacts } from './artifacts.service.ts';
+import { exportToPng } from './artifacts.export.ts';
+
+const PREFIX = '[artifacts:http]';
+
+export const artifactsRouter = Router();
+
+artifactsRouter.get('/api/artifacts/:sid', requireAuth, (req: Request<{ sid: string }>, res) => {
+  const artifacts = listArtifacts(req.params.sid);
+  res.json(artifacts);
+});
+
+// No auth — served as iframe src (session IDs are unguessable UUIDs)
+artifactsRouter.get('/api/artifacts/:sid/:id', (req: Request<{ sid: string; id: string }>, res) => {
+  const html = getArtifactHtml(req.params.sid, req.params.id);
+  if (!html) return res.sendStatus(404);
+  res.type('html').send(html);
+});
+
+artifactsRouter.get('/api/artifacts/:sid/:id/meta', requireAuth, (req: Request<{ sid: string; id: string }>, res) => {
+  const artifact = getArtifact(req.params.sid, req.params.id);
+  if (!artifact) return res.sendStatus(404);
+  res.json(artifact.meta);
+});
+
+artifactsRouter.post('/api/artifacts/:sid/:id/export', requireAuth, async (req: Request<{ sid: string; id: string }>, res) => {
+  const { sid, id } = req.params;
+  const artifact = getArtifact(sid, id);
+  if (!artifact) return res.sendStatus(404);
+
+  const dimensions: [number, number] = req.body?.dimensions ?? artifact.meta.dimensions;
+
+  try {
+    const png = await exportToPng(artifact.html, dimensions);
+    console.log(PREFIX, `exported ${id} → ${png.length} bytes`);
+    res.type('png').send(png);
+  } catch (err: any) {
+    console.error(PREFIX, 'export failed:', err.message);
+    res.status(500).json({ error: err.message });
+  }
+});

package/src/server/artifacts/artifacts.service.ts

@@ -0,0 +1,100 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { dataPath } from '../paths.ts';
+import type { Artifact, ArtifactIndex } from './artifacts.types.ts';
+
+const PREFIX = '[artifacts]';
+
+function artifactsDir(sessionId: string): string {
+  return dataPath(`sessions/${sessionId}/artifacts`);
+}
+
+function indexPath(sessionId: string): string {
+  return path.join(artifactsDir(sessionId), '_index.json');
+}
+
+function htmlPath(sessionId: string, id: string): string {
+  return path.join(artifactsDir(sessionId), `${id}.html`);
+}
+
+function loadIndex(sessionId: string): ArtifactIndex {
+  const p = indexPath(sessionId);
+  if (!existsSync(p)) return { artifacts: [] };
+  try { return JSON.parse(readFileSync(p, 'utf-8')); }
+  catch { return { artifacts: [] }; }
+}
+
+function saveIndex(sessionId: string, index: ArtifactIndex): void {
+  const dir = artifactsDir(sessionId);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(indexPath(sessionId), JSON.stringify(index, null, 2));
+}
+
+function generateId(): string {
+  return `art_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
+export function createArtifact(sessionId: string, opts: { title: string; html: string; dimensions?: [number, number]; filePath?: string }): Artifact {
+  const id = generateId();
+  const now = Date.now();
+  const artifact: Artifact = {
+    id,
+    sessionId,
+    title: opts.title,
+    dimensions: opts.dimensions ?? [1080, 1080],
+    version: 1,
+    createdAt: now,
+    updatedAt: now,
+    filePath: opts.filePath,
+  };
+
+  const dir = artifactsDir(sessionId);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(htmlPath(sessionId, id), opts.html, 'utf-8');
+
+  const index = loadIndex(sessionId);
+  index.artifacts.push(artifact);
+  saveIndex(sessionId, index);
+
+  console.log(PREFIX, `created ${id} "${opts.title}" [${artifact.dimensions.join('x')}]`);
+  return artifact;
+}
+
+export function updateArtifact(sessionId: string, id: string, opts: { html?: string; title?: string; dimensions?: [number, number] }): Artifact | null {
+  const index = loadIndex(sessionId);
+  const artifact = index.artifacts.find(a => a.id === id);
+  if (!artifact) return null;
+
+  if (opts.html) writeFileSync(htmlPath(sessionId, id), opts.html, 'utf-8');
+  if (opts.title) artifact.title = opts.title;
+  if (opts.dimensions) artifact.dimensions = opts.dimensions;
+  artifact.version++;
+  artifact.updatedAt = Date.now();
+
+  saveIndex(sessionId, index);
+  console.log(PREFIX, `updated ${id} v${artifact.version}`);
+  return artifact;
+}
+
+export function getArtifact(sessionId: string, id: string): { meta: Artifact; html: string } | null {
+  const index = loadIndex(sessionId);
+  const meta = index.artifacts.find(a => a.id === id);
+  if (!meta) return null;
+  const hp = htmlPath(sessionId, id);
+  if (!existsSync(hp)) return null;
+  return { meta, html: readFileSync(hp, 'utf-8') };
+}
+
+export function listArtifacts(sessionId: string): Artifact[] {
+  return loadIndex(sessionId).artifacts;
+}
+
+export function findByFilePath(sessionId: string, filePath: string): Artifact | null {
+  return loadIndex(sessionId).artifacts.find(a => a.filePath === filePath) ?? null;
+}
+
+export function getArtifactHtml(sessionId: string, id: string): string | null {
+  const hp = htmlPath(sessionId, id);
+  if (!existsSync(hp)) return null;
+  return readFileSync(hp, 'utf-8');
+}

package/src/server/artifacts/artifacts.types.ts

@@ -0,0 +1,31 @@
+export interface Artifact {
+  id: string;
+  sessionId: string;
+  title: string;
+  dimensions: [number, number];
+  version: number;
+  createdAt: number;
+  updatedAt: number;
+  /** Original file path the agent wrote to (for Edit detection) */
+  filePath?: string;
+}
+
+export interface ArtifactIndex {
+  artifacts: Artifact[];
+}
+
+export const DIMENSION_PRESETS: Record<string, [number, number]> = {
+  'fb-feed': [1080, 1080],
+  'fb-story': [1080, 1920],
+  'fb-landscape': [1200, 628],
+  'ig-square': [1080, 1080],
+  'ig-story': [1080, 1920],
+  'ig-landscape': [1080, 566],
+  'banner-leaderboard': [728, 90],
+  'banner-medium': [300, 250],
+};
+
+export class ArtifactOptions {
+  tailwindVersion = '3.4';
+  defaultDimensions: [number, number] = [1080, 1080];
+}

package/src/server/auth.ts

@@ -0,0 +1,262 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { randomBytes, timingSafeEqual, createHmac, scryptSync } from 'node:crypto';
+import { join } from 'node:path';
+import type { Request, Response, NextFunction } from 'express';
+
+// JwtHelper is not exported from the main edge.libx.js entry, import from build directly
+import { JwtHelper } from 'edge.libx.js/build/helpers/jwt.js';
+
+// Cache Google JWKS keys — avoids ~300ms fetch per token verification
+const _jwksCache = { keys: new Map<string, any>(), expiresAt: 0 };
+const _jwksInflight = new Map<string, Promise<any>>();
+const JWKS_TTL = 3600_000;
+// getGooglePublicKey is declared private on JwtHelper; we monkey-patch it (JS allows this
+// at runtime). Bracket access asserts the type without altering behavior.
+const _origGetKey = (JwtHelper as any)['getGooglePublicKey'].bind(JwtHelper);
+(JwtHelper as any)['getGooglePublicKey'] = async function (kid: string) {
+  if (_jwksCache.keys.has(kid) && Date.now() < _jwksCache.expiresAt) return _jwksCache.keys.get(kid);
+  if (_jwksInflight.has(kid)) return _jwksInflight.get(kid);
+  const p = _origGetKey(kid).then((key: any) => {
+    if (key) { _jwksCache.keys.set(kid, key); _jwksCache.expiresAt = Date.now() + JWKS_TTL; }
+    _jwksInflight.delete(kid);
+    return key;
+  }, (err: any) => {
+    _jwksInflight.delete(kid);
+    throw err;
+  });
+  _jwksInflight.set(kid, p);
+  return p;
+};
+import { dataPath } from './paths.ts';
+import { validateApiKey } from './api-keys.ts';
+
+/** Server secret for signing scoped internal tokens — stable per startup. */
+const INTERNAL_SECRET = process.env.INTERNAL_API_TOKEN || randomBytes(32).toString('hex');
+process.env.INTERNAL_API_TOKEN = INTERNAL_SECRET;
+const tmpDir = join(dataPath('..'), '.tmp');
+try { mkdirSync(tmpDir, { recursive: true }); writeFileSync(join(tmpDir, '.internal-token'), INTERNAL_SECRET); } catch (e: any) { console.error('[auth] failed to write .internal-token:', e.message); }
+
+/** Sign a scoped internal token embedding user identity. Agent subprocess uses this as INTERNAL_API_TOKEN — single env var carries both auth + identity. */
+export function signInternalToken(uid: string, email: string): string {
+  const payload = `${uid}:${email}`;
+  const sig = createHmac('sha256', INTERNAL_SECRET).update(payload).digest('hex');
+  return `${sig}:${payload}`;
+}
+
+/** Verify and extract user identity from a scoped internal token. Falls back to legacy global token check. */
+function verifyInternalToken(token: string): { uid: string; email: string } | null {
+  const firstColon = token.indexOf(':');
+  if (firstColon === 64) {
+    const sig = token.slice(0, 64);
+    const payload = token.slice(65);
+    const expected = createHmac('sha256', INTERNAL_SECRET).update(payload).digest('hex');
+    if (sig.length === expected.length && timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
+      const sepIdx = payload.indexOf(':');
+      if (sepIdx > 0) return { uid: payload.slice(0, sepIdx), email: payload.slice(sepIdx + 1) };
+    }
+    return null;
+  }
+  // Legacy: plain global token (backwards compat for old agents / direct curl)
+  if (token.length === INTERNAL_SECRET.length && timingSafeEqual(Buffer.from(token), Buffer.from(INTERNAL_SECRET))) {
+    return { uid: 'agent-internal', email: 'agent@internal' };
+  }
+  return null;
+}
+
+/**
+ * Persisted secret for signing MCP OAuth tokens. Unlike INTERNAL_SECRET (random per boot
+ * unless INTERNAL_API_TOKEN is set), this is stored in data/ so issued access/refresh tokens
+ * survive restarts/deploys — otherwise every restart would force claude.ai users to re-auth.
+ */
+let mcpSecret: string | null = null;
+function getMcpSecret(): string {
+  if (mcpSecret) return mcpSecret;
+  const p = dataPath('.mcp-oauth-secret');
+  try {
+    if (existsSync(p)) {
+      const s = readFileSync(p, 'utf8').trim();
+      if (s) return (mcpSecret = s);
+    }
+    mcpSecret = randomBytes(32).toString('hex');
+    writeFileSync(p, mcpSecret, { mode: 0o600 });
+  } catch (e: any) {
+    console.error('[auth] mcp-oauth secret persist failed, falling back to INTERNAL_SECRET:', e.message);
+    mcpSecret = INTERNAL_SECRET;
+  }
+  return mcpSecret;
+}
+
+/**
+ * Stateless OAuth access/refresh tokens for the MCP endpoint, signed with a persisted secret.
+ * Provider-agnostic: identity is established upstream by requireAuth (Firebase today,
+ * email-password later) — this only carries the resulting {uid, email}. No storage needed.
+ */
+export function signMcpToken(uid: string, email: string, kind: 'access' | 'refresh' = 'access', ttlSec = 3600): string {
+  const exp = Math.floor(Date.now() / 1000) + ttlSec;
+  const payload = `mcp:${kind}:${uid}:${email}:${exp}`;
+  const sig = createHmac('sha256', getMcpSecret()).update(payload).digest('hex');
+  return `mcp_${sig}.${Buffer.from(payload).toString('base64url')}`;
+}
+
+export function verifyMcpToken(token: string): { uid: string; email: string; kind: 'access' | 'refresh' } | null {
+  if (!token.startsWith('mcp_')) return null;
+  const body = token.slice(4);
+  const dot = body.indexOf('.');
+  if (dot < 0) return null;
+  const sig = body.slice(0, dot);
+  let payload: string;
+  try { payload = Buffer.from(body.slice(dot + 1), 'base64url').toString(); } catch { return null; }
+  const expected = createHmac('sha256', getMcpSecret()).update(payload).digest('hex');
+  if (sig.length !== expected.length || !timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) return null;
+  const parts = payload.split(':'); // mcp:kind:uid:email:exp  (uid/email never contain ':')
+  if (parts[0] !== 'mcp' || parts.length < 5) return null;
+  const exp = Number(parts[parts.length - 1]);
+  if (!exp || Math.floor(Date.now() / 1000) > exp) return null;
+  return { kind: parts[1] as 'access' | 'refresh', uid: parts[2], email: parts.slice(3, parts.length - 1).join(':') };
+}
+
+const WHITELIST_PATH = dataPath('whitelist.json');
+
+function loadWhitelist(): string[] {
+  if (!existsSync(WHITELIST_PATH)) return [];
+  try {
+    return JSON.parse(readFileSync(WHITELIST_PATH, 'utf-8'));
+  } catch {
+    return [];
+  }
+}
+
+export interface AuthUser {
+  uid: string;
+  email: string;
+  /** Owners can see all sessions/schedules across users (view-only bypass — mutations still restricted to owner of record). */
+  isOwner: boolean;
+}
+
+/** Owners from env: OWNERS="email1,email2" (case-insensitive). */
+function loadOwners(): string[] {
+  return (process.env.OWNERS ?? '')
+    .split(',')
+    .map((s) => s.trim().toLowerCase())
+    .filter(Boolean);
+}
+
+function isOwnerEmail(email?: string): boolean {
+  // Emailless tokens (e.g. anonymous Firebase users) are never owners — guard the .toLowerCase() crash.
+  return !!email && loadOwners().includes(email.toLowerCase());
+}
+
+export async function verifyToken(token: string): Promise<AuthUser> {
+  const projectId = JSON.parse(process.env.FIREBASE_CONFIG_PROD ?? process.env.VITE_FIREBASE_CONFIG_PROD ?? '{}').projectId;
+  if (!projectId) throw new Error('FIREBASE_CONFIG_PROD not set or missing projectId');
+  let payload: any;
+  try {
+    payload = await JwtHelper.verifyFirebaseToken(token, projectId);
+  } catch (err: any) {
+    const msg = typeof err === 'string' ? err : err?.message ?? String(err);
+    if (msg.includes('aud')) throw new Error(`Token audience mismatch (expected ${projectId}). Please sign out and sign in again.`);
+    throw new Error(msg);
+  }
+  const whitelist = loadWhitelist();
+  if (whitelist.length > 0 && !whitelist.includes(payload.email)) {
+    throw new Error('User not in whitelist');
+  }
+  return { uid: payload.user_id || payload.sub, email: payload.email, isOwner: isOwnerEmail(payload.email) };
+}
+
+// ── Pluggable auth provider ──────────────────────────────────────────────────
+// Default = 'local' (username/password, zero external deps — a dev can install and run
+// with no Firebase). Set AUTH_PROVIDER=firebase (an optional add-on) to verify Firebase
+// ID tokens instead. The provider only turns a bearer token into an AuthUser; api-key and
+// internal-token auth are provider-agnostic.
+export const AUTH_PROVIDER = (process.env.AUTH_PROVIDER || 'local').toLowerCase();
+
+interface LocalUser { email: string; salt: string; hash: string }
+const USERS_PATH = () => dataPath('users.json');
+function loadLocalUsers(): LocalUser[] {
+  try { return existsSync(USERS_PATH()) ? JSON.parse(readFileSync(USERS_PATH(), 'utf-8')) : []; }
+  catch (e: any) { console.error('[auth] users.json unreadable:', e.message); return []; }
+}
+function hashPw(password: string, salt = randomBytes(16).toString('hex')) {
+  return { salt, hash: scryptSync(password, salt, 64).toString('hex') };
+}
+/** Create a local user (used by `shraga user add` and first-run /api/auth/register). */
+export function addLocalUser(email: string, password: string): void {
+  const users = loadLocalUsers();
+  if (users.some((u) => u.email === email)) throw new Error(`user ${email} already exists`);
+  users.push({ email, ...hashPw(password) });
+  writeFileSync(USERS_PATH(), JSON.stringify(users, null, 2));
+}
+export function localUserCount(): number { return loadLocalUsers().length; }
+
+// Persisted secret so local session tokens survive restarts.
+let _localSecret: string | null = null;
+function localSecret(): string {
+  if (_localSecret) return _localSecret;
+  const p = dataPath('.local-auth-secret');
+  try {
+    if (existsSync(p)) return (_localSecret = readFileSync(p, 'utf8').trim());
+    _localSecret = randomBytes(32).toString('hex');
+    writeFileSync(p, _localSecret, { mode: 0o600 });
+  } catch { _localSecret = INTERNAL_SECRET; }
+  return _localSecret;
+}
+/** Issue a signed local session token: sha_<sig>.<base64url(email:exp)>. */
+export function localLogin(email: string, password: string): string | null {
+  const rec = loadLocalUsers().find((u) => u.email === email);
+  if (!rec) return null;
+  const { hash } = hashPw(password, rec.salt);
+  if (hash.length !== rec.hash.length || !timingSafeEqual(Buffer.from(hash), Buffer.from(rec.hash))) return null;
+  const exp = Math.floor(Date.now() / 1000) + 30 * 24 * 3600;
+  const payload = `${email}:${exp}`;
+  const sig = createHmac('sha256', localSecret()).update(payload).digest('hex');
+  return `sha_${sig}.${Buffer.from(payload).toString('base64url')}`;
+}
+function verifyLocalToken(token: string): AuthUser {
+  if (!token.startsWith('sha_')) throw new Error('Invalid session token');
+  const body = token.slice(4);
+  const dot = body.indexOf('.');
+  if (dot < 0) throw new Error('Malformed token');
+  const sig = body.slice(0, dot);
+  const payload = Buffer.from(body.slice(dot + 1), 'base64url').toString();
+  const expected = createHmac('sha256', localSecret()).update(payload).digest('hex');
+  if (sig.length !== expected.length || !timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) throw new Error('Bad token signature');
+  const sep = payload.lastIndexOf(':');
+  const email = payload.slice(0, sep);
+  if (Math.floor(Date.now() / 1000) > Number(payload.slice(sep + 1))) throw new Error('Token expired — sign in again');
+  return { uid: email, email, isOwner: isOwnerEmail(email) };
+}
+
+/** Dispatch bearer verification to the active provider. */
+export async function verifyBearer(token: string): Promise<AuthUser> {
+  return AUTH_PROVIDER === 'firebase' ? verifyToken(token) : verifyLocalToken(token);
+}
+
+export async function requireAuth(req: Request, res: Response, next: NextFunction) {
+  const internalToken = req.headers['x-internal-token'] as string | undefined;
+  if (internalToken) {
+    const identity = verifyInternalToken(internalToken);
+    if (identity) {
+      (req as any).user = { uid: identity.uid, email: identity.email, isOwner: isOwnerEmail(identity.email) } as AuthUser;
+      return next();
+    }
+  }
+
+  const token = req.headers.authorization?.replace('Bearer ', '') || (req.query.token as string);
+  if (!token) return void res.status(401).json({ error: 'Missing token' });
+
+  // API key auth (uck_…)
+  if (token.startsWith('uck_')) {
+    const identity = validateApiKey(token);
+    if (!identity) return void res.status(401).json({ error: 'Invalid API key' });
+    (req as any).user = { uid: identity.uid, email: identity.email, isOwner: isOwnerEmail(identity.email) } as AuthUser;
+    return next();
+  }
+
+  try {
+    (req as any).user = await verifyBearer(token);
+    next();
+  } catch (err: any) {
+    return void res.status(err?.message?.includes('whitelist') ? 403 : 401).json({ error: err.message });
+  }
+}