@syncular/client 0.72.1 → 0.73.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/apply.d.ts CHANGED
@@ -6,11 +6,11 @@ import { type OverlayScope } from './failed-overlay.js';
6
6
  */
7
7
  import { type CommitFrame, type RowsSegment, type RowValue, type ScopeMap } from '@syncular/core';
8
8
  import type { ClientDatabase } from './database.js';
9
- import type { EncryptionConfig } from './encryption.js';
9
+ import type { EncryptionConfig, SealedRow } from './encryption.js';
10
10
  import { type CompiledClientSchema, type CompiledClientTable, type JsonRowValue } from './schema.js';
11
11
  /** Lets the client wrap the physical write in its revision transaction. */
12
12
  export type ApplyTransaction = (fn: () => OverlayScope) => unknown;
13
- export declare function upsertLocalRow(db: ClientDatabase, table: CompiledClientTable, values: readonly RowValue[], syncVersion: number, serverWrite?: boolean): void;
13
+ export declare function upsertLocalRow(db: ClientDatabase, table: CompiledClientTable, values: readonly RowValue[], syncVersion: number, serverWrite?: boolean, sealed?: SealedRow): void;
14
14
  export declare function deleteLocalRow(db: ClientDatabase, table: CompiledClientTable, rowId: string, serverWrite?: boolean): void;
15
15
  /**
16
16
  * Apply one `COMMIT` frame in one local transaction (§1.4 rule 4) under the
package/dist/apply.js CHANGED
@@ -9,11 +9,14 @@ import { retainedBaseWrite, restoreFailedBases } from './failed-overlay.js';
9
9
  */
10
10
  import { decodeRow, } from '@syncular/core';
11
11
  import { ClientSyncError, invalidRequest } from './errors.js';
12
- import { quoteIdent, matchesLocalScopes, pkSqlValue, SYNC_VERSION_COLUMN, toSqlValue, rowValueToJson, } from './schema.js';
12
+ import { quoteIdent, matchesLocalScopes, pkSqlValue, SEALED_COLUMN, SEALED_KEY_COLUMN, SYNC_VERSION_COLUMN, toSqlValue, rowValueToJson, } from './schema.js';
13
13
  function upsertSql(table) {
14
14
  const names = [
15
15
  ...table.columns.map((column) => quoteIdent(column.name)),
16
16
  quoteIdent(SYNC_VERSION_COLUMN),
17
+ ...(table.hasEncryptedColumns
18
+ ? [quoteIdent(SEALED_KEY_COLUMN), quoteIdent(SEALED_COLUMN)]
19
+ : []),
17
20
  ];
18
21
  const placeholders = names.map(() => '?').join(', ');
19
22
  const updates = names
@@ -22,8 +25,14 @@ function upsertSql(table) {
22
25
  .join(', ');
23
26
  return `INSERT INTO ${quoteIdent(table.name)}(${names.join(', ')})VALUES(${placeholders})ON CONFLICT(${quoteIdent(table.primaryKey)})DO UPDATE SET ${updates}`;
24
27
  }
25
- export function upsertLocalRow(db, table, values, syncVersion, serverWrite = true) {
26
- db.exec(upsertSql(table), [...values.map(toSqlValue), syncVersion]);
28
+ export function upsertLocalRow(db, table, values, syncVersion, serverWrite = true, sealed) {
29
+ db.exec(upsertSql(table), [
30
+ ...values.map(toSqlValue),
31
+ syncVersion,
32
+ ...(table.hasEncryptedColumns
33
+ ? [sealed?.keyId ?? null, sealed?.envelopes ?? null]
34
+ : []),
35
+ ]);
27
36
  if (serverWrite)
28
37
  retainedBaseWrite(db, table, String(values[table.primaryKeyIndex]), Object.fromEntries(table.columns.map((column, index) => [
29
38
  column.name,
@@ -85,12 +94,17 @@ export async function applyCommitFrame(db, schema, frame, encryption, transactio
85
94
  if (change.row === undefined) {
86
95
  throw invalidRequest('upsert change without row payload');
87
96
  }
88
- let values = decodeRow(table.columns, change.row);
97
+ const values = decodeRow(table.columns, change.row);
89
98
  if (table.hasEncryptedColumns) {
90
- const { decryptRowValues } = await import('./encryption.js');
91
- values = await decryptRowValues(encryption, table, values);
99
+ const { decryptOrSealRowValues } = await import('./encryption.js');
100
+ resolved.push({
101
+ op: 'upsert',
102
+ table,
103
+ ...(await decryptOrSealRowValues(encryption, table, values)),
104
+ });
92
105
  }
93
- resolved.push({ op: 'upsert', table, values });
106
+ else
107
+ resolved.push({ op: 'upsert', table, values });
94
108
  }
95
109
  transaction(() => {
96
110
  // Exact keys name the rows this frame rebases; unique-key peers widen the
@@ -126,7 +140,7 @@ export async function applyCommitFrame(db, schema, frame, encryption, transactio
126
140
  if (change.op === 'delete')
127
141
  deleteLocalRow(db, change.table, rowId);
128
142
  else
129
- upsertLocalRow(db, change.table, change.values, rowVersion);
143
+ upsertLocalRow(db, change.table, change.values, rowVersion, true, change.sealed);
130
144
  }
131
145
  return rebaseScope(scope, kept, skipped);
132
146
  });
@@ -350,10 +364,10 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
350
364
  };
351
365
  let [boundary, where, params] = range(undefined, 1024);
352
366
  let applied = 0;
353
- // §5.3: the first chunk holds 1,024 rows. A later chunk holds at most
354
- // twice the rows of the one before, at most 65,536, and at most the rows
355
- // the one before applied per 100 ms from its start to its COMMIT; a
356
- // replaying chunk holds one statement.
367
+ // §5.3: the first chunk holds 1,024 rows. A later chunk holds at least
368
+ // 1,024 rows, at most twice the rows of the one before, at most 65,536,
369
+ // and at most the rows the one before applied per 250 ms from its start
370
+ // to its COMMIT; a replaying chunk holds one statement.
357
371
  for (let size = 1024;;) {
358
372
  if (options.isCurrent?.() === false)
359
373
  return applied;
@@ -409,7 +423,7 @@ export async function applySqliteSegment(db, schema, table, bytes, descriptor, o
409
423
  await yieldToHost();
410
424
  if (boundary === undefined || applied === count)
411
425
  break;
412
- size = Math.max(1, Math.min(2 * chunk, 65_536, Math.floor((chunk * 100) / duration)));
426
+ size = Math.max(1024, Math.min(2 * chunk, 65_536, Math.floor((chunk * 250) / duration)));
413
427
  [boundary, where, params] = range(boundary, Math.min(1024, size));
414
428
  }
415
429
  if (applied !== count)
@@ -440,13 +454,15 @@ export async function applyRowsSegment(db, schema, table, segment, options, encr
440
454
  // aborts before any write in this block.
441
455
  const rows = [];
442
456
  for (const row of block) {
443
- const values = table.hasEncryptedColumns
444
- ? await (async () => {
445
- const { decryptRowValues } = await import('./encryption.js');
446
- return decryptRowValues(encryption, table, row.values);
447
- })()
448
- : row.values;
449
- rows.push({ values, serverVersion: row.serverVersion });
457
+ if (table.hasEncryptedColumns) {
458
+ const { decryptOrSealRowValues } = await import('./encryption.js');
459
+ rows.push({
460
+ ...(await decryptOrSealRowValues(encryption, table, row.values)),
461
+ serverVersion: row.serverVersion,
462
+ });
463
+ }
464
+ else
465
+ rows.push(row);
450
466
  }
451
467
  if (options.isCurrent?.() === false)
452
468
  break;
@@ -474,7 +490,7 @@ export async function applyRowsSegment(db, schema, table, segment, options, encr
474
490
  for (const row of rows) {
475
491
  const rowId = String(row.values[table.primaryKeyIndex]);
476
492
  if (lands(db, table, rowId, row.serverVersion, kept, skipped))
477
- upsertLocalRow(db, table, row.values, row.serverVersion, protectedRows);
493
+ upsertLocalRow(db, table, row.values, row.serverVersion, protectedRows, row.sealed);
478
494
  applied += 1;
479
495
  if (applied % 1024 === 0)
480
496
  options.onProgress?.(applied);
package/dist/client.js CHANGED
@@ -29,7 +29,7 @@ import { decodeLocalDataRebootstrapReceipt, encodeLocalDataRebootstrapReceipt, }
29
29
  import { appendOutboxCommit, chainsOn, deleteOutboxCommit, encodeOutboxCommit, listOutbox, iterateOutbox, countOutbox, listOutboxBeforeImages, OutboxEncodeError, replaceOutboxBeforeImages, } from './outbox.js';
30
30
  import { activeFailureRecords, isStoredOperation, listCommitOutcomes, persistCommitOutcomeResolution, persistedCommitOutcome, pruneCommitOutcomes, commitOutcome as readCommitOutcome, recordCommitOutcome, scrubPurgedOutcomes, } from './outcomes.js';
31
31
  import { buildPreviousVersionAudit, capturePreviousVersion, clearPreviousVersionAudit, clearPreviousVersionRefusal, dropPreviousVersionContainer, loadLocalSchemaDescriptor, PREVIOUS_VERSION_CONTAINER_NAME, PREVIOUS_VERSION_MAX_LIMIT, readPreviousVersionContainer, readPreviousVersionRows, setLocalSchemaDescriptor, storedPreviousVersionAudit, storedPreviousVersionRefusal, withPreviousVersionContainer, writePreviousVersionAudit, writePreviousVersionRefusal, } from './previous-version.js';
32
- import { bytesToHex, compileClientSchema, hexToBytes, matchesLocalScopes, dropAndRecreateSyncedTables, ensureLocalBookkeepingSchema, ensureLocalSyncedSchema, fromSqlValue, coerceSqlRepresentation, localColumnType, jsonToRowValue, LOCAL_SCHEMA_VERSION_KEY, normalizeRecordKeys, OPTIMISTIC_VERSION, quoteIdent, recordToRowValues, rowValueToJson, SYNC_VERSION_COLUMN, stripSyncColumns, } from './schema.js';
32
+ import { bytesToHex, compileClientSchema, hexToBytes, matchesLocalScopes, dropAndRecreateSyncedTables, ensureLocalBookkeepingSchema, ensureLocalSyncedSchema, fromSqlValue, coerceSqlRepresentation, localColumnType, jsonToRowValue, LOCAL_SCHEMA_VERSION_KEY, normalizeRecordKeys, OPTIMISTIC_VERSION, quoteIdent, recordToRowValues, rowValueToJson, SEALED_COLUMN, SEALED_KEY_COLUMN, SYNC_VERSION_COLUMN, stripSyncColumns, toSqlValue, } from './schema.js';
33
33
  import { bootstrapping, bumpLocalRevision, covers, deleteUnit, ECHO_DIGEST_KEY, getLocalRevision, getMeta, getUnit, loadUnits, META_TABLE, owning, pairScopes, pruneUnknownUnits, REGISTERED_DIGEST_KEY, REPLICA_CURSOR_KEY, replicaCursor, resetUnits, saveUnit, saveUnitScopeSchema, setMeta, unitOwners, } from './state.js';
34
34
  import { deletePendingEviction, loadPendingEvictions, loadWindowUnits, savePendingEviction, windowBaseKey, windowRefs, WINDOWS_TABLE, windowUnitScopes, } from './window.js';
35
35
  /** Stable client-local error while protected operations are preflight-gated. */
@@ -813,6 +813,7 @@ export class SyncClient {
813
813
  this.#securityLifecycle = 'active';
814
814
  batch.status();
815
815
  });
816
+ await this.#serialize(() => this.#revealSealed());
816
817
  if (this.#hasStartupWork()) {
817
818
  this.#setSyncNeeded(true);
818
819
  this.#emitSyncNeeded('startup');
@@ -2331,6 +2332,16 @@ export class SyncClient {
2331
2332
  insert: insert ? true : undefined,
2332
2333
  });
2333
2334
  });
2335
+ // §5.11: a sealed row is read-only; a write could send NULL over
2336
+ // ciphertext this device cannot see.
2337
+ for (const operation of operations) {
2338
+ const table = this.#table(operation.table);
2339
+ if (!table.hasEncryptedColumns)
2340
+ continue;
2341
+ const keyId = this.#db.query(`SELECT ${quoteIdent(SEALED_KEY_COLUMN)} AS k FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [pkSqlValue(table, operation.rowId)])[0]?.k;
2342
+ if (typeof keyId === 'string')
2343
+ throw new ClientSyncError('client.encryption_key_missing', 'the row is sealed under a key this device does not hold', false, { table: table.name, keyId });
2344
+ }
2334
2345
  this.#applyBatch((batch) => {
2335
2346
  this.#db.transaction(() => {
2336
2347
  appendOutboxCommit(this.#db, clientCommitId, operations, this.#now(), this.#captureBeforeImages(operations));
@@ -2887,6 +2898,42 @@ export class SyncClient {
2887
2898
  sync() {
2888
2899
  return this.#sync();
2889
2900
  }
2901
+ /**
2902
+ * §5.11 reveal: under `missingKey: 'seal'`, decrypt every sealed row whose
2903
+ * envelope keys the keyring now holds and clear its reserved columns, one
2904
+ * revision per table.
2905
+ */
2906
+ async #revealSealed() {
2907
+ if (this.#encryption?.missingKey !== 'seal')
2908
+ return;
2909
+ const { decryptRowValues } = await import('./encryption.js');
2910
+ for (const table of this.#schema.tables.values()) {
2911
+ if (!table.hasEncryptedColumns)
2912
+ continue;
2913
+ const encrypted = table.columns.filter((column) => column.encrypted);
2914
+ const revealed = [];
2915
+ for (const row of this.#db.query(`SELECT ${quoteIdent(table.primaryKey)} AS id,${quoteIdent(SYNC_VERSION_COLUMN)} AS v,${quoteIdent(SEALED_COLUMN)} AS e FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(SEALED_KEY_COLUMN)} IS NOT NULL`)) {
2916
+ const stored = JSON.parse(String(row.e));
2917
+ const values = await decryptRowValues(this.#encryption, table, table.columns.map((column) => stored[column.name] ? new Uint8Array(stored[column.name]) : null)).catch((error) => {
2918
+ if (error.code !== 'client.encryption_key_missing')
2919
+ throw error;
2920
+ });
2921
+ if (values)
2922
+ revealed.push([
2923
+ ...table.columns.flatMap((column, i) => column.encrypted ? [toSqlValue(values[i] ?? null)] : []),
2924
+ row.id ?? null,
2925
+ row.v ?? null,
2926
+ ]);
2927
+ }
2928
+ if (revealed.length > 0)
2929
+ this.#applyBatch((batch) => {
2930
+ // A delivery since the read replaced the sealed state.
2931
+ for (const params of revealed)
2932
+ this.#db.exec(`UPDATE ${quoteIdent(table.name)} SET ${encrypted.map((column) => `${quoteIdent(column.name)}=?,`).join('')}${quoteIdent(SEALED_KEY_COLUMN)}=NULL,${quoteIdent(SEALED_COLUMN)}=NULL WHERE ${quoteIdent(table.primaryKey)}=? AND ${quoteIdent(SYNC_VERSION_COLUMN)}=? AND ${quoteIdent(SEALED_KEY_COLUMN)} IS NOT NULL`, params);
2933
+ batch.table(table.name);
2934
+ });
2935
+ }
2936
+ }
2890
2937
  /** `signal` is the `syncUntilIdle` deadline (§7.8); `sync()` has none. */
2891
2938
  #sync(signal) {
2892
2939
  this.#requireActive();
@@ -3022,6 +3069,7 @@ export class SyncClient {
3022
3069
  this.#setSyncNeeded(false);
3023
3070
  try {
3024
3071
  await this.#drainPendingEvictions();
3072
+ await this.#revealSealed();
3025
3073
  const logEpoch = getMeta(this.#db, LOG_EPOCH_META_KEY);
3026
3074
  // §7.4.4: encode the outbox with the CURRENT codec; a commit that
3027
3075
  // cannot express itself under the new schema (a dropped column/table)
@@ -32,6 +32,11 @@ export interface EncryptionConfig {
32
32
  * a non-encrypted string column whose row value is the active key id.
33
33
  */
34
34
  readonly keyIdColumns?: Readonly<Record<string, string>>;
35
+ /**
36
+ * §5.11 sealed apply. `'fail'` (default) fails a round on an envelope whose
37
+ * key the provider lacks; `'seal'` lands that row sealed and continues.
38
+ */
39
+ readonly missingKey?: 'fail' | 'seal';
35
40
  /**
36
41
  * Nonce source (§5.11). Production omits this (secure RNG). ONLY the crypto
37
42
  * golden-vector generator injects a fixed nonce — never a production path.
@@ -42,6 +47,7 @@ export interface EncryptionConfig {
42
47
  export interface EncryptionKeyringConfig {
43
48
  readonly keys: Readonly<Record<string, Uint8Array>>;
44
49
  readonly keyIdColumns?: Readonly<Record<string, string>>;
50
+ readonly missingKey?: 'fail' | 'seal';
45
51
  }
46
52
  /**
47
53
  * Convert a portable keyring into the direct-client encryption contract.
@@ -58,6 +64,22 @@ export declare function encryptionConfigFromKeyring(keyring: EncryptionKeyringCo
58
64
  * unencrypted (§5.11).
59
65
  */
60
66
  export declare function encryptRowValues<T extends RowValue | undefined>(config: EncryptionConfig | undefined, table: CompiledClientTable, rowId: string, values: readonly T[], storedKeyId?: string): Promise<T[]>;
67
+ /** §5.11 sealed state of a row: the `_sync_sealed_key` and `_sync_sealed` cells. */
68
+ export interface SealedRow {
69
+ readonly keyId: string;
70
+ /** JSON object of encrypted column name → envelope bytes. */
71
+ readonly envelopes: string;
72
+ }
73
+ /**
74
+ * The apply seam (§4.5 COMMIT, §5.6 rows segment): {@link decryptRowValues},
75
+ * except that under `missingKey: 'seal'` a missing key leaves every
76
+ * encrypted column NULL and `sealed` carries the first missing key id and
77
+ * the envelopes (§5.11).
78
+ */
79
+ export declare function decryptOrSealRowValues(config: EncryptionConfig | undefined, table: CompiledClientTable, values: readonly RowValue[]): Promise<{
80
+ values: RowValue[];
81
+ sealed?: SealedRow;
82
+ }>;
61
83
  /**
62
84
  * Decrypt the encrypted columns of a decoded positional row value array
63
85
  * (returns a new array). Called at the apply seam (§4.5 COMMIT, §5.6 rows
@@ -30,6 +30,9 @@ export function encryptionConfigFromKeyring(keyring) {
30
30
  ...(keyring.keyIdColumns !== undefined
31
31
  ? { keyIdColumns: keyring.keyIdColumns }
32
32
  : {}),
33
+ ...(keyring.missingKey !== undefined
34
+ ? { missingKey: keyring.missingKey }
35
+ : {}),
33
36
  };
34
37
  }
35
38
  function encryptionKeyId(config, table, rowId, values) {
@@ -118,6 +121,37 @@ export async function encryptRowValues(config, table, rowId, values, storedKeyId
118
121
  }
119
122
  return out;
120
123
  }
124
+ /**
125
+ * The apply seam (§4.5 COMMIT, §5.6 rows segment): {@link decryptRowValues},
126
+ * except that under `missingKey: 'seal'` a missing key leaves every
127
+ * encrypted column NULL and `sealed` carries the first missing key id and
128
+ * the envelopes (§5.11).
129
+ */
130
+ export async function decryptOrSealRowValues(config, table, values) {
131
+ try {
132
+ return { values: await decryptRowValues(config, table, values) };
133
+ }
134
+ catch (error) {
135
+ if (config?.missingKey !== 'seal' ||
136
+ !(error instanceof DecryptError) ||
137
+ error.code !== 'client.encryption_key_missing')
138
+ throw error;
139
+ // §5.11: every encrypted column is NULL; `_sync_sealed` keeps the
140
+ // envelopes as byte arrays for the reveal.
141
+ return {
142
+ values: values.map((value, i) => table.columns[i]?.encrypted ? null : value),
143
+ sealed: {
144
+ keyId: error.details.keyId,
145
+ envelopes: JSON.stringify(Object.fromEntries(table.columns.flatMap((column, i) => {
146
+ const value = values[i];
147
+ return column.encrypted && value instanceof Uint8Array
148
+ ? [[column.name, [...value]]]
149
+ : [];
150
+ }))),
151
+ },
152
+ };
153
+ }
154
+ }
121
155
  /**
122
156
  * Decrypt the encrypted columns of a decoded positional row value array
123
157
  * (returns a new array). Called at the apply seam (§4.5 COMMIT, §5.6 rows
@@ -454,7 +454,10 @@ class QueryEntry {
454
454
  this.#requestRead();
455
455
  }
456
456
  #publish(next) {
457
- if (next.rows === this.#state.rows &&
457
+ // A revision change alone publishes nothing, except the first answer:
458
+ // an empty answered read differs from an unread one by its revision.
459
+ if ((next.revision === undefined) === (this.#state.revision === undefined) &&
460
+ next.rows === this.#state.rows &&
458
461
  next.phase === this.#state.phase &&
459
462
  next.error === this.#state.error &&
460
463
  next.isRefreshing === this.#state.isRefreshing &&
package/dist/schema.d.ts CHANGED
@@ -82,6 +82,9 @@ export declare function compileClientSchema(schema: ClientSchema): CompiledClien
82
82
  * segment rows land with their real server version).
83
83
  */
84
84
  export declare const SYNC_VERSION_COLUMN = "_sync_version";
85
+ /** §5.11 sealed apply: the missing key id, and the envelopes kept for a reveal. */
86
+ export declare const SEALED_KEY_COLUMN = "_sync_sealed_key";
87
+ export declare const SEALED_COLUMN = "_sync_sealed";
85
88
  /** `_sync_version` for optimistic rows the server has never confirmed. */
86
89
  export declare const OPTIMISTIC_VERSION = -1;
87
90
  /**
package/dist/schema.js CHANGED
@@ -148,6 +148,9 @@ export function compileClientSchema(schema) {
148
148
  * segment rows land with their real server version).
149
149
  */
150
150
  export const SYNC_VERSION_COLUMN = '_sync_version';
151
+ /** §5.11 sealed apply: the missing key id, and the envelopes kept for a reveal. */
152
+ export const SEALED_KEY_COLUMN = '_sync_sealed_key';
153
+ export const SEALED_COLUMN = '_sync_sealed';
151
154
  /** `_sync_version` for optimistic rows the server has never confirmed. */
152
155
  export const OPTIMISTIC_VERSION = -1;
153
156
  /**
@@ -243,13 +246,18 @@ function createSyncedTable(db, table) {
243
246
  // §6.11: a declared reference is deliberately NOT emitted here. Windowing
244
247
  // evicts a parent independently of its children, so local SQLite never
245
248
  // enforces a reference; the server enforces it.
249
+ // §5.11: a sealed row holds NULL in every encrypted column.
246
250
  const columns = table.columns.map((column) => {
247
- const notNull = column.nullable ? '' : ' NOT NULL';
251
+ const notNull = column.nullable || column.encrypted ? '' : ' NOT NULL';
248
252
  const pk = column.name === table.primaryKey ? ' PRIMARY KEY' : '';
249
253
  return `${quoteIdent(column.name)} ${sqlType(column)}${notNull}${pk}`;
250
254
  });
251
255
  columns.push(`${quoteIdent(SYNC_VERSION_COLUMN)} INTEGER NOT NULL DEFAULT 0`);
256
+ if (table.hasEncryptedColumns)
257
+ columns.push(`${quoteIdent(SEALED_KEY_COLUMN)} TEXT`, `${quoteIdent(SEALED_COLUMN)} TEXT`);
252
258
  db.exec(`CREATE TABLE IF NOT EXISTS ${quoteIdent(table.name)}(${columns.join(', ')})`);
259
+ if (table.hasEncryptedColumns)
260
+ db.exec(`CREATE INDEX IF NOT EXISTS ${quoteIdent(`_syncular_sealed_${table.name}`)} ON ${quoteIdent(table.name)}(${quoteIdent(SEALED_KEY_COLUMN)}) WHERE ${quoteIdent(SEALED_KEY_COLUMN)} IS NOT NULL`);
253
261
  // Local secondary indexes (CREATE INDEX subset). Created here so both the
254
262
  // initial ensureLocalSchema and the §7.4.3 drop-and-recreate reset path
255
263
  // materialize them. IF NOT EXISTS keeps it idempotent; the DROP TABLE in the
@@ -383,6 +391,25 @@ function createFtsProjection(db, table, index) {
383
391
  export function ensureLocalSyncedSchema(db, schema) {
384
392
  db.transaction(() => {
385
393
  for (const table of schema.tables.values()) {
394
+ // §5.11: rebuild a table created before sealed apply (NOT NULL
395
+ // encrypted columns, no reserved columns), keeping its rows.
396
+ const info = table.hasEncryptedColumns
397
+ ? db.query(`PRAGMA table_info(${quoteIdent(table.name)})`)
398
+ : [];
399
+ if (info.length > 0 &&
400
+ !info.some((column) => column.name === SEALED_KEY_COLUMN)) {
401
+ const old = quoteIdent('_syncular_rebuild');
402
+ db.exec(`ALTER TABLE ${quoteIdent(table.name)} RENAME TO ${old}`);
403
+ for (const index of db.query("SELECT name FROM sqlite_master WHERE type='index' AND tbl_name='_syncular_rebuild' AND sql IS NOT NULL"))
404
+ db.exec(`DROP INDEX ${quoteIdent(String(index.name))}`);
405
+ createSyncedTable(db, table);
406
+ const names = [
407
+ ...table.columns.map((column) => quoteIdent(column.name)),
408
+ quoteIdent(SYNC_VERSION_COLUMN),
409
+ ].join(', ');
410
+ db.exec(`INSERT INTO ${quoteIdent(table.name)}(${names})SELECT ${names} FROM ${old}`);
411
+ db.exec(`DROP TABLE ${old}`);
412
+ }
386
413
  createSyncedTable(db, table);
387
414
  }
388
415
  for (const table of schema.tables.values()) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/client",
3
- "version": "0.72.1",
3
+ "version": "0.73.0",
4
4
  "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
5
5
  "license": "Apache-2.0",
6
6
  "author": "Benjamin Kniffler",
@@ -121,11 +121,11 @@
121
121
  },
122
122
  "dependencies": {
123
123
  "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
124
- "@syncular/core": "0.72.1"
124
+ "@syncular/core": "0.73.0"
125
125
  },
126
126
  "devDependencies": {
127
127
  "@electric-sql/pglite": "^0.5.4",
128
- "@syncular/server": "0.72.1",
128
+ "@syncular/server": "0.73.0",
129
129
  "playwright": "1.63.0",
130
130
  "vite": "8.3.4"
131
131
  }
package/src/apply.ts CHANGED
@@ -23,7 +23,7 @@ import {
23
23
  type SegmentRow,
24
24
  } from '@syncular/core';
25
25
  import type { ClientDatabase, SqlValue } from './database';
26
- import type { EncryptionConfig } from './encryption';
26
+ import type { EncryptionConfig, SealedRow } from './encryption';
27
27
  import { ClientSyncError, invalidRequest } from './errors';
28
28
  import {
29
29
  type CompiledClientSchema,
@@ -32,6 +32,8 @@ import {
32
32
  matchesLocalScopes,
33
33
  type JsonRowValue,
34
34
  pkSqlValue,
35
+ SEALED_COLUMN,
36
+ SEALED_KEY_COLUMN,
35
37
  SYNC_VERSION_COLUMN,
36
38
  toSqlValue,
37
39
  rowValueToJson,
@@ -44,6 +46,9 @@ function upsertSql(table: CompiledClientTable): string {
44
46
  const names = [
45
47
  ...table.columns.map((column) => quoteIdent(column.name)),
46
48
  quoteIdent(SYNC_VERSION_COLUMN),
49
+ ...(table.hasEncryptedColumns
50
+ ? [quoteIdent(SEALED_KEY_COLUMN), quoteIdent(SEALED_COLUMN)]
51
+ : []),
47
52
  ];
48
53
  const placeholders = names.map(() => '?').join(', ');
49
54
  const updates = names
@@ -59,8 +64,15 @@ export function upsertLocalRow(
59
64
  values: readonly RowValue[],
60
65
  syncVersion: number,
61
66
  serverWrite = true,
67
+ sealed?: SealedRow,
62
68
  ): void {
63
- db.exec(upsertSql(table), [...values.map(toSqlValue), syncVersion]);
69
+ db.exec(upsertSql(table), [
70
+ ...values.map(toSqlValue),
71
+ syncVersion,
72
+ ...(table.hasEncryptedColumns
73
+ ? [sealed?.keyId ?? null, sealed?.envelopes ?? null]
74
+ : []),
75
+ ]);
64
76
  if (serverWrite)
65
77
  retainedBaseWrite(
66
78
  db,
@@ -144,7 +156,12 @@ export async function applyCommitFrame(
144
156
  ): Promise<void> {
145
157
  type Resolved =
146
158
  | { op: 'delete'; table: CompiledClientTable }
147
- | { op: 'upsert'; table: CompiledClientTable; values: readonly RowValue[] };
159
+ | {
160
+ op: 'upsert';
161
+ table: CompiledClientTable;
162
+ values: readonly RowValue[];
163
+ sealed?: SealedRow | undefined;
164
+ };
148
165
  const resolved: Resolved[] = [];
149
166
  for (const change of frame.changes) {
150
167
  const tableName = frame.tables[change.tableIndex];
@@ -167,12 +184,15 @@ export async function applyCommitFrame(
167
184
  if (change.row === undefined) {
168
185
  throw invalidRequest('upsert change without row payload');
169
186
  }
170
- let values = decodeRow(table.columns, change.row);
187
+ const values = decodeRow(table.columns, change.row);
171
188
  if (table.hasEncryptedColumns) {
172
- const { decryptRowValues } = await import('./encryption');
173
- values = await decryptRowValues(encryption, table, values);
174
- }
175
- resolved.push({ op: 'upsert', table, values });
189
+ const { decryptOrSealRowValues } = await import('./encryption');
190
+ resolved.push({
191
+ op: 'upsert',
192
+ table,
193
+ ...(await decryptOrSealRowValues(encryption, table, values)),
194
+ });
195
+ } else resolved.push({ op: 'upsert', table, values });
176
196
  }
177
197
  transaction(() => {
178
198
  // Exact keys name the rows this frame rebases; unique-key peers widen the
@@ -218,7 +238,15 @@ export async function applyCommitFrame(
218
238
  );
219
239
  if (!land) continue;
220
240
  if (change.op === 'delete') deleteLocalRow(db, change.table, rowId);
221
- else upsertLocalRow(db, change.table, change.values, rowVersion);
241
+ else
242
+ upsertLocalRow(
243
+ db,
244
+ change.table,
245
+ change.values,
246
+ rowVersion,
247
+ true,
248
+ change.sealed,
249
+ );
222
250
  }
223
251
  return rebaseScope(scope, kept, skipped);
224
252
  });
@@ -588,10 +616,10 @@ export async function applySqliteSegment(
588
616
  };
589
617
  let [boundary, where, params] = range(undefined, 1024);
590
618
  let applied = 0;
591
- // §5.3: the first chunk holds 1,024 rows. A later chunk holds at most
592
- // twice the rows of the one before, at most 65,536, and at most the rows
593
- // the one before applied per 100 ms from its start to its COMMIT; a
594
- // replaying chunk holds one statement.
619
+ // §5.3: the first chunk holds 1,024 rows. A later chunk holds at least
620
+ // 1,024 rows, at most twice the rows of the one before, at most 65,536,
621
+ // and at most the rows the one before applied per 250 ms from its start
622
+ // to its COMMIT; a replaying chunk holds one statement.
595
623
  for (let size = 1024; ;) {
596
624
  if (options.isCurrent?.() === false) return applied;
597
625
  const started = now();
@@ -679,8 +707,8 @@ export async function applySqliteSegment(
679
707
  await yieldToHost();
680
708
  if (boundary === undefined || applied === count) break;
681
709
  size = Math.max(
682
- 1,
683
- Math.min(2 * chunk, 65_536, Math.floor((chunk * 100) / duration)),
710
+ 1024,
711
+ Math.min(2 * chunk, 65_536, Math.floor((chunk * 250) / duration)),
684
712
  );
685
713
  [boundary, where, params] = range(boundary, Math.min(1024, size));
686
714
  }
@@ -727,15 +755,19 @@ export async function applyRowsSegment(
727
755
  // §5.11: decrypt this block's rows before opening the sync transaction
728
756
  // (WebCrypto is async; the SQLite transaction is not). Decrypt failure
729
757
  // aborts before any write in this block.
730
- const rows: { values: readonly RowValue[]; serverVersion: number }[] = [];
758
+ const rows: {
759
+ values: readonly RowValue[];
760
+ serverVersion: number;
761
+ sealed?: SealedRow | undefined;
762
+ }[] = [];
731
763
  for (const row of block) {
732
- const values = table.hasEncryptedColumns
733
- ? await (async () => {
734
- const { decryptRowValues } = await import('./encryption');
735
- return decryptRowValues(encryption, table, row.values);
736
- })()
737
- : row.values;
738
- rows.push({ values, serverVersion: row.serverVersion });
764
+ if (table.hasEncryptedColumns) {
765
+ const { decryptOrSealRowValues } = await import('./encryption');
766
+ rows.push({
767
+ ...(await decryptOrSealRowValues(encryption, table, row.values)),
768
+ serverVersion: row.serverVersion,
769
+ });
770
+ } else rows.push(row);
739
771
  }
740
772
  if (options.isCurrent?.() === false) break;
741
773
  const clearThisBlock = first && options.clearFirst;
@@ -769,6 +801,7 @@ export async function applyRowsSegment(
769
801
  row.values,
770
802
  row.serverVersion,
771
803
  protectedRows,
804
+ row.sealed,
772
805
  );
773
806
  applied += 1;
774
807
  if (applied % 1024 === 0) options.onProgress?.(applied);
package/src/client.ts CHANGED
@@ -239,8 +239,11 @@ import {
239
239
  quoteIdent,
240
240
  recordToRowValues,
241
241
  rowValueToJson,
242
+ SEALED_COLUMN,
243
+ SEALED_KEY_COLUMN,
242
244
  SYNC_VERSION_COLUMN,
243
245
  stripSyncColumns,
246
+ toSqlValue,
244
247
  } from './schema';
245
248
  import {
246
249
  bootstrapping,
@@ -1689,6 +1692,7 @@ export class SyncClient {
1689
1692
  this.#securityLifecycle = 'active';
1690
1693
  batch.status();
1691
1694
  });
1695
+ await this.#serialize(() => this.#revealSealed());
1692
1696
  if (this.#hasStartupWork()) {
1693
1697
  this.#setSyncNeeded(true);
1694
1698
  this.#emitSyncNeeded('startup');
@@ -3561,6 +3565,23 @@ export class SyncClient {
3561
3565
  insert: insert ? true : undefined,
3562
3566
  });
3563
3567
  });
3568
+ // §5.11: a sealed row is read-only; a write could send NULL over
3569
+ // ciphertext this device cannot see.
3570
+ for (const operation of operations) {
3571
+ const table = this.#table(operation.table);
3572
+ if (!table.hasEncryptedColumns) continue;
3573
+ const keyId = this.#db.query(
3574
+ `SELECT ${quoteIdent(SEALED_KEY_COLUMN)} AS k FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`,
3575
+ [pkSqlValue(table, operation.rowId)],
3576
+ )[0]?.k;
3577
+ if (typeof keyId === 'string')
3578
+ throw new ClientSyncError(
3579
+ 'client.encryption_key_missing',
3580
+ 'the row is sealed under a key this device does not hold',
3581
+ false,
3582
+ { table: table.name, keyId },
3583
+ );
3584
+ }
3564
3585
  this.#applyBatch((batch) => {
3565
3586
  this.#db.transaction(() => {
3566
3587
  appendOutboxCommit(
@@ -4269,6 +4290,53 @@ export class SyncClient {
4269
4290
  return this.#sync();
4270
4291
  }
4271
4292
 
4293
+ /**
4294
+ * §5.11 reveal: under `missingKey: 'seal'`, decrypt every sealed row whose
4295
+ * envelope keys the keyring now holds and clear its reserved columns, one
4296
+ * revision per table.
4297
+ */
4298
+ async #revealSealed(): Promise<void> {
4299
+ if (this.#encryption?.missingKey !== 'seal') return;
4300
+ const { decryptRowValues } = await import('./encryption');
4301
+ for (const table of this.#schema.tables.values()) {
4302
+ if (!table.hasEncryptedColumns) continue;
4303
+ const encrypted = table.columns.filter((column) => column.encrypted);
4304
+ const revealed: SqlValue[][] = [];
4305
+ for (const row of this.#db.query(
4306
+ `SELECT ${quoteIdent(table.primaryKey)} AS id,${quoteIdent(SYNC_VERSION_COLUMN)} AS v,${quoteIdent(SEALED_COLUMN)} AS e FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(SEALED_KEY_COLUMN)} IS NOT NULL`,
4307
+ )) {
4308
+ const stored: Record<string, number[]> = JSON.parse(String(row.e));
4309
+ const values = await decryptRowValues(
4310
+ this.#encryption,
4311
+ table,
4312
+ table.columns.map((column) =>
4313
+ stored[column.name] ? new Uint8Array(stored[column.name]!) : null,
4314
+ ),
4315
+ ).catch((error: { code?: string }) => {
4316
+ if (error.code !== 'client.encryption_key_missing') throw error;
4317
+ });
4318
+ if (values)
4319
+ revealed.push([
4320
+ ...table.columns.flatMap((column, i) =>
4321
+ column.encrypted ? [toSqlValue(values[i] ?? null)] : [],
4322
+ ),
4323
+ row.id ?? null,
4324
+ row.v ?? null,
4325
+ ]);
4326
+ }
4327
+ if (revealed.length > 0)
4328
+ this.#applyBatch((batch) => {
4329
+ // A delivery since the read replaced the sealed state.
4330
+ for (const params of revealed)
4331
+ this.#db.exec(
4332
+ `UPDATE ${quoteIdent(table.name)} SET ${encrypted.map((column) => `${quoteIdent(column.name)}=?,`).join('')}${quoteIdent(SEALED_KEY_COLUMN)}=NULL,${quoteIdent(SEALED_COLUMN)}=NULL WHERE ${quoteIdent(table.primaryKey)}=? AND ${quoteIdent(SYNC_VERSION_COLUMN)}=? AND ${quoteIdent(SEALED_KEY_COLUMN)} IS NOT NULL`,
4333
+ params,
4334
+ );
4335
+ batch.table(table.name);
4336
+ });
4337
+ }
4338
+ }
4339
+
4272
4340
  /** `signal` is the `syncUntilIdle` deadline (§7.8); `sync()` has none. */
4273
4341
  #sync(signal?: AbortSignal): Promise<SyncSummary> {
4274
4342
  this.#requireActive();
@@ -4419,6 +4487,7 @@ export class SyncClient {
4419
4487
  this.#setSyncNeeded(false);
4420
4488
  try {
4421
4489
  await this.#drainPendingEvictions();
4490
+ await this.#revealSealed();
4422
4491
  const logEpoch = getMeta(this.#db, LOG_EPOCH_META_KEY);
4423
4492
  // §7.4.4: encode the outbox with the CURRENT codec; a commit that
4424
4493
  // cannot express itself under the new schema (a dropped column/table)
package/src/encryption.ts CHANGED
@@ -49,6 +49,11 @@ export interface EncryptionConfig {
49
49
  * a non-encrypted string column whose row value is the active key id.
50
50
  */
51
51
  readonly keyIdColumns?: Readonly<Record<string, string>>;
52
+ /**
53
+ * §5.11 sealed apply. `'fail'` (default) fails a round on an envelope whose
54
+ * key the provider lacks; `'seal'` lands that row sealed and continues.
55
+ */
56
+ readonly missingKey?: 'fail' | 'seal';
52
57
  /**
53
58
  * Nonce source (§5.11). Production omits this (secure RNG). ONLY the crypto
54
59
  * golden-vector generator injects a fixed nonce — never a production path.
@@ -60,6 +65,7 @@ export interface EncryptionConfig {
60
65
  export interface EncryptionKeyringConfig {
61
66
  readonly keys: Readonly<Record<string, Uint8Array>>;
62
67
  readonly keyIdColumns?: Readonly<Record<string, string>>;
68
+ readonly missingKey?: 'fail' | 'seal';
63
69
  }
64
70
 
65
71
  /**
@@ -87,6 +93,9 @@ export function encryptionConfigFromKeyring(
87
93
  ...(keyring.keyIdColumns !== undefined
88
94
  ? { keyIdColumns: keyring.keyIdColumns }
89
95
  : {}),
96
+ ...(keyring.missingKey !== undefined
97
+ ? { missingKey: keyring.missingKey }
98
+ : {}),
90
99
  };
91
100
  }
92
101
 
@@ -206,6 +215,56 @@ export async function encryptRowValues<T extends RowValue | undefined>(
206
215
  return out;
207
216
  }
208
217
 
218
+ /** §5.11 sealed state of a row: the `_sync_sealed_key` and `_sync_sealed` cells. */
219
+ export interface SealedRow {
220
+ readonly keyId: string;
221
+ /** JSON object of encrypted column name → envelope bytes. */
222
+ readonly envelopes: string;
223
+ }
224
+
225
+ /**
226
+ * The apply seam (§4.5 COMMIT, §5.6 rows segment): {@link decryptRowValues},
227
+ * except that under `missingKey: 'seal'` a missing key leaves every
228
+ * encrypted column NULL and `sealed` carries the first missing key id and
229
+ * the envelopes (§5.11).
230
+ */
231
+ export async function decryptOrSealRowValues(
232
+ config: EncryptionConfig | undefined,
233
+ table: CompiledClientTable,
234
+ values: readonly RowValue[],
235
+ ): Promise<{ values: RowValue[]; sealed?: SealedRow }> {
236
+ try {
237
+ return { values: await decryptRowValues(config, table, values) };
238
+ } catch (error) {
239
+ if (
240
+ config?.missingKey !== 'seal' ||
241
+ !(error instanceof DecryptError) ||
242
+ error.code !== 'client.encryption_key_missing'
243
+ )
244
+ throw error;
245
+ // §5.11: every encrypted column is NULL; `_sync_sealed` keeps the
246
+ // envelopes as byte arrays for the reveal.
247
+ return {
248
+ values: values.map((value, i) =>
249
+ table.columns[i]?.encrypted ? null : value,
250
+ ),
251
+ sealed: {
252
+ keyId: error.details!.keyId,
253
+ envelopes: JSON.stringify(
254
+ Object.fromEntries(
255
+ table.columns.flatMap((column, i) => {
256
+ const value = values[i];
257
+ return column.encrypted && value instanceof Uint8Array
258
+ ? [[column.name, [...value]]]
259
+ : [];
260
+ }),
261
+ ),
262
+ ),
263
+ },
264
+ };
265
+ }
266
+ }
267
+
209
268
  /**
210
269
  * Decrypt the encrypted columns of a decoded positional row value array
211
270
  * (returns a new array). Called at the apply seam (§4.5 COMMIT, §5.6 rows
@@ -601,7 +601,10 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
601
601
  }
602
602
 
603
603
  #publish(next: LiveQueryResult<Row>): void {
604
+ // A revision change alone publishes nothing, except the first answer:
605
+ // an empty answered read differs from an unread one by its revision.
604
606
  if (
607
+ (next.revision === undefined) === (this.#state.revision === undefined) &&
605
608
  next.rows === this.#state.rows &&
606
609
  next.phase === this.#state.phase &&
607
610
  next.error === this.#state.error &&
package/src/schema.ts CHANGED
@@ -262,6 +262,10 @@ export function compileClientSchema(
262
262
  */
263
263
  export const SYNC_VERSION_COLUMN = '_sync_version';
264
264
 
265
+ /** §5.11 sealed apply: the missing key id, and the envelopes kept for a reveal. */
266
+ export const SEALED_KEY_COLUMN = '_sync_sealed_key';
267
+ export const SEALED_COLUMN = '_sync_sealed';
268
+
265
269
  /** `_sync_version` for optimistic rows the server has never confirmed. */
266
270
  export const OPTIMISTIC_VERSION = -1;
267
271
 
@@ -376,15 +380,25 @@ function createSyncedTable(
376
380
  // §6.11: a declared reference is deliberately NOT emitted here. Windowing
377
381
  // evicts a parent independently of its children, so local SQLite never
378
382
  // enforces a reference; the server enforces it.
383
+ // §5.11: a sealed row holds NULL in every encrypted column.
379
384
  const columns = table.columns.map((column) => {
380
- const notNull = column.nullable ? '' : ' NOT NULL';
385
+ const notNull = column.nullable || column.encrypted ? '' : ' NOT NULL';
381
386
  const pk = column.name === table.primaryKey ? ' PRIMARY KEY' : '';
382
387
  return `${quoteIdent(column.name)} ${sqlType(column)}${notNull}${pk}`;
383
388
  });
384
389
  columns.push(`${quoteIdent(SYNC_VERSION_COLUMN)} INTEGER NOT NULL DEFAULT 0`);
390
+ if (table.hasEncryptedColumns)
391
+ columns.push(
392
+ `${quoteIdent(SEALED_KEY_COLUMN)} TEXT`,
393
+ `${quoteIdent(SEALED_COLUMN)} TEXT`,
394
+ );
385
395
  db.exec(
386
396
  `CREATE TABLE IF NOT EXISTS ${quoteIdent(table.name)}(${columns.join(', ')})`,
387
397
  );
398
+ if (table.hasEncryptedColumns)
399
+ db.exec(
400
+ `CREATE INDEX IF NOT EXISTS ${quoteIdent(`_syncular_sealed_${table.name}`)} ON ${quoteIdent(table.name)}(${quoteIdent(SEALED_KEY_COLUMN)}) WHERE ${quoteIdent(SEALED_KEY_COLUMN)} IS NOT NULL`,
401
+ );
388
402
  // Local secondary indexes (CREATE INDEX subset). Created here so both the
389
403
  // initial ensureLocalSchema and the §7.4.3 drop-and-recreate reset path
390
404
  // materialize them. IF NOT EXISTS keeps it idempotent; the DROP TABLE in the
@@ -561,6 +575,31 @@ export function ensureLocalSyncedSchema(
561
575
  ): void {
562
576
  db.transaction(() => {
563
577
  for (const table of schema.tables.values()) {
578
+ // §5.11: rebuild a table created before sealed apply (NOT NULL
579
+ // encrypted columns, no reserved columns), keeping its rows.
580
+ const info = table.hasEncryptedColumns
581
+ ? db.query(`PRAGMA table_info(${quoteIdent(table.name)})`)
582
+ : [];
583
+ if (
584
+ info.length > 0 &&
585
+ !info.some((column) => column.name === SEALED_KEY_COLUMN)
586
+ ) {
587
+ const old = quoteIdent('_syncular_rebuild');
588
+ db.exec(`ALTER TABLE ${quoteIdent(table.name)} RENAME TO ${old}`);
589
+ for (const index of db.query(
590
+ "SELECT name FROM sqlite_master WHERE type='index' AND tbl_name='_syncular_rebuild' AND sql IS NOT NULL",
591
+ ))
592
+ db.exec(`DROP INDEX ${quoteIdent(String(index.name))}`);
593
+ createSyncedTable(db, table);
594
+ const names = [
595
+ ...table.columns.map((column) => quoteIdent(column.name)),
596
+ quoteIdent(SYNC_VERSION_COLUMN),
597
+ ].join(', ');
598
+ db.exec(
599
+ `INSERT INTO ${quoteIdent(table.name)}(${names})SELECT ${names} FROM ${old}`,
600
+ );
601
+ db.exec(`DROP TABLE ${old}`);
602
+ }
564
603
  createSyncedTable(db, table);
565
604
  }
566
605
  for (const table of schema.tables.values()) {