FilePilot — Corporate Vault Integration Microservice

This microservice simulates or proxies a HashiCorp Vault server, allowing organizations to securely serve Connection Profiles to FilePilot clients over their intranet. It is designed to act as an enterprise config server, managing Key Encryption Keys (KEK), Data Encryption Keys (DEK), and compliance-checked remote connection configurations.

🚨 Production Deployment Checklist

Before deploying this microservice in a production environment, ensure the following security requirements are met:

• Production Database: Do NOT use SQLite for production. Deploy using PostgreSQL or MySQL to enable proper database-level deletion prevention triggers. Restrict database user privileges (revoke DELETE / DROP / TRUNCATE privileges on audit logs).
• Master Encryption Key: Always set the VAULT_MASTER_KEY environment variable as a 256-bit hex/base64 string. Never rely on the auto-generated .vault_key file-based fallback on disk in a containerized environment, as containers are ephemeral.
• Default Credentials: Always run the Setup Wizard (/admin/install.html on first boot) to establish a strong custom admin password. If default admin/vault-admin-pass credentials are ever initialized, change them immediately in the admin settings console.
• Network Security (TLS/HTTPS): Run the microservice behind a reverse proxy (e.g., Nginx, Cloudflare, AWS ALB) configured for HTTPS/TLS to protect credentials and tokens in transit.
• IP Allowlisting: Configure strict IP allowlists for all Vault Groups to restrict client synchronization access to designated enterprise subnets and VPN endpoints.

📦 Getting Started

Method 1: Local Node.js Setup

1. Install Dependencies:

   npm install

2. Start the Microservice:

   npm start

   The server will start listening on port 8200 (or the port specified by the PORT env var).

Method 2: Docker Setup (Recommended)

This microservice comes containerized with a lightweight Alpine-based Node.js Dockerfile.

1. Build the Docker Image Locally

docker build -t filepilot-enterprise-vault:latest .

2. Run the Container

Run the container mapping port 8443 on the host to port 8443 in the container, passing the master key, and persistent volume mount:

docker run -d \
  -p 8443:8443 \
  -e VAULT_MASTER_KEY="your-super-secret-256-bit-hex-key" \
  -v ./data:/app/data \
  --name filepilot-vault \
  abhibagul/filepilot-enterprise-vault:latest

[!NOTE] Mounting ./data or a Docker volume to /app/data ensures that the configuration, SQLite database, and backups persist across container lifecycles.

3. Docker Compose Configuration (docker-compose.yml)

To orchestrate the vault microservice with a Postgres database for enterprise production, configure docker-compose.yml as follows:

version: '3.8'

services:
  vault:
    image: abhibagul/filepilot-enterprise-vault:latest
    build: .
    ports:
      - "8443:8443"
    environment:
      - PORT=8443
      - NODE_ENV=production
      - VAULT_DATA_DIR=/app/data
      - VAULT_MASTER_KEY=4a6f6e617468616e206973206120736563726574206b65792121212121212121
    volumes:
      - vault_data:/app/data
    depends_on:
      - db

  db:
    image: postgres:15-alpine
    environment:
      - POSTGRES_DB=filepilot_vault
      - POSTGRES_USER=vault_admin
      - POSTGRES_PASSWORD=strong_db_password
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  vault_data:
  postgres_data:

Method 3: NPM & NPX Setup (CLI)

You can run the vault microservice directly using npx or install it globally from NPM:

Option A: Run directly with NPX (No installation required)

1. Run the Setup Wizard:

   npx filepilot-enterprise-vault init

2. Start the Server:

   npx filepilot-enterprise-vault start

Option B: Install Globally from NPM

1. Install Globally:

   npm install -g filepilot-enterprise-vault

2. Run the Setup Wizard:

   filepilot-enterprise-vault init

3. Start the Server:

   filepilot-enterprise-vault start

🚀 Pushing to Docker Hub & CI/CD

This repository includes a preconfigured GitHub Actions workflow in .github/workflows/docker-publish.yml to automate builds and pushes.

Prerequisites for GitHub Actions:

1. Go to your GitHub repository -> Settings -> Secrets and variables -> Actions.
2. Add the following Repository Secrets:
   • DOCKERHUB_USERNAME: Your Docker Hub username.
   • DOCKERHUB_TOKEN: A Personal Access Token (PAT) generated from your Docker Hub account with write access.
3. The workflow will automatically trigger, build, tag, and push the image to Docker Hub whenever you push a semantic version tag (e.g. v1.0.0) or publish a GitHub release.

🔒 Bring Your Own KMS (BYOK)

The Corporate Vault microservice supports Bring-Your-Own-KMS (BYOK) configurations. Enterprise administrators can offload Key Encryption Key (KEK) management and remote wrap/unwrap operations to their own customer-managed KMS systems (AWS KMS, Azure Key Vault, or HashiCorp Vault).

Supported KMS Providers & Configuration

1. Local (Default)

Uses the default app-managed VAULT_MASTER_KEY environment variable or local master key file to perform wrapping/unwrapping locally via AES-256-GCM. No external cloud credentials are required.

2. AWS KMS (aws-kms)

Calls AWS KMS remotely to perform Encrypt, Decrypt, and DescribeKey operations on a customer-provided KMS Key ARN.

• Non-secret Configuration (kms_config):
  • region: The target AWS Region (e.g. us-east-1).
  • keyArn: The full AWS KMS Key ARN.
• Credentials (kms_credentials):
  • accessKeyId: AWS Access Key ID.
  • secretAccessKey: AWS Secret Access Key.

3. Azure Key Vault (azure-keyvault)

Performs wrapKey and unwrapKey operations using an Azure Key Vault RSA key (via RSA-OAEP-256).

• Non-secret Configuration (kms_config):
  • vaultUrl: The target Key Vault endpoint URL (e.g. https://myvault.vault.azure.net).
  • keyName: The Key Name.
• Credentials (kms_credentials):
  • tenantId: Azure AD Tenant ID.
  • clientId: Client App Registration ID.
  • clientSecret: Client Secret.

4. HashiCorp Vault (hashicorp-vault)

Uses HashiCorp Vault's Transit Secrets Engine encrypt and decrypt endpoints over HTTP.

• Non-secret Configuration (kms_config):
  • vaultAddr: The address of the Vault server (e.g. https://vault.corp.internal:8200).
  • transitKeyName: Transit engine key name.
• Credentials (kms_credentials):
  • vaultToken: Vault access token.
  • roleId: AppRole Role ID.
  • secretId: AppRole Secret ID.

🔒 Tamper-Evidence & Deletion Prevention Security Boundary

The security audit logging system uses a cryptographic hash-chain to record actions, with database-level deletion prevention triggers.

| Database Engine | Application-level Deletion Block | Database-level Deletion Block | Tamper Detection (Hash-Chain Verification) | OS-level / Filesystem Access Protection | | --- | --- | --- | --- | --- | | MySQL | Yes (No DELETE/TRUNCATE endpoints) | Yes (prevent_delete_transferlog trigger blocks direct DELETE/TRUNCATE) | Yes (verify-full detects any hash/chain mismatch) | Admin should configure user privileges: revoke DELETE / DROP | | PostgreSQL | Yes (No DELETE/TRUNCATE endpoints) | Yes (prevent_delete_transferlog trigger blocks direct DELETE/TRUNCATE) | Yes (verify-full detects any hash/chain mismatch) | Admin should configure user privileges: revoke DELETE / TRUNCATE | | SQLite | Yes (No DELETE/TRUNCATE endpoints) | Yes (prevent_delete_transferlog trigger blocks direct DELETE) | Yes (verify-full detects any hash/chain mismatch) | None (Any user with read/write access to the database file can modify or delete the file directly) |

🔒 SIEM Webhook HMAC Signature Verification

This vault microservice sends JSON payloads of all security audit logs to the configured SIEM Webhook URL. Each webhook payload is cryptographically signed using the siem_webhook_secret using HMAC-SHA256.

The signature is sent in the HTTP header: X-Vault-Signature-256: sha256=<hex signature>

🔗 Integrating with FilePilot Client

1. Boot up this microservice (either locally or containerized).
2. Open the FilePilot client application.
3. Navigate to Settings -> Enterprise Sync.
4. Configure the Vault URL: http://<your-vault-host>:8200/v1/secret/data/filepilot/profiles.
5. Enter the vault access token or credentials configured in the admin panel.
6. Click Sync Profiles Now to retrieve connection profiles over the secure corporate network.