@prosopo/better-auth-procaptcha-plugin 0.0.0-stage → 0.0.0

package/dist/esm/siteverify.js

@@ -0,0 +1,68 @@
+import { DEFAULT_TIMEOUT_MS, PROCAPTCHA_SITEVERIFY_URL } from "./constants.js";
+//#region src/siteverify.ts
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var isSiteVerifyResponse = (value) => isRecord(value) && typeof value.status === "string" && typeof value.verified === "boolean" && (value.score === void 0 || typeof value.score === "number") && (value.reason === void 0 || typeof value.reason === "string");
+var isSiteVerifyErrorResponse = (value) => isRecord(value) && isRecord(value.error) && typeof value.error.key === "string";
+var readJson = async (response) => {
+	try {
+		return await response.json();
+	} catch {
+		return;
+	}
+};
+var isTransientStatus = (status) => status === 429 || status >= 500;
+var verifyProcaptchaToken = async ({ secretKey, token, ip, email, siteVerifyURL = PROCAPTCHA_SITEVERIFY_URL, timeoutMs = DEFAULT_TIMEOUT_MS, fetch: fetchImpl = fetch }) => {
+	const body = {
+		secret: secretKey,
+		token,
+		...ip ? { ip } : {},
+		...email ? { email } : {}
+	};
+	let response;
+	try {
+		response = await fetchImpl(siteVerifyURL, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				Accept: "application/json"
+			},
+			body: JSON.stringify(body),
+			signal: AbortSignal.timeout(timeoutMs)
+		});
+	} catch (error) {
+		return {
+			outcome: "error",
+			transient: true,
+			message: error instanceof Error ? error.message : String(error)
+		};
+	}
+	const payload = await readJson(response);
+	if (!response.ok) {
+		const errorBody = isSiteVerifyErrorResponse(payload) ? payload.error : void 0;
+		return {
+			outcome: "error",
+			transient: isTransientStatus(response.status),
+			status: response.status,
+			...errorBody ? { key: errorBody.key } : {},
+			message: typeof errorBody?.message === "string" ? errorBody.message : `siteverify responded with HTTP ${response.status}`
+		};
+	}
+	if (!isSiteVerifyResponse(payload)) return {
+		outcome: "error",
+		transient: true,
+		status: response.status,
+		message: "siteverify returned an unexpected response body"
+	};
+	const score = payload.score === void 0 ? {} : { score: payload.score };
+	if (!payload.verified) return {
+		outcome: "rejected",
+		...payload.reason ? { reason: payload.reason } : {},
+		...score
+	};
+	return {
+		outcome: "verified",
+		...score
+	};
+};
+//#endregion
+export { verifyProcaptchaToken };

package/dist/types/client.d.ts

@@ -0,0 +1,19 @@
+import type { procaptcha } from "./index.js";
+export interface ProcaptchaClientOptions {
+    getToken?: () => string | undefined | Promise<string | undefined>;
+    endpoints?: readonly string[];
+    headerName?: string;
+}
+export declare const procaptchaHeaders: (token: string, headerName?: string) => Record<string, string>;
+export declare const procaptchaClient: (options?: ProcaptchaClientOptions) => {
+    id: "procaptcha";
+    $InferServerPlugin: ReturnType<typeof procaptcha>;
+    fetchPlugins: {
+        id: string;
+        name: string;
+        hooks: {
+            onRequest: <T extends Record<string, any>>(context: import("better-auth/client").RequestContext<T>) => Promise<import("better-auth/client").RequestContext<T>>;
+        };
+    }[];
+};
+//# sourceMappingURL=client.d.ts.map

package/dist/types/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C,MAAM,WAAW,uBAAuB;IAMvC,QAAQ,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAElE,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAE9B,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,iBAAiB,UACtB,MAAM,eACD,MAAM,KAChB,MAAM,CAAC,MAAM,EAAE,MAAM,CAA8B,CAAC;AAQvD,eAAO,MAAM,gBAAgB,aAAa,uBAAuB;;wBASrC,UAAU,CAAC,OAAO,UAAU,CAAC;;;;;;;;CAyBxD,CAAC"}

package/dist/types/constants.d.ts

@@ -0,0 +1,12 @@
+export declare const PROCAPTCHA_SITEVERIFY_URL = "https://api.prosopo.io/siteverify";
+export declare const PROCAPTCHA_HEADER = "x-captcha-response";
+export declare const DEFAULT_ENDPOINTS: readonly string[];
+export declare const DEFAULT_TIMEOUT_MS = 10000;
+export declare const PROCAPTCHA_ERROR_CODES: {
+    PROCAPTCHA_MISSING_RESPONSE: import("better-auth").RawError<"PROCAPTCHA_MISSING_RESPONSE">;
+    PROCAPTCHA_VERIFICATION_FAILED: import("better-auth").RawError<"PROCAPTCHA_VERIFICATION_FAILED">;
+    PROCAPTCHA_SERVICE_UNAVAILABLE: import("better-auth").RawError<"PROCAPTCHA_SERVICE_UNAVAILABLE">;
+    PROCAPTCHA_UNKNOWN_ERROR: import("better-auth").RawError<"PROCAPTCHA_UNKNOWN_ERROR">;
+};
+export type ProcaptchaErrorCode = keyof typeof PROCAPTCHA_ERROR_CODES;
+//# sourceMappingURL=constants.d.ts.map

package/dist/types/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAeA,eAAO,MAAM,yBAAyB,sCAAsC,CAAC;AAE7E,eAAO,MAAM,iBAAiB,uBAAuB,CAAC;AAEtD,eAAO,MAAM,iBAAiB,EAAE,SAAS,MAAM,EAI9C,CAAC;AAEF,eAAO,MAAM,kBAAkB,QAAS,CAAC;AAEzC,eAAO,MAAM,sBAAsB;;;;;CAKjC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,MAAM,OAAO,sBAAsB,CAAC"}

package/dist/types/index.d.ts

@@ -0,0 +1,28 @@
+import type { AuthContext } from "better-auth";
+export { DEFAULT_ENDPOINTS, PROCAPTCHA_ERROR_CODES, PROCAPTCHA_HEADER, PROCAPTCHA_SITEVERIFY_URL, type ProcaptchaErrorCode, } from "./constants.js";
+export { verifyProcaptchaToken, type SiteVerifyErrorResponse, type SiteVerifyRequestBody, type SiteVerifyResponse, type VerifyResult, type VerifyTokenParams, } from "./siteverify.js";
+export interface ProcaptchaOptions {
+    secretKey: string;
+    endpoints?: readonly string[];
+    siteVerifyURL?: string;
+    headerName?: string;
+    sendIP?: boolean;
+    sendEmailDomain?: boolean;
+    maxScore?: number;
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+}
+export declare const procaptcha: (options: ProcaptchaOptions) => {
+    id: "procaptcha";
+    $ERROR_CODES: {
+        PROCAPTCHA_MISSING_RESPONSE: import("better-auth").RawError<"PROCAPTCHA_MISSING_RESPONSE">;
+        PROCAPTCHA_VERIFICATION_FAILED: import("better-auth").RawError<"PROCAPTCHA_VERIFICATION_FAILED">;
+        PROCAPTCHA_SERVICE_UNAVAILABLE: import("better-auth").RawError<"PROCAPTCHA_SERVICE_UNAVAILABLE">;
+        PROCAPTCHA_UNKNOWN_ERROR: import("better-auth").RawError<"PROCAPTCHA_UNKNOWN_ERROR">;
+    };
+    onRequest: (request: Request, ctx: AuthContext) => Promise<{
+        response: Response;
+    } | undefined>;
+    options: ProcaptchaOptions;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EACX,WAAW,EAGX,MAAM,aAAa,CAAC;AAarB,OAAO,EACN,iBAAiB,EACjB,sBAAsB,EACtB,iBAAiB,EACjB,yBAAyB,EACzB,KAAK,mBAAmB,GACxB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACN,qBAAqB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,iBAAiB,GACtB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,iBAAiB;IAEjC,SAAS,EAAE,MAAM,CAAC;IAOlB,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAE9B,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,UAAU,CAAC,EAAE,MAAM,CAAC;IAOpB,MAAM,CAAC,EAAE,OAAO,CAAC;IAOjB,eAAe,CAAC,EAAE,OAAO,CAAC;IAM1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACrB;AA8CD,eAAO,MAAM,UAAU,YAAa,iBAAiB;;;;;;;;yBAUzC,OAAO,OACX,WAAW,KACd,OAAO,CAAC;QAAE,QAAQ,EAAE,QAAQ,CAAA;KAAE,GAAG,SAAS,CAAC;;CAgE/C,CAAC"}

package/dist/types/path.d.ts

@@ -0,0 +1,4 @@
+export declare const normalizeAuthPath: (pathname: string, basePath: string) => string;
+export type PathMatcher = (path: string) => boolean;
+export declare const createPathMatcher: (endpoints: readonly string[]) => PathMatcher;
+//# sourceMappingURL=path.d.ts.map

package/dist/types/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../src/path.ts"],"names":[],"mappings":"AAaA,eAAO,MAAM,iBAAiB,aACnB,MAAM,YACN,MAAM,KACd,MAOF,CAAC;AAoDF,MAAM,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;AAEpD,eAAO,MAAM,iBAAiB,cAClB,SAAS,MAAM,EAAE,KAC1B,WAUF,CAAC"}

package/dist/types/siteverify.d.ts

@@ -0,0 +1,40 @@
+import type { VerificationResponse } from "@prosopo/types";
+export interface SiteVerifyRequestBody {
+    secret: string;
+    token: string;
+    ip?: string;
+    email?: string;
+}
+export type SiteVerifyResponse = Omit<VerificationResponse, "error" | "sessionId">;
+export interface SiteVerifyErrorResponse {
+    error: {
+        code: number;
+        key: string;
+        message: string | unknown[];
+    };
+}
+export type VerifyResult = {
+    outcome: "verified";
+    score?: number;
+} | {
+    outcome: "rejected";
+    reason?: string;
+    score?: number;
+} | {
+    outcome: "error";
+    transient: boolean;
+    status?: number;
+    key?: string;
+    message: string;
+};
+export interface VerifyTokenParams {
+    secretKey: string;
+    token: string;
+    ip?: string;
+    email?: string;
+    siteVerifyURL?: string;
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+}
+export declare const verifyProcaptchaToken: ({ secretKey, token, ip, email, siteVerifyURL, timeoutMs, fetch: fetchImpl, }: VerifyTokenParams) => Promise<VerifyResult>;
+//# sourceMappingURL=siteverify.d.ts.map

package/dist/types/siteverify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"siteverify.d.ts","sourceRoot":"","sources":["../../src/siteverify.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAG3D,MAAM,WAAW,qBAAqB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,kBAAkB,GAAG,IAAI,CACpC,oBAAoB,EACpB,OAAO,GAAG,WAAW,CACrB,CAAC;AAEF,MAAM,WAAW,uBAAuB;IACvC,KAAK,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,GAAG,EAAE,MAAM,CAAC;QACZ,OAAO,EAAE,MAAM,GAAG,OAAO,EAAE,CAAC;KAC5B,CAAC;CACF;AAED,MAAM,MAAM,YAAY,GACrB;IAAE,OAAO,EAAE,UAAU,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,OAAO,EAAE,UAAU,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACxD;IACA,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACf,CAAC;AAEL,MAAM,WAAW,iBAAiB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACrB;AA+BD,eAAO,MAAM,qBAAqB,iFAQ/B,iBAAiB,KAAG,OAAO,CAAC,YAAY,CA+D1C,CAAC"}

package/dist/types/tests/client.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=client.unit.test.d.ts.map

package/dist/types/tests/client.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.unit.test.d.ts","sourceRoot":"","sources":["../../../src/tests/client.unit.test.ts"],"names":[],"mappings":""}

package/dist/types/tests/path.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=path.unit.test.d.ts.map

package/dist/types/tests/path.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.unit.test.d.ts","sourceRoot":"","sources":["../../../src/tests/path.unit.test.ts"],"names":[],"mappings":""}

package/dist/types/tests/procaptcha.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=procaptcha.unit.test.d.ts.map

package/dist/types/tests/procaptcha.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"procaptcha.unit.test.d.ts","sourceRoot":"","sources":["../../../src/tests/procaptcha.unit.test.ts"],"names":[],"mappings":""}

package/dist/types/tests/siteVerifyMock.d.ts

@@ -0,0 +1,17 @@
+import { type Mock } from "vitest";
+import type { SiteVerifyRequestBody, SiteVerifyResponse } from "../siteverify.js";
+export interface SiteVerifyCall {
+    url: string;
+    headers: Headers;
+    body: SiteVerifyRequestBody;
+}
+export type SiteVerifyResponder = (body: SiteVerifyRequestBody) => Response | Promise<Response>;
+export interface SiteVerifyMock {
+    fetch: Mock<typeof fetch>;
+    calls: SiteVerifyCall[];
+}
+export declare const verifiedResponse: (overrides?: Partial<SiteVerifyResponse>) => Response;
+export declare const rejectedResponse: (reason?: string) => Response;
+export declare const errorEnvelope: (status: number, key: string, message: string) => Response;
+export declare const mockSiteVerify: (respond?: SiteVerifyResponder) => SiteVerifyMock;
+//# sourceMappingURL=siteVerifyMock.d.ts.map

package/dist/types/tests/siteVerifyMock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"siteVerifyMock.d.ts","sourceRoot":"","sources":["../../../src/tests/siteVerifyMock.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,KAAK,IAAI,EAAM,MAAM,QAAQ,CAAC;AACvC,OAAO,KAAK,EAEX,qBAAqB,EACrB,kBAAkB,EAClB,MAAM,kBAAkB,CAAC;AAE1B,MAAM,WAAW,cAAc;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,qBAAqB,CAAC;CAC5B;AAED,MAAM,MAAM,mBAAmB,GAAG,CACjC,IAAI,EAAE,qBAAqB,KACvB,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;AAElC,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,IAAI,CAAC,OAAO,KAAK,CAAC,CAAC;IAC1B,KAAK,EAAE,cAAc,EAAE,CAAC;CACxB;AAUD,eAAO,MAAM,gBAAgB,eACjB,OAAO,CAAC,kBAAkB,CAAC,KACpC,QAOF,CAAC;AAEF,eAAO,MAAM,gBAAgB,YAAa,MAAM,KAAG,QAOlD,CAAC;AAEF,eAAO,MAAM,aAAa,WACjB,MAAM,OACT,MAAM,WACF,MAAM,KACb,QAKF,CAAC;AAEF,eAAO,MAAM,cAAc,aACjB,mBAAmB,KAC1B,cAeF,CAAC"}

package/dist/types/tests/siteverify.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=siteverify.unit.test.d.ts.map

package/dist/types/tests/siteverify.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"siteverify.unit.test.d.ts","sourceRoot":"","sources":["../../../src/tests/siteverify.unit.test.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "@prosopo/better-auth-procaptcha-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.0",
+  "description": "Prosopo Procaptcha bot protection for Better Auth. Verifies a Procaptcha token before sign-up, sign-in and other auth endpoints run.",
+  "type": "module",
+  "engines": {
+    "node": "^24"
+  },
+  "main": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.cjs"
+    },
+    "./client": {
+      "types": "./dist/types/client.d.ts",
+      "import": "./dist/esm/client.js",
+      "require": "./dist/cjs/client.cjs"
+    }
+  },
+  "keywords": [
+    "better-auth",
+    "captcha",
+    "procaptcha",
+    "prosopo",
+    "bot-protection"
+  ],
+  "dependencies": {
+    "@prosopo/types": "5.30.0"
+  },
+  "peerDependencies": {
+    "better-auth": "^1.7.0"
+  },
+  "devDependencies": {
+    "@prosopo/config": "3.5.5",
+    "@types/node": "22.10.2",
+    "@vitest/coverage-v8": "5.0.4",
+    "better-auth": "1.7.15",
+    "del-cli": "6.0.0",
+    "tslib": "2.7.0",
+    "typescript": "5.6.2",
+    "vite": "8.1.6",
+    "vitest": "5.0.4"
+  },
+  "author": "PROSOPO LIMITED <info@prosopo.io>",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "bugs": {
+    "url": "https://github.com/prosopo/captcha/issues"
+  },
+  "homepage": "https://github.com/prosopo/captcha/tree/main/integration/frameworks/better-auth/better-auth-procaptcha-plugin#readme",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/prosopo/captcha.git",
+    "directory": "integration/frameworks/better-auth/better-auth-procaptcha-plugin"
+  },
+  "scripts": {
+    "clean": "del-cli --verbose dist",
+    "build:esm": "vite build --config vite.esm.config.ts --mode ${NODE_ENV:-development}",
+    "build:tsc": "tsc --build --verbose",
+    "build:cjs": "NODE_ENV=${NODE_ENV:-development}; vite build --config vite.cjs.config.ts --mode $NODE_ENV",
+    "build:types": "tsc --project tsconfig.types.json",
+    "test": "NODE_ENV=${NODE_ENV:-test}; pnpm exec vitest run --config ./vite.test.config.ts"
+  }
 }

package/readme.md

@@ -0,0 +1,145 @@
+# @prosopo/better-auth-procaptcha-plugin
+
+[Prosopo Procaptcha](https://prosopo.io) bot protection for [Better Auth](https://www.better-auth.com).
+
+The server plugin checks a Procaptcha token before Better Auth runs a protected endpoint, such as sign-up, sign-in or
+password reset. Requests without a valid token are rejected before they reach your database.
+
+- Works with Better Auth `^1.7.0`. Tested against 1.7.0 and 1.7.15.
+- Uses only Better Auth's public plugin API (`onRequest`, `getIP` from `better-auth/api`, client `fetchPlugins`).
+- Verifies tokens with Prosopo's [siteverify API](https://docs.prosopo.io/en/basics/server-side-verification/).
+
+## Install
+
+```bash
+npm install @prosopo/better-auth-procaptcha-plugin
+```
+
+You need a site key and a secret key from the [Prosopo portal](https://portal.prosopo.io).
+
+## Server
+
+```ts
+import { betterAuth } from "better-auth";
+import { procaptcha } from "@prosopo/better-auth-procaptcha-plugin";
+
+export const auth = betterAuth({
+	plugins: [
+		procaptcha({
+			secretKey: process.env.PROSOPO_SECRET_KEY as string,
+		}),
+	],
+});
+```
+
+By default the plugin protects `/sign-up/email`, `/sign-in/email` and `/request-password-reset`, the same endpoints as
+Better Auth's built-in captcha plugin.
+
+For each protected request the plugin:
+
+1. reads the token from the `x-captcha-response` header,
+2. sends `{ secret, token, ip }` to `https://api.prosopo.io/siteverify`,
+3. lets the request through only if the answer is `verified: true`.
+
+### Options
+
+| Option            | Default                                                    | What it does                                                                                                                                                     |
+| ----------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `secretKey`       | (required)                                                 | Your site's secret key.                                                                                                                                          |
+| `endpoints`       | `["/sign-up/email", "/sign-in/email", "/request-password-reset"]` | Paths to protect, without the Better Auth base path. `*` matches one path segment, `**` matches any depth, for example `/sign-in/*`.                           |
+| `siteVerifyURL`   | `https://api.prosopo.io/siteverify`                        | Use `https://eu-api.prosopo.io/siteverify` or `https://us-api.prosopo.io/siteverify` to keep verification in one region.                                         |
+| `headerName`      | `x-captcha-response`                                       | The request header that carries the token.                                                                                                                       |
+| `sendIP`          | `true`                                                     | Send the visitor's IP so Prosopo can compare it with the IP that solved the captcha. The IP comes from Better Auth's `advanced.ipAddress` settings.              |
+| `sendEmailDomain` | `false`                                                    | Send the domain of the `email` field in the request body (not the full address) for Prosopo's disposable and spam email filter.                                  |
+| `maxScore`        | none                                                       | Reject verified tokens whose risk score is above this number. Scores run from 0 (human) to 1 (bot) and are only returned on plans that include them.            |
+| `timeoutMs`       | `10000`                                                    | How long to wait for siteverify before failing the request.                                                                                                      |
+| `fetch`           | global `fetch`                                             | A custom fetch, for example one that goes through a proxy.                                                                                                       |
+
+### Errors
+
+The plugin answers with a JSON body `{ "code": "...", "message": "..." }`.
+
+| Status | `code`                           | When                                                                                           |
+| ------ | -------------------------------- | ---------------------------------------------------------------------------------------------- |
+| 400    | `PROCAPTCHA_MISSING_RESPONSE`    | The request has no token.                                                                      |
+| 403    | `PROCAPTCHA_VERIFICATION_FAILED` | Prosopo did not verify the token, or its score is above `maxScore`.                           |
+| 503    | `PROCAPTCHA_SERVICE_UNAVAILABLE` | siteverify could not be reached, timed out, rate limited the request or returned a 5xx.       |
+| 500    | `PROCAPTCHA_UNKNOWN_ERROR`       | The plugin is misconfigured: no `secretKey`, or siteverify rejected the secret or the request. |
+
+The plugin fails closed: if Prosopo cannot be reached, protected requests are rejected. The reason for a 500 or 503 is
+written to the Better Auth logger.
+
+### Verifying a token yourself
+
+`verifyProcaptchaToken` is the same check the plugin runs, for use in your own endpoints:
+
+```ts
+import { verifyProcaptchaToken } from "@prosopo/better-auth-procaptcha-plugin";
+
+const result = await verifyProcaptchaToken({ secretKey, token, ip });
+if (result.outcome !== "verified") {
+	// reject
+}
+```
+
+## Client
+
+Render the Procaptcha widget as described in the [client-side rendering guide](https://docs.prosopo.io/en/basics/client-side-rendering/),
+or with one of the framework wrappers, and keep the token it gives you.
+
+Then pass the token to Better Auth, either per request:
+
+```ts
+import { createAuthClient } from "better-auth/client";
+import {
+	procaptchaClient,
+	procaptchaHeaders,
+} from "@prosopo/better-auth-procaptcha-plugin/client";
+
+const authClient = createAuthClient({ plugins: [procaptchaClient()] });
+
+await authClient.signIn.email({
+	email,
+	password,
+	fetchOptions: { headers: procaptchaHeaders(token) },
+});
+```
+
+or automatically, by giving the client plugin a function that returns the current token:
+
+```ts
+let token: string | undefined;
+
+window.procaptcha.render(document.getElementById("procaptcha-container"), {
+	siteKey: "YOUR_SITE_KEY",
+	callback: (value: string) => {
+		token = value;
+	},
+	"expired-callback": () => {
+		token = undefined;
+	},
+});
+
+const authClient = createAuthClient({
+	plugins: [procaptchaClient({ getToken: () => token })],
+});
+```
+
+The client plugin only adds the header to requests for the protected endpoints. If you change `endpoints` or
+`headerName` on the server, pass the same values to `procaptchaClient`.
+
+A token can be verified only once and expires a few minutes after it is issued, so the visitor needs to solve the
+captcha again after each attempt.
+
+## Testing
+
+Prosopo's [test site keys](https://docs.prosopo.io/en/basics/test-keys/) work with this plugin. With the always-pass
+site key, siteverify returns `verified: true` for any secret, so you can run your sign-up and sign-in flows end to end
+in CI without solving a captcha.
+
+When Better Auth runs in development or test mode and no IP header is present, it reports the visitor's IP as
+`127.0.0.1`. Set `sendIP: false` locally if you use IP validation rules on your site.
+
+## License
+
+Apache-2.0

package/vite.cjs.config.ts

@@ -0,0 +1,24 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import path from "node:path";
+import { ViteCommonJSConfig } from "@prosopo/config";
+
+export default function () {
+	return ViteCommonJSConfig(
+		path.basename("."),
+		path.resolve("./tsconfig.json"),
+		["src/index.ts", "src/client.ts"],
+	);
+}

package/vite.esm.config.ts

@@ -0,0 +1,23 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import path from "node:path";
+import { ViteEsmConfig } from "@prosopo/config";
+
+export default function () {
+	return ViteEsmConfig(path.basename("."), path.resolve("./tsconfig.json"), [
+		"src/index.ts",
+		"src/client.ts",
+	]);
+}

package/vite.test.config.ts

@@ -0,0 +1,19 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { ViteTestConfig } from "@prosopo/config";
+
+process.env.NODE_ENV = "test";
+
+export default ViteTestConfig();

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.