The best way to control Claude Code, Codex and more from any computer or phone

main
ts 473 lines 15.8 KB
Raw
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 });