@silverassist/recaptcha 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-01-27
+
+### Added
+
+- Initial release of `@silverassist/recaptcha`
+- `RecaptchaWrapper` client component for automatic token generation
+  - Automatic script loading via Next.js `Script` component
+  - Token auto-refresh before expiration (90 seconds default)
+  - Hidden input field for form submission
+  - Configurable callbacks (`onTokenGenerated`, `onError`)
+  - Graceful fallback when not configured
+- `validateRecaptcha` server function for token validation
+  - Google API verification
+  - Score threshold checking
+  - Action verification
+  - Debug logging option
+  - Skip validation when not configured (dev mode)
+- `isRecaptchaEnabled` helper function
+- `getRecaptchaToken` FormData extraction helper
+- Full TypeScript support with exported types
+  - `RecaptchaWrapperProps`
+  - `RecaptchaValidationResult`
+  - `RecaptchaVerifyResponse`
+  - `RecaptchaConfig`
+  - `RecaptchaValidationOptions`
+- Subpath exports for tree-shaking
+  - `@silverassist/recaptcha/client`
+  - `@silverassist/recaptcha/server`
+  - `@silverassist/recaptcha/types`
+  - `@silverassist/recaptcha/constants`
+- Comprehensive test suite with >80% coverage
+- ESM and CommonJS bundle outputs
+
+### Security
+
+- Server-side token validation to prevent client-side bypass
+- Action verification to prevent token reuse across different forms
+- Configurable score thresholds for different risk levels

package/LICENSE

@@ -0,0 +1,135 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software.  Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright SilverAssist (https://silverassist.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization.  **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.
+
+---
+
+Required Notice: Copyright 2026 SilverAssist (https://silverassist.com)

package/README.md

@@ -0,0 +1,240 @@
+# @silverassist/recaptcha
+
+Google reCAPTCHA v3 integration for Next.js applications with Server Actions support.
+
+[![npm version](https://img.shields.io/npm/v/@silverassist/recaptcha.svg)](https://www.npmjs.com/package/@silverassist/recaptcha)
+[![License](https://img.shields.io/badge/license-PolyForm%20Noncommercial-blue.svg)](LICENSE)
+
+## Features
+
+- ✅ **Client Component**: `RecaptchaWrapper` for automatic token generation
+- ✅ **Server Validation**: `validateRecaptcha` function for Server Actions
+- ✅ **TypeScript Support**: Full type definitions included
+- ✅ **Next.js Optimized**: Works with App Router and Server Actions
+- ✅ **Auto Token Refresh**: Tokens refresh automatically before expiration
+- ✅ **Graceful Degradation**: Works in development without credentials
+- ✅ **Configurable Thresholds**: Custom score thresholds per form
+
+## Installation
+
+```bash
+npm install @silverassist/recaptcha
+# or
+yarn add @silverassist/recaptcha
+# or
+pnpm add @silverassist/recaptcha
+```
+
+## Setup
+
+### 1. Get reCAPTCHA Keys
+
+1. Go to [Google reCAPTCHA Admin](https://www.google.com/recaptcha/admin)
+2. Create a new site with reCAPTCHA v3
+3. Get your **Site Key** (public) and **Secret Key** (private)
+
+### 2. Add Environment Variables
+
+```bash
+# .env.local
+NEXT_PUBLIC_RECAPTCHA_SITE_KEY=your_site_key_here
+RECAPTCHA_SECRET_KEY=your_secret_key_here
+```
+
+## Usage
+
+### Client Component
+
+Add `RecaptchaWrapper` inside your form:
+
+```tsx
+"use client";
+
+import { RecaptchaWrapper } from "@silverassist/recaptcha";
+
+export function ContactForm() {
+  return (
+    <form action={submitForm}>
+      <RecaptchaWrapper action="contact_form" />
+      <input name="email" type="email" required />
+      <textarea name="message" required />
+      <button type="submit">Send</button>
+    </form>
+  );
+}
+```
+
+### Server Action
+
+Validate the token in your Server Action:
+
+```ts
+"use server";
+
+import { validateRecaptcha, getRecaptchaToken } from "@silverassist/recaptcha/server";
+
+export async function submitForm(formData: FormData) {
+  // Get and validate reCAPTCHA token
+  const token = getRecaptchaToken(formData);
+  const recaptcha = await validateRecaptcha(token, "contact_form");
+
+  if (!recaptcha.success) {
+    return { success: false, message: recaptcha.error };
+  }
+
+  // Process form data...
+  const email = formData.get("email");
+  const message = formData.get("message");
+
+  // Your form processing logic here
+
+  return { success: true };
+}
+```
+
+## API Reference
+
+### RecaptchaWrapper
+
+Client component that loads reCAPTCHA and generates tokens.
+
+```tsx
+<RecaptchaWrapper
+  action="contact_form"      // Required: action name for analytics
+  inputName="recaptchaToken" // Optional: hidden input name (default: "recaptchaToken")
+  inputId="recaptcha-token"  // Optional: hidden input id
+  siteKey="..."              // Optional: override env variable
+  refreshInterval={90000}    // Optional: token refresh interval in ms (default: 90000)
+  onTokenGenerated={(token) => {}} // Optional: callback when token is generated
+  onError={(error) => {}}    // Optional: callback on error
+/>
+```
+
+### validateRecaptcha
+
+Server-side token validation function.
+
+```ts
+const result = await validateRecaptcha(
+  token,          // Token from form
+  "contact_form", // Expected action (optional)
+  {
+    scoreThreshold: 0.5, // Minimum score (default: 0.5)
+    secretKey: "...",    // Override env variable
+    debug: true,         // Enable debug logging
+  }
+);
+
+// Result type:
+// {
+//   success: boolean,
+//   score: number,
+//   error?: string,
+//   skipped?: boolean,
+//   rawResponse?: RecaptchaVerifyResponse
+// }
+```
+
+### isRecaptchaEnabled
+
+Check if reCAPTCHA is configured.
+
+```ts
+import { isRecaptchaEnabled } from "@silverassist/recaptcha/server";
+
+if (isRecaptchaEnabled()) {
+  // Validate token
+} else {
+  // Skip validation (development)
+}
+```
+
+### getRecaptchaToken
+
+Extract token from FormData.
+
+```ts
+import { getRecaptchaToken } from "@silverassist/recaptcha/server";
+
+const token = getRecaptchaToken(formData);
+const token = getRecaptchaToken(formData, "customFieldName");
+```
+
+## Score Thresholds
+
+reCAPTCHA v3 returns a score from 0.0 to 1.0:
+
+| Score | Meaning |
+|-------|---------|
+| 1.0 | Very likely human |
+| 0.7+ | Likely human |
+| 0.5 | Default threshold |
+| 0.3- | Suspicious |
+| 0.0 | Very likely bot |
+
+Adjust threshold based on form sensitivity:
+
+```ts
+// Standard forms
+await validateRecaptcha(token, "contact", { scoreThreshold: 0.5 });
+
+// Sensitive forms (payments, account creation)
+await validateRecaptcha(token, "payment", { scoreThreshold: 0.7 });
+
+// Low-risk forms (newsletter signup)
+await validateRecaptcha(token, "newsletter", { scoreThreshold: 0.3 });
+```
+
+## Subpath Imports
+
+You can import from specific subpaths for better tree-shaking:
+
+```ts
+// Main exports (client + server + types)
+import { RecaptchaWrapper, validateRecaptcha } from "@silverassist/recaptcha";
+
+// Client only
+import { RecaptchaWrapper } from "@silverassist/recaptcha/client";
+
+// Server only
+import { validateRecaptcha, getRecaptchaToken, isRecaptchaEnabled } from "@silverassist/recaptcha/server";
+
+// Types only
+import type { RecaptchaValidationResult, RecaptchaWrapperProps } from "@silverassist/recaptcha/types";
+
+// Constants only
+import { DEFAULT_SCORE_THRESHOLD, RECAPTCHA_CONFIG } from "@silverassist/recaptcha/constants";
+```
+
+## Development
+
+In development, when `RECAPTCHA_SECRET_KEY` is not set, validation is skipped and forms work normally. This allows testing without reCAPTCHA credentials.
+
+```ts
+const result = await validateRecaptcha(token, "test");
+// Returns: { success: true, score: 1, skipped: true }
+```
+
+## TypeScript
+
+Full TypeScript support with exported types:
+
+```ts
+import type {
+  RecaptchaWrapperProps,
+  RecaptchaValidationResult,
+  RecaptchaVerifyResponse,
+  RecaptchaConfig,
+  RecaptchaValidationOptions,
+} from "@silverassist/recaptcha";
+```
+
+## License
+
+[Polyform Noncommercial License 1.0.0](LICENSE)
+
+## Links
+
+- [GitHub Repository](https://github.com/SilverAssist/recaptcha)
+- [npm Package](https://www.npmjs.com/package/@silverassist/recaptcha)
+- [Google reCAPTCHA v3 Documentation](https://developers.google.com/recaptcha/docs/v3)

package/dist/client/index.d.mts

@@ -0,0 +1,75 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Props for RecaptchaWrapper client component
+ */
+interface RecaptchaWrapperProps {
+    /** Action name for reCAPTCHA analytics (e.g., "contact_form", "signup") */
+    action: string;
+    /** Name attribute for the hidden input (default: "recaptchaToken") */
+    inputName?: string;
+    /** ID attribute for the hidden input */
+    inputId?: string;
+    /** Override site key (default: uses NEXT_PUBLIC_RECAPTCHA_SITE_KEY) */
+    siteKey?: string;
+    /** Token refresh interval in ms (default: 90000 = 90 seconds) */
+    refreshInterval?: number;
+    /** Callback when token is generated */
+    onTokenGenerated?: (token: string) => void;
+    /** Callback when an error occurs */
+    onError?: (error: Error) => void;
+}
+/**
+ * Global window interface extension for reCAPTCHA
+ */
+declare global {
+    interface Window {
+        grecaptcha: {
+            ready: (callback: () => void) => void;
+            execute: (siteKey: string, options: {
+                action: string;
+            }) => Promise<string>;
+        };
+    }
+}
+
+/**
+ * RecaptchaWrapper - Client component for reCAPTCHA v3 integration
+ *
+ * Features:
+ * - Loads reCAPTCHA script automatically
+ * - Generates token when script loads
+ * - Refreshes token periodically (tokens expire after 2 minutes)
+ * - Stores token in hidden input field for form submission
+ * - Graceful fallback when not configured
+ *
+ * @example Basic usage
+ * ```tsx
+ * <form action={formAction}>
+ *   <RecaptchaWrapper action="contact_form" />
+ *   <input name="email" type="email" required />
+ *   <button type="submit">Submit</button>
+ * </form>
+ * ```
+ *
+ * @example Custom input name
+ * ```tsx
+ * <RecaptchaWrapper
+ *   action="signup"
+ *   inputName="captchaToken"
+ *   inputId="signup-captcha"
+ * />
+ * ```
+ *
+ * @example With callbacks
+ * ```tsx
+ * <RecaptchaWrapper
+ *   action="payment"
+ *   onTokenGenerated={(token) => console.log("Token:", token)}
+ *   onError={(error) => console.error("Error:", error)}
+ * />
+ * ```
+ */
+declare function RecaptchaWrapper({ action, inputName, inputId, siteKey: propSiteKey, refreshInterval, onTokenGenerated, onError, }: RecaptchaWrapperProps): react_jsx_runtime.JSX.Element | null;
+
+export { RecaptchaWrapper, RecaptchaWrapper as default };

package/dist/client/index.d.ts

@@ -0,0 +1,75 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Props for RecaptchaWrapper client component
+ */
+interface RecaptchaWrapperProps {
+    /** Action name for reCAPTCHA analytics (e.g., "contact_form", "signup") */
+    action: string;
+    /** Name attribute for the hidden input (default: "recaptchaToken") */
+    inputName?: string;
+    /** ID attribute for the hidden input */
+    inputId?: string;
+    /** Override site key (default: uses NEXT_PUBLIC_RECAPTCHA_SITE_KEY) */
+    siteKey?: string;
+    /** Token refresh interval in ms (default: 90000 = 90 seconds) */
+    refreshInterval?: number;
+    /** Callback when token is generated */
+    onTokenGenerated?: (token: string) => void;
+    /** Callback when an error occurs */
+    onError?: (error: Error) => void;
+}
+/**
+ * Global window interface extension for reCAPTCHA
+ */
+declare global {
+    interface Window {
+        grecaptcha: {
+            ready: (callback: () => void) => void;
+            execute: (siteKey: string, options: {
+                action: string;
+            }) => Promise<string>;
+        };
+    }
+}
+
+/**
+ * RecaptchaWrapper - Client component for reCAPTCHA v3 integration
+ *
+ * Features:
+ * - Loads reCAPTCHA script automatically
+ * - Generates token when script loads
+ * - Refreshes token periodically (tokens expire after 2 minutes)
+ * - Stores token in hidden input field for form submission
+ * - Graceful fallback when not configured
+ *
+ * @example Basic usage
+ * ```tsx
+ * <form action={formAction}>
+ *   <RecaptchaWrapper action="contact_form" />
+ *   <input name="email" type="email" required />
+ *   <button type="submit">Submit</button>
+ * </form>
+ * ```
+ *
+ * @example Custom input name
+ * ```tsx
+ * <RecaptchaWrapper
+ *   action="signup"
+ *   inputName="captchaToken"
+ *   inputId="signup-captcha"
+ * />
+ * ```
+ *
+ * @example With callbacks
+ * ```tsx
+ * <RecaptchaWrapper
+ *   action="payment"
+ *   onTokenGenerated={(token) => console.log("Token:", token)}
+ *   onError={(error) => console.error("Error:", error)}
+ * />
+ * ```
+ */
+declare function RecaptchaWrapper({ action, inputName, inputId, siteKey: propSiteKey, refreshInterval, onTokenGenerated, onError, }: RecaptchaWrapperProps): react_jsx_runtime.JSX.Element | null;
+
+export { RecaptchaWrapper, RecaptchaWrapper as default };

package/dist/client/index.js

@@ -0,0 +1,115 @@
+"use client";
+
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var Script = require('next/script');
+var react = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var Script__default = /*#__PURE__*/_interopDefault(Script);
+
+var DEFAULT_TOKEN_REFRESH_INTERVAL = 9e4;
+var RECAPTCHA_CONFIG = {
+  /** Default token refresh interval */
+  tokenRefreshInterval: DEFAULT_TOKEN_REFRESH_INTERVAL
+};
+function RecaptchaWrapper({
+  action,
+  inputName = "recaptchaToken",
+  inputId = "recaptcha-token",
+  siteKey: propSiteKey,
+  refreshInterval = RECAPTCHA_CONFIG.tokenRefreshInterval,
+  onTokenGenerated,
+  onError
+}) {
+  const siteKey = propSiteKey ?? process.env.NEXT_PUBLIC_RECAPTCHA_SITE_KEY;
+  const tokenInputRef = react.useRef(null);
+  const refreshIntervalRef = react.useRef(null);
+  const executeRecaptcha = react.useCallback(async () => {
+    if (!siteKey) {
+      return;
+    }
+    try {
+      if (typeof window !== "undefined" && window.grecaptcha) {
+        window.grecaptcha.ready(async () => {
+          try {
+            const token = await window.grecaptcha.execute(siteKey, { action });
+            if (tokenInputRef.current) {
+              tokenInputRef.current.value = token;
+            }
+            if (onTokenGenerated) {
+              onTokenGenerated(token);
+            }
+          } catch (error) {
+            console.error("[reCAPTCHA] Error executing reCAPTCHA:", error);
+            if (onError && error instanceof Error) {
+              onError(error);
+            }
+          }
+        });
+      }
+    } catch (error) {
+      console.error("[reCAPTCHA] Error:", error);
+      if (onError && error instanceof Error) {
+        onError(error);
+      }
+    }
+  }, [siteKey, action, onTokenGenerated, onError]);
+  react.useEffect(() => {
+    executeRecaptcha();
+    refreshIntervalRef.current = setInterval(() => {
+      executeRecaptcha();
+    }, refreshInterval);
+    return () => {
+      if (refreshIntervalRef.current) {
+        clearInterval(refreshIntervalRef.current);
+      }
+    };
+  }, [executeRecaptcha, refreshInterval]);
+  if (!siteKey) {
+    if (process.env.NODE_ENV === "development") {
+      console.warn(
+        "[reCAPTCHA] Site key not configured. Set NEXT_PUBLIC_RECAPTCHA_SITE_KEY environment variable."
+      );
+    }
+    return null;
+  }
+  return /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+    /* @__PURE__ */ jsxRuntime.jsx(
+      "input",
+      {
+        ref: tokenInputRef,
+        type: "hidden",
+        name: inputName,
+        id: inputId,
+        "data-testid": "recaptcha-token-input"
+      }
+    ),
+    /* @__PURE__ */ jsxRuntime.jsx(
+      Script__default.default,
+      {
+        src: `https://www.google.com/recaptcha/api.js?render=${siteKey}`,
+        strategy: "afterInteractive",
+        onLoad: () => {
+          executeRecaptcha();
+        },
+        onError: () => {
+          console.error("[reCAPTCHA] Failed to load reCAPTCHA script");
+          if (onError) {
+            onError(new Error("Failed to load reCAPTCHA script"));
+          }
+        }
+      }
+    )
+  ] });
+}
+var client_default = RecaptchaWrapper;
+
+exports.RecaptchaWrapper = RecaptchaWrapper;
+exports.default = client_default;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map