passcontrol 1.8.0 → 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -46,6 +46,7 @@ function writeCache(file, nowMs, line) {
46
46
  export async function statuslineText({
47
47
  port,
48
48
  host = "127.0.0.1",
49
+ sidecarKey = null,
49
50
  cacheFile,
50
51
  now = () => Date.now(),
51
52
  fetch: fetchImpl = globalThis.fetch,
@@ -61,7 +62,8 @@ export async function statuslineText({
61
62
  let response;
62
63
  try {
63
64
  response = await fetchImpl(`http://${host}:${port}/api/v1/self`, {
64
- headers: { accept: "application/json" },
65
+ // The sidecar's key (review C-03): /api/v1/self is forwarded with the visa.
66
+ headers: { accept: "application/json", ...(sidecarKey ? { authorization: `Bearer ${sidecarKey}` } : {}) },
65
67
  signal: controller.signal,
66
68
  });
67
69
  } catch {
@@ -139,12 +141,13 @@ export function readStatusInput(stream = process.stdin, waitMs = STDIN_WAIT_MS)
139
141
  * Hands the usage window to the sidecar, for `watch` and `/passcontrol`. Best effort:
140
142
  * a sidecar that is not running only means the boards do not show it.
141
143
  */
142
- export async function postUsageWindow({ port, host = "127.0.0.1", window, fetch: fetchImpl = globalThis.fetch, timeoutMs = 500 }) {
144
+ export async function postUsageWindow({ port, host = "127.0.0.1", window, sidecarKey = null, fetch: fetchImpl = globalThis.fetch, timeoutMs = 500 }) {
143
145
  if (!window) return;
144
146
  try {
145
147
  const response = await fetchImpl(`http://${host}:${port}${WINDOW_PATH}`, {
146
148
  method: "POST",
147
- headers: { "content-type": "application/json" },
149
+ // The sidecar's own paths ask for its key too (review C-03 follow-up).
150
+ headers: { "content-type": "application/json", ...(sidecarKey ? { authorization: `Bearer ${sidecarKey}` } : {}) },
148
151
  body: JSON.stringify(window),
149
152
  signal: AbortSignal.timeout(timeoutMs),
150
153
  });
@@ -158,9 +161,9 @@ export async function postUsageWindow({ port, host = "127.0.0.1", window, fetch:
158
161
  * The status line with the usage window, when Claude Code sent one: the budget line
159
162
  * may come from the cache, the window is always this run's. Never throws.
160
163
  */
161
- export async function statuslineWithWindow({ input, port, host = "127.0.0.1", fetch: fetchImpl = globalThis.fetch, budgetLine }) {
164
+ export async function statuslineWithWindow({ input, port, host = "127.0.0.1", sidecarKey = null, fetch: fetchImpl = globalThis.fetch, budgetLine }) {
162
165
  const window = readUsageWindow(input);
163
- const [line] = await Promise.all([budgetLine(), postUsageWindow({ port, host, window, fetch: fetchImpl })]);
166
+ const [line] = await Promise.all([budgetLine(), postUsageWindow({ port, host, window, sidecarKey, fetch: fetchImpl })]);
164
167
  const text = usageWindowText(window, { short: true });
165
168
  return text ? `${line} · ${text}` : line;
166
169
  }
@@ -206,9 +209,12 @@ export function notInPathText(remoteHost) {
206
209
  const row = ([label, value]) => ` ${label.padEnd(11)} ${value}`;
207
210
 
208
211
  /** The usage window the sidecar holds, as short text, or "". Never throws. */
209
- async function readSidecarWindow({ host, port, fetch: fetchImpl, signal }) {
212
+ async function readSidecarWindow({ host, port, sidecarKey = null, fetch: fetchImpl, signal }) {
210
213
  try {
211
- const response = await fetchImpl(`http://${host}:${port}${WINDOW_PATH}`, { headers: { accept: "application/json" }, signal });
214
+ const response = await fetchImpl(`http://${host}:${port}${WINDOW_PATH}`, {
215
+ headers: { accept: "application/json", ...(sidecarKey ? { authorization: `Bearer ${sidecarKey}` } : {}) },
216
+ signal,
217
+ });
212
218
  if (!response.ok) {
213
219
  await response.body?.cancel().catch(() => {});
214
220
  return "";
@@ -228,6 +234,7 @@ async function readSidecarWindow({ host, port, fetch: fetchImpl, signal }) {
228
234
  export async function statusPanelText({
229
235
  port,
230
236
  host = "127.0.0.1",
237
+ sidecarKey = null,
231
238
  gateway,
232
239
  session = null,
233
240
  subscription = false,
@@ -236,6 +243,7 @@ export async function statusPanelText({
236
243
  }) {
237
244
  const dashboard = `${String(gateway ?? "").replace(/\/+$/, "")}/dashboard`;
238
245
  const headers = { accept: "application/json" };
246
+ if (sidecarKey) headers.authorization = `Bearer ${sidecarKey}`;
239
247
  if (typeof session === "string" && DECLARED_SESSION.test(session)) headers["x-claude-code-session-id"] = session;
240
248
 
241
249
  const controller = new AbortController();
@@ -293,7 +301,7 @@ export async function statusPanelText({
293
301
  if (typeof self?.budget !== "object" || self.budget === null) return "PassControl · unreadable answer";
294
302
  const agentId = typeof self.agent_id === "string" && UUID.test(self.agent_id) ? self.agent_id : null;
295
303
  const title = `PassControl${agentId ? ` · agent ${agentId.slice(0, 8)}` : ""}${limitReached(self) ? " · LIMIT REACHED" : paused(self) ? " · PAUSED" : ""}`;
296
- const window = subscription ? await readSidecarWindow({ host, port, fetch: fetchImpl, signal: controller.signal }) : "";
304
+ const window = subscription ? await readSidecarWindow({ host, port, sidecarKey, fetch: fetchImpl, signal: controller.signal }) : "";
297
305
  return [
298
306
  title,
299
307
  "",
package/cli/verify.mjs CHANGED
@@ -118,8 +118,34 @@ async function verifySigned(
118
118
  return { ok: false, reason: "bad_signature" };
119
119
  }
120
120
 
121
- export function verifyReceipt(jws, options) {
122
- return verifySigned(jws, RECEIPT_TYP, options);
121
+ export async function verifyReceipt(jws, options) {
122
+ const result = await verifySigned(jws, RECEIPT_TYP, options);
123
+ if (result.ok && result.claims.ver === 4 && !validGatewayEndingClaims(result.claims)) {
124
+ return { ok: false, reason: "claims" };
125
+ }
126
+ return result;
127
+ }
128
+
129
+ // v4 changes WHO acted. Reject contradictory identity evidence even when signed.
130
+ // Keep in sync with sdk/verify.ts.
131
+ function validGatewayEndingClaims(c) {
132
+ const auth = c.auth;
133
+ const end = c.end;
134
+ return c.sub === "gateway" &&
135
+ !["vjti", "act", "passportId", "visaJti", "agentAccessKeyId", "credentialUseId"].some((key) => key in c) &&
136
+ !!auth && typeof auth === "object" && !Array.isArray(auth) && auth.kind === "gateway_ending" &&
137
+ !["act", "kid", "use", "dlg", "dep", "ch", "prf"].some((key) => key in auth) &&
138
+ !!end && !Array.isArray(end) &&
139
+ typeof end.thg === "string" && end.thg.length > 0 &&
140
+ typeof end.knd === "string" && end.knd.length > 0 &&
141
+ ["kill_switch", "session", "service", "mission_end", "budget_pause"].includes(end.trg) &&
142
+ Number.isSafeInteger(end.sat) && end.sat >= 0;
143
+ }
144
+
145
+ /** Plain identity wording for the owner-stop receipt, not an agent credential. */
146
+ export function describeGatewayEnding(ending) {
147
+ const trigger = { kill_switch: "kill switch", session: "session stop", service: "service stop", mission_end: "mission end", budget_pause: "budget pause line" }[ending.trg];
148
+ return `Ended by PassControl on the owner's stop (${trigger}), not a call by the agent. No passport or agent key signed it.`;
123
149
  }
124
150
 
125
151
  /**
@@ -390,6 +416,7 @@ export async function verifySession(input, options) {
390
416
 
391
417
  /** Human-readable one-liners. Kept here so the CLI and its tests agree on wording. */
392
418
  export const FAILURE_REASONS = {
419
+ claims: "the receipt carries missing or conflicting gateway ending claims",
393
420
  malformed: "not a compact JWS",
394
421
  bad_signature: "signature does not verify against the issuer's published key",
395
422
  wrong_type: "this artifact is a different type than the one you asked to verify",
package/cli/watch.mjs CHANGED
@@ -56,7 +56,7 @@ const MIN_WIDTH = 40;
56
56
  * unreachable, closed, not-feed (an older sidecar, or something else on the port),
57
57
  * off (bound off loopback), refused, busy.
58
58
  */
59
- export function openFeed({ port, host = "127.0.0.1", onEvent, onError = () => {} }) {
59
+ export function openFeed({ port, host = "127.0.0.1", sidecarKey = null, onEvent, onError = () => {} }) {
60
60
  let done = false;
61
61
  let greeted = false;
62
62
  let buffer = "";
@@ -67,7 +67,9 @@ export function openFeed({ port, host = "127.0.0.1", onEvent, onError = () => {}
67
67
  req?.destroy();
68
68
  onError(error);
69
69
  };
70
- req = http.get({ host, port, path: WATCH_PATH, headers: { accept: "application/x-ndjson" }, agent: false }, (res) => {
70
+ // The feed shows what the agent did, so the sidecar asks for its key (review C-03 follow-up).
71
+ const headers = { accept: "application/x-ndjson", ...(sidecarKey ? { authorization: `Bearer ${sidecarKey}` } : {}) };
72
+ req = http.get({ host, port, path: WATCH_PATH, headers, agent: false }, (res) => {
71
73
  res.setEncoding("utf8");
72
74
  const type = String(res.headers["content-type"] ?? "");
73
75
  if (res.statusCode !== 200 || !type.startsWith("application/x-ndjson")) {
@@ -82,7 +84,7 @@ export function openFeed({ port, host = "127.0.0.1", onEvent, onError = () => {}
82
84
  } catch {
83
85
  // Not ours.
84
86
  }
85
- const kind = { watch_off: "off", watch_refused: "refused", watch_busy: "busy" }[code] ?? "not-feed";
87
+ const kind = { watch_off: "off", watch_refused: "refused", watch_busy: "busy", sidecar_caller_unauthenticated: "keyless" }[code] ?? "not-feed";
86
88
  fail({ kind, status: res.statusCode });
87
89
  };
88
90
  res.on("end", settle);
@@ -473,13 +475,15 @@ export function plainLine(row, { run, formatTime = localTime }) {
473
475
  // ── The budget, held in memory ───────────────────────────────────────────────
474
476
 
475
477
  /** GET /api/v1/self through the sidecar, which holds a warm visa. Never throws, never writes. */
476
- export async function fetchBudget({ port, host = "127.0.0.1", fetch: fetchImpl = globalThis.fetch, now = Date.now, timeoutMs = BUDGET_TIMEOUT_MS }) {
478
+ export async function fetchBudget({ port, host = "127.0.0.1", sidecarKey = null, fetch: fetchImpl = globalThis.fetch, now = Date.now, timeoutMs = BUDGET_TIMEOUT_MS }) {
477
479
  const controller = new AbortController();
478
480
  const timer = setTimeout(() => controller.abort(), timeoutMs);
479
481
  try {
480
482
  let response;
481
483
  try {
482
- response = await fetchImpl(`http://${host}:${port}/api/v1/self`, { headers: { accept: "application/json" }, signal: controller.signal });
484
+ // The sidecar's key (review C-03): /api/v1/self is forwarded with the visa like any call.
485
+ const headers = { accept: "application/json", ...(sidecarKey ? { authorization: `Bearer ${sidecarKey}` } : {}) };
486
+ response = await fetchImpl(`http://${host}:${port}/api/v1/self`, { headers, signal: controller.signal });
483
487
  } catch {
484
488
  return { kind: "unavailable", reason: controller.signal.aborted ? "no answer from the sidecar" : "sidecar not running" };
485
489
  }
@@ -514,6 +518,8 @@ function downMessage(error, port) {
514
518
  return "the sidecar refused the feed request";
515
519
  case "busy":
516
520
  return "too many boards are already watching this sidecar";
521
+ case "keyless":
522
+ return "the sidecar asked for its key · it runs with a passport this machine's config does not have (passcontrol login)";
517
523
  default:
518
524
  return `whatever answers on :${port} serves no watch feed · a sidecar started before \`watch\` existed needs a restart`;
519
525
  }
@@ -526,6 +532,7 @@ function downMessage(error, port) {
526
532
  export function runWatch({
527
533
  port,
528
534
  host = "127.0.0.1",
535
+ sidecarKey = null,
529
536
  out = process.stdout,
530
537
  input = process.stdin,
531
538
  signals = process,
@@ -590,6 +597,7 @@ export function runWatch({
590
597
  feed = openFeed({
591
598
  port,
592
599
  host,
600
+ sidecarKey,
593
601
  onEvent: (event) => {
594
602
  if (event.type === "hello") attempt = 0;
595
603
  applyEvent(state, event);
@@ -606,7 +614,7 @@ export function runWatch({
606
614
 
607
615
  async function pollBudget() {
608
616
  if (finished) return;
609
- state.budget = await fetchBudget({ port, host, fetch: fetchImpl });
617
+ state.budget = await fetchBudget({ port, host, sidecarKey, fetch: fetchImpl });
610
618
  schedule();
611
619
  if (!finished) later(pollBudget, budgetEveryMs);
612
620
  }
@@ -0,0 +1,103 @@
1
+ // Write authority for one command at a time (review C-01, 2026-11-15).
2
+ //
3
+ // `passcontrol login` keeps a READ-only control key, because the file it lives in also
4
+ // holds the agent's passport and the governed agent can read that file. A key there
5
+ // with write scope would let the agent act as its owner. So when a command needs to
6
+ // change something (kill off, resume, create an agent, import) and the gateway answers
7
+ // `insufficient_scope`, the CLI asks for a key for that one command: the same browser
8
+ // approval as login, which needs the owner signed in with their second factor. The
9
+ // key is held in this process's memory only, never written to disk, and revoked when
10
+ // the command ends (`releaseWriteKey`, called from bin/passcontrol.mjs on success and
11
+ // on failure).
12
+ //
13
+ // What this does NOT do: it does not stop an agent from STARTING such a command. It
14
+ // stops the command from finishing without a person approving it in the browser, and
15
+ // the approval screen names the command.
16
+ import os from "node:os";
17
+
18
+ import { approveInBrowser } from "./login.mjs";
19
+ import { step, warn } from "./config.mjs";
20
+
21
+ /** The one-command key this process holds, if any. */
22
+ let held = null;
23
+
24
+ /**
25
+ * Ctrl-C (or a kill) while the key is held: revoke it, then exit as the signal would
26
+ * have. Without this the key would stay live in Settings with nobody holding it.
27
+ */
28
+ function onSignal(signal) {
29
+ const code = signal === "SIGTERM" ? 143 : 130;
30
+ releaseWriteKey().finally(() => process.exit(code));
31
+ }
32
+ const SIGNALS = ["SIGINT", "SIGTERM"];
33
+
34
+ /** A short label for the approval screen and the key's name: the command words only, never arguments. */
35
+ export function commandLabel(rest = []) {
36
+ return rest.slice(0, 2).map(String).join(" ").replace(/[^A-Za-z0-9 ._-]/gu, "").trim() || "a command";
37
+ }
38
+
39
+ /** The key already approved for this origin in this process, or null. */
40
+ export function heldWriteKey(origin) {
41
+ return held && held.origin === origin ? held.key : null;
42
+ }
43
+
44
+ /**
45
+ * Ask the operator to approve this command in the browser, and return a write key for
46
+ * it. Refuses at once without a terminal: nobody would see the code, so the wait could
47
+ * only end at its ten-minute expiry.
48
+ */
49
+ export async function obtainWriteKey(origin, {
50
+ command = "a command",
51
+ interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY),
52
+ openUrl = () => {},
53
+ fetchImpl = fetch,
54
+ approve = approveInBrowser,
55
+ hostname = os.hostname(),
56
+ } = {}) {
57
+ const existing = heldWriteKey(origin);
58
+ if (existing) return existing;
59
+ if (!interactive) {
60
+ throw new Error(
61
+ `\`passcontrol ${command}\` changes something, and this machine's control key is read-only.\n` +
62
+ " Run it in a terminal: it asks you to approve it in the browser.\n" +
63
+ " Or pass a write key from Settings for this one command: PASSCONTROL_API_KEY=<key> passcontrol …"
64
+ );
65
+ }
66
+ warn(`\`passcontrol ${command}\` changes something. This machine's key is read-only, so approve it once.`);
67
+ const grant = await approve(origin, {
68
+ // The command first: the server keeps 60 characters, and a long hostname must not
69
+ // cut off the part the owner is approving.
70
+ clientName: `one command - ${command} - ${hostname}`,
71
+ title: "Approve this command",
72
+ // The gateway gives the key a fixed 15-minute life, so a CLI killed before it
73
+ // revokes the key does not leave a write key behind.
74
+ oneCommand: true,
75
+ openUrl,
76
+ fetchImpl,
77
+ });
78
+ if (!grant?.api_key) throw new Error("The approval returned no key. Nothing was changed.");
79
+ held = { origin, key: grant.api_key, fetchImpl };
80
+ for (const signal of SIGNALS) process.once(signal, onSignal);
81
+ return held.key;
82
+ }
83
+
84
+ /** Revoke the one-command key, if one is held. Safe to call more than once. */
85
+ export async function releaseWriteKey() {
86
+ if (!held) return { released: false };
87
+ const { origin, key, fetchImpl } = held;
88
+ held = null;
89
+ for (const signal of SIGNALS) process.removeListener(signal, onSignal);
90
+ try {
91
+ const res = await fetchImpl(`${origin}/api/control/v1/keys/self/revoke`, {
92
+ method: "POST",
93
+ headers: { authorization: `Bearer ${key}` },
94
+ });
95
+ // 404 and 409 both mean it can no longer be used (see the route).
96
+ if (res.ok || res.status === 404 || res.status === 409) return { released: true };
97
+ } catch {
98
+ // Reported below.
99
+ }
100
+ warn("Could not revoke the one-command key. It was never saved to disk;");
101
+ step("revoke the newest \"one command\" key in Settings → API keys to be sure.");
102
+ return { released: false };
103
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "passcontrol",
3
- "version": "1.8.0",
3
+ "version": "1.9.0",
4
4
  "description": "Identity, scope and budget controls for AI agents while provider keys stay server-side.",
5
5
  "license": "BUSL-1.1",
6
6
  "homepage": "https://passcontrol.vertias.eu",
package/sdk/verify.d.ts CHANGED
@@ -2,7 +2,7 @@ export declare const RECEIPT_TYP = "passcontrol-receipt+jwt";
2
2
  export declare const AGENT_TOKEN_TYP = "passcontrol-agent+jwt";
3
3
  /** The newest artifact version this verifier understands. */
4
4
  export declare const SUPPORTED_VER: number;
5
- export type VerifyFailure = "malformed" | "untrusted_issuer" | "unknown_key" | "bad_signature" | "wrong_type" | "unsupported_version" | "jwks_unreachable" | "expired" | "wrong_audience" | "revoked" | "status_unavailable";
5
+ export type VerifyFailure = "claims" | "malformed" | "untrusted_issuer" | "unknown_key" | "bad_signature" | "wrong_type" | "unsupported_version" | "jwks_unreachable" | "expired" | "wrong_audience" | "revoked" | "status_unavailable";
6
6
  export type VerifyResult<T> = {
7
7
  ok: true;
8
8
  claims: T;
@@ -31,6 +31,8 @@ export interface ReceiptClaims {
31
31
  agid: string;
32
32
  vjti?: string;
33
33
  auth?: {
34
+ kind: "gateway_ending";
35
+ } | {
34
36
  kind: "direct_key";
35
37
  kid: string;
36
38
  use: string;
@@ -44,6 +46,13 @@ export interface ReceiptClaims {
44
46
  ch: string;
45
47
  prf?: true;
46
48
  };
49
+ /** ver 4: the gateway ended this standing thing on the owner's stop. */
50
+ end?: {
51
+ thg: string;
52
+ knd: string;
53
+ trg: "kill_switch" | "session" | "service" | "mission_end" | "budget_pause";
54
+ sat: number;
55
+ };
47
56
  prov: string;
48
57
  mdl: string | null;
49
58
  mth: string;
@@ -192,9 +201,10 @@ export interface PublicJwk {
192
201
  */
193
202
  export declare function matchesIssuer(iss: string, trusted: string[]): boolean;
194
203
  /**
195
- * Verify a signed call receipt.
204
+ * Verify a signed receipt. Version 4 attests to a gateway ending on the owner's stop;
205
+ * it carries no agent authentication evidence.
196
206
  *
197
- * What a valid receipt proves: this issuer attests that the named passport or
207
+ * For an agent call, this issuer attests that the named passport or
198
208
  * Direct Agent Key authenticated this call, with this verdict and this cost.
199
209
  * `auth.kind === "passport_proof_per_request"` additionally attests that the
200
210
  * gateway verified the passport proof for this exact request. A direct receipt
package/sdk/verify.js CHANGED
@@ -176,9 +176,10 @@ async function verifySigned(token, typ, options, version = { claim: "ver", max:
176
176
  return fail("signature", "bad_signature");
177
177
  }
178
178
  /**
179
- * Verify a signed call receipt.
179
+ * Verify a signed receipt. Version 4 attests to a gateway ending on the owner's stop;
180
+ * it carries no agent authentication evidence.
180
181
  *
181
- * What a valid receipt proves: this issuer attests that the named passport or
182
+ * For an agent call, this issuer attests that the named passport or
182
183
  * Direct Agent Key authenticated this call, with this verdict and this cost.
183
184
  * `auth.kind === "passport_proof_per_request"` additionally attests that the
184
185
  * gateway verified the passport proof for this exact request. A direct receipt
@@ -187,8 +188,27 @@ async function verifySigned(token, typ, options, version = { claim: "ver", max:
187
188
  * anything about the response, and nothing at all by its absence — see
188
189
  * lib/receipt.ts for the limits, which are deliberate and documented.
189
190
  */
190
- export function verifyReceipt(jws, options) {
191
- return verifySigned(jws, RECEIPT_TYP, options);
191
+ export async function verifyReceipt(jws, options) {
192
+ const result = await verifySigned(jws, RECEIPT_TYP, options);
193
+ if (result.ok && result.claims.ver === 4 && !validGatewayEndingClaims(result.claims)) {
194
+ return { ok: false, reason: "claims" };
195
+ }
196
+ return result;
197
+ }
198
+ // v4 changes WHO acted. Reject contradictory identity evidence even when signed.
199
+ // Keep in sync with the standalone CLI verifier.
200
+ function validGatewayEndingClaims(c) {
201
+ const auth = c.auth;
202
+ const end = c.end;
203
+ return c.sub === "gateway" &&
204
+ !["vjti", "act", "passportId", "visaJti", "agentAccessKeyId", "credentialUseId"].some((key) => key in c) &&
205
+ !!auth && typeof auth === "object" && !Array.isArray(auth) && auth.kind === "gateway_ending" &&
206
+ !["act", "kid", "use", "dlg", "dep", "ch", "prf"].some((key) => key in auth) &&
207
+ !!end && !Array.isArray(end) &&
208
+ typeof end.thg === "string" && end.thg.length > 0 &&
209
+ typeof end.knd === "string" && end.knd.length > 0 &&
210
+ ["kill_switch", "session", "service", "mission_end", "budget_pause"].includes(end.trg) &&
211
+ Number.isSafeInteger(end.sat) && end.sat >= 0;
192
212
  }
193
213
  // ── Signed spend statements ────────────────────────────────────────────────
194
214
  export const STATEMENT_TYP = "passcontrol-statement+jws";