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/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
- return Array.isArray(body?.keys) ? body.keys : [];
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "passcontrol",
3
- "version": "1.3.0",
3
+ "version": "1.4.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
@@ -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
  *