cks inherent in raw SHA-256 usage. */ public signRequest(payload: Buffer): string { const hmac = crypto.createHmac('sha256', this.config.hmacSecret); return hmac.update(payload).digest('hex'); }

/**

• Verifies an HMAC signature using constant-time comparison.
• Eliminates timing side-channels that leak valid prefixes. */ public verifySignature(payload: Buffer, expectedSignature: string): boolean { const computed = this.signRequest(payload); const expectedBuffer = Buffer.from(expectedSignature, 'hex'); const computedBuffer = Buffer.from(computed, 'hex');

if (expectedBuffer.length !== computedBuffer.length) {

  return false;
}

return crypto.timingSafeEqual(expectedBuffer, computedBuffer);

}

/**

• Hashes a password using Argon2id with memory-hard parameters.
• Automatically generates and embeds salts. */ public async hashCredential(plaintext: string): Promise<string> { return argon2.hash(plaintext, { type: argon2.argon2id, memoryCost: this.config.argon2Memory, iterations: this.config.argon2Iterations, parallelism: this.config.argon2Parallelism, hashLength: 32, salt: crypto.randomBytes(16), }); }

/**

• Verifies a password against an Argon2id hash.
• Handles salt extraction and constant-time comparison internally. */ public async verifyCredential(plaintext: string, storedHash: string): Promise<boolean> { return argon2.verify(storedHash, plaintext); } }

### Architecture Decisions & Rationale

1. **HMAC over Raw SHA-256 for APIs**: Raw SHA-256 is vulnerable to length-extension attacks, where an attacker can append data to a message and compute a valid hash without knowing the secret. HMAC wraps the hash in a keyed construction that mathematically prevents this.
2. **Constant-Time Verification**: String comparison (`===`) short-circuits on the first mismatched character, leaking timing information. `crypto.timingSafeEqual` ensures comparison duration remains constant regardless of input, neutralizing side-channel attacks.
3. **Argon2id for Passwords**: Argon2id combines data-dependent and data-independent memory hardness, defending against both GPU/ASIC cracking and side-channel leaks. The library handles salt generation and encoding, eliminating manual salt management errors.
4. **Explicit Configuration Injection**: Secrets and tuning parameters are injected via constructor rather than hardcoded. This enables environment-specific tuning (e.g., higher memory cost in production, lower in CI) and simplifies secret rotation.

## Pitfall Guide

### 1. Raw Hashing for Password Storage
**Explanation**: Using `SHA-256(password)` or `MD5(password)` exposes credentials to instant offline cracking. Modern GPUs can compute billions of SHA-256 hashes per second.
**Fix**: Always use purpose-built password hashing functions like Argon2id, bcrypt, or scrypt. They enforce deliberate slowness and memory hardness.

### 2. Manual Salt Management
**Explanation**: Developers sometimes generate salts manually and store them separately from hashes. This increases complexity and risks salt reuse or predictable generation.
**Fix**: Rely on library-managed salts. Argon2 and bcrypt embed the salt directly in the output string, guaranteeing uniqueness and simplifying storage.

### 3. Timing Attacks on Signature Verification
**Explanation**: Using standard string equality to compare HMAC digests allows attackers to measure response times and incrementally guess valid signatures.
**Fix**: Use `crypto.timingSafeEqual` or equivalent constant-time comparison utilities. Ensure buffer lengths match before comparison to prevent type errors.

### 4. Confusing Collision Resistance with Preimage Resistance
**Explanation**: MD5 is broken for collisions (two inputs → same hash), but still resists preimage attacks (finding input for a given hash). Developers sometimes assume "broken" means "useless for everything."
**Fix**: Reserve MD5 only for non-adversarial checksums (e.g., cache invalidation, non-security file deduplication). Never use it where an attacker can influence inputs.

### 5. Hardcoding HMAC Secrets
**Explanation**: Embedding signing keys in source control or configuration files enables trivial signature forgery if the repository is exposed.
**Fix**: Store secrets in environment variables or secret management systems (HashiCorp Vault, AWS Secrets Manager). Implement key rotation policies with versioned prefixes.

### 6. Assuming Longer Output Equals Higher Security
**Explanation**: SHA-512 produces a 512-bit digest, but on 32-bit systems or JavaScript runtimes, it incurs unnecessary computational overhead without meaningful security gains over SHA-256.
**Fix**: Default to SHA-256 for general cryptographic operations. Reserve SHA-512 for environments where 64-bit operations are native and maximum margin is required.

### 7. Ignoring Algorithm Deprecation Cycles
**Explanation**: Cryptographic standards evolve. Algorithms considered secure today may face practical attacks tomorrow. Static implementations become liabilities.
**Fix**: Abstract hashing behind interfaces. Log algorithm versions alongside hashes. Implement migration strategies to re-hash or re-sign data when standards shift.

## Production Bundle

### Action Checklist
- [ ] Threat model classification: Map every hashing usage to integrity, authentication, or credential storage.
- [ ] Algorithm audit: Replace all MD5/SHA-1 instances with SHA-256 or Argon2id based on context.
- [ ] Constant-time verification: Audit all signature/password comparisons for timing-safe implementations.
- [ ] Secret rotation policy: Define HMAC key lifecycle, versioning, and automated rotation triggers.
- [ ] Password hashing parameters: Tune Argon2id memory/iterations to match hardware capacity and latency budgets.
- [ ] Dependency pinning: Lock cryptographic library versions and monitor CVE feeds for algorithm deprecations.
- [ ] Logging strategy: Record hash algorithm versions and verification outcomes without exposing raw digests.

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| Software distribution / file verification | SHA-256 | Fast, collision-resistant, industry standard | Negligible CPU overhead |
| API request signing / webhook validation | HMAC-SHA256 | Prevents length-extension, verifies origin | Low memory, moderate CPU |
| User credential storage | Argon2id | Memory-hard, GPU-resistant, auto-salted | High CPU/memory per request |
| Cache invalidation / non-security dedup | MD5 (legacy) or SHA-256 | Speed prioritized over adversarial resistance | Minimal overhead |
| Long-term archival integrity | SHA-512 | Larger output margin, 64-bit optimized | Slightly higher CPU on 32-bit systems |

### Configuration Template

```typescript
// src/config/crypto.config.ts
import { HashConfig } from '../services/VerificationEngine';

export const cryptoConfig: HashConfig = {
  hmacSecret: process.env.HMAC_SIGNING_KEY || '',
  argon2Memory: parseInt(process.env.ARGON2_MEMORY_KB || '65536', 10),
  argon2Iterations: parseInt(process.env.ARGON2_ITERATIONS || '3', 10),
  argon2Parallelism: parseInt(process.env.ARGON2_PARALLELISM || '4', 10),
};

// Validation guard
if (!cryptoConfig.hmacSecret) {
  throw new Error('HMAC_SIGNING_KEY environment variable is required');
}
if (cryptoConfig.argon2Memory < 16384) {
  console.warn('Argon2 memory cost is below recommended minimum (16MB)');
}

Quick Start Guide

1. Install dependencies: Run npm install @node-rs/argon2 and ensure Node.js 18+ is active for native crypto module support.
2. Define environment variables: Set HMAC_SIGNING_KEY (minimum 32 random bytes), ARGON2_MEMORY_KB, ARGON2_ITERATIONS, and ARGON2_PARALLELISM.
3. Initialize the engine: Import VerificationEngine and cryptoConfig, then instantiate with new VerificationEngine(cryptoConfig).
4. Integrate into workflows: Use computeIntegrityHash() for file verification, signRequest()/verifySignature() for API endpoints, and hashCredential()/verifyCredential() for authentication flows.
5. Validate in staging: Run load tests to measure Argon2id latency and adjust memory/iteration parameters to maintain sub-300ms response times under expected concurrency.