passcontrol 1.7.2 → 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.
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.7.2",
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";