feat: Add emergency token rotation runbook and automation script

- Created a comprehensive runbook for emergency token rotation, detailing when to rotate, prerequisites, and step-by-step procedures.
- Included methods for generating secure tokens, updating configurations, and verifying new tokens.
- Added an automation script for token rotation to streamline the process.
- Implemented compliance checklist and troubleshooting sections for better guidance.

test: Implement E2E tests for emergency server and token functionality

- Added tests for the emergency server to ensure it operates independently of the main application.
- Verified that the emergency server can bypass security controls and reset security settings.
- Implemented tests for emergency token validation, rate limiting, and audit logging.
- Documented expected behaviors for emergency access and security enforcement.

refactor: Introduce security test fixtures for better test management

- Created a fixtures file to manage security-related test data and functions.
- Included helper functions for enabling/disabling security modules and testing emergency access.
- Improved test readability and maintainability by centralizing common logic.

test: Enhance emergency token tests for robustness and coverage

- Expanded tests to cover various scenarios including token validation, rate limiting, and idempotency.
- Ensured that emergency token functionality adheres to security best practices.
- Documented expected behaviors and outcomes for clarity in test results.

.docker/compose/docker-compose.e2e.yml

@@ -16,8 +16,9 @@ services:
     restart: "no"
     ports:
       - "8080:8080"    # Management UI (Charon)
+      - "2020:2020"    # Emergency server (DO NOT expose publicly in production!)
     environment:
-      - CHARON_ENV=development
+      - CHARON_ENV=e2e  # Enable lenient rate limiting (50 attempts/min) for E2E tests
       - CHARON_DEBUG=0
       - TZ=UTC
       # Encryption key - MUST be provided via environment variable
@@ -26,6 +27,11 @@ services:
       # Emergency reset token - for break-glass recovery when locked out by ACL
       # Generate with: openssl rand -hex 32
       - CHARON_EMERGENCY_TOKEN=${CHARON_EMERGENCY_TOKEN:-test-emergency-token-for-e2e-32chars}
+      # Emergency server (Tier 2 break glass) - separate port bypassing all security
+      - CHARON_EMERGENCY_SERVER_ENABLED=true
+      - CHARON_EMERGENCY_BIND=0.0.0.0:2020  # Bind to all interfaces in container (avoid Caddy's 2019)
+      - CHARON_EMERGENCY_USERNAME=admin
+      - CHARON_EMERGENCY_PASSWORD=${CHARON_EMERGENCY_PASSWORD:-changeme}
       - CHARON_HTTP_PORT=8080
       - CHARON_DB_PATH=/app/data/charon.db
       - CHARON_FRONTEND_DIR=/app/frontend/dist

.docker/compose/docker-compose.yml

@@ -8,11 +8,23 @@ services:
       - "443:443"      # HTTPS (Caddy proxy)
       - "443:443/udp"  # HTTP/3 (Caddy proxy)
       - "8080:8080"    # Management UI (Charon)
+      # Emergency server port - ONLY expose via SSH tunnel or VPN for security
+      # Uncomment ONLY if you need localhost access on host machine:
+      # - "127.0.0.1:2019:2019"  # Emergency server (localhost-only)
     environment:
       - CHARON_ENV=production # CHARON_ preferred; CPM_ values still supported
       - TZ=UTC # Set timezone (e.g., America/New_York)
       # Generate with: openssl rand -base64 32
       - CHARON_ENCRYPTION_KEY=your-32-byte-base64-key-here
+      # Emergency break glass configuration (Tier 1 & Tier 2)
+      # Tier 1: Emergency token for Layer 7 bypass within application
+      # Generate with: openssl rand -hex 32
+      # - CHARON_EMERGENCY_TOKEN=${CHARON_EMERGENCY_TOKEN}  # Store in secrets manager
+      # Tier 2: Emergency server on separate port (bypasses Caddy/CrowdSec entirely)
+      # - CHARON_EMERGENCY_SERVER_ENABLED=false  # Disabled by default
+      # - CHARON_EMERGENCY_BIND=127.0.0.1:2019   # Localhost only
+      # - CHARON_EMERGENCY_USERNAME=admin
+      # - CHARON_EMERGENCY_PASSWORD=${EMERGENCY_PASSWORD}  # Store in secrets manager
       - CHARON_HTTP_PORT=8080
       - CHARON_DB_PATH=/app/data/charon.db
       - CHARON_FRONTEND_DIR=/app/frontend/dist