@chatpanel/gateway 0.1.0

package/LICENSE

@@ -0,0 +1,168 @@
+# PolyForm Shield License 1.0.0
+
+<https://polyformproject.org/licenses/shield/1.0.0>
+
+Required Notice: Copyright © 2026 ChatPanel (https://chatpanel.net)
+
+Licensor Line of Business: ChatPanel — an AI browser side-panel, its local
+bridge, and related developer tools and services (https://chatpanel.net)
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to
+distribute copies of the software.  Your license to distribute
+covers distributing the software with changes and new works
+permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright © 2026 ChatPanel (https://chatpanel.net)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncompete
+
+Any purpose is a permitted purpose, except for providing any
+product that competes with the software or any product the
+licensor or any of its affiliates provides using the software.
+
+## Competition
+
+Goods and services compete even when they provide functionality
+through different kinds of interfaces or for different technical
+platforms.  Applications can compete with services, libraries
+with plugins, frameworks with development tools, and so on,
+even if they're written in different programming languages
+or for different computer architectures.  Goods and services
+compete even when provided free of charge.  If you market a
+product as a practical substitute for the software or another
+product, it definitely competes.
+
+## New Products
+
+If you are using the software to provide a product that does
+not compete, but the licensor or any of its affiliates brings
+your product into competition by providing a new version of
+the software or another product using the software, you may
+continue using versions of the software available under these
+terms beforehand to provide your competing product, but not
+any later versions.
+
+## Discontinued Products
+
+You may begin using the software to compete with a product
+or service that the licensor or any of its affiliates has
+stopped providing, unless the licensor includes a plain-text
+line beginning with `Licensor Line of Business:` with the
+software that mentions that line of business.  For example:
+
+> Licensor Line of Business: ChatPanel — an AI browser side-panel, its local
+> bridge, and related developer tools and services (https://chatpanel.net)
+
+## Sales of Business
+
+If the licensor or any of its affiliates sells a line of
+business developing the software or using the software
+to provide a product, the buyer can also enforce
+Noncompete for that product.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law.  These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately.  If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+A **product** can be a good or service, or a combination
+of them.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+its affiliates.
+
+**Affiliates** means the other organizations that an
+organization has control over, is under the control of, or is
+under common control with.
+
+**Control** means ownership of substantially all the assets of
+an entity, or the power to direct its management and policies
+by vote, contract, or otherwise.  Control can be direct or
+indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

package/README.md

@@ -0,0 +1,150 @@
+# ChatPanel Privacy Gateway
+
+A localhost server that puts **ChatPanel's PII redaction / pseudonymization in the
+middle of two CLI agents** — so you can use the privacy features outside the
+ChatPanel extension. Point [opencode](https://opencode.ai) / pi at the gateway,
+and it drives **codex / Claude Code behind your existing subscription login**
+(via the [bridge](https://github.com/chatpanel/chatpanel-bridge)), redacting on
+the way out and restoring on the way back. The model only ever sees opaque
+placeholders like `[[PERSON_1]]` / `[[EMAIL_2]]` — **the real values never leave
+your machine.**
+
+```
+  opencode / pi   (configured with a custom provider → the gateway)
+        │   baseURL → http://127.0.0.1:4320/v1
+        ▼
+  ┌──────────────────────────────────────────────┐
+  │  ChatPanel Privacy Gateway                    │
+  │   1. detect + redact   →  [[PERSON_1]] …       │
+  │   2. drive the agent behind your login        │
+  │   3. restore placeholders in the reply         │
+  └──────────────────────────────────────────────┘
+        │   POST /chat  (bridge: subscription-authed CLI)
+        ▼
+  chatpanel-bridge ──spawns──▶ codex / claude   (your ChatGPT / enterprise / Claude login)
+```
+
+Two backends (config `backend`):
+
+- **`bridge`** (default) — drive the bridge's subscription-authed CLI agents
+  (`codex` / `claude` / `opencode` / `pi`). No API keys, uses your login. This is
+  the "privacy bridge between two agents" path above.
+- **`api`** — forward redacted traffic to a native OpenAI/Anthropic-compatible
+  endpoint (local models, BYO keys). The client's own auth header passes through;
+  the gateway stores no keys.
+
+The redaction engine is the **same code** the ChatPanel extension runs — the
+[`chatpanel-pii`](https://github.com/chatpanel/chatpanel-pii) package is the
+single source of truth, so a privacy feature added once is shared everywhere.
+
+## Quick start (bridge backend)
+
+You need the [ChatPanel bridge](https://github.com/chatpanel/chatpanel-bridge)
+running and logged into codex/claude (the same bridge the extension uses).
+
+```bash
+npm install -g chatpanel-gateway
+chatpanel-gateway
+# → ChatPanel Privacy Gateway v0.1.0 on http://127.0.0.1:4320
+#     backend  : bridge (agent: codex, via http://127.0.0.1:4319)
+```
+
+Then point your front-end agent at it. **opencode** (`opencode.json`):
+
+```jsonc
+{
+  "provider": {
+    "chatpanel": {
+      "npm": "@ai-sdk/openai-compatible",
+      "options": { "baseURL": "http://127.0.0.1:4320/v1" },
+      "models": { "codex": {}, "claude": {} }   // selects the agent behind the gateway
+    }
+  }
+}
+```
+
+Now opencode talks to codex **through** the gateway — every prompt is redacted
+before codex sees it, and the reply is restored before opencode renders it. The
+request's `model` (`codex`/`claude`/`opencode`/`pi`) picks which agent the bridge
+drives; otherwise the configured default (`codex`) is used.
+
+### Using the api backend instead (local models / BYO keys)
+
+Set `backend: "api"` (see config) and the gateway forwards redacted traffic to a
+real provider endpoint, passing your `Authorization` / `x-api-key` through:
+
+```bash
+export OPENAI_BASE_URL=http://127.0.0.1:4320/v1     # OpenAI / codex / aider / cursor
+export ANTHROPIC_BASE_URL=http://127.0.0.1:4320     # Claude Code / Anthropic SDK
+```
+
+## Name/org redaction is built in (bundled NER)
+
+Deterministic redaction (emails, phones, cards, SSNs, API keys, IPs) needs no
+setup. To also blind **names, organizations and locations**, the gateway bundles
+a local spaCy NER server under [`ner/`](ner) and — with `ner.autostart` on (the
+default) — **launches it for you on startup** and switches redaction to the
+`full` tier once it's healthy. First run creates a venv and downloads the model
+(needs `python3`); it's fail-open, so if Python isn't set up the gateway just runs
+deterministic-only.
+
+Prefer a local LLM or an external NER service? Set `redaction.detection` yourself
+and the gateway won't autostart the bundled one.
+
+## Configuration
+
+Precedence: defaults < `gateway.config.json` (or `$CHATPANEL_GATEWAY_CONFIG`) <
+env vars. See [`gateway.config.example.json`](gateway.config.example.json).
+
+| Key | Env | Default | Meaning |
+|-----|-----|---------|---------|
+| `backend` | — | `bridge` | `bridge` (drive CLI agents via login) or `api` (forward to a provider) |
+| `bridge.url` | — | `http://127.0.0.1:4319` | the ChatPanel bridge |
+| `bridge.agent` | — | `codex` | default agent the bridge drives |
+| `bridge.token` | — | _(auto)_ | bridge bearer token; empty = read `~/.chatpanel/bridge-token` |
+| `host` / `port` | `CHATPANEL_GATEWAY_HOST` / `_PORT` | `127.0.0.1` / `4320` | bind address |
+| `upstreams.openai.baseUrl` | `OPENAI_BASE_URL` | `https://api.openai.com` | api backend only |
+| `upstreams.anthropic.baseUrl` | `ANTHROPIC_BASE_URL` | `https://api.anthropic.com` | api backend only |
+| `redaction.tier` | `CHATPANEL_REDACTION_TIER` | `basic` | `basic` (regex) or `full` (+ NER + dictionary) |
+| `redaction.detection` | — | _(auto via NER)_ | local detector; set to override the bundled one |
+| `redaction.dictionary` | — | `[]` | custom `{ value\|pattern, type, alias? }` entries |
+| `ner.autostart` / `ner.port` | — | `true` / `9009` | launch + wire the bundled spaCy NER |
+
+## Endpoints
+
+| Route | Behavior |
+|-------|----------|
+| `GET /health` | `{ ok, version, backend, tier }` |
+| `GET /v1/models` | the agent(s) this gateway exposes |
+| `POST /v1/chat/completions` | OpenAI protocol — redact → backend → restore |
+| `POST /v1/responses` | OpenAI Responses protocol (Codex) |
+| `POST /v1/messages` | Anthropic protocol (Claude Code) |
+
+Streaming (SSE) is supported on all three: placeholders are restored on the fly,
+holding back a tail so a token split across chunks (`[[PER` … `SON_1]]`) still
+restores cleanly.
+
+## How it fits with ChatPanel
+
+The [extension](https://github.com/chatpanel/chatpanel-extension) redacts inside
+the browser; the [bridge](https://github.com/chatpanel/chatpanel-bridge) lets the
+browser drive local CLI agents. This gateway reuses the bridge to put the **same
+redaction engine** ([`chatpanel-pii`](https://github.com/chatpanel/chatpanel-pii))
+in front of *any* agent — so non-browser tools get the privacy too, and the
+agent's own multi-turn loop is blinded, not just the first prompt.
+
+## Caveats
+
+- **Reversibility** is best-effort: if the model paraphrases a placeholder instead
+  of echoing it, that one reference shows the token. The privacy guarantee (the
+  real value never left the device) always holds.
+- A dictionary **alias** is a *permanent* pseudonym — the agent sees the alias,
+  not the original, by design.
+- **Code edits**: redacting values that appear inside source can affect round-trip
+  edits. The default tier touches only structured secrets and (in `full`) detected
+  entities — keep your dictionary prose-focused.
+
+## License
+
+Source-available under the same license as the ChatPanel extension and bridge —
+see [LICENSE](LICENSE).

package/bin/chatpanel-gateway.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+// CLI entry for the ChatPanel Privacy Gateway.
+//
+//   chatpanel-gateway              start the gateway (foreground)
+//   chatpanel-gateway --install    register login auto-start + start now
+//   chatpanel-gateway --uninstall  remove login auto-start
+//   chatpanel-gateway --status     is auto-start registered?
+//   chatpanel-gateway --version    print version
+//
+// Config comes from gateway.config.json / env (see src/config.js).
+import { start, VERSION } from '../src/server.js';
+import { installService, uninstallService, serviceStatus } from '../src/service.js';
+
+const arg = process.argv[2];
+
+try {
+  switch (arg) {
+    case '--version':
+    case '-v':
+      console.log(VERSION);
+      break;
+    case '--install':
+      installService();
+      console.log('ChatPanel Privacy Gateway: installed login auto-start and started it.');
+      break;
+    case '--uninstall':
+      uninstallService();
+      console.log('ChatPanel Privacy Gateway: removed login auto-start.');
+      break;
+    case '--status':
+      console.log(serviceStatus() ? 'installed (auto-start registered)' : 'not installed');
+      break;
+    case undefined:
+      start();
+      break;
+    default:
+      console.error(`unknown option: ${arg}\nUsage: chatpanel-gateway [--install|--uninstall|--status|--version]`);
+      process.exit(2);
+  }
+} catch (e) {
+  console.error(`error: ${e.message}`);
+  process.exit(1);
+}

package/gateway.config.example.json

@@ -0,0 +1,33 @@
+{
+  "host": "127.0.0.1",
+  "port": 4320,
+
+  "backend": "bridge",
+  "bridge": {
+    "url": "http://127.0.0.1:4319",
+    "agent": "codex",
+    "token": ""
+  },
+
+  "upstreams": {
+    "openai": { "baseUrl": "https://api.openai.com" },
+    "anthropic": { "baseUrl": "https://api.anthropic.com" }
+  },
+
+  "redaction": {
+    "tier": "full",
+    "redactSystem": true,
+    "dictionary": [
+      { "value": "Acme Corp", "type": "ORG" },
+      { "value": "Project Atlas", "alias": "Project Nimbus" }
+    ]
+  },
+
+  "ner": {
+    "autostart": true,
+    "port": 9009,
+    "enableFullTier": true
+  },
+
+  "logRequests": true
+}

package/ner/README.md

@@ -0,0 +1,84 @@
+# ChatPanel — local NER helper (spaCy)
+
+A ~30-line local service that lets ChatPanel **auto-redact names, organizations,
+and locations** before anything is sent to a chat model. Detection runs entirely
+on your machine; the model only ever sees placeholders like `[[PERSON_1]]`.
+
+ChatPanel's redaction contract is simple — any local HTTP service works:
+
+```
+POST /ner   { "text": "..." }
+→           { "entities": [ { "value": "Alex", "type": "PERSON" }, ... ] }
+```
+
+(spaCy's `{ "ents": [{ "text", "label" }] }` shape is also accepted, as is a
+local OpenAI-compatible LLM — see "Other detectors" below.)
+
+## Quick start
+
+Most machines block installing Python packages globally, so use a virtual env:
+
+```bash
+cd helpers/ner-server
+
+python3 -m venv .venv
+source .venv/bin/activate            # Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+python -m spacy download en_core_web_sm
+
+uvicorn server:app --port 9009       # the file is server.py → import path "server:app"
+```
+
+…or just run the bundled script (does all of the above):
+
+```bash
+./run.sh                             # PORT=9100 ./run.sh to change the port
+```
+
+Check it's up: `curl http://127.0.0.1:9009/health`
+
+## Point ChatPanel at it
+
+**Settings → Privacy** (or the 🛡 button in the chat composer):
+
+| Field | Value |
+|------|-------|
+| Redaction | **On — + AI detection** |
+| Detector | **Local NER service (spaCy / Presidio)** |
+| Detector URL | `http://127.0.0.1:9009/ner` |
+| Redact types | People / Organizations / Locations / Numbers (your choice) |
+
+Now `my name is Alex from Denver` is sent to the model as
+`my name is [[PERSON_1]] from [[LOCATION_1]]`, and the reply is restored to the
+real values in your view.
+
+> Turning **Locations** off keeps city names readable (useful for "how far is X
+> from Y" questions) while still redacting people.
+
+## Accuracy vs. speed
+
+`en_core_web_sm` is small and fast (good default). For fewer misses:
+
+```bash
+python -m spacy download en_core_web_md     # or en_core_web_trf (best, heavier)
+```
+
+then change `MODEL` in `server.py`. Small models can over-tag short acronyms as
+`ORG`; ChatPanel drops noisy short numerics/dates automatically and lets you turn
+off whole categories.
+
+## Other detectors
+
+ChatPanel doesn't care what's behind the URL, as long as it returns the entity
+shape above. Drop-in alternatives:
+
+- **Microsoft Presidio** — `presidio-analyzer` behind a small FastAPI wrapper
+  (returns `{ "results": [...] }`, also accepted).
+- **A local LLM** — set the detector to **Local LLM (OpenAI-compatible)** and
+  point it at Ollama / LM Studio / llama.cpp (e.g. `http://127.0.0.1:11434`);
+  ChatPanel prompts it for strict JSON entities. Slower than spaCy, no extra
+  service to run if you already have a local model. See `../local-model.md`.
+
+Everything is local and latency-guarded (cached + timed out + fail-open): if the
+detector is slow or down, ChatPanel falls back to deterministic redaction so chat
+never blocks.

package/ner/requirements.txt

@@ -0,0 +1,3 @@
+fastapi
+uvicorn[standard]
+spacy

package/ner/run.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# One-shot: create the venv (if needed), install deps + the spaCy model, and serve.
+# Usage:  ./run.sh        (defaults to port 9009)
+#         PORT=9100 ./run.sh
+set -euo pipefail
+cd "$(dirname "$0")"
+
+if [ ! -d .venv ]; then
+  echo "→ creating virtual env (.venv)…"
+  python3 -m venv .venv
+fi
+# shellcheck disable=SC1091
+source .venv/bin/activate
+
+echo "→ installing dependencies…"
+pip install -q --upgrade pip
+pip install -q -r requirements.txt
+python -c "import en_core_web_sm" >/dev/null 2>&1 || python -m spacy download en_core_web_sm
+
+echo "→ serving on http://127.0.0.1:${PORT:-9009}/ner  (Ctrl-C to stop)"
+exec uvicorn server:app --port "${PORT:-9009}"

package/ner/server.py

@@ -0,0 +1,95 @@
+"""
+ChatPanel local NER helper — a tiny on-device entity detector for PII redaction.
+
+ChatPanel's Privacy → "AI detection" can point at any LOCAL service that accepts
+    POST {"text": "..."}
+and returns
+    {"entities": [{"value": "...", "type": "PERSON|ORG|GPE|EMAIL|PHONE|..."}]}
+
+This wraps spaCy (people / organizations / locations) AND adds a regex pass for
+the structured identifiers spaCy doesn't emit (emails, phone numbers, SSNs, cards,
+IPs), so the detector is comprehensive on its own. Only the redacted placeholders
+(e.g. [[PERSON_1]]) ever reach the chat model — the raw text never leaves your box.
+
+--------------------------------------------------------------------------------
+Setup  (most machines block global pip installs, so use a virtual env)
+
+    python3 -m venv .venv
+    source .venv/bin/activate          # Windows: .venv\\Scripts\\activate
+    pip install -r requirements.txt
+    python -m spacy download en_core_web_sm
+
+Run  (the file is server.py, so the uvicorn import path is "server:app")
+
+    uvicorn server:app --port 9009
+
+Then in ChatPanel → Settings → Privacy:
+    Redaction : On — + AI detection
+    Detector  : Local NER service (spaCy / Presidio)
+    URL       : http://127.0.0.1:9009/ner
+
+Tip: en_core_web_sm is small + fast. For better accuracy use en_core_web_md or
+en_core_web_trf (download the same way, then change the load below).
+--------------------------------------------------------------------------------
+"""
+from fastapi import FastAPI
+
+import re
+import spacy
+
+MODEL = "en_core_web_sm"
+nlp = spacy.load(MODEL)
+
+app = FastAPI(title="ChatPanel NER helper")
+
+# spaCy's NER emits names / orgs / locations but NOT structured identifiers, so add
+# a regex pass for those. (ChatPanel also catches these on-device, but emitting them
+# here keeps the detector self-contained — what you test is what you get.) Order
+# matters: more specific patterns run first so a card / SSN isn't re-matched as a
+# phone number.
+_PATTERNS = [
+    ("EMAIL", re.compile(r"[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}")),
+    ("SSN", re.compile(r"\b\d{3}-\d{2}-\d{4}\b")),
+    ("CREDIT_CARD", re.compile(r"\b(?:\d[ -]?){13,19}\b")),
+    ("IP", re.compile(r"\b(?:\d{1,3}\.){3}\d{1,3}\b")),
+    ("PHONE", re.compile(r"(?<!\d)(?:\+?\d{1,2}[ .\-]?)?\(?\d{3}\)?[ .\-]?\d{3}[ .\-]?\d{4}(?!\d)")),
+]
+
+
+def _regex_entities(text):
+    out, taken = [], []
+    for label, rx in _PATTERNS:
+        for m in rx.finditer(text):
+            start, end = m.start(), m.end()
+            if any(start < te and ts < end for ts, te in taken):
+                continue  # span already claimed by a more specific pattern
+            taken.append((start, end))
+            out.append({"value": m.group(0).strip(), "type": label})
+    return out
+
+
+@app.get("/health")
+def health():
+    return {"ok": True, "model": MODEL}
+
+
+@app.post("/ner")
+def ner(payload: dict):
+    """Return spaCy entities + regex identifiers in ChatPanel's expected shape.
+
+    ChatPanel maps common labels itself (PER→PERSON, GPE→LOCATION, …) and keeps
+    only the categories you enable in the Privacy tab, so it's fine to return all
+    of them here.
+    """
+    text = (payload or {}).get("text", "") or ""
+    doc = nlp(text)
+    ents = [{"value": ent.text, "type": ent.label_} for ent in doc.ents]
+    ents.extend(_regex_entities(text))
+    # De-dup identical value+type (spaCy and a regex can both surface the same span).
+    seen, out = set(), []
+    for e in ents:
+        key = (e["type"], e["value"].lower())
+        if e["value"] and key not in seen:
+            seen.add(key)
+            out.append(e)
+    return {"entities": out}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@chatpanel/gateway",
+  "version": "0.1.0",
+  "description": "Local privacy gateway — redacts PII out of OpenAI/Anthropic API traffic before it reaches a model, then restores it in the reply. Point opencode, codex, aider, Claude Code, etc. at it.",
+  "type": "module",
+  "bin": {
+    "chatpanel-gateway": "bin/chatpanel-gateway.js"
+  },
+  "main": "src/server.js",
+  "exports": {
+    ".": "./src/server.js"
+  },
+  "scripts": {
+    "start": "node bin/chatpanel-gateway.js",
+    "test": "node --test",
+    "typecheck": "tsc -p tsconfig.json",
+    "build:bin": "bash scripts/build-binaries.sh"
+  },
+  "files": [
+    "src",
+    "bin",
+    "ner",
+    "gateway.config.example.json",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@chatpanel/pii": "^0.1.0"
+  },
+  "homepage": "https://chatpanel.net",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chatpanel/chatpanel-gateway.git"
+  },
+  "keywords": [
+    "privacy",
+    "pii",
+    "redaction",
+    "pseudonymization",
+    "llm",
+    "proxy",
+    "gateway",
+    "openai",
+    "anthropic",
+    "opencode",
+    "codex"
+  ],
+  "author": "ChatPanel (https://chatpanel.net)",
+  "license": "SEE LICENSE IN LICENSE"
+}