passcontrol 0.7.2 → 0.9.0
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 +95 -61
- package/bin/passcontrol.mjs +745 -154
- package/cli/config.mjs +71 -9
- package/cli/gateway-wait.mjs +79 -0
- package/cli/login.mjs +55 -7
- package/cli/logout.mjs +243 -0
- package/cli/mcp/gateway.mjs +2 -0
- package/cli/menu-session.mjs +64 -0
- package/cli/menu.mjs +733 -0
- package/cli/passport-key-store.mjs +413 -0
- package/cli/protocols.d.mts +3 -0
- package/cli/protocols.mjs +23 -0
- package/cli/selftest.mjs +191 -0
- package/cli/sidecar.mjs +4 -0
- package/cli/verify.mjs +78 -3
- package/cli/visa-client.mjs +30 -2
- package/package.json +1 -1
- package/sdk/README.md +2 -1
- package/sdk/control.d.ts +38 -0
- package/sdk/control.js +32 -0
- package/sdk/index.d.ts +2 -2
- package/sdk/index.js +1 -1
- package/sdk/verify.d.ts +90 -1
- package/sdk/verify.js +83 -5
package/README.md
CHANGED
|
@@ -20,7 +20,11 @@ response is synthesized, by a keyless provider that never touches a vault.
|
|
|
20
20
|
|
|
21
21
|
The hosted demo includes the public **signed-receipt verifier** at
|
|
22
22
|
[`/verify/receipt`](https://passcontrol.vertias.eu/verify/receipt). Verification runs in your
|
|
23
|
-
browser; the receipt is never uploaded to PassControl.
|
|
23
|
+
browser; the receipt is never uploaded to PassControl. Release-by-release changes are collected
|
|
24
|
+
in the public [PassControl updates](https://passcontrol.vertias.eu/updates) archive. The
|
|
25
|
+
[AI agent security learning center](https://passcontrol.vertias.eu/learn) explains identity,
|
|
26
|
+
credential isolation, least privilege, budgets, revocation and audit evidence without treating
|
|
27
|
+
one product layer as the whole security stack.
|
|
24
28
|
|
|
25
29
|
**Hermes Agent:** the dashboard prints Hermes's current custom-provider YAML for a reveal-once
|
|
26
30
|
Direct Agent Key — the simplest path. For passport identity in Hermes, run the connector and
|
|
@@ -46,14 +50,16 @@ governed agent in ~15 minutes.
|
|
|
46
50
|
|
|
47
51
|
```bash
|
|
48
52
|
npm install -g passcontrol
|
|
49
|
-
passcontrol
|
|
50
|
-
passcontrol try # 60-second guided demo: governed call -> kill switch -> blocked
|
|
53
|
+
passcontrol login # approve once in your browser — this machine is set up
|
|
51
54
|
```
|
|
52
55
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
pipeline in your browser, keyless.
|
|
56
|
+
Nothing else to install: the npm package is the CLI, not the stack. `login` ends by making one
|
|
57
|
+
governed call and verifying its **signed receipt** against our published key, so you watch the
|
|
58
|
+
thing work rather than being told it does. Want a look first? The
|
|
59
|
+
[hosted demo](https://passcontrol.vertias.eu) runs the same pipeline in your browser, keyless.
|
|
60
|
+
|
|
61
|
+
Prefer to run the whole gateway yourself? `passcontrol setup` does that, and needs **Docker
|
|
62
|
+
Desktop, the Supabase CLI, and Node 18+** — see [Self-host](#self-host).
|
|
57
63
|
|
|
58
64
|
---
|
|
59
65
|
|
|
@@ -120,49 +126,54 @@ agent ──sign──▶ challenge ──visa──▶ ┌──────
|
|
|
120
126
|
|
|
121
127
|
## Install & first run
|
|
122
128
|
|
|
123
|
-
**
|
|
129
|
+
**Cloud — one command, and nothing else installed.** The published npm package is the CLI
|
|
130
|
+
only: no dashboard, no database, no Docker, no Supabase.
|
|
124
131
|
|
|
125
132
|
```bash
|
|
126
133
|
npm install -g passcontrol
|
|
127
|
-
passcontrol
|
|
128
|
-
passcontrol setup # prereq checks → fetches the stack → boots it → opens the dashboard
|
|
134
|
+
passcontrol login # opens your browser, you approve once, this machine is set up
|
|
129
135
|
```
|
|
130
136
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
version, free ports) and tells you exactly what to fix if something's missing.
|
|
137
|
+
`login` prints an 8-character code, copies it to your clipboard, and opens the approval page.
|
|
138
|
+
Paste it, press **Approve**, and the CLI generates an Ed25519 keypair *on your machine* — only
|
|
139
|
+
the public half is ever sent — creates your agent, and writes a working config. No 43-character
|
|
140
|
+
secrets travel between a browser and a terminal.
|
|
136
141
|
|
|
137
|
-
|
|
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
|
+
Then it proves it worked, before handing the terminal back:
|
|
142
143
|
|
|
143
|
-
|
|
144
|
-
|
|
144
|
+
```
|
|
145
|
+
✓ minted a visa with the passport this machine just created
|
|
146
|
+
✓ governed call ok — demo/demo-1, 12 tokens
|
|
147
|
+
✓ receipt verified against https://passcontrol.vertias.eu/.well-known/jwks.json
|
|
145
148
|
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
> runs (CI, piped output) get a generated password printed once. Deployed installs create
|
|
150
|
-
> accounts through normal signup, gated by `INVITE_CODE`.
|
|
149
|
+
Your agent is live. Anyone can check that call for themselves:
|
|
150
|
+
passcontrol verify receipt eyJhbGc… --issuer https://passcontrol.vertias.eu
|
|
151
|
+
```
|
|
151
152
|
|
|
152
|
-
|
|
153
|
-
|
|
153
|
+
That last line is the part nobody else has. It is a signed record of one governed call that a
|
|
154
|
+
stranger can verify offline against a public key, with no account and no access to your logs.
|
|
155
|
+
|
|
156
|
+
You type the code in yourself on purpose. **We will never send you an approval link with the
|
|
157
|
+
code already filled in**; if you receive one, it is not from us, and approving it would hand
|
|
158
|
+
whoever sent it a key to your workspace.
|
|
159
|
+
|
|
160
|
+
Now point an agent at it:
|
|
154
161
|
|
|
155
162
|
```bash
|
|
156
|
-
passcontrol
|
|
157
|
-
passcontrol
|
|
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
|
|
163
|
+
passcontrol sidecar # holds the passport, mints visas, forwards to Cloud
|
|
164
|
+
passcontrol env openhands # ready-to-paste settings for your agent
|
|
161
165
|
```
|
|
162
166
|
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
167
|
+
Finished with a machine? `passcontrol logout` revokes its control key and clears its
|
|
168
|
+
credentials, leaving your provider and model settings alone.
|
|
169
|
+
|
|
170
|
+
**Configuring by hand, or wiring up CI?** `passcontrol init` walks through gateway + passport +
|
|
171
|
+
provider/model with no browser, and plain environment variables work everywhere the config file
|
|
172
|
+
does.
|
|
173
|
+
|
|
174
|
+
**Want to run the whole thing yourself?** That is [Self-host](#self-host) below. `passcontrol
|
|
175
|
+
setup` is the self-host command, and it is the one that wants Docker and the Supabase CLI —
|
|
176
|
+
neither `login` nor the sidecar wants either.
|
|
166
177
|
|
|
167
178
|
> Working from a **source clone** instead of the global install? Everything below works as
|
|
168
179
|
> `npm run cli -- <command>`; after `npm link` in the clone, the short `passcontrol <command>` form
|
|
@@ -174,7 +185,7 @@ PassControl ships a local stdio MCP server. Store the passport once in the owner
|
|
|
174
185
|
profile, then let the CLI merge a secret-free entry into your client config:
|
|
175
186
|
|
|
176
187
|
```bash
|
|
177
|
-
passcontrol init --global
|
|
188
|
+
passcontrol login # or `passcontrol init --global` to do it by hand
|
|
178
189
|
passcontrol configure claude-desktop --write # or: cursor
|
|
179
190
|
# Claude Code: passcontrol configure claude-code prints its `claude mcp add` command
|
|
180
191
|
```
|
|
@@ -214,29 +225,6 @@ passcontrol sidecar # http://127.0.0.1:8788
|
|
|
214
225
|
passcontrol env openhands # prints ready-to-paste settings for your agent
|
|
215
226
|
```
|
|
216
227
|
|
|
217
|
-
### Passport identity on Cloud, from a machine with nothing installed
|
|
218
|
-
|
|
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:
|
|
221
|
-
|
|
222
|
-
```bash
|
|
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
|
|
226
|
-
```
|
|
227
|
-
|
|
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.
|
|
236
|
-
|
|
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
228
|
Point any OpenAI/Anthropic-compatible agent at the sidecar with a **dummy** key:
|
|
241
229
|
|
|
242
230
|
```bash
|
|
@@ -322,6 +310,8 @@ The primary interface is `passcontrol <command>`. Highlights:
|
|
|
322
310
|
|
|
323
311
|
| Need | Command |
|
|
324
312
|
|---|---|
|
|
313
|
+
| Set this machine up through the browser | `passcontrol login` |
|
|
314
|
+
| Revoke this machine's key and clear its credentials | `passcontrol logout` |
|
|
325
315
|
| Config, gateway status, suggested next steps | `passcontrol status` |
|
|
326
316
|
| Check local setup / mint a test visa | `passcontrol doctor --deep` |
|
|
327
317
|
| Compare CLI, gateway and database versions | `passcontrol version` |
|
|
@@ -403,6 +393,50 @@ Auth/SMTP checklist, five-minute Cron Trigger, local `workerd` preview, and owne
|
|
|
403
393
|
|
|
404
394
|
### Local (Docker) — the fastest path
|
|
405
395
|
|
|
396
|
+
```bash
|
|
397
|
+
npm install -g passcontrol
|
|
398
|
+
passcontrol setup # prereq checks → fetches the stack → boots it → opens the dashboard
|
|
399
|
+
```
|
|
400
|
+
|
|
401
|
+
`passcontrol setup` detects the global install and offers to clone the self-hostable stack (Supabase + Redis +
|
|
402
|
+
dashboard) into `~/passcontrol`, install its dependencies, and start it — one command from nothing
|
|
403
|
+
to a running Control Tower. It first checks your prerequisites (Docker running, Supabase CLI, Node
|
|
404
|
+
version, free ports) and tells you exactly what to fix if something's missing.
|
|
405
|
+
|
|
406
|
+
- Change the checkout location: `--app-dir <path>` or `PASSCONTROL_APP_ROOT=<path>`
|
|
407
|
+
- Non-interactive: `--yes`
|
|
408
|
+
- Skip opening the browser: `--no-open`
|
|
409
|
+
- Ports already taken by another local Supabase? `passcontrol setup --port-offset 100`
|
|
410
|
+
(offsets Supabase + Redis together, e.g. API `54421`, DB `54422`; the dashboard stays on `:3000`)
|
|
411
|
+
|
|
412
|
+
During `dev:stack` the seed step (`scripts/seed.mjs`) asks you to **choose an account email
|
|
413
|
+
and password**. Then log in to the Control Tower at **http://localhost:3000** with those.
|
|
414
|
+
|
|
415
|
+
> ⚠️ **No shared default credentials ship**, on any install. The account you create guards the
|
|
416
|
+
> real provider keys in your local Vault — and the stack stops being localhost-only the moment
|
|
417
|
+
> you reach it from another device (Tailscale, LAN), so choose a real password. Non-interactive
|
|
418
|
+
> runs (CI, piped output) get a generated password printed once. Deployed installs create
|
|
419
|
+
> accounts through normal signup, gated by `INVITE_CODE`.
|
|
420
|
+
|
|
421
|
+
Add a **non-critical** provider key in the Control Tower, issue a passport, and copy the one-time
|
|
422
|
+
`PASSPORT_ID` / `PASSPORT_SECRET`. Then, in your project directory:
|
|
423
|
+
|
|
424
|
+
```bash
|
|
425
|
+
passcontrol init # gateway + passport + provider/model → writes .passcontrol
|
|
426
|
+
passcontrol doctor --deep # verifies config, prerequisites, and mints a test visa
|
|
427
|
+
passcontrol version # CLI vs gateway vs database schema, in one table
|
|
428
|
+
passcontrol call "Say hello in 3 words"
|
|
429
|
+
passcontrol spend # confirms governed spend
|
|
430
|
+
```
|
|
431
|
+
|
|
432
|
+
You'll see a streamed response and an `ok` row in the dashboard Audit Log — the complete governed
|
|
433
|
+
loop: **passport → visa → vault key injection → proxied call → audit**. That last call uses your
|
|
434
|
+
real key from the local Vault, so start with a throwaway one.
|
|
435
|
+
|
|
436
|
+
> Working from a **source clone** instead of the global install? Everything below works as
|
|
437
|
+
> `npm run cli -- <command>`; after `npm link` in the clone, the short `passcontrol <command>` form
|
|
438
|
+
> works too.
|
|
439
|
+
|
|
406
440
|
`passcontrol setup` (above) is the one-command route. Under the hood it runs the bundled Docker
|
|
407
441
|
stack: local Supabase (Postgres + Vault + Auth), Redis-over-REST, migrations applied inside the DB
|
|
408
442
|
container, and a seeded dev user. Prereqs: **Docker Desktop, the Supabase CLI, Node 18+** — no host
|