device-passport 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -5,6 +5,36 @@ 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).
 
+## [1.1.0] - 2026-11-04
+
+> ⚠️ 发布受阻说明：本版本代码已合并并打好 tag，但 **npm 发布尚未完成** ——
+> `device-passport` 在 npmjs.com 上没有配置 Trusted Publisher 信任关系。
+> 证据：`device-passport@1.0.0` 没有 OIDC attestation（对比 `im-notify-kit@0.4.1` 有），
+> 说明该包从未成功走通 OIDC 通道；workflow 里的 `id-token: write` 只是必要条件，
+> 不是充分条件。需要在 npmjs.com → Packages → device-passport → Settings →
+> Trusted Publisher 里登记：GitHub Actions / 组织 `webkubor` / 仓库 `device-passport` /
+> 工作流 `publish.yml`，并允许 `npm publish`。登记后 2 天内需完成首次发布，否则配置过期。
+
+### Added
+- **Pixel-level protection**: `getStealthScript()` now appends a deterministic noise layer that patches `canvas.toDataURL()`, `getImageData()`, `gl.readPixels()` and the audio analyser, so read-back no longer exposes the host GPU or a shared hash across personas. The noise is derived from the passport seed — stable per account, distinct per account — and uses discrete quantization levels rather than per-pixel dithering, because a smooth ±1 RGB jitter is itself a fingerprint.
+- **Raw CDP adapter**: `getCdpPlan()` and `applyCdpPassport()` emit an ordered, transport-agnostic Chrome DevTools Protocol command plan for tools that speak bare CDP (e.g. `lite-browser`'s `cdp` channel). Covers headers, `Emulation.setUserAgentOverride` with Client-Hints metadata, timezone, locale, device metrics, touch emulation and init-script installation.
+
+### Fixed
+- **Canvas serialization recursion**: the temporary canvas used for re-serialization shares the patched prototype, so calling its `toDataURL` recursed until the stack limit. Serialization now uses the captured original method (verified with 25 repeated calls in real Chromium).
+- **WebGL canvases leaked the real framebuffer through `toDataURL()`**: a canvas with a WebGL context returns `null` from `getContext('2d')`, so that path silently skipped protection. Pixel perturbation now runs through `gl.readPixels` for such canvases.
+- **Alpha bytes were perturbed**: RGBA alpha now stays untouched, so transparent and opaque pixels keep their semantics (masks and hit-testing unaffected).
+- **Audio perturbation was seed-independent**: a fixed `1e-7` step was identical for every persona and rounded away in Float32 at typical dB values. The step is now seed-derived and representable.
+- **Injected stealth script was invalid JavaScript**: the runtime script embedded TypeScript-only syntax (`navigator as any`), which raised a `SyntaxError` in the page and silently disabled the **entire** stealth layer — `navigator.webdriver` stayed `true` and every spoofed API reverted to the real values. The script is now valid browser JavaScript, and a regression test parses it to prevent this from returning.
+- **CDP init scripts never executed**: `Page.addScriptToEvaluateOnNewDocument` was issued without `Page.enable`. Chrome accepted the script, returned an identifier and then never ran it, so a CDP-driven persona looked like a plain automation session. `Page.enable` is now emitted first, with a regression test covering the ordering.
+
+## [1.0.1] - 2026-10-17
+
+### Added
+- **Standard ESM subpath exports**: `device-passport/geo`, `device-passport/storage`, `device-passport/adapters` are now importable as separate entry points, each shipping its own `types` / `import` / `require` conditions. Consumers can tree-shake by pulling only the module they need instead of the whole bundle.
+
+### Fixed
+- **npm publish path**: the release workflow now runs on Node 24 with pure OIDC Trusted Publishing (the previous `NODE_AUTH_TOKEN` pointed at a secret that was never configured, which forced npm down the token-auth path and made Trusted Publishing ineffective).
+
 ## [1.0.0] - 2026-10-17
 
 ### Added

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="assets/banner.svg" alt="device-passport banner" width="800"/>
+  <img src="https://cdn.jsdelivr.net/gh/webkubor/free-imgbed@main/device-passport/banner.svg" alt="device-passport banner" width="800"/>
 </p>
 
 <h1 align="center">🛂 device-passport</h1>
@@ -59,7 +59,7 @@ Modern anti-bot classifiers (Cloudflare Turnstile, DataDome, Akamai, GitHub Anti
    Under-parameterized headers ($H(X) < 4.6$ bits/char) scream "naive scraper"; chaotic randomized noise ($H(X) > 5.6$ bits/char) screams "evasion bot". `device-passport` operates strictly within the natural human entropy equilibrium ($5.24$ bits/char).
 
 <p align="center">
-  <img src="assets/architecture.svg" alt="device-passport formal state-space architecture" width="100%"/>
+  <img src="https://cdn.jsdelivr.net/gh/webkubor/free-imgbed@main/device-passport/architecture.svg" alt="device-passport formal state-space architecture" width="100%"/>
 </p>
 
 ---
@@ -292,6 +292,60 @@ await passport.injectToPuppeteer(page);
 await page.goto('https://bot.sannysoft.com');
 ```
 
+### Raw CDP Integration (lite-browser, custom transports)
+
+Tools that drive Chrome over a bare DevTools Protocol socket cannot use the Playwright or
+Puppeteer adapters, because those return framework-shaped options. `getCdpPlan()` returns
+an ordered, transport-agnostic command plan instead:
+
+```typescript
+import { createPassport, applyCdpPassport } from 'device-passport';
+
+const passport = createPassport({ seed: 'worker_de_19', geo: 'DE', os: 'windows' });
+
+// `send` is yours: a WebSocket, stdio, or an in-process socket.
+await applyCdpPassport(passport, (cmd) => transport.send(cmd.method, cmd.params));
+```
+
+The plan covers `Page.enable`, extra HTTP headers, `Emulation.setUserAgentOverride`
+(with Client-Hints metadata), timezone, locale, device metrics and touch emulation, and
+installs the stealth script through `Page.addScriptToEvaluateOnNewDocument`.
+
+> **`Page.enable` is mandatory.** Without it Chrome accepts the init script, returns an
+> identifier, and then never runs it — the persona stays a plain automation session.
+> `applyCdpPassport` emits it first for that reason.
+
+---
+
+## Pixel-Level Protection
+
+API-level spoofing is not sufficient on its own. `canvas.toDataURL()` and
+`gl.readPixels()` hand back the **real** framebuffer, so a headless browser exposes
+SwiftShader while its User-Agent claims a discrete GPU — and every persona rendered on
+the same machine produces a **byte-identical** canvas hash, which makes a fleet easy to
+cluster.
+
+`getStealthScript()` now appends a deterministic pixel-protection layer that patches
+`toDataURL`, `getImageData`, `readPixels` and the audio analyser:
+
+```typescript
+import { createPassport, getStealthScript } from 'device-passport';
+
+const passport = createPassport('alice');
+const script = getStealthScript(passport);
+// Use with Playwright addInitScript, Puppeteer evaluateOnNewDocument, or CDP.
+```
+
+Properties:
+
+- **Deterministic per seed** — the same account reads back identical pixels forever,
+  which is what makes "sticky hardware" true beyond the API layer.
+- **Distinct per account** — different seeds produce different noise tables.
+- **Plausible** — a discrete quantization of a few levels, not per-pixel dithering. Real
+  GPUs quantize; a smooth ±1 RGB jitter on every pixel is itself a fingerprint.
+- **Self-contained** — dependency-free IIFE, safe to inject repeatedly (re-injection is
+  a no-op).
+
 ---
 
 ## Multi-Account Fleet Management (`PassportManager`)
@@ -411,6 +465,19 @@ npx device-passport inspect --seed production_user_102
  │ Native Fetch │                │  Playwright  │                │  Puppeteer   │
  │   Headers    │                │Context Options│               │ Emulation Hook│
  └──────────────┘                └──────────────┘                └──────────────┘
+                                 │                               │
+                                 └───────────────┬───────────────┘
+                                                 ▼
+                                 ┌───────────────────────────┐
+                                 │  Pixel-Level Protection   │
+                                 │ canvas / WebGL / audio    │
+                                 │ deterministic per seed    │
+                                 └───────────┬───────────────┘
+                                             ▼
+                                 ┌───────────────────────────┐
+                                 │  Raw CDP Command Plan     │
+                                 │ (lite-browser, custom)    │
+                                 └───────────────────────────┘
 ```
 
 ---

package/dist/adapters/index.cjs

@@ -0,0 +1,19 @@
+'use strict';
+
+const cdp = require('../shared/device-passport.CLaBZWUV.cjs');
+require('node:crypto');
+require('../shared/device-passport.BPd2-w8e.cjs');
+
+
+
+exports.CANONICAL_HEADER_ORDER = cdp.CANONICAL_HEADER_ORDER;
+exports.applyCdpPassport = cdp.applyCdpPassport;
+exports.applyToPlaywrightContext = cdp.applyToPlaywrightContext;
+exports.applyToPuppeteerPage = cdp.applyToPuppeteerPage;
+exports.formatCanonicalHeaders = cdp.formatCanonicalHeaders;
+exports.getCdpPlan = cdp.getCdpPlan;
+exports.getPlaywrightContext = cdp.getPlaywrightContext;
+exports.getPuppeteerArgs = cdp.getPuppeteerArgs;
+exports.getStealthScript = cdp.getStealthScript;
+exports.toCurl = cdp.toCurl;
+exports.withPassport = cdp.withPassport;

package/dist/adapters/index.d.cts

@@ -0,0 +1,156 @@
+import { DevicePassport } from '../types/index.cjs';
+import '../shared/device-passport.C_F1vBE8.cjs';
+
+/**
+ * Standard Chromium browser header ordering.
+ * Anti-bot systems (Cloudflare, Akamai, DataDome, Kasada) strictly inspect
+ * the sequence of HTTP request headers. A mismatch in header order triggers
+ * immediate bot heuristics.
+ */
+declare const CANONICAL_HEADER_ORDER: readonly string[];
+/**
+ * Sorts and formats HTTP headers according to canonical browser ordering.
+ * Merges base headers with optional overrides.
+ */
+declare function formatCanonicalHeaders(baseHeaders: Record<string, string>, overrides?: Record<string, string>): Record<string, string>;
+interface PassportLike {
+    headers: Record<string, string>;
+    getHeaders?: (overrides?: Record<string, string>) => Record<string, string>;
+}
+/**
+ * Higher-order fetch function wrapping standard fetch with canonical DevicePassport headers.
+ * Ensures consistent TLS/HTTP persona across API calls, scraping requests, and webhooks.
+ *
+ * @param passport DevicePassport instance or object
+ * @param customFetch Optional fetch implementation (e.g. node-fetch, undici, or global fetch)
+ */
+declare function withPassport(passport: PassportLike | DevicePassport, customFetch?: typeof fetch): typeof fetch;
+/**
+ * Generates an executable cURL command with correct browser headers.
+ */
+declare function toCurl(passport: PassportLike | DevicePassport, url: string, options?: {
+    method?: string;
+    data?: any;
+    headers?: Record<string, string>;
+}): string;
+
+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>;
+
+/**
+ * Raw Chrome DevTools Protocol adapter.
+ *
+ * 🔴 Why this exists (2026-11-04):
+ *   Tools that drive Chrome over a bare CDP socket — `lite-browser`'s `cdp <method> [json]`
+ *   channel, for example — cannot use the Playwright/Puppeteer adapters, because those
+ *   hand back framework-shaped options. This adapter speaks plain CDP so any CDP client
+ *   can apply a passport.
+ *
+ * The returned plan is deliberately **declarative**: a `send(method, params)` function
+ * applies every command in order. The caller owns the transport, so this module has no
+ * dependency and works over WebSocket, stdio, or an in-process socket.
+ */
+interface CdpCommand {
+    method: string;
+    params?: Record<string, unknown>;
+    /** `sessionId` is required for page-scoped domains when using flattened sessions. */
+    sessionId?: string;
+}
+interface CdpPassportPlan {
+    /** Ordered commands to apply the passport to a target. */
+    commands: CdpCommand[];
+    /** Init scripts to install on every new document. */
+    initScripts: {
+        source: string;
+    }[];
+    /** Extra HTTP headers to set on the session. */
+    headers: Record<string, string>;
+    /** The raw stealth + pixel-protection script, for callers that prefer their own path. */
+    stealthScript: string;
+}
+/**
+ * Builds the ordered CDP command plan for a passport.
+ *
+ * Order matters: the UA override must precede navigation, and the init script has to be
+ * installed before the first document is created.
+ */
+declare function getCdpPlan(passport: DevicePassport, sessionId?: string): CdpPassportPlan;
+/**
+ * Applies a passport through a raw CDP transport.
+ *
+ * @param send Function that sends one CDP command and resolves with its result.
+ */
+declare function applyCdpPassport(passport: DevicePassport, send: (command: CdpCommand) => Promise<unknown>, sessionId?: string): Promise<void>;
+
+export { CANONICAL_HEADER_ORDER, applyCdpPassport, applyToPlaywrightContext, applyToPuppeteerPage, formatCanonicalHeaders, getCdpPlan, getPlaywrightContext, getPuppeteerArgs, getStealthScript, toCurl, withPassport };
+export type { CdpCommand, CdpPassportPlan, PassportLike, PlaywrightContextOptions, PuppeteerEmulationOptions };

package/dist/adapters/index.d.mts

@@ -0,0 +1,156 @@
+import { DevicePassport } from '../types/index.mjs';
+import '../shared/device-passport.C_F1vBE8.mjs';
+
+/**
+ * Standard Chromium browser header ordering.
+ * Anti-bot systems (Cloudflare, Akamai, DataDome, Kasada) strictly inspect
+ * the sequence of HTTP request headers. A mismatch in header order triggers
+ * immediate bot heuristics.
+ */
+declare const CANONICAL_HEADER_ORDER: readonly string[];
+/**
+ * Sorts and formats HTTP headers according to canonical browser ordering.
+ * Merges base headers with optional overrides.
+ */
+declare function formatCanonicalHeaders(baseHeaders: Record<string, string>, overrides?: Record<string, string>): Record<string, string>;
+interface PassportLike {
+    headers: Record<string, string>;
+    getHeaders?: (overrides?: Record<string, string>) => Record<string, string>;
+}
+/**
+ * Higher-order fetch function wrapping standard fetch with canonical DevicePassport headers.
+ * Ensures consistent TLS/HTTP persona across API calls, scraping requests, and webhooks.
+ *
+ * @param passport DevicePassport instance or object
+ * @param customFetch Optional fetch implementation (e.g. node-fetch, undici, or global fetch)
+ */
+declare function withPassport(passport: PassportLike | DevicePassport, customFetch?: typeof fetch): typeof fetch;
+/**
+ * Generates an executable cURL command with correct browser headers.
+ */
+declare function toCurl(passport: PassportLike | DevicePassport, url: string, options?: {
+    method?: string;
+    data?: any;
+    headers?: Record<string, string>;
+}): string;
+
+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>;
+
+/**
+ * Raw Chrome DevTools Protocol adapter.
+ *
+ * 🔴 Why this exists (2026-11-04):
+ *   Tools that drive Chrome over a bare CDP socket — `lite-browser`'s `cdp <method> [json]`
+ *   channel, for example — cannot use the Playwright/Puppeteer adapters, because those
+ *   hand back framework-shaped options. This adapter speaks plain CDP so any CDP client
+ *   can apply a passport.
+ *
+ * The returned plan is deliberately **declarative**: a `send(method, params)` function
+ * applies every command in order. The caller owns the transport, so this module has no
+ * dependency and works over WebSocket, stdio, or an in-process socket.
+ */
+interface CdpCommand {
+    method: string;
+    params?: Record<string, unknown>;
+    /** `sessionId` is required for page-scoped domains when using flattened sessions. */
+    sessionId?: string;
+}
+interface CdpPassportPlan {
+    /** Ordered commands to apply the passport to a target. */
+    commands: CdpCommand[];
+    /** Init scripts to install on every new document. */
+    initScripts: {
+        source: string;
+    }[];
+    /** Extra HTTP headers to set on the session. */
+    headers: Record<string, string>;
+    /** The raw stealth + pixel-protection script, for callers that prefer their own path. */
+    stealthScript: string;
+}
+/**
+ * Builds the ordered CDP command plan for a passport.
+ *
+ * Order matters: the UA override must precede navigation, and the init script has to be
+ * installed before the first document is created.
+ */
+declare function getCdpPlan(passport: DevicePassport, sessionId?: string): CdpPassportPlan;
+/**
+ * Applies a passport through a raw CDP transport.
+ *
+ * @param send Function that sends one CDP command and resolves with its result.
+ */
+declare function applyCdpPassport(passport: DevicePassport, send: (command: CdpCommand) => Promise<unknown>, sessionId?: string): Promise<void>;
+
+export { CANONICAL_HEADER_ORDER, applyCdpPassport, applyToPlaywrightContext, applyToPuppeteerPage, formatCanonicalHeaders, getCdpPlan, getPlaywrightContext, getPuppeteerArgs, getStealthScript, toCurl, withPassport };
+export type { CdpCommand, CdpPassportPlan, PassportLike, PlaywrightContextOptions, PuppeteerEmulationOptions };

package/dist/adapters/index.d.ts

@@ -0,0 +1,156 @@
+import { DevicePassport } from '../types/index.js';
+import '../shared/device-passport.C_F1vBE8.js';
+
+/**
+ * Standard Chromium browser header ordering.
+ * Anti-bot systems (Cloudflare, Akamai, DataDome, Kasada) strictly inspect
+ * the sequence of HTTP request headers. A mismatch in header order triggers
+ * immediate bot heuristics.
+ */
+declare const CANONICAL_HEADER_ORDER: readonly string[];
+/**
+ * Sorts and formats HTTP headers according to canonical browser ordering.
+ * Merges base headers with optional overrides.
+ */
+declare function formatCanonicalHeaders(baseHeaders: Record<string, string>, overrides?: Record<string, string>): Record<string, string>;
+interface PassportLike {
+    headers: Record<string, string>;
+    getHeaders?: (overrides?: Record<string, string>) => Record<string, string>;
+}
+/**
+ * Higher-order fetch function wrapping standard fetch with canonical DevicePassport headers.
+ * Ensures consistent TLS/HTTP persona across API calls, scraping requests, and webhooks.
+ *
+ * @param passport DevicePassport instance or object
+ * @param customFetch Optional fetch implementation (e.g. node-fetch, undici, or global fetch)
+ */
+declare function withPassport(passport: PassportLike | DevicePassport, customFetch?: typeof fetch): typeof fetch;
+/**
+ * Generates an executable cURL command with correct browser headers.
+ */
+declare function toCurl(passport: PassportLike | DevicePassport, url: string, options?: {
+    method?: string;
+    data?: any;
+    headers?: Record<string, string>;
+}): string;
+
+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>;
+
+/**
+ * Raw Chrome DevTools Protocol adapter.
+ *
+ * 🔴 Why this exists (2026-11-04):
+ *   Tools that drive Chrome over a bare CDP socket — `lite-browser`'s `cdp <method> [json]`
+ *   channel, for example — cannot use the Playwright/Puppeteer adapters, because those
+ *   hand back framework-shaped options. This adapter speaks plain CDP so any CDP client
+ *   can apply a passport.
+ *
+ * The returned plan is deliberately **declarative**: a `send(method, params)` function
+ * applies every command in order. The caller owns the transport, so this module has no
+ * dependency and works over WebSocket, stdio, or an in-process socket.
+ */
+interface CdpCommand {
+    method: string;
+    params?: Record<string, unknown>;
+    /** `sessionId` is required for page-scoped domains when using flattened sessions. */
+    sessionId?: string;
+}
+interface CdpPassportPlan {
+    /** Ordered commands to apply the passport to a target. */
+    commands: CdpCommand[];
+    /** Init scripts to install on every new document. */
+    initScripts: {
+        source: string;
+    }[];
+    /** Extra HTTP headers to set on the session. */
+    headers: Record<string, string>;
+    /** The raw stealth + pixel-protection script, for callers that prefer their own path. */
+    stealthScript: string;
+}
+/**
+ * Builds the ordered CDP command plan for a passport.
+ *
+ * Order matters: the UA override must precede navigation, and the init script has to be
+ * installed before the first document is created.
+ */
+declare function getCdpPlan(passport: DevicePassport, sessionId?: string): CdpPassportPlan;
+/**
+ * Applies a passport through a raw CDP transport.
+ *
+ * @param send Function that sends one CDP command and resolves with its result.
+ */
+declare function applyCdpPassport(passport: DevicePassport, send: (command: CdpCommand) => Promise<unknown>, sessionId?: string): Promise<void>;
+
+export { CANONICAL_HEADER_ORDER, applyCdpPassport, applyToPlaywrightContext, applyToPuppeteerPage, formatCanonicalHeaders, getCdpPlan, getPlaywrightContext, getPuppeteerArgs, getStealthScript, toCurl, withPassport };
+export type { CdpCommand, CdpPassportPlan, PassportLike, PlaywrightContextOptions, PuppeteerEmulationOptions };

package/dist/adapters/index.mjs

@@ -0,0 +1,3 @@
+export { C as CANONICAL_HEADER_ORDER, a as applyCdpPassport, b as applyToPlaywrightContext, c as applyToPuppeteerPage, f as formatCanonicalHeaders, g as getCdpPlan, d as getPlaywrightContext, e as getPuppeteerArgs, h as getStealthScript, t as toCurl, w as withPassport } from '../shared/device-passport.NHw_f6HT.mjs';
+import 'node:crypto';
+import '../shared/device-passport.BBf9OKap.mjs';