docs(tasks): decompose review 001 remediation Units 1-5 into taskgraph tasks

21 review-001 tasks across server/adapters/client/gateway/websocket/infra, chunked from the 7-unit remediation plan in docs/reviews/001-initial-implementation-review.md. - Scope split by mechanism, not one-per-finding: 15 tasks in generation 1 (parallelizable), 6 sequenced after their file-sharing precursors - Deliberately deferred until dependent fixes land: projection/doc fidelity partial (Unit 6 beyond dependency hygiene), coverage backfills (COV-01..07 via in-task acceptance for forward.rs), and per-finding minors (OAI-06/07, HY-02/04/06/10/11, CON-08) - Cross-crate WS-12 (alkcall demux 4 GiB discard alloc) noted for filing in alkcall, not here taskgraph: validate clean, no cycles, 6 generations
2026-08-29 07:10:15 +00:00
parent 54f8e2310e
commit 12b35e2c5f
21 changed files with 1324 additions and 0 deletions
@@ -0,0 +1,52 @@
+---
+id: review-001-extra-routes-auth
+name: Mount extra_routes under the bearer-auth middleware (SRV-01)
+status: pending
+depends_on: []
+scope: narrow
+risk: medium
+impact: component
+level: implementation
+tags: [server, review-001, security]
+---
+
+## Description
+
+Review 001 finding SRV-01 (`docs/reviews/001-initial-implementation-review.md`,
+empirically verified): `build_router`
+(`src/server/adapter.rs:170-183`) applies `bearer_auth_middleware` via
+`route_layer` **before** merging `extra_routes`, so assembly-layer custom
+routes are mounted without auth — contradicting ADR-046 §4 ("custom routes
+carry the same auth middleware by default"). Amplified by
+`ResolvedIdentity` extraction being infallible: a custom handler silently
+receives `None` on every request.
+
+Fix: apply the auth layer **after** merging extra routes so the documented
+default holds. Per-route opt-out remains the deployment's explicit choice
+(extras may carry their own inner layers). Also decide and document the
+SRV-06 interaction: a same-method collision on a reserved path panics in
+axum's `merge` (sanctioned), but a different-method merge (e.g. custom
+`POST /search`) silently serves on a reserved path — enforce
+`RESERVED_PATHS` or document the behavior; the exported constant currently
+has no reader.
+
+## Acceptance Criteria
+
+- [ ] A test mounts an extra route and asserts `ResolvedIdentity` is resolved from the bearer token (auth applies)
+- [ ] A test shows an extra route carrying its own layer can still opt out (documented escape hatch)
+- [ ] SRV-06 decision landed: per-method reserved-path merges rejected/documented; `RESERVED_PATHS` enforced or un-exported
+- [ ] ADR-046 §4 language matches the implemented default after the fix
+- [ ] `cargo test` and `cargo clippy --all-targets -- -D warnings` pass
+
+## References
+
+- docs/reviews/001-initial-implementation-review.md (Part A, SRV-01, SRV-06)
+- docs/architecture/decisions/046-assembly-layer-custom-http-routes.md
+
+## Notes
+
+> Agent fills during implementation.
+
+## Summary
+
+> Filled on completion.
@@ -0,0 +1,67 @@
+---
+id: review-001-hyper-server-knobs
+name: Configure hyper timeouts + decoy/405/proxy-path fixes (SRV-04, SRV-07, SRV-08, SRV-09, SRV-10)
+status: pending
+depends_on: []
+scope: moderate
+risk: low
+impact: component
+level: implementation
+tags: [server, review-001, stealth]
+---
+
+## Description
+
+Review 001 server-core minors, grouped because they are small, disjoint,
+and all land in `src/server/`:
+
+- **SRV-04**: `HyperBuilder` (`src/server/adapter.rs:217-224`) sets no
+  timer — hyper 1.11 *silently ignores* `header_read_timeout` without one
+  (verified against hyper source), so the slow-loris surface is open and
+  every keep-alive knob is off. Set a timer (tokio) + `header_read_timeout`
+  + h1/h2 keep-alive knobs. No concurrency cap exists in this crate (the
+  accept loop is the consumer's) — document that boundary in the module
+  doc.
+- **SRV-05**: `with_decoy` consumes `extra_routes` via `.take()`
+  (`adapter.rs:104`); a second builder call silently rebuilds without the
+  custom routes. Clone (or error on double-build).
+- **SRV-07**: the decoy is only the router `fallback` — method-mismatch
+  requests return axum's bare 405 with no `Server: nginx` header, which
+  single-handedly distinguishes alkhttp from nginx in decoy deployments
+  (empirically verified). Wrap 405s with the decoy response.
+- **SRV-08**: `percent_decode` maps `+`→space (wrong in a URI path) and
+  per-byte→char (mojibake for non-ASCII filenames) — `decoy.rs:106-127`.
+  Fix with proper UTF-8 percent-decoding; also move the blocking
+  `is_dir()`/`is_file()` syscalls off the async path.
+- **SRV-09**: `/openapi.json` error path echoes raw serde internals to
+  unauthenticated callers and re-serializes the whole projection per
+  request (`adapter.rs:250-254`); companion unguarded
+  `.expect("to_openapi always emits…")` in `to_openapi.rs:67`. Cache the
+  serialized doc, return a generic 500 body, remove the `expect`.
+- **SRV-10**: WS upgrade hardcodes `NoCap` while the doc claims a
+  stricter policy is passable — add the injection point or fix the doc;
+  drop the double token resolution (router middleware + `ws_bearer_auth`).
+
+## Acceptance Criteria
+
+- [ ] Hyper configured with timer + header read timeout; knob values documented
+- [ ] 405 responses carry the decoy `Server` header (test with `OPTIONS /search`)
+- [ ] `%C3%A9` and `a+b.html` resolve correctly in the decoy static server (tests); async-path syscalls gone
+- [ ] `/openapi.json` 500 body is generic; doc cached; `expect` removed
+- [ ] Second `.with_decoy` no longer silently drops extra routes (test)
+- [ ] SRV-10: policy injection point exists or doc corrected; single token resolution
+- [ ] `cargo test`, `cargo test --all-features`, `cargo clippy --all-targets -- -D warnings` pass
+
+## References
+
+- docs/reviews/001-initial-implementation-review.md (Part A, SRV-04..SRV-10)
+- docs/architecture/decisions/010-alpn-router-and-endpoint.md
+
+## Notes
+
+> Agent fills during implementation. Independent of the other
+> review-001 tasks; can proceed in parallel.
+
+## Summary
+
+> Filled on completion.
@@ -0,0 +1,48 @@
+---
+id: review-001-mcp-body-limit
+name: Cap the /mcp nest body size (SRV-03, gated on mcp feature)
+status: pending
+depends_on: []
+scope: narrow
+risk: low
+impact: component
+level: implementation
+tags: [server, review-001, security, mcp]
+---
+
+## Description
+
+Review 001 finding SRV-03 (mcp feature only): `src/server/adapter.rs:141-150`
+nests rmcp's `StreamableHttpService`; the bearer middleware only stashes
+identity. axum's 2 MiB `DefaultBodyLimit` applies to axum *extractors*,
+but the nested rmcp service collects the raw body itself
+(`body.collect().await`, verified against rmcp 1.8.0) with no cap — a
+single multi-GB chunked `POST /mcp` is buffered entirely in memory; a few
+concurrent requests OOM the process. Gateway routes are correctly capped
+at 2 MiB by the extractors; `/mcp` is the one uncapped surface.
+
+Fix: wrap the `/mcp` nest with an explicit `DefaultBodyLimit` (or an
+equivalent body-limit layer) sized for MCP traffic. Pick and document the
+limit (a JSON-RPC batch is the largest legitimate body; something in the
+2–8 MiB range is defensible) rather than leaving it at hyper's unlimited
+default.
+
+## Acceptance Criteria
+
+- [ ] Explicit body limit applied to the `/mcp` nest; limit value documented in code and ADR-039 or http-server.md if touched
+- [ ] Test: oversized `POST /mcp` body → 413 (Content-Length and streaming/chunked variants)
+- [ ] Normal-size MCP initialize + tools/call round-trip still passes
+- [ ] `cargo test --all-features` passes (feature-gated code)
+
+## References
+
+- docs/reviews/001-initial-implementation-review.md (Part A, SRV-03)
+- docs/architecture/decisions/039-http-server-and-client-host-colocated.md
+
+## Notes
+
+> Agent fills during implementation.
+
+## Summary
+
+> Filled on completion.
@@ -0,0 +1,60 @@
+---
+id: review-001-schema-internal-visibility
+name: Enforce Internal-op invisibility on GET /schema (SRV-02, PRJ-06, GW-02)
+status: pending
+depends_on: []
+scope: narrow
+risk: medium
+impact: component
+level: implementation
+tags: [server, gateway, review-001, security]
+---
+
+## Description
+
+Review 001 findings SRV-02 + PRJ-06 + GW-02 — three faces of one
+visibility gap on the discovery axis:
+
+- **SRV-02** (`src/gateway/routes.rs:120-137`): `schema_handler` runs only
+  `access_check_for_op`; it skips the `is_internal_op` pre-check that
+  `/call`, `/batch`, `/subscribe`, `/publish` all apply. Internal ops carry
+  `AccessControl::default()`, so an unauthenticated caller can fetch the
+  full spec (visibility, schemas, `access_control`) of an op it cannot
+  call. `POST /call` on the same op correctly 404s (tested); `GET /schema`
+  does not — the invisibility invariant (ADR-015 §2) is defeated on the
+  discovery axis.
+- **PRJ-06** (`src/adapters/to_mcp.rs:148-174`): the MCP `schema` tool has
+  the identical gap — no per-op pre-check, full spec including
+  `required_scopes` returned for forbidden ops. The test
+  `schema_returns_full_operation_spec` enshrines the leak.
+- **GW-02**: `/search` and `/schema` are per-identity GETs with no
+  `Cache-Control: no-store` / `Vary: Authorization`, so shared caches may
+  serve caller A's filtered response to caller B.
+
+Fix all three in one pass since they share the pre-check logic and test
+fixtures: add the 404 guard to `schema_handler`; run the same
+`access_check_for_op` pre-check in the MCP `schema` tool (or filter the
+returned spec per identity) and fix the enshrining test; add cache headers
+to the two per-identity GETs.
+
+## Acceptance Criteria
+
+- [ ] `GET /schema?name=<internal>` → 404 unauthenticated, for an unauthorized identity, and for an anonymous identity (test)
+- [ ] MCP `schema` tool denies/404s unauthorized ops symmetrically with HTTP `/schema` (test); enshrining test fixed
+- [ ] `/search` + `/schema` responses carry `Cache-Control: no-store` (and `Vary: Authorization` where a token can change the body)
+- [ ] `cargo test` and `cargo clippy --all-targets -- -D warnings` pass
+- [ ] `cargo test --all-features` passes (the MCP half is feature-gated)
+
+## References
+
+- docs/reviews/001-initial-implementation-review.md (SRV-02, PRJ-06, GW-02)
+- docs/architecture/decisions/015-privilege-model-and-authority-context.md
+- docs/architecture/decisions/041-mcp-tool-gateway-pattern.md
+
+## Notes
+
+> Agent fills during implementation.
+
+## Summary
+
+> Filled on completion.