better-auth-fingerprint

Fingerprint plugin for Better Auth - device fingerprinting for fraud prevention and abuse detection.

Features

• Lightweight browser fingerprint generation using stable Web APIs (no external dependencies)
• Deterministic SHA-256 hashing of fingerprint data
• Optional double-hashing (client + server) for added security
• Automatic fingerprint attachment to authentication flows (sign-up, sign-in, session creation)
• User fingerprint linking for abuse tracking and analysis
• Configurable abuse detection rules (e.g. max accounts per fingerprint)
• Flexible enforcement modes: log (monitor only), soft (rate limit/warn), hard (block)
• Risk scoring system (0-100) to evaluate suspicious behavior patterns
• Middleware integration for seamless use with auth lifecycle
• Event hooks: onFingerprintCreated, onRiskDetected, onLimitExceeded, onUserFlagged
• Support for database adapters (Prisma, Drizzle, and generic SQL)
• Client-side helper utilities: getFingerprint, withFingerprint
• Optional debug mode for development
• Privacy-first design (no raw device data stored, only hashed fingerprints)
• Configurable opt-out support
• Minimal performance overhead
• Abuse analytics support

Installation

npm install better-auth-fingerprint

Server Usage

import { betterAuth } from "better-auth";
import { fingerprint } from "better-auth-fingerprint";

export const auth = betterAuth({
  database: /* your database adapter */,
  plugins: [
    fingerprint({
      trustedDevicesMax: 5,
      autoRemoveOldDevices: true,
      enforcementMode: "soft",
      enableDoubleHashing: false,
      maxAccountsPerFingerprint: 3,
      riskThreshold: 50,
      enableDebug: false,
      allowOptOut: false,
      trackAbuseAnalytics: false,
      hooks: {
        onFingerprintCreated: async (ctx) => {
          console.log("Fingerprint created:", ctx.fingerprint?.fingerprintId);
        },
        onRiskDetected: async (ctx) => {
          console.log("Risk detected:", ctx.riskScore?.score);
        },
        onLimitExceeded: async (ctx) => {
          console.log("Limit exceeded for user:", ctx.userId);
        },
        onUserFlagged: async (ctx) => {
          console.log("User flagged:", ctx.userId, ctx.reason);
        },
      },
    }),
  ],
});

Client Usage

import { createAuthClient } from "better-auth";
import { fingerprintClient, getFingerprint } from "better-auth-fingerprint/client";

const authClient = createAuthClient({
  baseURL: "http://localhost:3000",
  plugins: [fingerprintClient()],
});

// Get browser fingerprint
const fp = await getFingerprint();

// Use with auth operations
await authClient.signIn.signIn({
  email: "[email protected]",
  password: "password",
  // Fingerprint is automatically attached via plugin middleware
});

Risk Scoring

The plugin calculates a risk score (0-100) based on multiple factors:

• new_fingerprint (15pts) - New device not seen before
• multiple_accounts (25pts) - Multiple accounts from same fingerprint
• rapid_signups (30pts) - Rapid account creation
• unusual_location (20pts) - IP address change
• suspicious_user_agent (10pts) - Automated/bot user agents
• known_abuse_marker (40pts) - Previously flagged device
• device_mismatch (35pts) - Fingerprint mismatch

Risk levels:

• low: 0-19
• medium: 20-49
• high: 50-74
• critical: 75-100

Enforcement Modes

| Mode | Behavior | |------|----------| | log | Monitor only, log violations | | soft | Allow with warning, rate limit | | hard | Block requests exceeding threshold |

API Endpoints

| Endpoint | Method | Description | |----------|--------|-------------| | /fingerprint/validate | POST | Validate fingerprint | | /fingerprint/list | GET | List user fingerprints | | /fingerprint/delete | POST | Delete fingerprint | | /fingerprint/flag | POST | Flag fingerprint |

TypeScript Types

import type {
  FingerprintOptions,
  FingerprintData,
  FingerprintInput,
  RiskScore,
  EnforcementMode,
  FingerprintHooks,
  FingerprintClientPlugin,
} from "better-auth-fingerprint";

License

MIT !!! You are free to do whatever you want with it ;)