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

import * as zeroTrust from "@distilled.cloud/cloudflare/zero-trust";
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";

const TypeId = "Cloudflare.Gateway.Configuration" as const;
type TypeId = typeof TypeId;

/**
 * The Gateway account settings blocks this resource can manage. Only the
 * blocks you declare are patched (and captured for restore-on-destroy);
 * everything else on the account configuration is left untouched.
 */
export interface ConfigurationSettings {
  /** Activity logging master toggle for the account. */
  activityLog?: { enabled?: boolean };
  /** Anti-virus scanning of file downloads/uploads. */
  antivirus?: {
    /** Scan on file download. */
    enabledDownloadPhase?: boolean;
    /** Scan on file upload. */
    enabledUploadPhase?: boolean;
    /** Block requests for files that cannot be scanned. */
    failClosed?: boolean;
    /** Block-page notification settings shown when a file is blocked. */
    notificationSettings?: {
      enabled?: boolean;
      includeContext?: boolean;
      msg?: string;
      supportUrl?: string;
    };
  };
  /** Custom block page configuration. */
  blockPage?: {
    /** Background color in hex (e.g. `#1f2937`). */
    backgroundColor?: string;
    /** Enable the custom block page (disabled shows the default page). */
    enabled?: boolean;
    /** Footer text. */
    footerText?: string;
    /** Header text. */
    headerText?: string;
    /** Include rule/policy context on the page. */
    includeContext?: boolean;
    /** URL of a logo image to display. */
    logoPath?: string;
    /** Admin email shown as a mailto: link. */
    mailtoAddress?: string;
    /** Subject prefilled in the mailto: link. */
    mailtoSubject?: string;
    /** Block page mode. */
    mode?: "" | "customized_block_page" | "redirect_uri";
    /** Block page name. */
    name?: string;
    /** Hide the Cloudflare footer. */
    suppressFooter?: boolean;
    /** Redirect URI when `mode` is `redirect_uri`. */
    targetUri?: string;
  };
  /** HTTP body scanning behaviour. */
  bodyScanning?: { inspectionMode?: "deep" | "shallow" };
  /** Clientless browser isolation. */
  browserIsolation?: {
    nonIdentityEnabled?: boolean;
    urlBrowserIsolationEnabled?: boolean;
  };
  /**
   * The Gateway-managed certificate used for TLS interception. Reference
   * a `Cloudflare.Gateway.Certificate`'s `certificateId` here.
   */
  certificate?: { id: string };
  /** Match on both email aliases and the primary address. */
  extendedEmailMatching?: { enabled?: boolean };
  /** FIPS-compliant TLS-only enforcement. */
  fips?: { tls?: boolean };
  /** Host selector (egress by hostname) support. */
  hostSelector?: { enabled?: boolean };
  /** Traffic inspection mode. */
  inspection?: { mode?: "static" | "dynamic" };
  /** Detect protocols on the initial bytes of a connection. */
  protocolDetection?: { enabled?: boolean };
  /** File sandboxing. */
  sandbox?: { enabled?: boolean; fallbackAction?: "allow" | "block" };
  /** TLS decryption (required for HTTP inspection). */
  tlsDecrypt?: { enabled?: boolean };
}

export type ConfigurationBlockKey = keyof ConfigurationSettings;

export interface ConfigurationProps {
  /**
   * The settings blocks to manage. Reconcile patches only the declared
   * blocks (Cloudflare PATCH semantics — undeclared blocks are never
   * touched), and destroy restores each declared block to the value it
   * had before Alchemy first managed it.
   */
  settings: ConfigurationSettings;
}

/**
 * A captured snapshot of the managed settings blocks as observed on
 * Cloudflare before Alchemy first patched them. `null` records a block
 * that was absent at capture time.
 */
export type ConfigurationSnapshot = Partial<Record<ConfigurationBlockKey, unknown>>;

export interface ConfigurationAttributes {
  /** Account that owns the Gateway configuration singleton. */
  accountId: string;
  /** The full observed Gateway settings after reconciliation. */
  settings: unknown;
  /**
   * The managed blocks' pre-management values, restored on destroy so
   * deleting the resource puts the account back the way it was found.
   */
  initialSettings: ConfigurationSnapshot;
  /** ISO8601 creation timestamp of the configuration. */
  createdAt: string | undefined;
  /** ISO8601 last-update timestamp of the configuration. */
  updatedAt: string | undefined;
}

export type Configuration = Resource<
  TypeId,
  ConfigurationProps,
  ConfigurationAttributes,
  never,
  Providers
>;

/**
 * Manages the **singleton** Cloudflare Zero Trust **Gateway configuration**
 * for an account (`/accounts/{accountId}/gateway/configuration`) —
 * account-wide settings like activity logging, TLS decryption, the block
 * page, anti-virus scanning, and browser isolation.
 *
 * The singleton always exists, so reconcile patches only the settings
 * blocks you declare and never clobbers unmanaged blocks. The
 * pre-management value of each managed block is captured on first touch
 * and restored on destroy (capture-and-restore). Blocks that were unset
 * before Alchemy managed them cannot be restored (Cloudflare's API has no
 * way to unset a block) — destroy leaves the last managed value and logs
 * a warning.
 * ### Managing Gateway settings
 * **Example:** Enable activity logging and TLS decryption
 * ```typescript
 * yield* Cloudflare.Gateway.Configuration("Gateway", {
 *   settings: {
 *     activityLog: { enabled: true },
 *     tlsDecrypt: { enabled: true },
 *   },
 * });
 * ```
 *
 * **Example:** Custom block page
 * ```typescript
 * yield* Cloudflare.Gateway.Configuration("Gateway", {
 *   settings: {
 *     blockPage: {
 *       enabled: true,
 *       headerText: "Blocked by IT",
 *       footerText: "Contact support@example.com",
 *       backgroundColor: "#1f2937",
 *     },
 *   },
 * });
 * ```
 *
 * ### TLS interception
 * **Example:** Use a Gateway certificate for inspection
 * ```typescript
 * const cert = yield* Cloudflare.Gateway.Certificate("InspectionCa", {});
 * yield* Cloudflare.Gateway.Configuration("Gateway", {
 *   settings: {
 *     tlsDecrypt: { enabled: true },
 *     certificate: { id: cert.certificateId },
 *   },
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/cloudflare-one/policies/gateway/
 *
 * @resource
 * @product Gateway
 * @category Cloudflare One (Zero Trust)
 */
export const Configuration = Resource<Configuration>(TypeId);

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

export const ConfigurationProvider = () =>
  Provider.succeed(Configuration, {
    nuke: { singleton: true },
    stables: ["accountId", "initialSettings", "createdAt"],

    // Account-wide singleton: the Gateway configuration always exists for
    // the ambient account, so enumeration is a single read returning a
    // one-element array. There is no prior management context, so the
    // restore snapshot is empty.
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const observed = yield* zeroTrust.getGatewayConfiguration({
        accountId,
      });
      return [toAttributes(accountId, observed, {})];
    }),

    read: Effect.fn(function* ({ output, olds }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const acct = output?.accountId ?? accountId;
      const observed = yield* zeroTrust.getGatewayConfiguration({
        accountId: acct,
      });
      // The singleton always exists with account defaults — there is
      // nothing to "own", so a cold read adopts freely. The observed
      // blocks at adoption time become the restore target.
      const managed = managedKeys(olds?.settings ?? {});
      const initialSettings =
        output?.initialSettings ?? captureBlocks(observed.settings ?? {}, managed);
      return toAttributes(acct, observed, initialSettings);
    }),

    reconcile: Effect.fn(function* ({ news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const desired = (news.settings ?? {}) as ConfigurationSettings;
      const managed = managedKeys(desired);

      // 1. Observe — the singleton always exists; read its live state.
      const observed = yield* zeroTrust.getGatewayConfiguration({ accountId });
      const observedSettings = (observed.settings ?? {}) as Record<string, unknown>;

      // 2. Capture — pre-management values for every managed block,
      //    restored on destroy. Blocks newly managed by this update are
      //    captured now; previously captured blocks keep their original
      //    snapshot.
      const initialSettings: ConfigurationSnapshot = {
        ...captureBlocks(observedSettings, managed),
        ...output?.initialSettings,
      };

      // 3. Sync — patch only when a declared block diverges from the
      //    observed state; skip the API entirely on a no-op. PATCH
      //    replaces each provided block wholly and leaves the rest alone.
      const dirty = managed.some((key) => !subsetEquals(desired[key], observedSettings[key]));
      if (!dirty) {
        return toAttributes(accountId, observed, initialSettings);
      }
      yield* zeroTrust.patchGatewayConfiguration({
        accountId,
        settings: pickBlocks(
          desired,
          managed,
        ) as zeroTrust.PatchGatewayConfigurationRequest["settings"],
      });

      // 4. Return — re-read so attrs reflect post-sync truth.
      const final = yield* zeroTrust.getGatewayConfiguration({ accountId });
      return toAttributes(accountId, final, initialSettings);
    }),

    delete: Effect.fn(function* ({ output }) {
      const { accountId, initialSettings } = output;
      const managed = Object.keys(initialSettings) as ConfigurationBlockKey[];
      if (managed.length === 0) return;
      // Observe — restore only the blocks that still diverge from their
      // captured pre-management value (idempotent re-delete).
      const observed = yield* zeroTrust.getGatewayConfiguration({ accountId });
      const observedSettings = (observed.settings ?? {}) as Record<string, unknown>;
      const restore: Record<string, unknown> = {};
      for (const key of managed) {
        const initial = sanitizeBlock(initialSettings[key]);
        const current = sanitizeBlock(observedSettings[key]);
        if (deepEquals(initial ?? null, current ?? null)) continue;
        if (initial === undefined) {
          // The block was absent before we managed it. Cloudflare's PATCH
          // ignores `null` blocks, so an absent block cannot be restored —
          // the last managed value is left in place.
          yield* Effect.logWarning(
            `Gateway configuration block "${key}" was unset before Alchemy managed it and cannot be restored; leaving the current value in place.`,
          );
          continue;
        }
        restore[key] = initial;
      }
      if (Object.keys(restore).length === 0) return;
      yield* zeroTrust.patchGatewayConfiguration({
        accountId,
        settings: restore as zeroTrust.PatchGatewayConfigurationRequest["settings"],
      });
    }),
  });

const managedKeys = (settings: ConfigurationSettings): ConfigurationBlockKey[] =>
  (Object.keys(settings) as ConfigurationBlockKey[]).filter((key) => settings[key] !== undefined);

/**
 * Capture the observed value of each managed block (read-only fields
 * stripped so the snapshot can be patched straight back). Absent blocks
 * are recorded as `null`; they cannot be restored on destroy because
 * Cloudflare's PATCH ignores `null` blocks.
 */
const captureBlocks = (
  observedSettings: Partial<Record<ConfigurationBlockKey, unknown>>,
  keys: ConfigurationBlockKey[],
): ConfigurationSnapshot => {
  const snapshot: ConfigurationSnapshot = {};
  for (const key of keys) {
    snapshot[key] = sanitizeBlock(observedSettings[key]) ?? null;
  }
  return snapshot;
};

const pickBlocks = (
  settings: ConfigurationSettings,
  keys: ConfigurationBlockKey[],
): Record<string, unknown> => {
  const picked: Record<string, unknown> = {};
  for (const key of keys) picked[key] = settings[key];
  return picked;
};

/**
 * Read-only fields Cloudflare reports on settings blocks that the PATCH
 * endpoint does not accept back.
 */
const READ_ONLY_FIELDS = new Set([
  "readOnly",
  "sourceAccount",
  "version",
  "bindingStatus",
  "updatedAt",
]);

/**
 * Strip read-only fields and `null`-valued leaves from an observed block
 * so it can be compared with (and patched back as) a desired block.
 */
const sanitizeBlock = (block: unknown): unknown => {
  if (block === null || block === undefined) return undefined;
  if (Array.isArray(block)) return block.map(sanitizeBlock);
  if (typeof block === "object") {
    const out: Record<string, unknown> = {};
    for (const [k, v] of Object.entries(block as Record<string, unknown>)) {
      if (READ_ONLY_FIELDS.has(k)) continue;
      if (v === null || v === undefined) continue;
      out[k] = sanitizeBlock(v);
    }
    return out;
  }
  return block;
};

/**
 * True when every field declared in `desired` matches `observed`
 * (recursively). Fields the user did not declare are ignored, so an
 * observed block carrying extra server-side fields still counts as
 * converged.
 */
const subsetEquals = (desired: unknown, observed: unknown): boolean => {
  if (desired === undefined) return true;
  if (desired !== null && typeof desired === "object" && !Array.isArray(desired)) {
    if (observed === null || observed === undefined) return false;
    if (typeof observed !== "object" || Array.isArray(observed)) return false;
    return Object.entries(desired as Record<string, unknown>).every(([k, v]) =>
      subsetEquals(v, (observed as Record<string, unknown>)[k]),
    );
  }
  return deepEquals(desired, observed ?? null);
};

const deepEquals = (a: unknown, b: unknown): boolean => {
  if (a === b) return true;
  if (a === null || b === null) return false;
  if (Array.isArray(a) || Array.isArray(b)) {
    if (!Array.isArray(a) || !Array.isArray(b)) return false;
    if (a.length !== b.length) return false;
    return a.every((v, i) => deepEquals(v, b[i]));
  }
  if (typeof a === "object" && typeof b === "object") {
    const ak = Object.keys(a as Record<string, unknown>);
    const bk = Object.keys(b as Record<string, unknown>);
    if (ak.length !== bk.length) return false;
    return ak.every((k) =>
      deepEquals((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k]),
    );
  }
  return false;
};

const toAttributes = (
  accountId: string,
  observed: zeroTrust.GetGatewayConfigurationResponse,
  initialSettings: ConfigurationSnapshot,
): ConfigurationAttributes => ({
  accountId,
  settings: observed.settings ?? {},
  initialSettings,
  createdAt: observed.createdAt ?? undefined,
  updatedAt: observed.updatedAt ?? undefined,
});