altcha-lib 0.5.1 → 1.0.0

package/README.md

@@ -1,6 +1,6 @@
 # ALTCHA JS Library
 
-ALTCHA JS Library is a lightweight, zero-dependency library designed for creating and verifying [ALTCHA](https://altcha.org) challenges specifically tailored for Node.js, Bun, and Deno environments.
+ALTCHA JS Library is a lightweight, zero-dependency library designed for creating and verifying [ALTCHA](https://altcha.org) challenges.
 
 ## Compatibility
 
@@ -9,6 +9,7 @@ This library utilizes [Web Crypto](https://developer.mozilla.org/en-US/docs/Web/
 - Node.js 16+
 - Bun 1+
 - Deno 1+
+- WinterCG-compatible runtimes
 - All modern browsers
 
 ## Usage

package/cjs/dist/helpers.d.ts

@@ -1,9 +1,57 @@
 import type { Algorithm } from './types.js';
 export declare const encoder: TextEncoder;
+/**
+ * Converts an ArrayBuffer or Uint8Array to a hexadecimal string.
+ *
+ * @param ab - The ArrayBuffer or Uint8Array to convert.
+ * @returns The hexadecimal string representation of the input.
+ */
 export declare function ab2hex(ab: ArrayBuffer | Uint8Array): string;
+/**
+ * Generates a cryptographic hash using the specified algorithm.
+ *
+ * @param algorithm - The cryptographic hash algorithm to use (e.g., 'SHA-256').
+ * @param data - The data to hash, either as a string or ArrayBuffer.
+ * @returns A Promise that resolves to the computed hash as an ArrayBuffer.
+ */
 export declare function hash(algorithm: Algorithm, data: ArrayBuffer | string): Promise<ArrayBuffer>;
+/**
+ * Generates a cryptographic hash using the specified algorithm and returns it as a hexadecimal string.
+ *
+ * @param algorithm - The cryptographic hash algorithm to use (e.g., 'SHA-256').
+ * @param data - The data to hash, either as a string or ArrayBuffer.
+ * @returns A Promise that resolves to the computed hash as a hexadecimal string.
+ */
 export declare function hashHex(algorithm: Algorithm, data: ArrayBuffer | string): Promise<string>;
+/**
+ * Generates an HMAC using the specified algorithm and secret key.
+ *
+ * @param algorithm - The cryptographic hash algorithm to use for HMAC (e.g., 'SHA-256').
+ * @param data - The data to sign, either as a string or ArrayBuffer.
+ * @param secret - The secret key to use for HMAC.
+ * @returns A Promise that resolves to the computed HMAC as an ArrayBuffer.
+ */
 export declare function hmac(algorithm: Algorithm, data: ArrayBuffer | string, secret: string): Promise<ArrayBuffer>;
+/**
+ * Generates an HMAC using the specified algorithm and secret key, and returns it as a hexadecimal string.
+ *
+ * @param algorithm - The cryptographic hash algorithm to use for HMAC (e.g., 'SHA-256').
+ * @param data - The data to sign, either as a string or ArrayBuffer.
+ * @param secret - The secret key to use for HMAC.
+ * @returns A Promise that resolves to the computed HMAC as a hexadecimal string.
+ */
 export declare function hmacHex(algorithm: Algorithm, data: ArrayBuffer | string, secret: string): Promise<string>;
+/**
+ * Generates a random sequence of bytes of the specified length.
+ *
+ * @param length - The number of random bytes to generate.
+ * @returns A Uint8Array containing the random bytes.
+ */
 export declare function randomBytes(length: number): Uint8Array;
+/**
+ * Generates a random integer between 1 and the specified maximum value (inclusive).
+ *
+ * @param max - The maximum value for the random integer.
+ * @returns A random integer between 1 and the specified max value.
+ */
 export declare function randomInt(max: number): number;

package/cjs/dist/helpers.js

@@ -1,21 +1,54 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.randomInt = exports.randomBytes = exports.hmacHex = exports.hmac = exports.hashHex = exports.hash = exports.ab2hex = exports.encoder = void 0;
+exports.encoder = void 0;
+exports.ab2hex = ab2hex;
+exports.hash = hash;
+exports.hashHex = hashHex;
+exports.hmac = hmac;
+exports.hmacHex = hmacHex;
+exports.randomBytes = randomBytes;
+exports.randomInt = randomInt;
+// Create a TextEncoder instance to convert strings to UTF-8 byte arrays.
 exports.encoder = new TextEncoder();
+/**
+ * Converts an ArrayBuffer or Uint8Array to a hexadecimal string.
+ *
+ * @param ab - The ArrayBuffer or Uint8Array to convert.
+ * @returns The hexadecimal string representation of the input.
+ */
 function ab2hex(ab) {
     return [...new Uint8Array(ab)]
         .map((x) => x.toString(16).padStart(2, '0'))
         .join('');
 }
-exports.ab2hex = ab2hex;
+/**
+ * Generates a cryptographic hash using the specified algorithm.
+ *
+ * @param algorithm - The cryptographic hash algorithm to use (e.g., 'SHA-256').
+ * @param data - The data to hash, either as a string or ArrayBuffer.
+ * @returns A Promise that resolves to the computed hash as an ArrayBuffer.
+ */
 async function hash(algorithm, data) {
     return crypto.subtle.digest(algorithm.toUpperCase(), typeof data === 'string' ? exports.encoder.encode(data) : new Uint8Array(data));
 }
-exports.hash = hash;
+/**
+ * Generates a cryptographic hash using the specified algorithm and returns it as a hexadecimal string.
+ *
+ * @param algorithm - The cryptographic hash algorithm to use (e.g., 'SHA-256').
+ * @param data - The data to hash, either as a string or ArrayBuffer.
+ * @returns A Promise that resolves to the computed hash as a hexadecimal string.
+ */
 async function hashHex(algorithm, data) {
     return ab2hex(await hash(algorithm, data));
 }
-exports.hashHex = hashHex;
+/**
+ * Generates an HMAC using the specified algorithm and secret key.
+ *
+ * @param algorithm - The cryptographic hash algorithm to use for HMAC (e.g., 'SHA-256').
+ * @param data - The data to sign, either as a string or ArrayBuffer.
+ * @param secret - The secret key to use for HMAC.
+ * @returns A Promise that resolves to the computed HMAC as an ArrayBuffer.
+ */
 async function hmac(algorithm, data, secret) {
     const key = await crypto.subtle.importKey('raw', exports.encoder.encode(secret), {
         name: 'HMAC',
@@ -23,21 +56,37 @@ async function hmac(algorithm, data, secret) {
     }, false, ['sign', 'verify']);
     return crypto.subtle.sign('HMAC', key, typeof data === 'string' ? exports.encoder.encode(data) : new Uint8Array(data));
 }
-exports.hmac = hmac;
+/**
+ * Generates an HMAC using the specified algorithm and secret key, and returns it as a hexadecimal string.
+ *
+ * @param algorithm - The cryptographic hash algorithm to use for HMAC (e.g., 'SHA-256').
+ * @param data - The data to sign, either as a string or ArrayBuffer.
+ * @param secret - The secret key to use for HMAC.
+ * @returns A Promise that resolves to the computed HMAC as a hexadecimal string.
+ */
 async function hmacHex(algorithm, data, secret) {
     return ab2hex(await hmac(algorithm, data, secret));
 }
-exports.hmacHex = hmacHex;
+/**
+ * Generates a random sequence of bytes of the specified length.
+ *
+ * @param length - The number of random bytes to generate.
+ * @returns A Uint8Array containing the random bytes.
+ */
 function randomBytes(length) {
     const ab = new Uint8Array(length);
     crypto.getRandomValues(ab);
     return ab;
 }
-exports.randomBytes = randomBytes;
+/**
+ * Generates a random integer between 1 and the specified maximum value (inclusive).
+ *
+ * @param max - The maximum value for the random integer.
+ * @returns A random integer between 1 and the specified max value.
+ */
 function randomInt(max) {
     const ab = new Uint32Array(1);
     crypto.getRandomValues(ab);
     const randomNumber = ab[0] / (0xffffffff + 1);
     return Math.floor(randomNumber * max + 1);
 }
-exports.randomInt = randomInt;

package/cjs/dist/index.js

@@ -1,6 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.solveChallengeWorkers = exports.solveChallenge = exports.verifyServerSignature = exports.verifyFieldsHash = exports.verifySolution = exports.extractParams = exports.createChallenge = void 0;
+exports.createChallenge = createChallenge;
+exports.extractParams = extractParams;
+exports.verifySolution = verifySolution;
+exports.verifyFieldsHash = verifyFieldsHash;
+exports.verifyServerSignature = verifyServerSignature;
+exports.solveChallenge = solveChallenge;
+exports.solveChallengeWorkers = solveChallengeWorkers;
 const helpers_js_1 = require("./helpers.js");
 const DEFAULT_MAX_NUMBER = 1e6;
 const DEFAULT_SALT_LEN = 12;
@@ -24,7 +30,7 @@ async function createChallenge(options) {
     if (Object.keys(Object.fromEntries(params)).length) {
         salt = salt + '?' + params.toString();
     }
-    const number = options.number === void 0 ? (0, helpers_js_1.randomInt)(maxnumber) : options.number;
+    const number = options.number === undefined ? (0, helpers_js_1.randomInt)(maxnumber) : options.number;
     const challenge = await (0, helpers_js_1.hashHex)(algorithm, salt + number);
     return {
         algorithm,
@@ -34,7 +40,6 @@ async function createChallenge(options) {
         signature: await (0, helpers_js_1.hmacHex)(algorithm, challenge, options.hmacKey),
     };
 }
-exports.createChallenge = createChallenge;
 /**
  * Extracts parameters from the payload.
  *
@@ -47,7 +52,6 @@ function extractParams(payload) {
     }
     return Object.fromEntries(new URLSearchParams(payload?.salt?.split('?')?.[1] || ''));
 }
-exports.extractParams = extractParams;
 /**
  * Verifies the solution provided by the client.
  *
@@ -66,10 +70,13 @@ async function verifySolution(payload, hmacKey, checkExpires = true) {
         }
     }
     const params = extractParams(payload);
-    const expires = params.expires || params.expire;
-    if (checkExpires && expires) {
+    if (checkExpires) {
+        const expires = params.expires || params.expire;
+        if (!expires) {
+            return false;
+        }
         const date = new Date(parseInt(expires, 10) * 1000);
-        if (!isNaN(date.getTime()) && date.getTime() < Date.now()) {
+        if (Number.isNaN(date.getTime()) || date.getTime() < Date.now()) {
             return false;
         }
     }
@@ -82,7 +89,6 @@ async function verifySolution(payload, hmacKey, checkExpires = true) {
     return (check.challenge === payload.challenge &&
         check.signature === payload.signature);
 }
-exports.verifySolution = verifySolution;
 /**
  * Verifies the hash of form fields.
  *
@@ -100,7 +106,6 @@ async function verifyFieldsHash(formData, fields, fieldsHash, algorithm = DEFAUL
     }
     return (await (0, helpers_js_1.hashHex)(algorithm, lines.join('\n'))) === fieldsHash;
 }
-exports.verifyFieldsHash = verifyFieldsHash;
 /**
  * Verifies the server's signature.
  *
@@ -131,7 +136,7 @@ async function verifyServerSignature(payload, hmacKey) {
             reasons: params.get('reasons')?.split(','),
             score: params.get('score')
                 ? parseFloat(params.get('score') || '0')
-                : void 0,
+                : undefined,
             time: parseInt(params.get('time') || '0', 10),
             verified: params.get('verified') === 'true',
         };
@@ -147,7 +152,6 @@ async function verifyServerSignature(payload, hmacKey) {
             payload.signature === signature,
     };
 }
-exports.verifyServerSignature = verifyServerSignature;
 /**
  * Solves a challenge by brute force.
  *
@@ -181,7 +185,6 @@ function solveChallenge(challenge, salt, algorithm = 'SHA-256', max = 1e6, start
         controller,
     };
 }
-exports.solveChallenge = solveChallenge;
 /**
  * Solves a challenge using web workers for parallel computation.
  *
@@ -238,7 +241,6 @@ async function solveChallengeWorkers(workerScript, concurrency, challenge, salt,
     }
     return solutions.find((solution) => !!solution) || null;
 }
-exports.solveChallengeWorkers = solveChallengeWorkers;
 exports.default = {
     createChallenge,
     extractParams,

package/dist/helpers.d.ts

@@ -1,9 +1,57 @@
 import type { Algorithm } from './types.js';
 export declare const encoder: TextEncoder;
+/**
+ * Converts an ArrayBuffer or Uint8Array to a hexadecimal string.
+ *
+ * @param ab - The ArrayBuffer or Uint8Array to convert.
+ * @returns The hexadecimal string representation of the input.
+ */
 export declare function ab2hex(ab: ArrayBuffer | Uint8Array): string;
+/**
+ * Generates a cryptographic hash using the specified algorithm.
+ *
+ * @param algorithm - The cryptographic hash algorithm to use (e.g., 'SHA-256').
+ * @param data - The data to hash, either as a string or ArrayBuffer.
+ * @returns A Promise that resolves to the computed hash as an ArrayBuffer.
+ */
 export declare function hash(algorithm: Algorithm, data: ArrayBuffer | string): Promise<ArrayBuffer>;
+/**
+ * Generates a cryptographic hash using the specified algorithm and returns it as a hexadecimal string.
+ *
+ * @param algorithm - The cryptographic hash algorithm to use (e.g., 'SHA-256').
+ * @param data - The data to hash, either as a string or ArrayBuffer.
+ * @returns A Promise that resolves to the computed hash as a hexadecimal string.
+ */
 export declare function hashHex(algorithm: Algorithm, data: ArrayBuffer | string): Promise<string>;
+/**
+ * Generates an HMAC using the specified algorithm and secret key.
+ *
+ * @param algorithm - The cryptographic hash algorithm to use for HMAC (e.g., 'SHA-256').
+ * @param data - The data to sign, either as a string or ArrayBuffer.
+ * @param secret - The secret key to use for HMAC.
+ * @returns A Promise that resolves to the computed HMAC as an ArrayBuffer.
+ */
 export declare function hmac(algorithm: Algorithm, data: ArrayBuffer | string, secret: string): Promise<ArrayBuffer>;
+/**
+ * Generates an HMAC using the specified algorithm and secret key, and returns it as a hexadecimal string.
+ *
+ * @param algorithm - The cryptographic hash algorithm to use for HMAC (e.g., 'SHA-256').
+ * @param data - The data to sign, either as a string or ArrayBuffer.
+ * @param secret - The secret key to use for HMAC.
+ * @returns A Promise that resolves to the computed HMAC as a hexadecimal string.
+ */
 export declare function hmacHex(algorithm: Algorithm, data: ArrayBuffer | string, secret: string): Promise<string>;
+/**
+ * Generates a random sequence of bytes of the specified length.
+ *
+ * @param length - The number of random bytes to generate.
+ * @returns A Uint8Array containing the random bytes.
+ */
 export declare function randomBytes(length: number): Uint8Array;
+/**
+ * Generates a random integer between 1 and the specified maximum value (inclusive).
+ *
+ * @param max - The maximum value for the random integer.
+ * @returns A random integer between 1 and the specified max value.
+ */
 export declare function randomInt(max: number): number;

package/dist/helpers.js

@@ -1,15 +1,44 @@
+// Create a TextEncoder instance to convert strings to UTF-8 byte arrays.
 export const encoder = new TextEncoder();
+/**
+ * Converts an ArrayBuffer or Uint8Array to a hexadecimal string.
+ *
+ * @param ab - The ArrayBuffer or Uint8Array to convert.
+ * @returns The hexadecimal string representation of the input.
+ */
 export function ab2hex(ab) {
     return [...new Uint8Array(ab)]
         .map((x) => x.toString(16).padStart(2, '0'))
         .join('');
 }
+/**
+ * Generates a cryptographic hash using the specified algorithm.
+ *
+ * @param algorithm - The cryptographic hash algorithm to use (e.g., 'SHA-256').
+ * @param data - The data to hash, either as a string or ArrayBuffer.
+ * @returns A Promise that resolves to the computed hash as an ArrayBuffer.
+ */
 export async function hash(algorithm, data) {
     return crypto.subtle.digest(algorithm.toUpperCase(), typeof data === 'string' ? encoder.encode(data) : new Uint8Array(data));
 }
+/**
+ * Generates a cryptographic hash using the specified algorithm and returns it as a hexadecimal string.
+ *
+ * @param algorithm - The cryptographic hash algorithm to use (e.g., 'SHA-256').
+ * @param data - The data to hash, either as a string or ArrayBuffer.
+ * @returns A Promise that resolves to the computed hash as a hexadecimal string.
+ */
 export async function hashHex(algorithm, data) {
     return ab2hex(await hash(algorithm, data));
 }
+/**
+ * Generates an HMAC using the specified algorithm and secret key.
+ *
+ * @param algorithm - The cryptographic hash algorithm to use for HMAC (e.g., 'SHA-256').
+ * @param data - The data to sign, either as a string or ArrayBuffer.
+ * @param secret - The secret key to use for HMAC.
+ * @returns A Promise that resolves to the computed HMAC as an ArrayBuffer.
+ */
 export async function hmac(algorithm, data, secret) {
     const key = await crypto.subtle.importKey('raw', encoder.encode(secret), {
         name: 'HMAC',
@@ -17,14 +46,34 @@ export async function hmac(algorithm, data, secret) {
     }, false, ['sign', 'verify']);
     return crypto.subtle.sign('HMAC', key, typeof data === 'string' ? encoder.encode(data) : new Uint8Array(data));
 }
+/**
+ * Generates an HMAC using the specified algorithm and secret key, and returns it as a hexadecimal string.
+ *
+ * @param algorithm - The cryptographic hash algorithm to use for HMAC (e.g., 'SHA-256').
+ * @param data - The data to sign, either as a string or ArrayBuffer.
+ * @param secret - The secret key to use for HMAC.
+ * @returns A Promise that resolves to the computed HMAC as a hexadecimal string.
+ */
 export async function hmacHex(algorithm, data, secret) {
     return ab2hex(await hmac(algorithm, data, secret));
 }
+/**
+ * Generates a random sequence of bytes of the specified length.
+ *
+ * @param length - The number of random bytes to generate.
+ * @returns A Uint8Array containing the random bytes.
+ */
 export function randomBytes(length) {
     const ab = new Uint8Array(length);
     crypto.getRandomValues(ab);
     return ab;
 }
+/**
+ * Generates a random integer between 1 and the specified maximum value (inclusive).
+ *
+ * @param max - The maximum value for the random integer.
+ * @returns A random integer between 1 and the specified max value.
+ */
 export function randomInt(max) {
     const ab = new Uint32Array(1);
     crypto.getRandomValues(ab);

package/dist/index.js

@@ -21,7 +21,7 @@ export async function createChallenge(options) {
     if (Object.keys(Object.fromEntries(params)).length) {
         salt = salt + '?' + params.toString();
     }
-    const number = options.number === void 0 ? randomInt(maxnumber) : options.number;
+    const number = options.number === undefined ? randomInt(maxnumber) : options.number;
     const challenge = await hashHex(algorithm, salt + number);
     return {
         algorithm,
@@ -61,10 +61,13 @@ export async function verifySolution(payload, hmacKey, checkExpires = true) {
         }
     }
     const params = extractParams(payload);
-    const expires = params.expires || params.expire;
-    if (checkExpires && expires) {
+    if (checkExpires) {
+        const expires = params.expires || params.expire;
+        if (!expires) {
+            return false;
+        }
         const date = new Date(parseInt(expires, 10) * 1000);
-        if (!isNaN(date.getTime()) && date.getTime() < Date.now()) {
+        if (Number.isNaN(date.getTime()) || date.getTime() < Date.now()) {
             return false;
         }
     }
@@ -124,7 +127,7 @@ export async function verifyServerSignature(payload, hmacKey) {
             reasons: params.get('reasons')?.split(','),
             score: params.get('score')
                 ? parseFloat(params.get('score') || '0')
-                : void 0,
+                : undefined,
             time: parseInt(params.get('time') || '0', 10),
             verified: params.get('verified') === 'true',
         };

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "altcha-lib",
-  "version": "0.5.1",
+  "version": "1.0.0",
   "description": "A library for creating and verifying ALTCHA challenges for Node.js, Bun and Deno.",
-  "author": "Daniel Regeci",
+  "author": {
+    "name": "Daniel Regeci",
+    "url": "https://altcha.org"
+  },
+  "homepage": "https://altcha.org",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/altcha-org/altcha-lib"
+  },
   "license": "MIT",
   "keywords": [
     "altcha",
@@ -53,16 +61,16 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^20.9.0",
-    "@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",
-    "tsx": "^4.0.0",
-    "typescript": "^5.2.2",
-    "vitest": "^1.0.1"
+    "@types/node": "^20.16.3",
+    "@typescript-eslint/eslint-plugin": "^8.4.0",
+    "denoify": "^1.6.13",
+    "eslint": "^8.57.0",
+    "husky": "^9.1.5",
+    "prettier": "^3.3.3",
+    "rimraf": "^5.0.10",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.4",
+    "vitest": "^1.6.0"
   }
 }