@sip-protocol/api 0.1.0 → 0.1.1

package/src/middleware/rate-limit.ts

@@ -0,0 +1,203 @@
+import rateLimit, { type Store } from 'express-rate-limit'
+import { RedisStore, type SendCommandFn } from 'rate-limit-redis'
+import { Redis } from 'ioredis'
+import type { Request, Response } from 'express'
+
+/**
+ * Rate limiting configuration
+ *
+ * Environment variables:
+ * - RATE_LIMIT_WINDOW_MS: Window size in milliseconds (default: 60000 = 1 minute)
+ * - RATE_LIMIT_MAX_REQUESTS: Max requests per window (default: 100)
+ * - RATE_LIMIT_SKIP_FAILED: Skip failed requests from count (default: false)
+ * - RATE_LIMIT_STORE: Store type - 'redis' or 'memory' (default: 'memory')
+ * - REDIS_URL: Redis connection URL (required if store is 'redis')
+ *
+ * SECURITY NOTE: This rate limiter relies on Express trust proxy configuration
+ * to properly extract client IP from X-Forwarded-For header when behind a reverse proxy.
+ * Ensure TRUST_PROXY is correctly set in your environment configuration.
+ * See: https://expressjs.com/en/guide/behind-proxies.html
+ */
+
+const WINDOW_MS = parseInt(process.env.RATE_LIMIT_WINDOW_MS || '60000', 10)
+const MAX_REQUESTS = parseInt(process.env.RATE_LIMIT_MAX_REQUESTS || '100', 10)
+const SKIP_FAILED = process.env.RATE_LIMIT_SKIP_FAILED === 'true'
+const STORE_TYPE = process.env.RATE_LIMIT_STORE || 'memory'
+const REDIS_URL = process.env.REDIS_URL
+
+/**
+ * Redis client singleton for rate limiting
+ * Initialized lazily when Redis store is requested
+ */
+let redisClient: Redis | null = null
+let redisConnectionFailed = false
+
+/**
+ * Get or create Redis client
+ * Returns null if Redis is not configured or connection failed
+ */
+function getRedisClient(): Redis | null {
+  if (redisConnectionFailed) {
+    return null
+  }
+
+  if (!redisClient && REDIS_URL) {
+    redisClient = new Redis(REDIS_URL, {
+      maxRetriesPerRequest: 3,
+      retryStrategy: (times) => {
+        if (times > 3) {
+          console.warn('[rate-limit] Redis connection failed, falling back to memory store')
+          redisConnectionFailed = true
+          return null
+        }
+        return Math.min(times * 100, 1000)
+      },
+      lazyConnect: true,
+    })
+
+    redisClient.on('error', (err) => {
+      console.warn('[rate-limit] Redis error:', err.message)
+    })
+
+    redisClient.on('connect', () => {
+      console.log('[rate-limit] Redis connected successfully')
+    })
+  }
+
+  return redisClient
+}
+
+/**
+ * Check Redis connection health
+ */
+export async function checkRedisHealth(): Promise<{
+  connected: boolean
+  latencyMs?: number
+  error?: string
+}> {
+  const client = getRedisClient()
+  if (!client) {
+    return { connected: false, error: 'Redis not configured' }
+  }
+
+  try {
+    const start = Date.now()
+    await client.ping()
+    return { connected: true, latencyMs: Date.now() - start }
+  } catch (err) {
+    return {
+      connected: false,
+      error: err instanceof Error ? err.message : 'Unknown error',
+    }
+  }
+}
+
+/**
+ * Get Redis connection status for health endpoint
+ */
+export function getRedisStatus(): {
+  storeType: 'redis' | 'memory'
+  configured: boolean
+  connected: boolean
+} {
+  const client = getRedisClient()
+  return {
+    storeType: client && !redisConnectionFailed ? 'redis' : 'memory',
+    configured: !!REDIS_URL,
+    connected: client?.status === 'ready',
+  }
+}
+
+/**
+ * Create rate limit store based on configuration
+ * Falls back to memory store if Redis is unavailable
+ */
+function createStore(prefix: string): Store | undefined {
+  if (STORE_TYPE === 'redis' || REDIS_URL) {
+    const client = getRedisClient()
+    if (client && !redisConnectionFailed) {
+      const sendCommand: SendCommandFn = async (...args: string[]) => {
+        return client.call(args[0], ...args.slice(1)) as Promise<number | string>
+      }
+      return new RedisStore({
+        sendCommand,
+        prefix: `rl:${prefix}:`,
+      })
+    }
+  }
+
+  // Use default MemoryStore (undefined lets express-rate-limit use its default)
+  return undefined
+}
+
+// Key generator is intentionally not customized - we use express-rate-limit's
+// default behavior which properly handles IPv6 addresses via req.ip
+// See: https://express-rate-limit.github.io/ERR_ERL_KEY_GEN_IPV6/
+
+/**
+ * Standard rate limiter for general API endpoints
+ */
+export const rateLimiter = rateLimit({
+  windowMs: WINDOW_MS,
+  max: MAX_REQUESTS,
+  skipFailedRequests: SKIP_FAILED,
+  standardHeaders: true, // Return rate limit info in `RateLimit-*` headers
+  legacyHeaders: false, // Disable `X-RateLimit-*` headers
+  // Use Redis store if available, otherwise memory
+  store: createStore('api'),
+  handler: (_req: Request, res: Response) => {
+    res.status(429).json({
+      success: false,
+      error: {
+        code: 'RATE_LIMIT_EXCEEDED',
+        message: 'Too many requests, please try again later',
+        details: {
+          retryAfter: Math.ceil(WINDOW_MS / 1000),
+          limit: MAX_REQUESTS,
+          windowMs: WINDOW_MS,
+        },
+      },
+    })
+  },
+  skip: (req: Request) => {
+    // Skip rate limiting for health checks
+    return req.path === '/api/v1/health' || req.path === '/'
+  },
+})
+
+/**
+ * Strict rate limiter for sensitive endpoints (auth, proofs)
+ */
+export const strictRateLimiter = rateLimit({
+  windowMs: 60000, // 1 minute
+  max: 10, // 10 requests per minute
+  skipFailedRequests: false,
+  standardHeaders: true,
+  legacyHeaders: false,
+  // Use Redis store if available with different prefix
+  store: createStore('strict'),
+  handler: (_req: Request, res: Response) => {
+    res.status(429).json({
+      success: false,
+      error: {
+        code: 'RATE_LIMIT_EXCEEDED',
+        message: 'Rate limit exceeded for sensitive endpoint',
+        details: {
+          retryAfter: 60,
+          limit: 10,
+          windowMs: 60000,
+        },
+      },
+    })
+  },
+})
+
+/**
+ * Graceful shutdown for Redis client
+ */
+export async function shutdownRateLimiter(): Promise<void> {
+  if (redisClient) {
+    await redisClient.quit()
+    redisClient = null
+  }
+}

package/src/middleware/request-id.ts

@@ -0,0 +1,66 @@
+/**
+ * Request ID Middleware
+ *
+ * Generates unique request IDs for request correlation across services.
+ *
+ * Features:
+ * - Accepts client-provided X-Request-ID header for end-to-end tracing
+ * - Generates UUID v4 if no client ID provided
+ * - Sets X-Request-ID response header for client correlation
+ * - Attaches requestId to request object for use in routes/logging
+ *
+ * @example Client-side usage
+ * ```typescript
+ * // Send request with ID for tracing
+ * const response = await fetch('/api/v1/swap', {
+ *   headers: { 'X-Request-ID': crypto.randomUUID() }
+ * })
+ *
+ * // Use response ID for error reporting
+ * const requestId = response.headers.get('X-Request-ID')
+ * if (!response.ok) {
+ *   console.error(`Request ${requestId} failed`)
+ * }
+ * ```
+ */
+
+import { Request, Response, NextFunction, RequestHandler } from 'express'
+import crypto from 'crypto'
+
+/** Extended Request interface with requestId */
+export interface RequestWithId extends Request {
+  requestId: string
+}
+
+/**
+ * Type guard to check if request has requestId
+ */
+export function hasRequestId(req: Request): req is RequestWithId {
+  return 'requestId' in req && typeof (req as RequestWithId).requestId === 'string'
+}
+
+/**
+ * Request ID middleware
+ *
+ * Should be added early in the middleware chain (after shutdown middleware)
+ * so all subsequent middleware can access req.requestId.
+ */
+export const requestIdMiddleware: RequestHandler = (
+  req: Request,
+  res: Response,
+  next: NextFunction
+): void => {
+  // Accept client-provided ID or generate new one
+  const clientId = req.headers['x-request-id']
+  const requestId = (typeof clientId === 'string' && clientId.length > 0)
+    ? clientId
+    : crypto.randomUUID()
+
+  // Attach to request for downstream use
+  ;(req as RequestWithId).requestId = requestId
+
+  // Set response header for client correlation
+  res.setHeader('X-Request-ID', requestId)
+
+  next()
+}

package/src/middleware/validation.ts

@@ -1,13 +1,97 @@
 import { Request, Response, NextFunction } from 'express'
-import { z, ZodSchema } from 'zod'
+import { z } from 'zod'
+import type { ZodType } from 'zod'
+
+/**
+ * Maximum value for uint256 (2^256 - 1)
+ */
+export const MAX_UINT256 = 2n ** 256n - 1n
+
+/**
+ * Schema for validating BigInt amount strings
+ *
+ * Validates:
+ * - Positive integers only (no zero, no negatives)
+ * - No leading zeros
+ * - Maximum 78 characters (max uint256 length)
+ * - Value <= 2^256 - 1
+ */
+export const amountSchema = z
+  .string()
+  .regex(/^[1-9]\d*$/, 'Amount must be positive integer without leading zeros')
+  .max(78, 'Amount exceeds maximum uint256 length')
+  .refine(
+    (v) => {
+      try {
+        const n = BigInt(v)
+        return n > 0n && n <= MAX_UINT256
+      } catch {
+        return false
+      }
+    },
+    { message: 'Invalid amount: must be positive integer <= 2^256-1' }
+  )
+
+/**
+ * Schema for validating minimum threshold amounts (allows zero)
+ *
+ * Used for:
+ * - minRequired in funding proofs (prove balance >= 0 is valid)
+ * - minAmount in swap outputs
+ *
+ * Validates:
+ * - Non-negative integers (zero allowed)
+ * - No leading zeros (except "0" itself)
+ * - Maximum 78 characters (max uint256 length)
+ * - Value <= 2^256 - 1
+ */
+export const minAmountSchema = z
+  .string()
+  .regex(/^(0|[1-9]\d*)$/, 'Amount must be non-negative integer without leading zeros')
+  .max(78, 'Amount exceeds maximum uint256 length')
+  .refine(
+    (v) => {
+      try {
+        const n = BigInt(v)
+        return n >= 0n && n <= MAX_UINT256
+      } catch {
+        return false
+      }
+    },
+    { message: 'Invalid amount: must be non-negative integer <= 2^256-1' }
+  )
+
+/**
+ * Safely calculate minimum amount with slippage
+ *
+ * @param input - Input amount as bigint
+ * @param slippageBps - Slippage in basis points (0-10000)
+ * @returns Minimum output amount after slippage
+ * @throws Error if slippage is out of range
+ */
+export function calculateMinAmount(input: bigint, slippageBps: number): bigint {
+  if (slippageBps < 0 || slippageBps > 10000) {
+    throw new Error('Invalid slippage: must be 0-10000 basis points')
+  }
+  const bps = BigInt(Math.floor(slippageBps))
+  const multiplier = 10000n - bps
+  return (input * multiplier) / 10000n
+}
+
+/**
+ * Convert percentage (0-100) to basis points (0-10000)
+ */
+export function percentToBps(percent: number): number {
+  return Math.floor(percent * 100)
+}
 
 /**
  * Zod schema validation middleware factory
  */
 export function validateRequest(schema: {
-  body?: ZodSchema
-  query?: ZodSchema
-  params?: ZodSchema
+  body?: ZodType
+  query?: ZodType
+  params?: ZodType
 }) {
   return async (req: Request, res: Response, next: NextFunction) => {
     try {
@@ -15,10 +99,14 @@ export function validateRequest(schema: {
         req.body = await schema.body.parseAsync(req.body)
       }
       if (schema.query) {
-        req.query = await schema.query.parseAsync(req.query)
+        // Zod 4 returns unknown, cast to Express expected type
+        req.query = (await schema.query.parseAsync(req.query)) as typeof req.query
       }
       if (schema.params) {
-        req.params = await schema.params.parseAsync(req.params)
+        // Zod 4 returns unknown, cast to Express expected type
+        req.params = (await schema.params.parseAsync(
+          req.params
+        )) as typeof req.params
       }
       next()
     } catch (error) {
@@ -28,7 +116,8 @@ export function validateRequest(schema: {
           error: {
             code: 'VALIDATION_ERROR',
             message: 'Invalid request data',
-            details: error.errors,
+            // Zod 4 renamed 'errors' to 'issues'
+            details: error.issues,
           },
         })
       }
@@ -52,20 +141,20 @@ export const schemas = {
   }),
 
   createCommitment: z.object({
-    value: z.string().regex(/^\d+$/), // bigint as string
+    value: amountSchema,
     blindingFactor: z.string().regex(/^0x[0-9a-fA-F]+$/).optional(),
   }),
 
   generateFundingProof: z.object({
-    balance: z.string().regex(/^\d+$/),
-    minRequired: z.string().regex(/^\d+$/),
+    balance: amountSchema,
+    minRequired: minAmountSchema, // Zero allowed: "prove I have >= 0" is valid
     balanceBlinding: z.string().regex(/^0x[0-9a-fA-F]+$/),
   }),
 
   getQuote: z.object({
     inputChain: z.enum(['solana', 'ethereum', 'near', 'zcash', 'polygon', 'arbitrum', 'optimism', 'base', 'bitcoin', 'aptos', 'sui', 'cosmos', 'osmosis', 'injective', 'celestia', 'sei', 'dydx']),
     inputToken: z.string().min(1),
-    inputAmount: z.string().regex(/^\d+$/),
+    inputAmount: amountSchema,
     outputChain: z.enum(['solana', 'ethereum', 'near', 'zcash', 'polygon', 'arbitrum', 'optimism', 'base', 'bitcoin', 'aptos', 'sui', 'cosmos', 'osmosis', 'injective', 'celestia', 'sei', 'dydx']),
     outputToken: z.string().min(1),
     slippageTolerance: z.number().min(0).max(100).optional(),

package/src/monitoring/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Monitoring Module
+ *
+ * Exports all monitoring functionality:
+ * - Sentry error tracking
+ * - Prometheus metrics
+ */
+
+export {
+  initSentry,
+  isSentryEnabled,
+  captureException,
+  captureMessage,
+  setUser,
+  setTags,
+  setupSentryErrorHandler,
+  sentryRequestHandler,
+  sentryErrorHandler,
+  flushSentry,
+  Sentry,
+} from './sentry'
+
+export {
+  register,
+  httpRequestsTotal,
+  httpRequestDuration,
+  stealthAddressGenerations,
+  commitmentCreations,
+  proofGenerations,
+  proofGenerationDuration,
+  activeConnections,
+  swapRequests,
+  quoteRequests,
+  metricsMiddleware,
+  sipMetrics,
+} from './metrics'

package/src/monitoring/metrics.ts

@@ -0,0 +1,163 @@
+/**
+ * Prometheus Metrics
+ *
+ * Exposes metrics for monitoring:
+ * - HTTP request count and latency
+ * - SIP-specific operation metrics
+ * - Default Node.js metrics (memory, CPU, event loop)
+ */
+
+import { Registry, Counter, Histogram, collectDefaultMetrics, Gauge } from 'prom-client'
+import { Request, Response, NextFunction } from 'express'
+
+// Create a registry for all metrics
+export const register = new Registry()
+
+// Add default Node.js metrics
+collectDefaultMetrics({
+  register,
+  prefix: 'sip_api_',
+})
+
+// HTTP request counter
+export const httpRequestsTotal = new Counter({
+  name: 'sip_api_http_requests_total',
+  help: 'Total number of HTTP requests',
+  labelNames: ['method', 'path', 'status'] as const,
+  registers: [register],
+})
+
+// HTTP request duration histogram
+export const httpRequestDuration = new Histogram({
+  name: 'sip_api_http_request_duration_seconds',
+  help: 'Duration of HTTP requests in seconds',
+  labelNames: ['method', 'path', 'status'] as const,
+  buckets: [0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
+  registers: [register],
+})
+
+// SIP-specific metrics
+export const stealthAddressGenerations = new Counter({
+  name: 'sip_stealth_address_generations_total',
+  help: 'Total number of stealth address generations',
+  labelNames: ['chain'] as const,
+  registers: [register],
+})
+
+export const commitmentCreations = new Counter({
+  name: 'sip_commitment_creations_total',
+  help: 'Total number of commitment creations',
+  registers: [register],
+})
+
+export const proofGenerations = new Counter({
+  name: 'sip_proof_generations_total',
+  help: 'Total number of proof generations',
+  labelNames: ['type'] as const,
+  registers: [register],
+})
+
+export const proofGenerationDuration = new Histogram({
+  name: 'sip_proof_generation_duration_seconds',
+  help: 'Duration of proof generation in seconds',
+  labelNames: ['type'] as const,
+  buckets: [0.1, 0.5, 1, 2.5, 5, 10, 30, 60],
+  registers: [register],
+})
+
+export const activeConnections = new Gauge({
+  name: 'sip_api_active_connections',
+  help: 'Number of active connections',
+  registers: [register],
+})
+
+export const swapRequests = new Counter({
+  name: 'sip_swap_requests_total',
+  help: 'Total number of swap requests',
+  labelNames: ['from_chain', 'to_chain', 'status'] as const,
+  registers: [register],
+})
+
+export const quoteRequests = new Counter({
+  name: 'sip_quote_requests_total',
+  help: 'Total number of quote requests',
+  labelNames: ['from_chain', 'to_chain'] as const,
+  registers: [register],
+})
+
+/**
+ * Normalize path to avoid high-cardinality labels
+ * Replaces dynamic segments like IDs with placeholders
+ */
+function normalizePath(path: string): string {
+  return path
+    // Replace UUIDs
+    .replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, ':id')
+    // Replace hex addresses (0x...)
+    .replace(/0x[0-9a-fA-F]{40,}/g, ':address')
+    // Replace numeric IDs
+    .replace(/\/\d+/g, '/:id')
+    // Collapse multiple slashes
+    .replace(/\/+/g, '/')
+}
+
+/**
+ * Express middleware to track HTTP metrics
+ */
+export function metricsMiddleware(req: Request, res: Response, next: NextFunction): void {
+  // Skip metrics endpoint itself to avoid recursion
+  if (req.path === '/metrics') {
+    return next()
+  }
+
+  const startTime = process.hrtime.bigint()
+
+  // Track active connections
+  activeConnections.inc()
+
+  // On response finish, record metrics
+  res.on('finish', () => {
+    const endTime = process.hrtime.bigint()
+    const durationSeconds = Number(endTime - startTime) / 1e9
+
+    const path = normalizePath(req.route?.path || req.path)
+    const labels = {
+      method: req.method,
+      path,
+      status: res.statusCode.toString(),
+    }
+
+    httpRequestsTotal.inc(labels)
+    httpRequestDuration.observe(labels, durationSeconds)
+
+    activeConnections.dec()
+  })
+
+  next()
+}
+
+/**
+ * Helper to record SIP operation metrics
+ */
+export const sipMetrics = {
+  recordStealthGeneration(chain: string): void {
+    stealthAddressGenerations.inc({ chain })
+  },
+
+  recordCommitmentCreation(): void {
+    commitmentCreations.inc()
+  },
+
+  recordProofGeneration(type: string, durationSeconds: number): void {
+    proofGenerations.inc({ type })
+    proofGenerationDuration.observe({ type }, durationSeconds)
+  },
+
+  recordSwapRequest(fromChain: string, toChain: string, status: string): void {
+    swapRequests.inc({ from_chain: fromChain, to_chain: toChain, status })
+  },
+
+  recordQuoteRequest(fromChain: string, toChain: string): void {
+    quoteRequests.inc({ from_chain: fromChain, to_chain: toChain })
+  },
+}