[ety001]

Part of #381

Summary

A2 of the vault development kickoff: the persistent storage layer and the in-memory unlock-session layer. Five new files, zero changes to existing files (the A0/A1/A1.1 five vault modules and all existing tests are untouched).

src/lib/vault/registry.ts — IndexedDB storage primitives

• Versioned database steem-wallet-vault (v1), stores vaults (keyPath vaultName, one VaultRecordV1 per vault) and settings (singleton VaultSettingsV1).
• Atomic alias uniqueness: uniqueness check and write happen inside the SAME readwrite transaction, comparing vaultNameComparisonKey values (from validation.ts — the shared entry points; nothing re-implemented). Design choice: a unique index was rejected because it would require persisting a comparison-key field inside VaultRecordV1, which is not part of the type contract; IDB's per-store writer serialization gives check-then-act atomicity. The comparison key is not the vault identity and never enters the envelope/AAD.
• createVault validates name (VAULT_NAME_INVALID) + password (VAULT_PASSWORD_WEAK) at the primitive level (not left to callers), has a cheap pre-check so duplicate names never pay PBKDF2, and zeroizes its derived KEK inside the call — the registry never retains key material.
• swapRecord(expected, next): in-transaction CAS on (createdAt, revision, lockEpoch); drift → VAULT_SESSION_STALE, gone → VAULT_NOT_FOUND, malformed envelope → VAULT_ENVELOPE_INVALID, contract violations → TypeError (programmer error, crypto.ts precedent). next.revision must be expected.revision + 1.
• bumpLockEpoch (lockEpoch+1, revision untouched), renameVault (case-only self-rename allowed, collision with another comparison key rejected, settings active-pointer follows atomically), removeVault (active pointer cleared atomically with the delete), getSettings/putSettings (defaults signingMode: 'privateKey', corrupt row fails closed with VAULT_PAYLOAD_INVALID).
• Fail closed: missing indexedDB global, throwing open, erroring open request, or use-after-close → VAULT_STORAGE_UNAVAILABLE. No in-memory fallback pretending to be persistence.

src/lib/vault/service.ts — unlock sessions (createVaultService(registry) factory)

• KEK and decrypted payload live only in the instance closure; no exported function returns them. getAccounts() returns only public-key-derived VaultAccountSummary values (via the shared validateVaultWif entry point), getStatus() only non-sensitive counters.
• unlock (switch clears the previous session completely first — its lockEpoch is persisted), lock (KEK fill(0) BEFORE dropping references, then lockEpoch+1 persisted, then broadcast). Honest zeroization statement: the KEK bytes can be zeroed; WIF/password strings cannot be physically zeroed — dropping references is the documented limit, the code never claims otherwise. A KEK from a failed unlock is zeroized before the error propagates.
• Pure unlock/lock never touch stored salt/IV/ciphertext (asserted byte-identical). mutatePayload: draft copy → validate (failure = rollback by construction: nothing written, session keeps its original payload) → fresh IV → whole-payload re-encryption under the session KEK (salt unchanged) → CAS revision+1.
• Cross-tab invalidation, two layers: the hard line re-reads the registry and re-checks revision/lockEpoch before EVERY session-bound operation (status queries and mutations today, signing from A4 on) — delayed notifications are never the only defense. BroadcastChannel('steem-wallet-vault') lock/mutate events clear the local session early (acceleration); when the API is absent the service degrades gracefully.
• Fresh instance = locked (sessions are pure memory → page refresh locks).

Kickoff A2 completion criteria — item by item

• 别名原子唯一及 NFC/大小写用例: Work/work, NFC/NFD Café conflicts (VAULT_NAME_EXISTS), racing creators with colliding names — exactly one wins (serialized transactions). ✅
• 创建/激活/改名/删除语义: create/get/list/rename (case-only self allowed, collision rejected, NOT_FOUND on missing, invalid new name rejected)/remove (pointer cleared atomically) all covered. "激活" is exposed as the settings primitive (putSettings/getSettings with activeVaultName); the manager-level activateVault orchestration is A4 scope. ✅ (activation = settings primitive only)
• 刷新后锁定: new service instance over the same storage starts locked. ✅
• 切换…清除 KEK + 完整 payload: unlock A → unlock B fully locks A (its lockEpoch persists); a failed switch-unlock still leaves the previous session cleared. Mode switching (privateKey/vault) is the settings row + A5 UI scope — the service holds no mode state. ✅ (mode switch = A5)
• Redux 不保存敏感数据: A2 touches no Redux; exported values carry no WIF/KEK/payload (test walks every key of the exported account summaries). ✅
• Implementation rules (shared validators, in-transaction uniqueness, fill(0)-then-release, unlock/lock envelope immutability, mutate = new IV + full re-encrypt, re-check before every operation, complete lock on cross-tab invalidation): all implemented and asserted. ✅

Test plan

• tests/unit/vault-registry.test.ts — 41 cases, ~4.5s (7 PBKDF2 derivations; everything else seeded from the fixed vectors).
• tests/unit/vault-service.test.ts — 13 cases, ~16-18s (22 derivations total incl. shared beforeAll KEKs; every case rebuilds state in beforeEach — shuffle-stable).
• Full suite: pnpm verify green — type-check, lint (0 new warnings), 131 files / 1434 tests, coverage thresholds met (global 83.5% stmts / 74% branch). Vault module: registry.ts 95.9% stmts / 86.4% branch, service.ts 91.7% stmts / 75.9% branch / 100% funcs (crypto/envelope/validation still 100%/98.6%/100%).
• Environment probes (conclusions, run before coding): vitest jsdom has no indexedDB (fake required — as briefed); it does have a working BroadcastChannel (Node's own implementation leaks into the environment — divergence from the task brief). The "no BroadcastChannel" hard-line cases therefore hide the global explicitly; the acceleration cases use the real Node channel (cross-instance delivery, no self-receipt, structured clone verified by probe).

Fake IndexedDB fidelity boundary

tests/mocks/fake-indexeddb.ts (hand-written, no new dependencies): single shared state per database name (what the cross-instance "two tabs" cases need), FIFO transaction queue approximating IDB writer serialization, macrotask auto-commit grace, JSON deep-clone on read/write, an abortCount() observability hook. NOT simulated: versionchange/blocked negotiation, abort rollback, cursors/IDBKeyRange, real multi-connection browser semantics. Shared by both test files (a tests/mocks/ module — chosen over in-file copies so registry and service tests exercise the same fake).

Review follow-up (commit e02908c)

Three-way review round 1 found 1×P1 + 2×P2 (session-identity and failure-path defects, each experimentally reproduced), fixed in e02908c4 with regression tests verified to fail with the fix reverted:

• [P1] remove + same-name recreate reset counters to 0/0 and collided with a live session's identity, letting a stale tab overwrite the recreated vault's ciphertext with the old KEK (permanent corruption). Session identity now includes createdAt everywhere (freshness re-read, CAS pointer, adopt branch); residual same-millisecond window documented in-code (closing it fully needs a random per-record id, a VaultRecordV1 change deferred to a future schema version).
• [P2] The post-CAS adopt branch could install a zeroed KEK (destroy + re-unlock interleaving). It now adopts the live closure session's KEK.
• [P2] lock() skipped the BroadcastChannel notification when the lockEpoch persistence failed; the broadcast now runs in a finally and the error still propagates.
• Also: runInTransaction aborts on callback throw (no partial writes on real IDB), unlock re-checks the record after derivation (mid-unlock removal → VAULT_SESSION_STALE), service tests rebuilt as per-case independent state (shuffle-stable), fake dead index surface removed, several small hardening items.

Round 2 (3-way) confirmed the fixes via adversarial replay, a real-Chromium + real-IndexedDB golden run (43/43 incl. real rollback semantics and cross-page BroadcastChannel) and negative mutation controls (6/6 assertions flip red with fixes reverted).

Not verified / known limits (stated honestly)

• Real browser IndexedDB and multi-tab behavior are NOT verified in this stage (fake-only) — left for later e2e coverage; the hard line + e2e are the designated backstop, per the kickoff.
• WIF → public-key derivation in getAccounts is mock-driven under vitest (two-layer A1.1 discipline); real-crypto evidence remains tests/node/vault-wif-real-check.mjs (rerun not required — no WIF-handling change).
• Uncovered defensive branches: service.ts session-replaced-mid-await (throw locked() in the guard) and the CAS-race cleanup guard in mutatePayload — both exist precisely for interleavings that cannot be triggered deterministically through the public API; registry transaction onerror/onabort bodies and the generic storage wrap likewise never fire on the fake. Above thresholds regardless.
• openVaultRegistry(dbName) accepts a name override for future test parallelism; default is VAULT_DB_NAME.