Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .commitlintrc.json
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
"header-max-length": [2, "always", 72],
"references-empty": [1, "never"],
"subject-case": [0],
"scope-enum": [2, "always", ["mbe", "ebe", "docker"]],
"scope-enum": [2, "always", ["aw", "mbe", "sbe", "docker"]],
"scope-empty": [0, "never"]
},
"parserPreset": {
Expand Down
3 changes: 2 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -6,4 +6,5 @@ logs/
tsconfig.tsbuildinfo
out/
.vscode/
*.iml
*.iml
.nyc_output/
43 changes: 29 additions & 14 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,46 +5,52 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
## Commands

### Development

- `yarn start` - Start the application in development mode using nodemon for auto-reloading
- `yarn build` - Build the TypeScript code (creates /dist folder)
- `yarn lint` - Run ESLint to check for code issues
- `yarn lint:fix` - Run ESLint and automatically fix issues when possible

### Testing

- `yarn test` - Run all tests
- `yarn test:watch` - Run tests in watch mode
- `yarn test:coverage` - Run tests with coverage report
- `yarn generate-test-ssl` - Generate self-signed SSL certificates for testing

### Container

- `yarn container:build` - Build the container image using Podman (optionally use --build-arg PORT=3080)

## Architecture Overview

Enclaved BitGo Express is a secure cryptocurrency signing server with two operational modes:
Secured BitGo Express is a secure cryptocurrency signing server with two operational modes:

### 1. Secured Express Mode (`APP_MODE=secured`)

### 1. Enclaved Express Mode (`APP_MODE=enclaved`)
- Lightweight server focused solely on secure signing operations
- Runs on port 3080 by default
- Integrates with KMS for key management
- Handles cryptographic operations securely
- Exposes minimal endpoints focused on key generation and signing

### 2. Master Express Mode (`APP_MODE=master-express`)

- Full BitGo API functionality with integrated signing capabilities
- Runs on port 3081 by default
- Acts as an API gateway and communicates with Enclaved Express for signing operations
- Acts as an API gateway and communicates with Secured Express for signing operations
- Provides a broader set of BitGo wallet operations and transaction handling

### Security Architecture

- Both modes support mutual TLS (mTLS) authentication
- Certificates can be loaded from files or environment variables
- Client certificate validation for secure communications
- Option to validate client certificate fingerprints

### Code Structure
- `src/app.ts` - Main entry point that determines mode and starts the appropriate app
- `src/enclavedApp.ts` - Enclaved Express mode implementation

- `src/securedApp.ts` - Secured Express mode implementation
- `src/masterExpressApp.ts` - Master Express mode implementation
- `src/initConfig.ts` - Configuration loading and validation
- `src/routes/` - Express routes for both modes
Expand All @@ -53,47 +59,56 @@ Enclaved BitGo Express is a secure cryptocurrency signing server with two operat
- `src/shared/` - Shared utilities and types

### Configuration

Configuration is managed through environment variables with defaults defined in `src/initConfig.ts`. The application requires specific environment variables depending on the mode:

#### Common Variables
- `APP_MODE` - Set to "enclaved" or "master-express"

- `APP_MODE` - Set to "secured" or "master-express"
- `TLS_MODE` - Set to "mtls" or "disabled"
- `BIND` - Address to bind to (default: localhost)
- `TIMEOUT` - Request timeout in milliseconds (default: 305000)

#### Enclaved Mode Specific
- `ENCLAVED_EXPRESS_PORT` - Port to listen on (default: 3080)
#### Secured Mode Specific

- `SECURED_EXPRESS_PORT` - Port to listen on (default: 3080)
- `KMS_URL` - Required KMS service URL

#### Master Express Mode Specific

- `MASTER_EXPRESS_PORT` - Port to listen on (default: 3081)
- `BITGO_ENV` - BitGo environment (default: test)
- `ENCLAVED_EXPRESS_URL` - Required URL for the Enclaved Express server
- `ENCLAVED_EXPRESS_CERT` - Required path to Enclaved Express certificate
- `SECURED_EXPRESS_URL` - Required URL for the Secured Express server
- `SECURED_EXPRESS_CERT` - Required path to Secured Express certificate

## API Endpoints

### Enclaved Express (Port 3080)
### Secured Express (Port 3080)

- `POST /ping` - Health check
- `GET /version` - Version information
- `POST /:coin/key/independent` - Generate independent keychain

### Master Express (Port 3081)

#### Health and Status Endpoints

- `POST /ping` - Health check
- `GET /version` - Version information
- `POST /ping/enclavedExpress` - Test connection to Enclaved Express
- `GET /version/enclavedExpress` - Get Enclaved Express version information
- `POST /ping/securedExpress` - Test connection to Secured Express
- `GET /version/securedExpress` - Get Secured Express version information

#### Wallet Management

- `POST /api/:coin/wallet/generate` - Generate wallet (supports onchain and TSS multisig types)

#### Transaction Operations

- `POST /api/:coin/wallet/:walletId/sendMany` - Send transaction with multiple recipients
- `POST /api/:coin/wallet/:walletId/accelerate` - Accelerate pending transactions (CPFP/RBF)
- `POST /api/:coin/wallet/:walletId/consolidate` - Consolidate wallet addresses
- `POST /api/:coin/wallet/:walletId/consolidateunspents` - Consolidate unspent transaction outputs

#### Recovery
- `POST /api/:coin/wallet/recovery` - Recover wallet funds

- `POST /api/:coin/wallet/recovery` - Recover wallet funds
2 changes: 1 addition & 1 deletion Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -91,4 +91,4 @@ USER bitgo
EXPOSE ${PORT}

# Start the application using the binary
CMD ["./bin/enclaved-bitgo-express"]
CMD ["./bin/secured-bitgo-express"]
79 changes: 40 additions & 39 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,28 +1,28 @@
# Enclaved BitGo Express
# Secured BitGo Express

A secure, mTLS-enabled cryptocurrency signing server with two operational modes: Enclaved Express (dedicated signer) and Master Express (API gateway with integrated signing capabilities).
A secure, mTLS-enabled cryptocurrency signing server with two operational modes: Secured Express (dedicated signer) and Master Express (API gateway with integrated signing capabilities).

## Overview

This application provides secure cryptocurrency operations with mutual TLS (mTLS) authentication:

- **Enclaved Mode**: Lightweight signing server for secure key operations
- **Secured 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

## Architecture

- **Enclaved Express** (Port 3080): Focused signing operations with KMS integration
- **Master Express** (Port 3081): Full BitGo API functionality with secure communication to Enclaved Express
- **Secured Express** (Port 3080): Focused signing operations with KMS integration
- **Master Express** (Port 3081): Full BitGo API functionality with secure communication to Secured Express

## Configuration

Configuration is managed through environment variables:

### Required Settings

- `APP_MODE` - Application mode (required: "enclaved" or "master-express")
- `APP_MODE` - Application mode (required: "secured" or "master-express")

### Network Settings

Expand All @@ -31,9 +31,9 @@ Configuration is managed through environment variables:
- `KEEP_ALIVE_TIMEOUT` - Keep-alive timeout (optional)
- `HEADERS_TIMEOUT` - Headers timeout (optional)

#### Enclaved Mode Specific
#### Secured Mode Specific

- `ENCLAVED_EXPRESS_PORT` - Port to listen on (default: 3080)
- `SECURED_EXPRESS_PORT` - Port to listen on (default: 3080)
- `KMS_URL` - KMS service URL (required)

#### Master Express Mode Specific
Expand All @@ -44,8 +44,8 @@ Configuration is managed through environment variables:
- `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)
- `SECURED_EXPRESS_URL` - Secured Express server URL (required)
- `SECURED_EXPRESS_CERT` - Path to Secured Express server certificate (required)

### TLS/mTLS Configuration

Expand Down Expand Up @@ -76,7 +76,7 @@ Both modes use the same TLS configuration variables:
### Logging and Debug

- `LOGFILE` - Path to log file (optional)
- `DEBUG_NAMESPACE` - Debug namespaces to enable (e.g., 'enclaved:\*')
- `DEBUG_NAMESPACE` - Debug namespaces to enable (e.g., 'secured:\*')

## Quick Start

Expand All @@ -92,10 +92,10 @@ openssl genrsa -out server.key 2048
openssl req -new -x509 -key server.key -out server.crt -days 365 -subj "/CN=localhost"
```

### 2. Start Enclaved Express
### 2. Start Secured Express

```bash
APP_MODE=enclaved \
APP_MODE=secured \
KMS_URL=https://your-kms-service \
TLS_KEY_PATH=./server.key \
TLS_CERT_PATH=./server.crt \
Expand All @@ -113,19 +113,19 @@ APP_MODE=master-express \
BITGO_ENV=test \
TLS_KEY_PATH=./server.key \
TLS_CERT_PATH=./server.crt \
ENCLAVED_EXPRESS_URL=https://localhost:3080 \
ENCLAVED_EXPRESS_CERT=./server.crt \
SECURED_EXPRESS_URL=https://localhost:3080 \
SECURED_EXPRESS_CERT=./server.crt \
MTLS_REQUEST_CERT=false \
ALLOW_SELF_SIGNED=true \
yarn start
```

### 4. Test the Connection

Test that Master Express can communicate with Enclaved Express:
Test that Master Express can communicate with Secured Express:

```bash
curl -k -X POST https://localhost:3081/ping/enclavedExpress
curl -k -X POST https://localhost:3081/ping/securedExpress
```

## Production Configuration
Expand All @@ -141,13 +141,13 @@ curl -k -X POST https://localhost:3081/ping/enclavedExpress

### Production Setup Example

#### Enclaved Express (Production)
#### Secured Express (Production)

```bash
APP_MODE=enclaved \
APP_MODE=secured \
KMS_URL=https://production-kms.example.com \
TLS_KEY_PATH=/secure/path/enclaved.key \
TLS_CERT_PATH=/secure/path/enclaved.crt \
TLS_KEY_PATH=/secure/path/secured.key \
TLS_CERT_PATH=/secure/path/secured.crt \
MTLS_REQUEST_CERT=true \
ALLOW_SELF_SIGNED=false \
MTLS_ALLOWED_CLIENT_FINGERPRINTS=ABC123...,DEF456... \
Expand All @@ -161,8 +161,8 @@ 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 \
SECURED_EXPRESS_URL=https://secured.internal.example.com:3080 \
SECURED_EXPRESS_CERT=/secure/path/secured.crt \
MTLS_REQUEST_CERT=true \
ALLOW_SELF_SIGNED=false \
yarn start
Expand All @@ -176,22 +176,22 @@ First, build the container image:
# For Master Express (default port 3081)
yarn container:build

# For Enclaved Express (port 3080)
# For Secured Express (port 3080)
yarn container:build --build-arg PORT=3080
```

For local development, you'll need to run both the Enclaved Express and Master Express containers:
For local development, you'll need to run both the Secured Express and Master Express containers:

```bash
# Start Enclaved Express container
# Start Secured Express container
podman run -d \
-p 3080:3080 \
-v $(pwd)/certs:/app/certs:Z \
-e APP_MODE=enclaved \
-e APP_MODE=secured \
-e BIND=0.0.0.0 \
-e TLS_MODE=mtls \
-e TLS_KEY_PATH=/app/certs/enclaved-express-key.pem \
-e TLS_CERT_PATH=/app/certs/enclaved-express-cert.pem \
-e TLS_KEY_PATH=/app/certs/secured-express-key.pem \
-e TLS_CERT_PATH=/app/certs/secured-express-cert.pem \
-e KMS_URL=host.containers.internal:3000 \
-e NODE_ENV=development \
-e ALLOW_SELF_SIGNED=true \
Expand All @@ -212,33 +212,34 @@ podman run -d \
-e TLS_MODE=mtls \
-e TLS_KEY_PATH=/app/certs/test-ssl-key.pem \
-e TLS_CERT_PATH=/app/certs/test-ssl-cert.pem \
-e ENCLAVED_EXPRESS_URL=https://host.containers.internal:3080 \
-e ENCLAVED_EXPRESS_CERT=/app/certs/enclaved-express-cert.pem \
-e SECURED_EXPRESS_URL=https://host.containers.internal:3080 \
-e SECURED_EXPRESS_CERT=/app/certs/secured-express-cert.pem \
-e ALLOW_SELF_SIGNED=true \
bitgo-onprem-express

# View logs
podman logs -f <container_id>

# Test the endpoints (note: using https and mTLS)
# For Enclaved Express
curl -k --cert certs/test-ssl-cert.pem --key certs/enclaved-express-key.pem -X POST https://localhost:3080/ping
# For Secured Express
curl -k --cert certs/test-ssl-cert.pem --key certs/secured-express-key.pem -X POST https://localhost:3080/ping

# For Master Express
curl -k --cert certs/test-ssl-cert.pem --key certs/test-ssl-key.pem -X POST https://localhost:3081/ping

# Test the connection
curl -k -X POST https://localhost:3081/ping/enclavedExpress
curl -k -X POST https://localhost:3081/ping/securedExpress
```

Notes:

- `host.containers.internal` is a special DNS name that resolves to the host machine from inside containers
- The `:Z` option in volume mounts is specific to SELinux-enabled systems and ensures proper volume labeling
- The logs directory will be created with appropriate permissions if it doesn't exist

## API Endpoints

### Enclaved Express (Port 3080)
### Secured Express (Port 3080)

- `POST /ping` - Health check
- `GET /version` - Version information
Expand All @@ -248,8 +249,8 @@ Notes:

- `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)
- `POST /ping/securedExpress` - Test connection to Secured Express
- `POST /api/:coin/wallet/generate` - Generate wallet (with Secured Express integration)

## Troubleshooting

Expand Down Expand Up @@ -282,15 +283,15 @@ openssl x509 -in certificate.crt -text -noout

```bash
# Check that required variables are set
env | grep -E "(APP_MODE|KMS_URL|ENCLAVED_EXPRESS|TLS_)"
env | grep -E "(APP_MODE|KMS_URL|SECURED_EXPRESS|TLS_)"
```

### Debug Mode

Enable debug logging for detailed troubleshooting:

```bash
DEBUG_NAMESPACE=enclaved:*,master:* yarn start
DEBUG_NAMESPACE=secured:*,master:* yarn start
```

## License
Expand Down
File renamed without changes.
Loading