better-ship 0.26.0 → 0.27.0

package/dist/cloudflare/turnstile.d.ts

@@ -0,0 +1,57 @@
+import { Xt as AppError, Zt as FailureClassification } from "../index-DUFS0SJ_.js";
+//#region src/infrastructure/cloudflare/turnstile/turnstile.error.d.ts
+/**
+ * Siteverify did not produce a verdict.
+ * A rejected token is not this error. The caller logs it once.
+ */
+export declare class TurnstileVerificationError extends AppError {
+  readonly _tag = "TurnstileVerificationError";
+  readonly classification: FailureClassification;
+  readonly errorCodes: readonly string[];
+  constructor(args: {
+    readonly classification: FailureClassification;
+    readonly errorCodes: readonly string[];
+    readonly cause: unknown;
+  });
+}
+//#endregion
+//#region src/infrastructure/cloudflare/turnstile/turnstile.d.ts
+/** The values siteverify needs. The secret stays in the caller. */
+type TurnstileCheck = {
+  readonly secretKey: string;
+  readonly token: string;
+  /** Visitor address from `CF-Connecting-IP`. Omit it when the request has none. */
+  readonly remoteIp?: string;
+  /** Widget action. A present, different action rejects. A missing action does not. */
+  readonly expectedAction?: string;
+  /** Allowed widget hostnames. A testing-key success skips this list. */
+  readonly expectedHostnames?: readonly string[];
+  /** UUID reused for this call's retries. Omit it and the call mints one. */
+  readonly idempotencyKey?: string;
+};
+/** A solved challenge, or a refusal siteverify already decided. */
+type TurnstileVerdict = {
+  readonly _tag: 'Accepted';
+  readonly hostname: string;
+  readonly challengeTs: string;
+  readonly action?: string;
+} | {
+  readonly _tag: 'Rejected';
+  readonly errorCodes: readonly string[];
+};
+/** Deadline and fetch overrides. Production calls omit this argument. */
+type TurnstileVerifyOptions = {
+  /** Replaces global `fetch`. A test uses it for a response the testing secret cannot return. */
+  readonly fetch?: typeof fetch;
+  /** Siteverify deadline in milliseconds. The default is 10 seconds. */
+  readonly timeoutMs?: number;
+};
+/**
+ * Ask siteverify whether this token is a solved challenge.
+ * A rejection is a verdict. No verdict throws `TurnstileVerificationError`.
+ * A transient failure retries twice with the same idempotency key.
+ */
+export declare function verifyTurnstile(check: TurnstileCheck, options?: TurnstileVerifyOptions): Promise<TurnstileVerdict>;
+//#endregion
+export type { TurnstileCheck, TurnstileVerdict, TurnstileVerifyOptions };
+//# sourceMappingURL=turnstile.d.ts.map

package/dist/cloudflare/turnstile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turnstile.d.ts","names":[],"sources":["../../src/infrastructure/cloudflare/turnstile/turnstile.error.ts","../../src/infrastructure/cloudflare/turnstile/turnstile.ts"],"mappings":";;;;;;qBAMa,mCAAmC;WACrC;WACA,gBAAgB;WAChB;EAET,YAAY;aACD,gBAAgB;aAChB;aACA;;;;;;KCoCD;WACD;WACA;;WAEA;;WAEA;;WAEA;;WAEA;;;KAIC;WAEG;WACA;WACA;WACA;;WAGA;WACA;;;KAIH;;WAED,eAAe;;WAEf;;;;;;;wBAmBW,gBACpB,OAAO,gBACP,UAAS,yBACR,QAAQ"}

package/dist/cloudflare/turnstile.js

@@ -0,0 +1,191 @@
+import { b as shouldRetryFailure, c as exponentialEqualJitterMs, nt as AppError, u as classifyBoundaryError } from "../core-BiN6S_cm.js";
+import { z } from "zod";
+import { Result } from "better-result";
+
+//#region src/infrastructure/cloudflare/turnstile/turnstile.error.ts
+/**
+* Siteverify did not produce a verdict.
+* A rejected token is not this error. The caller logs it once.
+*/
+var TurnstileVerificationError = class extends AppError {
+	_tag = "TurnstileVerificationError";
+	classification;
+	errorCodes;
+	constructor(args) {
+		super("Turnstile siteverify could not produce a verdict", { cause: args.cause });
+		this.classification = args.classification;
+		this.errorCodes = args.errorCodes;
+	}
+};
+
+//#endregion
+//#region src/infrastructure/cloudflare/turnstile/turnstile.ts
+/**
+* Turnstile siteverify. Ported from Suparelay `verify-turnstile.ts` and Typist `turnstile.ts`.
+* A rejection is a verdict. This module does not log, and one call retries with one idempotency key.
+*/
+const SITEVERIFY_URL = "https://challenges.cloudflare.com/turnstile/v0/siteverify";
+const MAX_TOKEN_LENGTH = 2048;
+const DEFAULT_TIMEOUT_MS = 1e4;
+const RETRY_TIMES = 2;
+const CONFIGURATION_CODES = /* @__PURE__ */ new Set([
+	"missing-input-secret",
+	"invalid-input-secret",
+	"bad-request"
+]);
+const SuccessBody = z.object({
+	success: z.literal(true),
+	hostname: z.string(),
+	challenge_ts: z.string(),
+	action: z.string().optional(),
+	metadata: z.object({ result_with_testing_key: z.boolean().optional() }).optional()
+});
+const FailureBody = z.object({
+	success: z.literal(false),
+	"error-codes": z.array(z.string()).default([])
+});
+var SiteverifyRetry = class extends Error {
+	errorCodes;
+	_tag = "SiteverifyRetry";
+	constructor(errorCodes, cause) {
+		super("Turnstile siteverify did not answer", { cause });
+		this.errorCodes = errorCodes;
+	}
+};
+/**
+* Ask siteverify whether this token is a solved challenge.
+* A rejection is a verdict. No verdict throws `TurnstileVerificationError`.
+* A transient failure retries twice with the same idempotency key.
+*/
+async function verifyTurnstile(check, options = {}) {
+	if (check.token.length > MAX_TOKEN_LENGTH) return {
+		_tag: "Rejected",
+		errorCodes: ["invalid-input-response"]
+	};
+	const idempotencyKey = resolveIdempotencyKey(check.idempotencyKey);
+	const result = await Result.tryPromise({
+		try: () => requestVerdict(check, idempotencyKey, options),
+		catch: (cause) => cause
+	}, { retry: {
+		times: RETRY_TIMES,
+		delayMs: (_cause, context) => exponentialEqualJitterMs(25, 200, context.attempt),
+		shouldRetry: (cause) => cause instanceof SiteverifyRetry && shouldRetryFailure({
+			classification: "transient",
+			repeatSafe: true,
+			owner: "immediate"
+		})
+	} });
+	if (result.isOk()) return result.value;
+	if (result.error instanceof TurnstileVerificationError) throw result.error;
+	if (result.error instanceof SiteverifyRetry) throw new TurnstileVerificationError({
+		classification: "transient",
+		errorCodes: result.error.errorCodes,
+		cause: result.error.cause
+	});
+	throw new TurnstileVerificationError({
+		classification: "unknown",
+		errorCodes: [],
+		cause: result.error
+	});
+}
+function resolveIdempotencyKey(key) {
+	if (key === void 0) return crypto.randomUUID();
+	if (z.uuid().safeParse(key).success) return key;
+	throw new TurnstileVerificationError({
+		classification: "terminal",
+		errorCodes: [],
+		cause: { idempotencyKey: "invalid" }
+	});
+}
+async function requestVerdict(check, idempotencyKey, options) {
+	const fetchImpl = options.fetch ?? fetch;
+	const fields = {
+		secret: check.secretKey,
+		response: check.token,
+		idempotency_key: idempotencyKey
+	};
+	const payload = check.remoteIp !== void 0 && check.remoteIp !== "" ? {
+		...fields,
+		remoteip: check.remoteIp
+	} : fields;
+	let response;
+	try {
+		response = await fetchImpl(SITEVERIFY_URL, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(payload),
+			signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS)
+		});
+	} catch (cause) {
+		throw transportFailure(cause);
+	}
+	const text = await response.text();
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch (cause) {
+		throw unparsedFailure(response.status, cause);
+	}
+	const success = SuccessBody.safeParse(parsed);
+	if (success.success) return decideSuccess(success.data, check);
+	const failure = FailureBody.safeParse(parsed);
+	if (failure.success) return decideFailure(failure.data["error-codes"], response.status);
+	throw unparsedFailure(response.status, { status: response.status });
+}
+function decideSuccess(body, check) {
+	if (check.expectedAction !== void 0 && body.action !== void 0 && body.action !== check.expectedAction) return {
+		_tag: "Rejected",
+		errorCodes: ["action-mismatch"]
+	};
+	if (!(body.metadata?.result_with_testing_key === true) && check.expectedHostnames !== void 0 && !check.expectedHostnames.includes(body.hostname)) return {
+		_tag: "Rejected",
+		errorCodes: ["hostname-mismatch"]
+	};
+	if (body.action === void 0) return {
+		_tag: "Accepted",
+		hostname: body.hostname,
+		challengeTs: body.challenge_ts
+	};
+	return {
+		_tag: "Accepted",
+		hostname: body.hostname,
+		challengeTs: body.challenge_ts,
+		action: body.action
+	};
+}
+function decideFailure(errorCodes, status) {
+	if (errorCodes.some((code) => CONFIGURATION_CODES.has(code))) throw verificationFailure("terminal", errorCodes, status);
+	if (errorCodes.includes("internal-error") || status === 429 || status >= 500) throw new SiteverifyRetry(errorCodes, { status });
+	return {
+		_tag: "Rejected",
+		errorCodes
+	};
+}
+function transportFailure(cause) {
+	const classification = classifyBoundaryError({
+		cause,
+		classifyBoundary: () => void 0,
+		includeCloudflare: false
+	});
+	if (classification === "transient") return new SiteverifyRetry([], cause);
+	return new TurnstileVerificationError({
+		classification,
+		errorCodes: [],
+		cause
+	});
+}
+function unparsedFailure(status, cause) {
+	if (status === 429 || status >= 500) return new SiteverifyRetry([], cause);
+	return verificationFailure("terminal", [], status);
+}
+function verificationFailure(classification, errorCodes, status) {
+	return new TurnstileVerificationError({
+		classification,
+		errorCodes,
+		cause: { status }
+	});
+}
+
+//#endregion
+export { TurnstileVerificationError, verifyTurnstile };
+//# sourceMappingURL=turnstile.js.map

package/dist/cloudflare/turnstile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turnstile.js","names":[],"sources":["../../src/infrastructure/cloudflare/turnstile/turnstile.error.ts","../../src/infrastructure/cloudflare/turnstile/turnstile.ts"],"sourcesContent":["import { AppError, type FailureClassification } from '@/core'\n\n/**\n * Siteverify did not produce a verdict.\n * A rejected token is not this error. The caller logs it once.\n */\nexport class TurnstileVerificationError extends AppError {\n  readonly _tag = 'TurnstileVerificationError'\n  readonly classification: FailureClassification\n  readonly errorCodes: readonly string[]\n\n  constructor(args: {\n    readonly classification: FailureClassification\n    readonly errorCodes: readonly string[]\n    readonly cause: unknown\n  }) {\n    super('Turnstile siteverify could not produce a verdict', { cause: args.cause })\n    this.classification = args.classification\n    this.errorCodes = args.errorCodes\n  }\n}\n","import { Result } from 'better-result'\nimport { z } from 'zod'\n\nimport {\n  classifyBoundaryError,\n  exponentialEqualJitterMs,\n  shouldRetryFailure,\n  type FailureClassification,\n} from '@/core'\n\nimport { TurnstileVerificationError } from './turnstile.error.ts'\n\n/**\n * Turnstile siteverify. Ported from Suparelay `verify-turnstile.ts` and Typist `turnstile.ts`.\n * A rejection is a verdict. This module does not log, and one call retries with one idempotency key.\n */\n\nconst SITEVERIFY_URL = 'https://challenges.cloudflare.com/turnstile/v0/siteverify'\n\n// Cloudflare documents 2048 characters. The testing secret still accepts a longer token.\nconst MAX_TOKEN_LENGTH = 2048\n\n// Cloudflare's validation example stops at 10 seconds.\nconst DEFAULT_TIMEOUT_MS = 10_000\n\n// `times` counts retries after the first attempt, so a call stops at three attempts.\nconst RETRY_TIMES = 2\n\nconst CONFIGURATION_CODES: ReadonlySet<string> = new Set([\n  'missing-input-secret',\n  'invalid-input-secret',\n  'bad-request',\n])\n\nconst SuccessBody = z.object({\n  success: z.literal(true),\n  hostname: z.string(),\n  challenge_ts: z.string(),\n  action: z.string().optional(),\n  metadata: z.object({ result_with_testing_key: z.boolean().optional() }).optional(),\n})\n\nconst FailureBody = z.object({\n  success: z.literal(false),\n  'error-codes': z.array(z.string()).default([]),\n})\n\ntype SuccessBody = z.infer<typeof SuccessBody>\n\n/** The values siteverify needs. The secret stays in the caller. */\nexport type TurnstileCheck = {\n  readonly secretKey: string\n  readonly token: string\n  /** Visitor address from `CF-Connecting-IP`. Omit it when the request has none. */\n  readonly remoteIp?: string\n  /** Widget action. A present, different action rejects. A missing action does not. */\n  readonly expectedAction?: string\n  /** Allowed widget hostnames. A testing-key success skips this list. */\n  readonly expectedHostnames?: readonly string[]\n  /** UUID reused for this call's retries. Omit it and the call mints one. */\n  readonly idempotencyKey?: string\n}\n\n/** A solved challenge, or a refusal siteverify already decided. */\nexport type TurnstileVerdict =\n  | {\n      readonly _tag: 'Accepted'\n      readonly hostname: string\n      readonly challengeTs: string\n      readonly action?: string\n    }\n  | {\n      readonly _tag: 'Rejected'\n      readonly errorCodes: readonly string[]\n    }\n\n/** Deadline and fetch overrides. Production calls omit this argument. */\nexport type TurnstileVerifyOptions = {\n  /** Replaces global `fetch`. A test uses it for a response the testing secret cannot return. */\n  readonly fetch?: typeof fetch\n  /** Siteverify deadline in milliseconds. The default is 10 seconds. */\n  readonly timeoutMs?: number\n}\n\nclass SiteverifyRetry extends Error {\n  readonly _tag = 'SiteverifyRetry'\n\n  constructor(\n    readonly errorCodes: readonly string[],\n    cause: unknown,\n  ) {\n    super('Turnstile siteverify did not answer', { cause })\n  }\n}\n\n/**\n * Ask siteverify whether this token is a solved challenge.\n * A rejection is a verdict. No verdict throws `TurnstileVerificationError`.\n * A transient failure retries twice with the same idempotency key.\n */\nexport async function verifyTurnstile(\n  check: TurnstileCheck,\n  options: TurnstileVerifyOptions = {},\n): Promise<TurnstileVerdict> {\n  if (check.token.length > MAX_TOKEN_LENGTH) {\n    return { _tag: 'Rejected', errorCodes: ['invalid-input-response'] }\n  }\n  const idempotencyKey = resolveIdempotencyKey(check.idempotencyKey)\n  const result = await Result.tryPromise(\n    {\n      try: () => requestVerdict(check, idempotencyKey, options),\n      catch: (cause) => cause,\n    },\n    {\n      retry: {\n        times: RETRY_TIMES,\n        delayMs: (_cause, context) => exponentialEqualJitterMs(25, 200, context.attempt),\n        shouldRetry: (cause) =>\n          cause instanceof SiteverifyRetry &&\n          shouldRetryFailure({\n            classification: 'transient',\n            repeatSafe: true,\n            owner: 'immediate',\n          }),\n      },\n    },\n  )\n  if (result.isOk()) return result.value\n  if (result.error instanceof TurnstileVerificationError) throw result.error\n  if (result.error instanceof SiteverifyRetry) {\n    throw new TurnstileVerificationError({\n      classification: 'transient',\n      errorCodes: result.error.errorCodes,\n      cause: result.error.cause,\n    })\n  }\n  throw new TurnstileVerificationError({\n    classification: 'unknown',\n    errorCodes: [],\n    cause: result.error,\n  })\n}\n\nfunction resolveIdempotencyKey(key: string | undefined): string {\n  if (key === undefined) return crypto.randomUUID()\n  if (z.uuid().safeParse(key).success) return key\n  throw new TurnstileVerificationError({\n    classification: 'terminal',\n    errorCodes: [],\n    cause: { idempotencyKey: 'invalid' },\n  })\n}\n\nasync function requestVerdict(\n  check: TurnstileCheck,\n  idempotencyKey: string,\n  options: TurnstileVerifyOptions,\n): Promise<TurnstileVerdict> {\n  const fetchImpl = options.fetch ?? fetch\n  const fields = {\n    secret: check.secretKey,\n    response: check.token,\n    idempotency_key: idempotencyKey,\n  }\n  const payload =\n    check.remoteIp !== undefined && check.remoteIp !== ''\n      ? { ...fields, remoteip: check.remoteIp }\n      : fields\n\n  let response: Response\n  try {\n    response = await fetchImpl(SITEVERIFY_URL, {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify(payload),\n      signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS),\n    })\n  } catch (cause) {\n    throw transportFailure(cause)\n  }\n\n  const text = await response.text()\n  let parsed: unknown\n  try {\n    parsed = JSON.parse(text)\n  } catch (cause) {\n    throw unparsedFailure(response.status, cause)\n  }\n\n  const success = SuccessBody.safeParse(parsed)\n  if (success.success) return decideSuccess(success.data, check)\n  const failure = FailureBody.safeParse(parsed)\n  if (failure.success) return decideFailure(failure.data['error-codes'], response.status)\n  throw unparsedFailure(response.status, { status: response.status })\n}\n\nfunction decideSuccess(body: SuccessBody, check: TurnstileCheck): TurnstileVerdict {\n  // A testing secret omits action. Compare only an action the response names.\n  if (\n    check.expectedAction !== undefined &&\n    body.action !== undefined &&\n    body.action !== check.expectedAction\n  ) {\n    return { _tag: 'Rejected', errorCodes: ['action-mismatch'] }\n  }\n  // A testing secret reports example.com, so the allowlist does not apply to it.\n  const testingKey = body.metadata?.result_with_testing_key === true\n  if (\n    !testingKey &&\n    check.expectedHostnames !== undefined &&\n    !check.expectedHostnames.includes(body.hostname)\n  ) {\n    return { _tag: 'Rejected', errorCodes: ['hostname-mismatch'] }\n  }\n  if (body.action === undefined) {\n    return { _tag: 'Accepted', hostname: body.hostname, challengeTs: body.challenge_ts }\n  }\n  return {\n    _tag: 'Accepted',\n    hostname: body.hostname,\n    challengeTs: body.challenge_ts,\n    action: body.action,\n  }\n}\n\nfunction decideFailure(errorCodes: readonly string[], status: number): TurnstileVerdict {\n  if (errorCodes.some((code) => CONFIGURATION_CODES.has(code))) {\n    throw verificationFailure('terminal', errorCodes, status)\n  }\n  if (errorCodes.includes('internal-error') || status === 429 || status >= 500) {\n    throw new SiteverifyRetry(errorCodes, { status })\n  }\n  return { _tag: 'Rejected', errorCodes }\n}\n\nfunction transportFailure(cause: unknown): Error {\n  const classification = classifyBoundaryError({\n    cause,\n    classifyBoundary: () => undefined,\n    includeCloudflare: false,\n  })\n  if (classification === 'transient') return new SiteverifyRetry([], cause)\n  return new TurnstileVerificationError({ classification, errorCodes: [], cause })\n}\n\nfunction unparsedFailure(status: number, cause: unknown): Error {\n  if (status === 429 || status >= 500) return new SiteverifyRetry([], cause)\n  return verificationFailure('terminal', [], status)\n}\n\nfunction verificationFailure(\n  classification: FailureClassification,\n  errorCodes: readonly string[],\n  status: number,\n): TurnstileVerificationError {\n  return new TurnstileVerificationError({\n    classification,\n    errorCodes,\n    cause: { status },\n  })\n}\n"],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "better-ship",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Foundation for applications on Cloudflare Workers: logger, errors, message bus, infrastructure adapters, and UI primitives",
   "license": "Apache-2.0",
   "repository": {
@@ -38,6 +38,7 @@
     "./cloudflare/r2-errors": "./dist/cloudflare/r2-errors.js",
     "./cloudflare/scheduled": "./dist/cloudflare/scheduled.js",
     "./cloudflare/tracing": "./dist/cloudflare/tracing.js",
+    "./cloudflare/turnstile": "./dist/cloudflare/turnstile.js",
     "./core": "./dist/core.js",
     "./http": "./dist/http.js",
     "./postgres": "./dist/postgres.js",

package/src/infrastructure/cloudflare/turnstile/index.ts

@@ -0,0 +1,7 @@
+export { TurnstileVerificationError } from './turnstile.error.ts'
+export {
+  verifyTurnstile,
+  type TurnstileCheck,
+  type TurnstileVerdict,
+  type TurnstileVerifyOptions,
+} from './turnstile.ts'

package/src/infrastructure/cloudflare/turnstile/turnstile.error.ts

@@ -0,0 +1,21 @@
+import { AppError, type FailureClassification } from '@/core'
+
+/**
+ * Siteverify did not produce a verdict.
+ * A rejected token is not this error. The caller logs it once.
+ */
+export class TurnstileVerificationError extends AppError {
+  readonly _tag = 'TurnstileVerificationError'
+  readonly classification: FailureClassification
+  readonly errorCodes: readonly string[]
+
+  constructor(args: {
+    readonly classification: FailureClassification
+    readonly errorCodes: readonly string[]
+    readonly cause: unknown
+  }) {
+    super('Turnstile siteverify could not produce a verdict', { cause: args.cause })
+    this.classification = args.classification
+    this.errorCodes = args.errorCodes
+  }
+}

package/src/infrastructure/cloudflare/turnstile/turnstile.ts

@@ -0,0 +1,261 @@
+import { Result } from 'better-result'
+import { z } from 'zod'
+
+import {
+  classifyBoundaryError,
+  exponentialEqualJitterMs,
+  shouldRetryFailure,
+  type FailureClassification,
+} from '@/core'
+
+import { TurnstileVerificationError } from './turnstile.error.ts'
+
+/**
+ * Turnstile siteverify. Ported from Suparelay `verify-turnstile.ts` and Typist `turnstile.ts`.
+ * A rejection is a verdict. This module does not log, and one call retries with one idempotency key.
+ */
+
+const SITEVERIFY_URL = 'https://challenges.cloudflare.com/turnstile/v0/siteverify'
+
+// Cloudflare documents 2048 characters. The testing secret still accepts a longer token.
+const MAX_TOKEN_LENGTH = 2048
+
+// Cloudflare's validation example stops at 10 seconds.
+const DEFAULT_TIMEOUT_MS = 10_000
+
+// `times` counts retries after the first attempt, so a call stops at three attempts.
+const RETRY_TIMES = 2
+
+const CONFIGURATION_CODES: ReadonlySet<string> = new Set([
+  'missing-input-secret',
+  'invalid-input-secret',
+  'bad-request',
+])
+
+const SuccessBody = z.object({
+  success: z.literal(true),
+  hostname: z.string(),
+  challenge_ts: z.string(),
+  action: z.string().optional(),
+  metadata: z.object({ result_with_testing_key: z.boolean().optional() }).optional(),
+})
+
+const FailureBody = z.object({
+  success: z.literal(false),
+  'error-codes': z.array(z.string()).default([]),
+})
+
+type SuccessBody = z.infer<typeof SuccessBody>
+
+/** The values siteverify needs. The secret stays in the caller. */
+export type TurnstileCheck = {
+  readonly secretKey: string
+  readonly token: string
+  /** Visitor address from `CF-Connecting-IP`. Omit it when the request has none. */
+  readonly remoteIp?: string
+  /** Widget action. A present, different action rejects. A missing action does not. */
+  readonly expectedAction?: string
+  /** Allowed widget hostnames. A testing-key success skips this list. */
+  readonly expectedHostnames?: readonly string[]
+  /** UUID reused for this call's retries. Omit it and the call mints one. */
+  readonly idempotencyKey?: string
+}
+
+/** A solved challenge, or a refusal siteverify already decided. */
+export type TurnstileVerdict =
+  | {
+      readonly _tag: 'Accepted'
+      readonly hostname: string
+      readonly challengeTs: string
+      readonly action?: string
+    }
+  | {
+      readonly _tag: 'Rejected'
+      readonly errorCodes: readonly string[]
+    }
+
+/** Deadline and fetch overrides. Production calls omit this argument. */
+export type TurnstileVerifyOptions = {
+  /** Replaces global `fetch`. A test uses it for a response the testing secret cannot return. */
+  readonly fetch?: typeof fetch
+  /** Siteverify deadline in milliseconds. The default is 10 seconds. */
+  readonly timeoutMs?: number
+}
+
+class SiteverifyRetry extends Error {
+  readonly _tag = 'SiteverifyRetry'
+
+  constructor(
+    readonly errorCodes: readonly string[],
+    cause: unknown,
+  ) {
+    super('Turnstile siteverify did not answer', { cause })
+  }
+}
+
+/**
+ * Ask siteverify whether this token is a solved challenge.
+ * A rejection is a verdict. No verdict throws `TurnstileVerificationError`.
+ * A transient failure retries twice with the same idempotency key.
+ */
+export async function verifyTurnstile(
+  check: TurnstileCheck,
+  options: TurnstileVerifyOptions = {},
+): Promise<TurnstileVerdict> {
+  if (check.token.length > MAX_TOKEN_LENGTH) {
+    return { _tag: 'Rejected', errorCodes: ['invalid-input-response'] }
+  }
+  const idempotencyKey = resolveIdempotencyKey(check.idempotencyKey)
+  const result = await Result.tryPromise(
+    {
+      try: () => requestVerdict(check, idempotencyKey, options),
+      catch: (cause) => cause,
+    },
+    {
+      retry: {
+        times: RETRY_TIMES,
+        delayMs: (_cause, context) => exponentialEqualJitterMs(25, 200, context.attempt),
+        shouldRetry: (cause) =>
+          cause instanceof SiteverifyRetry &&
+          shouldRetryFailure({
+            classification: 'transient',
+            repeatSafe: true,
+            owner: 'immediate',
+          }),
+      },
+    },
+  )
+  if (result.isOk()) return result.value
+  if (result.error instanceof TurnstileVerificationError) throw result.error
+  if (result.error instanceof SiteverifyRetry) {
+    throw new TurnstileVerificationError({
+      classification: 'transient',
+      errorCodes: result.error.errorCodes,
+      cause: result.error.cause,
+    })
+  }
+  throw new TurnstileVerificationError({
+    classification: 'unknown',
+    errorCodes: [],
+    cause: result.error,
+  })
+}
+
+function resolveIdempotencyKey(key: string | undefined): string {
+  if (key === undefined) return crypto.randomUUID()
+  if (z.uuid().safeParse(key).success) return key
+  throw new TurnstileVerificationError({
+    classification: 'terminal',
+    errorCodes: [],
+    cause: { idempotencyKey: 'invalid' },
+  })
+}
+
+async function requestVerdict(
+  check: TurnstileCheck,
+  idempotencyKey: string,
+  options: TurnstileVerifyOptions,
+): Promise<TurnstileVerdict> {
+  const fetchImpl = options.fetch ?? fetch
+  const fields = {
+    secret: check.secretKey,
+    response: check.token,
+    idempotency_key: idempotencyKey,
+  }
+  const payload =
+    check.remoteIp !== undefined && check.remoteIp !== ''
+      ? { ...fields, remoteip: check.remoteIp }
+      : fields
+
+  let response: Response
+  try {
+    response = await fetchImpl(SITEVERIFY_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+    })
+  } catch (cause) {
+    throw transportFailure(cause)
+  }
+
+  const text = await response.text()
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text)
+  } catch (cause) {
+    throw unparsedFailure(response.status, cause)
+  }
+
+  const success = SuccessBody.safeParse(parsed)
+  if (success.success) return decideSuccess(success.data, check)
+  const failure = FailureBody.safeParse(parsed)
+  if (failure.success) return decideFailure(failure.data['error-codes'], response.status)
+  throw unparsedFailure(response.status, { status: response.status })
+}
+
+function decideSuccess(body: SuccessBody, check: TurnstileCheck): TurnstileVerdict {
+  // A testing secret omits action. Compare only an action the response names.
+  if (
+    check.expectedAction !== undefined &&
+    body.action !== undefined &&
+    body.action !== check.expectedAction
+  ) {
+    return { _tag: 'Rejected', errorCodes: ['action-mismatch'] }
+  }
+  // A testing secret reports example.com, so the allowlist does not apply to it.
+  const testingKey = body.metadata?.result_with_testing_key === true
+  if (
+    !testingKey &&
+    check.expectedHostnames !== undefined &&
+    !check.expectedHostnames.includes(body.hostname)
+  ) {
+    return { _tag: 'Rejected', errorCodes: ['hostname-mismatch'] }
+  }
+  if (body.action === undefined) {
+    return { _tag: 'Accepted', hostname: body.hostname, challengeTs: body.challenge_ts }
+  }
+  return {
+    _tag: 'Accepted',
+    hostname: body.hostname,
+    challengeTs: body.challenge_ts,
+    action: body.action,
+  }
+}
+
+function decideFailure(errorCodes: readonly string[], status: number): TurnstileVerdict {
+  if (errorCodes.some((code) => CONFIGURATION_CODES.has(code))) {
+    throw verificationFailure('terminal', errorCodes, status)
+  }
+  if (errorCodes.includes('internal-error') || status === 429 || status >= 500) {
+    throw new SiteverifyRetry(errorCodes, { status })
+  }
+  return { _tag: 'Rejected', errorCodes }
+}
+
+function transportFailure(cause: unknown): Error {
+  const classification = classifyBoundaryError({
+    cause,
+    classifyBoundary: () => undefined,
+    includeCloudflare: false,
+  })
+  if (classification === 'transient') return new SiteverifyRetry([], cause)
+  return new TurnstileVerificationError({ classification, errorCodes: [], cause })
+}
+
+function unparsedFailure(status: number, cause: unknown): Error {
+  if (status === 429 || status >= 500) return new SiteverifyRetry([], cause)
+  return verificationFailure('terminal', [], status)
+}
+
+function verificationFailure(
+  classification: FailureClassification,
+  errorCodes: readonly string[],
+  status: number,
+): TurnstileVerificationError {
+  return new TurnstileVerificationError({
+    classification,
+    errorCodes,
+    cause: { status },
+  })
+}