@prosopo/provider 4.15.14 → 4.15.16

package/dist/tasks/puzzleCaptcha/puzzleTasks.js

@@ -1,592 +1,423 @@
-import { u8aToHex, stringToHex } from "@polkadot/util";
-import { ProsopoApiError, ProsopoEnvError } from "@prosopo/common";
-import { POW_SEPARATOR, puzzleToleranceDefault, ApiParams, ResultReason, CaptchaStatus, CaptchaType, SimdReadingsStage, DecisionMachineDecision } from "@prosopo/types";
-import { at, extractData, assertCoordsSafe, verifyRecency } from "@prosopo/util";
-import { getIpAddressFromComposite, getCompositeIpAddress } from "../../compositeIpAddress.js";
-import { deepValidateIpAddress } from "../../util.js";
 import { buildAllWindowIncrements } from "../../util/usageCounters.js";
-import { CaptchaManager } from "../captchaManager.js";
 import { DecisionMachineRunner } from "../decisionMachine/decisionMachineRunner.js";
-import { enrichDnsEvent, getIpInfoAsn, computeDnsAsymmetry } from "../dnsEvent/enrichDnsEvent.js";
+import { getCompositeIpAddress, getIpAddressFromComposite } from "../../compositeIpAddress.js";
+import { computeDnsAsymmetry, enrichDnsEvent, getIpInfoAsn } from "../dnsEvent/enrichDnsEvent.js";
+import { CaptchaManager } from "../captchaManager.js";
+import { deepValidateIpAddress } from "../../util.js";
 import { computeFrictionlessScore } from "../frictionless/frictionlessTasksUtils.js";
 import { checkPowSignature } from "../powCaptcha/powTasksUtils.js";
 import { validatePuzzleSolution } from "./puzzleTasksUtils.js";
-class PuzzleCaptchaManager extends CaptchaManager {
-  constructor(db, pair, config, logger, usageCounters) {
-    super(db, pair, config, logger);
-    this.POW_SEPARATOR = POW_SEPARATOR;
-    this.decisionMachineRunner = new DecisionMachineRunner(db);
-    this.usageCounters = usageCounters ?? null;
-  }
-  /**
-   * @description Generates a Puzzle Captcha challenge for a given user and dapp
-   *
-   * @param {string} userAccount - user that is solving the captcha
-   * @param {string} dappAccount - dapp that is requesting the captcha
-   * @param origin - not currently used
-   * @param tolerance
-   */
-  async getPuzzleCaptchaChallenge(userAccount, dappAccount, origin, tolerance) {
-    const resolvedTolerance = tolerance ?? puzzleToleranceDefault;
-    const requestedAtTimestamp = Date.now();
-    const nonce = Math.floor(Math.random() * 1e6);
-    const challenge = `${requestedAtTimestamp}___${userAccount}___${dappAccount}___${nonce}`;
-    const challengeSignature = u8aToHex(this.pair.sign(stringToHex(challenge)));
-    const targetX = Math.floor(Math.random() * (280 - 150 + 1)) + 150;
-    const targetY = Math.floor(Math.random() * (170 - 30 + 1)) + 30;
-    const originX = Math.floor(Math.random() * (130 - 20 + 1)) + 20;
-    const originY = Math.floor(Math.random() * (170 - 30 + 1)) + 30;
-    return {
-      challenge,
-      targetX,
-      targetY,
-      originX,
-      originY,
-      tolerance: resolvedTolerance,
-      providerSignature: challengeSignature,
-      requestedAtTimestamp
-    };
-  }
-  /**
-   * @description Verifies a Puzzle Captcha solution for a given user and dapp
-   *
-   * @param {string} challenge - the challenge string
-   * @param {string} providerChallengeSignature - proof that the Provider provided the challenge
-   * @param {number} finalX - the final X coordinate of the puzzle
-   * @param {number} finalY - the final Y coordinate of the puzzle
-   * @param {PuzzleEvent[]} puzzleEvents - the puzzle event trail
-   * @param {number} timeout - the time in milliseconds since the Provider was selected to provide the captcha
-   * @param {string} userTimestampSignature
-   * @param ipAddress
-   * @param headers
-   * @param behavioralData
-   */
-  async verifyPuzzleCaptchaSolution(challenge, providerChallengeSignature, finalX, finalY, puzzleEvents, timeout, userTimestampSignature, ipAddress, headers, behavioralData, salt, simdReadings, clientMetaData) {
-    checkPowSignature(
-      challenge,
-      providerChallengeSignature,
-      this.pair.address,
-      ApiParams.challenge
-    );
-    const challengeSplit = challenge.split(this.POW_SEPARATOR);
-    const timestamp = Number.parseInt(at(challengeSplit, 0));
-    const userAccount = at(challengeSplit, 1);
-    checkPowSignature(
-      timestamp.toString(),
-      userTimestampSignature,
-      userAccount,
-      ApiParams.timestamp
-    );
-    const challengeRecord = await this.db.getPuzzleCaptchaRecordByChallenge(challenge);
-    if (!challengeRecord) {
-      this.logger.debug(() => ({
-        msg: `No record of this challenge: ${challenge}`
-      }));
-      return false;
-    }
-    let coords;
-    let saltDecodeError;
-    if (salt) {
-      try {
-        const extractedData = extractData(salt);
-        if (extractedData.length >= 2) {
-          const built = [
-            [[extractedData[0], extractedData[1]]]
-          ];
-          assertCoordsSafe(built, "coords");
-          coords = built;
-        }
-      } catch (error) {
-        saltDecodeError = error;
-        this.logger.warn(() => ({
-          msg: "Failed to extract coordinates from salt",
-          error,
-          salt
-        }));
-      }
-    }
-    if (challengeRecord.userSubmitted) {
-      this.logger.debug(() => ({
-        msg: `Challenge already submitted: ${challenge}`
-      }));
-      return false;
-    }
-    if (saltDecodeError) {
-      const badSaltResult = {
-        status: CaptchaStatus.disapproved,
-        reason: ResultReason.CAPTCHA_INVALID_SALT
-      };
-      await this.db.updatePuzzleCaptchaRecordResult(
-        challenge,
-        badSaltResult,
-        false,
-        // serverChecked
-        true,
-        // userSubmitted
-        userTimestampSignature,
-        void 0
-        // never persist the bad coords
-      );
-      if (challengeRecord.sessionId) {
-        await this.updateSessionRecordWithCache(challengeRecord.sessionId, {
-          userSubmitted: true,
-          result: badSaltResult
-        });
-      }
-      return false;
-    }
-    if (!verifyRecency(challenge, timeout)) {
-      const timeoutResult = {
-        status: CaptchaStatus.disapproved,
-        reason: ResultReason.CAPTCHA_INVALID_TIMESTAMP
-      };
-      await this.db.updatePuzzleCaptchaRecordResult(
-        challenge,
-        timeoutResult,
-        false,
-        //serverchecked
-        true,
-        // usersubmitted
-        userTimestampSignature,
-        coords
-      );
-      if (challengeRecord.sessionId) {
-        await this.updateSessionRecordWithCache(challengeRecord.sessionId, {
-          userSubmitted: true,
-          result: timeoutResult
-        });
-      }
-      return false;
-    }
-    const correct = validatePuzzleSolution(
-      finalX,
-      finalY,
-      challengeRecord.targetX,
-      challengeRecord.targetY,
-      challengeRecord.tolerance
-    );
-    let result = { status: CaptchaStatus.approved };
-    if (!correct) {
-      result = {
-        status: CaptchaStatus.disapproved,
-        reason: ResultReason.CAPTCHA_INVALID_SOLUTION
-      };
-    }
-    if (correct && this.usageCounters) {
-      const dappAccount = at(challengeSplit, 2);
-      this.usageCounters.incrManyAsync(
-        dappAccount,
-        buildAllWindowIncrements(
-          "solved",
-          CaptchaType.puzzle,
-          ipAddress.address,
-          userAccount
-        )
-      );
-    }
-    if (behavioralData) {
-      try {
-        const decryptKeys = [
-          // Process DB keys first, then env var key last as env key will likely be invalid
-          ...await this.getDetectorKeys(),
-          process.env.BOT_DECRYPTION_KEY
-        ];
-        const decryptedData = await this.decryptBehavioralData(
-          behavioralData,
-          decryptKeys
-        );
-        if (decryptedData) {
-          const dappAccount = at(challengeSplit, 2);
-          this.logger?.info(() => ({
-            msg: "Behavioral analysis completed",
-            data: {
-              userAccount,
-              dappAccount,
-              challenge,
-              mouseEventsCount: decryptedData.collector1?.length || 0,
-              touchEventsCount: decryptedData.collector2?.length || 0,
-              clickEventsCount: decryptedData.collector3?.length || 0,
-              deviceCapability: decryptedData.deviceCapability,
-              captchaResult: correct ? "passed" : "failed"
-            }
-          }));
-          const packedData = {
-            c1: decryptedData.collector1 || [],
-            c2: decryptedData.collector2 || [],
-            c3: decryptedData.collector3 || [],
-            d: decryptedData.deviceCapability
-          };
-          await this.db.updatePuzzleCaptchaRecord(challenge, {
-            behavioralDataPacked: packedData,
-            deviceCapability: decryptedData.deviceCapability,
-            puzzleEvents
-          });
-        }
-      } catch (error) {
-        this.logger?.error(() => ({
-          msg: "Failed to process behavioral data",
-          err: error
-        }));
-      }
-    } else {
-      await this.db.updatePuzzleCaptchaRecord(challenge, {
-        puzzleEvents
-      });
-    }
-    if (clientMetaData?.hp) {
-      await this.db.updatePuzzleCaptchaRecord(challenge, {
-        clientMetaData: { hp: clientMetaData.hp }
-      });
-    }
-    await this.db.updatePuzzleCaptchaRecordResult(
-      challenge,
-      result,
-      false,
-      true,
-      userTimestampSignature,
-      coords
-    );
-    if (challengeRecord.sessionId) {
-      const linkedSessionId = challengeRecord.sessionId;
-      await this.updateSessionRecordWithCache(linkedSessionId, {
-        userSubmitted: true,
-        result
-      });
-      if (simdReadings) {
-        await this.decryptAndAttachSimdReadingsIfAbsent(
-          linkedSessionId,
-          simdReadings,
-          SimdReadingsStage.submit
-        );
-      }
-    }
-    return correct;
-  }
-  /**
-   * @description Verifies a Puzzle Captcha for a given user and dapp. This is called by the server to verify the user's solution
-   * and update the record in the database to show that the user has solved the captcha
-   *
-   * @param {string} dappAccount - the dapp that is requesting the captcha
-   * @param {string} challenge - the challenge string
-   * @param {number} timeout - the time in milliseconds since the Provider was selected to provide the captcha
-   * @param env - provider environment
-   * @param ip - optional IP address for validation
-   * @param userAccessRulesStorage - storage for querying user access policies
-   * @param email
-   * @param spamEmailDomainCheckingEnabled
-   * @param trafficFilter
-   * @param storeMetadata - when true, persists the dapp-server-provided
-   *   `email` on the captcha record for spam-rate analysis.
-   */
-  async serverVerifyPuzzleCaptchaSolution(dappAccount, challenge, timeout, env, ip, userAccessRulesStorage, email, spamEmailDomainCheckingEnabled = false, trafficFilter, storeMetadata = false) {
-    const notVerifiedResponse = { verified: false };
-    const logger = this.logger.with({ challenge, dappAccount });
-    const challengeRecord = await this.db.getPuzzleCaptchaRecordByChallenge(challenge);
-    if (!challengeRecord) {
-      logger.debug(() => ({
-        msg: `No record of this challenge: ${challenge}`
-      }));
-      return notVerifiedResponse;
-    }
-    if (challengeRecord.result.status !== CaptchaStatus.approved) {
-      throw new ProsopoApiError("CAPTCHA.INVALID_SOLUTION", {
-        context: {
-          failedFuncName: this.serverVerifyPuzzleCaptchaSolution.name,
-          challenge
-        }
-      });
-    }
-    if (challengeRecord.serverChecked) return notVerifiedResponse;
-    const challengeDappAccount = challengeRecord.dappAccount;
-    if (dappAccount !== challengeDappAccount) {
-      throw new ProsopoEnvError("CAPTCHA.DAPP_USER_SOLUTION_NOT_FOUND", {
-        context: {
-          failedFuncName: this.serverVerifyPuzzleCaptchaSolution.name,
-          dappAccount,
-          challengeDappAccount
-        }
-      });
-    }
-    await this.db.updatePuzzleCaptchaRecord(challengeRecord.challenge, {
-      serverChecked: true,
-      lastUpdatedTimestamp: /* @__PURE__ */ new Date()
-    });
-    const submittedAt = challengeRecord.submittedAtTimestamp;
-    const submitToVerifyMs = submittedAt instanceof Date ? Date.now() - submittedAt.getTime() : Number.POSITIVE_INFINITY;
-    if (submitToVerifyMs > timeout) {
-      const disapprovedResult = {
-        status: CaptchaStatus.disapproved,
-        reason: ResultReason.TIMESTAMP_TOO_OLD
-      };
-      await this.db.updatePuzzleCaptchaRecord(challengeRecord.challenge, {
-        result: disapprovedResult
-      });
-      if (challengeRecord.sessionId) {
-        await this.updateSessionRecordWithCache(challengeRecord.sessionId, {
-          serverChecked: true,
-          result: disapprovedResult
-        });
-      }
-      return notVerifiedResponse;
-    }
-    if (userAccessRulesStorage) {
-      try {
-        const blockPolicy = await this.checkForHardBlock(
-          userAccessRulesStorage,
-          challengeRecord,
-          challengeRecord.userAccount,
-          challengeRecord.headers,
-          challengeRecord.coords,
-          challengeRecord.ipInfo?.isValid ? challengeRecord.ipInfo.countryCode : void 0,
-          challengeRecord.ipInfo?.isValid ? challengeRecord.ipInfo.asnNumber : void 0
-        );
-        if (blockPolicy) {
-          logger.info(() => ({
-            msg: "User blocked by access policy in server puzzle verification",
-            data: {
-              userAccount: challengeRecord.userAccount,
-              policy: blockPolicy
-            }
-          }));
-          const blockedResult = {
-            status: CaptchaStatus.disapproved,
-            reason: ResultReason.ACCESS_POLICY_BLOCK
-          };
-          await this.db.updatePuzzleCaptchaRecord(challengeRecord.challenge, {
-            result: blockedResult
-          });
-          if (challengeRecord.sessionId) {
-            await this.updateSessionRecordWithCache(challengeRecord.sessionId, {
-              serverChecked: true,
-              result: blockedResult
-            });
-          }
-          return notVerifiedResponse;
-        }
-      } catch (error) {
-        logger.warn(() => ({
-          msg: "Failed to check user access policies in server puzzle verification",
-          error
-        }));
-      }
-    }
-    if (email && spamEmailDomainCheckingEnabled) {
-      try {
-        const isSpam = await this.checkSpamEmail(email);
-        if (isSpam) {
-          const emailDomain = email.split("@")[1] || "unknown";
-          logger.info(() => ({
-            msg: "Spam email domain detected in server puzzle verification",
-            data: { emailDomain }
-          }));
-          await this.db.updatePuzzleCaptchaRecord(challengeRecord.challenge, {
-            result: {
-              status: CaptchaStatus.disapproved,
-              reason: ResultReason.SPAM_EMAIL_DOMAIN
-            }
-          });
-          return notVerifiedResponse;
-        }
-      } catch (error) {
-        logger.warn(() => ({
-          msg: "Failed to check spam email domain in server puzzle verification",
-          error
-        }));
-      }
-    }
-    const sessionRecord = challengeRecord.sessionId ? await this.db.getSessionRecordBySessionId(challengeRecord.sessionId) : void 0;
-    const enrichedDnsEvent = await enrichDnsEvent(
-      sessionRecord?.dnsEvent,
-      env.ipInfoService,
-      ip ?? challengeRecord.ipInfo?.ip
-    );
-    {
-      const check = await this.resolveTrafficFilterCheck(
-        env,
-        challengeRecord.ipInfo,
-        trafficFilter,
-        ip,
-        enrichedDnsEvent
-      );
-      if (check.isBlocked) {
-        logger.info(() => ({
-          msg: "Traffic filter rejected request in puzzle verification",
-          data: {
-            ip,
-            reason: check.reason,
-            dnsPeerIp: enrichedDnsEvent?.peerIp,
-            dnsResolverIp: enrichedDnsEvent?.resolverIp,
-            dnsPeerAsn: getIpInfoAsn(enrichedDnsEvent?.peerIpInfo),
-            dnsResolverAsn: getIpInfoAsn(enrichedDnsEvent?.resolverIpInfo),
-            dnsPathValid: enrichedDnsEvent?.pathValid
-          }
-        }));
-        const blockedResult = {
-          status: CaptchaStatus.disapproved,
-          reason: check.reason
-        };
-        await this.db.updatePuzzleCaptchaRecord(challengeRecord.challenge, {
-          result: blockedResult
-        });
-        if (challengeRecord.sessionId) {
-          await this.updateSessionRecordWithCache(challengeRecord.sessionId, {
-            serverChecked: true,
-            result: blockedResult
-          });
-        }
-        return notVerifiedResponse;
-      }
-    }
-    if (storeMetadata && email) {
-      await this.db.updatePuzzleCaptchaRecord(challengeRecord.challenge, {
-        metadata: { email }
-      });
-    }
-    if (ip) {
-      const challengeIpAddress = getIpAddressFromComposite(
-        challengeRecord.ipAddress
-      );
-      const clientRecord = await this.db.getClientRecord(dappAccount);
-      const ipValidationRules = clientRecord?.settings?.ipValidationRules;
-      await this.db.updatePuzzleCaptchaRecord(challengeRecord.challenge, {
-        providedIp: getCompositeIpAddress(ip)
-      });
-      if (ipValidationRules?.enabled === true) {
-        const ipValidation = await deepValidateIpAddress(
-          ip,
-          challengeIpAddress,
-          logger,
-          env.ipInfoService,
-          ipValidationRules,
-          enrichedDnsEvent?.peerIp
-        );
-        if (!ipValidation.isValid) {
-          logger.error(() => ({
-            msg: "IP validation failed for puzzle captcha",
-            data: {
-              ip,
-              challengeIp: challengeIpAddress.address,
-              error: ipValidation.errorMessage,
-              distanceKm: ipValidation.distanceKm
-            }
-          }));
-          const ipFailResult = {
-            status: CaptchaStatus.disapproved,
-            reason: ResultReason.FAILED_IP_VALIDATION
-          };
-          await this.db.updatePuzzleCaptchaRecord(challengeRecord.challenge, {
-            result: ipFailResult
-          });
-          if (challengeRecord.sessionId) {
-            await this.updateSessionRecordWithCache(challengeRecord.sessionId, {
-              serverChecked: true,
-              result: ipFailResult
-            });
-          }
-          return notVerifiedResponse;
-        }
-      }
-    }
-    let score;
-    if (sessionRecord) {
-      const dnsAsymmetry = computeDnsAsymmetry(
-        enrichedDnsEvent,
-        challengeRecord.ipInfo,
-        trafficFilter
-      );
-      if (dnsAsymmetry > 0) {
-        sessionRecord.scoreComponents = {
-          ...sessionRecord.scoreComponents,
-          dnsAsymmetry
-        };
-      }
-      score = computeFrictionlessScore(sessionRecord?.scoreComponents);
-      logger.info(() => ({
-        data: {
-          scoreComponents: { ...sessionRecord?.scoreComponents || {} },
-          score,
-          dnsPeerAsn: getIpInfoAsn(enrichedDnsEvent?.peerIpInfo),
-          dnsResolverAsn: getIpInfoAsn(enrichedDnsEvent?.resolverIpInfo)
-        }
-      }));
-    }
-    try {
-      const decisionInput = {
-        userAccount: challengeRecord.userAccount,
-        dappAccount: challengeRecord.dappAccount,
-        captchaResult: "passed",
-        headers: challengeRecord.headers,
-        captchaType: CaptchaType.puzzle,
-        behavioralDataPacked: challengeRecord.behavioralDataPacked,
-        deviceCapability: challengeRecord.deviceCapability,
-        countryCode: challengeRecord.ipInfo?.isValid ? challengeRecord.ipInfo.countryCode : void 0,
-        ipInfo: challengeRecord.ipInfo,
-        dnsEvent: enrichedDnsEvent,
-        score,
-        threshold: sessionRecord?.threshold,
-        scoreComponents: sessionRecord?.scoreComponents,
-        decryptedHeadHash: sessionRecord?.decryptedHeadHash,
-        userSitekeyIpHash: sessionRecord?.userSitekeyIpHash,
-        simdReadings: sessionRecord?.simdReadings,
-        frictionlessReason: sessionRecord?.reason,
-        ruleType: sessionRecord?.ruleType,
-        webView: sessionRecord?.webView,
-        iFrame: sessionRecord?.iFrame,
-        coords: challengeRecord.coords,
-        puzzleEvents: challengeRecord.puzzleEvents
-      };
-      const decision = await this.decisionMachineRunner.decide(
-        decisionInput,
-        logger
-      );
-      if (decision.decision === DecisionMachineDecision.Deny) {
-        logger.info(() => ({
-          msg: "Decision machine denied puzzle captcha in server verification",
-          data: {
-            userAccount: challengeRecord.userAccount,
-            reason: decision.reason,
-            score: decision.score,
-            tags: decision.tags
-          }
-        }));
-        const dmResult = {
-          status: CaptchaStatus.disapproved,
-          reason: decision.reason || ResultReason.CAPTCHA_DECISION_MACHINE_DENIED
-        };
-        await this.db.updatePuzzleCaptchaRecord(challengeRecord.challenge, {
-          result: dmResult
-        });
-        if (challengeRecord.sessionId) {
-          await this.updateSessionRecordWithCache(challengeRecord.sessionId, {
-            serverChecked: true,
-            result: dmResult
-          });
-        }
-        return notVerifiedResponse;
-      }
-      logger.debug(() => ({
-        msg: "Decision machine allowed puzzle captcha",
-        data: {
-          reason: decision.reason,
-          score: decision.score,
-          tags: decision.tags
-        }
-      }));
-    } catch (error) {
-      logger.error(() => ({
-        msg: "Failed to run decision machine in server puzzle verification",
-        err: error
-      }));
-    }
-    if (challengeRecord.sessionId) {
-      await this.updateSessionRecordWithCache(challengeRecord.sessionId, {
-        serverChecked: true,
-        result: { status: CaptchaStatus.approved }
-      });
-    }
-    return { verified: true, ...score ? { score } : {} };
-  }
-}
-export {
-  PuzzleCaptchaManager
+import { ProsopoApiError, ProsopoEnvError } from "@prosopo/common";
+import { ApiParams, CaptchaStatus, CaptchaType, DecisionMachineDecision, POW_SEPARATOR, ResultReason, SimdReadingsStage, puzzleToleranceDefault } from "@prosopo/types";
+import { assertCoordsSafe, at, extractData, verifyRecency } from "@prosopo/util";
+import { stringToHex, u8aToHex } from "@polkadot/util";
+//#region src/tasks/puzzleCaptcha/puzzleTasks.ts
+var PuzzleCaptchaManager = class extends CaptchaManager {
+	constructor(db, pair, config, logger, usageCounters) {
+		super(db, pair, config, logger);
+		this.POW_SEPARATOR = POW_SEPARATOR;
+		this.decisionMachineRunner = new DecisionMachineRunner(db);
+		this.usageCounters = usageCounters ?? null;
+	}
+	/**
+	* @description Generates a Puzzle Captcha challenge for a given user and dapp
+	*
+	* @param {string} userAccount - user that is solving the captcha
+	* @param {string} dappAccount - dapp that is requesting the captcha
+	* @param origin - not currently used
+	* @param tolerance
+	*/
+	async getPuzzleCaptchaChallenge(userAccount, dappAccount, origin, tolerance) {
+		const resolvedTolerance = tolerance ?? puzzleToleranceDefault;
+		const requestedAtTimestamp = Date.now();
+		const challenge = `${requestedAtTimestamp}___${userAccount}___${dappAccount}___${Math.floor(Math.random() * 1e6)}`;
+		const challengeSignature = u8aToHex(this.pair.sign(stringToHex(challenge)));
+		return {
+			challenge,
+			targetX: Math.floor(Math.random() * 131) + 150,
+			targetY: Math.floor(Math.random() * 141) + 30,
+			originX: Math.floor(Math.random() * 111) + 20,
+			originY: Math.floor(Math.random() * 141) + 30,
+			tolerance: resolvedTolerance,
+			providerSignature: challengeSignature,
+			requestedAtTimestamp
+		};
+	}
+	/**
+	* @description Verifies a Puzzle Captcha solution for a given user and dapp
+	*
+	* @param {string} challenge - the challenge string
+	* @param {string} providerChallengeSignature - proof that the Provider provided the challenge
+	* @param {number} finalX - the final X coordinate of the puzzle
+	* @param {number} finalY - the final Y coordinate of the puzzle
+	* @param {PuzzleEvent[]} puzzleEvents - the puzzle event trail
+	* @param {number} timeout - the time in milliseconds since the Provider was selected to provide the captcha
+	* @param {string} userTimestampSignature
+	* @param ipAddress
+	* @param headers
+	* @param behavioralData
+	*/
+	async verifyPuzzleCaptchaSolution(challenge, providerChallengeSignature, finalX, finalY, puzzleEvents, timeout, userTimestampSignature, ipAddress, headers, behavioralData, salt, simdReadings, clientMetaData) {
+		checkPowSignature(challenge, providerChallengeSignature, this.pair.address, ApiParams.challenge);
+		const challengeSplit = challenge.split(this.POW_SEPARATOR);
+		const timestamp = Number.parseInt(at(challengeSplit, 0));
+		const userAccount = at(challengeSplit, 1);
+		checkPowSignature(timestamp.toString(), userTimestampSignature, userAccount, ApiParams.timestamp);
+		const challengeRecord = await this.db.getPuzzleCaptchaRecordByChallenge(challenge);
+		if (!challengeRecord) {
+			this.logger.debug(() => ({ msg: `No record of this challenge: ${challenge}` }));
+			return false;
+		}
+		let coords;
+		let saltDecodeError;
+		if (salt) try {
+			const extractedData = extractData(salt);
+			if (extractedData.length >= 2) {
+				const built = [[[extractedData[0], extractedData[1]]]];
+				assertCoordsSafe(built, "coords");
+				coords = built;
+			}
+		} catch (error) {
+			saltDecodeError = error;
+			this.logger.warn(() => ({
+				msg: "Failed to extract coordinates from salt",
+				error,
+				salt
+			}));
+		}
+		if (challengeRecord.userSubmitted) {
+			this.logger.debug(() => ({ msg: `Challenge already submitted: ${challenge}` }));
+			return false;
+		}
+		if (saltDecodeError) {
+			const badSaltResult = {
+				status: CaptchaStatus.disapproved,
+				reason: ResultReason.CAPTCHA_INVALID_SALT
+			};
+			await this.db.updatePuzzleCaptchaRecordResult(challenge, badSaltResult, false, true, userTimestampSignature, void 0);
+			if (challengeRecord.sessionId) await this.updateSessionRecordWithCache(challengeRecord.sessionId, {
+				userSubmitted: true,
+				result: badSaltResult
+			});
+			return false;
+		}
+		if (!verifyRecency(challenge, timeout)) {
+			const timeoutResult = {
+				status: CaptchaStatus.disapproved,
+				reason: ResultReason.CAPTCHA_INVALID_TIMESTAMP
+			};
+			await this.db.updatePuzzleCaptchaRecordResult(challenge, timeoutResult, false, true, userTimestampSignature, coords);
+			if (challengeRecord.sessionId) await this.updateSessionRecordWithCache(challengeRecord.sessionId, {
+				userSubmitted: true,
+				result: timeoutResult
+			});
+			return false;
+		}
+		const correct = validatePuzzleSolution(finalX, finalY, challengeRecord.targetX, challengeRecord.targetY, challengeRecord.tolerance);
+		let result = { status: CaptchaStatus.approved };
+		if (!correct) result = {
+			status: CaptchaStatus.disapproved,
+			reason: ResultReason.CAPTCHA_INVALID_SOLUTION
+		};
+		if (correct && this.usageCounters) {
+			const dappAccount = at(challengeSplit, 2);
+			this.usageCounters.incrManyAsync(dappAccount, buildAllWindowIncrements("solved", CaptchaType.puzzle, ipAddress.address, userAccount));
+		}
+		if (behavioralData) try {
+			const decryptKeys = [...await this.getDetectorKeys(), process.env.BOT_DECRYPTION_KEY];
+			const decryptedData = await this.decryptBehavioralData(behavioralData, decryptKeys);
+			if (decryptedData) {
+				const dappAccount = at(challengeSplit, 2);
+				this.logger?.info(() => ({
+					msg: "Behavioral analysis completed",
+					data: {
+						userAccount,
+						dappAccount,
+						challenge,
+						mouseEventsCount: decryptedData.collector1?.length || 0,
+						touchEventsCount: decryptedData.collector2?.length || 0,
+						clickEventsCount: decryptedData.collector3?.length || 0,
+						deviceCapability: decryptedData.deviceCapability,
+						captchaResult: correct ? "passed" : "failed"
+					}
+				}));
+				const packedData = {
+					c1: decryptedData.collector1 || [],
+					c2: decryptedData.collector2 || [],
+					c3: decryptedData.collector3 || [],
+					d: decryptedData.deviceCapability
+				};
+				await this.db.updatePuzzleCaptchaRecord(challenge, {
+					behavioralDataPacked: packedData,
+					deviceCapability: decryptedData.deviceCapability,
+					puzzleEvents
+				});
+			}
+		} catch (error) {
+			this.logger?.error(() => ({
+				msg: "Failed to process behavioral data",
+				err: error
+			}));
+		}
+		else await this.db.updatePuzzleCaptchaRecord(challenge, { puzzleEvents });
+		if (clientMetaData?.hp) await this.db.updatePuzzleCaptchaRecord(challenge, { clientMetaData: { hp: clientMetaData.hp } });
+		await this.db.updatePuzzleCaptchaRecordResult(challenge, result, false, true, userTimestampSignature, coords);
+		if (challengeRecord.sessionId) {
+			const linkedSessionId = challengeRecord.sessionId;
+			await this.updateSessionRecordWithCache(linkedSessionId, {
+				userSubmitted: true,
+				result
+			});
+			if (simdReadings) await this.decryptAndAttachSimdReadingsIfAbsent(linkedSessionId, simdReadings, SimdReadingsStage.submit);
+		}
+		return correct;
+	}
+	/**
+	* @description Verifies a Puzzle Captcha for a given user and dapp. This is called by the server to verify the user's solution
+	* and update the record in the database to show that the user has solved the captcha
+	*
+	* @param {string} dappAccount - the dapp that is requesting the captcha
+	* @param {string} challenge - the challenge string
+	* @param {number} timeout - the time in milliseconds since the Provider was selected to provide the captcha
+	* @param env - provider environment
+	* @param ip - optional IP address for validation
+	* @param userAccessRulesStorage - storage for querying user access policies
+	* @param email
+	* @param spamEmailDomainCheckingEnabled
+	* @param trafficFilter
+	* @param storeMetadata - when true, persists the dapp-server-provided
+	*   `email` on the captcha record for spam-rate analysis.
+	*/
+	async serverVerifyPuzzleCaptchaSolution(dappAccount, challenge, timeout, env, ip, userAccessRulesStorage, email, spamEmailDomainCheckingEnabled = false, trafficFilter, storeMetadata = false) {
+		const notVerifiedResponse = { verified: false };
+		const logger = this.logger.with({
+			challenge,
+			dappAccount
+		});
+		const challengeRecord = await this.db.getPuzzleCaptchaRecordByChallenge(challenge);
+		if (!challengeRecord) {
+			logger.debug(() => ({ msg: `No record of this challenge: ${challenge}` }));
+			return notVerifiedResponse;
+		}
+		if (challengeRecord.result.status !== CaptchaStatus.approved) throw new ProsopoApiError("CAPTCHA.INVALID_SOLUTION", { context: {
+			code: 400,
+			failedFuncName: this.serverVerifyPuzzleCaptchaSolution.name,
+			challenge
+		} });
+		if (challengeRecord.serverChecked) return notVerifiedResponse;
+		const challengeDappAccount = challengeRecord.dappAccount;
+		if (dappAccount !== challengeDappAccount) throw new ProsopoEnvError("CAPTCHA.DAPP_USER_SOLUTION_NOT_FOUND", { context: {
+			failedFuncName: this.serverVerifyPuzzleCaptchaSolution.name,
+			dappAccount,
+			challengeDappAccount
+		} });
+		await this.db.updatePuzzleCaptchaRecord(challengeRecord.challenge, {
+			serverChecked: true,
+			lastUpdatedTimestamp: /* @__PURE__ */ new Date()
+		});
+		const submittedAt = challengeRecord.submittedAtTimestamp;
+		if ((submittedAt instanceof Date ? Date.now() - submittedAt.getTime() : Number.POSITIVE_INFINITY) > timeout) {
+			const disapprovedResult = {
+				status: CaptchaStatus.disapproved,
+				reason: ResultReason.TIMESTAMP_TOO_OLD
+			};
+			await this.db.updatePuzzleCaptchaRecord(challengeRecord.challenge, { result: disapprovedResult });
+			if (challengeRecord.sessionId) await this.updateSessionRecordWithCache(challengeRecord.sessionId, {
+				serverChecked: true,
+				result: disapprovedResult
+			});
+			return notVerifiedResponse;
+		}
+		if (userAccessRulesStorage) try {
+			const blockPolicy = await this.checkForHardBlock(userAccessRulesStorage, challengeRecord, challengeRecord.userAccount, challengeRecord.headers, challengeRecord.coords, challengeRecord.ipInfo?.isValid ? challengeRecord.ipInfo.countryCode : void 0, challengeRecord.ipInfo?.isValid ? challengeRecord.ipInfo.asnNumber : void 0);
+			if (blockPolicy) {
+				logger.info(() => ({
+					msg: "User blocked by access policy in server puzzle verification",
+					data: {
+						userAccount: challengeRecord.userAccount,
+						policy: blockPolicy
+					}
+				}));
+				const blockedResult = {
+					status: CaptchaStatus.disapproved,
+					reason: ResultReason.ACCESS_POLICY_BLOCK
+				};
+				await this.db.updatePuzzleCaptchaRecord(challengeRecord.challenge, { result: blockedResult });
+				if (challengeRecord.sessionId) await this.updateSessionRecordWithCache(challengeRecord.sessionId, {
+					serverChecked: true,
+					result: blockedResult
+				});
+				return notVerifiedResponse;
+			}
+		} catch (error) {
+			logger.warn(() => ({
+				msg: "Failed to check user access policies in server puzzle verification",
+				error
+			}));
+		}
+		if (email && spamEmailDomainCheckingEnabled) try {
+			if (await this.checkSpamEmail(email)) {
+				const emailDomain = email.split("@")[1] || "unknown";
+				logger.info(() => ({
+					msg: "Spam email domain detected in server puzzle verification",
+					data: { emailDomain }
+				}));
+				await this.db.updatePuzzleCaptchaRecord(challengeRecord.challenge, { result: {
+					status: CaptchaStatus.disapproved,
+					reason: ResultReason.SPAM_EMAIL_DOMAIN
+				} });
+				return notVerifiedResponse;
+			}
+		} catch (error) {
+			logger.warn(() => ({
+				msg: "Failed to check spam email domain in server puzzle verification",
+				error
+			}));
+		}
+		const sessionRecord = challengeRecord.sessionId ? await this.db.getSessionRecordBySessionId(challengeRecord.sessionId) : void 0;
+		const enrichedDnsEvent = await enrichDnsEvent(sessionRecord?.dnsEvent, env.ipInfoService, ip ?? challengeRecord.ipInfo?.ip);
+		{
+			const check = await this.resolveTrafficFilterCheck(env, challengeRecord.ipInfo, trafficFilter, ip, enrichedDnsEvent);
+			if (check.isBlocked) {
+				logger.info(() => ({
+					msg: "Traffic filter rejected request in puzzle verification",
+					data: {
+						ip,
+						reason: check.reason,
+						dnsPeerIp: enrichedDnsEvent?.peerIp,
+						dnsResolverIp: enrichedDnsEvent?.resolverIp,
+						dnsPeerAsn: getIpInfoAsn(enrichedDnsEvent?.peerIpInfo),
+						dnsResolverAsn: getIpInfoAsn(enrichedDnsEvent?.resolverIpInfo),
+						dnsPathValid: enrichedDnsEvent?.pathValid
+					}
+				}));
+				const blockedResult = {
+					status: CaptchaStatus.disapproved,
+					reason: check.reason
+				};
+				await this.db.updatePuzzleCaptchaRecord(challengeRecord.challenge, { result: blockedResult });
+				if (challengeRecord.sessionId) await this.updateSessionRecordWithCache(challengeRecord.sessionId, {
+					serverChecked: true,
+					result: blockedResult
+				});
+				return notVerifiedResponse;
+			}
+		}
+		if (storeMetadata && email) await this.db.updatePuzzleCaptchaRecord(challengeRecord.challenge, { metadata: { email } });
+		if (ip) {
+			const challengeIpAddress = getIpAddressFromComposite(challengeRecord.ipAddress);
+			const ipValidationRules = (await this.db.getClientRecord(dappAccount))?.settings?.ipValidationRules;
+			await this.db.updatePuzzleCaptchaRecord(challengeRecord.challenge, { providedIp: getCompositeIpAddress(ip) });
+			if (ipValidationRules?.enabled === true) {
+				const ipValidation = await deepValidateIpAddress(ip, challengeIpAddress, logger, env.ipInfoService, ipValidationRules, enrichedDnsEvent?.peerIp);
+				if (!ipValidation.isValid) {
+					logger.error(() => ({
+						msg: "IP validation failed for puzzle captcha",
+						data: {
+							ip,
+							challengeIp: challengeIpAddress.address,
+							error: ipValidation.errorMessage,
+							distanceKm: ipValidation.distanceKm
+						}
+					}));
+					const ipFailResult = {
+						status: CaptchaStatus.disapproved,
+						reason: ResultReason.FAILED_IP_VALIDATION
+					};
+					await this.db.updatePuzzleCaptchaRecord(challengeRecord.challenge, { result: ipFailResult });
+					if (challengeRecord.sessionId) await this.updateSessionRecordWithCache(challengeRecord.sessionId, {
+						serverChecked: true,
+						result: ipFailResult
+					});
+					return notVerifiedResponse;
+				}
+			}
+		}
+		let score;
+		if (sessionRecord) {
+			const dnsAsymmetry = computeDnsAsymmetry(enrichedDnsEvent, challengeRecord.ipInfo, trafficFilter);
+			if (dnsAsymmetry > 0) sessionRecord.scoreComponents = {
+				...sessionRecord.scoreComponents,
+				dnsAsymmetry
+			};
+			score = computeFrictionlessScore(sessionRecord?.scoreComponents);
+			logger.info(() => ({ data: {
+				scoreComponents: { ...sessionRecord?.scoreComponents || {} },
+				score,
+				dnsPeerAsn: getIpInfoAsn(enrichedDnsEvent?.peerIpInfo),
+				dnsResolverAsn: getIpInfoAsn(enrichedDnsEvent?.resolverIpInfo)
+			} }));
+		}
+		try {
+			const decisionInput = {
+				userAccount: challengeRecord.userAccount,
+				dappAccount: challengeRecord.dappAccount,
+				captchaResult: "passed",
+				headers: challengeRecord.headers,
+				captchaType: CaptchaType.puzzle,
+				behavioralDataPacked: challengeRecord.behavioralDataPacked,
+				deviceCapability: challengeRecord.deviceCapability,
+				countryCode: challengeRecord.ipInfo?.isValid ? challengeRecord.ipInfo.countryCode : void 0,
+				ipInfo: challengeRecord.ipInfo,
+				dnsEvent: enrichedDnsEvent,
+				score,
+				threshold: sessionRecord?.threshold,
+				scoreComponents: sessionRecord?.scoreComponents,
+				decryptedHeadHash: sessionRecord?.decryptedHeadHash,
+				userSitekeyIpHash: sessionRecord?.userSitekeyIpHash,
+				simdReadings: sessionRecord?.simdReadings,
+				frictionlessReason: sessionRecord?.reason,
+				ruleType: sessionRecord?.ruleType,
+				webView: sessionRecord?.webView,
+				iFrame: sessionRecord?.iFrame,
+				coords: challengeRecord.coords,
+				puzzleEvents: challengeRecord.puzzleEvents
+			};
+			const decision = await this.decisionMachineRunner.decide(decisionInput, logger);
+			if (decision.decision === DecisionMachineDecision.Deny) {
+				logger.info(() => ({
+					msg: "Decision machine denied puzzle captcha in server verification",
+					data: {
+						userAccount: challengeRecord.userAccount,
+						reason: decision.reason,
+						score: decision.score,
+						tags: decision.tags
+					}
+				}));
+				const dmResult = {
+					status: CaptchaStatus.disapproved,
+					reason: decision.reason || ResultReason.CAPTCHA_DECISION_MACHINE_DENIED
+				};
+				await this.db.updatePuzzleCaptchaRecord(challengeRecord.challenge, { result: dmResult });
+				if (challengeRecord.sessionId) await this.updateSessionRecordWithCache(challengeRecord.sessionId, {
+					serverChecked: true,
+					result: dmResult
+				});
+				return notVerifiedResponse;
+			}
+			logger.debug(() => ({
+				msg: "Decision machine allowed puzzle captcha",
+				data: {
+					reason: decision.reason,
+					score: decision.score,
+					tags: decision.tags
+				}
+			}));
+		} catch (error) {
+			logger.error(() => ({
+				msg: "Failed to run decision machine in server puzzle verification",
+				err: error
+			}));
+		}
+		if (challengeRecord.sessionId) await this.updateSessionRecordWithCache(challengeRecord.sessionId, {
+			serverChecked: true,
+			result: { status: CaptchaStatus.approved }
+		});
+		return {
+			verified: true,
+			...score ? { score } : {}
+		};
+	}
 };
+//#endregion
+export { PuzzleCaptchaManager };