@syncular/client 0.21.0 → 0.21.1

package/dist/client.js

@@ -9,6 +9,7 @@ import { ProgressEmitter, } from './progress.js';
  * `sync()` round (§7.2); local reads go straight to the database.
  */
 import { canonicalScopeJson, decodeMessage, decodeRow, decodeRowsSegment, encodeMessage, encodePresencePublish, MessageStreamScanner, PROTOCOL_WIRE_VERSION, parseRealtimeServerEvent, REALTIME_TAG_DELTA, REALTIME_TAG_ROUND, } from '@syncular/core';
+import { EncryptError } from '@syncular/core';
 import { applyCommitFrame, applyRowsSegment, applySqliteSegment, deleteLocalRow, deleteScopedRows, evictScopedRows, yieldToHost, upsertLocalRow, } from './apply.js';
 import { clearPendingUpload, computeBlobId, deleteUnreferencedCachedBlobs, enforceBlobCacheCap, ensureBlobSchema, getCachedBlob, listPendingUploads, parseBlobRef, putCachedBlob, recordPendingUpload, schemaHasBlobs, serializeBlobRef, } from './blob.js';
 import { registerDevtools } from './devtools.js';
@@ -1807,8 +1808,20 @@ export class SyncClient {
             try {
                 pushFrames.push(
                 // §5.11: encrypted columns are encrypted at this encode-at-send
-                // seam before the row codec serializes them.
-                await encodeOutboxCommit(this.#schema, commit, this.#encryption));
+                // seam before the row codec serializes them. The stored local row
+                // supplies an ABSENT key-id selector (§6.1 presence set first,
+                // stored row second); an unresolvable key becomes a durable
+                // rejection for that commit, never a sync() throw.
+                await encodeOutboxCommit(this.#schema, commit, this.#encryption, (table, rowId) => {
+                    const selector = this.#encryption?.keyIdColumns?.[table.name];
+                    if (selector === undefined)
+                        return undefined;
+                    const row = this.#db.query(`SELECT ${quoteIdent(selector)} AS value FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)} = ?`, [rowId])[0];
+                    const value = row?.value;
+                    return typeof value === 'string' && value.length > 0
+                        ? value
+                        : undefined;
+                }));
                 outbox.push(commit);
                 ops += commit.operations.length;
             }
@@ -1817,6 +1830,10 @@ export class SyncClient {
                     this.#dropIncompatibleCommit(commit, error.message);
                     continue;
                 }
+                if (error instanceof EncryptError) {
+                    this.#dropIncompatibleCommit(commit, error.message, error.code);
+                    continue;
+                }
                 throw error;
             }
         }
@@ -1826,14 +1843,15 @@ export class SyncClient {
      * §7.4.4: drop a commit that cannot re-encode after a bump, mirroring the
      * §7.2 `rejected` surface — the commit leaves the outbox, its
      * purely-optimistic rows are undone, and a rejection record is raised.
+     * §5.11: the same drop carries an encode-seam `client.encrypt_failed`.
      */
-    #dropIncompatibleCommit(commit, message) {
+    #dropIncompatibleCommit(commit, message, code = OUTBOX_INCOMPATIBLE_CODE) {
         this.#applyBatch((batch) => {
             this.#rollbackFailedCommit(commit, batch);
             const rejection = {
                 clientCommitId: commit.clientCommitId,
                 opIndex: 0,
-                code: OUTBOX_INCOMPATIBLE_CODE,
+                code,
                 message,
                 retryable: false,
                 ...(commit.operations[0] !== undefined

package/dist/encryption.d.ts

@@ -57,7 +57,7 @@ export declare function encryptionConfigFromKeyring(keyring: EncryptionKeyringCo
  * value becomes the §5.11 ciphertext-envelope `bytes`. NULLs pass through
  * unencrypted (§5.11).
  */
-export declare function encryptRowValues<T extends RowValue | undefined>(config: EncryptionConfig, table: CompiledClientTable, rowId: string, values: readonly T[]): Promise<T[]>;
+export declare function encryptRowValues<T extends RowValue | undefined>(config: EncryptionConfig, table: CompiledClientTable, rowId: string, values: readonly T[], storedKeyId?: string): Promise<T[]>;
 /**
  * Decrypt the encrypted columns of a decoded positional row value array
  * (returns a new array). Called at the apply seam (§4.5 COMMIT, §5.6 rows

package/dist/encryption.js

@@ -8,7 +8,7 @@
  * bridge between the positional `RowValue[]` and the `@syncular/core` §5.11
  * envelope primitives.
  */
-import { DecryptError, decryptValue, encryptValue, KEY_LENGTH, } from '@syncular/core';
+import { DecryptError, decryptValue, EncryptError, encryptValue, KEY_LENGTH, } from '@syncular/core';
 import { ClientSyncError } from './errors.js';
 /**
  * Convert a portable keyring into the direct-client encryption contract.
@@ -36,7 +36,7 @@ function encryptionKeyId(config, table, rowId, values) {
     if (config.keyIdFor !== undefined) {
         const selected = config.keyIdFor(table.name, rowId, values);
         if (selected.length === 0) {
-            throw new DecryptError(`empty encryption key id selected for table ${JSON.stringify(table.name)}`);
+            throw new EncryptError(`empty encryption key id selected for table ${JSON.stringify(table.name)}`);
         }
         return selected;
     }
@@ -45,14 +45,14 @@ function encryptionKeyId(config, table, rowId, values) {
         return table.name;
     const index = table.columns.findIndex((column) => column.name === selectorColumn);
     if (index < 0) {
-        throw new DecryptError(`encryption key-id column ${JSON.stringify(selectorColumn)} is not present on table ${JSON.stringify(table.name)}`);
+        throw new EncryptError(`encryption key-id column ${JSON.stringify(selectorColumn)} is not present on table ${JSON.stringify(table.name)}`);
     }
     if (table.columns[index]?.encrypted === true) {
-        throw new DecryptError(`encryption key-id column ${JSON.stringify(selectorColumn)} on table ${JSON.stringify(table.name)} must not be encrypted`);
+        throw new EncryptError(`encryption key-id column ${JSON.stringify(selectorColumn)} on table ${JSON.stringify(table.name)} must not be encrypted`);
     }
     const selected = values[index];
     if (typeof selected !== 'string' || selected.length === 0) {
-        throw new DecryptError(`encryption key-id column ${JSON.stringify(selectorColumn)} on table ${JSON.stringify(table.name)} must contain a non-empty string`);
+        throw new EncryptError(`encryption key-id column ${JSON.stringify(selectorColumn)} on table ${JSON.stringify(table.name)} must contain a non-empty string`);
     }
     return selected;
 }
@@ -68,13 +68,38 @@ function declaredTypeOf(column) {
  * value becomes the §5.11 ciphertext-envelope `bytes`. NULLs pass through
  * unencrypted (§5.11).
  */
-export async function encryptRowValues(config, table, rowId, values) {
+export async function encryptRowValues(config, table, rowId, values, storedKeyId) {
     if (!table.hasEncryptedColumns)
         return values.slice();
     const out = values.slice();
-    // A sparse operation's absent columns are densified to null for key
-    // selection only; the encryption loop leaves them untouched.
-    const keyId = encryptionKeyId(config, table, rowId, values.map((value) => value ?? null));
+    // Sparse semantics: absent (undefined) and NULL columns are never
+    // re-encrypted, so a patch that presents no encrypted value needs no key.
+    let hasPresentEncrypted = false;
+    for (let i = 0; i < table.columns.length; i++) {
+        if (table.columns[i]?.encrypted !== true)
+            continue;
+        const value = out[i];
+        if (value !== undefined && value !== null) {
+            hasPresentEncrypted = true;
+            break;
+        }
+    }
+    if (!hasPresentEncrypted)
+        return out;
+    // Key selection reads the presence set first, then the stored local row.
+    // Absent slots densify to null for selection only; the loop below still
+    // leaves them untouched. Absent ≠ NULL (§6.1): only an ABSENT selector
+    // slot is filled from the stored row, never a present NULL.
+    const selected = values.map((value) => value ?? null);
+    const selectorColumn = config.keyIdColumns?.[table.name];
+    if (selectorColumn !== undefined &&
+        config.keyIdFor === undefined &&
+        storedKeyId !== undefined) {
+        const index = table.columns.findIndex((column) => column.name === selectorColumn);
+        if (index >= 0 && values[index] === undefined)
+            selected[index] = storedKeyId;
+    }
+    const keyId = encryptionKeyId(config, table, rowId, selected);
     for (let i = 0; i < table.columns.length; i++) {
         const column = table.columns[i];
         if (column === undefined || !column.encrypted)
@@ -84,7 +109,7 @@ export async function encryptRowValues(config, table, rowId, values) {
             continue; // NULL stays NULL
         const key = config.keyProvider(keyId);
         if (key === undefined) {
-            throw new DecryptError(`no encryption key for keyId ${JSON.stringify(keyId)} (table ${table.name})`);
+            throw new EncryptError(`no encryption key for keyId ${JSON.stringify(keyId)} (table ${table.name})`);
         }
         out[i] = (await encryptValue(declaredTypeOf(column), value, keyId, key, config.nonceSource));
     }

package/dist/outbox.d.ts

@@ -61,9 +61,10 @@ export declare class OutboxEncodeError extends ClientSyncError {
  * schema's row codec (§6.1). When `encryption` is configured, encrypted
  * columns (§5.11) are encrypted here — the encode-at-send seam — before the
  * row codec serializes them as ciphertext-envelope `bytes`. Async because
- * WebCrypto is async.
+ * WebCrypto is async. `storedKeyIdFor` supplies the stored local row's
+ * key-id selector for a sparse upsert that omits that column (§5.11).
  */
-export declare function encodeOutboxCommit(schema: CompiledClientSchema, commit: OutboxCommit, encryption?: EncryptionConfig): Promise<PushCommitFrame>;
+export declare function encodeOutboxCommit(schema: CompiledClientSchema, commit: OutboxCommit, encryption?: EncryptionConfig, storedKeyIdFor?: (table: CompiledClientTable, rowId: string) => string | undefined): Promise<PushCommitFrame>;
 /**
  * §3.3: drop pending commits that write into a revoked scope instead of
  * replaying them into guaranteed rejections. A whole commit is dropped when

package/dist/outbox.js

@@ -132,9 +132,10 @@ function sparseValues(table, values) {
  * schema's row codec (§6.1). When `encryption` is configured, encrypted
  * columns (§5.11) are encrypted here — the encode-at-send seam — before the
  * row codec serializes them as ciphertext-envelope `bytes`. Async because
- * WebCrypto is async.
+ * WebCrypto is async. `storedKeyIdFor` supplies the stored local row's
+ * key-id selector for a sparse upsert that omits that column (§5.11).
  */
-export async function encodeOutboxCommit(schema, commit, encryption) {
+export async function encodeOutboxCommit(schema, commit, encryption, storedKeyIdFor) {
     const operations = [];
     for (const op of commit.operations) {
         if (op.op === 'delete') {
@@ -160,7 +161,7 @@ export async function encodeOutboxCommit(schema, commit, encryption) {
         if (encryption !== undefined && table.hasEncryptedColumns) {
             // Lazy: opt-in E2EE never enters an encryption-free app's bundle.
             const { encryptRowValues } = await import('./encryption.js');
-            values = await encryptRowValues(encryption, table, op.rowId, values);
+            values = await encryptRowValues(encryption, table, op.rowId, values, storedKeyIdFor?.(table, op.rowId));
         }
         operations.push({
             table: op.table,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.21.0",
+  "version": "0.21.1",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -89,10 +89,10 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.21.0"
+    "@syncular/core": "0.21.1"
   },
   "devDependencies": {
-    "@syncular/server": "0.21.0",
+    "@syncular/server": "0.21.1",
     "playwright": "1.63.0"
   }
 }

package/src/client.ts

@@ -37,6 +37,7 @@ import {
   type SubStartFrame,
   type WakeReason,
 } from '@syncular/core';
+import { EncryptError } from '@syncular/core';
 import {
   applyCommitFrame,
   applyRowsSegment,
@@ -2638,8 +2639,27 @@ export class SyncClient {
       try {
         pushFrames.push(
           // §5.11: encrypted columns are encrypted at this encode-at-send
-          // seam before the row codec serializes them.
-          await encodeOutboxCommit(this.#schema, commit, this.#encryption),
+          // seam before the row codec serializes them. The stored local row
+          // supplies an ABSENT key-id selector (§6.1 presence set first,
+          // stored row second); an unresolvable key becomes a durable
+          // rejection for that commit, never a sync() throw.
+          await encodeOutboxCommit(
+            this.#schema,
+            commit,
+            this.#encryption,
+            (table, rowId) => {
+              const selector = this.#encryption?.keyIdColumns?.[table.name];
+              if (selector === undefined) return undefined;
+              const row = this.#db.query(
+                `SELECT ${quoteIdent(selector)} AS value FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)} = ?`,
+                [rowId],
+              )[0];
+              const value = row?.value;
+              return typeof value === 'string' && value.length > 0
+                ? value
+                : undefined;
+            },
+          ),
         );
         outbox.push(commit);
         ops += commit.operations.length;
@@ -2648,6 +2668,10 @@ export class SyncClient {
           this.#dropIncompatibleCommit(commit, error.message);
           continue;
         }
+        if (error instanceof EncryptError) {
+          this.#dropIncompatibleCommit(commit, error.message, error.code);
+          continue;
+        }
         throw error;
       }
     }
@@ -2658,14 +2682,19 @@ export class SyncClient {
    * §7.4.4: drop a commit that cannot re-encode after a bump, mirroring the
    * §7.2 `rejected` surface — the commit leaves the outbox, its
    * purely-optimistic rows are undone, and a rejection record is raised.
+   * §5.11: the same drop carries an encode-seam `client.encrypt_failed`.
    */
-  #dropIncompatibleCommit(commit: OutboxCommit, message: string): void {
+  #dropIncompatibleCommit(
+    commit: OutboxCommit,
+    message: string,
+    code: string = OUTBOX_INCOMPATIBLE_CODE,
+  ): void {
     this.#applyBatch((batch) => {
       this.#rollbackFailedCommit(commit, batch);
       const rejection: RejectionRecord = {
         clientCommitId: commit.clientCommitId,
         opIndex: 0,
-        code: OUTBOX_INCOMPATIBLE_CODE,
+        code,
         message,
         retryable: false,
         ...(commit.operations[0] !== undefined

package/src/encryption.ts

@@ -12,6 +12,7 @@ import {
   type DeclaredType,
   DecryptError,
   decryptValue,
+  EncryptError,
   encryptValue,
   KEY_LENGTH,
   type NonceSource,
@@ -99,7 +100,7 @@ function encryptionKeyId(
   if (config.keyIdFor !== undefined) {
     const selected = config.keyIdFor(table.name, rowId, values);
     if (selected.length === 0) {
-      throw new DecryptError(
+      throw new EncryptError(
         `empty encryption key id selected for table ${JSON.stringify(table.name)}`,
       );
     }
@@ -111,18 +112,18 @@ function encryptionKeyId(
     (column) => column.name === selectorColumn,
   );
   if (index < 0) {
-    throw new DecryptError(
+    throw new EncryptError(
       `encryption key-id column ${JSON.stringify(selectorColumn)} is not present on table ${JSON.stringify(table.name)}`,
     );
   }
   if (table.columns[index]?.encrypted === true) {
-    throw new DecryptError(
+    throw new EncryptError(
       `encryption key-id column ${JSON.stringify(selectorColumn)} on table ${JSON.stringify(table.name)} must not be encrypted`,
     );
   }
   const selected = values[index];
   if (typeof selected !== 'string' || selected.length === 0) {
-    throw new DecryptError(
+    throw new EncryptError(
       `encryption key-id column ${JSON.stringify(selectorColumn)} on table ${JSON.stringify(table.name)} must contain a non-empty string`,
     );
   }
@@ -147,17 +148,40 @@ export async function encryptRowValues<T extends RowValue | undefined>(
   table: CompiledClientTable,
   rowId: string,
   values: readonly T[],
+  storedKeyId?: string,
 ): Promise<T[]> {
   if (!table.hasEncryptedColumns) return values.slice();
   const out = values.slice();
-  // A sparse operation's absent columns are densified to null for key
-  // selection only; the encryption loop leaves them untouched.
-  const keyId = encryptionKeyId(
-    config,
-    table,
-    rowId,
-    values.map((value) => value ?? null),
-  );
+  // Sparse semantics: absent (undefined) and NULL columns are never
+  // re-encrypted, so a patch that presents no encrypted value needs no key.
+  let hasPresentEncrypted = false;
+  for (let i = 0; i < table.columns.length; i++) {
+    if (table.columns[i]?.encrypted !== true) continue;
+    const value = out[i];
+    if (value !== undefined && value !== null) {
+      hasPresentEncrypted = true;
+      break;
+    }
+  }
+  if (!hasPresentEncrypted) return out;
+  // Key selection reads the presence set first, then the stored local row.
+  // Absent slots densify to null for selection only; the loop below still
+  // leaves them untouched. Absent ≠ NULL (§6.1): only an ABSENT selector
+  // slot is filled from the stored row, never a present NULL.
+  const selected: RowValue[] = values.map((value) => value ?? null);
+  const selectorColumn = config.keyIdColumns?.[table.name];
+  if (
+    selectorColumn !== undefined &&
+    config.keyIdFor === undefined &&
+    storedKeyId !== undefined
+  ) {
+    const index = table.columns.findIndex(
+      (column) => column.name === selectorColumn,
+    );
+    if (index >= 0 && values[index] === undefined)
+      selected[index] = storedKeyId;
+  }
+  const keyId = encryptionKeyId(config, table, rowId, selected);
   for (let i = 0; i < table.columns.length; i++) {
     const column = table.columns[i];
     if (column === undefined || !column.encrypted) continue;
@@ -165,7 +189,7 @@ export async function encryptRowValues<T extends RowValue | undefined>(
     if (value === null || value === undefined) continue; // NULL stays NULL
     const key = config.keyProvider(keyId);
     if (key === undefined) {
-      throw new DecryptError(
+      throw new EncryptError(
         `no encryption key for keyId ${JSON.stringify(keyId)} (table ${table.name})`,
       );
     }

package/src/outbox.ts

@@ -237,12 +237,17 @@ function sparseValues(
  * schema's row codec (§6.1). When `encryption` is configured, encrypted
  * columns (§5.11) are encrypted here — the encode-at-send seam — before the
  * row codec serializes them as ciphertext-envelope `bytes`. Async because
- * WebCrypto is async.
+ * WebCrypto is async. `storedKeyIdFor` supplies the stored local row's
+ * key-id selector for a sparse upsert that omits that column (§5.11).
  */
 export async function encodeOutboxCommit(
   schema: CompiledClientSchema,
   commit: OutboxCommit,
   encryption?: EncryptionConfig,
+  storedKeyIdFor?: (
+    table: CompiledClientTable,
+    rowId: string,
+  ) => string | undefined,
 ): Promise<PushCommitFrame> {
   const operations: PushOperation[] = [];
   for (const op of commit.operations) {
@@ -274,7 +279,13 @@ export async function encodeOutboxCommit(
     if (encryption !== undefined && table.hasEncryptedColumns) {
       // Lazy: opt-in E2EE never enters an encryption-free app's bundle.
       const { encryptRowValues } = await import('./encryption');
-      values = await encryptRowValues(encryption, table, op.rowId, values);
+      values = await encryptRowValues(
+        encryption,
+        table,
+        op.rowId,
+        values,
+        storedKeyIdFor?.(table, op.rowId),
+      );
     }
     operations.push({
       table: op.table,