# EXPOSED taint convention (OpenBao KV v2)

Date: 2026-07-16  
Workplan: WARDEN-WP-0026 T05

Mark a secret as **EXPOSED** when it may have landed in a logged or shared context
(agent transcript, chat, CI log). Taint is **advisory**: it does not revoke access
or rotate values. Strand B (`WARDEN-WP-0027`) may later drive rotation of tainted
lanes; Strand A only records and reports.

---

## Custom metadata keys

Set on the KV v2 secret **metadata** (never in secret data values):

| Key | Required | Meaning |
| --- | --- | --- |
| `exposed_at` | yes | ISO-8601 UTC when disclosure was recognized |
| `exposed_version` | recommended | KV version that was (or may have been) disclosed |
| `exposed_reason` | optional | short slug, e.g. `agent-session-kv-get-disclosure` |
| `exposed_ref` | optional | pointer to lessons note / CCR / incident doc |

A lane is **tainted** when `exposed_at` is present and non-empty.

---

## Mark EXPOSED

```bash
bao kv metadata put \
  -custom-metadata=exposed_at=2026-07-16T00:00:00Z \
  -custom-metadata=exposed_version=2 \
  -custom-metadata=exposed_reason=agent-session-kv-get-disclosure \
  -custom-metadata=exposed_ref=history/2026-07-16-credential-disclosure-lessons.md \
  platform/workloads/railiance/backup/offsite-lane
```

## Report taint (no secret values)

```bash
warden taint railiance-backup-offsite-lane
warden taint railiance-backup-offsite-lane --json
# or:
bao kv metadata get platform/workloads/railiance/backup/offsite-lane
```

## Clear taint (after rotation)

After following `warden rotate-guide <id>` and verifying the new version:

```bash
# Rewrite metadata without the exposed_* keys (preserve any other custom_metadata).
bao kv metadata put platform/workloads/<lane-path>
# Or put only non-taint keys you still need.
warden taint <id>   # expect tainted: no
```

---

## Semi-automatic candidates

Reads of high-risk paths from agent/shared identities in the OpenBao audit log
are candidates for marking EXPOSED. Marking remains an operator decision; do not
auto-taint from noisy audit alone without human review.

## See also

- `history/2026-07-16-credential-disclosure-lessons.md`
- `wiki/playbooks/catalog-lane-promotion.md` (capabilities-safe verify)
- OpenBao policy `agent-high-risk-boundary` (WP-0026 T04)