generated from coulomb/repo-seed
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.
This commit is contained in:
322
workplans/HF-WP-0003-openbao-keycape-login-overlay.md
Normal file
322
workplans/HF-WP-0003-openbao-keycape-login-overlay.md
Normal file
@@ -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.
|
||||||
Reference in New Issue
Block a user