@syncular/tauri 0.30.14 → 0.30.16

package/README.md

@@ -153,7 +153,9 @@ quarantine, or crash-resumed cleanup must finish before clinical data is
 available. The native database opens and migrates, but query/snapshot, mutation,
 subscription, sync, realtime, presence, blob, and automatic retry work fails
 with `client.security_preflight_required`. Status, local revision, lifecycle,
-and `purgeLocalData` remain available.
+and `purgeLocalData` remain available. A creation-time `defineAuthorityReads`
+policy on `createTauriAuthoritySyncClient` enables the read-only
+`authoritySnapshot()` described below.
 
 ```ts
 const client = await createTauriSyncClient({
@@ -180,6 +182,82 @@ with `setHeaders()` only after successful activation. Closed clients reject data
 and control calls with `client.closed` before testing preflight; listener
 registration and local progress reads throw that code. `close()` is idempotent.
 
+## Authority evidence before activation
+
+Declare authority reads at client creation with `defineAuthorityReads` from
+`@syncular/client/authority`. Each table declares plain columns, including
+its primary key and scope columns, and concrete scope selectors. These selectors remain
+fixed for that client. A declaration cannot include encrypted, bytes, blob,
+CRDT or internal columns. Choose only authority fields; clinical fields and
+credentials do not belong in this policy.
+
+```ts
+import { defineAuthorityReads } from '@syncular/client/authority';
+import { createTauriAuthoritySyncClient } from '@syncular/tauri/authority';
+
+const client = await createTauriAuthoritySyncClient({
+  schema,
+  securityPreflight: true,
+  transportEnabled: false,
+  authorityReads: defineAuthorityReads([{
+    table: 'memberships',
+    columns: ['id', 'user_id', 'facility_id', 'status', 'version'],
+    scopes: { membership_id: acceptedMembershipIds },
+  }]),
+});
+const evidence = await client.authoritySnapshot();
+```
+
+Use `createTauriAuthoritySyncClient` for the bridge that exposes
+`authoritySnapshot()`. The ordinary `createTauriSyncClient` class does not
+contain that method or its reply decoder. Upgrade 0.30.15 callers to these
+explicit subpaths; the snapshot and native security checks keep their semantics.
+
+The native application must also set an independent ceiling at plugin creation:
+
+```rust
+let config = SyncularConfig {
+    authority_columns: [("memberships".into(), vec![
+        "id".into(), "user_id".into(), "facility_id".into(),
+        "status".into(), "version".into(),
+    ])].into(),
+    ..Default::default()
+};
+```
+
+Rust rejects any webview declaration outside that ceiling. It also validates
+columns against the schema. `authoritySnapshot()` accepts zero arguments;
+forged IPC carrying SQL, replacement tables or columns fails with
+`client.authority_read_forbidden`. Ordinary `query`, `querySnapshot` and writes
+still fail with `client.security_preflight_required`.
+
+The result contains `revision: bigint`, `complete`, and `tables`. Every table
+contains accepted `rows` (`values`, server `version`, `hasLocalIntent`), scoped
+`localIntentRowIds`, the declared `scopes`, `coverage`, and sanitized
+`persisted` subscription evidence (`requestedScopes`, `effectiveScopes`,
+`cursor`, `status`, `complete`). It exposes no intended values, bootstrap
+tokens, subscription parameters or keys. Both cores read rows, revision and
+coverage in one SQLite snapshot. The native authority read runs on the mutable
+owner; it does not use the ordinary query sidecar or its latency contract.
+
+`coverage` is `complete`, `pending` or `missing`. Complete coverage requires
+completed unfiltered subscriptions for every requested scope tuple. Several
+subscriptions can cover the selection together. Scope loss and an unfinished
+bootstrap invalidate completeness. Completed empty coverage has an empty row
+set. The application must reject admission when an expected authority row is
+absent, even when the set is complete.
+
+Accepted bases remain separate from pending, failed and protected ACK intent.
+A local-only creation appears only in `localIntentRowIds`. The application
+validates the complete chain against independently accepted authority evidence,
+actor/device identity, signed lease and trusted time before installing keys.
+The SDK does not authorize the application. The read changes no lifecycle,
+transport, keyring, subscriptions or rows.
+
+The direct Bun/SQLite client and worker handle expose the same policy and
+snapshot shape. Importing the policy is opt-in; ordinary clients do not ship
+its reader. Update npm packages and native crates together and rebuild the app.
+
 ## Privacy-safe diagnostics
 
 `diagnosticsSnapshot({ expectedSubscriptions })` and `onDiagnostics(listener)`

package/dist/authority.d.ts

@@ -0,0 +1,10 @@
+import type { AuthorityReadPolicy, AuthoritySnapshot } from '@syncular/client/authority';
+import { TauriSyncClient, type TauriSyncClientConfig } from './index.js';
+/** Explicit native bridge with the zero-argument preflight authority read. */
+export declare class TauriAuthoritySyncClient extends TauriSyncClient {
+    authoritySnapshot(): Promise<AuthoritySnapshot>;
+}
+/** Construct an authority-enabled bridge; Rust still enforces its independent ceiling. */
+export declare function createTauriAuthoritySyncClient(config: TauriSyncClientConfig & {
+    readonly authorityReads: AuthorityReadPolicy;
+}): Promise<TauriAuthoritySyncClient>;

package/dist/authority.js

@@ -0,0 +1,26 @@
+import { createTauriSyncClient, decodeRow, TauriSyncClient, TauriSyncError, } from './index.js';
+/** Explicit native bridge with the zero-argument preflight authority read. */
+export class TauriAuthoritySyncClient extends TauriSyncClient {
+    async authoritySnapshot() {
+        this.requireOpen();
+        if (arguments.length)
+            throw new TauriSyncError('client.authority_read_forbidden', 'authoritySnapshot accepts no arguments');
+        const result = (await this.command('authoritySnapshot', {}));
+        this.requireOpen();
+        return {
+            ...result,
+            revision: BigInt(result.revision),
+            tables: result.tables.map((table) => ({
+                ...table,
+                rows: table.rows.map((row) => ({
+                    ...row,
+                    values: decodeRow(row.values),
+                })),
+            })),
+        };
+    }
+}
+/** Construct an authority-enabled bridge; Rust still enforces its independent ceiling. */
+export function createTauriAuthoritySyncClient(config) {
+    return createTauriSyncClient(config, (...args) => new TauriAuthoritySyncClient(...args));
+}

package/dist/index.d.ts

@@ -28,7 +28,7 @@ import type { ClientSnapshotMethods, PromiseMethods } from '@syncular/client';
  * `invoke`/`listen` either from its ESM entry points, from the ambient
  * `window.__TAURI__`, or via injected doubles (tests).
  */
-import type { ClientChangeListener, ClientDiagnosticsListener, ClientDiagnosticsRequest, ClientDiagnosticsSnapshot, CommitOutcome, CommitOutcomeQuery, ConflictRecord, EncryptionKeyringConfig, InvalidationListener, LocalDataPurgeInput, LocalDataPurgeResult, LocalDataRebootstrapInput, LocalDataRebootstrapResult, MutationInput, PresencePeer, PreviousVersionAudit, PreviousVersionReadSpec, PreviousVersionSnapshot, QueryReadSpec, QuerySnapshot, RejectionRecord, ResolveCommitOutcomeInput, SecurityLifecycle, SqlRow, SqlValue, SyncClientConfig, SyncStatusSnapshot, WindowBase, WindowState } from '@syncular/client';
+import type { AuthorityReadPolicy, ClientChangeListener, ClientDiagnosticsListener, ClientDiagnosticsRequest, ClientDiagnosticsSnapshot, CommitOutcome, CommitOutcomeQuery, ConflictRecord, EncryptionKeyringConfig, InvalidationListener, LocalDataPurgeInput, LocalDataPurgeResult, LocalDataRebootstrapInput, LocalDataRebootstrapResult, MutationInput, PresencePeer, PreviousVersionAudit, PreviousVersionReadSpec, PreviousVersionSnapshot, QueryReadSpec, QuerySnapshot, RejectionRecord, ResolveCommitOutcomeInput, SecurityLifecycle, SqlRow, SqlValue, SyncClientConfig, SyncStatusSnapshot, WindowBase, WindowState } from '@syncular/client';
 /** One event pushed on `syncular://event` (the derived client-observable set). */
 interface SyncularEvent {
     readonly type: string;
@@ -74,6 +74,8 @@ export interface TauriSyncClientConfig {
      * encoded into the native command envelope and never sent to the server.
      */
     readonly encryption?: EncryptionKeyringConfig;
+    /** Fixed plain authority reads permitted before security activation. */
+    readonly authorityReads?: AuthorityReadPolicy;
     /** Open the native replica behind the fail-closed security gate. */
     readonly securityPreflight?: boolean;
     /** Open local storage with network transport closed until explicitly resumed. */
@@ -95,6 +97,8 @@ export interface TauriSyncClientConfig {
 export type BytesEnvelope = {
     readonly $bytes: string;
 };
+/** @internal Shared native row codec. */
+export declare function decodeRow(row: Record<string, unknown>): SqlRow;
 /**
  * The webview-side proxy implementing `SyncClientLike` over the plugin. Every
  * snapshot method returns a promise from an IPC round trip. React hooks accept
@@ -104,6 +108,10 @@ export declare class TauriSyncClient implements PromiseMethods<ClientSnapshotMet
     #private;
     /** @internal — use {@link createTauriSyncClient}. */
     constructor(tauri: TauriApi, unlisten: () => void, securityLifecycle?: SecurityLifecycle);
+    /** @internal Shared command gate for explicit bridge extensions. */
+    protected command(method: string, params: Record<string, unknown>): Promise<unknown>;
+    /** @internal Recheck local close after an extension's asynchronous reply. */
+    protected requireOpen(): void;
     /** @internal — fan an incoming plugin event out to the local listeners. */
     __dispatchEvent(event: SyncularEvent): void;
     securityLifecycle(): Promise<SecurityLifecycle>;
@@ -201,4 +209,6 @@ export declare class TauriSyncError extends Error {
  * React `<SyncProvider client={…}>`.
  */
 export declare function createTauriSyncClient(config: TauriSyncClientConfig): Promise<TauriSyncClient>;
+/** @internal Explicit bridge extension used by the authority entry. */
+export declare function createTauriSyncClient<Client extends TauriSyncClient>(config: TauriSyncClientConfig, createClient: (...args: ConstructorParameters<typeof TauriSyncClient>) => Client): Promise<Client>;
 export {};

package/dist/index.js

@@ -82,7 +82,8 @@ function decodeCell(value) {
     // string (SQLite json columns arrive as text already; this is defensive).
     return JSON.stringify(value);
 }
-function decodeRow(row) {
+/** @internal Shared native row codec. */
+export function decodeRow(row) {
     const out = {};
     for (const [key, value] of Object.entries(row)) {
         // Reserved `_sync_*` columns stay engine-internal (parity with the
@@ -163,6 +164,7 @@ export class TauriSyncClient {
         this.#requireOpen();
         if (this.#securityLifecycle === 'preflight' &&
             ![
+                'authoritySnapshot',
                 'securityLifecycle',
                 'beginSecurityPreflight',
                 'activateSecurity',
@@ -189,6 +191,14 @@ export class TauriSyncClient {
             throw new TauriSyncError('client.closed', 'the Tauri sync client is closed');
         }
     }
+    /** @internal Shared command gate for explicit bridge extensions. */
+    command(method, params) {
+        return this.#command(method, params);
+    }
+    /** @internal Recheck local close after an extension's asynchronous reply. */
+    requireOpen() {
+        this.#requireOpen();
+    }
     #requireActive() {
         this.#requireOpen();
         if (this.#securityLifecycle === 'preflight')
@@ -578,19 +588,20 @@ export class TauriSyncClient {
     async close() {
         if (this.#closed)
             return;
+        const shutdown = this.#command('shutdown', {});
+        this.#closed = true;
         try {
-            await this.#command('shutdown', {});
+            await shutdown;
         }
         finally {
-            this.#closed = true;
+            this.#unlisten?.();
+            this.#unlisten = undefined;
+            this.#invalidationListeners.clear();
+            this.#progress.clear();
+            this.#changeListeners.clear();
+            this.#diagnosticsListeners.clear();
+            this.#presenceListeners.clear();
         }
-        this.#unlisten?.();
-        this.#unlisten = undefined;
-        this.#invalidationListeners.clear();
-        this.#progress.clear();
-        this.#changeListeners.clear();
-        this.#diagnosticsListeners.clear();
-        this.#presenceListeners.clear();
     }
 }
 function decodeDiagnosticsSnapshot(value, kind) {
@@ -700,13 +711,7 @@ function encodeMutation(mutation) {
     }
     return { ...mutation, values };
 }
-/**
- * Construct the bridge and issue the native `create` (opening/attaching the
- * file DB on the Rust side per the plugin config). Returns a ready
- * `TauriSyncClient` that satisfies `SyncClientLike` — pass it straight to the
- * React `<SyncProvider client={…}>`.
- */
-export async function createTauriSyncClient(config) {
+export async function createTauriSyncClient(config, createClient = (...args) => new TauriSyncClient(...args)) {
     const tauri = await resolveTauri(config.tauri);
     // Wire the event stream BEFORE create, so no early change batch is missed.
     const clientRef = {
@@ -719,7 +724,7 @@ export async function createTauriSyncClient(config) {
         unlisten();
         throw new TauriSyncError('sync.invalid_request', 'securityPreflight and encryption are mutually exclusive; install keys with activateSecurity after preflight');
     }
-    const client = new TauriSyncClient(tauri, unlisten, config.securityPreflight === true ? 'preflight' : 'active');
+    const client = createClient(tauri, unlisten, config.securityPreflight === true ? 'preflight' : 'active');
     clientRef.client = client;
     // The native side owns every path (plugin config); the JS side names a
     // database and supplies the schema, clientId, and limits.
@@ -743,6 +748,9 @@ export async function createTauriSyncClient(config) {
                 ...(config.transportEnabled !== undefined
                     ? { transportEnabled: config.transportEnabled }
                     : {}),
+                ...(config.authorityReads !== undefined
+                    ? { authorityReads: config.authorityReads.declarations }
+                    : {}),
                 ...(config.securityPreflight !== undefined
                     ? { securityPreflight: config.securityPreflight }
                     : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/tauri",
-  "version": "0.30.14",
+  "version": "0.30.16",
   "description": "Tauri integration for the Syncular client",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -33,6 +33,14 @@
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
       }
+    },
+    "./authority": {
+      "bun": "./src/authority.ts",
+      "browser": "./dist/authority.js",
+      "import": {
+        "types": "./dist/authority.d.ts",
+        "default": "./dist/authority.js"
+      }
     }
   },
   "files": [
@@ -48,13 +56,13 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@syncular/client": "0.30.14"
+    "@syncular/client": "0.30.16"
   },
   "peerDependencies": {
     "@tauri-apps/api": ">=2.0.0"
   },
   "devDependencies": {
-    "@syncular/react": "0.30.14",
-    "@syncular/server": "0.30.14"
+    "@syncular/react": "0.30.16",
+    "@syncular/server": "0.30.16"
   }
 }

package/src/authority.ts

@@ -0,0 +1,51 @@
+import type {
+  AuthorityReadPolicy,
+  AuthoritySnapshot,
+} from '@syncular/client/authority';
+import {
+  createTauriSyncClient,
+  decodeRow,
+  TauriSyncClient,
+  TauriSyncError,
+  type TauriSyncClientConfig,
+} from './index';
+
+/** Explicit native bridge with the zero-argument preflight authority read. */
+export class TauriAuthoritySyncClient extends TauriSyncClient {
+  async authoritySnapshot(): Promise<AuthoritySnapshot> {
+    this.requireOpen();
+    if (arguments.length)
+      throw new TauriSyncError(
+        'client.authority_read_forbidden',
+        'authoritySnapshot accepts no arguments',
+      );
+    const result = (await this.command('authoritySnapshot', {})) as Omit<
+      AuthoritySnapshot,
+      'revision'
+    > & { revision: string };
+    this.requireOpen();
+    return {
+      ...result,
+      revision: BigInt(result.revision),
+      tables: result.tables.map((table) => ({
+        ...table,
+        rows: table.rows.map((row) => ({
+          ...row,
+          values: decodeRow(row.values),
+        })),
+      })),
+    };
+  }
+}
+
+/** Construct an authority-enabled bridge; Rust still enforces its independent ceiling. */
+export function createTauriAuthoritySyncClient(
+  config: TauriSyncClientConfig & {
+    readonly authorityReads: AuthorityReadPolicy;
+  },
+): Promise<TauriAuthoritySyncClient> {
+  return createTauriSyncClient(
+    config,
+    (...args) => new TauriAuthoritySyncClient(...args),
+  );
+}

package/src/index.ts

@@ -34,6 +34,7 @@ import type { ClientSnapshotMethods, PromiseMethods } from '@syncular/client';
  */
 
 import type {
+  AuthorityReadPolicy,
   ClientChangeBatch,
   ClientChangeListener,
   ClientDiagnosticsListener,
@@ -139,6 +140,8 @@ export interface TauriSyncClientConfig {
    * encoded into the native command envelope and never sent to the server.
    */
   readonly encryption?: EncryptionKeyringConfig;
+  /** Fixed plain authority reads permitted before security activation. */
+  readonly authorityReads?: AuthorityReadPolicy;
   /** Open the native replica behind the fail-closed security gate. */
   readonly securityPreflight?: boolean;
   /** Open local storage with network transport closed until explicitly resumed. */
@@ -246,7 +249,8 @@ function decodeCell(value: unknown): SqlValue {
   return JSON.stringify(value);
 }
 
-function decodeRow(row: Record<string, unknown>): SqlRow {
+/** @internal Shared native row codec. */
+export function decodeRow(row: Record<string, unknown>): SqlRow {
   const out: SqlRow = {};
   for (const [key, value] of Object.entries(row)) {
     // Reserved `_sync_*` columns stay engine-internal (parity with the
@@ -346,6 +350,7 @@ export class TauriSyncClient implements PromiseMethods<ClientSnapshotMethods> {
     if (
       this.#securityLifecycle === 'preflight' &&
       ![
+        'authoritySnapshot',
         'securityLifecycle',
         'beginSecurityPreflight',
         'activateSecurity',
@@ -389,6 +394,19 @@ export class TauriSyncClient implements PromiseMethods<ClientSnapshotMethods> {
     }
   }
 
+  /** @internal Shared command gate for explicit bridge extensions. */
+  protected command(
+    method: string,
+    params: Record<string, unknown>,
+  ): Promise<unknown> {
+    return this.#command(method, params);
+  }
+
+  /** @internal Recheck local close after an extension's asynchronous reply. */
+  protected requireOpen(): void {
+    this.#requireOpen();
+  }
+
   #requireActive(): void {
     this.#requireOpen();
     if (this.#securityLifecycle === 'preflight') this.#throwSecurityPreflight();
@@ -932,18 +950,19 @@ export class TauriSyncClient implements PromiseMethods<ClientSnapshotMethods> {
   /** Shut down the native core, release its keyring, then detach listeners. */
   async close(): Promise<void> {
     if (this.#closed) return;
+    const shutdown = this.#command('shutdown', {});
+    this.#closed = true;
     try {
-      await this.#command('shutdown', {});
+      await shutdown;
     } finally {
-      this.#closed = true;
+      this.#unlisten?.();
+      this.#unlisten = undefined;
+      this.#invalidationListeners.clear();
+      this.#progress.clear();
+      this.#changeListeners.clear();
+      this.#diagnosticsListeners.clear();
+      this.#presenceListeners.clear();
     }
-    this.#unlisten?.();
-    this.#unlisten = undefined;
-    this.#invalidationListeners.clear();
-    this.#progress.clear();
-    this.#changeListeners.clear();
-    this.#diagnosticsListeners.clear();
-    this.#presenceListeners.clear();
   }
 }
 
@@ -1066,8 +1085,20 @@ function encodeMutation(mutation: MutationInput): unknown {
  * `TauriSyncClient` that satisfies `SyncClientLike` — pass it straight to the
  * React `<SyncProvider client={…}>`.
  */
+export function createTauriSyncClient(
+  config: TauriSyncClientConfig,
+): Promise<TauriSyncClient>;
+/** @internal Explicit bridge extension used by the authority entry. */
+export function createTauriSyncClient<Client extends TauriSyncClient>(
+  config: TauriSyncClientConfig,
+  createClient: (
+    ...args: ConstructorParameters<typeof TauriSyncClient>
+  ) => Client,
+): Promise<Client>;
 export async function createTauriSyncClient(
   config: TauriSyncClientConfig,
+  createClient = (...args: ConstructorParameters<typeof TauriSyncClient>) =>
+    new TauriSyncClient(...args),
 ): Promise<TauriSyncClient> {
   const tauri = await resolveTauri(config.tauri);
 
@@ -1090,7 +1121,7 @@ export async function createTauriSyncClient(
     );
   }
 
-  const client = new TauriSyncClient(
+  const client = createClient(
     tauri,
     unlisten,
     config.securityPreflight === true ? 'preflight' : 'active',
@@ -1119,6 +1150,9 @@ export async function createTauriSyncClient(
         ...(config.transportEnabled !== undefined
           ? { transportEnabled: config.transportEnabled }
           : {}),
+        ...(config.authorityReads !== undefined
+          ? { authorityReads: config.authorityReads.declarations }
+          : {}),
         ...(config.securityPreflight !== undefined
           ? { securityPreflight: config.securityPreflight }
           : {}),