passcontrol 1.8.0 → 1.9.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/README.md +11 -2
- package/bin/passcontrol.mjs +119 -29
- package/cli/claude-code.mjs +55 -29
- package/cli/codex-hooks.mjs +6 -3
- 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-review.mjs +8 -3
- package/cli/presets.mjs +5 -5
- package/cli/protocols.mjs +2 -1
- package/cli/sidecar-token.mjs +83 -0
- package/cli/sidecar.mjs +69 -2
- package/cli/statusline.mjs +16 -8
- 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/statusline.mjs
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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}`, {
|
|
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
|
-
|
|
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
|
-
|
|
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";
|