@acepaste/ingress 0.9.6 → 0.9.22

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.
Files changed (74) hide show
  1. package/dist/src/adapters.d.ts +9 -0
  2. package/dist/src/adapters.js +76 -6
  3. package/dist/src/agent-hooks.d.ts +112 -0
  4. package/dist/src/agent-hooks.js +533 -0
  5. package/dist/src/approvers.d.ts +16 -0
  6. package/dist/src/approvers.js +50 -0
  7. package/dist/src/audio.d.ts +70 -0
  8. package/dist/src/audio.js +224 -0
  9. package/dist/src/audit-changes.d.ts +46 -0
  10. package/dist/src/audit-changes.js +110 -0
  11. package/dist/src/audit-local.d.ts +57 -0
  12. package/dist/src/audit-local.js +231 -0
  13. package/dist/src/audit-parsers.d.ts +1 -1
  14. package/dist/src/audit.js +48 -0
  15. package/dist/src/broker.d.ts +92 -1
  16. package/dist/src/broker.js +222 -3
  17. package/dist/src/calendar.d.ts +36 -0
  18. package/dist/src/calendar.js +227 -0
  19. package/dist/src/captions.d.ts +44 -0
  20. package/dist/src/captions.js +209 -0
  21. package/dist/src/changes.d.ts +105 -0
  22. package/dist/src/changes.js +174 -0
  23. package/dist/src/character.js +15 -1
  24. package/dist/src/classifier-model.d.ts +53 -0
  25. package/dist/src/classifier-model.js +3 -0
  26. package/dist/src/classifier.d.ts +41 -0
  27. package/dist/src/classifier.js +213 -0
  28. package/dist/src/cli.js +501 -1
  29. package/dist/src/egress.d.ts +71 -0
  30. package/dist/src/egress.js +242 -0
  31. package/dist/src/email.d.ts +42 -0
  32. package/dist/src/email.js +424 -0
  33. package/dist/src/engine.d.ts +36 -12
  34. package/dist/src/engine.js +88 -37
  35. package/dist/src/image-meta.d.ts +33 -0
  36. package/dist/src/image-meta.js +433 -0
  37. package/dist/src/image.d.ts +110 -0
  38. package/dist/src/image.js +353 -0
  39. package/dist/src/index.d.ts +50 -5
  40. package/dist/src/index.js +28 -3
  41. package/dist/src/localguard.d.ts +33 -0
  42. package/dist/src/localguard.js +61 -0
  43. package/dist/src/meaning.d.ts +2 -0
  44. package/dist/src/meaning.js +77 -22
  45. package/dist/src/messages.d.ts +79 -0
  46. package/dist/src/messages.js +431 -0
  47. package/dist/src/nearby.d.ts +52 -0
  48. package/dist/src/nearby.js +186 -0
  49. package/dist/src/netpolicy.js +50 -19
  50. package/dist/src/provenance.d.ts +56 -0
  51. package/dist/src/provenance.js +114 -0
  52. package/dist/src/qr.d.ts +25 -0
  53. package/dist/src/qr.js +113 -0
  54. package/dist/src/safeguards.d.ts +61 -0
  55. package/dist/src/safeguards.js +199 -0
  56. package/dist/src/served.d.ts +20 -0
  57. package/dist/src/served.js +53 -0
  58. package/dist/src/shell-commands.d.ts +39 -0
  59. package/dist/src/shell-commands.js +291 -0
  60. package/dist/src/shortcuts.d.ts +45 -0
  61. package/dist/src/shortcuts.js +220 -0
  62. package/dist/src/stream.d.ts +88 -0
  63. package/dist/src/stream.js +119 -0
  64. package/dist/src/terminal.d.ts +29 -0
  65. package/dist/src/terminal.js +313 -0
  66. package/dist/src/tooldefs.d.ts +84 -0
  67. package/dist/src/tooldefs.js +122 -0
  68. package/dist/src/types.d.ts +50 -6
  69. package/dist/src/types.js +15 -2
  70. package/dist/src/visibility.d.ts +23 -3
  71. package/dist/src/visibility.js +285 -78
  72. package/native/ingress-presence.swift +48 -0
  73. package/native/ingress-vision.swift +417 -0
  74. package/package.json +3 -1
@@ -0,0 +1,231 @@
1
+ /**
2
+ * Environment audit, local side: what is attached to this machine and what it exposes.
3
+ * Pure parsers and classifiers (no file, process or network access here). Collectors are in audit.ts.
4
+ *
5
+ * input devices A device that presents itself as a keyboard types as the person. In an agent's terminal
6
+ * keystrokes are the user, so no content check ever sees them (BadUSB, "rubber ducky"
7
+ * cables, an unauthenticated Bluetooth keyboard). The audit cannot watch typing; it can say
8
+ * which keyboards exist, so a new one is noticed.
9
+ * listening What accepts connections, and whether from this machine only or from the network.
10
+ * Identity is the program and its exposure, not the port (ports change on every restart).
11
+ * tunnels A tunnel or reverse forward turns a local port into an internet address: "localhost"
12
+ * stops being local.
13
+ * printers A printer's name and address are set by whoever is on the network; a print job sends a
14
+ * document there.
15
+ * interfaces A new network adapter (a USB Ethernet dongle) can take over routing and DNS.
16
+ */
17
+ /** Parse `hidutil list`. Columns are fixed-width; the header gives their positions. */
18
+ export function parseHidutilList(text) {
19
+ const lines = text.split(/\r?\n/);
20
+ const out = [];
21
+ let cols;
22
+ for (const line of lines) {
23
+ if (/^VendorID\s+ProductID/.test(line)) {
24
+ cols = [...line.matchAll(/\S+/g)].map((m) => ({ name: m[0], start: m.index }));
25
+ continue;
26
+ }
27
+ if (!cols || !/^0x[0-9a-f]+\s/i.test(line)) {
28
+ if (/^\w+:\s*$/.test(line))
29
+ cols = undefined;
30
+ continue;
31
+ }
32
+ const cell = (name) => {
33
+ const i = cols.findIndex((c) => c.name === name);
34
+ if (i < 0)
35
+ return "";
36
+ return line.slice(cols[i].start, i + 1 < cols.length ? cols[i + 1].start : undefined).trim();
37
+ };
38
+ out.push({
39
+ vendorId: cell("VendorID").toLowerCase(), productId: cell("ProductID").toLowerCase(), transport: cell("Transport").replace(/^\(null\)$/, ""),
40
+ product: cell("Product").replace(/^\(null\)$/, ""), usagePage: Number(cell("UsagePage")) || 0, usage: Number(cell("Usage")) || 0, builtIn: cell("Built-In") === "1",
41
+ });
42
+ }
43
+ return out;
44
+ }
45
+ /** names that say the device is something other than a keyboard */
46
+ const NOT_A_KEYBOARD = /\b(cable|charger|charging|power ?bank|flash|drive|disk|storage|card ?reader|hub|adapter|dongle|camera|webcam|headset|headphone|speaker|audio|microphone|lan|ethernet|display|monitor|light|fan|usb ?c)\b/i;
47
+ const KEYBOARD_NAME = /\b(keyboard|keypad|kbd|receiver|magic|mx ?keys|k\d{2,3}|keychron|hhkb|planck|ergodox|corne|moonlander|numpad|macropad|stream ?deck|yubikey|security key|titan|scanner|barcode)\b/i;
48
+ export function classifyInputDevices(devices) {
49
+ // one physical device has several HID interfaces; it is a keyboard if any of them is (generic desktop page 1, usage 6 or 7)
50
+ const byDevice = new Map();
51
+ for (const d of devices) {
52
+ if (d.builtIn || !d.transport)
53
+ continue;
54
+ const id = `${d.vendorId}:${d.productId}:${d.product}`;
55
+ const e = byDevice.get(id) ?? { d, keyboard: false };
56
+ if (d.usagePage === 1 && (d.usage === 6 || d.usage === 7))
57
+ e.keyboard = true;
58
+ byDevice.set(id, e);
59
+ }
60
+ const out = [];
61
+ for (const { d, keyboard } of byDevice.values()) {
62
+ if (!keyboard)
63
+ continue;
64
+ const name = d.product || "(unnamed device)";
65
+ const odd = NOT_A_KEYBOARD.test(name) && !KEYBOARD_NAME.test(name);
66
+ const unnamed = !d.product;
67
+ out.push({
68
+ area: "input-devices", severity: odd || unnamed ? "high" : "review",
69
+ title: `${d.transport} device that can type: ${name}`,
70
+ detail: odd
71
+ ? `"${name}" (${d.vendorId}:${d.productId}) presents itself as a keyboard, which its name does not suggest. A device that types acts as you: in an agent's terminal its keystrokes are your prompts. Unplug it unless you know why it needs to type.`
72
+ : unnamed
73
+ ? `An unnamed ${d.transport} device (${d.vendorId}:${d.productId}) presents itself as a keyboard. A device that types acts as you.`
74
+ : `"${name}" (${d.vendorId}:${d.productId}) can type. Yours if you recognise it; a keyboard you did not attach acts as you.`,
75
+ where: `${d.transport} ${d.vendorId}:${d.productId}`,
76
+ });
77
+ }
78
+ return out;
79
+ }
80
+ export function parseLsofListen(text) {
81
+ const out = [];
82
+ for (const line of text.split(/\r?\n/)) {
83
+ const m = line.match(/^(\S+)\s+(\d+)\s+(\S+)\s+.*\sTCP\s+(\S+):(\d+)\s+\(LISTEN\)\s*$/);
84
+ if (!m)
85
+ continue;
86
+ const address = m[4].replace(/^\[|\]$/g, "");
87
+ const loopback = address === "localhost" || address === "::1" || /^127\./.test(address);
88
+ out.push({ command: m[1].replace(/\\x20/g, " "), pid: Number(m[2]), user: m[3], address, port: Number(m[5]), exposed: !loopback });
89
+ }
90
+ return out;
91
+ }
92
+ /** programs that serve a model or agent tools; exposed to the network without a login they hand both to anyone nearby */
93
+ const AI_SERVERS = /^(ollama|lm ?studio|lms|llama-server|llama\.cpp|koboldcpp|text-generation|oobabooga|vllm|localai|jan|open-webui|comfyui|invokeai|mcp[-\w]*|claude)$/i;
94
+ export function classifyListeners(listeners) {
95
+ const by = new Map();
96
+ for (const l of listeners) {
97
+ const key = `${l.command}|${l.exposed}`;
98
+ const e = by.get(key) ?? { command: l.command, exposed: l.exposed, ports: new Set(), users: new Set() };
99
+ e.ports.add(l.port);
100
+ e.users.add(l.user);
101
+ by.set(key, e);
102
+ }
103
+ const out = [];
104
+ for (const e of by.values()) {
105
+ const ports = [...e.ports].sort((a, b) => a - b).slice(0, 8).join(", ");
106
+ const ai = AI_SERVERS.test(e.command);
107
+ if (e.exposed) {
108
+ out.push({
109
+ area: "listening", severity: ai ? "high" : "review",
110
+ title: `${e.command} accepts connections from the network`,
111
+ detail: ai
112
+ ? `${e.command} looks like a model or tool server and listens on every interface (port ${ports}). Anyone on the same network can use it, and what it returns reaches your agents as if it were local. Bind it to 127.0.0.1 unless you mean to share it.`
113
+ : `Port ${ports}. Reachable from other machines on the network. Yours if you turned on a sharing feature or run a server on purpose.`,
114
+ where: "lsof",
115
+ });
116
+ }
117
+ else {
118
+ out.push({
119
+ area: "listening", severity: "info",
120
+ title: `${e.command} listens on this machine only`,
121
+ detail: `Port ${ports}. Reachable only from this machine. Programs here, including web pages in a browser, can still talk to it; content it serves is not trusted because it is local.`,
122
+ where: "lsof",
123
+ });
124
+ }
125
+ }
126
+ return out;
127
+ }
128
+ export function findTunnels(psOutput) {
129
+ const out = [];
130
+ for (const raw of psOutput.split(/\r?\n/)) {
131
+ const line = raw.trim();
132
+ if (!line)
133
+ continue;
134
+ const args = line.replace(/^\d+\s+\S+\s+/, "");
135
+ const prog = (args.split(/\s+/)[0] ?? "").split("/").pop() ?? "";
136
+ const short = args.replace(/(--?(?:authtoken|token|password|key|secret)[=\s]+)\S+/gi, "$1[hidden]").slice(0, 160);
137
+ if (/^ngrok$/i.test(prog) && /\b(http|tcp|tls|start|tunnel)\b/.test(args))
138
+ out.push({ tool: "ngrok", detail: short });
139
+ else if (/^cloudflared$/i.test(prog) && /\btunnel\b/.test(args))
140
+ out.push({ tool: "cloudflared", detail: short });
141
+ else if (/^ssh$/.test(prog) && /\s-[A-Za-z]*[RD]\b|\s-[A-Za-z]*R\s*\d|RemoteForward|DynamicForward/.test(args))
142
+ out.push({ tool: /\s-[A-Za-z]*D\b|DynamicForward/.test(args) ? "ssh dynamic forward (SOCKS proxy)" : "ssh remote forward", detail: short });
143
+ else if (/^tailscale$/i.test(prog) && /\b(funnel|serve)\b/.test(args))
144
+ out.push({ tool: `tailscale ${/funnel/.test(args) ? "funnel" : "serve"}`, detail: short });
145
+ else if (/^(frpc|bore|lt|localtunnel|devtunnel|zrok|pinggy|localhost\.run|serveo|pagekite(\.py)?|chisel|inlets)$/i.test(prog))
146
+ out.push({ tool: prog, detail: short });
147
+ else if (/^ssh$/.test(prog) && /(serveo\.net|localhost\.run|pinggy\.io|tunnelto|tmate\.io)/.test(args))
148
+ out.push({ tool: "ssh tunnel service", detail: short });
149
+ }
150
+ return out;
151
+ }
152
+ export function classifyTunnels(tunnels) {
153
+ return tunnels.map((t) => ({
154
+ area: "tunnels", severity: "review",
155
+ title: `tunnel open: ${t.tool}`,
156
+ detail: `${t.detail}. A tunnel gives a port on this machine an address on the internet (or carries this machine's traffic elsewhere). Data an agent sends to that local port leaves the machine. Yours if you started it.`,
157
+ where: "running processes",
158
+ }));
159
+ }
160
+ export function parseLpstatDevices(text) {
161
+ const out = [];
162
+ for (const line of text.split(/\r?\n/)) {
163
+ const m = line.match(/^device for (.+?):\s+(\S.*)$/);
164
+ if (m)
165
+ out.push({ name: m[1], uri: m[2].trim() });
166
+ }
167
+ return out;
168
+ }
169
+ const normName = (n) => n.toLowerCase().replace(/[^a-z0-9]+/g, "");
170
+ export function classifyPrinters(printers) {
171
+ const out = [];
172
+ const seen = new Map();
173
+ for (const p of printers) {
174
+ let host = "", scheme = "";
175
+ try {
176
+ const u = new URL(p.uri);
177
+ host = decodeURIComponent(u.hostname);
178
+ scheme = u.protocol.replace(":", "");
179
+ }
180
+ catch {
181
+ scheme = p.uri.split(":")[0];
182
+ }
183
+ const local = scheme === "usb" || scheme === "dnssd" || /\.local\.?$/i.test(host) || /^(10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.|169\.254\.|f[cd]|fe80)/i.test(host);
184
+ const twin = seen.get(normName(p.name).replace(/\d+$/, ""));
185
+ if (twin && twin.uri !== p.uri) {
186
+ out.push({ area: "printers", severity: "review", title: `two printers share a name: ${twin.name} and ${p.name}`, detail: `They point to different addresses (${twin.uri.slice(0, 80)} and ${p.uri.slice(0, 80)}). A printer that copies the name of one you use receives the documents meant for it.`, where: "lpstat -v" });
187
+ }
188
+ else
189
+ seen.set(normName(p.name).replace(/\d+$/, ""), p);
190
+ out.push({
191
+ area: "printers", severity: local ? "info" : "review",
192
+ title: `printer: ${p.name}`,
193
+ detail: local
194
+ ? `${p.uri.slice(0, 120)}. On this machine or the local network. A print job sends the document there.`
195
+ : `${p.uri.slice(0, 120)}. This printer is reached at an address outside the local network${scheme === "ipp" || scheme === "http" || scheme === "lpd" || scheme === "socket" ? ", without encryption" : ""}: every document printed to it leaves the building.`,
196
+ where: p.uri.slice(0, 120),
197
+ });
198
+ }
199
+ return out;
200
+ }
201
+ export function parseHardwarePorts(text) {
202
+ const out = [];
203
+ let port;
204
+ for (const line of text.split(/\r?\n/)) {
205
+ const p = line.match(/^Hardware Port:\s*(.+)$/);
206
+ if (p) {
207
+ port = p[1].trim();
208
+ continue;
209
+ }
210
+ const d = line.match(/^Device:\s*(\S+)/);
211
+ if (d && port) {
212
+ out.push({ port, device: d[1] });
213
+ port = undefined;
214
+ }
215
+ }
216
+ return out;
217
+ }
218
+ export function classifyHardwarePorts(ports) {
219
+ return ports.map((p) => {
220
+ const usb = /usb|lan adapter|dongle|rndis|tether|iphone|android/i.test(p.port);
221
+ return {
222
+ area: "network-interfaces", severity: "info",
223
+ // the device name (en6) changes when adapters are re-plugged; the port's name is the identity
224
+ title: `network interface: ${p.port.replace(/\s*\(en\d+\)$/, "")}`,
225
+ detail: usb
226
+ ? `${p.device}. A plug-in network adapter. One you did not attach can take over routing and name resolution for the whole machine.`
227
+ : `${p.device}.`,
228
+ where: "networksetup",
229
+ };
230
+ });
231
+ }
@@ -11,7 +11,7 @@
11
11
  * Severity: "high" = can steer what agents receive and looks out of place; "review" =
12
12
  * changes what agents receive and may well be yours (say so and move on); "info" = noted.
13
13
  */
14
- export type AuditArea = "hosts" | "dns" | "proxy" | "browser-search" | "browser-policy" | "browser-extension" | "certificates" | "network-extension" | "agent-config" | "agent-instructions" | "resolution";
14
+ export type AuditArea = "hosts" | "dns" | "proxy" | "browser-search" | "browser-policy" | "browser-extension" | "certificates" | "network-extension" | "agent-config" | "agent-instructions" | "resolution" | "input-devices" | "listening" | "tunnels" | "printers" | "network-interfaces";
15
15
  export type AuditSeverity = "high" | "review" | "info";
16
16
  export interface AuditFinding {
17
17
  area: AuditArea;
package/dist/src/audit.js CHANGED
@@ -13,6 +13,7 @@ import { connect } from "node:tls";
13
13
  import { createHash } from "node:crypto";
14
14
  import { compareServed } from "./engine.js";
15
15
  import { classifyHosts, classifyDnsmasq, classifyDnscryptRules, classifyResolvConf, classifyScutilDns, classifyScutilProxy, classifyProxyEnv, classifyChromiumSearch, classifyExtension, classifyChromiumPolicy, classifyTrustSettings, classifySystemExtensions, classifyMcpServers, classifyHooks, classifyResolution, summarizeAudit, ipv6Prefix64, WATCHED_DOMAINS, } from "./audit-parsers.js";
16
+ import { parseHidutilList, classifyInputDevices, parseLsofListen, classifyListeners, findTunnels, classifyTunnels, parseLpstatDevices, classifyPrinters, parseHardwarePorts, classifyHardwarePorts } from "./audit-local.js";
16
17
  const read = (p) => { try {
17
18
  return readFileSync(p, "utf8");
18
19
  }
@@ -276,6 +277,53 @@ export async function auditEnvironment(o = {}) {
276
277
  findings.push({ area: "agent-instructions", severity: "info", title: `global agent instructions: ${p}`, detail: `${t.length} characters, fingerprint ${sha}${verdict}. Loaded into every session of that agent; check it says only what you wrote.`, where: p });
277
278
  }
278
279
  note("agent-instructions", "global instruction files (Claude, Codex, Gemini, Windsurf, Cursor)", "checked");
280
+ // ---------- what is attached to this machine, and what it exposes (audit-local.ts) ----------
281
+ if (os === "darwin") {
282
+ const hid = await run("/usr/bin/hidutil", ["list"]);
283
+ if (hid) {
284
+ findings.push(...classifyInputDevices(parseHidutilList(hid)));
285
+ note("input-devices", "devices that can type (hidutil list)", "checked", "which keyboards exist, not what is typed");
286
+ }
287
+ else
288
+ note("input-devices", "devices that can type", "error");
289
+ const hw = await run("/usr/sbin/networksetup", ["-listallhardwareports"]);
290
+ if (hw) {
291
+ findings.push(...classifyHardwarePorts(parseHardwarePorts(hw)));
292
+ note("network-interfaces", "network interfaces (networksetup)", "checked");
293
+ }
294
+ else
295
+ note("network-interfaces", "network interfaces", "error");
296
+ }
297
+ else {
298
+ note("input-devices", "devices that can type", "skipped", "macOS only for now");
299
+ note("network-interfaces", "network interfaces", "skipped", "macOS only for now");
300
+ }
301
+ if (os !== "win32") {
302
+ const listen = await run("/usr/sbin/lsof", ["-nP", "-iTCP", "-sTCP:LISTEN"]) ?? await run("lsof", ["-nP", "-iTCP", "-sTCP:LISTEN"]);
303
+ if (listen !== undefined) {
304
+ findings.push(...classifyListeners(parseLsofListen(listen)));
305
+ note("listening", "listening services (lsof)", "checked", "this user's processes; others need administrator rights");
306
+ }
307
+ else
308
+ note("listening", "listening services", "error", "lsof not available");
309
+ const ps = await run("/bin/ps", ["-axo", "pid=,comm=,args="]);
310
+ if (ps !== undefined) {
311
+ findings.push(...classifyTunnels(findTunnels(ps)));
312
+ note("tunnels", "tunnels and port forwards among running processes", "checked");
313
+ }
314
+ else
315
+ note("tunnels", "tunnels and port forwards", "error");
316
+ const lp = await run("/usr/bin/lpstat", ["-v"]);
317
+ if (lp !== undefined) {
318
+ findings.push(...classifyPrinters(parseLpstatDevices(lp)));
319
+ note("printers", "configured printers (lpstat -v)", "checked");
320
+ // cups-browsed adds printers it hears about on the network without asking (CVE-2024-47176 and related)
321
+ if (os === "linux" && ps !== undefined && /\bcups-browsed\b/.test(ps))
322
+ findings.push({ area: "printers", severity: "review", title: "cups-browsed is running", detail: "It adds printers announced on the network without asking. In 2024 that let anyone on the network add a printer that ran commands when used (CVE-2024-47176 and related). Stop it unless you rely on automatic printer discovery.", where: "running processes" });
323
+ }
324
+ else
325
+ note("printers", "configured printers", "not present", "no print system found");
326
+ }
279
327
  // ---------- live resolution and TLS ----------
280
328
  if (o.network) {
281
329
  const names = WATCHED_DOMAINS.filter((d) => !d.startsWith("www.") && d !== "en.wikipedia.org");
@@ -14,9 +14,19 @@
14
14
  * outside an allowlist) need approval while tainted, even on "read" tools
15
15
  * - a run that touched a quarantined source is denied side effects outright
16
16
  *
17
+ * And whatever the run has read (safeguards.ts):
18
+ * - an action that creates something which acts later (a scheduled job, an automation, a mail rule,
19
+ * a hook, an edit to an agent's own instructions or memory) always needs a person
20
+ * - an action that carries the run's marker (a canary placed in its context) is refused: the context
21
+ * itself is leaving
22
+ * - a burst of actions, or the same action over and over, is held for a person
23
+ * - a stop switch a person can set refuses everything until they clear it
24
+ *
17
25
  * Limit, stated plainly: the broker enforces only on calls routed through it. A tool the
18
26
  * agent can reach directly is outside its control.
19
27
  */
28
+ import { type BurstPolicy } from "./safeguards.js";
29
+ import { type Blocklist } from "./egress.js";
20
30
  export type ActionDecision = "allow" | "require_approval" | "deny";
21
31
  export interface ActionRule {
22
32
  /** tool name, exact or with * wildcards ("*__send_*", "filesystem__write_file") */
@@ -50,12 +60,49 @@ export interface BrokerPolicy {
50
60
  maxShownArgChars: number;
51
61
  /** what to do when approval is needed but no approver is configured or it fails */
52
62
  onApproverUnavailable: "deny";
63
+ /**
64
+ * Actions that create something which acts later. "always": they need a person even in a run that has
65
+ * read nothing from outside. "tainted": only once the run has. "off": not checked.
66
+ */
67
+ persistenceGuard: "always" | "tainted" | "off";
68
+ /** limits on how fast and how repetitively a run may act before a person is asked */
69
+ burst: BurstPolicy;
70
+ /**
71
+ * Once a run has read outside content, does every tool not known to be read-only need a person? True for
72
+ * an agent whose tools all pass through the broker (the MCP proxy). A harness with its own permission
73
+ * prompts (a coding agent's shell) sets false and relies on the specific checks: persistence, data leaving,
74
+ * codes, blocklists, peripherals.
75
+ */
76
+ approveWhenTainted: boolean;
77
+ /**
78
+ * Is every "scheme:rest" in the arguments held to parsing as an address? True for tool arguments, where a
79
+ * field that looks like an address is one. False for free text such as shell commands.
80
+ */
81
+ strictAddresses: boolean;
82
+ /** requests to one host the run met in outside content, within ten minutes, before a person is asked */
83
+ callHomeLimit: number;
84
+ /** email addresses in one action's arguments, in a run that has read outside content, before a person is asked */
85
+ massRecipients: number;
86
+ /** how long a verification code the run read stays unsendable, milliseconds */
87
+ codeTtlMs: number;
53
88
  }
54
89
  export declare const DEFAULT_BROKER_POLICY: BrokerPolicy;
55
90
  export interface ProposedAction {
56
91
  runId: string;
57
92
  tool: string;
58
93
  args: unknown;
94
+ /**
95
+ * The parts of the arguments that can change something, when the caller can tell (a shell command with its
96
+ * read-only parts removed). When given, the check for things that act later reads these instead of every
97
+ * argument, so that reading a startup file is not mistaken for writing one.
98
+ */
99
+ writes?: string[];
100
+ /**
101
+ * Ways the action sends data to another machine, in plain words, when the caller can tell (a shell command
102
+ * that uploads a file). In a run that has read outside content these need a person, unless every address
103
+ * in the arguments is this machine, on the allowlist, or one the person named.
104
+ */
105
+ sends?: string[];
59
106
  }
60
107
  export interface ApprovalRequest {
61
108
  id: string;
@@ -110,6 +157,23 @@ export interface BrokerEvent {
110
157
  version: number;
111
158
  };
112
159
  }
160
+ /** A run's state as plain data, so a hook that starts a new process per event can carry it between events. */
161
+ export interface SerializedRun {
162
+ sources: string[];
163
+ receipts: string[];
164
+ hosts: string[];
165
+ quarantined: string[];
166
+ canaries: string[];
167
+ codes: Array<[string, number]>;
168
+ mentioned: Array<[string, string]>;
169
+ typed: string[];
170
+ heardPerson: boolean;
171
+ home: Record<string, number[]>;
172
+ burst: {
173
+ at: number[];
174
+ same: Array<[string, number[]]>;
175
+ };
176
+ }
113
177
  /** deterministic JSON: object keys sorted at every depth, so one call has one digest */
114
178
  export declare function canonicalJson(v: unknown): string;
115
179
  export declare function actionDigest(runId: string, tool: string, canonicalArgs: string): string;
@@ -136,8 +200,29 @@ export declare class ActionBroker {
136
200
  approver?: Approver;
137
201
  log?: (e: BrokerEvent) => void;
138
202
  now?: () => number;
203
+ /** why everything is stopped, or undefined (see safeguards.stopReason) */
204
+ stopCheck?: () => string | undefined;
205
+ /** known-bad destinations (see egress.Blocklist) */
206
+ blocklist?: Blocklist;
207
+ /** the program listening on a local port, so a tunnel behind "localhost" is seen for what it is */
208
+ portProgram?: (port: number) => string | undefined;
139
209
  });
140
210
  private run;
211
+ /** A run's state as plain data (see SerializedRun). */
212
+ exportRun(runId: string): SerializedRun;
213
+ /**
214
+ * What the person said in their own words (not what they pasted). A destination they named is theirs: it is
215
+ * not reported as coming from content, and repeated requests to it are not counted as calling home.
216
+ */
217
+ notePersonSaid(runId: string, text: string): void;
218
+ /** Restore a run from exported state. Unknown or malformed fields are ignored, never trusted to loosen anything. */
219
+ importRun(runId: string, s: Partial<SerializedRun> | undefined): void;
220
+ /**
221
+ * A marker for this run's context. Put the returned text where the model will read it (see
222
+ * safeguards.canaryNotice). Any later action whose arguments carry it is refused: nothing the
223
+ * person asked for needs the marker to leave, so its leaving means the context is being sent out.
224
+ */
225
+ plantCanary(runId: string): string;
141
226
  private quarantineHit;
142
227
  /** is this URL or host quarantined? (check before fetching, and on the final URL after redirects) */
143
228
  isQuarantined(urlOrHost: string): string | undefined;
@@ -145,7 +230,8 @@ export declare class ActionBroker {
145
230
  ingest(runId: string, source: {
146
231
  ref: string;
147
232
  receiptDigest?: string;
148
- host?: string;
233
+ host?: string; /** the text the run was given from this source: read for verification codes and for the hosts it names */
234
+ text?: string;
149
235
  }): {
150
236
  tainted: true;
151
237
  sources: string[];
@@ -166,6 +252,11 @@ export declare class ActionBroker {
166
252
  destinations: string[];
167
253
  fields: string[];
168
254
  };
255
+ /**
256
+ * Record that an action went ahead when something other than this broker's approver let it (a harness with
257
+ * its own permission prompt): the burst and call-home counters need to know.
258
+ */
259
+ noteRan(action: ProposedAction): void;
169
260
  /**
170
261
  * Decide, asking the approver when needed. The caller must then execute EXACTLY the
171
262
  * arguments it gets back (frozen) or not at all.