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/README.md +11 -2
- package/bin/passcontrol.mjs +169 -28
- package/cli/claude-code.mjs +55 -29
- package/cli/codex-hooks.mjs +8 -5
- package/cli/codex.mjs +12 -6
- package/cli/config.mjs +10 -1
- package/cli/login.mjs +80 -22
- package/cli/logout.mjs +14 -2
- package/cli/lowered-keys.mjs +67 -0
- package/cli/memory-custody-sidecar.d.mts +19 -0
- package/cli/memory-custody-sidecar.mjs +470 -0
- package/cli/memory-custody.d.mts +24 -0
- package/cli/memory-custody.mjs +444 -0
- package/cli/memory-inventory.d.mts +15 -0
- package/cli/memory-inventory.mjs +390 -0
- package/cli/memory-review.d.mts +3 -0
- package/cli/memory-review.mjs +70 -0
- package/cli/menu.mjs +1 -0
- package/cli/mission-tools.d.mts +27 -0
- package/cli/mission-tools.mjs +373 -0
- package/cli/presets.mjs +5 -5
- package/cli/protocols.mjs +2 -1
- package/cli/sidecar-token.mjs +83 -0
- package/cli/sidecar.mjs +206 -3
- package/cli/statusline.mjs +16 -8
- package/cli/subscription-gate.mjs +9 -1
- package/cli/tool-gate.mjs +45 -3
- package/cli/tripwire-scan.d.mts +20 -0
- package/cli/tripwire-scan.mjs +279 -0
- package/cli/tripwire-sidecar.d.mts +10 -0
- package/cli/tripwire-sidecar.mjs +84 -0
- package/cli/tripwires.d.mts +21 -0
- package/cli/tripwires.mjs +208 -0
- package/cli/verify.mjs +29 -2
- package/cli/watch.mjs +14 -6
- package/cli/write-approval.mjs +103 -0
- package/package.json +1 -1
- package/sdk/verify.d.ts +13 -3
- package/sdk/verify.js +24 -4
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
|
-
|
|
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
|
-
|
|
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
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
|
|
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
|
-
*
|
|
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
|
|
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
|
-
*
|
|
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
|
-
|
|
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";
|