@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.
- package/dist/src/adapters.d.ts +9 -0
- package/dist/src/adapters.js +76 -6
- package/dist/src/agent-hooks.d.ts +112 -0
- package/dist/src/agent-hooks.js +533 -0
- package/dist/src/approvers.d.ts +16 -0
- package/dist/src/approvers.js +50 -0
- package/dist/src/audio.d.ts +70 -0
- package/dist/src/audio.js +224 -0
- package/dist/src/audit-changes.d.ts +46 -0
- package/dist/src/audit-changes.js +110 -0
- package/dist/src/audit-local.d.ts +57 -0
- package/dist/src/audit-local.js +231 -0
- package/dist/src/audit-parsers.d.ts +1 -1
- package/dist/src/audit.js +48 -0
- package/dist/src/broker.d.ts +92 -1
- package/dist/src/broker.js +222 -3
- package/dist/src/calendar.d.ts +36 -0
- package/dist/src/calendar.js +227 -0
- package/dist/src/captions.d.ts +44 -0
- package/dist/src/captions.js +209 -0
- package/dist/src/changes.d.ts +105 -0
- package/dist/src/changes.js +174 -0
- package/dist/src/character.js +15 -1
- package/dist/src/classifier-model.d.ts +53 -0
- package/dist/src/classifier-model.js +3 -0
- package/dist/src/classifier.d.ts +41 -0
- package/dist/src/classifier.js +213 -0
- package/dist/src/cli.js +501 -1
- package/dist/src/egress.d.ts +71 -0
- package/dist/src/egress.js +242 -0
- package/dist/src/email.d.ts +42 -0
- package/dist/src/email.js +424 -0
- package/dist/src/engine.d.ts +36 -12
- package/dist/src/engine.js +88 -37
- package/dist/src/image-meta.d.ts +33 -0
- package/dist/src/image-meta.js +433 -0
- package/dist/src/image.d.ts +110 -0
- package/dist/src/image.js +353 -0
- package/dist/src/index.d.ts +50 -5
- package/dist/src/index.js +28 -3
- package/dist/src/localguard.d.ts +33 -0
- package/dist/src/localguard.js +61 -0
- package/dist/src/meaning.d.ts +2 -0
- package/dist/src/meaning.js +77 -22
- package/dist/src/messages.d.ts +79 -0
- package/dist/src/messages.js +431 -0
- package/dist/src/nearby.d.ts +52 -0
- package/dist/src/nearby.js +186 -0
- package/dist/src/netpolicy.js +50 -19
- package/dist/src/provenance.d.ts +56 -0
- package/dist/src/provenance.js +114 -0
- package/dist/src/qr.d.ts +25 -0
- package/dist/src/qr.js +113 -0
- package/dist/src/safeguards.d.ts +61 -0
- package/dist/src/safeguards.js +199 -0
- package/dist/src/served.d.ts +20 -0
- package/dist/src/served.js +53 -0
- package/dist/src/shell-commands.d.ts +39 -0
- package/dist/src/shell-commands.js +291 -0
- package/dist/src/shortcuts.d.ts +45 -0
- package/dist/src/shortcuts.js +220 -0
- package/dist/src/stream.d.ts +88 -0
- package/dist/src/stream.js +119 -0
- package/dist/src/terminal.d.ts +29 -0
- package/dist/src/terminal.js +313 -0
- package/dist/src/tooldefs.d.ts +84 -0
- package/dist/src/tooldefs.js +122 -0
- package/dist/src/types.d.ts +50 -6
- package/dist/src/types.js +15 -2
- package/dist/src/visibility.d.ts +23 -3
- package/dist/src/visibility.js +285 -78
- package/native/ingress-presence.swift +48 -0
- package/native/ingress-vision.swift +417 -0
- package/package.json +3 -1
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Nearby: what devices around you say about themselves.
|
|
3
|
+
*
|
|
4
|
+
* A Bonjour service name, a Bluetooth device name, a printer's description, a beacon's link: each is a string
|
|
5
|
+
* chosen by whoever owns the device, broadcast to everyone in range, and shown in pickers and lists that an
|
|
6
|
+
* agent may read ("which printer should I use?", "what's on this network?"). Nobody vouches for any of it.
|
|
7
|
+
* It is the lowest-trust content there is (trust level 6), and it is read here as content, never as fact.
|
|
8
|
+
*
|
|
9
|
+
* Checks:
|
|
10
|
+
* instructions in a name or a record the ordinary rules and the classifier's short-text mode
|
|
11
|
+
* authority names "IT Managed Printer", "Apple Setup", "System Update Service"
|
|
12
|
+
* lookalikes a name one or two characters from a device you know, or the same
|
|
13
|
+
* name from a different address
|
|
14
|
+
* links a beacon's or a service's URL is listed, never opened; ones that hide
|
|
15
|
+
* their destination are flagged
|
|
16
|
+
* oversized fields a TXT record or a name far longer than a device needs
|
|
17
|
+
*
|
|
18
|
+
* Ingress cannot stop a broadcast. It gates what an agent reads of it.
|
|
19
|
+
*/
|
|
20
|
+
import { execFile } from "node:child_process";
|
|
21
|
+
import { decodeEntities } from "./adapters.js";
|
|
22
|
+
import { linkTrick } from "./messages.js";
|
|
23
|
+
const str = (v) => (typeof v === "string" ? v : typeof v === "number" ? String(v) : "");
|
|
24
|
+
const TYPES = new Set(["bonjour", "bluetooth", "printer", "beacon", "wifi", "other"]);
|
|
25
|
+
export function looksLikeNearbyJson(doc) {
|
|
26
|
+
const list = Array.isArray(doc) ? doc : doc && typeof doc === "object" && Array.isArray(doc.devices) ? doc.devices : undefined;
|
|
27
|
+
return !!list?.length && list.slice(0, 30).every((r) => !!r && typeof r === "object" && typeof r.name === "string" && typeof r.type === "string" && TYPES.has(String(r.type)));
|
|
28
|
+
}
|
|
29
|
+
export function parseNearby(doc) {
|
|
30
|
+
const list = Array.isArray(doc) ? doc : doc && typeof doc === "object" ? (doc.devices ?? doc.records ?? doc.services) : undefined;
|
|
31
|
+
const out = [];
|
|
32
|
+
for (const r of (Array.isArray(list) ? list : []).slice(0, 2000)) {
|
|
33
|
+
if (!r || typeof r !== "object")
|
|
34
|
+
continue;
|
|
35
|
+
const o = r;
|
|
36
|
+
const name = str(o.name) || str(o.device_name) || str(o.ssid);
|
|
37
|
+
if (!name)
|
|
38
|
+
continue;
|
|
39
|
+
const fields = {};
|
|
40
|
+
for (const src of [o.txt, o.fields, o.attributes])
|
|
41
|
+
if (src && typeof src === "object")
|
|
42
|
+
for (const [k, v] of Object.entries(src).slice(0, 60))
|
|
43
|
+
if (str(v))
|
|
44
|
+
fields[k] = str(v);
|
|
45
|
+
for (const k of ["location", "description", "info", "make_and_model", "manufacturer", "model", "note"])
|
|
46
|
+
if (str(o[k]))
|
|
47
|
+
fields[k] = str(o[k]);
|
|
48
|
+
out.push({ type: TYPES.has(str(o.type)) ? str(o.type) : "other", name, service: str(o.service) || undefined, address: str(o.address) || str(o.host) || str(o.mac) || undefined, fields: Object.keys(fields).length ? fields : undefined, url: str(o.url) || undefined, known: o.known === true || o.paired === true || o.connected === true });
|
|
49
|
+
}
|
|
50
|
+
return out;
|
|
51
|
+
}
|
|
52
|
+
// ---------- reading what the system lists (macOS; read-only) ----------
|
|
53
|
+
/** `dns-sd -B <type>` lines: "Timestamp A/R Flags if Domain Service-Type Instance-Name" */
|
|
54
|
+
export function parseDnsSdBrowse(text) {
|
|
55
|
+
const out = [];
|
|
56
|
+
for (const line of text.split("\n")) {
|
|
57
|
+
const m = line.match(/^\s*\d{1,2}:\d{2}:\d{2}\.\d+\s+Add\s+\d+\s+\d+\s+(\S+)\s+(\S+)\s+(.+?)\s*$/);
|
|
58
|
+
// (the domain column, "local.", is not an address: a browse does not say which host a service is on)
|
|
59
|
+
if (m)
|
|
60
|
+
out.push({ type: "bonjour", name: m[3], service: m[2].replace(/\.$/, "") });
|
|
61
|
+
}
|
|
62
|
+
return out;
|
|
63
|
+
}
|
|
64
|
+
/** `system_profiler SPBluetoothDataType -json` */
|
|
65
|
+
export function parseBluetoothProfile(json) {
|
|
66
|
+
const out = [];
|
|
67
|
+
let doc;
|
|
68
|
+
try {
|
|
69
|
+
doc = JSON.parse(json);
|
|
70
|
+
}
|
|
71
|
+
catch {
|
|
72
|
+
return out;
|
|
73
|
+
}
|
|
74
|
+
for (const ctl of doc?.SPBluetoothDataType ?? []) {
|
|
75
|
+
for (const [key, known] of [["device_connected", true], ["device_not_connected", true], ["devices_list", false]]) {
|
|
76
|
+
for (const entry of ctl[key] ?? []) {
|
|
77
|
+
for (const [name, info] of Object.entries(entry)) {
|
|
78
|
+
const i = (info ?? {});
|
|
79
|
+
out.push({ type: "bluetooth", name, service: str(i.device_minorType) || undefined, address: str(i.device_address) || undefined, known, fields: str(i.device_vendorID) ? { vendor: str(i.device_vendorID) } : undefined });
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
return out;
|
|
85
|
+
}
|
|
86
|
+
/** `lpstat -l -p` blocks: "printer NAME ..." followed by indented "Description:", "Location:" lines */
|
|
87
|
+
export function parseLpstatPrinters(text) {
|
|
88
|
+
const out = [];
|
|
89
|
+
let cur;
|
|
90
|
+
for (const line of text.split("\n")) {
|
|
91
|
+
const p = line.match(/^printer\s+(\S+)/);
|
|
92
|
+
if (p) {
|
|
93
|
+
cur = { type: "printer", name: p[1], known: true, fields: {} };
|
|
94
|
+
out.push(cur);
|
|
95
|
+
continue;
|
|
96
|
+
}
|
|
97
|
+
const f = line.match(/^\s+(Description|Location|Interface|Alerts|Connection):\s*(.+)$/);
|
|
98
|
+
if (cur && f && f[2].trim())
|
|
99
|
+
cur.fields[f[1].toLowerCase()] = f[2].trim();
|
|
100
|
+
}
|
|
101
|
+
return out;
|
|
102
|
+
}
|
|
103
|
+
const run = (cmd, args, timeoutMs) => new Promise((resolve) => {
|
|
104
|
+
// dns-sd never exits on its own: it is stopped when the time is up, and what it printed is kept
|
|
105
|
+
execFile(cmd, args, { timeout: timeoutMs, encoding: "utf8", maxBuffer: 16 * 1024 * 1024, killSignal: "SIGTERM" }, (_err, stdout) => resolve(String(stdout ?? "")));
|
|
106
|
+
});
|
|
107
|
+
/** What this Mac currently lists: Bonjour services, Bluetooth devices, printers. Read-only; nothing is joined, paired or contacted. */
|
|
108
|
+
export async function collectNearby(opts = {}) {
|
|
109
|
+
if (process.platform !== "darwin")
|
|
110
|
+
return [];
|
|
111
|
+
const ms = Math.max(1, opts.seconds ?? 3) * 1000;
|
|
112
|
+
const types = parseDnsSdBrowse(await run("/usr/bin/dns-sd", ["-B", "_services._dns-sd._udp", "local."], ms)).map((r) => `${r.name}.${(r.service ?? "").replace(/\.local$/, "")}`).filter((t) => /^_[\w-]+\._(tcp|udp)$/.test(t)).slice(0, 40);
|
|
113
|
+
const browsed = await Promise.all([...new Set(types)].map((t) => run("/usr/bin/dns-sd", ["-B", t, "local."], ms)));
|
|
114
|
+
const [bt, lp] = await Promise.all([run("/usr/sbin/system_profiler", ["SPBluetoothDataType", "-json"], 20_000), run("/usr/bin/lpstat", ["-l", "-p"], 10_000)]);
|
|
115
|
+
return [...browsed.flatMap(parseDnsSdBrowse), ...parseBluetoothProfile(bt), ...parseLpstatPrinters(lp)];
|
|
116
|
+
}
|
|
117
|
+
// ---------- checks ----------
|
|
118
|
+
const AUTHORITY = /\b(?:it[- ]?(?:managed|admin|support|department)|admin(?:istrator)?|system (?:update|service|setup|recovery)|security (?:update|scanner|service)|(?:apple|microsoft|google|windows|macos|ios) (?:setup|support|update|security|recovery|configurator)|device (?:enrollment|management)|mdm|corporate (?:vpn|wifi|network)|free (?:public )?wi-?fi|guest wi-?fi login|software update|firmware update|setup assistant|recovery mode|password (?:reset|recovery))\b/i;
|
|
119
|
+
function distance(a, b) {
|
|
120
|
+
if (Math.abs(a.length - b.length) > 2)
|
|
121
|
+
return 3;
|
|
122
|
+
const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
|
|
123
|
+
for (let i = 1; i <= a.length; i++) {
|
|
124
|
+
let last = prev[0];
|
|
125
|
+
prev[0] = i;
|
|
126
|
+
for (let j = 1; j <= b.length; j++) {
|
|
127
|
+
const t = prev[j];
|
|
128
|
+
prev[j] = Math.min(prev[j] + 1, prev[j - 1] + 1, last + (a[i - 1] === b[j - 1] ? 0 : 1));
|
|
129
|
+
last = t;
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
return prev[b.length];
|
|
133
|
+
}
|
|
134
|
+
/** the name with lookalike characters folded, so "Offíce-Printer" and "Office-Printer" compare equal */
|
|
135
|
+
const fold = (s) => s.normalize("NFKD").replace(/[̀-ͯ]/g, "").toLowerCase().replace(/[0oо]/g, "o").replace(/[1lIіı|]/g, "l").replace(/[аa]/g, "a").replace(/[еe]/g, "e").replace(/[\s_\-.’']+/g, "");
|
|
136
|
+
export function adaptNearby(raw, hints = {}) {
|
|
137
|
+
const segments = [];
|
|
138
|
+
const findings = [];
|
|
139
|
+
const add = (f) => findings.push({ pass: "channel", action: "none", ...f });
|
|
140
|
+
let doc;
|
|
141
|
+
try {
|
|
142
|
+
doc = JSON.parse(raw);
|
|
143
|
+
}
|
|
144
|
+
catch {
|
|
145
|
+
doc = undefined;
|
|
146
|
+
}
|
|
147
|
+
if (doc === undefined || typeof doc !== "object") {
|
|
148
|
+
// a plain list of names, one per line
|
|
149
|
+
segments.push({ text: decodeEntities(typeof doc === "string" ? doc : raw).text, visibility: "visible", path: "nearby/text" });
|
|
150
|
+
return { segments, findings };
|
|
151
|
+
}
|
|
152
|
+
const records = parseNearby(doc);
|
|
153
|
+
const known = [...(hints.knownDevices ?? []), ...records.filter((r) => r.known).map((r) => ({ name: r.name, address: r.address, type: r.type }))];
|
|
154
|
+
// One device shows up in several lists (an iPad over Bluetooth and again over Bonjour), and stock names repeat
|
|
155
|
+
// in every office ("iPad", "HP LaserJet"). The same name at another address means something only within one
|
|
156
|
+
// kind of listing, and only for a name someone chose. (Found on the first live run: this Mac's own iPad.)
|
|
157
|
+
const stock = /^(?:i(?:Pad|Phone|Mac)|Mac(?:Book(?: Pro| Air)?| mini| Studio| Pro)?|AirPods(?: Pro| Max)?|Apple (?:Watch|TV)|HomePod(?: mini)?|Android|Galaxy\b.*|Pixel\b.*|HP\b.*|Brother\b.*|Canon\b.*|EPSON\b.*|Chromecast.*|Living Room|Bedroom|Kitchen|Office)$/i;
|
|
158
|
+
let authority = 0, lookalike = 0, oversized = 0, links = 0;
|
|
159
|
+
records.forEach((r, i) => {
|
|
160
|
+
const path = `nearby[${i}]:${r.type}`;
|
|
161
|
+
segments.push({ text: r.name, visibility: "visible", path: `${path}/name` });
|
|
162
|
+
for (const [k, v] of Object.entries(r.fields ?? {})) {
|
|
163
|
+
// a device's extra records are shown by few pickers: read, and judged as text nobody chose to look at
|
|
164
|
+
segments.push({ text: v, visibility: "attribute", path: `${path}/${k}` });
|
|
165
|
+
if (v.length > 400 && oversized++ < 3)
|
|
166
|
+
add({ kind: "nearby.oversized_field", confidence: 0.3, severity: 0.5, message: `a ${r.type} device publishes ${v.length} characters in its "${k.slice(0, 30)}" record: far more than a device needs to describe itself`, location: `${path}/${k}`, inHidden: true });
|
|
167
|
+
}
|
|
168
|
+
if (r.name.length > 120 && oversized++ < 3)
|
|
169
|
+
add({ kind: "nearby.oversized_field", confidence: 0.3, severity: 0.5, message: `a ${r.type} device has a ${r.name.length}-character name`, location: `${path}/name` });
|
|
170
|
+
if (!r.known && AUTHORITY.test(`${r.name} ${Object.values(r.fields ?? {}).join(" ")}`) && authority++ < 5)
|
|
171
|
+
add({ kind: "nearby.authority_name", confidence: 0.35, severity: 0.6, message: `a ${r.type} device nobody here set up calls itself "${r.name.slice(0, 60)}": anyone in range can broadcast that name`, location: `${path}/name` });
|
|
172
|
+
if (!r.known) {
|
|
173
|
+
const twin = known.find((k) => k.name !== r.name ? fold(k.name) === fold(r.name) || (Math.min(k.name.length, r.name.length) >= 6 && distance(k.name.toLowerCase(), r.name.toLowerCase()) <= 1) : !!k.address && !!r.address && k.address.toLowerCase() !== r.address.toLowerCase() && (!k.type || k.type === r.type) && !stock.test(r.name.trim()));
|
|
174
|
+
if (twin && lookalike++ < 5)
|
|
175
|
+
add({ kind: "nearby.lookalike", confidence: 0.45, severity: 0.65, message: twin.name === r.name ? `a second device is using the name of one you know ("${r.name.slice(0, 60)}") from a different address` : `"${r.name.slice(0, 60)}" is nearly the name of a device you know ("${twin.name.slice(0, 60)}")`, location: `${path}/name` });
|
|
176
|
+
}
|
|
177
|
+
const url = r.url ?? Object.values(r.fields ?? {}).find((v) => /^https?:\/\//i.test(v));
|
|
178
|
+
if (url) {
|
|
179
|
+
const trick = linkTrick(url);
|
|
180
|
+
segments.push({ text: `[${r.type} link: ${url.slice(0, 200)}]`, visibility: "attribute", path: `${path}/url` });
|
|
181
|
+
if (trick && links++ < 5)
|
|
182
|
+
add({ kind: "nearby.link", confidence: 0.4, severity: 0.6, message: `a ${r.type} device broadcasts a link that is ${trick}. Links from devices are listed, never opened`, location: `${path}/url` });
|
|
183
|
+
}
|
|
184
|
+
});
|
|
185
|
+
return { segments, findings };
|
|
186
|
+
}
|
package/dist/src/netpolicy.js
CHANGED
|
@@ -37,30 +37,60 @@ const BLOCKED_V4 = [
|
|
|
37
37
|
export function isPrivateIPv4(ip) {
|
|
38
38
|
return BLOCKED_V4.some((c) => inCidr4(ip, c));
|
|
39
39
|
}
|
|
40
|
+
/** Expand an IPv6 literal to its 8 groups (lower-case hex, no leading zeros), so every spelling compares alike. */
|
|
41
|
+
function expandIPv6(ip) {
|
|
42
|
+
let s = ip.toLowerCase().replace(/%.*$/, ""); // drop a zone id (fe80::1%en0)
|
|
43
|
+
// a dotted IPv4 tail (::ffff:127.0.0.1) becomes two groups
|
|
44
|
+
const v4 = s.match(/^(.*:)(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
|
|
45
|
+
if (v4) {
|
|
46
|
+
const [a, b, c, d] = v4.slice(2).map(Number);
|
|
47
|
+
if ([a, b, c, d].some((n) => n > 255))
|
|
48
|
+
return null;
|
|
49
|
+
s = `${v4[1]}${((a << 8) | b).toString(16)}:${((c << 8) | d).toString(16)}`;
|
|
50
|
+
}
|
|
51
|
+
const halves = s.split("::");
|
|
52
|
+
if (halves.length > 2)
|
|
53
|
+
return null;
|
|
54
|
+
const head = halves[0] ? halves[0].split(":") : [];
|
|
55
|
+
const tail = halves.length === 2 && halves[1] ? halves[1].split(":") : [];
|
|
56
|
+
const fill = halves.length === 2 ? 8 - head.length - tail.length : 0;
|
|
57
|
+
if (fill < 0 || (halves.length === 1 && head.length !== 8))
|
|
58
|
+
return null;
|
|
59
|
+
const groups = [...head, ...Array(fill).fill("0"), ...tail];
|
|
60
|
+
if (groups.length !== 8 || groups.some((g) => !/^[0-9a-f]{1,4}$/.test(g)))
|
|
61
|
+
return null;
|
|
62
|
+
return groups.map((g) => parseInt(g, 16));
|
|
63
|
+
}
|
|
64
|
+
const v4From = (hi, lo) => `${hi >> 8}.${hi & 255}.${lo >> 8}.${lo & 255}`;
|
|
40
65
|
export function isPrivateIPv6(ip) {
|
|
41
|
-
|
|
42
|
-
|
|
66
|
+
// Every spelling of an address must give the same answer: 0:0:0:0:0:0:0:1, ::ffff:127.0.0.1 and
|
|
67
|
+
// ::ffff:7f00:1 are all loopback. An address that cannot be parsed is treated as blocked.
|
|
68
|
+
const g = expandIPv6(ip);
|
|
69
|
+
if (!g)
|
|
43
70
|
return true;
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
return isPrivateIPv4(
|
|
53
|
-
|
|
54
|
-
|
|
71
|
+
const zeros = (n) => g.slice(0, n).every((x) => x === 0);
|
|
72
|
+
if (zeros(8))
|
|
73
|
+
return true; // ::
|
|
74
|
+
if (zeros(7) && g[7] === 1)
|
|
75
|
+
return true; // ::1
|
|
76
|
+
if (zeros(5) && g[5] === 0xffff)
|
|
77
|
+
return isPrivateIPv4(v4From(g[6], g[7])); // IPv4-mapped ::ffff:a.b.c.d
|
|
78
|
+
if (zeros(6))
|
|
79
|
+
return isPrivateIPv4(v4From(g[6], g[7])); // IPv4-compatible ::a.b.c.d (deprecated, still parsed)
|
|
80
|
+
if (g[0] === 0x2002)
|
|
81
|
+
return isPrivateIPv4(v4From(g[1], g[2])); // 6to4 carries an IPv4 address
|
|
82
|
+
if (g[0] === 0x64 && g[1] === 0xff9b)
|
|
83
|
+
return true; // NAT64 well-known prefix can reach v4 space
|
|
84
|
+
if ((g[0] & 0xffc0) === 0xfe80)
|
|
55
85
|
return true; // link-local fe80::/10
|
|
56
|
-
if (
|
|
86
|
+
if ((g[0] & 0xffc0) === 0xfec0)
|
|
87
|
+
return true; // site-local fec0::/10 (deprecated, still private by intent)
|
|
88
|
+
if ((g[0] & 0xfe00) === 0xfc00)
|
|
57
89
|
return true; // unique local fc00::/7
|
|
58
|
-
if (
|
|
90
|
+
if ((g[0] & 0xff00) === 0xff00)
|
|
59
91
|
return true; // multicast
|
|
60
|
-
if (
|
|
92
|
+
if (g[0] === 0x2001 && g[1] === 0xdb8)
|
|
61
93
|
return true; // documentation
|
|
62
|
-
if (l.startsWith("64:ff9b"))
|
|
63
|
-
return true; // NAT64 well-known prefix can reach v4 space
|
|
64
94
|
return false;
|
|
65
95
|
}
|
|
66
96
|
export function isPrivateIP(ip) {
|
|
@@ -83,7 +113,8 @@ function hostMatches(host, pattern) {
|
|
|
83
113
|
* them (DNS rebinding defense: the fetch must connect to what we checked).
|
|
84
114
|
*/
|
|
85
115
|
export async function checkTarget(url, policy, resolver = defaultResolve) {
|
|
86
|
-
|
|
116
|
+
// one spelling per host: no brackets, no trailing dot ("localhost." is localhost), lower case
|
|
117
|
+
const host = url.hostname.replace(/^\[|\]$/g, "").replace(/\.$/, "").toLowerCase();
|
|
87
118
|
const port = url.port ? Number(url.port) : url.protocol === "https:" ? 443 : 80;
|
|
88
119
|
if (port !== 80 && port !== 443 && !policy.extraPorts.includes(port)) {
|
|
89
120
|
throw new NetPolicyError(`port ${port} not allowed`, "bad_port");
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Provenance marks: what an agent wrote after reading outside content.
|
|
3
|
+
*
|
|
4
|
+
* A run that has read a web page, an email or a tool result may have been steered by it. What that run
|
|
5
|
+
* writes to disk is the way one steered moment reaches a later, clean session: a note, a script, a config.
|
|
6
|
+
* So each file written in such a run is marked: which session, when, and what it had read. When a later
|
|
7
|
+
* session reads the file, the mark says its content is at best "written by an agent earlier" (trust level 3
|
|
8
|
+
* only if the run that wrote it was clean; this one was not).
|
|
9
|
+
*
|
|
10
|
+
* A mark labels; it does not block. The files are the person's own project, and withholding them would stop
|
|
11
|
+
* work. The reader is told, the file is scanned as outside content, and the reading session counts as having
|
|
12
|
+
* read outside content.
|
|
13
|
+
*
|
|
14
|
+
* Marks are kept by path with the file's hash, so a mark also says whether the file changed since.
|
|
15
|
+
* A person clears a mark (`ingress provenance clear <path>`); an agent cannot.
|
|
16
|
+
*/
|
|
17
|
+
export interface ProvenanceMark {
|
|
18
|
+
path: string;
|
|
19
|
+
/** hash of the file when it was marked; undefined if it could not be read */
|
|
20
|
+
sha256?: string;
|
|
21
|
+
at: string;
|
|
22
|
+
session: string;
|
|
23
|
+
/** the last few things the writing session had read */
|
|
24
|
+
sources: string[];
|
|
25
|
+
}
|
|
26
|
+
export declare class ProvenanceLedger {
|
|
27
|
+
private file;
|
|
28
|
+
constructor(dir?: string);
|
|
29
|
+
private read;
|
|
30
|
+
private write;
|
|
31
|
+
/** Mark a file as written by a session that had read outside content. */
|
|
32
|
+
mark(path: string, by: {
|
|
33
|
+
session: string;
|
|
34
|
+
sources: readonly string[];
|
|
35
|
+
at?: string;
|
|
36
|
+
}): ProvenanceMark;
|
|
37
|
+
/** The mark on a file, and whether the file is still what was written then. */
|
|
38
|
+
lookup(path: string): {
|
|
39
|
+
mark: ProvenanceMark;
|
|
40
|
+
unchanged: boolean;
|
|
41
|
+
} | undefined;
|
|
42
|
+
/** Remove a mark: a person has looked at the file. Returns whether there was one. */
|
|
43
|
+
clear(path: string): boolean;
|
|
44
|
+
list(): ProvenanceMark[];
|
|
45
|
+
}
|
|
46
|
+
/** One sentence for whoever reads a marked file. */
|
|
47
|
+
export declare function describeMark(m: ProvenanceMark, unchanged: boolean): string;
|
|
48
|
+
/**
|
|
49
|
+
* Where the operating system says a file came from: macOS marks downloads (and what is unpacked from them)
|
|
50
|
+
* with a quarantine attribute naming the app that fetched them, and often the address. Undefined when the
|
|
51
|
+
* file has no such mark, or on a system without it.
|
|
52
|
+
*/
|
|
53
|
+
export declare function downloadOrigin(path: string): {
|
|
54
|
+
agent?: string;
|
|
55
|
+
from?: string;
|
|
56
|
+
} | undefined;
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Provenance marks: what an agent wrote after reading outside content.
|
|
3
|
+
*
|
|
4
|
+
* A run that has read a web page, an email or a tool result may have been steered by it. What that run
|
|
5
|
+
* writes to disk is the way one steered moment reaches a later, clean session: a note, a script, a config.
|
|
6
|
+
* So each file written in such a run is marked: which session, when, and what it had read. When a later
|
|
7
|
+
* session reads the file, the mark says its content is at best "written by an agent earlier" (trust level 3
|
|
8
|
+
* only if the run that wrote it was clean; this one was not).
|
|
9
|
+
*
|
|
10
|
+
* A mark labels; it does not block. The files are the person's own project, and withholding them would stop
|
|
11
|
+
* work. The reader is told, the file is scanned as outside content, and the reading session counts as having
|
|
12
|
+
* read outside content.
|
|
13
|
+
*
|
|
14
|
+
* Marks are kept by path with the file's hash, so a mark also says whether the file changed since.
|
|
15
|
+
* A person clears a mark (`ingress provenance clear <path>`); an agent cannot.
|
|
16
|
+
*/
|
|
17
|
+
import { createHash } from "node:crypto";
|
|
18
|
+
import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
|
|
19
|
+
import { execFileSync } from "node:child_process";
|
|
20
|
+
import { join, resolve } from "node:path";
|
|
21
|
+
import { stateDir } from "./changes.js";
|
|
22
|
+
const MAX_MARKS = 5000;
|
|
23
|
+
const MAX_HASH_BYTES = 20_000_000;
|
|
24
|
+
function hashFile(path) {
|
|
25
|
+
try {
|
|
26
|
+
if (statSync(path).size > MAX_HASH_BYTES)
|
|
27
|
+
return undefined;
|
|
28
|
+
return createHash("sha256").update(readFileSync(path)).digest("hex");
|
|
29
|
+
}
|
|
30
|
+
catch {
|
|
31
|
+
return undefined;
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
export class ProvenanceLedger {
|
|
35
|
+
file;
|
|
36
|
+
constructor(dir = stateDir()) { this.file = join(dir, "provenance.json"); }
|
|
37
|
+
read() {
|
|
38
|
+
try {
|
|
39
|
+
const v = JSON.parse(readFileSync(this.file, "utf8"));
|
|
40
|
+
return v && typeof v === "object" && !Array.isArray(v) ? v : {};
|
|
41
|
+
}
|
|
42
|
+
catch {
|
|
43
|
+
return {};
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
write(marks) {
|
|
47
|
+
let entries = Object.entries(marks);
|
|
48
|
+
if (entries.length > MAX_MARKS)
|
|
49
|
+
entries = entries.sort((a, b) => a[1].at.localeCompare(b[1].at)).slice(-MAX_MARKS);
|
|
50
|
+
mkdirSync(join(this.file, ".."), { recursive: true, mode: 0o700 });
|
|
51
|
+
writeFileSync(`${this.file}.${process.pid}.tmp`, JSON.stringify(Object.fromEntries(entries)), { mode: 0o600 });
|
|
52
|
+
renameSync(`${this.file}.${process.pid}.tmp`, this.file);
|
|
53
|
+
}
|
|
54
|
+
/** Mark a file as written by a session that had read outside content. */
|
|
55
|
+
mark(path, by) {
|
|
56
|
+
const p = resolve(path);
|
|
57
|
+
const mark = { path: p, sha256: hashFile(p), at: by.at ?? new Date().toISOString(), session: by.session, sources: by.sources.slice(-5).map((s) => s.slice(0, 200)) };
|
|
58
|
+
const marks = this.read();
|
|
59
|
+
marks[p] = mark;
|
|
60
|
+
this.write(marks);
|
|
61
|
+
return mark;
|
|
62
|
+
}
|
|
63
|
+
/** The mark on a file, and whether the file is still what was written then. */
|
|
64
|
+
lookup(path) {
|
|
65
|
+
const p = resolve(path);
|
|
66
|
+
const mark = this.read()[p];
|
|
67
|
+
if (!mark || typeof mark.path !== "string")
|
|
68
|
+
return undefined;
|
|
69
|
+
return { mark, unchanged: mark.sha256 !== undefined && mark.sha256 === hashFile(p) };
|
|
70
|
+
}
|
|
71
|
+
/** Remove a mark: a person has looked at the file. Returns whether there was one. */
|
|
72
|
+
clear(path) {
|
|
73
|
+
const p = resolve(path);
|
|
74
|
+
const marks = this.read();
|
|
75
|
+
if (!(p in marks))
|
|
76
|
+
return false;
|
|
77
|
+
delete marks[p];
|
|
78
|
+
this.write(marks);
|
|
79
|
+
return true;
|
|
80
|
+
}
|
|
81
|
+
list() { return Object.values(this.read()).sort((a, b) => b.at.localeCompare(a.at)); }
|
|
82
|
+
}
|
|
83
|
+
/** One sentence for whoever reads a marked file. */
|
|
84
|
+
export function describeMark(m, unchanged) {
|
|
85
|
+
const from = m.sources.length ? ` (it had read: ${m.sources.slice(-3).join(", ")})` : "";
|
|
86
|
+
return `this file was written on ${m.at.slice(0, 10)} by an agent session that had read outside content${from}${unchanged ? "" : "; it has been changed since"}`;
|
|
87
|
+
}
|
|
88
|
+
/**
|
|
89
|
+
* Where the operating system says a file came from: macOS marks downloads (and what is unpacked from them)
|
|
90
|
+
* with a quarantine attribute naming the app that fetched them, and often the address. Undefined when the
|
|
91
|
+
* file has no such mark, or on a system without it.
|
|
92
|
+
*/
|
|
93
|
+
export function downloadOrigin(path) {
|
|
94
|
+
if (process.platform !== "darwin" || !existsSync(path))
|
|
95
|
+
return undefined;
|
|
96
|
+
let q;
|
|
97
|
+
try {
|
|
98
|
+
q = execFileSync("/usr/bin/xattr", ["-p", "com.apple.quarantine", path], { encoding: "utf8", timeout: 2000, stdio: ["ignore", "pipe", "ignore"] }).trim();
|
|
99
|
+
}
|
|
100
|
+
catch {
|
|
101
|
+
return undefined;
|
|
102
|
+
}
|
|
103
|
+
if (!q)
|
|
104
|
+
return undefined;
|
|
105
|
+
// flags;timestamp;agent name;event id
|
|
106
|
+
const agent = q.split(";")[2] || undefined;
|
|
107
|
+
let from;
|
|
108
|
+
try {
|
|
109
|
+
const where = execFileSync("/usr/bin/mdls", ["-raw", "-name", "kMDItemWhereFroms", path], { encoding: "utf8", timeout: 2000, stdio: ["ignore", "pipe", "ignore"] });
|
|
110
|
+
from = where.match(/https?:\/\/[^\s",)]+/)?.[0];
|
|
111
|
+
}
|
|
112
|
+
catch { /* the attribute alone is enough */ }
|
|
113
|
+
return { agent, from };
|
|
114
|
+
}
|
package/dist/src/qr.d.ts
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a QR code (or any barcode with a text payload) would do if it were followed.
|
|
3
|
+
*
|
|
4
|
+
* A person cannot read a QR code. They see a square and whatever caption sits beside it; the payload is
|
|
5
|
+
* for the machine. So the payload is judged for what it is: a link, or an action (join this Wi-Fi network,
|
|
6
|
+
* add this one-time-code secret, send this text message, pay this account, open this app), or plain text.
|
|
7
|
+
* Nothing here opens, fetches or performs anything.
|
|
8
|
+
*/
|
|
9
|
+
export type QrKind = "link" | "wifi" | "otp-secret" | "sms" | "phone" | "email" | "payment" | "contact" | "event" | "location" | "app-link" | "text";
|
|
10
|
+
export interface QrVerdict {
|
|
11
|
+
kind: QrKind;
|
|
12
|
+
/** one sentence a person can act on */
|
|
13
|
+
summary: string;
|
|
14
|
+
/** following it does something, rather than showing something */
|
|
15
|
+
action: boolean;
|
|
16
|
+
/** 0 to 1: how much care it needs */
|
|
17
|
+
risk: number;
|
|
18
|
+
/** for links: the host, to be fetched only through the gate */
|
|
19
|
+
host?: string;
|
|
20
|
+
url?: string;
|
|
21
|
+
/** free text carried by the payload (the whole payload for "text"; a message body for sms and email), to be scanned as content */
|
|
22
|
+
text?: string;
|
|
23
|
+
notes: string[];
|
|
24
|
+
}
|
|
25
|
+
export declare function judgeQrPayload(payload: string): QrVerdict;
|
package/dist/src/qr.js
ADDED
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a QR code (or any barcode with a text payload) would do if it were followed.
|
|
3
|
+
*
|
|
4
|
+
* A person cannot read a QR code. They see a square and whatever caption sits beside it; the payload is
|
|
5
|
+
* for the machine. So the payload is judged for what it is: a link, or an action (join this Wi-Fi network,
|
|
6
|
+
* add this one-time-code secret, send this text message, pay this account, open this app), or plain text.
|
|
7
|
+
* Nothing here opens, fetches or performs anything.
|
|
8
|
+
*/
|
|
9
|
+
const PAY_SCHEMES = /^(?:bitcoin|bitcoincash|ethereum|litecoin|dogecoin|monero|solana|lightning|upi|paypal|venmo|cashapp|swish|bezahlcode|pix|alipays?|weixin|wxp)$/i;
|
|
10
|
+
const WEB = /^https?$/i;
|
|
11
|
+
function hostNotes(u) {
|
|
12
|
+
const n = [];
|
|
13
|
+
if (u.username || u.password)
|
|
14
|
+
n.push("the address carries a user name or password before the host, which hides where it really goes");
|
|
15
|
+
if (/^xn--|\.xn--/.test(u.hostname))
|
|
16
|
+
n.push("the host is an international name that may imitate another");
|
|
17
|
+
if (/^\d{1,3}(?:\.\d{1,3}){3}$|^\[/.test(u.hostname))
|
|
18
|
+
n.push("the host is a bare network address, not a name");
|
|
19
|
+
if (u.protocol === "http:")
|
|
20
|
+
n.push("the link is not encrypted");
|
|
21
|
+
if (/^(?:bit\.ly|t\.co|tinyurl\.com|goo\.gl|is\.gd|ow\.ly|buff\.ly|rebrand\.ly|cutt\.ly|qrco\.de|qr\.link|l\.ead\.me|s\.id|shorturl\.at|rb\.gy|t\.ly)$/i.test(u.hostname))
|
|
22
|
+
n.push("the link is a shortener: where it ends up is not visible here");
|
|
23
|
+
if (u.search.length > 200)
|
|
24
|
+
n.push(`the link carries ${u.search.length} characters of query data`);
|
|
25
|
+
return n;
|
|
26
|
+
}
|
|
27
|
+
export function judgeQrPayload(payload) {
|
|
28
|
+
const p = payload.trim();
|
|
29
|
+
const notes = [];
|
|
30
|
+
// Wi-Fi: WIFI:T:WPA;S:name;P:password;H:true;;
|
|
31
|
+
if (/^WIFI:/i.test(p)) {
|
|
32
|
+
const f = Object.fromEntries([...p.slice(5).matchAll(/([A-Z]):((?:\\.|[^;\\])*)/gi)].map((m) => [m[1].toUpperCase(), m[2].replace(/\\(.)/g, "$1")]));
|
|
33
|
+
if (!f.T || /^nopass$/i.test(f.T))
|
|
34
|
+
notes.push("the network has no password: anyone nearby can read its traffic");
|
|
35
|
+
if (/^true$/i.test(f.H ?? ""))
|
|
36
|
+
notes.push("the network is hidden");
|
|
37
|
+
return { kind: "wifi", action: true, risk: 0.6, summary: `joins the Wi-Fi network "${(f.S ?? "").slice(0, 64)}". A device that joins a network sends its traffic through whoever runs it`, notes };
|
|
38
|
+
}
|
|
39
|
+
// one-time-code secrets: scanning adds an authenticator entry; reading it gives away the secret
|
|
40
|
+
if (/^otpauth(?:-migration)?:\/\//i.test(p)) {
|
|
41
|
+
let label = "";
|
|
42
|
+
try {
|
|
43
|
+
label = decodeURIComponent(new URL(p).pathname.replace(/^\/+/, "")).slice(0, 80);
|
|
44
|
+
}
|
|
45
|
+
catch { /* shown without a label */ }
|
|
46
|
+
return { kind: "otp-secret", action: true, risk: 0.9, summary: `carries a one-time-code secret${label ? ` for "${label}"` : ""}. Whoever reads it can generate that account's sign-in codes: it must never be copied anywhere`, notes };
|
|
47
|
+
}
|
|
48
|
+
if (/^(?:smsto|sms|mms|mmsto):/i.test(p)) {
|
|
49
|
+
const m = p.match(/^(?:smsto|sms|mms|mmsto):\/{0,2}([^:?]*)[:?]?(?:body=)?([\s\S]*)$/i);
|
|
50
|
+
let body = m?.[2] ?? "";
|
|
51
|
+
try {
|
|
52
|
+
body = decodeURIComponent(body);
|
|
53
|
+
}
|
|
54
|
+
catch { /* as written */ }
|
|
55
|
+
if (/^\d{3,6}$/.test((m?.[1] ?? "").replace(/\D/g, "")))
|
|
56
|
+
notes.push("the number is a short code: messages to short codes can subscribe to paid services");
|
|
57
|
+
return { kind: "sms", action: true, risk: 0.6, summary: `writes a text message to ${(m?.[1] ?? "a number").slice(0, 40)}${body ? " with the words already filled in" : ""}`, text: body || undefined, notes };
|
|
58
|
+
}
|
|
59
|
+
if (/^tel:/i.test(p)) {
|
|
60
|
+
const num = p.slice(4);
|
|
61
|
+
if (/[*#]/.test(num))
|
|
62
|
+
notes.push("the number contains * or #: such codes can change phone settings such as call forwarding");
|
|
63
|
+
return { kind: "phone", action: true, risk: /[*#]/.test(num) ? 0.7 : 0.4, summary: `dials ${num.slice(0, 40)}`, notes };
|
|
64
|
+
}
|
|
65
|
+
if (/^(?:mailto:|MATMSG:)/i.test(p)) {
|
|
66
|
+
let body = "";
|
|
67
|
+
try {
|
|
68
|
+
const u = new URL(p.replace(/^MATMSG:/i, "mailto:"));
|
|
69
|
+
body = [u.searchParams.get("subject"), u.searchParams.get("body")].filter(Boolean).join("\n");
|
|
70
|
+
}
|
|
71
|
+
catch {
|
|
72
|
+
body = p.match(/BODY:([^;]*)/i)?.[1] ?? "";
|
|
73
|
+
}
|
|
74
|
+
return { kind: "email", action: true, risk: 0.4, summary: `writes an email${body ? " with the words already filled in" : ""}`, text: body || undefined, notes };
|
|
75
|
+
}
|
|
76
|
+
if (/^BEGIN:VCARD/i.test(p) || /^MECARD:/i.test(p))
|
|
77
|
+
return { kind: "contact", action: true, risk: 0.3, summary: "adds a contact to the address book", text: p.slice(0, 2000), notes };
|
|
78
|
+
if (/^BEGIN:VEVENT|^BEGIN:VCALENDAR/i.test(p))
|
|
79
|
+
return { kind: "event", action: true, risk: 0.4, summary: "adds an event to the calendar", text: p.slice(0, 4000), notes };
|
|
80
|
+
if (/^geo:/i.test(p))
|
|
81
|
+
return { kind: "location", action: false, risk: 0.1, summary: "opens a place on a map", notes };
|
|
82
|
+
// European bank transfer codes: "BCD" on the first line
|
|
83
|
+
if (/^BCD\r?\n\d{3}\r?\n/.test(p))
|
|
84
|
+
return { kind: "payment", action: true, risk: 0.8, summary: "starts a bank transfer with the recipient and amount already filled in", notes };
|
|
85
|
+
const scheme = p.match(/^([a-z][a-z0-9+.-]{1,31}):/i)?.[1];
|
|
86
|
+
if (scheme && WEB.test(scheme)) {
|
|
87
|
+
try {
|
|
88
|
+
const u = new URL(p);
|
|
89
|
+
notes.push(...hostNotes(u));
|
|
90
|
+
return { kind: "link", action: false, risk: Math.min(0.7, 0.15 + notes.length * 0.2), summary: `links to ${u.hostname}`, host: u.hostname.toLowerCase(), url: u.toString(), notes };
|
|
91
|
+
}
|
|
92
|
+
catch {
|
|
93
|
+
return { kind: "link", action: false, risk: 0.5, summary: "holds a web address that does not parse", notes: ["an address that parsers read differently is a common way to disguise a destination"] };
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
if (scheme && PAY_SCHEMES.test(scheme))
|
|
97
|
+
return { kind: "payment", action: true, risk: 0.8, summary: `starts a payment (${scheme.toLowerCase()}) with the recipient already filled in`, notes };
|
|
98
|
+
if (scheme && !/^(?:urn|data|javascript|file|about|blob)$/i.test(scheme) && /^[a-z][a-z0-9+.-]*:\/\//i.test(p)) {
|
|
99
|
+
return { kind: "app-link", action: true, risk: 0.5, summary: `opens an app through the "${scheme.toLowerCase()}:" scheme, with instructions for that app in the link`, text: p.slice(0, 2000), notes };
|
|
100
|
+
}
|
|
101
|
+
if (scheme && /^(?:javascript|data|file)$/i.test(scheme))
|
|
102
|
+
return { kind: "app-link", action: true, risk: 0.9, summary: `holds a "${scheme.toLowerCase()}:" address, which runs or opens content directly`, text: p.slice(0, 2000), notes };
|
|
103
|
+
// a bare domain is still a link once a scanner helps
|
|
104
|
+
if (/^(?:www\.)?[a-z0-9-]+(?:\.[a-z0-9-]+)+(?:\/\S*)?$/i.test(p) && !/\s/.test(p)) {
|
|
105
|
+
try {
|
|
106
|
+
const u = new URL(`https://${p}`);
|
|
107
|
+
notes.push(...hostNotes(u));
|
|
108
|
+
return { kind: "link", action: false, risk: 0.2 + notes.length * 0.2, summary: `links to ${u.hostname}`, host: u.hostname.toLowerCase(), url: u.toString(), notes };
|
|
109
|
+
}
|
|
110
|
+
catch { /* plain text */ }
|
|
111
|
+
}
|
|
112
|
+
return { kind: "text", action: false, risk: 0.1, summary: `holds ${p.length} characters of text`, text: p.slice(0, 8000), notes };
|
|
113
|
+
}
|
|
@@ -0,0 +1,61 @@
|
|
|
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
|
+
export interface PersistenceHit {
|
|
18
|
+
/** what kind of standing change this is */
|
|
19
|
+
kind: "scheduled-job" | "startup-item" | "automation" | "mail-rule" | "hook" | "agent-instructions" | "agent-config" | "remote-access" | "webhook";
|
|
20
|
+
/** short explanation for the person */
|
|
21
|
+
why: string;
|
|
22
|
+
}
|
|
23
|
+
/** Does this action create or change something that acts later? `strings` are the argument strings and keys. */
|
|
24
|
+
export declare function persistenceShapes(tool: string, strings: readonly string[]): PersistenceHit[];
|
|
25
|
+
/** A marker with no meaning anywhere else: 96 random bits, so it never appears by accident. */
|
|
26
|
+
export declare function newCanary(): string;
|
|
27
|
+
/** The sentence placed in the agent's context with the marker. */
|
|
28
|
+
export declare function canaryNotice(canary: string): string;
|
|
29
|
+
/** True when any argument string carries the marker, plainly or through a common encoding. */
|
|
30
|
+
export declare function carriesCanary(strings: readonly string[], canaries: readonly string[]): boolean;
|
|
31
|
+
export interface BurstPolicy {
|
|
32
|
+
/** side effects a run may perform per minute before the next one needs a person */
|
|
33
|
+
perMinute: number;
|
|
34
|
+
/** times the very same action (tool and arguments) may run in ten minutes before the next one needs a person */
|
|
35
|
+
sameAction: number;
|
|
36
|
+
}
|
|
37
|
+
export declare const DEFAULT_BURST: BurstPolicy;
|
|
38
|
+
export declare class BurstCounter {
|
|
39
|
+
private at;
|
|
40
|
+
private same;
|
|
41
|
+
/** record one side effect that ran */
|
|
42
|
+
record(digestKey: string, now: number): void;
|
|
43
|
+
/** reasons the next action should wait for a person; empty when it is within limits */
|
|
44
|
+
check(digestKey: string, now: number, p: BurstPolicy): string[];
|
|
45
|
+
export(): {
|
|
46
|
+
at: number[];
|
|
47
|
+
same: Array<[string, number[]]>;
|
|
48
|
+
};
|
|
49
|
+
import(d: {
|
|
50
|
+
at?: unknown;
|
|
51
|
+
same?: unknown;
|
|
52
|
+
} | undefined): void;
|
|
53
|
+
private trim;
|
|
54
|
+
}
|
|
55
|
+
/** the same action whatever run it is in: tool and canonical arguments */
|
|
56
|
+
export declare const actionKey: (tool: string, canonicalArgs: string) => string;
|
|
57
|
+
/** Why everything is stopped, or undefined when it is not. Any readable file there counts, even an empty one. */
|
|
58
|
+
export declare function stopReason(dir?: string): string | undefined;
|
|
59
|
+
/** Stop every action routed through any broker on this machine that uses this state folder. */
|
|
60
|
+
export declare function engageStop(reason: string, dir?: string, now?: Date): string;
|
|
61
|
+
export declare function clearStop(dir?: string): boolean;
|