# Credential Request And Lease Broker

**Workplan:** `RAILIANCE-WP-0005`
**Owner:** `railiance-platform`
**Status:** source implementation started

This document records the Railiance credential broker ownership decision and
the first implementation contract for short-lived OpenBao credential leases.

## Decision

`railiance-platform` owns OpenBao credential request, generation, delivery,
audit, and revocation because this repo owns the platform secrets service and
the OpenBao policy surface. The broker may later split into a dedicated
service repo if the implementation grows, but the grant catalog and OpenBao
policy contracts remain platform-owned.

The broker is not a new secret store. It is a controlled request path for
bounded credentials that already belong to OpenBao or adjacent platform
authorities.

## Boundaries

| Concern | Owner | Boundary |
| --- | --- | --- |
| OpenBao mounts, policies, token roles, response wrapping, audit | `railiance-platform` | Generates and revokes bounded credentials. |
| Human login, OIDC, MFA, IAM profile claims | `key-cape` | Authenticates human and service identities. |
| Authorization decision | `flex-auth` | Decides whether an actor may request a grant for a purpose, TTL, audience, and delivery mode. |
| SSH certificate signing | `ops-warden` | Issues SSH certificates only. It does not vend OpenBao tokens, API keys, or provider secrets. |
| Request tracking | State Hub | Stores non-secret metadata only: request ids, actor, grant, purpose, TTL, decision id, lease accessor, status, timestamps, and audit pointers. |
| Agent/runtime consumption | `llm-connect` and callers | Never place secrets in prompts. Consume credentials through local exec injection, response wrapping, service-account auth, or approved local files. |

## Non-Secret Metadata Only

State Hub, workplans, docs, Git, chat, and prompts may contain:

- grant ids such as `ops-warden/warden-sign`;
- requested TTL and bounded max TTL;
- actor and subject ids;
- purpose strings;
- lease handles or accessors when they are not sufficient to use the secret;
- OpenBao audit request ids or timestamps;
- status values such as requested, issued, denied, revoked, or expired.

They must not contain:

- OpenBao root tokens, platform-admin tokens, or wrapped token values;
- unseal shares, recovery codes, private keys, OTP seeds, passwords, or API keys;
- raw bearer tokens in command lines, prompt text, State Hub bodies, or logs;
- screenshots or pasted command output containing secret values.

## Grant Catalog

The catalog lives at:

```text
credential-grants/catalog.yaml
```

Validate it with:

```bash
make credential-grants-validate
```

Every grant entry defines:

- a stable grant id;
- credential type and OpenBao policy set;
- grant class: `self-service`, `approval-required`, or `break-glass`;
- default and max TTL;
- allowed actor types and purpose examples;
- allowed and denied delivery modes;
- audit and revocation expectations.

The first pilot grant is `ops-warden/warden-sign`, which creates a short-lived
OpenBao token with only the `warden-sign` policy.

## Delivery Modes

`exec-env` is the preferred local path. The helper obtains a lease, injects
the credential only into a child process environment, redacts output, and then
revokes or lets the credential expire.

`response-wrap` is for attended handoff. The broker returns a single-use
OpenBao wrapping token instead of the raw credential. The recipient unwraps it
once; a second unwrap must fail.

`local-token-file` is for tools that cannot consume environment variables
cleanly. Files must be mode `0600`, stored under `.local/credential-leases/`,
and removed when the lease is revoked or expires. That directory is ignored by
Git.

`kubernetes-auth` is for in-cluster workloads. Workloads should authenticate
with service-account-bound auth instead of receiving manually handed tokens.

The denied modes are absolute unless a later ADR updates the catalog:

- `chat`
- `state-hub-body`
- `git`
- `command-line-token-argument`
- `llm-prompt`

## Pilot Flow

The target ops-warden smoke path is:

```bash
credential exec --grant ops-warden/warden-sign --ttl 15m -- \
  SMOKE_VAULT=1 /home/worsch/ops-warden/scripts/policy_gate_production_smoke.sh
```

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.

## Implementation Sequence

1. Validate and maintain the non-secret grant catalog.
2. Add bounded OpenBao 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.
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
must remain useful without a live token.