security: restrict Router Replay read APIs with explicit authorization

Audited upstream baseline (2026-07-15)

On current main, Router Replay exposes read-only routes under /v1/router_replay for list/detail, aggregate, and trajectory data when replay recorders are configured. handleRequestHeaders dispatches these routes directly to handleRouterReplayAPI; there is no route-specific authentication or authorization check in that code path.

Replay records can contain request/response bodies and tool traces when those fields are configured for capture. This makes the API an operator surface, not a public inference endpoint. A deployment can place gateway authentication and network policy in front of it, but the repository does not yet define and test one explicit production access contract.

Scope

1. Define the trusted identity source and required permission for Router Replay reads.
2. Enforce fail-closed authorization for every Replay route, including list/detail, aggregate, and trajectory.
3. Keep authorization separate from record filtering: filtering results is not an access-control mechanism.
4. Document a supported deployment boundary for network isolation and gateway policy. NetworkPolicy belongs in deployment manifests/docs, not in the Go handler.
5. Ensure unauthorized attempts are observable without logging credentials or replay content.

Acceptance criteria

• Unauthenticated requests are rejected before any replay record is read.
• Authenticated but unauthorized callers receive a stable denial response.
• Authorized operators can use every documented Replay read route.
• Route aliases, query parameters, and detail modes cannot bypass the check.
• Tests cover enabled/disabled Replay, missing identity, denied identity, and allowed identity.
• Production deployment docs include least-privilege gateway/network-policy guidance.
• Logs and metrics contain no raw credentials, prompts, responses, or tool arguments.

Relevant surfaces

src/semantic-router/pkg/extproc/router_replay_api.go, processor_req_header.go, trusted auth/identity configuration, deployment manifests, docs, and E2E coverage.

Related history: #1075, #1107.