altcha-lib 0.1.2 → 0.1.4

package/README.md

@@ -4,7 +4,7 @@ ALTCHA JS Library is a lightweight, zero-dependency library designed for creatin
 
 ## Compatibility
 
-This library utilizes [Web Crypto](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto) and is intended for server-side use.
+This library utilizes [Web Crypto](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto) and can be used in modern browsers and supported server environments:
 
 - Node.js 16+
 - Bun 1+
@@ -20,6 +20,7 @@ const hmacKey = 'secret hmac key';
 // Create a new challenge and send it to the client:
 const challenge = await createChallenge({
   hmacKey,
+  maxNumber: 100000, // the maximum random number
 });
 
 // When submitted, verify the payload:
@@ -42,6 +43,8 @@ Parameters:
   - `salt?: string`: Optional salt string. If not provided, a random salt will be generated.
   - `saltLength?: number` Optional maximum lenght of the random salt (in bytes, defaults to 12).
 
+Returns: `Promise<Challenge>`
+
 ### `verifySolution(payload, hmacKey)`
 
 Verifies an ALTCHA solution. The payload can be a Base64-encoded JSON payload (as submitted by the widget) or an object.
@@ -51,6 +54,71 @@ Parameters:
 - `payload: string | Payload`
 - `hmacKey: string`
 
+Returns: `Promise<boolean>`
+
+### `solveChallenge(challenge, salt, algorithm?, max?, start?)`
+
+Finds a solution to the given challenge. 
+
+Parameters:
+
+- `challenge: string` (required): The challenge hash.
+- `salt: string` (required): The challenge salt.
+- `algorithm?: string`: Optional algorithm (default: `SHA-256`).
+- `max?: string`: Optional `maxnumber` to iterate to (default: 1e6).
+- `start?: string`: Optional starting number (default: 0).
+
+Returns: `{ controller: AbortController, promise: Promise<Solution | null> }`
+
+### `solveChallengeWorkers(workerScript, concurrency, challenge, salt, algorithm?, max?, start?)`
+
+Finds a solution to the given challenge with [Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Worker/Worker) running concurrently. 
+
+Parameters:
+
+- `workerScript: string` (required): The path or URL of the worker script.
+- `concurrency: number` (required): The concurrency (number of workers).
+- `challenge: string` (required): The challenge hash.
+- `salt: string` (required): The challenge salt.
+- `algorithm?: string`: Optional algorithm (default: `SHA-256`).
+- `max?: string`: Optional `maxnumber` to iterate to (default: 1e6).
+- `start?: string`: Optional starting number (default: 0).
+
+Returns: `Promise<Solution | null>`
+
+Usage with `altcha-lib/worker`:
+
+```ts
+import { solveChallengeWorkers } from 'altcha-lib';
+
+const solution = await solveChallengeWorkers(
+  'altcha-lib/worker', // Worker script URL or path
+  8, // Spawn 8 workers
+  challenge,
+  salt,
+);
+```
+
+## Benchmarks
+
+```
+> solveChallenge()
+- n = 1,000...............................        319 ops/s ±2.04%
+- n = 10,000..............................         31 ops/s ±1.02%
+- n = 50,000..............................          6 ops/s ±1.48%
+- n = 100,000.............................          3 ops/s ±0.27%
+- n = 500,000.............................          0 ops/s ±0.36%
+
+> solveChallengeWorkers() (8 workers)
+- n = 1,000...............................         62 ops/s ±5.69%
+- n = 10,000..............................         30 ops/s ±4.35%
+- n = 50,000..............................         12 ops/s ±2.89%
+- n = 100,000.............................          7 ops/s ±2.33%
+- n = 500,000.............................          1 ops/s ±2.22%
+```
+
+Run with Bun on MacBook Pro M3-Pro. See [/benchmark](/benchmark/) folder for more details.
+
 ## License
 
 MIT

package/cjs/dist/crypto.d.ts

@@ -0,0 +1 @@
+export {};

package/cjs/dist/crypto.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+if (!('crypto' in globalThis)) {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    globalThis.crypto = require('node:crypto').webcrypto;
+}

package/cjs/dist/helpers.d.ts

@@ -1,4 +1,6 @@
+import './crypto.js';
 import type { Algorithm } from './types.js';
+export declare const encoder: TextEncoder;
 export declare function ab2hex(ab: ArrayBuffer | Uint8Array): string;
 export declare function hash(algorithm: Algorithm, str: string): Promise<string>;
 export declare function hmac(algorithm: Algorithm, str: string, secret: string): Promise<string>;

package/cjs/dist/helpers.js

@@ -1,11 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.randomInt = exports.randomBytes = exports.hmac = exports.hash = exports.ab2hex = void 0;
-const encoder = new TextEncoder();
-if (!('crypto' in globalThis)) {
-    // eslint-disable-next-line @typescript-eslint/no-var-requires
-    globalThis.crypto = require('node:crypto').webcrypto;
-}
+exports.randomInt = exports.randomBytes = exports.hmac = exports.hash = exports.ab2hex = exports.encoder = void 0;
+// @denoify-line-ignore
+require("./crypto.js");
+exports.encoder = new TextEncoder();
 function ab2hex(ab) {
     return [...new Uint8Array(ab)]
         .map((x) => x.toString(16).padStart(2, '0'))
@@ -13,15 +11,15 @@ function ab2hex(ab) {
 }
 exports.ab2hex = ab2hex;
 async function hash(algorithm, str) {
-    return ab2hex(await crypto.subtle.digest(algorithm.toUpperCase(), encoder.encode(str)));
+    return ab2hex(await crypto.subtle.digest(algorithm.toUpperCase(), exports.encoder.encode(str)));
 }
 exports.hash = hash;
 async function hmac(algorithm, str, secret) {
-    const key = await crypto.subtle.importKey('raw', encoder.encode(secret), {
+    const key = await crypto.subtle.importKey('raw', exports.encoder.encode(secret), {
         name: 'HMAC',
         hash: algorithm,
     }, false, ['sign', 'verify']);
-    return ab2hex(await crypto.subtle.sign('HMAC', key, encoder.encode(str)));
+    return ab2hex(await crypto.subtle.sign('HMAC', key, exports.encoder.encode(str)));
 }
 exports.hmac = hmac;
 function randomBytes(length) {

package/cjs/dist/index.d.ts

@@ -1,3 +1,8 @@
-import type { Challenge, ChallengeOptions, Payload } from './types.js';
+import type { Challenge, ChallengeOptions, Payload, Solution } from './types.js';
 export declare function createChallenge(options: ChallengeOptions): Promise<Challenge>;
 export declare function verifySolution(payload: string | Payload, hmacKey: string): Promise<boolean>;
+export declare function solveChallenge(challenge: string, salt: string, algorithm?: string, max?: number, start?: number): {
+    promise: Promise<Solution | null>;
+    controller: AbortController;
+};
+export declare function solveChallengeWorkers(workerScript: string | URL | (() => Worker), concurrency: number, challenge: string, salt: string, algorithm?: string, max?: number, startNumber?: number): Promise<Solution | null>;

package/cjs/dist/index.js

@@ -1,20 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.verifySolution = exports.createChallenge = void 0;
+exports.solveChallengeWorkers = exports.solveChallenge = exports.verifySolution = exports.createChallenge = void 0;
 const helpers_js_1 = require("./helpers.js");
 const DEFAULT_MAX_NUMBER = 1e6;
 const DEFAULT_SALT_LEN = 12;
 const DEFAULT_ALG = 'SHA-256';
 async function createChallenge(options) {
     const algorithm = options.algorithm || DEFAULT_ALG;
-    const maxNumber = options.maxNumber || DEFAULT_MAX_NUMBER;
+    const max = options.maxNumber || DEFAULT_MAX_NUMBER;
     const saltLength = options.saltLength || DEFAULT_SALT_LEN;
     const salt = options.salt || (0, helpers_js_1.ab2hex)((0, helpers_js_1.randomBytes)(saltLength));
-    const number = options.number === void 0 ? (0, helpers_js_1.randomInt)(maxNumber) : options.number;
+    const number = options.number === void 0 ? (0, helpers_js_1.randomInt)(max) : options.number;
     const challenge = await (0, helpers_js_1.hash)(algorithm, salt + number);
     return {
         algorithm,
         challenge,
+        max,
         salt,
         signature: await (0, helpers_js_1.hmac)(algorithm, challenge, options.hmacKey),
     };
@@ -34,3 +35,88 @@ async function verifySolution(payload, hmacKey) {
         check.signature === payload.signature);
 }
 exports.verifySolution = verifySolution;
+function solveChallenge(challenge, salt, algorithm = 'SHA-256', max = 1e6, start = 0) {
+    const controller = new AbortController();
+    const promise = new Promise((resolve, reject) => {
+        const startTime = Date.now();
+        const next = (n) => {
+            if (controller.signal.aborted || n > max) {
+                resolve(null);
+            }
+            else {
+                hashChallenge(salt, n, algorithm)
+                    .then((t) => {
+                    if (t === challenge) {
+                        resolve({
+                            number: n,
+                            took: Date.now() - startTime,
+                        });
+                    }
+                    else {
+                        next(n + 1);
+                    }
+                })
+                    .catch(reject);
+            }
+        };
+        next(start);
+    });
+    return {
+        promise,
+        controller,
+    };
+}
+exports.solveChallenge = solveChallenge;
+async function solveChallengeWorkers(workerScript, concurrency, challenge, salt, algorithm = 'SHA-256', max = 1e6, startNumber = 0) {
+    const workers = [];
+    if (concurrency < 1) {
+        throw new Error('Wrong number of workers configured.');
+    }
+    if (concurrency > 16) {
+        throw new Error('Too many workers. Max. 16 allowed workers.');
+    }
+    for (let i = 0; i < concurrency; i++) {
+        if (typeof workerScript === 'function') {
+            workers.push(workerScript());
+        }
+        else {
+            workers.push(new Worker(workerScript, {
+                type: 'module',
+            }));
+        }
+    }
+    const step = Math.ceil(max / concurrency);
+    const solutions = await Promise.all(workers.map((worker, i) => {
+        const start = startNumber + i * step;
+        return new Promise((resolve) => {
+            worker.addEventListener('message', (message) => {
+                if (message.data) {
+                    for (const w of workers) {
+                        if (w !== worker) {
+                            w.postMessage({ type: 'abort' });
+                        }
+                    }
+                }
+                resolve(message.data);
+            });
+            worker.postMessage({
+                payload: {
+                    algorithm,
+                    challenge,
+                    max: start + step,
+                    salt,
+                    start,
+                },
+                type: 'work',
+            });
+        });
+    }));
+    for (const worker of workers) {
+        worker.terminate();
+    }
+    return solutions.find((solution) => !!solution) || null;
+}
+exports.solveChallengeWorkers = solveChallengeWorkers;
+async function hashChallenge(salt, num, algorithm) {
+    return (0, helpers_js_1.ab2hex)(await crypto.subtle.digest(algorithm.toUpperCase(), helpers_js_1.encoder.encode(salt + num)));
+}

package/cjs/dist/types.d.ts

@@ -2,6 +2,7 @@ export type Algorithm = 'SHA-1' | 'SHA-256' | 'SHA-512';
 export interface Challenge {
     algorithm: Algorithm;
     challenge: string;
+    max?: number;
     salt: string;
     signature: string;
 }
@@ -20,3 +21,8 @@ export interface Payload {
     salt: string;
     signature: string;
 }
+export interface Solution {
+    number: number;
+    took: number;
+    worker?: boolean;
+}

package/cjs/dist/worker.d.ts

@@ -0,0 +1 @@
+export {};

package/cjs/dist/worker.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("./index.js");
+let controller = undefined;
+onmessage = async (message) => {
+    const { type, payload } = message.data;
+    if (type === 'abort') {
+        controller?.abort();
+        controller = undefined;
+    }
+    else if (type === 'work') {
+        const { alg, challenge, max, salt, start } = payload || {};
+        const result = (0, index_js_1.solveChallenge)(challenge, salt, alg, max, start);
+        controller = result.controller;
+        result.promise.then((solution) => {
+            self.postMessage(solution ? { ...solution, worker: true } : solution);
+        });
+    }
+};

package/dist/crypto.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/crypto.js

@@ -0,0 +1,5 @@
+if (!('crypto' in globalThis)) {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    globalThis.crypto = require('node:crypto').webcrypto;
+}
+export {};

package/dist/helpers.d.ts

@@ -1,4 +1,6 @@
+import './crypto.js';
 import type { Algorithm } from './types.js';
+export declare const encoder: TextEncoder;
 export declare function ab2hex(ab: ArrayBuffer | Uint8Array): string;
 export declare function hash(algorithm: Algorithm, str: string): Promise<string>;
 export declare function hmac(algorithm: Algorithm, str: string, secret: string): Promise<string>;

package/dist/helpers.js

@@ -1,8 +1,6 @@
-const encoder = new TextEncoder();
-if (!('crypto' in globalThis)) {
-    // eslint-disable-next-line @typescript-eslint/no-var-requires
-    globalThis.crypto = require('node:crypto').webcrypto;
-}
+// @denoify-line-ignore
+import './crypto.js';
+export const encoder = new TextEncoder();
 export function ab2hex(ab) {
     return [...new Uint8Array(ab)]
         .map((x) => x.toString(16).padStart(2, '0'))

package/dist/index.d.ts

@@ -1,3 +1,8 @@
-import type { Challenge, ChallengeOptions, Payload } from './types.js';
+import type { Challenge, ChallengeOptions, Payload, Solution } from './types.js';
 export declare function createChallenge(options: ChallengeOptions): Promise<Challenge>;
 export declare function verifySolution(payload: string | Payload, hmacKey: string): Promise<boolean>;
+export declare function solveChallenge(challenge: string, salt: string, algorithm?: string, max?: number, start?: number): {
+    promise: Promise<Solution | null>;
+    controller: AbortController;
+};
+export declare function solveChallengeWorkers(workerScript: string | URL | (() => Worker), concurrency: number, challenge: string, salt: string, algorithm?: string, max?: number, startNumber?: number): Promise<Solution | null>;

package/dist/index.js

@@ -1,17 +1,18 @@
-import { ab2hex, hash, hmac, randomBytes, randomInt } from './helpers.js';
+import { ab2hex, encoder, hash, hmac, randomBytes, randomInt, } from './helpers.js';
 const DEFAULT_MAX_NUMBER = 1e6;
 const DEFAULT_SALT_LEN = 12;
 const DEFAULT_ALG = 'SHA-256';
 export async function createChallenge(options) {
     const algorithm = options.algorithm || DEFAULT_ALG;
-    const maxNumber = options.maxNumber || DEFAULT_MAX_NUMBER;
+    const max = options.maxNumber || DEFAULT_MAX_NUMBER;
     const saltLength = options.saltLength || DEFAULT_SALT_LEN;
     const salt = options.salt || ab2hex(randomBytes(saltLength));
-    const number = options.number === void 0 ? randomInt(maxNumber) : options.number;
+    const number = options.number === void 0 ? randomInt(max) : options.number;
     const challenge = await hash(algorithm, salt + number);
     return {
         algorithm,
         challenge,
+        max,
         salt,
         signature: await hmac(algorithm, challenge, options.hmacKey),
     };
@@ -29,3 +30,86 @@ export async function verifySolution(payload, hmacKey) {
     return (check.challenge === payload.challenge &&
         check.signature === payload.signature);
 }
+export function solveChallenge(challenge, salt, algorithm = 'SHA-256', max = 1e6, start = 0) {
+    const controller = new AbortController();
+    const promise = new Promise((resolve, reject) => {
+        const startTime = Date.now();
+        const next = (n) => {
+            if (controller.signal.aborted || n > max) {
+                resolve(null);
+            }
+            else {
+                hashChallenge(salt, n, algorithm)
+                    .then((t) => {
+                    if (t === challenge) {
+                        resolve({
+                            number: n,
+                            took: Date.now() - startTime,
+                        });
+                    }
+                    else {
+                        next(n + 1);
+                    }
+                })
+                    .catch(reject);
+            }
+        };
+        next(start);
+    });
+    return {
+        promise,
+        controller,
+    };
+}
+export async function solveChallengeWorkers(workerScript, concurrency, challenge, salt, algorithm = 'SHA-256', max = 1e6, startNumber = 0) {
+    const workers = [];
+    if (concurrency < 1) {
+        throw new Error('Wrong number of workers configured.');
+    }
+    if (concurrency > 16) {
+        throw new Error('Too many workers. Max. 16 allowed workers.');
+    }
+    for (let i = 0; i < concurrency; i++) {
+        if (typeof workerScript === 'function') {
+            workers.push(workerScript());
+        }
+        else {
+            workers.push(new Worker(workerScript, {
+                type: 'module',
+            }));
+        }
+    }
+    const step = Math.ceil(max / concurrency);
+    const solutions = await Promise.all(workers.map((worker, i) => {
+        const start = startNumber + i * step;
+        return new Promise((resolve) => {
+            worker.addEventListener('message', (message) => {
+                if (message.data) {
+                    for (const w of workers) {
+                        if (w !== worker) {
+                            w.postMessage({ type: 'abort' });
+                        }
+                    }
+                }
+                resolve(message.data);
+            });
+            worker.postMessage({
+                payload: {
+                    algorithm,
+                    challenge,
+                    max: start + step,
+                    salt,
+                    start,
+                },
+                type: 'work',
+            });
+        });
+    }));
+    for (const worker of workers) {
+        worker.terminate();
+    }
+    return solutions.find((solution) => !!solution) || null;
+}
+async function hashChallenge(salt, num, algorithm) {
+    return ab2hex(await crypto.subtle.digest(algorithm.toUpperCase(), encoder.encode(salt + num)));
+}

package/dist/types.d.ts

@@ -2,6 +2,7 @@ export type Algorithm = 'SHA-1' | 'SHA-256' | 'SHA-512';
 export interface Challenge {
     algorithm: Algorithm;
     challenge: string;
+    max?: number;
     salt: string;
     signature: string;
 }
@@ -20,3 +21,8 @@ export interface Payload {
     salt: string;
     signature: string;
 }
+export interface Solution {
+    number: number;
+    took: number;
+    worker?: boolean;
+}

package/dist/worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/worker.js

@@ -0,0 +1,17 @@
+import { solveChallenge } from './index.js';
+let controller = undefined;
+onmessage = async (message) => {
+    const { type, payload } = message.data;
+    if (type === 'abort') {
+        controller?.abort();
+        controller = undefined;
+    }
+    else if (type === 'work') {
+        const { alg, challenge, max, salt, start } = payload || {};
+        const result = solveChallenge(challenge, salt, alg, max, start);
+        controller = result.controller;
+        result.promise.then((solution) => {
+            self.postMessage(solution ? { ...solution, worker: true } : solution);
+        });
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "altcha-lib",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "A library for creating and verifying ALTCHA challenges for Node.js, Bun and Deno.",
   "author": "Daniel Regeci",
   "license": "MIT",
@@ -19,8 +19,9 @@
     "denoify": "rimraf deno_dist && denoify && find deno_dist/. -type f -exec sed -i '' -e 's/node:node:/node:/g' {} +",
     "eslint": "eslint ./lib/**/*",
     "format": "prettier --write './(lib|tests)/**/*'",
-    "test": "vitest",
-    "test:deno": "deno test tests/deno.ts"
+    "test": "vitest --run",
+    "test:deno": "deno test --allow-read tests/deno.ts",
+    "prepare": "husky"
   },
   "files": [
     "cjs",
@@ -36,6 +37,12 @@
     "./types": {
       "types": "./dist/types.d.ts",
       "import": "./dist/types.js"
+    },
+    "./worker": {
+      "types": "./dist/worker.d.ts",
+      "import": "./dist/worker.js",
+      "require": "./cjs/dist/worker.js",
+      "default": "./dist/worker.js"
     }
   },
   "typesVersions": {
@@ -50,6 +57,7 @@
     "@typescript-eslint/eslint-plugin": "^6.21.0",
     "denoify": "^1.6.9",
     "eslint": "^8.56.0",
+    "husky": "^9.0.11",
     "prettier": "^3.2.5",
     "rimraf": "^5.0.5",
     "ts-node": "^10.9.1",