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

main
ts 534 lines 18.7 KB
Raw
1 import * as zeroTrust from "@distilled.cloud/cloudflare/zero-trust";
2 import { createPhysicalName } from "alchemy/PhysicalName";
3 import * as Provider from "alchemy/Provider";
4 import { Resource } from "alchemy/Resource";
5 import { arrayEquals } from "alchemy/Util/equal";
6 import * as Data from "effect/Data";
7 import * as Effect from "effect/Effect";
8 import * as Stream from "effect/Stream";
9 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
10 import type { Providers } from "../Providers.ts";
11
12 export class RuleUnexpectedResponse extends Data.TaggedError("RuleUnexpectedResponse")<{
13 readonly message: string;
14 readonly cause?: unknown;
15 }> {}
16
17 /**
18 * Action Cloudflare Gateway takes when a rule's traffic/identity/device-posture
19 * expressions match. Mirrors the open-ended literal union distilled exposes so
20 * unknown values flowing back from Cloudflare narrow cleanly.
21 */
22 export type RuleAction =
23 | "on"
24 | "off"
25 | "allow"
26 | "block"
27 | "scan"
28 | "noscan"
29 | "safesearch"
30 | "ytrestricted"
31 | "isolate"
32 | "noisolate"
33 | "override"
34 | "l4_override"
35 | "egress"
36 | "resolve"
37 | "quarantine"
38 | "redirect"
39 | (string & {});
40
41 /**
42 * Filter Cloudflare Gateway evaluates the rule against. Selects the layer the
43 * `traffic` expression operates on — DNS, HTTP, raw L4, the egress path, or
44 * the `dns_resolver` plane (which is what private-app destinations use when
45 * Gateway needs to override the answer for an internal hostname).
46 */
47 export type RuleFilter = "http" | "dns" | "l4" | "egress" | "dns_resolver" | (string & {});
48
49 /**
50 * Settings the rule applies when it matches. Re-exports distilled's request
51 * shape so every server-recognised knob (override host, block page, DNS
52 * resolvers, BISO controls, egress IPs, redirect target, …) is available
53 * without re-declaring the structure.
54 *
55 * Only a subset is meaningful for any given `action`; consult Cloudflare's
56 * Gateway rule docs for which settings apply per action.
57 */
58 export type RuleSettings = NonNullable<zeroTrust.CreateGatewayRuleRequest["ruleSettings"]>;
59
60 export interface RuleProps {
61 /**
62 * Human-readable rule name. If omitted, a deterministic physical name is
63 * generated from the app/stage/logical-id. Used during adoption to locate
64 * an existing rule by name when no `ruleId` is cached.
65 */
66 name?: string;
67 /**
68 * Action Cloudflare Gateway takes when the rule matches. Stable across
69 * reconciles; changing it triggers a replacement so a rule never silently
70 * flips semantics under existing references.
71 */
72 action: RuleAction;
73 /**
74 * Protocol/layer the rule's `traffic` expression evaluates against.
75 * Cloudflare currently accepts a single filter per rule; the SDK still
76 * types it as an array to mirror the wire shape.
77 */
78 filters: ReadonlyArray<RuleFilter>;
79 /**
80 * Wirefilter expression used for traffic matching. Cloudflare auto-formats
81 * and sanitises this server-side — to avoid perpetual diffs, prefer the
82 * formatted form (e.g. `'any(dns.domains[*] == "internal.example")'`).
83 */
84 traffic?: string;
85 /**
86 * Wirefilter expression used for identity matching (group memberships,
87 * email, IdP attrs). Combined with `traffic` and `devicePosture` via
88 * logical AND.
89 */
90 identity?: string;
91 /**
92 * Wirefilter expression used for device-posture matching (WARP, MDM, etc).
93 */
94 devicePosture?: string;
95 /**
96 * Per-action settings applied when the rule matches. The most common
97 * private-app use case sets `overrideHost` to a `${tunnelId}.cfargotunnel.com`
98 * to point intercepted DNS at a Cloudflare Tunnel.
99 *
100 * @example
101 * ```ts
102 * ruleSettings: {
103 * overrideHost: `${tunnelId}.cfargotunnel.com`,
104 * }
105 * ```
106 */
107 ruleSettings?: RuleSettings;
108 /**
109 * Rule precedence — lower values evaluate first. When unset, Cloudflare
110 * picks one server-side; we then echo whatever it assigned back through
111 * the output attributes.
112 */
113 precedence?: number;
114 /**
115 * Whether the rule is enabled.
116 *
117 * @default true
118 */
119 enabled?: boolean;
120 /**
121 * Free-form description.
122 */
123 description?: string;
124 /**
125 * Adopt an existing rule with the same name (matched during the list-scan
126 * fallback when no `ruleId` is cached) instead of failing on conflict.
127 *
128 * @default false
129 */
130 adopt?: boolean;
131 }
132
133 export interface RuleAttributes {
134 /** Cloudflare-assigned rule UUID. */
135 ruleId: string;
136 /** Resolved display name (server-side). */
137 name: string;
138 /** Resolved action. */
139 action: RuleAction;
140 /** Resolved filters. */
141 filters: ReadonlyArray<RuleFilter>;
142 /** Server-assigned precedence (always populated on the response). */
143 precedence: number;
144 /** Account that owns this rule. */
145 accountId: string;
146 /** ISO8601 creation timestamp. */
147 createdAt: string | undefined;
148 /** ISO8601 last-update timestamp. */
149 updatedAt: string | undefined;
150 }
151
152 export type Rule = Resource<"Cloudflare.Gateway.Rule", RuleProps, RuleAttributes, never, Providers>;
153
154 /**
155 * A Cloudflare Zero Trust Gateway rule.
156 *
157 * Gateway rules sit on the WARP/Gateway data plane and run *before* Access:
158 * they decide whether to allow, block, override, isolate, or redirect a
159 * request based on wirefilter expressions over the request traffic,
160 * the authenticated identity, and the device posture. The most common
161 * companion to {@link Application} with a `private` destination is a
162 * `dns` rule with `action: "override"` that points an internal hostname at
163 * a Cloudflare Tunnel — without it, WARP intercepts the lookup but has
164 * nowhere to send the answer.
165 * ### DNS override for a private app
166 * **Example:** Resolve an internal hostname through a Cloudflare Tunnel
167 * ```typescript
168 * const adminDns = yield* Cloudflare.Gateway.Rule("AdminMicroagiDns", {
169 * name: "research-admin-microagi-dns-override",
170 * action: "override",
171 * filters: ["dns"],
172 * traffic: 'any(dns.domains[*] == "cluster-admin.microagi")',
173 * ruleSettings: {
174 * overrideHost: `${tunnel.tunnelId}.cfargotunnel.com`,
175 * },
176 * enabled: true,
177 * });
178 * ```
179 *
180 * ### Block a category
181 * **Example:** Block known phishing on HTTP
182 * ```typescript
183 * yield* Cloudflare.Gateway.Rule("BlockPhishing", {
184 * name: "block-phishing",
185 * action: "block",
186 * filters: ["http"],
187 * traffic: "any(http.request.uri.content_category[*] in {178})",
188 * });
189 * ```
190 *
191 * @resource
192 * @product Gateway
193 * @category Cloudflare One (Zero Trust)
194 */
195 export const Rule = Resource<Rule>("Cloudflare.Gateway.Rule");
196
197 // ---------------------------------------------------------------------------
198 // Provider
199 // ---------------------------------------------------------------------------
200
201 export const RuleProvider = () =>
202 Provider.effect(
203 Rule,
204 Effect.gen(function* () {
205 const env = yield* CloudflareEnvironment;
206
207 const createRule = yield* zeroTrust.createGatewayRule;
208 const getRule = yield* zeroTrust.getGatewayRule;
209 const updateRule = yield* zeroTrust.updateGatewayRule;
210 const deleteRule = yield* zeroTrust.deleteGatewayRule;
211 const listRules = zeroTrust.listGatewayRules;
212
213 const resolveName = (id: string, name: string | undefined) =>
214 Effect.gen(function* () {
215 if (name) return name;
216 return yield* createPhysicalName({ id });
217 });
218
219 // Locate an existing rule by name when no ruleId is cached — used for
220 // adoption and as a recovery path after a create returns a conflict.
221 const findRuleByName = (accountId: string, name: string) =>
222 listRules.items({ accountId }).pipe(
223 Stream.runCollect,
224 Effect.map((chunk) =>
225 Array.from(chunk).find((r) => (r as { name?: string | null }).name === name),
226 ),
227 Effect.map((found) =>
228 found === undefined ? undefined : narrowRule(found as Parameters<typeof narrowRule>[0]),
229 ),
230 );
231
232 const observeById = (accountId: string, ruleId: string) =>
233 Effect.gen(function* () {
234 const r = yield* getRule({ accountId, ruleId }).pipe(
235 // Distilled tags transport errors but not the live Cloudflare 404
236 // for a missing rule. Swallow generically so the reconcile flow
237 // falls through to recreate.
238 Effect.orElseSucceed(() => undefined),
239 );
240 if (r === undefined) return undefined;
241 return narrowRule(r as Parameters<typeof narrowRule>[0]);
242 });
243
244 return {
245 stables: ["ruleId", "action", "accountId"],
246
247 // Account collection (pattern b): Gateway rules are account-scoped
248 // (`/accounts/{id}/gateway/rules`). Exhaustively page the list op,
249 // narrow each rule, and hydrate the exact `read` Attributes shape.
250 // Rules missing a required field (id/action/filters/precedence) are
251 // dropped rather than surfaced as partial rows.
252 list: () =>
253 Effect.gen(function* () {
254 const { accountId } = yield* env;
255 return yield* listRules.pages({ accountId }).pipe(
256 Stream.runCollect,
257 Effect.map((chunk) =>
258 Array.from(chunk).flatMap((page) =>
259 (page.result ?? []).flatMap((raw) => {
260 const r = narrowRule(raw as Parameters<typeof narrowRule>[0]);
261 if (!r.id || !r.action || !r.filters || r.precedence === undefined) {
262 return [];
263 }
264 return [
265 {
266 ruleId: r.id,
267 name: r.name ?? r.id,
268 action: r.action,
269 filters: r.filters,
270 precedence: r.precedence,
271 accountId,
272 createdAt: r.createdAt,
273 updatedAt: r.updatedAt,
274 } satisfies RuleAttributes,
275 ];
276 }),
277 ),
278 ),
279 );
280 }),
281
282 diff: Effect.fn(function* ({ olds = {}, news }) {
283 if ((olds as RuleProps).action !== undefined) {
284 if ((olds as RuleProps).action !== (news as RuleProps).action) {
285 return { action: "replace" } as const;
286 }
287 }
288 }),
289
290 reconcile: Effect.fn(function* ({ id, news, output }) {
291 const { accountId } = yield* env;
292 const resolvedName = yield* resolveName(id, news.name);
293 const body = buildMutableBody(news, resolvedName);
294
295 // 1. Observe
296 let observed: ObservedRule | undefined;
297 if (output?.ruleId) {
298 observed = yield* observeById(accountId, output.ruleId);
299 }
300 if (!observed) {
301 // Adoption / recovery path — look up by name. Cheap relative to
302 // the create call we'd otherwise blow up on a duplicate name.
303 observed = yield* findRuleByName(accountId, resolvedName);
304 }
305
306 // 2. Ensure
307 if (!observed) {
308 const created = yield* createRule({
309 accountId,
310 name: resolvedName,
311 action: body.action,
312 filters: Array.from(body.filters),
313 traffic: body.traffic,
314 identity: body.identity,
315 devicePosture: body.devicePosture,
316 ruleSettings: body.ruleSettings,
317 precedence: body.precedence,
318 enabled: body.enabled,
319 description: body.description,
320 }).pipe(
321 // Distilled does not tag Conflict — fall back to a name lookup
322 // before re-failing so a racing create still converges.
323 Effect.catch((err) =>
324 Effect.gen(function* () {
325 const existing = yield* findRuleByName(accountId, resolvedName);
326 if (existing) return existing;
327 return yield* err;
328 }),
329 ),
330 );
331 observed = narrowRule(created as Parameters<typeof narrowRule>[0]);
332 }
333
334 // 3. Sync
335 if (!observed.id) {
336 return yield* new RuleUnexpectedResponse({
337 message: "Cloudflare did not return a rule id for Gateway rule",
338 });
339 }
340 if (!bodyEqualsObserved(body, observed)) {
341 const updated = yield* updateRule({
342 accountId,
343 ruleId: observed.id,
344 name: resolvedName,
345 action: body.action,
346 filters: Array.from(body.filters),
347 traffic: body.traffic,
348 identity: body.identity,
349 devicePosture: body.devicePosture,
350 ruleSettings: body.ruleSettings,
351 precedence: body.precedence,
352 enabled: body.enabled,
353 description: body.description,
354 });
355 observed = narrowRule(updated as Parameters<typeof narrowRule>[0]);
356 }
357
358 // 4. Return
359 if (
360 !observed.id ||
361 !observed.action ||
362 !observed.filters ||
363 observed.precedence === undefined
364 ) {
365 return yield* new RuleUnexpectedResponse({
366 message: "Cloudflare returned a Gateway rule without id/action/filters/precedence",
367 });
368 }
369 return {
370 ruleId: observed.id,
371 name: observed.name ?? resolvedName,
372 action: observed.action,
373 filters: observed.filters,
374 precedence: observed.precedence,
375 accountId,
376 createdAt: observed.createdAt,
377 updatedAt: observed.updatedAt,
378 } satisfies RuleAttributes;
379 }),
380
381 delete: Effect.fn(function* ({ output }) {
382 yield* deleteRule({
383 accountId: output.accountId,
384 ruleId: output.ruleId,
385 }).pipe(Effect.catch(() => Effect.void));
386 }),
387
388 read: Effect.fn(function* ({ output }) {
389 if (!output?.ruleId) return undefined;
390 const observed = yield* observeById(output.accountId, output.ruleId);
391 if (
392 !observed?.id ||
393 !observed.action ||
394 !observed.filters ||
395 observed.precedence === undefined
396 ) {
397 return undefined;
398 }
399 return {
400 ruleId: observed.id,
401 name: observed.name ?? output.name,
402 action: observed.action,
403 filters: observed.filters,
404 precedence: observed.precedence,
405 accountId: output.accountId,
406 createdAt: observed.createdAt ?? output.createdAt,
407 updatedAt: observed.updatedAt ?? output.updatedAt,
408 } satisfies RuleAttributes;
409 }),
410 };
411 }),
412 );
413
414 interface ObservedRule {
415 readonly id?: string;
416 readonly name?: string;
417 readonly action?: RuleAction;
418 readonly filters?: ReadonlyArray<RuleFilter>;
419 readonly traffic?: string;
420 readonly identity?: string;
421 readonly devicePosture?: string;
422 readonly precedence?: number;
423 readonly enabled?: boolean;
424 readonly description?: string;
425 readonly ruleSettings?: Record<string, unknown>;
426 readonly createdAt?: string;
427 readonly updatedAt?: string;
428 }
429
430 const undef = <T>(v: T | null | undefined): T | undefined => (v == null ? undefined : v);
431
432 const undefArr = <T>(
433 v: ReadonlyArray<T | null> | null | undefined,
434 ): ReadonlyArray<T> | undefined =>
435 v == null ? undefined : (v.filter((x) => x != null) as ReadonlyArray<T>);
436
437 const narrowRule = (raw: {
438 id?: string | null;
439 name?: string | null;
440 action?: string | null;
441 filters?: ReadonlyArray<RuleFilter | null> | null;
442 traffic?: string | null;
443 identity?: string | null;
444 devicePosture?: string | null;
445 precedence?: number | null;
446 enabled?: boolean | null;
447 description?: string | null;
448 ruleSettings?: Record<string, unknown> | null;
449 createdAt?: string | null;
450 updatedAt?: string | null;
451 }): ObservedRule => ({
452 id: undef(raw.id),
453 name: undef(raw.name),
454 action: raw.action == null ? undefined : (raw.action as RuleAction),
455 filters: undefArr(raw.filters ?? undefined),
456 traffic: undef(raw.traffic),
457 identity: undef(raw.identity),
458 devicePosture: undef(raw.devicePosture),
459 precedence: undef(raw.precedence),
460 enabled: undef(raw.enabled),
461 description: undef(raw.description),
462 ruleSettings: undef(raw.ruleSettings),
463 createdAt: undef(raw.createdAt),
464 updatedAt: undef(raw.updatedAt),
465 });
466
467 // ---------------------------------------------------------------------------
468 // Body construction
469 // ---------------------------------------------------------------------------
470
471 interface RuleMutableBody {
472 name: string;
473 action: RuleAction;
474 filters: ReadonlyArray<RuleFilter>;
475 traffic?: string;
476 identity?: string;
477 devicePosture?: string;
478 ruleSettings?: RuleSettings;
479 precedence?: number;
480 enabled?: boolean;
481 description?: string;
482 }
483
484 const buildMutableBody = (news: RuleProps, resolvedName: string): RuleMutableBody => {
485 const body: RuleMutableBody = {
486 name: resolvedName,
487 action: news.action,
488 filters: news.filters,
489 };
490 if (news.traffic !== undefined) body.traffic = news.traffic;
491 if (news.identity !== undefined) body.identity = news.identity;
492 if (news.devicePosture !== undefined) body.devicePosture = news.devicePosture;
493 if (news.ruleSettings !== undefined) body.ruleSettings = news.ruleSettings;
494 if (news.precedence !== undefined) body.precedence = news.precedence;
495 if (news.enabled !== undefined) body.enabled = news.enabled;
496 if (news.description !== undefined) body.description = news.description;
497 return body;
498 };
499
500 // ---------------------------------------------------------------------------
501 // Drift detection
502 // ---------------------------------------------------------------------------
503
504 const bodyEqualsObserved = (desired: RuleMutableBody, observed: ObservedRule): boolean => {
505 if (desired.name !== observed.name) return false;
506 if (desired.action !== observed.action) return false;
507 if (!arrayEquals(desired.filters, observed.filters)) return false;
508 if (desired.traffic !== undefined && desired.traffic !== observed.traffic) {
509 return false;
510 }
511 if (desired.identity !== undefined && desired.identity !== observed.identity) {
512 return false;
513 }
514 if (desired.devicePosture !== undefined && desired.devicePosture !== observed.devicePosture) {
515 return false;
516 }
517 if (desired.precedence !== undefined && desired.precedence !== observed.precedence) {
518 return false;
519 }
520 if (desired.enabled !== undefined && desired.enabled !== observed.enabled) {
521 return false;
522 }
523 if (desired.description !== undefined && desired.description !== observed.description) {
524 return false;
525 }
526 // ruleSettings is a deeply-nested object whose server echo may include
527 // extra `null` fields. Stringify-compare only when the caller set them.
528 if (desired.ruleSettings !== undefined) {
529 if (JSON.stringify(desired.ruleSettings) !== JSON.stringify(observed.ruleSettings ?? {})) {
530 return false;
531 }
532 }
533 return true;
534 };