baileys-antiban 3.7.0 → 3.8.1

package/CHANGELOG.md

@@ -5,6 +5,33 @@ 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.8.1] - 2026-04-28
+
+### Fixed
+- **`getStealthSocketConfig({ os })` now propagates `os` properly.** v3.8.0 silently dropped the value (placeholder no-op spread). The `os` opt rewrites the first slot of the resulting browser tuple as documented.
+- **Browser fingerprint randomized.** v3.8.0 hardcoded `['Ubuntu', 'Chrome', '20.0.04']` for every consumer — identical fingerprint across the install base is trivially cluster-able by WhatsApp. Now picks at random from `STEALTH_BROWSER_POOL`, a frozen array of realistic Mac/Windows/Linux Chrome/Safari/Firefox/Edge tuples with real-world version strings. Pool is exported so callers can extend or override.
+- **`rampPresenceAfterConnect()` accepts `AbortSignal`.** v3.8.0 had no way to cancel the pending timer; if the socket disconnected during the ramp window the post-delay `sendPresenceUpdate` would run against a dead socket. New `signal` option causes the returned promise to reject with `AbortError` when aborted, and clears the timer.
+- **Structural types instead of `any`.** `sock` parameter now typed as `PresenceCapableSocket` (matches `presenceChoreographer.ts`). `getStealthSocketConfig()` returns a typed `StealthSocketConfig`. Consumers get autocomplete on `markOnlineOnConnect` / `browser`.
+- JSDoc claims corrected — removed phantom `os` default value.
+
+### Added
+- `STEALTH_BROWSER_POOL` (named export) — frozen pool of realistic browser tuples used by `getStealthSocketConfig()`.
+- `AbortError` (named export) — thrown when `rampPresenceAfterConnect` is aborted via signal. Mirrors DOM `AbortError` semantics.
+- New typed exports: `BrowserTuple`, `StealthSocketConfig`, `GetStealthSocketConfigOptions`, `RampPresenceOptions`, `PresenceCapableSocket`.
+- `random` opt on both helpers — inject custom RNG (useful for deterministic tests).
+- `browser` opt on `getStealthSocketConfig()` — supply an explicit tuple. Takes precedence over `os` and the pool.
+
+### Migration
+- v3.8.0 → v3.8.1 is non-breaking. The shape of the returned config is unchanged at runtime; the default browser tuple is now random rather than fixed. If you depended on the exact `['Ubuntu', 'Chrome', '20.0.04']` value, pass it explicitly via `browser: ['Ubuntu', 'Chrome', '20.0.04']`.
+
+## [3.8.0] - 2026-04-28
+
+### Added
+- **Stealth Connect** — Gradual presence ramp to reduce ban signals. Inspired by GOWA's `--presence-on-connect=unavailable` flag. Bots that instantly snap online and start blasting messages look suspicious. New helpers:
+  - `getStealthSocketConfig({ os?: string })` — returns socket config with `markOnlineOnConnect: false` and sensible browser defaults.
+  - `rampPresenceAfterConnect(sock, { minDelayMs?, maxDelayMs?, targetState? })` — waits 30-90s (configurable), then transitions presence to `available` (or custom state). Call after socket connects. Returns a promise.
+- Use together: connect silently, ramp presence gradually when ready to act.
+
 ## [3.7.0] - 2026-04-27
 
 ### Added

package/README.md

@@ -599,6 +599,44 @@ npx baileys-antiban warmup --simulate 7 --preset moderate
 npx baileys-antiban reset --state ./antiban-state.json
 ```
 
+### Stealth Connect (v3.8.1)
+
+Bots that instantly snap online and start blasting messages look suspicious. Stealth connect joins WhatsApp without broadcasting `available`, then delays the presence ramp so the socket looks more like a human session.
+
+```typescript
+import { makeWASocket } from '@whiskeysockets/baileys';
+import {
+  getStealthSocketConfig,
+  rampPresenceAfterConnect,
+  AbortError,
+} from 'baileys-antiban';
+
+// Random fingerprint from STEALTH_BROWSER_POOL + markOnlineOnConnect: false.
+// Pass `os` to rebrand the OS slot, or `browser: [...]` to supply an explicit tuple.
+const config = getStealthSocketConfig({ os: 'My Custom App' });
+const sock = makeWASocket({ ...config, auth: state });
+
+// Cancel the pending ramp if the socket dies before the timer fires.
+const ac = new AbortController();
+sock.ev.on('connection.update', (u) => {
+  if (u.connection === 'close') ac.abort();
+});
+
+try {
+  await rampPresenceAfterConnect(sock, {
+    minDelayMs: 45000,
+    maxDelayMs: 120000,
+    signal: ac.signal,
+  });
+} catch (err) {
+  if (err instanceof AbortError) {
+    // socket disconnected before ramp fired — swallow
+  } else {
+    throw err;
+  }
+}
+```
+
 ## Quick Start (Legacy)
 
 ### Option 1: Wrap Your Socket (Easiest)

package/dist/index.d.ts

@@ -36,3 +36,5 @@ export { generateFingerprint, applyFingerprint, type DeviceFingerprint, type Dev
 export { credsSnapshot, type CredsSnapshot, type CredsSnapshotConfig, } from './credsSnapshot.js';
 export { readReceiptVariance, type ReadReceiptVariance, type ReadReceiptVarianceConfig, } from './readReceiptVariance.js';
 export { proxyRotator, type ProxyEndpoint, type ProxyRotatorConfig, type ProxyRotatorStats, type ProxyRotatorHandle, } from './proxyRotator.js';
+export { generateSessionFingerprint, applySessionFingerprint, getMessageSendJitter, getTypingJitter, getRetryJitter, getVoiceNoteMetadata, getBatteryState, createStealthFingerprint, type SessionFingerprint, type SessionFingerprintConfig, } from './sessionFingerprint.js';
+export { getStealthSocketConfig, rampPresenceAfterConnect, STEALTH_BROWSER_POOL, AbortError, type BrowserTuple, type StealthSocketConfig, type GetStealthSocketConfigOptions, type RampPresenceOptions, type PresenceCapableSocket, } from './stealthConnect.js';

package/dist/index.js

@@ -49,3 +49,7 @@ export { credsSnapshot, } from './credsSnapshot.js';
 export { readReceiptVariance, } from './readReceiptVariance.js';
 // v3.5 new modules
 export { proxyRotator, } from './proxyRotator.js';
+// v3.6 new modules (Obscura-inspired)
+export { generateSessionFingerprint, applySessionFingerprint, getMessageSendJitter, getTypingJitter, getRetryJitter, getVoiceNoteMetadata, getBatteryState, createStealthFingerprint, } from './sessionFingerprint.js';
+// v3.8 new modules
+export { getStealthSocketConfig, rampPresenceAfterConnect, STEALTH_BROWSER_POOL, AbortError, } from './stealthConnect.js';

package/dist/sessionFingerprint.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Session Fingerprint Randomization (Obscura-inspired)
+ *
+ * Per-session fingerprint randomization to prevent device tracking.
+ * Scavenged patterns from Obscura headless browser's stealth mode.
+ *
+ * Key principles from Obscura:
+ * 1. Per-session randomization (not per-request)
+ * 2. Consistent within session (same session = same fingerprint)
+ * 3. Feature-flag pattern for optional anti-detection
+ * 4. Emulation of real device profiles (not synthetic values)
+ *
+ * Browser fingerprint → WhatsApp signal mapping:
+ * - TLS fingerprint → WA protocol version
+ * - Canvas noise → message timing jitter
+ * - Audio fingerprint → voice note metadata
+ * - GPU info → device model/brand
+ * - Battery → connection state variation
+ * - User agent → WA client version
+ *
+ * @author Kobus Wentzel <kobie@pop.co.za>
+ * @license MIT
+ */
+import { type DeviceFingerprint } from './deviceFingerprint.js';
+export interface SessionFingerprintConfig {
+    /** Master switch for enhanced fingerprinting */
+    enabled?: boolean;
+    /** Device profile randomization (from deviceFingerprint.ts) */
+    deviceProfile?: {
+        randomizeAppVersion?: boolean;
+        randomizeOsVersion?: boolean;
+        randomizeDeviceModel?: boolean;
+        appVersionPool?: number[][];
+        osVersionPool?: string[];
+        deviceModelPool?: string[];
+    };
+    /** Network timing variance (anti-pattern detection) */
+    networkTiming?: {
+        /** Add jitter to message send timing (ms) */
+        sendJitterMs?: [number, number];
+        /** Add jitter to typing indicators (ms) */
+        typingJitterMs?: [number, number];
+        /** Vary connection retry backoff */
+        retryJitterMs?: [number, number];
+    };
+    /** Voice note metadata randomization */
+    voiceNote?: {
+        /** Vary waveform pattern slightly */
+        randomizeWaveform?: boolean;
+        /** Vary duration by small amount (ms) */
+        durationJitterMs?: number;
+        /** Randomize sample rate from pool */
+        sampleRatePool?: number[];
+    };
+    /** Connection state variance */
+    connectionState?: {
+        /** Vary idle timeout */
+        idleTimeoutJitterMs?: [number, number];
+        /** Vary keepalive interval */
+        keepaliveJitterMs?: [number, number];
+        /** Randomize battery state reported */
+        randomizeBattery?: boolean;
+        /** Battery level pool (0-100) */
+        batteryLevelPool?: number[];
+    };
+    /** Protocol version variance */
+    protocolVersion?: {
+        /** Randomize protocol sub-version */
+        randomizeSubVersion?: boolean;
+        /** Protocol version pool (e.g., different patch versions) */
+        versionPool?: string[];
+    };
+    /** Seed for deterministic randomization (testing/debugging) */
+    seed?: string;
+}
+export interface SessionFingerprint {
+    /** Core device profile */
+    device: DeviceFingerprint;
+    /** Network timing variances (stable per session) */
+    networkTiming: {
+        sendJitterMs: number;
+        typingJitterMs: number;
+        retryJitterMs: number;
+    };
+    /** Voice note profile */
+    voiceNote: {
+        waveformSeed: number;
+        durationJitterMs: number;
+        sampleRate: number;
+    };
+    /** Connection state profile */
+    connectionState: {
+        idleTimeoutMs: number;
+        keepaliveMs: number;
+        batteryLevel: number;
+        batteryCharging: boolean;
+    };
+    /** Protocol version */
+    protocolVersion: string;
+    /** Session identifier (stable for this fingerprint) */
+    sessionId: string;
+    /** Timestamp when fingerprint was generated */
+    createdAt: number;
+}
+/**
+ * Generate a comprehensive session fingerprint.
+ * Call once per session (socket initialization).
+ *
+ * Obscura pattern: consistent per session, randomized across sessions.
+ */
+export declare function generateSessionFingerprint(config?: SessionFingerprintConfig, sessionId?: string): SessionFingerprint;
+/**
+ * Apply session fingerprint to Baileys socket config.
+ *
+ * Usage:
+ *   const fingerprint = generateSessionFingerprint({ enabled: true });
+ *   const sock = makeWASocket(applySessionFingerprint(config, fingerprint));
+ */
+export declare function applySessionFingerprint(socketConfig: any, fingerprint: SessionFingerprint): any;
+/**
+ * Get timing jitter for message send (helper for presenceChoreographer/rateLimiter)
+ *
+ * Usage in beforeSend():
+ *   const jitter = getMessageSendJitter(fingerprint);
+ *   await sleep(baseDelay + jitter);
+ */
+export declare function getMessageSendJitter(fingerprint: SessionFingerprint): number;
+/**
+ * Get typing indicator jitter (helper for presenceChoreographer)
+ */
+export declare function getTypingJitter(fingerprint: SessionFingerprint): number;
+/**
+ * Get retry backoff jitter (helper for reconnectThrottle)
+ */
+export declare function getRetryJitter(fingerprint: SessionFingerprint): number;
+/**
+ * Get voice note metadata (helper for voice message encoding)
+ *
+ * Returns suggested sample rate and duration adjustment based on session fingerprint.
+ */
+export declare function getVoiceNoteMetadata(fingerprint: SessionFingerprint): {
+    sampleRate: number;
+    durationJitterMs: number;
+    waveformSeed: number;
+};
+/**
+ * Get battery state (helper for presence/connection state signals)
+ */
+export declare function getBatteryState(fingerprint: SessionFingerprint): {
+    level: number;
+    charging: boolean;
+};
+/**
+ * Create a session fingerprint preset (Obscura-inspired feature flag pattern)
+ */
+export declare function createStealthFingerprint(sessionId?: string): SessionFingerprint;

package/dist/sessionFingerprint.js

@@ -0,0 +1,248 @@
+/**
+ * Session Fingerprint Randomization (Obscura-inspired)
+ *
+ * Per-session fingerprint randomization to prevent device tracking.
+ * Scavenged patterns from Obscura headless browser's stealth mode.
+ *
+ * Key principles from Obscura:
+ * 1. Per-session randomization (not per-request)
+ * 2. Consistent within session (same session = same fingerprint)
+ * 3. Feature-flag pattern for optional anti-detection
+ * 4. Emulation of real device profiles (not synthetic values)
+ *
+ * Browser fingerprint → WhatsApp signal mapping:
+ * - TLS fingerprint → WA protocol version
+ * - Canvas noise → message timing jitter
+ * - Audio fingerprint → voice note metadata
+ * - GPU info → device model/brand
+ * - Battery → connection state variation
+ * - User agent → WA client version
+ *
+ * @author Kobus Wentzel <kobie@pop.co.za>
+ * @license MIT
+ */
+import { generateFingerprint } from './deviceFingerprint.js';
+/**
+ * Simple deterministic PRNG using mulberry32
+ * Same as deviceFingerprint.ts for consistency
+ */
+class SeededRandom {
+    state;
+    constructor(seed) {
+        let hash = 0;
+        for (let i = 0; i < seed.length; i++) {
+            hash = (hash << 5) - hash + seed.charCodeAt(i);
+            hash = hash & hash;
+        }
+        this.state = Math.abs(hash) || 1;
+    }
+    next() {
+        let t = (this.state += 0x6d2b79f5);
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    }
+    range(min, max) {
+        return Math.floor(this.next() * (max - min + 1)) + min;
+    }
+    rangeFloat(min, max) {
+        return this.next() * (max - min) + min;
+    }
+    pick(array) {
+        return array[Math.floor(this.next() * array.length)];
+    }
+    boolean(probability = 0.5) {
+        return this.next() < probability;
+    }
+}
+// Default configuration values (conservative, realistic)
+const DEFAULT_SEND_JITTER_MS = [50, 300];
+const DEFAULT_TYPING_JITTER_MS = [30, 150];
+const DEFAULT_RETRY_JITTER_MS = [100, 500];
+const DEFAULT_DURATION_JITTER_MS = 200;
+const DEFAULT_SAMPLE_RATE_POOL = [8000, 16000, 44100, 48000];
+const DEFAULT_IDLE_TIMEOUT_JITTER_MS = [25000, 35000];
+const DEFAULT_KEEPALIVE_JITTER_MS = [15000, 25000];
+const DEFAULT_BATTERY_LEVEL_POOL = [20, 35, 50, 65, 80, 95, 100];
+const DEFAULT_PROTOCOL_VERSION_POOL = ['2.24.5', '2.24.4', '2.24.3'];
+/**
+ * Generate a comprehensive session fingerprint.
+ * Call once per session (socket initialization).
+ *
+ * Obscura pattern: consistent per session, randomized across sessions.
+ */
+export function generateSessionFingerprint(config = {}, sessionId) {
+    const { enabled = true, deviceProfile = {}, networkTiming = {}, voiceNote = {}, connectionState = {}, protocolVersion = {}, seed, } = config;
+    const finalSessionId = sessionId || `session-${Date.now()}-${Math.random()}`;
+    const rng = new SeededRandom(seed || finalSessionId);
+    // Generate base device fingerprint (delegates to deviceFingerprint.ts)
+    const device = generateFingerprint({
+        enabled,
+        randomizeAppVersion: deviceProfile.randomizeAppVersion ?? true,
+        randomizeOsVersion: deviceProfile.randomizeOsVersion ?? true,
+        randomizeDeviceModel: deviceProfile.randomizeDeviceModel ?? true,
+        seed: seed || finalSessionId,
+        appVersionPool: deviceProfile.appVersionPool,
+        osVersionPool: deviceProfile.osVersionPool,
+        deviceModelPool: deviceProfile.deviceModelPool,
+    }, finalSessionId);
+    // Network timing variances (Obscura: prevent timing pattern detection)
+    const sendJitterRange = networkTiming.sendJitterMs || DEFAULT_SEND_JITTER_MS;
+    const typingJitterRange = networkTiming.typingJitterMs || DEFAULT_TYPING_JITTER_MS;
+    const retryJitterRange = networkTiming.retryJitterMs || DEFAULT_RETRY_JITTER_MS;
+    const networkTimingProfile = enabled
+        ? {
+            sendJitterMs: rng.range(sendJitterRange[0], sendJitterRange[1]),
+            typingJitterMs: rng.range(typingJitterRange[0], typingJitterRange[1]),
+            retryJitterMs: rng.range(retryJitterRange[0], retryJitterRange[1]),
+        }
+        : {
+            sendJitterMs: 0,
+            typingJitterMs: 0,
+            retryJitterMs: 0,
+        };
+    // Voice note profile (Obscura: audio fingerprint variance)
+    const sampleRatePool = voiceNote.sampleRatePool || DEFAULT_SAMPLE_RATE_POOL;
+    const voiceNoteProfile = {
+        waveformSeed: enabled ? rng.range(0, 2147483647) : 0,
+        durationJitterMs: enabled && voiceNote.randomizeWaveform !== false
+            ? rng.range(0, voiceNote.durationJitterMs || DEFAULT_DURATION_JITTER_MS)
+            : 0,
+        sampleRate: enabled ? rng.pick(sampleRatePool) : sampleRatePool[0],
+    };
+    // Connection state profile (Obscura: battery/network state variance)
+    const idleTimeoutRange = connectionState.idleTimeoutJitterMs || DEFAULT_IDLE_TIMEOUT_JITTER_MS;
+    const keepaliveRange = connectionState.keepaliveJitterMs || DEFAULT_KEEPALIVE_JITTER_MS;
+    const batteryLevelPool = connectionState.batteryLevelPool || DEFAULT_BATTERY_LEVEL_POOL;
+    const connectionStateProfile = {
+        idleTimeoutMs: enabled
+            ? rng.range(idleTimeoutRange[0], idleTimeoutRange[1])
+            : 30000,
+        keepaliveMs: enabled
+            ? rng.range(keepaliveRange[0], keepaliveRange[1])
+            : 20000,
+        batteryLevel: enabled && connectionState.randomizeBattery !== false
+            ? rng.pick(batteryLevelPool)
+            : 100,
+        batteryCharging: enabled ? rng.boolean(0.3) : false, // 30% charging probability
+    };
+    // Protocol version (Obscura: TLS fingerprint variance → WA protocol variance)
+    const versionPool = protocolVersion.versionPool || DEFAULT_PROTOCOL_VERSION_POOL;
+    const protocolVersionStr = enabled && protocolVersion.randomizeSubVersion !== false
+        ? rng.pick(versionPool)
+        : versionPool[0];
+    return {
+        device,
+        networkTiming: networkTimingProfile,
+        voiceNote: voiceNoteProfile,
+        connectionState: connectionStateProfile,
+        protocolVersion: protocolVersionStr,
+        sessionId: finalSessionId,
+        createdAt: Date.now(),
+    };
+}
+/**
+ * Apply session fingerprint to Baileys socket config.
+ *
+ * Usage:
+ *   const fingerprint = generateSessionFingerprint({ enabled: true });
+ *   const sock = makeWASocket(applySessionFingerprint(config, fingerprint));
+ */
+export function applySessionFingerprint(socketConfig, fingerprint) {
+    const config = { ...socketConfig };
+    // Apply device profile (appVersion, browser tuple)
+    config.version = fingerprint.device.appVersion;
+    config.browser = [
+        fingerprint.device.deviceModel,
+        fingerprint.device.osVersion,
+        `WhatsApp/${fingerprint.device.appVersion.join('.')}`,
+    ];
+    // Apply connection timeouts if fields exist
+    if ('connectTimeoutMs' in config || config.connectTimeoutMs !== undefined) {
+        // Add idle timeout jitter to connection config
+        config.connectTimeoutMs = fingerprint.connectionState.idleTimeoutMs;
+    }
+    // Apply keepalive if supported
+    if ('keepAliveIntervalMs' in config || config.keepAliveIntervalMs !== undefined) {
+        config.keepAliveIntervalMs = fingerprint.connectionState.keepaliveMs;
+    }
+    // Store fingerprint for runtime access (helpers can read this)
+    config.__sessionFingerprint = fingerprint;
+    return config;
+}
+/**
+ * Get timing jitter for message send (helper for presenceChoreographer/rateLimiter)
+ *
+ * Usage in beforeSend():
+ *   const jitter = getMessageSendJitter(fingerprint);
+ *   await sleep(baseDelay + jitter);
+ */
+export function getMessageSendJitter(fingerprint) {
+    // Return a random value within ±50% of the session's base jitter
+    // This adds per-message variance while staying within session profile
+    const base = fingerprint.networkTiming.sendJitterMs;
+    return Math.floor(base * 0.5 + Math.random() * base * 0.5);
+}
+/**
+ * Get typing indicator jitter (helper for presenceChoreographer)
+ */
+export function getTypingJitter(fingerprint) {
+    const base = fingerprint.networkTiming.typingJitterMs;
+    return Math.floor(base * 0.5 + Math.random() * base * 0.5);
+}
+/**
+ * Get retry backoff jitter (helper for reconnectThrottle)
+ */
+export function getRetryJitter(fingerprint) {
+    const base = fingerprint.networkTiming.retryJitterMs;
+    return Math.floor(base * 0.5 + Math.random() * base * 0.5);
+}
+/**
+ * Get voice note metadata (helper for voice message encoding)
+ *
+ * Returns suggested sample rate and duration adjustment based on session fingerprint.
+ */
+export function getVoiceNoteMetadata(fingerprint) {
+    return {
+        sampleRate: fingerprint.voiceNote.sampleRate,
+        durationJitterMs: fingerprint.voiceNote.durationJitterMs,
+        waveformSeed: fingerprint.voiceNote.waveformSeed,
+    };
+}
+/**
+ * Get battery state (helper for presence/connection state signals)
+ */
+export function getBatteryState(fingerprint) {
+    return {
+        level: fingerprint.connectionState.batteryLevel,
+        charging: fingerprint.connectionState.batteryCharging,
+    };
+}
+/**
+ * Create a session fingerprint preset (Obscura-inspired feature flag pattern)
+ */
+export function createStealthFingerprint(sessionId) {
+    return generateSessionFingerprint({
+        enabled: true,
+        deviceProfile: {
+            randomizeAppVersion: true,
+            randomizeOsVersion: true,
+            randomizeDeviceModel: true,
+        },
+        networkTiming: {
+            sendJitterMs: [100, 500],
+            typingJitterMs: [50, 200],
+            retryJitterMs: [200, 800],
+        },
+        voiceNote: {
+            randomizeWaveform: true,
+            durationJitterMs: 300,
+        },
+        connectionState: {
+            randomizeBattery: true,
+        },
+        protocolVersion: {
+            randomizeSubVersion: true,
+        },
+    }, sessionId);
+}

package/dist/stealthConnect.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Stealth Connect — Reduce ban signal on socket connect + presence ramp
+ *
+ * Inspired by GOWA's --presence-on-connect=unavailable flag. Bots that
+ * snap online immediately and start blasting messages look suspicious to
+ * WhatsApp's anti-spam classifier. This module ships two helpers:
+ *
+ *   - `getStealthSocketConfig()` returns a partial Baileys socket config
+ *     that disables `markOnlineOnConnect` and provides a non-default
+ *     browser fingerprint (random pick from a small pool unless overridden).
+ *
+ *   - `rampPresenceAfterConnect()` waits a randomized delay, then issues
+ *     `sendPresenceUpdate('available')`. Supports `AbortSignal` so the
+ *     caller can cancel if the socket dies before the timer fires.
+ *
+ * Usage:
+ *   const config = getStealthSocketConfig({ os: 'MyApp' });
+ *   const sock = makeWASocket({ ...config, auth: state });
+ *
+ *   const ac = new AbortController();
+ *   sock.ev.on('connection.update', u => {
+ *     if (u.connection === 'close') ac.abort();
+ *   });
+ *   await rampPresenceAfterConnect(sock, { signal: ac.signal });
+ */
+/**
+ * Browser tuple expected by Baileys: [appName, browserName, browserVersion].
+ */
+export type BrowserTuple = [string, string, string];
+/**
+ * Pool of realistic browser fingerprints.
+ *
+ * Values match formats actually emitted by WhatsApp Web clients in the wild.
+ * `getStealthSocketConfig()` picks one at random when caller does not supply
+ * an explicit `browser` or `os` option, so multiple consumers of the library
+ * do not all advertise an identical fingerprint (which would be trivially
+ * cluster-able by WhatsApp).
+ *
+ * Exported so callers can extend or override the pool if desired.
+ */
+export declare const STEALTH_BROWSER_POOL: readonly BrowserTuple[];
+/**
+ * Minimum structural shape a stealth socket config consumer needs.
+ * Avoids a hard dependency on Baileys' internal type names while still
+ * giving consumers TypeScript autocomplete on the keys we actually set.
+ */
+export interface StealthSocketConfig {
+    /** Whether Baileys broadcasts `available` presence on initial connect. */
+    markOnlineOnConnect: boolean;
+    /** Browser tuple sent during the WhatsApp Web pairing handshake. */
+    browser: BrowserTuple;
+}
+/**
+ * Options for `getStealthSocketConfig()`.
+ *
+ * Precedence: `browser` > `os` > random pick from `STEALTH_BROWSER_POOL`.
+ */
+export interface GetStealthSocketConfigOptions {
+    /**
+     * Override the OS / app name slot of the browser tuple. If supplied
+     * without `browser`, the OS replaces the first element of a randomly
+     * picked tuple — `[os, browser, version]`.
+     */
+    os?: string;
+    /**
+     * Provide an explicit browser tuple. When set, takes precedence over
+     * `os` and the pool. Use this if you have a fingerprint you trust.
+     */
+    browser?: BrowserTuple;
+    /**
+     * Custom RNG. Defaults to `Math.random`. Useful for tests.
+     */
+    random?: () => number;
+}
+/**
+ * Returns a partial Baileys socket config tuned for stealth connect.
+ *
+ * - `markOnlineOnConnect` set to `false` so the socket joins without
+ *   broadcasting `available` (matches GOWA's `presence-on-connect=unavailable`).
+ * - `browser` is a randomized realistic tuple from `STEALTH_BROWSER_POOL`
+ *   unless overridden via `opts.browser` or `opts.os`.
+ *
+ * Merge the result into your `makeWASocket` options:
+ *
+ *   const sock = makeWASocket({ ...getStealthSocketConfig(), auth: state });
+ */
+export declare function getStealthSocketConfig(opts?: GetStealthSocketConfigOptions): StealthSocketConfig;
+/**
+ * Minimal structural type for the socket consumed by `rampPresenceAfterConnect`.
+ * Matches the shape used elsewhere in this library (e.g. `presenceChoreographer`).
+ */
+export interface PresenceCapableSocket {
+    sendPresenceUpdate: (state: string, jid?: string) => Promise<void> | void;
+}
+/**
+ * Options for `rampPresenceAfterConnect()`.
+ */
+export interface RampPresenceOptions {
+    /** Minimum delay before issuing the presence update, ms. Default: 30000. */
+    minDelayMs?: number;
+    /** Maximum delay before issuing the presence update, ms. Default: 90000. */
+    maxDelayMs?: number;
+    /** Presence state to set after the delay. Default: `'available'`. */
+    targetState?: 'available' | 'unavailable' | 'composing' | 'recording' | 'paused';
+    /**
+     * If set, cancels the pending timer and prevents the presence update.
+     * Use this when the socket disconnects before the ramp fires.
+     * Aborting causes the returned promise to reject with `AbortError`.
+     */
+    signal?: AbortSignal;
+    /** Custom RNG. Defaults to `Math.random`. Useful for tests. */
+    random?: () => number;
+}
+/**
+ * Custom error thrown when `rampPresenceAfterConnect` is aborted via signal.
+ * Mirrors DOM `AbortError` semantics so consumers can `instanceof` check.
+ */
+export declare class AbortError extends Error {
+    name: string;
+    constructor(message?: string);
+}
+/**
+ * Waits a randomized delay then calls `sock.sendPresenceUpdate(targetState)`.
+ *
+ * Supports `AbortSignal` — abort during the delay window cancels the timer
+ * and rejects the returned promise with `AbortError`. Aborting after the
+ * presence update has already been sent is a no-op.
+ *
+ * Caller is responsible for invoking abort when the socket disconnects;
+ * otherwise the post-delay `sendPresenceUpdate` may run against a dead
+ * socket.
+ */
+export declare function rampPresenceAfterConnect(sock: PresenceCapableSocket, opts?: RampPresenceOptions): Promise<void>;

package/dist/stealthConnect.js

@@ -0,0 +1,130 @@
+/**
+ * Stealth Connect — Reduce ban signal on socket connect + presence ramp
+ *
+ * Inspired by GOWA's --presence-on-connect=unavailable flag. Bots that
+ * snap online immediately and start blasting messages look suspicious to
+ * WhatsApp's anti-spam classifier. This module ships two helpers:
+ *
+ *   - `getStealthSocketConfig()` returns a partial Baileys socket config
+ *     that disables `markOnlineOnConnect` and provides a non-default
+ *     browser fingerprint (random pick from a small pool unless overridden).
+ *
+ *   - `rampPresenceAfterConnect()` waits a randomized delay, then issues
+ *     `sendPresenceUpdate('available')`. Supports `AbortSignal` so the
+ *     caller can cancel if the socket dies before the timer fires.
+ *
+ * Usage:
+ *   const config = getStealthSocketConfig({ os: 'MyApp' });
+ *   const sock = makeWASocket({ ...config, auth: state });
+ *
+ *   const ac = new AbortController();
+ *   sock.ev.on('connection.update', u => {
+ *     if (u.connection === 'close') ac.abort();
+ *   });
+ *   await rampPresenceAfterConnect(sock, { signal: ac.signal });
+ */
+/**
+ * Pool of realistic browser fingerprints.
+ *
+ * Values match formats actually emitted by WhatsApp Web clients in the wild.
+ * `getStealthSocketConfig()` picks one at random when caller does not supply
+ * an explicit `browser` or `os` option, so multiple consumers of the library
+ * do not all advertise an identical fingerprint (which would be trivially
+ * cluster-able by WhatsApp).
+ *
+ * Exported so callers can extend or override the pool if desired.
+ */
+export const STEALTH_BROWSER_POOL = Object.freeze([
+    ['Mac OS', 'Chrome', '120.0.6099.109'],
+    ['Mac OS', 'Safari', '17.2.1'],
+    ['Windows', 'Chrome', '121.0.6167.85'],
+    ['Windows', 'Firefox', '122.0'],
+    ['Windows', 'Edge', '120.0.2210.144'],
+    ['Linux', 'Chrome', '120.0.6099.109'],
+    ['Linux', 'Firefox', '122.0'],
+    ['Ubuntu', 'Chrome', '121.0.6167.85'],
+]);
+/**
+ * Returns a partial Baileys socket config tuned for stealth connect.
+ *
+ * - `markOnlineOnConnect` set to `false` so the socket joins without
+ *   broadcasting `available` (matches GOWA's `presence-on-connect=unavailable`).
+ * - `browser` is a randomized realistic tuple from `STEALTH_BROWSER_POOL`
+ *   unless overridden via `opts.browser` or `opts.os`.
+ *
+ * Merge the result into your `makeWASocket` options:
+ *
+ *   const sock = makeWASocket({ ...getStealthSocketConfig(), auth: state });
+ */
+export function getStealthSocketConfig(opts) {
+    const random = opts?.random ?? Math.random;
+    let browser;
+    if (opts?.browser) {
+        browser = opts.browser;
+    }
+    else {
+        const pick = STEALTH_BROWSER_POOL[Math.floor(random() * STEALTH_BROWSER_POOL.length)];
+        // pick is guaranteed defined — pool is non-empty and frozen.
+        const tuple = pick;
+        if (opts?.os) {
+            browser = [opts.os, tuple[1], tuple[2]];
+        }
+        else {
+            browser = [tuple[0], tuple[1], tuple[2]];
+        }
+    }
+    return {
+        markOnlineOnConnect: false,
+        browser,
+    };
+}
+/**
+ * Custom error thrown when `rampPresenceAfterConnect` is aborted via signal.
+ * Mirrors DOM `AbortError` semantics so consumers can `instanceof` check.
+ */
+export class AbortError extends Error {
+    name = 'AbortError';
+    constructor(message = 'rampPresenceAfterConnect aborted') {
+        super(message);
+    }
+}
+/**
+ * Waits a randomized delay then calls `sock.sendPresenceUpdate(targetState)`.
+ *
+ * Supports `AbortSignal` — abort during the delay window cancels the timer
+ * and rejects the returned promise with `AbortError`. Aborting after the
+ * presence update has already been sent is a no-op.
+ *
+ * Caller is responsible for invoking abort when the socket disconnects;
+ * otherwise the post-delay `sendPresenceUpdate` may run against a dead
+ * socket.
+ */
+export async function rampPresenceAfterConnect(sock, opts) {
+    const minDelayMs = opts?.minDelayMs ?? 30000;
+    const maxDelayMs = opts?.maxDelayMs ?? 90000;
+    const targetState = opts?.targetState ?? 'available';
+    const random = opts?.random ?? Math.random;
+    const signal = opts?.signal;
+    if (signal?.aborted) {
+        throw new AbortError();
+    }
+    const range = Math.max(0, maxDelayMs - minDelayMs);
+    const delayMs = Math.floor(random() * (range + 1)) + minDelayMs;
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            if (signal) {
+                signal.removeEventListener('abort', onAbort);
+            }
+            resolve();
+        }, delayMs);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new AbortError());
+        };
+        if (signal) {
+            signal.addEventListener('abort', onAbort, { once: true });
+        }
+    });
+    // jid undefined => broadcast presence to all conversations
+    await sock.sendPresenceUpdate(targetState, undefined);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baileys-antiban",
-  "version": "3.7.0",
+  "version": "3.8.1",
   "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",