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

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.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 && 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.1.1",
-        "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"
+  }
 }