diff --git a/docs/OpenBaoIntroduction.md b/docs/OpenBaoIntroduction.md new file mode 100644 index 0000000..5fd911a --- /dev/null +++ b/docs/OpenBaoIntroduction.md @@ -0,0 +1,275 @@ +# 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/` +- [ ] Streamlined login mask (hide namespace, method, mount, role) +- [ ] `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. \ No newline at end of file