feat: add credential broker token helper

docs/credential-broker.md

@@ -76,6 +76,41 @@ Every grant entry defines:
 The first pilot grant is `ops-warden/warden-sign`, which creates a short-lived
 OpenBao token with only the `warden-sign` policy.
 
+## OpenBao Token Roles
+
+OpenBao-token grants are configured from source with:
+
+- an issuer policy under `openbao/policies/`;
+- an `auth/token/roles/<role>` token role with allowed policies, disallowed
+  admin policies, non-renewable TTL bounds, no default policy, and orphan token
+  issuance;
+- verification that reads the issuer policy, token role, and target workload
+  policy before any smoke token is minted.
+
+Dry-run the current grant configuration with:
+
+```bash
+make openbao-token-grants-dry-run
+make openbao-verify-token-grants-dry-run
+```
+
+Live application uses an operator-approved OpenBao token from
+`OPENBAO_TOKEN_FILE` or an interactive hidden prompt. The token is passed to the
+OpenBao pod through stdin, never through argv:
+
+```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
+```
+
+The smoke verifier can mint a short-lived child token, confirm that it can list
+`ssh/roles`, confirm that it cannot list unrelated secret engines, and revoke
+the token by accessor:
+
+```bash
+OPENBAO_TOKEN_FILE=~/.local/openbao/platform-admin.token make openbao-verify-token-grants-smoke
+```
+
 ## Delivery Modes
 
 `exec-env` is the preferred local path. The helper obtains a lease, injects
@@ -111,6 +146,34 @@ credential exec --grant ops-warden/warden-sign --ttl 15m -- \
   SMOKE_VAULT=1 /home/worsch/ops-warden/scripts/policy_gate_production_smoke.sh
 ```
 
+The source helper MVP lives at `scripts/credential.py` until this flow graduates
+into a packaged command. It supports the same core shape:
+
+```bash
+scripts/credential.py request --grant ops-warden/warden-sign --purpose flex-auth-openbao-smoke
+scripts/credential.py exec --grant ops-warden/warden-sign --purpose flex-auth-openbao-smoke -- \
+  SMOKE_VAULT=1 /home/worsch/ops-warden/scripts/policy_gate_production_smoke.sh
+scripts/credential.py status <lease-accessor>
+scripts/credential.py revoke <lease-accessor>
+```
+
+`request` defaults to `local-token-file`: the raw child token is written only to
+`.local/credential-leases/` with mode `0600`, and stdout contains the lease
+handle/accessor plus metadata. `--delivery response-wrap` returns an OpenBao
+wrapping token for attended handoff, not the raw child token.
+
+`exec` mints a bounded child token, injects it as `VAULT_TOKEN` only into the
+child process environment, redacts token-looking output, and revokes the token
+by accessor when the child exits. The helper rejects caller-supplied
+`VAULT_TOKEN`/`BAO_TOKEN` env assignments and unsafe OpenBao debug/trace log
+settings.
+
+Dry-run all helper paths with:
+
+```bash
+make credential-helper-dry-run
+```
+
 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.
@@ -122,11 +185,6 @@ prompt.
 3. Build a small helper that supports `request`, `exec`, `status`, and `revoke`.
 4. Add optional flex-auth preflight and State Hub request lifecycle metadata.
 5. Update ops-warden routing so OpenBao token needs point here, while SSH certificate issuance remains in ops-warden.
-token role configuration for each OpenBao-token grant. 3. Build a small helper
-that supports `request`, `exec`, `status`, and `revoke`. 4. Add optional
-flex-auth preflight and State Hub request lifecycle metadata. 5. Update
-ops-warden routing so OpenBao token needs point here, while SSH certificate
-issuance remains in ops-warden.
 
 Live token issuance requires an approved operator path to create or use the
 non-root issuer capability. Source-only validation and dry-run helper behavior