@bopen-io/messagebox-server 1.1.5 → 1.2.1

package/.dockerignore

@@ -0,0 +1,11 @@
+.git
+node_modules
+out
+dist
+build
+coverage
+logs
+*.log
+.vscode
+.DS_Store
+.env

package/.env.example

@@ -0,0 +1,11 @@
+NODE_ENV=development
+HOSTING_DOMAIN="http://localhost:8080"
+ROUTING_PREFIX=""
+SERVER_PRIVATE_KEY='0209cb3b54d5099acaa8ced2deebf2539fe8771c014a09057372c6bc671bfb9067' # Example key, use your own key in production!!
+MIGRATE_KEY="my-grate-key"
+
+# Firebase push notifications (optional — defaults to disabled)
+ENABLE_FIREBASE=false
+# FIREBASE_PROJECT_ID=your-project-id
+# FIREBASE_SERVICE_ACCOUNT_JSON={"type":"service_account",...}
+# FIREBASE_SERVICE_ACCOUNT_PATH=/path/to/serviceAccount.json

package/.eslintignore

@@ -0,0 +1,2 @@
+node_modules
+dist

package/.gcloudignore

@@ -0,0 +1,17 @@
+# This file specifies files that are *not* uploaded to Google Cloud Platform
+# using gcloud. It follows the same syntax as .gitignore, with the addition of
+# "#!include" directives (which insert the entries of the given .gitignore-style
+# file at that point).
+#
+# For more information, run:
+#   $ gcloud topic gcloudignore
+#
+.gcloudignore
+# If you would like to upload your .git directory, .gitignore file or files
+# from your .gitignore file, remove the corresponding line
+# below:
+.git
+.gitignore
+
+# Node.js dependencies:
+node_modules/

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/.github/workflows/build-and-push.yml

@@ -0,0 +1,51 @@
+name: Build and Push to AWS Marketplace ECR
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version tag (e.g., 1.0.0)'
+        required: true
+        default: '1.0.0'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
+      
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@e3dd6a429d7300a6a4c196c26e071d42e0343502
+        with:
+          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws-region: us-east-1
+      
+      - name: Login to Amazon ECR
+        run: |
+          aws ecr get-login-password --region us-east-1 | \
+          docker login --username AWS --password-stdin \
+          709825985650.dkr.ecr.us-east-1.amazonaws.com
+      
+      - name: Build Docker image
+        run: |
+          docker build --platform linux/amd64 -t message-box-server:${{ github.event.inputs.version }} .
+      
+      - name: Tag image
+        run: |
+          docker tag message-box-server:${{ github.event.inputs.version }} \
+          709825985650.dkr.ecr.us-east-1.amazonaws.com/bsv-blockchain/message-box-server:${{ github.event.inputs.version }}
+      
+      - name: Push to ECR
+        run: |
+          docker push 709825985650.dkr.ecr.us-east-1.amazonaws.com/bsv-blockchain/message-box-server:${{ github.event.inputs.version }}
+      
+      - name: Verify push
+        run: |
+          aws ecr describe-images \
+            --registry-id 709825985650 \
+            --repository-name bsv-blockchain/message-box-server \
+            --region us-east-1 \
+            --image-ids imageTag=${{ github.event.inputs.version }}

package/.github/workflows/deploy.yaml.example

@@ -0,0 +1,64 @@
+name: Deployment
+on:
+  push:
+    branches:
+      - master
+      - production
+
+env:
+  CURRENT_BRANCH: ${{ github.ref_name == 'production' && 'production' || 'master' }}
+  GCR_HOST: us.gcr.io
+  GOOGLE_PROJECT_ID: example-project-id
+  GCR_IMAGE_NAME: messagebox-server
+
+jobs:
+  build:
+    name: Deploy
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v2
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 22
+
+      - name: Install Dependencies
+        run: npm ci
+
+      - name: Push Docker Image to GCR
+        uses: RafikFarhad/push-to-gcr-github-action@v4.1
+        with:
+          gcloud_service_key: ${{ secrets.DOCKER_REGISTRY_PUSH_KEY }}
+          registry: ${{ env.GCR_HOST }}
+          project_id: ${{ env.GOOGLE_PROJECT_ID }}
+          image_name: ${{ env.GCR_IMAGE_NAME }}
+          image_tag: latest,${{ env.CURRENT_BRANCH }}-${{ github.sha }}
+
+      - name: Create Service Description File
+        run: ./scripts/mkenv.sh service.${{ env.CURRENT_BRANCH }}.yaml
+        env:
+          IMAGE: "${{ env.GCR_HOST }}/${{ env.GOOGLE_PROJECT_ID }}/${{ env.GCR_IMAGE_NAME }}:${{ env.CURRENT_BRANCH }}-${{ github.sha }}"
+          SERVICE: ${{ env.CURRENT_BRANCH == 'production' && 'prod-messagebox-server' || 'staging-messagebox-server' }}
+          BSV_NETWORK: ${{ env.CURRENT_BRANCH == 'production' && 'mainnet' || 'testnet' }}
+          NODE_ENV: ${{ env.CURRENT_BRANCH =='production' && 'production' || 'staging' }}
+          WALLET_STORAGE_URL: ${{ env.CURRENT_BRANCH == 'production' && secrets.PROD_WALLET_STORAGE_URL || secrets.STAGING_WALLET_STORAGE_URL }}
+          SERVER_PRIVATE_KEY: ${{ env.CURRENT_BRANCH == 'production' && secrets.PROD_SERVER_PRIVATE_KEY || secrets.STAGING_SERVER_PRIVATE_KEY }}
+          KNEX_DB_CONNECTION: ${{ env.CURRENT_BRANCH == 'production' && secrets.PROD_KNEX_DB_CONNECTION || secrets.STAGING_KNEX_DB_CONNECTION }}
+          LOGGING_ENABLED: ${{ env.CURRENT_BRANCH == 'production' && secrets.PROD_LOGGING_ENABLED || secrets.STAGING_LOGGING_ENABLED }}
+      - name: Authenticate to Google Cloud
+        uses: google-github-actions/auth@v1
+        with:
+          credentials_json: ${{ secrets.gcp_deploy_creds }}
+
+      - name: Deploy to Cloud Run
+        uses: google-github-actions/deploy-cloudrun@v1
+        with:
+          metadata: "service.${{ env.CURRENT_BRANCH }}.yaml"
+          region: us-west1
+
+      - name: Set Min Instances and Enable CPU Boost
+        run: |
+          gcloud run services update ${{ env.CURRENT_BRANCH == 'production' && 'prod-storage' || 'staging-storage' }} \
+            --min-instances=1 --cpu-boost --region=us-west1

package/.github/workflows/image.yaml

@@ -0,0 +1,66 @@
+name: Build and push OCI image to Docker Hub
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  check-current-branch:
+    runs-on: ubuntu-latest
+    outputs:
+      branch: ${{ steps.check_step.outputs.branch }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # v3
+        with:
+          fetch-depth: 0
+
+      - name: Get current branch
+        id: check_step
+        # 1. Get the list of branches ref where this tag exists
+        # 2. Remove 'origin/' from that result
+        # 3. Put that string in output
+        run: |
+          raw=$(git branch -r --contains ${{ github.ref }})
+          branch="$(echo ${raw//origin\//} | tr -d '\n')"
+          echo "{name}=branch" >> $GITHUB_OUTPUT
+          echo "Branches where this tag exists : $branch."
+
+  image:
+    runs-on: ubuntu-latest
+    needs: check-current-branch
+    if: contains(${{ needs.check.outputs.branch }}, 'main')`
+    steps:
+      - name: Check out the repo
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Get build args
+        id: build_args
+        run: |
+          echo "APP_COMMIT=$(git rev-parse --short HEAD)" >> "$GITHUB_OUTPUT"
+          echo "APP_VERSION=$(git describe --tags --always --abbrev=0 --match='v[0-9]*.[0-9]*.[0-9]*' 2> /dev/null | sed 's/^.//')" >> "$GITHUB_OUTPUT"
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3
+        with:
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_PASSWORD }}
+
+      - name: Extract metadata (tags, labels)
+        id: meta
+        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5
+        with:
+          images: bsvb/message-box-server
+
+      - name: Build and push image
+        uses: docker/build-push-action@ca052bb54ab0790a636c9b5f226502c73d547a25 # v5
+        with:
+          context: .
+          file: ./Dockerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          build-args: |
+            APP_COMMIT=${{ steps.build_args.outputs.APP_COMMIT }}
+            APP_VERSION=${{ steps.build_args.outputs.APP_VERSION }}

package/.vscode/launch.json

@@ -0,0 +1,67 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+    {
+        "name": "default",
+        "type": "node",
+        "request": "launch",
+        "skipFiles": [
+            "<node_internals>/**"
+        ],
+        "program": "${workspaceFolder}/lib/index.js",
+        "outFiles": [
+            "${workspaceFolder}/**/*.js"
+        ]
+    },
+    {
+        "name": "Launch",
+        "type": "node",
+        "program": "${workspaceFolder}/src/index.ts",
+        "request": "launch",
+        "stopOnEntry": false,
+        "args": [],
+        "cwd": "${workspaceFolder}/.",
+        "runtimeExecutable": null,
+        "runtimeArgs": [
+            "--nolazy"
+        ],
+        "env": {
+            "NODE_ENV": "development"
+        },
+        "console": "integratedTerminal",
+        "sourceMaps": true,
+        "outFiles": [
+            "${workspaceFolder}/**/*.js"
+        ]
+    },
+    {
+        "type": "node",
+        "request": "launch",
+        "name": "Jest Current Tests",
+        "program": "${workspaceFolder}/node_modules/.bin/jest",
+        "args": [
+            "--runTestsByPath",
+            "${relativeFile}"
+        ],
+        "console": "integratedTerminal",
+        "internalConsoleOptions": "neverOpen",
+        "sourceMaps": true,
+        "windows": {
+            "program": "${workspaceFolder}/node_modules/jest/bin/jest"
+        }
+    },
+    {
+        "type": "node",
+        "request": "attach",
+        "name": "Attach to Node Process",
+        "port": 9229,
+        "restart": true,
+        "skipFiles": ["<node_internals>/**"],
+        "sourceMaps": true
+    }
+]
+
+}

package/AGENTS.md

@@ -0,0 +1,92 @@
+# CLAUDE.md — Message Box Server
+
+## Purpose
+A secure peer-to-peer message routing server for the Bitcoin SV ecosystem. Provides identity-based message delivery, real-time WebSocket communication, and full mutual authentication using BRC-103 signatures. Messages are encrypted and stored until acknowledged, supporting both HTTP and WebSocket transports.
+
+## Service surface
+- **POST /sendMessage** – Send encrypted message to a recipient's message box
+- **POST /listMessages** – List all unacknowledged messages in a box (authenticated)
+- **POST /acknowledgeMessage** – Mark messages as read/delete them (authenticated)
+- **WebSocket** – Real-time authenticated messaging over `@bsv/authsocket` using rooms in format `{identityKey}-{messageBox}`
+  - Events: `authenticated`, `joinRoom`, `sendMessage`, `leaveRoom`
+- **Background jobs** – Firebase push notifications (optional, enabled via ENABLE_FIREBASE)
+
+## Real deployment
+- **Dockerfile** – Multi-stage build: node:20-alpine builder → production runtime with nginx reverse proxy on port 8080 (app runs on 3000, nginx on 8080)
+- **docker-compose.yml** – Backend (Node), MySQL 8.0, PHPMyAdmin. MySQL connection pool with health checks
+- **knexfile.ts** – MySQL 8.0 via mysql2, default connection string configurable via KNEX_DB_CONNECTION
+- **nginx.conf** – HTTP/2 reverse proxy listening on 8080, proxying to localhost:3000, gzip enabled, 1GB max body size
+- **Migrations** – Knex migrations stored in `src/migrations/`:
+  - `2022-12-28-001-initial-migration.ts` – Core messages table with identity keys
+  - `2023-01-17-messages-update.ts` – Payload storage updates
+  - `2024-03-05-001-messageID-upgrade.ts` – MessageID uniqueness constraints
+  - `2025-01-31-001-notification-permissions.ts` – Firebase notification permissions
+  - `2025-01-31-002-device-registrations.ts` – Device registration tracking
+
+## Configuration
+Environment variables (from `.env.example`):
+- **NODE_ENV** – `development`, `staging`, or `production`
+- **PORT** – Express port (default 3000 prod, 8080 dev)
+- **HTTP_PORT** – Alternative port alias
+- **HOSTING_DOMAIN** – Public domain for overlay advertisement (e.g., `http://localhost:8080`)
+- **SERVER_PRIVATE_KEY** – 256-bit hex private key for server identity and auth signing (required)
+- **ROUTING_PREFIX** – Optional path prefix for all routes (e.g., `/api`)
+- **ENABLE_WEBSOCKETS** – Set to `'true'` to enable real-time messaging (default true)
+- **LOGGING_ENABLED** – Set to `'true'` for verbose debug logging
+- **WALLET_STORAGE_URL** – URL of wallet storage service (e.g., `https://storage.babbage.systems`)
+- **KNEX_DB_CLIENT** – Database client (default: `mysql`)
+- **KNEX_DB_CONNECTION** – JSON connection config: `{"host":"localhost","port":3306,"user":"root","password":"...","database":"messagebox-backend"}`
+- **MIGRATE_KEY** – Optional key to authorize migration operations
+- **ENABLE_FIREBASE** – Set to `'true'` to enable Firebase push notifications
+- **FIREBASE_PROJECT_ID** – GCP project ID for Firebase
+- **FIREBASE_SERVICE_ACCOUNT_JSON** – Firebase service account JSON (inline)
+- **FIREBASE_SERVICE_ACCOUNT_PATH** – Path to Firebase service account JSON file
+
+## Dependencies
+- **Database** – MySQL 8.0 via knex + mysql2
+- **@bsv packages**
+  - `@bsv/sdk` – Cryptography, key handling
+  - `@bsv/auth-express-middleware` – BRC-103 request/response authentication
+  - `@bsv/authsocket` – Authenticated WebSocket server
+  - `@bsv/payment-express-middleware` – Optional payment verification
+  - `@bsv/wallet-toolbox` – Wallet operations
+- **External services**
+  - Wallet Storage (via `WALLET_STORAGE_URL`) – Stores key derivation metadata
+  - Firebase Admin SDK (optional) – Push notifications to registered devices
+- **Key packages** – Express, body-parser, dotenv, socket.io (WebSocket), web-push, firebase-admin, swagger-jsdoc
+
+## Operational concerns
+- **Local dev** – `npm run dev` with hot-reload via nodemon, requires MySQL running (use docker-compose)
+- **Production** – `npm run build && npm start` compiles TypeScript to `out/`, then `node out/src/index.js` starts
+- **Migrations** – Auto-run after server starts (5s delay in code); use `MIGRATE_KEY` to authorize if needed
+- **Health endpoint** – No explicit health check route; monitor WebSocket and HTTP endpoints
+- **Scaling** – Single instance by design; WebSocket rooms are in-memory, horizontal scaling requires sticky sessions or external message broker
+- **Database** – MySQL 8.0 required; note query performance with large message volumes (index on identity keys + messageBox)
+- **WebSocket** – `@bsv/authsocket` handles multiplexing; each client connects once but can join multiple rooms
+
+## Spec conformance
+- **BRC-103** – Mutual authentication on all requests and WebSocket handshakes
+- **BRC-2** – Optional AES-encrypted message payloads (client-side encryption supported)
+- **SHIP** – Overlay advertisement via `@bsv/sdk` PublicKey operations
+- **MessageBox protocol** – Custom identity + messageBox type routing model
+
+## Integration points
+- **@bsv/messagebox-client** – Client library that connects to this server, handles auth, encryption, WebSocket
+- **Wallet Storage** – Derives keys from SERVER_PRIVATE_KEY via configured wallet storage endpoint
+- **Overlay nodes** – Can advertise MessageBox capabilities via SHIP protocol using HOSTING_DOMAIN
+- **Payment processing** – Optionally enforces BRC-100 payment verification on message send (via `@bsv/payment-express-middleware`)
+
+## File map
+- **src/**
+  - `index.ts` – Entry point: loads env, creates HTTP + WebSocket servers, starts migrations
+  - `app.ts` – Express app setup, route mounting, auth middleware
+  - `routes/` – HTTP endpoints: `sendMessage.ts`, `listMessages.ts`, `acknowledgeMessage.ts`, device listing, permissions
+  - `config/firebase.ts` – Firebase Admin SDK initialization
+  - `utils/` – Helpers: logger, notification sending, message permissions
+  - `migrations/` – Knex schema migrations for messages, permissions, devices
+  - `types/` – TypeScript interfaces for notifications, permissions
+- **knexfile.ts** – Knex configuration, driver selection, connection pooling
+- **Dockerfile** – Multi-stage Node + nginx container
+- **docker-compose.yml** – Services: backend, MySQL, PHPMyAdmin
+- **nginx.conf** – Reverse proxy config
+- **.env.example** – Template with all required/optional variables

package/BASELINE.md

@@ -0,0 +1,55 @@
+# BASELINE — @bsv/messagebox-server
+
+> Captured: 2026-04-24. Reflects state at time of ts-stack migration.
+
+## Identity
+| Field | Value |
+|-------|-------|
+| Package | `@bsv/messagebox-server` |
+| Path | `packages/messaging/message-box-server` |
+| npm | private — not published |
+| Version | 1.1.5 |
+| Criticality | **Tier 2** — private messaging service; failure isolates to message delivery domain |
+| Reliability Level | **RL1** — builds, 3 test files, coverage tooling present but coverage unknown |
+| Owner | @sirdeggen |
+| Backup owner | — |
+
+## Build
+| Field | Value |
+|-------|-------|
+| Build command | `tsc` |
+| Build status | ✅ Passing (assumed — not yet verified in ts-stack CI) |
+| Outputs | Compiled JS (ESM via tsc) |
+
+## Tests
+| Field | Value |
+|-------|-------|
+| Test command | `node --experimental-vm-modules node_modules/jest/bin/jest.js --config=jest.config.mjs` |
+| Test files | 3 |
+| Coverage command | `node --experimental-vm-modules node_modules/jest/bin/jest.js --config=jest.config.mjs --coverage --coverageReporters=text --coverageReporters=html` |
+| Coverage | Not yet captured as baseline |
+| Known flaky | None identified |
+
+## Lint
+| Field | Value |
+|-------|-------|
+| Linter | ts-standard |
+| Lint command | `ts-standard --fix .` |
+
+## Dependencies
+| Type | Count | Packages |
+|------|-------|---------|
+| Production | 16 | @bsv/auth-express-middleware, @bsv/authsocket, @bsv/payment-express-middleware, @bsv/sdk, @bsv/wallet-toolbox, body-parser, dotenv, express, firebase-admin, knex, mongodb, mysql2, prettyjson, swagger-jsdoc, swagger-ui-express, web-push |
+
+## Known Issues & Incidents
+- Private package — not published to npm.
+- Service, not a library; requires database and external dependencies at runtime.
+- Uses `--experimental-vm-modules` flag for Jest ESM support.
+
+## Migration Gate Checklist (MBGA §13.3)
+- [x] BASELINE.md captured
+- [ ] Conformance runner vectors passing
+- [ ] Contract tests green
+- [ ] Publishing rehearsed (npm dry-run)
+- [ ] Rollback documented
+- [ ] 60-day deprecation notice in source repo

package/DEPLOYING.md

@@ -0,0 +1,120 @@
+# MessageBox Server Deployment Guide
+This guide covers how to deploy the MessageBox Server — a secure peer-to-peer message relay supporting authenticated HTTP and WebSocket communication and encrypted payloads.
+________________________________________
+### Overview
+The MessageBox Server is a node-based Express server that enables identity-authenticated messaging over HTTP and WebSocket. Key features:
+- Authenticated message sending and receiving
+- Message box creation and routing by identity key
+- WebSocket-based real-time delivery
+- AES-encrypted message payloads (handled by clients)
+________________________________________
+### Requirements
+- Node.js v18 or higher
+- MySQL v8 or higher
+- Docker (optional for local setup)
+- A valid SERVER_PRIVATE_KEY - a 256-bit hex private key
+- Wallet Storage instance URL (e.g., https://wallet-storage.babbage.systems)
+________________________________________
+### Project Structure
+```bash
+.
+├── src/                    # Server source files (Express app, routes, WebSocket, logger)
+├── knexfile.js             # DB connection settings
+├── app.ts                  # Express and route setup
+├── index.ts                # Server entry point with WebSocket support
+├── .env                    # Environment variable configuration
+└── ...
+```
+________________________________________
+### Required Environment Variables
+
+Create a .env file in the root with the following:
+
+```env
+NODE_ENV=production
+SERVER_PRIVATE_KEY=your_hex_64_char_key
+WALLET_STORAGE_URL=https://wallet-storage.babbage.systems
+ENABLE_WEBSOCKETS=true
+PORT=5001
+ROUTING_PREFIX=
+```
+
+Optional:
+
+```env
+LOGGING_ENABLED=true
+SKIP_NGINX=true     # Set to skip auto-starting nginx in production
+```
+________________________________________
+### Deployment Steps
+**Local Development**
+1.	Install dependencies:
+```bash
+npm install
+```
+2.	Start MySQL database (you can use Docker or your local MySQL):
+    - If using Docker:
+    ```bash
+    docker compose up --build
+    ```
+    - Otherwise, ensure a database is running and matches your knexfile.js.
+3.	Set up environment variables:
+```bash
+cp .env.example .env
+# Fill in actual values
+```
+4.	Run migrations:
+```bash
+npm run migrate
+```
+5.	Start the server in development mode:
+```bash
+npm run dev
+```
+Server will run at http://localhost:5001
+________________________________________
+### Production Deployment
+1.	Ensure production .env is configured correctly
+2.	Build the project (if applicable):
+```bash
+npm run build
+```
+3.	Run the server:
+```bash
+npm start
+```
+4.	Optionally, configure nginx to reverse proxy to the server. Nginx will start automatically unless SKIP_NGINX=true is set.
+________________________________________
+### WebSocket Support
+WebSocket support is enabled by default unless ENABLE_WEBSOCKETS=false is set in .env.
+Clients must authenticate with their identity key to establish a WebSocket connection.
+________________________________________
+### Testing
+To run tests:
+```bash
+npm test
+```
+This includes unit tests and integration tests for HTTP and WebSocket message delivery.
+________________________________________
+### Docker Usage
+Use Docker only if you're running a local test instance:
+```bash
+docker compose up -- build
+```
+- Web server runs on port 3002
+- Database runs on port 3001
+- PHPMyAdmin (for SQL browsing) runs on port 3003
+________________________________________
+### Deployment on Google Cloud Run
+MessageBox can also be containerized and deployed on Google Cloud Run or any similar service. See DEPLOYING.md in backend/ for overlay-specific LARS deployment instructions.
+________________________________________
+### Related Projects
+- [MessageBoxClient](https://github.com/bitcoin-sv/p2p)
+- [WalletClient](https://github.com/bitcoin-sv)
+- [Auth Middleware](https://www.npmjs.com/package/@bsv/auth-express-middleware)
+________________________________________
+📄 License
+The MessageBox Server is licensed under the [Open BSV License](https://www.bsvlicense.org/).
+________________________________________
+
+

package/Dockerfile

@@ -0,0 +1,63 @@
+# ---- Build stage ----
+FROM node:20-alpine AS builder
+
+WORKDIR /app
+
+# Native deps (better-sqlite3) compile from source on Alpine (musl, no prebuilt
+# binaries) — needs python3/make/g++.
+RUN apk add --no-cache python3 make g++
+
+# Copy package files first for better layer caching
+COPY package*.json ./
+COPY tsconfig*.json ./
+COPY knexfile.ts ./
+
+# Install all dependencies (including dev deps for build)
+RUN npm install
+
+# Install global tools (optional, depends on how you're running knex)
+RUN npm install -g knex typescript
+
+# Copy source code required for compilation
+COPY src ./src
+
+# Build the TypeScript project
+RUN npm run build
+
+# Copy compiled knexfile.js to /app root (where imports like '../../knexfile.js' expect it)
+RUN cp out/knexfile.js ./knexfile.js
+
+# ---- Production stage ----
+FROM node:20-alpine
+
+# Ensure all OS packages are up to date (patch CVEs in base image) and install nginx
+RUN apk upgrade --no-cache && \
+    apk add --no-cache nginx && \
+    chown -R nginx:www-data /var/lib/nginx
+
+WORKDIR /app
+
+# Copy package files and install production deps only.
+# better-sqlite3 compiles from source on Alpine; add the toolchain just for the
+# install, then remove it in the same layer to keep the image slim.
+COPY --chown=root:root --chmod=0444 package*.json ./
+RUN apk add --no-cache --virtual .build-deps python3 make g++ \
+ && npm ci --omit=dev \
+ && apk del .build-deps \
+ && rm -rf /usr/local/lib/node_modules/npm /usr/local/bin/npm /usr/local/bin/npx
+
+# Copy built output from builder
+COPY --from=builder --chown=root:root --chmod=0555 /app/out ./out
+COPY --from=builder --chown=root:root --chmod=0444 /app/knexfile.js ./knexfile.js
+
+# Copy nginx config
+COPY ./nginx.conf /etc/nginx/nginx.conf
+
+# Expose the API port
+EXPOSE 8080
+
+USER node
+
+# Start the app with the OpenTelemetry bootstrap preloaded (ESM --import) so
+# auto-instrumentation patches modules before they are imported.
+CMD [ "node", "--import", "./out/src/telemetry.js", "out/src/index.js" ]