Skip to content

docs: copy edited readme dx-2276 #149

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pranavjain97 merged 1 commit into from
Nov 7, 2025
Merged

docs: copy edited readme dx-2276 #149

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
135 changes: 66 additions & 69 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,17 @@
# Advanced Wallets

A secure, mTLS-enabled cryptocurrency signing server with two operational modes: Advanced Wallet Manager (dedicated signer) and Master Express (API gateway with integrated signing capabilities).
Advanced wallets are a type of self-custody cryptocurrency wallet that securely enable mutual TLS (mTLS) signing servers with two operational modes:

- **Advanced Wallet Manager Mode** - A lightweight, dedicated keygen/signing server that you can use for secure key operations. This mode includes support for wallet recoveries.
- **Master Express Mode** - An Express application that's the orchestrator between the Advanced Wallet Manager and [BitGo APIs](https://developers.bitgo.com/reference/overview#/). This mode serves as an API gateway with integrated signing capabilities.

Security includes:

- **mTLS Security** - Client certificate validation for secure communications.
- **Flexible Configuration** - Environment-based setup with file or variable-based certificates.

## Table of Contents

- [Overview](#overview)
- [Architecture](#architecture)
- [Installation](#installation)
- [Prerequisites](#prerequisites)
Expand All @@ -18,55 +25,45 @@ A secure, mTLS-enabled cryptocurrency signing server with two operational modes:
- [Production Setup](#production-setup)
- [License](#license)

## Overview

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

- **Advanced Wallet Manager Mode**: Lightweight keygen/signing server for secure key operations. Includes support for recovery.
- **Master Express Mode**: An express app that acts as the orchestrator between the Advanced Wallet Manager and BitGo APIs.
- **mTLS Security**: Client certificate validation for secure communications
- **Flexible Configuration**: Environment-based setup with file or variable-based certificates

## Architecture

- **Advanced Wallet Manager** (Port 3080): Isolated signing server with no internet access, only connects to KMS API for key operations.
- **Master Express** (Port 3081): API gateway providing end-to-end wallet creation and transaction support, integrating BitGo APIs with secure communication to Advanced Wallet Manager
- **Advanced Wallet Manager** (Port 3080) - An isolated signing server with no internet access that only connects to the key management service (KMS) API for key operations.
- **Master Express** (Port 3081) - An API gateway providing end-to-end wallet creation and transaction support, integrating [BitGo APIs](https://developers.bitgo.com/reference/overview#/) with secure communication to Advanced Wallet Manager.

## Installation

### Prerequisites

- **Node.js** 22.1.0 or higher
- **npm** or **yarn** package manager
- **OpenSSL** for certificate generation
- **Docker** and **Docker Compose** (for containerized deployment)
- **Podman** (alternative to Docker for containerized deployment)
- **KMS API Implementation** - Advanced Wallet Manager requires a KMS (Key Management Service) API for secure key operations. See implementation guides:
- **Node.js** 22.1.0 or higher.
- **npm** or **yarn** package manager.
- **OpenSSL** for certificate generation.
- **Docker** and **Docker Compose** for containerized deployment (or you can use **Podman** as alternative to Docker).
- **KMS API Implementation** - Advanced Wallet Manager requires a KMS API for secure key operations. For example:
- [AWS HSM Implementation](./demo-kms-script/aws-interface.md)
- [Dinamo HSM Implementation](./demo-kms-script/dinamo-interface.md)

### Setup

1. **Clone the repository:**
#### 1. Clone the Repository

```bash
git clone <repository-url>
cd advanced-wallets
```

2. **Install dependencies:**
#### 2. Install Dependencies

```bash
npm install
```

3. **Build the project:**
#### 3. Build the Project

```bash
npm run build
```

4. **Generate test certificates (optional):**
#### 4. Generate Test Certificates (Optional)

```bash
# Generate private key and certificate for testing
Expand Down Expand Up @@ -117,7 +114,7 @@ npm start

#### 2. Start Master BitGo Express (Port 3081)

In a new terminal:
Run the following in a new terminal:

```bash
TLS_MODE=disabled \
Expand All @@ -128,7 +125,7 @@ ADVANCED_WALLET_MANAGER_URL=http://localhost:3080 \
npm start
```

#### 3. Test the Connection
#### 3. Test Connection

```bash
# Test Advanced Wallet Manager
Expand All @@ -141,7 +138,7 @@ curl -X POST http://localhost:3081/ping
curl -X POST http://localhost:3081/ping/advancedWalletManager
```

**Note:** `TLS_MODE=disabled` should only be used for local development and testing. Always use mTLS in production environments. See the [Production Setup](#production-setup) section for production mTLS configuration.
> **Note:** You should only use `TLS_MODE=disabled` for local development and testing. Always use mTLS in production environments. For information about configuring mTLS in production, see the [Production Setup](#production-setup) section.

## Configuration

Expand All @@ -162,7 +159,7 @@ curl -X POST http://localhost:3081/ping/advancedWalletManager
| `ADVANCED_WALLET_MANAGER_PORT` | Port to listen on | `3080` | ❌ |
| `KMS_URL` | KMS service URL | - | ✅ |

**Note:** See [Prerequisites](#prerequisites) for KMS API implementation requirements.
> **Note:** For KMS API implementation requirements, see the [Prerequisites](#prerequisites).

### Master Express Settings

Expand Down Expand Up @@ -236,7 +233,7 @@ curl -X POST http://localhost:3081/ping/advancedWalletManager
| `KMS_SERVER_CA_CERT` | KMS server CA certificate (alternative) | PEM string |
| `KMS_SERVER_CERT_ALLOW_SELF_SIGNED` | Allow self-signed KMS server certificates | Boolean (default: `false`) |

**Note:** When `TLS_MODE=mtls`, outbound client certificates are required and cannot reuse server certificates for security reasons. In `TLS_MODE=disabled` mode, these certificates are not required.
> **Note:** For security reasons, when `TLS_MODE=mtls`, outbound client certificates are required and cannot reuse server certificates. When `TLS_MODE=disabled`, these certificates aren't required.

## Container Deployment with Podman

Expand All @@ -256,7 +253,7 @@ npm run container:build:advanced-wallet-manager -- --build-arg PORT=3082

### Run Containers

For local development, you'll need to run both the Advanced Wallet Manager and Master Express containers:
For local development, you must run both the Advanced Wallet Manager and the Master Express containers:

```bash
# Start Advanced Wallet Manager container
Expand Down Expand Up @@ -307,11 +304,11 @@ curl -k --cert certs/test-ssl-cert.pem --key certs/test-ssl-key.pem -X POST http
curl -k -X POST https://localhost:3081/ping/advancedWalletManager
```

**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
>**Note:**
>
> - `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 is created with appropriate permissions if it doesn't already exist.

## Docker Compose Deployment

Expand All @@ -321,9 +318,9 @@ The application includes a Docker Compose configuration that runs both Advanced

The Docker Compose setup creates two isolated services:

- **Advanced Wallet Manager (AWM)**: Runs in an isolated internal network with no external access for maximum security
- **Master BitGo Express (MBE)**: Connected to both internal network (for AWM communication) and public network (for external API access)
- **Network Isolation**: AWM is completely isolated from external networks and only accessible through MBE
- **Advanced Wallet Manager (AWM)**: Runs in an isolated internal network with no external access for maximum security.
- **Master BitGo Express (MBE)**: Connects to both internal network (for AWM communication) and public network (for external API access).
- **Network Isolation**: AWM is completely isolated from external networks and only accessible through MBE.

### Network Configuration

Expand All @@ -347,7 +344,7 @@ The setup creates two distinct networks:

### Quick Start

1. **Start the services:**
#### 1. Start Services

```bash
# Navigate to project directory
Expand All @@ -357,7 +354,7 @@ cd advanced-wallet
docker-compose up -d
```

2. **Stop the services:**
#### 2. Stop Services

```bash
# Stop and remove containers
Expand All @@ -368,38 +365,38 @@ docker-compose down

### Advanced Wallet Manager (Port 3080)

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

### Master Express (Port 3081)

- `POST /ping` - Health check
- `GET /version` - Version information
- `POST /ping/advancedWalletManager` - Test connection to Advanced Wallet Manager
- `POST /api/:coin/wallet/generate` - Generate wallet (with Advanced Wallet Manager integration)
- `POST /ping` - Health check.
- `GET /version` - Version information.
- `POST /ping/advancedWalletManager` - Test connection to Advanced Wallet Manager.
- `POST /api/:coin/wallet/generate` - Generate wallet (with Advanced Wallet Manager integration).

### API Documentation

**Master Express OpenAPI Specification**

The OpenAPI specification for Master Express is available at [`masterBitgoExpress.json`](./masterBitgoExpress.json).
You can vew the OpenAPI specification for Master Express at [`masterBitgoExpress.json`](./masterBitgoExpress.json).

To regenerate the API documentation:

```bash
npm run generate:openapi:masterExpress
```

This will generate/update the `masterBitgoExpress.json` file with the latest API specification. You can view this file with any OpenAPI viewer such as:
This generates or updates the `masterBitgoExpress.json` file with the latest API specification. You can view this file with any OpenAPI viewer such as:

- [Swagger Editor](https://editor.swagger.io/)
- [Redoc](https://redocly.github.io/redoc/)
- VS Code OpenAPI extensions

## Production Setup

### Quick Start (With mTLS)
### Quick Start (with mTLS)

For production deployments with proper mTLS security:

Expand Down Expand Up @@ -427,7 +424,7 @@ npm start

#### 2. Start Master Express (Port 3081)

In a new terminal:
Run the following in a new terminal:

```bash
export APP_MODE=master-express
Expand All @@ -449,9 +446,9 @@ export MTLS_ALLOWED_CLIENT_FINGERPRINTS=sha256:7g8h9i...,sha256:0j1k2l...
npm start
```

#### 3. Test the Connection
#### 3. Test Connection

For testing, you can use the server's IP address or `localhost` if running locally. In production deployments, configure your DNS or load balancer to point to the appropriate servers.
For testing, you can use the IP address of the server or `localhost` if you're running it locally. In production deployments, configure your DNS or load balancer to point to the appropriate servers.

```bash
# Test Advanced Wallet Manager (replace localhost with your server IP/hostname)
Expand All @@ -474,20 +471,20 @@ curl --cert /path/to/client-cert.crt --key /path/to/client-key.key \

For local testing, you can generate and use demo certificates with the self-signed configuration flags:

- Generate demo certificates: `npm run generate-test-ssl` (creates `demo.key` and `demo.crt`)
- Set `CLIENT_CERT_ALLOW_SELF_SIGNED=true`, `KMS_SERVER_CERT_ALLOW_SELF_SIGNED=true`, and `AWM_SERVER_CERT_ALLOW_SELF_SIGNED=true`
- Use the demo certificates for all certificate paths (server and client)
- **Important:** Demo certificates and self-signed configurations should never be used in production
- Generate demo certificates: `npm run generate-test-ssl` (creates `demo.key` and `demo.crt`).
- Set `CLIENT_CERT_ALLOW_SELF_SIGNED=true`, `KMS_SERVER_CERT_ALLOW_SELF_SIGNED=true`, and `AWM_SERVER_CERT_ALLOW_SELF_SIGNED=true`.
- Use the demo certificates for all certificate paths (server and client).
- **Important:** Demo certificates and self-signed configurations should never be used in production.

### Best Practices

1. **Use CA-signed certificates** instead of self-signed
2. **Set `CLIENT_CERT_ALLOW_SELF_SIGNED=false`** and server-specific allow self-signed flags to `false` in production
3. **Configure client certificate allowlisting** with `MTLS_ALLOWED_CLIENT_FINGERPRINTS`
4. **Use separate certificates** for each service (server, AWM client, KMS client)
5. **Regularly rotate certificates**
6. **Secure private key storage** and use appropriate file permissions
7. **Always use `TLS_MODE=mtls`** in production environments
1. **Use CA-signed certificates** instead of self-signed.
2. **Set `CLIENT_CERT_ALLOW_SELF_SIGNED=false`** and server-specific allow self-signed flags to `false` in production.
3. **Configure client certificate allowlisting** with `MTLS_ALLOWED_CLIENT_FINGERPRINTS`.
4. **Use separate certificates** for each service (server, AWM client, KMS client).
5. **Regularly rotate certificates**.
6. **Secure private key storage** and use appropriate file permissions.
7. **Always use `TLS_MODE=mtls`** in production environments.

### Certificate Management

Expand All @@ -499,20 +496,20 @@ To obtain certificate fingerprints for `MTLS_ALLOWED_CLIENT_FINGERPRINTS`:
openssl x509 -in /path/to/client-cert.crt -noout -fingerprint -sha256 | cut -d'=' -f2
```

The output will be in the format: `sha256:AB:CD:EF:...` which you can use in the configuration.
The output format is: `sha256:AB:CD:EF:...` which you can use in the configuration.

#### Certificate Requirements for Production

- All certificates should be CA-signed certificates issued by your organization's PKI
- Each service must use separate certificates (server cert, AWM client cert, KMS client cert)
- Client certificates for outbound connections must be different from server certificates
- All certificates should be CA-signed certificates issued by your organization's PKI.
- Each service must use separate certificates (server cert, AWM client cert, KMS client cert).
- Client certificates for outbound connections must be different from server certificates.
- Store private keys in secure locations with restricted file permissions:
```bash
chmod 400 /secure/certs/*.key
chown root:root /secure/certs/*.key
```
- Use `BIND=0.0.0.0` only if the service needs to be accessible from other machines
- Regularly rotate certificates according to your security policy
- Use `BIND=0.0.0.0` only if the service needs to be accessible from other machines.
- Regularly rotate certificates according to your security policy.

## License

Expand Down