@ianmenethil/zp-devicefp 0.1.0-alpha.0

package/docs/architecture.md

@@ -0,0 +1,40 @@
+# 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.

package/docs/privacy.md

@@ -0,0 +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.

package/docs/testing.md

@@ -0,0 +1,32 @@
+# Testing
+
+The project uses Node 24's built-in TypeScript execution and test runner.
+
+## Coverage intent
+
+The included tests focus on:
+
+- deterministic canonicalization
+- stable hashing
+- anomaly scoring
+- storage and WebRTC collector behavior
+- audio and media-device collector behavior
+- client sync collection
+- parallel async collection
+- abort and timeout paths
+- warning isolation between runs
+- upload plumbing
+- built-artifact smoke loading
+
+## Run locally
+
+```bash
+node --test ./tests/**/*.test.ts
+node ./scripts/build.mjs
+```
+
+## Suggested next expansion
+
+- Add browser-matrix tests in Playwright for Chromium, Firefox, and WebKit.
+- Add snapshot tests for collector outputs in privacy-hardened environments.
+- Add server-side reconciliation tests once an API consumer is introduced.

package/package.json

@@ -0,0 +1,75 @@
+{
+    "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"
+    }
+}