ALTCHA

https://github.com/altcha-org/altcha
Admin
ALTCHA is a privacy-first, self-hosted CAPTCHA alternative that protects websites from spam and...
Tokens:70,510
Snippets:459
Trust Score:9.4
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### PasswordBuffer Usage Example

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/pow.md

Example of initializing PasswordBuffer and setting a counter.

```js
import { PasswordBuffer } from 'altcha/lib'; // not re-exported; import from source path only
const pw = new PasswordBuffer(hexToBuffer(nonce), 'uint32');
const password = pw.setCounter(42);
```

--------------------------------

### Reset widget examples

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/widget-element.md

Examples of resetting the widget to unverified or forcing an error state.

```js
widget.reset(); // back to unverified
widget.reset(State.ERROR, 'Custom failure'); // force error state
```

--------------------------------

### Log widget configuration

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/widget-element.md

Example of retrieving and logging the current configuration.

```js
const cfg = widget.getConfiguration();
console.log(cfg.verifyUrl, cfg.workers);
```

--------------------------------

### Install ALTCHA via npm

Source: https://github.com/altcha-org/altcha/blob/main/README.md

Install the ALTCHA widget using npm. Run this command in your project directory.

```sh
npm install altcha
```

--------------------------------

### solveChallenge usage example

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/pow.md

An example demonstrating how to invoke solveChallenge with a SHA-256 algorithm configuration and a 30-second timeout.

```js
import { solveChallenge } from 'altcha/lib';
import { sha } from 'altcha/lib';

const solution = await solveChallenge({
	challenge: { parameters: { algorithm: 'SHA-256', nonce: '…', salt: '…', cost: 10, keyLength: 32, keyPrefix: 'c94e' } },
	deriveKey: sha.deriveKey,
	timeout: 30_000
});
if (!solution) {
	// timed out or aborted
}
```

--------------------------------

### verifyServerSignature usage example

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/server-signature.md

Example of how to call verifyServerSignature and handle the result.

```js
import { verifyServerSignature } from 'altcha/lib';

const result = await verifyServerSignature({
	payload: {
		algorithm: 'SHA-256',
		signature: '…',
		verificationData: 'verified=true&expire=1735689600&score=0.94',
		verified: true
	},
	hmacSecret: 'server-secret'
});
if (result.verified) {
	console.log('classification:', result.verificationData?.classification);
} else {
	console.log({ expired: result.expired, invalidSignature: result.invalidSignature, invalidSolution: result.invalidSolution });
}
```

--------------------------------

### Collector usage example

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/internals.md

Demonstrates initializing the collector, exporting the gathered data, and destroying the instance.

```js
// Internal — not exported from the package entry.
const collector = new Collector({ maxSamples: 120, sampleInterval: 30 });
const data = collector.export();
collector.destroy();
```

--------------------------------

### verifySolution Usage Example

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/pow.md

A basic implementation showing how to call verifySolution with a challenge, solution, and KDF function.

```js
import { verifySolution } from 'altcha/lib';
import { pbkdf2 } from 'altcha/lib';

const result = await verifySolution({
	challenge,
	solution,
	hmacSignatureSecret: 'server-secret',
	deriveKey: pbkdf2.deriveKey
});
if (!result.verified) {
	console.log({ expired: result.expired, badSignature: result.invalidSignature, badSolution: result.invalidSolution });
}
```

--------------------------------

### verifyFieldsHash usage example

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/server-signature.md

Example of how to call verifyFieldsHash with form data.

```js
const ok = await verifyFieldsHash({
	formData: new FormData(formElement),
	fields: ['email', 'message'],
	fieldsHash: 'a1b2…'
});
```

--------------------------------

### argon2id.deriveKey usage example

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/algorithms.md

Example of calling the argon2id.deriveKey function with specific parameters.

```js
import { argon2id } from 'altcha/lib';

const result = await argon2id.deriveKey(
	{ algorithm: 'ARGON2ID', cost: 3, memoryCost: 16384, parallelism: 1, keyLength: 32 },
	saltBytes,
	passwordBytes
);
```

--------------------------------

### Importing ALTCHA Types

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/types.md

Examples of how to import types from the altcha package, its lib sub-path, or the types module.

```ts
import type { Configuration, Challenge, Solution, State, HmacAlgorithm } from 'altcha';
import type { Configuration, Challenge, Solution, State, HmacAlgorithm } from 'altcha/lib';
import type * as AltchaTypes from 'altcha/types';
```

--------------------------------

### Creating a signed challenge

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/pow.md

Example of creating a challenge using PBKDF2 with an HMAC signature.

```js
import { createChallenge } from 'altcha/lib';
import { pbkdf2 } from 'altcha/lib';

const challenge = await createChallenge({
	algorithm: 'PBKDF2/SHA-256',
	cost: 5000,
	deriveKey: pbkdf2.deriveKey,
	expiresAt: Date.now() / 1000 + 120,
	hmacSignatureSecret: 'server-secret'
});
// challenge.signature is an HMAC-SHA-256 of the canonical JSON parameters
```

--------------------------------

### PBKDF2 deriveKey usage

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/algorithms.md

Example of using the PBKDF2 deriveKey function with specific algorithm and cost parameters.

```js
import { pbkdf2 } from 'altcha/lib';

const result = await pbkdf2.deriveKey(
	{ algorithm: 'PBKDF2/SHA-256', cost: 5000, keyLength: 32 },
	saltBytes,
	passwordBytes
);
```

--------------------------------

### Scrypt deriveKey usage with createChallenge

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/algorithms.md

Example of using the Scrypt deriveKey function within a createChallenge call, demonstrating default parameter backfilling.

```js
import { createChallenge } from 'altcha/lib';
import { scrypt } from 'altcha/lib';

const challenge = await createChallenge({
	algorithm: 'SCRYPT',
	cost: 5,
	deriveKey: scrypt.deriveKey
});
console.log(challenge.parameters.memoryCost, challenge.parameters.parallelism); // 8 1
```

--------------------------------

### solveChallengeWorkers usage example

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/pow.md

An example demonstrating how to initialize a challenge and solve it using multiple workers with the solveChallengeWorkers function.

```js
import { solveChallengeWorkers } from 'altcha';
import Argon2idWorker from 'altcha/workers/argon2id?worker';
import { createChallenge } from 'altcha/lib';
import { argon2id } from 'altcha/lib';

const challenge = await createChallenge({
	algorithm: 'ARGON2ID',
	cost: 3,
	memoryCost: 16384,
	parallelism: 1,
	deriveKey: argon2id.deriveKey
});

const solution = await solveChallengeWorkers({
	challenge,
	concurrency: 4,
	createWorker: () => new Argon2idWorker(),
	onOutOfMemory: (c) => (c > 2 ? Math.floor(c / 2) : 0)
});
```

--------------------------------

### Update widget UI

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/widget-element.md

Example of manually updating the UI after layout changes in floating mode.

```js
widget.updateUI(); // after layout changes in floating mode
```

--------------------------------

### Register custom algorithm end-to-end

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/global-store.md

Example of registering a custom algorithm like SCRYPT for server-issued challenges.

```ts
import 'altcha';
import ScryptWorker from 'altcha/workers/scrypt?worker';

$altcha.algorithms.set('SCRYPT', () => new ScryptWorker());

// Later, a server may issue: { "algorithm": "SCRYPT", ... }
```

--------------------------------

### Creating a deterministic challenge with key-signature

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/pow.md

Example of creating a deterministic challenge using SCRYPT with both HMAC signature and key signature.

```js
import { createChallenge, HmacAlgorithm } from 'altcha/lib';
import { scrypt } from 'altcha/lib';

try {
	const { parameters, derivedKey } = await createChallenge({
		algorithm: 'SCRYPT',
		cost: 5,
		counter: 17,
		keyPrefixLength: 8,
		deriveKey: scrypt.deriveKey,
		hmacAlgorithm: HmacAlgorithm.SHA_512,
		hmacSignatureSecret: 'secret-a',
		hmacKeySignatureSecret: 'secret-b'
	});
	console.log(parameters.keySignature, derivedKey?.length);
} catch (err) {
	// e.g. 'hmacKeySignatureSecret requires hmacSignatureSecret.'
	console.error(err.message);
}
```

--------------------------------

### Import ALTCHA in JavaScript

Source: https://github.com/altcha-org/altcha/blob/main/README.md

Import the ALTCHA widget in your main JavaScript file after installation.

```js
import 'altcha';
```

--------------------------------

### Configure advanced widget settings

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/widget-element.md

Example of setting advanced values like custom fetch, cookie output, and code challenge that cannot be passed as HTML attributes.

```js
widget.configure({
	fetch: (url, init) => fetch(url, { ...init, headers: { 'X-API-Key': '…' } }),
	setCookie: { name: 'altcha', path: '/', sameSite: 'Lax' },
	codeChallenge: { image: '/captcha.png', audio: '/captcha.mp3', length: 6 }
});
```

--------------------------------

### Obfuscate Data Example

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/plugins.md

Example usage of the obfuscate method to encrypt a mailto link.

```ts
import { ObfuscationPlugin } from 'altcha/plugins/obfuscation';

const obfuscatedData = await ObfuscationPlugin.obfuscate('mailto:hello@example.com', {
	counterMin: 50,
	counterMax: 100
});
```

--------------------------------

### Using SHA deriveKey in Challenges

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/algorithms.md

Example of using the SHA deriveKey function within the createChallenge and solveChallenge workflow.

```js
import { createChallenge, solveChallenge } from 'altcha/lib';
import { sha } from 'altcha/lib';

const challenge = await createChallenge({ algorithm: 'SHA-256', cost: 10, deriveKey: sha.deriveKey });
const solution = await solveChallenge({ challenge, deriveKey: sha.deriveKey });
```

--------------------------------

### Get widget configuration

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/widget-element.md

Retrieve a snapshot of the current merged configuration.

```ts
/** Get a snapshot of the current merged configuration */
export function getConfiguration() {
	return {
		...config
	};
}
```

--------------------------------

### Parse verification data example

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/server-signature.md

Example usage of parseVerificationData to convert a URL-encoded string into a typed object.

```js
const data = parseVerificationData('verified=true&score=0.9&expire=1735689600&fields=a,b');
// { verified: true, score: 0.9, expire: 1735689600, fields: ['a', 'b'] }
```

--------------------------------

### Check widget state

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/widget-element.md

Example of checking if the widget is unverified and triggering verification.

```js
if (widget.getState() === 'unverified') widget.verify();
```

--------------------------------

### Deobfuscate Data Example

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/plugins.md

Example usage of the deobfuscate method to decrypt data, including error handling.

```ts
import { ObfuscationPlugin } from 'altcha/plugins/obfuscation';

try {
	const text = await ObfuscationPlugin.deobfuscate(obfuscatedData, { concurrency: 2 });
	console.log(text);
} catch (err) {
	console.error('deobfuscation failed', err);
}
```

--------------------------------

### Override widget configuration

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/widget-element.md

Example of overriding worker count and language on an existing widget instance.

```js
const widget = document.querySelector('altcha-widget');
widget.configure({ workers: 2, language: 'fr' });
```

--------------------------------

### solveChallenge pseudo-code for client-side solution finding

Source: https://github.com/altcha-org/altcha/blob/main/src/playground/about.md

Searches for a counter that, when appended to the nonce, produces a derived key starting with the required keyPrefix. The loop increments the counter until a match is found.

```pseudo-code
FUNCTION solveChallenge(parameters):
    counter = 0
    LOOP:
        password = AppendUint32BE(parameters.nonce, counter)

        derivedKeyHex = DeriveKey(
            parameters.algorithm,
            parameters.salt,
            parameters.cost,
            password,
        )

        IF derivedKeyHex STARTS WITH parameters.keyPrefix:
            RETURN { counter, derivedKeyHex }

        counter += 1
```

--------------------------------

### solveChallenge

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/pow.md

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

```APIDOC
## solveChallenge

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

### Signature
```ts
export async function solveChallenge(options: SolveChallengeOptions): Promise<Solution | null>
```

### Parameters

#### options.challenge
- **Type**: `Challenge`
- **Required**: yes
- **Description**: Challenge to solve

#### options.deriveKey
- **Type**: `DeriveKeyFunction`
- **Required**: yes
- **Description**: KDF implementation

#### options.controller
- **Type**: `AbortController`
- **Required**: no
- **Default**: —
- **Description**: Aborts the loop (checked every 10 iterations)

#### options.counterMode
- **Type**: `'uint32' | 'string'`
- **Required**: no
- **Default**: `'uint32'`
- **Description**: Passwords are `nonce + counter` (`PasswordBuffer`)

#### options.counterStart
- **Type**: `number`
- **Required**: no
- **Default**: `0`
- **Description**: First counter value

#### options.counterStep
- **Type**: `number`
- **Required**: no
- **Default**: `1`
- **Description**: Counter increment per iteration

#### options.timeout
- **Type**: `number`
- **Required**: no
- **Default**: `90_000`
- **Description**: ms; loop aborts when exceeded (checked every 10 iterations)

### Returns
- **Type**: `Promise<Solution | null>`
- **Description**: `{ counter: number; derivedKey: string; time?: number }` — `time` is elapsed ms (`timeDuration`). Returns `null` on abort or timeout. Two prefix match modes: even-length hex prefix → byte comparison (`bufferStartsWith`); odd-length → case-insensitive string prefix. Yield to the event loop every ≥200 ms (`delay(0)`).

### Example
```js
import { solveChallenge } from 'altcha/lib';
import { sha } from 'altcha/lib';

const solution = await solveChallenge({
	challenge: { parameters: { algorithm: 'SHA-256', nonce: '…', salt: '…', cost: 10, keyLength: 32, keyPrefix: 'c94e' } },
	deriveKey: sha.deriveKey,
	timeout: 30_000
});
if (!solution) {
	// timed out or aborted
}
```
```

--------------------------------

### GET {challenge URL}

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/endpoints.md

Issued by fetchChallenge when config.challenge is a non-JSON string. Fetches a challenge from the configured URL, resolves it against location.origin, and validates the response as JSON.

```APIDOC
## [GET] {challenge URL}

### Description
Fetches a challenge from the configured challenge URL. The URL is resolved against location.origin. The response must be application/json and status codes >= 400 cause an error.

### Method
GET

### Endpoint
{challenge URL} (config.challenge, resolved against location.origin)

### Parameters
#### Query Parameters
None added by the widget.

#### Request Headers
None added by the widget.

#### Request Credentials
- **credentials** (string) - Optional - config.credentials when set

### Request Example
No request body.

### Response
#### Success Response (200)
Must be application/json. Shape is one of:
- Challenge JSON: { parameters: { algorithm, nonce, salt, cost, keyLength, keyPrefix, ... }, signature?, codeChallenge? }
- ChallengeV1 JSON: { algorithm, challenge, salt, signature, codeChallenge?, maxnumber? } (auto-converted)
- Challenge JSON with optional extension keys:
  - configuration: Partial<Configuration> - applied to the widget before solving
  - his: { url: string } - HIS handshake: the widget responds with a second request
  - hisResult: unknown - logged only

#### Response Headers
- **x-altcha-config** (string) - JSON-encoded configuration object, merged via processConfigHeader with legacy mappings sentinel.fields, sentinel.timeZone, verifyurl

#### Response Example
{
  "parameters": {
    "algorithm": "SHA-256",
    "nonce": "...",
    "salt": "...",
    "cost": 1000,
    "keyLength": 32,
    "keyPrefix": "altcha"
  },
  "signature": "..."
}

### Error Handling
- Status >= 400: throws error
- Client-side validation errors (isChallengeValid): missing parameters, parameters.algorithm, parameters.nonce, parameters.salt, or parameters.keyPrefix -> 'Challenge validation failed.'
```

--------------------------------

### Basic Client Usage

Source: https://github.com/altcha-org/altcha/blob/main/MIGRATION-v2.md

Import the altcha package to register the Web Component and use the altcha-widget element with the challenge attribute.

```html
<script>
	import 'altcha';
</script>

<altcha-widget challenge="https://api.example.com/challenge"></altcha-widget>
```

--------------------------------

### Importing Key Derivation Modules

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/algorithms.md

Shows how to import the key derivation namespaces from the main package or the lib entry point.

```ts
import { sha, pbkdf2, scrypt, argon2id } from 'altcha';
import { sha, pbkdf2, scrypt, argon2id } from 'altcha/lib';
```

--------------------------------

### Basic verify usage

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/widget-element.md

Demonstrates how to call the verify method and handle the resulting payload or failure state.

```js
const result = await widget.verify();
if (result) {
	console.log(result.payload, result.solution.counter);
} else {
	console.log(widget.getState(), 'verification failed');
}
```

--------------------------------

### Get widget state

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/widget-element.md

Retrieve the current widget state.

```ts
/** Get the current widget state (UNVERIFIED, VERIFYING, VERIFIED, etc.) */
export function getState() {
	return currentState;
}
```

--------------------------------

### Create, Solve, and Verify ALTCHA Challenges

Source: https://github.com/altcha-org/altcha/blob/main/MIGRATION-v2.md

Demonstrates the workflow for generating a challenge, solving it, and verifying the solution using the altcha package utilities.

```ts
import { createChallenge, solveChallenge, verifySolution, pbkdf2 } from 'altcha/lib';

const HMAC_SIGNATURE_SECRET = 'secret.key';
const HMAC_KEY_SIGNATURE_SECRET = 'second.secret.key';

const challenge = await createChallenge({
	algorithm: 'PBKDF2/SHA-256',
	cost: 5_000,
	deriveKey: pbkdf2.deriveKey,
	hmacKeySignatureSecret: HMAC_KEY_SIGNATURE_SECRET,
	hmacSignatureSecret: HMAC_SIGNATURE_SECRET
});

const solution = await solveChallenge({
	challenge,
	deriveKey: pbkdf2.deriveKey
});

const result = await verifySolution({
	challenge,
	deriveKey: pbkdf2.deriveKey,
	hmacKeySignatureSecret: HMAC_KEY_SIGNATURE_SECRET,
	hmacSignatureSecret: HMAC_SIGNATURE_SECRET,
	solution
});
```

--------------------------------

### show()

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/widget-element.md

Shows the widget and updates its position. Takes no parameters and returns void.

```APIDOC
## show()

### Description
Show the widget and update its position.

### Method
show

### Parameters
None

### Returns
void
```

--------------------------------

### VerifySolutionOptions

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/types.md

Options for verifying a solution. Contains the challenge, solution, HMAC secrets, and optional KDF parameters.

```APIDOC
## VerifySolutionOptions

### Description
Options for verifying a solution. Contains the challenge, solution, HMAC secrets, and optional KDF parameters.

### TypeScript Interface
```ts
export interface VerifySolutionOptions {
	challenge: Challenge;
	counterMode?: 'uint32' | 'string';
	deriveKey: DeriveKeyFunction;
	hmacAlgorithm?: HmacAlgorithm;
	hmacKeySignatureSecret?: string;
	hmacSignatureSecret: string;
	solution: Solution;
}
```

### Properties
- **challenge** (Challenge) - Required - The challenge to verify.
- **counterMode** ('uint32' | 'string') - Optional - Counter mode for the solution.
- **deriveKey** (DeriveKeyFunction) - Required - The key derivation function.
- **hmacAlgorithm** (HmacAlgorithm) - Optional - HMAC algorithm to use.
- **hmacKeySignatureSecret** (string) - Optional - Secret for key signature.
- **hmacSignatureSecret** (string) - Required - Secret for HMAC signature.
- **solution** (Solution) - Required - The solution to verify.
```

--------------------------------

### Configure widget via challenge JSON

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/configuration.md

Apply server-driven configuration by including a configuration object in the challenge response JSON, which is processed before solving.

```json
{
	"configuration": {
		"setCookie": { "name": "altcha", "path": "/submit" }
	},
	"parameters": {},
	"signature": "..."
}
```

--------------------------------

### Importing ALTCHA PoW functions

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/pow.md

Shows how to import the primary PoW functions from the widget or headless entry points.

```ts
import { createChallenge, solveChallenge, solveChallengeWorkers, verifySolution } from 'altcha';       // widget entry
import { createChallenge, solveChallenge, solveChallengeWorkers, verifySolution } from 'altcha/lib';    // headless entry
```

--------------------------------

### Configure widget instance

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/widget-element.md

Merge new configuration options into the current widget configuration.

```ts
/** Merge new configuration options into the current config */
export function configure(newConfig: Partial<Configuration>) {
	Object.assign(userConfig, {
		...Object.fromEntries(Object.entries(newConfig).filter(([_, value]) => value !== undefined))
	});
}
```

--------------------------------

### Import Server Signature functions

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/server-signature.md

Import the verification functions from the main package or the library entry point.

```ts
import { parseVerificationData, verifyFieldsHash, verifyServerSignature } from 'altcha';
import { parseVerificationData, verifyFieldsHash, verifyServerSignature } from 'altcha/lib';
```

--------------------------------

### configure(newConfig)

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/widget-element.md

Merges new configuration options into the current config. Accepts a partial configuration object and returns void.

```APIDOC
## configure(newConfig)

### Description
Merge new configuration options into the current config. Accepts a partial configuration object and returns void.

### Method
configure

### Parameters
- **newConfig** (Partial<Configuration>) - Required - Options merged over the global defaults and attribute props; undefined values are dropped.

### Returns
void

### Example
```js
const widget = document.querySelector('altcha-widget');
widget.configure({ workers: 2, language: 'fr' });
```

### Advanced Example
```js
widget.configure({
  fetch: (url, init) => fetch(url, { ...init, headers: { 'X-API-Key': '...' } }),
  setCookie: { name: 'altcha', path: '/', sameSite: 'Lax' },
  codeChallenge: { image: '/captcha.png', audio: '/captcha.mp3', length: 6 }
});
```
```

--------------------------------

### Set global defaults with $altcha.defaults

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/configuration.md

Use the $altcha.defaults global store to seed configuration for all future widget instances.

```js
$altcha.defaults.set({
	challenge: 'https://api.example.com/challenge',
	debug: true,
	retryOnOutOfMemoryError: false
});
```

--------------------------------

### Default entry point exports

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/entry-points.md

Exports from the default entry point (src/entry.ts), which includes the Svelte widget component, algorithm modules, and utility functions for proof-of-work and server signature verification.

```ts
export { Widget };                                                  // Svelte component compiled to <altcha-widget>
export * as argon2id from './algorithms/argon2id';
export * as pbkdf2 from './algorithms/pbkdf2';
export * as scrypt from './algorithms/scrypt';
export * as sha from './algorithms/sha';
export type * from './types';
export { createChallenge, solveChallenge, solveChallengeWorkers, verifySolution } from './pow';
export { parseVerificationData, verifyFieldsHash, verifyServerSignature } from './server-signature';
```

--------------------------------

### Customize ALTCHA translations via $altcha.i18n

Source: https://github.com/altcha-org/altcha/blob/main/README.md

Overrides default translations by updating the global $altcha registry. The example imports German and then sets a custom label.

```js
import 'altcha/i18n/de';

$altcha.i18n.set('de', {
	...$altcha.i18n.get('de'),
	label: 'Ich bin ein Mensch' // Custom label
});
```

--------------------------------

### verify(options?)

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/widget-element.md

Verifies the widget. Accepts optional options. Returns a Promise.

```APIDOC
## verify(options?)

### Description
Verify the widget.

### Method
verify

### Parameters
- **options** (object) - Optional - Verification options.

### Returns
Promise<void>
```

--------------------------------

### Library entry point exports

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/entry-points.md

Exports from the library entry point (src/entry-lib.ts), which provides algorithm modules and utility functions but excludes the widget component and automatic CSS injection.

```ts
export * as argon2id from './algorithms/argon2id';
export * as pbkdf2 from './algorithms/pbkdf2';
export * as scrypt from './algorithms/scrypt';
export * as sha from './algorithms/sha';
export type * from './types';
export { createChallenge, solveChallenge, solveChallengeWorkers, verifySolution } from './pow';
export { parseVerificationData, verifyFieldsHash, verifyServerSignature } from './server-signature';
```

--------------------------------

### Configuring Algorithms with Vite

Source: https://github.com/altcha-org/altcha/blob/main/MIGRATION-v2.md

Register algorithms using the global $altcha object when using altcha/external. Argon2 and Scrypt workers must be imported separately.

```ts
import 'altcha/external';
import Argon2idWorker from 'altcha/workers/argon2id?worker';
import Pbkdf2Worker from 'altcha/workers/pbkdf2?worker';
import ScryptWorker from 'altcha/workers/scrypt?worker';
import ShaWorker from 'altcha/workers/sha?worker';

$altcha.algorithms.set('PBKDF2/SHA-256', () => new Pbkdf2Worker());
$altcha.algorithms.set('PBKDF2/SHA-384', () => new Pbkdf2Worker());
$altcha.algorithms.set('PBKDF2/SHA-512', () => new Pbkdf2Worker());
$altcha.algorithms.set('SHA-256', () => new ShaWorker());
$altcha.algorithms.set('SHA-384', () => new ShaWorker());
$altcha.algorithms.set('SHA-512', () => new ShaWorker());
$altcha.algorithms.set('ARGON2ID', () => new Argon2idWorker());
$altcha.algorithms.set('SCRYPT', () => new ScryptWorker());
```

--------------------------------

### CreateChallengeOptions

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/types.md

Options for creating a challenge.

```APIDOC
## CreateChallengeOptions

### Description
Options for creating a challenge. Full per-field semantics and defaults: api-reference/pow.md#createchallenge.

### Fields
- **algorithm** (string) - Required - Algorithm name
- **counter** (number) - Optional - Initial counter value
- **counterMode** ('uint32' | 'string') - Optional - Counter mode
- **cost** (number) - Required - Cost factor
- **data** (Record<string, string | number | boolean | null>) - Optional - Opaque extra fields
- **deriveKey** (DeriveKeyFunction) - Required - Key derivation function
- **expiresAt** (number | Date) - Optional - Expiration time
- **hmacAlgorithm** (HmacAlgorithm) - Optional - HMAC algorithm
- **hmacKeySignatureSecret** (string) - Optional - Secret for key signature
- **hmacSignatureSecret** (string) - Optional - Secret for signature
- **keyLength** (number) - Optional - Derived key size in bytes
- **keyPrefix** (string) - Optional - Hex prefix for derived key
- **keyPrefixLength** (number) - Optional - Length of key prefix
- **memoryCost** (number) - Optional - Memory cost
- **parallelism** (number) - Optional - Parallelism
```

--------------------------------

### Basic HTML Widget Implementation

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/widget-element.md

Place the altcha-widget inside a form element to enable proof-of-work verification using a challenge URL.

```html
<form>
	<altcha-widget challenge="https://api.example.com/challenge"></altcha-widget>
</form>
```

--------------------------------

### createChallenge pseudo-code for server-side challenge creation

Source: https://github.com/altcha-org/altcha/blob/main/src/playground/about.md

Generates a probabilistic challenge with random salt and nonce, then signs the canonical parameters with HMAC. For deterministic mode, the server must pre-compute the keyPrefix from a target counter instead of using a static value.

```pseudo-code
FUNCTION createChallenge(algorithm, cost, keyPrefix, hmacSignatureSecret):
    salt = GenerateRandomHex(16)
    nonce = GenerateRandomHex(16)

    parameters = {
        algorithm,
        cost,
        nonce,
        salt,
        keyPrefix
    }

    signature = Hmac(hmacSignatureSecret, CanonicalJSON(parameters))
    RETURN { parameters, signature }
```

--------------------------------

### getConfiguration()

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/widget-element.md

Returns a shallow snapshot of the current merged configuration. Takes no parameters and returns a Configuration object.

```APIDOC
## getConfiguration()

### Description
Get a snapshot of the current merged configuration. Returns a shallow copy of the merged configuration (global defaults, defaults, user overrides).

### Method
getConfiguration

### Parameters
None

### Returns
Configuration - A shallow snapshot of the merged configuration.

### Example
```js
const cfg = widget.getConfiguration();
console.log(cfg.verifyUrl, cfg.workers);
```
```

--------------------------------

### Widget Usage with Obfuscation

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/plugins.md

How to use the altcha-widget with obfuscated data by importing the plugin.

```html
<script>
	import 'altcha/plugins/obfuscation';
	import 'altcha';
</script>

<altcha-widget data-obfuscated="${obfuscatedData}" display="floating"></altcha-widget>
```

--------------------------------

### Programmatic Configuration

Source: https://github.com/altcha-org/altcha/blob/main/README.md

Use the global $altcha object to set defaults or the .configure() method on a specific widget instance for dynamic updates.

```ts
// Set defaults for all future widget instances:
$altcha.defaults.set({
	challenge: 'https://api.example.com/challenge',
	debug: true
});

// Update a specific instance dynamically:
const widget = document.querySelector('altcha-widget');
widget.configure({
	workers: 2,
	language: 'fr'
});
```

--------------------------------

### Next.js SSR Implementation

Source: https://github.com/altcha-org/altcha/blob/main/MIGRATION-v2.md

Use useSyncExternalStore to handle client-side rendering for the ALTCHA widget in Next.js.

```jsx
'use client'

import { useSyncExternalStore } from 'react';
import 'altcha';
import type {} from 'altcha/types/react';

export default function Altcha() {
	const isClient = useSyncExternalStore(
		() => () => {},
		() => true,
		() => false
	);

	return isClient
		? <altcha-widget></altcha-widget>
		: <span>Loading...</span>;
}
```

--------------------------------

### Iterate over active instances

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/global-store.md

Enumerate all currently mounted widget instances to perform actions like re-configuration.

```js
for (const el of $altcha.instances) {
	el.configure({ debug: true });
}
```

--------------------------------

### SvelteKit SSR Implementation

Source: https://github.com/altcha-org/altcha/blob/main/MIGRATION-v2.md

Import the ALTCHA widget and types in a SvelteKit component to enable SSR support.

```html
<script lang="ts">
	import 'altcha';
	import type {} from 'altcha/types/svelte';
</script>

<altcha-widget></altcha-widget>
```

--------------------------------

### Store / Writable

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/types.md

The Store and Writable types define a Svelte-store-compatible wrapper used by $altcha.defaults and $altcha.i18n for state management.

```APIDOC
## Store / Writable

### Description
The Store type is a generic wrapper around a Svelte Writable store, providing get and set methods. The Writable type is a Svelte store interface with set, update, and subscribe methods.

### Store Type
```ts
export type Store<T extends object, K extends keyof T = keyof T> = {
	get: (name: K) => T[K];
	set: <N extends K>(name: N | T, value?: T[N]) => void;
	store: Writable<T>;
};
```

### Writable Type
```ts
export type Writable<T = Record<string, Record<string, string>>> = {
	set(this: void, value: T): void;
	update(this: void, updater: (value: T) => T): void;
	subscribe(this: void, run: (value: T) => void, invalidate?: () => void): () => void;
};
```

### Usage
Used by `$altcha.defaults` and `$altcha.i18n`.
```

--------------------------------

### Import combined bundle with widget and translations

Source: https://github.com/altcha-org/altcha/blob/main/README.md

Imports the combined bundle that includes both the widget and all translations.

```js
import 'altcha/i18n';
```

--------------------------------

### Hide, show, and update UI

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/widget-element.md

Methods to manage widget visibility and UI positioning.

```ts
/** Hide the widget (used in floating/bar/overlay modes) */
export function hide() {
	visible = false;
}

/** Show the widget and update its position */
export function show() {
	visible = true;
	tick().then(() => {
		updateUI();
	});
}

/** Update UI positioning */
export function updateUI() {
	switch (config.display) {
		case 'floating':
			return repositionFloating();
		default:
		// noop
	}
	updateUISignal += 1;
}
```

--------------------------------

### Exporting the Widget from altcha/external

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/entry-points.md

The entry point for the external module, which initializes global settings and exports the Svelte-based Widget component.

```ts
import './global';
import './i18n/en';
import Widget from './Widget.svelte';
import './widget.scss';

export { Widget };
```

--------------------------------

### Import all ALTCHA translations

Source: https://github.com/altcha-org/altcha/blob/main/README.md

Imports the bundle containing all supported language translations.

```js
import 'altcha/i18n/all';
```

--------------------------------

### Register Workers Without Bundler Support

Source: https://github.com/altcha-org/altcha/blob/main/README.md

Use this method if your environment does not support ?worker imports by loading prebuilt worker files directly from the distribution path.

```ts
import 'altcha';

$altcha.algorithms.set(
	'ARGON2ID',
	() => new Worker('/path/to/node_modules/altcha/dist/workers/argon2id.js')
);
$altcha.algorithms.set(
	'SCRYPT',
	() => new Worker('/path/to/node_modules/altcha/dist/workers/scrypt.js')
);
```

--------------------------------

### createChallenge

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/pow.md

Creates a new proof-of-work challenge. Generates random nonce and salt, optionally pre-computes a key prefix from a known counter value, and optionally signs the challenge with HMAC. Omitting hmacSignatureSecret creates an unsigned challenge; an empty or null secret throws, as does hmacKeySignatureSecret without hmacSignatureSecret.

```APIDOC
## createChallenge

### Description
Creates a new proof-of-work challenge. Generates random nonce and salt, optionally pre-computes a key prefix from a known counter value, and optionally signs the challenge with HMAC. Omitting `hmacSignatureSecret` creates an unsigned challenge; an empty or `null` secret throws, as does `hmacKeySignatureSecret` without `hmacSignatureSecret`.

### Method
async function

### Signature
`export async function createChallenge(options: CreateChallengeOptions): Promise<Challenge>`

### Parameters
#### options (object)
- **algorithm** (string) - Required - KDF name, e.g. 'SHA-256', 'PBKDF2/SHA-256', 'ARGON2ID', 'SCRYPT'. Validated against HmacAlgorithm values (SHA-256/384/512) for signing.
- **cost** (number) - Required - Positive integer cost/iteration count.
- **deriveKey** (DeriveKeyFunction) - Required - `(parameters, salt, password) => Promise<DeriveKeyFunctionResult>`.
- **counter** (number) - Optional - Deterministic mode: if set, derives the key for this counter, sets `keyPrefix` from it and returns the derived key. Must satisfy the counter mode bounds.
- **counterMode** ('uint32' | 'string') - Optional - Default: 'uint32' - Counter encoding for deterministic mode.
- **data** (Record<string, string | number | boolean | null>) - Optional - Opaque data embedded in the challenge parameters.
- **expiresAt** (number | Date) - Optional - Expiry as a Date or positive number of seconds.
- **hmacAlgorithm** (HmacAlgorithm) - Optional - Default: HmacAlgorithm.SHA_256 - HMAC hash for signing.
- **hmacSignatureSecret** (string) - Optional - Secret for signing the challenge parameters; omitted → unsigned challenge.
- **hmacKeySignatureSecret** (string) - Optional - Extra secret to sign the derived key (`keySignature`); requires `hmacSignatureSecret`.
- **keyLength** (number) - Optional - Default: 32 - Derived key length in bytes.
- **keyPrefix** (string) - Optional - Default: '00' - Hex prefix the solver must match (only meaningful without `counter`).
- **keyPrefixLength** (number) - Optional - Default: Math.floor(keyLength / 2) - Number of prefix bytes pre-computed in deterministic mode; must be < derivedKey.length.
- **memoryCost** (number) - Optional - Memory cost (Argon2/Scrypt).
- **parallelism** (number) - Optional - Parallelism (Argon2/Scrypt).

### Returns
`Promise<Challenge>`: `{ parameters: ChallengeParameters, signature?: string }` with sorted (canonical) parameter keys (`sortKeys`). Generated internally: 16 random bytes each for `nonce` and `salt` (hex).

### Example
```js
import { createChallenge } from 'altcha/lib';
import { pbkdf2 } from 'altcha/lib';

const challenge = await createChallenge({
	algorithm: 'PBKDF2/SHA-256',
	cost: 5000,
	deriveKey: pbkdf2.deriveKey,
	expiresAt: Date.now() / 1000 + 120,
	hmacSignatureSecret: 'server-secret'
});
// challenge.signature is an HMAC-SHA-256 of the canonical JSON parameters
```

### Error Handling Example
```js
import { createChallenge, HmacAlgorithm } from 'altcha/lib';
import { scrypt } from 'altcha/lib';

try {
	const { parameters, derivedKey } = await createChallenge({
		algorithm: 'SCRYPT',
		cost: 5,
		counter: 17,
		keyPrefixLength: 8,
		deriveKey: scrypt.deriveKey,
		hmacAlgorithm: HmacAlgorithm.SHA_512,
		hmacSignatureSecret: 'secret-a',
		hmacKeySignatureSecret: 'secret-b'
	});
	console.log(parameters.keySignature, derivedKey?.length);
} catch (err) {
	// e.g. 'hmacKeySignatureSecret requires hmacSignatureSecret.'
	console.error(err.message);
}
```
```

--------------------------------

### ChallengeParameters

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/types.md

Defines the parameters for a proof-of-work challenge, including algorithm, nonce, salt, cost, and derived key requirements.

```APIDOC
## ChallengeParameters

### Description
Defines the parameters for a proof-of-work challenge, including algorithm, nonce, salt, cost, and derived key requirements.

### Fields
- **algorithm** (string) - Required - KDF name (SHA-*, PBKDF2/SHA-*, ARGON2ID, SCRYPT)
- **nonce** (string) - Required - Hex nonce (16 random bytes by createChallenge)
- **salt** (string) - Required - Hex salt
- **cost** (number) - Required - Iterations / cost factor
- **keyLength** (number) - Required - Derived key size in bytes
- **keyPrefix** (string) - Required - Hex prefix the derived key must start with
- **keySignature** (string) - Optional - HMAC of the derived key (set when hmacKeySignatureSecret used)
- **memoryCost** (number) - Optional - Argon2/Scrypt memory (KB / block size)
- **parallelism** (number) - Optional - Argon2/Scrypt parallelism
- **expiresAt** (number) - Optional - Unix seconds; verification refuses expired challenges
- **data** (Record<string, string | number | boolean | null>) - Optional - Opaque extra fields (e.g. v1 query params)

### Usage
Used by: createChallenge (output), deriveChallenge, solveChallenge (challenge.parameters), verifySolution, all deriveKey implementations, the widget's verify().
```

--------------------------------

### log(...args)

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/widget-element.md

Logs messages. Accepts any number of arguments. Returns void.

```APIDOC
## log(...args)

### Description
Log messages.

### Method
log

### Parameters
- **args** (any[]) - Required - Arguments to log.

### Returns
void
```

--------------------------------

### updateUI()

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/widget-element.md

Updates UI positioning. Takes no parameters and returns void.

```APIDOC
## updateUI()

### Description
Update UI positioning. Repositions floating UI or nudges popover positioning.

### Method
updateUI

### Parameters
None

### Returns
void

### Example
```js
widget.updateUI(); // after layout changes in floating mode
```
```

--------------------------------

### Verify with abort and duration control

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/widget-element.md

Shows how to use an AbortController to cancel verification after a timeout and set custom concurrency and duration constraints.

```js
const controller = new AbortController();
setTimeout(() => controller.abort(), 10_000);
const result = await widget.verify({ concurrency: 4, controller, minDuration: 1000 });
```

--------------------------------

### Strings

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/types.md

Required keys of every registered translation in $altcha.i18n.

```APIDOC
## Strings

### Description
Interface defining required translation keys.

### Properties
- `ariaLinkLabel` (string) - Required
- `enterCode` (string) - Required
- `enterCodeAria` (string) - Required
- `error` (string) - Required
- `expired` (string) - Required
- `footer` (string) - Required
- `getAudioChallenge` (string) - Required
- `label` (string) - Required
- `loading` (string) - Required
- `reload` (string) - Required
- `verify` (string) - Required
- `verificationRequired` (string) - Required
- `verified` (string) - Required
- `verifying` (string) - Required
- `waitAlert` (string) - Required
```

--------------------------------

### verifySolution

Source: https://github.com/altcha-org/altcha/blob/main/_autodocs/api-reference/pow.md

Verifies a submitted solution against a challenge. Checks expiration, signature validity, and solution correctness. Returns a result object with verification status.

```APIDOC
## verifySolution

### Description
Verifies a submitted solution against a challenge. Checks (in order): 1. Whether the challenge has expired. 2. Whether the challenge has signature parameter. 3. Whether the challenge signature is valid (tamper check). 4. Whether the derived key matches — either via key signature or by re-deriving.

### Signature
```ts
export async function verifySolution(
	options: VerifySolutionOptions
): Promise<VerifySolutionResult>
```

### Parameters
- **options.challenge** (Challenge) - Required - The original challenge
- **options.solution** (Solution) - Required - Submitted `{ counter, derivedKey }`
- **options.deriveKey** (DeriveKeyFunction) - Required - KDF used for path 4b re-derivation
- **options.hmacSignatureSecret** (string) - Required - Secret; must be non-empty
- **options.hmacAlgorithm** (HmacAlgorithm) - Optional, default `HmacAlgorithm.SHA_256` - HMAC hash
- **options.hmacKeySignatureSecret** (string) - Optional - Enables path 4a (key signature check)
- **options.counterMode** ('uint32' | 'string') - Optional, default 'uint32' - Counter encoding used to re-derive

### Returns
Returns `Promise<VerifySolutionResult>` with fields:
- **expired** (boolean) - `expiresAt` in the past (`challenge.parameters.expiresAt < Date.now() / 1000`)
- **invalidSignature** (boolean | null) - `null` once expired; `true` if the challenge is unsigned or the HMAC-SHA of `canonicalJSON(parameters)` does not match (constant-time compare)
- **invalidSolution** (boolean | null) - `null` when expired or signature invalid; `true` for malformed solutions or key/prefix mismatch
- **time** (number) - Elapsed ms
- **verified** (boolean) - `!expired && !invalidSignature && !invalidSolution`

### Verification Paths
After the tamper check: 4a — if `challenge.parameters.keySignature` and `hmacKeySignatureSecret` are present, HMAC the submitted `derivedKey` bytes and compare constant-time with `keySignature`; 4b — re-derive the key from `solution.counter` and require it to equal `solution.derivedKey` **and** satisfy the signed `keyPrefix`. Malformed solutions (non-even-length lowercase hex `derivedKey`, or a `counter` outside the mode bounds) are reported as `invalidSolution: true`, never thrown. A missing/empty `hmacSignatureSecret` throws `'hmacSignatureSecret must be a non-empty string.'`.

### Example
```js
import { verifySolution } from 'altcha/lib';
import { pbkdf2 } from 'altcha/lib';

const result = await verifySolution({
	challenge,
	solution,
	hmacSignatureSecret: 'server-secret',
	deriveKey: pbkdf2.deriveKey
});
if (!result.verified) {
	console.log({ expired: result.expired, badSignature: result.invalidSignature, badSolution: result.invalidSolution });
}
```
```
Tokens:
Raw