@open-everywhere/create 0.7.0 → 0.8.1

package/template/claude/skills/quickstart-open-everywhere/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: quickstart-open-everywhere
-description: Set up, configure or deploy an Open Everywhere app — from a fresh scaffold to an agent that answers in Slack. Use when the user wants to set up Open Everywhere, deploy it, or connect Slack, Notion or GitHub. Two routes are supported, Vercel and Docker, and step 1 is to ask which. Drives the open-everywhere-ops MCP server (preflight, surface_manifest, scaffold_env, scaffold_credential_key, secret_set/list/rm) and the `@open-everywhere/create --check --json` status report.
+description: Set up, configure or deploy an Open Everywhere app — from a fresh scaffold to an agent that answers in Slack. Use when the user wants to set up Open Everywhere, deploy it, or connect Slack, Notion or GitHub. Two routes are supported, Vercel and Docker, and step 1 is to ask which. Drives the open-everywhere-ops MCP server (preflight, surface_manifest, surface_app_create, scaffold_env, scaffold_credential_key, secret_set/list/rm, sovereignty), the `@open-everywhere/create --check --json` status report and the `npm run check:model-config` model check.
 ---
 
 # Quickstart Open Everywhere
@@ -79,6 +79,10 @@ To turn it off, `OE_TELEMETRY=off` (or `DO_NOT_TRACK=1`) must be set on the DEPL
 `printf off | npx vercel env add OE_TELEMETRY production`. On the Docker route, put it in the
 container's environment. Every boot prints a line that says whether telemetry is on.
 
+eve's own CLI telemetry is separate: Open Everywhere sets `EVE_TELEMETRY_DISABLED=1` where it
+starts eve (its npm scripts and `Dockerfile`), and `OE_TELEMETRY` does not change it. For an `eve`
+command run by hand, or an app scaffolded before 0.8.0, read the eve section of the page above.
+
 ## Status, at every step
 
 - `npx @open-everywhere/create --check --json` — the step list as data: `satisfied`, `detail`, and a
@@ -92,6 +96,56 @@ Re-run both after each step. They are the only answer to "what is left to do": t
 tool. The same step list, written for a human, is
 `https://github.com/open-everywhere/open-everywhere/blob/main/docs/deploy/setup-steps.md`.
 
+## Check the model config, after every model setting
+
+Run `npm run check:model-config` after the model settings are written, and before the deploy that
+carries them. The Vercel route runs it at its build step, and the Docker route at its model route
+step. Run it again after each change to `models` in `agent/settings/settings.ts` (`dataPolicy`,
+`targets`, `force`), to the stack in `agent/model/stacks.ts`, or to a model route of a domain or a
+role. The command is the same in both homes. For each model, it reads the public list of endpoints
+from the model's target: the AI Gateway, unless `models.targets` names another URL. So it needs the
+network and no credential. It changes nothing.
+
+Read the result to the user in plain words:
+
+- **Exit 0, no `✗` line and no `?` line.** Each model the app can use has a provider that meets
+  every demand. Go on.
+- **A `?` line that says "did not answer", "answered HTTP" or "not in the expected shape".** The
+  check did not run for that model. This is not a green. Fix the network, then run it again. A
+  target URL that "does not serve the endpoints read" (a relay) cannot be checked here: say so.
+- **A `?` line that says a `providers.only` name "serves none of the checked models".** The name is
+  most likely a typo. Show it to the user.
+- **A `?` line that says "does not say whether".** The gateway does not publish that fact, so the
+  demand is unknown. Name the model and the demand to the user, then go on.
+- **Exit 1, a `✗` line.** Each line names one demand and one model. Read it to the user:
+  - `region eu: no provider for deepseek/deepseek-v4.1-flash` (or `zeroRetention`, `noTraining`,
+    `providers.only`): no provider meets the demand. Under it every call of that model fails
+    closed: the call errors, and it never goes to a provider outside the demand. The choices are a
+    stack whose models meet the demand, a wider `providers.only` list, or fewer rows in
+    `models.dataPolicy` or in the target's own `dataPolicy`.
+  - `models.dataPolicy and target <name> name two different regions`: no call can meet both.
+    Keep one region.
+  - `the gateway does not know this model`: correct the model id in the stack or the route.
+  - `models.targets names no such target`: add the target to `models.targets`, or correct the
+    `via` name.
+
+  **Do not deploy on this red.** Let the user pick the fix, then run the check again. One role
+  differs: transcription tries the fallback route that `agent/model/stacks.ts` names when the
+  primary route fails. So a red on the primary transcription model sends the audio to the fallback
+  route. Check that route too.
+
+After the deploy, `--check --host` reads the same check in the `model-route` row of the status
+route. That row names no model, so on a `no` there, run `npm run check:model-config` for the names.
+An app scaffolded before 0.8.0 has no `check:model-config` script: its upgrade notes say how to add it.
+
+## Tell the user where their data lives
+
+Before the first deploy, offer the data map once: `npx oe sovereignty --host vercel` (or
+`--host docker`), or the `sovereignty` ops tool. For each piece of data it says where it lives,
+which region, and which company could be compelled to hand it over. It reads the app's own config
+and changes nothing. Give the user the short version. Run it again after a change to the model
+settings or the store.
+
 ## The Vercel route
 
 1. **Install.** If `node_modules` is missing: `npm install`. Its `postinstall` runs `oe-eve-patch`,
@@ -132,7 +186,8 @@ tool. The same step list, written for a human, is
    `agent/memory/config/domains/org.ts` set `admins: ["slack/<team-id>/<member-id>"]`. Offer to
    commit both edits. They take effect on the next deploy, so make them before it.
    Then OFFER the optional window step below. Do not make it for the user unasked.
-8. **Build.** `npm run build`. It must pass.
+8. **Build.** `npm run build`. It must pass. Then `npm run check:model-config`, and read it as
+   "Check the model config" above says. A `✗` line stops the route here.
 9. **Deployment env.** `.env.local` never ships, so the deployment reads only what you set ON it.
    The names are `OE_CREDENTIAL_ENCRYPTION_KEY`, `SLACK_BOT_TOKEN` and `SLACK_SIGNING_SECRET`. The
    Neon integration already set `DATABASE_URL` there, and that one value resolves both stores — so
@@ -170,20 +225,28 @@ Then:
 1. **Install and build.** `npm install`, then `npm run build`.
 2. **Postgres.** Provision one the container can reach. The user runs `npx oe env set DATABASE_URL`
    and pastes its connection string at the prompt. That one value resolves both stores to postgres;
-   set no provider selector.
+   set no provider selector. The compose stack of step 6 also carries a Postgres of its own.
 3. **Key.** `scaffold_credential_key`.
 4. **Model route.** There is no OIDC off Vercel, so the user supplies `AI_GATEWAY_API_KEY` (Vercel
    → AI Gateway → API Keys issues one for any host) with `npx oe env set AI_GATEWAY_API_KEY`. Running a different model backend instead is
    an **adapter swap in app code**
    (`https://github.com/open-everywhere/open-everywhere/blob/main/docs/extending/adapter-model.md`),
    which `--check` cannot see: that step stays `missing` on the Docker route either way, so read it
-   and move on rather than chasing a green it cannot give.
+   and move on rather than chasing a green it cannot give. On the gateway, run
+   `npm run check:model-config` once the model settings are written, and read it as "Check the
+   model config" above says. A `✗` line stops the route here.
 5. **Slack app.** Exactly as steps 5–7 of the Vercel route.
-6. **Run it.** Build the image and run it on the server, with the contract's environment set and a
-   public HTTPS URL in front. The Open Everywhere repository's own `Dockerfile` and
-   `docker-compose.yml` are the starting point
-   (`https://github.com/open-everywhere/open-everywhere`); a scaffolded app ships neither, so copy
-   them from there.
+6. **Run it.** The app ships its own `Dockerfile` and `docker-compose.yml`: the image, the egress
+   proxy (`deploy/egress-proxy/`), Postgres and its WebSocket bridge. On the server, the user puts
+   the contract's environment in `.env`, with `OE_EGRESS_PROXY_TOKEN` (`openssl rand -hex 32`) and
+   a `POSTGRES_PASSWORD`, then runs `docker compose up --build`. The compose file sets
+   `DATABASE_URL` to its own `postgres` service. For the managed Postgres of step 2 instead, put
+   its `DATABASE_URL` in `.env`, then delete the app's `DATABASE_URL` and `OE_NEON_WS_PROXY` lines
+   and the `postgres` and `neon-wsproxy` services from the compose file. Put a TLS-terminating
+   reverse proxy in front that forwards `/eve/` and `/.well-known/workflow/`.
+   Tell the user plainly: this stack runs the `justbash` sandbox backend, so the agent's shell
+   shares the app process's filesystem and environment, every `.env` value included. That is
+   development grade, and it does not meet the contract's `sandbox-backend` requirement.
 7. **Prove it, then the Slack URLs and the hello.** As steps 11–13 of the Vercel route, with
    `--route docker --host https://<host>`.
 
@@ -233,6 +296,30 @@ person in chat cannot add one.
 With no server declared, nothing changes: the build writes no connection for one, and only the
 shipped connections (Notion) stay mounted.
 
+## Optional: connect GitHub
+
+Offer this step after the first deploy, when the user wants the agent to work in GitHub. The
+GitHub App is one click: the ops server generates its manifest, and GitHub hands the App's keys
+back to a page on this computer, so the user copies nothing.
+
+1. Call `surface_app_create { surface: "github", baseUrl: "https://<host>" }`. Pass
+   `owner: "<org login>"` to create the App under an organization. The default App also answers
+   @mentions on issues and pull requests; `variant: "source-control"` creates one for checkout,
+   pull requests and ticket actions only.
+2. Give the user the `openUrl` from the reply. It is a local page: they open it in a browser on
+   this computer. GitHub opens with the App filled in. They check the name (GitHub App names are
+   unique, so they change it if GitHub says it is taken) and confirm.
+3. Call `surface_app_create { surface: "github", action: "status" }`. `state: "done"` lists the
+   env names written to `.env.local` and the App's install link. Keep the link for step 5.
+4. On the Vercel route, push each name in `written` exactly as in step 9, then redeploy. On the
+   Docker route, add each one to the server's `.env` (Docker step 6), then restart the stack.
+5. Only after that redeploy or restart, ask the user to open the install link and install the App
+   on the repositories the agent works in. The install sends one `installation` delivery, and the
+   deployment learns the installation from it. Before the redeploy the deployment does not hold the
+   App's webhook secret, so it refuses that delivery and never learns the installation.
+
+The tool never returns a value, and it refuses to overwrite names `.env.local` already holds.
+
 ## Develop locally
 
 Only when the user asks to change or debug the agent — never as a setup step. The user creates

package/template/claude/skills/upgrade-open-everywhere/SKILL.md

@@ -55,13 +55,19 @@ nothing. Each entry names:
 | CONFIG | a change to this app's own config files. A codemod applies some; the rest are yours. |
 | ENV + / ENV - | an env NAME the deployment starts or stops needing. The admin sets the value. |
 | MANUAL | a step outside the files — a dashboard change, a URL to re-paste, a key to rotate. |
+| DEFAULT | behaviour the release turns on with no config change. It applies at the next deploy. The line says which setting turns it off, if one does. |
 
 The installed copy of the record cannot know about a release published after it, so `--plan`
 says plainly which crossed versions it has no entry for. The full window is printed again in
 step 3, after the install puts the target's own copy on disk. The same text is in
 `node_modules/@open-everywhere/core/UPGRADING.md`.
 
-**Stop and ask the user** when the window holds a breaking change, an env change or a manual step.
+The installed core prints no DEFAULT line for the target. To see the target's new defaults before
+the install, run the target's own `oe`:
+`npx -p @open-everywhere/core@<target> oe upgrade --plan --to <target>`.
+
+**Stop and ask the user** when the window holds a breaking change, an env change, a manual step or
+a new default.
 Those are decisions, not steps.
 
 `--plan` also prints a **template drift** report. It compares every file the scaffold copied into
@@ -116,7 +122,12 @@ In order, and it stops at the first step that fails:
 4. run the config codemods the target's notes name, and print the migrations that are yours;
 5. `oe build --accept` — this rewrites `roster.lock.json`;
 6. `npm run typecheck`;
-7. `npm run build`.
+7. `npm run build`. eve prepares the sandbox template at build time. Off Vercel an app whose
+   `sandbox.selfHostBackend` is `docker` needs a running Docker daemon for that (this template
+   declares `justbash`, which needs nothing). When the build fails, `docker version` does not
+   answer, and the app's `build` script ends in `eve build`, a core at 0.8.0 or later builds
+   again with `npm run build -- --skip-sandbox-prewarm` and says so in one line. eve says that output may not be deployable, so do not start or deploy
+   it. A Vercel deploy builds again on Vercel.
 
 A failed step prints which one and leaves the tree where it stopped. Fix the cause and run
 `oe upgrade` again: it RESUMES, from whichever step stopped it.
@@ -158,7 +169,8 @@ thing the agent can do. If a line surprises you, say so to the user before the p
 is the review surface, and it is the only one.
 
 Then run the app's own checks once more if anything above was fixed by hand:
-`npm run typecheck && npm run build`.
+`npm run typecheck && npm run build`. If the build stops because no Docker daemon runs, add
+`-- --skip-sandbox-prewarm` to the build, as `oe upgrade` does, and do not deploy that output.
 
 Then act on the template drift report. A core that carries it prints it again after the install;
 if this run printed no "Template drift" heading, run `npx oe upgrade --to <target> --plan` now to get it. For
@@ -185,6 +197,7 @@ Commit on a branch, never on the default branch. The body carries:
 - what changed in `roster.lock.json`, in your own words;
 - **the env names the deployment needs before this merges**, names only;
 - the manual steps, and who does each one.
+- each new default, and the setting the user chose for it, or that no setting turns it off.
 - the template files you synced or deleted, and each SYNC or DELETE line you left as it is, with the reason.
 
 Then stop. The admin reviews the lock diff and merges. The merge deploys.

package/template/deploy/egress-proxy/Dockerfile

@@ -0,0 +1,30 @@
+# Open Everywhere egress proxy — Squid (Tier A/B) + the Node policy control service.
+# The SOLE container with a WAN route in docker-compose.yml; the app reaches the internet
+# only by proxying through here. See deploy/egress-proxy/README.md.
+#
+# Base on node:24-alpine (NOT plain alpine, whose `nodejs` package is too old for
+# `--experimental-strip-types`). Node 24 runs the TypeScript control service directly via
+# native type stripping — no build step. node:24-alpine puts node at /usr/local/bin; the
+# squid external_acl helper references /usr/bin/node, so we symlink it below.
+FROM node:24-alpine
+
+# squid = the forward proxy + ssl_bump; openssl = CA generation for Tier B; wget = the
+# entrypoint health probe. (nodejs comes from the base image.)
+RUN apk add --no-cache squid openssl wget ca-certificates \
+  && ln -sf "$(command -v node)" /usr/bin/node \
+  && mkdir -p /opt/oe-egress/control /var/lib/squid /opt/oe-egress/ca
+
+WORKDIR /opt/oe-egress
+
+# Config + scripts + control service (kept alongside so the entrypoint copies a writable
+# squid.conf and can drop the Tier B overlay in conditionally).
+COPY squid.conf tier-b.conf gen-ca.sh install-ca.sh entrypoint.sh ./
+COPY control/ ./control/
+RUN chmod +x gen-ca.sh install-ca.sh entrypoint.sh
+
+# 3128 = the forward proxy the app points HTTPS_PROXY at. The control service (8080) is
+# reachable on the internal network so the app can POST policy; the ACL helper hits it on
+# loopback. Not exposed to the host.
+EXPOSE 3128 8080
+
+ENTRYPOINT ["/bin/sh", "/opt/oe-egress/entrypoint.sh"]

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