@vd7/fingerprinter

Browser fingerprinting utility — collect device/browser signals, hash, persist, and optionally send to a webhook. Framework-agnostic core with an optional React component.

Use cases: analytics, fraud detection, consent-aware visitor tracking, rate limiting by device.

Install

npm install @vd7/fingerprinter
# or from local path during development
npm install file:../fingerprinter

Core (any environment)

import { run, hasBeenCaptured, collect } from "@vd7/fingerprinter";

// One-shot: collect, send to webhook, mark as captured (skips if already captured)
const payload = await run({
  storageKey: "my_app_fp",
  webhookUrl: "https://your-endpoint.com/fp",
  onCollect: (p) => console.log("Collected", p.uniqueId),
});

// Or just collect without sending or persisting
const { payload, hash, uniqueId } = await collect();

// Check if this browser was already captured
if (hasBeenCaptured("my_app_fp")) { ... }

React

import { Fingerprint } from "@vd7/fingerprinter/react";

<Fingerprint
  storageKey="my_app_fp"
  webhookUrl="https://your-endpoint.com/fp"
  autoRunDelay={1500}
  showToast={true}
  toastMessage="Fingerprint captured"
/>

Runs collection on first interaction (mouse/touch) or after autoRunDelay ms. Shows an optional toast when done. No UI until then (invisible trigger layer).

Config

| Option | Description | |--------|-------------| | storageKey | localStorage/sessionStorage key for "already captured". Default vd7_fp_captured. | | webhookUrl | POST URL to send the JSON payload to. Omit to skip sending. | | webhookHeaders | Extra headers (e.g. Authorization). | | onCollect | Callback with full payload after collection. |

Payload shape

Includes: timestamp, page, path, referrer, trafficSource, UTM params, userAgent, platform, browser, os, language, screenResolution, viewport, timezone, fingerprintHash, uniqueId, canvas/audio hashes, GPU info, fonts, plugins, etc. See FingerprintPayload in TypeScript types.

Registry & landscape

• registry/fingerprint-manifest.json — Exhaustive list of every probe (implemented, todo, research). Single source of truth for “what we can collect.” Each entry: id, category, status, apiOrMethod, entropy, fastFail, payloadKey. Aligned with $PATTERNSJSON (resilience.shotgun_fallback, registry_rules, single_source_of_truth). See _meta._cross_references in the manifest.
• docs/LANDSCAPE.md — Full landscape: approach (probe aggressively, fast-fail, grab everything), horizon (client-side vs out-of-scope), and how to use the manifest to implement more probes.

Goal: enterprise-grade, best-of-everything fingerprinter; the manifest is the todo/backlog and the landscape doc is the map.

License

MIT