SPB Git

Repository Public

OPERATIONS.md 6.1 KB 91 lines markdown

1# Operations (MacLustr)23## Topology45```6Internet ── TLS (Caddy, Let's Encrypt, HSTS) ── BHS64 51.161.112.61 ── WireGuard wg1 ── node:8740  sp-vault         (API + web, PM2)7                                                                                         127.0.0.1:8742 sp-vault-managed (PM2, loopback only)8                                                                                         PostgreSQL 17: sp_vault, sp_vault_managed (local socket/loopback)9                                                                                         ~/sp-vault-data/attachments   (client-side encrypted chunks)10```1112* Deployed and routed by `mld` from the gateway M1M32; manifest `infrastructure/sp-vault.mld.json`13  (copy to `M1M32:~/dispatch/apps/sp-vault.json`). The app is pinned after first placement: data does not follow `mld move`.14* Source of truth after deployment: the git clone on the node (`~/apps/sp-vault`, origin `gitsrv:srv/git/sp-vault.git`).15  Apple targets (`apple/`) are built on the laptop.16* Environments: **production** = database `sp_vault` on the node. **Development / tests** = laptop databases17  `sp_vault_test`, `sp_vault_e2e_test` (wiped at every run), RP ID `localhost`, throwaway keys. No production18  data ever leaves the node except as encrypted backups. There is no shared staging; a staging instance is a19  second manifest with another port, database and domain.2021## Files that matter on the node (all 0600, directory 0700)2223| Path | What | If lost |24|---|---|---|25| `~/.config/sp-vault/backup.key` | Encrypts database dumps | Old backups unreadable (live data unaffected) |26| `~/.config/sp-vault/managed.key` | Master key of managed secrets | Managed secrets unrecoverable → re-enter them. Personal vaults unaffected |27| `~/.config/sp-vault/managed.token` | API ↔ managed process token | Regenerate, restart both processes |2829Copies of `backup.key` and `managed.key` belong off the node (laptop `~/Desktop/Cluster/secrets/sp-vault/`), and30`managed.key` must not sit next to database backups. Neither file gives access to any personal vault.3132## Routine3334```bash35mld status --live | grep sp-vault                     # where it runs, health36ssh <node> 'cd ~/apps/sp-vault && export PATH=/opt/homebrew/bin:$PATH DATABASE_URL=postgres://127.0.0.1/sp_vault SPV_ORIGIN=https://vault.spboucher.ai SPV_RP_ID=vault.spboucher.ai SPV_DATA_DIR=$HOME/sp-vault-data && node dist/cli.mjs status'37…node dist/cli.mjs invite --for "Name" --hours 24     # single-use invitation link (creates an account, never a device)38…node dist/cli.mjs revoke-sessions <handle>           # ends server sessions; does not and cannot touch vault keys39ssh <node> 'pm2 logs sp-vault --lines 50 --nostream'  # logs: route templates, status, duration — no content40```4142The operator CLI has no command that reads, resets or recovers a vault. That is deliberate.4344## Update (remote-first)4546On the node: `git pull` (or edit + commit) → `pnpm install --frozen-lockfile && pnpm build` → `pm2 restart sp-vault sp-vault-managed` → `curl -fsS localhost:8740/api/health/ready` → `git push origin main`.4748Rollout rules: migrations are additive and run inside a transaction with an advisory lock at start-up; a49migration that drops or rewrites data needs a dump first (`scripts/backup.sh`) and the owner's go-ahead. Envelope50version `v`/`alg` never change meaning: a new format is a new number, and clients must read all published ones51before any client writes the new one. Rollback = `git checkout <previous tag> && pnpm build && pm2 restart`;52additive migrations stay in place.5354## Backups, RPO / RTO5556* `sp-vault-backup` (PM2 cron, 03:40): encrypted `pg_dump` of both databases, rsync snapshot of attachments,57  **each dump restored into a scratch database and row-counted** before the run is declared good; 30 dumps kept.58* **RPO 24 h** for server-held state with the nightly job. Clients keep a full encrypted copy of what they59  synced, and users can export self-contained encrypted backups at any time, so a node loss within the RPO window60  loses at most the changes no surviving device had synced.61* **RTO ≈ 1 h**: `mld deploy sp-vault --node <other>`, copy `~/.config/sp-vault`, restore dumps62  (`openssl enc -d … | pg_restore -d sp_vault`), rsync attachments back, `mld tunnel route sp-vault`.63* **Offsite**: the nightly job writes to the same node. Copying `~/backups/sp-vault` to another site (already64  encrypted; BHS64 or the laptop) is `scripts/offsite-pull.sh <node> <dest>`; scheduling it is an open decision65  (destination, retention). Until then a disk failure of the node relies on client copies and user backups.66* Point-in-time recovery (WAL archiving) is not configured; nightly dumps only.67* Restore drills: record them in `docs/operations/RESTORE-DRILLS.md`.6869## Monitoring7071`/api/health/ready` (checked by `mld heal` every 5 min). `node dist/cli.mjs status` gives counts only. No72metrics endpoint exposes per-account or per-item data. Disk: attachments are capped at 100 MiB per file and735 GiB per account.7475## Hardening checklist7677HSTS preload header, CSP + Trusted Types, no CORS, cookies `__Host-` + `SameSite=Strict` + `HttpOnly` + `Secure`,78rate limits on every authentication path, request bodies ≤ 2 MiB (chunks 1 MiB), PostgreSQL bound to loopback,79FileVault state of the node (cluster nodes boot unattended with FileVault off — **the database volume is not80encrypted at rest**; vault content is ciphertext regardless, metadata and managed-secret ciphertext rely on81file permissions and on `managed.key` being a separate file), macOS updates per `mld harden`.8283## Incident playbook8485* **Node or database stolen / leaked**: personal vault content stays encrypted; treat metadata as disclosed;86  rotate every managed secret at its issuer; rotate `managed.key`; end sessions (`delete from sessions`).87* **A user device lost unlocked**: user revokes it (Devices) and runs Account rekey, then changes key passwords.88* **Suspected malicious web bundle**: stop the route (`mld tunnel rm sp-vault`), compare `dist/web` hashes with89  a clean build of the tagged commit, tell users to use native apps and rekey.90* **Agent misbehaving**: kill switch (Connect & Agents), then revoke its identity and rotate the secrets it used.91
Files main
Menu

Theme