altcha-lib 2.0.0 → 2.0.1

package/README.md

@@ -20,6 +20,7 @@ If your framework is not listed, see the [Advanced Usage](/docs/advanced-usage.m
 
 - Advanced Usage: [`/docs/advanced-usage.md`](/docs/advanced-usage.md)
 - Algorithms: [`/docs/algorithms.md`](/docs/algorithms.md)
+- CLI Usage: [`/docs/cli.md`](/docs/cli.md)
 - Configuration Options: [`/docs/configuration-options.md`](/docs/configuration-options.md)
 - Obfuscation: [`/docs/obfuscation.md`](/docs/obfuscation.md)
 - Store: [`/docs/store.md`](/docs/store.md)

package/bin/cli.mjs

@@ -1,35 +1,290 @@
 #!/usr/bin/env node
 
+import { readFile } from 'node:fs/promises';
+import { Worker as NodeWorker } from 'node:worker_threads';
 import { obfuscate, deobfuscate } from 'altcha-lib/obfuscation';
+import { createChallenge, solveChallengeWorkers, verifySolution } from 'altcha-lib';
+
+const ALGORITHMS = [
+	'PBKDF2/SHA-256',
+	'PBKDF2/SHA-384',
+	'PBKDF2/SHA-512',
+	'SCRYPT',
+	'ARGON2ID',
+	'SHA-256',
+	'SHA-384',
+	'SHA-512',
+];
+
+const USAGE = `Usage: altcha-lib <command> [options]
+
+Commands:
+  obfuscate [data]       Obfuscate a string
+  deobfuscate [data]     Deobfuscate a string
+  create                 Create a new challenge
+  solve [challenge]      Solve a challenge (JSON)
+                         --workers <n>          Number of worker threads (default: 1)
+  verify [challenge] [solution]  Verify a challenge solution (JSON files or inline JSON)
+
+Options for create:
+  --algorithm <algo>         Algorithm (default: PBKDF2/SHA-256)
+                             Supported: ${ALGORITHMS.join(', ')}
+  --cost <n>                 Cost parameter (default: 5000 for SHA/PBKDF2, 16384 for SCRYPT, 3 for ARGON2ID)
+  --hmac-secret <secret>     HMAC secret for signing the challenge
+  --hmac-key-secret <secret> HMAC secret for signing the derived key (deterministic mode)
+  --counter <n>              Known counter value for deterministic mode
+  --expires <seconds>        Seconds until the challenge expires
+  --key-prefix <prefix>      Key prefix override
+  --memory-cost <n>          Memory cost (SCRYPT/ARGON2ID only)
+  --parallelism <n>          Parallelism (SCRYPT/ARGON2ID only)
+
+Options for verify:
+  --hmac-secret <secret>     HMAC secret used when creating the challenge
+  --hmac-key-secret <secret> HMAC key secret used when creating the challenge (deterministic mode)
+`;
 
 const [command, ...rest] = process.argv.slice(2);
 
-if (!command || !['obfuscate', 'deobfuscate'].includes(command)) {
-  console.error('Usage: altcha-lib <obfuscate|deobfuscate> [data]');
-  process.exit(1);
+const COMMANDS = ['obfuscate', 'deobfuscate', 'create', 'solve', 'verify'];
+
+if (!command || !COMMANDS.includes(command)) {
+	process.stderr.write(USAGE);
+	process.exit(1);
 }
 
 function readStdin() {
-  return new Promise((resolve, reject) => {
-    let buf = '';
-    process.stdin.setEncoding('utf-8');
-    process.stdin.on('data', (chunk) => buf += chunk);
-    process.stdin.on('end', () => resolve(buf.trim()));
-    process.stdin.on('error', reject);
-  });
+	return new Promise((resolve, reject) => {
+		let buf = '';
+		process.stdin.setEncoding('utf-8');
+		process.stdin.on('data', (chunk) => (buf += chunk));
+		process.stdin.on('end', () => resolve(buf.trim()));
+		process.stdin.on('error', reject);
+	});
 }
 
-try {
-  const data = rest.length ? rest.join(' ') : await readStdin();
+async function readInput(arg, label) {
+	let raw;
+	if (arg) {
+		try {
+			raw = (await readFile(arg, 'utf-8')).trim();
+		} catch {
+			// Not a readable file — treat as inline JSON string
+			raw = arg;
+		}
+	} else {
+		raw = await readStdin();
+	}
+	if (!raw) {
+		console.error(`Error: No ${label} provided`);
+		process.exit(1);
+	}
+	return raw;
+}
+
+function parseArgs(args) {
+	const opts = {};
+	const positional = [];
+	for (let i = 0; i < args.length; i++) {
+		if (args[i].startsWith('--')) {
+			const key = args[i].slice(2);
+			if (i + 1 < args.length && !args[i + 1].startsWith('--')) {
+				opts[key] = args[++i];
+			} else {
+				opts[key] = true;
+			}
+		} else {
+			positional.push(args[i]);
+		}
+	}
+	return { opts, positional };
+}
+
+function getWorkerName(algorithm) {
+	const algo = (algorithm || '').toUpperCase();
+	if (algo.startsWith('PBKDF2')) return 'pbkdf2';
+	if (algo === 'SCRYPT') return 'scrypt';
+	if (algo === 'ARGON2ID') return 'argon2id';
+	return 'sha';
+}
+
+function createWorker(algorithm) {
+	const workerModuleUrl = new URL(
+		`../dist/esm/v2/workers/${getWorkerName(algorithm)}.js`,
+		import.meta.url
+	).href;
+	// Shim Web Worker globals (self.onmessage / self.postMessage) so the
+	// existing dist worker modules work inside a node:worker_threads context.
+	const shim = `
+import { parentPort } from 'node:worker_threads';
+const self = { onmessage: null, postMessage(d) { parentPort.postMessage(d); } };
+globalThis.self = self;
+parentPort.on('message', (data) => { if (typeof self.onmessage === 'function') self.onmessage({ data }); });
+await import(${JSON.stringify(workerModuleUrl)});
+`;
+	const worker = new NodeWorker(
+		new URL(`data:text/javascript,${encodeURIComponent(shim)}`),
+		{ type: 'module' }
+	);
+	// Adapt EventEmitter API to the EventTarget API expected by solveChallengeWorkers.
+	worker.addEventListener = (event, handler) => {
+		worker.on(event === 'message' ? 'message' : event, (data) =>
+			event === 'message' ? handler({ data }) : handler(data)
+		);
+	};
+	return worker;
+}
 
-  if (!data) {
-    console.error(`Error: No data provided for ${command}`);
-    process.exit(1);
-  }
+async function getDeriveKey(algorithm) {
+	const algo = (algorithm || 'PBKDF2/SHA-256').toUpperCase();
+	if (algo.startsWith('PBKDF2')) {
+		const mod = await import('altcha-lib/algorithms/pbkdf2');
+		return mod.deriveKey;
+	} else if (algo === 'SCRYPT') {
+		const mod = await import('altcha-lib/algorithms/scrypt');
+		return mod.deriveKey;
+	} else if (algo === 'ARGON2ID') {
+		const mod = await import('altcha-lib/algorithms/argon2id');
+		return mod.deriveKey;
+	} else {
+		const mod = await import('altcha-lib/algorithms/sha');
+		return mod.deriveKey;
+	}
+}
+
+function getDefaultCost(algorithm) {
+	const algo = (algorithm || 'SHA-256').toUpperCase();
+	if (algo === 'SCRYPT') return 16384;
+	if (algo === 'ARGON2ID') return 3;
+	return 5000;
+}
 
-  const result = command === 'obfuscate' ? await obfuscate(data) : await deobfuscate(data);
-  console.log(result);
+function getDefaultMemoryCost(algorithm) {
+	const algo = (algorithm || '').toUpperCase();
+	if (algo === 'SCRYPT') return 8;
+	if (algo === 'ARGON2ID') return 65536;
+	return undefined;
+}
+
+try {
+	if (command === 'obfuscate' || command === 'deobfuscate') {
+		const data = rest.length ? rest.join(' ') : await readStdin();
+		if (!data) {
+			console.error(`Error: No data provided for ${command}`);
+			process.exit(1);
+		}
+		const result =
+			command === 'obfuscate' ? await obfuscate(data) : await deobfuscate(data);
+		console.log(result);
+	} else if (command === 'create') {
+		const { opts } = parseArgs(rest);
+		const algorithm = opts['algorithm'] || 'SHA-256';
+		const cost = opts['cost']
+			? parseInt(opts['cost'], 10)
+			: getDefaultCost(algorithm);
+		const hmacSecret = opts['hmac-secret'];
+		const hmacKeySecret = opts['hmac-key-secret'];
+		const counter = opts['counter'] !== undefined ? parseInt(opts['counter'], 10) : undefined;
+		const expires = opts['expires'] ? parseInt(opts['expires'], 10) : undefined;
+		const keyPrefix = opts['key-prefix'];
+		const memoryCost = opts['memory-cost']
+			? parseInt(opts['memory-cost'], 10)
+			: getDefaultMemoryCost(algorithm);
+		const parallelism = opts['parallelism']
+			? parseInt(opts['parallelism'], 10)
+			: undefined;
+
+		const deriveKey = await getDeriveKey(algorithm);
+		const challenge = await createChallenge({
+			algorithm,
+			cost,
+			counter,
+			deriveKey,
+			expiresAt: expires ? new Date(Date.now() + expires * 1000) : undefined,
+			hmacSignatureSecret: hmacSecret,
+			hmacKeySignatureSecret: hmacKeySecret,
+			keyPrefix,
+			memoryCost,
+			parallelism,
+		});
+		console.log(JSON.stringify(challenge, null, 2));
+	} else if (command === 'solve') {
+		const { opts, positional } = parseArgs(rest);
+		const workers = opts['workers'] ? parseInt(opts['workers'], 10) : undefined;
+		const raw = await readInput(positional.length ? positional[0] : null, 'challenge JSON');
+		let challenge;
+		try {
+			challenge = JSON.parse(raw);
+		} catch {
+			console.error('Error: Invalid JSON for challenge');
+			process.exit(1);
+		}
+		const algorithm = challenge?.parameters?.algorithm;
+		const solution = await solveChallengeWorkers({
+			challenge,
+			concurrency: workers ?? 1,
+			createWorker: () => createWorker(algorithm),
+		});
+		if (!solution) {
+			console.error('Error: Failed to solve challenge (timeout or aborted)');
+			process.exit(1);
+		}
+		console.log(JSON.stringify(solution, null, 2));
+	} else if (command === 'verify') {
+		const { opts, positional } = parseArgs(rest);
+		const hmacSecret = opts['hmac-secret'];
+		const hmacKeySecret = opts['hmac-key-secret'];
+		if (!hmacSecret) {
+			console.error('Error: --hmac-secret is required for verify');
+			process.exit(1);
+		}
+		let challenge, solution;
+		if (positional.length >= 2) {
+			const rawChallenge = await readInput(positional[0], 'challenge JSON');
+			const rawSolution = await readInput(positional[1], 'solution JSON');
+			try {
+				challenge = JSON.parse(rawChallenge);
+			} catch {
+				console.error('Error: Invalid JSON for challenge');
+				process.exit(1);
+			}
+			try {
+				solution = JSON.parse(rawSolution);
+			} catch {
+				console.error('Error: Invalid JSON for solution');
+				process.exit(1);
+			}
+		} else {
+			const raw = await readInput(positional.length ? positional[0] : null, 'payload JSON');
+			let payload;
+			try {
+				payload = JSON.parse(raw);
+			} catch {
+				console.error('Error: Invalid JSON for payload');
+				process.exit(1);
+			}
+			({ challenge, solution } = payload);
+			if (!challenge || !solution) {
+				console.error(
+					'Error: Payload must contain "challenge" and "solution" fields'
+				);
+				process.exit(1);
+			}
+		}
+		const algorithm = challenge?.parameters?.algorithm;
+		const deriveKey = await getDeriveKey(algorithm);
+		const result = await verifySolution({
+			challenge,
+			solution,
+			deriveKey,
+			hmacSignatureSecret: hmacSecret,
+			hmacKeySignatureSecret: hmacKeySecret,
+		});
+		console.log(JSON.stringify(result, null, 2));
+		if (!result.verified) {
+			process.exit(1);
+		}
+	}
 } catch (err) {
-  console.error(`Error during ${command}: ${err.message}`);
-  process.exit(1);
-}
+	console.error(`Error: ${err.message}`);
+	process.exit(1);
+}

package/dist/cjs/v2/pow.js

@@ -89,17 +89,18 @@ async function solveChallenge(options) {
     const password = new PasswordBuffer(nonceBuf, counterMode);
     const start = performance.now();
     let counter = counterStart;
+    let iterations = 0;
     let derivedKeyHex = '';
     let lastYield = start;
     while (true) {
         // Check for abort signal or timeout every 10 iterations.
         if (controller?.signal.aborted ||
-            (timeout && counter % 10 === 0 && performance.now() - start > timeout)) {
+            (timeout && iterations % 10 === 0 && performance.now() - start > timeout)) {
             return null;
         }
         const { derivedKey } = await deriveKey(challenge.parameters, saltBuf, password.setCounter(counter));
         // Yield to the event loop periodically.
-        if (counter % 10 === 0 && performance.now() - lastYield > 200) {
+        if (iterations % 10 === 0 && performance.now() - lastYield > 200) {
             await (0, helpers_js_1.delay)(0);
             lastYield = performance.now();
         }
@@ -111,6 +112,7 @@ async function solveChallenge(options) {
             break;
         }
         counter = counter + counterStep;
+        iterations = iterations + 1;
     }
     return {
         counter,

package/dist/esm/v2/pow.js

@@ -84,17 +84,18 @@ export async function solveChallenge(options) {
     const password = new PasswordBuffer(nonceBuf, counterMode);
     const start = performance.now();
     let counter = counterStart;
+    let iterations = 0;
     let derivedKeyHex = '';
     let lastYield = start;
     while (true) {
         // Check for abort signal or timeout every 10 iterations.
         if (controller?.signal.aborted ||
-            (timeout && counter % 10 === 0 && performance.now() - start > timeout)) {
+            (timeout && iterations % 10 === 0 && performance.now() - start > timeout)) {
             return null;
         }
         const { derivedKey } = await deriveKey(challenge.parameters, saltBuf, password.setCounter(counter));
         // Yield to the event loop periodically.
-        if (counter % 10 === 0 && performance.now() - lastYield > 200) {
+        if (iterations % 10 === 0 && performance.now() - lastYield > 200) {
             await delay(0);
             lastYield = performance.now();
         }
@@ -106,6 +107,7 @@ export async function solveChallenge(options) {
             break;
         }
         counter = counter + counterStep;
+        iterations = iterations + 1;
     }
     return {
         counter,

package/dist/tsconfig.build.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["../src/v1/helpers.ts","../src/v1/index.ts","../src/v1/types.ts","../src/v1/worker.ts","../src/v2/capped-map.ts","../src/v2/helpers.ts","../src/v2/index.ts","../src/v2/obfuscation.ts","../src/v2/pow.ts","../src/v2/server-signature.ts","../src/v2/types.ts","../src/v2/algorithms/argon2id.ts","../src/v2/algorithms/pbkdf2.ts","../src/v2/algorithms/scrypt.ts","../src/v2/algorithms/sha.ts","../src/v2/algorithms/web/pbkdf2.ts","../src/v2/algorithms/web/sha.ts","../src/v2/frameworks/express.ts","../src/v2/frameworks/fastify.ts","../src/v2/frameworks/h3.ts","../src/v2/frameworks/hono.ts","../src/v2/frameworks/nestjs.ts","../src/v2/frameworks/nextjs.ts","../src/v2/frameworks/shared.ts","../src/v2/frameworks/sveltekit.ts","../src/v2/frameworks/types.ts","../src/v2/workers/argon2id.ts","../src/v2/workers/pbkdf2.ts","../src/v2/workers/scrypt.ts","../src/v2/workers/sha.ts","../src/v2/workers/shared.ts"],"version":"5.9.3"}

package/dist/tsconfig.cjs.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["../src/v1/helpers.ts","../src/v1/index.ts","../src/v1/types.ts","../src/v1/worker.ts","../src/v2/capped-map.ts","../src/v2/helpers.ts","../src/v2/index.ts","../src/v2/obfuscation.ts","../src/v2/pow.ts","../src/v2/server-signature.ts","../src/v2/types.ts","../src/v2/algorithms/argon2id.ts","../src/v2/algorithms/pbkdf2.ts","../src/v2/algorithms/scrypt.ts","../src/v2/algorithms/sha.ts","../src/v2/algorithms/web/pbkdf2.ts","../src/v2/algorithms/web/sha.ts","../src/v2/frameworks/express.ts","../src/v2/frameworks/fastify.ts","../src/v2/frameworks/h3.ts","../src/v2/frameworks/hono.ts","../src/v2/frameworks/nestjs.ts","../src/v2/frameworks/nextjs.ts","../src/v2/frameworks/shared.ts","../src/v2/frameworks/sveltekit.ts","../src/v2/frameworks/types.ts","../src/v2/workers/argon2id.ts","../src/v2/workers/pbkdf2.ts","../src/v2/workers/scrypt.ts","../src/v2/workers/sha.ts","../src/v2/workers/shared.ts"],"version":"5.9.3"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "altcha-lib",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "A lightweight library for creating and verifying ALTCHA challenges on the server.",
   "author": {
     "name": "Daniel Regeci",
@@ -114,7 +114,7 @@
     "fastify": "^5.8.2",
     "globals": "^17.4.0",
     "h3": "^2.0.1-rc.18",
-    "hono": "^4.12.5",
+    "hono": "^4.12.12",
     "husky": "^9.1.7",
     "prettier": "^3.8.1",
     "rimraf": "^6.1.3",

package/dist/cjs/tsconfig.cjs.tsbuildinfo

@@ -1 +0,0 @@
-{"root":["../../src/v1/helpers.ts","../../src/v1/index.ts","../../src/v1/types.ts","../../src/v1/worker.ts","../../src/v2/capped-map.ts","../../src/v2/helpers.ts","../../src/v2/index.ts","../../src/v2/obfuscation.ts","../../src/v2/pow.ts","../../src/v2/server-signature.ts","../../src/v2/types.ts","../../src/v2/algorithms/argon2id.ts","../../src/v2/algorithms/pbkdf2.ts","../../src/v2/algorithms/scrypt.ts","../../src/v2/algorithms/sha.ts","../../src/v2/algorithms/web/pbkdf2.ts","../../src/v2/algorithms/web/sha.ts","../../src/v2/frameworks/express.ts","../../src/v2/frameworks/fastify.ts","../../src/v2/frameworks/h3.ts","../../src/v2/frameworks/hono.ts","../../src/v2/frameworks/nestjs.ts","../../src/v2/frameworks/nextjs.ts","../../src/v2/frameworks/shared.ts","../../src/v2/frameworks/sveltekit.ts","../../src/v2/frameworks/types.ts","../../src/v2/workers/argon2id.ts","../../src/v2/workers/pbkdf2.ts","../../src/v2/workers/scrypt.ts","../../src/v2/workers/sha.ts","../../src/v2/workers/shared.ts"],"version":"5.9.3"}

package/dist/esm/tsconfig.build.tsbuildinfo

@@ -1 +0,0 @@
-{"root":["../../src/v1/helpers.ts","../../src/v1/index.ts","../../src/v1/types.ts","../../src/v1/worker.ts","../../src/v2/capped-map.ts","../../src/v2/helpers.ts","../../src/v2/index.ts","../../src/v2/obfuscation.ts","../../src/v2/pow.ts","../../src/v2/server-signature.ts","../../src/v2/types.ts","../../src/v2/algorithms/argon2id.ts","../../src/v2/algorithms/pbkdf2.ts","../../src/v2/algorithms/scrypt.ts","../../src/v2/algorithms/sha.ts","../../src/v2/algorithms/web/pbkdf2.ts","../../src/v2/algorithms/web/sha.ts","../../src/v2/frameworks/express.ts","../../src/v2/frameworks/fastify.ts","../../src/v2/frameworks/h3.ts","../../src/v2/frameworks/hono.ts","../../src/v2/frameworks/nestjs.ts","../../src/v2/frameworks/nextjs.ts","../../src/v2/frameworks/shared.ts","../../src/v2/frameworks/sveltekit.ts","../../src/v2/frameworks/types.ts","../../src/v2/workers/argon2id.ts","../../src/v2/workers/pbkdf2.ts","../../src/v2/workers/scrypt.ts","../../src/v2/workers/sha.ts","../../src/v2/workers/shared.ts"],"version":"5.9.3"}