@open-everywhere/core 0.1.0

package/agent/access/egress-status.ts

@@ -0,0 +1,195 @@
+// The in-sandbox egress self-diagnosis files, derived from the COMPILED policy so they cannot drift from what is enforced. HOSTS ONLY: never a credential value, never a header name, and `compileError` is a boolean rather than the thrown message.
+
+import type { SandboxNetworkPolicy } from "eve/sandbox";
+import { lockCommand, unlockCommand } from "../memory/readonly.js";
+import { ruleStampsCredential } from "./egress.js";
+
+/** Workspace-relative dir, top-level and unhidden on purpose: the consumer is an agent running `ls`, and a dotfile is a surface nobody finds when they need it. */
+const EGRESS_DIR = "egress";
+export const EGRESS_STATUS_PATH = `${EGRESS_DIR}/STATUS.json`;
+export const EGRESS_README_PATH = `${EGRESS_DIR}/README.md`;
+
+/** What the last apply established about enforcement. Three values rather than a boolean: `dry-run` (the policy was computed and nothing was applied) and `unenforced` (the backend refused it and the operator accepted that) are different facts. */
+export type EgressEnforcementState = "enforced" | "dry-run" | "unenforced";
+
+/** One allowed host, as the FIREWALL sees it — narrowing included, credential value excluded. */
+export interface EgressAllowEntry {
+  readonly host: string;
+  /** Union of the HTTP methods across this host's rules; absent when no rule narrows by method. */
+  readonly methods?: readonly string[];
+  /** Union of the path prefixes across this host's rules; absent when no rule narrows by path. */
+  readonly pathPrefixes?: readonly string[];
+  /** True iff the firewall injects an auth header on requests to this host. The VALUE is never
+   *  disclosed — this flag exists so the agent stops trying to authenticate a call itself. */
+  readonly credentialInjected: boolean;
+}
+
+export interface EgressPolicySummary {
+  /** Always `"deny"` for a compiled OE policy; `"allow"` only if something ever hands us the
+   *  runtime's allow-all string, which would be a bug worth seeing in the file rather than hiding. */
+  readonly defaultAction: "deny" | "allow";
+  readonly allow: readonly EgressAllowEntry[];
+}
+
+export interface EgressStatusInput {
+  readonly policy: SandboxNetworkPolicy;
+  readonly state: EgressEnforcementState;
+  /** The sha-256 of the applied policy — the same value the `egress.policy` audit row carries, so a
+   *  worker's report and the operator's audit trail name the same generation. */
+  readonly fingerprint: string;
+  /** True iff the policy is a fail-closed deny-all produced by a COMPILE failure rather than by a
+   *  deliberately-empty grant. The message is withheld (see the header). */
+  readonly compileError: boolean;
+}
+
+/** Structural read of a compiled rule — `match` only. `transform` is deliberately typed as an
+ *  opaque array so nothing in this module can accidentally reach a header. */
+interface OpaqueRule {
+  readonly match?: { readonly method?: readonly string[]; readonly path?: { readonly startsWith?: string } };
+  readonly transform?: readonly { readonly headers?: Record<string, string> }[];
+}
+
+/** Reduce a compiled policy to its DISCLOSABLE shape. Pure, and it reads a closed set of fields rather than mapping over the object, because it is the one function allowed to turn a credential-bearing policy into sandbox-visible bytes. */
+export function summariseEgressPolicy(policy: SandboxNetworkPolicy): EgressPolicySummary {
+  if (typeof policy === "string") {
+    return { defaultAction: policy === "allow-all" ? "allow" : "deny", allow: [] };
+  }
+  const allowMap = (policy as { allow?: Record<string, readonly OpaqueRule[]> }).allow ?? {};
+  const allow: EgressAllowEntry[] = [];
+  for (const host of Object.keys(allowMap).sort((a, b) => a.localeCompare(b))) {
+    const rules = allowMap[host] ?? [];
+    const methods = new Set<string>();
+    const prefixes = new Set<string>();
+    let credentialInjected = false;
+    for (const rule of rules) {
+      for (const m of rule.match?.method ?? []) methods.add(m);
+      const prefix = rule.match?.path?.startsWith;
+      if (typeof prefix === "string" && prefix.length > 0) prefixes.add(prefix);
+      // Boolean only: never read a header key, never a value — only whether the rule stamps anything. Through the SHARED discriminator, so the file the agent reads and the audit row the auditor reads cannot disagree about one policy.
+      if (ruleStampsCredential(rule)) credentialInjected = true;
+    }
+    allow.push({
+      host,
+      ...(methods.size > 0 ? { methods: [...methods].sort() } : {}),
+      ...(prefixes.size > 0 ? { pathPrefixes: [...prefixes].sort() } : {}),
+      credentialInjected,
+    });
+  }
+  return { defaultAction: "deny", allow };
+}
+
+/** The status file's bytes, DETERMINISTIC — no clock and no counter — so two sessions on one policy produce byte-identical files. The *when* lives in the audit row. */
+export function renderEgressStatus(input: EgressStatusInput): string {
+  const summary = summariseEgressPolicy(input.policy);
+  return `${JSON.stringify(
+    {
+      enforcement: input.state,
+      defaultAction: summary.defaultAction,
+      policyFingerprint: input.fingerprint,
+      compileError: input.compileError,
+      allow: summary.allow,
+      readme: `./${EGRESS_README_PATH.split("/").pop()}`,
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+/** The self-help README: STATIC and pinned byte-for-byte by `egress-status-test.ts`, because every load-bearing sentence is a claim about how this deployment behaves. It must state BOTH tiers — a self-host proxy logs each denial as an `egress.denied` row, the Vercel sandbox host logs none. */
+export const EGRESS_README = `# Egress from this sandbox
+
+Network access out of this sandbox is **default-deny**. Only the hosts listed in
+\`STATUS.json\` are reachable; everything else fails at the firewall.
+
+Read \`STATUS.json\` first. It carries the enforcement state, every allowed host with any
+method/path narrowing on it, and \`policyFingerprint\`.
+
+## If a request was blocked
+
+**Do not retry it, and do not try to route around it.** A denial here is policy, not an
+outage: a retry, a mirror, a proxy, a different port and a different DNS name all fail the
+same way, and the only thing they cost is your turn.
+
+**Report it instead**, in your answer, naming the host you needed and what you needed it
+for. The policy that denied you is on the record — an \`egress.policy\` audit row carries the
+\`policyFingerprint\` above — but whether **the individual blocked request** is depends on the
+tier. Where the proxy is ours (self-host) each denial becomes an \`egress.denied\` row — host,
+that fingerprint, a count, nothing else — which \`permission_fit_report\` reads as widening
+evidence. On the Vercel sandbox host the deny is out of band and no row exists at all. You
+cannot tell which from in here, so report either way: yours is the only signal that always
+exists, and the only one that says what you wanted the host **for**.
+
+Widening is deliberately 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.
+
+## Three things that will save you a wrong guess
+
+**Never add an \`Authorization\` header yourself.** Where \`credentialInjected\` is true in
+\`STATUS.json\`, the firewall stamps the credential onto the request as it leaves. You do not
+hold that secret and cannot read it. A 401 from such a host means the credential is wrong or
+expired upstream, so report it; do not go looking for a key.
+
+**This route cannot use anyone's own account.** One credential per host per session, so an
+own-account ask withholds that vendor's hosts from \`STATUS.json\`. A worker never holds them.
+A seat is covered from the ask onward, and this file was written when the turn began — so for
+the rest of THAT turn the host can still be listed here, on the team key. Do not use it: the
+team key is never the answer to "act as me". A host missing for that reason is
+not a config gap: say so, and send the person to their DM with me, where a personal grant is
+minted.
+
+**\`web_fetch\` and \`web_search\` do not run in here.** They execute host-side, outside this
+sandbox. That changes WHO enforces, not WHAT is allowed: \`web_fetch\` is fenced against this
+same allow-list before it dispatches, so a host absent from \`STATUS.json\` is refused there
+too — audibly, naming the host, unlike the silent failure you get in here. \`web_search\` runs
+inside the model call and is bounded by neither. \`github.com\` is the exception: a repo grant
+lists it for \`git\`, not for \`web_fetch\`. This file is about what **you** run in here:
+\`curl\`, \`git\`, \`npm\`.
+
+## If \`enforcement\` is not "enforced"
+
+\`dry-run\` means the intended policy was computed but not applied (\`egress.enforce: false\`);
+\`unenforced\` means the backend refused it and the operator accepted that. In both cases the
+list is what the operator INTENDS you to reach. Stay inside it, and say so if you notice you
+did not have to.
+`;
+
+/** The narrow slice of a sandbox session this module needs — injected so the publish is testable
+ *  against a fake, and so nothing here can reach the rest of the sandbox surface. */
+export interface EgressStatusSandbox {
+  // `PromiseLike`, not `Promise`: the AI SDK sandbox surface types `writeTextFile` as
+  // `PromiseLike<void>`, and a real `SandboxSession` has to be assignable to this.
+  writeTextFile(options: { path: string; content: string }): PromiseLike<unknown>;
+  run(options: { command: string }): PromiseLike<unknown>;
+}
+
+/** Materialise both files, then chmod the dir read-only: this is the agent's own account of what it may reach, and a file it could rewrite is one it could talk itself into believing. Best-effort — a failure here must never block the policy that was just applied. */
+/** The read half of {@link EgressStatusSandbox} — separate because only ONE caller needs it (the
+ *  OPE-393 subagent invariant) and the publish path must stay unable to read anything. */
+export interface EgressStatusReadableSandbox {
+  // `string | null`, not `string`: the AI SDK sandbox surface answers `null` for a missing file, and a
+  // real `SandboxSession` has to be assignable to this (same reason `writeTextFile` above is typed
+  // `PromiseLike`). A missing file is precisely the ordinary case here — an unpublished parent.
+  readTextFile(options: { path: string }): PromiseLike<string | null>;
+}
+
+/** The `policyFingerprint` currently published in this sandbox, or `undefined` when there is none to read. TOTAL and fail-soft by contract: `undefined` means "cannot assert", never "violated" — this is a tripwire on a bug, not a control against the child. */
+export async function readPublishedEgressFingerprint(sandbox: EgressStatusReadableSandbox): Promise<string | undefined> {
+  try {
+    const raw = await sandbox.readTextFile({ path: EGRESS_STATUS_PATH });
+    if (typeof raw !== "string" || raw.length === 0) return undefined;
+    const parsed: unknown = JSON.parse(raw);
+    const fp = (parsed as { policyFingerprint?: unknown } | null)?.policyFingerprint;
+    return typeof fp === "string" && fp.length > 0 ? fp : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function publishEgressStatus(sandbox: EgressStatusSandbox, input: EgressStatusInput): Promise<void> {
+  await sandbox.run({ command: `${unlockCommand(EGRESS_DIR)} 2>/dev/null || true` });
+  await sandbox.writeTextFile({ path: EGRESS_STATUS_PATH, content: renderEgressStatus(input) });
+  await sandbox.writeTextFile({ path: EGRESS_README_PATH, content: EGRESS_README });
+  await sandbox.run({ command: `${lockCommand(EGRESS_DIR)} 2>/dev/null || true` });
+}

package/agent/access/egress.ts

@@ -0,0 +1,321 @@
+// Compiles resolved access into a Vercel sandbox NetworkPolicy: a credentialed host becomes an allow rule whose transform injects the auth header AT THE FIREWALL, so the secret never enters the sandbox process, and a host with no key is denied implicitly. Fine-grained policies are honoured only by the Vercel sandbox backend — Docker honours coarse allow-all/deny-all and just-bash rejects setNetworkPolicy — so this compiles everywhere and enforces only there.
+
+import type { SandboxNetworkPolicy } from "eve/sandbox";
+import type { EffectiveAccess, ReachableHost } from "./resolver.js";
+import { EgressHostCollisionError } from "./resolver.js";
+import { egressHostsOverlap, normaliseEgressHost, type Connection } from "./bundle.js";
+import { extraEgressHosts } from "./extra-hosts.js";
+import { browserEgressHosts, type BrowserHostDeclaration } from "./browser-hosts.js";
+import { GIT_BROKER_HOSTS } from "./reserved-hosts.js";
+import { DEFAULT_NETWORK_ACCESS_LEVEL, TRUSTED_ACCESS_HOSTS, type NetworkAccessLevel } from "./network-access.js";
+
+// The git read-broker's reserved hosts live in access/reserved-hosts.ts, which imports nothing, because browser-hosts.ts is a fourth reader and could not import them back from here without a cycle. Re-exported so every existing caller keeps one import path.
+export { GIT_BROKER_HOSTS } from "./reserved-hosts.js";
+
+// ONE row shape for outbound-call evidence across both egress planes. credential is an IDENTITY and never a secret, and the type cannot enforce that — what holds it is where the secret lives plus what the writers pass, and two canary tests assert it on the output. unit is the discriminator and a physical fact: the host plane counts one row per CALL, the sandbox plane one per policy APPLY, because eve's sandbox surface exposes no per-request event.
+
+// This block lives here rather than in its own module because a new file under packages/core/agent needs its own entry in this package's exports map. Move it to access/egress-audit-row.ts when a run that may touch package.json passes this way.
+
+export type EgressPlane = "sandbox" | "host";
+
+/** What ONE row counts — see the header's unit rule. `"call"` is one outbound call; `"policy"` is
+ *  one host that one firewall apply left open. Deliberately NOT called a grain: see the header. */
+export type EgressRowUnit = "call" | "policy";
+
+/** On unit "call": allowed means dispatched, denied means refused by policy before the dispatch (an SSRF refusal is denied, never failed), failed means attempted and errored. On unit "policy": granted only — the firewall was set to admit this host, which must never be read as a call. */
+export type EgressOutcome = "allowed" | "denied" | "failed" | "granted";
+
+/** One outbound-egress evidence row, in the shape BOTH planes write. Spread it through egressAuditFields and never hand-spell it at a writer: a second copy is how one plane starts naming a field something else and the join quietly stops working. */
+export interface EgressAuditRow {
+  readonly plane: EgressPlane;
+  readonly unit: EgressRowUnit;
+  /** The destination host, lower-cased. `"*"` is a catch-all allow rule, not a hostname. */
+  readonly host: string;
+  /** The HTTP verbs this row covers: exactly one on a call, the admitted set on a policy — or
+   *  `"any"` when the rule declares no method match at all and so admits DELETE as readily as GET.
+   *  Upper-cased and sorted so two rows for the same subject compare byte-for-byte. */
+  readonly verb: readonly string[] | "any";
+  /** WHOSE credential rides, by IDENTITY — a bundle `Connection.id`, or a credential ref name.
+   *  `null` is a positive claim: nothing was attached by the plane. 🔴 Never a secret value. */
+  readonly credential: string | null;
+  readonly outcome: EgressOutcome;
+}
+
+/** Every field an {@link EgressAuditRow} carries. The contract test iterates THIS list against a
+ *  row from each plane, so a field added here without a writer to fill it fails loudly rather than
+ *  landing as an absence on one plane only. */
+export const EGRESS_AUDIT_ROW_FIELDS = ["plane", "unit", "host", "verb", "credential", "outcome"] as const;
+
+/** Upper-case, de-duplicate and sort a verb list, or pass `"any"` through. Shared so a call's one
+ *  verb and a policy's set are normalised by the same rule. */
+export function normaliseVerbs(verbs: readonly string[] | "any"): readonly string[] | "any" {
+  if (verbs === "any") return "any";
+  return [...new Set(verbs.map((v) => v.toUpperCase()))].sort();
+}
+
+/** Render one row, ready to spread into an audit detail. Total and pure: the host is lower-cased and the verbs normalised here rather than at each writer, so two planes describing the same host cannot disagree on its spelling. */
+export function egressAuditFields(row: EgressAuditRow): Record<string, unknown> {
+  return {
+    plane: row.plane,
+    unit: row.unit,
+    host: row.host.toLowerCase(),
+    verb: normaliseVerbs(row.verb),
+    credential: row.credential,
+    outcome: row.outcome,
+  };
+}
+
+/** The host plane's row: one call Open Everywhere dispatched itself. credential defaults to null — the oeFetch case, which sends nothing on a model-supplied URL by construction — and a seam that does attach one passes its ref NAME. */
+export function hostCallAuditFields(args: {
+  readonly host: string;
+  readonly verb: string;
+  readonly outcome: EgressOutcome;
+  readonly credential?: string | null;
+}): Record<string, unknown> {
+  return egressAuditFields({
+    plane: "host",
+    unit: "call",
+    host: args.host,
+    verb: [args.verb],
+    credential: args.credential ?? null,
+    outcome: args.outcome,
+  });
+}
+
+/** The sandbox plane's row: one host one firewall apply left open. outcome is fixed at "granted" and is not a parameter, because the only way this plane could report a call's fate is a per-call observation it does not have. */
+export function sandboxPolicyAuditFields(args: {
+  readonly host: string;
+  readonly verb: readonly string[] | "any";
+  readonly credential: string | null;
+}): Record<string, unknown> {
+  return egressAuditFields({
+    plane: "sandbox",
+    unit: "policy",
+    host: args.host,
+    verb: args.verb,
+    credential: args.credential,
+    outcome: "granted",
+  });
+}
+
+export type ResolveHeaders = (connection: Connection) => Promise<Record<string, string>>;
+
+/** Resolve the still-granted subset of connection ids against the live connector_override store — the same break-glass overlay the credential gate consults, narrow-only. null means the store read itself failed: fail closed and deny every credentialed host rather than fall back to the config grant. Injected so this compiler stays pure and testable. */
+export type NarrowConnections = (connectionIds: readonly string[]) => Promise<readonly string[] | null>;
+
+// A structural mirror of Vercel's NetworkPolicyRule, which eve does not export publicly; the git read-broker builds this same shape rather than a second, driftable copy. Since eve 0.27.1 the real rule REQUIRES transform, so an EMPTY array is the "allow, inject nothing" shape a match-only rule used to express by omission.
+export type EgressRule = {
+  match?: { method?: string[]; path?: { startsWith?: string } };
+  transform: { headers?: Record<string, string> }[];
+};
+
+function ruleForHost(
+  host: ReachableHost,
+  headers: Record<string, string> | null,
+): EgressRule[] {
+  if (host.viaConnection === null) return [];
+
+  const method = host.methods && host.methods.length > 0 ? [...host.methods] : undefined;
+  const transform = headers && Object.keys(headers).length > 0 ? [{ headers }] : [];
+
+  // Emit ONE allow rule per prefix — the rules array is an OR. Narrowing only when exactly one prefix was declared produced NO path restriction for two, which is fail-OPEN; every rule still carries the method match and the credential transform.
+  const prefixes = host.pathPrefixes ?? [];
+  if (prefixes.length > 0) {
+    return prefixes.map((prefix) => {
+      const rule: EgressRule = { match: { path: { startsWith: prefix } }, transform };
+      if (method) rule.match!.method = method;
+      return rule;
+    });
+  }
+
+  const rule: EgressRule = { transform };
+  if (method) rule.match = { method };
+  return [rule];
+}
+
+// A declared browser host compiles to a host+METHOD row the firewall enforces, so there is no verb the row omits that the browser can still reach, and a row naming a credential this session does not carry is DROPPED entirely rather than opened bare. The secret lives in transform and nowhere else, and this does NOT scope it to the browser: the stamped host is equally reachable from bash in that session, bounded only by the declared methods.
+
+/** The allow-map entries the declared browser hosts contribute, keyed by host. byId, grantedIds and resolveHeaders are passed in rather than re-derived, because a second lookup path is how a break-glass revoke stops reaching one of two callers; a null grantedIds denies every credentialed host here exactly as it does for a bundle host. */
+async function browserHostRules(
+  byId: ReadonlyMap<string, Connection>,
+  grantedIds: ReadonlySet<string> | null,
+  resolveHeaders: ResolveHeaders,
+): Promise<Record<string, EgressRule[]>> {
+  const armed = browserEgressHosts();
+
+  // A reserved broker host is REFUSED here, not merged: the broker replaces those hosts' rules wholesale mid-turn, so a declared row on github.com would lose both its verb narrowing and the credential the operator named. The throw is the same error family hooks/egress.ts turns into a deny-all apply, and the check overlaps and normalises rather than using a bare includes, because it is a backstop for a declaration the config lint never saw.
+  const collisions: string[] = [];
+  for (const row of armed) {
+    const claimed = normaliseEgressHost(row.host);
+    for (const host of GIT_BROKER_HOSTS) {
+      if (!egressHostsOverlap(claimed, host)) continue;
+      const where = claimed === host ? host : `${claimed} overlaps ${host}`;
+      collisions.push(`${where} (declared browser host, and the git read-broker, which replaces that host's rules mid-turn)`);
+    }
+  }
+  if (collisions.length > 0) throw new EgressHostCollisionError(collisions);
+
+  const out: Record<string, EgressRule[]> = {};
+  for (const row of armed) {
+    const method = [...row.methods];
+    if (row.credential === undefined) {
+      out[row.host] = [{ match: { method }, transform: [] }];
+      continue;
+    }
+    if (grantedIds === null || !grantedIds.has(row.credential)) continue; // revoked / unreadable store
+    const conn = byId.get(row.credential);
+    if (conn === undefined) continue; // this session's access does not carry the named connection
+    const headers = await resolveHeaders(conn);
+    // An empty header map means the broker resolved nothing. That is the same unhonourable request as
+    // a missing connection — omit rather than open the host with no credential on it.
+    if (Object.keys(headers).length === 0) continue;
+    out[row.host] = [{ match: { method }, transform: [{ headers }] }];
+  }
+  return out;
+}
+
+/** Build the sandbox NetworkPolicy for a resolved session; returns "deny-all" when nothing is reachable, which is fail-closed. networkAccessLevel is ADDITIVE only — "none" adds nothing, "trusted" adds bare registry and developer hosts, "full" adds a catch-all — and a host the resolved access already reaches keeps its own rules. */
+export async function compileNetworkPolicy(
+  access: EffectiveAccess,
+  resolveHeaders: ResolveHeaders,
+  narrowConnections: NarrowConnections,
+  networkAccessLevel: NetworkAccessLevel = DEFAULT_NETWORK_ACCESS_LEVEL,
+): Promise<SandboxNetworkPolicy> {
+  const byId = new Map(access.connections.map((c) => [c.id, c]));
+  const allow: Record<string, EgressRule[]> = {};
+
+  // The live revoke_connector override is consulted HERE too, keyed by connection id and narrow-only: applied only at the credential gate, a revoked host kept its injected credential in this allow-list until a deploy removed the bundle grant. The store read is skipped when nothing credentialed needs narrowing, which keeps a domain-only bundle's per-turn recompile a pure function.
+  const connectionIds = [...byId.keys()];
+  const granted = connectionIds.length > 0 ? await narrowConnections(connectionIds) : [];
+  // `null` = the override-store read itself failed: fail closed like the credential wall, denying
+  // EVERY credentialed host rather than trusting the config grant — an unreadable store must never
+  // be read as "nothing was revoked".
+  const grantedIds = granted === null ? null : new Set(granted);
+
+  for (const host of access.reachableHosts) {
+    if (host.viaConnection !== null && (grantedIds === null || !grantedIds.has(host.viaConnection))) {
+      continue; // narrowed by a break-glass revoke, or the override store couldn't be read
+    }
+    let headers: Record<string, string> | null = null;
+    if (host.viaConnection) {
+      const conn = byId.get(host.viaConnection);
+      headers = conn ? await resolveHeaders(conn) : null;
+    }
+    allow[host.host] = ruleForHost(host, headers);
+  }
+
+  // The declared browser hosts are merged under the SAME composition rule as everything else here: a host the bundle already reaches keeps its bundle rules.
+  for (const [host, rules] of Object.entries(await browserHostRules(byId, grantedIds, resolveHeaders))) {
+    if (!(host in allow)) allow[host] = rules;
+  }
+
+  // Capability-registered hosts merge as bare credential-less allows, and a host the bundle already reaches keeps its rules; living here means every recompile carries them. It runs AFTER the browser section and the order is load-bearing: a browser host that section narrowed, or fail-closed omitted, must not be re-opened here as a bare all-verbs allow.
+  for (const host of extraEgressHosts()) {
+    if (!(host in allow)) allow[host] = [];
+  }
+
+  // A granted repo implies the git host must be reachable, as a BARE allow: the read credential is brokered separately at SCM-call time, by a recompile that replaces this entry with owner-scoped rules. The bare entry stands as-is only where the firewall cannot be enforced at all.
+  if (access.repos.length > 0 && !allow["github.com"]) allow["github.com"] = [];
+
+  if (networkAccessLevel === "trusted") {
+    for (const host of TRUSTED_ACCESS_HOSTS) if (!(host in allow)) allow[host] = [];
+  } else if (networkAccessLevel === "full") {
+    if (!("*" in allow)) allow["*"] = [];
+  }
+
+  if (Object.keys(allow).length === 0) return "deny-all"; // fail-closed: nothing reachable
+  return { allow };
+}
+
+// The join an auditor needs: the hosts a policy leaves open to a MUTATING verb, each beside the connection id that opened it. Deliberately narrow, because listing every read-only allow would bury the two that matter. No byte of transform may reach a row — it is read for PRESENCE alone — and the input is the COMPILED policy, so a revoked host is absent and a registry or access-level top-up is present.
+
+/** The HTTP verbs that read. Anything else — and any rule that declares no method match at all —
+ *  can mutate the far side, so it is what {@link openWriteHosts} reports. */
+const READ_ONLY_METHODS: ReadonlySet<string> = new Set(["GET", "HEAD", "OPTIONS"]);
+
+/** A host one compiled policy leaves open to a mutating request. credential and verb are the SHARED egress-row names, not local spellings: rename either and the cross-plane join silently stops working, and the contract test is what says so. */
+export interface OpenWriteHost {
+  /** The allow-list key. `"*"` is the `networkAccessLevel: "full"` catch-all. */
+  readonly host: string;
+  /** The egress Connection.id whose credential this policy stamps on requests to this host, or null when no bundle connection names the stamp — an uncredentialed host, or a stamp from outside the bundle such as the broker's installation token. It is the credential's IDENTITY and never its value; read it WITH credentialed. */
+  readonly credential: string | null;
+  /** Whether this policy stamps ANY credential on this host, read off the compiled rules' own transform and never off the config. false is a positive claim, so an unrecognised transform shape errs toward "a credential rides" rather than toward that claim. */
+  readonly credentialed: boolean;
+  /** The methods the rules admit, upper-cased and de-duplicated — or `"any"` when at least one
+   *  rule for the host declares no method match, which admits DELETE as readily as GET. */
+  readonly verb: readonly string[] | "any";
+}
+
+/** THE one discriminator for "does the firewall stamp a credential here" — the audit row and the sandbox STATUS.json both call it, and nothing else may spell the test again, or a policy could make one say a credential rides while the other says nothing does. It reads the transform ENTRY rather than its headers, so an unrecognised shape resolves toward "a credential rides"; it returns a boolean, and no key and no value leaves it. */
+export function ruleStampsCredential(rule: { readonly transform?: readonly unknown[] }): boolean {
+  return (rule.transform ?? []).length > 0;
+}
+
+/** Cap on the `writeHosts` names ONE audit row lists. The `writeHostCount` beside it stays exact,
+ *  so a truncated list never tells a reader a smaller number. */
+const WRITE_HOSTS_ROW_CAP = 20;
+
+/** The writeHosts trio, ready to spread into an egress.policy detail, shared rather than spelled at each of the three writers an auditor joins on these names. writeHostCount rides EVERY row, 0 included, and each listed entry carries unit "policy", which tells a reader joining the planes that it is a reach the firewall granted and not a call anybody observed. */
+export function writeHostsAuditFields(writeHosts: readonly OpenWriteHost[]): Record<string, unknown> {
+  const listed = writeHosts.slice(0, WRITE_HOSTS_ROW_CAP).map((h) => ({
+    ...sandboxPolicyAuditFields({ host: h.host, verb: h.verb, credential: h.credential }),
+    credentialed: h.credentialed,
+  }));
+  return {
+    writeHostCount: writeHosts.length,
+    ...(listed.length > 0 ? { writeHosts: listed } : {}),
+    ...(writeHosts.length > WRITE_HOSTS_ROW_CAP ? { writeHostsTruncated: true } : {}),
+  };
+}
+
+/** Pure and total, sorted by host so two rows for one policy generation compare byte-for-byte; every unrecognised policy shape resolves toward MORE open, because an empty result reads as "this policy opened nothing mutating". A host is attributed only where its compiled rules really carry a transform, and a CALLER that replaced a host's rules must drop that host from reachableHosts, or the row names a bundle connection whose secret is not the one riding. */
+export function openWriteHosts(
+  policy: SandboxNetworkPolicy,
+  reachableHosts: readonly ReachableHost[] = [],
+  browserHosts: readonly BrowserHostDeclaration[] = [],
+): readonly OpenWriteHost[] {
+  if (typeof policy === "string") {
+    // `"allow-all"` carries no rules, so it stamps nothing — it is reach without a credential.
+    return policy === "allow-all" ? [{ host: "*", credential: null, credentialed: false, verb: "any" }] : [];
+  }
+  const allow = (policy as { allow?: readonly string[] | Record<string, EgressRule[]> }).allow;
+  if (!allow) return [];
+  // A declared browser host's credential is named by its own declaration, not by reachableHosts, which never mentions it. Layered UNDER the bundle entries on purpose: where both name one host the bundle's rules are the ones that compiled, so the bundle's connection id is the one that rides.
+  const viaByHost = new Map<string, string | null>(browserHosts.map((h) => [h.host, h.credential ?? null]));
+  for (const h of reachableHosts) viaByHost.set(h.host, h.viaConnection);
+  const byHost = (a: { host: string }, b: { host: string }): number => (a.host < b.host ? -1 : a.host > b.host ? 1 : 0);
+  if (Array.isArray(allow)) {
+    // A bare host array declares no rules at all, so it stamps no credential on any of its hosts —
+    // whatever the config wished for them.
+    return allow.map((host) => ({ host, credential: null, credentialed: false, verb: "any" as const })).sort(byHost);
+  }
+  const out: OpenWriteHost[] = [];
+  for (const [host, rules] of Object.entries(allow)) {
+    let unrestricted = false;
+    let credentialed = false;
+    const methods = new Set<string>();
+    for (const rule of rules ?? []) {
+      if (ruleStampsCredential(rule)) credentialed = true;
+      const declared = rule.match?.method;
+      // A rule with no method match admits every verb — the un-narrowed shape access/lint.ts's
+      // `methods` floor exists to make an operator declare away.
+      if (!declared || declared.length === 0) {
+        unrestricted = true;
+        continue;
+      }
+      for (const m of declared) methods.add(m.toUpperCase());
+    }
+    // An EMPTY rules array is the bare allow `ruleForHost` emits for a credential-less host: no
+    // match, so no narrowing, so every verb.
+    if ((rules ?? []).length === 0) unrestricted = true;
+    const writes = unrestricted || [...methods].some((m) => !READ_ONLY_METHODS.has(m));
+    if (!writes) continue;
+    out.push({
+      host,
+      credential: credentialed ? (viaByHost.get(host) ?? null) : null,
+      credentialed,
+      verb: unrestricted ? "any" : [...methods].sort(),
+    });
+  }
+  return out.sort(byHost);
+}

package/agent/access/enforcement.ts

@@ -0,0 +1,25 @@
+// Carries whether THIS session's egress firewall is genuinely enforced, stamped once by hooks/egress.ts so an SCM tool can pick a posture without re-running the resolve. Not enforced means the sandbox is not actually firewalled, so the read token falls back into the sandbox. FAIL CLOSED on the read side.
+
+import { defineState } from "eve/context";
+
+const slot = defineState<boolean>("open-everywhere.egress-enforced", () => true);
+
+/** Stamp whether THIS session's egress policy is actually being enforced. Fail-soft. */
+export function stampEnforcement(enforced: boolean): void {
+  try {
+    slot.update(() => enforced);
+  } catch {
+  }
+}
+
+/**
+ * Is this session's firewall enforced? Fail-closed: outside a session (unit tests,
+ * CLI) or before the hook has stamped anything, reads as enforced.
+ */
+export function isEnforced(): boolean {
+  try {
+    return slot.get();
+  } catch {
+    return true;
+  }
+}

package/agent/access/eve-patch-probe-boot.ts

@@ -0,0 +1,91 @@
+// The BOOT SIDE EFFECT of the unpatched-eve refusal (OPE-2182). Import this module for effect and
+// nothing else; every decision it takes lives in `eve-patch-probe.ts`, which stays pure so a test
+// can drive each missing part without a process that refuses to start.
+//
+// 🔴 THE TOP-LEVEL `await` IS THE MECHANISM, NOT A STYLE CHOICE. A module-evaluation throw is what
+// "refuses to boot" means here: every importer's evaluation fails, so the channel never mounts, the
+// agent root never finishes loading, and NO wake is served. A probe that merely set a flag would
+// leave the refusal up to whoever remembered to read it, which is the silent shape this ticket
+// closes.
+//
+// WHAT IT COSTS, PLAINLY. One eve-carrier load, about 0.7 s, once per process. A process that
+// serves a turn pays that load anyway and only pays it EARLIER. A process that never takes a turn
+// pays it as NEW cost, and most of the test chain is exactly that: `channels/unified.ts` is
+// imported by 40-odd core modules, so many suites now load four eve dist files they never needed.
+// That is the accepted price of deciding the question before the first wake rather than after it.
+//
+// WHERE IT IS IMPORTED, and why more than one place: `agent/agent.ts` is THIS deployment's boot
+// root, and `agent/channels/unified.ts` + `agent/channels/webhooks.ts` are core's two wake doors,
+// which is what an npm consumer of `@open-everywhere/core` mounts instead of our agent root. A
+// consumer cannot serve a wake through core without loading one of the two channels.
+//
+// 🔴 THE AUDIT ROW IS BEST-EFFORT AND USUALLY LOST — STDERR AND THE THROW ARE THE RECORD. This
+// module evaluates at its FIRST position in the import graph, not where an agent root lists it:
+// `agent/lib/register-config.js` reaches it transitively (measured — importing that module alone
+// publishes the markers), so it runs BEFORE `register-adapters.js` arms the operational store. A
+// row written then has no store to land in. `appendAudit` is contractually non-throwing, but its
+// provider can throw under a configured backend, so both calls are wrapped as well: the refusal
+// message must reach stderr and the throw must propagate even when the audit plane cannot answer.
+// Do NOT reorder anything to arm the store first — the throw is the mechanism, and it must not wait.
+//
+// The audit names are written as LITERALS at each call below, never through a helper that forwards
+// an `action` parameter: `lint:audit-actions` reads the write sites statically, and a forwarding
+// helper is a "road" it refuses until the road itself is declared.
+//
+// This closes the node_modules install. The INLINED hosted build is closed at the turn edge instead
+// — `hooks/eve-patch-gate.ts`, which needs no path to resolve. Neither path serves a wake on an
+// unpatched eve.
+
+import { appendAudit } from "../audit/audit.js";
+import { deploymentOrg } from "../identity/deployment-identity.js";
+import { assertEvePatched } from "./eve-patch-probe.js";
+
+try {
+  const result = await assertEvePatched();
+  if (result.status === "unverifiable") {
+    // Not a refusal, and NOT the end of the check — see eve-patch-probe.ts's header. The eve
+    // package root does not resolve here, which is expected on a hosted build that inlines eve.
+    // `hooks/eve-patch-gate.ts` re-asks at `turn.started`, where the carriers have evaluated and no
+    // path is needed, so an unpatched inlined build fails its first turn rather than serving it.
+    // The `test` chain (`lint:eve-patch`, `test:eve-install`) is the earlier control; nothing in
+    // `npm run build` itself re-checks the eve bytes.
+    console.warn(
+      `[open-everywhere:eve-patch-probe:boot] eve patch state UNVERIFIABLE at boot — the eve package ` +
+        `root did not resolve (${result.reason ?? "unknown reason"}), which is expected on a hosted ` +
+        `build that inlines eve. This is NOT a pass: the turn gate (hooks/eve-patch-gate.ts) re-checks ` +
+        `the markers at turn.started and refuses the turn if any is missing. A node_modules install is ` +
+        `verified here; \`lint:eve-patch\` and \`test:eve-install\` verify the bytes before a deploy.`,
+    );
+    try {
+      await appendAudit({
+        org: deploymentOrg(),
+        platform: "boot",
+        workspace: "boot",
+        action: "eve.patch.unverifiable",
+        detail: { reason: result.reason ?? "unknown" },
+      });
+    } catch {
+      /* the warn above is the record — see this file's header on the unarmed store */
+    }
+  }
+} catch (err) {
+  // The refusal reaches stderr FIRST: the re-throw below aborts this module's evaluation, and an
+  // operator reading a cold-start crash sees the framework's error, not necessarily ours. stderr is
+  // also the only channel that certainly works — a refusal can land before the audit plane is up.
+  const message = err instanceof Error ? err.message : String(err);
+  console.error(message);
+  // The row is attempted AFTER the message is on stderr and its failure is swallowed, so nothing
+  // between here and the re-throw can suppress either the message or the refusal.
+  try {
+    await appendAudit({
+      org: deploymentOrg(),
+      platform: "boot",
+      workspace: "boot",
+      action: "eve.patch.refused",
+      detail: { message },
+    });
+  } catch {
+    /* the stderr line above is the record — see this file's header */
+  }
+  throw err;
+}