🧬 VeriPrint

Capture the digital signature of every device through high-entropy signal fusion and advanced spoof detection.
Transform raw system data into trust — fast, local, and intelligent.
Empower your application to detect, verify, and outmaneuver deception.
No cloud. No black box. Just signal, logic, and truth.

🖇 Features

• 🔍 High-Entropy Signal Fusion — Combine dozens of device attributes for maximum uniqueness
• 🛡️ Advanced Spoof Detection — Identify and mitigate spoofing and fingerprint manipulation attempts
• ⚡ Fast Local Processing — Entirely offline signal processing for real-time performance and full control
• 🔧 Modular Signal Plugins — Enable or disable specific signal modules as needed
• 🔬 Stability Enhancer — Reduce fingerprint volatility across sessions
• 📦 Zero-Cloud Design — No external dependencies or telemetry
• 🔗 Structured Signature Output — Clean, canonicalized output for storage and matching

📎 Use Cases

• Device verification for login or transaction flows
• Bot detection and session integrity checks
• Fraud prevention and identity intelligence
• Anonymous user tracking without cookies
• Embedded trust anchors in local apps
• Analytics (User / Anonymous)

🌍 System Requirements

VeriPrint currently runs in the browser only. Server-side support (Node.js) is planned.

| Requirement | Version / Support | |------------------|-------------------------------| | Browser | Chrome, Firefox, Safari, Edge | | Environment | Modern browsers (ES2020+) | | Platform | Fully client-side, no server required |

📜 API Specifications

⚙️ Configurations Overview

Use these options to control versioning, salt persistence, and private-mode behavior.

new VeriPrint(options)

| Option | Type | Default | Purpose | |--------------------------|--------|-------------|-----------------------------------------------------------------------------------------| | veriPrintVersionID | string | "vp-id-1" | Tag embedded in the hashed payload; bump when your signal schema/normalizer changes. | | printStorageConfigurations | object | { preferLocalOverIDB:false, privateScoreThreshold:0.5, probeCacheTTL:2000 } | Pass-through options for VeriPrint storage. |

Example

const veri = new VeriPrint({
  veriPrintVersionID: "vp-id-2",
  printStorageConfigurations: {
    preferLocalOverIDB: false, // try IndexedDB before localStorage
    privateScoreThreshold: 0.5, // ≥ threshold => treated as private/incognito
    probeCacheTTL: 2000         // cache probe result (ms) to avoid repeated checks
  }
});

---

### 🔧 Storage Options

These control the creation / persistance of salts and the detection of private mode.

| Option                 | Type    | Default | Purpose                                                                 |
|------------------------|---------|---------|-------------------------------------------------------------------------|
| `preferLocalOverIDB`   | boolean | false   | Choose persistence order. |
| `privateScoreThreshold`| number  | 0.5     | Flags session private and disables salt once score reaches threshold. |
| `probeCacheTTL`        | number  | 2000    | Caches storage/private probe result for the given duration (ms). |

### Behavior summary
- **Private/incognito** (score ≥ threshold): `{ salt:null, tier:"none" }` → hash excludes salt.  
- **Normal**: salt persists in **IDB** or **localStorage** only → prints remain stable across browser restarts.  
- **If neither** IDB nor localStorage works, system omits salt to prevent churn.  

---

## 📦 Methods

| Method                         | Description                                                                 | Async |
|--------------------------------|-----------------------------------------------------------------------------|:-----:|
| `generate(options)`            | Captures a full fingerprint and returns hash, raw, normalized, and optionally flattened signals. | ✅     |
| `compare(a, b)`                | Compares two fingerprints and returns a confidence score and changed keys. | ✅     |
| `detectSpoofedPrint(print)`   | Analyzes a fingerprint and returns spoof score and spoof alerts.           | ✅     |
| `addSignal(name, fn)`         | Registers a custom async signal function under the specified name.         | ❌     |
| `removeSignal(name)`          | Removes a registered signal by name.                                       | ❌     |
| `useHashFunction(fn)`         | Replaces the internal hashing function.                                    | ❌     |
| `useNormalizer(fn)`           | Replaces the internal normalizer function.                                 | ❌     |
| `usePlugin(plugin)`           | Registers a plugin containing `name` and `collect()` method.               | ❌     |

---

## 🧬 Methods Overview

### 🔧 `generate(options)`

Captures a fingerprint using the configured signal modules.

#### Options

| Option              | Description                                               | Default         |
|---------------------|-----------------------------------------------------------|-----------------|
| `includeFlattened`  | Whether to include a flattened view of signal data        | `false`         |

#### Output

```js
{
     veriPrint     : "7a45fbd123ab...",
     rawData       : { ... },
     normalized    : { ... },
     flattened     : { ... } // only if requested
}

🔁 compare(inputPrint, comparisonPrint)

Returns a confidence score and changed signal keys between two fingerprints.

const result = await veri.compare(print1, print2);

console.log(result.confidence);     // 0.85
console.log(result.changedKeys);    // [ "gpu.vendor", "canvas.hash" ]

🛡️ detectSpoofedPrint(print)

Runs a spoof analysis on a given fingerprint.

const result = await veri.detectSpoofedPrint(print);

console.log(result.spoofScore);     // 85
console.log(result.alerts);         // [ "canvas hash mismatch", "mediaDevices missing" ]

🔌 addSignal(name, asyncFn)

Registers a custom signal generator.

veri.addSignal("myCustomID", async () => {
     return navigator.hardwareConcurrency + "-" + Math.random();
});

🔬 Signal Sources (Browser)

| Signal | Source Description | |---------------|-------------------------------------------| | User-Agent | Browser + platform string | | Screen | Resolution, color depth | | Timezone | Local timezone offset | | WebGL | GPU vendor + renderer + capabilities | | Canvas | toDataURL hash of canvas render | | AudioContext | Audio processing fingerprint | | mediaDevices | Microphone & camera device count | | Fonts | Installed fonts (detectable ones) | | Plugins | Browser plugin list (legacy) |

🧱 Installation

npm install @trap_stevo/veriprint

🚀 Getting Started

import VeriPrint from "@trap_stevo/veriprint";

const veri = new VeriPrint();

veri.generate({ includeFlattened: true }).then((print) =>  {
     console.log("veriID:", print.veriPrint);
     console.log("flattened:", print.flattened);
     console.log("raw signals:", print.rawData);
});

⚙️ Configuration Example

veri.useHashFunction(myCustomHasher);
veri.useNormalizer(myCustomNormalizer);
veri.addSignal("hardwareHash", async () => getHardwareHash());

🧠 Philosophy

Fingerprinting empowers developers — not the cloud.

VeriPrint gives you full visibility and control over identity. You collect, normalize, and verify signals without relying on remote servers or black-box APIs.

✨ License

See License in LICENSE.md

🧬 From Signal to Truth

VeriPrint captures what a device reveals — not what it claims. You extract its unique behavioral fingerprint through direct observation, turning ambient signals into actionable truth.