feat: support API key signing-secret rotation with grace window #1184

[OluwapelumiElisha]

📝 Description #1184

Adds support for rotating API key signing secrets through a new admin-only endpoint without requiring API key reissuance. The implementation introduces a configurable grace window that allows both the previous and newly generated signing secrets to remain valid during transition, preventing integrator downtime. All rotations are recorded in the audit trail for security and compliance purposes.

🎯 Type of Change

• New feature
• Security enhancement
• Documentation update

🔧 Changes Made

Files Modified

• backend/src/models/api-key.ts
• backend/src/services/api-key-service.ts
• backend/src/controllers/v1/api-keys.ts
• backend/src/routes/v1/api-keys.ts
• backend/docs/auth.md
• backend/openapi.yaml

New Files Added

• backend/src/tests/api-key-rotation.test.ts

Key Changes

• Added prev_signing_secret_hash and prev_secret_expires_at fields to API key model.
• Implemented admin endpoint: POST /api/v1/admin/api-keys/:id/rotate-signing-secret.
• Added configurable secret rotation grace period (default: 24 hours).
• Ensured both old and new secrets are accepted during the grace window.
• Invalidated previously rotated secrets when a subsequent rotation occurs.
• Added audit logging for all secret rotation events.
• Protected endpoint with existing admin RBAC middleware.
• Updated API documentation and authentication guides.
• Ensured newly generated secrets are returned only once and never logged.

🧪 Testing

Test Coverage

• Verified old and new signing secrets are accepted during grace period.
• Verified previous secret expires after grace window.
• Verified subsequent rotations invalidate earlier previous secrets.
• Verified audit entries are created for every rotation.
• Verified non-admin users receive authorization errors.
• Verified generated secrets are returned exactly once and excluded from logs.

🔒 Security Notes

• Rotation endpoint restricted to administrators.
• Secret hashes stored instead of plaintext values.
• Previous secrets automatically expire after configured grace period.
• Audit trail maintained for all rotation activity.

Merge #1184