Class PowCaptchaValidator

java.lang.Object
cloud.opencode.base.captcha.validator.PowCaptchaValidator
All Implemented Interfaces:
CaptchaValidator
public final class PowCaptchaValidator extends Object implements CaptchaValidator
Proof-of-Work Captcha Validator — Validates PoW nonce submissions 工作量证明验证码验证器 — 验证 PoW nonce 提交

Validates that SHA-256(challenge + nonce) has the required number of leading zero bits. The client submits a nonce that, when concatenated with the original challenge and hashed, produces a hash with the required number of leading zero bits.

验证 SHA-256(challenge + nonce) 是否具有所需数量的前导零位。 客户端提交一个 nonce，将其与原始挑战连接并哈希后， 产生具有所需数量前导零位的哈希值。

Features | 主要功能:

  • Single-use validation (challenge removed after check) - 一次性验证（检查后删除挑战）
  • Bit-level leading zero verification - 位级前导零验证
  • Constant-time hash computation (no timing side-channels) - 常量时间哈希计算（无时序侧信道）
  • Factory method for convenient creation - 工厂方法方便创建

Usage Examples | 使用示例:

CaptchaStore store = CaptchaStore.memory();
PowCaptchaValidator validator = PowCaptchaValidator.create(store);

// After generating a PoW CAPTCHA and storing the answer:
// store.store(captchaId, "challenge:20", Duration.ofMinutes(5));

// Client submits their computed nonce:
ValidationResult result = validator.validate(captchaId, clientNonce);
if (result.success()) {
    // PoW verified — proceed
}

Security | 安全性:

  • Thread-safe: Yes (delegates to thread-safe store) - 线程安全: 是（委托给线程安全的存储）
  • Null-safe: No (store, id, and answer must not be null) - 空值安全: 否（存储、ID和答案不能为null）
  • One-time use: Challenge is atomically removed on validation attempt - 一次性使用: 验证尝试时原子移除挑战

Performance | 性能:

  • Validation is O(1) — a single SHA-256 hash plus bit check - 验证为 O(1) — 单次 SHA-256 哈希加位检查
Since:
JDK 25, opencode-base-captcha V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Constructor Details

    • PowCaptchaValidator

      public PowCaptchaValidator(CaptchaStore store)
      Creates a new PoW validator with the specified store. 使用指定存储创建新的 PoW 验证器。
      Parameters:
      store - the CAPTCHA store for retrieving challenges | 用于检索挑战的验证码存储
      Throws:
      NullPointerException - if store is null | 如果 store 为 null

  • Method Details

    • validate

      public ValidationResult validate(String id, String answer)
      Validates a PoW nonce submission (case sensitivity is ignored for PoW). 验证 PoW nonce 提交（PoW 忽略大小写敏感性）。
      Specified by:
      validate in interface CaptchaValidator
      Parameters:
      id - the CAPTCHA ID | 验证码 ID
      answer - the nonce submitted by the client | 客户端提交的 nonce
      Returns:
      the validation result | 验证结果

    • validate

      public ValidationResult validate(String id, String answer, boolean caseSensitive)
      Validates a PoW nonce submission. 验证 PoW nonce 提交。

      The caseSensitive parameter is ignored for PoW validation, as the nonce is compared via cryptographic hash, not string equality.

      caseSensitive 参数在 PoW 验证中被忽略， 因为 nonce 通过加密哈希比较而非字符串相等比较。

      Specified by:
      validate in interface CaptchaValidator
      Parameters:
      id - the CAPTCHA ID | 验证码 ID
      answer - the nonce submitted by the client | 客户端提交的 nonce
      caseSensitive - ignored for PoW validation | PoW 验证中忽略此参数
      Returns:
      the validation result | 验证结果

    • create

      public static PowCaptchaValidator create(CaptchaStore store)
      Creates a new PoW validator with the specified store. 使用指定存储创建新的 PoW 验证器。
      Parameters:
      store - the CAPTCHA store | 验证码存储
      Returns:
      the PoW validator | PoW 验证器
      Throws:
      NullPointerException - if store is null | 如果 store 为 null