feat: enforce the administrative-only runtime API trust boundary

[Brad-Edwards]

Summary

Enforces the accepted host-mediated, administrative-only P2 exposure model (#1356). Every served route declares exactly one method-bound transport authority. Construction fails on any undeclared, duplicate, double-authority, public-mutation, or method-mismatched route. The served app then refuses startup and every request if its routes, middleware, exception handlers, or dependency overrides change after construction. Every response carries Cache-Control: no-store. Transport refusals return stable unauthorized/forbidden bodies, with the specific reason audit-only. Malformed bodies are admitted before they get a 422, and a forbidden resolution looks the same as an unknown operation. Configured principals, trust flags, limits, and credentials are validated at startup. HTTP-boundary tests pin the route matrix and every rejection path, and a new public guide documents deployment and host duties.

Requirement UIDs

• API-404

Related Issues

Refs #1359

ADR Impact

• ADR-104

Changes

• ControlPlaneRouteAuthority with one role table and one HTTP-method table in control_plane_security.py. Public probe and administrative read are GET-only; mutation and operator resolution are POST/PUT/PATCH/DELETE only. _ControlPlaneApiAuth.admit() is the single admission seam.
• create_control_plane_app() validates the route inventory, exposes it as app.state.control_plane_route_authority, and seals the app composition. _ControlPlaneFastAPI.build_middleware_stack and AppCompositionSealMiddleware refuse startup and every request when routes, middleware, exception handlers, or dependency overrides differ from the sealed set.
• NoStoreResponseMiddleware wraps every response. The redacted 500 and sealed-app refusals set no-store directly.
• Refusals no longer reveal their reason: 401 is always unauthorized, and transport 403 is always forbidden. Admission runs before a request-validation 422. A resolution the operator may not perform returns the same 404 as an unknown operation.
• Configured principals: frozenset roles, typed tuple bindings, and actor and scope within the operation-context bounds. Credential keys and principal names must be unpadded, trust flags must be real bool, and limits must be positive int.
• PyJWT (transitive via mcp[crypto]) upgraded 2.13.0 → 2.15.1 to clear ten published advisories flagged by the OSV supply-chain gate; the hash-complete smoke closures were regenerated from the lock.
• Research evidence captures republished at specification-coverage 60.0.0 and formal-validation 61.0.0 for the new source identity.
• API-404-C3 records the per-route, method-bound authority, the sealed composition, no-store, and non-revealing refusals. New guide docs/public/guides/control-plane.md. The Define control-plane and participant-access trust boundaries #1356 preflight names the renamed dependencies.

Test Plan

• Unit tests pass
• Integration tests pass if applicable
• Full completion suite required in CI before merge
• No coverage regression

Targeted: the 41 test files that build the HTTP adapter or security config (1,060 passed), the MCP-consuming test files after the PyJWT upgrade (329 passed), the three evidence modules including their integration lane (223 passed), both evidence checker CLIs, the OSV scan, the tooling artifact policy, fast-feedback (hygiene, policy, lint, changed pytest modules), repo policy, and the offline docs build (Vale, Sphinx, public inventory).

Ground Control Checks

• Repository policy checks required in CI before merge
• Pre-push Codex review completed; all findings fixed or dispositioned

Traceability

• IMPLEMENTS: API-404 ← implementations/python/packages/raes_runtime/control_plane_security.py, API-404 ← implementations/python/packages/raes_runtime/control_plane_api/_auth.py, API-404 ← implementations/python/packages/raes_runtime/control_plane_api/init.py, API-404 ← implementations/python/packages/raes_runtime/control_plane_api_guards.py, API-404 ← implementations/python/packages/raes_runtime/control_plane_api/_operation_routes.py, API-404 ← implementations/python/packages/raes_runtime/control_plane_api_participant_retrieval.py
• TESTS: API-404 ← implementations/python/tests/test_issue_1359_runtime_api_trust_boundary.py, API-404 ← implementations/python/tests/test_issue_1179_startup_reconciliation.py

Checklist

• Code follows the project's coding standards
• Changelog: owned by Release Please (generated from the Conventional Commit PR title; no per-PR fragment)
• Architectural docs updated if stack, package structure, or key behaviors changed

Documentation

Updated: see diff.

[Brad-Edwards]

Ground Control delivery — this pull request delivers issue #1359; Phase E runs on merge.