device-passport 1.0.0 → 1.2.0

package/dist/shared/device-passport.Cjxlv8xI.cjs

@@ -0,0 +1,245 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e.default : e; }
+
+const fs__default = /*#__PURE__*/_interopDefaultCompat(fs);
+const path__default = /*#__PURE__*/_interopDefaultCompat(path);
+
+class JSONFileStorage {
+  filePath;
+  pretty;
+  autoSave;
+  cache = /* @__PURE__ */ new Map();
+  isLoaded = false;
+  writeQueue = Promise.resolve();
+  constructor(filePathOrOptions) {
+    if (typeof filePathOrOptions === "string") {
+      this.filePath = path__default.resolve(filePathOrOptions);
+      this.pretty = true;
+      this.autoSave = true;
+    } else {
+      this.filePath = path__default.resolve(filePathOrOptions.filePath);
+      this.pretty = filePathOrOptions.pretty ?? true;
+      this.autoSave = filePathOrOptions.autoSave ?? true;
+    }
+  }
+  /**
+   * Ensure data is loaded from disk into the in-memory cache.
+   */
+  ensureLoaded() {
+    if (this.isLoaded) return;
+    this.isLoaded = true;
+    if (!fs__default.existsSync(this.filePath)) {
+      return;
+    }
+    try {
+      const raw = fs__default.readFileSync(this.filePath, "utf-8").trim();
+      if (!raw) return;
+      const data = JSON.parse(raw);
+      if (typeof data === "object" && data !== null) {
+        for (const [key, value] of Object.entries(data)) {
+          this.cache.set(key, value);
+        }
+      }
+    } catch (err) {
+      const corruptBackup = `${this.filePath}.corrupt-${Date.now()}`;
+      try {
+        fs__default.copyFileSync(this.filePath, corruptBackup);
+      } catch {
+      }
+      throw new Error(
+        `[JSONFileStorage] Failed to parse JSON file at ${this.filePath}: ${err.message}. A backup was created at ${corruptBackup}`
+      );
+    }
+  }
+  /**
+   * Atomic flush to disk. Writes to a unique temp file in the same directory,
+   * then atomically renames it to target file.
+   */
+  flushAtomic() {
+    const dir = path__default.dirname(this.filePath);
+    if (!fs__default.existsSync(dir)) {
+      fs__default.mkdirSync(dir, { recursive: true });
+    }
+    const obj = {};
+    for (const [k, v] of this.cache.entries()) {
+      obj[k] = v;
+    }
+    const jsonString = this.pretty ? JSON.stringify(obj, null, 2) : JSON.stringify(obj);
+    const nonce = Math.random().toString(36).slice(2, 8);
+    const tmpPath = path__default.join(dir, `.${path__default.basename(this.filePath)}.${process.pid}.${Date.now()}.${nonce}.tmp`);
+    try {
+      fs__default.writeFileSync(tmpPath, jsonString, "utf-8");
+      fs__default.renameSync(tmpPath, this.filePath);
+    } catch (err) {
+      if (fs__default.existsSync(tmpPath)) {
+        try {
+          fs__default.unlinkSync(tmpPath);
+        } catch {
+        }
+      }
+      throw err;
+    }
+  }
+  /**
+   * Queue a disk write to prevent race conditions during rapid concurrent mutations.
+   */
+  queueSave() {
+    if (!this.autoSave) {
+      return Promise.resolve();
+    }
+    this.writeQueue = this.writeQueue.then(() => {
+      this.flushAtomic();
+    }).catch((err) => {
+      return Promise.reject(err);
+    });
+    return this.writeQueue;
+  }
+  async get(key) {
+    return this.getSync(key);
+  }
+  getSync(key) {
+    this.ensureLoaded();
+    const val = this.cache.get(key);
+    return val !== void 0 ? val : null;
+  }
+  async set(key, value) {
+    this.ensureLoaded();
+    this.cache.set(key, value);
+    await this.queueSave();
+  }
+  setSync(key, value) {
+    this.ensureLoaded();
+    this.cache.set(key, value);
+    if (this.autoSave) {
+      this.flushAtomic();
+    }
+  }
+  async has(key) {
+    return this.hasSync(key);
+  }
+  hasSync(key) {
+    this.ensureLoaded();
+    return this.cache.has(key);
+  }
+  async delete(key) {
+    this.ensureLoaded();
+    const existed = this.cache.delete(key);
+    if (existed && this.autoSave) {
+      await this.queueSave();
+    }
+    return existed;
+  }
+  deleteSync(key) {
+    this.ensureLoaded();
+    const existed = this.cache.delete(key);
+    if (existed && this.autoSave) {
+      this.flushAtomic();
+    }
+    return existed;
+  }
+  async keys() {
+    return this.keysSync();
+  }
+  keysSync() {
+    this.ensureLoaded();
+    return Array.from(this.cache.keys());
+  }
+  async clear() {
+    this.ensureLoaded();
+    this.cache.clear();
+    if (this.autoSave) {
+      await this.queueSave();
+    }
+  }
+  clearSync() {
+    this.ensureLoaded();
+    this.cache.clear();
+    if (this.autoSave) {
+      this.flushAtomic();
+    }
+  }
+  /**
+   * Explicitly force a flush to disk (useful if autoSave is set to false).
+   */
+  async flush() {
+    await this.queueSave();
+  }
+  flushSync() {
+    this.flushAtomic();
+  }
+  get size() {
+    this.ensureLoaded();
+    return this.cache.size;
+  }
+}
+
+class MemoryStorage {
+  store = /* @__PURE__ */ new Map();
+  clone;
+  constructor(options) {
+    this.clone = options?.clone ?? true;
+  }
+  deepClone(val) {
+    if (!this.clone || val === null || typeof val !== "object") {
+      return val;
+    }
+    if (typeof structuredClone === "function") {
+      try {
+        return structuredClone(val);
+      } catch {
+        return JSON.parse(JSON.stringify(val));
+      }
+    }
+    return JSON.parse(JSON.stringify(val));
+  }
+  async get(key) {
+    return this.getSync(key);
+  }
+  getSync(key) {
+    const val = this.store.get(key);
+    if (val === void 0) {
+      return null;
+    }
+    return this.deepClone(val);
+  }
+  async set(key, value) {
+    this.setSync(key, value);
+  }
+  setSync(key, value) {
+    this.store.set(key, this.deepClone(value));
+  }
+  async has(key) {
+    return this.hasSync(key);
+  }
+  hasSync(key) {
+    return this.store.has(key);
+  }
+  async delete(key) {
+    return this.deleteSync(key);
+  }
+  deleteSync(key) {
+    return this.store.delete(key);
+  }
+  async keys() {
+    return this.keysSync();
+  }
+  keysSync() {
+    return Array.from(this.store.keys());
+  }
+  async clear() {
+    this.clearSync();
+  }
+  clearSync() {
+    this.store.clear();
+  }
+  get size() {
+    return this.store.size;
+  }
+}
+
+exports.JSONFileStorage = JSONFileStorage;
+exports.MemoryStorage = MemoryStorage;

package/dist/shared/device-passport.CsOWqPIr.d.cts

@@ -0,0 +1,77 @@
+import { DevicePassport } from '../types/index.cjs';
+
+interface PlaywrightContextOptions {
+    userAgent: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    deviceScaleFactor: number;
+    locale: string;
+    timezoneId: string;
+    geolocation?: {
+        latitude: number;
+        longitude: number;
+        accuracy?: number;
+    };
+    permissions?: string[];
+    extraHTTPHeaders: Record<string, string>;
+    hasTouch: boolean;
+    isMobile: boolean;
+    colorScheme?: 'light' | 'dark' | 'no-preference';
+}
+/**
+ * Builds Playwright BrowserContext options directly from a DevicePassport.
+ * Ready for `browser.newContext(getPlaywrightContext(passport))`.
+ */
+declare function getPlaywrightContext(passport: DevicePassport): PlaywrightContextOptions;
+/**
+ * Generates an in-page stealth script to patch runtime JavaScript APIs
+ * (navigator.webdriver, hardwareConcurrency, deviceMemory, WebGL unmasked vendor/renderer,
+ * navigator.userAgentData Client Hints, and Screen dimensions).
+ *
+ * 🔴 API-level spoofing is not enough on its own: `canvas.toDataURL()` and `gl.readPixels()`
+ * still return the **real** framebuffer, so a headless browser exposes SwiftShader while
+ * its UA claims a discrete GPU — and every persona on one machine hashes identically.
+ * The pixel-protection script is therefore appended here, so existing users get
+ * read-back-safe personas without changing their call sites.
+ *
+ * The noise is seeded from the passport seed: stable per account, different per account.
+ */
+declare function getStealthScript(passport: DevicePassport): string;
+/**
+ * Applies stealth injections and extra headers to a Playwright BrowserContext.
+ *
+ * @param context Playwright BrowserContext instance
+ * @param passport DevicePassport instance
+ */
+declare function applyToPlaywrightContext(context: any, passport: DevicePassport): Promise<void>;
+
+interface PuppeteerEmulationOptions {
+    launchArgs: string[];
+    defaultViewport: {
+        width: number;
+        height: number;
+        deviceScaleFactor: number;
+        isMobile: boolean;
+        hasTouch: boolean;
+    };
+    userAgent: string;
+    locale: string;
+    timezoneId: string;
+    extraHTTPHeaders: Record<string, string>;
+}
+/**
+ * Returns Puppeteer launch args and page emulation parameters matching the DevicePassport.
+ */
+declare function getPuppeteerArgs(passport: DevicePassport): PuppeteerEmulationOptions;
+/**
+ * Applies stealth injections, headers, viewport, and timezone emulation to a Puppeteer Page.
+ *
+ * @param page Puppeteer Page instance
+ * @param passport DevicePassport instance
+ */
+declare function applyToPuppeteerPage(page: any, passport: DevicePassport): Promise<void>;
+
+export { applyToPlaywrightContext as b, applyToPuppeteerPage as c, getPuppeteerArgs as d, getStealthScript as e, getPlaywrightContext as g };
+export type { PlaywrightContextOptions as P, PuppeteerEmulationOptions as a };

package/dist/shared/device-passport.CyQtcZeD.mjs

@@ -0,0 +1,237 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+class JSONFileStorage {
+  filePath;
+  pretty;
+  autoSave;
+  cache = /* @__PURE__ */ new Map();
+  isLoaded = false;
+  writeQueue = Promise.resolve();
+  constructor(filePathOrOptions) {
+    if (typeof filePathOrOptions === "string") {
+      this.filePath = path.resolve(filePathOrOptions);
+      this.pretty = true;
+      this.autoSave = true;
+    } else {
+      this.filePath = path.resolve(filePathOrOptions.filePath);
+      this.pretty = filePathOrOptions.pretty ?? true;
+      this.autoSave = filePathOrOptions.autoSave ?? true;
+    }
+  }
+  /**
+   * Ensure data is loaded from disk into the in-memory cache.
+   */
+  ensureLoaded() {
+    if (this.isLoaded) return;
+    this.isLoaded = true;
+    if (!fs.existsSync(this.filePath)) {
+      return;
+    }
+    try {
+      const raw = fs.readFileSync(this.filePath, "utf-8").trim();
+      if (!raw) return;
+      const data = JSON.parse(raw);
+      if (typeof data === "object" && data !== null) {
+        for (const [key, value] of Object.entries(data)) {
+          this.cache.set(key, value);
+        }
+      }
+    } catch (err) {
+      const corruptBackup = `${this.filePath}.corrupt-${Date.now()}`;
+      try {
+        fs.copyFileSync(this.filePath, corruptBackup);
+      } catch {
+      }
+      throw new Error(
+        `[JSONFileStorage] Failed to parse JSON file at ${this.filePath}: ${err.message}. A backup was created at ${corruptBackup}`
+      );
+    }
+  }
+  /**
+   * Atomic flush to disk. Writes to a unique temp file in the same directory,
+   * then atomically renames it to target file.
+   */
+  flushAtomic() {
+    const dir = path.dirname(this.filePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    const obj = {};
+    for (const [k, v] of this.cache.entries()) {
+      obj[k] = v;
+    }
+    const jsonString = this.pretty ? JSON.stringify(obj, null, 2) : JSON.stringify(obj);
+    const nonce = Math.random().toString(36).slice(2, 8);
+    const tmpPath = path.join(dir, `.${path.basename(this.filePath)}.${process.pid}.${Date.now()}.${nonce}.tmp`);
+    try {
+      fs.writeFileSync(tmpPath, jsonString, "utf-8");
+      fs.renameSync(tmpPath, this.filePath);
+    } catch (err) {
+      if (fs.existsSync(tmpPath)) {
+        try {
+          fs.unlinkSync(tmpPath);
+        } catch {
+        }
+      }
+      throw err;
+    }
+  }
+  /**
+   * Queue a disk write to prevent race conditions during rapid concurrent mutations.
+   */
+  queueSave() {
+    if (!this.autoSave) {
+      return Promise.resolve();
+    }
+    this.writeQueue = this.writeQueue.then(() => {
+      this.flushAtomic();
+    }).catch((err) => {
+      return Promise.reject(err);
+    });
+    return this.writeQueue;
+  }
+  async get(key) {
+    return this.getSync(key);
+  }
+  getSync(key) {
+    this.ensureLoaded();
+    const val = this.cache.get(key);
+    return val !== void 0 ? val : null;
+  }
+  async set(key, value) {
+    this.ensureLoaded();
+    this.cache.set(key, value);
+    await this.queueSave();
+  }
+  setSync(key, value) {
+    this.ensureLoaded();
+    this.cache.set(key, value);
+    if (this.autoSave) {
+      this.flushAtomic();
+    }
+  }
+  async has(key) {
+    return this.hasSync(key);
+  }
+  hasSync(key) {
+    this.ensureLoaded();
+    return this.cache.has(key);
+  }
+  async delete(key) {
+    this.ensureLoaded();
+    const existed = this.cache.delete(key);
+    if (existed && this.autoSave) {
+      await this.queueSave();
+    }
+    return existed;
+  }
+  deleteSync(key) {
+    this.ensureLoaded();
+    const existed = this.cache.delete(key);
+    if (existed && this.autoSave) {
+      this.flushAtomic();
+    }
+    return existed;
+  }
+  async keys() {
+    return this.keysSync();
+  }
+  keysSync() {
+    this.ensureLoaded();
+    return Array.from(this.cache.keys());
+  }
+  async clear() {
+    this.ensureLoaded();
+    this.cache.clear();
+    if (this.autoSave) {
+      await this.queueSave();
+    }
+  }
+  clearSync() {
+    this.ensureLoaded();
+    this.cache.clear();
+    if (this.autoSave) {
+      this.flushAtomic();
+    }
+  }
+  /**
+   * Explicitly force a flush to disk (useful if autoSave is set to false).
+   */
+  async flush() {
+    await this.queueSave();
+  }
+  flushSync() {
+    this.flushAtomic();
+  }
+  get size() {
+    this.ensureLoaded();
+    return this.cache.size;
+  }
+}
+
+class MemoryStorage {
+  store = /* @__PURE__ */ new Map();
+  clone;
+  constructor(options) {
+    this.clone = options?.clone ?? true;
+  }
+  deepClone(val) {
+    if (!this.clone || val === null || typeof val !== "object") {
+      return val;
+    }
+    if (typeof structuredClone === "function") {
+      try {
+        return structuredClone(val);
+      } catch {
+        return JSON.parse(JSON.stringify(val));
+      }
+    }
+    return JSON.parse(JSON.stringify(val));
+  }
+  async get(key) {
+    return this.getSync(key);
+  }
+  getSync(key) {
+    const val = this.store.get(key);
+    if (val === void 0) {
+      return null;
+    }
+    return this.deepClone(val);
+  }
+  async set(key, value) {
+    this.setSync(key, value);
+  }
+  setSync(key, value) {
+    this.store.set(key, this.deepClone(value));
+  }
+  async has(key) {
+    return this.hasSync(key);
+  }
+  hasSync(key) {
+    return this.store.has(key);
+  }
+  async delete(key) {
+    return this.deleteSync(key);
+  }
+  deleteSync(key) {
+    return this.store.delete(key);
+  }
+  async keys() {
+    return this.keysSync();
+  }
+  keysSync() {
+    return Array.from(this.store.keys());
+  }
+  async clear() {
+    this.clearSync();
+  }
+  clearSync() {
+    this.store.clear();
+  }
+  get size() {
+    return this.store.size;
+  }
+}
+
+export { JSONFileStorage as J, MemoryStorage as M };

package/dist/shared/device-passport.D7pEnyp2.d.ts

@@ -0,0 +1,77 @@
+import { DevicePassport } from '../types/index.js';
+
+interface PlaywrightContextOptions {
+    userAgent: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    deviceScaleFactor: number;
+    locale: string;
+    timezoneId: string;
+    geolocation?: {
+        latitude: number;
+        longitude: number;
+        accuracy?: number;
+    };
+    permissions?: string[];
+    extraHTTPHeaders: Record<string, string>;
+    hasTouch: boolean;
+    isMobile: boolean;
+    colorScheme?: 'light' | 'dark' | 'no-preference';
+}
+/**
+ * Builds Playwright BrowserContext options directly from a DevicePassport.
+ * Ready for `browser.newContext(getPlaywrightContext(passport))`.
+ */
+declare function getPlaywrightContext(passport: DevicePassport): PlaywrightContextOptions;
+/**
+ * Generates an in-page stealth script to patch runtime JavaScript APIs
+ * (navigator.webdriver, hardwareConcurrency, deviceMemory, WebGL unmasked vendor/renderer,
+ * navigator.userAgentData Client Hints, and Screen dimensions).
+ *
+ * 🔴 API-level spoofing is not enough on its own: `canvas.toDataURL()` and `gl.readPixels()`
+ * still return the **real** framebuffer, so a headless browser exposes SwiftShader while
+ * its UA claims a discrete GPU — and every persona on one machine hashes identically.
+ * The pixel-protection script is therefore appended here, so existing users get
+ * read-back-safe personas without changing their call sites.
+ *
+ * The noise is seeded from the passport seed: stable per account, different per account.
+ */
+declare function getStealthScript(passport: DevicePassport): string;
+/**
+ * Applies stealth injections and extra headers to a Playwright BrowserContext.
+ *
+ * @param context Playwright BrowserContext instance
+ * @param passport DevicePassport instance
+ */
+declare function applyToPlaywrightContext(context: any, passport: DevicePassport): Promise<void>;
+
+interface PuppeteerEmulationOptions {
+    launchArgs: string[];
+    defaultViewport: {
+        width: number;
+        height: number;
+        deviceScaleFactor: number;
+        isMobile: boolean;
+        hasTouch: boolean;
+    };
+    userAgent: string;
+    locale: string;
+    timezoneId: string;
+    extraHTTPHeaders: Record<string, string>;
+}
+/**
+ * Returns Puppeteer launch args and page emulation parameters matching the DevicePassport.
+ */
+declare function getPuppeteerArgs(passport: DevicePassport): PuppeteerEmulationOptions;
+/**
+ * Applies stealth injections, headers, viewport, and timezone emulation to a Puppeteer Page.
+ *
+ * @param page Puppeteer Page instance
+ * @param passport DevicePassport instance
+ */
+declare function applyToPuppeteerPage(page: any, passport: DevicePassport): Promise<void>;
+
+export { applyToPlaywrightContext as b, applyToPuppeteerPage as c, getPuppeteerArgs as d, getStealthScript as e, getPlaywrightContext as g };
+export type { PlaywrightContextOptions as P, PuppeteerEmulationOptions as a };