@twelvehart/supermemory-runtime 1.0.0-next.0

package/scripts/test-health-endpoint.sh

@@ -0,0 +1,328 @@
+#!/bin/bash
+
+# =============================================================================
+# Health Endpoint Test Script
+# =============================================================================
+# This script validates the /health endpoint implementation and Docker
+# health check integration.
+#
+# Usage:
+#   ./scripts/test-health-endpoint.sh [--docker]
+#
+# Options:
+#   --docker    Test Docker health checks instead of local endpoint
+# =============================================================================
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Configuration
+API_URL="${API_URL:-http://localhost:3000}"
+HEALTH_ENDPOINT="${API_URL}/health"
+DOCKER_MODE=false
+
+# Parse arguments
+if [[ "$1" == "--docker" ]]; then
+  DOCKER_MODE=true
+fi
+
+# Helper functions
+print_header() {
+  echo -e "\n${BLUE}==============================================================================${NC}"
+  echo -e "${BLUE}$1${NC}"
+  echo -e "${BLUE}==============================================================================${NC}\n"
+}
+
+print_success() {
+  echo -e "${GREEN}✓ $1${NC}"
+}
+
+print_error() {
+  echo -e "${RED}✗ $1${NC}"
+}
+
+print_warning() {
+  echo -e "${YELLOW}⚠ $1${NC}"
+}
+
+print_info() {
+  echo -e "${BLUE}ℹ $1${NC}"
+}
+
+# Test 1: Check if endpoint is accessible
+test_endpoint_accessible() {
+  print_header "TEST 1: Endpoint Accessibility"
+
+  if curl -f -s -o /dev/null -w "%{http_code}" "${HEALTH_ENDPOINT}" > /dev/null 2>&1; then
+    print_success "Health endpoint is accessible"
+    return 0
+  else
+    print_error "Health endpoint is not accessible"
+    print_info "Make sure the API server is running at ${API_URL}"
+    return 1
+  fi
+}
+
+# Test 2: Validate response format
+test_response_format() {
+  print_header "TEST 2: Response Format Validation"
+
+  local response=$(curl -s "${HEALTH_ENDPOINT}")
+  local status_code=$(curl -s -o /dev/null -w "%{http_code}" "${HEALTH_ENDPOINT}")
+
+  print_info "HTTP Status Code: ${status_code}"
+  print_info "Response Body:"
+  echo "${response}" | jq . 2>/dev/null || echo "${response}"
+
+  # Check if response is valid JSON
+  if echo "${response}" | jq . > /dev/null 2>&1; then
+    print_success "Response is valid JSON"
+  else
+    print_error "Response is not valid JSON"
+    return 1
+  fi
+
+  # Check required fields
+  local required_fields=("timestamp" "status" "version" "database" "uptime")
+  for field in "${required_fields[@]}"; do
+    if echo "${response}" | jq -e ".${field}" > /dev/null 2>&1; then
+      print_success "Field '${field}' is present"
+    else
+      print_error "Field '${field}' is missing"
+      return 1
+    fi
+  done
+
+  # Validate status field value
+  local status=$(echo "${response}" | jq -r '.status')
+  if [[ "${status}" == "healthy" ]] || [[ "${status}" == "unhealthy" ]]; then
+    print_success "Status field has valid value: ${status}"
+  else
+    print_error "Status field has invalid value: ${status}"
+    return 1
+  fi
+
+  return 0
+}
+
+# Test 3: Check HTTP status codes
+test_status_codes() {
+  print_header "TEST 3: HTTP Status Code Validation"
+
+  local status_code=$(curl -s -o /dev/null -w "%{http_code}" "${HEALTH_ENDPOINT}")
+
+  if [[ "${status_code}" == "200" ]]; then
+    print_success "Healthy state returns 200 OK"
+  elif [[ "${status_code}" == "503" ]]; then
+    print_warning "Service is unhealthy (503 Service Unavailable)"
+    print_info "This may indicate a database connectivity issue"
+  else
+    print_error "Unexpected status code: ${status_code}"
+    return 1
+  fi
+
+  return 0
+}
+
+# Test 4: Check database connectivity
+test_database_connectivity() {
+  print_header "TEST 4: Database Connectivity Check"
+
+  local response=$(curl -s "${HEALTH_ENDPOINT}")
+  local db_status=$(echo "${response}" | jq -r '.database')
+
+  if [[ "${db_status}" == "connected" ]]; then
+    print_success "Database is connected"
+  elif [[ "${db_status}" == "disconnected" ]]; then
+    print_error "Database is disconnected"
+    return 1
+  elif [[ "${db_status}" == "not_initialized" ]]; then
+    print_error "Database is not initialized"
+    return 1
+  else
+    print_warning "Database status is unknown: ${db_status}"
+    return 1
+  fi
+
+  return 0
+}
+
+# Test 5: Validate uptime field
+test_uptime_field() {
+  print_header "TEST 5: Uptime Field Validation"
+
+  local response=$(curl -s "${HEALTH_ENDPOINT}")
+  local uptime=$(echo "${response}" | jq -r '.uptime')
+
+  # Check if uptime is a number
+  if [[ "${uptime}" =~ ^[0-9]+(\.[0-9]+)?$ ]]; then
+    print_success "Uptime is a valid number: ${uptime} seconds"
+
+    # Convert to human-readable format
+    local hours=$((${uptime%.*} / 3600))
+    local minutes=$(((${uptime%.*} % 3600) / 60))
+    local seconds=$((${uptime%.*} % 60))
+    print_info "Process uptime: ${hours}h ${minutes}m ${seconds}s"
+  else
+    print_error "Uptime is not a valid number: ${uptime}"
+    return 1
+  fi
+
+  return 0
+}
+
+# Test 6: Response time check
+test_response_time() {
+  print_header "TEST 6: Response Time Check"
+
+  local response_time=$(curl -o /dev/null -s -w '%{time_total}' "${HEALTH_ENDPOINT}")
+
+  print_info "Response time: ${response_time} seconds"
+
+  # Convert to milliseconds
+  local response_ms=$(echo "${response_time} * 1000" | bc)
+
+  if (( $(echo "${response_ms} < 100" | bc -l) )); then
+    print_success "Response time is excellent (< 100ms)"
+  elif (( $(echo "${response_ms} < 500" | bc -l) )); then
+    print_success "Response time is good (< 500ms)"
+  elif (( $(echo "${response_ms} < 1000" | bc -l) )); then
+    print_warning "Response time is acceptable (< 1s)"
+  else
+    print_error "Response time is too slow (> 1s)"
+    return 1
+  fi
+
+  return 0
+}
+
+# Docker-specific tests
+test_docker_health() {
+  print_header "DOCKER: Container Health Status"
+
+  if ! command -v docker &> /dev/null; then
+    print_error "Docker is not installed"
+    return 1
+  fi
+
+  # Check if container is running
+  if docker compose ps api 2>/dev/null | grep -q "Up"; then
+    print_success "Container is running"
+  else
+    print_error "Container is not running"
+    print_info "Start the container with: docker compose up -d api"
+    return 1
+  fi
+
+  # Check health status
+  local health_status=$(docker inspect supermemory-api --format='{{.State.Health.Status}}' 2>/dev/null || echo "none")
+
+  print_info "Container health status: ${health_status}"
+
+  if [[ "${health_status}" == "healthy" ]]; then
+    print_success "Container is healthy"
+  elif [[ "${health_status}" == "unhealthy" ]]; then
+    print_error "Container is unhealthy"
+    print_info "Check logs with: docker compose logs api"
+    return 1
+  elif [[ "${health_status}" == "starting" ]]; then
+    print_warning "Container is still starting (within start_period)"
+    print_info "Wait a few more seconds and try again"
+  else
+    print_warning "No health status available (health check may not be configured)"
+  fi
+
+  return 0
+}
+
+test_docker_health_logs() {
+  print_header "DOCKER: Health Check Logs"
+
+  local health_log=$(docker inspect supermemory-api --format='{{json .State.Health}}' 2>/dev/null)
+
+  if [[ -n "${health_log}" ]]; then
+    echo "${health_log}" | jq . || echo "${health_log}"
+    print_success "Health check logs retrieved"
+  else
+    print_warning "No health check logs available"
+  fi
+
+  return 0
+}
+
+# Main execution
+main() {
+  echo -e "${GREEN}"
+  echo "  ╔═══════════════════════════════════════════════════════════════╗"
+  echo "  ║                                                               ║"
+  echo "  ║          SuperMemory Clone - Health Endpoint Tests           ║"
+  echo "  ║                                                               ║"
+  echo "  ╚═══════════════════════════════════════════════════════════════╝"
+  echo -e "${NC}"
+
+  local total_tests=0
+  local passed_tests=0
+  local failed_tests=0
+
+  run_test() {
+    local test_name="$1"
+    total_tests=$((total_tests + 1))
+
+    if $test_name; then
+      passed_tests=$((passed_tests + 1))
+    else
+      failed_tests=$((failed_tests + 1))
+    fi
+  }
+
+  if [[ "${DOCKER_MODE}" == true ]]; then
+    # Run Docker-specific tests
+    run_test test_docker_health
+    run_test test_docker_health_logs
+    run_test test_endpoint_accessible
+    run_test test_response_format
+  else
+    # Run standard tests
+    run_test test_endpoint_accessible
+    run_test test_response_format
+    run_test test_status_codes
+    run_test test_database_connectivity
+    run_test test_uptime_field
+    run_test test_response_time
+  fi
+
+  # Print summary
+  print_header "TEST SUMMARY"
+  echo -e "Total Tests:  ${total_tests}"
+  echo -e "Passed:       ${GREEN}${passed_tests}${NC}"
+  echo -e "Failed:       ${RED}${failed_tests}${NC}"
+
+  if [[ ${failed_tests} -eq 0 ]]; then
+    echo -e "\n${GREEN}✓ All tests passed!${NC}\n"
+    exit 0
+  else
+    echo -e "\n${RED}✗ Some tests failed${NC}\n"
+    exit 1
+  fi
+}
+
+# Check dependencies
+if ! command -v curl &> /dev/null; then
+  print_error "curl is not installed"
+  exit 1
+fi
+
+if ! command -v jq &> /dev/null; then
+  print_error "jq is not installed"
+  print_info "Install with: brew install jq (macOS) or apt-get install jq (Ubuntu)"
+  exit 1
+fi
+
+# Run main function
+main

package/src/api/index.ts

@@ -0,0 +1,2 @@
+// Deprecated API entrypoint. Use src/index.ts instead.
+export { app } from '../index.js'

package/src/api/middleware/auth.ts

@@ -0,0 +1,80 @@
+import { Context, MiddlewareHandler } from 'hono'
+import { AuthContext, ErrorCodes } from '../../types/api.types.js'
+
+function isAuthEnabled(): boolean {
+  const raw = process.env.AUTH_ENABLED
+  return raw === 'true' || raw === '1'
+}
+
+declare module 'hono' {
+  interface ContextVariableMap {
+    auth: AuthContext
+  }
+}
+
+/**
+ * Minimal optional bearer-token auth middleware.
+ * - AUTH_ENABLED=false (default): pass-through
+ * - AUTH_ENABLED=true: require Authorization: Bearer <AUTH_TOKEN>
+ */
+export const authMiddleware: MiddlewareHandler = async (c: Context, next) => {
+  if (!isAuthEnabled()) {
+    c.set('auth', { userId: 'anonymous', apiKey: '', scopes: ['*'] })
+    return next()
+  }
+
+  const configuredToken = process.env.AUTH_TOKEN
+  if (!configuredToken) {
+    return c.json(
+      {
+        error: {
+          code: ErrorCodes.INTERNAL_ERROR,
+          message: 'AUTH_TOKEN is required when AUTH_ENABLED=true',
+        },
+        status: 500,
+      },
+      500
+    )
+  }
+
+  const authHeader = c.req.header('Authorization')
+  if (!authHeader?.startsWith('Bearer ')) {
+    return c.json(
+      {
+        error: {
+          code: ErrorCodes.UNAUTHORIZED,
+          message: 'Authorization header is required (Bearer token)',
+        },
+        status: 401,
+      },
+      401
+    )
+  }
+
+  const token = authHeader.slice('Bearer '.length).trim()
+  if (!token || token !== configuredToken) {
+    return c.json(
+      {
+        error: {
+          code: ErrorCodes.UNAUTHORIZED,
+          message: 'Invalid authentication token',
+        },
+        status: 401,
+      },
+      401
+    )
+  }
+
+  c.set('auth', { userId: 'authenticated', apiKey: token, scopes: ['*'] })
+  return next()
+}
+
+/**
+ * Scope checks are intentionally no-op in minimal auth mode.
+ * Kept for backward compatibility with route declarations.
+ */
+export const requireScopes = (..._requiredScopes: string[]): MiddlewareHandler => {
+  return async (_c: Context, next) => {
+    return next()
+  }
+}

package/src/api/middleware/csrf.ts

@@ -0,0 +1,308 @@
+import { Context, MiddlewareHandler } from 'hono'
+import { getCookie, setCookie } from 'hono/cookie'
+import { createCsrfService, CsrfService } from '../../services/csrf.service.js'
+import { ErrorCodes } from '../../types/api.types.js'
+import { getLogger } from '../../utils/logger.js'
+
+const logger = getLogger('csrf-middleware')
+
+/**
+ * CSRF Protection Middleware for Hono
+ *
+ * Implements double-submit cookie pattern with:
+ * - Cryptographically secure token generation
+ * - HMAC-SHA256 signing
+ * - Constant-time comparison
+ * - SameSite=Strict cookies
+ * - Origin/Referer validation
+ * - Safe method exemption (GET, HEAD, OPTIONS)
+ *
+ * Security features:
+ * - Secure flag in production
+ * - HttpOnly flag always
+ * - Origin whitelist validation
+ * - 403 Forbidden for CSRF failures
+ */
+
+export interface CsrfConfig {
+  cookieName?: string
+  headerName?: string
+  allowedOrigins?: string[]
+  exemptMethods?: string[]
+  cookieOptions?: {
+    secure?: boolean
+    httpOnly?: boolean
+    sameSite?: 'Strict' | 'Lax' | 'None'
+    maxAge?: number
+  }
+}
+
+const DEFAULT_CONFIG: Required<CsrfConfig> = {
+  cookieName: '_csrf',
+  headerName: 'X-CSRF-Token',
+  allowedOrigins: [],
+  exemptMethods: ['GET', 'HEAD', 'OPTIONS'],
+  cookieOptions: {
+    secure: process.env.NODE_ENV === 'production',
+    httpOnly: true,
+    sameSite: 'Strict',
+    maxAge: 60 * 60, // 1 hour in seconds
+  },
+}
+
+// Global CSRF service instance
+let csrfService: CsrfService | null = null
+
+/**
+ * Get or create the global CSRF service instance.
+ */
+function getCsrfService(): CsrfService {
+  if (!csrfService) {
+    csrfService = createCsrfService()
+  }
+  return csrfService
+}
+
+/**
+ * CSRF protection middleware.
+ * Validates CSRF tokens for state-changing requests.
+ */
+export const csrfProtection = (config: CsrfConfig = {}): MiddlewareHandler => {
+  const cfg = { ...DEFAULT_CONFIG, ...config }
+  const service = getCsrfService()
+
+  return async (c: Context, next) => {
+    const method = c.req.method.toUpperCase()
+
+    // Exempt safe methods (GET, HEAD, OPTIONS)
+    if (cfg.exemptMethods.includes(method)) {
+      return next()
+    }
+
+    // Validate origin/referer for non-exempted methods
+    if (!validateOrigin(c, cfg.allowedOrigins)) {
+      return c.json(
+        {
+          error: {
+            code: ErrorCodes.FORBIDDEN,
+            message: 'Invalid origin or referer',
+          },
+          status: 403,
+        },
+        403
+      )
+    }
+
+    // Get token from cookie
+    const cookieToken = getCookie(c, cfg.cookieName)
+
+    if (!cookieToken) {
+      return c.json(
+        {
+          error: {
+            code: ErrorCodes.FORBIDDEN,
+            message: 'CSRF token missing in cookie',
+          },
+          status: 403,
+        },
+        403
+      )
+    }
+
+    // Parse cookie token (format: token:signature)
+    const cookieParts = cookieToken.split(':')
+    if (cookieParts.length !== 2) {
+      return c.json(
+        {
+          error: {
+            code: ErrorCodes.FORBIDDEN,
+            message: 'Invalid CSRF token format',
+          },
+          status: 403,
+        },
+        403
+      )
+    }
+
+    const [cookieTokenValue, cookieSignature] = cookieParts
+
+    // Get token from header or form data
+    let headerToken = c.req.header(cfg.headerName)
+
+    // If not in header, try to get from form data (for traditional forms)
+    if (!headerToken && c.req.header('content-type')?.includes('application/x-www-form-urlencoded')) {
+      try {
+        const body = await c.req.parseBody()
+        headerToken = body._csrf as string
+      } catch {
+        // Ignore parsing errors
+      }
+    }
+
+    if (!headerToken) {
+      return c.json(
+        {
+          error: {
+            code: ErrorCodes.FORBIDDEN,
+            message: 'CSRF token missing in request',
+          },
+          status: 403,
+        },
+        403
+      )
+    }
+
+    // Validate token (double-submit pattern: cookie token must match header token)
+    if (cookieTokenValue !== headerToken) {
+      return c.json(
+        {
+          error: {
+            code: ErrorCodes.FORBIDDEN,
+            message: 'CSRF token mismatch',
+          },
+          status: 403,
+        },
+        403
+      )
+    }
+
+    // Validate token signature and expiration
+    const isValid = service.validateToken(headerToken, cookieSignature ?? '')
+
+    if (!isValid) {
+      return c.json(
+        {
+          error: {
+            code: ErrorCodes.FORBIDDEN,
+            message: 'Invalid or expired CSRF token',
+          },
+          status: 403,
+        },
+        403
+      )
+    }
+
+    // Token is valid, proceed with request
+    return next()
+  }
+}
+
+/**
+ * Middleware to set CSRF cookie for clients.
+ * Should be applied before CSRF protection middleware.
+ */
+export const setCsrfCookie = (config: CsrfConfig = {}): MiddlewareHandler => {
+  const cfg = { ...DEFAULT_CONFIG, ...config }
+  const service = getCsrfService()
+
+  return async (c: Context, next) => {
+    const issueCsrfCookie = (): void => {
+      const csrfToken = service.generateToken()
+      const cookieValue = `${csrfToken.token}:${csrfToken.signature}`
+
+      setCookie(c, cfg.cookieName, cookieValue, {
+        httpOnly: cfg.cookieOptions.httpOnly,
+        secure: cfg.cookieOptions.secure,
+        sameSite: cfg.cookieOptions.sameSite,
+        maxAge: cfg.cookieOptions.maxAge,
+        path: '/',
+      })
+
+      c.set('csrfToken', csrfToken.token)
+    }
+
+    // Check if cookie already exists
+    const existingCookie = getCookie(c, cfg.cookieName)
+
+    if (!existingCookie) {
+      issueCsrfCookie()
+    } else {
+      const [token, signature, ...remainder] = existingCookie.split(':')
+      const hasValidFormat = remainder.length === 0 && !!token && !!signature
+
+      if (!hasValidFormat) {
+        issueCsrfCookie()
+      } else {
+        // Extract token from existing cookie
+        c.set('csrfToken', token)
+      }
+    }
+
+    return next()
+  }
+}
+
+/**
+ * Validate request origin/referer against whitelist.
+ *
+ * @param c - Hono context
+ * @param allowedOrigins - List of allowed origins
+ * @returns True if origin is valid
+ */
+function validateOrigin(c: Context, allowedOrigins: string[]): boolean {
+  // If no whitelist is configured, skip validation
+  if (allowedOrigins.length === 0) {
+    return true
+  }
+
+  // Get origin from Origin or Referer header
+  const origin = c.req.header('origin')
+  const referer = c.req.header('referer')
+
+  // If neither header is present, require explicit opt-in
+  if (!origin && !referer) {
+    // Explicit opt-in for missing origin/referer (dev/test environments)
+    // Use environment variable CSRF_ALLOW_MISSING_ORIGIN=true to enable
+    const allowMissing = process.env.CSRF_ALLOW_MISSING_ORIGIN === 'true'
+
+    if (!allowMissing && process.env.NODE_ENV === 'production') {
+      logger.warn('Blocked request with missing Origin and Referer headers in production')
+      return false
+    }
+
+    if (allowMissing && process.env.NODE_ENV !== 'production') {
+      logger.debug('Allowing request with missing Origin/Referer (dev mode)')
+      return true
+    }
+
+    return false
+  }
+
+  // Validate origin
+  if (origin && allowedOrigins.includes(origin)) {
+    return true
+  }
+
+  // Validate referer (extract origin from referer URL)
+  if (referer) {
+    try {
+      const refererUrl = new URL(referer)
+      const refererOrigin = `${refererUrl.protocol}//${refererUrl.host}`
+
+      if (allowedOrigins.includes(refererOrigin)) {
+        return true
+      }
+    } catch {
+      // Invalid referer URL
+      return false
+    }
+  }
+
+  return false
+}
+
+/**
+ * Extend Hono context to include CSRF token.
+ */
+declare module 'hono' {
+  interface ContextVariableMap {
+    csrfToken?: string
+  }
+}
+
+/**
+ * Helper to get CSRF token from context (for rendering in templates).
+ */
+export function getCsrfToken(c: Context): string | undefined {
+  return c.get('csrfToken')
+}