@bopen-io/messagebox-server 1.1.5 → 1.2.1

package/src/context.ts

@@ -0,0 +1,49 @@
+import type { Knex } from 'knex'
+import type { WalletInterface } from '@bsv/sdk'
+import type { Request } from 'express'
+
+export interface MessageBoxContext {
+  wallet: WalletInterface
+  knex: Knex
+  routingPrefix: string
+  enableWebSockets: boolean
+  enableSwagger: boolean
+  calculateRequestPrice: (req: Request) => Promise<number> | number
+  logger: Console
+}
+
+export interface CreateMessageBoxContextOptions {
+  wallet: WalletInterface
+  knex: Knex
+  routingPrefix?: string
+  enableWebSockets?: boolean
+  enableSwagger?: boolean
+  calculateRequestPrice?: (req: Request) => Promise<number> | number
+  logger?: Console
+}
+
+export function createMessageBoxContext (
+  deps: CreateMessageBoxContextOptions
+): MessageBoxContext {
+  if (deps.wallet == null) {
+    throw new Error('createMessageBoxContext requires a wallet')
+  }
+  if (deps.knex == null) {
+    throw new Error('createMessageBoxContext requires a knex instance')
+  }
+
+  return {
+    wallet: deps.wallet,
+    knex: deps.knex,
+    routingPrefix: deps.routingPrefix ?? '',
+    enableWebSockets: deps.enableWebSockets ?? true,
+    enableSwagger: deps.enableSwagger ?? true,
+    calculateRequestPrice: deps.calculateRequestPrice ?? (async (req: Request) => {
+      if (req.url.includes('/sendMessage')) {
+        // configurable via deps.calculateRequestPrice
+      }
+      return 0
+    }),
+    logger: deps.logger ?? console
+  }
+}

package/src/index.ts

@@ -0,0 +1,375 @@
+/**
+ * @file index.ts
+ * @description
+ * Main entry point for the MessageBox Server.
+ *
+ * Responsibilities:
+ * - Initializes environment variables and config
+ * - Creates HTTP and WebSocket servers
+ * - Boots authentication and route handlers
+ * - Sets up database migrations after a short delay
+ * - Emits and handles real-time message events over WebSocket
+ *
+ * Exports:
+ * - `start()` for programmatic bootstrapping
+ * - `http` and `io` server instances
+ * - `HTTP_PORT` and `ROUTING_PREFIX` for external reference
+ */
+
+import * as dotenv from 'dotenv'
+import { app, appReady, getWallet, knex } from './app.js'
+import { spawn } from 'child_process'
+import { createServer } from 'http'
+import { PublicKey } from '@bsv/sdk'
+import { Logger, log } from './utils/logger.js'
+import { trace, SpanStatusCode } from '@opentelemetry/api'
+import { AuthSocketServer } from '@bsv/authsocket'
+import * as crypto from 'crypto'
+import { initializeFirebase } from './config/firebase.js'
+(global.self as any) = { crypto }
+
+dotenv.config()
+
+// Load environment variables
+const {
+  NODE_ENV = 'development',
+  PORT,
+  SERVER_PRIVATE_KEY,
+  ENABLE_WEBSOCKETS = 'true',
+  ROUTING_PREFIX = ''
+} = process.env
+
+// if (NODE_ENV === 'development' || process.env.LOGGING_ENABLED === 'true') {
+//   Logger.enable()
+// }
+Logger.enable()
+// Determine which port to listen on
+const parsedPort = Number(PORT)
+const parsedEnvPort = Number(process.env.HTTP_PORT)
+
+const HTTP_PORT: number = NODE_ENV !== 'development'
+  ? 3000
+  : !Number.isNaN(parsedPort) && parsedPort > 0
+    ? parsedPort
+    : !Number.isNaN(parsedEnvPort) && parsedEnvPort > 0
+      ? parsedEnvPort
+      : 8080
+
+// Ensure private key is available before proceeding
+if (SERVER_PRIVATE_KEY === undefined || SERVER_PRIVATE_KEY === null || SERVER_PRIVATE_KEY.trim() === '') {
+  throw new Error('SERVER_PRIVATE_KEY is not defined in the environment variables.')
+}
+
+// Initialize Firebase Admin (only when ENABLE_FIREBASE=true)
+initializeFirebase()
+
+// Create HTTP server
+/* eslint-disable @typescript-eslint/no-misused-promises */
+const http = createServer(app)
+
+// WebSocket setup (only if enabled)
+// Held in a const container so the exported binding is never reassigned.
+const ioRef: { current: AuthSocketServer | null } = { current: null }
+
+/**
+ * @function start
+ * @description
+ * Initializes the WebSocket server with identity-key-based authentication
+ * and attaches all supported event handlers for:
+ * - `sendMessage`
+ * - `joinRoom`
+ * - `leaveRoom`
+ * - `disconnect`
+ *
+ * Only runs if `ENABLE_WEBSOCKETS` is set to `true` in the environment.
+ *
+ * @returns {Promise<void>} Resolves once WebSocket listeners are fully attached.
+ */
+export const start = async (): Promise<void> => {
+  await appReady
+
+  if (ENABLE_WEBSOCKETS.toLowerCase() === 'true') {
+    Logger.log('[WEBSOCKET] Initializing WebSocket support...')
+    ioRef.current = new AuthSocketServer(http, {
+      wallet: await getWallet(),
+      cors: {
+        origin: '*',
+        methods: ['GET', 'POST']
+      }
+    })
+
+    // Map to store authenticated identity keys
+    const authenticatedSockets = new Map<string, string>()
+
+    ioRef.current.on('connection', (socket) => {
+      Logger.log('[WEBSOCKET] New connection established.')
+
+      // Handle immediate authentication if identityKey is available
+      if (typeof socket.identityKey === 'string' && socket.identityKey.trim() !== '') {
+        try {
+          const parsedIdentityKey = PublicKey.fromString(socket.identityKey)
+          Logger.log('[DEBUG] Parsed WebSocket Identity Key Successfully:', parsedIdentityKey.toString())
+
+          authenticatedSockets.set(socket.id, parsedIdentityKey.toString())
+          Logger.log('[WEBSOCKET] Identity key stored for socket ID:', socket.id)
+
+          // Send confirmation immediately if identity key is provided on connection
+          void socket.emit('authenticationSuccess', { status: 'success' })
+        } catch (error) {
+          Logger.error('[ERROR] Failed to parse WebSocket identity key:', error)
+        }
+      } else {
+        // Wait for 'authenticated' event if identityKey was not in handshake
+        Logger.warn('[WARN] WebSocket connection received without identity key. Waiting for authentication...')
+
+        let identityKeyHandled = false
+
+        const authListener = async (data: { identityKey?: string }): Promise<void> => {
+          if (identityKeyHandled) return
+
+          Logger.log('[WEBSOCKET] Received authentication data:', data)
+
+          if (data !== null && data !== undefined && typeof data.identityKey === 'string' && data.identityKey.trim().length > 0) {
+            try {
+              const parsedIdentityKey = PublicKey.fromString(data.identityKey)
+              Logger.log('[DEBUG] Retrieved and parsed Identity Key after connection:', parsedIdentityKey.toString())
+
+              authenticatedSockets.set(socket.id, parsedIdentityKey.toString())
+              Logger.log('[WEBSOCKET] Stored authenticated Identity Key for socket ID:', socket.id)
+
+              identityKeyHandled = true
+
+              Logger.log(`New authenticated WebSocket connection from: ${authenticatedSockets.get(socket.id) ?? 'unknown'}`)
+
+              // Emit authentication success message
+              await socket.emit('authenticationSuccess', { status: 'success' }).catch(error => {
+                Logger.error('[WEBSOCKET ERROR] Failed to send authentication success event:', error)
+              })
+            } catch (error) {
+              Logger.error('[ERROR] Failed to parse Identity Key from authenticated event:', error)
+              await socket.emit('authenticationFailed', { reason: 'Invalid identity key format' })
+            }
+          } else {
+            Logger.warn('[WARN] Invalid or missing identity key in authentication event.')
+            await socket.emit('authenticationFailed', { reason: 'Missing identity key' })
+          }
+        }
+
+        // Ensure `authListener` is used properly
+        socket.on('authenticated', authListener)
+      }
+
+      // Handle sendMessage over WebSocket
+      socket.on(
+        'sendMessage',
+        async (data: { roomId: string, message: { messageId: string, recipient: string, body: string } }): Promise<void> => {
+          if (typeof data !== 'object' || data == null) {
+            Logger.error('[WEBSOCKET ERROR] Invalid data object received.')
+            await socket.emit('messageFailed', { reason: 'Invalid data object' })
+            return
+          }
+
+          const { roomId, message } = data
+
+          if (!authenticatedSockets.has(socket.id)) {
+            Logger.warn('[WEBSOCKET] Unauthorized attempt to send a message.')
+            await socket.emit('paymentFailed', { reason: 'Unauthorized: WebSocket not authenticated' })
+            return
+          }
+
+          Logger.log(`[WEBSOCKET] Processing sendMessage for room: ${roomId}`)
+
+          try {
+            if (typeof roomId !== 'string' || roomId.trim() === '') {
+              Logger.error('[WEBSOCKET ERROR] Invalid roomId:', roomId)
+              await socket.emit('messageFailed', { reason: 'Invalid room ID' })
+              return
+            }
+
+            if (typeof message !== 'object' || message == null) {
+              Logger.error('[WEBSOCKET ERROR] Invalid message object:', message)
+              await socket.emit('messageFailed', { reason: 'Invalid message object' })
+              return
+            }
+
+            if (typeof message.body !== 'string' || message.body.trim() === '') {
+              Logger.error('[WEBSOCKET ERROR] Invalid message body:', message.body)
+              await socket.emit('messageFailed', { reason: 'Invalid message body' })
+              return
+            }
+
+            Logger.log(`[WEBSOCKET] Acknowledging message ${message.messageId} to sender.`)
+
+            const ackPayload = {
+              status: 'success',
+              messageId: message.messageId
+            }
+
+            Logger.log(`[WEBSOCKET] Emitting ack event: sendMessageAck-${roomId}`)
+
+            socket.emit(`sendMessageAck-${roomId}`, ackPayload).catch((error) => {
+              Logger.error(`[WEBSOCKET ERROR] Failed to emit sendMessageAck-${roomId}:`, error)
+            })
+
+            // Store message in the database just like HTTP sendMessage route
+            try {
+              const parts = roomId.split('-')
+              const messageBoxType = parts.length > 1 ? parts[1] : 'default'
+
+              Logger.log(`[WEBSOCKET] Parsed messageBoxType: ${messageBoxType}`)
+              Logger.log(`[WEBSOCKET] Attempting to store message for recipient: ${message.recipient}, box type: ${messageBoxType}`)
+
+              let messageBox = await knex('messageBox')
+                .where({ identityKey: message.recipient, type: messageBoxType })
+                .first()
+
+              if (messageBox === null || messageBox === undefined) {
+                Logger.log('[WEBSOCKET] messageBox not found. Creating new messageBox.')
+                await knex('messageBox').insert({
+                  identityKey: message.recipient,
+                  type: messageBoxType,
+                  created_at: new Date(),
+                  updated_at: new Date()
+                })
+              }
+
+              messageBox = await knex('messageBox')
+                .where({ identityKey: message.recipient, type: messageBoxType })
+                .select('messageBoxId')
+                .first()
+
+              const messageBoxId = messageBox?.messageBoxId ?? null
+
+              if (messageBoxId === null || messageBoxId === undefined) {
+                Logger.warn('[WEBSOCKET WARNING] messageBoxId is null — message may not be stored correctly!')
+              } else {
+                Logger.log(`[WEBSOCKET] Resolved messageBoxId: ${String(messageBoxId)}`)
+              }
+
+              const senderKey = authenticatedSockets.get(socket.id) ?? null
+
+              const insertResult = await knex('messages')
+                .insert({
+                  messageId: message.messageId,
+                  messageBoxId,
+                  sender: senderKey,
+                  recipient: message.recipient,
+                  body: message.body,
+                  created_at: new Date(),
+                  updated_at: new Date()
+                })
+                .onConflict('messageId')
+                .ignore()
+
+              if (insertResult.length === 0) {
+                Logger.warn('[WEBSOCKET WARNING] Message insert was ignored due to conflict (duplicate messageId?)')
+              } else {
+                Logger.log('[WEBSOCKET] Message successfully stored in DB.')
+              }
+            } catch (dbError) {
+              Logger.error('[WEBSOCKET ERROR] Failed to store message in DB:', dbError)
+              await socket.emit('messageFailed', { reason: 'Failed to store message' })
+              return
+            }
+
+            if (ioRef.current === null) {
+              Logger.error('[WEBSOCKET ERROR] io is null, cannot emit message.')
+              return
+            }
+            Logger.log(`[WEBSOCKET] Emitting message to room ${roomId}`)
+            ioRef.current.emit(`sendMessage-${roomId}`, {
+              sender: authenticatedSockets.get(socket.id),
+              messageId: message.messageId,
+              body: message.body
+            })
+          } catch (error) {
+            Logger.error('[WEBSOCKET ERROR] Unexpected failure in sendMessage handler:', error)
+            await socket.emit('messageFailed', { reason: 'Unexpected error occurred' })
+          }
+        }
+      )
+
+      // Handle joining/leaving rooms
+      socket.on('joinRoom', async (roomId: string) => {
+        if (!authenticatedSockets.has(socket.id)) {
+          Logger.warn('[WEBSOCKET] Unauthorized attempt to join a room.')
+          await socket.emit('joinFailed', { reason: 'Unauthorized: WebSocket not authenticated' })
+          return
+        }
+
+        if (roomId == null || typeof roomId !== 'string' || roomId.trim() === '') {
+          Logger.error('[WEBSOCKET ERROR] Invalid roomId:', roomId)
+          await socket.emit('joinFailed', { reason: 'Invalid room ID' })
+          return
+        }
+
+        Logger.log(`[WEBSOCKET] User ${socket.id} joined room ${roomId}`)
+        await socket.emit('joinedRoom', { roomId })
+      })
+
+      socket.on('leaveRoom', async (roomId: string) => {
+        if (!authenticatedSockets.has(socket.id)) {
+          Logger.warn('[WEBSOCKET] Unauthorized attempt to leave a room.')
+          await socket.emit('leaveFailed', { reason: 'Unauthorized: WebSocket not authenticated' })
+          return
+        }
+
+        if (roomId == null || roomId === '' || typeof roomId !== 'string' || roomId.trim() === '') {
+          Logger.error('[WEBSOCKET ERROR] Invalid roomId:', roomId)
+          await socket.emit('leaveFailed', { reason: 'Invalid room ID' })
+          return
+        }
+
+        Logger.log(`[WEBSOCKET] User ${socket.id} left room ${roomId}`)
+        await socket.emit('leftRoom', { roomId })
+      })
+
+      // Clean up on disconnect
+      socket.on('disconnect', (reason: string) => {
+        Logger.log(`[WEBSOCKET] Disconnected: ${reason}`)
+        authenticatedSockets.delete(socket.id)
+      })
+    })
+  }
+}
+
+// Export for testing and CLI use.
+// `ioRef` is a const container; the live WebSocket server is at `ioRef.current`.
+export { ioRef as io, http, HTTP_PORT, ROUTING_PREFIX }
+
+// Only run server if not in test mode
+if (NODE_ENV !== 'test') {
+  const tracer = trace.getTracer('@bsv/messagebox-server')
+  http.listen(HTTP_PORT, () => {
+    log.info({ operation: 'listen', outcome: 'ok', port: HTTP_PORT }, 'MessageBox listening')
+
+      // Run DB migrations immediately, no delay needed with container healthchecks
+      ; tracer.startActiveSpan('messagebox.migrate', async (span) => {
+        const startedAt = Date.now()
+        try {
+          await knex.migrate.latest()
+          span.setStatus({ code: SpanStatusCode.OK })
+          log.info({ operation: 'migrate', outcome: 'ok', duration_ms: Date.now() - startedAt }, 'migrations applied')
+        } catch (error) {
+          span.recordException(error as Error)
+          span.setStatus({ code: SpanStatusCode.ERROR, message: (error as Error).message })
+          log.error({ operation: 'migrate', outcome: 'error', err: error }, '[STARTUP ERROR] migrations failed')
+        } finally {
+          span.end()
+        }
+      })
+  })
+
+  start().catch(error => {
+    log.error({ operation: 'server.init', outcome: 'error', err: error }, '[SERVER INIT ERROR]')
+  })
+}
+
+// Composable API for embedding (standalone boot above is unchanged)
+export {
+  createMessageBoxContext,
+  createMessageBoxApp,
+  mountMessageBoxRoutes,
+  attachMessageBoxWebSockets
+} from './compose.js'
+export type { MessageBoxContext, CreateMessageBoxContextOptions } from './context.js'

package/src/routes/__tests/acknowledgeMessage.test.ts

@@ -0,0 +1,158 @@
+/* eslint-env jest */
+import acknowledgeMessage, { AcknowledgeRequest } from '../acknowledgeMessage.js'
+import mockKnex, { Tracker } from 'mock-knex'
+import { Response } from 'express'
+import knexLib from 'knex'
+import knexConfig from '../../../knexfile.js'
+import { bindMessageBoxRuntime } from '../../runtimeDeps.js'
+
+const testKnex = (knexLib as any).default?.(knexConfig.development) ??
+  (knexLib as any)(knexConfig.development)
+bindMessageBoxRuntime({ knex: testKnex })
+const knex = acknowledgeMessage.knex
+let queryTracker: Tracker
+
+// Define Mock Express Response Object
+const mockRes: jest.Mocked<Response> = {
+  status: jest.fn().mockReturnThis(),
+  json: jest.fn().mockReturnThis(),
+  sendStatus: jest.fn().mockReturnThis(),
+  send: jest.fn().mockReturnThis(),
+  end: jest.fn().mockReturnThis(),
+  setHeader: jest.fn().mockReturnThis(),
+  getHeader: jest.fn(),
+  getHeaders: jest.fn(),
+  header: jest.fn().mockReturnThis(),
+  type: jest.fn().mockReturnThis(),
+  format: jest.fn(),
+  location: jest.fn().mockReturnThis(),
+  redirect: jest.fn().mockReturnThis(),
+  append: jest.fn().mockReturnThis(),
+  render: jest.fn(),
+  vary: jest.fn().mockReturnThis(),
+  cookie: jest.fn().mockReturnThis(),
+  clearCookie: jest.fn().mockReturnThis()
+} as unknown as jest.Mocked<Response>
+
+let validReq: AcknowledgeRequest
+
+describe('acknowledgeMessage', () => {
+  beforeAll(() => {
+    (mockKnex as any).mock(knex)
+  })
+
+  beforeEach(() => {
+    jest.spyOn(console, 'error').mockImplementation(() => { })
+
+    queryTracker = (mockKnex as any).getTracker() as Tracker
+    queryTracker.install()
+
+    validReq = {
+      auth: {
+        identityKey: 'mockIdKey'
+      },
+      body: {
+        messageIds: ['123']
+      },
+      get: jest.fn(),
+      header: jest.fn()
+    } as unknown as AcknowledgeRequest
+  })
+
+  afterEach(() => {
+    jest.clearAllMocks()
+
+    if (queryTracker !== null && queryTracker !== undefined) {
+      queryTracker.uninstall()
+    }
+  })
+
+  afterAll(() => {
+    (mockKnex as any).unmock(knex)
+  })
+
+  it('Throws an error if messageId is missing', async () => {
+    delete validReq.body.messageIds
+    await acknowledgeMessage.func(validReq, mockRes as Response)
+    expect(mockRes.status).toHaveBeenCalledWith(400)
+    expect(mockRes.json).toHaveBeenCalledWith(expect.objectContaining({
+      status: 'error',
+      code: 'ERR_MESSAGE_ID_REQUIRED'
+    }))
+  })
+
+  it('Throws an error if messageIds is not an Array', async () => {
+    validReq.body.messageIds = '24' as unknown as string[]
+
+    await acknowledgeMessage.func(validReq, mockRes as Response)
+
+    expect(mockRes.status).toHaveBeenCalledWith(400)
+    expect(mockRes.json).toHaveBeenCalledWith(expect.objectContaining({
+      status: 'error',
+      code: 'ERR_INVALID_MESSAGE_ID',
+      description: 'Message IDs must be formatted as an array of strings!'
+    }))
+  }, 7000)
+
+  it('Deletes a message', async () => {
+    queryTracker.on('query', (q, s) => {
+      if (s === 1) {
+        expect(q.method).toEqual('del')
+        expect(q.sql).toEqual(
+          'delete from `messages` where `recipient` = ? and `messageId` in (?)'
+        )
+        expect(q.bindings).toEqual([
+          'mockIdKey',
+          '123'
+        ])
+        q.response(true)
+      } else {
+        q.response([])
+      }
+    })
+
+    await acknowledgeMessage.func(validReq, mockRes as Response)
+    expect(mockRes.status).toHaveBeenCalledWith(200)
+    expect(mockRes.json).toHaveBeenCalledWith(expect.objectContaining({
+      status: 'success'
+    }))
+  })
+
+  it('Throws an error if deletion fails', async () => {
+    queryTracker.on('query', (q, step) => {
+      if (step === 1) {
+        expect(q.method).toEqual('del')
+        expect(q.sql).toEqual('delete from `messages` where `recipient` = ? and `messageId` in (?)')
+        expect(q.bindings).toEqual(['mockIdKey', '123'])
+
+        q.response(0) // Simulate deletion failure
+      } else {
+        q.response([]) // Prevent test from hanging due to unhandled second query
+      }
+    })
+
+    await acknowledgeMessage.func(validReq, mockRes as Response)
+
+    expect(mockRes.status).toHaveBeenCalledWith(400)
+    expect(mockRes.json).toHaveBeenCalledWith(expect.objectContaining({
+      status: 'error',
+      code: 'ERR_INVALID_ACKNOWLEDGMENT',
+      description: 'Message not found!'
+    }))
+  }, 7000)
+
+  it('Throws unknown errors', async () => {
+    queryTracker.on('query', () => {
+      throw new Error('Failed')
+    })
+
+    await acknowledgeMessage.func(validReq, mockRes as Response)
+
+    expect(mockRes.status).toHaveBeenCalledWith(500)
+    expect(mockRes.json).toHaveBeenCalledWith(expect.objectContaining({
+      status: 'error',
+      code: 'ERR_INTERNAL_ERROR',
+      description: 'An internal error has occurred while acknowledging the message'
+    }))
+  })
+})