recaptcha-utils/com.pambrose.common.recaptcha/RecaptchaService

RecaptchaService

Provides Google reCAPTCHA verification and HTML widget rendering for Ktor applications.

Includes server-side token verification via the Google reCAPTCHA API, a Ktor route-level validation extension, and kotlinx.html helpers for embedding the reCAPTCHA script and widget.

Holds a long-lived HttpClient; call close on application shutdown to release its resources.

Types

RecaptchaResponse

@Serializable

data class RecaptchaResponse(val success: Boolean, val errorCodes: List<String> = emptyList(), val hostname: String? = null, val challengeTs: String? = null)

Represents the JSON response from Google's reCAPTCHA verification endpoint.

Functions

open override fun close()

Releases the underlying HttpClient and its connection/thread pool.

loadRecaptchaScript

fun HEAD.loadRecaptchaScript(config: RecaptchaConfig)

Adds the Google reCAPTCHA JavaScript to the HTML HEAD if reCAPTCHA is enabled and both the site key and secret key are configured (kept in lockstep with server-side verification).

recaptchaWidget

fun FlowContent.recaptchaWidget(config: RecaptchaConfig)

Renders the reCAPTCHA widget <div> in the HTML body if reCAPTCHA is enabled and both the site key and secret key are configured (kept in lockstep with server-side verification).

validateRecaptcha

suspend fun RoutingContext.validateRecaptcha(config: RecaptchaConfig, params: Parameters): Boolean

Validates the reCAPTCHA response token from form parameters within a Ktor RoutingContext.