Define control-plane and participant-access trust boundaries

[Brad-Edwards]

Administrative credentials can read both participant projections and full snapshots. This is unsafe if those credentials are also used as participant-view credentials; the deployment boundary is currently unclear.

Acceptance criteria

• Inventory public runtime entry points and credentials, including snapshot, projection, operation, history, error, and event access. Specify who may use each surface and where authorization is enforced.
• Decide whether participant clients access RAE directly or through a backend boundary. Specify the required principal, audience, participant, and episode bindings for the selected exposure model.
• Cover alternate retrieval and mutation paths, cached/readback results, and cross-participant access. Authentication principals do not require new SDL participant declarations or roles.
• Publish the accepted trust-boundary decision, route/authority matrix, deployment requirements, and affected API-404/ADR-104 clauses. Keep organizational identity and policy responsibilities with the backend.

References: Diagnosis, Control-plane authorization, Ecosystem responsibilities.

Requirements

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

[Brad-Edwards]

🛠️ Picked up by /implement - driver codex, branch 1356-control-plane-participant-boundary, 2026-09-24T01:11:29.276Z.

[Brad-Edwards]

gc workflow phase recorded: preflight (issue #1356). 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 #1356). 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 #1356). 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.

Scope and decision

API-404 is in scope because this issue narrows its served-transport interpretation. Select backend-mediated participant access. RAE P2 identities remain privileged target-bound service identities; a participant/audience binding on one view does not restrict the same identity's snapshot route. The organizational backend owns user/session authentication, entitlement, run/participant/episode/audience/operation binding, credential custody, and the final release decision.

Acceptance criteria and implementation

1. Entry points and credentials — Path D (design contract). Inventory every current P2 route family, in-process/store access, health/OpenAPI, operation readback, raw event/audit paths, errors, and cached results in the issue-1356 decision. State the existing FastAPI role dependency, core authorization where present, and the permitted service/operator consumer. Cross-check against control_plane_api/_auth.py, route registrations, control_plane.py, and control_plane_api_participant_retrieval.py.
2. Exposure and bindings — Path D. Record backend mediation in ADR-104 §7 and API-404-C3. Require backend user/session, target/run, participant, exact episode, audience, and operation bindings for each release. Require a configured API-423/RUN-319 crossing resolver for participant-facing retrieval; the legacy ungoverned projection path is not deployment evidence.
3. Alternate paths and isolation — Path D. Cover mutation receipts, idempotent replay, polling, direct store/in-process reads, histories, diagnostics, errors, events, callbacks, conditional responses, and caches. Reauthorize at every release and reject cross-participant, cross-episode, stale-policy, and stale-state reuse. Keep SDL participant declarations separate from authentication principals.
4. Publication — Path D. Keep the accepted decision and route/authority/deployment matrix in docs/decisions/issue-1356-control-plane-participant-access-preflight.md; amend ADR-104 and its pin/index, API-404, and runtime architecture guidance. Reconcile API-404 DOCUMENTS traceability.

Repository fit and limits

Security layers: reuse ControlPlaneSecurityConfig, _ControlPlaneApiAuth, request-size and redacted-error guards, API-408/API-423 projection and crossing validators, actor-scoped idempotency/readback, the P1 store lease, and the one mutation authority. No client-supplied route selector or service token grants backend entitlement. The deployment keeps P2 on a private service network with protected credentials, one worker, TLS/proxy identity stripping, and private store paths. Maintainability: reuse these incumbents without another principal, DTO, store, or policy engine. Extensibility: the backend-to-RAE adapter is the seam for a later route-scoped credential or participant-safe transport. Whole-repo impact includes the ADR index, requirement traceability, runtime architecture guidance, policy checks, and the existing HTTP/crossing tests. This design makes no new runtime guarantee, organizational backend implementation, SDL role, published schema, or P3 claim.

Verification

Review the matrix against the registered routes and current role dependencies. Run targeted ADR pin/amendment, local-link, repository policy, and whitespace checks plus focused existing HTTP authorization/crossing cases. Full verification remains in CI. Set RAES_REQUIREMENT_UID=API-404 for policy and publish gates because the issue branch has no UID. The documentation-only TDD carve-out is not asserted for organizational backend obligations: this repository has no backend deployment or entitlement implementation whose behavior could be tested here. The decision states that deployment requires separate backend-boundary evidence before participant access is enabled.

[Brad-Edwards]

gc_codex_review — sanitized deferred publication for issue #1356, cycle 1 of 1
Reviewed revision: 51d27ad85fed05089755811373a14db1d1b8439f47523b904252e700ded53e08

Architectural read

Backend-mediated participant access preserves the privileged P2 service boundary, governed projection carriers, and existing mutation authority. No new runtime authorization guarantee is claimed.

Verdict: ship

Notes

• The accepted trust-boundary design has no new runtime enforcement. Align the two issue-1356 API-404 traceability links with design evidence as DOCUMENTS.

Findings

• (none)

[Brad-Edwards]

gc_codex_review pre-push cycle 1 of 1 complete for issue #1356 on branch '1356-control-plane-participant-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 #1356)

Reviewer: codex
Cycle: 1
Verdict: ship

Architectural read:

Backend-mediated participant access preserves the privileged P2 service boundary, governed projection carriers, and existing mutation authority. No new runtime authorization guarantee is claimed.

Blocking findings: 0 (clean run)

Notes (non-blocking, no decisions):

• The accepted trust-boundary design has no new runtime enforcement. Align the two issue-1356 API-404 traceability links with design evidence as DOCUMENTS.

[Brad-Edwards]

Pre-PR base synchronization

• Source: refs/remotes/origin/dev at b00aba06389ab75ffac3b3bdbd026a0dbecac487
• Outcome: already_current
• Published feature head: 45569dbc78a277eb9acd088dbe86f0fba37d58a3
• Synchronized tree: 0d7bf2c7fd1f01f1a33220f710da5ef7892e3fdf

[Brad-Edwards]

Pre-PR base synchronization

• Source: refs/remotes/origin/dev at b00aba06389ab75ffac3b3bdbd026a0dbecac487
• Outcome: already_current
• Published feature head: bc7d7981cda25e2ae905c8658e0ac89092be6149
• Synchronized tree: 73e37a9429903394975f4c3fe717eeeaa6e18bbe