fix(security): add API key rotation and optional TTL expiry

[anshul23102]

Problem

backend/data/.api_key stores the single authentication secret as a plaintext file with no TTL, rotation endpoint, or revocation mechanism. Any process with read access to that directory (a co-located container, a path-traversal exploit, or a leaked backup) obtains a credential that is valid indefinitely.

Fix

• Key file is now JSON ({"key": ..., "created_at": <epoch seconds>}) instead of bare plaintext, so the key's age can be tracked. A pre-existing plaintext key file is migrated in place on next startup -- the key itself is kept, just wrapped with a fresh created_at.
• POST /api/v1/admin/api-key/rotate generates a new key and invalidates the old one immediately -- no grace period. Gated by the separate, statically-configured admin API key so a leaked client key can never be used to mint itself a replacement.
• GET /api/v1/admin/api-key/status reports the key's age and, if configured, its expiry, without exposing the key itself.
• New SECUSCAN_API_KEY_TTL_SECONDS setting (default 0 = disabled, so existing deployments are unaffected until an operator opts in). When set, both require_api_key and the session-creation endpoint reject the client key once it's older than the TTL, forcing rotation.
• Documented the new flow in docs/api-authentication.md.

Testing

• testing/backend/unit/test_api_key_rotation.py: 15 new tests covering the JSON key format, legacy-plaintext migration, rotate/status endpoint auth gating, immediate old-key invalidation, and TTL expiry on both the main auth dependency and session creation
• Updated test_auth.py and test_api_auth.py: existing init_api_key tests asserted the key file was bare plaintext; updated to read the new JSON format (the key value itself is unchanged)
• pytest testing/backend/unit -q -m "not benchmark" -- 2240 passed, 1 pre-existing failure unrelated to this change (parser sandbox timeout test, flaky in this environment)
• ruff check -- all checks passed

Fixes #1619

[utksh1]

Excellent security enhancement! Addresses #1619 by adding API key rotation and optional TTL expiry.

Key improvements:
✅ Key file now JSON format with created_at timestamp
✅ POST /api/v1/admin/api-key/rotate endpoint (admin-gated)
✅ GET /api/v1/admin/api-key/status for monitoring
✅ Optional SECUSCAN_API_KEY_TTL_SECONDS setting
✅ Backward compatible - migrates plaintext keys automatically
✅ Comprehensive test coverage (15 new tests)

Next step: This PR is from July 8th. Please rebase with main to pick up recent changes (#2037, #2038, #2039, #2040, #2041, #2042) and verify all tests still pass. Once rebased, I'll merge immediately!

[utksh1]

This remains approved in principle, but the branch is behind main. Please rebase it on current main and rerun the API-key rotation/TTL test suite; it can be merged once the refreshed checks are clean.

[utksh1]

This remains approved in principle, but the branch is behind main. Please rebase it on current main and rerun the API-key rotation/TTL test suite; it can be merged once the refreshed checks are clean.

[anshul23102]

Addressed all feedback from your review:

1. Fixed the critical read-only file issue by:

   • Detecting when SECUSCAN_API_KEY_FILE is set (custom path for Docker secrets)
   • Checking write permissions before attempting plaintext-to-JSON migration
   • Gracefully using legacy keys on read-only mounts without attempting write

2. Updated README documentation to reflect the new JSON format:

   • Changed cat backend/data/.api_key to cat backend/data/.api_key | jq -r '.key'
   • Updated API examples to correctly extract the key from JSON

3. Rebased on current main to pick up all recent changes

The PR now handles read-only secret mounts safely and operators using SECUSCAN_API_KEY_FILE will not encounter write errors on startup.