@prosopo/provider 3.15.0 → 4.7.1

package/dist/tasks/powCaptcha/powTasks.js

@@ -1,57 +1,31 @@
 import { u8aToHex, stringToHex } from "@polkadot/util";
 import { ProsopoApiError, ProsopoEnvError } from "@prosopo/common";
-import { POW_SEPARATOR, ApiParams, CaptchaStatus } from "@prosopo/types";
-import { AccessPolicyType } from "@prosopo/user-access-policy";
+import { POW_SEPARATOR, ApiParams, ResultReason, CaptchaStatus, CaptchaType, SimdReadingsStage, DecisionMachineDecision } from "@prosopo/types";
 import { at, extractData, verifyRecency } from "@prosopo/util";
-import { getRequestUserScope } from "../../api/blacklistRequestInspector.js";
 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 { computeFrictionlessScore } from "../frictionless/frictionlessTasksUtils.js";
+import { applyRouter } from "../frictionless/routingMachine.js";
+import { evaluateEmailSpamRules } from "../spam/evaluateEmailSpamRules.js";
 import { checkPowSignature, validateSolution } from "./powTasksUtils.js";
-const findHardBlockPolicy = (accessPolicies) => {
-  return accessPolicies.find(
-    (policy) => policy.type === AccessPolicyType.Block && !policy.captchaType
-  );
-};
 const DEFAULT_POW_DIFFICULTY = 4;
 class PowCaptchaManager extends CaptchaManager {
-  constructor(db, pair, config, logger) {
-    super(db, pair, config, logger);
+  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;
   }
   /**
-   * Checks if a user should be hard blocked based on access policies
-   * Only checks for Block policies without captchaType
-   *
-   * @returns The blocking policy if user should be blocked, undefined otherwise
+   * 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.
    */
-  async checkForHardBlock(userAccessRulesStorage, challengeRecord, userAccount, headers, coords) {
-    let headHash;
-    if (challengeRecord.sessionId) {
-      const sessionRecord = await this.db.getSessionRecordBySessionId(
-        challengeRecord.sessionId
-      );
-      headHash = sessionRecord?.decryptedHeadHash;
-    }
-    const coordsString = coords ? JSON.stringify(coords) : void 0;
-    const ipAddressRecord = getIpAddressFromComposite(
-      challengeRecord.ipAddress
-    );
-    const userScope = getRequestUserScope(
-      headers,
-      challengeRecord.ja4,
-      ipAddressRecord.address,
-      userAccount,
-      headHash,
-      coordsString
-    );
-    const accessPolicies = await this.getPrioritisedAccessPolicies(
-      userAccessRulesStorage,
-      challengeRecord.dappAccount,
-      userScope
-    );
-    return findHardBlockPolicy(accessPolicies);
+  setPostPowContext(ctx) {
+    this.postPowContext = ctx;
   }
   /**
    * @description Generates a PoW Captcha for a given user and dapp
@@ -78,16 +52,16 @@ class PowCaptchaManager extends 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, behavioralData, salt) {
+  async verifyPowCaptchaSolution(challenge, providerChallengeSignature, nonce, timeout, userTimestampSignature, ipAddress, headers, behavioralData, salt, simdReadings, clientMetaData) {
     checkPowSignature(
       challenge,
       providerChallengeSignature,
@@ -108,7 +82,7 @@ class PowCaptchaManager extends CaptchaManager {
       this.logger.debug(() => ({
         msg: `No record of this challenge: ${challenge}`
       }));
-      return false;
+      return { verified: false };
     }
     const difficulty = challengeRecord.difficulty;
     let coords;
@@ -127,37 +101,55 @@ class PowCaptchaManager extends CaptchaManager {
       }
     }
     if (!verifyRecency(challenge, timeout)) {
-      await this.db.updatePowCaptchaRecordResult(
-        challenge,
-        {
-          status: CaptchaStatus.disapproved,
-          reason: "CAPTCHA.INVALID_TIMESTAMP"
-        },
-        false,
-        //serverchecked
-        true,
-        // usersubmitted
-        userTimestampSignature,
-        coords
-      );
-      return false;
+      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: "CAPTCHA.INVALID_SOLUTION"
+        reason: ResultReason.CAPTCHA_INVALID_SOLUTION
       };
     }
-    await this.db.updatePowCaptchaRecordResult(
-      challenge,
-      result,
-      false,
-      true,
-      userTimestampSignature,
-      coords
-    );
+    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 = [
@@ -190,10 +182,11 @@ class PowCaptchaManager extends CaptchaManager {
             c3: decryptedData.collector3 || [],
             d: decryptedData.deviceCapability
           };
-          await this.db.updatePowCaptchaRecord(challenge, {
+          behavioralUpdates = {
             behavioralDataPacked: packedData,
             deviceCapability: decryptedData.deviceCapability
-          });
+          };
+          decryptedBehavioralDataPacked = packedData;
         }
       } catch (error) {
         this.logger?.error(() => ({
@@ -202,7 +195,108 @@ class PowCaptchaManager extends CaptchaManager {
         }));
       }
     }
-    return correct;
+    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 || !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 = 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 }
+      }
+    };
+    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
@@ -214,15 +308,25 @@ class PowCaptchaManager extends CaptchaManager {
    * @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) {
-    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 !== CaptchaStatus.approved) {
       throw new ProsopoApiError("CAPTCHA.INVALID_SOLUTION", {
@@ -232,7 +336,8 @@ class PowCaptchaManager extends CaptchaManager {
         }
       });
     }
-    if (challengeRecord.serverChecked) return notVerifiedResponse;
+    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", {
@@ -246,24 +351,26 @@ class PowCaptchaManager extends CaptchaManager {
     await this.db.markDappUserPoWCommitmentsChecked([
       challengeRecord.challenge
     ]);
+    const powRecordUpdates = {};
+    let failResult;
+    let failReason;
     const recent = verifyRecency(challenge, timeout);
     if (!recent) {
-      await this.db.updatePowCaptchaRecord(challengeRecord.challenge, {
-        result: {
-          status: CaptchaStatus.disapproved,
-          reason: "API.TIMESTAMP_TOO_OLD"
-        }
-      });
-      return notVerifiedResponse;
+      failResult = {
+        status: CaptchaStatus.disapproved,
+        reason: ResultReason.TIMESTAMP_TOO_OLD
+      };
+      failReason = "API.TIMESTAMP_TOO_OLD";
     }
-    if (userAccessRulesStorage) {
+    if (!failResult && userAccessRulesStorage) {
       try {
         const blockPolicy = await this.checkForHardBlock(
           userAccessRulesStorage,
           challengeRecord,
           challengeRecord.userAccount,
           challengeRecord.headers,
-          challengeRecord.coords
+          challengeRecord.coords,
+          challengeRecord.ipInfo?.isValid ? challengeRecord.ipInfo.countryCode : void 0
         );
         if (blockPolicy) {
           this.logger.info(() => ({
@@ -275,13 +382,11 @@ class PowCaptchaManager extends CaptchaManager {
               policy: blockPolicy
             }
           }));
-          await this.db.updatePowCaptchaRecord(challengeRecord.challenge, {
-            result: {
-              status: CaptchaStatus.disapproved,
-              reason: "API.ACCESS_POLICY_BLOCK"
-            }
-          });
-          return notVerifiedResponse;
+          failResult = {
+            status: CaptchaStatus.disapproved,
+            reason: ResultReason.ACCESS_POLICY_BLOCK
+          };
+          failReason = "API.ACCESS_POLICY_BLOCK";
         }
       } catch (error) {
         this.logger.warn(() => ({
@@ -290,40 +395,95 @@ class PowCaptchaManager extends CaptchaManager {
         }));
       }
     }
-    if (ip) {
+    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: CaptchaStatus.disapproved,
+            reason: 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(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: CaptchaStatus.disapproved,
+          reason: 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: 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;
-      await this.db.updatePowCaptchaRecord(challengeRecord.challenge, {
-        providedIp: getCompositeIpAddress(ip)
-      });
-      const ipValidation = await 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
-          }
-        }));
-        await this.db.updatePowCaptchaRecord(challengeRecord.challenge, {
-          result: {
+      powRecordUpdates.providedIp = getCompositeIpAddress(ip);
+      if (ipValidationRules?.enabled === true) {
+        const ipValidation = await 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: CaptchaStatus.disapproved,
-            reason: "API.FAILED_IP_VALIDATION"
-          }
-        });
-        return notVerifiedResponse;
+            reason: ResultReason.FAILED_IP_VALIDATION
+          };
+          failReason = "API.FAILED_IP_VALIDATION";
+        }
       }
     }
     let score;
@@ -341,62 +501,92 @@ class PowCaptchaManager extends CaptchaManager {
         }));
       }
     }
-    return { verified: true, ...score ? { score } : {} };
-  }
-  /**
-   * Decrypts behavioral data
-   * @param encryptedData - The encrypted behavioral data
-   * @param decryptKeys - Array of possible decryption keys to try
-   * @returns Decrypted behavioral data in unpacked format, or null if decryption fails
-   */
-  async decryptBehavioralData(encryptedData, decryptKeys) {
-    const decryptBehavioralData = (await import("../detection/decodeBehavior.js")).default;
-    const validKeys = decryptKeys.filter((k) => k);
-    if (validKeys.length === 0) {
-      this.logger?.error(() => ({
-        msg: "No decryption keys provided for behavioral data"
-      }));
-      return null;
-    }
-    for (const [keyIndex, key] of validKeys.entries()) {
+    if (!failResult) {
       try {
-        this.logger?.debug(() => ({
-          msg: "Attempting to decrypt behavioral data",
-          data: {
-            keyIndex: keyIndex + 1,
-            totalKeys: validKeys.length
-          }
-        }));
-        const result = await decryptBehavioralData(encryptedData, key);
-        this.logger?.info(() => ({
-          msg: "Behavioral data decrypted successfully",
-          data: {
-            keyIndex: keyIndex + 1,
-            c1Length: result.collector1?.length || 0,
-            c2Length: result.collector2?.length || 0,
-            c3Length: result.collector3?.length || 0,
-            deviceCapability: result.deviceCapability
-          }
-        }));
-        return result;
+        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
+        };
+        const decision = await this.decisionMachineRunner.decide(
+          decisionInput,
+          this.logger
+        );
+        if (decision.decision === 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 || ResultReason.CAPTCHA_DECISION_MACHINE_DENIED;
+          failResult = {
+            status: 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?.debug(() => ({
-          msg: "Failed to decrypt with key, trying next",
-          data: {
-            keyIndex: keyIndex + 1,
-            totalKeys: validKeys.length,
-            err: error
-          }
+        this.logger?.error(() => ({
+          msg: "Failed to run decision machine in server PoW verification",
+          err: error
         }));
       }
     }
-    this.logger?.error(() => ({
-      msg: "Failed to decrypt behavioral data with all available keys",
-      data: {
-        totalKeysAttempted: validKeys.length
-      }
-    }));
-    return null;
+    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 {