@sip-protocol/api 0.1.0 → 0.1.1

package/src/services/webhook-delivery.ts

@@ -0,0 +1,146 @@
+/**
+ * Webhook Delivery Service
+ *
+ * Delivers payment notifications to registered agent URLs with:
+ * - HMAC-SHA256 signature (X-SIP-Signature header)
+ * - Exponential backoff retry (1s, 4s, 16s)
+ * - Graceful shutdown drain
+ */
+
+import { hmac } from '@noble/hashes/hmac'
+import { sha256 } from '@noble/hashes/sha256'
+import { bytesToHex } from '@noble/hashes/utils'
+import { logger } from '../logger'
+import { env } from '../config'
+import type { WebhookDeliveryPayload } from '../types/api'
+import type { WebhookRegistration } from '../stores/webhook-store'
+import type { SolanaScanResult } from '@sip-protocol/sdk'
+
+/**
+ * Compute HMAC-SHA256 signature for webhook payload
+ */
+export function computeHmacSignature(secret: string, body: string): string {
+  const encoder = new TextEncoder()
+  const sig = bytesToHex(hmac(sha256, encoder.encode(secret), encoder.encode(body)))
+  return `sha256=${sig}`
+}
+
+/**
+ * Sleep helper for retry backoff
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+export class WebhookDeliveryService {
+  private readonly maxRetries: number
+  private pendingDeliveries = new Set<Promise<void>>()
+
+  constructor(maxRetries?: number) {
+    this.maxRetries = maxRetries ?? env.WEBHOOK_DELIVERY_MAX_RETRIES
+  }
+
+  /**
+   * Build the delivery payload from a scan result
+   */
+  buildPayload(registration: WebhookRegistration, payment: SolanaScanResult): WebhookDeliveryPayload {
+    return {
+      event: 'payment.received',
+      webhookId: registration.id,
+      timestamp: new Date().toISOString(),
+      data: {
+        txSignature: payment.txSignature,
+        stealthAddress: payment.stealthAddress,
+        ephemeralPublicKey: payment.ephemeralPublicKey,
+        amount: payment.amount.toString(),
+        mint: payment.mint,
+        tokenSymbol: payment.tokenSymbol,
+        slot: payment.slot,
+        blockTime: payment.timestamp,
+      },
+    }
+  }
+
+  /**
+   * Deliver a payment notification to a registered webhook
+   *
+   * Retries with exponential backoff on failure.
+   */
+  async deliver(registration: WebhookRegistration, payment: SolanaScanResult): Promise<boolean> {
+    const payload = this.buildPayload(registration, payment)
+    const body = JSON.stringify(payload)
+    const signature = computeHmacSignature(registration.secret, body)
+
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      try {
+        const response = await fetch(registration.url, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'X-SIP-Signature': signature,
+            'X-SIP-Webhook-Id': registration.id,
+          },
+          body,
+          signal: AbortSignal.timeout(10_000),
+        })
+
+        if (response.ok) {
+          logger.info(
+            { webhookId: registration.id, attempt, status: response.status },
+            'Webhook delivered'
+          )
+          return true
+        }
+
+        logger.warn(
+          { webhookId: registration.id, attempt, status: response.status },
+          'Webhook delivery failed (non-2xx)'
+        )
+      } catch (error) {
+        logger.warn(
+          { webhookId: registration.id, attempt, error: (error as Error).message },
+          'Webhook delivery error'
+        )
+      }
+
+      if (attempt < this.maxRetries) {
+        const backoffMs = Math.pow(4, attempt) * 1000 // 1s, 4s, 16s
+        await sleep(backoffMs)
+      }
+    }
+
+    logger.error(
+      { webhookId: registration.id, maxRetries: this.maxRetries },
+      'Webhook delivery exhausted all retries'
+    )
+    return false
+  }
+
+  /**
+   * Queue a delivery (fire-and-forget with tracking)
+   */
+  queueDelivery(registration: WebhookRegistration, payment: SolanaScanResult): void {
+    const promise: Promise<void> = this.deliver(registration, payment)
+      .then(() => {})
+      .catch(err => {
+        logger.error({ webhookId: registration.id, err }, 'Unhandled webhook delivery error')
+      })
+      .finally(() => {
+        this.pendingDeliveries.delete(promise)
+      })
+    this.pendingDeliveries.add(promise)
+  }
+
+  /**
+   * Wait for all pending deliveries to complete (graceful shutdown)
+   */
+  async drainPending(): Promise<void> {
+    if (this.pendingDeliveries.size > 0) {
+      logger.info({ pending: this.pendingDeliveries.size }, 'Draining pending webhook deliveries')
+      await Promise.allSettled(this.pendingDeliveries)
+      logger.info('All webhook deliveries drained')
+    }
+  }
+}
+
+export const webhookDeliveryService = new WebhookDeliveryService()

package/src/shutdown.ts

@@ -0,0 +1,119 @@
+/**
+ * Graceful Shutdown Handler
+ *
+ * Handles SIGTERM and SIGINT signals to:
+ * - Stop accepting new connections
+ * - Allow in-flight requests to complete
+ * - Clean up resources
+ * - Exit gracefully
+ */
+
+import { Server } from 'http'
+import { logger } from './logger'
+import { env } from './config'
+
+let isShuttingDown = false
+
+/**
+ * Check if server is currently shutting down
+ */
+export function isServerShuttingDown(): boolean {
+  return isShuttingDown
+}
+
+/**
+ * Setup graceful shutdown handlers
+ *
+ * @param server - HTTP server instance
+ * @param cleanup - Optional cleanup function to run before exit
+ */
+export function setupGracefulShutdown(
+  server: Server,
+  cleanup?: () => Promise<void>
+): void {
+  const shutdown = async (signal: string) => {
+    if (isShuttingDown) {
+      logger.warn({ signal }, 'Shutdown already in progress, ignoring signal')
+      return
+    }
+
+    isShuttingDown = true
+    logger.info({ signal }, 'Received shutdown signal, starting graceful shutdown...')
+
+    // Stop accepting new connections
+    server.close(async (err) => {
+      if (err) {
+        logger.error({ err }, 'Error closing HTTP server')
+        process.exit(1)
+      }
+
+      logger.info('HTTP server closed, no longer accepting connections')
+
+      // Run cleanup if provided
+      if (cleanup) {
+        try {
+          logger.info('Running cleanup tasks...')
+          await cleanup()
+          logger.info('Cleanup completed successfully')
+        } catch (cleanupErr) {
+          logger.error({ err: cleanupErr }, 'Error during cleanup')
+        }
+      }
+
+      logger.info('Graceful shutdown complete, exiting')
+      process.exit(0)
+    })
+
+    // Force exit after timeout
+    setTimeout(() => {
+      logger.error(
+        { timeoutMs: env.SHUTDOWN_TIMEOUT_MS },
+        'Graceful shutdown timeout exceeded, forcing exit'
+      )
+      process.exit(1)
+    }, env.SHUTDOWN_TIMEOUT_MS)
+  }
+
+  // Handle termination signals
+  process.on('SIGTERM', () => shutdown('SIGTERM'))
+  process.on('SIGINT', () => shutdown('SIGINT'))
+
+  // Handle uncaught errors
+  process.on('uncaughtException', (err) => {
+    logger.fatal({ err }, 'Uncaught exception, shutting down')
+    shutdown('uncaughtException')
+  })
+
+  process.on('unhandledRejection', (reason) => {
+    logger.fatal({ reason }, 'Unhandled rejection, shutting down')
+    shutdown('unhandledRejection')
+  })
+
+  logger.debug('Graceful shutdown handlers registered')
+}
+
+/**
+ * Middleware to reject new requests during shutdown
+ */
+export function shutdownMiddleware(
+  req: { path: string },
+  res: { status: (code: number) => { json: (body: unknown) => void } },
+  next: () => void
+): void {
+  if (isShuttingDown) {
+    // Allow health checks to report unhealthy during shutdown
+    if (req.path === '/api/v1/health') {
+      return next()
+    }
+
+    res.status(503).json({
+      success: false,
+      error: {
+        code: 'SERVICE_UNAVAILABLE',
+        message: 'Server is shutting down',
+      },
+    })
+    return
+  }
+  next()
+}

package/src/stores/index.ts

@@ -0,0 +1,2 @@
+export { SwapStore, swapStore, type SwapData, type SwapStoreConfig } from './swap-store'
+export { WebhookStore, webhookStore, type WebhookRegistration } from './webhook-store'

package/src/stores/swap-store.ts

@@ -0,0 +1,158 @@
+import { LRUCache } from 'lru-cache'
+import type { HexString } from '@sip-protocol/types'
+import { logger } from '../logger'
+
+/**
+ * Swap data stored in the cache
+ */
+export interface SwapData {
+  id: string
+  status: 'pending' | 'processing' | 'completed' | 'failed'
+  transactionHash?: HexString
+  inputAmount: string
+  outputAmount?: string
+  createdAt: string
+  updatedAt: string
+  error?: string
+}
+
+/**
+ * Swap store configuration
+ */
+export interface SwapStoreConfig {
+  /** Maximum number of swaps to store (default: 10000) */
+  maxSize?: number
+  /** TTL in milliseconds (default: 24 hours) */
+  ttlMs?: number
+}
+
+const DEFAULT_MAX_SIZE = 10_000
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000 // 24 hours
+
+/**
+ * LRU cache-backed swap store with TTL
+ *
+ * Features:
+ * - Bounded memory (max 10,000 entries by default)
+ * - Automatic TTL-based expiration (24 hours by default)
+ * - LRU eviction when at capacity
+ * - Metrics for monitoring
+ */
+export class SwapStore {
+  private cache: LRUCache<string, SwapData>
+  private readonly maxSize: number
+  private readonly ttlMs: number
+
+  constructor(config: SwapStoreConfig = {}) {
+    this.maxSize = config.maxSize ?? DEFAULT_MAX_SIZE
+    this.ttlMs = config.ttlMs ?? DEFAULT_TTL_MS
+
+    this.cache = new LRUCache<string, SwapData>({
+      max: this.maxSize,
+      ttl: this.ttlMs,
+      updateAgeOnGet: false, // Don't reset TTL on read
+      updateAgeOnHas: false,
+      // Log when items are evicted or expired
+      disposeAfter: (_value, key, reason) => {
+        if (reason === 'evict') {
+          logger.debug({ swapId: key, reason }, 'Swap evicted from cache (LRU)')
+        } else if (reason === 'expire') {
+          logger.debug({ swapId: key, reason }, 'Swap expired from cache (TTL)')
+        }
+      },
+    })
+
+    logger.info(
+      { maxSize: this.maxSize, ttlMs: this.ttlMs },
+      'SwapStore initialized'
+    )
+  }
+
+  /**
+   * Get a swap by ID
+   */
+  get(id: string): SwapData | undefined {
+    return this.cache.get(id)
+  }
+
+  /**
+   * Check if a swap exists
+   */
+  has(id: string): boolean {
+    return this.cache.has(id)
+  }
+
+  /**
+   * Set/update a swap
+   */
+  set(id: string, data: SwapData): void {
+    this.cache.set(id, data)
+  }
+
+  /**
+   * Delete a swap
+   */
+  delete(id: string): boolean {
+    return this.cache.delete(id)
+  }
+
+  /**
+   * Update swap status
+   */
+  updateStatus(
+    id: string,
+    status: SwapData['status'],
+    updates?: Partial<SwapData>
+  ): SwapData | undefined {
+    const existing = this.cache.get(id)
+    if (!existing) {
+      return undefined
+    }
+
+    const updated: SwapData = {
+      ...existing,
+      ...updates,
+      status,
+      updatedAt: new Date().toISOString(),
+    }
+
+    this.cache.set(id, updated)
+    return updated
+  }
+
+  /**
+   * Get store metrics for monitoring
+   */
+  getMetrics(): {
+    size: number
+    maxSize: number
+    ttlMs: number
+    utilizationPercent: number
+  } {
+    const size = this.cache.size
+    return {
+      size,
+      maxSize: this.maxSize,
+      ttlMs: this.ttlMs,
+      utilizationPercent: Math.round((size / this.maxSize) * 100),
+    }
+  }
+
+  /**
+   * Clear all swaps (for testing)
+   */
+  clear(): void {
+    this.cache.clear()
+  }
+
+  /**
+   * Purge stale entries (normally handled automatically by LRU cache)
+   */
+  purgeStale(): void {
+    this.cache.purgeStale()
+  }
+}
+
+// Export singleton instance with default config
+// Can be overridden in tests or for custom configurations
+export const swapStore = new SwapStore()

package/src/stores/webhook-store.ts

@@ -0,0 +1,120 @@
+/**
+ * In-memory Webhook Registration Store
+ *
+ * Stores agent webhook registrations with bounded capacity.
+ * Data is lost on restart (MVP limitation — future: Redis/SQLite).
+ */
+
+import { randomBytes } from 'crypto'
+import type { HexString } from '@sip-protocol/types'
+import { logger } from '../logger'
+import { env } from '../config'
+
+/**
+ * Webhook registration entry
+ */
+export interface WebhookRegistration {
+  id: string
+  url: string
+  viewingPrivateKey: HexString
+  spendingPublicKey: HexString
+  secret: string
+  createdAt: string
+  active: boolean
+}
+
+/**
+ * Bounded in-memory store for webhook registrations
+ */
+export class WebhookStore {
+  private registrations = new Map<string, WebhookRegistration>()
+  private readonly maxSize: number
+
+  constructor(maxSize?: number) {
+    this.maxSize = maxSize ?? env.WEBHOOK_STORE_MAX_SIZE
+    logger.info({ maxSize: this.maxSize }, 'WebhookStore initialized')
+  }
+
+  /**
+   * Register a new webhook
+   *
+   * @returns The registration with secret (shown once only)
+   */
+  register(url: string, viewingPrivateKey: HexString, spendingPublicKey: HexString): WebhookRegistration {
+    if (this.registrations.size >= this.maxSize) {
+      throw new Error('WEBHOOK_STORE_FULL')
+    }
+
+    const id = randomBytes(16).toString('hex')
+    const secret = randomBytes(32).toString('hex')
+
+    const registration: WebhookRegistration = {
+      id,
+      url,
+      viewingPrivateKey,
+      spendingPublicKey,
+      secret,
+      createdAt: new Date().toISOString(),
+      active: true,
+    }
+
+    this.registrations.set(id, registration)
+    logger.info({ webhookId: id, url }, 'Webhook registered')
+    return registration
+  }
+
+  /**
+   * Unregister a webhook by ID
+   *
+   * @returns true if found and removed, false if not found
+   */
+  unregister(id: string): boolean {
+    const existed = this.registrations.delete(id)
+    if (existed) {
+      logger.info({ webhookId: id }, 'Webhook unregistered')
+    }
+    return existed
+  }
+
+  /**
+   * Get a registration by ID
+   */
+  get(id: string): WebhookRegistration | undefined {
+    return this.registrations.get(id)
+  }
+
+  /**
+   * Get all active registrations
+   */
+  getAll(): WebhookRegistration[] {
+    return Array.from(this.registrations.values()).filter(r => r.active)
+  }
+
+  /**
+   * Get all registrations (including inactive) for listing
+   */
+  getAllForList(): Array<{ id: string; url: string; active: boolean; createdAt: string }> {
+    return Array.from(this.registrations.values()).map(r => ({
+      id: r.id,
+      url: r.url,
+      active: r.active,
+      createdAt: r.createdAt,
+    }))
+  }
+
+  /**
+   * Current store size
+   */
+  get size(): number {
+    return this.registrations.size
+  }
+
+  /**
+   * Clear all registrations (for testing)
+   */
+  clear(): void {
+    this.registrations.clear()
+  }
+}
+
+export const webhookStore = new WebhookStore()

package/src/types/api.ts

@@ -17,10 +17,28 @@ export interface ApiResponse<T = unknown> {
  * Health check response
  */
 export interface HealthResponse {
-  status: 'healthy' | 'unhealthy'
+  status: 'healthy' | 'unhealthy' | 'shutting_down'
   version: string
   timestamp: string
   uptime: number
+  services?: {
+    proofProvider: {
+      ready: boolean
+      error: string | null
+    }
+    rateLimiter?: {
+      store: 'redis' | 'memory'
+      redisConfigured: boolean
+      redisConnected: boolean
+    }
+  }
+  cache?: {
+    swaps: {
+      size: number
+      maxSize: number
+      utilizationPercent: number
+    }
+  }
 }
 
 /**
@@ -121,3 +139,51 @@ export interface SwapStatusResponse {
   updatedAt: string
   error?: string
 }
+
+/**
+ * Webhook registration request
+ */
+export interface RegisterWebhookRequest {
+  url: string
+  viewingPrivateKey: HexString
+  spendingPublicKey: HexString
+}
+
+/**
+ * Webhook registration response (secret shown once only)
+ */
+export interface RegisterWebhookResponse {
+  id: string
+  url: string
+  secret: string
+  createdAt: string
+}
+
+/**
+ * Webhook list item (never exposes keys or secret)
+ */
+export interface WebhookListItem {
+  id: string
+  url: string
+  active: boolean
+  createdAt: string
+}
+
+/**
+ * Webhook delivery payload sent to agent URLs
+ */
+export interface WebhookDeliveryPayload {
+  event: 'payment.received'
+  webhookId: string
+  timestamp: string
+  data: {
+    txSignature: string
+    stealthAddress: string
+    ephemeralPublicKey: string
+    amount: string
+    mint: string
+    tokenSymbol?: string
+    slot: number
+    blockTime: number
+  }
+}