Add HF-WP-0003 workplan for OpenBao KeyCape login overlay

Define upgrade-safe overlay strategy to streamline the bao.coulomb.social login mask as "Sign in with KeyCape" with hidden netkingdom/platform-admin presets.
2026-06-19 20:21:53 +02:00
parent 32c552809b
commit 02f11f8a9b
1 changed files with 322 additions and 0 deletions
--- a/workplans/HF-WP-0003-openbao-keycape-login-overlay.md
+++ 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/<version>/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.