passcontrol 0.5.3 → 0.6.1
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 +2 -2
- package/README.md +90 -22
- package/bin/passcontrol.mjs +270 -73
- package/cli/config.mjs +124 -1
- package/cli/mcp/gateway.mjs +4 -4
- package/cli/presets.mjs +1 -0
- package/cli/proxy-policy.mjs +276 -0
- package/cli/sidecar.mjs +186 -9
- package/cli/visa-client.mjs +10 -2
- package/package.json +11 -3
- package/sdk/README.md +152 -0
- package/sdk/control.d.ts +103 -0
- package/sdk/control.js +102 -0
- package/sdk/gateway.d.ts +22 -0
- package/sdk/gateway.js +66 -0
- package/sdk/index.d.ts +6 -0
- package/sdk/index.js +20 -0
- package/sdk/passcontrol.d.ts +47 -0
- package/sdk/passcontrol.js +197 -0
- package/sdk/verify.d.ts +182 -0
- package/sdk/verify.js +238 -0
package/bin/passcontrol.mjs
CHANGED
|
@@ -24,6 +24,9 @@ import {
|
|
|
24
24
|
ok,
|
|
25
25
|
redact,
|
|
26
26
|
requireControlApiKey,
|
|
27
|
+
requireControlGateway,
|
|
28
|
+
operatorEnv,
|
|
29
|
+
requirePassportGateway,
|
|
27
30
|
requirePassport,
|
|
28
31
|
step,
|
|
29
32
|
warn,
|
|
@@ -125,48 +128,65 @@ function cliCommand(args = "") {
|
|
|
125
128
|
|
|
126
129
|
function usage() {
|
|
127
130
|
const cmd = cliPrefix();
|
|
128
|
-
return `${heading(
|
|
131
|
+
return `${heading(`PassControl ${CLI_VERSION}`)}
|
|
132
|
+
Governed identity and credentials for AI agents.
|
|
129
133
|
|
|
130
134
|
${heading("Usage:")}
|
|
131
135
|
${cmd} show cockpit status
|
|
132
|
-
${cmd}
|
|
133
|
-
|
|
136
|
+
${cmd} <command> [options]
|
|
137
|
+
|
|
138
|
+
${heading("Quick start")}
|
|
139
|
+
${cmd} init [--global] configure this project
|
|
134
140
|
${cmd} start [--dashboard-only] start the whole local stack (dashboard + Supabase + Redis)
|
|
141
|
+
${cmd} open start if needed and open the Control Tower
|
|
142
|
+
${cmd} try run the 60-second keyless guided demo
|
|
143
|
+
|
|
144
|
+
${heading("Operate")}
|
|
145
|
+
${cmd} status [--no-network] [--json]
|
|
146
|
+
show active config and instance state
|
|
147
|
+
${cmd} doctor [--deep] [--fix] diagnose setup and repair a stopped dashboard
|
|
148
|
+
${cmd} call "hi" mint a visa and make a governed model call
|
|
149
|
+
${cmd} sidecar [--port 8788] [--allow-connect host[,host]]
|
|
150
|
+
start the local agent bridge
|
|
151
|
+
|
|
152
|
+
${heading("Manage")}
|
|
153
|
+
${cmd} agent list [--json] list agents
|
|
154
|
+
${cmd} agent create <name> create an agent passport
|
|
155
|
+
${cmd} agent rotate <id> [--grace <seconds>]
|
|
156
|
+
rotate locally and reveal the new secret once
|
|
157
|
+
${cmd} agent suspend <id> suspend an agent
|
|
158
|
+
${cmd} agent resume <id> resume an agent
|
|
159
|
+
${cmd} agent revoke <id> permanently revoke an agent
|
|
160
|
+
${cmd} spend [--json] show fleet and per-agent spend
|
|
161
|
+
${cmd} audit [--limit 20] [--json]
|
|
162
|
+
show operator audit history
|
|
163
|
+
${cmd} logs [--limit 20] [--json]
|
|
164
|
+
show governed call logs
|
|
165
|
+
${cmd} kill on|off toggle the tenant kill switch
|
|
166
|
+
|
|
167
|
+
${heading("Integrate")}
|
|
168
|
+
${cmd} env [integration] print settings without writing anything
|
|
169
|
+
${cmd} configure <integration> [--write] [--force]
|
|
170
|
+
preview or write integration config
|
|
171
|
+
${cmd} mcp start the stdio MCP server
|
|
172
|
+
integrations: ${integrationChoices()}
|
|
173
|
+
|
|
174
|
+
${heading("Trust")}
|
|
175
|
+
${cmd} keygen instance create the receipt-signing key
|
|
176
|
+
${cmd} verify receipt <jws> --issuer <origin>
|
|
177
|
+
verify a signed call receipt
|
|
178
|
+
${cmd} verify token <jwt> --audience <aud> --issuer <origin>
|
|
179
|
+
verify an agent-to-agent token
|
|
180
|
+
|
|
181
|
+
${heading("Local stack")}
|
|
182
|
+
${cmd} setup [--no-open] [--port-offset N] [--app-dir DIR]
|
|
183
|
+
clone if needed, start services, open dashboard
|
|
135
184
|
${cmd} stop [--dashboard-only] stop the whole local stack (dashboard + Supabase + Redis)
|
|
136
185
|
${cmd} restart restart the CLI-managed local dashboard
|
|
137
186
|
${cmd} local-logs [--follow] show local dashboard logs
|
|
138
|
-
${cmd} doctor [--deep] [--fix] check local setup and repair a stopped dashboard
|
|
139
187
|
${cmd} reset --local --confirm RESET
|
|
140
188
|
destroy and recreate the local stack
|
|
141
|
-
${cmd} setup [--no-open] [--port-offset N] [--app-dir DIR]
|
|
142
|
-
clone the app (if needed), start local services, open the dashboard
|
|
143
|
-
--app-dir repoints the CLI and is remembered
|
|
144
189
|
${cmd} unlink forget the remembered app checkout
|
|
145
|
-
${cmd} try 60-second demo: governed keyless call + kill switch (no key)
|
|
146
|
-
${cmd} call "hi" mint a visa and call a model
|
|
147
|
-
${cmd} sidecar [--port 8788] start the local agent bridge
|
|
148
|
-
${cmd} mcp start the local stdio MCP server
|
|
149
|
-
${cmd} configure <integration> [--write] [--force]
|
|
150
|
-
set up an integration: previews the config, and
|
|
151
|
-
--write creates it for aider|claude-desktop|cursor
|
|
152
|
-
${cmd} env [integration] print the same settings without writing anything
|
|
153
|
-
(defaults to generic)
|
|
154
|
-
<integration>: ${integrationChoices()}
|
|
155
|
-
${cmd} agent list list agents
|
|
156
|
-
${cmd} agent create <name> create an agent passport
|
|
157
|
-
${cmd} agent suspend <id> suspend an agent
|
|
158
|
-
${cmd} agent resume <id> resume an agent
|
|
159
|
-
${cmd} agent revoke <id> revoke an agent
|
|
160
|
-
${cmd} spend show fleet + per-agent spend
|
|
161
|
-
${cmd} audit [--limit 20] show admin audit trail
|
|
162
|
-
${cmd} logs [--limit 20] show gateway call logs
|
|
163
|
-
${cmd} kill on|off toggle tenant kill switch
|
|
164
|
-
${cmd} keygen instance generate the deployment's receipt-signing key
|
|
165
|
-
${cmd} verify receipt <jws> --issuer <origin>
|
|
166
|
-
check a signed call receipt (no account needed)
|
|
167
|
-
${cmd} verify token <jwt> --audience <aud> --issuer <origin>
|
|
168
|
-
check an agent-to-agent token
|
|
169
|
-
${cmd} open start (if needed) and open the dashboard
|
|
170
190
|
|
|
171
191
|
${heading("Config:")}
|
|
172
192
|
Env vars win, then nearest .passcontrol, then ~/.config/passcontrol/config.
|
|
@@ -178,6 +198,30 @@ ${heading("Config:")}
|
|
|
178
198
|
`;
|
|
179
199
|
}
|
|
180
200
|
|
|
201
|
+
function agentUsage() {
|
|
202
|
+
const cmd = cliPrefix();
|
|
203
|
+
return `${heading("Manage agent passports")}
|
|
204
|
+
|
|
205
|
+
${heading("Usage:")}
|
|
206
|
+
${cmd} agent list
|
|
207
|
+
${cmd} agent create <name> [--provider <provider>] [--scope <model-pattern>]
|
|
208
|
+
${cmd} agent rotate <id> [--grace <seconds>]
|
|
209
|
+
${cmd} agent suspend <id>
|
|
210
|
+
${cmd} agent resume <id>
|
|
211
|
+
${cmd} agent revoke <id>
|
|
212
|
+
|
|
213
|
+
${heading("Examples")}
|
|
214
|
+
${cmd} agent create prod-summarizer --provider anthropic --scope 'claude-*'
|
|
215
|
+
${cmd} agent rotate <id> --grace 3600
|
|
216
|
+
${cmd} agent suspend <id>
|
|
217
|
+
|
|
218
|
+
Create and rotate generate the Ed25519 private key on this machine. Only the
|
|
219
|
+
public key crosses the control API. The private key is shown once; store it
|
|
220
|
+
before leaving the command. During rotation grace, both old and new keys work.
|
|
221
|
+
Revocation is permanent; suspension is reversible.
|
|
222
|
+
`;
|
|
223
|
+
}
|
|
224
|
+
|
|
181
225
|
function assertProvider(provider) {
|
|
182
226
|
if (!PROVIDERS.includes(provider)) {
|
|
183
227
|
throw new Error(`Unknown provider "${provider}". Use one of: ${PROVIDERS.join(", ")}.`);
|
|
@@ -211,34 +255,61 @@ async function gatewayStatus(noNetwork = false) {
|
|
|
211
255
|
}
|
|
212
256
|
}
|
|
213
257
|
|
|
214
|
-
async function printCockpit({ noNetwork = false } = {}) {
|
|
258
|
+
async function printCockpit({ noNetwork = false, json = false } = {}) {
|
|
215
259
|
const gateway = await gatewayStatus(noNetwork);
|
|
216
260
|
const passportConfigured = Boolean(config.passportId && config.passportSecret);
|
|
217
261
|
const adminConfigured = Boolean(config.apiKey);
|
|
262
|
+
const dashboard = dashboardStatusLabel(gateway, noNetwork);
|
|
263
|
+
const app = appRootLabel();
|
|
264
|
+
const configFile = configPathLabel(config.sources);
|
|
265
|
+
|
|
266
|
+
if (json) {
|
|
267
|
+
console.log(JSON.stringify({
|
|
268
|
+
version: CLI_VERSION,
|
|
269
|
+
gateway: { url: config.gateway, state: gateway.label, healthy: gateway.ok },
|
|
270
|
+
dashboard: { state: dashboard },
|
|
271
|
+
app: { state: app },
|
|
272
|
+
config: {
|
|
273
|
+
source: configFile,
|
|
274
|
+
provider: config.provider,
|
|
275
|
+
model: config.model,
|
|
276
|
+
passport_configured: passportConfigured,
|
|
277
|
+
control_api_key_configured: adminConfigured,
|
|
278
|
+
},
|
|
279
|
+
}, null, 2));
|
|
280
|
+
return;
|
|
281
|
+
}
|
|
218
282
|
|
|
219
283
|
console.log(`${heading("PassControl")}\n`);
|
|
220
284
|
console.log(formatLabel("Gateway", `${gateway.label} ${config.gateway}`));
|
|
221
|
-
console.log(formatLabel("Dashboard",
|
|
222
|
-
console.log(formatLabel("App",
|
|
223
|
-
console.log(formatLabel("Config",
|
|
285
|
+
console.log(formatLabel("Dashboard", dashboard));
|
|
286
|
+
console.log(formatLabel("App", app));
|
|
287
|
+
console.log(formatLabel("Config", configFile));
|
|
224
288
|
console.log(formatLabel("Provider", config.provider));
|
|
225
289
|
console.log(formatLabel("Model", config.model));
|
|
226
290
|
console.log(formatLabel("Passport", passportConfigured ? redact(config.passportId) : "missing"));
|
|
227
291
|
console.log(formatLabel("Admin key", adminConfigured ? redact(config.apiKey, 6) : "missing"));
|
|
228
292
|
console.log(`${formatLabel("Sidecar", `foreground command (\`${cliCommand("sidecar")}\`)`)}\n`);
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
293
|
+
const next = [];
|
|
294
|
+
if (config.sources.length === 0) {
|
|
295
|
+
next.push(["init", "configure this project"]);
|
|
296
|
+
}
|
|
297
|
+
if (gateway.ok === false) {
|
|
298
|
+
next.push(["start", "start the local control plane"]);
|
|
299
|
+
next.push(["doctor", "diagnose why the gateway is unavailable"]);
|
|
300
|
+
} else if (!passportConfigured) {
|
|
301
|
+
next.push(["agent create <name>", "issue a governed agent passport"]);
|
|
302
|
+
next.push(["open", "finish setup in the Control Tower"]);
|
|
303
|
+
} else {
|
|
304
|
+
next.push(['call "hi"', "test a governed model call"]);
|
|
305
|
+
next.push(["agent list", "inspect the configured fleet"]);
|
|
306
|
+
next.push(["open", "open the Control Tower"]);
|
|
307
|
+
}
|
|
308
|
+
|
|
309
|
+
console.log(heading("Next:"));
|
|
310
|
+
for (const [command, description] of next.slice(0, 3)) {
|
|
311
|
+
console.log(` ${cliCommand(command).padEnd(34)} ${description}`);
|
|
312
|
+
}
|
|
242
313
|
}
|
|
243
314
|
|
|
244
315
|
function appConfigDir(env = process.env) {
|
|
@@ -359,12 +430,28 @@ function checkDockerDaemon() {
|
|
|
359
430
|
};
|
|
360
431
|
}
|
|
361
432
|
try {
|
|
362
|
-
|
|
433
|
+
// Docker Desktop can leave its CLI socket present while the engine is
|
|
434
|
+
// wedged. A diagnostic command must report that state, not hang every
|
|
435
|
+
// onboarding/release check indefinitely — hence a bound.
|
|
436
|
+
//
|
|
437
|
+
// The bound is generous because the failure it must not cause is worse than
|
|
438
|
+
// the one it prevents. At 2s this reported "not running" about a daemon that
|
|
439
|
+
// was merely COLD: it failed the public repo's local-smoke CI job on a runner
|
|
440
|
+
// where Docker was available throughout, and it would tell a first-time user
|
|
441
|
+
// on a slow laptop to go start something already running. A wedged engine
|
|
442
|
+
// still gets caught; it just takes fifteen seconds to say so.
|
|
443
|
+
execFileSync("docker", ["info"], { stdio: "ignore", timeout: 15_000 });
|
|
363
444
|
return { ok: true, message: "Docker daemon: running." };
|
|
364
|
-
} catch {
|
|
445
|
+
} catch (error) {
|
|
446
|
+
// A timeout and a stopped daemon need different things from the reader, so
|
|
447
|
+
// they must not share a sentence. `execFileSync` surfaces the timeout kill as
|
|
448
|
+
// ETIMEDOUT, or as the signal it used when the platform reports no code.
|
|
449
|
+
const timedOut = error?.code === "ETIMEDOUT" || error?.signal === "SIGTERM";
|
|
365
450
|
return {
|
|
366
451
|
ok: false,
|
|
367
|
-
message:
|
|
452
|
+
message: timedOut
|
|
453
|
+
? "Docker daemon: did not respond within 15s. The engine may still be starting — wait and re-run. If it persists, Docker is wedged: restart Docker Desktop."
|
|
454
|
+
: "Docker daemon: not running. Fix: start Docker Desktop and wait for the engine to become ready.",
|
|
368
455
|
};
|
|
369
456
|
}
|
|
370
457
|
}
|
|
@@ -1039,12 +1126,17 @@ async function initCommand(opts) {
|
|
|
1039
1126
|
}
|
|
1040
1127
|
}
|
|
1041
1128
|
|
|
1129
|
+
// Destination first, passport second. The signature this produces is the
|
|
1130
|
+
// passport proving itself and carries no audience, so handing it to the wrong
|
|
1131
|
+
// host is the whole compromise — see `requirePassportGateway`. Validating here
|
|
1132
|
+
// covers every minting caller, `doctor --deep` and `try` included.
|
|
1042
1133
|
async function mintVisa(current = config) {
|
|
1134
|
+
const origin = requirePassportGateway(current);
|
|
1043
1135
|
const { passportId, passportSecret } = requirePassport(current);
|
|
1044
1136
|
const payloadObj = { passport_id: passportId, ts: Date.now(), nonce: crypto.randomUUID() };
|
|
1045
1137
|
const payload = b64url(new TextEncoder().encode(JSON.stringify(payloadObj)));
|
|
1046
1138
|
const signature = b64url(ed25519.sign(fromB64url(payload), fromB64url(passportSecret)));
|
|
1047
|
-
const res = await fetch(`${
|
|
1139
|
+
const res = await fetch(`${origin}/api/auth/challenge`, {
|
|
1048
1140
|
method: "POST",
|
|
1049
1141
|
headers: { "content-type": "application/json" },
|
|
1050
1142
|
body: JSON.stringify({ payload, signature }),
|
|
@@ -1109,15 +1201,19 @@ async function callCommand(rest, opts) {
|
|
|
1109
1201
|
assertProvider(provider);
|
|
1110
1202
|
const model = activeModel(provider, opts);
|
|
1111
1203
|
const prompt = rest.join(" ") || process.env.PROMPT || "Say hello in exactly 3 words.";
|
|
1204
|
+
// Before `requirePassport`, and before the banner: this line used to print
|
|
1205
|
+
// `config.gateway` verbatim, so `https://admin:hunter2@host` put the password
|
|
1206
|
+
// on the terminal and into any log scraping it.
|
|
1207
|
+
const origin = requirePassportGateway(config);
|
|
1112
1208
|
requirePassport(config);
|
|
1113
|
-
step(`${provider}/${model} via ${
|
|
1209
|
+
step(`${provider}/${model} via ${origin}`);
|
|
1114
1210
|
step(`prompt: ${prompt}\n`);
|
|
1115
1211
|
|
|
1116
1212
|
const { visa, expires_in } = await mintVisa(config);
|
|
1117
1213
|
ok(`minted visa (expires in ${expires_in ?? 300}s)`);
|
|
1118
1214
|
|
|
1119
1215
|
const { path: proxyPath, body } = requestFor(provider, model, prompt);
|
|
1120
|
-
const res = await fetch(`${
|
|
1216
|
+
const res = await fetch(`${origin}/api/v1/${provider}/${proxyPath}`, {
|
|
1121
1217
|
method: "POST",
|
|
1122
1218
|
headers: { "content-type": "application/json", authorization: `Bearer ${visa}` },
|
|
1123
1219
|
body: JSON.stringify(body),
|
|
@@ -1132,7 +1228,9 @@ async function callCommand(rest, opts) {
|
|
|
1132
1228
|
// keyless `demo` provider, then arms the kill switch to show the same call
|
|
1133
1229
|
// blocked. Everything is real (visa, scope, budget, kill) except the model.
|
|
1134
1230
|
async function tryCommand() {
|
|
1135
|
-
|
|
1231
|
+
// Covers the demo proxy call AND the kill-switch PUT below, which builds its
|
|
1232
|
+
// own control-plane URL rather than going through the guarded `api()`.
|
|
1233
|
+
const gateway = requirePassportGateway(config);
|
|
1136
1234
|
const demo = { gateway, passportId: DEMO_PASSPORT_ID, passportSecret: DEMO_PASSPORT_SECRET };
|
|
1137
1235
|
|
|
1138
1236
|
const demoCall = async () => {
|
|
@@ -1204,7 +1302,7 @@ async function tryCommand() {
|
|
|
1204
1302
|
const json = await res.json().catch(() => ({}));
|
|
1205
1303
|
const text = json?.choices?.[0]?.message?.content ?? JSON.stringify(json);
|
|
1206
1304
|
const usage = json?.usage ?? {};
|
|
1207
|
-
ok("Governed keyless call succeeded — the passport signed
|
|
1305
|
+
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:");
|
|
1208
1306
|
console.log(`\n ${text}\n`);
|
|
1209
1307
|
step(`tokens: ${usage.total_tokens ?? "?"} (prompt ${usage.prompt_tokens ?? "?"} + completion ${usage.completion_tokens ?? "?"})`);
|
|
1210
1308
|
|
|
@@ -1230,8 +1328,13 @@ async function tryCommand() {
|
|
|
1230
1328
|
}
|
|
1231
1329
|
|
|
1232
1330
|
async function api(method, pathPart, body) {
|
|
1331
|
+
// Destination first, key second — same order and same reason as the SDK's
|
|
1332
|
+
// ControlClient. `config.gateway` is whatever PASSCONTROL_GATEWAY said, and
|
|
1333
|
+
// this is the one place a long-lived fleet-wide `pc_` key goes on the wire, so
|
|
1334
|
+
// the URL is built from the validated origin rather than from that string.
|
|
1335
|
+
const origin = requireControlGateway(config);
|
|
1233
1336
|
const apiKey = requireControlApiKey(config);
|
|
1234
|
-
const res = await fetch(`${
|
|
1337
|
+
const res = await fetch(`${origin}/api/control/v1${pathPart}`, {
|
|
1235
1338
|
method,
|
|
1236
1339
|
headers: {
|
|
1237
1340
|
authorization: `Bearer ${apiKey}`,
|
|
@@ -1278,15 +1381,15 @@ async function agentCommand(rest, opts) {
|
|
|
1278
1381
|
switch (sub) {
|
|
1279
1382
|
case "list": {
|
|
1280
1383
|
const agents = await api("GET", "/agents");
|
|
1281
|
-
|
|
1282
|
-
agents.map((a) => ({
|
|
1384
|
+
const rows = agents.map((a) => ({
|
|
1283
1385
|
id: a.id,
|
|
1284
1386
|
name: a.name,
|
|
1285
1387
|
status: a.status,
|
|
1286
1388
|
tokens: a.spent_tokens,
|
|
1287
1389
|
usd: a.spent_microcents === undefined ? undefined : usd(a.spent_microcents),
|
|
1288
|
-
}))
|
|
1289
|
-
);
|
|
1390
|
+
}));
|
|
1391
|
+
if (opts.json) console.log(JSON.stringify(rows, null, 2));
|
|
1392
|
+
else console.table(rows);
|
|
1290
1393
|
break;
|
|
1291
1394
|
}
|
|
1292
1395
|
case "create": {
|
|
@@ -1322,13 +1425,57 @@ async function agentCommand(rest, opts) {
|
|
|
1322
1425
|
if (!args[0]) throw new Error("Usage: passcontrol agent revoke <id>");
|
|
1323
1426
|
console.log(await api("DELETE", `/agents/${encodeURIComponent(args[0])}`));
|
|
1324
1427
|
break;
|
|
1428
|
+
// Retire this agent's key and install a new one, keeping the agent — its id,
|
|
1429
|
+
// budgets, audit history and receipts all stay put.
|
|
1430
|
+
//
|
|
1431
|
+
// The keypair is generated HERE, on the operator's machine, and only the
|
|
1432
|
+
// PUBLIC half is sent. That is the product: the gateway has never held a
|
|
1433
|
+
// passport private key and this command must not be the first thing to
|
|
1434
|
+
// change that.
|
|
1435
|
+
case "rotate": {
|
|
1436
|
+
if (!args[0]) {
|
|
1437
|
+
throw new Error("Usage: passcontrol agent rotate <id> [--grace <seconds>]");
|
|
1438
|
+
}
|
|
1439
|
+
const grace = opts.grace === undefined ? undefined : Number(opts.grace);
|
|
1440
|
+
if (grace !== undefined && (!Number.isFinite(grace) || grace < 0)) {
|
|
1441
|
+
throw new Error("--grace must be a non-negative number of seconds.");
|
|
1442
|
+
}
|
|
1443
|
+
const priv = ed25519.utils.randomPrivateKey();
|
|
1444
|
+
const passportId = b64url(ed25519.getPublicKey(priv));
|
|
1445
|
+
const result = await api("POST", `/agents/${encodeURIComponent(args[0])}/rotate`, {
|
|
1446
|
+
passportPubkey: passportId,
|
|
1447
|
+
...(grace === undefined ? {} : { graceSeconds: grace }),
|
|
1448
|
+
});
|
|
1449
|
+
|
|
1450
|
+
ok(`rotated agent ${args[0]}`);
|
|
1451
|
+
// Printed BEFORE the deadline, and never written to a file. A rotation
|
|
1452
|
+
// that silently overwrote .passcontrol would destroy the only copy of the
|
|
1453
|
+
// key that is still working — mid-window, which is the outage the window
|
|
1454
|
+
// exists to prevent. The operator moves it deliberately.
|
|
1455
|
+
step("Store these - the secret is shown once and is the agent's new passport:");
|
|
1456
|
+
console.log(` PASSPORT_ID=${passportId}`);
|
|
1457
|
+
console.log(` PASSPORT_SECRET=${b64url(priv)}`);
|
|
1458
|
+
const until = result?.previous_valid_until;
|
|
1459
|
+
step(
|
|
1460
|
+
until
|
|
1461
|
+
? `The OLD key keeps working until ${until}. Both keys authenticate until then — deploy the new one before it passes.`
|
|
1462
|
+
: "The old key stops working immediately."
|
|
1463
|
+
);
|
|
1464
|
+
break;
|
|
1465
|
+
}
|
|
1325
1466
|
default:
|
|
1326
|
-
throw new Error(
|
|
1467
|
+
throw new Error(
|
|
1468
|
+
"Usage: passcontrol agent list|create <name>|suspend <id>|resume <id>|revoke <id>|rotate <id> [--grace <seconds>]"
|
|
1469
|
+
);
|
|
1327
1470
|
}
|
|
1328
1471
|
}
|
|
1329
1472
|
|
|
1330
|
-
async function spendCommand() {
|
|
1473
|
+
async function spendCommand(opts = {}) {
|
|
1331
1474
|
const data = await api("GET", "/spend");
|
|
1475
|
+
if (opts.json) {
|
|
1476
|
+
console.log(JSON.stringify(data, null, 2));
|
|
1477
|
+
return;
|
|
1478
|
+
}
|
|
1332
1479
|
console.log(`fleet: ${data.fleet.spent_tokens} tokens · ${usd(data.fleet.spent_microcents)}`);
|
|
1333
1480
|
console.table(
|
|
1334
1481
|
data.agents.map((agent) => ({
|
|
@@ -1342,6 +1489,10 @@ async function spendCommand() {
|
|
|
1342
1489
|
|
|
1343
1490
|
async function auditCommand(opts) {
|
|
1344
1491
|
const events = await api("GET", controlPath("/audit", { limit: safeLimit(opts.limit) }));
|
|
1492
|
+
if (opts.json) {
|
|
1493
|
+
console.log(JSON.stringify(events, null, 2));
|
|
1494
|
+
return;
|
|
1495
|
+
}
|
|
1345
1496
|
console.table(
|
|
1346
1497
|
events.map((event) => ({
|
|
1347
1498
|
at: event.created_at,
|
|
@@ -1361,6 +1512,10 @@ async function logsCommand(opts) {
|
|
|
1361
1512
|
status: opts.status,
|
|
1362
1513
|
})
|
|
1363
1514
|
);
|
|
1515
|
+
if (opts.json) {
|
|
1516
|
+
console.log(JSON.stringify(rows, null, 2));
|
|
1517
|
+
return;
|
|
1518
|
+
}
|
|
1364
1519
|
console.table(
|
|
1365
1520
|
rows.map((row) => {
|
|
1366
1521
|
const input = typeof row.input_tokens === "number" && Number.isFinite(row.input_tokens)
|
|
@@ -1398,13 +1553,32 @@ async function sidecarCommand(rest, opts) {
|
|
|
1398
1553
|
return;
|
|
1399
1554
|
}
|
|
1400
1555
|
|
|
1556
|
+
// Validate before the passport is read and before the listener binds: the
|
|
1557
|
+
// sidecar mints on demand for the lifetime of the process, so a bad
|
|
1558
|
+
// destination has to be refused at start, not at the first proxied request.
|
|
1559
|
+
const gateway = requirePassportGateway(config);
|
|
1401
1560
|
const { passportId, passportSecret } = requirePassport(config);
|
|
1402
1561
|
startSidecar({
|
|
1403
|
-
gateway
|
|
1562
|
+
gateway,
|
|
1404
1563
|
passportId,
|
|
1405
1564
|
passportSecret,
|
|
1406
|
-
port:
|
|
1565
|
+
port: sidecarPort(opts),
|
|
1407
1566
|
host: String(opts.host ?? process.env.SIDECAR_HOST ?? "127.0.0.1"),
|
|
1567
|
+
// Named on the command line, never inferred. A sidecar reachable off-host
|
|
1568
|
+
// mints visas for whoever connects, so widening the bind is a decision the
|
|
1569
|
+
// operator states rather than one a config value makes quietly.
|
|
1570
|
+
allowNonLoopback: Boolean(opts.allowNonLoopback),
|
|
1571
|
+
// Hosts the agent may CONNECT-tunnel to, beyond the gateway itself. Provider
|
|
1572
|
+
// hosts are never eligible — see cli/proxy-policy.mjs.
|
|
1573
|
+
//
|
|
1574
|
+
// `operatorEnv`, not `process.env`, for the same reason `allowNonLoopback`
|
|
1575
|
+
// above takes no environment fallback at all: this is an egress control. A
|
|
1576
|
+
// `.passcontrol` that travels with a cloned repository was able to add tunnel
|
|
1577
|
+
// destinations to a sidecar started with no flags, and say nothing about it.
|
|
1578
|
+
allowConnectHosts: String(opts.allowConnect ?? operatorEnv("SIDECAR_ALLOW_CONNECT") ?? "")
|
|
1579
|
+
.split(",")
|
|
1580
|
+
.map((entry) => entry.trim())
|
|
1581
|
+
.filter(Boolean),
|
|
1408
1582
|
refreshSkewSeconds: Number(opts.refreshSkewSeconds ?? process.env.REFRESH_SKEW_SECONDS ?? 30),
|
|
1409
1583
|
});
|
|
1410
1584
|
|
|
@@ -1415,21 +1589,31 @@ async function sidecarCommand(rest, opts) {
|
|
|
1415
1589
|
}
|
|
1416
1590
|
|
|
1417
1591
|
async function mcpCommand() {
|
|
1592
|
+
const gateway = requirePassportGateway(config);
|
|
1418
1593
|
const { passportId, passportSecret } = requirePassport(config);
|
|
1419
1594
|
const { startMcpServer } = await import("../cli/mcp/server.mjs");
|
|
1420
|
-
await startMcpServer({ gateway
|
|
1595
|
+
await startMcpServer({ gateway, passportId, passportSecret });
|
|
1596
|
+
}
|
|
1597
|
+
|
|
1598
|
+
function sidecarPort(opts = {}) {
|
|
1599
|
+
const port = Number(opts.port ?? process.env.SIDECAR_PORT ?? 8788);
|
|
1600
|
+
if (!Number.isInteger(port) || port < 1 || port > 65535) {
|
|
1601
|
+
throw new Error("--port must be an integer from 1 to 65535.");
|
|
1602
|
+
}
|
|
1603
|
+
return port;
|
|
1421
1604
|
}
|
|
1422
1605
|
|
|
1423
1606
|
function sidecarBaseUrl(opts = {}) {
|
|
1424
1607
|
const provider = String(opts.provider || config.provider);
|
|
1425
1608
|
assertProvider(provider);
|
|
1426
1609
|
const host = String(opts.host ?? process.env.SIDECAR_HOST ?? "127.0.0.1");
|
|
1427
|
-
const port =
|
|
1610
|
+
const port = sidecarPort(opts);
|
|
1428
1611
|
return {
|
|
1429
1612
|
provider,
|
|
1430
1613
|
model: activeModel(provider, opts),
|
|
1431
1614
|
apiKey: "passcontrol",
|
|
1432
1615
|
baseUrl: `http://${host}:${port}/api/v1/${provider}`,
|
|
1616
|
+
port,
|
|
1433
1617
|
};
|
|
1434
1618
|
}
|
|
1435
1619
|
|
|
@@ -1479,9 +1663,11 @@ function printAgentPreset(name = "generic", opts = {}) {
|
|
|
1479
1663
|
return;
|
|
1480
1664
|
}
|
|
1481
1665
|
|
|
1482
|
-
const { provider, model, apiKey, baseUrl } = sidecarBaseUrl(opts);
|
|
1666
|
+
const { provider, model, apiKey, baseUrl, port } = sidecarBaseUrl(opts);
|
|
1483
1667
|
const modelWithProvider = `${provider}/${model}`;
|
|
1484
|
-
const sidecarStart = opts.port
|
|
1668
|
+
const sidecarStart = opts.port != null || process.env.SIDECAR_PORT != null
|
|
1669
|
+
? cliCommand(`sidecar --port ${port}`)
|
|
1670
|
+
: cliCommand("sidecar");
|
|
1485
1671
|
|
|
1486
1672
|
console.log(`# Start the bridge first: ${sidecarStart}`);
|
|
1487
1673
|
|
|
@@ -1497,6 +1683,16 @@ function printAgentPreset(name = "generic", opts = {}) {
|
|
|
1497
1683
|
}
|
|
1498
1684
|
|
|
1499
1685
|
switch (preset) {
|
|
1686
|
+
case "hermes":
|
|
1687
|
+
console.log("# Hermes Agent custom provider (verified against Hermes 0.18.2):");
|
|
1688
|
+
console.log("# Merge this model block into ~/.hermes/config.yaml:");
|
|
1689
|
+
console.log("model:");
|
|
1690
|
+
console.log(` default: ${JSON.stringify(model)}`);
|
|
1691
|
+
console.log(" provider: custom");
|
|
1692
|
+
console.log(` base_url: ${JSON.stringify(`${baseUrl}/v1`)}`);
|
|
1693
|
+
console.log(` api_key: ${JSON.stringify(apiKey)}`);
|
|
1694
|
+
console.log("# The placeholder key is stripped by the sidecar. Keep `passcontrol sidecar` running.");
|
|
1695
|
+
break;
|
|
1500
1696
|
case "openhands":
|
|
1501
1697
|
console.log("# OpenHands / LiteLLM-compatible starting point:");
|
|
1502
1698
|
printExports([
|
|
@@ -1809,7 +2005,8 @@ async function main() {
|
|
|
1809
2005
|
const [command, ...commandRest] = rest;
|
|
1810
2006
|
|
|
1811
2007
|
if (opts.help || command === "help") {
|
|
1812
|
-
|
|
2008
|
+
const target = command === "help" ? commandRest[0] : command;
|
|
2009
|
+
console.log(target === "agent" || target === "fleet" ? agentUsage() : usage());
|
|
1813
2010
|
return;
|
|
1814
2011
|
}
|
|
1815
2012
|
if (opts.version || command === "version") {
|
|
@@ -1820,7 +2017,7 @@ async function main() {
|
|
|
1820
2017
|
switch (command) {
|
|
1821
2018
|
case undefined:
|
|
1822
2019
|
case "status":
|
|
1823
|
-
await printCockpit({ noNetwork: Boolean(opts.noNetwork) });
|
|
2020
|
+
await printCockpit({ noNetwork: Boolean(opts.noNetwork), json: Boolean(opts.json) });
|
|
1824
2021
|
break;
|
|
1825
2022
|
case "init":
|
|
1826
2023
|
await initCommand(opts);
|
|
@@ -1872,7 +2069,7 @@ async function main() {
|
|
|
1872
2069
|
await agentCommand(commandRest, opts);
|
|
1873
2070
|
break;
|
|
1874
2071
|
case "spend":
|
|
1875
|
-
await spendCommand();
|
|
2072
|
+
await spendCommand(opts);
|
|
1876
2073
|
break;
|
|
1877
2074
|
case "audit":
|
|
1878
2075
|
await auditCommand(opts);
|