baileys-antiban 3.5.0 → 3.6.0

package/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.6.0] - 2026-04-26
+
+### Added
+- Circadian timing curve in presenceChoreographer — typing/composing delays now scale with hour of day. Late-night messages get 4-6x slower presence to match human sleep patterns. Configurable via `circadian.profile` (default | nightOwl | earlyBird | always_on) and `circadian.timezone` (IANA).
+- Exported `getCircadianMultiplier(date, profile)` for downstream use.
+- Smooth cosine-based transitions between time periods (no stepped changes).
+- Circadian multiplier applied to typing durations, think pauses, read receipt delays.
+- Four built-in profiles: `default` (9-22 awake), `nightOwl` (+3hr shift), `earlyBird` (-2hr shift), `always_on` (flat 1.0 for 24/7 bots).
+- Timezone-aware hour calculation using `Intl.DateTimeFormat` for correct local time.
+
+### Why v3.6
+Per GapHunter competitive analysis, competitor `whatsapp-ai-framework` ships circadian response timing (slower at night). WhatsApp ban heuristics likely flag accounts that respond instantly at 04:00 AM. Real humans respond fast 09:00-22:00, slow late-night, near-zero 02:00-06:00. This release closes that gap.
+
 ## [3.5.0] — 2026-04-26
 
 ### Added

package/README.md

@@ -3,6 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/baileys-antiban.svg)](https://www.npmjs.com/package/baileys-antiban)
 [![Node.js Version](https://img.shields.io/node/v/baileys-antiban.svg)](https://nodejs.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![SLSA Provenance](https://img.shields.io/badge/SLSA-provenance%20signed-success?logo=sigstore)](https://github.com/kobie3717/baileys-antiban/actions/workflows/release.yml)
 [![Sister: baileys-keep-alive](https://img.shields.io/badge/sister-baileys--keep--alive-25D366)](https://github.com/kobie3717/baileys-keep-alive)
 
 **Drop-in anti-ban middleware for Baileys WhatsApp bots. Free, self-hosted, TypeScript-first. Whapi.Cloud alternative — zero monthly fees.**
@@ -11,6 +12,21 @@
 
 > **New in v3.3:** [LID Migration Guide](./docs/lid-migration.md) — survive Baileys v7's @lid default with stable thread keys.
 
+## Why Trust This Package
+
+The npm WhatsApp ecosystem has a malware problem. In April 2026, [`lotusbail`](https://www.koi.ai/blog/npm-package-with-56k-downloads-malware-stealing-whatsapp-messages) — an "anti-ban" package with 56,000 downloads — was confirmed to be exfiltrating session credentials and stealing WhatsApp messages. Picking the wrong package puts every user's chats and your business in someone else's pocket.
+
+`baileys-antiban` is built to be the answer to that risk:
+
+- **SLSA-signed releases** — every published version ships with a [Sigstore-verifiable provenance](https://github.com/kobie3717/baileys-antiban/actions/workflows/release.yml) chain. Tampering between source and registry is detectable.
+- **Zero telemetry** — no analytics, no remote config, no phone-home. The package never opens a network socket of its own. Audit `src/` and `dist/` and confirm.
+- **No obfuscated code** — published artifacts are readable, source-mapped TypeScript. No minified blobs hiding payloads.
+- **Minimal, pinned dependencies** — runtime deps listed in `package.json`, every one a known Baileys-ecosystem package.
+- **Open-source and auditable** — MIT-licensed. Every line at [github.com/kobie3717/baileys-antiban](https://github.com/kobie3717/baileys-antiban). 43+ stars, public review.
+- **Used in production** — powers [WhatsAuction](https://whatsauction.co.za) live. The author dogfoods this on his own customers' bots.
+
+If you can't read the code yourself, lean on these signals: signed releases, public audit trail, no telemetry, and a real product behind it. That's the floor. Everything below is the feature set.
+
 ## v2.0 New Features — Session Stability Module
 
 ### What's New in v2.0
@@ -447,6 +463,40 @@ await sock.sendMessage(jid, { text: messageText });
 5. Executes plan: fires `sendPresenceUpdate('composing'/'paused')` + sleeps for each step
 6. Supports AbortSignal for mid-plan cancellation
 
+#### Circadian Timing (v3.6+)
+
+Real humans respond fast during the day, slow at night, near-zero at 2-6 AM. WhatsApp's ban heuristics likely flag accounts that respond instantly at 04:00 AM. Circadian timing adds a day/night delay multiplier to all presence timings.
+
+```typescript
+import { wrapSocket } from 'baileys-antiban';
+
+const sock = wrapSocket(rawSock, {
+  presence: {
+    circadian: {
+      enabled: true,
+      profile: 'default',     // 'default' | 'nightOwl' | 'earlyBird' | 'always_on'
+      timezone: 'Africa/Johannesburg', // IANA timezone
+    },
+  },
+});
+```
+
+**Profiles:**
+- `default` — Awake 09:00-22:00, slow 22:00-02:00, dead zone 02:00-06:00 (4-6x slower), ramp 06:00-09:00
+- `nightOwl` — Peaks shifted +3hr (active until 02:00, dead 04:00-09:00)
+- `earlyBird` — Peaks shifted -2hr (active 06:00-20:00, dead 23:00-04:00)
+- `always_on` — Flat 1.0 multiplier (opt-out for 24/7 support bots)
+
+Multiplier is applied to typing durations, think pauses, and read receipt delays. Uses smooth cosine-based transitions (not stepped).
+
+**Direct usage:**
+```typescript
+import { getCircadianMultiplier } from 'baileys-antiban';
+
+const multiplier = getCircadianMultiplier(new Date(), 'default', 'Africa/Johannesburg');
+const adjustedDelay = baseDelay * multiplier;
+```
+
 **Why these features?** 2025-2026 ban research showed WhatsApp's ML models heavily weight reply-ratio (<10% = high risk), contact-graph distance (strangers = high risk), and temporal patterns (robotic timing = high risk). These modules address the three largest gaps in existing anti-ban libraries.
 
 ## baileys-antiban vs Whapi.Cloud vs DIY rate limiting
@@ -1110,6 +1160,21 @@ import type {
 
 Contributions are welcome! Please open an issue before submitting a PR.
 
+## Supply Chain Security
+
+This package is published from GitHub Actions with **npm provenance** via [sigstore](https://www.sigstore.dev/). Every release tag (`v*`) produces a signed attestation tying the published artifact back to the exact source commit + workflow run.
+
+To verify a downloaded version:
+
+```bash
+npm install baileys-antiban
+npm view baileys-antiban@<version> dist.integrity
+# or fetch the attestation:
+gh attestation verify $(npm pack baileys-antiban@<version>) --owner kobie3717
+```
+
+Inspired by post-lotusbail (Sept 2025, 56K-download supply chain attack on a baileys variant) — the only Baileys-ecosystem package shipping signed releases as of v3.5+.
+
 ## Related Projects
 
 - **[WaSP (WhatsApp Session Protocol)](https://github.com/kobie3717/wasp)** — Full-featured WhatsApp session management with built-in anti-ban (includes this library)

package/dist/index.d.ts

@@ -14,7 +14,7 @@ export { HealthMonitor, type HealthStatus, type HealthMonitorConfig, type BanRis
 export { TimelockGuard, type TimelockGuardConfig, type TimelockState } from './timelockGuard.js';
 export { ReplyRatioGuard, type ReplyRatioConfig, type ReplyRatioStats } from './replyRatio.js';
 export { ContactGraphWarmer, type ContactGraphConfig, type ContactGraphStats, type ContactState } from './contactGraph.js';
-export { PresenceChoreographer, type PresenceChoreographerConfig, type PresenceChoreographerStats, type TypingPlanStep } from './presenceChoreographer.js';
+export { PresenceChoreographer, type PresenceChoreographerConfig, type PresenceChoreographerStats, type TypingPlanStep, type CircadianProfile, getCircadianMultiplier, } from './presenceChoreographer.js';
 export { RetryReasonTracker, type RetryTrackerConfig, type RetryStats, type RetryReason } from './retryTracker.js';
 export { PostReconnectThrottle, type ReconnectThrottleConfig, type ReconnectThrottleStats } from './reconnectThrottle.js';
 export { LidResolver, type LidResolverConfig, type LidResolverStats, type LidMapping } from './lidResolver.js';

package/dist/index.js

@@ -16,7 +16,7 @@ export { TimelockGuard } from './timelockGuard.js';
 // v1.3 new modules
 export { ReplyRatioGuard } from './replyRatio.js';
 export { ContactGraphWarmer } from './contactGraph.js';
-export { PresenceChoreographer } from './presenceChoreographer.js';
+export { PresenceChoreographer, getCircadianMultiplier, } from './presenceChoreographer.js';
 // v1.5 new modules
 export { RetryReasonTracker } from './retryTracker.js';
 export { PostReconnectThrottle } from './reconnectThrottle.js';

package/dist/presenceChoreographer.d.ts

@@ -12,6 +12,7 @@
  * flagged at 3x rate vs accounts with circadian patterns. Human users have
  * 40-60% variance in hourly activity.
  */
+export type CircadianProfile = 'default' | 'nightOwl' | 'earlyBird' | 'always_on';
 export interface PresenceChoreographerConfig {
     /** Enable presence choreography (default: false — opt-in) */
     enabled?: boolean;
@@ -21,6 +22,12 @@ export interface PresenceChoreographerConfig {
     timezone?: string;
     /** Activity curve preset (default: 'office') */
     activityCurve?: 'office' | 'social' | 'global';
+    /** Circadian timing configuration (default: enabled with 'default' profile) */
+    circadian?: {
+        enabled?: boolean;
+        profile?: CircadianProfile;
+        timezone?: string;
+    };
     /** Probability (0-1) of distraction pause per send (default: 0.05 = 5%) */
     distractionPauseProbability?: number;
     /** Min distraction pause duration in ms (default: 300000 = 5min) */
@@ -73,6 +80,25 @@ export interface TypingPlanStep {
     state: 'composing' | 'paused';
     durationMs: number;
 }
+/**
+ * Get circadian delay multiplier based on hour of day.
+ * Returns a multiplier to apply to base delays (typing, presence, etc.).
+ *
+ * Multiplier ranges:
+ * - Awake hours (09:00-22:00): ~0.8-1.2 (near baseline)
+ * - Evening (22:00-00:00): 1.2 → 2.5
+ * - Late night (00:00-02:00): 2.5 → 4.0
+ * - Dead zone (02:00-06:00): 4.0-6.0 (peak slow)
+ * - Early morning (06:00-09:00): 4.0 → 1.0
+ *
+ * Uses cosine-based smooth transitions (not stepped).
+ *
+ * @param date - Date to check (uses hour from this)
+ * @param profile - Circadian profile ('default' | 'nightOwl' | 'earlyBird' | 'always_on')
+ * @param timezone - IANA timezone (optional, defaults to local)
+ * @returns Delay multiplier (0.5 = 2x faster, 2.0 = 2x slower, 5.0 = 5x slower)
+ */
+export declare function getCircadianMultiplier(date?: Date, profile?: CircadianProfile, timezone?: string): number;
 export declare class PresenceChoreographer {
     private config;
     private stats;
@@ -103,6 +129,7 @@ export declare class PresenceChoreographer {
      * Check if should mark message as read.
      * Returns { mark: false } if skip probability hit.
      * Returns { mark: true, delayMs: 5000 } otherwise.
+     * Applies circadian multiplier to delay.
      */
     shouldMarkRead(): {
         mark: boolean;
@@ -110,7 +137,7 @@ export declare class PresenceChoreographer {
     };
     /**
      * Compute realistic typing duration for a message of given length.
-     * Includes Gaussian WPM variance + think-pause injection.
+     * Includes Gaussian WPM variance + think-pause injection + circadian timing multiplier.
      * Returns a "typing plan": array of { state, durationMs } steps the caller should execute sequentially.
      *
      *   plan = [

package/dist/presenceChoreographer.js

@@ -17,6 +17,11 @@ const DEFAULT_CONFIG = {
     enableCircadianRhythm: true,
     timezone: 'UTC',
     activityCurve: 'office',
+    circadian: {
+        enabled: true,
+        profile: 'default',
+        timezone: 'UTC',
+    },
     distractionPauseProbability: 0.05,
     distractionPauseMinMs: 300000,
     distractionPauseMaxMs: 1200000,
@@ -72,6 +77,88 @@ const ACTIVITY_CURVES = {
         0.6, 0.5, 0.5, 0.5, 0.5, 0.5, // 19-24: night taper
     ],
 };
+/**
+ * Get circadian delay multiplier based on hour of day.
+ * Returns a multiplier to apply to base delays (typing, presence, etc.).
+ *
+ * Multiplier ranges:
+ * - Awake hours (09:00-22:00): ~0.8-1.2 (near baseline)
+ * - Evening (22:00-00:00): 1.2 → 2.5
+ * - Late night (00:00-02:00): 2.5 → 4.0
+ * - Dead zone (02:00-06:00): 4.0-6.0 (peak slow)
+ * - Early morning (06:00-09:00): 4.0 → 1.0
+ *
+ * Uses cosine-based smooth transitions (not stepped).
+ *
+ * @param date - Date to check (uses hour from this)
+ * @param profile - Circadian profile ('default' | 'nightOwl' | 'earlyBird' | 'always_on')
+ * @param timezone - IANA timezone (optional, defaults to local)
+ * @returns Delay multiplier (0.5 = 2x faster, 2.0 = 2x slower, 5.0 = 5x slower)
+ */
+export function getCircadianMultiplier(date = new Date(), profile = 'default', timezone) {
+    // always_on profile returns flat 1.0
+    if (profile === 'always_on') {
+        return 1.0;
+    }
+    // Get hour in specified timezone
+    let hour;
+    if (timezone) {
+        try {
+            const formatter = new Intl.DateTimeFormat('en-US', {
+                timeZone: timezone,
+                hour: 'numeric',
+                hour12: false,
+            });
+            const parts = formatter.formatToParts(date);
+            const hourPart = parts.find(p => p.type === 'hour');
+            hour = hourPart ? parseInt(hourPart.value, 10) : date.getHours();
+        }
+        catch {
+            hour = date.getHours();
+        }
+    }
+    else {
+        hour = date.getHours();
+    }
+    // Apply profile shift
+    let shiftedHour = hour;
+    if (profile === 'nightOwl') {
+        shiftedHour = (hour - 3 + 24) % 24; // shift +3hr (active until 02:00, dead 04:00-09:00)
+    }
+    else if (profile === 'earlyBird') {
+        shiftedHour = (hour + 2) % 24; // shift -2hr (active 06:00-20:00, dead 23:00-04:00)
+    }
+    // Cosine-based smooth curve
+    // Model: slow at night (02:00-06:00), fast during day (09:00-22:00)
+    // Use piecewise cosine for smooth transitions
+    if (shiftedHour >= 9 && shiftedHour < 22) {
+        // Awake hours: 09:00-22:00 — baseline ~0.8-1.2
+        // Add slight variance: cosine wave with period 13 hours
+        const t = (shiftedHour - 9) / 13;
+        return 1.0 + 0.2 * Math.cos(2 * Math.PI * t);
+    }
+    else if (shiftedHour >= 22 && shiftedHour < 24) {
+        // Evening: 22:00-00:00 — ramp 1.2 → 2.5
+        const t = (shiftedHour - 22) / 2;
+        return 1.2 + 1.3 * t;
+    }
+    else if (shiftedHour >= 0 && shiftedHour < 2) {
+        // Late night: 00:00-02:00 — ramp 2.5 → 4.0
+        const t = shiftedHour / 2;
+        return 2.5 + 1.5 * t;
+    }
+    else if (shiftedHour >= 2 && shiftedHour < 6) {
+        // Dead zone: 02:00-06:00 — peak slow 4.0-6.0
+        // Use cosine for smooth peak
+        const t = (shiftedHour - 2) / 4;
+        return 5.0 + 1.0 * Math.cos(Math.PI * t); // peaks at 6.0 around 04:00
+    }
+    else {
+        // Early morning: 06:00-09:00 — ramp 4.0 → 1.0
+        const t = (shiftedHour - 6) / 3;
+        return 4.0 - 3.0 * t;
+    }
+}
 export class PresenceChoreographer {
     config;
     stats = {
@@ -84,7 +171,14 @@ export class PresenceChoreographer {
         totalTypingTimeMs: 0,
     };
     constructor(config = {}) {
-        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.config = {
+            ...DEFAULT_CONFIG,
+            ...config,
+            circadian: {
+                ...DEFAULT_CONFIG.circadian,
+                ...(config.circadian || {}),
+            },
+        };
     }
     /**
      * Get current activity factor (0.1 to 1.0).
@@ -133,6 +227,7 @@ export class PresenceChoreographer {
      * Check if should mark message as read.
      * Returns { mark: false } if skip probability hit.
      * Returns { mark: true, delayMs: 5000 } otherwise.
+     * Applies circadian multiplier to delay.
      */
     shouldMarkRead() {
         if (!this.config.enabled) {
@@ -144,13 +239,19 @@ export class PresenceChoreographer {
             return { mark: false, delayMs: 0 };
         }
         // Delayed read receipt
-        const delayMs = this.randomBetween(this.config.readReceiptDelayMinMs, this.config.readReceiptDelayMaxMs);
+        const baseDelayMs = this.randomBetween(this.config.readReceiptDelayMinMs, this.config.readReceiptDelayMaxMs);
+        // Apply circadian multiplier if enabled
+        let delayMs = baseDelayMs;
+        if (this.config.circadian.enabled) {
+            const circadianMultiplier = getCircadianMultiplier(new Date(), this.config.circadian.profile, this.config.circadian.timezone);
+            delayMs = Math.floor(baseDelayMs * circadianMultiplier);
+        }
         this.stats.readReceiptsDelayed++;
         return { mark: true, delayMs };
     }
     /**
      * Compute realistic typing duration for a message of given length.
-     * Includes Gaussian WPM variance + think-pause injection.
+     * Includes Gaussian WPM variance + think-pause injection + circadian timing multiplier.
      * Returns a "typing plan": array of { state, durationMs } steps the caller should execute sequentially.
      *
      *   plan = [
@@ -175,9 +276,14 @@ export class PresenceChoreographer {
         const cps = (wpmSample * 5) / 60;
         // 3. Base typing time
         const baseMs = (messageLength / cps) * 1000;
-        // 4. Clamp to min/max
-        const targetMs = this.clamp(baseMs, this.config.typingMinMs, this.config.typingMaxMs);
-        // 5. Build plan with think pauses
+        // 4. Apply circadian multiplier if enabled
+        let circadianMultiplier = 1.0;
+        if (this.config.circadian.enabled) {
+            circadianMultiplier = getCircadianMultiplier(new Date(), this.config.circadian.profile, this.config.circadian.timezone);
+        }
+        // 5. Clamp to min/max
+        const targetMs = this.clamp(baseMs * circadianMultiplier, this.config.typingMinMs, this.config.typingMaxMs);
+        // 6. Build plan with think pauses
         const plan = [];
         let remainingBudget = targetMs;
         let position = 0;
@@ -197,8 +303,9 @@ export class PresenceChoreographer {
                 // Add composing step
                 plan.push({ state: 'composing', durationMs: chunkTypingMs });
                 remainingBudget -= chunkTypingMs;
-                // Add think pause (don't subtract from typing budget)
-                const pauseMs = this.randomBetween(this.config.thinkPauseMinMs, this.config.thinkPauseMaxMs);
+                // Add think pause (apply circadian multiplier to pause durations too)
+                const basePauseMs = this.randomBetween(this.config.thinkPauseMinMs, this.config.thinkPauseMaxMs);
+                const pauseMs = Math.floor(basePauseMs * circadianMultiplier);
                 plan.push({ state: 'paused', durationMs: pauseMs });
             }
             else {
@@ -213,12 +320,13 @@ export class PresenceChoreographer {
             }
             position += charsInChunk;
         }
-        // 6. Optional final pause before send
+        // 7. Optional final pause before send (apply circadian multiplier)
         if (Math.random() < this.config.intermittentPausedProbability) {
-            const finalPauseMs = this.randomBetween(200, 800);
+            const baseFinalPauseMs = this.randomBetween(200, 800);
+            const finalPauseMs = Math.floor(baseFinalPauseMs * circadianMultiplier);
             plan.push({ state: 'paused', durationMs: finalPauseMs });
         }
-        // Ensure we have at least one composing step
+        // 8. Ensure we have at least one composing step
         if (plan.length === 0 || !plan.some(step => step.state === 'composing')) {
             return [{ state: 'composing', durationMs: this.config.typingMinMs }];
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baileys-antiban",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "description": "Anti-ban middleware for Baileys WhatsApp bots. Rate limiting, warmup, health monitor, LID resolver, disconnect classifier. Free Whapi.Cloud alternative.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",