feat: add IP whitelist middleware for admin routes

.env.example

@@ -61,4 +61,7 @@ SENDGRID_API_KEY=SG.xxxxxxxxxxxxx
 FROM_EMAIL=noreply@stellarsettle.com
 
 #dev-secret-key
-ADMIN_API_KEY=dev-secret-key
+ADMIN_API_KEY=dev-secret-key
+
+# IP Whitelist for admin routes (comma-separated CIDR blocks)
+ADMIN_IP_WHITELIST=127.0.0.1,::1

package.json

@@ -26,6 +26,7 @@
     "express": "^5.2.1",
     "express-rate-limit": "^7.1.5",
     "helmet": "^7.1.0",
+    "ip-range-check": "^0.2.0",
     "joi": "^17.11.0",
     "jsonwebtoken": "^9.0.2",
     "multer": "^2.1.1",

src/app.ts

@@ -15,6 +15,7 @@ import { createInvoiceRouter } from "./routes/invoice.routes";
 import { createInvestmentRouter } from "./routes/investment.routes";
 import { createSettlementRouter } from "./routes/settlement.routes";
 import { createMarketplaceRouter } from "./routes/marketplace.routes";
+import { createAdminRouter } from "./routes/admin/admin.routes";
 
 import type { AuthService } from "./services/auth.service";
 import type { NotificationService } from "./services/notification.service";
@@ -189,6 +190,10 @@ export function createApp({
     app.use("/api/v1/marketplace", createMarketplaceRouter({ marketplaceService }));
   }
 
+  if (config?.admin.ipWhitelist.length) {
+    app.use("/api/v1/admin", createAdminRouter({ dataSource, allowedCidrs: config.admin.ipWhitelist }));
+  }
+
   app.use(notFoundMiddleware);
   app.use(createErrorMiddleware(appLogger));
 

src/config/env.ts

@@ -60,6 +60,9 @@ export interface AppConfig {
   kyc: {
     skipVerification: boolean;
   };
+  admin: {
+    ipWhitelist: string[];
+  };
 }
 
 
@@ -287,5 +290,9 @@ export function getConfig(): AppConfig {
         "SKIP_KYC_VERIFICATION"
       ),
     },
+
+    admin: {
+      ipWhitelist: parseCsv(process.env.ADMIN_IP_WHITELIST),
+    },
   };
 }

src/middleware/ip-whitelist.middleware.ts

@@ -0,0 +1,19 @@
+import type { NextFunction, Request, Response } from "express";
+import ipRangeCheck from "ip-range-check";
+
+export function ipWhitelistMiddleware(allowedCidrs: string[]) {
+  return (req: Request, res: Response, next: NextFunction): void => {
+    const clientIp =
+      (req.headers["x-forwarded-for"] as string)?.split(",")[0]?.trim() ||
+      req.ip ||
+      req.socket.remoteAddress;
+
+    if (!clientIp || !ipRangeCheck(clientIp, allowedCidrs)) {
+      return res.status(403).json({
+        error: "Access denied: IP address not authorized.",
+      });
+    }
+
+    next();
+  };
+}

src/routes/admin/admin.routes.ts

@@ -0,0 +1,31 @@
+import { Router } from "express";
+import { DataSource } from "typeorm";
+
+import { ipWhitelistMiddleware } from "@/middleware/ip-whitelist.middleware";
+import { approveKYC } from "./approve-kyc";
+import { rejectKYC } from "./reject-kyc";
+
+export interface AdminRouterDependencies {
+  dataSource: DataSource;
+  allowedCidrs: string[];
+}
+
+export function createAdminRouter({
+  dataSource,
+  allowedCidrs,
+}: AdminRouterDependencies): Router {
+  const router = Router();
+  const ipWhitelist = ipWhitelistMiddleware(allowedCidrs);
+
+  router.use(ipWhitelist);
+
+  router.post("/approve-kyc", (req, res) => {
+    approveKYC(req, res, dataSource);
+  });
+
+  router.post("/reject-kyc", (req, res) => {
+    rejectKYC(req, res, dataSource);
+  });
+
+  return router;
+}

tests/unit/ip-whitelist.middleware.test.ts

@@ -0,0 +1,166 @@
+import { ipWhitelistMiddleware } from "@/middleware/ip-whitelist.middleware";
+
+describe("ipWhitelistMiddleware", () => {
+  const allowedCidrs = ["127.0.0.0/8", "::1/128", "10.0.0.0/8"];
+
+  function makeReq(overrides: Record<string, unknown> = {}) {
+    return {
+      ip: undefined as string | undefined,
+      headers: {} as Record<string, string>,
+      socket: { remoteAddress: undefined as string | undefined },
+      ...overrides,
+    };
+  }
+
+  function makeRes() {
+    return {
+      status: jest.fn().mockReturnThis(),
+      json: jest.fn().mockReturnThis(),
+    };
+  }
+
+  function makeNext() {
+    return jest.fn();
+  }
+
+  it("calls next() when client IP is in the whitelist CIDR", () => {
+    const middleware = ipWhitelistMiddleware(allowedCidrs);
+    const req = makeReq({ ip: "127.0.0.1" });
+    const res = makeRes();
+    const next = makeNext();
+
+    middleware(req as never, res as never, next as never);
+
+    expect(next).toHaveBeenCalledTimes(1);
+    expect(res.status).not.toHaveBeenCalled();
+  });
+
+  it("calls next() when client IP matches a CIDR in the whitelist", () => {
+    const middleware = ipWhitelistMiddleware(["192.168.1.0/24"]);
+    const req = makeReq({ ip: "192.168.1.42" });
+    const res = makeRes();
+    const next = makeNext();
+
+    middleware(req as never, res as never, next as never);
+
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+
+  it("returns 403 when client IP is not in any whitelisted CIDR", () => {
+    const middleware = ipWhitelistMiddleware(allowedCidrs);
+    const req = makeReq({ ip: "203.0.113.50" });
+    const res = makeRes();
+    const next = makeNext();
+
+    middleware(req as never, res as never, next as never);
+
+    expect(next).not.toHaveBeenCalled();
+    expect(res.status).toHaveBeenCalledWith(403);
+    expect(res.json).toHaveBeenCalledWith({
+      error: "Access denied: IP address not authorized.",
+    });
+  });
+
+  it("returns 403 when client IP is undefined and no fallback is available", () => {
+    const middleware = ipWhitelistMiddleware(allowedCidrs);
+    const req = makeReq({ ip: undefined, socket: { remoteAddress: undefined } });
+    const res = makeRes();
+    const next = makeNext();
+
+    middleware(req as never, res as never, next as never);
+
+    expect(next).not.toHaveBeenCalled();
+    expect(res.status).toHaveBeenCalledWith(403);
+  });
+
+  it("extracts client IP from X-Forwarded-For header", () => {
+    const middleware = ipWhitelistMiddleware(allowedCidrs);
+    const req = makeReq({
+      headers: { "x-forwarded-for": "127.0.0.1, 70.41.3.18, 150.172.238.178" },
+    });
+    const res = makeRes();
+    const next = makeNext();
+
+    middleware(req as never, res as never, next as never);
+
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+
+  it("returns 403 when the first IP in X-Forwarded-For is not whitelisted", () => {
+    const middleware = ipWhitelistMiddleware(allowedCidrs);
+    const req = makeReq({
+      headers: { "x-forwarded-for": "203.0.113.50, 127.0.0.1" },
+    });
+    const res = makeRes();
+    const next = makeNext();
+
+    middleware(req as never, res as never, next as never);
+
+    expect(next).not.toHaveBeenCalled();
+    expect(res.status).toHaveBeenCalledWith(403);
+  });
+
+  it("falls back to req.socket.remoteAddress when req.ip is undefined", () => {
+    const middleware = ipWhitelistMiddleware(allowedCidrs);
+    const req = makeReq({
+      ip: undefined,
+      socket: { remoteAddress: "::1" },
+    });
+    const res = makeRes();
+    const next = makeNext();
+
+    middleware(req as never, res as never, next as never);
+
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+
+  it("returns 403 when req.socket.remoteAddress is not in whitelist", () => {
+    const middleware = ipWhitelistMiddleware(allowedCidrs);
+    const req = makeReq({
+      ip: undefined,
+      socket: { remoteAddress: "203.0.113.50" },
+    });
+    const res = makeRes();
+    const next = makeNext();
+
+    middleware(req as never, res as never, next as never);
+
+    expect(next).not.toHaveBeenCalled();
+    expect(res.status).toHaveBeenCalledWith(403);
+  });
+
+  it("returns 403 for an empty allowed CIDRs list", () => {
+    const middleware = ipWhitelistMiddleware([]);
+    const req = makeReq({ ip: "127.0.0.1" });
+    const res = makeRes();
+    const next = makeNext();
+
+    middleware(req as never, res as never, next as never);
+
+    expect(next).not.toHaveBeenCalled();
+    expect(res.status).toHaveBeenCalledWith(403);
+  });
+
+  it("works with IPv6 whitelisted addresses", () => {
+    const middleware = ipWhitelistMiddleware(["::1/128"]);
+    const req = makeReq({ ip: "::1" });
+    const res = makeRes();
+    const next = makeNext();
+
+    middleware(req as never, res as never, next as never);
+
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+
+  it("returns 403 for IPv6 addresses not in the whitelist", () => {
+    const middleware = ipWhitelistMiddleware(["::1/128"]);
+    const req = makeReq({ ip: "2001:db8::1" });
+    const res = makeRes();
+    const next = makeNext();
+
+    middleware(req as never, res as never, next as never);
+
+    expect(next).not.toHaveBeenCalled();
+    expect(res.status).toHaveBeenCalledWith(403);
+  });
+});