standalone@2.0.13: better ratelimiting & docs

tiagozip · tiagozip · commit 1e796a310eae · 2025-10-25T11:04:14.000+01:00
diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs
@@ -159,25 +159,23 @@ export default withMermaid({
 		sidebar: [
 			{ text: "Quickstart", link: "/guide/index.md" },
 			{ text: "Feature comparison", link: "/guide/alternatives.md" },
-			{ text: "Community libraries", link: "/guide/community.md" },
 			{
-				text: "Libraries",
+				text: "Standalone",
 				collapsed: false,
 				items: [
-					{ text: "Server", link: "/guide/server.md" },
-					{ text: "Widget", link: "/guide/widget.md" },
-					{ text: "Solver", link: "/guide/solver.md" },
+					{ text: "Quickstart", link: "/guide/standalone/index.md" },
+					{ text: "API", link: "/guide/standalone/api.md" },
+					{ text: "Options", link: "/guide/standalone/options.md" },
 				],
 			},
 			{
-				text: "Standalone",
+				text: "Libraries",
 				collapsed: true,
 				items: [
-					{ text: "About", link: "/guide/standalone/index.md" },
-					{ text: "Installation", link: "/guide/standalone/installation.md" },
-					{ text: "Usage", link: "/guide/standalone/usage.md" },
-					{ text: "API", link: "/guide/standalone/api.md" },
-					{ text: "Options", link: "/guide/standalone/options.md" },
+					{ text: "Server", link: "/guide/server.md" },
+					{ text: "Widget", link: "/guide/widget.md" },
+					{ text: "Solver", link: "/guide/solver.md" },
+			{ text: "Community libraries", link: "/guide/community.md" },
 				],
 			},
 			{
diff --git a/docs/guide/standalone/index.md b/docs/guide/standalone/index.md
@@ -2,8 +2,111 @@
 
 Cap Standalone is a self-hosted version of Cap's backend that allows you to spin up a server to validate and create challenges so you can use it with languages other than JS.
 
-It's simple yet amazingly powerful, allowing you to use Cap in any language that can make HTTP requests. It's mostly compatible with reCAPTCHA and hCaptcha's siteverify enpoints, so you can use it as a drop-in replacement for them.
+It's simple yet powerful, allowing you to use Cap in any language that can make HTTP requests. It's mostly compatible with reCAPTCHA and hCaptcha's siteverify enpoints, so you can use it as a drop-in replacement for them.
 
-It also offers API key support, a built-in assets server, a dashboard with statistics, and more. To get started, follow [the instructions to install it on your server](installation.md).
+It also offers API key support, a built-in assets server, a dashboard with statistics, and more.
 
 ![Screenshot of Cap's standalone mode](/standalone_screenshot.png)
+
+## Installation
+
+### Requirements
+
+You'll need to have [Docker Engine 20.10 or higher](https://docs.docker.com/get-docker/) installed on your server. Both `x86_64` (amd64) and `arm64` architectures are supported.
+
+---
+
+Run the following command to pull the Cap Standalone Docker image from Docker Hub:
+
+```bash
+docker pull tiago2/cap:latest
+```
+
+Then, to run the server, use the following command:
+
+```bash
+docker run -d \
+  -p 3000:3000 \
+  -v cap-data:/usr/src/app/.data \
+  -e ADMIN_KEY=your_secret_password \
+  --name cap-standalone \
+  tiago2/cap:latest
+```
+
+Make sure to replace `your_secret_password` with a strong password, as anyone with it will be able to log into the dashboard and create keys. It'll need to be at least 30 characters long.
+
+Then, you can access the dashboard at `http://localhost:3000`, log in, and create a key. You'll get a site key and a secret key which you'll be able to use on your widget.
+
+On Debian and other OSes that don't use `iptables`, if you can't open the dashboard, try setting `--network=host` in the run command. Thanks to [Boro Vukovic](https://github.com/tiagozip/cap/issues/70#issuecomment-3086464282) for letting me know about this.
+
+You'll also need to make the server publicly accessible from the internet, as the widget needs to be able to reach it. If you're using a reverse proxy, make sure to check [the options guide](/guide/standalone/options.md) to configure rate-limiting properly.
+
+## Usage
+
+### Client-side
+
+Let's configure your widget to use your self-hosted Cap Standalone server. To do this, set the widget's API endpoint option to:
+
+```
+https://<instance_url>/<site_key>/
+```
+
+Make sure to replace:
+
+- `<instance_url>`: The actual URL where your Cap Standalone instance is running. This URL must be publicly accessible from the internet.
+- `<site_key>`: Your site key from this dashboard.
+
+Example:
+
+```html
+<cap-widget
+  data-cap-api-endpoint="https://cap.example.com/d9256640cb53/"
+></cap-widget>
+```
+
+### Server-side
+
+After a user completes the CAPTCHA on your site, your backend needs to verify their token using this server's API.
+
+You can do this by sending a `POST` request from your server to the following endpoint:
+
+```
+https://<instance_url>/<site_key>/siteverify
+```
+
+Your request needs to include the following data:
+
+- `secret`: Your key secret from this dashboard. This is **not** the admin key, but rather your site key's secret.
+
+- `response`: The CAPTCHA token generated by the widget on the client-side
+
+Example using `curl`:
+
+```bash
+curl "https://<instance_url>/<site_key>/siteverify" \
+  -X POST \
+  -H "Content-Type: application/json" \
+  -d '{ "secret": "<key_secret>", "response": "<captcha_token>" }'
+```
+
+The response should look like this:
+
+```json
+{
+  "success": true
+}
+```
+
+Or, if the captcha token is invalid or expired, it will return:
+
+```json
+{
+  "success": false
+}
+```
+
+If `success` is true, you can proceed with your app logic.
+
+### Client-side library storage
+
+Cap Standalone can also serve the widget and floating client-side library files. [Learn more](options.md#asset-server).
diff --git a/docs/guide/standalone/installation.md b/docs/guide/standalone/installation.md
@@ -1,34 +1,3 @@
 # Installation
 
-### Requirements
-
-You'll need to have [Docker Engine 20.10 or higher](https://docs.docker.com/get-docker/) installed on your server. Both `x86_64` (amd64) and `arm64` architectures are supported.
-
----
-
-Run the following command to pull the Cap Standalone Docker image from Docker Hub:
-
-```bash
-docker pull tiago2/cap:latest
-```
-
-Then, to run the server, use the following command:
-
-```bash
-docker run -d \
-  -p 3000:3000 \
-  -v cap-data:/usr/src/app/.data \
-  -e ADMIN_KEY=your_secret_password \
-  --name cap-standalone \
-  tiago2/cap:latest
-```
-
-Make sure to replace `your_secret_password` with a strong password, as anyone with it will be able to log into the dashboard and create keys. It'll need to be at least 30 characters long.
-
-Then, you can access the dashboard at `http://localhost:3000`, log in, and create a key. You'll get a site key and a secret key which you'll be able to use on your widget.
-
-On Debian and other OSes that don't use `iptables`, if you can't open the dashboard, try setting `--network=host` in the run command. Thanks to [Boro Vukovic](https://github.com/tiagozip/cap/issues/70#issuecomment-3086464282) for letting me know about this.
-
-You'll also need to make the server publicly accessible from the internet, as the widget needs to be able to reach it.
-
-Done! Now, read the [usage guide](/guide/standalone/usage.md) to learn how to use it.
+This section has moved to [Standalone](/guide/standalone/index.md).
diff --git a/docs/guide/standalone/options.md b/docs/guide/standalone/options.md
@@ -43,7 +43,9 @@ By default, Standalone will use Elysia's built-in `server.requestIP` function to
 
 If so, you can change the IP extraction logic to simply read from a header set in `RATELIMIT_IP_HEADER` in your env. For example, if you were using Cloudflare, you might set `RATELIMIT_IP_HEADER` to `cf-connecting-ip`. On most setups, this is `x-forwarded-for`.
 
+The `/siteverify` endpoint is intended for server-to-server use, so each request checks if your key's secret is valid. If it is, the request is allowed. If not, the request is denied and the client's IP is temporarily blocked for a few hundred milliseconds. This prevents database strain without affecting legitimate requests.
+
 If you're interested in an option to fully disable ratelimiting, let us know using GitHub issues.
 
 ## Custom data path
-If you would like the data to be stored in a custom path inside the container, you can set the `DATA_PATH` environment variable to the desired path. Note that this only works in Standalone 2.0.9 or above. Added by [#100](https://github.com/tiagozip/cap/issues/100)
+If you would like the data to be stored in a custom path inside the container, you can set the `DATA_PATH` environment variable to the desired path. Note that this only works in Standalone 2.0.9 or above.
diff --git a/docs/guide/standalone/usage.md b/docs/guide/standalone/usage.md
@@ -1,73 +1,3 @@
-# Usage
+# Installation
 
-First, make sure Cap Standalone is installed and running by following [the installation guide](installation.md).
-
-Then, you can get to using Cap Standalone:
-
-### Client-side
-
-Let's configure your widget to use your self-hosted Cap Standalone server. To do this, set the widget's API endpoint option to:
-
-```
-https://<instance_url>/<site_key>/
-```
-
-Make sure to replace:
-
-- `<instance_url>`: The actual URL where your Cap Standalone instance is running. This URL must be publicly accessible from the internet.
-- `<site_key>`: Your site key from this dashboard.
-
-Example:
-
-```html
-<cap-widget
-  data-cap-api-endpoint="https://cap.example.com/d9256640cb53/"
-></cap-widget>
-```
-
-### Server-side
-
-After a user completes the CAPTCHA on your site, your backend needs to verify their token using this server's API.
-
-You can do this by sending a `POST` request from your server to the following endpoint:
-
-```
-https://<instance_url>/<site_key>/siteverify
-```
-
-Your request needs to include the following data:
-
-- `secret`: Your key secret from this dashboard. This is **not** the admin key, but rather your site key's secret.
-
-- `response`: The CAPTCHA token generated by the widget on the client-side
-
-Example using `curl`:
-
-```bash
-curl "https://<instance_url>/<site_key>/siteverify" \
-  -X POST \
-  -H "Content-Type: application/json" \
-  -d '{ "secret": "<key_secret>", "response": "<captcha_token>" }'
-```
-
-The response should look like this:
-
-```json
-{
-  "success": true
-}
-```
-
-Or, if the captcha token is invalid or expired, it will return:
-
-```json
-{
-  "success": false
-}
-```
-
-If `success` is true, you can proceed with your app logic.
-
-### Client-side library storage
-
-To learn more about using the client-side library, check out the [guide on it](options.md#asset-server).
+This section has moved to [Standalone](/guide/standalone/index.md).
diff --git a/standalone/package.json b/standalone/package.json
@@ -1,6 +1,6 @@
 {
   "name": "cap-standalone",
-  "version": "2.0.12",
+  "version": "2.0.13",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
     "dev": "bun run --watch src/index.js",
diff --git a/standalone/src/cap.js b/standalone/src/cap.js
@@ -9,9 +9,6 @@ import { ratelimitGenerator } from "./ratelimit.js";
 const getSitekeyConfigQuery = db.query(
 	`SELECT (config) FROM keys WHERE siteKey = ?`,
 );
-const getSitekeyWithSecretQuery = db.query(
-	`SELECT * FROM keys WHERE siteKey = ?`,
-);
 
 const insertChallengeQuery = db.query(`
   INSERT INTO challenges (siteKey, token, data, expires)
@@ -28,12 +25,6 @@ const insertTokenQuery = db.query(`
   INSERT INTO tokens (siteKey, token, expires)
   VALUES (?, ?, ?)
 `);
-const getTokenQuery = db.query(`
-  SELECT * FROM tokens WHERE siteKey = ? AND token = ?
-`);
-const deleteTokenQuery = db.query(`
-  DELETE FROM tokens WHERE siteKey = ? AND token = ?
-`);
 
 const upsertSolutionQuery = db.query(`
   INSERT INTO solutions (siteKey, bucket, count)
@@ -138,40 +129,4 @@ export const capServer = new Elysia({
 			token,
 			expires,
 		};
-	})
-	.post("/:siteKey/siteverify", async ({ body, set, params }) => {
-		const sitekey = params.siteKey;
-		const { secret, response } = body;
-
-		if (!sitekey || !secret || !response) {
-			set.status = 400;
-			return { error: "Missing required parameters" };
-		}
-
-		const keyHash = getSitekeyWithSecretQuery.get(sitekey)?.secretHash;
-		if (!keyHash) {
-			set.status = 404;
-			return { error: "Invalid site key or secret" };
-		}
-
-		if (!(await Bun.password.verify(secret, keyHash))) {
-			set.status = 403;
-			return { error: "Invalid site key or secret" };
-		}
-
-		const token = getTokenQuery.get(params.siteKey, response);
-
-		if (!token) {
-			set.status = 404;
-			return { error: "Token not found" };
-		}
-
-		if (token.expires < Date.now()) {
-			deleteTokenQuery.run(params.siteKey, response);
-			set.status = 403;
-			return { error: "Token expired" };
-		}
-
-		deleteTokenQuery.run(params.siteKey, response);
-		return { success: true };
 	});
diff --git a/standalone/src/index.js b/standalone/src/index.js
@@ -5,6 +5,7 @@ import { assetsServer } from "./assets.js";
 import { auth } from "./auth.js";
 import { capServer } from "./cap.js";
 import { server } from "./server.js";
+import { siteverifyServer } from "./siteverify.js";
 
 const serverPort = process.env.SERVER_PORT || 3000;
 const serverHostname = process.env.SERVER_HOSTNAME || "0.0.0.0";
@@ -71,6 +72,7 @@ new Elysia({
   .use(server)
   .use(assetsServer)
   .use(capServer)
+  .use(siteverifyServer)
   .listen(serverPort);
 
 console.log(`🧢 Cap running on http://${serverHostname}:${serverPort}`);
diff --git a/standalone/src/siteverify.js b/standalone/src/siteverify.js

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "cap-standalone",`
`3`		`- "version": "2.0.12",`
	`3`	`+ "version": "2.0.13",`
`4`	`4`	`"scripts": {`
`5`	`5`	`"test": "echo \"Error: no test specified\" && exit 1",`
`6`	`6`	`"dev": "bun run --watch src/index.js",`