@gafj/gafj 0.1.1

package/http/hosted.js

@@ -0,0 +1,273 @@
+"use strict";
+
+/**
+ * The hosted server (plan section W): the same routes, screens, doors, and
+ * gate as the local server, behind a sign-in instead of a launch cookie,
+ * with one store per user. Tenant isolation is a property of the request:
+ * the session names a uid, the uid names a home folder, and every handler
+ * runs against that folder's database and config only. There is no query
+ * that spans tenants. A user can export their store (a restorable backup
+ * file) and delete their account (the folder is gone, sessions with it).
+ *
+ * Provider keys are never stored for hosted users; the model is reached
+ * through the relay with a service key and the uid, never a user token.
+ */
+
+const http = require("http");
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const crypto = require("crypto");
+const { readJson, parseCookies } = require("./guard");
+const { securityHeaders, CSP } = require("./headers");
+const { serveEvents } = require("./sse");
+const api = require("./api");
+const { open } = require("../store/db");
+const { migrate } = require("../store/migrate");
+const { readConfig, writeConfig } = require("../store/config");
+const { DEFAULT_THRESHOLDS } = require("../store/snapshot");
+const { ulid } = require("../core/ulid");
+const { backup, backupName } = require("../store/backup");
+const { silent } = require("../store/log");
+const { UI_DIR } = require("./server");
+
+const COOKIE = "gafj_hs";
+const SESSION_TTL_MS = 30 * 24 * 3600 * 1000;
+const IDLE_CLOSE_MS = 10 * 60 * 1000;
+const SIGNIN_CSP = "default-src 'self'; script-src 'self' https://www.gstatic.com https://apis.google.com; style-src 'self'; img-src 'self' data:; font-src 'self'; connect-src 'self' https://identitytoolkit.googleapis.com https://securetoken.googleapis.com https://www.googleapis.com https://apis.google.com; frame-src https://*.firebaseapp.com https://accounts.google.com; frame-ancestors 'none'; base-uri 'none'; form-action 'self'; object-src 'none'";
+const MIME = { ".html": "text/html; charset=utf-8", ".js": "text/javascript; charset=utf-8", ".mjs": "text/javascript; charset=utf-8", ".css": "text/css; charset=utf-8", ".json": "application/json; charset=utf-8", ".svg": "image/svg+xml", ".png": "image/png", ".webmanifest": "application/manifest+json", ".ico": "image/x-icon", ".woff2": "font/woff2" };
+const BLOCKED_IN_HOSTED = [/^\/api\/settings\/providers/, /^\/api\/mcp-config$/, /^\/api\/restore-test$/];
+
+function json(res, status, body) {
+  const text = JSON.stringify(body);
+  res.writeHead(status, { "Content-Type": "application/json; charset=utf-8", "Content-Length": Buffer.byteLength(text) });
+  res.end(text);
+}
+
+const safeUid = (uid) => (/^[A-Za-z0-9_-]{1,128}$/.test(uid) ? uid : crypto.createHash("sha256").update(String(uid)).digest("hex").slice(0, 40));
+
+/** Server-side sessions: random id to uid, persisted so a restart signs nobody out. */
+class Sessions {
+  constructor(file, now) { this.file = file; this.now = now; this.map = new Map(); this.load(); }
+  load() {
+    try { for (const [k, v] of Object.entries(JSON.parse(fs.readFileSync(this.file, "utf8")))) this.map.set(k, v); } catch (_) { /* first start */ }
+  }
+  save() {
+    try { fs.writeFileSync(this.file, JSON.stringify(Object.fromEntries(this.map)) + "\n", { mode: 0o600 }); } catch (_) { /* read-only disk: sessions live in memory */ }
+  }
+  create(who) {
+    for (const [k, v] of this.map) if (v.expires < this.now()) this.map.delete(k);
+    const id = crypto.randomBytes(32).toString("base64url");
+    this.map.set(id, { uid: who.uid, email: who.email || null, created: this.now(), expires: this.now() + SESSION_TTL_MS });
+    this.save();
+    return id;
+  }
+  get(id) {
+    if (!id) return null;
+    const s = this.map.get(id);
+    if (!s) return null;
+    if (s.expires < this.now()) { this.map.delete(id); this.save(); return null; }
+    return s;
+  }
+  drop(id) { if (this.map.delete(id)) this.save(); }
+  dropUid(uid) { let n = 0; for (const [k, v] of this.map) if (v.uid === uid) { this.map.delete(k); n++; } if (n) this.save(); return n; }
+}
+
+/** One home folder per uid; open databases cached and closed when idle. */
+class Tenants {
+  constructor(root, { now, relay }) { this.root = root; this.now = now; this.relay = relay; this.openDbs = new Map(); }
+  homeFor(uid) { return path.join(this.root, "tenants", safeUid(uid)); }
+  exists(uid) { return fs.existsSync(path.join(this.homeFor(uid), "gafj.db")); }
+  /** First sign-in creates the store, the candidate, and a config with the credits route and nothing else. */
+  ensure(who, nowIso) {
+    const home = this.homeFor(who.uid);
+    fs.mkdirSync(home, { recursive: true, mode: 0o700 });
+    const t = this.open(who.uid);
+    let cfg = readConfig(home);
+    if (!cfg.candidate_id) {
+      const id = ulid(Date.parse(nowIso));
+      const name = (who.name || (who.email ? who.email.split("@")[0] : "") || "You").slice(0, 80);
+      t.db.prepare("INSERT INTO candidate (id, name, created_at) VALUES (?, ?, ?)").run(id, name, nowIso);
+      cfg = { candidate_id: id, route: "credits", providers: [], thresholds: { ...DEFAULT_THRESHOLDS }, hosted: true, email: who.email || null };
+      writeConfig(home, cfg);
+      require("../store/onboarding").openBatch(t.db, { candidate_id: id, now: nowIso, actor: { type: "ui", ref: "signup" } });
+    }
+    return t;
+  }
+  open(uid) {
+    const hit = this.openDbs.get(uid);
+    if (hit) { hit.last = this.now(); return hit; }
+    const home = this.homeFor(uid);
+    fs.mkdirSync(home, { recursive: true, mode: 0o700 });
+    const db = open(path.join(home, "gafj.db"));
+    migrate(db);
+    const t = { uid, home, db, last: this.now() };
+    this.openDbs.set(uid, t);
+    return t;
+  }
+  close(uid) { const t = this.openDbs.get(uid); if (t) { try { t.db.close(); } catch (_) { /* closed */ } this.openDbs.delete(uid); } }
+  closeIdle() { for (const [uid, t] of this.openDbs) if (this.now() - t.last > IDLE_CLOSE_MS) this.close(uid); }
+  closeAll() { for (const uid of [...this.openDbs.keys()]) this.close(uid); }
+  /** The account is gone: database, exports, config, everything under the folder. */
+  destroy(uid) { this.close(uid); fs.rmSync(this.homeFor(uid), { recursive: true, force: true }); }
+  /** The request context the shared handlers run against: this tenant's store, config, and folders only. */
+  ctx(t, { version, fetchImpl, now }) {
+    const cfg = readConfig(t.home);
+    const ctx = { db: t.db, candidate_id: cfg.candidate_id, thresholds: cfg.thresholds || {}, route: cfg.route || "credits", exportDir: path.join(t.home, "exports"), home: t.home, version, now, fetch: fetchImpl, hosted: true, uid: t.uid };
+    ctx.reload = () => {};
+    if (this.relay && this.relay.url) ctx.relayAuth = { relay_url: this.relay.url, headers: { "x-gafj-service": this.relay.service_key, "x-gafj-uid": t.uid } };
+    return ctx;
+  }
+}
+
+/**
+ * @param {object} o { root, verifyIdToken, host?, port?, insecure?, firebase?: {apiKey, authDomain, projectId}, relay?: {url, service_key}, version, now?, log?, fetch? }
+ */
+function createHostedServer(o) {
+  const nowIso = o.now || (() => new Date().toISOString());
+  const nowMs = () => Date.parse(nowIso());
+  const log = o.log || silent();
+  const secure = !o.insecure;
+  const host = o.host ? String(o.host).toLowerCase() : null;
+  const originOf = (req) => `${secure ? "https" : "http"}://${String(req.headers.host || "").toLowerCase()}`;
+  fs.mkdirSync(o.root, { recursive: true, mode: 0o700 });
+  const sessions = new Sessions(path.join(o.root, "sessions.json"), nowMs);
+  const tenants = new Tenants(o.root, { now: nowMs, relay: o.relay });
+  const sse = new Set();
+  const cookie = (id) => `${COOKIE}=${id}; HttpOnly; SameSite=Lax; Path=/${secure ? "; Secure" : ""}`;
+  const clearCookie = () => `${COOKIE}=; HttpOnly; SameSite=Lax; Path=/; Max-Age=0${secure ? "; Secure" : ""}`;
+  const idle = setInterval(() => tenants.closeIdle(), 60 * 1000);
+  idle.unref();
+
+  function mutationCheck(req) {
+    if ((req.headers.origin || "") !== originOf(req)) return { status: 403, error: "foreign origin" };
+    if (!/^application\/json\b/i.test(String(req.headers["content-type"] || ""))) return { status: 415, error: "application/json only" };
+    if (req.headers["sec-fetch-site"] && !["same-origin", "none"].includes(req.headers["sec-fetch-site"])) return { status: 403, error: "cross-site fetch" };
+    return null;
+  }
+  const sessionOf = (req) => { const id = parseCookies(req.headers.cookie)[COOKIE]; const s = sessions.get(id); return s ? { id, ...s } : null; };
+
+  const server = http.createServer(async (req, res) => {
+    const url = new URL(req.url, `http://${req.headers.host || "localhost"}`);
+    const p = url.pathname;
+    const isApi = p.startsWith("/api/");
+    const started = Date.now();
+    let who = null;
+    res.on("finish", () => log.write(res.statusCode >= 500 ? "error" : res.statusCode >= 400 ? "warn" : "info", "request",
+      { entity: "http", entity_id: `${req.method} ${p}`, actor: who ? "user" : "anon", ms: Date.now() - started, status: res.statusCode }));
+    try {
+      if (host && String(req.headers.host || "").toLowerCase() !== host) return json(res, 421, { error: "wrong host" });
+      const mutation = req.method !== "GET" && req.method !== "HEAD";
+      securityHeaders(res, { noStore: isApi || p.startsWith("/auth/") || p.startsWith("/account/") });
+
+      if (p === "/signin" || p === "/signin/") {
+        res.setHeader("Content-Security-Policy", SIGNIN_CSP);
+        res.writeHead(200, { "Content-Type": MIME[".html"], "Cache-Control": "no-cache" });
+        return fs.createReadStream(path.join(UI_DIR, "hosted", "signin.html")).pipe(res);
+      }
+      if (p === "/signin/config.json") return json(res, 200, { firebase: o.firebase || null, signed_in: !!sessionOf(req) });
+      if (p === "/auth/session" && req.method === "POST") {
+        const g = mutationCheck(req);
+        if (g) return json(res, g.status, { error: g.error });
+        const body = await readJson(req);
+        let id;
+        try { id = await o.verifyIdToken(String(body.id_token || "")); } catch (e) { return json(res, 401, { error: e.message || "token rejected" }); }
+        if (!id || !id.uid) return json(res, 401, { error: "token rejected" });
+        if (id.email_verified === false) return json(res, 403, { error: "verify your Google email first" });
+        who = id;
+        tenants.ensure(id, nowIso());
+        const sid = sessions.create(id);
+        log.info("signin", { entity: "account", entity_id: safeUid(id.uid), actor: "user" });
+        res.setHeader("Set-Cookie", cookie(sid));
+        return json(res, 200, { ok: true, uid: id.uid, email: id.email || null });
+      }
+      if (p === "/auth/signout" && req.method === "POST") {
+        const s = sessionOf(req);
+        if (s) sessions.drop(s.id);
+        res.setHeader("Set-Cookie", clearCookie());
+        return json(res, 200, { ok: true });
+      }
+      if (p === "/auth/me") {
+        const s = sessionOf(req);
+        return json(res, s ? 200 : 401, s ? { uid: s.uid, email: s.email, hosted: true } : { error: "not signed in", hosted: true });
+      }
+
+      const s = sessionOf(req);
+      if (p === "/account/export" && req.method === "GET") {
+        if (!s) return json(res, 401, { error: "not signed in", hosted: true });
+        who = s;
+        const t = tenants.open(s.uid);
+        const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "gafj-export-"));
+        const file = path.join(tmp, backupName(nowIso()));
+        await backup(t.db, file);
+        res.writeHead(200, { "Content-Type": "application/octet-stream", "Content-Disposition": `attachment; filename="gafj-export-${backupName(nowIso()).slice(5, 18)}.db"`, "Content-Length": fs.statSync(file).size });
+        fs.createReadStream(file).on("close", () => fs.rmSync(tmp, { recursive: true, force: true })).pipe(res);
+        log.info("export", { entity: "account", entity_id: safeUid(s.uid), actor: "user" });
+        return;
+      }
+      if (p === "/account/delete" && req.method === "POST") {
+        if (!s) return json(res, 401, { error: "not signed in", hosted: true });
+        const g = mutationCheck(req);
+        if (g) return json(res, g.status, { error: g.error });
+        const body = await readJson(req);
+        if (body.confirm !== "delete") return json(res, 400, { error: 'send {"confirm":"delete"} to delete the account and everything in it' });
+        who = s;
+        for (const stop of sse) if (stop.uid === s.uid) stop();
+        tenants.destroy(s.uid);
+        sessions.dropUid(s.uid);
+        res.setHeader("Set-Cookie", clearCookie());
+        log.info("account_deleted", { entity: "account", entity_id: safeUid(s.uid), actor: "user" });
+        return json(res, 200, { deleted: true });
+      }
+
+      if (isApi) {
+        if (!s) return json(res, 401, { error: "not signed in", hosted: true });
+        who = s;
+        if (mutation) { const g = mutationCheck(req); if (g) return json(res, g.status, { error: g.error }); }
+        if (BLOCKED_IN_HOSTED.some((re) => re.test(p))) return json(res, 404, { error: "no such route" });
+        const t = tenants.open(s.uid);
+        const ctx = tenants.ctx(t, { version: o.version, fetchImpl: o.fetch, now: nowIso });
+        if (!ctx.candidate_id) return json(res, 409, { error: "account not initialized; sign in again" });
+        if (p === "/api/events" && req.method === "GET") {
+          const stop = serveEvents(t.db, req, res, { candidate_id: ctx.candidate_id, cursor: req.headers["last-event-id"] || url.searchParams.get("since") });
+          stop.uid = s.uid;
+          sse.add(stop);
+          req.on("close", () => sse.delete(stop));
+          return;
+        }
+        const m = api.match(req.method, p);
+        if (!m) return json(res, 404, { error: "no such route" });
+        const body = mutation ? await readJson(req, p === "/api/sources" ? 16 * 1024 * 1024 : undefined) : {};
+        if (p === "/api/settings" && req.method === "PUT" && body.route && body.route !== "credits" && body.route !== "paste") return json(res, 400, { error: "hosted accounts use credits or paste; provider keys are never stored here" });
+        let result = await m.handler(ctx, m.params, body, url.searchParams);
+        if (result === undefined) result = { ok: true };
+        if (p === "/api/me" || p === "/api/settings") result = { ...result, hosted: true, email: s.email || null };
+        return json(res, 200, result);
+      }
+
+      if (mutation) { res.writeHead(405); return res.end(); }
+      if ((p === "/" || p === "/index.html") && !s) { res.writeHead(302, { Location: "/signin" }); return res.end(); }
+      const rel = p === "/" || !path.extname(p) ? "index.html" : p.replace(/^\/+/, "");
+      const file = path.normalize(path.join(UI_DIR, rel));
+      if (!file.startsWith(UI_DIR) || !fs.existsSync(file) || fs.statSync(file).isDirectory()) { res.writeHead(404); return res.end("not found"); }
+      res.writeHead(200, { "Content-Type": MIME[path.extname(file)] || "application/octet-stream", "Cache-Control": "no-cache" });
+      return fs.createReadStream(file).pipe(res);
+    } catch (e) {
+      const status = api.statusOf(e);
+      if (status >= 500) process.stderr.write(`gafj serve-hosted: ${e.stack || e.message}\n`);
+      return json(res, status, { error: e.message, allowed: e.allowed, detail: e.detail });
+    }
+  });
+  server.keepAliveTimeout = 5000;
+
+  return {
+    server, sessions, tenants,
+    listen: (bind = "127.0.0.1") => new Promise((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(o.port || 0, bind, () => resolve({ host: bind, port: server.address().port, origin: `http://${bind}:${server.address().port}` }));
+    }),
+    close: () => new Promise((resolve) => { clearInterval(idle); for (const stop of sse) stop(); server.closeAllConnections?.(); server.close(() => { tenants.closeAll(); resolve(); }); }),
+  };
+}
+
+module.exports = { createHostedServer, Sessions, Tenants, COOKIE, SIGNIN_CSP, CSP, safeUid };

package/http/identity.js

@@ -0,0 +1,70 @@
+"use strict";
+
+/**
+ * Who is signing in (plan section W, gate 1). A Firebase ID token is an
+ * RS256 JWT signed by Google's securetoken keys; verifying one needs the
+ * public JWK set, the project id, and a clock. No SDK: node:crypto does
+ * the signature, this file does the claims. The JWK set is cached for the
+ * time Google's Cache-Control allows. A test signs with its own key pair
+ * and serves its own JWK set through fetchImpl.
+ */
+
+const crypto = require("crypto");
+
+const JWK_URL = "https://www.googleapis.com/service_accounts/v1/jwk/securetoken@system.gserviceaccount.com";
+const SKEW_S = 60;
+
+class IdentityError extends Error {
+  constructor(message) { super(message); this.name = "IdentityError"; this.status = 401; }
+}
+
+const b64 = (s) => Buffer.from(String(s), "base64url");
+const parseJson = (buf) => { try { return JSON.parse(buf.toString("utf8")); } catch (_) { throw new IdentityError("token is not a JWT"); } };
+
+function firebaseVerifier({ projectId, fetchImpl, now = () => Date.now(), jwkUrl = JWK_URL }) {
+  if (!projectId) throw new Error("firebaseVerifier needs a projectId");
+  const f = fetchImpl || fetch;
+  let cache = { keys: null, until: 0 };
+
+  async function keys(force) {
+    if (!force && cache.keys && now() < cache.until) return cache.keys;
+    const res = await f(jwkUrl, { redirect: "error" });
+    if (!res.ok) throw new IdentityError("could not fetch Google's signing keys");
+    const body = await res.json();
+    const m = /max-age=(\d+)/.exec(String(res.headers && typeof res.headers.get === "function" ? res.headers.get("cache-control") || "" : ""));
+    cache = { keys: new Map((body.keys || []).filter((k) => k.kid && k.kty === "RSA").map((k) => [k.kid, k])), until: now() + (m ? Number(m[1]) : 3600) * 1000 };
+    return cache.keys;
+  }
+
+  return async function verifyIdToken(token) {
+    const parts = String(token || "").split(".");
+    if (parts.length !== 3) throw new IdentityError("token is not a JWT");
+    const header = parseJson(b64(parts[0]));
+    const claims = parseJson(b64(parts[1]));
+    if (header.alg !== "RS256" || !header.kid) throw new IdentityError("unexpected token algorithm");
+    let jwk = (await keys(false)).get(header.kid);
+    if (!jwk) jwk = (await keys(true)).get(header.kid);
+    if (!jwk) throw new IdentityError("unknown signing key");
+    const key = crypto.createPublicKey({ key: jwk, format: "jwk" });
+    const ok = crypto.verify("RSA-SHA256", Buffer.from(parts[0] + "." + parts[1]), key, b64(parts[2]));
+    if (!ok) throw new IdentityError("bad signature");
+    const t = Math.floor(now() / 1000);
+    if (typeof claims.exp !== "number" || claims.exp < t - SKEW_S) throw new IdentityError("token expired");
+    if (typeof claims.iat !== "number" || claims.iat > t + SKEW_S) throw new IdentityError("token issued in the future");
+    if (claims.aud !== projectId) throw new IdentityError("token is for another project");
+    if (claims.iss !== `https://securetoken.google.com/${projectId}`) throw new IdentityError("token issuer mismatch");
+    if (!claims.sub || typeof claims.sub !== "string" || claims.sub.length > 128) throw new IdentityError("token has no subject");
+    return { uid: claims.sub, email: claims.email || null, email_verified: claims.email_verified !== false, name: claims.name || null };
+  };
+}
+
+/** Tests and dry runs: a fixed map of token to identity. */
+function staticVerifier(map) {
+  return async (token) => {
+    const who = map[token];
+    if (!who) throw new IdentityError("token rejected");
+    return { email_verified: true, ...who };
+  };
+}
+
+module.exports = { firebaseVerifier, staticVerifier, IdentityError, JWK_URL };

package/http/server.js

@@ -0,0 +1,136 @@
+"use strict";
+
+/**
+ * The local server (plan section O). 127.0.0.1 only. Static UI from ui/,
+ * JSON API behind the guard, SSE change feed, launch URL with a single-use
+ * nonce. The CLI mints a launch URL by presenting the session token as a
+ * header (same OS user, same config file). serve.lock holds pid and port.
+ * Every request writes one line to the operational log: method, path
+ * shape, status, and milliseconds, never a body. Launch nonces and query
+ * strings are not in it.
+ */
+
+const http = require("http");
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const { Guard, readJson } = require("./guard");
+const { securityHeaders } = require("./headers");
+const { serveEvents } = require("./sse");
+const api = require("./api");
+const { silent } = require("../store/log");
+
+/** The path as logged: launch nonces collapsed, nothing after the path. */
+const logPath = (p) => (p.startsWith("/launch/") ? "/launch/*" : p);
+
+const UI_DIR = path.join(__dirname, "..", "ui");
+const MIME = { ".html": "text/html; charset=utf-8", ".js": "text/javascript; charset=utf-8", ".mjs": "text/javascript; charset=utf-8", ".css": "text/css; charset=utf-8", ".json": "application/json; charset=utf-8", ".svg": "image/svg+xml", ".png": "image/png", ".webmanifest": "application/manifest+json", ".ico": "image/x-icon", ".woff2": "font/woff2" };
+
+function json(res, status, body) {
+  const text = JSON.stringify(body);
+  res.writeHead(status, { "Content-Type": "application/json; charset=utf-8", "Content-Length": Buffer.byteLength(text) });
+  res.end(text);
+}
+
+function serveStatic(res, urlPath) {
+  const rel = urlPath === "/" || !path.extname(urlPath) ? "index.html" : urlPath.replace(/^\/+/, "");
+  const file = path.normalize(path.join(UI_DIR, rel));
+  if (!file.startsWith(UI_DIR) || !fs.existsSync(file) || fs.statSync(file).isDirectory()) { res.writeHead(404); res.end("not found"); return; }
+  res.writeHead(200, { "Content-Type": MIME[path.extname(file)] || "application/octet-stream", "Cache-Control": "no-cache" });
+  fs.createReadStream(file).pipe(res);
+}
+
+/**
+ * @param {object} o { db, cfg, home, exportDir, host?, port?, now?, version, log? }
+ */
+function createServer(o) {
+  const host = o.host || "127.0.0.1";
+  const log = o.log || silent();
+  const guard = new Guard({ host, port: o.port || 0, sessionToken: o.cfg.session_token, allowedHosts: o.cfg.allowed_hosts || [] });
+  const ctx = { db: o.db, candidate_id: o.cfg.candidate_id, thresholds: o.cfg.thresholds || {}, route: o.cfg.route || "paste", exportDir: o.exportDir, home: o.home, version: o.version, now: o.now || (() => new Date().toISOString()), fetch: o.fetch };
+  ctx.reload = () => {
+    try {
+      const { readConfig } = require("../store/config");
+      const fresh = readConfig(o.home);
+      if (fresh.candidate_id) { ctx.thresholds = fresh.thresholds || {}; ctx.route = fresh.route || "paste"; ctx.exportDir = fresh.export_dir || o.exportDir; }
+    } catch (_) { /* keep the running values */ }
+  };
+  const sse = new Set();
+
+  const server = http.createServer(async (req, res) => {
+    const url = new URL(req.url, `http://${host}`);
+    const p = url.pathname;
+    const isApi = p.startsWith("/api/");
+    const started = Date.now();
+    res.on("finish", () => log.write(res.statusCode >= 500 ? "error" : res.statusCode >= 400 ? "warn" : "info", "request",
+      { entity: "http", entity_id: `${req.method} ${logPath(p)}`, actor: isApi ? "ui" : "browser", ms: Date.now() - started, status: res.statusCode }));
+    securityHeaders(res, { noStore: isApi || p.startsWith("/launch") });
+    try {
+      if (p === "/launch/new") {
+        if (guard.check(req)) return json(res, 421, { error: "wrong host" });
+        if (!guard.checkCliToken(req)) return json(res, 401, { error: "no token" });
+        const want = String(url.searchParams.get("host") || "").toLowerCase();
+        if (want && !guard.allowedHosts.includes(want)) return json(res, 400, { error: `${want} is not in allowed_hosts` });
+        return json(res, 200, { url: `${want ? "https://" + want : guard.origin}/launch/${guard.mintNonce()}` });
+      }
+      if (p.startsWith("/launch/")) {
+        const g = guard.check(req);
+        if (g) return json(res, g.status, { error: g.error });
+        if (!guard.burnNonce(p.slice(8))) { res.writeHead(403, { "Content-Type": "text/plain" }); return res.end("launch link used or expired; run gafj url"); }
+        res.writeHead(302, { "Set-Cookie": guard.cookieHeader(guard.viaProxy(req)), Location: "/" });
+        return res.end();
+      }
+      if (isApi) {
+        const mutation = req.method !== "GET" && req.method !== "HEAD";
+        const g = guard.check(req, { api: true, mutation });
+        if (g) return json(res, g.status, { error: g.error });
+        if (p === "/api/events" && req.method === "GET") {
+          const stop = serveEvents(o.db, req, res, { candidate_id: ctx.candidate_id, cursor: req.headers["last-event-id"] || url.searchParams.get("since") });
+          sse.add(stop);
+          req.on("close", () => sse.delete(stop));
+          return;
+        }
+        const m = api.match(req.method, p);
+        if (!m) return json(res, 404, { error: "no such route" });
+        const body = mutation ? await readJson(req, p === "/api/sources" ? 16 * 1024 * 1024 : undefined) : {};
+        const result = await m.handler(ctx, m.params, body, url.searchParams);
+        return json(res, 200, result === undefined ? { ok: true } : result);
+      }
+      if (req.method !== "GET" && req.method !== "HEAD") { res.writeHead(405); return res.end(); }
+      if (guard.check(req)) return json(res, 421, { error: "wrong host" });
+      return serveStatic(res, p);
+    } catch (e) {
+      const status = api.statusOf(e);
+      if (status >= 500) process.stderr.write(`gafj serve: ${e.stack || e.message}\n`);
+      return json(res, status, { error: e.message, allowed: e.allowed, detail: e.detail });
+    }
+  });
+  server.keepAliveTimeout = 5000;
+
+  return {
+    server, guard,
+    listen: () => new Promise((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(o.port || 0, host, () => { guard.port = server.address().port; resolve({ host, port: guard.port, origin: guard.origin }); });
+    }),
+    launchUrl: () => `${guard.origin}/launch/${guard.mintNonce()}`,
+    close: () => new Promise((resolve) => { for (const stop of sse) stop(); server.closeAllConnections?.(); server.close(() => resolve()); }),
+  };
+}
+
+function ensureSessionToken(cfg) {
+  if (!cfg.session_token || String(cfg.session_token).length < 32) cfg.session_token = crypto.randomBytes(32).toString("hex");
+  return cfg;
+}
+
+const LOCK = "serve.lock";
+function readLock(homeDir) {
+  try { return JSON.parse(fs.readFileSync(path.join(homeDir, LOCK), "utf8")); } catch (_) { return null; }
+}
+function pidAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; }
+}
+function writeLock(homeDir, data) { fs.writeFileSync(path.join(homeDir, LOCK), JSON.stringify(data) + "\n"); }
+function removeLock(homeDir) { try { fs.unlinkSync(path.join(homeDir, LOCK)); } catch (_) { /* gone */ } }
+
+module.exports = { createServer, ensureSessionToken, readLock, writeLock, removeLock, pidAlive, UI_DIR };

package/http/sse.js

@@ -0,0 +1,41 @@
+"use strict";
+
+/**
+ * The change feed: /api/events as Server-Sent Events. The event log is the
+ * source; each connection polls it from its cursor (Last-Event-ID) because
+ * the MCP process writes to the same file from outside this process. The
+ * client refetches on any event; the payload is a hint, not the data.
+ */
+
+const { eventsSince } = require("../store/events");
+
+const POLL_MS = 1000;
+const HEARTBEAT_MS = 15000;
+
+function serveEvents(db, req, res, { candidate_id, cursor }) {
+  res.writeHead(200, { "Content-Type": "text/event-stream; charset=utf-8", "Cache-Control": "no-store", Connection: "keep-alive", "X-Accel-Buffering": "no" });
+  res.write(": connected\n\n");
+  let last = Number(cursor || 0);
+  if (!cursor) {
+    const max = db.prepare("SELECT max(id) AS m FROM event_log").get().m;
+    last = Number(max || 0);
+    res.write(`id: ${last}\nevent: hello\ndata: {"cursor":${last}}\n\n`);
+  }
+  const tick = () => {
+    try {
+      for (const e of eventsSince(db, last, 200)) {
+        if (e.candidate_id !== candidate_id) { last = e.id; continue; }
+        last = e.id;
+        res.write(`id: ${e.id}\nevent: change\ndata: ${JSON.stringify({ entity: e.entity, entity_id: e.entity_id, event: e.event, actor: e.actor_type, at: e.at })}\n\n`);
+      }
+    } catch (err) { res.write(`event: error\ndata: ${JSON.stringify({ error: err.message })}\n\n`); }
+  };
+  const poll = setInterval(tick, POLL_MS);
+  const beat = setInterval(() => res.write(": heartbeat\n\n"), HEARTBEAT_MS);
+  const stop = () => { clearInterval(poll); clearInterval(beat); };
+  req.on("close", stop);
+  res.on("close", stop);
+  return stop;
+}
+
+module.exports = { serveEvents, POLL_MS };

package/mcp/server.js

@@ -0,0 +1,25 @@
+"use strict";
+
+/**
+ * The stdio MCP server, phase 3. One process, one store, the tiered tools.
+ * stdout is the wire: nothing else may write to it. Errors and warnings go
+ * to stderr. The store stays open for the life of the process; WAL and
+ * busy_timeout let the CLI and a UI server share it.
+ */
+
+const { McpServer } = require("@modelcontextprotocol/server");
+const { registerTools } = require("./tools");
+const pkg = require("../package.json");
+
+function createServer(deps) {
+  const server = new McpServer({ name: "gafj", version: pkg.version }, { capabilities: { tools: {} } });
+  registerTools(server, deps);
+  return server;
+}
+
+async function serve(deps) {
+  const { serveStdio } = require("@modelcontextprotocol/server/stdio");
+  return serveStdio(() => createServer(deps), { onerror: (e) => process.stderr.write(`gafj mcp: ${e.message}\n`) });
+}
+
+module.exports = { createServer, serve };