Class ApiKeyHash

java.lang.Object
io.leandev.appfuse.security.auth.ApiKeyHash
public final class ApiKeyHash extends Object

API key 的雜湊（ADR-025 決策五）

簽發端（存 hash）與驗證端（比對每個請求帶來的 key）共用本類，確保 round-trip 對稱。

為何是 SHA-256 而非 bcrypt

慢雜湊（bcrypt／argon2）的價值在防低熵密碼的字典攻擊——刻意讓每次嘗試昂貴。API key 由 ClientCredentialsFactory.newApiKey() 產生、256 bits 隨機，沒有字典攻擊面：窮舉在物理上 不可行，慢雜湊擋的是一個不存在的威脅。

而代價是實在的：API key 是逐請求呈遞的憑證，用 bcrypt 等於每個請求付 ≈100ms 的 CPU ——那是自我 DoS。這與 client_secret 的處境不同（後者只在換 token 時比對一次，故用 PasswordEncoder）。

前提是 key 真的高熵：若消費端改用人工指定的短 key，本類的安全論證即不成立——那種情形 應改走密碼路徑（PasswordEncoder），不要沿用本類。

  • Method Details

    • of

      public static String of(String rawKey)

      計算 key 的雜湊（SHA-256 → url-safe base64，無 padding）

      無鹽：key 本身即高熵隨機值，rainbow table 不適用；且驗證端須以 key 直接查出對應主體 （逐筆比對加鹽雜湊等於全表掃描）。

      Parameters:
      rawKey - 明文 key
      Returns:
      雜湊值；rawKey 為 null／空白時回 null（呼叫端據此略過）