ALTCHA JS Library

ALTCHA TS/JS Library is a lightweight library for creating and verifying ALTCHA challenges on the server.

Installation

npm install altcha-lib

Usage

import { createChallenge, deriveHmacKeySecret, randomInt, verifySolution } from 'altcha-lib';
import { deriveKey } from 'altcha-lib/algorithms/pbkdf2';

const HMAC_SECRET = 'your-secret-key';
const HMAC_KEY_SECRET = 'your-other-secret-key';

// On the server: create a challenge and send it to the client
const challenge = await createChallenge({
  algorithm: 'PBKDF2/SHA-256',
  cost: 5_000,
	counter: randomInt(5_000, 10_000),
  deriveKey,
  hmacSignatureSecret: HMAC_SECRET,
	hmacKeySignatureSecret: HMAC_KEY_SECRET,
});

// On the server: verify the solution submitted by the client
const result = await verifySolution({
  challenge: payload.challenge,
  solution: payload.solution,
  deriveKey,
  hmacSignatureSecret: HMAC_SECRET,
	hmacKeySignatureSecret: HMAC_KEY_SECRET,
});

if (result.verified) {
  // challenge passed
}

Get Started

The library includes plugins for several popular frameworks to simplify integration.

• Express: /docs/express.md
• Fastify: /docs/fastify.md
• Hono: /docs/hono.md
• NestJS: /docs/nestjs.md
• Next.js: /docs/nextjs.md
• Nuxt: /docs/nuxt.md
• SvelteKit: /docs/sveltekit.md

If your framework is not listed, see the Advanced Usage guide for custom integrations.

Documentation

• Advanced Usage: /docs/advanced-usage.md
• Algorithms: /docs/algorithms.md
• CLI Usage: /docs/cli.md
• Configuration Options: /docs/configuration-options.md
• Obfuscation: /docs/obfuscation.md
• Store: /docs/store.md
• Usage with ALTCHA Sentinel: /docs/server-signatures.md
• Using the /verify Route: /docs/verify-route.md
• Workers: /docs/workers.md

Compatibility

| Runtime | Version | Notes | | ----------------- | ------: | ----------------------------------------------- | | Node.js | 20+ | Argon2 available natively in 24.7+ | | Bun | 1+ | Argon2 not available natively | | Deno | 2+ | Argon2 not available natively | | WinterCG runtimes | — | Use WebCrypto algorithms |

Run Examples

Express example (Node.js with tsx):

npx tsx examples/express-example.ts

Hono example (Bun):

bun run --port 3000 examples/hono-example.ts

Hono example (Deno):

deno serve --allow-net --sloppy-imports --port 3000 examples/hono-example.ts

Breaking Changes (v2)

Version 2 introduces a new proof-of-work mechanism and challenge format. See the PoW documentation for details.

While the overall usage remains similar, the library has been refactored and several function signatures have changed. Using the provided framework plugins is recommended. For unsupported frameworks or custom setups, refer to the Advanced Usage guide.

Compatibility with v1

The API for the previous PoW version (v1) remains available under the altcha-lib/v1 path:

import { createChallenge } from 'altcha-lib/v1';

API Reference

The default import path (altcha-lib) uses the v2 API. The v1 API is available at altcha-lib/v1.

v2 (altcha-lib)

createChallenge(options: CreateChallengeOptions): Promise<Challenge>

Creates a new proof-of-work challenge. Generates a random nonce and salt, optionally pre-computes a key prefix from a known counter value, and optionally signs the challenge with HMAC.

| Option | Type | Description | |---|---|---| | algorithm | string | Key derivation algorithm (e.g. 'PBKDF2/SHA-256', 'ARGON2ID', 'SCRYPT'). | | cost | number | Algorithm-specific cost controlling computational difficulty. | | deriveKey | DeriveKeyFunction | Key derivation function. | | counter | number? | Known counter value for deterministic mode. | | counterMode | 'uint32' \| 'string' | Counter encoding format. Defaults to 'uint32'. | | data | Record<string, ...>? | Arbitrary metadata embedded in the challenge. | | expiresAt | number \| Date? | Expiry timestamp (seconds) or Date. | | hmacAlgorithm | HmacAlgorithm? | HMAC digest algorithm. Defaults to 'SHA-256'. | | hmacKeySignatureSecret | string? | HMAC secret for signing derived keys (deterministic mode). | | hmacSignatureSecret | string? | HMAC secret for signing the challenge payload. | | keyLength | number? | Derived key length in bytes. Defaults to 32. | | keyPrefix | string? | Required prefix the derived key must match. | | keyPrefixLength | number? | Number of bytes used as prefix in deterministic mode. Defaults to keyLength / 2. | | memoryCost | number? | Memory cost in KiB (Argon2id/scrypt only). | | parallelism | number? | Parallelism setting (Argon2id/scrypt only). |

solveChallenge(options: SolveChallengeOptions): Promise<Solution | null>

Solves a challenge by brute-forcing counter values until the derived key starts with the required prefix. Returns null on timeout or abort.

| Option | Type | Description | |---|---|---| | challenge | Challenge | The challenge to solve. | | deriveKey | DeriveKeyFunction | Key derivation function. | | controller | AbortController? | For cancelling the solve operation. | | counterStart | number? | Initial counter value. Defaults to 0. | | counterStep | number? | Increment between attempts. Defaults to 1. | | counterMode | 'uint32' \| 'string'? | Counter encoding format. Defaults to 'uint32'. | | timeout | number? | Timeout in milliseconds. Defaults to 90000. |

solveChallengeWorkers(options): Promise<Solution | null>

Solves a challenge using multiple Web Workers in parallel. Each worker tests a different interleaved subset of counter values. Automatically retries with fewer workers on out-of-memory errors.

| Option | Type | Description | |---|---|---| | challenge | Challenge | The challenge to solve. | | concurrency | number | Number of workers to use (max 16). | | createWorker | (algorithm: string) => Worker \| Promise<Worker> | Factory function to create a worker. | | controller | AbortController? | For cancelling the solve operation. | | counterMode | 'uint32' \| 'string'? | Counter encoding format. | | onOutOfMemory | (concurrency: number) => number \| void? | Called on OOM; return new concurrency to retry or falsy to abort. | | timeout | number? | Timeout in milliseconds. |

verifySolution(options: VerifySolutionOptions): Promise<VerifySolutionResult>

Verifies a submitted solution against a challenge. Checks expiration, challenge signature integrity, and that the derived key matches the solution.

| Option | Type | Description | |---|---|---| | challenge | Challenge | The original challenge. | | solution | Solution | The solution to verify. | | hmacSignatureSecret | string | HMAC secret used when the challenge was created. | | deriveKey | DeriveKeyFunction | Key derivation function. | | counterMode | 'uint32' \| 'string'? | Counter encoding format. | | hmacAlgorithm | HmacAlgorithm? | HMAC digest algorithm. Defaults to 'SHA-256'. | | hmacKeySignatureSecret | string? | HMAC secret for verifying derived-key signatures. |

Returns VerifySolutionResult:

| Field | Type | Description | |---|---|---| | verified | boolean | Whether the solution is valid. | | expired | boolean | Whether the challenge has expired. | | invalidSignature | boolean \| null | Whether the challenge signature is invalid. | | invalidSolution | boolean \| null | Whether the solution is incorrect. | | time | number | Time taken to verify in milliseconds. |

verifyFieldsHash(options): Promise<boolean>

Verifies the SHA hash of specified form fields.

| Option | Type | Description | |---|---|---| | formData | FormData \| Record<string, unknown> | The form data to verify. | | fields | string[] | Field names to include in the hash. | | fieldsHash | string | The expected hash value. | | algorithm | string? | Hash algorithm. Defaults to 'SHA-256'. |

verifyServerSignature(options): Promise<VerifyServerSignatureResult>

Verifies a server signature payload from ALTCHA Sentinel.

| Option | Type | Description | |---|---|---| | payload | ServerSignaturePayload | The payload to verify. | | hmacSecret | string | The HMAC secret. |

Returns VerifyServerSignatureResult (extends VerifySolutionResult):

| Field | Type | Description | |---|---|---| | verified | boolean | Whether the signature is valid. | | verificationData | ServerSignatureVerificationData \| null | Parsed verification data. |

obfuscate(str: string, options?): Promise<string>

Import from altcha-lib/obfuscation

Encrypts a string using AES-GCM, with the key derived from a PoW challenge. Returns a base64-encoded payload.

| Option | Type | Description | |---|---|---| | counterMin | number? | Minimum counter value. Defaults to 20. | | counterMax | number? | Maximum counter value. Defaults to 200. | | deriveKey | DeriveKeyFunction? | Key derivation function. Defaults to PBKDF2. | | ... | | Any CreateChallengeOptions fields. |

deobfuscate(obfuscatedData: string, options?): Promise<string>

Import from altcha-lib/obfuscation

Decrypts an obfuscated string by solving the embedded PoW challenge and using the derived key.

| Option | Type | Description | |---|---|---| | concurrency | number? | Worker concurrency. Defaults to up to 4. | | createWorker | (algorithm: string) => Worker? | Factory to create a worker for solving. | | deriveKey | DeriveKeyFunction? | Key derivation function. Defaults to PBKDF2. |

randomInt(max: number, min?: number): number

Returns a cryptographically random integer between min (default 1) and max.

class CappedMap<K, V>

A Map subclass with a fixed maximum size. When full, the oldest entry is evicted on insertion.

new CappedMap({ maxSize: number })

enum HmacAlgorithm

| Value | String | |---|---| | HmacAlgorithm.SHA_256 | 'SHA-256' | | HmacAlgorithm.SHA_384 | 'SHA-384' | | HmacAlgorithm.SHA_512 | 'SHA-512' |

v1 (altcha-lib/v1)

createChallenge(options: ChallengeOptions): Promise<Challenge>

Creates a v1 SHA-based proof-of-work challenge.

| Option | Type | Description | |---|---|---| | hmacKey | string | Required. HMAC key for signing. | | algorithm | 'SHA-1' \| 'SHA-256' \| 'SHA-512'? | Hash algorithm. Defaults to 'SHA-256'. | | expires | Date? | Expiry date embedded in the salt. | | maxNumber | number? | Maximum random number. Defaults to 1000000. | | number | number? | Fixed number (skips random selection). | | params | Record<string, string>? | Extra parameters embedded in the salt. | | salt | string? | Custom salt value. | | saltLength | number? | Random salt length in bytes. Defaults to 12. |

verifySolution(payload: string | Payload, hmacKey: string, checkExpires?: boolean): Promise<boolean>

Verifies a v1 solution payload.

verifyFieldsHash(formData, fields, fieldsHash, algorithm?): Promise<boolean>

Verifies the hash of specified form fields.

verifyServerSignature(payload: string | ServerSignaturePayload, hmacKey: string): Promise<{ verified: boolean, verificationData: ServerSignatureVerificationData | null }>

Verifies a v1 server signature.

solveChallenge(challenge, salt, algorithm?, max?, start?): { promise: Promise<Solution | null>, controller: AbortController }

Solves a v1 challenge by brute force.

solveChallengeWorkers(workerScript, concurrency, challenge, salt, algorithm?, max?, startNumber?): Promise<Solution | null>

Solves a v1 challenge using Web Workers.

extractParams(payload: string | Payload | Challenge): Record<string, string>

Extracts URL parameters embedded in a challenge salt.

License

MIT