solrouter 0.1.0

package/README.md

@@ -0,0 +1,119 @@
+# solrouter
+
+A local routing proxy for your coding tools. It gives you the strongest model that
+*will* do your work, without handing that model anything it doesn't need to know
+about who the work is for.
+
+Two things happen to every request, **on your machine, before anything leaves**:
+
+1. **Pseudonymise.** Names, emails, IBANs, cards, API keys, private keys, internal
+   hostnames, case references are swapped for *realistic* stand-ins (not `[REDACTED]`
+   — that makes the model dumber). The mapping table never leaves your machine. The
+   provider does the thinking on a version of your problem with the identities
+   changed; you get the answer back with the real values restored, locally.
+2. **Route.** Most requests go to a frontier model. Work a frontier model **won't**
+   do doesn't dead-end at a refusal — it routes to an open-weight model you control.
+   Not by tricking the frontier model or disguising the request (that doesn't work
+   and gets your account banned) — by sending it, openly, to a different model.
+
+Every call leaves a **receipt**: a hash-chained record of what was masked, which
+model ran it, and a hash of exactly what the provider received. No PII in it.
+
+> **P0 (this version).** Prose masking, reactive refusal detection (send to
+> frontier, detect a refusal, retry on the private leg), fuzzy + streaming-safe
+> restore, receipts. Not yet: tool-call-argument masking, TEE-side classifier,
+> task decomposition. See `SPEC.md`.
+
+## Bring your own key — it's a drop-in, not a gateway
+
+By default the **frontier leg uses your own credentials**, passed straight through.
+The proxy inherits whatever your tool already uses — an `ANTHROPIC_API_KEY`, an
+`OPENAI_API_KEY`, or a Claude Code subscription login — and needs no key of its own.
+It's not reselling you frontier tokens; it sits in the middle, masks and routes, and
+forwards your request under your own account.
+
+A SolRouter account is only needed for the **private/uncensored leg** (the model you
+don't otherwise have access to) — so you can try masking + routing with your existing
+setup and no signup.
+
+```
+frontier leg  →  your own key / subscription   (auth: "passthrough", the default)
+private  leg  →  SolRouter uncensored model     (auth: "solrouter", needs login)
+```
+
+## Install & run
+
+```bash
+npx solrouter                # or: npm i -g solrouter
+solrouter start              # runs on http://127.0.0.1:8787 — uses your existing key
+solrouter login              # opens the browser — sign in with your subscription
+```
+
+`login` opens `solrouter.com/cli/auth`, you sign in with your SolRouter
+subscription, and a key is minted and handed back to the CLI automatically — no
+paste. (`login --token sk_solrouter_...` still works for CI / headless.) The private
+leg then calls the backend's `/agent` route (open-weight model `qwen3.8:27b`).
+
+Then point any OpenAI- or Anthropic-compatible tool at it — no code change:
+
+| Tool | Setting |
+|---|---|
+| **OpenAI SDK / most tools** | base URL → `http://127.0.0.1:8787/v1` |
+| **Anthropic SDK / Claude Code** | base URL → `http://127.0.0.1:8787` |
+| **Cursor / Cline / Continue (VS Code)** | set the custom OpenAI base URL to `http://127.0.0.1:8787/v1` |
+
+Example:
+
+```bash
+export OPENAI_BASE_URL=http://127.0.0.1:8787/v1
+# ...run your tool as usual
+```
+
+## Per-request control (headers)
+
+You keep the agency — override the router per call:
+
+| Header | Effect |
+|---|---|
+| `x-route: frontier` | force the frontier model |
+| `x-route: private` | force the open model you control |
+| `x-route: auto` (default) | frontier, falling back to the open model on a refusal |
+| `x-mode: private` | private leg for everything this request |
+| `x-intent: <text>` | attach a one-line intent note **to the frontier leg only** — for legitimately-scoped work (e.g. an authorized pentest) that a frontier model will do once it has context. Trades some privacy for the stronger model; never sent to the private leg. |
+
+## Commands
+
+```
+solrouter login [--token <key>]   verify account (browser), or paste a key
+solrouter start [--port N] [--mode auto|frontier|private]
+solrouter status                  config + login state
+solrouter verify                  check the receipt hash-chain
+solrouter logout
+```
+
+## Config
+
+Copy `config.example.json` to `~/.solrouter/config.json` or
+`./solrouter.config.json`. Set `frontier` / `private` base URLs, models, and
+your gazetteer of `names`. With `viaSolrouter: true` the legs go through the
+SolRouter backend (which holds provider keys and does x402 billing); otherwise set
+provider keys via `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `SOLROUTER_API_KEY`.
+
+## What this will not do
+
+It never reformulates, splits, or disguises a request to make a frontier model
+comply with something it would otherwise refuse. Refused work goes to a *different
+model*, openly. That's the honest and durable answer — and it's what keeps your
+account, and everyone else's on the same backend, from being banned. See `SPEC.md` §7.
+
+## Develop
+
+```bash
+node --test 'test/*.test.js'
+```
+
+## Note
+
+`src/pseudonymise.js` is vendored from `routerlabs/lib/pseudonymise.js` — keep both
+in sync until it's published as a shared package. Any dependency added to the
+masking path is a deployment blocker (it has to run inside the user's perimeter).

package/SPEC.md

@@ -0,0 +1,199 @@
+# SolRouter Proxy — architecture spec (draft for review)
+
+> Status: **proposal, awaiting Noah's approval.** No further code until this is signed off.
+> Written 2026-09-14, informed by four research passes (routing, refusal prediction,
+> reversible PII masking, task decomposition). Sources are cited inline next to the
+> decision they drive, so each claim is checkable.
+
+---
+
+## 1. What this is
+
+A routing proxy that gives a developer the strongest model that *will* do their work,
+without handing that model anything it doesn't need to know about who the work is for.
+
+Two things happen to every request, locally, before it leaves the machine:
+
+1. **Pseudonymise** — names, IDs, secrets, financial identifiers replaced with realistic
+   surrogates. The mapping never leaves.
+2. **Route** — the request goes to a frontier model, unless a frontier model would refuse
+   it, in which case it goes to an open-weight uncensored model the user controls.
+
+The result is restored locally and written to a hash-chained receipt.
+
+## 2. Goals and non-goals
+
+**Goals**
+- **User agency.** The user decides where each request runs; the proxy never blocks. If the
+  frontier won't do it, the open leg will.
+- **Privacy without losing capability.** The strong model does the hard thinking but never
+  learns identities. Privacy and quality stop being a tradeoff.
+- **Run-anywhere.** Masking is zero-dependency and runs on the user's machine. The routing
+  brain runs in the SolRouter TEE. No plaintext reaches a third-party provider.
+- **Auditability.** One verifiable receipt per call: what was masked, where it ran, a hash of
+  what the provider actually saw.
+
+**Non-goals — explicit**
+- **Not a frontier-guardrail bypass.** The proxy never reformulates, splits, or disguises a
+  request to make a frontier model comply with something it would otherwise refuse. Refused
+  work goes to a *different model*, openly. This is the load-bearing ethical and ToS line:
+  decomposition-to-evade is how an org's API key gets banned, and it is out of scope. See §7.
+- Not a hosted gateway that sees plaintext (breaks the privacy claim; rejected in review).
+
+## 3. The three reasons to route — and which the research supports
+
+This is the most important section, because the literature treats these very differently.
+
+| Split by… | Rationale | Research verdict |
+|---|---|---|
+| **Permission** | Frontier won't do it; open leg will | **Sound.** Not a quality bet — the open model is the only option for that segment, so the quality-diversity critique below doesn't apply. |
+| **Privacy** | User doesn't want the provider to see this at all | **Sound.** User's choice; the open leg in the TEE sees only what the user permits. |
+| **Quality / cost** | A cheaper/smaller model is "good enough" here | **Handle with care.** This is where mixing models quietly loses quality. |
+
+Why "quality/cost" is dangerous: **Self-MoA** (arXiv:2502.00674) shows aggregating the single
+best model beats mixed-model ensembles (+6.6% AlpacaEval, +3.8% avg) — the *quality-diversity
+tradeoff*: adding weaker models for diversity drags average quality down. **MAST**
+(arXiv:2503.13657, 200+ traces) finds multi-agent gains "often minimal" and failures dominated
+by system design, not model weakness. **Cognition** ("Don't Build Multi-Agents") shows parallel
+isolated segments merge incoherently.
+
+**Design consequence:** the orchestrator splits a task **only** when a segment is (a) genuinely
+independent read/breadth work, or (b) needs the permission/privacy leg. It does **not** split a
+coherent task across vendors to chase quality. Default is *one* strong model for the whole task,
+pseudonymised.
+
+## 4. Architecture — the boundary (decision: local mask + TEE router)
+
+```
+┌─ USER MACHINE (laptop / VPC) ─────────────┐   ┌─ SOLROUTER TEE ──────────┐   ┌─ PROVIDERS ─┐
+│ proxy (OpenAI/Anthropic-compatible)       │   │  router brain            │   │ Claude/GPT/  │
+│                                           │   │   · refusal predictor    │   │ Gemini       │
+│ request                                   │   │     (guard model)        │   │ (frontier)   │
+│   └─ 1. detect + pseudonymise ─ masked ───┼──▶│   · refusal detector     │   │              │
+│        map stays here ◀───────────────────┼───┤     (WildGuard-class)    │   │ Qwen         │
+│                                           │   │   · decompose (if any)   │◀──┼─ uncensored  │
+│   ┌─ restored answer ◀── masked answer ───┼───┤  routes each segment:    │──▶│ (open-weight,│
+│   ▼  (fuzzy restore, streaming-safe)      │   │   frontier | private     │   │  Nosana/TEE) │
+│ 2. receipt (hash-chained, → Solana attest)│   │  reactive retry on       │   │              │
+└───────────────────────────────────────────┘   │  detected refusal        │   └──────────────┘
+                                                 └──────────────────────────┘
+```
+
+- **Plaintext never leaves the user machine.** Only surrogate text crosses any boundary.
+- **Masking is local** (zero-dependency, ships into the perimeter). The **routing brain is in
+  the TEE**, so a larger classifier can decide than a laptop could run, and the frontier
+  provider is reached from the TEE, never given plaintext.
+- Masked text is safe to send to the TEE router *and* to providers — masking removes identity,
+  not the content the router needs to judge refusal.
+
+## 5. Components
+
+### 5.1 Masker (local, zero-dependency)
+- Base: current `pseudonymise.js` (IBAN mod-97, Luhn, EN/DE detectors) + `secrets.js`
+  (API keys, JWTs, PEM, connection strings, internal hosts).
+- **CHANGE from current code — realistic surrogates, not `«PERSON_1»` tokens.** Surrogate
+  substitution beats placeholders by **+13.26 BERTScore** at equal privacy (SurrogateShield,
+  arXiv:2606.29567); Anonymous-by-Construction (arXiv:2603.17217) reaches 0.95 Q&A accuracy vs
+  0.82 for redaction. Generate type-consistent fake values (name→name, IBAN→valid-format IBAN),
+  preserving format/gender/number. Reference implementation to study: LangChain
+  `PresidioReversibleAnonymizer` (Faker operators + instance mapping).
+- **Deterministic, consistent mapping** — same original → same surrogate for the session, or the
+  model contradicts itself. Map is instance-level, local, short-TTL.
+- **Structural masking of tool-call JSON and code**, not regex-over-blob — this is the biggest
+  silent leak in real redactors (dev.to/crp4222 tool-call-args writeup; truefoundry gateway
+  analysis). Mask: system prompt, all message text, tool_call arguments, tool results, tool
+  *definitions*.
+- **Recall gap to note:** regex+NER (Presidio-class) is ~0.56 privacy recall — misses
+  contextual identifiers ("the Leverkusen client from March"). Optionally add an LLM-in-TEE
+  detector pass for recall; document the limit either way (the masker already carries a STATED
+  LIMITS block — keep it).
+
+### 5.2 Restorer (local, streaming-safe)
+- **Fuzzy / n-gram matching, never exact replace** — models re-case, split, or paraphrase the
+  value (LangChain graded strategies: exact → case-insensitive → fuzzy → n-gram). Realistic
+  surrogates survive round-trips better than tokens.
+- **Streaming:** buffer at chunk boundaries; a surrogate can be split across chunks. Restore
+  over a reassembled boundary-safe window, not per token. (qaskills.sh streaming-redaction.)
+- Leak check: assert no residual surrogate tokens in assembled output.
+
+### 5.3 Router brain (TEE)
+- **Reactive detection is primary, prediction is an optimization.** Predicting frontier refusal
+  from the prompt is *not* a solved, off-the-shelf capability: guard models classify **harm**,
+  but frontier refusal is idiosyncratic and over-fires on **25-40% of benign prompts**
+  (arXiv:2605.05427; over-refusal benchmarks XSTest 2308.01263, OR-Bench 2405.20947). So:
+  1. **Predict (cheap, optional):** a small guard (Llama Guard 3 1B / ShieldGemma 2B) flags
+     obvious cases and skips the wasted frontier round-trip.
+  2. **Reactive (authoritative):** send masked prompt to frontier; **detect refusal** with a
+     substring pre-filter (AdvBench/GCG prefix list) + a small classifier (WildGuard-7B, the
+     only open system near GPT-4 on refusal detection, arXiv:2406.18495); on refusal, retry on
+     the open leg. Substrings alone are unreliable ("Sure, here…" then refuses) — use both.
+- **Route selection when routing by quality/cost** (not permission): binary strong/weak is
+  RouteLLM's exact problem (arXiv:2406.18665) — MF router hits 95% GPT-4 quality at 14-26%
+  frontier calls on chat traffic, and *transfers across model pairs without retraining*, so it's
+  a credible off-the-shelf start. Gains are large on mixed-difficulty traffic, thin on uniform
+  knowledge tests — measure before assuming.
+- **Explicit override always wins:** `x-route: frontier|private|auto`. Default `auto`.
+
+### 5.4 Orchestrator / decomposer (TEE) — conservative by default
+- Off unless the task needs it (§3). When on: strong-model planner emits **explicit subtask
+  contracts** (objective, output format, boundaries) — the single highest-leverage artifact per
+  Anthropic's multi-agent write-up (+90.2% on research tasks, but read/breadth only). Parallelise
+  **reads**, never shared **writes** (Cognition). Pass full traces, not just messages. End with a
+  **synthesis + verification pass** (no reconciliation trick substitutes for it — MAST).
+- Per-segment routing uses §5.3, with the permission/quality distinction from §3.
+
+### 5.5 Receipt (local + Solana)
+- One hash-chained JSONL line per call: labels + counts only (never raw values or the map), which
+  leg ran it, why, `sha256` of the provider payload, refusal flag, `prev` hash.
+- Anchor the chain head to Solana via existing `encrypted-storage` / Light Protocol attestation.
+- Safe to show an auditor: it proves what was protected and where it ran without containing PII.
+
+## 6. What to measure before claiming anything
+- **Over-refusal / prediction accuracy:** XSTest, OR-Bench, FalseReject — *not* harm benchmarks.
+  These are the prompts that silently break routing.
+- **Routing quality/cost:** RouterBench, APGR vs frontier-call fraction (RouteLLM frame).
+- **Masking utility:** BERTScore / task accuracy, masked vs unmasked, per SurrogateShield frame.
+- **Restore fidelity:** residual-token rate, fuzzy-match precision on paraphrased surrogates.
+
+## 7. What this system will not do (and why it's also good product)
+No reformulation, decomposition, or obfuscation whose purpose is to make a frontier model comply
+with what it would refuse if it saw the whole request. Reasons, in order of who they protect:
+1. **The user** — it doesn't even work: guardrails judge meaning, not the masked name in the text.
+2. **Router Labs** — provider misuse detection bans the *org key*, taking the frontier leg from
+   every customer at once. Steady refusals/evasion traffic is the signature.
+3. **The enterprise story** — a "get past refusals" feature found during due diligence sinks the
+   compliance sale that funds everything else.
+The uncensored leg is the honest answer to "the frontier won't do this": a different model,
+openly, that the user controls.
+
+## 8. PoC phases (proposed, post-approval)
+1. **P0 — local proxy, prose only:** OpenAI/Anthropic dialects, surrogate masking, reactive
+   refusal detection (substrings), fuzzy restore, receipt. Demo: Claude Code on a repo with a
+   `.env`; split screen provider-view vs user-view.
+2. **P1 — TEE router:** move detection/prediction into the TEE; add WildGuard-class classifier;
+   `x-route` + `x-intent` headers.
+3. **P2 — tool-call + streaming:** structural JSON masking, streaming-safe restore.
+4. **P3 — decomposition:** conservative orchestrator for independent/permission segments only.
+5. **P4 — SDK middleware:** fold the core into `@solrouter/sdk` as opt-in.
+
+## 8a. Resolved from the backend (2026-09-14)
+- **Private leg contract:** `POST {backend}/agent`, `Authorization: Bearer
+  sk_solrouter_...`, body `{prompt, model:"qwen3.8:27b", useTools:false}`, stateless
+  for API-key users, returns `{success, reply}`. Verified in `routes/agent.js` +
+  `middleware/apiKeyAuth.js`. There is no plaintext-messages route for the Qwen node
+  and no `/cli/verify` to build — the `sk_solrouter_` key IS the auth.
+- **Model:** `qwen3.8:27b` (uncensored); legacy `qwen3-8b`/`qwen3:8b` alias to it
+  (`routes/nosana.js` ALIASES). Priced in `routes/private-ai-api.js`.
+- **`/api/v1/chat/completions`** is OpenAI-named but requires an Arcium
+  `encryptedPrompt`, so it's not the plaintext drop-in; `/agent` is. An encrypted
+  private leg via `@solrouter/sdk` (E2E to the TEE) is the P1 upgrade.
+
+## 9. Open questions for Noah
+- Surrogate library: hand-rolled type-consistent generators (keeps zero-dependency) vs pulling a
+  Faker-class dependency into the *local* masker (a deployment-boundary cost — see the routerlabs
+  note that any dependency in the masker is a blocker). Recommendation: hand-rolled.
+- Does the open/uncensored leg run on Nosana, in the Phala TEE, or both? Affects where "private"
+  actually executes and what the receipt can attest.
+- Is P0 single-user local, or do we demo the TEE router from day one? (Answered "local mask + TEE
+  router" for architecture; question is whether P0 stubs the TEE or uses it live.)
+```

package/TESTING.md

@@ -0,0 +1,110 @@
+# Testing the proxy (no account needed)
+
+Everything below runs locally with **no SolRouter login**. The frontier leg uses
+your own key; the private/uncensored leg needs a login (endpoint not built yet — see
+bottom).
+
+Requires Node 22+. From `dev/backend/packages/router-proxy/`:
+
+## 1. Prove masking works — zero setup, no key
+
+```bash
+node bin/proxy.js demo
+```
+
+Spins a local mock provider, sends a message full of real PII through the full
+pipeline, and prints: what you typed, what the provider actually received
+(surrogates), whether anything real leaked (should say `NONE ✓`), and the receipt.
+Nothing leaves your machine.
+
+Run the unit tests too:
+
+```bash
+npm test
+```
+
+## 2. Run it against a real frontier model (your own key)
+
+The frontier leg passes your own credentials through — nothing to configure but the key.
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...        # your existing key
+node bin/proxy.js start                     # http://127.0.0.1:8787
+```
+
+Point a tool at it, or curl it directly:
+
+```bash
+curl http://127.0.0.1:8787/v1/messages \
+  -H "content-type: application/json" \
+  -H "x-api-key: $ANTHROPIC_API_KEY" \
+  -H "anthropic-version: 2023-06-01" \
+  -d '{
+    "model": "claude-opus-5",
+    "max_tokens": 300,
+    "messages": [{ "role": "user",
+      "content": "Write a payment reminder to Margaret Ellison (margaret@acme.co) for IBAN DE44500105175407324931." }]
+  }'
+```
+
+You get a normal answer with the real name/IBAN in it. To see what the model
+*actually* received, check the receipt hash and detected labels:
+
+```bash
+node bin/proxy.js verify
+cat ~/.solrouter/receipts.jsonl | tail -1
+```
+
+`detected` lists the labels masked (PERSON, EMAIL, IBAN…); the model never saw the
+real values.
+
+## 3. Wire it into a coding tool
+
+Set the tool's base URL and keep using your own key:
+
+```bash
+# OpenAI-compatible (Cursor, Cline, Continue, OpenAI SDK)
+export OPENAI_BASE_URL=http://127.0.0.1:8787/v1
+
+# Anthropic-compatible (Claude Code)
+export ANTHROPIC_BASE_URL=http://127.0.0.1:8787
+```
+
+Per-request control:
+
+```bash
+-H "x-route: private"    # force the uncensored leg (needs login)
+-H "x-route: frontier"   # force the frontier model
+-H "x-mode: private"     # private for this whole request
+-H "x-intent: authorized pentest, scope acme.com"   # frontier leg only
+```
+
+## 4. Test the private/uncensored leg (real backend)
+
+The private leg calls the SolRouter backend's `/agent` route with a `sk_solrouter_`
+key — the same key type the backend already issues. No new endpoint needed.
+
+```bash
+solrouter login --token sk_solrouter_...   # your SolRouter API key
+# force the uncensored leg for a request:
+curl http://127.0.0.1:8787/v1/chat/completions \
+  -H "content-type: application/json" \
+  -H "x-route: private" \
+  -d '{"model":"x","messages":[{"role":"user","content":"..."}]}'
+```
+
+It hits `POST {backend}/agent` with `{prompt, model:"qwen3.8:27b", useTools:false}`,
+stateless (no chatId needed for API-key users). `x-route: auto` (the default) tries
+the frontier model first and reroutes here if it refuses.
+
+Requires the backend + its Nosana/TEE node to be up (it's the live prod backend by
+default). If the Qwen node is cold, see `scripts/NOSANA_RUNBOOK.md`.
+
+## What needs a live backend vs. runs anywhere
+
+- **Anywhere, no account:** `demo`, `npm test`, masking/restore/receipts, and the
+  frontier leg with your own key (§2–3).
+- **Needs a `sk_solrouter_` key + backend up:** the private/uncensored leg (§4).
+
+The only not-yet-built convenience is the browser `login` (loopback OAuth); the
+`--token` path is complete and is what makes the private leg work today.

package/bin/proxy.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// solrouter — CLI. Same shape as Claude Code / gh:
+//   solrouter login          verify your account in the browser
+//   solrouter start           run the local proxy (default command)
+//   solrouter status          show config + login state
+//   solrouter verify          check the receipt hash-chain
+//   solrouter logout
+
+import { loadConfig, isLoggedIn, loadAuth, HOME_DIR } from "../src/config.js";
+import { browserLogin, loginWithToken } from "../src/auth.js";
+import { startServer } from "../src/server.js";
+import { verifyChain } from "../src/receipt.js";
+import { runDemo } from "../src/demo.js";
+import { rmSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+const [, , cmdRaw, ...rest] = process.argv;
+const cmd = cmdRaw || "start";
+const flag = name => { const i = rest.indexOf(name); return i >= 0 ? (rest[i + 1] ?? true) : undefined; };
+
+async function main() {
+  switch (cmd) {
+    case "login": {
+      const token = flag("--token");
+      if (token && token !== true) {
+        loginWithToken(token, flag("--account") || null);
+        console.log("Saved. You're logged in.");
+        return;
+      }
+      try {
+        const t = await browserLogin();
+        console.log(`Logged in${t.account ? " as " + t.account : ""}.`);
+      } catch (e) {
+        console.error("Login failed:", e.message);
+        console.error("Stopgap: solrouter login --token <your SolRouter API key>");
+        process.exit(1);
+      }
+      return;
+    }
+
+    case "logout": {
+      const p = join(HOME_DIR, "auth.json");
+      if (existsSync(p)) rmSync(p);
+      console.log("Logged out.");
+      return;
+    }
+
+    case "status": {
+      const cfg = loadConfig();
+      const a = loadAuth();
+      console.log("SolRouter proxy");
+      console.log("  logged in :", isLoggedIn() ? `yes${a.account ? " (" + a.account + ")" : ""}` : "no");
+      console.log("  port      :", cfg.port);
+      console.log("  mode      :", cfg.mode);
+      console.log("  frontier  :", cfg.frontier.model, "→", cfg.frontier.baseUrl);
+      console.log("  private   :", cfg.private.model, "→", cfg.private.baseUrl);
+      console.log("  masking   :", cfg.masking?.enabled === false ? "off" : "on");
+      console.log("  receipts  :", cfg.receipt?.path);
+      return;
+    }
+
+    case "demo": {
+      const ok = await runDemo();
+      process.exit(ok ? 0 : 1);
+    }
+
+    case "verify": {
+      const cfg = loadConfig();
+      const r = verifyChain(cfg.receipt.path);
+      if (r.ok) console.log(`Receipt chain OK — ${r.count} record(s).`);
+      else { console.error(`Receipt chain BROKEN at record ${r.brokenAt} (${r.why}).`); process.exit(1); }
+      return;
+    }
+
+    case "start":
+    default: {
+      const cfg = loadConfig({ port: flag("--port") ? Number(flag("--port")) : undefined,
+                              mode: flag("--mode") || undefined });
+      // Pass-through supplies frontier creds per request, so login is not required
+      // to start — it only unlocks the private/uncensored leg.
+      if (!isLoggedIn()) {
+        console.warn("Note: not logged in — the private/uncensored leg is unavailable.");
+        console.warn("      The frontier leg uses your tool's own credentials. Run `login` to enable both.\n");
+      }
+      startServer(cfg);
+      return;
+    }
+  }
+}
+
+main().catch(e => { console.error(e); process.exit(1); });

package/config.example.json

@@ -0,0 +1,24 @@
+{
+  "port": 8787,
+  "mode": "auto",
+  "frontier": {
+    "baseUrl": "https://api.anthropic.com",
+    "dialect": "anthropic",
+    "model": "claude-opus-5"
+  },
+  "private": {
+    "baseUrl": "https://solrouter-obb4.onrender.com",
+    "dialect": "openai",
+    "model": "qwen3.8:27b"
+  },
+  "masking": {
+    "enabled": true,
+    "names": ["Acme Holdings", "Margaret Ellison"],
+    "guessNames": true
+  },
+  "receipt": {
+    "enabled": true,
+    "path": "~/.solrouter/receipts.jsonl"
+  },
+  "viaSolrouter": true
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "solrouter",
+  "version": "0.1.0",
+  "description": "Local privacy router for coding tools: pseudonymises every request before it leaves your machine, and sends work a frontier model would refuse to an uncensored open-weight model you control.",
+  "type": "module",
+  "bin": {
+    "solrouter": "bin/proxy.js"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "SPEC.md",
+    "TESTING.md",
+    "config.example.json"
+  ],
+  "scripts": {
+    "start": "node bin/proxy.js",
+    "demo": "node bin/proxy.js demo",
+    "test": "node --test 'test/*.test.js'",
+    "prepublishOnly": "node --test 'test/*.test.js'"
+  },
+  "keywords": [
+    "solrouter", "privacy", "llm", "proxy", "pseudonymize", "pii", "claude", "openai", "router"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}

package/src/auth.js

@@ -0,0 +1,69 @@
+// auth.js — "download, verify in the browser, ship" login, same shape as the
+// Claude Code / gh CLI flow.
+//
+// The CLI opens a loopback server on a random port, opens the browser to the
+// SolRouter verify page with that port as the redirect target, the user approves
+// in the browser, the page redirects back to the loopback with a token, and the
+// CLI saves it. A `state` nonce ties the callback to this attempt.
+//
+// The real auth is a SolRouter API key (`sk_solrouter_...`, bcrypt-verified by the
+// backend). `login --token sk_solrouter_...` saves one and the private leg works.
+// The browser loopback flow below is a future convenience that mints/returns such a
+// key without a paste; it needs a small backend verify page, which is optional —
+// the token path is complete on its own.
+
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+import { exec } from "node:child_process";
+import { saveAuth } from "./config.js";
+
+const VERIFY_BASE = process.env.SOLROUTER_VERIFY_URL || "https://solrouter.com/cli/auth";
+
+function openBrowser(url) {
+  const cmd = process.platform === "darwin" ? "open"
+    : process.platform === "win32" ? "start \"\"" : "xdg-open";
+  exec(`${cmd} "${url}"`);
+}
+
+/** Loopback browser login. Resolves once the callback delivers a token.
+ *  `open` is injectable for testing (defaults to launching the real browser). */
+export function browserLogin({ timeoutMs = 180000, open = openBrowser } = {}) {
+  return new Promise((resolve, reject) => {
+    const state = randomBytes(16).toString("hex");
+    const server = createServer((req, res) => {
+      const url = new URL(req.url, "http://127.0.0.1");
+      if (url.pathname !== "/callback") { res.writeHead(404).end(); return; }
+      if (url.searchParams.get("state") !== state) {
+        res.writeHead(400).end("state mismatch"); return;
+      }
+      const token = {
+        access_token: url.searchParams.get("token"),
+        account: url.searchParams.get("account") || null,
+        expires_at: Number(url.searchParams.get("expires_at")) || null,
+      };
+      res.writeHead(200, { "content-type": "text/html" });
+      res.end("<h2>SolRouter proxy connected.</h2><p>You can close this tab and return to the terminal.</p>");
+      server.close();
+      if (!token.access_token) return reject(new Error("no token in callback"));
+      saveAuth(token);
+      resolve(token);
+    });
+    server.listen(0, "127.0.0.1", () => {
+      const port = server.address().port;
+      const redirect = `http://127.0.0.1:${port}/callback`;
+      const verifyUrl = `${VERIFY_BASE}?redirect_uri=${encodeURIComponent(redirect)}&state=${state}`;
+      console.log("Opening your browser to verify your SolRouter account…");
+      console.log("If it doesn't open, visit:\n  " + verifyUrl);
+      open(verifyUrl);
+    });
+    setTimeout(() => { server.close(); reject(new Error("login timed out")); }, timeoutMs);
+  });
+}
+
+/** Stopgap: save a pasted token directly. */
+export function loginWithToken(token, account = null) {
+  saveAuth({ access_token: token, account, expires_at: null });
+  return { access_token: token, account };
+}
+
+export default { browserLogin, loginWithToken };