@syncular/tauri 0.15.13 → 0.15.15

package/README.md

@@ -28,6 +28,55 @@ for validating the server-authoritative directive, gating subscriptions before
 the purge, deleting app-owned drafts/files, and removing the corresponding key
 from the OS secure store after SQLite cleanup succeeds.
 
+## Secure preflight and native disposal
+
+Create with `securityPreflight: true` when authentication, signed device
+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.
+
+```ts
+const client = await createTauriSyncClient({
+  schema,
+  securityPreflight: true,
+});
+
+await client.purgeLocalData(directive.plan);
+await client.activateSecurity({ encryption: acceptedKeyring });
+```
+
+`beginSecurityPreflight()` closes the JavaScript gate synchronously, waits for
+the mutable owner and independent SQLite snapshot reader, disconnects realtime,
+and removes the Rust keyring. `close()` now issues native shutdown before
+detaching listeners, so disposing a resource does not leave a key-bearing core
+behind. The Rust core overwrites owned key buffers on replacement/drop; the app
+still owns OS secure-store deletion and any key buffers it supplied.
+
+## React availability guard
+
+The Tauri bridge carries `currentSchemaVersion`, `schemaFloor`, and migration
+status through the same public React boundary as the browser worker. Guard the
+application once instead of parsing native error strings:
+
+```tsx
+<SyncProvider
+  client={clientResource}
+  renderBoundary={(state, actions) => (
+    <SyncBlockedScreen state={state} onRetry={actions.retry} />
+  )}
+>
+  <App />
+</SyncProvider>
+```
+
+The state is a discriminated union covering startup, migration,
+`client-upgrade-required`, `server-behind`, and `incompatible-schema`.
+Compatibility recovery automatically restores the provider's children. Live
+queries report `phase === 'blocked'` with `isLoading === false` while retaining
+previously safe rows for an explicitly read-only view.
+
 Part of [Syncular](https://syncular.dev) — an offline-first sync framework.
 See the [Syncular repository](https://github.com/syncular/syncular) for docs.
 

package/dist/index.d.ts

@@ -26,7 +26,7 @@
  * `invoke`/`listen` either from its ESM entry points, from the ambient
  * `window.__TAURI__`, or via injected doubles (tests).
  */
-import type { ClientChangeListener, CommitOutcome, CommitOutcomeQuery, ConflictRecord, EncryptionKeyringConfig, InvalidationListener, LeaseState, LocalDataPurgeInput, LocalDataPurgeResult, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, ResolveCommitOutcomeInput, SchemaFloor, SqlRow, SqlValue, SyncStatusSnapshot, WindowBase, WindowState } from '@syncular/client';
+import type { ClientChangeListener, CommitOutcome, CommitOutcomeQuery, ConflictRecord, EncryptionKeyringConfig, InvalidationListener, LeaseState, LocalDataPurgeInput, LocalDataPurgeResult, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, ResolveCommitOutcomeInput, SchemaFloor, SecurityLifecycle, SqlRow, SqlValue, SyncStatusSnapshot, WindowBase, WindowState } from '@syncular/client';
 /** One event pushed on `syncular://event` (the derived client-observable set). */
 interface SyncularEvent {
     readonly type: string;
@@ -58,6 +58,8 @@ export interface TauriSyncClientConfig {
      * encoded into the native command envelope and never sent to the server.
      */
     readonly encryption?: EncryptionKeyringConfig;
+    /** Open the native replica behind the fail-closed security gate. */
+    readonly securityPreflight?: boolean;
     /**
      * The Tauri primitives. Omit in a real Tauri webview to auto-resolve from
      * `@tauri-apps/api` (peer dep) or the ambient `window.__TAURI__`; inject in
@@ -77,9 +79,14 @@ export type BytesEnvelope = {
 export declare class TauriSyncClient {
     #private;
     /** @internal — use {@link createTauriSyncClient}. */
-    constructor(tauri: TauriApi, unlisten: () => void);
+    constructor(tauri: TauriApi, unlisten: () => void, securityLifecycle?: SecurityLifecycle);
     /** @internal — fan an incoming plugin event out to the local listeners. */
     __dispatchEvent(event: SyncularEvent): void;
+    securityLifecycle(): Promise<SecurityLifecycle>;
+    beginSecurityPreflight(): Promise<void>;
+    activateSecurity(options?: {
+        readonly encryption?: EncryptionKeyringConfig;
+    }): Promise<void>;
     onInvalidate(listener: InvalidationListener): () => void;
     onChange(listener: ClientChangeListener): () => void;
     onPresence(listener: (scopeKey: string) => void): () => void;
@@ -135,7 +142,7 @@ export declare class TauriSyncClient {
     setPresence(scopeKey: string, doc: Record<string, unknown> | null): Promise<void>;
     connectRealtime(): Promise<void>;
     disconnectRealtime(): Promise<void>;
-    /** Detach the event listener; the native core keeps running (host process). */
+    /** Shut down the native core, release its keyring, then detach listeners. */
     close(): Promise<void>;
 }
 /** The error a `{error}` reply surfaces (mirrors the web-client `ClientSyncError`). */

package/dist/index.js

@@ -26,6 +26,10 @@
  * `invoke`/`listen` either from its ESM entry points, from the ambient
  * `window.__TAURI__`, or via injected doubles (tests).
  */
+// -- Types the bridge speaks (structurally the web-client's) -----------------
+// Most imports stay type-only; the stable preflight error code is shared at
+// runtime so every host surfaces byte-identical policy evidence.
+import { SECURITY_PREFLIGHT_REQUIRED_CODE } from '@syncular/client';
 /** The plugin's Tauri event name — mirror of `tauri-plugin-syncular`. */
 export const SYNCULAR_EVENT = 'syncular://event';
 const PLUGIN = 'plugin:syncular|';
@@ -151,19 +155,44 @@ export class TauriSyncClient {
     #presenceListeners = new Set();
     #unlisten;
     #closed = false;
+    #securityLifecycle;
+    #preflightBarrier;
     /** @internal — use {@link createTauriSyncClient}. */
-    constructor(tauri, unlisten) {
+    constructor(tauri, unlisten, securityLifecycle = 'active') {
         this.#tauri = tauri;
         this.#unlisten = unlisten;
+        this.#securityLifecycle = securityLifecycle;
     }
     /** Dispatch a `syncular_command` and unwrap `{result}` / throw on `{error}`. */
     async #command(method, params) {
+        if (this.#closed) {
+            throw new TauriSyncError('client.closed', 'the Tauri sync client is closed');
+        }
+        if (this.#securityLifecycle === 'preflight' &&
+            ![
+                'securityLifecycle',
+                'beginSecurityPreflight',
+                'activateSecurity',
+                'purgeLocalData',
+                'localRevision',
+                'statusSnapshot',
+                'shutdown',
+            ].includes(method)) {
+            this.#throwSecurityPreflight();
+        }
         const reply = await this.#tauri.invoke(`${PLUGIN}syncular_command`, { command: { method, params } });
         if (reply.error !== undefined) {
             throw new TauriSyncError(reply.error.code, reply.error.message);
         }
         return reply.result;
     }
+    #throwSecurityPreflight() {
+        throw new TauriSyncError(SECURITY_PREFLIGHT_REQUIRED_CODE, 'the local replica is in security preflight; complete quarantine checks and call activateSecurity before accessing protected data');
+    }
+    #requireActive() {
+        if (this.#securityLifecycle === 'preflight')
+            this.#throwSecurityPreflight();
+    }
     /** @internal — fan an incoming plugin event out to the local listeners. */
     __dispatchEvent(event) {
         switch (event.type) {
@@ -211,6 +240,40 @@ export class TauriSyncClient {
         }
     }
     // -- SyncClientLike --------------------------------------------------------
+    securityLifecycle() {
+        return Promise.resolve(this.#securityLifecycle);
+    }
+    beginSecurityPreflight() {
+        if (this.#closed) {
+            return Promise.reject(new TauriSyncError('client.closed', 'the Tauri sync client is closed'));
+        }
+        if (this.#preflightBarrier !== undefined)
+            return this.#preflightBarrier;
+        // Flip synchronously so a same-webview query cannot race the IPC barrier.
+        this.#securityLifecycle = 'preflight';
+        const barrier = this.#command('beginSecurityPreflight', {}).then(() => { });
+        this.#preflightBarrier = barrier;
+        void barrier.then(() => {
+            if (this.#preflightBarrier === barrier)
+                this.#preflightBarrier = undefined;
+        }, () => {
+            if (this.#preflightBarrier === barrier)
+                this.#preflightBarrier = undefined;
+        });
+        return barrier;
+    }
+    async activateSecurity(options = {}) {
+        if (this.#securityLifecycle === 'active') {
+            throw new TauriSyncError('sync.invalid_request', 'activateSecurity requires the client to be in security preflight');
+        }
+        await this.#preflightBarrier;
+        await this.#command('activateSecurity', {
+            ...(options.encryption !== undefined
+                ? { encryption: encodeEncryption(options.encryption) }
+                : {}),
+        });
+        this.#securityLifecycle = 'active';
+    }
     onInvalidate(listener) {
         this.#invalidationListeners.add(listener);
         return () => this.#invalidationListeners.delete(listener);
@@ -224,6 +287,7 @@ export class TauriSyncClient {
         return () => this.#presenceListeners.delete(listener);
     }
     async query(sql, params) {
+        this.#requireActive();
         const reply = await this.#tauri.invoke(`${PLUGIN}syncular_query`, { sql, params: (params ?? []).map(encodeParam) });
         if (reply.error !== undefined) {
             throw new TauriSyncError(reply.error.code, reply.error.message);
@@ -232,6 +296,7 @@ export class TauriSyncClient {
         return rows.map((r) => decodeRow(r));
     }
     async querySnapshot(spec) {
+        this.#requireActive();
         const reply = await this.#tauri.invoke(`${PLUGIN}syncular_query_snapshot`, {
             sql: spec.sql,
             params: (spec.params ?? []).map(encodeParam),
@@ -424,11 +489,16 @@ export class TauriSyncClient {
     async disconnectRealtime() {
         await this.#command('disconnectRealtime', {});
     }
-    /** Detach the event listener; the native core keeps running (host process). */
+    /** Shut down the native core, release its keyring, then detach listeners. */
     async close() {
         if (this.#closed)
             return;
-        this.#closed = true;
+        try {
+            await this.#command('shutdown', {});
+        }
+        finally {
+            this.#closed = true;
+        }
         this.#unlisten?.();
         this.#unlisten = undefined;
         this.#invalidationListeners.clear();
@@ -544,7 +614,11 @@ export async function createTauriSyncClient(config) {
     const unlisten = await tauri.listen(SYNCULAR_EVENT, (event) => {
         clientRef.client?.__dispatchEvent(event.payload);
     });
-    const client = new TauriSyncClient(tauri, unlisten);
+    if (config.securityPreflight === true && config.encryption !== undefined) {
+        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');
     clientRef.client = client;
     // The native side owns the db path (plugin config); the JS side supplies the
     // schema, clientId, and limits. `dbPath` is injected by the plugin.
@@ -558,6 +632,9 @@ export async function createTauriSyncClient(config) {
                 ...(config.encryption !== undefined
                     ? { encryption: encodeEncryption(config.encryption) }
                     : {}),
+                ...(config.securityPreflight !== undefined
+                    ? { securityPreflight: config.securityPreflight }
+                    : {}),
             },
         },
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/tauri",
-  "version": "0.15.13",
+  "version": "0.15.15",
   "description": "Tauri integration for the Syncular client",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -48,12 +48,12 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@syncular/client": "0.15.13"
+    "@syncular/client": "0.15.15"
   },
   "peerDependencies": {
     "@tauri-apps/api": ">=2.0.0"
   },
   "devDependencies": {
-    "@syncular/react": "0.15.13"
+    "@syncular/react": "0.15.15"
   }
 }

package/src/index.ts

@@ -27,9 +27,6 @@
  * `window.__TAURI__`, or via injected doubles (tests).
  */
 
-// -- Types the bridge speaks (structurally the web-client's) -----------------
-// Imported as types only, so the bridge has no runtime dependency on
-// @syncular/client (the app already carries it via @syncular/react).
 import type {
   ClientChangeBatch,
   ClientChangeListener,
@@ -49,12 +46,17 @@ import type {
   RejectionRecord,
   ResolveCommitOutcomeInput,
   SchemaFloor,
+  SecurityLifecycle,
   SqlRow,
   SqlValue,
   SyncStatusSnapshot,
   WindowBase,
   WindowState,
 } from '@syncular/client';
+// -- Types the bridge speaks (structurally the web-client's) -----------------
+// Most imports stay type-only; the stable preflight error code is shared at
+// runtime so every host surfaces byte-identical policy evidence.
+import { SECURITY_PREFLIGHT_REQUIRED_CODE } from '@syncular/client';
 
 /** A driver-protocol reply: `{result}` on success or `{error}` on failure. */
 interface CommandReply {
@@ -99,6 +101,8 @@ export interface TauriSyncClientConfig {
    * encoded into the native command envelope and never sent to the server.
    */
   readonly encryption?: EncryptionKeyringConfig;
+  /** Open the native replica behind the fail-closed security gate. */
+  readonly securityPreflight?: boolean;
   /**
    * The Tauri primitives. Omit in a real Tauri webview to auto-resolve from
    * `@tauri-apps/api` (peer dep) or the ambient `window.__TAURI__`; inject in
@@ -249,11 +253,18 @@ export class TauriSyncClient {
   readonly #presenceListeners = new Set<(scopeKey: string) => void>();
   #unlisten: (() => void) | undefined;
   #closed = false;
+  #securityLifecycle: SecurityLifecycle;
+  #preflightBarrier: Promise<void> | undefined;
 
   /** @internal — use {@link createTauriSyncClient}. */
-  constructor(tauri: TauriApi, unlisten: () => void) {
+  constructor(
+    tauri: TauriApi,
+    unlisten: () => void,
+    securityLifecycle: SecurityLifecycle = 'active',
+  ) {
     this.#tauri = tauri;
     this.#unlisten = unlisten;
+    this.#securityLifecycle = securityLifecycle;
   }
 
   /** Dispatch a `syncular_command` and unwrap `{result}` / throw on `{error}`. */
@@ -261,6 +272,26 @@ export class TauriSyncClient {
     method: string,
     params: Record<string, unknown>,
   ): Promise<unknown> {
+    if (this.#closed) {
+      throw new TauriSyncError(
+        'client.closed',
+        'the Tauri sync client is closed',
+      );
+    }
+    if (
+      this.#securityLifecycle === 'preflight' &&
+      ![
+        'securityLifecycle',
+        'beginSecurityPreflight',
+        'activateSecurity',
+        'purgeLocalData',
+        'localRevision',
+        'statusSnapshot',
+        'shutdown',
+      ].includes(method)
+    ) {
+      this.#throwSecurityPreflight();
+    }
     const reply = await this.#tauri.invoke<CommandReply>(
       `${PLUGIN}syncular_command`,
       { command: { method, params } },
@@ -271,6 +302,17 @@ export class TauriSyncClient {
     return reply.result;
   }
 
+  #throwSecurityPreflight(): never {
+    throw new TauriSyncError(
+      SECURITY_PREFLIGHT_REQUIRED_CODE,
+      'the local replica is in security preflight; complete quarantine checks and call activateSecurity before accessing protected data',
+    );
+  }
+
+  #requireActive(): void {
+    if (this.#securityLifecycle === 'preflight') this.#throwSecurityPreflight();
+  }
+
   /** @internal — fan an incoming plugin event out to the local listeners. */
   __dispatchEvent(event: SyncularEvent): void {
     switch (event.type) {
@@ -316,6 +358,52 @@ export class TauriSyncClient {
 
   // -- SyncClientLike --------------------------------------------------------
 
+  securityLifecycle(): Promise<SecurityLifecycle> {
+    return Promise.resolve(this.#securityLifecycle);
+  }
+
+  beginSecurityPreflight(): Promise<void> {
+    if (this.#closed) {
+      return Promise.reject(
+        new TauriSyncError('client.closed', 'the Tauri sync client is closed'),
+      );
+    }
+    if (this.#preflightBarrier !== undefined) return this.#preflightBarrier;
+    // Flip synchronously so a same-webview query cannot race the IPC barrier.
+    this.#securityLifecycle = 'preflight';
+    const barrier = this.#command('beginSecurityPreflight', {}).then(() => {});
+    this.#preflightBarrier = barrier;
+    void barrier.then(
+      () => {
+        if (this.#preflightBarrier === barrier)
+          this.#preflightBarrier = undefined;
+      },
+      () => {
+        if (this.#preflightBarrier === barrier)
+          this.#preflightBarrier = undefined;
+      },
+    );
+    return barrier;
+  }
+
+  async activateSecurity(
+    options: { readonly encryption?: EncryptionKeyringConfig } = {},
+  ): Promise<void> {
+    if (this.#securityLifecycle === 'active') {
+      throw new TauriSyncError(
+        'sync.invalid_request',
+        'activateSecurity requires the client to be in security preflight',
+      );
+    }
+    await this.#preflightBarrier;
+    await this.#command('activateSecurity', {
+      ...(options.encryption !== undefined
+        ? { encryption: encodeEncryption(options.encryption) }
+        : {}),
+    });
+    this.#securityLifecycle = 'active';
+  }
+
   onInvalidate(listener: InvalidationListener): () => void {
     this.#invalidationListeners.add(listener);
     return () => this.#invalidationListeners.delete(listener);
@@ -332,6 +420,7 @@ export class TauriSyncClient {
   }
 
   async query(sql: string, params?: readonly SqlValue[]): Promise<SqlRow[]> {
+    this.#requireActive();
     const reply = await this.#tauri.invoke<CommandReply>(
       `${PLUGIN}syncular_query`,
       { sql, params: (params ?? []).map(encodeParam) },
@@ -346,6 +435,7 @@ export class TauriSyncClient {
   async querySnapshot<Row = SqlRow>(
     spec: QueryReadSpec,
   ): Promise<QuerySnapshot<Row>> {
+    this.#requireActive();
     const reply = await this.#tauri.invoke<CommandReply>(
       `${PLUGIN}syncular_query_snapshot`,
       {
@@ -643,10 +733,14 @@ export class TauriSyncClient {
     await this.#command('disconnectRealtime', {});
   }
 
-  /** Detach the event listener; the native core keeps running (host process). */
+  /** Shut down the native core, release its keyring, then detach listeners. */
   async close(): Promise<void> {
     if (this.#closed) return;
-    this.#closed = true;
+    try {
+      await this.#command('shutdown', {});
+    } finally {
+      this.#closed = true;
+    }
     this.#unlisten?.();
     this.#unlisten = undefined;
     this.#invalidationListeners.clear();
@@ -770,7 +864,19 @@ export async function createTauriSyncClient(
     },
   );
 
-  const client = new TauriSyncClient(tauri, unlisten);
+  if (config.securityPreflight === true && config.encryption !== undefined) {
+    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',
+  );
   clientRef.client = client;
 
   // The native side owns the db path (plugin config); the JS side supplies the
@@ -785,6 +891,9 @@ export async function createTauriSyncClient(
         ...(config.encryption !== undefined
           ? { encryption: encodeEncryption(config.encryption) }
           : {}),
+        ...(config.securityPreflight !== undefined
+          ? { securityPreflight: config.securityPreflight }
+          : {}),
       },
     },
   });