feat!: the membership token travels in x-httpeers-token, never Authorization

[mkotelnikov]

Why

LiteLLM's Playground, opened through the mesh (/peers/<hub>/llm/ui/), failed every call with 401 "malformed token". The Playground sends its key through the OpenAI SDK, which always puts it in Authorization: Bearer sk-…. The mesh token was in the same header, and the ServiceWorker edge never overwrites a page's Authorization. So no mesh token was attached, and withAccess tried to verify the LiteLLM key as a mesh token. LiteLLM never saw the request.

Authorization belongs to the application a request is addressed to. The mesh now uses its own header for its token.

What changes

• httpeers-core: adds MESH_TOKEN_HEADER = x-httpeers-token (the bare token, no Bearer prefix), setMeshToken / readMeshToken, and MESH_CREDENTIAL_HEADERS (the token header plus x-httpeers-peer), which lists the headers a request leaving the mesh must not carry.
• httpeers-access: withAccess reads only MESH_TOKEN_HEADER. A token sent in Authorization is treated as absent, and Authorization is left on the request for the handler.
• httpeers-member: peerRequest and the edge write the new header. The edge attaches the token whatever the page put in Authorization, and still never overwrites a mesh token the page set itself.
• httpeers-ghost: the pin writes the viewer's token to the new header.
• hub llm passthrough: strips MESH_CREDENTIAL_HEADERS. A Bearer value in Authorization moves to x-litellm-api-key (the header the appliance's LiteLLM reads) when that header is absent. Authorization never reaches LiteLLM.
• demos proxy page: its upstream strips MESH_CREDENTIAL_HEADERS. The builder moved to shared/proxy-upstream.ts so it can be tested.
• conformance: a source-scan test fails if any library reads or writes Authorization, or spells the header name outside httpeers-core.
• Docs: root README (a third "rule the packages are built on"), the core and access READMEs, docs/security-model.md, and the LiteLLM config comments.

All tests were written first and watched fail. tests/llm-mesh-credentials.test.ts reproduces the Playground request end to end through withAccess and the llm module.

Breaking: deploy the hub and the pages together

An old page sends its token in Authorization, and a new hub refuses it with 401 "membership token required". The reverse mismatch fails the same way. The hub and the static pages must be redeployed together.

Related

• statewalker/webrun-wire mesh-auth-header: urlUpstream stops dropping authorization. This PR does not depend on it: with the published webrun-http-proxy 0.1.0, the passthrough moves the key before the proxy drops authorization, and the mesh headers are stripped either way.
• statewalker/umbrella mesh-auth-header: dated amendments to the design specs.

Verification

A clean pnpm -r run build, test, typecheck and lint:check of the httpeers + webrun-wire assembly all pass, with the same skips as main. Not yet checked against the live server.

🤖 Generated with Claude Code