sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Firewall/ AccessRule.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 FirewallAccessRuleTypeId = "Cloudflare.Firewall.AccessRule" as const;
type FirewallAccessRuleTypeId = typeof FirewallAccessRuleTypeId;

/**
 * The action an IP Access rule applies to a matched request.
 *
 * Note: `block` for `country`/`asn` targets requires an Enterprise plan;
 * `challenge` and `managed_challenge` work on all plans.
 */
export type AccessRuleMode =
  | "block"
  | "challenge"
  | "whitelist"
  | "js_challenge"
  | "managed_challenge";

/**
 * What a rule's configuration matches on: a single IPv4 (`ip`), a single
 * IPv6 (`ip6`), a CIDR range (`ip_range`), an AS number (`asn`), or a
 * two-letter ISO-3166-1 alpha-2 country code (`country`).
 */
export type AccessRuleTarget = "ip" | "ip6" | "ip_range" | "asn" | "country";

/**
 * The match configuration of an IP Access rule. Immutable — the Cloudflare
 * API only allows `mode`/`notes` to be patched, so changing the
 * configuration replaces the rule.
 */
export interface AccessRuleConfiguration {
  /**
   * What the rule matches on.
   */
  target: AccessRuleTarget;
  /**
   * The value to match — e.g. `198.51.100.4` (`ip`), `2001:db8::/64`
   * (`ip_range`), `AS13335` (`asn`), or `US` (`country`).
   */
  value: string;
}

export interface AccessRuleProps {
  /**
   * Zone the rule applies to. When omitted, the rule is created at the
   * account level and applies to every zone in the account.
   *
   * Stable — moving a rule between scopes triggers a replacement.
   */
  zoneId?: string;
  /**
   * The rule's match configuration (target + value).
   *
   * Immutable — the API has no way to change a rule's configuration
   * (only `mode`/`notes` are patchable), so changing it triggers a
   * replacement.
   */
  configuration: AccessRuleConfiguration;
  /**
   * The action to apply to a matched request. Mutable — patched in place.
   */
  mode: AccessRuleMode;
  /**
   * An informative summary of the rule, typically used as a reminder or
   * explanation. Mutable — patched in place.
   */
  notes?: string;
}

export interface AccessRuleAttributes {
  /** Cloudflare-assigned identifier of the IP Access rule. */
  ruleId: string;
  /** Zone the rule belongs to, or `undefined` for account-scoped rules. */
  zoneId: string | undefined;
  /** Account the rule was created under. */
  accountId: string;
  /** The rule's match configuration. */
  configuration: AccessRuleConfiguration;
  /** The action applied to matched requests. */
  mode: AccessRuleMode;
  /** The actions available for this rule. */
  allowedModes: AccessRuleMode[];
  /** The rule's informative summary, if set. */
  notes: string | undefined;
  /** ISO8601 creation timestamp. */
  createdOn: string | undefined;
  /** ISO8601 last-modified timestamp. */
  modifiedOn: string | undefined;
}

export type AccessRule = Resource<
  FirewallAccessRuleTypeId,
  AccessRuleProps,
  AccessRuleAttributes,
  never,
  Providers
>;

/**
 * A Cloudflare IP Access rule — block, challenge, or whitelist requests by
 * IP, CIDR range, ASN, or country, either on a single zone or across the
 * whole account.
 *
 * A rule's identity is its `configuration` (target + value) within a scope:
 * Cloudflare rejects a second rule for the same configuration with a
 * duplicate error, and the configuration cannot be changed after creation —
 * only `mode` and `notes` are mutable. Changing `configuration` or moving
 * the rule between zone and account scope triggers a replacement.
 *
 * Safety: IP Access rules carry no ownership markers. When there is no
 * prior state, `read` scans the scope for an existing rule with the same
 * configuration and reports it as `Unowned`, so the engine refuses to take
 * it over unless `--adopt` (or `adopt(true)`) is set.
 * ### Blocking an IP
 * **Example:** Block a single IPv4 address on a zone
 * ```typescript
 * yield* Cloudflare.Firewall.AccessRule("BlockBadActor", {
 *   zoneId: zone.zoneId,
 *   configuration: { target: "ip", value: "198.51.100.4" },
 *   mode: "block",
 *   notes: "repeated credential stuffing",
 * });
 * ```
 *
 * **Example:** Block a CIDR range account-wide
 * ```typescript
 * // No zoneId — the rule applies to every zone in the account.
 * yield* Cloudflare.Firewall.AccessRule("BlockScannerRange", {
 *   configuration: { target: "ip_range", value: "203.0.113.0/24" },
 *   mode: "block",
 * });
 * ```
 *
 * ### Challenging traffic
 * **Example:** Managed challenge for a country
 * ```typescript
 * // `block` for country targets is Enterprise-only; challenges work on
 * // all plans.
 * yield* Cloudflare.Firewall.AccessRule("ChallengeCountry", {
 *   zoneId: zone.zoneId,
 *   configuration: { target: "country", value: "KP" },
 *   mode: "managed_challenge",
 * });
 * ```
 *
 * ### Whitelisting
 * **Example:** Always allow an office IP
 * ```typescript
 * yield* Cloudflare.Firewall.AccessRule("AllowOffice", {
 *   zoneId: zone.zoneId,
 *   configuration: { target: "ip", value: "192.0.2.10" },
 *   mode: "whitelist",
 *   notes: "office egress IP",
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/waf/tools/ip-access-rules/
 *
 * @resource
 * @product Firewall
 * @category Application Security
 */
export const AccessRule = Resource<AccessRule>(FirewallAccessRuleTypeId);

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

export const AccessRuleProvider = () =>
  Provider.succeed(AccessRule, {
    stables: ["ruleId", "zoneId", "accountId", "allowedModes", "createdOn"],

    diff: Effect.fn(function* ({ olds = {}, news }) {
      const o = olds as AccessRuleProps;
      const n = news as AccessRuleProps;
      // No prior props to compare against — let the engine decide.
      if (o.configuration === undefined) return undefined;
      // The API can only patch mode/notes — configuration is immutable.
      if (
        o.configuration.target !== n.configuration.target ||
        o.configuration.value !== n.configuration.value
      ) {
        return { action: "replace" } as const;
      }
      // Scope change (zone <-> account, or a different zone) replaces.
      if ((o.zoneId === undefined) !== (n.zoneId === undefined)) {
        return { action: "replace" } as const;
      }
      // 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 { accountId } = yield* yield* CloudflareEnvironment;
      const zoneId = output?.zoneId ?? (olds?.zoneId as string | undefined);
      const acct = output?.accountId ?? accountId;

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

      // Adoption path: a rule with this configuration may already exist in
      // the scope. Access rules carry no ownership markers, so we cannot
      // prove we created it — brand it `Unowned` so the engine refuses to
      // take over unless `adopt` is set.
      const configuration = output?.configuration ?? olds?.configuration;
      if (configuration) {
        const observed = yield* findByConfiguration(zoneId, acct, configuration);
        if (observed) return Unowned(toAttributes(observed, zoneId, acct));
      }
      return undefined;
    }),

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

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

      // 2. Fall back to scanning the scope for a configuration 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* findByConfiguration(zoneId, accountId, news.configuration);
      }

      // 3. Ensure — create when missing. A concurrent create surfaces as
      //    `DuplicateAccessRule` (Cloudflare code 10009): converge by
      //    re-scanning for the rule that won the race.
      if (!observed) {
        observed = yield* createRule(zoneId, accountId, news).pipe(
          Effect.catchTag("DuplicateAccessRule", (error) =>
            findByConfiguration(zoneId, accountId, news.configuration).pipe(
              Effect.flatMap((existing) =>
                existing ? Effect.succeed(existing) : Effect.fail(error),
              ),
            ),
          ),
        );
      }

      // 4. Sync — diff observed mode/notes against desired; skip the
      //    patch call entirely on a no-op.
      const dirty =
        observed.mode !== news.mode ||
        (news.notes !== undefined && (observed.notes ?? "") !== news.notes);
      if (dirty) {
        observed = yield* patchRule(zoneId, accountId, observed.id, news);
      }

      return toAttributes(observed, zoneId, accountId);
    }),

    // IP Access rules are hybrid-scoped: account-level rules (zoneId
    // undefined) plus per-zone rules. Enumerate both — the account
    // collection, then fan out across every zone — and tag each item with
    // its scope so the result matches the exact `read` Attributes shape.
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;

      const accountRules = yield* firewall.listAccessRulesForAccount.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? []).map((rule) => toAttributes(rule, undefined, accountId)),
          ),
        ),
        // No permission to read account-level rules — skip them.
        Effect.catchTag("Forbidden", () => Effect.succeed([])),
      );

      const zones = yield* listAllZones(accountId);
      const zoneRuleGroups = yield* Effect.forEach(
        zones,
        (zone) =>
          firewall.listAccessRulesForZone.pages({ zoneId: zone.id }).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((page) =>
                (page.result ?? []).map((rule) => toAttributes(rule, zone.id, accountId)),
              ),
            ),
            // Plan-gated / partial zones reject the route; skip them.
            Effect.catchTag("Forbidden", () => Effect.succeed([])),
          ),
        { concurrency: 10 },
      );

      return [...accountRules, ...zoneRuleGroups.flat()];
    }),

    delete: Effect.fn(function* ({ output }) {
      // Cloudflare answers DELETE for an already-gone rule with HTTP 200
      // and `result: null` (not an error envelope), which the typed
      // response decode rejects — observe first and treat missing as done.
      const observed = yield* getRule(output.zoneId, output.accountId, output.ruleId);
      if (!observed) return;
      yield* deleteRule(output.zoneId, output.accountId, output.ruleId).pipe(
        Effect.catchTag("AccessRuleNotFound", () => Effect.void),
      );
    }),
  });

// ---------------------------------------------------------------------------
// Scoped API helpers (zone-level when zoneId is set, account-level otherwise)
// ---------------------------------------------------------------------------

type ObservedRule = firewall.GetAccessRuleResponse;

/**
 * Read a rule by id, mapping "gone" (`AccessRuleNotFound`, Cloudflare error
 * code 10001 `firewallaccessrules.api.not_found`) to `undefined`.
 */
const getRule = (zoneId: string | undefined, accountId: string, ruleId: string) =>
  (zoneId !== undefined
    ? firewall.getAccessRuleForZone({ zoneId, ruleId })
    : firewall.getAccessRuleForAccount({ accountId, ruleId })
  ).pipe(
    Effect.map((rule): ObservedRule | undefined => rule),
    Effect.catchTag("AccessRuleNotFound", () => Effect.undefined),
  );

/**
 * Find a rule by exact configuration (target + value) within the scope.
 * The configuration is a rule's identity — Cloudflare rejects duplicates —
 * so at most one rule can match.
 */
const findByConfiguration = (
  zoneId: string | undefined,
  accountId: string,
  configuration: AccessRuleConfiguration,
) =>
  (zoneId !== undefined
    ? firewall.listAccessRulesForZone.items({ zoneId })
    : firewall.listAccessRulesForAccount.items({ accountId })
  ).pipe(
    Stream.runCollect,
    Effect.map((chunk) =>
      Array.from(chunk).find(
        (rule): rule is ObservedRule =>
          rule.configuration.target === configuration.target &&
          rule.configuration.value === configuration.value,
      ),
    ),
  );

const createRule = (zoneId: string | undefined, accountId: string, news: AccessRuleProps) =>
  zoneId !== undefined
    ? firewall.createAccessRuleForZone({
        zoneId,
        configuration: news.configuration,
        mode: news.mode,
        notes: news.notes,
      })
    : firewall.createAccessRuleForAccount({
        accountId,
        configuration: news.configuration,
        mode: news.mode,
        notes: news.notes,
      });

const patchRule = (
  zoneId: string | undefined,
  accountId: string,
  ruleId: string,
  news: AccessRuleProps,
) =>
  zoneId !== undefined
    ? firewall.patchAccessRuleForZone({
        zoneId,
        ruleId,
        configuration: news.configuration,
        mode: news.mode,
        notes: news.notes,
      })
    : firewall.patchAccessRuleForAccount({
        accountId,
        ruleId,
        configuration: news.configuration,
        mode: news.mode,
        notes: news.notes,
      });

const deleteRule = (zoneId: string | undefined, accountId: string, ruleId: string) =>
  zoneId !== undefined
    ? firewall.deleteAccessRuleForZone({ zoneId, ruleId })
    : firewall.deleteAccessRuleForAccount({ accountId, ruleId });

const toAttributes = (
  rule: ObservedRule,
  zoneId: string | undefined,
  accountId: string,
): AccessRuleAttributes => ({
  ruleId: rule.id,
  zoneId,
  accountId,
  configuration: {
    // Distilled types each union variant's target/value as optional —
    // Cloudflare always echoes both for a persisted rule.
    target: (rule.configuration.target ?? "ip") as AccessRuleTarget,
    value: rule.configuration.value ?? "",
  },
  mode: rule.mode as AccessRuleMode,
  allowedModes: [...rule.allowedModes] as AccessRuleMode[],
  notes: rule.notes ?? undefined,
  createdOn: rule.createdOn ?? undefined,
  modifiedOn: rule.modifiedOn ?? undefined,
});