mirror of
https://github.com/versia-pub/server.git
synced 2025-12-06 16:38:19 +01:00
55 lines
2 KiB
Markdown
55 lines
2 KiB
Markdown
# Challenges API
|
|
|
|
Some API routes may require a cryptographic challenge to be solved before the request can be made. This is to prevent abuse of the API by bots and other malicious actors. The challenge is a simple mathematical problem that can be solved by any client.
|
|
|
|
This is a form of proof of work CAPTCHA, and should be mostly invisible to users. The challenge is generated by the server and sent to the client, which must solve it and send the solution back to the server.
|
|
|
|
## Solving a Challenge
|
|
|
|
Challenges are powered by the [Altcha](https://altcha.org/) library. You may either reimplement their solution code (which is very simple), or use [`altcha-lib`](https://github.com/altcha-org/altcha-lib) to solve the challenges.
|
|
|
|
## Request Challenge
|
|
|
|
```http
|
|
POST /api/v1/challenges
|
|
```
|
|
|
|
Generates a new challenge for the client to solve.
|
|
|
|
### Response
|
|
|
|
```ts
|
|
// 200 OK
|
|
{
|
|
id: string,
|
|
algorithm: "SHA-256" | "SHA-384" | "SHA-512",
|
|
challenge: string;
|
|
maxnumber?: number;
|
|
salt: string;
|
|
signature: string;
|
|
}
|
|
```
|
|
|
|
## Sending a Solution
|
|
|
|
To send a solution with any request, add the following headers:
|
|
- `X-Challenge-Solution`: A base64 encoded string of the following JSON object:
|
|
```ts
|
|
{
|
|
number: number; // Solution to the challenge
|
|
algorithm: "SHA-256" | "SHA-384" | "SHA-512";
|
|
challenge: string;
|
|
salt: string,
|
|
signature: string,
|
|
}
|
|
```
|
|
Example: `{"number": 42, "algorithm": "SHA-256", "challenge": "xxxx", "salt": "abc", "signature": "def"}` -> `eyJudW1iZXIiOjQyLCJhbGdvcml0aG0iOiJTSEEtMjU2IiwiY2hhbGxlbmdlIjoieHh4eCIsInNhbHQiOiJhYmMiLCJzaWduYXR1cmUiOiJkZWYifQ==`
|
|
|
|
A challenge solution is valid for 5 minutes (configurable) after the challenge is generated. No solved challenge may be used more than once.
|
|
|
|
## Routes Requiring Challenges
|
|
|
|
If challenges are enabled, the following routes will require a challenge to be solved before the request can be made:
|
|
- `POST /api/v1/accounts`
|
|
|
|
Which routes require challenges may eventually be expanded or made configurable. |