@acepaste/ingress 0.9.24 → 0.9.26

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.
@@ -22,6 +22,8 @@
22
22
  * Everything that gates fails closed: if the gate cannot run, the content is withheld with the reason.
23
23
  */
24
24
  import { type BurstPolicy } from "./safeguards.js";
25
+ import { type Approver } from "./broker.js";
26
+ import { type ProxyConnection } from "./egress-proxy.js";
25
27
  import { Blocklist } from "./egress.js";
26
28
  import type { ContentKind, IngressResult, SourceInfo } from "./types.js";
27
29
  /** What a hook needs from Ingress: the engine in this process, or the local service over HTTP. */
@@ -58,6 +60,16 @@ export interface HookOptions {
58
60
  agent?: string;
59
61
  from?: string;
60
62
  } | undefined;
63
+ /**
64
+ * The egress proxy is on (INGRESS_EGRESS_PROXY=on): what it logged for a session since a shell command started.
65
+ * A command whose programs connected somewhere has outside content in its output, whatever the command looked like.
66
+ */
67
+ proxyConnections?: (session: string, toolUseId: string | undefined) => ProxyConnection[];
68
+ /** the egress proxy is on: its port, and the file the harness reads shell variables from (CLAUDE_ENV_FILE at session start) */
69
+ egressProxy?: {
70
+ port: number;
71
+ envFile?: string;
72
+ };
61
73
  }
62
74
  type Json = Record<string, unknown>;
63
75
  export declare function withheld(source: string, why: string): string;
@@ -107,6 +119,44 @@ export interface EgressHookOptions extends HookOptions {
107
119
  now?: () => number;
108
120
  }
109
121
  export declare function preToolUse(event: Json, o?: EgressHookOptions): Json | undefined;
122
+ /**
123
+ * The same decision, with every "ask" put to a person through `approver` before the hook answers
124
+ * (INGRESS_HOOK_APPROVER=macos-presence). The harness's "ask" is a prompt the harness may answer for the
125
+ * person: a mode that approves prompts automatically turns it into "allow". With an approver, the question
126
+ * goes to a channel the model cannot drive (the exact action in a system dialog, then Touch ID or the login
127
+ * password), and only then does the hook answer:
128
+ * approved nothing. The harness's own permission flow carries on as if this hook had no opinion.
129
+ * The hook never says "allow": a person's yes to this question is not a yes to the harness's.
130
+ * anything else (declined, nobody answered, the approver could not run) "deny", with the reason.
131
+ * The outcome is appended to the egress log beside the question (never the arguments).
132
+ *
133
+ * `answerWithinMs`: the hook answers "deny" itself when the person has not answered by then. It must be shorter
134
+ * than the timeout the harness gives the hook: a hook the harness has to kill has said nothing, and the
135
+ * harness would carry on without it.
136
+ */
137
+ export declare function preToolUseAnswered(event: Json, approver: Approver, o?: EgressHookOptions & {
138
+ answerWithinMs?: number;
139
+ }): Promise<Json | undefined>;
140
+ /**
141
+ * With the egress proxy on, what the pre-tool-use hook does for a shell command after the egress decision
142
+ * (`reply` is that decision's reply; undefined means the gate had no objection, or a person at the machine
143
+ * approved it through the approver):
144
+ * - records when the command started, so the hook that runs after it can ask the proxy what connected meanwhile
145
+ * - records the hosts the command names, when the gate had no objection: what the command starts may connect
146
+ * to them. A command that was refused or put to the harness's prompt grants nothing: a prompt can be
147
+ * declined, and a refused command must not open a door for the next one.
148
+ * - asks, when the command visibly steps around the proxy settings, or the proxy is not running and could
149
+ * not be started (`ensure`)
150
+ * It never rewrites the command. The session's commands were pointed at the proxy when the session started.
151
+ */
152
+ export declare function egressProxyBefore(event: Json, reply: Json | undefined, o: {
153
+ dir?: string;
154
+ now?: () => number;
155
+ ensure: () => Promise<{
156
+ ok: boolean;
157
+ why?: string;
158
+ }>;
159
+ }): Promise<Json | undefined>;
110
160
  /** A gate backed by the Ingress HTTP service, so its receipts and audit trail record what hooks gated. */
111
161
  export declare function remoteGate(base: string, key: string, timeoutMs?: number): HookGate;
112
162
  export {};
@@ -26,7 +26,8 @@ import { execFileSync } from "node:child_process";
26
26
  import { join } from "node:path";
27
27
  import { stateDir } from "./changes.js";
28
28
  import { stopReason, canaryNotice } from "./safeguards.js";
29
- import { ActionBroker } from "./broker.js";
29
+ import { ActionBroker, destinationsIn } from "./broker.js";
30
+ import { noteCommandStart, noteVisibleHosts, proxyEnv, proxySecret, sessionToken } from "./egress-proxy.js";
30
31
  import { Blocklist } from "./egress.js";
31
32
  import { scanCharacters } from "./character.js";
32
33
  import { shellOutputSource, shellWrites, shellUploads } from "./shell-commands.js";
@@ -88,7 +89,21 @@ async function postToolUseInner(event, gate, o, seen) {
88
89
  const isMcp = name.startsWith("mcp__") && !gated.some((s) => name.startsWith(`mcp__${s}__`));
89
90
  const emit = (out) => ({ hookSpecificOutput: { hookEventName: "PostToolUse", ...out } });
90
91
  const cwd = typeof event.cwd === "string" ? event.cwd : undefined;
91
- const bashSource = name === "Bash" ? shellOutputSource(String(input.command ?? ""), { cwd, ownPort: o.ownPort }) : undefined;
92
+ // What the egress proxy saw this command's programs do. A program that connected somewhere brought outside
93
+ // content back, whether or not the command looked like a network command.
94
+ let viaProxy = [];
95
+ if (name === "Bash" && obj && o.proxyConnections) {
96
+ try {
97
+ viaProxy = o.proxyConnections(String(event.session_id ?? ""), typeof event.tool_use_id === "string" ? event.tool_use_id : undefined);
98
+ }
99
+ catch { /* the proxy's log is extra knowledge */ }
100
+ }
101
+ const carried = [...new Set(viaProxy.filter((c) => c.decision === "allow").map((c) => c.host))];
102
+ const proxyNote = proxyNotes(viaProxy);
103
+ const bashSource = name !== "Bash" ? undefined
104
+ : shellOutputSource(String(input.command ?? ""), { cwd, ownPort: o.ownPort })
105
+ ?? (carried.length ? `shell:a program that connected to ${carried.slice(0, 3).join(", ")}${carried.length > 3 ? ` and ${carried.length - 3} more` : ""}` : undefined);
106
+ const noted = (out) => (!proxyNote ? out : { hookSpecificOutput: { hookEventName: "PostToolUse", ...(out?.hookSpecificOutput ?? {}), additionalContext: proxyNote } });
92
107
  try {
93
108
  if (name === "WebFetch" && obj) {
94
109
  const url = String(input.url ?? "");
@@ -123,11 +138,16 @@ async function postToolUseInner(event, gate, o, seen) {
123
138
  // command output is terminal output: read as a terminal would show it, at open-channel trust
124
139
  const text = out + (err ? `\n--- stderr ---\n${err}` : "");
125
140
  seen.push({ ref: bashSource });
141
+ for (const h of carried)
142
+ seen.push({ ref: bashSource, host: h }); // where its programs really went joins what the session has contacted
126
143
  const env = await refusal(gate, text, bashSource, { kind: "log", source: { channel: "shell command output", trust: 5 } });
127
144
  if (!env)
128
145
  seen.push({ ref: bashSource, text });
129
- return env ? emit({ updatedToolOutput: { ...obj, stdout: env, stderr: "" } }) : undefined;
146
+ return noted(env ? emit({ updatedToolOutput: { ...obj, stdout: env, stderr: "" } }) : undefined);
130
147
  }
148
+ // nothing came back through the proxy, but it refused something: the model is told why its command failed
149
+ if (name === "Bash" && proxyNote)
150
+ return noted(undefined);
131
151
  if (name === "Read" && obj && isTaskOutput(String(input.file_path ?? ""))) {
132
152
  const f = obj.file;
133
153
  if (!f || typeof f.content !== "string")
@@ -253,6 +273,19 @@ async function postToolUseInner(event, gate, o, seen) {
253
273
  }
254
274
  return undefined;
255
275
  }
276
+ /** What the model is told about connections the egress proxy refused or flagged while a command ran. */
277
+ function proxyNotes(conns) {
278
+ const refused = [...new Map(conns.filter((c) => c.decision === "refuse").map((c) => [`${c.host}:${c.port}`, c])).values()];
279
+ const flags = [...new Set(conns.map((c) => c.flag).filter((f) => typeof f === "string"))];
280
+ if (!refused.length && !flags.length)
281
+ return undefined;
282
+ const parts = [];
283
+ if (refused.length)
284
+ parts.push(`AcePaste Ingress's egress proxy refused ${refused.length === 1 ? "a connection" : `${refused.length} connections`} a program started by this command tried to make: ${refused.slice(0, 4).map((c) => `${c.host}:${c.port} (${c.reason})`).join("; ")}. That is a refusal, not a fault: do not unset the proxy settings or reach the destination another way. Tell the person, who can name the host in their own words or put it on the allowlist.`);
285
+ if (flags.length)
286
+ parts.push(`AcePaste Ingress's egress proxy flagged this command: ${flags.slice(0, 4).join("; ")}. Tell the person.`);
287
+ return parts.join("\n");
288
+ }
256
289
  // ---------- UserPromptSubmit: the paste gate ----------
257
290
  const PASTED = /<pasted_content id="([^"]*)">\n?([\s\S]*?)\n?<\/pasted_content id="\1">/g;
258
291
  /** a person typing this, outside any pasted block, sends the prompt as it is */
@@ -407,6 +440,20 @@ export function sessionStart(event, o = {}) {
407
440
  }
408
441
  catch { /* without a marker the other checks still run */ }
409
442
  }
443
+ // the egress proxy: this session's shell commands are pointed at it, with a token that says whose they are
444
+ if (session && o.egressProxy) {
445
+ try {
446
+ const vars = proxyEnv(o.egressProxy.port, sessionToken(proxySecret(dir), session));
447
+ if (o.egressProxy.envFile) {
448
+ appendFileSync(o.egressProxy.envFile, Object.entries(vars).map(([k, v]) => `export ${k}='${v}'`).join("\n") + "\n");
449
+ notes.push(`Network connections made by shell commands in this session go through AcePaste Ingress's egress proxy on this machine (127.0.0.1:${o.egressProxy.port}), which decides each one by its destination. A connection it refuses fails with "403" from the proxy and the reason. That is a refusal: do not unset the proxy variables or reach the destination another way. Tell the person.`);
450
+ }
451
+ else {
452
+ notes.push("AcePaste Ingress's egress proxy is turned on, but this harness gave the session-start hook no environment file (CLAUDE_ENV_FILE), so this session's shell commands are not routed through it.");
453
+ }
454
+ }
455
+ catch { /* the other hooks still run */ }
456
+ }
410
457
  return notes.length ? { hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: notes.join("\n\n") } } : undefined;
411
458
  }
412
459
  // ---------- what the session has read, carried between hook calls ----------
@@ -471,6 +518,101 @@ function asAction(name, input) {
471
518
  return undefined;
472
519
  }
473
520
  export function preToolUse(event, o = {}) {
521
+ return decideEgress(event, o)?.reply;
522
+ }
523
+ /**
524
+ * The same decision, with every "ask" put to a person through `approver` before the hook answers
525
+ * (INGRESS_HOOK_APPROVER=macos-presence). The harness's "ask" is a prompt the harness may answer for the
526
+ * person: a mode that approves prompts automatically turns it into "allow". With an approver, the question
527
+ * goes to a channel the model cannot drive (the exact action in a system dialog, then Touch ID or the login
528
+ * password), and only then does the hook answer:
529
+ * approved nothing. The harness's own permission flow carries on as if this hook had no opinion.
530
+ * The hook never says "allow": a person's yes to this question is not a yes to the harness's.
531
+ * anything else (declined, nobody answered, the approver could not run) "deny", with the reason.
532
+ * The outcome is appended to the egress log beside the question (never the arguments).
533
+ *
534
+ * `answerWithinMs`: the hook answers "deny" itself when the person has not answered by then. It must be shorter
535
+ * than the timeout the harness gives the hook: a hook the harness has to kill has said nothing, and the
536
+ * harness would carry on without it.
537
+ */
538
+ export async function preToolUseAnswered(event, approver, o = {}) {
539
+ const d = decideEgress(event, o);
540
+ if (!d?.ask)
541
+ return d?.reply;
542
+ let answer;
543
+ let timer;
544
+ try {
545
+ const asked = approver.request(d.ask);
546
+ answer = o.answerWithinMs === undefined ? await asked : await Promise.race([asked, new Promise((resolve) => { timer = setTimeout(() => resolve("timeout"), o.answerWithinMs); })]);
547
+ }
548
+ catch {
549
+ answer = "unavailable";
550
+ }
551
+ finally {
552
+ if (timer)
553
+ clearTimeout(timer);
554
+ }
555
+ if (answer !== "approved" && answer !== "denied" && answer !== "timeout")
556
+ answer = "unavailable";
557
+ try {
558
+ appendFileSync(join(d.dir, "egress-log.jsonl"), JSON.stringify({ at: new Date(o.now?.() ?? Date.now()).toISOString(), session: d.ask.runId, tool: d.ask.tool, decision: "ask", answer, approver: approver.name, action: d.ask.digest }) + "\n", { mode: 0o600 });
559
+ }
560
+ catch { /* the answer stands whether or not it could be recorded */ }
561
+ if (answer === "approved")
562
+ return undefined;
563
+ const how = answer === "denied" ? "A person at this machine was asked and declined" : answer === "timeout" ? "A person at this machine was asked and did not answer" : `It needs a person at this machine to confirm it, and the approval prompt (${approver.name}) could not be shown`;
564
+ return { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: `AcePaste Ingress: ${d.ask.reasons.join("; ")}. ${how}. This is refused; do not try another route. Tell the person what you wanted to do.` } };
565
+ }
566
+ /** visible ways a command steps around the proxy settings its session was given */
567
+ const PROXY_TAMPER = /(?:^|[\s;&|(])(?:unset\s+(?:-\w+\s+)*(?:https?_proxy|all_proxy|no_proxy|node_use_env_proxy)\b|(?:export\s+)?(?:https?_proxy|all_proxy|no_proxy|node_use_env_proxy)=|env\s+(?:-\w+\s+)*-u\s*(?:https?_proxy|all_proxy)\b)|\s--no-?proxy\b|\s--proxy(?:-server)?[=\s]|\bhttps?\.proxy=/i;
568
+ /**
569
+ * With the egress proxy on, what the pre-tool-use hook does for a shell command after the egress decision
570
+ * (`reply` is that decision's reply; undefined means the gate had no objection, or a person at the machine
571
+ * approved it through the approver):
572
+ * - records when the command started, so the hook that runs after it can ask the proxy what connected meanwhile
573
+ * - records the hosts the command names, when the gate had no objection: what the command starts may connect
574
+ * to them. A command that was refused or put to the harness's prompt grants nothing: a prompt can be
575
+ * declined, and a refused command must not open a door for the next one.
576
+ * - asks, when the command visibly steps around the proxy settings, or the proxy is not running and could
577
+ * not be started (`ensure`)
578
+ * It never rewrites the command. The session's commands were pointed at the proxy when the session started.
579
+ */
580
+ export async function egressProxyBefore(event, reply, o) {
581
+ if (String(event.tool_name ?? "") !== "Bash")
582
+ return reply;
583
+ const session = String(event.session_id ?? "");
584
+ if (!session)
585
+ return reply;
586
+ const decided = (reply?.hookSpecificOutput?.permissionDecision ?? "");
587
+ if (decided === "deny")
588
+ return reply;
589
+ const dir = o.dir ?? stateDir(), now = o.now?.() ?? Date.now();
590
+ const command = String((event.tool_input ?? {}).command ?? "");
591
+ try {
592
+ noteCommandStart(dir, session, typeof event.tool_use_id === "string" ? event.tool_use_id : "", now);
593
+ }
594
+ catch { /* best effort */ }
595
+ if (reply !== undefined)
596
+ return reply; // already a question: it stands, and grants nothing
597
+ try {
598
+ noteVisibleHosts(dir, session, destinationsIn({ command }).hosts, now);
599
+ }
600
+ catch { /* best effort */ }
601
+ const ask = (why) => {
602
+ try {
603
+ appendFileSync(join(dir, "egress-log.jsonl"), JSON.stringify({ at: new Date(now).toISOString(), session, tool: "Bash", decision: "ask", reasons: [why] }) + "\n", { mode: 0o600 });
604
+ }
605
+ catch { /* the question stands */ }
606
+ return { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "ask", permissionDecisionReason: `AcePaste Ingress: ${why}.` } };
607
+ };
608
+ if (PROXY_TAMPER.test(command))
609
+ return ask("this command changes or steps around the proxy settings that send its network calls through the egress proxy");
610
+ const up = await o.ensure();
611
+ if (!up.ok)
612
+ return ask(`the egress proxy is not running (${up.why ?? "unknown reason"}), so this command's network calls would fail or go unchecked`);
613
+ return undefined;
614
+ }
615
+ function decideEgress(event, o) {
474
616
  const name = String(event.tool_name ?? "");
475
617
  const action = asAction(name, (event.tool_input ?? {}));
476
618
  const session = String(event.session_id ?? "");
@@ -500,14 +642,21 @@ export function preToolUse(event, o = {}) {
500
642
  }
501
643
  const say = (permissionDecision) => ({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision, permissionDecisionReason: `AcePaste Ingress: ${c.reasons.join("; ")}.${permissionDecision === "deny" ? " This is refused, not a question; do not try another route. Tell the person what you wanted to do." : ""}` } });
502
644
  if (c.decision === "deny")
503
- return say("deny");
645
+ return { reply: say("deny"), dir };
504
646
  // counted as having run: if the person declines at the prompt the count is one too high, which errs toward asking
647
+ let sources = [];
505
648
  try {
506
649
  broker.noteRan({ runId: session, tool: action.tool, args: action.args });
507
- saveRun(dir, session, broker.exportRun(session));
650
+ const run = broker.exportRun(session);
651
+ sources = run.sources;
652
+ saveRun(dir, session, run);
508
653
  }
509
654
  catch { /* best effort */ }
510
- return c.decision === "require_approval" ? say("ask") : undefined;
655
+ if (c.decision !== "require_approval")
656
+ return { reply: undefined, dir };
657
+ // what a person would be shown if the question goes to them directly: the harness's tool name and exactly what will run
658
+ const ask = { id: c.digest.slice(0, 16), runId: session, tool: name, canonicalArgs: c.canonicalArgs, digest: c.digest, reasons: c.reasons, destinations: c.destinations, fields: c.fields, sources, createdAt: o.now?.() ?? Date.now(), expiresAt: (o.now?.() ?? Date.now()) + 300_000 };
659
+ return { reply: say("ask"), ask, dir };
511
660
  }
512
661
  // ---------- a gate that talks to the local service ----------
513
662
  /** A gate backed by the Ingress HTTP service, so its receipts and audit trail record what hooks gated. */
@@ -0,0 +1,57 @@
1
+ /**
2
+ * Keeping the blocklists current.
3
+ *
4
+ * `ingress blocklist update` downloads the free lists. Until 0.9.25 a person had to run it, so an installed
5
+ * gate had an empty list on its first day and a stale one a month later. Now the lists refresh themselves:
6
+ * when the newest downloaded list is more than a day old (or there is none), the session-start hook, the HTTP
7
+ * service and the MCP proxy start the same command as a separate, detached process and carry on. Nothing waits
8
+ * for it and nothing fails because of it. INGRESS_BLOCKLIST_AUTO=off turns that off.
9
+ *
10
+ * Only the addresses in BLOCKLIST_FEEDS are contacted. A download is kept only if it parses as a list: a block
11
+ * page or an error page saved as a list would silently protect nothing.
12
+ */
13
+ import { BLOCKLIST_FEEDS } from "./egress.js";
14
+ /** lists older than this are refreshed */
15
+ export declare const BLOCKLIST_MAX_AGE_MS: number;
16
+ /** after an attempt, nothing tries again for this long: several sessions starting together refresh once, and a machine without a network does not retry at every session */
17
+ export declare const BLOCKLIST_RETRY_MS: number;
18
+ type Feed = (typeof BLOCKLIST_FEEDS)[number];
19
+ type FetchText = (url: string) => Promise<{
20
+ ok: boolean;
21
+ status: number;
22
+ text: string;
23
+ }>;
24
+ export interface FeedOutcome {
25
+ name: string;
26
+ what: string;
27
+ entries?: number;
28
+ error?: string;
29
+ }
30
+ /** Download each feed into `dir`. A feed that fails, or does not parse as a list, leaves the previous copy in place. */
31
+ export declare function updateBlocklists(dir?: string, o?: {
32
+ feeds?: readonly Feed[];
33
+ fetchText?: FetchText;
34
+ now?: () => number;
35
+ }): Promise<FeedOutcome[]>;
36
+ /** When the newest downloaded list was written, or undefined when none has been. Lists a person added do not count. */
37
+ export declare function blocklistsRefreshedAt(dir?: string, feeds?: readonly Feed[]): number | undefined;
38
+ export declare function blocklistRefreshDue(dir: string, now: number, feeds?: readonly Feed[]): boolean;
39
+ /**
40
+ * One refresh at a time, and not more often than BLOCKLIST_RETRY_MS: the file is created exclusively, so of
41
+ * several processes that find the lists stale at the same moment exactly one gets it. It is never removed; its
42
+ * age is the time since the last attempt.
43
+ */
44
+ export declare function claimBlocklistRefresh(dir: string, now: number): boolean;
45
+ export type RefreshStart = "started" | "off" | "fresh" | "recently-tried" | "failed";
46
+ /**
47
+ * Start `ingress blocklist update --quiet` as a detached process if the lists are due. Returns at once, and
48
+ * never throws: a refresh that cannot start leaves the lists as they were.
49
+ */
50
+ export declare function startBlocklistRefresh(o?: {
51
+ dir?: string;
52
+ env?: Record<string, string | undefined>;
53
+ now?: () => number;
54
+ cli?: string;
55
+ spawnImpl?: (command: string, args: string[]) => void;
56
+ }): RefreshStart;
57
+ export {};
@@ -0,0 +1,133 @@
1
+ /**
2
+ * Keeping the blocklists current.
3
+ *
4
+ * `ingress blocklist update` downloads the free lists. Until 0.9.25 a person had to run it, so an installed
5
+ * gate had an empty list on its first day and a stale one a month later. Now the lists refresh themselves:
6
+ * when the newest downloaded list is more than a day old (or there is none), the session-start hook, the HTTP
7
+ * service and the MCP proxy start the same command as a separate, detached process and carry on. Nothing waits
8
+ * for it and nothing fails because of it. INGRESS_BLOCKLIST_AUTO=off turns that off.
9
+ *
10
+ * Only the addresses in BLOCKLIST_FEEDS are contacted. A download is kept only if it parses as a list: a block
11
+ * page or an error page saved as a list would silently protect nothing.
12
+ */
13
+ import { spawn } from "node:child_process";
14
+ import { existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
15
+ import { join } from "node:path";
16
+ import { fileURLToPath } from "node:url";
17
+ import { HONEST_USER_AGENT } from "./acquire.js";
18
+ import { stateDir } from "./changes.js";
19
+ import { Blocklist, BLOCKLIST_FEEDS } from "./egress.js";
20
+ /** lists older than this are refreshed */
21
+ export const BLOCKLIST_MAX_AGE_MS = 24 * 3600 * 1000;
22
+ /** after an attempt, nothing tries again for this long: several sessions starting together refresh once, and a machine without a network does not retry at every session */
23
+ export const BLOCKLIST_RETRY_MS = 3600 * 1000;
24
+ const defaultFetch = async (url) => {
25
+ const res = await fetch(url, { signal: AbortSignal.timeout(30_000), redirect: "follow", headers: { "user-agent": HONEST_USER_AGENT } });
26
+ return { ok: res.ok, status: res.status, text: res.ok ? await res.text() : "" };
27
+ };
28
+ /** Download each feed into `dir`. A feed that fails, or does not parse as a list, leaves the previous copy in place. */
29
+ export async function updateBlocklists(dir = join(stateDir(), "blocklists"), o = {}) {
30
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
31
+ const out = [];
32
+ for (const f of o.feeds ?? BLOCKLIST_FEEDS) {
33
+ try {
34
+ const res = await (o.fetchText ?? defaultFetch)(f.url);
35
+ if (!res.ok)
36
+ throw new Error(`HTTP ${res.status}`);
37
+ if (res.text.length > 50_000_000)
38
+ throw new Error("larger than 50 MB");
39
+ const n = new Blocklist().add(res.text, f.name);
40
+ if (n < 5)
41
+ throw new Error(`only ${n} entries parsed; keeping the previous copy`);
42
+ const p = join(dir, `${f.name}.txt`);
43
+ writeFileSync(`${p}.tmp`, `# ${f.what}\n# from ${f.url} on ${new Date(o.now?.() ?? Date.now()).toISOString()} (${f.terms})\n${res.text}`, { mode: 0o600 });
44
+ renameSync(`${p}.tmp`, p);
45
+ out.push({ name: f.name, what: f.what, entries: n });
46
+ }
47
+ catch (e) {
48
+ out.push({ name: f.name, what: f.what, error: e.message ?? String(e) });
49
+ }
50
+ }
51
+ return out;
52
+ }
53
+ /** When the newest downloaded list was written, or undefined when none has been. Lists a person added do not count. */
54
+ export function blocklistsRefreshedAt(dir = join(stateDir(), "blocklists"), feeds = BLOCKLIST_FEEDS) {
55
+ let newest;
56
+ for (const f of feeds) {
57
+ try {
58
+ const t = statSync(join(dir, `${f.name}.txt`)).mtimeMs;
59
+ if (newest === undefined || t > newest)
60
+ newest = t;
61
+ }
62
+ catch { /* not downloaded yet */ }
63
+ }
64
+ return newest;
65
+ }
66
+ export function blocklistRefreshDue(dir, now, feeds = BLOCKLIST_FEEDS) {
67
+ const at = blocklistsRefreshedAt(dir, feeds);
68
+ return at === undefined || now - at > BLOCKLIST_MAX_AGE_MS;
69
+ }
70
+ /**
71
+ * One refresh at a time, and not more often than BLOCKLIST_RETRY_MS: the file is created exclusively, so of
72
+ * several processes that find the lists stale at the same moment exactly one gets it. It is never removed; its
73
+ * age is the time since the last attempt.
74
+ */
75
+ export function claimBlocklistRefresh(dir, now) {
76
+ const lock = join(dir, ".refresh-attempt");
77
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
78
+ for (let i = 0; i < 2; i++) {
79
+ try {
80
+ writeFileSync(lock, `${new Date(now).toISOString()} pid ${process.pid}\n`, { flag: "wx", mode: 0o600 });
81
+ return true;
82
+ }
83
+ catch {
84
+ let at;
85
+ try {
86
+ at = Date.parse(readFileSync(lock, "utf8").split(" ")[0]);
87
+ }
88
+ catch {
89
+ return false;
90
+ }
91
+ // an unreadable stamp is treated as old: better one extra download than never refreshing again
92
+ if (Number.isFinite(at) && now - at < BLOCKLIST_RETRY_MS)
93
+ return false;
94
+ try {
95
+ unlinkSync(lock);
96
+ }
97
+ catch {
98
+ return false;
99
+ }
100
+ }
101
+ }
102
+ return false;
103
+ }
104
+ /**
105
+ * Start `ingress blocklist update --quiet` as a detached process if the lists are due. Returns at once, and
106
+ * never throws: a refresh that cannot start leaves the lists as they were.
107
+ */
108
+ export function startBlocklistRefresh(o = {}) {
109
+ try {
110
+ const env = o.env ?? process.env;
111
+ if (/^(off|0|false|no)$/i.test(env.INGRESS_BLOCKLIST_AUTO ?? ""))
112
+ return "off";
113
+ const dir = o.dir ?? join(stateDir(), "blocklists");
114
+ const now = o.now?.() ?? Date.now();
115
+ if (!blocklistRefreshDue(dir, now))
116
+ return "fresh";
117
+ if (!claimBlocklistRefresh(dir, now))
118
+ return "recently-tried";
119
+ const cli = o.cli ?? fileURLToPath(new URL("./cli.js", import.meta.url));
120
+ if (!o.spawnImpl && !existsSync(cli))
121
+ return "failed";
122
+ const run = o.spawnImpl ?? ((command, args) => {
123
+ const child = spawn(command, args, { detached: true, stdio: "ignore", env: { ...process.env, INGRESS_BLOCKLIST_AUTO: "off" } });
124
+ child.on("error", () => { });
125
+ child.unref();
126
+ });
127
+ run(process.execPath, [cli, "blocklist", "update", "--quiet"]);
128
+ return "started";
129
+ }
130
+ catch {
131
+ return "failed";
132
+ }
133
+ }
@@ -243,6 +243,18 @@ export declare class ActionBroker {
243
243
  sources: string[];
244
244
  quarantined: string[];
245
245
  };
246
+ /**
247
+ * What this run knows about one destination, for something that sees a connection rather than an action
248
+ * (the egress proxy): is it on the allowlist, did the person name it, and did it first appear in outside
249
+ * content (and where). The same facts `classify` judges an action's destinations with.
250
+ */
251
+ hostStanding(runId: string, host: string): {
252
+ allowed: boolean;
253
+ typed: boolean;
254
+ fromContent?: string;
255
+ tainted: boolean;
256
+ heardPerson: boolean;
257
+ };
246
258
  /** decide without asking anyone (for previews and tests) */
247
259
  classify(action: ProposedAction): {
248
260
  decision: ActionDecision;
@@ -345,6 +345,16 @@ export class ActionBroker {
345
345
  const r = this.run(runId);
346
346
  return { tainted: r.sources.size > 0, sources: [...r.sources], quarantined: [...r.quarantined] };
347
347
  }
348
+ /**
349
+ * What this run knows about one destination, for something that sees a connection rather than an action
350
+ * (the egress proxy): is it on the allowlist, did the person name it, and did it first appear in outside
351
+ * content (and where). The same facts `classify` judges an action's destinations with.
352
+ */
353
+ hostStanding(runId, host) {
354
+ const r = this.run(runId);
355
+ const h = host.toLowerCase().replace(/^\[|\]$/g, "").replace(/\.$/, "");
356
+ return { allowed: hostAllowed(h, this.policy.allowHosts), typed: typedBy(r, h), fromContent: metIn(r, h), tainted: r.sources.size > 0, heardPerson: r.heardPerson };
357
+ }
348
358
  /** decide without asking anyone (for previews and tests) */
349
359
  classify(action) {
350
360
  const r = this.run(action.runId);