officer
a4cf939be7
Tenth plugin out, and the one whose extraction turned on a permission decision rather than a mechanical move. The wallet permission was kind: 'admin' — owner only, not grantable, invisible to every other account. Plugin permissions are ALWAYS kind: 'app': mount.ts forces it and the manifest has no field for anything else, deliberately, so that "can a plugin escalate itself" is a question which cannot be asked. So extraction could not preserve admin, and that was raised as a blocker before any code moved. It was the right change anyway, and the objection inverts. Every wallet query is scoped by user_id, and that id comes from X-Officer-User which the platform injects from the authenticated session — a caller cannot name someone else's. So granting this gives an account ITS OWN wallet. Not through the API and not with root either does it hand over anyone else's, because their seed is sealed under a passphrase the server never stores. kind: 'admin' was single-user thinking; grantable is how a second person gets a wallet at all. Named bitcoin-wallet rather than wallet: it is a bitcoin wallet specifically, and the appName drives the route, the API prefix, the table prefix and the install key together. Tables renamed to bitcoin_wallet_* accordingly — the prefix guard normalises the hyphen. Free only because no wallet table existed on any server, which was checked before deciding: db:push treats a rename as a drop plus a create. The three custody test files moved with it and still run — 72 tests over scrypt sealing, envelope open and bolt11. bunfig.toml's test root was widened on 2026-08-15 after music took lyrics.test.ts and the suite silently shrank by nine, so that trap was already closed. 68 palette classes converted, five status vocabularies hoisted into shared.ts. Two deliberate flattenings recorded in PLUGIN.md: testnet/signet/regtest all read as warning, and the bitcoin and lightning rails no longer differ by hue. Deferred on purpose: watch-only data (xpubs, balances, history) stays unencrypted so a locked wallet still shows a balance. Anyone with the database can therefore SEE any user's balances; they can never move a coin.
4.9 KiB
Wallet — the extraction record
Extracted on 2026-08-19, the tenth plugin out. plugins/EXTRACTING-A-PLUGIN.md is the runbook, and
docs/wallet-key-custody.md in the platform is authoritative for the crypto — read that before touching
sidecar/keys.ts.
The decision this extraction actually turned on
The wallet permission was kind: 'admin' — owner only, not grantable, invisible to every other
account. Plugin permissions are always kind: 'app', which means grantable: mount.ts forces it and
the manifest has no field for anything else, deliberately, so that "can a plugin escalate itself" is a
question that cannot be asked.
So extracting this could not preserve admin. That was raised as a blocker before any code moved,
because turning "the server owner's bitcoin" into a row in the grants list next to Photos and Music is
the kind of change nobody notices until someone ticks it.
It was the right change anyway, and for a reason that inverts the objection. Every wallet query is
scoped by user_id, and that id comes from X-Officer-User, injected by the platform from the
authenticated session — a caller cannot name someone else's. So granting this permission gives an
account its own wallet. It does not hand over anyone else's.
kind: 'admin' was single-user thinking. Grantable is the mechanism by which a second person gets a
wallet at all.
What that means for isolation, precisely
| Who | Can they reach another user's wallet? |
|---|---|
| A member, through the API | No. Queries filter on user_id, including fetch-by-id, so guessing an id gets nothing. |
| The OWNER, through the API | No. The owner bypasses permission checks, not query scoping — listWallets returns the caller's. |
| The owner, with root and the database | Can read watch-only data. Cannot spend. |
| Anyone, wanting to spend | Needs that wallet's own passphrase. scrypt N=2¹⁷, ~1s and 128 MiB per guess, and the server never stores it. |
The gap that is real, and deferred on purpose
Watch-only data — xpubs, and the balances, addresses and history derived from them — is stored in the clear. That is what makes a locked wallet still show a balance, which is the property that stops anyone leaving a wallet unlocked for convenience.
The cost: anyone holding the Postgres database, or a backup of it, can read any user's balances and history. They can never move a coin.
Encrypting it per-user was discussed and explicitly deferred — it would cost balance-while-locked, and the decision was not to hinder the extraction for it. Recorded here rather than left to be discovered.
A hazard that is NOT this plugin's, but which will bite here first
Layer 2 of the custody design encrypts the sealed envelope with the platform's encryptSecret(). If that
key is lost, the envelope cannot be opened and the seed is gone — layer 1 is inside layer 2.
This is not hypothetical: on 2026-08-19 the alpha server's key had been re-minted, and every stored secret (slskd, gitea, memos) became undecryptable. Those are re-typeable credentials. A seed envelope is not. Back up the key file before funding a wallet.
What moved
| Was | Is now |
|---|---|
src/servers/sidecar/wallet/* (19 files, incl. aezeed/, backends/) |
sidecar/* |
src/servers/api/wallet/router.ts |
api/router.ts |
src/databases/officer_db/src/wallet/* (3 files) |
db/* |
src/workspaces/officerdev/src/apps/Wallet/* (35 files, incl. dialogs/) |
web/* |
src/apps/officer-web/Screens/Dashboard/Wallet/* |
web/layout.ts |
The three test files moved with it and still run — keys.test.ts, bolt11.test.ts,
chain-source-esplora.test.ts, 72 tests covering the custody crypto. bunfig.toml's test root was
widened on 2026-08-15 for exactly this, after music took lyrics.test.ts away and the suite silently
shrank by nine. Worth stating because it is the one extraction where losing the tests would have mattered
most.
Not self-contained in one place
config.ts and upstream.ts read the core service_connections table for the NBXplorer connection —
the same coupling transmission and soulseek have. The wallet's own three tables moved with it.
Fixtures
wallet was the canonical kind: 'admin' fixture in registry.test.ts and its no-selfService fixture.
Re-anchored to user-admin/server-admin and terminal. The admin-kind test now carries a note that a
plugin's permissions are always app — which is precisely why this extraction needed a decision rather
than a default.