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 +423 -216
- package/bin/passcontrol.mjs +85 -19
- package/cli/config.mjs +57 -1
- package/cli/login.mjs +466 -0
- package/package.json +1 -1
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
|
|
4
|
-
into agent runtimes. Start with a named,
|
|
5
|
-
|
|
6
|
-
**work-visas**. The gateway injects your
|
|
7
|
-
and proxies the call — so the agent never holds the key
|
|
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**
|
|
11
|
-
self-
|
|
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
|
+

|
|
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
|
|
15
|
-
> first
|
|
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
|
-
|
|
22
|
-
|
|
23
|
-
|
|
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
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
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
|
-
|
|
38
|
-
-
|
|
39
|
-
-
|
|
40
|
-
|
|
41
|
-
-
|
|
42
|
-
-
|
|
43
|
-
-
|
|
44
|
-
|
|
45
|
-
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
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
|
-
|
|
100
|
-
|
|
101
|
-
|
|
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
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
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
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
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
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
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
|
-
|
|
126
|
-
|
|
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
|
-
|
|
129
|
-
|
|
130
|
-
|
|
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
|
-
|
|
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
|
-
|
|
136
|
-
|
|
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
|
-
|
|
142
|
-
|
|
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
|
-
|
|
146
|
-
|
|
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
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
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
|
-
###
|
|
217
|
+
### Passport identity on Cloud, from a machine with nothing installed
|
|
155
218
|
|
|
156
|
-
|
|
157
|
-
|
|
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
|
-
|
|
162
|
-
|
|
163
|
-
|
|
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
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
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
|
-
|
|
178
|
-
|
|
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
|
|
182
|
-
export
|
|
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
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
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
|
-
|
|
192
|
-
|
|
193
|
-
|
|
280
|
+
```bash
|
|
281
|
+
passcontrol keygen instance # generates INSTANCE_SIGNING_KEY; set PASSCONTROL_ISSUER too
|
|
282
|
+
```
|
|
194
283
|
|
|
195
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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 "
|
|
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.
|
|
225
|
-
|
|
226
|
-
|
|
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
|
-
|
|
229
|
-
|
|
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
|
-
|
|
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
|
-
|
|
238
|
-
|
|
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
|
-
|
|
242
|
-
|
|
243
|
-
#
|
|
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
|
-
|
|
247
|
-
`
|
|
248
|
-
|
|
249
|
-
|
|
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
|
-
|
|
253
|
-
|
|
254
|
-
suspend/kill
|
|
255
|
-
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
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
|
-
|
|
285
|
-
|
|
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.
|
|
289
|
-
|
|
290
|
-
|
|
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
|
|
507
|
+
enforces it). Be kind — this is early.
|