[Security P5] Use constant-time comparisons and salted KDF for stored credential hashes

[cursor]

Summary

API tokens and ingest secrets are stored as plain SHA-256 hashes without per-credential salt or a slow KDF. Secret comparisons use non-constant-time equality checks.

Severity

Medium

Context

From full-codebase security review (2026-07-11). Priority remediation item #5.

Affected areas

• apps/api/src/application/auth.ts:5-11 — SHA-256 hashing
• apps/api/src/application/auth.ts:39-47 — bootstrap token compared with ===
• apps/api/src/application/tokens.ts:52-53 — token hash storage
• apps/api/src/application/ingest.ts:349-354 — ingest secret verification via Array.find + ===
• apps/api/src/application/endpoints.ts:336 — endpoint secret hashing

Risk

• Database leak enables faster offline hash comparison attacks
• Timing side channels on secret/token verification (lower practical risk with high-entropy secrets, but worth hardening)
• Bootstrap token comparison is especially sensitive if the token is weak

Recommendations

• Use a slow KDF (e.g. PBKDF2, scrypt, or Argon2 via Web Crypto) with per-record salt for stored hashes
• Compare fixed-length digests with constant-time equality (crypto.subtle.timingSafeEqual or equivalent)
• For multiple active ingest secrets, compare all hashes in constant time without early exit
• Enforce strong bootstrap secret length/entropy; disable bootstrap in production after initial provisioning

Acceptance criteria

• Token and ingest secret hashes use salted slow KDF
• All secret/token comparisons are constant-time
• Migration path for existing hashed credentials is documented or implemented
• Tests cover timing-safe comparison behavior
• Bootstrap token handling is hardened

References

• Security review findings: unsalted SHA-256, non-constant-time comparisons
• Related spec: requirements/barestash-backend.spec.md

[codemountains]

Closing as completed by #98.

The original finding was valid: plain SHA-256 storage and non-constant-time comparisons needed hardening. PR #98 replaced stored PAT and endpoint ingest-secret hashes with HMAC-SHA-256(server pepper, raw secret), added constant-time digest comparison, checks every active ingest secret without an early exit, hardened bootstrap-token handling, and documented the breaking migration/replacement path for legacy hashes. The PR has been merged to main, with CI and end-to-end checks passing.

We intentionally did not adopt the issue's salted slow-KDF acceptance criterion. Barestash credentials are machine-generated, high-entropy secrets rather than user-chosen passwords, and the authentication specification defines peppered HMAC-SHA-256 as the source-of-truth storage scheme. A slow password KDF would add request cost and denial-of-service exposure without materially improving resistance to guessing these random secrets. The server-side pepper also protects hashes if D1 alone is disclosed.

Accordingly, the security risk described here is addressed by the merged implementation, while the implementation differs from the originally proposed KDF mechanism by design.