Proxy (BFF)

Where the proxy listens. The WS-only startWsProxyServer listens on 4001 by default (hostname 0.0.0.0) when run separately.

Development mode — supplies the DEFAULT debug-logging flag for both the HTTP and WS handlers. Each of http/ws also accepts its own `debug` boolean (HttpProxyConfig.debug / WsProxyConfig.debug) that overrides this per-handler (debug: config.http.debug ?? dev); the flag gates info-level proxy logging.

HTTP forwarding config: an array of targets plus onRequest/onResponse/onError hooks for logging and metrics.

WebSocket forwarding config: targets, optional HMR allowance, unknown-path rejection, ping interval, plus onOpen(path, target) / onClose(path) / onError(error, path) lifecycle hooks for logging and metrics.

Bypasses the WS proxy for Next.js HMR sockets ('/_next/webpack-hmr'). Set false to route HMR paths through the proxy like any other target.

A WS handshake whose path matches no target is rejected with a 404. Set false to let unmatched paths fall through instead of being closed.

Keep-alive ping interval in ms for proxied WS connections. 0 (the default) disables the periodic ping; set a positive value to ping the socket on that interval.

Optional env file to load, plus onReady({ port, hostname }) fired when the server is listening. Note: ProxyServerConfig.onError is declared on the type but NOT wired — createProxyServer never calls it and Bun.serve is given no error handler; use the per-request http/ws onError hooks (HttpProxyConfig.onError / WsProxyConfig.onError) for error handling.

The upstream service this target forwards to.

Glob patterns that route to this target (e.g. '/auth/*', '/api/*'). First match wins.

Example: ["/auth/*", "/api/*"]

Rewrite matched paths before forwarding (e.g. strip a '/api' prefix the upstream doesn't expect).

Rewrite the Host header to the target's host (and, for WS, the Origin) — needed by many upstreams. Set false to DROP the Host override: the HTTP proxy deletes the Host header and lets the upstream fetch derive it from the target URL (the original client Host is not forwarded). For WS, changeOrigin=false leaves Host unset but still forwards the original Origin.

Static headers added to every forwarded request on this target.

HTTP-target only (not on WsProxyTarget). Upstream request timeout in ms; the proxy aborts to a 504 Gateway Timeout when exceeded. Any non-timeout upstream failure (connection refused, DNS error, etc.) instead returns 502 Bad Gateway with the underlying error message as its body; both branches also invoke HttpProxyConfig.onError with the resulting status (504 or 502).

HTTP-target only (not on WsProxyTarget). When true the proxy follows upstream 3xx redirects; false forwards them verbatim (redirect: 'manual').

Enforce nucleus claims on a non-nucleus upstream: serviceId, manifest { url, roleClaimsUrl (required when claimsMode='resolve'), token, refreshSec }, jwt { secret, cookieName, headerName }, claimsMode 'embed' (default) | 'resolve', and mode 'enforce' (default) | 'audit'. Also: onUnmapped 'allow' | 'deny' (default 'deny' — how to treat a request whose path matches no discovered endpoint), publicPaths (glob paths skipped by the claim gate), and godminRole (default 'godmin' — a bearer of this role bypasses the gate, including quotaSuppression). quotaSuppression.url is the opt-in ClaimGuard gate: the proxy fetches suppressed claims from that URL, subtracts them, and returns HTTP 429 with reason 'claim_guard' when a guard fires — and this 429 fires EVEN in audit mode (every other would-block only logs while auditing). See config.authorization.endpointDiscovery in the Authorization docs.

For a WebSocket target, validates the upstream TLS certificate on the proxy→backend connection. tokenRefresh on a WS target runs a PRE-handshake refresh (when enabled + a refresh cookie is present + the access cookie is missing/expiring).

The cookie to read the token from, with optional fallbackCookieNames for older names.

Where to put the token — this distinguishes the transport LEG, not the protocol. The browser can't set headers on a WS handshake, so a query param carries the token on the browser→proxy leg; a WS target may ALSO set headerName so the proxy forwards the token as a header on the proxy→backend leg. For HTTP, headerName (e.g. 'authorization') is used throughout.

HS256-verify the JWT in a cookie and forward its subject as x-user-id (or a custom header) — lets upstreams trust an identity without re-parsing tokens. HTTP targets only — injectUserIdFromJwt is a field on HttpProxyTarget and is read only in the HTTP handler; WsProxyTarget has no such field, so WS upstreams receive no x-user-id. The token is cryptographically verified with secret (falling back to authorize.jwt.secret); any inbound client-supplied header is stripped first, and with no verify secret the header is left unset (fail-closed), never trusting a raw sub.

Turn on silent refresh and point it at the IDP. Enabling it does TWO things. (1) A PROACTIVE pre-request refresh, gated on enabled alone (independent of retryOn401): when the request carries no access cookie but a refresh cookie IS present, the proxy refreshes BEFORE forwarding — and if that refresh fails it returns HTTP 401 'Token refresh failed. Please login again.' to the client WITHOUT ever contacting the upstream. This is the primary path for SSR requests that arrive without an access cookie. (2) The REACTIVE retry-on-401 governed by retryOn401 (below). WS targets run their own pre-handshake variant of the proactive path.

On a 401, refresh the token and replay the original request once (the body is buffered for the replay). maxRefreshRetries is declared on the type but currently unused — the reactive retry always runs at most once.

Which cookies hold the refresh and access tokens, so rotated values can be re-set after a refresh.

The IDP path (appended to idpBaseUrl) the proxy POSTs to when it needs a new token.

Aborts the refresh fetch after this many ms so a hung IDP can't stall the request.

Optional callbacks fired after a refresh completes — onRefreshSuccess(path) and onRefreshFailure(path, error) — for logging or metrics.