@glance-apps/sync 1.1.2 → 1.2.0

package/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-06-13
+
+### Added
+
+- **Phase 3: database (GLANCEvault) sync transport**, selected via
+  `transportMode: 'database'` in the engine config. The file-tier transport is
+  completely unchanged; file-tier users run the identical code path as before.
+  - `src/dbCrypto.js`: per-entity encryption. One PBKDF2 root key per account
+    (salt from the GLANCEvault salt endpoint), per-entity AES-256-GCM keys
+    HKDF-derived from it using the entityId as context, fresh IV per entity.
+  - `src/vaultClient.js`: Bearer-authenticated HTTP client for the vault batch,
+    list, get, delete, device, and salt endpoints, with an injectable fetch.
+  - `src/dbEngine.js`: row-grained engine with per-entity dirty tracking
+    (`markDirty`), seq-based incremental pull, entity-grain last-writer-wins,
+    insert-only union, partial-write safety, and a best-effort device cursor.
+  - New exports: `createDbSyncEngine`, `createVaultClient`, `setupDbRootKey`,
+    `initDbRootKey`, `clearDbRootKey`, `hasDbRootKey`, `encryptEntity`,
+    `decryptEntity`.
+  - See `docs/PHASE3_DB_TRANSPORT.md` for design decisions, the coordinated
+    GLANCEvault `POST /sync/:app/device` endpoint, and the Phase 4 cutover steps.
+
 ## [1.1.2] - 2026-06-04
 
 ### Fixed

package/package.json

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

package/src/dbCrypto.js

@@ -0,0 +1,307 @@
+// Per-entity encryption for the database sync transport (Phase 3).
+//
+// The file-tier transport (crypto.js) encrypts the entire entity array as one
+// AES-GCM blob. The database transport instead encrypts one entity at a time so
+// that each row on GLANCEvault is an independent ciphertext that can be fetched,
+// upserted, and decrypted on its own.
+//
+// Crypto design (mirrors the per-envelope pattern in @glance-apps/intents):
+//   1. A single root key is derived once from the passphrase with PBKDF2
+//      (SHA-256, 310 000 iterations) using a per-account salt fetched from the
+//      GLANCEvault salt endpoint. This matches the file-tier derivation cost.
+//   2. Per entity, an AES-256-GCM key is HKDF-derived from the root key using
+//      the entityId as the HKDF info context. HKDF is cheap, so deriving a fresh
+//      key per row is fast (no extra PBKDF2 work per entity).
+//   3. Each entity is encrypted with a fresh 12-byte IV. The stored ciphertext
+//      is base64(IV || AES-GCM output).
+//
+// This module is entirely additive: it does not import from, modify, or share
+// mutable state with crypto.js beyond reading the shared session passphrase,
+// which the engine wires up via getSyncPassphrase().
+
+const PBKDF2_ITERATIONS = 310_000;
+const ROOT_KEY_BYTES    = 32; // 256 bits
+const IV_BYTES          = 12;
+
+// HKDF info prefix. Namespacing the entityId keeps these derivations distinct
+// from any other HKDF use of the same root key.
+const HKDF_INFO_PREFIX = 'glance-sync:entity:';
+
+// ---------------------------------------------------------------------------
+// Session state (in-memory only, never persisted in plaintext)
+// ---------------------------------------------------------------------------
+let _rootKey = null; // CryptoKey | null  (an HKDF base key, non-extractable)
+
+export function hasDbRootKey() { return _rootKey !== null; }
+export function getDbRootKey()  { return _rootKey; }
+
+// ---------------------------------------------------------------------------
+// Byte helpers
+// ---------------------------------------------------------------------------
+function packBytes(...arrays) {
+  const total = arrays.reduce((n, a) => n + a.length, 0);
+  const out   = new Uint8Array(total);
+  let   offset = 0;
+  for (const a of arrays) { out.set(a, offset); offset += a.length; }
+  return out;
+}
+
+export function toBase64(bytes) {
+  let binary = '';
+  const chunk = 8192;
+  for (let i = 0; i < bytes.length; i += chunk) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+  }
+  return btoa(binary);
+}
+
+export function fromBase64(b64) {
+  return Uint8Array.from(atob(b64), c => c.charCodeAt(0));
+}
+
+// ---------------------------------------------------------------------------
+// Key derivation
+// ---------------------------------------------------------------------------
+
+// Derives the raw 32-byte root key from a passphrase and salt using the same
+// PBKDF2 parameters as the file-tier crypto. Returned as raw bytes so the
+// caller can persist them in device storage; HKDF base keys are non-extractable
+// and cannot be re-exported once imported.
+async function deriveRootBits(passphrase, salt) {
+  const enc         = new TextEncoder();
+  const keyMaterial = await crypto.subtle.importKey(
+    'raw', enc.encode(passphrase), 'PBKDF2', false, ['deriveBits']
+  );
+  const bits = await crypto.subtle.deriveBits(
+    { name: 'PBKDF2', salt, iterations: PBKDF2_ITERATIONS, hash: 'SHA-256' },
+    keyMaterial,
+    ROOT_KEY_BYTES * 8
+  );
+  return new Uint8Array(bits);
+}
+
+// Imports raw root bytes as a non-extractable HKDF base key usable only to
+// derive per-entity keys.
+async function importRootKey(rootBytes) {
+  return crypto.subtle.importKey('raw', rootBytes, 'HKDF', false, ['deriveKey']);
+}
+
+// HKDF-derives a fresh AES-256-GCM key from the root key, scoped to one entity.
+async function deriveEntityKey(rootKey, entityId) {
+  const enc = new TextEncoder();
+  return crypto.subtle.deriveKey(
+    {
+      name: 'HKDF',
+      hash: 'SHA-256',
+      salt: new Uint8Array(0),
+      info: enc.encode(HKDF_INFO_PREFIX + entityId),
+    },
+    rootKey,
+    { name: 'AES-GCM', length: 256 },
+    false,
+    ['encrypt', 'decrypt']
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Root key lifecycle (storage parallels crypto.js but uses its own DB/record)
+// ---------------------------------------------------------------------------
+const KEY_DB_VERSION = 1;
+const KEY_STORE      = 'db-root-keys';
+const ROOT_KEY_ID    = 'db-root-key';
+
+function openRootKeyDB(cryptoDBName) {
+  return new Promise((resolve, reject) => {
+    const req = indexedDB.open(`${cryptoDBName}-db`, KEY_DB_VERSION);
+    req.onupgradeneeded = (e) => {
+      const db = e.target.result;
+      if (!db.objectStoreNames.contains(KEY_STORE)) {
+        db.createObjectStore(KEY_STORE, { keyPath: 'id' });
+      }
+    };
+    req.onsuccess = () => resolve(req.result);
+    req.onerror  = () => reject(req.error);
+  });
+}
+
+async function saveRootToIndexedDB(cryptoDBName, rootBytes, salt) {
+  const db = await openRootKeyDB(cryptoDBName);
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(KEY_STORE, 'readwrite');
+    tx.objectStore(KEY_STORE).put({
+      id: ROOT_KEY_ID,
+      rootBytes: Array.from(rootBytes),
+      salt: Array.from(salt),
+    });
+    tx.oncomplete = () => resolve();
+    tx.onerror    = () => reject(tx.error);
+  });
+}
+
+async function loadRootFromIndexedDB(cryptoDBName) {
+  try {
+    const db     = await openRootKeyDB(cryptoDBName);
+    const record = await new Promise((resolve, reject) => {
+      const tx  = db.transaction(KEY_STORE, 'readonly');
+      const req = tx.objectStore(KEY_STORE).get(ROOT_KEY_ID);
+      req.onsuccess = () => resolve(req.result);
+      req.onerror   = () => reject(req.error);
+    });
+    if (!record) return null;
+    return { rootBytes: new Uint8Array(record.rootBytes), salt: new Uint8Array(record.salt) };
+  } catch {
+    return null;
+  }
+}
+
+async function clearRootFromIndexedDB(cryptoDBName) {
+  try {
+    const db = await openRootKeyDB(cryptoDBName);
+    await new Promise((resolve, reject) => {
+      const tx = db.transaction(KEY_STORE, 'readwrite');
+      tx.objectStore(KEY_STORE).delete(ROOT_KEY_ID);
+      tx.oncomplete = () => resolve();
+      tx.onerror    = () => reject(tx.error);
+    });
+  } catch { /* ignore */ }
+}
+
+// Native bridge (Android Keystore) stores the same record as a base64 JSON blob.
+async function loadRootFromNative(nativeGetSyncKey) {
+  try {
+    const b64 = await nativeGetSyncKey();
+    if (!b64) return null;
+    const record = JSON.parse(atob(b64));
+    return { rootBytes: new Uint8Array(record.rootBytes), salt: new Uint8Array(record.salt) };
+  } catch {
+    return null;
+  }
+}
+
+async function saveRootToNative(nativeStoreSyncKey, rootBytes, salt) {
+  if (!nativeStoreSyncKey) return;
+  const record = { rootBytes: Array.from(rootBytes), salt: Array.from(salt) };
+  nativeStoreSyncKey(btoa(JSON.stringify(record)));
+}
+
+async function clearRootFromNative(nativeStoreSyncKey) {
+  try { if (nativeStoreSyncKey) nativeStoreSyncKey(null); }
+  catch { /* ignore */ }
+}
+
+// ---------------------------------------------------------------------------
+// Public lifecycle API
+// ---------------------------------------------------------------------------
+
+/**
+ * First-time setup: derive the root key from the passphrase + account salt and
+ * cache it in device storage. The salt is provided by the engine (fetched from
+ * or registered with the GLANCEvault salt endpoint).
+ *
+ * @param {string} passphrase
+ * @param {Uint8Array} salt
+ * @param {object} config
+ * @param {string} config.cryptoDBName
+ * @param {Function|null} [config.nativeGetSyncKey]
+ * @param {Function|null} [config.nativeStoreSyncKey]
+ */
+export async function setupDbRootKey(passphrase, salt, { cryptoDBName, nativeGetSyncKey = null, nativeStoreSyncKey = null } = {}) {
+  const rootBytes = await deriveRootBits(passphrase, salt);
+  _rootKey = await importRootKey(rootBytes);
+  if (nativeGetSyncKey != null) {
+    await saveRootToNative(nativeStoreSyncKey, rootBytes, salt);
+  } else {
+    await saveRootToIndexedDB(cryptoDBName, rootBytes, salt);
+  }
+}
+
+/**
+ * Restores the root key from device storage without requiring the passphrase.
+ * Returns true if a key was restored, false if setup is still required.
+ *
+ * @param {object} config
+ * @param {string} config.cryptoDBName
+ * @param {Function|null} [config.nativeGetSyncKey]
+ * @returns {Promise<boolean>}
+ */
+export async function initDbRootKey({ cryptoDBName, nativeGetSyncKey = null } = {}) {
+  try {
+    const result = nativeGetSyncKey != null
+      ? await loadRootFromNative(nativeGetSyncKey)
+      : await loadRootFromIndexedDB(cryptoDBName);
+    if (result) {
+      _rootKey = await importRootKey(result.rootBytes);
+      return true;
+    }
+  } catch { /* storage unavailable */ }
+  return false;
+}
+
+/**
+ * Clears the cached root key from device storage and session memory.
+ *
+ * @param {object} config
+ */
+export async function clearDbRootKey({ cryptoDBName, nativeGetSyncKey = null, nativeStoreSyncKey = null } = {}) {
+  _rootKey = null;
+  if (nativeGetSyncKey != null) {
+    await clearRootFromNative(nativeStoreSyncKey);
+  } else {
+    await clearRootFromIndexedDB(cryptoDBName);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Encrypt / decrypt a single entity
+// ---------------------------------------------------------------------------
+
+/**
+ * Encrypts one entity into a base64 ciphertext string for the row's
+ * `ciphertext` field. The output encodes [ 12-byte IV ][ AES-GCM ciphertext ].
+ *
+ * @param {*} entity        - plain JS value to encrypt (serialised with JSON)
+ * @param {string} entityId - stable entity UUID, used as HKDF context
+ * @param {CryptoKey} [rootKey] - explicit root key (defaults to the session key)
+ * @returns {Promise<string>} base64 ciphertext
+ */
+export async function encryptEntity(entity, entityId, rootKey = _rootKey) {
+  if (!rootKey) {
+    const err = new Error('Database root key not available. Please enter your sync passphrase.');
+    err.code = 'PASSPHRASE_REQUIRED';
+    throw err;
+  }
+  const key        = await deriveEntityKey(rootKey, entityId);
+  const plaintext  = new TextEncoder().encode(JSON.stringify(entity));
+  const iv         = crypto.getRandomValues(new Uint8Array(IV_BYTES));
+  const ciphertext = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, plaintext);
+  return toBase64(packBytes(iv, new Uint8Array(ciphertext)));
+}
+
+/**
+ * Decrypts a base64 ciphertext produced by encryptEntity back into the entity.
+ *
+ * @param {string} ciphertextB64 - the row's `ciphertext` field
+ * @param {string} entityId      - stable entity UUID, used as HKDF context
+ * @param {CryptoKey} [rootKey]  - explicit root key (defaults to the session key)
+ * @returns {Promise<*>} the decrypted entity
+ */
+export async function decryptEntity(ciphertextB64, entityId, rootKey = _rootKey) {
+  if (!rootKey) {
+    const err = new Error('Database root key not available. Please enter your sync passphrase.');
+    err.code = 'PASSPHRASE_REQUIRED';
+    throw err;
+  }
+  const packed     = fromBase64(ciphertextB64);
+  const iv         = packed.slice(0, IV_BYTES);
+  const ciphertext = packed.slice(IV_BYTES);
+  const key        = await deriveEntityKey(rootKey, entityId);
+  try {
+    const plaintext = await crypto.subtle.decrypt({ name: 'AES-GCM', iv }, key, ciphertext);
+    return JSON.parse(new TextDecoder().decode(plaintext));
+  } catch (err) {
+    if (err.name === 'OperationError') {
+      throw new Error('Decryption failed: wrong passphrase or corrupted data.');
+    }
+    throw err;
+  }
+}

package/src/dbEngine.js

@@ -0,0 +1,371 @@
+// Database sync engine for @glance-apps/sync (Phase 3).
+//
+// This is the row-grained transport that runs when config.transportMode is
+// 'database'. It sits alongside the file-tier engine in engine.js, which is left
+// completely untouched: file-tier users never reach this code.
+//
+// Where the file tier downloads the whole entity array, merges it, and uploads
+// the whole array back, this engine tracks dirty entities locally and exchanges
+// only the rows that changed, using GLANCEvault's seq-based incremental sync:
+//
+//   1. PUSH dirty rows   (encrypted per-entity, cleared only on full ack)
+//   2. PULL remote rows  (seq cursor, paginated, entity-grain LWW)
+//   3. UPDATE device cursor (best-effort)
+//
+// Local sync state (dbSyncHighWaterMark, dbSyncDirtySet) is persisted via the
+// same localStorage that the file engine uses for its sync metadata, keyed by
+// storageKeyPrefix. See the Phase 3 summary for why localStorage is used here in
+// place of the spec's IndexedDB suggestion.
+
+import { createVaultClient } from './vaultClient.js';
+import { getSyncPassphrase } from './crypto.js';
+import {
+  setupDbRootKey,
+  initDbRootKey,
+  hasDbRootKey,
+  encryptEntity,
+  decryptEntity,
+} from './dbCrypto.js';
+
+const ts = (v) => {
+  if (v == null) return 0;
+  const t = new Date(v).getTime();
+  return Number.isNaN(t) ? 0 : t;
+};
+
+/**
+ * Creates the database sync engine.
+ *
+ * @param {object} config
+ * @param {string}  config.storageKeyPrefix - namespace for local sync state
+ * @param {string}  config.appId            - app identity (fallback URL segment)
+ * @param {string} [config.vaultApp]        - URL path segment for the app (defaults to appId)
+ * @param {string}  config.vaultUrl
+ * @param {string}  config.vaultToken
+ * @param {string}  config.accountId
+ * @param {string} [config.deviceId]
+ * @param {string}  config.cryptoDBName     - device storage name for the root key
+ * @param {Function|null} [config.nativeGetSyncKey]
+ * @param {Function|null} [config.nativeStoreSyncKey]
+ * @param {Function} [config.fetchImpl]     - injectable fetch (tests / native shells)
+ *
+ * Data callbacks (the engine is data-shape agnostic):
+ * @param {Function} config.getLocalEntity      - (entityId) => entity | null | Promise
+ * @param {Function} config.applyRemoteEntity   - (entityId, entity) => void | Promise
+ * @param {Function} config.applyRemoteDelete   - (entityId) => void | Promise
+ * @param {Function} [config.isInsertOnly]       - (entity, entityId) => boolean
+ * @param {Function} [config.getEntityLastModified] - (entity) => string|number (defaults to entity.lastModified)
+ *
+ * Event callbacks (optional):
+ * @param {Function} [config.onStatusChange]
+ * @param {Function} [config.onError]
+ */
+export const createDbSyncEngine = (config) => {
+  const {
+    storageKeyPrefix,
+    appId,
+    vaultApp,
+    vaultUrl,
+    vaultToken,
+    accountId,
+    deviceId,
+    cryptoDBName,
+    nativeGetSyncKey = null,
+    nativeStoreSyncKey = null,
+    fetchImpl,
+    getLocalEntity,
+    applyRemoteEntity,
+    applyRemoteDelete,
+    isInsertOnly,
+    getEntityLastModified,
+    onStatusChange,
+    onError,
+  } = config;
+
+  if (!storageKeyPrefix) throw new Error('createDbSyncEngine: storageKeyPrefix is required');
+  if (!config.vaultClient && !vaultUrl)   throw new Error('createDbSyncEngine: vaultUrl is required');
+  if (!config.vaultClient && !vaultToken) throw new Error('createDbSyncEngine: vaultToken is required');
+  if (!accountId)        throw new Error('createDbSyncEngine: accountId is required');
+  if (typeof getLocalEntity    !== 'function') throw new Error('createDbSyncEngine: getLocalEntity is required');
+  if (typeof applyRemoteEntity !== 'function') throw new Error('createDbSyncEngine: applyRemoteEntity is required');
+  if (typeof applyRemoteDelete !== 'function') throw new Error('createDbSyncEngine: applyRemoteDelete is required');
+
+  const app = vaultApp || appId;
+  const lastModifiedOf = typeof getEntityLastModified === 'function'
+    ? getEntityLastModified
+    : (entity) => entity && entity.lastModified;
+  const insertOnly = typeof isInsertOnly === 'function'
+    ? isInsertOnly
+    : () => false;
+
+  const cryptoCfg = { cryptoDBName, nativeGetSyncKey, nativeStoreSyncKey };
+  // config.vaultClient lets tests and native shells supply a pre-built client;
+  // otherwise build the default HTTP client from the vault credentials.
+  const vault = config.vaultClient || createVaultClient({ vaultUrl, vaultToken, fetchImpl });
+
+  // localStorage keys owned by this engine.
+  const KEY_CONFIG = `${storageKeyPrefix}-db-sync-config`;
+  const KEY_HWM    = `${storageKeyPrefix}-db-sync-hwm`;
+  const KEY_DIRTY  = `${storageKeyPrefix}-db-sync-dirty`;
+  const KEY_LAST_SYNCED = `${storageKeyPrefix}-db-sync-last-synced`;
+
+  // ── In-memory guard ───────────────────────────────────────────────────────
+  let syncing = false;
+
+  // ── Local state accessors ─────────────────────────────────────────────────
+  const getConfig = () => {
+    const saved = localStorage.getItem(KEY_CONFIG);
+    return saved ? JSON.parse(saved) : null;
+  };
+  const setConfig = (cfg) => {
+    if (cfg) localStorage.setItem(KEY_CONFIG, JSON.stringify(cfg));
+    else     localStorage.removeItem(KEY_CONFIG);
+  };
+  const getLastSynced = () => localStorage.getItem(KEY_LAST_SYNCED) || null;
+
+  const getHighWaterMark = () => {
+    const raw = localStorage.getItem(KEY_HWM);
+    const n = raw == null ? 0 : Number(raw);
+    return Number.isFinite(n) ? n : 0;
+  };
+  const setHighWaterMark = (seq) => {
+    localStorage.setItem(KEY_HWM, String(seq));
+  };
+
+  // Dirty set persisted as a JSON array; deduped via Set on read/write.
+  const getDirtySet = () => {
+    const raw = localStorage.getItem(KEY_DIRTY);
+    if (!raw) return [];
+    try {
+      const arr = JSON.parse(raw);
+      return Array.isArray(arr) ? arr : [];
+    } catch {
+      return [];
+    }
+  };
+  const writeDirtySet = (ids) => {
+    localStorage.setItem(KEY_DIRTY, JSON.stringify([...new Set(ids)]));
+  };
+  const clearDirty = () => localStorage.removeItem(KEY_DIRTY);
+
+  // 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.
+  const markDirty = (entityId) => {
+    if (entityId == null) return;
+    const id = String(entityId);
+    const current = getDirtySet();
+    if (current.includes(id)) return;
+    current.push(id);
+    writeDirtySet(current);
+  };
+
+  // ── Root key / salt bootstrap ─────────────────────────────────────────────
+  // Ensures the per-account root key is available, fetching or registering the
+  // salt with the vault on first use.
+  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;
+    }
+
+    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);
+  };
+
+  // ── 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.
+  const pushDirtyRows = async () => {
+    const dirty = getDirtySet();
+    if (dirty.length === 0) return { written: 0, deleted: 0, maxSeq: getHighWaterMark() };
+
+    await ensureRootKey();
+
+    const upserts = [];
+    const deletes = [];
+    for (const entityId of dirty) {
+      const entity = await getLocalEntity(entityId);
+      if (entity == null) {
+        deletes.push(entityId);
+      } else {
+        const ciphertext = await encryptEntity(entity, entityId);
+        upserts.push({ entityId, ciphertext, createdAt: Date.now() });
+      }
+    }
+
+    // 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();
+    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);
+      if (r && typeof r.maxSeq === 'number') maxSeq = Math.max(maxSeq, r.maxSeq);
+    }
+    if (upserts.length > 0) {
+      const result = await vault.batch(app, { accountId, rows: upserts });
+      if (result && typeof result.maxSeq === 'number') maxSeq = Math.max(maxSeq, result.maxSeq);
+    }
+
+    // Full acknowledgment: safe to mark clean.
+    clearDirty();
+    setHighWaterMark(maxSeq);
+    return { written: upserts.length, deleted: deletes.length, maxSeq };
+  };
+
+  // ── 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.
+  const pullRemoteChanges = async () => {
+    let since = getHighWaterMark();
+    let maxSeq = since;
+    let appliedRemote = false;
+
+    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.ciphertext, 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]);
+          }
+          // 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);
+      }
+
+      hasMore = !!more;
+    }
+
+    setHighWaterMark(Math.max(getHighWaterMark(), maxSeq));
+    return { maxSeq, appliedRemote };
+  };
+
+  // ── Step 3: update device cursor ──────────────────────────────────────────
+  // Best-effort: a failure here only affects tombstone GC timing, never sync
+  // correctness, so it is swallowed.
+  const updateDeviceCursor = async () => {
+    if (!deviceId) return { updated: false };
+    try {
+      return await vault.device(app, {
+        accountId,
+        deviceId,
+        lastSeenSeq: getHighWaterMark(),
+      });
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.warn(`[${appId}] db sync device cursor update failed (non-fatal):`, err);
+      return { updated: false };
+    }
+  };
+
+  // ── Full cycle ────────────────────────────────────────────────────────────
+  const dbSyncCycle = async () => {
+    const cfg = getConfig();
+    if (cfg && cfg.enabled === false) return;
+    if (syncing) return;
+    syncing = true;
+    onStatusChange?.('uploading');
+    onError?.(null, null, false);
+    try {
+      await pushDirtyRows();
+      onStatusChange?.('downloading');
+      await pullRemoteChanges();
+      await updateDeviceCursor();
+
+      const now = new Date().toISOString();
+      localStorage.setItem(KEY_LAST_SYNCED, now);
+      onStatusChange?.('success');
+    } 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');
+    } finally {
+      syncing = false;
+    }
+  };
+
+  // ── Public API ────────────────────────────────────────────────────────────
+  return {
+    transportMode: 'database',
+
+    // Lifecycle
+    sync: dbSyncCycle,
+    dbSyncCycle,
+    pushDirtyRows,
+    pullRemoteChanges,
+    updateDeviceCursor,
+    ensureRootKey,
+
+    // Dirty tracking
+    markDirty,
+    getDirtySet,
+    clearDirty,
+
+    // Cursor
+    getHighWaterMark,
+    setHighWaterMark,
+
+    // Config
+    getConfig,
+    setConfig,
+    getLastSynced,
+
+    // State queries
+    isSyncing:        () => syncing,
+    hasEncryptionReady: hasDbRootKey,
+
+    // Sub-modules
+    vault,
+  };
+};

package/src/engine.js

@@ -22,6 +22,7 @@
 //     written before Step 6 don't include either field).
 
 import { createProviders, webdavFetch } from './providers.js';
+import { createDbSyncEngine } from './dbEngine.js';
 import {
   hasEncryptionReady,
 } from './crypto.js';
@@ -56,6 +57,13 @@ const MIN_SYNC_DURATION_MS = 2000;
  * config schema and behavioral contract.
  */
 export const createSyncEngine = (config) => {
+  // Transport selection (Phase 3). When transportMode is 'database', delegate to
+  // the row-grained DB engine. The default ('file', or unset) falls through to
+  // the original file-tier engine below, whose code path is unchanged.
+  if (config.transportMode === 'database') {
+    return createDbSyncEngine(config);
+  }
+
   const {
     storageKeyPrefix,
     appId,

package/src/index.js

@@ -38,3 +38,15 @@ export {
   SCHEMA_VERSION,
   SUPPORTED_MAX_SCHEMA_VERSION,
 } from './engine.js';
+
+// Phase 3: database transport (selected via transportMode: 'database').
+export { createDbSyncEngine } from './dbEngine.js';
+export { createVaultClient } from './vaultClient.js';
+export {
+  setupDbRootKey,
+  initDbRootKey,
+  clearDbRootKey,
+  hasDbRootKey,
+  encryptEntity,
+  decryptEntity,
+} from './dbCrypto.js';

package/src/providers.js

@@ -246,7 +246,12 @@ export function createProviders(engineConfig) {
           // nativeHttpRequest != null means the Android HTTP bridge is available,
           // which bypasses Koofr's server-side block on Vercel proxy IPs.
           const onAndroid = engineConfig.nativeHttpRequest != null;
-          if (!onAndroid) return { success: false, error: "Koofr is blocking requests from the web app's server. Use the Android app — it connects to Koofr directly." };
+          if (!onAndroid) {
+            if (engineConfig.isHostedApp) {
+              return { success: false, error: "Koofr blocks requests from dayglance.app's servers. Use a self-hosted instance or the Android app to connect directly." };
+            }
+            return { success: false, error: "Access forbidden. If requests are going through a proxy, Koofr may be blocking that server's IP." };
+          }
           return { success: false, error: 'Access forbidden. Check that your app password is correct and has not been revoked.' };
         }
         return { success: false, error: `Unexpected response: ${res.status}${res.statusText ? ' ' + res.statusText : ''}` };

package/src/vaultClient.js

@@ -0,0 +1,162 @@
+// HTTP client for the GLANCEvault database backend (Phase 3).
+//
+// GLANCEvault is a self-hosted Express/SQLite server that stores one encrypted
+// row per entity. This client wraps its sync endpoints. All requests carry a
+// Bearer token. The fetch implementation is injectable so tests can supply a
+// synthetic transport and native/Electron shells can route through their own
+// network bridge if needed; it defaults to the platform fetch.
+//
+// Endpoints:
+//   POST   /sync/:app/batch                     upsert rows, returns { written, maxSeq }
+//   GET    /sync/:app/list?accountId=&since=     incremental fetch, { rows, hasMore }
+//   GET    /sync/:app/:entityId?accountId=       fetch one row
+//   DELETE /sync/:app/:entityId?accountId=       soft-delete a row
+//   POST   /sync/:app/device                     update device cursor, { updated }
+//   GET    /salt/:accountId                      fetch the account root-key salt
+//   PUT    /salt/:accountId                      register a salt (first-write-wins)
+//
+// Salts cross the wire as base64 in a { salt } field. The client converts to and
+// from Uint8Array at the boundary so callers always deal in bytes.
+
+import { toBase64, fromBase64 } from './dbCrypto.js';
+
+class VaultError extends Error {
+  constructor(message, status) {
+    super(message);
+    this.name = 'VaultError';
+    this.code = 'VAULT_ERROR';
+    this.status = status;
+  }
+}
+
+/**
+ * Creates a vault client bound to a server URL and token.
+ *
+ * @param {object} config
+ * @param {string} config.vaultUrl   - base URL of the GLANCEvault server
+ * @param {string} config.vaultToken - Bearer token
+ * @param {Function} [config.fetchImpl] - fetch implementation (defaults to global fetch)
+ */
+export function createVaultClient({ vaultUrl, vaultToken, fetchImpl } = {}) {
+  if (!vaultUrl)   throw new Error('createVaultClient: vaultUrl is required');
+  if (!vaultToken) throw new Error('createVaultClient: vaultToken is required');
+  const doFetch = fetchImpl || globalThis.fetch;
+  if (typeof doFetch !== 'function') {
+    throw new Error('createVaultClient: no fetch implementation available');
+  }
+
+  const base = vaultUrl.replace(/\/+$/, '');
+  const authHeaders = (extra = {}) => ({
+    Authorization: `Bearer ${vaultToken}`,
+    ...extra,
+  });
+
+  const request = async (method, path, { body, query } = {}) => {
+    let url = base + path;
+    if (query) {
+      const qs = new URLSearchParams(query).toString();
+      if (qs) url += `?${qs}`;
+    }
+    const init = { method, headers: authHeaders() };
+    if (body !== undefined) {
+      init.headers['Content-Type'] = 'application/json';
+      init.body = JSON.stringify(body);
+    }
+    const res = await doFetch(url, init);
+    return res;
+  };
+
+  const jsonOrThrow = async (res, context) => {
+    if (!res.ok) {
+      throw new VaultError(`${context} failed: ${res.status}`, res.status);
+    }
+    return res.json();
+  };
+
+  return {
+    /**
+     * Upserts a batch of rows. Each row is { entityId, ciphertext, createdAt }.
+     * @returns {Promise<{ written: number, maxSeq: number }>}
+     */
+    async batch(app, { accountId, rows }) {
+      const res = await request('POST', `/sync/${encodeURIComponent(app)}/batch`, {
+        body: { accountId, rows },
+      });
+      return jsonOrThrow(res, 'batch upsert');
+    },
+
+    /**
+     * Fetches rows changed since `since` (a seq). One page per call.
+     * @returns {Promise<{ rows: Array, hasMore: boolean }>}
+     */
+    async list(app, { accountId, since }) {
+      const res = await request('GET', `/sync/${encodeURIComponent(app)}/list`, {
+        query: { accountId, since: String(since) },
+      });
+      return jsonOrThrow(res, 'list');
+    },
+
+    /**
+     * Fetches a single row by entityId. Returns null on 404.
+     */
+    async getRow(app, entityId, accountId) {
+      const res = await request('GET', `/sync/${encodeURIComponent(app)}/${encodeURIComponent(entityId)}`, {
+        query: { accountId },
+      });
+      if (res.status === 404) return null;
+      return jsonOrThrow(res, 'get row');
+    },
+
+    /**
+     * Soft-deletes a row by entityId. Returns the server response (may include
+     * the new seq for the tombstone).
+     */
+    async deleteRow(app, entityId, accountId) {
+      const res = await request('DELETE', `/sync/${encodeURIComponent(app)}/${encodeURIComponent(entityId)}`, {
+        query: { accountId },
+      });
+      if (res.status === 404) return null;
+      return jsonOrThrow(res, 'delete row');
+    },
+
+    /**
+     * Updates this device's cursor. Best-effort: callers should not let a
+     * failure here abort the sync cycle.
+     * @returns {Promise<{ updated: boolean }>}
+     */
+    async device(app, { accountId, deviceId, lastSeenSeq }) {
+      const res = await request('POST', `/sync/${encodeURIComponent(app)}/device`, {
+        body: { accountId, deviceId, lastSeenSeq },
+      });
+      return jsonOrThrow(res, 'device cursor');
+    },
+
+    /**
+     * Fetches the account's root-key salt. Returns a Uint8Array, or null if no
+     * salt is registered yet (404).
+     */
+    async getSalt(accountId) {
+      const res = await request('GET', `/salt/${encodeURIComponent(accountId)}`);
+      if (res.status === 404) return null;
+      const body = await jsonOrThrow(res, 'get salt');
+      return body && body.salt ? fromBase64(body.salt) : null;
+    },
+
+    /**
+     * Registers a salt (first-write-wins). Returns whatever salt the server has
+     * stored as a Uint8Array, which may differ from the one sent if another
+     * device registered first.
+     *
+     * @param {string} accountId
+     * @param {Uint8Array} salt
+     * @returns {Promise<Uint8Array>}
+     */
+    async putSalt(accountId, salt) {
+      const res = await request('PUT', `/salt/${encodeURIComponent(accountId)}`, {
+        body: { salt: toBase64(salt) },
+      });
+      const body = await jsonOrThrow(res, 'put salt');
+      return body && body.salt ? fromBase64(body.salt) : salt;
+    },
+  };
+}

package/types/index.d.ts

@@ -265,6 +265,9 @@ export interface ValidationResult {
 }
 
 export interface SyncEngineConfig {
+  // Transport selection (Phase 3). Defaults to 'file' when unset.
+  transportMode?: 'file' | 'database';
+
   // Identity
   storageKeyPrefix: string;
   cryptoDBName: string;
@@ -336,7 +339,119 @@ export interface SyncEngine {
   webdavFetch: WebdavFetch;
 }
 
+// createSyncEngine returns the file-tier engine by default, or the DB engine
+// when config.transportMode is 'database'.
 export function createSyncEngine(config: SyncEngineConfig): SyncEngine;
+export function createSyncEngine(config: DbSyncEngineConfig & { transportMode: 'database' }): DbSyncEngine;
 
 export const SCHEMA_VERSION: number;
 export const SUPPORTED_MAX_SCHEMA_VERSION: number;
+
+// ---------------------------------------------------------------------------
+// Database transport (Phase 3)
+// ---------------------------------------------------------------------------
+
+// Per-entity crypto. The root key is PBKDF2-derived from the passphrase and a
+// per-account salt; per-entity AES-GCM keys are HKDF-derived from it.
+export interface DbCryptoConfig {
+  cryptoDBName: string;
+  nativeGetSyncKey?: (() => string | null | Promise<string | null>) | null;
+  nativeStoreSyncKey?: ((value: string | null) => void) | null;
+}
+
+export function setupDbRootKey(passphrase: string, salt: Uint8Array, config: DbCryptoConfig): Promise<void>;
+export function initDbRootKey(config: DbCryptoConfig): Promise<boolean>;
+export function clearDbRootKey(config: DbCryptoConfig): Promise<void>;
+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>;
+
+// Row exchanged with GLANCEvault. ciphertext is base64(IV || AES-GCM output).
+export interface VaultRow {
+  entityId: string;
+  ciphertext: string;
+  createdAt: number;
+}
+
+export interface VaultPulledRow extends Partial<VaultRow> {
+  entityId: string;
+  seq: number;
+  deleted?: boolean;
+  ciphertext?: string;
+}
+
+export interface VaultClient {
+  batch(app: string, args: { accountId: string; rows: VaultRow[] }): Promise<{ written: number; maxSeq: number }>;
+  list(app: string, args: { accountId: string; since: number }): Promise<{ rows: VaultPulledRow[]; hasMore: boolean }>;
+  getRow(app: string, entityId: string, accountId: string): Promise<VaultPulledRow | null>;
+  deleteRow(app: string, entityId: string, accountId: string): Promise<{ seq?: number } | null>;
+  device(app: string, args: { accountId: string; deviceId: string; lastSeenSeq: number }): Promise<{ updated: boolean }>;
+  getSalt(accountId: string): Promise<Uint8Array | null>;
+  putSalt(accountId: string, salt: Uint8Array): Promise<Uint8Array>;
+}
+
+export function createVaultClient(config: {
+  vaultUrl: string;
+  vaultToken: string;
+  fetchImpl?: typeof fetch;
+}): VaultClient;
+
+export interface DbSyncEngineConfig {
+  // Identity / local state
+  storageKeyPrefix: string;
+  appId: string;
+  vaultApp?: string;
+  cryptoDBName: string;
+  nativeGetSyncKey?: (() => string | null | Promise<string | null>) | null;
+  nativeStoreSyncKey?: ((value: string | null) => void) | null;
+
+  // Transport selection
+  transportMode?: 'database';
+
+  // Vault connection
+  vaultUrl?: string;
+  vaultToken?: string;
+  accountId: string;
+  deviceId?: string;
+  fetchImpl?: typeof fetch;
+  vaultClient?: VaultClient;
+
+  // Data callbacks
+  getLocalEntity: (entityId: string) => unknown | Promise<unknown>;
+  applyRemoteEntity: (entityId: string, entity: unknown) => void | Promise<void>;
+  applyRemoteDelete: (entityId: string) => void | Promise<void>;
+  isInsertOnly?: (entity: unknown, entityId: string) => boolean;
+  getEntityLastModified?: (entity: unknown) => string | number | undefined;
+
+  // Event callbacks
+  onStatusChange?: (status: SyncStatus, hints?: { from?: SyncStatus }) => void;
+  onError?: (message: string | null, code: SyncErrorCode | null, isHardStop: boolean) => void;
+}
+
+export interface DbSyncEngine {
+  transportMode: 'database';
+  sync(): Promise<void>;
+  dbSyncCycle(): Promise<void>;
+  pushDirtyRows(): Promise<{ written: number; deleted: number; maxSeq: number }>;
+  pullRemoteChanges(): Promise<{ maxSeq: number; appliedRemote: boolean }>;
+  updateDeviceCursor(): Promise<{ updated: boolean }>;
+  ensureRootKey(): Promise<void>;
+
+  markDirty(entityId: string): void;
+  getDirtySet(): string[];
+  clearDirty(): void;
+
+  getHighWaterMark(): number;
+  setHighWaterMark(seq: number): void;
+
+  getConfig(): Record<string, unknown> | null;
+  setConfig(config: Record<string, unknown> | null): void;
+  getLastSynced(): string | null;
+
+  isSyncing(): boolean;
+  hasEncryptionReady(): boolean;
+
+  vault: VaultClient;
+}
+
+export function createDbSyncEngine(config: DbSyncEngineConfig): DbSyncEngine;