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

import * as originTls from "@distilled.cloud/cloudflare/origin-tls-client-auth";
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 * as Redacted from "effect/Redacted";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";
import { listAllZones } from "../Zone/lookup.ts";

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

/**
 * Deployment status of the certificate. Deploying and deleting are
 * asynchronous (`pending_deployment` → `active`, `pending_deletion` →
 * `deleted`), typically settling within minutes.
 */
export type HostnameCertificateStatus =
  | "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 HostnameCertificateProps = {
  /**
   * Zone the certificate is uploaded to. Cannot be changed after upload —
   * updating this property triggers a replacement.
   */
  zoneId: string;
  /**
   * The per-hostname client certificate in PEM format, presented by
   * Cloudflare to your origin for hostnames associated with it via
   * {@link HostnameAssociation}. Cannot be changed after
   * upload — updating this property triggers a replacement.
   */
  certificate: string;
  /**
   * The certificate's private key in PEM format. Cannot be changed after
   * upload — updating this property triggers a replacement.
   */
  privateKey: Redacted.Redacted<string>;
};

export type HostnameCertificateAttributes = {
  /** Unique identifier of the uploaded certificate. */
  certificateId: string;
  /** Zone the certificate is uploaded to. */
  zoneId: string;
  /** Deployment status of the certificate. */
  status: HostnameCertificateStatus | undefined;
  /** When the certificate expires. */
  expiresOn: string | undefined;
  /** The certificate authority that issued the certificate. */
  issuer: string | undefined;
  /** The serial number on the uploaded certificate. */
  serialNumber: string | undefined;
  /** The type of hash used for the certificate signature. */
  signature: string | undefined;
  /** When the certificate was uploaded to Cloudflare. */
  uploadedOn: string | undefined;
};

export type HostnameCertificate = Resource<
  TypeId,
  HostnameCertificateProps,
  HostnameCertificateAttributes,
  never,
  Providers
>;

/**
 * A per-hostname Authenticated Origin Pulls (AOP) client certificate
 * (`/zones/{zone_id}/origin_tls_client_auth/hostnames/certificates`).
 *
 * Uploads a client certificate that Cloudflare presents to your origin for
 * specific hostnames. Hostnames opt in by referencing the certificate from an
 * {@link HostnameAssociation}, which pins the certificate
 * and enables hostname-level AOP.
 *
 * Certificates are immutable: there is no update API, so changing any
 * property triggers a replacement. Deployment is asynchronous — the
 * certificate starts in `pending_deployment` and becomes `active` within a
 * few minutes; deletion likewise passes through `pending_deletion`.
 * ### Uploading a hostname certificate
 * **Example:** Hostname client certificate
 * ```typescript
 * const cert = yield* Cloudflare.OriginTlsClientAuth.HostnameCertificate("AopHostCert", {
 *   zoneId: zone.zoneId,
 *   certificate: clientCertPem,
 *   privateKey: yield* Config.Redacted("AOP_CLIENT_KEY"),
 * });
 * ```
 *
 * ### Enabling AOP for a hostname
 * **Example:** Upload the certificate and associate a hostname
 * ```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,
 * });
 * ```
 *
 * @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 HostnameCertificate = Resource<HostnameCertificate>(TypeId);

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

export const HostnameCertificateProvider = () =>
  Provider.succeed(HostnameCertificate, {
    stables: ["certificateId", "zoneId"],

    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // Per-hostname client certificates live inside a zone and are only
      // enumerable per-zone — fan out over every zone in the account.
      const zones = yield* listAllZones(accountId);
      const rows = yield* Effect.forEach(
        zones,
        (zone) =>
          originTls.listHostnameCertificates.pages({ zoneId: zone.id }).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((page) =>
                (page.result ?? [])
                  // Match `read`: tombstoned (deleted / pending_deletion)
                  // certificates no longer satisfy the desired state.
                  .filter((c) => isLive(c.status))
                  .map((c) => toAttributes(c, zone.id)),
              ),
            ),
            // Plan-gated / partial zones reject the route; skip them.
            Effect.catchTag("Forbidden", () => Effect.succeed([])),
          ),
        { concurrency: 10 },
      );
      return rows.flat();
    }),

    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;
      }
      // Compare the certificate only when the old value is known — an
      // Output-valued `certificate` doesn't survive a `creating`-state
      // round-trip (it deserializes as `undefined`).
      if (
        (olds.certificate !== undefined &&
          normalizePem(olds.certificate) !== normalizePem(news.certificate)) ||
        unwrap(olds.privateKey) !== unwrap(news.privateKey)
      ) {
        // There is no update API for hostname client certificates — every
        // change is a replacement.
        return { action: "replace" } as const;
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ output, olds }) {
      const zoneId = output?.zoneId ?? (olds?.zoneId as string | undefined);
      if (!zoneId) return undefined;
      if (output?.certificateId) {
        const observed = yield* observeById(zoneId, output.certificateId);
        if (observed) return toAttributes(observed, zoneId);
      }
      // Cold read — recover by listing and matching on the certificate PEM
      // content (the only identity available; hostname client certificates
      // have no name or tags). A content match IS the desired state, so
      // adoption is safe without an `Unowned` gate.
      if (typeof olds?.certificate === "string") {
        const match = yield* findByContent(zoneId, olds.certificate);
        if (match) return toAttributes(match, zoneId);
      }
      return undefined;
    }),

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

      // 1. Observe — the certificate id is the stable identifier; fall
      //    through a HostnameCertificateNotFound (or a pending/completed
      //    deletion) to the list+content match so we recover from
      //    out-of-band deletes and partial state persistence.
      let observed = output?.certificateId
        ? yield* observeById(zoneId, output.certificateId)
        : yield* findByContent(zoneId, news.certificate);

      // 2. Ensure — upload if missing. Cloudflare rejects uploading a PEM
      //    identical to an existing certificate (code 1406); tolerate the
      //    race (or an orphaned prior upload) by re-listing and adopting the
      //    certificate with identical PEM content. A destroy→deploy cycle
      //    also hits 1406 while the old certificate's tombstone is still
      //    `pending_deletion` (observed live: it settles to `deleted` within
      //    ~10 seconds, after which re-uploading the PEM resurrects it under
      //    the same id) — ride that window out with a bounded retry of the
      //    whole create-or-adopt step.
      if (!observed) {
        observed = yield* originTls
          .createHostnameCertificate({
            zoneId,
            certificate: news.certificate,
            privateKey: unwrap(news.privateKey),
          })
          .pipe(
            Effect.catchTag("CertificateAlreadyExists", (originalError) =>
              Effect.gen(function* () {
                const match = yield* findByContent(zoneId, news.certificate);
                if (!match) return yield* originalError;
                return match;
              }),
            ),
            Effect.retry({
              while: (e) => e._tag === "CertificateAlreadyExists",
              schedule: Schedule.spaced("5 seconds"),
              times: 10,
            }),
          );
      }

      // 3. Return — deployment is asynchronous (`pending_deployment` →
      //    `active`); we do not block on activation.
      return toAttributes(observed, zoneId);
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* originTls
        .deleteHostnameCertificate({
          zoneId: output.zoneId,
          certificateId: output.certificateId,
        })
        .pipe(
          // The certificate cannot be deleted while a hostname association
          // still references it (code 1433) or while its initial deployment
          // is still propagating (code 1434). Both clear within seconds once
          // the association is voided / the deployment lands — ride them out
          // with a bounded retry.
          Effect.retry({
            while: (e) =>
              e._tag === "HostnameCertificateInUse" || e._tag === "CertificatePendingDeployment",
            schedule: Schedule.spaced("5 seconds"),
            times: 10,
          }),
          // Already gone (404 / code 1551) or already on its way out
          // (code 1414 pending deletion) — delete is idempotent.
          Effect.catchTag(
            ["HostnameCertificateNotFound", "CertificatePendingDeletion"],
            () => Effect.void,
          ),
        );
    }),
  });

/** A certificate that is being or has been deleted no longer satisfies the desired state. */
const isLive = (status: string | null | undefined): boolean =>
  status !== "deleted" && status !== "pending_deletion";

// Observe a certificate by id, treating "not found" and "deleted /
// pending_deletion" (Cloudflare keeps tombstones readable by id) as missing.
const observeById = (zoneId: string, certificateId: string) =>
  originTls.getHostnameCertificate({ zoneId, certificateId }).pipe(
    Effect.map((cert) => (isLive(cert.status) ? cert : undefined)),
    Effect.catchTag("HostnameCertificateNotFound", () => Effect.undefined),
  );

// Locate a live certificate by exact PEM content. Tombstoned certificates
// are excluded so a destroy→deploy cycle re-creates (resurrects) instead of
// adopting a certificate that is on its way out.
const findByContent = (zoneId: string, certificate: string) =>
  Effect.gen(function* () {
    const list = yield* originTls.listHostnameCertificates({ zoneId });
    return list.result.find(
      (c) => isLive(c.status) && normalizePem(c.certificate ?? "") === normalizePem(certificate),
    );
  });

const normalizePem = (pem: string): string => pem.trim();

const unwrap = (value: Redacted.Redacted<string> | string): string =>
  Redacted.isRedacted(value) ? Redacted.value(value) : value;

type CertificateShape = {
  id?: string | null;
  status?: string | null;
  expiresOn?: string | null;
  issuer?: string | null;
  serialNumber?: string | null;
  signature?: string | null;
  uploadedOn?: string | null;
};

const toAttributes = (cert: CertificateShape, zoneId: string): HostnameCertificateAttributes => ({
  certificateId: cert.id!,
  zoneId,
  status: cert.status ?? undefined,
  expiresOn: cert.expiresOn ?? undefined,
  issuer: cert.issuer ?? undefined,
  serialNumber: cert.serialNumber ?? undefined,
  signature: cert.signature ?? undefined,
  uploadedOn: cert.uploadedOn ?? undefined,
});