@syncular/client 0.15.8 → 0.15.9

package/dist/encryption.d.ts

@@ -20,14 +20,31 @@ import type { CompiledClientTable } from './schema.js';
 export interface EncryptionConfig {
     /** `keyId → 32-byte key`, or `undefined` if unknown (decrypt fails loud). */
     readonly keyProvider: (keyId: string) => Uint8Array | undefined;
-    /** Choose the key-id for an encrypt. Default: per-table (`table`). */
-    readonly keyIdFor?: (table: string, rowId: string) => string;
+    /**
+     * Choose the key-id for an encrypt. The plaintext positional row is supplied
+     * so direct clients can select a Facility/workspace/key-grant key without
+     * deriving privacy-sensitive state from an opaque row id. Default: the
+     * configured `keyIdColumns[table]`, then the table name.
+     */
+    readonly keyIdFor?: (table: string, rowId: string, values: readonly RowValue[]) => string;
+    /**
+     * Portable declarative selector used by Worker/Tauri hosts. Each value names
+     * a non-encrypted string column whose row value is the active key id.
+     */
+    readonly keyIdColumns?: Readonly<Record<string, string>>;
     /**
      * Nonce source (§5.11). Production omits this (secure RNG). ONLY the crypto
      * golden-vector generator injects a fixed nonce — never a production path.
      */
     readonly nonceSource?: NonceSource;
 }
+/** Structured-clone/JSON-safe keyring accepted by Worker and Tauri hosts. */
+export interface EncryptionKeyringConfig {
+    readonly keys: Readonly<Record<string, Uint8Array>>;
+    readonly keyIdColumns?: Readonly<Record<string, string>>;
+}
+/** Convert a portable keyring into the direct-client encryption contract. */
+export declare function encryptionConfigFromKeyring(keyring: EncryptionKeyringConfig): EncryptionConfig;
 /**
  * Encrypt the encrypted columns of a positional row value array in place-safe
  * fashion (returns a new array). Called at the outbox encode-at-send seam

package/dist/encryption.js

@@ -9,6 +9,39 @@
  * envelope primitives.
  */
 import { DecryptError, decryptValue, encryptValue, } from '@syncular/core';
+/** Convert a portable keyring into the direct-client encryption contract. */
+export function encryptionConfigFromKeyring(keyring) {
+    return {
+        keyProvider: (keyId) => keyring.keys[keyId],
+        ...(keyring.keyIdColumns !== undefined
+            ? { keyIdColumns: keyring.keyIdColumns }
+            : {}),
+    };
+}
+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)}`);
+        }
+        return selected;
+    }
+    const selectorColumn = config.keyIdColumns?.[table.name];
+    if (selectorColumn === undefined)
+        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)}`);
+    }
+    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`);
+    }
+    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`);
+    }
+    return selected;
+}
 function declaredTypeOf(column) {
     // An encrypted column always carries declaredType (typegen guarantees it;
     // §5.11). Fall back to the wire type defensively.
@@ -24,8 +57,8 @@ function declaredTypeOf(column) {
 export async function encryptRowValues(config, table, rowId, values) {
     if (!table.hasEncryptedColumns)
         return values.slice();
-    const keyIdFor = config.keyIdFor ?? ((t) => t);
     const out = values.slice();
+    const keyId = encryptionKeyId(config, table, rowId, values);
     for (let i = 0; i < table.columns.length; i++) {
         const column = table.columns[i];
         if (column === undefined || !column.encrypted)
@@ -33,7 +66,6 @@ export async function encryptRowValues(config, table, rowId, values) {
         const value = out[i];
         if (value === null || value === undefined)
             continue; // NULL stays NULL
-        const keyId = keyIdFor(table.name, rowId);
         const key = config.keyProvider(keyId);
         if (key === undefined) {
             throw new DecryptError(`no encryption key for keyId ${JSON.stringify(keyId)} (table ${table.name})`);

package/dist/schema.js

@@ -104,9 +104,6 @@ export function compileClientSchema(schema) {
                 if (localColumnType(column) !== 'string') {
                     throw new Error(`table ${table.name}: FTS projection ${JSON.stringify(index.name)} column ${JSON.stringify(columnName)} must have string type`);
                 }
-                if (column.encrypted === true) {
-                    throw new Error(`table ${table.name}: FTS projection ${JSON.stringify(index.name)} cannot index encrypted column ${JSON.stringify(columnName)}`);
-                }
             }
             if (!ALLOWED_FTS_TOKENIZERS.has(index.tokenize)) {
                 throw new Error(`table ${table.name}: FTS projection ${JSON.stringify(index.name)} tokenizer ${JSON.stringify(index.tokenize)} is not allowlisted`);

package/dist/worker-entry.js

@@ -14,6 +14,7 @@
  * the core owns exactly one loop.
  */
 import { SyncClient } from './client.js';
+import { encryptionConfigFromKeyring } from './encryption.js';
 import { ClientSyncError } from './errors.js';
 import { httpBlobTransport, httpSegmentDownloader, httpSyncTransport, webSocketRealtimeConnector, } from './http.js';
 import { openPersistentWasmDatabase } from './wasm-database.js';
@@ -216,6 +217,9 @@ export function startSyncWorker(overrides = {}) {
             },
             ...(config.clientId !== undefined ? { clientId: config.clientId } : {}),
             ...(config.limits !== undefined ? { limits: config.limits } : {}),
+            ...(config.encryption !== undefined
+                ? { encryption: encryptionConfigFromKeyring(config.encryption) }
+                : {}),
             onSyncNeeded: (reason) => {
                 post({ t: 'event', event: { kind: 'sync-needed', reason } });
                 consumeSyncIntent({ kind: 'interactive' });

package/dist/worker-host.d.ts

@@ -25,6 +25,7 @@ import type { WakeReason } from '@syncular/core';
 import type { BlobRef, CachedBlob } from './blob.js';
 import type { ConflictRecord, LeaseState, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, SchemaFloor, SubscribeInput, SyncClientLimits, SyncSummary, WindowState } from './client.js';
 import type { SqlRow, SqlValue } from './database.js';
+import type { EncryptionKeyringConfig } from './encryption.js';
 import { ChangeEmitter, type ClientChangeListener, InvalidationEmitter, type InvalidationListener, type LocalRevision, type SyncStatusSnapshot } from './invalidation.js';
 import { type LeaderLease, type LeaderLock } from './leader-lock.js';
 import { type CrossTabChannel, FollowerLink, LeaderBridge } from './multi-tab.js';
@@ -46,6 +47,8 @@ export interface SyncClientHandleConfig {
     readonly schema: ClientSchema;
     readonly database: WorkerDatabaseInit;
     readonly endpoints: WorkerEndpoints;
+    /** Structured-clone-safe E2EE keyring installed only in the leader worker. */
+    readonly encryption?: EncryptionKeyringConfig;
     readonly clientId?: string;
     readonly limits?: SyncClientLimits;
     /** Worker-side host loop (§8.4); default true. */

package/dist/worker-host.js

@@ -367,6 +367,9 @@ function buildInitConfig(config) {
         schema: config.schema,
         database: config.database,
         endpoints: config.endpoints,
+        ...(config.encryption !== undefined
+            ? { encryption: config.encryption }
+            : {}),
         ...(config.clientId !== undefined ? { clientId: config.clientId } : {}),
         ...(config.limits !== undefined ? { limits: config.limits } : {}),
         ...(config.autoSync !== undefined ? { autoSync: config.autoSync } : {}),

package/dist/worker-protocol.d.ts

@@ -20,6 +20,7 @@ import type { WakeReason } from '@syncular/core';
 import type { BlobRef, CachedBlob } from './blob.js';
 import type { ConflictRecord, LeaseState, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, SchemaFloor, SubscribeInput, SyncClientLimits, SyncSummary, WindowState } from './client.js';
 import type { SqlRow, SqlValue } from './database.js';
+import type { EncryptionKeyringConfig } from './encryption.js';
 import type { ClientChangeBatch, LocalRevision, SyncStatusSnapshot } from './invalidation.js';
 import type { OutboxCommit } from './outbox.js';
 import type { CommitOutcome, CommitOutcomeQuery, ResolveCommitOutcomeInput } from './outcomes.js';
@@ -61,6 +62,8 @@ export interface WorkerInitConfig {
     readonly schema: ClientSchema;
     readonly database: WorkerDatabaseInit;
     readonly endpoints: WorkerEndpoints;
+    /** Portable raw keyring installed inside the worker-owned client core. */
+    readonly encryption?: EncryptionKeyringConfig;
     readonly clientId?: string;
     readonly limits?: SyncClientLimits;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.15.8",
+  "version": "0.15.9",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -81,7 +81,7 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.15.8"
+    "@syncular/core": "0.15.9"
   },
   "peerDependencies": {
     "better-sqlite3": ">=11"
@@ -92,7 +92,7 @@
     }
   },
   "devDependencies": {
-    "@syncular/server": "0.15.8",
+    "@syncular/server": "0.15.9",
     "@types/better-sqlite3": "^7.6.13",
     "better-sqlite3": "^12.11.1"
   }

package/src/encryption.ts

@@ -30,8 +30,22 @@ import type { CompiledClientTable } from './schema';
 export interface EncryptionConfig {
   /** `keyId → 32-byte key`, or `undefined` if unknown (decrypt fails loud). */
   readonly keyProvider: (keyId: string) => Uint8Array | undefined;
-  /** Choose the key-id for an encrypt. Default: per-table (`table`). */
-  readonly keyIdFor?: (table: string, rowId: string) => string;
+  /**
+   * Choose the key-id for an encrypt. The plaintext positional row is supplied
+   * so direct clients can select a Facility/workspace/key-grant key without
+   * deriving privacy-sensitive state from an opaque row id. Default: the
+   * configured `keyIdColumns[table]`, then the table name.
+   */
+  readonly keyIdFor?: (
+    table: string,
+    rowId: string,
+    values: readonly RowValue[],
+  ) => string;
+  /**
+   * Portable declarative selector used by Worker/Tauri hosts. Each value names
+   * a non-encrypted string column whose row value is the active key id.
+   */
+  readonly keyIdColumns?: Readonly<Record<string, string>>;
   /**
    * Nonce source (§5.11). Production omits this (secure RNG). ONLY the crypto
    * golden-vector generator injects a fixed nonce — never a production path.
@@ -39,6 +53,63 @@ export interface EncryptionConfig {
   readonly nonceSource?: NonceSource;
 }
 
+/** Structured-clone/JSON-safe keyring accepted by Worker and Tauri hosts. */
+export interface EncryptionKeyringConfig {
+  readonly keys: Readonly<Record<string, Uint8Array>>;
+  readonly keyIdColumns?: Readonly<Record<string, string>>;
+}
+
+/** Convert a portable keyring into the direct-client encryption contract. */
+export function encryptionConfigFromKeyring(
+  keyring: EncryptionKeyringConfig,
+): EncryptionConfig {
+  return {
+    keyProvider: (keyId) => keyring.keys[keyId],
+    ...(keyring.keyIdColumns !== undefined
+      ? { keyIdColumns: keyring.keyIdColumns }
+      : {}),
+  };
+}
+
+function encryptionKeyId(
+  config: EncryptionConfig,
+  table: CompiledClientTable,
+  rowId: string,
+  values: readonly RowValue[],
+): string {
+  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)}`,
+      );
+    }
+    return selected;
+  }
+  const selectorColumn = config.keyIdColumns?.[table.name];
+  if (selectorColumn === undefined) 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)}`,
+    );
+  }
+  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`,
+    );
+  }
+  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`,
+    );
+  }
+  return selected;
+}
+
 function declaredTypeOf(column: RowColumn): DeclaredType {
   // An encrypted column always carries declaredType (typegen guarantees it;
   // §5.11). Fall back to the wire type defensively.
@@ -59,14 +130,13 @@ export async function encryptRowValues(
   values: readonly RowValue[],
 ): Promise<RowValue[]> {
   if (!table.hasEncryptedColumns) return values.slice();
-  const keyIdFor = config.keyIdFor ?? ((t: string) => t);
   const out = values.slice();
+  const keyId = encryptionKeyId(config, table, rowId, values);
   for (let i = 0; i < table.columns.length; i++) {
     const column = table.columns[i];
     if (column === undefined || !column.encrypted) continue;
     const value = out[i];
     if (value === null || value === undefined) continue; // NULL stays NULL
-    const keyId = keyIdFor(table.name, rowId);
     const key = config.keyProvider(keyId);
     if (key === undefined) {
       throw new DecryptError(

package/src/schema.ts

@@ -216,11 +216,6 @@ export function compileClientSchema(
             `table ${table.name}: FTS projection ${JSON.stringify(index.name)} column ${JSON.stringify(columnName)} must have string type`,
           );
         }
-        if (column.encrypted === true) {
-          throw new Error(
-            `table ${table.name}: FTS projection ${JSON.stringify(index.name)} cannot index encrypted column ${JSON.stringify(columnName)}`,
-          );
-        }
       }
       if (!ALLOWED_FTS_TOKENIZERS.has(index.tokenize)) {
         throw new Error(

package/src/worker-entry.ts

@@ -15,6 +15,7 @@
  */
 import { SyncClient } from './client';
 import type { ClientDatabase } from './database';
+import { encryptionConfigFromKeyring } from './encryption';
 import { ClientSyncError } from './errors';
 import {
   httpBlobTransport,
@@ -299,6 +300,9 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
       },
       ...(config.clientId !== undefined ? { clientId: config.clientId } : {}),
       ...(config.limits !== undefined ? { limits: config.limits } : {}),
+      ...(config.encryption !== undefined
+        ? { encryption: encryptionConfigFromKeyring(config.encryption) }
+        : {}),
       onSyncNeeded: (reason) => {
         post({ t: 'event', event: { kind: 'sync-needed', reason } });
         consumeSyncIntent({ kind: 'interactive' });

package/src/worker-host.ts

@@ -39,6 +39,7 @@ import type {
 } from './client';
 import type { SqlRow, SqlValue } from './database';
 import { registerDevtools } from './devtools';
+import type { EncryptionKeyringConfig } from './encryption';
 import { ClientSyncError } from './errors';
 import {
   ChangeEmitter,
@@ -100,6 +101,8 @@ export interface SyncClientHandleConfig {
   readonly schema: ClientSchema;
   readonly database: WorkerDatabaseInit;
   readonly endpoints: WorkerEndpoints;
+  /** Structured-clone-safe E2EE keyring installed only in the leader worker. */
+  readonly encryption?: EncryptionKeyringConfig;
   readonly clientId?: string;
   readonly limits?: SyncClientLimits;
   /** Worker-side host loop (§8.4); default true. */
@@ -624,6 +627,9 @@ function buildInitConfig(config: SyncClientHandleConfig): WorkerInitConfig {
     schema: config.schema,
     database: config.database,
     endpoints: config.endpoints,
+    ...(config.encryption !== undefined
+      ? { encryption: config.encryption }
+      : {}),
     ...(config.clientId !== undefined ? { clientId: config.clientId } : {}),
     ...(config.limits !== undefined ? { limits: config.limits } : {}),
     ...(config.autoSync !== undefined ? { autoSync: config.autoSync } : {}),

package/src/worker-protocol.ts

@@ -33,6 +33,7 @@ import type {
   WindowState,
 } from './client';
 import type { SqlRow, SqlValue } from './database';
+import type { EncryptionKeyringConfig } from './encryption';
 import type {
   ClientChangeBatch,
   LocalRevision,
@@ -96,6 +97,8 @@ export interface WorkerInitConfig {
   readonly schema: ClientSchema;
   readonly database: WorkerDatabaseInit;
   readonly endpoints: WorkerEndpoints;
+  /** Portable raw keyring installed inside the worker-owned client core. */
+  readonly encryption?: EncryptionKeyringConfig;
   readonly clientId?: string;
   readonly limits?: SyncClientLimits;
   /**