sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ PageShield/ Settings.ts

import * as pageShield from "@distilled.cloud/cloudflare/page-shield";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Predicate from "effect/Predicate";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";
import { listAllZones } from "../Zone/lookup.ts";

const TypeId = "Cloudflare.PageShield.Settings" as const;
type TypeId = typeof TypeId;

export interface SettingsProps {
  /**
   * Zone whose Page Shield configuration is managed. Stable — changing
   * the zone triggers a replacement (the old zone's configuration is
   * restored to the values it had before Alchemy managed it).
   */
  zoneId: string;
  /**
   * Whether Page Shield (client-side script monitoring) is enabled on
   * the zone. The resource exists to turn the feature on, so this
   * defaults to `true`. Mutable — updated in place.
   * @default true
   */
  enabled?: boolean;
  /**
   * When true, CSP reports are sent to Cloudflare's own reporting
   * endpoint (`https://csp-reporting.cloudflare.com/...`) instead of
   * the zone's `/cdn-cgi/script_monitor/report` path. Mutable.
   *
   * Setting this to `false` requires the dedicated-domain-reporting
   * entitlement — on non-entitled zones the write fails with the typed
   * `NotEntitled` error.
   * @default true
   */
  useCloudflareReportingEndpoint?: boolean;
  /**
   * When true, the paths associated with connection URLs are also
   * analyzed (not just the host). Mutable.
   *
   * Setting this to `true` requires the connection-monitor entitlement
   * (Business/Enterprise) — on non-entitled zones the write fails with
   * the typed `NotEntitled` error.
   * @default false
   */
  useConnectionUrlPath?: boolean;
}

export interface SettingsAttributes {
  /** Zone the configuration belongs to. */
  zoneId: string;
  /** Whether Page Shield is enabled. */
  enabled: boolean;
  /** Whether CSP reports are sent to Cloudflare's reporting endpoint. */
  useCloudflareReportingEndpoint: boolean;
  /** Whether connection URL paths are analyzed. */
  useConnectionUrlPath: boolean;
  /** When the Page Shield configuration was last updated. */
  updatedAt: string;
  /**
   * The `enabled` flag the zone had before Alchemy first touched the
   * configuration. Restored on destroy.
   */
  initialEnabled: boolean;
  /**
   * The `useCloudflareReportingEndpoint` flag the zone had before
   * Alchemy first touched the configuration. Restored on destroy.
   */
  initialUseCloudflareReportingEndpoint: boolean;
  /**
   * The `useConnectionUrlPath` flag the zone had before Alchemy first
   * touched the configuration. Restored on destroy.
   */
  initialUseConnectionUrlPath: boolean;
}

export type Settings = Resource<TypeId, SettingsProps, SettingsAttributes, never, Providers>;

/**
 * The Page Shield configuration of a Cloudflare zone
 * (`/zones/{zone_id}/page_shield`).
 *
 * Page Shield monitors the JavaScript and connections loaded by your
 * visitors' browsers to detect supply-chain attacks (e.g. Magecart). The
 * configuration is a zone **singleton** — it always exists (default
 * disabled), so this resource never creates or deletes anything physical.
 * Reconcile PUTs the configuration when the observed flags differ from the
 * desired ones; destroy restores the flags the zone had before Alchemy
 * first managed them.
 *
 * Script/connection *monitoring data* requires a Business or Enterprise
 * zone plan, but the configuration endpoints themselves accept reads and
 * `enabled` writes on lower plans. Setting `useConnectionUrlPath: true`
 * or `useCloudflareReportingEndpoint: false` on a non-entitled zone fails
 * with the typed `NotEntitled` error.
 *
 * Only one `Settings` resource per zone makes sense — two
 * instances managing the same zone would fight over the singleton.
 * ### Managing Page Shield
 * **Example:** Enable Page Shield on a zone
 * ```typescript
 * const zone = yield* Cloudflare.Zone.Zone("Site", { name: "example.com" });
 *
 * yield* Cloudflare.PageShield.Settings("PageShield", {
 *   zoneId: zone.zoneId,
 * });
 * ```
 *
 * **Example:** Analyze connection URL paths too
 * ```typescript
 * yield* Cloudflare.PageShield.Settings("PageShield", {
 *   zoneId: zone.zoneId,
 *   useConnectionUrlPath: true,
 * });
 * ```
 *
 * **Example:** Report CSP violations to the zone instead of Cloudflare
 * ```typescript
 * yield* Cloudflare.PageShield.Settings("PageShield", {
 *   zoneId: zone.zoneId,
 *   useCloudflareReportingEndpoint: false,
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/page-shield/
 *
 * @resource
 * @product Page Shield
 * @category Application Security
 */
export const Settings = Resource<Settings>(TypeId);

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

interface DesiredSettings {
  enabled: boolean;
  useCloudflareReportingEndpoint: boolean;
  useConnectionUrlPath: boolean;
}

const desiredSettings = (props: SettingsProps): DesiredSettings => ({
  enabled: props.enabled ?? true,
  useCloudflareReportingEndpoint: props.useCloudflareReportingEndpoint ?? true,
  useConnectionUrlPath: props.useConnectionUrlPath ?? false,
});

export const SettingsProvider = () =>
  Provider.succeed(Settings, {
    nuke: { singleton: true },
    stables: [
      "zoneId",
      "initialEnabled",
      "initialUseCloudflareReportingEndpoint",
      "initialUseConnectionUrlPath",
    ],

    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // No account-wide API for this zone singleton — enumerate every
      // zone in the account and read its configuration (every zone has
      // one, defaulting to disabled).
      const allZones = yield* listAllZones(accountId);
      const rows = yield* Effect.forEach(
        allZones.map((zone) => zone.id),
        (zoneId) =>
          pageShield.getPageShield({ zoneId }).pipe(
            // On a cold enumeration the observed flags are the zone's
            // current state and double as the `initial*` baseline.
            Effect.map((observed) => toAttributes(zoneId, observed, observed)),
            // Zones the scoped token can't read (partial / restricted)
            // reject with the typed `Forbidden` error; skip them.
            Effect.catchTag("Forbidden", () => Effect.undefined),
          ),
        { concurrency: 10 },
      );
      return rows.filter((row): row is SettingsAttributes => row !== undefined);
    }),

    diff: Effect.fn(function* ({ news, output }) {
      if (!isResolved(news)) return undefined;
      // zoneId is the singleton's identity — moving the resource to a
      // different zone replaces it (restoring the old zone on delete).
      if (output !== undefined && output.zoneId !== news.zoneId) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ output, olds }) {
      const zoneId = output?.zoneId ?? (typeof olds?.zoneId === "string" ? olds.zoneId : undefined);
      if (!zoneId) return undefined;
      const observed = yield* pageShield.getPageShield({ zoneId });
      // The configuration is a singleton that always exists with a
      // Cloudflare default — there is nothing to "own", so a cold read
      // adopts freely (never `Unowned`). The observed flags at adoption
      // time become the `initial*` values restored on destroy.
      const initial: DesiredSettings =
        output !== undefined
          ? {
              enabled: output.initialEnabled,
              useCloudflareReportingEndpoint: output.initialUseCloudflareReportingEndpoint,
              useConnectionUrlPath: output.initialUseConnectionUrlPath,
            }
          : observed;
      return toAttributes(zoneId, observed, initial);
    }),

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

      // 1. Observe — the configuration always exists; read its live state.
      const observed = yield* pageShield.getPageShield({ zoneId });

      // 2. Capture — the pre-management flags, restored on destroy.
      //    `output` (including an adoption read) already carries them;
      //    otherwise this is our first touch and the observed flags are
      //    the zone's original.
      const initial: DesiredSettings =
        output !== undefined
          ? {
              enabled: output.initialEnabled,
              useCloudflareReportingEndpoint: output.initialUseCloudflareReportingEndpoint,
              useConnectionUrlPath: output.initialUseConnectionUrlPath,
            }
          : observed;

      // 3. Sync — PUT the full desired body only when something differs.
      const desired = desiredSettings(news);
      if (sameSettings(observed, desired)) {
        return toAttributes(zoneId, observed, initial);
      }
      const updated = yield* pageShield.putPageShield({
        zoneId,
        ...desired,
      });
      return toAttributes(zoneId, updated, initial);
    }),

    delete: Effect.fn(function* ({ output }) {
      const { zoneId } = output;
      const initial: DesiredSettings = {
        enabled: output.initialEnabled,
        useCloudflareReportingEndpoint: output.initialUseCloudflareReportingEndpoint,
        useConnectionUrlPath: output.initialUseConnectionUrlPath,
      };
      // Observe, then restore the pre-management flags; skip the call
      // when they already match (idempotent re-delete after a crash).
      const observed = yield* pageShield.getPageShield({ zoneId });
      if (sameSettings(observed, initial)) return;
      yield* pageShield.putPageShield({ zoneId, ...initial });
    }),
  });

const sameSettings = (a: DesiredSettings, b: DesiredSettings): boolean =>
  a.enabled === b.enabled &&
  a.useCloudflareReportingEndpoint === b.useCloudflareReportingEndpoint &&
  a.useConnectionUrlPath === b.useConnectionUrlPath;

const toAttributes = (
  zoneId: string,
  observed: pageShield.GetPageShieldResponse | pageShield.PutPageShieldResponse,
  initial: DesiredSettings,
): SettingsAttributes => ({
  zoneId,
  enabled: observed.enabled,
  useCloudflareReportingEndpoint: observed.useCloudflareReportingEndpoint,
  useConnectionUrlPath: observed.useConnectionUrlPath,
  updatedAt: observed.updatedAt,
  initialEnabled: initial.enabled,
  initialUseCloudflareReportingEndpoint: initial.useCloudflareReportingEndpoint,
  initialUseConnectionUrlPath: initial.useConnectionUrlPath,
});