diff --git a/workplans/HF-WP-0003-openbao-keycape-login-overlay.md b/workplans/HF-WP-0003-openbao-keycape-login-overlay.md new file mode 100644 index 0000000..05aa2aa --- /dev/null +++ b/workplans/HF-WP-0003-openbao-keycape-login-overlay.md @@ -0,0 +1,322 @@ +--- +id: HF-WP-0003 +type: workplan +title: "Streamline OpenBao login screen for KeyCape sign-in" +domain: helix_forge +repo: helix-forge +status: ready +owner: codex +topic_slug: openbao-keycape-login-overlay +created: "2026-06-19" +updated: "2026-06-19" +planning_priority: medium +planning_order: 3 +related_repos: + - railiance-platform + - net-kingdom + - helix-forge +related_workplans: + - HF-WP-0002 +--- + +# Streamline OpenBao login screen for KeyCape sign-in + +## Goal + +Replace the raw OpenBao login mask at `https://bao.coulomb.social` with a +streamlined operator experience: + +```text +Sign in with KeyCape +[ Sign in ] +``` + +Hidden presets (not user-editable): + +| Field | Preset | +| --- | --- | +| Namespace | blank (root) | +| Method | OIDC | +| Mount path | `netkingdom` | +| Role | `platform-admin` | + +Operators should no longer need to understand OpenBao auth-mount semantics +to sign in. The `keycape` mount remains a server-side compatibility alias but +must not appear in the default login mask. + +## Context + +`HF-WP-0002` exposed the OpenBao browser UI and wired KeyCape OIDC through +the `netkingdom` mount with the `platform-admin` role. Login works end to end, +but the stock OpenBao UI still shows namespace, method, mount path, and role +fields that confuse platform operators. + +Architectural intent is captured in: + +- `helix-forge/docs/OpenBaoIntroduction.md` — field semantics and target UX +- `helix-forge/INTENT.md` — platform custody principle + +OpenBao ships UI static assets inside the container image +(`quay.io/openbao/openbao:2.5.4` today, chart `openbao/openbao` `0.28.2`). +There is **no supported API** to hide login fields or set auth defaults. The +only documented `/sys/config/ui` endpoint configures **response headers**, not +login form behaviour. Upstream feature request +[openbao/openbao#2936](https://github.com/openbao/openbao/issues/2936) proposes +a `custom-css` API but is not implemented yet. + +Therefore customization must be an **overlay layer we own**, applied at deploy +time — never hand-edits inside the running pod or vendor image layers. + +## Upgrade-safe overlay principle + +All login-mask changes live in `railiance-platform` as a versioned overlay +package. Upgrading OpenBao image or Helm chart must **not** require hunting +for forgotten in-container edits. + +### Required properties + +1. **Source of truth in Git** — overlay assets, apply script, and version pin + live in `railiance-platform`, not on cluster nodes. +2. **Pinned to upstream UI version** — overlay metadata records the OpenBao + image tag (and optionally chart version) it was built against. +3. **Idempotent apply** — `make openbao-deploy` (or a dedicated target) applies + the overlay every time; no manual kubectl steps for routine deploys. +4. **Documented reapply path** — after an OpenBao bump, operators follow a + short runbook: diff upstream login assets, refresh overlay patches, run + verifier, redeploy. +5. **No secret material** — overlay contains only public CSS/JS/HTML transforms + and preset auth parameters already visible in docs. + +### Proposed overlay layout (implementation target) + +```text +railiance-platform/helm/openbao-ui-overlay/ + README.md # mechanism choice, reapply runbook entry point + VERSION # openbao image tag this overlay targets + presets.json # namespace, method, mount, role defaults + overlay.css # hide fields, KeyCape branding + overlay.js # pre-fill presets, single-button OIDC redirect + apply-overlay.sh # idempotent apply invoked from deploy pipeline + patches/ # optional unified diffs against upstream bundles + 2.5.4/ + manifest.sha256 # hash of upstream login asset for drift detection +``` + +Exact delivery mechanism is decided in T01. Candidates, in preference order +until upstream ships native customization: + +| Mechanism | Upgrade resilience | Notes | +| --- | --- | --- | +| **Traefik response injection** | High — no pod filesystem mutation | Inject `overlay.css` / `overlay.js` on `/ui/*` HTML responses via middleware or plugin | +| **Init-container emptyDir overlay** | Medium — reapply on every pod start | Copy overlay into shared volume over upstream static path if chart supports `extraVolumes` | +| **Post-start patch Job** | Medium — must rerun on recreate | One-shot Job patches files; fragile if path layout changes | +| **Upstream `/sys/config/ui/custom-css`** | Highest when available | Track #2936; migrate off injection when released | + +Whichever mechanism wins, keep the **same overlay asset files** so only the +apply plumbing changes when we migrate upstream. + +## Security boundary + +- Overlay is cosmetic and preset-only; it must not weaken auth or bypass + KeyCape/MFA. +- Preset mount `netkingdom` and role `platform-admin` remain enforced server + side by OpenBao OIDC configuration (`HF-WP-0002`). +- Do not expose root-token login, token auth, or additional auth methods in the + streamlined mask. +- Overlay injection must use Subresource Integrity or same-origin-only script + loading where possible; avoid loading third-party assets. +- No OpenBao tokens, OIDC secrets, or secret values in overlay files or Git. + +## Proposed implementation + +1. Spike overlay delivery options against the live chart and Traefik ingress. +2. Create the overlay package with KeyCape branding and hidden-field presets. +3. Wire overlay apply into `make openbao-deploy`. +4. Add an automated verifier that checks the public login page shape. +5. Document the OpenBao upgrade / overlay-reapply runbook. +6. Roll out to `bao.coulomb.social` and confirm attended KeyCape login still + works. + +## Tasks + +### T01 - Spike overlay delivery mechanism + +```task +id: HF-WP-0003-T01 +status: todo +priority: high +target_repo: railiance-platform +``` + +Evaluate Traefik injection, init-container volume overlay, and chart extension +points against `openbao-values.yaml` and the running `openbao` `0.28.2` / +`2.5.4` deployment. + +Record: + +- chosen mechanism and why alternatives were rejected; +- exact upstream asset paths / HTML hooks used by the login page; +- `manifest.sha256` or equivalent fingerprint for drift detection after upgrades. + +Done when a short decision note exists in +`railiance-platform/helm/openbao-ui-overlay/README.md` and the overlay +directory skeleton is committed. + +--- + +### T02 - Implement overlay assets and presets + +```task +id: HF-WP-0003-T02 +status: todo +priority: high +target_repo: railiance-platform +depends_on: HF-WP-0003-T01 +``` + +Create `overlay.css`, `overlay.js`, and `presets.json` implementing: + +- hidden namespace, method, mount path, and role inputs; +- visible “Sign in with KeyCape” copy and single sign-in control; +- programmatic defaults: blank namespace, OIDC, mount `netkingdom`, role + `platform-admin`; +- no `keycape` mount in the default mask. + +Assets must be plain static files suitable for reapplication across mechanism +changes. + +Done when a local/static preview or dry-run apply shows the intended mask +against the pinned `2.5.4` login markup. + +--- + +### T03 - Wire overlay into OpenBao deploy pipeline + +```task +id: HF-WP-0003-T03 +status: todo +priority: high +target_repo: railiance-platform +depends_on: HF-WP-0003-T02 +``` + +Integrate `apply-overlay.sh` into the OpenBao deployment path so +`make openbao-deploy` applies the overlay idempotently. + +Update as needed: + +- `helm/openbao-values.yaml` (extra volumes, init containers, or annotations); +- `helm/openbao-middleware.yaml` (if Traefik injection is chosen); +- `Makefile` `openbao-deploy` / `openbao-dry-run` targets. + +`VERSION` must track the OpenBao image tag in `openbao-values.yaml`. + +Done when `make openbao-dry-run` shows overlay resources and a staging or +production deploy applies them without manual steps. + +--- + +### T04 - Add login-mask verifier + +```task +id: HF-WP-0003-T04 +status: todo +priority: medium +target_repo: railiance-platform +depends_on: HF-WP-0003-T03 +``` + +Add `scripts/openbao-verify-login-overlay.sh` (or extend +`openbao-verify-authenticated.sh`) to assert on the public login page: + +- “Sign in with KeyCape” (or approved copy) is present; +- raw namespace / method / mount / role controls are not visible to users; +- OIDC redirect still targets `auth/netkingdom/oidc` with role + `platform-admin`. + +Include a `--check-upstream-drift` mode that compares the live upstream login +asset fingerprint to `patches//manifest.sha256` and warns when an +OpenBao bump likely requires overlay refresh. + +Done when the verifier passes against the deployed overlay and fails clearly +when overlay is missing or upstream markup drifts. + +--- + +### T05 - Document upgrade and reapply runbook + +```task +id: HF-WP-0003-T05 +status: todo +priority: medium +target_repo: railiance-platform +depends_on: HF-WP-0003-T04 +``` + +Document in `railiance-platform/docs/openbao.md` and +`helm/openbao-ui-overlay/README.md`: + +- streamlined login operator path (“Sign in with KeyCape” only); +- overlay package layout and version pinning; +- **reapply checklist** when bumping OpenBao image or chart: + 1. update image tag in `openbao-values.yaml`; + 2. run drift check / inspect upstream login assets; + 3. refresh `overlay.css` / `overlay.js` / `patches/` if hooks changed; + 4. bump `VERSION` and `manifest.sha256`; + 5. run `openbao-verify-login-overlay.sh`; + 6. `make openbao-deploy`; +- pointer to upstream #2936 for eventual migration to native custom CSS. + +Cross-link from `helix-forge/docs/OpenBaoIntroduction.md` phased checklist +item “Streamlined login mask”. + +Done when the next operator can reapply the overlay after an OpenBao upgrade +without rediscovering the approach. + +--- + +### T06 - Live rollout and attended login verification + +```task +id: HF-WP-0003-T06 +status: todo +priority: high +depends_on: HF-WP-0003-T05 +``` + +Deploy the overlay to `https://bao.coulomb.social` and perform attended +verification: + +1. Open the login page — only KeyCape-branded sign-in is shown. +2. Complete KeyCape OIDC login with MFA. +3. Confirm `platform-admin` session and metadata path access still work. +4. Run `openbao-verify-login-overlay.sh` against production. + +Done when production login matches the target UX and verification scripts pass. +Record only non-secret evidence in this workplan. + +--- + +## Acceptance criteria + +This workplan is complete when: + +1. Operators see “Sign in with KeyCape” with a single sign-in action at + `bao.coulomb.social`; namespace, method, mount, and role are not exposed. +2. Login still authenticates through `auth/netkingdom/oidc` and + `platform-admin` with KeyCape MFA. +3. Overlay assets and apply logic live entirely in `railiance-platform` Git. +4. `make openbao-deploy` applies the overlay without manual pod edits. +5. A documented reapply runbook exists for OpenBao image/chart upgrades. +6. An automated verifier catches missing overlay and upstream UI drift. + +## Notes + +- Primary implementation repo: `railiance-platform` (Helm, overlay, verifiers, + runbooks). +- Intent and field semantics remain in `helix-forge` (`OpenBaoIntroduction.md`). +- OIDC mount/role configuration is already live from `HF-WP-0002`; this + workplan changes presentation only, not auth policy. +- When OpenBao ships native UI customization (#2936), prefer migrating to it + and retiring injection/pod-overlay plumbing while keeping the same preset + values and branding assets where possible. \ No newline at end of file