openVault

TOTP-gated session keys for vault access. Rocky-local, 10-hour TTL.
deployed 127.0.0.1:8200 no autostart yet
This is the spin-up cheat sheet for the artificer. If you booted a fresh shell and a vault call failed, start here.

what it is

openVault replaces the old static vault key with a time-limited session key. The operator authenticates once via TOTP (an authenticator app on phone). Agents read VAULT_KEY from environment; the shell profile fetches it from openVault at startup. After 10 hours the session expires and the operator re-authenticates.

three states

When opening a new shell, you'll always be in one of three states.

// STATE 1 -- service running, session valid

Less than 10 hours since the last TOTP unlock. VAULT_KEY auto-loads in any new shell. Nothing to do.

Confirm:

python C:\Users\ctgau\library\0-system\security\dev\openVault.py status

Expected output: Session: ACTIVE -- Xh remaining

// STATE 2 -- service running, session expired

Past the 10-hour mark. Service is fine, just re-authenticate. Open the authenticator app, grab the 6-digit code, then run:

curl -X POST http://127.0.0.1:8200/unlock ^
  -H "Content-Type: application/json" ^
  -d "{\"totp\":\"<6-digits>\"}"

New shells will then pull VAULT_KEY cleanly on startup.

// STATE 3 -- process died or Rocky rebooted

The service is not under autostart yet. After a reboot, relaunch it in a terminal you can leave running:

python C:\Users\ctgau\library\0-system\security\dev\openVault.py serve

Then run the STATE 2 unlock command to authenticate.

quick check anytime

Open a fresh shell. Behavior tells you the state:

What you seeState
silent (no openVault output)STATE 1 -- $env:VAULT_KEY populated
[openVault] locked or unreachableSTATE 2 or 3 -- run unlock or serve

how it fits together

+----------------------+
|  authenticator app   |   (operator's phone)
+----------+-----------+
           | TOTP 6-digit code
           v
+----------------------+
|  openVault service   |  127.0.0.1:8200 on Rocky
|  python script       |  10-hour session
+----------+-----------+
           | GET /master-key
           v
+----------------------+
|  shell profile       |  PowerShell + bash
|  fetches VAULT_KEY   |  on every new shell
+----------+-----------+
           | sets $env:VAULT_KEY
           v
+----------------------+
|  agent session       |
|  uses VAULT_KEY to   |
|  call vault API      |  questboard-ec2:8120
+----------------------+

pending work

references