Security
The router holds every provider key you give it. This page says exactly how those keys are held, what can read them, which values are scrubbed at which sink, what crosses to an upstream, and which misconfigurations are refused at load rather than at 3am.
Start with what the router does not do
Read this first, because everything below assumes it. The router performs no authentication of its own. There is no API-key check on the way in, no allowlist of callers, no session. Anyone who can open a socket to the listening port can spend your provider keys and draw down your budget caps.
Danger
There is no inbound authentication. The deployment contract is a loopback sidecar, or a
private network behind ingress you control and authenticate yourself. The default bind
is 127.0.0.1; moving off loopback is a decision you make deliberately, and
it exposes a process that holds all of your provider credentials.
Process posture
| Behavior | What actually happens |
|---|---|
| Default bind | 127.0.0.1, unless you set a host yourself. |
| Non-loopback bind |
Honored, and warned about by name at startup. The check fires for any host that is
not 127.0.0.1, localhost or ::1, whether it
came from listen.host in the config or from --host.
|
| Unknown paths | A structured 404. Nothing unrecognized is proxied upstream. |
| Request body cap | 8 MiB, then 413. |
| Handler exception | A 500 with no stack in the response. If the head is already committed the socket is closed best-effort rather than left hanging. |
The exposure warning is verbatim, so you can grep for it in your logs:
[switchback] WARNING: frontend binding non-loopback host "<host>" — the router holds all
configured provider keys; exposing it on the network is a deliberate choice (§17.2).
Ensure upstream auth and network access are locked down.
Bind topology, replicas and shared state are covered on Deploy.
Keys are references, never literals
An upstream's auth is a reference to a credential, not the
credential. The config file is meant to be readable, diffable and committable; the secret
lives in your environment or in a mode-restricted file, and the loader enforces that.
Exactly one of env or file, or null. Omitting
it (or writing null) declares a deliberately keyless upstream: correct
for a local model server, wrong for anything that expects a key.
The name of an environment variable, read once at load. If the variable is unset or empty, startup fails and names the variable. That failure is the point: a silently keyless upstream would 401 on every request instead.
Path to a file containing the credential. The file must be mode 0400 or 0600; any other mode is a hard load error that states the actual octal mode it found. Relative paths resolve against the config file's directory, and contents are trimmed.
Whether a caller's own credential may pass through to this upstream. A
sibling of auth, not a key inside it. See Caller keys.
Extra caller headers this upstream is allowed to receive, matched case-insensitively. Naming a provider-auth header here is a hard load error.
A missing auth.env variable looks like this, and the router exits rather than
starting up in a state where every request fails:
upstream "stub": auth.env references environment variable "STUB_API_KEY" which is
unset or empty — a declared key must be present at load, otherwise the upstream is
silently keyless and every request 401s
Every other shape is refused at load
These refusals exist for one reason: to make it impossible to write a config that leaks a credential into a file, a log line, or an upstream that should never have seen it. Where the offending value looks like a credential, the error does not echo it.
| What you wrote | Result | Value echoed? |
|---|---|---|
| "auth": "<credential-shaped string>" | Load error saying it is an inline credential | Never |
| "auth": "<any other bare string>" | Load error: got a bare string |
No |
| auth with both env and file | Load error; only one is allowed | No |
| auth with neither | Load error | No |
| auth with any extra key | Load error naming the extra keys | No |
| auth.env whose name looks like a credential | Load error | No |
| baseURL with inline userinfo | Load error | Redacted |
| catalog.url with inline userinfo | Load error | Redacted |
| headers entry with a credential-shaped value | Load error | Redacted |
| forwardHeaders naming a provider-auth header | Load error | No |
| auth.file readable by group or other | Load error stating the actual octal mode | No |
Danger
auth.allowCallerKeys is not a real path. Nesting
allowCallerKeys inside auth hits the "unexpected key(s)"
refusal and the router will not start. That is the safe outcome, but it means a config
you believed was locked to the router's own key was never loaded at all. Write
"allowCallerKeys": false as a sibling of "auth".
How a credential shape is recognized
One shared matcher backs both the load-time guard and the runtime scrubber, so the two
cannot drift apart: what the config refuses is what the logs redact. It matches
Bearer/Basic/Key schemes with a token,
sk- keys, GitHub gh*_ tokens, Slack xox*- tokens,
Google ya29. and AIza keys, JWTs beginning eyJ, AWS
AKIA ids, xai- keys, and inline URL userinfo. On top of that,
the config guard adds a generic high-entropy fallback (24 characters or more containing a
digit and a lowercase letter, with no whitespace), so an un-prefixed token is caught too.
Ordinary UPPER_SNAKE variable names never match, which is why naming a
variable is always safe and pasting its value never is.
Per-upstream credential isolation
There is no shared key pool. Each upstream's credential is wrapped in an opaque handle that is bound to that upstream by name, and the value is not a field on the handle; it lives in a module-private weak map. Serializing, logging or inspecting a handle cannot produce the secret:
| Operation on the handle | What you get |
|---|---|
| toString() | [redacted] |
| toJSON() | { upstream, presence, mode, value: "[redacted]" } |
| Reading a property | There is no property holding the value. |
| revealAuthValue(material, upstream) | The only reader. It first asserts the handle is bound to that exact upstream. |
A mismatch throws an isolation error naming both upstreams and no key value. Crossing upstream A's key into a request for upstream B is refused structurally, not by convention. There is no code path that can carry it there, and a bug that tried would surface as a loud error rather than a leaked credential.
Each handle also records a mode: static-key for the dialects that carry a key
in a header, and signed for bedrock-converse, which does not
inject a header at all and is signed by the SigV4 adapter instead.
What crosses to an upstream
Header forwarding is an allowlist, and a short one. The caller's relationship is with the router, not with your provider account, so the router does not hand the caller's request headers onward by default.
| Caller header | Reaches the upstream? | Why |
|---|---|---|
| content-type | Yes | Base allowlist. |
| accept | Yes | Base allowlist. |
| Anything you list in forwardHeaders | Yes | Per-upstream opt-in, matched case-insensitively. Provider-auth header names are refused at load. |
| Client auth headers | No | Dropped, then governed by the caller-key policy below. |
| cookie | No | Not on the allowlist. |
| Tracing and correlation headers | No | Not on the allowlist. Add them explicitly if an upstream needs them. |
| Everything else | No | Allowlist, not denylist. |
Caller keys (BYO passthrough)
The router can either spend its own configured key or pass a caller's key through to the
provider. allowCallerKeys decides which, per upstream, and it
defaults to true.
| Upstream setting | What the caller sent | What the upstream receives |
|---|---|---|
| allowCallerKeys not false (default) | A real credential | The caller's credential, forwarded verbatim. |
| allowCallerKeys not false (default) | Nothing, or an sk-aimock- marked dummy | The upstream's configured key. |
| allowCallerKeys: false | Anything at all | The dialect's auth header is deleted outright from the forward set, then the configured key is injected. Unconditional. |
| dialect: bedrock-converse | Anything at all | No injection happens here; the SigV4 adapter signs the request instead. |
The deletion in the false row is the load-bearing part. It happens
before injection, so even if a forwardHeaders entry had smuggled the
caller's auth header into the forward set, it is gone before the request is built. That is
also why forwardHeaders may not name a provider-auth header in the first
place: two independent barriers against the same leak.
Warning
Because the default is true, an upstream you have not thought about will
forward a caller-supplied credential straight to the provider. If your callers should
never reach the provider under their own identity, or should never be able to bypass
your own key and its caps, set
"allowCallerKeys": false on every upstream, explicitly.
Redaction: one chokepoint, every sink
There is a single redaction module, and the rule is that everything which writes headers or bodies to any sink goes through it. That is what makes the guarantee checkable: you do not have to audit each writer, you have to audit one module and its callers.
| Sink | Redacted? | Detail worth knowing |
|---|---|---|
| Routing reports | Yes |
Redacted before the report enters the ring buffer, not on the way out of
/route/reports. A leak cannot sit in memory waiting to be served.
|
| The in-memory journal | Yes | Same chokepoint. The journal has no HTTP endpoint of its own. |
| Recorded fixtures | Yes | Shadow recordings are written through the same path. |
| stdout / stderr | Yes | The runtime logger is scrub-wrapped once when the runtime is assembled, so every line is scrubbed, including config values interpolated far downstream such as a refresh URL. |
| Client-facing error envelopes | Yes | Message and metadata, including in-stream error frames, because metadata routinely echoes the request's auth header. |
/budget response body |
Yes | Redacted on the way out. |
Header names that are always replaced
authorization, proxy-authorization, x-api-key,
x-goog-api-key, api-key, xi-api-key,
cookie, set-cookie. A coverage test asserts that this list
covers every provider-auth header name the router knows about, so adding a new auth scheme
without extending the list breaks the build rather than shipping a gap.
What redaction does to a value
Whole values become [redacted]. Credential shapes found
mid-string are collapsed in place, keeping the scheme word so the message still
reads: Bearer [redacted] rather than an opaque blank. Deep structures are
walked recursively and cycle-safely: a self-referential value is marked
[circular] instead of overflowing the stack and taking the sink down with it.
Canonical errors get their message, their raw payload and their metadata all covered.
Note
The redaction module supports an extra header denylist internally, but nothing in the config schema exposes it today. Treat the list above as the operator-visible set.
Two ways to keep keys out of everything else
--redact-env, and the trade it makes
With --redact-env, once the keys have been materialized into the isolated
store the referenced environment variables are
deleted from the process environment. Child processes and diagnostics can
no longer read them. Dispatch is unaffected, because the router reads from the bound
store, never from the environment. Only variable names are ever logged.
# default
[switchback] auth: default mode — keys held in memory; SIGHUP re-reads keys from env
# with --redact-env
[switchback] auth: redact-env mode — provider key vars scrubbed from process.env after load;
SIGHUP reloads non-secret config only (key rotation requires restart)
[switchback] redact-env: scrubbed 1 provider key var(s) from the environment after load
The trade is stated in that second line and it is a real one: with the variables gone there is nothing left to re-read, so SIGHUP key rotation becomes impossible and rotating a key means restarting the process.
On any reload, key material is carried forward only for auth references that did not change. Re-pointing a reference from one variable to another, changing a key file's path, or changing the auth kind each emit a loud warning and leave that upstream keyless until restart. The old key is deliberately not kept live under a config that names a different one. In default mode, SIGHUP re-reads keys from the environment and rebuilds the auth registry; a reload that throws is swallowed and the process keeps serving the last-good config. Signals and flags in full are on the CLI reference.
config check: validate without dispatching
Validates the config and that every referenced environment variable is present. It dispatches nothing, and it prints names only, never values, so it is safe to run in CI and safe to paste the output of.
node dist/switchback-cli.js config check --config switchback.config.json
One honest wrinkle: the loader hard-fails on the first unset variable, so you fix missing keys one at a time rather than getting the full list in a single pass.
A hardened upstream, end to end
Loopback bind, a key by reference, caller keys off, a minimal forward allowlist, and catalog refresh explicitly off.
{
"route": {
"listen": { "host": "127.0.0.1", "port": 4011 },
"upstreams": {
"openai-direct": {
"baseURL": "https://api.openai.com/v1",
"dialect": "openai-compat",
"profile": "openai",
"auth": { "env": "OPENAI_API_KEY" },
"allowCallerKeys": false,
"forwardHeaders": ["HTTP-Referer", "X-Title"]
}
},
"models": { "gpt-4o": { "openai-direct": "gpt-4o" } },
"routes": {
"chat-default": {
"match": {},
"chain": ["gpt-4o"],
"policy": { "advanceOn": ["rate_limited", "server_error"] }
}
},
"catalog": { "refresh": false }
}
}
Put the key in the environment however your secret store does it. The config only ever holds the variable's name, so it stays safe to commit:
# the value comes from your secret store; the config names the variable, never the key
export OPENAI_API_KEY="$(cat /run/secrets/openai_api_key)"
node dist/switchback-cli.js --config switchback.config.json --redact-env
Field-by-field semantics for everything in that file are on Configuration.
The complete outbound-connection list
Three things this process can dial. Not three categories — three things.
-
Each configured upstream's
baseURL. Upstream URLs come only from static config, never from request content. -
The catalog refresh URL, and only when
catalog.refreshis enabled together with a URL and an interval. The default is off, and the bundled price snapshot means the default configuration makes this connection zero times. -
The budget Redis backend, only when
budget.backend.kindisredis, at the URL you configure.
No telemetry and no phone-home: nothing else in the tree opens a socket.
The catalog-refresh guard
The refresh URL is the one URL in the config that gets fetched, so it is checked at config load before any timer arms, and again at fetch time:
-
only
httpandhttps; any other scheme is refused by name -
private, reserved, link-local and cloud-metadata addresses are rejected, overridable
only by setting
AIMOCK_ALLOW_PRIVATE_URLS=1 -
redirects are disabled outright; a 3xx is an error that names the
Locationit refused to follow - a response size cap, enforced incrementally, and a total fetch timeout
Catalog integrity, and why a price file is a security artifact
The price catalog decides what a request is estimated to cost, so a poisoned catalog is a
dollar-cap bypass. It is treated accordingly: the artifact carries a detached Ed25519
signature that is verified before parse against a pinned public key, and
a verification failure throws rather than partial-loading. A fetched catalog whose version
is older than or equal to the one in force is refused as a replay, with versions
compared segment-wise and numerically so 2026.7.9 sorts below
2026.7.10. Every refresh failure is fail-safe: the catalog already in force
stays in force, and a failure counter increments for you to alert on.
Warning
In this build, catalog.refresh exists but cannot arm. The
pinned verifying key is still the committed development fixture key, whose private half
is in the repository and is therefore forgeable, which would make signature verification
worthless exactly where it matters. The network refresh path refuses to start and logs
why. The bundled snapshot still verifies normally. Treat catalog refresh as present and
gated, not as a working feature.
Dependency surface
The router has exactly one runtime dependency, aimock, at a pinned
version. That is deliberate, and it has a cost worth naming: two components are
hand-rolled rather than taken from a library: the AWS SigV4 signer used by
bedrock-converse, and the minimal RESP2 client used by the Redis
budget backend. Both are small, both are ours, and both are code
you would otherwise be trusting someone else to have got right. Weigh that how you like;
we would rather you knew which trade we made.
The repository is private and nothing has been published from it, so there is no signed release artifact and no published container image to make claims about. Anything you read elsewhere about provenance-signed publishes or a hardened image describes an intention, not something that exists today.
Honest limits
Every item here is a real gap or a real trade, not a caveat for form's sake. If one of them matters to you, it matters now, not after you deploy.
Anyone who can reach the port can spend your keys and your budget. Loopback, or a private network behind your own authenticated ingress, is the deployment contract.
The pinned verifying key is the committed dev key, so the network path refuses to start and logs its reason. The bundled snapshot verifies and is used instead.
The host is validated, and then fetch resolves it again. Pinning the
checked address into the dial is out of scope, so a name that resolves differently
between the two steps is not caught.
After a restart it resets to the bundled snapshot's version, so a validly-signed catalog newer than the snapshot but older than one accepted in a previous run can be accepted again.
Scrubbing the variables is what removes the re-read path. Pick the property you want per deployment; you cannot have both.
Intentional, and it will still catch out anyone who reflexively
chmod 644s the file backing the budget store.
The repository carries no SECURITY.md, and this page deliberately
publishes no reporting address and no response-time commitment. Any address or
timeline you find in older drafts is unsourced. Do not rely on it.