Message Box Server

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.

What it does

The Message Box Server implements encrypted, store-and-forward messaging with support for both HTTP and WebSocket transports. Messages are identified by sender identity keys and recipient message boxes, encrypted end-to-end, and stored in MySQL until acknowledged by the recipient. The server speaks HTTP and WebSocket protocols, maintains connection state via @bsv/authsocket rooms, and can emit Firebase push notifications to registered devices.

Clients connect with identity-based authentication, send and receive messages through authenticated endpoints, and can opt into real-time WebSocket delivery for immediate notifications.

When to deploy this

• Building peer-to-peer messaging applications on BSV
• You need encrypted, identity-based message delivery
• Supporting both HTTP polling and real-time WebSocket clients
• Requiring Firebase push notifications to mobile devices

Dependencies

HTTP endpoints

The omitted page size is 1,000 in the standard profile and is operator configurable. Responses include limit, offset, nextOffset, and hasMore. See Service Resource Profiles for all limits, shared state, BRC-105 pricing, memory evidence, and scaling guidance.

WebSocket endpoints

• ws://host:8080 – Authenticated WebSocket server using @bsv/authsocket
  • Subscription names: {identityKey}-{messageBox} format
  • Events: authenticated, joinRoom, sendMessage, leaveRoom
  • Payload identity claims must match the BRC-103 peer identity
  • Notifications are routed only to authenticated recipient connections; sends reuse the HTTP validation, permission, fee, and persistence policy

Configuration (env vars)

See Public Service Edge Security for rate, timeout, WebSocket authorization, CORS/CSP, and error controls.

Run locally

# Install dependencies
npm install

# Development with hot-reload
npm run dev

# Database setup (MySQL 8.0 running)
docker compose up -d mysql

# Build for production
npm run build

# Run production build
npm start

Deploy to production

# Build Docker image
docker build -t messagebox:latest .

# Run the service directly on port 8080
docker run -d \
  -e NODE_ENV=production \
  -e PORT=8080 \
  -e SERVER_PRIVATE_KEY=<hex-key> \
  -e KNEX_DB_CONNECTION='{"host":"mysql","port":3306,"user":"root","password":"...","database":"messagebox-backend"}' \
  -e ENABLE_WEBSOCKETS=true \
  -p 8080:8080 \
  messagebox:latest

# Or use docker-compose
docker compose up -d

The multi-stage Dockerfile compiles TypeScript for a minimal production runtime. The Node process serves HTTP and WebSocket traffic directly; deploy a trusted platform ingress or load balancer in front when required.

Migrations

Knex migrations run automatically at server startup. After building, they can also be run manually:

npx --no-install knex --knexfile out/knexfile.js migrate:latest --env production

Migrations tracked 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
• 2026-07-26-001-message-permission-scope.ts – Enforce one box-wide or sender-specific permission per scope
• 2026-07-26-002-list-query-indexes.ts – Add indexes for bounded inbox and sender-list queries
• 2026-08-04-001-resource-safety.ts – Add retained-state accounting and resource-safety fields

Health checks

• GET /health reports process liveness without authentication.
• GET /ready verifies database connectivity and returns a non-sensitive 503 response while dependencies are unavailable.
• Test an authenticated WebSocket handshake separately when live transport is enabled.

Spec conformance

• BRC-103 – Mutual authentication on all HTTP 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 with ts-stack

• Clients connect via @bsv/message-box-client
• Uses Wallet Storage for key derivation from SERVER_PRIVATE_KEY
• Advertises MessageBox capabilities to overlay nodes via SHIP protocol using HOSTING_DOMAIN
• Optionally enforces BRC-100 payment verification on message send via @bsv/payment-express-middleware

Common pitfalls

• WebSocket scaling: authenticated connection routing is per process; use sticky sessions or an authenticated external broker for horizontal scaling
• Database indexing: Ensure indexes on identity keys + messageBox for high-volume deployments
• Firebase setup: Requires valid service account JSON; Firebase push disabled if misconfigured
• Private key generation: Must be 256-bit hex; asymmetric key used for mutual auth signing
• Migration failures prevent the process from accepting traffic; deployments should still gate traffic on /ready.

Source

• GitHub

The service package is private and is distributed as a container, not as a public npm package.