@ianmenethil/zp-devicefp 0.1.0-alpha.1 → 0.1.0

package/README.md

@@ -1,6 +1,12 @@
 # Browser Fingerprint Library
 
-Async-first TypeScript browser and device fingerprinting library built from the supplied design brief. It collects a tiered set of browser signals, computes per-component hashes, returns a composite thumbprint, and includes a lightweight anomaly report instead of pretending a client-only fingerprint is unforgeable.
+Async-first TypeScript browser and device fingerprinting library. Collects 19 tiered browser signals, computes per-component SHA-256 hashes, returns a composite thumbprint, and includes an anti-spoof anomaly report with confidence scoring.
+
+- **Zero runtime dependencies** — no CDN loads, no npm deps at runtime.
+- **ESM, CJS, and IIFE** — single TypeScript source tree, three distribution formats.
+- **84 tests, 95% line coverage.**
+
+---
 
 ## Install
 
@@ -12,97 +18,236 @@ bun add @ianmenethil/zp-devicefp
 import { createFingerprintClient } from '@ianmenethil/zp-devicefp';
 ```
 
-## Package contents
+## Quick start
 
-```text
-@ianmenethil/zp-devicefp/
-├── dist/
-│   ├── npm/
-│   │   ├── index.mjs          ← ESM entry (browser, es2022)
-│   │   ├── index.cjs          ← CJS entry (Node 22+)
-│   │   └── index.d.ts         ← public types
-│   └── cdn/
-│       ├── zp.dfp.js              ← IIFE (unminified)
-│       ├── zp.dfp.min.js          ← IIFE (minified)
-│       ├── zp.dfp.obf.js          ← IIFE (minified + obfuscated)
-│       ├── zp.dfp.esm.js          ← ESM for import()
-│       └── zp.dfp.manifest.json   ← SRI integrity hashes
-├── README.md
-├── LICENSE
-└── docs/
+```ts
+import { createFingerprintClient } from '@ianmenethil/zp-devicefp';
+
+const client = await createFingerprintClient({ timeoutMs: 1500 });
+
+// Async collection — all signals, parallel with timeouts
+const result = await client.collect();
+
+console.log(result.thumbprint);      // "a1b2c3d4..." (64-char SHA-256 hex)
+console.log(result.confidence);      // 0.87
+console.log(result.antiSpoof.score); // 0.94
 ```
 
-## CDN
+---
 
-CDN files are available from two sources — jsDelivr (automatic from each npm publish) and the self-hosted CDN at `cdn.zenithpayments.support` (deployed on every build).
+## API overview
 
-| File | jsDelivr | Self-hosted |
-|------|----------|-------------|
-| IIFE (minified) | `@ianmenethil/zp-devicefp/dist/cdn/zp.dfp.min.js` | `devicefp/latest/zp.dfp.min.js` |
-| IIFE (unminified) | `@ianmenethil/zp-devicefp/dist/cdn/zp.dfp.js` | `devicefp/latest/zp.dfp.js` |
-| IIFE (obfuscated) | `@ianmenethil/zp-devicefp/dist/cdn/zp.dfp.obf.js` | `devicefp/latest/zp.dfp.obf.js` |
-| ESM | `@ianmenethil/zp-devicefp/dist/cdn/zp.dfp.esm.js` | `devicefp/latest/zp.dfp.esm.js` |
-| Manifest | `@ianmenethil/zp-devicefp/dist/cdn/zp.dfp.manifest.json` | `devicefp/latest/zp.dfp.manifest.json` |
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `client.collect(options?)` | `Promise<FingerprintResult>` | Async collection. All signals run in parallel with per-signal timeouts. Emits events. |
+| `client.collectSync(options?)` | `FingerprintResult` | Sync collection. Only 13 of 19 signals support sync mode. No timeout/abort. |
+| `client.upload(result, options)` | `Promise<Response>` | POST the fingerprint to a backend endpoint. |
+| `client.on(event, callback)` | `() => void` | Subscribe to `progress`, `warning`, or `complete` events during async collection. |
 
-- **jsDelivr base:** `https://cdn.jsdelivr.net/npm/` — drop the version tag for latest, or pin with `@2.1` or `@2`.
-- **Self-hosted base:** `https://cdn.zenithpayments.support/` — `latest/` always points to the most recent build; versioned folders (`2.1.1/`) are created on `bun run release`.
+### Events
 
-### CDN usage
+```ts
+client.on('progress', (e) => {
+	// { completed: 3, total: 10, signal: 'canvas', result: SignalResult }
+	console.log(`${e.completed}/${e.total}: ${e.signal}`);
+});
 
-```html
-<!-- jsDelivr -->
-<script src="https://cdn.jsdelivr.net/npm/@ianmenethil/zp-devicefp/dist/cdn/zp.dfp.min.js"></script>
+client.on('warning', (e) => {
+	// { signal?: 'webrtc', message: 'RTCPeerConnection not available' }
+	console.warn(e.message);
+});
 
-<!-- Self-hosted -->
-<script src="https://cdn.zenithpayments.support/devicefp/latest/zp.dfp.min.js"></script>
+client.on('complete', (e) => {
+	// { result: FingerprintResult }
+	console.log('Done', e.result.thumbprint);
+});
+```
 
-<script>
-  const client = await window.DeviceFP.createFingerprintClient({ timeoutMs: 1500 });
-  const result = await client.collect();
-</script>
+### Upload
+
+```ts
+await client.upload(result, {
+	endpoint: 'https://api.example.com/fingerprint',
+	headers: { 'Authorization': 'Bearer token' },
+	bodyExtras: { sessionId: 'abc123' },
+});
 ```
 
-## Public API
+### Aborting
 
 ```ts
-import { createFingerprintClient } from '@ianmenethil/zp-devicefp';
+const controller = new AbortController();
 
-const client = await createFingerprintClient({
-  timeoutMs: 1500,
-  extended: false,
-});
+const resultPromise = client.collect({ abortSignal: controller.signal });
 
-const result = await client.collect();
-console.log(result.thumbprint, result.antiSpoof);
-console.log(result.diagnostics);
+// Cancel mid-flight
+controller.abort();
+
+const result = await resultPromise;
+// Aborted signals appear as status: 'error' with error: 'Collection aborted.'
 ```
 
-`collectSync()` intentionally returns a partial fingerprint that only uses sync-safe collectors.
+---
 
-Each result also includes:
+## Options
 
-- `componentHashes`: deterministic per-signal digests
-- `antiSpoof`: anomaly and automation hints
-- `diagnostics`: requested signals, completed signals, and elapsed runtime
-- `warnings`: collection-time warnings that are scoped to that run only
+```ts
+interface CollectOptions {
+	include?: SignalName[];      // whitelist: only collect these signals
+	exclude?: SignalName[];      // blacklist: skip these signals
+	timeoutMs?: number;          // per-signal timeout (default: 1500)
+	abortSignal?: AbortSignal;   // cancel in-flight collection
+	extended?: boolean;          // include extended-tier signals (default: false)
+	debug?: boolean;             // enable debug logging (default: false)
+}
+```
 
-## Signals
+---
 
-Core tier:
+## Result shape
 
-`ua` · `uaHints` · `locale` · `screen` · `hardware` · `storage` · `fonts` · `canvas` · `webgl` · `audio`
+```ts
+interface FingerprintResult {
+	schemaVersion: number;       // schema version (integer, bumped on breaking changes)
+	libraryVersion: string;      // library semver string
+	thumbprint: string;          // SHA-256 of all component hashes combined
+	confidence: number;          // 0–1 quality score
+	componentHashes: Partial<Record<SignalName, string>>; // per-signal SHA-256 digests
+	signals: Partial<Record<SignalName, SignalResult>>;   // raw signal results
+	antiSpoof: AntiSpoofReport;  // coherence analysis and automation hints
+	warnings: string[];          // non-fatal collection warnings
+	diagnostics: CollectorDiagnostics; // run metadata
+}
+```
 
-Extended tier:
+### `AntiSpoofReport`
 
-`mediaDevices` · `permissions` · `webrtc` · `frameInfo` · `networkInfo` · `paymentSupport` · `referrerInfo` · `navigationInfo` · `riskSignals`
+```ts
+{
+	score: number;           // 0 = automated/bot, 1 = genuine user
+	anomalies: string[];     // signal inconsistencies (6 anomaly types)
+	automationHints: string[]; // headless/bot indicators (2 hint types)
+}
+```
 
-## Design choices
+### `SignalResult`
+
+```ts
+{
+	status: 'ok' | 'unsupported' | 'blocked' | 'timeout' | 'error';
+	value?: unknown;     // signal-specific data (only when status === 'ok')
+	durationMs: number;  // wall-clock collection time
+	error?: string;      // error description (when status !== 'ok')
+}
+```
+
+Full API reference with all types, methods, events, options, confidence scoring, anti-spoof heuristics, and constants: **[docs/api-reference.md](docs/api-reference.md)**
+
+---
+
+## Signals (19 total)
+
+### Core tier (10 signals, enabled by default)
 
-- Async first: high-value collectors like audio, UA hints, media devices, permissions, and WebRTC run in `collect()`.
-- Explainable output: every signal includes a status and duration.
-- No dangerous defaults: no battery, sensors, arbitrary installed-app probes, or local IP harvesting.
-- Anti-spoofing focuses on coherence checks and automation hints.
-- Upload is backend-neutral and optional.
+| Signal | Sync | Description |
+|--------|------|-------------|
+| `ua` | yes | `navigator.userAgent`, platform, webdriver, maxTouchPoints, cookieEnabled, vendor |
+| `uaHints` | no | User-Agent Client Hints: brands, platform, high-entropy values (architecture, bitness, model, etc.) |
+| `locale` | yes | Language, languages, locale, calendar, numbering system, timeZone, formatted samples |
+| `screen` | yes | Screen width/height, colorDepth, orientation, DPR, media queries (color-gamut, reduced-motion, contrast, forced-colors) |
+| `hardware` | yes | `navigator.hardwareConcurrency`, `deviceMemory`, platform, maxTouchPoints |
+| `storage` | yes | localStorage, sessionStorage, IndexedDB, Web SQL availability (write-read-delete probe) |
+| `fonts` | yes | Installed font detection via hidden DOM span measurement (10 fonts, 3 generic families) |
+| `canvas` | yes | Canvas 2D rendering pattern → `toDataURL()` (GPU+driver fingerprint) |
+| `webgl` | yes | WebGL renderer/vendor (unmasked), version, extensions, max texture/viewport |
+| `audio` | no | OfflineAudioContext oscillator+compressor numeric signature |
+
+### Extended tier (9 signals, requires `extended: true`)
+
+| Signal | Sync | Description |
+|--------|------|-------------|
+| `mediaDevices` | no | Media device counts by kind (audioinput, audiooutput, videoinput) — no labels/IDs |
+| `permissions` | no | Permissions API state for geolocation, notifications, camera, microphone |
+| `webrtc` | no | RTCPeerConnection SDP codec/extmap capability hash |
+| `frameInfo` | yes | Iframe count, source domains, top-level window check |
+| `networkInfo` | yes | NetworkInformation API: effectiveType, downlink, RTT, saveData |
+| `paymentSupport` | yes | `window.PaymentRequest` availability |
+| `referrerInfo` | yes | `document.referrer` |
+| `navigationInfo` | yes | PerformanceNavigationTiming.type (navigate/reload/back_forward/prerender) |
+| `riskSignals` | no | Bot/headless detection: webdriver, headless UA, missing chrome object, zero dimensions, empty plugins, UA-CH consistency, notification permission, time to capture |
+
+Complete per-signal documentation with value shapes, APIs used, and edge cases: **[docs/signals.md](docs/signals.md)**
+
+---
+
+## Anti-spoof heuristics (6 anomalies + 2 automation hints)
+
+| Code | What it detects |
+|------|----------------|
+| `navigator_webdriver` | `navigator.webdriver` is truthy |
+| `headless_user_agent` | UA contains `"headless"` |
+| `ua_platform_mismatch` | `navigator.platform` contradicts UA-CH platform |
+| `touch_claim_without_touch_points` | iPhone UA but `maxTouchPoints` is 0 |
+| `mobile_ua_desktop_screen` | Android UA with screen width >= 1600px |
+| `windows_ua_mac_platform` | Windows UA but platform reports macOS |
+| `implausible_device_memory` | `deviceMemory` < 0.25 or > 64 GB |
+| `tiny_screen_geometry` | Screen width and height both < 200px |
+
+---
+
+## Confidence scoring
+
+Each signal has a fixed weight (0.2–1.0). Canvas, WebGL, fonts, and audio carry the highest weight. Status affects points earned: `ok` = full weight, `unsupported`/`blocked` = 35%, `timeout` = 15%, `error` = 0.
+
+The base ratio is blended with the anti-spoof score (65% base / 35% anti-spoof). Full details in [docs/api-reference.md](docs/api-reference.md).
+
+---
+
+## CDN
+
+CDN files are available from jsDelivr (automatic from npm publish) and self-hosted.
+
+| File | Format |
+|------|--------|
+| `zp.dfp.js` | IIFE (unminified) |
+| `zp.dfp.min.js` | IIFE (minified) |
+| `zp.dfp.obf.js` | IIFE (minified + obfuscated) |
+| `zp.dfp.esm.js` | ESM for `import()` |
+| `zp.dfp.manifest.json` | SRI integrity hashes |
+
+```html
+<!-- jsDelivr -->
+<script src="https://cdn.jsdelivr.net/npm/@ianmenethil/zp-devicefp/dist/cdn/zp.dfp.min.js"></script>
+
+<!-- Self-hosted -->
+<script src="https://cdn.zenithpayments.support/devicefp/latest/zp.dfp.min.js"></script>
+
+<script>
+	const client = await window.DeviceFP.createFingerprintClient({ timeoutMs: 1500 });
+	const result = await client.collect();
+	console.log(window.DeviceFP.LIBRARY_VERSION); // "0.1.0"
+</script>
+```
+
+---
+
+## Package layout
+
+```text
+dist/
+├── npm/
+│   ├── index.mjs       # ESM entry (browser, ES2022)
+│   ├── index.cjs       # CJS entry (Node 22+)
+│   └── index.d.ts      # public types
+└── cdn/
+    ├── zp.dfp.js       # IIFE (unminified)
+    ├── zp.dfp.min.js   # IIFE (minified)
+    ├── zp.dfp.obf.js   # IIFE (minified + obfuscated)
+    ├── zp.dfp.esm.js   # ESM for import()
+    └── zp.dfp.manifest.json
+```
+
+---
 
 ## Build and test
 
@@ -113,22 +258,32 @@ bun test            # 84 tests, 95% line coverage
 bun run smoke       # validates all dist artifacts
 ```
 
-The build pipeline runs esbuild to produce `dist/npm/` and `dist/cdn/`, then copies CDN files to the local CDN server directory for self-hosting.
+---
 
-## Limitations
+## Docs
 
-- Browser-side fingerprints are probabilistic, not identity proofs.
-- The default font probe is intentionally bounded and conservative.
-- The anti-spoof report is heuristic and should be combined with server-side context for real fraud or login-risk decisions.
+| Document | Covers |
+|----------|--------|
+| [docs/api-reference.md](docs/api-reference.md) | Complete API: types, methods, events, options, constants, confidence, anti-spoof, upload, CDN |
+| [docs/signals.md](docs/signals.md) | All 19 signals: value shapes, APIs used, sync support, edge cases |
+| [docs/architecture.md](docs/architecture.md) | High-level flow and module map |
+| [docs/privacy.md](docs/privacy.md) | Privacy-by-design notes |
+| [docs/testing.md](docs/testing.md) | Test strategy and coverage intent |
 
-## Layout
+---
 
-```text
-zp-devicefp/
-├── src/           # 19 signal collectors, core modules
-├── tests/         # bun test (unit + integration)
-├── docs/          # architecture, privacy, testing docs
-├── .scripts/      # esbuild build pipeline
-├── scripts/       # smoke tests
-└── dist/          # generated (npm/ + cdn/)
-```
+## Design choices
+
+- **Async first** — high-value collectors (audio, UA hints, media devices, permissions, WebRTC, risk signals) run in `collect()`.
+- **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.
+- **Upload is backend-neutral and optional** — you control where (if anywhere) fingerprints are sent.
+
+---
+
+## Limitations
+
+- Browser-side fingerprints are probabilistic, not identity proofs.
+- Font detection is bounded to 10 common fonts and is intentionally conservative.
+- The anti-spoof report is heuristic — combine with server-side context for fraud or login-risk decisions.

package/docs/api-reference.md

@@ -0,0 +1,472 @@
+# API Reference
+
+Complete reference for `@ianmenethil/zp-devicefp` — every type, method, option, event, and export.
+
+---
+
+## Exports
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `createFingerprintClient` | function | Async factory that returns a configured `FingerprintClient` |
+| `LIBRARY_VERSION` | `string` | Semantic version of the library (e.g. `"0.1.0"`) |
+| `SCHEMA_VERSION` | `number` | Schema version for the result shape (integer, bumped on breaking changes) |
+
+---
+
+## `createFingerprintClient(options?)`
+
+Factory function. Returns `Promise<FingerprintClient>`.
+
+```ts
+import { createFingerprintClient } from '@ianmenethil/zp-devicefp';
+
+const client = await createFingerprintClient({
+	timeoutMs: 1500,
+	extended: false,
+	debug: false,
+});
+```
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `options` | `CollectOptions` | `{}` | Configuration overrides applied to all subsequent `collect()` / `collectSync()` calls. Can be overridden per-call. |
+
+---
+
+## `CollectOptions`
+
+```ts
+interface CollectOptions {
+	include?: SignalName[];
+	exclude?: SignalName[];
+	timeoutMs?: number;
+	abortSignal?: AbortSignal;
+	extended?: boolean;
+	debug?: boolean;
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `include` | `SignalName[]` | undefined | Whitelist of signals to collect. When set, only these signals run. |
+| `exclude` | `SignalName[]` | undefined | Blacklist of signals to skip. |
+| `timeoutMs` | `number` | `1500` | Per-signal timeout in milliseconds. Signals exceeding this return `status: 'timeout'`. |
+| `abortSignal` | `AbortSignal` | undefined | Pass an `AbortController.signal` to cancel in-flight collection. Aborted signals return `status: 'error'`. |
+| `extended` | `boolean` | `false` | When `true`, includes extended-tier signals in the collection. |
+| `debug` | `boolean` | `false` | Enable debug logging (passed to signal collectors via context). |
+
+### Signal resolution order
+
+1. Start with core signals (`ua`, `uaHints`, `locale`, `screen`, `hardware`, `storage`, `fonts`, `canvas`, `webgl`, `audio`).
+2. If `extended: true`, add all 9 extended signals.
+3. In `collectSync()` mode, remove signals without `supportsSync: true`.
+4. If `include` is set, keep only signals present in the list.
+5. Remove any signals listed in `exclude`.
+
+---
+
+## `FingerprintClient`
+
+The object returned by `createFingerprintClient()`.
+
+```ts
+interface FingerprintClient {
+	collect(options?: CollectOptions): Promise<FingerprintResult>;
+	collectSync(options?: Omit<CollectOptions, 'timeoutMs' | 'abortSignal'>): FingerprintResult;
+	upload(result: FingerprintResult, options: UploadOptions): Promise<Response>;
+	on<K extends keyof EventPayloadMap>(event: K, cb: (payload: EventPayloadMap[K]) => void): () => void;
+}
+```
+
+### `client.collect(options?)`
+
+Collects signals asynchronously. All signals run in parallel with per-signal timeouts. Emits `progress`, `warning`, and `complete` events.
+
+```ts
+const result = await client.collect({ extended: true, timeoutMs: 3000 });
+console.log(result.thumbprint);
+console.log(result.confidence);
+```
+
+- **Returns**: `Promise<FingerprintResult>`
+- **Events emitted**: `progress` (per signal), `warning` (on non-fatal issues), `complete` (once, with final result)
+
+### `client.collectSync(options?)`
+
+Collects signals synchronously. Only signals with `supportsSync: true` will run. Timeout and abort are not supported — the `timeoutMs` and `abortSignal` fields are excluded from the options type.
+
+```ts
+const result = client.collectSync();
+console.log(result.thumbprint);
+```
+
+- **Returns**: `FingerprintResult`
+- **Sync-capable signals** (13): `ua`, `locale`, `screen`, `hardware`, `storage`, `fonts`, `canvas`, `webgl`, `frameInfo`, `networkInfo`, `paymentSupport`, `referrerInfo`, `navigationInfo`
+- **NOT sync-capable** (6): `uaHints`, `audio`, `mediaDevices`, `permissions`, `webrtc`, `riskSignals`
+
+### `client.upload(result, options)`
+
+Posts a fingerprint result to a remote endpoint via HTTP POST.
+
+```ts
+const response = await client.upload(result, {
+	endpoint: 'https://api.example.com/fingerprint',
+	headers: { 'Authorization': 'Bearer token' },
+	bodyExtras: { sessionId: 'abc123' },
+});
+```
+
+Payload shape:
+```json
+{
+	"fingerprint": { /* full FingerprintResult */ },
+	"...bodyExtras keys..."
+}
+```
+
+- **Returns**: `Promise<Response>` — native `fetch` Response
+- **Throws**: if `fetch` is not available in the runtime
+
+### `client.on(event, callback)`
+
+Subscribe to lifecycle events during async collection.
+
+```ts
+const unsubscribe = client.on('progress', (event) => {
+	console.log(`${event.completed}/${event.total}: ${event.signal}`);
+});
+
+// Later, remove the listener:
+unsubscribe();
+```
+
+- **Returns**: `() => void` — call to unsubscribe
+
+---
+
+## Events
+
+| Event | Payload Type | When Emitted |
+|-------|-------------|--------------|
+| `progress` | `ProgressEvent` | After each signal completes during `collect()` |
+| `warning` | `WarningEvent` | When a non-fatal issue occurs (unsupported signal, blocked API, etc.) |
+| `complete` | `CompleteEvent` | After all signals finish in `collect()` |
+
+### `ProgressEvent`
+
+```ts
+interface ProgressEvent {
+	completed: number;  // signals completed so far
+	total: number;      // total signals requested
+	signal: SignalName; // name of the signal that just completed
+	result: SignalResult; // the signal's collection result
+}
+```
+
+### `WarningEvent`
+
+```ts
+interface WarningEvent {
+	signal?: SignalName;  // which signal triggered the warning, if applicable
+	message: string;       // human-readable warning message
+}
+```
+
+### `CompleteEvent`
+
+```ts
+interface CompleteEvent {
+	result: FingerprintResult; // the completed fingerprint result
+}
+```
+
+---
+
+## `FingerprintResult`
+
+The complete output of `collect()` or `collectSync()`.
+
+```ts
+interface FingerprintResult {
+	schemaVersion: number;
+	libraryVersion: string;
+	thumbprint: string;
+	confidence: number;
+	componentHashes: Partial<Record<SignalName, string>>;
+	signals: Partial<Record<SignalName, SignalResult>>;
+	antiSpoof: AntiSpoofReport;
+	warnings: string[];
+	diagnostics: CollectorDiagnostics;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `schemaVersion` | `number` | Schema version (currently `1`). Bumped on breaking result shape changes. |
+| `libraryVersion` | `string` | Library version that produced this result (e.g. `"0.1.0"`). |
+| `thumbprint` | `string` | SHA-256 hash of all component hashes combined. The primary fingerprint identifier. |
+| `confidence` | `number` | 0–1 score. 0 = unreliable, 1 = high confidence. Weighted average of signal quality blended with anti-spoof score. |
+| `componentHashes` | `Partial<Record<SignalName, string>>` | Per-signal SHA-256 hashes of canonicalized signal values. Only present for signals that returned `value`. |
+| `signals` | `Partial<Record<SignalName, SignalResult>>` | Raw signal collection results, keyed by signal name. |
+| `antiSpoof` | `AntiSpoofReport` | Cross-signal coherence analysis and automation detection. |
+| `warnings` | `string[]` | Non-fatal warnings from the collection run. |
+| `diagnostics` | `CollectorDiagnostics` | Metadata about what ran and how long it took. |
+
+### Thumbprint derivation
+
+1. Each signal value is canonicalized (deterministic JSON serialization with sorted keys, normalized numbers, ISO dates).
+2. Each canonicalized value is hashed with SHA-256 → `componentHashes`.
+3. Component hashes are sorted by name, serialized as `[[name, hash], ...]`, canonicalized, and hashed once more → `thumbprint`.
+
+---
+
+## `SignalResult`
+
+The result of collecting a single signal.
+
+```ts
+interface SignalResult<T = unknown> {
+	status: 'ok' | 'unsupported' | 'blocked' | 'timeout' | 'error';
+	value?: T;
+	durationMs: number;
+	error?: string;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `status` | `SignalStatus` | Outcome of the collection attempt. |
+| `value` | `T` (optional) | The collected signal data. Only present when `status` is `'ok'`. |
+| `durationMs` | `number` | Wall-clock milliseconds spent collecting this signal. |
+| `error` | `string` (optional) | Human-readable error description. Present when status is not `'ok'`. |
+
+### `SignalStatus`
+
+```ts
+type SignalStatus = 'ok' | 'unsupported' | 'blocked' | 'timeout' | 'error';
+```
+
+| Value | Meaning |
+|-------|---------|
+| `ok` | Signal collected successfully. `value` is populated. |
+| `unsupported` | The required browser API is not available. |
+| `blocked` | The API exists but access was denied (e.g. permissions, secure context). |
+| `timeout` | Collection exceeded the per-signal timeout. |
+| `error` | An unexpected error occurred during collection. |
+
+---
+
+## `AntiSpoofReport`
+
+Cross-signal coherence analysis.
+
+```ts
+interface AntiSpoofReport {
+	score: number;
+	anomalies: string[];
+	automationHints: string[];
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `score` | `number` | Normalized score 0–1. 0 = automated/bot, 1 = genuine user. Each anomaly deducts 0.12; each automation hint deducts 0.18. Floor at 0, ceiling at 1. |
+| `anomalies` | `string[]` | Specific inconsistencies found between signals. |
+| `automationHints` | `string[]` | Indicators of headless, automated, or bot environments. |
+
+### Anomaly codes
+
+| Code | Trigger |
+|------|---------|
+| `ua_platform_mismatch` | `navigator.platform` contradicts UA Client Hints platform |
+| `touch_claim_without_touch_points` | iPhone UA but `maxTouchPoints` is 0 |
+| `mobile_ua_desktop_screen` | Android UA but screen width >= 1600px |
+| `windows_ua_mac_platform` | Windows UA string but platform reports macOS |
+| `implausible_device_memory` | `deviceMemory` < 0.25 or > 64 GB |
+| `tiny_screen_geometry` | Screen width and height both < 200px |
+
+### Automation hint codes
+
+| Code | Trigger |
+|------|---------|
+| `navigator_webdriver` | `navigator.webdriver` is truthy |
+| `headless_user_agent` | UA string contains `"headless"` |
+
+---
+
+## `CollectorDiagnostics`
+
+```ts
+interface CollectorDiagnostics {
+	requestedSignals: SignalName[];
+	completedSignals: SignalName[];
+	elapsedMs: number;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `requestedSignals` | `SignalName[]` | Signals requested for the run (after include/exclude/mode resolution). |
+| `completedSignals` | `SignalName[]` | Signals that produced a result (any status). Sorted alphabetically. |
+| `elapsedMs` | `number` | Total wall-clock milliseconds for the entire run (rounded to 3 decimal places). |
+
+---
+
+## `UploadOptions`
+
+```ts
+interface UploadOptions {
+	endpoint: string;
+	headers?: Record<string, string>;
+	bodyExtras?: Record<string, unknown>;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `endpoint` | `string` | URL to POST the fingerprint payload to. |
+| `headers` | `Record<string, string>` | Additional HTTP headers merged with `content-type: application/json`. |
+| `bodyExtras` | `Record<string, unknown>` | Extra properties merged into the JSON body alongside `fingerprint`. |
+
+---
+
+## Confidence scoring
+
+Each signal has a fixed weight. The base confidence is the weighted ratio of earned points to available points.
+
+### Signal weights
+
+| Signal | Weight | Signal | Weight |
+|--------|--------|--------|--------|
+| `canvas` | 1.0 | `audio` | 0.9 |
+| `webgl` | 1.0 | `fonts` | 0.9 |
+| `screen` | 0.8 | `webrtc` | 0.8 |
+| `uaHints` | 0.7 | `hardware` | 0.7 |
+| `riskSignals` | 0.7 | `mediaDevices` | 0.6 |
+| `networkInfo` | 0.6 | `ua` | 0.5 |
+| `locale` | 0.5 | `storage` | 0.4 |
+| `permissions` | 0.4 | `navigationInfo` | 0.4 |
+| `frameInfo` | 0.3 | `referrerInfo` | 0.3 |
+| `paymentSupport` | 0.2 | | |
+
+### Points per status
+
+| Status | Points earned |
+|--------|---------------|
+| `ok` | Full weight |
+| `unsupported` | 35% of weight |
+| `blocked` | 35% of weight |
+| `timeout` | 15% of weight |
+| `error` | 0% |
+
+### Final score
+
+```
+base = earned / available
+final = base * (0.65 + antiSpoofScore * 0.35)
+```
+
+The anti-spoof score blends 35% into the final confidence, meaning a low anti-spoof score drags confidence down proportionally.
+
+---
+
+## Internal constants
+
+These values are used internally to configure the library. They are not public exports but are documented here for reference.
+
+| Constant | Type | Value |
+|----------|------|-------|
+| `CORE_SIGNALS` | `SignalName[]` | `['ua', 'uaHints', 'locale', 'screen', 'hardware', 'storage', 'fonts', 'canvas', 'webgl', 'audio']` |
+| `EXTENDED_SIGNALS` | `SignalName[]` | `['mediaDevices', 'permissions', 'webrtc', 'frameInfo', 'networkInfo', 'paymentSupport', 'referrerInfo', 'navigationInfo', 'riskSignals']` |
+| `SYNC_SIGNALS` | `SignalName[]` | `['ua', 'locale', 'screen', 'hardware', 'storage', 'fonts', 'canvas', 'webgl', 'frameInfo', 'networkInfo', 'paymentSupport', 'referrerInfo', 'navigationInfo']` |
+| `DEFAULT_TIMEOUT_MS` | `number` | `1500` |
+| `DEFAULT_FONT_LIST` | `string[]` | `['Arial', 'Helvetica Neue', 'Times New Roman', 'Georgia', 'Courier New', 'Trebuchet MS', 'Verdana', 'Tahoma', 'Impact', 'Comic Sans MS']` |
+| `DEFAULT_PERMISSION_NAMES` | `readonly string[]` | `['geolocation', 'notifications', 'camera', 'microphone']` |
+| `DEFAULT_UA_HINTS` | `readonly string[]` | `['architecture', 'bitness', 'formFactors', 'fullVersionList', 'model', 'platform', 'platformVersion', 'wow64']` |
+
+---
+
+## CDN / IIFE API
+
+When loaded via `<script>` tag, the library attaches to `window.DeviceFP`.
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@ianmenethil/zp-devicefp/dist/cdn/zp.dfp.min.js"></script>
+<script>
+	const client = await window.DeviceFP.createFingerprintClient({ timeoutMs: 1500 });
+	const result = await client.collect();
+	console.log(window.DeviceFP.LIBRARY_VERSION);
+	console.log(window.DeviceFP.SCHEMA_VERSION);
+</script>
+```
+
+### `window.DeviceFP` shape
+
+| Property | Type |
+|----------|------|
+| `createFingerprintClient` | `(options?: CollectOptions) => Promise<FingerprintClient>` |
+| `LIBRARY_VERSION` | `string` |
+| `SCHEMA_VERSION` | `number` |
+
+### CDN files
+
+| File | Format | Description |
+|------|--------|-------------|
+| `zp.dfp.js` | IIFE | Unminified global bundle |
+| `zp.dfp.min.js` | IIFE | Minified global bundle |
+| `zp.dfp.obf.js` | IIFE | Minified + obfuscated global bundle |
+| `zp.dfp.esm.js` | ESM | Module for `import()` / `<script type="module">` |
+| `zp.dfp.manifest.json` | JSON | SRI integrity hashes for all CDN files |
+
+### CDN sources
+
+| Source | Base URL |
+|--------|----------|
+| jsDelivr | `https://cdn.jsdelivr.net/npm/@ianmenethil/zp-devicefp/dist/cdn/` |
+| Self-hosted | `https://cdn.zenithpayments.support/devicefp/latest/` |
+
+---
+
+## NPM package layout
+
+```text
+@ianmenethil/zp-devicefp/
+├── dist/npm/
+│   ├── index.mjs       # ESM entry (browser, ES2022)
+│   ├── index.cjs       # CJS entry (Node 22+)
+│   └── index.d.ts      # Public type declarations
+├── dist/cdn/
+│   ├── zp.dfp.js       # IIFE (unminified)
+│   ├── zp.dfp.min.js   # IIFE (minified)
+│   ├── zp.dfp.obf.js   # IIFE (minified + obfuscated)
+│   ├── zp.dfp.esm.js   # ESM for import()
+│   └── zp.dfp.manifest.json
+```
+
+---
+
+## NPM usage
+
+```bash
+bun add @ianmenethil/zp-devicefp
+```
+
+```ts
+import {
+	createFingerprintClient,
+	LIBRARY_VERSION,
+	SCHEMA_VERSION,
+} from '@ianmenethil/zp-devicefp';
+
+const client = await createFingerprintClient({ timeoutMs: 2000 });
+const result = await client.collect({ extended: true });
+
+// Upload to your backend
+await client.upload(result, {
+	endpoint: '/api/fingerprint',
+	bodyExtras: { userId: 'u_123' },
+});
+```

package/docs/signals.md

@@ -0,0 +1,383 @@
+# Signal Reference
+
+Every signal collected by the library, including its name, tier, sync support, description, and the shape of its `value` when `status` is `'ok'`.
+
+---
+
+## Signal overview
+
+| # | Signal | Tier | Sync | Description |
+|---|--------|------|------|-------------|
+| 1 | `ua` | core | yes | Legacy `navigator.userAgent` and related properties |
+| 2 | `uaHints` | core | no | User-Agent Client Hints (brands, platform, high-entropy values) |
+| 3 | `locale` | core | yes | Language, locale, calendar, time zone, number/date formatting |
+| 4 | `screen` | core | yes | Screen dimensions, color depth, orientation, DPR, media queries |
+| 5 | `hardware` | core | yes | Hardware concurrency, device memory, platform |
+| 6 | `storage` | core | yes | localStorage, sessionStorage, IndexedDB, Web SQL availability |
+| 7 | `fonts` | core | yes | Installed font detection via DOM measurement |
+| 8 | `canvas` | core | yes | Canvas 2D rendering fingerprint (GPU+driver signature) |
+| 9 | `webgl` | core | yes | WebGL renderer, vendor, extensions, GPU capabilities |
+| 10 | `audio` | core | no | OfflineAudioContext oscillator+compressor signature |
+| 11 | `mediaDevices` | extended | no | Media device kind enumeration (counts only, no labels) |
+| 12 | `permissions` | extended | no | Permissions API state for geolocation, notifications, camera, microphone |
+| 13 | `webrtc` | extended | no | RTCPeerConnection codec and extmap capability hash |
+| 14 | `frameInfo` | extended | yes | Iframe context: count, domains, top-level check |
+| 15 | `networkInfo` | extended | yes | NetworkInformation API: effective type, downlink, RTT, saveData |
+| 16 | `paymentSupport` | extended | yes | PaymentRequest API availability |
+| 17 | `referrerInfo` | extended | yes | `document.referrer` |
+| 18 | `navigationInfo` | extended | yes | PerformanceNavigationTiming type (navigate/reload/back_forward/prerender) |
+| 19 | `riskSignals` | extended | no | Bot/headless detection: 9 heuristics |
+
+---
+
+## Core signals
+
+### `ua` — User-Agent string
+
+**Tier:** core | **Sync:** yes | **APIs used:** `navigator`
+
+```ts
+// value shape:
+{
+	userAgent: string;        // navigator.userAgent
+	appVersion: string;       // navigator.appVersion
+	vendor: string;           // navigator.vendor
+	platform: string;         // navigator.platform
+	webdriver: boolean;       // navigator.webdriver
+	maxTouchPoints: number;   // navigator.maxTouchPoints
+	cookieEnabled: boolean;   // navigator.cookieEnabled
+	vendorSub: string;        // navigator.vendorSub
+}
+```
+
+Returns `'unsupported'` if `navigator` is not available.
+
+### `uaHints` — User-Agent Client Hints
+
+**Tier:** core | **Sync:** no | **APIs used:** `navigator.userAgentData`
+
+```ts
+// value shape:
+{
+	brands: { brand: string; version: string }[];  // low-entropy brands
+	mobile: boolean;                                 // userAgentData.mobile
+	platform: string;                                // userAgentData.platform
+	architecture?: string;                           // high-entropy: CPU architecture
+	bitness?: string;                                // high-entropy: 32/64
+	formFactors?: string[];                          // high-entropy: device form factors
+	fullVersionList?: { brand: string; version: string }[]; // high-entropy: full versions
+	model?: string;                                  // high-entropy: device model
+	platformVersion?: string;                        // high-entropy: OS version
+	wow64?: boolean;                                 // high-entropy: 32-bit on 64-bit
+}
+```
+
+Returns `'unsupported'` if `navigator.userAgentData` is not available. Returns `'blocked'` if `getHighEntropyValues` throws.
+
+### `locale` — Language and internationalization
+
+**Tier:** core | **Sync:** yes | **APIs used:** `navigator`, `Intl`
+
+```ts
+// value shape:
+{
+	language: string;                // navigator.language
+	languages: readonly string[];    // navigator.languages
+	locale: string;                  // Intl.DateTimeFormat resolved locale
+	calendar: string;                // e.g. "gregory", "iso8601"
+	numberingSystem: string;         // e.g. "latn", "arab"
+	timeZone: string;                // IANA timezone e.g. "America/New_York"
+	hourCycle: string;               // e.g. "h12", "h23"
+	timeZoneOffsetMinutes: number;   // UTC offset in minutes
+	formattedNumber: string;         // Intl.NumberFormat sample: "123,456.789"
+	formattedDate: string;           // Intl.DateTimeFormat sample for Jan 2, 2024
+	formattedRelativeDay: string | undefined; // Intl.RelativeTimeFormat: "yesterday" etc.
+}
+```
+
+Returns `'unsupported'` if `navigator` or `Intl` is not available.
+
+### `screen` — Screen and display
+
+**Tier:** core | **Sync:** yes | **APIs used:** `screen`, `navigator`, `matchMedia`, `devicePixelRatio`
+
+```ts
+// value shape:
+{
+	width: number;                   // screen.width
+	height: number;                  // screen.height
+	availWidth: number;              // screen.availWidth
+	availHeight: number;             // screen.availHeight
+	colorDepth: number;              // screen.colorDepth
+	pixelDepth: number;              // screen.pixelDepth
+	orientationType: string;         // screen.orientation.type
+	orientationAngle: number;        // screen.orientation.angle
+	maxTouchPoints: number;          // navigator.maxTouchPoints (0 if missing)
+	devicePixelRatio: number | undefined; // window.devicePixelRatio
+	colorGamutP3: boolean | 'unsupported';    // (color-gamut: p3) media query
+	prefersReducedMotion: boolean | 'unsupported';  // (prefers-reduced-motion: reduce)
+	prefersContrastMore: boolean | 'unsupported';   // (prefers-contrast: more)
+	forcedColorsActive: boolean | 'unsupported';    // (forced-colors: active)
+}
+```
+
+Returns `'unsupported'` if `screen` is not available.
+
+### `hardware` — Hardware properties
+
+**Tier:** core | **Sync:** yes | **APIs used:** `navigator`
+
+```ts
+// value shape:
+{
+	hardwareConcurrency: number;    // navigator.hardwareConcurrency (logical CPU cores)
+	deviceMemory: number | undefined; // navigator.deviceMemory (GB, may be undefined)
+	platform: string;               // navigator.platform
+	maxTouchPoints: number;         // navigator.maxTouchPoints
+}
+```
+
+Returns `'unsupported'` if `navigator` is not available.
+
+### `storage` — Storage API availability
+
+**Tier:** core | **Sync:** yes | **APIs used:** `localStorage`, `sessionStorage`, `indexedDB`, `openDatabase`, `navigator`
+
+```ts
+// value shape:
+{
+	cookiesEnabled: boolean;                     // navigator.cookieEnabled
+	localStorage: 'available' | 'blocked' | 'unsupported';    // write-read-delete probe
+	sessionStorage: 'available' | 'blocked' | 'unsupported';  // write-read-delete probe
+	indexedDb: 'available' | 'unsupported';                  // typeof indexedDB check
+	openDatabase: 'available' | 'unsupported';                // typeof openDatabase check (Web SQL)
+	pdfViewerEnabled: boolean;                               // navigator.pdfViewerEnabled
+}
+```
+
+### `fonts` — Font detection
+
+**Tier:** core | **Sync:** yes | **APIs used:** DOM (`document.createElement`, `offsetWidth`)
+
+```ts
+// value shape:
+{
+	detectedFonts: string[];  // sorted list of detected font family names
+	fontCount: number;         // count of detected fonts
+}
+```
+
+Tests 10 fonts against 3 generic families (monospace, sans-serif, serif) by rendering hidden `<span>` elements and measuring width differences. Returns `'unsupported'` if the DOM is not available.
+
+**Fonts probed:** `Arial`, `Helvetica Neue`, `Times New Roman`, `Georgia`, `Courier New`, `Trebuchet MS`, `Verdana`, `Tahoma`, `Impact`, `Comic Sans MS`
+
+### `canvas` — Canvas 2D fingerprint
+
+**Tier:** core | **Sync:** yes | **APIs used:** Canvas 2D (`getContext('2d')`)
+
+```ts
+// value shape:
+{
+	dataUrl: string;   // canvas.toDataURL() — base64 PNG of rendered pattern
+	winding: boolean;  // ctx.isPointInPath(1, 1, 'evenodd')
+}
+```
+
+Renders a 280×80 canvas with a filled rectangle (#f60), text ("Browser FP"), and an arc. Differences in GPU, driver, and browser anti-aliasing produce distinct fingerprints.
+
+Returns `'unsupported'` if the canvas 2D context is unavailable. Returns `'error'` if rendering throws.
+
+### `webgl` — WebGL fingerprint
+
+**Tier:** core | **Sync:** yes | **APIs used:** WebGL (`getContext('webgl')`, `WEBGL_debug_renderer_info`)
+
+```ts
+// value shape:
+{
+	vendor: string;                 // UNMASKED_VENDOR_WEBGL or VENDOR
+	renderer: string;               // UNMASKED_RENDERER_WEBGL or RENDERER
+	version: string;                // WebGL version string
+	shadingLanguageVersion: string; // GLSL version string
+	maxTextureSize: number;         // MAX_TEXTURE_SIZE
+	maxViewportDims: Int32Array;    // MAX_VIEWPORT_DIMS
+	extensions: string[];           // getSupportedExtensions() sorted
+}
+```
+
+Attempts `webgl` context first, falls back to `experimental-webgl`. Uses `WEBGL_debug_renderer_info` for unmasked GPU strings when available.
+
+Returns `'unsupported'` if canvas/WebGL is not available.
+
+### `audio` — AudioContext fingerprint
+
+**Tier:** core | **Sync:** no | **APIs used:** `OfflineAudioContext`, `OscillatorNode`, `DynamicsCompressorNode`
+
+```ts
+// value shape:
+{
+	sampleRate: number;     // rendered.sampleRate
+	length: number;         // rendered.length (number of sample frames)
+	signalValue: number;    // sum of absolute channel data values (6 decimal places)
+}
+```
+
+Creates an OfflineAudioContext (1 channel, 5000 samples, 44100 Hz), plays a 10 kHz triangle wave through a DynamicsCompressor with tuned parameters, then sums the absolute values of the rendered output. Different audio hardware/drivers produce distinct values.
+
+Returns `'unsupported'` if `OfflineAudioContext` (or `webkitOfflineAudioContext`) is not available. Returns `'blocked'` if rendering throws.
+
+---
+
+## Extended signals
+
+### `mediaDevices` — Media device enumeration
+
+**Tier:** extended | **Sync:** no | **APIs used:** `navigator.mediaDevices.enumerateDevices`
+
+```ts
+// value shape — an object keyed by MediaDeviceKind:
+{
+	audioinput: number;   // count of audio input devices
+	audiooutput: number;  // count of audio output devices
+	videoinput: number;   // count of video input devices
+}
+```
+
+Only device counts and kinds are collected — no device labels or IDs. Requires a secure context (HTTPS) and a visible document.
+
+Returns `'blocked'` if not in a secure context, if document is not visible, or if `enumerateDevices` throws. Returns `'unsupported'` if `mediaDevices` is not available.
+
+### `permissions` — Permissions API state
+
+**Tier:** extended | **Sync:** no | **APIs used:** `navigator.permissions.query`
+
+```ts
+// value shape:
+{
+	geolocation: 'granted' | 'denied' | 'prompt' | 'unsupported';
+	notifications: 'granted' | 'denied' | 'prompt' | 'unsupported';
+	camera: 'granted' | 'denied' | 'prompt' | 'unsupported';
+	microphone: 'granted' | 'denied' | 'prompt' | 'unsupported';
+}
+```
+
+Queries 4 permission names in parallel. Each individual query that fails returns `'unsupported'` for that key.
+
+Returns `'unsupported'` if `navigator.permissions` is not available. Returns `'blocked'` if all queries fail together.
+
+### `webrtc` — WebRTC codec capability
+
+**Tier:** extended | **Sync:** no | **APIs used:** `RTCPeerConnection`
+
+```ts
+// value shape:
+{
+	codecs: string[];   // sorted audio/video codec names from SDP rtpmap lines
+	extmaps: string[];  // sorted extmap IDs from SDP
+}
+```
+
+Creates an RTCPeerConnection, opens a data channel, generates an SDP offer, and parses supported codecs and extmap entries. The peer connection is closed after collection.
+
+Returns `'unsupported'` if `RTCPeerConnection` (or `webkitRTCPeerConnection`) is not available. Returns `'blocked'` if SDP negotiation throws.
+
+### `frameInfo` — Iframe context
+
+**Tier:** extended | **Sync:** yes | **APIs used:** DOM, `window.top`
+
+```ts
+// value shape:
+{
+	iframesCount: number;       // count of <iframe> elements in the document
+	isTopLevel: boolean;        // whether window === window.top
+	iframeDomains: string[];    // hostnames extracted from iframe src URLs
+}
+```
+
+Returns `'unsupported'` if `document` is not available. Returns `'error'` if enumeration throws.
+
+### `networkInfo` — Network Information
+
+**Tier:** extended | **Sync:** yes | **APIs used:** `navigator.connection` (vendor-prefixed)
+
+```ts
+// value shape:
+{
+	effectiveType: string | null;  // 'slow-2g' | '2g' | '3g' | '4g' | null
+	downlink: number | null;       // estimated downlink speed in Mbps
+	rtt: number | null;            // estimated round-trip time in ms
+	saveData: boolean | null;      // data-saver mode
+}
+```
+
+Checks `navigator.connection`, `navigator.mozConnection`, and `navigator.webkitConnection` for the NetworkInformation API (Chrome, Firefox, older WebKit).
+
+Returns `'unsupported'` if `navigator` or the connection API is not available.
+
+### `paymentSupport` — PaymentRequest API
+
+**Tier:** extended | **Sync:** yes | **APIs used:** `window.PaymentRequest`
+
+```ts
+// value shape:
+{
+	paymentRequest: boolean;  // whether PaymentRequest constructor exists
+}
+```
+
+### `referrerInfo` — Document referrer
+
+**Tier:** extended | **Sync:** yes | **APIs used:** `document.referrer`
+
+```ts
+// value shape:
+{
+	referrer: string;  // document.referrer (empty string if no referrer)
+}
+```
+
+Returns `'unsupported'` if `document` is not available.
+
+### `navigationInfo` — Navigation type
+
+**Tier:** extended | **Sync:** yes | **APIs used:** `PerformanceNavigationTiming`
+
+```ts
+// value shape:
+{
+	navigationType: string | number | null;
+	// 'navigate' | 'reload' | 'back_forward' | 'prerender' (modern)
+	// 0 | 1 | 2 | 255 (legacy performance.navigation.type)
+}
+```
+
+Prefers `PerformanceNavigationTiming.type`. Falls back to deprecated `performance.navigation.type` in older browsers.
+
+Returns `'unsupported'` if `performance` is not available. Returns `'error'` if probing throws.
+
+### `riskSignals` — Bot and headless detection
+
+**Tier:** extended | **Sync:** no | **APIs used:** `navigator`, `Notification`, `Permissions`, `Performance`
+
+```ts
+// value shape:
+{
+	webdriver: boolean | null;           // navigator.webdriver flag
+	headlessHints: string[];             // detected headless indicators
+	uaConsistency: boolean | null;       // UA platform vs UA-CH consistency
+	notificationPermission: string | null; // Notification.permission
+	permissionsHeadlessHint: boolean | null; // denied+default mismatch
+	timeToCaptureMs: number | null;      // ms since navigation start
+}
+```
+
+#### Headless hints checked
+
+| Hint code | Trigger |
+|-----------|---------|
+| `headless-ua` | UA contains `"HeadlessChrome"` |
+| `missing-chrome-object` | Chrome UA but `window.chrome` is not an object |
+| `zero-outer-dimensions` | `outerWidth === 0` or `outerHeight === 0` |
+| `no-plugins-on-desktop-chrome` | Chrome UA (non-mobile) but `navigator.plugins` is empty |
+| `empty-languages` | `navigator.languages` is an empty array |
+
+Returns `'unsupported'` if `navigator` is not available. Returns `'blocked'` if collection throws.

package/package.json

@@ -1,75 +1,78 @@
 {
-    "name": "@ianmenethil/zp-devicefp",
-    "version": "0.1.0-alpha.1",
-    "description": "Async-first browser and device fingerprinting library with explainable signals and anomaly scoring.",
-    "type": "module",
-    "main": "./dist/npm/index.cjs",
-    "module": "./dist/npm/index.mjs",
-    "types": "./dist/npm/index.d.ts",
-    "sideEffects": false,
-    "exports": {
-        ".": {
-            "types": "./dist/npm/index.d.ts",
-            "import": "./dist/npm/index.mjs",
-            "require": "./dist/npm/index.cjs",
-            "default": "./dist/npm/index.mjs"
-        }
-    },
-    "files": [
-        "dist",
-        "README.md",
-        "LICENSE",
-        "docs"
-    ],
-    "packageManager": "bun@1.3.9",
-    "engines": {
-        "bun": ">=1.3.0",
-        "node": ">=22"
-    },
-    "prepublishOnly": "bun run build",
-    "scripts": {
-        "build": "bun run check && bun run test:coverage && bun -e \"await import('./.scripts/build.ts')\"",
-        "test": "bun test",
-        "test:coverage": "bun test --coverage",
-        "release": "sh -c 'V=$(npm version \"${1:-minor}\" -m \"chore: release %s\" | tail -1 | sed s/v//) && bun publish --access public && mkdir -p \"F:/_ZP-Main/apps/CDN-server/public/devicefp/$V\" && cp -r dist/cdn/* \"F:/_ZP-Main/apps/CDN-server/public/devicefp/$V/\" && mkdir -p \"F:/_ZP-Main/apps/CDN-server/public/devicefp/latest\" && cp -r dist/cdn/* \"F:/_ZP-Main/apps/CDN-server/public/devicefp/latest/\" && git push --follow-tags' --",
-        "smoke": "bun run scripts/smoke.mjs",
-        "check": "bun run lint && bun run typecheck && bun run knip && bun run jscpd",
-        "lint": "eslint . --config eslint.config.js",
-        "typecheck": "tsc -p tsconfig.json --noEmit",
-        "knip": "knip --config knip.json",
-        "jscpd": "jscpd --config .jscpd.json",
-        "format": "prettier --write .",
-        "format:check": "prettier --check ."
-    },
-    "keywords": [
-        "browser",
-        "device",
-        "fingerprint",
-        "typescript",
-        "fraud",
-        "risk"
-    ],
-    "author": "Ian / Zenith Payments",
-    "license": "MIT",
-    "homepage": "https://github.com/ianmenethil/zp-devicefp#readme",
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/ianmenethil/zp-devicefp.git"
-    },
-    "bugs": {
-        "url": "https://github.com/ianmenethil/zp-devicefp/issues"
-    },
-    "devDependencies": {
-        "@eslint/js": "^10.0.1",
-        "esbuild": "^0.28.0",
-        "eslint": "^10.3.0",
-        "eslint-plugin-tsdoc": "^0.5.2",
-        "javascript-obfuscator": "^5.4.2",
-        "jscpd": "^4.2.0",
-        "knip": "^6.13.1",
-        "lefthook": "^2.1.6",
-        "prettier": "^3.8.3",
-        "typescript": "~6.0.3",
-        "typescript-eslint": "^8.59.3"
+  "name": "@ianmenethil/zp-devicefp",
+  "version": "0.1.0",
+  "description": "Async-first browser and device fingerprinting library with explainable signals and anomaly scoring.",
+  "type": "module",
+  "main": "./dist/npm/index.cjs",
+  "module": "./dist/npm/index.mjs",
+  "types": "./dist/npm/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/npm/index.d.ts",
+      "import": "./dist/npm/index.mjs",
+      "require": "./dist/npm/index.cjs",
+      "default": "./dist/npm/index.mjs"
     }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "docs"
+  ],
+  "packageManager": "bun@1.3.9",
+  "engines": {
+    "bun": ">=1.3.0",
+    "node": ">=22"
+  },
+  "prepublishOnly": "bun run build",
+  "scripts": {
+    "build": "bun run check && bun run test:coverage && bun -e \"await import('./.scripts/build.ts')\"",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "release": "sh -c 'V=$(npm version \"${1:-minor}\" -m \"chore: release %s\" | tail -1 | sed s/v//) && bun publish --access public && rm -rf \"F:/_ZP-Main/apps/CDN-server/public/devicefp\" && mkdir -p \"F:/_ZP-Main/apps/CDN-server/public/devicefp/$V\" && cp -r dist/cdn/* \"F:/_ZP-Main/apps/CDN-server/public/devicefp/$V/\" && mkdir -p \"F:/_ZP-Main/apps/CDN-server/public/devicefp/latest\" && cp -r dist/cdn/* \"F:/_ZP-Main/apps/CDN-server/public/devicefp/latest/\" && git push --follow-tags' --",
+    "release:minor": "bun run release minor",
+    "release:patch": "bun run release patch",
+    "release:major": "bun run release major",
+    "smoke": "bun run scripts/smoke.mjs",
+    "check": "bun run lint && bun run typecheck && bun run knip && bun run jscpd",
+    "lint": "eslint . --config eslint.config.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "knip": "knip --config knip.json",
+    "jscpd": "jscpd --config .jscpd.json",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "keywords": [
+    "browser",
+    "device",
+    "fingerprint",
+    "typescript",
+    "fraud",
+    "risk"
+  ],
+  "author": "Ian / Zenith Payments",
+  "license": "MIT",
+  "homepage": "https://github.com/ianmenethil/zp-devicefp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ianmenethil/zp-devicefp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ianmenethil/zp-devicefp/issues"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "esbuild": "^0.28.0",
+    "eslint": "^10.3.0",
+    "eslint-plugin-tsdoc": "^0.5.2",
+    "javascript-obfuscator": "^5.4.2",
+    "jscpd": "^4.2.0",
+    "knip": "^6.13.1",
+    "lefthook": "^2.1.6",
+    "prettier": "^3.8.3",
+    "typescript": "~6.0.3",
+    "typescript-eslint": "^8.59.3"
+  }
 }