@proofofbot/client-altcha

Generated client for the altcha target. It talks to a wred sidecar over a pipe.

Solves ALTCHA proof-of-work challenges without a browser

Install

npm install @proofofbot/client-altcha

The binary for your platform arrives as an optional dependency. Set WRE_BINARY to an absolute path to override it with a local build.

Use

import { AltchaClient } from "@proofofbot/client-altcha";

const client = await AltchaClient.open({});
const result = await client.solve({ url: "https://example.com", his: true });
console.log(result);
await client.close();

One client owns one session, which owns the mounted realm. Open it once and reuse it. Opening one per call pays the warmup cost every time.

Configuration

These fields go in the object you pass to open. The session keeps them for its whole life.

| Field | Type | Default | Description | | --- | --- | --- | --- | | challenge_url | string \| null | optional | Endpoint the widget fetches its challenge from | | verify_url | string \| null | optional | Endpoint used by submit | | hmac_secret | string \| null | optional | Server secret, only needed by verify and create_challenge | | workers | number | 0 | Solver threads, 0 picks one per core | | max_counter | number | 5000000 | Highest counter the solver will try before giving up | | his | boolean | true | Answer an interaction signature request when the server asks for one | | proxy | string \| null | optional | - | | fingerprint | string \| null | optional | Client to emulate as profile[:platform], for example chrome_141:windows | | user_agent | string \| null | optional | User agent to send, which also picks the matching transport fingerprint | | clock_ms | number \| null | optional | Freeze the clock, which fixes the expiry checks | | seed | number \| null | optional | Seed the random source, which fixes the his samples | | timeout_ms | number | 30000 | - |

Operations

client.info(options)

What this build supports

Takes no arguments.

Returns:

| Field | Type | Description | | --- | --- | --- | | target | string | - | | version | string | - | | algorithms | Array<string> | - | | workers | number | - |

client.challenge(params, options)

Fetch a challenge, answering an interaction signature request if asked

Server side deadline: 30 s. Pass a shorter one per call to cap it further.

Takes:

| Field | Type | Default | Description | | --- | --- | --- | --- | | url | string \| null | optional | Overrides challenge_url from the session config | | his | boolean \| null | optional | Answer a human interaction signature request |

Returns:

| Field | Type | Description | | --- | --- | --- | | challenge | unknown | The challenge exactly as the server sent it | | format | number | 1 for the legacy format, 3 otherwise | | algorithm | string | - | | cost | number | - | | key_length | number | - | | expires_at | number \| null | - |

client.solve(params, options)

Fetch or take a challenge, solve it, and return the form payload

Server side deadline: 2 min. Pass a shorter one per call to cap it further.

Streams: progress.

Takes:

| Field | Type | Default | Description | | --- | --- | --- | --- | | challenge | unknown \| null | optional | A challenge object, otherwise one is fetched | | url | string \| null | optional | Challenge endpoint, overrides challenge_url | | his | boolean \| null | optional | - | | max_counter | number \| null | optional | - | | workers | number \| null | optional | - |

Returns:

| Field | Type | Description | | --- | --- | --- | | payload | string | Base64 form value for the altcha field | | field | string | - | | counter | number | - | | derived_key | string | - | | algorithm | string | - | | format | number | Challenge format, 1 or 3 | | attempts | number | - | | took_ms | number | - |

client.deriveKey(params, options)

Run one derivation, the unit the solver loops over

Takes:

| Field | Type | Default | Description | | --- | --- | --- | --- | | algorithm | string | required | - | | nonce | string | required | Hex, or plain text in string mode | | salt | string | "" | Hex | | counter | number | required | - | | cost | number | 1 | - | | key_length | number | 32 | - | | memory_cost | number \| null | optional | - | | parallelism | number \| null | optional | - | | counter_mode | string | "uint32" | - |

Returns:

| Field | Type | Description | | --- | --- | --- | | key | string | - | | password | string | - |

client.verify(params, options)

Check a payload the way an altcha server does

Takes:

| Field | Type | Default | Description | | --- | --- | --- | --- | | payload | string \| null | optional | - | | challenge | unknown \| null | optional | - | | solution | unknown \| null | optional | - | | secret | string \| null | optional | HMAC secret, overrides hmac_secret from the config |

Returns:

| Field | Type | Description | | --- | --- | --- | | verified | boolean | - | | expired | boolean | - | | invalid_signature | boolean \| null | - | | invalid_solution | boolean \| null | - | | format | number | - |

client.createChallenge(params, options)

Build a signed challenge, for tests and for measuring solve cost

Server side deadline: 1 min. Pass a shorter one per call to cap it further.

Takes:

| Field | Type | Default | Description | | --- | --- | --- | --- | | algorithm | string | "SHA-256" | - | | cost | number | 100000 | - | | counter | number \| null | optional | The counter the solver is meant to find | | key_length | number | 32 | - | | key_prefix_length | number \| null | optional | - | | nonce | string \| null | optional | - | | salt | string \| null | optional | - | | expires_in_s | number \| null | optional | - | | memory_cost | number \| null | optional | - | | parallelism | number \| null | optional | - | | secret | string \| null | optional | - | | format | number | 3 | - |

Returns:

| Field | Type | Description | | --- | --- | --- | | challenge | unknown | The challenge exactly as the server sent it | | format | number | 1 for the legacy format, 3 otherwise | | algorithm | string | - | | cost | number | - | | key_length | number | - | | expires_at | number \| null | - |

client.his(params, options)

Synthesise the pointer, scroll and focus samples the collector exports

Takes:

| Field | Type | Default | Description | | --- | --- | --- | --- | | width | number | 1280 | - | | height | number | 800 | - | | target_x | number \| null | optional | - | | target_y | number \| null | optional | - | | duration_ms | number | 1400 | - | | start_ms | number | 900 | - | | touch | boolean | false | - | | scroll | boolean | true | - |

Returns unknown.

client.deobfuscate(params, options)

Solve and decrypt text hidden by the obfuscation plugin

Server side deadline: 2 min. Pass a shorter one per call to cap it further.

Takes:

| Field | Type | Default | Description | | --- | --- | --- | --- | | data | string | required | The data-obfuscated attribute from the widget | | max_counter | number \| null | optional | - |

Returns:

| Field | Type | Description | | --- | --- | --- | | text | string | - | | counter | number | - | | took_ms | number | - |

client.serverSignature(params, options)

Parse and check a Sentinel server signature payload

Takes:

| Field | Type | Default | Description | | --- | --- | --- | --- | | payload | string | required | - | | secret | string \| null | optional | - | | fields | Record<string, unknown> \| null | optional | Form values, checked against fieldsHash when present |

Returns:

| Field | Type | Description | | --- | --- | --- | | verified | boolean | - | | expired | boolean | - | | invalid_signature | boolean | - | | invalid_solution | boolean | - | | fields_valid | boolean \| null | - | | verification_data | unknown | - |

client.submit(params, options)

Post a payload to a server verification endpoint

Server side deadline: 30 s. Pass a shorter one per call to cap it further.

Takes:

| Field | Type | Default | Description | | --- | --- | --- | --- | | url | string \| null | optional | Overrides verify_url from the session config | | payload | string | required | - | | code | string \| null | optional | - | | fields | Record<string, unknown> \| null | optional | - |

Returns:

| Field | Type | Description | | --- | --- | --- | | status | number | - | | ok | boolean | - | | body | unknown | - |

Events

solve streams progress while it runs. A session is not an emitter, so pass onEvent when you open the client to see every event, or per call to scope it to one:

const client = await AltchaClient.open({}, {
  onEvent: (id, event, data) => console.log(event, data),
});

await client.solve({ url: "https://example.com", his: true }, {
  onEvent: (id, event, data) => console.log(event, data),
});

| Event | Data | Description | | --- | --- | --- | | progress | Progress | Step counter for solve |

Deadlines and cancellation

Every op takes a second options argument: deadlineMs caps the call and fails it with kind === "timeout", signal takes an AbortSignal and fails it with kind === "cancelled". Both stop the work inside the sidecar, they do not only abandon the promise.

const abort = new AbortController();
setTimeout(() => abort.abort(), 5000);
await client.solve({ url: "https://example.com", his: true }, { signal: abort.signal, deadlineMs: 120000 });

Errors

Every rejection is a WreError with a stable kind: bad_input, unsupported, target_drift, blocked, timeout, cancelled, resource, protocol, internal. Branch on kind, never on the message. error.retryable says whether the same call is worth repeating.

Sidecar output and diagnostics

The sidecar logs to its own stderr, which is discarded by default. Pass { stderr: "inherit" } to open, or set WRE_STDERR=inherit, to see it.

A failing call writes a diagnostic report and puts its path in error.detail.diagnostics. WRE_DIAG=always records every call, WRE_DIAG=off records none, and await client.diagnose(true) writes one on demand. Send that file with a bug report.

Pinned build

• bundle default
• binary version 0.1.0
• schema hash 26bd761bdc493953

The schema hash is checked at connect time. A mismatch means this package and the installed binary disagree about the callable surface, and the connect call fails.