@diegoaltoworks/chatter 0.40.0 → 0.42.0

package/README.md

@@ -76,6 +76,7 @@ Complete guides for setup, deployment, and integration:
 - **[Deployment](./docs/deployment.md)** - Google Cloud Run, Fly.io, Railway, VPS
 - **[Testing](./docs/testing.md)** - Comprehensive testing guide
 - **[Code Quality](./docs/CODE_QUALITY.md)** - Security assessment and architecture review
+- **[Sprint Review](./docs/sprint-review.md)** - Cross-module & security-invariant audit
 - **[FAQs](./docs/faqs.md)** - Troubleshooting and common questions
 
 ## Demo

package/dist/bin/wa-pair.js

@@ -156,6 +156,8 @@ var MAX_PAIRING_RECONNECTS = 12;
 var PAIRING_RECONNECT_DELAY_MS = 2e3;
 var PAIRING_RECONNECT_MAX_DELAY_MS = 8e3;
 var RESTART_REQUIRED_DELAY_MS = 500;
+var REGISTERED_CONFIRM_TIMEOUT_MS = 15e3;
+var REGISTERED_CONFIRM_POLL_MS = 500;
 function pairingReconnectDelayMs(statusCode, attempt) {
   if (statusCode === RESTART_REQUIRED_STATUS) return RESTART_REQUIRED_DELAY_MS;
   return Math.min(
@@ -192,6 +194,41 @@ function runPairing(deps) {
       resolve(result);
     };
     const status = (message) => deps.onStatus?.(message);
+    const wait = (ms) => new Promise((resolve2) => {
+      schedule(() => resolve2(), ms);
+    });
+    let saves = Promise.resolve();
+    const queueSave = (saveCreds) => {
+      saves = saves.then(saveCreds).catch((error) => {
+        status(`Failed to save the session credentials: ${describeError(error)}`);
+      });
+    };
+    const flushSaves = async () => {
+      let awaited;
+      while (awaited !== saves) {
+        awaited = saves;
+        await awaited;
+      }
+    };
+    const confirmRegistered = async () => {
+      await flushSaves();
+      const verify = deps.verifyRegistered;
+      if (!verify) return true;
+      const pollMs = deps.registeredPollMs ?? REGISTERED_CONFIRM_POLL_MS;
+      const polls = Math.max(
+        1,
+        Math.ceil((deps.registeredTimeoutMs ?? REGISTERED_CONFIRM_TIMEOUT_MS) / pollMs)
+      );
+      for (let poll = 0; poll < polls; poll++) {
+        if (await verify()) return true;
+        if (poll === polls - 1) break;
+        if (poll === 0)
+          status("Link is open \u2014 waiting for the session to be saved as registered...");
+        await wait(pollMs);
+        await flushSaves();
+      }
+      return false;
+    };
     const requestCode = async (sock) => {
       if (settled || codeRequested || !deps.phoneNumber) return;
       try {
@@ -216,7 +253,15 @@ function runPairing(deps) {
         }
       }
       if (connection === "open") {
-        settle({ ok: true, userId: sock.user?.id });
+        if (await confirmRegistered()) {
+          settle({ ok: true, userId: sock.user?.id });
+        } else {
+          settle({
+            ok: false,
+            reason: "unregistered",
+            message: "The link opened but the stored session never read back as registered, so the server would not find it. Run wa-pair again (add --reset to pair from scratch)."
+          });
+        }
         return;
       }
       if (connection === "close") {
@@ -252,13 +297,29 @@ function runPairing(deps) {
       if (settled) return;
       const mine = generation;
       const attempt = attempts;
+      await flushSaves();
+      if (settled) return;
       let sock;
+      let saveCreds;
       try {
-        sock = await deps.connect(attempt);
+        const opened = await deps.connect(attempt);
+        if ("sock" in opened) {
+          sock = opened.sock;
+          saveCreds = opened.saveCreds;
+        } else {
+          sock = opened;
+        }
       } catch (error) {
         settle({ ok: false, reason: "error", message: describeError(error) });
         return;
       }
+      if (saveCreds) {
+        const save = saveCreds;
+        sock.ev.on("creds.update", () => {
+          if (settled || mine !== generation) return;
+          queueSave(save);
+        });
+      }
       sock.ev.on("connection.update", (update) => {
         if (mine !== generation || settled) return;
         handleUpdate(update, sock).catch((error) => {
@@ -418,11 +479,15 @@ async function start() {
       logger,
       markOnlineOnConnect: false
     });
-    sock.ev.on("creds.update", saveCreds);
-    return sock;
+    return { sock, saveCreds };
+  };
+  const storedIsRegistered = async () => {
+    const { state } = await useTursoAuthState(db, sessionSecret, sessionId, runtime);
+    return state.creds.registered === true;
   };
   const result = await runPairing({
     connect,
+    verifyRegistered: storedIsRegistered,
     loggedOutCode: baileys.DisconnectReason.loggedOut,
     phoneNumber,
     onQr: renderQr,
@@ -440,8 +505,10 @@ async function start() {
     console.error(`\u274C ${result.message}`);
     process.exit(1);
   }
-  console.log(`
-\u2705 Paired session "${sessionId}" as ${result.userId}. Session saved (encrypted).`);
+  console.log(
+    `
+\u2705 Paired session "${sessionId}" as ${result.userId}. Session saved (encrypted) and verified registered.`
+  );
   console.log("The running server will pick this session up on its next connect.");
   process.exit(0);
 }

package/dist/channels/whatsapp/pairing.d.ts

@@ -14,6 +14,15 @@
  * So a close during pairing is normal, not fatal: reconnect with stored creds,
  * bounded, until `open` confirms the link. Only an explicit logout or running
  * out of attempts ends the run.
+ *
+ * Credentials are persisted by this loop rather than by the caller's socket
+ * wiring, because the saves have to be ordered against the reconnects: the
+ * registration that a 515 interrupts is only useful if it reaches storage
+ * BEFORE the next attempt re-reads the session, and the flag that marks the
+ * session usable (`registered`) is often written by a `creds.update` that
+ * lands around or after `open`. A run therefore ends successfully only once
+ * the caller confirms — by reading storage back — that the stored session is
+ * registered.
  */
 /** Baileys' "restart required" — emitted immediately after a QR scan registers the device. */
 export declare const RESTART_REQUIRED_STATUS = 515;
@@ -52,7 +61,7 @@ export declare function decidePairingClose(input: PairingCloseInput): PairingClo
 /** The slice of a Baileys socket the pairing loop uses. */
 export interface PairingSocket {
     ev: {
-        on: (event: "connection.update", listener: (update: PairingConnectionUpdate) => void) => void;
+        on: (event: "connection.update" | "creds.update", listener: (update: PairingConnectionUpdate) => void) => void;
     };
     user?: {
         id?: string;
@@ -61,6 +70,16 @@ export interface PairingSocket {
     /** Closes a superseded socket so it stops writing to the session. */
     end?: (error?: Error) => void;
 }
+/**
+ * A socket plus the way to persist the credentials it mutates. Returning the
+ * pair (instead of wiring `creds.update` at the call site) lets the loop order
+ * saves against reconnects — see the module comment.
+ */
+export interface PairingAttempt {
+    sock: PairingSocket;
+    /** Writes this attempt's credentials to storage; called on every `creds.update`. */
+    saveCreds?: () => Promise<void>;
+}
 export interface PairingConnectionUpdate {
     connection?: string;
     qr?: string;
@@ -73,17 +92,29 @@ export type PairingResult = {
     userId?: string;
 } | {
     ok: false;
-    reason: "loggedOut" | "exhausted" | "error";
+    reason: "loggedOut" | "exhausted" | "error" | "unregistered";
     message: string;
 };
 export interface PairingRunDeps {
     /**
-     * Opens a socket for `attempt` (0 = first). MUST reuse the stored
+     * Opens a socket for `attempt` (0 = first). MUST re-read the stored
      * credentials — a reconnect that starts from blank creds shows a fresh QR
      * instead of finishing the link the phone is waiting on.
      */
-    connect: (attempt: number) => PairingSocket | Promise<PairingSocket>;
+    connect: (attempt: number) => PairingSocket | PairingAttempt | Promise<PairingSocket | PairingAttempt>;
     loggedOutCode: number;
+    /**
+     * Reads the STORED session back and answers whether it is registered — i.e.
+     * whether the server would find a usable session. Polled after `open` while
+     * late `creds.update` events are still being persisted; a run that never
+     * sees `true` fails with reason `unregistered` rather than claiming success
+     * over a session nothing can use. Omit to skip the check.
+     */
+    verifyRegistered?: () => boolean | Promise<boolean>;
+    /** How long to wait for the stored session to read back registered. */
+    registeredTimeoutMs?: number;
+    /** Gap between those reads. */
+    registeredPollMs?: number;
     /** Digits-only number for pairing-code mode; omit for QR mode. */
     phoneNumber?: string;
     maxAttempts?: number;

package/dist/channels/whatsapp/pairing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pairing.d.ts","sourceRoot":"","sources":["../../../src/channels/whatsapp/pairing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,8FAA8F;AAC9F,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAE3C,mFAAmF;AACnF,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAMzC;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAM/F;AAED,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACvD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,WAAW,GAAG,WAAW,CAAA;CAAE,CAAC;AAEzD,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,aAAa,EAAE,MAAM,CAAC;IACtB,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,iBAAiB,GAAG,kBAAkB,CAS/E;AAED,2DAA2D;AAC3D,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE;QACF,EAAE,EAAE,CAAC,KAAK,EAAE,mBAAmB,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,uBAAuB,KAAK,IAAI,KAAK,IAAI,CAAC;KAC/F,CAAC;IACF,IAAI,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9B,kBAAkB,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7D,qEAAqE;IACrE,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,KAAK,IAAI,CAAC;CAC/B;AAOD,MAAM,WAAW,uBAAuB;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,cAAc,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CAC7C;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,WAAW,GAAG,WAAW,GAAG,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhF,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACrE,aAAa,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mFAAmF;IACnF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,uDAAuD;IACvD,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,2EAA2E;IAC3E,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAuIvE"}
+{"version":3,"file":"pairing.d.ts","sourceRoot":"","sources":["../../../src/channels/whatsapp/pairing.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegoaltoworks/chatter",
-  "version": "0.40.0",
+  "version": "0.42.0",
   "description": "Embeddable AI chatbot framework with RAG, authentication, and customizable widgets",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",