Merge pull request InsurNiffy#1064 from kceeglo345-dev/feat/claim-timeline-admin-allowlist

feat(backend): add claim timeline API and admin IP allowlist middleware

Author: jhayniffy

backend/src/admin/__tests__/allowlist.middleware.spec.ts

@@ -0,0 +1,193 @@
+import { AllowlistMiddleware } from '../middleware/allowlist.middleware';
+import { ForbiddenException } from '@nestjs/common';
+import type { Request, Response, NextFunction } from 'express';
+
+function mockConfig(cidrs: string) {
+  return { get: jest.fn((key: string) => (key === 'ADMIN_ALLOWED_CIDRS' ? cidrs : undefined)) };
+}
+
+function makeReq(ip: string, forwarded?: string): Request {
+  return {
+    ip,
+    get: jest.fn((header: string) => {
+      if (header === 'X-Forwarded-For') return forwarded ?? undefined;
+      return undefined;
+    }),
+    socket: { remoteAddress: ip },
+  } as unknown as Request;
+}
+
+function makeRes(): Response {
+  return { status: jest.fn().mockReturnThis(), json: jest.fn() } as unknown as Response;
+}
+
+describe('AllowlistMiddleware', () => {
+  describe('empty allowlist (backward compatible)', () => {
+    it('allows any IP when ADMIN_ALLOWED_CIDRS is empty', () => {
+      const mw = new AllowlistMiddleware(mockConfig('') as never);
+      const next: NextFunction = jest.fn();
+      mw.use(makeReq('10.0.0.1'), makeRes(), next);
+      expect(next).toHaveBeenCalled();
+    });
+
+    it('allows any IP when ADMIN_ALLOWED_CIDRS is unset', () => {
+      const mw = new AllowlistMiddleware(mockConfig('') as never);
+      const next: NextFunction = jest.fn();
+      mw.use(makeReq('::1'), makeRes(), next);
+      expect(next).toHaveBeenCalled();
+    });
+  });
+
+  describe('single CIDR rule', () => {
+    it('allows IP within the CIDR range', () => {
+      const mw = new AllowlistMiddleware(mockConfig('10.0.0.0/24') as never);
+      const next: NextFunction = jest.fn();
+      mw.use(makeReq('10.0.0.42'), makeRes(), next);
+      expect(next).toHaveBeenCalled();
+    });
+
+    it('blocks IP outside the CIDR range with ForbiddenException', () => {
+      const mw = new AllowlistMiddleware(mockConfig('10.0.0.0/24') as never);
+      const next: NextFunction = jest.fn();
+      expect(() => mw.use(makeReq('10.0.1.1'), makeRes(), next)).toThrow(ForbiddenException);
+      expect(next).not.toHaveBeenCalled();
+    });
+
+    it('blocks IP with 403 — no auth processing happens', () => {
+      const mw = new AllowlistMiddleware(mockConfig('10.0.0.0/24') as never);
+      const next: NextFunction = jest.fn();
+      try {
+        mw.use(makeReq('192.168.1.1'), makeRes(), next);
+      } catch (e) {
+        expect(e).toBeInstanceOf(ForbiddenException);
+        expect((e as ForbiddenException).getStatus()).toBe(403);
+        expect((e as ForbiddenException).message).toBe('Access denied');
+      }
+      expect(next).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('multiple CIDR rules', () => {
+    it('allows IP matching any of the rules', () => {
+      const mw = new AllowlistMiddleware(mockConfig('10.0.0.0/8,192.168.0.0/16') as never);
+      const next: NextFunction = jest.fn();
+      mw.use(makeReq('10.1.2.3'), makeRes(), next);
+      expect(next).toHaveBeenCalled();
+    });
+
+    it('blocks IP not matching any rule', () => {
+      const mw = new AllowlistMiddleware(mockConfig('10.0.0.0/8,192.168.0.0/16') as never);
+      const next: NextFunction = jest.fn();
+      expect(() => mw.use(makeReq('172.16.0.1'), makeRes(), next)).toThrow(ForbiddenException);
+      expect(next).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('IPv6 support', () => {
+    it('allows IPv6 within the CIDR range', () => {
+      const mw = new AllowlistMiddleware(mockConfig('2001:db8::/32') as never);
+      const next: NextFunction = jest.fn();
+      mw.use(makeReq('2001:db8:dead:beef::1'), makeRes(), next);
+      expect(next).toHaveBeenCalled();
+    });
+
+    it('blocks IPv6 outside the CIDR range', () => {
+      const mw = new AllowlistMiddleware(mockConfig('2001:db8::/32') as never);
+      const next: NextFunction = jest.fn();
+      expect(() => mw.use(makeReq('2001:db9::1'), makeRes(), next)).toThrow(ForbiddenException);
+      expect(next).not.toHaveBeenCalled();
+    });
+
+    it('handles IPv6 with :: compression', () => {
+      const mw = new AllowlistMiddleware(mockConfig('fd00::/8') as never);
+      const next: NextFunction = jest.fn();
+      mw.use(makeReq('fd12:3456:789a::1'), makeRes(), next);
+      expect(next).toHaveBeenCalled();
+    });
+
+    it('handles ::1 loopback', () => {
+      const mw = new AllowlistMiddleware(mockConfig('::1/128') as never);
+      const next: NextFunction = jest.fn();
+      mw.use(makeReq('::1'), makeRes(), next);
+      expect(next).toHaveBeenCalled();
+    });
+  });
+
+  describe('IPv4-mapped IPv6', () => {
+    it('matches IPv4-mapped address against IPv4 CIDR rule', () => {
+      const mw = new AllowlistMiddleware(mockConfig('10.0.0.0/24') as never);
+      const next: NextFunction = jest.fn();
+      mw.use(makeReq('::ffff:10.0.0.5'), makeRes(), next);
+      expect(next).toHaveBeenCalled();
+    });
+
+    it('blocks IPv4-mapped address outside the IPv4 CIDR', () => {
+      const mw = new AllowlistMiddleware(mockConfig('10.0.0.0/24') as never);
+      const next: NextFunction = jest.fn();
+      expect(() => mw.use(makeReq('::ffff:172.16.0.1'), makeRes(), next)).toThrow(ForbiddenException);
+      expect(next).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('X-Forwarded-For', () => {
+    it('uses X-Forwarded-For header when present', () => {
+      const mw = new AllowlistMiddleware(mockConfig('10.0.0.0/24') as never);
+      const next: NextFunction = jest.fn();
+      // req.ip is blocked but X-Forwarded-For is allowed
+      mw.use(makeReq('192.168.1.1', '10.0.0.5'), makeRes(), next);
+      expect(next).toHaveBeenCalled();
+    });
+
+    it('takes first IP from X-Forwarded-For chain', () => {
+      const mw = new AllowlistMiddleware(mockConfig('10.0.0.0/24') as never);
+      const next: NextFunction = jest.fn();
+      mw.use(makeReq('192.168.1.1', '10.0.0.5, 192.168.1.1'), makeRes(), next);
+      expect(next).toHaveBeenCalled();
+    });
+  });
+
+  describe('non-leaky error message', () => {
+    it('does not expose the allowlist config in the error', () => {
+      const mw = new AllowlistMiddleware(mockConfig('10.0.0.0/24,192.168.0.0/16') as never);
+      const next: NextFunction = jest.fn();
+      try {
+        mw.use(makeReq('1.2.3.4'), makeRes(), next);
+      } catch (e) {
+        expect(e).toBeInstanceOf(ForbiddenException);
+        expect((e as ForbiddenException).message).toBe('Access denied');
+        // Should not leak CIDR ranges
+        expect((e as ForbiddenException).message).not.toContain('10.0.0.0');
+        expect((e as ForbiddenException).message).not.toContain('192.168.0.0');
+      }
+    });
+  });
+
+  describe('edge cases', () => {
+    it('allows exact /32 match', () => {
+      const mw = new AllowlistMiddleware(mockConfig('10.0.0.42/32') as never);
+      const next: NextFunction = jest.fn();
+      mw.use(makeReq('10.0.0.42'), makeRes(), next);
+      expect(next).toHaveBeenCalled();
+    });
+
+    it('blocks non-matching exact /32', () => {
+      const mw = new AllowlistMiddleware(mockConfig('10.0.0.42/32') as never);
+      const next: NextFunction = jest.fn();
+      expect(() => mw.use(makeReq('10.0.0.43'), makeRes(), next)).toThrow(ForbiddenException);
+    });
+
+    it('allows /0 (all IPs)', () => {
+      const mw = new AllowlistMiddleware(mockConfig('0.0.0.0/0') as never);
+      const next: NextFunction = jest.fn();
+      mw.use(makeReq('8.8.8.8'), makeRes(), next);
+      expect(next).toHaveBeenCalled();
+    });
+
+    it('skips invalid CIDR entries without crashing', () => {
+      const mw = new AllowlistMiddleware(mockConfig('not-a-cidr,10.0.0.0/24') as never);
+      const next: NextFunction = jest.fn();
+      mw.use(makeReq('10.0.0.1'), makeRes(), next);
+      expect(next).toHaveBeenCalled();
+    });
+  });
+});

backend/src/admin/admin.module.ts

@@ -15,6 +15,7 @@ import { MaintenanceModule } from '../maintenance/maintenance.module';
 import { RateLimitModule } from '../rate-limit/rate-limit.module';
 import { QueueMonitorService } from '../queues/queue-monitor.service';
 import { BullBoardMiddleware } from './bull-board.middleware';
+import { AllowlistMiddleware } from './middleware/allowlist.middleware';
 import { MetricsModule } from '../metrics/metrics.module';
 import { CacheModule } from '../cache/cache.module';
 import { RpcModule } from '../rpc/rpc.module';
@@ -43,6 +44,11 @@ import { CommentRepository } from '../claims/comments/comment.repository';
 })
 export class AdminModule implements NestModule {
   configure(consumer: MiddlewareConsumer) {
+    // IP allowlist runs before auth guards to fail closed for blocked IPs
+    consumer
+      .apply(AllowlistMiddleware)
+      .forRoutes({ path: 'admin*', method: RequestMethod.ALL });
+
     consumer
       .apply(BullBoardMiddleware)
       .forRoutes({ path: 'admin/queues*', method: RequestMethod.ALL });

backend/src/admin/middleware/allowlist.middleware.ts

@@ -0,0 +1,173 @@
+import { Injectable, NestMiddleware, ForbiddenException, Logger } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { Request, Response, NextFunction } from 'express';
+import { isIPv4, isIPv6 } from 'net';
+
+interface CidrRule {
+  network: bigint;
+  mask: bigint;
+  family: 4 | 6;
+}
+
+@Injectable()
+export class AllowlistMiddleware implements NestMiddleware {
+  private readonly logger = new Logger(AllowlistMiddleware.name);
+  private readonly rules: CidrRule[] = [];
+  private readonly isEmpty: boolean;
+
+  constructor(private readonly configService: ConfigService) {
+    const raw = this.configService.get<string>('ADMIN_ALLOWED_CIDRS') ?? '';
+    const parts = raw
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+
+    for (const part of parts) {
+      const rule = parseCidr(part);
+      if (rule) {
+        this.rules.push(rule);
+      } else {
+        this.logger.warn(`Invalid CIDR in ADMIN_ALLOWED_CIDRS: "${part}" — skipping`);
+      }
+    }
+
+    this.isEmpty = this.rules.length === 0;
+    if (this.isEmpty) {
+      this.logger.warn(
+        'ADMIN_ALLOWED_CIDRS is empty/unset — all IPs are allowed. ' +
+        'Set this variable to restrict admin endpoints to trusted CIDR ranges.',
+      );
+    }
+  }
+
+  use(req: Request, res: Response, next: NextFunction): void {
+    if (this.isEmpty) {
+      next();
+      return;
+    }
+
+    const clientIp = getClientIp(req);
+    const allowed = this.rules.some((rule) => ipMatchesCidr(clientIp, rule));
+
+    if (!allowed) {
+      this.logger.warn(`Admin access denied for IP: ${clientIp}`);
+      throw new ForbiddenException('Access denied');
+    }
+
+    next();
+  }
+}
+
+/**
+ * Extract the client IP from a request, respecting X-Forwarded-For.
+ */
+function getClientIp(req: Request): string {
+  const forwarded = req.get('X-Forwarded-For');
+  if (forwarded) {
+    const first = forwarded.split(',')[0].trim();
+    if (first) return first;
+  }
+  return req.ip || req.socket?.remoteAddress || 'unknown';
+}
+
+/**
+ * Parse a CIDR notation string into a rule object.
+ * Supports both IPv4 (e.g. "10.0.0.0/8") and IPv6 (e.g. "2001:db8::/32").
+ */
+function parseCidr(input: string): CidrRule | null {
+  const parts = input.split('/');
+  const addr = parts[0];
+  const prefixBits = parts[1] ? parseInt(parts[1], 10) : null;
+
+  if (isIPv4(addr)) {
+    const bits = prefixBits ?? 32;
+    if (bits < 0 || bits > 32) return null;
+    const ipInt = ipv4ToBigInt(addr);
+    const mask = bits === 0 ? BigInt(0) : (BigInt(1) << BigInt(32)) - (BigInt(1) << BigInt(32 - bits));
+    return { network: ipInt & mask, mask, family: 4 };
+  }
+
+  if (isIPv6(addr)) {
+    const bits = prefixBits ?? 128;
+    if (bits < 0 || bits > 128) return null;
+    const ipBig = ipv6ToBigInt(addr);
+    const mask = bits === 0 ? BigInt(0) : (BigInt(1) << BigInt(128)) - (BigInt(1) << BigInt(128 - bits));
+    return { network: ipBig & mask, mask, family: 6 };
+  }
+
+  return null;
+}
+
+/**
+ * Check whether an IP string falls within a CIDR rule.
+ * Handles IPv4-mapped IPv6 addresses (e.g. ::ffff:10.0.0.1).
+ */
+function ipMatchesCidr(ip: string, rule: CidrRule): boolean {
+  if (isIPv4(ip)) {
+    if (rule.family === 6) return false; // different families
+    const ipInt = ipv4ToBigInt(ip);
+    return (ipInt & rule.mask) === rule.network;
+  }
+
+  if (isIPv6(ip)) {
+    if (rule.family === 4) {
+      // Check if the IPv6 address is an IPv4-mapped address
+      const mapped = extractV4FromMappedV6(ip);
+      if (mapped) {
+        const ipInt = ipv4ToBigInt(mapped);
+        return (ipInt & rule.mask) === rule.network;
+      }
+      return false;
+    }
+    const ipBig = ipv6ToBigInt(ip);
+    return (ipBig & rule.mask) === rule.network;
+  }
+
+  return false;
+}
+
+function ipv4ToBigInt(ip: string): bigint {
+  const octets = ip.split('.').map((o) => parseInt(o, 10));
+  return BigInt(octets[0]) << BigInt(24) |
+         BigInt(octets[1]) << BigInt(16) |
+         BigInt(octets[2]) << BigInt(8) |
+         BigInt(octets[3]);
+}
+
+function ipv6ToBigInt(ip: string): bigint {
+  const hextets = expandV6(ip);
+  let result = BigInt(0);
+  for (const h of hextets) {
+    result = (result << BigInt(16)) | BigInt(parseInt(h, 16));
+  }
+  return result;
+}
+
+/**
+ * Expand an IPv6 address into 8 hextets, handling :: compression.
+ */
+function expandV6(ip: string): string[] {
+  const lower = ip.toLowerCase();
+  const parts = lower.split('::');
+
+  if (parts.length === 2) {
+    const left = parts[0] ? parts[0].split(':').filter(Boolean) : [];
+    const right = parts[1] ? parts[1].split(':').filter(Boolean) : [];
+    const fill = 8 - left.length - right.length;
+    return [...left, ...new Array(fill).fill('0'), ...right];
+  }
+
+  return lower.split(':').filter(Boolean);
+}
+
+/**
+ * If an IPv6 address is an IPv4-mapped IPv6 address (::ffff:x.x.x.x),
+ * extract and return the embedded IPv4 string. Otherwise return null.
+ */
+function extractV4FromMappedV6(ip: string): string | null {
+  const lower = ip.toLowerCase();
+  if (!lower.startsWith('::ffff:')) return null;
+  const candidate = lower.slice(7); // strip "::ffff:"
+  if (isIPv4(candidate)) return candidate;
+  return null;
+}