@foldrun/core 1.2.0 → 1.3.0

package/dist/src/scan.d.ts

@@ -33,6 +33,9 @@ export interface ScanOptions {
     outwardTools?: Iterable<string>;
     /** Only these rule ids (or categories, `secret`, `security`, …). */
     only?: string[];
+    /** The account AGENTS.md's `network:` — the level above the workspace's,
+     *  which the files of one workspace do not carry. */
+    accountNetwork?: unknown;
 }
 export declare const OWASP_URL = "https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026";
 export declare const SCAN_RULES: readonly ScanRule[];
@@ -60,6 +63,9 @@ export declare function ruleDocsUrl(id: string): string;
 export declare function findingFingerprint(rule: string, file: string, text: string): string;
 /** What a finding may show of a secret: enough to find it, not to use it. */
 export declare function redactSecret(secret: string): string;
+/** The text with every credential in it redacted — for a finding that
+ *  quotes source, so no message ever carries a key whole. */
+export declare function redactText(text: string): string;
 /** The known field a key was probably meant to be, or null. */
 export declare function nearestField(key: string, known: readonly string[]): string | null;
 /**

package/dist/src/scan.js

@@ -28,6 +28,7 @@
 import crypto from "node:crypto";
 import matter from "gray-matter";
 import { refNames } from "./refs.js";
+import { resolveNetwork } from "./network.js";
 export const OWASP_URL = "https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026";
 export const SCAN_RULES = [
     {
@@ -74,7 +75,8 @@ export const SCAN_RULES = [
         level: "warn",
         title: "Reads untrusted content, holds private data and can send it out",
         help: "An agent with all three can be told — by any page it reads — to send what it holds anywhere it can reach. " +
-            "Take one leg away: narrow `network:` to the sites it needs, split the reading and the sending into two agents, " +
+            "Take one leg away: take it off the open network (`network: { level: trusted, allow: [the sites it needs] }` — a bare list only adds sites, " +
+            "and an agent that reads the web stays open), split the reading and the sending into two agents, " +
             "or guard its calls with a `hooks:` gate. An approval (`!`) on every outward step is the other answer.",
         owasp: ["ASI01", "ASI02", "ASI03"],
     },
@@ -272,6 +274,41 @@ function credentialLike(value) {
 export function redactSecret(secret) {
     return secret.length <= 8 ? "****" : `${secret.slice(0, 4)}…${secret.slice(-2)}`;
 }
+/** Every credential in a piece of text, as [value, what]. One reading for
+ *  the secret rule and for any other rule that quotes the line. */
+function credentialsIn(line) {
+    const out = [];
+    const seen = new Set();
+    const add = (v, what) => {
+        if (!seen.has(v)) {
+            seen.add(v);
+            out.push([v, what]);
+        }
+    };
+    for (const [re, what] of SECRET_SHAPES) {
+        if (what === "a private key")
+            continue; // a header names a key; it is not one
+        for (const m of line.matchAll(re)) {
+            if (!PLACEHOLDER.test(m[0]) && entropy(m[0]) >= 3)
+                add(m[0], what);
+        }
+    }
+    for (const m of line.matchAll(ASSIGNED))
+        if (credentialLike(m[2]))
+            add(m[2], `\`${m[1]}\` with a literal value`);
+    for (const m of line.matchAll(BEARER))
+        if (credentialLike(m[1]))
+            add(m[1], "a bearer token");
+    return out;
+}
+/** The text with every credential in it redacted — for a finding that
+ *  quotes source, so no message ever carries a key whole. */
+export function redactText(text) {
+    let out = text;
+    for (const [v] of credentialsIn(text).sort((a, b) => b[0].length - a[0].length))
+        out = out.split(v).join(redactSecret(v));
+    return out;
+}
 function scanSecrets(file, lines, push) {
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
@@ -351,13 +388,13 @@ function scanContent(file, lines, push) {
             const kind = HIDDEN_NAMES.find(([re]) => re.test(line))?.[1] ?? "invisible characters";
             const n = line.match(HIDDEN)?.length ?? 0;
             const tagged = /\uDB40[\uDC00-\uDC7F]/.test(line) ? ` that read as: "${decodeTags(line).slice(0, 80)}"` : "";
-            push("content/hidden-unicode", file.path, i + 1, line, `${n} ${kind}${tagged} — invisible to a reviewer, read by the model`);
+            push("content/hidden-unicode", file.path, i + 1, line, `${n} ${kind}${redactText(tagged)} — invisible to a reviewer, read by the model`);
         }
         // An instruction quoted inside a fence is an example of one, not one.
         if (data && !fenced) {
             const m = INJECTION.find((re) => re.test(line));
             if (m)
-                push("content/injection-phrase", file.path, i + 1, line, `"${line.trim().slice(0, 90)}" — agents read this file as data, and this line reads as an order`);
+                push("content/injection-phrase", file.path, i + 1, line, `"${redactText(line.trim()).slice(0, 90)}" — agents read this file as data, and this line reads as an order`);
         }
         if (md) {
             for (const b of line.matchAll(BLOB)) {
@@ -502,15 +539,13 @@ function docKind(p) {
 }
 // ── agents: what one can reach, taken together ─────────────────────────────
 const WRITE_METHODS = /\b(?:POST|PUT|PATCH|DELETE)\b/i;
-function scanAgents(agents, outward, toolDefs, push) {
+function scanAgents(agents, outward, toolDefs, push, networks) {
     const byName = new Map(agents.map((a) => [a.name, a]));
     for (const a of agents) {
         const d = a.data;
         const tools = refNames(d.tools);
         const denied = new Set(refNames(d.disallowedTools));
         const has = (t) => tools.includes(t) && !denied.has(t);
-        const network = d.network;
-        const netLevel = typeof network === "string" ? network : Array.isArray(network) ? "list" : network && typeof network === "object" ? "list" : null;
         // Untrusted: it reads the open web. (A webhook body is the other source;
         // that is a flow's trigger, and the flow-level rule is a later one.)
         const readsWeb = has("web") || tools.some((t) => /browse|fetch|scrape|crawl/i.test(t) && has(t));
@@ -519,16 +554,18 @@ function scanAgents(agents, outward, toolDefs, push) {
         const apis = Array.isArray(d.apis) ? d.apis : [];
         const mcp = d.mcpServers && typeof d.mcpServers === "object" ? Object.keys(d.mcpServers) : [];
         const privateLeg = [...secrets.map((s) => `secret ${s}`), ...apis.map((x) => `api ${x?.name ?? "?"}`), ...mcp.map((m) => `MCP ${m}`)];
-        // Out: a sandbox open to every site (an agent that reads the web is open
-        // unless it says otherwise), a tool marked outward, or an API it may write to.
-        const openNet = netLevel === "open" || (readsWeb && netLevel === null);
+        // Out: a sandbox open to every site, a tool marked outward, or an API it
+        // may write to. The level is the runtime's own resolution — agent, then
+        // workspace, then account, and open by default for an agent that reads
+        // the web; a bare list of sites adds to a level, it does not set one.
+        const openNet = resolveNetwork({ account: networks.account, workspace: networks.workspace, agent: d.network, readsWeb }).level === "open";
         const outwardTools = tools.filter((t) => outward.has(t) && !denied.has(t));
         const writeApis = apis.filter((x) => WRITE_METHODS.test(JSON.stringify(x?.methods ?? x?.method ?? "")));
         const outLeg = [...(openNet ? ["an open network"] : []), ...outwardTools.map((t) => `outward tool ${t}`), ...writeApis.map((x) => `writes to api ${x?.name ?? "?"}`)];
         const gated = refNames(d.hooks).length > 0 || d.permissionMode === "plan";
         if (readsWeb && privateLeg.length && outLeg.length && !gated) {
             push("security/lethal-trifecta", a.file, a.line, `trifecta ${a.name}`, `${a.name} reads the web, holds ${privateLeg.slice(0, 3).join(", ")}${privateLeg.length > 3 ? ", …" : ""} and can reach ${outLeg.slice(0, 2).join(" and ")} — ` +
-                `a page it reads can tell it where to send what it holds. Narrow network:, split it, or add a hooks: gate`);
+                `a page it reads can tell it where to send what it holds. Take it off the open network (network: { level: trusted, allow: [...] }), split it, or add a hooks: gate`);
         }
         // Sub-agents declaring tools the parent lacks.
         for (const s of refNames(d.subagents)) {
@@ -666,7 +703,8 @@ export function scanFiles(files, options = {}) {
             toolDefs.set(f.path, { data, lines });
         }
     }
-    scanAgents(agents, outward, toolDefs, push);
+    const workspaceMd = files.find((f) => f.path === "AGENTS.md");
+    scanAgents(agents, outward, toolDefs, push, { account: options.accountNetwork, workspace: workspaceMd ? frontOf(workspaceMd.content)?.network : undefined });
     return findings.sort((a, b) => a.file.localeCompare(b.file) || (a.line ?? 0) - (b.line ?? 0) || a.rule.localeCompare(b.rule));
 }
 /**
@@ -698,7 +736,9 @@ export function applyBaseline(findings, baseline) {
     const b = baseline;
     if (!b || b.version !== 1 || !Array.isArray(b.findings))
         return { kept: findings, baselined: 0 };
-    const known = new Set(b.findings.map((f) => `${f.rule}\0${f.file}\0${f.fingerprint}`));
+    // An entry that is not {rule, file, fingerprint} hides nothing.
+    const entries = b.findings.filter((f) => !!f && typeof f === "object" && typeof f.rule === "string" && typeof f.file === "string" && typeof f.fingerprint === "string");
+    const known = new Set(entries.map((f) => `${f.rule}\0${f.file}\0${f.fingerprint}`));
     const kept = findings.filter((f) => !known.has(`${f.rule}\0${f.file}\0${f.fingerprint}`));
     return { kept, baselined: findings.length - kept.length };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldrun/core",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Agents are just folders. The format, the runner, the checks.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",

package/src/scan.ts

@@ -29,6 +29,7 @@
 import crypto from "node:crypto";
 import matter from "gray-matter";
 import { refNames } from "./refs.ts";
+import { resolveNetwork } from "./network.ts";
 
 export type ScanLevel = "error" | "warn" | "info";
 export type ScanCategory = "secret" | "security" | "content" | "supply-chain" | "config";
@@ -69,6 +70,9 @@ export interface ScanOptions {
   outwardTools?: Iterable<string>;
   /** Only these rule ids (or categories, `secret`, `security`, …). */
   only?: string[];
+  /** The account AGENTS.md's `network:` — the level above the workspace's,
+   *  which the files of one workspace do not carry. */
+  accountNetwork?: unknown;
 }
 
 export const OWASP_URL = "https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026";
@@ -123,7 +127,8 @@ export const SCAN_RULES: readonly ScanRule[] = [
     title: "Reads untrusted content, holds private data and can send it out",
     help:
       "An agent with all three can be told — by any page it reads — to send what it holds anywhere it can reach. " +
-      "Take one leg away: narrow `network:` to the sites it needs, split the reading and the sending into two agents, " +
+      "Take one leg away: take it off the open network (`network: { level: trusted, allow: [the sites it needs] }` — a bare list only adds sites, " +
+      "and an agent that reads the web stays open), split the reading and the sending into two agents, " +
       "or guard its calls with a `hooks:` gate. An approval (`!`) on every outward step is the other answer.",
     owasp: ["ASI01", "ASI02", "ASI03"],
   },
@@ -329,6 +334,36 @@ export function redactSecret(secret: string): string {
   return secret.length <= 8 ? "****" : `${secret.slice(0, 4)}…${secret.slice(-2)}`;
 }
 
+/** Every credential in a piece of text, as [value, what]. One reading for
+ *  the secret rule and for any other rule that quotes the line. */
+function credentialsIn(line: string): [string, string][] {
+  const out: [string, string][] = [];
+  const seen = new Set<string>();
+  const add = (v: string, what: string) => {
+    if (!seen.has(v)) {
+      seen.add(v);
+      out.push([v, what]);
+    }
+  };
+  for (const [re, what] of SECRET_SHAPES) {
+    if (what === "a private key") continue; // a header names a key; it is not one
+    for (const m of line.matchAll(re)) {
+      if (!PLACEHOLDER.test(m[0]) && entropy(m[0]) >= 3) add(m[0], what);
+    }
+  }
+  for (const m of line.matchAll(ASSIGNED)) if (credentialLike(m[2]!)) add(m[2]!, `\`${m[1]}\` with a literal value`);
+  for (const m of line.matchAll(BEARER)) if (credentialLike(m[1]!)) add(m[1]!, "a bearer token");
+  return out;
+}
+
+/** The text with every credential in it redacted — for a finding that
+ *  quotes source, so no message ever carries a key whole. */
+export function redactText(text: string): string {
+  let out = text;
+  for (const [v] of credentialsIn(text).sort((a, b) => b[0].length - a[0].length)) out = out.split(v).join(redactSecret(v));
+  return out;
+}
+
 function scanSecrets(file: ScanFile, lines: string[], push: Push) {
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i]!;
@@ -403,12 +438,12 @@ function scanContent(file: ScanFile, lines: string[], push: Push) {
       const kind = HIDDEN_NAMES.find(([re]) => re.test(line))?.[1] ?? "invisible characters";
       const n = line.match(HIDDEN)?.length ?? 0;
       const tagged = /\uDB40[\uDC00-\uDC7F]/.test(line) ? ` that read as: "${decodeTags(line).slice(0, 80)}"` : "";
-      push("content/hidden-unicode", file.path, i + 1, line, `${n} ${kind}${tagged} — invisible to a reviewer, read by the model`);
+      push("content/hidden-unicode", file.path, i + 1, line, `${n} ${kind}${redactText(tagged)} — invisible to a reviewer, read by the model`);
     }
     // An instruction quoted inside a fence is an example of one, not one.
     if (data && !fenced) {
       const m = INJECTION.find((re) => re.test(line));
-      if (m) push("content/injection-phrase", file.path, i + 1, line, `"${line.trim().slice(0, 90)}" — agents read this file as data, and this line reads as an order`);
+      if (m) push("content/injection-phrase", file.path, i + 1, line, `"${redactText(line.trim()).slice(0, 90)}" — agents read this file as data, and this line reads as an order`);
     }
     if (md) {
       for (const b of line.matchAll(BLOB)) {
@@ -568,15 +603,13 @@ interface ToolFacts {
   lines: string[];
 }
 
-function scanAgents(agents: AgentFacts[], outward: Set<string>, toolDefs: Map<string, ToolFacts>, push: Push) {
+function scanAgents(agents: AgentFacts[], outward: Set<string>, toolDefs: Map<string, ToolFacts>, push: Push, networks: { account?: unknown; workspace?: unknown }) {
   const byName = new Map(agents.map((a) => [a.name, a]));
   for (const a of agents) {
     const d = a.data;
     const tools = refNames(d.tools);
     const denied = new Set(refNames(d.disallowedTools));
     const has = (t: string) => tools.includes(t) && !denied.has(t);
-    const network = d.network;
-    const netLevel = typeof network === "string" ? network : Array.isArray(network) ? "list" : network && typeof network === "object" ? "list" : null;
 
     // Untrusted: it reads the open web. (A webhook body is the other source;
     // that is a flow's trigger, and the flow-level rule is a later one.)
@@ -586,9 +619,11 @@ function scanAgents(agents: AgentFacts[], outward: Set<string>, toolDefs: Map<st
     const apis = Array.isArray(d.apis) ? d.apis : [];
     const mcp = d.mcpServers && typeof d.mcpServers === "object" ? Object.keys(d.mcpServers as object) : [];
     const privateLeg = [...secrets.map((s) => `secret ${s}`), ...apis.map((x: any) => `api ${x?.name ?? "?"}`), ...mcp.map((m) => `MCP ${m}`)];
-    // Out: a sandbox open to every site (an agent that reads the web is open
-    // unless it says otherwise), a tool marked outward, or an API it may write to.
-    const openNet = netLevel === "open" || (readsWeb && netLevel === null);
+    // Out: a sandbox open to every site, a tool marked outward, or an API it
+    // may write to. The level is the runtime's own resolution — agent, then
+    // workspace, then account, and open by default for an agent that reads
+    // the web; a bare list of sites adds to a level, it does not set one.
+    const openNet = resolveNetwork({ account: networks.account, workspace: networks.workspace, agent: d.network, readsWeb }).level === "open";
     const outwardTools = tools.filter((t) => outward.has(t) && !denied.has(t));
     const writeApis = apis.filter((x: any) => WRITE_METHODS.test(JSON.stringify(x?.methods ?? x?.method ?? "")));
     const outLeg = [...(openNet ? ["an open network"] : []), ...outwardTools.map((t) => `outward tool ${t}`), ...writeApis.map((x: any) => `writes to api ${x?.name ?? "?"}`)];
@@ -598,7 +633,7 @@ function scanAgents(agents: AgentFacts[], outward: Set<string>, toolDefs: Map<st
       push(
         "security/lethal-trifecta", a.file, a.line, `trifecta ${a.name}`,
         `${a.name} reads the web, holds ${privateLeg.slice(0, 3).join(", ")}${privateLeg.length > 3 ? ", …" : ""} and can reach ${outLeg.slice(0, 2).join(" and ")} — ` +
-          `a page it reads can tell it where to send what it holds. Narrow network:, split it, or add a hooks: gate`,
+          `a page it reads can tell it where to send what it holds. Take it off the open network (network: { level: trusted, allow: [...] }), split it, or add a hooks: gate`,
       );
     }
 
@@ -748,7 +783,8 @@ export function scanFiles(files: ScanFile[], options: ScanOptions = {}): ScanFin
       toolDefs.set(f.path, { data, lines });
     }
   }
-  scanAgents(agents, outward, toolDefs, push);
+  const workspaceMd = files.find((f) => f.path === "AGENTS.md");
+  scanAgents(agents, outward, toolDefs, push, { account: options.accountNetwork, workspace: workspaceMd ? frontOf(workspaceMd.content)?.network : undefined });
 
   return findings.sort((a, b) => a.file.localeCompare(b.file) || (a.line ?? 0) - (b.line ?? 0) || a.rule.localeCompare(b.rule));
 }
@@ -791,7 +827,12 @@ export function makeBaseline(findings: Pick<ScanFinding, "rule" | "file" | "fing
 export function applyBaseline<T extends Pick<ScanFinding, "rule" | "file" | "fingerprint">>(findings: T[], baseline: unknown): { kept: T[]; baselined: number } {
   const b = baseline as ScanBaseline | null;
   if (!b || b.version !== 1 || !Array.isArray(b.findings)) return { kept: findings, baselined: 0 };
-  const known = new Set(b.findings.map((f) => `${f.rule}\0${f.file}\0${f.fingerprint}`));
+  // An entry that is not {rule, file, fingerprint} hides nothing.
+  const entries = (b.findings as unknown[]).filter(
+    (f): f is ScanBaseline["findings"][number] =>
+      !!f && typeof f === "object" && typeof (f as any).rule === "string" && typeof (f as any).file === "string" && typeof (f as any).fingerprint === "string",
+  );
+  const known = new Set(entries.map((f) => `${f.rule}\0${f.file}\0${f.fingerprint}`));
   const kept = findings.filter((f) => !known.has(`${f.rule}\0${f.file}\0${f.fingerprint}`));
   return { kept, baselined: findings.length - kept.length };
 }