# Emergency Access Server

A fail-safe webserver that provides secure access to decryption key parts with mandatory notification system integration. Designed for emergency scenarios where key retrieval must be monitored and logged.

## Features

- **Fail-safe design**: All operations require successful notification delivery
- **Dual endpoint system**: Emergency key access and health monitoring
- **dschep/ntfy integration**: Real-time notifications via multiple backends (Pushover, Pushbullet, Slack, etc.)
- **Real-time log monitoring**: All application logs automatically sent to notification backends
- **Configurable security**: Random endpoint paths and file locations
- **Caddy reverse proxy ready**: Runs on localhost for secure proxy setup
- **Systemd integration**: Automatic startup and service management
- **Comprehensive logging**: Detailed audit trail of all operations with live notifications

## Architecture

The system consists of two main endpoints:

1. **Emergency Key Endpoint** (`/emergency-key-xyz123`): 
   - Serves the actual decryption key part
   - Sends critical alerts via dschep/ntfy to configured backends
   - Fails closed if notifications cannot be sent

2. **Health Check Endpoint** (`/health-check-abc456`):
   - Verifies all system components required for emergency access
   - Tests both health and emergency notification backends
   - Validates file system access for both dummy and key files
   - Ensures complete emergency system readiness
   - Used for regular system verification

**Log Monitoring**: All application logs (WARNING level and above by default) are automatically sent to the health backends for real-time monitoring and alerting.

The server runs on localhost:1127 by default and is designed to be accessed through a Caddy reverse proxy for security and TLS termination.

## Installation

### Quick Install

Run the automated installation script as root:

```bash
sudo ./install.sh
```

### Manual Installation

1. **Install system dependencies**:
   ```bash
   # Ubuntu/Debian
   sudo apt-get update
   sudo apt-get install python3 python3-pip python3-venv

   # RHEL/CentOS/Fedora (venv is built-in with Python 3.3+)
   sudo dnf install python3 python3-pip

   # Verify venv is available
   python3 -m venv --help
   ```

2. **Create service user**:
   ```bash
   sudo groupadd --system emergency-access
   sudo useradd --system --gid emergency-access --home-dir /opt/emergency-access \
                --shell /bin/false emergency-access
   ```

3. **Setup directories**:
   ```bash
   sudo mkdir -p /opt/emergency-access /etc/emergency-access
   sudo chown emergency-access:emergency-access /opt/emergency-access /etc/emergency-access
   sudo chmod 755 /opt/emergency-access
   sudo chmod 750 /etc/emergency-access
   ```

4. **Install application**:
   ```bash
   sudo cp *.py requirements.txt /opt/emergency-access/
   sudo cp config.json /etc/emergency-access/
   sudo chown -R emergency-access:emergency-access /opt/emergency-access
   ```

5. **Setup Python environment**:
   ```bash
   sudo -u emergency-access python3 -m venv /opt/emergency-access/venv
   sudo -u emergency-access /opt/emergency-access/venv/bin/pip install -r /opt/emergency-access/requirements.txt
   ```

6. **Install systemd service**:
   ```bash
   sudo cp emergency-access.service /etc/systemd/system/
   sudo systemctl daemon-reload
   ```

## Configuration

### Main Configuration File

Edit `/etc/emergency-access/config.json`:

```json
{
  "server": {
    "host": "127.0.0.1",
    "port": 1127
  },
  "routes": {
    "key_route": "/emergency-key-a7f9d2e1",
    "health_route": "/health-check-b8e3f4a2"
  },
  "files": {
    "key_file": "/etc/emergency-access/key-part.txt",
    "dummy_file": "/etc/emergency-access/dummy.txt"
  },
  "notifications": {
    "key_backends": ["matrix_sec", "pushover_emergency"],
    "health_backends": ["matrix_health"],
    "config_path": "/etc/emergency-access/ntfy.yml",
    "key_message": "🚨 EMERGENCY: Decryption key accessed from server",
    "health_message": "✅ Emergency access server health check completed",
    "log_level": "WARNING",
    "send_all_logs": true
  }
}
```

### Configuration Options

#### Server Settings
- `host`: Bind address (default: `127.0.0.1` for localhost only)
- `port`: Listen port (default: `1127`)

#### Route Settings
- `key_route`: Random path for key access (e.g., `/emergency-key-a7f9d2e1`)
- `health_route`: Path for health checks (e.g., `/health-check-b8e3f4a2`)

#### File Settings
- `key_file`: Path to the actual key part file
- `dummy_file`: Path to dummy content for health checks (health check also validates key file accessibility)

#### Notification Settings
- `key_backends`: List of backend names from `/etc/emergency-access/ntfy.yml` for key access alerts
- `health_backends`: List of backend names from `/etc/emergency-access/ntfy.yml` for health check notifications and all application logs
- `config_path`: Path to the ntfy configuration file (default: `/etc/emergency-access/ntfy.yml`)
- `key_message`: Message sent when key is accessed
- `health_message`: Message sent for health checks
- `log_level`: Minimum log level to send to health backends ("INFO", "WARNING", "ERROR")
- `send_all_logs`: Whether to send application logs to health backends (true/false)

#### Backend Name Examples
- `matrix_sec`: Matrix backend for security alerts
- `pushover_emergency`: Pushover backend for emergency notifications
- `slack_critical`: Slack backend for critical alerts
- Any backend name configured in `/etc/emergency-access/ntfy.yml`

### Key and Dummy Files

1. **Create key file**:
   ```bash
   echo "YOUR_ACTUAL_KEY_PART_HERE" | sudo tee /etc/emergency-access/key-part.txt
   sudo chown emergency-access:emergency-access /etc/emergency-access/key-part.txt
   sudo chmod 600 /etc/emergency-access/key-part.txt
   ```

2. **Create dummy file**:
   ```bash
   echo "system_healthy" | sudo tee /etc/emergency-access/dummy.txt
   sudo chown emergency-access:emergency-access /etc/emergency-access/dummy.txt
   sudo chmod 644 /etc/emergency-access/dummy.txt
   ```

## dschep/ntfy Backend Setup

The system uses a dedicated ntfy configuration file at `/etc/emergency-access/ntfy.yml`. Configure your notification backends in this file and reference them by name in the main configuration.

### Configuring Notification Backends

1. **Edit the dedicated ntfy config** (`/etc/emergency-access/ntfy.yml`):
   ```yaml
   backends:
     - matrix_sec
     - matrix_health
     - pushover_emergency
   
   matrix_sec:
     backend: matrix
     url: https://your-matrix-server.com
     roomId: "!emergency-security:your-matrix-server.com"
     userId: "@emergency-bot:your-matrix-server.com"
     password: "your-matrix-bot-password"
   
   matrix_health:
     backend: matrix
     url: https://your-matrix-server.com
     roomId: "!emergency-health:your-matrix-server.com"
     userId: "@emergency-bot:your-matrix-server.com"
     password: "your-matrix-bot-password"
   
   pushover_emergency:
     backend: pushover
     user_key: YOUR_PUSHOVER_USER_KEY
     priority: 2
     retry: 60
     expire: 3600
     sound: siren
   ```

2. **Reference backend names** in emergency access config:
   ```json
   "notifications": {
     "key_backends": ["matrix_sec", "pushover_emergency"],
     "health_backends": ["matrix_health"],
     "config_path": "/etc/emergency-access/ntfy.yml"
   }
   ```

### Adding Additional Backends

Add more backends to `/etc/emergency-access/ntfy.yml` as needed:

```yaml
# Additional backends in /etc/emergency-access/ntfy.yml
backends:
  - matrix_sec
  - matrix_health
  - pushover_emergency
  - slack_critical
  - email_emergency

slack_critical:
  backend: slack
  token: YOUR_SLACK_BOT_TOKEN
  recipient: "#emergency-alerts"

email_emergency:
  backend: email
  smtp_server: smtp.gmail.com
  smtp_port: 587
  username: your-email@gmail.com
  password: your-app-password
  to: emergency-team@company.com
  from: emergency-access@company.com
```

## Service Management

### Start and Enable Service

```bash
# Start the service
sudo systemctl start emergency-access

# Enable automatic startup
sudo systemctl enable emergency-access

# Check status
sudo systemctl status emergency-access
```

### Monitoring and Logs

```bash
# View real-time logs
sudo journalctl -u emergency-access -f

# View log file
sudo tail -f /var/log/emergency-access.log

# Check service health (through Caddy proxy)
curl https://your-domain.com/health-check-b8e3f4a2

# Or directly to local service (for testing)
curl http://localhost:1127/health-check-b8e3f4a2
```

## Usage

### Emergency Key Access

```bash
# Access the key (replace with your actual route)
curl https://your-domain.com/emergency-key-a7f9d2e1

# Expected response:
{
  "success": true,
  "key_part": "YOUR_KEY_PART_HERE",
  "timestamp": 1703123456.789,
  "notified_backends": ["matrix_sec"]
}
```

### Health Check

```bash
# Regular health monitoring
curl https://your-domain.com/health-check-b8e3f4a2

# Expected response (all systems operational):
{
  "status": "ok",
  "timestamp": 1703123456.789,
  "health_backends_notified": ["matrix_health"],
  "key_backends_tested": ["matrix_sec", "pushover_emergency"],
  "dummy_content_length": 14,
  "key_file_accessible": true,
  "emergency_system_ready": true
}

# Error response (when components fail):
{
  "status": "error",
  "message": "System components failed",
  "details": ["key notifications failed", "key file access failed: Permission denied"],
  "health_notifications": true,
  "key_notifications": false,
  "dummy_file_access": true,
  "key_file_access": false
}
```

## Security Considerations

### Caddy Reverse Proxy Setup

1. **Basic Caddyfile configuration**:
   ```caddy
   emergency.yourdomain.com {
       tls your-email@example.com
       reverse_proxy localhost:1127
       
       header {
           X-Content-Type-Options nosniff
           X-Frame-Options DENY
       }
       
       rate_limit {
           zone emergency {
               key {remote_host}
               events 10
               window 1m
           }
       }
   }
   ```

2. **Path-based routing**:
   ```caddy
   yourdomain.com {
       handle /emergency/* {
           uri strip_prefix /emergency
           reverse_proxy localhost:1127
       }
   }
   ```

3. **IP-restricted access**:
   ```caddy
   :443 {
       @allowed_ips remote_ip 192.168.0.0/16
       handle @allowed_ips {
           reverse_proxy localhost:1127
       }
       handle {
           respond "Access Denied" 403
       }
   }
   ```

### Network Security

The service binds only to localhost (127.0.0.1:1127) and is accessed through your existing Caddy reverse proxy. No additional firewall configuration is required.

### File Permissions

- Key file: `600` (owner read-only)
- Config file: `640` (owner read/write, group read)
- Application files: `644` (standard read permissions)

### Monitoring

1. **Set up regular health checks**:
   ```bash
   # Cron job for health monitoring through Caddy
   */5 * * * * curl -s https://yourdomain.com/health-check-b8e3f4a2 > /dev/null
   
   # Or direct to service for internal monitoring
   */5 * * * * curl -s http://localhost:1127/health-check-b8e3f4a2 > /dev/null
   ```

2. **Monitor notification delivery**:
   - Configure notification backends (Pushover, Pushbullet, etc.)
   - Set up monitoring of notification delivery in your backends
   - Monitor log files for errors
   - All application logs are automatically sent to health backends for real-time monitoring

## Troubleshooting

### Common Issues

1. **Service won't start**:
   ```bash
   sudo journalctl -u emergency-access -n 50
   sudo systemctl status emergency-access
   ```

2. **Notification failures**:
   ```bash
   # Test dschep/ntfy installation and configuration
   ntfy -c /etc/emergency-access/ntfy.yml send "test message"
   
   # Check ntfy configuration
   cat /etc/emergency-access/ntfy.yml
   
   # Test specific backend
   ntfy -c /etc/emergency-access/ntfy.yml -b matrix_sec send "test message"
   ```

3. **File permission errors**:
   ```bash
   sudo chown -R emergency-access:emergency-access /opt/emergency-access
   sudo chown emergency-access:emergency-access /etc/emergency-access/*
   ```



### Configuration Validation

Test your setup before deployment:

```bash
# Validate configuration
sudo -u emergency-access /opt/emergency-access/venv/bin/python /opt/emergency-access/main.py --validate

# Test notifications manually with your backend
ntfy -c /etc/emergency-access/ntfy.yml -b matrix_sec send "Test notification"
ntfy -c /etc/emergency-access/ntfy.yml -b pushover_emergency send "Test emergency notification"
```

## Development

### Running in Development Mode

```bash
# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run with development config
EMERGENCY_CONFIG=config.json python main.py
```

### Testing

```bash
# Test key endpoint (direct to service)
curl http://localhost:1127/emergency-key-xyz123

# Test health endpoint (direct to service)
curl http://localhost:1127/health-check

# Test through Caddy proxy
curl https://yourdomain.com/emergency-key-xyz123
curl https://yourdomain.com/health-check
```

## License

This project is designed for emergency access scenarios. Use responsibly and ensure proper security measures are in place.

## Support

For issues and questions:
1. Check the logs: `/var/log/emergency-access.log`
2. Verify configuration: `/etc/emergency-access/config.json`
3. Test notification systems independently
4. Monitor service status: `systemctl status emergency-access`