@prosopo/provider 4.15.14 → 4.15.16

package/dist/tasks/captchaManager.js

@@ -1,488 +1,408 @@
-import { getLogger } from "@prosopo/logger";
-import { ResultReason, Tier, ApiParams } from "@prosopo/types";
-import { AccessPolicyType } from "@prosopo/user-access-policy";
-import { getPrioritisedAccessRule, getRequestUserScope } from "../api/blacklistRequestInspector.js";
 import { getIpAddressFromComposite } from "../compositeIpAddress.js";
+import { getPrioritisedAccessRule, getRequestUserScope } from "../api/blacklistRequestInspector.js";
+import { checkTrafficFilter } from "./spam/checkTrafficFilter.js";
 import { extraIpInfosFromEnrichedDnsEvent } from "./dnsEvent/enrichDnsEvent.js";
 import { checkSpamEmail } from "./spam/checkSpamEmail.js";
-import { checkTrafficFilter } from "./spam/checkTrafficFilter.js";
-const findHardBlockPolicy = (accessPolicies) => {
-  return accessPolicies.find((policy) => {
-    if (policy.deferToVerify === true) {
-      return true;
-    }
-    return policy.type === AccessPolicyType.Block && !policy.captchaType;
-  });
+import { getLogger } from "@prosopo/logger";
+import { ApiParams, ResultReason, Tier } from "@prosopo/types";
+import { AccessPolicyType } from "@prosopo/user-access-policy";
+//#region src/tasks/captchaManager.ts
+/**
+* Finds a hard block policy from access policies.
+*
+* A hard block is either:
+*   (a) A Block policy with no captchaType (the historical "block all
+*       challenge types" case).
+*   (b) A Block policy with `deferToVerify: true` — request-time
+*       middleware skips these, so verify-time is the only place they
+*       can reject the commitment.
+*   (c) A Restrict policy with `deferToVerify: true` — the frictionless
+*       flow serves the rule's captchaType/solvedImagesCount normally
+*       (imposing the compute burden of the challenge), then verify
+*       marks the commitment disapproved regardless of solve outcome.
+*       Used by PROXY_POOL_TLS_NARROW to force a solving farm to burn
+*       8 image rounds per session while still failing verify — bots
+*       solve at 100% so we can't stop them by demanding correctness,
+*       only by wasting their compute.
+*
+* Policies with captchaType and without `deferToVerify` are pure routing
+* rules — they pick which challenge type to serve, not whether to reject.
+*/
+var findHardBlockPolicy = (accessPolicies) => {
+	return accessPolicies.find((policy) => {
+		if (policy.deferToVerify === true) return true;
+		return policy.type === AccessPolicyType.Block && !policy.captchaType;
+	});
 };
-class CaptchaManager {
-  constructor(db, pair, config, logger, writeQueue) {
-    this.pair = pair;
-    this.db = db;
-    this.config = config;
-    this.logger = logger || getLogger("info", "provider:captcha-manager");
-    this.writeQueue = writeQueue ?? null;
-  }
-  /**
-   * Update a session record with cache-first / write-behind semantics:
-   * the Redis cache patch is awaited (so the in-request view of the
-   * session is up-to-date for any subsequent fast-path read), and the
-   * Mongo write is fire-and-forget so the response isn't gated on a
-   * round-trip to Mongo. Matches the `RedisWriteQueue` design where
-   * Redis is the source of truth for the in-flight request and Mongo is
-   * eventually consistent.
-   *
-   * Prefer this over `this.db.updateSessionRecord` in any in-request
-   * handler.
-   */
-  async updateSessionRecordWithCache(sessionId, updates, streamToCentral) {
-    if (this.writeQueue) {
-      await this.writeQueue.patchCachedSession(
-        sessionId,
-        updates
-      );
-    }
-    this.scheduleMongoSessionUpdate(sessionId, updates, streamToCentral);
-  }
-  /**
-   * Decrypt with the active detector keys and strip the throwaway
-   * `timestamp` field. Returns `undefined` when no key decrypts.
-   */
-  async decryptSimdReadingsForAttach(simdReadingsCiphertext) {
-    const decryptKeys = [
-      ...await this.getDetectorKeys(),
-      process.env.BOT_DECRYPTION_KEY
-    ];
-    const decrypted = await this.decryptSimdReadings(
-      simdReadingsCiphertext,
-      decryptKeys
-    );
-    if (!decrypted) return void 0;
-    const { timestamp: _ignored, ...readings } = decrypted;
-    return readings;
-  }
-  /** Decrypt + first-hop-wins attach. No-op on decrypt failure. */
-  async decryptAndAttachSimdReadingsIfAbsent(sessionId, simdReadingsCiphertext, stage) {
-    const readings = await this.decryptSimdReadingsForAttach(
-      simdReadingsCiphertext
-    );
-    if (!readings) return;
-    await this.recordSessionSimdReadingsIfAbsentWithCache(
-      sessionId,
-      readings,
-      stage
-    );
-  }
-  /**
-   * First-hop-wins SIMD attach with cache-first / Mongo-deferred
-   * semantics — mirrors `updateSessionRecordWithCache`.
-   */
-  async recordSessionSimdReadingsIfAbsentWithCache(sessionId, readings, stage) {
-    if (this.writeQueue) {
-      await this.writeQueue.patchCachedSimdReadingsIfAbsent(
-        sessionId,
-        readings,
-        stage
-      );
-    }
-    this.scheduleMongoSimdReadingsUpdate(sessionId, readings, stage);
-  }
-  /**
-   * Fire-and-forget Mongo session update. Public so non-Task handlers
-   * (e.g. challenge GETs) can keep request response latency off the
-   * Mongo critical path while still ensuring eventual persistence.
-   */
-  scheduleMongoSessionUpdate(sessionId, updates, streamToCentral) {
-    Promise.resolve(
-      streamToCentral === void 0 ? this.db.updateSessionRecord(sessionId, updates) : this.db.updateSessionRecord(sessionId, updates, streamToCentral)
-    ).catch((err) => {
-      this.logger.warn(() => ({
-        err,
-        msg: "Background Mongo session update failed",
-        data: { sessionId }
-      }));
-    });
-  }
-  /**
-   * Fire-and-forget Mongo SIMD-readings update. Public for the same
-   * reason as `scheduleMongoSessionUpdate`.
-   */
-  scheduleMongoSimdReadingsUpdate(sessionId, readings, stage) {
-    Promise.resolve(
-      this.db.recordSessionSimdReadingsIfAbsent(sessionId, readings, stage)
-    ).catch((err) => {
-      this.logger.warn(() => ({
-        err,
-        msg: "Background Mongo SIMD-readings update failed",
-        data: { sessionId, stage }
-      }));
-    });
-  }
-  async validateSessionIP(sessionRecord, currentIP, env) {
-    return { valid: true };
-  }
-  async isValidRequest(clientSettings, requestedCaptchaType, env, sessionId, userAccessPolicy, currentIP) {
-    this.logger.debug(() => ({
-      msg: "Validating request",
-      data: {
-        captchaType: requestedCaptchaType,
-        sessionId
-      }
-    }));
-    if (userAccessPolicy?.captchaType !== void 0 && userAccessPolicy.captchaType !== requestedCaptchaType) {
-      this.logger.warn(() => ({
-        msg: "Invalid captcha type for user access policy",
-        data: {
-          account: clientSettings.account,
-          captchaType: userAccessPolicy.captchaType
-        }
-      }));
-      return {
-        valid: false,
-        reason: ResultReason.INCORRECT_CAPTCHA_TYPE,
-        type: requestedCaptchaType
-      };
-    }
-    if (sessionId) {
-      const cachedBeforeRemove = this.writeQueue ? await this.writeQueue.getCachedSession(sessionId) : null;
-      const cachedHash = typeof cachedBeforeRemove?.userSitekeyIpHash === "string" ? cachedBeforeRemove.userSitekeyIpHash : void 0;
-      await Promise.all([
-        this.writeQueue?.invalidateCachedSession(sessionId),
-        cachedHash ? this.writeQueue?.invalidateCachedSessionByHash(cachedHash) : Promise.resolve()
-      ]);
-      let sessionRecord = await this.db.checkAndRemoveSession(sessionId);
-      let resolvedSessionId = sessionId;
-      if (!sessionRecord && this.writeQueue) {
-        const escalationSessionId = await this.writeQueue.getCachedSessionEscalation(sessionId);
-        if (escalationSessionId && escalationSessionId !== sessionId) {
-          const peekedEscalationRecord = await this.db.getSessionRecordBySessionId(escalationSessionId);
-          if (peekedEscalationRecord) {
-            this.logger.info(() => ({
-              msg: "Resolving origin sessionId to escalation",
-              data: {
-                account: clientSettings.account,
-                originSessionId: sessionId,
-                escalationSessionId,
-                escalationCaptchaType: peekedEscalationRecord.captchaType,
-                requestedCaptchaType
-              }
-            }));
-            if (peekedEscalationRecord.captchaType === requestedCaptchaType) {
-              const consumedEscalationRecord = await this.db.checkAndRemoveSession(escalationSessionId);
-              if (consumedEscalationRecord) {
-                sessionRecord = consumedEscalationRecord;
-                resolvedSessionId = escalationSessionId;
-              }
-            } else {
-              this.logger.warn(() => ({
-                msg: "Escalation captcha type does not match requested type",
-                data: {
-                  account: clientSettings.account,
-                  originSessionId: sessionId,
-                  escalationSessionId,
-                  escalationCaptchaType: peekedEscalationRecord.captchaType,
-                  requestedCaptchaType
-                }
-              }));
-              await this.writeQueue.invalidateCachedSessionEscalation(
-                sessionId
-              );
-              return {
-                valid: false,
-                reason: ResultReason.INCORRECT_CAPTCHA_TYPE,
-                type: requestedCaptchaType
-              };
-            }
-          }
-          await this.writeQueue.invalidateCachedSessionEscalation(sessionId);
-        }
-      }
-      if (!sessionRecord) {
-        this.logger.warn(() => ({
-          msg: "No session found",
-          data: {
-            account: clientSettings.account,
-            sessionId
-          }
-        }));
-        if (this.writeQueue) {
-          const cachedHash2 = typeof cachedBeforeRemove?.userSitekeyIpHash === "string" ? cachedBeforeRemove.userSitekeyIpHash : void 0;
-          await Promise.all([
-            this.writeQueue.invalidateCachedSession(sessionId),
-            cachedHash2 ? this.writeQueue.invalidateCachedSessionByHash(cachedHash2) : Promise.resolve()
-          ]);
-        }
-        return {
-          valid: false,
-          reason: ResultReason.CAPTCHA_NO_SESSION_FOUND,
-          type: requestedCaptchaType
-        };
-      }
-      sessionId = resolvedSessionId;
-      if (this.writeQueue) {
-        await Promise.all([
-          this.writeQueue.invalidateCachedSession(sessionId),
-          sessionRecord.userSitekeyIpHash ? this.writeQueue.invalidateCachedSessionByHash(
-            sessionRecord.userSitekeyIpHash
-          ) : Promise.resolve()
-        ]);
-      }
-      if (currentIP) {
-        const ipValidation = await this.validateSessionIP(
-          sessionRecord,
-          currentIP,
-          env
-        );
-        if (!ipValidation.valid) {
-          return {
-            valid: false,
-            reason: ipValidation.reason,
-            type: requestedCaptchaType
-          };
-        }
-      }
-      if (sessionRecord.captchaType !== requestedCaptchaType) {
-        this.logger.warn(() => ({
-          msg: "Session captcha type does not match requested type",
-          data: {
-            account: clientSettings.account,
-            sessionId,
-            sessionCaptchaType: sessionRecord.captchaType,
-            requestedCaptchaType
-          }
-        }));
-        return {
-          valid: false,
-          reason: ResultReason.INCORRECT_CAPTCHA_TYPE,
-          type: requestedCaptchaType
-        };
-      }
-      return {
-        valid: true,
-        sessionId: sessionRecord.sessionId,
-        type: requestedCaptchaType,
-        ...sessionRecord.powDifficulty && {
-          powDifficulty: sessionRecord.powDifficulty
-        },
-        ...sessionRecord.solvedImagesCount && {
-          solvedImagesCount: sessionRecord.solvedImagesCount
-        },
-        ipInfo: sessionRecord.ipInfo
-      };
-    }
-    if (clientSettings?.settings?.captchaType !== requestedCaptchaType) {
-      this.logger.warn(() => ({
-        msg: `Invalid ${requestedCaptchaType} request`,
-        data: {
-          account: clientSettings.account,
-          requestedCaptchaType,
-          settingsCaptchaType: clientSettings?.settings?.captchaType
-        }
-      }));
-      return {
-        valid: false,
-        reason: ResultReason.INCORRECT_CAPTCHA_TYPE,
-        type: requestedCaptchaType
-      };
-    }
-    return { valid: true, type: requestedCaptchaType };
-  }
-  getVerificationResponse(verified, clientRecord, translateFn, score, reason) {
-    return {
-      status: translateFn(
-        verified ? "API.USER_VERIFIED" : "API.USER_NOT_VERIFIED"
-      ),
-      [ApiParams.verified]: verified,
-      ...CaptchaManager.canClientSeeScore(clientRecord.tier, score) && {
-        [ApiParams.score]: score
-      },
-      ...!verified && clientRecord.tier !== Tier.Free && reason && {
-        [ApiParams.reason]: reason
-      }
-    };
-  }
-  async getPrioritisedAccessPolicies(userAccessRulesStorage, clientId, userScope, options) {
-    return getPrioritisedAccessRule(
-      userAccessRulesStorage,
-      userScope,
-      clientId,
-      options
-    );
-  }
-  async getDetectorKeys() {
-    return await this.db.getDetectorKeys();
-  }
-  /**
-   * Decrypt the catcher's WASM SIMD CPU fingerprint readings via the
-   * obfuscated `decodeSimd.js` bundle (source lives in the private
-   * @prosopo/catcher repo). Mirrors `decryptBehavioralData`: tries each
-   * detector key in turn (loaded by the caller, with the env-var key as
-   * fallback). Returns null when no key works so the caller can drop
-   * the field rather than fail the whole request.
-   */
-  async decryptSimdReadings(encryptedData, decryptKeys) {
-    const decryptSimdReadings = (await import("./detection/decodeSimd.js")).default;
-    const validKeys = decryptKeys.filter((k) => k);
-    if (validKeys.length === 0) {
-      this.logger?.error(() => ({
-        msg: "No decryption keys provided for SIMD readings"
-      }));
-      return null;
-    }
-    for (const [keyIndex, key] of validKeys.entries()) {
-      try {
-        return await decryptSimdReadings(encryptedData, key);
-      } catch (err) {
-        this.logger?.debug(() => ({
-          msg: "Failed to decrypt SIMD readings with key, trying next",
-          data: {
-            keyIndex: keyIndex + 1,
-            totalKeys: validKeys.length,
-            err
-          }
-        }));
-      }
-    }
-    this.logger?.warn(() => ({
-      msg: "Failed to decrypt SIMD readings with all available keys",
-      data: { totalKeysAttempted: validKeys.length }
-    }));
-    return null;
-  }
-  async decryptBehavioralData(encryptedData, decryptKeys) {
-    const decryptBehavioralData = (await import("./detection/decodeBehavior.js")).default;
-    const validKeys = decryptKeys.filter((k) => k);
-    if (validKeys.length === 0) {
-      this.logger?.error(() => ({
-        msg: "No decryption keys provided for behavioral data"
-      }));
-      return null;
-    }
-    for (const [keyIndex, key] of validKeys.entries()) {
-      try {
-        this.logger?.debug(() => ({
-          msg: "Attempting to decrypt behavioral data",
-          data: {
-            keyIndex: keyIndex + 1,
-            totalKeys: validKeys.length
-          }
-        }));
-        const result = await decryptBehavioralData(encryptedData, key);
-        this.logger?.info(() => ({
-          msg: "Behavioral data decrypted successfully",
-          data: {
-            keyIndex: keyIndex + 1,
-            c1Length: result.collector1?.length || 0,
-            c2Length: result.collector2?.length || 0,
-            c3Length: result.collector3?.length || 0,
-            deviceCapability: result.deviceCapability
-          }
-        }));
-        return result;
-      } catch (error) {
-        this.logger?.debug(() => ({
-          msg: "Failed to decrypt with key, trying next",
-          data: {
-            keyIndex: keyIndex + 1,
-            totalKeys: validKeys.length,
-            err: error
-          }
-        }));
-      }
-    }
-    this.logger?.error(() => ({
-      msg: "Failed to decrypt behavioral data with all available keys",
-      data: {
-        totalKeysAttempted: validKeys.length
-      }
-    }));
-    return null;
-  }
-  /**
-   * Checks if a user should be hard blocked based on access policies
-   * Only checks for Block policies without captchaType
-   *
-   * @returns The blocking policy if user should be blocked, undefined otherwise
-   */
-  async checkForHardBlock(userAccessRulesStorage, challengeRecord, userAccount, headers, coords, countryCode, asn) {
-    let headHash;
-    if (challengeRecord.sessionId) {
-      const sessionRecord = await this.db.getSessionRecordBySessionId(
-        challengeRecord.sessionId
-      );
-      headHash = sessionRecord?.decryptedHeadHash;
-    }
-    const coordsString = coords ? JSON.stringify(coords) : void 0;
-    const ipAddressRecord = getIpAddressFromComposite(
-      challengeRecord.ipAddress
-    );
-    const userScope = getRequestUserScope(
-      headers,
-      challengeRecord.ja4,
-      ipAddressRecord.address,
-      userAccount,
-      headHash,
-      coordsString,
-      countryCode,
-      asn
-    );
-    const accessPolicies = await this.getPrioritisedAccessPolicies(
-      userAccessRulesStorage,
-      challengeRecord.dappAccount,
-      userScope,
-      // Hard-block lookup only — restrict the Redis-side candidate
-      // pool to Block rules so the SERVER_SIDE_RANK_TOP_N cap can't
-      // crowd a hard-block out of the top-N with Restrict or
-      // routing-Block (captchaType-scoped) entries.
-      { blockOnly: true }
-    );
-    return findHardBlockPolicy(accessPolicies);
-  }
-  /**
-   * Checks if the provided email address has a domain in the spam email domain list.
-   * Returns true if the email domain is spam (i.e. should be blocked), false otherwise.
-   * Handles formats: user@domain.com, @domain.com, domain.com
-   */
-  async checkSpamEmail(email) {
-    return checkSpamEmail(email, this.db, this.config, this.logger);
-  }
-  /**
-   * Resolves the IP info to feed to `checkTrafficFilter` and runs the check.
-   *
-   * - The captcha record already carries the IPInfoResponse from request
-   *   time (ipInfoMiddleware → storeXxxRecord), so by default we reuse it
-   *   instead of hitting the sidecar again.
-   * - If the dapp's server passed up the end user's current IP via the
-   *   verify call, look that up fresh — it's the "now" IP for filtering
-   *   and may differ from the IP that originally requested the captcha.
-   * - When the session carries a `dnsEvent`, its `peerIp` and `resolverIp`
-   *   are enriched and passed alongside the primary IP.
-   * - `blockAbuser` defaults to true so abusive networks are always
-   *   blocked even when the site hasn't configured a trafficFilter.
-   * - Returns `{ isBlocked: false }` if every filter flag is off, without
-   *   consulting the payload at all.
-   *
-   * Callers handle the "blocked" branch themselves (each verify path
-   * updates record / session state differently); this helper just returns
-   * the verdict.
-   */
-  async resolveTrafficFilterCheck(env, recordIpInfo, trafficFilter, currentIp, enrichedDnsEvent) {
-    const effective = { blockAbuser: true, ...trafficFilter };
-    const hasAny = Object.values(effective).some((v) => v);
-    if (!hasAny) {
-      return { isBlocked: false };
-    }
-    const ipInfo = currentIp ? await env.ipInfoService.lookup(currentIp) : recordIpInfo;
-    return checkTrafficFilter(
-      ipInfo,
-      effective,
-      extraIpInfosFromEnrichedDnsEvent(enrichedDnsEvent),
-      enrichedDnsEvent?.pathValid
-    );
-  }
-  static canClientSeeScore(tier, score) {
-    return score && tier && tier !== Tier.Free;
-  }
-}
-export {
-  CaptchaManager
+var CaptchaManager = class CaptchaManager {
+	constructor(db, pair, config, logger, writeQueue) {
+		this.pair = pair;
+		this.db = db;
+		this.config = config;
+		this.logger = logger || getLogger("info", "provider:captcha-manager");
+		this.writeQueue = writeQueue ?? null;
+	}
+	/**
+	* Update a session record with cache-first / write-behind semantics:
+	* the Redis cache patch is awaited (so the in-request view of the
+	* session is up-to-date for any subsequent fast-path read), and the
+	* Mongo write is fire-and-forget so the response isn't gated on a
+	* round-trip to Mongo. Matches the `RedisWriteQueue` design where
+	* Redis is the source of truth for the in-flight request and Mongo is
+	* eventually consistent.
+	*
+	* Prefer this over `this.db.updateSessionRecord` in any in-request
+	* handler.
+	*/
+	async updateSessionRecordWithCache(sessionId, updates, streamToCentral) {
+		if (this.writeQueue) await this.writeQueue.patchCachedSession(sessionId, updates);
+		this.scheduleMongoSessionUpdate(sessionId, updates, streamToCentral);
+	}
+	/**
+	* Decrypt with the active detector keys and strip the throwaway
+	* `timestamp` field. Returns `undefined` when no key decrypts.
+	*/
+	async decryptSimdReadingsForAttach(simdReadingsCiphertext) {
+		const decryptKeys = [...await this.getDetectorKeys(), process.env.BOT_DECRYPTION_KEY];
+		const decrypted = await this.decryptSimdReadings(simdReadingsCiphertext, decryptKeys);
+		if (!decrypted) return void 0;
+		const { timestamp: _ignored, ...readings } = decrypted;
+		return readings;
+	}
+	/** Decrypt + first-hop-wins attach. No-op on decrypt failure. */
+	async decryptAndAttachSimdReadingsIfAbsent(sessionId, simdReadingsCiphertext, stage) {
+		const readings = await this.decryptSimdReadingsForAttach(simdReadingsCiphertext);
+		if (!readings) return;
+		await this.recordSessionSimdReadingsIfAbsentWithCache(sessionId, readings, stage);
+	}
+	/**
+	* First-hop-wins SIMD attach with cache-first / Mongo-deferred
+	* semantics — mirrors `updateSessionRecordWithCache`.
+	*/
+	async recordSessionSimdReadingsIfAbsentWithCache(sessionId, readings, stage) {
+		if (this.writeQueue) await this.writeQueue.patchCachedSimdReadingsIfAbsent(sessionId, readings, stage);
+		this.scheduleMongoSimdReadingsUpdate(sessionId, readings, stage);
+	}
+	/**
+	* Fire-and-forget Mongo session update. Public so non-Task handlers
+	* (e.g. challenge GETs) can keep request response latency off the
+	* Mongo critical path while still ensuring eventual persistence.
+	*/
+	scheduleMongoSessionUpdate(sessionId, updates, streamToCentral) {
+		Promise.resolve(streamToCentral === void 0 ? this.db.updateSessionRecord(sessionId, updates) : this.db.updateSessionRecord(sessionId, updates, streamToCentral)).catch((err) => {
+			this.logger.warn(() => ({
+				err,
+				msg: "Background Mongo session update failed",
+				data: { sessionId }
+			}));
+		});
+	}
+	/**
+	* Fire-and-forget Mongo SIMD-readings update. Public for the same
+	* reason as `scheduleMongoSessionUpdate`.
+	*/
+	scheduleMongoSimdReadingsUpdate(sessionId, readings, stage) {
+		Promise.resolve(this.db.recordSessionSimdReadingsIfAbsent(sessionId, readings, stage)).catch((err) => {
+			this.logger.warn(() => ({
+				err,
+				msg: "Background Mongo SIMD-readings update failed",
+				data: {
+					sessionId,
+					stage
+				}
+			}));
+		});
+	}
+	async validateSessionIP(sessionRecord, currentIP, env) {
+		return { valid: true };
+	}
+	async isValidRequest(clientSettings, requestedCaptchaType, env, sessionId, userAccessPolicy, currentIP) {
+		this.logger.debug(() => ({
+			msg: "Validating request",
+			data: {
+				captchaType: requestedCaptchaType,
+				sessionId
+			}
+		}));
+		if (userAccessPolicy?.captchaType !== void 0 && userAccessPolicy.captchaType !== requestedCaptchaType) {
+			this.logger.warn(() => ({
+				msg: "Invalid captcha type for user access policy",
+				data: {
+					account: clientSettings.account,
+					captchaType: userAccessPolicy.captchaType
+				}
+			}));
+			return {
+				valid: false,
+				reason: ResultReason.INCORRECT_CAPTCHA_TYPE,
+				type: requestedCaptchaType
+			};
+		}
+		if (sessionId) {
+			const cachedBeforeRemove = this.writeQueue ? await this.writeQueue.getCachedSession(sessionId) : null;
+			const cachedHash = typeof cachedBeforeRemove?.userSitekeyIpHash === "string" ? cachedBeforeRemove.userSitekeyIpHash : void 0;
+			await Promise.all([this.writeQueue?.invalidateCachedSession(sessionId), cachedHash ? this.writeQueue?.invalidateCachedSessionByHash(cachedHash) : Promise.resolve()]);
+			let sessionRecord = await this.db.checkAndRemoveSession(sessionId);
+			let resolvedSessionId = sessionId;
+			if (!sessionRecord && this.writeQueue) {
+				const escalationSessionId = await this.writeQueue.getCachedSessionEscalation(sessionId);
+				if (escalationSessionId && escalationSessionId !== sessionId) {
+					const peekedEscalationRecord = await this.db.getSessionRecordBySessionId(escalationSessionId);
+					if (peekedEscalationRecord) {
+						this.logger.info(() => ({
+							msg: "Resolving origin sessionId to escalation",
+							data: {
+								account: clientSettings.account,
+								originSessionId: sessionId,
+								escalationSessionId,
+								escalationCaptchaType: peekedEscalationRecord.captchaType,
+								requestedCaptchaType
+							}
+						}));
+						if (peekedEscalationRecord.captchaType === requestedCaptchaType) {
+							const consumedEscalationRecord = await this.db.checkAndRemoveSession(escalationSessionId);
+							if (consumedEscalationRecord) {
+								sessionRecord = consumedEscalationRecord;
+								resolvedSessionId = escalationSessionId;
+							}
+						} else {
+							this.logger.warn(() => ({
+								msg: "Escalation captcha type does not match requested type",
+								data: {
+									account: clientSettings.account,
+									originSessionId: sessionId,
+									escalationSessionId,
+									escalationCaptchaType: peekedEscalationRecord.captchaType,
+									requestedCaptchaType
+								}
+							}));
+							await this.writeQueue.invalidateCachedSessionEscalation(sessionId);
+							return {
+								valid: false,
+								reason: ResultReason.INCORRECT_CAPTCHA_TYPE,
+								type: requestedCaptchaType
+							};
+						}
+					}
+					await this.writeQueue.invalidateCachedSessionEscalation(sessionId);
+				}
+			}
+			if (!sessionRecord) {
+				this.logger.warn(() => ({
+					msg: "No session found",
+					data: {
+						account: clientSettings.account,
+						sessionId
+					}
+				}));
+				if (this.writeQueue) {
+					const cachedHash = typeof cachedBeforeRemove?.userSitekeyIpHash === "string" ? cachedBeforeRemove.userSitekeyIpHash : void 0;
+					await Promise.all([this.writeQueue.invalidateCachedSession(sessionId), cachedHash ? this.writeQueue.invalidateCachedSessionByHash(cachedHash) : Promise.resolve()]);
+				}
+				return {
+					valid: false,
+					reason: ResultReason.CAPTCHA_NO_SESSION_FOUND,
+					type: requestedCaptchaType
+				};
+			}
+			sessionId = resolvedSessionId;
+			if (this.writeQueue) await Promise.all([this.writeQueue.invalidateCachedSession(sessionId), sessionRecord.userSitekeyIpHash ? this.writeQueue.invalidateCachedSessionByHash(sessionRecord.userSitekeyIpHash) : Promise.resolve()]);
+			if (currentIP) {
+				const ipValidation = await this.validateSessionIP(sessionRecord, currentIP, env);
+				if (!ipValidation.valid) return {
+					valid: false,
+					reason: ipValidation.reason,
+					type: requestedCaptchaType
+				};
+			}
+			if (sessionRecord.captchaType !== requestedCaptchaType) {
+				this.logger.warn(() => ({
+					msg: "Session captcha type does not match requested type",
+					data: {
+						account: clientSettings.account,
+						sessionId,
+						sessionCaptchaType: sessionRecord.captchaType,
+						requestedCaptchaType
+					}
+				}));
+				return {
+					valid: false,
+					reason: ResultReason.INCORRECT_CAPTCHA_TYPE,
+					type: requestedCaptchaType
+				};
+			}
+			return {
+				valid: true,
+				sessionId: sessionRecord.sessionId,
+				type: requestedCaptchaType,
+				...sessionRecord.powDifficulty && { powDifficulty: sessionRecord.powDifficulty },
+				...sessionRecord.solvedImagesCount && { solvedImagesCount: sessionRecord.solvedImagesCount },
+				ipInfo: sessionRecord.ipInfo
+			};
+		}
+		if (clientSettings?.settings?.captchaType !== requestedCaptchaType) {
+			this.logger.warn(() => ({
+				msg: `Invalid ${requestedCaptchaType} request`,
+				data: {
+					account: clientSettings.account,
+					requestedCaptchaType,
+					settingsCaptchaType: clientSettings?.settings?.captchaType
+				}
+			}));
+			return {
+				valid: false,
+				reason: ResultReason.INCORRECT_CAPTCHA_TYPE,
+				type: requestedCaptchaType
+			};
+		}
+		return {
+			valid: true,
+			type: requestedCaptchaType
+		};
+	}
+	getVerificationResponse(verified, clientRecord, translateFn, score, reason) {
+		return {
+			status: translateFn(verified ? "API.USER_VERIFIED" : "API.USER_NOT_VERIFIED"),
+			[ApiParams.verified]: verified,
+			...CaptchaManager.canClientSeeScore(clientRecord.tier, score) && { [ApiParams.score]: score },
+			...!verified && clientRecord.tier !== Tier.Free && reason && { [ApiParams.reason]: reason }
+		};
+	}
+	async getPrioritisedAccessPolicies(userAccessRulesStorage, clientId, userScope, options) {
+		return getPrioritisedAccessRule(userAccessRulesStorage, userScope, clientId, options);
+	}
+	async getDetectorKeys() {
+		return await this.db.getDetectorKeys();
+	}
+	/**
+	* Decrypt the catcher's WASM SIMD CPU fingerprint readings via the
+	* obfuscated `decodeSimd.js` bundle (source lives in the private
+	* @prosopo/catcher repo). Mirrors `decryptBehavioralData`: tries each
+	* detector key in turn (loaded by the caller, with the env-var key as
+	* fallback). Returns null when no key works so the caller can drop
+	* the field rather than fail the whole request.
+	*/
+	async decryptSimdReadings(encryptedData, decryptKeys) {
+		const decryptSimdReadings = (await import("./detection/decodeSimd.js")).default;
+		const validKeys = decryptKeys.filter((k) => k);
+		if (validKeys.length === 0) {
+			this.logger?.error(() => ({ msg: "No decryption keys provided for SIMD readings" }));
+			return null;
+		}
+		for (const [keyIndex, key] of validKeys.entries()) try {
+			return await decryptSimdReadings(encryptedData, key);
+		} catch (err) {
+			this.logger?.debug(() => ({
+				msg: "Failed to decrypt SIMD readings with key, trying next",
+				data: {
+					keyIndex: keyIndex + 1,
+					totalKeys: validKeys.length,
+					err
+				}
+			}));
+		}
+		this.logger?.warn(() => ({
+			msg: "Failed to decrypt SIMD readings with all available keys",
+			data: { totalKeysAttempted: validKeys.length }
+		}));
+		return null;
+	}
+	async decryptBehavioralData(encryptedData, decryptKeys) {
+		const decryptBehavioralData = (await import("./detection/decodeBehavior.js")).default;
+		const validKeys = decryptKeys.filter((k) => k);
+		if (validKeys.length === 0) {
+			this.logger?.error(() => ({ msg: "No decryption keys provided for behavioral data" }));
+			return null;
+		}
+		for (const [keyIndex, key] of validKeys.entries()) try {
+			this.logger?.debug(() => ({
+				msg: "Attempting to decrypt behavioral data",
+				data: {
+					keyIndex: keyIndex + 1,
+					totalKeys: validKeys.length
+				}
+			}));
+			const result = await decryptBehavioralData(encryptedData, key);
+			this.logger?.info(() => ({
+				msg: "Behavioral data decrypted successfully",
+				data: {
+					keyIndex: keyIndex + 1,
+					c1Length: result.collector1?.length || 0,
+					c2Length: result.collector2?.length || 0,
+					c3Length: result.collector3?.length || 0,
+					deviceCapability: result.deviceCapability
+				}
+			}));
+			return result;
+		} catch (error) {
+			this.logger?.debug(() => ({
+				msg: "Failed to decrypt with key, trying next",
+				data: {
+					keyIndex: keyIndex + 1,
+					totalKeys: validKeys.length,
+					err: error
+				}
+			}));
+		}
+		this.logger?.error(() => ({
+			msg: "Failed to decrypt behavioral data with all available keys",
+			data: { totalKeysAttempted: validKeys.length }
+		}));
+		return null;
+	}
+	/**
+	* Checks if a user should be hard blocked based on access policies
+	* Only checks for Block policies without captchaType
+	*
+	* @returns The blocking policy if user should be blocked, undefined otherwise
+	*/
+	async checkForHardBlock(userAccessRulesStorage, challengeRecord, userAccount, headers, coords, countryCode, asn) {
+		let headHash;
+		if (challengeRecord.sessionId) headHash = (await this.db.getSessionRecordBySessionId(challengeRecord.sessionId))?.decryptedHeadHash;
+		const coordsString = coords ? JSON.stringify(coords) : void 0;
+		const ipAddressRecord = getIpAddressFromComposite(challengeRecord.ipAddress);
+		const userScope = getRequestUserScope(headers, challengeRecord.ja4, ipAddressRecord.address, userAccount, headHash, coordsString, countryCode, asn);
+		return findHardBlockPolicy(await this.getPrioritisedAccessPolicies(userAccessRulesStorage, challengeRecord.dappAccount, userScope, { blockOnly: true }));
+	}
+	/**
+	* Checks if the provided email address has a domain in the spam email domain list.
+	* Returns true if the email domain is spam (i.e. should be blocked), false otherwise.
+	* Handles formats: user@domain.com, @domain.com, domain.com
+	*/
+	async checkSpamEmail(email) {
+		return checkSpamEmail(email, this.db, this.config, this.logger);
+	}
+	/**
+	* Resolves the IP info to feed to `checkTrafficFilter` and runs the check.
+	*
+	* - The captcha record already carries the IPInfoResponse from request
+	*   time (ipInfoMiddleware → storeXxxRecord), so by default we reuse it
+	*   instead of hitting the sidecar again.
+	* - If the dapp's server passed up the end user's current IP via the
+	*   verify call, look that up fresh — it's the "now" IP for filtering
+	*   and may differ from the IP that originally requested the captcha.
+	* - When the session carries a `dnsEvent`, its `peerIp` and `resolverIp`
+	*   are enriched and passed alongside the primary IP.
+	* - `blockAbuser` defaults to true so abusive networks are always
+	*   blocked even when the site hasn't configured a trafficFilter.
+	* - Returns `{ isBlocked: false }` if every filter flag is off, without
+	*   consulting the payload at all.
+	*
+	* Callers handle the "blocked" branch themselves (each verify path
+	* updates record / session state differently); this helper just returns
+	* the verdict.
+	*/
+	async resolveTrafficFilterCheck(env, recordIpInfo, trafficFilter, currentIp, enrichedDnsEvent) {
+		const effective = {
+			blockAbuser: true,
+			...trafficFilter
+		};
+		if (!Object.values(effective).some((v) => v)) return { isBlocked: false };
+		return checkTrafficFilter(currentIp ? await env.ipInfoService.lookup(currentIp) : recordIpInfo, effective, extraIpInfosFromEnrichedDnsEvent(enrichedDnsEvent), enrichedDnsEvent?.pathValid);
+	}
+	static canClientSeeScore(tier, score) {
+		return score && tier && tier !== Tier.Free;
+	}
 };
+//#endregion
+export { CaptchaManager };