passcontrol 0.6.2 → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,203 +1,371 @@
1
1
  # PassControl
2
2
 
3
- **An identity & credential gateway for AI agents.** Stop pasting your OpenAI/Anthropic keys
4
- into agent runtimes. Start with a named, revocable **Direct Agent Key**, or give a
5
- higher-assurance agent a cryptographic **passport** that signs challenges for short-lived
6
- **work-visas**. The gateway injects your *real* provider key from a vault
7
- and proxies the call — so the agent never holds the key. You get per-agent budgets, scopes,
8
- an instant kill switch, and a per-agent audit trail.
3
+ **An identity & credential gateway for AI agents.** Stop pasting your OpenAI / Anthropic /
4
+ Groq / Mistral / Together / DeepSeek keys into agent runtimes. Start with a named,
5
+ revocable **Direct Agent Key**, or give the agent a higher-assurance cryptographic
6
+ **passport** that signs challenges for short-lived **work-visas**. The gateway injects your
7
+ *real* provider key from a vault and proxies the call — so **the agent never holds the key**.
8
+ You get per-agent budgets, capability scopes, an instant kill switch, and a per-agent audit trail.
9
9
 
10
- A [Vertias](https://vertias.eu) project. **Bring-your-own-key** (you keep your provider key);
11
- self-host it, or [request access](https://passcontrol.vertias.eu/beta) to the free Cloud private beta.
10
+ A [Vertias](https://vertias.eu) project. **Bring-your-own-key** — your provider key stays in your
11
+ own vault when self-hosted, or in the managed server-side Vault in PassControl Cloud. Cloud is
12
+ currently a free private beta; [request access](https://passcontrol.vertias.eu/beta).
13
+
14
+ ### ▶ [See it work in 60 seconds →](https://passcontrol.vertias.eu)
15
+
16
+ No signup, no provider key, nothing to install. Run a governed AI call, arm the kill switch,
17
+ run the same call again, and watch it get blocked at the gateway. The demo runs the **real**
18
+ pipeline — passport → work-visa → scope + budget checks → kill switch — and only the model
19
+ response is synthesized, by a keyless provider that never touches a vault.
20
+
21
+ The hosted demo includes the public **signed-receipt verifier** at
22
+ [`/verify/receipt`](https://passcontrol.vertias.eu/verify/receipt). Verification runs in your
23
+ browser; the receipt is never uploaded to PassControl.
24
+
25
+ **Hermes Agent:** the dashboard prints Hermes's current custom-provider YAML for a reveal-once
26
+ Direct Agent Key — the simplest path. For passport identity in Hermes, run the connector and
27
+ print its form with `passcontrol env hermes`; that works against Cloud too.
28
+ See [`docs/integrations/hermes.md`](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/hermes.md).
29
+
30
+ **Never paste a passport private key into a client's `api_key` field.** A passport is a signing
31
+ key, not a bearer token — a client that only stores a static string cannot sign a challenge, so
32
+ the call is refused and the key is exposed. Static-key clients take a Direct Agent Key or the
33
+ connector.
34
+
35
+ ![PassControl kill switch — a live agent's calls flip from 200 OK to 403 BLOCKED the instant the kill switch is armed, then back when it's released](https://raw.githubusercontent.com/Vertias3u/PassControl/main/docs/demo/kill-switch.gif)
36
+
37
+ *Instant, per-agent revocation — the kill switch cuts off a live agent mid-run (`200 OK` → `403 BLOCKED`) and restores it, with no key rotation and no redeploy. Real traffic through the gateway; the status codes and timestamps are live.*
12
38
 
13
39
  > ⚠️ **Status: early.** Built by a small team, **not yet independently audited.** It's
14
- > security-focused and test-covered, but treat it as beta — run it on a non-critical key
15
- > first, and see [Security](#security) for responsible disclosure. We'd rather you know than
40
+ > security-focused and test-covered, but treat it as beta — run it against a **non-critical key
41
+ > first**, and see [Security](#security) for responsible disclosure. We'd rather you know than
16
42
  > find out.
17
43
 
44
+ **New here?** The [Getting Started tutorial](https://github.com/Vertias3u/PassControl/blob/main/TUTORIAL.md) takes you from install to a real
45
+ governed agent in ~15 minutes.
46
+
47
+ ```bash
48
+ npm install -g passcontrol
49
+ passcontrol setup # boots the self-hostable stack + opens the Control Tower
50
+ passcontrol try # 60-second guided demo: governed call -> kill switch -> blocked
51
+ ```
52
+
53
+ `setup` needs **Docker Desktop, the Supabase CLI, and Node 18+** — it checks all four
54
+ prerequisites (those three plus free ports) and tells you everything that's missing before it
55
+ starts. Nothing to install? The [hosted demo](https://passcontrol.vertias.eu) runs the same
56
+ pipeline in your browser, keyless.
57
+
18
58
  ---
19
59
 
20
60
  ## Why
21
- A raw provider key handed to an autonomous agent leaks (logs, repos, prompts), never rotates,
22
- has no per-agent spend cap, no off-switch, and no record of *which* agent did *what*.
23
- PassControl removes the key from the agent entirely and puts a governed gateway in front.
61
+
62
+ A raw provider key handed to an autonomous agent **leaks** (logs, repos, prompts), **never
63
+ rotates**, has **no per-agent spend cap**, **no off-switch**, and leaves **no record** of which
64
+ agent did what. PassControl takes the key out of the agent entirely and puts a governed gateway
65
+ in front of it.
24
66
 
25
67
  ## How it works
26
- 1. **Identity** — paste a reveal-once Direct Agent Key into the provider-native SDK or compatible client,
27
- or use an Ed25519 passport whose private key only signs and never travels.
28
- 2. **Work-visa (passport mode)** — the agent signs a challenge (timestamp + single-use nonce) → mints a
29
- short-lived (5 minutes by default) HS256 token carrying its identity, scope, and budget.
30
- 3. **Inject & proxy** — a request arrives with a visa; the gateway verifies it → checks the
31
- kill switch → checks scope → reserves budget → pulls your provider key from Supabase Vault
32
- → injects it → forwards to the provider and streams back. The agent never sees the key.
33
- 4. **Govern** — per-agent token/cost budgets (enforced), layered kill switch
34
- (platform / tenant / per-agent), and an append-only audit log of every call.
68
+
69
+ 1. **Identity** — use a reveal-once Direct Agent Key in the provider-native SDK or compatible client, or a
70
+ passport whose Ed25519 private key only signs and never travels over the wire.
71
+ 2. **Work-visa (passport mode)** — the agent signs a challenge (timestamp + single-use nonce) and mints a
72
+ short-lived (~5 min) token carrying its identity, scope, and budget snapshot.
73
+ 3. **Inject & proxy** — a request arrives bearing a visa. The gateway verifies it → checks the
74
+ kill switch → checks scope (provider + model **and** endpoint) → reserves budget atomically →
75
+ pulls your provider key from the vault → injects it → forwards to the provider and streams
76
+ back. The agent never sees the key.
77
+ 4. **Govern** — per-agent **token + dollar** budgets (enforced *before* the call), a layered kill
78
+ switch (platform / tenant / per-agent), and an append-only audit log of every call.
79
+
80
+ ```
81
+ agent ──sign──▶ challenge ──visa──▶ ┌─────────── PassControl gateway ───────────┐
82
+ │ verify · kill/scope/budget · inject key │ ──▶ provider
83
+ (holds only a passport key) │ (real key from vault, never returned) │ ◀── stream
84
+ └────────────────────────────────────────────┘
85
+ ```
35
86
 
36
87
  ## Features
37
- - 🔑 Agents never hold your provider key (BYOK; key stays in the vault, injected in-flight)
38
- - 🪪 Per-agent cryptographic identity (Ed25519), short-lived revocable visas
39
- - 🔌 Direct Agent Keys — named, independently revocable installation credentials for a
40
- 90-second provider-native Cloud on-ramp; receipts label this lower-assurance mode honestly
41
- - 💸 Enforced per-agent token/cost budgets (reserved pre-flight, reconciled after)
42
- - ⛔ Layered, per-tenant kill switch + per-agent suspend
43
- - 📒 Per-agent / per-passport audit trail (append-only; direct `UPDATE` / `DELETE` /
44
- `TRUNCATE` rejected by the database)
45
- - 🧾 Signed call receipts — a governed call, allowed *or* blocked, is recorded in an
46
- Ed25519-signed artifact anyone can check with `passcontrol verify receipt` (no account,
47
- no access to your database), or by pasting it into `/verify/receipt` on your deployment
48
- - 🧰 Drop-in: point your existing OpenAI/Anthropic/OpenAI-compatible SDK at the gateway
49
- (OpenAI, Anthropic, Groq, Mistral, Together, DeepSeek)
50
- - 🔌 MCP server: expose governed `chat` / `list_models` tools to Claude Desktop, Cursor &
51
- Claude Code — same scope, budget, and kill switch (`passcontrol mcp`)
52
- - 🪪 Agent passport page — per-agent identity document: key-derived sigil, allowed scopes,
53
- providers actually reached, budget state, exportable (redacted) PNG
54
- - 🧭 Policy rules — deny by model or endpoint, restrict to time windows, cap requests per
55
- hour; evaluated at the gateway *before* your provider key is ever resolved
56
- - 🧪 Policy shadow mode — run a candidate policy against real traffic without enforcing it,
57
- see where it would have diverged from the live one, then promote the exact draft you tested
58
- - 🔄 Passport rotation & expiry — rotate a key with a grace window where both keys work, or
59
- with no window at all if it leaked; set an expiry that's enforced when a visa is minted
60
- - 🚨 Break-glass elevation — widen an agent's scope deliberately, for a bounded window (max
61
- 1 hour), with a mandatory reason, an audit row, and a security alert. It widens **scope
62
- only**: kill switch, suspend, policy denials and budgets all still apply
63
- - 🕓 Capability-change history — what changed on an agent, what it changed *from*, and
64
- whether it came from the dashboard or the API
65
- - 🏷️ Owner binding — bind a fleet to a domain you prove you control (HTTPS well-known
66
- challenge), and optionally publish it, so a signed receipt can say *whose* agent called
67
- - 🔀 Provider failover — an ordered fallback list per agent, applied inside the same
68
- governed call
69
- - 🖥️ Control Tower dashboard — an attention queue ranking the fleet by budget risk, expiry,
70
- refusals and inactivity; a call-detail drawer over the stored audit row; before/after
71
- previews on every consequential save; and a persistent indicator while any agent is
72
- elevated. Plus a developer control-plane API and TOTP MFA
73
-
74
- ## Quickstart (self-host)
75
- Stack: **Next.js** (App Router, edge routes) · **Supabase** (Postgres + Vault + Auth) ·
76
- **Upstash Redis**. Deploy on Vercel, Cloudflare Workers through the tested OpenNext path, or any
77
- Node host (`next start`). No Vercel-proprietary services are required — the kill switch is
78
- Redis-backed. See [`docs/deployment/cloudflare.md`](https://github.com/Vertias3u/PassControl/blob/main/docs/deployment/cloudflare.md) for the Cloud
79
- build, production Auth/SMTP checklist, five-minute Cron Trigger, local `workerd` preview, and the
80
- explicit owner-only deploy handoff.
81
-
82
- ### See it work in 60 seconds — nothing to install
83
-
84
- **[passcontrol.vertias.eu](https://passcontrol.vertias.eu)** — no signup, no provider key,
85
- no clone. Run a governed AI call, arm the kill switch, run the same call again, and watch
86
- it get blocked at the gateway.
87
-
88
- That demo runs the **real** pipeline — passport → work-visa → scope + budget checks → kill
89
- switch. Only the model response is synthesized, by a keyless `demo` provider that never
90
- touches the Vault.
91
-
92
- ### Prove it on your own machine (`passcontrol try`)
93
-
94
- Same story, your hardware, still no provider key and no account. This one is a real local
95
- install — **prereqs: Docker Desktop and the Supabase CLI**, and the first stack boot takes
96
- a few minutes:
88
+
89
+ - 🔑 **Agents never hold your provider key** — BYOK; the key stays vaulted, injected in-flight only
90
+ - 🪪 **Per-agent cryptographic identity** (Ed25519) with short-lived, revocable visas
91
+ - 🔌 **Direct Agent Keys** — named, independently revocable installation credentials for a
92
+ fast provider-native on-ramp, with receipts that never mislabel them as passports
93
+ - 💸 **Enforced per-agent token + cost (USD) budgets** — reserved pre-flight, reconciled after
94
+ - 🎯 **Capability scoping** — a visa is scoped to specific models *and* endpoints, so a
95
+ chat-scoped agent can't reach files, fine-tuning, batches, embeddings, etc. with your key
96
+ - ⛔ **Instant, layered kill switch** + per-agent suspend/revoke — stop a running agent mid-task
97
+ - 📒 **Append-only audit trail** per agent/passport (direct `UPDATE`/`DELETE`/`TRUNCATE` rejected
98
+ by the database)
99
+ - 🧾 **Signed call receipts** — a governed call, allowed *or* blocked, is recorded in an
100
+ Ed25519-signed artifact a counterparty can check without an account, your database, or your
101
+ permission ([details below](#signed-call-receipts))
102
+ - 🌐 **Paste-and-check verification page** at `/verify/receipt` — runs entirely in the visitor's
103
+ browser; the receipt is never uploaded
104
+ - 👤 **Owner binding** — declare who your agents are operated by, so a receipt can say *whose*
105
+ agent made the call. Self-declared by default; provable by domain control or an identity
106
+ check, and the two are stored and rendered separately so a claim never passes as a fact
107
+ - 🧰 **Drop-in for your SDK** (OpenAI, Anthropic, and OpenAI-compatible Groq / Mistral / Together /
108
+ DeepSeek) — **or any agent or desktop chat app** that takes a base URL and a key (OpenHands,
109
+ Aider, Cline, Continue, Chatbox, Jan, Msty, Cherry Studio, Open WebUI, LibreChat…): a Cloud
110
+ Direct Agent Key on the hosted service, or the passport connector. None of them has native
111
+ passport support; the connector is what supplies passport identity to a static-key tool —
112
+ against Cloud or a self-hosted gateway
113
+ - 🔌 **Local MCP server** for Claude Desktop, Cursor, and Claude Code — governed `chat` and
114
+ `list_models` tools with no provider key or passport secret in the client config
115
+ - 🪪 **Agent passport page** — a per-agent identity document: a sigil derived from the
116
+ agent's public key, its visas (allowed scopes), the providers it has actually reached,
117
+ budget state, and a redacted PNG you can export
118
+ - 🖥️ **Control Tower** dashboard (fleet, spend, budgets, audit, kill switch) + a developer
119
+ control-plane API + TOTP MFA
120
+
121
+ ## Install & first run
122
+
123
+ **Global CLI (recommended):**
97
124
 
98
125
  ```bash
99
- git clone https://github.com/Vertias3u/PassControl.git && cd PassControl
100
- npm install
101
- PASSCONTROL_DEMO=1 npm run dev:stack # local stack + a keyless demo passport
102
- PASSCONTROL_DEMO=1 npm run dev:docker & # run the gateway with demo mode on
103
- npx passcontrol try # governed call → arm kill switch → blocked → disarm
126
+ npm install -g passcontrol
127
+ passcontrol --version # confirms the install
128
+ passcontrol setup # prereq checks → fetches the stack → boots it → opens the dashboard
104
129
  ```
105
130
 
106
- `passcontrol try` runs the real pipeline end-to-end and shows the same call blocked after
107
- the kill switch fires — the whole PassControl story in one command, verified on your own
108
- stack. Demo mode is **off by default and must never be enabled in production**: the keyless
109
- `demo` provider is env-gated and never touches the Vault. Ready to use it for real?
110
- Continue with the full quickstart below.
131
+ The published npm package is **just the CLI** (a handful of files, no provider keys). `passcontrol
132
+ setup` detects the global install and offers to clone the self-hostable stack (Supabase + Redis +
133
+ dashboard) into `~/passcontrol`, install its dependencies, and start it — one command from nothing
134
+ to a running Control Tower. It first checks your prerequisites (Docker running, Supabase CLI, Node
135
+ version, free ports) and tells you exactly what to fix if something's missing.
136
+
137
+ - Change the checkout location: `--app-dir <path>` or `PASSCONTROL_APP_ROOT=<path>`
138
+ - Non-interactive: `--yes`
139
+ - Skip opening the browser: `--no-open`
140
+ - Ports already taken by another local Supabase? `passcontrol setup --port-offset 100`
141
+ (offsets Supabase + Redis together, e.g. API `54421`, DB `54422`; the dashboard stays on `:3000`)
142
+
143
+ During `dev:stack` the seed step (`scripts/seed.mjs`) asks you to **choose an account email
144
+ and password**. Then log in to the Control Tower at **http://localhost:3000** with those.
111
145
 
112
- ### Local (Docker) quickstart
113
- For the fastest local run, use the bundled Docker stack. It starts Supabase locally
114
- (Postgres + Vault + Auth), Redis-over-REST, applies migrations inside the DB container, and
115
- prompts you to create your Control Tower account. Prereqs: Docker Desktop and the Supabase
116
- CLI. No host `psql` is required.
146
+ > ⚠️ **No shared default credentials ship**, on any install. The account you create guards the
147
+ > real provider keys in your local Vault — and the stack stops being localhost-only the moment
148
+ > you reach it from another device (Tailscale, LAN), so choose a real password. Non-interactive
149
+ > runs (CI, piped output) get a generated password printed once. Deployed installs create
150
+ > accounts through normal signup, gated by `INVITE_CODE`.
151
+
152
+ Add a **non-critical** provider key in the Control Tower, issue a passport, and copy the one-time
153
+ `PASSPORT_ID` / `PASSPORT_SECRET`. Then, in your project directory:
117
154
 
118
155
  ```bash
119
- git clone https://github.com/Vertias3u/PassControl.git && cd PassControl
120
- npm install
121
- npm run dev:stack # starts Supabase + Redis locally, migrates, creates your account
122
- npm run dev:docker # runs the app against the local stack (loads .env.docker)
156
+ passcontrol init # gateway + passport + provider/model → writes .passcontrol
157
+ passcontrol doctor --deep # verifies config, prerequisites, and mints a test visa
158
+ passcontrol version # CLI vs gateway vs database schema, in one table
159
+ passcontrol call "Say hello in 3 words"
160
+ passcontrol spend # confirms governed spend
123
161
  ```
124
162
 
125
- > Use **`npm run dev:docker`**, not `npm run dev`, for the local stack — plain `npm run
126
- > dev` loads `.env.local` (your hosted Supabase), not the Docker stack's `.env.docker`.
163
+ You'll see a streamed response and an `ok` row in the dashboard Audit Log — the complete governed
164
+ loop: **passport → visa → vault key injection → proxied call → audit**. That last call uses your
165
+ real key from the local Vault, so start with a throwaway one.
127
166
 
128
- During `dev:stack` you're asked to choose an account email and password — that account
129
- guards the provider keys in your local Vault, so pick a real password. Open
130
- `http://localhost:3000` and log in with it.
167
+ > Working from a **source clone** instead of the global install? Everything below works as
168
+ > `npm run cli -- <command>`; after `npm link` in the clone, the short `passcontrol <command>` form
169
+ > works too.
131
170
 
132
- > No shared default credentials ship. If the stack was brought up without a terminal
133
- > attached (CI, piped output), a password is generated and printed once by the seed step.
171
+ ## Claude Desktop, Cursor, and Claude Code via MCP
134
172
 
135
- Then add a provider key in the Control Tower. The fastest route is **Connect an agent**:
136
- copy the generated provider-native base URL and reveal-once Direct Agent Key into the
137
- matching SDK or compatible client. For higher-assurance challenge-response identity, issue a passport
138
- and run:
173
+ PassControl ships a local stdio MCP server. Store the passport once in the owner-only global
174
+ profile, then let the CLI merge a secret-free entry into your client config:
139
175
 
140
176
  ```bash
141
- PASSPORT_ID=<passport_id> PASSPORT_SECRET=<passport_secret> \
142
- node examples/chat-agent.mjs "Say hello in 3 words"
177
+ passcontrol init --global
178
+ passcontrol configure claude-desktop --write # or: cursor
179
+ # Claude Code: passcontrol configure claude-code prints its `claude mcp add` command
143
180
  ```
144
181
 
145
- The final agent call uses your real Anthropic/OpenAI key from the local Vault, so start
146
- with a non-critical key.
182
+ Restart the client, then use the governed `chat` and `list_models` tools. The generated config
183
+ contains only absolute Node/CLI paths—no passport or provider key. `chat` still goes through the
184
+ gateway's identity, scope, budget, endpoint, and kill-switch checks. Preview without writing via
185
+ `passcontrol configure claude-desktop`, or print the JSON with `passcontrol env claude-desktop`.
186
+
187
+ ## Real agents & the passport connector
188
+
189
+ > **The connector is not self-hosting.** It is a small local signer — one foreground process,
190
+ > no Docker, no database — that holds your passport and talks to whichever gateway you configure,
191
+ > **including PassControl Cloud**. Running it is the same shape as running a cloud provider's
192
+ > local auth proxy: the control plane stays hosted, only the signing key stays yours.
193
+ >
194
+ > Pick by what your client can do, not by where the gateway lives:
195
+ >
196
+ > | Your client | Credential | Local process? |
197
+ > |---|---|---|
198
+ > | You control its JS/TS | **Passport** via [the SDK](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/passport-sdk.md) | none |
199
+ > | Claude Desktop / Cursor / Claude Code | **Passport** via `passcontrol mcp` | the MCP server |
200
+ > | Takes only a base URL + API key | **Passport** via this connector | the connector |
201
+ > | Takes only a base URL + API key | **Direct Agent Key** — simplest | none |
202
+ >
203
+ > A Direct Agent Key is lower-assurance bearer possession, issued reveal-once from the dashboard
204
+ > and bound to one agent. It is the right default for a static-key tool. The connector is what you
205
+ > reach for when you want passport identity in that same tool — on Cloud or self-hosted alike.
206
+
207
+ A visa is deliberately short-lived so it's revocable — but a real coding agent runs a **long,
208
+ multi-call session** that would outlive a single visa. The **sidecar** solves this: a tiny local
209
+ proxy that mints, caches, and auto-refreshes the visa (and re-mints instantly on expiry), so your
210
+ agent points at one stable endpoint and **never times out mid-task**.
147
211
 
148
- > **Installed globally?** The stack lives in a checkout of this repo, not in the npm
149
- > package, and the CLI remembers which one in `~/.config/passcontrol/app.json`. That file
150
- > outlives `npm uninstall -g`, so a fresh install can keep pointing at an old directory.
151
- > `passcontrol status` shows where the current path came from; `passcontrol unlink` forgets
152
- > it, and `passcontrol setup --app-dir <path>` repoints.
212
+ ```bash
213
+ passcontrol sidecar # http://127.0.0.1:8788
214
+ passcontrol env openhands # prints ready-to-paste settings for your agent
215
+ ```
153
216
 
154
- ### Manual self-host quickstart
217
+ ### Passport identity on Cloud, from a machine with nothing installed
155
218
 
156
- > **Supabase specifically** (not vanilla Postgres): the credential vault uses the
157
- > `supabase_vault` extension, so you need a Supabase project (hosted or the self-hosted
158
- > Supabase stack), not a plain Postgres database.
219
+ Three commands. The published CLI is the CLI only — not the dashboard, not the database — so
220
+ this needs no Docker and no Supabase:
159
221
 
160
222
  ```bash
161
- git clone https://github.com/Vertias3u/PassControl.git && cd PassControl
162
- npm install
163
- cp .env.example .env.local # fill in Supabase / Upstash / secrets
164
- DATABASE_URL='postgresql://…' npm run migrate # applies db/migrations/*.sql in order, once each
165
- npm run dev # or build + `next start` on any Node host
223
+ npm i -g passcontrol
224
+ passcontrol login # opens your browser, you approve once, this machine is set up
225
+ passcontrol sidecar # holds the passport, mints visas, forwards to Cloud
166
226
  ```
167
- See `.env.example` for the full config (Supabase URL/keys, `VISA_SECRET`, `CACHE_ENC_KEY`,
168
- Upstash, `CRON_SECRET`, `PASSCONTROL_SIGNUP_MODE`, `INVITE_CODE`). Apply migrations `0001 → …` in order;
169
- `db/tests/rls_invariants.sql` checks tenant isolation on your database.
170
227
 
171
- **Background reconcile job (required on non-Vercel hosts):** a periodic call to
172
- `GET /api/cron/reconcile` (with header `Authorization: Bearer $CRON_SECRET`) corrects budget
173
- drift and flushes last-seen. On Vercel it's wired via `vercel.json`. Self-hosting, schedule it
174
- yourself (system `cron`, a GitHub Action, etc.) every few minutes — it's a correction layer,
175
- not the hot path, so an occasional missed run is harmless.
228
+ `passcontrol login` prints an 8-character code, copies it to your clipboard, and opens the
229
+ approval page. Paste it, press Approve, and the CLI writes a working config — no copying
230
+ 43-character secrets between a browser and a terminal.
231
+
232
+ You type the code in yourself on purpose. **We will never send you an approval link with the
233
+ code already filled in**; if you receive one, it is not from us, and approving it would hand
234
+ whoever sent it a key to your workspace. Prefer to configure by hand? `passcontrol init` still
235
+ does exactly that.
176
236
 
177
- ## Using it from an agent
178
- For the generic Direct Agent Key path, use the values the dashboard shows once:
237
+ `passcontrol setup` is the *self-host* command and is the one that wants Docker and the
238
+ Supabase CLI. Neither `login` nor the connector wants either.
239
+
240
+ Point any OpenAI/Anthropic-compatible agent at the sidecar with a **dummy** key:
179
241
 
180
242
  ```bash
181
- export OPENAI_BASE_URL=https://YOUR-PASSCONTROL-HOST/api/v1/openai/v1
182
- export OPENAI_API_KEY=pc_agent_REVEAL_ONCE_VALUE
183
- export OPENAI_MODEL=gpt-5
243
+ export ANTHROPIC_BASE_URL="http://127.0.0.1:8788/api/v1/anthropic" # or /api/v1/openai, /deepseek…
244
+ export ANTHROPIC_API_KEY="passcontrol" # ignored — the sidecar injects a live visa
184
245
  ```
185
246
 
186
- For Anthropic's native SDK, the same wizard instead emits
187
- `ANTHROPIC_BASE_URL=https://YOUR-PASSCONTROL-HOST/api/v1/anthropic`,
188
- `ANTHROPIC_API_KEY`, and a concrete `ANTHROPIC_MODEL`. Authorization wildcard patterns
189
- such as `gpt-*` or `claude-*` are never copied into the SDK's model field.
247
+ **Why not `HTTPS_PROXY`?** Because governing a `CONNECT` tunnel means terminating its TLS,
248
+ which means installing a certificate authority on your machine that can impersonate any
249
+ site to any program trusting it. PassControl exists to get a one-provider secret *off* your
250
+ machine; installing a broader one to save an environment variable is the wrong trade. So
251
+ the sidecar answers `HTTPS_PROXY` honestly instead of silently: a `CONNECT` to a provider
252
+ is **refused** with the base URL to use, never quietly tunnelled into a call that looks
253
+ governed and is not. It also refuses every other host — it is not an open proxy — and
254
+ `--allow-connect <host>` names exceptions, which can never be a provider.
255
+
256
+ The agent never holds a real key or a long-lived token. Presets ship for coding agents
257
+ (**openhands, aider, cline, continue, litellm**), for the desktop chat apps you would otherwise
258
+ paste a raw provider key into (**chatbox, jan, msty, cherry-studio, open-webui, librechat**), and
259
+ a catch-all **generic** (`passcontrol env <preset>`). `passcontrol env` with an unknown name
260
+ prints the current list, which is generated — it cannot drift from what the CLI accepts. Also,
261
+ **[Hermes Agent](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/hermes.md)** works through the generic settings with no custom
262
+ code. A single long streaming completion also works
263
+ directly — it's verified once at the start, so it finishes even if it runs past the visa TTL; only
264
+ *multi-call* sessions need the sidecar's refresh. Raise `VISA_TTL_SECONDS` (300–900) to widen the
265
+ window, but the sidecar is the real answer for long sessions.
266
+
267
+ > If a client defaults to OpenAI `/responses` (some Continue configs for o-series/gpt-5), force
268
+ > `/chat/completions` — PassControl intentionally proxies only chat/messages and model-listing
269
+ > endpoints.
270
+
271
+ ## Signed call receipts
272
+
273
+ Your audit log convinces **you**. It convinces nobody else — you control that database.
274
+
275
+ A **receipt** is one call's record, signed with your deployment's Ed25519 key. Anyone can
276
+ check it with no account, no access to your database, and no cooperation from you. Approvals
277
+ and refusals are both signed; *"the gateway stopped this agent from touching that model,
278
+ here's the proof"* is often the more useful document.
190
279
 
191
- That key is not a passport and never becomes one in receipts. It is still bound to the
192
- agent's live scopes, policy, budgets, suspension, and kill switches. Add a signing passport
193
- later without replacing the agent ID or history.
280
+ ```bash
281
+ passcontrol keygen instance # generates INSTANCE_SIGNING_KEY; set PASSCONTROL_ISSUER too
282
+ ```
194
283
 
195
- Hermes Agent uses its current `model.provider: custom` configuration, not the removed legacy
196
- base-URL environment variables. Cloud users copy the exact YAML from **Connect an agent**;
197
- self-hosted passport users run `passcontrol env hermes`. See
198
- [`docs/integrations/hermes.md`](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/hermes.md).
284
+ Then anyone you hand a receipt to runs:
199
285
 
200
- For passport mode, the client SDK hides the visa dance:
286
+ ```bash
287
+ passcontrol verify receipt "<receipt>" --issuer https://passcontrol.example.com
288
+ ```
289
+
290
+ ```
291
+ ✓ Receipt is valid.
292
+ → Issuer: http://localhost:3000
293
+ → Passport: kZCFp7d2x4VDruiulJ21gogYbczBDAGZa-OuwR3qgh8
294
+ → Call: POST chat/completions → demo/demo-1
295
+ → Verdict: ok (HTTP 200)
296
+ → Usage: 15 in / 46 out · 61 µ¢
297
+ → Request: sha-256 VizsbKJwhtYoTNBv_XkJSf4ihWpdQWQfpXVvuDA6usM (105 bytes)
298
+ ```
299
+
300
+ Change one character and it fails. No terminal? Your deployment serves a paste-and-check page
301
+ at **`/verify/receipt`** (including on the hosted demo) — verification runs in the visitor's browser, the receipt is never
302
+ uploaded, and the shareable link carries it in the URL fragment, which browsers never send to
303
+ a server.
304
+
305
+ **What it does and doesn't prove.** A valid signature means the named issuer signed this
306
+ record and nothing in it has changed. It does *not* vouch for the issuer — anyone can run
307
+ PassControl, so trusting it is the reader's call. It covers the **request and the gateway's
308
+ decision**, never the provider's reply. And the absence of a receipt proves nothing: receipt
309
+ writing is best-effort, so this is evidence, not a complete ledger.
310
+
311
+ > **Rotating the signing key is the one dangerous operation.** Receipts never expire, so
312
+ > replacing the key retroactively invalidates every receipt you have ever signed. Move the old
313
+ > seed to `INSTANCE_SIGNING_KEY_PREV` **first** — nothing is ever signed with it; it exists so
314
+ > its public half stays published. This is inverted relative to `VISA_SECRET_PREV`.
315
+
316
+ Full claim reference and the JWKS endpoint: [`DOCUMENTATION.md`](https://github.com/Vertias3u/PassControl/blob/main/DOCUMENTATION.md) ·
317
+ walkthrough: [`TUTORIAL.md`](https://github.com/Vertias3u/PassControl/blob/main/TUTORIAL.md).
318
+
319
+ ## CLI command center
320
+
321
+ The primary interface is `passcontrol <command>`. Highlights:
322
+
323
+ | Need | Command |
324
+ |---|---|
325
+ | Config, gateway status, suggested next steps | `passcontrol status` |
326
+ | Check local setup / mint a test visa | `passcontrol doctor --deep` |
327
+ | Compare CLI, gateway and database versions | `passcontrol version` |
328
+ | Make a governed model call | `passcontrol call "Summarize this"` |
329
+ | Run the local MCP server | `passcontrol mcp` |
330
+ | Run the auto-refreshing bridge for an agent | `passcontrol sidecar` |
331
+ | Print agent/MCP settings without writing | `passcontrol env openhands` · `passcontrol env claude-desktop` |
332
+ | List / create agents | `passcontrol agent list` · `passcontrol agent create billing-bot` |
333
+ | Suspend, resume, or revoke an agent | `passcontrol agent suspend <id>` |
334
+ | Inspect spend, logs, and audit history | `passcontrol spend` · `passcontrol logs` · `passcontrol audit` |
335
+ | Save / restore a workspace configuration snapshot | `passcontrol export --out workspace.json` · `passcontrol import workspace.json` (previews first; never overwrites an existing agent) |
336
+ | Generate this deployment's receipt signing key | `passcontrol keygen instance` |
337
+ | Check a receipt or agent token (no account needed) | `passcontrol verify receipt <jws> --issuer <origin>` |
338
+ | Arm / release the tenant kill switch | `passcontrol kill on` · `passcontrol kill off` |
339
+ | Prepare or repair local services | `passcontrol setup` · `passcontrol doctor --fix` |
340
+ | Start / stop the whole local stack | `passcontrol start` · `passcontrol stop` · `passcontrol restart` (add `--dashboard-only` to leave Supabase and Redis alone) |
341
+ | Follow local dashboard logs | `passcontrol local-logs --follow` |
342
+ | Point the CLI at a different checkout | `passcontrol setup --app-dir <path>` |
343
+ | Forget the remembered checkout | `passcontrol unlink` |
344
+ | Open the Control Tower | `passcontrol open` |
345
+ | Set up an integration (preview, or `--write`) | `passcontrol configure aider` · `passcontrol configure claude-desktop --write` |
346
+
347
+ `passcontrol stop` brings down the **whole** local stack — dashboard, Supabase, and Redis.
348
+ Use `--dashboard-only` to leave the services running. It never removes volumes, so your
349
+ Vault, passports, and audit log survive; wiping data stays with `reset` below.
350
+
351
+ Config resolves in order: **environment variables → project-local `.passcontrol` →
352
+ `~/.config/passcontrol/config`**. `.passcontrol` holds a passport secret, is gitignored, and is
353
+ written owner-only — never commit or share it.
354
+
355
+ The local stack itself lives in a checkout of this repo, not in the installed npm package.
356
+ The CLI resolves it in order: **`--app-dir <path>` → `PASSCONTROL_APP_ROOT` → the
357
+ surrounding checkout → the one it remembers** in `~/.config/passcontrol/app.json`.
358
+ `passcontrol status` shows which of those the current path came from. That remembered path
359
+ outlives `npm uninstall -g`, so if a fresh install keeps pointing at an old directory, clear
360
+ it with `passcontrol unlink` (or repoint with `--app-dir`).
361
+
362
+ `passcontrol reset --local --confirm RESET` destroys and recreates local data — use it only for a
363
+ clean slate.
364
+
365
+ ## Using it from your own code
366
+
367
+ The client SDK exported at `passcontrol/sdk` hides the visa dance — point your provider SDK at the
368
+ gateway and visas auto-refresh:
201
369
 
202
370
  ```ts
203
371
  import OpenAI from "openai";
@@ -207,94 +375,133 @@ const pc = new PassControl({ gateway, passportId, passportSecret });
207
375
  const openai = new OpenAI(pc.clientOptions("openai")); // baseURL + auth wired; visas auto-refresh
208
376
  ```
209
377
 
210
- The compiled ESM SDK ships at `passcontrol/sdk` with the current CLI release. Keep the Passport secret
211
- in a trusted agent runtime; never place it in a browser-exposed environment variable. See the
212
- [Cloud Passport SDK guide](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/passport-sdk.md).
213
-
214
- Manage the fleet programmatically with the control-plane SDK + API key:
378
+ Manage the fleet programmatically with the control-plane SDK + an API key:
215
379
 
216
380
  ```ts
217
- import { ControlClient } from "./sdk";
381
+ import { ControlClient } from "passcontrol/sdk";
218
382
  const cp = new ControlClient({ gateway, apiKey: process.env.PASSCONTROL_API_KEY! });
219
383
  await cp.agents.list();
220
384
  await cp.killSwitch.set(true);
221
385
  ```
222
386
 
223
387
  Both credential-bearing clients enforce the same `gateway` boundary — a bare HTTPS origin, plain
224
- HTTP only on loopback — and refuse anything else at construction, before any request. The `pc_`
225
- key manages the whole fleet, so like the Passport secret it stays server-side and never reaches a
226
- browser bundle.
388
+ HTTP only on loopback — and refuse anything else at construction, before any request.
389
+
390
+ The compiled ESM SDK ships with the current CLI release. Keep Passport secrets **and `pc_` control keys**
391
+ in trusted server runtimes, never browser-exposed variables. See the
392
+ [Cloud Passport SDK guide](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/passport-sdk.md).
393
+ Full API reference: [`openapi.yaml`](https://github.com/Vertias3u/PassControl/blob/main/openapi.yaml) and [`DOCUMENTATION.md`](https://github.com/Vertias3u/PassControl/blob/main/DOCUMENTATION.md). Runnable example
394
+ agents live in [`examples/`](https://github.com/Vertias3u/PassControl/tree/main/examples).
395
+
396
+ ## Self-host
227
397
 
228
- Full API reference: [`openapi.yaml`](https://github.com/Vertias3u/PassControl/blob/main/openapi.yaml) and [`DOCUMENTATION.md`](https://github.com/Vertias3u/PassControl/blob/main/DOCUMENTATION.md).
229
- Runnable example agents in [`examples/`](https://github.com/Vertias3u/PassControl/tree/main/examples).
398
+ Stack: **Next.js** (App Router, edge routes) · **Supabase** (Postgres + Vault + Auth) · **Upstash /
399
+ any Redis**. Deploy on Vercel, Cloudflare Workers through the tested OpenNext path, or any Node host
400
+ (`next start`). No Vercel-proprietary services are required — the kill switch is Redis-backed. See
401
+ [`docs/deployment/cloudflare.md`](https://github.com/Vertias3u/PassControl/blob/main/docs/deployment/cloudflare.md) for the Cloud build, production
402
+ Auth/SMTP checklist, five-minute Cron Trigger, local `workerd` preview, and owner-only deploy handoff.
230
403
 
231
- ## Use it from Claude Desktop, Cursor, or Claude Code (MCP)
232
- `passcontrol mcp` runs a local [MCP](https://modelcontextprotocol.io) server that exposes two
233
- tools — `chat` and `list_models` — to any MCP client. Every `chat` goes through the gateway,
234
- so the provider key stays server-side and the passport's scope, budget, and kill switch all
235
- apply. The client sees the model's response, never your key.
404
+ ### Local (Docker) — the fastest path
236
405
 
237
- Set it up once. Your passport lives in a single trusted local file; the client config never
238
- holds a secret:
406
+ `passcontrol setup` (above) is the one-command route. Under the hood it runs the bundled Docker
407
+ stack: local Supabase (Postgres + Vault + Auth), Redis-over-REST, migrations applied inside the DB
408
+ container, and a seeded dev user. Prereqs: **Docker Desktop, the Supabase CLI, Node 18+** — no host
409
+ `psql` required.
410
+
411
+ From a source checkout you can drive the same thing directly:
412
+
413
+ ```bash
414
+ git clone https://github.com/Vertias3u/PassControl && cd PassControl
415
+ npm install
416
+ npm run cli -- setup # or: passcontrol setup after `npm link`
417
+ ```
418
+
419
+ ### Manual self-host
420
+
421
+ > **Supabase specifically** (not vanilla Postgres): the credential vault uses the `supabase_vault`
422
+ > extension, so you need a Supabase project — hosted or the self-hosted Supabase stack — not a
423
+ > plain Postgres database.
239
424
 
240
425
  ```bash
241
- passcontrol init --global # store the passport once (~/.config/passcontrol)
242
- passcontrol configure claude-desktop --write # merge a secret-free MCP entry into the client
243
- # then restart Claude Desktop
426
+ git clone https://github.com/Vertias3u/PassControl && cd PassControl
427
+ npm install
428
+ cp .env.example .env.local # fill in Supabase / Redis / secrets
429
+ DATABASE_URL='postgresql://…' npm run migrate # applies db/migrations/*.sql in order, once each
430
+ npm run dev # or build + `next start` on any Node host
244
431
  ```
245
432
 
246
- Swap `claude-desktop` for `cursor`, or for Claude Code run the printed
247
- `claude mcp add --scope user passcontrol -- passcontrol mcp`. Ask the client to use the `chat`
248
- tool and the call is governed end-to-end — arm the kill switch and the next tool call is
249
- refused. Run `passcontrol env claude-desktop` to preview the config without writing it.
433
+ See [`.env.example`](https://github.com/Vertias3u/PassControl/blob/main/.env.example) for the full config (Supabase URL/keys, `VISA_SECRET`,
434
+ `CACHE_ENC_KEY`, Redis, `CRON_SECRET`, `PASSCONTROL_SIGNUP_MODE`, `INVITE_CODE`). Apply migrations `0001 → …` in order;
435
+ [`db/tests/rls_invariants.sql`](https://github.com/Vertias3u/PassControl/blob/main/db/tests/rls_invariants.sql) checks tenant isolation and the
436
+ privileged-column locks on your database.
437
+
438
+ **Background reconcile job (required on non-Vercel hosts):** a periodic `GET /api/cron/reconcile`
439
+ (header `Authorization: Bearer $CRON_SECRET`) corrects budget drift and flushes last-seen. On
440
+ Vercel it's wired via `vercel.json`; elsewhere schedule it yourself (system `cron`, a GitHub
441
+ Action…) every few minutes. It's a correction layer, not the hot path — an occasional missed run is
442
+ harmless.
443
+
444
+ ## Providers & endpoints
445
+
446
+ Supported providers: **OpenAI, Anthropic, Groq, Mistral, Together, DeepSeek**. The gateway proxies
447
+ **only chat and model-listing endpoints** — OpenAI-shaped chat completions + models, Anthropic
448
+ messages + models, DeepSeek chat completions. It does **not** proxy embeddings, files, fine-tuning,
449
+ batches, `/responses`, or token-counting endpoints (that's the point — a leaked visa can't reach
450
+ your full provider surface).
250
451
 
251
452
  ## Limitations
252
- - A work-visa is a bearer token and is reusable until it expires — 5 minutes by default,
253
- configurable up to 15 via `VISA_TTL_SECONDS`. Keep it out of logs and prompts; use
254
- suspend/kill switches to block future requests.
255
- - Passport expiry is checked when a visa is **minted**, not on every proxied call, so a
256
- passport that lapses mid-visa keeps working until that visa runs out. Suspend the agent
257
- if you need it stopped now.
258
- - Shadow-mode counts are a **floor, not a census.** The audit write is best-effort by
259
- design, so a database blip loses the row and the shadow verdict with it. Calls logged
260
- before the current draft was last edited are excluded rather than misattributed to it.
261
- - Break-glass widens **scope and nothing else.** To get past a deny rule, change the deny
262
- rule — that is a reviewable act, and break-glass deliberately isn't a way around it.
263
- - An owner binding that is only a typed name is **self-attested, and the UI says so.** Only
264
- the domain-verified tier means anything was actually checked, and a binding that stops
265
- confirming is demoted rather than silently kept.
266
- - The gateway proxies only chat and model-listing endpoints: OpenAI/Groq/Mistral/Together
267
- chat completions and models, Anthropic messages and models, and DeepSeek chat
268
- completions. It does **not** proxy embeddings, files, fine-tuning, batches, responses, or
269
- token-counting endpoints.
270
- - Pricing is a best-effort in-code table and can lag provider price changes. Use it for
271
- budgets and monitoring, not as billing reconciliation against provider invoices.
272
- - Instant revocation assumes Redis is configured for persistence/no-eviction behavior. If
273
- Redis evicts suspend/kill keys, enforcement falls back to short visa TTLs and durable agent
274
- status checks at the next mint.
275
- - Receipts are best-effort: a signing failure never aborts a call, so the **absence** of a
276
- receipt is not evidence a call did not happen. A receipt covers the request and the
277
- gateway's decision — not the provider's reply. Verifying one proves the named issuer signed
278
- it, not that the issuer is honest; anyone can run PassControl.
279
- - Receipts have **no expiry** and are checked against the keys a deployment publishes now, so
280
- replacing `INSTANCE_SIGNING_KEY` invalidates every receipt ever signed. Move the old seed to
281
- `INSTANCE_SIGNING_KEY_PREV` first — it is never signed with; its public half stays published.
453
+
454
+ - A work-visa is a **bearer token**, reusable until it expires (≤5 min). Keep it out of logs and
455
+ prompts; use suspend/kill to block future requests immediately.
456
+ - **Pricing** is a best-effort in-code table and can lag provider price changes. Use it for budgets
457
+ and monitoring, not billing reconciliation against provider invoices.
458
+ - **Instant revocation** assumes Redis is configured for persistence / no-eviction. If Redis evicts
459
+ suspend/kill keys, enforcement falls back to short visa TTLs and the durable agent-status check at
460
+ the next mint.
461
+
462
+ ## What the CLI sends, and where
463
+
464
+ No telemetry, no analytics, no usage reporting — none of this tool's operation is
465
+ reported anywhere. There is exactly **one** outbound request PassControl makes that
466
+ you did not ask for, and it is worth naming precisely rather than leaving you to
467
+ find it in a packet capture:
468
+
469
+ Once every 24 hours, `passcontrol` asks `registry.npmjs.org` for the latest published
470
+ version number so it can tell you when your install is old. It sends nothing but the
471
+ HTTP request itself — no identifiers, no configuration, no workspace or agent data.
472
+ It is skipped entirely when stdout is not a terminal (so it never fires inside an
473
+ agent run, a CI job, or a piped command), skipped under `--json`, and skipped when
474
+ `CI` is set.
475
+
476
+ To turn it off completely:
477
+
478
+ ```bash
479
+ export PASSCONTROL_NO_UPDATE_CHECK=1 # or the conventional NO_UPDATE_NOTIFIER=1
480
+ ```
481
+
482
+ It never downloads or installs anything. Upgrading stays a command you type.
282
483
 
283
484
  ## Security
284
- Security is the point of this project, so please report issues privately rather than opening
285
- a public issue — use GitHub's
485
+
486
+ Security is the whole point, so please report issues privately rather than opening a public
487
+ issue — use GitHub's
286
488
  **[private vulnerability reporting](https://github.com/Vertias3u/PassControl/security/advisories/new)**
287
489
  (Security tab → "Report a vulnerability"). You'll get an acknowledgement and a fix +
288
- disclosure timeline worked out with you. Notes:
289
- - It's **BYOK** — your provider key lives encrypted in your own Supabase Vault; it's
290
- decrypted only in-flight and cached briefly (encrypted) in your own Redis.
490
+ disclosure timeline worked out with you.
491
+
492
+ - It's **BYOK** — your provider key lives encrypted in your own Supabase Vault, decrypted only
493
+ in-flight and cached briefly (encrypted) in your own Redis. It is never logged or returned.
494
+ - Tenant isolation is enforced by Postgres **RLS on every table**; the sole decrypt path is a
495
+ `SECURITY DEFINER`, service-role-only function.
291
496
  - It is **not yet independently audited.** If you find a hole, you're doing us a favor.
292
497
 
293
498
  ## License
499
+
294
500
  Source-available under the **Business Source License (BSL 1.1)** — read it, run it, modify it,
295
501
  self-host it. The one restriction: you may not offer it as a competing hosted/managed service.
296
502
  Converts to Apache 2.0 after the change date. See [`LICENSE`](./LICENSE).
297
503
 
298
504
  ## Contributing
505
+
299
506
  Issues and PRs welcome. Run `npm run typecheck && npm test && npm run build` before a PR (CI
300
- enforces it). Be kind; this is early.
507
+ enforces it). Be kind — this is early.