The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import * as contentScanning from "@distilled.cloud/cloudflare/content-scanning"; |
| 2 | import { Unowned } from "alchemy/AdoptPolicy"; |
| 3 | import { isResolved } from "alchemy/Diff"; |
| 4 | import * as Provider from "alchemy/Provider"; |
| 5 | import { Resource } from "alchemy/Resource"; |
| 6 | import * as Data from "effect/Data"; |
| 7 | import * as Effect from "effect/Effect"; |
| 8 | import * as Option from "effect/Option"; |
| 9 | import * as Predicate from "effect/Predicate"; |
| 10 | import * as Stream from "effect/Stream"; |
| 11 | import { CloudflareEnvironment } from "../CloudflareEnvironment.ts"; |
| 12 | import type { Providers } from "../Providers.ts"; |
| 13 | import { listAllZones } from "../Zone/lookup.ts"; |
| 14 | |
| 15 | const TypeId = "Cloudflare.ContentScanning.Expression" as const; |
| 16 | type TypeId = typeof TypeId; |
| 17 | |
| 18 | export interface ExpressionProps { |
| 19 | /** |
| 20 | * Zone the custom scan expression belongs to. Stable — moving an |
| 21 | * expression between zones triggers a replacement. |
| 22 | */ |
| 23 | zoneId: string; |
| 24 | /** |
| 25 | * Ruleset-language expression that locates the content to scan inside |
| 26 | * the request — e.g. |
| 27 | * `lookup_json_string(http.request.body.raw, "file")`. |
| 28 | * |
| 29 | * Immutable — the API has no update endpoint for expressions, so |
| 30 | * changing the payload triggers a replacement (create new, delete old). |
| 31 | */ |
| 32 | payload: string; |
| 33 | } |
| 34 | |
| 35 | export interface ExpressionAttributes { |
| 36 | /** Cloudflare-assigned identifier of the custom scan expression. */ |
| 37 | expressionId: string; |
| 38 | /** Zone the expression belongs to. */ |
| 39 | zoneId: string; |
| 40 | /** The ruleset-language expression locating the content to scan. */ |
| 41 | payload: string; |
| 42 | } |
| 43 | |
| 44 | export type Expression = Resource<TypeId, ExpressionProps, ExpressionAttributes, never, Providers>; |
| 45 | |
| 46 | /** |
| 47 | * A custom scan expression ("payload") for WAF Content Scanning — tells the |
| 48 | * malicious-uploads scanner where to find encoded or nested content in the |
| 49 | * request body (`/zones/{zone_id}/content-upload-scan/payloads`). |
| 50 | * |
| 51 | * An expression's identity is its `payload` text within the zone: the API |
| 52 | * offers create/list/delete only (no update), so changing `payload` |
| 53 | * triggers a replacement. The zone must have Content Scanning enabled (see |
| 54 | * `Cloudflare.ContentScanning.ContentScanning`) — payload calls on a zone where scanning is |
| 55 | * disabled fail with the typed `ContentScanningNotEnabled` error. |
| 56 | * |
| 57 | * Safety: expressions carry no ownership markers. When there is no prior |
| 58 | * state, `read` scans the zone for an expression with the same payload text |
| 59 | * and reports it as `Unowned`, so the engine refuses to take it over unless |
| 60 | * `--adopt` (or `adopt(true)`) is set. |
| 61 | * ### Creating expressions |
| 62 | * **Example:** Scan a JSON-embedded file field |
| 63 | * ```typescript |
| 64 | * const scanning = yield* Cloudflare.ContentScanning.ContentScanning("UploadScanning", { |
| 65 | * zoneId: zone.zoneId, |
| 66 | * }); |
| 67 | * |
| 68 | * yield* Cloudflare.ContentScanning.Expression("ScanJsonFile", { |
| 69 | * zoneId: scanning.zoneId, |
| 70 | * payload: 'lookup_json_string(http.request.body.raw, "file")', |
| 71 | * }); |
| 72 | * ``` |
| 73 | * |
| 74 | * **Example:** Scan a base64-encoded form field |
| 75 | * ```typescript |
| 76 | * yield* Cloudflare.ContentScanning.Expression("ScanBase64Document", { |
| 77 | * zoneId: scanning.zoneId, |
| 78 | * payload: 'base64_decode(http.request.body.form["document"][0])', |
| 79 | * }); |
| 80 | * ``` |
| 81 | * |
| 82 | * @see https://developers.cloudflare.com/waf/detections/malicious-uploads/#add-custom-scan-expressions |
| 83 | * |
| 84 | * @resource |
| 85 | * @product Content Scanning |
| 86 | * @category Application Security |
| 87 | */ |
| 88 | export const Expression = Resource<Expression>(TypeId); |
| 89 | |
| 90 | /** |
| 91 | * Returns true if the given value is a Expression resource. |
| 92 | */ |
| 93 | export const isExpression = (value: unknown): value is Expression => |
| 94 | Predicate.hasProperty(value, "Type") && value.Type === TypeId; |
| 95 | |
| 96 | /** |
| 97 | * Cloudflare accepted the create call but the expression did not appear in |
| 98 | * the returned list — an API anomaly that should never happen in practice. |
| 99 | */ |
| 100 | export class ExpressionCreateAnomaly extends Data.TaggedError("ExpressionCreateAnomaly")<{ |
| 101 | readonly zoneId: string; |
| 102 | readonly payload: string; |
| 103 | }> {} |
| 104 | |
| 105 | export const ExpressionProvider = () => |
| 106 | Provider.succeed(Expression, { |
| 107 | stables: ["expressionId", "zoneId", "payload"], |
| 108 | |
| 109 | // Custom scan expressions are a zone-scoped Content Scanning feature. Fan |
| 110 | // out over every zone in the account, exhaustively paginate each zone's |
| 111 | // payloads, and hydrate each into the same Attributes shape `read` |
| 112 | // produces. Zones without Content Scanning enabled (or not entitled) reject |
| 113 | // payload calls with the typed `ContentScanningNotEnabled`/`Forbidden` |
| 114 | // tags, and a deleted zone with `InvalidRoute` — skip all three. |
| 115 | list: Effect.fn(function* () { |
| 116 | const { accountId } = yield* yield* CloudflareEnvironment; |
| 117 | const allZones = yield* listAllZones(accountId); |
| 118 | const rows = yield* Effect.forEach( |
| 119 | allZones, |
| 120 | (zone) => |
| 121 | contentScanning.listPayloads.pages({ zoneId: zone.id }).pipe( |
| 122 | Stream.runCollect, |
| 123 | Effect.map((chunk) => |
| 124 | Array.from(chunk).flatMap((page) => |
| 125 | (page.result ?? []).map((expression) => toAttributes(zone.id, expression)), |
| 126 | ), |
| 127 | ), |
| 128 | Effect.catchTags({ |
| 129 | ContentScanningNotEnabled: () => Effect.succeed([]), |
| 130 | Forbidden: () => Effect.succeed([]), |
| 131 | InvalidRoute: () => Effect.succeed([]), |
| 132 | }), |
| 133 | ), |
| 134 | { concurrency: 10 }, |
| 135 | ); |
| 136 | return rows.flat(); |
| 137 | }), |
| 138 | |
| 139 | diff: Effect.fn(function* ({ olds, news, output }) { |
| 140 | // zoneId is Input<string>; compare only once both sides are concrete. |
| 141 | if (!isResolved(news)) return undefined; |
| 142 | const old = olds !== undefined && isResolved(olds) ? olds : undefined; |
| 143 | // The payload is the expression's identity — no update endpoint. |
| 144 | const oldPayload = output?.payload ?? old?.payload; |
| 145 | if (oldPayload !== undefined && oldPayload !== news.payload) { |
| 146 | return { action: "replace" } as const; |
| 147 | } |
| 148 | const oldZoneId = output?.zoneId ?? old?.zoneId; |
| 149 | if (oldZoneId !== undefined && oldZoneId !== news.zoneId) { |
| 150 | return { action: "replace" } as const; |
| 151 | } |
| 152 | return undefined; |
| 153 | }), |
| 154 | |
| 155 | read: Effect.fn(function* ({ output, olds }) { |
| 156 | const zoneId = output?.zoneId ?? (olds?.zoneId as string | undefined); |
| 157 | if (!zoneId) return undefined; |
| 158 | |
| 159 | const expressions = yield* listExpressions(zoneId); |
| 160 | // Scanning disabled or zone gone — no expressions are observable. |
| 161 | if (expressions === undefined) return undefined; |
| 162 | |
| 163 | // Owned path: refresh by our persisted expression id. |
| 164 | if (output?.expressionId) { |
| 165 | const observed = expressions.find((e) => e.id === output.expressionId); |
| 166 | if (observed) return toAttributes(zoneId, observed); |
| 167 | } |
| 168 | |
| 169 | // Adoption path: an expression with this payload text may already |
| 170 | // exist on the zone. Expressions carry no ownership markers, so we |
| 171 | // cannot prove we created it — brand it `Unowned` so the engine |
| 172 | // refuses to take over unless `adopt` is set. |
| 173 | const payload = output?.payload ?? olds?.payload; |
| 174 | if (payload !== undefined) { |
| 175 | const observed = expressions.find((e) => e.payload === payload); |
| 176 | if (observed) return Unowned(toAttributes(zoneId, observed)); |
| 177 | } |
| 178 | return undefined; |
| 179 | }), |
| 180 | |
| 181 | reconcile: Effect.fn(function* ({ news, output }) { |
| 182 | // Inputs have been resolved to concrete strings by Plan. |
| 183 | const zoneId = news.zoneId as string; |
| 184 | |
| 185 | // 1. Observe — the expression id cached on `output` is a hint, not |
| 186 | // a guarantee: a missing expression falls through to the payload |
| 187 | // scan and then to create. (Scanning must be enabled here — a |
| 188 | // disabled zone fails with the typed ContentScanningNotEnabled.) |
| 189 | const expressionId = output?.expressionId; |
| 190 | let observed: ObservedExpression | undefined = expressionId |
| 191 | ? yield* findExpression(zoneId, (e) => e.id === expressionId) |
| 192 | : undefined; |
| 193 | |
| 194 | // 2. Fall back to matching by payload text. Ownership has already |
| 195 | // been verified upstream — `read` reports existing expressions as |
| 196 | // `Unowned` and the engine gates takeover behind the adopt policy |
| 197 | // before reconcile ever runs. |
| 198 | if (!observed) { |
| 199 | observed = yield* findExpression(zoneId, (e) => e.payload === news.payload); |
| 200 | } |
| 201 | |
| 202 | // 3. Ensure — create when missing. The create call returns the full |
| 203 | // list of expressions; find ours by payload text. |
| 204 | if (!observed) { |
| 205 | const created = yield* contentScanning.createPayload({ |
| 206 | zoneId, |
| 207 | body: [{ payload: news.payload }], |
| 208 | }); |
| 209 | observed = created.result.find((e) => e.payload === news.payload); |
| 210 | if (!observed) { |
| 211 | return yield* new ExpressionCreateAnomaly({ |
| 212 | zoneId, |
| 213 | payload: news.payload, |
| 214 | }); |
| 215 | } |
| 216 | } |
| 217 | |
| 218 | // 4. No sync step — expressions have nothing mutable beyond identity. |
| 219 | return toAttributes(zoneId, observed); |
| 220 | }), |
| 221 | |
| 222 | delete: Effect.fn(function* ({ output }) { |
| 223 | const { zoneId, expressionId } = output; |
| 224 | // Observe first — scanning disabled / zone gone / already deleted |
| 225 | // all mean there is nothing left to remove. |
| 226 | const expressions = yield* listExpressions(zoneId); |
| 227 | if (expressions === undefined) return; |
| 228 | if (!expressions.some((e) => e.id === expressionId)) return; |
| 229 | yield* contentScanning.deletePayload({ zoneId, expressionId }).pipe( |
| 230 | // A concurrent disable between observe and delete is "gone". |
| 231 | Effect.catchTags({ |
| 232 | ContentScanningNotEnabled: () => Effect.void, |
| 233 | InvalidRoute: () => Effect.void, |
| 234 | }), |
| 235 | ); |
| 236 | }), |
| 237 | }); |
| 238 | |
| 239 | type ObservedExpression = { id?: string | null; payload?: string | null }; |
| 240 | |
| 241 | /** |
| 242 | * Find the first expression on the zone matching `predicate`, terminating |
| 243 | * pagination as soon as a match is seen. Unlike {@link listExpressions}, |
| 244 | * "not observable" errors propagate (reconcile requires scanning enabled). |
| 245 | */ |
| 246 | const findExpression = (zoneId: string, predicate: (e: ObservedExpression) => boolean) => |
| 247 | contentScanning.listPayloads |
| 248 | .items({ zoneId }) |
| 249 | .pipe(Stream.filter(predicate), Stream.runHead, Effect.map(Option.getOrUndefined)); |
| 250 | |
| 251 | /** |
| 252 | * List the zone's custom scan expressions, mapping "not observable" |
| 253 | * (scanning disabled on the zone, or the zone itself gone) to `undefined`. |
| 254 | */ |
| 255 | const listExpressions = (zoneId: string) => |
| 256 | contentScanning.listPayloads.items({ zoneId }).pipe( |
| 257 | Stream.runCollect, |
| 258 | Effect.map((chunk): readonly ObservedExpression[] | undefined => Array.from(chunk)), |
| 259 | Effect.catchTags({ |
| 260 | ContentScanningNotEnabled: () => Effect.undefined, |
| 261 | InvalidRoute: () => Effect.undefined, |
| 262 | }), |
| 263 | ); |
| 264 | |
| 265 | const toAttributes = (zoneId: string, expression: ObservedExpression): ExpressionAttributes => ({ |
| 266 | // Cloudflare always echoes both fields for a persisted expression. |
| 267 | expressionId: expression.id ?? "", |
| 268 | zoneId, |
| 269 | payload: expression.payload ?? "", |
| 270 | }); |