# Proof-of-work

> **Sentinel v2 (beta):** This page documents Sentinel v2, a beta rewrite that may change before the stable release. It does not apply to Sentinel v1, the current stable version: see the [Sentinel v1 documentation](/docs/sentinel.md).

Every challenge Sentinel issues is a proof-of-work that the ALTCHA widget solves in the browser before the form can be submitted. It costs a visitor a moment of computing time and costs an automated client that time on every submission; security-group rules decide the algorithm and how much work each request gets.

## How it works

Sentinel issues challenges in ALTCHA's deterministic mode:

1. `GET /v2/challenge` picks a random counter from the `pow.counter` range and derives a key from a random nonce, salt and that counter with the chosen algorithm and cost. The challenge carries the first half of the key (`keyPrefix`), an HMAC of the whole key (`keySignature`), and is signed with the API key's secret.
2. The widget derives keys for counters 0, 1, 2, … until one starts with `keyPrefix`. The work is about the counter times one derivation, split across the widget's workers.
3. `POST /v2/verify` checks the signature and the HMAC of the submitted key. It doesn't derive the key again, so only the challenge endpoints pay for derivations.

A challenge verifies once, only with the API key that issued it, and only from the device that fetched it (see [Verifying submissions](/docs/sentinel/v2/integrate/verification/)). It expires after `pow.expires`, default `20m`.

A security group without rules issues `PBKDF2/SHA-256` challenges with cost `5000` and a counter of `1-15000`. This is a light challenge for ordinary visitors; rules raise it for clients that look risky.

### Algorithms

| Algorithm | `pow.cost` is | Default cost | Default counter | Widget solver |
| --- | --- | --- | --- | --- |
| `PBKDF2/SHA-256` (default), `PBKDF2/SHA-384`, `PBKDF2/SHA-512` | Iterations | `5000` | `1-15000` | Bundled |
| `SHA-256`, `SHA-384`, `SHA-512` | Hash rounds | `5000` | `1-1000` | Bundled |
| `ARGON2ID` | Passes; memory is `pow.memoryCost` (default `65536` KiB) | `2` | `1-200` | Import separately |
| `SCRYPT` | N, a power of 2; the memory is N KiB (block size 8) | `65536` | `1-200` | Import separately |

PBKDF2 and SHA cost CPU time only, which GPUs and ASICs compute far faster and in parallel. `ARGON2ID` and `SCRYPT` are memory-hard: every attempt has to allocate the memory cost, which narrows the gap between a phone and specialized hardware.

### When memory-hard is worth the cost

Memory-hard challenges pay off against attackers who solve challenges at scale on GPUs or solver farms, which is the usual source of high-volume automated sign-ups and form spam. They have three costs:

- **The widget needs the solver.** The widget bundles only the PBKDF2 and SHA solvers. Register the `ARGON2ID` and `SCRYPT` workers under `$altcha.algorithms` on every page that uses the key; a widget without them can't solve the challenge. See [Algorithms](/docs/integration/widget/#algorithms) in the widget docs.
- **Visitors pay memory per worker.** Each widget worker allocates the memory cost, so 64 MiB with 8 workers is 512 MiB. Old phones may run out of memory or take noticeably longer; the widget's `retryOnOutOfMemoryError` option retries with fewer workers.
- **Sentinel pays memory and CPU per challenge.** Each `GET /v2/challenge` runs one derivation at the full cost.

If your visitors are mostly on desktops and you see solver traffic, use memory-hard challenges for every request or only for elevated ones. If many visitors use low-end phones, keep PBKDF2 as the base and switch to `ARGON2ID` with a modest `pow.memoryCost` only for risky clients.

## Enabling it

Proof-of-work is always on. Two server settings limit what rules can ask for:

```toml
[pow]
max_memory_cost = 131072   # KiB: caps pow.memoryCost and scrypt N at 128 MiB (default 262144)
cpus            = 4        # derivations at once; default: half the available CPUs, at least 1
```

`[pow] max_memory_cost` (1024 to 4194304 KiB) is the largest memory one derivation may use. Rules above it are rejected when saved; rules saved under a higher cap still issue challenges, with the memory lowered to the cap. `[pow] cpus` (1 to 1024) caps how many challenge derivations run at once, for any algorithm; further challenges wait for a free slot. With memory-hard challenges, Sentinel's peak memory for derivations is about `cpus` × the memory cost. See [`[pow]`](/docs/sentinel/v2/reference/configuration/#pow) in the Configuration reference.

Rules set everything else. This `set` rule moves every challenge of the group to Argon2id with 16 MiB of memory and a 5-minute lifetime:

```json
{
"name": "memory-hard",
"action": "set",
"set": [
{ "field": "pow.algorithm", "value": "ARGON2ID" },
{ "field": "pow.cost", "value": "2" },
{ "field": "pow.memoryCost", "value": "16384" },
{ "field": "pow.counter", "value": "1-400" },
{ "field": "pow.expires", "value": "5m" }
]
}
```

Add a condition, such as `penalty` `>=` `3` or `risk` `>=` `4`, to apply it to risky clients only. See [Writing security rules](/docs/sentinel/v2/policies/security-rules/#challenge-harder-on-penalty) for an escalation recipe and [Apply rules](/docs/sentinel/v2/policies/security-rules/#apply-rules) for saving rules in the admin UI or with the API.

> **Warning:**
>
> Load the `ARGON2ID` or `SCRYPT` worker in the widget before a rule switches a key to that algorithm. Otherwise no visitor can solve a challenge.

The admin UI writes ready-made memory-hard rules too: check **Memory-hard proof-of-work (Argon2id)** on a security group's **Templates** tab before you apply a base preset. See [Memory-hard variants](/docs/sentinel/v2/policies/presets/#memory-hard-variants) for the memory and counter of each preset.

## Rules & signals

Proof-of-work has no classifier rules of its own. These `set` fields tune it:

| Field | What it controls |
| --- | --- |
| `pow.algorithm` | The algorithm, case-insensitive. |
| `pow.cost` | The algorithm's cost: iterations, hash rounds, Argon2id passes (1–10), or scrypt N. |
| `pow.memoryCost` | Argon2id memory in KiB, 1024 to `[pow] max_memory_cost`. Other algorithms ignore it. |
| `pow.counter` | The counter as `N` or a random `MIN-MAX` range, within 1–1000000. The main difficulty setting. |
| `pow.expires` | The challenge lifetime, `10s` to `24h`. |

Ranges and defaults are in the [Rules reference](/docs/sentinel/v2/reference/rules/#proof-of-work).

Sentinel checks a `pow.cost` against every algorithm it can end up with, as if any combination of rules could match. A cost without a `pow.algorithm` in the same rule must fit the algorithms of earlier rules and the default, and a later rule that sets only `pow.algorithm` must accept the costs before it. A list that breaks this is rejected:

```json
{
"code": "INVALID_RULES",
"error": "rules[1].set[0].value: must be an integer from 1 to 10 for ARGON2ID (pow.algorithm of rules[0]); set pow.algorithm and pow.cost in the same rule",
"statusCode": 400
}
```

Set `pow.algorithm` and `pow.cost` in the same rule to avoid this.

Each verification signs the algorithm as `challenge.algorithm` in `verificationData`. Request logs record it as **Proof-of-work algorithm**, and Prometheus counts issued challenges in `altcha_sentinel_challenges_issued_total` by `algorithm` and `protection_level`.

## Using the API

The widget fetches challenges itself; you call `GET /v2/challenge` directly only to test your rules. Use a `public` key. Without rules, the group issues the default challenge:

```bash
curl 'https://sentinel.example.com/v2/challenge?apiKey=key_…'
```

```json
{
"configuration": {
"serverVerificationFields": false,
"serverVerificationTimeZone": true,
"verifyUrl": "/v2/verify"
},
"parameters": {
"algorithm": "PBKDF2/SHA-256",
"cost": 5000,
"data": { "edk": "12bc56b2…", "id": "a351236c…", "issued": 1795055939725 },
"expiresAt": 1795057139,
"keyLength": 32,
"keyPrefix": "0ef5cee25ca54376907743c3a4ce5221",
"keySignature": "60137202…",
"nonce": "f95ce641…",
"salt": "af5a0108…"
},
"signature": "358ffc5e…"
}
```

The challenge isn't wrapped in `{ "data": … }`, because the widget expects this shape. With the `memory-hard` rule above saved, the same request returns:

```json
{
"configuration": { … },
"parameters": {
"algorithm": "ARGON2ID",
"cost": 2,
"data": { "edk": "12bc56b2…", "id": "50d2f521…", "issued": 1795055971816 },
"expiresAt": 1795056271,
"keyLength": 32,
"keyPrefix": "d0e802b9d4e1a43417c89907ffc401fb",
"keySignature": "47a459bf…",
"memoryCost": 16384,
"nonce": "b86f86bf…",
"salt": "482f3466…"
},
"signature": "6c10086d…"
}
```

- `memoryCost` is omitted for PBKDF2 and SHA. For `SCRYPT` it is the block size, always `8`, and `cost` is N.
- `expiresAt` is in unix seconds, `issued` in unix milliseconds: here 300 seconds apart, from `pow.expires` `5m`.
- The counter isn't in the response; the widget finds it.

See [`GET /v2/challenge`](/sentinel-api-docs-v2.html#tag/challenge/GET/v2/challenge) in the API reference.

## Tuning

- **Raise the counter first.** The counter multiplies the visitor's work directly, costs Sentinel nothing extra (it derives one key whatever the counter), and needs no widget changes. The presets escalate from the default `1-15000` to `1-30000` and `1-50000` for risky clients. A range picks a new counter for each challenge, so solve times vary.
- **Start counter ranges at 1.** The widget searches from 0, but a solver that knows the minimum (from a preset, or from the counters of challenges it already solved) starts there, so `MIN-MAX` costs it only as much as `1-(MAX-MIN)` while your visitors still pay for `MIN`. With `1-MAX`, the longest solve stays the same and visitors and solvers alike pay about `MAX/2` derivations on average. Every default and preset starts at 1.
- **Keep `pow.cost` at the default** unless you have a reason. For PBKDF2 and SHA, the visitor's work grows with the cost as with the counter, but a higher cost also raises Sentinel's own derivation time per challenge.
- **Measure on a low-end phone.** Fetch a challenge with the rule you plan and solve it in the widget on the slowest device your visitors use. Memory-hard costs that work on a desktop can fail on a phone.
- **Shorten `pow.expires`** for login and sign-up forms (the **Strict** preset uses `5m`), so solved challenges can't be stockpiled. Keep it longer than the time a visitor needs to fill in the form, or the submission fails with `CHALLENGE_EXPIRED`.
- **Combine it with rate limits.** Proof-of-work slows each request but doesn't cap them. Add `rateLimit.limits` (see [Rate limiting & penalty](/docs/sentinel/v2/features/rate-limiting/)), which also protects Sentinel's CPU from challenge floods.
- **Size `[pow] cpus` for your traffic.** With memory-hard algorithms, a burst of challenges queues for the derivation slots. Raise `cpus` on a dedicated host, or lower `max_memory_cost` to bound memory.

Monitor mode doesn't help with `set` rules here: a monitored rule's settings aren't applied, so its challenge stays unchanged. Test a new rule on a separate key and security group instead.

## Limitations

- Proof-of-work raises the cost of each submission; it doesn't detect bots. An attacker who pays the cost gets through, so combine it with the [classifier](/docs/sentinel/v2/features/classifier/), [Human Interaction Signature](/docs/sentinel/v2/features/human-interaction-signature/) and rate limits.
- Memory-hard algorithms work only with widgets that load their solvers. Native apps and custom clients need an Argon2id or scrypt implementation too.
- Only widget v3 and later are supported; legacy SHA challenges from widgets 2.x and earlier get `400 INVALID_PAYLOAD`.
- Sentinel derives one key per challenge, so challenge floods cost it CPU, and with memory-hard algorithms memory. `[pow] cpus` bounds the cost, at the price of queued challenges.

## Related

- [`pow.*` set fields](/docs/sentinel/v2/reference/rules/#proof-of-work) in the Rules reference
- [`[pow]`](/docs/sentinel/v2/reference/configuration/#pow) in the Configuration reference
- [Memory-hard variants](/docs/sentinel/v2/policies/presets/#memory-hard-variants) of the security presets
- [Code challenge](/docs/sentinel/v2/features/code-challenge/)
- [Widget integration](/docs/sentinel/v2/integrate/widget/) and the widget's [algorithm workers](/docs/integration/widget/#algorithms)
- [Verifying submissions](/docs/sentinel/v2/integrate/verification/)
