@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,199 @@
1
+ /**
2
+ * Safeguards the broker applies to every proposed action, whatever the run has read.
3
+ *
4
+ * These exist for the agent as much as for the person: an agent that has been steered by something it
5
+ * read cannot tell from the inside. Each check here is something the agent would want between itself and
6
+ * the world.
7
+ *
8
+ * persistence An action that creates something which acts later (a scheduled job, an automation, a
9
+ * mail rule, a login item, a hook, an edit to the agent's own instructions or memory)
10
+ * turns one bad moment into a standing one. It always needs a person.
11
+ * canary A marker placed in the run's context that has no reason to leave it. If it shows up in
12
+ * an outbound argument, the context itself is being sent somewhere: refuse.
13
+ * burst Many side effects in a short time, or the same one over and over, is a loop or a
14
+ * mass-send. Hold it for a person.
15
+ * stop One file a person can create to make every action wait until they remove it.
16
+ */
17
+ import { createHash, randomBytes } from "node:crypto";
18
+ import { existsSync, readFileSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
19
+ import { dirname, join } from "node:path";
20
+ import { stateDir } from "./changes.js";
21
+ /** words in a tool's own name that mean it creates or changes something that acts later */
22
+ const PERSISTENCE_TOOL_WORDS = [
23
+ [/\b(cron|crontab|schedule[drs]?|scheduler|timer|recurring|launchd|launch ?agent|systemd)\b/, "scheduled-job", "it schedules something to run later"],
24
+ [/\b(automation|automations|workflow|workflows|zap|zaps|scenario|recipe|applet|blueprint|shortcut|shortcuts|trigger|triggers)\b/, "automation", "it creates or changes an automation"],
25
+ [/\b(filter|filters|forward|forwarding|auto ?forward|redirect|inbox ?rule|mail ?rule|rule|rules|vacation|auto ?reply|autoresponder|delegate|delegation)\b/, "mail-rule", "it creates or changes a rule that handles messages without you"],
26
+ [/\b(webhook|webhooks|subscription|subscriptions|callback ?url)\b/, "webhook", "it registers an address that will be called later"],
27
+ [/\b(login ?item|startup|autostart|boot)\b/, "startup-item", "it sets something to start automatically"],
28
+ [/\b(hook|hooks)\b/, "hook", "it installs a hook that runs on later events"],
29
+ [/\b(memory|memories|instruction|instructions|system ?prompt|rules ?file|persona)\b/, "agent-instructions", "it writes to what an agent will read as its own instructions or memory"],
30
+ ];
31
+ /** only tools that write count: reading a schedule or listing rules is not persistence */
32
+ const WRITE_WORDS = /\b(create|add|new|set|update|edit|write|save|put|insert|enable|install|register|upsert|modify|change|patch|append|schedule|import|make|configure)\b/;
33
+ /** paths whose contents run, or steer an agent, later */
34
+ const PERSISTENCE_PATHS = [
35
+ [/(?:^|[/\\])Library[/\\]Launch(?:Agents|Daemons)[/\\]|[/\\]etc[/\\]systemd[/\\]|[/\\]\.config[/\\]systemd[/\\]|[/\\]etc[/\\]init\.d[/\\]|\.(?:timer|service)\b(?=["'\s]|$)/i, "scheduled-job", "a launch agent, daemon or systemd unit"],
36
+ [/[/\\]etc[/\\]cron|[/\\]var[/\\]spool[/\\]cron|[/\\]etc[/\\]crontab\b|[/\\]etc[/\\]periodic[/\\]/i, "scheduled-job", "a cron table"],
37
+ [/(?:^|[/\\])\.(?:bashrc|bash_profile|bash_login|profile|zshrc|zshenv|zprofile|zlogin|config[/\\]fish[/\\]config\.fish)\b|[/\\]etc[/\\](?:profile|zshrc|bashrc|paths)\b/i, "startup-item", "a shell startup file, which runs in every new terminal"],
38
+ [/[/\\](?:Startup|StartupItems|LoginItems|autostart)[/\\]|com\.apple\.loginitems|backgrounditems\.btm/i, "startup-item", "a login or startup item"],
39
+ [/(?:^|[/\\])\.git[/\\]hooks[/\\]|(?:^|[/\\])\.husky[/\\]|(?:^|[/\\])\.claude[/\\]settings(?:\.local)?\.json|(?:^|[/\\])\.claude[/\\]hooks[/\\]/i, "hook", "a hook that runs on later events"],
40
+ [/(?:^|[/\\])(?:CLAUDE|AGENTS|GEMINI|COPILOT)\.md\b|(?:^|[/\\])\.cursorrules\b|(?:^|[/\\])\.cursor[/\\]rules[/\\]|(?:^|[/\\])\.github[/\\]copilot-instructions\.md|(?:^|[/\\])\.claude[/\\](?:commands|agents|skills)[/\\]|[/\\]memory[/\\][^/\\]+\.md\b|(?:^|[/\\])MEMORY\.md\b|global_rules\.md\b/i, "agent-instructions", "a file agents read as their own instructions or memory"],
41
+ [/(?:^|[/\\])\.mcp\.json\b|claude_desktop_config\.json|(?:^|[/\\])\.claude\.json\b|[/\\]\.cursor[/\\]mcp\.json|mcp_config\.json/i, "agent-config", "an agent's list of tool servers"],
42
+ [/(?:^|[/\\])\.ssh[/\\]authorized_keys|(?:^|[/\\])\.ssh[/\\]config\b|[/\\]etc[/\\]sudoers|[/\\]etc[/\\]ssh[/\\]sshd_config/i, "remote-access", "a file that decides who can log in or act as an administrator"],
43
+ [/[/\\]Library[/\\](?:Shortcuts|Services|Workflows)[/\\]|\.shortcut\b|[/\\]Folder Action Scripts[/\\]/i, "automation", "a shortcut, service or folder action"],
44
+ ];
45
+ /** shell commands that create something which runs later */
46
+ const PERSISTENCE_COMMANDS = [
47
+ [/\bcrontab\s+(?!-l\b)\S|\bat\s+(?:now|\d|midnight|noon|tomorrow)\b|\bschtasks\b[^\n]*\/create\b|\bsystemctl\s+(?:--user\s+)?(?:enable|link)\b|\bsystemd-run\b[^\n]*--on-/i, "scheduled-job", "a command that schedules something to run later"],
48
+ [/\blaunchctl\s+(?:load|bootstrap|enable|submit)\b/i, "scheduled-job", "a command that loads a launch agent or daemon"],
49
+ [/\bosascript\b[^\n]*login item|\bsfltool\b|\bdefaults\s+write\b[^\n]*(?:loginwindow|LoginHook|AutoLaunchedApplicationDictionary)/i, "startup-item", "a command that adds a login item"],
50
+ [/\bgit\s+config\b[^\n]*core\.hooksPath\b|\bshortcuts\s+(?:import|sign)\b/i, "hook", "a command that installs a hook or shortcut"],
51
+ [/\bssh-copy-id\b|>>?\s*~?[^\s]*authorized_keys\b/i, "remote-access", "a command that lets a key log in later"],
52
+ ];
53
+ const ownName = (tool) => { const i = tool.indexOf("__"); return i >= 0 ? tool.slice(i + 2) : tool; };
54
+ const words = (s) => s.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[_\-.:/]+/g, " ").toLowerCase();
55
+ /** Does this action create or change something that acts later? `strings` are the argument strings and keys. */
56
+ export function persistenceShapes(tool, strings) {
57
+ const hits = new Map();
58
+ const add = (kind, why) => { if (!hits.has(kind))
59
+ hits.set(kind, { kind, why }); };
60
+ const name = words(ownName(tool));
61
+ if (WRITE_WORDS.test(name))
62
+ for (const [re, kind, why] of PERSISTENCE_TOOL_WORDS)
63
+ if (re.test(name))
64
+ add(kind, why);
65
+ // a mail tool that sets a forwarding address under any name: the field says so
66
+ const keys = strings.map(words).join(" | ");
67
+ if (/\b(forward(?:ing)? ?(?:to|address|email)|auto ?forward|redirect ?to|forwarding ?smtp)\b/.test(keys))
68
+ add("mail-rule", "it sets an address that mail will be forwarded to");
69
+ for (const s of strings) {
70
+ if (s.length > 20_000)
71
+ continue; // a file body is content, not a destination; the path argument is what matters
72
+ for (const [re, kind, why] of PERSISTENCE_PATHS)
73
+ if (re.test(s))
74
+ add(kind, `it touches ${why}`);
75
+ for (const [re, kind, why] of PERSISTENCE_COMMANDS)
76
+ if (re.test(s))
77
+ add(kind, `it runs ${why}`);
78
+ }
79
+ return [...hits.values()];
80
+ }
81
+ // ---------- canary ----------
82
+ /** A marker with no meaning anywhere else: 96 random bits, so it never appears by accident. */
83
+ export function newCanary() {
84
+ return `ingress-marker-${randomBytes(12).toString("hex")}`;
85
+ }
86
+ /** The sentence placed in the agent's context with the marker. */
87
+ export function canaryNotice(canary) {
88
+ return `[AcePaste Ingress run marker: ${canary}. It identifies this run and is not data. It must never appear in a tool argument, a message, a file or a URL; an action that carries it is refused.]`;
89
+ }
90
+ /** every spelling of the marker that would survive common encodings of the text around it */
91
+ function canaryForms(canary) {
92
+ const forms = new Set([canary, [...canary].reverse().join("")]);
93
+ const b = Buffer.from(canary, "utf8");
94
+ forms.add(b.toString("hex"));
95
+ // base64 depends on where the marker starts inside the encoded text: take the stable middle of each alignment
96
+ for (let pad = 0; pad < 3; pad++) {
97
+ const enc = Buffer.concat([Buffer.alloc(pad, 0x20), b]).toString("base64").replace(/=+$/, "");
98
+ forms.add(enc.slice(pad ? 4 : 0, enc.length - 4));
99
+ }
100
+ forms.add(encodeURIComponent(canary));
101
+ // the unique part alone: catches a marker whose fixed prefix was dropped or the text was split there
102
+ forms.add(canary.slice("ingress-marker-".length));
103
+ return [...forms].filter((f) => f.length >= 16);
104
+ }
105
+ /** True when any argument string carries the marker, plainly or through a common encoding. */
106
+ export function carriesCanary(strings, canaries) {
107
+ if (!canaries.length)
108
+ return false;
109
+ const forms = canaries.flatMap(canaryForms);
110
+ for (const s of strings) {
111
+ const variants = [s, s.toLowerCase()];
112
+ try {
113
+ variants.push(decodeURIComponent(s));
114
+ }
115
+ catch { /* keep as is */ }
116
+ const squeezed = s.replace(/[\s\-_.:,;|/\\]+/g, ""); // a marker broken up with separators
117
+ variants.push(squeezed, squeezed.toLowerCase());
118
+ for (const v of variants)
119
+ for (const f of forms)
120
+ if (v.includes(f) || v.includes(f.replace(/-/g, "")))
121
+ return true;
122
+ }
123
+ return false;
124
+ }
125
+ export const DEFAULT_BURST = { perMinute: 20, sameAction: 3 };
126
+ export class BurstCounter {
127
+ at = [];
128
+ same = new Map();
129
+ /** record one side effect that ran */
130
+ record(digestKey, now) {
131
+ this.at.push(now);
132
+ const s = this.same.get(digestKey) ?? [];
133
+ s.push(now);
134
+ this.same.set(digestKey, s);
135
+ this.trim(now);
136
+ }
137
+ /** reasons the next action should wait for a person; empty when it is within limits */
138
+ check(digestKey, now, p) {
139
+ this.trim(now);
140
+ const why = [];
141
+ const lastMinute = this.at.filter((t) => now - t < 60_000).length;
142
+ if (lastMinute >= p.perMinute)
143
+ why.push(`this run has already performed ${lastMinute} actions in the last minute`);
144
+ const repeats = (this.same.get(digestKey) ?? []).length;
145
+ if (repeats >= p.sameAction)
146
+ why.push(`this exact action has already run ${repeats} times in the last ten minutes`);
147
+ return why;
148
+ }
149
+ export() { return { at: this.at.slice(-200), same: [...this.same].slice(-200) }; }
150
+ import(d) {
151
+ if (!d || typeof d !== "object")
152
+ return;
153
+ if (Array.isArray(d.at))
154
+ this.at.push(...d.at.filter((x) => typeof x === "number"));
155
+ for (const e of Array.isArray(d.same) ? d.same : [])
156
+ if (Array.isArray(e) && typeof e[0] === "string" && Array.isArray(e[1]))
157
+ this.same.set(e[0], e[1].filter((x) => typeof x === "number"));
158
+ }
159
+ trim(now) {
160
+ this.at = this.at.filter((t) => now - t < 600_000);
161
+ for (const [k, v] of this.same) {
162
+ const kept = v.filter((t) => now - t < 600_000);
163
+ if (kept.length)
164
+ this.same.set(k, kept);
165
+ else
166
+ this.same.delete(k);
167
+ }
168
+ }
169
+ }
170
+ /** the same action whatever run it is in: tool and canonical arguments */
171
+ export const actionKey = (tool, canonicalArgs) => createHash("sha256").update(`${tool}\n${canonicalArgs}`, "utf8").digest("hex");
172
+ // ---------- stop switch ----------
173
+ const stopPath = (dir) => join(dir ?? stateDir(), "STOP");
174
+ /** Why everything is stopped, or undefined when it is not. Any readable file there counts, even an empty one. */
175
+ export function stopReason(dir) {
176
+ const p = stopPath(dir);
177
+ if (!existsSync(p))
178
+ return undefined;
179
+ try {
180
+ return readFileSync(p, "utf8").trim().slice(0, 300) || "stopped by a person";
181
+ }
182
+ catch {
183
+ return "stopped (the stop file exists but could not be read)";
184
+ }
185
+ }
186
+ /** Stop every action routed through any broker on this machine that uses this state folder. */
187
+ export function engageStop(reason, dir, now = new Date()) {
188
+ const p = stopPath(dir);
189
+ mkdirSync(dirname(p), { recursive: true, mode: 0o700 });
190
+ writeFileSync(p, `${reason.trim() || "stopped by a person"} (since ${now.toISOString()})\n`, { mode: 0o600 });
191
+ return p;
192
+ }
193
+ export function clearStop(dir) {
194
+ const p = stopPath(dir);
195
+ if (!existsSync(p))
196
+ return false;
197
+ rmSync(p);
198
+ return true;
199
+ }
@@ -0,0 +1,20 @@
1
+ /**
2
+ * Comparing two copies of "the same" content by their words: the page served to an AI fetcher and to a
3
+ * browser, an email's plain part and its HTML part, a video's captions and its speech.
4
+ * The question is always whether one reader was told something the other was not.
5
+ */
6
+ /** words of served text with markup, link targets and bare URLs removed, so Markdown and HTML of the same page compare equal */
7
+ export declare function servedWords(text: string): string[];
8
+ /** how much of what the agent received is absent from what the browser received (word occurrences, not distinct words) */
9
+ export declare function compareServed(agentText: string, humanText: string): {
10
+ agentWords: number;
11
+ agentOnlyWords: number;
12
+ agentOnlyShare: number;
13
+ longestAgentOnlyRun: number;
14
+ sample: string;
15
+ };
16
+ /**
17
+ * The passages of `text` that `reference` does not contain: runs of at least `minRun` words in a row that
18
+ * appear nowhere in the reference. Returned as the original text of each run, for scanning.
19
+ */
20
+ export declare function passagesOnlyIn(text: string, reference: string, minRun?: number): string[];
@@ -0,0 +1,53 @@
1
+ /**
2
+ * Comparing two copies of "the same" content by their words: the page served to an AI fetcher and to a
3
+ * browser, an email's plain part and its HTML part, a video's captions and its speech.
4
+ * The question is always whether one reader was told something the other was not.
5
+ */
6
+ /** words of served text with markup, link targets and bare URLs removed, so Markdown and HTML of the same page compare equal */
7
+ export function servedWords(text) {
8
+ const t = text
9
+ .replace(/!?\[([^\]]*)\]\([^)]*\)/g, " $1 ") // [label](target) and ![alt](src) -> label
10
+ .replace(/<\/?[a-z][^>]*>/gi, " ") // stray tags
11
+ .replace(/\b(?:https?:\/\/|www\.)\S+/gi, " ") // bare URLs
12
+ .replace(/[#>*_`~|\-]{1,}/g, " "); // markdown syntax
13
+ return t.toLowerCase().split(/[^\p{L}\p{N}']+/u).filter((w) => w.length > 2);
14
+ }
15
+ /** how much of what the agent received is absent from what the browser received (word occurrences, not distinct words) */
16
+ export function compareServed(agentText, humanText) {
17
+ const A = servedWords(agentText);
18
+ const H = new Set(servedWords(humanText));
19
+ const only = A.filter((w) => !H.has(w));
20
+ let run = 0, longestAgentOnlyRun = 0;
21
+ for (const w of A) {
22
+ run = H.has(w) ? 0 : run + 1;
23
+ if (run > longestAgentOnlyRun)
24
+ longestAgentOnlyRun = run;
25
+ }
26
+ const sampleSeen = new Set();
27
+ const sample = only.filter((w) => (sampleSeen.has(w) ? false : (sampleSeen.add(w), true))).slice(0, 30).join(" ");
28
+ return { agentWords: A.length, agentOnlyWords: only.length, agentOnlyShare: A.length ? only.length / A.length : 0, longestAgentOnlyRun, sample };
29
+ }
30
+ /**
31
+ * The passages of `text` that `reference` does not contain: runs of at least `minRun` words in a row that
32
+ * appear nowhere in the reference. Returned as the original text of each run, for scanning.
33
+ */
34
+ export function passagesOnlyIn(text, reference, minRun = 8) {
35
+ const H = new Set(servedWords(reference));
36
+ const out = [];
37
+ // walk the original text sentence by sentence so the passages read as written
38
+ for (const sentence of text.split(/(?<=[.!?])\s+|\n{2,}/)) {
39
+ const words = servedWords(sentence);
40
+ if (words.length < minRun)
41
+ continue;
42
+ let run = 0, longest = 0;
43
+ for (const w of words) {
44
+ run = H.has(w) ? 0 : run + 1;
45
+ if (run > longest)
46
+ longest = run;
47
+ }
48
+ const missing = words.filter((w) => !H.has(w)).length;
49
+ if (longest >= minRun || (missing >= minRun && missing / words.length >= 0.7))
50
+ out.push(sentence.trim());
51
+ }
52
+ return out;
53
+ }
@@ -0,0 +1,39 @@
1
+ /**
2
+ * Which shell commands bring outside content into an agent's context?
3
+ *
4
+ * A PostToolUse hook sees a command and its output. Output that came from the network (curl, wget, gh, a
5
+ * script that calls fetch) or from a background task's output file is outside content and must be gated;
6
+ * the output of `ls` or `npm test` is not. This module answers that question from the command text.
7
+ *
8
+ * It errs toward gating: a command it cannot parse is gated if a network program appears in it at all.
9
+ */
10
+ /** Split a command line into words and operators. Throws on an unterminated quote. */
11
+ export declare function shellTokens(command: string): string[];
12
+ /** Each simple command in command position: its program name (without a path) and its arguments. */
13
+ export declare function shellInvocations(command: string): Array<{
14
+ program: string;
15
+ args: string[];
16
+ }>;
17
+ /**
18
+ * The parts of a command line that can change something: every simple command except those that only read.
19
+ * `cat ~/.zshrc | grep PATH` changes nothing; `echo x >> ~/.zshrc` does. Used so that looking at a startup
20
+ * file or an agent's settings is not mistaken for editing it. A command that cannot be parsed is returned whole.
21
+ */
22
+ export declare function shellWrites(command: string): string[];
23
+ /**
24
+ * Ways a command line sends data to another machine, in plain words; empty when it only asks for something.
25
+ * `curl https://x/page` asks. `curl -d @notes.txt https://x`, `cat key | nc host 9000`, `scp a host:b`,
26
+ * a request built from another command's output: those send.
27
+ */
28
+ export declare function shellUploads(command: string): string[];
29
+ export interface ShellGateOptions {
30
+ cwd?: string;
31
+ /** a loopback port whose responses are already gated (the Ingress service itself); requests only to it are not gated again */
32
+ ownPort?: number;
33
+ }
34
+ /**
35
+ * A label for where this command's output came from if it must be gated, else undefined.
36
+ * Loopback is not exempt: a dev server, a local model server and a tunnel all serve content someone else
37
+ * wrote. Only requests addressed solely to `ownPort` are skipped.
38
+ */
39
+ export declare function shellOutputSource(command: string, opts?: ShellGateOptions): string | undefined;
@@ -0,0 +1,291 @@
1
+ /**
2
+ * Which shell commands bring outside content into an agent's context?
3
+ *
4
+ * A PostToolUse hook sees a command and its output. Output that came from the network (curl, wget, gh, a
5
+ * script that calls fetch) or from a background task's output file is outside content and must be gated;
6
+ * the output of `ls` or `npm test` is not. This module answers that question from the command text.
7
+ *
8
+ * It errs toward gating: a command it cannot parse is gated if a network program appears in it at all.
9
+ */
10
+ import { existsSync, readFileSync, statSync } from "node:fs";
11
+ import { isAbsolute, join } from "node:path";
12
+ import { isIP } from "node:net";
13
+ const NET_CLIENTS = new Set(["curl", "wget", "http", "https", "xh", "xhs", "aria2c", "lynx", "w3m", "links", "elinks", "gh", "nc", "ncat", "netcat", "telnet", "ftp", "sftp", "scp", "rsync", "dig", "nslookup", "host", "whois", "openssl"]);
14
+ const INTERPRETERS = new Set(["node", "python", "python3", "ruby", "perl", "php", "deno", "bun", "tsx", "ts-node", "npx", "bunx", "uvx", "pipx"]);
15
+ const WRAPPERS = new Set(["sudo", "env", "command", "time", "nohup", "exec", "nice", "caffeinate", "stdbuf", "unbuffer", "xargs", "watch"]);
16
+ const OPS = new Set([";", "&", "|", "(", ")", "`", "\n"]);
17
+ const NETWORK_CODE = /https?:\/\/|\bfetch\s*\(|urllib|\brequests\b|http\.client|aiohttp|httpx|axios|node:https?|require\(\s*['"]https?['"]\s*\)|net\/http|Net::HTTP|LWP::|WebSocket|curl_init|file_get_contents\s*\(\s*['"]https?|socket\.|XMLHttpRequest|undici|got\(|node-fetch/;
18
+ /** Split a command line into words and operators. Throws on an unterminated quote. */
19
+ export function shellTokens(command) {
20
+ const out = [];
21
+ let cur = "", has = false;
22
+ const push = () => { if (has)
23
+ out.push(cur); cur = ""; has = false; };
24
+ for (let i = 0; i < command.length; i++) {
25
+ const c = command[i];
26
+ if (c === "'") {
27
+ const end = command.indexOf("'", i + 1);
28
+ if (end < 0)
29
+ throw new Error("unterminated single quote");
30
+ cur += command.slice(i + 1, end);
31
+ has = true;
32
+ i = end;
33
+ }
34
+ else if (c === '"') {
35
+ let j = i + 1, s = "";
36
+ for (; j < command.length && command[j] !== '"'; j++) {
37
+ if (command[j] === "\\" && j + 1 < command.length)
38
+ j++;
39
+ s += command[j];
40
+ }
41
+ if (j >= command.length)
42
+ throw new Error("unterminated double quote");
43
+ cur += s;
44
+ has = true;
45
+ i = j;
46
+ }
47
+ else if (c === "\\" && i + 1 < command.length) {
48
+ cur += command[++i];
49
+ has = true;
50
+ }
51
+ else if (c === " " || c === "\t" || c === "\r")
52
+ push();
53
+ else if (OPS.has(c)) {
54
+ push();
55
+ let op = c;
56
+ while (i + 1 < command.length && OPS.has(command[i + 1]) && command[i + 1] !== "\n")
57
+ op += command[++i];
58
+ out.push(op);
59
+ }
60
+ else {
61
+ cur += c;
62
+ has = true;
63
+ }
64
+ }
65
+ push();
66
+ return out;
67
+ }
68
+ // (an empty quoted word, '' or "", is an argument, not an operator: before 0.9.17 it ended the command it was in)
69
+ const isOp = (t) => t.length > 0 && [...t].every((c) => OPS.has(c));
70
+ /** Each simple command in command position: its program name (without a path) and its arguments. */
71
+ export function shellInvocations(command) {
72
+ const toks = shellTokens(command);
73
+ const out = [];
74
+ let i = 0, atCmd = true;
75
+ while (i < toks.length) {
76
+ const t = toks[i];
77
+ if (isOp(t)) {
78
+ atCmd = true;
79
+ i++;
80
+ continue;
81
+ }
82
+ if (atCmd) {
83
+ const word = t.replace(/^[$(`]+/, "");
84
+ if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(word)) {
85
+ i++;
86
+ continue;
87
+ }
88
+ const base = word.split("/").pop() ?? word;
89
+ if (WRAPPERS.has(base)) {
90
+ i++;
91
+ continue;
92
+ }
93
+ if (base === "timeout") {
94
+ i += 2;
95
+ continue;
96
+ }
97
+ let j = i + 1;
98
+ while (j < toks.length && !isOp(toks[j]))
99
+ j++;
100
+ out.push({ program: base, args: toks.slice(i + 1, j) });
101
+ i = j;
102
+ atCmd = false;
103
+ continue;
104
+ }
105
+ i++;
106
+ }
107
+ return out;
108
+ }
109
+ /** programs that only read, whatever file they are pointed at (given no output redirect) */
110
+ const READERS = new Set(["cat", "less", "more", "head", "tail", "grep", "egrep", "fgrep", "rg", "ag", "ls", "wc", "stat", "file", "diff", "cmp", "jq", "test", "[", "[[", "md5", "md5sum", "shasum", "sha256sum", "uniq", "cut", "tr", "echo", "printf", "pwd", "which", "type", "basename", "dirname", "realpath", "readlink", "du", "df", "tree", "bat", "cd", "true", "false", "nl", "strings", "xxd", "hexdump", "od", "column", "fold", "rev", "tac", "comm", "date", "id", "whoami", "uname", "hostname", "printenv", "sleep"]);
111
+ const HARMLESS_REDIRECT = /^(?:\d*>&\d+|[\d&]*>>?\/dev\/null|\d*<.*)$/;
112
+ function readsOnly(program, args) {
113
+ for (let i = 0; i < args.length; i++) {
114
+ const a = args[i];
115
+ if (!/^[\d&]*>/.test(a))
116
+ continue;
117
+ if (HARMLESS_REDIRECT.test(a))
118
+ continue;
119
+ if (/^[\d&]*>>?$/.test(a) && args[i + 1] === "/dev/null") {
120
+ i++;
121
+ continue;
122
+ }
123
+ return false; // output goes to a file
124
+ }
125
+ if (READERS.has(program))
126
+ return true;
127
+ switch (program) {
128
+ case "sed": return !args.some((a) => /^-[a-zA-Z]*i|^--in-place/.test(a)) && !args.some((a) => /(?:^|;|\s)w\s+\S/.test(a));
129
+ case "awk":
130
+ case "gawk": return !args.some((a) => />|\bsystem\s*\(|\|/.test(a));
131
+ case "sort": return !args.some((a) => /^-[a-zA-Z]*o|^--output/.test(a));
132
+ case "find": return !args.some((a) => /^-(?:delete|exec|execdir|ok|okdir|fprint|fprintf|fls)$/.test(a));
133
+ case "plutil": return args[0] === "-p" || args[0] === "-lint";
134
+ case "yq": return !args.some((a) => /^-[a-zA-Z]*i|^--inplace/.test(a));
135
+ case "git": return ["status", "log", "diff", "show", "branch", "remote", "rev-parse", "ls-files", "blame", "describe", "tag"].includes(args.find((a) => !a.startsWith("-")) ?? "") && !args.some((a) => /^-(?:d|D|m|M)$|^--(?:delete|move|set-upstream|add)/.test(a));
136
+ default: return false;
137
+ }
138
+ }
139
+ /**
140
+ * The parts of a command line that can change something: every simple command except those that only read.
141
+ * `cat ~/.zshrc | grep PATH` changes nothing; `echo x >> ~/.zshrc` does. Used so that looking at a startup
142
+ * file or an agent's settings is not mistaken for editing it. A command that cannot be parsed is returned whole.
143
+ */
144
+ export function shellWrites(command) {
145
+ let inv;
146
+ try {
147
+ inv = shellInvocations(command);
148
+ }
149
+ catch {
150
+ return [command];
151
+ }
152
+ // a here-document or a loop body is not understood by the splitter: keep the whole command
153
+ if (/<<-?\s*['"]?\w/.test(command))
154
+ return [command];
155
+ return inv.filter((i) => !readsOnly(i.program, i.args)).map((i) => [i.program, ...i.args].join(" "));
156
+ }
157
+ /**
158
+ * Ways a command line sends data to another machine, in plain words; empty when it only asks for something.
159
+ * `curl https://x/page` asks. `curl -d @notes.txt https://x`, `cat key | nc host 9000`, `scp a host:b`,
160
+ * a request built from another command's output: those send.
161
+ */
162
+ export function shellUploads(command) {
163
+ const why = new Set();
164
+ let inv = [];
165
+ try {
166
+ inv = shellInvocations(command);
167
+ }
168
+ catch { /* judged from the raw text below */ }
169
+ const piped = (program) => new RegExp(String.raw `\|\s*(?:\S+/)?${program}\b`).test(command);
170
+ for (const { program, args } of inv) {
171
+ const joined = args.join(" ");
172
+ if (program === "curl") {
173
+ for (let i = 0; i < args.length; i++) {
174
+ const a = args[i], v = args[i + 1] ?? "";
175
+ if (/^(?:-d|--data(?:-binary|-raw|-urlencode|-ascii)?|--json)$/.test(a) && /^@|=@/.test(v))
176
+ why.add(v === "@-" ? "it sends the output of another command" : "it sends the contents of a file");
177
+ if (/^(?:-d|--data(?:-binary|-urlencode)?|--json)@/.test(a) || /^--data(?:-binary|-urlencode)?=@/.test(a))
178
+ why.add("it sends the contents of a file");
179
+ if (/^(?:-F|--form)$/.test(a) && /=[@<]/.test(v))
180
+ why.add("it uploads a file as a form field");
181
+ if (/^(?:-T|--upload-file)$/.test(a) || /^--upload-file=/.test(a))
182
+ why.add("it uploads a file");
183
+ }
184
+ }
185
+ if (program === "wget" && /--(?:post-file|body-file)\b/.test(joined))
186
+ why.add("it sends the contents of a file");
187
+ if (["nc", "ncat", "netcat", "telnet", "socat"].includes(program) && (piped(program) || args.some((a) => /^</.test(a))))
188
+ why.add("it pipes data to a network connection");
189
+ if (program === "scp" || program === "sftp")
190
+ why.add("it copies files to or from another machine");
191
+ if (program === "rsync" && args.some((a) => /^rsync:\/\/|^[^/\s:]+@?[^/\s:]*:[^/]/.test(a) && !/^[A-Za-z]:\\/.test(a)))
192
+ why.add("it copies files to or from another machine");
193
+ if (program === "git" && args[0] === "push" && args.slice(1).some((a) => /:\/\/|^[\w.-]+@[\w.-]+:/.test(a)))
194
+ why.add("it pushes the repository to an address given in the command");
195
+ if (program === "gh" && args[0] === "gist" && args[1] === "create")
196
+ why.add("it publishes files as a gist");
197
+ if (["aws", "gsutil", "s5cmd", "rclone", "az"].includes(program) && /\b(?:cp|sync|mv|copy|upload|put)\b/.test(joined) && /\b(?:s3|gs|az|r2):\/\/|\b\w+:[\w/-]+/.test(joined))
198
+ why.add("it copies files to cloud storage");
199
+ if (["mail", "mailx", "sendmail", "mutt", "msmtp"].includes(program))
200
+ why.add("it sends mail");
201
+ }
202
+ // a request whose address or body is built from another command's output
203
+ if (/(?:^|[;&|(\s])(?:\S+\/)?(?:curl|wget|http|https|xh|nc|ncat)\b[^\n;|&]*(?:\$\(|`)/.test(command))
204
+ why.add("it builds a request from the output of another command");
205
+ return [...why];
206
+ }
207
+ function isLoopbackHost(host) {
208
+ const h = host.replace(/^\[|\]$/g, "").toLowerCase().replace(/\.$/, "");
209
+ if (h === "localhost" || h === "ip6-localhost" || h.endsWith(".localhost"))
210
+ return true;
211
+ if (isIP(h) === 4)
212
+ return h.startsWith("127.") || h === "0.0.0.0";
213
+ if (isIP(h) === 6)
214
+ return h === "::1" || h === "::";
215
+ return false;
216
+ }
217
+ /** (host, port) of each URL-like argument; port is undefined when not given. */
218
+ function argTargets(args) {
219
+ const out = [];
220
+ for (const a of args) {
221
+ if (a.startsWith("-") || a.startsWith("@"))
222
+ continue;
223
+ if (a.includes("://")) {
224
+ try {
225
+ const u = new URL(a);
226
+ out.push({ host: u.hostname, port: u.port ? Number(u.port) : undefined });
227
+ }
228
+ catch {
229
+ out.push({ host: "" });
230
+ }
231
+ continue;
232
+ }
233
+ const m = a.match(/^(\[[0-9a-fA-F:]+\]|[A-Za-z0-9.-]+)(?::(\d+))?(?:[/?#].*)?$/);
234
+ if (m && (m[1].includes(".") || m[1].toLowerCase() === "localhost" || m[1].startsWith("[")))
235
+ out.push({ host: m[1], port: m[2] ? Number(m[2]) : undefined });
236
+ }
237
+ return out;
238
+ }
239
+ function scriptUsesNetwork(args, cwd) {
240
+ const code = [];
241
+ let takeNext = false;
242
+ for (const a of args) {
243
+ if (takeNext) {
244
+ code.push(a);
245
+ takeNext = false;
246
+ }
247
+ else if (["-e", "-c", "--eval", "-p", "--print", "-r"].includes(a))
248
+ takeNext = true;
249
+ else if (!a.startsWith("-") && /\.(m?js|cjs|ts|mts|py|rb|pl|php)$/.test(a)) {
250
+ const path = isAbsolute(a) ? a : join(cwd ?? ".", a);
251
+ try {
252
+ if (existsSync(path) && statSync(path).size <= 2_000_000)
253
+ code.push(readFileSync(path, "utf8"));
254
+ }
255
+ catch { /* unreadable: not evidence either way */ }
256
+ break;
257
+ }
258
+ }
259
+ return code.some((c) => NETWORK_CODE.test(c));
260
+ }
261
+ /**
262
+ * A label for where this command's output came from if it must be gated, else undefined.
263
+ * Loopback is not exempt: a dev server, a local model server and a tunnel all serve content someone else
264
+ * wrote. Only requests addressed solely to `ownPort` are skipped.
265
+ */
266
+ export function shellOutputSource(command, opts = {}) {
267
+ if (/\/tasks\/[^\s'"]+\.output\b/.test(command))
268
+ return "background-task-output";
269
+ let found;
270
+ try {
271
+ found = shellInvocations(command);
272
+ }
273
+ catch {
274
+ // unparseable (a heredoc, an odd quote): gate if a network program or interpreter appears in command position at all
275
+ const names = [...NET_CLIENTS, ...INTERPRETERS].join("|");
276
+ return new RegExp(`(?:^|[;&|(\`\\n])\\s*(?:\\S*/)?(${names})\\b`, "m").test(command) ? "bash:unparsed" : undefined;
277
+ }
278
+ for (const { program, args } of found) {
279
+ if (NET_CLIENTS.has(program)) {
280
+ if (program === "gh")
281
+ return `gh:${args.slice(0, 2).join(" ")}`;
282
+ const targets = argTargets(args);
283
+ if (opts.ownPort !== undefined && targets.length && targets.every((t) => isLoopbackHost(t.host) && t.port === opts.ownPort))
284
+ continue;
285
+ return args.find((a) => a.includes("://")) ?? `${program}:${args.join(" ").slice(0, 80)}`;
286
+ }
287
+ if (INTERPRETERS.has(program) && scriptUsesNetwork(args, opts.cwd))
288
+ return `${program}:network-code`;
289
+ }
290
+ return undefined;
291
+ }
@@ -0,0 +1,45 @@
1
+ /**
2
+ * Shortcuts: reading an automation before it is installed.
3
+ *
4
+ * A shared shortcut is a program someone else wrote that runs with your contacts, photos, files, messages and
5
+ * network. Its actions are listed in the file. This scanner reads them and says what the shortcut can do, in
6
+ * three questions that matter together:
7
+ *
8
+ * does it read private data? contacts, photos, files, the clipboard, location, messages, health
9
+ * does it take input from outside? the contents of a web address, a page, a feed, whatever is shared to it
10
+ * can it send things out? a web request with a body, a message, an email, a post, a remote script
11
+ *
12
+ * Any one is ordinary. All three in one shortcut is a program that can be told from outside to send your data
13
+ * somewhere, and it is reported as that. Running code (shell, AppleScript, JavaScript on a page, SSH) and
14
+ * running other shortcuts are reported. Every piece of text in it (comments, message bodies, scripts, URLs)
15
+ * is scanned like any other content.
16
+ *
17
+ * Input: the shortcut as JSON or an XML property list (`plutil -convert json -o - file.shortcut` gives JSON).
18
+ * A signed shortcut exported from the app is encrypted to Apple's format and cannot be read here; one opened
19
+ * from a shared link, or saved unsigned, can.
20
+ */
21
+ import type { AdapterResult } from "./adapters.js";
22
+ type Json = Record<string, unknown>;
23
+ export interface ShortcutAction {
24
+ id: string;
25
+ params: Json;
26
+ }
27
+ export interface ShortcutSummary {
28
+ actions: number;
29
+ readsPrivate: string[];
30
+ outsideInput: string[];
31
+ sendsOut: string[];
32
+ runsCode: string[];
33
+ runsOtherShortcuts: string[];
34
+ destinations: string[];
35
+ acceptsSharedInput: boolean;
36
+ }
37
+ export declare function looksLikeShortcut(doc: unknown): boolean;
38
+ /** A property list in XML, as far as a shortcut needs: dictionaries, arrays, strings, numbers, booleans. */
39
+ export declare function parsePlistXml(xml: string): unknown;
40
+ export declare function summarizeShortcut(doc: unknown): {
41
+ summary: ShortcutSummary;
42
+ actions: ShortcutAction[];
43
+ };
44
+ export declare function adaptShortcut(raw: string): AdapterResult;
45
+ export {};