@cloudglides/veil 0.1.0 → 0.1.1

package/.github/workflows/build-on-tag.yml

@@ -78,3 +78,5 @@ jobs:
             dist/veil_core_bg.wasm
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+

package/.github/workflows/deploy-pages.yml

@@ -0,0 +1,73 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches:
+      - master
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: pnpm/action-setup@v2
+        with:
+          version: 8
+      
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+      
+      - uses: dtolnay/rust-toolchain@stable
+      
+      - name: Install wasm-pack
+        run: curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
+      
+      - name: Install dependencies
+        run: pnpm install
+      
+      - name: Build WASM
+        run: pnpm run build:wasm
+      
+      - name: Build
+        run: pnpm run build
+        env:
+          # Add this if you need base path configuration
+          VITE_BASE_PATH: /veil/
+      
+      - name: Copy dist to example
+        run: |
+          cp -r dist/* example/
+          touch example/.nojekyll
+      
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+      
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: 'example'
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+
+

package/README.md

@@ -0,0 +1,190 @@
+# Veil
+
+A deterministic browser fingerprinting library with mathematical rigor and tamper detection.
+
+## Features
+
+- **Deterministic Hashing** - Consistent fingerprints across browser refreshes
+- **Mathematical Rigor** - Information-theoretic entropy sources with Bayesian scoring
+- **Tamper Detection** - Identifies suspicious patterns and anomalies in entropy data
+- **Browser Compatible** - Works in modern browsers via WASM
+- **Minimal Overhead** - Lightweight library with no external dependencies
+- **Detailed Metrics** - Uniqueness, confidence, and per-source entropy analysis
+
+## Installation
+
+```bash
+npm install @cloudglides/veil
+# or
+pnpm add @cloudglides/veil
+```
+
+## Quick Start
+
+```javascript
+import { getFingerprint } from "@cloudglides/veil";
+
+// Simple hash
+const hash = await getFingerprint();
+console.log(hash); // e.g., "a3f5d8c..."
+
+// Detailed analysis
+const fingerprint = await getFingerprint({ detailed: true });
+console.log(fingerprint.hash); // fingerprint hash
+console.log(fingerprint.uniqueness); // 0-1 uniqueness score
+console.log(fingerprint.confidence); // 0-1 confidence score
+console.log(fingerprint.tampering_risk); // 0-1 tampering risk
+console.log(fingerprint.anomalies); // array of detected anomalies
+console.log(fingerprint.sources); // entropy sources and their contributions
+```
+
+## API Reference
+
+### `getFingerprint(options?): Promise<string | FingerprintResponse>`
+
+Generates a browser fingerprint.
+
+**Options:**
+
+```typescript
+interface FingerprintOptions {
+  entropy?: {
+    userAgent?: boolean; // default: true
+    canvas?: boolean; // default: true
+    webgl?: boolean; // default: true
+    fonts?: boolean; // default: true
+    storage?: boolean; // default: true
+    screen?: boolean; // default: true
+  };
+  hash?: "sha256" | "sha512"; // default: "sha256"
+  detailed?: boolean; // return full response (default: false)
+}
+```
+
+**Returns:**
+
+- `string` - 64 or 128 character hash (if `detailed: false`)
+- `FingerprintResponse` - Full analysis object (if `detailed: true`)
+
+### `compareFingerpints(fp1, fp2): Promise<{ similarity: number; match: boolean }>`
+
+Compares two fingerprints using Levenshtein distance.
+
+```javascript
+const fp1 = await getFingerprint();
+const fp2 = await getFingerprint();
+const { similarity, match } = await compareFingerpints(fp1, fp2);
+
+console.log(similarity); // 0-1, higher = more similar
+console.log(match); // true if similarity > 0.95
+```
+
+### `matchProbability(stored, current): Promise<{ bestMatch: number; confidence: number }>`
+
+Finds best match from a stored fingerprint set.
+
+```javascript
+const currentFp = await getFingerprint();
+const storedFps = [fp1, fp2, fp3];
+
+const { bestMatch, confidence } = await matchProbability(storedFps, currentFp);
+console.log(bestMatch); // 0-1 highest similarity
+console.log(confidence); // probability estimate
+```
+
+## Entropy Sources
+
+Veil collects entropy from multiple sources:
+
+- **userAgent** - Browser user agent string
+- **canvas** - HTML5 canvas fingerprinting
+- **webgl** - WebGL capabilities and renderer
+- **fonts** - Installed system fonts
+- **storage** - LocalStorage and SessionStorage
+- **screen** - Display resolution and color depth
+- **distribution** - KS-test on seeded random samples
+- **complexity** - Lempel-Ziv complexity
+- **spectral** - Spectral entropy analysis
+- **approximate** - Approximate entropy
+- **os** - Operating system detection
+- **language** - Browser language preferences
+- **timezone** - System timezone
+- **hardware** - CPU cores and device memory
+- **plugins** - Browser plugins/extensions
+- **browser** - Browser vendor and version
+- **adblock** - Adblock detection
+- **webFeatures** - Supported web APIs
+
+## Tamper Detection
+
+Each fingerprint includes a `tampering_risk` score (0-1) and list of detected `anomalies`:
+
+```javascript
+const fp = await getFingerprint({ detailed: true });
+
+if (fp.tampering_risk > 0.5) {
+  console.warn("High tampering risk detected:", fp.anomalies);
+}
+```
+
+**Detected Anomalies:**
+
+- Suspiciously uniform entropy across sources
+- Duplicate values in multiple sources
+- Missing critical entropy sources
+- Cross-source inconsistencies (e.g., canvas/webgl mismatch)
+- Suspicious placeholder values (null, fake, mock)
+
+## Example
+
+See `/example/index.html` for a working demo with UI controls.
+
+```bash
+# Start local server
+python3 -m http.server 8000
+
+# Visit http://localhost:8000/example/
+```
+
+## How It Works
+
+1. **Entropy Collection** - Gathers browser characteristics from 25+ sources
+2. **Hashing** - Combines entropy sources and applies SHA-256/512
+3. **Scoring** - Calculates uniqueness via Bayesian methods
+4. **Anomaly Detection** - Analyzes entropy distribution for tampering signs
+5. **Output** - Returns fingerprint hash with optional detailed metrics
+
+The library uses WASM (via Rust) for computationally intensive operations:
+
+- Kolmogorov-Smirnov test (distribution analysis)
+- Lempel-Ziv complexity
+- Spectral entropy
+- Approximate entropy
+
+## Performance
+
+- Generation: ~50-100ms (first call includes WASM init)
+- Subsequent calls: ~20-30ms
+- Bundle size: ~23KB (gzipped)
+
+## Browser Support
+
+- Chrome/Edge 90+
+- Firefox 88+
+- Safari 14+
+- Any browser supporting:
+  - WebAssembly
+  - Web Crypto API
+  - Canvas API
+
+## License
+
+MIT - See LICENSE file
+
+## Contributing
+
+Contributions welcome. Please open an issue or PR on GitHub.
+
+---
+
+**Disclaimer:** Browser fingerprinting has privacy implications. Use responsibly and ensure compliance with local regulations and user privacy expectations.

package/example/index.html

@@ -2,6 +2,7 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
+    <!-- base href removed to fix module import paths -->
     <title>Veil Fingerprinting Demo</title>
     <style>
       body {
@@ -96,14 +97,6 @@
         <input type="checkbox" id="detailedCheckbox" checked />
         Detailed output (JSON)
       </label>
-      <label>
-        <input type="checkbox" id="cpuCheckbox" />
-        CPU benchmark
-      </label>
-      <label>
-        <input type="checkbox" id="gpuCheckbox" />
-        GPU benchmark
-      </label>
     </div>
 
     <div class="controls">
@@ -115,33 +108,26 @@
     <div id="result">Click "Generate" to start...</div>
 
     <script type="module">
-      import { getFingerprint } from "../dist/index.js";
+      let distPath = '../dist/index.js';
+      if (window.location.pathname.includes('/veil/')) {
+        distPath = '/veil/dist/index.js';
+      }
+      const { getFingerprint } = await import(distPath);
 
       window.generateFingerprint = async () => {
         const result = document.getElementById("result");
         const detailed = document.getElementById("detailedCheckbox").checked;
-        const cpuBenchmark = document.getElementById("cpuCheckbox").checked;
-        const gpuBenchmark = document.getElementById("gpuCheckbox").checked;
 
         result.innerHTML = '<div class="loading">Generating fingerprint...</div>';
         console.log("Starting fingerprint generation");
-        console.log("Options:", { detailed, cpuBenchmark, gpuBenchmark });
+        console.log("Options:", { detailed });
 
         try {
           const startTime = performance.now();
 
-          if (cpuBenchmark) {
-            console.log("Running CPU benchmark...");
-          }
-          if (gpuBenchmark) {
-            console.log("Running GPU benchmark...");
-          }
-
           const fp = await getFingerprint({
             hash: "sha256",
             detailed,
-            cpuBenchmark,
-            gpuBenchmark,
           });
 
           const endTime = performance.now();
@@ -169,7 +155,15 @@
                 
                 <strong>Metrics:</strong><br/>
                 <pre>Uniqueness: ${(fp.uniqueness * 100).toFixed(2)}%
-Confidence: ${(fp.confidence * 100).toFixed(2)}%</pre>
+Confidence: ${(fp.confidence * 100).toFixed(2)}%
+Tampering Risk: ${(fp.tampering_risk * 100).toFixed(2)}%</pre>
+
+                ${fp.anomalies.length > 0 ? `
+                <strong>Anomalies Detected (${fp.anomalies.length}):</strong><br/>
+                <pre>${fp.anomalies.map(a => 
+                  `[${a.severity.toUpperCase()}] ${a.id} (${a.category})\n${a.message}\nRisk: ${(a.riskContribution * 100).toFixed(0)}%\n`
+                ).join("\n")}</pre>
+                ` : ""}
 
                 <strong>System:</strong><br/>
                 <pre>OS: ${fp.system.os}

package/example/veil_core.d.ts

@@ -0,0 +1,71 @@
+/* tslint:disable */
+/* eslint-disable */
+
+export function approx_entropy(samples: Float64Array, m: number): number;
+
+export function cosine_similarity(v1: Float64Array, v2: Float64Array): number;
+
+export function fnv_hash(s: string): string;
+
+export function kolmogorov_complexity(s: string): number;
+
+export function ks_test(values: Float64Array): number;
+
+export function levenshtein_distance(s1: string, s2: string): number;
+
+export function lz_complexity(data: Uint8Array): number;
+
+export function murmur_hash(s: string): string;
+
+export function sample_ent(samples: Float64Array, m: number, r: number): number;
+
+export function shannon_entropy(s: string): number;
+
+export function similarity_score(s1: string, s2: string): number;
+
+export function spectral(samples: Float64Array): number;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+  readonly memory: WebAssembly.Memory;
+  readonly cosine_similarity: (a: number, b: number, c: number, d: number) => number;
+  readonly levenshtein_distance: (a: number, b: number, c: number, d: number) => number;
+  readonly similarity_score: (a: number, b: number, c: number, d: number) => number;
+  readonly approx_entropy: (a: number, b: number, c: number) => number;
+  readonly fnv_hash: (a: number, b: number) => [number, number];
+  readonly kolmogorov_complexity: (a: number, b: number) => number;
+  readonly ks_test: (a: number, b: number) => number;
+  readonly lz_complexity: (a: number, b: number) => number;
+  readonly sample_ent: (a: number, b: number, c: number, d: number) => number;
+  readonly shannon_entropy: (a: number, b: number) => number;
+  readonly spectral: (a: number, b: number) => number;
+  readonly murmur_hash: (a: number, b: number) => [number, number];
+  readonly __wbindgen_externrefs: WebAssembly.Table;
+  readonly __wbindgen_malloc: (a: number, b: number) => number;
+  readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+  readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+  readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+* Instantiates the given `module`, which can either be bytes or
+* a precompiled `WebAssembly.Module`.
+*
+* @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+*
+* @returns {InitOutput}
+*/
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+* If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+* for everything else, calls `WebAssembly.instantiate` directly.
+*
+* @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+*
+* @returns {Promise<InitOutput>}
+*/
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;