Skip to content
SENS Platform Docs

Secret Management

OpenBao is the authoritative store for platform runtime secrets. The sens-platform-ops portal is the normal human interface for catalog-bound create, reveal, update, soft-delete, history, restore, and delivery operations. Direct OpenBao UI or API access is reserved for documented break-glass recovery.

Ops portal -> catalog + role matrix + TOTP -> OpenBao KV v2
OpenBao -> Kubernetes Auth -> namespace-scoped ESO -> existing Kubernetes Secrets

Security boundaries

Section titled “Security boundaries”

The three KV-v2 mounts are sens-test, sens-production, and sens-operations. They use check-and-set, retain at most 20 versions, and do not grant the portal destroy or metadata-delete rights. One catalog group is one KV document. Field-level create, update, delete, and restore are implemented as server-side read-modify-write operations with the expected group version.

The versioned catalog is sens-platform-infra/config/secret-management/catalog.v1.yaml. It contains names, paths, required-state metadata, and delivery targets, but no values. An unknown path or key is rejected. A new secret therefore requires a reviewed Git change to the catalog, application schema, tests, and documentation before a value can be entered.

Viewer users see only value-free ESO and SecretStore delivery health. Admins initially have full access in Test and read/list access in Production and Operations. SuperAdmins initially have all five actions and can change the revisioned role matrix. Missing matrix entries deny access. Production reveal, create, update, soft-delete, and restore require a fresh, action-bound TOTP step-up. Production deletion additionally requires the exact environment, group ID, and key ID confirmation.

Runtime delivery

Section titled “Runtime delivery”

There are four namespace-scoped ESO identities:

  • external-secrets-test in sens-test;
  • external-secrets-production in sens-production;
  • external-secrets-argocd in argocd;
  • external-secrets-monitoring in monitoring.

Each identity is bound to its exact namespace, ServiceAccount, audience openbao, and read-only paths. ESO extracts complete KV-v2 group documents and keeps the existing Kubernetes Secret names, refreshInterval: 1m, orphan creation, merge deletion, and Reloader behavior. Applications read Kubernetes Secrets only; they do not call OpenBao.

GitHub Actions Secrets are delivered by a constrained controller AppRole. The controller queue stores only catalog ID, target ID, expected version, actor ID, correlation ID, and idempotency key. It fetches the current value immediately before delivery. GitHub exposes only existence and update time after delivery. Coolify remains a manual, audited handoff.

Observability exclusion

Section titled “Observability exclusion”

Secret values, lengths, hashes, TOTP codes, request bodies, OpenBao responses, and paths are prohibited from Pino logs, VictoriaLogs, Sentry, PostHog, metrics, Valkey, controller commands, URLs, and browser caches. Secret responses use Cache-Control: no-store, private, Pragma: no-cache, and Vary: Cookie. Reveal values are removed after 60 seconds, tab hiding, navigation, or dialog closure. OpenBao audit devices use HMAC protection and are retained on a dedicated volume rather than forwarded as general logs.

Sentry DSNs, PostHog project keys, hosts, project IDs, feature flags, sampling rates, and environment names remain non-secret deployment configuration. SENTRY_AUTH_TOKEN, OpenBao AppRole SecretIDs, database credentials, auth keys, SMTP passwords, API tokens, and SENS_PRODUCT_ANALYTICS_ID_HMAC_KEY are secrets.

Local development

Section titled “Local development”

The normal local workflow uses an ignored .env. Authorized developers may inject one Test group into one child process through the Ops portal without a temporary file:

Terminal window
cd ../sens-platform-ops
pnpm secrets:run \
  --environment test \
  --group test-runtime-platform-api \
  --cwd ../sens-platform \
  -- pnpm --filter @sens-platform/platform-api dev

The wrapper prompts interactively for login and TOTP, never prints names or values, and rejects Production and Operations.

Availability and production backup gate

Section titled “Availability and production backup gate”

An OpenBao outage pauses new ESO synchronization; already synchronized Kubernetes Secrets remain until changed by another actor. A sealed instance, audit failure, Raft failure, and non-ready ESO object are alerted.

Automated OpenBao snapshots and restore probes are deliberately disabled in the current Test and development phase. The data and audit volumes are not backups; if they are lost, the environment is rebuilt from Git and freshly entered secret values. Real production use is blocked until a separately reviewed contract provides an external encrypted destination, retention, RPO/RTO, monitoring, a value-free runbook, and a successfully tested isolated restore. The current operational commands and this gate are maintained in sens-platform-infra/docs/openbao-operator-guide.md.