@acepaste/ingress 0.7.0 → 0.9.0

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.
@@ -11,19 +11,21 @@
11
11
  * hostile -> refuse. Not overridable at runtime. Logged.
12
12
  */
13
13
  import { createHash, createHmac, randomBytes, createPrivateKey, createPublicKey, generateKeyPairSync, sign as cryptoSign, verify as cryptoVerify } from "node:crypto";
14
- import { acquire, AcquireError } from "./acquire.js";
14
+ import { acquire, acquireWithBrowser, AcquireError, HONEST_USER_AGENT } from "./acquire.js";
15
15
  import { analyzeHtml, rulesFromCss, colorRulesFromCss } from "./visibility.js";
16
16
  import { scanCharacters } from "./character.js";
17
17
  import { countHostileInvisibles } from "./acepaste-alphabet.js";
18
18
  import { analyzeScripts } from "./script.js";
19
19
  import { scanMeaning, neutralizeMeaning } from "./meaning.js";
20
20
  import { scanSupplyChain } from "./supplychain.js";
21
+ import { scanCode } from "./codepass.js";
21
22
  import { scanSecrets, redactSecrets, collectSecrets, scrubExcerpt } from "./secrets.js";
22
23
  import { attachEvidence } from "./evidence.js";
23
24
  import { adaptJavascript, adaptJson, adaptMarkdown, adaptText, decodeEntities, detectKind } from "./adapters.js";
24
25
  import { runSandbox } from "./sandbox.js";
25
26
  import { DEFAULT_CONFIG, ENGINE_VERSION, RULESET_VERSION, } from "./types.js";
26
27
  const sha256 = (s) => createHash("sha256").update(s, "utf8").digest("hex");
28
+ export const ASSEMBLED_LIMITS = { fragments: 32, fragmentBytes: 64_000, assembledBytes: 256_000 };
27
29
  export class IngressEngine {
28
30
  config;
29
31
  cache = new Map();
@@ -46,12 +48,21 @@ export class IngressEngine {
46
48
  now: deps.now ?? (() => new Date()),
47
49
  log: deps.log ?? ((e) => process.stderr.write(JSON.stringify(e) + "\n")),
48
50
  sandboxImpl: deps.sandboxImpl ?? runSandbox,
51
+ browserAcquireImpl: deps.browserAcquireImpl ?? acquireWithBrowser,
52
+ random: deps.random ?? Math.random,
53
+ sleep: deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms))),
49
54
  };
55
+ const [jmin, jmax] = this.config.cloakingJitterMs;
56
+ if (!(jmin >= 0 && jmax >= jmin))
57
+ throw new Error("IngressEngine: cloakingJitterMs must be [min, max] with 0 <= min <= max");
50
58
  }
51
59
  /** Gate a URL: policy check, acquire (twice when cloaking check is on), analyze, decide. */
52
60
  async fetch(url, opts = {}) {
53
61
  const t0 = performance.now();
54
62
  const timings = {};
63
+ const preQ = opts.quarantined ?? opts.quarantineCheck?.(url);
64
+ if (preQ)
65
+ return this.refuse(url, [{ pass: "policy", kind: "policy.denied_source", confidence: 1, severity: 1, message: `source is quarantined by your organization: ${preQ}`, action: "none" }], timings, t0, "text", "hostile", true);
55
66
  const cached = this.cacheGet(url, opts);
56
67
  if (cached)
57
68
  return cached;
@@ -61,28 +72,57 @@ export class IngressEngine {
61
72
  return this.refuse(url, [{ pass: "policy", kind: "policy.denied_source", confidence: 1, severity: 1, message: `source ${hostOf(url)} is denied by policy`, action: "none" }], timings, t0, "text");
62
73
  }
63
74
  const cloaking = rule?.cloakingCheck ?? this.config.cloakingCheck;
75
+ // Two fetches, told apart only by what they present. The agent fetch wears the user agent of a
76
+ // real AI assistant's fetcher (that is what agent-targeted cloaking keys on). The human fetch looks
77
+ // like desktop Chrome, optionally through a different network (humanProxy) and optionally in a real
78
+ // browser (humanFetch: "browser"). Which goes first and the gap between them are random, so the pair
79
+ // does not arrive as a simultaneous, identically-timed signature.
80
+ const agentUA = this.pickAgentUserAgent();
81
+ const fetchAgent = () => acquire(url, "agent", this.config, this.config.net, this.deps.fetchImpl, this.deps.resolver, { userAgent: agentUA });
82
+ const fetchHuman = () => this.config.humanFetch === "browser"
83
+ ? this.deps.browserAcquireImpl(url, this.config, this.config.net, this.deps.resolver, { proxyUrl: this.config.humanProxy })
84
+ : acquire(url, "human", this.config, this.config.net, this.deps.fetchImpl, this.deps.resolver, { proxyUrl: this.config.humanProxy });
85
+ const findings = [];
64
86
  let agentRes, humanRes;
65
- try {
66
- const ta = performance.now();
67
- if (cloaking) {
68
- [agentRes, humanRes] = await Promise.all([
69
- acquire(url, "agent", this.config, this.config.net, this.deps.fetchImpl, this.deps.resolver),
70
- acquire(url, "human", this.config, this.config.net, this.deps.fetchImpl, this.deps.resolver),
71
- ]);
87
+ const ta = performance.now();
88
+ if (cloaking) {
89
+ const [jmin, jmax] = this.config.cloakingJitterMs;
90
+ const gap = Math.round(jmin + this.deps.random() * (jmax - jmin));
91
+ const humanFirst = this.deps.random() < 0.5;
92
+ const later = (f) => this.deps.sleep(gap).then(f);
93
+ const [agentS, humanS] = await Promise.allSettled(humanFirst ? [later(fetchAgent), fetchHuman()] : [fetchAgent(), later(fetchHuman)]);
94
+ timings.acquire = performance.now() - ta;
95
+ if (agentS.status === "rejected") {
96
+ if (agentS.reason instanceof AcquireError)
97
+ return this.refuseOnAcquire(url, agentS.reason, timings, t0);
98
+ throw agentS.reason;
72
99
  }
100
+ agentRes = agentS.value;
101
+ if (humanS.status === "fulfilled")
102
+ humanRes = humanS.value;
73
103
  else {
74
- agentRes = await acquire(url, "agent", this.config, this.config.net, this.deps.fetchImpl, this.deps.resolver);
104
+ // the page itself was fetched; only the comparison is missing. Recorded, weightless.
105
+ findings.push({ pass: "acquire", kind: "acquire.cloaking_check_incomplete", confidence: 0, severity: 0, message: `cloaking check skipped: the browser-fingerprint fetch failed (${humanS.reason?.message ?? "unknown"})`, action: "none" });
106
+ }
107
+ }
108
+ else {
109
+ try {
110
+ agentRes = await fetchAgent();
111
+ }
112
+ catch (e) {
113
+ if (e instanceof AcquireError)
114
+ return this.refuseOnAcquire(url, e, timings, t0);
115
+ throw e;
75
116
  }
76
117
  timings.acquire = performance.now() - ta;
77
118
  }
78
- catch (e) {
79
- if (e instanceof AcquireError)
80
- return this.refuseOnAcquire(url, e, timings, t0);
81
- throw e;
119
+ if (opts.quarantineCheck) {
120
+ for (const hop of [...agentRes.redirectChain, agentRes.finalUrl]) {
121
+ const q = opts.quarantineCheck(hop);
122
+ if (q)
123
+ return this.refuse(url, [{ pass: "policy", kind: "policy.denied_source", confidence: 1, severity: 1, message: `redirected to a source quarantined by your organization: ${q}`, action: "none" }], timings, t0, "text", "hostile", true);
124
+ }
82
125
  }
83
- if (!agentRes)
84
- throw new Error("acquire returned nothing");
85
- const findings = [];
86
126
  if (agentRes.redirectChain.length) {
87
127
  const hosts = new Set(agentRes.redirectChain.concat(agentRes.finalUrl).map(hostOf));
88
128
  if (hosts.size > 2)
@@ -91,6 +131,26 @@ export class IngressEngine {
91
131
  if (finalRule?.deny)
92
132
  return this.refuse(url, [{ pass: "policy", kind: "policy.denied_source", confidence: 1, severity: 1, message: `redirect target ${hostOf(agentRes.finalUrl)} is denied by policy`, action: "none" }], timings, t0, "text");
93
133
  }
134
+ // Many sites refuse AI-assistant user agents outright. When the browser fetch got through, fetch
135
+ // once more under the gate's own name so the page can still be read and compared.
136
+ if (cloaking && [401, 403, 429].includes(agentRes.status) && humanRes && humanRes.status < 400 && agentUA !== HONEST_USER_AGENT) {
137
+ try {
138
+ const retry = await acquire(url, "agent", this.config, this.config.net, this.deps.fetchImpl, this.deps.resolver, { userAgent: HONEST_USER_AGENT });
139
+ findings.push({ pass: "acquire", kind: "acquire.ai_agent_refused", confidence: 0, severity: 0, message: `the site refused an AI-assistant user agent (HTTP ${agentRes.status}); fetched again as AcePaste Ingress (HTTP ${retry.status})`, action: "none" });
140
+ agentRes = retry;
141
+ }
142
+ catch { /* keep the refusal */ }
143
+ }
144
+ // An error page is not the page. If the site refused the AI fetcher (many block AI user agents or
145
+ // challenge non-browsers), there is nothing to deliver and nothing to compare: unreachable, not an attack.
146
+ if (agentRes.status >= 400) {
147
+ const both = humanRes ? `; the browser fetch got HTTP ${humanRes.status}` : "";
148
+ return this.refuse(url, [{ pass: "acquire", kind: "acquire.unreachable", confidence: 0, severity: 0, message: `the site answered the AI fetcher with HTTP ${agentRes.status}${both}`, action: "none" }], timings, t0, "text", "unreachable");
149
+ }
150
+ if (humanRes && humanRes.status >= 400) {
151
+ findings.push({ pass: "acquire", kind: "acquire.cloaking_check_incomplete", confidence: 0, severity: 0, message: `cloaking check skipped: the browser-fingerprint fetch got HTTP ${humanRes.status}`, action: "none" });
152
+ humanRes = undefined;
153
+ }
94
154
  const kind = detectKind(agentRes.contentType, agentRes.body, agentRes.finalUrl);
95
155
  // external stylesheets (same origin only, bounded)
96
156
  let externalRules = [];
@@ -102,7 +162,7 @@ export class IngressEngine {
102
162
  }
103
163
  const result = await this.guarded(url, kind, t0, () => this.analyze({
104
164
  url, finalUrl: agentRes.finalUrl, redirectChain: agentRes.redirectChain, raw: agentRes.body, kind,
105
- humanRaw: humanRes?.body, externalRules, externalColorRules, timings, t0, override: !!opts.override, extraFindings: findings, rule,
165
+ humanRaw: humanRes?.body, humanContentType: humanRes?.contentType, externalRules, externalColorRules, timings, t0, override: !!opts.override, extraFindings: findings, rule,
106
166
  }));
107
167
  this.cacheSet(url, opts, result);
108
168
  return result;
@@ -111,6 +171,8 @@ export class IngressEngine {
111
171
  async scan(content, opts = {}) {
112
172
  const t0 = performance.now();
113
173
  const url = opts.url ?? "inline:";
174
+ if (opts.quarantined)
175
+ return this.refuse(url, [{ pass: "policy", kind: "policy.denied_source", confidence: 1, severity: 1, message: `source is quarantined by your organization: ${opts.quarantined}`, action: "none" }], {}, t0, "text", "hostile", true);
114
176
  const bytes = Buffer.byteLength(content, "utf8");
115
177
  if (bytes > this.config.maxBodyBytes) {
116
178
  return this.refuse(url, [{ pass: "policy", kind: "policy.denied_source", confidence: 0.5, severity: 0.5, message: `content is ${bytes} bytes, over the ${this.config.maxBodyBytes} byte limit`, action: "none" }], {}, t0, "text");
@@ -119,6 +181,35 @@ export class IngressEngine {
119
181
  const rule = url.startsWith("inline:") ? undefined : this.domainRule(url);
120
182
  return this.guarded(url, kind, t0, () => this.analyze({ url, finalUrl: url, redirectChain: [], raw: content, kind, externalRules: [], timings: {}, t0, override: !!opts.override, extraFindings: [], rule }));
121
183
  }
184
+ /**
185
+ * Gate what the model will actually receive when several sources are combined (search
186
+ * results, retrieved chunks, several tool results). An instruction can be split so each
187
+ * fragment looks harmless alone: each fragment is gated, then the text that would be
188
+ * delivered from all of them together is gated as one. `composedOnly` is true when the
189
+ * combination is worse than every fragment on its own.
190
+ */
191
+ async scanAssembled(fragments) {
192
+ if (!fragments.length || fragments.length > ASSEMBLED_LIMITS.fragments)
193
+ throw new Error(`scanAssembled: between 1 and ${ASSEMBLED_LIMITS.fragments} fragments`);
194
+ for (const f of fragments) {
195
+ if (!f.sourceId || Buffer.byteLength(f.sourceId, "utf8") > 256)
196
+ throw new Error("scanAssembled: each fragment needs a sourceId of at most 256 bytes");
197
+ if (Buffer.byteLength(f.text, "utf8") > ASSEMBLED_LIMITS.fragmentBytes)
198
+ throw new Error(`scanAssembled: fragment ${f.sourceId} is over ${ASSEMBLED_LIMITS.fragmentBytes} bytes`);
199
+ }
200
+ const results = [];
201
+ for (const f of fragments)
202
+ results.push(await this.scan(f.text, { url: `inline:${f.sourceId}`, isHtml: f.isHtml, contentType: f.contentType }));
203
+ // the combined representation: what each clean fragment would deliver, joined in order
204
+ const joined = results.filter((r) => r.tier === "clean").map((r) => r.delivered).join("\n");
205
+ if (Buffer.byteLength(joined, "utf8") > ASSEMBLED_LIMITS.assembledBytes)
206
+ throw new Error(`scanAssembled: combined text is over ${ASSEMBLED_LIMITS.assembledBytes} bytes`);
207
+ const assembled = await this.scan(joined, { url: "inline:assembled", isHtml: false });
208
+ const rank = (t) => ({ clean: 0, unreachable: 0, suspect: 1, hostile: 2 })[t];
209
+ const worstFragment = results.reduce((m, r) => Math.max(m, rank(r.tier)), 0);
210
+ const tier = ["clean", "suspect", "hostile"][Math.max(worstFragment, rank(assembled.tier))];
211
+ return { tier, composedOnly: rank(assembled.tier) > worstFragment, fragments: results, assembled, sha256: sha256(joined), delivered: tier === "clean" ? joined : "" };
212
+ }
122
213
  /** Any analysis failure is a refusal, never a pass: the gate fails closed. */
123
214
  async guarded(url, kind, t0, run) {
124
215
  try {
@@ -202,14 +293,25 @@ export class IngressEngine {
202
293
  // cloaking: compare visible text under the two fingerprints
203
294
  if (a.humanRaw !== undefined) {
204
295
  const tc = performance.now();
205
- const humanVisible = a.kind === "html" ? analyzeHtml(a.humanRaw, a.externalRules, a.externalColorRules ?? []).visibleText : a.humanRaw;
206
- const sim = jaccardWords(visibleText, humanVisible);
207
- if (sim < 0.6 && (visibleText.length > 200 || humanVisible.length > 200)) {
296
+ // The two fetches may legitimately get different formats (a site that hands agents Markdown and
297
+ // browsers HTML). Compare words, not markup: the question is whether the agent was told anything
298
+ // the person would not have seen.
299
+ const humanKind = detectKind(a.humanContentType ?? "", a.humanRaw, a.finalUrl);
300
+ // Against everything in the browser's copy, hidden or not: cloaking means the agent got words the
301
+ // browser was never sent. (Text the browser got but hides is the visibility pass's business, and
302
+ // static CSS analysis can wrongly mark a JavaScript-revealed page as hidden.)
303
+ const humanText = humanKind === "html" ? analyzeHtml(a.humanRaw, a.externalRules, a.externalColorRules ?? []).segments.map((x) => x.text).join(" ") : a.humanRaw;
304
+ const cmp = compareServed(visibleText, humanText);
305
+ // two bands: most of the agent's page is unseen by the browser (a different page), or a solid
306
+ // block of it is (the usual cloaking move: the real page plus a passage only the AI receives)
307
+ const wholesale = cmp.agentWords >= 30 && cmp.agentOnlyShare > 0.4 && cmp.agentOnlyWords >= 15;
308
+ const block = cmp.agentOnlyWords >= 25 && cmp.agentOnlyShare >= 0.15 && cmp.longestAgentOnlyRun >= 12;
309
+ if (wholesale || block) {
208
310
  findings.push({
209
311
  pass: "cloaking", kind: "cloaking.agent_targeted_divergence",
210
- confidence: Math.min(0.95, 0.5 + (0.6 - sim)), severity: 0.9,
211
- message: `page served to an agent fingerprint shares only ${(sim * 100).toFixed(0)}% of its words with the page served to a browser fingerprint`,
212
- excerpt: diffSample(visibleText, humanVisible), action: "none",
312
+ confidence: wholesale ? Math.min(0.95, 0.5 + (cmp.agentOnlyShare - 0.4)) : Math.min(0.6, 0.3 + cmp.agentOnlyShare / 2), severity: 0.9,
313
+ message: `${(cmp.agentOnlyShare * 100).toFixed(0)}% of the words served to an AI fetcher do not appear on the page served to a browser`,
314
+ excerpt: `agent-only words: ${cmp.sample}`, action: "none",
213
315
  });
214
316
  }
215
317
  timings.cloaking = performance.now() - tc;
@@ -260,10 +362,16 @@ export class IngressEngine {
260
362
  }
261
363
  // supply-chain pass (underlight lineage): manifests, lockfiles, install commands
262
364
  const tsc = performance.now();
263
- const sc = scanSupplyChain({ kind: a.kind, raw, segments: cleanedSegments, decodedPayloads: charAll.decodedPayloads });
365
+ const sc = scanSupplyChain({ kind: a.kind, raw, segments: cleanedSegments, decodedPayloads: charAll.decodedPayloads, pageHost: a.finalUrl.startsWith("inline:") ? undefined : hostOf(a.finalUrl) });
264
366
  findings.push(...sc);
265
367
  timings.supplychain = performance.now() - tsc;
266
368
  passesRun.push("supplychain");
369
+ // code behavior pass: what code the model receives would do
370
+ const tcode = performance.now();
371
+ const codeScan = scanCode({ kind: a.kind, raw, segments: cleanedSegments, decodedPayloads: charAll.decodedPayloads });
372
+ findings.push(...codeScan.findings);
373
+ timings.code = performance.now() - tcode;
374
+ passesRun.push("code");
267
375
  // meaning pass over cleaned segments and decoded payloads
268
376
  const tm = performance.now();
269
377
  findings.push(...scanMeaning({ segments: cleanedSegments, decodedPayloads: charAll.decodedPayloads }));
@@ -299,7 +407,7 @@ export class IngressEngine {
299
407
  // evidence model (Kith & Revere lineage): class, band, cited artifact, benign alternative
300
408
  attachEvidence(findings, sha256(a.raw));
301
409
  // score and tier (per-domain thresholds override)
302
- const score = aggregate(findings);
410
+ const score = aggregate(findings, { cloakingCompared: passesRun.includes("cloaking") });
303
411
  const hostileAt = a.rule?.hostileThreshold ?? this.config.hostileThreshold;
304
412
  const suspectAt = a.rule?.suspectThreshold ?? this.config.suspectThreshold;
305
413
  const tier = score >= hostileAt ? "hostile" : score >= suspectAt ? "suspect" : "clean";
@@ -319,7 +427,7 @@ export class IngressEngine {
319
427
  timings.total = performance.now() - a.t0;
320
428
  if (tier !== "clean")
321
429
  this.deps.log(buildLogEntry(a.finalUrl, tier, score, findings, safePayloads, receipt, overridden));
322
- return { tier, score, contentKind: a.kind, delivered, envelope, findings, receipt, timings, overridden };
430
+ return { tier, score, contentKind: a.kind, delivered, envelope, findings, receipt, timings, overridden, coverage: { code: codeScan.coverage } };
323
431
  }
324
432
  async fetchStylesheets(html, baseUrl) {
325
433
  const rules = [];
@@ -361,19 +469,33 @@ export class IngressEngine {
361
469
  return p.startsWith(".") ? host === p.slice(1) || host.endsWith(p) : host === p;
362
470
  });
363
471
  }
364
- refuse(url, findings, timings, t0, kind) {
472
+ refuse(url, findings, timings, t0, kind, tier = "hostile", quarantine = false) {
365
473
  attachEvidence(findings, sha256(""));
366
- const receipt = this.receipt({ url, finalUrl: url, redirectChain: [], kind, raw: "", delivered: "", tier: "hostile", score: 1, findings, overridden: false, passesRun: ["policy"], acepasteInvisibleCount: 0 });
367
- const envelope = buildEnvelope(url, "hostile", "", findings, receipt, false);
474
+ const score = tier === "hostile" ? 1 : 0;
475
+ const receipt = this.receipt({ url, finalUrl: url, redirectChain: [], kind, raw: "", delivered: "", tier, score, findings, overridden: false, passesRun: tier === "hostile" ? ["policy"] : ["acquire"], acepasteInvisibleCount: 0 });
476
+ const envelope = buildEnvelope(url, tier, "", findings, receipt, false);
368
477
  timings.total = performance.now() - t0;
369
- this.deps.log(buildLogEntry(url, "hostile", 1, findings, [], receipt, false));
370
- return { tier: "hostile", score: 1, contentKind: kind, delivered: "", envelope, findings, receipt, timings, overridden: false };
478
+ // unreachable is not an attack: it goes to the operational log, never to the attack log or public feed
479
+ if (quarantine)
480
+ this.deps.log({ event: "ingress.quarantined", at: this.deps.now().toISOString(), url });
481
+ else if (tier === "hostile")
482
+ this.deps.log(buildLogEntry(url, "hostile", 1, findings, [], receipt, false));
483
+ else
484
+ this.deps.log({ event: "ingress.unreachable", at: this.deps.now().toISOString(), url, reason: findings[0]?.message ?? "" });
485
+ return { tier, score, contentKind: kind, delivered: "", envelope, findings, receipt, timings, overridden: false };
371
486
  }
372
487
  refuseOnAcquire(url, e, timings, t0) {
373
- const f = e.code === "policy"
374
- ? { pass: "acquire", kind: "policy.denied_source", confidence: 1, severity: 1, message: `network policy refused the fetch (${e.policyCode}): ${e.message}`, action: "none" }
375
- : { pass: "acquire", kind: "policy.denied_source", confidence: 0.5, severity: 0.5, message: `acquisition refused (${e.code}): ${e.message}`, action: "none" };
376
- return this.refuse(url, [f], timings, t0, "text");
488
+ // a network-policy refusal (private address, denied port) is the gate doing its job; everything else is the source failing to deliver
489
+ if (e.code === "policy" && e.policyCode !== "unresolvable") {
490
+ return this.refuse(url, [{ pass: "acquire", kind: "policy.denied_source", confidence: 1, severity: 1, message: `network policy refused the fetch (${e.policyCode}): ${e.message}`, action: "none" }], timings, t0, "text");
491
+ }
492
+ return this.refuse(url, [{ pass: "acquire", kind: "acquire.unreachable", confidence: 0, severity: 0, message: `could not fetch or read the source (${e.policyCode ?? e.code}): ${e.message}`, action: "none" }], timings, t0, "text", "unreachable");
493
+ }
494
+ pickAgentUserAgent() {
495
+ const list = this.config.agentUserAgents.filter((u) => typeof u === "string" && u.trim());
496
+ if (!list.length)
497
+ return HONEST_USER_AGENT;
498
+ return list[Math.min(list.length - 1, Math.floor(this.deps.random() * list.length))];
377
499
  }
378
500
  receipt(r) {
379
501
  const ecdsa = this.signer();
@@ -496,16 +618,34 @@ function hostOf(url) {
496
618
  * fact, not twelve attacks)
497
619
  * - noisy-OR across kinds
498
620
  * - hidden text that carries no instruction shape is informational: it is
499
- * not delivered anyway, so visibility-only evidence is capped below the
500
- * hostile line
621
+ * never delivered, so visibility-only evidence is capped below the
622
+ * suspect line. The page passes clean, the hidden text is stripped, and
623
+ * the findings stay on the receipt (ratified 2026-11-03: hidden menus,
624
+ * collapsed sections and screen-reader labels must not refuse a page)
501
625
  * - co-occurrence of hidden-text and meaning findings, cloaking, and
502
626
  * webdriver-keyed divergence each add a bonus
503
627
  */
504
- export function aggregate(findings) {
505
- if (!findings.length)
628
+ /** below the default suspect threshold (0.25), so hidden text alone never refuses */
629
+ export const VISIBILITY_ONLY_CAP = 0.2;
630
+ export function aggregate(findings, ctx = {}) {
631
+ const weighted = findings.filter((f) => f.confidence * f.severity > 0);
632
+ if (!weighted.length)
633
+ return 0;
634
+ const passesAll = new Set(weighted.map((f) => f.pass));
635
+ // Hidden text matters when it carries something: an instruction found inside it, invisible
636
+ // characters, or a browser-observed change. Otherwise it is page furniture (menus, labels,
637
+ // collapsed sections), never delivered, and does not add to the score. It stays on the receipt.
638
+ const hiddenCarries = weighted.some((f) => f.pass === "meaning" && f.inHidden) || passesAll.has("character") || passesAll.has("sandbox");
639
+ // Page scripts are never delivered to the model, only the static text is. Their findings
640
+ // (automation probes, obfuscation, minified bundles) predict that the page shows bots something
641
+ // else. Once the two-fingerprint comparison has run and found no divergence, that prediction is
642
+ // answered, so they do not add to the score.
643
+ const scriptsAnswered = !!ctx.cloakingCompared && !passesAll.has("cloaking") && !passesAll.has("sandbox");
644
+ const scored = weighted.filter((f) => (f.pass !== "visibility" || hiddenCarries || passesAll.size === 1) && (f.pass !== "script" || !scriptsAnswered));
645
+ if (!scored.length)
506
646
  return 0;
507
647
  const byKind = new Map();
508
- for (const f of findings) {
648
+ for (const f of scored) {
509
649
  const p = Math.max(0, Math.min(1, f.confidence * f.severity));
510
650
  const arr = byKind.get(f.kind) ?? [];
511
651
  arr.push(p);
@@ -518,34 +658,41 @@ export function aggregate(findings) {
518
658
  notP *= 1 - Math.min(1, max * bonus);
519
659
  }
520
660
  let score = 1 - notP;
521
- const passes = new Set(findings.map((f) => f.pass));
522
- const onlyVisibility = [...passes].every((p) => p === "visibility");
523
- if (onlyVisibility)
524
- score = Math.min(score, 0.45);
525
- const hiddenAndMeaning = (passes.has("visibility") || passes.has("character") || passes.has("sandbox")) && passes.has("meaning");
661
+ const passes = new Set(scored.map((f) => f.pass));
662
+ if ([...passes].every((p) => p === "visibility"))
663
+ score = Math.min(score, VISIBILITY_ONLY_CAP);
664
+ const hiddenAndMeaning = scored.some((f) => f.pass === "meaning" && f.inHidden) || ((passes.has("character") || passes.has("sandbox")) && passes.has("meaning"));
526
665
  if (hiddenAndMeaning)
527
666
  score = Math.min(1, score + 0.15);
528
667
  if (passes.has("cloaking"))
529
668
  score = Math.min(1, score + 0.1);
530
- if (findings.some((f) => f.kind === "sandbox.webdriver_keyed_divergence"))
669
+ if (scored.some((f) => f.kind === "sandbox.webdriver_keyed_divergence"))
531
670
  score = Math.min(1, score + 0.1);
532
671
  return +score.toFixed(4);
533
672
  }
534
- function jaccardWords(a, b) {
535
- const A = new Set(a.toLowerCase().split(/\W+/).filter((w) => w.length > 2));
536
- const B = new Set(b.toLowerCase().split(/\W+/).filter((w) => w.length > 2));
537
- if (!A.size && !B.size)
538
- return 1;
539
- let inter = 0;
540
- for (const w of A)
541
- if (B.has(w))
542
- inter++;
543
- return inter / (A.size + B.size - inter);
673
+ /** words of served text with markup, link targets and bare URLs removed, so Markdown and HTML of the same page compare equal */
674
+ export function servedWords(text) {
675
+ const t = text
676
+ .replace(/!?\[([^\]]*)\]\([^)]*\)/g, " $1 ") // [label](target) and ![alt](src) -> label
677
+ .replace(/<\/?[a-z][^>]*>/gi, " ") // stray tags
678
+ .replace(/\b(?:https?:\/\/|www\.)\S+/gi, " ") // bare URLs
679
+ .replace(/[#>*_`~|\-]{1,}/g, " "); // markdown syntax
680
+ return t.toLowerCase().split(/[^\p{L}\p{N}']+/u).filter((w) => w.length > 2);
544
681
  }
545
- function diffSample(agent, human) {
546
- const H = new Set(human.toLowerCase().split(/\W+/));
547
- const onlyAgent = agent.split(/\s+/).filter((w) => !H.has(w.toLowerCase())).slice(0, 30).join(" ");
548
- return `agent-only words: ${onlyAgent}`;
682
+ /** how much of what the agent received is absent from what the browser received (word occurrences, not distinct words) */
683
+ export function compareServed(agentText, humanText) {
684
+ const A = servedWords(agentText);
685
+ const H = new Set(servedWords(humanText));
686
+ const only = A.filter((w) => !H.has(w));
687
+ let run = 0, longestAgentOnlyRun = 0;
688
+ for (const w of A) {
689
+ run = H.has(w) ? 0 : run + 1;
690
+ if (run > longestAgentOnlyRun)
691
+ longestAgentOnlyRun = run;
692
+ }
693
+ const sampleSeen = new Set();
694
+ const sample = only.filter((w) => (sampleSeen.has(w) ? false : (sampleSeen.add(w), true))).slice(0, 30).join(" ");
695
+ return { agentWords: A.length, agentOnlyWords: only.length, agentOnlyShare: A.length ? only.length / A.length : 0, longestAgentOnlyRun, sample };
549
696
  }
550
697
  /**
551
698
  * Spotlighting-style envelope. Random boundary so content cannot forge the
@@ -560,6 +707,13 @@ export function buildEnvelope(source, tier, delivered, findings, receipt, overri
560
707
  `verdict: ${tier}${overridden ? " (delivered under human override)" : ""} (score ${receipt.score})`,
561
708
  `receipt: ${receipt.digest.slice(0, 16)} issued ${receipt.issuedAt} engine ${receipt.engineVersion} ruleset ${receipt.rulesetVersion}`,
562
709
  ];
710
+ if (tier === "unreachable") {
711
+ head.push(`content: UNAVAILABLE. The source could not be fetched or read, so nothing was delivered. This is not an attack verdict; the source may be down, slow or not text.`);
712
+ for (const f of findings.slice(0, 2))
713
+ head.push(` - ${f.message}`);
714
+ head.push(`<</acepaste-ingress ${b}>>`);
715
+ return head.join("\n");
716
+ }
563
717
  if (tier === "hostile" || (tier === "suspect" && !overridden)) {
564
718
  head.push(`attack: ${kinds.join(", ")}`);
565
719
  head.push(tier === "hostile"
@@ -1,7 +1,10 @@
1
- export { IngressEngine, aggregate, buildEnvelope, buildLogEntry } from "./engine.js";
2
- export type { EngineDeps, IngressOptions } from "./engine.js";
3
- export { acquire, AcquireError, MAX_REDIRECTS } from "./acquire.js";
4
- export type { FetchLike } from "./acquire.js";
1
+ export { IngressEngine, aggregate, buildEnvelope, buildLogEntry, compareServed, servedWords, VISIBILITY_ONLY_CAP } from "./engine.js";
2
+ export type { EngineDeps, IngressOptions, AssembledResult } from "./engine.js";
3
+ export { ASSEMBLED_LIMITS } from "./engine.js";
4
+ export { acquire, acquireWithBrowser, AcquireError, MAX_REDIRECTS, HONEST_USER_AGENT } from "./acquire.js";
5
+ export type { FetchLike, AcquireOptions } from "./acquire.js";
6
+ export { summarize, findingWeight, cloakingConfigFromEnv } from "./summary.js";
7
+ export type { ResultSummary, FindingGroup, TopFinding } from "./summary.js";
5
8
  export { checkTarget, isPrivateIP, isPrivateIPv4, isPrivateIPv6, NetPolicyError, DEFAULT_NET_POLICY } from "./netpolicy.js";
6
9
  export type { NetPolicy } from "./netpolicy.js";
7
10
  export { analyzeHtml, findStylesheetLinks, rulesFromCss, colorRulesFromCss } from "./visibility.js";
@@ -24,3 +27,14 @@ export { countHostileInvisibles, ACEPASTE_INVISIBLE_SOURCE, ACEPASTE_INVISIBLE_S
24
27
  export * from "./types.js";
25
28
  /** @deprecated renamed to IngressEngine in 0.7.0 (AcePaste Gate -> AcePaste Ingress) */
26
29
  export { IngressEngine as GateEngine } from "./engine.js";
30
+ export { ActionBroker, isSideEffectName, DEFAULT_BROKER_POLICY, canonicalJson, actionDigest, destinationsIn, exfilShapes, describeApproval } from "./broker.js";
31
+ export type { ActionDecision, ActionRule, BrokerPolicy, ProposedAction, ApprovalRequest, Approver, BrokerVerdict, BrokerEvent } from "./broker.js";
32
+ export { macosDialogApprover, callbackApprover, denyAllApprover } from "./approvers.js";
33
+ export { scanMultilingual, MULTILINGUAL_RULES, MULTILINGUAL_RULESET } from "./multilingual.js";
34
+ export { scanCode, extractCodeUnits, guessLang, lex } from "./codepass.js";
35
+ export type { CodeUnit, CodeLang, CodeCoverage } from "./codepass.js";
36
+ export { INSTRUCTION_FILE_PATTERNS, discoverInstructionFiles, readInstructionBytes, approveInstructionFile, checkInstructionFiles, loadInstructionFiles } from "./instructions.js";
37
+ export type { InstructionFile, InstructionCheck, InstructionStatus, ApprovalEntry } from "./instructions.js";
38
+ export { auditEnvironment, formatAudit, readChromiumExtensions } from "./audit.js";
39
+ export type { AuditReport, AuditCheck, AuditOptions } from "./audit.js";
40
+ export * from "./audit-parsers.js";
package/dist/src/index.js CHANGED
@@ -1,5 +1,7 @@
1
- export { IngressEngine, aggregate, buildEnvelope, buildLogEntry } from "./engine.js";
2
- export { acquire, AcquireError, MAX_REDIRECTS } from "./acquire.js";
1
+ export { IngressEngine, aggregate, buildEnvelope, buildLogEntry, compareServed, servedWords, VISIBILITY_ONLY_CAP } from "./engine.js";
2
+ export { ASSEMBLED_LIMITS } from "./engine.js";
3
+ export { acquire, acquireWithBrowser, AcquireError, MAX_REDIRECTS, HONEST_USER_AGENT } from "./acquire.js";
4
+ export { summarize, findingWeight, cloakingConfigFromEnv } from "./summary.js";
3
5
  export { checkTarget, isPrivateIP, isPrivateIPv4, isPrivateIPv6, NetPolicyError, DEFAULT_NET_POLICY } from "./netpolicy.js";
4
6
  export { analyzeHtml, findStylesheetLinks, rulesFromCss, colorRulesFromCss } from "./visibility.js";
5
7
  export { parseColor, contrastRatio, INVISIBLE_CONTRAST } from "./color.js";
@@ -17,3 +19,10 @@ export { countHostileInvisibles, ACEPASTE_INVISIBLE_SOURCE, ACEPASTE_INVISIBLE_S
17
19
  export * from "./types.js";
18
20
  /** @deprecated renamed to IngressEngine in 0.7.0 (AcePaste Gate -> AcePaste Ingress) */
19
21
  export { IngressEngine as GateEngine } from "./engine.js";
22
+ export { ActionBroker, isSideEffectName, DEFAULT_BROKER_POLICY, canonicalJson, actionDigest, destinationsIn, exfilShapes, describeApproval } from "./broker.js";
23
+ export { macosDialogApprover, callbackApprover, denyAllApprover } from "./approvers.js";
24
+ export { scanMultilingual, MULTILINGUAL_RULES, MULTILINGUAL_RULESET } from "./multilingual.js";
25
+ export { scanCode, extractCodeUnits, guessLang, lex } from "./codepass.js";
26
+ export { INSTRUCTION_FILE_PATTERNS, discoverInstructionFiles, readInstructionBytes, approveInstructionFile, checkInstructionFiles, loadInstructionFiles } from "./instructions.js";
27
+ export { auditEnvironment, formatAudit, readChromiumExtensions } from "./audit.js";
28
+ export * from "./audit-parsers.js";
@@ -0,0 +1,84 @@
1
+ /**
2
+ * Instruction-file approval for coding agents.
3
+ *
4
+ * Reading a repository's AGENTS.md to understand a project is one decision; obeying it as
5
+ * guidance is another. A dependency, a pull request or a compromised script can write one.
6
+ * This module finds the files coding agents load as instructions, and serves a file as
7
+ * guidance only when its exact bytes match a version a person approved. Anything else is
8
+ * handed over as untrusted data, gated like web content.
9
+ *
10
+ * Approvals live outside the repository (~/.acepaste-ingress/instruction-approvals.json),
11
+ * each one signed with a local key, and are made only from an interactive terminal
12
+ * (`ingress instructions approve`), never by a tool the model can call.
13
+ *
14
+ * Limits: this is enforcement only where the agent loads instructions through it (the MCP
15
+ * tool, a hook, a wrapper). An agent runtime that reads CLAUDE.md or AGENTS.md natively
16
+ * bypasses it; turn native loading off where the runtime allows. Code running as the same
17
+ * user can read the key and forge approvals. Approval means "this version may be used as
18
+ * project guidance", never "every instruction in it is authorized": tool permissions are
19
+ * still the broker's job.
20
+ */
21
+ /** file names and paths coding agents load as instructions (as of 2026-11) */
22
+ export declare const INSTRUCTION_FILE_PATTERNS: RegExp[];
23
+ export interface InstructionFile {
24
+ relPath: string;
25
+ absPath: string;
26
+ bytes: number;
27
+ sha256: string;
28
+ inDependency: boolean;
29
+ }
30
+ /** walk a repository for instruction files. Dependencies (node_modules, vendor, .venv) are searched too, and marked. */
31
+ export declare function discoverInstructionFiles(root: string, opts?: {
32
+ maxDepth?: number;
33
+ maxFiles?: number;
34
+ maxEntries?: number;
35
+ }): InstructionFile[];
36
+ export interface ApprovalEntry {
37
+ root: string;
38
+ relPath: string;
39
+ sha256: string;
40
+ approvedAt: string;
41
+ approvedBy: string;
42
+ mac: string;
43
+ }
44
+ export interface LedgerOptions {
45
+ dir?: string;
46
+ }
47
+ /** read an instruction file's bytes once, refusing links and anything outside the root */
48
+ export declare function readInstructionBytes(root: string, relPath: string): {
49
+ base: string;
50
+ abs: string;
51
+ buf: Buffer;
52
+ sha256: string;
53
+ };
54
+ /**
55
+ * Record a person's approval of one file's exact bytes. `expectedSha256` is the fingerprint
56
+ * of the bytes the person was shown; if the file changed since, nothing is approved.
57
+ */
58
+ export declare function approveInstructionFile(root: string, relPath: string, approvedBy: string, expectedSha256: string, o?: LedgerOptions): ApprovalEntry;
59
+ export type InstructionStatus = "approved" | "changed" | "unknown";
60
+ export interface InstructionCheck extends InstructionFile {
61
+ status: InstructionStatus;
62
+ approvedSha256?: string;
63
+ }
64
+ export declare function checkInstructionFiles(root: string, o?: LedgerOptions): InstructionCheck[];
65
+ /**
66
+ * Read each instruction file ONCE and decide from those bytes: approved bytes come back
67
+ * as guidance; anything else comes back only as untrusted data. `gate` is the engine's
68
+ * scan, so even approved files carry a verdict.
69
+ */
70
+ export declare function loadInstructionFiles(root: string, gate: (text: string, source: string) => Promise<{
71
+ tier: string;
72
+ envelope: string;
73
+ findings: {
74
+ kind: string;
75
+ }[];
76
+ }>, o?: LedgerOptions): Promise<{
77
+ relPath: string;
78
+ status: InstructionStatus;
79
+ inDependency: boolean;
80
+ tier: string;
81
+ sha256: string;
82
+ guidance?: string;
83
+ untrusted?: string;
84
+ }[]>;