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/bin/passcontrol.mjs +20 -8
- package/cli/claude-code.mjs +41 -12
- package/cli/client-events-upload.mjs +22 -0
- package/cli/codex-hooks.mjs +44 -8
- package/cli/injection-hold.d.mts +7 -0
- package/cli/injection-hold.mjs +30 -0
- package/cli/injection-scan.d.mts +11 -0
- package/cli/injection-scan.mjs +405 -0
- package/cli/injection-sidecar.mjs +78 -0
- package/cli/sidecar.mjs +73 -2
- package/cli/subscription-gate.mjs +18 -1
- package/cli/tool-gate.mjs +70 -13
- package/cli/watch-feed.mjs +39 -0
- package/cli/watch.mjs +39 -3
- package/package.json +1 -1
- package/sdk/verify.d.ts +13 -0
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
|
|
103
|
-
|
|
104
|
-
const
|
|
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
|
|
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
|
-
|
|
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 };
|
package/cli/watch-feed.mjs
CHANGED
|
@@ -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
|
-
|
|
400
|
-
const
|
|
401
|
-
|
|
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
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
|
}
|