API reference

captcha.turnstile(options) creates a Cloudflare Turnstile guard. captcha.recaptcha(options) creates a Google reCAPTCHA guard from an existing Google widget.

Import

import { captcha } from "@layeron/modules"

`captcha.turnstile`

Create a Cloudflare Turnstile Captcha guard.

TypeSpec operation: turnstile.

captcha.turnstile(options: CaptchaTurnstileOptions): CaptchaModule

CaptchaTokenSource

One request location that may contain a CAPTCHA token.

Field	Type	Description
`kind`	`CaptchaTokenSourceKind`	Request location kind.
`name`	`string`	Header, form field, or JSON property name.

CaptchaFailureOptions

Failure response returned by automatic guards and manual result.response().

Field	Type	Description
`status`	`int32 \| undefined`	HTTP error status returned when verification fails.
`body`	`unknown \| undefined`	JSON body returned when verification fails.

CaptchaTokenSourceOptions

Custom request locations used to read CAPTCHA tokens.

Field	Type	Description
`header`	`string \| undefined`	Header name that carries the token.
`form`	`string \| undefined`	Form field name that carries the token.
`json`	`string \| undefined`	JSON property name that carries the token.

SecretRef

Reference to a Layeron secret.

Field	Type	Description
`kind`	`”secret_ref”`	Secret reference discriminator.
`name`	`string`	Layeron secret name.

CaptchaTurnstileOptions

Options accepted by captcha.turnstile().

Field	Type	Description
`name`	`string`	Stable Captcha instance name.
`namespace`	`string \| undefined`	Platform namespace for the instance. Defaults to `default`.
`mode`	`TurnstileMode \| undefined`	Cloudflare Turnstile widget mode. Defaults to `managed`.
`domains`	`string[] \| undefined`	Allowed hostnames returned by the provider Siteverify response.
`action`	`string \| undefined`	Expected provider action value for this flow.
`cData`	`string \| undefined`	Expected Cloudflare Turnstile cData value for this flow.
`sitekey`	`string \| undefined`	Existing Turnstile sitekey to adopt. Omit it to let Layeron create and maintain the widget.
`secret`	`SecretRef \| undefined`	Layeron secret reference for an adopted Turnstile widget secret.
`tokenFrom`	`CaptchaTokenSourceOptions \| undefined`	Custom request locations used to read the token.
`failure`	`CaptchaFailureOptions \| undefined`	Failure response used by automatic guards and manual result.response().
`dev`	`CaptchaDevOptions \| undefined`	Local development options.

CaptchaDevOptions

Local development Captcha behavior.

Field	Type	Description
`mode`	`”bypass” \| undefined`	Bypass provider verification in local or test environments.

CaptchaRecaptchaOptions

Options accepted by captcha.recaptcha().

Field	Type	Description
`name`	`string`	Stable Captcha instance name.
`namespace`	`string \| undefined`	Platform namespace for the instance. Defaults to `default`.
`sitekey`	`string`	Google reCAPTCHA public sitekey.
`secret`	`SecretRef`	Layeron secret reference for the Google reCAPTCHA secret.
`domains`	`string[] \| undefined`	Allowed hostnames returned by the provider Siteverify response.
`action`	`string \| undefined`	Expected provider action value for this flow.
`minScore`	`float64 \| undefined`	Minimum accepted Google reCAPTCHA score from 0 to 1.
`tokenFrom`	`CaptchaTokenSourceOptions \| undefined`	Custom request locations used to read the token.
`failure`	`CaptchaFailureOptions \| undefined`	Failure response used by automatic guards and manual result.response().
`dev`	`CaptchaDevOptions \| undefined`	Local development options.

CaptchaTurnstileConfig

Normalized configuration for a Cloudflare Turnstile Captcha instance.

Field	Type	Description
`kind`	`”captcha”`	Module config kind.
`provider`	`CaptchaProvider`	Provider used by this Captcha instance.
`name`	`string`	Stable Captcha instance name.
`namespace`	`string`	Platform namespace for the instance. Defaults to `default`.
`mode`	`TurnstileMode`	Cloudflare Turnstile widget mode.
`domains`	`string[] \| undefined`	Allowed hostnames returned by the provider Siteverify response.
`action`	`string \| undefined`	Expected provider action value for this flow.
`cData`	`string \| undefined`	Expected Cloudflare Turnstile cData value for this flow.
`sitekey`	`string \| undefined`	Existing or generated public sitekey.
`secretRef`	`SecretRef \| undefined`	Layeron secret reference for an adopted Turnstile widget secret.
`tokenSources`	`CaptchaTokenSource[]`	Request locations used to read the token.
`failure`	`CaptchaFailureOptions`	Failure response used by automatic guards and manual result.response().
`dev`	`CaptchaDevOptions \| undefined`	Local development options.

CaptchaRecaptchaConfig

Normalized configuration for a Google reCAPTCHA Captcha instance.

Field	Type	Description
`kind`	`”captcha”`	Module config kind.
`provider`	`CaptchaProvider`	Provider used by this Captcha instance.
`name`	`string`	Stable Captcha instance name.
`namespace`	`string`	Platform namespace for the instance. Defaults to `default`.
`domains`	`string[] \| undefined`	Allowed hostnames returned by the provider Siteverify response.
`action`	`string \| undefined`	Expected provider action value for this flow.
`minScore`	`float64 \| undefined`	Minimum accepted Google reCAPTCHA score from 0 to 1.
`sitekey`	`string`	Google reCAPTCHA public sitekey.
`secretRef`	`SecretRef`	Layeron secret reference for the Google reCAPTCHA secret.
`tokenSources`	`CaptchaTokenSource[]`	Request locations used to read the token.
`failure`	`CaptchaFailureOptions`	Failure response used by automatic guards and manual result.response().
`dev`	`CaptchaDevOptions \| undefined`	Local development options.

CaptchaModule

Layeron Captcha module returned by captcha.turnstile() or captcha.recaptcha().

Field	Type	Description
`name`	`”captcha”`	Module name.
`config`	`CaptchaTurnstileConfig \| CaptchaRecaptchaConfig`	Normalized module configuration.

CaptchaVerifyInput

Manual Captcha verification input.

Field	Type	Description
`token`	`string \| undefined`	Provider token. verify(request) can extract the token from configured token sources.
`remoteIp`	`string \| undefined`	Remote user IP sent to the provider Siteverify endpoint.
`idempotencyKey`	`string \| undefined`	Idempotency key forwarded to providers that support it.
`hostname`	`string \| undefined`	Expected hostname for this verification call.
`action`	`string \| undefined`	Expected provider action for this verification call.
`cData`	`string \| undefined`	Expected Cloudflare Turnstile cData for this verification call.
`minScore`	`float64 \| undefined`	Minimum accepted Google reCAPTCHA score from 0 to 1 for this verification call.

CaptchaVerifyTokenInput

Manual Captcha verification input used after the token is passed separately.

Field	Type	Description
`remoteIp`	`string \| undefined`	Remote user IP sent to the provider Siteverify endpoint.
`idempotencyKey`	`string \| undefined`	Idempotency key forwarded to providers that support it.
`hostname`	`string \| undefined`	Expected hostname for this verification call.
`action`	`string \| undefined`	Expected provider action for this verification call.
`cData`	`string \| undefined`	Expected Cloudflare Turnstile cData for this verification call.
`minScore`	`float64 \| undefined`	Minimum accepted Google reCAPTCHA score from 0 to 1 for this verification call.

CaptchaVerifyResult

Result returned by manual Captcha verification.

Field	Type	Description
`ok`	`boolean`	True when provider verification and Layeron validation pass.
`success`	`boolean`	Provider-compatible success flag.
`errorCodes`	`string[]`	Provider errors and Layeron validation error codes.
`hostname`	`string \| undefined`	Hostname returned by the provider Siteverify response.
`action`	`string \| undefined`	Action returned by the provider Siteverify response.
`cData`	`string \| undefined`	Cloudflare Turnstile cData returned by the provider Siteverify response.
`score`	`float64 \| undefined`	Google reCAPTCHA score returned by the provider Siteverify response.
`challengeTs`	`string \| undefined`	Challenge timestamp returned by the provider Siteverify response.

CaptchaTokenSourceKind

Request location used to read a CAPTCHA token.

Value	Description
`header`	Read the token from an HTTP request header.
`form`	Read the token from a submitted form field.
`json`	Read the token from a JSON request body field.

TurnstileMode

Cloudflare Turnstile widget interaction mode.

Value	Description
`managed`	Cloudflare managed challenge mode.
`invisible`	Invisible challenge mode.
`non-interactive`	Non-interactive challenge mode.

CaptchaProvider

CAPTCHA provider verified by the Captcha module.

Value	Description
`cloudflare_turnstile`	Cloudflare Turnstile verification.
`google_recaptcha`	Google reCAPTCHA verification.

Operations

`captcha.recaptcha`

Create a Google reCAPTCHA guard from an existing Google widget.

TypeSpec operation: recaptcha.

captcha.recaptcha(options: CaptchaRecaptchaOptions): CaptchaModule

`captcha.verify`

Verify a Captcha request or token with manual control flow.

TypeSpec operation: verify.

captcha.verify(input: CaptchaVerifyInput): CaptchaVerifyResult

`captcha.verifyToken`

Verify an explicit Captcha token with manual control flow.

TypeSpec operation: verifyToken.

captcha.verifyToken(token: string, input?: CaptchaVerifyTokenInput): CaptchaVerifyResult

TypeScript result contracts

These TypeScript result contracts are part of the public module API.

Result
`TurnstileSiteverifyResponse`
`RecaptchaSiteverifyResponse`