374 lines
12 KiB
Markdown
374 lines
12 KiB
Markdown
# @wrnexus/captcha
|
||
|
||
A first-class CAPTCHA and anti-automation package for WRNexusJS. It supports self-hosted challenges, a managed WRNexus service, external providers, form submission guards, page gates, accessible audio, adaptive risk checks, and a Tailwind-only `.wrn` component.
|
||
|
||
## Install
|
||
|
||
```bash
|
||
bun add @wrnexus/captcha
|
||
```
|
||
|
||
WRNexusJS automatically discovers the package plugin, component, client runtime, styles, and DevToolbar audit. Use `<Captcha />` directly after installation. The browser runtime is injected once only on responses that render a CAPTCHA; no script tag, public-file copy, or manual plugin registration is required. Call `captchaPlugin(options)` explicitly only when an application needs to override the discovered package configuration.
|
||
|
||
## Included challenge modes
|
||
|
||
- Number, alphabet, and alphanumeric image challenges
|
||
- Addition, subtraction, multiplication, and exact-division calculations
|
||
- Generated shape-selection image challenges
|
||
- Audio alternatives for text, numbers, and calculations
|
||
- Honeypot and minimum-completion-time invisible checks
|
||
- Self-hosted “I’m not a robot” checkbox challenge with one-time server verification
|
||
- Always, once-per-session, and adaptive page gates
|
||
- Cloudflare Turnstile, Google reCAPTCHA, hCaptcha, managed, and custom providers
|
||
|
||
## Create the self-hosted engine
|
||
|
||
```ts
|
||
import {
|
||
createCaptchaEngine,
|
||
createCaptchaHttpHandlers,
|
||
RedisCaptchaStore,
|
||
} from "@wrnexus/captcha/server";
|
||
|
||
const engine = createCaptchaEngine({
|
||
secret: process.env.CAPTCHA_SECRET!,
|
||
store: new RedisCaptchaStore(redis),
|
||
basePath: "/api/captcha",
|
||
challengeTtlMs: 2 * 60_000,
|
||
responseTokenTtlMs: 5 * 60_000,
|
||
maxAttempts: 3,
|
||
minCompletionMs: 800,
|
||
});
|
||
|
||
export const handlers = createCaptchaHttpHandlers(engine);
|
||
```
|
||
|
||
Mount the handlers from an API catch-all route:
|
||
|
||
```ts
|
||
import type { Context } from "@wrnexus/core";
|
||
import { handlers } from "../../lib/captcha.ts";
|
||
|
||
export async function POST(ctx: Context) {
|
||
return (await handlers.handle(ctx.req, ctx)) ?? new Response("Not Found", { status: 404 });
|
||
}
|
||
export const GET = POST;
|
||
export const HEAD = POST;
|
||
```
|
||
|
||
## Use the component
|
||
|
||
```wrn
|
||
<Captcha
|
||
type="alphanumeric"
|
||
action="signup"
|
||
endpoint="/api/captcha/challenge"
|
||
verifyEndpoint="/api/captcha/verify"
|
||
difficulty="normal"
|
||
disturbance="50"
|
||
imageStyle="random"
|
||
allowedStyles="classic,snow,distortion,wave"
|
||
size="normal"
|
||
showAudio="true"
|
||
showListen="true"
|
||
@success='captchaToken = event.detail.responseToken'
|
||
@failure='formError = event.detail.extra.message'
|
||
/>
|
||
```
|
||
|
||
The component uses Tailwind utilities and `--wire-*` theme variables. It has no companion component CSS file.
|
||
|
||
### Main props
|
||
|
||
`provider`, `siteKey`, `type`, `action`, `presentation`, `difficulty`, `disturbance`, `imageStyle`, `allowedStyles`, `excludedStyles`, `randomizeStyle`, `locale`, `size`, `color`, `class`, `name`, `endpoint`, `verifyEndpoint`, `responseField`, labels/messages, `autoLoad`, `autoVerify`, `showVerify`, `showRefresh`, `showAudio`, `showListen`, `showStatus`, `disabled`, `required`, and the backward-compatible `compact` alias.
|
||
|
||
### Component sizes
|
||
|
||
Use one of the three supported display modes:
|
||
|
||
```wrn
|
||
<Captcha size="compact" action="small-form" />
|
||
<Captcha size="normal" action="standard-form" />
|
||
<Captcha size="big" action="security-page" />
|
||
```
|
||
|
||
`small`/`sm` are accepted as aliases for `compact`, while `large`/`lg` are accepted as aliases for `big`. The old `compact="true"` prop still forces compact mode.
|
||
|
||
### Listen button visibility
|
||
|
||
Audio remains available by default. Hide the Listen and Use audio controls with either of these props:
|
||
|
||
```wrn
|
||
<Captcha showListen="false" action="without-listen-button" />
|
||
<Captcha showAudio="false" action="without-audio-alternative" />
|
||
```
|
||
|
||
`showListen` is the direct UI switch. `showAudio` remains the broader backward-compatible audio switch.
|
||
|
||
### I’m not a robot checkbox
|
||
|
||
```wrn
|
||
<Captcha
|
||
type="not-robot"
|
||
action="contact-submit"
|
||
size="compact"
|
||
showListen="false"
|
||
/>
|
||
```
|
||
|
||
The checkbox is not a client-only boolean. Clicking it completes a self-hosted invisible challenge that is time-limited, attempt-limited, one-time-use, action-bound, optionally session/hostname/IP-bound, and verified on the server. It is a low-friction anti-automation layer; use adaptive escalation to a visual or external provider for high-risk traffic.
|
||
|
||
### Visual disturbance
|
||
|
||
Use `disturbance` for visual and image-selection challenges. It accepts an integer from `25` through `75`:
|
||
|
||
- `25`: light disturbance and easiest readability
|
||
- `50`: balanced default
|
||
- `75`: maximum supported dots, line crossings, glyph movement, and image-tile noise
|
||
|
||
The browser sends this value to the challenge API, and the server validates the range before generating the challenge. It is also returned in challenge metadata.
|
||
|
||
### Generated image renderer styles
|
||
|
||
Text, number, alphanumeric, and calculation CAPTCHA images support 18 concrete renderers plus a random mode:
|
||
|
||
`classic`, `collision`, `snow`, `corrosion`, `spiderweb`, `cross-shadow`, `split`, `split2`, `cut`, `darts`, `distortion`, `stitch`, `striped`, `wave`, `grid-noise`, `scribble`, `pixel`, and `broken-lines`.
|
||
|
||
Use a fixed style:
|
||
|
||
```wrn
|
||
<Captcha
|
||
type="alphanumeric"
|
||
action="signup"
|
||
imageStyle="spiderweb"
|
||
disturbance="55"
|
||
/>
|
||
```
|
||
|
||
Use a new random style whenever the challenge is refreshed:
|
||
|
||
```wrn
|
||
<Captcha
|
||
type="number"
|
||
action="login"
|
||
imageStyle="random"
|
||
difficulty="normal"
|
||
/>
|
||
```
|
||
|
||
Control the random pool with comma-separated component props or arrays in the TypeScript API:
|
||
|
||
```wrn
|
||
<Captcha
|
||
type="alphanumeric"
|
||
action="checkout"
|
||
imageStyle="random"
|
||
allowedStyles="classic,snow,distortion,wave"
|
||
excludedStyles="collision"
|
||
/>
|
||
```
|
||
|
||
```ts
|
||
const challenge = await engine.create({
|
||
action: "checkout",
|
||
type: "alphanumeric",
|
||
imageStyle: "random",
|
||
allowedStyles: ["classic", "snow", "distortion", "wave"],
|
||
excludedStyles: ["collision"],
|
||
});
|
||
```
|
||
|
||
Set `randomizeStyle: true` to force random selection even when `imageStyle` names a concrete renderer. The resolved style, requested style, and active pool are returned in challenge metadata. The answer is never embedded in metadata or browser JavaScript.
|
||
|
||
### Events
|
||
|
||
`@ready`, `@challenge`, `@input`, `@verify`, `@success`, `@failure`, `@expired`, `@refresh`, `@audioStart`, `@audioEnd`, and `@error`.
|
||
|
||
## Protect a validated form API
|
||
|
||
Validate a cloned request first, then consume the CAPTCHA response token. This prevents a valid token from being consumed when ordinary field validation fails.
|
||
|
||
```ts
|
||
import { captchaGuard } from "@wrnexus/captcha/server";
|
||
import { parseBody } from "@wrnexus/validation";
|
||
import contactSchema from "../schemas/contact.ts";
|
||
import { engine } from "../lib/captcha.ts";
|
||
|
||
const guard = captchaGuard({
|
||
action: "contact-submit",
|
||
engine,
|
||
bindHostname: true,
|
||
bindSession: true,
|
||
});
|
||
|
||
export async function POST(ctx) {
|
||
const validation = await parseBody(contactSchema, ctx.req.clone());
|
||
if (!validation.ok) return validation.response;
|
||
|
||
return guard(ctx, async () => Response.json({ ok: true, submission: validation.value }));
|
||
}
|
||
```
|
||
|
||
The CAPTCHA runtime binds its required-form check in the capture phase, so a `data-schema` validator cannot submit the form before CAPTCHA verification. After a successful form request, the component automatically creates a fresh challenge.
|
||
|
||
### Retryable operations such as login
|
||
|
||
A login may consume a valid CAPTCHA and then fail because the password is
|
||
incorrect. Configure a short action-bound session grant so the user can correct
|
||
their credentials without solving CAPTCHA again:
|
||
|
||
```ts
|
||
const guard = captchaGuard({
|
||
action: "auth-login",
|
||
engine,
|
||
bindHostname: true,
|
||
bindSession: true,
|
||
verifiedForMs: 5 * 60_000,
|
||
});
|
||
```
|
||
|
||
Keep the verified widget state for non-CAPTCHA form errors:
|
||
|
||
```wrn
|
||
<Captcha
|
||
action="auth-login"
|
||
required="true"
|
||
resetOnError="false"
|
||
/>
|
||
```
|
||
|
||
The grant is stored in the current session and bound to the configured action.
|
||
Expired grants and CAPTCHA-specific errors still require and load a fresh
|
||
challenge. Keep login rate limits and authentication lockout enabled;
|
||
`verifiedForMs` removes repeated human verification, not credential-abuse
|
||
controls.
|
||
|
||
## Validate a schema and CAPTCHA together
|
||
|
||
```ts
|
||
const result = await parseWithCaptcha(signupSchema, body, ctx, {
|
||
action: "signup",
|
||
engine,
|
||
});
|
||
|
||
if (!result.ok) return Response.json({ ok: false, errors: result.errors }, { status: 400 });
|
||
```
|
||
|
||
## Page gate
|
||
|
||
```ts
|
||
export default captchaPageGate({
|
||
action: "reports-access",
|
||
engine,
|
||
challengePath: "/captcha",
|
||
policy: {
|
||
mode: "session",
|
||
verifiedForMs: 15 * 60_000,
|
||
routeGroups: ["/reports"],
|
||
},
|
||
});
|
||
```
|
||
|
||
Use `mode: "always"` for every visit, `mode: "session"` for a temporary grant, or `mode: "adaptive"` with `signals(ctx)`.
|
||
|
||
The challenge page should post the return path as a normal hidden field instead of constructing JavaScript inside the HTML `action` attribute:
|
||
|
||
```wrn
|
||
<form method="post" action="/api/page-grant">
|
||
<input type="hidden" name="returnTo" value='{returnTo}' />
|
||
<Captcha action="reports-access" />
|
||
<button type="submit">Continue</button>
|
||
</form>
|
||
```
|
||
|
||
The `/api/page-grant` route reads `returnTo`, restricts it to the current origin, and redirects only after `captchaPageGate()` has verified and stored the temporary session grant.
|
||
|
||
## External providers
|
||
|
||
```ts
|
||
const turnstile = turnstileProvider({
|
||
secretKey: process.env.TURNSTILE_SECRET!,
|
||
siteKey: process.env.PUBLIC_TURNSTILE_SITE_KEY!,
|
||
expectedHostnames: ["example.com"],
|
||
expectedAction: "signup",
|
||
});
|
||
```
|
||
|
||
```wrn
|
||
<Captcha
|
||
provider="turnstile"
|
||
siteKey="PUBLIC_SITE_KEY"
|
||
action="signup"
|
||
/>
|
||
```
|
||
|
||
Use the matching provider in `captchaGuard({ provider: turnstile })`. reCAPTCHA and hCaptcha adapters follow the same pattern.
|
||
|
||
## Managed provider
|
||
|
||
```ts
|
||
const managed = managedCaptchaProvider({
|
||
baseUrl: "https://captcha.example.com",
|
||
siteKey: process.env.PUBLIC_CAPTCHA_SITE_KEY!,
|
||
secretKey: process.env.CAPTCHA_SECRET_KEY!,
|
||
});
|
||
```
|
||
|
||
For direct browser challenge creation, configure the component’s `endpoint` as the managed `/v1/challenges` URL and its `verifyEndpoint` as `/v1/solve`. Keep the secret key only in the server provider.
|
||
|
||
## Stores
|
||
|
||
- `MemoryCaptchaStore`: development and one-process applications
|
||
- `SqliteCaptchaStore`: adapter for SQLite-like `prepare().run/get/all()` clients
|
||
- `RedisCaptchaStore`: shared TTL storage with Lua-backed atomic consumption when `eval` is available
|
||
- `CaptchaStore`: implement this interface for PostgreSQL, MySQL, MongoDB, or another backend
|
||
|
||
## Audio
|
||
|
||
`AssetAudioRenderer` concatenates bundled English PCM WAV clips without calling an external service. Supply a custom `CaptchaAudioRenderer` for recorded voices, Hindi or other languages, or managed text-to-speech.
|
||
|
||
## DevToolbar
|
||
|
||
The automatically discovered CAPTCHA plugin registers its DevToolbar audit panel. It checks for likely client-side secrets, missing action bindings, missing provider site keys, optional CAPTCHA fields, accessible alternatives, and server-verification reminders. Explicit `captchaPlugin(options)` registration is needed only to override automatic configuration.
|
||
|
||
## Testing
|
||
|
||
Use deterministic custom generators in unit tests. Never require users or CI to solve random CAPTCHA images. The package includes engine, provider, policy, HTTP, storage, replay, expiry, binding, and audio authorization tests.
|
||
|
||
## Custom challenge generator
|
||
|
||
```ts
|
||
import { defineCaptchaGenerator, createCaptchaEngine } from "@wrnexus/captcha";
|
||
|
||
const wordChallenge = defineCaptchaGenerator({
|
||
type: "word" as const,
|
||
generate(context) {
|
||
const answer = "NEXUS";
|
||
return {
|
||
type: "word",
|
||
presentation: "visual",
|
||
prompt: "Enter the displayed word",
|
||
answer,
|
||
answerKind: "text",
|
||
image: renderYourImage(answer),
|
||
inputMode: "text",
|
||
};
|
||
},
|
||
});
|
||
|
||
const engine = createCaptchaEngine({ secret, generators: [wordChallenge] });
|
||
```
|
||
|
||
Applications may also implement `CaptchaStore`, `CaptchaAudioRenderer`, or use `defineCaptchaProvider()` for a completely custom service.
|
||
|
||
## Helper and block kit
|
||
|
||
The package exports `captchaTokenFrom`, `captchaHeaders`, `captchaFields`, `verifyCaptcha`, `verifyCaptchaOrThrow`, `captchaResultResponse`, and `captchaContext` for consistent server and client integration.
|
||
|
||
Enable the CAPTCHA plugin to use the low-level `<Captcha />` challenge plus complete UI-composed blocks:
|
||
|
||
- `<CaptchaField />`
|
||
- `<CaptchaStatus />`
|
||
|
||
`CaptchaField` composes `Card` from `@wrnexus/ui` and keeps the CAPTCHA-specific size separate from the surrounding UI size.
|