@prosopo/provider 3.13.7 → 4.7.1

package/dist/cjs/tasks/powCaptcha/powTasks.cjs

@@ -6,14 +6,28 @@ const types = require("@prosopo/types");
 const util$1 = require("@prosopo/util");
 const compositeIpAddress = require("../../compositeIpAddress.cjs");
 const util$2 = require("../../util.cjs");
+const usageCounters = require("../../util/usageCounters.cjs");
 const captchaManager = require("../captchaManager.cjs");
+const decisionMachineRunner = require("../decisionMachine/decisionMachineRunner.cjs");
 const frictionlessTasksUtils = require("../frictionless/frictionlessTasksUtils.cjs");
+const routingMachine = require("../frictionless/routingMachine.cjs");
+const evaluateEmailSpamRules = require("../spam/evaluateEmailSpamRules.cjs");
 const powTasksUtils = require("./powTasksUtils.cjs");
 const DEFAULT_POW_DIFFICULTY = 4;
 class PowCaptchaManager extends captchaManager.CaptchaManager {
-  constructor(db, pair, config, logger) {
-    super(db, pair, config, logger);
+  constructor(db, pair, config, logger, writeQueue, usageCounters2) {
+    super(db, pair, config, logger, writeQueue);
     this.POW_SEPARATOR = types.POW_SEPARATOR;
+    this.decisionMachineRunner = new decisionMachineRunner.DecisionMachineRunner(db);
+    this.usageCounters = usageCounters2 ?? 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
@@ -40,15 +54,16 @@ class PowCaptchaManager extends captchaManager.CaptchaManager {
    * @description Verifies a PoW Captcha for a given user and dapp
    *
    * @param {string} challenge - the starting string for the PoW challenge
-   * @param {string} difficulty - how many leading zeroes the solution must have
    * @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) {
+  async verifyPowCaptchaSolution(challenge, providerChallengeSignature, nonce, timeout, userTimestampSignature, ipAddress, headers, behavioralData, salt, simdReadings, clientMetaData) {
     powTasksUtils.checkPowSignature(
       challenge,
       providerChallengeSignature,
@@ -69,40 +84,221 @@ class PowCaptchaManager extends captchaManager.CaptchaManager {
       this.logger.debug(() => ({
         msg: `No record of this challenge: ${challenge}`
       }));
-      return false;
+      return { verified: false };
     }
     const difficulty = challengeRecord.difficulty;
+    let coords;
+    if (salt) {
+      try {
+        const extractedData = util$1.extractData(salt);
+        if (extractedData.length >= 2) {
+          coords = [[[extractedData[0], extractedData[1]]]];
+        }
+      } catch (error) {
+        this.logger.warn(() => ({
+          msg: "Failed to extract coordinates from salt",
+          error,
+          salt
+        }));
+      }
+    }
     if (!util$1.verifyRecency(challenge, timeout)) {
-      await this.db.updatePowCaptchaRecordResult(
-        challenge,
-        {
-          status: types.CaptchaStatus.disapproved,
-          reason: "CAPTCHA.INVALID_TIMESTAMP"
-        },
-        false,
-        //serverchecked
-        true,
-        // usersubmitted
-        userTimestampSignature
-      );
-      return false;
+      const timeoutResult = {
+        status: types.CaptchaStatus.disapproved,
+        reason: types.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 = powTasksUtils.validateSolution(nonce, challenge, difficulty);
     let result = { status: types.CaptchaStatus.approved };
     if (!correct) {
       result = {
         status: types.CaptchaStatus.disapproved,
-        reason: "CAPTCHA.INVALID_SOLUTION"
+        reason: types.ResultReason.CAPTCHA_INVALID_SOLUTION
       };
     }
-    await this.db.updatePowCaptchaRecordResult(
-      challenge,
-      result,
-      false,
-      true,
-      userTimestampSignature
+    if (correct && this.usageCounters) {
+      const dappAccount = util$1.at(challengeSplit, 2);
+      this.usageCounters.incrManyAsync(
+        dappAccount,
+        usageCounters.buildAllWindowIncrements(
+          "solved",
+          types.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 = util$1.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,
+            types.SimdReadingsStage.submit
+          )
+        );
+      }
+    }
+    await Promise.all(writePromises);
+    if (!correct || !this.postPowContext) {
+      return { verified: correct };
+    }
+    const routingOutput = await this.runPostPowRouting({
+      challengeRecord,
+      challengeSplit,
+      behavioralDataPacked: decryptedBehavioralDataPacked
+    });
+    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 = frictionlessTasksUtils.computeFrictionlessScore(sessionRecord.scoreComponents);
+    const dappAccount = util$1.at(challengeSplit, 2);
+    const userAccount = util$1.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 }
+      }
+    };
+    const baseline = {
+      captchaType: types.CaptchaType.pow,
+      powDifficulty: challengeRecord.difficulty
+    };
+    return routingMachine.applyRouter(
+      this.decisionMachineRunner,
+      this.usageCounters,
+      baseline,
+      ctx,
+      this.logger,
+      "postPow"
     );
-    return correct;
   }
   /**
    * @description Verifies a PoW Captcha for a given user and dapp. This is called by the server to verify the user's solution
@@ -111,16 +307,28 @@ class PowCaptchaManager extends captchaManager.CaptchaManager {
    * @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 ip
+   * @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) {
-    const notVerifiedResponse = { verified: false };
+  async serverVerifyPowCaptchaSolution(dappAccount, challenge, timeout, env, ip, userAccessRulesStorage, email, spamEmailDomainCheckingEnabled = false, spamFilter, trafficFilter, storeMetadata = false) {
+    const notVerified = (reason) => ({
+      verified: false,
+      reason
+    });
     const challengeRecord = await this.db.getPowCaptchaRecordByChallenge(challenge);
     if (!challengeRecord) {
       this.logger.debug(() => ({
         msg: `No record of this challenge: ${challenge}`
       }));
-      return notVerifiedResponse;
+      return notVerified("CAPTCHA.DAPP_USER_SOLUTION_NOT_FOUND");
     }
     if (challengeRecord.result.status !== types.CaptchaStatus.approved) {
       throw new common.ProsopoApiError("CAPTCHA.INVALID_SOLUTION", {
@@ -130,7 +338,8 @@ class PowCaptchaManager extends captchaManager.CaptchaManager {
         }
       });
     }
-    if (challengeRecord.serverChecked) return notVerifiedResponse;
+    if (challengeRecord.serverChecked)
+      return notVerified("API.USER_ALREADY_VERIFIED");
     const challengeDappAccount = challengeRecord.dappAccount;
     if (dappAccount !== challengeDappAccount) {
       throw new common.ProsopoEnvError("CAPTCHA.DAPP_USER_SOLUTION_NOT_FOUND", {
@@ -144,38 +353,139 @@ class PowCaptchaManager extends captchaManager.CaptchaManager {
     await this.db.markDappUserPoWCommitmentsChecked([
       challengeRecord.challenge
     ]);
+    const powRecordUpdates = {};
+    let failResult;
+    let failReason;
     const recent = util$1.verifyRecency(challenge, timeout);
     if (!recent) {
-      return notVerifiedResponse;
+      failResult = {
+        status: types.CaptchaStatus.disapproved,
+        reason: types.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
+        );
+        if (blockPolicy) {
+          this.logger.info(() => ({
+            msg: "User blocked by access policy in server PoW verification",
+            data: {
+              challenge,
+              userAccount: challengeRecord.userAccount,
+              dappAccount,
+              policy: blockPolicy
+            }
+          }));
+          failResult = {
+            status: types.CaptchaStatus.disapproved,
+            reason: types.ResultReason.ACCESS_POLICY_BLOCK
+          };
+          failReason = "API.ACCESS_POLICY_BLOCK";
+        }
+      } catch (error) {
+        this.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";
+          this.logger.info(() => ({
+            msg: "Spam email domain detected in server PoW verification",
+            data: { challenge, dappAccount, emailDomain }
+          }));
+          failResult = {
+            status: types.CaptchaStatus.disapproved,
+            reason: types.ResultReason.SPAM_EMAIL_DOMAIN
+          };
+          failReason = "API.SPAM_EMAIL_DOMAIN";
+        }
+      } catch (error) {
+        this.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.evaluateEmailSpamRules(email, spamFilter.emailRules);
+      if (result.isSpam) {
+        this.logger.info(() => ({
+          msg: "Spam filter rejected email in PoW verification",
+          data: { challenge, dappAccount, reason: result.reason }
+        }));
+        failResult = {
+          status: types.CaptchaStatus.disapproved,
+          reason: types.ResultReason.SPAM_EMAIL_RULE
+        };
+        failReason = "API.SPAM_EMAIL_RULE";
+      }
+    }
+    if (!failResult) {
+      const check = await this.resolveTrafficFilterCheck(
+        env,
+        challengeRecord.ipInfo,
+        trafficFilter,
+        ip
+      );
+      if (check.isBlocked) {
+        this.logger.info(() => ({
+          msg: "Traffic filter rejected request in PoW verification",
+          data: { challenge, dappAccount, ip, reason: check.reason }
+        }));
+        failResult = {
+          status: types.CaptchaStatus.disapproved,
+          reason: check.reason
+        };
+        failReason = check.reason;
+      }
+    }
+    if (storeMetadata && email) {
+      powRecordUpdates.metadata = { email };
     }
-    if (ip) {
+    if (!failResult && ip) {
       const challengeIpAddress = compositeIpAddress.getIpAddressFromComposite(
         challengeRecord.ipAddress
       );
       const clientRecord = await this.db.getClientRecord(dappAccount);
       const ipValidationRules = clientRecord?.settings?.ipValidationRules;
-      await this.db.updatePowCaptchaRecord(challengeRecord.challenge, {
-        providedIp: compositeIpAddress.getCompositeIpAddress(ip)
-      });
-      const ipValidation = await util$2.deepValidateIpAddress(
-        ip,
-        challengeIpAddress,
-        this.logger,
-        env.config.ipApi.apiKey,
-        env.config.ipApi.baseUrl,
-        ipValidationRules
-      );
-      if (!ipValidation.isValid) {
-        this.logger.error(() => ({
-          msg: "IP validation failed for PoW captcha",
-          data: {
-            ip,
-            challengeIp: challengeIpAddress.address,
-            error: ipValidation.errorMessage,
-            distanceKm: ipValidation.distanceKm
-          }
-        }));
-        return notVerifiedResponse;
+      powRecordUpdates.providedIp = compositeIpAddress.getCompositeIpAddress(ip);
+      if (ipValidationRules?.enabled === true) {
+        const ipValidation = await util$2.deepValidateIpAddress(
+          ip,
+          challengeIpAddress,
+          this.logger,
+          env.ipInfoService,
+          ipValidationRules
+        );
+        if (!ipValidation.isValid) {
+          this.logger.error(() => ({
+            msg: "IP validation failed for PoW captcha",
+            data: {
+              ip,
+              challengeIp: challengeIpAddress.address,
+              error: ipValidation.errorMessage,
+              distanceKm: ipValidation.distanceKm
+            }
+          }));
+          failResult = {
+            status: types.CaptchaStatus.disapproved,
+            reason: types.ResultReason.FAILED_IP_VALIDATION
+          };
+          failReason = "API.FAILED_IP_VALIDATION";
+        }
       }
     }
     let score;
@@ -193,6 +503,91 @@ class PowCaptchaManager extends captchaManager.CaptchaManager {
         }));
       }
     }
+    if (!failResult) {
+      try {
+        const decisionInput = {
+          userAccount: challengeRecord.userAccount,
+          dappAccount: challengeRecord.dappAccount,
+          captchaResult: "passed",
+          headers: challengeRecord.headers,
+          captchaType: types.CaptchaType.pow,
+          behavioralDataPacked: challengeRecord.behavioralDataPacked,
+          deviceCapability: challengeRecord.deviceCapability,
+          countryCode: challengeRecord.ipInfo?.isValid ? challengeRecord.ipInfo.countryCode : void 0
+        };
+        const decision = await this.decisionMachineRunner.decide(
+          decisionInput,
+          this.logger
+        );
+        if (decision.decision === types.DecisionMachineDecision.Deny) {
+          this.logger.info(() => ({
+            msg: "Decision machine denied PoW captcha in server verification",
+            data: {
+              challenge,
+              userAccount: challengeRecord.userAccount,
+              dappAccount,
+              reason: decision.reason,
+              score: decision.score,
+              tags: decision.tags
+            }
+          }));
+          const dmReason = decision.reason || types.ResultReason.CAPTCHA_DECISION_MACHINE_DENIED;
+          failResult = {
+            status: types.CaptchaStatus.disapproved,
+            reason: dmReason
+          };
+          failReason = dmReason;
+        } else {
+          this.logger.debug(() => ({
+            msg: "Decision machine allowed PoW captcha",
+            data: {
+              challenge,
+              reason: decision.reason,
+              score: decision.score,
+              tags: decision.tags
+            }
+          }));
+        }
+      } catch (error) {
+        this.logger?.error(() => ({
+          msg: "Failed to run decision machine in server PoW verification",
+          err: error
+        }));
+      }
+    }
+    const finalResult = failResult || {
+      status: types.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 } : {} };
   }
 }