@syncular/client 0.15.14 → 0.15.16

package/README.md

@@ -232,6 +232,28 @@ subscription that could download the protected rows again. This method does
 not authenticate a directive, revoke server authority, delete app-owned files,
 or remove a key from the OS secure store.
 
+For a race-free bootstrap, construct the client/worker handle with
+`securityPreflight: true`. Before activation, protected reads, writes,
+subscriptions, sync/realtime, blobs, and the automatic host loop fail with
+`client.security_preflight_required`; status, local revision, lifecycle, and
+the exact local purge remain available.
+
+```ts
+const client = await createSyncClientHandle({
+  ...config,
+  securityPreflight: true,
+});
+
+await client.purgeLocalData(directive.plan);
+await client.activateSecurity({ encryption: acceptedKeyring });
+```
+
+Use `beginSecurityPreflight()` before a live key rotation/revocation. It gates
+new calls immediately, disconnects realtime, waits for in-flight core/blob work,
+and releases the old keyring before resolving. In multi-tab mode the gate
+belongs to the single shared leader replica. Direct clients expose the same
+lifecycle with an `EncryptionConfig`; Worker handles use the portable keyring.
+
 Within one local SQLite transaction the engine deletes exactly the matching
 synced rows, lets generated FTS triggers remove their projections, drops every
 whole pending commit with a matching operation, restores/replays unrelated

package/dist/client.d.ts

@@ -147,6 +147,25 @@ export interface SyncClientConfig {
      * `client.decrypt_failed`, never silent plaintext).
      */
     readonly encryption?: EncryptionConfig;
+    /**
+     * Open the local replica in the fail-closed security preflight state.
+     *
+     * Preflight opens/migrates the database but suppresses every protected read,
+     * mutation, subscription, transport, realtime, presence, and blob operation.
+     * Only lifecycle/status inspection and `purgeLocalData` remain available.
+     * Install the post-authentication keyring and release the gate with
+     * `activateSecurity`. This is mutually exclusive with `encryption`: secure
+     * hosts must not materialize key bytes before their preflight has passed.
+     */
+    readonly securityPreflight?: boolean;
+}
+/** The fail-closed local-replica security lifecycle shared by every host. */
+export type SecurityLifecycle = 'preflight' | 'active';
+/** Stable client-local error while protected operations are preflight-gated. */
+export declare const SECURITY_PREFLIGHT_REQUIRED_CODE = "client.security_preflight_required";
+/** Key material installed atomically when a direct client becomes active. */
+export interface SecurityActivation {
+    readonly encryption?: EncryptionConfig;
 }
 /** §8.6 a peer's ephemeral presence document on a scope key. */
 export interface PresencePeer {
@@ -216,6 +235,20 @@ export declare class SyncClient {
     /** Acquire leadership, create local tables, resolve the clientId. */
     start(): Promise<void>;
     close(): Promise<void>;
+    /** Current fail-closed local-replica security state. */
+    get securityLifecycle(): SecurityLifecycle;
+    /**
+     * Block new protected operations immediately, then wait for every already
+     * serialized database/network operation to settle before releasing key
+     * references. Hosts await this barrier before applying a quarantine purge.
+     */
+    beginSecurityPreflight(): Promise<void>;
+    /**
+     * Atomically install the post-authentication keyring and release the gate.
+     * Persisted subscriptions/outbox work produces one exact startup intent only
+     * after activation, never while the local quarantine decision is pending.
+     */
+    activateSecurity(options?: SecurityActivation): Promise<void>;
     get clientId(): string;
     /** The underlying database — raw SQL is the local query API (B3). */
     get database(): ClientDatabase;

package/dist/client.js

@@ -21,6 +21,8 @@ import { assertReadOnlyQuery } from './query-guard.js';
 import { compileClientSchema, dropAndRecreateSyncedTables, ensureLocalBookkeepingSchema, ensureLocalSyncedSchema, fromSqlValue, jsonToRowValue, LOCAL_SCHEMA_VERSION_KEY, normalizeRecordKeys, OPTIMISTIC_VERSION, quoteIdent, recordToRowValues, rowValueToJson, SYNC_VERSION_COLUMN, stripSyncColumns, } from './schema.js';
 import { bumpLocalRevision, deleteSubscription, getLocalRevision, getMeta, getSubscription, loadSubscriptions, pruneUnknownSubscriptions, resetSubscriptionsForBump, saveSubscription, setMeta, } from './state.js';
 import { deletePendingEviction, deleteWindowUnit, deriveSubId, getWindowUnitBySubId, insertWindowUnit, loadPendingEvictions, loadWindowUnits, savePendingEviction, unitScopes, windowBaseKey, } from './window.js';
+/** Stable client-local error while protected operations are preflight-gated. */
+export const SECURITY_PREFLIGHT_REQUIRED_CODE = 'client.security_preflight_required';
 /**
  * True iff `unit` is windowed-in AND its bootstrap completed (§4.8 I3):
  * registered and not pending. A unit with zero server rows still becomes
@@ -72,6 +74,7 @@ export class SyncClient {
     #schema;
     /** §5.11 client-side encryption config; undefined ⇒ E2EE off. */
     #encryption;
+    #securityLifecycle;
     #now;
     #outcomeRetentionMaxEntries;
     #started = false;
@@ -124,11 +127,21 @@ export class SyncClient {
      * sections, when the seam is quiescent.
      */
     #opChain = Promise.resolve();
+    /** Async protected operations outside the SQLite serialization chain
+     * (blob I/O and realtime connect). Security preflight waits for this set to
+     * drain after synchronously closing the gate. */
+    #protectedAsync = new Set();
+    #preflightBarrier;
     constructor(config) {
+        if (config.securityPreflight === true && config.encryption !== undefined) {
+            throw new ClientSyncError('sync.invalid_request', 'securityPreflight and encryption are mutually exclusive; install keys with activateSecurity after preflight');
+        }
         this.#config = config;
         this.#db = config.database;
         this.#schema = compileClientSchema(config.schema);
         this.#encryption = config.encryption;
+        this.#securityLifecycle =
+            config.securityPreflight === true ? 'preflight' : 'active';
         this.#now = config.now ?? Date.now;
         const outcomeRetentionMaxEntries = config.limits?.outcomeRetentionMaxEntries ?? 1_000;
         if (!Number.isSafeInteger(outcomeRetentionMaxEntries) ||
@@ -192,7 +205,7 @@ export class SyncClient {
         const startupWork = this.#schemaFloor === undefined &&
             (listOutbox(this.#db).length > 0 ||
                 subscriptions.some((sub) => sub.status === 'active'));
-        if (startupWork) {
+        if (startupWork && this.#securityLifecycle === 'active') {
             this.#needsPull = true;
             this.#config.onSyncNeeded?.('startup');
             this.#config.onSyncIntent?.({ kind: 'interactive' });
@@ -294,12 +307,66 @@ export class SyncClient {
         this.#lease = undefined;
         this.#started = false;
     }
+    /** Current fail-closed local-replica security state. */
+    get securityLifecycle() {
+        return this.#securityLifecycle;
+    }
+    /**
+     * Block new protected operations immediately, then wait for every already
+     * serialized database/network operation to settle before releasing key
+     * references. Hosts await this barrier before applying a quarantine purge.
+     */
+    beginSecurityPreflight() {
+        this.#requireStarted();
+        if (this.#preflightBarrier !== undefined)
+            return this.#preflightBarrier;
+        this.#securityLifecycle = 'preflight';
+        this.disconnectRealtime();
+        const barrier = (async () => {
+            await Promise.allSettled([this.#opChain, ...this.#protectedAsync]);
+            this.disconnectRealtime();
+            this.#encryption = undefined;
+            this.#syncOutstanding = false;
+        })();
+        this.#preflightBarrier = barrier;
+        void barrier.then(() => {
+            if (this.#preflightBarrier === barrier)
+                this.#preflightBarrier = undefined;
+        }, () => {
+            if (this.#preflightBarrier === barrier)
+                this.#preflightBarrier = undefined;
+        });
+        return barrier;
+    }
+    /**
+     * Atomically install the post-authentication keyring and release the gate.
+     * Persisted subscriptions/outbox work produces one exact startup intent only
+     * after activation, never while the local quarantine decision is pending.
+     */
+    async activateSecurity(options = {}) {
+        this.#requireStarted();
+        if (this.#securityLifecycle === 'active') {
+            throw new ClientSyncError('sync.invalid_request', 'activateSecurity requires the client to be in security preflight');
+        }
+        await (this.#preflightBarrier ?? this.#opChain);
+        this.#encryption = options.encryption;
+        this.#securityLifecycle = 'active';
+        const startupWork = this.#schemaFloor === undefined &&
+            (listOutbox(this.#db).length > 0 ||
+                loadSubscriptions(this.#db).some((sub) => sub.status === 'active'));
+        if (startupWork) {
+            this.#setSyncNeeded(true);
+            this.#config.onSyncNeeded?.('startup');
+            this.#config.onSyncIntent?.({ kind: 'interactive' });
+        }
+    }
     // -- accessors ------------------------------------------------------------
     get clientId() {
         return this.#clientId;
     }
     /** The underlying database — raw SQL is the local query API (B3). */
     get database() {
+        this.#requireActive();
         return this.#db;
     }
     /**
@@ -311,6 +378,7 @@ export class SyncClient {
      * internals read `this.#db` directly and skip this method by design.
      */
     query(sql, params) {
+        this.#requireActive();
         assertReadOnlyQuery(sql);
         return stripSyncColumns(this.#db.query(sql, params));
     }
@@ -325,7 +393,7 @@ export class SyncClient {
      * `windowState()` across separate worker/IPC calls.
      */
     querySnapshot(spec) {
-        this.#requireStarted();
+        this.#requireActive();
         assertReadOnlyQuery(spec.sql);
         return this.#db.transaction(() => {
             const revision = getLocalRevision(this.#db);
@@ -456,6 +524,13 @@ export class SyncClient {
         this.#opChain = next.then(() => undefined, () => undefined);
         return next;
     }
+    #runProtectedAsync(fn) {
+        this.#requireActive();
+        const task = Promise.resolve().then(fn);
+        this.#protectedAsync.add(task);
+        void task.then(() => this.#protectedAsync.delete(task), () => this.#protectedAsync.delete(task));
+        return task;
+    }
     // -- blobs (§5.9) ---------------------------------------------------------
     /**
      * Stage a blob for attachment (§5.9.7): hash the bytes into the content
@@ -464,7 +539,10 @@ export class SyncClient {
      * a `blob_ref` column of a mutation. The referencing row MUST be written
      * (via `mutate`) after this call so upload-before-push holds (§5.9.3).
      */
-    async uploadBlob(bytes, options) {
+    uploadBlob(bytes, options) {
+        return this.#runProtectedAsync(() => this.#uploadBlob(bytes, options));
+    }
+    async #uploadBlob(bytes, options) {
         if (this.#config.blobs === undefined) {
             throw new ClientSyncError('sync.invalid_request', 'uploadBlob requires a blob transport (SyncClientConfig.blobs, §5.9)');
         }
@@ -496,7 +574,10 @@ export class SyncClient {
      * transport (§5.9.5), verifies the content address, caches, and returns.
      * Accepts a raw `blob_ref` column string or a bare `blobId`.
      */
-    async fetchBlob(blobIdOrRef) {
+    fetchBlob(blobIdOrRef) {
+        return this.#runProtectedAsync(() => this.#fetchBlob(blobIdOrRef));
+    }
+    async #fetchBlob(blobIdOrRef) {
         const blobId = blobIdOrRef.startsWith('sha256:')
             ? blobIdOrRef
             : parseBlobRef(blobIdOrRef).blobId;
@@ -550,7 +631,10 @@ export class SyncClient {
         enforceBlobCacheCap(this.#db, cap);
     }
     /** Flush any queued blob uploads (§5.9.7 B4); safe to call standalone. */
-    async flushBlobUploads() {
+    flushBlobUploads() {
+        return this.#runProtectedAsync(() => this.#flushBlobUploads());
+    }
+    async #flushBlobUploads() {
         const transport = this.#config.blobs;
         if (transport === undefined || !this.#hasBlobs)
             return;
@@ -598,19 +682,21 @@ export class SyncClient {
         await transport.upload(blobId, bytes, mediaType);
     }
     get conflicts() {
+        this.#requireActive();
         return this.#conflicts;
     }
     get rejections() {
+        this.#requireActive();
         return this.#rejections;
     }
     /** One durable final outcome by the originating client commit id. */
     commitOutcome(clientCommitId) {
-        this.#requireStarted();
+        this.#requireActive();
         return readCommitOutcome(this.#db, clientCommitId);
     }
     /** Newest-first durable outcome journal. */
     commitOutcomes(query = {}) {
-        this.#requireStarted();
+        this.#requireActive();
         return listCommitOutcomes(this.#db, query);
     }
     /**
@@ -620,7 +706,7 @@ export class SyncClient {
      * dismissed. The transition is one-way and survives restart.
      */
     resolveCommitOutcome(input) {
-        this.#requireStarted();
+        this.#requireActive();
         const current = readCommitOutcome(this.#db, input.clientCommitId);
         if (current === undefined) {
             throw new ClientSyncError('sync.outcome_not_found', `no durable outcome exists for ${JSON.stringify(input.clientCommitId)}`);
@@ -704,11 +790,13 @@ export class SyncClient {
      * Ephemeral — reflects only what the socket has delivered.
      */
     presence(scopeKey) {
+        this.#requireActive();
         const peers = this.#presence.get(scopeKey);
         return peers === undefined ? [] : [...peers.values()];
     }
     /** Every scope key this client currently has presence state for. */
     presenceKeys() {
+        this.#requireActive();
         return [...this.#presence.keys()];
     }
     /**
@@ -731,7 +819,7 @@ export class SyncClient {
      * by the server with `presence.forbidden`.
      */
     setPresence(scopeKey, doc) {
-        this.#requireStarted();
+        this.#requireActive();
         const socket = this.#socket;
         if (socket === undefined) {
             throw new ClientSyncError('sync.invalid_request', 'setPresence requires a connected realtime socket (§8.6)');
@@ -757,20 +845,20 @@ export class SyncClient {
             (urlCapable ? ACCEPT_SIGNED_URLS : 0));
     }
     subscriptions() {
-        this.#requireStarted();
+        this.#requireActive();
         return loadSubscriptions(this.#db);
     }
     subscription(id) {
-        this.#requireStarted();
+        this.#requireActive();
         return getSubscription(this.#db, id);
     }
     pendingCommits() {
-        this.#requireStarted();
+        this.#requireActive();
         return listOutbox(this.#db);
     }
     // -- subscriptions ----------------------------------------------------------
     subscribe(input) {
-        this.#requireStarted();
+        this.#requireActive();
         if (!this.#schema.tables.has(input.table)) {
             throw new ClientSyncError('sync.unknown_table', `subscribe: unknown local table ${JSON.stringify(input.table)}`);
         }
@@ -794,7 +882,7 @@ export class SyncClient {
         });
     }
     unsubscribe(id) {
-        this.#requireStarted();
+        this.#requireActive();
         deleteSubscription(this.#db, id);
     }
     // -- windowed subscriptions (§4.8) ------------------------------------------
@@ -816,7 +904,7 @@ export class SyncClient {
     }
     /** Exact core command result consumed by automatic host loops (§7.5). */
     async setWindowCommand(base, units) {
-        this.#requireStarted();
+        this.#requireActive();
         const table = this.#table(base.table);
         if (!table.scopeColumnByVariable.has(base.variable)) {
             throw new ClientSyncError('sync.invalid_request', `setWindow: table ${JSON.stringify(base.table)} has no scope variable ${JSON.stringify(base.variable)} (§4.8)`);
@@ -879,7 +967,7 @@ export class SyncClient {
      * advances past -1 with no resume token held).
      */
     windowState(base) {
-        this.#requireStarted();
+        this.#requireActive();
         const baseKey = windowBaseKey(base);
         const live = loadWindowUnits(this.#db, baseKey);
         const pending = [];
@@ -978,7 +1066,7 @@ export class SyncClient {
         return this.#recordMutations(mutations);
     }
     #recordMutations(mutations, changedFieldsByIndex = []) {
-        this.#requireStarted();
+        this.#requireActive();
         const clientCommitId = crypto.randomUUID();
         const operations = mutations.map((mutation, index) => {
             const table = this.#table(mutation.table);
@@ -1039,7 +1127,7 @@ export class SyncClient {
      * an error — there is no base to merge into.
      */
     patch(table, rowId, partial, options) {
-        this.#requireStarted();
+        this.#requireActive();
         const compiled = this.#table(table);
         const pkColumn = compiled.columns[compiled.primaryKeyIndex];
         const rows = this.#db.query(`SELECT * FROM ${quoteIdent(compiled.name)} WHERE ${quoteIdent(pkColumn.name)} = ?`, [rowId]);
@@ -1310,7 +1398,7 @@ export class SyncClient {
      * `setWindow` at an await point.
      */
     sync() {
-        this.#requireStarted();
+        this.#requireActive();
         if (this.#syncOutstanding) {
             return Promise.reject(new ClientSyncError('sync.invalid_request', 'sync() is already running — the core owns one loop (coalesce wake-ups)'));
         }
@@ -1489,13 +1577,15 @@ export class SyncClient {
         round.reject(new ClientSyncError('sync.transport_failed', reason, true));
     }
     // -- realtime (§8 client side) ----------------------------------------------
-    async connectRealtime() {
-        this.#requireStarted();
+    connectRealtime() {
+        return this.#runProtectedAsync(() => this.#connectRealtime());
+    }
+    async #connectRealtime() {
         const connector = this.#config.realtime;
         if (connector === undefined) {
             throw new ClientSyncError('sync.invalid_request', 'no realtime connector configured');
         }
-        this.#socket = await connector({
+        const socket = await connector({
             onText: (text) => this.#handleRealtimeText(text),
             onBinary: (bytes) => this.#routeRealtimeBinary(bytes),
             onClose: () => {
@@ -1504,6 +1594,11 @@ export class SyncClient {
                 this.#abortPendingRound('realtime socket closed mid-round (§8.7)');
             },
         });
+        if (this.#securityLifecycle === 'preflight') {
+            socket.close();
+            throw new ClientSyncError(SECURITY_PREFLIGHT_REQUIRED_CODE, 'realtime connected after the client entered security preflight');
+        }
+        this.#socket = socket;
     }
     disconnectRealtime() {
         this.#socket?.close();
@@ -2410,4 +2505,10 @@ export class SyncClient {
             throw new ClientSyncError('sync.invalid_request', 'SyncClient.start() has not completed');
         }
     }
+    #requireActive() {
+        this.#requireStarted();
+        if (this.#securityLifecycle === 'preflight') {
+            throw new ClientSyncError(SECURITY_PREFLIGHT_REQUIRED_CODE, 'the local replica is in security preflight; complete quarantine checks and call activateSecurity before accessing protected data');
+        }
+    }
 }

package/dist/worker-entry.js

@@ -88,8 +88,11 @@ export function startSyncWorker(overrides = {}) {
     let backgroundDue = Number.POSITIVE_INFINITY;
     function runAutoSync() {
         autoSyncScheduled = false;
-        if (closed || client === undefined)
+        if (closed ||
+            client === undefined ||
+            client.securityLifecycle === 'preflight') {
             return;
+        }
         const running = client;
         void serializedSync(() => running.syncUntilIdle())
             .then((summary) => {
@@ -106,7 +109,11 @@ export function startSyncWorker(overrides = {}) {
         });
     }
     function consumeSyncIntent(intent) {
-        if (!autoSync || closed || client === undefined || intent.kind === 'none') {
+        if (!autoSync ||
+            closed ||
+            client === undefined ||
+            client.securityLifecycle === 'preflight' ||
+            intent.kind === 'none') {
             return;
         }
         if (intent.kind === 'background') {
@@ -220,6 +227,9 @@ export function startSyncWorker(overrides = {}) {
             ...(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' });
@@ -257,6 +267,22 @@ export function startSyncWorker(overrides = {}) {
         return { clientId: started.clientId };
     }
     const api = {
+        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/dist/worker-host.d.ts

@@ -23,7 +23,7 @@
  */
 import type { WakeReason } from '@syncular/core';
 import type { BlobRef, CachedBlob } from './blob.js';
-import type { ConflictRecord, LeaseState, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, SchemaFloor, SubscribeInput, SyncClientLimits, SyncSummary, WindowState } from './client.js';
+import type { ConflictRecord, LeaseState, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, SchemaFloor, SecurityLifecycle, SubscribeInput, SyncClientLimits, SyncSummary, WindowState } from './client.js';
 import type { SqlRow, SqlValue } from './database.js';
 import type { EncryptionKeyringConfig } from './encryption.js';
 import { ChangeEmitter, type ClientChangeListener, InvalidationEmitter, type InvalidationListener, type LocalRevision, type SyncStatusSnapshot } from './invalidation.js';
@@ -35,7 +35,7 @@ import type { CommitOutcome, CommitOutcomeQuery, ResolveCommitOutcomeInput } fro
 import type { ClientSchema } from './schema.js';
 import type { SubscriptionRecord } from './state.js';
 import type { WindowBase } from './window.js';
-import { type SyncWorkerEvent, type WorkerDatabaseInit, type WorkerEndpoints, type WorkerErrorShape } from './worker-protocol.js';
+import { type SyncWorkerEvent, type WorkerDatabaseInit, type WorkerEndpoints, type WorkerErrorShape, type WorkerSecurityActivation } from './worker-protocol.js';
 export type HandleRole = 'leader' | 'follower';
 export type BrowserReplicaMode = {
     readonly mode: 'shared';
@@ -69,6 +69,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. */
@@ -170,6 +172,9 @@ export declare class SyncClientHandle {
     onRoleChange(listener: (role: HandleRole) => void): () => void;
     onLeadershipChange(listener: (state: LeadershipState) => void): () => void;
     subscribe(input: SubscribeInput): Promise<void>;
+    securityLifecycle(): Promise<SecurityLifecycle>;
+    beginSecurityPreflight(): Promise<void>;
+    activateSecurity(options?: WorkerSecurityActivation): Promise<void>;
     unsubscribe(id: string): Promise<void>;
     setWindow(base: WindowBase, units: readonly string[]): Promise<void>;
     windowState(base: WindowBase): Promise<WindowState>;

package/dist/worker-host.js

@@ -206,6 +206,15 @@ export class SyncClientHandle {
     subscribe(input) {
         return this.#call('subscribe', [input]);
     }
+    securityLifecycle() {
+        return this.#call('securityLifecycle', []);
+    }
+    beginSecurityPreflight() {
+        return this.#call('beginSecurityPreflight', []);
+    }
+    activateSecurity(options = {}) {
+        return this.#call('activateSecurity', [options]);
+    }
     unsubscribe(id) {
         return this.#call('unsubscribe', [id]);
     }
@@ -433,6 +442,9 @@ function buildInitConfig(config) {
         ...(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 } : {}),
@@ -665,6 +677,13 @@ async function bootFollower(config, lockName, lock, parts) {
     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) {

package/dist/worker-protocol.d.ts

@@ -18,7 +18,7 @@
  */
 import type { WakeReason } from '@syncular/core';
 import type { BlobRef, CachedBlob } from './blob.js';
-import type { ConflictRecord, LeaseState, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, SchemaFloor, SubscribeInput, SyncClientLimits, SyncSummary, WindowState } from './client.js';
+import type { ConflictRecord, LeaseState, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, SchemaFloor, SecurityLifecycle, SubscribeInput, SyncClientLimits, SyncSummary, WindowState } from './client.js';
 import type { SqlRow, SqlValue } from './database.js';
 import type { EncryptionKeyringConfig } from './encryption.js';
 import type { ClientChangeBatch, LocalRevision, SyncStatusSnapshot } from './invalidation.js';
@@ -65,6 +65,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;
     /**
@@ -78,7 +80,14 @@ export interface WorkerInitConfig {
 export interface WorkerInitResult {
     readonly clientId: string;
 }
+/** Structured-clone-safe key material installed at security activation. */
+export interface WorkerSecurityActivation {
+    readonly encryption?: EncryptionKeyringConfig;
+}
 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. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.15.14",
+  "version": "0.15.16",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -81,7 +81,7 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.15.14"
+    "@syncular/core": "0.15.16"
   },
   "peerDependencies": {
     "better-sqlite3": ">=11"
@@ -92,7 +92,7 @@
     }
   },
   "devDependencies": {
-    "@syncular/server": "0.15.14",
+    "@syncular/server": "0.15.16",
     "@types/better-sqlite3": "^7.6.13",
     "better-sqlite3": "^12.11.1"
   }

package/src/client.ts

@@ -315,6 +315,29 @@ export interface SyncClientConfig {
    * `client.decrypt_failed`, never silent plaintext).
    */
   readonly encryption?: EncryptionConfig;
+  /**
+   * Open the local replica in the fail-closed security preflight state.
+   *
+   * Preflight opens/migrates the database but suppresses every protected read,
+   * mutation, subscription, transport, realtime, presence, and blob operation.
+   * Only lifecycle/status inspection and `purgeLocalData` remain available.
+   * Install the post-authentication keyring and release the gate with
+   * `activateSecurity`. This is mutually exclusive with `encryption`: secure
+   * hosts must not materialize key bytes before their preflight has passed.
+   */
+  readonly securityPreflight?: boolean;
+}
+
+/** The fail-closed local-replica security lifecycle shared by every host. */
+export type SecurityLifecycle = 'preflight' | 'active';
+
+/** Stable client-local error while protected operations are preflight-gated. */
+export const SECURITY_PREFLIGHT_REQUIRED_CODE =
+  'client.security_preflight_required';
+
+/** Key material installed atomically when a direct client becomes active. */
+export interface SecurityActivation {
+  readonly encryption?: EncryptionConfig;
 }
 
 /** §8.6 a peer's ephemeral presence document on a scope key. */
@@ -471,7 +494,8 @@ export class SyncClient {
   readonly #db: ClientDatabase;
   readonly #schema: CompiledClientSchema;
   /** §5.11 client-side encryption config; undefined ⇒ E2EE off. */
-  readonly #encryption: EncryptionConfig | undefined;
+  #encryption: EncryptionConfig | undefined;
+  #securityLifecycle: SecurityLifecycle;
   readonly #now: () => number;
   readonly #outcomeRetentionMaxEntries: number;
   #started = false;
@@ -524,12 +548,25 @@ export class SyncClient {
    * sections, when the seam is quiescent.
    */
   #opChain: Promise<unknown> = Promise.resolve();
+  /** Async protected operations outside the SQLite serialization chain
+   * (blob I/O and realtime connect). Security preflight waits for this set to
+   * drain after synchronously closing the gate. */
+  readonly #protectedAsync = new Set<Promise<unknown>>();
+  #preflightBarrier: Promise<void> | undefined;
 
   constructor(config: SyncClientConfig) {
+    if (config.securityPreflight === true && config.encryption !== undefined) {
+      throw new ClientSyncError(
+        'sync.invalid_request',
+        'securityPreflight and encryption are mutually exclusive; install keys with activateSecurity after preflight',
+      );
+    }
     this.#config = config;
     this.#db = config.database;
     this.#schema = compileClientSchema(config.schema);
     this.#encryption = config.encryption;
+    this.#securityLifecycle =
+      config.securityPreflight === true ? 'preflight' : 'active';
     this.#now = config.now ?? Date.now;
     const outcomeRetentionMaxEntries =
       config.limits?.outcomeRetentionMaxEntries ?? 1_000;
@@ -613,7 +650,7 @@ export class SyncClient {
       this.#schemaFloor === undefined &&
       (listOutbox(this.#db).length > 0 ||
         subscriptions.some((sub) => sub.status === 'active'));
-    if (startupWork) {
+    if (startupWork && this.#securityLifecycle === 'active') {
       this.#needsPull = true;
       this.#config.onSyncNeeded?.('startup');
       this.#config.onSyncIntent?.({ kind: 'interactive' });
@@ -722,6 +759,68 @@ export class SyncClient {
     this.#started = false;
   }
 
+  /** Current fail-closed local-replica security state. */
+  get securityLifecycle(): SecurityLifecycle {
+    return this.#securityLifecycle;
+  }
+
+  /**
+   * Block new protected operations immediately, then wait for every already
+   * serialized database/network operation to settle before releasing key
+   * references. Hosts await this barrier before applying a quarantine purge.
+   */
+  beginSecurityPreflight(): Promise<void> {
+    this.#requireStarted();
+    if (this.#preflightBarrier !== undefined) return this.#preflightBarrier;
+    this.#securityLifecycle = 'preflight';
+    this.disconnectRealtime();
+    const barrier = (async () => {
+      await Promise.allSettled([this.#opChain, ...this.#protectedAsync]);
+      this.disconnectRealtime();
+      this.#encryption = undefined;
+      this.#syncOutstanding = false;
+    })();
+    this.#preflightBarrier = barrier;
+    void barrier.then(
+      () => {
+        if (this.#preflightBarrier === barrier)
+          this.#preflightBarrier = undefined;
+      },
+      () => {
+        if (this.#preflightBarrier === barrier)
+          this.#preflightBarrier = undefined;
+      },
+    );
+    return barrier;
+  }
+
+  /**
+   * Atomically install the post-authentication keyring and release the gate.
+   * Persisted subscriptions/outbox work produces one exact startup intent only
+   * after activation, never while the local quarantine decision is pending.
+   */
+  async activateSecurity(options: SecurityActivation = {}): Promise<void> {
+    this.#requireStarted();
+    if (this.#securityLifecycle === 'active') {
+      throw new ClientSyncError(
+        'sync.invalid_request',
+        'activateSecurity requires the client to be in security preflight',
+      );
+    }
+    await (this.#preflightBarrier ?? this.#opChain);
+    this.#encryption = options.encryption;
+    this.#securityLifecycle = 'active';
+    const startupWork =
+      this.#schemaFloor === undefined &&
+      (listOutbox(this.#db).length > 0 ||
+        loadSubscriptions(this.#db).some((sub) => sub.status === 'active'));
+    if (startupWork) {
+      this.#setSyncNeeded(true);
+      this.#config.onSyncNeeded?.('startup');
+      this.#config.onSyncIntent?.({ kind: 'interactive' });
+    }
+  }
+
   // -- accessors ------------------------------------------------------------
 
   get clientId(): string {
@@ -730,6 +829,7 @@ export class SyncClient {
 
   /** The underlying database — raw SQL is the local query API (B3). */
   get database(): ClientDatabase {
+    this.#requireActive();
     return this.#db;
   }
 
@@ -742,6 +842,7 @@ export class SyncClient {
    * internals read `this.#db` directly and skip this method by design.
    */
   query(sql: string, params?: readonly SqlValue[]): SqlRow[] {
+    this.#requireActive();
     assertReadOnlyQuery(sql);
     return stripSyncColumns(this.#db.query(sql, params));
   }
@@ -758,7 +859,7 @@ export class SyncClient {
    * `windowState()` across separate worker/IPC calls.
    */
   querySnapshot<Row = SqlRow>(spec: QueryReadSpec): QuerySnapshot<Row> {
-    this.#requireStarted();
+    this.#requireActive();
     assertReadOnlyQuery(spec.sql);
     return this.#db.transaction(() => {
       const revision = getLocalRevision(this.#db);
@@ -901,6 +1002,17 @@ export class SyncClient {
     return next;
   }
 
+  #runProtectedAsync<T>(fn: () => Promise<T>): Promise<T> {
+    this.#requireActive();
+    const task = Promise.resolve().then(fn);
+    this.#protectedAsync.add(task);
+    void task.then(
+      () => this.#protectedAsync.delete(task),
+      () => this.#protectedAsync.delete(task),
+    );
+    return task;
+  }
+
   // -- blobs (§5.9) ---------------------------------------------------------
 
   /**
@@ -910,7 +1022,14 @@ export class SyncClient {
    * a `blob_ref` column of a mutation. The referencing row MUST be written
    * (via `mutate`) after this call so upload-before-push holds (§5.9.3).
    */
-  async uploadBlob(
+  uploadBlob(
+    bytes: Uint8Array,
+    options?: { readonly mediaType?: string; readonly name?: string },
+  ): Promise<BlobRef> {
+    return this.#runProtectedAsync(() => this.#uploadBlob(bytes, options));
+  }
+
+  async #uploadBlob(
     bytes: Uint8Array,
     options?: { readonly mediaType?: string; readonly name?: string },
   ): Promise<BlobRef> {
@@ -950,7 +1069,11 @@ export class SyncClient {
    * transport (§5.9.5), verifies the content address, caches, and returns.
    * Accepts a raw `blob_ref` column string or a bare `blobId`.
    */
-  async fetchBlob(blobIdOrRef: string): Promise<CachedBlob> {
+  fetchBlob(blobIdOrRef: string): Promise<CachedBlob> {
+    return this.#runProtectedAsync(() => this.#fetchBlob(blobIdOrRef));
+  }
+
+  async #fetchBlob(blobIdOrRef: string): Promise<CachedBlob> {
     const blobId = blobIdOrRef.startsWith('sha256:')
       ? blobIdOrRef
       : parseBlobRef(blobIdOrRef).blobId;
@@ -1021,7 +1144,11 @@ export class SyncClient {
   }
 
   /** Flush any queued blob uploads (§5.9.7 B4); safe to call standalone. */
-  async flushBlobUploads(): Promise<void> {
+  flushBlobUploads(): Promise<void> {
+    return this.#runProtectedAsync(() => this.#flushBlobUploads());
+  }
+
+  async #flushBlobUploads(): Promise<void> {
     const transport = this.#config.blobs;
     if (transport === undefined || !this.#hasBlobs) return;
     for (const pending of listPendingUploads(this.#db)) {
@@ -1086,22 +1213,24 @@ export class SyncClient {
   }
 
   get conflicts(): readonly ConflictRecord[] {
+    this.#requireActive();
     return this.#conflicts;
   }
 
   get rejections(): readonly RejectionRecord[] {
+    this.#requireActive();
     return this.#rejections;
   }
 
   /** One durable final outcome by the originating client commit id. */
   commitOutcome(clientCommitId: string): CommitOutcome | undefined {
-    this.#requireStarted();
+    this.#requireActive();
     return readCommitOutcome(this.#db, clientCommitId);
   }
 
   /** Newest-first durable outcome journal. */
   commitOutcomes(query: CommitOutcomeQuery = {}): readonly CommitOutcome[] {
-    this.#requireStarted();
+    this.#requireActive();
     return listCommitOutcomes(this.#db, query);
   }
 
@@ -1112,7 +1241,7 @@ export class SyncClient {
    * dismissed. The transition is one-way and survives restart.
    */
   resolveCommitOutcome(input: ResolveCommitOutcomeInput): CommitOutcome {
-    this.#requireStarted();
+    this.#requireActive();
     const current = readCommitOutcome(this.#db, input.clientCommitId);
     if (current === undefined) {
       throw new ClientSyncError(
@@ -1226,12 +1355,14 @@ export class SyncClient {
    * Ephemeral — reflects only what the socket has delivered.
    */
   presence(scopeKey: string): readonly PresencePeer[] {
+    this.#requireActive();
     const peers = this.#presence.get(scopeKey);
     return peers === undefined ? [] : [...peers.values()];
   }
 
   /** Every scope key this client currently has presence state for. */
   presenceKeys(): string[] {
+    this.#requireActive();
     return [...this.#presence.keys()];
   }
 
@@ -1256,7 +1387,7 @@ export class SyncClient {
    * by the server with `presence.forbidden`.
    */
   setPresence(scopeKey: string, doc: Record<string, unknown> | null): void {
-    this.#requireStarted();
+    this.#requireActive();
     const socket = this.#socket;
     if (socket === undefined) {
       throw new ClientSyncError(
@@ -1289,24 +1420,24 @@ export class SyncClient {
   }
 
   subscriptions(): SubscriptionRecord[] {
-    this.#requireStarted();
+    this.#requireActive();
     return loadSubscriptions(this.#db);
   }
 
   subscription(id: string): SubscriptionRecord | undefined {
-    this.#requireStarted();
+    this.#requireActive();
     return getSubscription(this.#db, id);
   }
 
   pendingCommits(): OutboxCommit[] {
-    this.#requireStarted();
+    this.#requireActive();
     return listOutbox(this.#db);
   }
 
   // -- subscriptions ----------------------------------------------------------
 
   subscribe(input: SubscribeInput): void {
-    this.#requireStarted();
+    this.#requireActive();
     if (!this.#schema.tables.has(input.table)) {
       throw new ClientSyncError(
         'sync.unknown_table',
@@ -1334,7 +1465,7 @@ export class SyncClient {
   }
 
   unsubscribe(id: string): void {
-    this.#requireStarted();
+    this.#requireActive();
     deleteSubscription(this.#db, id);
   }
 
@@ -1362,7 +1493,7 @@ export class SyncClient {
     base: WindowBase,
     units: readonly string[],
   ): Promise<CommandResult<void>> {
-    this.#requireStarted();
+    this.#requireActive();
     const table = this.#table(base.table);
     if (!table.scopeColumnByVariable.has(base.variable)) {
       throw new ClientSyncError(
@@ -1429,7 +1560,7 @@ export class SyncClient {
    * advances past -1 with no resume token held).
    */
   windowState(base: WindowBase): WindowState {
-    this.#requireStarted();
+    this.#requireActive();
     const baseKey = windowBaseKey(base);
     const live = loadWindowUnits(this.#db, baseKey);
     const pending: string[] = [];
@@ -1540,7 +1671,7 @@ export class SyncClient {
     mutations: readonly MutationInput[],
     changedFieldsByIndex: readonly (readonly string[] | undefined)[] = [],
   ): string {
-    this.#requireStarted();
+    this.#requireActive();
     const clientCommitId = crypto.randomUUID();
     const operations: OutboxOperation[] = mutations.map((mutation, index) => {
       const table = this.#table(mutation.table);
@@ -1617,7 +1748,7 @@ export class SyncClient {
     partial: Readonly<Record<string, unknown>>,
     options?: { readonly baseVersion?: number },
   ): string {
-    this.#requireStarted();
+    this.#requireActive();
     const compiled = this.#table(table);
     const pkColumn = compiled.columns[compiled.primaryKeyIndex] as RowColumn;
     const rows = this.#db.query(
@@ -1951,7 +2082,7 @@ export class SyncClient {
    * `setWindow` at an await point.
    */
   sync(): Promise<SyncSummary> {
-    this.#requireStarted();
+    this.#requireActive();
     if (this.#syncOutstanding) {
       return Promise.reject(
         new ClientSyncError(
@@ -2159,8 +2290,11 @@ export class SyncClient {
 
   // -- realtime (§8 client side) ----------------------------------------------
 
-  async connectRealtime(): Promise<void> {
-    this.#requireStarted();
+  connectRealtime(): Promise<void> {
+    return this.#runProtectedAsync(() => this.#connectRealtime());
+  }
+
+  async #connectRealtime(): Promise<void> {
     const connector = this.#config.realtime;
     if (connector === undefined) {
       throw new ClientSyncError(
@@ -2168,7 +2302,7 @@ export class SyncClient {
         'no realtime connector configured',
       );
     }
-    this.#socket = await connector({
+    const socket = await connector({
       onText: (text) => this.#handleRealtimeText(text),
       onBinary: (bytes) => this.#routeRealtimeBinary(bytes),
       onClose: () => {
@@ -2177,6 +2311,14 @@ export class SyncClient {
         this.#abortPendingRound('realtime socket closed mid-round (§8.7)');
       },
     });
+    if (this.#securityLifecycle === 'preflight') {
+      socket.close();
+      throw new ClientSyncError(
+        SECURITY_PREFLIGHT_REQUIRED_CODE,
+        'realtime connected after the client entered security preflight',
+      );
+    }
+    this.#socket = socket;
   }
 
   disconnectRealtime(): void {
@@ -3336,4 +3478,14 @@ export class SyncClient {
       );
     }
   }
+
+  #requireActive(): void {
+    this.#requireStarted();
+    if (this.#securityLifecycle === 'preflight') {
+      throw new ClientSyncError(
+        SECURITY_PREFLIGHT_REQUIRED_CODE,
+        'the local replica is in security preflight; complete quarantine checks and call activateSecurity before accessing protected data',
+      );
+    }
+  }
 }

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,
@@ -87,6 +88,7 @@ import {
   type WorkerInitConfig,
   type WorkerInitResult,
   type WorkerMethod,
+  type WorkerSecurityActivation,
   type WorkerToMainMessage,
 } from './worker-protocol';
 
@@ -140,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. */
@@ -423,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]);
   }
@@ -724,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 } : {}),
@@ -1007,6 +1026,13 @@ 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;
 }
 

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. */