device-passport 1.0.0 → 1.1.0

package/dist/index.d.cts

@@ -1,388 +1,13 @@
-/**
- * Geographic, Locale and Timezone definitions for Device Passport.
- */
-interface LanguageWeight {
-    code: string;
-    weight?: number;
-}
-interface LocaleProfile {
-    /** Primary locale identifier, e.g. 'en-US', 'zh-CN', 'ja-JP' */
-    language: string;
-    /** Fallback languages ordered by preference, e.g. ['en-US', 'en'] */
-    languages: string[];
-    /** IANA Time Zone identifier, e.g. 'America/New_York', 'Asia/Shanghai' */
-    timezone: string;
-    /** Timezone offset in minutes relative to UTC (e.g. -240 for EDT, +480 for CST) */
-    timezoneOffset: number;
-    /** ISO 3166-1 alpha-2 country code, e.g. 'US', 'GB', 'CN', 'JP' */
-    country: string;
-    /** ISO 4217 currency code, e.g. 'USD', 'EUR', 'CNY', 'JPY' */
-    currency?: string;
-    /** Formatted Accept-Language header string e.g. 'en-US,en;q=0.9' */
-    acceptLanguage?: string;
-}
-interface GeoCoordinates {
-    latitude: number;
-    longitude: number;
-    accuracy?: number;
-}
-interface GeoLocation extends GeoCoordinates {
-    country: string;
-    countryCode?: string;
-    region?: string;
-    city?: string;
-    timezone: string;
-    locale: string;
-    languages: string[];
-}
-interface CountryGeoDefinition {
-    country: string;
-    countryName: string;
-    defaultLocale: string;
-    supportedLocales: string[];
-    defaultTimezone: string;
-    timezones: string[];
-    coordinates: GeoCoordinates;
-    currency?: string;
-}
-interface GeoOptions {
-    /** Explicit ISO country code, country name, or connection string */
-    country?: string;
-    /** Residential proxy URL or IP to detect geographic location from */
-    proxyUrl?: string;
-    ip?: string;
-    /** Explicit IANA timezone override (e.g. 'America/Los_Angeles') */
-    timezone?: string;
-    /** Explicit primary locale override (e.g. 'en-US') */
-    locale?: string;
-    /** Explicit language array override (e.g. ['en-US', 'en']) */
-    languages?: string[];
-    /** Explicit Accept-Language weighted header string override */
-    acceptLanguage?: string;
-    /** Fallback country code if detection fails (defaults to 'US') */
-    fallbackCountry?: string;
-    /** Explicit geographical coordinates override */
-    coordinates?: GeoCoordinates;
-}
-interface GeoContext {
-    country: string;
-    timezone: string;
-    locale: string;
-    language: string;
-    acceptLanguage: string;
-    languages: string[];
-    timezoneOffset: number;
-    currency?: string;
-    coordinates?: GeoCoordinates;
-}
-
-/**
- * Metrics, Consistency Evaluation, and Benchmark types for Device Passport.
- */
-type ConsistencyCategory = 'os_ua_alignment' | 'client_hints_entropy' | 'hardware_plausibility' | 'geo_locale_coherence' | 'webgl_hardware_coupling' | 'screen_viewport_consistency';
-interface ConsistencyCheck {
-    id: string;
-    name: string;
-    category: ConsistencyCategory;
-    passed: boolean;
-    score: number;
-    weight: number;
-    message: string;
-    details?: Record<string, unknown>;
-}
-interface EntropyAnalysis {
-    estimatedBits: number;
-    collisionRisk: 'very_low' | 'low' | 'moderate' | 'high';
-    fingerprintUniqueness?: number;
-}
-type EvaluationStatus = 'PASS' | 'WARN' | 'FAIL';
-type EvaluationGrade = 'A+' | 'A' | 'B' | 'C' | 'F';
-interface PassportEvaluation {
-    /** Overall consistency score (0 - 100) */
-    overallScore: number;
-    /** Pass / Warn / Fail status based on strict thresholds */
-    status: EvaluationStatus;
-    /** Academic grade assessment */
-    grade: EvaluationGrade;
-    /** Individual check breakdowns */
-    checks: ConsistencyCheck[];
-    /** Entropy and collision analysis */
-    entropyAnalysis?: EntropyAnalysis;
-    /** ISO timestamp when evaluated */
-    evaluatedAt: string;
-}
-interface BenchmarkMetrics {
-    passportId: string;
-    determinismScore: number;
-    contradictionRate: number;
-    overallConsistencyScore: number;
-    generationLatencyMs: number;
-    entropyBits: number;
-    timestamp: string;
-}
-
-/**
- * Core type definitions for Device Passport.
- * Compliant with RFC 8942, W3C User-Agent Client Hints, and WebGL specs.
- */
-
-type SupportedBrowserName = 'Chrome' | 'Edge' | 'Safari' | 'Firefox';
-type SupportedPlatform = 'macOS' | 'Windows';
-type SupportedArchitecture = 'arm' | 'x86';
-interface BrowserProfile {
-    name: SupportedBrowserName;
-    version: string;
-    majorVersion: number;
-    userAgent: string;
-}
-interface OperatingSystemProfile {
-    name: SupportedPlatform;
-    platform: SupportedPlatform;
-    version: string;
-    release: string;
-    architecture: SupportedArchitecture;
-}
-interface ScreenProfile {
-    width: number;
-    height: number;
-    availWidth: number;
-    availHeight: number;
-    dpr: number;
-    colorDepth: number;
-    pixelDepth: number;
-}
-interface CpuProfile {
-    architecture: SupportedArchitecture;
-    concurrency: number;
-}
-interface MemoryProfile {
-    deviceMemory: number;
-    physicalMemoryGB?: number;
-}
-interface GpuProfile {
-    vendor: string;
-    renderer: string;
-    webglVendor?: string;
-    webglRenderer?: string;
-}
-interface HardwareProfile {
-    screen: ScreenProfile;
-    cpu: CpuProfile;
-    memory: MemoryProfile;
-    gpu: GpuProfile;
-}
-interface BrandVersion {
-    brand: string;
-    version: string;
-}
-/**
- * Raw RFC 8942 / RFC 8941 structured client hints headers.
- */
-interface ClientHintsHeaders {
-    /** Low-entropy brand and major version, e.g. `"Chromium";v="124", "Google Chrome";v="124", "Not-A.Brand";v="99"` */
-    'sec-ch-ua': string;
-    /** Low-entropy mobile indicator, `"?0"` or `"?1"` */
-    'sec-ch-ua-mobile': string;
-    /** Low-entropy platform, e.g. `"macOS"` or `"Windows"` */
-    'sec-ch-ua-platform': string;
-    /** High-entropy OS version, e.g. `"14.6.1"` or `"15.0.0"` */
-    'sec-ch-ua-platform-version': string;
-    /** High-entropy architecture, e.g. `"arm"` or `"x86"` */
-    'sec-ch-ua-arch': string;
-    /** High-entropy bitness, e.g. `"64"` */
-    'sec-ch-ua-bitness': string;
-    /** High-entropy device model, `""` for desktop */
-    'sec-ch-ua-model': string;
-    /** High-entropy full version list, e.g. `"Chromium";v="124.0.6367.208", "Google Chrome";v="124.0.6367.208"` */
-    'sec-ch-ua-full-version-list': string;
-    /** High-entropy 32-bit on 64-bit Windows flag, `"?0"` */
-    'sec-ch-ua-wow64'?: string;
-}
-/**
- * Structured User-Agent Client Hints object representing navigator.userAgentData.
- */
-interface UserAgentClientHints {
-    brands: BrandVersion[];
-    mobile: boolean;
-    platform: string;
-    platformVersion: string;
-    architecture: string;
-    bitness: string;
-    model: string;
-    fullVersionList: BrandVersion[];
-    wow64?: boolean;
-    /** Serialized RFC 8942 compliant headers */
-    headers: ClientHintsHeaders;
-}
-interface DevicePassportContext {
-    viewport: {
-        width: number;
-        height: number;
-    };
-    userAgent: string;
-    locale: string;
-    timezoneId: string;
-    geolocation?: {
-        latitude: number;
-        longitude: number;
-        accuracy?: number;
-    };
-    permissions?: string[];
-    extraHTTPHeaders: Record<string, string>;
-    deviceScaleFactor: number;
-    hasTouch: boolean;
-    isMobile: boolean;
-    colorScheme?: 'light' | 'dark' | 'no-preference';
-}
-interface DevicePassport {
-    /** Unique deterministic or UUID identifier */
-    id: string;
-    /** Seed used to generate this passport */
-    seed: string;
-    /** ISO 8601 creation timestamp */
-    createdAt: string;
-    /** Browser profile */
-    browser: BrowserProfile;
-    /** Operating system profile */
-    os: OperatingSystemProfile;
-    /** Hardware profile (screen, cpu, memory, gpu) */
-    hardware: HardwareProfile;
-    /** Locale, language, timezone */
-    locale: LocaleProfile;
-    /** All HTTP headers (User-Agent, Sec-CH-UA*, Accept*, etc.) */
-    headers: Record<string, string>;
-    /** High-entropy and low-entropy Client Hints */
-    clientHints: UserAgentClientHints;
-    /** Ready-to-use context options for Playwright / Puppeteer / Browser */
-    context: DevicePassportContext;
-    /** Consistency and anti-detection score evaluation */
-    evaluation?: PassportEvaluation;
-    /** Optional helper method to get merged headers */
-    getHeaders?: (overrides?: Record<string, string>) => Record<string, string>;
-}
-/** Alias for backward compatibility */
-type DeviceProfile = DevicePassport;
-interface PassportGeneratorOptions {
-    /** Deterministic seed (username, account ID, proxy IP, etc.) */
-    seed?: string | number;
-    /** Geographic country code ('US', 'JP', etc.) or residential proxy URL */
-    geo?: string;
-    /** Residential proxy URL to detect geographical location from */
-    proxy?: string;
-    proxyUrl?: string;
-    /** Preferred Operating System */
-    os?: SupportedPlatform;
-    /** Preferred Browser */
-    browser?: SupportedBrowserName;
-    /** Preferred primary locale (e.g. 'en-US', 'zh-CN') */
-    locale?: string;
-    /** Preferred country code (e.g. 'US', 'GB', 'DE', 'JP') */
-    country?: string;
-    /** Preferred timezone (e.g. 'America/New_York') */
-    timezone?: string;
-    /** Whether to integrate with header-generator when available */
-    useHeaderGenerator?: boolean;
-    /** Hardware tier preference */
-    hardwareTier?: 'standard' | 'high-performance';
-}
-
-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).
- */
-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>;
-
-/**
- * StorageAdapter interface for DevicePassport persistence.
- * Implementations provide pluggable storage backends (Memory, File, Redis, DB, etc.)
- */
-interface StorageAdapter<T = any> {
-    /**
-     * Retrieve an item by key.
-     * Returns null if key does not exist.
-     */
-    get(key: string): Promise<T | null>;
-    /**
-     * Store an item with the given key.
-     */
-    set(key: string, value: T): Promise<void>;
-    /**
-     * Check if a key exists in storage.
-     */
-    has(key: string): Promise<boolean>;
-    /**
-     * Delete an item by key.
-     * Returns true if item existed and was deleted, false otherwise.
-     */
-    delete(key: string): Promise<boolean>;
-    /**
-     * Return all keys currently stored.
-     */
-    keys(): Promise<string[]>;
-    /**
-     * Clear all items in this storage.
-     */
-    clear(): Promise<void>;
-}
+import { PassportGeneratorOptions, DevicePassport, BrowserProfile, OperatingSystemProfile, HardwareProfile, UserAgentClientHints, DevicePassportContext, PassportEvaluation, SupportedPlatform, SupportedBrowserName, SupportedArchitecture, BrandVersion } from './types/index.cjs';
+export { BenchmarkMetrics, ClientHintsHeaders, ConsistencyCategory, ConsistencyCheck, CpuProfile, DeviceProfile, EntropyAnalysis, EvaluationGrade, EvaluationStatus, GpuProfile, MemoryProfile, ScreenProfile } from './types/index.cjs';
+import { PlaywrightContextOptions, PuppeteerEmulationOptions } from './adapters/index.cjs';
+export { CANONICAL_HEADER_ORDER, CdpCommand, CdpPassportPlan, PassportLike, applyCdpPassport, applyToPlaywrightContext, applyToPuppeteerPage, formatCanonicalHeaders, getCdpPlan, getPlaywrightContext, getPuppeteerArgs, getStealthScript, toCurl, withPassport } from './adapters/index.cjs';
+import { StorageAdapter } from './storage/index.cjs';
+export { JSONFileStorage, JSONFileStorageOptions, MemoryStorage, MemoryStorageOptions } from './storage/index.cjs';
+import { L as LocaleProfile } from './shared/device-passport.C_F1vBE8.cjs';
+export { C as CountryGeoDefinition, G as GeoContext, a as GeoCoordinates, b as GeoLocation, c as GeoOptions, d as LanguageWeight } from './shared/device-passport.C_F1vBE8.cjs';
+export { ALPHA3_TO_ALPHA2, COUNTRY_LOCALES, COUNTRY_NAME_TO_CODE, CountryLocaleConfig, DEFAULT_ACCEPT_LANGUAGE, DEFAULT_COUNTRY, DEFAULT_LOCALE, DEFAULT_TIMEZONE, GEO_LOCALES, GeoDetectOptions, TIMEZONE_MATRIX, TIMEZONE_TO_COUNTRY, alignGeoContext, detectCountry, detectGeoFromUrl, extractCountryFromProxyUrl, formatAcceptLanguage, getAllSupportedCountries, getCountryConfig, getCountryForTimezone, getDefaultTimezoneForCountry, getLocaleProfile, getTimezoneOffsetMinutes, getTimezonesForCountry, hasCountryConfig, isGeoAligned, isTimezoneAlignedWithCountry, isValidCountryCode, isValidTimezone, listAllTimezones, normalizeCountryCode, parseAcceptLanguage, toGeoLocation, toLocaleProfile } from './geo/index.cjs';
+export { BASELINE_OPTIMAL_ENTROPY, BROWSER_BASELINE_FREQUENCIES, COUNTRY_PRIMARY_LANGUAGES, COUNTRY_TIMEZONE_MAP, CoherenceEvaluationResult, Contradiction, ContradictionCategory, ContradictionSeverity, EntropyAnalysisResult, HeaderEntropyProfile, MIN_STRUCTURAL_ENTROPY, MathematicalModelFormalism, OPTIMAL_CHAR_ENTROPY_MAX, OPTIMAL_CHAR_ENTROPY_MIN, OPTIMAL_ENTROPY_MAX, OPTIMAL_ENTROPY_MIN, SubspaceEvaluation, analyzeHeaderEntropy, calculateKLDivergence, calculateShannonEntropy, calculateStructuralEntropy, detectAllContradictions, detectClientHintsContradictions, detectGeoChronoContradictions, detectHardwareContradictions, detectOSBrowserContradictions, evaluateCoherence, evaluateGeoAlignment, evaluatePassport } from './evaluator/index.cjs';
 
 /**
  * DevicePassportInstance encapsulates a single concrete, zero-contradiction digital identity persona.
@@ -707,533 +332,50 @@ declare function generatePassport(options?: PassportGeneratorOptions): DevicePas
 declare const generateDevicePassport: typeof generatePassport;
 
 /**
- * Comprehensive Geographic-Locale Mapping Database.
- * Zero-dependency, pure TypeScript.
- */
-
-interface CountryLocaleConfig {
-    /** ISO 3166-1 alpha-2 uppercase country code */
-    country: string;
-    /** Full English country name */
-    countryName: string;
-    /** Primary locale identifier, e.g. 'en-US', 'ja-JP' */
-    primaryLocale: string;
-    /** Primary and fallback languages ordered by preference */
-    languages: string[];
-    /** Strictly formatted RFC 9110 Accept-Language weighted header string */
-    acceptLanguage: string;
-    /** Supported IANA timezones within this country */
-    timezones: string[];
-    /** Default primary IANA timezone */
-    defaultTimezone: string;
-    /** ISO 4217 currency code */
-    currency: string;
-    /** Representative geographical center/capital coordinates */
-    coordinates: GeoCoordinates;
-}
-/**
- * Global fallback defaults
- */
-declare const DEFAULT_COUNTRY = "US";
-declare const DEFAULT_LOCALE = "en-US";
-declare const DEFAULT_TIMEZONE = "America/New_York";
-declare const DEFAULT_ACCEPT_LANGUAGE = "en-US,en;q=0.9";
-/**
- * Comprehensive Country Locale & Geographic Database.
- */
-declare const COUNTRY_LOCALES: Record<string, CountryLocaleConfig>;
-/**
- * Get country locale configuration with fallback.
- */
-declare function getCountryConfig(countryCode?: string | null): CountryLocaleConfig;
-/**
- * Check if a country code is supported in the database.
- */
-declare function hasCountryConfig(countryCode?: string | null): boolean;
-/**
- * Get all supported ISO country codes.
- */
-declare function getAllSupportedCountries(): string[];
-/**
- * Strictly format an Accept-Language weighted header string from an array of languages.
- * Example: ['en-US', 'en'] -> 'en-US,en;q=0.9'
- * Example: ['de-DE', 'de', 'en-US', 'en'] -> 'de-DE,de;q=0.9,en-US;q=0.8,en;q=0.7'
- */
-declare function formatAcceptLanguage(languages: string[]): string;
-/**
- * Parse an Accept-Language header string into an array of { locale, q } items ordered by weight descending.
- */
-declare function parseAcceptLanguage(header: string): Array<{
-    locale: string;
-    q: number;
-}>;
-
-/**
- * Timezone Matrix and Chrono-Alignment Engine.
- * Pure TypeScript, zero external dependencies.
- */
-/**
- * Direct mapping from IANA Timezone ID to ISO 3166-1 alpha-2 country code.
- */
-declare const TIMEZONE_TO_COUNTRY: Record<string, string>;
-/**
- * Validate if a timezone string is a valid IANA timezone identifier.
- */
-declare function isValidTimezone(timezone: string): boolean;
-/**
- * Get all supported timezones for a specific country code.
- */
-declare function getTimezonesForCountry(countryCode: string): string[];
-/**
- * Look up the ISO country code associated with an IANA timezone identifier.
- */
-declare function getCountryForTimezone(timezone: string): string | undefined;
-/**
- * Get the primary/default timezone for a country code.
- */
-declare function getDefaultTimezoneForCountry(countryCode: string): string;
-/**
- * Check if a timezone is chronologically aligned with a given country.
- */
-declare function isTimezoneAlignedWithCountry(timezone: string, countryCode: string): boolean;
-/**
- * Calculate timezone offset in minutes relative to UTC.
- * Note: Following the standard convention matching LocaleProfile.timezoneOffset:
- * - Negative for zones west of UTC (e.g. -240 for EDT, -300 for EST)
- * - Positive for zones east of UTC (e.g. +480 for CST / Asia/Shanghai, +540 for JST)
- * - 0 for UTC
- */
-declare function getTimezoneOffsetMinutes(timezone: string, date?: Date): number;
-/**
- * List all unique timezones known to the system.
- */
-declare function listAllTimezones(): string[];
-
-/**
- * Proxy and Geo-Context Detector.
- * Extracts country and geo information from residential proxy URLs, IP hints, or explicit ISO codes.
- * Pure TypeScript, zero external dependencies.
- */
-interface GeoDetectOptions {
-    /** Country code to fall back to if detection fails. Defaults to 'US'. */
-    fallbackCountry?: string;
-}
-/**
- * ISO 3166-1 alpha-3 to alpha-2 code mapping.
- */
-declare const ALPHA3_TO_ALPHA2: Record<string, string>;
-/**
- * Common English country name aliases to ISO 3166-1 alpha-2 code.
- */
-declare const COUNTRY_NAME_TO_CODE: Record<string, string>;
-/**
- * Normalize any country input (2-letter, 3-letter, alias, name) to an ISO 3166-1 alpha-2 uppercase code.
- */
-declare function normalizeCountryCode(code?: string | null): string | null;
-/**
- * Extract an ISO country code from a residential proxy URL or connection string.
- * Supports:
- * - Username authentication tokens (e.g. user-country-us, customer-zone-cc-DE, lum-customer-*-country-fr)
- * - Query parameters (e.g. ?country=JP, &country_code=KR, ?cc=SG, &geo=DE)
- * - Subdomain patterns (e.g. us.smartproxy.com, jp.proxy-seller.com)
- */
-declare function extractCountryFromProxyUrl(url: string): string | null;
-/**
- * Universal country detector.
- * Accepts:
- * - Explicit ISO 3166-1 alpha-2 / alpha-3 codes ('US', 'GB', 'jp', 'JPN')
- * - Country names ('Japan', 'United States', 'Germany')
- * - Residential proxy URLs (http://user-country-us:pass@proxy...)
- * - IANA Timezone strings ('America/New_York' -> 'US', 'Asia/Tokyo' -> 'JP')
- * - Falls back to DEFAULT_COUNTRY ('US') when unknown.
- */
-declare function detectCountry(input?: string | null, options?: GeoDetectOptions): string;
-
-/**
- * Geo-Chrono Aligner.
- * Aligns browser persona parameters (country, timezone, locale, accept-language header)
- * with zero contradictions for stealth crawlers and automation.
- * Pure TypeScript, zero external dependencies.
- */
-
-/**
- * Align geographic and chronological parameters into a cohesive, contradiction-free GeoContext.
- *
- * @param geoInput Proxy URL, ISO country code, IANA timezone string, or GeoOptions object
- * @returns Fully correlated GeoContext
- */
-declare function alignGeoContext(geoInput?: string | GeoOptions): GeoContext;
-/**
- * Verify whether a partial or full GeoContext is free of geographic or chronological contradictions.
- */
-declare function isGeoAligned(context: Partial<GeoContext>): boolean;
-/**
- * Format GeoContext into a LocaleProfile for runtime device-passport consumers.
- */
-declare function toLocaleProfile(geo: GeoContext): {
-    language: string;
-    languages: string[];
-    timezone: string;
-    timezoneOffset: number;
-    country: string;
-    currency: string | undefined;
-};
-/**
- * Format GeoContext into a GeoLocation object for browser geolocation emulation.
- */
-declare function toGeoLocation(geo: GeoContext): {
-    latitude: number;
-    longitude: number;
-    accuracy: number;
-    country: string;
-    countryCode: string;
-    timezone: string;
-    locale: string;
-    languages: string[];
-};
-
-/**
- * Geo and Chrono Aligner module for Device Passport.
- * Provides geographic-locale mapping database, proxy/IP geo detector,
- * and zero-contradiction geo-chrono alignment.
- */
-
-declare const GEO_LOCALES: Record<string, CountryLocaleConfig>;
-declare const TIMEZONE_MATRIX: Record<string, string>;
-declare const isValidCountryCode: typeof hasCountryConfig;
-/**
- * Detect country code from residential proxy URL.
- */
-declare function detectGeoFromUrl(url: string): string | null;
-/**
- * Get a complete LocaleProfile for a country code and optional timezone.
- */
-declare function getLocaleProfile(countryCode?: string | null, timezone?: string): LocaleProfile;
-
-/**
- * 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 MemoryStorageOptions {
-    /**
-     * Whether to deep-clone stored and retrieved objects to prevent external mutations.
-     * Defaults to true.
-     */
-    clone?: boolean;
-}
-/**
- * In-memory storage adapter.
- * Useful for ephemeral scraping runs, tests, and caching.
- */
-declare class MemoryStorage<T = any> implements StorageAdapter<T> {
-    private readonly store;
-    private readonly clone;
-    constructor(options?: MemoryStorageOptions);
-    private deepClone;
-    get(key: string): Promise<T | null>;
-    getSync(key: string): T | null;
-    set(key: string, value: T): Promise<void>;
-    setSync(key: string, value: T): void;
-    has(key: string): Promise<boolean>;
-    hasSync(key: string): boolean;
-    delete(key: string): Promise<boolean>;
-    deleteSync(key: string): boolean;
-    keys(): Promise<string[]>;
-    keysSync(): string[];
-    clear(): Promise<void>;
-    clearSync(): void;
-    get size(): number;
-}
-
-interface JSONFileStorageOptions {
-    /**
-     * Path to the JSON file on disk.
-     */
-    filePath: string;
-    /**
-     * Format JSON with indentation for readability.
-     * Defaults to true.
-     */
-    pretty?: boolean;
-    /**
-     * Auto-save to disk immediately when values change.
-     * Defaults to true.
-     */
-    autoSave?: boolean;
-}
-/**
- * File-backed JSON storage adapter.
- * Uses atomic writes via temp-file + renameSync to ensure zero corruption
- * even if the process is killed mid-write. Automatically creates directories.
- */
-declare class JSONFileStorage<T = any> implements StorageAdapter<T> {
-    readonly filePath: string;
-    private readonly pretty;
-    private readonly autoSave;
-    private readonly cache;
-    private isLoaded;
-    private writeQueue;
-    constructor(filePathOrOptions: string | JSONFileStorageOptions);
-    /**
-     * Ensure data is loaded from disk into the in-memory cache.
-     */
-    private ensureLoaded;
-    /**
-     * Atomic flush to disk. Writes to a unique temp file in the same directory,
-     * then atomically renames it to target file.
-     */
-    private flushAtomic;
-    /**
-     * Queue a disk write to prevent race conditions during rapid concurrent mutations.
-     */
-    private queueSave;
-    get(key: string): Promise<T | null>;
-    getSync(key: string): T | null;
-    set(key: string, value: T): Promise<void>;
-    setSync(key: string, value: T): void;
-    has(key: string): Promise<boolean>;
-    hasSync(key: string): boolean;
-    delete(key: string): Promise<boolean>;
-    deleteSync(key: string): boolean;
-    keys(): Promise<string[]>;
-    keysSync(): string[];
-    clear(): Promise<void>;
-    clearSync(): void;
-    /**
-     * Explicitly force a flush to disk (useful if autoSave is set to false).
-     */
-    flush(): Promise<void>;
-    flushSync(): void;
-    get size(): number;
-}
-
-/**
- * Contradiction Detection Engine for Device Passport.
- *
- * Evaluates cross-layer integrity across the 4-tuple formal model:
- * P = ⟨H, S, G, C⟩ (Hardware, System, Geo, Client-Hints).
- *
- * Implements deterministic anomaly and anti-fingerprinting rules based on
- * empirical browser telemetry, W3C Client Hints RFCs, and anti-bot heuristic vectors.
- */
-
-type ContradictionSeverity = 'fatal' | 'high' | 'medium' | 'low';
-type ContradictionCategory = 'hardware_system' | 'os_browser' | 'geo_chrono' | 'client_hints' | 'entropy';
-interface Contradiction {
-    id: string;
-    category: ContradictionCategory;
-    severity: ContradictionSeverity;
-    description: string;
-    fields: string[];
-    actual: unknown;
-    expected: unknown;
-    impactPenalty: number;
-}
-declare const COUNTRY_TIMEZONE_MAP: Record<string, string[]>;
-declare const COUNTRY_PRIMARY_LANGUAGES: Record<string, string[]>;
-/**
- * Detect OS vs Browser compatibility contradictions.
- */
-declare function detectOSBrowserContradictions(passport: DevicePassport): Contradiction[];
-/**
- * Detect Hardware vs System cross-layer contradictions.
- */
-declare function detectHardwareContradictions(passport: DevicePassport): Contradiction[];
-/**
- * Detect Geographic, Locale, and Chronological (Geo-Chrono) Contradictions.
- */
-declare function detectGeoChronoContradictions(passport: DevicePassport): Contradiction[];
-/**
- * Detect W3C Client Hints Internal Consistency Contradictions.
- */
-declare function detectClientHintsContradictions(passport: DevicePassport): Contradiction[];
-/**
- * Master contradiction detection runner across all 4 sub-spaces:
- * P = ⟨H, S, G, C⟩.
- */
-declare function detectAllContradictions(passport: DevicePassport): Contradiction[];
-
-/**
- * Shannon Entropy Analyzer for Device Passport HTTP Headers.
- *
- * Grounded in Information Theory (Shannon, 1948: "A Mathematical Theory of Communication"):
- * H(X) = - \sum_{i=1}^{n} P(x_i) \log_2 P(x_i)
- *
- * Evaluates generated header distributions against empirical modern browser baselines
- * to detect:
- * 1. Under-parameterized / Low-entropy signatures (naive scrapers, curl, missing sec-ch headers)
- * 2. Over-parameterized / High-entropy anomalies (random noise injection, spoofing artifacts)
- * 3. Relative Entropy (Kullback-Leibler Divergence) against empirical Chrome/Edge/Safari profiles
- */
-interface HeaderEntropyProfile {
-    characterEntropy: number;
-    structuralEntropy: number;
-    klDivergence: number;
-    totalHeaderBytes: number;
-    headerCount: number;
-}
-interface EntropyAnalysisResult {
-    entropyScore: number;
-    estimatedBits: number;
-    klDivergence: number;
-    anomaly: 'too_low' | 'too_high' | 'optimal';
-    collisionRisk: 'very_low' | 'low' | 'moderate' | 'high';
-    verdict: string;
-    details: {
-        characterEntropy: number;
-        structuralEntropy: number;
-        baselineEntropy: number;
-        deltaFromOptimal: number;
-    };
-}
-/**
- * Empirical baseline frequency distribution of headers in real modern desktop browsers (Chromium 120+).
- * Baseline average entropy is calibrated at 4.45 bits/char.
- */
-declare const BROWSER_BASELINE_FREQUENCIES: Record<string, number>;
-declare const OPTIMAL_CHAR_ENTROPY_MIN = 4.6;
-declare const OPTIMAL_CHAR_ENTROPY_MAX = 5.6;
-declare const OPTIMAL_ENTROPY_MIN = 4.6;
-declare const OPTIMAL_ENTROPY_MAX = 5.6;
-declare const BASELINE_OPTIMAL_ENTROPY = 5.25;
-declare const MIN_STRUCTURAL_ENTROPY = 3.5;
-/**
- * Calculates fundamental Shannon Information Entropy (in bits) of any string input.
- * H(X) = -\sum_{i=1}^n P(x_i) \log_2 P(x_i)
- */
-declare function calculateShannonEntropy(data: string): number;
-/**
- * Calculates structural header presence entropy across expected browser header space.
- */
-declare function calculateStructuralEntropy(headers: Record<string, string>): number;
-/**
- * Calculates Kullback-Leibler (KL) Divergence:
- * D_KL(P || Q) = \sum P(x) * log2(P(x) / Q(x))
- * Measures informational distance between current header distribution and natural browser baseline.
- */
-declare function calculateKLDivergence(headers: Record<string, string>): number;
-/**
- * Analyzes the entropy of an HTTP header dictionary.
- * Evaluates whether entropy is in the realistic "sweet spot" of real browser traffic.
- */
-declare function analyzeHeaderEntropy(headers: Record<string, string>): EntropyAnalysisResult;
-
-/**
- * Academic Coherence Evaluator for Device Passport.
+ * Pixel-Level Protection — canvas / WebGL noise that survives read-back.
  *
- * Implements the Formal Mathematical Model:
- * P = ⟨H, S, G, C⟩
+ * 🔴 Why this module exists (real gap found 2026-11-04):
+ *   `getStealthScript()` only rewrites **API return values**. `canvas.toDataURL()` and
+ *   `gl.readPixels()` still hand back the **real** framebuffer, so a headless Chromium
+ *   exposes `ANGLE (Google, Vulkan 1.3.0 (SwiftShader Device ...))` while its UA claims
+ *   a discrete NVIDIA card. Worse, every persona rendered on the same machine produces a
+ *   **byte-identical** canvas hash — a fleet of accounts with different identities but one
+ *   identical pixel fingerprint is trivially clustered.
  *
- * Where:
- * - H ∈ Ω_H: Hardware Sub-space ⟨Screen, CPU, Memory, GPU⟩
- * - S ∈ Ω_S: System Sub-space ⟨OS, Browser, UserAgent⟩
- * - G ∈ Ω_G: Geo-Chrono Sub-space ⟨Country, Timezone, Locale, Languages, Coordinates⟩
- * - C ∈ Ω_C: Client-Hints Sub-space ⟨Sec-CH-UA*, Low & High Entropy Hints⟩
+ * ⚠️ Determinism is the whole point:
+ *   The noise MUST be derived from the passport seed, never from `Math.random()`.
+ *   The same account has to read back identical pixels on every visit, otherwise a
+ *   changing canvas hash is itself an automation signal (and breaks "sticky hardware").
  *
- * The coherence evaluation function Φ(P) maps P into [0, 100%], quantifying
- * cross-subspace plausibility and absence of anti-bot contradiction signatures.
+ * The noise is a **seeded permutation of a few discrete levels**, not random dithering:
+ *   real devices quantize canvas output; a smooth ±1 RGB jitter on every pixel is its own
+ *   fingerprint because no GPU produces it.
  */
-
-interface SubspaceEvaluation {
-    valid: boolean;
-    score: number;
-    notes: string[];
-}
-interface MathematicalModelFormalism {
-    formalism: string;
-    definition: {
-        H: string;
-        S: string;
-        G: string;
-        C: string;
-    };
-    subspaces: {
-        H: SubspaceEvaluation;
-        S: SubspaceEvaluation;
-        G: SubspaceEvaluation;
-        C: SubspaceEvaluation;
-    };
-}
-interface CoherenceEvaluationResult {
-    /** Overall cross-layer coherence score (0 - 100%) */
-    coherenceScore: number;
-    /** Specific geo-temporal-linguistic alignment score (0 - 100%) */
-    geoAlignmentScore: number;
-    /** Shannon entropy realistic score (0 - 100%) */
-    entropyScore: number;
-    /** List of detected contradictions and anomalies */
-    contradictions: Contradiction[];
-    /** Mathematical formalization of the evaluation state */
-    mathematicalModel: MathematicalModelFormalism;
-    /** Entropy analysis breakdown */
-    entropyAnalysis: EntropyAnalysisResult;
-    /** Evaluation summary and grade */
-    summary: {
-        passed: boolean;
-        fatalCount: number;
-        warningCount: number;
-        grade: 'A+' | 'A' | 'B' | 'C' | 'F';
-        verdict: string;
-    };
+/** Canvas read-back surface exposed to the page. */
+interface CanvasNoiseConfig {
+    /** Deterministic seed; identical seeds must produce identical pixels. */
+    seed: string;
+    /** Maximum per-channel deviation applied to read-back pixels. */
+    amplitude?: number;
+    /** Noise applied to 2D canvas read-back. */
+    enabled2d?: boolean;
+    /** Noise applied to WebGL read-back. */
+    enabledWebgl?: boolean;
 }
 /**
- * Calculates Geo-Alignment score between Geographic Country, Timezone, and Accept-Language.
- */
-declare function evaluateGeoAlignment(passport: DevicePassport): number;
-/**
- * Evaluates the complete internal consistency and coherence of a Device Passport.
+ * Produces the JavaScript source that patches canvas and WebGL read-back.
  *
- * Implements:
- * Φ: Ω_H × Ω_S × Ω_G × Ω_C → [0, 100%]
+ * The patch is intentionally dependency-free and IIFE-scoped so it can be injected through
+ * Playwright `addInitScript`, Puppeteer `evaluateOnNewDocument`, or a raw CDP
+ * `Page.addScriptToEvaluateOnNewDocument` call.
  */
-declare function evaluateCoherence(passport: DevicePassport): CoherenceEvaluationResult;
-
+declare function getPixelProtectionScript(config: CanvasNoiseConfig): string;
 /**
- * Academic Evaluation Engine for Device Passport.
+ * Builds the noise configuration for a passport.
  *
- * Implements verification algorithms for the formal model:
- * P = ⟨H, S, G, C⟩
- *
- * Evaluates:
- * 1. Internal Coherence Score (0 - 100%)
- * 2. Geo-Chrono-Linguistic Alignment Score (0 - 100%)
- * 3. Shannon Entropy Analyzer for HTTP Header Distributions
- * 4. Cross-layer Contradiction and Detection Anomaly Detection
- */
-
-/**
- * High-level evaluation entry point for any DevicePassport instance.
+ * The seed is the passport seed, so a persona keeps identical pixels across sessions.
  */
-declare function evaluatePassport(passport: DevicePassport): CoherenceEvaluationResult;
+declare function getPixelProtectionConfig(seed: string, overrides?: Partial<Omit<CanvasNoiseConfig, 'seed'>>): CanvasNoiseConfig;
 
 /**
  * Academic Comparative Benchmark Matrix for Anti-Detection and Device Personas.
@@ -1330,5 +472,5 @@ declare function formatComparativeMatrixJSON(): string;
  */
 declare const VERSION = "1.0.0";
 
-export { ALL_PRESETS, ALPHA3_TO_ALPHA2, BASELINE_OPTIMAL_ENTROPY, BENCHMARK_METRICS_METADATA, BROWSER_BASELINE_FREQUENCIES, CANONICAL_HEADER_ORDER, CHROME_VERSIONS, COMPARATIVE_DATASET, COUNTRY_LOCALES, COUNTRY_NAME_TO_CODE, COUNTRY_PRIMARY_LANGUAGES, COUNTRY_TIMEZONE_MAP, DEFAULT_ACCEPT_LANGUAGE, DEFAULT_COUNTRY, DEFAULT_LOCALE, DEFAULT_TIMEZONE, DevicePassportInstance, EDGE_VERSIONS, GEO_LOCALES, JSONFileStorage, MACOS_PRESETS, MIN_STRUCTURAL_ENTROPY, MemoryStorage, OPTIMAL_CHAR_ENTROPY_MAX, OPTIMAL_CHAR_ENTROPY_MIN, OPTIMAL_ENTROPY_MAX, OPTIMAL_ENTROPY_MIN, PassportManager, TIMEZONE_MATRIX, TIMEZONE_TO_COUNTRY, VERSION, WINDOWS_PRESETS, alignGeoContext, analyzeHeaderEntropy, applyToPlaywrightContext, applyToPuppeteerPage, buildUserAgent, calculateKLDivergence, calculateShannonEntropy, calculateStructuralEntropy, createDeterministicPRNG, createMulberry32, createPassport, detectAllContradictions, detectClientHintsContradictions, detectCountry, detectGeoChronoContradictions, detectGeoFromUrl, detectHardwareContradictions, detectOSBrowserContradictions, evaluateCoherence, evaluateGeoAlignment, evaluatePassport, extractCountryFromProxyUrl, fnv1a, formatAcceptLanguage, formatCanonicalHeaders, formatComparativeMatrixJSON, formatComparativeMatrixLaTeX, formatComparativeMatrixMarkdown, formatStructuredBrandList, generateBrandVersions, generateDevicePassport, generatePassport, generateUserAgentClientHints, getAllSupportedCountries, getApifyHeadersIfAvailable, getCountryConfig, getCountryForTimezone, getDefaultTimezoneForCountry, getHardwarePresets, getLocaleProfile, getPlaywrightContext, getPuppeteerArgs, getStaticFallbackHeaders, getStealthScript, getTimezoneOffsetMinutes, getTimezonesForCountry, hasCountryConfig, isGeoAligned, isTimezoneAlignedWithCountry, isValidCountryCode, isValidTimezone, listAllTimezones, murmur3, normalizeCountryCode, parseAcceptLanguage, parseStructuredBrandList, runComparativeBenchmark, toCurl, toGeoLocation, toLocaleProfile, validateHardwareContradictions, withPassport };
-export type { BenchmarkMetrics, BenchmarkReportSummary, BrandVersion, BrowserProfile, ClientHintsGenerateOptions, ClientHintsHeaders, CoherenceEvaluationResult, ConsistencyCategory, ConsistencyCheck, Contradiction, ContradictionCategory, ContradictionSeverity, CountryGeoDefinition, CountryLocaleConfig, CpuProfile, CreatePassportInputOptions, DeviceMatrixPreset, DevicePassport, DevicePassportContext, DeviceProfile, EntropyAnalysis, EntropyAnalysisResult, EvaluationGrade, EvaluationStatus, GeoContext, GeoCoordinates, GeoDetectOptions, GeoLocation, GeoOptions, GpuProfile, HardwareProfile, HeaderEntropyProfile, JSONFileStorageOptions, LanguageWeight, LibraryBenchmarkProfile, LocaleProfile, MathematicalModelFormalism, MemoryProfile, MemoryStorageOptions, MetricMetadata, MetricScore, OperatingSystemProfile, PassportEvaluation, PassportGeneratorOptions, PassportLike, PassportManagerOptions, PlaywrightContextOptions, PuppeteerEmulationOptions, ScreenProfile, StorageAdapter, SubspaceEvaluation, SupportedArchitecture, SupportedBrowserName, SupportedPlatform, UserAgentClientHints };
+export { ALL_PRESETS, BENCHMARK_METRICS_METADATA, BrandVersion, BrowserProfile, CHROME_VERSIONS, COMPARATIVE_DATASET, DevicePassport, DevicePassportContext, DevicePassportInstance, EDGE_VERSIONS, HardwareProfile, LocaleProfile, MACOS_PRESETS, OperatingSystemProfile, PassportEvaluation, PassportGeneratorOptions, PassportManager, PlaywrightContextOptions, PuppeteerEmulationOptions, StorageAdapter, SupportedArchitecture, SupportedBrowserName, SupportedPlatform, UserAgentClientHints, VERSION, WINDOWS_PRESETS, buildUserAgent, createDeterministicPRNG, createMulberry32, createPassport, fnv1a, formatComparativeMatrixJSON, formatComparativeMatrixLaTeX, formatComparativeMatrixMarkdown, formatStructuredBrandList, generateBrandVersions, generateDevicePassport, generatePassport, generateUserAgentClientHints, getApifyHeadersIfAvailable, getHardwarePresets, getPixelProtectionConfig, getPixelProtectionScript, getStaticFallbackHeaders, murmur3, parseStructuredBrandList, runComparativeBenchmark, validateHardwareContradictions };
+export type { BenchmarkReportSummary, CanvasNoiseConfig, ClientHintsGenerateOptions, CreatePassportInputOptions, DeviceMatrixPreset, LibraryBenchmarkProfile, MetricMetadata, MetricScore, PassportManagerOptions };