@open-everywhere/core 0.1.0

package/agent/access/host-egress.ts

@@ -0,0 +1,432 @@
+// The host-side egress guard: assertEgressReach is the ONE reach decision every model-influenced host-side call must pass, taken against the same resolved allowlist the sandbox compiles, and this plane admits less than the sandbox plane and never more. It is fail-closed by choice — wildcard allow-keys, the network-access level's hosts and the bare github.com a repo grant implies are all UNREACHABLE here, a name that resolves to no address is denied, reachability is checked before any DNS lookup, and no credential header ever rides a model-supplied URL.
+
+import dnsPromises from "node:dns/promises";
+import net, { type LookupFunction } from "node:net";
+import { Agent, ProxyAgent, type Dispatcher } from "undici";
+import type { BindableContext } from "../identity/binding.js";
+import { ownAccountEgressRefusalText, type OwnAccountEgressRefusal, type ReachableHost } from "./resolver.js";
+import { resolveAccessFor } from "./request.js";
+import { narrowByConnectorOverride } from "./connector-scope.js";
+import { withExtraEgressHosts } from "./extra-hosts.js";
+import { egressHostsOverlap } from "./bundle.js";
+import { auditToolAction } from "../audit/tool-action.js";
+import { hostCallAuditFields } from "./egress.js";
+import { haltScopeForCtx, resolveHalt } from "./halt.js";
+
+// Production resolves via node:dns; tests inject a deterministic map here, so a rebind host can be pointed at a metadata IP with no real DNS.
+export type HostLookup = (hostname: string) => Promise<readonly string[]>;
+let lookupImpl: HostLookup | undefined;
+/** Override DNS resolution for tests; pass undefined to restore node:dns. */
+export function setHostEgressLookup(fn: HostLookup | undefined): void {
+  lookupImpl = fn;
+}
+async function resolveAll(hostname: string): Promise<readonly string[]> {
+  if (lookupImpl) return lookupImpl(hostname);
+  const records = await dnsPromises.lookup(hostname, { all: true });
+  return records.map((r) => r.address);
+}
+
+// The old literal host patterns, lifted to RESOLVED-IP checks: any address in these ranges is refused after resolution.
+
+/** A denied IPv4 address? Malformed → denied (fail-closed). */
+function isDeniedIpv4(ip: string): boolean {
+  const parts = ip.split(".").map((p) => Number(p));
+  if (parts.length !== 4 || parts.some((o) => !Number.isInteger(o) || o < 0 || o > 255)) return true;
+  const [a, b] = parts;
+  if (a === 0) return true; // 0.0.0.0/8 "this network"
+  if (a === 10) return true; // 10.0.0.0/8 private-A
+  if (a === 127) return true; // 127.0.0.0/8 loopback
+  if (a === 169 && b === 254) return true; // 169.254.0.0/16 link-local (incl. 169.254.169.254 metadata)
+  if (a === 172 && b >= 16 && b <= 31) return true; // 172.16.0.0/12 private-B
+  if (a === 192 && b === 168) return true; // 192.168.0.0/16 private-C
+  if (a === 100 && b >= 64 && b <= 127) return true; // 100.64.0.0/10 CGNAT
+  return false;
+}
+
+/** First 16-bit hextet of an IPv6 address (0 when the address begins with `::`). */
+function firstHextet(ip: string): number {
+  const addr = ip.split("%")[0]; // strip a zone id
+  if (addr.startsWith("::")) return 0;
+  const g = addr.split(":")[0];
+  return g ? parseInt(g, 16) : 0;
+}
+
+/** A denied IP (v4 or v6)? A non-IP string is DENIED (fail-closed — callers guard with net.isIP). */
+function isDeniedIp(ip: string): boolean {
+  const fam = net.isIP(ip);
+  if (fam === 4) return isDeniedIpv4(ip);
+  if (fam === 6) {
+    const lower = ip.toLowerCase();
+    // IPv4-mapped ::ffff:a.b.c.d — re-check the embedded v4 (a common bypass).
+    const mapped = /^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/.exec(lower);
+    if (mapped) return isDeniedIpv4(mapped[1]);
+    if (lower === "::1") return true; // loopback
+    if (lower === "::") return true; // unspecified
+    const first = firstHextet(lower);
+    if (first >= 0xfc00 && first <= 0xfdff) return true; // fc00::/7 unique-local
+    if (first >= 0xfe80 && first <= 0xfebf) return true; // fe80::/10 link-local
+    return false;
+  }
+  return true; // unclassifiable → deny
+}
+
+// Names and IPs refused WITHOUT a DNS lookup, so a bare metadata IP is refused before anything is ever resolved.
+function isLiteralPrivateHost(host: string): boolean {
+  const h = host.toLowerCase();
+  if (h === "localhost" || h.endsWith(".localhost")) return true;
+  if (h === "metadata.google.internal") return true;
+  if (net.isIP(h) !== 0 && isDeniedIp(h)) return true;
+  return false;
+}
+
+/** The tool name every refusal on this plane is prefixed with. It defaults to post_file because the existing messages, and the e2e SSRF probe that reads them, were written against that prefix; every other caller passes its own name, so the model is told which of its hands was refused. */
+const DEFAULT_TOOL_LABEL = "post_file";
+
+/** Parse + validate scheme + literal-host reject — the cheap, no-DNS gate. Throws on refusal. */
+function parseHttpUrl(raw: string, tool: string = DEFAULT_TOOL_LABEL): URL {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new Error(`${tool}: "${raw}" is not a valid URL.`);
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error(`${tool}: only http(s) URLs may be fetched — got "${url.protocol}".`);
+  }
+  if (isLiteralPrivateHost(url.hostname)) {
+    throw new Error(`${tool}: refusing to fetch an internal/loopback/link-local host ("${url.hostname}").`);
+  }
+  return url;
+}
+
+// Every fetch this file dispatches honours *_PROXY itself: with proxy envs set the call goes through a ProxyAgent, the local IP-pin is NOT applied, and anti-rebind is DELEGATED to the proxy's own default-deny ACL; the direct path resolves, denies private ranges and pins the socket, unchanged. An operator who points HTTPS_PROXY at some other forward proxy inherits that proxy's posture, which we have not measured, and the shipped proxy's host-based ACL would not refuse an allow-listed hostname that rebinds to an address the PROXY can reach.
+
+/** Why a dispatch-time throw happened, tagged onto the error itself so the audit row can tell a
+ *  POLICY refusal from a resolver that could not answer. Only `"resolve-failed"` is ever tagged;
+ *  an untagged throw from this file's dispatch path is a policy refusal. */
+export type EgressRefusalCause = "resolve-failed";
+
+export type EgressRoute = { readonly via: "direct" } | { readonly via: "proxy"; readonly proxyUrl: string };
+
+export interface EgressDispatch {
+  readonly url: URL;
+  readonly dispatcher: Dispatcher;
+  readonly via: "direct" | "proxy";
+  /** `ip-pin` = this process resolved, refused denied ranges, and pinned the socket.
+   *  `proxy-acl` = DELEGATED to the forward proxy (see the section header). */
+  readonly antiRebind: "ip-pin" | "proxy-acl";
+}
+
+/** Does `NO_PROXY` exempt this destination? Mirrors undici's `EnvHttpProxyAgent`: comma/whitespace
+ *  separated, `*` matches everything, a leading dot is optional, an entry may carry a `:port`, and
+ *  a bare name matches itself plus any subdomain. */
+function noProxyExempts(url: URL, noProxy: string): boolean {
+  const host = url.hostname.toLowerCase();
+  const port = url.port || (url.protocol === "https:" ? "443" : "80");
+  for (const raw of noProxy.split(/[,\s]+/)) {
+    let entry = raw.trim().toLowerCase();
+    if (entry === "") continue;
+    if (entry === "*") return true;
+    const colon = entry.lastIndexOf(":");
+    if (colon > 0 && /^\d+$/.test(entry.slice(colon + 1))) {
+      if (entry.slice(colon + 1) !== port) continue;
+      entry = entry.slice(0, colon);
+    }
+    if (entry.startsWith(".")) entry = entry.slice(1);
+    if (entry === "") continue;
+    if (host === entry || host.endsWith(`.${entry}`)) return true;
+  }
+  return false;
+}
+
+/** Which route this destination takes. Pure over env so a test pins the DECISION without opening a socket, and a proxy env that is set but unparseable THROWS rather than silently falling back to direct — a silent fallback leaves the plane looking configured when it is not. */
+export function resolveEgressRoute(url: URL, env: NodeJS.ProcessEnv = process.env, tool: string = DEFAULT_TOOL_LABEL): EgressRoute {
+  // Lowercase wins over uppercase when both are set (undici's rule); the self-host stack sets the
+  // uppercase pair, so both must be honoured.
+  const names = url.protocol === "https:" ? (["https_proxy", "HTTPS_PROXY"] as const) : (["http_proxy", "HTTP_PROXY"] as const);
+  const key = (env[names[0]] ?? "").trim() !== "" ? names[0] : names[1];
+  const proxyUrl = (env[key] ?? "").trim();
+  if (proxyUrl === "") return { via: "direct" };
+  const noProxy = (env.no_proxy ?? env.NO_PROXY ?? "").trim();
+  if (noProxy !== "" && noProxyExempts(url, noProxy)) return { via: "direct" };
+  // `new URL()` alone is too permissive to be a validity check here: `oe-egress-proxy:3128` parses
+  // (scheme `oe-egress-proxy:`, path `3128`) and would then blow up inside ProxyAgent. Require what
+  // a forward proxy actually is — an http(s) origin with a host.
+  let parsed: URL | undefined;
+  try {
+    parsed = new URL(proxyUrl);
+  } catch {
+    /* handled below */
+  }
+  if (parsed === undefined || (parsed.protocol !== "http:" && parsed.protocol !== "https:") || parsed.hostname === "") {
+    throw new Error(`${tool}: ${key}="${proxyUrl}" is not a valid http(s) proxy URL — refusing to fall back to an unproxied request.`);
+  }
+  return { via: "proxy", proxyUrl };
+}
+
+/** Resolve the host, refuse if ANY resolved address is in a denied range, and build a dispatcher that PINS the connection to a validated IP — closing the DNS-rebind TOCTOU window — while keeping the original hostname for TLS SNI and the Host header. */
+async function pinResolvedIp(url: URL, tool: string = DEFAULT_TOOL_LABEL): Promise<{ url: URL; dispatcher: Agent }> {
+  // A resolver that could not ANSWER is not a policy refusal, so its throw is tagged: without the tag a resolver blip on an allow-listed host was audited as an SSRF event. The two branches below stay policy refusals — a denied range, and a name that resolved to nothing, which this file denies by design.
+  let addrs: readonly string[];
+  try {
+    addrs = await resolveAll(url.hostname);
+  } catch (err) {
+    if (err instanceof Error) (err as { oeEgressCause?: EgressRefusalCause }).oeEgressCause = "resolve-failed";
+    throw err;
+  }
+  if (addrs.length === 0) {
+    throw new Error(`${tool}: "${url.hostname}" did not resolve to any address.`);
+  }
+  for (const ip of addrs) {
+    if (isDeniedIp(ip)) {
+      throw new Error(
+        `${tool}: "${url.hostname}" resolves to a blocked internal/loopback/link-local address (${ip}) — refusing (DNS-rebinding guard).`,
+      );
+    }
+  }
+  const pinned = addrs[0];
+  const family = net.isIP(pinned);
+  // Ignore any re-resolution: always connect to the address we validated. undici may call
+  // with { all: true } (expects a LookupAddress[]) or the classic (err, address, family).
+  const lookup: LookupFunction = (_hostname, options, callback): void => {
+    if ((options as { all?: boolean }).all) callback(null, [{ address: pinned, family }]);
+    else callback(null, pinned, family);
+  };
+  const dispatcher = new Agent({ connect: { lookup } });
+  return { url, dispatcher };
+}
+
+/** The proxy-hop dispatch: hostname straight to the forward proxy, anti-rebind delegated to it. */
+function proxyDispatch(url: URL, proxyUrl: string): EgressDispatch {
+  return { url, dispatcher: new ProxyAgent({ uri: proxyUrl }), via: "proxy", antiRebind: "proxy-acl" };
+}
+
+/** The direct dispatch: resolve, refuse denied ranges, pin the socket to a validated address. */
+async function directDispatch(url: URL, tool: string): Promise<EgressDispatch> {
+  const pinned = await pinResolvedIp(url, tool);
+  return { url: pinned.url, dispatcher: pinned.dispatcher, via: "direct", antiRebind: "ip-pin" };
+}
+
+/** Build the dispatch for an already-parsed URL. The route decision is taken FIRST so a
+ *  proxy-config error is never mistaken for an SSRF event by a caller that audits the throw. */
+async function dispatchFor(url: URL, tool: string): Promise<EgressDispatch> {
+  const route = resolveEgressRoute(url, process.env, tool);
+  return route.via === "proxy" ? proxyDispatch(url, route.proxyUrl) : directDispatch(url, tool);
+}
+
+/** SSRF guard for a model-supplied URL: http(s) only, no literal internal host, then either a pinned direct socket or the forward proxy behind its own default-deny ACL. It is the SSRF half ONLY and makes no reach decision, so an exported caller — the Slack attachment seam, which must send a token and cannot use oeFetch — still owes its own. */
+export async function assertSafeFetchUrl(raw: string, tool: string = DEFAULT_TOOL_LABEL): Promise<EgressDispatch> {
+  const url = parseHttpUrl(raw, tool);
+  return dispatchFor(url, tool);
+}
+
+/** Is `hostname` reachable from this session's compiled allowlist? EXACT match only. */
+export function hostReachable(hostname: string, hosts: readonly ReachableHost[]): boolean {
+  const h = hostname.toLowerCase();
+  return hosts.some((rh) => rh.host.toLowerCase() === h);
+}
+
+/** The allow-list entry for a hostname, or undefined. The same EXACT-match rule as hostReachable, which is this lookup's boolean face, so the two can never disagree about what "reachable" means. */
+function reachableEntry(hostname: string, hosts: readonly ReachableHost[]): ReachableHost | undefined {
+  const h = hostname.toLowerCase();
+  return hosts.find((rh) => rh.host.toLowerCase() === h);
+}
+
+/** The widening route, stated ONCE, so an agent that hits both this fence and the sandbox firewall's own README learns one protocol rather than two. Keep the two texts in agreement: the only intended difference is that a host-side deny is on the record and a sandbox firewall deny is not. */
+export const EGRESS_REPORT_PROTOCOL =
+  "This is policy, not an outage: a retry, a mirror, a proxy, a different port and a different DNS " +
+  "name all fail the same way. Report it in your answer instead, naming the host you needed and " +
+  "what you needed it for. Widening is not something either of us can do at runtime — a reachable " +
+  "host is config-as-code, and it changes by reviewed pull request against the bundle that grants " +
+  "it (a `domains` entry for an uncredentialed host, or a connection's `allowedWebsites` for a " +
+  "credentialed one). It then lands on the session's next turn.";
+
+/** Why a host-side reach check refused; all are audited as egress.hostside.deny. own-account-withheld is NOT a narrower not-allowlisted: the host IS in the bundle, so the widening protocol is the wrong advice and would send an agent to open a pull request for a refusal the member's own sentence caused. */
+export type ReachDenyReason = "not-allowlisted" | "own-account-withheld" | "connector-revoked" | "halted";
+
+/** Every reason an egress.hostside.deny row carries on this plane, so the trail's vocabulary has one home and a sixth spelling fails to compile. It bounds THIS ACTION only: a seam writing its own deny action keeps its own vocabulary and is deliberately not folded in. */
+type HostDenyReason = ReachDenyReason | "ssrf" | "resolve-failed" | "redirect-bound";
+
+/** The bound is NOT the security control — assertEgressHop re-takes the full reach decision on every hop, so hop 5 is fenced exactly as hop 0 is — it only stops a chain that never terminates. It counts ONE request's chain, not one tool call, so an eve retry after a challenge starts again at hop 0 and every hop of both chains is fenced. */
+export const MAX_REDIRECT_HOPS = 5;
+
+/** The refusal text for a chain that hit {@link MAX_REDIRECT_HOPS}. Not {@link egressReachDenial}:
+ *  nothing here is an allow-list problem, so the widening protocol would be wrong advice. */
+export function redirectBoundDenial(tool: string, host: string): string {
+  return (
+    `${tool}: this request has already followed ${MAX_REDIRECT_HOPS} redirects, and "${host}" is the next one. ` +
+    `A chain that long is a loop or a cloak, so the fence stopped it. Fetch the final URL directly instead.`
+  );
+}
+
+export function egressReachDenial(tool: string, host: string, reason: ReachDenyReason, withheld?: OwnAccountEgressRefusal): string {
+  // The own-account refusal answers a DIFFERENT question, so it takes neither the shared cause
+  // clause nor the report protocol — see {@link ReachDenyReason} for why that advice would misdirect.
+  if (reason === "own-account-withheld") {
+    const why =
+      withheld !== undefined
+        ? ownAccountEgressRefusalText(withheld)
+        : `Host "${host}" is withheld from this session because its requester asked to act with their own account there. ` +
+          `Answering that here would mean a second credential on one host, which this deployment never allows. ` +
+          `Ask again in your DM with me, where a personal grant can be minted.`;
+    return `${tool}: the request was refused before it was made. ${why}`;
+  }
+  const cause =
+    reason === "not-allowlisted"
+      ? `host "${host}" is not on this session's egress allow-list`
+      : reason === "halted"
+        ? `a break-glass halt is in force for this deployment, so NO host is reachable until an admin runs \`resume\` — this is not about "${host}"`
+        : `host "${host}" is reachable only through a connection that has been revoked (break-glass \`revoke_connector\`)`;
+  return `${tool}: ${cause}, so the request was refused before it was made. ${EGRESS_REPORT_PROTOCOL}`;
+}
+
+/** The one verb this plane sends, a CONSTANT rather than an option, because assertEgressReach never reads a host's declared methods: it can admit a HOST and cannot admit a VERB, so a caller-supplied verb would reach a read-only connection's host with a DELETE that nothing on this plane refuses. A seam that must send another verb adds the methods gate to the reach decision first, with its own refusal reason and its own test; it does not add an option here. */
+const HOST_PLANE_VERB = "GET";
+
+/** How the reach decision reads the world. Both default to the LIVE seams; a test overrides them
+ *  rather than seeding global config, which keeps the decision itself a plain function. */
+export interface ReachDeps {
+  readonly tool?: string;
+  /** This session's resolved allow-list. Default: the same `resolveAccessFor` read the sandbox
+   *  firewall compiles from. */
+  readonly hosts?: (ctx: BindableContext) => readonly ReachableHost[];
+  /** Break-glass narrow over connection ids (OPE-311). Default: the live `connector_override`
+   *  store — the SAME overlay the credential gate and the firewall compiler consult. */
+  readonly narrow?: (ctx: BindableContext, ids: readonly string[]) => Promise<readonly string[] | null>;
+  /** Is a BREAK-GLASS HALT in force for this seat (OPE-1602)? Default: the live halt store, read
+   *  FAIL-CLOSED — an unreadable store refuses the reach rather than granting it. */
+  readonly halted?: (ctx: BindableContext) => Promise<boolean>;
+  /** Extra detail every audit row THIS decision writes carries. assertEgressHop passes the hop number and the dispatch owner through it, so a refused REDIRECT is legible as one: without it, an allow-listed host bouncing to an undeclared host at hop 3 wrote a row byte-identical to the model simply typing that host itself. */
+  readonly rowFields?: Readonly<Record<string, unknown>>;
+  /** Hosts this session WITHHELD because its requester asked to act with their own account there. Consulted ONLY when the reach lookup already missed, so it decides which absence a refusal is about and never whether one happens. */
+  readonly withheld?: (ctx: BindableContext) => readonly OwnAccountEgressRefusal[];
+}
+
+/** THE host-side reach decision: parse the URL, then answer one question against this session's live policy — may this seat reach that host at all? ONE call governs ONE request and never a chain, so a caller whose dispatcher follows redirects owes a decision per hop. A credentialed host is re-checked against the same live break-glass override store the firewall compiler consults — narrow-only, fail-closed on a store read error, and skipped entirely for a credential-less host. */
+export async function assertEgressReach(ctx: BindableContext, rawUrl: string, deps: ReachDeps = {}): Promise<URL> {
+  const tool = deps.tool ?? DEFAULT_TOOL_LABEL;
+  // Cheap parse + literal-host reject FIRST — a bare metadata IP is refused before any allowlist
+  // read, and (below) before any DNS lookup.
+  const url = parseHttpUrl(rawUrl, tool);
+  // The declared list is only HALF of what the sandbox policy is compiled from: the capability registry is merged too, or this plane refuses a host the agent's own STATUS.json lists as allowed. Declared wins and the registry can only ADD, and the merge applies to an INJECTED hosts dep too, because the registry is a process-global source.
+  const hosts = withExtraEgressHosts((deps.hosts ?? ((c: BindableContext) => resolveAccessFor(c).reachableHosts))(ctx));
+  const entry = reachableEntry(url.hostname, hosts);
+  const deny = async (reason: ReachDenyReason, withheld?: OwnAccountEgressRefusal): Promise<never> => {
+    await auditToolAction(ctx, "egress.hostside.deny", {
+      // The shared cross-plane egress row. credential is null and that is a positive claim on this path: the request was refused before it was built, so nothing was ever attached to it.
+      ...hostCallAuditFields({ host: url.hostname, verb: HOST_PLANE_VERB, outcome: "denied" }),
+      reason,
+      tool,
+      ...(deps.rowFields ?? {}),
+    });
+    throw new Error(egressReachDenial(tool, url.hostname, reason, withheld));
+  };
+  // The break-glass halt is checked BEFORE the allow-list, because a halt is not about this host, and it is read fail-CLOSED: an unreadable store refuses reach rather than granting it. It does NOT reach a subagent's own framework web_fetch or provider-executed web_search — both are covered only by ABSENCE at projectToolSet while halted.
+  const halted = deps.halted ?? ((c: BindableContext) => resolveHalt(haltScopeForCtx(c)).then((s) => s.halted));
+  if (await halted(ctx)) return deny("halted");
+  if (!entry) {
+    // A host WITHHELD by an own-account ask is missing from reachableHosts for the same structural reason an ungranted host is, and the two need opposite answers: one wants a config pull request, the other wants the DM. The lookup runs only on the deny path, so an allowed fetch still pays one resolve.
+    const withheld = (deps.withheld ?? ((c: BindableContext) => resolveAccessFor(c).ownAccountEgressRefusals ?? []))(ctx);
+    const match = withheld.find((r) => egressHostsOverlap(r.host, url.hostname.trim().toLowerCase()));
+    if (match !== undefined) return deny("own-account-withheld", match);
+    return deny("not-allowlisted");
+  }
+  if (entry.viaConnection !== null) {
+    const narrow = deps.narrow ?? narrowByConnectorOverride;
+    const granted = await narrow(ctx, [entry.viaConnection]);
+    // `null` = the override store could not be read. Deny, exactly as the credential gate and the
+    // firewall compiler do: an unreadable store must never be read as "nothing was revoked".
+    if (granted === null || !granted.includes(entry.viaConnection)) return deny("connector-revoked");
+  }
+  return url;
+}
+
+/** ONE HOP of a call the FRAMEWORK dispatches: eve follows redirects itself, so every hop calls back here, re-takes the same full reach decision, writes its own row and refuses under the same text as a direct deny. Every row carries the hop number and the framework dispatch marker, and "allowed" here means admitted and handed to eve's dispatcher — a reader must never read these rows as transport successes. */
+export async function assertEgressHop(ctx: BindableContext, rawUrl: string, hop: number, deps: ReachDeps = {}): Promise<URL> {
+  const tool = deps.tool ?? DEFAULT_TOOL_LABEL;
+  // Parse FIRST, so the bound refusal below can name the host it stopped at, and so a malformed
+  // `Location` is refused under the same scheme/literal-host rules the model's own URL passes.
+  const parsed = parseHttpUrl(rawUrl, tool);
+  const rowFields = { hop, dispatch: "framework" } as const;
+  if (hop > MAX_REDIRECT_HOPS) {
+    const reason: HostDenyReason = "redirect-bound";
+    await auditToolAction(ctx, "egress.hostside.deny", {
+      ...hostCallAuditFields({ host: parsed.hostname, verb: HOST_PLANE_VERB, outcome: "denied" }),
+      reason,
+      tool,
+      ...rowFields,
+    });
+    throw new Error(redirectBoundDenial(tool, parsed.hostname));
+  }
+  const url = await assertEgressReach(ctx, rawUrl, { ...deps, rowFields });
+  await auditToolAction(ctx, "egress.hostside.allow", {
+    ...hostCallAuditFields({ host: url.hostname, verb: HOST_PLANE_VERB, outcome: "allowed" }),
+    tool,
+    ...rowFields,
+  });
+  return url;
+}
+
+export interface OeFetchOpts {
+  /** Audit action label for the ALLOW line (default "egress.hostside.allow"). */
+  readonly auditAs?: string;
+  /** Tool name for refusal messages + the audit row (default "post_file"). */
+  readonly tool?: string;
+  // 🔴 THERE IS DELIBERATELY NO `method` HERE. This function sends {@link HOST_PLANE_VERB} and
+  // nothing else — read that constant before you add one.
+}
+
+/** The seam every model-influenced HOST-SIDE fetch that OE itself dispatches routes through: the reach decision, then the SSRF-guarded dispatch, sending NO credentials and refusing redirects, with both the deny and the allow audited against the destination host. Not every governed call comes through here — the REACH DECISION, not this function, is what "governed" means, and web_fetch takes it alone. */
+export async function oeFetch(ctx: BindableContext, rawUrl: string, opts: OeFetchOpts = {}): Promise<Response> {
+  const tool = opts.tool ?? DEFAULT_TOOL_LABEL;
+  // 1+2. Parse, literal-host reject, and the shared REACH decision against the same allowlist the
+  //      sandbox gets — all BEFORE any DNS lookup, so a non-allowlisted attacker hostname is never
+  //      resolved (no DNS side-channel). Audits + throws its own legible refusal.
+  const parsed = await assertEgressReach(ctx, rawUrl, { tool });
+  // Route FIRST: a malformed proxy env is a config error, not an SSRF event, and must not be audited as one. On the direct path an allow-listed host that resolves into a denied range is audited too; on the proxy path there is no local resolution to audit, so the allow row records the proxy-ACL posture and the trail says which one actually held.
+  const route = resolveEgressRoute(parsed, process.env, tool);
+  let dispatch: EgressDispatch;
+  if (route.via === "proxy") {
+    dispatch = proxyDispatch(parsed, route.proxyUrl);
+  } else {
+    try {
+      dispatch = await directDispatch(parsed, tool);
+    } catch (err) {
+      // A POLICY refusal here — a resolved address in a denied range, or a hostname that resolved
+      // to none at all — is `denied`: nothing was dispatched, so nothing failed. A resolver that
+      // could not ANSWER is `failed`, and says so under its own reason; see `pinResolvedIp`.
+      const resolveFailed = (err as { oeEgressCause?: EgressRefusalCause })?.oeEgressCause === "resolve-failed";
+      const reason: HostDenyReason = resolveFailed ? "resolve-failed" : "ssrf";
+      await auditToolAction(ctx, "egress.hostside.deny", {
+        ...hostCallAuditFields({ host: parsed.hostname, verb: HOST_PLANE_VERB, outcome: resolveFailed ? "failed" : "denied" }),
+        reason,
+        tool,
+      });
+      throw err;
+    }
+  }
+  const { url, dispatcher, via, antiRebind } = dispatch;
+  // The row is written AFTER the dispatch settles, and that is a trade: a response is allowed, a transport throw is failed, and a process that dies mid-flight now leaves no row for that call. The refusal paths are untouched and still record before anything leaves, so the fence's own evidence never depended on it.
+  const auditAs = opts.auditAs ?? "egress.hostside.allow";
+  let response: Response;
+  try {
+    // No credentials on a model-supplied URL, no redirect follow, and either pinned to the validated IP or handed to the forward proxy. No method key either, so the dispatch is a GET by construction and the row below reports that same constant.
+    response = await fetch(url, { dispatcher, redirect: "error", headers: {} } as unknown as RequestInit);
+  } catch (err) {
+    await auditToolAction(ctx, auditAs, {
+      ...hostCallAuditFields({ host: url.hostname, verb: HOST_PLANE_VERB, outcome: "failed" }),
+      tool,
+      route: via,
+      antiRebind,
+    });
+    throw err;
+  }
+  await auditToolAction(ctx, auditAs, {
+    ...hostCallAuditFields({ host: url.hostname, verb: HOST_PLANE_VERB, outcome: "allowed" }),
+    tool,
+    route: via,
+    antiRebind,
+    status: response.status,
+  });
+  return response;
+}

package/agent/access/human-only-invariants-manifest.ts

@@ -0,0 +1,172 @@
+// The invariant: an agent-callable tool may PROPOSE a consequential action but never DECIDE one, and never widen who is trusted to decide. The scan matches the imported IDENTIFIER rather than a module path — a re-exporting barrel reaches the same value — and runs only over the tool roster.
+
+export interface ProtectedHumanOnlyExportGroup {
+  /** Display-only: where the export actually lives today. Not used for matching — see the
+   *  module header's "why name-based" note. */
+  readonly module: string;
+  /** The exact identifiers a tool file must never import, under any local alias. */
+  readonly exportNames: readonly string[];
+  readonly reason: string;
+}
+
+export const PROTECTED_HUMAN_ONLY_EXPORTS: readonly ProtectedHumanOnlyExportGroup[] = [
+  {
+    module: "agent/approvals/flow.ts",
+    exportNames: ["resolveApprovalClick", "clickerMayDecide", "handleApprovalPayload"],
+    reason:
+      "resolves or decides a pending approval card. The agent may PROPOSE one (requestApproval); " +
+      "only a human's click or the RBAC-gated control plane may DECIDE one.",
+  },
+  {
+    module: "agent/approvals/judge-contradiction.ts",
+    exportNames: ["contradictJudgeAllow", "disarmApprovalJudge", "rearmApprovalJudge"],
+    reason:
+      "writes an `approval.judge.contradicted` row — the ledger that carries every human act over " +
+      "the approval judge, and the one the judge's own disarm state is derived from. Every row " +
+      "asserts that A PERSON acted, so a tool-written one would be the machine forging a human " +
+      "judgement in the honest record. 🔴 The module holds BOTH directions since OPE-1102: an " +
+      "overrule and a disarm are restrictive (the judge stops lifting, cards come back), but a " +
+      "RE-ARM is permissive — a tool-written one would cancel an operator's break-glass disarm and " +
+      "restore card-free auto-approval for the domain. Since OPE-1130 a re-arm also carries an " +
+      "ORG-WIDE address (`orgWide: true`), which restores every defer-flipped propose that carries " +
+      "no domain — `pr.open` and `routine.create` always, plus user-level `spend.set` and any " +
+      "`memory.purge`/`access.request` from a domain-less surface. A tool that could write that " +
+      "row would re-arm the judge over its own highest-volume rows in one act, without naming a " +
+      "single domain. So this guards audit integrity AND an " +
+      "escalation path. Only a human's click or the RBAC-gated control plane may write one.",
+  },
+  {
+    module: "agent/identity/trust.ts",
+    exportNames: ["registerSurfaces"],
+    reason:
+      "the one runtime write path for the operator-declared trust registry. Trust is boot-time " +
+      "config-as-code and must never become agent-writable.",
+  },
+  // FORWARD GUARD (OPE-517 / OPE-512): the pre-approval rules store currently has NO write path
+  // (config-as-code; pure readers only). If one is ever added, it belongs in a THIRD entry here —
+  // see the module header.
+];
+
+const PROTECTED_NAMES: ReadonlySet<string> = new Set(PROTECTED_HUMAN_ONLY_EXPORTS.flatMap((g) => g.exportNames));
+
+function groupFor(name: string): ProtectedHumanOnlyExportGroup {
+  const g = PROTECTED_HUMAN_ONLY_EXPORTS.find((group) => group.exportNames.includes(name));
+  if (!g) throw new Error(`human-only-invariants-manifest: "${name}" is not a protected export (internal error)`);
+  return g;
+}
+
+/** Blank out comment content so a name mentioned in prose is never mistaken for an import — the
+ *  same discipline principal-gate-manifest.ts's stripComments uses. Block-comment state is
+ *  tracked across lines; string literals are NOT parsed (a `//` inside one blanks the rest of the
+ *  line), which can only ever make this checker see LESS, never invent a site. */
+function stripComments(lines: readonly string[]): string[] {
+  let inBlock = false;
+  return lines.map((raw) => {
+    let out = "";
+    let i = 0;
+    while (i < raw.length) {
+      if (inBlock) {
+        if (raw.startsWith("*/", i)) {
+          inBlock = false;
+          out += "  ";
+          i += 2;
+        } else {
+          out += " ";
+          i += 1;
+        }
+        continue;
+      }
+      if (raw.startsWith("/*", i)) {
+        inBlock = true;
+        out += "  ";
+        i += 2;
+        continue;
+      }
+      if (raw.startsWith("//", i)) {
+        out += " ".repeat(raw.length - i);
+        break;
+      }
+      out += raw[i];
+      i += 1;
+    }
+    return out;
+  });
+}
+
+export interface ProtectedImportSite {
+  readonly file: string;
+  readonly line: number;
+  /** The protected name as IMPORTED (before any local `as` alias) — the alias cannot launder the
+   *  capability, so the site is reported on the original name. */
+  readonly name: string;
+  readonly group: ProtectedHumanOnlyExportGroup;
+}
+
+function lineAt(stripped: string, index: number | undefined): number {
+  return stripped.slice(0, index ?? 0).split("\n").length;
+}
+
+function namesFromBraceGroup(raw: string): string[] {
+  return raw
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0)
+    .map((s) => s.split(/\s+as\s+/i)[0]!.trim());
+}
+
+// PASS 1 — named bindings: `import { A, B as C } from`, the combined form, and the re-export form. A tool file re-exporting a protected name is as much a violation as one importing it.
+const IMPORT_BLOCK_RE = /\b(?:import|export)\s+(?:[A-Za-z_$][\w$]*\s*,\s*)?(?:type\s+)?\{([^}]*)\}\s*from\s*["'][^"']+["']/g;
+
+// PASS 2 — a destructured dynamic import, the same grammar awaited. The `await` is optional, because `.then` destructuring uses the bare form.
+const DYNAMIC_DESTRUCTURE_RE = /\b(?:const|let)\s*\{([^}]*)\}\s*=\s*(?:await\s+)?import\s*\(\s*["'][^"']+["']\s*\)/g;
+
+// PASS 3 — namespace bindings, static or dynamic: the binding itself is not a violation, a later member access is (found by `memberAccessSites`). Deliberately unbounded by module specifier, for the same reason PASS 1 is name-based rather than path-based.
+const NAMESPACE_IMPORT_RE = /\bimport\s+\*\s+as\s+([A-Za-z_$][\w$]*)\s+from\s+["'][^"']+["']/g;
+const DYNAMIC_NAMESPACE_RE = /\b(?:const|let)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:await\s+)?import\s*\(\s*["'][^"']+["']\s*\)/g;
+
+// PASS 4 — an inline dynamic access with no intermediate binding. The optional extra `)` absorbs the closing paren of the `(await …)` wrapper.
+const DYNAMIC_INLINE_ACCESS_RE = /\bimport\s*\(\s*["'][^"']+["']\s*\)\s*\)?\s*\.\s*([A-Za-z_$][\w$]*)/g;
+
+/** Every `<alias>.<protectedName>` access of a namespace handle bound to `alias`, anywhere in
+ *  `stripped` — PASS 3's second half. Unbounded scan (not "after the binding line") because a
+ *  static analysis has no reason to trust source order over a defect it can just find. */
+function memberAccessSites(file: string, stripped: string, alias: string): ProtectedImportSite[] {
+  const sites: ProtectedImportSite[] = [];
+  const re = new RegExp(`\\b${alias}\\s*\\.\\s*([A-Za-z_$][\\w$]*)`, "g");
+  for (const m of stripped.matchAll(re)) {
+    const name = m[1]!;
+    if (PROTECTED_NAMES.has(name)) sites.push({ file, line: lineAt(stripped, m.index), name, group: groupFor(name) });
+  }
+  return sites;
+}
+
+/** Every protected-export import, re-export or dynamic-access site in `source`. Pure, and it FINDS sites rather than deciding whether one is a violation — a driver over an allowlisted caller would have to filter its own results, and the root lint never does because it only ever scans the tool roster. */
+export function findProtectedImports(file: string, source: string): ProtectedImportSite[] {
+  const lines = source.split("\n");
+  const stripped = stripComments(lines).join("\n");
+  const sites: ProtectedImportSite[] = [];
+
+  for (const m of stripped.matchAll(IMPORT_BLOCK_RE)) {
+    for (const name of namesFromBraceGroup(m[1]!)) {
+      if (PROTECTED_NAMES.has(name)) sites.push({ file, line: lineAt(stripped, m.index), name, group: groupFor(name) });
+    }
+  }
+
+  for (const m of stripped.matchAll(DYNAMIC_DESTRUCTURE_RE)) {
+    for (const name of namesFromBraceGroup(m[1]!)) {
+      if (PROTECTED_NAMES.has(name)) sites.push({ file, line: lineAt(stripped, m.index), name, group: groupFor(name) });
+    }
+  }
+
+  const aliases = new Set<string>();
+  for (const m of stripped.matchAll(NAMESPACE_IMPORT_RE)) aliases.add(m[1]!);
+  for (const m of stripped.matchAll(DYNAMIC_NAMESPACE_RE)) aliases.add(m[1]!);
+  for (const alias of aliases) sites.push(...memberAccessSites(file, stripped, alias));
+
+  for (const m of stripped.matchAll(DYNAMIC_INLINE_ACCESS_RE)) {
+    const name = m[1]!;
+    if (PROTECTED_NAMES.has(name)) sites.push({ file, line: lineAt(stripped, m.index), name, group: groupFor(name) });
+  }
+
+  return sites;
+}