@udibo/oauth2 0.1.0

package/esm/errors.d.ts

@@ -0,0 +1,203 @@
+/**
+ * OAuth2 error classes following RFC 6749.
+ *
+ * These error classes map to the OAuth2 error codes defined in:
+ * - RFC 6749 Section 4.1.2.1 (Authorization errors)
+ * - RFC 6749 Section 5.2 (Token errors)
+ * - RFC 6750 Section 3.1 (Bearer token errors)
+ * - RFC 8628 Section 3.5 (Device flow errors)
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-5.2
+ * @see https://datatracker.ietf.org/doc/html/rfc6750#section-3.1
+ * @module
+ */
+import { HttpError, type HttpErrorOptions } from "./deps/jsr.io/@udibo/http-error/0.11.1/mod.js";
+/**
+ * Problem Details extension members carried by every {@linkcode OAuth2Error}.
+ *
+ * These map the standard OAuth2 error response fields (RFC 6749 Section 5.2)
+ * onto the error's `extensions` bag so they can be serialized in either the
+ * OAuth2 error format or the RFC 9457 Problem Details format.
+ */
+export interface OAuth2ProblemDetailsExtensions {
+    /** An ASCII error code. */
+    error?: string;
+    /** Human-readable error description. */
+    error_description?: string;
+    /** A URI identifying a human readable web page with information about the error. */
+    error_uri?: string;
+}
+/**
+ * Constructor type for OAuth2 error classes produced by
+ * `createHttpErrorClass`. Declared explicitly so the exported error classes
+ * have a JSR-fast public type (the inferred type spans multiple constructor
+ * overloads and trips the `no-slow-types` rule).
+ */
+export type OAuth2ErrorClass<Extensions extends OAuth2ProblemDetailsExtensions = OAuth2ProblemDetailsExtensions> = {
+    new <E extends Extensions = Extensions>(status?: number, message?: string, options?: HttpErrorOptions<E>): HttpError<E>;
+    new <E extends Extensions = Extensions>(status?: number, options?: HttpErrorOptions<E>): HttpError<E>;
+    new <E extends Extensions = Extensions>(message?: string, options?: HttpErrorOptions<E>): HttpError<E>;
+    new <E extends Extensions = Extensions>(options?: HttpErrorOptions<E>): HttpError<E>;
+    prototype: HttpError<Extensions>;
+};
+/**
+ * An OAuth2 error: an {@linkcode HttpError} whose `extensions` carry the
+ * OAuth2 error fields described by {@linkcode OAuth2ProblemDetailsExtensions}.
+ * This is the common type for every error class in this module.
+ */
+export type OAuth2Error = HttpError<OAuth2ProblemDetailsExtensions>;
+/**
+ * The base OAuth2 error class, an {@linkcode HttpError} subclass that defaults
+ * to the `server_error` code. Used as a catch-all and as the value-side
+ * companion of the {@linkcode OAuth2Error} type; prefer a specific subclass
+ * (e.g. {@linkcode InvalidRequestError}) when the condition is known.
+ */
+export declare const OAuth2Error: OAuth2ErrorClass;
+/** Type guard for OAuth2 errors. */
+export declare function isOAuth2Error(value: unknown): value is OAuth2Error;
+/**
+ * Converts an arbitrary error into an {@link OAuth2Error}.
+ *
+ * If the input is already an OAuth2Error it is returned as-is; otherwise it is
+ * wrapped in a {@link ServerError} with the original error attached as `cause`.
+ *
+ * The returned error also has its `type` and `extensions.error_uri` synced so
+ * that if one is set the other is too. This lets both the standard OAuth2
+ * error format (which emits `error_uri`) and the RFC 9457 Problem Details
+ * format (which emits `type`) carry the same URI without the handler having to
+ * set both fields.
+ */
+export declare function toOAuth2Error(error: unknown): OAuth2Error;
+/**
+ * The request is missing a required parameter, includes an unsupported parameter value,
+ * repeats a parameter, includes multiple credentials, utilizes more than one mechanism
+ * for authenticating the client, or is otherwise malformed.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-5.2
+ */
+export declare const InvalidRequestError: OAuth2ErrorClass;
+/**
+ * Client authentication failed.
+ *
+ * The authorization server MAY return an HTTP 401 (Unauthorized) status code
+ * to indicate which HTTP authentication schemes are supported.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-5.2
+ */
+export declare const InvalidClientError: OAuth2ErrorClass;
+/**
+ * The provided authorization grant or refresh token is invalid, expired, revoked,
+ * does not match the redirection URI used in the authorization request, or was issued to another client.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-5.2
+ */
+export declare const InvalidGrantError: OAuth2ErrorClass;
+/**
+ * The authenticated client is not authorized to use this authorization grant type.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-5.2
+ */
+export declare const UnauthorizedClientError: OAuth2ErrorClass;
+/**
+ * The token type is not supported by the authorization server.
+ *
+ * Used by the revocation endpoint (RFC 7009) when the server doesn't
+ * support revoking the presented token type.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc7009#section-2.2.1
+ */
+export declare const UnsupportedTokenTypeError: OAuth2ErrorClass;
+/**
+ * The authorization grant type is not supported by the authorization server.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-5.2
+ */
+export declare const UnsupportedGrantTypeError: OAuth2ErrorClass;
+/**
+ * The resource owner or authorization server denied the request.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1
+ */
+export declare const AccessDeniedError: OAuth2ErrorClass;
+/**
+ * The access token provided is expired, revoked, malformed, or invalid.
+ *
+ * Per RFC 6750, this error uses HTTP 401 status and should trigger
+ * a WWW-Authenticate header with the "invalid_token" error code.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6750#section-3.1
+ */
+export declare const InvalidTokenError: OAuth2ErrorClass;
+/**
+ * The request requires higher privileges than provided by the access token.
+ *
+ * Per RFC 6750, this error uses HTTP 403 status and should trigger
+ * a WWW-Authenticate header with the "insufficient_scope" error code
+ * and optionally a "requiredScope" extension indicating required scope.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6750#section-3.1
+ */
+export declare const InsufficientScopeError: OAuth2ErrorClass<OAuth2ProblemDetailsExtensions & {
+    requiredScope?: string;
+}>;
+/**
+ * The request requires an authorization the subject does not hold — a
+ * permission, role, or organization context check failed on an otherwise
+ * valid token. HTTP 403 with a bare `realm` challenge: RFC 6750 registers no
+ * challenge code for this, so unlike {@link InsufficientScopeError} the
+ * `WWW-Authenticate` header names no error — the body carries
+ * `insufficient_permissions`.
+ */
+export declare const InsufficientPermissionsError: OAuth2ErrorClass;
+/**
+ * The authorization server does not support obtaining an authorization code using this method.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1
+ */
+export declare const UnsupportedResponseTypeError: OAuth2ErrorClass;
+/**
+ * The requested scope is invalid, unknown, or malformed.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-5.2
+ */
+export declare const InvalidScopeError: OAuth2ErrorClass;
+/**
+ * The authorization server encountered an unexpected condition that prevented it from fulfilling the request.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1
+ */
+export declare const ServerError: OAuth2ErrorClass;
+/**
+ * The authorization server is currently unable to handle the request due to a temporary overloading or maintenance.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1
+ */
+export declare const TemporarilyUnavailableError: OAuth2ErrorClass;
+/**
+ * The authorization request is still pending user approval.
+ *
+ * Used in the device authorization flow (RFC 8628) when the user
+ * has not yet authorized the request.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc8628#section-3.5
+ */
+export declare const AuthorizationPendingError: OAuth2ErrorClass;
+/**
+ * The client is polling too frequently.
+ *
+ * Used in the device authorization flow (RFC 8628) when the client
+ * polls faster than the allowed interval. The client should increase
+ * its polling interval by 5 seconds.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc8628#section-3.5
+ */
+export declare const SlowDownError: OAuth2ErrorClass;
+/**
+ * The device_code has expired.
+ *
+ * Used in the device authorization flow (RFC 8628) when the
+ * device code expires before the user authorizes the request.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc8628#section-3.5
+ */
+export declare const ExpiredTokenError: OAuth2ErrorClass;

package/esm/errors.js

@@ -0,0 +1,287 @@
+/**
+ * OAuth2 error classes following RFC 6749.
+ *
+ * These error classes map to the OAuth2 error codes defined in:
+ * - RFC 6749 Section 4.1.2.1 (Authorization errors)
+ * - RFC 6749 Section 5.2 (Token errors)
+ * - RFC 6750 Section 3.1 (Bearer token errors)
+ * - RFC 8628 Section 3.5 (Device flow errors)
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-5.2
+ * @see https://datatracker.ietf.org/doc/html/rfc6750#section-3.1
+ * @module
+ */
+import { createHttpErrorClass, HttpError, } from "./deps/jsr.io/@udibo/http-error/0.11.1/mod.js";
+/**
+ * The base OAuth2 error class, an {@linkcode HttpError} subclass that defaults
+ * to the `server_error` code. Used as a catch-all and as the value-side
+ * companion of the {@linkcode OAuth2Error} type; prefer a specific subclass
+ * (e.g. {@linkcode InvalidRequestError}) when the condition is known.
+ */
+export const OAuth2Error = createHttpErrorClass({
+    name: "OAuth2 Error",
+    extensions: {
+        error: "server_error",
+    },
+});
+/** Type guard for OAuth2 errors. */
+export function isOAuth2Error(value) {
+    return value instanceof HttpError && value.extensions.error !== undefined;
+}
+/**
+ * Converts an arbitrary error into an {@link OAuth2Error}.
+ *
+ * If the input is already an OAuth2Error it is returned as-is; otherwise it is
+ * wrapped in a {@link ServerError} with the original error attached as `cause`.
+ *
+ * The returned error also has its `type` and `extensions.error_uri` synced so
+ * that if one is set the other is too. This lets both the standard OAuth2
+ * error format (which emits `error_uri`) and the RFC 9457 Problem Details
+ * format (which emits `type`) carry the same URI without the handler having to
+ * set both fields.
+ */
+export function toOAuth2Error(error) {
+    const oauth2Error = isOAuth2Error(error)
+        ? error
+        : new ServerError("unexpected error", { cause: error });
+    if (oauth2Error.type && !oauth2Error.extensions.error_uri) {
+        oauth2Error.extensions.error_uri = oauth2Error.type;
+    }
+    else if (oauth2Error.extensions.error_uri && !oauth2Error.type) {
+        oauth2Error.type = oauth2Error.extensions.error_uri;
+    }
+    return oauth2Error;
+}
+/**
+ * The request is missing a required parameter, includes an unsupported parameter value,
+ * repeats a parameter, includes multiple credentials, utilizes more than one mechanism
+ * for authenticating the client, or is otherwise malformed.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-5.2
+ */
+export const InvalidRequestError = createHttpErrorClass({
+    name: "Invalid Request",
+    status: 400,
+    extensions: {
+        error: "invalid_request",
+    },
+});
+/**
+ * Client authentication failed.
+ *
+ * The authorization server MAY return an HTTP 401 (Unauthorized) status code
+ * to indicate which HTTP authentication schemes are supported.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-5.2
+ */
+export const InvalidClientError = createHttpErrorClass({
+    name: "Invalid Client",
+    status: 401,
+    extensions: {
+        error: "invalid_client",
+    },
+});
+/**
+ * The provided authorization grant or refresh token is invalid, expired, revoked,
+ * does not match the redirection URI used in the authorization request, or was issued to another client.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-5.2
+ */
+export const InvalidGrantError = createHttpErrorClass({
+    name: "Invalid Grant",
+    status: 400,
+    extensions: {
+        error: "invalid_grant",
+    },
+});
+/**
+ * The authenticated client is not authorized to use this authorization grant type.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-5.2
+ */
+export const UnauthorizedClientError = createHttpErrorClass({
+    name: "Unauthorized Client",
+    status: 401,
+    extensions: {
+        error: "unauthorized_client",
+    },
+});
+/**
+ * The token type is not supported by the authorization server.
+ *
+ * Used by the revocation endpoint (RFC 7009) when the server doesn't
+ * support revoking the presented token type.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc7009#section-2.2.1
+ */
+export const UnsupportedTokenTypeError = createHttpErrorClass({
+    name: "Unsupported Token Type",
+    status: 400,
+    extensions: {
+        error: "unsupported_token_type",
+    },
+});
+/**
+ * The authorization grant type is not supported by the authorization server.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-5.2
+ */
+export const UnsupportedGrantTypeError = createHttpErrorClass({
+    name: "Unsupported Grant Type",
+    status: 400,
+    extensions: {
+        error: "unsupported_grant_type",
+    },
+});
+/**
+ * The resource owner or authorization server denied the request.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1
+ */
+export const AccessDeniedError = createHttpErrorClass({
+    name: "Access Denied",
+    status: 401,
+    extensions: {
+        error: "access_denied",
+    },
+});
+/**
+ * The access token provided is expired, revoked, malformed, or invalid.
+ *
+ * Per RFC 6750, this error uses HTTP 401 status and should trigger
+ * a WWW-Authenticate header with the "invalid_token" error code.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6750#section-3.1
+ */
+export const InvalidTokenError = createHttpErrorClass({
+    name: "Invalid Token",
+    status: 401,
+    extensions: {
+        error: "invalid_token",
+    },
+});
+/**
+ * The request requires higher privileges than provided by the access token.
+ *
+ * Per RFC 6750, this error uses HTTP 403 status and should trigger
+ * a WWW-Authenticate header with the "insufficient_scope" error code
+ * and optionally a "requiredScope" extension indicating required scope.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6750#section-3.1
+ */
+export const InsufficientScopeError = createHttpErrorClass({
+    name: "Insufficient Scope",
+    status: 403,
+    extensions: {
+        error: "insufficient_scope",
+    },
+});
+/**
+ * The request requires an authorization the subject does not hold — a
+ * permission, role, or organization context check failed on an otherwise
+ * valid token. HTTP 403 with a bare `realm` challenge: RFC 6750 registers no
+ * challenge code for this, so unlike {@link InsufficientScopeError} the
+ * `WWW-Authenticate` header names no error — the body carries
+ * `insufficient_permissions`.
+ */
+export const InsufficientPermissionsError = createHttpErrorClass({
+    name: "Insufficient Permissions",
+    status: 403,
+    extensions: {
+        error: "insufficient_permissions",
+    },
+});
+/**
+ * The authorization server does not support obtaining an authorization code using this method.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1
+ */
+export const UnsupportedResponseTypeError = createHttpErrorClass({
+    name: "Unsupported Response Type",
+    status: 400,
+    extensions: {
+        error: "unsupported_response_type",
+    },
+});
+/**
+ * The requested scope is invalid, unknown, or malformed.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-5.2
+ */
+export const InvalidScopeError = createHttpErrorClass({
+    name: "Invalid Scope",
+    status: 400,
+    extensions: {
+        error: "invalid_scope",
+    },
+});
+/**
+ * The authorization server encountered an unexpected condition that prevented it from fulfilling the request.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1
+ */
+export const ServerError = createHttpErrorClass({
+    name: "Server Error",
+    status: 500,
+    extensions: {
+        error: "server_error",
+    },
+});
+/**
+ * The authorization server is currently unable to handle the request due to a temporary overloading or maintenance.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1
+ */
+export const TemporarilyUnavailableError = createHttpErrorClass({
+    name: "Temporarily Unavailable",
+    status: 503,
+    extensions: {
+        error: "temporarily_unavailable",
+    },
+});
+/**
+ * The authorization request is still pending user approval.
+ *
+ * Used in the device authorization flow (RFC 8628) when the user
+ * has not yet authorized the request.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc8628#section-3.5
+ */
+export const AuthorizationPendingError = createHttpErrorClass({
+    name: "Authorization Pending",
+    status: 400,
+    extensions: {
+        error: "authorization_pending",
+    },
+});
+/**
+ * The client is polling too frequently.
+ *
+ * Used in the device authorization flow (RFC 8628) when the client
+ * polls faster than the allowed interval. The client should increase
+ * its polling interval by 5 seconds.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc8628#section-3.5
+ */
+export const SlowDownError = createHttpErrorClass({
+    name: "Slow Down",
+    status: 400,
+    extensions: {
+        error: "slow_down",
+    },
+});
+/**
+ * The device_code has expired.
+ *
+ * Used in the device authorization flow (RFC 8628) when the
+ * device code expires before the user authorizes the request.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc8628#section-3.5
+ */
+export const ExpiredTokenError = createHttpErrorClass({
+    name: "Expired Token",
+    status: 400,
+    extensions: {
+        error: "expired_token",
+    },
+});

package/esm/identity/captcha.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Bring-your-own bot-challenge verification for auth endpoints — the CAPTCHA
+ * analogue of the {@link RateLimiterLike} seam. {@link CaptchaProvider} is the
+ * contract a client-issued challenge token is verified against server-side;
+ * Cloudflare Turnstile, hCaptcha, and reCAPTCHA all satisfy it, so nothing here
+ * depends on a vendor SDK. {@link verifyCaptcha} composes a provider with the
+ * fail-open/closed discipline a login flow needs: a missing or rejected token
+ * is a refusal, but a provider *outage* degrades to your existing rate-limit and
+ * lockout floor rather than locking everyone out.
+ *
+ * Tenant-agnostic: scope by passing whatever `action` and `ip` your provider
+ * scores on. **No provider means no challenge** — {@link verifyCaptcha} passes
+ * every request, so wiring the seam without configuring a provider changes
+ * nothing about existing behavior.
+ *
+ * @module
+ */
+/** What a {@link CaptchaProvider} is told about the request it is scoring. */
+export interface CaptchaVerifyContext {
+    /**
+     * The caller's IP, for providers that fold network reputation into the score
+     * (Turnstile's `remoteip`, reCAPTCHA's `remoteip`). Omit when unknown.
+     */
+    ip?: string;
+    /**
+     * The flow the token was issued for (`"signup"`, `"signin"`, …). Providers
+     * that bind a token to an action (reCAPTCHA v3, Turnstile `action`) verify it
+     * against this; providers that don't may ignore it.
+     */
+    action?: string;
+}
+/** The outcome of a {@link CaptchaProvider.verify}. */
+export interface CaptchaVerifyResult {
+    /**
+     * Whether the token is a valid, unspent solution to a real challenge. `false`
+     * is a genuine rejection (forged, replayed, or expired token) — the caller
+     * refuses the request. Reserve *throwing* for the provider being unreachable
+     * so {@link verifyCaptcha} can tell a rejection apart from an outage.
+     */
+    success: boolean;
+    /**
+     * The provider's confidence in `[0, 1]` when it scores (reCAPTCHA v3,
+     * Turnstile enterprise), higher meaning more likely human. Omit for
+     * pass/fail providers. Surfaced for score-threshold tuning; {@link
+     * verifyCaptcha} decides purely on `success`.
+     */
+    score?: number;
+}
+/**
+ * The seam a bot-challenge vendor plugs into: verify one client-issued token
+ * server-side and report pass/fail. The package ships **no** provider — bring
+ * your own: implement this against your provider's siteverify endpoint (a
+ * single HTTPS POST, as in the example below — Turnstile, hCaptcha, and
+ * reCAPTCHA all take that shape) or against an enterprise bot-detection service
+ * you already run. Wire the result through {@link verifyCaptcha} for the
+ * fail-open/closed handling, and reject a `"fail"` decision with
+ * `IdentityError` `captcha_failed`.
+ *
+ * @example
+ * ```ts
+ * const provider: CaptchaProvider = {
+ *   async verify(token, context) {
+ *     const body = new URLSearchParams({ secret, response: token });
+ *     if (context?.ip) body.set("remoteip", context.ip);
+ *     const res = await fetch(SITEVERIFY, { method: "POST", body });
+ *     if (!res.ok) throw new Error(`siteverify ${res.status}`); // outage
+ *     const data = await res.json() as { success: boolean };
+ *     return { success: data.success };
+ *   },
+ * };
+ * ```
+ */
+export interface CaptchaProvider {
+    /**
+     * Verify `token` server-side. Resolve `{ success: false }` for a genuine
+     * rejection; **throw** when the provider cannot be reached (network error,
+     * non-2xx) so an outage is distinguishable from a rejection.
+     */
+    verify(token: string, context?: CaptchaVerifyContext): Promise<CaptchaVerifyResult>;
+}
+/** The decision {@link verifyCaptcha} returns. */
+export interface CaptchaOutcome {
+    /** `"pass"` lets the flow proceed; `"fail"` is a refusal. */
+    decision: "pass" | "fail";
+    /**
+     * Whether a provider actually evaluated a token. `false` means no provider
+     * was configured (the request passes unchallenged) — distinct from a `"pass"`
+     * a provider granted.
+     */
+    challenged: boolean;
+    /** The provider's {@link CaptchaVerifyResult.score}, when it returned one. */
+    score?: number;
+    /**
+     * Whether the provider could not be reached, so this outcome came from the
+     * `failOpen` policy rather than a real evaluation — `true` on both the
+     * fail-open `"pass"` and the fail-closed `"fail"`. Audit it: a degraded pass
+     * is the window where only your rate-limit/lockout floor is protecting the
+     * endpoint, and a run of degraded fails is an outage locking users out.
+     */
+    degraded: boolean;
+}
+/** Options for {@link verifyCaptcha}. */
+export interface VerifyCaptchaOptions {
+    /**
+     * The provider to verify against. `undefined` disables the challenge
+     * entirely — {@link verifyCaptcha} returns an unchallenged `"pass"`.
+     */
+    provider: CaptchaProvider | undefined;
+    /**
+     * The client-issued token from the request. A missing/empty token with a
+     * provider configured is a `"fail"` (the challenge was required and not
+     * answered).
+     */
+    token: string | null | undefined;
+    /** Passed through to {@link CaptchaProvider.verify}. */
+    context?: CaptchaVerifyContext;
+    /**
+     * What to do when the provider throws (an outage). `true` (the default)
+     * fails open — the request passes with `degraded: true` — so a provider
+     * outage falls back to your rate-limit/lockout floor instead of blocking
+     * every user. `false` fails closed for a tenant that would rather refuse than
+     * degrade.
+     */
+    failOpen?: boolean;
+}
+/**
+ * Verify a client-issued CAPTCHA token with the fail-open/closed discipline an
+ * auth endpoint needs, and return a {@link CaptchaOutcome}.
+ *
+ * - **No provider** → unchallenged `"pass"` (`challenged: false`).
+ * - **Missing/empty token** → `"fail"` (the challenge went unanswered).
+ * - **Provider `{ success }`** → `"pass"`/`"fail"` accordingly.
+ * - **Provider throws (outage)** → `failOpen` decides `"pass"` or `"fail"`;
+ *   either way the outcome is `degraded: true`, because no token was really
+ *   evaluated.
+ *
+ * Never throws — a broken provider becomes a decision, not an exception the
+ * route must catch. Compose the result with your rate limiter and lockout; this
+ * does not replace them.
+ *
+ * @example
+ * ```ts
+ * const outcome = await verifyCaptcha({ provider, token, context: { ip, action: "signin" } });
+ * if (outcome.decision === "fail") return uniformRejection();
+ * ```
+ */
+export declare function verifyCaptcha(options: VerifyCaptchaOptions): Promise<CaptchaOutcome>;