New Captcha Package added

2026-07-25 13:38:18 +05:30
parent d0aded0392
commit 8b728a3e5d
157 changed files with 12092 additions and 1913 deletions
@@ -0,0 +1,66 @@
+# WRNexus Managed CAPTCHA service starter
+
+A provider-neutral HTTP service built on `@wrnexus/captcha`. It includes:
+
+- Project creation and listing behind an admin bearer token
+- Public site keys and one-time-returned secret keys
+- SHA-256 secret-key storage
+- Allowed-hostname enforcement
+- Monthly challenge quotas
+- Secret-key rotation
+- Public challenge creation (`POST /v1/challenges`) with visual disturbance from 25 through 75 and 18 generated image renderer styles
+- Managed self-hosted `not-robot` checkbox challenges
+- Public answer solving (`POST /v1/solve`)
+- Secret-authenticated one-use token verification (`POST /v1/verify`)
+
+## Run
+
+```bash
+CAPTCHA_ADMIN_TOKEN="replace-with-a-long-random-token" \
+CAPTCHA_BASE_URL="http://localhost:8787" \
+bun run dev
+```
+
+Create a project:
+
+```bash
+curl -X POST http://localhost:8787/v1/projects \
+  -H "Authorization: Bearer $CAPTCHA_ADMIN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"Website","allowedHostnames":["localhost","example.com"],"monthlyQuota":10000}'
+```
+
+Create a challenge with controlled visual disturbance:
+
+```bash
+curl -X POST http://localhost:8787/v1/challenges \
+  -H "Content-Type: application/json" \
+  -d '{"siteKey":"YOUR_SITE_KEY","action":"signup","type":"image","disturbance":50}'
+```
+
+Create an “I’m not a robot” checkbox challenge:
+
+```bash
+curl -X POST http://localhost:8787/v1/challenges \
+  -H "Content-Type: application/json" \
+  -d '{"siteKey":"YOUR_SITE_KEY","action":"signup","type":"not-robot"}'
+```
+
+The secret key is returned only when a project is created or rotated. Store it in a secret manager.
+
+## Production work still required
+
+The included service is a complete reference/starter, not a turnkey global control plane. Replace the in-memory project and CAPTCHA stores with durable shared adapters, add authenticated organization/workspace ownership, audit logs, billing, dashboards, regional routing, metrics, backups, and operational alerting before public multi-tenant production use.
+
+## Generated image styles
+
+Managed challenge creation accepts the same renderer controls as the self-hosted engine:
+
+```bash
+curl -X POST https://captcha.example.com/v1/challenges \
+  -H "content-type: application/json" \
+  -d '{"siteKey":"YOUR_SITE_KEY","action":"signup","type":"alphanumeric","imageStyle":"random","allowedStyles":["classic","snow","distortion","wave"],"disturbance":50}'
+```
+
+Supported concrete renderers are `classic`, `collision`, `snow`, `corrosion`, `spiderweb`, `cross-shadow`, `split`, `split2`, `cut`, `darts`, `distortion`, `stitch`, `striped`, `wave`, `grid-noise`, `scribble`, `pixel`, and `broken-lines`. Challenge metadata returns the resolved renderer, requested renderer, and active pool.
+