@sip-protocol/api 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sip-protocol/api",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "REST API service for SIP Protocol SDK - Optional wrapper for non-JS backends",
   "author": "SIP Protocol <hello@sip-protocol.org>",
   "homepage": "https://sip-protocol.org",
@@ -19,24 +19,38 @@
     "src"
   ],
   "dependencies": {
-    "@sip-protocol/sdk": "^0.6.0",
-    "@sip-protocol/types": "^0.2.0",
+    "@noble/hashes": "^1.3.3",
+    "@sentry/node": "^10.56.0",
     "compression": "^1.8.1",
-    "cors": "^2.8.5",
-    "express": "^4.22.1",
-    "helmet": "^7.2.0",
-    "morgan": "^1.10.1",
-    "zod": "^3.25.76"
+    "cors": "^2.8.6",
+    "envalid": "^8.1.1",
+    "express": "^5.2.1",
+    "express-rate-limit": "^8.5.2",
+    "helmet": "^8.2.0",
+    "ioredis": "^5.11.0",
+    "lru-cache": "^11.5.1",
+    "morgan": "^1.11.0",
+    "pino": "^10.3.1",
+    "pino-http": "^11.0.0",
+    "prom-client": "^15.1.3",
+    "rate-limit-redis": "^4.3.1",
+    "zod": "^4.4.3",
+    "@sip-protocol/sdk": "0.11.0",
+    "@sip-protocol/types": "0.2.2"
   },
   "devDependencies": {
     "@types/compression": "^1.8.1",
     "@types/cors": "^2.8.19",
-    "@types/express": "^4.17.25",
+    "@types/express": "^5.0.6",
     "@types/morgan": "^1.9.10",
+    "@types/pino-http": "^6.1.0",
+    "@types/supertest": "^6.0.3",
+    "pino-pretty": "^13.1.3",
+    "supertest": "^7.2.2",
     "tsup": "^8.5.1",
-    "tsx": "^4.21.0",
+    "tsx": "^4.22.4",
     "typescript": "^5.3.0",
-    "vitest": "^1.1.0"
+    "vitest": "^4.1.0"
   },
   "keywords": [
     "sip",

package/src/config.ts

@@ -0,0 +1,121 @@
+/**
+ * Environment Configuration with Validation
+ *
+ * Validates all environment variables at startup with clear error messages.
+ * Uses envalid for type-safe environment access.
+ */
+
+import { cleanEnv, str, port, bool, num } from 'envalid'
+
+/**
+ * Validated environment configuration
+ */
+export const env = cleanEnv(process.env, {
+  // Server configuration
+  NODE_ENV: str({
+    choices: ['development', 'production', 'test'] as const,
+    default: 'development',
+    desc: 'Application environment',
+  }),
+  PORT: port({
+    default: 3000,
+    desc: 'Server port',
+  }),
+
+  // CORS configuration
+  CORS_ORIGINS: str({
+    default: '',
+    desc: 'Comma-separated list of allowed origins (empty = localhost only in dev)',
+  }),
+
+  // Authentication
+  API_KEYS: str({
+    default: '',
+    desc: 'Comma-separated list of valid API keys (empty = auth disabled in dev)',
+  }),
+
+  // Rate limiting
+  RATE_LIMIT_MAX: num({
+    default: 100,
+    desc: 'Maximum requests per window',
+  }),
+  RATE_LIMIT_WINDOW_MS: num({
+    default: 60000,
+    desc: 'Rate limit window in milliseconds',
+  }),
+
+  // Proxy trust configuration (for X-Forwarded-For header)
+  // Set to number of trusted proxies (e.g., 1 for single nginx)
+  // or 'loopback' for local proxies, or 'uniquelocal' for private IPs
+  TRUST_PROXY: str({
+    default: '1',
+    desc: 'Express trust proxy setting (number of hops, "loopback", "uniquelocal", or "false")',
+  }),
+
+  // Logging
+  LOG_LEVEL: str({
+    choices: ['trace', 'debug', 'info', 'warn', 'error', 'fatal'] as const,
+    default: 'info',
+    desc: 'Logging level',
+  }),
+
+  // Graceful shutdown
+  SHUTDOWN_TIMEOUT_MS: num({
+    default: 30000,
+    desc: 'Graceful shutdown timeout in milliseconds',
+  }),
+
+  // Monitoring
+  SENTRY_DSN: str({
+    default: '',
+    desc: 'Sentry DSN for error tracking (optional)',
+  }),
+  METRICS_ENABLED: str({
+    choices: ['true', 'false'] as const,
+    default: 'true',
+    desc: 'Enable Prometheus metrics endpoint',
+  }),
+
+  // Webhook configuration
+  HELIUS_WEBHOOK_SECRET: str({
+    default: '',
+    desc: 'Helius webhook HMAC secret for signature verification (optional)',
+  }),
+  WEBHOOK_DELIVERY_MAX_RETRIES: num({
+    default: 3,
+    desc: 'Maximum delivery attempts for webhook notifications',
+  }),
+  WEBHOOK_STORE_MAX_SIZE: num({
+    default: 1000,
+    desc: 'Maximum number of registered webhooks',
+  }),
+})
+
+/**
+ * Log startup warnings for potentially insecure configurations
+ */
+export function logConfigWarnings(logger: { warn: (msg: string) => void }): void {
+  if (env.isProduction) {
+    if (!env.API_KEYS) {
+      logger.warn('API_KEYS not set in production - authentication disabled')
+    }
+    if (!env.CORS_ORIGINS) {
+      logger.warn('CORS_ORIGINS not set in production - only localhost allowed')
+    }
+  }
+}
+
+/**
+ * Check if running in production
+ */
+export const isProduction = env.isProduction
+
+/**
+ * Check if running in development
+ */
+export const isDevelopment = env.isDevelopment
+
+/**
+ * Check if running in test
+ */
+export const isTest = env.isTest

package/src/logger.ts

@@ -0,0 +1,99 @@
+/**
+ * Structured Logger
+ *
+ * Production-ready logging with pino.
+ * - JSON format in production for log aggregation
+ * - Pretty printed in development
+ * - Request ID tracking
+ * - Log levels configurable via LOG_LEVEL
+ */
+
+import pino from 'pino'
+import pinoHttp from 'pino-http'
+import crypto from 'crypto'
+import { env } from './config'
+
+/**
+ * Base logger configuration
+ */
+const loggerConfig: pino.LoggerOptions = {
+  level: env.LOG_LEVEL,
+  base: {
+    service: 'sip-api',
+    version: '0.1.0',
+  },
+  timestamp: pino.stdTimeFunctions.isoTime,
+}
+
+/**
+ * Add pretty printing in development
+ */
+if (env.isDevelopment) {
+  loggerConfig.transport = {
+    target: 'pino-pretty',
+    options: {
+      colorize: true,
+      translateTime: 'HH:MM:ss',
+      ignore: 'pid,hostname,service,version',
+    },
+  }
+}
+
+/**
+ * Main application logger
+ */
+export const logger = pino(loggerConfig)
+
+/**
+ * HTTP request logger middleware
+ *
+ * Automatically logs all incoming requests with:
+ * - Request ID (from header or generated)
+ * - Method and URL
+ * - Response status and time
+ * - Log level based on status code
+ */
+export const requestLogger = pinoHttp({
+  logger,
+  // Use requestId from requestIdMiddleware (set earlier in chain)
+  // Falls back to header or generates new if middleware didn't run
+  genReqId: (req) => {
+    // Type assertion for augmented request
+    const augmentedReq = req as typeof req & { requestId?: string }
+    if (augmentedReq.requestId) {
+      return augmentedReq.requestId
+    }
+    // Fallback for direct logger usage (tests, etc.)
+    const existingId = req.headers['x-request-id']
+    if (existingId && typeof existingId === 'string') {
+      return existingId
+    }
+    return crypto.randomUUID()
+  },
+  customLogLevel: (_req, res, err) => {
+    if (res.statusCode >= 500 || err) return 'error'
+    if (res.statusCode >= 400) return 'warn'
+    return 'info'
+  },
+  customSuccessMessage: (req, res) => {
+    return `${req.method} ${req.url} ${res.statusCode}`
+  },
+  customErrorMessage: (req, res, err) => {
+    return `${req.method} ${req.url} ${res.statusCode} - ${err.message}`
+  },
+  // Don't log health checks in production
+  autoLogging: {
+    ignore: (req) => {
+      return req.url === '/api/v1/health' && env.isProduction
+    },
+  },
+})
+
+/**
+ * Create a child logger with additional context
+ */
+export function createChildLogger(context: Record<string, unknown>) {
+  return logger.child(context)
+}
+
+export default logger

package/src/middleware/auth.ts

@@ -0,0 +1,128 @@
+import { Request, Response, NextFunction } from 'express'
+import { timingSafeEqual } from 'crypto'
+
+/**
+ * API Key Authentication Middleware
+ *
+ * Environment variables:
+ * - API_KEYS: Comma-separated list of valid API keys
+ * - AUTH_ENABLED: Enable/disable authentication (default: true in production)
+ * - AUTH_SKIP_PATHS: Comma-separated paths to skip auth (default: /health,/)
+ *
+ * Headers:
+ * - X-API-Key: The API key to authenticate with
+ * - Authorization: Bearer <api-key> (alternative)
+ */
+
+const API_KEYS = (process.env.API_KEYS || '').split(',').filter(Boolean)
+const NODE_ENV = process.env.NODE_ENV || 'development'
+const AUTH_ENABLED = process.env.AUTH_ENABLED !== 'false' && NODE_ENV === 'production'
+const SKIP_PATHS = (process.env.AUTH_SKIP_PATHS || '/health,/,/webhooks/internal/helius').split(',').map(p => p.trim())
+
+/**
+ * Timing-safe comparison of API keys
+ */
+function safeCompare(a: string, b: string): boolean {
+  if (a.length !== b.length) {
+    return false
+  }
+  try {
+    return timingSafeEqual(Buffer.from(a), Buffer.from(b))
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Check if a given API key is valid
+ */
+function isValidApiKey(key: string): boolean {
+  return API_KEYS.some(validKey => safeCompare(key, validKey))
+}
+
+/**
+ * Extract API key from request headers
+ */
+function extractApiKey(req: Request): string | null {
+  // Check X-API-Key header first
+  const apiKeyHeader = req.headers['x-api-key']
+  if (typeof apiKeyHeader === 'string' && apiKeyHeader) {
+    return apiKeyHeader
+  }
+
+  // Check Authorization header (Bearer token)
+  const authHeader = req.headers.authorization
+  if (authHeader?.startsWith('Bearer ')) {
+    return authHeader.slice(7)
+  }
+
+  return null
+}
+
+/**
+ * Authentication middleware
+ */
+export function authenticate(req: Request, res: Response, next: NextFunction) {
+  // Skip auth in development if not explicitly enabled
+  if (!AUTH_ENABLED) {
+    return next()
+  }
+
+  // Skip auth for certain paths
+  const path = req.path.replace('/api/v1', '')
+  if (SKIP_PATHS.some(skipPath => path === skipPath || path.startsWith(skipPath + '/'))) {
+    return next()
+  }
+
+  // Check if API keys are configured
+  if (API_KEYS.length === 0) {
+    console.warn('[Auth] No API keys configured. Set API_KEYS environment variable.')
+    return res.status(500).json({
+      success: false,
+      error: {
+        code: 'AUTH_NOT_CONFIGURED',
+        message: 'Authentication is enabled but no API keys are configured',
+      },
+    })
+  }
+
+  // Extract and validate API key
+  const apiKey = extractApiKey(req)
+
+  if (!apiKey) {
+    return res.status(401).json({
+      success: false,
+      error: {
+        code: 'UNAUTHORIZED',
+        message: 'API key required. Provide via X-API-Key header or Authorization: Bearer <key>',
+      },
+    })
+  }
+
+  if (!isValidApiKey(apiKey)) {
+    return res.status(401).json({
+      success: false,
+      error: {
+        code: 'INVALID_API_KEY',
+        message: 'Invalid API key',
+      },
+    })
+  }
+
+  // API key is valid
+  next()
+}
+
+/**
+ * Check if authentication is enabled
+ */
+export function isAuthEnabled(): boolean {
+  return AUTH_ENABLED
+}
+
+/**
+ * Get the number of configured API keys
+ */
+export function getApiKeyCount(): number {
+  return API_KEYS.length
+}

package/src/middleware/cors.ts

@@ -0,0 +1,163 @@
+import cors, { CorsOptions } from 'cors'
+import { Request, RequestHandler } from 'express'
+
+/**
+ * CORS Configuration Middleware
+ *
+ * Environment variables:
+ * - CORS_ORIGINS: Comma-separated list of allowed origins (required in production)
+ * - CORS_CREDENTIALS: Allow credentials (default: true)
+ * - CORS_MAX_AGE: Preflight cache duration in seconds (default: 86400 = 24 hours)
+ *
+ * Security:
+ * - In production, CORS_ORIGINS must be explicitly set (no wildcards allowed)
+ * - In development, allows localhost origins by default
+ */
+
+const NODE_ENV = process.env.NODE_ENV || 'development'
+const CORS_ORIGINS = process.env.CORS_ORIGINS?.split(',').map(o => o.trim()).filter(Boolean) || []
+const CORS_CREDENTIALS = process.env.CORS_CREDENTIALS !== 'false'
+const CORS_MAX_AGE = parseInt(process.env.CORS_MAX_AGE || '86400', 10)
+
+// Default development origins
+const DEV_ORIGINS = [
+  'http://localhost:3000',
+  'http://localhost:3001',
+  'http://localhost:4000',
+  'http://localhost:5173', // Vite
+  'http://127.0.0.1:3000',
+  'http://127.0.0.1:3001',
+  'http://127.0.0.1:4000',
+  'http://127.0.0.1:5173',
+]
+
+/**
+ * Get allowed origins based on environment
+ */
+function getAllowedOrigins(): string[] {
+  if (CORS_ORIGINS.length > 0) {
+    return CORS_ORIGINS
+  }
+
+  if (NODE_ENV === 'development' || NODE_ENV === 'test') {
+    return DEV_ORIGINS
+  }
+
+  // Production with no origins configured - deny all
+  return []
+}
+
+/**
+ * Safely parse a URL, returning null if malformed
+ */
+function safeParseUrl(url: string): URL | null {
+  try {
+    return new URL(url)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Check if origin is allowed
+ *
+ * Security: Handles malformed URLs gracefully (denies instead of crashing)
+ * and enforces HTTPS in production mode for wildcard subdomain matches.
+ */
+function isOriginAllowed(origin: string | undefined): boolean {
+  if (!origin) {
+    // Allow requests with no origin (same-origin, curl, etc.)
+    return true
+  }
+
+  const allowedOrigins = getAllowedOrigins()
+
+  // Check exact match
+  if (allowedOrigins.includes(origin)) {
+    return true
+  }
+
+  // Parse origin URL for wildcard matching
+  // Security: Wrap in try/catch to handle malformed URLs gracefully
+  let originUrl: URL
+  try {
+    originUrl = new URL(origin)
+  } catch {
+    // Malformed URL = denied (don't crash, just reject)
+    console.warn(`[CORS] Rejected malformed origin: ${origin}`)
+    return false
+  }
+
+  // Check wildcard subdomains (e.g., *.example.com)
+  for (const allowed of allowedOrigins) {
+    if (allowed.startsWith('*.')) {
+      const baseDomain = allowed.slice(2)
+      const originHost = originUrl.host
+
+      // Security: Enforce HTTPS in production for wildcard matches
+      // This prevents attackers from using HTTP to bypass HSTS
+      if (NODE_ENV === 'production' && originUrl.protocol !== 'https:') {
+        console.warn(`[CORS] Rejected non-HTTPS origin in production: ${origin}`)
+        continue
+      }
+
+      // Match base domain or subdomains
+      if (originHost === baseDomain || originHost.endsWith('.' + baseDomain)) {
+        return true
+      }
+    }
+  }
+
+  return false
+}
+
+/**
+ * Dynamic CORS options based on request origin
+ */
+const corsOptionsDelegate = (req: Request, callback: (err: Error | null, options?: CorsOptions) => void) => {
+  const origin = req.headers.origin
+  const allowed = isOriginAllowed(origin)
+
+  const options: CorsOptions = {
+    origin: allowed ? origin : false,
+    credentials: CORS_CREDENTIALS,
+    maxAge: CORS_MAX_AGE,
+    methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'],
+    allowedHeaders: [
+      'Content-Type',
+      'Authorization',
+      'X-API-Key',
+      'X-Request-ID',
+      'X-Forwarded-For',
+    ],
+    exposedHeaders: [
+      'RateLimit-Limit',
+      'RateLimit-Remaining',
+      'RateLimit-Reset',
+      'X-Request-ID',
+    ],
+  }
+
+  if (!allowed && origin) {
+    console.warn(`[CORS] Blocked request from origin: ${origin}`)
+  }
+
+  callback(null, options)
+}
+
+/**
+ * Secure CORS middleware
+ */
+export const secureCors: RequestHandler = cors(corsOptionsDelegate) as RequestHandler
+
+/**
+ * Get current CORS configuration (for debugging/health checks)
+ */
+export function getCorsConfig() {
+  return {
+    origins: getAllowedOrigins(),
+    credentials: CORS_CREDENTIALS,
+    maxAge: CORS_MAX_AGE,
+    environment: NODE_ENV,
+  }
+}

package/src/middleware/error-handler.ts

@@ -1,5 +1,8 @@
 import { Request, Response, NextFunction } from 'express'
-import { SIPError, isSIPError } from '@sip-protocol/sdk'
+import { SIPError, ValidationError, isSIPError } from '@sip-protocol/sdk'
+import { logger } from '../logger'
+import { env } from '../config'
+import { captureException } from '../monitoring'
 
 /**
  * Global error handler middleware
@@ -10,37 +13,45 @@ export function errorHandler(
   res: Response,
   next: NextFunction
 ) {
-  // Log error for debugging
-  console.error('[API Error]', {
+  // Log error with structured logger
+  logger.error({
     path: req.path,
     method: req.method,
     error: err.message,
     stack: err.stack,
-  })
+  }, 'API Error')
 
   // Handle SIP SDK errors
   if (isSIPError(err)) {
     const sipError = err as SIPError
+    // Check if it's a ValidationError with field property
+    const isValidationError = err instanceof ValidationError
     return res.status(400).json({
       success: false,
       error: {
         code: sipError.code,
         message: sipError.message,
         details: {
-          field: (sipError as any).field,
-          expected: (sipError as any).expected,
+          ...(isValidationError && { field: (err as ValidationError).field }),
+          ...sipError.context,
         },
       },
     })
   }
 
+  // Capture to Sentry (for 5xx errors)
+  captureException(err, {
+    path: req.path,
+    method: req.method,
+  })
+
   // Handle generic errors
   res.status(500).json({
     success: false,
     error: {
       code: 'INTERNAL_SERVER_ERROR',
       message: 'An unexpected error occurred',
-      details: process.env.NODE_ENV === 'development' ? err.message : undefined,
+      details: env.isDevelopment ? err.message : undefined,
     },
   })
 }

package/src/middleware/index.ts

@@ -1,2 +1,14 @@
 export { errorHandler, notFoundHandler } from './error-handler'
-export { validateRequest, schemas } from './validation'
+export {
+  validateRequest,
+  schemas,
+  amountSchema,
+  minAmountSchema,
+  calculateMinAmount,
+  percentToBps,
+  MAX_UINT256
+} from './validation'
+export { rateLimiter, strictRateLimiter } from './rate-limit'
+export { authenticate, isAuthEnabled, getApiKeyCount } from './auth'
+export { secureCors, getCorsConfig } from './cors'
+export { requestIdMiddleware } from './request-id'