feat: bootstrap Express API with shared response envelope

.env.example

@@ -2,6 +2,19 @@
 PORT=3000
 NODE_ENV=development
 
+# HTTP Security
+TRUST_PROXY=false
+CORS_ORIGIN=http://localhost:3000
+# CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173
+CORS_ALLOW_CREDENTIALS=true
+HTTP_BODY_SIZE_LIMIT=1mb
+HTTP_SHUTDOWN_TIMEOUT_MS=15000
+
+# Rate Limiting
+RATE_LIMIT_ENABLED=true
+RATE_LIMIT_WINDOW_MS=60000
+RATE_LIMIT_MAX=100
+
 # Database
 DATABASE_URL=postgresql://user:password@localhost:5432/stellarsettle
 

src/app.ts

@@ -2,12 +2,15 @@ import cors from "cors";
 import express from "express";
 import helmet from "helmet";
 import { createErrorMiddleware, notFoundMiddleware } from "./middleware/error.middleware";
+import { applyRateLimiters, createAuthRateLimitMiddleware } from "./middleware/rate-limit.middleware";
 import { createRequestObservabilityMiddleware } from "./middleware/request-observability.middleware";
 import { logger, type AppLogger } from "./observability/logger";
 import { getMetricsContentType, MetricsRegistry } from "./observability/metrics";
 import { createAuthRouter } from "./routes/auth.routes";
 import { createInvoiceRouter } from "./routes/invoice.routes";
 import type { AuthService } from "./services/auth.service";
+import type { ApiResponseEnvelope } from "./utils/http-error";
+import dataSource from "./config/database";
 import type { InvoiceService } from "./services/invoice.service";
 import type { AppConfig } from "./config/env";
 
@@ -23,6 +26,11 @@ export interface AppDependencies {
     corsAllowCredentials?: boolean;
     bodySizeLimit?: string;
     nodeEnv?: string;
+    rateLimit?: {
+      enabled?: boolean;
+      windowMs?: number;
+      max?: number;
+    };
   };
   ipfsConfig?: AppConfig["ipfs"];
   requestLifecycleTracker?: RequestLifecycleTracker;
@@ -124,6 +132,7 @@ export function createApp({
   const bodySizeLimit = http?.bodySizeLimit ?? "1mb";
   const trustProxy = http?.trustProxy ?? false;
   const nodeEnv = http?.nodeEnv ?? process.env.NODE_ENV ?? "development";
+  const rateLimitEnabled = http?.rateLimit?.enabled ?? true;
 
   app.set("trust proxy", trustProxy);
   app.use(helmet());
@@ -137,6 +146,16 @@ export function createApp({
     ),
   );
   app.use(express.json({ limit: bodySizeLimit }));
+
+  if (rateLimitEnabled) {
+    applyRateLimiters(app, appLogger, {
+      global: {
+        windowMs: http?.rateLimit?.windowMs,
+        max: http?.rateLimit?.max,
+      },
+    });
+  }
+
   app.use((req, res, next) => {
     requestLifecycleTracker.onRequestStart();
     const finalize = () => {
@@ -158,11 +177,60 @@ export function createApp({
   );
 
   app.get("/health", (req, res) => {
-    res.status(200).json({
-      status: "ok",
-      uptimeSeconds: Number(process.uptime().toFixed(3)),
-      requestId: req.requestId,
-    });
+    const envelope: ApiResponseEnvelope<{ status: string; timestamp: string; uptimeSeconds: number; requestId: string }> = {
+      success: true,
+      data: {
+        status: "ok",
+        timestamp: new Date().toISOString(),
+        uptimeSeconds: Number(process.uptime().toFixed(3)),
+        requestId: req.requestId ?? "unknown",
+      },
+    };
+    res.status(200).json(envelope);
+  });
+
+  app.get("/health/db", async (req, res) => {
+    try {
+      if (!dataSource.isInitialized) {
+        const envelope: ApiResponseEnvelope<{ requestId: string }> = {
+          success: false,
+          error: {
+            code: "DB_NOT_INITIALIZED",
+            message: "Database connection is not initialized.",
+          },
+          data: {
+            requestId: req.requestId ?? "unknown",
+          },
+        };
+        res.status(503).json(envelope);
+        return;
+      }
+
+      await dataSource.query("SELECT 1");
+
+      const envelope: ApiResponseEnvelope<{ status: string; timestamp: string; connection: string; requestId: string }> = {
+        success: true,
+        data: {
+          status: "ok",
+          timestamp: new Date().toISOString(),
+          connection: "postgres",
+          requestId: req.requestId ?? "unknown",
+        },
+      };
+      res.status(200).json(envelope);
+    } catch (error) {
+      const envelope: ApiResponseEnvelope<{ requestId: string }> = {
+        success: false,
+        error: {
+          code: "DB_CONNECTION_ERROR",
+          message: "Database connection failed.",
+        },
+        data: {
+          requestId: req.requestId ?? "unknown",
+        },
+      };
+      res.status(503).json(envelope);
+    }
   });
 
   if (metricsEnabled) {
@@ -172,7 +240,11 @@ export function createApp({
     });
   }
 
-  app.use("/api/v1/auth", createAuthRouter(authService));
+  const authRouter = createAuthRouter(authService);
+  if (rateLimitEnabled) {
+    authRouter.use(createAuthRateLimitMiddleware(appLogger));
+  }
+  app.use("/api/v1/auth", authRouter);
 
   // Add invoice routes if service is provided
   if (invoiceService && ipfsConfig) {

src/config/env.ts

@@ -22,6 +22,11 @@ export interface AppConfig {
     corsAllowCredentials: boolean;
     bodySizeLimit: string;
     shutdownTimeoutMs: number;
+    rateLimit?: {
+      enabled: boolean;
+      windowMs: number;
+      max: number;
+    };
   };
   reconciliation: {
     enabled: boolean;
@@ -225,7 +230,7 @@ export function getConfig(): AppConfig {
     },
     http: {
       trustProxy: parseTrustProxy(process.env.TRUST_PROXY),
-      corsAllowedOrigins: parseCsv(process.env.CORS_ALLOWED_ORIGINS),
+      corsAllowedOrigins: parseCsv(process.env.CORS_ORIGIN ?? process.env.CORS_ALLOWED_ORIGINS),
       corsAllowCredentials: parseBoolean(
         process.env.CORS_ALLOW_CREDENTIALS,
         true,
@@ -237,6 +242,15 @@ export function getConfig(): AppConfig {
         DEFAULT_SHUTDOWN_TIMEOUT_MS,
         "HTTP_SHUTDOWN_TIMEOUT_MS",
       ),
+      rateLimit: {
+        enabled: parseBoolean(process.env.RATE_LIMIT_ENABLED, true, "RATE_LIMIT_ENABLED"),
+        windowMs: parsePositiveInteger(
+          process.env.RATE_LIMIT_WINDOW_MS,
+          60 * 1000,
+          "RATE_LIMIT_WINDOW_MS",
+        ),
+        max: parsePositiveInteger(process.env.RATE_LIMIT_MAX, 100, "RATE_LIMIT_MAX"),
+      },
     },
     reconciliation: {
       enabled: parseBoolean(

src/index.ts

@@ -56,6 +56,7 @@ export async function bootstrap(): Promise<ApplicationRuntime> {
       corsAllowCredentials: config.http.corsAllowCredentials,
       bodySizeLimit: config.http.bodySizeLimit,
       nodeEnv: config.nodeEnv,
+      rateLimit: config.http.rateLimit,
     },
     ipfsConfig: config.ipfs,
     requestLifecycleTracker,

src/middleware/error.middleware.ts

@@ -1,11 +1,16 @@
 import type { NextFunction, Request, Response } from "express";
 import type { AppLogger } from "../observability/logger";
-import { HttpError } from "../utils/http-error";
+import type { ApiResponseEnvelope } from "../utils/http-error";
+import { AppError, HttpError } from "../utils/http-error";
 
 export function notFoundMiddleware(_req: Request, _res: Response, next: NextFunction) {
   next(new HttpError(404, "Route not found."));
 }
 
+function sendEnvelopeResponse<T>(res: Response, statusCode: number, payload: ApiResponseEnvelope<T>) {
+  res.status(statusCode).json(payload);
+}
+
 export function createErrorMiddleware(logger: AppLogger) {
   return (
     error: unknown,
@@ -15,18 +20,25 @@ export function createErrorMiddleware(logger: AppLogger) {
   ): void => {
     void next;
 
-    if (error instanceof HttpError) {
+    if (error instanceof AppError || error instanceof HttpError) {
       logger.warn("HTTP request failed.", {
         requestId: req.requestId,
         method: req.method,
         path: req.path,
         statusCode: error.statusCode,
+        code: error.code,
         error: error.message,
       });
-      res.status(error.statusCode).json({
-        error: error.message,
-        details: error.details,
-      });
+
+      const envelope: ApiResponseEnvelope = {
+        success: false,
+        error: {
+          code: error.code,
+          message: error.message,
+        },
+      };
+
+      sendEnvelopeResponse(res, error.statusCode, envelope);
       return;
     }
 
@@ -38,8 +50,14 @@ export function createErrorMiddleware(logger: AppLogger) {
       error: error instanceof Error ? error.message : "Unknown error",
     });
 
-    res.status(500).json({
-      error: "Internal server error.",
-    });
+    const envelope: ApiResponseEnvelope = {
+      success: false,
+      error: {
+        code: "INTERNAL_ERROR",
+        message: "Internal server error.",
+      },
+    };
+
+    sendEnvelopeResponse(res, 500, envelope);
   };
 }