@syncular/react 0.15.14 → 0.15.15

package/README.md

@@ -101,6 +101,27 @@ const clientResource = createSyncClientResource(() => createClient());
 Call `await clientResource.dispose()` from the application's real lifecycle
 owner, not from a StrictMode-sensitive child effect.
 
+If the application requires authentication or signed quarantine processing
+before protected data is visible, complete the concrete client's security
+preflight before returning it from the resource factory. Do not mount the
+ordinary provider tree while `securityLifecycle` is `preflight`: reactive store
+startup intentionally touches protected status/outcome/query surfaces.
+
+```ts
+const clientResource = createSyncClientResource(async () => {
+  const client = await createClient({ securityPreflight: true });
+  await applyValidatedLocalPurge(client);
+  await client.activateSecurity({ encryption: acceptedKeyring });
+  return client;
+});
+```
+
+The normalized client exposes `securityLifecycle()`,
+`beginSecurityPreflight()`, and keyless `activateSecurity()` for host-agnostic
+coordination. Key-bearing activation stays on each concrete client type because
+direct TypeScript uses an `EncryptionConfig`, while Worker/Tauri/React Native
+use the portable keyring.
+
 Use `renderBoundary` as the canonical application guard across browser and
 native hosts. It covers resource startup/errors, migration, client upgrade,
 server-behind, incompatible-schema, and unreachable-leader states. The

package/dist/client.d.ts

@@ -11,7 +11,7 @@
  * value → read it) and wraps every result in `Promise.resolve`, so a hook
  * never has to care which core it holds.
  */
-import type { ClientChangeListener, CommitOutcome, CommitOutcomeQuery, ConflictRecord, InvalidationListener, LeadershipState, LeaseState, LocalDataPurgeInput, LocalDataPurgeResult, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, ResolveCommitOutcomeInput, SchemaFloor, SqlRow, SqlValue, SyncStatusSnapshot, WindowBase, WindowState } from '@syncular/client';
+import type { ClientChangeListener, CommitOutcome, CommitOutcomeQuery, ConflictRecord, InvalidationListener, LeadershipState, LeaseState, LocalDataPurgeInput, LocalDataPurgeResult, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, ResolveCommitOutcomeInput, SchemaFloor, SecurityLifecycle, SqlRow, SqlValue, SyncStatusSnapshot, WindowBase, WindowState } from '@syncular/client';
 /**
  * The structural union of `SyncClient` and `SyncClientHandle`. Members that
  * diverge are typed as "value or method, sync or promise"; {@link normalizeClient}
@@ -25,6 +25,10 @@ export interface SyncClientLike {
     onPresence(listener: (scopeKey: string) => void): () => void;
     onLeadershipChange?(listener: (state: LeadershipState) => void): () => void;
     leadershipSnapshot?(): LeadershipState | undefined;
+    securityLifecycle: SecurityLifecycle | (() => SecurityLifecycle | Promise<SecurityLifecycle>);
+    beginSecurityPreflight(): void | Promise<void>;
+    /** Key-bearing activation remains available on each concrete host type. */
+    activateSecurity(): void | Promise<void>;
     query(sql: string, params?: readonly SqlValue[]): SqlRow[] | Promise<SqlRow[]>;
     mutate(mutations: readonly MutationInput[]): string | Promise<string>;
     patch(table: string, rowId: string, partial: Readonly<Record<string, unknown>>, options?: {
@@ -58,6 +62,10 @@ export interface NormalizedClient {
     onPresence(listener: (scopeKey: string) => void): () => void;
     onLeadershipChange(listener: (state: LeadershipState) => void): () => void;
     leadershipSnapshot(): LeadershipState | undefined;
+    securityLifecycle(): Promise<SecurityLifecycle>;
+    beginSecurityPreflight(): Promise<void>;
+    /** Key-bearing activation remains available on each concrete host type. */
+    activateSecurity(): Promise<void>;
     query(sql: string, params?: readonly SqlValue[]): Promise<SqlRow[]>;
     mutate(mutations: readonly MutationInput[]): Promise<string>;
     patch(table: string, rowId: string, partial: Readonly<Record<string, unknown>>, options?: {

package/dist/client.js

@@ -20,6 +20,9 @@ export function normalizeClient(client) {
         onPresence: (listener) => client.onPresence(listener),
         onLeadershipChange: (listener) => client.onLeadershipChange?.(listener) ?? (() => { }),
         leadershipSnapshot: () => client.leadershipSnapshot?.(),
+        securityLifecycle: () => resolveMember(client, 'securityLifecycle'),
+        beginSecurityPreflight: () => Promise.resolve(client.beginSecurityPreflight()),
+        activateSecurity: () => Promise.resolve(client.activateSecurity()),
         query: (sql, params) => Promise.resolve(client.query(sql, params)),
         mutate: (mutations) => Promise.resolve(client.mutate(mutations)),
         patch: (table, rowId, partial, options) => Promise.resolve(client.patch(table, rowId, partial, options)),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/react",
-  "version": "0.15.14",
+  "version": "0.15.15",
   "description": "React hooks for Syncular offline-first sync",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -48,15 +48,15 @@
     "test": "bun test --preload ./test/setup.ts"
   },
   "dependencies": {
-    "@syncular/client": "0.15.14"
+    "@syncular/client": "0.15.15"
   },
   "peerDependencies": {
     "react": ">=18.0.0"
   },
   "devDependencies": {
-    "@happy-dom/global-registrator": "^15.11.0",
-    "@syncular/core": "0.15.14",
-    "@syncular/server": "0.15.14",
+    "@happy-dom/global-registrator": "^20.0.0",
+    "@syncular/core": "0.15.15",
+    "@syncular/server": "0.15.15",
     "@testing-library/react": "^16.1.0",
     "@types/react": "^18.3.0",
     "react": "^18.3.1",

package/src/client.ts

@@ -28,6 +28,7 @@ import type {
   RejectionRecord,
   ResolveCommitOutcomeInput,
   SchemaFloor,
+  SecurityLifecycle,
   SqlRow,
   SqlValue,
   SyncStatusSnapshot,
@@ -48,6 +49,12 @@ export interface SyncClientLike {
   onPresence(listener: (scopeKey: string) => void): () => void;
   onLeadershipChange?(listener: (state: LeadershipState) => void): () => void;
   leadershipSnapshot?(): LeadershipState | undefined;
+  securityLifecycle:
+    | SecurityLifecycle
+    | (() => SecurityLifecycle | Promise<SecurityLifecycle>);
+  beginSecurityPreflight(): void | Promise<void>;
+  /** Key-bearing activation remains available on each concrete host type. */
+  activateSecurity(): void | Promise<void>;
   query(
     sql: string,
     params?: readonly SqlValue[],
@@ -130,6 +137,10 @@ export interface NormalizedClient {
   onPresence(listener: (scopeKey: string) => void): () => void;
   onLeadershipChange(listener: (state: LeadershipState) => void): () => void;
   leadershipSnapshot(): LeadershipState | undefined;
+  securityLifecycle(): Promise<SecurityLifecycle>;
+  beginSecurityPreflight(): Promise<void>;
+  /** Key-bearing activation remains available on each concrete host type. */
+  activateSecurity(): Promise<void>;
   query(sql: string, params?: readonly SqlValue[]): Promise<SqlRow[]>;
   mutate(mutations: readonly MutationInput[]): Promise<string>;
   patch(
@@ -173,6 +184,10 @@ export function normalizeClient(client: SyncClientLike): NormalizedClient {
     onLeadershipChange: (listener) =>
       client.onLeadershipChange?.(listener) ?? (() => {}),
     leadershipSnapshot: () => client.leadershipSnapshot?.(),
+    securityLifecycle: () => resolveMember(client, 'securityLifecycle'),
+    beginSecurityPreflight: () =>
+      Promise.resolve(client.beginSecurityPreflight()),
+    activateSecurity: () => Promise.resolve(client.activateSecurity()),
     query: (sql, params) => Promise.resolve(client.query(sql, params)),
     mutate: (mutations) => Promise.resolve(client.mutate(mutations)),
     patch: (table, rowId, partial, options) =>