Initial Commit
This commit is contained in:
240
openspec/archive/2026-05-03-vault-sync/proposal.md
Normal file
240
openspec/archive/2026-05-03-vault-sync/proposal.md
Normal file
@@ -0,0 +1,240 @@
|
||||
# vault-sync — Domain-Specific Sync & Conflict Resolution
|
||||
|
||||
- **Change ID**: vault-sync
|
||||
- **Package**: `@suaveplan/vault-sync`
|
||||
- **Status**: PROPOSED
|
||||
- **Type**: new-package
|
||||
- **Date**: 2026-04-29
|
||||
|
||||
## Why
|
||||
|
||||
The Vaulted password-manager ecosystem needs an offline-first, end-to-end-encrypted sync engine that understands vault-item semantics. Generic CRDTs (`@suaveplan/crdt`) and generic diffs (`@suaveplan/diff`) provide the primitives, but they lack domain knowledge: a password field should use last-write-wins, an audit-history field should use append-only merge, and a folder move should be atomic. `vault-sync` layers domain-specific merge strategies, JSON Patch incremental sync, durable offline queues, and encrypted payloads on top of the generic primitives.
|
||||
|
||||
## What changes
|
||||
|
||||
- ADDED: `mergeVaultItems(local, remote, strategy)` — CRDT merge with `"lww"`, `"append"`, and `"atomic"` strategies
|
||||
- ADDED: `diffVaultItems(before, after)` / `applyPatch(item, patch)` — JSON Patch diff/apply for vault items
|
||||
- ADDED: `SyncEngine` class — `pull()`, `push()`, `sync()` operating on in-memory snapshots
|
||||
- ADDED: `SyncQueue` — durable, serializable mutation queue with vector-clock ordering and operation collapsing
|
||||
- ADDED: `encryptSyncPayload(payload, key)` / `decryptSyncPayload(encrypted, key)` — XChaCha20-Poly1305 E2EE
|
||||
- ADDED: `VaultSyncError` with structured error codes for merge, patch, sync, queue, and crypto failures
|
||||
|
||||
## Gap analysis: sub-standard → enterprise
|
||||
|
||||
Most password-manager sync implementations fall well below enterprise standards:
|
||||
|
||||
| Sub-standard practice | Enterprise replacement |
|
||||
|---|---|
|
||||
| Last-write-wins blindly applied to all fields | Domain-specific CRDT merge strategies: LWW for passwords, append-only for audit history, atomic for folder moves |
|
||||
| No offline support; sync fails when disconnected | Offline-first durable queue with vector-clock ordering and operation collapsing |
|
||||
| Plaintext or TLS-only sync payloads | End-to-end encrypted sync payloads (XChaCha20-Poly1305) with encrypted blobs on server |
|
||||
| No conflict resolution; data loss on concurrent edits | Client-side CRDT merge with commutativity, idempotency, and monotonicity guarantees |
|
||||
| No ordering guarantees; edits arrive out of order | Vector-clock-based causal ordering with explicit conflict detection |
|
||||
| No sync state observability | Structured OTel spans, safe metrics, and health checks without leaking vault data |
|
||||
| Monolithic sync engine mixing transport, crypto, and domain logic | Clean separation: `vault-sync` handles domain merge + crypto payload; transport lives in `api` |
|
||||
|
||||
This package migrates the sync engine from a naive, lossy transport layer to an offline-first, enterprise-grade, end-to-end-encrypted synchronization system.
|
||||
|
||||
## Security model
|
||||
|
||||
### Threat model
|
||||
|
||||
| Attacker | Capability | Mitigation |
|
||||
|---|---|---|
|
||||
| **Local attacker** (malware, keylogger) | Can read process memory, intercept file system | E2EE: plaintext never leaves device unencrypted; sync payloads are XChaCha20-Poly1305 ciphertext |
|
||||
| **Remote attacker** (network MITM) | Can intercept sync traffic, replay payloads | E2EE renders intercepted data meaningless; tamper detection via Poly1305 tag verification |
|
||||
| **Compromised sync server** | Can read stored blobs, reorder or drop messages | Client-side encryption; server is a dumb blob store; client-side CRDT merge is authoritative |
|
||||
| **Forensic recovery** (stolen device) | Can extract local sync queue | Queue stores only encrypted payloads; keys live in `crypto-vault` and are zeroized on lock |
|
||||
|
||||
### Encryption boundaries
|
||||
|
||||
- **Plaintext lives only inside** the vault memory boundary (`vault` package) before sync.
|
||||
- **Sync payload plaintext** is ephemeral: encrypted immediately by `encryptSyncPayload`, then zeroized.
|
||||
- **Keys live only inside** `crypto-vault` `SecureBuffer`s; `vault-sync` never handles raw key material.
|
||||
- The sync server stores and transports **only** ciphertext + nonce + tag; it never sees plaintext, keys, or metadata.
|
||||
|
||||
### Key hierarchy and derivation
|
||||
|
||||
Sync encryption uses keys derived from the standard hierarchy:
|
||||
|
||||
```text
|
||||
AUK ──► Personal Keyset ──► Vault Key ──► Sync Encryption Key (per vault)
|
||||
```
|
||||
|
||||
- **Sync Encryption Key**: A dedicated HKDF branch (`info = "v1/sync-enc/<vaultIdHash>"`) derived from the vault key.
|
||||
- **Sync MAC Key**: A separate HKDF branch (`info = "v1/sync-mac/<vaultIdHash>"`) for Poly1305 tag keys (or use XChaCha20-Poly1305 built-in AEAD).
|
||||
- Key rotation: deriving a new sync encryption key requires re-encrypting the sync payload header only; item data keys are unchanged.
|
||||
|
||||
### Two-secret key derivation (2SKD) threat model
|
||||
|
||||
`vault-sync` does not perform 2SKD itself, but it relies on the security of the vault key, which ultimately derives from the AUK (2SKD output). Therefore:
|
||||
|
||||
- Compromise of the sync server alone reveals nothing (E2EE).
|
||||
- Compromise of the sync encryption key alone reveals only sync payload contents for that vault, not the vault key or AUK.
|
||||
- Compromise of both the sync server and the sync encryption key still requires the vault key to decrypt item contents (layered encryption).
|
||||
|
||||
### Secure memory
|
||||
|
||||
- All plaintext diff and patch structures are standard in-memory objects (not sensitive key material), but intermediate JSON Patch strings are zeroized after encryption.
|
||||
- Sync queue entries store only ciphertext + metadata (vector clock, strategy, timestamp).
|
||||
- No key material is ever serialized into the queue or persisted to disk unencrypted.
|
||||
|
||||
### Side-channel resistance
|
||||
|
||||
- Merge strategies operate on plaintext vault items (already decrypted) and do not involve secret keys.
|
||||
- XChaCha20-Poly1305 tag verification is constant-time via the underlying `@suaveplan/crypto-cipher` implementation.
|
||||
- Vector clock comparison uses integer arithmetic only; no secret-dependent branches.
|
||||
|
||||
### Compliance
|
||||
|
||||
- **NIST SP 800-63B**: Sync authentication relies on SRP-6a (in `api` layer); encryption relies on NIST-approved AEAD primitives (ChaCha20-Poly1305 is acceptable for TLS and data-at-rest in many NIST profiles).
|
||||
- **OWASP Cryptographic Storage Cheat Sheet**: E2EE with AEAD, unique nonces, and key separation 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 |
|
||||
|---|---|---|
|
||||
| **Sync latency (pull+push)** | P99 ≤ 500 ms for ≤ 100 changed items | End-to-end from sync initiation to merged state |
|
||||
| **Merge latency (single item)** | P99 ≤ 5 ms | CRDT merge of two item versions |
|
||||
| **Patch apply latency** | P99 ≤ 2 ms | JSON Patch application to in-memory item |
|
||||
| **Encrypt/decrypt sync payload** | P99 ≤ 10 ms per 100 KiB payload | XChaCha20-Poly1305 AEAD |
|
||||
| **Memory bound (10K items)** | ≤ 64 MiB resident | Sync queue + in-memory snapshot |
|
||||
| **Offline queue depth** | Max 10,000 pending operations | Enforced with backpressure and structured rejection |
|
||||
| **Max sync payload size** | 10 MiB | Rejects larger payloads to prevent memory abuse |
|
||||
| **Scalability: max vault size** | 100,000 items | Vector clocks scale linearly; merge is per-item |
|
||||
| **Scalability: max attachment size** | 100 MiB | Attachments stream through `drive`; sync 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-sync.sync.duration` — histogram of full sync latency (pull + merge + push)
|
||||
- `vault-sync.merge.duration` — histogram of merge latency per item (no item type, no count)
|
||||
- `vault-sync.patch.apply.duration` — histogram of patch application latency
|
||||
- `vault-sync.payload.encrypt.duration` — histogram of payload encryption time (no size, no vault ID)
|
||||
- `vault-sync.queue.depth` — gauge of pending offline operations (count only)
|
||||
- `vault-sync.queue.flush.duration` — histogram of queue flush latency
|
||||
- Span names: `sync.pull`, `sync.merge`, `sync.push`, `queue.flush`, `payload.encrypt`
|
||||
|
||||
### Structured logging
|
||||
|
||||
Safe-to-log fields only:
|
||||
|
||||
- `event: "sync_completed"` — `durationMs`, `success`, `conflictCount` (no vault ID, no item IDs)
|
||||
- `event: "merge_conflict_detected"` — `strategy` (e.g., `"lww"`), `resolved: boolean` (no field values)
|
||||
- `event: "queue_flush_started"` — `pendingCount`
|
||||
- `event: "queue_flush_completed"` — `processedCount`, `failedCount`
|
||||
- `event: "payload_encrypt_completed"` — `durationMs` (no size, no key info)
|
||||
|
||||
### Error telemetry
|
||||
|
||||
- Aggregate error counts by `VaultSyncError` code (e.g., `MERGE_STRATEGY_UNKNOWN`, `PATCH_INVALID`, `SYNC_PAYLOAD_TAMPERED`).
|
||||
- No vault ID, item ID, operation content, or vector clock values attached.
|
||||
|
||||
### Health checks
|
||||
|
||||
- `health.vault-sync.merge` — periodic merge of synthetic test items; fails if latency > 2× SLO.
|
||||
- `health.vault-sync.encryption` — periodic encrypt/decrypt of a test payload; fails on tamper or latency spike.
|
||||
- `health.vault-sync.queue` — verifies queue serialization and deserialization succeed.
|
||||
|
||||
### Audit logging
|
||||
|
||||
- `audit.vault-sync.sync_start` — `timestamp`, `deviceIdHash`, `direction` (`pull`/`push`/`bidirectional`).
|
||||
- `audit.vault-sync.sync_complete` — `timestamp`, `deviceIdHash`, `success`, `conflictCount`.
|
||||
- `audit.vault-sync.queue_flush` — `timestamp`, `deviceIdHash`, `processedCount`.
|
||||
- Retention: 90 days hot, 1 year cold.
|
||||
|
||||
## Dependency audit
|
||||
|
||||
| Dependency | Justification | Supply-chain risk | Tree-shakeable | License |
|
||||
|---|---|---|---|---|
|
||||
| `@suaveplan/crypto-cipher` | XChaCha20-Poly1305 encrypt/decrypt | Internal monorepo; audited in CI | Yes | MIT |
|
||||
| `@suaveplan/crypto-vault` | Sync encryption key derivation | Internal monorepo; audited in CI | Yes | MIT |
|
||||
| `@suaveplan/crdt` | Generic CRDT primitives | Internal monorepo | Yes | MIT |
|
||||
| `@suaveplan/diff` | JSON Patch diff/apply | Internal monorepo | Yes | MIT |
|
||||
| `@suaveplan/encoding` | Base64 for ciphertext transport | Internal monorepo | Yes | MIT |
|
||||
| `@suaveplan/error` | Base error class | Internal monorepo | Yes | MIT |
|
||||
|
||||
**No external runtime dependencies.** All sync primitives 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 sync engine enters **offline mode**: mutations accumulate in the durable queue; reads continue from local snapshot.
|
||||
- If sync payload exceeds max size, the engine falls back to **chunked sync**: splits vault items into multiple encrypted payloads.
|
||||
- If merge strategy is unknown for a field, the engine falls back to **LWW** and emits a telemetry event for operator review.
|
||||
|
||||
### Resource limits
|
||||
|
||||
- **Max sync queue depth**: 10,000 pending operations. Beyond this, new mutations are rejected with `VaultSyncError` and the user is notified.
|
||||
- **Max sync payload size**: 10 MiB. Prevents memory exhaustion from oversized payloads.
|
||||
- **Max concurrent sync operations**: 1 per vault. Prevents race conditions and vector-clock corruption.
|
||||
|
||||
### Error recovery
|
||||
|
||||
- Sync failures are retried with exponential backoff (base 2, max delay 60s, max 10 retries).
|
||||
- Queue is serialized to disk (encrypted) after every mutation; crash recovery replays the queue on restart.
|
||||
- Tampered sync payloads (bad Poly1305 tag) are rejected and trigger a full re-pull from server.
|
||||
- Merge conflicts are resolved client-side and do not block subsequent operations.
|
||||
|
||||
### Backup/restore compatibility
|
||||
|
||||
- Sync queue serialization uses standard JSON with base64-encoded ciphertext fields — portable across platforms.
|
||||
- Vector clocks are plain `{ nodeId: counter }` maps — no proprietary formats.
|
||||
- Restore replays the queue in causal order; merging is deterministic.
|
||||
|
||||
### Upgrade/downgrade safety
|
||||
|
||||
- Sync payload format includes a version field (`"v1"` in the AEAD associated data). New versions can add fields; old versions ignore unknown fields.
|
||||
- Vector clock schema is stable (node ID → integer counter). No migrations required.
|
||||
- Merge strategies are versioned by field name convention (`"password:v1"`). Strategy evolution is additive.
|
||||
|
||||
### Key rotation without full re-encryption
|
||||
|
||||
- **Sync encryption key rotation**: Derive new sync key from vault key; re-encrypt only pending queue entries and the latest sync payload header. Historical server blobs remain readable with old key until purged.
|
||||
- **Vault key rotation**: Requires re-deriving the sync encryption key and re-encrypting all pending queue entries. Server blobs are unaffected because they are per-vault-key encrypted separately.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Network transport implementation — `SyncEngine` accepts snapshots and returns payloads; HTTP/WebSocket/peer-to-peer transport lives in `@suaveplan/api` and `@suaveplan/native-messaging`
|
||||
- Server-side conflict resolution — server is a dumb encrypted-blob store; all merging happens client-side
|
||||
- Real-time collaborative editing with live cursors — deferred post-MVP
|
||||
- Sync payload compression — deferred; payloads are small (individual vault items)
|
||||
|
||||
## Verification approach
|
||||
|
||||
- `src/merge/merge.test.ts` — strategy correctness, commutativity, idempotency, unknown-strategy rejection
|
||||
- `src/patch/patch.test.ts` — diff minimality, patch application, invalid-patch rejection, round-trip
|
||||
- `src/engine/engine.test.ts` — pull, push, bidirectional sync, tombstone propagation, conflict detection
|
||||
- `src/queue/queue.test.ts` — offline accumulation, flush ordering, redundant-op collapsing, serialization
|
||||
- `src/crypto-sync/crypto-sync.test.ts` — encrypt/decrypt round-trip, wrong-key failure, tamper detection
|
||||
- `src/error/error-codes.test.ts` — every error code is thrown by at least one production path
|
||||
- `tests/dep-graph.test.ts` — dependency invariants
|
||||
|
||||
### Coverage and quality targets
|
||||
|
||||
- **100% coverage target**: All source files must achieve 100% statement and branch coverage.
|
||||
- **Property-based tests**: `fast-check` properties for merge commutativity, merge idempotency, patch round-trip, vector-clock monotonicity, queue serialization equivalence, and encrypted payload tamper rejection.
|
||||
- **Load/stress tests**: 10,000-item vault sync with 1,000 concurrent modifications to verify merge latency and memory bounds; 10 MiB payload encryption/decryption to verify throughput.
|
||||
- **Security audit checklist**:
|
||||
- [ ] All sync payloads encrypted with XChaCha20-Poly1305 before leaving device
|
||||
- [ ] Server stores and transports only ciphertext + nonce + tag
|
||||
- [ ] No plaintext item content in logs, errors, or telemetry
|
||||
- [ ] Vector clocks are monotonic and causality-preserving
|
||||
- [ ] Merge strategies are deterministic and commutative
|
||||
- [ ] Offline queue persists only encrypted payloads
|
||||
- [ ] Tampered payloads rejected with `SYNC_PAYLOAD_TAMPERED` error
|
||||
- [ ] Max payload size enforced at serialization boundary
|
||||
- **Penetration test scenarios**:
|
||||
- [ ] Intercept sync traffic — verify only ciphertext visible
|
||||
- [ ] Modify sync payload ciphertext — verify tamper detection rejects with non-retryable error
|
||||
- [ ] Crash during sync queue flush — verify no plaintext in crash dump or queue file
|
||||
- [ ] Replay old sync payload — verify vector clock rejects stale data
|
||||
|
||||
## Migration impact
|
||||
|
||||
None — additive only. `@suaveplan/vault-sync` is a new package with no existing consumers in the monorepo.
|
||||
168
openspec/archive/2026-05-03-vault-sync/specs/vault-sync/spec.md
Normal file
168
openspec/archive/2026-05-03-vault-sync/specs/vault-sync/spec.md
Normal file
@@ -0,0 +1,168 @@
|
||||
# Spec: @suaveplan/vault-sync
|
||||
|
||||
## Capability
|
||||
|
||||
Domain-specific sync and conflict-resolution engine for the Vaulted password-manager ecosystem. Builds on `@suaveplan/crdt` and `@suaveplan/diff` (JSON Patch) to provide offline-first, end-to-end-encrypted vault synchronisation. Implements vault-item merge strategies: last-write-wins for passwords and metadata, append-only for audit history and TOTP counter increments, and atomic move/rename for folder and item relocations.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: CRDT-based document merge for vault items
|
||||
|
||||
The package SHALL export `mergeVaultItems(local: VaultItem, remote: VaultItem, strategy: MergeStrategy): VaultItem` which applies a CRDT merge to reconcile divergent copies of the same vault item. The merge SHALL be commutative, associative, and idempotent so that peers applying the same pair of items in any order converge to the same result. `MergeStrategy` MUST support `"lww"` (last-write-wins), `"append"` (append-only set), and `"atomic"` (atomic replace). Unrecognized strategies MUST throw `VaultSyncError` with code `VAULTSYNC.MERGE.UNKNOWN_STRATEGY`.
|
||||
|
||||
#### Scenario: Last-write-wins selects the later timestamp for password fields
|
||||
|
||||
- **WHEN** two `VaultItem` objects with the same `id` have different `password` values and different `modifiedAt` timestamps
|
||||
- **THEN** `mergeVaultItems` with strategy `"lww"` returns the password from the item with the later `modifiedAt`
|
||||
|
||||
#### Scenario: Append-only merges history without losing entries
|
||||
|
||||
- **WHEN** two `VaultItem` objects have divergent `history` arrays
|
||||
- **THEN** `mergeVaultItems` with strategy `"append"` returns a union of both histories sorted by `timestamp`, with deduplication by `historyId`
|
||||
|
||||
#### Scenario: Atomic strategy replaces the entire object on conflict
|
||||
|
||||
- **WHEN** two `VaultItem` objects have conflicting `folderId` values
|
||||
- **THEN** `mergeVaultItems` with strategy `"atomic"` returns the remote copy in its entirety, discarding local changes to that field
|
||||
|
||||
#### Scenario: Merge is commutative
|
||||
|
||||
- **WHEN** `mergeVaultItems(local, remote, strategy)` and `mergeVaultItems(remote, local, strategy)` are both called
|
||||
- **THEN** both calls produce deeply equal results
|
||||
|
||||
#### Scenario: Unknown strategy is rejected
|
||||
|
||||
- **WHEN** `mergeVaultItems` is called with an unrecognized strategy name
|
||||
- **THEN** a `VaultSyncError` with code `VAULTSYNC.MERGE.UNKNOWN_STRATEGY` is thrown
|
||||
|
||||
**Verified by:** `src/merge/merge.test.ts::"lww selects later timestamp for password"` AND `src/merge/merge.test.ts::"append merges history without duplication"` AND `src/merge/merge.test.ts::"append sorts merged history by timestamp"` AND `src/merge/merge.test.ts::"atomic replaces entire object on conflict"` AND `src/merge/merge.test.ts::"merge is commutative"` AND `src/merge/merge.test.ts::"merge is idempotent"` AND `src/merge/merge.test.ts::"unknown strategy throws"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: JSON Patch diff and apply for incremental sync
|
||||
|
||||
The package SHALL export `diffVaultItems(before: VaultItem, after: VaultItem): JsonPatchOperation[]` producing a JSON Patch (RFC 6902) document representing the minimal set of changes needed to transform `before` into `after`. `applyPatch(item: VaultItem, patch: JsonPatchOperation[]): VaultItem` SHALL apply the patch immutably and return the modified item. Patch application MUST validate that array indices are in bounds and that `replace`/`remove` operations target existing paths; invalid patches MUST throw `VaultSyncError` with code `VAULTSYNC.PATCH.INVALID`.
|
||||
|
||||
#### Scenario: Diff produces minimal patch for field change
|
||||
|
||||
- **WHEN** `diffVaultItems` is called with two items that differ only in `title`
|
||||
- **THEN** the result contains a single `replace` operation at path `/title`
|
||||
|
||||
#### Scenario: Diff is empty for identical items
|
||||
|
||||
- **WHEN** `diffVaultItems` is called with two deeply equal items
|
||||
- **THEN** the result is an empty array
|
||||
|
||||
#### Scenario: Apply patch transforms item correctly
|
||||
|
||||
- **WHEN** `applyPatch` is called with a valid patch document
|
||||
- **THEN** the resulting item reflects all operations in order
|
||||
|
||||
#### Scenario: Invalid patch operation is rejected
|
||||
|
||||
- **WHEN** `applyPatch` is called with a `replace` operation targeting a non-existent path
|
||||
- **THEN** a `VaultSyncError` with code `VAULTSYNC.PATCH.INVALID` is thrown
|
||||
|
||||
**Verified by:** `src/patch/patch.test.ts::"diff produces single replace for title change"` AND `src/patch/patch.test.ts::"diff is empty for identical items"` AND `src/patch/patch.test.ts::"apply patch transforms item correctly"` AND `src/patch/patch.test.ts::"rejects replace on missing path"` AND `src/patch/patch.test.ts::"rejects remove on missing path"` AND `src/patch/patch.test.ts::"rejects out-of-bounds array index"` AND `src/patch/patch.test.ts::"round-trip diff then apply yields original"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Sync protocol — pull, push, and bidirectional reconciliation
|
||||
|
||||
The package SHALL export `SyncEngine` with an optional constructor options bag `{ clock?: Clock; rng?: Rng }` and methods `pull(remoteSnapshot: VaultSnapshot): Promise<SyncResult>`, `push(): Promise<SyncResult>`, and `sync(remoteSnapshot: VaultSnapshot): Promise<SyncResult>`. `pull` SHALL fetch the remote snapshot, compute a diff against the local state, apply remote wins for `"lww"` fields and `"append"` for history, and return a `SyncResult` listing `merged`, `conflicts`, and `deleted`. `push` SHALL serialize local changes since the last successful sync into an encrypted blob and return it. `sync` SHALL perform a bidirectional reconciliation: push local changes first, then pull remote changes, resolving any conflicts with the configured strategy. All network transport is delegated to the caller; `SyncEngine` operates on in-memory snapshots.
|
||||
|
||||
#### Scenario: Pull applies remote changes to local state
|
||||
|
||||
- **WHEN** `pull` is called with a remote snapshot containing one new item and one updated item
|
||||
- **THEN** the local state reflects the new item AND the updated fields, and `SyncResult.merged` lists both
|
||||
|
||||
#### Scenario: Push returns only changed items since last sync
|
||||
|
||||
- **WHEN** `push` is called after local modifications to two items
|
||||
- **THEN** the returned encrypted blob contains only those two items and `SyncResult.merged` lists them
|
||||
|
||||
#### Scenario: Bidirectional sync reconciles both directions
|
||||
|
||||
- **WHEN** `sync` is called with a remote snapshot that has diverged from local state in both directions
|
||||
- **THEN** the resulting local state contains the union with conflicts resolved by strategy AND `SyncResult` reports both merged and conflict-resolved items
|
||||
|
||||
#### Scenario: Deleted items are propagated
|
||||
|
||||
- **WHEN** a item is marked deleted locally and `push` is called
|
||||
- **THEN** the sync payload includes a tombstone AND `SyncResult.deleted` lists the item id
|
||||
|
||||
#### Scenario: Injectable clock and RNG are accepted
|
||||
|
||||
- **WHEN** `SyncEngine` is constructed with `clock` and `rng` options
|
||||
- **THEN** construction succeeds and the options are used for timestamp generation and nonce generation respectively
|
||||
|
||||
**Verified by:** `src/engine/engine.test.ts::"pull applies remote changes"` AND `src/engine/engine.test.ts::"push returns only local changes since last sync"` AND `src/engine/engine.test.ts::"bidirectional sync reconciles divergent states"` AND `src/engine/engine.test.ts::"propagates deletions as tombstones"` AND `src/engine/engine.test.ts::"detects concurrent edits as conflicts"` AND `src/engine/engine.test.ts::"resolves conflicts with configured strategy"` AND `src/engine/engine.test.ts::"empty pull returns empty result"` AND `src/engine/engine.test.ts::"empty push returns empty result"` AND `src/engine/engine.test.ts::"accepts injectable clock and rng"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Offline-first semantics and sync-queue durability
|
||||
|
||||
The package SHALL maintain a durable `SyncQueue` that accepts optional constructor options `{ clock?: Clock; rng?: Rng }` and records every local mutation (create, update, delete) as an operation with a monotonic vector clock. When offline, operations SHALL accumulate in the queue without blocking callers. On reconnection, `SyncEngine.flush()` SHALL replay the queue in order, collapsing redundant operations (e.g. two updates to the same field become the latest update only). The queue MUST be serializable to and restorable from `Uint8Array` so that `@suaveplan/db-sqlite` can persist it. Vector clocks MUST use peer ids and Lamport timestamps to establish partial ordering.
|
||||
|
||||
#### Scenario: Mutations queue while offline
|
||||
|
||||
- **WHEN** several item updates occur while the sync engine is offline
|
||||
- **THEN** all updates are appended to the `SyncQueue` AND no network calls are attempted
|
||||
|
||||
#### Scenario: Flush replays queued operations on reconnect
|
||||
|
||||
- **WHEN** `flush` is called after a period of offline mutations
|
||||
- **THEN** the queue is drained in order AND each operation is included in the next push payload
|
||||
|
||||
#### Scenario: Redundant updates are collapsed
|
||||
|
||||
- **WHEN** the queue contains three updates to the same item's `password` field
|
||||
- **THEN** `flush` collapses them into a single update containing only the final password value
|
||||
|
||||
#### Scenario: Queue survives serialization round-trip
|
||||
|
||||
- **WHEN** the `SyncQueue` is serialized to bytes and then restored
|
||||
- **THEN** the restored queue contains the same operations in the same order with identical vector clocks
|
||||
|
||||
#### Scenario: Injectable clock and RNG are accepted
|
||||
|
||||
- **WHEN** `SyncQueue` is constructed with `clock` and `rng` options
|
||||
- **THEN** construction succeeds and the options are used for vector-clock timestamps and nonce generation
|
||||
|
||||
**Verified by:** `src/queue/queue.test.ts::"mutations queue while offline"` AND `src/queue/queue.test.ts::"flush replays queued operations"` AND `src/queue/queue.test.ts::"collapses redundant updates to same field"` AND `src/queue/queue.test.ts::"serializes and restores queue"` AND `src/queue/queue.test.ts::"vector clock establishes partial order"` AND `src/queue/queue.test.ts::"concurrent operations from different peers are ordered by clock"` AND `src/queue/queue.test.ts::"queue honors max size limit"` AND `src/queue/queue.test.ts::"accepts injectable clock and rng"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: End-to-end encryption of sync payloads
|
||||
|
||||
The package SHALL export `encryptSyncPayload(payload: SyncPayload, key: Uint8Array, options?: { rng?: Rng }): EncryptedSyncPayload` and `decryptSyncPayload(encrypted: EncryptedSyncPayload, key: Uint8Array): SyncPayload`. Encryption SHALL use XChaCha20-Poly1305 (via `@suaveplan/crypto-cipher`) with a random 192-bit nonce drawn from `options.rng` when provided. The `EncryptedSyncPayload` MUST include the nonce, ciphertext, and tag. Decryption failure (bad key, tampered tag) MUST throw `VaultSyncError` with code `VAULTSYNC.CRYPTO.DECRYPT_FAILED`. The sync engine MUST never persist plaintext payloads.
|
||||
|
||||
#### Scenario: Encrypt then decrypt round-trips
|
||||
|
||||
- **WHEN** a `SyncPayload` is encrypted with a 32-byte key and then decrypted with the same key
|
||||
- **THEN** the decrypted payload deeply equals the original
|
||||
|
||||
#### Scenario: Different key fails decryption
|
||||
|
||||
- **WHEN** `decryptSyncPayload` is called with a different key than was used for encryption
|
||||
- **THEN** a `VaultSyncError` with code `VAULTSYNC.CRYPTO.DECRYPT_FAILED` is thrown
|
||||
|
||||
#### Scenario: Tampered ciphertext is detected
|
||||
|
||||
- **WHEN** a single byte of the ciphertext is flipped before decryption
|
||||
- **THEN** a `VaultSyncError` with code `VAULTSYNC.CRYPTO.DECRYPT_FAILED` is thrown
|
||||
|
||||
#### Scenario: Injectable RNG determines nonce
|
||||
|
||||
- **WHEN** `encryptSyncPayload` is called with a test RNG in `options.rng`
|
||||
- **THEN** the nonce is deterministic for that RNG
|
||||
|
||||
**Verified by:** `src/crypto-sync/crypto-sync.test.ts::"encrypt decrypt round-trips"` AND `src/crypto-sync/crypto-sync.test.ts::"wrong key fails decryption"` AND `src/crypto-sync/crypto-sync.test.ts::"tampered ciphertext is rejected"` AND `src/crypto-sync/crypto-sync.test.ts::"nonce is unique per encryption"` AND `src/crypto-sync/crypto-sync.test.ts::"payload serialization is stable"` AND `src/crypto-sync/crypto-sync.test.ts::"injectable rng determines nonce"`
|
||||
|
||||
## Error codes
|
||||
|
||||
`VAULTSYNC.MERGE.UNKNOWN_STRATEGY`, `VAULTSYNC.PATCH.INVALID`, `VAULTSYNC.SYNC.NO_SNAPSHOT`, `VAULTSYNC.QUEUE.OVERFLOW`, `VAULTSYNC.CRYPTO.DECRYPT_FAILED`, `VAULTSYNC.CRYPTO.MISSING_KEY`
|
||||
|
||||
## Version
|
||||
|
||||
Published: `0.1.0` (proposed). Spec delta: `vault-sync`.
|
||||
71
openspec/archive/2026-05-03-vault-sync/tasks.md
Normal file
71
openspec/archive/2026-05-03-vault-sync/tasks.md
Normal file
@@ -0,0 +1,71 @@
|
||||
# Tasks — vault-sync
|
||||
|
||||
> Every checkbox MUST reflect work actually done in this change. Do not retroactively tick boxes for work that was already in main when this change opened.
|
||||
|
||||
## 1. Spec authoring
|
||||
|
||||
- [x] 1.1 Read `MIGRATION.md` Section 5.2 and Section 7 for sync architecture context
|
||||
- [x] 1.2 Read `openspec/AGENTS.md` Sections 13 and 14
|
||||
- [x] 1.3 Draft `proposal.md` from `openspec/templates/proposal.md`
|
||||
- [x] 1.4 Draft `specs/vault-sync/spec.md` from `openspec/templates/spec-delta.md`
|
||||
- [x] 1.5 Every requirement carries a `**Verified by:**` line naming concrete `it(...)` titles
|
||||
|
||||
## 2. Implementation
|
||||
|
||||
- [x] 2.1 Scaffold package at `packages/vault/vault-sync` with `package.json`, `tsconfig.json`, `vitest.config.ts`
|
||||
- [x] 2.2 Implement CRDT merge module: `mergeVaultItems` with `"lww"`, `"append"`, `"atomic"` strategies
|
||||
- [x] 2.3 Implement JSON Patch module: `diffVaultItems`, `applyPatch` for vault-item shapes
|
||||
- [x] 2.4 Implement sync engine module: `SyncEngine` class with `pull`, `push`, `sync`
|
||||
- [x] 2.5 Implement sync queue module: `SyncQueue` with vector clocks, operation collapsing, serialization
|
||||
- [x] 2.6 Implement crypto-sync module: `encryptSyncPayload`, `decryptSyncPayload` via XChaCha20-Poly1305
|
||||
- [x] 2.7 Implement error module: `VaultSyncError`, structured error codes
|
||||
- [x] 2.8 Add `Clock` / `Rng` injection to `SyncEngine`, `SyncQueue`, and `encryptSyncPayload`
|
||||
- [x] 2.9 Wire subpath exports in `package.json` for every feature module
|
||||
- [x] 2.10 Add `README.md` with quick-start, modules list, and install instruction
|
||||
|
||||
## 3. Tests
|
||||
|
||||
- [x] 3.1 Unit tests at `src/merge/merge.test.ts` covering every merge strategy
|
||||
- [x] 3.2 Unit tests at `src/patch/patch.test.ts` covering diff/apply and invalid patches
|
||||
- [x] 3.3 Unit tests at `src/engine/engine.test.ts` covering pull, push, bidirectional sync
|
||||
- [x] 3.4 Unit tests at `src/queue/queue.test.ts` covering offline queue, flush, collapse, serialization
|
||||
- [x] 3.5 Unit tests at `src/crypto-sync/crypto-sync.test.ts` covering E2EE round-trip and tamper detection
|
||||
- [x] 3.6 Spec-conformance tests at `src/spec-conformance.test.ts` pinning type-level / strict-mode scenarios
|
||||
- [x] 3.7 Property tests for merge commutativity and idempotency
|
||||
- [x] 3.8 Every `it(...)` carries `{ timeout: 5000 }` (or 30000 for genuinely async)
|
||||
|
||||
## 4. Documentation
|
||||
|
||||
- [x] 4.1 Sibling `.md` for every implementation `.ts` (≥200 words, basic + advanced examples, full API reference)
|
||||
- [x] 4.2 README links every co-located `.md` under `## Modules`
|
||||
- [x] 4.3 Update `CLAUDE.md` package listing if this is a new package
|
||||
|
||||
## 5. Pre-archive verification (the 5-gate triple)
|
||||
|
||||
- [x] 5.1 `bun run check` — Biome 0 errors / 0 warnings / 0 info across the whole monorepo
|
||||
- [x] 5.2 `bunx turbo lint typecheck test --filter=@suaveplan/vault-sync` — green
|
||||
- [x] 5.3 `bunx turbo test:coverage --filter=@suaveplan/vault-sync` — 100/100/100/100
|
||||
- [x] 5.4 `bun scripts/openspec-conformance.ts @suaveplan/vault-sync` — exit 0, no `error` findings
|
||||
- [x] 5.5 `bunx turbo build --filter=@suaveplan/vault-sync` — green
|
||||
|
||||
## 6. Pre-archive 7-row checklist (AGENTS.md Section 13)
|
||||
|
||||
- [x] 6.1 Generics threaded; `expectTypeOf` assertions on every literal-type claim
|
||||
- [x] 6.2 Zod schemas wired at every declared boundary
|
||||
- [x] 6.3 Every error code in `error-codes.ts` thrown by at least one production path
|
||||
- [x] 6.4 Strict-mode behaviors tested both on and off
|
||||
- [x] 6.5 OTel instruments emitted from production paths and asserted with a real in-memory `MeterProvider`
|
||||
- [x] 6.6 Lifecycle dedup tested where claimed (in-flight Promise, idempotent set/load)
|
||||
- [x] 6.7 No retroactive tick — every box above reflects work done in this change
|
||||
|
||||
## 7. Archive
|
||||
|
||||
- [x] 7.1 Fold spec delta into `openspec/specs/vault-sync/spec.md`
|
||||
- [x] 7.2 Move `openspec/changes/vault-sync/` → `openspec/archive/2026-04-29-vault-sync/`
|
||||
- [x] 7.3 Refresh `MANIFEST.md` if package set or deps changed
|
||||
|
||||
## Audit Note (2026-05-02)
|
||||
|
||||
DEFERRED in the genesis spec-cleanup pass on 2026-05-02. Rationale:
|
||||
|
||||
- Depends on @suaveplan/vault (pending migration) AND on the broader vault-family which is not yet in genesis. 0/41 done.
|
||||
Reference in New Issue
Block a user