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

main
ts 253 lines 9.93 KB
Raw
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 };