@oxidezap/baileyrs 0.2.11 → 0.2.13

package/lib/Socket/index.js

@@ -31,6 +31,7 @@ import { makeBridgeClientOwner } from './bridge-client-owner.js';
 import { warnUnsupportedConfig } from './unsupported-config.js';
 import { wrapBridgeClient } from './bridge-error-boundary.js';
 import { makeTerminalCloseReporter } from './terminal-close-reporter.js';
+import { mapConnectFailureToDisconnect } from './terminal-close.js';
 import { makeEventHandlers } from './events.js';
 import { makeGroupMethods } from './groups.js';
 import { makeInternalMethods, makeUnexpectedErrorReporter } from './internals.js';
@@ -71,6 +72,29 @@ const browserToPlatformType = (browser) => {
             return 'CHROME';
     }
 };
+const COMPLETION_FAILURE_CODES = new Map([
+    ['Generic', 400],
+    ['LoggedOut', 401],
+    ['TempBanned', 402],
+    ['AccountLocked', 403],
+    ['UnknownLogout', 406],
+    ['ClientOutdated', 405],
+    ['BadUserAgent', 409],
+    ['CatExpired', 413],
+    ['CatInvalid', 414],
+    ['NotFound', 415],
+    ['ClientUnknown', 418],
+    ['InternalServerError', 500],
+    ['Experimental', 501],
+    ['ServiceUnavailable', 503]
+]);
+const completionFailureCode = (reason) => {
+    const named = COMPLETION_FAILURE_CODES.get(reason);
+    if (named !== undefined)
+        return named;
+    const unknown = /^Unknown\((-?\d+)\)$/.exec(reason)?.[1];
+    return unknown === undefined ? undefined : Number(unknown);
+};
 /** Build the ws EventEmitter with auto-enable raw node forwarding */
 const makeWASocket = (config) => {
     const fullConfig = { ...DEFAULT_CONNECTION_CONFIG, ...config };
@@ -261,6 +285,37 @@ const makeWASocket = (config) => {
     let autoReconnectEnabled = true;
     /** Owns reporting the terminal close: once, after teardown, never not at all. */
     const terminalClose = makeTerminalCloseReporter({ logger });
+    const runCompletionError = (completion) => {
+        let statusCode = DisconnectReason.connectionClosed;
+        let message = 'Connection closed';
+        if (completion.reason === 'unknown') {
+            message = `Connection run ended: ${completion.detail}`;
+        }
+        else if (completion.reason === 'stopped') {
+            message = 'Connection run stopped';
+        }
+        else if (completion.reason === 'already-running') {
+            message = 'Connection run was already running';
+        }
+        else if (completion.reason === 'auto-reconnect-disabled') {
+            const protocol = completion.protocolError;
+            if (protocol?.kind === 'conflict') {
+                statusCode = DisconnectReason.connectionReplaced;
+                message = 'Connection replaced';
+            }
+            else if (protocol?.kind === 'stream-error') {
+                statusCode = mapConnectFailureToDisconnect(protocol.code);
+            }
+            else if (protocol?.kind === 'connect-failure') {
+                statusCode = mapConnectFailureToDisconnect(completionFailureCode(protocol.reason));
+            }
+            else if (completion.connection?.kind === 'server-close') {
+                message = completion.connection.reason;
+            }
+        }
+        return new Boom(message, { statusCode, data: { runCompletion: completion } });
+    };
+    const reportTerminalClose = (error, publish) => terminalClose.reportAfter(() => owner.close(error).finally(() => initPromise), publish);
     /**
      * Held in a reporter rather than captured, because `sock.onUnexpectedError`
      * is an assignable property: a consumer that replaces it has to be the one
@@ -401,7 +456,7 @@ const makeWASocket = (config) => {
             // is still owned. This waits for the real teardown, and cannot
             // deadlock because `reportAfter` runs it detached; nothing in the
             // teardown is waiting on this.
-            terminalClose.reportAfter(() => owner.close(error).finally(() => initPromise), publish);
+            reportTerminalClose(error, publish);
         },
         isAutoReconnectEnabled: () => autoReconnectEnabled,
         // Timers the dispatcher armed outlive the events that armed them, and
@@ -454,7 +509,13 @@ const makeWASocket = (config) => {
         }
         if (useNativeMemory)
             logger.debug('auth: using socket-local native memory backend');
-        const created = await createWhatsAppClient(makeTransport(fullConfig), makeHttpClient(fullConfig), eventHandlers, bridgeStore, fullConfig.cache ?? null, fullConfig.version, fullConfig.wantedPreKeyCount ?? null);
+        const created = await createWhatsAppClient(makeTransport(fullConfig), makeHttpClient(fullConfig), eventHandlers, bridgeStore, fullConfig.cache ?? null, fullConfig.version, fullConfig.wantedPreKeyCount ?? null, 
+        // Passed through exactly as configured, never normalized by truthiness:
+        // the bridge only honours a literal `true` here and rejects any
+        // other truthy value at construction, so a `!!`/ternary-style
+        // coercion could promote a malformed opt-out into an opt-in.
+        // Absent stays strict.
+        fullConfig.dangerSkipCertChainVerify);
         // `end()` can land while the client is still being built — a `sock.end()`
         // or `await using` right after `makeWASocket()` does exactly that. When
         // it has, `adopt` frees this client and tells us to stop: nothing else
@@ -521,23 +582,46 @@ const makeWASocket = (config) => {
         // starting the read loop now would run against a handle about to go.
         if (owner.isClosing())
             return;
-        // `run()` spawns the connect/handshake/read/reconnect loop as a
-        // background task and returns `void` — it deliberately is not `async`,
-        // so that it does not hold a wasm-bindgen borrow on `self` that would
-        // block `disconnect()`.
-        //
-        // Consequence: the loop's exit is not observable from here. The engine
-        // clears `enable_auto_reconnect` and breaks out on every terminal
-        // disconnect (conflict/401/409/516, and any `<failure>` whose reason is
-        // not 500/503), and when it does, the `WasmWhatsAppClient` is dead
-        // weight that only `sock.end()` can free — nothing else can, because
-        // the bridge holds the JS event callbacks as wasm-bindgen externrefs,
-        // those close over `ctx`, and `ctx` closes over `client`, so the cycle
-        // crosses the JS/wasm boundary and no `FinalizationRegistry` fires.
-        // Freeing that automatically needs the bridge to expose loop completion
-        // (a terminal callback or an awaitable handle); until it does, the
-        // consumer has to call `sock.end()` on a terminal close.
+        // `run()` deliberately returns immediately so callers can use the
+        // client while supervision owns its background task. Registering the
+        // completion observer after it is started is safe: bridge 0.21.0 admits
+        // late observers against the stored result for this run generation.
         created.run();
+        const observedClient = created;
+        void created
+            .waitForRunCompletion()
+            .then(completion => {
+            // The owner identity is the socket generation fence. A completion
+            // from a client that teardown already released must never close a
+            // later socket using the same auth state.
+            if (owner.isClosing() || owner.peek() !== observedClient)
+                return;
+            const error = runCompletionError(completion);
+            reportTerminalClose(error, () => ev.emit('connection.update', {
+                connection: 'close',
+                lastDisconnect: { error, date: new Date() }
+            }));
+        }, error => {
+            if (owner.isClosing() || owner.peek() !== observedClient)
+                return;
+            const closeError = new Boom('Connection run ended without a completion result', {
+                statusCode: DisconnectReason.connectionClosed
+            });
+            reportTerminalClose(closeError, () => ev.emit('connection.update', {
+                connection: 'close',
+                lastDisconnect: { error: closeError, date: new Date() }
+            }));
+            try {
+                logger.error({ err: error }, 'bridge run completion observation failed');
+            }
+            catch {
+                // A consumer logger cannot prevent the terminal cleanup above.
+            }
+        })
+            .catch(() => {
+            // The reporter contains teardown and publish failures; this final guard
+            // also contains a consumer logger that throws from an observation path.
+        });
         initialized = true;
     };
     /**

package/lib/Socket/terminal-close-reporter.d.ts

@@ -1,6 +1,13 @@
 /**
- * Reports the terminal `connection.update { close }` — exactly once, after
- * teardown, and never silently not at all.
+ * Reports the terminal `connection.update { close }` — exactly once, and
+ * never silently not at all.
+ *
+ * The accepted claim publishes after its teardown settles, so a consumer that
+ * answers the close with a replacement socket does not overlap the old one's
+ * release. The watchdog is the deliberate exception: past the timeout the
+ * close goes out with teardown still running (and logged), because losing the
+ * event entirely is the worse failure. Nothing here promises that every close
+ * lands after every resource is released — only that at most one close lands.
  *
  * That sentence is the whole contract this branch sells, and getting it wrong
  * has two opposite failure modes, both bad:
@@ -8,9 +15,8 @@
  *  - **Not reported.** The consumer's handler never runs, so it never builds a
  *    replacement socket. A bot offline with nothing in its logs — the original
  *    bug this branch exists to fix.
- *  - **Reported early, or twice.** The replacement socket overlaps the old
- *    one's auth-store flush and `free()`, or every listener sees two terminal
- *    notifications for one socket and a handler that cleans up on close loops.
+ *  - **Reported twice.** Every listener sees two terminal notifications for
+ *    one socket and a handler that cleans up on close loops.
  *
  * Keeping both away used to be inline logic split across the dispatcher hook
  * and `logout()`, sharing a counter and a promise. Nine separate bugs came out
@@ -41,13 +47,26 @@ export interface TerminalCloseReporter {
      *
      * Never rejects and never leaves `publish` uncalled: teardown failures are
      * logged, a throwing listener is contained, and a teardown that hangs is
-     * cut short by the watchdog.
+     * reported past by the watchdog.
+     *
+     * Idempotent per socket: the first claim wins and every later call is
+     * ignored entirely — neither its teardown nor its publish is invoked. A
+     * socket never gets a second generation — a terminal close means "build a
+     * new socket" — so a second terminal event (a logout racing a dispatcher
+     * close, a late duplicate dispatch) must not publish again.
+     *
+     * The watchdog bounds how long `published()` waits, not the teardown
+     * itself: it neither cancels nor settles the underlying teardown, and a
+     * teardown that finishes late publishes nothing further.
      */
     reportAfter: (teardown: () => Promise<void>, publish: () => void) => void;
     /**
      * Publish immediately, for a close nothing else will announce — a `logout()`
      * with no live client, or one whose `logout()` threw before the bridge
      * dispatched anything.
+     *
+     * Part of the same single claim as `reportAfter`: a no-op when a close
+     * was already claimed.
      */
     reportNow: (publish: () => void) => void;
     /**
@@ -63,11 +82,13 @@ export interface TerminalCloseReporter {
      */
     hasReported: () => boolean;
     /**
-     * Settles once the most recent report has been published — the moment the
+     * Settles once the single report has been published — the moment the
      * consumer sees it, not the moment teardown finishes, so a waiter is not
      * left hanging when the watchdog is what released the event.
      *
-     * Resolves immediately when nothing has been reported.
+     * Resolves immediately when nothing has been reported. Every waiter
+     * observes the same promise, so concurrent `logout()` and dispatcher
+     * paths cannot split across generations.
      */
     published: () => Promise<void>;
 }

package/lib/Socket/terminal-close-reporter.js

@@ -1,6 +1,13 @@
 /**
- * Reports the terminal `connection.update { close }` — exactly once, after
- * teardown, and never silently not at all.
+ * Reports the terminal `connection.update { close }` — exactly once, and
+ * never silently not at all.
+ *
+ * The accepted claim publishes after its teardown settles, so a consumer that
+ * answers the close with a replacement socket does not overlap the old one's
+ * release. The watchdog is the deliberate exception: past the timeout the
+ * close goes out with teardown still running (and logged), because losing the
+ * event entirely is the worse failure. Nothing here promises that every close
+ * lands after every resource is released — only that at most one close lands.
  *
  * That sentence is the whole contract this branch sells, and getting it wrong
  * has two opposite failure modes, both bad:
@@ -8,9 +15,8 @@
  *  - **Not reported.** The consumer's handler never runs, so it never builds a
  *    replacement socket. A bot offline with nothing in its logs — the original
  *    bug this branch exists to fix.
- *  - **Reported early, or twice.** The replacement socket overlaps the old
- *    one's auth-store flush and `free()`, or every listener sees two terminal
- *    notifications for one socket and a handler that cleans up on close loops.
+ *  - **Reported twice.** Every listener sees two terminal notifications for
+ *    one socket and a handler that cleans up on close loops.
  *
  * Keeping both away used to be inline logic split across the dispatcher hook
  * and `logout()`, sharing a counter and a promise. Nine separate bugs came out
@@ -35,9 +41,24 @@ export const TERMINAL_CLOSE_PUBLISH_TIMEOUT_MS = 60000;
 export const makeTerminalCloseReporter = (opts) => {
     const { logger } = opts;
     const publishTimeoutMs = opts.publishTimeoutMs ?? TERMINAL_CLOSE_PUBLISH_TIMEOUT_MS;
-    /** Claims, not deliveries — see `hasReported`. */
+    /**
+     * Claims, not deliveries — see `hasReported`. At most one: a socket has a
+     * single terminal generation, so the first claim wins and later ones are
+     * ignored rather than published.
+     */
     let claimed = 0;
     let publishedPromise;
+    /**
+     * True once the single terminal generation has been claimed. Deliberately
+     * log-free: a duplicate arrives on a path whose logger is
+     * consumer-replaceable, and an ignored signal must never throw.
+     */
+    const claim = () => {
+        if (claimed > 0)
+            return false;
+        claimed++;
+        return true;
+    };
     /** One publish per claim, whatever gets there first, and never throwing. */
     const makeOnce = (publish, settle) => {
         let done = false;
@@ -59,7 +80,8 @@ export const makeTerminalCloseReporter = (opts) => {
     };
     return {
         reportAfter: (teardown, publish) => {
-            claimed++;
+            if (!claim())
+                return;
             let settle;
             publishedPromise = new Promise(resolve => {
                 settle = resolve;
@@ -94,7 +116,8 @@ export const makeTerminalCloseReporter = (opts) => {
             }
         },
         reportNow: publish => {
-            claimed++;
+            if (!claim())
+                return;
             let settle;
             publishedPromise = new Promise(resolve => {
                 settle = resolve;

package/lib/Socket/terminal-close.d.ts

@@ -1,39 +1,5 @@
-/**
- * Which bridge disconnects end the socket for good.
- *
- * This mirrors one decision that lives in the Rust engine, so keep it honest:
- * `whatsapp-rust` clears `enable_auto_reconnect` and breaks out of its run loop
- * on exactly these, and retries everything else on the WA Web Fibonacci backoff
- * (`client/lifecycle.rs`).
- *
- * The socket layer needs the answer because `WasmWhatsAppClient.run()` returns
- * `void` — it spawns the loop as a background task, so the loop's exit is not
- * observable from JS (`whatsapp_rust_bridge.d.ts`, `run(): void`). Until the
- * bridge exposes loop completion, this table is how the socket knows a client
- * has become dead weight that only `free()` can reclaim.
- *
- * The upstream Baileys contract this buys us: `connection.update { close }`
- * means "this socket is finished, build a new one" — which is what every
- * consumer written against upstream already assumes, because upstream has no
- * auto-reconnect at all. Transient drops therefore never surface as `close`;
- * they surface as `connecting`.
- *
- * Events deliberately absent from the terminal set, and why:
- *  - `disconnected` — the engine only dispatches `Event::Disconnected` for an
- *    *unexpected* loop exit, and every terminal path sets `expected_disconnect`
- *    first, which suppresses it (`client/lifecycle.rs`). So this one is the
- *    "engine is retrying" signal — with one exception the dispatcher handles:
- *    under `setAutoReconnect(false)` the run loop dispatches `Disconnected`
- *    and only *then* tests the flag and breaks out, which makes the very same
- *    event terminal. Absence from this list means "not terminal on its own",
- *    not "never terminal".
- *  - `streamError` — reaches JS only from the engine's catch-all `<stream:error>`
- *    branch (unknown code, `<ack/>`, `<xml-not-well-formed>`); the coded ones
- *    (401/409/515/516/429/503) dispatch their own events instead. Every case
- *    that gets here keeps the connection or recycles it deliberately.
- *  - `pairError` — pairing failed, but the engine keeps its loop and re-emits a
- *    QR; nothing about the client is dead.
- */
 /** True when the engine will keep retrying after this `<failure>`. */
 export declare const isReconnectableConnectFailure: (reason: number | undefined) => boolean;
+/** Map a typed bridge connect-failure code to Baileys' close status. */
+export declare const mapConnectFailureToDisconnect: (reason: number | undefined) => number;
 //# sourceMappingURL=terminal-close.d.ts.map

package/lib/Socket/terminal-close.js

@@ -1,3 +1,4 @@
+import { DisconnectReason } from '../Types/index.js';
 /**
  * Which bridge disconnects end the socket for good.
  *
@@ -6,11 +7,10 @@
  * on exactly these, and retries everything else on the WA Web Fibonacci backoff
  * (`client/lifecycle.rs`).
  *
- * The socket layer needs the answer because `WasmWhatsAppClient.run()` returns
- * `void` — it spawns the loop as a background task, so the loop's exit is not
- * observable from JS (`whatsapp_rust_bridge.d.ts`, `run(): void`). Until the
- * bridge exposes loop completion, this table is how the socket knows a client
- * has become dead weight that only `free()` can reclaim.
+ * The socket layer needs the answer for bridge events that classify a terminal
+ * close before the supervised run completion is observed. Bridge 0.21.0 also
+ * exposes `waitForRunCompletion()` for exits with no terminal event; that
+ * observer uses the same terminal-close reporter and owner as this table.
  *
  * The upstream Baileys contract this buys us: `connection.update { close }`
  * means "this socket is finished, build a new one" — which is what every
@@ -48,4 +48,28 @@ const RECONNECTABLE_CONNECT_FAILURE_REASONS = new Set([
 ]);
 /** True when the engine will keep retrying after this `<failure>`. */
 export const isReconnectableConnectFailure = (reason) => reason !== undefined && RECONNECTABLE_CONNECT_FAILURE_REASONS.has(reason);
+/** Map a typed bridge connect-failure code to Baileys' close status. */
+export const mapConnectFailureToDisconnect = (reason) => {
+    switch (reason) {
+        case 401:
+        case 403:
+        case 406:
+            return DisconnectReason.loggedOut;
+        case 402:
+            return DisconnectReason.forbidden;
+        case 405:
+            return 405;
+        case 411:
+            return DisconnectReason.multideviceMismatch;
+        case 503:
+        case 501:
+            return DisconnectReason.unavailableService;
+        case 408:
+            return DisconnectReason.timedOut;
+        case 515:
+            return DisconnectReason.restartRequired;
+        default:
+            return DisconnectReason.connectionClosed;
+    }
+};
 //# sourceMappingURL=terminal-close.js.map

package/lib/Socket/unsupported-config.d.ts

@@ -33,7 +33,7 @@ export declare const UNSUPPORTED_CONFIG_KEYS: readonly ["keepAliveIntervalMs", "
  * member of `SocketConfig` belongs to neither list — which is exactly how the
  * first version of the catalog shipped twelve keys short.
  */
-export declare const READ_CONFIG_KEYS: readonly ["waWebSocketUrl", "options", "logger", "version", "browser", "pushName", "auth", "cache", "deviceProps", "wantedPreKeyCount", "emitOwnEvents", "shouldIgnoreJid", "defaultQueryTimeoutMs", "transactionOpts", "makeSignalRepository"];
+export declare const READ_CONFIG_KEYS: readonly ["waWebSocketUrl", "options", "logger", "version", "browser", "pushName", "auth", "cache", "deviceProps", "wantedPreKeyCount", "dangerSkipCertChainVerify", "emitOwnEvents", "shouldIgnoreJid", "defaultQueryTimeoutMs", "transactionOpts", "makeSignalRepository"];
 /**
  * Which unsupported options this caller actually passed.
  *

package/lib/Socket/unsupported-config.js

@@ -98,6 +98,7 @@ export const READ_CONFIG_KEYS = [
     'cache',
     'deviceProps',
     'wantedPreKeyCount',
+    'dangerSkipCertChainVerify',
     'emitOwnEvents',
     'shouldIgnoreJid',
     'defaultQueryTimeoutMs',

package/lib/Types/Socket.d.ts

@@ -93,6 +93,14 @@ export type SocketConfig = {
      * generated and encoded in one shot). Must be set before connecting.
      */
     wantedPreKeyCount?: number;
+    /**
+     * Testing-only bypass for the Noise server-cert chain check, for mock
+     * servers that cannot sign a chain rooted in WhatsApp's issuer. Strict by
+     * default: absent, null and false all verify, and only a literal `true`
+     * opts in — the bridge rejects any other truthy value at construction
+     * rather than treating it as opt-in. Never set this outside tests.
+     */
+    dangerSkipCertChainVerify?: boolean;
     /** @deprecated QR timeout is handled by the bridge connection state machine. */
     qrTimeout?: number;
     /** Maximum retry count. */

package/lib/Utils/use-bridge-store.d.ts

@@ -1,13 +1,84 @@
 import type { AuthenticationState } from '../Types/index.js';
+/**
+ * Pure classifier for directory-barrier failures: does this error mean
+ * "this platform cannot sync directory handles" (degrade to process-crash
+ * atomicity) or "the durability barrier did not hold" (propagate)?
+ *
+ * - `ENOSYS` / `ENOTSUP` on any platform: the operation is not
+ *   implemented — genuinely unsupported, safe to degrade.
+ * - `EINVAL` / `EPERM` / `EISDIR` on `win32` only: Windows directory
+ *   handles reject open-for-read and FlushFileBuffers with these codes,
+ *   so they are the documented platform fallback there. On Linux/macOS
+ *   the same codes from a freshly opened directory handle mean something
+ *   is genuinely wrong and they propagate.
+ * - Everything else propagates everywhere: `EIO`, `ENOSPC`, `EROFS`,
+ *   `EACCES`, `ENOENT`, and notably `EBADF` (a bad handle is a real bug,
+ *   never evidence of an unsupported platform).
+ *
+ * `platform` defaults to the running platform; tests pass explicit values
+ * to cover the matrix deterministically on any OS.
+ */
+export declare const isUnsupportedDirSync: (e: unknown, platform?: NodeJS.Platform) => boolean;
+type BridgeStoreFileHandle = {
+    writeFile(value: Uint8Array): Promise<void>;
+    sync(): Promise<void>;
+    close(): Promise<void>;
+};
+type BridgeStoreFileIO = {
+    writeTmp?(tmpPath: string, value: Uint8Array): Promise<void>;
+    publishTmp?(tmpPath: string, finalPath: string): Promise<void>;
+    syncDir?(dir: string): Promise<void>;
+    openTmp?(tmpPath: string): Promise<BridgeStoreFileHandle>;
+};
+type BridgeStoreOptions = {
+    io?: BridgeStoreFileIO;
+};
 /**
  * Creates a file-based store for the WASM bridge.
  *
  * Each (store, key) pair maps to a file: `<folder>/<store>-<key>.bin`
  *
- * Uses a write-through in-memory cache to avoid redundant disk reads.
- * Writes go to both cache and disk. Reads hit cache first, disk on miss.
+ * Durability model:
+ * - Caller buffers are copied synchronously at admission (`set`/`setMany`
+ *   copy before queueing), so mutating a buffer after the call — even
+ *   before awaiting it — can never change what gets persisted.
+ * - Critical stores write through `durableWrite` before `set`/`setMany`
+ *   resolve. The in-memory map only records bytes AFTER the full barrier
+ *   (write + fsync + atomic rename + directory sync) succeeds, so an
+ *   identical retry following a failure is never skipped and always
+ *   re-attempts the write.
+ * - If the post-rename barrier fails, the key is marked uncertain: prior
+ *   durable knowledge is discarded, reads serve best-available bytes
+ *   without re-certifying them, and no identical set is skipped until a
+ *   later operation completes the full barrier for that key.
+ * - Non-critical stores are debounced (50ms coalescing) and readable
+ *   immediately (read-your-write), but such reads are NOT durable until
+ *   `flush()` succeeds. A failed flush keeps the pending entry and throws,
+ *   so the next `flush()` retries the same bytes.
+ * - `flush()` first waits for every operation admitted before it
+ *   (barrier), then drains the pending writes those operations produced.
+ *   Failures observed by the barrier propagate — a failed admitted write
+ *   fails the flush — but only operations outstanding during that flush
+ *   are reported, so history never poisons later flushes. A drain pass
+ *   with any failure stops at that pass and leaves the failed entries
+ *   for the next explicit flush. `flush()` never reports quiescence
+ *   while prior admitted work is still running.
+ * - All operations on one key (set, delete, flush, concurrent batches) run
+ *   through a per-key chain, so a stale failure can never erase newer
+ *   state and an in-flight write can never resurrect a deleted key.
+ * - A failed delete restores the preceding pending/durable state, so an
+ *   acknowledged value stays readable and flushable; only a successful
+ *   delete (unlink + directory barrier) clears it. A delete retried while
+ *   the key is uncertain re-runs the directory barrier instead of
+ *   swallowing the uncertainty as idempotent absence — except that a
+ *   directory removed externally surfaces ENOENT rather than success.
+ * - Every byte array handed back to callers is a copy.
  *
  * @param folder Directory to store bridge state files
+ * @param options Optional per-store file-I/O steps. Test/fault-injection
+ *   seam only: the default implementation is the sole provider of the
+ *   durability contract above.
  */
-export declare function useBridgeStore(folder: string): Promise<NonNullable<AuthenticationState['store']>>;
+export declare function useBridgeStore(folder: string, options?: BridgeStoreOptions): Promise<NonNullable<AuthenticationState['store']>>;
+export {};
 //# sourceMappingURL=use-bridge-store.d.ts.map