chore: add mtls specific middleware and error msgs

Ticket: WP-4663

Author: pranavjain97

README.md

@@ -1,161 +1,226 @@
-# Enclaved Express
+# Enclaved BitGo Express
 
-Enclaved Express is a secure signer implementation for cryptocurrency operations. It's designed to run in a secure enclave environment with mTLS security.
+A secure, mTLS-enabled cryptocurrency signing server with two operational modes: Enclaved Express (dedicated signer) and Master Express (API gateway with integrated signing capabilities).
 
 ## Overview
 
-This module provides a lightweight, dedicated signing server with these features:
+This application provides secure cryptocurrency operations with mutual TLS (mTLS) authentication:
 
-- Focused on signing operations only - no BitGo API dependencies
-- mTLS security for secure connections with client certificate validation
-- Simple configuration and deployment
+- **Enclaved Mode**: Lightweight signing server for secure key operations
+- **Master Express Mode**: Full BitGo Express functionality with integrated signing
+- **mTLS Security**: Client certificate validation for secure communications
+- **Flexible Configuration**: Environment-based setup with file or variable-based certificates
 
-## Supported Operations
+## Architecture
 
-Currently, the following operations are supported:
-
-- `/ping` - Health check endpoint
+- **Enclaved Express** (Port 3080): Focused signing operations with KMS integration
+- **Master Express** (Port 3081): Full BitGo API functionality with secure communication to Enclaved Express
 
 ## Configuration
 
-Configuration is done via environment variables:
+Configuration is managed through environment variables:
 
 ### Required Settings
 
-- `APP_MODE` - Application mode (required, must be either "enclaved" or "master-express")
+- `APP_MODE` - Application mode (required: "enclaved" or "master-express")
 
 ### Network Settings
 
-#### Enclaved Mode
+- `BIND` - Address to bind to (default: localhost)
+- `TIMEOUT` - Request timeout in milliseconds (default: 305000)
+- `KEEP_ALIVE_TIMEOUT` - Keep-alive timeout (optional)
+- `HEADERS_TIMEOUT` - Headers timeout (optional)
+
+#### Enclaved Mode Specific
 
 - `ENCLAVED_EXPRESS_PORT` - Port to listen on (default: 3080)
-- `MASTER_BITGO_EXPRESS_BIND` - Address to bind to (default: localhost)
-- `MASTER_BITGO_EXPRESS_TIMEOUT` - Request timeout in milliseconds (default: 305000)
+- `KMS_URL` - KMS service URL (required)
 
-#### Master Express Mode
+#### Master Express Mode Specific
 
 - `MASTER_EXPRESS_PORT` - Port to listen on (default: 3081)
-- `BITGO_BIND` - Address to bind to (default: localhost)
-- `BITGO_TIMEOUT` - Request timeout in milliseconds (default: 305000)
+- `BITGO_ENV` - BitGo environment (default: test)
+- `BITGO_DISABLE_ENV_CHECK` - Disable environment check (default: true)
+- `BITGO_AUTH_VERSION` - Authentication version (default: 2)
+- `BITGO_CUSTOM_ROOT_URI` - Custom BitGo API root URI (optional)
+- `BITGO_CUSTOM_BITCOIN_NETWORK` - Custom Bitcoin network (optional)
+- `ENCLAVED_EXPRESS_URL` - Enclaved Express server URL (required)
+- `ENCLAVED_EXPRESS_CERT` - Path to Enclaved Express server certificate (required)
 
-### mTLS Settings
+### TLS/mTLS Configuration
 
-#### Enclaved Mode
+Both modes use the same TLS configuration variables:
 
-- `MASTER_BITGO_EXPRESS_KEYPATH` - Path to server key file (required)
-- `MASTER_BITGO_EXPRESS_CRTPATH` - Path to server certificate file (required)
-- `MASTER_BITGO_EXPRESS_TLS_KEY` - Server key content (alternative to keyPath)
-- `MASTER_BITGO_EXPRESS_TLS_CERT` - Server certificate content (alternative to crtPath)
-- `MTLS_REQUEST_CERT` - Whether to request client certificates (default: true)
-- `MTLS_REJECT_UNAUTHORIZED` - Whether to reject unauthorized connections (default: true)
-- `MTLS_ALLOWED_CLIENT_FINGERPRINTS` - Comma-separated list of allowed client certificate fingerprints (optional)
-- `MASTER_BITGO_EXPRESS_DISABLE_TLS` - Disable TLS completely (default: false)
+#### Certificate Configuration (choose one approach)
+
+**Option 1: Certificate Files**
 
-#### Master Express Mode
+- `TLS_KEY_PATH` - Path to private key file
+- `TLS_CERT_PATH` - Path to certificate file
 
-- `BITGO_KEYPATH` - Path to server key file (required)
-- `BITGO_CRTPATH` - Path to server certificate file (required)
-- `BITGO_TLS_KEY` - Server key content (alternative to keyPath)
-- `BITGO_TLS_CERT` - Server certificate content (alternative to crtPath)
-- `MTLS_REQUEST_CERT` - Whether to request client certificates (default: true)
-- `MTLS_REJECT_UNAUTHORIZED` - Whether to reject unauthorized connections (default: true)
+**Option 2: Environment Variables**
+
+- `TLS_KEY` - Private key content (PEM format)
+- `TLS_CERT` - Certificate content (PEM format)
+
+#### mTLS Settings
+
+- `MTLS_REQUEST_CERT` - Request client certificates (default: true)
+- `ALLOW_SELF_SIGNED` - Allow self-signed certificates (default: false)
 - `MTLS_ALLOWED_CLIENT_FINGERPRINTS` - Comma-separated list of allowed client certificate fingerprints (optional)
 - `MASTER_BITGO_EXPRESS_DISABLE_TLS` - Disable TLS completely (default: false)
 
-### Master Express Settings
+### Logging and Debug
 
-- `BITGO_ENV` - Environment name (default: test)
-- `BITGO_DISABLE_ENV_CHECK` - Disable environment check (default: true)
-- `BITGO_AUTH_VERSION` - Authentication version (default: 2)
-- `ENCLAVED_EXPRESS_URL` - URL of the enclaved express server (required)
-- `ENCLAVED_EXPRESS_SSL_CERT` - Path to the enclaved express server's SSL certificate (required)
-- `BITGO_CUSTOM_ROOT_URI` - Custom root URI for BitGo API
-- `BITGO_CUSTOM_BITCOIN_NETWORK` - Custom Bitcoin network
+- `LOGFILE` - Path to log file (optional)
+- `DEBUG_NAMESPACE` - Debug namespaces to enable (e.g., 'enclaved:\*')
 
-### Other Settings
+## Quick Start
 
-- `LOGFILE` - Path to log file (optional)
-- `DEBUG` - Debug namespaces to enable (e.g., 'enclaved:\*')
+### 1. Generate Test Certificates
+
+First, create self-signed certificates for testing:
 
-## Running Enclaved Express
+```bash
+# Generate private key
+openssl genrsa -out server.key 2048
 
-### Basic Setup (mTLS)
+# Generate certificate
+openssl req -new -x509 -key server.key -out server.crt -days 365 -subj "/CN=localhost"
+```
+
+### 2. Start Enclaved Express
 
 ```bash
 APP_MODE=enclaved \
-ENCLAVED_EXPRESS_PORT=3080 \
-MASTER_BITGO_EXPRESS_BIND=localhost \
-MASTER_BITGO_EXPRESS_KEYPATH=./test-ssl-key.pem \
-MASTER_BITGO_EXPRESS_CRTPATH=./test-ssl-cert.pem \
+KMS_URL=https://your-kms-service \
+TLS_KEY_PATH=./server.key \
+TLS_CERT_PATH=./server.crt \
 MTLS_REQUEST_CERT=true \
-MTLS_REJECT_UNAUTHORIZED=true \
+ALLOW_SELF_SIGNED=true \
 yarn start
 ```
 
-### Connecting from Master Express
+### 3. Start Master Express
 
-To connect to Enclaved Express from the Master Express server:
+In a separate terminal:
 
 ```bash
 APP_MODE=master-express \
-MASTER_EXPRESS_PORT=3081 \
-BITGO_BIND=localhost \
 BITGO_ENV=test \
-BITGO_KEYPATH=./test-ssl-key.pem \
-BITGO_CRTPATH=./test-ssl-cert.pem \
+TLS_KEY_PATH=./server.key \
+TLS_CERT_PATH=./server.crt \
 ENCLAVED_EXPRESS_URL=https://localhost:3080 \
-ENCLAVED_EXPRESS_SSL_CERT=./enclaved-express-cert.pem \
+ENCLAVED_EXPRESS_CERT=./server.crt \
+MTLS_REQUEST_CERT=false \
+ALLOW_SELF_SIGNED=true \
 yarn start
 ```
 
-## Understanding mTLS Configuration
+### 4. Test the Connection
 
-### Server Side (Enclaved Express)
+Test that Master Express can communicate with Enclaved Express:
 
-- Uses both certificate and key files
-- The key file (`test-ssl-key.pem`) is used to prove the server's identity
-- The certificate file (`test-ssl-cert.pem`) is what the server presents to clients
-- Client certificates are required by default
-- Unauthorized connections are rejected by default
+```bash
+curl -k -X POST https://localhost:3081/ping/enclavedExpress
+```
 
-### Client Side (Master Express)
+## Production Configuration
 
-- Must provide a valid client certificate
-- Server certificate must be trusted
-- Client certificate must be in the allowed fingerprints list (if specified)
+### Security Best Practices
 
-## Security Considerations
+1. **Use CA-signed certificates** instead of self-signed
+2. **Set `ALLOW_SELF_SIGNED=false`** in production
+3. **Configure client certificate allowlisting** with `MTLS_ALLOWED_CLIENT_FINGERPRINTS`
+4. **Use separate certificates** for each service
+5. **Regularly rotate certificates**
+6. **Secure private key storage**
 
-- Always use proper CA-signed certificates in production
-- Keep private keys secure
-- Regularly rotate certificates
-- Use client certificate allowlisting
-- Enable strict certificate verification
-- Never disable TLS in production
+### Production Setup Example
+
+#### Enclaved Express (Production)
+
+```bash
+APP_MODE=enclaved \
+KMS_URL=https://production-kms.example.com \
+TLS_KEY_PATH=/secure/path/enclaved.key \
+TLS_CERT_PATH=/secure/path/enclaved.crt \
+MTLS_REQUEST_CERT=true \
+ALLOW_SELF_SIGNED=false \
+MTLS_ALLOWED_CLIENT_FINGERPRINTS=ABC123...,DEF456... \
+yarn start
+```
+
+#### Master Express (Production)
+
+```bash
+APP_MODE=master-express \
+BITGO_ENV=prod \
+TLS_KEY_PATH=/secure/path/master.key \
+TLS_CERT_PATH=/secure/path/master.crt \
+ENCLAVED_EXPRESS_URL=https://enclaved.internal.example.com:3080 \
+ENCLAVED_EXPRESS_CERT=/secure/path/enclaved.crt \
+MTLS_REQUEST_CERT=true \
+ALLOW_SELF_SIGNED=false \
+yarn start
+```
+
+## API Endpoints
+
+### Enclaved Express (Port 3080)
+
+- `POST /ping` - Health check
+- `GET /version` - Version information
+- `POST /:coin/key/independentKey` - Generate independent keychain
+
+### Master Express (Port 3081)
+
+- `POST /ping` - Health check
+- `GET /version` - Version information
+- `POST /ping/enclavedExpress` - Test connection to Enclaved Express
+- `POST /api/:coin/wallet/generate` - Generate wallet (with Enclaved Express integration)
 
 ## Troubleshooting
 
 ### Common Issues
 
-1. **Certificate Errors**
+#### 1. Certificate Loading Errors
 
-   - Ensure paths to certificate files are correct
-   - Check file permissions on certificate files
-   - Verify certificate format is correct
-   - Check that client certificates are valid and trusted
+```bash
+# Check certificate file paths and permissions
+ls -la /path/to/certificates/
+# Verify certificate format
+openssl x509 -in certificate.crt -text -noout
+```
+
+#### 2. mTLS Authentication Failures
+
+- Verify client certificates are provided
+- Check `ALLOW_SELF_SIGNED` setting matches certificate type
+- Confirm client certificate fingerprints are in allowlist
+- Ensure both services use compatible TLS settings
+
+#### 3. Connection Refused
+
+- Verify both services are running on correct ports
+- Check firewall settings
+- Confirm URLs use `https://` prefix
+- Test basic connectivity with curl
 
-2. **Connection Issues**
+#### 4. Environment Variable Issues
 
-   - Verify ports are not in use
-   - Check firewall settings
-   - Ensure URLs are correct (including https:// prefix)
-   - Verify client certificates are properly configured
+```bash
+# Check that required variables are set
+env | grep -E "(APP_MODE|KMS_URL|ENCLAVED_EXPRESS|TLS_)"
+```
+
+### Debug Mode
 
-3. **mTLS Errors**
-   - Verify client certificates are valid
-   - Check certificate configuration
-   - Ensure client certificate is trusted by server
-   - Check that client certificate fingerprint is in allowlist (if specified)
+Enable debug logging for detailed troubleshooting:
+
+```bash
+DEBUG_NAMESPACE=enclaved:*,master:* yarn start
+```
 
 ## License