The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import * as botManagement from "@distilled.cloud/cloudflare/bot-management"; |
| 2 | import * as Provider from "alchemy/Provider"; |
| 3 | import { Resource } from "alchemy/Resource"; |
| 4 | import * as Effect from "effect/Effect"; |
| 5 | import * as Predicate from "effect/Predicate"; |
| 6 | import { CloudflareEnvironment } from "../CloudflareEnvironment.ts"; |
| 7 | import type { Providers } from "../Providers.ts"; |
| 8 | import { listAllZones } from "../Zone/lookup.ts"; |
| 9 | |
| 10 | const TypeId = "Cloudflare.BotManagement.BotManagement" as const; |
| 11 | type TypeId = typeof TypeId; |
| 12 | |
| 13 | /** |
| 14 | * Action for AI scrapers and crawlers. |
| 15 | */ |
| 16 | export type AiBotsProtection = "block" | "disabled" | "only_on_ad_pages"; |
| 17 | |
| 18 | /** |
| 19 | * Policy for one class of AI crawler (search or agent). `disabled` |
| 20 | * allows the class; `block` blocks it; `only_on_ad_pages` blocks it only |
| 21 | * on pages that show ads. |
| 22 | */ |
| 23 | export type AiCrawlerPolicy = "disabled" | "block" | "only_on_ad_pages"; |
| 24 | |
| 25 | /** |
| 26 | * Policy for AI model-training crawlers. `disallow` adds a robots.txt |
| 27 | * disallow without blocking at the edge. |
| 28 | */ |
| 29 | export type AiTrainingPolicy = AiCrawlerPolicy | "disallow"; |
| 30 | |
| 31 | /** |
| 32 | * Robots Access Control License variant. |
| 33 | */ |
| 34 | export type CfRobotsVariant = "off" | "policy_only"; |
| 35 | |
| 36 | /** |
| 37 | * Super Bot Fight Mode action for definitely / likely automated traffic. |
| 38 | */ |
| 39 | export type SbfmAction = "allow" | "block" | "managed_challenge"; |
| 40 | |
| 41 | /** |
| 42 | * Super Bot Fight Mode action for verified bot traffic. |
| 43 | */ |
| 44 | export type SbfmVerifiedBotsAction = "allow" | "block"; |
| 45 | |
| 46 | /** |
| 47 | * The writable bot-management settings. Which fields the Cloudflare API |
| 48 | * accepts depends on the zone's plan: |
| 49 | * |
| 50 | * - **Free** — `fightMode` (Bot Fight Mode) |
| 51 | * - **Pro** — `sbfmDefinitelyAutomated`, `sbfmVerifiedBots`, |
| 52 | * `sbfmStaticResourceProtection`, `optimizeWordpress` |
| 53 | * - **Business / Enterprise (without the Bot Management add-on)** — Pro |
| 54 | * fields plus `sbfmLikelyAutomated` |
| 55 | * - **Enterprise with Bot Management add-on** — `autoUpdateModel`, |
| 56 | * `bmCookieEnabled`, `suppressSessionScore` |
| 57 | * |
| 58 | * `aiSearch`, `aiUser`, `aiTraining`, `botPreferenceSyncEnabled`, |
| 59 | * `aiBotsProtection`, `crawlerProtection`, `contentBotsProtection`, |
| 60 | * `cfRobotsVariant`, `enableJs`, and `isRobotsTxtManaged` are shared |
| 61 | * across plans (though some accounts reject writes to a subset of them). |
| 62 | * |
| 63 | * Only fields you explicitly set are ever sent to Cloudflare — sending a |
| 64 | * field outside the zone's plan shape fails validation server-side. |
| 65 | */ |
| 66 | export interface Settings { |
| 67 | /** |
| 68 | * Policy for AI search crawlers. |
| 69 | */ |
| 70 | aiSearch?: AiCrawlerPolicy; |
| 71 | /** |
| 72 | * Policy for AI assistant and agent crawlers. |
| 73 | */ |
| 74 | aiUser?: AiCrawlerPolicy; |
| 75 | /** |
| 76 | * Policy for AI model-training crawlers. |
| 77 | */ |
| 78 | aiTraining?: AiTrainingPolicy; |
| 79 | /** |
| 80 | * Let Cloudflare serve robots.txt content derived from the zone's |
| 81 | * `aiSearch`, `aiUser` and `aiTraining` preferences. |
| 82 | */ |
| 83 | botPreferenceSyncEnabled?: boolean; |
| 84 | /** |
| 85 | * Action for AI scrapers and crawlers ("block AI bots"). Note |
| 86 | * `only_on_ad_pages` is not available for Enterprise zones. |
| 87 | * |
| 88 | * Cloudflare deprecated this setting in favour of the per-class |
| 89 | * `aiSearch`, `aiUser`, and `aiTraining` policies. |
| 90 | */ |
| 91 | aiBotsProtection?: AiBotsProtection; |
| 92 | /** |
| 93 | * Punish AI scrapers and crawlers via a link maze (AI Labyrinth). |
| 94 | */ |
| 95 | crawlerProtection?: "enabled" | "disabled"; |
| 96 | /** |
| 97 | * Block content bots — automated traffic with low bot scores, excluding |
| 98 | * safe verified bot categories. |
| 99 | */ |
| 100 | contentBotsProtection?: "block" | "disabled"; |
| 101 | /** |
| 102 | * Robots Access Control License variant to use. |
| 103 | */ |
| 104 | cfRobotsVariant?: CfRobotsVariant; |
| 105 | /** |
| 106 | * Use lightweight, invisible JavaScript detections to improve Bot |
| 107 | * Management. |
| 108 | */ |
| 109 | enableJs?: boolean; |
| 110 | /** |
| 111 | * Serve a Cloudflare-managed robots.txt. If the origin already serves |
| 112 | * one, the managed file is prepended to it. |
| 113 | * |
| 114 | * Cloudflare deprecated this setting in favour of |
| 115 | * `botPreferenceSyncEnabled`. |
| 116 | */ |
| 117 | isRobotsTxtManaged?: boolean; |
| 118 | /** |
| 119 | * Bot Fight Mode (Free-plan zones). Mutually exclusive with the SBFM |
| 120 | * fields below. |
| 121 | */ |
| 122 | fightMode?: boolean; |
| 123 | /** |
| 124 | * Super Bot Fight Mode action for definitely automated requests |
| 125 | * (Pro and above). |
| 126 | */ |
| 127 | sbfmDefinitelyAutomated?: SbfmAction; |
| 128 | /** |
| 129 | * Super Bot Fight Mode action for likely automated requests |
| 130 | * (Business and above). |
| 131 | */ |
| 132 | sbfmLikelyAutomated?: SbfmAction; |
| 133 | /** |
| 134 | * Super Bot Fight Mode action for verified bot requests (Pro and above). |
| 135 | */ |
| 136 | sbfmVerifiedBots?: SbfmVerifiedBotsAction; |
| 137 | /** |
| 138 | * Super Bot Fight Mode static resource protection (Pro and above). |
| 139 | * Enabling can challenge legitimate static-asset consumers. |
| 140 | */ |
| 141 | sbfmStaticResourceProtection?: boolean; |
| 142 | /** |
| 143 | * Optimize Super Bot Fight Mode protections for WordPress |
| 144 | * (Pro and above). |
| 145 | */ |
| 146 | optimizeWordpress?: boolean; |
| 147 | /** |
| 148 | * Automatically update to the newest bot detection model (Enterprise |
| 149 | * Bot Management add-on). |
| 150 | */ |
| 151 | autoUpdateModel?: boolean; |
| 152 | /** |
| 153 | * Whether the bot management cookie may be placed on end-user devices |
| 154 | * (Enterprise Bot Management add-on). |
| 155 | * @default true |
| 156 | */ |
| 157 | bmCookieEnabled?: boolean; |
| 158 | /** |
| 159 | * Disable tracking the highest bot score for a session in the Bot |
| 160 | * Management cookie (Enterprise Bot Management add-on). |
| 161 | * @default false |
| 162 | */ |
| 163 | suppressSessionScore?: boolean; |
| 164 | } |
| 165 | |
| 166 | export interface Props extends Settings { |
| 167 | /** |
| 168 | * Zone whose bot-management configuration is managed. Stable — changing |
| 169 | * the zone triggers a replacement (which simply re-adopts the new |
| 170 | * zone's singleton and restores the old zone's snapshot). |
| 171 | */ |
| 172 | zoneId: string; |
| 173 | } |
| 174 | |
| 175 | export interface Attributes extends Settings { |
| 176 | /** |
| 177 | * Zone that owns this bot-management configuration. |
| 178 | */ |
| 179 | zoneId: string; |
| 180 | /** |
| 181 | * Whether the zone is running the latest ML model (read-only, |
| 182 | * Enterprise Bot Management add-on). |
| 183 | */ |
| 184 | usingLatestModel: boolean | undefined; |
| 185 | /** |
| 186 | * Snapshot of the writable settings observed **before** this resource |
| 187 | * first wrote to the zone. `delete` restores these values for the |
| 188 | * fields this resource managed. |
| 189 | */ |
| 190 | initialSettings: Settings; |
| 191 | } |
| 192 | |
| 193 | export type BotManagement = Resource<TypeId, Props, Attributes, never, Providers>; |
| 194 | |
| 195 | /** |
| 196 | * The bot-management configuration of a Cloudflare zone — a zone-scoped |
| 197 | * **singleton**: every zone always has exactly one bot-management config, |
| 198 | * so there is no create or delete on the Cloudflare side. Reconciling this |
| 199 | * resource adopts the singleton and PUTs only the fields you explicitly |
| 200 | * set, leaving every other field untouched. |
| 201 | * |
| 202 | * Which fields are writable depends on the zone's plan (see |
| 203 | * {@link Settings}). Setting a field outside the zone's plan |
| 204 | * shape fails validation on Cloudflare's side. |
| 205 | * |
| 206 | * On destroy, the resource restores the fields it managed to the values |
| 207 | * observed before its first write (the `initialSettings` snapshot). |
| 208 | * Fields that were never set by this resource are not touched. Settings |
| 209 | * changed out-of-band after the snapshot was taken, or fields the zone's |
| 210 | * plan no longer accepts, cannot be restored. |
| 211 | * ### Super Bot Fight Mode |
| 212 | * **Example:** Challenge definitely automated traffic (Pro and above) |
| 213 | * ```typescript |
| 214 | * yield* Cloudflare.BotManagement.BotManagement("Bots", { |
| 215 | * zoneId: zone.zoneId, |
| 216 | * sbfmDefinitelyAutomated: "managed_challenge", |
| 217 | * sbfmVerifiedBots: "allow", |
| 218 | * }); |
| 219 | * ``` |
| 220 | * |
| 221 | * **Example:** Static resource protection and WordPress optimization |
| 222 | * ```typescript |
| 223 | * yield* Cloudflare.BotManagement.BotManagement("Bots", { |
| 224 | * zoneId: zone.zoneId, |
| 225 | * sbfmDefinitelyAutomated: "block", |
| 226 | * sbfmStaticResourceProtection: true, |
| 227 | * optimizeWordpress: true, |
| 228 | * }); |
| 229 | * ``` |
| 230 | * |
| 231 | * ### AI bot protection |
| 232 | * **Example:** Block AI scrapers and crawlers |
| 233 | * ```typescript |
| 234 | * yield* Cloudflare.BotManagement.BotManagement("Bots", { |
| 235 | * zoneId: zone.zoneId, |
| 236 | * aiBotsProtection: "block", |
| 237 | * crawlerProtection: "enabled", |
| 238 | * }); |
| 239 | * ``` |
| 240 | * |
| 241 | * **Example:** Allow AI search and agent crawlers, disallow training |
| 242 | * ```typescript |
| 243 | * yield* Cloudflare.BotManagement.BotManagement("Bots", { |
| 244 | * zoneId: zone.zoneId, |
| 245 | * aiSearch: "disabled", |
| 246 | * aiUser: "disabled", |
| 247 | * aiTraining: "disallow", |
| 248 | * }); |
| 249 | * ``` |
| 250 | * |
| 251 | * ### Bot Fight Mode (Free plans) |
| 252 | * **Example:** Enable Bot Fight Mode |
| 253 | * ```typescript |
| 254 | * yield* Cloudflare.BotManagement.BotManagement("Bots", { |
| 255 | * zoneId: zone.zoneId, |
| 256 | * fightMode: true, |
| 257 | * }); |
| 258 | * ``` |
| 259 | * |
| 260 | * @see https://developers.cloudflare.com/bots/ |
| 261 | * |
| 262 | * @resource |
| 263 | * @product Bot Management |
| 264 | * @category Application Security |
| 265 | */ |
| 266 | export const BotManagement = Resource<BotManagement>(TypeId, { |
| 267 | aliases: ["Cloudflare.BotManagement"], |
| 268 | }); |
| 269 | |
| 270 | /** |
| 271 | * Returns true if the given value is a BotManagement resource. |
| 272 | */ |
| 273 | export const isBotManagement = (value: unknown): value is BotManagement => |
| 274 | Predicate.hasProperty(value, "Type") && value.Type === TypeId; |
| 275 | |
| 276 | /** |
| 277 | * Every writable settings key, used to project observed cloud state and |
| 278 | * user props into the only-send-what-is-set PUT body. |
| 279 | */ |
| 280 | const SETTINGS_KEYS = [ |
| 281 | "aiSearch", |
| 282 | "aiUser", |
| 283 | "aiTraining", |
| 284 | "botPreferenceSyncEnabled", |
| 285 | "aiBotsProtection", |
| 286 | "crawlerProtection", |
| 287 | "contentBotsProtection", |
| 288 | "cfRobotsVariant", |
| 289 | "enableJs", |
| 290 | "isRobotsTxtManaged", |
| 291 | "fightMode", |
| 292 | "sbfmDefinitelyAutomated", |
| 293 | "sbfmLikelyAutomated", |
| 294 | "sbfmVerifiedBots", |
| 295 | "sbfmStaticResourceProtection", |
| 296 | "optimizeWordpress", |
| 297 | "autoUpdateModel", |
| 298 | "bmCookieEnabled", |
| 299 | "suppressSessionScore", |
| 300 | ] as const; |
| 301 | |
| 302 | type SettingsKey = (typeof SETTINGS_KEYS)[number]; |
| 303 | |
| 304 | export const BotManagementProvider = () => |
| 305 | Provider.succeed(BotManagement, { |
| 306 | nuke: { singleton: true }, |
| 307 | stables: ["zoneId", "initialSettings"], |
| 308 | |
| 309 | list: Effect.fn(function* () { |
| 310 | const { accountId } = yield* yield* CloudflareEnvironment; |
| 311 | // No account-wide API for this zone singleton — enumerate every |
| 312 | // zone in the account and read its bot-management config (every |
| 313 | // live zone always has exactly one). |
| 314 | const allZones = yield* listAllZones(accountId); |
| 315 | const rows = yield* Effect.forEach( |
| 316 | allZones.map((zone) => zone.id), |
| 317 | (zoneId) => |
| 318 | // `observe` maps a dead zone (`InvalidRoute`) to undefined; a |
| 319 | // plan-gated zone forbids the read — skip both. |
| 320 | observe(zoneId).pipe( |
| 321 | Effect.map((observed) => |
| 322 | observed === undefined |
| 323 | ? undefined |
| 324 | : toAttributes(zoneId, observed, pickSettings(observed)), |
| 325 | ), |
| 326 | Effect.catchTag("Forbidden", () => Effect.undefined), |
| 327 | ), |
| 328 | { concurrency: 10 }, |
| 329 | ); |
| 330 | return rows.filter((row): row is Attributes => row !== undefined); |
| 331 | }), |
| 332 | |
| 333 | diff: Effect.fn(function* ({ olds = {}, news, output }) { |
| 334 | const o = olds as Props; |
| 335 | const n = news as Props; |
| 336 | // zoneId is Input<string>; compare only when both sides are concrete. |
| 337 | const oldZone = output?.zoneId ?? o.zoneId; |
| 338 | if (typeof oldZone === "string" && typeof n.zoneId === "string" && oldZone !== n.zoneId) { |
| 339 | return { action: "replace" } as const; |
| 340 | } |
| 341 | }), |
| 342 | |
| 343 | read: Effect.fn(function* ({ output, olds }) { |
| 344 | // The config is a singleton — it exists iff the zone exists. |
| 345 | const zoneId = output?.zoneId ?? (olds?.zoneId as string | undefined); |
| 346 | if (!zoneId) return undefined; |
| 347 | const observed = yield* observe(zoneId); |
| 348 | if (!observed) return undefined; |
| 349 | return toAttributes(zoneId, observed, output?.initialSettings ?? pickSettings(observed)); |
| 350 | }), |
| 351 | |
| 352 | reconcile: Effect.fn(function* ({ news, output }) { |
| 353 | // Inputs are resolved to concrete strings by Plan. |
| 354 | const zoneId = (output?.zoneId ?? news.zoneId) as string; |
| 355 | |
| 356 | // 1. Observe — the singleton always exists for a live zone. |
| 357 | let observed = yield* botManagement.getBotManagement({ zoneId }); |
| 358 | |
| 359 | // 2. Snapshot — capture pre-management values once; `output` acts |
| 360 | // as the cache that keeps the very first observation sticky. |
| 361 | const initialSettings = output?.initialSettings ?? pickSettings(observed); |
| 362 | |
| 363 | // 3. Sync — diff observed against the fields the user set and PUT |
| 364 | // only when something actually differs. Unset fields are never |
| 365 | // sent (plan-shape validation + don't clobber dashboard config). |
| 366 | const desired = pickSettings(news); |
| 367 | if (!settingsEqual(desired, pickSettings(observed))) { |
| 368 | observed = yield* botManagement.putBotManagement({ |
| 369 | zoneId, |
| 370 | ...desired, |
| 371 | }); |
| 372 | } |
| 373 | |
| 374 | // 4. Return fresh attributes. |
| 375 | return toAttributes(zoneId, observed, initialSettings); |
| 376 | }), |
| 377 | |
| 378 | delete: Effect.fn(function* ({ output, olds }) { |
| 379 | // Singleton — nothing to delete on the Cloudflare side. Restore the |
| 380 | // fields this resource managed (i.e. the props that were set) to |
| 381 | // their pre-management snapshot values. Fields whose snapshot value |
| 382 | // is absent (the plan never exposed them, or Cloudflare returned |
| 383 | // null) cannot be restored and are left as-is. |
| 384 | const observed = yield* observe(output.zoneId); |
| 385 | if (!observed) return; // zone is gone — nothing to restore |
| 386 | const managed = pickSettings(olds ?? {}); |
| 387 | const current = pickSettings(observed); |
| 388 | const restore: Settings = {}; |
| 389 | for (const key of SETTINGS_KEYS) { |
| 390 | const snapshot = output.initialSettings?.[key]; |
| 391 | if (managed[key] !== undefined && snapshot !== undefined && current[key] !== snapshot) { |
| 392 | (restore as Record<SettingsKey, unknown>)[key] = snapshot; |
| 393 | } |
| 394 | } |
| 395 | if (Object.keys(restore).length > 0) { |
| 396 | yield* botManagement.putBotManagement({ |
| 397 | zoneId: output.zoneId, |
| 398 | ...restore, |
| 399 | }); |
| 400 | } |
| 401 | }), |
| 402 | }); |
| 403 | |
| 404 | /** |
| 405 | * The distilled response is a 4-way union of plan shapes. Widen to a flat |
| 406 | * bag of optional fields so observation code can read any field without |
| 407 | * narrowing on the plan. |
| 408 | */ |
| 409 | interface ObservedBotManagement { |
| 410 | readonly aiSearch?: string | null; |
| 411 | readonly aiUser?: string | null; |
| 412 | readonly aiTraining?: string | null; |
| 413 | readonly botPreferenceSyncEnabled?: boolean | null; |
| 414 | readonly aiBotsProtection?: string | null; |
| 415 | readonly crawlerProtection?: string | null; |
| 416 | readonly contentBotsProtection?: string | null; |
| 417 | readonly cfRobotsVariant?: string | null; |
| 418 | readonly enableJs?: boolean | null; |
| 419 | readonly isRobotsTxtManaged?: boolean | null; |
| 420 | readonly fightMode?: boolean | null; |
| 421 | readonly sbfmDefinitelyAutomated?: string | null; |
| 422 | readonly sbfmLikelyAutomated?: string | null; |
| 423 | readonly sbfmVerifiedBots?: string | null; |
| 424 | readonly sbfmStaticResourceProtection?: boolean | null; |
| 425 | readonly optimizeWordpress?: boolean | null; |
| 426 | readonly autoUpdateModel?: boolean | null; |
| 427 | readonly bmCookieEnabled?: boolean | null; |
| 428 | readonly suppressSessionScore?: boolean | null; |
| 429 | readonly usingLatestModel?: boolean | null; |
| 430 | } |
| 431 | |
| 432 | /** |
| 433 | * Read the zone's bot-management config, mapping a dead zone |
| 434 | * (`InvalidRoute`, Cloudflare code 7003) to `undefined`. |
| 435 | */ |
| 436 | const observe = (zoneId: string) => |
| 437 | botManagement |
| 438 | .getBotManagement({ zoneId }) |
| 439 | .pipe(Effect.catchTag("InvalidRoute", () => Effect.undefined)); |
| 440 | |
| 441 | const undef = <T>(v: T | null | undefined): T | undefined => (v == null ? undefined : v); |
| 442 | |
| 443 | /** |
| 444 | * Project any source (observed union member, props, attrs) onto the |
| 445 | * writable settings keys, dropping `null`/`undefined` values. |
| 446 | */ |
| 447 | const pickSettings = (source: ObservedBotManagement | Settings): Settings => { |
| 448 | const bag = source as Record<SettingsKey, unknown>; |
| 449 | const out: Record<string, unknown> = {}; |
| 450 | for (const key of SETTINGS_KEYS) { |
| 451 | const value = undef(bag[key]); |
| 452 | if (value !== undefined) out[key] = value; |
| 453 | } |
| 454 | return out as Settings; |
| 455 | }; |
| 456 | |
| 457 | /** |
| 458 | * True when every field set in `desired` matches `observed`. Unset |
| 459 | * desired fields are ignored — they are dashboard/plan-managed. |
| 460 | */ |
| 461 | const settingsEqual = (desired: Settings, observed: Settings): boolean => |
| 462 | SETTINGS_KEYS.every((key) => desired[key] === undefined || desired[key] === observed[key]); |
| 463 | |
| 464 | const toAttributes = ( |
| 465 | zoneId: string, |
| 466 | observed: ObservedBotManagement, |
| 467 | initialSettings: Settings, |
| 468 | ): Attributes => ({ |
| 469 | zoneId, |
| 470 | ...pickSettings(observed), |
| 471 | usingLatestModel: undef(observed.usingLatestModel), |
| 472 | initialSettings, |
| 473 | }); |