solrouter 0.1.0

package/src/config.js

@@ -0,0 +1,85 @@
+// config.js — load proxy config and the saved auth token.
+//
+// Precedence (low → high): built-in defaults, ~/.solrouter/config.json,
+// ./solrouter.config.json, environment variables. The auth token lives
+// separately in ~/.solrouter/auth.json (written by `login`), chmod 600.
+
+import { readFileSync, existsSync, mkdirSync, writeFileSync, chmodSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const HOME_DIR = join(homedir(), ".solrouter");
+const AUTH_PATH = join(HOME_DIR, "auth.json");
+
+const DEFAULTS = {
+  port: 8787,
+  mode: "auto",                 // auto | frontier | private — default routing mode
+  // Where each leg goes. Both are OpenAI/Anthropic-compatible base URLs.
+  frontier: {
+    baseUrl: "https://api.anthropic.com",
+    dialect: "anthropic",       // anthropic | openai
+    model: null,                // null = keep the client's requested model
+    auth: "passthrough",        // passthrough (default) = use the dev's OWN creds,
+                                // so the proxy is a drop-in for existing setups.
+                                // Set apiKey (or auth:"solrouter") to override.
+  },
+  // The uncensored leg: the SolRouter backend's /agent route (open-weight model,
+  // sk_solrouter_ key). Stateless for API-key users; prompt is pseudonymised first.
+  private: {
+    baseUrl: "https://solrouter-obb4.onrender.com",
+    transport: "solrouter-agent",
+    model: "qwen3.8:27b",
+    auth: "solrouter",
+  },
+  masking: {
+    enabled: true,
+    names: [],                  // customer gazetteer
+    guessNames: true,
+  },
+  receipt: {
+    enabled: true,
+    path: join(HOME_DIR, "receipts.jsonl"),
+  },
+  // Route each leg through the SolRouter backend (which holds provider keys and
+  // does x402 billing) instead of hitting providers directly.
+  viaSolrouter: true,
+};
+
+function readJson(path) {
+  try { return existsSync(path) ? JSON.parse(readFileSync(path, "utf8")) : {}; }
+  catch { return {}; }
+}
+
+function deepMerge(a, b) {
+  const out = { ...a };
+  for (const k of Object.keys(b || {})) {
+    out[k] = b[k] && typeof b[k] === "object" && !Array.isArray(b[k])
+      ? deepMerge(a[k] || {}, b[k]) : b[k];
+  }
+  return out;
+}
+
+export function loadConfig(cliOverrides = {}) {
+  let cfg = DEFAULTS;
+  cfg = deepMerge(cfg, readJson(join(HOME_DIR, "config.json")));
+  cfg = deepMerge(cfg, readJson(join(process.cwd(), "solrouter.config.json")));
+  if (process.env.SOLROUTER_PROXY_PORT) cfg.port = Number(process.env.SOLROUTER_PROXY_PORT);
+  // Provider keys from env if talking to providers directly.
+  cfg.frontier.apiKey ||= process.env.ANTHROPIC_API_KEY || process.env.OPENAI_API_KEY || "";
+  cfg.private.apiKey ||= process.env.SOLROUTER_API_KEY || "";
+  return deepMerge(cfg, cliOverrides);
+}
+
+// ── auth token ────────────────────────────────────────────────────────────────
+export function saveAuth(token) {
+  if (!existsSync(HOME_DIR)) mkdirSync(HOME_DIR, { recursive: true });
+  writeFileSync(AUTH_PATH, JSON.stringify(token, null, 2));
+  try { chmodSync(AUTH_PATH, 0o600); } catch {}
+}
+export function loadAuth() { return readJson(AUTH_PATH); }
+export function isLoggedIn() {
+  const a = loadAuth();
+  return !!(a.access_token && (!a.expires_at || a.expires_at > Date.now()));
+}
+
+export default { loadConfig, saveAuth, loadAuth, isLoggedIn, HOME_DIR };

package/src/demo.js

@@ -0,0 +1,71 @@
+// demo.js — a self-contained proof you can run with no API key. Spins a local mock
+// "provider" that reports back exactly what it received, runs a request with real
+// PII through the proxy, and shows: what the provider saw (surrogates) vs what you
+// get back (restored), plus the receipt. This is the "does it actually work" check.
+
+import { createServer } from "node:http";
+import { mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { handle } from "./index.js";
+
+const SAMPLE =
+  "Draft a short email to Dr. Margaret Ellison (margaret.ellison@acme.co) about " +
+  "invoice #4021 — her IBAN DE44 5001 0517 5407 3249 31 was charged on card " +
+  "4111 1111 1111 1111. Our contact there is Klaus Baumann, +49 170 1234567. " +
+  "The prod DB is at db.internal.acme.corp and the key is sk-proj-abc123def456ghi789jkl.";
+
+export async function runDemo() {
+  // Mock provider: capture what it received, echo a plausible answer that reuses
+  // the (masked) identifiers, so we can watch them get restored on the way out.
+  let providerSaw = "";
+  const upstream = createServer((req, res) => {
+    let b = ""; req.on("data", c => b += c); req.on("end", () => {
+      const body = JSON.parse(b || "{}");
+      providerSaw = (body.messages || []).map(m => m.content).join(" ");
+      res.writeHead(200, { "content-type": "application/json" });
+      res.end(JSON.stringify({ choices: [{ message: { role: "assistant",
+        content: "Drafted. I addressed the recipient by name and referenced their IBAN and card." } }] }));
+    });
+  });
+  await new Promise(r => upstream.listen(0, "127.0.0.1", r));
+  const up = upstream.address().port;
+
+  const dir = mkdtempSync(join(tmpdir(), "solrouter-demo-"));
+  const cfg = {
+    mode: "auto",
+    frontier: { baseUrl: `http://127.0.0.1:${up}`, dialect: "openai", model: null, auth: "passthrough" },
+    private: { baseUrl: `http://127.0.0.1:${up}`, dialect: "openai", model: "qwen", auth: "solrouter" },
+    masking: { enabled: true, guessNames: true },
+    receipt: { enabled: true, path: join(dir, "receipts.jsonl") },
+  };
+
+  const body = { model: "your-model", messages: [{ role: "user", content: SAMPLE }] };
+  const out = await handle(body, { path: "/v1/chat/completions", headers: {} }, cfg);
+
+  const real = [
+    "Margaret Ellison", "margaret.ellison@acme.co", "Klaus Baumann",
+    "+49 170 1234567", "4111 1111 1111 1111", "db.internal.acme.corp",
+    "sk-proj-abc123def456ghi789jkl", "DE44",
+  ];
+  const leaked = real.filter(v => providerSaw.includes(v));
+
+  const line = "─".repeat(72);
+  console.log("\n" + line);
+  console.log("YOU TYPED (stayed on your machine):\n");
+  console.log("  " + SAMPLE.replace(/\. /g, ".\n  "));
+  console.log("\n" + line);
+  console.log("WHAT THE PROVIDER RECEIVED (surrogates only):\n");
+  console.log("  " + providerSaw.replace(/\. /g, ".\n  "));
+  console.log("\n" + line);
+  console.log("REAL IDENTIFIERS LEAKED TO PROVIDER:  " + (leaked.length ? leaked.join(", ") : "NONE ✓"));
+  console.log(line);
+  console.log("RECEIPT (labels + hashes only, no PII — safe to keep):\n");
+  console.log("  " + readFileSync(cfg.receipt.path, "utf8").trim());
+  console.log(line + "\n");
+
+  upstream.close();
+  return leaked.length === 0;
+}
+
+export default { runDemo };

package/src/index.js

@@ -0,0 +1,122 @@
+// index.js — the orchestration core. One request in, one answer out:
+//   detect dialect → mask (local) → decide leg → call leg → (reactive) detect a
+//   refusal and retry on the private leg → restore locally → write a receipt.
+//
+// The two legs speak different backends:
+//   frontier — the dev's own provider (Anthropic/OpenAI), credentials passed
+//              through, so the proxy is a drop-in for an existing setup.
+//   private  — the SolRouter backend's /agent route (uncensored open-weight model,
+//              sk_solrouter_ key). The prompt is pseudonymised before it goes.
+//
+// Streaming note (P0): reactive refusal-retry needs the whole answer, so streaming
+// uses the proactive route decision only. The private leg has no streaming endpoint
+// yet, so a streamed request that resolves to private is answered non-streamed.
+
+import { dialect, extractText, rewriteText, extractResponseText, rewriteResponseText, buildResponse } from "./wire.js";
+import { createMasker } from "./mask.js";
+import { decideRoute, isRefusal } from "./route.js";
+import { callLeg, streamLeg, callSolrouterAgent } from "./providers.js";
+import { writeReceipt } from "./receipt.js";
+
+/** Attach a per-request intent note to the frontier leg only (never the private one). */
+function withIntent(body, kind, intent) {
+  if (!intent) return body;
+  const note = `Context for this request: ${intent}`;
+  const out = structuredClone(body);
+  if (kind === "anthropic") {
+    out.system = out.system ? `${note}\n\n${typeof out.system === "string" ? out.system : ""}` : note;
+  } else {
+    out.messages = [{ role: "system", content: note }, ...(out.messages || [])];
+  }
+  return out;
+}
+
+/** Call one leg with an already-masked body. Returns { status, json, model }. */
+async function dispatch(cfg, which, maskedBody, kind, clientHeaders, intent) {
+  if (which === "private") {
+    const prompt = extractText(maskedBody, kind);
+    const r = await callSolrouterAgent(cfg.private, prompt);
+    return { status: r.status, ok: r.ok, model: cfg.private.model,
+      json: r.ok ? buildResponse(kind, r.reply, cfg.private.model)
+                 : { error: r.error || "private_leg_error", detail: r.raw } };
+  }
+  const leg = cfg.frontier;
+  const toSend = withIntent(maskedBody, kind, intent);
+  const r = await callLeg(leg, toSend, clientHeaders);
+  return { status: r.status, ok: r.ok, json: r.json, model: leg.model, dialect: leg.dialect || kind };
+}
+
+/** Handle one non-streaming request. Returns { status, json, receipt, leg, reason, refused }. */
+export async function handle(body, ctx = {}, cfg) {
+  const kind = dialect(body, ctx.path);
+  const forced = ctx.headers?.["x-route"];
+  const intent = ctx.headers?.["x-intent"];
+  const mode = ctx.headers?.["x-mode"] || cfg.mode;
+
+  // 1. mask — local, nothing leaves unmasked
+  const masker = createMasker(cfg.masking);
+  const masked = cfg.masking?.enabled === false
+    ? body : rewriteText(body, kind, s => masker.mask(s).text);
+
+  // 2. decide leg
+  let { leg: which, reason } = decideRoute({ text: extractText(body, kind), forced, mode });
+
+  // 3. call, with reactive refusal retry: frontier refuses → private
+  let refused = false;
+  let resp = await dispatch(cfg, which, masked, kind, ctx.headers, intent);
+  if (which === "frontier" && mode === "auto" && resp.ok) {
+    const answer = extractResponseText(resp.json, resp.dialect || kind);
+    if (isRefusal(answer)) {
+      refused = true; which = "private"; reason = "reactive-refusal";
+      resp = await dispatch(cfg, "private", masked, kind, ctx.headers, intent);
+    }
+  }
+
+  // 4. restore — local
+  const respDialect = which === "private" ? kind : (resp.dialect || kind);
+  let outJson = resp.json;
+  if (cfg.masking?.enabled !== false && resp.ok && outJson) {
+    outJson = rewriteResponseText(outJson, respDialect, s => masker.unmask(s));
+  }
+
+  // 5. receipt
+  let receipt = null;
+  if (cfg.receipt?.enabled) {
+    receipt = writeReceipt(cfg.receipt.path, {
+      leg: which, reason, model: resp.model,
+      entities: masker.entities(), refused, sentToProvider: JSON.stringify(masked),
+    });
+  }
+  return { status: resp.status, json: outJson, receipt, leg: which, reason, refused };
+}
+
+/**
+ * Handle one streaming request. Returns either a live { stream, masker, … } for the
+ * frontier leg, or { prebuilt: true, json } when the leg can't stream (private).
+ * Caller pipes `stream` through masker.streamingUnmasker() and receipts on end.
+ */
+export async function handleStream(body, ctx = {}, cfg) {
+  const kind = dialect(body, ctx.path);
+  const forced = ctx.headers?.["x-route"];
+  const intent = ctx.headers?.["x-intent"];
+  const mode = ctx.headers?.["x-mode"] || cfg.mode;
+
+  const masker = createMasker(cfg.masking);
+  const masked = cfg.masking?.enabled === false
+    ? body : rewriteText(body, kind, s => masker.mask(s).text);
+  const { leg, reason } = decideRoute({ text: extractText(body, kind), forced, mode });
+
+  if (leg === "private") {
+    // No streaming endpoint on the private leg yet — answer non-streamed.
+    const out = await handle(body, ctx, cfg);
+    return { prebuilt: true, status: out.status, json: out.json, leg, reason };
+  }
+
+  const toSend = withIntent(masked, kind, intent);
+  const r = await streamLeg(cfg.frontier, toSend, ctx.headers);
+  return { status: r.status, ok: r.ok, stream: r.stream, masker, leg, reason,
+    model: cfg.frontier.model, sent: JSON.stringify(masked) };
+}
+
+export { createMasker } from "./mask.js";
+export default { handle, handleStream };

package/src/mask.js

@@ -0,0 +1,121 @@
+// mask.js — pseudonymise a request before it leaves the machine, restore the reply
+// as it comes back. Uses pseudonymise.js only to DETECT identifiers, then swaps in
+// realistic type-consistent surrogates (see surrogates.js) rather than «TOKEN»
+// placeholders, and keeps a reverse map that never leaves.
+//
+// A session masker is stateful on purpose: the same real value maps to the same
+// surrogate across every call in a conversation, so the model never sees the same
+// person under two different names.
+
+import { pseudonymise } from "./pseudonymise.js";
+import { SECRET_PATTERNS } from "./secrets.js";
+import { surrogateFor } from "./surrogates.js";
+
+/**
+ * Create a session-scoped masker. Hold one per conversation.
+ * @param opts.names     customer gazetteer (beats heuristics)
+ * @param opts.patterns  extra {label, re, check} detectors
+ */
+export function createMasker(opts = {}) {
+  const patterns = [...SECRET_PATTERNS, ...(opts.patterns || [])];
+  const fwd = new Map();    // original value -> surrogate
+  const rev = new Map();    // surrogate -> original value
+  const used = new Set();   // surrogate collision guard
+  const seen = [];          // every entity masked this session (for the receipt)
+
+  function surrogate(label, value) {
+    if (fwd.has(value)) return fwd.get(value);
+    let s = surrogateFor(label, value);
+    // Deterministic collision (two different originals → same fake): salt until unique.
+    let salt = 0;
+    while ((used.has(s) && rev.get(s) !== value)) s = surrogateFor(label, value + "#" + ++salt);
+    fwd.set(value, s); rev.set(s, value); used.add(s);
+    return s;
+  }
+
+  return {
+    /** Mask one string. Returns { text, entities }. Updates the session map. */
+    mask(text) {
+      const { entities } = pseudonymise(text, { names: opts.names, patterns });
+      // entities are resolved, non-overlapping, sorted by start — splice in order.
+      let out = "", cursor = 0;
+      const src = String(text ?? "");
+      for (const e of entities) {
+        out += src.slice(cursor, e.start) + surrogate(e.label, e.value);
+        cursor = e.end;
+        seen.push({ label: e.label });   // label only — never store the raw value here
+      }
+      out += src.slice(cursor);
+      return { text: out, entities };
+    },
+
+    /** Restore a complete string: surrogates → originals, fuzzy for mangled cases. */
+    unmask(text) {
+      return restore(String(text ?? ""), rev);
+    },
+
+    /** A stateful restorer for streamed output (holds back a boundary-safe tail). */
+    streamingUnmasker() {
+      return streamingRestorer(rev);
+    },
+
+    /** The reverse map, for a receipt or for persisting a session. Never send it out. */
+    map() { return Object.fromEntries(rev); },
+    /** How many distinct identifiers masked this session. */
+    size() { return rev.size; },
+    /** Every entity masked this session (labels only), for the receipt. */
+    entities() { return seen; },
+  };
+}
+
+// ── restore ──────────────────────────────────────────────────────────────────
+
+function escapeRe(s) { return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); }
+
+/** Exact then case-insensitive replace. Longest surrogates first so no prefix clobbers. */
+function restore(text, rev) {
+  const keys = [...rev.keys()].sort((a, b) => b.length - a.length);
+  for (const s of keys) {
+    if (text.includes(s)) { text = text.split(s).join(rev.get(s)); continue; }
+    // case-insensitive fallback — models re-case surrogates
+    const re = new RegExp(escapeRe(s), "gi");
+    if (re.test(text)) text = text.replace(re, rev.get(s));
+  }
+  return text;
+}
+
+/**
+ * Streaming restorer. A surrogate can be split across chunk boundaries, and once a
+ * chunk ships you can't recall it — so hold back a tail that might still be growing
+ * into a surrogate, and only emit text that is safe to restore.
+ */
+function streamingRestorer(rev) {
+  let buf = "";
+  const keys = [...rev.keys()];
+  // How many trailing chars of buf must be held back because they could still be
+  // the START of a surrogate that will complete in a later chunk. We hold only
+  // PROPER prefixes, so a surrogate that is already complete in buf is emitted and
+  // restored rather than stranded.
+  function holdback() {
+    let hold = 0;
+    for (const k of keys) {
+      const max = Math.min(k.length - 1, buf.length); // proper prefix only
+      for (let n = max; n > hold; n--) {
+        if (buf.slice(buf.length - n) === k.slice(0, n)) { hold = n; break; }
+      }
+    }
+    return hold;
+  }
+  return {
+    push(chunk) {
+      buf += String(chunk ?? "");
+      const hold = holdback();
+      const emitRaw = buf.slice(0, buf.length - hold);
+      buf = buf.slice(buf.length - hold);
+      return restore(emitRaw, rev);
+    },
+    flush() { const out = restore(buf, rev); buf = ""; return out; },
+  };
+}
+
+export default { createMasker };

package/src/providers.js

@@ -0,0 +1,100 @@
+// providers.js — send a (already-masked) request to one leg and get the answer.
+// Speaks both OpenAI /v1/chat/completions and Anthropic /v1/messages, streaming
+// and non-streaming. Nothing here ever sees plaintext — masking happened upstream.
+//
+// Auth resolution per leg, in order:
+//   1. leg.apiKey            — an explicit key in config/env
+//   2. pass-through          — forward the CLIENT's own credentials (leg.auth
+//      !== "solrouter"). This is what makes the proxy a drop-in: it inherits the
+//      dev's existing Claude Code / Cursor / GPT setup (API key OR subscription
+//      login) and needs no key of its own for the frontier leg.
+//   3. SolRouter account     — the saved login token (leg.auth === "solrouter",
+//      used for the private/uncensored leg the dev has no credentials for).
+
+import { loadAuth } from "./config.js";
+
+// Client auth headers worth forwarding verbatim in pass-through mode.
+const FORWARD = ["authorization", "x-api-key", "anthropic-version", "anthropic-beta", "openai-organization"];
+
+function authHeaders(leg, clientHeaders = {}) {
+  const h = { "content-type": "application/json" };
+
+  // 1. explicit key
+  if (leg.apiKey) {
+    if (leg.dialect === "anthropic") { h["x-api-key"] = leg.apiKey; h["anthropic-version"] = "2023-06-01"; }
+    else h["authorization"] = `Bearer ${leg.apiKey}`;
+    return h;
+  }
+
+  // 3. SolRouter account (private leg, or explicitly configured)
+  if (leg.auth === "solrouter") {
+    const auth = loadAuth();
+    if (auth.access_token) h["authorization"] = `Bearer ${auth.access_token}`;
+    return h;
+  }
+
+  // 2. pass-through (default): forward the client's own credentials
+  let forwarded = false;
+  for (const k of FORWARD) if (clientHeaders[k]) { h[k] = clientHeaders[k]; forwarded = true; }
+  if (!forwarded) {
+    // nothing to forward — fall back to the account token if we have one
+    const auth = loadAuth();
+    if (auth.access_token) h["authorization"] = `Bearer ${auth.access_token}`;
+  }
+  if (leg.dialect === "anthropic" && !h["anthropic-version"]) h["anthropic-version"] = "2023-06-01";
+  return h;
+}
+
+function endpoint(leg) {
+  const base = leg.baseUrl.replace(/\/$/, "");
+  return leg.dialect === "anthropic" ? `${base}/v1/messages` : `${base}/v1/chat/completions`;
+}
+
+/** Force the request body onto the leg's chosen model (or leave the client's if unset). */
+function withModel(body, leg) {
+  return leg.model ? { ...body, model: leg.model } : body;
+}
+
+/** Non-streaming call. Returns { ok, status, json }. */
+export async function callLeg(leg, body, clientHeaders) {
+  const res = await fetch(endpoint(leg), {
+    method: "POST",
+    headers: authHeaders(leg, clientHeaders),
+    body: JSON.stringify(withModel({ ...body, stream: false }, leg)),
+  });
+  let json = null;
+  try { json = await res.json(); } catch {}
+  return { ok: res.ok, status: res.status, json };
+}
+
+/**
+ * The private/uncensored leg: the SolRouter backend's /agent route. Takes a plain
+ * prompt + a sk_solrouter_ key (stateless for API-key users), returns { reply }.
+ * The prompt is already pseudonymised upstream.
+ */
+export async function callSolrouterAgent(leg, prompt) {
+  const auth = loadAuth();
+  const key = leg.apiKey || auth.access_token;
+  if (!key) return { ok: false, status: 401, reply: "", error: "no SolRouter API key — run `login --token sk_solrouter_...`" };
+  const base = leg.baseUrl.replace(/\/$/, "");
+  const res = await fetch(`${base}/agent`, {
+    method: "POST",
+    headers: { "content-type": "application/json", "authorization": `Bearer ${key}` },
+    body: JSON.stringify({ prompt, model: leg.model || "qwen3.8:27b", useTools: false }),
+  });
+  let json = null;
+  try { json = await res.json(); } catch {}
+  return { ok: res.ok && json?.success !== false, status: res.status, reply: json?.reply ?? "", raw: json };
+}
+
+/** Streaming call. Returns { ok, status, stream } (raw SSE ReadableStream). */
+export async function streamLeg(leg, body, clientHeaders) {
+  const res = await fetch(endpoint(leg), {
+    method: "POST",
+    headers: authHeaders(leg, clientHeaders),
+    body: JSON.stringify(withModel({ ...body, stream: true }, leg)),
+  });
+  return { ok: res.ok, status: res.status, stream: res.body };
+}
+
+export default { callLeg, streamLeg };

package/src/receipt.js

@@ -0,0 +1,62 @@
+// receipt.js — one hash-chained JSONL line per call. What was detected, what was
+// masked, which leg ran it, and a hash of what the provider actually received.
+// The receipt never contains raw values or the map — only labels, counts, and
+// hashes — so the audit log itself is safe to keep and to show an auditor.
+
+import { createHash } from "node:crypto";
+import { appendFileSync, readFileSync, existsSync } from "node:fs";
+
+const sha256 = s => createHash("sha256").update(String(s)).digest("hex");
+
+/** Last line's hash, so a new receipt chains onto it. */
+function lastHash(path) {
+  if (!existsSync(path)) return "GENESIS";
+  const lines = readFileSync(path, "utf8").trim().split("\n").filter(Boolean);
+  if (!lines.length) return "GENESIS";
+  try { return JSON.parse(lines.at(-1)).hash || "GENESIS"; }
+  catch { return "GENESIS"; }
+}
+
+/**
+ * Append a receipt.
+ * @param path   receipt file (JSONL)
+ * @param entry  { leg, reason, model, entities, sentToProvider, refused }
+ */
+export function writeReceipt(path, entry) {
+  const prev = lastHash(path);
+  const summary = {};
+  for (const e of entry.entities || []) summary[e.label] = (summary[e.label] || 0) + 1;
+
+  const body = {
+    ts: new Date().toISOString(),
+    leg: entry.leg,                     // frontier | private
+    reason: entry.reason,               // why it was routed there
+    model: entry.model || null,
+    detected: summary,                  // { PERSON: 2, OPENAI_KEY: 1, … } — labels only
+    masked_count: (entry.entities || []).length,
+    provider_payload_sha256: entry.sentToProvider ? sha256(entry.sentToProvider) : null,
+    refused: !!entry.refused,           // frontier refused and we rerouted
+    prev,
+  };
+  const hash = sha256(prev + JSON.stringify(body));
+  const line = JSON.stringify({ ...body, hash });
+  appendFileSync(path, line + "\n");
+  return { ...body, hash };
+}
+
+/** Walk the chain, confirm each line hashes onto the previous. */
+export function verifyChain(path) {
+  if (!existsSync(path)) return { ok: true, count: 0 };
+  const lines = readFileSync(path, "utf8").trim().split("\n").filter(Boolean);
+  let prev = "GENESIS";
+  for (let i = 0; i < lines.length; i++) {
+    const rec = JSON.parse(lines[i]);
+    const { hash, ...body } = rec;
+    if (body.prev !== prev) return { ok: false, brokenAt: i, why: "prev-mismatch" };
+    if (sha256(prev + JSON.stringify(body)) !== hash) return { ok: false, brokenAt: i, why: "hash-mismatch" };
+    prev = hash;
+  }
+  return { ok: true, count: lines.length };
+}
+
+export default { writeReceipt, verifyChain };

package/src/route.js

@@ -0,0 +1,64 @@
+// route.js — decide where a request runs.
+//
+// Two ways a request lands on the uncensored leg:
+//   1. explicit — the caller sets `x-route: private`
+//   2. auto — a frontier model would refuse it, so it goes to the uncensored leg
+//      instead of failing the user.
+//
+// "Would a frontier model refuse" has no cheap oracle. We use both signals:
+//   · proactive — a fast local guess, so obvious cases skip the frontier round-trip
+//     (and never expose the request to a provider that would reject it anyway).
+//   · reactive — if the frontier model is tried and actually refuses, retry on the
+//     uncensored leg. This is the accurate signal; the proactive guess only exists
+//     to avoid the wasted call and the logged refusal.
+//
+// The proactive guesser is deliberately crude and local. Swapping it for a small
+// classifier model in the TEE is the obvious upgrade, and the interface here
+// (string in, {private, reason} out) is what that model would implement.
+
+// Phrases a frontier model tends to refuse on. This is a routing hint, not a
+// content policy — its only job is to save a round-trip. The uncensored leg's
+// own limits are set in config, not here.
+const LIKELY_REFUSED = [
+  /\b(?:uncensored|no\s*guardrails|jailbreak|without\s+(?:any\s+)?restrictions?)\b/i,
+  /\bexplicit\s+(?:sexual|erotic|nsfw)\b/i,
+  /\b(?:graphic|extreme)\s+violence\b/i,
+];
+
+const REFUSAL_SIGNATURES = [
+  /\bI (?:can(?:'|no)?t|won'?t|am (?:not able|unable))\b.{0,60}\b(?:help|assist|comply|provide|create|generate|continue)\b/i,
+  /\bI'?m (?:sorry|afraid)\b.{0,40}\b(?:can(?:'|no)?t|won'?t|unable)\b/i,
+  /\b(?:against|violates?)\b.{0,30}\b(?:policy|policies|guidelines|content policy)\b/i,
+  /\bI (?:must|have to) (?:decline|refuse)\b/i,
+];
+
+/** Cheap local guess: would the frontier model likely refuse this? */
+export function likelyRefused(text) {
+  const s = String(text ?? "");
+  for (const re of LIKELY_REFUSED) if (re.test(s)) return true;
+  return false;
+}
+
+/** Did a model response come back as a refusal? Used for the reactive retry. */
+export function isRefusal(text) {
+  const s = String(text ?? "").trim();
+  if (!s || s.length > 1500) return false; // real refusals are short
+  for (const re of REFUSAL_SIGNATURES) if (re.test(s)) return true;
+  return false;
+}
+
+/**
+ * Decide the leg for an outgoing request.
+ * @returns {{ leg: 'frontier'|'private', reason: string }}
+ */
+export function decideRoute({ text, forced, mode = "auto" }) {
+  if (forced === "private") return { leg: "private", reason: "forced" };
+  if (forced === "frontier") return { leg: "frontier", reason: "forced" };
+  if (mode === "private") return { leg: "private", reason: "mode=private" };
+  if (mode === "frontier") return { leg: "frontier", reason: "mode=frontier" };
+  // auto
+  if (likelyRefused(text)) return { leg: "private", reason: "predicted-refusal" };
+  return { leg: "frontier", reason: "default-frontier" };
+}
+
+export default { decideRoute, likelyRefused, isRefusal };