@gafj/gafj 0.1.1

package/http/api.js

@@ -0,0 +1,260 @@
+"use strict";
+
+/**
+ * The JSON API (plan section L), UI only, behind the guard. Every handler
+ * is (ctx, params, body, query) and returns a value or throws an error with
+ * a status. Transition errors are 409 with the allowed set. The run id of
+ * an ingest comes from the path; generated JSON never names it.
+ */
+
+const path = require("path");
+const { snapshot } = require("../store/snapshot");
+const reads = require("../store/reads");
+const T = require("../store/transitions");
+const { openRun } = require("../store/packets");
+const { ingestDocument } = require("../store/ingest");
+const { saveReply } = require("../store/reply");
+const { renderDocument } = require("../store/render");
+const { renderPasteText } = require("../bridge/paste");
+const { storePosting } = require("../store/proposals");
+const { proposeFromScan, freezeScoring } = require("../store/scoring");
+const { PacketError } = require("../core/generators/packet");
+const { SliceError } = require("../core/generators/slice");
+const { listReview, mutate } = require("../store/review");
+
+const ACTOR = (ref) => ({ type: "ui", ref });
+const bad = (msg, status = 400) => Object.assign(new Error(msg), { status });
+
+function need(body, key) {
+  if (body[key] === undefined || body[key] === null || body[key] === "") throw bad(`${key} is required`);
+  return body[key];
+}
+
+const routes = [];
+const route = (method, pattern, handler) => routes.push({ method, re: new RegExp("^" + pattern.replace(/:(\w+)/g, "(?<$1>[^/]+)") + "$"), handler });
+
+route("GET", "/api/snapshot", (c) => snapshot(c.db, { candidate_id: c.candidate_id, now: c.now(), thresholds: c.thresholds }));
+route("GET", "/api/me", (c) => ({ candidate_id: c.candidate_id, name: c.db.prepare("SELECT name FROM candidate WHERE id = ?").get(c.candidate_id).name, route: c.route, version: c.version, home: c.home }));
+
+route("GET", "/api/applications", (c) => reads.listApplications(c.db, c.candidate_id));
+route("GET", "/api/applications/:id", (c, p) => reads.applicationDetail(c.db, p.id) || (() => { throw bad("unknown application", 404); })());
+route("POST", "/api/applications", (c, p, b) => T.logApplication(c.db, { posting_id: need(b, "posting_id"), status: b.status, now: c.now(), actor: ACTOR("log_application") }));
+route("POST", "/api/applications/:id/status", (c, p, b) => T.updateStatus(c.db, { application_id: p.id, status: need(b, "status"), resume_doc_id: b.resume_doc_id, cover_doc_id: b.cover_doc_id, now: c.now(), actor: ACTOR("update_status") }));
+route("POST", "/api/applications/:id/correct", (c, p, b) => T.correctStatus(c.db, { application_id: p.id, status: need(b, "status"), reason: need(b, "reason"), now: c.now(), actor: ACTOR("correct_status") }));
+route("POST", "/api/applications/:id/decision-expected", (c, p, b) => T.setDecisionExpected(c.db, { application_id: p.id, at: b.at, now: c.now(), actor: ACTOR("decision_expected") }));
+route("POST", "/api/applications/:id/notes", (c, p, b) => T.setNotes(c.db, { application_id: p.id, notes: b.notes, now: c.now(), actor: ACTOR("notes") }));
+route("POST", "/api/applications/:id/people", (c, p, b) => T.attachPersonToApplication(c.db, { application_id: p.id, person: b.person || b, role: b.role, now: c.now(), actor: ACTOR("person_attach") }));
+
+route("GET", "/api/interviews/:id", (c, p) => reads.interviewDetail(c.db, p.id) || (() => { throw bad("unknown interview", 404); })());
+route("POST", "/api/interviews", (c, p, b) => T.scheduleInterview(c.db, { application_id: need(b, "application_id"), round_label: need(b, "round_label"), scheduled_at: need(b, "scheduled_at"), tz: need(b, "tz"), format: need(b, "format"), invite_received_at: b.invite_received_at, people: b.people || [], now: c.now(), actor: ACTOR("schedule_interview") }));
+route("POST", "/api/interviews/:id/reschedule", (c, p, b) => T.rescheduleInterview(c.db, { interview_id: p.id, scheduled_at: need(b, "scheduled_at"), tz: b.tz, format: b.format, now: c.now(), actor: ACTOR("reschedule") }));
+route("POST", "/api/interviews/:id/complete", (c, p, b) => T.completeInterview(c.db, { interview_id: p.id, completed_at: b.completed_at, outcome: b.outcome, now: c.now(), actor: ACTOR("mark_completed") }));
+route("POST", "/api/interviews/:id/outcome", (c, p, b) => T.setOutcome(c.db, { interview_id: p.id, outcome: need(b, "outcome"), now: c.now(), actor: ACTOR("outcome") }));
+route("POST", "/api/interviews/:id/cancel", (c, p) => T.cancelInterview(c.db, { interview_id: p.id, now: c.now(), actor: ACTOR("cancel") }));
+route("POST", "/api/interviews/:id/invite-received", (c, p, b) => T.inviteReceived(c.db, { interview_id: p.id, at: b.at, now: c.now(), actor: ACTOR("invite_received") }));
+route("POST", "/api/interviews/:id/debrief", (c, p, b) => T.captureDebrief(c.db, { interview_id: p.id, text: need(b, "text"), now: c.now(), actor: ACTOR("capture_debrief") }));
+route("POST", "/api/interviews/:id/pins", (c, p, b) => T.pinStories(c.db, { interview_id: p.id, ids: need(b, "ids"), now: c.now(), actor: ACTOR("pin_stories") }));
+route("POST", "/api/interviews/:id/people", (c, p, b) => T.attachPersonToInterview(c.db, { interview_id: p.id, person: b.person || b, now: c.now(), actor: ACTOR("person_attach") }));
+
+route("POST", "/api/people", (c, p, b) => T.addPerson(c.db, { candidate_id: c.candidate_id, ...b, now: c.now(), actor: ACTOR("person_add") }));
+route("GET", "/api/people/:id", (c, p) => reads.person(c.db, p.id) || (() => { throw bad("unknown person", 404); })());
+route("POST", "/api/people/:id", (c, p, b) => T.updatePerson(c.db, { person_id: p.id, ...b, now: c.now(), actor: ACTOR("person_update") }));
+route("POST", "/api/people/:id/merge", (c, p, b) => T.mergePerson(c.db, { person_id: p.id, into_id: need(b, "into_id"), now: c.now(), actor: ACTOR("person_merge") }));
+
+route("GET", "/api/packets/:op", (c, p, b, q) => {
+  if (p.op === "discover") require("../store/discover").assertCanOpen(c.db, c.candidate_id);
+  const r = openRun(c.db, { op: p.op, candidate_id: c.candidate_id, source_document_id: q.get("source_document_id") || undefined, interview_id: q.get("interview_id") || undefined, posting_id: q.get("posting_id") || undefined, route: "paste", actor: ACTOR("packet"), now: c.now() });
+  return { run_id: r.run_id, packet: r.packet, paste_text: renderPasteText(r.packet, { run_id: r.run_id }) };
+});
+route("POST", "/api/runs/:run_id/ingest", (c, p, b) => {
+  const routeName = b.route === "manual" ? "manual" : "paste";
+  return saveReply(c.db, { run_id: p.run_id, content: need(b, "content"), route: routeName, actor: ACTOR("ingest"), now: c.now() });
+});
+
+// onboarding (phase 5b)
+const onboarding = require("../store/onboarding");
+route("GET", "/api/onboarding", (c) => ({ batch: onboarding.batchView(c.db, c.candidate_id), style: onboarding.proposeStyle(c.db, c.candidate_id) }));
+route("POST", "/api/onboarding/batches", (c) => onboarding.openBatch(c.db, { candidate_id: c.candidate_id, now: c.now(), actor: ACTOR("onboarding") }));
+route("POST", "/api/onboarding/batches/:id/status", (c, p, b) => onboarding.setBatchStatus(c.db, { candidate_id: c.candidate_id, batch_id: p.id, status: need(b, "status"), now: c.now(), actor: ACTOR("onboarding") }));
+route("POST", "/api/sources", async (c, p, b) => {
+  const batch = b.batch_id || onboarding.openBatch(c.db, { candidate_id: c.candidate_id, now: c.now(), actor: ACTOR("onboarding") }).batch_id;
+  const buffer = Buffer.from(need(b, "data_base64"), "base64");
+  return onboarding.addSource(c.db, { candidate_id: c.candidate_id, batch_id: batch, filename: need(b, "filename"), buffer, now: c.now(), actor: ACTOR("upload") });
+});
+route("GET", "/api/sources/:id", (c, p) => { const s = onboarding.sourceText(c.db, p.id); if (s.candidate_id !== c.candidate_id) throw bad("unknown source document", 404); return { source_document_id: s.id, filename: s.filename, kind: s.kind, extractor: s.extractor, extractor_version: s.extractor_version, text: s.text }; });
+route("POST", "/api/onboarding/batches/:id/dedup", (c, p) => onboarding.suggestDedup(c.db, { candidate_id: c.candidate_id, batch_id: p.id, now: c.now(), actor: ACTOR("dedup") }));
+route("POST", "/api/kb/groups/:id/merge", (c, p, b) => onboarding.mergeGroup(c.db, { candidate_id: c.candidate_id, dedup_group_id: p.id, keep_id: b.keep_id, now: c.now(), actor: ACTOR("merge") }));
+route("POST", "/api/kb/groups/:id/keep", (c, p) => onboarding.keepSeparate(c.db, { candidate_id: c.candidate_id, dedup_group_id: p.id, now: c.now(), actor: ACTOR("keep_separate") }));
+route("GET", "/api/runs/:run_id", (c, p) => {
+  const r = c.db.prepare("SELECT id AS run_id, operation, route, interview_id, posting_id, final_result, started_at, finished_at FROM ai_run WHERE id = ? AND candidate_id = ?").get(p.run_id, c.candidate_id);
+  if (!r) throw bad("unknown run", 404);
+  r.attempts = c.db.prepare("SELECT attempt_no, result, error_code, started_at FROM ai_attempt WHERE ai_run_id = ? ORDER BY attempt_no").all(r.run_id);
+  return r;
+});
+route("GET", "/api/documents/:id", (c, p) => {
+  const d = reads.documentDetail(c.db, p.id);
+  if (!d || d.candidate_id !== c.candidate_id) throw bad("unknown document", 404);
+  return d;
+});
+/** Repair: a new run for the same op and target, then ingest as manual. */
+route("POST", "/api/documents/:id/repair", (c, p, b) => {
+  const d = reads.documentDetail(c.db, p.id);
+  if (!d || d.candidate_id !== c.candidate_id) throw bad("unknown document", 404);
+  const op = d.run ? d.run.operation : d.kind === "email" ? "followup" : d.kind;
+  const r = openRun(c.db, { op, interview_id: d.interview_id || (d.kind === "email" && d.run ? d.run.interview_id : undefined) || undefined, posting_id: d.posting_id || undefined, route: "manual", actor: ACTOR("repair"), now: c.now() });
+  return ingestDocument(c.db, { run_id: r.run_id, content: need(b, "content"), route: "manual", actor: ACTOR("repair"), now: c.now() });
+});
+route("POST", "/api/documents/:id/export", (c, p, b) => {
+  const r = renderDocument(c.db, { document_id: p.id, outDir: path.join(c.exportDir, "documents"), homeDir: c.home, now: c.now(), actor: ACTOR("export") });
+  return { rel_path: r.rel, file: r.file };
+});
+
+route("POST", "/api/communications", (c, p, b) => T.markSent(c.db, { application_id: need(b, "application_id"), interview_id: b.interview_id, kind: need(b, "kind"), document_id: b.document_id, to_addr: b.to_addr, sent_body_text: b.sent_body_text, sent_at: b.sent_at, now: c.now(), actor: ACTOR("mark_sent") }));
+
+route("GET", "/api/accomplishments", (c, p, b, q) => reads.searchAccomplishments(c.db, c.candidate_id, q.get("q") || "", Number(q.get("limit") || 20)));
+route("GET", "/api/kb/review", (c) => listReview(c.db, c.candidate_id, {}));
+route("POST", "/api/kb/:id/review", (c, p, b) => mutate(c.db, { candidate_id: c.candidate_id, record: p.id, dimension: need(b, "dimension"), value: need(b, "value"), action: b.action || "confirm", edits: b.edits || {}, now: c.now(), actor: ACTOR("review") }));
+
+// postings: UI paste inserts accepted; accept promotes a proposed row
+route("GET", "/api/postings", (c) => c.db.prepare(`SELECT p.id AS posting_id, p.status, p.company, p.title, p.location, p.comp_text, p.captured_at, p.taken_down_at,
+    (SELECT count(*) FROM scoring s WHERE s.posting_id = p.id AND s.status = 'frozen') > 0 AS scoring_frozen, a.id AS application_id FROM posting p LEFT JOIN application a ON a.posting_id = p.id
+    WHERE p.candidate_id = ? ORDER BY p.captured_at DESC`).all(c.candidate_id).map((r) => ({ ...r, scoring_frozen: !!r.scoring_frozen })));
+route("GET", "/api/postings/:id", (c, p) => {
+  const r = c.db.prepare("SELECT id AS posting_id, status, company, title, location, comp_text, source_url, captured_at, taken_down_at, raw_text FROM posting WHERE id = ? AND candidate_id = ?").get(p.id, c.candidate_id);
+  if (!r) throw bad("unknown posting", 404);
+  r.scoring = c.db.prepare("SELECT id AS scoring_id, status, fit_score, verdict, verdict_reason, categories_json, scored_at FROM scoring WHERE posting_id = ? ORDER BY scored_at DESC, rowid DESC").all(r.posting_id)
+    .map((s) => ({ ...s, categories: JSON.parse(s.categories_json), categories_json: undefined }));
+  r.gaps = c.db.prepare("SELECT id AS gap_id, requirement_text, question, created_at, resolved_at FROM kb_gap WHERE posting_id = ?").all(r.posting_id);
+  return r;
+});
+route("POST", "/api/postings", (c, p, b) => {
+  const r = storePosting(c.db, { candidate_id: c.candidate_id, company: need(b, "company"), title: need(b, "title"), raw_text: need(b, "raw_text"), source_url: b.source_url, comp_text: b.comp_text, location: b.location, now: c.now(), actor: ACTOR("paste_posting") });
+  if (r.created || r.status === "proposed") T.acceptPosting(c.db, { posting_id: r.posting_id, now: c.now(), actor: ACTOR("paste_posting") });
+  return { posting_id: r.posting_id, status: "accepted", created: r.created };
+});
+route("POST", "/api/postings/:id/accept", (c, p) => T.acceptPosting(c.db, { posting_id: p.id, now: c.now(), actor: ACTOR("accept_posting") }));
+route("POST", "/api/postings/:id/archive", (c, p) => T.archivePosting(c.db, { posting_id: p.id, now: c.now(), actor: ACTOR("archive_posting") }));
+route("POST", "/api/postings/:id/taken-down", (c, p) => T.postingTakenDown(c.db, { posting_id: p.id, now: c.now(), actor: ACTOR("taken_down") }));
+route("POST", "/api/postings/:id/scan", (c, p) => proposeFromScan(c.db, { posting_id: p.id, now: c.now(), actor: ACTOR("scan") }));
+route("POST", "/api/postings/:id/freeze", (c, p, b) => freezeScoring(c.db, { posting_id: p.id, categories: b.categories, scores: b.scores, now: c.now(), actor: ACTOR("freeze_categories"), thresholds: c.thresholds }));
+
+// knowledge base (screen 5)
+const kb = require("../store/kb");
+route("GET", "/api/kb", (c) => ({ ...kb.summary(c.db, c.candidate_id), gaps: kb.listGaps(c.db, c.candidate_id), holes: kb.listHoles(c.db, c.candidate_id), questions: require("../store/discover").listQuestions(c.db, c.candidate_id), pending: kb.listPending(c.db, c.candidate_id), review: listReview(c.db, c.candidate_id, {}) }));
+route("POST", "/api/kb/gaps/:id/answer", (c, p, b) => kb.answerGap(c.db, { candidate_id: c.candidate_id, gap_id: p.id, draft: need(b, "draft"), now: c.now(), actor: ACTOR("answer_gap") }));
+route("POST", "/api/kb/pending", (c, p, b) => kb.proposeManual(c.db, { candidate_id: c.candidate_id, draft: need(b, "draft"), now: c.now(), actor: ACTOR("propose_manual") }));
+route("POST", "/api/kb/pending/:id/confirm", (c, p, b) => kb.confirmPending(c.db, { candidate_id: c.candidate_id, pending_id: p.id, edits: b.edits || {}, now: c.now(), actor: ACTOR("confirm_accomplishment") }));
+route("POST", "/api/kb/pending/:id/dismiss", (c, p) => kb.dismissPending(c.db, { candidate_id: c.candidate_id, pending_id: p.id, now: c.now(), actor: ACTOR("dismiss_pending") }));
+// discovery (the shakedown): the AI's questions, answered here in the candidate's words
+const discover = require("../store/discover");
+route("GET", "/api/kb/questions", (c, p, b, q) => discover.listQuestions(c.db, c.candidate_id, { all: q.get("all") === "1" }));
+route("POST", "/api/kb/questions/:id/answer", (c, p, b) => discover.answerQuestion(c.db, { candidate_id: c.candidate_id, question_id: p.id, draft: need(b, "draft"), now: c.now(), actor: ACTOR("answer_question") }));
+route("POST", "/api/kb/questions/:id/dismiss", (c, p) => discover.dismissQuestion(c.db, { candidate_id: c.candidate_id, question_id: p.id, now: c.now(), actor: ACTOR("dismiss_question") }));
+
+// settings (screen 6)
+const settings = require("../store/settings");
+route("GET", "/api/settings", (c) => settings.getSettings(c.db, c.home, c.candidate_id));
+route("PUT", "/api/settings", (c, p, b) => { const r = settings.putSettings(c.db, c.home, c.candidate_id, b, { now: c.now(), actor: ACTOR("settings") }); if (c.reload) c.reload(); return r; });
+route("PUT", "/api/settings/providers/:id", (c, p, b) => settings.putProvider(c.home, p.id, b));
+route("POST", "/api/settings/providers", (c, p, b) => settings.putProvider(c.home, null, b));
+route("DELETE", "/api/settings/providers/:id", (c, p) => settings.deleteProvider(c.home, p.id));
+route("POST", "/api/settings/providers/:id/test", async (c, p) => {
+  const { testProvider } = require("../bridge/byo_key");
+  const r = await testProvider(c.home, p.id, c.fetch);
+  settings.recordTest(c.home, p.id, { ok: r.ok, at: c.now(), message: r.message });
+  return r;
+});
+route("GET", "/api/mcp-config", (c) => {
+  const cli = path.resolve(__dirname, "..", "bin", "cli.js");
+  return { desktop: { mcpServers: { gafj: { command: process.execPath, args: [cli, "mcp"], env: { GAFJ_HOME: c.home } } } }, code: `claude mcp add gafj -e GAFJ_HOME=${JSON.stringify(c.home)} -- ${JSON.stringify(process.execPath)} ${JSON.stringify(cli)} mcp` };
+});
+
+route("GET", "/api/credits/balance", async (c) => {
+  const { balance } = require("../bridge/credits");
+  const r = await balance(c.home, c.fetch, c.relayAuth);
+  settings.recordBalance(c.home, { ...r, at: c.now() });
+  return r;
+});
+
+route("POST", "/api/credits/checkout", async (c, p, b) => {
+  const { checkout } = require("../bridge/credits");
+  return checkout(c.home, need(b, "pack"), c.fetch, c.relayAuth);
+});
+
+// byo_key or credits: run a packet through the active provider or the relay, then through the door (phases 6 and 7)
+route("POST", "/api/run/:op", async (c, p, b, q) => {
+  const { readConfig } = require("../store/config");
+  const cfg = readConfig(c.home);
+  if (cfg.route !== "byo_key" && cfg.route !== "credits") throw bad("the active route is neither byo_key nor credits; set it in settings", 409);
+  const routeName = cfg.route;
+  let reply;
+  if (p.op === "discover") require("../store/discover").assertCanOpen(c.db, c.candidate_id);
+  const opened = openRun(c.db, { op: p.op, candidate_id: c.candidate_id, interview_id: q.get("interview_id") || undefined, posting_id: q.get("posting_id") || undefined, source_document_id: q.get("source_document_id") || undefined, route: routeName, actor: ACTOR("run"), now: c.now() });
+  if (routeName === "credits") {
+    const { runPacket } = require("../bridge/credits");
+    reply = await runPacket(c.home, { packet: opened.packet, fetchImpl: c.fetch, auth: c.relayAuth });
+  } else {
+    const providerId = b.provider_id || cfg.active_provider_id;
+    if (!providerId) throw bad("no active provider", 409);
+    const { runPacket } = require("../bridge/byo_key");
+    reply = await runPacket(c.home, providerId, { packet: opened.packet, fetchImpl: c.fetch });
+  }
+  const r = saveReply(c.db, { run_id: opened.run_id, content: reply.content, route: routeName, actor: ACTOR("run"), now: c.now(), provider: reply.provider, model: reply.model, tokens_in: reply.tokens_in, tokens_out: reply.tokens_out, latency_ms: reply.latency_ms });
+  return reply.credits_left === undefined ? r : { ...r, charged: reply.charged, credits_left: reply.credits_left };
+});
+
+route("POST", "/api/documents/:id/workbook", async (c, p) => {
+  const { writeWorkbook } = require("../store/practice");
+  const r = await writeWorkbook(c.db, { document_id: p.id, outDir: path.join(c.exportDir, "documents"), homeDir: c.home, now: c.now(), actor: ACTOR("workbook") });
+  return { rel_path: r.rel, file: r.file, planted: r.planted };
+});
+route("POST", "/api/restore-test", async (c) => {
+  const os = require("os");
+  const fs = require("fs");
+  const { backup, restore, backupName } = require("../store/backup");
+  const { snapshot: snap } = require("../store/snapshot");
+  const { open } = require("../store/db");
+  const file = path.join(c.exportDir, "backups", backupName(c.now()));
+  await backup(c.db, file);
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "gafj-restore-"));
+  const r = await restore(file, tmp, { now: c.now() });
+  const db2 = open(r.file);
+  try {
+    const now = c.now();
+    const a = snap(c.db, { candidate_id: c.candidate_id, now, thresholds: c.thresholds });
+    const b2 = snap(db2, { candidate_id: c.candidate_id, now, thresholds: c.thresholds });
+    return { ok: true, backup: file, restored_to: tmp, snapshot_matches: JSON.stringify(a) === JSON.stringify(b2) };
+  } finally { db2.close(); }
+});
+
+route("POST", "/api/backup", async (c) => {
+  const { readConfig } = require("../store/config");
+  const { backupDir, backupTo } = require("../store/backup_dir");
+  const r = await backupTo(c.db, backupDir(readConfig(c.home), c.exportDir), c.now());
+  settings.recordBackup(c.home, { file: r.file, at: c.now(), method: r.method, by: "click" });
+  return { file: r.file, method: r.method, pruned: r.pruned };
+});
+route("POST", "/api/export-tracker", async (c) => {
+  const { exportTracker } = require("../store/export_xlsx");
+  const r = await exportTracker(c.db, { candidate_id: c.candidate_id, outDir: c.exportDir, now: c.now() });
+  return { file: r.file, rows: r.rows };
+});
+
+function match(method, pathname) {
+  for (const r of routes) {
+    if (r.method !== method) continue;
+    const m = r.re.exec(pathname);
+    if (m) return { handler: r.handler, params: m.groups || {} };
+  }
+  return null;
+}
+
+function statusOf(e) {
+  if (e.status) return e.status;
+  if (e instanceof PacketError || e instanceof SliceError) return 409;
+  if (/^unknown /.test(e.message)) return 404;
+  if (/needs a |is required|must be|not accepted|expected|is not/.test(e.message)) return 400;
+  return 500;
+}
+
+module.exports = { match, routes, statusOf };

package/http/guard.js

@@ -0,0 +1,106 @@
+"use strict";
+
+/**
+ * The guard (plan section H): bind 127.0.0.1; reject any Host that is not
+ * the bound host and port; every /api request carries the session cookie,
+ * reads included; mutations also carry a matching Origin and a JSON body;
+ * bodies are capped at 1 MB. Launch nonces are single use and expire.
+ */
+
+const crypto = require("crypto");
+
+const COOKIE = "gafj_session";
+const BODY_CAP = 1024 * 1024;
+const NONCE_TTL_MS = 10 * 60 * 1000;
+
+function parseCookies(header) {
+  const out = {};
+  for (const part of String(header || "").split(";")) {
+    const i = part.indexOf("=");
+    if (i > 0) out[part.slice(0, i).trim()] = decodeURIComponent(part.slice(i + 1).trim());
+  }
+  return out;
+}
+
+function timingEqual(a, b) {
+  const x = Buffer.from(String(a || "")), y = Buffer.from(String(b || ""));
+  return x.length === y.length && x.length > 0 && crypto.timingSafeEqual(x, y);
+}
+
+class Guard {
+  constructor({ host, port, sessionToken, allowedHosts = [] }) {
+    this.host = host;
+    this.port = port;
+    this.sessionToken = sessionToken;
+    this.nonces = new Map();
+    // Extra hosts a local TLS proxy (Tailscale Serve, for the phone) presents; each is reached over https.
+    this.allowedHosts = allowedHosts.map((h) => String(h).toLowerCase().trim()).filter(Boolean);
+  }
+  get origin() { return `http://${this.host}:${this.port}`; }
+  get hostHeader() { return `${this.host}:${this.port}`; }
+  /** True when the request arrived under one of the allowed proxy hosts (https on the outside). */
+  viaProxy(req) {
+    const h = String(req.headers.host || "").toLowerCase();
+    return this.allowedHosts.includes(h) || this.allowedHosts.includes(h.replace(/:443$/, ""));
+  }
+  originFor(req) {
+    return this.viaProxy(req) ? `https://${String(req.headers.host).toLowerCase().replace(/:443$/, "")}` : this.origin;
+  }
+
+  mintNonce(now = Date.now()) {
+    for (const [k, t] of this.nonces) if (now - t > NONCE_TTL_MS) this.nonces.delete(k);
+    const n = crypto.randomBytes(24).toString("base64url");
+    this.nonces.set(n, now);
+    return n;
+  }
+  burnNonce(n, now = Date.now()) {
+    const t = this.nonces.get(n);
+    if (t === undefined) return false;
+    this.nonces.delete(n);
+    return now - t <= NONCE_TTL_MS;
+  }
+  cookieHeader(secure = false) {
+    return `${COOKIE}=${this.sessionToken}; HttpOnly; SameSite=Strict; Path=/${secure ? "; Secure" : ""}`;
+  }
+
+  /** Returns null when the request may proceed, else { status, error }. */
+  check(req, { api = false, mutation = false } = {}) {
+    if ((req.headers.host || "") !== this.hostHeader && !this.viaProxy(req)) return { status: 421, error: "wrong host" };
+    if (api) {
+      const c = parseCookies(req.headers.cookie);
+      if (!timingEqual(c[COOKIE], this.sessionToken)) return { status: 401, error: "no session; open the launch URL from gafj url" };
+    }
+    if (mutation) {
+      if ((req.headers.origin || "") !== this.originFor(req)) return { status: 403, error: "foreign origin" };
+      const ct = String(req.headers["content-type"] || "");
+      if (!/^application\/json\b/i.test(ct)) 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;
+  }
+
+  /** The CLI's way in: the session token itself, as a header, from the same OS user. */
+  checkCliToken(req) {
+    return timingEqual(req.headers["x-gafj-token"], this.sessionToken);
+  }
+}
+
+function readJson(req, cap = BODY_CAP) {
+  return new Promise((resolve, reject) => {
+    let size = 0;
+    const chunks = [];
+    req.on("data", (c) => {
+      size += c.length;
+      if (size > cap) { reject(Object.assign(new Error("body larger than 1 MB"), { status: 413 })); req.destroy(); return; }
+      chunks.push(c);
+    });
+    req.on("end", () => {
+      const text = Buffer.concat(chunks).toString("utf8");
+      if (!text.trim()) return resolve({});
+      try { resolve(JSON.parse(text)); } catch (e) { reject(Object.assign(new Error("invalid JSON body"), { status: 400 })); }
+    });
+    req.on("error", reject);
+  });
+}
+
+module.exports = { Guard, readJson, parseCookies, COOKIE, BODY_CAP };

package/http/headers.js

@@ -0,0 +1,17 @@
+"use strict";
+
+/** Security headers on every response (plan section H). No remote scripts, no framing, no caching of API or launch. */
+const CSP = "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self'; font-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'self'; object-src 'none'";
+
+function securityHeaders(res, { noStore = false } = {}) {
+  res.setHeader("Content-Security-Policy", CSP);
+  res.setHeader("X-Content-Type-Options", "nosniff");
+  res.setHeader("X-Frame-Options", "DENY");
+  res.setHeader("Referrer-Policy", "no-referrer");
+  res.setHeader("Permissions-Policy", "camera=(), microphone=(), geolocation=()");
+  res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
+  res.setHeader("Cross-Origin-Resource-Policy", "same-origin");
+  if (noStore) res.setHeader("Cache-Control", "no-store");
+}
+
+module.exports = { securityHeaders, CSP };