@glance-apps/sync 1.5.0 → 1.5.2

package/CHANGELOG.md

@@ -7,6 +7,59 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.5.2] - 2026-06-19
+
+### Fixed
+
+- **Key verifier no longer fails with a cryptic `get row failed: 400`.** The
+  verifier's single-row GET (`GET /sync/{app}/__glance_keycheck`) is scoped by
+  `accountId`, which GLANCEvault requires as a query param on every row-scoped
+  endpoint. When the verifier ran with an `accountId` that was empty or
+  whitespace — e.g. fired during reconstruction before the account id was
+  populated — the request went out as `?accountId=` (or `?accountId=+++`), which
+  the server correctly rejects with `400 {"error":"accountId is required"}`,
+  aborting enable. The default `createVaultClient` now validates `accountId` on
+  every row-scoped call (`batch`, `list`, single-row GET, `DELETE`, `device`) and
+  throws a clear, typed, retryable `ACCOUNT_ID_REQUIRED` instead of putting a
+  malformed `accountId` on the wire — so the next cycle (once the id is loaded)
+  succeeds. `createDbSyncEngine` also rejects an empty/whitespace `accountId` at
+  construction (a whitespace-only id previously passed the plain falsy check).
+  The verifier path surfaces `ACCOUNT_ID_REQUIRED` (and `PASSPHRASE_REQUIRED`)
+  with their own code rather than mislabeling them `VERIFIER_UNSUPPORTED`. The
+  verifier GET correctly carries `?accountId=...` (like the working `list` call)
+  and, on a fresh account, 404 → writes the verifier via `batch` with
+  `accountId` + `insertOnly: true`.
+
+### Added
+
+- `ACCOUNT_ID_REQUIRED` standardized on the `SyncErrorCode` type.
+
+## [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

package/package.json

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

package/src/dbEngine.js

@@ -61,8 +61,9 @@ const ts = (v) => {
  *
  * Event callbacks (optional):
  * @param {Function} [config.onStatusChange]
- * @param {Function} [config.onError]      - (message, code, isHardStop) called with code 'KEY_MISMATCH' on a wrong key
+ * @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 {
@@ -85,12 +86,19 @@ export const createDbSyncEngine = (config) => {
     onStatusChange,
     onError,
     onRowsSkipped,
+    allowUnverified = false,
   } = 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 accountId !== 'string' || accountId.trim() === '') {
+    // Reject empty/whitespace too: a whitespace-only id passes a plain falsy
+    // check but serialises to `?accountId=+++`, which the server trims to empty
+    // and rejects with a cryptic 400 on every row-scoped call (incl. the key
+    // verifier's single-row GET).
+    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');
@@ -233,15 +241,51 @@ export const createDbSyncEngine = (config) => {
   // 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.)
+  // Client-readiness failures (no passphrase yet, or accountId not populated)
+  // are NOT a server problem: re-throw them as-is so they surface with their own
+  // typed, retryable code instead of being mislabeled "update your server".
+  const isClientNotReady = (err) =>
+    err && (err.code === 'ACCOUNT_ID_REQUIRED' || err.code === 'PASSPHRASE_REQUIRED');
+
+  const verifierUnsupported = (cause) => {
+    if (isClientNotReady(cause)) throw 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; }
 
-    const row = await vault.getRow(app, KEYCHECK_ENTITY_ID, accountId);
+    // 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) {
-      // Existing account: the verifier must decrypt under our derived key.
+      // Outcome 1: existing account — the verifier must decrypt under our key.
       try {
         await decryptEntity(row.envelope, KEYCHECK_ENTITY_ID);
         verified = true;
@@ -251,15 +295,22 @@ export const createDbSyncEngine = (config) => {
         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.
+      // 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);
-      await vault.batch(app, {
-        accountId,
-        rows: [{ entityId: KEYCHECK_ENTITY_ID, envelope, createdAt: Date.now(), insertOnly: true }],
-      });
+      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;
     }
   };

package/src/vaultClient.js

@@ -73,12 +73,27 @@ export function createVaultClient({ vaultUrl, vaultToken, fetchImpl } = {}) {
     return res.json();
   };
 
+  // accountId scopes every row-scoped endpoint (batch, list, single-row GET,
+  // DELETE, device). The server has no default and rejects a missing/empty value
+  // with a cryptic 400 {"error":"accountId is required"}. Validate it here so a
+  // caller that fires before the account id is populated (e.g. the key verifier
+  // running during reconstruction) fails with a clear, typed, retryable error
+  // and we never put a malformed `?accountId=` on the wire.
+  const requireAccountId = (accountId, context) => {
+    if (typeof accountId !== 'string' || accountId.trim() === '') {
+      const err = new Error(`${context}: accountId is required but was missing or empty.`);
+      err.code = 'ACCOUNT_ID_REQUIRED';
+      throw err;
+    }
+  };
+
   return {
     /**
      * Upserts a batch of rows. Each row is { entityId, envelope, createdAt }.
      * @returns {Promise<{ written: number, maxSeq: number }>}
      */
     async batch(app, { accountId, rows }) {
+      requireAccountId(accountId, 'batch upsert');
       const res = await request('POST', `/sync/${encodeURIComponent(app)}/batch`, {
         body: { accountId, rows },
       });
@@ -90,6 +105,7 @@ export function createVaultClient({ vaultUrl, vaultToken, fetchImpl } = {}) {
      * @returns {Promise<{ rows: Array, hasMore: boolean }>}
      */
     async list(app, { accountId, since }) {
+      requireAccountId(accountId, 'list');
       const res = await request('GET', `/sync/${encodeURIComponent(app)}/list`, {
         query: { accountId, since: String(since) },
       });
@@ -100,6 +116,7 @@ export function createVaultClient({ vaultUrl, vaultToken, fetchImpl } = {}) {
      * Fetches a single row by entityId. Returns null on 404.
      */
     async getRow(app, entityId, accountId) {
+      requireAccountId(accountId, 'get row');
       const res = await request('GET', `/sync/${encodeURIComponent(app)}/${encodeURIComponent(entityId)}`, {
         query: { accountId },
       });
@@ -112,6 +129,7 @@ export function createVaultClient({ vaultUrl, vaultToken, fetchImpl } = {}) {
      * the new seq for the tombstone).
      */
     async deleteRow(app, entityId, accountId) {
+      requireAccountId(accountId, 'delete row');
       const res = await request('DELETE', `/sync/${encodeURIComponent(app)}/${encodeURIComponent(entityId)}`, {
         query: { accountId },
       });
@@ -125,6 +143,7 @@ export function createVaultClient({ vaultUrl, vaultToken, fetchImpl } = {}) {
      * @returns {Promise<{ updated: boolean }>}
      */
     async device(app, { accountId, deviceId, lastSeenSeq }) {
+      requireAccountId(accountId, 'device cursor');
       const res = await request('POST', `/sync/${encodeURIComponent(app)}/device`, {
         body: { accountId, deviceId, lastSeenSeq },
       });

package/types/index.d.ts

@@ -21,7 +21,13 @@ export type SyncErrorCode =
   | 'KEY_MISMATCH'
   // DB transport: a single row failed to decrypt (surfaced as a count via
   // onRowsSkipped, never thrown).
-  | 'ROW_DECRYPT_FAILED';
+  | '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'
+  // DB transport: a row-scoped call (incl. the key verifier) was made before the
+  // accountId was populated — retryable once the account id is available.
+  | 'ACCOUNT_ID_REQUIRED';
 
 export type SyncStatus = 'idle' | 'uploading' | 'downloading' | 'success' | 'error';
 
@@ -438,10 +444,16 @@ 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.
+  // 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. */