feat(security): mirror anti-DDoS blocks to Cloudflare edge via API

- gate creates a zone IP Access Rule (block) for proxied offenders that hit the block threshold, deduped until the tiered block expires
- cloudflare-api lib: verified endpoints, create/delete/verify/list helpers, Redis-backed tracking + 30s TTL sweep (instrumentation worker + admin render)
- runtime toggle cloudflareAutoBlock in antiddos config; boot default CLOUDFLARE_AUTO_BLOCK_ENABLED
- admin panel: Cloudflare edge-blocks card with verify + remove-rule actions; unban also lifts the edge block
- credentials live in env only (CLOUDFLARE_API_TOKEN / CLOUDFLARE_ZONE_ID)

src/actions/admin-antiddos.ts

@@ -10,6 +10,11 @@ import {
 	antiddosDefaultsFromEnv,
 	invalidateAntiddosConfig,
 } from "@/lib/antiddos-config";
+import {
+	removeCloudflareBlock,
+	setLastCloudflareVerify,
+	verifyCloudflareConnection,
+} from "@/lib/cloudflare-api";
 import { db, WebsiteSetting } from "@/lib/db";
 import { logger } from "@/lib/logger";
 import { PERMS } from "@/lib/permissions";
@@ -93,6 +98,7 @@ function configFromForm(formData: FormData): AntiddosConfig {
 			formData.get("global_halt_ms"),
 			defaults.globalHaltMs,
 		),
+		cloudflareAutoBlock: str(formData.get("cfa_auto_block")) === "1",
 	};
 }
 
@@ -116,6 +122,7 @@ async function persistSettings(config: AntiddosConfig): Promise<void> {
 				.join(","),
 		],
 		["antiddos_global_halt_ms", String(config.globalHaltMs)],
+		["antiddos_cfa_auto_block", config.cloudflareAutoBlock ? "1" : "0"],
 	];
 	await Promise.all(
 		entries.map(([key, value]) =>
@@ -190,12 +197,49 @@ export async function unbanAntiddosIp(formData: FormData): Promise<void> {
 				redis.del(`antiddos:v:${ip}`),
 			]);
 		}
+		// Also lift a matching Cloudflare edge block (best effort).
+		const cloudflare = await removeCloudflareBlock(ip);
 		logger.info("Anti-DDoS block manually removed", {
 			staff: staff.username,
 			ip,
+			cloudflareCleared: cloudflare.removed,
 		});
 	} catch (err) {
 		logger.error("Failed to remove anti-DDoS block", { err, ip });
 	}
 	revalidatePath("/admin/devops/antiddos");
 }
+
+/** Remove an automatic Cloudflare edge block for a tracked IP. */
+export async function removeCloudflareRule(formData: FormData): Promise<void> {
+	const staff = await requirePermission(PERMS.SETTINGS_VIEW);
+	const ip = str(formData.get("ip")).trim();
+	if (!ip) return;
+
+	const result = await removeCloudflareBlock(ip);
+	logger.info(
+		result.removed
+			? "Cloudflare automatic block removed"
+			: "Cloudflare automatic block removal skipped",
+		{
+			staff: staff.username,
+			ip,
+			message: result.message,
+		},
+	);
+	revalidatePath("/admin/devops/antiddos");
+}
+
+/** Test the configured Cloudflare API credentials against the zone. */
+export async function verifyCloudflareConfiguration(): Promise<void> {
+	const staff = await requirePermission(PERMS.SETTINGS_VIEW);
+	const status = await verifyCloudflareConnection();
+	await setLastCloudflareVerify(status);
+	logger.info("Cloudflare API configuration verified", {
+		staff: staff.username,
+		ok: status.ok,
+		zoneName: status.zoneName,
+		message: status.message,
+	});
+	revalidatePath("/admin/devops/antiddos");
+}

src/env.ts

@@ -132,6 +132,22 @@ const schema = z
 		// Logging level.
 		LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).optional(),
 		APP_VERSION: z.string().optional(),
+		// Cloudflare API — optional. When the API token + zone id are set, the
+		// anti-DDoS gate can automatically mirror escalated IP blocks to the
+		// zone's IP Access Rules so attackers are dropped at the edge. The token
+		// lives in env only and is never persisted into Redis-visible config.
+		CLOUDFLARE_API_BASE_URL: z
+			.string()
+			.url()
+			.default("https://api.cloudflare.com/client/v4"),
+		CLOUDFLARE_API_TOKEN: z.string().optional(),
+		CLOUDFLARE_ZONE_ID: z.string().optional(),
+		// Boot default for the runtime "auto-create Cloudflare blocks" toggle
+		// (overridable via the admin panel / antiddos:config).
+		CLOUDFLARE_AUTO_BLOCK_ENABLED: z
+			.string()
+			.optional()
+			.transform((value) => value !== "false" && value !== "0"),
 	})
 	.superRefine((data, ctx) => {
 		if (data.NODE_ENV !== "production") return;

src/instrumentation.ts

@@ -34,4 +34,9 @@ export async function register() {
 		void drainFurnitureImports();
 	}, 30000);
 	timer.unref();
+	const { sweepExpiredCloudflareBlocks } = await import("@/lib/cloudflare-api");
+	const cloudflareSweep = setInterval(() => {
+		void sweepExpiredCloudflareBlocks();
+	}, 30000);
+	cloudflareSweep.unref();
 }

src/lib/antiddos-config.ts

@@ -23,6 +23,7 @@ export interface AntiddosConfig {
 	maxViolations: number;
 	blockTiers: AntiddosBlockTier[];
 	globalHaltMs: number;
+	cloudflareAutoBlock: boolean;
 }
 
 const DEFAULT_CONFIG: AntiddosConfig = {
@@ -39,6 +40,7 @@ const DEFAULT_CONFIG: AntiddosConfig = {
 		{ minViolations: 50, ttlSeconds: 86_400 },
 	],
 	globalHaltMs: 10_000,
+	cloudflareAutoBlock: true,
 };
 
 function positiveInt(value: number | undefined, fallback: number): number {
@@ -65,11 +67,19 @@ function parseTiers(raw: string | undefined): AntiddosBlockTier[] | null {
 	return tiers;
 }
 
+/**
+ * Gate on a boolean-flag env value that is either already transformed to a
+ * real boolean (production schema) or still a raw string (SKIP-env tests).
+ */
+function isTruthyFlag(value: string | boolean | undefined): boolean {
+	return !(value === false || value === "false" || value === "0");
+}
+
 /** Boot defaults from environment (explicitly set → overrides code; unset → sane value). */
 export function antiddosDefaultsFromEnv(): AntiddosConfig {
 	const tiers = parseTiers(env.ANTI_DDOS_BLOCK_TIERS);
 	return {
-		enabled: env.ANTI_DDOS_ENABLED !== false,
+		enabled: isTruthyFlag(env.ANTI_DDOS_ENABLED),
 		pages: {
 			limit: positiveInt(env.ANTI_DDOS_PAGES_LIMIT, DEFAULT_CONFIG.pages.limit),
 			windowSeconds: positiveInt(
@@ -114,6 +124,7 @@ export function antiddosDefaultsFromEnv(): AntiddosConfig {
 			env.ANTI_DDOS_GLOBAL_HALT_MS,
 			DEFAULT_CONFIG.globalHaltMs,
 		),
+		cloudflareAutoBlock: isTruthyFlag(env.CLOUDFLARE_AUTO_BLOCK_ENABLED),
 	};
 }
 
@@ -155,6 +166,7 @@ function sanitize(config: AntiddosConfig): AntiddosConfig {
 						.sort((a, b) => a.minViolations - b.minViolations)
 				: base.blockTiers,
 		globalHaltMs: positiveInt(config?.globalHaltMs, base.globalHaltMs),
+		cloudflareAutoBlock: config?.cloudflareAutoBlock !== false,
 	};
 }
 

src/lib/ddos-guard.ts

@@ -5,6 +5,8 @@ import { NextResponse } from "next/server";
 import { env } from "@/env";
 import { getAntiddosConfig } from "@/lib/antiddos-config";
 import { resolveClientIp } from "@/lib/client-ip";
+import { isCloudflareProxied } from "@/lib/cloudflare";
+import { maybeAutoBlockCloudflare } from "@/lib/cloudflare-api";
 import { classifyDdos, isSuspiciousPath } from "@/lib/ddos";
 import { rateLimit } from "@/lib/rate-limit";
 import { redis } from "@/lib/redis";
@@ -110,6 +112,17 @@ export async function enforceDdosRateLimit(
 			const ttl = blockTtlForViolations(violations, config.blockTiers);
 			if (violations >= config.maxViolations) {
 				await redis.set(blockKey, "1", "EX", ttl);
+				// Mirror the host-level block to the Cloudflare edge (IP Access
+				// Rules) so a repeat offender is shed before it reaches the
+				// origin. Only when this request demonstrably transited
+				// Cloudflare — that is when the client IP is trustworthy.
+				void maybeAutoBlockCloudflare({
+					ip,
+					ttlSeconds: ttl,
+					category,
+					enabled:
+						config.cloudflareAutoBlock && isCloudflareProxied(req.headers),
+				});
 			}
 			return { outcome: "block", retryAfterSeconds: ttl };
 		} catch {