sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Gateway/ Rule.ts

import * as zeroTrust from "@distilled.cloud/cloudflare/zero-trust";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { arrayEquals } from "alchemy/Util/equal";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";

export class RuleUnexpectedResponse extends Data.TaggedError("RuleUnexpectedResponse")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

/**
 * Action Cloudflare Gateway takes when a rule's traffic/identity/device-posture
 * expressions match. Mirrors the open-ended literal union distilled exposes so
 * unknown values flowing back from Cloudflare narrow cleanly.
 */
export type RuleAction =
  | "on"
  | "off"
  | "allow"
  | "block"
  | "scan"
  | "noscan"
  | "safesearch"
  | "ytrestricted"
  | "isolate"
  | "noisolate"
  | "override"
  | "l4_override"
  | "egress"
  | "resolve"
  | "quarantine"
  | "redirect"
  | (string & {});

/**
 * Filter Cloudflare Gateway evaluates the rule against. Selects the layer the
 * `traffic` expression operates on — DNS, HTTP, raw L4, the egress path, or
 * the `dns_resolver` plane (which is what private-app destinations use when
 * Gateway needs to override the answer for an internal hostname).
 */
export type RuleFilter = "http" | "dns" | "l4" | "egress" | "dns_resolver" | (string & {});

/**
 * Settings the rule applies when it matches. Re-exports distilled's request
 * shape so every server-recognised knob (override host, block page, DNS
 * resolvers, BISO controls, egress IPs, redirect target, …) is available
 * without re-declaring the structure.
 *
 * Only a subset is meaningful for any given `action`; consult Cloudflare's
 * Gateway rule docs for which settings apply per action.
 */
export type RuleSettings = NonNullable<zeroTrust.CreateGatewayRuleRequest["ruleSettings"]>;

export interface RuleProps {
  /**
   * Human-readable rule name. If omitted, a deterministic physical name is
   * generated from the app/stage/logical-id. Used during adoption to locate
   * an existing rule by name when no `ruleId` is cached.
   */
  name?: string;
  /**
   * Action Cloudflare Gateway takes when the rule matches. Stable across
   * reconciles; changing it triggers a replacement so a rule never silently
   * flips semantics under existing references.
   */
  action: RuleAction;
  /**
   * Protocol/layer the rule's `traffic` expression evaluates against.
   * Cloudflare currently accepts a single filter per rule; the SDK still
   * types it as an array to mirror the wire shape.
   */
  filters: ReadonlyArray<RuleFilter>;
  /**
   * Wirefilter expression used for traffic matching. Cloudflare auto-formats
   * and sanitises this server-side — to avoid perpetual diffs, prefer the
   * formatted form (e.g. `'any(dns.domains[*] == "internal.example")'`).
   */
  traffic?: string;
  /**
   * Wirefilter expression used for identity matching (group memberships,
   * email, IdP attrs). Combined with `traffic` and `devicePosture` via
   * logical AND.
   */
  identity?: string;
  /**
   * Wirefilter expression used for device-posture matching (WARP, MDM, etc).
   */
  devicePosture?: string;
  /**
   * Per-action settings applied when the rule matches. The most common
   * private-app use case sets `overrideHost` to a `${tunnelId}.cfargotunnel.com`
   * to point intercepted DNS at a Cloudflare Tunnel.
   *
   * @example
   * ```ts
   * ruleSettings: {
   *   overrideHost: `${tunnelId}.cfargotunnel.com`,
   * }
   * ```
   */
  ruleSettings?: RuleSettings;
  /**
   * Rule precedence — lower values evaluate first. When unset, Cloudflare
   * picks one server-side; we then echo whatever it assigned back through
   * the output attributes.
   */
  precedence?: number;
  /**
   * Whether the rule is enabled.
   *
   * @default true
   */
  enabled?: boolean;
  /**
   * Free-form description.
   */
  description?: string;
  /**
   * Adopt an existing rule with the same name (matched during the list-scan
   * fallback when no `ruleId` is cached) instead of failing on conflict.
   *
   * @default false
   */
  adopt?: boolean;
}

export interface RuleAttributes {
  /** Cloudflare-assigned rule UUID. */
  ruleId: string;
  /** Resolved display name (server-side). */
  name: string;
  /** Resolved action. */
  action: RuleAction;
  /** Resolved filters. */
  filters: ReadonlyArray<RuleFilter>;
  /** Server-assigned precedence (always populated on the response). */
  precedence: number;
  /** Account that owns this rule. */
  accountId: string;
  /** ISO8601 creation timestamp. */
  createdAt: string | undefined;
  /** ISO8601 last-update timestamp. */
  updatedAt: string | undefined;
}

export type Rule = Resource<"Cloudflare.Gateway.Rule", RuleProps, RuleAttributes, never, Providers>;

/**
 * A Cloudflare Zero Trust Gateway rule.
 *
 * Gateway rules sit on the WARP/Gateway data plane and run *before* Access:
 * they decide whether to allow, block, override, isolate, or redirect a
 * request based on wirefilter expressions over the request traffic,
 * the authenticated identity, and the device posture. The most common
 * companion to {@link Application} with a `private` destination is a
 * `dns` rule with `action: "override"` that points an internal hostname at
 * a Cloudflare Tunnel — without it, WARP intercepts the lookup but has
 * nowhere to send the answer.
 * ### DNS override for a private app
 * **Example:** Resolve an internal hostname through a Cloudflare Tunnel
 * ```typescript
 * const adminDns = yield* Cloudflare.Gateway.Rule("AdminMicroagiDns", {
 *   name: "research-admin-microagi-dns-override",
 *   action: "override",
 *   filters: ["dns"],
 *   traffic: 'any(dns.domains[*] == "cluster-admin.microagi")',
 *   ruleSettings: {
 *     overrideHost: `${tunnel.tunnelId}.cfargotunnel.com`,
 *   },
 *   enabled: true,
 * });
 * ```
 *
 * ### Block a category
 * **Example:** Block known phishing on HTTP
 * ```typescript
 * yield* Cloudflare.Gateway.Rule("BlockPhishing", {
 *   name: "block-phishing",
 *   action: "block",
 *   filters: ["http"],
 *   traffic: "any(http.request.uri.content_category[*] in {178})",
 * });
 * ```
 *
 * @resource
 * @product Gateway
 * @category Cloudflare One (Zero Trust)
 */
export const Rule = Resource<Rule>("Cloudflare.Gateway.Rule");

// ---------------------------------------------------------------------------
// Provider
// ---------------------------------------------------------------------------

export const RuleProvider = () =>
  Provider.effect(
    Rule,
    Effect.gen(function* () {
      const env = yield* CloudflareEnvironment;

      const createRule = yield* zeroTrust.createGatewayRule;
      const getRule = yield* zeroTrust.getGatewayRule;
      const updateRule = yield* zeroTrust.updateGatewayRule;
      const deleteRule = yield* zeroTrust.deleteGatewayRule;
      const listRules = zeroTrust.listGatewayRules;

      const resolveName = (id: string, name: string | undefined) =>
        Effect.gen(function* () {
          if (name) return name;
          return yield* createPhysicalName({ id });
        });

      // Locate an existing rule by name when no ruleId is cached — used for
      // adoption and as a recovery path after a create returns a conflict.
      const findRuleByName = (accountId: string, name: string) =>
        listRules.items({ accountId }).pipe(
          Stream.runCollect,
          Effect.map((chunk) =>
            Array.from(chunk).find((r) => (r as { name?: string | null }).name === name),
          ),
          Effect.map((found) =>
            found === undefined ? undefined : narrowRule(found as Parameters<typeof narrowRule>[0]),
          ),
        );

      const observeById = (accountId: string, ruleId: string) =>
        Effect.gen(function* () {
          const r = yield* getRule({ accountId, ruleId }).pipe(
            // Distilled tags transport errors but not the live Cloudflare 404
            // for a missing rule. Swallow generically so the reconcile flow
            // falls through to recreate.
            Effect.orElseSucceed(() => undefined),
          );
          if (r === undefined) return undefined;
          return narrowRule(r as Parameters<typeof narrowRule>[0]);
        });

      return {
        stables: ["ruleId", "action", "accountId"],

        // Account collection (pattern b): Gateway rules are account-scoped
        // (`/accounts/{id}/gateway/rules`). Exhaustively page the list op,
        // narrow each rule, and hydrate the exact `read` Attributes shape.
        // Rules missing a required field (id/action/filters/precedence) are
        // dropped rather than surfaced as partial rows.
        list: () =>
          Effect.gen(function* () {
            const { accountId } = yield* env;
            return yield* listRules.pages({ accountId }).pipe(
              Stream.runCollect,
              Effect.map((chunk) =>
                Array.from(chunk).flatMap((page) =>
                  (page.result ?? []).flatMap((raw) => {
                    const r = narrowRule(raw as Parameters<typeof narrowRule>[0]);
                    if (!r.id || !r.action || !r.filters || r.precedence === undefined) {
                      return [];
                    }
                    return [
                      {
                        ruleId: r.id,
                        name: r.name ?? r.id,
                        action: r.action,
                        filters: r.filters,
                        precedence: r.precedence,
                        accountId,
                        createdAt: r.createdAt,
                        updatedAt: r.updatedAt,
                      } satisfies RuleAttributes,
                    ];
                  }),
                ),
              ),
            );
          }),

        diff: Effect.fn(function* ({ olds = {}, news }) {
          if ((olds as RuleProps).action !== undefined) {
            if ((olds as RuleProps).action !== (news as RuleProps).action) {
              return { action: "replace" } as const;
            }
          }
        }),

        reconcile: Effect.fn(function* ({ id, news, output }) {
          const { accountId } = yield* env;
          const resolvedName = yield* resolveName(id, news.name);
          const body = buildMutableBody(news, resolvedName);

          // 1. Observe
          let observed: ObservedRule | undefined;
          if (output?.ruleId) {
            observed = yield* observeById(accountId, output.ruleId);
          }
          if (!observed) {
            // Adoption / recovery path — look up by name. Cheap relative to
            // the create call we'd otherwise blow up on a duplicate name.
            observed = yield* findRuleByName(accountId, resolvedName);
          }

          // 2. Ensure
          if (!observed) {
            const created = yield* createRule({
              accountId,
              name: resolvedName,
              action: body.action,
              filters: Array.from(body.filters),
              traffic: body.traffic,
              identity: body.identity,
              devicePosture: body.devicePosture,
              ruleSettings: body.ruleSettings,
              precedence: body.precedence,
              enabled: body.enabled,
              description: body.description,
            }).pipe(
              // Distilled does not tag Conflict — fall back to a name lookup
              // before re-failing so a racing create still converges.
              Effect.catch((err) =>
                Effect.gen(function* () {
                  const existing = yield* findRuleByName(accountId, resolvedName);
                  if (existing) return existing;
                  return yield* err;
                }),
              ),
            );
            observed = narrowRule(created as Parameters<typeof narrowRule>[0]);
          }

          // 3. Sync
          if (!observed.id) {
            return yield* new RuleUnexpectedResponse({
              message: "Cloudflare did not return a rule id for Gateway rule",
            });
          }
          if (!bodyEqualsObserved(body, observed)) {
            const updated = yield* updateRule({
              accountId,
              ruleId: observed.id,
              name: resolvedName,
              action: body.action,
              filters: Array.from(body.filters),
              traffic: body.traffic,
              identity: body.identity,
              devicePosture: body.devicePosture,
              ruleSettings: body.ruleSettings,
              precedence: body.precedence,
              enabled: body.enabled,
              description: body.description,
            });
            observed = narrowRule(updated as Parameters<typeof narrowRule>[0]);
          }

          // 4. Return
          if (
            !observed.id ||
            !observed.action ||
            !observed.filters ||
            observed.precedence === undefined
          ) {
            return yield* new RuleUnexpectedResponse({
              message: "Cloudflare returned a Gateway rule without id/action/filters/precedence",
            });
          }
          return {
            ruleId: observed.id,
            name: observed.name ?? resolvedName,
            action: observed.action,
            filters: observed.filters,
            precedence: observed.precedence,
            accountId,
            createdAt: observed.createdAt,
            updatedAt: observed.updatedAt,
          } satisfies RuleAttributes;
        }),

        delete: Effect.fn(function* ({ output }) {
          yield* deleteRule({
            accountId: output.accountId,
            ruleId: output.ruleId,
          }).pipe(Effect.catch(() => Effect.void));
        }),

        read: Effect.fn(function* ({ output }) {
          if (!output?.ruleId) return undefined;
          const observed = yield* observeById(output.accountId, output.ruleId);
          if (
            !observed?.id ||
            !observed.action ||
            !observed.filters ||
            observed.precedence === undefined
          ) {
            return undefined;
          }
          return {
            ruleId: observed.id,
            name: observed.name ?? output.name,
            action: observed.action,
            filters: observed.filters,
            precedence: observed.precedence,
            accountId: output.accountId,
            createdAt: observed.createdAt ?? output.createdAt,
            updatedAt: observed.updatedAt ?? output.updatedAt,
          } satisfies RuleAttributes;
        }),
      };
    }),
  );

interface ObservedRule {
  readonly id?: string;
  readonly name?: string;
  readonly action?: RuleAction;
  readonly filters?: ReadonlyArray<RuleFilter>;
  readonly traffic?: string;
  readonly identity?: string;
  readonly devicePosture?: string;
  readonly precedence?: number;
  readonly enabled?: boolean;
  readonly description?: string;
  readonly ruleSettings?: Record<string, unknown>;
  readonly createdAt?: string;
  readonly updatedAt?: string;
}

const undef = <T>(v: T | null | undefined): T | undefined => (v == null ? undefined : v);

const undefArr = <T>(
  v: ReadonlyArray<T | null> | null | undefined,
): ReadonlyArray<T> | undefined =>
  v == null ? undefined : (v.filter((x) => x != null) as ReadonlyArray<T>);

const narrowRule = (raw: {
  id?: string | null;
  name?: string | null;
  action?: string | null;
  filters?: ReadonlyArray<RuleFilter | null> | null;
  traffic?: string | null;
  identity?: string | null;
  devicePosture?: string | null;
  precedence?: number | null;
  enabled?: boolean | null;
  description?: string | null;
  ruleSettings?: Record<string, unknown> | null;
  createdAt?: string | null;
  updatedAt?: string | null;
}): ObservedRule => ({
  id: undef(raw.id),
  name: undef(raw.name),
  action: raw.action == null ? undefined : (raw.action as RuleAction),
  filters: undefArr(raw.filters ?? undefined),
  traffic: undef(raw.traffic),
  identity: undef(raw.identity),
  devicePosture: undef(raw.devicePosture),
  precedence: undef(raw.precedence),
  enabled: undef(raw.enabled),
  description: undef(raw.description),
  ruleSettings: undef(raw.ruleSettings),
  createdAt: undef(raw.createdAt),
  updatedAt: undef(raw.updatedAt),
});

// ---------------------------------------------------------------------------
// Body construction
// ---------------------------------------------------------------------------

interface RuleMutableBody {
  name: string;
  action: RuleAction;
  filters: ReadonlyArray<RuleFilter>;
  traffic?: string;
  identity?: string;
  devicePosture?: string;
  ruleSettings?: RuleSettings;
  precedence?: number;
  enabled?: boolean;
  description?: string;
}

const buildMutableBody = (news: RuleProps, resolvedName: string): RuleMutableBody => {
  const body: RuleMutableBody = {
    name: resolvedName,
    action: news.action,
    filters: news.filters,
  };
  if (news.traffic !== undefined) body.traffic = news.traffic;
  if (news.identity !== undefined) body.identity = news.identity;
  if (news.devicePosture !== undefined) body.devicePosture = news.devicePosture;
  if (news.ruleSettings !== undefined) body.ruleSettings = news.ruleSettings;
  if (news.precedence !== undefined) body.precedence = news.precedence;
  if (news.enabled !== undefined) body.enabled = news.enabled;
  if (news.description !== undefined) body.description = news.description;
  return body;
};

// ---------------------------------------------------------------------------
// Drift detection
// ---------------------------------------------------------------------------

const bodyEqualsObserved = (desired: RuleMutableBody, observed: ObservedRule): boolean => {
  if (desired.name !== observed.name) return false;
  if (desired.action !== observed.action) return false;
  if (!arrayEquals(desired.filters, observed.filters)) return false;
  if (desired.traffic !== undefined && desired.traffic !== observed.traffic) {
    return false;
  }
  if (desired.identity !== undefined && desired.identity !== observed.identity) {
    return false;
  }
  if (desired.devicePosture !== undefined && desired.devicePosture !== observed.devicePosture) {
    return false;
  }
  if (desired.precedence !== undefined && desired.precedence !== observed.precedence) {
    return false;
  }
  if (desired.enabled !== undefined && desired.enabled !== observed.enabled) {
    return false;
  }
  if (desired.description !== undefined && desired.description !== observed.description) {
    return false;
  }
  // ruleSettings is a deeply-nested object whose server echo may include
  // extra `null` fields. Stringify-compare only when the caller set them.
  if (desired.ruleSettings !== undefined) {
    if (JSON.stringify(desired.ruleSettings) !== JSON.stringify(observed.ruleSettings ?? {})) {
      return false;
    }
  }
  return true;
};