# vault — Vault Orchestration Layer

- **Change ID**: vault
- **Package**: `@suaveplan/vault`
- **Status**: PROPOSED
- **Type**: new-package
- **Date**: 2026-04-29

## Why

The Vaulted password-manager ecosystem needs a single domain abstraction that orchestrates `crypto-vault` (key hierarchy), `@suaveplan/crypto/keychain` (keypair utilities), `db-sqlite` (item storage), `drive` (attachments), `drive-sharing` (share links), and `vault-sync` (sync engine). Today, vault-shaped helpers (`sealVaultPayload`, `openVaultPayload`, `LegacyVault`) live alongside primitive crypto in `@suaveplan/crypto/vault` — that subpath is fine for the low-level seal/open building blocks, but it does NOT provide the lifecycle, item-CRUD, attachment, share, or sync orchestration consumers need. Creating `@suaveplan/vault` introduces a clean orchestration layer above the existing crypto primitives; satisfies the security invariant that key material never leaves `crypto-vault`; and provides a clean API surface for desktop, mobile, and browser-extension consumers.

> **Amendment 2026-05-03:** This proposal originally referenced `@suaveplan/keys` as the source for `VaultManager` / `VaultFactory`. On the genesis branch that package never landed — keypair management was absorbed into `@suaveplan/crypto/keychain` and the legacy vault helpers into `@suaveplan/crypto/vault` during the genesis architecture redesign. References to `@suaveplan/keys` below have been amended to point at the corresponding `@suaveplan/crypto` subpaths.

## What changes

- ADDED: `Vault` class — `Vault.open(config, options?)`, `unlock(password, secretKey, options?)`, `lock()`
- ADDED: `OpaqueKeyHandle` — wraps raw `Uint8Array` keys exported by `crypto-vault` before crossing module boundaries
- ADDED: `vault.items` — `create()`, `get()`, `update()`, `delete()`, `list()`, `search()` delegated to `db-sqlite`
- ADDED: `vault.attachments` — `upload()`, `download()`, `delete()` delegated to `drive`
- ADDED: `vault.shares` — `createLink()`, `revokeLink()` delegated to `drive-sharing`
- ADDED: `vault.sync` — `pull()`, `push()`, `sync()` delegated to `vault-sync`
- ADDED: `VaultConfig`, `VaultState`, `VaultItem`, `ItemFields`, `Attachment`, `ShareLink`, `SearchQuery`, `SyncResult` types
- ADDED: `VaultError` with structured error codes for lifecycle, item, attachment, share, and sync failures
- MODIFIED: `@suaveplan/crypto/vault` — the orchestration concerns previously envisioned for `keys`'s `VaultManager` / `VaultFactory` are authored fresh inside `@suaveplan/vault`. The existing primitives at `@suaveplan/crypto/vault` (`sealPrivateKeyBlob`, `openPrivateKeyBlob`, `sealVaultPayload`, `openVaultPayload`, `changePassword`, `rotateApplicationData`, `LegacyVault`) are unchanged; `@suaveplan/vault` consumes them. No `@suaveplan/keys` migration is required because that package was never created on genesis (its responsibilities are split across `@suaveplan/crypto/keychain`, `@suaveplan/crypto/authority`, and `@suaveplan/crypto/vault`).

## Phased delivery

- **Phase 1** (this change): `vault` defines adapter interfaces (`DriveLike`, `DriveSharingLike`, `VaultSyncLike`) so it compiles and tests without the real `drive`, `drive-sharing`, and `vault-sync` packages. Adapters are injected via `VaultConfig`.
- **Phase 2** (follow-up changes): When `drive`, `drive-sharing`, and `vault-sync` land, `vault` swaps the adapter interfaces for real implementations. No public API changes are expected at that point.

## Out of scope

- UI components or React hooks — belong in `@suaveplan/react-vault` (future package)
- Browser-extension-specific vault access patterns — extensions delegate crypto to the desktop app via `@suaveplan/native-messaging`
- Biometric unlock integration — `vault.unlock` accepts password+secretKey; biometric path wraps this in `@suaveplan/biometrics`
- Import/export from competing password managers (1Password, Bitwarden, KeePass) — deferred to dedicated import packages
- SQLCipher native integration — `db-sqlite` handles SQLite; encryption-at-rest is the vault layer's responsibility via `drive`

## Gap analysis: sub-standard → enterprise

Most password-manager vault implementations fall well below enterprise standards:

| Sub-standard practice | Enterprise replacement |
|---|---|
| Mixed concerns (key generation, vault logic, and UI state in one module) | Clean separation: `crypto-vault` owns keys, `vault` owns orchestration, `react-vault` owns UI |
| No clear lifecycle (implicit initialization, ambiguous lock/unlock boundaries) | Explicit `Vault.open(config) → unlock(password, secretKey) → lock()` state machine with enforced transitions |
| Key material leaked across module boundaries as strings or plain buffers | `SecureBuffer` from `crypto-vault` never crosses the `vault` API boundary; only opaque handles are exchanged |
| No structured error handling (generic `Error` with string messages) | `VaultError` with structured error codes for every failure mode (lifecycle, item, attachment, share, sync) |
| Ad-hoc item encryption (some fields encrypted, others not, no versioning) | Deterministic field-level encryption: concealed fields always encrypted, schema versioned, history append-only |
| No search safety (full-text search over plaintext or unencrypted indices) | FTS5 over encrypted blind indices; concealed fields excluded from search results |
| No offline queue for mutations | Durable offline queue via `vault-sync`; reads continue from local snapshot when disconnected |
| Monolithic sync with no conflict resolution | Client-side CRDT merge with domain-specific strategies delegated to `vault-sync` |

This package migrates vault orchestration from an ad-hoc, tightly-coupled module to a rigorously designed, lifecycle-driven, enterprise-grade layer.

## Security model

### Threat model

| Attacker | Capability | Mitigation |
|---|---|---|
| **Local attacker** (malware, keylogger) | Can read process memory, intercept file system | `SecureBuffer` eager zeroization via `fill(0)` from `crypto-vault`; key material never leaves `crypto-vault` boundary; vault layer only handles opaque handles |
| **Remote attacker** (network MITM, compromised API) | Can intercept sync payloads, replay auth | E2EE via `vault-sync` (XChaCha20-Poly1305); SRP-6a authentication in `api` layer |
| **Compromised sync server** | Can read stored blobs, modify sync data | Client-side encryption; server never sees plaintext, keys, or metadata; `vault` orchestrates encryption before any network operation |
| **Forensic recovery** (stolen device, cold boot) | Can extract RAM contents post-unlock | `SecureBuffer` zeroization on lock; no key material persisted unencrypted; `vault.lock()` triggers global zeroization |

### Encryption boundaries

- **Plaintext lives only inside** the `vault` memory boundary during active sessions (unlocked state).
- **Key material lives only inside** `crypto-vault`; `vault` wraps raw `Uint8Array` keys in `OpaqueKeyHandle` objects before crossing module boundaries.
- **Item concealed fields** (passwords, PINs, secure notes) are encrypted with per-item keys derived from the hierarchical key tree.
- **Attachment plaintext** is ephemeral: decrypted for upload/download streaming only, then zeroized.
- **Search indices** use blind-index tokens (HMAC of field values) rather than plaintext to enable encrypted search.

### Key hierarchy and derivation

```text
Account Password + Secret Key + Email + Salt ──► Argon2id ──► AUK (in crypto-vault)
                                                                  │
                                                                  ▼
                                              HKDF-Expand ──► Personal Keyset
                                                                  │
                                                                  ├──► HKDF ──► Vault Key (per vaultId)
                                                                  │                    │
                                                                  │                    ├──► HKDF ──► Item Key (per itemId)
                                                                  │                    │
                                                                  │                    └──► HKDF ──► Sync Encryption Key
                                                                  │
                                                                  └──► HKDF ──► SRP Private Key / Verifier
```

- **AUK**: Ephemeral root held only in `crypto-vault`. `vault` never accesses it directly.
- **Vault Key**: Per-vault symmetric key used to derive item keys.
- **Item Key**: Per-item symmetric key for encrypting concealed fields.
- **Sync Encryption Key**: Derived from vault key for E2EE sync payloads.

### Two-secret key derivation (2SKD) threat model

`vault` does not perform 2SKD itself, but it enforces the security invariant that the AUK (2SKD output) never leaves `crypto-vault`:

- `vault.unlock(password, secretKey)` delegates derivation to `crypto-vault` and receives only an opaque vault-key handle.
- Compromise of the `vault` process alone does not reveal key material because `crypto-vault` uses pinned memory and zeroization.
- Compromise of both `vault` and `crypto-vault` still requires the password and Secret Key to derive the AUK.

### Secure memory

- All key material is allocated inside `crypto-vault` as `Uint8Array` keys; `vault` wraps them in `OpaqueKeyHandle` instances before storing them.
- `vault` stores only opaque key handles in its state machine.
- On `vault.lock()`, all opaque handles are invalidated and `crypto-vault.zeroizeAll()` is invoked.
- Attachment streaming uses fixed-size chunks; no large plaintext buffers are retained.

### Side-channel resistance

- Search blind-index tokens are computed via constant-time HMAC to prevent timing leaks of field values.
- Item field comparison (e.g., duplicate detection) uses constant-time comparison for concealed fields.
- Vault state transitions (locked → unlocked) are not secret-dependent branches at the `vault` layer.

### Compliance

- **NIST SP 800-63B**: Relies on `crypto-vault` Argon2id for memorized secret verification; satisfies NIST-approved key hierarchy via HKDF.
- **OWASP Cryptographic Storage Cheat Sheet**: Field-level encryption with AEAD, unique per-item keys, and secure memory satisfies recommended controls.
- **GDPR Article 32**: E2EE with client-side key management provides a strong technical safeguard for personal data processing.

## Performance SLOs

| Metric | Target | Measurement |
|---|---|---|
| **Unlock latency** | P99 ≤ 1.5s on target hardware | End-to-end from `vault.unlock()` call to usable vault state (includes Argon2id in `crypto-vault`) |
| **Item CRUD latency** | P99 ≤ 10 ms | Create, read, update, delete a single item (includes encryption/decryption) |
| **Search latency (FTS5)** | P99 ≤ 50 ms for 10K items | Full-text query over 10,000 items with category/tag filters |
| **Sync latency (pull+push)** | P99 ≤ 500 ms for ≤ 100 changed items | End-to-end sync delegation to `vault-sync` |
| **Attachment upload/download** | P99 ≤ 200 ms per 1 MiB | Streaming encryption/decryption via `drive` |
| **Memory bound (10K items)** | ≤ 128 MiB resident | Vault state + SQLite connection + `crypto-vault` key hierarchy |
| **Argon2id parameterization** | Memory = 64 MiB, iterations = 3, parallelism = 4 | Default from `crypto-vault`; higher tiers configurable |
| **Scalability: max vault size** | 100,000 items | Hierarchical key derivation is O(1) per item; SQLite FTS5 scales with proper indexing |
| **Scalability: max attachment size** | 100 MiB | Streaming through `drive`; vault layer handles metadata only |

## Observability plan

All telemetry is **safe-by-construction**: no key material, no item content, no plaintext fields, no vault-specific identifiers, and no user data in spans, metrics, or logs.

### OTel spans and metrics

- `vault.unlock.duration` — histogram of unlock latency (no password, no secret key info)
- `vault.lock.duration` — histogram of lock latency (includes zeroization time)
- `vault.item.crud.duration` — histogram of item CRUD latency (no item type, no count)
- `vault.search.duration` — histogram of search latency (no query terms, no result count)
- `vault.sync.duration` — histogram of sync delegation latency (no direction, no vault ID)
- `vault.attachment.transfer.duration` — histogram of attachment upload/download latency (no size, no file name)
- `vault.state` — gauge of current vault state (`0 = locked`, `1 = unlocked`)
- Span names: `vault.unlock`, `vault.lock`, `vault.item.crud`, `vault.search`, `vault.sync`, `vault.attachment.transfer`

### Structured logging

Safe-to-log fields only:

- `event: "vault_unlocked"` — `durationMs`, `success`
- `event: "vault_locked"` — `durationMs`, `zeroizedBufferCount`
- `event: "item_created"` — `durationMs` (no item type, no field names)
- `event: "search_completed"` — `durationMs` (no query, no result count)
- `event: "sync_delegated"` — `durationMs`, `direction` (`pull`/`push`/`bidirectional`)
- `event: "attachment_transferred"` — `durationMs`, `operation` (`upload`/`download`)

### Error telemetry

- Aggregate error counts by `VaultError` code (e.g., `VAULT_LOCKED`, `ITEM_NOT_FOUND`, `SYNC_FAILED`).
- No vault ID, item ID, attachment name, or user context attached.

### Health checks

- `health.vault.unlock` — periodic test unlock with a synthetic config; fails if latency > 2× SLO.
- `health.vault.crud` — periodic create/get/delete of a synthetic item; fails on error or latency spike.
- `health.vault.search` — periodic FTS5 query over synthetic index; fails on error or latency spike.
- `health.vault.lock` — verifies lock triggers zeroization and state transition.

### Audit logging

- `audit.vault.unlock` — `timestamp`, `deviceIdHash`, `success` (no password, no key material).
- `audit.vault.lock` — `timestamp`, `deviceIdHash`, `zeroizedBufferCount`.
- `audit.vault.item.access` — `timestamp`, `deviceIdHash`, `operation` (`create`/`read`/`update`/`delete`), `itemTypeHash` (one-way hash of item type, not item ID).
- Retention: 90 days hot, 1 year cold.

## Dependency audit

| Dependency | Justification | Supply-chain risk | Tree-shakeable | License |
|---|---|---|---|---|
| `@suaveplan/crypto-vault` | Key hierarchy, 2SKD, `SecureBuffer`, zeroization | Internal monorepo; audited in CI | Yes | MIT |
| `@suaveplan/crypto` (subpaths `/keychain`, `/keychain/keypair`, `/keychain/storage`, `/authority`, `/vault`) | Keypair generation, validation, keychain storage adapters, Authority chain-of-trust (replaces upstream `ChainSigner`), low-level vault seal/open primitives consumed by the orchestration layer | Internal monorepo; audited in CI | Yes | MIT |
| `@suaveplan/db-sqlite` | Item storage, FTS5 search, history append | Internal monorepo | Yes | MIT |
| `@suaveplan/drive` | Attachment upload/download streaming | Internal monorepo | Yes | MIT |
| `@suaveplan/drive-sharing` | Share link creation/revocation | Internal monorepo | Yes | MIT |
| `@suaveplan/vault-sync` | Offline-first sync engine, CRDT merge | Internal monorepo; audited in CI | Yes | MIT |
| `@suaveplan/error` | Base error class | Internal monorepo | Yes | MIT |

**No external runtime dependencies.** All orchestration dependencies are internal monorepo packages. This eliminates hidden transitive dependencies and minimizes supply-chain attack surface.

## Operational readiness

### Graceful degradation

- If sync server is unreachable, the vault enters **offline mode**: reads and local mutations continue; sync is deferred to `vault-sync` queue.
- If attachment upload fails (network or storage quota), the item is saved locally and the attachment is queued for retry.
- If search index is corrupted, the vault falls back to **linear scan** with a warning telemetry event and schedules index rebuild.
- If `crypto-vault` derivation fails (bad password), unlock rejects immediately with `VaultError` — no silent downgrades.

### Resource limits

- **Max items per vault**: 100,000. Beyond this, creation is rejected with `VaultError`.
- **Max attachment size**: 100 MiB per file. Prevents memory exhaustion and storage abuse.
- **Max concurrent attachment transfers**: 3 per vault. Prevents network and memory saturation.
- **Max search query length**: 256 characters. Prevents pathological FTS5 queries.
- **Max offline sync queue depth**: 10,000 pending operations (enforced by `vault-sync`).

### Error recovery

- Unlock failures are non-retryable by design (bad password, bad config). Caller receives structured error code.
- Item CRUD failures trigger rollback of in-memory state; SQLite transaction ensures atomicity.
- Sync failures are retried with exponential backoff by `vault-sync` (base 2, max delay 60s, max 10 retries).
- Attachment transfer failures are retried up to 3 times; persistent failures queue for later retry.
- Search index corruption triggers automatic rebuild from encrypted item data on next unlock.

### Backup/restore compatibility

- Vault data is backed up as standard SQLite + encrypted attachments. No proprietary formats.
- Key hierarchy is fully deterministic from mnemonic + passphrase (stored in `crypto-vault`); restore re-derives identical keys.
- Sync queue is serialized as standard JSON with base64-encoded ciphertext fields — portable across platforms.
- Restore replays the sync queue in causal order; merging is deterministic.

### Upgrade/downgrade safety

- Vault item schema includes a version field. New versions can add optional fields; old versions ignore unknown fields.
- SQLite schema migrations are versioned and tested. Downgrade is supported to the previous minor version.
- Attachment format includes a version header. New encryption algorithms can be introduced alongside old ones.
- No key format migrations required for pure orchestration — math does not change.

### Key rotation without full re-encryption

- **Account password rotation**: Delegated to `crypto-vault`; re-derives AUK and re-encrypts personal keyset wrapper only. Vault keys and item keys remain unchanged.
- **Secret Key rotation**: Delegated to `crypto-vault`; re-derives AUK and re-encrypts personal keyset wrapper. Vault keys and item keys remain unchanged.
- **Vault key rotation**: Delegated to `crypto-vault`; derives new vault key from personal keyset. Item keys are re-encrypted under the new vault key (header-only change).
- **Item key rotation**: Delegated to `crypto-vault`; derives new item key from vault key. Re-encrypts single item only.
- **Sync encryption key rotation**: Delegated to `vault-sync`; re-encrypts pending queue entries and latest sync payload header.

## Verification approach

- `src/vault/vault.test.ts` — lifecycle (open/unlock/lock), state transitions, locked-operation rejection, re-unlock freshness
- `src/items/items.test.ts` — CRUD, encryption of concealed fields, history append, tombstone deletion, validation
- `src/search/search.test.ts` — FTS5 delegation, category/tag/favorite filters, concealed-field exclusion
- `src/attachments/attachments.test.ts` — upload/download round-trip, encryption, deletion, locked-state rejection
- `src/shares/shares.test.ts` — link creation/revocation, key-material exclusion, locked-state rejection
- `src/sync/sync.test.ts` — pull/push/bidirectional sync delegation, offline queue, locked-state rejection
- `src/error/error-codes.test.ts` — every error code is thrown by at least one production path
- `tests/dep-graph.test.ts` — dependency invariants (no circular deps with `crypto-vault`, `keys`, `drive`, `drive-sharing`, `vault-sync`)

### Coverage and quality targets

- **100% coverage target**: All source files must achieve 100% statement and branch coverage.
- **Property-based tests**: `fast-check` properties for vault lifecycle state transitions, item CRUD round-trip, search query safety, attachment upload/download round-trip, and sync delegation correctness.
- **Load/stress tests**: 10,000-item vault CRUD to verify memory bounds and latency SLOs; 100 concurrent unlock/lock cycles to verify zeroization and state machine robustness; 1,000 concurrent searches to verify FTS5 contention limits.
- **Security audit checklist**:
  - [ ] Argon2id memory cost ≥ 64 MiB enforced at runtime (delegated to `crypto-vault`)
  - [ ] All key material zeroized on lock (`vault.lock()` triggers `crypto-vault.zeroizeAll()`)
  - [ ] No plaintext key material in any log, error message, or `toString()` output
  - [ ] Concealed fields encrypted before persistence; no plaintext passwords in SQLite
  - [ ] Search blind indices do not reveal field values (HMAC with vault-scoped key)
  - [ ] Locked vault rejects all item, attachment, share, and sync operations
  - [ ] Vault state machine transitions are deterministic and enforced (no invalid states)
  - [ ] Share links never include key material or vault identifiers
- **Penetration test scenarios**:
  - [ ] Dump process memory after `vault.lock()` — verify no vault key, item key, or AUK material present
  - [ ] Attempt CRUD operation on locked vault — verify rejection with `VAULT_LOCKED` error
  - [ ] Fuzz search queries — verify no crashes, no information leakage, no SQL injection
  - [ ] Attempt direct SQLite access — verify concealed fields are ciphertext, not plaintext
  - [ ] Crash during attachment upload — verify no plaintext in crash dump or temp files

## Migration impact

None on genesis — additive only. `@suaveplan/keys` was never created on genesis; its responsibilities are already split across the existing `@suaveplan/crypto` subpaths. The vault layer is therefore a pure new-package landing with no source moves and no deprecation aliases.

Final ownership matrix on genesis:

- `@suaveplan/crypto/keychain` (existing) owns: `generateKeypair`, `validateKeypair`, `assertValidKeypair`, `Keychain` plus storage adapters.
- `@suaveplan/crypto/authority` (existing) owns: chain-of-trust signing — replaces upstream's `ChainedKeySigner`.
- `@suaveplan/crypto/vault` (existing) owns: low-level seal / open primitives (`sealPrivateKeyBlob`, `openPrivateKeyBlob`, `sealVaultPayload`, `openVaultPayload`, `changePassword`, `rotateApplicationData`, `LegacyVault`). Unchanged by this proposal.
- `@suaveplan/crypto-vault` (shipped) owns: BIP39, Argon2id, 2SKD, SRP-6a, key hierarchy, `SecureBuffer`, `OpaqueKeyHandle`.
- `@suaveplan/vault` (this change) owns: `Vault` lifecycle (`Vault.open` / `unlock` / `lock`), `VaultFactory`, item / attachment / share / sync orchestration, encrypted-field policy, `OpaqueKeyHandle` boundary enforcement.