@nauth-toolkit/recaptcha 0.1.92

package/dist/src/providers/recaptcha-v3.provider.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RecaptchaV3Provider = void 0;
+/**
+ * Google reCAPTCHA v3 Provider
+ *
+ * Implements invisible, score-based bot detection without user interaction.
+ * Returns a risk score (0.0 - 1.0) indicating likelihood of bot activity.
+ *
+ * v3 is recommended for most web applications as it provides better UX
+ * by not requiring user interaction while still detecting bots effectively.
+ *
+ * @example
+ * ```typescript
+ * const provider = new RecaptchaV3Provider({
+ *   secretKey: process.env.RECAPTCHA_SECRET_KEY!,
+ * });
+ *
+ * const result = await provider.verify(token, clientIp, 'login');
+ *
+ * if (!result.success) {
+ *   throw new Error('reCAPTCHA validation failed');
+ * }
+ *
+ * if (result.score && result.score < 0.5) {
+ *   throw new Error('Suspicious activity detected');
+ * }
+ * ```
+ */
+class RecaptchaV3Provider {
+    secretKey;
+    verifyUrl;
+    timeout;
+    constructor(config) {
+        this.secretKey = config.secretKey;
+        this.verifyUrl = config.verifyUrl || 'https://www.google.com/recaptcha/api/siteverify';
+        this.timeout = config.timeout || 10000;
+    }
+    /**
+     * Verify reCAPTCHA v3 token with Google's API
+     *
+     * @param token - Token from client
+     * @param remoteIp - Client IP address (optional but recommended)
+     * @param action - Action name used when generating token (e.g., 'login', 'signup')
+     * @returns Verification result with score
+     *
+     * @throws Error if network request fails or times out
+     */
+    async verify(token, remoteIp, _action) {
+        // Build request body
+        const params = new URLSearchParams({
+            secret: this.secretKey,
+            response: token,
+        });
+        if (remoteIp) {
+            params.append('remoteip', remoteIp);
+        }
+        try {
+            // Create abort controller for timeout
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+            // Make request to Google's API
+            const response = await fetch(this.verifyUrl, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                },
+                body: params.toString(),
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+                throw new Error(`reCAPTCHA API returned status ${response.status}`);
+            }
+            const data = await response.json();
+            // Map Google's response to our interface
+            return {
+                success: data.success === true,
+                score: data.score,
+                action: data.action,
+                hostname: data.hostname,
+                errorCodes: data['error-codes'],
+            };
+        }
+        catch (error) {
+            // Handle network errors
+            if (error instanceof Error) {
+                if (error.name === 'AbortError') {
+                    throw new Error(`reCAPTCHA verification timeout after ${this.timeout}ms`);
+                }
+                throw new Error(`reCAPTCHA verification failed: ${error.message}`);
+            }
+            throw new Error('reCAPTCHA verification failed with unknown error');
+        }
+    }
+}
+exports.RecaptchaV3Provider = RecaptchaV3Provider;
+//# sourceMappingURL=recaptcha-v3.provider.js.map

package/dist/src/providers/recaptcha-v3.provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recaptcha-v3.provider.js","sourceRoot":"","sources":["../../../src/providers/recaptcha-v3.provider.ts"],"names":[],"mappings":";;;AA2BA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAa,mBAAmB;IACb,SAAS,CAAS;IAClB,SAAS,CAAS;IAClB,OAAO,CAAS;IAEjC,YAAY,MAAyB;QACnC,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;QAClC,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,iDAAiD,CAAC;QACvF,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,KAAK,CAAC;IACzC,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,QAAiB,EAAE,OAAgB;QAC7D,qBAAqB;QACrB,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC;YACjC,MAAM,EAAE,IAAI,CAAC,SAAS;YACtB,QAAQ,EAAE,KAAK;SAChB,CAAC,CAAC;QAEH,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;QACtC,CAAC;QAED,IAAI,CAAC;YACH,sCAAsC;YACtC,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;YACzC,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;YAErE,+BAA+B;YAC/B,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE;gBAC3C,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,cAAc,EAAE,mCAAmC;iBACpD;gBACD,IAAI,EAAE,MAAM,CAAC,QAAQ,EAAE;gBACvB,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;YAEH,YAAY,CAAC,SAAS,CAAC,CAAC;YAExB,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,IAAI,KAAK,CAAC,iCAAiC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;YACtE,CAAC;YAED,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YAEnC,yCAAyC;YACzC,OAAO;gBACL,OAAO,EAAE,IAAI,CAAC,OAAO,KAAK,IAAI;gBAC9B,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,UAAU,EAAE,IAAI,CAAC,aAAa,CAAC;aAChC,CAAC;QACJ,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,wBAAwB;YACxB,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;gBAC3B,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;oBAChC,MAAM,IAAI,KAAK,CAAC,wCAAwC,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC;gBAC5E,CAAC;gBACD,MAAM,IAAI,KAAK,CAAC,kCAAkC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YACrE,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;QACtE,CAAC;IACH,CAAC;CACF;AA1ED,kDA0EC"}

package/dist/src/recaptcha-provider.interface.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Google reCAPTCHA provider interface
+ *
+ * Supports v2, v3, and Enterprise versions of Google reCAPTCHA.
+ * Implementations should handle token verification with Google's API.
+ *
+ * @example
+ * ```typescript
+ * const provider = new RecaptchaV3Provider({ secretKey: 'your-secret' });
+ * const result = await provider.verify(token, clientIp, 'login');
+ * if (result.success) {
+ *   console.log('Valid token');
+ * }
+ * ```
+ */
+export interface RecaptchaProvider {
+    /**
+     * Verify reCAPTCHA token with Google's API
+     *
+     * @param token - Token from client (generated by Google reCAPTCHA)
+     * @param remoteIp - Client IP address (optional but recommended for security)
+     * @param action - Action name for v3/Enterprise (e.g., 'login', 'signup')
+     * @returns Verification result with score (v3/Enterprise) or success (v2)
+     *
+     * @example
+     * ```typescript
+     * const result = await provider.verify(
+     *   'token-from-client',
+     *   '192.168.1.1',
+     *   'login'
+     * );
+     * ```
+     */
+    verify(token: string, remoteIp?: string, action?: string): Promise<RecaptchaVerificationResult>;
+}
+/**
+ * Result of reCAPTCHA token verification
+ *
+ * Different fields are populated depending on reCAPTCHA version:
+ * - v2: success, challengeTs, hostname
+ * - v3: success, score, action, hostname
+ * - Enterprise: success, score, action, hostname
+ */
+export interface RecaptchaVerificationResult {
+    /**
+     * Whether the token is valid
+     */
+    success: boolean;
+    /**
+     * Risk score for v3/Enterprise (0.0 - 1.0)
+     *
+     * - 0.0: Very likely a bot
+     * - 1.0: Very likely a human
+     * - Not present for v2
+     */
+    score?: number;
+    /**
+     * Action name that was verified (v3/Enterprise only)
+     */
+    action?: string;
+    /**
+     * Timestamp of the challenge load (v2 only)
+     * ISO 8601 format
+     */
+    challengeTs?: string;
+    /**
+     * Hostname of the site where the reCAPTCHA was solved
+     */
+    hostname?: string;
+    /**
+     * Error codes returned by Google (if any)
+     *
+     * Common errors:
+     * - missing-input-secret: Secret key is missing
+     * - invalid-input-secret: Secret key is invalid
+     * - missing-input-response: Token is missing
+     * - invalid-input-response: Token is invalid or expired
+     * - timeout-or-duplicate: Token has been used or expired
+     */
+    errorCodes?: string[];
+}
+//# sourceMappingURL=recaptcha-provider.interface.d.ts.map

package/dist/src/recaptcha-provider.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recaptcha-provider.interface.d.ts","sourceRoot":"","sources":["../../src/recaptcha-provider.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAAC;CACjG;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB"}

package/dist/src/recaptcha-provider.interface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=recaptcha-provider.interface.js.map

package/dist/src/recaptcha-provider.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recaptcha-provider.interface.js","sourceRoot":"","sources":["../../src/recaptcha-provider.interface.ts"],"names":[],"mappings":""}