alepha/dist/captcha/index.d.ts

Easy-to-use modern TypeScript framework for building many kind of applications.

//#region ../../src/captcha/providers/CaptchaProvider.d.ts
/**
 * Captcha verification provider interface.
 *
 * Verifies that a user-submitted captcha token is valid. Implementations
 * call the relevant captcha service (Turnstile, reCAPTCHA, hCaptcha, etc.)
 * to validate the token server-side.
 */
declare abstract class CaptchaProvider {
  /**
   * Verify a captcha token.
   *
   * @param token - The captcha response token submitted by the client.
   * @param ip - Optional client IP address for additional validation.
   * @returns Whether the token is valid.
   */
  abstract verify(token: string, ip?: string): Promise<boolean>;
  /**
   * Public site/widget key to hand to the browser, when applicable.
   *
   * Returns `undefined` for providers that don't need a client key
   * (e.g. in-memory/test providers).
   */
  getSiteKey(): string | undefined;
}
//#endregion
//#region ../../src/captcha/providers/MemoryCaptchaProvider.d.ts
interface CaptchaRecord {
  token: string;
  ip?: string;
  verifiedAt: Date;
}
/**
 * In-memory captcha provider for testing.
 *
 * Accepts all tokens by default. Use `reject()` to make verification fail,
 * and `accept()` to restore. All verification attempts are recorded for assertions.
 */
declare class MemoryCaptchaProvider implements CaptchaProvider {
  protected readonly log: import("alepha/logger").Logger;
  /**
   * All verification attempts.
   */
  records: CaptchaRecord[];
  protected shouldAccept: boolean;
  getSiteKey(): string | undefined;
  verify(token: string, ip?: string): Promise<boolean>;
  /**
   * Make all subsequent verifications fail.
   */
  reject(): void;
  /**
   * Make all subsequent verifications pass (default behavior).
   */
  accept(): void;
  /**
   * Whether a token was verified.
   */
  wasVerified(token: string): boolean;
  /**
   * Get the last verification attempt.
   */
  get last(): CaptchaRecord | undefined;
}
//#endregion
//#region ../../src/captcha/providers/TurnstileCaptchaProvider.d.ts
/**
 * Cloudflare Turnstile captcha verification provider.
 *
 * Validates captcha tokens against the Cloudflare Turnstile siteverify API.
 * Free, privacy-friendly, and supports invisible mode.
 *
 * ## Setup
 *
 * 1. Create a Turnstile widget at https://dash.cloudflare.com/?to=/:account/turnstile
 * 2. Copy the **Site Key** (public, for the client) and **Secret Key** (private, for the server)
 * 3. Set `TURNSTILE_SECRET_KEY` in your environment
 *
 * ## Client-side integration
 *
 * Add the Turnstile script and widget to your form:
 *
 * ```html
 * <script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
 * <form>
 *   <div class="cf-turnstile" data-sitekey="YOUR_SITE_KEY"></div>
 *   <button type="submit">Submit</button>
 * </form>
 * ```
 *
 * The widget injects a hidden `cf-turnstile-response` input into the form.
 * Send this value as the `captchaToken` in your registration request.
 *
 * For explicit rendering (React, SPA):
 *
 * ```ts
 * turnstile.render("#container", {
 *   sitekey: "YOUR_SITE_KEY",
 *   callback: (token) => setCaptchaToken(token),
 * });
 * ```
 *
 * ## Server-side usage
 *
 * Register the provider in your app:
 *
 * ```ts
 * import { CaptchaProvider } from "alepha/captcha";
 * import { TurnstileCaptchaProvider } from "alepha/captcha";
 *
 * alepha.with({ provide: CaptchaProvider, use: TurnstileCaptchaProvider });
 * ```
 *
 * ## Test keys (for development)
 *
 * - Always passes: site `1x00000000000000000000AA`, secret `1x0000000000000000000000000000000AA`
 * - Always blocks: site `2x00000000000000000000AB`, secret `2x0000000000000000000000000000000AB`
 * - Forces interactive: site `3x00000000000000000000FF`
 *
 * ## Environment Variables
 *
 * - `TURNSTILE_SECRET_KEY`: The secret key from the Cloudflare Turnstile dashboard.
 *
 * @see https://developers.cloudflare.com/turnstile/get-started/server-side-validation/
 */
declare class TurnstileCaptchaProvider implements CaptchaProvider {
  protected readonly log: import("alepha/logger").Logger;
  protected readonly secretKey: string;
  protected readonly siteKey: string;
  constructor();
  getSiteKey(): string;
  verify(token: string, ip?: string): Promise<boolean>;
}
//#endregion
//#region ../../src/captcha/index.d.ts
/**
 * Captcha verification for bot protection.
 *
 * **Features:**
 * - Provider abstraction for captcha services
 * - Cloudflare Turnstile support (free, privacy-friendly)
 * - In-memory provider for testing
 *
 * @module alepha.captcha
 */
declare const AlephaCaptcha: import("alepha").Service<import("alepha").Module>;
//#endregion
export { AlephaCaptcha, CaptchaProvider, CaptchaRecord, MemoryCaptchaProvider, TurnstileCaptchaProvider };
//# sourceMappingURL=index.d.ts.map