@syncular/client 0.15.13 → 0.15.15

package/src/worker-entry.ts

@@ -143,7 +143,13 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
 
   function runAutoSync(): void {
     autoSyncScheduled = false;
-    if (closed || client === undefined) return;
+    if (
+      closed ||
+      client === undefined ||
+      client.securityLifecycle === 'preflight'
+    ) {
+      return;
+    }
     const running = client;
     void serializedSync(() => running.syncUntilIdle())
       .then((summary) => {
@@ -160,7 +166,13 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
   }
 
   function consumeSyncIntent(intent: SyncIntent): void {
-    if (!autoSync || closed || client === undefined || intent.kind === 'none') {
+    if (
+      !autoSync ||
+      closed ||
+      client === undefined ||
+      client.securityLifecycle === 'preflight' ||
+      intent.kind === 'none'
+    ) {
       return;
     }
     if (intent.kind === 'background') {
@@ -303,6 +315,9 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
       ...(config.encryption !== undefined
         ? { encryption: encryptionConfigFromKeyring(config.encryption) }
         : {}),
+      ...(config.securityPreflight !== undefined
+        ? { securityPreflight: config.securityPreflight }
+        : {}),
       onSyncNeeded: (reason) => {
         post({ t: 'event', event: { kind: 'sync-needed', reason } });
         consumeSyncIntent({ kind: 'interactive' });
@@ -344,6 +359,21 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
   }
 
   const api: WorkerApi = {
+    securityLifecycle: () => requireClient().securityLifecycle,
+    beginSecurityPreflight: async () => {
+      if (backgroundTimer !== undefined) clearTimeout(backgroundTimer);
+      backgroundTimer = undefined;
+      backgroundDue = Number.POSITIVE_INFINITY;
+      autoSyncScheduled = false;
+      await requireClient().beginSecurityPreflight();
+    },
+    activateSecurity: async (options = {}) => {
+      await requireClient().activateSecurity({
+        ...(options.encryption !== undefined
+          ? { encryption: encryptionConfigFromKeyring(options.encryption) }
+          : {}),
+      });
+    },
     subscribe: (input) => requireClient().subscribe(input),
     unsubscribe: (id) => requireClient().unsubscribe(id),
     setWindow: async (base, units) => {

package/src/worker-host.ts

@@ -32,6 +32,7 @@ import type {
   QuerySnapshot,
   RejectionRecord,
   SchemaFloor,
+  SecurityLifecycle,
   SubscribeInput,
   SyncClientLimits,
   SyncSummary,
@@ -62,6 +63,7 @@ import {
   type CrossTabChannel,
   FollowerLink,
   LeaderBridge,
+  type LeadershipState,
   multiTabChannelName,
   newTabId,
 } from './multi-tab';
@@ -86,11 +88,47 @@ import {
   type WorkerInitConfig,
   type WorkerInitResult,
   type WorkerMethod,
+  type WorkerSecurityActivation,
   type WorkerToMainMessage,
 } from './worker-protocol';
 
 export type HandleRole = 'leader' | 'follower';
 
+export type BrowserReplicaMode =
+  | { readonly mode: 'shared' }
+  | { readonly mode: 'isolated'; readonly id: string };
+
+export interface IsolatedReplicaNames {
+  readonly databaseName: string;
+  readonly databaseDirectory: string;
+  readonly lockName: string;
+  readonly channelName: string;
+}
+
+/** Derive the complete ownership tuple for an independently owned replica. */
+export function isolatedReplicaNames(options: {
+  readonly databaseName: string;
+  readonly databaseDirectory?: string;
+  readonly lockName?: string;
+  readonly replicaId: string;
+}): IsolatedReplicaNames {
+  if (!/^[A-Za-z0-9._-]+$/.test(options.replicaId)) {
+    throw new ClientSyncError(
+      'sync.invalid_request',
+      'an isolated replica id must contain only letters, numbers, dot, underscore, or dash',
+    );
+  }
+  const suffix = `--replica-${options.replicaId}`;
+  const databaseName = `${options.databaseName}${suffix}`;
+  const lockName = `${options.lockName ?? 'syncular-leader'}${suffix}`;
+  return {
+    databaseName,
+    databaseDirectory: `${options.databaseDirectory ?? `.syncular/${options.databaseName}`}${suffix}`,
+    lockName,
+    channelName: multiTabChannelName(lockName),
+  };
+}
+
 export interface SyncClientHandleConfig {
   /**
    * Spawns the worker running `startSyncWorker()` (a factory so bundlers
@@ -104,6 +142,8 @@ export interface SyncClientHandleConfig {
   readonly endpoints: WorkerEndpoints;
   /** Structured-clone-safe E2EE keyring installed only in the leader worker. */
   readonly encryption?: EncryptionKeyringConfig;
+  /** Open the worker-owned replica behind the fail-closed security gate. */
+  readonly securityPreflight?: boolean;
   readonly clientId?: string;
   readonly limits?: SyncClientLimits;
   /** Worker-side host loop (§8.4); default true. */
@@ -111,6 +151,8 @@ export interface SyncClientHandleConfig {
   /** Default: Web Locks when available, else single-owner. */
   readonly leaderLock?: LeaderLock;
   readonly lockName?: string;
+  /** Shared by default; isolated derives the database/lock/channel tuple. */
+  readonly replica?: BrowserReplicaMode;
   /**
    * Multi-tab followers (TODO 3.2). On by default: a tab that loses the
    * leader election becomes a FOLLOWER that proxies to the leader over a
@@ -125,6 +167,8 @@ export interface SyncClientHandleConfig {
   readonly followerCallTimeoutMs?: number;
   /** Fires when this handle's role changes (follower → leader on promotion). */
   readonly onRoleChange?: (role: HandleRole) => void;
+  /** Fires when reachability or ownership changes without replacing the handle. */
+  readonly onLeadershipChange?: (state: LeadershipState) => void;
   readonly onSyncNeeded?: (reason: 'startup' | 'hello' | WakeReason) => void;
   readonly onConflict?: (conflict: ConflictRecord) => void;
   /** A worker-side autoSync round finished (or failed). */
@@ -183,15 +227,28 @@ export class SyncClientHandle {
   get clientId(): string {
     return this.#clientId;
   }
+  get currentSchemaVersion(): number {
+    return this.#currentSchemaVersion;
+  }
+  get leadership(): LeadershipState {
+    return this.#leadership;
+  }
+
+  leadershipSnapshot(): LeadershipState {
+    return this.#leadership;
+  }
 
   #role: HandleRole;
   #clientId: string;
+  readonly #currentSchemaVersion: number;
+  #leadership: LeadershipState;
   #core: LeaderCore | undefined;
   #follower: FollowerLink | undefined;
   readonly #invalidation: InvalidationEmitter;
   readonly #changes: ChangeEmitter;
   readonly #presence: Set<(scopeKey: string) => void>;
   readonly #roleListeners: Set<(role: HandleRole) => void>;
+  readonly #leadershipListeners: Set<(state: LeadershipState) => void>;
   readonly #devtoolsUnregister: () => void;
   #closed = false;
 
@@ -199,21 +256,36 @@ export class SyncClientHandle {
   constructor(internals: {
     role: HandleRole;
     clientId: string;
+    currentSchemaVersion: number;
     core?: LeaderCore;
     follower?: FollowerLink;
     invalidation: InvalidationEmitter;
     changes: ChangeEmitter;
     presence: Set<(scopeKey: string) => void>;
     roleListeners?: Set<(role: HandleRole) => void>;
+    leadershipListeners?: Set<(state: LeadershipState) => void>;
+    leadership?: LeadershipState;
   }) {
     this.#role = internals.role;
     this.#clientId = internals.clientId;
+    this.#currentSchemaVersion = internals.currentSchemaVersion;
+    this.#leadership =
+      internals.leadership ??
+      (internals.role === 'leader'
+        ? { state: 'leader', clientId: internals.clientId }
+        : (internals.follower?.leadershipState ?? {
+            state: 'blocked',
+            reason: 'leader-unreachable',
+            code: 'client.follower_timeout',
+            retryable: true,
+          }));
     this.#core = internals.core;
     this.#follower = internals.follower;
     this.#invalidation = internals.invalidation;
     this.#changes = internals.changes;
     this.#presence = internals.presence;
     this.#roleListeners = internals.roleListeners ?? new Set();
+    this.#leadershipListeners = internals.leadershipListeners ?? new Set();
     // RFC 0002 §3.2: console introspection — a no-op outside a dev page.
     this.#devtoolsUnregister = registerDevtools({
       kind: 'handle',
@@ -237,6 +309,7 @@ export class SyncClientHandle {
     this.#core = core;
     this.#clientId = core.clientId;
     this.#role = 'leader';
+    this.__setLeadership({ state: 'leader', clientId: core.clientId });
     for (const listener of this.#roleListeners) {
       try {
         listener('leader');
@@ -246,6 +319,19 @@ export class SyncClientHandle {
     }
   }
 
+  /** @internal — apply a follower reachability snapshot in place. */
+  __setLeadership(state: LeadershipState): void {
+    this.#leadership = state;
+    if (state.state === 'follower') this.#clientId = state.leaderClientId;
+    for (const listener of this.#leadershipListeners) {
+      try {
+        listener(state);
+      } catch {
+        /* a UI listener must never break leadership transitions */
+      }
+    }
+  }
+
   /** @internal — dispatch a worker/relayed event to handle-local listeners. */
   __dispatchEvent(event: SyncWorkerEvent): void {
     if (event.kind === 'presence') {
@@ -296,6 +382,13 @@ export class SyncClientHandle {
     };
   }
 
+  onLeadershipChange(listener: (state: LeadershipState) => void): () => void {
+    this.#leadershipListeners.add(listener);
+    return () => {
+      this.#leadershipListeners.delete(listener);
+    };
+  }
+
   #call<M extends WorkerMethod>(
     method: M,
     args: Parameters<WorkerApi[M]>,
@@ -334,6 +427,18 @@ export class SyncClientHandle {
     return this.#call('subscribe', [input]);
   }
 
+  securityLifecycle(): Promise<SecurityLifecycle> {
+    return this.#call('securityLifecycle', []);
+  }
+
+  beginSecurityPreflight(): Promise<void> {
+    return this.#call('beginSecurityPreflight', []);
+  }
+
+  activateSecurity(options: WorkerSecurityActivation = {}): Promise<void> {
+    return this.#call('activateSecurity', [options]);
+  }
+
   unsubscribe(id: string): Promise<void> {
     return this.#call('unsubscribe', [id]);
   }
@@ -635,6 +740,9 @@ function buildInitConfig(config: SyncClientHandleConfig): WorkerInitConfig {
     ...(config.encryption !== undefined
       ? { encryption: config.encryption }
       : {}),
+    ...(config.securityPreflight !== undefined
+      ? { securityPreflight: config.securityPreflight }
+      : {}),
     ...(config.clientId !== undefined ? { clientId: config.clientId } : {}),
     ...(config.limits !== undefined ? { limits: config.limits } : {}),
     ...(config.autoSync !== undefined ? { autoSync: config.autoSync } : {}),
@@ -672,13 +780,19 @@ function fireConfigCallbacks(
 export async function createSyncClientHandle(
   config: SyncClientHandleConfig,
 ): Promise<SyncClientHandle> {
-  const lock = config.leaderLock ?? defaultLeaderLock();
-  const lockName = config.lockName ?? 'syncular-leader';
+  const resolvedConfig = resolveReplicaConfig(config);
+  const lock = resolvedConfig.leaderLock ?? defaultLeaderLock();
+  const lockName = resolvedConfig.lockName ?? 'syncular-leader';
   const invalidation = new InvalidationEmitter();
   const changes = new ChangeEmitter();
   const presence = new Set<(scopeKey: string) => void>();
   const roleListeners = new Set<(role: HandleRole) => void>();
-  if (config.onRoleChange !== undefined) roleListeners.add(config.onRoleChange);
+  if (resolvedConfig.onRoleChange !== undefined)
+    roleListeners.add(resolvedConfig.onRoleChange);
+  const leadershipListeners = new Set<(state: LeadershipState) => void>();
+  if (resolvedConfig.onLeadershipChange !== undefined) {
+    leadershipListeners.add(resolvedConfig.onLeadershipChange);
+  }
 
   // Leadership BEFORE the worker exists: one core per origin, and a losing
   // tab never boots a database it must not own.
@@ -692,34 +806,38 @@ export async function createSyncClientHandle(
     // Epoch derivation for a fresh boot: epoch 0. A promoter (below) reads
     // the highest epoch it has seen and adds one, so leaders monotonically
     // increase it across handovers.
-    return await bootLeader(config, lockName, lease, {
+    return await bootLeader(resolvedConfig, lockName, lease, {
       epoch: 0,
       invalidation,
       changes,
       presence,
       roleListeners,
+      leadershipListeners,
     });
   }
 
   // ---- Lost the election. ----
-  if (config.multiTab === false) {
+  if (resolvedConfig.multiTab === false) {
     // Opted-out single-tab contract: a dead not-leader handle.
     return new SyncClientHandle({
       role: 'follower',
       clientId: '',
+      currentSchemaVersion: resolvedConfig.schema.version,
       invalidation,
       changes,
       presence,
       roleListeners,
+      leadershipListeners,
     });
   }
 
   // ---- Follower: proxy to the leader; contest + promote on its close. ----
-  return await bootFollower(config, lockName, lock, {
+  return await bootFollower(resolvedConfig, lockName, lock, {
     invalidation,
     changes,
     presence,
     roleListeners,
+    leadershipListeners,
   });
 }
 
@@ -729,6 +847,7 @@ interface HandleParts {
   changes: ChangeEmitter;
   presence: Set<(scopeKey: string) => void>;
   roleListeners: Set<(role: HandleRole) => void>;
+  leadershipListeners: Set<(state: LeadershipState) => void>;
 }
 
 /** Boot (or promote to) a leader: spawn the worker, wire the bridge. */
@@ -761,6 +880,10 @@ async function bootLeader(
             epoch: parts.epoch ?? 0,
             clientId,
             invoke,
+            heartbeatMs: Math.max(
+              10,
+              Math.floor((config.followerCallTimeoutMs ?? 10_000) / 3),
+            ),
           });
         }
       : undefined;
@@ -776,11 +899,13 @@ async function bootLeader(
   const handle = new SyncClientHandle({
     role: 'leader',
     clientId: core.clientId,
+    currentSchemaVersion: config.schema.version,
     core,
     invalidation: parts.invalidation,
     changes: parts.changes,
     presence: parts.presence,
     roleListeners: parts.roleListeners,
+    leadershipListeners: parts.leadershipListeners,
   });
   handleRef.handle = handle;
   return handle;
@@ -811,6 +936,7 @@ async function bootFollower(
       // it after binding). Nothing else to do — calls already flush.
       void clientId;
     },
+    onStateChange: (state) => handleRef.handle?.__setLeadership(state),
     ...(config.followerCallTimeoutMs !== undefined
       ? { callTimeoutMs: config.followerCallTimeoutMs }
       : {}),
@@ -855,6 +981,10 @@ async function bootFollower(
                   epoch: nextEpoch,
                   clientId,
                   invoke,
+                  heartbeatMs: Math.max(
+                    10,
+                    Math.floor((config.followerCallTimeoutMs ?? 10_000) / 3),
+                  ),
                 });
               },
             }
@@ -874,11 +1004,13 @@ async function bootFollower(
     // leave '' until promotion (the shared id is the leader's — hooks that
     // need it read it after a round). Followers rarely need clientId directly.
     clientId: '',
+    currentSchemaVersion: config.schema.version,
     follower,
     invalidation: parts.invalidation,
     changes: parts.changes,
     presence: parts.presence,
     roleListeners: parts.roleListeners,
+    leadershipListeners: parts.leadershipListeners,
   });
   handleRef.handle = handle;
   // Do not hand back a follower until its link has bound to the leader (the
@@ -894,5 +1026,41 @@ async function bootFollower(
   } catch {
     /* bind timed out — return the (degraded but functional) handle anyway */
   }
+  // Init configuration belongs to the one leader worker. A newly opened
+  // follower that explicitly requests security preflight must therefore put
+  // the shared origin replica behind the same barrier before it is returned;
+  // otherwise an already-running leader would silently ignore the request.
+  if (config.securityPreflight === true) {
+    await handle.beginSecurityPreflight();
+  }
   return handle;
 }
+
+function resolveReplicaConfig(
+  config: SyncClientHandleConfig,
+): SyncClientHandleConfig {
+  if (config.replica?.mode !== 'isolated') return config;
+  if (config.database.mode !== 'persistent') {
+    throw new ClientSyncError(
+      'sync.invalid_request',
+      'isolated browser replicas require a named persistent database',
+    );
+  }
+  const names = isolatedReplicaNames({
+    databaseName: config.database.name,
+    ...(config.database.directory !== undefined
+      ? { databaseDirectory: config.database.directory }
+      : {}),
+    ...(config.lockName !== undefined ? { lockName: config.lockName } : {}),
+    replicaId: config.replica.id,
+  });
+  return {
+    ...config,
+    lockName: names.lockName,
+    database: {
+      ...config.database,
+      name: names.databaseName,
+      directory: names.databaseDirectory,
+    },
+  };
+}

package/src/worker-protocol.ts

@@ -27,6 +27,7 @@ import type {
   QuerySnapshot,
   RejectionRecord,
   SchemaFloor,
+  SecurityLifecycle,
   SubscribeInput,
   SyncClientLimits,
   SyncSummary,
@@ -100,6 +101,8 @@ export interface WorkerInitConfig {
   readonly endpoints: WorkerEndpoints;
   /** 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 securityPreflight?: boolean;
   readonly clientId?: string;
   readonly limits?: SyncClientLimits;
   /**
@@ -115,11 +118,19 @@ export interface WorkerInitResult {
   readonly clientId: string;
 }
 
+/** Structured-clone-safe key material installed at security activation. */
+export interface WorkerSecurityActivation {
+  readonly encryption?: EncryptionKeyringConfig;
+}
+
 // ---------------------------------------------------------------------------
 // The logical API — the one shared shape (worker implements, handle projects)
 // ---------------------------------------------------------------------------
 
 export interface WorkerApi {
+  securityLifecycle(): SecurityLifecycle;
+  beginSecurityPreflight(): Promise<void>;
+  activateSecurity(options?: WorkerSecurityActivation): Promise<void>;
   subscribe(input: SubscribeInput): void;
   unsubscribe(id: string): void;
   /** §4.8 windowed subscriptions: set the live units for a window base. */