passcontrol 1.3.0 → 1.4.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/bin/passcontrol.mjs +264 -6
- package/cli/budget-format.mjs +76 -0
- package/cli/claude-code.mjs +80 -16
- package/cli/config.mjs +1 -1
- package/cli/declared-session.mjs +33 -0
- package/cli/journal.mjs +84 -0
- package/cli/mcp/README.md +4 -1
- package/cli/mcp/gateway.mjs +13 -0
- package/cli/mcp/server.mjs +27 -0
- package/cli/menu.mjs +3 -0
- package/cli/protocols.d.mts +2 -0
- package/cli/protocols.mjs +14 -0
- package/cli/sidecar.mjs +42 -5
- package/cli/statusline.mjs +89 -0
- package/cli/verify.mjs +215 -5
- package/package.json +1 -1
- package/sdk/verify.d.ts +108 -0
- package/sdk/verify.js +219 -1
package/cli/verify.mjs
CHANGED
|
@@ -8,13 +8,16 @@
|
|
|
8
8
|
// the artifact and the issuer's origin. That is the whole point.
|
|
9
9
|
import { ed25519 } from "@noble/curves/ed25519";
|
|
10
10
|
import { sha256 } from "@noble/hashes/sha256";
|
|
11
|
-
import { RECEIPT_PROTOCOL, STATEMENT_PROTOCOL } from "./protocols.mjs";
|
|
11
|
+
import { RECEIPT_PROTOCOL, SESSION_PROTOCOL, STATEMENT_PROTOCOL } from "./protocols.mjs";
|
|
12
12
|
|
|
13
13
|
export const RECEIPT_TYP = "passcontrol-receipt+jwt";
|
|
14
14
|
export const AGENT_TOKEN_TYP = "passcontrol-agent+jwt";
|
|
15
15
|
export const STATEMENT_TYP = "passcontrol-statement+jws";
|
|
16
|
+
export const SESSION_TYP = "passcontrol-session+jws";
|
|
16
17
|
// Its own version line, separate from the receipt's — see protocols.mjs.
|
|
17
18
|
export const STATEMENT_SUPPORTED_VER = STATEMENT_PROTOCOL.maximum;
|
|
19
|
+
// Session seals: their own line too.
|
|
20
|
+
export const SESSION_SUPPORTED_VER = SESSION_PROTOCOL.maximum;
|
|
18
21
|
// Receipts v2 add Direct Agent identity claims. This is a maximum, not an
|
|
19
22
|
// equality check: v1 receipts remain independently verifiable forever.
|
|
20
23
|
export const SUPPORTED_VER = RECEIPT_PROTOCOL.maximum;
|
|
@@ -34,12 +37,15 @@ export function matchesIssuer(iss, trusted) {
|
|
|
34
37
|
return trusted.some((candidate) => strip(candidate) === strip(iss));
|
|
35
38
|
}
|
|
36
39
|
|
|
37
|
-
async function loadJwks(issuer, fetchImpl) {
|
|
40
|
+
async function loadJwks(issuer, fetchImpl, cache) {
|
|
41
|
+
if (cache?.has(issuer)) return cache.get(issuer);
|
|
38
42
|
try {
|
|
39
43
|
const res = await fetchImpl(new URL("/.well-known/jwks.json", issuer).toString());
|
|
40
44
|
if (!res.ok) return null;
|
|
41
45
|
const body = await res.json();
|
|
42
|
-
|
|
46
|
+
const keys = Array.isArray(body?.keys) ? body.keys : [];
|
|
47
|
+
cache?.set(issuer, keys);
|
|
48
|
+
return keys;
|
|
43
49
|
} catch {
|
|
44
50
|
return null;
|
|
45
51
|
}
|
|
@@ -59,7 +65,7 @@ async function loadJwks(issuer, fetchImpl) {
|
|
|
59
65
|
async function verifySigned(
|
|
60
66
|
token,
|
|
61
67
|
typ,
|
|
62
|
-
{ issuer, fetch: fetchImpl = fetch },
|
|
68
|
+
{ issuer, fetch: fetchImpl = fetch, jwksCache },
|
|
63
69
|
version = { claim: "ver", max: SUPPORTED_VER }
|
|
64
70
|
) {
|
|
65
71
|
const parts = String(token).split(".");
|
|
@@ -88,7 +94,7 @@ async function verifySigned(
|
|
|
88
94
|
return { ok: false, reason: "unsupported_version" };
|
|
89
95
|
}
|
|
90
96
|
|
|
91
|
-
const keys = await loadJwks(claims.iss, fetchImpl);
|
|
97
|
+
const keys = await loadJwks(claims.iss, fetchImpl, jwksCache);
|
|
92
98
|
if (!keys) return { ok: false, reason: "jwks_unreachable" };
|
|
93
99
|
|
|
94
100
|
const candidates = keys.filter(
|
|
@@ -184,6 +190,204 @@ export async function verifyAgentToken(token, options) {
|
|
|
184
190
|
return result;
|
|
185
191
|
}
|
|
186
192
|
|
|
193
|
+
// ── Session seals ────────────────────────────────────────────────────────────
|
|
194
|
+
|
|
195
|
+
/** Leaf and node hashing, the same domain separation as verifyInclusion above. */
|
|
196
|
+
function sessionHash(prefix, ...parts) {
|
|
197
|
+
const total = parts.reduce((sum, p) => sum + p.length, 1);
|
|
198
|
+
const buf = new Uint8Array(total);
|
|
199
|
+
buf[0] = prefix;
|
|
200
|
+
let at = 1;
|
|
201
|
+
for (const p of parts) {
|
|
202
|
+
buf.set(p, at);
|
|
203
|
+
at += p.length;
|
|
204
|
+
}
|
|
205
|
+
return sha256(buf);
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
/** lib/merkle.ts's root: leaves in bundle order, an odd node promoted unchanged. */
|
|
209
|
+
function sessionRoot(bundle) {
|
|
210
|
+
if (bundle.length === 0) return null;
|
|
211
|
+
let level = bundle.map((jws) => sessionHash(0x00, new TextEncoder().encode(jws)));
|
|
212
|
+
while (level.length > 1) {
|
|
213
|
+
const next = [];
|
|
214
|
+
for (let i = 0; i < level.length; i += 2) {
|
|
215
|
+
next.push(level[i + 1] ? sessionHash(0x01, level[i], level[i + 1]) : level[i]);
|
|
216
|
+
}
|
|
217
|
+
level = next;
|
|
218
|
+
}
|
|
219
|
+
return Buffer.from(level[0]).toString("base64url");
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
function decodePayload(jws) {
|
|
223
|
+
try {
|
|
224
|
+
const claims = decodeJson(String(jws).split(".")[1] ?? "");
|
|
225
|
+
return claims && typeof claims === "object" && !Array.isArray(claims) ? claims : null;
|
|
226
|
+
} catch {
|
|
227
|
+
return null;
|
|
228
|
+
}
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : 0);
|
|
232
|
+
const orNull = (v) => (typeof v === "string" ? v : null);
|
|
233
|
+
|
|
234
|
+
/** Tree and model lists, compared as sets: one canonical string each. */
|
|
235
|
+
function canonical(entries, keys) {
|
|
236
|
+
if (!Array.isArray(entries)) return null;
|
|
237
|
+
return JSON.stringify(
|
|
238
|
+
entries
|
|
239
|
+
.map((e) => keys.map((k) => (k.text ? orNull(e?.[k.name]) : num(e?.[k.name]))))
|
|
240
|
+
.sort((a, b) => (JSON.stringify(a) < JSON.stringify(b) ? -1 : JSON.stringify(a) > JSON.stringify(b) ? 1 : 0))
|
|
241
|
+
);
|
|
242
|
+
}
|
|
243
|
+
const TREE_KEYS = [{ name: "agt", text: true }, { name: "par", text: true }, { name: "n" }, { name: "cost" }, { name: "refused" }];
|
|
244
|
+
const MODEL_KEYS = [{ name: "mdl", text: true }, { name: "n" }, { name: "cost" }];
|
|
245
|
+
|
|
246
|
+
/** What the bundle itself adds up to, from the receipts' own claims. */
|
|
247
|
+
function bundleTotals(decoded) {
|
|
248
|
+
const tree = new Map();
|
|
249
|
+
const models = new Map();
|
|
250
|
+
let cost = 0;
|
|
251
|
+
let unp = 0;
|
|
252
|
+
for (const c of decoded) {
|
|
253
|
+
if (!c) continue;
|
|
254
|
+
const ctx = c.ctx && typeof c.ctx === "object" ? c.ctx : {};
|
|
255
|
+
const agt = orNull(ctx.agt);
|
|
256
|
+
const par = orNull(ctx.par);
|
|
257
|
+
const refused = typeof c.res?.status === "string" && c.res.status.startsWith("blocked_") ? 1 : 0;
|
|
258
|
+
const key = JSON.stringify([agt, par]);
|
|
259
|
+
const node = tree.get(key) ?? { agt, par, n: 0, cost: 0, refused: 0 };
|
|
260
|
+
node.n += 1;
|
|
261
|
+
node.cost += num(c.cost);
|
|
262
|
+
node.refused += refused;
|
|
263
|
+
tree.set(key, node);
|
|
264
|
+
const mdl = orNull(c.mdl);
|
|
265
|
+
const m = models.get(JSON.stringify(mdl)) ?? { mdl, n: 0, cost: 0 };
|
|
266
|
+
m.n += 1;
|
|
267
|
+
m.cost += num(c.cost);
|
|
268
|
+
models.set(JSON.stringify(mdl), m);
|
|
269
|
+
cost += num(c.cost);
|
|
270
|
+
if (c.unp === true) unp += 1;
|
|
271
|
+
}
|
|
272
|
+
return { cost, unp, tree: [...tree.values()], mdl: [...models.values()] };
|
|
273
|
+
}
|
|
274
|
+
|
|
275
|
+
/**
|
|
276
|
+
* A journal entry is a receipt id, or `{ id, ... }` as the sidecar writes it. This
|
|
277
|
+
* session's ids (and lines naming no session), and how many named another (`ses`):
|
|
278
|
+
* one sidecar run serves many sessions.
|
|
279
|
+
*/
|
|
280
|
+
function journalIds(journal, session) {
|
|
281
|
+
if (!Array.isArray(journal)) return null;
|
|
282
|
+
const ids = [];
|
|
283
|
+
let other = 0;
|
|
284
|
+
for (const entry of journal) {
|
|
285
|
+
const id = typeof entry === "string" ? entry : entry && typeof entry === "object" ? entry.id : undefined;
|
|
286
|
+
if (typeof id !== "string" || id.length === 0) return null;
|
|
287
|
+
const ses = entry && typeof entry === "object" ? entry.ses : undefined;
|
|
288
|
+
if (typeof ses === "string" && ses !== session) {
|
|
289
|
+
other += 1;
|
|
290
|
+
continue;
|
|
291
|
+
}
|
|
292
|
+
ids.push(id);
|
|
293
|
+
}
|
|
294
|
+
return { ids, other };
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
/**
|
|
298
|
+
* Verify a session seal against its bundle and, when given, the user's journal.
|
|
299
|
+
*
|
|
300
|
+
* Four checks: (1) the seal's signature; (2) its root and totals recompute from
|
|
301
|
+
* the bundle; (3) every receipt in the bundle verifies and belongs to this
|
|
302
|
+
* session, agent and window; (4) every receipt id the user's sidecar journaled is
|
|
303
|
+
* in the bundle, directly or through a receipt's `prev` link.
|
|
304
|
+
*
|
|
305
|
+
* Without a journal a seal is no stronger than a statement: `checks.journal` is
|
|
306
|
+
* null and says so. A journaled id that is absent is MISSING, not tampering: the
|
|
307
|
+
* gateway's log write is best-effort, so a lost row and an omission look alike.
|
|
308
|
+
* Receipts in the bundle but not the journal are reported in `unjournaled` and
|
|
309
|
+
* never fail the session.
|
|
310
|
+
*/
|
|
311
|
+
export async function verifySession(input, options) {
|
|
312
|
+
const jwksCache = new Map();
|
|
313
|
+
const opts = { ...options, jwksCache };
|
|
314
|
+
const result = {
|
|
315
|
+
ok: false,
|
|
316
|
+
checks: { signature: false, bundle: null, receipts: null, journal: null },
|
|
317
|
+
mismatched: [],
|
|
318
|
+
rejected: [],
|
|
319
|
+
missing: [],
|
|
320
|
+
unjournaled: [],
|
|
321
|
+
otherSessions: 0,
|
|
322
|
+
};
|
|
323
|
+
|
|
324
|
+
const sealed = await verifySigned(input?.seal, SESSION_TYP, opts, { claim: "v", max: SESSION_SUPPORTED_VER });
|
|
325
|
+
if (!sealed.ok) return { ...result, reason: sealed.reason };
|
|
326
|
+
const claims = sealed.claims;
|
|
327
|
+
result.claims = claims;
|
|
328
|
+
result.checks.signature = true;
|
|
329
|
+
|
|
330
|
+
const bundle = Array.isArray(input?.bundle) && input.bundle.every((j) => typeof j === "string") ? input.bundle : null;
|
|
331
|
+
if (!bundle) {
|
|
332
|
+
return { ...result, reason: "malformed_bundle", checks: { ...result.checks, bundle: false } };
|
|
333
|
+
}
|
|
334
|
+
|
|
335
|
+
// 2. The root and every total, recomputed from the bundle.
|
|
336
|
+
const decoded = bundle.map(decodePayload);
|
|
337
|
+
const totals = bundleTotals(decoded);
|
|
338
|
+
if (sessionRoot(bundle) !== (claims.root ?? null)) result.mismatched.push("root");
|
|
339
|
+
if (claims.n !== bundle.length) result.mismatched.push("n");
|
|
340
|
+
if (claims.cost !== totals.cost) result.mismatched.push("cost");
|
|
341
|
+
if (claims.unp !== totals.unp) result.mismatched.push("unp");
|
|
342
|
+
if (canonical(claims.tree, TREE_KEYS) !== canonical(totals.tree, TREE_KEYS)) result.mismatched.push("tree");
|
|
343
|
+
if (canonical(claims.mdl, MODEL_KEYS) !== canonical(totals.mdl, MODEL_KEYS)) result.mismatched.push("mdl");
|
|
344
|
+
result.checks.bundle = result.mismatched.length === 0;
|
|
345
|
+
|
|
346
|
+
// 3. Every receipt verifies, and belongs to this session, agent and window.
|
|
347
|
+
const seen = new Set();
|
|
348
|
+
for (let index = 0; index < bundle.length; index++) {
|
|
349
|
+
const id = orNull(decoded[index]?.jti);
|
|
350
|
+
const verified = await verifyReceipt(bundle[index], opts);
|
|
351
|
+
let reason = verified.ok ? null : verified.reason;
|
|
352
|
+
if (verified.ok) {
|
|
353
|
+
const c = verified.claims;
|
|
354
|
+
const t = Math.floor(num(c.t0) / 1000);
|
|
355
|
+
if (seen.has(c.jti)) reason = "duplicate";
|
|
356
|
+
else if (c.ctx?.ses !== claims.ses?.id) reason = "other_session";
|
|
357
|
+
else if (c.agid !== claims.sub) reason = "other_agent";
|
|
358
|
+
else if (!(t >= num(claims.per?.from) && t < num(claims.per?.to))) reason = "outside_period";
|
|
359
|
+
seen.add(c.jti);
|
|
360
|
+
}
|
|
361
|
+
if (reason) result.rejected.push({ index, id, reason });
|
|
362
|
+
}
|
|
363
|
+
result.checks.receipts = result.rejected.length === 0;
|
|
364
|
+
|
|
365
|
+
// 4. The user's own record.
|
|
366
|
+
if (input.journal !== undefined) {
|
|
367
|
+
const journaled = journalIds(input.journal, claims.ses?.id);
|
|
368
|
+
if (!journaled) {
|
|
369
|
+
result.reason = "malformed_journal";
|
|
370
|
+
result.checks.journal = false;
|
|
371
|
+
} else {
|
|
372
|
+
const inBundle = new Set(decoded.map((c) => orNull(c?.jti)).filter(Boolean));
|
|
373
|
+
const predecessors = new Set(decoded.map((c) => orNull(c?.prev)).filter(Boolean));
|
|
374
|
+
result.otherSessions = journaled.other;
|
|
375
|
+
const ids = new Set(journaled.ids);
|
|
376
|
+
result.missing = [...ids].filter((id) => !inBundle.has(id) && !predecessors.has(id));
|
|
377
|
+
for (const id of inBundle) {
|
|
378
|
+
if (!ids.has(id)) {
|
|
379
|
+
result.unjournaled.push({ id, why: predecessors.has(id) ? "failover_predecessor" : "not_in_journal" });
|
|
380
|
+
}
|
|
381
|
+
}
|
|
382
|
+
result.checks.journal = result.missing.length === 0;
|
|
383
|
+
}
|
|
384
|
+
}
|
|
385
|
+
|
|
386
|
+
const { signature, bundle: b, receipts, journal } = result.checks;
|
|
387
|
+
result.ok = signature && b === true && receipts === true && journal !== false;
|
|
388
|
+
return result;
|
|
389
|
+
}
|
|
390
|
+
|
|
187
391
|
/** Human-readable one-liners. Kept here so the CLI and its tests agree on wording. */
|
|
188
392
|
export const FAILURE_REASONS = {
|
|
189
393
|
malformed: "not a compact JWS",
|
|
@@ -195,4 +399,10 @@ export const FAILURE_REASONS = {
|
|
|
195
399
|
unsupported_version: "signed by a newer PassControl than this CLI understands",
|
|
196
400
|
wrong_audience: "minted for a different audience",
|
|
197
401
|
expired: "expired",
|
|
402
|
+
malformed_bundle: "the bundle is not a list of receipts",
|
|
403
|
+
malformed_journal: "the journal could not be read as a list of receipt ids",
|
|
404
|
+
other_session: "this receipt is not from the sealed session",
|
|
405
|
+
other_agent: "this receipt is from a different agent than the seal names",
|
|
406
|
+
outside_period: "this receipt falls outside the seal's time window",
|
|
407
|
+
duplicate: "the same receipt appears twice in the bundle",
|
|
198
408
|
};
|
package/package.json
CHANGED
package/sdk/verify.d.ts
CHANGED
|
@@ -257,6 +257,114 @@ export declare function verifyStatement(jws: string, options: VerifyOptions): Pr
|
|
|
257
257
|
* and the statement's `root`.
|
|
258
258
|
*/
|
|
259
259
|
export declare function verifyInclusion(receiptJws: string, proof: readonly InclusionProofStep[], root: Uint8Array | string): boolean;
|
|
260
|
+
export declare const SESSION_TYP = "passcontrol-session+jws";
|
|
261
|
+
/** The newest session-seal version this verifier understands. See SESSION_PROTOCOL. */
|
|
262
|
+
export declare const SESSION_SUPPORTED_VER: number;
|
|
263
|
+
/** One node of a session's agent tree. `agt: null` is the main agent; `par: null` is "spawned by the main agent". */
|
|
264
|
+
export interface SessionTreeNode {
|
|
265
|
+
agt: string | null;
|
|
266
|
+
par: string | null;
|
|
267
|
+
n: number;
|
|
268
|
+
cost: number;
|
|
269
|
+
/** Calls the gateway refused (`res.status` starting `blocked_`). */
|
|
270
|
+
refused: number;
|
|
271
|
+
}
|
|
272
|
+
export interface SessionClaims {
|
|
273
|
+
iss: string;
|
|
274
|
+
/** The agent id. */
|
|
275
|
+
sub: string;
|
|
276
|
+
jti: string;
|
|
277
|
+
iat: number;
|
|
278
|
+
fmt: string;
|
|
279
|
+
v: number;
|
|
280
|
+
/** The session id and who declared it (`claude-code`, `codex`, `sidecar`). Declared by the client, never authenticated. */
|
|
281
|
+
ses: {
|
|
282
|
+
id: string;
|
|
283
|
+
src: string;
|
|
284
|
+
};
|
|
285
|
+
/** Half-open window `[from, to)`, epoch seconds. */
|
|
286
|
+
per: {
|
|
287
|
+
from: number;
|
|
288
|
+
to: number;
|
|
289
|
+
};
|
|
290
|
+
n: number;
|
|
291
|
+
nr: number;
|
|
292
|
+
cost: number;
|
|
293
|
+
unp: number;
|
|
294
|
+
unk: number;
|
|
295
|
+
root: string | null;
|
|
296
|
+
tree: SessionTreeNode[];
|
|
297
|
+
mdl: {
|
|
298
|
+
mdl: string | null;
|
|
299
|
+
n: number;
|
|
300
|
+
cost: number;
|
|
301
|
+
}[];
|
|
302
|
+
}
|
|
303
|
+
/** Why one receipt in a bundle was not accepted as part of the session. */
|
|
304
|
+
export type SessionReceiptRejection = VerifyFailure | "duplicate" | "other_session" | "other_agent" | "outside_period";
|
|
305
|
+
export interface SessionVerifyResult {
|
|
306
|
+
/** All of: signature, bundle and receipts pass, and the journal check did not fail. */
|
|
307
|
+
ok: boolean;
|
|
308
|
+
/** Set when the seal itself failed, or when the bundle or journal could not be read. */
|
|
309
|
+
reason?: VerifyFailure | "malformed_bundle" | "malformed_journal";
|
|
310
|
+
claims?: SessionClaims;
|
|
311
|
+
/** null = not run. `journal` is null when no journal was given: the seal is then no stronger than a statement. */
|
|
312
|
+
checks: {
|
|
313
|
+
signature: boolean;
|
|
314
|
+
bundle: boolean | null;
|
|
315
|
+
receipts: boolean | null;
|
|
316
|
+
journal: boolean | null;
|
|
317
|
+
};
|
|
318
|
+
/** Seal claims that do not match what the bundle adds up to: root, n, cost, unp, tree, mdl. */
|
|
319
|
+
mismatched: string[];
|
|
320
|
+
rejected: {
|
|
321
|
+
index: number;
|
|
322
|
+
id: string | null;
|
|
323
|
+
reason: SessionReceiptRejection;
|
|
324
|
+
}[];
|
|
325
|
+
/** Journaled receipt ids the bundle does not contain. MISSING, not proof of tampering: see verifySession. */
|
|
326
|
+
missing: string[];
|
|
327
|
+
/** Bundle receipts the journal never saw. Reported, never a failure. */
|
|
328
|
+
unjournaled: {
|
|
329
|
+
id: string;
|
|
330
|
+
why: "failover_predecessor" | "not_in_journal";
|
|
331
|
+
}[];
|
|
332
|
+
/**
|
|
333
|
+
* Journal lines that name ANOTHER session (`ses`), left out of check 4: one sidecar
|
|
334
|
+
* run serves many sessions. A line that names none is checked as before.
|
|
335
|
+
*/
|
|
336
|
+
otherSessions: number;
|
|
337
|
+
}
|
|
338
|
+
export interface SessionBundle {
|
|
339
|
+
seal: string;
|
|
340
|
+
/** Every receipt the seal covers, as compact JWS, in seal order. */
|
|
341
|
+
bundle: string[];
|
|
342
|
+
/** The user's sidecar journal: receipt ids, or `{ id, ... }` entries. */
|
|
343
|
+
journal?: unknown;
|
|
344
|
+
}
|
|
345
|
+
/**
|
|
346
|
+
* Verify a session seal against its bundle and, when given, the user's journal.
|
|
347
|
+
*
|
|
348
|
+
* Four checks: (1) the seal's signature; (2) its root and totals recompute from
|
|
349
|
+
* the bundle; (3) every receipt in the bundle verifies and belongs to this
|
|
350
|
+
* session, agent and window; (4) every receipt id the user's sidecar journaled is
|
|
351
|
+
* in the bundle, directly or through a receipt's `prev` link.
|
|
352
|
+
*
|
|
353
|
+
* WHAT CHECK 4 ADDS. A statement can only show the issuer committed to a set. The
|
|
354
|
+
* journal is the user's own independent list of their calls, so a call left out
|
|
355
|
+
* of the seal is caught. Without a journal a seal is no stronger than a statement,
|
|
356
|
+
* and `checks.journal` is null to say so.
|
|
357
|
+
*
|
|
358
|
+
* WHAT `missing` MEANS. A journaled id that is absent is MISSING, never proof of
|
|
359
|
+
* tampering: the gateway's log write is best-effort, so a lost row and an
|
|
360
|
+
* omission look the same from here. Receipts in the bundle but not the journal
|
|
361
|
+
* (failover predecessors, direct calls, another machine) are reported in
|
|
362
|
+
* `unjournaled` and never fail the session.
|
|
363
|
+
*
|
|
364
|
+
* The session id inside each receipt is DECLARED by the client. Check 3 shows the
|
|
365
|
+
* issuer grouped what the client declared; it does not show who made the call.
|
|
366
|
+
*/
|
|
367
|
+
export declare function verifySession(input: SessionBundle, options: VerifyOptions): Promise<SessionVerifyResult>;
|
|
260
368
|
export interface VerifyAgentTokenOptions extends VerifyOptions {
|
|
261
369
|
/** The audience YOU are. Required: a token minted for someone else is not for you. */
|
|
262
370
|
audience: string;
|
package/sdk/verify.js
CHANGED
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
// edge runtimes, and the browser.
|
|
10
10
|
import { ed25519 } from "@noble/curves/ed25519";
|
|
11
11
|
import { sha256 } from "@noble/hashes/sha256";
|
|
12
|
-
import { RECEIPT_PROTOCOL, STATEMENT_PROTOCOL } from "../cli/protocols.mjs";
|
|
12
|
+
import { RECEIPT_PROTOCOL, SESSION_PROTOCOL, STATEMENT_PROTOCOL } from "../cli/protocols.mjs";
|
|
13
13
|
export const RECEIPT_TYP = "passcontrol-receipt+jwt";
|
|
14
14
|
export const AGENT_TOKEN_TYP = "passcontrol-agent+jwt";
|
|
15
15
|
/** The newest artifact version this verifier understands. */
|
|
@@ -264,6 +264,224 @@ export function verifyInclusion(receiptJws, proof, root) {
|
|
|
264
264
|
return false;
|
|
265
265
|
}
|
|
266
266
|
}
|
|
267
|
+
// ── Session seals ────────────────────────────────────────────────────────────
|
|
268
|
+
export const SESSION_TYP = "passcontrol-session+jws";
|
|
269
|
+
/** The newest session-seal version this verifier understands. See SESSION_PROTOCOL. */
|
|
270
|
+
export const SESSION_SUPPORTED_VER = SESSION_PROTOCOL.maximum;
|
|
271
|
+
// The same hashing as verifyInclusion, restated for the same reason: this file
|
|
272
|
+
// is vendored alone. Leaves in bundle order; an odd node is promoted unchanged.
|
|
273
|
+
function sessionHash(prefix, ...parts) {
|
|
274
|
+
const total = parts.reduce((sum, p) => sum + p.length, 1);
|
|
275
|
+
const buf = new Uint8Array(total);
|
|
276
|
+
buf[0] = prefix;
|
|
277
|
+
let at = 1;
|
|
278
|
+
for (const p of parts) {
|
|
279
|
+
buf.set(p, at);
|
|
280
|
+
at += p.length;
|
|
281
|
+
}
|
|
282
|
+
return sha256(buf);
|
|
283
|
+
}
|
|
284
|
+
/** Platform-neutral (no Buffer): this file also runs in the browser. */
|
|
285
|
+
function bytesToB64url(bytes) {
|
|
286
|
+
let bin = "";
|
|
287
|
+
for (const b of bytes)
|
|
288
|
+
bin += String.fromCharCode(b);
|
|
289
|
+
return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
|
|
290
|
+
}
|
|
291
|
+
function sessionRoot(bundle) {
|
|
292
|
+
if (bundle.length === 0)
|
|
293
|
+
return null;
|
|
294
|
+
let level = bundle.map((jws) => sessionHash(0x00, utf8(jws)));
|
|
295
|
+
while (level.length > 1) {
|
|
296
|
+
const next = [];
|
|
297
|
+
for (let i = 0; i < level.length; i += 2) {
|
|
298
|
+
const right = level[i + 1];
|
|
299
|
+
next.push(right ? sessionHash(0x01, level[i], right) : level[i]);
|
|
300
|
+
}
|
|
301
|
+
level = next;
|
|
302
|
+
}
|
|
303
|
+
return bytesToB64url(level[0]);
|
|
304
|
+
}
|
|
305
|
+
function decodePayload(jws) {
|
|
306
|
+
try {
|
|
307
|
+
const claims = JSON.parse(new TextDecoder().decode(b64urlToBytes(jws.split(".")[1] ?? "")));
|
|
308
|
+
return claims && typeof claims === "object" && !Array.isArray(claims) ? claims : null;
|
|
309
|
+
}
|
|
310
|
+
catch {
|
|
311
|
+
return null;
|
|
312
|
+
}
|
|
313
|
+
}
|
|
314
|
+
const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : 0);
|
|
315
|
+
const orNull = (v) => (typeof v === "string" ? v : null);
|
|
316
|
+
const TREE_KEYS = [{ name: "agt", text: true }, { name: "par", text: true }, { name: "n" }, { name: "cost" }, { name: "refused" }];
|
|
317
|
+
const MODEL_KEYS = [{ name: "mdl", text: true }, { name: "n" }, { name: "cost" }];
|
|
318
|
+
/** Tree and model lists, compared as sets: one canonical string each. */
|
|
319
|
+
function canonical(entries, keys) {
|
|
320
|
+
if (!Array.isArray(entries))
|
|
321
|
+
return null;
|
|
322
|
+
const rows = entries.map((e) => keys.map((k) => (k.text ? orNull(e?.[k.name]) : num(e?.[k.name]))));
|
|
323
|
+
const cmp = (a, b) => (JSON.stringify(a) < JSON.stringify(b) ? -1 : JSON.stringify(a) > JSON.stringify(b) ? 1 : 0);
|
|
324
|
+
return JSON.stringify(rows.sort(cmp));
|
|
325
|
+
}
|
|
326
|
+
function bundleTotals(decoded) {
|
|
327
|
+
const tree = new Map();
|
|
328
|
+
const models = new Map();
|
|
329
|
+
let cost = 0;
|
|
330
|
+
let unp = 0;
|
|
331
|
+
for (const c of decoded) {
|
|
332
|
+
if (!c)
|
|
333
|
+
continue;
|
|
334
|
+
const ctx = c.ctx && typeof c.ctx === "object" ? c.ctx : {};
|
|
335
|
+
const agt = orNull(ctx.agt);
|
|
336
|
+
const par = orNull(ctx.par);
|
|
337
|
+
const refused = typeof c.res?.status === "string" && c.res.status.startsWith("blocked_") ? 1 : 0;
|
|
338
|
+
const key = JSON.stringify([agt, par]);
|
|
339
|
+
const node = tree.get(key) ?? { agt, par, n: 0, cost: 0, refused: 0 };
|
|
340
|
+
node.n += 1;
|
|
341
|
+
node.cost += num(c.cost);
|
|
342
|
+
node.refused += refused;
|
|
343
|
+
tree.set(key, node);
|
|
344
|
+
const mdl = orNull(c.mdl);
|
|
345
|
+
const m = models.get(JSON.stringify(mdl)) ?? { mdl, n: 0, cost: 0 };
|
|
346
|
+
m.n += 1;
|
|
347
|
+
m.cost += num(c.cost);
|
|
348
|
+
models.set(JSON.stringify(mdl), m);
|
|
349
|
+
cost += num(c.cost);
|
|
350
|
+
if (c.unp === true)
|
|
351
|
+
unp += 1;
|
|
352
|
+
}
|
|
353
|
+
return { cost, unp, tree: [...tree.values()], mdl: [...models.values()] };
|
|
354
|
+
}
|
|
355
|
+
/** This session's journaled ids (and lines naming no session), and how many named another. */
|
|
356
|
+
function journalIds(journal, session) {
|
|
357
|
+
if (!Array.isArray(journal))
|
|
358
|
+
return null;
|
|
359
|
+
const ids = [];
|
|
360
|
+
let other = 0;
|
|
361
|
+
for (const entry of journal) {
|
|
362
|
+
const id = typeof entry === "string" ? entry : entry && typeof entry === "object" ? entry.id : undefined;
|
|
363
|
+
if (typeof id !== "string" || id.length === 0)
|
|
364
|
+
return null;
|
|
365
|
+
const ses = entry && typeof entry === "object" ? entry.ses : undefined;
|
|
366
|
+
if (typeof ses === "string" && ses !== session) {
|
|
367
|
+
other += 1;
|
|
368
|
+
continue;
|
|
369
|
+
}
|
|
370
|
+
ids.push(id);
|
|
371
|
+
}
|
|
372
|
+
return { ids, other };
|
|
373
|
+
}
|
|
374
|
+
/**
|
|
375
|
+
* Verify a session seal against its bundle and, when given, the user's journal.
|
|
376
|
+
*
|
|
377
|
+
* Four checks: (1) the seal's signature; (2) its root and totals recompute from
|
|
378
|
+
* the bundle; (3) every receipt in the bundle verifies and belongs to this
|
|
379
|
+
* session, agent and window; (4) every receipt id the user's sidecar journaled is
|
|
380
|
+
* in the bundle, directly or through a receipt's `prev` link.
|
|
381
|
+
*
|
|
382
|
+
* WHAT CHECK 4 ADDS. A statement can only show the issuer committed to a set. The
|
|
383
|
+
* journal is the user's own independent list of their calls, so a call left out
|
|
384
|
+
* of the seal is caught. Without a journal a seal is no stronger than a statement,
|
|
385
|
+
* and `checks.journal` is null to say so.
|
|
386
|
+
*
|
|
387
|
+
* WHAT `missing` MEANS. A journaled id that is absent is MISSING, never proof of
|
|
388
|
+
* tampering: the gateway's log write is best-effort, so a lost row and an
|
|
389
|
+
* omission look the same from here. Receipts in the bundle but not the journal
|
|
390
|
+
* (failover predecessors, direct calls, another machine) are reported in
|
|
391
|
+
* `unjournaled` and never fail the session.
|
|
392
|
+
*
|
|
393
|
+
* The session id inside each receipt is DECLARED by the client. Check 3 shows the
|
|
394
|
+
* issuer grouped what the client declared; it does not show who made the call.
|
|
395
|
+
*/
|
|
396
|
+
export async function verifySession(input, options) {
|
|
397
|
+
const jwksCache = options.jwksCache ?? new Map();
|
|
398
|
+
const result = {
|
|
399
|
+
ok: false,
|
|
400
|
+
checks: { signature: false, bundle: null, receipts: null, journal: null },
|
|
401
|
+
mismatched: [],
|
|
402
|
+
rejected: [],
|
|
403
|
+
missing: [],
|
|
404
|
+
unjournaled: [],
|
|
405
|
+
otherSessions: 0,
|
|
406
|
+
};
|
|
407
|
+
const sealed = await verifySigned(String(input?.seal ?? ""), SESSION_TYP, { ...options, jwksCache }, {
|
|
408
|
+
claim: "v",
|
|
409
|
+
max: SESSION_SUPPORTED_VER,
|
|
410
|
+
});
|
|
411
|
+
if (!sealed.ok)
|
|
412
|
+
return { ...result, reason: sealed.reason };
|
|
413
|
+
const claims = sealed.claims;
|
|
414
|
+
result.claims = claims;
|
|
415
|
+
result.checks.signature = true;
|
|
416
|
+
const bundle = Array.isArray(input?.bundle) && input.bundle.every((j) => typeof j === "string") ? input.bundle : null;
|
|
417
|
+
if (!bundle)
|
|
418
|
+
return { ...result, reason: "malformed_bundle", checks: { ...result.checks, bundle: false } };
|
|
419
|
+
// 2. The root and every total, recomputed from the bundle.
|
|
420
|
+
const decoded = bundle.map(decodePayload);
|
|
421
|
+
const totals = bundleTotals(decoded);
|
|
422
|
+
if (sessionRoot(bundle) !== (claims.root ?? null))
|
|
423
|
+
result.mismatched.push("root");
|
|
424
|
+
if (claims.n !== bundle.length)
|
|
425
|
+
result.mismatched.push("n");
|
|
426
|
+
if (claims.cost !== totals.cost)
|
|
427
|
+
result.mismatched.push("cost");
|
|
428
|
+
if (claims.unp !== totals.unp)
|
|
429
|
+
result.mismatched.push("unp");
|
|
430
|
+
if (canonical(claims.tree, TREE_KEYS) !== canonical(totals.tree, TREE_KEYS))
|
|
431
|
+
result.mismatched.push("tree");
|
|
432
|
+
if (canonical(claims.mdl, MODEL_KEYS) !== canonical(totals.mdl, MODEL_KEYS))
|
|
433
|
+
result.mismatched.push("mdl");
|
|
434
|
+
result.checks.bundle = result.mismatched.length === 0;
|
|
435
|
+
// 3. Every receipt verifies, and belongs to this session, agent and window.
|
|
436
|
+
// Traced steps describe the seal only; the receipts are checked untraced.
|
|
437
|
+
const receiptOptions = { ...options, jwksCache, onStep: undefined };
|
|
438
|
+
const seen = new Set();
|
|
439
|
+
for (let index = 0; index < bundle.length; index++) {
|
|
440
|
+
const id = orNull(decoded[index]?.jti);
|
|
441
|
+
const verified = await verifyReceipt(bundle[index], receiptOptions);
|
|
442
|
+
let reason = verified.ok ? null : verified.reason;
|
|
443
|
+
if (verified.ok) {
|
|
444
|
+
const c = verified.claims;
|
|
445
|
+
const t = Math.floor(num(c.t0) / 1000);
|
|
446
|
+
if (seen.has(c.jti))
|
|
447
|
+
reason = "duplicate";
|
|
448
|
+
else if (c.ctx?.ses !== claims.ses?.id)
|
|
449
|
+
reason = "other_session";
|
|
450
|
+
else if (c.agid !== claims.sub)
|
|
451
|
+
reason = "other_agent";
|
|
452
|
+
else if (!(t >= num(claims.per?.from) && t < num(claims.per?.to)))
|
|
453
|
+
reason = "outside_period";
|
|
454
|
+
seen.add(c.jti);
|
|
455
|
+
}
|
|
456
|
+
if (reason)
|
|
457
|
+
result.rejected.push({ index, id, reason });
|
|
458
|
+
}
|
|
459
|
+
result.checks.receipts = result.rejected.length === 0;
|
|
460
|
+
// 4. The user's own record.
|
|
461
|
+
if (input.journal !== undefined) {
|
|
462
|
+
const journaled = journalIds(input.journal, claims.ses?.id);
|
|
463
|
+
if (!journaled) {
|
|
464
|
+
result.reason = "malformed_journal";
|
|
465
|
+
result.checks.journal = false;
|
|
466
|
+
}
|
|
467
|
+
else {
|
|
468
|
+
const inBundle = new Set(decoded.map((c) => orNull(c?.jti)).filter((v) => v !== null));
|
|
469
|
+
const predecessors = new Set(decoded.map((c) => orNull(c?.prev)).filter((v) => v !== null));
|
|
470
|
+
result.otherSessions = journaled.other;
|
|
471
|
+
const ids = new Set(journaled.ids);
|
|
472
|
+
result.missing = [...ids].filter((id) => !inBundle.has(id) && !predecessors.has(id));
|
|
473
|
+
for (const id of inBundle) {
|
|
474
|
+
if (!ids.has(id)) {
|
|
475
|
+
result.unjournaled.push({ id, why: predecessors.has(id) ? "failover_predecessor" : "not_in_journal" });
|
|
476
|
+
}
|
|
477
|
+
}
|
|
478
|
+
result.checks.journal = result.missing.length === 0;
|
|
479
|
+
}
|
|
480
|
+
}
|
|
481
|
+
const { signature, bundle: b, receipts, journal } = result.checks;
|
|
482
|
+
result.ok = signature && b === true && receipts === true && journal !== false;
|
|
483
|
+
return result;
|
|
484
|
+
}
|
|
267
485
|
/**
|
|
268
486
|
* Verify an agent-to-agent token.
|
|
269
487
|
*
|