Merge pull request #443 from Chibey-max/blackboxai/354-claim-rate-limiting

feat(rate-limit): #354 per-wallet and global claim submission limits

Author: jhayniffy

backend/docs/rate-limiting.md

@@ -19,6 +19,47 @@ This means authenticated users behind a shared corporate NAT are not penalised c
 > Limits for claim submission (`POST /api/claims/submit`) are additionally governed by
 > a per-policy ledger-window counter (see claim rate limiting docs).
 
+## Claim Submission Rate Limits
+
+Claim submission (`POST /api/claims/submit`) is protected by **three layers** of rate limiting:
+
+1. **Global circuit breaker** — prevents system overload from any source.
+2. **Per-wallet sliding window** — prevents a single wallet from flooding claims.
+3. **Per-policy ledger window** — prevents spam against a single policy.
+
+### Layer 1: Global Circuit Breaker
+
+| Limit | Window | Rationale |
+|---|---|---|
+| 100 claims | 5 minutes | Protects governance capacity and DAO voter attention across all policies. If triggered, all claim submissions are rejected until the window slides. |
+
+### Layer 2: Per-Wallet Sliding Window
+
+| Limit | Window | Rationale |
+|---|---|---|
+| 3 claims | 1 hour | Prevents a single wallet from exhausting governance for a specific tenant or policy type. Aligns with typical legitimate catastrophic-event filing patterns (1–2 claims per hour). |
+
+### Layer 3: Per-Policy Ledger Window
+
+| Limit | Window | Rationale |
+|---|---|---|
+| 5 claims | 17,280 ledgers (~24h) | Prevents spam against an individual policy. Uses ledger-based windows to avoid clock-skew issues. |
+
+### Claim Rate Limit Configuration
+
+Environment variables:
+
+| Variable | Default | Description |
+|---|---|---|
+| `GLOBAL_RATE_LIMIT` | 100 | Global claim submissions per window |
+| `GLOBAL_RATE_LIMIT_WINDOW_SECONDS` | 300 | Global window in seconds |
+| `WALLET_RATE_LIMIT` | 3 | Claims per wallet per window |
+| `WALLET_RATE_LIMIT_WINDOW_SECONDS` | 3600 | Wallet window in seconds |
+| `RATE_LIMIT_DEFAULTS.DEFAULT_LIMIT` | 5 | Per-policy claim limit |
+| `RATE_LIMIT_DEFAULTS.WINDOW_SIZE_LEDGERS` | 17280 | Per-policy window in ledgers |
+
+All values are stored in Redis and survive service restarts.
+
 ## Response Headers
 
 Every response includes:

backend/src/rate-limit/__tests__/rate-limit.service.spec.ts

@@ -0,0 +1,89 @@
+/**
+ * Rate Limit Service Tests
+ *
+ * Tests per-wallet sliding window, global circuit breaker, and limit reset.
+ */
+import { RateLimitService } from '../rate-limit.service';
+import { RedisService } from '../../cache/redis.service';
+import { ConfigService } from '@nestjs/config';
+
+describe('RateLimitService — wallet & global limits', () => {
+  let service: RateLimitService;
+  let redisMock: { getClient: jest.Mock; get: jest.Mock; set: jest.Mock };
+  let redisClient: Record<string, jest.Mock>;
+
+  beforeEach(() => {
+    redisClient = {
+      zremrangebyscore: jest.fn().mockResolvedValue(0),
+      zcard: jest.fn().mockResolvedValue(0),
+      zadd: jest.fn().mockResolvedValue(1),
+      pexpire: jest.fn().mockResolvedValue(1),
+      zrange: jest.fn().mockResolvedValue([]),
+      hset: jest.fn().mockResolvedValue(1),
+      hgetall: jest.fn().mockResolvedValue({}),
+      hget: jest.fn().mockResolvedValue(null),
+      hincrby: jest.fn().mockResolvedValue(1),
+      exists: jest.fn().mockResolvedValue(0),
+    };
+
+    redisMock = {
+      getClient: jest.fn().mockReturnValue(redisClient),
+      get: jest.fn(),
+      set: jest.fn(),
+    };
+
+    const configMock = {
+      get: jest.fn((key: string, fallback: unknown) => fallback),
+    };
+
+    service = new RateLimitService(redisMock as unknown as RedisService, configMock as unknown as ConfigService);
+  });
+
+  describe('checkWalletLimit', () => {
+    it('allows request when under limit', async () => {
+      redisClient.zcard.mockResolvedValue(0);
+      const result = await service.checkWalletLimit('GABC123');
+      expect(result.allowed).toBe(true);
+      expect(result.retryAfterSeconds).toBe(0);
+      expect(redisClient.zadd).toHaveBeenCalled();
+    });
+
+    it('blocks request when limit exceeded', async () => {
+      redisClient.zcard.mockResolvedValue(3);
+      redisClient.zrange.mockResolvedValue(['entry', String(Date.now() - 1800000)]); // 30 min ago
+      const result = await service.checkWalletLimit('GABC123');
+      expect(result.allowed).toBe(false);
+      expect(result.retryAfterSeconds).toBeGreaterThan(0);
+    });
+
+    it('fails open on Redis error', async () => {
+      redisClient.zcard.mockRejectedValue(new Error('Redis down'));
+      const result = await service.checkWalletLimit('GABC123');
+      expect(result.allowed).toBe(true);
+    });
+  });
+
+  describe('checkGlobalLimit', () => {
+    it('allows request when under global limit', async () => {
+      redisClient.zcard.mockResolvedValue(50);
+      const result = await service.checkGlobalLimit();
+      expect(result.allowed).toBe(true);
+      expect(result.retryAfterSeconds).toBe(0);
+    });
+
+    it('blocks request when global circuit breaker triggered', async () => {
+      redisClient.zcard.mockResolvedValue(100);
+      redisClient.zrange.mockResolvedValue(['entry', String(Date.now() - 120000)]); // 2 min ago
+      const result = await service.checkGlobalLimit();
+      expect(result.allowed).toBe(false);
+      expect(result.retryAfterSeconds).toBeGreaterThan(0);
+    });
+
+    it('fails open on Redis error', async () => {
+      redisClient.zcard.mockRejectedValue(new Error('Redis down'));
+      const result = await service.checkGlobalLimit();
+      expect(result.allowed).toBe(true);
+    });
+  });
+});
+

backend/src/rate-limit/rate-limit.constants.ts

@@ -1,3 +1,19 @@
+/**
+ * Per-wallet rate limit: number of claims allowed per wallet per time window.
+ */
+export const WALLET_RATE_LIMIT_DEFAULTS = {
+  LIMIT: 3,                    // claims per wallet per window
+  WINDOW_SECONDS: 3600,        // 1 hour sliding window
+};
+
+/**
+ * Global rate limit circuit breaker: total claims across all wallets per window.
+ */
+export const GLOBAL_RATE_LIMIT_DEFAULTS = {
+  LIMIT: 100,                  // total claims per window across all wallets
+  WINDOW_SECONDS: 300,         // 5 minute sliding window
+};
+
 export const RATE_LIMIT_DEFAULTS = {
   DEFAULT_LIMIT: 5,              // claims per window
   WINDOW_SIZE_LEDGERS: 17_280,   // ~24 hours at 5s/ledger
@@ -9,4 +25,6 @@ export const REDIS_KEYS = {
   COUNTER: (policyId: string) => `rate_limit:counter:${policyId}`,
   CONFIG: (policyId: string) => `rate_limit:config:${policyId}`,
   DEFAULTS: 'rate_limit:defaults',
+  WALLET_WINDOW: (wallet: string) => `rate_limit:wallet:${wallet}`,
+  GLOBAL_WINDOW: 'rate_limit:global',
 };

backend/src/rate-limit/rate-limit.exception.ts

@@ -6,23 +6,31 @@ export interface RateLimitErrorDetails {
   limit: number;
   windowResetLedger: number;
   remainingLedgers: number;
+  /** Seconds until the client should retry */
+  retryAfterSeconds?: number;
+  /** Type of limit that was exceeded */
+  limitType?: 'policy' | 'wallet' | 'global';
 }
 
 export class RateLimitException extends HttpException {
   constructor(details: RateLimitErrorDetails) {
+    const typeLabel = details.limitType ?? 'policy';
     const message =
-      `Rate limit exceeded for policy ${details.policyId}. ` +
+      `Rate limit exceeded for ${typeLabel} ${details.policyId}. ` +
       `Current: ${details.currentCount}/${details.limit}. ` +
       `Window resets in ${details.remainingLedgers} ledgers (ledger ${details.windowResetLedger}).`;
 
-    super(
-      {
-        statusCode: HttpStatus.TOO_MANY_REQUESTS,
-        error: 'Too Many Requests',
-        message,
-        details,
-      },
-      HttpStatus.TOO_MANY_REQUESTS,
-    );
+    const responseBody: Record<string, unknown> = {
+      statusCode: HttpStatus.TOO_MANY_REQUESTS,
+      error: 'Too Many Requests',
+      message,
+      details,
+    };
+
+    if (details.retryAfterSeconds && details.retryAfterSeconds > 0) {
+      responseBody.retryAfter = details.retryAfterSeconds;
+    }
+
+    super(responseBody, HttpStatus.TOO_MANY_REQUESTS);
   }
 }

backend/src/rate-limit/rate-limit.guard.ts

@@ -1,4 +1,5 @@
 import { Injectable, CanActivate, ExecutionContext, Logger } from '@nestjs/common';
+import { Response } from 'express';
 import { RateLimitService } from './rate-limit.service';
 import { RateLimitException } from './rate-limit.exception';
 import { SorobanService } from '../rpc/soroban.service';
@@ -14,6 +15,7 @@ export class RateLimitGuard implements CanActivate {
 
   async canActivate(context: ExecutionContext): Promise<boolean> {
     const request = context.switchToHttp().getRequest();
+    const response = context.switchToHttp().getResponse<Response>();
     const { policyId } = request.body;
 
     // If policyId is missing, let validation handle it
@@ -22,22 +24,58 @@ export class RateLimitGuard implements CanActivate {
     }
 
     try {
-      // Get current ledger from Soroban
-      const currentLedger = await this.soroban.getLatestLedger();
+      // ── 1. Global circuit breaker ───────────────────────────────────────
+      const globalCheck = await this.rateLimitService.checkGlobalLimit();
+      if (!globalCheck.allowed) {
+        response.setHeader('Retry-After', String(globalCheck.retryAfterSeconds));
+        throw new RateLimitException({
+          policyId: 'global',
+          currentCount: globalCheck.retryAfterSeconds,
+          limit: 0,
+          windowResetLedger: 0,
+          remainingLedgers: 0,
+          retryAfterSeconds: globalCheck.retryAfterSeconds,
+          limitType: 'global',
+        });
+      }
 
-      // Check rate limit and increment counter
+      // ── 2. Per-wallet sliding window ────────────────────────────────────
+      const walletAddress = this.extractWalletAddress(request, policyId);
+      if (walletAddress) {
+        const walletCheck = await this.rateLimitService.checkWalletLimit(walletAddress);
+        if (!walletCheck.allowed) {
+          response.setHeader('Retry-After', String(walletCheck.retryAfterSeconds));
+          throw new RateLimitException({
+            policyId: walletAddress,
+            currentCount: walletCheck.retryAfterSeconds,
+            limit: 0,
+            windowResetLedger: 0,
+            remainingLedgers: 0,
+            retryAfterSeconds: walletCheck.retryAfterSeconds,
+            limitType: 'wallet',
+          });
+        }
+      }
+
+      // ── 3. Per-policy ledger-based limit ────────────────────────────────
+      const currentLedger = await this.soroban.getLatestLedger();
       const result = await this.rateLimitService.checkAndIncrement(
         policyId,
         currentLedger,
       );
 
       if (!result.allowed) {
+        const retryAfterLedgers = result.windowResetLedger - currentLedger;
+        const retryAfterSeconds = Math.max(1, retryAfterLedgers * 5); // ~5s per ledger
+        response.setHeader('Retry-After', String(retryAfterSeconds));
         throw new RateLimitException({
           policyId,
           currentCount: result.currentCount,
           limit: result.limit,
           windowResetLedger: result.windowResetLedger,
-          remainingLedgers: result.windowResetLedger - currentLedger,
+          remainingLedgers: retryAfterLedgers,
+          retryAfterSeconds,
+          limitType: 'policy',
         });
       }
 
@@ -53,4 +91,31 @@ export class RateLimitGuard implements CanActivate {
       return true;
     }
   }
+
+  /**
+   * Extract wallet address from request (JWT user, body, or policyId).
+   */
+  private extractWalletAddress(request: { user?: { walletAddress?: string }; body?: { holder?: string; policyId?: string } }, policyId?: string): string | undefined {
+    // 1. Authenticated user
+    if (request.user?.walletAddress) {
+      return request.user.walletAddress;
+    }
+
+    // 2. Explicit holder field in body
+    if (request.body?.holder) {
+      return request.body.holder;
+    }
+
+    // 3. Parse from policyId (format: holderAddress:policyId)
+    if (policyId && policyId.includes(':')) {
+      const parts = policyId.split(':');
+      // Stellar addresses start with G and are 56 chars
+      const candidate = parts[0];
+      if (candidate.length >= 56 && candidate.startsWith('G')) {
+        return candidate;
+      }
+    }
+
+    return undefined;
+  }
 }