passcontrol 0.7.2 → 0.8.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,8 @@ 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.
24
25
 
25
26
  **Hermes Agent:** the dashboard prints Hermes's current custom-provider YAML for a reveal-once
26
27
  Direct Agent Key — the simplest path. For passport identity in Hermes, run the connector and
@@ -46,14 +47,16 @@ governed agent in ~15 minutes.
46
47
 
47
48
  ```bash
48
49
  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
50
+ passcontrol login # approve once in your browser — this machine is set up
51
51
  ```
52
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.
53
+ Nothing else to install: the npm package is the CLI, not the stack. `login` ends by making one
54
+ governed call and verifying its **signed receipt** against our published key, so you watch the
55
+ thing work rather than being told it does. Want a look first? The
56
+ [hosted demo](https://passcontrol.vertias.eu) runs the same pipeline in your browser, keyless.
57
+
58
+ Prefer to run the whole gateway yourself? `passcontrol setup` does that, and needs **Docker
59
+ Desktop, the Supabase CLI, and Node 18+** — see [Self-host](#self-host).
57
60
 
58
61
  ---
59
62
 
@@ -120,49 +123,54 @@ agent ──sign──▶ challenge ──visa──▶ ┌──────
120
123
 
121
124
  ## Install & first run
122
125
 
123
- **Global CLI (recommended):**
126
+ **Cloud — one command, and nothing else installed.** The published npm package is the CLI
127
+ only: no dashboard, no database, no Docker, no Supabase.
124
128
 
125
129
  ```bash
126
130
  npm install -g passcontrol
127
- passcontrol --version # confirms the install
128
- passcontrol setup # prereq checks → fetches the stack → boots it → opens the dashboard
131
+ passcontrol login # opens your browser, you approve once, this machine is set up
129
132
  ```
130
133
 
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.
134
+ `login` prints an 8-character code, copies it to your clipboard, and opens the approval page.
135
+ Paste it, press **Approve**, and the CLI generates an Ed25519 keypair *on your machine* — only
136
+ the public half is ever sent — creates your agent, and writes a working config. No 43-character
137
+ secrets travel between a browser and a terminal.
136
138
 
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`)
139
+ Then it proves it worked, before handing the terminal back:
142
140
 
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.
141
+ ```
142
+ ✓ minted a visa with the passport this machine just created
143
+ ✓ governed call ok — demo/demo-1, 12 tokens
144
+ ✓ receipt verified against https://passcontrol.vertias.eu/.well-known/jwks.json
145
145
 
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`.
146
+ Your agent is live. Anyone can check that call for themselves:
147
+ passcontrol verify receipt eyJhbGc… --issuer https://passcontrol.vertias.eu
148
+ ```
151
149
 
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:
150
+ That last line is the part nobody else has. It is a signed record of one governed call that a
151
+ stranger can verify offline against a public key, with no account and no access to your logs.
152
+
153
+ You type the code in yourself on purpose. **We will never send you an approval link with the
154
+ code already filled in**; if you receive one, it is not from us, and approving it would hand
155
+ whoever sent it a key to your workspace.
156
+
157
+ Now point an agent at it:
154
158
 
155
159
  ```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
160
+ passcontrol sidecar # holds the passport, mints visas, forwards to Cloud
161
+ passcontrol env openhands # ready-to-paste settings for your agent
161
162
  ```
162
163
 
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.
164
+ Finished with a machine? `passcontrol logout` revokes its control key and clears its
165
+ credentials, leaving your provider and model settings alone.
166
+
167
+ **Configuring by hand, or wiring up CI?** `passcontrol init` walks through gateway + passport +
168
+ provider/model with no browser, and plain environment variables work everywhere the config file
169
+ does.
170
+
171
+ **Want to run the whole thing yourself?** That is [Self-host](#self-host) below. `passcontrol
172
+ setup` is the self-host command, and it is the one that wants Docker and the Supabase CLI —
173
+ neither `login` nor the sidecar wants either.
166
174
 
167
175
  > Working from a **source clone** instead of the global install? Everything below works as
168
176
  > `npm run cli -- <command>`; after `npm link` in the clone, the short `passcontrol <command>` form
@@ -174,7 +182,7 @@ PassControl ships a local stdio MCP server. Store the passport once in the owner
174
182
  profile, then let the CLI merge a secret-free entry into your client config:
175
183
 
176
184
  ```bash
177
- passcontrol init --global
185
+ passcontrol login # or `passcontrol init --global` to do it by hand
178
186
  passcontrol configure claude-desktop --write # or: cursor
179
187
  # Claude Code: passcontrol configure claude-code prints its `claude mcp add` command
180
188
  ```
@@ -214,29 +222,6 @@ passcontrol sidecar # http://127.0.0.1:8788
214
222
  passcontrol env openhands # prints ready-to-paste settings for your agent
215
223
  ```
216
224
 
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
225
  Point any OpenAI/Anthropic-compatible agent at the sidecar with a **dummy** key:
241
226
 
242
227
  ```bash
@@ -322,6 +307,8 @@ The primary interface is `passcontrol <command>`. Highlights:
322
307
 
323
308
  | Need | Command |
324
309
  |---|---|
310
+ | Set this machine up through the browser | `passcontrol login` |
311
+ | Revoke this machine's key and clear its credentials | `passcontrol logout` |
325
312
  | Config, gateway status, suggested next steps | `passcontrol status` |
326
313
  | Check local setup / mint a test visa | `passcontrol doctor --deep` |
327
314
  | Compare CLI, gateway and database versions | `passcontrol version` |
@@ -403,6 +390,50 @@ Auth/SMTP checklist, five-minute Cron Trigger, local `workerd` preview, and owne
403
390
 
404
391
  ### Local (Docker) — the fastest path
405
392
 
393
+ ```bash
394
+ npm install -g passcontrol
395
+ passcontrol setup # prereq checks → fetches the stack → boots it → opens the dashboard
396
+ ```
397
+
398
+ `passcontrol setup` detects the global install and offers to clone the self-hostable stack (Supabase + Redis +
399
+ dashboard) into `~/passcontrol`, install its dependencies, and start it — one command from nothing
400
+ to a running Control Tower. It first checks your prerequisites (Docker running, Supabase CLI, Node
401
+ version, free ports) and tells you exactly what to fix if something's missing.
402
+
403
+ - Change the checkout location: `--app-dir <path>` or `PASSCONTROL_APP_ROOT=<path>`
404
+ - Non-interactive: `--yes`
405
+ - Skip opening the browser: `--no-open`
406
+ - Ports already taken by another local Supabase? `passcontrol setup --port-offset 100`
407
+ (offsets Supabase + Redis together, e.g. API `54421`, DB `54422`; the dashboard stays on `:3000`)
408
+
409
+ During `dev:stack` the seed step (`scripts/seed.mjs`) asks you to **choose an account email
410
+ and password**. Then log in to the Control Tower at **http://localhost:3000** with those.
411
+
412
+ > ⚠️ **No shared default credentials ship**, on any install. The account you create guards the
413
+ > real provider keys in your local Vault — and the stack stops being localhost-only the moment
414
+ > you reach it from another device (Tailscale, LAN), so choose a real password. Non-interactive
415
+ > runs (CI, piped output) get a generated password printed once. Deployed installs create
416
+ > accounts through normal signup, gated by `INVITE_CODE`.
417
+
418
+ Add a **non-critical** provider key in the Control Tower, issue a passport, and copy the one-time
419
+ `PASSPORT_ID` / `PASSPORT_SECRET`. Then, in your project directory:
420
+
421
+ ```bash
422
+ passcontrol init # gateway + passport + provider/model → writes .passcontrol
423
+ passcontrol doctor --deep # verifies config, prerequisites, and mints a test visa
424
+ passcontrol version # CLI vs gateway vs database schema, in one table
425
+ passcontrol call "Say hello in 3 words"
426
+ passcontrol spend # confirms governed spend
427
+ ```
428
+
429
+ You'll see a streamed response and an `ok` row in the dashboard Audit Log — the complete governed
430
+ loop: **passport → visa → vault key injection → proxied call → audit**. That last call uses your
431
+ real key from the local Vault, so start with a throwaway one.
432
+
433
+ > Working from a **source clone** instead of the global install? Everything below works as
434
+ > `npm run cli -- <command>`; after `npm link` in the clone, the short `passcontrol <command>` form
435
+ > works too.
436
+
406
437
  `passcontrol setup` (above) is the one-command route. Under the hood it runs the bundled Docker
407
438
  stack: local Supabase (Postgres + Vault + Auth), Redis-over-REST, migrations applied inside the DB
408
439
  container, and a seeded dev user. Prereqs: **Docker Desktop, the Supabase CLI, Node 18+** — no host
@@ -22,6 +22,7 @@ import {
22
22
  formatChallengeError,
23
23
  formatProxyError,
24
24
  globalConfigPath,
25
+ mergeConfigFile,
25
26
  heading,
26
27
  ok,
27
28
  redact,
@@ -54,6 +55,8 @@ import { importCompletionMessage, noAgentCreateMessage } from "../cli/workspace-
54
55
  import { checkForUpdate } from "../cli/update-check.mjs";
55
56
  import { startSidecar } from "../cli/sidecar.mjs";
56
57
  import { loginCommand } from "../cli/login.mjs";
58
+ import { logoutCommand } from "../cli/logout.mjs";
59
+ import { proveItWorks } from "../cli/selftest.mjs";
57
60
  import {
58
61
  checkIssuerPublishesKey,
59
62
  generateInstanceKey,
@@ -75,14 +78,6 @@ const CLI_VERSION = (() => {
75
78
  }
76
79
  })();
77
80
 
78
- // Fixed demo credentials for `passcontrol try` — LOCAL demo stack ONLY. The demo
79
- // passport can only ever reach the keyless `demo` provider (no real key, no cost,
80
- // no real upstream); the demo provider + these seeds exist only when the stack is
81
- // brought up with PASSCONTROL_DEMO=1. Hardcoding them is safe, like the seeded dev
82
- // password — they grant nothing in a real deployment.
83
- // App-side source of truth: lib/demo/identity.ts (duplicated here to keep the shipped plain-ESM CLI transpilation-free).
84
- const DEMO_PASSPORT_ID = "kZCFp7d2x4VDruiulJ21gogYbczBDAGZa-OuwR3qgh8";
85
- const DEMO_PASSPORT_SECRET = "XqsVuXtmWiu6bKEmmqov2Q2TwkOVdzlZMWR-NWubSKo";
86
81
  const DEMO_API_KEY = "pc_demolocaltrydemolocaltrydemolocaltry0000";
87
82
  const DASHBOARD_STATE_FILE = "local-dashboard.json";
88
83
  const APP_STATE_FILE = "app.json";
@@ -153,7 +148,6 @@ ${heading("Usage:")}
153
148
  ${heading("Quick start")}
154
149
  Cloud. No Docker, no database — this CLI is the only thing you install.
155
150
  ${cmd} login [--project] sign in through your browser and set this machine up
156
- ${cmd} try run the 60-second keyless guided demo
157
151
  ${cmd} call "hi" mint a visa and make a governed model call
158
152
  ${cmd} mcp passport identity for Claude Desktop, Cursor, Claude Code
159
153
  ${cmd} sidecar [--port 8788] [--allow-connect host[,host]]
@@ -165,11 +159,13 @@ ${heading("Operate")}
165
159
  ${cmd} version [--json] CLI, gateway and database schema versions
166
160
  ${cmd} doctor [--deep] [--fix] diagnose setup and repair a stopped dashboard
167
161
  ${cmd} open open the Control Tower in a browser
162
+ ${cmd} logout [--revoke-agent] revoke this machine's key and clear its credentials
168
163
  ${cmd} init [--global] configure by hand, without a browser
169
164
 
170
165
  ${heading("Manage")}
171
166
  ${cmd} agent list [--json] list agents
172
- ${cmd} agent create <name> create an agent passport
167
+ ${cmd} agent create <name> [--write]
168
+ create an agent passport (--write saves it here)
173
169
  ${cmd} agent rotate <id> [--grace <seconds>]
174
170
  rotate locally and reveal the new secret once
175
171
  ${cmd} agent suspend <id> suspend an agent
@@ -228,6 +224,7 @@ function agentUsage() {
228
224
  ${heading("Usage:")}
229
225
  ${cmd} agent list
230
226
  ${cmd} agent create <name> [--provider <provider>] [--scope <model-pattern>]
227
+ [--write [--project] [--force]]
231
228
  ${cmd} agent rotate <id> [--grace <seconds>]
232
229
  ${cmd} agent suspend <id>
233
230
  ${cmd} agent resume <id>
@@ -235,6 +232,7 @@ ${heading("Usage:")}
235
232
 
236
233
  ${heading("Examples")}
237
234
  ${cmd} agent create prod-summarizer --provider anthropic --scope 'claude-*'
235
+ ${cmd} agent create this-box --write # save the passport here, never print it
238
236
  ${cmd} agent rotate <id> --grace 3600
239
237
  ${cmd} agent suspend <id>
240
238
 
@@ -1370,111 +1368,6 @@ async function callCommand(rest, opts) {
1370
1368
  ok("done - check the dashboard audit log + spend for this call.");
1371
1369
  }
1372
1370
 
1373
- // `passcontrol try` — the 60-second, no-key, no-accounts experience. Uses the
1374
- // seeded demo passport (demo scope only) to make a GOVERNED call through the
1375
- // keyless `demo` provider, then arms the kill switch to show the same call
1376
- // blocked. Everything is real (visa, scope, budget, kill) except the model.
1377
- async function tryCommand() {
1378
- // Covers the demo proxy call AND the kill-switch PUT below, which builds its
1379
- // own control-plane URL rather than going through the guarded `api()`.
1380
- const gateway = requirePassportGateway(config);
1381
- const demo = { gateway, passportId: DEMO_PASSPORT_ID, passportSecret: DEMO_PASSPORT_SECRET };
1382
-
1383
- const demoCall = async () => {
1384
- const { visa } = await mintVisa(demo);
1385
- return fetch(`${gateway}/api/v1/demo/chat/completions`, {
1386
- method: "POST",
1387
- headers: { "content-type": "application/json", authorization: `Bearer ${visa}` },
1388
- body: JSON.stringify({
1389
- model: "demo-1",
1390
- max_tokens: 64,
1391
- messages: [{ role: "user", content: "Say hi in exactly three words" }],
1392
- }),
1393
- });
1394
- };
1395
- const setKill = async (armed) => {
1396
- const res = await fetch(`${gateway}/api/control/v1/kill-switch`, {
1397
- method: "PUT",
1398
- headers: {
1399
- "content-type": "application/json",
1400
- authorization: `Bearer ${DEMO_API_KEY}`,
1401
- "idempotency-key": crypto.randomUUID(),
1402
- },
1403
- body: JSON.stringify({ armed }),
1404
- });
1405
- if (!res.ok) throw new Error(`kill-switch ${armed ? "on" : "off"} → ${res.status} ${await res.text()}`);
1406
- };
1407
-
1408
- console.log(`${heading("PassControl — 60-second try (no provider key, no accounts)")}\n`);
1409
- step(`gateway: ${gateway}`);
1410
-
1411
- // 1. Governed, keyless call.
1412
- let res;
1413
- try {
1414
- res = await demoCall();
1415
- } catch (e) {
1416
- const msg = e?.message || String(e);
1417
- if (/unknown_passport|Challenge failed|challenge/i.test(msg)) {
1418
- // Gateway reachable, but the demo passport isn't seeded in ITS database.
1419
- fail(`The gateway is up, but the demo passport isn't seeded here (${msg}).`);
1420
- step("Seed + enable the demo on this stack:");
1421
- step(" PASSCONTROL_DEMO=1 npm run dev:stack # seeds the demo passport + control key");
1422
- step(" PASSCONTROL_DEMO=1 npm run dev:docker # enables the keyless demo provider");
1423
- } else {
1424
- fail(`Could not reach the gateway at ${gateway} (${msg}).`);
1425
- step(`Nothing installed yet? The same pipeline runs keyless in your browser: ${HOSTED_DEMO_URL}`);
1426
- step("To run it here instead, bring the local demo stack up first:");
1427
- step(" PASSCONTROL_DEMO=1 npm run dev:stack # Supabase + Redis + migrate + seed the demo passport");
1428
- step(" PASSCONTROL_DEMO=1 npm run dev:docker # start the gateway with the demo provider enabled");
1429
- }
1430
- process.exitCode = 1;
1431
- return;
1432
- }
1433
- if (res.status === 404) {
1434
- fail("The demo provider is not enabled on this gateway.");
1435
- step("Start it with PASSCONTROL_DEMO=1 (e.g. `PASSCONTROL_DEMO=1 npm run dev:docker`).");
1436
- process.exitCode = 1;
1437
- return;
1438
- }
1439
- if (res.status === 401 || res.status === 403) {
1440
- fail(`Demo passport not accepted (${res.status}). Re-seed the demo stack: PASSCONTROL_DEMO=1 npm run seed`);
1441
- process.exitCode = 1;
1442
- return;
1443
- }
1444
- if (!res.ok) {
1445
- fail(`Unexpected ${res.status}: ${await res.text()}`);
1446
- process.exitCode = 1;
1447
- return;
1448
- }
1449
-
1450
- const json = await res.json().catch(() => ({}));
1451
- const text = json?.choices?.[0]?.message?.content ?? JSON.stringify(json);
1452
- const usage = json?.usage ?? {};
1453
- ok("Governed keyless call succeeded — the passport signed the challenge, the gateway issued a short-lived visa and enforced scope + budget, and no key was needed:");
1454
- console.log(`\n ${text}\n`);
1455
- step(`tokens: ${usage.total_tokens ?? "?"} (prompt ${usage.prompt_tokens ?? "?"} + completion ${usage.completion_tokens ?? "?"})`);
1456
-
1457
- // 2. Kill switch blocks the very next call.
1458
- console.log("");
1459
- step("arming the kill switch…");
1460
- await setKill(true);
1461
- try {
1462
- const blocked = await demoCall();
1463
- if (blocked.status === 403) {
1464
- ok(`Kill switch works — the same call is now ${blocked.status} blocked_suspended.`);
1465
- } else {
1466
- fail(`Expected 403 after arming the kill switch, got ${blocked.status}.`);
1467
- }
1468
- } finally {
1469
- await setKill(false);
1470
- step("kill switch disarmed.");
1471
- }
1472
-
1473
- console.log("");
1474
- ok("That's PassControl: cryptographic identity → short-lived visa → governed call → instant kill. The provider key never touched the agent.");
1475
- step("Next: add a real provider key in the Control Tower and re-point your agent at the gateway (see the README).");
1476
- }
1477
-
1478
1371
  async function api(method, pathPart, body, { timeoutMs } = {}) {
1479
1372
  // Destination first, key second — same order and same reason as the SDK's
1480
1373
  // ControlClient. `config.gateway` is whatever PASSCONTROL_GATEWAY said, and
@@ -1567,10 +1460,39 @@ async function agentCommand(rest, opts) {
1567
1460
  scopes: [{ provider, models: [scopeModel] }],
1568
1461
  });
1569
1462
  ok(`created agent ${created.id} (${created.name})`);
1463
+
1464
+ // --write puts the passport somewhere durable INSTEAD of on the terminal.
1465
+ // Ordering matters: the file is written before anything is printed, so a
1466
+ // failure to write can still fall through to printing. The reverse — print
1467
+ // suppressed, write failed — loses the key permanently.
1468
+ if (opts.write) {
1469
+ const target = opts.project ? path.join(process.cwd(), CONFIG_FILE) : globalConfigPath();
1470
+ // Refuse rather than prompt. This command is run non-interactively (CI,
1471
+ // provisioning scripts) at least as often as by hand, and PassControl has
1472
+ // no copy of whatever is already in that file — an overwrite is not
1473
+ // undoable by us or by anyone.
1474
+ const existing = fs.existsSync(target) ? fs.readFileSync(target, "utf8") : "";
1475
+ if (/^PASSPORT_SECRET=(.+)$/mu.exec(existing)?.[1]?.trim() && !opts.force) {
1476
+ throw new Error(
1477
+ `${target} already holds a passport secret, and PassControl has no copy of it.\n` +
1478
+ " Re-run with --force to replace it, or without --write to print the new one instead."
1479
+ );
1480
+ }
1481
+ mergeConfigFile(target, { PASSPORT_ID: passportId, PASSPORT_SECRET: b64url(priv) });
1482
+ ok(`wrote the passport to ${target} — it was not printed`);
1483
+ break;
1484
+ }
1485
+
1570
1486
  step("Store these - the secret is shown once and is the agent's passport:");
1571
1487
  console.log(` PASSPORT_ID=${passportId}`);
1572
1488
  console.log(` PASSPORT_SECRET=${b64url(priv)}`);
1573
- step("Paste them into .passcontrol, then run `passcontrol call \"hi\"`.");
1489
+ // The paste is the fallback, not the lesson. Copying a private key between
1490
+ // a browser, a clipboard and a file is how a passport secret once ended up
1491
+ // in a Hermes `api_key` field — and for a second machine it is not even
1492
+ // necessary: `login` there mints its own passport and copies nothing.
1493
+ step("Running this agent on ANOTHER machine? Run `passcontrol login` there instead —");
1494
+ step("it creates its own passport locally and no secret is ever copied.");
1495
+ step("Otherwise store the secret like a password, or re-run with --write to save it here.");
1574
1496
  break;
1575
1497
  }
1576
1498
  case "suspend":
@@ -1621,6 +1543,10 @@ async function agentCommand(rest, opts) {
1621
1543
  ? `The OLD key keeps working until ${until}. Both keys authenticate until then — deploy the new one before it passes.`
1622
1544
  : "The old key stops working immediately."
1623
1545
  );
1546
+ // No --write here, deliberately: see the note above the reveal. What this
1547
+ // CAN say is that a machine you control does not need the rotation at all.
1548
+ step("Rotating only to set up a new machine? `passcontrol login` there creates its own");
1549
+ step("passport instead, and leaves this one working everywhere it already runs.");
1624
1550
  break;
1625
1551
  }
1626
1552
  default:
@@ -2150,14 +2076,24 @@ async function doctorCommand(opts = {}) {
2150
2076
  printSystemHealthDiagnostic(await fetchSystemHealth());
2151
2077
  await runLocalPrerequisiteChecks({ report: true });
2152
2078
  if (config.passportId && config.passportSecret) {
2153
- try {
2154
- const visa = await mintVisa(config);
2155
- ok(`Visa mint works (expires in ${visa.expires_in ?? 300}s)`);
2156
- } catch (error) {
2157
- fail(`Visa mint failed: ${error.message}`);
2158
- }
2079
+ // The whole chain, not just the mint. "Visa mint works" proves the passport
2080
+ // authenticates and says nothing about scope, budget, the proxy or receipts —
2081
+ // so the most useful diagnostic in the tool was the one thing `login` already
2082
+ // did better. Shared implementation (cli/selftest.mjs) rather than a second
2083
+ // copy, because two copies of a five-leg check drift.
2084
+ const proof = await proveItWorks({
2085
+ origin: requirePassportGateway(config),
2086
+ passportId: config.passportId,
2087
+ passportSecret: config.passportSecret,
2088
+ apiKey: config.apiKey,
2089
+ fetchImpl: fetch,
2090
+ });
2091
+ if (proof.receipt === "verified") ok("End to end: governed call made, receipt verified");
2092
+ else if (proof.call) step("Governed call works; its receipt was not verified (see above)");
2093
+ else if (proof.visa) step("Passport authenticates; no governed call was possible here");
2094
+ else fail("Passport could not authenticate — see the reason above");
2159
2095
  } else {
2160
- step("Skipping visa mint check: no passport configured.");
2096
+ step("Skipping the end-to-end check: no passport configured.");
2161
2097
  }
2162
2098
 
2163
2099
  if (config.apiKey) {
@@ -2482,6 +2418,9 @@ async function main() {
2482
2418
  // through startDashboard, which clones the self-host repo.
2483
2419
  await loginCommand(opts, { openUrl, promptLine, confirmYes });
2484
2420
  break;
2421
+ case "logout":
2422
+ await logoutCommand(opts, { confirmYes });
2423
+ break;
2485
2424
  case "init":
2486
2425
  await initCommand(opts);
2487
2426
  break;
@@ -2513,8 +2452,18 @@ async function main() {
2513
2452
  await callCommand(commandRest, opts);
2514
2453
  break;
2515
2454
  case "try":
2516
- await tryCommand();
2517
- break;
2455
+ // Removed, not silently dropped. `passcontrol try` is named in the help
2456
+ // text and README of every published release up to this one, so somebody
2457
+ // is following a page that still lists it. `Unknown command "try"` reads
2458
+ // as a broken install; this reads as a changelog.
2459
+ //
2460
+ // CLI_VERSION, never a typed literal — tests/site-metadata.test.ts exists
2461
+ // because advertised version strings drift the moment they are hand-written.
2462
+ throw new Error(
2463
+ `\`passcontrol try\` was removed in ${CLI_VERSION}.\n` +
2464
+ " `passcontrol login` now does the same thing with YOUR agent rather than a\n" +
2465
+ " shared demo one: a governed call and a signed receipt you can verify."
2466
+ );
2518
2467
  case "sidecar":
2519
2468
  await sidecarCommand(commandRest, opts);
2520
2469
  break;
package/cli/login.mjs CHANGED
@@ -51,6 +51,7 @@ import {
51
51
  step,
52
52
  warn,
53
53
  } from "./config.mjs";
54
+ import { proveItWorks } from "./selftest.mjs";
54
55
 
55
56
  export { CLOUD_GATEWAY };
56
57
 
@@ -194,7 +195,17 @@ const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
194
195
  * Honours the server's `interval` and backs off on `slow_down`, so the poll rate
195
196
  * is the server's decision and can be widened without shipping a new CLI.
196
197
  */
197
- async function pollForGrant(origin, deviceCode, { interval, expiresIn, fetchImpl, now = Date.now }) {
198
+ async function pollForGrant(
199
+ origin,
200
+ deviceCode,
201
+ // `now` and `wait` are a matched pair, and injecting only one is worse than
202
+ // injecting neither: a fake clock with a real sleep still burns wall time,
203
+ // and a real clock with a fake sleep spins the loop against a deadline that
204
+ // never moves. TRANSPORT_GRACE_MS below is ninety REAL seconds, so a test
205
+ // that drives the give-up path without both of these sleeps through all
206
+ // ninety of them — which is exactly what this file used to do.
207
+ { interval, expiresIn, fetchImpl, now = Date.now, wait = sleep }
208
+ ) {
198
209
  const deadline = now() + expiresIn * 1000;
199
210
  let waitMs = Math.max(500, interval * 1000);
200
211
  // A transport failure is NOT fatal here, and this is the one place in the flow
@@ -215,7 +226,7 @@ async function pollForGrant(origin, deviceCode, { interval, expiresIn, fetchImpl
215
226
  let transportFailures = 0;
216
227
  let failingSince = 0;
217
228
  while (now() < deadline) {
218
- await sleep(waitMs);
229
+ await wait(waitMs);
219
230
  let res;
220
231
  try {
221
232
  res = await postJson(`${origin}/api/auth/device/token`, { device_code: deviceCode }, { fetchImpl });
@@ -271,7 +282,13 @@ async function control(origin, apiKey, method, path, body, fetchImpl = fetch) {
271
282
  if (!res.ok) {
272
283
  throw new Error(`Control plane refused ${method} ${path} (${res.status}).`);
273
284
  }
274
- return parsed;
285
+ // Every control route answers `{ data: ... }` (lib/control/respond.ts), and
286
+ // bin/passcontrol.mjs's own `api()` has always unwrapped it. This helper did
287
+ // not, and the callers below then reached for `.agents` and `.id` one level
288
+ // too high — so the agent list was permanently empty and a created agent's id
289
+ // was permanently undefined. Unwrapped HERE rather than at each call site, so
290
+ // the next route this file consumes cannot reintroduce it.
291
+ return parsed && typeof parsed === "object" && "data" in parsed ? parsed.data : parsed;
275
292
  }
276
293
 
277
294
  /**
@@ -377,6 +394,12 @@ export async function loginCommand(opts = {}, deps = {}) {
377
394
  const openUrl = deps.openUrl ?? (() => {});
378
395
  const confirm = deps.confirmYes ?? (async (_q, o = {}) => o.default !== false);
379
396
  const promptLine = deps.promptLine ?? (async (_q, fallback) => fallback);
397
+ // Only the poll loop reads these, and only a test passes them. Kept on `deps`
398
+ // beside `fetch` rather than on `opts`, because they are seams for the caller,
399
+ // not options for the operator — there is no flag that makes login lie about
400
+ // the time.
401
+ const now = deps.now ?? Date.now;
402
+ const wait = deps.sleep ?? sleep;
380
403
 
381
404
  // Validate the destination BEFORE anything is requested — the ordering mintVisa
382
405
  // uses. A rejected gateway must cost zero sockets.
@@ -446,6 +469,8 @@ export async function loginCommand(opts = {}, deps = {}) {
446
469
  interval: Number(started.body.interval ?? 1),
447
470
  expiresIn: Number(started.body.expires_in ?? 600),
448
471
  fetchImpl,
472
+ now,
473
+ wait,
449
474
  });
450
475
  ok("approved");
451
476
 
@@ -454,7 +479,7 @@ export async function loginCommand(opts = {}, deps = {}) {
454
479
  // The keypair is generated HERE and only the PUBLIC half is sent. The gateway
455
480
  // has never held a passport private key; this command must not be the first
456
481
  // thing to change that.
457
- const agents = (await control(origin, grant.api_key, "GET", "/agents", null, fetchImpl))?.agents ?? [];
482
+ const agents = (await control(origin, grant.api_key, "GET", "/agents", null, fetchImpl)) ?? [];
458
483
  let agentId = null;
459
484
  if (agents.length > 0 && !opts.new) {
460
485
  step(`This workspace has ${agents.length} agent(s).`);
@@ -482,7 +507,17 @@ export async function loginCommand(opts = {}, deps = {}) {
482
507
  const created = await control(origin, grant.api_key, "POST", "/agents", {
483
508
  name: clientName,
484
509
  passportPubkey: passportId,
485
- scopes: [{ provider: "anthropic", models: ["claude-*"] }],
510
+ // The demo scope is what makes `proveItWorks` below possible, and it is
511
+ // here rather than added-then-removed for one reason: a brand-new tenant
512
+ // has NO provider key in Vault, so the keyless demo provider is the only
513
+ // call this agent can legally make on its first day. It reaches a
514
+ // synthesized response, never `get_provider_key`, and never forwards
515
+ // anywhere — so it grants no spend and no upstream reach. It also leaves
516
+ // every agent able to self-test forever, which `doctor` can lean on.
517
+ scopes: [
518
+ { provider: "demo", models: ["*"] },
519
+ { provider: "anthropic", models: ["claude-*"] },
520
+ ],
486
521
  }, fetchImpl);
487
522
  agentId = created?.id ?? null;
488
523
  ok(`created agent ${created?.name ?? clientName}`);
@@ -512,7 +547,15 @@ export async function loginCommand(opts = {}, deps = {}) {
512
547
  warnIfShadowed(target);
513
548
 
514
549
  step("");
515
- step('Try it: passcontrol call "hi"');
550
+ const proof = await proveItWorks({
551
+ origin,
552
+ passportId,
553
+ passportSecret,
554
+ apiKey: grant.api_key,
555
+ fetchImpl,
556
+ });
557
+
558
+ step("");
516
559
  step(`The key is listed in Settings as "CLI on ${clientName}" and can be revoked there.`);
517
- return { agentId, passportId, target };
560
+ return { agentId, passportId, target, proof };
518
561
  }
package/cli/logout.mjs ADDED
@@ -0,0 +1,199 @@
1
+ // `passcontrol logout` — undo a login, on both sides.
2
+ //
3
+ // Until now there was no way to undo `passcontrol login`, and no CLI path to
4
+ // revoke a control key at all: `revokeApiKey` is a dashboard action. The manual
5
+ // equivalent was two halves nobody remembers as a pair — revoke the key in
6
+ // Settings AND delete the config — and doing one without the other leaves either
7
+ // a live write-scoped key on the tenant (create/suspend/revoke agents, rotate
8
+ // passports, arm the kill switch) or a passport private key sitting on disk.
9
+ //
10
+ // ── The ordering here is policy ─────────────────────────────────────────────
11
+ //
12
+ // resolve → look up the agent → decide about the agent → revoke the agent →
13
+ // revoke the control key → blank the file.
14
+ //
15
+ // The control key is revoked LAST because it is the credential doing all of the
16
+ // work above; revoking it first turns every remaining step into a 401. The file
17
+ // is blanked last of all, and — this is the part worth stating — it is blanked
18
+ // EVEN IF the server steps failed. The operator asked to log out. Deciding on
19
+ // their behalf that a live key elsewhere is a reason to leave a private key on
20
+ // their disk gets the trade backwards; the honest response is to clear the
21
+ // machine and say plainly that the key is still live.
22
+ import fs from "node:fs";
23
+ import path from "node:path";
24
+ import {
25
+ CONFIG_FILE,
26
+ config,
27
+ configSources,
28
+ globalConfigPath,
29
+ mergeConfigFile,
30
+ ok,
31
+ requireControlGateway,
32
+ step,
33
+ warn,
34
+ } from "./config.mjs";
35
+
36
+ /**
37
+ * The file that ACTUALLY holds the passport, not the one login would have
38
+ * written today.
39
+ *
40
+ * Mirroring login's `--project ? cwd : global` choice would be the obvious
41
+ * implementation and the wrong one: a user who logged in with `--project` and
42
+ * then runs a bare `logout` would be told their machine was cleared while the
43
+ * project `.passcontrol` still authenticates. That is `warnIfShadowed`'s failure
44
+ * in reverse — right result, wrong file — and it is worse here, because the
45
+ * whole point of the command is that nothing is left behind.
46
+ *
47
+ * `configSources` is pushed global-then-project and merged in that order, so the
48
+ * LAST source defining the key is the one that wins at resolution time.
49
+ */
50
+ export function credentialFile(opts = {}, { sources = configSources, cwd = process.cwd() } = {}) {
51
+ if (opts.project) return path.join(cwd, CONFIG_FILE);
52
+ if (opts.global) return globalConfigPath();
53
+ const holder = [...sources]
54
+ .reverse()
55
+ .find((source) => String(source?.values?.PASSPORT_SECRET ?? "").trim());
56
+ return holder?.path ?? null;
57
+ }
58
+
59
+ async function control(origin, apiKey, method, route, fetchImpl) {
60
+ const res = await fetchImpl(`${origin}/api/control/v1${route}`, {
61
+ method,
62
+ headers: { authorization: `Bearer ${apiKey}` },
63
+ });
64
+ const parsed = await res.json().catch(() => null);
65
+ if (!res.ok) {
66
+ const error = new Error(`${method} ${route} answered ${res.status}`);
67
+ error.status = res.status;
68
+ error.code = parsed?.error ?? null;
69
+ throw error;
70
+ }
71
+ // `{ data: ... }` — see lib/control/respond.ts and the note in cli/login.mjs.
72
+ // Reading the envelope instead of the payload is why the first real run of
73
+ // this command could not name the agent it was logging out of.
74
+ return parsed && typeof parsed === "object" && "data" in parsed ? parsed.data : parsed;
75
+ }
76
+
77
+ export async function logoutCommand(opts = {}, deps = {}) {
78
+ const fetchImpl = deps.fetch ?? fetch;
79
+ const confirm = deps.confirmYes ?? (async (_q, o = {}) => o.default !== false);
80
+ const warnings = [];
81
+
82
+ const target = credentialFile(opts);
83
+ if (!target || !fs.existsSync(target)) {
84
+ step("No passport is configured on this machine, so there is nothing to clear.");
85
+ return { target: null, keyRevoked: false, agentRevoked: false, agent: null, warnings };
86
+ }
87
+
88
+ // ── Ask before destroying the passport, BEFORE touching anything ─────────
89
+ //
90
+ // `login` and `logout` differ by ONE CHARACTER, and only one of them asks.
91
+ // That asymmetry is not theoretical: this guard exists because a `logout` run
92
+ // as a smoke test, against the real config rather than an isolated one,
93
+ // blanked a working Cloud passport in the time it took to press enter.
94
+ // PassControl has never held that private key, so nothing could give it back.
95
+ //
96
+ // It sits here — ahead of every server call — rather than beside the write it
97
+ // guards. Confirming later would mean a declined logout that had already
98
+ // revoked the control key and possibly the agent: a half state the operator
99
+ // never asked for and cannot easily read. Answering "no" to a destructive
100
+ // prompt should mean nothing happened, so nothing has yet.
101
+ if (!opts.yes) {
102
+ const holdsPassport = /^PASSPORT_SECRET=(.+)$/mu.exec(fs.readFileSync(target, "utf8"))?.[1]?.trim();
103
+ if (holdsPassport) {
104
+ warn(`${target} holds a passport secret, and PassControl has no copy of it.`);
105
+ step("Clearing it is permanent — anything still using that passport keeps working, but");
106
+ step("this machine can never authenticate as it again.");
107
+ if (!(await confirm("Log out of this machine? [y/N] ", { default: false }))) {
108
+ step("Left everything as it was.");
109
+ return { target: null, keyRevoked: false, agentRevoked: false, agent: null, warnings, cancelled: true };
110
+ }
111
+ }
112
+ }
113
+
114
+ // Validated before any socket opens, the ordering every other command uses. A
115
+ // logout aimed at a rejected origin must cost zero requests.
116
+ const origin = config.apiKey ? requireControlGateway(config) : null;
117
+ const apiKey = config.apiKey;
118
+
119
+ // ── Which agent is this passport? ─────────────────────────────────────────
120
+ // The config holds a PUBLIC key, not an agent id, so the name has to be looked
121
+ // up — and it has to happen while the control key still works. Best effort: a
122
+ // failure here costs the operator a name, not their logout.
123
+ let agent = null;
124
+ if (origin && apiKey && config.passportId) {
125
+ try {
126
+ const listed = (await control(origin, apiKey, "GET", "/agents", fetchImpl)) ?? [];
127
+ agent = listed.find((row) => row?.passport_pubkey === config.passportId) ?? null;
128
+ } catch {
129
+ warnings.push("Could not list agents, so this could not name the agent behind the passport.");
130
+ }
131
+ }
132
+
133
+ // ── The agent itself ──────────────────────────────────────────────────────
134
+ // Default NO, and not out of timidity: clearing this file destroys the only
135
+ // copy of that agent's private key, but a copy may well exist in a project
136
+ // `.passcontrol`, a password manager, or a CI secret. Revoking on a hunch
137
+ // stops something the operator did not ask to stop.
138
+ let agentRevoked = false;
139
+ if (agent && !opts.keepAgent) {
140
+ const wanted =
141
+ opts.revokeAgent === true ||
142
+ (await confirm(
143
+ `Also revoke agent "${agent.name}"? It can never authenticate again. [y/N] `,
144
+ { default: false }
145
+ ));
146
+ if (wanted) {
147
+ try {
148
+ await control(origin, apiKey, "POST", `/agents/${encodeURIComponent(agent.id)}/revoke`, fetchImpl);
149
+ agentRevoked = true;
150
+ ok(`revoked agent ${agent.name}`);
151
+ } catch {
152
+ warnings.push(`Could not revoke agent "${agent.name}" — do it in the Control Tower.`);
153
+ }
154
+ }
155
+ }
156
+
157
+ // ── The control key ───────────────────────────────────────────────────────
158
+ // Self-revoke: the route takes no id and revokes whatever key authenticated,
159
+ // so this cannot reach another key even by accident.
160
+ let keyRevoked = false;
161
+ if (origin && apiKey) {
162
+ try {
163
+ await control(origin, apiKey, "POST", "/keys/self/revoke", fetchImpl);
164
+ keyRevoked = true;
165
+ ok("revoked this machine's control key");
166
+ } catch (error) {
167
+ // 409 `already_revoked` and 404 `not_found` both mean the key cannot be
168
+ // used again — the route conflates missing and revoked on purpose so that
169
+ // another tenant's id stays indistinguishable from absence. Reporting
170
+ // "STILL LIVE" for either would send the operator to Settings to revoke a
171
+ // key that is not there, and teach them to distrust the message on the one
172
+ // occasion it is true.
173
+ if (error?.status === 409 || error?.status === 404) {
174
+ keyRevoked = true;
175
+ ok("this machine's control key was already revoked");
176
+ } else {
177
+ warnings.push(
178
+ "Could not revoke the control key — it is STILL LIVE. Revoke it in Settings → API keys."
179
+ );
180
+ }
181
+ }
182
+ }
183
+
184
+ // ── The machine ───────────────────────────────────────────────────────────
185
+ // Blank, never delete, and never a full write: PROVIDER, MODEL and the gateway
186
+ // are not credentials and the operator did not ask to lose them. `mergeConfigFile`
187
+ // spreads over what is already there, and writeConfigFile emits `?? ""` for every
188
+ // key, so an empty string is the supported way to clear one.
189
+ mergeConfigFile(target, { PASSPORT_ID: "", PASSPORT_SECRET: "", PASSCONTROL_API_KEY: "" });
190
+ ok(`cleared the credentials in ${target}`);
191
+
192
+ for (const line of warnings) warn(line);
193
+ if (agent && !agentRevoked) {
194
+ step(`Agent "${agent.name}" is still listed, and this machine no longer holds its passport.`);
195
+ }
196
+ step("Log back in any time with `passcontrol login`.");
197
+
198
+ return { target, keyRevoked, agentRevoked, agent, warnings };
199
+ }
@@ -0,0 +1,141 @@
1
+ // The end-to-end proof: does this passport actually govern a call, and can a
2
+ // stranger check that it did?
3
+ //
4
+ // Extracted from `passcontrol login` so `doctor --deep` runs the SAME chain
5
+ // rather than a second one that drifts. Before this, doctor stopped at "visa
6
+ // mint works" — which proves the passport authenticates and nothing about
7
+ // scope, budget, the proxy, or receipts. The most useful diagnostic in the tool
8
+ // was the one thing login already did better.
9
+ //
10
+ // Every leg is existing surface:
11
+ // challenge -> visa cli/visa-client.mjs (the same signer the sidecar uses)
12
+ // demo call app/api/v1/[provider]/[...path]/route.ts, keyless
13
+ // receipt row GET /api/control/v1/receipts/{id}
14
+ // verification cli/verify.mjs, the same code `passcontrol verify` runs
15
+ import { ok, step, warn } from "./config.mjs";
16
+ import { createVisaClient } from "./visa-client.mjs";
17
+ import { verifyReceipt } from "./verify.mjs";
18
+
19
+ async function control(origin, apiKey, method, path, fetchImpl) {
20
+ const res = await fetchImpl(`${origin}/api/control/v1${path}`, {
21
+ method,
22
+ headers: { authorization: `Bearer ${apiKey}` },
23
+ });
24
+ const parsed = await res.json().catch(() => null);
25
+ if (!res.ok) throw new Error(`Control plane refused ${method} ${path} (${res.status}).`);
26
+ // `{ data: ... }` — see lib/control/respond.ts. Unwrapped here so callers read
27
+ // the payload, never the envelope.
28
+ return parsed && typeof parsed === "object" && "data" in parsed ? parsed.data : parsed;
29
+ }
30
+
31
+ /**
32
+ * End the command with the product working, not with homework.
33
+ *
34
+ * `login` used to sign off with homework — go and make a call yourself. This
35
+ * runs it for them, and then does the part nothing else on the market does:
36
+ * fetches the SIGNED RECEIPT for that call and verifies the signature locally,
37
+ * against the gateway's published JWKS.
38
+ *
39
+ * Nothing here is new server surface. Every leg already existed:
40
+ * challenge → visa cli/visa-client.mjs (the same signer the sidecar uses)
41
+ * demo call app/api/v1/[provider]/[...path]/route.ts
42
+ * receipt row GET /api/control/v1/receipts/{id}
43
+ * verification cli/verify.mjs, the same code `passcontrol verify` runs
44
+ *
45
+ * `createVisaClient` rather than a local ed25519.sign: it re-validates the
46
+ * origin at the point of signature, which is the guard its own header explains
47
+ * is easy to leave behind when a new caller copies the signing lines instead.
48
+ *
49
+ * ── This function must never throw ──────────────────────────────────────────
50
+ *
51
+ * In login, the agent, the key and the config all already exist by the time
52
+ * this runs — the command has SUCCEEDED. A proof that could turn that into a
53
+ * non-zero exit would be a demo that costs people their setup. In doctor, a
54
+ * throwing diagnostic is simply a bad diagnostic. So every branch degrades to
55
+ * a quieter message and returns, and it wraps ITSELF rather than trusting each
56
+ * caller to remember.
57
+ */
58
+ export async function proveItWorks({ origin, passportId, passportSecret, apiKey, fetchImpl }) {
59
+ const proof = { visa: false, call: false, receipt: null };
60
+ try {
61
+ const visas = createVisaClient({ gateway: origin, passportId, passportSecret, fetch: fetchImpl });
62
+ const visa = await visas.getVisa();
63
+ proof.visa = true;
64
+ ok("minted a visa with the passport this machine just created");
65
+
66
+ const res = await fetchImpl(`${origin}/api/v1/demo/chat/completions`, {
67
+ method: "POST",
68
+ headers: { "content-type": "application/json", authorization: `Bearer ${visa}` },
69
+ body: JSON.stringify({
70
+ model: "demo-1",
71
+ max_tokens: 32,
72
+ messages: [{ role: "user", content: "Say hello in three words." }],
73
+ }),
74
+ });
75
+
76
+ if (!res.ok) {
77
+ // 404 is the ordinary answer from a self-hosted gateway that has not set
78
+ // PASSCONTROL_DEMO=1 — a correctly configured gateway, not a fault. Say so
79
+ // in those words, because "404" here would read as something being broken.
80
+ proof.reason = res.status === 404 ? "demo_unavailable" : `call_${res.status}`;
81
+ step(
82
+ res.status === 404
83
+ ? "This gateway has no keyless demo provider, so there was nothing free to call."
84
+ : `The demo call answered ${res.status}; your passport is still fine.`
85
+ );
86
+ step('Add a provider key in the Control Tower, then: passcontrol call "hi"');
87
+ return proof;
88
+ }
89
+ proof.call = true;
90
+ const body = await res.json().catch(() => null);
91
+ const tokens = body?.usage?.total_tokens;
92
+ ok(`governed call ok — demo/${body?.model ?? "demo-1"}${tokens ? `, ${tokens} tokens` : ""}`);
93
+
94
+ // Absent only when the deployment predates receipts; the id is the handle
95
+ // for the audit row either way.
96
+ const receiptId = res.headers.get("x-passcontrol-receipt-id");
97
+ // No control key (doctor can run without one): the call is still proven,
98
+ // the receipt just cannot be fetched to check.
99
+ if (!receiptId || !apiKey) {
100
+ proof.receipt = "unavailable";
101
+ return proof;
102
+ }
103
+ proof.receiptId = receiptId;
104
+
105
+ const row = await control(origin, apiKey, "GET", `/receipts/${receiptId}`, fetchImpl);
106
+ const jws = row?.receipt;
107
+ if (!jws) {
108
+ // The route says why itself: no INSTANCE_SIGNING_KEY is a configuration
109
+ // answer, not missing data.
110
+ proof.receipt = "unavailable";
111
+ step(
112
+ row?.reason === "receipts_not_enabled"
113
+ ? "This deployment signs no receipts yet (no instance signing key)."
114
+ : "No receipt was stored for that call."
115
+ );
116
+ return proof;
117
+ }
118
+
119
+ // Verified HERE, on this machine, against the issuer's published key — the
120
+ // same code path `passcontrol verify receipt` runs for a stranger. If this
121
+ // said "verified" without checking, the feature would be a slogan.
122
+ const verified = await verifyReceipt(jws, { issuer: origin, fetch: fetchImpl });
123
+ proof.receipt = verified.ok ? "verified" : "unverified";
124
+ if (verified.ok) {
125
+ ok(`receipt verified against ${origin}/.well-known/jwks.json`);
126
+ step("");
127
+ step("Your agent is live. Anyone can check that call for themselves:");
128
+ step(` passcontrol verify receipt ${jws} --issuer ${origin}`);
129
+ } else {
130
+ warn(`A receipt came back but did not verify (${verified.reason}).`);
131
+ }
132
+ return proof;
133
+ } catch (error) {
134
+ // Deliberately quiet. The login worked; this did not, and saying so loudly
135
+ // would teach the operator to distrust a config that is perfectly good.
136
+ proof.reason = error?.message ?? "unknown";
137
+ step("Could not run the first call just now — your config is written and valid.");
138
+ step('Try it yourself: passcontrol call "hi"');
139
+ return proof;
140
+ }
141
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "passcontrol",
3
- "version": "0.7.2",
3
+ "version": "0.8.0",
4
4
  "description": "Identity, scope and budget controls for AI agents while provider keys stay server-side.",
5
5
  "license": "BUSL-1.1",
6
6
  "homepage": "https://passcontrol.vertias.eu",