Skip to content

Commit fdc438a

Browse files
committed
feat: add tamper evidence collector and related functionality
- Implemented `createTamperEvidenceCollector` to assess browser tampering risks. - Added `evaluateTamperEvidence` function to analyze various indicators of tampering. - Introduced `createStabilityMonitor` for tracking component drift in identity verification. - Created `USE_CASE_PRESETS` for managing different privacy and risk profiles. - Developed `createExplainableReport` to generate detailed reports on identity and risk assessments. - Implemented replay protection mechanisms in `createReplayToken` and `verifyReplayToken`. - Added network risk evaluation capabilities with `evaluateNetworkRisk` and static network adapter. - Comprehensive test suite for tamper evidence, stability monitoring, and replay protection. - Defined TypeScript types for server-related functionalities.
1 parent 30d0a76 commit fdc438a

37 files changed

Lines changed: 3547 additions & 36 deletions

README.md

Lines changed: 48 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
[![Build](https://img.shields.io/badge/build-verified-brightgreen)](.github/workflows/ci.yml)
44
[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](package.json)
5-
[![Browser Bundle](https://img.shields.io/badge/browser%20bundle-%3C55KB-blue)](scripts/check-size.mjs)
5+
[![Browser Bundle](https://img.shields.io/badge/browser%20bundle-%3C65KB-blue)](scripts/check-size.mjs)
66
[![Runtime](https://img.shields.io/badge/runtime-no%20production%20deps-success)](package.json)
77
[![BotBlocker Security](https://img.shields.io/badge/BotBlocker-Security-0f766e)](https://botblocker.top)
88

@@ -27,6 +27,7 @@ Package entry points:
2727
- `@botblocker/fingerprintjs`
2828
- `@botblocker/fingerprintjs/collectors`
2929
- `@botblocker/fingerprintjs/policy`
30+
- `@botblocker/fingerprintjs/server`
3031
- `@botblocker/fingerprintjs/storage`
3132

3233
Each package entry supports ESM `import` and CommonJS `require`. Browser builds expose the `FingerprintJSBotBlocker` global.
@@ -38,7 +39,7 @@ import { hashComponents, loadClient } from '@botblocker/fingerprintjs';
3839

3940
const client = await loadClient({
4041
namespace: 'my-product',
41-
profile: 'extended',
42+
useCase: 'fraud-defense',
4243
storage: 'local',
4344
identity: {
4445
denyCollectors: ['browser.botDetection', 'browser.privacyMode'],
@@ -75,6 +76,36 @@ const client = createClient({
7576
});
7677
```
7778
79+
## Backend Verification
80+
81+
The server package adds replay protection, server-only hashing, result verification, and network risk adapters. It is intended for backend use and is not included in the browser global bundle.
82+
83+
```js
84+
import {
85+
createMemoryReplayStore,
86+
createReplayToken,
87+
verifyFingerprintResult
88+
} from '@botblocker/fingerprintjs/server';
89+
90+
const replayStore = createMemoryReplayStore();
91+
const replayToken = await createReplayToken({
92+
secret: process.env.FINGERPRINT_SERVER_SECRET,
93+
purpose: 'login-risk'
94+
});
95+
96+
const verification = await verifyFingerprintResult(resultFromBrowser, {
97+
secret: process.env.FINGERPRINT_SERVER_SECRET,
98+
replayToken,
99+
replayStore,
100+
network: { ip: request.ip },
101+
networkAdapter: yourIpRiskAdapter
102+
});
103+
104+
if (!verification.ok || verification.network?.verdict === 'high_risk_network') {
105+
// Increase friction, deny the request, or send the event to BotBlocker Security.
106+
}
107+
```
108+
78109
## Script-Tag Usage
79110
80111
```html
@@ -114,6 +145,7 @@ Core signal groups:
114145
115146
- Runtime: browser runtime, client hints, navigator properties, API feature support, CSS feature support, performance memory diagnostics, Node runtime.
116147
- Risk: bot/automation evidence, browser inconsistency evidence, and private-mode indicators.
148+
- Integrity: tamper evidence for patched browser APIs and inconsistent runtime claims.
117149
- Locale: language, calendar, numbering system, timezone, offset.
118150
- Display: screen metrics, screen frame, media preferences.
119151
- Hardware: concurrency, memory, touch support, architecture byte pattern.
@@ -127,6 +159,8 @@ Core signal groups:
127159
128160
Bot detection is evidence-based. Strong signals such as WebDriver exposure, known automation globals, headless user agents, and impossible browser dimensions increase the score. Weaker inconsistencies such as language mismatches, impossible hardware ranges, plugin structure anomalies, patched permissions APIs, and empty Chromium globals are reported as evidence without being treated as proof by themselves.
129161
162+
Tamper evidence is also evidence-based. `browser.tamperEvidence` reports patched native APIs, platform/client-hints mismatches, zero screen dimensions, suspicious language lists, and patched canvas serialization. It is report-only by default and should be combined with server verification before enforcement.
163+
130164
Private-mode detection is intentionally conservative. Modern browsers do not expose a universal incognito flag, so `browser.privacyMode` reports likelihood, score, confidence, and evidence from storage availability, IndexedDB behavior, quota estimates, and persistence state.
131165
132166
## Privacy Profiles
@@ -137,6 +171,15 @@ Private-mode detection is intentionally conservative. Modern browsers do not exp
137171
138172
Policy controls include consent gates, sensitivity limits, active collector permission, allow/deny lists, category filters, and optional value redaction.
139173
174+
Use-case presets are available through `useCase` or `createUseCasePreset()`:
175+
176+
- `privacy-first`
177+
- `analytics-lite`
178+
- `login-risk`
179+
- `checkout-risk`
180+
- `bot-defense`
181+
- `fraud-defense`
182+
140183
Identity controls are separate from policy controls:
141184
142185
- `identity.includeNonHashable`: include report-only components in the hash for diagnostics or custom deployments.
@@ -155,6 +198,8 @@ The browser demo in [examples/browser.html](examples/browser.html) renders two r
155198
156199
Both reports include all collected capabilities and calculation data. Use the `extended` profile in the demo to exercise the full collector pack and confirm that report-only changes do not move the stable visitor ID.
157200
201+
The debug inspector in [examples/inspector.html](examples/inspector.html) accepts an `IdentifyResult` or full demo report JSON and explains identity components, report-only components, tamper, bot, and private-mode evidence.
202+
158203
## Verification
159204
160205
`npm run verify` runs the full quality gate:
@@ -163,7 +208,7 @@ Both reports include all collected capabilities and calculation data. Use the `e
163208
- declaration validation through TypeScript;
164209
- Node tests with 100% line, branch, and function coverage for `src/**/*.js`;
165210
- Playwright browser tests in Chromium, Firefox, and WebKit;
166-
- minified browser bundle size gate under 55 KB.
211+
- minified browser bundle size gate under 65 KB.
167212
168213
Additional docs:
169214

0 commit comments

Comments
 (0)