@wocha/fingerprint

Browser-only fingerprint SDK for the Wocha authentication platform. Collects device and browser signals, runs lightweight bot detection, and produces an encrypted payload for the risk engine.

Privacy-preserving: no cookies, no localStorage, no cross-site identifiers, and no PII beyond what the auth flow already collects.

Install

npm install @wocha/fingerprint

Quick start

import {
  collectFingerprint,
  attachToForm,
  initAutoCollect,
} from "@wocha/fingerprint";

const config = {
  publicKey: "<tenant-rsa-public-key-spki-base64>",
  geoCountry: "GB", // optional, for timezone/locale mismatch checks
};

// Option 1: manual collection
const payload = await collectFingerprint(config);
attachToForm(document.querySelector("form")!, payload);

// Option 2: auto-attach to all forms on auth pages
initAutoCollect(config);

API

| Function | Description | |----------|-------------| | collectFingerprint(config) | Collect signals, detect bots, encrypt, and return FingerprintPayload | | attachToForm(form, payload) | Inject hidden __wocha_fp field into a form | | createHeaderValue(payload) | Base64-encode payload for X-Wocha-Fingerprint header | | createMiddleware(config) | Returns a fetch wrapper that adds the fingerprint header | | initAutoCollect(config) | Auto-bind fingerprint collection to all page forms |

Payload shape

interface FingerprintPayload {
  version: 1;
  timestamp: number;
  fingerprint_hash: string; // SHA-256 of canonical signal JSON
  signals: string;          // AES-GCM envelope encrypted with tenant RSA public key
  bot_score: number;        // 0–1 preliminary bot assessment
  bot_reasons: string[];    // e.g. ["webdriver_detected", "headless_browser"]
}

Signals are encrypted with a hybrid scheme: AES-256-GCM for the payload, RSA-OAEP (SHA-256) for the ephemeral AES key. The fingerprint_hash is computed separately so the server can perform device trust lookups without decryption.

Bot detection

The SDK runs client-side heuristics before submission:

| Signal | Weight | |--------|--------| | navigator.webdriver === true | 0.9 | | Automation globals (__selenium, callPhantom, etc.) | 0.9 | | Chrome with zero plugins | 0.3 | | Known headless canvas fingerprint | 0.5 | | Impossible screen resolution | 0.4 | | Form fill time < 500ms | 0.6 | | No mouse/touch/keyboard events | 0.4 | | Timezone mismatch with geo | 0.2 | | Language mismatch with geo | 0.2 |

HTTP header integration

import { collectFingerprint, createHeaderValue } from "@wocha/fingerprint";

const payload = await collectFingerprint(config);
await fetch("/api/auth/login", {
  method: "POST",
  headers: {
    "X-Wocha-Fingerprint": createHeaderValue(payload),
  },
  body: JSON.stringify({ email, password }),
});

Or use the middleware helper:

import { createMiddleware } from "@wocha/fingerprint";

const fpFetch = createMiddleware(config);
await fpFetch("/api/auth/login", { method: "POST", body });

Requirements

• Modern browser with Web Crypto API (SubtleCrypto)
• ES2020+
• Tenant RSA public key in SPKI DER format (base64)

License

Apache-2.0