secrets-engine/docs/keycape-openbao-consumer-custody.md

# KeyCape `secrets-engine-openbao` consumer custody packet

Prepared 2026-10-06 by secrets-engine for KEY-WP-0037-T02 and
RPF-WP-0035-T02 (proposed CCR-2026-0033 custody child). Tracked in
SECRETS-WP-0012. **Source and documentation only.** No value was generated,
fetched or written; no host, cluster, OpenBao or KeyCape state was changed.
The founder's custody-boundary decision `632a8893-0d6a-4591-a50b-40bbdb798f32`
approves the two-copy boundary, not generation, fetch, delivery, registration
or deployment. Each live step below still needs its own approval.

This packet names the **consumer copy only**: the secrets-engine-owned
mode-0600 file. The authoritative copy (platform KV
`platform/services/keycape/secrets-engine-openbao`, field `CLIENT_SECRET`) and
the issuer-side ESO copy (`sso` Secret `keycape-secrets-engine-openbao-client`,
key `client-secret`) are platform's and KeyCape's. Issuer ESO does not supply
this copy, and nothing here adds a client-side OpenBao reader.

## What the code supports (determined from source)

- secrets-engine is a CLI, not a daemon. The OpenBao JWT login runs inside
  whichever process an operator starts with `--auth service-jwt` (or `auto`
  once `SECRETS_ENGINE_OPENBAO_JWT_LOGIN` is set); it logs in for one command
  and self-revokes (`engine_auth.login_service_jwt`). There is no service
  account, unit file or container for the engine.
- The provider reads the secret from the path in
  `SECRETS_ENGINE_KEYCAPE_CLIENT_SECRET_FILE` (`config.py`), rereads it before
  every exchange and sends it only as HTTP Basic (`service_auth.py`).
- As of this packet the read goes through `read_client_secret_file`, which
  refuses, without exposing the value: a relative path; a missing file; any
  symlink or non-canonical path component; a non-regular file; a file or
  parent directory not owned by the effective user; any group/other mode bit on
  the file (must be 0600) or its parent (must be 0700); a path inside a Git
  worktree; empty content; content that is not exactly one token. Before this
  change only the file mode, worktree and empty checks existed. The approval
  profile shares the same provider and therefore the same checks.
- `secrets-engine service-auth check-secret-file [--path P] [--json]` runs those
  checks and prints check names and pass/fail only — never the value, its
  length or any hash. Exit 0 = accepted, 1 = refused. This is the bounded
  validation interface RPF-WP-0035-T02 asked for.

## Consumer coordinates

| Coordinate | Value | Basis |
| --- | --- | --- |
| Host | Operator workstation (the WSL2 Linux host where every documented live secrets-engine OpenBao operation runs against `BAO_ADDR=https://bao.coulomb.social`) | Documented practice; **founder decision D1** |
| OS user / owner | `worsch`, file and parent `worsch:worsch` | The account that runs the CLI; **founder decision D2** |
| File | `/home/worsch/.secrets-engine/keycape/secrets-engine-openbao.client-secret` | Follows existing `~/.secrets-engine/bootstrap/` convention |
| File mode | `0600`, regular file, single token, no trailing data other than one newline | Enforced by code |
| Parent | `/home/worsch/.secrets-engine/keycape`, `0700`, owned by `worsch` | Enforced by code |
| Grandparent | `/home/worsch/.secrets-engine` exists today as `0755` with only `0700` children; not changed by this packet | Observed metadata only |
| Git | Outside every worktree (`/home/worsch` and `~/.secrets-engine` are not worktrees) | Enforced by code |
| Storage | Persistent ext4 home, not tmpfs | **Founder decision D3** |
| Config reference | `SECRETS_ENGINE_KEYCAPE_CLIENT_SECRET_FILE=<file above>` | `config.py` |
| Companion config | `SECRETS_ENGINE_KEYCAPE_TOKEN_URL=https://kc.coulomb.social/token`, `SECRETS_ENGINE_KEYCAPE_ISSUER=https://kc.coulomb.social`, `SECRETS_ENGINE_OPENBAO_JWT_LOGIN=/home/worsch/.secrets-engine/keycape/openbao-jwt-login.yaml` (non-secret `mount`/`role: secrets-engine-openbao`/`bound_issuer`, content published by platform) | `engine_auth.py`, platform design |

One host and one file. A second host or user would be a third copy and needs
its own approval; the engine has no mechanism that distributes the file.

## Delivery (platform custody → this file)

Attended operator path, executed on the host above as `worsch`, inside the
platform-owned custody child of CCR-2026-0033:

1. Preconditions: founder approval of the exact custody child; platform's
   operator OpenBao session for the KV write; `umask 077`; shell tracing and
   credential-bearing debug logs off.
2. The custody child generates one random value **in process memory** and
   compare-before-writes it to the authoritative KV field. If that write fails,
   no consumer file is written.
3. In the **same process**, it writes the consumer copy: create the parent
   with `0700` if absent (refuse if it exists with other owner/mode); open a
   new temp file in that directory with `O_CREAT|O_EXCL|O_WRONLY`, mode `0600`;
   write, `fsync`, `rename` onto the final path; `fsync` the directory. The
   value never appears in argv, environment, stdout/stderr, logs, Git or the hub.
4. It then runs `secrets-engine service-auth check-secret-file --json` and
   records only that result plus non-secret IDs in the native receipt.

No client-side read of OpenBao is used or required: the consumer copy is
written from the same in-memory value that creates the authoritative version.
If the founder rejects same-process delivery, the only alternative is a
separately admitted, single-path client-side reader (as RPF-WP-0035-T06 does
for the approval client); this packet does not request one.

Ownership: platform owns generation, the authoritative write and the delivery
code path; secrets-engine owns these destination coordinates, the acceptance
check and the file's lifecycle on the host.

## Detecting a failed delivery

- `check-secret-file` exits 1 and names the failing check (missing, mode,
  owner, parent, symlink, worktree, empty). The receipt must carry `ok: true`.
- At use time the same checks refuse the exchange with `ProvisioningError`
  (exit 6); `service-jwt` never falls back to bootstrap, `BAO_TOKEN` or AppRole.
- A value that is well-formed but does not match the issuer is detectable only
  by the first live exchange (KEY-WP-0037-T04): KeyCape answers HTTP 401 and
  the engine reports `KeyCape token exchange failed with HTTP 401`. No hash or
  fingerprint of the value is recorded to compare copies; that is deliberate.
- Crash between the KV write and the rename: the KV version exists and the
  consumer file does not (or a stale temp file remains in the 0700 directory).
  Recovery is a fresh rotation, not a KV read; the operator removes the exact
  temp file after inspecting its name and metadata only.

## Rotation and revocation

| Event | Owner | Action |
| --- | --- | --- |
| Generation / authoritative version | railiance-platform | New KV version via the custody child |
| Issuer pickup | KeyCape / NetKingdom | ESO refresh plus KeyCape restart (secrets load at startup) |
| Consumer copy replacement | secrets-engine (file), executed in platform's attended child | Atomic rename as above, then `check-secret-file` |
| Disable on compromise | KeyCape / NetKingdom | Remove or disable the registration first |
| Retire versions | railiance-platform | Destroy/retire per CCR |
| Remove consumer copy | secrets-engine operator | See rollback below |

KeyCape holds one secret per client, so rotation has a cutover window: hold
the new value in the attended process, replace the consumer file only after
the issuer reload is confirmed, and accept that exchanges fail closed (401) in
between. Already-issued JWTs live at most 15 minutes; OpenBao tokens from this
login are self-revoked per command and bounded by platform's TTL/use limits.
No instant JWT recall is claimed.

Rotation cadence is **founder decision D4**.

## Rollback and cleanup

1. Unset `SECRETS_ENGINE_KEYCAPE_CLIENT_SECRET_FILE` (and the JWT login
   contract variable) in the operator environment.
2. Remove the exact file path (no recursive removal); `rmdir` the parent only
   if it is empty.
3. Verify with `check-secret-file --path <file>`: it must exit 1 on `exists`.
4. Record cleanup status only. Unlink on ext4 is not secure erasure and not
   revocation; revocation is the KeyCape and platform steps above.

## Founder / owner decisions (with recommendation)

- **D1 Host.** Recommended: the operator workstation only. Alternative:
  railiance01, which has no documented secrets-engine OpenBao operator use and
  would need its own user and path decision.
- **D2 OS user.** Recommended: the operator account `worsch`, since the engine
  runs only as that user's CLI. A dedicated system user only makes sense once
  an unattended engine runtime exists, and no source supports one today.
- **D3 Persistence.** Recommended: persistent home storage. tmpfs would
  require re-delivery after every reboot, and every re-delivery would need either
  a rotation or an unadmitted client-side KV read. Open owner question: whether
  any workstation backup or sync tool covers `~/.secrets-engine`. If one does,
  exclude it there before delivery.
- **D4 Rotation cadence.** Recommended: event-driven (compromise, host or user
  change, operator departure) plus a 90-day scheduled rotation run through the
  same attended child. Platform's CCR sets the binding value.

## Not established

No registration, issued JWT, KV version, ESO Secret or consumer file exists
by implication of this packet. Code tests use synthetic values only and prove
file acceptance/refusal, not live delivery, issuer match or OpenBao login.