@bopen-io/messagebox-server 1.1.5 → 1.2.1

package/src/app.ts

@@ -0,0 +1,210 @@
+/**
+ * @file app.ts
+ * @description
+ * Initializes the MessageBoxServer Express app.
+ *
+ * Responsibilities:
+ * - Parses environment variables and loads config
+ * - Sets up Knex for DB access
+ * - Initializes WalletClient from the BSV SDK
+ * - Mounts Express routes (pre-auth and post-auth)
+ * - Applies auth middleware using wallet identity
+ *
+ * This file exports:
+ * - `app`: the configured Express instance
+ * - `walletReady`: a promise that resolves once the wallet is ready
+ * - `getWallet()`: async accessor for the WalletClient
+ * - `useRoutes()`: middleware + route initialization
+ * - `appReady`: promise that completes once all setup is done
+ */
+
+import * as dotenv from 'dotenv'
+import express, {
+  Express,
+  Request as ExpressRequest,
+  Response,
+  NextFunction,
+  RequestHandler
+} from 'express'
+import bodyParser from 'body-parser'
+import { preAuth, postAuth } from './routes/index.js'
+import { Logger } from './utils/logger.js'
+import sendMessageRoute from './routes/sendMessage.js'
+import { Setup } from '@bsv/wallet-toolbox'
+import knexLib, { Knex } from 'knex'
+import knexConfig from '../knexfile.js'
+import type { WalletInterface } from '@bsv/sdk'
+import { createAuthMiddleware } from '@bsv/auth-express-middleware'
+import { createPaymentMiddleware } from '@bsv/payment-express-middleware'
+import { setupSwagger } from './swagger.js'
+import { bindMessageBoxRuntime } from './runtimeDeps.js'
+import * as crypto from 'crypto'
+(global.self as any) = { crypto }
+
+dotenv.config()
+
+// Create the Express app instance
+export const app: Express = express()
+
+// Load environment variables
+const {
+  NODE_ENV = 'development',
+  ROUTING_PREFIX = '',
+  SERVER_PRIVATE_KEY,
+  WALLET_STORAGE_URL,
+  BSV_NETWORK = 'mainnet'
+} = process.env
+
+// Enable logger in dev mode or if explicitly enabled
+if (NODE_ENV === 'development' || process.env.LOGGING_ENABLED === 'true') {
+  Logger.enable()
+}
+
+/**
+ * Knex instance connected based on environment (development, production, or staging).
+ */
+export const knex: Knex = (knexLib as any).default?.(
+  NODE_ENV === 'production' || NODE_ENV === 'staging'
+    ? knexConfig.production
+    : knexConfig.development
+) ?? (knexLib as any)(
+  NODE_ENV === 'production' || NODE_ENV === 'staging'
+    ? knexConfig.production
+    : knexConfig.development
+)
+
+// Wallet initialization logic
+let _wallet: WalletInterface | undefined
+let _resolveReady: () => void
+export const walletReady = new Promise<void>((resolve) => {
+  _resolveReady = resolve
+})
+
+/**
+ * @function initializeWallet
+ * @description Initializes the WalletClient with a root identity key and storage backend.
+ *
+ * Loads configuration from the environment and connects to the wallet service.
+ *
+ * @returns {Promise<void>} Resolves when the wallet is initialized.
+ * @throws If SERVER_PRIVATE_KEY is missing or invalid.
+ */
+export async function initializeWallet (): Promise<void> {
+  if (SERVER_PRIVATE_KEY == null || SERVER_PRIVATE_KEY.trim() === '') {
+    throw new Error('SERVER_PRIVATE_KEY is not defined in environment variables.')
+  }
+
+  _wallet = await Setup.createWalletClientNoEnv({
+    chain: BSV_NETWORK === 'testnet' ? 'test' : 'main',
+    rootKeyHex: SERVER_PRIVATE_KEY,
+    storageUrl: WALLET_STORAGE_URL
+  })
+
+  bindMessageBoxRuntime({ knex, wallet: _wallet })
+  _resolveReady()
+}
+
+/**
+ * @function getWallet
+ * @description Waits for the WalletClient to be ready and returns the instance.
+ *
+ * @returns {Promise<WalletInterface>} The initialized wallet client
+ * @throws {Error} If called before the wallet is initialized
+ */
+export async function getWallet (): Promise<WalletInterface> {
+  await walletReady
+  if (_wallet == null) {
+    throw new Error('Wallet has not been initialized yet.')
+  }
+  return _wallet
+}
+
+// Run on app startup to prep wallet and activate routes
+export const appReady = (async () => {
+  await initializeWallet()
+  await useRoutes()
+})()
+
+/**
+ * @function useRoutes
+ * @description Registers all routes and middleware on the Express app instance.
+ *
+ * Steps:
+ * - Applies JSON body parser
+ * - Enables CORS headers for all routes
+ * - Waits for WalletClient to initialize
+ * - Adds authentication middleware
+ * - Mounts pre-auth and post-auth route handlers
+ *
+ * @returns {Promise<void>} Once all middleware and routes are mounted
+ * @throws If wallet is not available when needed
+ */
+export async function useRoutes (): Promise<void> {
+  // Parse incoming JSON bodies with a high limit
+  app.use(bodyParser.json({ limit: '1gb', type: 'application/json' }))
+
+  // CORS setup
+  app.use((req, res, next) => {
+    res.header('Access-Control-Allow-Origin', '*')
+    res.header('Access-Control-Allow-Headers', '*')
+    res.header('Access-Control-Allow-Methods', '*')
+    res.header('Access-Control-Expose-Headers', '*')
+    res.header('Access-Control-Allow-Private-Network', 'true')
+
+    if (req.method === 'OPTIONS') {
+      res.sendStatus(200)
+    } else {
+      next()
+    }
+  })
+
+  // Enable Swagger docs
+  setupSwagger(app)
+
+  await walletReady
+  if (_wallet == null) {
+    throw new Error('Wallet is not initialized for auth middleware')
+  }
+
+  app.use(
+    createAuthMiddleware({
+      wallet: _wallet,
+      logger: console
+    })
+  )
+
+  app.use(
+    createPaymentMiddleware({
+      wallet: _wallet,
+      calculateRequestPrice: async (req: Request) => {
+        if (req.url.includes('/sendMessage')) {
+          // TODO: Configure a custom price calculation as needed.
+        }
+        return 0
+      }
+    })
+  )
+
+  // Register pre-authentication routes (no auth required)
+  preAuth.forEach((route) => {
+    app[route.type as 'get' | 'post' | 'put' | 'delete'](
+      `${String(ROUTING_PREFIX)}${String(route.path)}`,
+      route.func as unknown as (req: ExpressRequest, res: Response, next: NextFunction) => void
+    )
+  })
+
+  // Register post-authentication routes (requires auth header)
+  postAuth.forEach((route) => {
+    if (route.path === '/sendMessage') {
+      app[route.type as 'get' | 'post' | 'put' | 'delete'](
+        `${ROUTING_PREFIX}${route.path}`,
+        sendMessageRoute.func as unknown as RequestHandler
+      )
+    } else {
+      app[route.type as 'get' | 'post' | 'put' | 'delete'](
+        `${ROUTING_PREFIX}${route.path}`,
+        route.func as RequestHandler
+      )
+    }
+  })
+}

package/src/compose.ts

@@ -0,0 +1,286 @@
+/**
+ * Composable entrypoints for embedding messagebox in a parent app.
+ * Standalone binary continues to use index.ts → app.ts as before.
+ */
+import express, {
+  type Express,
+  type Request as ExpressRequest,
+  type Response,
+  type NextFunction,
+  type RequestHandler,
+  Router
+} from 'express'
+import bodyParser from 'body-parser'
+import type { Server as HttpServer } from 'node:http'
+import { PublicKey } from '@bsv/sdk'
+import { createAuthMiddleware } from '@bsv/auth-express-middleware'
+import { createPaymentMiddleware } from '@bsv/payment-express-middleware'
+import { AuthSocketServer } from '@bsv/authsocket'
+import { preAuth, postAuth } from './routes/index.js'
+import sendMessageRoute from './routes/sendMessage.js'
+import { setupSwagger } from './swagger.js'
+import { Logger } from './utils/logger.js'
+import { bindMessageBoxRuntime } from './runtimeDeps.js'
+import type { MessageBoxContext } from './context.js'
+
+export { createMessageBoxContext } from './context.js'
+export type { MessageBoxContext, CreateMessageBoxContextOptions } from './context.js'
+
+type HttpMethod = 'get' | 'post' | 'put' | 'delete'
+
+
+export function createMessageBoxApp (): Express {
+  return express()
+}
+
+/**
+ * Mount messagebox HTTP routes on an Express app.
+ * Auth/payment middleware apply only to this router (not the parent app).
+ */
+export function mountMessageBoxRoutes (app: Express, ctx: MessageBoxContext): void {
+  bindMessageBoxRuntime({ knex: ctx.knex, wallet: ctx.wallet })
+
+  const router = Router()
+  router.use(bodyParser.json({ limit: '1gb', type: 'application/json' }))
+  router.use((req, res, next) => {
+    res.header('Access-Control-Allow-Origin', '*')
+    res.header('Access-Control-Allow-Headers', '*')
+    res.header('Access-Control-Allow-Methods', '*')
+    res.header('Access-Control-Expose-Headers', '*')
+    res.header('Access-Control-Allow-Private-Network', 'true')
+    if (req.method === 'OPTIONS') {
+      res.sendStatus(200)
+    } else {
+      next()
+    }
+  })
+
+  if (ctx.enableSwagger) {
+    setupSwagger(app)
+  }
+
+  preAuth.forEach((route) => {
+    router[route.type as HttpMethod](
+      route.path,
+      route.func as unknown as (req: ExpressRequest, res: Response, next: NextFunction) => void
+    )
+  })
+
+  router.use(
+    createAuthMiddleware({
+      wallet: ctx.wallet,
+      logger: ctx.logger
+    })
+  )
+
+  router.use(
+    createPaymentMiddleware({
+      wallet: ctx.wallet,
+      calculateRequestPrice: async (req) =>
+        await Promise.resolve(ctx.calculateRequestPrice(req as unknown as ExpressRequest))
+    })
+  )
+
+  postAuth.forEach((route) => {
+    const method = route.type as HttpMethod
+    if (route.path === '/sendMessage') {
+      router[method](route.path, sendMessageRoute.func as unknown as RequestHandler)
+    } else {
+      router[method](route.path, route.func as RequestHandler)
+    }
+  })
+
+  const prefix = ctx.routingPrefix ?? ''
+  app.use(prefix === '' ? '/' : prefix, router)
+}
+
+/**
+ * Attach authenticated WebSocket handlers. Mirrors standalone index.ts behavior
+ * with injected wallet/knex instead of module singletons.
+ */
+export function attachMessageBoxWebSockets (
+  httpServer: HttpServer,
+  ctx: MessageBoxContext
+): AuthSocketServer | null {
+  if (!ctx.enableWebSockets) {
+    return null
+  }
+
+  bindMessageBoxRuntime({ knex: ctx.knex, wallet: ctx.wallet })
+
+  Logger.log('[WEBSOCKET] Initializing WebSocket support...')
+
+  const io = new AuthSocketServer(httpServer, {
+    wallet: ctx.wallet,
+    cors: {
+      origin: '*',
+      methods: ['GET', 'POST']
+    }
+  })
+
+  const knex = ctx.knex
+  const authenticatedSockets = new Map<string, string>()
+
+  io.on('connection', (socket) => {
+    Logger.log('[WEBSOCKET] New connection established.')
+
+    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)
+        void socket.emit('authenticationSuccess', { status: 'success' })
+      } catch (error) {
+        Logger.error('[ERROR] Failed to parse WebSocket identity key:', error)
+      }
+    } else {
+      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?.identityKey != null && data.identityKey.trim().length > 0) {
+          try {
+            const parsedIdentityKey = PublicKey.fromString(data.identityKey)
+            authenticatedSockets.set(socket.id, parsedIdentityKey.toString())
+            identityKeyHandled = true
+            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' })
+        }
+      }
+      socket.on('authenticated', authListener)
+    }
+
+    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
+        }
+        try {
+          if (typeof roomId !== 'string' || roomId.trim() === '') {
+            await socket.emit('messageFailed', { reason: 'Invalid room ID' })
+            return
+          }
+          if (typeof message !== 'object' || message == null) {
+            await socket.emit('messageFailed', { reason: 'Invalid message object' })
+            return
+          }
+          if (typeof message.body !== 'string' || message.body.trim() === '') {
+            await socket.emit('messageFailed', { reason: 'Invalid message body' })
+            return
+          }
+
+          socket.emit(`sendMessageAck-${roomId}`, {
+            status: 'success',
+            messageId: message.messageId
+          }).catch((error) => {
+            Logger.error(`[WEBSOCKET ERROR] Failed to emit sendMessageAck-${roomId}:`, error)
+          })
+
+          try {
+            const parts = roomId.split('-')
+            const messageBoxType = parts.length > 1 ? parts[1] : 'default'
+
+            let messageBox = await knex('messageBox')
+              .where({ identityKey: message.recipient, type: messageBoxType })
+              .first()
+
+            if (messageBox == null) {
+              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
+            const senderKey = authenticatedSockets.get(socket.id) ?? null
+
+            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()
+          } catch (dbError) {
+            Logger.error('[WEBSOCKET ERROR] Failed to store message in DB:', dbError)
+            await socket.emit('messageFailed', { reason: 'Failed to store message' })
+            return
+          }
+
+          io.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' })
+        }
+      }
+    )
+
+    socket.on('joinRoom', async (roomId: string) => {
+      if (!authenticatedSockets.has(socket.id)) {
+        await socket.emit('joinFailed', { reason: 'Unauthorized: WebSocket not authenticated' })
+        return
+      }
+      if (typeof roomId !== 'string' || roomId.trim() === '') {
+        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)) {
+        await socket.emit('leaveFailed', { reason: 'Unauthorized: WebSocket not authenticated' })
+        return
+      }
+      if (typeof roomId !== 'string' || roomId.trim() === '') {
+        await socket.emit('leaveFailed', { reason: 'Invalid room ID' })
+        return
+      }
+      Logger.log(`[WEBSOCKET] User ${socket.id} left room ${roomId}`)
+      await socket.emit('leftRoom', { roomId })
+    })
+
+    socket.on('disconnect', (reason: string) => {
+      Logger.log(`[WEBSOCKET] Disconnected: ${reason}`)
+      authenticatedSockets.delete(socket.id)
+    })
+  })
+
+  return io
+}

package/src/config/firebase.ts

@@ -0,0 +1,183 @@
+import { initializeApp, getApps, getApp, cert, applicationDefault, type App } from 'firebase-admin/app'
+import { getMessaging, type Messaging, type Message } from 'firebase-admin/messaging'
+import { getFirestore, type Firestore } from 'firebase-admin/firestore'
+import * as path from 'path'
+import dotenv from 'dotenv'
+import { log } from '../utils/logger.js'
+
+dotenv.config()
+
+let firebaseApp: App | null = null
+
+/**
+ * Initialize Firebase Admin SDK.
+ * Returns null (and logs a warning) when ENABLE_FIREBASE is not 'true',
+ * or when FIREBASE_PROJECT_ID is absent, so the server can run without Firebase.
+ */
+export function initializeFirebase(): App | null {
+  const enableFirebase = process.env.ENABLE_FIREBASE
+
+  if (enableFirebase !== 'true') {
+    log.info({ operation: 'firebase.init', enable_firebase: enableFirebase ?? 'unset' }, 'Firebase disabled, skipping initialization')
+    return null
+  }
+
+  if (firebaseApp != null) {
+    log.info({ operation: 'firebase.init' }, 'Firebase already initialized')
+    return firebaseApp
+  }
+
+  try {
+    const serviceAccountJson = process.env.FIREBASE_SERVICE_ACCOUNT_JSON
+    const serviceAccountPath = process.env.FIREBASE_SERVICE_ACCOUNT_PATH
+    const projectId = process.env.FIREBASE_PROJECT_ID
+
+    if (projectId == null || projectId === '') {
+      throw new Error('FIREBASE_PROJECT_ID environment variable is required')
+    }
+
+    let firebaseCredential: any // Will be assigned based on auth method
+
+    if (serviceAccountJson != null && serviceAccountJson !== '') {
+      log.info({ operation: 'firebase.init', credential_source: 'env' }, 'Using Firebase service account from environment variable')
+      try {
+        log.debug({ operation: 'firebase.init', service_account_json_length: serviceAccountJson.length }, 'Service account JSON length')
+
+        // Debug credential functions
+        log.debug({ operation: 'firebase.init', cert_function_type: typeof cert }, 'cert function type')
+        log.debug({ operation: 'firebase.init', application_default_function_type: typeof applicationDefault }, 'applicationDefault function type')
+
+        const serviceAccount = JSON.parse(serviceAccountJson)
+        log.debug({ operation: 'firebase.init', service_account_keys: Object.keys(serviceAccount ?? {}) }, 'Parsed service account keys')
+
+        if (serviceAccount == null || typeof serviceAccount !== 'object') {
+          throw new Error('Parsed service account is not a valid object')
+        }
+
+        if (serviceAccount.private_key == null || serviceAccount.client_email == null || serviceAccount.project_id == null) {
+          throw new Error('Service account missing required fields (private_key, client_email, project_id)')
+        }
+
+        firebaseCredential = cert(serviceAccount)
+        log.info({ operation: 'firebase.init' }, 'Firebase credential created successfully')
+      } catch (parseError) {
+        log.error({ operation: 'firebase.init', outcome: 'error', err: parseError }, 'Firebase service account parsing failed')
+        throw new Error(`Failed to parse FIREBASE_SERVICE_ACCOUNT_JSON: ${(parseError instanceof Error) ? parseError.message : 'Invalid JSON'}`)
+      }
+    } else if (serviceAccountPath != null && serviceAccountPath !== '') {
+      log.info({ operation: 'firebase.init', credential_source: 'file' }, 'Using Firebase service account key file')
+      const absolutePath = path.resolve(process.cwd(), serviceAccountPath)
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      firebaseCredential = cert(require(absolutePath))
+    } else {
+      log.info({ operation: 'firebase.init', credential_source: 'default' }, 'Using Firebase default credentials')
+      firebaseCredential = applicationDefault()
+    }
+
+    // Check if Firebase app is already initialized
+    if (getApps().length === 0) {
+      firebaseApp = initializeApp({
+        credential: firebaseCredential,
+        projectId
+      })
+    } else {
+      firebaseApp = getApp()
+    }
+
+    log.info({ operation: 'firebase.init' }, 'Firebase Admin SDK initialized successfully')
+    return firebaseApp
+  } catch (error) {
+    log.error({ operation: 'firebase.init', outcome: 'error', err: error }, 'Firebase initialization failed')
+    throw error
+  }
+}
+
+/**
+ * Get Firebase Messaging instance, or null if Firebase is not initialized.
+ */
+export function getFirebaseMessaging(): Messaging | null {
+  if (firebaseApp == null) {
+    return null
+  }
+  return getMessaging(firebaseApp)
+}
+
+/**
+ * Get Firestore instance  
+ */
+export function getFirebaseFirestore(): Firestore {
+  if (firebaseApp == null) {
+    throw new Error(
+      'Firebase not initialized. Call initializeFirebase() first.'
+    )
+  }
+  return getFirestore(firebaseApp)
+}
+
+interface FCMPayload {
+  title: string;
+  body: string;
+  icon?: string;
+  badge?: number;
+  data?: Record<string, string>;
+}
+
+interface SendNotificationResult {
+  success: boolean;
+  messageId: string;
+}
+
+/**
+ * Send a push notification via FCM
+ */
+export async function sendNotification(
+  fcmToken: string,
+  payload: FCMPayload,
+): Promise<SendNotificationResult> {
+  try {
+    const messaging = getFirebaseMessaging()
+
+    if (messaging == null) {
+      throw new Error('Firebase Messaging is not initialized (ENABLE_FIREBASE != true)')
+    }
+
+    const message: Message = {
+      token: fcmToken,
+      notification: {
+        title: payload.title,
+        body: payload.body,
+        ...(payload.icon && { imageUrl: payload.icon }),
+      },
+      data: payload.data || {},
+      android: {
+        priority: "high",
+        notification: {
+          clickAction: "OPEN_ACTIVITY_1",
+          ...(payload.badge && { notificationCount: payload.badge }),
+        },
+      },
+      apns: {
+        headers: {
+          "apns-priority": "10",
+        },
+        payload: {
+          aps: {
+            alert: {
+              title: payload.title,
+              body: payload.body,
+            },
+            sound: "default",
+            badge: payload.badge || 1,
+          },
+        },
+      },
+    };
+
+    const response = await messaging.send(message);
+    log.info({ operation: 'firebase.send_notification', message_id: response }, 'Notification sent successfully')
+    return { success: true, messageId: response };
+  } catch (error) {
+    log.error({ operation: 'firebase.send_notification', outcome: 'error', err: error }, 'Failed to send notification')
+    throw error;
+  }
+}