passcontrol 1.3.0 → 1.5.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/LICENSE +3 -1
- package/README.md +10 -1
- package/bin/passcontrol.mjs +455 -10
- package/cli/budget-format.mjs +113 -0
- package/cli/claude-code.mjs +80 -16
- package/cli/config.mjs +36 -2
- package/cli/declared-session.mjs +61 -0
- package/cli/delegation.d.mts +60 -0
- package/cli/delegation.mjs +192 -0
- package/cli/journal.mjs +84 -0
- package/cli/mcp/README.md +4 -1
- package/cli/mcp/gateway.mjs +13 -0
- package/cli/mcp/server.mjs +27 -0
- package/cli/menu.mjs +7 -0
- package/cli/profiles.mjs +92 -0
- package/cli/protocols.d.mts +2 -0
- package/cli/protocols.mjs +17 -1
- package/cli/sidecar.mjs +194 -20
- package/cli/statusline.mjs +213 -0
- package/cli/verify.mjs +215 -5
- package/cli/visa-client.mjs +5 -1
- package/cli/watch-feed.mjs +275 -0
- package/cli/watch.mjs +601 -0
- package/package.json +1 -1
- package/sdk/index.d.ts +2 -1
- package/sdk/index.js +3 -0
- package/sdk/passcontrol.d.ts +46 -0
- package/sdk/passcontrol.js +47 -2
- package/sdk/verify.d.ts +115 -0
- package/sdk/verify.js +219 -1
package/bin/passcontrol.mjs
CHANGED
|
@@ -90,7 +90,15 @@ import {
|
|
|
90
90
|
import { isLocalGatewayOrigin, probeGatewayVersion, probeTimeoutMs } from "../cli/gateway-probe.mjs";
|
|
91
91
|
import { dashboardOriginForOffset, portHolders, stackPortConflictMessage } from "../cli/local-stack.mjs";
|
|
92
92
|
import { startSidecar } from "../cli/sidecar.mjs";
|
|
93
|
-
import {
|
|
93
|
+
import { listProfiles, profilePath, readProfile, TOOL_PROFILE_PORTS, writeProfile } from "../cli/profiles.mjs";
|
|
94
|
+
import {
|
|
95
|
+
claudeCodeEnv,
|
|
96
|
+
claudeCodeSettingsPath,
|
|
97
|
+
removeClaudeCodeSettings,
|
|
98
|
+
writeClaudeCodeSettings,
|
|
99
|
+
} from "../cli/claude-code.mjs";
|
|
100
|
+
import { notInPathText, sidecarFromBaseUrl, statusPanelText, statuslineText } from "../cli/statusline.mjs";
|
|
101
|
+
import { runWatch } from "../cli/watch.mjs";
|
|
94
102
|
import { CODEX_PROFILE, codexProfilePath, codexProfileToml, codexStoresApiKey, removeCodexProfile, writeCodexProfile } from "../cli/codex.mjs";
|
|
95
103
|
import { waitForGateway as awaitGateway } from "../cli/gateway-wait.mjs";
|
|
96
104
|
import { loginCommand } from "../cli/login.mjs";
|
|
@@ -102,7 +110,7 @@ import {
|
|
|
102
110
|
instanceKidFromSeed,
|
|
103
111
|
retiredKeyEntry,
|
|
104
112
|
} from "../cli/instance-key.mjs";
|
|
105
|
-
import { FAILURE_REASONS, verifyAgentToken, verifyReceipt, verifyStatement } from "../cli/verify.mjs";
|
|
113
|
+
import { FAILURE_REASONS, verifyAgentToken, verifyReceipt, verifySession, verifyStatement } from "../cli/verify.mjs";
|
|
106
114
|
import { compareProtocolSets } from "../cli/protocols.mjs";
|
|
107
115
|
import { defaultAllowedModelForProvider } from "../cli/integration-defaults.mjs";
|
|
108
116
|
import {
|
|
@@ -200,8 +208,10 @@ ${heading("Quick start")}
|
|
|
200
208
|
${cmd} login [--project] sign in through your browser and set this machine up
|
|
201
209
|
${cmd} call "hi" mint a visa and make a governed model call
|
|
202
210
|
${cmd} mcp passport identity for Claude Desktop, Cursor, Claude Code
|
|
203
|
-
${cmd} sidecar [--port 8788] [--allow-connect host[,host]] [--ollama-port 11435]
|
|
211
|
+
${cmd} sidecar [--port 8788] [--allow-connect host[,host]] [--ollama-port 11435] [--no-journal]
|
|
204
212
|
passport identity for any tool that takes an api_key
|
|
213
|
+
${cmd} sidecar --profile <name> | --profiles a,b
|
|
214
|
+
run a coding tool's own sidecar (or several, one process)
|
|
205
215
|
|
|
206
216
|
${heading("Operate")}
|
|
207
217
|
${cmd} status [--no-network] [--json]
|
|
@@ -217,6 +227,7 @@ ${heading("Operate")}
|
|
|
217
227
|
|
|
218
228
|
${heading("Manage")}
|
|
219
229
|
${cmd} agent list [--json] list agents
|
|
230
|
+
${cmd} profile list [--json] show the profiles: one identity per coding tool
|
|
220
231
|
${cmd} agent create <name> [--write]
|
|
221
232
|
create an agent passport (--write saves it here)
|
|
222
233
|
${cmd} agent rotate <id> [--grace <seconds>]
|
|
@@ -224,6 +235,10 @@ ${heading("Manage")}
|
|
|
224
235
|
${cmd} agent suspend <id> suspend an agent
|
|
225
236
|
${cmd} agent resume <id> resume an agent
|
|
226
237
|
${cmd} agent revoke <id> permanently revoke an agent
|
|
238
|
+
${cmd} agent delegations <id> [--json]
|
|
239
|
+
list the delegations its workers have used
|
|
240
|
+
${cmd} agent revoke-delegation <id> <jti>|--all
|
|
241
|
+
permanently revoke one delegation, or all before now
|
|
227
242
|
${cmd} spend [--json] show fleet and per-agent spend
|
|
228
243
|
${cmd} audit [--limit 20] [--json]
|
|
229
244
|
show operator audit history
|
|
@@ -231,6 +246,13 @@ ${heading("Manage")}
|
|
|
231
246
|
show governed call logs
|
|
232
247
|
${cmd} statements [--limit 20] [--json]
|
|
233
248
|
show the chain of signed spend statements
|
|
249
|
+
${cmd} sessions [--agent ID] [--limit 20] [--json]
|
|
250
|
+
list Claude Code / Codex sessions (declared by the client)
|
|
251
|
+
${cmd} seal <session> --agent ID [--out FILE]
|
|
252
|
+
sign one session; save the seal and its receipts
|
|
253
|
+
${cmd} statusline [--port 8788] one line for Claude Code's status line (configure claude-code --statusline)
|
|
254
|
+
${cmd} statusline --panel [--session <id>] the longer view the Claude Code plugin's /passcontrol shows
|
|
255
|
+
${cmd} watch [--port 8788] a live board of each call the sidecar relays (read-only)
|
|
234
256
|
${cmd} kill on|off toggle the tenant kill switch
|
|
235
257
|
${cmd} export [--out FILE] save a workspace configuration snapshot
|
|
236
258
|
${cmd} import <file> [--confirm IMPORT]
|
|
@@ -238,7 +260,7 @@ ${heading("Manage")}
|
|
|
238
260
|
|
|
239
261
|
${heading("Integrate")}
|
|
240
262
|
${cmd} env [integration] print settings without writing anything
|
|
241
|
-
${cmd} configure <integration> [--write] [--force]
|
|
263
|
+
${cmd} configure <integration> [--write] [--force] [--dedicated]
|
|
242
264
|
preview or write integration config
|
|
243
265
|
integrations: ${integrationChoices()}
|
|
244
266
|
|
|
@@ -291,6 +313,8 @@ ${heading("Usage:")}
|
|
|
291
313
|
${cmd} agent suspend <id>
|
|
292
314
|
${cmd} agent resume <id>
|
|
293
315
|
${cmd} agent revoke <id>
|
|
316
|
+
${cmd} agent delegations <id> [--json]
|
|
317
|
+
${cmd} agent revoke-delegation <id> <jti>|--all
|
|
294
318
|
|
|
295
319
|
${heading("Examples")}
|
|
296
320
|
${cmd} agent create prod-summarizer --provider anthropic --scope 'claude-*'
|
|
@@ -362,6 +386,7 @@ async function printCockpit({ noNetwork = false, json = false } = {}) {
|
|
|
362
386
|
app: { state: app },
|
|
363
387
|
config: {
|
|
364
388
|
source: configFile,
|
|
389
|
+
profile: config.profile,
|
|
365
390
|
provider: config.provider,
|
|
366
391
|
model: config.model,
|
|
367
392
|
passport_configured: passportConfigured,
|
|
@@ -2262,9 +2287,66 @@ async function agentCommand(rest, opts) {
|
|
|
2262
2287
|
step("passport instead, and leaves this one working everywhere it already runs.");
|
|
2263
2288
|
break;
|
|
2264
2289
|
}
|
|
2290
|
+
// An agent's signed delegations to its workers (Bet D). A delegation is made
|
|
2291
|
+
// offline, so the gateway knows a link only once a worker has exchanged it; the
|
|
2292
|
+
// listing says so, and --all is the tool that reaches the ones never seen.
|
|
2293
|
+
case "delegations": {
|
|
2294
|
+
if (!args[0]) throw new Error("Usage: passcontrol agent delegations <agent-id> [--json]");
|
|
2295
|
+
const rows = await api("GET", `/agents/${encodeURIComponent(args[0])}/delegations`);
|
|
2296
|
+
if (opts.json) {
|
|
2297
|
+
console.log(JSON.stringify(rows, null, 2));
|
|
2298
|
+
break;
|
|
2299
|
+
}
|
|
2300
|
+
step("Only delegations a worker has used appear here. A delegation is signed offline, so the");
|
|
2301
|
+
step("gateway learns of it at its first exchange; `revoke-delegation --all` also reaches unseen ones.");
|
|
2302
|
+
if (!Array.isArray(rows) || rows.length === 0) {
|
|
2303
|
+
step("No worker has used a delegation from this agent yet.");
|
|
2304
|
+
break;
|
|
2305
|
+
}
|
|
2306
|
+
// Server text reaches a terminal: keep it to printable ASCII.
|
|
2307
|
+
const printable = (v) => String(v ?? "").replace(/[^\x20-\x7e]/g, "?").slice(0, 64);
|
|
2308
|
+
const now = Date.now();
|
|
2309
|
+
console.table(
|
|
2310
|
+
rows.map((d) => ({
|
|
2311
|
+
jti: printable(d.jti),
|
|
2312
|
+
depth: d.depth,
|
|
2313
|
+
status: d.revoked ? "revoked" : Date.parse(d.expires_at) <= now ? "expired" : "active",
|
|
2314
|
+
worker: `${printable(d.worker_key).slice(0, 12)}…`,
|
|
2315
|
+
cap: usd(d.cap_microcents),
|
|
2316
|
+
models: Array.isArray(d.scope)
|
|
2317
|
+
? d.scope.map((s) => `${printable(s?.provider)}:${(Array.isArray(s?.models) ? s.models : []).map(printable).join("|")}`).join(", ")
|
|
2318
|
+
: "",
|
|
2319
|
+
expires: printable(d.expires_at).slice(0, 19),
|
|
2320
|
+
"first used": printable(d.first_exchanged_at).slice(0, 19),
|
|
2321
|
+
}))
|
|
2322
|
+
);
|
|
2323
|
+
break;
|
|
2324
|
+
}
|
|
2325
|
+
case "revoke-delegation": {
|
|
2326
|
+
const usage = "Usage: passcontrol agent revoke-delegation <agent-id> <jti>|--all";
|
|
2327
|
+
const [agentId, jti] = args;
|
|
2328
|
+
const all = opts.all === true;
|
|
2329
|
+
if (!agentId || all === Boolean(jti)) throw new Error(usage);
|
|
2330
|
+
const result = await api(
|
|
2331
|
+
"POST",
|
|
2332
|
+
`/agents/${encodeURIComponent(agentId)}/delegations/revoke`,
|
|
2333
|
+
all ? { all: true } : { jti }
|
|
2334
|
+
);
|
|
2335
|
+
ok(
|
|
2336
|
+
all
|
|
2337
|
+
? `revoked every delegation agent ${agentId} issued before now, seen or not`
|
|
2338
|
+
: `revoked delegation ${jti} and every delegation under it`
|
|
2339
|
+
);
|
|
2340
|
+
step("This is permanent. To let a worker go on, the agent delegates to it again.");
|
|
2341
|
+
if (result?.immediate === false) {
|
|
2342
|
+
step("Recorded, but the gateway's fast copy could not be written: a worker holding a current");
|
|
2343
|
+
step("visa can keep calling until that visa expires (5 minutes by default).");
|
|
2344
|
+
}
|
|
2345
|
+
break;
|
|
2346
|
+
}
|
|
2265
2347
|
default:
|
|
2266
2348
|
throw new Error(
|
|
2267
|
-
"Usage: passcontrol agent list|create <name>|suspend <id>|resume <id>|revoke <id>|rotate <id> [--grace <seconds>]"
|
|
2349
|
+
"Usage: passcontrol agent list|create <name>|suspend <id>|resume <id>|revoke <id>|rotate <id> [--grace <seconds>]|delegations <id>|revoke-delegation <id> <jti>|--all"
|
|
2268
2350
|
);
|
|
2269
2351
|
}
|
|
2270
2352
|
}
|
|
@@ -2357,6 +2439,31 @@ async function sidecarCommand(rest, opts) {
|
|
|
2357
2439
|
// sidecar mints on demand for the lifetime of the process, so a bad
|
|
2358
2440
|
// destination has to be refused at start, not at the first proxied request.
|
|
2359
2441
|
const gateway = requirePassportGateway(config);
|
|
2442
|
+
if (opts.profiles) {
|
|
2443
|
+
// Several identities, one process: one listener per profile, each with its own
|
|
2444
|
+
// passport, visa and journal (candidate 4). One terminal, one Ctrl-C.
|
|
2445
|
+
const names = String(opts.profiles).split(",").map((n) => n.trim()).filter(Boolean);
|
|
2446
|
+
for (const name of names) {
|
|
2447
|
+
const values = readProfile(name);
|
|
2448
|
+
if (!values?.PASSPORT_ID || !values?.PASSPORT_SECRET) {
|
|
2449
|
+
throw new Error(`Profile ${name} has no passport. Create it with ${cliCommand(`configure ${name} --dedicated --write`)}.`);
|
|
2450
|
+
}
|
|
2451
|
+
step(`Profile ${name}:`);
|
|
2452
|
+
startSidecar({
|
|
2453
|
+
gateway,
|
|
2454
|
+
passportId: values.PASSPORT_ID,
|
|
2455
|
+
passportSecret: values.PASSPORT_SECRET,
|
|
2456
|
+
keyStorage: null,
|
|
2457
|
+
port: sidecarPort({ port: values.SIDECAR_PORT }),
|
|
2458
|
+
host: String(opts.host ?? process.env.SIDECAR_HOST ?? "127.0.0.1"),
|
|
2459
|
+
allowNonLoopback: Boolean(opts.allowNonLoopback),
|
|
2460
|
+
allowConnectHosts: [],
|
|
2461
|
+
refreshSkewSeconds: Number(opts.refreshSkewSeconds ?? process.env.REFRESH_SKEW_SECONDS ?? 30),
|
|
2462
|
+
noJournal: opts.journal === false || Boolean(opts.noJournal),
|
|
2463
|
+
});
|
|
2464
|
+
}
|
|
2465
|
+
return;
|
|
2466
|
+
}
|
|
2360
2467
|
const { passportId, passportSecret, keyStorage } = requirePassport(config);
|
|
2361
2468
|
startSidecar({
|
|
2362
2469
|
gateway,
|
|
@@ -2382,6 +2489,10 @@ async function sidecarCommand(rest, opts) {
|
|
|
2382
2489
|
.map((entry) => entry.trim())
|
|
2383
2490
|
.filter(Boolean),
|
|
2384
2491
|
refreshSkewSeconds: Number(opts.refreshSkewSeconds ?? process.env.REFRESH_SKEW_SECONDS ?? 30),
|
|
2492
|
+
// The receipt-id journal (cli/journal.mjs) is on unless the flag says off.
|
|
2493
|
+
// A flag only, like --allow-non-loopback: whether this machine keeps a record
|
|
2494
|
+
// is the operator's to state, not a config file's.
|
|
2495
|
+
noJournal: opts.journal === false || Boolean(opts.noJournal),
|
|
2385
2496
|
});
|
|
2386
2497
|
|
|
2387
2498
|
if (opts.for) {
|
|
@@ -2405,6 +2516,38 @@ function sidecarPort(opts = {}) {
|
|
|
2405
2516
|
return port;
|
|
2406
2517
|
}
|
|
2407
2518
|
|
|
2519
|
+
/**
|
|
2520
|
+
* The agent's budget as one line, read through the running sidecar (cli/statusline.mjs).
|
|
2521
|
+
* Never throws: whatever happens, Claude Code gets one line and a clean exit.
|
|
2522
|
+
*/
|
|
2523
|
+
async function statuslineCommand(opts) {
|
|
2524
|
+
try {
|
|
2525
|
+
const port = sidecarPort(opts);
|
|
2526
|
+
// `--panel`: the several-line view `/passcontrol` shows in Claude Code (F3).
|
|
2527
|
+
// Without --port, the sidecar Claude Code's own ANTHROPIC_BASE_URL names.
|
|
2528
|
+
if (opts.panel) {
|
|
2529
|
+
const route = opts.port === undefined ? sidecarFromBaseUrl(process.env.ANTHROPIC_BASE_URL) : null;
|
|
2530
|
+
if (route?.remote) return notInPathText(route.remote);
|
|
2531
|
+
return await statusPanelText({
|
|
2532
|
+
port: route?.port ?? port,
|
|
2533
|
+
gateway: config.gateway,
|
|
2534
|
+
session: typeof opts.session === "string" ? opts.session : null,
|
|
2535
|
+
});
|
|
2536
|
+
}
|
|
2537
|
+
const cacheFile = path.join(path.dirname(globalConfigPath()), `statusline-${port}.json`);
|
|
2538
|
+
return await statuslineText({ port, cacheFile });
|
|
2539
|
+
} catch (error) {
|
|
2540
|
+
return `PassControl · ${error instanceof Error && /--port/.test(error.message) ? "bad --port" : "unavailable"}`;
|
|
2541
|
+
}
|
|
2542
|
+
}
|
|
2543
|
+
|
|
2544
|
+
/** The command Claude Code's settings run: the installed binary, or this checkout's. */
|
|
2545
|
+
function statusLineSettingsCommand(port) {
|
|
2546
|
+
const args = `statusline --port ${port}`;
|
|
2547
|
+
if (process.env.npm_lifecycle_event !== "cli") return `passcontrol ${args}`;
|
|
2548
|
+
return `node ${JSON.stringify(CLI_ENTRY)} ${args}`;
|
|
2549
|
+
}
|
|
2550
|
+
|
|
2408
2551
|
function sidecarBaseUrl(opts = {}) {
|
|
2409
2552
|
const provider = String(opts.provider || config.provider);
|
|
2410
2553
|
assertProvider(provider);
|
|
@@ -2446,7 +2589,9 @@ function passControlMcpEntry() {
|
|
|
2446
2589
|
}
|
|
2447
2590
|
|
|
2448
2591
|
function printMcpPreset(integration, opts = {}) {
|
|
2449
|
-
|
|
2592
|
+
// Claude Code's lines only point it at the sidecar, which holds the passport (as in
|
|
2593
|
+
// configureMcpClient); the MCP clients below launch `passcontrol mcp`, which needs it.
|
|
2594
|
+
if (integration !== "claude-code") requireGlobalMcpPassport();
|
|
2450
2595
|
if (integration === "claude-code") {
|
|
2451
2596
|
const { baseUrl } = sidecarBaseUrl({ ...opts, provider: "anthropic" });
|
|
2452
2597
|
console.log("# Route Claude Code's model calls through the sidecar (start it first):");
|
|
@@ -2619,16 +2764,29 @@ function configureClaudeCode(opts = {}) {
|
|
|
2619
2764
|
if (!opts.write) {
|
|
2620
2765
|
step(`Dry run only. Re-run with \`--write\` to merge these two keys${scope === "project" ? " (or --write --global for every session)" : ""}.`);
|
|
2621
2766
|
} else {
|
|
2622
|
-
const result = writeClaudeCodeSettings({
|
|
2767
|
+
const result = writeClaudeCodeSettings({
|
|
2768
|
+
target,
|
|
2769
|
+
baseUrl,
|
|
2770
|
+
force: Boolean(opts.force),
|
|
2771
|
+
statusLineCommand: opts.statusline ? statusLineSettingsCommand(port) : null,
|
|
2772
|
+
});
|
|
2623
2773
|
if (!result.changed) ok(`${target} already routes Claude Code through PassControl`);
|
|
2624
2774
|
else {
|
|
2625
2775
|
if (result.backupPath) step(`backed up ${result.backupPath}`);
|
|
2626
2776
|
ok(`wrote ${target}`);
|
|
2627
2777
|
}
|
|
2778
|
+
if (result.statusLine?.existing) {
|
|
2779
|
+
warn(`${target} already has a status line (${result.statusLine.existing}); it was left as it is. To show the budget there, add \`${statusLineSettingsCommand(port)}\` to it yourself.`);
|
|
2780
|
+
} else if (result.statusLine?.changed) ok("added the agent's budget to Claude Code's status line");
|
|
2628
2781
|
if (result.rawKeyFound) {
|
|
2629
2782
|
warn(`${target} also holds a raw ANTHROPIC_API_KEY. PassControl does not need it there; remove it so no key sits on disk.`);
|
|
2630
2783
|
}
|
|
2631
2784
|
}
|
|
2785
|
+
if (opts.statusline && !opts.write) {
|
|
2786
|
+
step(`With --write, the status line would run: ${statusLineSettingsCommand(port)}`);
|
|
2787
|
+
} else if (!opts.statusline) {
|
|
2788
|
+
step(`Optional, the agent's budget in Claude Code's status line: ${cliCommand(`configure claude-code --write --statusline${scope === "user" ? " --global" : ""}`)}`);
|
|
2789
|
+
}
|
|
2632
2790
|
step(`Start the sidecar before Claude Code: ${cliCommand(port === 8788 ? "sidecar" : `sidecar --port ${port}`)}`);
|
|
2633
2791
|
step("The agent's Anthropic scope must allow the models Claude Code uses (its main model, and Haiku for small tasks).");
|
|
2634
2792
|
step(`Optional, the chat tool as well: ${CLAUDE_CODE_ADD_COMMAND}`);
|
|
@@ -2660,6 +2818,68 @@ function printCodexPreset(opts = {}) {
|
|
|
2660
2818
|
* Codex layers over its config when started with `--profile passcontrol`.
|
|
2661
2819
|
* `--remove` deletes that file, and only when PassControl wrote it.
|
|
2662
2820
|
*/
|
|
2821
|
+
// ── One identity per coding tool (candidate 4, plans/one-identity-per-tool.md) ──
|
|
2822
|
+
//
|
|
2823
|
+
// `configure <tool> --dedicated` gives Claude Code or Codex its OWN agent: its own
|
|
2824
|
+
// passport, budget, scope and kill switch, served by its own sidecar port, kept in
|
|
2825
|
+
// a named profile (cli/profiles.mjs). Re-running reuses the profile; it never
|
|
2826
|
+
// creates a second agent.
|
|
2827
|
+
async function prepareDedicatedProfile(tool, opts) {
|
|
2828
|
+
const port = TOOL_PROFILE_PORTS[tool];
|
|
2829
|
+
opts.port = port;
|
|
2830
|
+
const existing = readProfile(tool);
|
|
2831
|
+
if (existing?.PASSPORT_ID && existing?.PASSPORT_SECRET) {
|
|
2832
|
+
opts.port = Number(existing.SIDECAR_PORT || port);
|
|
2833
|
+
step(`Using the ${tool} profile's own agent (passport …${existing.PASSPORT_ID.slice(-8)}), sidecar port ${opts.port}.`);
|
|
2834
|
+
return;
|
|
2835
|
+
}
|
|
2836
|
+
const label = tool === "claude-code" ? "Claude Code" : "Codex";
|
|
2837
|
+
const provider = tool === "claude-code" ? "anthropic" : "openai";
|
|
2838
|
+
const name = `${label} @ ${os.hostname().split(".")[0] || "this machine"}`;
|
|
2839
|
+
if (!opts.write) {
|
|
2840
|
+
step(`With --write: creates the agent "${name}" with its own passport, saved in the ${tool} profile, served on sidecar port ${port}.`);
|
|
2841
|
+
return;
|
|
2842
|
+
}
|
|
2843
|
+
requireControlApiKey(config);
|
|
2844
|
+
// The keypair is made here and only the public half leaves, as in `agent create`.
|
|
2845
|
+
// The profile is written FIRST, so a created agent never exists without its key on
|
|
2846
|
+
// this machine; if creating it fails, the profile is removed again.
|
|
2847
|
+
const priv = ed25519.utils.randomPrivateKey();
|
|
2848
|
+
const passportId = b64url(ed25519.getPublicKey(priv));
|
|
2849
|
+
writeProfile(tool, { PASSPORT_ID: passportId, PASSPORT_SECRET: b64url(priv), PASSPORT_KEY_STORAGE: "", SIDECAR_PORT: String(port) });
|
|
2850
|
+
let created;
|
|
2851
|
+
try {
|
|
2852
|
+
created = await api("POST", "/agents", {
|
|
2853
|
+
name,
|
|
2854
|
+
passportPubkey: passportId,
|
|
2855
|
+
scopes: [{ provider, models: [defaultAllowedModelForProvider(provider)] }],
|
|
2856
|
+
});
|
|
2857
|
+
} catch (error) {
|
|
2858
|
+
fs.rmSync(profilePath(tool), { force: true });
|
|
2859
|
+
throw error;
|
|
2860
|
+
}
|
|
2861
|
+
ok(`created agent ${created.id} (${created.name}); its passport is in the ${tool} profile and was not printed`);
|
|
2862
|
+
}
|
|
2863
|
+
|
|
2864
|
+
function dedicatedSidecarHint(tool) {
|
|
2865
|
+
step(`Run its own sidecar: ${cliCommand(`sidecar --profile ${tool}`)}`);
|
|
2866
|
+
step(`Both coding tools at once, each as its own agent: ${cliCommand("sidecar --profiles claude-code,codex")}`);
|
|
2867
|
+
}
|
|
2868
|
+
|
|
2869
|
+
function profileCommand(rest, opts) {
|
|
2870
|
+
if (rest[0] !== "list") throw new Error("Usage: passcontrol profile list");
|
|
2871
|
+
const rows = listProfiles().map((p) => ({ profile: p.name, passport: p.passportId ? `…${p.passportId.slice(-8)}` : "none", port: p.port || "-" }));
|
|
2872
|
+
if (opts.json) {
|
|
2873
|
+
console.log(JSON.stringify(rows, null, 2));
|
|
2874
|
+
return;
|
|
2875
|
+
}
|
|
2876
|
+
if (!rows.length) {
|
|
2877
|
+
step(`No profiles yet. Give a coding tool its own agent: ${cliCommand("configure claude-code --dedicated --write")}`);
|
|
2878
|
+
return;
|
|
2879
|
+
}
|
|
2880
|
+
for (const r of rows) console.log(`${r.profile.padEnd(20)} passport ${r.passport.padEnd(10)} port ${r.port}`);
|
|
2881
|
+
}
|
|
2882
|
+
|
|
2663
2883
|
function configureCodex(opts = {}) {
|
|
2664
2884
|
const target = codexProfilePath();
|
|
2665
2885
|
if (opts.remove) {
|
|
@@ -2690,11 +2910,13 @@ function configureCodex(opts = {}) {
|
|
|
2690
2910
|
}
|
|
2691
2911
|
|
|
2692
2912
|
function configureMcpClient(integration, opts = {}) {
|
|
2693
|
-
|
|
2913
|
+
// Claude Code's settings only point it at the sidecar, which holds the passport
|
|
2914
|
+
// itself; requiring one here also stopped `--remove` once the config was gone.
|
|
2694
2915
|
if (integration === "claude-code") {
|
|
2695
2916
|
configureClaudeCode(opts);
|
|
2696
2917
|
return;
|
|
2697
2918
|
}
|
|
2919
|
+
requireGlobalMcpPassport();
|
|
2698
2920
|
|
|
2699
2921
|
const target = mcpClientConfigPath(integration);
|
|
2700
2922
|
const entry = passControlMcpEntry();
|
|
@@ -2726,12 +2948,17 @@ async function configureCommand(rest, opts = {}) {
|
|
|
2726
2948
|
`Unknown integration "${integration}". Use one of: ${integrationChoices()}.`
|
|
2727
2949
|
);
|
|
2728
2950
|
}
|
|
2951
|
+
if (opts.dedicated && (integration === "claude-code" || integration === "codex")) {
|
|
2952
|
+
await prepareDedicatedProfile(integration, opts);
|
|
2953
|
+
}
|
|
2729
2954
|
if (integration === "codex") {
|
|
2730
2955
|
configureCodex(opts);
|
|
2956
|
+
if (opts.dedicated) dedicatedSidecarHint(integration);
|
|
2731
2957
|
return;
|
|
2732
2958
|
}
|
|
2733
2959
|
if (isMcpIntegration(integration)) {
|
|
2734
2960
|
configureMcpClient(integration, opts);
|
|
2961
|
+
if (opts.dedicated && integration === "claude-code") dedicatedSidecarHint(integration);
|
|
2735
2962
|
return;
|
|
2736
2963
|
}
|
|
2737
2964
|
if (!supportsWrite(integration)) {
|
|
@@ -3033,11 +3260,12 @@ async function verifyCommand(rest, opts) {
|
|
|
3033
3260
|
const artifact = rest[1];
|
|
3034
3261
|
const issuer = String(opts.issuer || process.env.PASSCONTROL_ISSUER || "");
|
|
3035
3262
|
|
|
3036
|
-
if ((what !== "token" && what !== "receipt" && what !== "statement") || !artifact) {
|
|
3263
|
+
if ((what !== "token" && what !== "receipt" && what !== "statement" && what !== "session") || !artifact) {
|
|
3037
3264
|
throw new Error(
|
|
3038
3265
|
"Usage: passcontrol verify token <jwt> --audience <aud> --issuer <origin>\n" +
|
|
3039
3266
|
" passcontrol verify receipt <jws> --issuer <origin>\n" +
|
|
3040
|
-
" passcontrol verify statement <jws> --issuer <origin
|
|
3267
|
+
" passcontrol verify statement <jws> --issuer <origin>\n" +
|
|
3268
|
+
" passcontrol verify session <seal.json> [--journal <file>[,<file>]] --issuer <origin>"
|
|
3041
3269
|
);
|
|
3042
3270
|
}
|
|
3043
3271
|
if (!issuer) {
|
|
@@ -3047,6 +3275,11 @@ async function verifyCommand(rest, opts) {
|
|
|
3047
3275
|
);
|
|
3048
3276
|
}
|
|
3049
3277
|
|
|
3278
|
+
if (what === "session") {
|
|
3279
|
+
await verifySessionCommand(artifact, opts, issuer);
|
|
3280
|
+
return;
|
|
3281
|
+
}
|
|
3282
|
+
|
|
3050
3283
|
const result =
|
|
3051
3284
|
what === "token"
|
|
3052
3285
|
? await verifyAgentToken(artifact, { issuer, audience: String(opts.audience || "") })
|
|
@@ -3096,6 +3329,17 @@ async function verifyCommand(rest, opts) {
|
|
|
3096
3329
|
step(`Verdict: ${c.res?.status} (HTTP ${c.res?.http})`);
|
|
3097
3330
|
step(`Usage: ${c.use?.in ?? 0} in / ${c.use?.out ?? 0} out · ${c.cost ?? 0} µ¢`);
|
|
3098
3331
|
if (c.req) step(`Request: ${c.req.alg} ${c.req.dig} (${c.req.len} bytes)`);
|
|
3332
|
+
// Lineage is DECLARED by the client: any local process can send those
|
|
3333
|
+
// headers. Say so on the same line, so nobody reads it as passport-proven.
|
|
3334
|
+
// Printable ASCII only: a signed value is still not a terminal's to obey.
|
|
3335
|
+
if (c.ctx?.ses) {
|
|
3336
|
+
const shown = (v) => String(v).replace(/[^\x20-\x7e]/g, "?").slice(0, 128);
|
|
3337
|
+
const who = c.ctx.agt
|
|
3338
|
+
? `sub-agent ${shown(c.ctx.agt)}${c.ctx.par ? `, spawned by ${shown(c.ctx.par)}` : ""}`
|
|
3339
|
+
: "main agent";
|
|
3340
|
+
step(`Session: ${shown(c.ctx.ses)} · ${who}`);
|
|
3341
|
+
step(` declared by the client (${shown(c.ctx.cli ?? "unknown")}), not verified`);
|
|
3342
|
+
}
|
|
3099
3343
|
}
|
|
3100
3344
|
if (c.own) {
|
|
3101
3345
|
step(
|
|
@@ -3104,6 +3348,184 @@ async function verifyCommand(rest, opts) {
|
|
|
3104
3348
|
}
|
|
3105
3349
|
}
|
|
3106
3350
|
|
|
3351
|
+
// ── Session seals (sprint Q7) ───────────────────────────────────────────────
|
|
3352
|
+
|
|
3353
|
+
const SESSION_ARG_RE = /^[A-Za-z0-9._:-]{1,128}$/;
|
|
3354
|
+
const shown = (v) => String(v ?? "").replace(/[^\x20-\x7e]/g, "?").slice(0, 128);
|
|
3355
|
+
|
|
3356
|
+
/** The journal files the sidecar wrote (cli/journal.mjs): one JSON object per line. */
|
|
3357
|
+
function readJournals(spec) {
|
|
3358
|
+
const entries = [];
|
|
3359
|
+
for (const file of String(spec).split(",").map((f) => f.trim()).filter(Boolean)) {
|
|
3360
|
+
const text = fs.readFileSync(file, "utf8");
|
|
3361
|
+
for (const line of text.split("\n")) {
|
|
3362
|
+
if (!line.trim()) continue;
|
|
3363
|
+
try {
|
|
3364
|
+
entries.push(JSON.parse(line));
|
|
3365
|
+
} catch {
|
|
3366
|
+
// An unreadable line is passed through as-is, so the verifier reports the
|
|
3367
|
+
// journal as malformed instead of this command quietly skipping a call.
|
|
3368
|
+
entries.push(line);
|
|
3369
|
+
}
|
|
3370
|
+
}
|
|
3371
|
+
}
|
|
3372
|
+
return entries;
|
|
3373
|
+
}
|
|
3374
|
+
|
|
3375
|
+
async function verifySessionCommand(file, opts, issuer) {
|
|
3376
|
+
let parsed;
|
|
3377
|
+
try {
|
|
3378
|
+
parsed = JSON.parse(fs.readFileSync(String(file), "utf8"));
|
|
3379
|
+
} catch (e) {
|
|
3380
|
+
fail(`Could not read ${shown(file)}: ${e.message}`);
|
|
3381
|
+
process.exitCode = 1;
|
|
3382
|
+
return;
|
|
3383
|
+
}
|
|
3384
|
+
// Accepts the control API's response as saved ({ data: { seal, bundle } }) or
|
|
3385
|
+
// just { seal, bundle }, which is what `passcontrol seal` writes.
|
|
3386
|
+
const doc = parsed?.data && typeof parsed.data === "object" ? parsed.data : parsed;
|
|
3387
|
+
const journal = opts.journal && opts.journal !== true ? readJournals(opts.journal) : undefined;
|
|
3388
|
+
const r = await verifySession({ seal: doc?.seal, bundle: doc?.bundle, journal }, { issuer });
|
|
3389
|
+
|
|
3390
|
+
if (!r.checks.signature) {
|
|
3391
|
+
fail(`Not valid: ${FAILURE_REASONS[r.reason] ?? r.reason}`);
|
|
3392
|
+
process.exitCode = 1;
|
|
3393
|
+
return;
|
|
3394
|
+
}
|
|
3395
|
+
const c = r.claims;
|
|
3396
|
+
(r.ok ? ok : fail)(r.ok ? "Session seal is valid." : "Session seal did not pass every check.");
|
|
3397
|
+
step(`Issuer: ${shown(c.iss)}`);
|
|
3398
|
+
step(`Agent: ${shown(c.sub)}`);
|
|
3399
|
+
step(`Session: ${shown(c.ses?.id)} · declared by the client (${shown(c.ses?.src)}), not verified`);
|
|
3400
|
+
step(`Window: ${new Date(c.per?.from * 1000).toISOString()} → ${new Date(c.per?.to * 1000).toISOString()}`);
|
|
3401
|
+
step(`Covers: ${c.n} of ${c.nr} logged calls · ${c.cost} µ¢`);
|
|
3402
|
+
if (c.unp) step(` ${c.unp} call(s) could not be priced: that cost is unknown, not zero.`);
|
|
3403
|
+
if (c.unk) step(` ${c.unk} call(s) have no recorded cost and no recorded reason.`);
|
|
3404
|
+
for (const node of Array.isArray(c.tree) ? c.tree : []) {
|
|
3405
|
+
const who = node.agt ? `sub-agent ${shown(node.agt)}${node.par ? ` (spawned by ${shown(node.par)})` : ""}` : "main agent";
|
|
3406
|
+
step(` ${who}: ${node.n} call(s), ${node.cost} µ¢${node.refused ? `, ${node.refused} refused` : ""}`);
|
|
3407
|
+
}
|
|
3408
|
+
step("");
|
|
3409
|
+
|
|
3410
|
+
ok("Signature matches the issuer's published key");
|
|
3411
|
+
if (r.checks.bundle) ok(`Bundle: the root and every total recompute from its ${doc.bundle.length} receipt(s)`);
|
|
3412
|
+
else fail(`Bundle: these do not match the receipts it came with: ${r.mismatched.join(", ") || r.reason}`);
|
|
3413
|
+
if (r.checks.receipts === null) step("Receipts: not checked");
|
|
3414
|
+
else if (r.checks.receipts) ok("Receipts: every one verifies and belongs to this agent, session and window");
|
|
3415
|
+
else {
|
|
3416
|
+
fail(`Receipts: ${r.rejected.length} not accepted`);
|
|
3417
|
+
for (const x of r.rejected) step(` #${x.index} ${shown(x.id ?? "?")}: ${FAILURE_REASONS[x.reason] ?? x.reason}`);
|
|
3418
|
+
}
|
|
3419
|
+
|
|
3420
|
+
if (r.checks.journal === null) {
|
|
3421
|
+
step("No journal given. Without your own record this proves no more than a statement does:");
|
|
3422
|
+
step(" that the issuer committed to these receipts, not that it left none out.");
|
|
3423
|
+
step(" Pass --journal with the file your sidecar printed when it started.");
|
|
3424
|
+
} else if (r.reason === "malformed_journal") {
|
|
3425
|
+
fail("Journal: could not be read as a list of receipt ids.");
|
|
3426
|
+
} else if (r.checks.journal) {
|
|
3427
|
+
ok("Journal: every call your sidecar recorded is in the seal");
|
|
3428
|
+
} else {
|
|
3429
|
+
fail(`Journal: ${r.missing.length} call(s) your sidecar recorded are missing from the seal:`);
|
|
3430
|
+
for (const id of r.missing) step(` ${shown(id)}`);
|
|
3431
|
+
step(" Missing means not in this seal. The gateway's log write can fail on its own,");
|
|
3432
|
+
step(" so a missing call can be a lost record as easily as one left out.");
|
|
3433
|
+
}
|
|
3434
|
+
if (r.otherSessions) {
|
|
3435
|
+
step(`Your journal also holds ${r.otherSessions} call(s) from other sessions of the same sidecar run; not checked against this seal.`);
|
|
3436
|
+
}
|
|
3437
|
+
if (r.unjournaled.length) {
|
|
3438
|
+
step(`In the seal but not in your journal (reported, not a failure): ${r.unjournaled.length}`);
|
|
3439
|
+
for (const x of r.unjournaled) {
|
|
3440
|
+
step(` ${shown(x.id)}${x.why === "failover_predecessor" ? " (an earlier attempt of a failed-over call)" : ""}`);
|
|
3441
|
+
}
|
|
3442
|
+
}
|
|
3443
|
+
if (!r.ok) process.exitCode = 1;
|
|
3444
|
+
}
|
|
3445
|
+
|
|
3446
|
+
async function sealCommand(rest, opts) {
|
|
3447
|
+
const session = rest[0];
|
|
3448
|
+
if (!session || !SESSION_ARG_RE.test(session)) {
|
|
3449
|
+
throw new Error("Usage: passcontrol seal <session> --agent <agent-id> [--out FILE]");
|
|
3450
|
+
}
|
|
3451
|
+
if (!opts.agent || opts.agent === true) {
|
|
3452
|
+
throw new Error("Name the agent: passcontrol seal <session> --agent <agent-id> (see `passcontrol sessions`).");
|
|
3453
|
+
}
|
|
3454
|
+
let data;
|
|
3455
|
+
try {
|
|
3456
|
+
data = await api("POST", `/sessions/${encodeURIComponent(session)}/seal`, { agent_id: String(opts.agent) });
|
|
3457
|
+
} catch (e) {
|
|
3458
|
+
// api() leads with the status, then the error code. The route's own 404 carries
|
|
3459
|
+
// `not_found`; a gateway without the route (self-host: sealing is a hosted
|
|
3460
|
+
// capability, the format and verifier are not) answers with no code at all.
|
|
3461
|
+
const message = String(e?.message || "");
|
|
3462
|
+
if (/^404 not_found\b/.test(message)) {
|
|
3463
|
+
throw new Error(`No session ${session} for agent ${opts.agent} on this gateway (see \`passcontrol sessions\`).`);
|
|
3464
|
+
}
|
|
3465
|
+
if (/^404\b/.test(message)) {
|
|
3466
|
+
throw new Error(
|
|
3467
|
+
"This gateway does not seal sessions. Sealing is a hosted capability; checking a seal works anywhere:\n" +
|
|
3468
|
+
" passcontrol verify session <seal.json> --journal <file> --issuer <origin>"
|
|
3469
|
+
);
|
|
3470
|
+
}
|
|
3471
|
+
throw e;
|
|
3472
|
+
}
|
|
3473
|
+
const file = String(opts.out && opts.out !== true ? opts.out : `session-${session}.seal.json`);
|
|
3474
|
+
// It is spend and call volume: owner-only, like the journal it is checked against.
|
|
3475
|
+
fs.writeFileSync(file, JSON.stringify({ seal: data.seal, bundle: data.bundle }, null, 2) + "\n", { mode: 0o600 });
|
|
3476
|
+
fs.chmodSync(file, 0o600);
|
|
3477
|
+
ok(`Sealed ${data.bundle?.length ?? 0} receipt(s) → ${file}`);
|
|
3478
|
+
// The issuer the seal names, not the gateway just called: the two can differ (a
|
|
3479
|
+
// self-host behind a proxy), and the issuer is the one a verifier must trust.
|
|
3480
|
+
// Read without verifying, only to print a suggestion; `verify session` checks it.
|
|
3481
|
+
let issuer = requireControlGateway(config);
|
|
3482
|
+
try {
|
|
3483
|
+
const claims = JSON.parse(Buffer.from(String(data.seal).split(".")[1] ?? "", "base64url").toString("utf8"));
|
|
3484
|
+
if (typeof claims?.iss === "string") issuer = shown(claims.iss);
|
|
3485
|
+
} catch {
|
|
3486
|
+
// Not a JWS: verify session will say so. Keep the gateway as the suggestion.
|
|
3487
|
+
}
|
|
3488
|
+
step(`Check it: passcontrol verify session ${file} --journal <your sidecar journal> --issuer ${issuer}`);
|
|
3489
|
+
}
|
|
3490
|
+
|
|
3491
|
+
async function sessionsCommand(opts) {
|
|
3492
|
+
let rows;
|
|
3493
|
+
try {
|
|
3494
|
+
rows = await api(
|
|
3495
|
+
"GET",
|
|
3496
|
+
controlPath("/sessions", { agent_id: opts.agent === true ? undefined : opts.agent, limit: safeLimit(opts.limit) })
|
|
3497
|
+
);
|
|
3498
|
+
} catch (e) {
|
|
3499
|
+
if (/^404\b/.test(String(e?.message || ""))) {
|
|
3500
|
+
step("This gateway does not serve sessions. Verifying a seal works anywhere:");
|
|
3501
|
+
step(" passcontrol verify session <seal.json> --journal <file> --issuer <origin>");
|
|
3502
|
+
return;
|
|
3503
|
+
}
|
|
3504
|
+
throw e;
|
|
3505
|
+
}
|
|
3506
|
+
if (opts.json) {
|
|
3507
|
+
console.log(JSON.stringify(rows, null, 2));
|
|
3508
|
+
return;
|
|
3509
|
+
}
|
|
3510
|
+
if (!Array.isArray(rows) || rows.length === 0) {
|
|
3511
|
+
step("No sessions yet. Calls appear here once Claude Code or Codex (or a sidecar run) declares one.");
|
|
3512
|
+
return;
|
|
3513
|
+
}
|
|
3514
|
+
step("Sessions are declared by the client: they group calls, they do not prove who made them.");
|
|
3515
|
+
console.table(
|
|
3516
|
+
rows.map((row) => ({
|
|
3517
|
+
session: shown(row.session_id).slice(0, 36),
|
|
3518
|
+
via: row.client_kind,
|
|
3519
|
+
agent: String(row.agent_id ?? "").slice(0, 8),
|
|
3520
|
+
calls: row.calls,
|
|
3521
|
+
"sub-agents": row.subagents,
|
|
3522
|
+
refused: row.refused,
|
|
3523
|
+
cost: usd(row.cost_microcents) + (Number(row.unknown_cost) ? ` + ${row.unknown_cost} unknown` : ""),
|
|
3524
|
+
last: String(row.last_at ?? "").slice(0, 19),
|
|
3525
|
+
}))
|
|
3526
|
+
);
|
|
3527
|
+
}
|
|
3528
|
+
|
|
3107
3529
|
/**
|
|
3108
3530
|
* The chain of signed spend statements for this workspace.
|
|
3109
3531
|
*
|
|
@@ -3946,6 +4368,20 @@ async function main(argv = process.argv.slice(2), runtime = {}) {
|
|
|
3946
4368
|
const { opts, rest } = parseArgv(argv);
|
|
3947
4369
|
const [command, ...commandRest] = rest;
|
|
3948
4370
|
|
|
4371
|
+
// First, before the update check or anything else that could print or wait:
|
|
4372
|
+
// Claude Code shows this command's whole stdout as its status line, runs it
|
|
4373
|
+
// after every assistant message, and cancels a run that is still going.
|
|
4374
|
+
if (command === "statusline") {
|
|
4375
|
+
console.log(await statuslineCommand(opts));
|
|
4376
|
+
return;
|
|
4377
|
+
}
|
|
4378
|
+
|
|
4379
|
+
// Also before the update check: a full-screen board owns the terminal from its
|
|
4380
|
+
// first frame, and the check's cache would be the one file `watch` ever wrote.
|
|
4381
|
+
if (command === "watch" && !opts.help) {
|
|
4382
|
+
process.exit(await runWatch({ port: sidecarPort(opts) }));
|
|
4383
|
+
}
|
|
4384
|
+
|
|
3949
4385
|
// Started here and awaited at the very end, so the registry lookup overlaps
|
|
3950
4386
|
// the command instead of being tacked onto the exit. On anything that touches
|
|
3951
4387
|
// the network — which is most of this CLI — it costs nothing measurable, and
|
|
@@ -4047,6 +4483,9 @@ async function main(argv = process.argv.slice(2), runtime = {}) {
|
|
|
4047
4483
|
" `passcontrol login` now does the same thing with YOUR agent rather than a\n" +
|
|
4048
4484
|
" shared demo one: a governed call and a signed receipt you can verify."
|
|
4049
4485
|
);
|
|
4486
|
+
case "profile":
|
|
4487
|
+
profileCommand(commandRest, opts);
|
|
4488
|
+
break;
|
|
4050
4489
|
case "sidecar":
|
|
4051
4490
|
await sidecarCommand(commandRest, opts);
|
|
4052
4491
|
break;
|
|
@@ -4075,6 +4514,12 @@ async function main(argv = process.argv.slice(2), runtime = {}) {
|
|
|
4075
4514
|
case "statements":
|
|
4076
4515
|
await statementsCommand(opts);
|
|
4077
4516
|
break;
|
|
4517
|
+
case "sessions":
|
|
4518
|
+
await sessionsCommand(opts);
|
|
4519
|
+
break;
|
|
4520
|
+
case "seal":
|
|
4521
|
+
await sealCommand(commandRest, opts);
|
|
4522
|
+
break;
|
|
4078
4523
|
case "kill":
|
|
4079
4524
|
await killCommand(commandRest);
|
|
4080
4525
|
break;
|