@glance-apps/sync 1.3.2 → 1.5.0

package/CHANGELOG.md

@@ -7,6 +7,58 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-06-19
+
+### Added
+
+- **DB sync key verifier (fail fast; never upload under an unverified key).**
+  Before pushing, the DB engine now proves the derived root key matches the
+  account's existing data. It reserves an engine-owned entity
+  (`__glance_keycheck`, never routed to `getLocalEntity` / `applyRemoteEntity`)
+  holding a fixed known plaintext; decryptability under the derived key is the
+  signal. `ensureRootKey` runs `verifyAccountKey()` once per session: an existing
+  verifier that fails to decrypt throws a typed `KEY_MISMATCH` and gates the push
+  (nothing is uploaded), so a wrong passphrase — or a per-account salt that
+  drifted across server redeploys — can no longer poison an account. A new
+  account writes the verifier insert-only (first-write-wins), matching the salt's
+  concurrency model. Exposed via `engine.isKeyVerified()` and
+  `config.onError(message, 'KEY_MISMATCH')`.
+- **DB sync per-row decrypt quarantine (one bad row must not wedge the cycle).**
+  `pullRemoteChanges` now wraps each row's decrypt + apply in try/catch: an
+  individual undecryptable row is counted, recorded in a persisted quarantine set
+  (localStorage, keyed by `storageKeyPrefix`), and the cursor is advanced past it
+  — the cycle no longer throws and wedges all future sync. Reserved `__glance_*`
+  rows are skipped from normal routing. Key verification (Part A) runs first, so
+  a globally wrong key aborts once with `KEY_MISMATCH` instead of quarantining
+  rows one by one. Each cycle re-attempts quarantined rows by id and drops them
+  on a successful decrypt + apply, so a row self-heals once the correct key is in
+  use. Surfaced via `config.onRowsSkipped(count, entityIds)`; `dbSyncCycle()` now
+  resolves to `{ applied, skipped, skippedEntityIds }` and `engine.getQuarantine()`
+  exposes the set.
+- Error codes `KEY_MISMATCH` and `ROW_DECRYPT_FAILED` standardized on the
+  `SyncErrorCode` type.
+
+## [1.4.0] - 2026-06-18
+
+### Fixed
+
+- **DB sync push no longer skips unread remote rows.** The DB engine split the
+  single high-water mark into two cursors: a pull cursor (`getHighWaterMark`,
+  the highest seq actually listed and applied) that only the pull step
+  advances, and a separate push-ack marker (`getPushAck`) for push
+  idempotency. Previously `pushDirtyRows` advanced the shared high-water mark to
+  the max seq the server assigned its pushed rows; because pushed rows get the
+  highest seqs, the next pull resumed from `since` above any remote row whose
+  seq sat below them and silently skipped it — unrecoverable for insert-only
+  rows. A push consumes nothing and now never moves the pull cursor, so
+  push-then-pull and pull-then-push are both safe. An existing stored cursor is
+  read as pull-progress (the conservative interpretation), so upgrades are safe.
+
+### Added
+
+- `getPushAck()` / `setPushAck()` on the DB sync engine expose the push-ack
+  high-water mark.
+
 ## [1.3.2] - 2026-06-14
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glance-apps/sync",
-  "version": "1.3.2",
+  "version": "1.5.0",
   "license": "MIT",
   "type": "module",
   "main": "src/index.js",

package/src/dbCrypto.js

@@ -27,6 +27,27 @@ const IV_BYTES          = 12;
 // from any other HKDF use of the same root key.
 const HKDF_INFO_PREFIX = 'glance-sync:entity:';
 
+// ---------------------------------------------------------------------------
+// Engine-reserved entities
+// ---------------------------------------------------------------------------
+// Rows whose entityId starts with this prefix are owned by the sync engine
+// itself (e.g. the key verifier) and are NOT app entities: they must never be
+// routed to getLocalEntity / applyRemoteEntity.
+export const RESERVED_ENTITY_PREFIX = '__glance_';
+
+// The key-verifier row. Its decryptability under the derived root key is the
+// signal the engine uses to prove a passphrase matches an account's data.
+export const KEYCHECK_ENTITY_ID = '__glance_keycheck';
+
+// Any fixed known plaintext works: AES-GCM tag validation means a wrong key
+// fails to decrypt regardless of contents, so decryption SUCCESS is the signal.
+export const KEYCHECK_PAYLOAD = { v: 1, magic: 'glance-keycheck' };
+
+/** True for engine-reserved rows (e.g. the key verifier), which apps never see. */
+export function isReservedEntityId(entityId) {
+  return typeof entityId === 'string' && entityId.startsWith(RESERVED_ENTITY_PREFIX);
+}
+
 // ---------------------------------------------------------------------------
 // Session state (in-memory only, never persisted in plaintext)
 // ---------------------------------------------------------------------------
@@ -300,7 +321,9 @@ export async function decryptEntity(ciphertextB64, entityId, rootKey = _rootKey)
     return JSON.parse(new TextDecoder().decode(plaintext));
   } catch (err) {
     if (err.name === 'OperationError') {
-      throw new Error('Decryption failed: wrong passphrase or corrupted data.');
+      const failure = new Error('Decryption failed: wrong passphrase or corrupted data.');
+      failure.code = 'ROW_DECRYPT_FAILED';
+      throw failure;
     }
     throw err;
   }

package/src/dbEngine.js

@@ -25,6 +25,9 @@ import {
   hasDbRootKey,
   encryptEntity,
   decryptEntity,
+  isReservedEntityId,
+  KEYCHECK_ENTITY_ID,
+  KEYCHECK_PAYLOAD,
 } from './dbCrypto.js';
 
 const ts = (v) => {
@@ -58,7 +61,8 @@ const ts = (v) => {
  *
  * Event callbacks (optional):
  * @param {Function} [config.onStatusChange]
- * @param {Function} [config.onError]
+ * @param {Function} [config.onError]      - (message, code, isHardStop) called with code 'KEY_MISMATCH' on a wrong key
+ * @param {Function} [config.onRowsSkipped] - (count, entityIds) called when a cycle skipped undecryptable rows
  */
 export const createDbSyncEngine = (config) => {
   const {
@@ -80,6 +84,7 @@ export const createDbSyncEngine = (config) => {
     getEntityLastModified,
     onStatusChange,
     onError,
+    onRowsSkipped,
   } = config;
 
   if (!storageKeyPrefix) throw new Error('createDbSyncEngine: storageKeyPrefix is required');
@@ -105,12 +110,29 @@ export const createDbSyncEngine = (config) => {
 
   // localStorage keys owned by this engine.
   const KEY_CONFIG = `${storageKeyPrefix}-db-sync-config`;
+  // KEY_HWM is the PULL cursor: the highest seq this device has actually
+  // consumed (listed + applied). It is the `since` we resume pulling from, so
+  // only the pull step may advance it. A push consumes nothing and must never
+  // touch it — see KEY_PUSH_ACK below.
   const KEY_HWM    = `${storageKeyPrefix}-db-sync-hwm`;
+  // KEY_PUSH_ACK is the PUSH high-water mark: the highest seq the server has
+  // assigned to rows this device has pushed and fully acknowledged. It exists
+  // purely for push idempotency/observability and is never read by the pull
+  // cursor, so it cannot cause unread remote rows to be skipped.
+  const KEY_PUSH_ACK = `${storageKeyPrefix}-db-sync-push-ack`;
   const KEY_DIRTY  = `${storageKeyPrefix}-db-sync-dirty`;
   const KEY_LAST_SYNCED = `${storageKeyPrefix}-db-sync-last-synced`;
+  // KEY_QUARANTINE persists the set of rows that failed to decrypt under the
+  // (otherwise verified) account key, as [{ entityId, seq }]. They are skipped
+  // on pull so one bad row cannot wedge the cycle, and re-attempted each cycle
+  // so a row recovers if the correct key later becomes available.
+  const KEY_QUARANTINE = `${storageKeyPrefix}-db-sync-quarantine`;
 
-  // ── In-memory guard ───────────────────────────────────────────────────────
+  // ── In-memory guards ──────────────────────────────────────────────────────
   let syncing = false;
+  // Per-session cache: once the derived root key is proven against the account's
+  // existing data (Part A), we never re-verify for the life of this engine.
+  let verified = false;
 
   // ── Local state accessors ─────────────────────────────────────────────────
   const getConfig = () => {
@@ -123,6 +145,10 @@ export const createDbSyncEngine = (config) => {
   };
   const getLastSynced = () => localStorage.getItem(KEY_LAST_SYNCED) || null;
 
+  // PULL cursor. Advanced only by pullRemoteChanges from rows actually applied.
+  // An existing stored value from before the pull/push split is read as
+  // pull-progress, which is the conservative interpretation (it never lets us
+  // resume ahead of what we have consumed).
   const getHighWaterMark = () => {
     const raw = localStorage.getItem(KEY_HWM);
     const n = raw == null ? 0 : Number(raw);
@@ -132,6 +158,17 @@ export const createDbSyncEngine = (config) => {
     localStorage.setItem(KEY_HWM, String(seq));
   };
 
+  // PUSH high-water mark. Tracked separately so a push can never advance the
+  // pull cursor (KEY_HWM) and skip lower-seq remote rows.
+  const getPushAck = () => {
+    const raw = localStorage.getItem(KEY_PUSH_ACK);
+    const n = raw == null ? 0 : Number(raw);
+    return Number.isFinite(n) ? n : 0;
+  };
+  const setPushAck = (seq) => {
+    localStorage.setItem(KEY_PUSH_ACK, String(seq));
+  };
+
   // Dirty set persisted as a JSON array; deduped via Set on read/write.
   const getDirtySet = () => {
     const raw = localStorage.getItem(KEY_DIRTY);
@@ -148,6 +185,32 @@ export const createDbSyncEngine = (config) => {
   };
   const clearDirty = () => localStorage.removeItem(KEY_DIRTY);
 
+  // Quarantine set persisted as a JSON array of { entityId, seq }.
+  const getQuarantine = () => {
+    const raw = localStorage.getItem(KEY_QUARANTINE);
+    if (!raw) return [];
+    try {
+      const arr = JSON.parse(raw);
+      return Array.isArray(arr) ? arr : [];
+    } catch {
+      return [];
+    }
+  };
+  const writeQuarantine = (list) => {
+    if (list.length === 0) localStorage.removeItem(KEY_QUARANTINE);
+    else localStorage.setItem(KEY_QUARANTINE, JSON.stringify(list));
+  };
+  const addToQuarantine = (entityId, seq) => {
+    const list = getQuarantine();
+    const i = list.findIndex((q) => q.entityId === entityId);
+    if (i >= 0) list[i] = { entityId, seq };
+    else list.push({ entityId, seq });
+    writeQuarantine(list);
+  };
+  const removeFromQuarantine = (entityId) => {
+    writeQuarantine(getQuarantine().filter((q) => q.entityId !== entityId));
+  };
+
   // markDirty: called by the app on every local write (and at creation time for
   // insert-only types). Idempotent and synchronous so it can run inside the
   // app's own write path.
@@ -160,38 +223,90 @@ export const createDbSyncEngine = (config) => {
     writeDirtySet(current);
   };
 
+  // ── Key verifier (Part A) ─────────────────────────────────────────────────
+  // Proves the derived root key matches the account's existing data BEFORE we
+  // are allowed to push. A wrong passphrase — or a per-account salt that drifted
+  // across server redeploys — derives a non-matching key; without this check it
+  // would only surface as a cryptic per-row failure mid-sync, after a device may
+  // already have uploaded rows under the bad key and poisoned the account.
+  //
+  // The signal is decryptability: AES-GCM tag validation means a wrong key
+  // simply fails, so the verifier payload's contents need not match. Runs once
+  // per session (cached via `verified`).
+  const verifyAccountKey = async () => {
+    if (verified) return;
+    // Verification needs a single-row fetch. Clients that don't implement getRow
+    // (e.g. minimal test stubs) cannot be verified; don't block sync on them.
+    if (typeof vault.getRow !== 'function') { verified = true; return; }
+
+    const row = await vault.getRow(app, KEYCHECK_ENTITY_ID, accountId);
+    if (row && !row.deleted && row.envelope) {
+      // Existing account: the verifier must decrypt under our derived key.
+      try {
+        await decryptEntity(row.envelope, KEYCHECK_ENTITY_ID);
+        verified = true;
+      } catch {
+        const err = new Error("This sync passphrase doesn't match this account's existing data.");
+        err.code = 'KEY_MISMATCH';
+        throw err;
+      }
+    } else {
+      // New account: establish the verifier. Insert-only / first-write-wins so
+      // concurrent establishers don't clobber — and since the salt is already
+      // first-write-wins, concurrent establishers derive the same key and their
+      // verifiers are mutually decryptable anyway.
+      const envelope = await encryptEntity(KEYCHECK_PAYLOAD, KEYCHECK_ENTITY_ID);
+      await vault.batch(app, {
+        accountId,
+        rows: [{ entityId: KEYCHECK_ENTITY_ID, envelope, createdAt: Date.now(), insertOnly: true }],
+      });
+      verified = true;
+    }
+  };
+
   // ── Root key / salt bootstrap ─────────────────────────────────────────────
   // Ensures the per-account root key is available, fetching or registering the
-  // salt with the vault on first use.
+  // salt with the vault on first use, then verifies it once per session.
   const ensureRootKey = async () => {
-    if (hasDbRootKey()) return;
-    if (await initDbRootKey(cryptoCfg)) return;
-
-    const passphrase = getSyncPassphrase();
-    if (!passphrase) {
-      const err = new Error('Encryption passphrase not available. Please enter your sync passphrase.');
-      err.code = 'PASSPHRASE_REQUIRED';
-      throw err;
-    }
+    if (!hasDbRootKey() && !(await initDbRootKey(cryptoCfg))) {
+      const passphrase = getSyncPassphrase();
+      if (!passphrase) {
+        const err = new Error('Encryption passphrase not available. Please enter your sync passphrase.');
+        err.code = 'PASSPHRASE_REQUIRED';
+        throw err;
+      }
 
-    let salt = await vault.getSalt(accountId);
-    if (!salt) {
-      const fresh = crypto.getRandomValues(new Uint8Array(16));
-      // First-write-wins: use whatever the server returns (another device may
-      // have registered a salt between our GET and PUT).
-      salt = await vault.putSalt(accountId, fresh);
+      let salt = await vault.getSalt(accountId);
+      if (!salt) {
+        const fresh = crypto.getRandomValues(new Uint8Array(16));
+        // First-write-wins: use whatever the server returns (another device may
+        // have registered a salt between our GET and PUT).
+        salt = await vault.putSalt(accountId, fresh);
+      }
+      await setupDbRootKey(passphrase, salt, cryptoCfg);
     }
-    await setupDbRootKey(passphrase, salt, cryptoCfg);
+
+    // Key is now available (restored or freshly derived). Prove it matches the
+    // account before anything else relies on it; this gates the push.
+    await verifyAccountKey();
   };
 
   // ── Step 1: push dirty rows ───────────────────────────────────────────────
   // Encrypts every dirty entity and upserts it as a batch. Entities that no
   // longer exist locally are pushed as soft-deletes. The dirty set is cleared
-  // and the high water mark advanced only after the server fully acknowledges,
-  // so a network failure leaves un-acked rows dirty for an idempotent re-send.
+  // and the push-ack high water mark advanced only after the server fully
+  // acknowledges, so a network failure leaves un-acked rows dirty for an
+  // idempotent re-send. Push deliberately does NOT touch the pull cursor
+  // (getHighWaterMark): the server assigns pushed rows the highest seqs, so
+  // advancing `since` here would skip any remote row whose seq sits below them.
+  //
+  // The push is GATED on key verification: ensureRootKey runs Part A's
+  // verifyAccountKey, which throws KEY_MISMATCH (before any upsert) if the
+  // derived key doesn't match the account — so a device can never upload rows
+  // under a non-matching key.
   const pushDirtyRows = async () => {
     const dirty = getDirtySet();
-    if (dirty.length === 0) return { written: 0, deleted: 0, maxSeq: getHighWaterMark() };
+    if (dirty.length === 0) return { written: 0, deleted: 0, maxSeq: getPushAck() };
 
     await ensureRootKey();
 
@@ -208,8 +323,8 @@ export const createDbSyncEngine = (config) => {
     }
 
     // Soft-delete first, then batch the upserts. If any call throws, we fall out
-    // before clearing the dirty set or advancing the cursor.
-    let maxSeq = getHighWaterMark();
+    // before clearing the dirty set or advancing the push-ack marker.
+    let maxSeq = getPushAck();
     for (const entityId of deletes) {
       const r = await vault.deleteRow(app, entityId, accountId);
       if (r && typeof r.seq === 'number') maxSeq = Math.max(maxSeq, r.seq);
@@ -220,63 +335,124 @@ export const createDbSyncEngine = (config) => {
       if (result && typeof result.maxSeq === 'number') maxSeq = Math.max(maxSeq, result.maxSeq);
     }
 
-    // Full acknowledgment: safe to mark clean.
+    // Full acknowledgment: safe to mark clean. Advance the push-ack marker only;
+    // the pull cursor stays put so the next pull still lists from the highest
+    // seq we have actually consumed.
     clearDirty();
-    setHighWaterMark(maxSeq);
+    setPushAck(maxSeq);
     return { written: upserts.length, deleted: deletes.length, maxSeq };
   };
 
+  // Decrypts and applies one row with entity-grain LWW. Mutates the supplied
+  // `dirty` Set in place (and persists it) when a remote write supersedes a
+  // dirty local copy, so we do not re-push a superseded version. Returns true if
+  // a remote write/delete was applied. Throws (ROW_DECRYPT_FAILED) on a decrypt
+  // failure — the caller decides whether to quarantine.
+  const applyRemoteRow = async (R, dirty) => {
+    if (R.deleted) {
+      await applyRemoteDelete(R.entityId);
+      if (dirty.delete(R.entityId)) writeDirtySet([...dirty]);
+      return true;
+    }
+
+    const remoteEntity = await decryptEntity(R.envelope, R.entityId);
+    const local = await getLocalEntity(R.entityId);
+
+    if (local == null) {
+      await applyRemoteEntity(R.entityId, remoteEntity);
+      return true;
+    }
+    if (insertOnly(remoteEntity, R.entityId)) {
+      // Insert-only types never conflict: applying is an idempotent union.
+      await applyRemoteEntity(R.entityId, remoteEntity);
+      return true;
+    }
+    // Entity-grain last-writer-wins. The same comparison covers both the clean
+    // case and the contended (locally dirty) case.
+    const remoteWins = ts(lastModifiedOf(remoteEntity)) > ts(lastModifiedOf(local));
+    if (remoteWins) {
+      await applyRemoteEntity(R.entityId, remoteEntity);
+      if (dirty.delete(R.entityId)) writeDirtySet([...dirty]);
+      return true;
+    }
+    // local is newer or equal: keep local and discard remote. If the entity is
+    // dirty it stays dirty and will be re-pushed next cycle.
+    return false;
+  };
+
+  // ── Quarantine self-heal (Part B) ─────────────────────────────────────────
+  // Quarantined rows sit BELOW the pull cursor (we advanced past them), so they
+  // never reappear in list() — re-fetching by id is the only recovery path. A
+  // row drops out of quarantine on successful decrypt+apply (e.g. once the
+  // correct key is in use) or once it is gone from the server.
+  const healQuarantine = async (dirty) => {
+    const list = getQuarantine();
+    if (list.length === 0 || typeof vault.getRow !== 'function') return 0;
+
+    let healed = 0;
+    for (const { entityId } of list) {
+      let R;
+      try {
+        R = await vault.getRow(app, entityId, accountId);
+      } catch {
+        continue; // transient network error: leave quarantined, retry next cycle
+      }
+      if (R == null) {
+        removeFromQuarantine(entityId); // gone from server: nothing to recover
+        continue;
+      }
+      try {
+        const didApply = await applyRemoteRow(R, dirty);
+        removeFromQuarantine(entityId);
+        if (didApply) healed += 1;
+      } catch {
+        // Still undecryptable under the current key: leave quarantined.
+      }
+    }
+    return healed;
+  };
+
   // ── Step 2: pull remote changes ───────────────────────────────────────────
   // Paginates from the high water mark, applying each row with entity-grain LWW.
-  // Rows that are also locally dirty are resolved against the dirty local copy
-  // (contended path): remote wins only if its lastModified is newer, and when it
-  // does win the entity is dropped from the dirty set so we do not re-push a
-  // superseded version.
+  // Part A's key verification has already run (via ensureRootKey), so a globally
+  // wrong key has aborted with KEY_MISMATCH before we get here; any decrypt
+  // failure now is an INDIVIDUAL bad row. Such a row is counted, quarantined,
+  // and its cursor advanced past — it must never throw and wedge the cycle.
   const pullRemoteChanges = async () => {
+    await ensureRootKey();
+
     let since = getHighWaterMark();
     let maxSeq = since;
     let appliedRemote = false;
+    let applied = 0;
+    let skipped = 0;
+    const skippedEntityIds = [];
+
+    // Re-attempt previously quarantined rows first; a snapshot dirty set keeps
+    // contended-path resolution consistent across heal + page application.
+    const dirty = new Set(getDirtySet());
+    applied += await healQuarantine(dirty);
 
     let hasMore = true;
     while (hasMore) {
       const { rows, hasMore: more } = await vault.list(app, { accountId, since });
       if (!Array.isArray(rows) || rows.length === 0) break;
 
-      // Snapshot the dirty set once per page for contended-path resolution.
-      const dirty = new Set(getDirtySet());
-
       for (const R of rows) {
         if (typeof R.seq === 'number' && R.seq > maxSeq) maxSeq = R.seq;
 
-        if (R.deleted) {
-          await applyRemoteDelete(R.entityId);
-          if (dirty.delete(R.entityId)) writeDirtySet([...dirty]);
-          appliedRemote = true;
-          continue;
-        }
-
-        await ensureRootKey();
-        const remoteEntity = await decryptEntity(R.envelope, R.entityId);
-        const local = await getLocalEntity(R.entityId);
-
-        if (local == null) {
-          await applyRemoteEntity(R.entityId, remoteEntity);
-          appliedRemote = true;
-        } else if (insertOnly(remoteEntity, R.entityId)) {
-          // Insert-only types never conflict: applying is an idempotent union.
-          await applyRemoteEntity(R.entityId, remoteEntity);
-          appliedRemote = true;
-        } else {
-          // Entity-grain last-writer-wins. The same comparison covers both the
-          // clean case and the contended (locally dirty) case.
-          const remoteWins = ts(lastModifiedOf(remoteEntity)) > ts(lastModifiedOf(local));
-          if (remoteWins) {
-            await applyRemoteEntity(R.entityId, remoteEntity);
-            appliedRemote = true;
-            if (dirty.delete(R.entityId)) writeDirtySet([...dirty]);
+        // Engine-reserved rows (e.g. the key verifier) are not app entities and
+        // must never be routed to applyRemoteEntity. Advance past them.
+        if (!isReservedEntityId(R.entityId)) {
+          try {
+            const didApply = await applyRemoteRow(R, dirty);
+            if (didApply) { appliedRemote = true; applied += 1; }
+          } catch {
+            // Per-row decrypt failure: quarantine, count, advance, continue.
+            skipped += 1;
+            skippedEntityIds.push(R.entityId);
+            addToQuarantine(R.entityId, R.seq);
           }
-          // else: local is newer or equal, so keep local and discard remote. If the
-          // entity is dirty it stays dirty and will be re-pushed next cycle.
         }
 
         if (typeof R.seq === 'number') since = Math.max(since, R.seq);
@@ -285,13 +461,18 @@ export const createDbSyncEngine = (config) => {
       hasMore = !!more;
     }
 
+    // Pull is the sole writer of the pull cursor. Advance it (monotonically)
+    // from the highest seq we actually listed this run.
     setHighWaterMark(Math.max(getHighWaterMark(), maxSeq));
-    return { maxSeq, appliedRemote };
+    return { maxSeq, appliedRemote, applied, skipped, skippedEntityIds };
   };
 
   // ── Step 3: update device cursor ──────────────────────────────────────────
   // Best-effort: a failure here only affects tombstone GC timing, never sync
-  // correctness, so it is swallowed.
+  // correctness, so it is swallowed. lastSeenSeq reports the pull cursor (what
+  // we have truly consumed), not the push-ack marker: reporting consumed
+  // progress is the conservative value for server-side tombstone GC, since it
+  // never lets the server reclaim a tombstone this device has not yet seen.
   const updateDeviceCursor = async () => {
     if (!deviceId) return { updated: false };
     try {
@@ -316,20 +497,29 @@ export const createDbSyncEngine = (config) => {
     onStatusChange?.('uploading');
     onError?.(null, null, false);
     try {
+      // Part A first: prove the key before we push anything. A globally wrong
+      // key aborts here with KEY_MISMATCH (push gated, nothing uploaded) rather
+      // than quarantining thousands of rows one by one on the pull.
+      await ensureRootKey();
+
       await pushDirtyRows();
       onStatusChange?.('downloading');
-      await pullRemoteChanges();
+      const pull = await pullRemoteChanges();
       await updateDeviceCursor();
 
       const now = new Date().toISOString();
       localStorage.setItem(KEY_LAST_SYNCED, now);
       onStatusChange?.('success');
+
+      if (pull.skipped > 0) onRowsSkipped?.(pull.skipped, pull.skippedEntityIds);
+      return { applied: pull.applied, skipped: pull.skipped, skippedEntityIds: pull.skippedEntityIds };
     } catch (err) {
       // eslint-disable-next-line no-console
       console.error(`[${appId}] db sync cycle error:`, err);
       const code = err && err.code ? err.code : 'NETWORK_ERROR';
       onError?.(err?.message || String(err), code, false);
       onStatusChange?.('error');
+      return { applied: 0, skipped: 0, skippedEntityIds: [] };
     } finally {
       syncing = false;
     }
@@ -352,9 +542,14 @@ export const createDbSyncEngine = (config) => {
     getDirtySet,
     clearDirty,
 
-    // Cursor
+    // Quarantine (per-row decrypt failures awaiting self-heal)
+    getQuarantine,
+
+    // Cursor (pull-progress) and push-ack marker
     getHighWaterMark,
     setHighWaterMark,
+    getPushAck,
+    setPushAck,
 
     // Config
     getConfig,
@@ -363,6 +558,7 @@ export const createDbSyncEngine = (config) => {
 
     // State queries
     isSyncing:        () => syncing,
+    isKeyVerified:    () => verified,
     hasEncryptionReady: hasDbRootKey,
 
     // Sub-modules

package/src/index.js

@@ -49,4 +49,8 @@ export {
   hasDbRootKey,
   encryptEntity,
   decryptEntity,
+  isReservedEntityId,
+  RESERVED_ENTITY_PREFIX,
+  KEYCHECK_ENTITY_ID,
+  KEYCHECK_PAYLOAD,
 } from './dbCrypto.js';

package/types/index.d.ts

@@ -16,7 +16,12 @@ export type SyncErrorCode =
   | 'FORBIDDEN'
   | 'AUTH_FAILURE'
   | 'LOCKED'
-  | 'NETWORK_ERROR';
+  | 'NETWORK_ERROR'
+  // DB transport: derived root key does not match the account's existing data.
+  | 'KEY_MISMATCH'
+  // DB transport: a single row failed to decrypt (surfaced as a count via
+  // onRowsSkipped, never thrown).
+  | 'ROW_DECRYPT_FAILED';
 
 export type SyncStatus = 'idle' | 'uploading' | 'downloading' | 'success' | 'error';
 
@@ -366,6 +371,14 @@ export function hasDbRootKey(): boolean;
 export function encryptEntity(entity: unknown, entityId: string, rootKey?: CryptoKey): Promise<string>;
 export function decryptEntity<T = unknown>(ciphertext: string, entityId: string, rootKey?: CryptoKey): Promise<T>;
 
+// Engine-reserved entities. Rows whose entityId starts with RESERVED_ENTITY_PREFIX
+// are owned by the sync engine (e.g. the key verifier) and are never routed to
+// getLocalEntity / applyRemoteEntity.
+export const RESERVED_ENTITY_PREFIX: string;
+export const KEYCHECK_ENTITY_ID: string;
+export const KEYCHECK_PAYLOAD: { v: number; magic: string };
+export function isReservedEntityId(entityId: string): boolean;
+
 // Row exchanged with GLANCEvault. envelope is base64(IV || AES-GCM output).
 export interface VaultRow {
   entityId: string;
@@ -425,30 +438,54 @@ export interface DbSyncEngineConfig {
 
   // Event callbacks
   onStatusChange?: (status: SyncStatus, hints?: { from?: SyncStatus }) => void;
+  // Called with code === 'KEY_MISMATCH' when the derived key doesn't match the account.
   onError?: (message: string | null, code: SyncErrorCode | null, isHardStop: boolean) => void;
+  // Called once per cycle that skipped > 0 undecryptable rows (per-row quarantine).
+  onRowsSkipped?: (count: number, entityIds: string[]) => void;
+}
+
+/** Result of a DB sync cycle / pull: how many rows applied vs. quarantined. */
+export interface DbSyncResult {
+  applied: number;
+  skipped: number;
+  skippedEntityIds: string[];
+}
+
+/** A row quarantined after failing to decrypt under the (verified) account key. */
+export interface QuarantinedRow {
+  entityId: string;
+  seq: number;
 }
 
 export interface DbSyncEngine {
   transportMode: 'database';
-  sync(): Promise<void>;
-  dbSyncCycle(): Promise<void>;
+  sync(): Promise<DbSyncResult>;
+  dbSyncCycle(): Promise<DbSyncResult>;
   pushDirtyRows(): Promise<{ written: number; deleted: number; maxSeq: number }>;
-  pullRemoteChanges(): Promise<{ maxSeq: number; appliedRemote: boolean }>;
+  pullRemoteChanges(): Promise<DbSyncResult & { maxSeq: number; appliedRemote: boolean }>;
   updateDeviceCursor(): Promise<{ updated: boolean }>;
   ensureRootKey(): Promise<void>;
 
   markDirty(entityId: string): void;
   getDirtySet(): string[];
   clearDirty(): void;
+  /** Rows quarantined after a per-row decrypt failure, awaiting self-heal. */
+  getQuarantine(): QuarantinedRow[];
 
+  /** Pull cursor: highest seq actually listed + applied. Only pull advances it. */
   getHighWaterMark(): number;
   setHighWaterMark(seq: number): void;
+  /** Push-ack marker: highest seq the server assigned to pushed rows. Never feeds the pull cursor. */
+  getPushAck(): number;
+  setPushAck(seq: number): void;
 
   getConfig(): Record<string, unknown> | null;
   setConfig(config: Record<string, unknown> | null): void;
   getLastSynced(): string | null;
 
   isSyncing(): boolean;
+  /** True once the derived root key has been proven against the account (Part A). */
+  isKeyVerified(): boolean;
   hasEncryptionReady(): boolean;
 
   vault: VaultClient;