passcontrol 1.7.1 → 1.8.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 +51 -0
- package/cli/codex-hooks.mjs +2 -2
- package/cli/memory-custody-sidecar.d.mts +19 -0
- package/cli/memory-custody-sidecar.mjs +470 -0
- package/cli/memory-custody.d.mts +24 -0
- package/cli/memory-custody.mjs +444 -0
- package/cli/memory-inventory.d.mts +15 -0
- package/cli/memory-inventory.mjs +390 -0
- package/cli/memory-review.d.mts +3 -0
- package/cli/memory-review.mjs +65 -0
- package/cli/menu.mjs +1 -0
- package/cli/mission-tools.d.mts +27 -0
- package/cli/mission-tools.mjs +373 -0
- package/cli/proxy-policy.mjs +1 -1
- package/cli/sidecar.mjs +176 -5
- package/cli/subscription-gate.mjs +32 -10
- package/cli/tool-gate.mjs +45 -3
- package/cli/tool-rules.d.mts +5 -1
- package/cli/tool-rules.mjs +29 -10
- package/cli/tripwire-scan.d.mts +20 -0
- package/cli/tripwire-scan.mjs +279 -0
- package/cli/tripwire-sidecar.d.mts +10 -0
- package/cli/tripwire-sidecar.mjs +84 -0
- package/cli/tripwires.d.mts +21 -0
- package/cli/tripwires.mjs +208 -0
- package/cli/visa-client.mjs +3 -0
- package/cli/watch-feed.mjs +1 -1
- package/package.json +1 -1
- package/sdk/passcontrol.js +8 -1
package/cli/sidecar.mjs
CHANGED
|
@@ -9,12 +9,15 @@ import { declaredLineage, declaredSession } from "./declared-session.mjs";
|
|
|
9
9
|
import { defaultJournalDir, openJournal } from "./journal.mjs";
|
|
10
10
|
import { heldUnderTaint } from "./injection-hold.mjs";
|
|
11
11
|
import { findingsFromHook, gapFromOversizedHook } from "./injection-sidecar.mjs";
|
|
12
|
-
import {
|
|
12
|
+
import { plantedDigests } from "./tripwires.mjs";
|
|
13
|
+
import { createTripwireReporter, decoyInHeaders, decoysInHook, TRIPWIRE_PATH } from "./tripwire-sidecar.mjs";
|
|
14
|
+
import { answer, createWatchFeed, hostIsThisListener, isNotACall, isLocalCaller, LOCAL_PREFIX, peekText, providerOf, refusalCode, requestModel } from "./watch-feed.mjs";
|
|
13
15
|
import { createStopGate, HOOK_PATH, SELF_READ_TIMEOUT_MS, selfAnswerState } from "./subscription-gate.mjs";
|
|
14
16
|
import { createToolGate } from "./tool-gate.mjs";
|
|
15
17
|
import { OTLP_LOGS_PATH, readClaudeCodeEvents } from "./otlp-logs.mjs";
|
|
16
18
|
import { CLIENT_EVENTS_PATH, CLIENT_EVENTS_SOURCE, createCallUploader } from "./client-events-upload.mjs";
|
|
17
19
|
import { heldUsageWindow, WINDOW_PATH } from "./usage-window.mjs";
|
|
20
|
+
import { createMemoryCustody } from "./memory-custody-sidecar.mjs";
|
|
18
21
|
|
|
19
22
|
// Hop-by-hop headers plus the ones the sidecar rebuilds itself. `proxy-connection`
|
|
20
23
|
// and friends only appear once something is used as a FORWARD proxy, which is
|
|
@@ -158,6 +161,9 @@ export function createSidecar({
|
|
|
158
161
|
// Subscription mode, Phase 1b: upload the calls Claude Code reports to the
|
|
159
162
|
// gateway's agent page (cli/client-events-upload.mjs). `--no-report-calls` turns it off.
|
|
160
163
|
reportCalls = true,
|
|
164
|
+
// Idea 12: the digests of the decoys `configure tripwires` planted on this machine.
|
|
165
|
+
// Read once at start; a re-run of configure takes effect on the next sidecar start.
|
|
166
|
+
tripwireDigests = plantedDigests(),
|
|
161
167
|
}) {
|
|
162
168
|
// The upstream URL below is built from this, not from the argument: the
|
|
163
169
|
// sidecar forwards a bearer visa on every proxied request, so its destination
|
|
@@ -212,10 +218,11 @@ export function createSidecar({
|
|
|
212
218
|
"accept-encoding": "identity",
|
|
213
219
|
};
|
|
214
220
|
if (session) headers["x-claude-code-session-id"] = session;
|
|
215
|
-
return fetch(`${origin}${path}`, { headers, signal });
|
|
221
|
+
return fetch(`${origin}${path}`, { headers, signal, redirect: "manual" });
|
|
216
222
|
})]);
|
|
217
223
|
const answer = await Promise.race([deadline, selfAnswerState(response)]);
|
|
218
224
|
if (answer.state === "open") {
|
|
225
|
+
memoryCustody.setView(answer.memory);
|
|
219
226
|
readHighVersion = Math.max(readHighVersion, highAtStart);
|
|
220
227
|
readRelayVersion = Math.max(readRelayVersion, relayAtStart);
|
|
221
228
|
if (answer.injection?.mode === "hold" && !reportCalls && !holdOptOutWarned) {
|
|
@@ -230,6 +237,29 @@ export function createSidecar({
|
|
|
230
237
|
}
|
|
231
238
|
const stopGate = createStopGate({ readSelf, dashboardUrl: `${origin}/dashboard` });
|
|
232
239
|
|
|
240
|
+
// Idea 13: memory custody (cli/memory-custody-sidecar.mjs). Hashes and kinds only.
|
|
241
|
+
const MEMORY_CUSTODY_PATH = "/api/v1/memory-custody";
|
|
242
|
+
const MEMORY_CUSTODY_TIMEOUT_MS = 4_000;
|
|
243
|
+
async function sendMemoryCustody(payload) {
|
|
244
|
+
const response = await visas.fetchWithVisa((visa) =>
|
|
245
|
+
fetch(`${origin}${MEMORY_CUSTODY_PATH}`, {
|
|
246
|
+
method: "POST",
|
|
247
|
+
redirect: "manual",
|
|
248
|
+
headers: {
|
|
249
|
+
"content-type": "application/json",
|
|
250
|
+
authorization: `Bearer ${visa}`,
|
|
251
|
+
"x-passcontrol-run": runId,
|
|
252
|
+
"x-passcontrol-proof": visas.createProof(visa, "POST", new URL(MEMORY_CUSTODY_PATH, origin)),
|
|
253
|
+
"accept-encoding": "identity",
|
|
254
|
+
},
|
|
255
|
+
body: JSON.stringify(payload),
|
|
256
|
+
signal: AbortSignal.timeout(MEMORY_CUSTODY_TIMEOUT_MS),
|
|
257
|
+
})
|
|
258
|
+
);
|
|
259
|
+
return { status: response.status, body: await response.json().catch(() => null) };
|
|
260
|
+
}
|
|
261
|
+
const memoryCustody = createMemoryCustody({ send: sendMemoryCustody, onWarn: (m) => warn(m) });
|
|
262
|
+
|
|
233
263
|
// Phase 2's `ask_owner` tool rules: the gateway asks the owner (their alert
|
|
234
264
|
// destination is in its Vault) and holds each request a few seconds; this asks
|
|
235
265
|
// again until the owner answers or the tool gate's wait runs out.
|
|
@@ -253,6 +283,7 @@ export function createSidecar({
|
|
|
253
283
|
if (session) headers["x-claude-code-session-id"] = session;
|
|
254
284
|
return fetch(`${origin}${TOOL_APPROVALS_PATH}`, {
|
|
255
285
|
method: "POST",
|
|
286
|
+
redirect: "manual",
|
|
256
287
|
headers,
|
|
257
288
|
body,
|
|
258
289
|
signal: AbortSignal.timeout(Math.min(APPROVAL_REQUEST_TIMEOUT_MS, Math.max(1_000, deadline - Date.now()))),
|
|
@@ -280,6 +311,7 @@ export function createSidecar({
|
|
|
280
311
|
const response = await visas.fetchWithVisa((visa) =>
|
|
281
312
|
fetch(`${origin}${CLIENT_EVENTS_PATH}`, {
|
|
282
313
|
method: "POST",
|
|
314
|
+
redirect: "manual",
|
|
283
315
|
headers: {
|
|
284
316
|
"content-type": "application/json",
|
|
285
317
|
authorization: `Bearer ${visa}`,
|
|
@@ -309,6 +341,36 @@ export function createSidecar({
|
|
|
309
341
|
}
|
|
310
342
|
const injectionSeen = new Set();
|
|
311
343
|
const uploader = reportCalls ? createCallUploader({ send: sendReportedCalls }) : null;
|
|
344
|
+
// Idea 12. Reports go as this agent, through the same visa path as every upload.
|
|
345
|
+
async function sendTripwire(body) {
|
|
346
|
+
const response = await visas.fetchWithVisa((visa) =>
|
|
347
|
+
fetch(`${origin}${TRIPWIRE_PATH}`, {
|
|
348
|
+
method: "POST",
|
|
349
|
+
redirect: "manual",
|
|
350
|
+
headers: {
|
|
351
|
+
"content-type": "application/json",
|
|
352
|
+
authorization: `Bearer ${visa}`,
|
|
353
|
+
"x-passcontrol-run": runId,
|
|
354
|
+
"x-passcontrol-proof": visas.createProof(visa, "POST", new URL(TRIPWIRE_PATH, origin)),
|
|
355
|
+
"accept-encoding": "identity",
|
|
356
|
+
},
|
|
357
|
+
body: JSON.stringify(body),
|
|
358
|
+
signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS),
|
|
359
|
+
})
|
|
360
|
+
);
|
|
361
|
+
return { status: response.status };
|
|
362
|
+
}
|
|
363
|
+
const tripwires = tripwireDigests.size > 0 ? createTripwireReporter({ send: sendTripwire }) : null;
|
|
364
|
+
const lastTools = [];
|
|
365
|
+
const TOOL_NAME = /^[A-Za-z0-9_.-]{1,128}$/;
|
|
366
|
+
function noteTools(input) {
|
|
367
|
+
const calls = input.hook_event_name === "PostToolBatch" && Array.isArray(input.tool_calls) ? input.tool_calls : [input];
|
|
368
|
+
for (const c of calls) {
|
|
369
|
+
if (typeof c?.tool_name === "string" && TOOL_NAME.test(c.tool_name)) lastTools.push(c.tool_name);
|
|
370
|
+
}
|
|
371
|
+
while (lastTools.length > 5) lastTools.shift();
|
|
372
|
+
}
|
|
373
|
+
const recentTools = () => [...lastTools];
|
|
312
374
|
// Its decisions reach the agent's page with the reported calls (same opt-out).
|
|
313
375
|
const toolGate = createToolGate({
|
|
314
376
|
askOwner,
|
|
@@ -442,6 +504,22 @@ export function createSidecar({
|
|
|
442
504
|
res.end();
|
|
443
505
|
}
|
|
444
506
|
|
|
507
|
+
// Idea 13: `passcontrol memory review` asks here, from this machine only.
|
|
508
|
+
const MEMORY_REVIEW_PATH = "/_passcontrol/memory";
|
|
509
|
+
async function serveMemoryReview(req, res) {
|
|
510
|
+
const port = server.address()?.port;
|
|
511
|
+
req.resume();
|
|
512
|
+
if (req.method !== "GET") return answer(res, 405, "method_not_allowed", "GET only.");
|
|
513
|
+
if (!isLocalCaller(req, port)) return answer(res, 403, "memory_refused", "For this machine only.");
|
|
514
|
+
const url = new URL(req.url ?? "/", "http://127.0.0.1");
|
|
515
|
+
const cwd = url.searchParams.get("cwd");
|
|
516
|
+
if (!cwd || !cwd.startsWith("/")) return answer(res, 400, "memory_cwd", "Pass the workspace as ?cwd=/absolute/path.");
|
|
517
|
+
const out = await memoryCustody.review(cwd, url.searchParams.get("client") === "codex" ? "codex" : "claude-code").catch(() => ({ state: "unavailable", items: [] }));
|
|
518
|
+
const body = JSON.stringify(out);
|
|
519
|
+
res.writeHead(200, { "content-type": "application/json", "content-length": Buffer.byteLength(body), "cache-control": "no-store" });
|
|
520
|
+
res.end(body);
|
|
521
|
+
}
|
|
522
|
+
|
|
445
523
|
function serveHook(req, res) {
|
|
446
524
|
const port = server.address()?.port;
|
|
447
525
|
if (req.method !== "POST") {
|
|
@@ -498,6 +576,18 @@ export function createSidecar({
|
|
|
498
576
|
// Bounded by HOOK_BODY_LIMIT; 8 MB of hostile text scans in under half a second
|
|
499
577
|
// (measured 2026-10-31). Only the upload is asynchronous.
|
|
500
578
|
if (input.hook_event_name === "PostToolBatch" || input.hook_event_name === "PostToolUse") {
|
|
579
|
+
// Idea 12: a planted decoy in what a tool returned to the model is Seen. Digests
|
|
580
|
+
// only leave; the upload is not awaited and never changes the hook answer.
|
|
581
|
+
if (tripwires) {
|
|
582
|
+
try {
|
|
583
|
+
noteTools(input);
|
|
584
|
+
const seenDecoys = decoysInHook(input, tripwireDigests);
|
|
585
|
+
if (seenDecoys.length) tripwires.seen(seenDecoys).catch(() => {});
|
|
586
|
+
tripwires.heartbeat().catch(() => {});
|
|
587
|
+
} catch {
|
|
588
|
+
// Local telemetry must never change the hook answer.
|
|
589
|
+
}
|
|
590
|
+
}
|
|
501
591
|
try {
|
|
502
592
|
for (const event of findingsFromHook(input, { seen: injectionSeen })) {
|
|
503
593
|
// A gap holds like a strong finding (1.7.1).
|
|
@@ -511,6 +601,14 @@ export function createSidecar({
|
|
|
511
601
|
// Local telemetry must never change the hook answer.
|
|
512
602
|
}
|
|
513
603
|
}
|
|
604
|
+
// Idea 13: memory custody sees the event first, so a check that arms the hold has
|
|
605
|
+
// armed it before the tool gate decides this very tool.
|
|
606
|
+
const hookParams = new URL(req.url ?? "/", "http://127.0.0.1").searchParams;
|
|
607
|
+
await memoryCustody.hook(input, {
|
|
608
|
+
client: hookParams.get("client") === "codex" ? "codex" : "claude-code",
|
|
609
|
+
// API mode's own hooks (configure writes `mode=api` on its tool hook, `note=only` on its prompt hook).
|
|
610
|
+
api: hookParams.get("mode") === "api" || hookParams.get("note") === "only",
|
|
611
|
+
});
|
|
514
612
|
let out;
|
|
515
613
|
try {
|
|
516
614
|
if (input.hook_event_name === "PreToolUse") await freshInjectionFor(input.tool_name);
|
|
@@ -523,7 +621,13 @@ export function createSidecar({
|
|
|
523
621
|
if (out.continue !== false && input.hook_event_name === "PreToolUse") {
|
|
524
622
|
let tool;
|
|
525
623
|
try {
|
|
526
|
-
|
|
624
|
+
// A strong local finding the gateway has not yet been read after (the read
|
|
625
|
+
// just failed) puts a held tool to the gateway's own taint, whatever the cached
|
|
626
|
+
// "clear" says: an agent that floods /self straight after reading an injection
|
|
627
|
+
// must not outrun its taint (cloud review 2026-11-03, SC-B). The gateway then
|
|
628
|
+
// decides: no taint there answers `not_ask_owner`, and the tool goes.
|
|
629
|
+
const unconfirmed = stopGate.injectionHoldMode() && heldUnderTaint(input.tool_name) && highVersion > readHighVersion;
|
|
630
|
+
tool = await toolGate.decide(input, stopGate.toolRules(), hookTimeoutS(req.url), unconfirmed ? "tainted" : stopGate.injection(), memoryCustody.state(input.session_id));
|
|
527
631
|
} catch {
|
|
528
632
|
tool = {};
|
|
529
633
|
}
|
|
@@ -537,6 +641,31 @@ export function createSidecar({
|
|
|
537
641
|
req.on("error", () => res.destroy());
|
|
538
642
|
}
|
|
539
643
|
|
|
644
|
+
// Idea 13, API mode: the tool results and memory sections a model request carries.
|
|
645
|
+
// Bounded: past the wait the call goes on and the hold is armed (fail closed).
|
|
646
|
+
async function memoryCustodyOfRequest(req, body) {
|
|
647
|
+
if (!body || memoryCustody.state() === "off") return null;
|
|
648
|
+
const session = lineageOf(req.headers)?.session;
|
|
649
|
+
const withhold = memoryCustody.mode() === "withhold";
|
|
650
|
+
if (body.length > 16 * 1024 * 1024) return withhold ? memoryCustody.fallback(session, null) : null;
|
|
651
|
+
let parsed;
|
|
652
|
+
try {
|
|
653
|
+
parsed = JSON.parse(body.toString("utf8"));
|
|
654
|
+
} catch {
|
|
655
|
+
return null; // not a JSON model request: there is no memory in it to cut
|
|
656
|
+
}
|
|
657
|
+
if (!session && !withhold) return null;
|
|
658
|
+
let timer;
|
|
659
|
+
const result = await Promise.race([
|
|
660
|
+
memoryCustody.modelRequest(session, parsed).then((b) => ({ done: true, b })),
|
|
661
|
+
new Promise((resolve) => { timer = setTimeout(() => resolve({ done: false }), 5_000); }),
|
|
662
|
+
]).finally(() => clearTimeout(timer));
|
|
663
|
+
// Withhold mode never forwards what it did not finish checking: on a timeout every memory
|
|
664
|
+
// section is cut and the session is held (fail closed).
|
|
665
|
+
const next = result.done ? result.b : withhold ? memoryCustody.fallback(session, parsed) : null;
|
|
666
|
+
return next ? Buffer.from(JSON.stringify(next)) : null;
|
|
667
|
+
}
|
|
668
|
+
|
|
540
669
|
const localBaseUrl = () => {
|
|
541
670
|
const address = server?.listening ? server.address() : null;
|
|
542
671
|
return `http://${host}:${address?.port ?? port}`;
|
|
@@ -561,7 +690,8 @@ export function createSidecar({
|
|
|
561
690
|
headers["x-passcontrol-run"] = runId;
|
|
562
691
|
headers["x-passcontrol-proof"] = visas.createProof(visa, req.method, new URL(path, origin));
|
|
563
692
|
headers["accept-encoding"] = "identity";
|
|
564
|
-
|
|
693
|
+
// Hand redirects to the agent; never replay the visa, proof or body at Location.
|
|
694
|
+
return fetch(`${origin}${path}`, { method: req.method, headers, body: body ?? undefined, redirect: "manual" });
|
|
565
695
|
}
|
|
566
696
|
|
|
567
697
|
// A service call's pagination `link` and same-origin `location` name the
|
|
@@ -654,11 +784,37 @@ export function createSidecar({
|
|
|
654
784
|
}
|
|
655
785
|
}
|
|
656
786
|
|
|
787
|
+
// A proxied call carries this run's visa, so a web page must never get one
|
|
788
|
+
// (cloud review 2026-11-03, SC-A). Browsers mark what they send: an Origin on a
|
|
789
|
+
// cross-origin or non-GET request, and Sec-Fetch-Site on every request
|
|
790
|
+
// (Chrome, Firefox, Safari 16.4+). Agent clients send neither. Node's own fetch
|
|
791
|
+
// does send `sec-fetch-mode: cors`, so that header proves nothing and is not read.
|
|
792
|
+
// A DNS-rebound page sends no Origin, but its Host names the attacker's domain:
|
|
793
|
+
// an origin-form request on a loopback bind must name this listener exactly. A
|
|
794
|
+
// forward-proxy request (absolute form) names its target and goes to the classifier;
|
|
795
|
+
// a page cannot send one. Off loopback (an explicit opt-in) the Host is whatever the
|
|
796
|
+
// network calls this machine, so only the browser check applies there.
|
|
797
|
+
const checksHost = isLoopbackBindHost(host);
|
|
798
|
+
function refuseBrowserCaller(req, res, port) {
|
|
799
|
+
const browser = req.headers.origin !== undefined || req.headers["sec-fetch-site"] !== undefined;
|
|
800
|
+
const rebound = checksHost && String(req.url ?? "").startsWith("/") && !hostIsThisListener(req.headers.host, port);
|
|
801
|
+
if (!browser && !rebound) return false;
|
|
802
|
+
req.resume();
|
|
803
|
+
if (browser) {
|
|
804
|
+
answer(res, 403, "sidecar_browser_refused", "The PassControl sidecar serves agents on this machine, not web pages.");
|
|
805
|
+
} else {
|
|
806
|
+
answer(res, 403, "sidecar_host_refused", `Address the sidecar as 127.0.0.1:${port} or localhost:${port}.`);
|
|
807
|
+
}
|
|
808
|
+
return true;
|
|
809
|
+
}
|
|
810
|
+
|
|
657
811
|
const server = http.createServer(async (req, res) => {
|
|
812
|
+
if (refuseBrowserCaller(req, res, server.address()?.port)) return;
|
|
658
813
|
// The sidecar's own paths: answered here, never forwarded with a visa.
|
|
659
814
|
if (String(req.url ?? "").startsWith(LOCAL_PREFIX)) {
|
|
660
815
|
const localPath = String(req.url).split("?")[0];
|
|
661
816
|
if (localPath === HOOK_PATH) return serveHook(req, res);
|
|
817
|
+
if (localPath === MEMORY_REVIEW_PATH) return void serveMemoryReview(req, res);
|
|
662
818
|
if (localPath === OTLP_LOGS_PATH) return serveOtlpLogs(req, res);
|
|
663
819
|
if (localPath === WINDOW_PATH) return serveWindow(req, res);
|
|
664
820
|
feed.serve(req, res, { port: server.address()?.port });
|
|
@@ -679,8 +835,22 @@ export function createSidecar({
|
|
|
679
835
|
let watch = null;
|
|
680
836
|
try {
|
|
681
837
|
const body = await readBody(req);
|
|
838
|
+
// Idea 12: a planted decoy in a credential header is Used. The sidecar would strip
|
|
839
|
+
// it and send its own visa, so the gateway would never see it: refuse here with the
|
|
840
|
+
// answer an unknown key gets, and report it first, so the stop happens before the
|
|
841
|
+
// answer. A report that fails still refuses; nothing is forwarded either way.
|
|
842
|
+
const decoy = tripwires ? decoyInHeaders(req.headers, tripwireDigests, isStripped) : null;
|
|
843
|
+
if (decoy) {
|
|
844
|
+
await tripwires.used(decoy, recentTools());
|
|
845
|
+
feed.record({ outcome: "denied", code: "invalid_credential", status: 401, lineage: lineageOf(req.headers), startedAt });
|
|
846
|
+
res.writeHead(401, { "content-type": "application/json" });
|
|
847
|
+
res.end(JSON.stringify({ error: "invalid_credential" }));
|
|
848
|
+
return;
|
|
849
|
+
}
|
|
682
850
|
watch = watchCall(req, verdict.path, body, startedAt);
|
|
683
|
-
|
|
851
|
+
// Idea 13: in withhold mode the body may come back with pending memory cut out.
|
|
852
|
+
const sent = (await memoryCustodyOfRequest(req, body)) ?? body;
|
|
853
|
+
const upstream = await visas.fetchWithVisa((visa) => fetchUpstream(req, verdict.path, sent, visa));
|
|
684
854
|
writeResponse(res, upstream, req.headers, watch);
|
|
685
855
|
} catch (e) {
|
|
686
856
|
upstreamFailed(res, watch, req, verdict.path, e);
|
|
@@ -702,6 +872,7 @@ export function createSidecar({
|
|
|
702
872
|
// is not answered here: it goes to the gateway as `/api/version`, so an app
|
|
703
873
|
// sees the gateway's real answer, including a refusal where `local` is off.
|
|
704
874
|
const ollamaServer = http.createServer(async (req, res) => {
|
|
875
|
+
if (refuseBrowserCaller(req, res, ollamaServer.address()?.port)) return;
|
|
705
876
|
if (!String(req.url ?? "").startsWith("/")) {
|
|
706
877
|
req.resume();
|
|
707
878
|
res.writeHead(400, { "content-type": "application/json" });
|
|
@@ -146,7 +146,12 @@ export function createStopGate({
|
|
|
146
146
|
if (answer.state === "open" && answer.self) latest = { self: answer.self, at: now() };
|
|
147
147
|
if (answer.state === "open") {
|
|
148
148
|
injectionEntry = { value: answer.injection, at: now() };
|
|
149
|
-
rules = {
|
|
149
|
+
rules = {
|
|
150
|
+
read: answer.toolRules && typeof answer.toolRules === "object" ? answer.toolRules : { state: "none" },
|
|
151
|
+
at: now(),
|
|
152
|
+
// Idea 11: the mission's local-tool section, when the agent is on one.
|
|
153
|
+
...(answer.mission && typeof answer.mission === "object" ? { mission: answer.mission } : {}),
|
|
154
|
+
};
|
|
150
155
|
}
|
|
151
156
|
if (["open", "stopped"].includes(answer.state) || (session !== null && answer.state === "session_stopped")) {
|
|
152
157
|
record(session, answer.state);
|
|
@@ -237,21 +242,35 @@ export function createStopGate({
|
|
|
237
242
|
return warnOnce(session ?? "", reason ?? "no answer");
|
|
238
243
|
}
|
|
239
244
|
|
|
240
|
-
/**
|
|
245
|
+
/**
|
|
246
|
+
* The tool rules from the latest answer, however old; null only before the first.
|
|
247
|
+
*
|
|
248
|
+
* They used to lapse after `maxStaleMs`, and lapsed rules let every tool through. A
|
|
249
|
+
* read fails when /self's own rate limit is spent, which anything on the machine can
|
|
250
|
+
* do through the sidecar, so "the reads fail" switched the rules off on demand (cloud
|
|
251
|
+
* review 2026-11-03, SC-B). The last rules the gateway gave stay in force until it
|
|
252
|
+
* gives others (owner, 2026-11-04: option 1). Stops are not kept this way: those are
|
|
253
|
+
* the gateway's to enforce, and it does, ahead of the rate limit.
|
|
254
|
+
*/
|
|
241
255
|
function toolRules() {
|
|
242
|
-
return rules
|
|
256
|
+
return rules;
|
|
243
257
|
}
|
|
244
258
|
|
|
245
259
|
function injection() {
|
|
246
260
|
if (!injectionEntry || injectionEntry.value === undefined) return "off";
|
|
247
|
-
if (age(injectionEntry) > maxStaleMs) return "unknown";
|
|
248
261
|
const value = injectionEntry.value;
|
|
249
|
-
|
|
250
|
-
if (value.
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
262
|
+
let state = "unknown";
|
|
263
|
+
if (value && value.mode === "hold" && value.readable === true) {
|
|
264
|
+
if (value.tainted_until === null) state = "clear";
|
|
265
|
+
else if (typeof value.tainted_until === "string") {
|
|
266
|
+
const until = Date.parse(value.tainted_until);
|
|
267
|
+
if (Number.isFinite(until)) state = until > now() ? "tainted" : "clear";
|
|
268
|
+
}
|
|
269
|
+
}
|
|
270
|
+
// A taint the gateway named holds until the end it named, read or no read (SC-B,
|
|
271
|
+
// as above). Any other state is only as good as its age.
|
|
272
|
+
if (age(injectionEntry) > maxStaleMs && state !== "tainted") return "unknown";
|
|
273
|
+
return state;
|
|
255
274
|
}
|
|
256
275
|
|
|
257
276
|
// Keep the last known mode even after max-stale: a fresh read may recover it.
|
|
@@ -270,6 +289,9 @@ export async function selfAnswerState(response) {
|
|
|
270
289
|
const toolRules = body && typeof body === "object" ? body.tool_rules : undefined;
|
|
271
290
|
const answer = toolRules && typeof toolRules === "object" ? { state: "open", toolRules } : { state: "open" };
|
|
272
291
|
if (body && typeof body === "object" && Object.hasOwn(body, "injection")) answer.injection = body.injection;
|
|
292
|
+
if (body && typeof body === "object" && body.mission && typeof body.mission === "object") answer.mission = body.mission;
|
|
293
|
+
// Idea 13: the memory hold (absent when the owner has memory custody off).
|
|
294
|
+
if (body && typeof body === "object" && Object.hasOwn(body, "memory")) answer.memory = body.memory;
|
|
273
295
|
// The limits and the soft pause, for the agent's note; nothing else from the answer is kept.
|
|
274
296
|
if (body && typeof body === "object" && body.budget && typeof body.budget === "object") {
|
|
275
297
|
const kept = (v) => (v && typeof v === "object" ? v : null);
|
package/cli/tool-gate.mjs
CHANGED
|
@@ -27,6 +27,7 @@
|
|
|
27
27
|
// page: tool name, decision, rule number and wait. Never the command, path or URL.
|
|
28
28
|
import { underTaint } from "./injection-hold.mjs";
|
|
29
29
|
import { evaluateToolRules, parseToolRules } from "./tool-rules.mjs";
|
|
30
|
+
import { evaluateMissionTools, toolItemKey } from "./mission-tools.mjs";
|
|
30
31
|
|
|
31
32
|
/** The wait ends this long before Claude Code would give up on the hook. */
|
|
32
33
|
export const HOOK_MARGIN_S = 30;
|
|
@@ -86,8 +87,9 @@ export function createToolGate({ askOwner, onDecision = () => {}, now = () => Da
|
|
|
86
87
|
* The rules from the latest trusted /self read, or null.
|
|
87
88
|
* @param {number | null} hookTimeoutS What the hook's URL says it waits; null when it does not say.
|
|
88
89
|
* @param {"off" | "clear" | "tainted" | "unknown"} injection
|
|
90
|
+
* @param {"off" | "clear" | "held"} memory idea 13: unresolved memory arrivals hold the same tools
|
|
89
91
|
*/
|
|
90
|
-
async function decide(input, rulesEntry, hookTimeoutS, injection = "off") {
|
|
92
|
+
async function decide(input, rulesEntry, hookTimeoutS, injection = "off", memory = "off") {
|
|
91
93
|
if (input?.hook_event_name !== "PreToolUse") return {};
|
|
92
94
|
if (needsRefresh || refreshing) {
|
|
93
95
|
if (!refreshing) {
|
|
@@ -114,10 +116,13 @@ export function createToolGate({ askOwner, onDecision = () => {}, now = () => Da
|
|
|
114
116
|
}
|
|
115
117
|
|
|
116
118
|
const original = evaluateToolRules(parsed, input);
|
|
117
|
-
const hit = injection === "tainted" ? underTaint(original, input.tool_name) : original;
|
|
119
|
+
const hit = injection === "tainted" || memory === "held" ? underTaint(original, input.tool_name) : original;
|
|
118
120
|
const escalated = hit.reason === "injection_taint";
|
|
119
121
|
// `/self` says only that the agent is tainted, not why: a tell, or output not fully checked (1.7.1).
|
|
120
|
-
const guardText =
|
|
122
|
+
const guardText =
|
|
123
|
+
injection !== "tainted" && memory === "held"
|
|
124
|
+
? "This tool was held by memory custody: the agent's memory files have entries waiting for the owner's review (they arrived with no custody record, or were written while outside content was in its context)."
|
|
125
|
+
: "This tool was held by the injection guard: something the agent recently read looked like a prompt injection, or could not be fully checked.";
|
|
121
126
|
let warning = {};
|
|
122
127
|
if (injection === "unknown" && (injectionWarnedAt === null || now() - injectionWarnedAt >= WARN_EVERY_MS)) {
|
|
123
128
|
injectionWarnedAt = now();
|
|
@@ -129,6 +134,43 @@ export function createToolGate({ askOwner, onDecision = () => {}, now = () => Da
|
|
|
129
134
|
try { onHold({ tool: String(input.tool_name ?? "").slice(0, 128), outcome }); } catch {}
|
|
130
135
|
}
|
|
131
136
|
}
|
|
137
|
+
// Idea 11: the agent's mission, local-tool section. A GUARD RAIL, not a boundary
|
|
138
|
+
// (cli/mission-tools.mjs says why). Only adds friction where the rules above are
|
|
139
|
+
// not already stricter: a deny stays a deny, an ask_owner still asks the owner.
|
|
140
|
+
// Outside an enforcing mission the call holds through Claude Code's own prompt;
|
|
141
|
+
// shadow mode records what it would have held and changes nothing.
|
|
142
|
+
const mission = rulesEntry?.mission;
|
|
143
|
+
if (mission && (hit.effect === null || hit.effect === "ask") && !escalated) {
|
|
144
|
+
// Mission-only (R11-01): between missions nothing is standing authority, so every
|
|
145
|
+
// tool the rules do not already decide holds here, as the gateway holds services.
|
|
146
|
+
if (mission.only === true && mission.state === "none") {
|
|
147
|
+
record(input, "mission_outside", null, 0);
|
|
148
|
+
return withWarning(
|
|
149
|
+
verdict(
|
|
150
|
+
"ask",
|
|
151
|
+
"PassControl: this agent works only on missions, and none is in force. Confirm it here if you meant it; a mission is approved by the owner. This check is a guard rail on this machine, not a boundary."
|
|
152
|
+
)
|
|
153
|
+
);
|
|
154
|
+
}
|
|
155
|
+
if (mission.state === "ok" && Array.isArray(mission.tools)) {
|
|
156
|
+
const judged = evaluateMissionTools(mission.tools, input);
|
|
157
|
+
if (judged.state === "outside" && mission.mode === "enforce") {
|
|
158
|
+
record(input, "mission_outside", null, 0);
|
|
159
|
+
const what = judged.missing.map((item) => toolItemKey(item)).join(", ");
|
|
160
|
+
return withWarning(
|
|
161
|
+
verdict(
|
|
162
|
+
"ask",
|
|
163
|
+
`PassControl: this is outside this agent's mission (${short(what)}). Confirm it here if you meant it; widening the mission itself needs the owner. This check is a guard rail on this machine, not a boundary.`
|
|
164
|
+
)
|
|
165
|
+
);
|
|
166
|
+
}
|
|
167
|
+
if (judged.state === "outside") record(input, "mission_would_hold", null, 0);
|
|
168
|
+
} else if (mission.state === "unknown" && (warnedAt === null || now() - warnedAt >= WARN_EVERY_MS)) {
|
|
169
|
+
warnedAt = now();
|
|
170
|
+
warning = { ...warning, systemMessage: "PassControl could not read this agent's mission yet, so this goes ahead. The gateway still enforces it for models and services." };
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
|
|
132
174
|
const ruleIndex = escalated ? null : hit.ruleIndex;
|
|
133
175
|
if (hit.effect === null) return withWarning({});
|
|
134
176
|
const rule = escalated ? "injection guard" : `rule ${hit.ruleIndex + 1}`;
|
package/cli/tool-rules.d.mts
CHANGED
|
@@ -25,4 +25,8 @@ export const TOOL_RULE_LIMITS: {
|
|
|
25
25
|
};
|
|
26
26
|
export function globMatch(pattern: string, text: string): boolean;
|
|
27
27
|
export function parseToolRules(value: unknown): ParsedToolRules;
|
|
28
|
-
export function evaluateToolRules(
|
|
28
|
+
export function evaluateToolRules(
|
|
29
|
+
parsed: { rules: ToolRule[] },
|
|
30
|
+
input: ToolRuleInput,
|
|
31
|
+
options?: { platform?: string; caseless?: boolean }
|
|
32
|
+
): ToolRuleVerdict;
|
package/cli/tool-rules.mjs
CHANGED
|
@@ -25,6 +25,8 @@
|
|
|
25
25
|
// Honest limit: these are guard rails for the owner's own sessions. `sh -c`, an alias,
|
|
26
26
|
// a script file or a different tool gets round a command rule.
|
|
27
27
|
|
|
28
|
+
import { normalizeHostname } from "./proxy-policy.mjs";
|
|
29
|
+
|
|
28
30
|
export const TOOL_RULE_EFFECTS = ["deny", "ask_owner", "ask"];
|
|
29
31
|
const STRICTNESS = { deny: 3, ask_owner: 2, ask: 1 };
|
|
30
32
|
|
|
@@ -144,10 +146,17 @@ function normalisePath(raw) {
|
|
|
144
146
|
}
|
|
145
147
|
|
|
146
148
|
function commandPieces(command) {
|
|
149
|
+
// Cheap shell forms only, not a Bash parser: quoting, escapes, wrappers and
|
|
150
|
+
// program-specific options can still evade these guard rails.
|
|
147
151
|
return command
|
|
148
|
-
.split(
|
|
152
|
+
.split(/&&|\|\||\$\(|[;&|\n()`]/)
|
|
149
153
|
.map((piece) => piece.trim())
|
|
150
|
-
.filter(Boolean)
|
|
154
|
+
.filter(Boolean)
|
|
155
|
+
.flatMap((piece) => {
|
|
156
|
+
const stripped = piece.replace(/^(?:[A-Za-z_][A-Za-z0-9_]*=(?:'[^']*'|"[^"]*"|[^\s'"]*)\s+)+/, "");
|
|
157
|
+
return stripped === piece ? [piece] : [piece, stripped];
|
|
158
|
+
})
|
|
159
|
+
.map((piece) => piece.replace(/\s+/g, " "));
|
|
151
160
|
}
|
|
152
161
|
|
|
153
162
|
function toolMatches(pattern, name) {
|
|
@@ -161,14 +170,22 @@ function toolMatches(pattern, name) {
|
|
|
161
170
|
*
|
|
162
171
|
* Input a rule needs but cannot read (no command, a URL that does not parse) counts as
|
|
163
172
|
* matching that rule: a rule the owner wrote is not skipped because the input was odd.
|
|
173
|
+
*
|
|
174
|
+
* Path rules ignore case where the filesystem does (cloud review 2026-11-03, SC-E):
|
|
175
|
+
* macOS and Windows by default, so `/users/NAS/.SSH/key` meets a deny on
|
|
176
|
+
* `/Users/nas/.ssh/*`. Every effect is restrictive, so this only ever makes the gate
|
|
177
|
+
* stricter for the sidecar. `caseless` overrides the platform; the gateway passes it
|
|
178
|
+
* both ways (see app/api/v1/tool-approvals), since a caseless deny must not pre-empt
|
|
179
|
+
* its taint hold.
|
|
164
180
|
*/
|
|
165
|
-
export function evaluateToolRules(parsed, input) {
|
|
181
|
+
export function evaluateToolRules(parsed, input, { platform = typeof process === "undefined" ? "" : process.platform, caseless } = {}) {
|
|
182
|
+
const ignoreCase = caseless ?? (platform === "darwin" || platform === "win32");
|
|
166
183
|
const name = typeof input?.tool_name === "string" ? input.tool_name : "";
|
|
167
184
|
const toolInput = isRecord(input?.tool_input) ? input.tool_input : {};
|
|
168
185
|
let best = null;
|
|
169
186
|
parsed.rules.forEach((rule, ruleIndex) => {
|
|
170
187
|
if (!toolMatches(rule.tool, name)) return;
|
|
171
|
-
const subject = subjectFor(rule, name, toolInput, input);
|
|
188
|
+
const subject = subjectFor(rule, name, toolInput, input, ignoreCase);
|
|
172
189
|
if (subject === undefined) return;
|
|
173
190
|
if (!best || STRICTNESS[rule.effect] > STRICTNESS[best.effect]) best = { effect: rule.effect, ruleIndex, subject };
|
|
174
191
|
});
|
|
@@ -176,7 +193,7 @@ export function evaluateToolRules(parsed, input) {
|
|
|
176
193
|
}
|
|
177
194
|
|
|
178
195
|
// The matched text, `undefined` when the rule does not apply to this input.
|
|
179
|
-
function subjectFor(rule, name, toolInput, input) {
|
|
196
|
+
function subjectFor(rule, name, toolInput, input, ignoreCase) {
|
|
180
197
|
if (rule.command !== undefined) {
|
|
181
198
|
if (typeof toolInput.command !== "string") return "";
|
|
182
199
|
return commandPieces(toolInput.command).find((piece) => globMatch(rule.command, piece));
|
|
@@ -187,20 +204,22 @@ function subjectFor(rule, name, toolInput, input) {
|
|
|
187
204
|
if (raw === undefined && SEARCH_TOOLS.has(name) && typeof input?.cwd === "string") raw = input.cwd;
|
|
188
205
|
if (raw === undefined) return "";
|
|
189
206
|
const path = normalisePath(raw);
|
|
190
|
-
|
|
207
|
+
const hit = ignoreCase ? globMatch(rule.path.toLowerCase(), path.toLowerCase()) : globMatch(rule.path, path);
|
|
208
|
+
return hit ? path : undefined;
|
|
191
209
|
}
|
|
192
210
|
if (rule.domain !== undefined) {
|
|
193
211
|
let host;
|
|
194
212
|
try {
|
|
195
|
-
host = new URL(String(toolInput.url)).hostname
|
|
213
|
+
host = normalizeHostname(new URL(String(toolInput.url)).hostname);
|
|
196
214
|
} catch {
|
|
197
215
|
return "";
|
|
198
216
|
}
|
|
199
|
-
|
|
200
|
-
|
|
217
|
+
const domain = normalizeHostname(rule.domain);
|
|
218
|
+
if (domain.startsWith("*.")) {
|
|
219
|
+
const base = domain.slice(2);
|
|
201
220
|
return host === base || host.endsWith(`.${base}`) ? host : undefined;
|
|
202
221
|
}
|
|
203
|
-
return host ===
|
|
222
|
+
return host === domain ? host : undefined;
|
|
204
223
|
}
|
|
205
224
|
return name;
|
|
206
225
|
}
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
export interface DecoyCandidates {
|
|
2
|
+
candidates: string[];
|
|
3
|
+
truncated: boolean;
|
|
4
|
+
}
|
|
5
|
+
export const TRIPWIRE_SCAN_LIMITS: Readonly<{
|
|
6
|
+
maxCandidates: number;
|
|
7
|
+
maxDepth: number;
|
|
8
|
+
streamWindow: number;
|
|
9
|
+
streamTail: number;
|
|
10
|
+
seam: number;
|
|
11
|
+
}>;
|
|
12
|
+
/** A credential header's value, plus its decoded HTTP Basic credentials when it is Basic auth. */
|
|
13
|
+
export function credentialHeaderTexts(raw: unknown): string[];
|
|
14
|
+
export function findDecoyCandidates(text: string): DecoyCandidates;
|
|
15
|
+
export function candidatesInJson(value: unknown): DecoyCandidates & { gaps: ("depth_limit" | "candidate_limit")[] };
|
|
16
|
+
export function createStreamCandidateFinder(): {
|
|
17
|
+
push(fragment: string): void;
|
|
18
|
+
finish(): DecoyCandidates;
|
|
19
|
+
retained(): number;
|
|
20
|
+
};
|