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

import * as hostnames from "@distilled.cloud/cloudflare/hostnames";
import { Unowned } from "alchemy/AdoptPolicy";
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.HostnameTlsSetting.HostnameTlsSetting" as const;
type TypeId = typeof TypeId;

/**
 * Which per-hostname TLS setting to override:
 *
 * - `ciphers` — allowed cipher suites (BoringSSL names) for the hostname
 * - `min_tls_version` — minimum TLS protocol version for the hostname
 * - `http2` — whether HTTP/2 is offered to clients connecting to the hostname
 */
export type Id = "ciphers" | "min_tls_version" | "http2";

/**
 * The value of a per-hostname TLS setting. The shape depends on
 * {@link Id}:
 *
 * - `ciphers` → `string[]` of BoringSSL cipher suite names
 * - `min_tls_version` → `"1.0" | "1.1" | "1.2" | "1.3"`
 * - `http2` → `"on" | "off"`
 */
export type Value = "1.0" | "1.1" | "1.2" | "1.3" | "on" | "off" | string[];

export interface Props {
  /**
   * Zone the hostname belongs to. Stable — moving the override to another
   * zone triggers a replacement.
   */
  zoneId: string;
  /**
   * Which TLS setting to override (`ciphers`, `min_tls_version`, or
   * `http2`). Part of the override's identity — changing it triggers a
   * replacement.
   */
  settingId: Id;
  /**
   * The hostname the override applies to. Part of the override's identity —
   * changing it triggers a replacement.
   *
   * Per-hostname TLS settings require the hostname to be covered by
   * Cloudflare for SaaS custom hostnames or an Advanced Certificate
   * Manager certificate on the zone; without that entitlement the API
   * rejects writes with `AdvancedCertificateManagerRequired`.
   */
  hostname: string;
  /**
   * Desired value of the setting. The shape depends on `settingId`:
   * `ciphers` takes a `string[]` of BoringSSL cipher names,
   * `min_tls_version` takes `"1.0" | "1.1" | "1.2" | "1.3"`, and `http2`
   * takes `"on" | "off"`.
   *
   * Mutable — upserted in place via PUT.
   */
  value: Value;
}

export interface Attributes {
  /** Zone the hostname belongs to. */
  zoneId: string;
  /** The overridden TLS setting's identifier. */
  settingId: string;
  /** The hostname the override applies to. */
  hostname: string;
  /** Current value of the override. */
  value: Value;
  /**
   * Deployment status of the override (e.g. `pending_deployment`,
   * `active`). Propagation to the edge is asynchronous.
   */
  status: string | undefined;
  /** When the override was first created, if Cloudflare reports it. */
  createdAt: string | undefined;
  /** When the override was last updated, if Cloudflare reports it. */
  updatedAt: string | undefined;
}

export type HostnameTlsSetting = Resource<TypeId, Props, Attributes, never, Providers>;

/**
 * A per-hostname TLS setting override
 * (`/zones/{zone_id}/hostnames/settings/{settingId}/{hostname}`) — pins
 * `ciphers`, `min_tls_version`, or `http2` for a single hostname instead of
 * the whole zone.
 *
 * Each `(settingId, hostname)` pair is an independent override with PUT
 * (upsert) / DELETE semantics; deleting the override reverts the hostname to
 * the zone-wide default. Overrides are mostly useful with Cloudflare for
 * SaaS custom hostnames or Advanced Certificate Manager — on zones without
 * that entitlement, writes fail with the typed
 * `AdvancedCertificateManagerRequired` error (Cloudflare code 1450).
 *
 * Safety: overrides carry no ownership markers. When there is no prior
 * state, `read` scans the setting's hostname list and reports an existing
 * override as `Unowned`, so the engine refuses to take it over unless
 * `--adopt` (or `adopt(true)`) is set.
 * ### Minimum TLS version
 * **Example:** Require TLS 1.2 for a single hostname
 * ```typescript
 * yield* Cloudflare.HostnameTlsSetting.HostnameTlsSetting("ApiMinTls", {
 *   zoneId: zone.zoneId,
 *   settingId: "min_tls_version",
 *   hostname: "api.example.com",
 *   value: "1.2",
 * });
 * ```
 *
 * ### HTTP/2
 * **Example:** Disable HTTP/2 for a legacy hostname
 * ```typescript
 * yield* Cloudflare.HostnameTlsSetting.HostnameTlsSetting("LegacyHttp2", {
 *   zoneId: zone.zoneId,
 *   settingId: "http2",
 *   hostname: "legacy.example.com",
 *   value: "off",
 * });
 * ```
 *
 * ### Cipher suites
 * **Example:** Restrict a hostname to modern ciphers
 * ```typescript
 * yield* Cloudflare.HostnameTlsSetting.HostnameTlsSetting("StrictCiphers", {
 *   zoneId: zone.zoneId,
 *   settingId: "ciphers",
 *   hostname: "secure.example.com",
 *   value: ["ECDHE-RSA-AES128-GCM-SHA256", "AES128-GCM-SHA256"],
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/ssl/edge-certificates/additional-options/custom-metadata/
 * @see https://developers.cloudflare.com/api/resources/hostnames/subresources/settings/subresources/tls/
 *
 * @resource
 * @product Hostname TLS Settings
 * @category SSL/TLS & Certificates
 */
export const HostnameTlsSetting = Resource<HostnameTlsSetting>(TypeId, {
  aliases: ["Cloudflare.HostnameTlsSetting"],
});

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

export const HostnameTlsSettingProvider = () =>
  Provider.succeed(HostnameTlsSetting, {
    stables: ["zoneId", "settingId", "hostname", "createdAt"],

    list: Effect.fn(function* () {
      // Enumerate every override, including subdomains, through the zone's
      // collection endpoint. The per-hostname GET returns 405 on live zones.
      const { accountId } = yield* yield* CloudflareEnvironment;
      const zones = yield* listAllZones(accountId);
      const settingIds: Id[] = ["ciphers", "min_tls_version", "http2"];
      const rows = yield* Effect.forEach(
        zones,
        (zone) =>
          Effect.forEach(
            settingIds,
            (settingId) =>
              hostnames
                .listSettingsTls({ zoneId: zone.id, settingId })
                .pipe(
                  Effect.map((settings) =>
                    settings.flatMap((setting) =>
                      setting.hostname == null
                        ? []
                        : [toAttributes(zone.id, settingId, setting.hostname, setting)],
                    ),
                  ),
                ),
            { concurrency: "unbounded" },
          ).pipe(Effect.map((perSetting) => perSetting.flat())),
        { concurrency: 10 },
      );
      return rows.flat();
    }),

    diff: Effect.fn(function* ({ olds, news, output }) {
      // `news` may still carry unresolved plan-time expressions — defer to
      // the engine's default update logic until everything is concrete.
      if (!isResolved(news)) return undefined;
      // (settingId, hostname) is the override's identity.
      const oldSettingId = output?.settingId ?? olds?.settingId;
      if (oldSettingId !== undefined && oldSettingId !== news.settingId) {
        return { action: "replace" } as const;
      }
      const oldHostname = output?.hostname ?? olds?.hostname;
      if (oldHostname !== undefined && oldHostname !== news.hostname) {
        return { action: "replace" } as const;
      }
      // zoneId is Input<string>; compare only once both sides are concrete.
      const oldZoneId =
        output?.zoneId ?? (typeof olds?.zoneId === "string" ? olds.zoneId : undefined);
      if (oldZoneId !== undefined && typeof news.zoneId === "string" && oldZoneId !== 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);
      const settingId = output?.settingId ?? olds?.settingId;
      const hostname = output?.hostname ?? olds?.hostname;
      if (!zoneId || !settingId || !hostname) return undefined;

      const observed = yield* findSetting(zoneId, settingId, hostname);
      if (observed === undefined) return undefined;

      const attrs = toAttributes(zoneId, settingId, hostname, observed);
      // Overrides carry no ownership markers — on a cold read (no prior
      // state) we cannot prove we created it, so brand it `Unowned` and
      // let the engine gate takeover behind the adopt policy.
      return output !== undefined ? attrs : Unowned(attrs);
    }),

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

      // 1. Observe — list the setting's overrides and match on hostname.
      const observed = yield* findSetting(zoneId, settingId, hostname);

      // 2. Sync — PUT is a true upsert, so a single call covers both the
      //    missing and the drifted case; skip it entirely on a no-op.
      if (observed !== undefined && valueEquals(observed.value, news.value)) {
        return toAttributes(zoneId, settingId, hostname, observed);
      }
      const updated = yield* hostnames.putSettingTls({
        zoneId,
        settingId,
        hostname,
        value: news.value,
      });
      // The list can briefly echo a stale value after the PUT (edge
      // deployment is async) — trust the PUT response, not a re-read.
      return toAttributes(zoneId, settingId, hostname, updated);
    }),

    delete: Effect.fn(function* ({ output }) {
      const { zoneId, settingId, hostname } = output;
      // Observe first — deleting an already-removed override is not an
      // error (idempotent re-delete after a crashed run).
      const observed = yield* findSetting(zoneId, settingId, hostname);
      if (observed === undefined) return;
      yield* hostnames.deleteSettingTls({ zoneId, settingId, hostname }).pipe(
        // Lost a race with an out-of-band delete — already converged.
        Effect.catchTag("HostnameTlsSettingNotFound", () => Effect.void),
      );
    }),
  });

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

type ObservedSetting = hostnames.ListSettingsTlsResponse[number];

const findSetting = (zoneId: string, settingId: string, hostname: string) =>
  hostnames
    .listSettingsTls({ zoneId, settingId })
    .pipe(Effect.map((settings) => settings.find((setting) => setting.hostname === hostname)));

/**
 * Structural equality for setting values — scalar versions/toggles compare
 * by identity, cipher lists element-wise (order matters: the list is the
 * client-facing preference order).
 */
const valueEquals = (a: ObservedSetting["value"], b: Value): boolean => {
  if (Array.isArray(a) || Array.isArray(b)) {
    if (!Array.isArray(a) || !Array.isArray(b)) return false;
    return a.length === b.length && a.every((v, i) => v === b[i]);
  }
  return a === b;
};

const toAttributes = (
  zoneId: string,
  settingId: string,
  hostname: string,
  setting: ObservedSetting | hostnames.PutSettingTlsResponse,
): Attributes => ({
  zoneId,
  settingId,
  hostname,
  value: normalizeValue(setting.value),
  status: setting.status ?? undefined,
  createdAt: setting.createdAt ?? undefined,
  updatedAt: setting.updatedAt ?? undefined,
});

/**
 * Distilled types the echoed value as nullable and cipher arrays as
 * `readonly string[]` — normalize to the props-facing shape. A persisted
 * override always carries a value; fall back to `"off"` purely to satisfy
 * the type.
 */
const normalizeValue = (value: ObservedSetting["value"]): Value =>
  value === null || value === undefined ? "off" : Array.isArray(value) ? [...value] : value;