passcontrol 1.6.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.
- package/bin/passcontrol.mjs +20 -8
- package/cli/claude-code.mjs +41 -12
- package/cli/client-events-upload.mjs +42 -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 +150 -0
- package/cli/sidecar.mjs +125 -12
- package/cli/subscription-gate.mjs +18 -1
- package/cli/tool-gate.mjs +71 -13
- package/cli/watch-feed.mjs +39 -0
- package/cli/watch.mjs +39 -3
- package/package.json +2 -2
- package/sdk/verify.d.ts +13 -0
package/bin/passcontrol.mjs
CHANGED
|
@@ -92,6 +92,7 @@ import { dashboardOriginForOffset, portHolders, stackPortConflictMessage } from
|
|
|
92
92
|
import { startSidecar } from "../cli/sidecar.mjs";
|
|
93
93
|
import { listProfiles, profilePath, readProfile, TOOL_PROFILE_PORTS, writeProfile } from "../cli/profiles.mjs";
|
|
94
94
|
import {
|
|
95
|
+
apiToolHooks,
|
|
95
96
|
claudeCodeEnv,
|
|
96
97
|
claudeCodeSettingsPath,
|
|
97
98
|
removeClaudeCodeSettings,
|
|
@@ -282,6 +283,8 @@ ${heading("Integrate")}
|
|
|
282
283
|
${cmd} env [integration] print settings without writing anything
|
|
283
284
|
${cmd} configure <integration> [--write] [--force] [--dedicated]
|
|
284
285
|
preview or write integration config
|
|
286
|
+
${cmd} configure claude-code --write
|
|
287
|
+
route model calls; tools ask the sidecar first
|
|
285
288
|
${cmd} configure claude-code --subscription [--write|--remove]
|
|
286
289
|
a Pro/Max login: stops, calls, usage window
|
|
287
290
|
${cmd} configure codex --subscription [--write|--remove]
|
|
@@ -2784,7 +2787,7 @@ function aiderConfig(opts = {}) {
|
|
|
2784
2787
|
/**
|
|
2785
2788
|
* Claude Code's own model calls, through the sidecar (cli/claude-code.mjs). The
|
|
2786
2789
|
* project's settings by default; `--global` for every session; `--remove` takes
|
|
2787
|
-
* PassControl's
|
|
2790
|
+
* PassControl's env keys and tool hook back out. The MCP chat tool stays a separate command
|
|
2788
2791
|
* Claude Code owns.
|
|
2789
2792
|
*/
|
|
2790
2793
|
function configureClaudeCode(opts = {}) {
|
|
@@ -2799,11 +2802,11 @@ function configureClaudeCode(opts = {}) {
|
|
|
2799
2802
|
}
|
|
2800
2803
|
const { baseUrl, port } = sidecarBaseUrl({ ...opts, provider: "anthropic" });
|
|
2801
2804
|
const note = Boolean(opts.agentNote);
|
|
2802
|
-
const preview = { env: claudeCodeEnv(baseUrl) };
|
|
2803
|
-
if (note) preview.hooks = { UserPromptSubmit: [{ hooks: [{ type: "http", url: `http://127.0.0.1:${port}/_passcontrol/hook?note=only`, timeout: 5 }] }] };
|
|
2805
|
+
const preview = { env: claudeCodeEnv(baseUrl), hooks: apiToolHooks(port) };
|
|
2806
|
+
if (note) preview.hooks = { ...preview.hooks, UserPromptSubmit: [{ hooks: [{ type: "http", url: `http://127.0.0.1:${port}/_passcontrol/hook?note=only`, timeout: 5 }] }] };
|
|
2804
2807
|
console.log(`Preview: ${target}\n\n${JSON.stringify(preview, null, 2)}`);
|
|
2805
2808
|
if (!opts.write) {
|
|
2806
|
-
step(`Dry run only. Re-run with \`--write\` to merge these
|
|
2809
|
+
step(`Dry run only. Re-run with \`--write\` to merge these env keys and the tool hook${scope === "project" ? " (or --write --global for every session)" : ""}.`);
|
|
2807
2810
|
} else {
|
|
2808
2811
|
const result = writeClaudeCodeSettings({
|
|
2809
2812
|
target,
|
|
@@ -2811,12 +2814,14 @@ function configureClaudeCode(opts = {}) {
|
|
|
2811
2814
|
force: Boolean(opts.force),
|
|
2812
2815
|
statusLineCommand: opts.statusline ? statusLineSettingsCommand(port) : null,
|
|
2813
2816
|
noteHookPort: note ? port : null,
|
|
2817
|
+
toolHookPort: port,
|
|
2814
2818
|
});
|
|
2815
2819
|
if (!result.changed) ok(`${target} already routes Claude Code through PassControl`);
|
|
2816
2820
|
else {
|
|
2817
2821
|
if (result.backupPath) step(`backed up ${result.backupPath}`);
|
|
2818
2822
|
ok(`wrote ${target}`);
|
|
2819
2823
|
}
|
|
2824
|
+
ok("Claude Code’s tools now ask the sidecar first for the agent’s tool rules and the injection guard’s hold.");
|
|
2820
2825
|
if (result.statusLine?.existing) {
|
|
2821
2826
|
warn(`${target} already has a status line (${result.statusLine.existing}); it was left as it is. To show the budget there, add \`${statusLineSettingsCommand(port)}\` to it yourself.`);
|
|
2822
2827
|
} else if (result.statusLine?.changed) ok("added the agent's budget to Claude Code's status line");
|
|
@@ -2982,7 +2987,7 @@ function profileCommand(rest, opts) {
|
|
|
2982
2987
|
/**
|
|
2983
2988
|
* Subscription mode for Codex (cli/codex-hooks.mjs): a ChatGPT login keeps talking
|
|
2984
2989
|
* to OpenAI directly; PassControl's stops and tool rules reach the session through
|
|
2985
|
-
*
|
|
2990
|
+
* three hooks in $CODEX_HOME/hooks.json, next to anyone else's.
|
|
2986
2991
|
*/
|
|
2987
2992
|
function configureCodexSubscription(opts = {}) {
|
|
2988
2993
|
const target = codexHooksPath();
|
|
@@ -2998,14 +3003,14 @@ function configureCodexSubscription(opts = {}) {
|
|
|
2998
3003
|
const command = codexHookCommand({ port, entry: fs.realpathSync(CLI_ENTRY) });
|
|
2999
3004
|
console.log(`Preview: added to ${target} (anything already there is kept)\n\n${JSON.stringify(codexHookEntries(command), null, 2)}`);
|
|
3000
3005
|
if (!opts.write) {
|
|
3001
|
-
step("Dry run only. Re-run with `--write` to add these
|
|
3006
|
+
step("Dry run only. Re-run with `--write` to add these three hooks.");
|
|
3002
3007
|
} else {
|
|
3003
3008
|
const result = writeCodexHooks({ target, command });
|
|
3004
3009
|
if (!result.changed) ok(`${target} already has PassControl's hooks`);
|
|
3005
3010
|
else {
|
|
3006
3011
|
if (result.backupPath) step(`backed up ${result.backupPath}`);
|
|
3007
3012
|
ok(`wrote ${target}`);
|
|
3008
|
-
warn("Not on yet: Codex runs a hook only after you trust it. Open Codex, type /hooks, and trust PassControl's
|
|
3013
|
+
warn("Not on yet: Codex runs a hook only after you trust it. Open Codex, type /hooks, and trust PassControl's three hooks (any you trusted before stay trusted). Until then they are skipped without a word.");
|
|
3009
3014
|
}
|
|
3010
3015
|
const probe = probeCodexHookCommand(command);
|
|
3011
3016
|
if (probe.ok) ok("the hook command runs on its own, without your shell's PATH");
|
|
@@ -3013,6 +3018,7 @@ function configureCodexSubscription(opts = {}) {
|
|
|
3013
3018
|
}
|
|
3014
3019
|
step(`Start the sidecar before Codex: ${cliCommand(port === 8788 ? "sidecar" : `sidecar --port ${port}`)}`);
|
|
3015
3020
|
step("Your ChatGPT login stays between Codex and OpenAI. PassControl never sees it or sits in the path.");
|
|
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.");
|
|
3016
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.");
|
|
3017
3023
|
step("What it cannot do, plainly:");
|
|
3018
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).");
|
|
@@ -3475,14 +3481,20 @@ async function verifyCommand(rest, opts) {
|
|
|
3475
3481
|
// Lineage is DECLARED by the client: any local process can send those
|
|
3476
3482
|
// headers. Say so on the same line, so nobody reads it as passport-proven.
|
|
3477
3483
|
// Printable ASCII only: a signed value is still not a terminal's to obey.
|
|
3484
|
+
const shown = (v) => String(v).replace(/[^\x20-\x7e]/g, "?").slice(0, 128);
|
|
3478
3485
|
if (c.ctx?.ses) {
|
|
3479
|
-
const shown = (v) => String(v).replace(/[^\x20-\x7e]/g, "?").slice(0, 128);
|
|
3480
3486
|
const who = c.ctx.agt
|
|
3481
3487
|
? `sub-agent ${shown(c.ctx.agt)}${c.ctx.par ? `, spawned by ${shown(c.ctx.par)}` : ""}`
|
|
3482
3488
|
: "main agent";
|
|
3483
3489
|
step(`Session: ${shown(c.ctx.ses)} · ${who}`);
|
|
3484
3490
|
step(` declared by the client (${shown(c.ctx.cli ?? "unknown")}), not verified`);
|
|
3485
3491
|
}
|
|
3492
|
+
const inj = c.inj;
|
|
3493
|
+
if (typeof inj === "object" && inj !== null && !Array.isArray(inj) &&
|
|
3494
|
+
typeof inj.d === "string" && inj.d && Number.isSafeInteger(inj.n) && inj.n >= 1 && Array.isArray(inj.f)) {
|
|
3495
|
+
step(`Injection: ${inj.n} block(s) of tool output carried injection tells (${shown(inj.d)})`);
|
|
3496
|
+
step(` kinds: ${inj.f.slice(0, 16).map(shown).join(", ")}`);
|
|
3497
|
+
}
|
|
3486
3498
|
}
|
|
3487
3499
|
if (c.own) {
|
|
3488
3500
|
step(
|
package/cli/claude-code.mjs
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
// Bearer token with no "use this API key?" prompt. The sidecar strips it and the
|
|
7
7
|
// gateway injects the real key, so Claude Code never holds one.
|
|
8
8
|
//
|
|
9
|
-
// The settings file belongs to the user.
|
|
9
|
+
// The settings file belongs to the user. The env keys and tool hook, and with
|
|
10
10
|
// --statusline a `statusLine` running `passcontrol statusline`, are written or
|
|
11
11
|
// removed, in one save; the previous file is backed up, a file that is not a JSON
|
|
12
12
|
// object is refused rather than overwritten, a different gateway already
|
|
@@ -96,7 +96,7 @@ function withNoteOnlyHook(hooks, port) {
|
|
|
96
96
|
* The env keys, and with `statusLineCommand` the status line too, in ONE save:
|
|
97
97
|
* two saves would back up the first save's output and lose the user's original.
|
|
98
98
|
*/
|
|
99
|
-
export function writeClaudeCodeSettings({ target, baseUrl, force = false, statusLineCommand = null, noteHookPort = null }) {
|
|
99
|
+
export function writeClaudeCodeSettings({ target, baseUrl, force = false, statusLineCommand = null, noteHookPort = null, toolHookPort = null }) {
|
|
100
100
|
const { exists, value } = readSettings(target);
|
|
101
101
|
const env = typeof value.env === "object" && value.env !== null && !Array.isArray(value.env) ? value.env : {};
|
|
102
102
|
const rawKeyFound = typeof env.ANTHROPIC_API_KEY === "string" && env.ANTHROPIC_API_KEY.length > 0;
|
|
@@ -114,7 +114,8 @@ export function writeClaudeCodeSettings({ target, baseUrl, force = false, status
|
|
|
114
114
|
next = line.value;
|
|
115
115
|
statusLine = line.existing !== undefined ? { changed: false, existing: line.existing } : { changed: line.changed };
|
|
116
116
|
}
|
|
117
|
-
|
|
117
|
+
// configure passes the sidecar's port; URL.port is "" for :80, which would write a hook to nowhere.
|
|
118
|
+
const hooks = withApiTools(withNoteOnlyHook(value.hooks, noteHookPort), toolHookPort ?? (new URL(baseUrl).port || 80));
|
|
118
119
|
const hooksChanged = !same(hooks ?? null, value.hooks ?? null);
|
|
119
120
|
if (hooksChanged) {
|
|
120
121
|
next = { ...next };
|
|
@@ -126,7 +127,7 @@ export function writeClaudeCodeSettings({ target, baseUrl, force = false, status
|
|
|
126
127
|
return { changed, backupPath, rawKeyFound, ...(statusLine ? { statusLine } : {}) };
|
|
127
128
|
}
|
|
128
129
|
|
|
129
|
-
/** PassControl's
|
|
130
|
+
/** PassControl's env keys, tool hook, optional note and status line, in one save. */
|
|
130
131
|
export function removeClaudeCodeSettings({ target }) {
|
|
131
132
|
if (!fs.existsSync(target)) return { changed: false };
|
|
132
133
|
const { value } = readSettings(target);
|
|
@@ -145,7 +146,7 @@ export function removeClaudeCodeSettings({ target }) {
|
|
|
145
146
|
next = rest;
|
|
146
147
|
}
|
|
147
148
|
if (isObject(next.hooks)) {
|
|
148
|
-
const hooks = withNoteOnlyHook(next.hooks, null);
|
|
149
|
+
const hooks = withApiTools(withNoteOnlyHook(next.hooks, null), null);
|
|
149
150
|
if (!same(hooks, next.hooks)) {
|
|
150
151
|
next = { ...next };
|
|
151
152
|
if (Object.keys(hooks).length) next.hooks = hooks;
|
|
@@ -218,11 +219,10 @@ export function removeClaudeCodeStatusLine({ target }) {
|
|
|
218
219
|
|
|
219
220
|
const LOOPBACK_BASE = "http://127.0.0.1:";
|
|
220
221
|
const OUR_LOGS_ENDPOINT = /^http:\/\/127\.0\.0\.1:\d{1,5}\/_passcontrol\/otlp\/v1\/logs$/;
|
|
221
|
-
const OUR_HOOK_URL = /^http:\/\/127\.0\.0\.1:\d{1,5}\/_passcontrol\/hook(\?(t=\d{1,4}
|
|
222
|
+
const OUR_HOOK_URL = /^http:\/\/127\.0\.0\.1:\d{1,5}\/_passcontrol\/hook(\?(t=\d{1,4}(&mode=api)?|note=1))?$/;
|
|
222
223
|
// API mode's own prompt hook, for the agent's note only (1.6.0): never a stop.
|
|
223
224
|
const OUR_NOTE_ONLY_URL = /^http:\/\/127\.0\.0\.1:\d{1,5}\/_passcontrol\/hook\?note=only$/;
|
|
224
225
|
const OUR_SIDECAR_URL = /^http:\/\/127\.0\.0\.1:\d{1,5}$/;
|
|
225
|
-
const GATED_EVENTS = ["UserPromptSubmit", "PreToolUse", "PostToolBatch"];
|
|
226
226
|
// The log-export settings this mode owns, with the value it writes.
|
|
227
227
|
const LOGS_ENV = {
|
|
228
228
|
OTEL_LOGS_EXPORTER: "otlp",
|
|
@@ -250,8 +250,38 @@ function gateHook(port, note = false) {
|
|
|
250
250
|
// told, and a Phase 1 hook (no `t`, 5 s) refuses a tool that would need the owner
|
|
251
251
|
// instead of letting it through on the timeout.
|
|
252
252
|
export const TOOL_HOOK_TIMEOUT_S = 600;
|
|
253
|
-
function toolHook(port) {
|
|
254
|
-
return { type: "http", url: `${LOOPBACK_BASE}${port}/_passcontrol/hook?t=${TOOL_HOOK_TIMEOUT_S}`, timeout: TOOL_HOOK_TIMEOUT_S };
|
|
253
|
+
function toolHook(port, api = false) {
|
|
254
|
+
return { type: "http", url: `${LOOPBACK_BASE}${port}/_passcontrol/hook?t=${TOOL_HOOK_TIMEOUT_S}${api ? "&mode=api" : ""}`, timeout: TOOL_HOOK_TIMEOUT_S };
|
|
255
|
+
}
|
|
256
|
+
|
|
257
|
+
/** API mode always asks the sidecar before a tool. */
|
|
258
|
+
export function apiToolHooks(port) {
|
|
259
|
+
return { PreToolUse: [{ matcher: "*", hooks: [toolHook(port, true)] }] };
|
|
260
|
+
}
|
|
261
|
+
|
|
262
|
+
const OUR_API_TOOL_URL = /^http:\/\/127\.0\.0\.1:\d{1,5}\/_passcontrol\/hook\?t=\d{1,4}&mode=api$/;
|
|
263
|
+
|
|
264
|
+
// Writing: the same ownership matcher and merge as subscription mode, scoped to tools, so
|
|
265
|
+
// an API setup replaces subscription mode's tool hook instead of adding a second one.
|
|
266
|
+
// Removing (port null): only API mode's own hook. Subscription mode's stays, or a Pro/Max
|
|
267
|
+
// setup would keep its prompt and batch hooks and lose its tool rules.
|
|
268
|
+
function withApiTools(hooks, port) {
|
|
269
|
+
const base = isObject(hooks) ? hooks : {};
|
|
270
|
+
const tools = Object.hasOwn(base, "PreToolUse") ? { PreToolUse: base.PreToolUse } : {};
|
|
271
|
+
const next = { ...base };
|
|
272
|
+
delete next.PreToolUse;
|
|
273
|
+
if (port !== null) return { ...next, ...withOurHooks(tools, port, false, apiToolHooks(port)) };
|
|
274
|
+
if (!Array.isArray(tools.PreToolUse)) return isObject(hooks) ? { ...next, ...tools } : hooks;
|
|
275
|
+
const isApiTool = (h) => isObject(h) && h.type === "http" && typeof h.url === "string" && OUR_API_TOOL_URL.test(h.url);
|
|
276
|
+
const kept = [];
|
|
277
|
+
for (const group of tools.PreToolUse) {
|
|
278
|
+
if (!isObject(group) || !Array.isArray(group.hooks) || !group.hooks.some(isApiTool)) kept.push(group);
|
|
279
|
+
else {
|
|
280
|
+
const rest = group.hooks.filter((h) => !isApiTool(h));
|
|
281
|
+
if (rest.length) kept.push({ ...group, hooks: rest });
|
|
282
|
+
}
|
|
283
|
+
}
|
|
284
|
+
return kept.length ? { ...next, PreToolUse: kept } : next;
|
|
255
285
|
}
|
|
256
286
|
|
|
257
287
|
/** `note`: the agent's opt-in note rides on the prompt hook (`--agent-note`). */
|
|
@@ -292,11 +322,10 @@ function withoutOurHooks(hooks) {
|
|
|
292
322
|
}
|
|
293
323
|
|
|
294
324
|
/** `hooks` with exactly this port's gate hooks, leaving them where they are when already right. */
|
|
295
|
-
function withOurHooks(hooks, port, note = false) {
|
|
296
|
-
const ours = subscriptionHooks(port, { note });
|
|
325
|
+
function withOurHooks(hooks, port, note = false, ours = subscriptionHooks(port, { note })) {
|
|
297
326
|
const base = isObject(hooks) ? hooks : {};
|
|
298
327
|
const next = withoutOurHooks(base);
|
|
299
|
-
for (const event of
|
|
328
|
+
for (const event of Object.keys(ours)) {
|
|
300
329
|
const current = Array.isArray(base[event]) ? base[event] : [];
|
|
301
330
|
const already = current.filter((g) => isObject(g) && Array.isArray(g.hooks) && g.hooks.some(isOurHook));
|
|
302
331
|
if (already.length === 1 && same(already[0], ours[event][0])) next[event] = current;
|
|
@@ -40,6 +40,8 @@ const newKey = () => `evt_${randomBytes(16).toString("base64url")}`;
|
|
|
40
40
|
/** One event from readClaudeCodeEvents, as the gateway takes it. Absent fields are left out. */
|
|
41
41
|
function toWire(event, key) {
|
|
42
42
|
if (event.kind === "tool_decision") return toolDecisionWire(event, key);
|
|
43
|
+
if (event.kind === "injection_finding") return injectionFindingWire(event, key);
|
|
44
|
+
if (event.kind === "injection_incomplete") return injectionIncompleteWire(event, key);
|
|
43
45
|
const wire = {
|
|
44
46
|
key,
|
|
45
47
|
kind: event.kind === "api_error" ? "model_error" : "model_call",
|
|
@@ -75,6 +77,46 @@ function toolDecisionWire(event, key) {
|
|
|
75
77
|
return wire;
|
|
76
78
|
}
|
|
77
79
|
|
|
80
|
+
// What the sidecar's scan of a tool's output found (cli/injection-sidecar.mjs): the
|
|
81
|
+
// gateway's fixed fields only (plans/injection-guard.md §2b), so nothing a caller adds,
|
|
82
|
+
// least of all text, is ever sent.
|
|
83
|
+
function injectionFindingWire(event, key) {
|
|
84
|
+
const wire = {
|
|
85
|
+
key,
|
|
86
|
+
kind: "injection_finding",
|
|
87
|
+
at: event.at,
|
|
88
|
+
source: event.source,
|
|
89
|
+
path: event.path,
|
|
90
|
+
tool: event.tool,
|
|
91
|
+
families: event.families,
|
|
92
|
+
severity: event.severity,
|
|
93
|
+
detector: event.detector,
|
|
94
|
+
normalization_version: event.normalization_version,
|
|
95
|
+
block_sha256: event.block_sha256,
|
|
96
|
+
};
|
|
97
|
+
for (const name of Object.keys(wire)) if (wire[name] === null || wire[name] === undefined) delete wire[name];
|
|
98
|
+
return wire;
|
|
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
|
+
|
|
78
120
|
/**
|
|
79
121
|
* @param {{
|
|
80
122
|
* send: (events: object[]) => Promise<{ status: number, error?: string, retryAfterS?: number }>,
|
package/cli/codex-hooks.mjs
CHANGED
|
@@ -3,13 +3,14 @@
|
|
|
3
3
|
// A Codex session signed in with a ChatGPT plan talks to OpenAI directly, so the
|
|
4
4
|
// gateway cannot refuse its calls, as with a Claude Pro/Max login
|
|
5
5
|
// (cli/subscription-gate.mjs). The stops and tool rules still reach it through
|
|
6
|
-
// Codex's hooks: `passcontrol configure codex --subscription` adds
|
|
6
|
+
// Codex's hooks: `passcontrol configure codex --subscription` adds three to
|
|
7
7
|
// `$CODEX_HOME/hooks.json`, each running `passcontrol codex-hook`, which hands
|
|
8
8
|
// Codex's input to the sidecar's hook endpoint (the one Claude Code calls) and
|
|
9
9
|
// answers in Codex's terms:
|
|
10
10
|
//
|
|
11
11
|
// UserPromptSubmit a stopped agent's prompt is blocked and the turn ends
|
|
12
12
|
// PreToolUse a stopped agent's tools, and the tool rules' denials, are refused
|
|
13
|
+
// PostToolUse tool output is scanned for injection tells; always neutral
|
|
13
14
|
//
|
|
14
15
|
// Codex has command hooks only (no http hook), hence the relay. Three differences
|
|
15
16
|
// from Claude Code are handled here, not in the sidecar:
|
|
@@ -46,7 +47,8 @@ import { GATE_HOOK_TIMEOUT_S, HOOK_PATH } from "./subscription-gate.mjs";
|
|
|
46
47
|
export const CODEX_TOOL_HOOK_TIMEOUT_S = 600;
|
|
47
48
|
const PROMPT_RELAY_MS = GATE_HOOK_TIMEOUT_S * 1000 - 500;
|
|
48
49
|
const TOOL_RELAY_MS = (CODEX_TOOL_HOOK_TIMEOUT_S - 10) * 1000;
|
|
49
|
-
const
|
|
50
|
+
const POST_TOOL_RELAY_MS = 1500;
|
|
51
|
+
const EVENTS = ["UserPromptSubmit", "PreToolUse", "PostToolUse"];
|
|
50
52
|
const BACKUP_SUFFIX = ".passcontrol-backup";
|
|
51
53
|
|
|
52
54
|
const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
|
|
@@ -62,7 +64,7 @@ export function isPassControlCodexHook(hook) {
|
|
|
62
64
|
}
|
|
63
65
|
|
|
64
66
|
/**
|
|
65
|
-
* The command
|
|
67
|
+
* The command all hooks run: node and the CLI by absolute path, so PATH never
|
|
66
68
|
* decides whether it runs. Refuses a path a shell would read differently.
|
|
67
69
|
*/
|
|
68
70
|
export function codexHookCommand({ port, node = process.execPath, entry }) {
|
|
@@ -91,12 +93,13 @@ export function probeCodexHookCommand(command) {
|
|
|
91
93
|
return { ok: true };
|
|
92
94
|
}
|
|
93
95
|
|
|
94
|
-
/** The
|
|
96
|
+
/** The three entries PassControl adds, as a hooks file of their own. */
|
|
95
97
|
export function codexHookEntries(command) {
|
|
96
98
|
return {
|
|
97
99
|
hooks: {
|
|
98
100
|
UserPromptSubmit: [{ hooks: [{ type: "command", command, timeout: GATE_HOOK_TIMEOUT_S }] }],
|
|
99
101
|
PreToolUse: [{ matcher: ".*", hooks: [{ type: "command", command, timeout: CODEX_TOOL_HOOK_TIMEOUT_S }] }],
|
|
102
|
+
PostToolUse: [{ matcher: ".*", hooks: [{ type: "command", command, timeout: GATE_HOOK_TIMEOUT_S }] }],
|
|
100
103
|
},
|
|
101
104
|
};
|
|
102
105
|
}
|
|
@@ -141,12 +144,19 @@ function save(target, value) {
|
|
|
141
144
|
fs.renameSync(temp, target);
|
|
142
145
|
}
|
|
143
146
|
|
|
144
|
-
/** Add PassControl's
|
|
147
|
+
/** Add PassControl's three hooks, replacing any earlier ones of its own and nobody else's. */
|
|
145
148
|
export function writeCodexHooks({ target, command }) {
|
|
146
149
|
const { value, exists } = readHooksFile(target);
|
|
147
150
|
const hooks = withoutOurs(value.hooks ?? {});
|
|
148
151
|
for (const [event, groups] of Object.entries(codexHookEntries(command).hooks)) {
|
|
149
|
-
|
|
152
|
+
// Codex keys trust by place (`<file>:<event>:<group>:<hook>`), so an entry of ours
|
|
153
|
+
// goes back where it stood: appended, it would swap with a hook added after it and
|
|
154
|
+
// both would quietly lose their trust. The groups before it held none of ours, so
|
|
155
|
+
// they are still the first `at`.
|
|
156
|
+
const before = Array.isArray(value.hooks?.[event]) ? value.hooks[event] : [];
|
|
157
|
+
const at = before.findIndex((g) => isObject(g) && Array.isArray(g.hooks) && g.hooks.some(isPassControlCodexHook));
|
|
158
|
+
const rest = Array.isArray(hooks[event]) ? hooks[event] : [];
|
|
159
|
+
hooks[event] = at < 0 ? [...rest, ...groups] : [...rest.slice(0, at), ...groups, ...rest.slice(at)];
|
|
150
160
|
}
|
|
151
161
|
const next = { ...value, hooks };
|
|
152
162
|
if (JSON.stringify(next) === JSON.stringify(value)) return { changed: false, backupPath: null };
|
|
@@ -180,6 +190,7 @@ const ASK_IN_CODEX =
|
|
|
180
190
|
* and a failed hook lets the tool run.
|
|
181
191
|
*/
|
|
182
192
|
export function codexHookAnswer(event, out) {
|
|
193
|
+
if (event === "PostToolUse") return {}; // Telemetry must never alter Codex output.
|
|
183
194
|
const o = isObject(out) ? out : {};
|
|
184
195
|
const systemMessage = text(o.systemMessage);
|
|
185
196
|
const warning = systemMessage ? { systemMessage } : {};
|
|
@@ -209,9 +220,10 @@ export function codexHookAnswer(event, out) {
|
|
|
209
220
|
/**
|
|
210
221
|
* What `passcontrol codex-hook` prints for one hook run: Codex's input in, the
|
|
211
222
|
* sidecar's answer out, or nothing. Never throws, and never blocks on its own
|
|
212
|
-
* failure: a sidecar that is down or slow lets the action go ahead, with a warning
|
|
223
|
+
* failure: a sidecar that is down or slow lets the action go ahead, with a warning
|
|
224
|
+
* for prompts/pre-tool events. Post-tool telemetry always prints nothing.
|
|
213
225
|
*/
|
|
214
|
-
export async function runCodexHook({ input, port, fetchImpl = fetch, promptTimeoutMs = PROMPT_RELAY_MS, toolTimeoutMs = TOOL_RELAY_MS }) {
|
|
226
|
+
export async function runCodexHook({ input, port, fetchImpl = fetch, promptTimeoutMs = PROMPT_RELAY_MS, toolTimeoutMs = TOOL_RELAY_MS, postToolTimeoutMs = POST_TOOL_RELAY_MS }) {
|
|
215
227
|
let parsed;
|
|
216
228
|
try {
|
|
217
229
|
parsed = JSON.parse(input);
|
|
@@ -221,6 +233,30 @@ export async function runCodexHook({ input, port, fetchImpl = fetch, promptTimeo
|
|
|
221
233
|
const event = isObject(parsed) ? parsed.hook_event_name : null;
|
|
222
234
|
if (!EVENTS.includes(event)) return "";
|
|
223
235
|
const tool = event === "PreToolUse";
|
|
236
|
+
const postTool = event === "PostToolUse";
|
|
237
|
+
// A post-tool hook is telemetry only. Bound the entire operation, including a
|
|
238
|
+
// stalled response body or a transport that does not honor AbortSignal.
|
|
239
|
+
if (postTool) {
|
|
240
|
+
const controller = new AbortController();
|
|
241
|
+
let timer;
|
|
242
|
+
try {
|
|
243
|
+
const timeout = new Promise((resolve) => {
|
|
244
|
+
timer = setTimeout(() => { controller.abort(); resolve(""); }, postToolTimeoutMs);
|
|
245
|
+
});
|
|
246
|
+
const relay = async () => {
|
|
247
|
+
await fetchImpl(`http://127.0.0.1:${port}${HOOK_PATH}`, {
|
|
248
|
+
method: "POST", headers: { "content-type": "application/json" }, body: input, signal: controller.signal,
|
|
249
|
+
});
|
|
250
|
+
return "";
|
|
251
|
+
};
|
|
252
|
+
return await Promise.race([relay(), timeout]);
|
|
253
|
+
} catch {
|
|
254
|
+
return "";
|
|
255
|
+
} finally {
|
|
256
|
+
clearTimeout(timer);
|
|
257
|
+
controller.abort();
|
|
258
|
+
}
|
|
259
|
+
}
|
|
224
260
|
const controller = new AbortController();
|
|
225
261
|
const timer = setTimeout(() => controller.abort(), tool ? toolTimeoutMs : promptTimeoutMs);
|
|
226
262
|
const warn = (why) => JSON.stringify({ systemMessage: `PassControl: ${why}, so this goes ahead unchecked.` });
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import type { ToolRuleVerdict } from "./tool-rules.mjs";
|
|
2
|
+
|
|
3
|
+
export type TaintVerdict = ToolRuleVerdict | { effect: "ask_owner"; reason: "injection_taint" };
|
|
4
|
+
|
|
5
|
+
export const INJECTION_HOLD_TOOLS: ReadonlySet<string>;
|
|
6
|
+
export function heldUnderTaint(toolName: unknown): boolean;
|
|
7
|
+
export function underTaint<V extends ToolRuleVerdict>(verdict: V, toolName: unknown): V | { effect: "ask_owner"; reason: "injection_taint" };
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
// Injection guard Phase 2, `hold`: which tools wait for the owner while an agent is
|
|
2
|
+
// tainted (owner, 2026-10-30; plans/injection-guard.md §4).
|
|
3
|
+
//
|
|
4
|
+
// Shared by the sidecar's tool gate and the gateway's re-check in
|
|
5
|
+
// POST /api/v1/tool-approvals, so what the sidecar holds is exactly what the gateway
|
|
6
|
+
// will put to the owner. Reading goes on: Read, Glob and Grep pass. Acting waits:
|
|
7
|
+
// running a command, writing a file, fetching a URL (a URL can carry data out) and any
|
|
8
|
+
// MCP tool. An explicit deny rule still wins, as everywhere in the rule language.
|
|
9
|
+
// `apply_patch` is Codex's file edit (its shell arrives as `Bash`; seen live, Codex
|
|
10
|
+
// 0.163, 2026-10-30).
|
|
11
|
+
|
|
12
|
+
export const INJECTION_HOLD_TOOLS = new Set(["Bash", "Write", "Edit", "MultiEdit", "NotebookEdit", "WebFetch", "apply_patch"]);
|
|
13
|
+
|
|
14
|
+
/** True for a tool a tainted agent may not run without the owner. */
|
|
15
|
+
export function heldUnderTaint(toolName) {
|
|
16
|
+
if (typeof toolName !== "string") return false;
|
|
17
|
+
if (INJECTION_HOLD_TOOLS.has(toolName)) return true;
|
|
18
|
+
// `mcp__<server>__<tool>`: anything past the prefix.
|
|
19
|
+
return toolName.startsWith("mcp__") && toolName.length > "mcp__".length;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* The verdict while tainted: a held tool is put to the owner unless a rule already
|
|
24
|
+
* denies it or already asks the owner. Any other verdict comes back unchanged.
|
|
25
|
+
*/
|
|
26
|
+
export function underTaint(verdict, toolName) {
|
|
27
|
+
if (!heldUnderTaint(toolName)) return verdict;
|
|
28
|
+
if (verdict?.effect === "deny" || verdict?.effect === "ask_owner") return verdict;
|
|
29
|
+
return { effect: "ask_owner", reason: "injection_taint" };
|
|
30
|
+
}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
export type InjectionFamily = "role_markup" | "instruction_override" | "exfil_directive" | "authority_claim" | "hidden_text";
|
|
2
|
+
export type InjectionSeverity = "high" | "low";
|
|
3
|
+
export interface InjectionHit {
|
|
4
|
+
family: InjectionFamily;
|
|
5
|
+
severity: InjectionSeverity;
|
|
6
|
+
}
|
|
7
|
+
|
|
8
|
+
export const INJECTION_DETECTOR: "pc-heuristic-1";
|
|
9
|
+
export const INJECTION_NORMALIZATION: 1;
|
|
10
|
+
export const INJECTION_FAMILIES: readonly InjectionFamily[];
|
|
11
|
+
export function scanText(raw: string): InjectionHit[];
|