passcontrol 1.6.0 → 1.7.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/tool-gate.mjs CHANGED
@@ -25,6 +25,7 @@
25
25
  //
26
26
  // Each outcome that is not a plain pass is handed to `onDecision` for the agent's
27
27
  // page: tool name, decision, rule number and wait. Never the command, path or URL.
28
+ import { underTaint } from "./injection-hold.mjs";
28
29
  import { evaluateToolRules, parseToolRules } from "./tool-rules.mjs";
29
30
 
30
31
  /** The wait ends this long before Claude Code would give up on the hook. */
@@ -46,12 +47,17 @@ function verdict(permissionDecision, reason) {
46
47
  * askOwner: (input: object, ask: { ruleIndex: number, subject: string, session: string | null, waitMs: number }) =>
47
48
  * Promise<{ state: "approved" | "denied" | "timeout" | "unavailable" | "full" | "refused" | "too_large" }>,
48
49
  * onDecision?: (record: { session: string | null, agent: string | null, tool: string, decision: string, ruleIndex: number | null, waitMs: number }) => void,
50
+ * onHold?: (record: { tool: string, outcome: string }) => void,
51
+ * refresh?: () => Promise<object | null>,
49
52
  * now?: () => number,
50
53
  * dashboardUrl?: string,
51
54
  * }} options
52
55
  */
53
- export function createToolGate({ askOwner, onDecision = () => {}, now = () => Date.now(), dashboardUrl = "" }) {
56
+ export function createToolGate({ askOwner, onDecision = () => {}, now = () => Date.now(), dashboardUrl = "", onHold = () => {}, refresh = async () => null }) {
54
57
  let warnedAt = null;
58
+ let injectionWarnedAt = null;
59
+ let needsRefresh = false;
60
+ let refreshing = null;
55
61
  const where = dashboardUrl ? ` on ${dashboardUrl}` : " on the agent's dashboard page";
56
62
  // Said with every rule's refusal: told only "the tool rules refuse this", Claude
57
63
  // Code went looking for the rule in the local PassControl config, which has none.
@@ -79,16 +85,24 @@ export function createToolGate({ askOwner, onDecision = () => {}, now = () => Da
79
85
  * @param {{ read: { state: string, document?: unknown }, at: number } | null} rulesEntry
80
86
  * The rules from the latest trusted /self read, or null.
81
87
  * @param {number | null} hookTimeoutS What the hook's URL says it waits; null when it does not say.
88
+ * @param {"off" | "clear" | "tainted" | "unknown"} injection
82
89
  */
83
- async function decide(input, rulesEntry, hookTimeoutS) {
90
+ async function decide(input, rulesEntry, hookTimeoutS, injection = "off") {
84
91
  if (input?.hook_event_name !== "PreToolUse") return {};
92
+ if (needsRefresh || refreshing) {
93
+ if (!refreshing) {
94
+ needsRefresh = false;
95
+ refreshing = Promise.resolve().then(refresh).finally(() => { refreshing = null; });
96
+ }
97
+ const fresh = await refreshing;
98
+ if (fresh) ({ rulesEntry, injection } = fresh);
99
+ }
85
100
  const read = rulesEntry?.read;
86
- if (read?.state === "none") return {};
87
101
  if (read?.state === "invalid") {
88
102
  record(input, "rules_invalid", null, 0);
89
103
  return verdict("deny", `PassControl: this agent's tool rules cannot be read here, so no tool runs until they are fixed${where}.`);
90
104
  }
91
- const parsed = read?.state === "ok" ? parseToolRules(read.document) : null;
105
+ const parsed = read?.state === "none" ? parseToolRules({ rules: [] }) : read?.state === "ok" ? parseToolRules(read.document) : null;
92
106
  if (!parsed) {
93
107
  if (warnedAt !== null && now() - warnedAt < WARN_EVERY_MS) return {};
94
108
  warnedAt = now();
@@ -99,36 +113,77 @@ export function createToolGate({ askOwner, onDecision = () => {}, now = () => Da
99
113
  return verdict("deny", `PassControl: this agent's tool rules cannot be read here, so no tool runs until they are fixed${where}.`);
100
114
  }
101
115
 
102
- const hit = evaluateToolRules(parsed, input);
103
- if (hit.effect === null) return {};
104
- const rule = `rule ${hit.ruleIndex + 1}`;
116
+ const original = evaluateToolRules(parsed, input);
117
+ const hit = injection === "tainted" ? underTaint(original, input.tool_name) : original;
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.";
120
+ let warning = {};
121
+ if (injection === "unknown" && (injectionWarnedAt === null || now() - injectionWarnedAt >= WARN_EVERY_MS)) {
122
+ injectionWarnedAt = now();
123
+ warning = { systemMessage: "PassControl could not check this agent's injection guard, so this goes ahead." };
124
+ }
125
+ const withWarning = (out) => ({ ...out, ...warning });
126
+ function holdRecord(outcome) {
127
+ if (escalated) {
128
+ try { onHold({ tool: String(input.tool_name ?? "").slice(0, 128), outcome }); } catch {}
129
+ }
130
+ }
131
+ const ruleIndex = escalated ? null : hit.ruleIndex;
132
+ if (hit.effect === null) return withWarning({});
133
+ const rule = escalated ? "injection guard" : `rule ${hit.ruleIndex + 1}`;
105
134
  if (hit.effect === "deny") {
106
135
  record(input, "deny", hit.ruleIndex, 0);
107
- return verdict("deny", `PassControl: the agent's tool rules refuse this (${rule}: ${short(hit.subject)}). ${rulesLive}`);
136
+ return withWarning(verdict("deny", `PassControl: the agent's tool rules refuse this (${rule}: ${short(hit.subject)}). ${rulesLive}`));
108
137
  }
109
138
  if (hit.effect === "ask") {
110
139
  record(input, "ask", hit.ruleIndex, 0);
111
- return verdict("ask", `PassControl: the agent's tool rules ask you to confirm this (${rule}: ${short(hit.subject)}). ${rulesLive}`);
140
+ return withWarning(verdict("ask", `PassControl: the agent's tool rules ask you to confirm this (${rule}: ${short(hit.subject)}). ${rulesLive}`));
112
141
  }
113
142
 
114
143
  // ask_owner
115
144
  const waitS = hookTimeoutS === null ? 0 : Math.min(parsed.approvalWaitS, hookTimeoutS - HOOK_MARGIN_S);
145
+ if (waitS < MIN_WAIT_S && escalated) {
146
+ record(input, "owner_unavailable", null, 0);
147
+ holdRecord("unavailable");
148
+ return verdict("deny", `PassControl: ${guardText} The hook cannot wait for the owner. Run \`passcontrol configure claude-code --subscription --write\`, then try again.`);
149
+ }
116
150
  if (waitS < MIN_WAIT_S) {
117
151
  record(input, "owner_unavailable", hit.ruleIndex, 0);
118
- return verdict(
152
+ return withWarning(verdict(
119
153
  "deny",
120
154
  `PassControl: this needs the agent's owner to say yes (${rule}), and Claude Code's hook would give up before the answer. Run \`passcontrol configure claude-code --subscription --write\`, then try again.`
121
- );
155
+ ));
122
156
  }
123
157
  const started = now();
124
158
  let answer;
125
159
  try {
126
- answer = await askOwner(input, { ruleIndex: hit.ruleIndex, subject: hit.subject, session: declared(input.session_id), waitMs: waitS * 1000 });
160
+ answer = await askOwner(input, { ruleIndex, subject: escalated ? "injection guard" : hit.subject, session: declared(input.session_id), waitMs: waitS * 1000 });
127
161
  } catch {
128
162
  answer = { state: "unavailable" };
129
163
  }
130
164
  const waited = Math.max(0, now() - started);
131
- switch (answer?.state) {
165
+ if (escalated) {
166
+ const state = answer?.state;
167
+ if (state === "refused") {
168
+ // Not an owner outcome: the tool goes ahead on its own rules, so the agent's page
169
+ // gets the record those rules give (only an "ask"), never "owner unavailable".
170
+ needsRefresh = true;
171
+ holdRecord("through");
172
+ if (original.effect === "ask") {
173
+ record(input, "ask", original.ruleIndex, 0);
174
+ return verdict("ask", `PassControl: ${guardText} The gateway now sees no taint. The tool rules still ask you to confirm this (rule ${original.ruleIndex + 1}: ${short(original.subject)}). ${rulesLive}`);
175
+ }
176
+ return { systemMessage: `PassControl: ${guardText} The gateway now sees no taint, so this goes ahead.` };
177
+ }
178
+ const outcome = ["approved", "denied", "timeout"].includes(state) ? state : "unavailable";
179
+ holdRecord(outcome);
180
+ record(input, `owner_${outcome}`, null, waited);
181
+ if (outcome === "approved") return { systemMessage: `PassControl: ${guardText} The agent's owner approved it.` };
182
+ const ending = outcome === "denied" ? "The agent's owner said no." : outcome === "timeout" ? `The agent's owner did not answer within ${waitS} s, so this was not run.` : "The owner could not be asked, so this was not run.";
183
+ return verdict("deny", `PassControl: ${guardText} ${ending}`);
184
+ }
185
+ function ruleAnswer() {
186
+ switch (answer?.state) {
132
187
  case "approved":
133
188
  record(input, "owner_approved", hit.ruleIndex, waited);
134
189
  return {};
@@ -150,7 +205,9 @@ export function createToolGate({ askOwner, onDecision = () => {}, now = () => Da
150
205
  default:
151
206
  record(input, "owner_unavailable", hit.ruleIndex, waited);
152
207
  return verdict("deny", `PassControl: this needs the agent's owner to say yes (${rule}), and they could not be reached, so it was not run.`);
208
+ }
153
209
  }
210
+ return withWarning(ruleAnswer());
154
211
  }
155
212
 
156
213
  return { decide };
@@ -21,6 +21,8 @@
21
21
  // cannot keep up is dropped rather than buffered for, and nothing on the proxy
22
22
  // path waits on a subscriber.
23
23
 
24
+ import { INJECTION_FAMILIES } from "./injection-scan.mjs";
25
+
24
26
  export const WATCH_PATH = "/_passcontrol/watch";
25
27
  /** Paths under this prefix are the sidecar's own and are never forwarded. */
26
28
  export const LOCAL_PREFIX = "/_passcontrol/";
@@ -270,6 +272,41 @@ export function createWatchFeed({ runId, capacity = 200, maxSubscribers = 8, ena
270
272
  }
271
273
  }
272
274
 
275
+ /** A local scan saw a tell; this says nothing about server recording. */
276
+ function injection(event) {
277
+ try {
278
+ const families = INJECTION_FAMILIES.filter((f) => Array.isArray(event.families) && event.families.includes(f));
279
+ if (!families.length) return;
280
+ const record = {
281
+ type: "injection_finding", seq: ++seq,
282
+ at: Number.isFinite(event.at) ? event.at : now(), source: "tool_result",
283
+ tool: held(/^[A-Za-z0-9_.-]{1,128}$/, event.tool), families,
284
+ };
285
+ remember(record);
286
+ broadcast(record);
287
+ } catch {
288
+ // Like calls, findings are best-effort metadata only.
289
+ }
290
+ }
291
+
292
+ /**
293
+ * One tool the injection guard held (Phase 2): tool name and outcome only, never
294
+ * its input. Not a call, so the board does not count it. Never throws.
295
+ */
296
+ function toolHold(event) {
297
+ try {
298
+ if (!["approved", "denied", "timeout", "unavailable", "through"].includes(event?.outcome)) return;
299
+ const record = {
300
+ type: "tool_hold", seq: ++seq,
301
+ at: Number.isFinite(event.at) ? event.at : now(),
302
+ tool: held(/^[A-Za-z0-9_.-]{1,128}$/, event.tool),
303
+ outcome: event.outcome,
304
+ };
305
+ remember(record);
306
+ broadcast(record);
307
+ } catch {}
308
+ }
309
+
273
310
  /**
274
311
  * The latest usage window, already held to its shape by the caller. Replaces the
275
312
  * last one and tells every board. Never throws.
@@ -335,6 +372,8 @@ export function createWatchFeed({ runId, capacity = 200, maxSubscribers = 8, ena
335
372
  begin,
336
373
  record,
337
374
  report,
375
+ injection,
376
+ toolHold,
338
377
  setWindow,
339
378
  window: () => usageWindow,
340
379
  serve,
package/cli/watch.mjs CHANGED
@@ -16,6 +16,7 @@
16
16
  // fields are held to the feed's own patterns on arrival, and every cell is stripped
17
17
  // of control characters again before it is drawn.
18
18
  import http from "node:http";
19
+ import { INJECTION_FAMILIES } from "./injection-scan.mjs";
19
20
  import { formatUsd, limitReached, panelRows, paused } from "./budget-format.mjs";
20
21
  import { WATCH_PATH } from "./watch-feed.mjs";
21
22
  import { heldUsageWindow, resetTime, usageWindowText } from "./usage-window.mjs";
@@ -141,6 +142,29 @@ export function applyEvent(state, event) {
141
142
  state.feed = { state: "live" };
142
143
  return state;
143
144
  }
145
+ if (event.type === "tool_hold") {
146
+ if (!Number.isInteger(event.seq) || event.seq < 1 || !["approved", "denied", "timeout", "unavailable", "through"].includes(event.outcome)) return state;
147
+ const row = { type: "tool_hold", seq: event.seq, at: count(event.at), tool: held(/^[A-Za-z0-9_.-]{1,128}$/, event.tool), outcome: event.outcome };
148
+ const existing = state.rows.findIndex((r) => r.seq === row.seq);
149
+ if (existing === -1) state.rows.push(row);
150
+ else state.rows[existing] = row;
151
+ if (state.rows.length > MAX_ROWS) state.rows.splice(0, state.rows.length - MAX_ROWS);
152
+ return state;
153
+ }
154
+ if (event.type === "injection_finding") {
155
+ if (!Number.isInteger(event.seq) || event.seq < 1 || event.source !== "tool_result") return state;
156
+ const families = INJECTION_FAMILIES.filter((f) => Array.isArray(event.families) && event.families.includes(f));
157
+ if (!families.length) return state;
158
+ const row = {
159
+ type: "injection_finding", seq: event.seq, at: count(event.at), source: "tool_result",
160
+ tool: held(/^[A-Za-z0-9_.-]{1,128}$/, event.tool), families,
161
+ };
162
+ const existing = state.rows.findIndex((r) => r.seq === row.seq);
163
+ if (existing === -1) state.rows.push(row);
164
+ else state.rows[existing] = row;
165
+ if (state.rows.length > MAX_ROWS) state.rows.splice(0, state.rows.length - MAX_ROWS);
166
+ return state;
167
+ }
144
168
  if (event.type === "call") {
145
169
  if (!Number.isInteger(event.seq) || event.seq < 1) return state;
146
170
  const row = {
@@ -275,6 +299,17 @@ const BAR_STYLE = { boarded: "green", denied: "red", error: "yellow" };
275
299
 
276
300
  /** One board row, `width` wide at most. */
277
301
  function rowLine(row, cols, { run, now, formatTime, color }) {
302
+ if (row.type === "tool_hold") {
303
+ const tool = held(/^[A-Za-z0-9_.-]{1,128}$/, row.tool) ?? "—";
304
+ return paint(color, "yellow", clean(`${fit(row.at !== null ? formatTime(row.at) : "", cols.time)} HELD · injection guard · ${tool} · ${row.outcome}`));
305
+ }
306
+ if (row.type === "injection_finding") {
307
+ const families = INJECTION_FAMILIES.filter((f) => Array.isArray(row.families) && row.families.includes(f));
308
+ const tool = held(/^[A-Za-z0-9_.-]{1,128}$/, row.tool) ?? "—";
309
+ // The local scan saw it; whether the gateway recorded it is the owner's policy, unknown here.
310
+ const text = `${fit(row.at ? formatTime(row.at) : "", cols.time)} INJECTION? · tool_result · ${tool} · ${families.join("+")}`;
311
+ return paint(color, "yellow", clean(text));
312
+ }
278
313
  const cells = [fit(row.at !== null ? formatTime(row.at) : "", cols.time)];
279
314
  if (cols.withSession) cells.push(fit(sessionText(row, run), cols.session));
280
315
  cells.push(agentText(row, cols.agent));
@@ -396,9 +431,10 @@ export function renderBoard(state, { width, height, port, now = Date.now(), form
396
431
  const cols = columns(w);
397
432
  const rows = state.rows;
398
433
  const tally = { boarded: 0, denied: 0, error: 0, seen: 0 };
399
- for (const r of rows) tally[r.outcome] += 1;
400
- const counts = rows.length
401
- ? `${rows.length} call${rows.length === 1 ? "" : "s"}: ${tally.seen ? `${tally.seen} seen, ` : ""}${tally.boarded} boarded, ${tally.denied} denied${tally.error ? `, ${tally.error} error` : ""}`
434
+ const calls = rows.filter((r) => r.type !== "injection_finding" && r.type !== "tool_hold");
435
+ for (const r of calls) tally[r.outcome] += 1;
436
+ const counts = calls.length
437
+ ? `${calls.length} call${calls.length === 1 ? "" : "s"}: ${tally.seen ? `${tally.seen} seen, ` : ""}${tally.boarded} boarded, ${tally.denied} denied${tally.error ? `, ${tally.error} error` : ""}`
402
438
  : "no calls yet";
403
439
  const lines = [
404
440
  `${paint(color, "bold", "PassControl watch")} · sidecar :${port} · ${feedText(state.feed, port)} · ${counts}`,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "passcontrol",
3
- "version": "1.6.0",
3
+ "version": "1.7.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
@@ -120,6 +120,19 @@ export interface ReceiptClaims {
120
120
  * the earlier provider refused before doing any work.
121
121
  */
122
122
  why?: string;
123
+ /**
124
+ * Present only when the issuing gateway's injection guard flagged tool output in
125
+ * this call's request: the detector, how many blocks, and their kinds (for example
126
+ * `instruction_override`). Kinds only, never the text. A tell is a hint, not proof.
127
+ *
128
+ * Optional, and `ver` stays where it was: a verifier that predates it ignores it.
129
+ * Treat `f` as open-ended strings: a newer detector may add kinds.
130
+ */
131
+ inj?: {
132
+ d: string;
133
+ n: number;
134
+ f: string[];
135
+ };
123
136
  ver: number;
124
137
  [claim: string]: unknown;
125
138
  }