66 lines
2.7 KiB
Markdown
66 lines
2.7 KiB
Markdown
# 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.
|