Skip to content

fix(proxy): restrict /proxy/* to signed peers and a read-only endpoint allowlist - #309

Merged
benders merged 3 commits into
mainfrom
feature/308-proxy-peer-only-allowlist
Nov 12, 2026
Merged

benders merged 3 commits into
mainfrom
feature/308-proxy-peer-only-allowlist

Conversation

@benders

@benders benders commented Nov 12, 2026 •

Copy link
Copy Markdown
Owner

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.ts accepts Ed25519-signed peer requests and nothing else. The JWT and Subsonic-credential branches are removed. The lifecycle gate (disabled / tombstoned peers get the uniform 403) and the MIN_FEDERATION_API_VERSION floor check are unchanged.

  • Endpoint allowlist. hub/src/routes/proxy.ts forwards only GET /proxy/rest/<endpoint>[.view] for:

    Endpoint Peer call site
    getArtists library sync (library/sync-instance.ts)
    getArtist library sync
    getAlbum library sync
    getScanStatus auto-sync poll (services/auto-sync.ts)
    getCoverArt peer cover art (routes/subsonic/stream.ts)

    Other methods get 405, other paths 404. 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-length are 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_VERSION is not bumped and MIN_FEDERATION_API_VERSION stays at 5. Reasoning:

  • No supported peer (v5–v8) issues a /proxy/* request outside the allowlist, so no conforming peer can observe the narrowing. Request and response shapes for the allowed calls are unchanged.
  • A bump is not free: the handshake compares the invitee's version against the current 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.md now points at the allowlist so the peer-facing surface is documented in the contract.

Tests

hub/test/proxy.test.ts rewritten 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-/rest paths, 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 in SECURITY.md.

Gates

  • pnpm verify — typecheck + lint clean (zero output); hub 1033 passed / 77 files; frontend 193 passed / 24 files; hub integration 22 passed, 8 skipped
  • pnpm test:federation — sync, cover art, peer streaming, lifecycle scenarios all passed; subsonic-compat 84 passed
  • Docs
  • CI on the pushed head (unit + federation green)

🤖 Generated with Claude Code

@benders
benders marked this pull request as ready for review November 12, 2026 01:01
benders and others added 3 commits November 11, 2026 17:15
…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
benders force-pushed the feature/308-proxy-peer-only-allowlist branch from e3e2f6e to 03d0e98 Compare November 12, 2026 01:16
@benders
benders merged commit e14a4f0 into main Nov 12, 2026
2 checks passed
@benders
benders deleted the feature/308-proxy-peer-only-allowlist branch November 12, 2026 01:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Restrict /proxy/* to signed peers and a read-only endpoint allowlist

1 participant