helix-forge/docs/OpenBaoIntroduction.md

# OpenBao in the HelixForge / NetKingdom / Coulomb Universe

This document anchors **why** OpenBao exists in the platform, **what** it is
responsible for, and **where** we are headed. It is written for operators,
architects, and builders working across HelixForge intent, NetKingdom security
architecture, and Coulomb as the first reference tenant.

Operational runbooks and deployment detail live in adjacent repos. This file
is the conceptual home in `helix-forge`.

| Topic | Canonical detail |
| --- | --- |
| Deployment, Helm, break-glass | `railiance-platform/docs/openbao.md` |
| Platform vs tenant security model | `net-kingdom/docs/platform-identity-security-architecture.md` |
| KeyCape OIDC wiring | `net-kingdom/sso-mfa/k8s/keycape/README.md` |
| Credential routing for agents | `helix-forge/AGENTS.md` (Credential and access routing) |

---

## Purpose

OpenBao is the **platform secrets service**: the place where sensitive material
is stored, accessed under policy, audited, and delivered to trusted actors.

HelixForge describes *how capabilities evolve*. NetKingdom describes *who may
act and under what trust model*. Coulomb is *tenant zero* — the first internal
tenant on that platform. OpenBao sits in the **custody plane**:

- It holds API keys, database passwords, signing material, operator credentials,
  and workload secrets.
- It does **not** replace identity (KeyCape), application authorization
  (flex-auth), or general configuration in Git.

The goal is **IT security from inception to production**: secrets enter custody
early, move through governed paths, and reach production workloads without
living in Git, chat, State Hub, or ad hoc env files.

---

## What OpenBao is — and is not

| OpenBao is | OpenBao is not |
| --- | --- |
| A centralized secret store with policy and audit | An identity provider |
| A broker for dynamic credentials (DB, PKI, SSH, …) | An application authorization engine |
| A delivery point for workloads (API, CSI, ESO) | A tenant registry or user directory |
| The system of record for **secret values** | A substitute for SOPS/age in Git-at-rest bootstrap |

**Privacy of secrets is achieved through path layout, identity binding, and
least-privilege policies** — not merely by storing data inside OpenBao.

---

## Place in the stack

```text
Human / service / agent principal
        |
        v
NetKingdom IAM Profile (identity semantics)
        |
        +-- KeyCape (+ privacyIDEA MFA)  -->  humans, OIDC login
        |
        +-- flex-auth (+ Topaz)            -->  application authorization
        |
        v
OpenBao (custody)                        -->  secret paths, policies, audit
        |
        v
Workloads (K8s pods, jobs, operators)    -->  consume secrets via scoped auth
```

- **KeyCape** answers: who is this principal, which groups/tenants apply?
- **flex-auth** answers: may this principal perform action A on resource R?
- **OpenBao** answers: may this principal read or write secret path P?

End users of tenant applications should normally **not** browse OpenBao. They
authenticate to apps; apps (or operators) fetch secrets through scoped machine
or operator identity.

---

## Browser login — what the UI fields mean

Operators reach the UI at `https://bao.coulomb.social`. The raw OpenBao login
form exposes four fields. For platform operators today, most should be **hidden
presets**, not user choices.

| UI field | Technical meaning | User/admin mental model |
| --- | --- | --- |
| **Namespace** | OpenBao-internal partition (multi-tenancy inside one cluster) | Leave **blank** = the single root vault we use today |
| **Method** | Auth backend type (OIDC, token, kubernetes, …) | **OIDC** = “Sign in with KeyCape” |
| **Mount path** | Which auth backend handles login (`auth/<mount>/`) | **`netkingdom`** = platform identity plane login door |
| **Role** | OIDC auth role → maps claims to OpenBao **policies** | **`platform-admin`** = platform operator custody |

### Common misconceptions

1. **Namespace ≠ tenant/vendor.** Coulomb, customers, and HelixForge are not
   selected in the namespace box. Tenant scope is expressed in **identity
   claims, KV paths, and policies**.
2. **Mount path ≠ repo, domain, or user group.** It is only *which configured
   login door* to use. `netkingdom` and legacy `keycape` are aliases to the
   same KeyCape-backed OIDC config today.
3. **`platform-admin` ≠ namespace root.** Blank namespace means root namespace;
   `platform-admin` is an **operator policy** granting access to paths like
   `platform/*`.
4. **There is no generic `user` login role yet.** Only `platform-admin` is wired
   for human OIDC. Narrower roles come with tenant onboarding.

### Streamlined operator experience (target)

```text
Sign in with KeyCape
[ Sign in ]
```

Hidden presets: namespace blank, method OIDC, mount `netkingdom`, role
`platform-admin`. Retire `keycape` from the default mask once compatibility
notes are no longer needed.

Do **not** use the root token through the browser UI.

---

## Multi-entity secret ownership

NetKingdom targets a platform that is **multi-tenant, multi-vendor,
multi-application, multi-customer, and multi-user**. Many of those entities need
secrets. **Yes, OpenBao can hold them all** — with explicit ownership rules.

OpenBao does not natively understand “tenant” or “vendor”. We encode ownership:

| Layer | Responsibility |
| --- | --- |
| **Path convention** | Every secret has an unambiguous owner prefix |
| **Identity** | KeyCape groups, K8s service accounts, scoped tokens |
| **Policy** | Least privilege: which paths each identity may touch |
| **Delivery** | ESO / CSI / API — only the intended workload receives the value |
| **Audit** | Who accessed which path (values are not logged) |

### Target path taxonomy (evolving)

```text
platform/                              # platform control plane only
platform/operators/<service>/          # operator API keys, bootstrap creds
platform/workloads/<ns>/<sa>/<name>    # platform workload secrets

tenants/coulomb/                       # tenant zero (reference tenant)
tenants/coulomb/apps/<app>/            # application secrets
tenants/coulomb/vendors/<vendor>/      # vendor integration secrets

tenants/<customer>/                    # future customer tenants
tenants/<customer>/apps/<app>/         # customer application secrets
```

Aligns with NetKingdom language:

```text
tenant:platform          # platform control plane
tenant:coulomb           # first internal / reference tenant
tenant:customer:<name>   # future customer tenants
tenant:sandbox:<name>    # sandboxes
```

### Actor → access (target matrix)

| Actor | Auth path | Typical secret scope |
| --- | --- | --- |
| Platform operator | KeyCape OIDC → `platform-admin` | `platform/*` (narrow over time) |
| Platform auditor | KeyCape OIDC → `platform-readonly` | metadata, no secret reads |
| Tenant admin (future) | KeyCape OIDC → `tenant-<id>-admin` | `tenants/<id>/*` only |
| Workload (pod) | Kubernetes auth → per-SA role | one path prefix, read-only where possible |
| Break-glass | offline/root procedures | emergency only, audited |

Tenant administrators must **not** be able to alter platform root trust,
global identity config, or policies governing the platform itself.

---

## Workloads

A **workload** is a **running piece of software** that does a job without a
human at the keyboard: API server, worker, cron job, operator script running as
a service account.

| Term | Meaning |
| --- | --- |
| **User** | Human (e.g. platform operator via KeyCape) |
| **Application** | Software product (Inter-Hub, a tenant app) |
| **Workload** | Running instance of that application in the cluster |
| **Service account** | The workload's machine identity in Kubernetes |

Humans use **OIDC + MFA**. Workloads use **Kubernetes auth** (or tightly scoped
tokens) so secrets are delivered automatically and least-privilege.

```text
Human operator  →  OIDC (KeyCape)     →  platform-admin  →  platform/operators/...
Inter-Hub pod   →  Kubernetes auth    →  inter-hub-role  →  platform/workloads/inter-hub/...
Tenant app pod  →  Kubernetes auth    →  tenant-app-role →  tenants/coulomb/apps/myapp/...
```

---

## Current state vs direction

### Today (bootstrap / platform phase)

- Single OpenBao cluster on Railiance01, root namespace only.
- Browser UI at `bao.coulomb.social` with KeyCape OIDC and `platform-admin`.
- Platform operator paths under `platform/` (e.g. Inter-Hub and ops-hub operator
  keys).
- Humans for attended custody; workloads largely still catching up on
  Kubernetes auth + ESO/CSI delivery.
- `platform-admin` is intentionally broad for bootstrap; it must shrink as
  tenant paths appear.

### Direction (inception → production)

1. **Platform custody** — operator keys, shared infra, break-glass discipline.
2. **Tenant paths** — `tenants/coulomb/*` for first internal tenant apps.
3. **Workload auth** — per-namespace, per-service-account OpenBao roles.
4. **Human role split** — readonly, tenant-admin, no default `platform-admin`
   for routine tenant work.
5. **Customer tenants** — isolated paths and policies; optional OpenBao
   namespaces later if compliance requires stronger partitions.

HelixForge capability work should treat **secret path + policy + delivery** as
part of a capability's security contract, not an afterthought.

---

## Rules of custody (non-negotiable)

- Secret values, root tokens, unseal shares, and display-once API keys **never**
  go into Git, State Hub, workplans, chat, or logs.
- Display-once material is stored at the **approved OpenBao path** immediately,
  then removed from temp files.
- Prefer **metadata-only inspection** in the UI when checking whether a secret
  exists.
- Route credential *ownership* questions through `warden route` (see
  `helix-forge` agent instructions); ops-warden issues SSH certs only, not
  vault secrets.

---

## Phased rollout checklist

Use this as a maturity ladder, not a single big bang.

- [x] OpenBao deployed; audit enabled; root token retired or break-glass only
- [x] Human operator path: KeyCape OIDC, MFA, browser UI
- [x] Platform operator secrets under `platform/operators/`
- [x] Streamlined login mask (hide namespace, method, mount, role) — `HF-WP-0003`, overlay in `railiance-platform/helm/openbao-ui-overlay/`
- [ ] `platform-readonly` role for auditors
- [ ] Path tree for `tenants/coulomb/`
- [ ] Kubernetes auth roles for platform workloads
- [ ] Tenant-scoped OIDC roles (no `platform-admin` for tenant admins)
- [ ] External Secrets Operator / CSI delivery for app charts
- [ ] Per-tenant audit review practices
- [ ] Optional OpenBao namespaces for high-isolation customers

---

## Summary

OpenBao is how the Coulomb / NetKingdom platform keeps secrets **private to
their owners** at scale: one vault, many owners, enforced by naming, identity,
and policy. HelixForge supplies the evolution loop; NetKingdom supplies the
trust model; Coulomb proves the first tenant path. OpenBao is the custody layer
that lets that model survive contact with production.

**One line:** Sign in with KeyCape for platform custody; encode tenant and
application ownership in paths and policies; let workloads authenticate as
themselves — so secrets stay out of Git and in governed hands from inception
through production.