Implement API key generation, hashing, and validation utilities (issue #540)

[ngjunsiang]

Summary

Implements API key generation, hashing, and validation utilities for the Campus Audit Service as specified in issue #540. This provides the cryptographic foundation for secure API key authentication.

Changes

New Functions in campus/common/utils/secret.py

• generate_audit_api_key() - Generate 31-character API keys with format audit_v1_<22-char-base64url>
• hash_api_key() - SHA-256 hashing for secure storage (64-char hex output)
• verify_api_key_hash() - Constant-time comparison using hmac.compare_digest() to prevent timing attacks
• is_valid_audit_api_key_format() - Format validation (prefix, length, base64url character set)

Key Format Specification

audit_v1_kXj9mP2nQ5vR8sT7uV3wY4zX5cV6bN7m
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
         22 base64url chars (~132-bit entropy)

• Total Length: 31 characters (9-char prefix + 22-char random)
• Entropy: ~132 bits (strong security margin)
• Encoding: URL-safe base64url (no +, /, or = padding)
• Prefix: audit_v1_ for version identification

Comprehensive Unit Tests

Added 20 test cases in tests/unit/common/test_secret.py:

• Key generation uniqueness and format validation
• Hash generation and verification edge cases
• Security property tests (randomness, distribution)
• Performance benchmarks: 723K verifications/second (0.0014ms each)

Acceptance Criteria

✅ Key generation creates 31-char keys with audit_v1_ prefix
✅ Keys use base64url encoding for URL-safe characters
✅ ~132-bit entropy achieved with 22 random characters
✅ SHA-256 hashing (salt optional per requirements)
✅ Constant-time comparison for timing attack prevention
✅ Comprehensive edge case handling
✅ Security enforced (no key logging, timing-safe comparison)
✅ 20 security-focused unit tests
✅ Performance benchmarks (723K ops/sec)

Status: 8/9 applicable criteria fully met

Security Features

• Constant-time comparison prevents timing attacks on verification
• 132-bit entropy provides strong security margin (Stripe: ~130 bits, GitHub: 160 bits)
• SHA-256 hashing for secure storage (never store plaintext keys)
• No key logging in implementation
• Comprehensive validation prevents format-based attacks

Performance

• Hash verification: 0.0014ms per operation (723K ops/sec)
• Well under target: <0.1ms per verification ✅
• Suitable for high-throughput API authentication

Related Issues

• Resolves Issue 538.2: API Key Hashing and Validation #540 (API Key Hashing and Validation)
• Part of campus.audit: API Key Security Implementation #538 (API Key Security Implementation)
• Follows Issue 538.1: API Key Model Implementation #539 (API Key Model Implementation)

Next Steps

Future issues will implement:

• Issue 538.3: API Key Management Endpoints #541: API Key Management Endpoints (CRUD operations)
• Issue 538.4: API Key Authentication Middleware #542: API Key Authentication Middleware (request validation)

Testing

PYTHONPATH=/home/kureshii/nyjc-computing/campus python -m unittest tests.unit.common.test_secret.TestAuditAPIKeyFunctions -v

All 20 tests passing ✅

🤖 Generated with Claude Code

[ngjunsiang]

Integration test failures related to ongoing work in audit middleware, for which this issue is working towards a resolution