@sip-protocol/api 0.1.0 → 0.1.1

package/src/routes/webhook.ts

@@ -0,0 +1,156 @@
+/**
+ * Webhook Routes
+ *
+ * CRUD for agent webhook registrations + Helius ingest endpoint.
+ *
+ * POST   /webhooks/register     — Register a webhook
+ * DELETE /webhooks/:id          — Unregister a webhook
+ * GET    /webhooks              — List registered webhooks
+ * POST   /internal/helius       — Helius webhook callback (no API key auth)
+ */
+
+import { Router, Request, Response } from 'express'
+import { z } from 'zod'
+import { validateRequest } from '../middleware'
+import { webhookStore } from '../stores/webhook-store'
+import { heliusListenerService } from '../services/helius-listener'
+import type {
+  ApiResponse,
+  RegisterWebhookResponse,
+  WebhookListItem,
+} from '../types/api'
+
+const router: Router = Router()
+
+/**
+ * Validation schemas for webhook endpoints
+ */
+const webhookSchemas = {
+  register: z.object({
+    url: z.string().url('Must be a valid URL'),
+    viewingPrivateKey: z
+      .string()
+      .regex(/^0x[0-9a-fA-F]{64}$/, 'Must be 0x-prefixed 32-byte hex'),
+    spendingPublicKey: z
+      .string()
+      .regex(/^0x[0-9a-fA-F]{64}$/, 'Must be 0x-prefixed 32-byte hex'),
+  }),
+
+  unregister: z.object({
+    id: z.string().min(1),
+  }),
+}
+
+/**
+ * POST /webhooks/register
+ * Register a webhook to receive payment notifications
+ */
+router.post(
+  '/register',
+  validateRequest({ body: webhookSchemas.register }),
+  (req: Request, res: Response) => {
+    const { url, viewingPrivateKey, spendingPublicKey } = req.body
+
+    try {
+      const registration = webhookStore.register(url, viewingPrivateKey, spendingPublicKey)
+
+      const response: ApiResponse<RegisterWebhookResponse> = {
+        success: true,
+        data: {
+          id: registration.id,
+          url: registration.url,
+          secret: registration.secret,
+          createdAt: registration.createdAt,
+        },
+      }
+
+      res.status(201).json(response)
+    } catch (error) {
+      if ((error as Error).message === 'WEBHOOK_STORE_FULL') {
+        res.status(503).json({
+          success: false,
+          error: {
+            code: 'WEBHOOK_STORE_FULL',
+            message: 'Maximum webhook registrations reached',
+          },
+        })
+        return
+      }
+      throw error
+    }
+  }
+)
+
+/**
+ * DELETE /webhooks/:id
+ * Unregister a webhook
+ */
+router.delete(
+  '/:id',
+  validateRequest({ params: webhookSchemas.unregister }),
+  (req: Request, res: Response) => {
+    const removed = webhookStore.unregister(req.params.id as string)
+
+    if (!removed) {
+      res.status(404).json({
+        success: false,
+        error: {
+          code: 'WEBHOOK_NOT_FOUND',
+          message: 'Webhook not found',
+        },
+      })
+      return
+    }
+
+    res.status(204).send()
+  }
+)
+
+/**
+ * GET /webhooks
+ * List all registered webhooks (never exposes keys or secret)
+ */
+router.get('/', (_req: Request, res: Response) => {
+  const webhooks = webhookStore.getAllForList()
+
+  const response: ApiResponse<{ webhooks: WebhookListItem[] }> = {
+    success: true,
+    data: { webhooks },
+  }
+
+  res.json(response)
+})
+
+/**
+ * POST /internal/helius
+ * Helius webhook callback endpoint
+ *
+ * Authentication: Helius HMAC signature (not API key).
+ * This path is added to AUTH_SKIP_PATHS in server.ts.
+ * Returns 200 immediately to Helius; processing is async.
+ */
+router.post('/internal/helius', async (req: Request, res: Response) => {
+  const headers = {
+    signature: req.headers['x-helius-signature'] as string | undefined,
+    rawBody: typeof req.body === 'string' ? req.body : JSON.stringify(req.body),
+  }
+
+  try {
+    const matchCount = await heliusListenerService.processIncoming(req.body, headers)
+    res.status(200).json({ success: true, matched: matchCount })
+  } catch (error) {
+    if ((error as Error).message === 'HELIUS_SIGNATURE_INVALID') {
+      res.status(401).json({
+        success: false,
+        error: {
+          code: 'HELIUS_SIGNATURE_INVALID',
+          message: 'Invalid Helius webhook signature',
+        },
+      })
+      return
+    }
+    throw error
+  }
+})
+
+export default router

package/src/server.ts

@@ -1,24 +1,79 @@
+/**
+ * SIP Protocol REST API Server
+ *
+ * Production-ready Express server with:
+ * - Structured logging (pino)
+ * - Environment validation (envalid)
+ * - Graceful shutdown handling
+ * - Security middleware (helmet, CORS, rate limiting)
+ * - Request authentication
+ * - Error monitoring (Sentry)
+ * - Metrics collection (Prometheus)
+ */
+
 import express, { Express } from 'express'
-import cors from 'cors'
 import helmet from 'helmet'
 import compression from 'compression'
-import morgan from 'morgan'
 import router from './routes'
-import { errorHandler, notFoundHandler } from './middleware'
+import metricsRouter from './routes/metrics'
+import { env, logConfigWarnings } from './config'
+import { logger, requestLogger } from './logger'
+import { setupGracefulShutdown, shutdownMiddleware, isServerShuttingDown } from './shutdown'
+import {
+  errorHandler,
+  notFoundHandler,
+  secureCors,
+  rateLimiter,
+  authenticate,
+  isAuthEnabled,
+  getCorsConfig,
+  requestIdMiddleware,
+} from './middleware'
+import {
+  initSentry,
+  setupSentryErrorHandler,
+  flushSentry,
+  isSentryEnabled,
+  metricsMiddleware,
+} from './monitoring'
+import { webhookDeliveryService } from './services/webhook-delivery'
+
+// Initialize Sentry early (before Express)
+initSentry()
 
 const app: Express = express()
 
-// Environment configuration
-const PORT = process.env.PORT || 3000
-const NODE_ENV = process.env.NODE_ENV || 'development'
-const CORS_ORIGIN = process.env.CORS_ORIGIN || '*'
+// Trust proxy configuration for X-Forwarded-For header
+// SECURITY: Required for rate limiting to work behind reverse proxy (nginx, Cloudflare, etc.)
+// Without this, rate limiting is trivially bypassable via X-Forwarded-For spoofing
+const trustProxy = env.TRUST_PROXY
+if (trustProxy !== 'false') {
+  // Parse as number if it looks like a number, otherwise use as string
+  const parsedValue = /^\d+$/.test(trustProxy) ? parseInt(trustProxy, 10) : trustProxy
+  app.set('trust proxy', parsedValue)
+  logger.info({ trustProxy: parsedValue }, 'Proxy trust configured')
+}
+
+// Metrics middleware (early to capture all requests)
+if (env.METRICS_ENABLED === 'true') {
+  app.use(metricsMiddleware)
+}
+
+// Shutdown middleware (early to reject during shutdown)
+app.use(shutdownMiddleware)
+
+// Request ID middleware (early for correlation)
+app.use(requestIdMiddleware)
 
 // Security middleware
 app.use(helmet())
-app.use(cors({
-  origin: CORS_ORIGIN,
-  credentials: true,
-}))
+app.use(secureCors)
+
+// Rate limiting (before auth to prevent brute force)
+app.use(rateLimiter)
+
+// Authentication
+app.use(authenticate)
 
 // Body parsing middleware
 app.use(express.json({ limit: '1mb' }))
@@ -27,14 +82,20 @@ app.use(express.urlencoded({ extended: true, limit: '1mb' }))
 // Compression middleware
 app.use(compression())
 
-// Logging middleware
-app.use(morgan(NODE_ENV === 'development' ? 'dev' : 'combined'))
+// Request logging (replaces morgan)
+app.use(requestLogger)
 
 // API routes
 app.use('/api/v1', router)
 
+// Metrics endpoint (no auth required for Prometheus scraping)
+if (env.METRICS_ENABLED === 'true') {
+  app.use('/metrics', metricsRouter)
+}
+
 // Root endpoint
 app.get('/', (req, res) => {
+  const corsConfig = getCorsConfig()
   res.json({
     name: '@sip-protocol/api',
     version: '0.1.0',
@@ -48,6 +109,18 @@ app.get('/', (req, res) => {
       quote: 'POST /api/v1/quote',
       swap: 'POST /api/v1/swap',
       swapStatus: 'GET /api/v1/swap/:id/status',
+      webhookRegister: 'POST /api/v1/webhooks/register',
+      webhookUnregister: 'DELETE /api/v1/webhooks/:id',
+      webhookList: 'GET /api/v1/webhooks',
+      heliusIngest: 'POST /api/v1/webhooks/internal/helius',
+    },
+    security: {
+      authentication: isAuthEnabled() ? 'enabled' : 'disabled',
+      cors: {
+        origins: corsConfig.origins.length > 0 ? corsConfig.origins.length + ' configured' : 'none (blocked)',
+        credentials: corsConfig.credentials,
+      },
+      rateLimit: 'enabled',
     },
   })
 })
@@ -55,22 +128,72 @@ app.get('/', (req, res) => {
 // 404 handler
 app.use(notFoundHandler)
 
+// Sentry error handler (uses Sentry v10 auto-instrumentation)
+setupSentryErrorHandler(app)
+
 // Error handler (must be last)
 app.use(errorHandler)
 
 // Start server
 if (require.main === module) {
-  app.listen(PORT, () => {
-    console.log(`
+  // Log configuration warnings
+  logConfigWarnings(logger)
+
+  const corsConfig = getCorsConfig()
+  const server = app.listen(env.PORT, () => {
+    logger.info({
+      port: env.PORT,
+      environment: env.NODE_ENV,
+      auth: isAuthEnabled() ? 'enabled' : 'disabled',
+      corsOrigins: corsConfig.origins.length,
+      logLevel: env.LOG_LEVEL,
+      sentry: isSentryEnabled() ? 'enabled' : 'disabled',
+      metrics: env.METRICS_ENABLED === 'true' ? 'enabled' : 'disabled',
+    }, 'SIP Protocol API started')
+
+    // Pretty banner in development
+    if (env.isDevelopment) {
+      console.log(`
 ╔════════════════════════════════════════════════════╗
 ║  SIP Protocol REST API                             ║
 ║  Version: 0.1.0                                    ║
-║  Port: ${PORT}                                         ║
-║  Environment: ${NODE_ENV}                              ║
-║  Documentation: http://localhost:${PORT}/              ║
+╠════════════════════════════════════════════════════╣
+║  Port: ${String(env.PORT).padEnd(43)}║
+║  Environment: ${env.NODE_ENV.padEnd(37)}║
+╠════════════════════════════════════════════════════╣
+║  Security:                                         ║
+║  • Auth: ${(isAuthEnabled() ? 'ENABLED' : 'disabled (dev mode)').padEnd(42)}║
+║  • CORS: ${(corsConfig.origins.length + ' origins').padEnd(42)}║
+║  • Rate Limit: enabled                             ║
+╠════════════════════════════════════════════════════╣
+║  Monitoring:                                       ║
+║  • Sentry: ${(isSentryEnabled() ? 'ENABLED' : 'disabled').padEnd(40)}║
+║  • Metrics: ${(env.METRICS_ENABLED === 'true' ? '/metrics' : 'disabled').padEnd(39)}║
+╠════════════════════════════════════════════════════╣
+║  Logging: ${env.LOG_LEVEL.padEnd(41)}║
+╠════════════════════════════════════════════════════╣
+║  Documentation: http://localhost:${String(env.PORT).padEnd(17)}║
 ╚════════════════════════════════════════════════════╝
-    `)
+      `)
+    }
+  })
+
+  // Setup graceful shutdown
+  setupGracefulShutdown(server, async () => {
+    // Drain pending webhook deliveries
+    logger.info('Draining webhook deliveries...')
+    await webhookDeliveryService.drainPending()
+
+    // Flush Sentry events before shutdown
+    if (isSentryEnabled()) {
+      logger.info('Flushing Sentry events...')
+      await flushSentry(2000)
+    }
+    logger.info('Flushing logs...')
+    // pino handles its own flushing on process exit
   })
 }
 
+// Export for testing
 export default app
+export { isServerShuttingDown }

package/src/services/helius-listener.ts

@@ -0,0 +1,104 @@
+/**
+ * Helius Webhook Listener Service
+ *
+ * Ingests raw Helius webhook payloads and fans out to registered
+ * agent webhooks. For each active registration, checks if the
+ * transaction contains a stealth payment for that agent.
+ *
+ * Uses the SDK's processWebhookTransaction() for payment detection
+ * and verifyWebhookSignature() for Helius signature verification.
+ */
+
+import {
+  processWebhookTransaction,
+  verifyWebhookSignature,
+} from '@sip-protocol/sdk'
+import type { HeliusWebhookTransaction } from '@sip-protocol/sdk'
+import { webhookStore } from '../stores/webhook-store'
+import { webhookDeliveryService } from './webhook-delivery'
+import { logger } from '../logger'
+import { env } from '../config'
+
+export class HeliusListenerService {
+  /**
+   * Process an incoming Helius webhook payload
+   *
+   * 1. Verify Helius signature (if configured)
+   * 2. For each active registration, check if payment is for them
+   * 3. On match, queue delivery to the agent's URL
+   *
+   * @returns Number of matched deliveries queued
+   */
+  async processIncoming(
+    payload: HeliusWebhookTransaction | HeliusWebhookTransaction[],
+    headers: { signature?: string; rawBody?: string }
+  ): Promise<number> {
+    // Verify Helius signature if secret is configured
+    if (env.HELIUS_WEBHOOK_SECRET && headers.rawBody) {
+      const valid = verifyWebhookSignature(
+        headers.rawBody,
+        headers.signature,
+        env.HELIUS_WEBHOOK_SECRET
+      )
+      if (!valid) {
+        logger.warn('Helius webhook signature verification failed')
+        throw new Error('HELIUS_SIGNATURE_INVALID')
+      }
+    }
+
+    const transactions = Array.isArray(payload) ? payload : [payload]
+    const registrations = webhookStore.getAll()
+
+    if (registrations.length === 0) {
+      logger.debug('No active webhook registrations, skipping processing')
+      return 0
+    }
+
+    let matchCount = 0
+
+    for (const tx of transactions) {
+      for (const registration of registrations) {
+        try {
+          const payment = await processWebhookTransaction(
+            tx,
+            registration.viewingPrivateKey,
+            registration.spendingPublicKey
+          )
+
+          if (payment) {
+            matchCount++
+            webhookDeliveryService.queueDelivery(registration, payment)
+            logger.info(
+              {
+                webhookId: registration.id,
+                txSignature: payment.txSignature,
+              },
+              'Payment matched, delivery queued'
+            )
+          }
+        } catch (error) {
+          logger.warn(
+            {
+              webhookId: registration.id,
+              error: (error as Error).message,
+            },
+            'Error checking transaction against registration'
+          )
+        }
+      }
+    }
+
+    logger.info(
+      {
+        transactions: transactions.length,
+        registrations: registrations.length,
+        matches: matchCount,
+      },
+      'Helius webhook processed'
+    )
+
+    return matchCount
+  }
+}
+
+export const heliusListenerService = new HeliusListenerService()

package/src/services/index.ts

@@ -0,0 +1,15 @@
+export {
+  getTokenMetadata,
+  getTokenDecimals,
+  isKnownToken,
+  type TokenMetadata,
+} from './token-metadata'
+export {
+  WebhookDeliveryService,
+  webhookDeliveryService,
+  computeHmacSignature,
+} from './webhook-delivery'
+export {
+  HeliusListenerService,
+  heliusListenerService,
+} from './helius-listener'

package/src/services/token-metadata.ts

@@ -0,0 +1,91 @@
+import type { ChainId } from '@sip-protocol/types'
+
+/**
+ * Token metadata interface
+ */
+export interface TokenMetadata {
+  symbol: string
+  decimals: number
+  name: string
+  address?: string
+}
+
+/**
+ * Token registry with known tokens and their metadata
+ *
+ * IMPORTANT: This is a static registry for common tokens.
+ * In production, fetch metadata from on-chain or token list APIs.
+ */
+const TOKEN_REGISTRY: Record<string, Record<string, TokenMetadata>> = {
+  // Solana tokens
+  solana: {
+    SOL: { symbol: 'SOL', decimals: 9, name: 'Solana' },
+    USDC: { symbol: 'USDC', decimals: 6, name: 'USD Coin', address: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v' },
+    USDT: { symbol: 'USDT', decimals: 6, name: 'Tether USD', address: 'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB' },
+    RAY: { symbol: 'RAY', decimals: 6, name: 'Raydium', address: '4k3Dyjzvzp8eMZWUXbBCjEvwSkkk59S5iCNLY3QrkX6R' },
+    BONK: { symbol: 'BONK', decimals: 5, name: 'Bonk', address: 'DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263' },
+    JUP: { symbol: 'JUP', decimals: 6, name: 'Jupiter', address: 'JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN' },
+  },
+  // Ethereum tokens
+  ethereum: {
+    ETH: { symbol: 'ETH', decimals: 18, name: 'Ethereum' },
+    USDC: { symbol: 'USDC', decimals: 6, name: 'USD Coin', address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' },
+    USDT: { symbol: 'USDT', decimals: 6, name: 'Tether USD', address: '0xdAC17F958D2ee523a2206206994597C13D831ec7' },
+    WETH: { symbol: 'WETH', decimals: 18, name: 'Wrapped Ether', address: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2' },
+    DAI: { symbol: 'DAI', decimals: 18, name: 'Dai Stablecoin', address: '0x6B175474E89094C44Da98b954EesdeB131e560dA7' },
+    WBTC: { symbol: 'WBTC', decimals: 8, name: 'Wrapped Bitcoin', address: '0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599' },
+  },
+  // NEAR tokens
+  near: {
+    NEAR: { symbol: 'NEAR', decimals: 24, name: 'NEAR Protocol' },
+    USDC: { symbol: 'USDC', decimals: 6, name: 'USD Coin', address: 'usdc.near' },
+    USDT: { symbol: 'USDT', decimals: 6, name: 'Tether USD', address: 'usdt.near' },
+    wNEAR: { symbol: 'wNEAR', decimals: 24, name: 'Wrapped NEAR', address: 'wrap.near' },
+  },
+  // Bitcoin (mostly for reference)
+  bitcoin: {
+    BTC: { symbol: 'BTC', decimals: 8, name: 'Bitcoin' },
+  },
+}
+
+/**
+ * Get token metadata for a given chain and symbol
+ *
+ * @throws Error if token not found (never silently return wrong decimals)
+ */
+export function getTokenMetadata(chain: ChainId, symbol: string): TokenMetadata {
+  const chainTokens = TOKEN_REGISTRY[chain]
+  if (!chainTokens) {
+    throw new Error(`Unknown chain: ${chain}. Supported chains: ${Object.keys(TOKEN_REGISTRY).join(', ')}`)
+  }
+
+  // Case-insensitive lookup
+  const normalizedSymbol = symbol.toUpperCase()
+  const token = chainTokens[normalizedSymbol]
+  if (!token) {
+    throw new Error(`Unknown token ${symbol} on ${chain}. Known tokens: ${Object.keys(chainTokens).join(', ')}`)
+  }
+
+  return token
+}
+
+/**
+ * Get token decimals for a given chain and symbol
+ *
+ * @throws Error if token not found (never silently return wrong decimals)
+ */
+export function getTokenDecimals(chain: ChainId, symbol: string): number {
+  return getTokenMetadata(chain, symbol).decimals
+}
+
+/**
+ * Check if token exists in registry
+ */
+export function isKnownToken(chain: ChainId, symbol: string): boolean {
+  try {
+    getTokenMetadata(chain, symbol)
+    return true
+  } catch {
+    return false
+  }
+}