passcontrol 1.7.0 → 1.7.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.
@@ -3018,7 +3018,7 @@ function configureCodexSubscription(opts = {}) {
3018
3018
  }
3019
3019
  step(`Start the sidecar before Codex: ${cliCommand(port === 8788 ? "sidecar" : `sidecar --port ${port}`)}`);
3020
3020
  step("Your ChatGPT login stays between Codex and OpenAI. PassControl never sees it or sits in the path.");
3021
- step("What Codex's tools return is also scanned on this machine for the injection guard (the PostToolUse hook). That hook never blocks a tool or changes what it returned.");
3021
+ step("For the injection guard, the tool output Codex hands its PostToolUse hook is also checked on this machine; some built-in or hosted tools may not hand theirs over. That hook never blocks a tool or changes what it returned.");
3022
3022
  step("What it does: a suspended agent, or the kill switch, blocks the next prompt and refuses tools. The agent's tool rules refuse what they deny; an \"ask the owner\" rule waits for the owner's answer.");
3023
3023
  step("What it cannot do, plainly:");
3024
3024
  step(" Codex has no strict hook mode. If the sidecar is not running, or a hook fails, Codex goes ahead (with a warning when the sidecar is down).");
@@ -41,6 +41,7 @@ const newKey = () => `evt_${randomBytes(16).toString("base64url")}`;
41
41
  function toWire(event, key) {
42
42
  if (event.kind === "tool_decision") return toolDecisionWire(event, key);
43
43
  if (event.kind === "injection_finding") return injectionFindingWire(event, key);
44
+ if (event.kind === "injection_incomplete") return injectionIncompleteWire(event, key);
44
45
  const wire = {
45
46
  key,
46
47
  kind: event.kind === "api_error" ? "model_error" : "model_call",
@@ -97,6 +98,25 @@ function injectionFindingWire(event, key) {
97
98
  return wire;
98
99
  }
99
100
 
101
+ // What the sidecar could not fully check (1.7.1): why, where, and a hash over what went
102
+ // unread. No families: nothing was found, because not all of it was read.
103
+ function injectionIncompleteWire(event, key) {
104
+ const wire = {
105
+ key,
106
+ kind: "injection_incomplete",
107
+ at: event.at,
108
+ source: event.source,
109
+ path: event.path,
110
+ tool: event.tool,
111
+ gap: event.gap,
112
+ detector: event.detector,
113
+ normalization_version: event.normalization_version,
114
+ block_sha256: event.block_sha256,
115
+ };
116
+ for (const name of Object.keys(wire)) if (wire[name] === null || wire[name] === undefined) delete wire[name];
117
+ return wire;
118
+ }
119
+
100
120
  /**
101
121
  * @param {{
102
122
  * send: (events: object[]) => Promise<{ status: number, error?: string, retryAfterS?: number }>,
@@ -1,8 +1,11 @@
1
1
  // Local, best-effort tool-result scan. Only fixed metadata and a hash leave here.
2
- import { createHash } from "node:crypto";
2
+ import { createHash, randomBytes } from "node:crypto";
3
3
  import { scanText, INJECTION_DETECTOR, INJECTION_NORMALIZATION, INJECTION_FAMILIES } from "./injection-scan.mjs";
4
4
 
5
- const MAX_LEAF_BYTES = 1024 * 1024;
5
+ // What one hook may scan, in UTF-8 bytes. Each leaf is scanned whole, never in chunks
6
+ // (a chunk boundary would split a fence or hidden-text span); 8 MB of hostile text scans
7
+ // in under half a second (measured 2026-10-31). Past it, the rest is a gap.
8
+ export const HOOK_SCAN_BUDGET = 8 * 1024 * 1024;
6
9
  const MAX_FINDINGS = 20;
7
10
  const MAX_SEEN = 1000;
8
11
  const PATH = /^[A-Za-z0-9_.\[\]?-]{1,512}$/;
@@ -33,13 +36,29 @@ function* stringLeaves(value, path) {
33
36
  }
34
37
  }
35
38
 
39
+ /** One `injection_incomplete` event for what went unread (1.7.1, external review P1):
40
+ * where the first such leaf was, and a hash over the hashes of every one, so the same
41
+ * output re-sent is the same gap and different unread output is a new one. */
42
+ function gapEvent(gap, unread, at) {
43
+ const [first] = unread;
44
+ const digest = createHash("sha256").update(`gap:${gap}:`);
45
+ for (const leaf of unread) digest.update(leaf.hash);
46
+ return {
47
+ kind: "injection_incomplete", at, source: "tool_result", path: first.path,
48
+ ...(first.tool ? { tool: first.tool } : {}),
49
+ gap, detector: INJECTION_DETECTOR, normalization_version: INJECTION_NORMALIZATION, block_sha256: digest.digest("hex"),
50
+ };
51
+ }
52
+
36
53
  /** `seen` belongs to one sidecar; no text or hook input is retained. Never throws.
37
- * `scan` is injectable for failure tests. Failed scans emit nothing and do not
38
- * consume hashes, allowing a later hook to retry.
54
+ * `scan` is injectable for failure tests. What could not be read (past the budget, or
55
+ * where the scanner threw) is reported as a gap, never left out as if clean.
39
56
  */
40
57
  export function findingsFromHook(input, { seen = new Set(), now = Date.now, scan = scanText } = {}) {
41
58
  const events = [];
42
59
  const found = new Set();
60
+ const unread = { too_large: [], scan_failed: [] };
61
+ let budget = HOOK_SCAN_BUDGET;
43
62
  try {
44
63
  let calls;
45
64
  if (input?.hook_event_name === "PostToolBatch" && Array.isArray(input.tool_calls)) {
@@ -50,29 +69,82 @@ export function findingsFromHook(input, { seen = new Set(), now = Date.now, scan
50
69
  const field = ["tool_response", "tool_output", "output"].find((key) => input[key] != null);
51
70
  calls = field ? [[input, input[field], field]] : [];
52
71
  } else return [];
72
+ // Every leaf is read; MAX_FINDINGS caps what is uploaded, strong findings first
73
+ // (1.7.1: a cap that stopped the scan let twenty weak tells hide a strong one).
53
74
  for (const [call, response, root] of calls) {
54
- if (events.length >= MAX_FINDINGS) break;
75
+ const tool = typeof call.tool_name === "string" && TOOL.test(call.tool_name) ? call.tool_name : undefined;
55
76
  for (const [text, path] of stringLeaves(response, root)) {
56
- if (Buffer.byteLength(text, "utf8") > MAX_LEAF_BYTES) continue;
57
77
  const hash = createHash("sha256").update(text, "utf8").digest("hex");
58
78
  if (seen.has(hash) || found.has(hash)) continue;
59
- const hits = scan(text);
60
- const families = INJECTION_FAMILIES.filter((family) => hits.some((hit) => hit.family === family));
79
+ const bytes = Buffer.byteLength(text, "utf8");
80
+ if (bytes > budget) {
81
+ unread.too_large.push({ path, tool, hash });
82
+ continue;
83
+ }
84
+ budget -= bytes;
85
+ let families, severity;
86
+ try {
87
+ const hits = scan(text);
88
+ families = INJECTION_FAMILIES.filter((family) => hits.some((hit) => hit.family === family));
89
+ severity = hits.some((hit) => hit.severity === "high") ? "high" : "low";
90
+ } catch {
91
+ unread.scan_failed.push({ path, tool, hash });
92
+ continue;
93
+ }
61
94
  if (!families.length) continue;
62
95
  events.push({
63
96
  kind: "injection_finding", at: now(), source: "tool_result", path,
64
- ...(typeof call.tool_name === "string" && TOOL.test(call.tool_name) ? { tool: call.tool_name } : {}),
65
- families, severity: hits.some((hit) => hit.severity === "high") ? "high" : "low",
97
+ ...(tool ? { tool } : {}),
98
+ families, severity,
66
99
  detector: INJECTION_DETECTOR, normalization_version: INJECTION_NORMALIZATION, block_sha256: hash,
67
100
  });
68
101
  found.add(hash);
69
- if (events.length >= MAX_FINDINGS) break;
70
102
  }
71
103
  }
72
- for (const hash of found) seen.add(hash);
104
+ // Gaps first: at most one per kind, and the hold depends on them as on a strong tell.
105
+ const gaps = Object.entries(unread).filter(([, leaves]) => leaves.length).map(([gap, leaves]) => gapEvent(gap, leaves, now()))
106
+ .filter((e) => !seen.has(e.block_sha256));
107
+ const kept = [...gaps, ...events.filter((e) => e.severity === "high"), ...events.filter((e) => e.severity !== "high")].slice(0, MAX_FINDINGS);
108
+ // Only what is uploaded is seen: a block past the cap is found again by a later hook.
109
+ for (const event of kept) seen.add(event.block_sha256);
110
+ while (seen.size > MAX_SEEN) seen.delete(seen.values().next().value);
111
+ return kept;
112
+ } catch {
113
+ // The hook as a whole went unread. Nothing identifies it, so the gap is new each
114
+ // time: in hold mode that holds, the safe side for a failure this rare.
115
+ try {
116
+ const path = input.hook_event_name === "PostToolUse" ? "tool_response" : "tool_calls";
117
+ return [gapEvent("scan_failed", [{ path, hash: randomBytes(32).toString("hex") }], Date.now())];
118
+ } catch {
119
+ return [];
120
+ }
121
+ }
122
+ }
123
+
124
+ const HOOK_NAME = /"hook_event_name"\s*:\s*"([A-Za-z]{1,64})"/;
125
+ // A tool's own fields. A name that comes after one may be inside the tool's output.
126
+ const TOOL_FIELD = /"(?:tool_response|tool_output|tool_calls|tool_input|output)"\s*:/;
127
+
128
+ /**
129
+ * A hook body over the sidecar's limit is refused unread (cli/sidecar.mjs). Unless its
130
+ * start plainly names a hook that carries no tool output, that output went unchecked:
131
+ * one too_large gap, from the start of the body (`head`) and a SHA-256 of all of it.
132
+ * Never throws.
133
+ */
134
+ export function gapFromOversizedHook(head, bodySha256, { seen = new Set(), now = Date.now } = {}) {
135
+ try {
136
+ const match = HOOK_NAME.exec(head);
137
+ const toolField = TOOL_FIELD.exec(head);
138
+ // Claude Code and Codex both send the hook's name before the tool's fields.
139
+ const name = match && !(toolField && toolField.index < match.index) ? match[1] : undefined;
140
+ if (name && name !== "PostToolBatch" && name !== "PostToolUse") return null;
141
+ const path = name === "PostToolBatch" ? "tool_calls" : name === "PostToolUse" ? "tool_response" : "hook_input";
142
+ const event = gapEvent("too_large", [{ path, hash: bodySha256 }], now());
143
+ if (seen.has(event.block_sha256)) return null;
144
+ seen.add(event.block_sha256);
73
145
  while (seen.size > MAX_SEEN) seen.delete(seen.values().next().value);
74
- return events;
146
+ return event;
75
147
  } catch {
76
- return [];
148
+ return null;
77
149
  }
78
150
  }
package/cli/sidecar.mjs CHANGED
@@ -1,4 +1,4 @@
1
- import { randomUUID } from "node:crypto";
1
+ import { createHash, randomUUID } from "node:crypto";
2
2
  import http from "node:http";
3
3
  import net from "node:net";
4
4
  import { Readable } from "node:stream";
@@ -8,7 +8,7 @@ import { createVisaClient } from "./visa-client.mjs";
8
8
  import { declaredLineage, declaredSession } from "./declared-session.mjs";
9
9
  import { defaultJournalDir, openJournal } from "./journal.mjs";
10
10
  import { heldUnderTaint } from "./injection-hold.mjs";
11
- import { findingsFromHook } from "./injection-sidecar.mjs";
11
+ import { findingsFromHook, gapFromOversizedHook } from "./injection-sidecar.mjs";
12
12
  import { answer, createWatchFeed, isNotACall, isLocalCaller, LOCAL_PREFIX, peekText, providerOf, refusalCode, requestModel } from "./watch-feed.mjs";
13
13
  import { createStopGate, HOOK_PATH, SELF_READ_TIMEOUT_MS, selfAnswerState } from "./subscription-gate.mjs";
14
14
  import { createToolGate } from "./tool-gate.mjs";
@@ -59,9 +59,13 @@ const OTLP_BODY_LIMIT = 4 * 1024 * 1024;
59
59
  // counted a second time. Bounded: the oldest is forgotten first.
60
60
  const RELAYED_SESSIONS_MAX = 1000;
61
61
 
62
- // Claude Code's hook input carries the tool's input (a whole file for Write), so it
63
- // is not small; past this it is refused rather than buffered.
64
- const HOOK_BODY_LIMIT = 1024 * 1024;
62
+ // Claude Code's hook input carries the tool's input (a whole file for Write), and a
63
+ // post-tool hook carries the tool's output, so it is not small; past this it is refused
64
+ // rather than buffered. Above the scan budget (8 MB, cli/injection-sidecar.mjs), so a
65
+ // body near it is still read; past it, a post-tool body is a gap, never clean (1.7.1).
66
+ const HOOK_BODY_LIMIT = 10 * 1024 * 1024;
67
+ // How much of a refused body is kept, to see which hook sent it.
68
+ const HOOK_PEEK_BYTES = 64 * 1024;
65
69
 
66
70
  // How long Claude Code waits for the hook, as configure wrote it into the URL
67
71
  // (`?t=600`); null for a hook that does not say (a Phase 1 install).
@@ -290,6 +294,19 @@ export function createSidecar({
290
294
  const body = await response.json().catch(() => ({}));
291
295
  return { status: response.status, error: body?.error, retryAfterS: Number(response.headers.get("retry-after")) };
292
296
  }
297
+ // 1.7.1 F2: a self-hosted gateway is a dev server that compiles each route on its first
298
+ // request, which outlasted the hooks' short wait, so a held agent's first tools after a
299
+ // start went ahead with the warning. Asked once, after the visa works: /self as the hooks
300
+ // ask it, and the two POST routes with a GET and no credential, which loads them, asks
301
+ // the owner nothing and uploads nothing. Never throws.
302
+ const WARM_ROUTE_TIMEOUT_MS = 60_000;
303
+ async function warmRoutes() {
304
+ const touch = (path) =>
305
+ fetch(`${origin}${path}`, { method: "GET", signal: AbortSignal.timeout(WARM_ROUTE_TIMEOUT_MS) })
306
+ .then((response) => response.body?.cancel())
307
+ .catch(() => {});
308
+ await Promise.all([readSelf(null).catch(() => {}), touch(TOOL_APPROVALS_PATH), touch(CLIENT_EVENTS_PATH)]);
309
+ }
293
310
  const injectionSeen = new Set();
294
311
  const uploader = reportCalls ? createCallUploader({ send: sendReportedCalls }) : null;
295
312
  // Its decisions reach the agent's page with the reported calls (same opt-out).
@@ -437,14 +454,34 @@ export function createSidecar({
437
454
  }
438
455
  const chunks = [];
439
456
  let size = 0;
440
- let tooBig = false;
457
+ // Past the limit: only a hash of the whole body and its start are kept.
458
+ let digest = null;
459
+ let head = "";
441
460
  req.on("data", (c) => {
442
461
  size += c.length;
443
- if (size > HOOK_BODY_LIMIT) tooBig = true;
444
- else chunks.push(c);
462
+ if (digest) return void digest.update(c);
463
+ chunks.push(c);
464
+ if (size <= HOOK_BODY_LIMIT) return;
465
+ digest = createHash("sha256");
466
+ for (const chunk of chunks) digest.update(chunk);
467
+ head = Buffer.concat(chunks).subarray(0, HOOK_PEEK_BYTES).toString("utf8");
468
+ chunks.length = 0;
445
469
  });
446
470
  req.on("end", async () => {
447
- if (tooBig) return answer(res, 413, "hook_too_large", "Hook input over 1 MB.");
471
+ if (digest) {
472
+ // Synchronous, like the scan below: the next PreToolUse already knows.
473
+ try {
474
+ const gap = gapFromOversizedHook(head, digest.digest("hex"), { seen: injectionSeen });
475
+ if (gap) {
476
+ highVersion++;
477
+ feed.injection(gap);
478
+ uploader?.add(gap);
479
+ }
480
+ } catch {
481
+ // Local telemetry must never change the hook answer.
482
+ }
483
+ return answer(res, 413, "hook_too_large", "Hook input over 10 MB.");
484
+ }
448
485
  let input;
449
486
  try {
450
487
  input = JSON.parse(Buffer.concat(chunks).toString("utf8"));
@@ -454,6 +491,26 @@ export function createSidecar({
454
491
  if (!input || typeof input !== "object" || Array.isArray(input)) {
455
492
  return answer(res, 400, "hook_not_json", "Expected Claude Code's hook input, a JSON object.");
456
493
  }
494
+ // Injection tells in what the tools returned (plans/injection-guard.md §2b). Before
495
+ // the answer and before any await (1.7.1, external review P4): the event loop runs
496
+ // nothing else meanwhile, so no PreToolUse can be decided before a finding here has
497
+ // bumped highVersion, which makes it flush the upload and re-read the taint first.
498
+ // Bounded by HOOK_BODY_LIMIT; 8 MB of hostile text scans in under half a second
499
+ // (measured 2026-10-31). Only the upload is asynchronous.
500
+ if (input.hook_event_name === "PostToolBatch" || input.hook_event_name === "PostToolUse") {
501
+ try {
502
+ for (const event of findingsFromHook(input, { seen: injectionSeen })) {
503
+ // A gap holds like a strong finding (1.7.1).
504
+ if (event.severity === "high" || event.kind === "injection_incomplete") highVersion++;
505
+ feed.injection(event);
506
+ // With the reported calls (same opt-out). The gateway records it only while
507
+ // the owner has the guard on, and never says which.
508
+ uploader?.add(event);
509
+ }
510
+ } catch {
511
+ // Local telemetry must never change the hook answer.
512
+ }
513
+ }
457
514
  let out;
458
515
  try {
459
516
  if (input.hook_event_name === "PreToolUse") await freshInjectionFor(input.tool_name);
@@ -476,23 +533,6 @@ export function createSidecar({
476
533
  const body = JSON.stringify(out);
477
534
  res.writeHead(200, { "content-type": "application/json", "content-length": Buffer.byteLength(body), "cache-control": "no-store" });
478
535
  res.end(body);
479
- // Injection tells in what the tools returned (plans/injection-guard.md §2b): after
480
- // the answer is written, so the scan never delays or changes it.
481
- if (input.hook_event_name === "PostToolBatch" || input.hook_event_name === "PostToolUse") {
482
- setImmediate(() => {
483
- try {
484
- for (const event of findingsFromHook(input, { seen: injectionSeen })) {
485
- if (event.severity === "high") highVersion++;
486
- feed.injection(event);
487
- // With the reported calls (same opt-out). The gateway records it only while
488
- // the owner has the guard on, and never says which.
489
- uploader?.add(event);
490
- }
491
- } catch {
492
- // Local telemetry must never change or delay the hook answer.
493
- }
494
- });
495
- }
496
536
  });
497
537
  req.on("error", () => res.destroy());
498
538
  }
@@ -738,7 +778,7 @@ export function createSidecar({
738
778
  });
739
779
 
740
780
  server.on("close", () => uploader?.close());
741
- return { server, ollamaServer, getVisa: visas.getVisa, runId, feed, uploader };
781
+ return { server, ollamaServer, getVisa: visas.getVisa, warmRoutes, runId, feed, uploader };
742
782
  }
743
783
 
744
784
  /**
@@ -771,7 +811,7 @@ export function startSidecar(opts) {
771
811
  onError: (e) =>
772
812
  warn(`journal: could not write ${journal.path} (${e.message}). Calls are unaffected; this run is no longer being recorded.`),
773
813
  });
774
- const { server, ollamaServer, getVisa, feed } = createSidecar({ ...opts, runId, journal });
814
+ const { server, ollamaServer, getVisa, warmRoutes, feed } = createSidecar({ ...opts, runId, journal });
775
815
  if (ollamaPort != null) {
776
816
  ollamaServer.listen(ollamaPort, host, () => {
777
817
  step(`Ollama API (local models) on http://${host}:${ollamaPort}: set OLLAMA_HOST=${host}:${ollamaPort}`);
@@ -817,6 +857,8 @@ export function startSidecar(opts) {
817
857
  if (ollamaServer.listening) ollamaServer.close();
818
858
  setTimeout(() => process.exit(1), 1000).unref();
819
859
  },
860
+ }).then((warmed) => {
861
+ if (warmed) void warmRoutes();
820
862
  });
821
863
  });
822
864
  return server;
package/cli/tool-gate.mjs CHANGED
@@ -116,7 +116,8 @@ export function createToolGate({ askOwner, onDecision = () => {}, now = () => Da
116
116
  const original = evaluateToolRules(parsed, input);
117
117
  const hit = injection === "tainted" ? underTaint(original, input.tool_name) : original;
118
118
  const escalated = hit.reason === "injection_taint";
119
- const guardText = "This tool was held by the injection guard because the agent recently read something that looked like a prompt injection.";
119
+ // `/self` says only that the agent is tainted, not why: a tell, or output not fully checked (1.7.1).
120
+ const guardText = "This tool was held by the injection guard: something the agent recently read looked like a prompt injection, or could not be fully checked.";
120
121
  let warning = {};
121
122
  if (injection === "unknown" && (injectionWarnedAt === null || now() - injectionWarnedAt >= WARN_EVERY_MS)) {
122
123
  injectionWarnedAt = now();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "passcontrol",
3
- "version": "1.7.0",
3
+ "version": "1.7.1",
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",
@@ -45,6 +45,6 @@
45
45
  "@noble/curves": "^1.6.0",
46
46
  "@noble/hashes": "^1.5.0",
47
47
  "jose": "^5.9.3",
48
- "zod": "^3.25.76"
48
+ "zod": "^4.6.7"
49
49
  }
50
50
  }