feat: complete credential broker source flow

docs/credential-broker.md

@@ -2,7 +2,7 @@
 
 **Workplan:** `RAILIANCE-WP-0005`
 **Owner:** `railiance-platform`
-**Status:** source implementation started
+**Status:** source implementation complete; live verification pending approved token path
 
 This document records the Railiance credential broker ownership decision and
 the first implementation contract for short-lived OpenBao credential leases.
@@ -128,6 +128,9 @@ Git.
 
 `kubernetes-auth` is for in-cluster workloads. Workloads should authenticate
 with service-account-bound auth instead of receiving manually handed tokens.
+For the pilot grant, `request --delivery kubernetes-auth` returns only
+non-secret OpenBao auth metadata such as the auth mount, role, service account
+names, and namespaces; it does not mint or print a bearer token.
 
 The denied modes are absolute unless a later ADR updates the catalog:
 
@@ -174,10 +177,122 @@ Dry-run all helper paths with:
 make credential-helper-dry-run
 ```
 
+Pass helper global options before the subcommand. For example, if the OpenBao
+pod has an approved token helper session:
+
+```bash
+make credential-exec-ops-warden-smoke CREDENTIAL_HELPER_GLOBAL_ARGS=--use-token-helper
+```
+
 The child process receives `VAULT_TOKEN` in its environment. The token is not
 printed, written to shell history, sent to State Hub, or placed in an LLM
 prompt.
 
+## Identity And Authorization
+
+The helper records the following non-secret request identity fields:
+
+- `actor`: the requester identity, defaulting to `codex:<local-user>`;
+- `actor_type`: one of the grant-approved actor classes such as
+  `human-operator`, `approved-agent`, or `ci-runner`;
+- `subject`: the bound human, agent, CI, or Kubernetes service-account subject.
+
+Human operators should use the KeyCape/OIDC path with MFA when the grant class
+or purpose requires it. Agents and CI runners should use stable subject strings
+that can be mapped to IAM profile claims, for example
+`agent:codex/railiance-platform` or
+`system:serviceaccount:<namespace>:<service-account>`. Headless automation must
+use Kubernetes auth or an explicitly approved non-interactive identity; it must
+not reuse a human OpenBao token.
+
+The helper performs local catalog checks before any issuance:
+
+- purpose is required;
+- requested TTL must not exceed the grant max TTL;
+- delivery mode must be allowed by the grant;
+- actor type must be allowed by the grant.
+
+Optional flex-auth preflight is enabled with `--flex-auth-url` or `FLEX_AUTH_URL`.
+The helper posts non-secret request metadata to
+`/credential-grants/authorize` by default and accepts allow/deny responses using
+`allowed`, `decision`, or `status` fields plus optional `decision_id` and
+`reason`. Use `--require-flex-auth` when local preauthorization is not
+acceptable. Use `--decision-id` to carry an already-approved external decision
+without calling flex-auth again.
+
+## State Hub Metadata
+
+State Hub recording is opt-in through `--record-state-hub` or
+`CREDENTIAL_RECORD_STATE_HUB=1`. The helper writes request lifecycle notes to
+`/progress/` with non-secret metadata only:
+
+- grant id, actor, actor type, subject, purpose, requested TTL, delivery mode;
+- authorization mode, decision id, and decision reason;
+- lease accessor, wrapping accessor, or wrapped accessor when available;
+- status values such as `requested`, `issued`, `wrapped`, `revoked`, or
+  `delegated`.
+
+It never records raw child tokens, wrapping tokens, token files, passwords,
+OpenBao root/platform-admin tokens, or command output.
+
+## Verification And Revocation
+
+Offline checks:
+
+```bash
+make credential-grants-validate
+make credential-tests
+make openbao-token-grants-dry-run
+make openbao-verify-token-grants-dry-run
+make credential-helper-dry-run
+```
+
+Live source-owned checks, once an approved OpenBao issuer token path exists:
+
+```bash
+OPENBAO_TOKEN_FILE=~/.local/openbao/platform-admin.token make openbao-configure-token-grants
+OPENBAO_TOKEN_FILE=~/.local/openbao/platform-admin.token make openbao-verify-token-grants-smoke
+OPENBAO_TOKEN_FILE=~/.local/openbao/platform-admin.token make credential-exec-ops-warden-smoke
+```
+
+Emergency revocation by accessor:
+
+```bash
+scripts/credential.py revoke <lease-accessor>
+```
+
+When using `local-token-file`, remove stale local lease material after revoke or
+expiry:
+
+```bash
+find .local/credential-leases -type f -maxdepth 1 -print
+```
+
+Response wrapping live verification is manual until a richer integration test
+exists: unwrap the returned wrapping token once with OpenBao, confirm the second
+unwrap attempt fails, then revoke the wrapped child token by accessor.
+
+## Routing And Rollout
+
+Credential routing remains split by responsibility:
+
+- `ops-warden` signs SSH certificates only;
+- OpenBao token or dynamic-lease needs route to `railiance-platform`;
+- login/MFA routes to KeyCape;
+- authorization decisions route to flex-auth.
+
+The rollout sequence is:
+
+1. `ops-warden/warden-sign` pilot for the flex-auth/ops-warden smoke.
+2. Platform-readonly token helper for diagnostics.
+3. Workload-specific grants for application repositories.
+4. Optional split to a dedicated credential-broker repo if the helper grows
+   beyond platform ownership.
+
+The workplan can close only after the live warden-sign pilot runs through the
+helper and the credential routing catalog returns this railiance-platform flow
+for VAULT_TOKEN/OpenBao-token requests.
+
 ## Implementation Sequence
 
 1. Validate and maintain the non-secret grant catalog.