@rimelight/security 0.0.20 → 0.0.21

package/dist/config/index.d.mts

@@ -1,3 +1,3 @@
-import { i as SecurityOptions, n as RateLimitOptions, r as RateLimiterBinding, t as ConstructionOptions } from "../types-Dcvwj-af.mjs";
+import { i as SecurityOptions, n as RateLimitOptions, r as RateLimiterBinding, t as ConstructionOptions } from "../types-CL5HooHU.mjs";
 import { buildCspHeader } from "../csp.mjs";
 export { ConstructionOptions, RateLimitOptions, RateLimiterBinding, SecurityOptions, buildCspHeader };

package/dist/csp.d.mts

@@ -1,4 +1,4 @@
-import { i as SecurityOptions } from "./types-Dcvwj-af.mjs";
+import { i as SecurityOptions } from "./types-CL5HooHU.mjs";
 //#region src/csp.d.ts
 /**
  * Builds the Content-Security-Policy header string dynamically for a given request nonce.

package/dist/csp.mjs

@@ -4,27 +4,31 @@
 */
 function buildCspHeader(options = {}, nonce) {
 	const domain = options.domain || "";
+	const imgSources = Array.from(/* @__PURE__ */ new Set([
+		"'self'",
+		"data:",
+		...domain ? [`https://cdn.${domain}`] : [],
+		"https://i3.ytimg.com",
+		"https://www.youtube.com",
+		"https://www.youtube-nocookie.com",
+		...options.imgSrc || []
+	]));
+	const allowTurnstile = options.turnstile !== false;
 	const defaultDirectives = {
 		"default-src": ["'none'"],
-		"img-src": Array.from(/* @__PURE__ */ new Set([
-			"'self'",
-			"data:",
-			...domain ? [`https://cdn.${domain}`] : [],
-			"https://i3.ytimg.com",
-			"https://www.youtube.com",
-			"https://www.youtube-nocookie.com",
-			...options.imgSrc || []
-		])),
+		"img-src": imgSources,
 		"font-src": ["'self'"],
 		"connect-src": Array.from(/* @__PURE__ */ new Set([
 			"'self'",
 			"https://cloudflareinsights.com",
+			...allowTurnstile ? ["https://challenges.cloudflare.com"] : [],
 			...options.connectSrc || []
 		])),
 		"frame-ancestors": ["'none'"],
 		"frame-src": Array.from(/* @__PURE__ */ new Set([
 			"https://www.youtube.com",
 			"https://www.youtube-nocookie.com",
+			...allowTurnstile ? ["https://challenges.cloudflare.com"] : [],
 			...options.frameSrc || []
 		])),
 		"script-src": Array.from(/* @__PURE__ */ new Set([
@@ -32,6 +36,7 @@ function buildCspHeader(options = {}, nonce) {
 			...nonce ? [`'nonce-${nonce}'`] : [],
 			"https://static.cloudflareinsights.com",
 			"https://betterlytics.io/analytics.js",
+			...allowTurnstile ? ["https://challenges.cloudflare.com"] : [],
 			"'inline-speculation-rules'",
 			"'sha256-ZuMSxilKU+4KIM8LWna4lqBEKzd6WaiAjz6gamhm7zM='",
 			...options.scriptResources || []

package/dist/index.d.mts

@@ -1,6 +1,7 @@
-import { i as SecurityOptions, n as RateLimitOptions, r as RateLimiterBinding, t as ConstructionOptions } from "./types-Dcvwj-af.mjs";
+import { i as SecurityOptions, n as RateLimitOptions, r as RateLimiterBinding, t as ConstructionOptions } from "./types-CL5HooHU.mjs";
 import { buildCspHeader } from "./csp.mjs";
 import { RimelightSecurityPlugin, SecurityPluginOptions, security } from "./vite.mjs";
 import { CONSTRUCTION_GUEST_COOKIE, construction, isConstructionGuest, signInConstructionGuest } from "./middleware/construction.mjs";
 import rimelightSecurity, { RimelightSecurityOptions } from "./integration.mjs";
-export { CONSTRUCTION_GUEST_COOKIE, ConstructionOptions, RateLimitOptions, RateLimiterBinding, RimelightSecurityOptions, RimelightSecurityPlugin, SecurityOptions, SecurityPluginOptions, buildCspHeader, construction, isConstructionGuest, rimelightSecurity, security, security as sri, signInConstructionGuest };
+import { TurnstileVerifyOptions, TurnstileVerifyResult, getTurnstileSecretKey, getTurnstileSiteKey, isTurnstileEnabled, verifyTurnstile } from "./turnstile.mjs";
+export { CONSTRUCTION_GUEST_COOKIE, ConstructionOptions, RateLimitOptions, RateLimiterBinding, RimelightSecurityOptions, RimelightSecurityPlugin, SecurityOptions, SecurityPluginOptions, TurnstileVerifyOptions, TurnstileVerifyResult, buildCspHeader, construction, getTurnstileSecretKey, getTurnstileSiteKey, isConstructionGuest, isTurnstileEnabled, rimelightSecurity, security, security as sri, signInConstructionGuest, verifyTurnstile };

package/dist/index.mjs

@@ -3,4 +3,5 @@ import { buildCspHeader } from "./csp.mjs";
 import { security } from "./vite.mjs";
 import { CONSTRUCTION_GUEST_COOKIE, construction, isConstructionGuest, signInConstructionGuest } from "./middleware/construction.mjs";
 import rimelightSecurity from "./integration.mjs";
-export { CONSTRUCTION_GUEST_COOKIE, buildCspHeader, construction, isConstructionGuest, rimelightSecurity, security, security as sri, signInConstructionGuest };
+import { getTurnstileSecretKey, getTurnstileSiteKey, isTurnstileEnabled, verifyTurnstile } from "./turnstile.mjs";
+export { CONSTRUCTION_GUEST_COOKIE, buildCspHeader, construction, getTurnstileSecretKey, getTurnstileSiteKey, isConstructionGuest, isTurnstileEnabled, rimelightSecurity, security, security as sri, signInConstructionGuest, verifyTurnstile };

package/dist/integration.d.mts

@@ -1,4 +1,4 @@
-import { i as SecurityOptions, t as ConstructionOptions } from "./types-Dcvwj-af.mjs";
+import { i as SecurityOptions, t as ConstructionOptions } from "./types-CL5HooHU.mjs";
 import { AstroIntegration } from "astro";
 //#region src/integration.d.ts
 export interface RimelightSecurityOptions extends SecurityOptions {

package/dist/middleware/construction.d.mts

@@ -1,4 +1,4 @@
-import { t as ConstructionOptions } from "../types-Dcvwj-af.mjs";
+import { t as ConstructionOptions } from "../types-CL5HooHU.mjs";
 //#region src/middleware/construction.d.ts
 export declare const CONSTRUCTION_GUEST_COOKIE = "rimelight-construction-guest";
 /**

package/dist/middleware/ratelimit.d.mts

@@ -1,4 +1,4 @@
-import { n as RateLimitOptions } from "../types-Dcvwj-af.mjs";
+import { n as RateLimitOptions } from "../types-CL5HooHU.mjs";
 //#region src/middleware/ratelimit.d.ts
 /**
  * Middleware to enforce rate limits on sensitive endpoints using Cloudflare Rate Limiting bindings.
@@ -18,5 +18,5 @@ import { n as RateLimitOptions } from "../types-Dcvwj-af.mjs";
  *     })
  *   )
  */
-export declare const ratelimit: (options?: RateLimitOptions) => (c: any, next: () => Promise<any> | any) => Promise<Response | any>;
+export declare const ratelimit: (options?: RateLimitOptions) => (c: any, next: () => Promise<any>) => Promise<any>;
 //#endregion

package/dist/middleware/security.d.mts

@@ -1,4 +1,4 @@
-import { i as SecurityOptions } from "../types-Dcvwj-af.mjs";
+import { i as SecurityOptions } from "../types-CL5HooHU.mjs";
 //#region src/middleware/security.d.ts
 /**
  * Universal Security Middleware for Hono and Web Standards (Fetch API). Injects security headers,

package/dist/turnstile.d.mts

@@ -0,0 +1,53 @@
+//#region src/turnstile.d.ts
+export interface TurnstileVerifyOptions {
+  /**
+   * The response token provided by the Turnstile client-side widget (e.g. `cf-turnstile-response`).
+   */
+  token?: string | null | undefined;
+  /**
+   * The secret key for Turnstile verification. Can be passed directly or read from `env`.
+   */
+  secretKey?: string | undefined;
+  /**
+   * The Cloudflare environment or process environment object containing TURNSTILE_SECRET_KEY /
+   * TURNSTILE_SITE_KEY.
+   */
+  env?: any;
+  /**
+   * The client's IP address (e.g. from `CF-Connecting-IP` or `Astro.clientAddress`).
+   */
+  remoteIp?: string | undefined;
+  /**
+   * Whether to fail open (succeed) if keys are not configured or during network errors. Defaults to
+   * `true` (safe for local development).
+   */
+  failOpen?: boolean | undefined;
+  /**
+   * Custom verify endpoint URL. Defaults to
+   * `https://challenges.cloudflare.com/turnstile/v0/siteverify`.
+   */
+  endpoint?: string | undefined;
+}
+export interface TurnstileVerifyResult {
+  success: boolean;
+  error?: string | undefined;
+  errorCodes?: string[] | undefined;
+}
+/**
+ * Checks if Turnstile keys are present in the provided environment or `process.env`.
+ */
+export declare function isTurnstileEnabled(env?: any): boolean;
+/**
+ * Resolves the Turnstile secret key from options or environment.
+ */
+export declare function getTurnstileSecretKey(options: TurnstileVerifyOptions): string | undefined;
+/**
+ * Resolves the Turnstile site key from environment or process.env.
+ */
+export declare function getTurnstileSiteKey(env?: any): string | undefined;
+/**
+ * Verifies a Cloudflare Turnstile token on the server. Supports both options object and classic
+ * signature `(token, env, remoteIp)`.
+ */
+export declare function verifyTurnstile(tokenOrOptions: string | null | undefined | TurnstileVerifyOptions, legacyEnv?: any, legacyRemoteIp?: string): Promise<TurnstileVerifyResult>;
+//#endregion

package/dist/turnstile.mjs

@@ -0,0 +1,92 @@
+//#region src/turnstile.ts
+/**
+* Checks if Turnstile keys are present in the provided environment or `process.env`.
+*/
+function isTurnstileEnabled(env) {
+	const siteKey = env?.TURNSTILE_SITE_KEY || (typeof process !== "undefined" ? process.env?.["TURNSTILE_SITE_KEY"] : void 0);
+	const secretKey = env?.TURNSTILE_SECRET_KEY || (typeof process !== "undefined" ? process.env?.["TURNSTILE_SECRET_KEY"] : void 0);
+	return Boolean(siteKey && secretKey);
+}
+/**
+* Resolves the Turnstile secret key from options or environment.
+*/
+function getTurnstileSecretKey(options) {
+	if (options.secretKey) return options.secretKey;
+	return options.env?.TURNSTILE_SECRET_KEY || (typeof process !== "undefined" ? process.env?.["TURNSTILE_SECRET_KEY"] : void 0);
+}
+/**
+* Resolves the Turnstile site key from environment or process.env.
+*/
+function getTurnstileSiteKey(env) {
+	return env?.TURNSTILE_SITE_KEY || (typeof process !== "undefined" ? process.env?.["TURNSTILE_SITE_KEY"] : void 0);
+}
+/**
+* Verifies a Cloudflare Turnstile token on the server. Supports both options object and classic
+* signature `(token, env, remoteIp)`.
+*/
+async function verifyTurnstile(tokenOrOptions, legacyEnv, legacyRemoteIp) {
+	const options = typeof tokenOrOptions === "object" && tokenOrOptions !== null ? tokenOrOptions : {
+		token: tokenOrOptions,
+		env: legacyEnv,
+		remoteIp: legacyRemoteIp
+	};
+	const failOpen = options.failOpen ?? true;
+	const token = options.token;
+	const secretKey = getTurnstileSecretKey(options);
+	if (!secretKey) {
+		if (failOpen) {
+			console.log("[Turnstile] Keys missing or not configured. Skipping verification (Failing Open for local dev).");
+			return { success: true };
+		}
+		return {
+			success: false,
+			error: "Turnstile secret key is not configured."
+		};
+	}
+	if (!token) return {
+		success: false,
+		error: "Security check token is missing."
+	};
+	try {
+		const endpoint = options.endpoint || "https://challenges.cloudflare.com/turnstile/v0/siteverify";
+		const response = await fetch(endpoint, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({
+				secret: secretKey,
+				response: token,
+				remoteip: options.remoteIp
+			})
+		});
+		if (!response.ok) {
+			if (failOpen) {
+				console.error(`[Turnstile] API returned status ${response.status}. Failing open.`);
+				return { success: true };
+			}
+			return {
+				success: false,
+				error: `Cloudflare Turnstile API returned status ${response.status}`
+			};
+		}
+		const data = await response.json();
+		if (data.success) return { success: true };
+		const codes = data["error-codes"] || [];
+		let msg = "Bot check verification failed.";
+		if (codes.includes("timeout-or-duplicate")) msg = "Verification token expired or already used. Please refresh the security check.";
+		else if (codes.includes("invalid-input-response")) msg = "Invalid verification response. Please try again.";
+		return {
+			success: false,
+			error: msg,
+			errorCodes: codes
+		};
+	} catch (err) {
+		console.error("[Turnstile Exception]", err);
+		if (failOpen) return { success: true };
+		return {
+			success: false,
+			error: err?.message || "Turnstile verification encountered an exception."
+		};
+	}
+}
+//#endregion
+export { getTurnstileSecretKey, getTurnstileSiteKey, isTurnstileEnabled, verifyTurnstile };

package/dist/{types-Dcvwj-af.d.mts → types-CL5HooHU.d.mts}

@@ -29,6 +29,11 @@ interface SecurityOptions {
    * Additional style resources / origins
    */
   styleResources?: string[];
+  /**
+   * Enables Cloudflare Turnstile CSP allowances (challenges.cloudflare.com in script-src,
+   * frame-src, connect-src). Defaults to true.
+   */
+  turnstile?: boolean;
   /**
    * Enables the 'require-trusted-types-for' directive
    */

package/dist/types.d.mts

@@ -1,2 +1,2 @@
-import { i as SecurityOptions, n as RateLimitOptions, r as RateLimiterBinding, t as ConstructionOptions } from "./types-Dcvwj-af.mjs";
+import { i as SecurityOptions, n as RateLimitOptions, r as RateLimiterBinding, t as ConstructionOptions } from "./types-CL5HooHU.mjs";
 export { ConstructionOptions, RateLimitOptions, RateLimiterBinding, SecurityOptions };

package/dist/vite.d.mts

@@ -1,4 +1,4 @@
-import { i as SecurityOptions } from "./types-Dcvwj-af.mjs";
+import { i as SecurityOptions } from "./types-CL5HooHU.mjs";
 //#region src/vite.d.ts
 export interface RimelightSecurityPlugin {
   name: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rimelight/security",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "private": false,
   "description": "Rimelight Entertainment's Security Package",
   "homepage": "https://rimelight.com/docs",
@@ -37,6 +37,10 @@
       "types": "./dist/integration.d.mts",
       "import": "./dist/integration.mjs"
     },
+    "./turnstile": {
+      "types": "./dist/turnstile.d.mts",
+      "import": "./dist/turnstile.mjs"
+    },
     "./components/*": "./src/components/*",
     "./layouts/*": "./src/layouts/*",
     "./pages/*": "./src/pages/*",
@@ -47,12 +51,12 @@
   },
   "dependencies": {
     "@rimelight/i18n": "0.0.17",
-    "@rimelight/seo": "0.0.13",
+    "@rimelight/seo": "0.0.14",
     "@rimelight/ui": "0.0.57"
   },
   "devDependencies": {
     "@astrojs/check": "0.9.10",
-    "@rimelight/config": "0.0.16",
+    "@rimelight/config": "0.0.17",
     "astro": "7.3.3",
     "hono": "4.13.8",
     "typescript": "6.0.3"

package/src/components/Turnstile.astro

@@ -0,0 +1,94 @@
+---
+import { getTurnstileSiteKey } from "../turnstile"
+
+export interface Props {
+  /**
+   * Cloudflare Turnstile Site Key. If omitted, attempts to read from `Astro.locals.runtime.env` or `import.meta.env`.
+   */
+  siteKey?: string
+
+  /**
+   * Theme mode for Turnstile widget: "auto", "light", or "dark". Defaults to "auto".
+   */
+  theme?: "auto" | "light" | "dark"
+
+  /**
+   * Widget size: "normal", "compact", or "flexible". Defaults to "normal".
+   */
+  size?: "normal" | "compact" | "flexible"
+
+  /**
+   * Optional custom CSS class.
+   */
+  class?: string
+
+  /**
+   * Form field name for the generated token. Defaults to "cf-turnstile-response".
+   */
+  responseFieldName?: string
+
+  /**
+   * Action name used for Turnstile analytics / reporting.
+   */
+  action?: string
+
+  /**
+   * CData payload if using custom challenge metadata.
+   */
+  cdata?: string
+
+  /**
+   * Turnstile execution mode: "render" (immediate) or "execute" (explicit).
+   */
+  execution?: "render" | "execute"
+
+  /**
+   * Turnstile appearance mode: "always", "execute", or "interaction-only".
+   */
+  appearance?: "always" | "execute" | "interaction-only"
+
+  /**
+   * Automatically load the Cloudflare Turnstile api.js script. Defaults to true.
+   */
+  injectScript?: boolean
+}
+
+const {
+  siteKey: propSiteKey,
+  theme = "auto",
+  size = "normal",
+  class: className = "cf-turnstile my-2",
+  responseFieldName = "cf-turnstile-response",
+  action,
+  cdata,
+  execution,
+  appearance,
+  injectScript = true,
+  ...rest
+} = Astro.props
+
+const env = (Astro.locals as any)?.runtime?.env
+const resolvedSiteKey = propSiteKey || getTurnstileSiteKey(env) || import.meta.env["TURNSTILE_SITE_KEY"] || ""
+---
+
+{
+  resolvedSiteKey && (
+    <>
+      <div
+        class={className}
+        data-sitekey={resolvedSiteKey}
+        data-theme={theme}
+        data-size={size}
+        data-response-field-name={responseFieldName}
+        data-action={action}
+        data-cdata={cdata}
+        data-execution={execution}
+        data-appearance={appearance}
+        {...rest}
+      />
+      {injectScript && (
+        <script is:inline src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
+      )}
+    </>
+  )
+}

package/src/csp.ts

@@ -18,14 +18,22 @@ export function buildCspHeader(options: SecurityOptions = {}, nonce?: string): s
     ])
   )
 
+  const allowTurnstile = options.turnstile !== false
+
   const connectSources = Array.from(
-    new Set(["'self'", "https://cloudflareinsights.com", ...(options.connectSrc || [])])
+    new Set([
+      "'self'",
+      "https://cloudflareinsights.com",
+      ...(allowTurnstile ? ["https://challenges.cloudflare.com"] : []),
+      ...(options.connectSrc || [])
+    ])
   )
 
   const frameSources = Array.from(
     new Set([
       "https://www.youtube.com",
       "https://www.youtube-nocookie.com",
+      ...(allowTurnstile ? ["https://challenges.cloudflare.com"] : []),
       ...(options.frameSrc || [])
     ])
   )
@@ -36,6 +44,7 @@ export function buildCspHeader(options: SecurityOptions = {}, nonce?: string): s
       ...(nonce ? [`'nonce-${nonce}'`] : []),
       "https://static.cloudflareinsights.com",
       "https://betterlytics.io/analytics.js",
+      ...(allowTurnstile ? ["https://challenges.cloudflare.com"] : []),
       "'inline-speculation-rules'",
       // Astro ClientRouter (View Transitions inline script sha)
       "'sha256-ZuMSxilKU+4KIM8LWna4lqBEKzd6WaiAjz6gamhm7zM='",

package/src/index.ts

@@ -3,3 +3,4 @@ export * from "./types"
 export * from "./csp"
 export * from "./middleware/construction"
 export * from "./integration"
+export * from "./turnstile"

package/src/middleware/ratelimit.ts

@@ -58,7 +58,7 @@ export const ratelimit = (options: RateLimitOptions = {}) => {
     }
   } = options
 
-  return async (c: any, next: () => Promise<any> | any): Promise<Response | any> => {
+  return async (c: any, next: () => Promise<any>): Promise<any> => {
     const path = c?.req?.path || ""
 
     // 1. Check if the current request matches the rate-limited routes

package/src/turnstile.ts

@@ -0,0 +1,172 @@
+export interface TurnstileVerifyOptions {
+  /**
+   * The response token provided by the Turnstile client-side widget (e.g. `cf-turnstile-response`).
+   */
+  token?: string | null | undefined
+
+  /**
+   * The secret key for Turnstile verification. Can be passed directly or read from `env`.
+   */
+  secretKey?: string | undefined
+
+  /**
+   * The Cloudflare environment or process environment object containing TURNSTILE_SECRET_KEY /
+   * TURNSTILE_SITE_KEY.
+   */
+  env?: any
+
+  /**
+   * The client's IP address (e.g. from `CF-Connecting-IP` or `Astro.clientAddress`).
+   */
+  remoteIp?: string | undefined
+
+  /**
+   * Whether to fail open (succeed) if keys are not configured or during network errors. Defaults to
+   * `true` (safe for local development).
+   */
+  failOpen?: boolean | undefined
+
+  /**
+   * Custom verify endpoint URL. Defaults to
+   * `https://challenges.cloudflare.com/turnstile/v0/siteverify`.
+   */
+  endpoint?: string | undefined
+}
+
+export interface TurnstileVerifyResult {
+  success: boolean
+  error?: string | undefined
+  errorCodes?: string[] | undefined
+}
+
+interface CloudflareVerifyResponse {
+  "success": boolean
+  "error-codes"?: string[]
+  "challenge_ts"?: string
+  "hostname"?: string
+  "action"?: string
+  "cdata"?: string
+}
+
+/**
+ * Checks if Turnstile keys are present in the provided environment or `process.env`.
+ */
+export function isTurnstileEnabled(env?: any): boolean {
+  const siteKey =
+    env?.TURNSTILE_SITE_KEY ||
+    (typeof process !== "undefined" ? process.env?.["TURNSTILE_SITE_KEY"] : undefined)
+
+  const secretKey =
+    env?.TURNSTILE_SECRET_KEY ||
+    (typeof process !== "undefined" ? process.env?.["TURNSTILE_SECRET_KEY"] : undefined)
+
+  return Boolean(siteKey && secretKey)
+}
+
+/**
+ * Resolves the Turnstile secret key from options or environment.
+ */
+export function getTurnstileSecretKey(options: TurnstileVerifyOptions): string | undefined {
+  if (options.secretKey) return options.secretKey
+  const env = options.env
+  return (
+    env?.TURNSTILE_SECRET_KEY ||
+    (typeof process !== "undefined" ? process.env?.["TURNSTILE_SECRET_KEY"] : undefined)
+  )
+}
+
+/**
+ * Resolves the Turnstile site key from environment or process.env.
+ */
+export function getTurnstileSiteKey(env?: any): string | undefined {
+  return (
+    env?.TURNSTILE_SITE_KEY ||
+    (typeof process !== "undefined" ? process.env?.["TURNSTILE_SITE_KEY"] : undefined)
+  )
+}
+
+/**
+ * Verifies a Cloudflare Turnstile token on the server. Supports both options object and classic
+ * signature `(token, env, remoteIp)`.
+ */
+export async function verifyTurnstile(
+  tokenOrOptions: string | null | undefined | TurnstileVerifyOptions,
+  legacyEnv?: any,
+  legacyRemoteIp?: string
+): Promise<TurnstileVerifyResult> {
+  const options: TurnstileVerifyOptions =
+    typeof tokenOrOptions === "object" && tokenOrOptions !== null
+      ? tokenOrOptions
+      : {
+          token: tokenOrOptions,
+          env: legacyEnv,
+          remoteIp: legacyRemoteIp
+        }
+
+  const failOpen = options.failOpen ?? true
+  const token = options.token
+
+  // If Turnstile is not enabled (missing keys in env and no explicit secretKey), fail open for local dev
+  const secretKey = getTurnstileSecretKey(options)
+  if (!secretKey) {
+    if (failOpen) {
+      console.log(
+        "[Turnstile] Keys missing or not configured. Skipping verification (Failing Open for local dev)."
+      )
+      return { success: true }
+    }
+    return { success: false, error: "Turnstile secret key is not configured." }
+  }
+
+  if (!token) {
+    return { success: false, error: "Security check token is missing." }
+  }
+
+  try {
+    const endpoint = options.endpoint || "https://challenges.cloudflare.com/turnstile/v0/siteverify"
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        secret: secretKey,
+        response: token,
+        remoteip: options.remoteIp
+      })
+    })
+
+    if (!response.ok) {
+      if (failOpen) {
+        console.error(`[Turnstile] API returned status ${response.status}. Failing open.`)
+        return { success: true }
+      }
+      return {
+        success: false,
+        error: `Cloudflare Turnstile API returned status ${response.status}`
+      }
+    }
+
+    const data: CloudflareVerifyResponse = await response.json()
+    if (data.success) {
+      return { success: true }
+    }
+
+    const codes = data["error-codes"] || []
+    let msg = "Bot check verification failed."
+    if (codes.includes("timeout-or-duplicate")) {
+      msg = "Verification token expired or already used. Please refresh the security check."
+    } else if (codes.includes("invalid-input-response")) {
+      msg = "Invalid verification response. Please try again."
+    }
+
+    return { success: false, error: msg, errorCodes: codes }
+  } catch (err: any) {
+    console.error("[Turnstile Exception]", err)
+    if (failOpen) {
+      return { success: true }
+    }
+    return {
+      success: false,
+      error: err?.message || "Turnstile verification encountered an exception."
+    }
+  }
+}

package/src/types.ts

@@ -35,6 +35,12 @@ export interface SecurityOptions {
    */
   styleResources?: string[]
 
+  /**
+   * Enables Cloudflare Turnstile CSP allowances (challenges.cloudflare.com in script-src,
+   * frame-src, connect-src). Defaults to true.
+   */
+  turnstile?: boolean
+
   /**
    * Enables the 'require-trusted-types-for' directive
    */