coulomb/helix-forge
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
02f11f8a9b85520da047daf1458cfbab26896e68
helix-forge/workplans/HF-WP-0003-openbao-keycape-login-overlay.md
tegwick 02f11f8a9b 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

11 KiB
Raw Blame History

id, type, title, domain, repo, status, owner, topic_slug, created, updated, planning_priority, planning_order, related_repos, related_workplans
id type title domain repo status owner topic_slug created updated planning_priority planning_order related_repos related_workplans
HF-WP-0003 workplan Streamline OpenBao login screen for KeyCape sign-in helix_forge helix-forge ready codex openbao-keycape-login-overlay 2026-06-19 2026-06-19 medium 3
railiance-platform
net-kingdom
helix-forge
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:

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

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

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

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

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

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

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

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 View Git Blame Copy Permalink