🧪 test: add JWT secret rotation BDD scenarios and step implementations (#12)

✨ merge: implement JWT secret rotation with BDD scenario isolation

- Implement JWT secret rotation mechanism (closes #8)
- Add per-scenario state isolation for BDD tests (closes #14)
- Validate password reset workflow via BDD tests (closes #7)
- Fix port conflicts in test validation
- Add state tracer for debugging test execution
- Document BDD isolation strategies in ADR 0025
- Fix PostgreSQL configuration environment variables

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
Co-authored-by: Gabriel Radureau <arcodange@gmail.com>
Co-committed-by: Gabriel Radureau <arcodange@gmail.com>

features/jwt/jwt_secret_retention.feature

@@ -0,0 +1,181 @@
+# features/jwt_secret_retention.feature
+Feature: JWT Secret Retention Policy
+  As a system administrator
+  I want automatic cleanup of expired JWT secrets
+  So that we can maintain security while ensuring system performance
+
+  Background:
+    Given the server is running with JWT secret retention configured
+    And the default JWT TTL is 24 hours
+    And the retention factor is 2.0
+    And the maximum retention is 72 hours
+
+  Scenario: Automatic cleanup of expired secrets
+    Given a primary JWT secret exists
+    And I add a secondary JWT secret with 1 hour expiration
+    When I wait for the retention period to elapse
+    Then the expired secondary secret should be automatically removed
+    And the primary secret should remain active
+    And I should see cleanup event in logs
+
+  Scenario: Secret retention based on TTL factor
+    Given the JWT TTL is set to 2 hours
+    And the retention factor is 3.0
+    When I add a new JWT secret
+    Then the secret should expire after 6 hours
+    And the retention period should be 6 hours
+
+  Scenario: Maximum retention period enforcement
+    Given the JWT TTL is set to 72 hours
+    And the retention factor is 3.0
+    And the maximum retention is 72 hours
+    When I add a new JWT secret
+    Then the retention period should be capped at 72 hours
+    And not exceed the maximum retention limit
+
+  Scenario: Cleanup preserves primary secret
+    Given a primary JWT secret exists
+    And the primary secret is older than retention period
+    When the cleanup job runs
+    Then the primary secret should not be removed
+    And the primary secret should remain active
+
+  @todo
+  Scenario: Multiple secrets with different ages
+    Given I have 3 JWT secrets of different ages
+    And secret A is 1 hour old (within retention)
+    And secret B is 50 hours old (expired)
+    And secret C is the primary secret
+    When the cleanup job runs
+    Then secret A should be retained
+    And secret B should be removed
+    And secret C should be retained as primary
+
+  @todo
+  Scenario: Cleanup frequency configuration
+    Given the cleanup interval is set to 30 minutes
+    When I add an expired JWT secret
+    Then it should be removed within 30 minutes
+    And I should see cleanup events every 30 minutes
+
+  @todo
+  Scenario: Token validation with expired secret
+    Given a user "retentionuser" exists with password "testpass123"
+    And I authenticate with username "retentionuser" and password "testpass123"
+    And I receive a valid JWT token signed with current secret
+    When I wait for the secret to expire
+    And I try to validate the expired token
+    Then the token validation should fail
+    And I should receive "invalid_token" error
+
+  @todo
+  Scenario: Graceful rotation during retention period
+    Given a user "gracefuluser" exists with password "testpass123"
+    And I authenticate with username "gracefuluser" and password "testpass123"
+    And I receive a valid JWT token signed with primary secret
+    When I add a new secondary secret and rotate to it
+    And I authenticate again with username "gracefuluser" and password "testpass123"
+    Then I should receive a new token signed with secondary secret
+    And the old token should still be valid during retention period
+    And both tokens should work until retention period expires
+
+  Scenario: Configuration validation
+    Given I set retention factor to 0.5
+    When I try to start the server
+    Then I should receive configuration validation error
+    And the error should mention "retention_factor must be ≥ 1.0"
+
+  @todo @nice_to_have
+  Scenario: Metrics for secret retention
+    Given I have enabled Prometheus metrics
+    When the cleanup job removes expired secrets
+    Then I should see "jwt_secrets_expired_total" metric increment
+    And I should see "jwt_secrets_active_count" metric decrease
+    And I should see "jwt_secret_retention_duration_seconds" histogram update
+
+  @todo @nice_to_have
+  Scenario: Log masking for security
+    Given I add a new JWT secret "super-secret-key-123456"
+    When the cleanup job runs
+    Then the logs should show masked secret "supe****123456"
+    And not expose the full secret in logs
+
+  @todo
+  Scenario: Cleanup with high volume of secrets
+    Given I have 1000 JWT secrets
+    And 300 of them are expired
+    When the cleanup job runs
+    Then it should complete within 100 milliseconds
+    And remove all 300 expired secrets
+    And not impact server performance
+
+  @todo
+  Scenario: Disabled cleanup via configuration
+    Given I set cleanup interval to 8760 hours
+    When I add expired JWT secrets
+    Then they should not be automatically removed
+    And manual cleanup should still be possible
+
+  @todo
+  Scenario: Retention period calculation edge cases
+    Given the JWT TTL is 1 hour
+    And the retention factor is 1.0
+    When I add a new JWT secret
+    Then the retention period should be 1 hour
+    And the secret should expire after 1 hour
+
+  @todo
+  Scenario: Secret validation with retention policy
+    Given I try to add an invalid JWT secret
+    When the secret is less than 16 characters
+    Then I should receive validation error
+    And the error should mention "must be at least 16 characters"
+
+  @todo
+  Scenario: Cleanup job error handling
+    Given the cleanup job encounters an error
+    When it tries to remove a secret
+    Then it should log the error
+    And continue with remaining secrets
+    And not crash the cleanup process
+
+  @todo
+  Scenario: Configuration reload without restart
+    Given the server is running with default retention settings
+    When I update the retention factor via configuration
+    Then the new settings should take effect immediately
+    And existing secrets should be reevaluated
+    And cleanup should use new retention periods
+
+  @todo @nice_to_have
+  Scenario: Audit trail for secret operations
+    Given I enable audit logging
+    When I add a new JWT secret
+    Then I should see audit log entry with event type "secret_added"
+    And when the secret is removed by cleanup
+    Then I should see audit log entry with event type "secret_removed"
+
+  @todo
+  Scenario: Retention policy with token refresh
+    Given a user "refreshuser" exists with password "testpass123"
+    And I authenticate and receive token A
+    When I refresh my token during retention period
+    Then I should receive new token B
+    And token A should still be valid until retention expires
+    And both tokens should work concurrently
+
+  @todo
+  Scenario: Emergency secret rotation
+    Given a security incident requires immediate rotation
+    When I rotate to a new primary secret
+    Then old tokens should be invalidated immediately
+    And new tokens should use the emergency secret
+    And cleanup should remove compromised secrets
+  
+  @todo @nice_to_have
+  Scenario: Monitoring and alerting
+    Given I have monitoring configured
+    When the cleanup job fails repeatedly
+    Then I should receive alert notification
+    And the alert should include error details
+    And suggest remediation steps