@open-everywhere/create 0.7.0 → 0.8.1

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)`);
+});

package/template/deploy/egress-proxy/entrypoint.sh

@@ -0,0 +1,62 @@
+#!/bin/sh
+# Entrypoint for the oe-egress-proxy container: start the policy control service, wire the
+# tier (A default / B if OE_EGRESS_MITM=1), then exec Squid in the foreground.
+set -eu
+
+CONTROL_PORT="${OE_EGRESS_CONTROL_PORT:-8080}"
+MITM="${OE_EGRESS_MITM:-0}"
+SQUID_CONF="/etc/squid/squid.conf"
+
+echo "[oe-egress] starting (MITM=$MITM) ..."
+
+# ── Control service (loopback + app-net): holds per-source policy, answers ACL callouts ──
+# Node 24 runs the TypeScript directly (native type stripping) — no build step, no tsx.
+node --experimental-strip-types /opt/oe-egress/control/server.ts &
+CONTROL_PID=$!
+
+# Wait for the control service to accept connections before Squid starts firing callouts.
+i=0
+while [ $i -lt 50 ]; do
+  if wget -q -O /dev/null "http://127.0.0.1:${CONTROL_PORT}/healthz" 2>/dev/null; then break; fi
+  i=$((i + 1)); sleep 0.2
+done
+
+# ── Fresh, writable copy of the config (the image ships it read-only) ──
+cp /opt/oe-egress/squid.conf "$SQUID_CONF"
+
+if [ "$MITM" = "1" ]; then
+  echo "[oe-egress] Tier B (MITM) enabled — generating CA + initialising cert DB."
+  sh /opt/oe-egress/gen-ca.sh
+  # Augment the forward-proxy listener with ssl-bump so CONNECTs can be decrypted.
+  sed -i \
+    "s#^http_port 3128\$#http_port 3128 ssl-bump generate-host-certificates=on dynamic_cert_mem_cache_size=4MB tls-cert=${OE_EGRESS_CA_DIR:-/opt/oe-egress/ca}/oe-egress-ca.crt tls-key=${OE_EGRESS_CA_DIR:-/opt/oe-egress/ca}/oe-egress-ca.key#" \
+    "$SQUID_CONF"
+  # Append the Tier B overlay directly (no conf.d include — see squid.conf).
+  cat /opt/oe-egress/tier-b.conf >> "$SQUID_CONF"
+  # Initialise the dynamic-cert DB used by security_file_certgen.
+  rm -rf /var/lib/squid/ssl_db
+  /usr/lib/squid/security_file_certgen -c -s /var/lib/squid/ssl_db -M 4MB || true
+  chown -R squid:squid /var/lib/squid 2>/dev/null || true
+else
+  echo "[oe-egress] Tier A (SNI/CONNECT host allow-deny, no decryption)."
+fi
+
+# Squid drops to the `squid` user. Give it ownership of its state dir, and chown the
+# container's stdout/stderr pipes so `access_log stdio:/dev/stdout` works as non-root
+# (opening /dev/stdout by path FATALs otherwise — see squid.conf).
+chown -R squid:squid /var/lib/squid 2>/dev/null || true
+chown squid:squid /dev/stdout /dev/stderr 2>/dev/null || true
+
+# The denial log (OPE-314). Created unconditionally so `access_log stdio:/var/log/oe-egress/...`
+# can always be opened — Squid FATALs on an access_log it cannot open, and the volume that shares
+# this file with the app is optional. Unmounted, the file lives inside the container and nobody
+# reads it; mounted, the app tails it (read-only) and turns denials into audit rows.
+mkdir -p /var/log/oe-egress
+chown -R squid:squid /var/log/oe-egress 2>/dev/null || true
+
+# Squid needs its swap/cache dirs initialised once.
+squid -N -f "$SQUID_CONF" -z 2>/dev/null || true
+
+echo "[oe-egress] launching squid."
+# -N = no daemon (stay in foreground so the container's lifecycle tracks squid).
+exec squid -N -f "$SQUID_CONF" -d 1

package/template/deploy/egress-proxy/gen-ca.sh

@@ -0,0 +1,42 @@
+#!/bin/sh
+# Generate the local MITM CA for Tier B (opt-in) of the Open Everywhere egress proxy.
+#
+# Produces, in the shared CA dir (default /opt/oe-egress/ca, a mounted volume in
+# docker-compose.yml so the app container can read the cert too):
+#   oe-egress-ca.key  — the CA private key (proxy-only; NEVER leaves the proxy container)
+#   oe-egress-ca.crt  — the CA certificate (installed into the app/sandbox trust store by
+#                       install-ca.sh so git/npm/curl trust the bumped TLS)
+#
+# Idempotent: if a CA already exists it is left untouched (re-running won't churn the cert
+# and invalidate an already-installed trust anchor). Delete the files to rotate.
+#
+# SECURITY: the CA key can mint a cert for ANY host. It is a real secret — keep it inside
+# the proxy container's volume, never commit it (deploy/egress-proxy/.gitignore blocks it),
+# and treat a leak as "rotate immediately". Tier B is opt-in precisely because introducing a
+# trusted CA into the guest is a real trust decision (see README client-compat caveats).
+set -eu
+
+CA_DIR="${OE_EGRESS_CA_DIR:-/opt/oe-egress/ca}"
+CA_KEY="$CA_DIR/oe-egress-ca.key"
+CA_CRT="$CA_DIR/oe-egress-ca.crt"
+CA_CN="${OE_EGRESS_CA_CN:-Open Everywhere Egress Proxy CA}"
+DAYS="${OE_EGRESS_CA_DAYS:-3650}"
+
+mkdir -p "$CA_DIR"
+
+if [ -f "$CA_KEY" ] && [ -f "$CA_CRT" ]; then
+  echo "[gen-ca] CA already present at $CA_DIR — leaving it untouched (delete to rotate)."
+  exit 0
+fi
+
+echo "[gen-ca] generating a new local CA in $CA_DIR ..."
+openssl genrsa -out "$CA_KEY" 4096
+openssl req -x509 -new -nodes -key "$CA_KEY" -sha256 -days "$DAYS" \
+  -subj "/CN=$CA_CN" \
+  -addext "basicConstraints=critical,CA:TRUE" \
+  -addext "keyUsage=critical,keyCertSign,cRLSign" \
+  -out "$CA_CRT"
+chmod 600 "$CA_KEY"
+chmod 644 "$CA_CRT"
+echo "[gen-ca] done. CA cert: $CA_CRT"
+echo "[gen-ca] install it into the app/sandbox with install-ca.sh (see README)."

package/template/deploy/egress-proxy/install-ca.sh

@@ -0,0 +1,39 @@
+#!/bin/sh
+# Install the Tier B MITM CA into THIS container's trust store + configure the common
+# clients (git/npm/curl) to trust and use the proxy. Run inside the APP container (and,
+# for the docker() sandbox backend, bake it into the sandbox image) — NOT the proxy.
+#
+# Requires the CA cert produced by gen-ca.sh, shared via the mounted /opt/oe-egress/ca
+# volume. No-op-safe to run more than once.
+#
+# ⚠ CLIENT-COMPAT CAVEATS (design flagged these — do not paper over them):
+#   - Tools that PIN certificates (some language package managers, apps with bundled CA
+#     stores that ignore the OS store) will still reject the bumped cert. Those hosts must
+#     be Tier-A-spliced (host allow, no decryption), not bumped.
+#   - Tools that IGNORE the proxy env (HTTPS_PROXY) bypass the proxy entirely. On the
+#     internal-only Docker network they then simply fail to connect (no WAN route) — the
+#     structural backstop turns a proxy-bypass into a hard failure, not a leak.
+#   - Node/npm read NODE_EXTRA_CA_CERTS, not always the OS store — set below.
+set -eu
+
+CA_CRT="${OE_EGRESS_CA_CRT:-/opt/oe-egress/ca/oe-egress-ca.crt}"
+PROXY_URL="${OE_EGRESS_PROXY_HTTP:-http://oe-egress-proxy:3128}"
+
+if [ ! -f "$CA_CRT" ]; then
+  echo "[install-ca] CA cert not found at $CA_CRT — run gen-ca.sh in the proxy first (Tier B)." >&2
+  exit 1
+fi
+
+# 1. OS trust store (alpine: ca-certificates). curl + git (via libcurl) pick this up.
+if command -v update-ca-certificates >/dev/null 2>&1; then
+  cp "$CA_CRT" /usr/local/share/ca-certificates/oe-egress-ca.crt 2>/dev/null \
+    || cp "$CA_CRT" /etc/ssl/certs/oe-egress-ca.pem
+  update-ca-certificates >/dev/null 2>&1 || true
+fi
+
+echo "[install-ca] CA installed. Export these in the app environment (compose sets them):"
+echo "  HTTP_PROXY=$PROXY_URL"
+echo "  HTTPS_PROXY=$PROXY_URL"
+echo "  NODE_EXTRA_CA_CERTS=$CA_CRT   # Node/npm trust the MITM CA"
+echo "  GIT_SSL_CAINFO=$CA_CRT        # git trusts the MITM CA"
+echo "[install-ca] (git also honors http.proxy=$PROXY_URL; npm honors https-proxy=$PROXY_URL)"

package/template/deploy/egress-proxy/squid.conf

@@ -0,0 +1,93 @@
+# Open Everywhere egress proxy — Squid base config.
+#
+# TIER A (default, NO MITM): a forward proxy that allows/denies each CONNECT (and plain
+# HTTP) request by destination host, decided live by the control service via an
+# external_acl callout. TLS is never decrypted — the raw bytes are tunnelled once the host
+# passes (peek-and-splice semantics fall out of a plain CONNECT tunnel: Squid sees the
+# CONNECT authority in cleartext and never terminates TLS). This restores the default-deny
+# exfiltration backstop on justbash/docker without KVM.
+#
+# TIER B (opt-in, MITM) lives in conf.d/tier-b.conf, dropped in by entrypoint.sh only when
+# OE_EGRESS_MITM=1. It ssl_bumps with a local CA so the decrypted request's method/path can
+# be narrowed and a credential header injected.
+#
+# NB the exact external_acl format codes below (%SRC %DST %METHOD %PATH) are the widely
+# supported named tokens; if your Squid build differs, adjust in one place here. See
+# deploy/egress-proxy/README.md.
+
+# Forward-proxy listener the app points HTTPS_PROXY/HTTP_PROXY at.
+http_port 3128
+
+# ── The live policy ACL: one callout per request to the control service (helper.cjs) ──
+# ttl=0 → never cache a decision (the policy changes mid-turn via the git broker).
+# %>{Proxy-Authorization} names the PRINCIPAL (OPE-2406). The app's own model call carries
+# `Bearer <OE_EGRESS_PROXY_TOKEN>` and is decided against the app's host-plane allow list. A
+# request without it is a session request, decided against the session policy for its source
+# IP. Squid consumes the header here and does not forward it to the origin. No auth_param is
+# configured, so Squid never answers 407 and an uncredentialed request is not challenged.
+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
+acl oe_allowed external oe_egress
+
+# ── Standard safety ACLs ──
+acl CONNECT method CONNECT
+acl SSL_ports port 443
+acl Safe_ports port 80
+acl Safe_ports port 443
+
+http_access deny !Safe_ports
+http_access deny CONNECT !SSL_ports
+
+# ── The one allow rule: the control-service policy. Everything else is denied. ──
+http_access allow oe_allowed
+http_access deny all
+
+# Policy gateway, not a cache.
+cache deny all
+via off
+forwarded_for delete
+
+# Squid drops privileges to the `squid` user. It logs to the container's stdout/stderr
+# (below); the entrypoint chowns those pipes to `squid` so the non-root worker can open them
+# (Squid 7 FATALs on `cache_effective_user root`, so dropping privileges is mandatory).
+
+# Logs to the container's stdout/stderr for `docker logs`.
+logfile_rotate 0
+access_log stdio:/dev/stdout squid
+
+# ── THE DENIAL LOG (OPE-314) — the ONE file the app is allowed to read ────────────────────────
+# The app tails this to turn policy denials into `egress.denied` audit rows, which is what lets
+# the permission-homeostasis widening loop see this plane at all (before OPE-314 an individual
+# blocked request left no record anywhere — see packages/core/agent/access/egress-denial-log.ts).
+#
+# 🔴 THE MINIMISATION HAPPENS HERE, AT THE SOURCE, not only in the reader. The `squid` format
+# above carries the full request URL, and under Tier B (MITM) Squid has DECRYPTED the request, so
+# that URL includes the path AND the query string — the single most likely place for a token, an
+# object id or a person's email to be sitting. This format carries three fields and no more:
+#   %ts.%03tu   when         (unix seconds + ms)
+#   %Ss/%03>Hs  what Squid decided  (e.g. TCP_DENIED/403 — the reader keys on the `_DENIED` tag)
+#   %>rd        the DOMAIN   (request URL domain — no scheme, no port, no path, no query)
+# No client address, no method, no bytes, no user. The reader re-derives the host defensively
+# anyway (it must also cope with an operator pointing it at a conventional access.log), but this
+# line is why the bytes on the shared volume never contain a path in the first place.
+#
+# The `http_status 403` ACL is what narrows the file to refusals; a Squid ACL cannot match on %Ss.
+# That is imprecise in one direction only — under Tier B an ORIGIN's own 403 also lands here as
+# `TCP_MISS/403` — and the reader discards those, because only a `_DENIED` tag is OUR refusal.
+#
+# The directory is created by entrypoint.sh whether or not a volume is mounted over it, so Squid
+# can never FATAL on an unopenable access_log; unmounted, the file simply stays inside the
+# container and nothing reads it.
+logformat oe_deny %ts.%03tu %Ss/%03>Hs %>rd
+acl oe_deny_status http_status 403
+access_log stdio:/var/log/oe-egress/denied.log oe_deny oe_deny_status
+# cache_log (debug) also to stdout — the non-root `squid` user reliably reopens the chowned
+# /dev/stdout pipe; /dev/stderr is flakier under Docker, and interleaving both on stdout is
+# the conventional container pattern (`docker logs` captures it either way).
+cache_log stdio:/dev/stdout
+pid_filename /tmp/squid.pid
+
+# Tier B (MITM) directives, if enabled, are APPENDED to this file by entrypoint.sh when
+# OE_EGRESS_MITM=1 (not via an `include` glob — Squid 6.x treats a conf.d/*.conf glob that
+# matches zero files as a FATAL error, which is exactly the Tier A case).

package/template/deploy/egress-proxy/tier-b.conf

@@ -0,0 +1,42 @@
+# Open Everywhere egress proxy — TIER B (opt-in MITM) overlay.
+#
+# Dropped into /etc/squid/conf.d/ by entrypoint.sh ONLY when OE_EGRESS_MITM=1. It makes
+# Squid terminate TLS with the locally-generated CA (deploy/egress-proxy/ca, installed into
+# the sandbox/guest trust store by gen-ca.sh) so that:
+#   1. the decrypted request's method + path can be narrowed by the compiled policy, and
+#   2. a Tier B credential header (the git read-broker Authorization) can be injected at the
+#      firewall — full parity with Vercel's transform.headers, secret never in-sandbox.
+#
+# ⚠ CLIENT COMPAT (see README): MITM only works for clients that (a) honor the proxy env
+# (HTTPS_PROXY) and (b) trust the local CA. git/npm/curl do once the CA is installed and
+# their proxy env is set; some tools pin certificates or bypass the proxy — those break
+# under Tier B and must be allow-listed for Tier A splice instead.
+
+# Bump listener — the CA cert+key generated by gen-ca.sh.
+sslcrtd_program /usr/lib/squid/security_file_certgen -s /var/lib/squid/ssl_db -M 4MB
+tls_outgoing_options options=NO_SSLv3
+
+# Peek at the ClientHello (to read SNI for the ACL), then bump (decrypt) allowed hosts.
+acl step1 at_step SslBump1
+# THE HOST PLANE IS SPLICED AT STEP 1, never peeked or bumped (OPE-2406). The app's own model
+# call carries Proxy-Authorization on the CONNECT only. After a peek, Squid re-checks a fake
+# CONNECT built from the SNI, and a bumped inner request is a new request: neither carries the
+# header, so the control service would decide it against the SESSION policy and deny the model
+# call. `oe_proxy_cred` matches only a `Bearer <value>` header, and `oe_allowed` then passes only
+# the valid token to a host-plane host. A missing header, or a literal `-` (which the control
+# service reads as "no credential", the session shape), never matches, so a session request is
+# peeked and bumped as before and cannot dodge Tier B's method/path narrowing by this rule.
+acl oe_proxy_cred req_header Proxy-Authorization ^Bearer[[:space:]]+[^[:space:]]
+ssl_bump splice step1 oe_proxy_cred oe_allowed
+ssl_bump peek step1
+ssl_bump bump oe_allowed
+ssl_bump terminate all
+
+# Inject the Tier B credential header the helper returned as the `authz` annotation.
+# Only stamped when the ACL matched AND returned a header (the git read-broker path).
+# The helper's `OK authz="…"` becomes a transaction note read here as %note{authz}
+# (Squid 7 dropped %external_acl_message for request_header_add). The leading `'` is the
+# LOG_QUOTE_NONE modifier — WITHOUT it Squid URL-encodes the note, turning the mandatory
+# space in `Basic <base64>` / `Bearer <jwt>` into %20 and corrupting every real credential.
+acl oe_has_authz note authz
+request_header_add Authorization "%'note{authz}" oe_has_authz

package/template/docker-compose.yml

@@ -0,0 +1,135 @@
+# This app on the Docker route: the app, the egress proxy, Postgres and the Postgres WebSocket bridge.
+#
+# THE TOPOLOGY IS THE EGRESS BACKSTOP:
+#   - `oe-net-internal` is `internal: true`, so it has NO route to the internet. The app is ONLY on it.
+#   - `oe-egress-proxy` is on `oe-net-internal` AND `oe-net-wan`. It is the one container with a route
+#     out, and its default is deny. So the app reaches the internet only through the proxy, even
+#     when a policy push fails.
+#
+# Before the first start:
+#   1. `npm install` (the image builds from package-lock.json).
+#   2. Put the deployment's values in `.env` (AI_GATEWAY_API_KEY, SLACK_*, OE_CREDENTIAL_KEY, ...).
+#      It must hold OE_EGRESS_PROXY_TOKEN (`openssl rand -hex 32`): without it compose refuses to
+#      start the stack. Set POSTGRES_PASSWORD there too; the default below is for a local trial only.
+# Start: docker compose up --build
+#
+# The requirements this stack satisfies, and the ones it does not, are in the deployment contract:
+# https://github.com/open-everywhere/open-everywhere/blob/main/docs/deploy/contract.md
+# The egress proxy is documented in the self-host egress guide:
+# https://github.com/open-everywhere/open-everywhere/blob/main/docs/deploy/platforms/self-host-egress.md
+
+services:
+  oe-egress-proxy:
+    build:
+      context: ./deploy/egress-proxy
+    networks: [oe-net-internal, oe-net-wan]
+    environment:
+      OE_EGRESS_MITM: "${OE_EGRESS_MITM:-0}"          # 1 = Tier B (MITM); the default is Tier A
+      # The shared secret for POST/DELETE /policy. `:?` makes compose refuse to start the stack when
+      # it is unset or empty. Without it, any peer on oe-net-internal could install an allow-all policy.
+      OE_EGRESS_PROXY_TOKEN: "${OE_EGRESS_PROXY_TOKEN:?set OE_EGRESS_PROXY_TOKEN in .env — the egress control plane refuses to start without it (generate: openssl rand -hex 32)}"
+      OE_EGRESS_CONTROL_PORT: "8080"
+      OE_EGRESS_CA_DIR: "/opt/oe-egress/ca"
+    volumes:
+      - oe-ca:/opt/oe-egress/ca                        # the CA, shared with the app (Tier B trust)
+      - oe-egress-log:/var/log/oe-egress               # the denial log; the app reads it read-only
+    restart: unless-stopped
+    # No host port: the proxy is internal to the compose networks.
+
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    depends_on:
+      oe-egress-proxy:
+        condition: service_started
+      postgres:
+        condition: service_healthy
+      neon-wsproxy:
+        condition: service_started
+    networks: [oe-net-internal]                        # internal ONLY: no direct route out
+    env_file:
+      - .env
+    environment:
+      # VERCEL stays UNSET: the self-host sandbox backend and the self-host egress push.
+      NODE_USE_ENV_PROXY: "1"                          # Node 24: built-in fetch uses *_PROXY
+      HTTP_PROXY: "http://oe-egress-proxy:3128"
+      HTTPS_PROXY: "http://oe-egress-proxy:3128"
+      # The policy push and the Postgres WebSocket go direct. `neon-wsproxy` MUST be here: Node 24
+      # also sends the driver's WebSocket through HTTP_PROXY, the proxy denies it, and the app exits
+      # at boot.
+      NO_PROXY: "oe-egress-proxy,neon-wsproxy,localhost,127.0.0.1"
+      # The app declares `sandbox.selfHostBackend: "justbash"` (agent/settings/settings.ts). Its
+      # session egress leaves through this app process, so the proxy holds every session request to
+      # the session's allow list. justbash shares this process's filesystem: development-grade
+      # isolation. The app refuses to boot here on `"docker"`: eve starts docker session containers
+      # on the daemon's default network, outside this proxy.
+      OE_EGRESS_PROXY_URL: "http://oe-egress-proxy:8080"    # the control endpoint for the policy push
+      OE_EGRESS_PROXY_TOKEN: "${OE_EGRESS_PROXY_TOKEN:?set OE_EGRESS_PROXY_TOKEN in .env — the app's policy push is rejected without it (same value as the proxy)}"
+      # The proxy's denial log: a refused host becomes an `egress.denied` audit row. Unset it to turn
+      # the reader off.
+      OE_EGRESS_DENIAL_LOG: "${OE_EGRESS_DENIAL_LOG:-/var/log/oe-egress/denied.log}"
+      # Tier B: trust the MITM CA for git, npm and curl (no effect on Tier A).
+      NODE_EXTRA_CA_CERTS: "/opt/oe-egress/ca/oe-egress-ca.crt"
+      GIT_SSL_CAINFO: "/opt/oe-egress/ca/oe-egress-ca.crt"
+      # The operational store: the `postgres` sidecar below. This line wins over `.env`. For a
+      # managed Postgres, put its DATABASE_URL in .env, and delete this line, OE_NEON_WS_PROXY and
+      # the `postgres` and `neon-wsproxy` services.
+      DATABASE_URL: "postgres://openeverywhere:${POSTGRES_PASSWORD:-change-me-local-only}@postgres:5432/openeverywhere"
+      # The Postgres driver speaks WebSocket, not raw TCP, so it reaches the sidecar through
+      # `neon-wsproxy`. A hosted Neon database ignores this value.
+      OE_NEON_WS_PROXY: "${OE_NEON_WS_PROXY:-neon-wsproxy:80}"
+      PORT: "3000"
+    volumes:
+      - oe-memory:/app/.open-everywhere-memory         # the git or sqlite memory backing
+      - oe-workflow:/app/.workflow-data                # durable sessions
+      - oe-ca:/opt/oe-egress/ca:ro                     # the CA, for Tier B trust
+      - oe-egress-log:/var/log/oe-egress:ro            # the proxy's denial log (READ-ONLY)
+    # Put a TLS-terminating reverse proxy in front of the app, and forward BOTH /eve/ and
+    # /.well-known/workflow/. To reach it directly for a local test, publish the port:
+    # ports: ["3000:3000"]
+    restart: unless-stopped
+
+  postgres:
+    # The same major version as hosted Neon.
+    image: postgres:17-alpine
+    networks: [oe-net-internal]
+    environment:
+      POSTGRES_USER: openeverywhere
+      POSTGRES_PASSWORD: "${POSTGRES_PASSWORD:-change-me-local-only}"
+      POSTGRES_DB: openeverywhere
+    volumes:
+      - oe-pg:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U openeverywhere -d openeverywhere"]
+      interval: 5s
+      timeout: 3s
+      retries: 20
+    restart: unless-stopped
+
+  # Bridges the driver's WebSocket transport to the plain-TCP `postgres` sidecar.
+  neon-wsproxy:
+    image: ghcr.io/neondatabase/wsproxy:latest
+    networks: [oe-net-internal]
+    environment:
+      # EMPTY: the driver already sends `address=host:port`, and wsproxy appends this value to it.
+      APPEND_PORT: ""
+      ALLOW_ADDR_REGEX: "postgres:5432"                # forward to the sidecar only
+      LOG_TRAFFIC: "false"
+    depends_on:
+      postgres:
+        condition: service_healthy
+    restart: unless-stopped
+
+networks:
+  oe-net-internal:
+    internal: true      # the backstop: NO route to the internet
+  oe-net-wan:
+    driver: bridge
+
+volumes:
+  oe-memory:
+  oe-workflow:
+  oe-ca:
+  oe-egress-log:
+  oe-pg:

package/template/gitignore

@@ -42,5 +42,9 @@ node_modules/
 *.pem
 *.key
 
+# The egress proxy's MITM CA (Tier B). It lives in a Docker volume; a copy on disk is a real secret.
+deploy/egress-proxy/ca/
+deploy/egress-proxy/*.crt
+
 # A built Teams app package (`surface_app_package`): rebuilt from config, never committed.
 teams-app/*.zip