altcha-lib 1.4.1 → 2.0.0-beta.1

package/dist/esm/v2/types.d.ts

@@ -0,0 +1,277 @@
+export interface Challenge {
+    codeChallenge?: CodeChallenge;
+    parameters: ChallengeParameters;
+    signature?: string;
+}
+export interface ChallengeParameters {
+    algorithm: string;
+    nonce: string;
+    salt: string;
+    cost: number;
+    keyLength: number;
+    keyPrefix: string;
+    keySignature?: string;
+    memoryCost?: number;
+    parallelism?: number;
+    expiresAt?: number;
+    data?: Record<string, string | number | boolean | null>;
+}
+export interface CodeChallenge {
+    image: string;
+    audio?: string;
+    length?: number;
+}
+export interface CreateChallengeOptions {
+    /**
+     * Key derivation algorithm used for the challenge.
+     * Common values: `'PBKDF2/SHA-256'`, `'ARGON2ID'`, `'SCRYPT'`.
+     */
+    algorithm: string;
+    /**
+     * Randomly selected integer used as the starting counter in deterministic mode.
+     */
+    counter?: number;
+    /**
+     * Encoding format for the counter value.
+     * V2 uses `'uint32'`; `'string'` is supported for backward compatibility with V1.
+     */
+    counterMode?: 'uint32' | 'string';
+    /**
+     * Algorithm-specific cost parameter controlling computational difficulty
+     * (e.g., iteration count for PBKDF2, time cost for Argon2id).
+     */
+    cost: number;
+    /**
+     * Arbitrary key-value metadata embedded in the challenge.
+     */
+    data?: Record<string, string | number | boolean | null>;
+    /**
+     * Algorithm-specific key derivation function used to generate challenge keys.
+     */
+    deriveKey: DeriveKeyFunction;
+    /**
+     * Timestamp in seconds or Date after which the challenge is no longer valid.
+     */
+    expiresAt?: number | Date;
+    /**
+     * HMAC digest algorithm used for signing challenges.
+     * Defaults to `'SHA-256'`.
+     */
+    hmacAlgorithm?: HmacAlgorithm;
+    /**
+     * HMAC secret used to sign derived keys in deterministic mode.
+     */
+    hmacKeySignatureSecret?: string;
+    /**
+     * HMAC secret used to sign the challenge payload.
+     */
+    hmacSignatureSecret?: string;
+    /**
+     * Length of the derived key in bytes.
+     * Defaults to `32`.
+     */
+    keyLength?: number;
+    /**
+     * Required prefix that the derived key must match for the challenge to be solved.
+     */
+    keyPrefix?: string;
+    /**
+     * Number of bytes from the derived key used as the prefix in deterministic mode.
+     * Defaults to `keyLength / 2`.
+     */
+    keyPrefixLength?: number;
+    /**
+     * Algorithm-specific memory cost in KiB (applicable to Argon2id and scrypt).
+     */
+    memoryCost?: number;
+    /**
+     * Algorithm-specific parallelism setting controlling the parallelism
+     * (applicable to Argon2id and scrypt).
+     */
+    parallelism?: number;
+}
+export type DeriveKeyFunction = (parameters: ChallengeParameters, salt: Uint8Array, password: Uint8Array) => Promise<DeriveKeyFunctionResult>;
+export interface DeriveKeyFunctionResult {
+    parameters?: Partial<ChallengeParameters>;
+    derivedKey: Uint8Array;
+}
+export declare enum HmacAlgorithm {
+    SHA_256 = "SHA-256",
+    SHA_384 = "SHA-384",
+    SHA_512 = "SHA-512"
+}
+export interface Payload {
+    challenge: Omit<Challenge, 'codeChallenge'>;
+    solution: Solution;
+}
+export interface PayloadV1 {
+    algorithm: string;
+    challenge: string;
+    number: number;
+    salt: string;
+    signature?: string;
+    took: number;
+}
+export interface SetCookieOptions {
+    domain?: string;
+    name?: string;
+    maxAge?: number;
+    path?: string;
+    sameSite?: string;
+    secure?: boolean;
+}
+export type ServerClassification = 'BAD' | 'GOOD' | 'NEUTRAL';
+export interface ServerSignaturePayload {
+    algorithm: string;
+    apiKey?: string;
+    id?: string;
+    signature: string;
+    verificationData: string;
+    verified: boolean;
+}
+export interface ServerSignatureVerificationData {
+    [key: string]: string | unknown;
+    classification?: ServerClassification;
+    email?: string;
+    expire?: number;
+    fields?: string[];
+    fieldsHash?: string;
+    id?: string;
+    ipAddress?: string;
+    reasons?: string[];
+    score?: number;
+    time?: number;
+    verified?: boolean;
+}
+export interface ServerVerificationResult {
+    algorithm?: string;
+    apiKey?: string;
+    id?: string;
+    payload?: string;
+    reason?: string;
+    score?: number;
+    signature?: string;
+    verificationData?: string;
+    verified?: boolean;
+}
+export interface SolveChallengeOptions {
+    /**
+     * Challenge object to solve, either decoded from a server payload
+     * or as originally returned by `createChallenge`.
+     */
+    challenge: Challenge;
+    /**
+     * AbortController for cancelling the solve operation before completion.
+     */
+    controller?: AbortController;
+    /**
+     * Initial counter value to begin iterating from.
+     * Useful for resuming or partitioning work across multiple solvers.
+     */
+    counterStart?: number;
+    /**
+     * Increment between counter attempts.
+     * Defaults to `1`.
+     */
+    counterStep?: number;
+    /**
+     * Encoding format for the counter value.
+     * V2 uses `'uint32'`; `'string'` is supported for backward compatibility with V1.
+     */
+    counterMode?: 'uint32' | 'string';
+    /**
+     * Algorithm-specific key derivation function used to compute candidate keys
+     * for each counter value until a match is found.
+     */
+    deriveKey: DeriveKeyFunction;
+    /**
+     * Maximum time in milliseconds before the solve attempt is aborted.
+     * Defaults to `90_000` (90 seconds).
+     */
+    timeout?: number;
+}
+export interface Strings {
+    ariaLinkLabel: string;
+    enterCode: string;
+    enterCodeAria: string;
+    error: string;
+    expired: string;
+    footer: string;
+    getAudioChallenge: string;
+    label: string;
+    loading: string;
+    reload: string;
+    verify: string;
+    verificationRequired: string;
+    verified: string;
+    verifying: string;
+    waitAlert: string;
+}
+export declare enum State {
+    CODE = "code",
+    ERROR = "error",
+    VERIFIED = "verified",
+    VERIFYING = "verifying",
+    UNVERIFIED = "unverified",
+    EXPIRED = "expired"
+}
+export interface Solution {
+    counter: number;
+    derivedKey: string;
+    time?: number;
+}
+export interface VerifyOptions {
+    concurrency?: number;
+    controller?: AbortController;
+    minDuration?: number;
+}
+export interface VerifyResult {
+    challenge?: Challenge;
+    payload: string;
+    solution?: Solution;
+}
+export interface VerifyServerSignatureResult extends VerifySolutionResult {
+    verificationData?: ServerSignatureVerificationData | null;
+}
+export interface VerifySolutionOptions {
+    /**
+     * Challenge object to verify against, either decoded from the client payload
+     * or as originally returned by `createChallenge`.
+     */
+    challenge: Challenge;
+    /**
+     * Encoding format for the counter value.
+     * V2 uses `'uint32'`; `'string'` is supported for backward compatibility with V1.
+     */
+    counterMode?: 'uint32' | 'string';
+    /**
+     * Algorithm-specific key derivation function used to recompute the expected key
+     * during verification.
+     */
+    deriveKey: DeriveKeyFunction;
+    /**
+     * HMAC digest algorithm used when verifying challenge signatures.
+     * Defaults to `'SHA-256'`.
+     */
+    hmacAlgorithm?: HmacAlgorithm;
+    /**
+     * HMAC secret used to verify derived-key signatures in deterministic mode.
+     */
+    hmacKeySignatureSecret?: string;
+    /**
+     * HMAC secret used to verify the challenge payload signature.
+     */
+    hmacSignatureSecret: string;
+    /**
+     * Solution object to validate, either decoded from the client payload
+     * or as returned by `solveChallenge`.
+     */
+    solution: Solution;
+}
+export interface VerifySolutionResult {
+    expired: boolean;
+    invalidSignature: boolean | null;
+    invalidSolution: boolean | null;
+    time: number;
+    verified: boolean;
+}

package/dist/esm/v2/types.js

@@ -0,0 +1,15 @@
+export var HmacAlgorithm;
+(function (HmacAlgorithm) {
+    HmacAlgorithm["SHA_256"] = "SHA-256";
+    HmacAlgorithm["SHA_384"] = "SHA-384";
+    HmacAlgorithm["SHA_512"] = "SHA-512";
+})(HmacAlgorithm || (HmacAlgorithm = {}));
+export var State;
+(function (State) {
+    State["CODE"] = "code";
+    State["ERROR"] = "error";
+    State["VERIFIED"] = "verified";
+    State["VERIFYING"] = "verifying";
+    State["UNVERIFIED"] = "unverified";
+    State["EXPIRED"] = "expired";
+})(State || (State = {}));

package/dist/esm/v2/workers/argon2id.d.ts

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

package/dist/esm/v2/workers/argon2id.js

@@ -0,0 +1,5 @@
+import { handler } from './shared.js';
+import { deriveKey } from '../algorithms/argon2id.js';
+handler({
+    deriveKey,
+});

package/dist/esm/v2/workers/pbkdf2.d.ts

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

package/dist/esm/v2/workers/pbkdf2.js

@@ -0,0 +1,5 @@
+import { handler } from './shared.js';
+import { deriveKey } from '../algorithms/pbkdf2.js';
+handler({
+    deriveKey,
+});

package/dist/esm/v2/workers/scrypt.d.ts

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

package/dist/esm/v2/workers/scrypt.js

@@ -0,0 +1,5 @@
+import { handler } from './shared.js';
+import { deriveKey } from '../algorithms/scrypt.js';
+handler({
+    deriveKey,
+});

package/dist/esm/v2/workers/sha.d.ts

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

package/dist/esm/v2/workers/sha.js

@@ -0,0 +1,5 @@
+import { handler } from './shared.js';
+import { deriveKey } from '../algorithms/sha.js';
+handler({
+    deriveKey,
+});

package/dist/esm/v2/workers/shared.d.ts

@@ -0,0 +1,4 @@
+import type { DeriveKeyFunction } from '../types.js';
+export declare function handler(options: {
+    deriveKey: DeriveKeyFunction;
+}): void;

package/dist/esm/v2/workers/shared.js

@@ -0,0 +1,29 @@
+import { solveChallenge } from '../pow.js';
+export function handler(options) {
+    const { deriveKey } = options;
+    let controller = undefined;
+    self.onmessage = async (message) => {
+        const { challenge, counterMode, counterStart, counterStep, type } = message.data;
+        if (type === 'abort') {
+            controller?.abort();
+        }
+        else if (type === 'work') {
+            controller = new AbortController();
+            let solution;
+            try {
+                solution = await solveChallenge({
+                    challenge,
+                    controller,
+                    counterStart,
+                    counterStep,
+                    deriveKey,
+                    counterMode,
+                });
+            }
+            catch (err) {
+                return self.postMessage({ error: err });
+            }
+            self.postMessage(solution);
+        }
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "altcha-lib",
-  "version": "1.4.1",
-  "description": "A library for creating and verifying ALTCHA challenges for Node.js, Bun and Deno.",
+  "version": "2.0.0-beta.1",
+  "description": "A lightweight library for creating and verifying ALTCHA challenges on the server.",
   "author": {
     "name": "Daniel Regeci",
     "url": "https://altcha.org"
@@ -23,55 +23,166 @@
   "types": "./dist/index.d.ts",
   "type": "module",
   "scripts": {
-    "build": "rimraf dist && rimraf cjs/dist && tsc -b tsconfig.build.json tsconfig.cjs.json",
-    "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)/**/*'",
+    "build": "rimraf dist && tsc -b tsconfig.build.json tsconfig.cjs.json",
+    "lint": "eslint ./src/**/*",
+    "format": "prettier --write './(src|tests)/**/*'",
     "test": "vitest --run",
-    "test:deno": "deno test --allow-read tests/deno.ts",
     "prepare": "husky"
   },
   "files": [
-    "cjs",
     "dist"
   ],
+  "bin": {
+    "altcha-lib": "./bin/cli.mjs"
+  },
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./cjs/dist/index.js",
-      "default": "./dist/index.js"
+      "types": "./dist/esm/v2/index.d.ts",
+      "import": "./dist/esm/v2/index.js",
+      "require": "./dist/cjs/v2/index.js",
+      "default": "./dist/esm/v2/index.js"
+    },
+    "./algorithms/*": {
+      "types": "./dist/esm/v2/algorithms/*.d.ts",
+      "import": "./dist/esm/v2/algorithms/*.js",
+      "require": "./dist/cjs/v2/algorithms/*.js"
+    },
+    "./frameworks/*": {
+      "types": "./dist/esm/v2/frameworks/*.d.ts",
+      "import": "./dist/esm/v2/frameworks/*.js",
+      "require": "./dist/cjs/v2/frameworks/*.js"
+    },
+    "./obfuscation": {
+      "types": "./dist/esm/v2/obfuscation.d.ts",
+      "import": "./dist/esm/v2/obfuscation.js",
+      "require": "./dist/cjs/v2/obfuscation.js"
+    },
+    "./workers/*": {
+      "types": "./dist/esm/v2/workers/*.d.ts",
+      "import": "./dist/esm/v2/workers/*.js",
+      "require": "./dist/cjs/v2/workers/*.js"
     },
     "./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"
+      "types": "./dist/esm/v2/types.d.ts",
+      "import": "./dist/esm/v2/types.js"
+    },
+    "./v1": {
+      "types": "./dist/esm/v1/index.d.ts",
+      "import": "./dist/esm/v1/index.js",
+      "require": "./dist/cjs/v1/index.js",
+      "default": "./dist/esm/v1/index.js"
+    },
+    "./v1/types": {
+      "types": "./dist/esm/v1/types.d.ts",
+      "import": "./dist/esm/v1/types.js"
+    },
+    "./v1/worker": {
+      "types": "./dist/esm/v1/worker.d.ts",
+      "import": "./dist/esm/v1/worker.js",
+      "require": "./dist/cjs/v1/worker.js",
+      "default": "./dist/esm/v1/worker.js"
     }
   },
   "typesVersions": {
     "*": {
       "types": [
-        "./dist/types"
+        "./dist/esm/v2/types"
       ]
     }
   },
   "devDependencies": {
+    "@eslint/eslintrc": "^3.3.5",
+    "@eslint/js": "^10.0.1",
+    "@fastify/cookie": "^11.0.2",
+    "@fastify/cors": "^11.2.0",
+    "@fastify/formbody": "^8.0.2",
+    "@nestjs/common": "^11.1.16",
+    "@nestjs/core": "^11.1.16",
+    "@nestjs/platform-express": "^11.1.16",
+    "@sveltejs/kit": "^2.54.0",
+    "@types/cookie-parser": "^1.4.10",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.6",
     "@types/node": "^24.10.3",
+    "@types/supertest": "^7.2.0",
     "@typescript-eslint/eslint-plugin": "^8.49.0",
-    "denoify": "^1.6.17",
-    "eslint": "^8.57.1",
+    "cookie-parser": "^1.4.7",
+    "cors": "^2.8.6",
+    "eslint": "^10.0.3",
+    "express": "^5.2.1",
+    "fastify": "^5.8.2",
+    "globals": "^17.4.0",
+    "h3": "2.0.1-rc.16",
+    "hono": "^4.12.5",
     "husky": "^9.1.7",
-    "prettier": "^3.7.4",
-    "rimraf": "^6.1.2",
+    "prettier": "^3.8.1",
+    "rimraf": "^6.1.3",
+    "supertest": "^7.2.2",
     "ts-node": "^10.9.2",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "vite": "^7.2.7",
-    "vitest": "^4.0.15"
+    "vite": "^8.0.0",
+    "vitest": "^4.1.0",
+    "web-worker": "^1.5.0"
+  },
+  "peerDependencies": {
+    "@fastify/cookie": "^11.0.0",
+    "@fastify/cors": "^11.0.0",
+    "@fastify/formbody": "^8.0.0",
+    "@nestjs/common": "^10.0.0 || ^11.0.0",
+    "@nestjs/core": "^10.0.0 || ^11.0.0",
+    "@nestjs/platform-express": "^10.0.0 || ^11.0.0",
+    "@sveltejs/kit": "^2.0.0",
+    "cookie-parser": "^1.0.0",
+    "cors": "^2.0.0",
+    "express": "^4.0.0 || ^5.0.0",
+    "fastify": "^5.0.0",
+    "h3": "^2.0.0",
+    "hono": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@nestjs/common": {
+      "optional": true
+    },
+    "@nestjs/core": {
+      "optional": true
+    },
+    "@nestjs/platform-express": {
+      "optional": true
+    },
+    "@fastify/cookie": {
+      "optional": true
+    },
+    "@fastify/cors": {
+      "optional": true
+    },
+    "@fastify/formbody": {
+      "optional": true
+    },
+    "@sveltejs/kit": {
+      "optional": true
+    },
+    "cookie-parser": {
+      "optional": true
+    },
+    "cors": {
+      "optional": true
+    },
+    "express": {
+      "optional": true
+    },
+    "fastify": {
+      "optional": true
+    },
+    "h3": {
+      "optional": true
+    },
+    "hono": {
+      "optional": true
+    }
+  },
+  "overrides": {
+    "cookie": "^1.1.1",
+    "file-type": "^21.3.1"
   }
 }

package/cjs/dist/tsconfig.cjs.tsbuildinfo

@@ -1 +0,0 @@
-{"root":["../../lib/helpers.ts","../../lib/index.ts","../../lib/types.ts","../../lib/worker.ts"],"version":"5.9.3"}

package/cjs/package.json

@@ -1,3 +0,0 @@
-{
-    "type": "commonjs"
-}

package/dist/tsconfig.build.tsbuildinfo

@@ -1 +0,0 @@
-{"root":["../lib/helpers.ts","../lib/index.ts","../lib/types.ts","../lib/worker.ts"],"version":"5.9.3"}