Enforce the accepted runtime API trust boundary

[Brad-Edwards]

Implement the accepted control-plane exposure model across every runtime route that can reveal state or cause effects.

Acceptance criteria

• Apply the route/authority matrix to current APIs. Make the resulting authorization boundary available to new operation and inject routes; bind identity, audience, participant, and episode only where the selected exposure model requires them.
• Prevent credentials limited to participant views from retrieving full snapshots or another participant's state. Enforce the selected administrative-only boundary where direct participant access is excluded.
• Cover alternate retrieval paths, errors, events, cached results, and idempotent readback. Keep backend-owned organizational authentication and policy at their defined boundary.
• Publish deployment guidance and verify permitted access plus cross-scope and route-bypass rejection using the actual HTTP/API boundary.

Prerequisites: #1356.

References: Diagnosis.

Requirements

• API-404 — Secure, Durable, And Idempotent Control-Plane Semantics

[Brad-Edwards]

🛠️ Picked up by /implement - driver claude-code, branch 1359-enforce-runtime-api-boundary, 2026-09-26T03:06:46.480Z.

[Brad-Edwards]

gc workflow phase recorded: preflight (issue #1359). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

[Brad-Edwards]

gc workflow phase recorded: preflight (issue #1359). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

[Brad-Edwards]

gc workflow phase recorded: plan (issue #1359). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

Plan — enforce the accepted runtime API trust boundary (API-404-C3)

Selected model (#1356, preflight docs/decisions/issue-1359-runtime-api-trust-boundary-preflight.md): host-mediated, administrative-only P2. No participant role, episode token, new route, or published schema.

Code (implementations/python/packages/raes_runtime/)

1. One transport-authority seam — control_plane_security.py: add ControlPlaneRouteAuthority (public-probe, administrative-read, administrative-mutation, operator-resolution) and the single role table per authority. control_plane_api/_auth.py: replace the three role methods with admit(request, authority); rename the dependency aliases to _AdministrativeReadIdentity / _AdministrativeMutationIdentity / _OperatorResolutionIdentity, add a no-op public-probe marker dependency.
2. Fail-closed route inventory — at the end of create_control_plane_app(), derive every route's authority from its direct dependency. Construction fails for a runtime route with zero or several authorities, a public probe on a non-GET method, or any non-API route other than the framework description routes. The immutable (method, path) → authority inventory is exposed as app.state.control_plane_route_authority. Future operation/inject/stream routes must choose one authority, then apply their core subject policy.
3. Remove the duplicate read dependency in control_plane_api_participant_retrieval.py; import the shared one (the inventory check would otherwise reject it). Health routes declare public-probe.
4. No-store boundary — a pure-ASGI middleware in control_plane_api_guards.py, installed outermost, sets Cache-Control: no-store on every response (reads, errors, 401/403/404/409/413/422, idempotent replay). The redacted 500 handler sets it directly because Starlette's server-error layer sits outside user middleware.
5. Config shape — _frozen_principals validates roles as a frozenset of ControlPlaneRole, target_name as None or non-empty str, and both subject-binding fields as tuples of their dataclasses. Errors are value-free.

Tests (Path A) — tests/test_issue_1359_runtime_api_trust_boundary.py, real ASGI boundary

• The inventory equals the expected matrix (drift). Construction rejects unauthenticated, double-authority, and mutating-public routes.
• Every authenticated route: unauthenticated → 401; wrong target → 403; wrong role → 403; no-role audience-bound identity → 403 (the participant-limited case). An admitted identity passes transport admission on every route.
• A read role plus an audience binding reads /snapshot (proof of broad administrative authority).
• Governed views: bound participant → 200. Another or unknown participant → identical 403. Ambiguous binding → 409. Episode mismatch → 404. Same-key replay returns the retained view with no new crossing; a cross-scope identity reusing the key → 403. Legacy no-resolver view is an admin read with no crossing.
• Operation readback: cross-actor response identical to unknown (404). Control occurrence with audience binding only → 403.
• no-store on success, 401/403/404/413/422/500, and replay. Health/OpenAPI routes expose no target/run state. Bypass: trailing slash, HEAD, and untrusted proxy headers do not admit.
• Config-shape rejection cases.

Docs (Path D)

• New public guide docs/public/guides/control-plane.md ("Serve the runtime control plane"): host responsibilities, authority table, identity configuration, legacy-view refusal, deployment checklist (admin network, TLS, header stripping, one worker/no reload, secret handling, no shared caching, host cache scoping, error hygiene), and how a new route declares authority. Added to the toctree and the index routes.
• Pointer from docs/explain/sdl/runtime-architecture.md.
• API-404-C3 clarified: per-route declared authority, fail-closed composition, no-store. Traceability (Step 16): DOCUMENTS Enforce the accepted runtime API trust boundary #1359 and preflight, IMPLEMENTS changed files, TESTS new file. API-404 is already ACTIVE, so the transition is a no-op.

Constraints

Targeted local tests only (the new file plus test_runtime_control_plane_api.py, test_run_310_supervisory_lifecycle.py, and the crossing/1179 auth tests); CI owns the full suite. RAES_REQUIREMENT_UID=API-404. No CHANGELOG or version edits. PR title feat:.

[Brad-Edwards]

gc_codex_review — sanitized deferred publication for issue #1359, cycle 1 of 1
Reviewed revision: da19cd175b8799ef7be3296d6e96bfd5517db60103abac4173df15f3703c957e

Architectural read

Core reviewer: transport admission sits at the shared route-dependency seam and the no-store cache policy is applied at the application boundary. Participant and operation-specific decisions stay in the core, consistent with ADR-104, and a new administrative route can reuse the seam. Remaining gap: configuration-time validation does not enforce the bounds that downstream operation-context and audit contracts require.

Security reviewer: the change keeps participant and operation scope checks in the core, applies no-store across the P2 app, and creates no participant credential. No concrete exploitable issue was introduced by the diff.

Verdict: ship-with-fixes

Findings

core-F1 — Validate principal contents against downstream bounds when freezing configuration

• Classification: one-off
• Decision: fix
• Location: implementations/python/packages/raes_runtime/control_plane_security.py:131
• Rationale: Real defect: the config check validates containers but not actor length, binding field types or lengths, or aggregate authorization-scope size. An over-bound actor passes configuration and later produces a 500 when the audit event is built. Fix: validate each principal against the existing operation-context and audit bounds when the principal maps are frozen, and add regression cases for over-bound actors, malformed binding fields, and oversized scope.

[Brad-Edwards]

gc_codex_review pre-push cycle 1 of 1 complete for issue #1359 on branch '1359-enforce-runtime-api-boundary'. Posted by the MCP server to enforce the pre-push hard-cap-1 contract (issues #796, #804, #906). Do not edit or delete — used by the next gc_codex_review (uncommitted) invocation to count cycles.

[Brad-Edwards]

Review decision record — codex cycle 1 (issue #1359)

Reviewer: codex
Cycle: 1
Verdict: ship-with-fixes

Architectural read:

Core reviewer: transport admission sits at the shared route-dependency seam and the no-store cache policy is applied at the application boundary. Participant and operation-specific decisions stay in the core, consistent with ADR-104, and a new administrative route can reuse the seam. Remaining gap: configuration-time validation does not enforce the bounds that downstream operation-context and audit contracts require.

Security reviewer: the change keeps participant and operation scope checks in the core, applies no-store across the P2 app, and creates no participant credential. No concrete exploitable issue was introduced by the diff.

Blocking findings: 1

Finding 1 — one-off

• ID: core-F1
• Title: Validate principal contents against downstream bounds when freezing configuration
• Location: implementations/python/packages/raes_runtime/control_plane_security.py:131
• Decision: fix
• Rationale: Real defect: the config check validates containers but not actor length, binding field types or lengths, or aggregate authorization-scope size. An over-bound actor passes configuration and later produces a 500 when the audit event is built. Fix: validate each principal against the existing operation-context and audit bounds when the principal maps are frozen, and add regression cases for over-bound actors, malformed binding fields, and oversized scope.

[Brad-Edwards]

Pre-PR base synchronization

• Source: refs/remotes/origin/dev at 998364710820e96a11d9ca9ba153ab5ef1cf8633
• Outcome: merged_clean
• Published feature head: d0c6bde026821586f1ccf91af4b279822cb3aeba
• Synchronized tree: 5a4ea2df77a5551c67934902b78f03c17216fdcf