Feat/security hardening

[DioChuks]

Summary

Successfully hardened API key validation in the Go REST API, added CLI/script key generation tooling, documented the complete API key lifecycle, updated environment configuration references, and verified all tests pass.

Changes Made

1. API Key Validation Middleware

• auth.go:
  • Added crypto/subtle import.
  • Implemented ConstantTimeContains(validHashes, targetHash) helper using subtle.ConstantTimeCompare to eliminate timing side-channel vulnerabilities during hash comparisons.
  • Updated ParseKeyHashes to automatically fall back to single-key environment variable API_KEY when API_KEY_HASHES is not set.
  • Ensured raw key strings are never stored in memory structures or emitted in logs.

2. Key Generation Tooling

• services/api/cmd/keygen/main.go:
  • Created a Go CLI utility that generates a 32-byte cryptographically secure random API key (crypto/rand), hex-encodes it (64 characters), computes its HMAC-SHA256 digest using API_KEY_SALT, and prints deployment configuration instructions.
• scripts/generate-api-key.sh:
  • Created helper script wrapping go run ./cmd/keygen for quick key generation.

3. Documentation & Environment References

• [docs/api-keys.md]docs/api-keys.md):
  • Documented overview, security model, key generation instructions, environment setup, zero-downtime key rotation procedure, and Phase 1 vs Phase 2 architecture.
• .env.example & docs/ENVIRONMENT.md:
  • Added documentation and usage guidance for API_KEY, API_KEY_HASHES, and API_KEY_SALT.

4. Unit Tests

• auth_test.go:
  • Updated unit tests to verify valid key, missing key (401 + UNAUTHORIZED), invalid key (401 + UNAUTHORIZED), public /v1/health bypass, API_KEY fallback, constant-time hash comparison logic, and raw key non-leakage.

Verification Results

Unit Tests

Ran go test ./... in services/api:

• All test packages (handlers, middleware, httputil, config, cursor, grpc, internal/*, validation, ws) passed 100%.

Closes #48

[drips-wave]

@DioChuks Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits