@open-everywhere/create 0.6.0 → 0.8.0

package/template/deploy/egress-proxy/control/acl.ts

@@ -0,0 +1,228 @@
+// Pure ACL logic for the Open Everywhere egress-proxy control service.
+//
+// This is the enforcement decision the Squid `external_acl_type` helper calls per request:
+// given a source IP + destination host (+ method/path when the request is decrypted in
+// Tier B), decide allow/deny against the compiled SandboxNetworkPolicy the app PUSHED for
+// that source, and — in Tier B — return the credential-injection headers to stamp.
+//
+// Deliberately dependency-free (no eve, no npm): it is imported by server.ts, unit-tested
+// via tsx (acl-test.ts), and runs under Node's native TS stripping in the proxy container.
+//
+// The policy shape mirrors eve's SandboxNetworkPolicy (Vercel NetworkPolicy) — a structural
+// copy so this module needs no eve import. See
+// node_modules/eve/dist/src/compiled/@vercel/sandbox/network-policy.d.ts.
+
+export type NetworkTransformer = { headers?: Record<string, string> };
+export type PolicyMatch = {
+  path?: { exact?: string; startsWith?: string; regex?: string };
+  method?: string[];
+};
+export type PolicyRule = { match?: PolicyMatch; transform?: NetworkTransformer[] };
+export type EgressPolicy =
+  | "allow-all"
+  | "deny-all"
+  | {
+      allow?: string[] | Record<string, PolicyRule[]>;
+      subnets?: { allow?: string[]; deny?: string[] };
+    };
+
+export interface AclRequest {
+  /** Destination host (SNI for Tier A peek, CONNECT target, or Host header for Tier B). */
+  host: string;
+  /** HTTP method — only known in Tier B (decrypted). Undefined ⇒ Tier A, method un-checkable. */
+  method?: string;
+  /** Request path — only known in Tier B. Undefined ⇒ Tier A, path un-checkable. */
+  path?: string;
+}
+
+export interface AclDecision {
+  readonly allow: boolean;
+  /** The allow-map key that matched (for logging). */
+  readonly matchedHost?: string;
+  /** Tier B credential-injection headers from the first matching rule's transforms. */
+  readonly headers?: Record<string, string>;
+}
+
+const DENY: AclDecision = { allow: false };
+
+/** Normalize a host for matching: lowercase, drop a trailing dot, strip any :port. */
+export function normalizeHost(host: string): string {
+  let h = host.trim().toLowerCase();
+  if (h.endsWith(".")) h = h.slice(0, -1);
+  // Strip a trailing :port, but leave bare IPv6 (no port) alone. CONNECT targets are
+  // "host:port"; SNI has no port. Only strip when there's a single trailing :digits.
+  const m = h.match(/^(.*):(\d+)$/);
+  if (m && !h.includes("::")) h = m[1];
+  // Strip IPv6 brackets if present ("[::1]:443" → "::1").
+  if (h.startsWith("[") && h.includes("]")) h = h.slice(1, h.indexOf("]"));
+  return h;
+}
+
+/** Normalize a source IP key: strip IPv4-mapped-IPv6 prefix so "::ffff:172.20.0.3" == "172.20.0.3". */
+export function normalizeSourceIp(ip: string): string {
+  const v = ip.trim().toLowerCase();
+  return v.startsWith("::ffff:") ? v.slice("::ffff:".length) : v;
+}
+
+/**
+ * Does an allow-map key match a destination host? Supports Vercel's `*` wildcard prefix
+ * (`*.npmjs.org` matches any subdomain of npmjs.org) and a bare `*` (match everything).
+ * A plain key matches its exact host only.
+ */
+export function hostKeyMatches(key: string, host: string): boolean {
+  const k = normalizeHost(key);
+  const h = normalizeHost(host);
+  if (k === "*") return true;
+  if (k.startsWith("*.")) {
+    const suffix = k.slice(1); // ".npmjs.org"
+    return h.endsWith(suffix) && h.length > suffix.length;
+  }
+  return k === h;
+}
+
+/** Does a single rule permit this request? method/path constraints are SKIPPED when the
+ * corresponding request field is undefined (Tier A can't see them — host granularity only). */
+function ruleAllows(rule: PolicyRule, req: AclRequest): boolean {
+  const m = rule.match;
+  if (!m) return true;
+  if (m.method && m.method.length > 0 && req.method !== undefined) {
+    const want = m.method.map((x) => x.toUpperCase());
+    if (!want.includes(req.method.toUpperCase())) return false;
+  }
+  if (m.path && req.path !== undefined) {
+    const p = req.path;
+    if (m.path.exact !== undefined && p !== m.path.exact) return false;
+    if (m.path.startsWith !== undefined && !p.startsWith(m.path.startsWith)) return false;
+    if (m.path.regex !== undefined) {
+      try {
+        if (!new RegExp(m.path.regex).test(p)) return false;
+      } catch {
+        return false; // an un-compilable regex fails closed
+      }
+    }
+  }
+  return true;
+}
+
+function mergeHeaders(rule: PolicyRule): Record<string, string> | undefined {
+  if (!rule.transform || rule.transform.length === 0) return undefined;
+  const out: Record<string, string> = {};
+  for (const t of rule.transform) {
+    if (t.headers) for (const [k, v] of Object.entries(t.headers)) out[k] = v;
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/**
+ * Decide allow/deny for `req` against `policy`. FAIL-CLOSED: an unknown host, a policy with
+ * no allow map, or "deny-all" all deny. "allow-all" allows. For the record form, the first
+ * rule that permits the request wins (its transform headers ride back for Tier B injection);
+ * an empty rules array is a bare allow (no headers).
+ */
+export function decide(policy: EgressPolicy | undefined, req: AclRequest): AclDecision {
+  if (policy === undefined) return DENY; // no policy pushed for this source yet
+  if (policy === "deny-all") return DENY;
+  if (policy === "allow-all") return { allow: true };
+  const allow = policy.allow;
+  if (!allow) return DENY;
+
+  if (Array.isArray(allow)) {
+    // Simple string list — host-level only, no credential injection.
+    for (const key of allow) {
+      if (hostKeyMatches(key, req.host)) return { allow: true, matchedHost: normalizeHost(key) };
+    }
+    return DENY;
+  }
+
+  // Record form: find the matching host key, then a permitting rule under it.
+  for (const [key, rules] of Object.entries(allow)) {
+    if (!hostKeyMatches(key, req.host)) continue;
+    if (!rules || rules.length === 0) return { allow: true, matchedHost: normalizeHost(key) };
+    for (const rule of rules) {
+      if (ruleAllows(rule, req)) {
+        return { allow: true, matchedHost: normalizeHost(key), headers: mergeHeaders(rule) };
+      }
+    }
+    // Host is listed but no rule permitted this specific method/path (Tier B narrowing).
+    return DENY;
+  }
+  return DENY;
+}
+
+/**
+ * In-memory policy store keyed by (normalized) source IP. The control service holds one
+ * compiled policy per active sandbox source. Unknown source ⇒ deny (fail-closed) — the
+ * internal-only Docker network is the structural backstop; this is the runtime floor.
+ */
+export class PolicyStore {
+  private readonly byIp = new Map<string, EgressPolicy>();
+  /** The APP's own allow list (OPE-2406), kept apart from every per-source session policy. See {@link validateHostPlanePolicy}. */
+  private hostPlanePolicy: EgressPolicy | undefined;
+
+  setHostPlane(policy: EgressPolicy): void {
+    this.hostPlanePolicy = policy;
+  }
+
+  /** Undefined until the app pushes one, which {@link decide} reads as deny. */
+  hostPlane(): EgressPolicy | undefined {
+    return this.hostPlanePolicy;
+  }
+
+  set(sourceIp: string, policy: EgressPolicy): void {
+    this.byIp.set(normalizeSourceIp(sourceIp), policy);
+  }
+
+  get(sourceIp: string): EgressPolicy | undefined {
+    return this.byIp.get(normalizeSourceIp(sourceIp));
+  }
+
+  delete(sourceIp: string): boolean {
+    return this.byIp.delete(normalizeSourceIp(sourceIp));
+  }
+
+  size(): number {
+    return this.byIp.size;
+  }
+
+  /** Decide for a source+request in one call (fail-closed on unknown source). */
+  decide(sourceIp: string, req: AclRequest): AclDecision {
+    return decide(this.get(sourceIp), req);
+  }
+}
+
+/**
+ * Validate a pushed policy body just enough to reject garbage before it becomes the ACL
+ * for a source. Returns the policy or throws with a reason (the server turns it into 400).
+ */
+export function validatePolicy(input: unknown): EgressPolicy {
+  if (input === "allow-all" || input === "deny-all") return input;
+  if (input && typeof input === "object") {
+    const obj = input as Record<string, unknown>;
+    const allow = obj.allow;
+    if (allow === undefined || Array.isArray(allow) || (allow && typeof allow === "object")) {
+      return input as EgressPolicy;
+    }
+  }
+  throw new Error('policy must be "allow-all", "deny-all", or an object with an `allow` list/map');
+}
+
+/**
+ * Validate a HOST-PLANE policy (OPE-2406): the hosts the APP process itself calls, for example the
+ * model gateway. It is narrower than {@link validatePolicy} on purpose. Only a list of exact hosts
+ * passes: no "allow-all", no wildcard, no rule map (so no Tier B credential injection on this plane).
+ * The app is the only writer, because the push needs the control token. The narrow shape keeps a
+ * wrong push from opening the whole internet to every request that carries the credential.
+ */
+export function validateHostPlanePolicy(input: unknown): EgressPolicy {
+  const allow = input && typeof input === "object" ? (input as Record<string, unknown>).allow : undefined;
+  if (!Array.isArray(allow) || allow.length === 0) {
+    throw new Error("host-plane policy must be an object with a non-empty `allow` list of exact hosts");
+  }
+  const hosts: string[] = [];
+  for (const h of allow) {
+    if (typeof h !== "string" || h.trim() === "") throw new Error("host-plane `allow` entries must be non-empty host strings");
+    if (h.includes("*")) throw new Error(`host-plane hosts are exact hosts, never a wildcard ("${h}")`);
+    hosts.push(normalizeHost(h));
+  }
+  return { allow: hosts };
+}

package/template/deploy/egress-proxy/control/handlers.ts

@@ -0,0 +1,174 @@
+// Pure request handlers for the control service — the policy-push handler, the ACL query
+// handler, and the two auth primitives (boot-time token requirement + bearer comparison),
+// factored out of the HTTP plumbing (server.ts) so all are unit-testable without opening a
+// socket (acl-test.ts).
+
+import { timingSafeEqual } from "node:crypto";
+import { PolicyStore, decide, validatePolicy, validateHostPlanePolicy, normalizeSourceIp, type AclRequest, type AclDecision } from "./acl.ts";
+
+export interface PushInput {
+  /** Parsed JSON body of POST /policy. */
+  readonly body: unknown;
+  /** The connection's remote address (the fallback source-IP key). */
+  readonly remoteAddr: string;
+  /** Whether the request carried the valid bearer token. Auth is never disabled — the control
+   * service refuses to boot without a token (see requireControlToken). */
+  readonly authOk: boolean;
+}
+
+/**
+ * The fatal message printed when the control service is started without a token. Kept next to
+ * requireControlToken so the test can pin the wording that operators will actually see.
+ */
+export const MISSING_TOKEN_FATAL =
+  "OE_EGRESS_PROXY_TOKEN is required — the control service writes the egress policy that is the " +
+  "only thing standing between the sandbox and the open internet, and it listens on the same " +
+  "network the sandbox runs on. Refusing to start without it. Generate one with " +
+  "`openssl rand -hex 32` and set it on BOTH the proxy and the app (docker-compose.yml passes " +
+  "it to both).";
+
+/**
+ * Resolve the control-plane bearer token, or throw. There is deliberately NO tokenless mode and
+ * no opt-out flag: this proxy exists only for self-host deploys, where an unauthenticated
+ * `POST /policy` lets any peer on the internal network (including a compromised sandbox) install
+ * an allow-all policy for itself and defeat default-deny egress entirely. Fail loud at boot
+ * rather than silently ship an open control plane.
+ */
+export function requireControlToken(raw: string | undefined): string {
+  const token = raw?.trim();
+  if (!token) throw new Error(MISSING_TOKEN_FATAL);
+  return token;
+}
+
+/**
+ * Constant-time bearer-token check for the `Authorization` header. Length is compared first
+ * (timingSafeEqual throws on a length mismatch), so this leaks the token's length and nothing
+ * else. Returns false for a missing/duplicated/non-Bearer header — fail-closed.
+ */
+export function bearerMatches(header: string | string[] | undefined, token: string): boolean {
+  if (typeof header !== "string") return false;
+  const prefix = "Bearer ";
+  if (!header.startsWith(prefix)) return false;
+  const got = Buffer.from(header.slice(prefix.length), "utf-8");
+  const want = Buffer.from(token, "utf-8");
+  if (got.length !== want.length) return false;
+  return timingSafeEqual(got, want);
+}
+
+export interface PushResult {
+  readonly status: number;
+  readonly body: unknown;
+  /** The source-IP key the policy was stored under (undefined on rejection). */
+  readonly keyed?: string;
+}
+
+/**
+ * Apply a policy push. Keys by the body's explicit `sourceIp` when present, else the
+ * connection's remote address (correct for the justbash topology, where the app pushes
+ * from the very IP its egress uses). Fail-closed on auth/validation.
+ *
+ * `plane: "host"` writes the HOST-PLANE policy instead (OPE-2406): the app's own allow list,
+ * which only a request that carries the control credential is decided against (see
+ * {@link handleAcl}). It is never keyed by source IP, so it never reaches a session. It travels
+ * in `hostPlane`, never in `policy`: a proxy built before the host plane validates `policy`
+ * and so refuses this body (400) instead of storing the list as the app IP's session policy.
+ */
+export function handlePolicyPush(store: PolicyStore, input: PushInput): PushResult {
+  if (!input.authOk) return { status: 401, body: { error: "unauthorized" } };
+  const body = input.body;
+  if (!body || typeof body !== "object") {
+    return { status: 400, body: { error: "expected a JSON object body" } };
+  }
+  const obj = body as Record<string, unknown>;
+  if (obj.plane !== undefined && obj.plane !== "host" && obj.plane !== "session") {
+    return { status: 400, body: { error: 'plane must be "host" or "session"' } };
+  }
+  if (obj.plane === "host") {
+    if (obj.policy !== undefined) return { status: 400, body: { error: "a host-plane push carries `hostPlane`, never `policy`" } };
+    let hostPolicy;
+    try {
+      hostPolicy = validateHostPlanePolicy(obj.hostPlane);
+    } catch (err) {
+      return { status: 400, body: { error: String(err instanceof Error ? err.message : err) } };
+    }
+    store.setHostPlane(hostPolicy);
+    return { status: 200, body: { ok: true, plane: "host", policies: store.size() }, keyed: "host-plane" };
+  }
+  let policy;
+  try {
+    policy = validatePolicy(obj.policy);
+  } catch (err) {
+    return { status: 400, body: { error: String(err instanceof Error ? err.message : err) } };
+  }
+  const explicit = typeof obj.sourceIp === "string" && obj.sourceIp.trim() ? obj.sourceIp.trim() : undefined;
+  const key = explicit ?? input.remoteAddr;
+  if (!key) return { status: 400, body: { error: "no source IP: set body.sourceIp or connect from the sandbox network" } };
+  store.set(key, policy);
+  return { status: 200, body: { ok: true, sourceIp: key, policies: store.size() }, keyed: key };
+}
+
+export interface AclQuery {
+  src?: string;
+  host?: string;
+  method?: string;
+  path?: string;
+  /** The request's `Proxy-Authorization` value, as Squid passed it. Absent ⇒ a session request. */
+  auth?: string;
+}
+
+export interface AclResult {
+  readonly decision: AclDecision;
+  /** True iff the query was well-formed enough to evaluate. Malformed ⇒ fail-closed deny. */
+  readonly evaluated: boolean;
+}
+
+/**
+ * Evaluate an ACL query from the Squid helper. Missing src/host ⇒ fail-closed deny (a
+ * malformed callout must never open the firewall). "-" is Squid's empty-field sentinel.
+ *
+ * 🔴 TWO PRINCIPALS, ONE SOURCE IP (OPE-2406). Under the justbash backend the app process and
+ * the agent's sandboxed session send from the same address, so the address cannot tell them
+ * apart. The credential does: the app sends `Proxy-Authorization: Bearer <control token>` on its
+ * own model call. The token stays in the app's environment, outside the session's shell, and a
+ * session that obtained it could already push itself any policy, so this adds no reach. So:
+ *   - no credential  → the SESSION policy for the source IP, exactly as before;
+ *   - the credential → the HOST-PLANE policy only, never the session policy;
+ *   - any other credential → deny. A wrong token never falls back to the session policy.
+ * The host plane never widens what a session reaches: a session request carries no credential,
+ * so the host-plane list is never consulted for it.
+ */
+export function handleAcl(store: PolicyStore, q: AclQuery, token?: string): AclResult {
+  const src = clean(q.src);
+  const host = clean(q.host);
+  if (!src || !host) return { decision: { allow: false }, evaluated: false };
+  const req: AclRequest = { host };
+  const method = clean(q.method);
+  const path = clean(q.path);
+  if (method) req.method = method;
+  if (path) req.path = path;
+  const auth = clean(q.auth);
+  if (auth !== undefined) {
+    if (token === undefined || !bearerMatches(auth, token)) return { decision: { allow: false }, evaluated: true };
+    // Host grain only: the host plane carries no rule map, so method/path cannot narrow or inject.
+    return { decision: decide(store.hostPlane(), { host }), evaluated: true };
+  }
+  return { decision: store.decide(src, req), evaluated: true };
+}
+
+/**
+ * Is a connection's remote address loopback (127.0.0.0/8 or ::1)? Gates /acl, which returns
+ * Tier B credential-injection headers and must only ever answer the in-container Squid helper
+ * (which calls over 127.0.0.1). A cross-container peer arrives under its network IP, never
+ * loopback, so it is refused. Empty/unknown ⇒ not loopback (fail-closed).
+ */
+export function isLoopbackAddr(addr: string | undefined): boolean {
+  if (!addr) return false;
+  const a = normalizeSourceIp(addr); // lowercases + strips the ::ffff: ipv4-mapped prefix
+  return a === "::1" || /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(a);
+}
+
+function clean(v: string | undefined): string | undefined {
+  if (v === undefined) return undefined;
+  const t = v.trim();
+  return t === "" || t === "-" ? undefined : t;
+}

package/template/deploy/egress-proxy/control/helper.cjs

@@ -0,0 +1,108 @@
+// Squid external_acl_type helper for the Open Everywhere egress proxy.
+//
+// Squid spawns this as a long-lived child, feeds it one whitespace-separated request line
+// per lookup on stdin, and reads one response line on stdout. We use the concurrency
+// (channel-id) protocol: each input line is `<id> <src> <host> <method> <path> <auth>` and each
+// output line is `<id> OK`/`<id> ERR`, optionally with a `message="..."` and, for Tier B,
+// a `authz="<header value>"` annotation Squid can stamp onto the forwarded request.
+//
+// It simply forwards the decision to the local control service (server.ts) over loopback.
+// Plain Node, zero deps (no TS) so it needs no build step.
+//
+// Squid config wires it as (deploy/egress-proxy/squid.conf):
+//   external_acl_type oe_egress ttl=0 negative_ttl=0 grace=0 concurrency=64 children-max=8 \
+//     children-startup=1 \
+//     %SRC %DST %METHOD %PATH %>{Proxy-Authorization} \
+//     /usr/bin/node /opt/oe-egress/control/helper.cjs
+// The last field is the request's Proxy-Authorization ("-" when absent). Only the APP's own
+// model call carries one (OPE-2406); the control service decides it against the host-plane
+// list, and every request without one against the session policy for its source IP.
+// (Tier A, no MITM: a CONNECT carries no method and no path, so only %SRC and %DST decide it —
+//  handleLine below blanks the CONNECT method and the rule matches at host grain. A plain-HTTP
+//  request on port 80 still arrives with a real method and path, and a rule's method/path
+//  narrowing does apply to that one.)
+
+const http = require("node:http");
+
+const CONTROL_HOST = process.env.OE_EGRESS_CONTROL_HOST_INTERNAL || "127.0.0.1";
+const CONTROL_PORT = Number(process.env.OE_EGRESS_CONTROL_PORT || 8080);
+
+function query(src, host, method, path, auth) {
+  return new Promise((resolve) => {
+    const qs = new URLSearchParams({ src: src || "", host: host || "", method: method || "", path: path || "", auth: auth || "" });
+    const req = http.request(
+      { host: CONTROL_HOST, port: CONTROL_PORT, path: `/acl?${qs.toString()}`, method: "GET", timeout: 2000 },
+      (res) => {
+        let buf = "";
+        res.on("data", (d) => (buf += d));
+        res.on("end", () => {
+          try {
+            resolve(JSON.parse(buf));
+          } catch {
+            resolve({ allow: false }); // fail-closed on a malformed control response
+          }
+        });
+      },
+    );
+    req.on("error", () => resolve({ allow: false })); // fail-closed if control is unreachable
+    req.on("timeout", () => {
+      req.destroy();
+      resolve({ allow: false });
+    });
+    req.end();
+  });
+}
+
+function esc(v) {
+  return String(v).replace(/"/g, '\\"');
+}
+
+async function handleLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return;
+  // Concurrency protocol: first token is the channel id.
+  const parts = trimmed.split(/\s+/);
+  const id = parts.shift();
+  const [src, host, rawMethod, path, auth] = parts;
+  // A CONNECT is tunnel establishment, not the inner HTTP request — in Tier A (splice, no
+  // decryption) we only ever see CONNECT, so treat its method/path as UNKNOWN and match at
+  // host granularity. In Tier B (bump) Squid re-issues the decrypted GET/POST with a real
+  // method+path, which arrives here for narrowing + header injection.
+  const method = rawMethod && rawMethod.toUpperCase() === "CONNECT" ? "" : rawMethod;
+  const decision = await query(dec(src), dec(host), dec(method), dec(path), dec(auth));
+  if (decision && decision.allow) {
+    // Tier B: pass the Authorization header value back as an annotation Squid stamps.
+    let extra = "";
+    if (decision.headers && decision.headers.authorization) {
+      extra = ` authz="${esc(decision.headers.authorization)}"`;
+    } else if (decision.headers && decision.headers.Authorization) {
+      extra = ` authz="${esc(decision.headers.Authorization)}"`;
+    }
+    process.stdout.write(`${id} OK${extra}\n`);
+  } else {
+    process.stdout.write(`${id} ERR message="denied by open-everywhere egress policy"\n`);
+  }
+}
+
+// Squid URL-ENCODES the fields it passes (%PATH and friends can hold spaces); decode defensively.
+function dec(v) {
+  if (v === undefined) return "";
+  try {
+    return decodeURIComponent(v);
+  } catch {
+    return v;
+  }
+}
+
+let backlog = "";
+process.stdin.setEncoding("utf-8");
+process.stdin.on("data", (chunk) => {
+  backlog += chunk;
+  let nl;
+  while ((nl = backlog.indexOf("\n")) >= 0) {
+    const line = backlog.slice(0, nl);
+    backlog = backlog.slice(nl + 1);
+    void handleLine(line);
+  }
+});
+process.stdin.on("end", () => process.exit(0));

package/template/deploy/egress-proxy/control/server.ts

@@ -0,0 +1,122 @@
+// Control service for the Open Everywhere egress proxy.
+//
+// Two clients:
+//  1. The app (agent/access/self-host-egress.ts) POSTs the compiled SandboxNetworkPolicy
+//     to POST /policy whenever it changes (session start + mid-turn git broker).
+//  2. The Squid `external_acl_type` helper (helper.cjs) GETs /acl per request to decide
+//     allow/deny and fetch any Tier B credential-injection headers.
+//
+// Dependency-free: Node's built-in http only, runs under `node --experimental-strip-types`
+// (Node 24) so no build step and no npm install in the proxy image. All decision logic
+// lives in the pure, unit-tested acl.ts / handlers.ts.
+//
+// Endpoints:
+//   POST   /policy    { policy, sourceIp?, sessionId? }  → store policy for a source IP
+//   POST   /policy    { plane: "host", hostPlane }       → store the app's HOST-PLANE allow list
+//   DELETE /policy    ?sourceIp=IP                        → drop a source's policy
+//   GET    /acl       ?src=&host=&method=&path=&auth=     → { allow, headers } (helper only)
+//   GET    /healthz                                       → 200
+//
+// Auth: OE_EGRESS_PROXY_TOKEN is REQUIRED — the service refuses to start without it (there is
+// no tokenless mode and no opt-out flag). POST/DELETE /policy require `Authorization: Bearer
+// <token>`; the listener is on the same internal network as the sandbox, so a tokenless control
+// plane would let a compromised sandbox POST itself an allow-all policy and walk out through the
+// proxy. /acl carries the Tier B credential-injection headers, so it is LOOPBACK-ONLY: the
+// handler refuses any /acl request whose peer is not 127.0.0.0/8 or ::1 (403). The in-container
+// Squid helper (helper.cjs) calls it over 127.0.0.1 and is unaffected; a sandbox on the
+// app-facing network therefore cannot read an injected credential back out.
+
+import http from "node:http";
+import { PolicyStore } from "./acl.ts";
+import { handlePolicyPush, handleAcl, isLoopbackAddr, requireControlToken, bearerMatches } from "./handlers.ts";
+
+const store = new PolicyStore();
+
+/** Fail loud and early: no token ⇒ no control plane. */
+function loadToken(): string {
+  try {
+    return requireControlToken(process.env.OE_EGRESS_PROXY_TOKEN);
+  } catch (err) {
+    console.error(`[oe-egress-control] FATAL: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+}
+
+const TOKEN = loadToken();
+const PORT = Number(process.env.OE_EGRESS_CONTROL_PORT ?? 8080);
+const HOST = process.env.OE_EGRESS_CONTROL_HOST ?? "0.0.0.0";
+
+function authOk(req: http.IncomingMessage): boolean {
+  return bearerMatches(req.headers["authorization"], TOKEN);
+}
+
+function remoteAddr(req: http.IncomingMessage): string {
+  return req.socket.remoteAddress ?? "";
+}
+
+function send(res: http.ServerResponse, status: number, body: unknown): void {
+  const payload = typeof body === "string" ? body : JSON.stringify(body);
+  res.writeHead(status, { "content-type": typeof body === "string" ? "text/plain" : "application/json" });
+  res.end(payload);
+}
+
+async function readJson(req: http.IncomingMessage): Promise<unknown> {
+  const chunks: Buffer[] = [];
+  for await (const c of req) chunks.push(c as Buffer);
+  const raw = Buffer.concat(chunks).toString("utf-8");
+  if (!raw) return undefined;
+  return JSON.parse(raw);
+}
+
+const server = http.createServer(async (req, res) => {
+  try {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    const path = url.pathname;
+
+    if (req.method === "GET" && path === "/healthz") return send(res, 200, { ok: true, policies: store.size(), hostPlane: store.hostPlane() !== undefined });
+
+    if (path === "/policy" && req.method === "POST") {
+      let body: unknown;
+      try {
+        body = await readJson(req);
+      } catch {
+        return send(res, 400, { error: "invalid JSON" });
+      }
+      const result = handlePolicyPush(store, { body, remoteAddr: remoteAddr(req), authOk: authOk(req) });
+      if (result.keyed) console.log(`[oe-egress-control] policy set for ${result.keyed} (${store.size()} session source(s) active)`);
+      return send(res, result.status, result.body);
+    }
+
+    if (path === "/policy" && req.method === "DELETE") {
+      if (!authOk(req)) return send(res, 401, { error: "unauthorized" });
+      const src = url.searchParams.get("sourceIp") ?? remoteAddr(req);
+      const removed = store.delete(src);
+      return send(res, 200, { ok: true, removed });
+    }
+
+    if (path === "/acl" && req.method === "GET") {
+      // /acl returns Tier B credential-injection headers; it is loopback-only (the in-container
+      // Squid helper calls over 127.0.0.1). Refuse any non-loopback peer so a sandbox on the
+      // app-facing network cannot read injected credentials back. See handlers.ts:isLoopbackAddr.
+      if (!isLoopbackAddr(remoteAddr(req))) return send(res, 403, { error: "forbidden" });
+      const q = {
+        src: url.searchParams.get("src") ?? undefined,
+        host: url.searchParams.get("host") ?? undefined,
+        method: url.searchParams.get("method") ?? undefined,
+        path: url.searchParams.get("path") ?? undefined,
+        auth: url.searchParams.get("auth") ?? undefined,
+      };
+      const { decision } = handleAcl(store, q, TOKEN);
+      return send(res, 200, { allow: decision.allow, headers: decision.headers ?? null, matchedHost: decision.matchedHost ?? null });
+    }
+
+    return send(res, 404, { error: "not found" });
+  } catch (err) {
+    console.error(`[oe-egress-control] error: ${String(err)}`);
+    return send(res, 500, { error: "internal error" });
+  }
+});
+
+server.listen(PORT, HOST, () => {
+  console.log(`[oe-egress-control] listening on ${HOST}:${PORT} (auth required on /policy)`);
+});