@ianmenethil/zp-devicefp 0.1.1 → 0.2.0

package/docs/architecture.md

@@ -1,40 +1,171 @@
-# Architecture
-
-## High-level flow
-
-1. Resolve the active signal set from `CollectOptions`.
-2. Run each collector with per-signal timing and timeout handling.
-3. Canonicalize each successful value into stable JSON.
-4. Hash each component with SHA-256.
-5. Derive a composite thumbprint from the ordered component hashes.
-6. Generate an anti-spoof report from cross-signal consistency checks.
-7. Compute a local confidence score from signal quality and anomaly penalties.
-
-## Module map
-
-- `src/client.ts`: public client factory and orchestration
-- `src/signals/*.ts`: one module per signal collector
-- `src/core/canonicalize.ts`: deterministic serialization
-- `src/core/hash.ts`: zero-dependency SHA-256 implementation
-- `src/core/antiSpoof.ts`: anomaly and automation heuristics
-- `src/core/confidence.ts`: local signal-quality scoring
-- `src/core/upload.ts`: optional backend-neutral upload helper
-- `src/runtime/browser.ts`: runtime feature access
-
-## Signal tiers
-
-The package splits collectors into:
-
-- Core: safe defaults that avoid permission prompts and still provide broad browser/device context.
-- Extended: slower or more privacy-sensitive capability probes such as permissions, media-device counts, and WebRTC codec signatures.
-
-## Anti-spoof strategy
-
-The library does not use “secret” client tricks. It scores coherence:
-
-- user-agent vs platform contradictions
-- headless or webdriver hints
-- mobile user-agent with implausibly desktop geometry
-- obviously implausible hardware values
-
-This report is meant to enrich downstream server-side risk logic, not replace it.
+# Architecture
+
+## Module structure
+
+```mermaid
+graph TD
+    subgraph "Public API"
+        index["src/index.ts<br/>Barrel: createFingerprintClient,<br/>LIBRARY_VERSION, SCHEMA_VERSION"]
+        cdn["src/cdn.ts<br/>IIFE entry: attaches<br/>window.DeviceFP"]
+    end
+
+    subgraph "Client Orchestration"
+        client["src/client.ts<br/>Factory + collect / collectSync / on"]
+    end
+
+    subgraph "Core Modules"
+        options["core/options.ts<br/>Default resolution,<br/>signal set filtering"]
+        canonicalize["core/canonicalize.ts<br/>Deterministic JSON<br/>for hashing"]
+        hash["core/hash.ts<br/>Zero-dependency SHA-256"]
+        antiSpoof["core/antiSpoof.ts<br/>Cross-signal coherence<br/>6 anomaly + 2 automation checks"]
+        confidence["core/confidence.ts<br/>Weighted signal scoring,<br/>anti-spoof blend (65/35)"]
+        events["core/events.ts<br/>Typed FingerprintEmitter<br/>(progress/warning/complete)"]
+    end
+
+    subgraph "Runtime"
+        browser["runtime/browser.ts<br/>getBrowserEnv, now,<br/>hasDom, hasCanvas"]
+    end
+
+    subgraph "Signal Collectors (21)"
+        signalsIdx["signals/index.ts<br/>signalCollectors array +<br/>collectorMap (Map)"]
+        coreSigs["Core (10): ua, uaHints, locale,<br/>screen, hardware, storage, fonts,<br/>canvas, webgl, audio"]
+        extSigs["Extended (11): mediaDevices,<br/>permissions, webrtc, frameInfo,<br/>networkInfo, paymentSupport,<br/>referrerInfo, navigationInfo,<br/>riskSignals, adblock, geolocation"]
+    end
+
+    subgraph "Types"
+        publicT["types/public.ts<br/>All public interfaces:<br/>FingerprintResult, CollectOptions, etc."]
+        internalT["types/internal.ts<br/>BrowserEnv, SignalCollector,<br/>CollectorContext"]
+    end
+
+    subgraph "Constants"
+        consts["constants.ts<br/>CORE_SIGNALS, EXTENDED_SIGNALS,<br/>SYNC_SIGNALS, DEFAULT_TIMEOUT_MS,<br/>DEFAULT_FONT_LIST, etc."]
+    end
+
+    index --> client
+    cdn --> index
+    client --> options
+    client --> canonicalize
+    client --> hash
+    client --> antiSpoof
+    client --> confidence
+    client --> events
+    client --> browser
+    client --> signalsIdx
+    client --> consts
+    signalsIdx --> coreSigs
+    signalsIdx --> extSigs
+    signalsIdx --> internalT
+    coreSigs --> browser
+    extSigs --> browser
+```
+
+## Main runtime flow (async `collect()`)
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Client
+    participant Options
+    participant Signals
+    participant Core
+    participant Emitter
+
+    User->>Client: collect(options?)
+    Client->>Options: withDefaultOptions(options)
+    Options-->>Client: resolved options
+    Client->>Options: resolveSignalSet(resolved, 'async')
+    Options-->>Client: signalNames[]
+    Client->>Client: getBrowserEnv()
+
+    par Parallel signal collection
+        Client->>Signals: collector.collect(ctx) + timeout race
+        Signals-->>Client: SignalResult (per signal)
+        Client->>Emitter: emit('progress', { completed, total, signal, result })
+    end
+
+    loop For each ok signal
+        Client->>Core: canonicalizeToString(value)
+        Core-->>Client: deterministic JSON
+        Client->>Core: sha256Hex(json)
+        Core-->>Client: component hash
+    end
+
+    Client->>Core: sha256Hex(sorted component hashes)
+    Core-->>Client: thumbprint
+
+    Client->>Core: analyseSignals(signals)
+    Core-->>Client: AntiSpoofReport
+
+    Client->>Core: computeConfidence(signals, antiSpoof)
+    Core-->>Client: confidence score
+
+    Client->>Emitter: emit('complete', { result })
+    Client-->>User: FingerprintResult
+```
+
+## Data flow: signal → hash → thumbprint
+
+```mermaid
+flowchart LR
+    A["Signal value<br/>(raw JS object)"] --> B["canonicalizeToString()<br/>sorted keys, 6-decimal numbers,<br/>ISO dates, undefined → 'undefined'"]
+    B --> C["sha256Hex()<br/>64-char hex digest"]
+    C --> D["componentHashes<br/>Partial&lt;Record&lt;SignalName, string&gt;&gt;"]
+    D --> E["Sort by signal name,<br/>serialize as [[name, hash], ...]"]
+    E --> F["sha256Hex()"]
+    F --> G["thumbprint<br/>(composite 64-char hex)"]
+```
+
+## Signal tiers
+
+The library splits collectors into two tiers:
+
+| Tier | Count | Signals | Description |
+|------|-------|---------|-------------|
+| **Core** | 10 | `ua`, `uaHints`, `locale`, `screen`, `hardware`, `storage`, `fonts`, `canvas`, `webgl`, `audio` | Safe defaults — no permission prompts, broad browser/device context |
+| **Extended** | 11 | `mediaDevices`, `permissions`, `webrtc`, `frameInfo`, `networkInfo`, `paymentSupport`, `referrerInfo`, `navigationInfo`, `riskSignals`, `adblock`, `geolocation` | Slower or more privacy-sensitive probes — requires `extended: true` |
+
+## Sync vs async support
+
+| Type | Count | Signals |
+|------|-------|---------|
+| **Sync-capable** | 13 | `ua`, `locale`, `screen`, `hardware`, `storage`, `fonts`, `canvas`, `webgl`, `frameInfo`, `networkInfo`, `paymentSupport`, `referrerInfo`, `navigationInfo` |
+| **Async-only** | 8 | `uaHints`, `audio`, `mediaDevices`, `permissions`, `webrtc`, `riskSignals`, `adblock`, `geolocation` |
+
+When `collectSync()` is called, only the 13 sync-capable signals run. The 8 async-only signals are silently skipped (with a warning emitted).
+
+## Confidence scoring
+
+```mermaid
+flowchart TD
+    subgraph "Per-signal points"
+        W["Signal weights (0.2–1.0)"] --> E
+        S["Signal status"] --> E["Earn = weight × multiplier"]
+        E --> E2["ok → 1.0× | unsupported/blocked → 0.35×<br/>timeout → 0.15× | error → 0×"]
+    end
+
+    E2 --> BASE["base = earned / available"]
+
+    subgraph "Anti-spoof blend"
+        AS["antiSpoof.score<br/>(0 = bot, 1 = genuine)"] --> BLEND
+        BASE --> BLEND["final = base × (0.65 + antiSpoof × 0.35)"]
+    end
+
+    BLEND --> FINAL["confidence<br/>(0–1, 3 decimal places)"]
+```
+
+## Anti-spoof strategy
+
+The library does not use "secret" client tricks. It scores coherence through cross-signal consistency checks:
+
+- **Anomalies (6 checks, -0.12 each):** platform mismatches between UA and UA-CH, touch claims without touch points, mobile UA with desktop screen, Windows UA with macOS platform, implausible device memory, tiny screen geometry.
+- **Automation hints (2 checks, -0.18 each):** `navigator.webdriver` flag, headless user-agent string.
+
+This report is meant to enrich downstream server-side risk logic, not replace it.
+
+## Key design decisions
+
+- **Async first** — high-value collectors (audio, UA hints, media devices, permissions, WebRTC, risk signals) run async.
+- **Explainable output** — every signal includes a status and duration. No silent failures.
+- **No dangerous defaults** — no battery, sensors, arbitrary installed-app probes, or local IP harvesting.
+- **Anti-spoofing** focuses on coherence checks and automation hints, not "secret" client tricks.
+- **Zero runtime dependencies** — no CDN loads, no npm deps at runtime. SHA-256 is implemented in-house.

package/docs/privacy.md

@@ -1,20 +1,20 @@
-# Privacy Notes
-
-This implementation follows the brief's privacy-by-design direction:
-
-- The default collector avoids permission prompts.
-- It does not attempt raw local IP discovery.
-- It does not probe battery state, arbitrary sensors, or installed apps.
-- Media devices are summarized by counts and kinds only.
-- WebRTC collection uses capability signatures derived from SDP, not network-address harvesting.
-
-## Recommended operational posture
-
-- Treat the output as pseudonymous device intelligence, not anonymous data.
-- Retain raw signal payloads for a shorter window than derived hashes or risk scores.
-- Scope identifiers per product or tenant if cross-context correlation is not required.
-- Provide notice and an account- or tenant-level suppression path where appropriate.
-
-## Jurisdiction reminder
-
-The code can support legitimate security and fraud-prevention use cases, but the legal position still depends on purpose, notice, retention, and jurisdiction. The bundle is intentionally structured so upload is optional and backend handling can enforce local policy.
+# Privacy Notes
+
+This implementation follows the brief's privacy-by-design direction:
+
+- The default collector avoids permission prompts.
+- It does not attempt raw local IP discovery.
+- It does not probe battery state, arbitrary sensors, or installed apps.
+- Media devices are summarized by counts and kinds only.
+- WebRTC collection uses capability signatures derived from SDP, not network-address harvesting.
+
+## Recommended operational posture
+
+- Treat the output as pseudonymous device intelligence, not anonymous data.
+- Retain raw signal payloads for a shorter window than derived hashes or risk scores.
+- Scope identifiers per product or tenant if cross-context correlation is not required.
+- Provide notice and an account- or tenant-level suppression path where appropriate.
+
+## Jurisdiction reminder
+
+The code can support legitimate security and fraud-prevention use cases, but the legal position still depends on purpose, notice, retention, and jurisdiction. Backend handling can enforce local policy on data retention and processing.