@ianmenethil/zp-devicefp 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,134 @@
+# 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.
+
+## Install
+
+```bash
+bun add @ianmenethil/zp-devicefp
+```
+
+```ts
+import { createFingerprintClient } from '@ianmenethil/zp-devicefp';
+```
+
+## Package contents
+
+```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/
+```
+
+## 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).
+
+| 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` |
+
+- **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`.
+
+### CDN usage
+
+```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();
+</script>
+```
+
+## Public API
+
+```ts
+import { createFingerprintClient } from '@ianmenethil/zp-devicefp';
+
+const client = await createFingerprintClient({
+  timeoutMs: 1500,
+  extended: false,
+});
+
+const result = await client.collect();
+console.log(result.thumbprint, result.antiSpoof);
+console.log(result.diagnostics);
+```
+
+`collectSync()` intentionally returns a partial fingerprint that only uses sync-safe collectors.
+
+Each result also includes:
+
+- `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
+
+## Signals
+
+Core tier:
+
+`ua` · `uaHints` · `locale` · `screen` · `hardware` · `storage` · `fonts` · `canvas` · `webgl` · `audio`
+
+Extended tier:
+
+`mediaDevices` · `permissions` · `webrtc` · `frameInfo` · `networkInfo` · `paymentSupport` · `referrerInfo` · `navigationInfo` · `riskSignals`
+
+## Design choices
+
+- 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.
+
+## Build and test
+
+```bash
+bun install
+bun run build       # lint → typecheck → knip → jscpd → tests + coverage → esbuild → CDN deploy
+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
+
+- 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.
+
+## 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/)
+```