passcontrol 0.7.1 → 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 +92 -61
- package/bin/passcontrol.mjs +74 -125
- package/cli/login.mjs +108 -13
- package/cli/logout.mjs +199 -0
- package/cli/selftest.mjs +141 -0
- package/package.json +1 -1
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
|
|
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
|
-
|
|
54
|
-
|
|
55
|
-
|
|
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
|
-
**
|
|
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
|
|
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
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
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
|
-
|
|
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
|
-
|
|
144
|
-
|
|
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
|
-
|
|
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`.
|
|
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
|
-
|
|
153
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
164
|
-
|
|
165
|
-
|
|
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
|
package/bin/passcontrol.mjs
CHANGED
|
@@ -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>
|
|
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
|
-
|
|
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
|
-
|
|
2154
|
-
|
|
2155
|
-
|
|
2156
|
-
|
|
2157
|
-
|
|
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
|
|
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
|
-
|
|
2517
|
-
|
|
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
|
@@ -39,6 +39,8 @@ import { ed25519 } from "@noble/curves/ed25519";
|
|
|
39
39
|
import fs from "node:fs";
|
|
40
40
|
import {
|
|
41
41
|
CLOUD_GATEWAY,
|
|
42
|
+
configInjectedKeys,
|
|
43
|
+
configSources,
|
|
42
44
|
fail,
|
|
43
45
|
findProjectConfig,
|
|
44
46
|
globalConfigPath,
|
|
@@ -49,6 +51,7 @@ import {
|
|
|
49
51
|
step,
|
|
50
52
|
warn,
|
|
51
53
|
} from "./config.mjs";
|
|
54
|
+
import { proveItWorks } from "./selftest.mjs";
|
|
52
55
|
|
|
53
56
|
export { CLOUD_GATEWAY };
|
|
54
57
|
|
|
@@ -192,7 +195,17 @@ const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
|
|
|
192
195
|
* Honours the server's `interval` and backs off on `slow_down`, so the poll rate
|
|
193
196
|
* is the server's decision and can be widened without shipping a new CLI.
|
|
194
197
|
*/
|
|
195
|
-
async function pollForGrant(
|
|
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
|
+
) {
|
|
196
209
|
const deadline = now() + expiresIn * 1000;
|
|
197
210
|
let waitMs = Math.max(500, interval * 1000);
|
|
198
211
|
// A transport failure is NOT fatal here, and this is the one place in the flow
|
|
@@ -213,7 +226,7 @@ async function pollForGrant(origin, deviceCode, { interval, expiresIn, fetchImpl
|
|
|
213
226
|
let transportFailures = 0;
|
|
214
227
|
let failingSince = 0;
|
|
215
228
|
while (now() < deadline) {
|
|
216
|
-
await
|
|
229
|
+
await wait(waitMs);
|
|
217
230
|
let res;
|
|
218
231
|
try {
|
|
219
232
|
res = await postJson(`${origin}/api/auth/device/token`, { device_code: deviceCode }, { fetchImpl });
|
|
@@ -269,7 +282,13 @@ async function control(origin, apiKey, method, path, body, fetchImpl = fetch) {
|
|
|
269
282
|
if (!res.ok) {
|
|
270
283
|
throw new Error(`Control plane refused ${method} ${path} (${res.status}).`);
|
|
271
284
|
}
|
|
272
|
-
|
|
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;
|
|
273
292
|
}
|
|
274
293
|
|
|
275
294
|
/**
|
|
@@ -334,11 +353,53 @@ export function resolveLoginGateway(opts = {}, env = process.env) {
|
|
|
334
353
|
return requireControlGateway({ gateway: fromFlag || fromConfig || CLOUD_GATEWAY });
|
|
335
354
|
}
|
|
336
355
|
|
|
356
|
+
/**
|
|
357
|
+
* WHERE the destination came from — so a failure can name something editable.
|
|
358
|
+
*
|
|
359
|
+
* This exists because the honest answer is not "the environment". cli/config.mjs
|
|
360
|
+
* injects config-file values into `process.env` at import, so by the time
|
|
361
|
+
* resolveLoginGateway reads PASSCONTROL_GATEWAY the shell and a file on disk are
|
|
362
|
+
* indistinguishable — and an error telling someone to "unset PASSCONTROL_GATEWAY"
|
|
363
|
+
* when their value lives in `~/.config/passcontrol/config` is instructing them to
|
|
364
|
+
* change something that is not set. They run it, nothing moves, and the CLI looks
|
|
365
|
+
* broken rather than merely configured. Reported from a real machine on 0.7.1.
|
|
366
|
+
*
|
|
367
|
+
* `configInjectedKeys` is the same set cli/config.mjs keeps so that "a file said
|
|
368
|
+
* so" and "the operator said so" stay separable for credentials. This is that
|
|
369
|
+
* distinction applied to advice.
|
|
370
|
+
*
|
|
371
|
+
* The file search takes the LAST match, not the first. applyConfigSourcesToEnv
|
|
372
|
+
* pushes global then project and Object.assign()es in order, so a project
|
|
373
|
+
* `.passcontrol` overwrites the global config — and `.find()` would confidently
|
|
374
|
+
* name a file whose value never reached the environment.
|
|
375
|
+
*/
|
|
376
|
+
export function gatewaySource(
|
|
377
|
+
opts = {},
|
|
378
|
+
env = process.env,
|
|
379
|
+
{ sources = configSources, injected = configInjectedKeys } = {}
|
|
380
|
+
) {
|
|
381
|
+
if (typeof opts.gateway === "string" && opts.gateway.trim()) return { from: "flag" };
|
|
382
|
+
if (typeof env.PASSCONTROL_GATEWAY === "string" && env.PASSCONTROL_GATEWAY.trim()) {
|
|
383
|
+
if (!injected.has("PASSCONTROL_GATEWAY")) return { from: "env" };
|
|
384
|
+
const file = [...sources]
|
|
385
|
+
.reverse()
|
|
386
|
+
.find((source) => "PASSCONTROL_GATEWAY" in (source?.values ?? {}));
|
|
387
|
+
return file ? { from: "file", path: file.path } : { from: "env" };
|
|
388
|
+
}
|
|
389
|
+
return { from: "default" };
|
|
390
|
+
}
|
|
391
|
+
|
|
337
392
|
export async function loginCommand(opts = {}, deps = {}) {
|
|
338
393
|
const fetchImpl = deps.fetch ?? fetch;
|
|
339
394
|
const openUrl = deps.openUrl ?? (() => {});
|
|
340
395
|
const confirm = deps.confirmYes ?? (async (_q, o = {}) => o.default !== false);
|
|
341
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;
|
|
342
403
|
|
|
343
404
|
// Validate the destination BEFORE anything is requested — the ordering mintVisa
|
|
344
405
|
// uses. A rejected gateway must cost zero sockets.
|
|
@@ -360,12 +421,26 @@ export async function loginCommand(opts = {}, deps = {}) {
|
|
|
360
421
|
// never be true and the timeout wording would be dead code.
|
|
361
422
|
const underlying = error?.cause ?? error;
|
|
362
423
|
const reason = underlying?.name === "AbortError" ? "timed out" : "could not be reached";
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
);
|
|
424
|
+
// Name the place BEFORE offering the remedy — that is the whole job of
|
|
425
|
+
// gatewaySource above. The default origin is nobody's mistake, and blaming a
|
|
426
|
+
// config file that never mentions a gateway sends the operator to edit a line
|
|
427
|
+
// that is not there.
|
|
428
|
+
const source = gatewaySource(opts);
|
|
429
|
+
const lines = [`${origin} ${reason} (${underlying?.message ?? "unknown"}).`];
|
|
430
|
+
if (source.from === "file") {
|
|
431
|
+
lines.push(` That origin comes from ${source.path}, not from your shell.`);
|
|
432
|
+
lines.push(` Edit or delete its PASSCONTROL_GATEWAY line to change it.`);
|
|
433
|
+
} else if (source.from === "env") {
|
|
434
|
+
lines.push(` That origin comes from PASSCONTROL_GATEWAY in your shell.`);
|
|
435
|
+
}
|
|
436
|
+
if (source.from === "default") {
|
|
437
|
+
lines.push(` • Self-hosting? Start your stack, then pass --gateway <origin>.`);
|
|
438
|
+
lines.push(` • Otherwise check your connection and run the command again.`);
|
|
439
|
+
} else {
|
|
440
|
+
lines.push(` • Self-hosting? Start your stack, or pass --gateway <origin>.`);
|
|
441
|
+
lines.push(` • Meant to use Cloud? passcontrol login --gateway ${CLOUD_GATEWAY}`);
|
|
442
|
+
}
|
|
443
|
+
throw new Error(lines.join("\n"), { cause: error });
|
|
369
444
|
}
|
|
370
445
|
if (started.status !== 200 || !started.body?.user_code) {
|
|
371
446
|
throw new Error(
|
|
@@ -394,6 +469,8 @@ export async function loginCommand(opts = {}, deps = {}) {
|
|
|
394
469
|
interval: Number(started.body.interval ?? 1),
|
|
395
470
|
expiresIn: Number(started.body.expires_in ?? 600),
|
|
396
471
|
fetchImpl,
|
|
472
|
+
now,
|
|
473
|
+
wait,
|
|
397
474
|
});
|
|
398
475
|
ok("approved");
|
|
399
476
|
|
|
@@ -402,7 +479,7 @@ export async function loginCommand(opts = {}, deps = {}) {
|
|
|
402
479
|
// The keypair is generated HERE and only the PUBLIC half is sent. The gateway
|
|
403
480
|
// has never held a passport private key; this command must not be the first
|
|
404
481
|
// thing to change that.
|
|
405
|
-
const agents = (await control(origin, grant.api_key, "GET", "/agents", null, fetchImpl))
|
|
482
|
+
const agents = (await control(origin, grant.api_key, "GET", "/agents", null, fetchImpl)) ?? [];
|
|
406
483
|
let agentId = null;
|
|
407
484
|
if (agents.length > 0 && !opts.new) {
|
|
408
485
|
step(`This workspace has ${agents.length} agent(s).`);
|
|
@@ -430,7 +507,17 @@ export async function loginCommand(opts = {}, deps = {}) {
|
|
|
430
507
|
const created = await control(origin, grant.api_key, "POST", "/agents", {
|
|
431
508
|
name: clientName,
|
|
432
509
|
passportPubkey: passportId,
|
|
433
|
-
|
|
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
|
+
],
|
|
434
521
|
}, fetchImpl);
|
|
435
522
|
agentId = created?.id ?? null;
|
|
436
523
|
ok(`created agent ${created?.name ?? clientName}`);
|
|
@@ -460,7 +547,15 @@ export async function loginCommand(opts = {}, deps = {}) {
|
|
|
460
547
|
warnIfShadowed(target);
|
|
461
548
|
|
|
462
549
|
step("");
|
|
463
|
-
|
|
550
|
+
const proof = await proveItWorks({
|
|
551
|
+
origin,
|
|
552
|
+
passportId,
|
|
553
|
+
passportSecret,
|
|
554
|
+
apiKey: grant.api_key,
|
|
555
|
+
fetchImpl,
|
|
556
|
+
});
|
|
557
|
+
|
|
558
|
+
step("");
|
|
464
559
|
step(`The key is listed in Settings as "CLI on ${clientName}" and can be revoked there.`);
|
|
465
|
-
return { agentId, passportId, target };
|
|
560
|
+
return { agentId, passportId, target, proof };
|
|
466
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
|
+
}
|
package/cli/selftest.mjs
ADDED
|
@@ -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