Altcha-lib NPM

ALTCHA JS Library

ALTCHA JS Library is a lightweight, zero-dependency library designed for creating and verifying ALTCHA challenges specifically tailored for Node.js, Bun, and Deno environments.

Compatibility

This library utilizes Web Crypto and is intended for server-side use.

Node.js 16+
Bun 1+
Deno 1+

Usage

import { createChallenge, verifySolution } from 'altcha-lib';

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:
const ok = await verifySolution(payload, hmacKey);

API

`createChallenge(options)`

Creates a new challenge for ALTCHA.

Parameters:

options: ChallengeOptions:
- algorithm?: string: Algorithm to use (SHA-1, SHA-256, SHA-512, default: SHA-256).
- hmacKey: string (required): Signature HMAC key.
- maxNumber?: number Optional maximum number for the random number generator (defaults to 1,000,000).
- number?: number: Optional number to use. If not provided, a random number will be generated.
- 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.

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> }

`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 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:

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...............................        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...............................         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 folder for more details.