feat: implement API key authentication for iOS client security

[bmchrist]

Closes #2

Summary

Implemented API key authentication for the iOS client following Apple's latest security standards.

Changes

• Added secure API key generation using crypto/rand (256-bit keys)
• Implemented authentication middleware with X-API-Key header validation
• Protected all endpoints except health check and API key generation
• Added master key system for controlled API key generation
• Created comprehensive iOS implementation guide in CLAUDE.md
• Added API key persistence and test coverage
• Updated README with authentication documentation

iOS Implementation Details

The CLAUDE.md file now contains:

• Complete Keychain storage examples for secure key management
• Network request examples with authentication headers
• Biometric authentication integration (Face ID/Touch ID)
• Security best practices following Apple's latest standards

Generated with Claude Code

[claude]

Code Review

I've reviewed the API key authentication implementation. Overall, this is a solid security enhancement with good iOS integration documentation. Here are my findings:

✅ Strengths

1. Strong Cryptographic Implementation: Uses crypto/rand for 256-bit keys (32 bytes) which provides excellent entropy
2. Secure Comparisons: Uses subtle.ConstantTimeCompare for master key validation to prevent timing attacks
3. Comprehensive iOS Documentation: Excellent Swift examples with Keychain storage, biometric authentication, and proper error handling
4. Good Test Coverage: auth_test.go covers key generation, validation, middleware, and persistence
5. Backward Compatibility: Health check endpoint remains public while protecting sensitive operations

🔍 Areas for Improvement

1. Security Considerations

• API Key Rotation: While mentioned in docs, there's no actual endpoint to rotate/regenerate keys. Consider adding a POST /rotate-api-key endpoint.

• Rate Limiting: No rate limiting on API key generation endpoint could allow brute-force attempts on the master key. Consider adding rate limiting middleware.

• Key Expiration: API keys never expire. Consider adding an optional ExpiresAt field to the APIKey struct.

2. Code Quality

• Error Handling: In auth.go:228, saveAPIKeys() errors are only logged, not returned. This could lead to silent failures where keys appear created but aren't persisted.

• File Permissions: api_keys.json is saved with 0600 permissions (good), but consider using a more robust storage solution for production (e.g., encrypted SQLite, environment-specific key stores).

• Concurrent Access: While mutex protection exists, the one-key-per-user limitation (auth.go:62-64) might be restrictive for users with multiple devices.

3. Operational Concerns

• Master Key Management:

  • Auto-generating master key on startup (main.go:126-129) is convenient but risky for production
  • Consider requiring MASTER_API_KEY to be set explicitly in production environments
  • Add validation that master key meets minimum entropy requirements

• Logging: Good security logging, but consider adding structured logging for better observability

4. Testing Gaps

• Missing test for concurrent API key creation/validation
• No test for API key persistence across server restarts
• Consider adding integration tests for the full authentication flow

5. Documentation

• README could benefit from a "Security" section explaining:
  • How API keys are stored (encrypted at rest would be ideal)
  • Key rotation procedures
  • What to do if a key is compromised
  • Audit trail capabilities

🐛 Potential Bugs

1. Race Condition: In createAPIKey(), if two requests for the same user arrive simultaneously, the second might overwrite the first before saveAPIKeys() completes.

2. Memory Growth: validateAPIKey() updates LastUsed and saves to disk on every request. High traffic could cause performance issues. Consider batching updates or using an in-memory cache with periodic flushes.

📋 Recommendations

1. High Priority:

   • Add rate limiting to prevent brute-force attacks
   • Implement API key rotation endpoint
   • Require explicit MASTER_API_KEY in production

2. Medium Priority:

   • Add key expiration support
   • Implement structured logging
   • Consider multi-key per user support

3. Low Priority:

   • Move to encrypted storage for production
   • Add metrics/monitoring for key usage
   • Implement audit trail for security events

✅ Summary

This PR successfully implements secure API key authentication with excellent iOS integration guidance. The core implementation is solid, but would benefit from additional security hardening for production use. The test coverage is good but could be expanded for edge cases and concurrency scenarios.

Recommendation: Approve with the understanding that follow-up PRs should address the high-priority security improvements, especially rate limiting and key rotation capabilities.