(SP: 3)[Security] Harden rate-limit inputs, normalize webhook subjects, and isolate test env

frontend/.env.example

@@ -70,8 +70,23 @@ CSRF_SECRET=
 CHECKOUT_RATE_LIMIT_MAX=10
 CHECKOUT_RATE_LIMIT_WINDOW_SECONDS=300
 
+# Stripe webhook rate limit envs (applied per reason; reason-specific overrides generic).
+# Missing signature has its own envs with fallback to generic, then legacy invalid_sig.
+STRIPE_WEBHOOK_MISSING_SIG_RL_MAX=30
+STRIPE_WEBHOOK_MISSING_SIG_RL_WINDOW_SECONDS=60
+
+# Generic Stripe webhook rate limit fallback (applies to missing_sig and invalid_sig).
+STRIPE_WEBHOOK_RL_MAX=30
+STRIPE_WEBHOOK_RL_WINDOW_SECONDS=60
+
+# Invalid signature envs (canonical for invalid_sig, legacy fallback for missing_sig).
 STRIPE_WEBHOOK_INVALID_SIG_RL_MAX=30
 STRIPE_WEBHOOK_INVALID_SIG_RL_WINDOW_SECONDS=60
 
+# SECURITY: If true, trust x-real-ip / x-forwarded-for headers for rate limiting.
+# Enable ONLY behind Cloudflare or a trusted reverse proxy that overwrites these headers.
+# Default: false (empty/0/false).
+TRUST_FORWARDED_HEADERS=0
+
 # emergency switch
 RATE_LIMIT_DISABLED=0

frontend/app/api/shop/checkout/route.ts

@@ -1,7 +1,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import {
   enforceRateLimit,
-  getClientIp,
+  getRateLimitSubject,
   rateLimitResponse,
 } from '@/lib/security/rate-limit';
 import { getCurrentUser } from '@/lib/auth';
@@ -233,14 +233,26 @@ export async function POST(request: NextRequest) {
   }
   // P1: rate limit checkout (cross-instance, DB-backed)
   // Policy: allow reasonable retries; block abusive burst.
-  const checkoutSubject = sessionUserId ?? getClientIp(request) ?? 'anon';
+  const checkoutSubject = sessionUserId ?? getRateLimitSubject(request);
+
+  const limitParsed = Number.parseInt(
+    process.env.CHECKOUT_RATE_LIMIT_MAX ?? '',
+    10
+  );
+  const windowParsed = Number.parseInt(
+    process.env.CHECKOUT_RATE_LIMIT_WINDOW_SECONDS ?? '',
+    10
+  );
+
+  const limit =
+    Number.isFinite(limitParsed) && limitParsed > 0 ? limitParsed : 10;
+  const windowSeconds =
+    Number.isFinite(windowParsed) && windowParsed > 0 ? windowParsed : 300;
 
   const decision = await enforceRateLimit({
     key: `checkout:${checkoutSubject}`,
-    limit: Number(process.env.CHECKOUT_RATE_LIMIT_MAX ?? 10),
-    windowSeconds: Number(
-      process.env.CHECKOUT_RATE_LIMIT_WINDOW_SECONDS ?? 300
-    ),
+    limit,
+    windowSeconds,
   });
 
   if (!decision.ok) {

frontend/app/api/shop/webhooks/stripe/route.ts

@@ -15,9 +15,10 @@ import {
 import { markStripeAttemptFinal } from '@/lib/services/orders/payment-attempts';
 import {
   enforceRateLimit,
-  getClientIp,
+  getRateLimitSubject,
   rateLimitResponse,
 } from '@/lib/security/rate-limit';
+import { resolveStripeWebhookRateLimit } from '@/lib/security/stripe-webhook-rate-limit';
 
 const REFUND_FULLNESS_UNDETERMINED = 'REFUND_FULLNESS_UNDETERMINED' as const;
 
@@ -317,13 +318,12 @@ export async function POST(request: NextRequest) {
 
   const signature = request.headers.get('stripe-signature');
   if (!signature) {
-    const ip = getClientIp(request) ?? 'anon';
+    const subject = getRateLimitSubject(request);
+    const rateLimit = resolveStripeWebhookRateLimit('missing_sig');
     const decision = await enforceRateLimit({
-      key: `stripe_webhook:missing_sig:${ip}`,
-      limit: Number(process.env.STRIPE_WEBHOOK_INVALID_SIG_RL_MAX ?? 30),
-      windowSeconds: Number(
-        process.env.STRIPE_WEBHOOK_INVALID_SIG_RL_WINDOW_SECONDS ?? 60
-      ),
+      key: `stripe_webhook:missing_sig:${subject}`,
+      limit: rateLimit.max,
+      windowSeconds: rateLimit.windowSeconds,
     });
 
     if (!decision.ok) {
@@ -353,13 +353,12 @@ export async function POST(request: NextRequest) {
       error instanceof Error &&
       error.message === 'STRIPE_INVALID_SIGNATURE'
     ) {
-      const ip = getClientIp(request) ?? 'anon';
+      const subject = getRateLimitSubject(request);
+      const rateLimit = resolveStripeWebhookRateLimit('invalid_sig');
       const decision = await enforceRateLimit({
-        key: `stripe_webhook:invalid_sig:${ip}`,
-        limit: Number(process.env.STRIPE_WEBHOOK_INVALID_SIG_RL_MAX ?? 30),
-        windowSeconds: Number(
-          process.env.STRIPE_WEBHOOK_INVALID_SIG_RL_WINDOW_SECONDS ?? 60
-        ),
+        key: `stripe_webhook:invalid_sig:${subject}`,
+        limit: rateLimit.max,
+        windowSeconds: rateLimit.windowSeconds,
       });
 
       if (!decision.ok) {

frontend/lib/security/rate-limit.ts

@@ -2,12 +2,85 @@ import 'server-only';
 
 import type { NextRequest } from 'next/server';
 import { NextResponse } from 'next/server';
+import { isIP } from 'node:net';
+import { createHash } from 'node:crypto';
 import { sql } from 'drizzle-orm';
 
 import { db } from '@/db';
 
 type GateRow = { window_started_at: unknown; count: unknown };
 
+const SUBJECT_PREFIXES = [
+  'checkout:',
+  'stripe_webhook:missing_sig:',
+  'stripe_webhook:invalid_sig:',
+];
+
+const SAFE_SUBJECT_RE = /^[a-zA-Z0-9._-]$/;
+
+function hashSubject(subject: string, prefix: string): string {
+  const digest = createHash('sha256')
+    .update(subject, 'utf8')
+    .digest('base64url');
+  return `${prefix}${digest.slice(0, 16)}`;
+}
+
+function sanitizeSubject(subject: string): string {
+  if (!subject) return 'anon';
+  let sanitized = '';
+  let lastUnderscore = false;
+  for (const char of subject) {
+    if (SAFE_SUBJECT_RE.test(char)) {
+      sanitized += char;
+      lastUnderscore = false;
+      continue;
+    }
+    if (!lastUnderscore) {
+      sanitized += '_';
+      lastUnderscore = true;
+    }
+  }
+  sanitized = sanitized.replace(/^_+|_+$/g, '');
+  if (!sanitized) return 'anon';
+  if (sanitized.length > 64) return hashSubject(subject, 'h_');
+  return sanitized;
+}
+
+export function normalizeRateLimitSubject(subject: string): string {
+  const trimmed = subject.trim();
+  if (!trimmed) return 'anon';
+
+  const ipKind = isIP(trimmed); // 0 | 4 | 6
+  if (ipKind === 6) return hashSubject(trimmed, 'ip6_');
+  if (ipKind === 4) return trimmed;
+
+  return sanitizeSubject(trimmed);
+}
+
+function normalizeRateLimitKey(key: string): {
+  legacyKey: string;
+  normalizedKey: string;
+} {
+  const legacyKey = key;
+  if (!key) return { legacyKey, normalizedKey: key };
+  const prefix = SUBJECT_PREFIXES.find(candidate => key.startsWith(candidate));
+  if (prefix) {
+    const subject = key.slice(prefix.length);
+    const normalizedSubject = normalizeRateLimitSubject(subject);
+    if (normalizedSubject === subject) return { legacyKey, normalizedKey: key };
+    return { legacyKey, normalizedKey: `${prefix}${normalizedSubject}` };
+  }
+  const lastColon = key.lastIndexOf(':');
+  if (lastColon === -1) return { legacyKey, normalizedKey: key };
+  const subject = key.slice(lastColon + 1);
+  const normalizedSubject = normalizeRateLimitSubject(subject);
+  if (normalizedSubject === subject) return { legacyKey, normalizedKey: key };
+  return {
+    legacyKey,
+    normalizedKey: `${key.slice(0, lastColon + 1)}${normalizedSubject}`,
+  };
+}
+
 function normalizeDate(x: unknown): Date | null {
   if (!x) return null;
   if (x instanceof Date) return isNaN(x.getTime()) ? null : x;
@@ -22,24 +95,59 @@ function envInt(name: string, fallback: number): number {
   return Number.isFinite(n) ? Math.floor(n) : fallback;
 }
 
-export function getClientIp(request: NextRequest): string | null {
-  const h = request.headers;
+function envBool(name: string, fallback: boolean): boolean {
+  const raw = (process.env[name] ?? '').trim().toLowerCase();
+  if (!raw) return fallback;
+
+  if (raw === '1' || raw === 'true' || raw === 'yes' || raw === 'on')
+    return true;
+  if (raw === '0' || raw === 'false' || raw === 'no' || raw === 'off')
+    return false;
+
+  return fallback;
+}
 
-  const cf = (h.get('cf-connecting-ip') ?? '').trim();
-  if (cf) return cf;
+export function getClientIpFromHeaders(headers: Headers): string | null {
+  // Always allow Cloudflare canonical header (highest priority).
+  const cf = (headers.get('cf-connecting-ip') ?? '').trim();
+  if (cf && isIP(cf)) return cf;
 
-  const xr = (h.get('x-real-ip') ?? '').trim();
-  if (xr) return xr;
+  const trustForwarded = envBool('TRUST_FORWARDED_HEADERS', false);
 
-  const xff = (h.get('x-forwarded-for') ?? '').trim();
+  // Trusted boundary: if we don't trust forwarded headers and CF is missing,
+  // do NOT fall back to spoofable headers.
+  if (!trustForwarded) return null;
+
+  const xr = (headers.get('x-real-ip') ?? '').trim();
+  if (xr && isIP(xr)) return xr;
+
+  const xff = (headers.get('x-forwarded-for') ?? '').trim();
   if (xff) {
-    const first = xff.split(',')[0]?.trim();
-    return first?.length ? first : null;
+    for (const part of xff.split(',')) {
+      const candidate = part.trim();
+      if (candidate && isIP(candidate)) return candidate;
+    }
   }
 
   return null;
 }
 
+export function getClientIp(request: NextRequest): string | null {
+  return getClientIpFromHeaders(request.headers);
+}
+
+export function getRateLimitSubject(request: NextRequest): string {
+  const ip = getClientIp(request);
+  // Keep subject clean/stable for IPv6 (no ":"), consistent with key normalization.
+  if (ip) return normalizeRateLimitSubject(ip);
+
+  const ua = (request.headers.get('user-agent') ?? '').trim();
+  const al = (request.headers.get('accept-language') ?? '').trim();
+  const baseString = `${ua}|${al}`;
+  const hash = createHash('sha256').update(baseString).digest('base64url');
+  return `ua_${hash.slice(0, 16)}`;
+}
+
 export type RateLimitOk = { ok: true; remaining: number };
 export type RateLimitNo = { ok: false; retryAfterSeconds: number };
 export type RateLimitDecision = RateLimitOk | RateLimitNo;
@@ -56,7 +164,8 @@ export async function enforceRateLimit(params: {
 }): Promise<RateLimitDecision> {
   const limit = Math.max(0, Math.floor(params.limit));
   const windowSeconds = Math.max(1, Math.floor(params.windowSeconds));
-  const key = params.key;
+  const { legacyKey, normalizedKey } = normalizeRateLimitKey(params.key);
+  const key = normalizedKey;
 
   // Allow disabling via env (for emergency): RATE_LIMIT_DISABLED=1
   if (envInt('RATE_LIMIT_DISABLED', 0) === 1) {
@@ -67,6 +176,21 @@ export async function enforceRateLimit(params: {
     return { ok: true, remaining: Number.MAX_SAFE_INTEGER };
   }
 
+  if (legacyKey !== normalizedKey) {
+    try {
+      await db.execute(sql`
+        UPDATE api_rate_limits
+        SET key = ${normalizedKey}
+        WHERE key = ${legacyKey}
+          AND NOT EXISTS (
+            SELECT 1 FROM api_rate_limits WHERE key = ${normalizedKey}
+          )
+      `);
+    } catch {
+      // Ignore conflicts; fall through to use normalizedKey for enforcement.
+    }
+  }
+
   const res = await db.execute<GateRow>(sql`
     INSERT INTO api_rate_limits (key, window_started_at, count, updated_at)
     VALUES (${key}, now(), 1, now())

frontend/lib/security/stripe-webhook-rate-limit.ts

@@ -0,0 +1,80 @@
+export type StripeWebhookRateLimitReason = 'missing_sig' | 'invalid_sig';
+
+type StripeWebhookRateLimitConfig = {
+  max: number;
+  windowSeconds: number;
+};
+
+// Must match previous inline defaults in the webhook route.
+const DEFAULT_STRIPE_WEBHOOK_RL_MAX = 30;
+const DEFAULT_STRIPE_WEBHOOK_RL_WINDOW_SECONDS = 60;
+
+function parsePositiveIntStrict(raw: string | undefined): number | null {
+  if (raw === undefined) return null;
+
+  const trimmed = raw.trim();
+  if (!trimmed) return null;
+
+  // Strict: digits only (no "+", "-", decimals, exponent, or "10abc").
+  if (!/^\d+$/.test(trimmed)) return null;
+
+  const parsed = Number.parseInt(trimmed, 10);
+  if (!Number.isSafeInteger(parsed)) return null;
+
+  return parsed > 0 ? parsed : null;
+}
+
+function resolveEnvPositiveInt(
+  values: Array<string | undefined>,
+  fallback: number
+): number {
+  for (const raw of values) {
+    const parsed = parsePositiveIntStrict(raw);
+    if (parsed !== null) return parsed;
+  }
+  return fallback;
+}
+
+export function resolveStripeWebhookRateLimit(
+  reason: StripeWebhookRateLimitReason
+): StripeWebhookRateLimitConfig {
+  if (reason === 'missing_sig') {
+    return {
+      max: resolveEnvPositiveInt(
+        [
+          process.env.STRIPE_WEBHOOK_MISSING_SIG_RL_MAX,
+          process.env.STRIPE_WEBHOOK_RL_MAX,
+          // legacy fallback to preserve current behavior:
+          process.env.STRIPE_WEBHOOK_INVALID_SIG_RL_MAX,
+        ],
+        DEFAULT_STRIPE_WEBHOOK_RL_MAX
+      ),
+      windowSeconds: resolveEnvPositiveInt(
+        [
+          process.env.STRIPE_WEBHOOK_MISSING_SIG_RL_WINDOW_SECONDS,
+          process.env.STRIPE_WEBHOOK_RL_WINDOW_SECONDS,
+          // legacy fallback to preserve current behavior:
+          process.env.STRIPE_WEBHOOK_INVALID_SIG_RL_WINDOW_SECONDS,
+        ],
+        DEFAULT_STRIPE_WEBHOOK_RL_WINDOW_SECONDS
+      ),
+    };
+  }
+
+  return {
+    max: resolveEnvPositiveInt(
+      [
+        process.env.STRIPE_WEBHOOK_INVALID_SIG_RL_MAX,
+        process.env.STRIPE_WEBHOOK_RL_MAX,
+      ],
+      DEFAULT_STRIPE_WEBHOOK_RL_MAX
+    ),
+    windowSeconds: resolveEnvPositiveInt(
+      [
+        process.env.STRIPE_WEBHOOK_INVALID_SIG_RL_WINDOW_SECONDS,
+        process.env.STRIPE_WEBHOOK_RL_WINDOW_SECONDS,
+      ],
+      DEFAULT_STRIPE_WEBHOOK_RL_WINDOW_SECONDS
+    ),
+  };
+}