---
id: w4/m5/t001
title: "ADR docs/ADR013-secrets.md: OpenBao for tenant credentials — alternatives, storage backend, unseal strategy"
worker: worker4
status: done
estimate: 35m
depends_on: []
---

## Objective

Write the ADR that anchors the tenant-secrets substrate: why OpenBao (Linux Foundation fork of Vault, MPL-2.0 — passes the same governance test as Ory/CNPG in docs/ADR012-auth.md §1, whereas Vault itself is BUSL), what it stores (tenant runtime credentials, explicitly NOT the platform's own deploy secrets — that's w1/m7 t003), which storage backend (integrated Raft on a PVC vs a CNPG Postgres cluster like `kratos-db`/`hydra-db`), and the unseal strategy (static unseal keys held out-of-band in `.env`, re-unseal on pod restart via script, vs auto-unseal options).

## Context

- Pattern to follow: `docs/ADR012-auth.md` (the Kratos+Hydra ADR) — context / decision / verification / alternatives / consequences, mermaid diagram.
- Alternatives to reject with reasons: HashiCorp Vault (BUSL license), External-Secrets-Operator-only (sync tool, not a store), Infisical (heavier, less standard API), plain k8s Secrets (etcd plaintext, no versioning/policy/audit).
- The consumer story: bex-api (m6) authenticates via the Kubernetes auth method and reads/writes `tenants/<tenant>/services/<app>/env`.
- Boundary statement: tenant runtime credentials ≠ platform git secrets (w1/m7 t003 sealed-secrets/SOPS).

## Steps

1. Read `docs/ADR012-auth.md` and `docs/ADR009-postgresql-management.md` §1 for the governance-test framing.
2. Draft `docs/ADR013-secrets.md` with context, decision (OpenBao; chosen storage backend; unseal strategy), path/tenancy layout (`tenants/` KV v2), alternatives considered, consequences (unseal-on-restart operational cost, backup obligations joining w1/m7).
3. Add the docs-index line in `CLAUDE.md` (or defer to t006 if cleaner — but the file must exist now).
4. `npx prettier@3.4.2 --write "**/*.md"`.

## Files

- `docs/ADR013-secrets.md` (new)
- `CLAUDE.md` (docs index)

## Acceptance criteria

- [ ] ADR records explicit decisions for: OpenBao vs alternatives, storage backend, unseal strategy, tenancy path layout.
- [ ] The w1/m7-t003 boundary (platform git secrets vs tenant runtime credentials) is stated.
- [ ] Prettier-clean.

## Out of scope

- Any deployment YAML (t002) or scripts (t003–t005).
