docs: record shared API credential boundaries for every product

Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>

Author: jeremi

crates/registry-cli-api/README.md

@@ -22,6 +22,54 @@ check output uses the shared `PlatformCliConnectionCheckReport` contract in
 with [example/connection-check-report.json](example/connection-check-report.json)
 as its maintained example.
 
+## Security boundary
+
+Connection selection does not create product authority. `--client` delegates
+to the product adapter, which owns any retained local endpoint, credential,
+profile headers, and readiness checks. `--connection` materializes one saved
+connection for that product, and `--url` is an advanced one-off destination
+that is anonymous unless `--token-file` is supplied. Saved authentication is
+exactly one of anonymous, a referenced bearer, or `private_key_jwt`. The
+receiving product still authenticates and authorizes every protected request.
+
+The direct `--token-file` input must fit within 8 KiB, including its optional
+line ending. That ending is removed and the bearer remains opaque; it need not
+be a compact JWT. Direct token,
+CA, request-body, and header files use the shared bounded regular-file reader;
+on Unix it opens nonblocking, so a FIFO is refused instead of hanging. A
+symlink whose target is a regular file remains accepted. Only `--input -`
+reads a request body from standard input. The saved-connections document uses
+the same reader under its own document bound. Saved bearer and private-key
+references instead use the platform secret resolver, retaining that resolver's
+separate root, permission, size, and symlink policy.
+
+Every service base URL uses the shared checked HTTP(S) type, which permits
+plain HTTP only for loopback. A request path stays under the selected origin
+and deployment prefix. The selected connection owns `Host`, automatic
+`Authorization`, and any product profile header it sets, so command-line headers
+cannot replace them. The client ignores ambient proxies, follows no redirect,
+retries no request, applies fixed connect and overall deadlines, and bounds
+both request and response bodies. Debug output and transport errors do not
+contain the bearer or request values.
+
+The maintained proofs are:
+
+- `crates/registry-cli-api/tests/api_http.rs`, including
+  `automatic_credentials_cannot_be_replaced_by_a_repeated_header`,
+  `paths_and_host_headers_cannot_escape_the_selected_endpoint`,
+  `redirect_answers_are_returned_without_following_them`,
+  `response_bodies_are_bounded`, and
+  `bearer_connection_debug_and_failures_do_not_disclose_the_token`;
+- `crates/registry-cli-api/tests/connection_store.rs`,
+  `saved_connections_add_show_use_reread_credentials_and_acquire_private_key_jwt`;
+- `crates/registry-bregctl/tests/api_cli.rs`,
+  `raw_api_refuses_fifo_file_inputs_without_blocking`,
+  `connection_commands_refuse_fifo_stores_without_blocking`, and
+  `raw_api_accepts_a_regular_token_file_and_request_body_from_standard_input`.
+
+These references identify the maintained contract; this README does not claim
+that they ran in a particular review.
+
 Run the focused checks from the workspace root:
 
 ```console

products/breg/SECURITY-REVIEW-NOTES.md

@@ -4588,3 +4588,33 @@ traceability catalog records these proofs without claiming an execution run.
 - The route reads the known Proposal's Action identifier before body parsing so
   it can attribute an admitted refusal. It releases no Proposal or context
   values during that lookup or refusal.
+
+## Raw API caller credentials
+
+### Threat
+
+A local raw API request uses a client registered for another resource, or the
+tooling's bearer and endpoint selection is mistaken for BReg authorization.
+
+### Enforcement and defaults
+
+`bregctl api PATH --client CLIENT` requires a ready local development session,
+selects only a client admitted to that BReg resource, obtains a fresh bearer
+for the client's registered resource and scopes, and keeps it in memory. The
+adapter uses the API origin retained by that session and creates no reusable
+header file. A saved or explicit remote connection instead uses the endpoint
+and authentication the operator selected. Both paths use the
+[`registry-cli-api` security boundary](../../crates/registry-cli-api/README.md#security-boundary).
+
+The helper adds no BReg grant. The runtime still verifies the credential,
+resolves the configured access profile, and authorizes the requested route,
+record, fields, and operation.
+
+### Tests
+
+- `crates/registry-bregctl/src/dev/tests.rs`:
+  `local_api_accepts_only_clients_admitted_to_this_breg_resource`.
+- The shared transport, saved-credential, and process tests named in the
+  `registry-cli-api` security boundary.
+
+These are maintained test references, not claims of execution in this note.

products/casework/SECURITY-REVIEW-NOTES.md

@@ -1123,3 +1123,29 @@ worker iteration that fails, such as a finish refused under a replaced lease,
 is logged without the row's `event_id` and `destination_id`, because the
 dispatch core reports it without its row. Dispatch operational events are not
 audited.
+
+## Raw API caller credentials and profiles
+
+Threat: a local diagnostic request presents one client's bearer with another
+client's Casework or Review profile, or treats a profile header as authority
+independent of runtime authorization.
+
+`caseworkctl api PATH --client CLIENT` requires a ready local development
+session. Its adapter selects the exact retained client and profile, obtains a
+fresh bearer for that client, and binds the same profile into the
+`Registry-Casework-Profile` and `Registry-Review-Profile` headers. The selected
+connection owns those headers and `Authorization`, so raw command-line headers
+cannot replace them. An integration client registered for another resource is
+refused. Saved and explicit remote connections remain operator-selected and
+follow the shared
+[`registry-cli-api` security boundary](../../crates/registry-cli-api/README.md#security-boundary).
+
+The tooling adds no queue, source, review, or task authority. Casework still
+authenticates the bearer, resolves the applicable caller policy, and decides
+each protected route. The maintained proofs are
+`api_client_selects_the_exact_retained_profile_and_refuses_unknown_clients`,
+`api_connection_sends_the_bearer_profiles_and_writes_only_response_bytes`, and
+`local_api_refuses_an_integration_client_bound_to_another_resource` in
+`crates/registry-caseworkctl/src/dev/tests.rs`, plus the shared tests named in
+the `registry-cli-api` README. This note records their obligations, not an
+execution result.

products/coordinator/SECURITY-REVIEW-NOTES.md

@@ -80,6 +80,50 @@ value-free diagnostics remain unchanged. This check applies only to
   filesystem and directory-component races remain accepted for this adopter
   CLI rather than introducing a directory-descriptor traversal policy.
 
+## Raw API connection authentication
+
+### Threat
+
+An operator assumes the raw API command reuses the legacy Coordinator token
+reader, or assumes a saved bearer or `private_key_jwt` connection grants
+workflow authority by itself.
+
+### Enforcement and defaults
+
+Coordinator retains no local caller session, so `coordinatorctl api` refuses
+`--client`. The operator selects a saved connection or an explicit one-off
+URL. Saved authentication is exactly one of anonymous, a referenced opaque
+bearer, or renewable `private_key_jwt`, under the shared
+[`registry-cli-api` security boundary](../../crates/registry-cli-api/README.md#security-boundary).
+The helper confines the destination and headers, acquires the selected
+credential, and releases only the raw bounded response. It carries no caller
+policy, workflow, run ownership, or downstream product authority. Coordinator
+still authenticates and authorizes each protected route, and every receiving
+product still decides an effect requested by a run.
+
+This path deliberately does not reuse the legacy reader described above.
+Legacy authenticated Coordinator commands keep their 16,384-byte compact-JWT
+validation and, on Unix, `NOFOLLOW` token open. Direct
+`api --url --token-file` instead uses the shared opaque-bearer contract: at
+most 8 KiB and a symlink to a regular file is accepted. Saved bearer and
+private-key references use the platform secret resolver's separate strict
+file policy. These differences preserve both existing contracts rather than
+silently changing older commands.
+
+### Tests
+
+- `crates/registry-coordinator/tests/api_cli.rs`:
+  `api_and_saved_connections_are_available_without_a_runtime_config` and
+  `raw_api_refuses_report_format_before_network_access`.
+- The shared saved-credential, transport, regular-file, and process tests
+  named in the `registry-cli-api` security boundary.
+- The legacy reader remains pinned by
+  `token_file_refuses_symlinks_and_fifos_without_blocking` and
+  `a_relative_token_file_is_read_from_the_current_directory` in
+  `crates/registry-coordinator/tests/cli_remote.rs`.
+
+These are maintained references, not claims that the tests ran in this note.
+
 ## OIDC issuer transport and private addresses
 
 ### Threat

products/discovery/README.md

@@ -41,6 +41,19 @@ traceability. The normal operator flow, owned by `discoveryctl`, is offline
 then restart. The runtime verifies `SHA256SUMS` and an optional
 `package.expectedDigest` pin before consuming the exact packaged index bytes.
 
+`discoveryctl api` has no local `--client` credential adapter. Discovery's
+endpoint is public, so the product resolver directs operators to an anonymous
+saved connection. The shared CLI also permits an operator to deliberately
+select an explicit or saved authenticated connection, but that credential is
+operator-supplied transport state: it is never derived from catalog metadata,
+creates no Discovery authority, and does not make Discovery a native-provider
+proxy. Endpoint and request handling follow the shared
+[`registry-cli-api` security boundary](../../crates/registry-cli-api/README.md#security-boundary).
+`api_and_saved_connections_are_available_without_a_runtime_config` in
+`crates/registry-discoveryctl/tests/api_cli.rs` pins the product surface; the
+shared README names the transport and credential tests. These are maintained
+references, not claims of execution here.
+
 ## Independent release installation
 
 For a published Discovery unit release, download its `discovery-vX.Y.Z-install.sh`

products/evidence/README.md

@@ -105,6 +105,24 @@ before the response exists. Stop and clean with `dev stop` and `dev clean`.
 An explicitly configured shared issuer can be selected with `--issuer-project`;
 Evidence still verifies its own clients, resources, scopes and complete grants.
 
+`evidencectl api PATH --client CLIENT` reuses that ready local session without
+writing the tutorial bearer header. It resolves the exact registered client
+against the retained access-profile digests, obtains a fresh short-lived token
+with the client's retained private key, and sends it only to the Evidence
+origin in the validated ready state. A saved or explicit remote connection is
+operator-selected. Both follow the shared
+[`registry-cli-api` security boundary](../../crates/registry-cli-api/README.md#security-boundary),
+which supplies transport and credentials but no Evidence authority. The
+runtime still decides authentication, complete-grant authorization, selector
+minimization, audit, and disclosure.
+
+`ready_and_stopped_handoffs_validate_the_closed_lifecycle_state` in
+`crates/registry-evidencectl/src/dev.rs` pins the ready-state handoff, and
+`raw_api_response_bypasses_the_ctl_report_envelope` in
+`crates/registry-evidencectl/tests/api_cli.rs` pins the product command's raw
+response path. The shared README names the transport and credential tests.
+These are maintained references, not claims of execution here.
+
 Source descriptions accept HTTPS or numeric loopback HTTP and reject embedded
 credentials, queries and fragments. Fetch an authenticated API description with
 your own client and pass its local file. Source credentials grant no Evidence

products/messaging/SECURITY-REVIEW-NOTES.md

@@ -1011,8 +1011,9 @@ client-token acquisition path, but keeps the token in the request connection
 instead of publishing a header file. It requires a ready development session
 and takes its destination only from the exact nonzero
 `http://127.0.0.1:PORT` API origin retained in the typed session record. The
-shared CLI API transport appends only a relative path without changing that
-origin or its deployment prefix, owns the `Host` and automatic
+shared [`registry-cli-api` security boundary](../../crates/registry-cli-api/README.md#security-boundary)
+appends only a relative path without changing that origin or its deployment
+prefix, owns the `Host` and automatic
 `Authorization` headers, follows no redirects, and ignores ambient proxy
 settings. The Messaging runtime still authenticates the token and applies its
 ordinary access-profile and operation authorization on every protected route;

products/scheduling/SECURITY-REVIEW-NOTES.md

@@ -1493,3 +1493,25 @@ remaining focused proofs and does not assert that they ran.
 - Detail readers receive the current attendance observation with the ordinary
   appointment document. Operational readers receive it only when their profile
   explicitly selects attendance.
+
+## Raw API connection authentication
+
+Threat: a generic diagnostic command is mistaken for Scheduling authority, or
+a credential selected for one connection is silently replaced on the request.
+
+Scheduling retains no local caller session, so `schedulingctl api` does not
+resolve `--client`. The operator selects a saved connection or an explicit
+one-off URL. A saved connection may be anonymous, a referenced bearer, or a
+renewable `private_key_jwt` client under the shared
+[`registry-cli-api` security boundary](../../crates/registry-cli-api/README.md#security-boundary).
+That boundary owns endpoint confinement, automatic authorization, credential
+resolution, redirects, proxies, bounds, and redaction; it carries no task
+grant, catalogue scope, appointment ownership, or capacity authority.
+
+The runtime continues to authenticate and authorize every protected request.
+An anonymous connection reaches only routes the runtime already makes public.
+`api_and_saved_connections_are_available_without_a_runtime_config` and
+`raw_api_refuses_report_format_before_network_access` in
+`crates/registry-schedulingctl/tests/api_cli.rs` pin the product surface. The
+shared README names the saved bearer, `private_key_jwt`, and transport proofs.
+These references do not assert an execution run here.