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

import * as originTls from "@distilled.cloud/cloudflare/origin-tls-client-auth";
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 type { Providers } from "../Providers.ts";

const TypeId = "Cloudflare.OriginTlsClientAuth.HostnameAssociation" as const;
type TypeId = typeof TypeId;

/**
 * Deployment status of the association or its pinned certificate. Changes
 * propagate asynchronously (`pending_deployment` → `active`), typically
 * settling within seconds.
 */
export type HostnameAssociationStatus =
  | "initializing"
  | "pending_deployment"
  | "pending_deletion"
  | "active"
  | "deleted"
  | "deployment_timed_out"
  | "deletion_timed_out"
  // Keep the union open so new Cloudflare statuses aren't blocked by stale types.
  | (string & {});

export type HostnameAssociationProps = {
  /**
   * Zone the hostname belongs to. Cannot be changed — updating this property
   * triggers a replacement.
   */
  zoneId: string;
  /**
   * The hostname on the origin for which the client certificate will be
   * presented. Must be a hostname of the zone. This is the association's
   * identity — updating it triggers a replacement (the old hostname's
   * association is voided).
   */
  hostname: string;
  /**
   * Identifier of the hostname client certificate
   * ({@link HostnameCertificate}) presented to the origin
   * for this hostname. Required by Cloudflare for every hostname AOP
   * configuration. Mutable — updated in place.
   */
  certId: string;
  /**
   * Whether hostname-level Authenticated Origin Pulls is enabled for this
   * hostname. Mutable — updated in place. On destroy the association is
   * voided (Cloudflare's `enabled: null`), restoring the hostname to
   * zone-level behavior.
   */
  enabled: boolean;
};

export type HostnameAssociationAttributes = {
  /** Zone the hostname belongs to. */
  zoneId: string;
  /** The hostname the association applies to. */
  hostname: string;
  /** Identifier of the pinned hostname client certificate. */
  certId: string;
  /** Whether hostname-level Authenticated Origin Pulls is enabled. */
  enabled: boolean;
  /** Deployment status of the association. */
  status: HostnameAssociationStatus | undefined;
  /** Deployment status of the pinned certificate. */
  certStatus: HostnameAssociationStatus | undefined;
};

export type HostnameAssociation = Resource<
  TypeId,
  HostnameAssociationProps,
  HostnameAssociationAttributes,
  never,
  Providers
>;

/**
 * A per-hostname Authenticated Origin Pulls (AOP) association
 * (`/zones/{zone_id}/origin_tls_client_auth/hostnames`).
 *
 * Pins a hostname client certificate
 * ({@link HostnameCertificate}) to a hostname and toggles
 * hostname-level AOP for it. Cloudflare's API is a bulk upsert keyed by
 * hostname; this resource manages exactly one hostname per instance, so
 * separate instances for different hostnames are safe to deploy
 * concurrently. On destroy the association is voided (`enabled: null`),
 * which restores the hostname to zone-level AOP behavior.
 * ### Enabling AOP for a hostname
 * **Example:** Associate a hostname with a client certificate
 * ```typescript
 * const cert = yield* Cloudflare.OriginTlsClientAuth.HostnameCertificate("AopHostCert", {
 *   zoneId: zone.zoneId,
 *   certificate: clientCertPem,
 *   privateKey: yield* Config.Redacted("AOP_CLIENT_KEY"),
 * });
 *
 * yield* Cloudflare.OriginTlsClientAuth.HostnameAssociation("AopHost", {
 *   zoneId: zone.zoneId,
 *   hostname: "api.example.com",
 *   certId: cert.certificateId,
 *   enabled: true,
 * });
 * ```
 *
 * **Example:** Keep the certificate pinned but disable enforcement
 * ```typescript
 * yield* Cloudflare.OriginTlsClientAuth.HostnameAssociation("AopHost", {
 *   zoneId: zone.zoneId,
 *   hostname: "api.example.com",
 *   certId: cert.certificateId,
 *   enabled: false,
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/ssl/origin-configuration/authenticated-origin-pull/set-up/per-hostname/
 *
 * @resource
 * @product Origin TLS Client Auth
 * @category SSL/TLS & Certificates
 */
export const HostnameAssociation = Resource<HostnameAssociation>(TypeId);

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

export const HostnameAssociationProvider = () =>
  Provider.succeed(HostnameAssociation, {
    stables: ["zoneId", "hostname"],

    // Non-listable: an association is keyed entirely by {zoneId, hostname}
    // and the only read op is `getHostname({ zoneId, hostname })`. Cloudflare
    // exposes no endpoint that enumerates which hostnames in a zone have an
    // AOP association (`listHostnameCertificates` lists certificates, which
    // carry no hostname), so there is provably no way to discover the
    // hostnames to read. Return [] rather than throwing.
    list: () => Effect.succeed<HostnameAssociationAttributes[]>([]),

    diff: Effect.fn(function* ({ olds, news }) {
      if (!isResolved(news)) return undefined;
      // zoneId is Input<string>; compare only once both sides are concrete.
      if (
        typeof olds.zoneId === "string" &&
        typeof news.zoneId === "string" &&
        olds.zoneId !== news.zoneId
      ) {
        return { action: "replace" } as const;
      }
      // The hostname is the association's identity in Cloudflare's bulk
      // upsert — changing it must void the old hostname's entry, so it is a
      // replacement.
      if (olds.hostname !== news.hostname) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ output, olds }) {
      const zoneId = output?.zoneId ?? (olds?.zoneId as string | undefined);
      const hostname = output?.hostname ?? olds?.hostname;
      if (!zoneId || !hostname) return undefined;
      const observed = yield* observeAssociation(zoneId, hostname);
      if (!observed) return undefined;
      const attrs = toAttributes(observed, zoneId, hostname);
      // Cold read (no prior output): an association for this hostname exists
      // but carries no ownership markers, so we cannot prove we created it —
      // brand it `Unowned` so the engine refuses to take it over unless
      // `adopt` is set.
      return output === undefined ? Unowned(attrs) : attrs;
    }),

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

      // 1. Observe — the hostname is the deterministic identity; a voided
      //    (`enabled: null`) or missing entry reads as absent.
      const observed = yield* observeAssociation(zoneId, hostname);

      // 2. Sync — the PUT is a true upsert; skip it when the observed entry
      //    already matches the desired certificate and enablement.
      if (observed && observed.certId === certId && observed.enabled === news.enabled) {
        return toAttributes(observed, zoneId, hostname);
      }
      const put = yield* originTls.putHostname({
        zoneId,
        config: [{ hostname, certId, enabled: news.enabled }],
      });
      const result = put.result.find((r) => r.hostname === hostname);

      // 3. Return — propagation is asynchronous (`pending_deployment` →
      //    `active`); we do not block on activation.
      return toAttributes(result ?? { certId, enabled: news.enabled }, zoneId, hostname);
    }),

    delete: Effect.fn(function* ({ output }) {
      const { zoneId, hostname } = output;
      // Observe first — voiding an already-voided / never-created hostname
      // is a no-op, and the PUT needs the certificate id currently pinned to
      // the association.
      const observed = yield* observeAssociation(zoneId, hostname);
      if (!observed) return;
      yield* originTls
        .putHostname({
          zoneId,
          // `enabled: null` voids the association; Cloudflare still requires
          // the pinned certificate id in the payload.
          config: [
            {
              hostname,
              certId: observed.certId ?? output.certId,
              enabled: null,
            },
          ],
        })
        .pipe(
          // Code 1415: the pinned certificate was already deleted out from
          // under the association, which Cloudflare rejects even for a void.
          // The association is inert without its certificate — treat as done.
          Effect.catchTag("InvalidHostnameConfig", () => Effect.void),
        );
    }),
  });

// Observe a hostname's association, mapping "never configured" (HTTP 404 /
// code 1553) and "voided" (`enabled: null`) to `undefined`.
const observeAssociation = (zoneId: string, hostname: string) =>
  originTls.getHostname({ zoneId, hostname }).pipe(
    Effect.map((assoc) =>
      assoc.enabled === null || assoc.enabled === undefined ? undefined : assoc,
    ),
    Effect.catchTag("HostnameAssociationNotFound", () => Effect.undefined),
  );

type AssociationShape = {
  certId?: string | null;
  enabled?: boolean | null;
  status?: string | null;
  certStatus?: string | null;
};

const toAttributes = (
  assoc: AssociationShape,
  zoneId: string,
  hostname: string,
): HostnameAssociationAttributes => ({
  zoneId,
  hostname,
  certId: assoc.certId!,
  enabled: assoc.enabled ?? false,
  status: assoc.status ?? undefined,
  certStatus: assoc.certStatus ?? undefined,
});