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 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 setup # boots the self-hostable stack + opens the Control Tower
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
- `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.
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
- **Global CLI (recommended):**
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 --version # confirms the install
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
- 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.
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
- - 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
+ Then it proves it worked, before handing the terminal back:
142
143
 
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.
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
- > ⚠️ **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`.
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
- 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:
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 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
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
- 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.
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