docs: distinguish automatic and explicit API credentials

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

Author: jeremi

crates/registry-cli-api/README.md

@@ -27,10 +27,13 @@ as its maintained example.
 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.
+connection for that product. `--url` is an advanced one-off destination with
+no automatic credential unless `--token-file` is supplied. A saved
+connection's automatic authentication mode is one of anonymous, a referenced
+bearer, or `private_key_jwt`. Anonymous means that the connection supplies no
+automatic credential; when no automatic provider is selected, the raw command
+may still supply one explicit `Authorization` header. 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
@@ -43,19 +46,33 @@ 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.
 
+An explicit header may be inline, read as one value with `NAME: @FILE`, or
+read as complete `NAME: VALUE` lines with `@FILE`. Each header file is bounded
+to 64 KiB. These explicit headers are raw request material held as ordinary
+strings; they do not inherit the 8 KiB `--token-file` credential contract or
+the saved secret resolver's custody policy. In particular, an inline
+credential may be visible to process-argument inspection.
+
 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.
+`Authorization`, and any product profile header it sets, so command-line
+headers cannot replace them. Without an automatic provider, exactly one
+explicit `Authorization` header is accepted through any of the raw header
+forms; another explicit source is refused. The client ignores ambient proxies,
+follows no redirect, retries no request, applies fixed connect and overall
+deadlines, and bounds both request and response bodies. `ApiArgs` debug output
+records header counts and option presence rather than raw request values, and
+the automatic bearer connection's tested debug and failure paths do not expose
+that bearer. Those focused properties are not a general secret-custody
+guarantee for explicit raw headers.
 
 The maintained proofs are:
 
 - `crates/registry-cli-api/tests/api_http.rs`, including
+  `anonymous_requests_accept_one_explicit_authorization_header_from_each_supported_input`,
   `automatic_credentials_cannot_be_replaced_by_a_repeated_header`,
+  `api_args_debug_redacts_request_values`,
   `paths_and_host_headers_cannot_escape_the_selected_endpoint`,
   `redirect_answers_are_returned_without_following_them`,
   `response_bodies_are_bounded`, and

crates/registry-cli-api/tests/api_http.rs

@@ -120,6 +120,50 @@ fn automatic_credentials_cannot_be_replaced_by_a_repeated_header() {
     assert!(!error.to_string().contains("canary-token"));
 }
 
+#[test]
+fn anonymous_requests_accept_one_explicit_authorization_header_from_each_supported_input() {
+    let temporary = TempDir::new().unwrap();
+    let complete_header = temporary.path().join("complete-header");
+    let header_value = temporary.path().join("header-value");
+    fs::write(
+        &complete_header,
+        "Authorization: Bearer complete-file-canary\n",
+    )
+    .unwrap();
+    fs::write(&header_value, "Bearer value-file-canary\n").unwrap();
+
+    for (argument, expected) in [
+        (
+            "Authorization: Bearer inline-canary".to_owned(),
+            "Bearer inline-canary",
+        ),
+        (
+            format!("@{}", complete_header.display()),
+            "Bearer complete-file-canary",
+        ),
+        (
+            format!("Authorization: @{}", header_value.display()),
+            "Bearer value-file-canary",
+        ),
+    ] {
+        let response = b"HTTP/1.1 200 OK\r\nContent-Length: 2\r\nConnection: close\r\n\r\nok";
+        let (base_url, request) = server(response);
+        let mut args = api_args("v1/status", temporary.path().join("out"));
+        args.url = Some(base_url);
+        args.header = vec![argument];
+        run_api("breg", args, |_, _| unreachable!("--url bypasses resolver")).unwrap();
+
+        let request = String::from_utf8(request.recv().unwrap()).unwrap();
+        let authorization = request
+            .lines()
+            .filter_map(|line| line.split_once(':'))
+            .filter(|(name, _)| name.eq_ignore_ascii_case("authorization"))
+            .map(|(_, value)| value.trim_start())
+            .collect::<Vec<_>>();
+        assert_eq!(authorization, [expected]);
+    }
+}
+
 #[test]
 fn local_connection_headers_cannot_be_replaced_by_cli_headers() {
     let temporary = TempDir::new().unwrap();

products/coordinator/SECURITY-REVIEW-NOTES.md

@@ -92,14 +92,17 @@ workflow authority by itself.
 
 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
+URL. A saved connection's automatic 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.
+Anonymous supplies no automatic credential, but the raw command may still
+supply one explicit `Authorization` header. The helper confines the
+destination and headers, acquires any selected automatic 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

products/discovery/README.md

@@ -43,11 +43,13 @@ then restart. The runtime verifies `SHA256SUMS` and an optional
 
 `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
+saved connection, meaning the connection supplies no automatic credential.
+The shared CLI also permits one explicit `Authorization` header on that raw
+request, or lets an operator deliberately select an explicit or saved
+authenticated connection. Such a 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

products/scheduling/SECURITY-REVIEW-NOTES.md

@@ -1501,15 +1501,19 @@ 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
+one-off URL. A saved connection's automatic authentication 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.
+That boundary owns endpoint confinement, automatic credential resolution and
+header precedence, redirects, proxies, bounds, and its focused debug
+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.
+An anonymous connection supplies no automatic credential, but the raw command
+may still supply one explicit `Authorization` header under the shared contract.
+The runtime, not the connection label, decides whether the request may reach a
+public or protected route.
 `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