@acepaste/ingress 0.9.25 → 0.9.27

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.
@@ -0,0 +1,567 @@
1
+ /**
2
+ * The egress proxy: where programs an agent runs actually connect.
3
+ *
4
+ * The egress hook reads a command. It does not read the program the command starts: `python upload.py` sends
5
+ * whatever the script sends. Stopping that for a whole machine needs a network filter Apple licenses. This is
6
+ * the part that needs no licence: an HTTP forward proxy on 127.0.0.1 that the agent's shell commands are
7
+ * pointed at (HTTPS_PROXY and friends), which decides each connection by its destination.
8
+ *
9
+ * - CONNECT (everything over TLS) and plain HTTP. It sees a host name and a port, and counts bytes. It never
10
+ * reads what is sent: TLS is not opened.
11
+ * - Every client presents a token made for one agent session. No token, no service. The token says whose
12
+ * connection this is, so the decision can use what that session has read.
13
+ * - The decision reuses what the action broker knows (see ActionBroker.hostStanding): a blocklisted host or
14
+ * address is refused; an address on this machine or a private network is refused (the proxy must not be a
15
+ * way around the checks the gate's own fetches make); a host that came into the session only through
16
+ * outside content, and that no command named, is refused (or put to a person, when an approver is
17
+ * configured); a host on the allowlist, or one the person typed, passes. Anything else passes and is
18
+ * logged, or is refused in strict mode.
19
+ * - Every connection is logged in <state>/egress-proxy/connections.jsonl: time, session, host, port, bytes
20
+ * each way, decision. Never content.
21
+ *
22
+ * What it is not: a firewall. A program that ignores proxy settings connects directly unless it runs under the
23
+ * sandbox wrapper below (`ingress run`). A host that is allowed can pass data on to another. It covers what
24
+ * the agent starts, not the machine.
25
+ */
26
+ import { createServer, request as httpRequest } from "node:http";
27
+ import { connect as netConnect, isIP } from "node:net";
28
+ import { lookup } from "node:dns/promises";
29
+ import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
30
+ import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync } from "node:fs";
31
+ import { spawn, spawnSync } from "node:child_process";
32
+ import { homedir } from "node:os";
33
+ import { join } from "node:path";
34
+ import { stateDir } from "./changes.js";
35
+ import { stopReason } from "./safeguards.js";
36
+ import { ActionBroker } from "./broker.js";
37
+ import { Blocklist } from "./egress.js";
38
+ import { isPrivateIP } from "./netpolicy.js";
39
+ export const EGRESS_PROXY_PORT = 8788;
40
+ const HEALTH_PATH = "/.well-known/ingress-egress-proxy";
41
+ /** how long a host named in a command the hook let through stays usable by what that command started */
42
+ export const VISIBLE_HOST_TTL_MS = 10 * 60_000;
43
+ const proxyDir = (dir) => join(dir, "egress-proxy");
44
+ const safeName = (session) => session.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 80);
45
+ /** the same file the hooks keep a session's state in (agent-hooks.ts) */
46
+ const sessionStatePath = (dir, session) => join(dir, "sessions", `${safeName(session)}.json`);
47
+ const cleanHost = (h) => h.toLowerCase().replace(/^\[|\]$/g, "").replace(/\.$/, "");
48
+ const hmac = (secret, text) => createHmac("sha256", secret).update(text, "utf8").digest("hex");
49
+ function writeAtomic(path, text) {
50
+ writeFileSync(`${path}.${process.pid}.tmp`, text, { mode: 0o600 });
51
+ renameSync(`${path}.${process.pid}.tmp`, path);
52
+ }
53
+ function readJson(path) {
54
+ try {
55
+ return JSON.parse(readFileSync(path, "utf8"));
56
+ }
57
+ catch {
58
+ return undefined;
59
+ }
60
+ }
61
+ // ---------- tokens: whose connection is this ----------
62
+ /** The secret tokens are made with. Created on first use; readable by this user only. */
63
+ export function proxySecret(dir = stateDir()) {
64
+ const p = join(proxyDir(dir), "secret");
65
+ try {
66
+ const s = readFileSync(p, "utf8").trim();
67
+ if (s.length >= 32)
68
+ return s;
69
+ }
70
+ catch { /* made below */ }
71
+ mkdirSync(proxyDir(dir), { recursive: true, mode: 0o700 });
72
+ try {
73
+ writeFileSync(p, randomBytes(32).toString("hex") + "\n", { mode: 0o600, flag: "wx" });
74
+ }
75
+ catch { /* another process made it first */ }
76
+ return readFileSync(p, "utf8").trim();
77
+ }
78
+ /** A token for one session: the session's name and a keyed digest of it. Safe to put in a URL. */
79
+ export function sessionToken(secret, session) {
80
+ const s = session.slice(0, 200);
81
+ return `${Buffer.from(s, "utf8").toString("base64url")}.${hmac(secret, `session:${s}`).slice(0, 40)}`;
82
+ }
83
+ /** The session a token was made for, or undefined when it was not made with this secret. */
84
+ export function sessionOfToken(secret, token) {
85
+ const dot = token.lastIndexOf(".");
86
+ if (dot <= 0)
87
+ return undefined;
88
+ let session;
89
+ try {
90
+ session = Buffer.from(token.slice(0, dot), "base64url").toString("utf8");
91
+ }
92
+ catch {
93
+ return undefined;
94
+ }
95
+ if (!session)
96
+ return undefined;
97
+ const want = Buffer.from(hmac(secret, `session:${session}`).slice(0, 40)), got = Buffer.from(token.slice(dot + 1));
98
+ return want.length === got.length && timingSafeEqual(want, got) ? session : undefined;
99
+ }
100
+ /** The variables that point a command's network calls at the proxy. Loopback is left alone. */
101
+ export function proxyEnv(port, token) {
102
+ const url = `http://ingress:${token}@127.0.0.1:${port}`;
103
+ const none = "localhost,127.0.0.1,::1";
104
+ return {
105
+ HTTPS_PROXY: url, HTTP_PROXY: url, ALL_PROXY: url, https_proxy: url, http_proxy: url, all_proxy: url,
106
+ NO_PROXY: none, no_proxy: none,
107
+ NODE_USE_ENV_PROXY: "1", // Node 22.21 / 24 and later: fetch and http(s) honour the variables above
108
+ INGRESS_EGRESS_PROXY_URL: url,
109
+ };
110
+ }
111
+ // ---------- what the hooks leave for the proxy, and the proxy for the hooks ----------
112
+ /** Hosts named in a command the egress hook let through: what that command starts may connect to them. */
113
+ export function noteVisibleHosts(dir, session, hosts, now = Date.now()) {
114
+ if (!session || !hosts.length)
115
+ return;
116
+ const p = join(proxyDir(dir), "visible", `${safeName(session)}.json`);
117
+ const seen = readJson(p) ?? {};
118
+ for (const h of hosts)
119
+ seen[cleanHost(h)] = now;
120
+ const kept = Object.entries(seen).filter(([, at]) => now - at < VISIBLE_HOST_TTL_MS).sort((a, b) => b[1] - a[1]).slice(0, 200);
121
+ mkdirSync(join(proxyDir(dir), "visible"), { recursive: true, mode: 0o700 });
122
+ writeAtomic(p, JSON.stringify(Object.fromEntries(kept)));
123
+ }
124
+ export function isVisibleHost(dir, session, host, now = Date.now()) {
125
+ const seen = readJson(join(proxyDir(dir), "visible", `${safeName(session)}.json`));
126
+ if (!seen)
127
+ return false;
128
+ const h = cleanHost(host);
129
+ return Object.entries(seen).some(([named, at]) => now - at < VISIBLE_HOST_TTL_MS && (h === named || h.endsWith("." + named)));
130
+ }
131
+ /** When a shell command started, so the hook that runs after it can ask what connected meanwhile. */
132
+ export function noteCommandStart(dir, session, toolUseId, now = Date.now()) {
133
+ if (!session)
134
+ return;
135
+ const p = join(proxyDir(dir), "commands", `${safeName(session)}.json`);
136
+ const all = readJson(p) ?? {};
137
+ all[toolUseId || "last"] = now;
138
+ all.last = now;
139
+ const kept = Object.entries(all).sort((a, b) => b[1] - a[1]).slice(0, 60);
140
+ mkdirSync(join(proxyDir(dir), "commands"), { recursive: true, mode: 0o700 });
141
+ writeAtomic(p, JSON.stringify(Object.fromEntries(kept)));
142
+ }
143
+ export function commandStart(dir, session, toolUseId) {
144
+ const all = readJson(join(proxyDir(dir), "commands", `${safeName(session)}.json`));
145
+ return all?.[toolUseId || "last"];
146
+ }
147
+ const logPath = (dir) => join(proxyDir(dir), "connections.jsonl");
148
+ /** Connections a session opened (or was refused) since a moment. One entry per connection, with the bytes when it has closed. */
149
+ export function connectionsSince(dir, session, sinceMs) {
150
+ let text;
151
+ try {
152
+ text = readFileSync(logPath(dir), "utf8");
153
+ }
154
+ catch {
155
+ return [];
156
+ }
157
+ if (text.length > 4_000_000)
158
+ text = text.slice(-4_000_000);
159
+ const byId = new Map();
160
+ for (const line of text.split("\n")) {
161
+ if (!line.includes(`"session":${JSON.stringify(session)}`))
162
+ continue;
163
+ let e;
164
+ try {
165
+ e = JSON.parse(line);
166
+ }
167
+ catch {
168
+ continue;
169
+ }
170
+ if (e.session !== session || typeof e.id !== "string")
171
+ continue;
172
+ const first = byId.get(e.id);
173
+ if (first)
174
+ byId.set(e.id, { ...first, up: e.up, down: e.down, ms: e.ms, flag: e.flag ?? first.flag, closed: true });
175
+ else if (Date.parse(e.at) >= sinceMs && !e.closed)
176
+ byId.set(e.id, e);
177
+ }
178
+ return [...byId.values()];
179
+ }
180
+ export const DEFAULT_PROXY_POLICY = { mode: "log", allowHosts: [], allowPrivate: [], ports: [], contentHosts: "refuse", uploadFlagBytes: 1_000_000 };
181
+ const hostIn = (host, list) => list.some((a) => { const x = cleanHost(a); return x.startsWith(".") ? host === x.slice(1) || host.endsWith(x) : host === x; });
182
+ /**
183
+ * Decide one connection. Pure: everything it needs is handed in.
184
+ * `addresses` are what the name resolved to (or the literal address); the caller connects to one of exactly those.
185
+ * Without `addresses` only the rules about the name are applied. The proxy asks that way first: a name it is
186
+ * going to refuse is never looked up, because a lookup of `<anything>.their-domain` is itself a message to
187
+ * whoever runs that domain.
188
+ */
189
+ export function decideConnection(c, ctx) {
190
+ const host = cleanHost(c.host), p = ctx.policy;
191
+ if (ctx.stopped)
192
+ return { decision: "refuse", code: "stopped", reason: `a person has stopped all agent actions (${ctx.stopped})` };
193
+ if (c.port !== 80 && c.port !== 443 && !p.ports.includes(c.port))
194
+ return { decision: "refuse", code: "port", reason: `port ${c.port} is not one this proxy carries (80 and 443${p.ports.length ? `, ${p.ports.join(", ")}` : ""})` };
195
+ const listed = ctx.blocklist.match(host) ?? c.addresses?.map((a) => ctx.blocklist.match(a)).find(Boolean);
196
+ if (listed)
197
+ return { decision: "refuse", code: "blocklisted", reason: `${host} is on a blocklist of malware and botnet infrastructure (${listed})` };
198
+ if (c.addresses && !c.addresses.length)
199
+ return { decision: "refuse", code: "unresolvable", reason: `${host} does not resolve to an address` };
200
+ const local = host === "localhost" || /\.(localhost|local|internal|arpa)$/.test(host) || (c.addresses ?? []).some((a) => isPrivateIP(a));
201
+ if (local && !hostIn(host, p.allowPrivate))
202
+ return { decision: "refuse", code: "private", reason: `${host} is this machine or a private network address` };
203
+ if (ctx.standing.allowed || hostIn(host, p.allowHosts))
204
+ return { decision: "allow", code: "allowlisted", reason: "on the allowlist" };
205
+ if (ctx.standing.typed)
206
+ return { decision: "allow", code: "typed", reason: "named by the person" };
207
+ if (ctx.visible)
208
+ return { decision: "allow", code: "named-in-command", reason: "named in a command the egress gate let through" };
209
+ if (ctx.standing.fromContent !== undefined) {
210
+ const reason = `${host} first appeared in ${ctx.standing.fromContent}, not in anything the person typed, and no command names it`;
211
+ return { decision: p.contentHosts === "ask" ? "ask" : "refuse", code: "content-only", reason };
212
+ }
213
+ if (p.mode === "strict")
214
+ return { decision: "refuse", code: "not-listed", reason: `${host} is not on the allowlist, was not named by the person and is not named in a command (strict mode)` };
215
+ return { decision: "allow", code: "default", reason: "no rule against it" };
216
+ }
217
+ const defaultResolve = async (host) => (await lookup(host, { all: true, verbatim: true })).map((a) => a.address);
218
+ /** Start the proxy on 127.0.0.1. Resolves once it is listening. */
219
+ export function startEgressProxy(o = {}) {
220
+ const dir = o.dir ?? stateDir();
221
+ const policy = { ...DEFAULT_PROXY_POLICY, ...(o.policy ?? {}) };
222
+ const now = o.now ?? Date.now;
223
+ const resolve = o.resolve ?? defaultResolve;
224
+ const secret = proxySecret(dir);
225
+ const since = new Date(now()).toISOString();
226
+ mkdirSync(proxyDir(dir), { recursive: true, mode: 0o700 });
227
+ let blocklist = o.blocklist ?? Blocklist.load(join(dir, "blocklists")), blocklistAt = now();
228
+ let lastUse = now(), seq = 0;
229
+ const answers = new Map();
230
+ const asking = new Map();
231
+ const log = (e) => {
232
+ try {
233
+ const p = logPath(dir);
234
+ try {
235
+ if (statSync(p).size > 8_000_000)
236
+ renameSync(p, `${p}.1`);
237
+ }
238
+ catch { /* no log yet */ }
239
+ appendFileSync(p, JSON.stringify({ at: new Date(now()).toISOString(), ...e }) + "\n", { mode: 0o600 });
240
+ }
241
+ catch { /* a connection is decided whether or not it could be recorded */ }
242
+ };
243
+ const sessionOf = (req) => {
244
+ const h = String(req.headers["proxy-authorization"] ?? "");
245
+ const m = h.match(/^Basic\s+([A-Za-z0-9+/=_-]+)$/i);
246
+ if (!m)
247
+ return undefined;
248
+ const creds = Buffer.from(m[1], "base64").toString("utf8");
249
+ return sessionOfToken(secret, creds.slice(creds.indexOf(":") + 1));
250
+ };
251
+ /** Ask a person about one host for one session; one dialog at a time per host, and the answer is kept a while. */
252
+ const askPerson = (session, host, port, reason, sources) => {
253
+ const key = `${session}\n${host}`;
254
+ const kept = answers.get(key);
255
+ if (kept && now() - kept.at < (kept.answer === "approved" ? VISIBLE_HOST_TTL_MS : 120_000))
256
+ return Promise.resolve(kept.answer);
257
+ const running = asking.get(key);
258
+ if (running)
259
+ return running;
260
+ const args = JSON.stringify({ host, port });
261
+ const digest = hmac("approval", `${session}\n${args}`);
262
+ const req = { id: digest.slice(0, 16), runId: session, tool: "network connection (a program the agent started)", canonicalArgs: args, digest, reasons: [reason], destinations: [host], fields: [], sources, createdAt: now(), expiresAt: now() + (o.approvalMs ?? 90_000) };
263
+ let timer;
264
+ const p = (async () => {
265
+ let a;
266
+ try {
267
+ a = await Promise.race([o.approver.request(req), new Promise((r) => { timer = setTimeout(() => r("timeout"), o.approvalMs ?? 90_000); })]);
268
+ }
269
+ catch {
270
+ a = "denied";
271
+ }
272
+ finally {
273
+ if (timer)
274
+ clearTimeout(timer);
275
+ }
276
+ const answer = a === "approved" ? "approved" : "denied";
277
+ answers.set(key, { answer, at: now() });
278
+ asking.delete(key);
279
+ return answer;
280
+ })();
281
+ asking.set(key, p);
282
+ return p;
283
+ };
284
+ /** Everything up to "may this connection be made, and to which address". */
285
+ const admit = async (session, hostRaw, port) => {
286
+ lastUse = now();
287
+ const host = cleanHost(hostRaw), id = `${process.pid}-${++seq}`;
288
+ if (!o.blocklist && now() - blocklistAt > 10 * 60_000) {
289
+ blocklist = Blocklist.load(join(dir, "blocklists"));
290
+ blocklistAt = now();
291
+ }
292
+ const broker = new ActionBroker({ allowHosts: policy.allowHosts });
293
+ const run = readJson(sessionStatePath(dir, session));
294
+ broker.importRun(session, run);
295
+ const standing = broker.hostStanding(session, host);
296
+ const ctx = { policy, blocklist, standing, visible: isVisibleHost(dir, session, host, now()), stopped: stopReason(dir) };
297
+ // The name first, then the addresses: a name that is going to be refused is never looked up.
298
+ let addresses = isIP(host) ? [host] : [];
299
+ let d = decideConnection({ host, port, addresses: isIP(host) ? addresses : undefined }, ctx);
300
+ if (d.decision === "ask") {
301
+ const answer = o.approver ? await askPerson(session, host, port, d.reason, broker.state(session).sources) : "denied";
302
+ d = answer === "approved"
303
+ ? { decision: "allow", code: "approved", reason: `${d.reason}; a person at this machine approved it` }
304
+ : { decision: "refuse", code: d.code, reason: `${d.reason}; ${o.approver ? "a person at this machine was asked and did not approve it" : "no approver is configured"}` };
305
+ }
306
+ if (d.decision === "allow" && !isIP(host)) {
307
+ try {
308
+ addresses = await resolve(host);
309
+ }
310
+ catch {
311
+ addresses = [];
312
+ }
313
+ // the name is settled; only what its addresses add can change the answer
314
+ const again = decideConnection({ host, port, addresses }, ctx);
315
+ if (again.decision === "refuse" && ["blocklisted", "unresolvable", "private"].includes(again.code))
316
+ d = again;
317
+ }
318
+ log({ session, host, port, decision: d.decision === "allow" ? "allow" : "refuse", reason: d.reason, code: d.code, id });
319
+ if (d.decision !== "allow")
320
+ return { ok: false, reason: d.reason };
321
+ return { ok: true, addresses, tainted: standing.tainted, id };
322
+ };
323
+ const refusalText = (reason) => `AcePaste Ingress egress proxy refused this connection: ${reason}.\nThis is a refusal, not a fault. Do not route around the proxy; tell the person.\n`;
324
+ const closed = (session, host, port, id, started, up, down, tainted) => {
325
+ const flag = tainted && up >= policy.uploadFlagBytes ? `sent ${up} bytes to ${host} after the session had read outside content` : undefined;
326
+ log({ session, host, port, decision: "allow", reason: "closed", code: "closed", id, up, down, ms: now() - started, closed: true, ...(flag ? { flag } : {}) });
327
+ };
328
+ const server = createServer((req, res) => { void onRequest(req, res); });
329
+ // ---- CONNECT: a tunnel. Only the host name and port are seen.
330
+ server.on("connect", (req, client, head) => {
331
+ void (async () => {
332
+ const say = (status, body = "", extra = "") => { try {
333
+ client.end(`HTTP/1.1 ${status}\r\n${extra}Content-Type: text/plain; charset=utf-8\r\nContent-Length: ${Buffer.byteLength(body)}\r\nConnection: close\r\n\r\n${body}`);
334
+ }
335
+ catch { /* gone */ } };
336
+ client.on("error", () => { });
337
+ const session = sessionOf(req);
338
+ if (!session)
339
+ return say("407 Proxy Authentication Required", "AcePaste Ingress egress proxy: this connection carries no session token.\n", 'Proxy-Authenticate: Basic realm="ingress-egress"\r\n');
340
+ const m = String(req.url ?? "").match(/^(\[[0-9a-fA-F:.]+\]|[^:\s]+):(\d{1,5})$/);
341
+ if (!m)
342
+ return say("400 Bad Request", "AcePaste Ingress egress proxy: not a host and port.\n");
343
+ const host = cleanHost(m[1]), port = Number(m[2]);
344
+ const a = await admit(session, host, port);
345
+ if (!a.ok)
346
+ return say("403 Forbidden", refusalText(a.reason), "X-Ingress-Egress: refused\r\n");
347
+ const started = now();
348
+ let up = head.length, down = 0, done = false, tried = 0;
349
+ const dial = () => {
350
+ const upstream = netConnect({ host: a.addresses[tried], port });
351
+ let established = false;
352
+ upstream.setTimeout(30_000, () => upstream.destroy(new Error("timeout")));
353
+ upstream.once("connect", () => {
354
+ established = true;
355
+ upstream.setTimeout(0);
356
+ client.write("HTTP/1.1 200 Connection Established\r\n\r\n");
357
+ if (head.length)
358
+ upstream.write(head);
359
+ client.on("data", (c) => { up += c.length; });
360
+ upstream.on("data", (c) => { down += c.length; });
361
+ client.pipe(upstream);
362
+ upstream.pipe(client);
363
+ const finish = () => { if (done)
364
+ return; done = true; client.destroy(); upstream.destroy(); closed(session, host, port, a.id, started, up, down, a.tainted); };
365
+ client.on("close", finish);
366
+ upstream.on("close", finish);
367
+ });
368
+ upstream.on("error", () => {
369
+ if (established)
370
+ return; // the tunnel was up: its close event finishes it
371
+ if (++tried < a.addresses.length)
372
+ return dial();
373
+ say("502 Bad Gateway", `AcePaste Ingress egress proxy: could not reach ${host}:${port}.\n`);
374
+ });
375
+ };
376
+ dial();
377
+ })();
378
+ });
379
+ // ---- plain HTTP: the request line carries a full URL. Headers and body pass through unread.
380
+ async function onRequest(req, res) {
381
+ const url = String(req.url ?? "");
382
+ const send = (status, body, headers = {}) => { res.writeHead(status, { "content-type": "text/plain; charset=utf-8", ...headers }); res.end(body); };
383
+ if (url.startsWith("/")) {
384
+ // who is listening here: proved by a keyed digest of the caller's challenge, so a hook is not fooled by another program on this port
385
+ const u = new URL(url, "http://127.0.0.1");
386
+ if (req.method === "GET" && u.pathname === HEALTH_PATH)
387
+ return send(200, JSON.stringify({ ok: true, proof: hmac(secret, `health:${u.searchParams.get("c") ?? ""}`), pid: process.pid, since, mode: policy.mode }), { "content-type": "application/json" });
388
+ return send(400, "AcePaste Ingress egress proxy: this is a forward proxy; ask for a full URL.\n");
389
+ }
390
+ const session = sessionOf(req);
391
+ if (!session)
392
+ return send(407, "AcePaste Ingress egress proxy: this connection carries no session token.\n", { "proxy-authenticate": 'Basic realm="ingress-egress"' });
393
+ let target;
394
+ try {
395
+ target = new URL(url);
396
+ }
397
+ catch {
398
+ return send(400, "AcePaste Ingress egress proxy: not a URL.\n");
399
+ }
400
+ if (target.protocol !== "http:")
401
+ return send(400, "AcePaste Ingress egress proxy: only http and CONNECT are carried.\n");
402
+ const host = cleanHost(target.hostname), port = target.port ? Number(target.port) : 80;
403
+ const a = await admit(session, host, port);
404
+ if (!a.ok)
405
+ return send(403, refusalText(a.reason), { "x-ingress-egress": "refused" });
406
+ const started = now();
407
+ let up = 0, down = 0, done = false;
408
+ const headers = { ...req.headers };
409
+ for (const h of ["proxy-authorization", "proxy-connection"])
410
+ delete headers[h];
411
+ const out = httpRequest({ host: a.addresses[0], port, method: req.method, path: `${target.pathname}${target.search}`, headers, setHost: false, timeout: 60_000 }, (back) => {
412
+ res.writeHead(back.statusCode ?? 502, back.headers);
413
+ back.on("data", (c) => { down += c.length; });
414
+ back.pipe(res);
415
+ });
416
+ const finish = () => { if (done)
417
+ return; done = true; closed(session, host, port, a.id, started, up, down, a.tainted); };
418
+ req.on("data", (c) => { up += c.length; });
419
+ out.on("timeout", () => out.destroy(new Error("timeout")));
420
+ out.on("error", () => { if (!res.headersSent)
421
+ send(502, `AcePaste Ingress egress proxy: could not reach ${host}:${port}.\n`);
422
+ else
423
+ res.destroy(); finish(); });
424
+ res.on("close", finish);
425
+ req.pipe(out);
426
+ }
427
+ return new Promise((ok, fail) => {
428
+ server.once("error", fail);
429
+ server.listen(o.port ?? EGRESS_PROXY_PORT, "127.0.0.1", () => {
430
+ const addr = server.address();
431
+ const port = typeof addr === "object" && addr ? addr.port : o.port ?? EGRESS_PROXY_PORT;
432
+ try {
433
+ writeAtomic(join(proxyDir(dir), "proxy.json"), JSON.stringify({ port, pid: process.pid, since }));
434
+ }
435
+ catch { /* informational */ }
436
+ let idle;
437
+ if (o.idleExitMs) {
438
+ idle = setInterval(() => { if (now() - lastUse > o.idleExitMs)
439
+ o.onIdle?.(); }, 60_000);
440
+ idle.unref();
441
+ }
442
+ ok({ port, server, close: () => new Promise((done) => { if (idle)
443
+ clearInterval(idle); server.closeAllConnections?.(); server.close(() => done()); }) });
444
+ });
445
+ });
446
+ }
447
+ /** Options from the environment, shared by `ingress egress-proxy` and the HTTP service. */
448
+ export function egressProxyOptionsFromEnv(env = process.env) {
449
+ const list = (v) => (v ?? "").split(",").map((s) => s.trim()).filter(Boolean);
450
+ const port = Number(env.INGRESS_EGRESS_PROXY_PORT);
451
+ const flag = Number(env.INGRESS_EGRESS_UPLOAD_FLAG_BYTES);
452
+ return {
453
+ port: Number.isInteger(port) && port > 0 && port < 65536 ? port : EGRESS_PROXY_PORT,
454
+ policy: {
455
+ mode: env.INGRESS_EGRESS_PROXY_MODE === "strict" ? "strict" : "log",
456
+ allowHosts: list(env.INGRESS_EGRESS_ALLOW_HOSTS),
457
+ allowPrivate: list(env.INGRESS_EGRESS_PROXY_ALLOW_PRIVATE),
458
+ ports: list(env.INGRESS_EGRESS_PROXY_PORTS).map(Number).filter((n) => Number.isInteger(n) && n > 0 && n < 65536),
459
+ ...(Number.isFinite(flag) && flag > 0 ? { uploadFlagBytes: flag } : {}),
460
+ },
461
+ };
462
+ }
463
+ export const egressProxyOn = (env = process.env) => /^(on|1|true|yes)$/i.test(env.INGRESS_EGRESS_PROXY ?? "");
464
+ // ---------- is it running; start it ----------
465
+ /** Is our proxy (one that holds this state folder's secret) listening on the port? */
466
+ export async function proxyHealth(port, dir = stateDir(), timeoutMs = 800) {
467
+ const c = randomBytes(8).toString("hex");
468
+ try {
469
+ const res = await fetch(`http://127.0.0.1:${port}${HEALTH_PATH}?c=${c}`, { signal: AbortSignal.timeout(timeoutMs) });
470
+ const body = (await res.json().catch(() => undefined));
471
+ return body?.proof === hmac(proxySecret(dir), `health:${c}`) ? "ours" : "other";
472
+ }
473
+ catch {
474
+ // no answer to the question: is anything listening at all?
475
+ return new Promise((done) => {
476
+ const s = netConnect({ host: "127.0.0.1", port });
477
+ const say = (v) => { s.destroy(); done(v); };
478
+ s.setTimeout(timeoutMs, () => say("other"));
479
+ s.once("connect", () => say("other"));
480
+ s.once("error", () => say("down"));
481
+ });
482
+ }
483
+ }
484
+ /**
485
+ * Make sure the proxy is listening, starting `ingress egress-proxy` as a detached process when it is not.
486
+ * Never throws. "other": something else has the port, and nothing was started.
487
+ */
488
+ export async function ensureEgressProxy(o = {}) {
489
+ const port = o.port ?? EGRESS_PROXY_PORT, dir = o.dir ?? stateDir();
490
+ try {
491
+ const state = await proxyHealth(port, dir);
492
+ if (state === "ours")
493
+ return { ok: true };
494
+ if (state === "other")
495
+ return { ok: false, why: `port ${port} on this machine answers, but not as this installation's egress proxy` };
496
+ const cli = o.cli ?? process.argv[1];
497
+ if (!o.spawnImpl && (!cli || !existsSync(cli)))
498
+ return { ok: false, why: "the ingress command could not be found to start it" };
499
+ (o.spawnImpl ?? ((command, args) => { spawn(command, args, { detached: true, stdio: "ignore", env: { ...process.env, INGRESS_EGRESS_PROXY_PORT: String(port) } }).unref(); }))(process.execPath, [cli, "egress-proxy", "--idle-exit"]);
500
+ const until = Date.now() + (o.waitMs ?? 4000);
501
+ while (Date.now() < until) {
502
+ await new Promise((r) => setTimeout(r, 120));
503
+ if ((await proxyHealth(port, dir, 400)) === "ours")
504
+ return { ok: true };
505
+ }
506
+ return { ok: false, why: "it was started and did not answer in time" };
507
+ }
508
+ catch (e) {
509
+ return { ok: false, why: String(e.message ?? e) };
510
+ }
511
+ }
512
+ // ---------- the sandbox wrapper: programs that ignore proxy settings ----------
513
+ const SANDBOX_EXEC = "/usr/bin/sandbox-exec";
514
+ const sb = (s) => `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
515
+ const real = (p) => { try {
516
+ return realpathSync(p);
517
+ }
518
+ catch {
519
+ return p;
520
+ } };
521
+ /**
522
+ * A macOS sandbox profile (the language `sandbox-exec` reads): everything is allowed except the process's own
523
+ * outbound network, which may only reach the proxy.
524
+ * loopback "proxy-only" nothing but the proxy's port
525
+ * loopback "allow" other ports on this machine too (a test suite talking to its own server), except
526
+ * the name-service ports: a resolver listening on this machine would carry data out
527
+ * Name lookups through the system (which is how nearly every program resolves a name) go over a local socket
528
+ * to a system service; "deny network-outbound" covers that socket, so they fail. A program using the proxy
529
+ * does not need them: the proxy resolves. The files that would let a program speak for another session, or
530
+ * use the Ingress service as a relay, cannot be read.
531
+ */
532
+ export function sandboxProfile(o) {
533
+ const lines = ["(version 1)", "(allow default)", "(deny network-outbound)"];
534
+ if (o.loopback === "allow")
535
+ lines.push('(allow network-outbound (remote ip "localhost:*"))', ...[53, 853, 5353].filter((p) => p !== o.proxyPort).map((p) => `(deny network-outbound (remote ip "localhost:${p}"))`));
536
+ lines.push(`(allow network-outbound (remote ip "localhost:${o.proxyPort}"))`);
537
+ for (const p of o.denyRead ?? [])
538
+ lines.push(`(deny file-read* (literal ${sb(real(p))}))`);
539
+ return lines.join("\n") + "\n";
540
+ }
541
+ /** Files a sandboxed program must not read: the token secret, and the keys of the local Ingress service. */
542
+ export function sandboxSecrets(dir = stateDir()) {
543
+ const home = join(homedir(), ".acepaste-ingress");
544
+ return [join(proxyDir(dir), "secret"), join(home, "local-api-key"), join(home, "private.pem")];
545
+ }
546
+ /** Can this process start a sandbox? Not on other systems, and not from inside another sandbox. */
547
+ export function sandboxUsable() {
548
+ if (process.platform !== "darwin")
549
+ return { ok: false, why: "the sandbox wrapper is built for macOS only (sandbox-exec); nothing equivalent is built for this system" };
550
+ if (!existsSync(SANDBOX_EXEC))
551
+ return { ok: false, why: `${SANDBOX_EXEC} is not on this Mac` };
552
+ const r = spawnSync(SANDBOX_EXEC, ["-p", "(version 1)(allow default)", "/usr/bin/true"], { stdio: "ignore", timeout: 10_000 });
553
+ if (r.status !== 0)
554
+ return { ok: false, why: "this process cannot start a sandbox, which is what happens inside another sandbox (an agent harness's own sandbox mode, or an app sandbox). Run it outside that sandbox, or rely on that sandbox's own network rules" };
555
+ return { ok: true };
556
+ }
557
+ /**
558
+ * Run a command with its network confined to the proxy. Returns the command's exit status.
559
+ * The command inherits this process's terminal. Its children are confined too: a sandbox cannot be left.
560
+ */
561
+ export function runSandboxed(argv, o) {
562
+ const profile = sandboxProfile({ proxyPort: o.proxyPort, loopback: o.loopback, denyRead: sandboxSecrets(o.dir ?? stateDir()) });
563
+ const r = spawnSync(SANDBOX_EXEC, ["-p", profile, ...argv], { stdio: "inherit", env: { ...(o.env ?? process.env), ...proxyEnv(o.proxyPort, o.token) } });
564
+ if (r.error)
565
+ throw r.error;
566
+ return r.status ?? (r.signal ? 128 : 1);
567
+ }
@@ -14,6 +14,8 @@ import { type KeyObject } from "node:crypto";
14
14
  import { acquireWithBrowser, type FetchLike } from "./acquire.js";
15
15
  import { type VisionRunner } from "./image.js";
16
16
  import { type AudioRunner } from "./audio.js";
17
+ import { type VideoRunner, type AudioExtractor } from "./video.js";
18
+ import type { ScreenHints } from "./screen.js";
17
19
  import { servedWords, compareServed } from "./served.js";
18
20
  import { runSandbox } from "./sandbox.js";
19
21
  import { type ContentKind, type Finding, type IngressConfig, type IngressResult, type SourceInfo, type TaintReceipt, type Tier } from "./types.js";
@@ -107,7 +109,8 @@ export declare class IngressEngine {
107
109
  source?: SourceInfo; /** words shown beside the image: a caption, alt text, a file name */
108
110
  caption?: string; /** for a screenshot: the text the page's own source says is on it (see image.ts) */
109
111
  sourceText?: string; /** how to read the pixels (default: the vision helper when built); false reads the container only */
110
- vision?: VisionRunner | false;
112
+ vision?: VisionRunner | false; /** how the picture was taken, when known: a capture of a page's content area holds no real browser chrome (see screen.ts) */
113
+ screen?: ScreenHints;
111
114
  }): Promise<IngressResult>;
112
115
  /**
113
116
  * Gate a sound recording: what is said in it, and what is there only for a machine (see audio.ts).
@@ -119,6 +122,22 @@ export declare class IngressEngine {
119
122
  source?: SourceInfo; /** how to transcribe (default: the command in INGRESS_AUDIO_TRANSCRIBER); false reads the container only */
120
123
  transcriber?: AudioRunner | false;
121
124
  }): Promise<IngressResult>;
125
+ /**
126
+ * Gate a video: what is on screen and for how long, the codes in its frames, its subtitle tracks, its sound
127
+ * (when a transcriber is configured) and its tags (see video.ts). The delivered text is what a viewer can
128
+ * read on screen, the captions and the transcript. Whether the video itself goes on to the model is the
129
+ * caller's decision, made on the verdict. `coverage.video` says how much of it was read.
130
+ */
131
+ scanVideo(bytes: Uint8Array, opts?: IngressOptions & {
132
+ url?: string;
133
+ source?: SourceInfo; /** how to read the frames (default: the vision helper when built); false reads nothing from the picture */
134
+ video?: VideoRunner | false; /** how to transcribe the sound (default: INGRESS_AUDIO_TRANSCRIBER); false skips it */
135
+ transcriber?: AudioRunner | false;
136
+ extractAudio?: AudioExtractor; /** a captions file that came with the video */
137
+ captions?: string;
138
+ maxFrames?: number;
139
+ maxSeconds?: number;
140
+ }): Promise<IngressResult>;
122
141
  /**
123
142
  * Gate what the model will actually receive when several sources are combined (search
124
143
  * results, retrieved chunks, several tool results). An instruction can be split so each