passcontrol 1.2.1 → 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/README.md +3 -2
- package/bin/passcontrol.mjs +397 -18
- package/cli/budget-format.mjs +76 -0
- package/cli/claude-code.mjs +160 -0
- package/cli/codex.mjs +102 -0
- package/cli/config.mjs +3 -3
- package/cli/declared-session.mjs +33 -0
- package/cli/integration-defaults.d.mts +1 -0
- package/cli/integration-defaults.mjs +5 -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/presets.mjs +15 -5
- package/cli/protocols.d.mts +2 -0
- package/cli/protocols.mjs +14 -0
- package/cli/proxy-policy.mjs +1 -0
- package/cli/sidecar.mjs +93 -5
- package/cli/statusline.mjs +89 -0
- package/cli/verify.mjs +215 -5
- package/package.json +2 -2
- package/sdk/README.md +1 -1
- package/sdk/passcontrol.d.ts +1 -1
- package/sdk/verify.d.ts +108 -0
- package/sdk/verify.js +219 -1
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
|
*
|