Repository navigation
fix(proxy): restrict /proxy/* to signed peers and a read-only endpoint allowlist - #309
Merged
Merged
Conversation
benders
marked this pull request as ready for review
November 12, 2026 01:01
…st (#308) /proxy/* exists so peer hubs can read library metadata and cover art from the local Navidrome. Narrow it to that job: - proxy/auth.ts accepts Ed25519-signed peers only; the JWT and Subsonic credential branches are removed. Lifecycle gate and version-floor check are unchanged. - routes/proxy.ts forwards only GET /proxy/rest/<endpoint>[.view] for the endpoints peer sync, auto-sync and peer cover art call (getArtists, getArtist, getAlbum, getScanStatus, getCoverArt). Other methods get 405, other paths 404, a request with a body 400 — all decided in onRequest, before auth and body parsing, so none reaches Navidrome. - The upstream path is rebuilt from the matched allowlist entry instead of copied from the caller; body headers are no longer forwarded; a caller `jwt` query param is stripped alongside u/p/t/s. Tests: every allowlisted endpoint passes for a signed active peer (with and without .view); non-GET, off-list endpoints, non-/rest paths, bodies, JWT-only and Subsonic-only callers, disabled and tombstoned peers are all refused without an upstream request. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
- authentication.md: surface table + "Proxy auth" rewritten (who / what, refusal codes). - hub-internals.md: proxy contract — allowlist with the peer call site for each entry, match rules, forwarded headers. - system-architecture.md: auth table, federation route table, and the stream/art rows (peer audio is /federation/stream/:id, not the proxy). - pitfalls.md: rule against widening the proxy. - federation-api.md: peer-facing proxy surface; no version bump needed. - SECURITY.md: status note on the matching assessment finding. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Observed while running the gate for this branch: the Docker VM ran out of memory with three test stacks up and the kernel killed a live hub. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
benders
force-pushed
the
feature/308-proxy-peer-only-allowlist
branch
from
November 12, 2026 01:16
e3e2f6e to
03d0e98
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #308.
What changes
/proxy/*exists so peer hubs can read library metadata and cover art from the local Navidrome. This narrows the route to that job.Peer-only.
hub/src/proxy/auth.tsaccepts Ed25519-signed peer requests and nothing else. The JWT and Subsonic-credential branches are removed. The lifecycle gate (disabled / tombstoned peers get the uniform403) and theMIN_FEDERATION_API_VERSIONfloor check are unchanged.Endpoint allowlist.
hub/src/routes/proxy.tsforwards onlyGET /proxy/rest/<endpoint>[.view]for:getArtistslibrary/sync-instance.ts)getArtistgetAlbumgetScanStatusservices/auto-sync.ts)getCoverArtroutes/subsonic/stream.ts)Other methods get
405, other paths404. The match is an exact comparison on the undecoded path, and the upstream path is rebuilt from the matched entry rather than copied from the caller.No request bodies. A request that declares a body gets
400;content-type/content-lengthare no longer forwarded.The method / path / body checks run in
onRequest, before auth and before body parsing, so a refused request never produces a Navidrome request.How the allowlist was derived
Every call that goes through a peer's
/proxy/*was enumerated in the current tree and in the tree at the federation v5 release (the supported floor), plus the history in between. The set of proxied endpoints is the same five at v5, v6, v7 and v8. Peer audio uses/federation/stream/:id, and local sync talks to Navidrome directly, so neither needs the proxy. The frontend, scripts and the Python federation suite contain no/proxy/caller.Federation API version
FEDERATION_API_VERSIONis not bumped andMIN_FEDERATION_API_VERSIONstays at 5. Reasoning:/proxy/*request outside the allowlist, so no conforming peer can observe the narrowing. Request and response shapes for the allowed calls are unchanged.FEDERATION_API_VERSION, so raising it would block new handshakes with hubs that have not upgraded yet, for a change they cannot see.docs/federation-api.mdnow points at the allowlist so the peer-facing surface is documented in the contract.Tests
hub/test/proxy.test.tsrewritten around the new surface: every allowlisted endpoint passes for a signed active peer (with and without.view); non-GET, off-list endpoints, near-miss paths, non-/restpaths, bodies, JWT-only callers (header, cookie, query), Subsonic-only callers, peers below the floor, disabled and tombstoned peers are refused, each asserting zero upstream requests.Docs
docs/authentication.md(surface table + "Proxy auth"),docs/hub-internals.md(proxy contract, allowlist with call sites),docs/system-architecture.md(auth table, route table, stream/art rows — these still described peer audio as going through the proxy),docs/pitfalls.md(rule against widening the proxy; a harness memory gotcha hit while running the gate),docs/federation-api.md, and a status note on the matching finding inSECURITY.md.Gates
pnpm verify— typecheck + lint clean (zero output); hub 1033 passed / 77 files; frontend 193 passed / 24 files; hub integration 22 passed, 8 skippedpnpm test:federation— sync, cover art, peer streaming, lifecycle scenarios all passed;subsonic-compat84 passedunit+federationgreen)🤖 Generated with Claude Code