alkhttp/docs/architecture/decisions/071-dispatch-schema-guard.md

ADR-071: The dispatch-spine services/schema op-path guard

Status

Accepted

Context

Review-002 PRJ-16 ([major, security]) found that the GET /schema disclosure fixes (GW-02, SRV-02) had a sibling hole through the op path: services/schema is an External operation with default ACL, so the gateway's outer-name pre-checks admit it — and alkcall's services_schema_handler performs a bare registry.registration(name) → spec projection with no visibility and no AccessControl check of its own. Any HTTP caller could fetch the full spec (input/output/error schemas, required_scopes) of an Internal or ACL-restricted operation with:

POST /call {"operation":"services/schema","input":{"name":"secret/op"}}

— unauthenticated, and identically through the MCP call and batch tools. The same GET /schema route that returns 404 for that op was thus circumventable in one request. (Disclosure only; the target op's handler never executes.)

The complete fix is alkcall-side: the handler itself must check — filed as CF-004 in alkcall/docs/reviews/consumer-findings-ledger.md. But the alkcall lead time was unknown, and the hole is in this crate's wire surface today.

Decision

GatewayDispatch blocks services/schema invocations whose inner name input would be denied by the GET /schema route for the same identity. Before dispatch, when the resolved operation is the services/schema meta-op, the spine applies the same two checks the route applies to ?name=:

• Inner op is Visibility::Internal → NOT_FOUND (404 on HTTP).
• Inner op denies the caller's AccessControl → FORBIDDEN (401 unauthenticated / 403 authenticated under the gateway error mapping — identical to the GET /schema denials).

The guard lives in the dispatch spine (invoke + invoke_streaming), not in the route handlers, because every HTTP transport and the MCP call/batch tools flow through it — one interception point covers /call, /batch, /subscribe (defense-in-depth: the registry rejects the Query-typed meta-op on the streaming path anyway), and the MCP tools. Sink dispatch (/publish) cannot reach services/schema: the registry rejects non-Pub operations before the handler runs and the sink ignores the input, so nothing is projected there.

The visibility + ACL check itself is one shared function (schema_disclosure_denial) used by the HTTP GET /schema route, the dispatch-spine guard, and the MCP schema tool, so the transports cannot drift.

Consequences

• Transport-level invariant (PRJ-16's wording): no alkhttp transport can fetch, through any path, a spec the GET /schema route would deny for the same identity.
• When CF-004 landed, the guard stayed — and was promoted. The alkcall-side handler check is the complete fix for every transport (wire, overlays, peer composition; alkcall commit 8cb2a6e). The alkhttp spine, the GET /schema route, the MCP schema tool, and the spine's services/schema op-path guard all now converge on the shared promoted implementation: alkcall::gateway:: schema_disclosure_denial (alkcall ADR-048). The local copy was deleted on the alkcall-0.2 bump — one implementation, so the transports still cannot drift, and no alkhttp-local fork remains. Do not re-introduce a local copy.
• The dispatch spine itself is promoted too. GatewayDispatch (the invoke/invoke_streaming/invoke_sink spine with the root-OperationContext invariants and the inner-name guard) is alkcall::gateway::GatewayDispatch (feature gateway, enabled unconditionally by the alkcall dependency — the gateway endpoints are this crate's sole invoke path, ADR-047). The alkhttp-local copy was deleted; only the HTTP-specific layers remain here (the CallError → HTTP mapping in gateway::error, NDJSON/SSE framing, body caps, batch envelopes, and this ADR's original FORBIDDEN-vs-spec-404 split on the GET route).
• /publish chunk validation is registry-backed. The local compile-once PublishSchemaCache was deleted: alkcall CF-003 compiles publish_schema at registration time and exposes the cached validator as OperationRegistry::publish_validator. The /publish chunk stream resolves against that cache; the fail-closed guarantee moved upstream with it (an un-compilable schema is a registration error, so an unvalidated-ingest path cannot be constructed).
• CF-001 resolution: alkcall's CallError::connection_closed (retryable CONNECTION_CLOSED) covers the write-failure race; the from_wss drop-monitor race tests assert retryable-only (the previously-tolerated non-retryable INTERNAL: failed to write request frame outcome is gone from the wire vocabulary on the undelivered-request path).
• Wire-observable behavior is unchanged from the pre-promotion guard: previously-leaking requests still get the same 404/403 the GET route returns; legitimate services/schema calls (allowed inner names) are unaffected.
• The guard matches the outer registration's spec.name against the services/schema constant rather than the raw request string, so leading-slash variants (/services/schema) hit the same check.