# Scope non-proto fetch allowances by file and exact target

Decided 2026-08-19. Check 5 enforces generated ConnectRPC hooks for frontend
API access. Its `knownNonProtoFetches` map matched broad URL prefixes and
reported every recognized exception as a warning. The CMS and orchestrator
therefore produced eleven permanent warnings for transport contracts that
cannot use generated unary hooks: multipart uploads, an SSE response stream,
the authenticated CMS support proxy, and the browser leg of MCP device
authorization. The warnings added no actionable signal, while prefixes such as
`/api/support/` and `/api/mcp/` could classify unrelated future calls as known.

## Decision

- Replace URL-prefix recognition with `allowedNonProtoFetches`, whose entries
  bind one exact literal fetch target to one source file.
- Require every allowance to carry a rationale explaining why generated
  ConnectRPC hooks cannot express the transport or protocol.
- Permit documented matches without a warning. Continue failing every
  undocumented `/api/` fetch, including an allowed endpoint copied to another
  file or an unreviewed sibling endpoint added to an allowed file.
- Parse the literal first argument to `fetch()` before matching so an exact
  `/api/support/tickets` allowance cannot also admit a longer route by prefix.
- Cover all eleven current exceptions and both scope boundaries with unit
  tests.

Keeping permanent warnings was rejected because a clean run could never reach
zero warnings and new actionable warnings were hidden in expected noise.
Allowlisting entire files was rejected because it would also bypass the manual
client, transport, and unrelated fetch checks. Retaining broad endpoint
prefixes without warnings was rejected because future REST calls could evade
review merely by sharing a namespace.

## Consequences

- Check 5 reports cleanly for the reviewed backup, helpdesk, AI streaming,
  support, MCP device, and plugin upload calls.
- New non-proto calls require an explicit file-and-target decision with a
  written rationale; otherwise the safety run fails.
- Renaming a route expression or moving a caller deliberately invalidates its
  allowance and forces review.
- `frontend.go` owns the allowance policy and exact-target matcher;
  `frontend_test.go` is the executable inventory and boundary regression suite.

Keywords: check-safety, check 5, frontend.go, frontend_test.go, knownNonProtoFetches, allowedNonProtoFetches, nonProtoFetchAllowed, literalFetchTarget, fetch-non-proto-api, no-fetch-api, ConnectRPC, multipart, FormData, SSE, /api/push/upload, /api/helpdesk/upload, /api/ai/chat/stream, /api/support, /api/mcp/device, /api/plugins/upload