@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

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