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.
43 lines
1.8 KiB
Markdown
43 lines
1.8 KiB
Markdown
# Wallet
|
|
|
|
A self-custodial bitcoin wallet inside Officer, with the keys held on **your server** rather than on a
|
|
phone or in a browser.
|
|
|
|
## What you get
|
|
|
|
- On-chain balance, receive addresses and transaction history
|
|
- Send, with fee control, coin selection and UTXO freezing
|
|
- Labels for addresses and transactions
|
|
- Multiple wallets, one active
|
|
- Chain data from **Esplora** or your own **NBXplorer**
|
|
|
|
## How the keys are held
|
|
|
|
Read `docs/wallet-key-custody.md` in the platform for the full design. The short version:
|
|
|
|
- Your seed is encrypted under a key derived from **your own passphrase** (scrypt, N=2¹⁷), then encrypted
|
|
again at rest. The server never stores the passphrase.
|
|
- The wallet is **usable while locked** — balances, history and fresh receive addresses all work without
|
|
it. Unlocking is required only to **sign**.
|
|
- An unlock lasts 15 minutes by default and **does not extend on use**. A restart relocks everything.
|
|
- There is no "forgot passphrase". There is no recovery. Your seed backup is the recovery.
|
|
|
|
## Multi-user
|
|
|
|
Each account gets its **own** wallet, sealed under its own passphrase. Granting the `bitcoin-wallet` permission
|
|
to a role gives those people a wallet of their own — it does not give them yours, and it does not give
|
|
you theirs. Not through the app, and not with root either: their seed is sealed under a passphrase you
|
|
do not have.
|
|
|
|
**One caveat, stated plainly:** balances and history are stored unencrypted so a locked wallet still
|
|
shows them. Anyone with the database — or a backup of it — can *see* any user's balances. They can never
|
|
*move* anything.
|
|
|
|
## Permissions
|
|
|
|
One permission, `bitcoin-wallet`. Grantable per role like any other app permission.
|
|
|
|
## Requirements
|
|
|
|
None to start. Esplora is used by default; point it at your own NBXplorer if you run one.
|