sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Firewall/ UaRule.ts

import * as firewall from "@distilled.cloud/cloudflare/firewall";
import { Unowned } from "alchemy/AdoptPolicy";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Predicate from "effect/Predicate";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";
import { listAllZones } from "../Zone/lookup.ts";

const UaRuleTypeId = "Cloudflare.Firewall.UaRule" as const;
type UaRuleTypeId = typeof UaRuleTypeId;

/**
 * The action a User Agent Blocking rule applies to a matched request.
 */
export type UaRuleMode = "block" | "challenge" | "js_challenge" | "managed_challenge";

export interface UaRuleProps {
  /**
   * Zone the rule applies to.
   *
   * Stable — moving a rule between zones triggers a replacement.
   */
  zoneId: string;
  /**
   * The exact User-Agent string to match. The whole UA header must equal
   * this value — no wildcards or substring matching.
   *
   * Mutable — updated in place via PUT. Note that Cloudflare rejects a
   * second rule for the same User-Agent string in a zone, so the value
   * acts as the rule's identity for adoption.
   */
  userAgent: string;
  /**
   * The action to apply to a matched request. Mutable — updated in place.
   */
  mode: UaRuleMode;
  /**
   * An informative summary of the rule. Sanitized server-side (HTML tags
   * are removed). Mutable — updated in place.
   */
  description?: string;
  /**
   * When true, the rule is disabled without being deleted.
   * Mutable — updated in place.
   *
   * @default false
   */
  paused?: boolean;
}

export interface UaRuleAttributes {
  /** Cloudflare-assigned identifier of the User Agent Blocking rule. */
  uaRuleId: string;
  /** Zone the rule belongs to. */
  zoneId: string;
  /** The exact User-Agent string the rule matches. */
  userAgent: string;
  /** The action applied to matched requests. */
  mode: UaRuleMode;
  /** The rule's informative summary, if set. */
  description: string | undefined;
  /** Whether the rule is currently paused. */
  paused: boolean;
}

export type UaRule = Resource<UaRuleTypeId, UaRuleProps, UaRuleAttributes, never, Providers>;

/**
 * A Cloudflare User Agent Blocking rule — block or challenge every request
 * to a zone whose `User-Agent` header exactly matches a given string.
 *
 * Everything about a UA rule is mutable in place: `userAgent`, `mode`,
 * `description`, and `paused` are all updated via PUT without replacing the
 * rule. Only moving the rule to a different zone triggers a replacement.
 *
 * Cloudflare rejects a second rule for the same User-Agent string in a zone
 * with a duplicate error, so the UA string acts as a rule's identity. Plan
 * quotas: Free 10, Pro 50, Business 250, Enterprise 1000 rules.
 *
 * Safety: UA rules carry no ownership markers. When there is no prior
 * state, `read` scans the zone for an existing rule with the same
 * User-Agent string and reports it as `Unowned`, so the engine refuses to
 * take it over unless `--adopt` (or `adopt(true)`) is set.
 * ### Blocking a User-Agent
 * **Example:** Block a scraper outright
 * ```typescript
 * yield* Cloudflare.Firewall.UaRule("BlockScraper", {
 *   zoneId: zone.zoneId,
 *   userAgent: "BadBot/1.2 (+http://badbot.example)",
 *   mode: "block",
 *   description: "aggressive scraper",
 * });
 * ```
 *
 * ### Challenging a User-Agent
 * **Example:** Managed challenge instead of a hard block
 * ```typescript
 * yield* Cloudflare.Firewall.UaRule("ChallengeOldClient", {
 *   zoneId: zone.zoneId,
 *   userAgent: "LegacyApp/0.9",
 *   mode: "managed_challenge",
 * });
 * ```
 *
 * ### Pausing a rule
 * **Example:** Temporarily disable a rule without deleting it
 * ```typescript
 * yield* Cloudflare.Firewall.UaRule("BlockScraper", {
 *   zoneId: zone.zoneId,
 *   userAgent: "BadBot/1.2 (+http://badbot.example)",
 *   mode: "block",
 *   paused: true,
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/waf/tools/user-agent-blocking/
 *
 * @resource
 * @product Firewall
 * @category Application Security
 */
export const UaRule = Resource<UaRule>(UaRuleTypeId);

/**
 * Returns true if the given value is a UaRule resource.
 */
export const isUaRule = (value: unknown): value is UaRule =>
  Predicate.hasProperty(value, "Type") && value.Type === UaRuleTypeId;

export const UaRuleProvider = () =>
  Provider.succeed(UaRule, {
    stables: ["uaRuleId", "zoneId"],

    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // UA rules live inside a zone (`/zones/{zone_id}/firewall/ua_rules`)
      // with no account-wide list — enumerate every zone and exhaustively
      // paginate each one's rules.
      const zones = yield* listAllZones(accountId);
      const rows = yield* Effect.forEach(
        zones,
        (zone) =>
          firewall.listUaRules.pages({ zoneId: zone.id }).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((page) =>
                (page.result ?? []).map((rule) => toAttributes(rule, zone.id)),
              ),
            ),
            // Plan-gated / partial zones (eventually-consistent scoped
            // tokens) reject the route; skip them rather than fail the
            // whole enumeration.
            Effect.catchTag("Forbidden", () => Effect.succeed([])),
          ),
        { concurrency: 10 },
      );
      return rows.flat();
    }),

    diff: Effect.fn(function* ({ olds = {}, news }) {
      const o = olds as UaRuleProps;
      const n = news as UaRuleProps;
      // No prior props to compare against — let the engine decide.
      if (o.zoneId === undefined) return undefined;
      // zoneId is Input<string>; compare only once both are concrete.
      if (typeof o.zoneId === "string" && typeof n.zoneId === "string" && o.zoneId !== n.zoneId) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ output, olds }) {
      const zoneId = output?.zoneId ?? (olds?.zoneId as string | undefined);
      if (zoneId === undefined) return undefined;

      // Owned path: refresh by our persisted rule id.
      if (output?.uaRuleId) {
        const observed = yield* getUaRule(zoneId, output.uaRuleId);
        if (observed) return toAttributes(observed, zoneId);
      }

      // Adoption path: a rule for this User-Agent string may already exist
      // (Cloudflare rejects duplicates, so the UA string is the rule's
      // identity within a zone). UA rules carry no ownership markers, so
      // brand a match `Unowned` and let the engine gate takeover behind
      // the adopt policy.
      const userAgent = output?.userAgent ?? olds?.userAgent;
      if (userAgent) {
        const observed = yield* findByUserAgent(zoneId, userAgent);
        if (observed) return Unowned(toAttributes(observed, zoneId));
      }
      return undefined;
    }),

    reconcile: Effect.fn(function* ({ news, output }) {
      // Inputs have been resolved to concrete strings by Plan.
      const zoneId = news.zoneId as string;

      // 1. Observe — the rule id cached on `output` is a hint, not a
      //    guarantee: a missing rule falls through to the User-Agent scan
      //    and then to create.
      let observed = output?.uaRuleId ? yield* getUaRule(zoneId, output.uaRuleId) : undefined;

      // 2. Fall back to scanning the zone for a User-Agent match.
      //    Ownership has already been verified upstream — `read` reports
      //    existing rules as `Unowned` and the engine gates takeover
      //    behind the adopt policy before reconcile ever runs.
      if (!observed) {
        observed = yield* findByUserAgent(zoneId, news.userAgent);
      }

      // 3. Ensure — create when missing. A concurrent create surfaces as
      //    `DuplicateUaRule` (Cloudflare code 10009): converge by
      //    re-scanning for the rule that won the race.
      if (!observed) {
        observed = yield* firewall
          .createUaRule({
            zoneId,
            configuration: { target: "ua", value: news.userAgent },
            mode: news.mode,
            description: news.description,
            paused: news.paused,
          })
          .pipe(
            Effect.catchTag("DuplicateUaRule", (error) =>
              findByUserAgent(zoneId, news.userAgent).pipe(
                Effect.flatMap((existing) =>
                  existing ? Effect.succeed(existing) : Effect.fail(error),
                ),
              ),
            ),
          );
      }

      // 4. Sync — diff observed cloud state against desired; skip the PUT
      //    entirely on a no-op. Undefined optional props are treated as
      //    "no constraint" so adoption doesn't clobber foreign settings.
      const dirty =
        (observed.configuration?.value ?? "") !== news.userAgent ||
        observed.mode !== news.mode ||
        (news.description !== undefined && (observed.description ?? "") !== news.description) ||
        (news.paused !== undefined && (observed.paused ?? false) !== news.paused);
      if (dirty) {
        observed = yield* firewall.updateUaRule({
          zoneId,
          uaRuleId: observed.id ?? "",
          configuration: { target: "ua", value: news.userAgent },
          mode: news.mode,
          description: news.description,
          paused: news.paused,
        });
      }

      return toAttributes(observed, zoneId);
    }),

    delete: Effect.fn(function* ({ output }) {
      // Cloudflare's DELETE is naturally idempotent (an already-gone rule
      // answers HTTP 200 echoing the id) — the typed catch covers the rare
      // not-found envelope race.
      yield* firewall
        .deleteUaRule({ zoneId: output.zoneId, uaRuleId: output.uaRuleId })
        .pipe(Effect.catchTag("UaRuleNotFound", () => Effect.void));
    }),
  });

// ---------------------------------------------------------------------------
// API helpers
// ---------------------------------------------------------------------------

type ObservedUaRule = firewall.GetUaRuleResponse;

/**
 * Read a UA rule by id, mapping "gone" (`UaRuleNotFound`, Cloudflare error
 * code 10001 `firewalluablock.api.not_found`) to `undefined`.
 */
const getUaRule = (zoneId: string, uaRuleId: string) =>
  firewall.getUaRule({ zoneId, uaRuleId }).pipe(
    Effect.map((rule): ObservedUaRule | undefined => rule),
    Effect.catchTag("UaRuleNotFound", () => Effect.undefined),
  );

/**
 * Find a rule by exact User-Agent string within the zone. The UA string is
 * a rule's identity — Cloudflare rejects duplicates — so at most one rule
 * can match.
 */
const findByUserAgent = (zoneId: string, userAgent: string) =>
  firewall.listUaRules.items({ zoneId }).pipe(
    Stream.runCollect,
    Effect.map((chunk) =>
      Array.from(chunk).find(
        (rule): rule is ObservedUaRule => rule.configuration?.value === userAgent,
      ),
    ),
  );

const toAttributes = (rule: ObservedUaRule, zoneId: string): UaRuleAttributes => ({
  // Distilled types every field as optional/nullable — Cloudflare always
  // echoes them for a persisted rule.
  uaRuleId: rule.id ?? "",
  zoneId,
  userAgent: rule.configuration?.value ?? "",
  mode: (rule.mode ?? "block") as UaRuleMode,
  description: rule.description ?? undefined,
  paused: rule.paused ?? false,
});