feat(rate-limit): per-user limiters for OCR, AI, and exports

Adds three named rate limiters to the existing Redis sliding-window
catalog and a withRateLimit wrapper that composes inside withAuth.
Wires the OCR limiter into the receipt-scan endpoint so a runaway
client can't burn through the AI budget in a tight loop.

- ocr: 10/min/user
- ai: 60/min/user (reserved for future server-side AI surfaces)
- exports: 30/hour/user (reserved for GDPR bundle, PDF, CSV exports)

429 responses include X-RateLimit-* headers and a Retry-After hint.

Tests: 771/771 vitest (was 766) — +5 rate-limit tests covering catalog
shape, sliding window, cross-prefix isolation, cross-user isolation,
and resetAt timestamp.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/app/api/v1/expenses/scan-receipt/route.ts

@@ -1,6 +1,6 @@
 import { NextResponse } from 'next/server';
 
-import { withAuth, withPermission } from '@/lib/api/helpers';
+import { withAuth, withPermission, withRateLimit } from '@/lib/api/helpers';
 import { errorResponse } from '@/lib/errors';
 import { logger } from '@/lib/logger';
 import { getResolvedOcrConfig } from '@/lib/services/ocr-config.service';
@@ -22,92 +22,96 @@ const EMPTY: ParsedReceipt = {
 };
 
 export const POST = withAuth(
-  withPermission('expenses', 'create', async (req, ctx) => {
-    try {
-      const formData = await req.formData();
-      const file = formData.get('file') as File | null;
-      if (!file) {
-        return NextResponse.json({ error: 'No file provided' }, { status: 400 });
-      }
-      const buffer = Buffer.from(await file.arrayBuffer());
-      const mimeType = file.type || 'image/jpeg';
-
-      const config = await getResolvedOcrConfig(ctx.portId);
-      // Tesseract.js (in-browser) is the default. The server only invokes
-      // an AI provider when (a) the port admin has flipped `aiEnabled` on
-      // and (b) a key resolves. Otherwise the client falls back to its
-      // local Tesseract result.
-      if (!config.aiEnabled) {
-        return NextResponse.json({
-          data: { parsed: EMPTY, source: 'manual', reason: 'ai-disabled' },
-        });
-      }
-      if (!config.apiKey) {
-        return NextResponse.json({
-          data: { parsed: EMPTY, source: 'manual', reason: 'no-ocr-configured' },
-        });
-      }
-
-      // Per-port budget gate — refuse the call before we spend tokens
-      // when the port has already hit its hard cap, or when the request
-      // would push it past the cap. Soft-cap warnings ride along on the
-      // success response so the UI can show a banner without blocking.
-      const budget = await checkBudget({
-        portId: ctx.portId,
-        estimatedTokens: OCR_ESTIMATED_TOKENS,
-      });
-      if (!budget.ok) {
-        return NextResponse.json({
-          data: {
-            parsed: EMPTY,
-            source: 'manual',
-            reason: 'budget-exceeded',
-            providerError: `AI budget reached (${budget.usedTokens}/${budget.capTokens} tokens this period).`,
-          },
-        });
-      }
-
+  withPermission(
+    'expenses',
+    'create',
+    withRateLimit('ocr', async (req, ctx) => {
       try {
-        const result = await runOcr({
-          provider: config.provider,
-          model: config.model,
-          apiKey: config.apiKey,
-          imageBuffer: buffer,
-          mimeType,
-        });
-        await recordAiUsage({
+        const formData = await req.formData();
+        const file = formData.get('file') as File | null;
+        if (!file) {
+          return NextResponse.json({ error: 'No file provided' }, { status: 400 });
+        }
+        const buffer = Buffer.from(await file.arrayBuffer());
+        const mimeType = file.type || 'image/jpeg';
+
+        const config = await getResolvedOcrConfig(ctx.portId);
+        // Tesseract.js (in-browser) is the default. The server only invokes
+        // an AI provider when (a) the port admin has flipped `aiEnabled` on
+        // and (b) a key resolves. Otherwise the client falls back to its
+        // local Tesseract result.
+        if (!config.aiEnabled) {
+          return NextResponse.json({
+            data: { parsed: EMPTY, source: 'manual', reason: 'ai-disabled' },
+          });
+        }
+        if (!config.apiKey) {
+          return NextResponse.json({
+            data: { parsed: EMPTY, source: 'manual', reason: 'no-ocr-configured' },
+          });
+        }
+
+        // Per-port budget gate — refuse the call before we spend tokens
+        // when the port has already hit its hard cap, or when the request
+        // would push it past the cap. Soft-cap warnings ride along on the
+        // success response so the UI can show a banner without blocking.
+        const budget = await checkBudget({
           portId: ctx.portId,
-          userId: ctx.userId,
-          feature: OCR_FEATURE,
-          provider: config.provider,
-          model: config.model,
-          inputTokens: result.usage.inputTokens,
-          outputTokens: result.usage.outputTokens,
-          requestId: result.usage.requestId,
+          estimatedTokens: OCR_ESTIMATED_TOKENS,
         });
-        return NextResponse.json({
-          data: {
-            parsed: result.parsed,
-            source: 'ai',
+        if (!budget.ok) {
+          return NextResponse.json({
+            data: {
+              parsed: EMPTY,
+              source: 'manual',
+              reason: 'budget-exceeded',
+              providerError: `AI budget reached (${budget.usedTokens}/${budget.capTokens} tokens this period).`,
+            },
+          });
+        }
+
+        try {
+          const result = await runOcr({
             provider: config.provider,
             model: config.model,
-            softCapWarning: budget.softCap,
-          },
-        });
-      } catch (err) {
-        logger.error({ err, provider: config.provider }, 'OCR provider call failed');
-        // Provider hiccup — degrade to manual entry rather than 500-ing.
-        return NextResponse.json({
-          data: {
-            parsed: EMPTY,
-            source: 'manual',
-            reason: 'provider-error',
-            providerError: err instanceof Error ? err.message.slice(0, 200) : 'Unknown error',
-          },
-        });
+            apiKey: config.apiKey,
+            imageBuffer: buffer,
+            mimeType,
+          });
+          await recordAiUsage({
+            portId: ctx.portId,
+            userId: ctx.userId,
+            feature: OCR_FEATURE,
+            provider: config.provider,
+            model: config.model,
+            inputTokens: result.usage.inputTokens,
+            outputTokens: result.usage.outputTokens,
+            requestId: result.usage.requestId,
+          });
+          return NextResponse.json({
+            data: {
+              parsed: result.parsed,
+              source: 'ai',
+              provider: config.provider,
+              model: config.model,
+              softCapWarning: budget.softCap,
+            },
+          });
+        } catch (err) {
+          logger.error({ err, provider: config.provider }, 'OCR provider call failed');
+          // Provider hiccup — degrade to manual entry rather than 500-ing.
+          return NextResponse.json({
+            data: {
+              parsed: EMPTY,
+              source: 'manual',
+              reason: 'provider-error',
+              providerError: err instanceof Error ? err.message.slice(0, 200) : 'Unknown error',
+            },
+          });
+        }
+      } catch (error) {
+        return errorResponse(error);
       }
-    } catch (error) {
-      return errorResponse(error);
-    }
-  }),
+    }),
+  ),
 );