--- 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.