45 lines
2.6 KiB
Markdown
45 lines
2.6 KiB
Markdown
# 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
|