@prosopo/provider 4.15.14 → 4.15.16

package/dist/tasks/powCaptcha/powTasks.js

@@ -1,688 +1,492 @@
-import { u8aToHex, stringToHex } from "@polkadot/util";
-import { ProsopoApiError, ProsopoEnvError } from "@prosopo/common";
-import { POW_SEPARATOR, ApiParams, ResultReason, CaptchaStatus, CaptchaType, SimdReadingsStage, FrictionlessReason, 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 { computeFrictionlessScore } from "../frictionless/frictionlessTasksUtils.js";
+import { getCompositeIpAddress, getIpAddressFromComposite } from "../../compositeIpAddress.js";
+import { computeDnsAsymmetry, enrichDnsEvent, getIpInfoAsn } from "../dnsEvent/enrichDnsEvent.js";
+import { CaptchaManager } from "../captchaManager.js";
 import { applyRouter } from "../frictionless/routingMachine.js";
+import { deepValidateIpAddress } from "../../util.js";
+import { computeFrictionlessScore } from "../frictionless/frictionlessTasksUtils.js";
 import { evaluateEmailSpamRules } from "../spam/evaluateEmailSpamRules.js";
 import { checkPowSignature, validateSolution } from "./powTasksUtils.js";
-const DEFAULT_POW_DIFFICULTY = 4;
-class PowCaptchaManager extends CaptchaManager {
-  constructor(db, pair, config, logger, writeQueue, usageCounters) {
-    super(db, pair, config, logger, writeQueue);
-    this.POW_SEPARATOR = POW_SEPARATOR;
-    this.decisionMachineRunner = new DecisionMachineRunner(db);
-    this.usageCounters = usageCounters ?? null;
-  }
-  /**
-   * Provide the request-side data needed to run the post-pow routing pass
-   * inside `verifyPowCaptchaSolution`. When unset, the routing pass is
-   * skipped and verification behaves exactly as before.
-   */
-  setPostPowContext(ctx) {
-    this.postPowContext = ctx;
-  }
-  /**
-   * @description Generates a PoW Captcha 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 powDifficulty
-   */
-  async getPowCaptchaChallenge(userAccount, dappAccount, origin, powDifficulty) {
-    const difficulty = powDifficulty || DEFAULT_POW_DIFFICULTY;
-    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)));
-    return {
-      challenge,
-      difficulty,
-      providerSignature: challengeSignature,
-      requestedAtTimestamp
-    };
-  }
-  /**
-   * @description Verifies a PoW Captcha for a given user and dapp
-   *
-   * @param {string} challenge - the starting string for the PoW challenge
-   * @param {string} providerChallengeSignature - proof that the Provider provided the challenge
-   * @param {string} nonce - the string that the user has found that satisfies the PoW challenge
-   * @param {number} timeout - the time in milliseconds since the Provider was selected to provide the PoW captcha
-   * @param {string} userTimestampSignature
-   * @param ipAddress
-   * @param headers
-   * @param behavioralData
-   * @param salt
-   */
-  async verifyPowCaptchaSolution(challenge, providerChallengeSignature, nonce, 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.getPowCaptchaRecordByChallenge(challenge);
-    if (!challengeRecord) {
-      this.logger.debug(() => ({
-        msg: `No record of this challenge: ${challenge}`
-      }));
-      return { verified: false };
-    }
-    const difficulty = challengeRecord.difficulty;
-    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 (saltDecodeError) {
-      const badSaltResult = {
-        status: CaptchaStatus.disapproved,
-        reason: ResultReason.CAPTCHA_INVALID_SALT
-      };
-      const writePromises2 = [
-        this.db.updatePowCaptchaRecordResult(
-          challenge,
-          badSaltResult,
-          false,
-          // serverChecked
-          true,
-          // userSubmitted
-          userTimestampSignature,
-          void 0
-          // never persist the bad coords
-        )
-      ];
-      if (challengeRecord.sessionId) {
-        writePromises2.push(
-          this.updateSessionRecordWithCache(challengeRecord.sessionId, {
-            userSubmitted: true,
-            result: badSaltResult
-          })
-        );
-      }
-      await Promise.all(writePromises2);
-      return { verified: false };
-    }
-    if (!verifyRecency(challenge, timeout)) {
-      const timeoutResult = {
-        status: CaptchaStatus.disapproved,
-        reason: ResultReason.CAPTCHA_INVALID_TIMESTAMP
-      };
-      const writePromises2 = [
-        this.db.updatePowCaptchaRecordResult(
-          challenge,
-          timeoutResult,
-          false,
-          //serverchecked
-          true,
-          // usersubmitted
-          userTimestampSignature,
-          coords
-        )
-      ];
-      if (challengeRecord.sessionId) {
-        writePromises2.push(
-          this.updateSessionRecordWithCache(challengeRecord.sessionId, {
-            userSubmitted: true,
-            result: timeoutResult
-          })
-        );
-      }
-      await Promise.all(writePromises2);
-      return { verified: false };
-    }
-    const correct = validateSolution(nonce, challenge, difficulty);
-    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.pow,
-          ipAddress.address,
-          userAccount
-        )
-      );
-    }
-    let behavioralUpdates = {};
-    let decryptedBehavioralDataPacked;
-    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
-          };
-          behavioralUpdates = {
-            behavioralDataPacked: packedData,
-            deviceCapability: decryptedData.deviceCapability
-          };
-          decryptedBehavioralDataPacked = packedData;
-        }
-      } catch (error) {
-        this.logger?.error(() => ({
-          msg: "Failed to process behavioral data",
-          err: error
-        }));
-      }
-    }
-    const recordUpdates = { ...behavioralUpdates };
-    if (clientMetaData?.hp) {
-      recordUpdates.clientMetaData = { hp: clientMetaData.hp };
-    }
-    if (Object.keys(recordUpdates).length > 0) {
-      await this.db.updatePowCaptchaRecord(challenge, recordUpdates);
-    }
-    const writePromises = [
-      this.db.updatePowCaptchaRecordResult(
-        challenge,
-        result,
-        false,
-        true,
-        userTimestampSignature,
-        coords
-      )
-    ];
-    if (challengeRecord.sessionId) {
-      const linkedSessionId = challengeRecord.sessionId;
-      writePromises.push(
-        this.updateSessionRecordWithCache(linkedSessionId, {
-          userSubmitted: true,
-          result
-        })
-      );
-      if (simdReadings) {
-        writePromises.push(
-          this.decryptAndAttachSimdReadingsIfAbsent(
-            linkedSessionId,
-            simdReadings,
-            SimdReadingsStage.submit
-          )
-        );
-      }
-    }
-    await Promise.all(writePromises);
-    if (!correct) {
-      return { verified: correct };
-    }
-    const escalateForMissingCoords = !coords && Boolean(challengeRecord.sessionId);
-    let routingOutput = this.postPowContext ? await this.runPostPowRouting({
-      challengeRecord,
-      challengeSplit,
-      behavioralDataPacked: decryptedBehavioralDataPacked
-    }) : void 0;
-    if (escalateForMissingCoords && routingOutput?.captchaType !== CaptchaType.image && routingOutput?.captchaType !== CaptchaType.puzzle) {
-      routingOutput = {
-        captchaType: CaptchaType.image,
-        reason: FrictionlessReason.MISSING_COORDINATES
-      };
-    }
-    return { verified: correct, routingOutput };
-  }
-  /**
-   * Resolve the originating session, build a full RoutingContext, and run the
-   * post-pow phase of the routing machine. Returns the machine's output, or
-   * undefined when prerequisites are missing (no session, no score) — in
-   * which case the caller treats the result as "no escalation".
-   */
-  async runPostPowRouting(args) {
-    if (!this.postPowContext) return void 0;
-    const { challengeRecord, challengeSplit, behavioralDataPacked } = args;
-    if (!challengeRecord.sessionId) {
-      this.logger.debug(() => ({
-        msg: "Skipping post-pow routing: PoW record has no linked session"
-      }));
-      return void 0;
-    }
-    const sessionRecord = await this.db.getSessionRecordBySessionId(
-      challengeRecord.sessionId
-    );
-    if (!sessionRecord) {
-      this.logger.debug(() => ({
-        msg: "Skipping post-pow routing: session record not found",
-        data: { sessionId: challengeRecord.sessionId }
-      }));
-      return void 0;
-    }
-    const score = computeFrictionlessScore(sessionRecord.scoreComponents);
-    const dappAccount = at(challengeSplit, 2);
-    const userAccount = at(challengeSplit, 1);
-    const platform = {
-      ...this.postPowContext.platform,
-      isWebView: sessionRecord.webView
-    };
-    const ctx = {
-      dappAccount,
-      userAccount,
-      ip: this.postPowContext.ip,
-      countryCode: this.postPowContext.countryCode,
-      score,
-      platform,
-      raw: {
-        ...this.postPowContext.raw,
-        ...behavioralDataPacked && { behavioralDataPacked },
-        // SIMD readings are decrypted and attached to the session above
-        // (decryptAndAttachSimdReadingsIfAbsent) before this re-fetch, so
-        // they are available here in decoded form for the routing machine.
-        ...sessionRecord.simdReadings && { simd: sessionRecord.simdReadings },
-        // currentUrl / iframeUrl were captured at frictionless time
-        // from the widget's payload — the submit request has no
-        // equivalent signal (its Referer is the captcha iframe, not
-        // the host page) so we surface them from the persisted
-        // session. iframeUrl is only present when the widget was
-        // embedded at frictionless time.
-        ...sessionRecord.currentUrl && {
-          currentUrl: sessionRecord.currentUrl
-        },
-        ...sessionRecord.iframeUrl && {
-          iframeUrl: sessionRecord.iframeUrl
-        }
-      }
-    };
-    const baseline = {
-      captchaType: CaptchaType.pow,
-      powDifficulty: challengeRecord.difficulty
-    };
-    return applyRouter(
-      this.decisionMachineRunner,
-      this.usageCounters,
-      baseline,
-      ctx,
-      this.logger,
-      "postPow"
-    );
-  }
-  /**
-   * @description Verifies a PoW 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 starting string for the PoW challenge
-   * @param {number} timeout - the time in milliseconds since the Provider was selected to provide the PoW 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 spamFilter
-   * @param trafficFilter
-   * @param storeMetadata - when true, persists the dapp-server-provided
-   *   `email` (and any future metadata fields) on the captcha record so
-   *   it can be inspected for spam-rate analysis.
-   */
-  async serverVerifyPowCaptchaSolution(dappAccount, challenge, timeout, env, ip, userAccessRulesStorage, email, spamEmailDomainCheckingEnabled = false, spamFilter, trafficFilter, storeMetadata = false) {
-    const notVerified = (reason) => ({
-      verified: false,
-      reason
-    });
-    const logger = this.logger.with({ challenge, dappAccount });
-    const challengeRecord = await this.db.getPowCaptchaRecordByChallenge(challenge);
-    if (!challengeRecord) {
-      logger.debug(() => ({
-        msg: `No record of this challenge: ${challenge}`
-      }));
-      return notVerified("CAPTCHA.DAPP_USER_SOLUTION_NOT_FOUND");
-    }
-    if (challengeRecord.result.status !== CaptchaStatus.approved) {
-      throw new ProsopoApiError("CAPTCHA.INVALID_SOLUTION", {
-        context: {
-          failedFuncName: this.serverVerifyPowCaptchaSolution.name,
-          challenge
-        }
-      });
-    }
-    if (challengeRecord.serverChecked)
-      return notVerified("API.USER_ALREADY_VERIFIED");
-    const challengeDappAccount = challengeRecord.dappAccount;
-    if (dappAccount !== challengeDappAccount) {
-      throw new ProsopoEnvError("CAPTCHA.DAPP_USER_SOLUTION_NOT_FOUND", {
-        context: {
-          failedFuncName: this.serverVerifyPowCaptchaSolution.name,
-          dappAccount,
-          challengeDappAccount
-        }
-      });
-    }
-    await this.db.markDappUserPoWCommitmentsChecked([
-      challengeRecord.challenge
-    ]);
-    const powRecordUpdates = {};
-    let failResult;
-    let failReason;
-    const submittedAt = challengeRecord.submittedAtTimestamp;
-    const submitToVerifyMs = submittedAt instanceof Date ? Date.now() - submittedAt.getTime() : Number.POSITIVE_INFINITY;
-    if (submitToVerifyMs > timeout) {
-      failResult = {
-        status: CaptchaStatus.disapproved,
-        reason: ResultReason.TIMESTAMP_TOO_OLD
-      };
-      failReason = "API.TIMESTAMP_TOO_OLD";
-    }
-    if (!failResult && 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 PoW verification",
-            data: {
-              userAccount: challengeRecord.userAccount,
-              policy: blockPolicy
-            }
-          }));
-          failResult = {
-            status: CaptchaStatus.disapproved,
-            reason: ResultReason.ACCESS_POLICY_BLOCK
-          };
-          failReason = "API.ACCESS_POLICY_BLOCK";
-        }
-      } catch (error) {
-        logger.warn(() => ({
-          msg: "Failed to check user access policies in server PoW verification",
-          error
-        }));
-      }
-    }
-    if (!failResult && 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 PoW verification",
-            data: { emailDomain }
-          }));
-          failResult = {
-            status: CaptchaStatus.disapproved,
-            reason: ResultReason.SPAM_EMAIL_DOMAIN
-          };
-          failReason = "API.SPAM_EMAIL_DOMAIN";
-        }
-      } catch (error) {
-        logger.warn(() => ({
-          msg: "Failed to check spam email domain in server PoW verification",
-          error
-        }));
-      }
-    }
-    if (!failResult && spamFilter?.enabled && spamFilter.emailRules?.enabled && email) {
-      const result = evaluateEmailSpamRules(email, spamFilter.emailRules);
-      if (result.isSpam) {
-        logger.info(() => ({
-          msg: "Spam filter rejected email in PoW verification",
-          data: { reason: result.reason }
-        }));
-        failResult = {
-          status: CaptchaStatus.disapproved,
-          reason: ResultReason.SPAM_EMAIL_RULE
-        };
-        failReason = "API.SPAM_EMAIL_RULE";
-      }
-    }
-    const sessionRecord = challengeRecord.sessionId ? await this.db.getSessionRecordBySessionId(challengeRecord.sessionId) : void 0;
-    const enrichedDnsEvent = await enrichDnsEvent(
-      sessionRecord?.dnsEvent,
-      env.ipInfoService,
-      ip ?? challengeRecord.ipInfo?.ip
-    );
-    if (!failResult) {
-      const check = await this.resolveTrafficFilterCheck(
-        env,
-        challengeRecord.ipInfo,
-        trafficFilter,
-        ip,
-        enrichedDnsEvent
-      );
-      if (check.isBlocked) {
-        logger.info(() => ({
-          msg: "Traffic filter rejected request in PoW verification",
-          data: {
-            ip,
-            reason: check.reason,
-            dnsPeerIp: enrichedDnsEvent?.peerIp,
-            dnsResolverIp: enrichedDnsEvent?.resolverIp,
-            dnsPeerAsn: getIpInfoAsn(enrichedDnsEvent?.peerIpInfo),
-            dnsResolverAsn: getIpInfoAsn(enrichedDnsEvent?.resolverIpInfo),
-            dnsPathValid: enrichedDnsEvent?.pathValid
-          }
-        }));
-        failResult = {
-          status: CaptchaStatus.disapproved,
-          reason: check.reason
-        };
-        failReason = check.reason;
-      }
-    }
-    if (storeMetadata && email) {
-      powRecordUpdates.metadata = { email };
-    }
-    if (!failResult && ip) {
-      const challengeIpAddress = getIpAddressFromComposite(
-        challengeRecord.ipAddress
-      );
-      const clientRecord = await this.db.getClientRecord(dappAccount);
-      const ipValidationRules = clientRecord?.settings?.ipValidationRules;
-      powRecordUpdates.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 PoW captcha",
-            data: {
-              ip,
-              challengeIp: challengeIpAddress.address,
-              error: ipValidation.errorMessage,
-              distanceKm: ipValidation.distanceKm
-            }
-          }));
-          failResult = {
-            status: CaptchaStatus.disapproved,
-            reason: ResultReason.FAILED_IP_VALIDATION
-          };
-          failReason = "API.FAILED_IP_VALIDATION";
-        }
-      }
-    }
-    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)
-        }
-      }));
-    }
-    if (!failResult) {
-      try {
-        const decisionInput = {
-          userAccount: challengeRecord.userAccount,
-          dappAccount: challengeRecord.dappAccount,
-          captchaResult: "passed",
-          headers: challengeRecord.headers,
-          captchaType: CaptchaType.pow,
-          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
-        };
-        const decision = await this.decisionMachineRunner.decide(
-          decisionInput,
-          logger
-        );
-        if (decision.decision === DecisionMachineDecision.Deny) {
-          logger.info(() => ({
-            msg: "Decision machine denied PoW captcha in server verification",
-            data: {
-              userAccount: challengeRecord.userAccount,
-              reason: decision.reason,
-              score: decision.score,
-              tags: decision.tags
-            }
-          }));
-          const dmReason = decision.reason || ResultReason.CAPTCHA_DECISION_MACHINE_DENIED;
-          failResult = {
-            status: CaptchaStatus.disapproved,
-            reason: dmReason
-          };
-          failReason = dmReason;
-        } else {
-          logger.debug(() => ({
-            msg: "Decision machine allowed PoW captcha",
-            data: {
-              reason: decision.reason,
-              score: decision.score,
-              tags: decision.tags
-            }
-          }));
-        }
-      } catch (error) {
-        logger.error(() => ({
-          msg: "Failed to run decision machine in server PoW verification",
-          err: error
-        }));
-      }
-    }
-    const finalResult = failResult || {
-      status: CaptchaStatus.approved
-    };
-    if (failResult) {
-      powRecordUpdates.result = failResult;
-    }
-    const writePromises = [];
-    if (Object.keys(powRecordUpdates).length > 0) {
-      writePromises.push(
-        this.db.updatePowCaptchaRecord(
-          challengeRecord.challenge,
-          powRecordUpdates
-        )
-      );
-    }
-    if (challengeRecord.sessionId) {
-      writePromises.push(
-        this.updateSessionRecordWithCache(
-          challengeRecord.sessionId,
-          {
-            serverChecked: true,
-            result: finalResult
-          },
-          true
-        )
-      );
-    }
-    if (writePromises.length > 0) {
-      await Promise.all(writePromises);
-    }
-    if (failReason) {
-      return notVerified(failReason);
-    }
-    return { verified: true, ...score ? { score } : {} };
-  }
-}
-export {
-  PowCaptchaManager
+import { ProsopoApiError, ProsopoEnvError } from "@prosopo/common";
+import { ApiParams, CaptchaStatus, CaptchaType, DecisionMachineDecision, FrictionlessReason, POW_SEPARATOR, ResultReason, SimdReadingsStage } from "@prosopo/types";
+import { assertCoordsSafe, at, extractData, verifyRecency } from "@prosopo/util";
+import { stringToHex, u8aToHex } from "@polkadot/util";
+//#region src/tasks/powCaptcha/powTasks.ts
+var DEFAULT_POW_DIFFICULTY = 4;
+var PowCaptchaManager = class extends CaptchaManager {
+	constructor(db, pair, config, logger, writeQueue, usageCounters) {
+		super(db, pair, config, logger, writeQueue);
+		this.POW_SEPARATOR = POW_SEPARATOR;
+		this.decisionMachineRunner = new DecisionMachineRunner(db);
+		this.usageCounters = usageCounters ?? null;
+	}
+	/**
+	* Provide the request-side data needed to run the post-pow routing pass
+	* inside `verifyPowCaptchaSolution`. When unset, the routing pass is
+	* skipped and verification behaves exactly as before.
+	*/
+	setPostPowContext(ctx) {
+		this.postPowContext = ctx;
+	}
+	/**
+	* @description Generates a PoW Captcha 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 powDifficulty
+	*/
+	async getPowCaptchaChallenge(userAccount, dappAccount, origin, powDifficulty) {
+		const difficulty = powDifficulty || DEFAULT_POW_DIFFICULTY;
+		const requestedAtTimestamp = Date.now();
+		const challenge = `${requestedAtTimestamp}___${userAccount}___${dappAccount}___${Math.floor(Math.random() * 1e6)}`;
+		return {
+			challenge,
+			difficulty,
+			providerSignature: u8aToHex(this.pair.sign(stringToHex(challenge))),
+			requestedAtTimestamp
+		};
+	}
+	/**
+	* @description Verifies a PoW Captcha for a given user and dapp
+	*
+	* @param {string} challenge - the starting string for the PoW challenge
+	* @param {string} providerChallengeSignature - proof that the Provider provided the challenge
+	* @param {string} nonce - the string that the user has found that satisfies the PoW challenge
+	* @param {number} timeout - the time in milliseconds since the Provider was selected to provide the PoW captcha
+	* @param {string} userTimestampSignature
+	* @param ipAddress
+	* @param headers
+	* @param behavioralData
+	* @param salt
+	*/
+	async verifyPowCaptchaSolution(challenge, providerChallengeSignature, nonce, 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.getPowCaptchaRecordByChallenge(challenge);
+		if (!challengeRecord) {
+			this.logger.debug(() => ({ msg: `No record of this challenge: ${challenge}` }));
+			return { verified: false };
+		}
+		const difficulty = challengeRecord.difficulty;
+		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 (saltDecodeError) {
+			const badSaltResult = {
+				status: CaptchaStatus.disapproved,
+				reason: ResultReason.CAPTCHA_INVALID_SALT
+			};
+			const writePromises = [this.db.updatePowCaptchaRecordResult(challenge, badSaltResult, false, true, userTimestampSignature, void 0)];
+			if (challengeRecord.sessionId) writePromises.push(this.updateSessionRecordWithCache(challengeRecord.sessionId, {
+				userSubmitted: true,
+				result: badSaltResult
+			}));
+			await Promise.all(writePromises);
+			return { verified: false };
+		}
+		if (!verifyRecency(challenge, timeout)) {
+			const timeoutResult = {
+				status: CaptchaStatus.disapproved,
+				reason: ResultReason.CAPTCHA_INVALID_TIMESTAMP
+			};
+			const writePromises = [this.db.updatePowCaptchaRecordResult(challenge, timeoutResult, false, true, userTimestampSignature, coords)];
+			if (challengeRecord.sessionId) writePromises.push(this.updateSessionRecordWithCache(challengeRecord.sessionId, {
+				userSubmitted: true,
+				result: timeoutResult
+			}));
+			await Promise.all(writePromises);
+			return { verified: false };
+		}
+		const correct = validateSolution(nonce, challenge, difficulty);
+		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.pow, ipAddress.address, userAccount));
+		}
+		let behavioralUpdates = {};
+		let decryptedBehavioralDataPacked;
+		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
+				};
+				behavioralUpdates = {
+					behavioralDataPacked: packedData,
+					deviceCapability: decryptedData.deviceCapability
+				};
+				decryptedBehavioralDataPacked = packedData;
+			}
+		} catch (error) {
+			this.logger?.error(() => ({
+				msg: "Failed to process behavioral data",
+				err: error
+			}));
+		}
+		const recordUpdates = { ...behavioralUpdates };
+		if (clientMetaData?.hp) recordUpdates.clientMetaData = { hp: clientMetaData.hp };
+		if (Object.keys(recordUpdates).length > 0) await this.db.updatePowCaptchaRecord(challenge, recordUpdates);
+		const writePromises = [this.db.updatePowCaptchaRecordResult(challenge, result, false, true, userTimestampSignature, coords)];
+		if (challengeRecord.sessionId) {
+			const linkedSessionId = challengeRecord.sessionId;
+			writePromises.push(this.updateSessionRecordWithCache(linkedSessionId, {
+				userSubmitted: true,
+				result
+			}));
+			if (simdReadings) writePromises.push(this.decryptAndAttachSimdReadingsIfAbsent(linkedSessionId, simdReadings, SimdReadingsStage.submit));
+		}
+		await Promise.all(writePromises);
+		if (!correct) return { verified: correct };
+		const escalateForMissingCoords = !coords && Boolean(challengeRecord.sessionId);
+		let routingOutput = this.postPowContext ? await this.runPostPowRouting({
+			challengeRecord,
+			challengeSplit,
+			behavioralDataPacked: decryptedBehavioralDataPacked
+		}) : void 0;
+		if (escalateForMissingCoords && routingOutput?.captchaType !== CaptchaType.image && routingOutput?.captchaType !== CaptchaType.puzzle) routingOutput = {
+			captchaType: CaptchaType.image,
+			reason: FrictionlessReason.MISSING_COORDINATES
+		};
+		return {
+			verified: correct,
+			routingOutput
+		};
+	}
+	/**
+	* Resolve the originating session, build a full RoutingContext, and run the
+	* post-pow phase of the routing machine. Returns the machine's output, or
+	* undefined when prerequisites are missing (no session, no score) — in
+	* which case the caller treats the result as "no escalation".
+	*/
+	async runPostPowRouting(args) {
+		if (!this.postPowContext) return void 0;
+		const { challengeRecord, challengeSplit, behavioralDataPacked } = args;
+		if (!challengeRecord.sessionId) {
+			this.logger.debug(() => ({ msg: "Skipping post-pow routing: PoW record has no linked session" }));
+			return;
+		}
+		const sessionRecord = await this.db.getSessionRecordBySessionId(challengeRecord.sessionId);
+		if (!sessionRecord) {
+			this.logger.debug(() => ({
+				msg: "Skipping post-pow routing: session record not found",
+				data: { sessionId: challengeRecord.sessionId }
+			}));
+			return;
+		}
+		const score = computeFrictionlessScore(sessionRecord.scoreComponents);
+		const dappAccount = at(challengeSplit, 2);
+		const userAccount = at(challengeSplit, 1);
+		const platform = {
+			...this.postPowContext.platform,
+			isWebView: sessionRecord.webView
+		};
+		const ctx = {
+			dappAccount,
+			userAccount,
+			ip: this.postPowContext.ip,
+			countryCode: this.postPowContext.countryCode,
+			score,
+			platform,
+			raw: {
+				...this.postPowContext.raw,
+				...behavioralDataPacked && { behavioralDataPacked },
+				...sessionRecord.simdReadings && { simd: sessionRecord.simdReadings },
+				...sessionRecord.currentUrl && { currentUrl: sessionRecord.currentUrl },
+				...sessionRecord.iframeUrl && { iframeUrl: sessionRecord.iframeUrl }
+			}
+		};
+		const baseline = {
+			captchaType: CaptchaType.pow,
+			powDifficulty: challengeRecord.difficulty
+		};
+		return applyRouter(this.decisionMachineRunner, this.usageCounters, baseline, ctx, this.logger, "postPow");
+	}
+	/**
+	* @description Verifies a PoW 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 starting string for the PoW challenge
+	* @param {number} timeout - the time in milliseconds since the Provider was selected to provide the PoW 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 spamFilter
+	* @param trafficFilter
+	* @param storeMetadata - when true, persists the dapp-server-provided
+	*   `email` (and any future metadata fields) on the captcha record so
+	*   it can be inspected for spam-rate analysis.
+	*/
+	async serverVerifyPowCaptchaSolution(dappAccount, challenge, timeout, env, ip, userAccessRulesStorage, email, spamEmailDomainCheckingEnabled = false, spamFilter, trafficFilter, storeMetadata = false) {
+		const notVerified = (reason) => ({
+			verified: false,
+			reason
+		});
+		const logger = this.logger.with({
+			challenge,
+			dappAccount
+		});
+		const challengeRecord = await this.db.getPowCaptchaRecordByChallenge(challenge);
+		if (!challengeRecord) {
+			logger.debug(() => ({ msg: `No record of this challenge: ${challenge}` }));
+			return notVerified("CAPTCHA.DAPP_USER_SOLUTION_NOT_FOUND");
+		}
+		if (challengeRecord.result.status !== CaptchaStatus.approved) throw new ProsopoApiError("CAPTCHA.INVALID_SOLUTION", { context: {
+			code: 400,
+			failedFuncName: this.serverVerifyPowCaptchaSolution.name,
+			challenge
+		} });
+		if (challengeRecord.serverChecked) return notVerified("API.USER_ALREADY_VERIFIED");
+		const challengeDappAccount = challengeRecord.dappAccount;
+		if (dappAccount !== challengeDappAccount) throw new ProsopoEnvError("CAPTCHA.DAPP_USER_SOLUTION_NOT_FOUND", { context: {
+			failedFuncName: this.serverVerifyPowCaptchaSolution.name,
+			dappAccount,
+			challengeDappAccount
+		} });
+		await this.db.markDappUserPoWCommitmentsChecked([challengeRecord.challenge]);
+		const powRecordUpdates = {};
+		let failResult;
+		let failReason;
+		const submittedAt = challengeRecord.submittedAtTimestamp;
+		if ((submittedAt instanceof Date ? Date.now() - submittedAt.getTime() : Number.POSITIVE_INFINITY) > timeout) {
+			failResult = {
+				status: CaptchaStatus.disapproved,
+				reason: ResultReason.TIMESTAMP_TOO_OLD
+			};
+			failReason = "API.TIMESTAMP_TOO_OLD";
+		}
+		if (!failResult && 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 PoW verification",
+					data: {
+						userAccount: challengeRecord.userAccount,
+						policy: blockPolicy
+					}
+				}));
+				failResult = {
+					status: CaptchaStatus.disapproved,
+					reason: ResultReason.ACCESS_POLICY_BLOCK
+				};
+				failReason = "API.ACCESS_POLICY_BLOCK";
+			}
+		} catch (error) {
+			logger.warn(() => ({
+				msg: "Failed to check user access policies in server PoW verification",
+				error
+			}));
+		}
+		if (!failResult && email && spamEmailDomainCheckingEnabled) try {
+			if (await this.checkSpamEmail(email)) {
+				const emailDomain = email.split("@")[1] || "unknown";
+				logger.info(() => ({
+					msg: "Spam email domain detected in server PoW verification",
+					data: { emailDomain }
+				}));
+				failResult = {
+					status: CaptchaStatus.disapproved,
+					reason: ResultReason.SPAM_EMAIL_DOMAIN
+				};
+				failReason = "API.SPAM_EMAIL_DOMAIN";
+			}
+		} catch (error) {
+			logger.warn(() => ({
+				msg: "Failed to check spam email domain in server PoW verification",
+				error
+			}));
+		}
+		if (!failResult && spamFilter?.enabled && spamFilter.emailRules?.enabled && email) {
+			const result = evaluateEmailSpamRules(email, spamFilter.emailRules);
+			if (result.isSpam) {
+				logger.info(() => ({
+					msg: "Spam filter rejected email in PoW verification",
+					data: { reason: result.reason }
+				}));
+				failResult = {
+					status: CaptchaStatus.disapproved,
+					reason: ResultReason.SPAM_EMAIL_RULE
+				};
+				failReason = "API.SPAM_EMAIL_RULE";
+			}
+		}
+		const sessionRecord = challengeRecord.sessionId ? await this.db.getSessionRecordBySessionId(challengeRecord.sessionId) : void 0;
+		const enrichedDnsEvent = await enrichDnsEvent(sessionRecord?.dnsEvent, env.ipInfoService, ip ?? challengeRecord.ipInfo?.ip);
+		if (!failResult) {
+			const check = await this.resolveTrafficFilterCheck(env, challengeRecord.ipInfo, trafficFilter, ip, enrichedDnsEvent);
+			if (check.isBlocked) {
+				logger.info(() => ({
+					msg: "Traffic filter rejected request in PoW verification",
+					data: {
+						ip,
+						reason: check.reason,
+						dnsPeerIp: enrichedDnsEvent?.peerIp,
+						dnsResolverIp: enrichedDnsEvent?.resolverIp,
+						dnsPeerAsn: getIpInfoAsn(enrichedDnsEvent?.peerIpInfo),
+						dnsResolverAsn: getIpInfoAsn(enrichedDnsEvent?.resolverIpInfo),
+						dnsPathValid: enrichedDnsEvent?.pathValid
+					}
+				}));
+				failResult = {
+					status: CaptchaStatus.disapproved,
+					reason: check.reason
+				};
+				failReason = check.reason;
+			}
+		}
+		if (storeMetadata && email) powRecordUpdates.metadata = { email };
+		if (!failResult && ip) {
+			const challengeIpAddress = getIpAddressFromComposite(challengeRecord.ipAddress);
+			const ipValidationRules = (await this.db.getClientRecord(dappAccount))?.settings?.ipValidationRules;
+			powRecordUpdates.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 PoW captcha",
+						data: {
+							ip,
+							challengeIp: challengeIpAddress.address,
+							error: ipValidation.errorMessage,
+							distanceKm: ipValidation.distanceKm
+						}
+					}));
+					failResult = {
+						status: CaptchaStatus.disapproved,
+						reason: ResultReason.FAILED_IP_VALIDATION
+					};
+					failReason = "API.FAILED_IP_VALIDATION";
+				}
+			}
+		}
+		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)
+			} }));
+		}
+		if (!failResult) try {
+			const decisionInput = {
+				userAccount: challengeRecord.userAccount,
+				dappAccount: challengeRecord.dappAccount,
+				captchaResult: "passed",
+				headers: challengeRecord.headers,
+				captchaType: CaptchaType.pow,
+				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
+			};
+			const decision = await this.decisionMachineRunner.decide(decisionInput, logger);
+			if (decision.decision === DecisionMachineDecision.Deny) {
+				logger.info(() => ({
+					msg: "Decision machine denied PoW captcha in server verification",
+					data: {
+						userAccount: challengeRecord.userAccount,
+						reason: decision.reason,
+						score: decision.score,
+						tags: decision.tags
+					}
+				}));
+				const dmReason = decision.reason || ResultReason.CAPTCHA_DECISION_MACHINE_DENIED;
+				failResult = {
+					status: CaptchaStatus.disapproved,
+					reason: dmReason
+				};
+				failReason = dmReason;
+			} else logger.debug(() => ({
+				msg: "Decision machine allowed PoW captcha",
+				data: {
+					reason: decision.reason,
+					score: decision.score,
+					tags: decision.tags
+				}
+			}));
+		} catch (error) {
+			logger.error(() => ({
+				msg: "Failed to run decision machine in server PoW verification",
+				err: error
+			}));
+		}
+		const finalResult = failResult || { status: CaptchaStatus.approved };
+		if (failResult) powRecordUpdates.result = failResult;
+		const writePromises = [];
+		if (Object.keys(powRecordUpdates).length > 0) writePromises.push(this.db.updatePowCaptchaRecord(challengeRecord.challenge, powRecordUpdates));
+		if (challengeRecord.sessionId) writePromises.push(this.updateSessionRecordWithCache(challengeRecord.sessionId, {
+			serverChecked: true,
+			result: finalResult
+		}, true));
+		if (writePromises.length > 0) await Promise.all(writePromises);
+		if (failReason) return notVerified(failReason);
+		return {
+			verified: true,
+			...score ? { score } : {}
+		};
+	}
 };
+//#endregion
+export { PowCaptchaManager };