altcha-lib 0.1.4 → 0.2.0

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 can be used in modern browsers and supported server environments:
+This library utilizes [Web Crypto](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto) and is intended for server-side use.
 
 - Node.js 16+
 - Bun 1+
@@ -70,6 +70,17 @@ Parameters:
 
 Returns: `{ controller: AbortController, promise: Promise<Solution | null> }`
 
+### `verifyServerSignature(payload, hmacKey)`
+
+Verifies the server signature returned by the API. The payload can be a Base64-encoded JSON payload or an object.
+
+Parameters:
+
+- `payload: string | ServerSignaturePayload`
+- `hmacKey: string`
+
+Returns: `Promise<{ verificationData: ServerSignatureVerificationData | null, verified: boolean }>`
+
 ### `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. 
@@ -103,18 +114,16 @@ const solution = await solveChallengeWorkers(
 
 ```
 > 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%
+- n = 1,000...............................        317 ops/s ±2.63%
+- n = 10,000..............................         32 ops/s ±1.88%
+- n = 100,000.............................          3 ops/s ±0.34%
+- n = 500,000.............................          0 ops/s ±0.32%
 
 > 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%
+- n = 1,000...............................         66 ops/s ±3.44%
+- n = 10,000..............................         31 ops/s ±4.28%
+- n = 100,000.............................          7 ops/s ±4.40%
+- n = 500,000.............................          1 ops/s ±2.49%
 ```
 
 Run with Bun on MacBook Pro M3-Pro. See [/benchmark](/benchmark/) folder for more details.

package/cjs/dist/helpers.d.ts

@@ -2,7 +2,9 @@ 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>;
+export declare function hash(algorithm: Algorithm, data: ArrayBuffer | string): Promise<ArrayBuffer>;
+export declare function hashHex(algorithm: Algorithm, data: ArrayBuffer | string): Promise<string>;
+export declare function hmac(algorithm: Algorithm, data: ArrayBuffer | string, secret: string): Promise<ArrayBuffer>;
+export declare function hmacHex(algorithm: Algorithm, data: ArrayBuffer | string, secret: string): Promise<string>;
 export declare function randomBytes(length: number): Uint8Array;
 export declare function randomInt(max: number): number;

package/cjs/dist/helpers.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.randomInt = exports.randomBytes = exports.hmac = exports.hash = exports.ab2hex = exports.encoder = void 0;
+exports.randomInt = exports.randomBytes = exports.hmacHex = exports.hmac = exports.hashHex = exports.hash = exports.ab2hex = exports.encoder = void 0;
 // @denoify-line-ignore
 require("./crypto.js");
 exports.encoder = new TextEncoder();
@@ -10,18 +10,26 @@ function ab2hex(ab) {
         .join('');
 }
 exports.ab2hex = ab2hex;
-async function hash(algorithm, str) {
-    return ab2hex(await crypto.subtle.digest(algorithm.toUpperCase(), exports.encoder.encode(str)));
+async function hash(algorithm, data) {
+    return crypto.subtle.digest(algorithm.toUpperCase(), typeof data === 'string' ? exports.encoder.encode(data) : new Uint8Array(data));
 }
 exports.hash = hash;
-async function hmac(algorithm, str, secret) {
+async function hashHex(algorithm, data) {
+    return ab2hex(await hash(algorithm, data));
+}
+exports.hashHex = hashHex;
+async function hmac(algorithm, data, 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, exports.encoder.encode(str)));
+    return crypto.subtle.sign('HMAC', key, typeof data === 'string' ? exports.encoder.encode(data) : new Uint8Array(data));
 }
 exports.hmac = hmac;
+async function hmacHex(algorithm, data, secret) {
+    return ab2hex(await hmac(algorithm, data, secret));
+}
+exports.hmacHex = hmacHex;
 function randomBytes(length) {
     const ab = new Uint8Array(length);
     crypto.getRandomValues(ab);

package/cjs/dist/index.d.ts

@@ -1,8 +1,20 @@
-import type { Challenge, ChallengeOptions, Payload, Solution } from './types.js';
+import type { Challenge, ChallengeOptions, Payload, ServerSignaturePayload, ServerSignatureVerificationData, 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 verifyServerSignature(payload: string | ServerSignaturePayload, hmacKey: string): Promise<{
+    verificationData: ServerSignatureVerificationData | null;
+    verified: boolean | null;
+}>;
 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>;
+declare const _default: {
+    createChallenge: typeof createChallenge;
+    solveChallenge: typeof solveChallenge;
+    solveChallengeWorkers: typeof solveChallengeWorkers;
+    verifyServerSignature: typeof verifyServerSignature;
+    verifySolution: typeof verifySolution;
+};
+export default _default;

package/cjs/dist/index.js

@@ -1,23 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.solveChallengeWorkers = exports.solveChallenge = exports.verifySolution = exports.createChallenge = void 0;
+exports.solveChallengeWorkers = exports.solveChallenge = exports.verifyServerSignature = 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 max = options.maxNumber || DEFAULT_MAX_NUMBER;
+    const maxnumber = options.maxnumber || 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)(max) : options.number;
-    const challenge = await (0, helpers_js_1.hash)(algorithm, salt + number);
+    const number = options.number === void 0 ? (0, helpers_js_1.randomInt)(maxnumber) : options.number;
+    const challenge = await (0, helpers_js_1.hashHex)(algorithm, salt + number);
     return {
         algorithm,
         challenge,
-        max,
+        maxnumber,
         salt,
-        signature: await (0, helpers_js_1.hmac)(algorithm, challenge, options.hmacKey),
+        signature: await (0, helpers_js_1.hmacHex)(algorithm, challenge, options.hmacKey),
     };
 }
 exports.createChallenge = createChallenge;
@@ -35,6 +35,39 @@ async function verifySolution(payload, hmacKey) {
         check.signature === payload.signature);
 }
 exports.verifySolution = verifySolution;
+async function verifyServerSignature(payload, hmacKey) {
+    if (typeof payload === 'string') {
+        payload = JSON.parse(atob(payload));
+    }
+    const signature = await (0, helpers_js_1.hmacHex)(payload.algorithm, await (0, helpers_js_1.hash)(payload.algorithm, payload.verificationData), hmacKey);
+    let verificationData = null;
+    try {
+        const params = new URLSearchParams(payload.verificationData);
+        verificationData = {
+            ...Object.fromEntries(params),
+            expire: parseInt(params.get('expire') || '0', 10),
+            fields: params.get('fields')?.split(','),
+            reasons: params.get('reasons')?.split(','),
+            score: params.get('score')
+                ? parseFloat(params.get('score') || '0')
+                : void 0,
+            time: parseInt(params.get('time') || '0', 10),
+            verified: params.get('verified') === 'true',
+        };
+    }
+    catch {
+        // noop
+    }
+    return {
+        verificationData,
+        verified: payload.verified === true &&
+            verificationData &&
+            verificationData.verified === true &&
+            verificationData.expire > Math.floor(Date.now() / 1000) &&
+            payload.signature === signature,
+    };
+}
+exports.verifyServerSignature = verifyServerSignature;
 function solveChallenge(challenge, salt, algorithm = 'SHA-256', max = 1e6, start = 0) {
     const controller = new AbortController();
     const promise = new Promise((resolve, reject) => {
@@ -44,7 +77,7 @@ function solveChallenge(challenge, salt, algorithm = 'SHA-256', max = 1e6, start
                 resolve(null);
             }
             else {
-                hashChallenge(salt, n, algorithm)
+                (0, helpers_js_1.hashHex)(algorithm, salt + n)
                     .then((t) => {
                     if (t === challenge) {
                         resolve({
@@ -117,6 +150,10 @@ async function solveChallengeWorkers(workerScript, concurrency, challenge, salt,
     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)));
-}
+exports.default = {
+    createChallenge,
+    solveChallenge,
+    solveChallengeWorkers,
+    verifyServerSignature,
+    verifySolution,
+};

package/cjs/dist/types.d.ts

@@ -2,13 +2,14 @@ export type Algorithm = 'SHA-1' | 'SHA-256' | 'SHA-512';
 export interface Challenge {
     algorithm: Algorithm;
     challenge: string;
-    max?: number;
+    maxnumber?: number;
     salt: string;
     signature: string;
 }
 export interface ChallengeOptions {
     algorithm?: Algorithm;
     hmacKey: string;
+    maxnumber?: number;
     maxNumber?: number;
     number?: number;
     salt?: string;
@@ -21,6 +22,23 @@ export interface Payload {
     salt: string;
     signature: string;
 }
+export interface ServerSignaturePayload {
+    algorithm: Algorithm;
+    signature: string;
+    verificationData: string;
+    verified: boolean;
+}
+export interface ServerSignatureVerificationData {
+    classification?: string;
+    email?: string;
+    expire: number;
+    fields?: string[];
+    fieldsHash?: string;
+    reasons?: string[];
+    score?: number;
+    time: number;
+    verified: boolean;
+}
 export interface Solution {
     number: number;
     took: number;

package/dist/helpers.d.ts

@@ -2,7 +2,9 @@ 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>;
+export declare function hash(algorithm: Algorithm, data: ArrayBuffer | string): Promise<ArrayBuffer>;
+export declare function hashHex(algorithm: Algorithm, data: ArrayBuffer | string): Promise<string>;
+export declare function hmac(algorithm: Algorithm, data: ArrayBuffer | string, secret: string): Promise<ArrayBuffer>;
+export declare function hmacHex(algorithm: Algorithm, data: ArrayBuffer | string, secret: string): Promise<string>;
 export declare function randomBytes(length: number): Uint8Array;
 export declare function randomInt(max: number): number;

package/dist/helpers.js

@@ -6,15 +6,21 @@ export function ab2hex(ab) {
         .map((x) => x.toString(16).padStart(2, '0'))
         .join('');
 }
-export async function hash(algorithm, str) {
-    return ab2hex(await crypto.subtle.digest(algorithm.toUpperCase(), encoder.encode(str)));
+export async function hash(algorithm, data) {
+    return crypto.subtle.digest(algorithm.toUpperCase(), typeof data === 'string' ? encoder.encode(data) : new Uint8Array(data));
 }
-export async function hmac(algorithm, str, secret) {
+export async function hashHex(algorithm, data) {
+    return ab2hex(await hash(algorithm, data));
+}
+export async function hmac(algorithm, data, secret) {
     const key = await crypto.subtle.importKey('raw', encoder.encode(secret), {
         name: 'HMAC',
         hash: algorithm,
     }, false, ['sign', 'verify']);
-    return ab2hex(await crypto.subtle.sign('HMAC', key, encoder.encode(str)));
+    return crypto.subtle.sign('HMAC', key, typeof data === 'string' ? encoder.encode(data) : new Uint8Array(data));
+}
+export async function hmacHex(algorithm, data, secret) {
+    return ab2hex(await hmac(algorithm, data, secret));
 }
 export function randomBytes(length) {
     const ab = new Uint8Array(length);

package/dist/index.d.ts

@@ -1,8 +1,20 @@
-import type { Challenge, ChallengeOptions, Payload, Solution } from './types.js';
+import type { Challenge, ChallengeOptions, Payload, ServerSignaturePayload, ServerSignatureVerificationData, 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 verifyServerSignature(payload: string | ServerSignaturePayload, hmacKey: string): Promise<{
+    verificationData: ServerSignatureVerificationData | null;
+    verified: boolean | null;
+}>;
 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>;
+declare const _default: {
+    createChallenge: typeof createChallenge;
+    solveChallenge: typeof solveChallenge;
+    solveChallengeWorkers: typeof solveChallengeWorkers;
+    verifyServerSignature: typeof verifyServerSignature;
+    verifySolution: typeof verifySolution;
+};
+export default _default;

package/dist/index.js

@@ -1,20 +1,20 @@
-import { ab2hex, encoder, hash, hmac, randomBytes, randomInt, } from './helpers.js';
+import { ab2hex, hash, hashHex, hmacHex, 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 max = options.maxNumber || DEFAULT_MAX_NUMBER;
+    const maxnumber = options.maxnumber || 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(max) : options.number;
-    const challenge = await hash(algorithm, salt + number);
+    const number = options.number === void 0 ? randomInt(maxnumber) : options.number;
+    const challenge = await hashHex(algorithm, salt + number);
     return {
         algorithm,
         challenge,
-        max,
+        maxnumber,
         salt,
-        signature: await hmac(algorithm, challenge, options.hmacKey),
+        signature: await hmacHex(algorithm, challenge, options.hmacKey),
     };
 }
 export async function verifySolution(payload, hmacKey) {
@@ -30,6 +30,38 @@ export async function verifySolution(payload, hmacKey) {
     return (check.challenge === payload.challenge &&
         check.signature === payload.signature);
 }
+export async function verifyServerSignature(payload, hmacKey) {
+    if (typeof payload === 'string') {
+        payload = JSON.parse(atob(payload));
+    }
+    const signature = await hmacHex(payload.algorithm, await hash(payload.algorithm, payload.verificationData), hmacKey);
+    let verificationData = null;
+    try {
+        const params = new URLSearchParams(payload.verificationData);
+        verificationData = {
+            ...Object.fromEntries(params),
+            expire: parseInt(params.get('expire') || '0', 10),
+            fields: params.get('fields')?.split(','),
+            reasons: params.get('reasons')?.split(','),
+            score: params.get('score')
+                ? parseFloat(params.get('score') || '0')
+                : void 0,
+            time: parseInt(params.get('time') || '0', 10),
+            verified: params.get('verified') === 'true',
+        };
+    }
+    catch {
+        // noop
+    }
+    return {
+        verificationData,
+        verified: payload.verified === true &&
+            verificationData &&
+            verificationData.verified === true &&
+            verificationData.expire > Math.floor(Date.now() / 1000) &&
+            payload.signature === signature,
+    };
+}
 export function solveChallenge(challenge, salt, algorithm = 'SHA-256', max = 1e6, start = 0) {
     const controller = new AbortController();
     const promise = new Promise((resolve, reject) => {
@@ -39,7 +71,7 @@ export function solveChallenge(challenge, salt, algorithm = 'SHA-256', max = 1e6
                 resolve(null);
             }
             else {
-                hashChallenge(salt, n, algorithm)
+                hashHex(algorithm, salt + n)
                     .then((t) => {
                     if (t === challenge) {
                         resolve({
@@ -110,6 +142,10 @@ export async function solveChallengeWorkers(workerScript, concurrency, challenge
     }
     return solutions.find((solution) => !!solution) || null;
 }
-async function hashChallenge(salt, num, algorithm) {
-    return ab2hex(await crypto.subtle.digest(algorithm.toUpperCase(), encoder.encode(salt + num)));
-}
+export default {
+    createChallenge,
+    solveChallenge,
+    solveChallengeWorkers,
+    verifyServerSignature,
+    verifySolution,
+};

package/dist/types.d.ts

@@ -2,13 +2,14 @@ export type Algorithm = 'SHA-1' | 'SHA-256' | 'SHA-512';
 export interface Challenge {
     algorithm: Algorithm;
     challenge: string;
-    max?: number;
+    maxnumber?: number;
     salt: string;
     signature: string;
 }
 export interface ChallengeOptions {
     algorithm?: Algorithm;
     hmacKey: string;
+    maxnumber?: number;
     maxNumber?: number;
     number?: number;
     salt?: string;
@@ -21,6 +22,23 @@ export interface Payload {
     salt: string;
     signature: string;
 }
+export interface ServerSignaturePayload {
+    algorithm: Algorithm;
+    signature: string;
+    verificationData: string;
+    verified: boolean;
+}
+export interface ServerSignatureVerificationData {
+    classification?: string;
+    email?: string;
+    expire: number;
+    fields?: string[];
+    fieldsHash?: string;
+    reasons?: string[];
+    score?: number;
+    time: number;
+    verified: boolean;
+}
 export interface Solution {
     number: number;
     took: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "altcha-lib",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "A library for creating and verifying ALTCHA challenges for Node.js, Bun and Deno.",
   "author": "Daniel Regeci",
   "license": "MIT",