device-passport 1.1.0 → 1.2.0

package/dist/storage/index.d.cts

@@ -1,35 +1,4 @@
-/**
- * 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 { S as StorageAdapter } from '../shared/device-passport.DirQmSd4.cjs';
 
 interface MemoryStorageOptions {
     /**
@@ -124,5 +93,5 @@ declare class JSONFileStorage<T = any> implements StorageAdapter<T> {
     get size(): number;
 }
 
-export { JSONFileStorage, MemoryStorage };
-export type { JSONFileStorageOptions, MemoryStorageOptions, StorageAdapter };
+export { JSONFileStorage, MemoryStorage, StorageAdapter };
+export type { JSONFileStorageOptions, MemoryStorageOptions };

package/dist/storage/index.d.mts

@@ -1,35 +1,4 @@
-/**
- * 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 { S as StorageAdapter } from '../shared/device-passport.DirQmSd4.mjs';
 
 interface MemoryStorageOptions {
     /**
@@ -124,5 +93,5 @@ declare class JSONFileStorage<T = any> implements StorageAdapter<T> {
     get size(): number;
 }
 
-export { JSONFileStorage, MemoryStorage };
-export type { JSONFileStorageOptions, MemoryStorageOptions, StorageAdapter };
+export { JSONFileStorage, MemoryStorage, StorageAdapter };
+export type { JSONFileStorageOptions, MemoryStorageOptions };

package/dist/storage/index.d.ts

@@ -1,35 +1,4 @@
-/**
- * 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 { S as StorageAdapter } from '../shared/device-passport.DirQmSd4.js';
 
 interface MemoryStorageOptions {
     /**
@@ -124,5 +93,5 @@ declare class JSONFileStorage<T = any> implements StorageAdapter<T> {
     get size(): number;
 }
 
-export { JSONFileStorage, MemoryStorage };
-export type { JSONFileStorageOptions, MemoryStorageOptions, StorageAdapter };
+export { JSONFileStorage, MemoryStorage, StorageAdapter };
+export type { JSONFileStorageOptions, MemoryStorageOptions };

package/dist/types/index.d.cts

@@ -46,6 +46,188 @@ interface BenchmarkMetrics {
     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.
@@ -212,4 +394,4 @@ interface PassportGeneratorOptions {
 }
 
 export { LocaleProfile };
-export type { BenchmarkMetrics, BrandVersion, BrowserProfile, ClientHintsHeaders, ConsistencyCategory, ConsistencyCheck, CpuProfile, DevicePassport, DevicePassportContext, DeviceProfile, EntropyAnalysis, EvaluationGrade, EvaluationStatus, GpuProfile, HardwareProfile, MemoryProfile, OperatingSystemProfile, PassportEvaluation, PassportGeneratorOptions, ScreenProfile, SupportedArchitecture, SupportedBrowserName, SupportedPlatform, UserAgentClientHints };
+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.d.mts

@@ -46,6 +46,188 @@ interface BenchmarkMetrics {
     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.
@@ -212,4 +394,4 @@ interface PassportGeneratorOptions {
 }
 
 export { LocaleProfile };
-export type { BenchmarkMetrics, BrandVersion, BrowserProfile, ClientHintsHeaders, ConsistencyCategory, ConsistencyCheck, CpuProfile, DevicePassport, DevicePassportContext, DeviceProfile, EntropyAnalysis, EvaluationGrade, EvaluationStatus, GpuProfile, HardwareProfile, MemoryProfile, OperatingSystemProfile, PassportEvaluation, PassportGeneratorOptions, ScreenProfile, SupportedArchitecture, SupportedBrowserName, SupportedPlatform, UserAgentClientHints };
+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 };