# 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//`) | **`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// # operator API keys, bootstrap creds platform/workloads/// # platform workload secrets tenants/coulomb/ # tenant zero (reference tenant) tenants/coulomb/apps// # application secrets tenants/coulomb/vendors// # vendor integration secrets tenants// # future customer tenants tenants//apps// # customer application secrets ``` Aligns with NetKingdom language: ```text tenant:platform # platform control plane tenant:coulomb # first internal / reference tenant tenant:customer: # future customer tenants tenant:sandbox: # 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--admin` | `tenants//*` 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.