Skip to main content

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):

ListenerDefault portBindRoutesCredential
DataGATEWAY_DATA_PORT = 8787GATEWAY_DATA_HOST (one explicit IP; image default 0.0.0.0)POST /v1/messages, POST /mcp, GET /healthafj_ job token
ControlGATEWAY_CONTROL_PORT = 8788GATEWAY_CONTROL_HOST, or derived from GATEWAY_CONTROL_BIND_CIDRPOST /control/v1/subjects, POST /control/v1/jobs, DELETE /control/v1/jobs/:requestId, GET /control/v1/healthroute-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​

VariableDefaultRule
ANTHROPIC_API_KEYnone (required)non-empty; the only copy of the key in the system
UPSTREAM_BASE_URLhttps://api.anthropic.commust equal that value, except under the test flag
GATEWAY_TEST_UPSTREAMunset1 with NODE_ENV=test allows http://127.0.0.1:<port> upstream, IdP and registry endpoints
DATABASE_URLnone (required)
GATEWAY_MODELSnone (required)comma list, non-empty, subset of the priced models (claude-haiku-5-5, claude-sonnet-5-5)
GATEWAY_MAX_TOKENS_CAP8192integer at least 1
GATEWAY_ALLOWED_BETASthe 8 default betassubset of KNOWN_BETAS
GATEWAY_ALLOWED_FIELDSthe 13 default fieldssubset of KNOWN_FIELDS
GATEWAY_ALLOWED_QUERIESemptysubset of KNOWN_QUERIES (beta=true)
GATEWAY_MAX_BODY_BYTES8388608 (8 MiB)
GATEWAY_POLICY_DIRrequired; image sets /policiessee Job tokens and policies
GATEWAY_REGISTRY_DIRrequired; image sets /registryempty directory = empty registry
GATEWAY_IDP_TOKEN_URL, GATEWAY_IDP_CLIENT_ID, GATEWAY_IDP_CLIENT_SECRETunsetall three or none; URL must be https (loopback http only under the test flag); none = every exchange denied
GATEWAY_MCP_TIMEOUT_MS60000100 to 60000
GATEWAY_DATA_HOSTrequired; image sets 0.0.0.0one explicit IP (isIP)
GATEWAY_DATA_PORT87870 to 65535
GATEWAY_CONTROL_HOSTrequired unless derived; no image defaultone explicit IP; 0.0.0.0 and :: refused unless GATEWAY_CONTROL_BIND_ANY is set
GATEWAY_CONTROL_BIND_ANYunsetthe only accepted value is private-network-only
GATEWAY_CONTROL_BIND_CIDRunsetIPv4 CIDR /8 to /32; see below
GATEWAY_CONTROL_PORT8788must differ from the data port when binding all interfaces
GATEWAY_CONTROL_TOKEN_API, GATEWAY_CONTROL_TOKEN_WORKERrequiredat least 32 chars each; must differ
GATEWAY_PREAUTH_PER_SEC20failed authentications per source address per second
GATEWAY_JOB_CONCURRENCY4concurrent calls per job token
GATEWAY_JOB_PER_MIN120requests per job token per minute
GATEWAY_GLOBAL_CONCURRENCY32concurrent calls across all jobs
GATEWAY_HEADER_TIMEOUT_MS10000headersTimeout
GATEWAY_BODY_TIMEOUT_MS30000body read deadline; requestTimeout = header + body timeout
GATEWAY_UPSTREAM_TIMEOUT_MS600000until upstream response headers
GATEWAY_STREAM_IDLE_MS120000gap between SSE chunks
GATEWAY_STREAM_TOTAL_MS900000whole stream
GATEWAY_MAX_JOBS1000live registrations and pending subjects
GATEWAY_CONTROL_PER_SEC60control calls per route token per second
GATEWAY_SHUTDOWN_GRACE_MS10000drain time for in-flight calls
GATEWAY_OVERHEAD_TOKENS2000added 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_DIR unless GATEWAY_ALLOW_EXTRA_CA=1;
  • NODE_OPTIONS unless GATEWAY_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:

OptionSettingWhen it is safeStatus
Explicit IPGATEWAY_CONTROL_HOST=<one IP>the IP is on a network no untrusted process can reachbuilt
Bind anyGATEWAY_CONTROL_HOST=0.0.0.0 plus GATEWAY_CONTROL_BIND_ANY=private-network-onlyonly while the gateway is attached to the private encrypted overlay alone, never to a shared onebuilt; 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 subneton 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 403 permission_error.
  • Any path starting with /control/ returns 404 not_found_error: control routes do not exist on the data port.
  • Routes: /v1/messages POST, /mcp POST, /health GET. Any other path is 403; a wrong method is 405 invalid_request_error.
  • A query string must match one GATEWAY_ALLOWED_QUERIES entry exactly (the CLI sends beta=true), else 403.
  • /health returns {"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-key or authorization (bearer scheme). Both present: 400 auth_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: 401 authentication_error "invalid job token".
  • Only failed authentications count in the per-source pre-auth window (GATEWAY_PREAUTH_PER_SEC); over it, 429 rate_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​

StepCheckStatus, error typeAudit reason
2settings.isDisabled(); a read error counts as disabled503 api_errordisabled
3content-type exactly application/json415 invalid_request_errorcontent_type_not_allowed
3declared content-length or streamed bytes over GATEWAY_MAX_BODY_BYTES413 request_too_largebody_too_large
3body not received within GATEWAY_BODY_TIMEOUT_MS408 invalid_request_errorclient_aborted
3body not valid UTF-8 (fatal decoder)400invalid_json
4not JSON, not an object, or nesting overflows the stack400invalid_json
4a top-level key outside GATEWAY_ALLOWED_FIELDS (own keys, so __proto__ counts); per-message output_config when the top-level field is not allowed403 permission_errorfield_not_allowed
6a tool with a type other than custom403tool_type_not_allowed
4aa schema issue under message content or system blocks403content_not_allowed
4any other schema issue400invalid_json
5model not in the job's grants or not in GATEWAY_MODELS403model_not_allowed
5max_tokens missing, non-integer, below 1 or above min(grants.maxTokens, GATEWAY_MAX_TOKENS_CAP)403max_tokens_invalid
5thinking.type = enabled with budget_tokens >= max_tokens403thinking_budget_invalid
7anthropic-version missing or not YYYY-MM-DD400header_invalid
7an anthropic-beta value outside GATEWAY_ALLOWED_BETAS403beta_not_allowed

The audit target (model id) is recorded only once the model is allowlisted (finding 1).

Allowlists​

ListValuesSource
Default fieldsmodel, messages, system, max_tokens, temperature, top_p, top_k, stop_sequences, stream, metadata, tools, tool_choice, thinkingDEFAULT_ALLOWED_FIELDS
Extra fields config may enablecontext_management, output_configKNOWN_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-13DEFAULT_ALLOWED_BETAS
Extra betas config may enableadvisor-tool-2026-03-01, inline-tools-2026-09-15, structured-outputs-2025-12-15KNOWN_BETAS
Queriesbeta=trueKNOWN_QUERIES
Image media typesimage/jpeg, image/png, image/gif, image/webp (base64 source only)IMAGE_MEDIA_TYPES
Content blockstext, image, tool_use, tool_result (text and image only inside), thinking, redacted_thinkingmessages.ts ContentBlock
Response headers forwardedcontent-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 outcomeResponseAudit reason
throws503 api_error "ledger unavailable"ledger_error
insufficient429 rate_limit_error, header x-should-retry: falsebudget_exhausted
row settled or goneregistration revoked, 401 authentication_errorregistration_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, headers content-type, anthropic-version, x-api-key (the real key) and anthropic-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): JobDropped maps to audit reason revoked.
  • A fetch failure is 504 (upstream_timeout) or 502 (upstream_error), settled at the worst case.
  • A response content type other than application/json or text/event-stream is 502 upstream_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). UsageTap reads message_start.message.usage and the last message_delta.usage; usage counts only after message_stop, with no error event and no line over SSE_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 (settled guard): settleCall(requestId, worst, actual), an info log model call settled, and one allow audit row with costUsd, 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.

RouteAccepted tokenSuccessFailure statuses
POST /control/v1/subjectsapi201 {expiresAt}400 invalid body; 401; 403 (worker token); 409 live subject for turnKey; 429; 503 overloaded_error busy
POST /control/v1/jobsapi or worker201 {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/:requestIdapi (own registrations only) or worker (any)204401; 404 no live registration; 429
GET /control/v1/healthworker200 {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.ts
  • apps/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.ts
  • apps/gateway/src/control.ts (controlApp), apps/gateway/src/registrations.ts
  • apps/gateway/Dockerfile, packages/db/src/schema.ts (gatewayAudit), packages/agent-types/src/audit.ts
  • docs/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.md sections 6.1 to 6.5