# fingerprintjs-risk-signal-lab

A defensive lab for normalizing browser risk signals and turning them into explainable server-side decisions.

This project is useful for teams that use FingerprintJS or similar visitor-identification signals and want a cleaner contract between the client, backend, and abuse-prevention logic.

It is not affiliated with FingerprintJS.

## What It Includes

- A small normalization layer for common visitor and risk fields.
- An explainable scoring function with low, medium, and high tiers.
- Fixtures for clean, review, and block decisions.
- A Worker-style example for server-side gating.
- Privacy notes for keeping risk signals narrow and purposeful.

## Quick Start

```bash
npm install
npm test
npm run score:fixtures
```

## Example

```js
import { scoreRisk } from './src/risk-score.mjs';

const decision = scoreRisk({
  visitorId: 'visitor_123',
  requestId: 'request_123',
  timestamp: new Date().toISOString(),
  confidenceScore: 0.91,
  botDetected: false,
  velocity: { requestsInWindow: 3, windowSeconds: 300 }
});

console.log(decision.action);
```

## Decision Model

- `low`: allow with logging.
- `medium`: ask for step-up verification.
- `high`: block or send to manual review.

The scoring weights are intentionally simple so teams can see why a decision happened and adapt the thresholds to their own threat model.

## Security

Please report security issues to `security@mirogate.com`. See `SECURITY.md`.