switchback — part of the aimock family private · pre-launch

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:

non-loopback bind warning stderr
[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.

auth object | null optional default: keyless

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.

auth.env string optional one of env / file

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.

auth.file string optional one of env / file

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.

allowCallerKeys boolean optional default: true

Whether a caller's own credential may pass through to this upstream. A sibling of auth, not a key inside it. See Caller keys.

forwardHeaders string[] optional default: none

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:

unset key variable, at load stderr
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.

what the router prints in each mode stderr
# 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.

validate, then run shell
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.

switchback.config.json json
{
  "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:

run it with the tightest posture shell
# 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.

  1. Each configured upstream's baseURL. Upstream URLs come only from static config, never from request content.
  2. The catalog refresh URL, and only when catalog.refresh is 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.
  3. The budget Redis backend, only when budget.backend.kind is redis, 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:

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.

No inbound authentication by design plan for it

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.

catalog.refresh cannot arm gated this build

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.

DNS-rebinding TOCTOU on the refresh URL accepted residual documented in-code

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.

The catalog replay high-water mark is in-memory accepted residual resets on restart

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.

--redact-env disables SIGHUP key rotation trade restart to rotate

Scrubbing the variables is what removes the re-read path. Pick the property you want per deployment; you cannot have both.

A group- or other-readable budget state file is refused feature will surprise you

Intentional, and it will still catch out anyone who reflexively chmod 644s the file backing the budget store.

No published disclosure channel pre-launch nothing to cite

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.