@geraldmaron/construct 1.0.0 → 1.0.2

package/lib/server/auth.mjs

@@ -0,0 +1,168 @@
+/**
+ * lib/server/auth.mjs — Dashboard authentication middleware.
+ *
+ * Token-based auth for the Construct dashboard. A single shared bearer token
+ * is stored at ~/.construct/config.env under CONSTRUCT_DASHBOARD_TOKEN. If no
+ * token is configured the dashboard runs open (localhost-only by design). The
+ * browser receives a short-lived session cookie on successful token exchange so
+ * subsequent requests don't need to re-send the Authorization header.
+ *
+ * API routes check: Authorization: Bearer <token>  OR  session cookie.
+ * The login page POSTs to /api/auth/login and receives a Set-Cookie response.
+ * GET /api/auth/status returns { configured, authenticated }.
+ */
+
+import { randomBytes, timingSafeEqual } from 'crypto';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const HOME = homedir();
+const CONFIG_ENV = join(HOME, '.construct', 'config.env');
+const SESSION_COOKIE = 'cx_session';
+const SESSION_TTL_MS = 8 * 60 * 60 * 1000; // 8 hours
+const SUPPORTED_OAUTH_PROVIDERS = new Set(['github', 'google']);
+
+// ── In-memory session store ────────────────────────────────────────────────
+// Sessions are ephemeral — cleared on server restart. Acceptable for a local
+// single-user dashboard; no persistence needed.
+const sessions = new Map(); // token → { expiresAt }
+
+function parseEnvFile(filePath) {
+  if (!existsSync(filePath)) return {};
+  const out = {};
+  for (const line of readFileSync(filePath, 'utf8').split('\n')) {
+    const m = line.trim().match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+    if (m) out[m[1]] = m[2].replace(/^["']|["']$/g, '');
+  }
+  return out;
+}
+
+// ── Token management ───────────────────────────────────────────────────────
+
+export function getDashboardToken() {
+  const env = parseEnvFile(CONFIG_ENV);
+  return env.CONSTRUCT_DASHBOARD_TOKEN || null;
+}
+
+export function setDashboardToken(token) {
+  mkdirSync(join(HOME, '.construct'), { recursive: true });
+  const env = existsSync(CONFIG_ENV) ? readFileSync(CONFIG_ENV, 'utf8') : '';
+  const lines = env.split('\n').filter(l => !l.startsWith('CONSTRUCT_DASHBOARD_TOKEN='));
+  lines.push(`CONSTRUCT_DASHBOARD_TOKEN=${token}`);
+  writeFileSync(CONFIG_ENV, lines.filter(Boolean).join('\n') + '\n', 'utf8');
+}
+
+export function generateToken() {
+  return randomBytes(32).toString('hex');
+}
+
+// ── Auth state ─────────────────────────────────────────────────────────────
+
+export function isAuthConfigured() {
+  return Boolean(getDashboardToken());
+}
+
+export function getAuthConfig(env = process.env) {
+  const rawMode = String(env.CONSTRUCT_AUTH_MODE || '').trim().toLowerCase();
+  const mode = rawMode === 'oauth' ? 'oauth' : 'token';
+  const providers = String(env.CONSTRUCT_OAUTH_PROVIDERS || '')
+    .split(',')
+    .map((value) => value.trim().toLowerCase())
+    .filter(Boolean)
+    .filter((value, index, array) => array.indexOf(value) === index)
+    .filter((value) => SUPPORTED_OAUTH_PROVIDERS.has(value));
+  const rolesEnabled = String(env.CONSTRUCT_AUTH_ROLES_ENABLED || '').trim() === '1';
+
+  return {
+    mode,
+    providers,
+    rolesEnabled,
+    sessionBackend: 'memory',
+    tokenConfigured: isAuthConfigured(),
+    oauthConfigured: providers.length > 0,
+    supportsTokenLogin: true,
+    supportsOauthLogin: providers.length > 0,
+  };
+}
+
+function safeCompare(a, b) {
+  try {
+    const ab = Buffer.from(a, 'utf8');
+    const bb = Buffer.from(b, 'utf8');
+    if (ab.length !== bb.length) {
+      // Still run the comparison to avoid timing leak
+      timingSafeEqual(ab, Buffer.alloc(ab.length));
+      return false;
+    }
+    return timingSafeEqual(ab, bb);
+  } catch {
+    return false;
+  }
+}
+
+export function validateToken(candidate) {
+  const stored = getDashboardToken();
+  if (!stored) return true; // No token configured → open
+  if (!candidate) return false;
+  return safeCompare(candidate, stored);
+}
+
+// ── Session cookie helpers ─────────────────────────────────────────────────
+
+function parseCookies(header) {
+  const out = {};
+  if (!header) return out;
+  for (const part of header.split(';')) {
+    const [k, ...rest] = part.trim().split('=');
+    if (k) out[k.trim()] = rest.join('=').trim();
+  }
+  return out;
+}
+
+export function createSession() {
+  const token = randomBytes(32).toString('hex');
+  sessions.set(token, { expiresAt: Date.now() + SESSION_TTL_MS });
+  return token;
+}
+
+export function validateSession(cookieHeader) {
+  const cookies = parseCookies(cookieHeader);
+  const token = cookies[SESSION_COOKIE];
+  if (!token) return false;
+  const session = sessions.get(token);
+  if (!session) return false;
+  if (Date.now() > session.expiresAt) { sessions.delete(token); return false; }
+  return true;
+}
+
+export function sessionCookieHeader(token) {
+  const maxAge = Math.floor(SESSION_TTL_MS / 1000);
+  return `${SESSION_COOKIE}=${token}; HttpOnly; SameSite=Strict; Max-Age=${maxAge}; Path=/`;
+}
+
+export function clearSessionCookieHeader() {
+  return `${SESSION_COOKIE}=; HttpOnly; SameSite=Strict; Max-Age=0; Path=/`;
+}
+
+// ── Middleware ─────────────────────────────────────────────────────────────
+
+/**
+ * Returns true if the request is authenticated (or auth is not configured).
+ * Checks: session cookie first, then Authorization: Bearer header.
+ */
+export function isAuthenticated(req) {
+  if (!isAuthConfigured()) return true;
+  if (validateSession(req.headers.cookie)) return true;
+  const authHeader = req.headers.authorization || '';
+  const bearer = authHeader.startsWith('Bearer ') ? authHeader.slice(7).trim() : null;
+  return validateToken(bearer);
+}
+
+/**
+ * Send a 401 JSON response.
+ */
+export function rejectUnauthorized(res) {
+  res.writeHead(401, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify({ error: 'Unauthorized', hint: 'Set Authorization: Bearer <CONSTRUCT_DASHBOARD_TOKEN>' }));
+}

package/lib/server/chat.mjs

@@ -0,0 +1,336 @@
+/**
+ * lib/server/chat.mjs — Dashboard chat endpoint handler.
+ *
+ * Handles POST /api/chat (non-streaming JSON) and GET /api/chat/stream (SSE).
+ * Shells out to the `claude --print` CLI and streams the response back as
+ * Server-Sent Events. Returns a structured fallback if the CLI is unavailable.
+ *
+ * Message history is kept per conversation ID in memory (cleared on restart).
+ * The client sends { id?, message } — omitting id starts a new conversation.
+ */
+
+import { spawn, execSync } from 'child_process';
+import { randomBytes } from 'crypto';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+
+const HOME = homedir();
+const ROOT_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+// ── Session-end optimize hook ──────────────────────────────────────────────
+// After a chat session closes, check whether enough new quality scores have
+// accumulated in the performance review to warrant running optimize.
+// Fires asynchronously — never blocks the response.
+
+let _sessionsSinceOptimize = 0;
+const OPTIMIZE_EVERY_N_SESSIONS = parseInt(process.env.CX_OPTIMIZE_INTERVAL ?? '5', 10);
+
+function maybeRunOptimize() {
+  _sessionsSinceOptimize++;
+  if (_sessionsSinceOptimize < OPTIMIZE_EVERY_N_SESSIONS) return;
+  _sessionsSinceOptimize = 0;
+
+  // Spawn optimize --list to see if any agents are below threshold
+  const script = join(ROOT_DIR, 'scripts', 'optimize.mjs');
+  if (!existsSync(script)) return;
+
+  const proc = spawn(process.execPath, [script, '--list', '--threshold=0.7'], {
+    cwd: ROOT_DIR,
+    env: { ...process.env },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  let out = '';
+  proc.stdout.on('data', d => { out += d; });
+  proc.on('close', () => {
+    // Find agents flagged below threshold and run optimize on each
+    const flagged = out.split('\n')
+      .filter(l => l.includes('← below threshold'))
+      .map(l => l.trim().split(/\s+/)[0])
+      .filter(Boolean);
+
+    for (const agent of flagged) {
+      const opt = spawn(process.execPath, [script, agent, `--threshold=0.7`], {
+        cwd: ROOT_DIR,
+        env: { ...process.env },
+        stdio: 'ignore',
+        detached: true,
+      });
+      opt.unref();
+    }
+  });
+  proc.unref();
+}
+
+// ── Conversation store ─────────────────────────────────────────────────────
+const conversations = new Map();
+const CONV_TTL_MS = 2 * 60 * 60 * 1000;
+
+function pruneConversations() {
+  const now = Date.now();
+  for (const [id, conv] of conversations) {
+    if (now - conv.lastAt > CONV_TTL_MS) conversations.delete(id);
+  }
+}
+
+export function getOrCreateConversation(id) {
+  pruneConversations();
+  if (id && conversations.has(id)) {
+    const conv = conversations.get(id);
+    conv.lastAt = Date.now();
+    return conv;
+  }
+  const newId = randomBytes(12).toString('hex');
+  const conv = { id: newId, messages: [], createdAt: Date.now(), lastAt: Date.now() };
+  conversations.set(newId, conv);
+  return conv;
+}
+
+// ── CLI detection ──────────────────────────────────────────────────────────
+
+let _cliCmd = undefined; // undefined = not yet checked, false = not found, string = found
+
+function detectCli() {
+  if (_cliCmd !== undefined) return _cliCmd;
+  for (const cmd of ['claude', 'anthropic']) {
+    try {
+      execSync(`which ${cmd}`, { stdio: 'ignore' });
+      _cliCmd = cmd;
+      return _cliCmd;
+    } catch { /* not found */ }
+  }
+  _cliCmd = false;
+  return _cliCmd;
+}
+
+// Read-only Construct MCP tools that are pre-authorized in dashboard chat.
+// Destructive tools (storage_reset, delete_ingested_artifacts, ingest_document)
+// are deliberately omitted and still require explicit approval.
+const ALLOWED_CONSTRUCT_TOOLS = [
+  'mcp__construct-mcp__provider_fetch',
+  'mcp__construct-mcp__knowledge_search',
+  'mcp__construct-mcp__memory_search',
+  'mcp__construct-mcp__memory_recent',
+  'mcp__construct-mcp__project_context',
+  'mcp__construct-mcp__session_list',
+  'mcp__construct-mcp__session_load',
+  'mcp__construct-mcp__session_search',
+  'mcp__construct-mcp__agent_health',
+  'mcp__construct-mcp__storage_status',
+  'mcp__construct-mcp__list_skills',
+  'mcp__construct-mcp__get_skill',
+  'mcp__construct-mcp__list_templates',
+  'mcp__construct-mcp__get_template',
+  'mcp__construct-mcp__list_teams',
+  'mcp__construct-mcp__get_team',
+  'mcp__construct-mcp__agent_contract',
+  'mcp__construct-mcp__orchestration_policy',
+  'mcp__construct-mcp__search_skills',
+  'mcp__construct-mcp__efficiency_snapshot',
+  'mcp__construct-mcp__session_usage',
+  'mcp__construct-mcp__list_schema_artifacts',
+  'mcp__construct-mcp__extract_document_text',
+  'mcp__construct-mcp__summarize_diff',
+  'mcp__construct-mcp__scan_file',
+  'Read', 'Glob', 'Grep',
+];
+
+function buildCliArgs() {
+  return [
+    '--print',
+    '--permission-mode', 'default',
+    '--allowedTools', ...ALLOWED_CONSTRUCT_TOOLS,
+  ];
+}
+
+// ── Prompt builder ─────────────────────────────────────────────────────────
+
+function buildPrompt(messages, newMessage, rootDir) {
+  const lines = [];
+
+  // Attach project context prefix on first message
+  if (messages.length === 0) {
+    lines.push(
+      '[System]',
+      'You are Construct, the operator-facing chat for this project. The MCP tools',
+      '`provider_fetch`, `knowledge_search`, `memory_search`, `memory_recent`,',
+      '`project_context`, and `session_*` are pre-authorized read-only lookups.',
+      'Call them directly without asking for approval. They route to the configured',
+      'GitHub/Jira/Slack/local sources via authority-guarded providers.',
+      'For "what is X" / "tell me about X" queries about a project name, repo, or',
+      'concept, your first action is `provider_fetch({ query: "<user query>" })`.',
+      '',
+    );
+    const contextFile = join(rootDir || process.cwd(), '.cx', 'context.md');
+    if (existsSync(contextFile)) {
+      try {
+        const ctx = readFileSync(contextFile, 'utf8').slice(0, 1500);
+        lines.push(`[Project context]\n${ctx}\n`);
+      } catch { /* ignore */ }
+    }
+  }
+
+  // Include last 6 turns of history
+  for (const m of messages.slice(-6)) {
+    lines.push(`${m.role === 'user' ? 'Human' : 'Assistant'}: ${m.content}`);
+  }
+  lines.push(`Human: ${newMessage}`, '', 'Assistant:');
+  return lines.join('\n');
+}
+
+// ── SSE helpers ────────────────────────────────────────────────────────────
+
+function sseWrite(res, type, text, id) {
+  res.write(`data: ${JSON.stringify({ type, text, id })}\n\n`);
+}
+
+function cliMissingResponse(res, conv) {
+  sseWrite(res, 'chunk',
+    '**Construct chat** requires the `claude` CLI.\n\n' +
+    'Install: `npm install -g @anthropic-ai/claude-code`\n\n' +
+    'Then authenticate once with `claude` before using the dashboard chat.',
+    conv.id);
+  sseWrite(res, 'done', '', conv.id);
+  conv.messages.push({ role: 'assistant', content: '[claude CLI not available]' });
+  res.end();
+}
+
+// ── Handlers ───────────────────────────────────────────────────────────────
+
+/**
+ * GET /api/chat/stream?message=<text>[&id=<convId>]
+ * Streams response as SSE: data: { type, text, id }
+ *   type = 'chunk' | 'done' | 'error'
+ */
+export function handleChatStream(req, res, { rootDir } = {}) {
+  const url = new URL(req.url, 'http://localhost');
+  const message = url.searchParams.get('message');
+  const convId = url.searchParams.get('id') || undefined;
+
+  if (!message) {
+    res.writeHead(400, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'message query param required' }));
+    return;
+  }
+
+  res.writeHead(200, {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache',
+    'Connection': 'keep-alive',
+  });
+
+  const conv = getOrCreateConversation(convId);
+  conv.messages.push({ role: 'user', content: message });
+
+  const cli = detectCli();
+  if (!cli) { cliMissingResponse(res, conv); return; }
+
+  const prompt = buildPrompt(conv.messages.slice(0, -1), message, rootDir);
+  const proc = spawn(cli, buildCliArgs(), {
+    cwd: rootDir || process.cwd(),
+    env: { ...process.env },
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+
+  proc.stdin.write(prompt);
+  proc.stdin.end();
+
+  let fullResponse = '';
+
+  proc.stdout.on('data', chunk => {
+    const text = chunk.toString();
+    fullResponse += text;
+    sseWrite(res, 'chunk', text, conv.id);
+  });
+
+  proc.on('close', code => {
+    if (code !== 0 && !fullResponse) {
+      sseWrite(res, 'error', `Chat exited with code ${code}. Check that \`claude\` is authenticated.`, conv.id);
+    } else {
+      sseWrite(res, 'done', '', conv.id);
+    }
+    conv.messages.push({ role: 'assistant', content: fullResponse || '[no response]' });
+    res.end();
+    maybeRunOptimize();
+  });
+
+  proc.on('error', err => {
+    sseWrite(res, 'error', 'Failed to start chat: ' + err.message, conv.id);
+    res.end();
+  });
+
+  req.on('close', () => { try { proc.kill(); } catch { /* ignore */ } });
+}
+
+/**
+ * POST /api/chat — non-streaming, full response as JSON.
+ * Body: { id?, message }  →  { id, reply }
+ */
+export function handleChat(req, res, { rootDir } = {}) {
+  let body = '';
+  req.on('data', chunk => { body += chunk; });
+  req.on('end', () => {
+    try {
+      const data = JSON.parse(body || '{}');
+      if (!data.message) throw new Error('message required');
+
+      const conv = getOrCreateConversation(data.id);
+      conv.messages.push({ role: 'user', content: data.message });
+
+      const cli = detectCli();
+      if (!cli) {
+        const reply = 'The `claude` CLI is not installed. Run: npm install -g @anthropic-ai/claude-code';
+        conv.messages.push({ role: 'assistant', content: reply });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ id: conv.id, reply, cliMissing: true }));
+        return;
+      }
+
+      const prompt = buildPrompt(conv.messages.slice(0, -1), data.message, rootDir);
+      const proc = spawn(cli, buildCliArgs(), {
+        cwd: rootDir || process.cwd(),
+        env: { ...process.env },
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+
+      proc.stdin.write(prompt);
+      proc.stdin.end();
+
+      let reply = '';
+      proc.stdout.on('data', c => { reply += c.toString(); });
+      proc.on('close', code => {
+        const text = reply.trim() || (code !== 0 ? `[exit ${code}]` : '[empty response]');
+        conv.messages.push({ role: 'assistant', content: text });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ id: conv.id, reply: text }));
+        maybeRunOptimize();
+      });
+      proc.on('error', err => {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: err.message }));
+      });
+    } catch (err) {
+      res.writeHead(400, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: err.message }));
+    }
+  });
+}
+
+/**
+ * GET /api/chat/history?id=<convId>
+ */
+export function handleChatHistory(req, res) {
+  const url = new URL(req.url, 'http://localhost');
+  const id = url.searchParams.get('id');
+  if (!id || !conversations.has(id)) {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ id: null, messages: [] }));
+    return;
+  }
+  const conv = conversations.get(id);
+  res.writeHead(200, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify({ id: conv.id, messages: conv.messages }));
+}

package/lib/server/cors.mjs

@@ -0,0 +1,77 @@
+/**
+ * lib/server/cors.mjs — origin allowlist for the dashboard server.
+ *
+ * The default is exact-match against the dashboard's own origin (single-host
+ * self-hosted install). Operators can pass extra origins via the env var
+ * `CONSTRUCT_DASHBOARD_ORIGINS` as a comma-separated list.
+ *
+ *   CONSTRUCT_DASHBOARD_ORIGINS="https://my-laptop.tail-net.ts.net,https://construct.example.com"
+ *
+ * Wildcard origins are NOT supported. `Access-Control-Allow-Origin: *` is
+ * never set — paid deployments behind a private network or behind an ALB
+ * with a CloudFront distribution declare exactly which origins may issue
+ * requests.
+ *
+ * Exports:
+ *   - applyCors(req, res, opts)  : sets the right Access-Control-* headers
+ *                                   on a request. Returns true when the
+ *                                   request was a preflight (OPTIONS) and
+ *                                   the caller should respond with 204.
+ *   - originAllowed(req, opts)   : true/false. Useful when middleware wants
+ *                                   to enforce same-origin without setting
+ *                                   any headers (e.g. on SSE streams).
+ */
+
+const HEADER_NAME = 'access-control-allow-origin';
+
+function parseOrigins(env) {
+  const list = (env.CONSTRUCT_DASHBOARD_ORIGINS || '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+  return new Set(list);
+}
+
+function selfOrigin(req) {
+  const proto = req.headers['x-forwarded-proto'] || (req.socket?.encrypted ? 'https' : 'http');
+  const host = req.headers['x-forwarded-host'] || req.headers.host;
+  if (!host) return null;
+  return `${proto}://${host}`;
+}
+
+export function originAllowed(req, { env = process.env } = {}) {
+  const origin = req.headers.origin;
+  if (!origin) return true;
+  const allowed = parseOrigins(env);
+  allowed.add(selfOrigin(req));
+  return allowed.has(origin);
+}
+
+/**
+ * Set CORS headers on a response. Returns `true` for preflight requests
+ * that the caller should answer with 204 immediately.
+ */
+export function applyCors(req, res, { env = process.env } = {}) {
+  const origin = req.headers.origin;
+  if (origin && originAllowed(req, { env })) {
+    res.setHeader(HEADER_NAME, origin);
+    res.setHeader('Vary', 'Origin');
+    res.setHeader('Access-Control-Allow-Credentials', 'true');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
+    res.setHeader(
+      'Access-Control-Allow-Headers',
+      'Content-Type, Authorization, X-Construct-Csrf, X-Construct-Token'
+    );
+  }
+  if (req.method === 'OPTIONS') {
+    if (origin && !originAllowed(req, { env })) {
+      res.statusCode = 403;
+      res.end('origin not allowed');
+      return true;
+    }
+    res.statusCode = 204;
+    res.end();
+    return true;
+  }
+  return false;
+}

package/lib/server/csrf.mjs

@@ -0,0 +1,91 @@
+/**
+ * lib/server/csrf.mjs — double-submit CSRF protection for state-mutating routes.
+ *
+ * Every non-GET request must include a `X-Construct-Csrf` header whose value
+ * matches the `cx_csrf` cookie. The dashboard mints the cookie on first
+ * authenticated load (the cookie value is a 256-bit random hex string,
+ * SameSite=Lax, HttpOnly=false so the SPA can read it). Issuing the header
+ * proves the request originated from a page that received the cookie, which
+ * a cross-origin attacker cannot forge.
+ *
+ * Routes that legitimately accept unauthenticated requests (webhooks,
+ * /api/auth/login) opt out by passing `{ skipMethods: ['POST'] }` or by
+ * checking `csrfRequired(url)` themselves.
+ */
+
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+
+const COOKIE_NAME = 'cx_csrf';
+const HEADER_NAME = 'x-construct-csrf';
+const TOKEN_BYTES = 32;
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+
+function parseCookies(req) {
+  const out = {};
+  const header = req.headers.cookie;
+  if (!header) return out;
+  for (const part of header.split(';')) {
+    const [k, ...rest] = part.split('=');
+    if (!k) continue;
+    out[k.trim()] = rest.join('=').trim();
+  }
+  return out;
+}
+
+function bufFromHex(s) {
+  if (typeof s !== 'string' || s.length % 2 !== 0) return null;
+  try { return Buffer.from(s, 'hex'); } catch { return null; }
+}
+
+export function mintCsrfToken() {
+  return randomBytes(TOKEN_BYTES).toString('hex');
+}
+
+/**
+ * Ensure the response has the `cx_csrf` cookie. If the request already had
+ * one, leave it alone. Otherwise mint and set it.
+ *
+ * @returns {string} the token now in play
+ */
+export function ensureCsrfCookie(req, res) {
+  const existing = parseCookies(req)[COOKIE_NAME];
+  if (existing) return existing;
+  const token = mintCsrfToken();
+  const sec = req.socket?.encrypted ? '; Secure' : '';
+  res.setHeader(
+    'Set-Cookie',
+    `${COOKIE_NAME}=${token}; Path=/; SameSite=Lax; Max-Age=43200${sec}`
+  );
+  return token;
+}
+
+/**
+ * Verify the `X-Construct-Csrf` header matches the `cx_csrf` cookie. Returns
+ * true on safe methods (GET/HEAD/OPTIONS) without checking. Returns true on
+ * URLs that opt out via `skip(url)`.
+ */
+export function verifyCsrf(req, { skip } = {}) {
+  if (SAFE_METHODS.has(req.method)) return true;
+  if (typeof skip === 'function' && skip(req.url || '')) return true;
+  const headerVal = req.headers[HEADER_NAME];
+  const cookieVal = parseCookies(req)[COOKIE_NAME];
+  if (!headerVal || !cookieVal) return false;
+  if (headerVal.length !== cookieVal.length) return false;
+  const a = bufFromHex(headerVal);
+  const b = bufFromHex(cookieVal);
+  if (!a || !b || a.length !== b.length) return false;
+  try { return timingSafeEqual(a, b); } catch { return false; }
+}
+
+/**
+ * Default skip predicate — webhooks and auth/login may legitimately accept
+ * cross-origin POSTs without the CSRF dance.
+ */
+export function defaultSkip(url) {
+  if (!url) return false;
+  return (
+    url.startsWith('/api/webhooks/') ||
+    url === '/api/auth/login' ||
+    url === '/api/slack/commands'
+  );
+}