@syncular/tauri 0.15.15 → 0.15.17

package/README.md

@@ -54,6 +54,26 @@ 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.
 
+Runtime `setHeaders()` is an active-session operation and is rejected during
+preflight at both the JavaScript and native command boundaries. Supply bootstrap
+headers through trusted plugin configuration; rotate them only after successful
+activation.
+
+## Privacy-safe diagnostics
+
+`diagnosticsSnapshot({ expectedSubscriptions })` and `onDiagnostics(listener)`
+carry the native Rust core's versioned support evidence through the Tauri event
+channel. The bridge marks the host as `{ kind: 'tauri', role: 'single' }`; it
+does not infer state from IPC commands. Expected subscriptions accept only
+stable PHI-free ids and generated table names, never scope values.
+
+The snapshot is suitable for a redacted “copy diagnostics” workflow: it omits
+rows, clinical row counts, scopes, SQL, paths, client/actor/lease ids, auth,
+keys, mutations, stack traces, and arbitrary prose. Do not supplement it with
+the SQLite file, WebView console dump, or application state. Diagnostics stays
+blocked during security preflight because subscription/table evidence is
+protected. See SPEC §7.6 and `@syncular/react`'s `useDiagnostics`.
+
 ## React availability guard
 
 The Tauri bridge carries `currentSchemaVersion`, `schemaFloor`, and migration

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, SecurityLifecycle, SqlRow, SqlValue, SyncStatusSnapshot, WindowBase, WindowState } from '@syncular/client';
+import type { ClientChangeListener, ClientDiagnosticsListener, ClientDiagnosticsRequest, ClientDiagnosticsSnapshot, 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;
@@ -89,11 +89,13 @@ export declare class TauriSyncClient {
     }): Promise<void>;
     onInvalidate(listener: InvalidationListener): () => void;
     onChange(listener: ClientChangeListener): () => void;
+    onDiagnostics(listener: ClientDiagnosticsListener): () => void;
     onPresence(listener: (scopeKey: string) => void): () => void;
     query(sql: string, params?: readonly SqlValue[]): Promise<SqlRow[]>;
     querySnapshot<Row = SqlRow>(spec: QueryReadSpec): Promise<QuerySnapshot<Row>>;
     localRevision(): Promise<bigint>;
     statusSnapshot(): Promise<SyncStatusSnapshot>;
+    diagnosticsSnapshot(request?: ClientDiagnosticsRequest): Promise<ClientDiagnosticsSnapshot>;
     mutate(mutations: readonly MutationInput[]): Promise<string>;
     patch(table: string, rowId: string, partial: Readonly<Record<string, unknown>>, options?: {
         readonly baseVersion?: number;

package/dist/index.js

@@ -29,7 +29,7 @@
 // -- 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';
+import { SECURITY_PREFLIGHT_REQUIRED_CODE, withClientDiagnosticsHost, } from '@syncular/client';
 /** The plugin's Tauri event name — mirror of `tauri-plugin-syncular`. */
 export const SYNCULAR_EVENT = 'syncular://event';
 const PLUGIN = 'plugin:syncular|';
@@ -152,6 +152,7 @@ export class TauriSyncClient {
     #tauri;
     #invalidationListeners = new Set();
     #changeListeners = new Set();
+    #diagnosticsListeners = new Set();
     #presenceListeners = new Set();
     #unlisten;
     #closed = false;
@@ -233,6 +234,20 @@ export class TauriSyncClient {
                 }
                 break;
             }
+            case 'diagnostics': {
+                const snapshot = decodeDiagnosticsSnapshot(event.snapshot, 'tauri');
+                if (snapshot === undefined)
+                    break;
+                for (const listener of this.#diagnosticsListeners) {
+                    try {
+                        listener(snapshot);
+                    }
+                    catch {
+                        /* a diagnostics observer must never break event dispatch */
+                    }
+                }
+                break;
+            }
             default:
                 // Unknown extension events are deliberately ignored. All durable
                 // observable state arrives in the revisioned `change` batch.
@@ -282,6 +297,10 @@ export class TauriSyncClient {
         this.#changeListeners.add(listener);
         return () => this.#changeListeners.delete(listener);
     }
+    onDiagnostics(listener) {
+        this.#diagnosticsListeners.add(listener);
+        return () => this.#diagnosticsListeners.delete(listener);
+    }
     onPresence(listener) {
         this.#presenceListeners.add(listener);
         return () => this.#presenceListeners.delete(listener);
@@ -319,6 +338,16 @@ export class TauriSyncClient {
     async statusSnapshot() {
         return (await this.#command('statusSnapshot', {}));
     }
+    async diagnosticsSnapshot(request = {}) {
+        const snapshot = (await this.#command('diagnosticsSnapshot', {
+            expectedSubscriptions: request.expectedSubscriptions ?? [],
+        }));
+        return withClientDiagnosticsHost(snapshot, {
+            ...snapshot.host,
+            kind: 'tauri',
+            role: 'single',
+        });
+    }
     async mutate(mutations) {
         const result = (await this.#command('mutate', {
             mutations: mutations.map(encodeMutation),
@@ -348,6 +377,7 @@ export class TauriSyncClient {
      * the realtime socket applies it on its next (re)connect.
      */
     async setHeaders(headers) {
+        this.#requireActive();
         const reply = await this.#tauri.invoke(`${PLUGIN}syncular_set_headers`, { headers });
         if (reply.error !== undefined) {
             throw new TauriSyncError(reply.error.code, reply.error.message);
@@ -503,9 +533,22 @@ export class TauriSyncClient {
         this.#unlisten = undefined;
         this.#invalidationListeners.clear();
         this.#changeListeners.clear();
+        this.#diagnosticsListeners.clear();
         this.#presenceListeners.clear();
     }
 }
+function decodeDiagnosticsSnapshot(value, kind) {
+    if (value === null || typeof value !== 'object')
+        return undefined;
+    const snapshot = value;
+    if (snapshot.version !== 1 || snapshot.host === undefined)
+        return undefined;
+    return withClientDiagnosticsHost(snapshot, {
+        ...snapshot.host,
+        kind,
+        role: 'single',
+    });
+}
 /** The error a `{error}` reply surfaces (mirrors the web-client `ClientSyncError`). */
 export class TauriSyncError extends Error {
     code;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/tauri",
-  "version": "0.15.15",
+  "version": "0.15.17",
   "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.15"
+    "@syncular/client": "0.15.17"
   },
   "peerDependencies": {
     "@tauri-apps/api": ">=2.0.0"
   },
   "devDependencies": {
-    "@syncular/react": "0.15.15"
+    "@syncular/react": "0.15.17"
   }
 }

package/src/index.ts

@@ -30,6 +30,9 @@
 import type {
   ClientChangeBatch,
   ClientChangeListener,
+  ClientDiagnosticsListener,
+  ClientDiagnosticsRequest,
+  ClientDiagnosticsSnapshot,
   CommitOutcome,
   CommitOutcomeQuery,
   ConflictRecord,
@@ -56,7 +59,10 @@ import type {
 // -- 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';
+import {
+  SECURITY_PREFLIGHT_REQUIRED_CODE,
+  withClientDiagnosticsHost,
+} from '@syncular/client';
 
 /** A driver-protocol reply: `{result}` on success or `{error}` on failure. */
 interface CommandReply {
@@ -250,6 +256,7 @@ export class TauriSyncClient {
   readonly #tauri: TauriApi;
   readonly #invalidationListeners = new Set<InvalidationListener>();
   readonly #changeListeners = new Set<ClientChangeListener>();
+  readonly #diagnosticsListeners = new Set<ClientDiagnosticsListener>();
   readonly #presenceListeners = new Set<(scopeKey: string) => void>();
   #unlisten: (() => void) | undefined;
   #closed = false;
@@ -349,6 +356,18 @@ export class TauriSyncClient {
         }
         break;
       }
+      case 'diagnostics': {
+        const snapshot = decodeDiagnosticsSnapshot(event.snapshot, 'tauri');
+        if (snapshot === undefined) break;
+        for (const listener of this.#diagnosticsListeners) {
+          try {
+            listener(snapshot);
+          } catch {
+            /* a diagnostics observer must never break event dispatch */
+          }
+        }
+        break;
+      }
       default:
         // Unknown extension events are deliberately ignored. All durable
         // observable state arrives in the revisioned `change` batch.
@@ -414,6 +433,11 @@ export class TauriSyncClient {
     return () => this.#changeListeners.delete(listener);
   }
 
+  onDiagnostics(listener: ClientDiagnosticsListener): () => void {
+    this.#diagnosticsListeners.add(listener);
+    return () => this.#diagnosticsListeners.delete(listener);
+  }
+
   onPresence(listener: (scopeKey: string) => void): () => void {
     this.#presenceListeners.add(listener);
     return () => this.#presenceListeners.delete(listener);
@@ -470,6 +494,19 @@ export class TauriSyncClient {
     return (await this.#command('statusSnapshot', {})) as SyncStatusSnapshot;
   }
 
+  async diagnosticsSnapshot(
+    request: ClientDiagnosticsRequest = {},
+  ): Promise<ClientDiagnosticsSnapshot> {
+    const snapshot = (await this.#command('diagnosticsSnapshot', {
+      expectedSubscriptions: request.expectedSubscriptions ?? [],
+    })) as ClientDiagnosticsSnapshot;
+    return withClientDiagnosticsHost(snapshot, {
+      ...snapshot.host,
+      kind: 'tauri',
+      role: 'single',
+    });
+  }
+
   async mutate(mutations: readonly MutationInput[]): Promise<string> {
     const result = (await this.#command('mutate', {
       mutations: mutations.map(encodeMutation),
@@ -509,6 +546,7 @@ export class TauriSyncClient {
    * the realtime socket applies it on its next (re)connect.
    */
   async setHeaders(headers: Readonly<Record<string, string>>): Promise<void> {
+    this.#requireActive();
     const reply = await this.#tauri.invoke<CommandReply>(
       `${PLUGIN}syncular_set_headers`,
       { headers },
@@ -745,10 +783,25 @@ export class TauriSyncClient {
     this.#unlisten = undefined;
     this.#invalidationListeners.clear();
     this.#changeListeners.clear();
+    this.#diagnosticsListeners.clear();
     this.#presenceListeners.clear();
   }
 }
 
+function decodeDiagnosticsSnapshot(
+  value: unknown,
+  kind: 'tauri',
+): ClientDiagnosticsSnapshot | undefined {
+  if (value === null || typeof value !== 'object') return undefined;
+  const snapshot = value as ClientDiagnosticsSnapshot;
+  if (snapshot.version !== 1 || snapshot.host === undefined) return undefined;
+  return withClientDiagnosticsHost(snapshot, {
+    ...snapshot.host,
+    kind,
+    role: 'single',
+  });
+}
+
 /** The error a `{error}` reply surfaces (mirrors the web-client `ClientSyncError`). */
 export class TauriSyncError extends Error {
   readonly code: string;