@anonympins/fingerprint 0.7.4 → 0.8.0

package/src/js/fingerprint.utils.js

@@ -1,5 +1,18 @@
 import {cyrb53} from "./fingerprint.builder.js";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
 
+/**
+ * Verifies a Zero-Knowledge Proof (ZKP) of the Schnorr type.
+ * The verification checks that g^s ≡ t * y^c (mod p),
+ * where c is a challenge computed by SHA-256 hashing of (g, y, t).
+ *
+ * @param {string} yStr - The public key y, hex-encoded (without the 0x prefix).
+ * @param {string} tStr - The commitment t, hex-encoded (without the 0x prefix).
+ * @param {string} sStr - The response s, hex-encoded (without the 0x prefix).
+ * @returns {boolean} True if the proof is valid, false otherwise (or on error).
+ */
 export function verifyZkpProof(yStr, tStr, sStr) {
     try {
         const y = BigInt('0x' + yStr);
@@ -19,6 +32,14 @@ export function verifyZkpProof(yStr, tStr, sStr) {
     }
 }
 
+/**
+ * Serializes a value to JSON while escaping dangerous characters
+ * for safe inclusion in HTML/JS (XSS prevention).
+ * Escapes <, >, U+2028, and U+2029.
+ *
+ * @param {*} val - The value to serialize.
+ * @returns {string} The escaped JSON string.
+ */
 export function safeJsonStringify(val) {
     return JSON.stringify(val)
         .replace(/</g, '\\u003c')
@@ -27,6 +48,16 @@ export function safeJsonStringify(val) {
         .replace(/\u2029/g, '\\u2029');
 }
 
+/**
+ * Sanitizes and validates a redirect path to prevent open redirects.
+ * - Strips out disallowed characters.
+ * - Prevents protocol-relative redirects (//evil.com).
+ * - Prevents absolute redirects (http://evil.com).
+ * - Ensures the path starts with a single '/'.
+ *
+ * @param {string} p - The raw redirect path.
+ * @returns {string} The sanitized path (or '/' by default).
+ */
 export function sanitizeRedirectPath(p) {
     if (typeof p !== 'string') return '/';
     let sanitized = p.replace(/[^a-zA-Z0-9\/.\-_~%?&=:@+,;]/g, '');
@@ -49,6 +80,16 @@ export function sanitizeRedirectPath(p) {
     }
     return sanitized.replace(/^\/+/g, '/');
 }
+
+/**
+ * Decodes a polymorphic fingerprint by restoring the original keys
+ * from a mapping of randomized keys.
+ * Expected format: "randKey: value|randKey: value|...".
+ *
+ * @param {string} fpString - The encoded fingerprint.
+ * @param {object} mapping - The mapping object containing `keys` (orig -> rand).
+ * @returns {string} The decoded fingerprint with original keys.
+ */
 export function decodePolymorphicFingerprint(fpString, mapping) {
     if (!fpString || !mapping || !mapping.keys) return fpString;
     const reverseKeys = {};
@@ -67,6 +108,130 @@ export function decodePolymorphicFingerprint(fpString, mapping) {
     return mappedParts.join('|');
 }
 
+/**
+ * Extracts and parses a Private Access Token (PAT / Privacy Pass / RFC 9578).
+ * Supports 'Authorization: PrivateToken token="..."' and 'Sec-Private-State-Token'.
+ *
+ * @param {object} headers - HTTP request headers object.
+ * @returns {Array<Uint8Array>} Array of raw binary tokens.
+ */
+export function extractPrivateAccessTokens(headers) {
+    if (!headers) return [];
+    const tokens = [];
+
+    const authHeader = headers['authorization'] || headers['Authorization'];
+    if (typeof authHeader === 'string' && authHeader.toLowerCase().startsWith('privatetoken ')) {
+        const match = authHeader.match(/token=(?:"([^"]+)"|([a-zA-Z0-9_\-+/=]+))/i);
+        if (match) {
+            const rawB64 = match[1] || match[2];
+            try {
+                tokens.push(Buffer.from(rawB64.replace(/-/g, '+').replace(/_/g, '/'), 'base64'));
+            } catch (e) {}
+        }
+    }
+
+    const pstHeader = headers['sec-private-state-token'] || headers['Sec-Private-State-Token'];
+    if (typeof pstHeader === 'string') {
+        const parts = pstHeader.split(',');
+        for (const part of parts) {
+            const trimmed = part.trim();
+            if (trimmed) {
+                try {
+                    tokens.push(Buffer.from(trimmed.replace(/-/g, '+').replace(/_/g, '/'), 'base64'));
+                } catch (e) {}
+            }
+        }
+    }
+
+    return tokens;
+}
+
+/**
+ * Decodes an RFC 9578 Token structure:
+ * uint16_t token_type (2 bytes)
+ * uint8_t nonce[32] (32 bytes)
+ * uint8_t challenge_digest[32] (32 bytes)
+ * uint8_t token_key_id[32] (32 bytes)
+ * uint8_t authenticator[Nk] (>= 32 bytes)
+ *
+ * @param {Uint8Array|Buffer} buffer
+ * @returns {object|null}
+ */
+export function parsePrivateAccessToken(buffer) {
+    if (!buffer || buffer.length < 98) return null; // 2 + 32 + 32 + 32 = 98 min
+
+    const view = Buffer.isBuffer(buffer) ? buffer : Buffer.from(buffer);
+    const tokenType = view.readUInt16BE(0);
+    const nonce = view.subarray(2, 34);
+    const challengeDigest = view.subarray(34, 66);
+    const tokenKeyId = view.subarray(66, 98);
+    const authenticator = view.subarray(98);
+
+    if (authenticator.length === 0) return null;
+
+    return {
+        tokenType,
+        nonce: nonce.toString('hex'),
+        challengeDigest: challengeDigest.toString('hex'),
+        tokenKeyId: tokenKeyId.toString('hex'),
+        authenticator,
+        signedData: view.subarray(0, 98)
+    };
+}
+
+/**
+ * Validates a decoded Private Access Token signature against configured public keys.
+ *
+ * @param {object} parsedToken - Output from parsePrivateAccessToken.
+ * @param {object} patConfig - Configuration with trustedKeys mapping.
+ * @returns {boolean} True if signature is cryptographically valid.
+ */
+export function verifyPatSignature(parsedToken, patConfig = {}) {
+    if (!parsedToken) return false;
+    const trustedKeys = patConfig.trustedKeys || {};
+    const keyId = parsedToken.tokenKeyId;
+    const publicKey = trustedKeys[keyId] || trustedKeys[keyId.toLowerCase()] || patConfig.defaultPublicKey;
+
+    if (!publicKey) {
+        return false;
+    }
+
+    const { tokenType, signedData, authenticator } = parsedToken;
+
+    try {
+        // Type 0x0001 (Blind RSA 2048) / 0x0002 (Rate-Limited Blind RSA)
+        if (tokenType === 0x0001 || tokenType === 0x0002 || tokenType === 1 || tokenType === 2) {
+            // Try RSA-PSS with SHA-384 (RFC 9577) first, fallback to SHA-256 and PKCS#1 v1.5
+            const algorithms = [
+                { hash: 'sha384', padding: crypto.constants.RSA_PKCS1_PSS_PADDING, saltLength: 48 },
+                { hash: 'sha256', padding: crypto.constants.RSA_PKCS1_PSS_PADDING, saltLength: 32 },
+                { hash: 'sha384', padding: crypto.constants.RSA_PKCS1_PADDING },
+                { hash: 'sha256', padding: crypto.constants.RSA_PKCS1_PADDING }
+            ];
+
+            for (const alg of algorithms) {
+                try {
+                    const verifier = crypto.createVerify(alg.hash);
+                    verifier.update(signedData);
+                    const isValid = verifier.verify({
+                        key: publicKey,
+                        padding: alg.padding,
+                        saltLength: alg.saltLength
+                    }, authenticator);
+                    if (isValid) return true;
+                } catch (verifyErr) {}
+            }
+        } else if (tokenType === 0x0003 || tokenType === 3) {
+            // VOPRF / Ed25519 authentication verification
+            try {
+                return crypto.verify(null, signedData, publicKey, authenticator);
+            } catch (voprfErr) {}
+        }
+    } catch (e) {
+        return false;
+    }
+    return false;
+}
 
 /**
  * @private
@@ -127,6 +292,15 @@ export function parseJa3(ja3String) {
     };
 }
 
+/**
+ * Computes modular exponentiation (base^exponent mod modulus) efficiently
+ * using the binary exponentiation method (square-and-multiply).
+ *
+ * @param {bigint} base - The base.
+ * @param {bigint} exponent - The exponent.
+ * @param {bigint} modulus - The modulus.
+ * @returns {bigint} The result of base^exponent mod modulus.
+ */
 export function modPow(base, exponent, modulus) {
     if (modulus === 1n) return 0n;
     let result = 1n;
@@ -142,6 +316,14 @@ export function modPow(base, exponent, modulus) {
 }
 
 
+/**
+ * Computes a simple hash of the IP network by applying a mask (CIDR prefix).
+ * For example, with a prefix of 24, only the first 3 octets are kept.
+ *
+ * @param {string} ip - The IP address in IPv4 format (e.g. "192.168.1.42").
+ * @param {number} [prefix=24] - The network prefix length (in bits).
+ * @returns {string|null} A hexadecimal hash of the network, or null if the IP is invalid.
+ */
 export function hashNetwork(ip, prefix = 24) {
     // Network hash (/24 or /16 mask)
     const parts = ip.split('.');
@@ -157,6 +339,14 @@ export function hashNetwork(ip, prefix = 24) {
     }
     return hash.toString(16);
 }
+
+/**
+ * Checks whether an IP address is a loopback address (localhost).
+ * Handles IPv4, IPv6, and the IPv4-mapped prefix (::ffff:).
+ *
+ * @param {string} ip - The IP address to test.
+ * @returns {boolean} True if the IP is a loopback address, false otherwise.
+ */
 export function isLoopbackIp(ip) {
     if (!ip || typeof ip !== 'string') return true;
     let cleanIp = ip.trim().toLowerCase();
@@ -164,9 +354,16 @@ export function isLoopbackIp(ip) {
         cleanIp = cleanIp.substring(7);
     }
     return cleanIp === '127.0.0.1' || cleanIp === '::1' || cleanIp === 'localhost' ||
-           cleanIp.startsWith('127.') || cleanIp === '0.0.0.0' || cleanIp === '::';
+        cleanIp.startsWith('127.') || cleanIp === '0.0.0.0' || cleanIp === '::';
 }
 
+/**
+ * Normalizes a referer URL by keeping only the protocol and hostname
+ * (e.g. "https://example.com").
+ *
+ * @param {string} referer - The raw referer URL.
+ * @returns {string} The normalized URL, or the original value if invalid.
+ */
 export function normalizeReferer(referer) {
     try {
         const url = new URL(referer);
@@ -176,6 +373,13 @@ export function normalizeReferer(referer) {
     }
 }
 
+/**
+ * Checks whether an IP address belongs to a private range (RFC 1918, loopback,
+ * link-local, CGNAT, etc.). Handles both IPv4 and IPv6 formats.
+ *
+ * @param {string} ip - The IP address to test.
+ * @returns {boolean} True if the IP is private, false otherwise.
+ */
 export function isPrivateIp(ip) {
     if (!ip || typeof ip !== 'string') return false;
     let cleanIp = ip.trim().toLowerCase();
@@ -200,7 +404,16 @@ export function isPrivateIp(ip) {
     }
     return false;
 }
-// Utility parsing functions
+
+/**
+ * Basic User-Agent parsing to extract:
+ * - the browser (with major version),
+ * - the operating system,
+ * - the device type (mobile, tablet, desktop).
+ *
+ * @param {string} ua - The User-Agent string.
+ * @returns {object} An object { browser?, os?, device }.
+ */
 export function parseUserAgent(ua) {
     // Basic User-Agent parser
     const result = {};
@@ -238,4 +451,41 @@ export function parseUserAgent(ua) {
     else result.device = 'desktop';
 
     return result;
+}
+
+/**
+ * Programmatically generates an Ed25519 key pair in PEM format
+ * (PKCS#8 for private key, SPKI for public key) matching OpenSSL CLI:
+ * `openssl genpkey -algorithm ed25519 -out issuer-private.pem`
+ * `openssl pkey -in issuer-private.pem -pubout -out issuer-public.pem`
+ *
+ * @param {string} [outDir='./config'] Target directory to store the PEM files.
+ * @param {object} [options={}] Optional configuration (e.g. custom file names).
+ * @returns {{privateKeyPath: string, publicKeyPath: string, privateKey: string, publicKey: string}}
+ */
+export function generateIssuerPemKeys(outDir = './config', options = {}) {
+    const privateKeyName = options.privateKeyName || 'issuer-private.pem';
+    const publicKeyName = options.publicKeyName || 'issuer-public.pem';
+
+    const { privateKey, publicKey } = crypto.generateKeyPairSync('ed25519', {
+        privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+        publicKeyEncoding: { type: 'spki', format: 'pem' }
+    });
+
+    if (!fs.existsSync(outDir)) {
+        fs.mkdirSync(outDir, { recursive: true });
+    }
+
+    const privateKeyPath = path.join(outDir, privateKeyName);
+    const publicKeyPath = path.join(outDir, publicKeyName);
+
+    fs.writeFileSync(privateKeyPath, privateKey, { mode: 0o600 });
+    fs.writeFileSync(publicKeyPath, publicKey, { mode: 0o644 });
+
+    return {
+        privateKeyPath,
+        publicKeyPath,
+        privateKey,
+        publicKey
+    };
 }

package/src/js/pow.worker.js

@@ -10,7 +10,7 @@ self.onmessage = async (event) => {
     let solution = 0;
     const encoder = new TextEncoder();
     if (baseBlock) {
-        // Mode solveCpuTargetInline (Uint8Array base block)
+        // solveCpuTargetInline mode (Uint8Array base block)
         const blockArray = new Uint8Array(baseBlock);
         while (true) {
             const solutionBytes = encoder.encode(String(solution));
@@ -31,7 +31,7 @@ self.onmessage = async (event) => {
             }
         }
     } else {
-        // Mode solveCpuTarget standard/legacy (Message string)
+        // Standard/legacy solveCpuTarget mode (Message string)
         while (true) {
             const currentMessage = `${message}:${solution}`;
             const data = encoder.encode(currentMessage);

package/src/js/tests/cross_parity.test.js

@@ -12,14 +12,14 @@ describe('Cross-Parity Chaos PoW Floating Point Parity (JS vs WASM vs PHP)', ()
     let wasmModule = null;
 
     beforeAll(async () => {
-        // Essai de compilation WASM à la volée s'il y a em++
+        // Attempt on-the-fly WASM compilation if em++ toolchain is available
         try {
             execSync('node src/js/build-client.js', { stdio: 'ignore' });
         } catch (e) {
-            // Ignorer si Emscripten n'est pas présent dans l'env
+            // Ignore if Emscripten is missing in environment
         }
 
-        // Instancier le WASM réel si compilé
+        // Instantiate compiled WASM module if available
         if (fs.existsSync(fpJsPath) && fs.existsSync(fpWasmPath)) {
             try {
                 const module = await import(fpJsPath);

package/src/js/tests/dns-circuit-breaker.test.js

@@ -9,15 +9,15 @@ describe('DNS Circuit Breaker', () => {
         dnsCircuitBreaker.failureCount = 0;
         dnsCircuitBreaker.lastStateChange = 0;
         dnsCircuitBreaker.threshold = 5;
-        dnsCircuitBreaker.cooldownMs = 1000; // 1s de cooldown pour accélérer le test unitaire
+        dnsCircuitBreaker.cooldownMs = 1000; // 1s cooldown to speed up test execution
     });
 
-    it('devrait démarrer à l\'état CLOSED et autoriser les résolutions', () => {
+    it('should start in CLOSED state and allow lookups', () => {
         expect(canAttemptDns()).toBe(true);
         expect(dnsCircuitBreaker.state).toBe('CLOSED');
     });
 
-    it('devrait s\'ouvrir après avoir atteint le seuil d\'échecs (5)', () => {
+    it('should transition to OPEN after reaching failure threshold (5)', () => {
         for (let i = 0; i < 4; i++) {
             recordDnsFailure();
             expect(canAttemptDns()).toBe(true);
@@ -29,7 +29,7 @@ describe('DNS Circuit Breaker', () => {
         expect(dnsCircuitBreaker.state).toBe('OPEN');
     });
 
-    it('devrait passer en HALF-OPEN après expiration du cooldown', async () => {
+    it('should transition to HALF-OPEN after cooldown expires', async () => {
         for (let i = 0; i < 5; i++) {
             recordDnsFailure();
         }
@@ -41,12 +41,12 @@ describe('DNS Circuit Breaker', () => {
         expect(dnsCircuitBreaker.state).toBe('HALF-OPEN');
     });
 
-    it('devrait se refermer (CLOSED) après un succès en HALF-OPEN', async () => {
+    it('should reset to CLOSED after a success while in HALF-OPEN', async () => {
         for (let i = 0; i < 5; i++) {
             recordDnsFailure();
         }
         await new Promise((resolve) => setTimeout(resolve, 1100));
-        expect(canAttemptDns()).toBe(true); // Passage en HALF-OPEN
+        expect(canAttemptDns()).toBe(true); // Transition to HALF-OPEN
 
         recordDnsSuccess();
         expect(dnsCircuitBreaker.state).toBe('CLOSED');

package/src/js/tests/dynamic-wasm.test.js

@@ -1,78 +1,78 @@
-import { describe, expect, it } from 'vitest';
-import { DynamicWasmGenerator } from '../dynamic-wasm.js';
-
-// Helper function to decode ULEB128 (for verification)
-function decodeULEB128(bytes) {
-    let result = 0;
-    let shift = 0;
-    for (const byte of bytes) {
-        result |= (byte & 0x7f) << shift;
-        if (!(byte & 0x80)) {
-            break;
-        }
-        shift += 7;
-    }
-    return result;
-}
-
-describe('DynamicWasmGenerator', () => {
-    it('should generate a valid WASM module buffer', () => {
-        const constants = { seed: 123, multiplier: 33, adder: 7 };
-        const wasmBuffer = DynamicWasmGenerator.generate(constants);
-
-        // Basic check: ensure it's a Buffer and starts with WASM magic number
-        expect(wasmBuffer).toBeInstanceOf(Buffer);
-        expect(wasmBuffer.slice(0, 4).toString('hex')).toBe('0061736d'); // \0asm
-        expect(wasmBuffer.slice(4, 8).toString('hex')).toBe('01000000'); // Version 1
-
-        // Attempt to compile and instantiate the module to ensure validity
-        let instance;
-        try {
-            const module = new WebAssembly.Module(wasmBuffer);
-            instance = new WebAssembly.Instance(module, {});
-        } catch (e) {
-            // If compilation/instantiation fails, it's an invalid WASM module
-            expect.fail(`Generated WASM module is invalid: ${e.message}`);
-        }
-
-        // Verify the exported hash function exists
-        expect(instance.exports.hash).toBeInstanceOf(Function);
-        expect(instance.exports.memory).toBeInstanceOf(WebAssembly.Memory);
-    });
-
-    it('should produce a consistent hash result with the JS fallback', () => {
-        const constants = { seed: 42, multiplier: 1597334677, adder: 12345 };
-        const testString = "hello world";
-
-        const wasmBuffer = DynamicWasmGenerator.generate(constants);
-        const module = new WebAssembly.Module(wasmBuffer);
-        const instance = new WebAssembly.Instance(module, {});
-        const exports = instance.exports;
-        const memory = exports.memory;
-
-        // Write string to WASM memory
-        const encoder = new TextEncoder();
-        const bytes = encoder.encode(testString);
-        const view = new Uint8Array(memory.buffer);
-        view.set(bytes, 0); // Assuming hash function expects string at address 0
-
-        // Calculate hash using WASM
-        const wasmHash = exports.hash(0, bytes.length);
-
-        // Calculate hash using JS fallback
-        const jsHash = DynamicWasmGenerator.hashJs(testString, constants);
-
-        // The WASM and JS implementations should yield the same result
-        expect(wasmHash).toBe(jsHash);
-    });
-
-    it('should generate different WASM modules for different constants', () => {
-        const constants1 = { seed: 1, multiplier: 2, adder: 3 };
-        const constants2 = { seed: 4, multiplier: 5, adder: 6 };
-
-        const wasmBuffer1 = DynamicWasmGenerator.generate(constants1);
-        const wasmBuffer2 = DynamicWasmGenerator.generate(constants2);
-
-        expect(wasmBuffer1.toString('hex')).not.toBe(wasmBuffer2.toString('hex'));
-    });
+import { describe, expect, it } from 'vitest';
+import { DynamicWasmGenerator } from '../dynamic-wasm.js';
+
+// Helper function to decode ULEB128 (for verification)
+function decodeULEB128(bytes) {
+    let result = 0;
+    let shift = 0;
+    for (const byte of bytes) {
+        result |= (byte & 0x7f) << shift;
+        if (!(byte & 0x80)) {
+            break;
+        }
+        shift += 7;
+    }
+    return result;
+}
+
+describe('DynamicWasmGenerator', () => {
+    it('should generate a valid WASM module buffer', () => {
+        const constants = { seed: 123, multiplier: 33, adder: 7 };
+        const wasmBuffer = DynamicWasmGenerator.generate(constants);
+
+        // Basic check: ensure it's a Buffer and starts with WASM magic number
+        expect(wasmBuffer).toBeInstanceOf(Buffer);
+        expect(wasmBuffer.slice(0, 4).toString('hex')).toBe('0061736d'); // \0asm
+        expect(wasmBuffer.slice(4, 8).toString('hex')).toBe('01000000'); // Version 1
+
+        // Attempt to compile and instantiate the module to ensure validity
+        let instance;
+        try {
+            const module = new WebAssembly.Module(wasmBuffer);
+            instance = new WebAssembly.Instance(module, {});
+        } catch (e) {
+            // If compilation/instantiation fails, it's an invalid WASM module
+            expect.fail(`Generated WASM module is invalid: ${e.message}`);
+        }
+
+        // Verify the exported hash function exists
+        expect(instance.exports.hash).toBeInstanceOf(Function);
+        expect(instance.exports.memory).toBeInstanceOf(WebAssembly.Memory);
+    });
+
+    it('should produce a consistent hash result with the JS fallback', () => {
+        const constants = { seed: 42, multiplier: 1597334677, adder: 12345 };
+        const testString = "hello world";
+
+        const wasmBuffer = DynamicWasmGenerator.generate(constants);
+        const module = new WebAssembly.Module(wasmBuffer);
+        const instance = new WebAssembly.Instance(module, {});
+        const exports = instance.exports;
+        const memory = exports.memory;
+
+        // Write string to WASM memory
+        const encoder = new TextEncoder();
+        const bytes = encoder.encode(testString);
+        const view = new Uint8Array(memory.buffer);
+        view.set(bytes, 0); // Assuming hash function expects string at address 0
+
+        // Calculate hash using WASM
+        const wasmHash = exports.hash(0, bytes.length);
+
+        // Calculate hash using JS fallback
+        const jsHash = DynamicWasmGenerator.hashJs(testString, constants);
+
+        // The WASM and JS implementations should yield the same result
+        expect(wasmHash).toBe(jsHash);
+    });
+
+    it('should generate different WASM modules for different constants', () => {
+        const constants1 = { seed: 1, multiplier: 2, adder: 3 };
+        const constants2 = { seed: 4, multiplier: 5, adder: 6 };
+
+        const wasmBuffer1 = DynamicWasmGenerator.generate(constants1);
+        const wasmBuffer2 = DynamicWasmGenerator.generate(constants2);
+
+        expect(wasmBuffer1.toString('hex')).not.toBe(wasmBuffer2.toString('hex'));
+    });
 });