@oxidezap/baileyrs 0.2.10 → 0.2.12

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