device-passport 1.0.0 → 1.2.0

package/dist/shared/device-passport.dVEqzSEb.d.mts

@@ -0,0 +1,469 @@
+import { DevicePassport, BrowserProfile, OperatingSystemProfile, HardwareProfile, UserAgentClientHints, DevicePassportContext, PassportEvaluation, PassportGeneratorOptions, SupportedPlatform, SupportedBrowserName, EgoAccountProfile, EgoLiteBridge, EgoProfile, EgoProfileReadiness, EgoProxyBinding, EgoSessionPlan, EgoProxyDeclaration } from '../types/index.mjs';
+import { P as PlaywrightContextOptions, a as PuppeteerEmulationOptions } from './device-passport.ZBspe4ZW.mjs';
+import { S as StorageAdapter } from './device-passport.DirQmSd4.mjs';
+import { L as LocaleProfile } from './device-passport.C_F1vBE8.mjs';
+
+/**
+ * DevicePassportInstance encapsulates a single concrete, zero-contradiction digital identity persona.
+ *
+ * Provides runtime adapters for:
+ * 1. Lightweight HTTP mode (Fetch, Axios, Undici, Got, cURL) with strict canonical header ordering.
+ * 2. Heavyweight browser automation (Playwright, Puppeteer, ego-lite) with deep fingerprint masking.
+ * 3. Self-evaluating consistency diagnostics based on empirical telemetry models.
+ */
+declare class DevicePassportInstance {
+    readonly profile: DevicePassport;
+    constructor(profile: DevicePassport);
+    /**
+     * Factory method to create an instance from a plain DevicePassport object.
+     */
+    static from(profile: DevicePassport): DevicePassportInstance;
+    get id(): string;
+    get seed(): string;
+    get createdAt(): string;
+    get browser(): BrowserProfile;
+    get os(): OperatingSystemProfile;
+    get hardware(): HardwareProfile;
+    get locale(): LocaleProfile;
+    get headers(): Record<string, string>;
+    get clientHints(): UserAgentClientHints;
+    get context(): DevicePassportContext;
+    get userAgent(): string;
+    get timezone(): string;
+    get playwrightContext(): PlaywrightContextOptions;
+    get puppeteerArgs(): PuppeteerEmulationOptions;
+    get evaluation(): PassportEvaluation | undefined;
+    /**
+     * Returns HTTP headers formatted in strict canonical browser sequence.
+     * Essential for anti-bot evasion against Cloudflare, Akamai, and DataDome.
+     */
+    getHeaders(overrides?: Record<string, string>): Record<string, string>;
+    /**
+     * Returns a higher-order fetch function wrapping standard fetch with this passport's canonical persona.
+     */
+    wrapFetch(customFetch?: typeof fetch): typeof fetch;
+    /**
+     * Alias for wrapFetch.
+     */
+    withPassport(customFetch?: typeof fetch): typeof fetch;
+    /**
+     * Generates a copy-pasteable cURL command with correct browser headers and User-Agent.
+     */
+    toCurl(url: string, options?: {
+        method?: string;
+        data?: any;
+        headers?: Record<string, string>;
+    }): string;
+    /**
+     * Generates Playwright BrowserContext options.
+     * Usage:
+     * ```ts
+     * const context = await browser.newContext(passport.getPlaywrightContext());
+     * ```
+     */
+    getPlaywrightContext(): PlaywrightContextOptions;
+    /**
+     * Returns Puppeteer launch args and page emulation parameters.
+     */
+    getPuppeteerArgs(): PuppeteerEmulationOptions;
+    /**
+     * Generates an in-page stealth script to patch runtime JavaScript APIs
+     * (navigator.webdriver, hardwareConcurrency, deviceMemory, WebGL, Client Hints).
+     */
+    getStealthScript(): string;
+    /**
+     * Injects stealth scripts and extra HTTP headers into a Playwright BrowserContext.
+     */
+    applyToPlaywright(context: any): Promise<void>;
+    /**
+     * Injects stealth scripts and emulation parameters into a Puppeteer Page.
+     */
+    applyToPuppeteer(page: any): Promise<void>;
+    /**
+     * Evaluates cross-layer consistency and Shannon entropy.
+     * Caches the result on `this.profile.evaluation`.
+     */
+    evaluate(forceRecompute?: boolean): PassportEvaluation;
+    /**
+     * Returns the underlying raw DevicePassport data object.
+     */
+    toJSON(): DevicePassport;
+    toString(): string;
+}
+interface CreatePassportInputOptions extends PassportGeneratorOptions {
+    /** Optional file path or storage adapter to persist this passport deterministically */
+    store?: string | StorageAdapter<DevicePassport>;
+}
+/**
+ * Universal polymorphic factory for creating a DevicePassportInstance.
+ *
+ * Supports:
+ * - One-line string seed: `createPassport('alice', { geo: 'US' })`
+ * - Full options object: `createPassport({ seed: 'bot1', store: './passports.json' })`
+ * - Existing raw profile: `createPassport(rawProfile)`
+ * - Zero-config ephemeral persona: `createPassport()`
+ */
+declare function createPassport(seedOrOptionsOrProfile?: string | CreatePassportInputOptions | DevicePassport, extraOptions?: CreatePassportInputOptions): DevicePassportInstance;
+
+interface PassportManagerOptions {
+    /**
+     * Storage backend for persisting passports:
+     * - String path (e.g. './passports.json') -> creates JSONFileStorage automatically.
+     * - StorageAdapter instance -> custom pluggable storage (Memory, File, Redis, DB).
+     * - Omitted or 'memory' -> uses MemoryStorage.
+     */
+    store?: string | StorageAdapter<DevicePassport>;
+    /**
+     * Default geographic country code for newly generated personas (e.g. 'US', 'GB', 'DE', 'JP').
+     * Defaults to 'US'.
+     */
+    defaultGeo?: string;
+    /**
+     * Default operating system preference ('macOS' | 'Windows').
+     */
+    defaultOS?: SupportedPlatform;
+    /**
+     * Default browser preference ('Chrome' | 'Edge').
+     */
+    defaultBrowser?: SupportedBrowserName;
+    /**
+     * Generator function. Defaults to engine's generatePassport.
+     */
+    generator?: (options?: PassportGeneratorOptions) => DevicePassport;
+}
+/**
+ * PassportManager manages fleet-scale digital device identities.
+ *
+ * Guarantees true sticky identity across runs:
+ * Calling `getPassport(seed)` with the same seed (e.g. account ID, proxy IP, username)
+ * will consistently return the exact same device passport across restarts and cron jobs.
+ */
+declare class PassportManager {
+    readonly storage: StorageAdapter<DevicePassport>;
+    readonly defaultGeo: string;
+    readonly defaultOS?: SupportedPlatform;
+    readonly defaultBrowser?: SupportedBrowserName;
+    private readonly generator;
+    constructor(options?: PassportManagerOptions);
+    /**
+     * Retrieves an existing sticky passport by seed or deterministically generates
+     * and persists a new one if it does not already exist.
+     *
+     * @param seed Deterministic seed (user ID, account handle, proxy IP, worker slot)
+     * @param options Generator options to use if persona needs to be created
+     */
+    getPassport(seed: string | number, options?: PassportGeneratorOptions): Promise<DevicePassportInstance>;
+    /**
+     * Synchronous passport retrieval for environments backed by MemoryStorage or JSONFileStorage.
+     */
+    getPassportSync(seed: string | number, options?: PassportGeneratorOptions): DevicePassportInstance;
+    /**
+     * Forces re-generation and overwrite of a passport for the given seed.
+     */
+    renewPassport(seed: string | number, options?: PassportGeneratorOptions): Promise<DevicePassportInstance>;
+    /**
+     * Check if a passport exists in storage for the given seed.
+     */
+    hasPassport(seed: string | number): Promise<boolean>;
+    /**
+     * Delete a passport from storage.
+     */
+    deletePassport(seed: string | number): Promise<boolean>;
+    /**
+     * Import an existing passport into storage.
+     */
+    importPassport(passport: DevicePassport | DevicePassportInstance): Promise<DevicePassportInstance>;
+    /**
+     * List all stored seeds.
+     */
+    listSeeds(): Promise<string[]>;
+    /**
+     * List all stored passports as DevicePassportInstance objects.
+     */
+    listPassports(): Promise<DevicePassportInstance[]>;
+    /**
+     * Clear all stored passports.
+     */
+    clear(): Promise<void>;
+    /**
+     * Return number of stored personas.
+     */
+    count(): Promise<number>;
+}
+
+/**
+ * Account profile manager for ego-lite.
+ *
+ * Maps one account (seed) onto three things that must travel together:
+ *   1. a **sticky passport** — same seed ⇒ same persona, forever (via `PassportManager`),
+ *   2. an **ego-lite profile binding** (`profileId`) — the browser profile whose
+ *      cookies and login state persist across task spaces,
+ *   3. a **proxy declaration** — recorded, but never applied at the browser layer.
+ *
+ * The proxy is a declared *gap*, not a feature: ego-lite has no browser-level proxy
+ * API, so the profile either has a proxy declared (and the operator must bind it at
+ * the system level) or it does not, and the manager reports `missing-proxy` so
+ * nobody mistakes "no proxy" for "proxy applied".
+ */
+
+/**
+ * Options for {@link AccountProfileManager}.
+ */
+interface AccountProfileManagerOptions {
+    /**
+     * Storage backend for the account profile records (seed → profile binding).
+     * - String path → creates a `JSONFileStorage` automatically (atomic writes).
+     * - StorageAdapter instance → custom backend.
+     * - Omitted → `MemoryStorage`.
+     */
+    store?: string | StorageAdapter<EgoAccountProfile>;
+    /**
+     * Storage backend for the sticky passports (seed → persona).
+     *
+     * 🔴 Why this is separate from {@link store}:
+     *   Account records and personas are two different kinds of state with two
+     *   different lifetimes. Persisting the records but not the personas means a
+     *   restart regenerates the persona from the default geo — the persona silently
+     *   changes while its `id` stays the same, so no caller can tell it drifted.
+     *   Persisting both makes the identity survive a restart for real.
+     *
+     * - String path → creates a `JSONFileStorage` automatically (atomic writes).
+     * - StorageAdapter instance → custom backend.
+     * - Omitted → falls back to `passportOptions.store`, then `MemoryStorage`.
+     */
+    passportStore?: string | StorageAdapter<DevicePassport>;
+    /**
+     * The passport manager that owns the sticky identities.
+     * When omitted, an internal one is created from {@link passportOptions}.
+     */
+    passportManager?: PassportManager;
+    /**
+     * Options for the internal passport manager. Ignored when
+     * {@link passportManager} is supplied.
+     */
+    passportOptions?: PassportManagerOptions;
+    /**
+     * The ego-lite bridge used to list profiles and open task spaces.
+     * When omitted, no profile listing is possible and binding is rejected.
+     */
+    bridge?: EgoLiteBridge;
+}
+/**
+ * Options for binding an account to an ego-lite profile.
+ */
+interface BindProfileOptions {
+    /** The ego-lite profile id to bind. Must exist in the ego-lite profile list. */
+    profileId: string;
+    /**
+     * The proxy declaration for this account. Omit to leave the account unbound.
+     */
+    proxy?: EgoProxyBinding | null;
+}
+/**
+ * Options for creating a session plan.
+ */
+interface CreateSessionPlanOptions {
+    /** Task space name. Defaults to a name derived from the seed. */
+    taskSpaceName?: string;
+    /** Optional CDP session id to attach to every command. */
+    sessionId?: string;
+}
+/**
+ * Manages ego-lite account profiles: sticky passport + profile binding + proxy declaration.
+ */
+declare class AccountProfileManager {
+    /** Persistent store of account profile records. */
+    readonly storage: StorageAdapter<EgoAccountProfile>;
+    /** The passport manager holding the sticky identities. */
+    readonly passportManager: PassportManager;
+    /** The ego-lite bridge, when one was injected. */
+    readonly bridge?: EgoLiteBridge;
+    constructor(options?: AccountProfileManagerOptions);
+    /**
+     * Lists the ego-lite profiles available for binding.
+     *
+     * @throws When no bridge was injected — ego-lite has no "create profile" API,
+     * so a profile must already exist and be listed before it can be bound.
+     */
+    listEgoProfiles(): Promise<EgoProfile[]>;
+    /**
+     * Returns the stored account profile record for a seed.
+     */
+    getProfile(seed: string | number): Promise<EgoAccountProfile | null>;
+    /**
+     * Returns the readiness of an account profile.
+     *
+     * `ready` requires both a bound ego-lite profile and a declared proxy.
+     */
+    getReadiness(seed: string | number): Promise<EgoProfileReadiness>;
+    /**
+     * Binds an account to an existing ego-lite profile, and optionally declares its proxy.
+     *
+     * The proxy is only *recorded* here. ego-lite cannot apply it at the browser layer,
+     * so the operator must bind it at the system level before launching a session.
+     *
+     * @param seed The account seed. Doubles as the sticky passport seed.
+     * @param options The profile id to bind and the optional proxy declaration.
+     * @param passportOptions Generator options used when the passport is first created.
+     */
+    bindProfile(seed: string | number, options: BindProfileOptions, passportOptions?: PassportGeneratorOptions): Promise<EgoAccountProfile>;
+    /**
+     * Declares (or clears) the proxy binding of an account.
+     *
+     * Passing `null` removes the declaration; the account then reports `missing-proxy`.
+     */
+    setProxy(seed: string | number, proxy: EgoProxyBinding | null): Promise<EgoAccountProfile>;
+    /**
+     * Returns the sticky passport instance for an account.
+     */
+    getPassport(seed: string | number, options?: PassportGeneratorOptions): Promise<DevicePassportInstance>;
+    /**
+     * Builds the complete launch plan for one account session.
+     *
+     * The plan carries the CDP command sequence, init scripts, headers, the ego-lite
+     * profile id, and an explicit proxy declaration whose `bound` flag reflects whether
+     * a proxy is actually declared for the account.
+     *
+     * @throws When the account has no bound profile.
+     */
+    createSessionPlan(seed: string | number, options?: CreateSessionPlanOptions): Promise<EgoSessionPlan>;
+    /**
+     * Opens an ego-lite task space bound to the account's profile.
+     *
+     * The task space inherits the profile's cookies and login state; a different
+     * profile is fully isolated from it.
+     *
+     * @returns The task space identifier.
+     * @throws When the account has no bound profile or no bridge was injected.
+     */
+    openTaskSpace(seed: string | number, taskSpaceName?: string): Promise<string>;
+    /**
+     * Lists every stored account seed.
+     */
+    listSeeds(): Promise<string[]>;
+    /**
+     * Removes an account profile record.
+     */
+    removeProfile(seed: string | number): Promise<boolean>;
+}
+
+/**
+ * Session plan builder for ego-lite.
+ *
+ * Turns one account profile into everything needed to launch a session:
+ * the ordered CDP command sequence, the init scripts, the canonical headers,
+ * the ego-lite profile id, and an explicit proxy declaration.
+ *
+ * The proxy declaration is the important part: ego-lite cannot set a proxy at the
+ * browser layer, so the plan states plainly whether a proxy is declared and that
+ * it must be arranged outside the browser.
+ */
+
+/**
+ * How the proxy is resolved for every ego-lite session.
+ *
+ * ego-lite exposes no proxy API (no `Browser.setProxySettings` in CDP, no proxy
+ * setter among its native bindings), and `--proxy-server` is a browser *launch*
+ * flag rather than a CDP command. A proxy must therefore be bound outside the
+ * browser: OS-level proxy, TUN/transparent redirect, or a local forwarder in
+ * front of the ego-lite process.
+ */
+declare const PROXY_RESOLUTION_NOTE: string;
+/**
+ * The note used when an account has no proxy declared at all.
+ */
+declare const PROXY_MISSING_NOTE: string;
+/**
+ * Computes the readiness of an account profile.
+ *
+ * `ready` requires *both* a bound ego-lite profile and a declared proxy.
+ */
+declare function getProfileReadiness(profile: EgoAccountProfile): EgoProfileReadiness;
+/**
+ * Builds the proxy declaration for an account profile.
+ */
+declare function buildProxyDeclaration(profile: EgoAccountProfile): EgoProxyDeclaration;
+/**
+ * Options for {@link buildEgoSessionPlan}.
+ */
+interface BuildEgoSessionPlanOptions {
+    /** Optional task space name. Defaults to a name derived from the seed. */
+    taskSpaceName?: string;
+    /** Optional CDP session id to attach to every command. */
+    sessionId?: string;
+}
+/**
+ * Builds the complete launch plan for one account session.
+ *
+ * Command order is inherited from {@link getCdpPlan} and is load-bearing:
+ * `Page.enable` comes first (without it the init script is accepted but never
+ * runs), the user-agent override precedes navigation, and the init script is
+ * installed last so it is in place before the first document is created.
+ *
+ * The profile id has exactly one source: the persisted account record. Accepting
+ * a second, caller-supplied profile id would let the plan's profile id and its
+ * readiness disagree, and a caller could end up launching a session under a
+ * profile that was never validated.
+ *
+ * @param passport The sticky passport for the account.
+ * @param profile The persisted account profile (supplies the profile id and the
+ *   proxy declaration).
+ * @param options Task space name and session id.
+ */
+declare function buildEgoSessionPlan(passport: DevicePassport, profile: EgoAccountProfile, options?: BuildEgoSessionPlanOptions): EgoSessionPlan;
+/**
+ * Builds the default task space name for a seed.
+ *
+ * Task space names must be unique per launch, so callers normally append a
+ * timestamp or counter. The default is stable enough to be recognizable.
+ */
+declare function defaultTaskSpaceName(seed: string): string;
+
+/**
+ * ego-lite bridge adapters.
+ *
+ * 🔴 Why this exists:
+ *   ego-lite is the author's own agent browser. It runs on the local machine and is
+ *   driven through the `ego-browser` CLI's nodejs heredoc mode. This package must not
+ *   depend on ego-lite (it ships zero dependencies), so the ego-lite specific API is
+ *   described structurally and injected from the outside.
+ *
+ * The capability boundary this module encodes — verified against ego-lite's own
+ * source, not guessed:
+ *   · `listProfiles` exists and lists browser profiles.
+ *   · `createTaskSpace` / `useTaskSpace` accept a `profileId`.
+ *   · There is **no** proxy API: no `Browser.setProxySettings` in CDP, and no proxy
+ *     setter among ego-lite's native bindings.
+ *   · `page.cdp(method, params)` can send arbitrary CDP commands.
+ */
+
+/**
+ * The minimal shape of the ego-lite global object this bridge uses.
+ *
+ * Matches ego-lite's native binding names exactly, so `globalThis.ego` satisfies it
+ * structurally without importing ego-lite.
+ */
+interface EgoNativeBridge {
+    /** Lists the browser profiles available for new task spaces. */
+    listProfiles?(): Promise<{
+        profiles?: EgoProfile[];
+    } | EgoProfile[]>;
+    /** Creates a task space, optionally bound to a browser profile. */
+    createTaskSpace?(name: string, profileId?: string): Promise<unknown>;
+}
+/**
+ * Reads the ego-lite native bridge from the global scope.
+ *
+ * @returns The native bridge, or `null` when ego-lite is not present.
+ */
+declare function getEgoNativeBridge(scope?: unknown): EgoNativeBridge | null;
+/**
+ * Builds an {@link EgoLiteBridge} on top of the ego-lite native bindings.
+ *
+ * @param native The native bridge. Defaults to `globalThis.ego`.
+ * @throws When ego-lite is unavailable or lacks a required binding.
+ */
+declare function createEgoBridge(native?: EgoNativeBridge | null): EgoLiteBridge;
+
+export { AccountProfileManager as A, DevicePassportInstance as D, PROXY_MISSING_NOTE as P, PROXY_RESOLUTION_NOTE as d, PassportManager as e, buildEgoSessionPlan as g, buildProxyDeclaration as h, createEgoBridge as i, createPassport as j, defaultTaskSpaceName as k, getEgoNativeBridge as l, getProfileReadiness as m };
+export type { BindProfileOptions as B, CreatePassportInputOptions as C, EgoNativeBridge as E, AccountProfileManagerOptions as a, BuildEgoSessionPlanOptions as b, CreateSessionPlanOptions as c, PassportManagerOptions as f };