@bopen-io/messagebox-server 1.1.5 → 1.2.1

package/src/runtimeDeps.ts

@@ -0,0 +1,29 @@
+/**
+ * Injectable knex/wallet for route handlers.
+ * Binary entry and mountMessageBoxRoutes call bindMessageBoxRuntime before serving.
+ */
+import type { Knex } from 'knex'
+import type { WalletInterface } from '@bsv/sdk'
+
+/** Bound before serving; routes read knex/wallet from here. */
+export const runtimeDeps: {
+  knex: Knex
+  wallet?: WalletInterface
+} = {
+  knex: null as unknown as Knex
+}
+
+export function bindMessageBoxRuntime (deps: {
+  knex: Knex
+  wallet?: WalletInterface
+}): void {
+  runtimeDeps.knex = deps.knex
+  runtimeDeps.wallet = deps.wallet
+}
+
+export async function getWallet (): Promise<WalletInterface> {
+  if (runtimeDeps.wallet == null) {
+    throw new Error('Wallet is not initialized')
+  }
+  return runtimeDeps.wallet
+}

package/src/swagger.ts

@@ -0,0 +1,54 @@
+import swaggerJsdoc from 'swagger-jsdoc'
+import swaggerUi from 'swagger-ui-express'
+import { Express } from 'express'
+
+export function setupSwagger (app: Express): void {
+  const options = {
+    definition: {
+      openapi: '3.0.0',
+      info: {
+        title: 'MessageBox Server API',
+        version: '1.0.0',
+        description: 'API documentation for the MessageBox Server, including message delivery, retrieval, acknowledgment, and overlay routing.'
+      },
+      servers: [
+        {
+          url: 'http://localhost:5001',
+          description: 'Local Development Server'
+        },
+        {
+          url: 'https://messagebox.babbage.systems',
+          description: 'Production MessageBox Server'
+        }
+      ],
+      components: {
+        securitySchemes: {
+          BearerAuth: {
+            type: 'http',
+            scheme: 'bearer',
+            bearerFormat: 'JWT',
+            description: 'Provide your signed identity key JWT in the `Authorization` header as: `Bearer <token>`'
+          }
+        }
+      },
+      security: [
+        {
+          BearerAuth: []
+        }
+      ]
+    },
+    apis: ['./src/routes/*.ts']
+  }
+
+  const swaggerSpec = swaggerJsdoc(options)
+
+  // Swagger UI at /docs — cast needed for @types/swagger-ui-express v4 + @types/express v5 compat
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ;(app as any).use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec))
+
+  // Serve raw OpenAPI spec at /openapi.json
+  app.get('/openapi.json', (_req, res) => {
+    res.setHeader('Content-Type', 'application/json')
+    res.send(swaggerSpec)
+  })
+}

package/src/telemetry.ts

@@ -0,0 +1,158 @@
+/**
+ * OpenTelemetry bootstrap (ESM) — preloaded before app code via
+ * `node --import ./out/src/telemetry.js`.
+ *
+ * Emits traces, metrics and logs. All wiring is driven by OTEL_* env vars; when
+ * OTEL_EXPORTER_OTLP_ENDPOINT is unset we fall back to console exporters so the
+ * process always boots (dev-safe). Runtime (heap/GC/event-loop) metrics are
+ * enabled to support memory-leak diagnosis.
+ *
+ * ESM note: we deliberately do NOT register the import-in-the-middle loader
+ * hook (@opentelemetry/instrumentation/hook.mjs). That hook rebuilds the named
+ * exports of CJS packages imported as ESM and drops some of them (e.g.
+ * @bsv/sdk's PushDrop), which crashes the app at import time. The libraries we
+ * actually instrument (http, express, mongodb, mysql2, pino) are pulled in
+ * through CJS dependency chains (overlay-express, wallet-toolbox, authsocket)
+ * and are still patched by require-in-the-middle, so coverage is retained.
+ *
+ * See docs/superpowers/specs/2026-06-22-infra-opentelemetry-design.md.
+ */
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+
+import { NodeSDK } from '@opentelemetry/sdk-node'
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'
+import { RuntimeNodeInstrumentation } from '@opentelemetry/instrumentation-runtime-node'
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
+import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http'
+import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http'
+import {
+    ConsoleSpanExporter,
+    BatchSpanProcessor,
+    SimpleSpanProcessor,
+    type SpanExporter,
+} from '@opentelemetry/sdk-trace-base'
+import {
+    PeriodicExportingMetricReader,
+    ConsoleMetricExporter,
+    type PushMetricExporter,
+} from '@opentelemetry/sdk-metrics'
+import {
+    BatchLogRecordProcessor,
+    SimpleLogRecordProcessor,
+    ConsoleLogRecordExporter,
+    type LogRecordExporter,
+} from '@opentelemetry/sdk-logs'
+import { resourceFromAttributes } from '@opentelemetry/resources'
+import {
+    ATTR_SERVICE_NAME,
+    ATTR_SERVICE_VERSION,
+} from '@opentelemetry/semantic-conventions'
+import { logs, SeverityNumber } from '@opentelemetry/api-logs'
+import { diag, DiagConsoleLogger, DiagLogLevel } from '@opentelemetry/api'
+
+// Resolve the component's package.json relative to the working directory (the
+// app root in every Dockerfile and local run) — robust regardless of build layout.
+const require = createRequire(import.meta.url)
+const pkg = require(join(process.cwd(), 'package.json')) as { name: string; version: string }
+
+const otlpEndpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT
+const useOtlp = typeof otlpEndpoint === 'string' && otlpEndpoint.length > 0
+const env = process.env.DEPLOY_ENV ?? process.env.NODE_ENV ?? 'development'
+
+if (process.env.OTEL_DIAG === 'true') {
+    diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.INFO)
+}
+
+const resource = resourceFromAttributes({
+    [ATTR_SERVICE_NAME]: process.env.OTEL_SERVICE_NAME ?? pkg.name,
+    [ATTR_SERVICE_VERSION]: pkg.version,
+    'deployment.environment': env,
+})
+
+const traceExporter: SpanExporter = useOtlp
+    ? new OTLPTraceExporter()
+    : new ConsoleSpanExporter()
+const metricExporter: PushMetricExporter = useOtlp
+    ? new OTLPMetricExporter()
+    : new ConsoleMetricExporter()
+const logExporter: LogRecordExporter = useOtlp
+    ? new OTLPLogExporter()
+    : new ConsoleLogRecordExporter()
+
+const logRecordProcessor = useOtlp
+    ? new BatchLogRecordProcessor(logExporter)
+    : new SimpleLogRecordProcessor(logExporter)
+
+const sdk = new NodeSDK({
+    resource,
+    spanProcessors: [
+        useOtlp
+            ? new BatchSpanProcessor(traceExporter)
+            : new SimpleSpanProcessor(traceExporter),
+    ],
+    metricReader: new PeriodicExportingMetricReader({
+        exporter: metricExporter,
+        exportIntervalMillis: Number(process.env.OTEL_METRIC_EXPORT_INTERVAL ?? 60000),
+    }),
+    logRecordProcessors: [logRecordProcessor],
+    instrumentations: [
+        getNodeAutoInstrumentations({
+            '@opentelemetry/instrumentation-fs': { enabled: false },
+        }),
+        new RuntimeNodeInstrumentation(),
+    ],
+})
+
+sdk.start()
+
+// Capture clean console refs before patching, for telemetry's own messages.
+const rawInfo = console.info.bind(console)
+const rawError = console.error.bind(console)
+
+// Bridge stray console.* calls into OTel logs so nothing is lost while code is
+// migrated to the structured (pino) logger.
+const logger = logs.getLogger(pkg.name, pkg.version)
+const SEVERITY: Record<string, SeverityNumber> = {
+    debug: SeverityNumber.DEBUG,
+    info: SeverityNumber.INFO,
+    log: SeverityNumber.INFO,
+    warn: SeverityNumber.WARN,
+    error: SeverityNumber.ERROR,
+}
+for (const method of ['debug', 'info', 'log', 'warn', 'error'] as const) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const original = (console as any)[method].bind(console)
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ;(console as any)[method] = (...args: any[]) => {
+        try {
+            logger.emit({
+                severityNumber: SEVERITY[method],
+                severityText: method.toUpperCase(),
+                body: args
+                    .map((a) =>
+                        typeof a === 'string' ? a : (() => {
+                            try { return JSON.stringify(a) } catch { return String(a) }
+                        })()
+                    )
+                    .join(' '),
+            })
+        } catch {
+            /* never let telemetry break logging */
+        }
+        original(...args)
+    }
+}
+
+// Flush telemetry on shutdown. Only force-exit if the app registered no handler
+// of its own for this signal — otherwise we let the app's shutdown drive exit.
+const shutdown = (signal: NodeJS.Signals) => {
+    sdk.shutdown()
+        .then(() => rawInfo(`[otel] flushed (${signal})`))
+        .catch((err: unknown) => rawError('[otel] shutdown error', err))
+        .finally(() => {
+            if (process.listeners(signal).length <= 1) process.exit(0)
+        })
+}
+process.on('SIGTERM', () => shutdown('SIGTERM'))
+process.on('SIGINT', () => shutdown('SIGINT'))

package/src/types/messagePermissions.ts

@@ -0,0 +1,18 @@
+import { PubKeyHex } from '@bsv/sdk'
+
+// Generalized message permission for any box/sender combination
+export interface MessagePermission {
+  id: number
+  recipient: PubKeyHex // identityKey of permission owner
+  sender: PubKeyHex | null // identityKey of sender (null for box-wide defaults)
+  message_box: string // messageBox type (e.g., 'notifications', 'inbox', etc.)
+  recipient_fee: number // -1 = block, 0 = free, >0 = satoshi amount required
+  created_at: Date
+  updated_at: Date
+}
+
+// Fee calculation result
+export interface FeeCalculationResult {
+  deliveryFee: number
+  recipientFee: number
+}

package/src/types/mock-knex.d.ts

@@ -0,0 +1,18 @@
+declare module 'mock-knex' {
+  import { Knex } from 'knex'
+
+  export interface Tracker {
+    install: () => void
+    uninstall: () => void
+    on: (event: 'query', callback: (query: any, step: number) => void) => void
+  }
+
+  export interface MockKnex {
+    mock: (db: Knex) => void
+    unmock: (db: Knex) => void
+    getTracker: () => Tracker
+  }
+
+  const mockKnex: MockKnex
+  export default mockKnex
+}

package/src/types/notifications.ts

@@ -0,0 +1,27 @@
+import { PubKeyHex } from '@bsv/sdk'
+
+// TODO: Determine payload structure for notifications
+export interface EncryptedNotificationPayload {
+  title?: string // Optional unencrypted title for display
+}
+
+// Optional payment structure
+export interface NotificationPayment {
+  amount: number // Satoshis
+  recipient: PubKeyHex
+  // TODO: Add more payment fields as needed for internalizeAction
+}
+
+// FCM configuration interface (adapted from Jackie's code)
+export interface FCMPayload {
+  title: string
+  body: string
+  icon?: string
+  badge?: number
+  data?: Record<string, string>
+}
+
+export interface SendNotificationResult {
+  success: boolean
+  messageId: string
+}

package/src/utils/logger.ts

@@ -0,0 +1,92 @@
+import pino from 'pino'
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+
+const require = createRequire(import.meta.url)
+const pkg = require(join(process.cwd(), 'package.json')) as { name: string; version: string }
+
+// Structured pino logger. @opentelemetry/instrumentation-pino (loaded by
+// telemetry.ts) injects trace_id/span_id into every record, and records are
+// shipped to the OTLP logs endpoint. Stable base fields: service, env.
+const pinoLogger = pino({
+  name: pkg.name,
+  level: process.env.LOG_LEVEL ?? 'info',
+  base: {
+    service: process.env.OTEL_SERVICE_NAME ?? pkg.name,
+    env: process.env.DEPLOY_ENV ?? process.env.NODE_ENV ?? 'development',
+  },
+  // Scrub PII / credentials before records leave the process. on-chain data
+  // (identity_key, txid) is public and intentionally NOT redacted.
+  redact: {
+    paths: [
+      'phone', 'phoneNumber', 'identifier',
+      'presentation_key', 'presentationKey', 'payload', 'store',
+      'password', 'pass', 'secret', 'privateKey', 'private_key',
+      'authorization', 'token', 'access_token',
+      '*.phone', '*.phoneNumber', '*.identifier', '*.authorization',
+    ],
+    censor: '[redacted]',
+  },
+  formatters: {
+    level: (label) => ({ level: label }),
+  },
+})
+
+// Export the raw pino logger for call sites that want structured fields:
+//   log.info({ operation: 'send', room_id }, 'message delivered')
+export const log = pinoLogger
+
+// Split variadic args into a message string + structured detail object so legacy
+// Logger.log('text', value) calls still produce useful structured records.
+function emit(level: 'info' | 'warn' | 'error', args: unknown[]): void {
+  const strings: string[] = []
+  const details: unknown[] = []
+  for (const a of args) {
+    if (typeof a === 'string' || typeof a === 'number' || typeof a === 'boolean') {
+      strings.push(String(a))
+    } else {
+      details.push(a)
+    }
+  }
+  const msg = strings.join(' ')
+  if (details.length > 0) {
+    pinoLogger[level]({ detail: details.length === 1 ? details[0] : details }, msg)
+  } else {
+    pinoLogger[level](msg)
+  }
+}
+
+/**
+ * Backwards-compatible static facade over the structured logger. Existing
+ * Logger.log/warn/error call sites keep working but now emit structured,
+ * trace-correlated records. `enable`/`disable` toggle info/warn verbosity;
+ * errors are always emitted.
+ */
+// eslint-disable-next-line @typescript-eslint/no-extraneous-class
+export class Logger {
+  private static isEnabled = false
+
+  static enable(): void {
+    this.isEnabled = true
+  }
+
+  static disable(): void {
+    this.isEnabled = false
+  }
+
+  static log(...args: unknown[]): void {
+    if (this.isEnabled) {
+      emit('info', args)
+    }
+  }
+
+  static warn(...args: unknown[]): void {
+    if (this.isEnabled) {
+      emit('warn', args)
+    }
+  }
+
+  static error(...args: unknown[]): void {
+    emit('error', args)
+  }
+}

package/src/utils/messagePermissions.ts

@@ -0,0 +1,148 @@
+import { Logger } from './logger.js'
+import { PubKeyHex } from '@bsv/sdk'
+import { runtimeDeps } from '../runtimeDeps.js'
+
+/**
+ * Fee calculation result structure
+ */
+export interface FeeCalculationResult {
+  delivery_fee: number
+  recipient_fee: number
+  total_cost: number
+  allowed: boolean
+  requires_payment: boolean
+  blocked_reason?: string
+}
+
+/**
+ * Get server delivery fee for a message box type
+ */
+export async function getServerDeliveryFee(messageBox: string): Promise<number> {
+  try {
+    const serverFee = await runtimeDeps.knex('server_fees')
+      .where({ message_box: messageBox })
+      .select('delivery_fee')
+      .first()
+
+    return serverFee?.delivery_fee ?? 0
+  } catch (error) {
+    Logger.error('[ERROR] Error getting server delivery fee:', error)
+    return 0
+  }
+}
+
+/**
+ * Get recipient fee for a sender/messageBox combination with hierarchical fallback
+ */
+export async function getRecipientFee(
+  recipient: PubKeyHex,
+  sender: PubKeyHex | null,
+  messageBox: string
+): Promise<number> {
+  try {
+    // Debug parameter types
+    Logger.log(`[DEBUG] getRecipientFee params - recipient: ${typeof recipient} (${JSON.stringify(recipient)}), sender: ${typeof sender} (${JSON.stringify(sender)}), messageBox: ${typeof messageBox} (${JSON.stringify(messageBox)})`)
+
+    // First try sender-specific permission
+    if (sender != null) {
+      const senderSpecific = await runtimeDeps.knex('message_permissions')
+        .where({
+          recipient: String(recipient),
+          sender: String(sender),
+          message_box: String(messageBox)
+        })
+        .select('recipient_fee')
+        .first()
+
+      if (senderSpecific != null) {
+        return senderSpecific.recipient_fee
+      }
+    }
+
+    // Fallback to box-wide default
+    const boxWideDefault = await runtimeDeps.knex('message_permissions')
+      .where({
+        recipient: String(recipient),
+        sender: null, // Box-wide default
+        message_box: String(messageBox)
+      })
+      .select('recipient_fee')
+      .first()
+
+    if (boxWideDefault != null) {
+      return boxWideDefault.recipient_fee
+    }
+
+    // Auto-create box-wide default if none exists
+    const defaultFee = getSmartDefaultFee(String(messageBox))
+    await runtimeDeps.knex('message_permissions').insert({
+      recipient: String(recipient),
+      sender: null,
+      message_box: String(messageBox),
+      recipient_fee: defaultFee,
+      created_at: new Date(),
+      updated_at: new Date()
+    })
+
+    Logger.log(`[DEBUG] Created box-wide default permission for ${recipient}/${messageBox} with fee ${defaultFee}`)
+    return defaultFee
+  } catch (error) {
+    Logger.error('[ERROR] Error getting recipient fee:', error)
+    return 0 // Block on error
+  }
+}
+
+/**
+ * Get smart default fee based on message box type
+ */
+function getSmartDefaultFee(messageBox: string): number {
+  // Notifications are premium service
+  if (messageBox === 'notifications') {
+    return 10 // 10 satoshis
+  }
+
+  // Other message boxes are always allowed by default
+  return 0
+}
+
+/**
+ * Set message permission for a sender/recipient/messageBox combination
+ */
+export async function setMessagePermission(
+  recipient: PubKeyHex,
+  sender: PubKeyHex | null,
+  messageBox: string,
+  recipientFee: number
+): Promise<boolean> {
+  try {
+    const now = new Date()
+
+    // Use upsert (insert or update)
+    await runtimeDeps.knex('message_permissions')
+      .insert({
+        recipient,
+        sender,
+        message_box: messageBox,
+        recipient_fee: recipientFee,
+        created_at: now,
+        updated_at: now
+      })
+      .onConflict(['recipient', 'sender', 'message_box'])
+      .merge({
+        recipient_fee: recipientFee,
+        updated_at: now
+      })
+
+    return true
+  } catch (error) {
+    Logger.error('[ERROR] Error setting message permission:', error)
+    return false
+  }
+}
+
+/**
+ * Check if FCM delivery should be used for this message box
+ */
+export function shouldUseFCMDelivery(messageBox: string): boolean {
+  return messageBox === 'notifications'
+}

package/src/utils/sendFCMNotification.ts

@@ -0,0 +1,143 @@
+import { getFirebaseMessaging } from '../config/firebase.js'
+import { Logger } from './logger.js'
+import { PubKeyHex } from '@bsv/sdk'
+import { runtimeDeps } from '../runtimeDeps.js'
+
+/**
+ * FCM Payload interface
+ */
+export interface FCMPayload {
+  title: string
+  messageId: string
+  originator?: string
+}
+
+/**
+ * FCM notification result
+ */
+export interface SendNotificationResult {
+  success: boolean
+  error?: string
+}
+
+/**
+ * Send FCM push notification to all registered devices for a recipient
+ * Looks up FCM tokens from device_registrations table and sends to all active devices
+ */
+export async function sendFCMNotification(
+  recipient: PubKeyHex,
+  payload: FCMPayload
+): Promise<SendNotificationResult> {
+  try {
+    Logger.log(`[DEBUG] Attempting to send FCM notification to ${recipient}`)
+    Logger.log('[DEBUG] Payload:', payload)
+
+    // Look up all active FCM tokens for this recipient
+    const deviceRegistrations = await runtimeDeps.knex('device_registrations')
+      .where({
+        identity_key: recipient,
+        active: true
+      })
+      .select('fcm_token', 'platform', 'device_id')
+
+    if (deviceRegistrations.length === 0) {
+      Logger.log(`[DEBUG] No active FCM tokens found for recipient ${recipient}`)
+      return { success: false, error: 'No registered devices found for recipient' }
+    }
+
+    Logger.log(`[DEBUG] Found ${deviceRegistrations.length} active device(s) for ${recipient}`)
+
+    // Send notification to all registered devices
+    const sendPromises = deviceRegistrations.map(async (device) => {
+      try {
+        Logger.log(`[DEBUG] Sending to ${device.platform ?? 'unknown'} device: ${device.device_id ?? 'unknown'}`)
+
+        const messaging = getFirebaseMessaging()
+        if (messaging == null) {
+          return { success: false, token: device.fcm_token, error: 'Firebase Messaging not initialized (ENABLE_FIREBASE != true)' }
+        }
+
+        await messaging.send({
+          token: device.fcm_token,
+          notification: {
+            title: payload.title,
+            body: payload.messageId
+          },
+          // Android configuration for headless service
+          android: {
+            priority: 'high',
+            data: {
+              messageId: payload.messageId,
+              originator: payload.originator || 'unknown'
+            }
+          },
+          // iOS configuration for mutable content and Notification Service Extension
+          apns: {
+            headers: {
+              'apns-push-type': 'alert', // required for iOS 13+
+              'apns-priority': '10',     // deliver immediately
+              // optional: 'apns-topic': '<your app bundle id>'  // FCM fills this automatically
+            },
+            payload: {
+              aps: {
+                'mutable-content': 1,
+                alert: {                 // include an alert so NSE can modify it
+                  title: payload.title,
+                  body: payload.messageId,
+                },
+                // do NOT set 'content-available': 1 unless you also want background fetch
+              },
+              // custom keys your NSE can read:
+              messageId: payload.messageId,
+              originator: payload.originator ?? 'unknown',
+            },
+          },
+        })
+
+        // Update last_used timestamp on successful send
+        await runtimeDeps.knex('device_registrations')
+          .where('fcm_token', device.fcm_token)
+          .update({
+            last_used: new Date(),
+            updated_at: new Date()
+          })
+
+        return { success: true, token: device.fcm_token }
+      } catch (error) {
+        Logger.error(`[FCM ERROR] Failed to send to token ${device.fcm_token.slice(-10)}:`, error)
+
+        // Mark token as inactive if it's invalid
+        if (error instanceof Error && (
+          error.message.includes('registration-token-not-registered') ||
+          error.message.includes('invalid-registration-token')
+        )) {
+          Logger.log(`[DEBUG] Marking invalid token as inactive: ...${device.fcm_token.slice(-10)}`)
+          await runtimeDeps.knex('device_registrations')
+            .where('fcm_token', device.fcm_token)
+            .update({
+              active: false,
+              updated_at: new Date()
+            })
+        }
+
+        return { success: false, token: device.fcm_token, error: error instanceof Error ? error.message : String(error) }
+      }
+    })
+
+    const results = await Promise.all(sendPromises)
+    const successCount = results.filter(r => r.success).length
+    const failureCount = results.length - successCount
+
+    Logger.log(`[DEBUG] FCM notification results: ${successCount} successful, ${failureCount} failed`)
+
+    // Consider it successful if at least one device received the notification
+    if (successCount > 0) {
+      return { success: true }
+    } else {
+      return { success: false, error: `Failed to send to all ${results.length} registered devices` }
+    }
+  } catch (error) {
+    Logger.error('[FCM ERROR] Failed to send FCM notification:', error)
+    return { success: false, error: error instanceof Error ? error.message : String(error) }
+  }
+}