# Vault — the extraction record

Extracted from the platform on **2026-08-18**, the fourth plugin out (after offscale, music, email).
`plugins/EXTRACTING-A-PLUGIN.md` is the runbook; this file is what was decided and what it cost.

## Where it came from

| Was                                    | Is now                        |
| -------------------------------------- | ----------------------------- |
| `src/servers/api/vault/router.ts`       | `api/router.ts` (+ config routes) |
| `src/servers/api/vault/broker.ts`       | `api/broker.ts`               |
| `src/servers/api/vault/token-store.ts`  | `api/token-store.ts`          |
| `src/servers/api/vault/proxy-util.ts`   | `api/proxy-util.ts`           |
| `src/servers/api/vault/sidecar-server.ts` | `api/sidecar-server.ts`     |
| `src/servers/api/vault/public-router.ts` | **deleted** — see below       |
| `src/servers/api/vault/websocket.ts`    | **deleted** — see below       |
| `src/servers/sidecar/vault/*`           | `sidecar/*`                   |
| `src/databases/officer_db/src/vault/*`  | `db/*`                        |
| —                                       | `web/*` — new, there was no UI |

## The state it was found in

Vault had been **switched off since 2026-08-13** (`1eecc400`, "switch off Vaultwarden's routers, pending
extraction into a plugin") — mounts commented, code left on disk, tables commented out of `schema.ts` and
therefore dropped by a later push. It was briefly re-enabled earlier the same day as this extraction
(`c775e8c7`) on a misreading of what the owner wanted, then extracted properly. That commit is a dead end
kept in history rather than reverted, per the repo's own rule about committing the mistakes.

Consequence worth stating: **nothing regressed for anyone**, because nothing was live. `vault_tokens` and
`vault_unlock_keys` did not exist in Postgres and `sidecar_installs` had no vault row.

## Decisions

### 1. The Vaultwarden URL moved from `.env` into the database — server-wide

`VAULTWARDEN_URL` is gone. It is now `vault_config`, a one-row table (`id` pinned to 1 by a CHECK), with a
settings panel at `/vault` writing it.

Server-wide rather than per-user, decided with the owner: one Vaultwarden per install. Jellyfin's registry
is per-user because that machine genuinely runs four instances; there is no such case here, and a `userId`
column would be a join paid on every request for a second row that does not exist.

The env var could not survive anyway — a plugin cannot ask the owner to edit a file and restart a process.
Installing it has to be enough.

**Cost:** the sidecar now reads its upstream from Postgres instead of memory. It caches with a 10s TTL
(`sidecar/upstream.ts`) rather than querying per request, because this sits in front of every proxied byte
including attachment uploads. The TTL is the whole mechanism — there is no push, because
`sidecar-registry.ts` has no generic "send a command to the sidecar named X" and building one for a cache
hint would be a channel built for the wrong reason.

### 2. Core stopped importing the vault, via a new lifecycle hook — NOT by reaching into its tables

The reverse dependency that decided the split. Three core auth sites — `signout.ts`, `revoke-handler.ts`,
`panic-handler.ts` — imported `clearVaultTokens` / `clearVaultUnlockKey` from `officerdb` and called them.
That is the security property behind the distress and panic buttons: "someone got in, make the vault need
a master password again."

Three options, and the stakes chose:

- **Drop the wipe.** A silent security regression on the path that exists for the worst day. No.
- **Have core `DELETE FROM vault_tokens` by name.** Removes the import, keeps the coupling, and moves it
  somewhere worse — core would depend on this plugin's *schema*, so renaming a column would silently stop
  the wipe. This is the shape `docs/email-plugin-extraction.md` took for *reading* a plugin's data, where
  a stale answer is a missing feature rather than a lock left open.
- **A lifecycle announcement.** Taken. `src/servers/account-lifecycle.ts` is ~30 lines: core emits
  `signout` / `distress` / `panic` with a user id, anything holding per-account state subscribes. Core
  names no plugin, no table and no column, and a listener that is not there is a plugin that is not
  installed.

The severity mapping moved into the plugin, where it belongs, and the behaviour is unchanged: `signout`
drops the brokered session and keeps the protector key; `distress` and `panic` drop both.

**Known hole, accepted:** uninstall keeps rows, so a panic while the plugin is uninstalled wipes nothing.
The tokens are unusable in that state (no routes mounted) and reinstalling is an owner action, so this is
narrow rather than dangerous — but it is real.

### 3. The unauthenticated Bitwarden passthrough was deleted, not carried

`public-router.ts` served Vaultwarden at Officer's own hostname with no Officer auth, so the Bitwarden
browser extension could be configured with the bare Officer URL — mounted at `/vaultwarden` and at four
root prefixes (`/identity`, `/notifications`, `/icons`, `/events`), with an `/api/*` diverter keying off
the `Bitwarden-Client-Name` header.

**A plugin cannot serve any of that.** Plugin routers mount into `protectedRouter` at
`/api/<name>` — behind the account gate, by design. Top-level unauthenticated prefixes are not something a
manifest can declare, and the Bun route table those paths need entries in is built once at `serve()`.
Keeping it would have meant core naming `/vaultwarden` and `/identity` in its own route table: the exact
vocabulary leak the runbook forbids, for a path its own comments already called TEMPORARY.

The owner's call was "nice to have, not a requirement", with the intended end state being a first-party
browser extension that authenticates to Officer like every other client — which deletes the need rather
than restoring the workaround. So it is deleted here rather than carried as dead code.

**This is the one user-visible loss**, and it was already dark since 2026-08-13.

### 4. The notifications websocket went with it

`/api/vault/notifications/*` was upgraded at the serve level and piped to the sidecar with the Vaultwarden
token injected. Same blocker as above plus a second one: **no plugin owns a websocket on this platform
yet** — `server.reload({ routes })` is proven and never called, and `handlers` in `server.tsx` is a static
map. Music parked `cliamp/` for exactly this.

SignalR degrades to HTTP long-polling on its own, and that path *does* extract — it rides the ordinary
HTTP proxy. So clients still sync; they learn about changes on their next poll rather than instantly.

The sidecar's own websocket proxy is kept and still works (it is what a future platform mechanism would
plug into). Its `open` handler had to become async because the upstream base now comes from the database —
state is registered before the first `await` so frames arriving during setup are queued rather than
dropped, which is the shape the deleted platform-side proxy already used.

### 5. Owner-only stayed owner-only, in the plugin's own gate

A plugin permission is grantable per role by design — the rule is uniform and has no `ownerOnly`. So a
member could hold `vault`. The router keeps its own `isSuperAdmin` gate rather than inheriting an answer:
the permission decides whether the *route* is reachable, and the vault is the owner's.

## What the platform lost

Deleted, not commented: both routers, the sidecar, the db directory, the `hono.ts` mounts and imports, the
`server.tsx` ws import / handler entry / route-table entries, `/vault` from `UNPROTECTED_API_PREFIXES`,
both entries in `totality.ts`'s exemption lists, both database barrels, and the `app-store/catalogue.ts`
entry.

**The catalogue entry deletion is required, not tidying** — the trap the runbook records as having bitten
twice. `permissionAvailability()` derives from `sidecar_installs`, which a plugin never gets a row in, so a
leftover entry makes the permission permanently `unavailable`, puts the route into `deniedRoutes`, and
withholds the dock tile on a server where the plugin is installed and healthy.

Two tests referenced the catalogue entry. Vault was the **only** `members: 'invite'` entry, so removing it
would have silently dropped coverage of that branch in `plannedOutcome` — it is now tested against a
synthetic entry instead, because deleting an assertion along with the last real user of a case is how a
switch arm stops being covered without anyone deciding it should.

## Still open

- **The Bitwarden-direct path** (decision 3). Needs either a first-party extension or a platform mechanism
  for manifest-declared public prefixes; the latter also needs `server.reload({ routes })` to actually be
  called for the first time.
- **The notifications websocket** (decision 4). Blocked on plugin-owned websockets, platform-wide.
- **Additional accounts.** Everything is owner-only. Vaultwarden has its own users and mapping Officer
  accounts onto them is unbuilt.
- **The panic-while-uninstalled hole** (decision 2).