@glance-apps/sync 1.4.0 → 1.5.1

package/CHANGELOG.md

@@ -7,6 +7,63 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.5.1] - 2026-06-19
+
+### Fixed
+
+- **Key verification fails clearly when the server can't host the verifier.**
+  1.5.0's `verifyAccountKey` did `GET /sync/{app}/__glance_keycheck`; against a
+  server that doesn't yet support the reserved id or the single-row GET, that
+  threw a raw `get row failed: 400` and aborted the whole sync with a meaningless
+  message. `verifyAccountKey` now distinguishes three outcomes: a
+  present-but-undecryptable verifier still throws `KEY_MISMATCH`; an absent
+  verifier (404) is still written; but any *other* error from the single-row GET
+  or the verifier write (HTTP 400/405/500, or a 404 on the route itself) now
+  throws a typed `VERIFIER_UNSUPPORTED` with an actionable "update your server"
+  message. The engine never silently proceeds unverified (the verifier gates push
+  and quarantine does not, so a wrong-key device with verification skipped would
+  still push poison rows), so sync pauses with a clear reason. Surfaced via
+  `config.onError(message, code)` like `KEY_MISMATCH`.
+
+### Added
+
+- `config.allowUnverified` (default `false`): an opt-in operator escape hatch
+  that downgrades `VERIFIER_UNSUPPORTED` to a logged warning and proceeds, for
+  operators who knowingly accept the risk of syncing against a server that can't
+  host the verifier.
+- `VERIFIER_UNSUPPORTED` standardized on the `SyncErrorCode` type.
+
+## [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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glance-apps/sync",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "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,9 @@ 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, or 'VERIFIER_UNSUPPORTED' when the server can't host the verifier
+ * @param {Function} [config.onRowsSkipped] - (count, entityIds) called when a cycle skipped undecryptable rows
+ * @param {boolean}  [config.allowUnverified=false] - operator escape hatch: downgrade VERIFIER_UNSUPPORTED to a logged warning and proceed (unsafe; off by default)
  */
 export const createDbSyncEngine = (config) => {
   const {
@@ -80,6 +85,8 @@ export const createDbSyncEngine = (config) => {
     getEntityLastModified,
     onStatusChange,
     onError,
+    onRowsSkipped,
+    allowUnverified = false,
   } = config;
 
   if (!storageKeyPrefix) throw new Error('createDbSyncEngine: storageKeyPrefix is required');
@@ -117,9 +124,17 @@ export const createDbSyncEngine = (config) => {
   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 = () => {
@@ -172,6 +187,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.
@@ -184,28 +225,108 @@ 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`).
+  // A server that can't host the verifier (doesn't support the reserved id or
+  // the single-row GET endpoint) must fail with a CLEAR reason, not a raw
+  // "get row failed: 400". We never silently proceed unverified: the verifier
+  // gates push and quarantine does NOT, so a wrong-key device with verification
+  // skipped would still push poison rows. Pausing sync with a clear reason is
+  // the correct degradation. (config.allowUnverified is an explicit operator
+  // escape hatch, off by default, that downgrades this to a logged warning.)
+  const verifierUnsupported = (cause) => {
+    if (allowUnverified) {
+      // eslint-disable-next-line no-console
+      console.warn(`[${appId}] db sync proceeding UNVERIFIED: the server cannot host the key verifier (${KEYCHECK_ENTITY_ID}).`, cause);
+      verified = true;
+      return; // caller returns from verifyAccountKey and sync proceeds
+    }
+    const err = new Error('Your GLANCEvault server needs to be updated to support key verification (the __glance_keycheck row).');
+    err.code = 'VERIFIER_UNSUPPORTED';
+    if (cause) err.cause = cause;
+    throw err;
+  };
+
+  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; }
+
+    // Outcome 3: any error from the GET (HTTP 400/405/500, or a 404 on the route
+    // itself) means the server can't host the verifier — fail clearly.
+    let row;
+    try {
+      row = await vault.getRow(app, KEYCHECK_ENTITY_ID, accountId);
+    } catch (cause) {
+      verifierUnsupported(cause);
+      return; // only reached when downgraded via allowUnverified
+    }
+
+    if (row && !row.deleted && row.envelope) {
+      // Outcome 1: existing account — the verifier must decrypt under our 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 {
+      // Outcome 2: row absent (404 -> getRow returned null) — new account.
+      // Establish the verifier insert-only / first-write-wins so concurrent
+      // establishers don't clobber; since the salt is already first-write-wins,
+      // they derive the same key and their verifiers are mutually decryptable.
+      const envelope = await encryptEntity(KEYCHECK_PAYLOAD, KEYCHECK_ENTITY_ID);
+      try {
+        await vault.batch(app, {
+          accountId,
+          rows: [{ entityId: KEYCHECK_ENTITY_ID, envelope, createdAt: Date.now(), insertOnly: true }],
+        });
+      } catch (cause) {
+        // The write itself rejecting the reserved id (400/405/…) is the same
+        // "server can't host the verifier" condition.
+        verifierUnsupported(cause);
+        return;
+      }
+      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 ───────────────────────────────────────────────
@@ -216,6 +337,11 @@ export const createDbSyncEngine = (config) => {
   // 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: getPushAck() };
@@ -255,57 +381,116 @@ export const createDbSyncEngine = (config) => {
     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);
@@ -317,7 +502,7 @@ export const createDbSyncEngine = (config) => {
     // 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 ──────────────────────────────────────────
@@ -350,20 +535,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;
     }
@@ -386,6 +580,9 @@ export const createDbSyncEngine = (config) => {
     getDirtySet,
     clearDirty,
 
+    // Quarantine (per-row decrypt failures awaiting self-heal)
+    getQuarantine,
+
     // Cursor (pull-progress) and push-ack marker
     getHighWaterMark,
     setHighWaterMark,
@@ -399,6 +596,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,15 @@ 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'
+  // DB transport: the server can't host the key verifier (doesn't support the
+  // reserved __glance_keycheck id or the single-row endpoint).
+  | 'VERIFIER_UNSUPPORTED';
 
 export type SyncStatus = 'idle' | 'uploading' | 'downloading' | 'success' | 'error';
 
@@ -366,6 +374,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,21 +441,45 @@ 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, or 'VERIFIER_UNSUPPORTED' when the server can't host the verifier.
   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;
+
+  // Operator escape hatch: downgrade VERIFIER_UNSUPPORTED to a logged warning
+  // and proceed without verification (unsafe — a wrong-key device could push
+  // poison rows). Off by default so the safe behavior is the default.
+  allowUnverified?: boolean;
+}
+
+/** 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;
@@ -453,6 +493,8 @@ export interface DbSyncEngine {
   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;