device-passport 1.0.0 → 1.2.0

package/dist/types/index.d.ts

@@ -0,0 +1,397 @@
+import { L as LocaleProfile } from '../shared/device-passport.C_F1vBE8.js';
+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.js';
+
+/**
+ * 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;
+}
+
+/**
+ * Chrome DevTools Protocol command types.
+ *
+ * 🔴 SSOP: these live in `src/types/` so that both the CDP adapter and the
+ * ego-lite account profile layer speak about "a CDP command" with one shape.
+ * Do not redeclare these interfaces inside a submodule.
+ */
+/** A single CDP command, ready to be sent over any CDP transport. */
+interface CdpCommand {
+    method: string;
+    params?: Record<string, unknown>;
+    /** `sessionId` is required for page-scoped domains when using flattened sessions. */
+    sessionId?: string;
+}
+/** An init script installed on every new document of a target. */
+interface CdpInitScript {
+    source: string;
+    /** `sessionId` is required for page-scoped targets when using flattened sessions. */
+    sessionId?: string;
+}
+/** The ordered, declarative plan that applies a passport to a CDP target. */
+interface CdpPassportPlan {
+    /** Ordered commands to apply the passport to a target. */
+    commands: CdpCommand[];
+    /** Init scripts to install on every new document. */
+    initScripts: CdpInitScript[];
+    /** 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;
+}
+
+/**
+ * ego-lite account profile types.
+ *
+ * 🔴 SSOP: shared domain types live here, not inside `src/ego/`.
+ *
+ * ## Why the proxy is a declared *gap* rather than a feature
+ *
+ * ego-lite exposes no browser-level proxy configuration:
+ *   · there is no `Browser.setProxySettings` in CDP (Chromium has never shipped it),
+ *   · ego-lite's native bindings have no proxy setter either — the binding list is
+ *     `listProfiles / createTaskSpace / useTaskSpace / closeTaskSpace / listTaskSpaces /
+ *      sendCDPMessage / snapshot / createTab / setAgentTaskState / handOffTaskSpace /
+ *      takeOverTaskSpace / claimTaskSpace / completeTaskSpace / animations / learnings / helpers`,
+ *   · `--proxy-server` is a *launch* flag on the browser process, not a CDP command,
+ *     so it cannot be changed after the profile is already running.
+ *
+ * A proxy therefore has to be bound **outside** the browser: at the OS level
+ * (system proxy / TUN / transparent redirect), or by routing the ego-lite process
+ * through a local forwarder that owns the upstream proxy.
+ *
+ * This layer refuses to pretend otherwise. An account profile either carries a
+ * declared proxy binding (`ready`) or it does not (`missing-proxy`), and the
+ * session plan repeats that state so a caller cannot mistake "no proxy" for
+ * "proxy applied".
+ */
+
+/**
+ * One browser profile exposed by ego-lite.
+ *
+ * Mirrors `ego.listProfiles()`: ids are stable locators, display names are not
+ * guaranteed to be unique.
+ */
+interface EgoProfile {
+    /** Stable profile id — the value to pass as `profileId` when creating a task space. */
+    id: string;
+    /** Human-readable display name. Not unique. */
+    name: string;
+    /** Whether this is the browser's default profile. */
+    isDefault: boolean;
+}
+/**
+ * The slice of the ego-lite global bridge this layer talks to.
+ *
+ * Deliberately narrow and structural: the layer never imports ego-lite (it is an
+ * optional peer dependency, and this package ships zero dependencies). Tests and
+ * callers inject their own implementation.
+ */
+interface EgoLiteBridge {
+    /**
+     * List the browser profiles available for new task spaces.
+     * Mirrors `ego.listProfiles()`.
+     */
+    listProfiles(): Promise<EgoProfile[]>;
+    /**
+     * Create (or reuse) a task space bound to a profile.
+     * Mirrors `taskSpace(name, { profileId })`.
+     *
+     * @returns The task space identifier used to select the space later.
+     */
+    createTaskSpace(name: string, profileId: string): Promise<string>;
+}
+/**
+ * A proxy binding for an account profile.
+ *
+ * ⚠️ This is a *declaration*, not an applied configuration. ego-lite cannot
+ * configure a proxy at the browser layer, so the caller must make this true at
+ * the system layer (OS proxy / TUN / local forwarder) before starting a session.
+ */
+interface EgoProxyBinding {
+    /** Proxy URL, e.g. `http://user:pass@gate.example.com:7000`. */
+    url: string;
+    /** Human-readable description of which egress this binding represents. */
+    description: string;
+    /**
+     * ISO 3166-1 alpha-2 country the proxy egresses from, when known.
+     * Used to keep the passport's geo context aligned with the exit IP.
+     */
+    country?: string;
+}
+/**
+ * Readiness of an account profile for launching a session.
+ *
+ * - `ready`         — a profile is bound AND a proxy is declared.
+ * - `missing-proxy` — a profile is bound, but no proxy is declared.
+ * - `missing-profile`— a proxy is declared, but no ego-lite profile is bound.
+ *
+ * `missing-proxy` exists so that "the browser has no proxy" can never be
+ * silently read as "the proxy is in effect".
+ */
+type EgoProfileReadiness = 'ready' | 'missing-proxy' | 'missing-profile';
+/**
+ * The persisted account profile: one account (seed) mapped to a sticky
+ * passport, an ego-lite profile binding, and a proxy declaration.
+ */
+interface EgoAccountProfile {
+    /** The account seed. Same seed ⇒ same sticky passport, forever. */
+    seed: string;
+    /** Id of the persisted passport record (see `DevicePassport.id`). */
+    passportId: string;
+    /** The ego-lite profile this account is bound to. */
+    profileId: string;
+    /** Declared proxy binding, or `null` when the account has no proxy. */
+    proxy: EgoProxyBinding | null;
+    /** ISO 8601 timestamp of the last write. */
+    updatedAt: string;
+}
+/**
+ * The proxy declaration attached to a session plan.
+ *
+ * `bound: false` means the session will egress directly — the caller must
+ * arrange the proxy outside the browser before launching.
+ */
+interface EgoProxyDeclaration {
+    /** Whether a proxy is declared for this account. */
+    bound: boolean;
+    /** The declared binding, present only when `bound` is true. */
+    binding: EgoProxyBinding | null;
+    /**
+     * How the proxy is actually applied, given ego-lite's capability boundary.
+     * Always `'system-level'` — the browser layer cannot set it.
+     */
+    resolution: 'system-level';
+    /**
+     * Human-readable note telling the operator what to do when `bound` is true,
+     * or why it cannot be applied when `bound` is false.
+     */
+    note: string;
+}
+/**
+ * Everything required to start one account session in ego-lite.
+ *
+ * Extends {@link CdpPassportPlan} so the CDP payload has exactly one definition.
+ * Re-declaring `commands` / `initScripts` / `headers` here would let the two
+ * shapes drift apart, and would silently drop `stealthScript` from the plan.
+ */
+interface EgoSessionPlan extends CdpPassportPlan {
+    /** The account seed this plan belongs to. */
+    seed: string;
+    /** The ego-lite profile the session must run under. */
+    profileId: string;
+    /** Suggested task space name (unique per launch attempt). */
+    taskSpaceName: string;
+    /** The proxy declaration, with its `bound` state spelled out. */
+    proxy: EgoProxyDeclaration;
+    /** Readiness of the underlying account profile. */
+    readiness: EgoProfileReadiness;
+    /** Whether the session may be launched as-is. */
+    launchable: boolean;
+}
+
+/**
+ * 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';
+}
+
+export { LocaleProfile };
+export type { BenchmarkMetrics, BrandVersion, BrowserProfile, CdpCommand, CdpInitScript, CdpPassportPlan, ClientHintsHeaders, ConsistencyCategory, ConsistencyCheck, CpuProfile, DevicePassport, DevicePassportContext, DeviceProfile, EgoAccountProfile, EgoLiteBridge, EgoProfile, EgoProfileReadiness, EgoProxyBinding, EgoProxyDeclaration, EgoSessionPlan, EntropyAnalysis, EvaluationGrade, EvaluationStatus, GpuProfile, HardwareProfile, MemoryProfile, OperatingSystemProfile, PassportEvaluation, PassportGeneratorOptions, ScreenProfile, SupportedArchitecture, SupportedBrowserName, SupportedPlatform, UserAgentClientHints };

package/dist/types/index.mjs

@@ -0,0 +1 @@
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "device-passport",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Digital device passports for scrapers, bots and automation. 100% consistent, stateful browser personas with sticky hardware, correlated Client-Hints, and geo-aligned locales.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -11,6 +11,36 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
       "require": "./dist/index.cjs"
+    },
+    "./geo": {
+      "types": "./dist/geo/index.d.ts",
+      "import": "./dist/geo/index.mjs",
+      "require": "./dist/geo/index.cjs"
+    },
+    "./storage": {
+      "types": "./dist/storage/index.d.ts",
+      "import": "./dist/storage/index.mjs",
+      "require": "./dist/storage/index.cjs"
+    },
+    "./adapters": {
+      "types": "./dist/adapters/index.d.ts",
+      "import": "./dist/adapters/index.mjs",
+      "require": "./dist/adapters/index.cjs"
+    },
+    "./ego": {
+      "types": "./dist/ego/index.d.ts",
+      "import": "./dist/ego/index.mjs",
+      "require": "./dist/ego/index.cjs"
+    },
+    "./evaluator": {
+      "types": "./dist/evaluator/index.d.ts",
+      "import": "./dist/evaluator/index.mjs",
+      "require": "./dist/evaluator/index.cjs"
+    },
+    "./types": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/types/index.mjs",
+      "require": "./dist/types/index.cjs"
     }
   },
   "files": [
@@ -24,7 +54,7 @@
     "build": "unbuild",
     "test": "bun test tests/",
     "lint": "tsc --noEmit",
-    "prepublishOnly": "bun run test && bun run build"
+    "prepublishOnly": "npm run build && node scripts/prepublish-gate.mjs && node scripts/readme-gate.mjs && node scripts/version-sync-gate.mjs"
   },
   "keywords": [
     "user-agent",