stealth-ws 1.0.0

package/lib/fingerprint.js

@@ -0,0 +1,208 @@
+/**
+ * Fingerprint profile management
+ * 
+ * Manages TLS fingerprint profiles for different browsers.
+ * These are passed to the Go bridge for TLS handshake spoofing.
+ */
+
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Available fingerprint profiles
+ * Maps profile name to Go uTLS Hello spec name
+ */
+export const PROFILES = {
+  // Chrome versions
+  'chrome120': 'HelloChrome_120',
+  'chrome119': 'HelloChrome_119',
+  'chrome118': 'HelloChrome_118',
+  'chrome117': 'HelloChrome_117',
+  'chrome116': 'HelloChrome_116',
+  'chrome115': 'HelloChrome_115',
+  'chrome114': 'HelloChrome_114',
+  'chrome113': 'HelloChrome_113',
+  'chrome112': 'HelloChrome_112',
+  'chrome110': 'HelloChrome_110',
+  'chrome100': 'HelloChrome_100_Auto',
+  'chromeAuto': 'HelloChrome_Auto',
+
+  // Firefox versions
+  'firefox121': 'HelloFirefox_121',
+  'firefox120': 'HelloFirefox_120',
+  'firefox115': 'HelloFirefox_115',
+  'firefox110': 'HelloFirefox_110',
+  'firefox100': 'HelloFirefox_100',
+  'firefoxAuto': 'HelloFirefox_Auto',
+
+  // Safari versions
+  'safari17': 'HelloSafari_17_0',
+  'safari16': 'HelloSafari_16_6',
+  'safari15': 'HelloSafari_15_6',
+  'safari14': 'HelloSafari_14_1',
+  'safariAuto': 'HelloSafari_Auto',
+
+  // Edge versions
+  'edge120': 'HelloEdge_120',
+  'edge119': 'HelloEdge_119',
+  'edge118': 'HelloEdge_118',
+  'edge117': 'HelloEdge_117',
+  'edge116': 'HelloEdge_116',
+  'edgeAuto': 'HelloEdge_Auto',
+
+  // iOS
+  'ios17': 'HelloIOS_17_1',
+  'ios16': 'HelloIOS_16_1',
+  'ios15': 'HelloIOS_15_5',
+  'iosAuto': 'HelloIOS_Auto',
+
+  // Android
+  'android12': 'HelloAndroid_12',
+  'android11': 'HelloAndroid_11',
+  'androidAuto': 'HelloAndroid_Auto'
+};
+
+/**
+ * FingerprintProfiles class for managing browser fingerprints
+ */
+export class FingerprintProfiles {
+  /**
+   * List all available fingerprint profiles
+   * 
+   * @returns {string[]} Array of profile names
+   */
+  static list() {
+    return Object.keys(PROFILES);
+  }
+
+  /**
+   * Get the Go Hello spec name for a profile
+   * 
+   * @param {string} profile - Profile name
+   * @returns {string} Go Hello spec name
+   */
+  static getSpecName(profile) {
+    const specName = PROFILES[profile];
+    if (!specName) {
+      console.warn(`Unknown fingerprint profile: ${profile}, using chrome120`);
+      return 'HelloChrome_120';
+    }
+    return specName;
+  }
+
+  /**
+   * Validate a profile name
+   * 
+   * @param {string} profile - Profile name
+   * @returns {boolean} True if valid
+   */
+  static isValid(profile) {
+    return profile in PROFILES;
+  }
+
+  /**
+   * Get profile by category
+   * 
+   * @param {string} category - 'chrome', 'firefox', 'safari', 'edge', 'ios', 'android'
+   * @returns {string[]} Array of profile names in category
+   */
+  static byCategory(category) {
+    const prefix = category.toLowerCase();
+    return Object.keys(PROFILES).filter(name => name.startsWith(prefix));
+  }
+
+  /**
+   * Get recommended profile for general use
+   * 
+   * @returns {string} Recommended profile name
+   */
+  static recommended() {
+    return 'chrome120';
+  }
+
+  /**
+   * Get profile with specific Chrome version
+   * 
+   * @param {number} version - Chrome version (e.g., 120)
+   * @returns {string} Profile name
+   */
+  static chromeVersion(version) {
+    const profile = `chrome${version}`;
+    if (PROFILES[profile]) {
+      return profile;
+    }
+    // Find closest version
+    const versions = Object.keys(PROFILES)
+      .filter(k => k.startsWith('chrome') && k !== 'chromeAuto')
+      .map(k => parseInt(k.replace('chrome', '')))
+      .sort((a, b) => b - a);
+    
+    const closest = versions.find(v => v <= version) || versions[0];
+    return `chrome${closest}`;
+  }
+
+  /**
+   * Get all Chrome profiles
+   * 
+   * @returns {string[]} Chrome profile names
+   */
+  static chrome() {
+    return this.byCategory('chrome');
+  }
+
+  /**
+   * Get all Firefox profiles
+   * 
+   * @returns {string[]} Firefox profile names
+   */
+  static firefox() {
+    return this.byCategory('firefox');
+  }
+
+  /**
+   * Get all Safari profiles
+   * 
+   * @returns {string[]} Safari profile names
+   */
+  static safari() {
+    return this.byCategory('safari');
+  }
+
+  /**
+   * Get all Edge profiles
+   * 
+   * @returns {string[]} Edge profile names
+   */
+  static edge() {
+    return this.byCategory('edge');
+  }
+}
+
+/**
+ * Get default fingerprint configuration
+ * 
+ * @returns {Object} Default fingerprint config
+ */
+export function getDefaultFingerprint() {
+  return {
+    profile: 'chrome120',
+    specName: PROFILES['chrome120']
+  };
+}
+
+/**
+ * Create a custom fingerprint configuration
+ * 
+ * @param {Object} options - Custom fingerprint options
+ * @returns {Object} Fingerprint configuration
+ */
+export function createCustomFingerprint(options = {}) {
+  return {
+    profile: options.profile || 'custom',
+    specName: options.specName || 'HelloChrome_Auto',
+    customSpec: options.customSpec || null
+  };
+}

package/lib/index.d.ts

@@ -0,0 +1,74 @@
+/// <reference types="node" />
+
+import { EventEmitter } from 'events';
+
+export interface WebSocketOptions {
+  fingerprint?: string;
+  cookies?: string | Array<{ name: string; value: string }> | CookieJar;
+  proxy?: string;
+  headers?: Record<string, string>;
+  perMessageDeflate?: boolean;
+  debug?: boolean;
+}
+
+export declare class WebSocket extends EventEmitter {
+  static readonly CONNECTING: 0;
+  static readonly OPEN: 1;
+  static readonly CLOSING: 2;
+  static readonly CLOSED: 3;
+
+  readonly url: string;
+  readonly readyState: 0 | 1 | 2 | 3;
+  readonly protocol: string;
+  readonly extensions: string;
+  readonly bufferedAmount: number;
+  binaryType: 'nodebuffer' | 'arraybuffer' | 'fragments';
+
+  constructor(url: string, options?: WebSocketOptions);
+
+  send(data: string | Buffer, options?: { binary?: boolean }, callback?: (err?: Error) => void): void;
+  close(code?: number, reason?: string): void;
+  terminate(): void;
+  ping(data?: string | Buffer, mask?: boolean, callback?: (err?: Error) => void): void;
+  pong(data?: string | Buffer, mask?: boolean, callback?: (err?: Error) => void): void;
+  pause(): void;
+  resume(): void;
+
+  addEventListener(type: 'open', listener: () => void): void;
+  addEventListener(type: 'message', listener: (data: Buffer, isBinary: boolean) => void): void;
+  addEventListener(type: 'close', listener: (code: number, reason: string) => void): void;
+  addEventListener(type: 'error', listener: (err: Error) => void): void;
+  addEventListener(type: string, listener: (...args: unknown[]) => void): void;
+
+  removeEventListener(type: string, listener: (...args: unknown[]) => void): void;
+
+  on(event: 'open', listener: () => void): this;
+  on(event: 'message', listener: (data: Buffer, isBinary: boolean) => void): this;
+  on(event: 'close', listener: (code: number, reason: string) => void): this;
+  on(event: 'error', listener: (err: Error) => void): this;
+  on(event: 'ping', listener: (data?: Buffer) => void): this;
+  on(event: 'auth_required', listener: () => void): this;
+  on(event: string, listener: (...args: unknown[]) => void): this;
+}
+
+export declare class FingerprintProfiles {
+  static list(): string[];
+  static getSpecName(profile: string): string;
+  static isValid(profile: string): boolean;
+  static byCategory(category: 'chrome' | 'firefox' | 'safari' | 'edge' | 'ios' | 'android'): string[];
+  static recommended(): string;
+  static chromeVersion(version: number): string;
+  static chrome(): string[];
+  static firefox(): string[];
+  static safari(): string[];
+  static edge(): string[];
+}
+
+export declare class CookieJar {
+  loadFromFile(path: string): void;
+  getCookieString(url: string): string;
+}
+
+export declare const VERSION: string;
+
+export default WebSocket;

package/lib/index.js

@@ -0,0 +1,29 @@
+/**
+ * stealth-ws - WebSocket client with TLS fingerprint spoofing
+ * 
+ * A drop-in replacement for the 'ws' package that spoofs browser
+ * TLS fingerprints to bypass Cloudflare and other bot detection systems.
+ */
+
+import { WebSocket } from './websocket.js';
+import { FingerprintProfiles } from './fingerprint.js';
+import { CookieJar } from './cookie-jar.js';
+
+// Re-export WebSocket class as default export
+export default WebSocket;
+
+// Export named exports
+export {
+  WebSocket,
+  FingerprintProfiles,
+  CookieJar
+};
+
+// Static properties for compatibility with ws
+WebSocket.CONNECTING = 0;
+WebSocket.OPEN = 1;
+WebSocket.CLOSING = 2;
+WebSocket.CLOSED = 3;
+
+// Version
+export const VERSION = '1.0.0';