# OpenBao KeyCape login overlay

Streamlines the browser login mask at `https://bao.coulomb.social` to a single
**Sign in with KeyCape** action. Namespace, auth method, mount path, and role
are preset in `presets.json` and hidden by `overlay.css` / `overlay.js`.

## Mechanism (T01 decision)

OpenBao ships UI assets inside the container image. There is no supported API
to customize the login form ([`/sys/config/ui`](https://openbao.org/api-docs/system/config-ui/)
only configures response headers).

We use an **nginx UI gateway** (`openbao-ui-gateway`) that:

1. Proxies all traffic to `openbao.openbao.svc.cluster.local:8200`.
2. Serves overlay assets from a ConfigMap at `/ui/platform-overlay/`.
3. Injects `overlay.css` and `overlay.js` into HTML responses via `sub_filter`.

Overlay assets live entirely in this directory. Upgrading OpenBao does not
require hand-editing files inside the OpenBao pod.

Track upstream [openbao/openbao#2936](https://github.com/openbao/openbao/issues/2936)
for native custom CSS. When available, keep `presets.json` and branding assets
and retire nginx `sub_filter` injection if the upstream API covers the same
behaviour.

## Layout

| File | Purpose |
| --- | --- |
| `VERSION` | OpenBao image tag this overlay targets (`openbao-values.yaml`) |
| `presets.json` | Hidden login defaults (`netkingdom`, `platform-admin`, …) |
| `overlay.css` | Hide raw OpenBao login fields |
| `overlay.js` | Apply presets, branding, mount deep-link |
| `nginx.conf` | Gateway proxy + HTML injection |
| `patches/<version>/manifest.sha256` | Upstream UI fingerprints for drift detection |

## Deploy

From `railiance-platform`:

```bash
make openbao-overlay-apply   # overlay only
make openbao-deploy          # middleware + overlay + Helm upgrade
make openbao-verify-login-overlay
```

## Reapply after an OpenBao upgrade

1. Bump `server.image.tag` in `helm/openbao-values.yaml`.
2. Deploy: `make openbao-deploy`.
3. Fetch live UI assets and compare hashes:

   ```bash
   curl -sS https://bao.coulomb.social/ui/ -o /tmp/index.html
   # locate vault-*.js path in /tmp/index.html, then:
   curl -sS "https://bao.coulomb.social/ui/assets/vault-....js" -o /tmp/vault.js
   sha256sum /tmp/index.html /tmp/vault.js
   ```

4. If hashes differ from `patches/<old-version>/manifest.sha256`, update
   `overlay.css` / `overlay.js` selectors against the new Ember templates.
5. Write `patches/<new-version>/manifest.sha256`, update `VERSION`.
6. Run `make openbao-verify-login-overlay CHECK_UPSTREAM_DRIFT=1`.
7. Attended browser login through KeyCape MFA.

Workplan: `helix-forge/workplans/HF-WP-0003-openbao-keycape-login-overlay.md`