Governance gateway
apps/gateway is a Hono app on @hono/node-server that runs two listeners in one process, sharing in-memory state
(GatewayState: registrations, the subject-token cache, counters, the in-flight count):
| Listener | Default port | Bind | Routes | Credential |
|---|---|---|---|---|
| Data | GATEWAY_DATA_PORT = 8787 | GATEWAY_DATA_HOST (one explicit IP; image default 0.0.0.0) | POST /v1/messages, POST /mcp, GET /health | afj_ job token |
| Control | GATEWAY_CONTROL_PORT = 8788 | GATEWAY_CONTROL_HOST, or derived from GATEWAY_CONTROL_BIND_CIDR | POST /control/v1/subjects, POST /control/v1/jobs, DELETE /control/v1/jobs/:requestId, GET /control/v1/health | route-scoped control tokens |
The gateway is the only holder of the model key, the place where every model and MCP call is metered against the ledger,
and the enforcement point for the kill switch. The entry point is apps/gateway/src/server.ts: it loads config, builds a
pg.Pool (max: 10), wires PgLedgerStore, PgSettingsStore and PgAuditStore, and calls startGateway.
Startup and configuration
loadConfig (apps/gateway/src/config.ts) parses env with Zod (blank values count as unset), then loads the policy
directory and the MCP registry. Any error throws and the process exits 1 ("refuse to start, no partial policy or
registry").
Environment variables
| Variable | Default | Rule |
|---|---|---|
ANTHROPIC_API_KEY | none (required) | non-empty; the only copy of the key in the system |
UPSTREAM_BASE_URL | https://api.anthropic.com | must equal that value, except under the test flag |
GATEWAY_TEST_UPSTREAM | unset | 1 with NODE_ENV=test allows http://127.0.0.1:<port> upstream, IdP and registry endpoints |
DATABASE_URL | none (required) | |
GATEWAY_MODELS | none (required) | comma list, non-empty, subset of the priced models (claude-haiku-5-5, claude-sonnet-5-5) |
GATEWAY_MAX_TOKENS_CAP | 8192 | integer at least 1 |
GATEWAY_ALLOWED_BETAS | the 8 default betas | subset of KNOWN_BETAS |
GATEWAY_ALLOWED_FIELDS | the 13 default fields | subset of KNOWN_FIELDS |
GATEWAY_ALLOWED_QUERIES | empty | subset of KNOWN_QUERIES (beta=true) |
GATEWAY_MAX_BODY_BYTES | 8388608 (8 MiB) | |
GATEWAY_POLICY_DIR | required; image sets /policies | see Job tokens and policies |
GATEWAY_REGISTRY_DIR | required; image sets /registry | empty directory = empty registry |
GATEWAY_IDP_TOKEN_URL, GATEWAY_IDP_CLIENT_ID, GATEWAY_IDP_CLIENT_SECRET | unset | all three or none; URL must be https (loopback http only under the test flag); none = every exchange denied |
GATEWAY_MCP_TIMEOUT_MS | 60000 | 100 to 60000 |
GATEWAY_DATA_HOST | required; image sets 0.0.0.0 | one explicit IP (isIP) |
GATEWAY_DATA_PORT | 8787 | 0 to 65535 |
GATEWAY_CONTROL_HOST | required unless derived; no image default | one explicit IP; 0.0.0.0 and :: refused unless GATEWAY_CONTROL_BIND_ANY is set |
GATEWAY_CONTROL_BIND_ANY | unset | the only accepted value is private-network-only |
GATEWAY_CONTROL_BIND_CIDR | unset | IPv4 CIDR /8 to /32; see below |
GATEWAY_CONTROL_PORT | 8788 | must differ from the data port when binding all interfaces |
GATEWAY_CONTROL_TOKEN_API, GATEWAY_CONTROL_TOKEN_WORKER | required | at least 32 chars each; must differ |
GATEWAY_PREAUTH_PER_SEC | 20 | failed authentications per source address per second |
GATEWAY_JOB_CONCURRENCY | 4 | concurrent calls per job token |
GATEWAY_JOB_PER_MIN | 120 | requests per job token per minute |
GATEWAY_GLOBAL_CONCURRENCY | 32 | concurrent calls across all jobs |
GATEWAY_HEADER_TIMEOUT_MS | 10000 | headersTimeout |
GATEWAY_BODY_TIMEOUT_MS | 30000 | body read deadline; requestTimeout = header + body timeout |
GATEWAY_UPSTREAM_TIMEOUT_MS | 600000 | until upstream response headers |
GATEWAY_STREAM_IDLE_MS | 120000 | gap between SSE chunks |
GATEWAY_STREAM_TOTAL_MS | 900000 | whole stream |
GATEWAY_MAX_JOBS | 1000 | live registrations and pending subjects |
GATEWAY_CONTROL_PER_SEC | 60 | control calls per route token per second |
GATEWAY_SHUTDOWN_GRACE_MS | 10000 | drain time for in-flight calls |
GATEWAY_OVERHEAD_TOKENS | 2000 | added to the worst-case input bound |
SSRF and MITM hardening at startup
GatewayEnv.superRefine refuses:
NODE_TLS_REJECT_UNAUTHORIZED=0;NODE_USE_ENV_PROXY(any value);NODE_EXTRA_CA_CERTS,SSL_CERT_FILE,SSL_CERT_DIRunlessGATEWAY_ALLOW_EXTRA_CA=1;NODE_OPTIONSunlessGATEWAY_ALLOW_NODE_OPTIONS=1(it could add--use-openssl-ca,--require,--import).
The HTTP server uses Node's strict llhttp parser (insecureHTTPParser is never set), headersTimeout = GATEWAY_HEADER_TIMEOUT_MS, requestTimeout = header + body timeout, and checks connections every 1000 ms
(apps/gateway/src/serve.ts).
Control bind options
The control listener must never be reachable from a sandbox or from a shared network. Three mutually exclusive ways to set its address exist:
| Option | Setting | When it is safe | Status |
|---|---|---|---|
| Explicit IP | GATEWAY_CONTROL_HOST=<one IP> | the IP is on a network no untrusted process can reach | built |
| Bind any | GATEWAY_CONTROL_HOST=0.0.0.0 plus GATEWAY_CONTROL_BIND_ANY=private-network-only | only while the gateway is attached to the private encrypted overlay alone, never to a shared one | built; used at launch on the core host |
| CIDR (option A) | GATEWAY_CONTROL_BIND_CIDR=<private IPv4 CIDR> | the CIDR is the private overlay's pinned subnet | on main, not released or deployed (ADR 0008) |
controlHostFromCidr details: an IPv6 CIDR is refused with its own message; a malformed CIDR, a prefix shorter than
/8 or extra / parts are refused; host bits in the CIDR are ignored; network and broadcast addresses count as inside;
the same address on two interfaces counts as two matches. Error messages name the setting and the match count only,
never the CIDR or the local addresses. The derived address then passes every other rule (one explicit IP, differs
from GATEWAY_DATA_HOST).
Why it exists: publishing the data port in swarm ingress mode puts the whole gateway container on the shared ingress
overlay, so a control listener on 0.0.0.0 would be reachable from every other service publishing a port. Launch
therefore publishes no gateway port (ADR 0005) and fleet exec workers cannot reach the gateway until the CIDR bind is
released, the overlay subnet is pinned and the data port is published (design doc steps 2 to 5, still open).
UNVERIFIED: interface naming and ordering inside swarm tasks with several networks.
Data listener request path
The step order in apps/gateway/src/proxy.ts is part of the contract. Steps 0 and 1 touch no database and write no
audit row (a flood must not write); every deny after step 1 writes exactly one gateway_audit row.
Step 0: path, method, query
- The raw request target is checked before URL parsing (parsing would normalize
..and//).BAD_PATH=/%|\.\.|\/\/|\\/returns 403permission_error. - Any path starting with
/control/returns 404not_found_error: control routes do not exist on the data port. - Routes:
/v1/messagesPOST,/mcpPOST,/healthGET. Any other path is 403; a wrong method is 405invalid_request_error. - A query string must match one
GATEWAY_ALLOWED_QUERIESentry exactly (the CLI sendsbeta=true), else 403. /healthreturns{"status":"ok"}and nothing else.- While shutting down, every model and MCP call returns 503
api_error"shutting down".
Step 1: authentication
- Exactly one of
x-api-keyorauthorization(bearer scheme). Both present: 400auth_conflict. - The presented value is hashed with sha256 (constant work for every unknown token) and looked up only if it matches
JOB_TOKEN=^afj_[A-Za-z0-9_-]{43}$. No match: 401authentication_error"invalid job token". - Only failed authentications count in the per-source pre-auth window (
GATEWAY_PREAUTH_PER_SEC); over it, 429rate_limit_error. Authenticated traffic is limited per job instead, so a busy job never exhausts its source's bucket. - Pre-auth denials increment
state.preAuthDenials[reason]and log a warn sampled at most once per second.
Per-job limits
WindowLimiter (fixed window, at most 10 000 keys, oldest evicted) and Concurrency (per key plus one global pool) in
apps/gateway/src/limits.ts. Over the window or out of slots: 429 rate_limit_error with reason rate_limited or
busy, counted in state.limitDenials, no audit row. The MCP route has its own window and slots with the same
limits (GW29).
Steps 2 to 7: validation
| Step | Check | Status, error type | Audit reason |
|---|---|---|---|
| 2 | settings.isDisabled(); a read error counts as disabled | 503 api_error | disabled |
| 3 | content-type exactly application/json | 415 invalid_request_error | content_type_not_allowed |
| 3 | declared content-length or streamed bytes over GATEWAY_MAX_BODY_BYTES | 413 request_too_large | body_too_large |
| 3 | body not received within GATEWAY_BODY_TIMEOUT_MS | 408 invalid_request_error | client_aborted |
| 3 | body not valid UTF-8 (fatal decoder) | 400 | invalid_json |
| 4 | not JSON, not an object, or nesting overflows the stack | 400 | invalid_json |
| 4 | a top-level key outside GATEWAY_ALLOWED_FIELDS (own keys, so __proto__ counts); per-message output_config when the top-level field is not allowed | 403 permission_error | field_not_allowed |
| 6 | a tool with a type other than custom | 403 | tool_type_not_allowed |
| 4a | a schema issue under message content or system blocks | 403 | content_not_allowed |
| 4 | any other schema issue | 400 | invalid_json |
| 5 | model not in the job's grants or not in GATEWAY_MODELS | 403 | model_not_allowed |
| 5 | max_tokens missing, non-integer, below 1 or above min(grants.maxTokens, GATEWAY_MAX_TOKENS_CAP) | 403 | max_tokens_invalid |
| 5 | thinking.type = enabled with budget_tokens >= max_tokens | 403 | thinking_budget_invalid |
| 7 | anthropic-version missing or not YYYY-MM-DD | 400 | header_invalid |
| 7 | an anthropic-beta value outside GATEWAY_ALLOWED_BETAS | 403 | beta_not_allowed |
The audit target (model id) is recorded only once the model is allowlisted (finding 1).
Allowlists
| List | Values | Source |
|---|---|---|
| Default fields | model, messages, system, max_tokens, temperature, top_p, top_k, stop_sequences, stream, metadata, tools, tool_choice, thinking | DEFAULT_ALLOWED_FIELDS |
| Extra fields config may enable | context_management, output_config | KNOWN_FIELDS |
| Default betas (8) | claude-code-20250219, context-management-2025-06-27, effort-2025-11-24, interleaved-thinking-2025-05-14, mid-conversation-tool-changes-2026-07-01, per-turn-control-2026-07-01, thinking-display-updates-2026-08-18, thinking-token-count-2026-05-13 | DEFAULT_ALLOWED_BETAS |
| Extra betas config may enable | advisor-tool-2026-03-01, inline-tools-2026-09-15, structured-outputs-2025-12-15 | KNOWN_BETAS |
| Queries | beta=true | KNOWN_QUERIES |
| Image media types | image/jpeg, image/png, image/gif, image/webp (base64 source only) | IMAGE_MEDIA_TYPES |
| Content blocks | text, image, tool_use, tool_result (text and image only inside), thinking, redacted_thinking | messages.ts ContentBlock |
| Response headers forwarded | content-type, request-id, retry-after, anthropic-ratelimit-* | FORWARDED_RESPONSE_HEADERS |
The allowlists are frozen (ALLOWLISTS_FROZEN = true) for SDK 0.3.322 / CLI 2.1.322 (FROZEN_FOR_SDK); the guard
test SB-FRZ1 fails when the SDK pin moves. The flag is logged at start and does not change request handling. The
Console line-item comparison (F2) is UNVERIFIED. Every inbound header other than anthropic-version and allowed betas
is dropped; the recorded CLI header list is in the comment at the top of allowlists.ts.
Production note (app-03 smoke, docs/p2-findings.md): the CLI needs GATEWAY_ALLOWED_QUERIES=beta=true and
GATEWAY_ALLOWED_FIELDS including context_management and output_config; with the defaults it is denied before
auth reaches the model.
Step 8: worst-case debit
worst = worstUsd(model, inputUpperBound(req, canonical, GATEWAY_OVERHEAD_TOKENS), max_tokens). The input bound is the
byte length of the canonical body minus base64 image bytes, plus per image max(base64 length, IMAGE_MAX_TOKENS)
(IMAGE_MAX_TOKENS = 4784), plus the overhead. metering.debit(requestId, worst) is an atomic conditional debit
against the ledger row the worker admitted:
| Debit outcome | Response | Audit reason |
|---|---|---|
| throws | 503 api_error "ledger unavailable" | ledger_error |
insufficient | 429 rate_limit_error, header x-should-retry: false | budget_exhausted |
| row settled or gone | registration revoked, 401 authentication_error | registration_stale |
Steps 9 and 10: upstream call and response
- Constant URL
new URL('/v1/messages', UPSTREAM_BASE_URL), method POST, body = the canonical re-serialization, headerscontent-type,anthropic-version,x-api-key(the real key) andanthropic-beta(allowed values only),redirect: 'error'. - The abort signal combines client disconnect,
GATEWAY_UPSTREAM_TIMEOUT_MS, and the job being dropped (revoke, expiry, settled row):JobDroppedmaps to audit reasonrevoked. - A fetch failure is 504 (
upstream_timeout) or 502 (upstream_error), settled at the worst case. - A response content type other than
application/jsonortext/event-streamis 502upstream_bad_content_type. - JSON or a non-2xx response is buffered. A non-2xx status in
UNBILLED_UPSTREAM_STATUSES(400, 401, 402, 403, 404, 409, 413, 429, 500, 504, 529) settles at 0; any other non-2xx keeps the worst case. The unbilled list is "our reading" and UNVERIFIED until RK-G. - SSE passes through unchanged with a pull-based stream (
highWaterMark: 0, so backpressure holds).UsageTapreadsmessage_start.message.usageand the lastmessage_delta.usage; usage counts only aftermessage_stop, with noerrorevent and no line overSSE_LINE_CAP(1 MiB). Idle (GATEWAY_STREAM_IDLE_MS) and total (GATEWAY_STREAM_TOTAL_MS) timers abort; any abort cancels upstream, closes the client side and destroys the socket even when no read is pending (finding 2). - Every admitted call settles exactly once (
settledguard):settleCall(requestId, worst, actual), an info logmodel call settled, and oneallowaudit row withcostUsd, token counts and latency.
Unexpected throws become an Anthropic-shaped 500 api_error "internal error"; the log carries only the error name, no
body or secret (security review S1 finding 5). All error bodies use the shape
{"type":"error","error":{"type":…,"message":…}} (apps/gateway/src/errors.ts).
Control listener
All routes sit behind a 64 KiB bodyLimit (400 "body too large"). Tokens are compared as sha256 digests with
timingSafeEqual against both route tokens.
| Route | Accepted token | Success | Failure statuses |
|---|---|---|---|
POST /control/v1/subjects | api | 201 {expiresAt} | 400 invalid body; 401; 403 (worker token); 409 live subject for turnKey; 429; 503 overloaded_error busy |
POST /control/v1/jobs | api or worker | 201 {jobToken, hookTools, expiresAt} | 400 invalid body or policy compile failed; 401; 403 api-token restriction; 404 no ledger row; 409 conflict; 429; 503 ledger unavailable or busy |
DELETE /control/v1/jobs/:requestId | api (own registrations only) or worker (any) | 204 | 401; 404 no live registration; 429 |
GET /control/v1/health | worker | 200 {status, auditWriteFailures, preAuthDenials, limitDenials} | 401; 403 (api token); 429 |
Rate limiting: authenticated calls are limited per route token (GATEWAY_CONTROL_PER_SEC), failed authentications
per source address with the same limit. An unknown route returns 404, or 429 when the source is over its pre-auth
limit. The registration flow and the api-token restrictions are in
Job tokens and policies.
Audit
One gateway_audit row per decision (except pre-auth and per-job-limit denials). Columns: id, at, job_id,
request_id, subject_id, target, args_sha256, kind (model, tool, context, control), decision
(allow, deny), identity (obo, service, none), reason, http_status, input_tokens, output_tokens,
latency_ms, cost_usd. No prompts, bodies, tokens, headers or tool arguments; tool calls carry args_sha256 only.
CHECK constraints bound target to 256 chars and require reason except on allow rows of kind model or tool.
A failed audit write never fails the request: it is a warn plus auditWriteFailures on /control/v1/health ("audit is
evidence, the ledger the control"). Full column details are in Data model.
Shutdown
stop(signal) on SIGTERM or SIGINT: set stopping (new model and MCP calls get 503), wait up to
GATEWAY_SHUTDOWN_GRACE_MS for inflight to reach 0 (streams count until settled), close all connections on both
listeners, end the pool. Exit code 0 when drained, else 1. All registrations are in memory, so a restart invalidates
every live job token; callers re-register on their retry.
Image
apps/gateway/Dockerfile: node:24-bookworm-slim pinned by digest, tini as PID 1, user agentforge uid 10001,
/policies and /registry root-owned 0755 with the baked policies at mode 0444, env defaults
GATEWAY_DATA_HOST=0.0.0.0 GATEWAY_DATA_PORT=8787 GATEWAY_CONTROL_PORT=8788 GATEWAY_POLICY_DIR=/policies GATEWAY_REGISTRY_DIR=/registry, a healthcheck on GET /health of the data port, EXPOSE 8787 8788. There is no
default for GATEWAY_CONTROL_HOST.
Sources
apps/gateway/src/config.ts(GatewayEnv,controlHostFromCidr,loadConfig,isTestUpstream)apps/gateway/src/serve.ts(startGateway,listen),apps/gateway/src/server.ts,apps/gateway/src/app.tsapps/gateway/src/proxy.ts(dataApp,authenticate,UsageTap,SSE_LINE_CAP,ROUTES,BAD_PATH)apps/gateway/src/messages.ts(MessagesRequest,validate,inputUpperBound,IMAGE_MAX_TOKENS)apps/gateway/src/allowlists.ts,apps/gateway/src/limits.ts,apps/gateway/src/body.ts,apps/gateway/src/errors.tsapps/gateway/src/control.ts(controlApp),apps/gateway/src/registrations.tsapps/gateway/Dockerfile,packages/db/src/schema.ts(gatewayAudit),packages/agent-types/src/audit.tsdocs/design-gateway-fleet-exposure.md,docs/p2-findings.md("App-03 production deploy and smoke test")docs/sessions/2026-11-15-app03-deploy-and-smoke/adr/0005-gateway-publishes-no-port-at-launch.md,docs/sessions/2026-11-16-codecrucible-and-gateway-cidr/adr/0008-gateway-control-bind-cidr.md.omc/plans/p2g-governance-gateway.mdsections 6.1 to 6.5