@syncular/client 0.30.14 → 0.30.16

package/dist/worker-host.js

@@ -332,6 +332,11 @@ export class SyncClientHandle {
     query(sql, params) {
         return this.#call('query', [sql, params]);
     }
+    authoritySnapshot() {
+        if (arguments.length)
+            throw new ClientSyncError('client.authority_read_forbidden', 'authoritySnapshot accepts no arguments');
+        return this.#call('authoritySnapshot', []);
+    }
     querySnapshot(spec) {
         return this.#call('querySnapshot', [spec]);
     }
@@ -569,6 +574,9 @@ function buildInitConfig(config, headers = config.headers) {
         ...(config.transportEnabled !== undefined
             ? { transportEnabled: config.transportEnabled }
             : {}),
+        ...(config.authorityReads !== undefined
+            ? { authorityReads: config.authorityReads.declarations }
+            : {}),
         ...(config.securityPreflight !== undefined
             ? { securityPreflight: config.securityPreflight }
             : {}),

package/dist/worker-protocol.d.ts

@@ -77,6 +77,7 @@ export interface WorkerInitConfig {
     /** Portable raw keyring installed inside the worker-owned client core. */
     readonly encryption?: EncryptionKeyringConfig;
     /** Open the worker-owned replica behind the fail-closed security gate. */
+    readonly authorityReads?: readonly import('./authority.js').AuthorityReadDeclaration[];
     readonly securityPreflight?: boolean;
     readonly transportEnabled?: boolean;
     readonly clientId?: string;
@@ -138,6 +139,7 @@ export interface WorkerApi extends Omit<ClientSnapshotMethods, 'querySnapshot'>
     sync(): Promise<SyncSummary>;
     syncUntilIdle(maxRounds?: number): Promise<SyncSummary>;
     query(sql: string, params?: readonly SqlValue[]): SqlRow[];
+    authoritySnapshot(): import('./authority.js').AuthoritySnapshot;
     querySnapshot(spec: QueryReadSpec): QuerySnapshot;
     localRevision(): LocalRevision;
     pendingCommits(): OutboxCommit[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.30.14",
+  "version": "0.30.16",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -73,6 +73,14 @@
         "types": "./dist/worker-entry.d.ts",
         "default": "./dist/worker-entry.js"
       }
+    },
+    "./authority": {
+      "bun": "./src/authority.ts",
+      "browser": "./dist/authority.js",
+      "import": {
+        "types": "./dist/authority.d.ts",
+        "default": "./dist/authority.js"
+      }
     }
   },
   "files": [
@@ -89,10 +97,10 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.30.14"
+    "@syncular/core": "0.30.16"
   },
   "devDependencies": {
-    "@syncular/server": "0.30.14",
+    "@syncular/server": "0.30.16",
     "playwright": "1.63.0",
     "@electric-sql/pglite": "^0.5.4"
   }

package/src/authority.ts

@@ -0,0 +1,414 @@
+import type { ClientDatabase, SqlRow, SqlValue } from './database';
+import { ClientSyncError } from './errors';
+import { listOutbox, listOutboxBeforeImages } from './outbox';
+import { RETAINED_ROWS } from './failed-overlay';
+import { getLocalRevision, getMeta, loadSubscriptions } from './state';
+import { fromSqlValue, quoteIdent, SYNC_VERSION_COLUMN } from './schema';
+import type { CompiledClientSchema, JsonRowValue } from './schema';
+
+/** Frozen at client creation. Scope selectors use the schema's variables. */
+export interface AuthorityReadDeclaration {
+  readonly table: string;
+  readonly columns: readonly string[];
+  readonly scopes: Readonly<Record<string, readonly string[]>>;
+}
+export interface AuthoritySnapshot {
+  readonly revision: bigint;
+  readonly complete: boolean;
+  readonly tables: readonly {
+    readonly table: string;
+    readonly rows: readonly {
+      readonly values: SqlRow;
+      readonly version: number;
+      readonly hasLocalIntent: boolean;
+    }[];
+    /** Includes local-only creations; no intended values are disclosed. */
+    readonly localIntentRowIds: readonly string[];
+    readonly coverage: 'complete' | 'pending' | 'missing';
+    readonly scopes: AuthorityReadDeclaration['scopes'];
+    readonly persisted: readonly {
+      readonly requestedScopes: AuthorityReadDeclaration['scopes'];
+      readonly status: string;
+      readonly cursor: number;
+      readonly effectiveScopes: AuthorityReadDeclaration['scopes'] | null;
+      readonly complete: boolean;
+    }[];
+  }[];
+}
+
+function validateAuthorityReads(
+  schema: CompiledClientSchema,
+  declarations: readonly AuthorityReadDeclaration[],
+): void {
+  if (!Array.isArray(declarations))
+    throw new ClientSyncError(
+      'client.authority_read_forbidden',
+      'authorityReads must be a list',
+    );
+  const seen = new Set<string>();
+  for (const read of declarations) {
+    if (
+      !read ||
+      typeof read !== 'object' ||
+      !Array.isArray(read.columns) ||
+      !read.scopes ||
+      typeof read.scopes !== 'object' ||
+      Array.isArray(read.scopes)
+    )
+      throw new ClientSyncError(
+        'client.authority_read_forbidden',
+        'invalid authority declaration',
+      );
+    const table = schema.tables.get(read.table);
+    const plain = (name: string) =>
+      table?.columns.some(
+        (c) =>
+          c.name === name &&
+          name !== 'authority_version' &&
+          !name.startsWith('_sync') &&
+          !c.encrypted &&
+          ['string', 'integer', 'float', 'boolean', 'json'].includes(c.type),
+      );
+    if (
+      Object.keys(read).sort().join() !== 'columns,scopes,table' ||
+      !table ||
+      seen.has(read.table) ||
+      !read.columns.length ||
+      new Set(read.columns).size !== read.columns.length ||
+      !read.columns.includes(table.primaryKey) ||
+      !read.columns.every(plain) ||
+      !Object.keys(read.scopes).length ||
+      !Object.entries(read.scopes).every(
+        ([variable, values]) =>
+          read.columns.includes(
+            table.scopeColumnByVariable.get(variable) ?? '',
+          ) &&
+          plain(table.scopeColumnByVariable.get(variable) ?? '') &&
+          Array.isArray(values) &&
+          values.length > 0 &&
+          values.every(
+            (v) => typeof v === 'string' && v.length > 0 && v !== '*',
+          ),
+      )
+    ) {
+      throw new ClientSyncError(
+        'client.authority_read_forbidden',
+        'authority reads require declared tables, plain columns, a primary key and nonempty plain scope selectors',
+      );
+    }
+    Object.freeze(read.columns);
+    for (const values of Object.values(read.scopes)) Object.freeze(values);
+    Object.freeze(read.scopes);
+    Object.freeze(read);
+    seen.add(read.table);
+  }
+}
+
+/** Read accepted bases without restoring or replaying the visible projection. */
+function readAuthoritySnapshot(
+  db: ClientDatabase,
+  schema: CompiledClientSchema,
+  declarations: readonly AuthorityReadDeclaration[],
+): AuthoritySnapshot {
+  if (!declarations.length)
+    throw new ClientSyncError(
+      'client.authority_read_forbidden',
+      'no authority reads were declared at client creation',
+    );
+  return db.transaction(() => {
+    const raw = getMeta(db, 'localRevision');
+    if (
+      raw === undefined ||
+      !/^(0|[1-9][0-9]*)$/.test(raw) ||
+      BigInt(raw) > 18446744073709551615n
+    )
+      throw new ClientSyncError(
+        'sync.local_corrupt',
+        'authority revision is missing or invalid',
+      );
+    const revision = getLocalRevision(db);
+    const subscriptions = loadSubscriptions(db);
+    const tables = declarations.map((read) => {
+      const table = schema.tables.get(read.table)!;
+      const columns = [
+        ...new Set([
+          ...read.columns,
+          ...Object.keys(read.scopes).map((v) =>
+            table.scopeColumnByVariable.get(v)!,
+          ),
+        ]),
+      ];
+      const scalar = (
+        column: string,
+        value: SqlValue | JsonRowValue,
+      ): string => {
+        if (value === null || typeof value === 'object')
+          throw new ClientSyncError(
+            'sync.local_corrupt',
+            'authority scalar is missing or invalid',
+          );
+        return String(
+          fromSqlValue(table.columns[table.columnIndex.get(column)!]!, value),
+        );
+      };
+      const matches = (values: Record<string, SqlValue | JsonRowValue>) =>
+        Object.entries(read.scopes).every(([v, held]) => {
+          const column = table.scopeColumnByVariable.get(v)!;
+          return (
+            values[column] !== null &&
+            values[column] !== undefined &&
+            held.includes(scalar(column, values[column]!))
+          );
+        });
+      const bases = new Map<
+        string,
+        {
+          values: Record<string, JsonRowValue | SqlValue> | null;
+          version: number;
+        }
+      >();
+      const intent = new Set<string>();
+      const relevantIntent = new Set<string>();
+      // FIFO before-images precede the earliest still-pending intent.
+      for (const commit of listOutbox(db)) {
+        const images = listOutboxBeforeImages(db, commit.clientCommitId);
+        for (const [idx, op] of commit.operations.entries())
+          if (op.table === read.table) {
+            intent.add(op.rowId);
+            if (op.values && matches(op.values)) relevantIntent.add(op.rowId);
+            if (bases.has(op.rowId)) continue;
+            const image = images.find((i) => i.opIndex === idx);
+            if (
+              !image ||
+              (image.existed &&
+                (image.values === undefined || image.syncVersion === undefined))
+            )
+              throw new ClientSyncError(
+                'sync.local_corrupt',
+                'authority intent before-image is missing',
+              );
+            bases.set(op.rowId, {
+              values: image.values ?? null,
+              version: image.syncVersion ?? -1,
+            });
+          }
+      }
+      // A retained/ACK base precedes pending edits stacked over that intent.
+      const retained = new Set<string>();
+      for (const row of db.query(
+        `SELECT id,base,version,intent FROM ${RETAINED_ROWS} WHERE tbl=? ORDER BY commit_seq,at,commit_id,idx`,
+        [read.table],
+      )) {
+        const id = String(row.id);
+        if (row.base !== null && row.version === null)
+          throw new ClientSyncError(
+            'sync.local_corrupt',
+            'authority base version is missing',
+          );
+        intent.add(id);
+        if (row.intent !== null && matches(JSON.parse(String(row.intent))))
+          relevantIntent.add(id);
+        if (!retained.has(id))
+          bases.set(id, {
+            values: row.base === null ? null : JSON.parse(String(row.base)),
+            version: Number(row.version ?? -1),
+          });
+        retained.add(id);
+      }
+      const visible = db.query(
+        `SELECT ${columns.map(quoteIdent).join(',')},${SYNC_VERSION_COLUMN} FROM ${quoteIdent(read.table)}`,
+      );
+      for (const row of visible) {
+        const id = scalar(table.primaryKey, row[table.primaryKey]!);
+        if (!bases.has(id))
+          bases.set(id, {
+            values: row,
+            version: Number(row[SYNC_VERSION_COLUMN]),
+          });
+      }
+      const rows = [...bases]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .flatMap(([id, base]) => {
+          if (
+            !Number.isSafeInteger(base.version) ||
+            base.version < -1 ||
+            (base.values &&
+              base.version >= 0 &&
+              !read.columns.every((c) => Object.hasOwn(base.values!, c)))
+          )
+            throw new ClientSyncError(
+              'sync.local_corrupt',
+              'authority base evidence is incomplete',
+            );
+          if (!base.values || base.version < 0 || !matches(base.values))
+            return [];
+          return [
+            {
+              values: Object.fromEntries(
+                read.columns.map((c) => [
+                  c,
+                  typeof base.values![c] === 'boolean'
+                    ? base.values![c]
+                      ? 1
+                      : 0
+                    : (base.values![c] ?? null),
+                ]),
+              ) as SqlRow,
+              version: base.version,
+              hasLocalIntent: intent.has(id),
+            },
+          ];
+        });
+      const persisted = subscriptions
+        .filter((s) => s.table === read.table)
+        .map((s) => {
+          const effective = s.effectiveScopes;
+          const complete =
+            effective !== undefined &&
+            Object.keys(effective).length === Object.keys(read.scopes).length &&
+            s.status === 'active' &&
+            s.cursor >= 0 &&
+            s.bootstrapState === undefined &&
+            s.params === undefined;
+          return {
+            requestedScopes: Object.fromEntries(
+              Object.keys(read.scopes).map((v) => [v, s.scopes[v] ?? []]),
+            ),
+            status: s.status,
+            cursor: s.cursor,
+            effectiveScopes:
+              effective === undefined
+                ? null
+                : Object.fromEntries(
+                    Object.keys(read.scopes).map((v) => [
+                      v,
+                      effective[v] ?? [],
+                    ]),
+                  ),
+            complete,
+          };
+        });
+      const selectors = Object.entries(read.scopes);
+      const covered = (at: number, candidates: typeof persisted): boolean =>
+        at === selectors.length
+          ? candidates.length > 0
+          : selectors[at]![1].every((value) =>
+              covered(
+                at + 1,
+                candidates.filter((p) =>
+                  p.effectiveScopes?.[selectors[at]![0]]?.some(
+                    (held) => held === value || held === '*',
+                  ),
+                ),
+              ),
+            );
+      const coverage = covered(
+        0,
+        persisted.filter((p) => p.complete),
+      )
+        ? 'complete'
+        : persisted.some(
+              (p) =>
+                p.status === 'active' &&
+                selectors.every(([v, values]) =>
+                  values.some((value) => p.requestedScopes[v]?.includes(value)),
+                ),
+            )
+          ? 'pending'
+          : 'missing';
+      return {
+        table: read.table,
+        rows,
+        localIntentRowIds: [...intent]
+          .filter(
+            (id) =>
+              relevantIntent.has(id) ||
+              rows.some(
+                (row) =>
+                  scalar(table.primaryKey, row.values[table.primaryKey]!) ===
+                  id,
+              ) ||
+              visible.some(
+                (row) =>
+                  scalar(table.primaryKey, row[table.primaryKey]!) === id &&
+                  matches(row),
+              ),
+          )
+          .sort(),
+        scopes: read.scopes,
+        coverage,
+        persisted,
+      } as AuthoritySnapshot['tables'][number];
+    });
+    return {
+      revision,
+      complete: tables.every((t) => t.coverage === 'complete'),
+      tables,
+    };
+  });
+}
+
+/** Opt-in policy module; ordinary clients ship no authority reader. */
+export class AuthorityReadPolicy {
+  readonly #declarations: readonly AuthorityReadDeclaration[];
+  get declarations(): readonly AuthorityReadDeclaration[] {
+    return this.#declarations;
+  }
+  constructor(declarations: readonly AuthorityReadDeclaration[]) {
+    if (!Array.isArray(declarations))
+      throw new ClientSyncError(
+        'client.authority_read_forbidden',
+        'authorityReads must be a list',
+      );
+    this.#declarations = structuredClone(declarations);
+    for (const read of this.#declarations) {
+      if (
+        !read ||
+        typeof read !== 'object' ||
+        !Array.isArray(read.columns) ||
+        !read.scopes ||
+        typeof read.scopes !== 'object' ||
+        Array.isArray(read.scopes)
+      )
+        throw new ClientSyncError(
+          'client.authority_read_forbidden',
+          'invalid authority declaration',
+        );
+      Object.freeze(read.columns);
+      for (const values of Object.values(read.scopes)) Object.freeze(values);
+      Object.freeze(read.scopes);
+      Object.freeze(read);
+    }
+    Object.freeze(this.#declarations);
+    Object.freeze(this);
+  }
+  /** @internal */
+  validate(schema: CompiledClientSchema): void {
+    validateAuthorityReads(schema, this.declarations);
+    Object.freeze(this.declarations);
+    Object.freeze(this);
+  }
+  /** @internal */
+  snapshot(
+    db: ClientDatabase,
+    schema: CompiledClientSchema,
+  ): AuthoritySnapshot {
+    validateAuthorityReads(schema, this.declarations);
+    try {
+      return readAuthoritySnapshot(db, schema, this.declarations);
+    } catch (error) {
+      if (error instanceof SyntaxError)
+        throw new ClientSyncError(
+          'sync.local_corrupt',
+          'authority persisted evidence is invalid',
+        );
+      throw error;
+    }
+  }
+}
+/** Declare authority tables, plain columns and scope selectors at creation. */
+export function defineAuthorityReads(
+  declarations: readonly AuthorityReadDeclaration[],
+): AuthorityReadPolicy {
+  return new AuthorityReadPolicy(declarations);
+}

package/src/client.ts

@@ -1,4 +1,5 @@
 import { BLOB_COMMIT_REFS } from './blob';
+import type { AuthorityReadPolicy, AuthoritySnapshot } from './authority';
 import { hasUniqueIndex } from './schema';
 import { OUTCOMES_TABLE } from './outcomes';
 import { OUTBOX_TABLE } from './outbox';
@@ -424,6 +425,7 @@ export interface SyncClientConfig {
    * hosts must not materialize key bytes before their preflight has passed.
    */
   readonly securityPreflight?: boolean;
+  readonly authorityReads?: AuthorityReadPolicy;
   /**
    * RFC 0005 previous-version context. A feature flag, default off: when
    * absent or `enabled: false`, a schema bump behaves exactly as 0.22.0 did
@@ -746,6 +748,7 @@ export type ClientSnapshotReader = {
 
 export class SyncClient {
   readonly #config: SyncClientConfig;
+  readonly #authorityReads: AuthorityReadPolicy | undefined;
   readonly #db: ClientDatabase;
   readonly #schema: CompiledClientSchema;
   /** §5.11 client-side encryption config; undefined ⇒ E2EE off. */
@@ -860,6 +863,8 @@ export class SyncClient {
     this.#retainFailedCommits = config.retainFailedCommits === true;
     this.#db = config.database;
     this.#schema = compileClientSchema(config.schema);
+    this.#authorityReads = config.authorityReads;
+    this.#authorityReads?.validate(this.#schema);
     const realtimePolicy = config.realtimePolicy ?? 'optional';
     if (
       realtimePolicy !== 'required' &&
@@ -1232,6 +1237,7 @@ export class SyncClient {
   }
 
   async close(): Promise<void> {
+    this.#started = false;
     this.#emitSyncIntent({ kind: 'none' });
     this.#devtoolsUnregister?.();
     this.#devtoolsUnregister = undefined;
@@ -1239,7 +1245,6 @@ export class SyncClient {
     this.#abortPendingRound('client closed mid-round');
     await this.#lease?.release();
     this.#lease = undefined;
-    this.#started = false;
     this.#progress.clear();
     this.#syncNeededListeners.clear();
     this.#syncIntentListeners.clear();
@@ -1398,6 +1403,17 @@ export class SyncClient {
     return getLocalRevision(this.#db);
   }
 
+  /** Read the creation-time plain authority policy, including preflight. */
+  authoritySnapshot(): AuthoritySnapshot {
+    this.#requireStarted();
+    if (!this.#authorityReads || arguments.length)
+      throw new ClientSyncError(
+        'client.authority_read_forbidden',
+        'authority read denied',
+      );
+    return this.#authorityReads.snapshot(this.#db, this.#schema);
+  }
+
   /**
    * Read rows, window answerability, and revision from one SQLite snapshot.
    * Reactive integrations use this instead of composing `query()` and
@@ -1418,28 +1434,11 @@ export class SyncClient {
         const missing: WindowUnitRef[] = [];
         for (const requested of spec.coverage ?? []) {
           const baseKey = windowBaseKey(requested.base);
-          const live = new Map(
-            loadWindowUnits(this.#db, baseKey).map((entry) => [
-              entry.unit,
-              entry.subId,
-            ]),
-          );
+          const state = this.windowState(requested.base);
           for (const unit of new Set(requested.units)) {
-            const subId = live.get(unit);
             const ref = { baseKey, unit };
-            if (subId === undefined) {
-              missing.push(ref);
-              continue;
-            }
-            const sub = getSubscription(this.#db, subId);
-            if (
-              sub === undefined ||
-              sub.status !== 'active' ||
-              sub.cursor < 0 ||
-              sub.bootstrapState !== undefined
-            ) {
-              pending.push(ref);
-            }
+            if (!state.units.includes(unit)) missing.push(ref);
+            else if (state.pending.includes(unit)) pending.push(ref);
           }
         }
         return {
@@ -1817,7 +1816,7 @@ export class SyncClient {
         item.table.length === 0
       ) {
         throw invalidRequest(
-          'diagnosticsSnapshot expected subscriptions require non-empty id and table strings',
+          'diagnosticsSnapshot needs subscription id and table',
         );
       }
       const registeredSubscription = subscriptions.get(item.id);
@@ -3170,9 +3169,7 @@ export class SyncClient {
       };
     }
     if (this.#schemaFloor !== undefined) {
-      throw invalidRequest(
-        'local rebootstrap cannot bypass an active schema-floor stop; update the application first',
-      );
+      throw invalidRequest('local rebootstrap needs a schema-floor update');
     }
 
     const pending = listOutbox(this.#db);
@@ -5331,7 +5328,7 @@ export class SyncClient {
 
   #requireStarted(): void {
     if (!this.#started) {
-      throw invalidRequest('call SyncClient.start() first');
+      throw invalidRequest('call start() first');
     }
   }
 
@@ -5340,7 +5337,7 @@ export class SyncClient {
     if (this.#securityLifecycle === 'preflight') {
       throw new ClientSyncError(
         SECURITY_PREFLIGHT_REQUIRED_CODE,
-        'security preflight must complete before accessing protected data; call activateSecurity',
+        'protected reads require activateSecurity',
       );
     }
   }

package/src/index.ts

@@ -8,6 +8,11 @@
  * (`worker-host`) and the RPC protocol types are root exports — they
  * import no SQLite.
  */
+export type {
+  AuthorityReadPolicy,
+  AuthorityReadDeclaration,
+  AuthoritySnapshot,
+} from './authority';
 export * from './apply';
 export * from './availability';
 export * from './blob';