nuxt4-turnstile 1.0.0

package/README.md

@@ -0,0 +1,266 @@
+# Nuxt4 Turnstile
+
+[![npm version](https://img.shields.io/npm/v/nuxt4-turnstile.svg)](https://www.npmjs.com/package/nuxt4-turnstile)
+[![Nuxt](https://img.shields.io/badge/Nuxt-4.x-00DC82?logo=nuxt.js)](https://nuxt.com)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Cloudflare Turnstile integration for **Nuxt 4** - A privacy-focused CAPTCHA alternative.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/bootssecurity/nuxt4-turnstile/main/public/screenshot.png" width="600" alt="Nuxt4 Turnstile Demo">
+</p>
+
+## ✨ Features
+
+- 🔒 **Privacy-focused** - No tracking, no cookies, no fingerprinting
+- 🚀 **Nuxt 4 Compatible** - Built specifically for Nuxt 4
+- 📦 **Auto-imported** - Components and composables ready to use
+- 🛡️ **Server Validation** - Built-in server-side token verification
+- 🎨 **Customizable** - Theme, size, appearance options
+- ♻️ **Auto-refresh** - Automatically refreshes tokens before expiry
+- 📝 **TypeScript** - Full TypeScript support
+
+## 📦 Installation
+
+```bash
+# npm
+npm install nuxt4-turnstile
+
+# pnpm
+pnpm add nuxt4-turnstile
+
+# bun
+bun add nuxt4-turnstile
+```
+
+## ⚙️ Configuration
+
+Add `nuxt4-turnstile` to your `nuxt.config.ts`:
+
+```typescript
+export default defineNuxtConfig({
+  modules: ['nuxt4-turnstile'],
+
+  turnstile: {
+    siteKey: 'your-site-key', // Get from Cloudflare Dashboard
+  },
+
+  runtimeConfig: {
+    turnstile: {
+      // Override with NUXT_TURNSTILE_SECRET_KEY env variable
+      secretKey: '',
+    },
+  },
+})
+```
+
+### Get Your Keys
+
+1. Go to [Cloudflare Turnstile](https://dash.cloudflare.com/?to=/:account/turnstile)
+2. Create a new site
+3. Copy your **Site Key** (public) and **Secret Key** (server-side)
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `siteKey` | `string` | `''` | Your Turnstile site key (required) |
+| `secretKey` | `string` | `''` | Your Turnstile secret key (server-side) |
+| `addValidateEndpoint` | `boolean` | `false` | Add `/_turnstile/validate` endpoint |
+| `appearance` | `'always' \| 'execute' \| 'interaction-only'` | `'always'` | Widget visibility |
+| `theme` | `'light' \| 'dark' \| 'auto'` | `'auto'` | Widget theme |
+| `size` | `'normal' \| 'compact' \| 'flexible'` | `'normal'` | Widget size |
+| `retry` | `'auto' \| 'never'` | `'auto'` | Retry behavior |
+| `retryInterval` | `number` | `8000` | Retry interval in ms |
+| `refreshExpired` | `number` | `250` | Auto-refresh before expiry (seconds) |
+| `language` | `string` | `'auto'` | Widget language |
+
+## 🚀 Usage
+
+### Component
+
+Use the auto-imported `<NuxtTurnstile>` component:
+
+```vue
+<template>
+  <form @submit.prevent="onSubmit">
+    <NuxtTurnstile v-model="token" />
+    <button type="submit" :disabled="!token">Submit</button>
+  </form>
+</template>
+
+<script setup>
+const token = ref('')
+
+async function onSubmit() {
+  // Send token to your server for verification
+  await $fetch('/api/contact', {
+    method: 'POST',
+    body: { token, message: '...' }
+  })
+}
+</script>
+```
+
+### Component Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `v-model` | `string` | Two-way binding for the token |
+| `element` | `string` | HTML element to use (default: `'div'`) |
+| `options` | `TurnstileOptions` | Override module options |
+| `action` | `string` | Custom action for analytics |
+| `cData` | `string` | Custom data payload |
+
+### Component Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `@verify` | `token: string` | Token generated |
+| `@expire` | - | Token expired |
+| `@error` | `error: Error` | Error occurred |
+| `@before-interactive` | - | Before challenge |
+| `@after-interactive` | - | After challenge |
+| `@unsupported` | - | Browser unsupported |
+
+### Component Methods (via ref)
+
+```vue
+<template>
+  <NuxtTurnstile ref="turnstile" v-model="token" />
+  <button @click="turnstile?.reset()">Reset</button>
+</template>
+
+<script setup>
+const turnstile = ref()
+const token = ref('')
+</script>
+```
+
+| Method | Description |
+|--------|-------------|
+| `reset()` | Reset widget for re-verification |
+| `remove()` | Remove widget from DOM |
+| `getResponse()` | Get current token |
+| `isExpired()` | Check if token is expired |
+| `execute()` | Execute invisible challenge |
+
+## 🛡️ Server Verification
+
+### Using the Built-in Endpoint
+
+Enable the validation endpoint in your config:
+
+```typescript
+export default defineNuxtConfig({
+  turnstile: {
+    siteKey: '...',
+    addValidateEndpoint: true,
+  },
+})
+```
+
+Then call it from your client:
+
+```typescript
+const { success } = await $fetch('/_turnstile/validate', {
+  method: 'POST',
+  body: { token }
+})
+```
+
+### Using the Helper Function
+
+In your server routes:
+
+```typescript
+// server/api/contact.post.ts
+export default defineEventHandler(async (event) => {
+  const { token, message } = await readBody(event)
+
+  // Verify the token
+  const result = await verifyTurnstileToken(token)
+
+  if (!result.success) {
+    throw createError({
+      statusCode: 400,
+      message: 'Invalid captcha'
+    })
+  }
+
+  // Continue with your logic...
+  return { success: true }
+})
+```
+
+### Verification Options
+
+```typescript
+await verifyTurnstileToken(token, {
+  secretKey: 'override-secret',  // Override config secret
+  remoteip: '1.2.3.4',           // Client IP for security
+  action: 'login',               // Validate expected action
+  cdata: 'user-123',             // Validate expected cdata
+})
+```
+
+## 🔧 Composable
+
+Use the `useTurnstile` composable for programmatic access:
+
+```typescript
+const {
+  isAvailable,  // Is Turnstile loaded?
+  siteKey,      // Get site key
+  verify,       // Verify token via endpoint
+  render,       // Render widget programmatically
+  reset,        // Reset widget
+  remove,       // Remove widget
+  getResponse,  // Get token
+  isExpired,    // Check expiry
+  execute,      // Execute invisible challenge
+} = useTurnstile()
+```
+
+## 🌐 Environment Variables
+
+Override configuration with environment variables:
+
+```bash
+NUXT_PUBLIC_TURNSTILE_SITE_KEY=your-site-key
+NUXT_TURNSTILE_SECRET_KEY=your-secret-key
+```
+
+## 📝 TypeScript
+
+Types are automatically available:
+
+```typescript
+import type {
+  TurnstileInstance,
+  TurnstileOptions,
+  TurnstileVerifyResponse,
+} from 'nuxt4-turnstile'
+```
+
+## 🧪 Testing
+
+For testing, use Cloudflare's test keys:
+
+| Key | Behavior |
+|-----|----------|
+| `1x00000000000000000000AA` | Always passes |
+| `2x00000000000000000000AB` | Always blocks |
+| `3x00000000000000000000FF` | Forces interactive challenge |
+
+Secret test keys:
+
+| Key | Behavior |
+|-----|----------|
+| `1x0000000000000000000000000000000AA` | Always passes |
+| `2x0000000000000000000000000000000AA` | Always fails |
+| `3x0000000000000000000000000000000AA` | Yields token spend error |
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) for details.

package/dist/module.d.mts

@@ -0,0 +1,59 @@
+import * as _nuxt_schema from '@nuxt/schema';
+export { TurnstileInstance, TurnstileOptions } from '../dist/runtime/types.js';
+
+interface ModuleOptions {
+    /**
+     * Turnstile site key (public)
+     * Get one at https://dash.cloudflare.com/turnstile
+     */
+    siteKey: string;
+    /**
+     * Turnstile secret key (server-side only)
+     * Override with NUXT_TURNSTILE_SECRET_KEY env variable
+     */
+    secretKey?: string;
+    /**
+     * Add a validation endpoint at /_turnstile/validate
+     * @default false
+     */
+    addValidateEndpoint?: boolean;
+    /**
+     * Turnstile widget appearance
+     * @default 'auto'
+     */
+    appearance?: 'always' | 'execute' | 'interaction-only';
+    /**
+     * Turnstile widget theme
+     * @default 'auto'
+     */
+    theme?: 'light' | 'dark' | 'auto';
+    /**
+     * Turnstile widget size
+     * @default 'normal'
+     */
+    size?: 'normal' | 'compact' | 'flexible';
+    /**
+     * Retry behavior
+     * @default 'auto'
+     */
+    retry?: 'auto' | 'never';
+    /**
+     * Retry interval in milliseconds
+     * @default 8000
+     */
+    retryInterval?: number;
+    /**
+     * Refresh token before expiry (in seconds)
+     * @default 250
+     */
+    refreshExpired?: number;
+    /**
+     * Language code for widget
+     * @default 'auto'
+     */
+    language?: string;
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,12 @@
+{
+  "name": "nuxt4-turnstile",
+  "configKey": "turnstile",
+  "compatibility": {
+    "nuxt": ">=4.0.0"
+  },
+  "version": "1.0.0",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "3.6.1"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,75 @@
+import { defineNuxtModule, createResolver, addPlugin, addComponent, addImports, addServerImports, addServerHandler } from '@nuxt/kit';
+import { defu } from 'defu';
+
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "nuxt4-turnstile",
+    configKey: "turnstile",
+    compatibility: {
+      nuxt: ">=4.0.0"
+    }
+  },
+  // Default configuration options
+  defaults: {
+    siteKey: "",
+    secretKey: "",
+    addValidateEndpoint: false,
+    appearance: "always",
+    theme: "auto",
+    size: "normal",
+    retry: "auto",
+    retryInterval: 8e3,
+    refreshExpired: 250,
+    language: "auto"
+  },
+  setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    if (!options.siteKey) {
+      console.warn("[nuxt-turnstile-cf] No siteKey provided. Set turnstile.siteKey in your nuxt.config or NUXT_PUBLIC_TURNSTILE_SITE_KEY env variable.");
+    }
+    nuxt.options.runtimeConfig.public = defu(nuxt.options.runtimeConfig.public, {
+      turnstile: {
+        siteKey: options.siteKey,
+        appearance: options.appearance,
+        theme: options.theme,
+        size: options.size,
+        retry: options.retry,
+        retryInterval: options.retryInterval,
+        refreshExpired: options.refreshExpired,
+        language: options.language
+      }
+    });
+    nuxt.options.runtimeConfig.turnstile = defu(
+      nuxt.options.runtimeConfig.turnstile,
+      {
+        secretKey: options.secretKey || ""
+      }
+    );
+    addPlugin(resolver.resolve("./runtime/plugin.client"));
+    addComponent({
+      name: "NuxtTurnstile",
+      filePath: resolver.resolve("./runtime/components/NuxtTurnstile.vue")
+    });
+    addImports({
+      name: "useTurnstile",
+      as: "useTurnstile",
+      from: resolver.resolve("./runtime/composables/useTurnstile")
+    });
+    addServerImports([
+      {
+        name: "verifyTurnstileToken",
+        as: "verifyTurnstileToken",
+        from: resolver.resolve("./runtime/server/utils/verifyTurnstileToken")
+      }
+    ]);
+    if (options.addValidateEndpoint) {
+      addServerHandler({
+        route: "/_turnstile/validate",
+        method: "post",
+        handler: resolver.resolve("./runtime/server/api/validate")
+      });
+    }
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/components/NuxtTurnstile.d.vue.ts

@@ -0,0 +1,45 @@
+import type { TurnstileInstance, TurnstileOptions } from '../types.js';
+type __VLS_Props = {
+    /**
+     * HTML element to use as container
+     */
+    element?: string;
+    /**
+     * Custom Turnstile options (overrides module config)
+     */
+    options?: Partial<TurnstileOptions>;
+    /**
+     * Custom action for analytics
+     */
+    action?: string;
+    /**
+     * Custom cData payload
+     */
+    cData?: string;
+};
+type __VLS_ModelProps = {
+    modelValue?: string;
+};
+type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
+declare const __VLS_export: import("vue").DefineComponent<__VLS_PublicProps, TurnstileInstance, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:modelValue": (value: string) => any;
+} & {
+    verify: (token: string) => any;
+    expire: () => any;
+    error: (error: Error) => any;
+    "before-interactive": () => any;
+    "after-interactive": () => any;
+    unsupported: () => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    onVerify?: ((token: string) => any) | undefined;
+    onExpire?: (() => any) | undefined;
+    onError?: ((error: Error) => any) | undefined;
+    "onBefore-interactive"?: (() => any) | undefined;
+    "onAfter-interactive"?: (() => any) | undefined;
+    onUnsupported?: (() => any) | undefined;
+    "onUpdate:modelValue"?: ((value: string) => any) | undefined;
+}>, {
+    element: string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/components/NuxtTurnstile.vue

@@ -0,0 +1,132 @@
+<template>
+  <component :is="element" ref="containerRef" />
+</template>
+
+<script setup>
+const props = defineProps({
+  element: { type: String, required: false, default: "div" },
+  options: { type: Object, required: false },
+  action: { type: String, required: false },
+  cData: { type: String, required: false }
+});
+const config = useRuntimeConfig();
+const token = defineModel({ type: String, ...{ default: "" } });
+const containerRef = ref(null);
+const widgetId = ref(null);
+const isReady = ref(false);
+const emit = defineEmits(["verify", "expire", "error", "before-interactive", "after-interactive", "unsupported"]);
+const reset = () => {
+  if (widgetId.value && window.turnstile) {
+    window.turnstile.reset(widgetId.value);
+    token.value = "";
+  }
+};
+const remove = () => {
+  if (widgetId.value && window.turnstile) {
+    window.turnstile.remove(widgetId.value);
+    widgetId.value = null;
+    token.value = "";
+  }
+};
+const getResponse = () => {
+  if (widgetId.value && window.turnstile) {
+    return window.turnstile.getResponse(widgetId.value);
+  }
+  return void 0;
+};
+const isExpired = () => {
+  if (widgetId.value && window.turnstile) {
+    return window.turnstile.isExpired(widgetId.value);
+  }
+  return false;
+};
+const execute = () => {
+  if (widgetId.value && window.turnstile) {
+    window.turnstile.execute(widgetId.value);
+  }
+};
+const instance = {
+  reset,
+  remove,
+  getResponse,
+  isExpired,
+  execute
+};
+defineExpose(instance);
+const renderWidget = () => {
+  if (!containerRef.value || !window.turnstile) return;
+  const publicConfig = config.public.turnstile;
+  const widgetOptions = {
+    sitekey: publicConfig.siteKey,
+    theme: props.options?.theme || publicConfig.theme,
+    size: props.options?.size || publicConfig.size,
+    appearance: props.options?.appearance || publicConfig.appearance,
+    retry: props.options?.retry || publicConfig.retry,
+    "retry-interval": props.options?.["retry-interval"] || publicConfig.retryInterval,
+    language: props.options?.language || publicConfig.language,
+    action: props.action,
+    cData: props.cData,
+    callback: (responseToken) => {
+      token.value = responseToken;
+      emit("verify", responseToken);
+    },
+    "expired-callback": () => {
+      token.value = "";
+      emit("expire");
+    },
+    "error-callback": (error) => {
+      token.value = "";
+      emit("error", error);
+    },
+    "before-interactive-callback": () => {
+      emit("before-interactive");
+    },
+    "after-interactive-callback": () => {
+      emit("after-interactive");
+    },
+    "unsupported-callback": () => {
+      emit("unsupported");
+    },
+    ...props.options
+  };
+  widgetId.value = window.turnstile.render(containerRef.value, widgetOptions);
+  isReady.value = true;
+};
+const refreshExpiredInterval = ref(null);
+const startAutoRefresh = () => {
+  const refreshSeconds = config.public.turnstile.refreshExpired;
+  if (refreshSeconds && refreshSeconds > 0) {
+    refreshExpiredInterval.value = setInterval(() => {
+      if (isExpired()) {
+        reset();
+      }
+    }, refreshSeconds * 1e3);
+  }
+};
+onMounted(() => {
+  if (window.turnstile) {
+    renderWidget();
+    startAutoRefresh();
+  } else {
+    const checkTurnstile = setInterval(() => {
+      if (window.turnstile) {
+        clearInterval(checkTurnstile);
+        renderWidget();
+        startAutoRefresh();
+      }
+    }, 100);
+    setTimeout(() => {
+      clearInterval(checkTurnstile);
+      if (!window.turnstile) {
+        console.error("[nuxt-turnstile-cf] Turnstile script failed to load");
+      }
+    }, 1e4);
+  }
+});
+onBeforeUnmount(() => {
+  if (refreshExpiredInterval.value) {
+    clearInterval(refreshExpiredInterval.value);
+  }
+  remove();
+});
+</script>

package/dist/runtime/components/NuxtTurnstile.vue.d.ts

@@ -0,0 +1,45 @@
+import type { TurnstileInstance, TurnstileOptions } from '../types.js';
+type __VLS_Props = {
+    /**
+     * HTML element to use as container
+     */
+    element?: string;
+    /**
+     * Custom Turnstile options (overrides module config)
+     */
+    options?: Partial<TurnstileOptions>;
+    /**
+     * Custom action for analytics
+     */
+    action?: string;
+    /**
+     * Custom cData payload
+     */
+    cData?: string;
+};
+type __VLS_ModelProps = {
+    modelValue?: string;
+};
+type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
+declare const __VLS_export: import("vue").DefineComponent<__VLS_PublicProps, TurnstileInstance, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:modelValue": (value: string) => any;
+} & {
+    verify: (token: string) => any;
+    expire: () => any;
+    error: (error: Error) => any;
+    "before-interactive": () => any;
+    "after-interactive": () => any;
+    unsupported: () => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    onVerify?: ((token: string) => any) | undefined;
+    onExpire?: (() => any) | undefined;
+    onError?: ((error: Error) => any) | undefined;
+    "onBefore-interactive"?: (() => any) | undefined;
+    "onAfter-interactive"?: (() => any) | undefined;
+    onUnsupported?: (() => any) | undefined;
+    "onUpdate:modelValue"?: ((value: string) => any) | undefined;
+}>, {
+    element: string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/composables/useTurnstile.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Composable for programmatic Turnstile access
+ */
+export declare function useTurnstile(): {
+    isAvailable: any;
+    siteKey: any;
+    verify: (token: string) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    render: (element: string | HTMLElement, options?: Partial<{
+        callback: (token: string) => void;
+        expiredCallback: () => void;
+        errorCallback: (error: Error) => void;
+    }>) => string | null;
+    reset: (widgetId?: string) => void;
+    remove: (widgetId?: string) => void;
+    getResponse: (widgetId?: string) => string | undefined;
+    isExpired: (widgetId?: string) => boolean;
+    execute: (widgetId?: string) => void;
+};

package/dist/runtime/composables/useTurnstile.js

@@ -0,0 +1,77 @@
+export function useTurnstile() {
+  const config = useRuntimeConfig();
+  const publicConfig = config.public.turnstile;
+  const isAvailable = computed(() => {
+    if (import.meta.client) {
+      return !!window.turnstile;
+    }
+    return false;
+  });
+  const siteKey = computed(() => publicConfig?.siteKey);
+  const verify = async (token) => {
+    try {
+      const response = await $fetch("/_turnstile/validate", {
+        method: "POST",
+        body: { token }
+      });
+      return response;
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : "Verification failed"
+      };
+    }
+  };
+  const render = (element, options) => {
+    if (!import.meta.client || !window.turnstile) {
+      console.warn("[nuxt4-turnstile] Turnstile not available");
+      return null;
+    }
+    return window.turnstile.render(element, {
+      sitekey: publicConfig?.siteKey,
+      theme: publicConfig?.theme,
+      size: publicConfig?.size,
+      callback: options?.callback,
+      "expired-callback": options?.expiredCallback,
+      "error-callback": options?.errorCallback
+    });
+  };
+  const reset = (widgetId) => {
+    if (import.meta.client && window.turnstile) {
+      window.turnstile.reset(widgetId);
+    }
+  };
+  const remove = (widgetId) => {
+    if (import.meta.client && window.turnstile) {
+      window.turnstile.remove(widgetId);
+    }
+  };
+  const getResponse = (widgetId) => {
+    if (import.meta.client && window.turnstile) {
+      return window.turnstile.getResponse(widgetId);
+    }
+    return void 0;
+  };
+  const isExpired = (widgetId) => {
+    if (import.meta.client && window.turnstile) {
+      return window.turnstile.isExpired(widgetId);
+    }
+    return false;
+  };
+  const execute = (widgetId) => {
+    if (import.meta.client && window.turnstile) {
+      window.turnstile.execute(widgetId);
+    }
+  };
+  return {
+    isAvailable,
+    siteKey,
+    verify,
+    render,
+    reset,
+    remove,
+    getResponse,
+    isExpired,
+    execute
+  };
+}

package/dist/runtime/plugin.client.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Client plugin to load Cloudflare Turnstile script
+ */
+declare const _default: any;
+export default _default;

package/dist/runtime/plugin.client.js

@@ -0,0 +1,22 @@
+export default defineNuxtPlugin(() => {
+  const config = useRuntimeConfig();
+  const publicConfig = config.public.turnstile;
+  if (!publicConfig?.siteKey) {
+    console.warn("[nuxt4-turnstile] No siteKey configured. Turnstile widget will not work.");
+    return;
+  }
+  if (document.querySelector('script[src*="challenges.cloudflare.com/turnstile"]')) {
+    return;
+  }
+  const script = document.createElement("script");
+  script.src = "https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit";
+  script.async = true;
+  script.defer = true;
+  script.onload = () => {
+    console.debug("[nuxt4-turnstile] Turnstile script loaded");
+  };
+  script.onerror = () => {
+    console.error("[nuxt4-turnstile] Failed to load Turnstile script");
+  };
+  document.head.appendChild(script);
+});

package/dist/runtime/server/api/validate.d.ts

@@ -0,0 +1,19 @@
+/**
+ * POST /_turnstile/validate
+ *
+ * Validate a Turnstile token from the client
+ *
+ * Request body:
+ * {
+ *   "token": "turnstile-response-token"
+ * }
+ *
+ * Response:
+ * {
+ *   "success": true,
+ *   "challenge_ts": "2024-01-01T00:00:00Z",
+ *   "hostname": "example.com"
+ * }
+ */
+declare const _default: any;
+export default _default;

package/dist/runtime/server/api/validate.js

@@ -0,0 +1,22 @@
+import { verifyTurnstileToken } from "../utils/verifyTurnstileToken.js";
+export default defineEventHandler(async (event) => {
+  const body = await readBody(event);
+  if (!body?.token) {
+    throw createError({
+      statusCode: 422,
+      statusMessage: "Token not provided"
+    });
+  }
+  const remoteip = getHeader(event, "cf-connecting-ip") || getHeader(event, "x-forwarded-for")?.split(",")[0] || getHeader(event, "x-real-ip") || void 0;
+  const result = await verifyTurnstileToken(body.token, { remoteip });
+  if (!result.success) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: "Token verification failed",
+      data: {
+        errors: result["error-codes"]
+      }
+    });
+  }
+  return result;
+});

package/dist/runtime/server/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../../.nuxt/tsconfig.server.json",
+}

package/dist/runtime/server/utils/verifyTurnstileToken.d.ts

@@ -0,0 +1,41 @@
+import type { TurnstileVerifyResponse } from '../../types.js';
+/**
+ * Verify a Turnstile token on the server
+ *
+ * @param token - The token from the client-side widget
+ * @param options - Additional verification options
+ * @returns Verification response from Cloudflare
+ *
+ * @example
+ * ```ts
+ * // In your server route
+ * export default defineEventHandler(async (event) => {
+ *   const { token } = await readBody(event)
+ *   const result = await verifyTurnstileToken(token)
+ *
+ *   if (!result.success) {
+ *     throw createError({ statusCode: 400, message: 'Invalid captcha' })
+ *   }
+ *
+ *   // Continue with your logic...
+ * })
+ * ```
+ */
+export declare function verifyTurnstileToken(token: string, options?: {
+    /**
+     * Custom secret key (overrides config)
+     */
+    secretKey?: string;
+    /**
+     * Client's IP address (recommended for security)
+     */
+    remoteip?: string;
+    /**
+     * Expected action (if set during widget render)
+     */
+    action?: string;
+    /**
+     * Expected cData (if set during widget render)
+     */
+    cdata?: string;
+}): Promise<TurnstileVerifyResponse>;

package/dist/runtime/server/utils/verifyTurnstileToken.js

@@ -0,0 +1,53 @@
+const TURNSTILE_VERIFY_URL = "https://challenges.cloudflare.com/turnstile/v0/siteverify";
+export async function verifyTurnstileToken(token, options) {
+  const config = useRuntimeConfig();
+  const secretKey = options?.secretKey || config.turnstile?.secretKey;
+  if (!secretKey) {
+    console.error("[nuxt4-turnstile] No secret key configured for server-side verification");
+    return {
+      success: false,
+      "error-codes": ["missing-secret-key"]
+    };
+  }
+  if (!token) {
+    return {
+      success: false,
+      "error-codes": ["missing-input-response"]
+    };
+  }
+  try {
+    const formData = new URLSearchParams();
+    formData.append("secret", secretKey);
+    formData.append("response", token);
+    if (options?.remoteip) {
+      formData.append("remoteip", options.remoteip);
+    }
+    const response = await fetch(TURNSTILE_VERIFY_URL, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded"
+      },
+      body: formData.toString()
+    });
+    const result = await response.json();
+    if (options?.action && result.action !== options.action) {
+      return {
+        success: false,
+        "error-codes": ["action-mismatch"]
+      };
+    }
+    if (options?.cdata && result.cdata !== options.cdata) {
+      return {
+        success: false,
+        "error-codes": ["cdata-mismatch"]
+      };
+    }
+    return result;
+  } catch (error) {
+    console.error("[nuxt4-turnstile] Verification request failed:", error);
+    return {
+      success: false,
+      "error-codes": ["network-error"]
+    };
+  }
+}

package/dist/runtime/types.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Turnstile Widget Instance
+ */
+export interface TurnstileInstance {
+    /**
+     * Reset the widget to allow re-verification
+     */
+    reset: () => void;
+    /**
+     * Remove the widget from the DOM
+     */
+    remove: () => void;
+    /**
+     * Get the current response token
+     */
+    getResponse: () => string | undefined;
+    /**
+     * Check if the widget is expired
+     */
+    isExpired: () => boolean;
+    /**
+     * Execute the challenge (for invisible mode)
+     */
+    execute: () => void;
+}
+/**
+ * Turnstile Widget Options
+ */
+export interface TurnstileOptions {
+    /**
+     * Site key from Cloudflare dashboard
+     */
+    sitekey: string;
+    /**
+     * Callback when verification succeeds
+     */
+    callback?: (token: string) => void;
+    /**
+     * Callback when token expires
+     */
+    'expired-callback'?: () => void;
+    /**
+     * Callback when error occurs
+     */
+    'error-callback'?: (error: Error) => void;
+    /**
+     * Callback before interactive challenge starts
+     */
+    'before-interactive-callback'?: () => void;
+    /**
+     * Callback after interactive challenge completes
+     */
+    'after-interactive-callback'?: () => void;
+    /**
+     * Callback when widget is unsupported
+     */
+    'unsupported-callback'?: () => void;
+    /**
+     * Widget theme
+     */
+    theme?: 'light' | 'dark' | 'auto';
+    /**
+     * Widget size
+     */
+    size?: 'normal' | 'compact' | 'flexible';
+    /**
+     * Widget appearance
+     */
+    appearance?: 'always' | 'execute' | 'interaction-only';
+    /**
+     * Retry behavior
+     */
+    retry?: 'auto' | 'never';
+    /**
+     * Retry interval in ms
+     */
+    'retry-interval'?: number;
+    /**
+     * Refresh before expiry behavior
+     */
+    'refresh-expired'?: 'auto' | 'manual' | 'never';
+    /**
+     * Language code
+     */
+    language?: string;
+    /**
+     * Custom action for analytics
+     */
+    action?: string;
+    /**
+     * Custom data payload
+     */
+    cData?: string;
+    /**
+     * Response field name for form submission
+     */
+    'response-field'?: boolean;
+    /**
+     * Custom response field name
+     */
+    'response-field-name'?: string;
+}
+/**
+ * Turnstile Verification Response
+ */
+export interface TurnstileVerifyResponse {
+    success: boolean;
+    challenge_ts?: string;
+    hostname?: string;
+    'error-codes'?: string[];
+    action?: string;
+    cdata?: string;
+}
+/**
+ * Cloudflare Turnstile global object
+ */
+export interface TurnstileWindow {
+    turnstile?: {
+        render: (element: string | HTMLElement, options: TurnstileOptions) => string;
+        reset: (widgetId?: string) => void;
+        remove: (widgetId?: string) => void;
+        getResponse: (widgetId?: string) => string | undefined;
+        isExpired: (widgetId?: string) => boolean;
+        execute: (widgetId?: string) => void;
+    };
+}
+declare global {
+    interface Window extends TurnstileWindow {
+    }
+}

package/dist/types.d.mts

@@ -0,0 +1,5 @@
+export { type TurnstileInstance, type TurnstileOptions } from '../dist/runtime/types.js'
+
+export { default } from './module.mjs'
+
+export { type ModuleOptions } from './module.mjs'

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "nuxt4-turnstile",
+  "version": "1.0.0",
+  "description": "Cloudflare Turnstile integration for Nuxt 4 - A privacy-focused CAPTCHA alternative",
+  "repository": "bootssecurity/nuxt4-turnstile",
+  "homepage": "https://github.com/bootssecurity/nuxt4-turnstile",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    }
+  },
+  "main": "./dist/module.mjs",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  },
+  "files": [
+    "dist",
+    "public"
+  ],
+  "scripts": {
+    "prepack": "nuxt-module-build build",
+    "dev": "npm run dev:prepare && nuxi dev playground",
+    "dev:build": "nuxi build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
+    "release": "npm run lint && npm run test && npm run prepack && changelogen --release && npm publish && git push --follow-tags",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
+  },
+  "dependencies": {
+    "@nuxt/kit": "^4.2.2",
+    "defu": "^6.1.4"
+  },
+  "devDependencies": {
+    "@nuxt/devtools": "^3.1.1",
+    "@nuxt/eslint-config": "^1.12.1",
+    "@nuxt/module-builder": "^1.0.2",
+    "@nuxt/schema": "^4.2.2",
+    "@nuxt/test-utils": "^3.23.0",
+    "@types/node": "latest",
+    "changelogen": "^0.6.2",
+    "eslint": "^9.39.2",
+    "nuxt": "^4.2.2",
+    "typescript": "~5.9.3",
+    "vitest": "^4.0.17",
+    "vue-tsc": "^3.2.2"
+  },
+  "keywords": [
+    "nuxt",
+    "nuxt4",
+    "nuxt-module",
+    "cloudflare",
+    "turnstile",
+    "captcha",
+    "security",
+    "bot-protection"
+  ]
+}