memory-journal-mcp 7.7.1 → 8.0.0

package/skills/cloudflare/references/turnstile/api.md

@@ -0,0 +1,253 @@
+# API Reference
+
+## Client-Side JavaScript API
+
+The Turnstile JavaScript API is available at `window.turnstile` after loading the script.
+
+### `turnstile.render(container, options)`
+
+Renders a Turnstile widget into a container element.
+
+**Parameters:**
+
+- `container` (string | HTMLElement): CSS selector or DOM element
+- `options` (TurnstileOptions): Configuration object (see [configuration.md](configuration.md))
+
+**Returns:** `string` - Widget ID for use with other API methods
+
+**Example:**
+
+```javascript
+const widgetId = window.turnstile.render('#my-container', {
+  sitekey: 'YOUR_SITE_KEY',
+  callback: (token) => console.log('Success:', token),
+  'error-callback': (code) => console.error('Error:', code),
+})
+```
+
+### `turnstile.reset(widgetId)`
+
+Resets a widget (clears token, resets challenge state). Useful when form validation fails.
+
+**Parameters:**
+
+- `widgetId` (string): Widget ID from `render()`, or container element
+
+**Returns:** `void`
+
+**Example:**
+
+```javascript
+// Reset on form error
+if (!validateForm()) {
+  window.turnstile.reset(widgetId)
+}
+```
+
+### `turnstile.remove(widgetId)`
+
+Removes a widget from the DOM completely.
+
+**Parameters:**
+
+- `widgetId` (string): Widget ID from `render()`
+
+**Returns:** `void`
+
+**Example:**
+
+```javascript
+// Cleanup on navigation
+window.turnstile.remove(widgetId)
+```
+
+### `turnstile.getResponse(widgetId)`
+
+Gets the current token from a widget (if challenge completed).
+
+**Parameters:**
+
+- `widgetId` (string): Widget ID from `render()`, or container element
+
+**Returns:** `string | undefined` - Token string, or undefined if not ready
+
+**Example:**
+
+```javascript
+const token = window.turnstile.getResponse(widgetId)
+if (token) {
+  submitForm(token)
+}
+```
+
+### `turnstile.isExpired(widgetId)`
+
+Checks if a widget's token has expired (>5 minutes old).
+
+**Parameters:**
+
+- `widgetId` (string): Widget ID from `render()`
+
+**Returns:** `boolean` - True if expired
+
+**Example:**
+
+```javascript
+if (window.turnstile.isExpired(widgetId)) {
+  window.turnstile.reset(widgetId)
+}
+```
+
+## Callback Signatures
+
+```typescript
+type TurnstileCallback = (token: string) => void
+type ErrorCallback = (errorCode: string) => void
+type TimeoutCallback = () => void
+type ExpiredCallback = () => void
+type BeforeInteractiveCallback = () => void
+type AfterInteractiveCallback = () => void
+type UnsupportedCallback = () => void
+```
+
+## Siteverify API (Server-Side)
+
+**Endpoint:** `https://challenges.cloudflare.com/turnstile/v0/siteverify`
+
+### Request
+
+**Method:** POST  
+**Content-Type:** `application/json` or `application/x-www-form-urlencoded`
+
+```typescript
+interface SiteverifyRequest {
+  secret: string // Your secret key (never expose client-side)
+  response: string // Token from cf-turnstile-response
+  remoteip?: string // User's IP (optional but recommended)
+  idempotency_key?: string // Unique key for idempotent validation
+}
+```
+
+**Example:**
+
+```javascript
+// Cloudflare Workers
+const result = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    secret: env.TURNSTILE_SECRET,
+    response: token,
+    remoteip: request.headers.get('CF-Connecting-IP'),
+  }),
+})
+const data = await result.json()
+```
+
+### Response
+
+```typescript
+interface SiteverifyResponse {
+  success: boolean // Validation result
+  challenge_ts?: string // ISO timestamp of challenge
+  hostname?: string // Hostname where widget was solved
+  'error-codes'?: string[] // Error codes if success=false
+  action?: string // Action name from widget config
+  cdata?: string // Custom data from widget config
+}
+```
+
+**Example Success:**
+
+```json
+{
+  "success": true,
+  "challenge_ts": "2024-01-15T10:30:00Z",
+  "hostname": "example.com",
+  "action": "login",
+  "cdata": "user123"
+}
+```
+
+**Example Failure:**
+
+```json
+{
+  "success": false,
+  "error-codes": ["timeout-or-duplicate"]
+}
+```
+
+## Error Codes
+
+| Code                     | Cause                           | Solution                          |
+| ------------------------ | ------------------------------- | --------------------------------- |
+| `missing-input-secret`   | Secret key not provided         | Include `secret` in request       |
+| `invalid-input-secret`   | Secret key is wrong             | Check secret key in dashboard     |
+| `missing-input-response` | Token not provided              | Include `response` token          |
+| `invalid-input-response` | Token is invalid/malformed      | Verify token from widget          |
+| `timeout-or-duplicate`   | Token expired (>5min) or reused | Generate new token, validate once |
+| `internal-error`         | Cloudflare server error         | Retry with exponential backoff    |
+| `bad-request`            | Malformed request               | Check JSON/form encoding          |
+
+## TypeScript Types
+
+```typescript
+interface TurnstileOptions {
+  sitekey: string
+  action?: string
+  cData?: string
+  callback?: (token: string) => void
+  'error-callback'?: (errorCode: string) => void
+  'expired-callback'?: () => void
+  'timeout-callback'?: () => void
+  'before-interactive-callback'?: () => void
+  'after-interactive-callback'?: () => void
+  'unsupported-callback'?: () => void
+  theme?: 'light' | 'dark' | 'auto'
+  size?: 'normal' | 'compact' | 'flexible'
+  tabindex?: number
+  'response-field'?: boolean
+  'response-field-name'?: string
+  retry?: 'auto' | 'never'
+  'retry-interval'?: number
+  language?: string
+  execution?: 'render' | 'execute'
+  appearance?: 'always' | 'execute' | 'interaction-only'
+  'refresh-expired'?: 'auto' | 'manual' | 'never'
+}
+
+interface Turnstile {
+  render(container: string | HTMLElement, options: TurnstileOptions): string
+  reset(widgetId: string): void
+  remove(widgetId: string): void
+  getResponse(widgetId: string): string | undefined
+  isExpired(widgetId: string): boolean
+  execute(container?: string | HTMLElement, options?: TurnstileOptions): void
+}
+
+declare global {
+  interface Window {
+    turnstile: Turnstile
+    onloadTurnstileCallback?: () => void
+  }
+}
+```
+
+## Script Loading
+
+```html
+<!-- Standard -->
+<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
+
+<!-- Explicit render mode -->
+<script src="https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit"></script>
+
+<!-- With load callback -->
+<script src="https://challenges.cloudflare.com/turnstile/v0/api.js?onload=onloadTurnstileCallback"></script>
+<script>
+  window.onloadTurnstileCallback = () => {
+    window.turnstile.render('#container', { sitekey: 'YOUR_SITE_KEY' })
+  }
+</script>
+```

package/skills/cloudflare/references/turnstile/configuration.md

@@ -0,0 +1,242 @@
+# Configuration
+
+## Script Loading
+
+### Basic (Implicit Rendering)
+
+```html
+<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
+```
+
+Automatically renders widgets with `class="cf-turnstile"` on page load.
+
+### Explicit Rendering
+
+```html
+<script src="https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit"></script>
+```
+
+Manual control over when/where widgets render via `window.turnstile.render()`.
+
+### With Load Callback
+
+```html
+<script src="https://challenges.cloudflare.com/turnstile/v0/api.js?onload=myCallback"></script>
+<script>
+  function myCallback() {
+    // API ready
+    window.turnstile.render('#container', { sitekey: 'YOUR_SITE_KEY' })
+  }
+</script>
+```
+
+### Compatibility Mode
+
+```html
+<script src="https://challenges.cloudflare.com/turnstile/v0/api.js?compat=recaptcha"></script>
+```
+
+Provides `grecaptcha` API for Google reCAPTCHA drop-in replacement.
+
+## Widget Configuration
+
+### Complete Options Object
+
+```javascript
+{
+  // Required
+  sitekey: 'YOUR_SITE_KEY',        // Widget sitekey from dashboard
+
+  // Callbacks
+  callback: (token) => {},          // Success - token ready
+  'error-callback': (code) => {},   // Error occurred
+  'expired-callback': () => {},     // Token expired (>5min)
+  'timeout-callback': () => {},     // Challenge timeout
+  'before-interactive-callback': () => {}, // Before showing checkbox
+  'after-interactive-callback': () => {},  // After user interacts
+  'unsupported-callback': () => {}, // Browser doesn't support Turnstile
+
+  // Appearance
+  theme: 'auto',                    // 'light' | 'dark' | 'auto'
+  size: 'normal',                   // 'normal' | 'compact' | 'flexible'
+  tabindex: 0,                      // Tab order (accessibility)
+  language: 'auto',                 // ISO 639-1 code or 'auto'
+
+  // Behavior
+  execution: 'render',              // 'render' (auto) | 'execute' (manual)
+  appearance: 'always',             // 'always' | 'execute' | 'interaction-only'
+  retry: 'auto',                    // 'auto' | 'never'
+  'retry-interval': 8000,           // Retry interval (ms), default 8000
+  'refresh-expired': 'auto',        // 'auto' | 'manual' | 'never'
+
+  // Form Integration
+  'response-field': true,           // Add hidden input (default: true)
+  'response-field-name': 'cf-turnstile-response', // Hidden input name
+
+  // Analytics & Data
+  action: 'login',                  // Action name (for analytics)
+  cData: 'user-session-123',        // Custom data (returned in siteverify)
+}
+```
+
+### Key Options Explained
+
+**`execution`:**
+
+- `'render'` (default): Challenge starts immediately on render
+- `'execute'`: Wait for `turnstile.execute()` call
+
+**`appearance`:**
+
+- `'always'` (default): Widget always visible
+- `'execute'`: Hidden until `execute()` called
+- `'interaction-only'`: Hidden until user interaction needed
+
+**`refresh-expired`:**
+
+- `'auto'` (default): Auto-refresh expired tokens
+- `'manual'`: App must call `reset()` after expiry
+- `'never'`: No refresh, expired-callback triggered
+
+**`retry`:**
+
+- `'auto'` (default): Auto-retry failed challenges
+- `'never'`: Don't retry, trigger error-callback
+
+## HTML Data Attributes
+
+For implicit rendering, use data attributes on `<div class="cf-turnstile">`:
+
+| JavaScript Property   | HTML Data Attribute        | Example                              |
+| --------------------- | -------------------------- | ------------------------------------ |
+| `sitekey`             | `data-sitekey`             | `data-sitekey="YOUR_KEY"`            |
+| `action`              | `data-action`              | `data-action="login"`                |
+| `cData`               | `data-cdata`               | `data-cdata="session-123"`           |
+| `callback`            | `data-callback`            | `data-callback="onSuccess"`          |
+| `error-callback`      | `data-error-callback`      | `data-error-callback="onError"`      |
+| `expired-callback`    | `data-expired-callback`    | `data-expired-callback="onExpired"`  |
+| `timeout-callback`    | `data-timeout-callback`    | `data-timeout-callback="onTimeout"`  |
+| `theme`               | `data-theme`               | `data-theme="dark"`                  |
+| `size`                | `data-size`                | `data-size="compact"`                |
+| `tabindex`            | `data-tabindex`            | `data-tabindex="0"`                  |
+| `response-field`      | `data-response-field`      | `data-response-field="false"`        |
+| `response-field-name` | `data-response-field-name` | `data-response-field-name="token"`   |
+| `retry`               | `data-retry`               | `data-retry="never"`                 |
+| `retry-interval`      | `data-retry-interval`      | `data-retry-interval="5000"`         |
+| `language`            | `data-language`            | `data-language="en"`                 |
+| `execution`           | `data-execution`           | `data-execution="execute"`           |
+| `appearance`          | `data-appearance`          | `data-appearance="interaction-only"` |
+| `refresh-expired`     | `data-refresh-expired`     | `data-refresh-expired="manual"`      |
+
+**Example:**
+
+```html
+<div
+  class="cf-turnstile"
+  data-sitekey="YOUR_SITE_KEY"
+  data-theme="dark"
+  data-callback="onTurnstileSuccess"
+  data-error-callback="onTurnstileError"
+></div>
+```
+
+## Content Security Policy
+
+Add these directives to CSP header/meta tag:
+
+```
+script-src https://challenges.cloudflare.com;
+frame-src https://challenges.cloudflare.com;
+```
+
+**Full Example:**
+
+```html
+<meta
+  http-equiv="Content-Security-Policy"
+  content="default-src 'self'; 
+               script-src 'self' https://challenges.cloudflare.com; 
+               frame-src https://challenges.cloudflare.com;"
+/>
+```
+
+## Framework-Specific Setup
+
+### React
+
+```bash
+npm install @marsidev/react-turnstile
+```
+
+```jsx
+import Turnstile from '@marsidev/react-turnstile'
+;<Turnstile siteKey="YOUR_SITE_KEY" onSuccess={(token) => console.log(token)} />
+```
+
+### Vue
+
+```bash
+npm install vue-turnstile
+```
+
+```vue
+<template>
+  <VueTurnstile site-key="YOUR_SITE_KEY" @success="onSuccess" />
+</template>
+<script setup>
+import VueTurnstile from 'vue-turnstile'
+</script>
+```
+
+### Svelte
+
+```bash
+npm install svelte-turnstile
+```
+
+```svelte
+<script>
+import Turnstile from 'svelte-turnstile';
+</script>
+<Turnstile siteKey="YOUR_SITE_KEY" on:turnstile-callback={handleToken} />
+```
+
+### Next.js (App Router)
+
+```tsx
+// app/components/TurnstileWidget.tsx
+'use client'
+import { useEffect, useRef } from 'react'
+
+export default function TurnstileWidget({ sitekey, onSuccess }) {
+  const ref = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    if (ref.current && window.turnstile) {
+      const widgetId = window.turnstile.render(ref.current, {
+        sitekey,
+        callback: onSuccess,
+      })
+      return () => window.turnstile.remove(widgetId)
+    }
+  }, [sitekey, onSuccess])
+
+  return <div ref={ref} />
+}
+```
+
+## Cloudflare Pages Plugin
+
+```bash
+npm install @cloudflare/pages-plugin-turnstile
+```
+
+```typescript
+// functions/_middleware.ts
+import turnstilePlugin from '@cloudflare/pages-plugin-turnstile'
+
+export const onRequest = turnstilePlugin({
+  secret: 'YOUR_SECRET_KEY',
+  onError: () => new Response('CAPTCHA failed', { status: 403 }),
+})
+```