@npm-pipl/device-intelligence 1.1.1

package/README.md

@@ -0,0 +1,8 @@
+# device-intelligence-service-internal
+
+
+## Deployment
+
+This SDK is automatically deployed via GitHub Actions:
+- **CI**: Merges to `main` automatically deploy to dev bucket and `latest` folder
+- **CD**: Manual workflow deploys to production bucket

package/dist/agent.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Device Intelligence Agent
+ *
+ * Manages the lifecycle of attribute collection including:
+ * - Collection timing (immediate, onLoad, manual)
+ * - State tracking
+ * - Attribute caching with TTL
+ * - Elephant device caching
+ * - Promise-based waiting for collection completion
+ */
+import type { DeviceIntelligenceOptions, UserData, IDeviceIntelligence, DebugInfo } from "./types";
+/**
+ * DeviceIntelligenceAgent - manages attribute collection lifecycle
+ */
+export declare class DeviceIntelligenceAgent implements IDeviceIntelligence {
+    private options;
+    private log;
+    private attributeEngine;
+    private state;
+    private cachedCollection;
+    private cachedElephantDevice;
+    private collectionAndSendPromise;
+    private localElephantDevice;
+    private isInitialized;
+    private lastSendSucceeded;
+    private pendingUserData;
+    /**
+     * Initialize the agent with options and start collection based on timing configuration.
+     * Returns a Promise that resolves with debug info (in debug mode) or null when collection is complete.
+     * In debug mode, the Promise rejects on errors; callers can await to catch them.
+     */
+    init(options?: DeviceIntelligenceOptions): Promise<DebugInfo | null>;
+    /**
+     * Add user data and send collected attributes to the server.
+     * If collection is in progress, merges user data and waits for it.
+     * Returns debug info in debug mode, null otherwise.
+     */
+    addUserData(userData?: UserData): Promise<DebugInfo | null>;
+    /**
+     * Returns the elephant device issued by the server (public identifier).
+     * This is not the internal local identifier used in payloads.
+     */
+    getElephantDevice(): string | null;
+    /**
+     * Get debug information including collected attributes.
+     * Only available when debug mode is enabled.
+     */
+    private getDebugInfo;
+    /**
+     * Collect attributes and send to server with optional user data.
+     * This is the main unified function used by both init() and addUserData().
+     * Returns debug info in debug mode, null otherwise.
+     */
+    collectAndSend(userData?: UserData): Promise<DebugInfo | null>;
+    /**
+     * Check if the cached collection is still valid
+     */
+    private isCacheValid;
+    /**
+     * Collect device attributes and cache them.
+     */
+    private collectAttributes;
+    /**
+     * Build payload and send to server
+     * @param userData - Optional user data to include
+     */
+    private buildAndSendPayload;
+    /**
+     * Convert attribute results to DeviceAttributes format
+     */
+    private toAttributes;
+    /**
+     * Send payload to server (with encryption when supported)
+     * Returns true if send was successful, false otherwise.
+     */
+    private sendToServer;
+}

package/dist/attributes/collectors/accessibility.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Accessibility Collectors
+ *
+ * User preferences: Contrast, Motion, Dark Mode.
+ * Explicitly groups user-defined settings vs. hardware capabilities.
+ *
+ */
+import type { AttributeCollector } from "../types";
+export declare const accessibilityCollectors: AttributeCollector[];

package/dist/attributes/collectors/audio.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Audio Collectors
+ *
+ * Audio hardware and processing (AudioContext).
+ * High-entropy fingerprints from audio processing differences.
+ *
+ */
+import type { AttributeCollector } from "../types";
+export declare const audioCollectors: AttributeCollector[];

package/dist/attributes/collectors/browser.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Browser Collectors
+ *
+ * Software features: Plugins, MimeTypes, PDF Viewer, Codecs.
+ * Captures the browser software configuration rather than the device.
+ *
+ */
+import type { AttributeCollector } from "../types";
+export declare const browserCollectors: AttributeCollector[];

package/dist/attributes/collectors/fonts.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Fonts Collectors
+ *
+ * Font enumeration and metrics.
+ * Font detection is one of the most powerful fingerprinting techniques.
+ *
+ */
+import type { AttributeCollector } from "../types";
+export declare const fontsCollectors: AttributeCollector[];

package/dist/attributes/collectors/graphics.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Graphics Collectors
+ *
+ * All rendering capabilities: Canvas, WebGL, GPU, SVG.
+ * These provide the highest uniqueness for device fingerprinting.
+ *
+ */
+import type { AttributeCollector } from "../types";
+export declare const graphicsCollectors: AttributeCollector[];

package/dist/attributes/collectors/hardware.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Hardware Collectors
+ *
+ * Physical device specs: CPU cores, Memory, Battery, Touch, Sensors.
+ * Distinct from "OS" or "Platform"; describes the silicon.
+ *
+ */
+import type { AttributeCollector } from "../types";
+export declare const hardwareCollectors: AttributeCollector[];

package/dist/attributes/collectors/index.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Attribute Collectors Index
+ *
+ * This file re-exports all collector arrays from the category-specific files.
+ * Collectors are organized into 12 categories based on the new standard:
+ *
+ * 1. Graphics (20 attrs): Canvas, WebGL, GPU, SVG rendering
+ * 2. Audio (4 attrs): AudioContext and audio hardware
+ * 3. Screen (13 attrs): Display properties (resolution, color depth, HDR)
+ * 4. Hardware (12 attrs): Physical device specs (CPU, memory, battery, sensors)
+ * 5. Platform (18 attrs): OS and navigator identity (UA, locale, timezone)
+ * 6. Runtime (10 attrs): JS engine quirks (math, workers, stack limits)
+ * 7. Fonts (9 attrs): Font enumeration and metrics
+ * 8. Browser (26 attrs): Software features (plugins, codecs, permissions)
+ * 9. Network (2 attrs): Connectivity (WebRTC, connection type)
+ * 10. Storage (3 attrs): Persistence capabilities (cookies, IndexedDB)
+ * 11. Accessibility (9 attrs): User preferences (contrast, motion, dark mode)
+ * 12. Risk (5 attrs): Bot detection, debugger, tampering
+ *
+ * Total: 131+ attributes
+ *
+ * Usage:
+ * ```typescript
+ * import { getAllCollectors } from './collectors';
+ *
+ * const collectors = getAllCollectors();
+ * // Or import specific categories:
+ * import { graphicsCollectors } from './collectors/graphics';
+ * ```
+ */
+import type { AttributeCollector } from "../types";
+export { graphicsCollectors } from "./graphics";
+export { audioCollectors } from "./audio";
+export { screenCollectors } from "./screen";
+export { hardwareCollectors } from "./hardware";
+export { platformCollectors } from "./platform";
+export { runtimeCollectors } from "./runtime";
+export { fontsCollectors } from "./fonts";
+export { browserCollectors } from "./browser";
+export { networkCollectors } from "./network";
+export { storageCollectors } from "./storage";
+export { accessibilityCollectors } from "./accessibility";
+export { riskCollectors } from "./risk";
+/**
+ * Map of category names to their collector arrays.
+ */
+export declare const collectorsByCategory: Record<string, AttributeCollector[]>;
+/**
+ * Returns all collectors combined in optimal collection order:
+ * - Synchronous high-entropy collectors first (graphics, fonts)
+ * - Platform and hardware next
+ * - Browser features
+ * - Async operations last (audio, network, storage persistence)
+ *
+ * @returns Array of all attribute collectors
+ */
+export declare function getAllCollectors(): AttributeCollector[];
+/**
+ * Returns collectors for a specific category.
+ *
+ * @param category - One of: graphics, audio, screen, hardware, platform, runtime, fonts, browser, network, storage, accessibility, risk
+ * @returns Array of collectors for that category
+ */
+export declare function getCollectorsByCategory(category: string): AttributeCollector[];
+/**
+ * Returns statistics about collectors.
+ *
+ * @returns Object with counts per category and total
+ */
+export declare function getCollectorStats(): Record<string, number>;
+/**
+ * List of all category names.
+ */
+export declare const categoryNames: readonly ["graphics", "audio", "screen", "hardware", "platform", "runtime", "fonts", "browser", "network", "storage", "accessibility", "risk"];
+export type CategoryName = (typeof categoryNames)[number];

package/dist/attributes/collectors/network.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Network Collectors
+ *
+ * Connectivity: WebRTC IPs, Connection Type.
+ * Aligns with Network Information API and WebRTC leakage.
+ *
+ */
+import type { AttributeCollector } from "../types";
+export declare const networkCollectors: AttributeCollector[];

package/dist/attributes/collectors/platform.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Platform Collectors
+ *
+ * The OS and Navigator identity: UA, Platform, Architecture, Locale.
+ * "Platform" is the standard term for OS/UA-CH.
+ *
+ */
+import type { AttributeCollector } from "../types";
+export declare const platformCollectors: AttributeCollector[];

package/dist/attributes/collectors/risk.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Risk Collectors
+ *
+ * Heuristics: Bot detection, Debugger, Tampering.
+ * Clearly labels signals that are inferred (like "is_bot") rather than read.
+ *
+ */
+import type { AttributeCollector } from "../types";
+export declare const riskCollectors: AttributeCollector[];

package/dist/attributes/collectors/runtime.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Runtime Collectors
+ *
+ * JS Engine quirks: Math primitives, Worker diffs, Stack limits.
+ * Groups floating-point math and JS execution limits.
+ *
+ */
+import type { AttributeCollector } from "../types";
+export declare const runtimeCollectors: AttributeCollector[];

package/dist/attributes/collectors/screen.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Screen Collectors
+ *
+ * Physical display properties: Resolution, Color Depth, HDR.
+ * Matches the standard DOM window.screen API interface.
+ *
+ */
+import type { AttributeCollector } from "../types";
+export declare const screenCollectors: AttributeCollector[];

package/dist/attributes/collectors/storage.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Storage Collectors
+ *
+ * Persistence capabilities: Cookies, IndexedDB, LocalStorage.
+ * Matches the Storage Manager API family.
+ *
+ */
+import type { AttributeCollector } from "../types";
+export declare const storageCollectors: AttributeCollector[];

package/dist/attributes/default_collectors.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Default Collectors
+ *
+ * This module provides the default set of attribute collectors shipped with the SDK.
+ *
+ * The collectors are organized into 12 categories:
+ *
+ * 1. Graphics - Canvas, WebGL, GPU, SVG rendering (highest entropy)
+ * 2. Audio - AudioContext and audio hardware
+ * 3. Screen - Display properties (resolution, color depth, HDR)
+ * 4. Hardware - Physical device specs (CPU, memory, battery, sensors)
+ * 5. Platform - OS and navigator identity (UA, locale, timezone)
+ * 6. Runtime - JS engine quirks (math, workers, stack limits)
+ * 7. Fonts - Font enumeration and metrics (high entropy)
+ * 8. Browser - Software features (plugins, codecs, permissions)
+ * 9. Network - Connectivity (WebRTC, connection type)
+ * 10. Storage - Persistence capabilities (cookies, IndexedDB)
+ * 11. Accessibility - User preferences (contrast, motion, dark mode)
+ * 12. Risk - Bot detection, debugger, tampering
+ *
+ * Total: 131+ unique attributes
+ *
+ */
+import type { AttributeCollector } from "./types";
+import { getCollectorsByCategory, getCollectorStats, categoryNames, type CategoryName } from "./collectors";
+/**
+ * Default collectors shipped in the SDK.
+ *
+ * This returns all 131+ collectors organized by category and optimized
+ * for collection order (high-entropy synchronous signals first,
+ * async operations last).
+ */
+export declare function getDefaultCollectors(): AttributeCollector[];
+/**
+ * Get a minimal set of fast collectors (no async operations).
+ *
+ * Useful for scenarios where speed is critical and async operations
+ * (audio fingerprint, WebRTC, permissions) are not needed.
+ *
+ * Excludes:
+ * - Audio fingerprint (async, ~50-100ms)
+ * - WebRTC IP handling (async, network dependent)
+ * - Permissions state (async)
+ * - Speech synthesis (async)
+ * - User agent data high entropy (async)
+ * - Battery status (async)
+ * - CPU architecture (async via userAgentData)
+ * - Worker differences (async)
+ * - Storage persistence (async)
+ * - Media devices (async)
+ * - Keyboard layout map (async)
+ * - Subtle crypto support (async)
+ * - DRM support (async)
+ * - Incognito mode (async)
+ */
+export declare function getFastCollectors(): AttributeCollector[];
+/**
+ * Get critical-only collectors (highest entropy signals).
+ *
+ * Useful for lightweight fingerprinting where only the most
+ * distinguishing signals are needed.
+ *
+ * Includes:
+ * - Canvas fingerprint
+ * - WebGL fingerprint
+ * - Audio fingerprint
+ * - GPU vendor/renderer
+ * - Screen resolution
+ * - Installed fonts
+ * - User agent
+ * - Platform
+ * - Timezone
+ * - Math fingerprint
+ * - Automation detection
+ * - Hardware concurrency
+ * - Device memory
+ */
+export declare function getCriticalCollectors(): AttributeCollector[];
+/**
+ * Get collectors for a specific category.
+ *
+ * @param category - One of: graphics, audio, screen, hardware, platform, runtime, fonts, browser, network, storage, accessibility, risk
+ * @returns Array of collectors for that category
+ */
+export { getCollectorsByCategory };
+/**
+ * Get collector statistics by category.
+ *
+ * @returns Object with counts per category and total
+ */
+export { getCollectorStats };
+/**
+ * List of all available category names.
+ */
+export { categoryNames };
+/**
+ * Type for category names.
+ */
+export type { CategoryName };

package/dist/attributes/engine.d.ts

@@ -0,0 +1,26 @@
+import type { AttributeCollector, AttributeResult } from "./types";
+type EngineOptions = {
+    collectors: AttributeCollector[];
+    debug: boolean;
+    log: (...args: unknown[]) => void;
+    /** Optional limit for concurrent collectors (useful for heavy attributes) */
+    concurrency?: number;
+};
+/**
+ * AttributeEngine
+ *
+ * Executes a list of attribute collectors with per-collector error isolation,
+ * caching, timeouts, and optional concurrency limiting.
+ */
+export declare class AttributeEngine {
+    private readonly collectors;
+    private readonly ctx;
+    private readonly concurrency;
+    private readonly collectorKeys;
+    constructor(opts: EngineOptions);
+    /**
+     * Collect all attributes and return results (including per-attribute errors).
+     */
+    collectAll(parentSignal?: AbortSignal): Promise<AttributeResult[]>;
+}
+export {};

package/dist/attributes/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Attribute collection (internal) types.
+ *
+ * We use the term "attributes" (not signals) across the SDK.
+ */
+export type AttributeStatus = "ok" | "error" | "skipped";
+export type AttributeError = {
+    name: string;
+    message: string;
+    retryable?: boolean;
+};
+export type AttributeResult<T = unknown> = {
+    /** Attribute classification (e.g. "graphics", "audio", "screen", "hardware", "platform", "runtime", "fonts", "browser", "network", "storage", "accessibility", "risk") */
+    category: string;
+    key: string;
+    version: number;
+    status: AttributeStatus;
+    value?: T;
+    error?: AttributeError;
+    durationMs: number;
+};
+export type AttributeContext = {
+    debug: boolean;
+    log: (...args: unknown[]) => void;
+    now: () => number;
+    cache: Map<string, {
+        expiresAt: number;
+        value: unknown;
+    }>;
+};
+export interface AttributeCollector<T = unknown> {
+    /**
+     * Attribute classification. One of:
+     * - graphics: Canvas, WebGL, GPU, SVG rendering
+     * - audio: AudioContext and audio hardware
+     * - screen: Display properties (resolution, color depth, HDR)
+     * - hardware: Physical device specs (CPU, memory, battery, touch, sensors)
+     * - platform: OS and navigator identity (UA, locale, timezone)
+     * - runtime: JS engine quirks (math, workers, stack limits)
+     * - fonts: Font enumeration and metrics
+     * - browser: Software features (plugins, codecs, permissions)
+     * - network: Connectivity (WebRTC, connection type)
+     * - storage: Persistence (cookies, IndexedDB, localStorage)
+     * - accessibility: User preferences (contrast, motion, dark mode)
+     * - risk: Heuristics (bot detection, debugger, tampering)
+     *
+     * Optional: defaults to "browser".
+     */
+    category?: string;
+    /** Key (must be unique across collectors if you want a flat attributes map) */
+    key: string;
+    /** Bump when logic changes materially */
+    version: number;
+    /** If false, engine will mark as skipped (no error) */
+    isSupported?: (ctx: AttributeContext) => boolean;
+    /** Per-collector timeout cap (ms) */
+    timeoutMs?: number;
+    /** Cache within a page/session for this long (ms) */
+    cacheTtlMs?: number;
+    collect: (ctx: AttributeContext, signal: AbortSignal) => Promise<T> | T;
+}

package/dist/constants.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Device Intelligence SDK Constants
+ */
+import type { ResolvedOptions } from "./types";
+/**
+ * Schema version for payload format
+ */
+export declare const SCHEMA_VERSION = 1;
+/**
+ * SDK type identifier
+ */
+export declare const SDK_TYPE = "web";
+/**
+ * RSA Public Key for payload encryption (PEM format)
+ * Private key is stored on server only
+ */
+export declare const RSA_PUBLIC_KEY_PEM = "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA1DV8em/rKKXLkNE+5uKK\nHRb8nt46DaQrHrzK1GAi2ZcPQQHPT/Iiy/TCI3HCGGXeSl8/ZFHlT9Xuc+g4Wuce\njE5mNAHwJrbUqZgJKSfkK0KwbTz84U0Bic3HWpjW7E2I+cEbdjnGuQfI8ZNqw19g\ns7Zo6xVYArdd57nbInF7dh/kRVnYxmbqtpt3SpyqtaBPouLDsSTkjHefXKBA0uNM\nU7ix5OlOHFsUGTjsbWoQbiMRDrcozp1KtVJN7n0d095gJW+bsBSBMd3/LMIbVPox\nrfokGe0h+6z0RLxSSu3178r8Cug01xz9D4pXWpugTJvJNN4boMeOV5rItLdqyNq0\nZwIDAQAB\n-----END PUBLIC KEY-----";
+/**
+ * Local storage keys
+ */
+export declare const STORAGE_KEYS: {
+    /** localStorage key for persistent local client id (matches CollectPayload.local_elephant_device) */
+    readonly LOCAL_ELEPHANT_DEVICE: "local_elephant_device";
+    /** localStorage key for server-issued elephant device */
+    readonly ELEPHANT_DEVICE: "elephant_device";
+    readonly SENT_PAYLOADS: "sent_payloads";
+};
+/**
+ * Default attribute cache TTL (5 minutes)
+ */
+export declare const DEFAULT_ATTRIBUTE_CACHE_TTL: number;
+/**
+ * Default minimum send interval (5 hours)
+ * Prevents sending identical payloads more often than this
+ */
+export declare const DEFAULT_MIN_SEND_INTERVAL: number;
+/**
+ * Default configuration options
+ */
+export declare const DEFAULT_OPTIONS: ResolvedOptions;