The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import * as schemaValidation from "@distilled.cloud/cloudflare/schema-validation"; |
| 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.SchemaValidation.Settings" as const; |
| 11 | type TypeId = typeof TypeId; |
| 12 | |
| 13 | /** |
| 14 | * Mitigation action applied when a request does not conform to a schema: |
| 15 | * `log` records the request, `block` denies it, `none` does nothing. |
| 16 | */ |
| 17 | export type MitigationAction = "none" | "log" | "block"; |
| 18 | |
| 19 | export interface SettingsProps { |
| 20 | /** |
| 21 | * Zone the settings belong to. Stable — changing the zone triggers a |
| 22 | * replacement (the old zone's settings are restored to the values they |
| 23 | * had before Alchemy managed them). |
| 24 | */ |
| 25 | zoneId: string; |
| 26 | /** |
| 27 | * The default mitigation action used when a request does not conform to |
| 28 | * an enabled schema: `log` records it, `block` denies it, `none` does |
| 29 | * nothing. `log` and `block` may be plan-gated (API Shield entitlement). |
| 30 | */ |
| 31 | validationDefaultMitigationAction: MitigationAction; |
| 32 | /** |
| 33 | * Zone-wide kill switch. When set to `"none"`, schema validation is |
| 34 | * skipped entirely for every request, overriding both the zone default |
| 35 | * and any per-operation settings. `null` clears the override. |
| 36 | * @default null |
| 37 | */ |
| 38 | validationOverrideMitigationAction?: "none" | null; |
| 39 | } |
| 40 | |
| 41 | export interface SettingsAttributes { |
| 42 | /** Zone the settings belong to. */ |
| 43 | zoneId: string; |
| 44 | /** The default mitigation action for non-conforming requests. */ |
| 45 | validationDefaultMitigationAction: MitigationAction; |
| 46 | /** The zone-wide override (`"none"` = validation disabled), if set. */ |
| 47 | validationOverrideMitigationAction: "none" | (string & {}) | null; |
| 48 | /** |
| 49 | * The default action the zone had before Alchemy first managed these |
| 50 | * settings. Restored on destroy. |
| 51 | */ |
| 52 | initialDefaultMitigationAction: MitigationAction; |
| 53 | /** |
| 54 | * The override the zone had before Alchemy first managed these settings. |
| 55 | * Restored on destroy. |
| 56 | */ |
| 57 | initialOverrideMitigationAction: "none" | (string & {}) | null; |
| 58 | } |
| 59 | |
| 60 | export type Settings = Resource<TypeId, SettingsProps, SettingsAttributes, never, Providers>; |
| 61 | |
| 62 | /** |
| 63 | * Zone-level schema validation settings |
| 64 | * (`/zones/{zone_id}/schema_validation/settings`) — the default mitigation |
| 65 | * action applied to requests that do not conform to an enabled schema, plus |
| 66 | * an optional zone-wide kill switch. |
| 67 | * |
| 68 | * The settings are a zone singleton: they always exist (Cloudflare default |
| 69 | * is `none`), so this resource never creates or deletes anything physical. |
| 70 | * Reconcile PUTs the desired state when the observed state differs; destroy |
| 71 | * restores the values the zone had before Alchemy first managed them. |
| 72 | * |
| 73 | * The `log` action is plan-gated (API Shield entitlement) on some zones — |
| 74 | * setting it there fails with the typed `UnentitledMitigationAction` error. |
| 75 | * ### Managing the zone default |
| 76 | * **Example:** Block non-conforming requests |
| 77 | * ```typescript |
| 78 | * yield* Cloudflare.SchemaValidation.Settings("Validation", { |
| 79 | * zoneId: zone.zoneId, |
| 80 | * validationDefaultMitigationAction: "block", |
| 81 | * }); |
| 82 | * ``` |
| 83 | * |
| 84 | * ### Kill switch |
| 85 | * **Example:** Temporarily disable validation zone-wide |
| 86 | * ```typescript |
| 87 | * yield* Cloudflare.SchemaValidation.Settings("Validation", { |
| 88 | * zoneId: zone.zoneId, |
| 89 | * validationDefaultMitigationAction: "block", |
| 90 | * // overrides every schema and per-operation setting: |
| 91 | * validationOverrideMitigationAction: "none", |
| 92 | * }); |
| 93 | * ``` |
| 94 | * |
| 95 | * @see https://developers.cloudflare.com/api-shield/security/schema-validation/ |
| 96 | * |
| 97 | * @resource |
| 98 | * @product Schema Validation |
| 99 | * @category Application Security |
| 100 | */ |
| 101 | export const Settings = Resource<Settings>(TypeId); |
| 102 | |
| 103 | /** |
| 104 | * Returns true if the given value is a Settings resource. |
| 105 | */ |
| 106 | export const isSettings = (value: unknown): value is Settings => |
| 107 | Predicate.hasProperty(value, "Type") && value.Type === TypeId; |
| 108 | |
| 109 | export const SettingsProvider = () => |
| 110 | Provider.succeed(Settings, { |
| 111 | nuke: { singleton: true }, |
| 112 | stables: ["zoneId", "initialDefaultMitigationAction", "initialOverrideMitigationAction"], |
| 113 | |
| 114 | list: Effect.fn(function* () { |
| 115 | const { accountId } = yield* yield* CloudflareEnvironment; |
| 116 | // No account-wide API for this zone singleton — enumerate every |
| 117 | // zone in the account and read its setting (every zone has one, |
| 118 | // defaulting to `none`). |
| 119 | const allZones = yield* listAllZones(accountId); |
| 120 | const rows = yield* Effect.forEach( |
| 121 | allZones.map((zone) => zone.id), |
| 122 | (zoneId) => |
| 123 | schemaValidation.getSetting({ zoneId }).pipe( |
| 124 | // A cold read adopts freely; the observed state is the |
| 125 | // initial state (nothing has been managed yet). |
| 126 | Effect.map((observed) => toAttributes(zoneId, observed, observedState(observed))), |
| 127 | // A scoped token may lack access to some zones; skip them. |
| 128 | Effect.catchTag("Forbidden", () => Effect.undefined), |
| 129 | ), |
| 130 | { concurrency: 10 }, |
| 131 | ); |
| 132 | return rows.filter((row): row is SettingsAttributes => row !== undefined); |
| 133 | }), |
| 134 | |
| 135 | diff: Effect.fn(function* ({ olds = {}, news, output }) { |
| 136 | const o = olds as SettingsProps; |
| 137 | const n = news as SettingsProps; |
| 138 | // zoneId is Input<string>; compare only once both sides are concrete. |
| 139 | const oldZoneId = output?.zoneId ?? (typeof o.zoneId === "string" ? o.zoneId : undefined); |
| 140 | if (oldZoneId !== undefined && typeof n.zoneId === "string" && oldZoneId !== n.zoneId) { |
| 141 | return { action: "replace" } as const; |
| 142 | } |
| 143 | return undefined; |
| 144 | }), |
| 145 | |
| 146 | read: Effect.fn(function* ({ output, olds }) { |
| 147 | const zoneId = output?.zoneId ?? (typeof olds?.zoneId === "string" ? olds.zoneId : undefined); |
| 148 | if (zoneId === undefined) return undefined; |
| 149 | const observed = yield* schemaValidation.getSetting({ zoneId }); |
| 150 | // The settings are a singleton that always exists with a Cloudflare |
| 151 | // default — there is nothing to "own", so a cold read adopts freely |
| 152 | // (never `Unowned`). The observed values at adoption time become the |
| 153 | // initial values restored on destroy. |
| 154 | return toAttributes( |
| 155 | zoneId, |
| 156 | observed, |
| 157 | output !== undefined |
| 158 | ? { |
| 159 | defaultAction: output.initialDefaultMitigationAction, |
| 160 | overrideAction: output.initialOverrideMitigationAction, |
| 161 | } |
| 162 | : observedState(observed), |
| 163 | ); |
| 164 | }), |
| 165 | |
| 166 | reconcile: Effect.fn(function* ({ news, output }) { |
| 167 | // Inputs have been resolved to concrete strings by Plan. |
| 168 | const zoneId = news.zoneId as string; |
| 169 | const desired = { |
| 170 | defaultAction: news.validationDefaultMitigationAction, |
| 171 | overrideAction: news.validationOverrideMitigationAction ?? null, |
| 172 | }; |
| 173 | |
| 174 | // 1. Observe — the settings always exist; read the live state. |
| 175 | const observed = yield* schemaValidation.getSetting({ zoneId }); |
| 176 | |
| 177 | // 2. Capture — the pre-management values, restored on destroy. |
| 178 | // `output` (including an adoption read) already carries them; |
| 179 | // otherwise this is our first touch and the observed state is the |
| 180 | // zone's original. |
| 181 | const initial = |
| 182 | output !== undefined |
| 183 | ? { |
| 184 | defaultAction: output.initialDefaultMitigationAction, |
| 185 | overrideAction: output.initialOverrideMitigationAction, |
| 186 | } |
| 187 | : observedState(observed); |
| 188 | |
| 189 | // 3. Sync — PUT the full desired state only when it differs. |
| 190 | const current = observedState(observed); |
| 191 | if ( |
| 192 | current.defaultAction === desired.defaultAction && |
| 193 | current.overrideAction === desired.overrideAction |
| 194 | ) { |
| 195 | return toAttributes(zoneId, observed, initial); |
| 196 | } |
| 197 | const updated = yield* schemaValidation.putSetting({ |
| 198 | zoneId, |
| 199 | validationDefaultMitigationAction: desired.defaultAction, |
| 200 | validationOverrideMitigationAction: desired.overrideAction, |
| 201 | }); |
| 202 | return toAttributes(zoneId, updated, initial); |
| 203 | }), |
| 204 | |
| 205 | delete: Effect.fn(function* ({ output }) { |
| 206 | const { zoneId, initialDefaultMitigationAction, initialOverrideMitigationAction } = output; |
| 207 | // The singleton cannot be deleted — restore the pre-management |
| 208 | // state. Skip the call when it already matches (idempotent re-delete |
| 209 | // after a crashed run). |
| 210 | const observed = yield* schemaValidation.getSetting({ zoneId }); |
| 211 | const current = observedState(observed); |
| 212 | if ( |
| 213 | current.defaultAction === initialDefaultMitigationAction && |
| 214 | current.overrideAction === initialOverrideMitigationAction |
| 215 | ) { |
| 216 | return; |
| 217 | } |
| 218 | yield* schemaValidation.putSetting({ |
| 219 | zoneId, |
| 220 | validationDefaultMitigationAction: initialDefaultMitigationAction, |
| 221 | validationOverrideMitigationAction: initialOverrideMitigationAction, |
| 222 | }); |
| 223 | yield* Effect.logInfo( |
| 224 | "Cloudflare schema validation settings are a zone singleton and cannot be deleted; restored the pre-management values instead.", |
| 225 | ); |
| 226 | }), |
| 227 | }); |
| 228 | |
| 229 | type SettingResponse = schemaValidation.GetSettingResponse | schemaValidation.PutSettingResponse; |
| 230 | |
| 231 | const observedState = (setting: SettingResponse) => ({ |
| 232 | // Distilled widens the generated enum to an open union (`string & {}`). |
| 233 | defaultAction: setting.validationDefaultMitigationAction as MitigationAction, |
| 234 | overrideAction: setting.validationOverrideMitigationAction ?? null, |
| 235 | }); |
| 236 | |
| 237 | const toAttributes = ( |
| 238 | zoneId: string, |
| 239 | setting: SettingResponse, |
| 240 | initial: { |
| 241 | defaultAction: MitigationAction; |
| 242 | overrideAction: "none" | (string & {}) | null; |
| 243 | }, |
| 244 | ): SettingsAttributes => { |
| 245 | const current = observedState(setting); |
| 246 | return { |
| 247 | zoneId, |
| 248 | validationDefaultMitigationAction: current.defaultAction, |
| 249 | validationOverrideMitigationAction: current.overrideAction, |
| 250 | initialDefaultMitigationAction: initial.defaultAction, |
| 251 | initialOverrideMitigationAction: initial.overrideAction, |
| 252 | }; |
| 253 | }; |