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

import crypto from "node:crypto";
import * as customCertificates from "@distilled.cloud/cloudflare/custom-certificates";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Predicate from "effect/Predicate";
import * as Redacted from "effect/Redacted";
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.CustomCertificate.CustomCertificate" as const;
type TypeId = typeof TypeId;

/**
 * How Cloudflare builds the certificate chain served to clients.
 *
 * A `ubiquitous` bundle has the highest probability of being verified
 * everywhere, even by clients using outdated or unusual trust stores. An
 * `optimal` bundle uses the shortest chain and newest intermediates. `force`
 * serves exactly the certificate you uploaded.
 */
export type BundleMethod = "ubiquitous" | "optimal" | "force";

/**
 * SNI support of the uploaded certificate. `legacy_custom` enables support
 * for legacy clients which do not include SNI in the TLS handshake (requires
 * dedicated IPs); `sni_custom` is the recommended modern option.
 */
export type Type = "legacy_custom" | "sni_custom";

/**
 * Lifecycle status of a custom certificate. Uploads are asynchronous —
 * a certificate transitions `initializing` → `active`.
 */
export type Status =
  | "active"
  | "expired"
  | "deleted"
  | "pending"
  | "initializing"
  // Keep the union open so new Cloudflare statuses aren't blocked by stale
  // types.
  | (string & {});

/**
 * Geo Key Manager region restriction: where the certificate's private key
 * may be held locally for optimal TLS performance.
 */
export interface GeoRestrictions {
  /**
   * Region label: `us`, `eu`, or `highest_security`.
   */
  label: "us" | "eu" | "highest_security";
}

export interface Props {
  /**
   * Zone the certificate is uploaded to. Custom certificates are a
   * zone-level feature (Business and Enterprise plans only).
   *
   * Immutable — moving a certificate between zones triggers a replacement.
   */
  zoneId: string;
  /**
   * The zone's SSL certificate — the leaf certificate plus any
   * intermediates, in PEM format. Plain `string` (not `string`) so
   * its content hash is statically computable.
   *
   * Mutable — Cloudflare PATCHes a new certificate onto the same record,
   * keeping the certificate id stable across rotations.
   */
  certificate: string;
  /**
   * The certificate's private key in PEM format. Not required when
   * `customCsrId` is provided, in which case the private key is retrieved
   * from the CSR record held by Cloudflare.
   *
   * Write-only — Cloudflare never echoes the key back; a content hash of
   * the certificate/key pair is persisted in the attributes for diffing.
   */
  privateKey?: Redacted.Redacted<string>;
  /**
   * The identifier of a Custom CSR held by Cloudflare to source the private
   * key from, as an alternative to uploading `privateKey`.
   */
  customCsrId?: string;
  /**
   * How Cloudflare builds the certificate chain served to clients.
   * @default "ubiquitous"
   */
  bundleMethod?: BundleMethod;
  /**
   * SNI support: `sni_custom` (recommended) or `legacy_custom` (supports
   * non-SNI clients; requires dedicated IPs).
   *
   * Immutable — the PATCH endpoint does not accept `type`, so changing it
   * triggers a replacement.
   * @default "legacy_custom"
   */
  type?: Type;
  /**
   * Geo Key Manager region restriction for the private key. Mutually
   * exclusive with `policy`.
   */
  geoRestrictions?: GeoRestrictions;
  /**
   * Geo Key Manager policy expression (e.g.
   * `(country: US) or (region: EU)`) that determines where the private key
   * is held. Mutually exclusive with `geoRestrictions`. Cloudflare echoes
   * this back as the `policyRestrictions` attribute.
   */
  policy?: string;
  /**
   * The environment to deploy the certificate to. Staging deploys are an
   * Enterprise feature. Write-only — not echoed back by the API.
   * @default "production"
   */
  deploy?: "staging" | "production";
  /**
   * The order/priority in which the certificate is used in a request. A
   * higher priority breaks ties across overlapping `legacy_custom`
   * certificates. Synced via the prioritize endpoint when it differs from
   * the observed value.
   * @default API-assigned
   */
  priority?: number;
}

export interface Attributes {
  /** Cloudflare-assigned identifier of the custom certificate. Stable across in-place certificate rotations. */
  certificateId: string;
  /** Zone the certificate belongs to. */
  zoneId: string;
  /** Hostnames covered by the certificate. */
  hosts: string[];
  /** The certificate authority that issued the certificate. */
  issuer: string | undefined;
  /** The type of hash used for the certificate signature. */
  signature: string | undefined;
  /** ISO8601 date the certificate expires. */
  expiresOn: string | undefined;
  /** ISO8601 date the certificate was uploaded to Cloudflare. */
  uploadedOn: string | undefined;
  /** ISO8601 date the certificate was last modified. */
  modifiedOn: string | undefined;
  /** How Cloudflare builds the certificate chain served to clients. */
  bundleMethod: BundleMethod | undefined;
  /** SNI support the certificate was uploaded with. Not echoed by the API — persisted from the input props. */
  type: Type;
  /** The order/priority in which the certificate is used in a request. */
  priority: number | undefined;
  /** Lifecycle status of the certificate (`initializing` → `active`). */
  status: Status | undefined;
  /** Geo Key Manager policy expression, as echoed by the API for the `policy` prop. */
  policyRestrictions: string | undefined;
  /** Geo Key Manager region restriction, if set. */
  geoRestrictions: GeoRestrictions | undefined;
  /**
   * SHA-256 hash of the uploaded certificate/private key pair. Cloudflare
   * never echoes the PEM contents back, so this hash is the diff baseline
   * for deciding whether to re-push the certificate (a documented exception
   * to "observation > assumption").
   */
  contentHash: string;
}

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

/**
 * A Cloudflare custom (BYO) edge certificate — upload your own SSL
 * certificate and private key to be served at Cloudflare's edge for a zone.
 *
 * Custom certificates are a **Business / Enterprise** feature; on lower
 * plans every API call fails with the typed `PlanLevelNotAllowed` error
 * (Cloudflare error code 1011).
 *
 * The certificate id is stable across in-place rotations: PATCHing a new
 * `certificate`/`privateKey` pair keeps the same id. Cloudflare never echoes
 * the PEM contents back, so a SHA-256 content hash of the pair is persisted
 * in the attributes and used as the rotation diff baseline. Only `zoneId`
 * and `type` force a replacement.
 * ### Uploading a certificate
 * **Example:** Basic SNI certificate
 * ```typescript
 * const cert = yield* Cloudflare.CustomCertificate.CustomCertificate("EdgeCert", {
 *   zoneId: zone.zoneId,
 *   certificate: certPem,
 *   privateKey: Redacted.make(keyPem),
 *   type: "sni_custom",
 * });
 * ```
 *
 * **Example:** Optimal bundle with a Geo Key Manager region
 * ```typescript
 * yield* Cloudflare.CustomCertificate.CustomCertificate("EuCert", {
 *   zoneId: zone.zoneId,
 *   certificate: certPem,
 *   privateKey: Redacted.make(keyPem),
 *   type: "sni_custom",
 *   bundleMethod: "optimal",
 *   geoRestrictions: { label: "eu" },
 * });
 * ```
 *
 * ### Rotating the certificate
 * **Example:** Rotate in place
 * ```typescript
 * // Changing `certificate`/`privateKey` PATCHes the same certificate id —
 * // no replacement, no coverage gap.
 * yield* Cloudflare.CustomCertificate.CustomCertificate("EdgeCert", {
 *   zoneId: zone.zoneId,
 *   certificate: renewedCertPem,
 *   privateKey: Redacted.make(renewedKeyPem),
 *   type: "sni_custom",
 * });
 * ```
 *
 * ### Prioritizing overlapping certificates
 * **Example:** Explicit priority
 * ```typescript
 * // Higher priority breaks ties across overlapping legacy_custom certs.
 * yield* Cloudflare.CustomCertificate.CustomCertificate("PrimaryCert", {
 *   zoneId: zone.zoneId,
 *   certificate: certPem,
 *   privateKey: Redacted.make(keyPem),
 *   priority: 1,
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/ssl/edge-certificates/custom-certificates/
 *
 * @resource
 * @product Custom Certificates
 * @category SSL/TLS & Certificates
 */
export const CustomCertificate = Resource<CustomCertificate>(TypeId, {
  aliases: ["Cloudflare.CustomCertificate"],
});

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

export const CustomCertificateProvider = () =>
  Provider.succeed(CustomCertificate, {
    stables: ["certificateId", "zoneId", "type", "uploadedOn"],

    // Zone-scoped collection: fan out over every zone and exhaustively
    // paginate that zone's custom certificates. The PEM contents and the
    // uploaded `type` are write-only (never echoed back), so — exactly like
    // `read`'s cold adoption path — the unknowable `type`/`contentHash`
    // default to `legacy_custom`/`""`. Plan-gated zones reject the route with
    // the typed `PlanLevelNotAllowed` (custom certs are Business/Enterprise),
    // zones that can't host custom certs (partial/pending/deleted between
    // list and read) reject with `ZoneNotFound` ("Cannot find a valid zone"),
    // and freshly-scoped tokens may blip `Forbidden`; all three skip the zone
    // so enumeration still returns every zone it can read.
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const zones = yield* listAllZones(accountId);
      const rows = yield* Effect.forEach(
        zones,
        (zone) =>
          customCertificates.listCustomCertificates.pages({ zoneId: zone.id }).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((page) =>
                (page.result ?? []).map((cert): Attributes =>
                  toAttributes(cert, {
                    type: "legacy_custom",
                    contentHash: "",
                  }),
                ),
              ),
            ),
            Effect.catchTag(["PlanLevelNotAllowed", "ZoneNotFound", "Forbidden"], () =>
              Effect.succeed([] as Attributes[]),
            ),
          ),
        { concurrency: 10 },
      );
      return rows.flat();
    }),

    diff: Effect.fn(function* ({ olds, news, output }) {
      if (!isResolved(news)) return undefined;
      // Zone move replaces. zoneId is Input<string>; compare only once
      // both sides are concrete.
      const oldZone =
        output?.zoneId ??
        (olds !== undefined && isResolved(olds) ? (olds.zoneId as string | undefined) : undefined);
      if (
        typeof oldZone === "string" &&
        typeof news.zoneId === "string" &&
        oldZone !== news.zoneId
      ) {
        return { action: "replace" } as const;
      }
      // `type` is create-only (the PATCH body does not accept it).
      const oldType =
        output?.type ??
        (olds !== undefined && isResolved(olds) ? olds.type : undefined) ??
        "legacy_custom";
      if ((news.type ?? "legacy_custom") !== oldType) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ output, olds }) {
      const zoneId = output?.zoneId ?? (olds?.zoneId as string | undefined);
      if (zoneId === undefined) return undefined;

      // Owned path: refresh by our persisted certificate id.
      if (output?.certificateId) {
        const observed = yield* getCertificate(zoneId, output.certificateId);
        return observed
          ? toAttributes(observed, {
              type: output.type,
              contentHash: output.contentHash,
            })
          : undefined;
      }

      // Cold path: state was lost. Custom certificates carry no ownership
      // markers and no name, so identify the desired certificate by its
      // parsed expiry timestamp (an upload of the same PEM always yields
      // the same `expires_on`) and report it as `Unowned` so the engine
      // gates takeover behind the adopt policy.
      if (olds?.certificate === undefined) return undefined;
      const parsed = yield* parseCertificate(olds.certificate);
      const observed = yield* findByExpiry(zoneId, parsed.expiresAtMs);
      if (observed) {
        return Unowned(
          toAttributes(observed, {
            type: olds.type ?? "legacy_custom",
            // The live cert/key contents are unknowable — force one
            // convergence PATCH after adoption.
            contentHash: "",
          }),
        );
      }
      return undefined;
    }),

    reconcile: Effect.fn(function* ({ news, output }) {
      // Inputs have been resolved to concrete strings by Plan.
      const zoneId = news.zoneId as string;
      const customCsrId = news.customCsrId as string | undefined;
      const type = news.type ?? output?.type ?? "legacy_custom";
      const desiredHash = yield* hashContent(news);

      // 1. Observe — the certificate id cached on `output` is a hint, not
      //    a guarantee: a missing certificate falls through to create.
      let observed = output?.certificateId
        ? yield* getCertificate(zoneId, output.certificateId)
        : undefined;

      // 2. Ensure — upload when missing. Certificates have no uniqueness
      //    constraint on Cloudflare's side, so there is no AlreadyExists
      //    race to tolerate.
      if (!observed) {
        observed = yield* customCertificates.createCustomCertificate({
          zoneId,
          certificate: news.certificate,
          privateKey: news.privateKey ? Redacted.value(news.privateKey) : undefined,
          customCsrId,
          bundleMethod: news.bundleMethod,
          type: news.type,
          geoRestrictions: news.geoRestrictions,
          policy: news.policy,
          deploy: news.deploy,
        });
        // The freshly uploaded contents are the desired contents.
        observed = yield* syncPriority(zoneId, observed, news.priority);
        return toAttributes(observed, { type, contentHash: desiredHash });
      }

      // 3. Sync — diff observed cloud state against desired. The PEM
      //    contents are write-only, so the persisted content hash is the
      //    baseline for the certificate/key pair; everything else diffs
      //    against the observed response.
      const certDirty = output?.contentHash !== desiredHash;
      const bundleDirty =
        news.bundleMethod !== undefined && observed.bundleMethod !== news.bundleMethod;
      const geoDirty =
        news.geoRestrictions !== undefined &&
        observed.geoRestrictions?.label !== news.geoRestrictions.label;
      const policyDirty =
        news.policy !== undefined && (observed.policyRestrictions ?? undefined) !== news.policy;

      if (certDirty || bundleDirty || geoDirty || policyDirty) {
        observed = yield* customCertificates.patchCustomCertificate({
          zoneId,
          customCertificateId: observed.id,
          ...(certDirty
            ? {
                certificate: news.certificate,
                privateKey: news.privateKey ? Redacted.value(news.privateKey) : undefined,
                customCsrId,
                deploy: news.deploy,
              }
            : {}),
          ...(bundleDirty ? { bundleMethod: news.bundleMethod } : {}),
          ...(geoDirty ? { geoRestrictions: news.geoRestrictions } : {}),
          ...(policyDirty ? { policy: news.policy } : {}),
        });
      }

      observed = yield* syncPriority(zoneId, observed, news.priority);
      return toAttributes(observed, { type, contentHash: desiredHash });
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* customCertificates
        .deleteCustomCertificate({
          zoneId: output.zoneId,
          customCertificateId: output.certificateId,
        })
        .pipe(Effect.catchTag("CustomCertificateNotFound", () => Effect.void));
    }),
  });

// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------

type ObservedCertificate = customCertificates.GetCustomCertificateResponse;

/**
 * Read a certificate by id, mapping "gone" (`CustomCertificateNotFound`,
 * HTTP 404) to `undefined`.
 */
const getCertificate = (zoneId: string, customCertificateId: string) =>
  customCertificates.getCustomCertificate({ zoneId, customCertificateId }).pipe(
    Effect.map((cert): ObservedCertificate | undefined => cert),
    Effect.catchTag("CustomCertificateNotFound", () => Effect.undefined),
  );

/**
 * Find a certificate in the zone whose `expires_on` matches the desired
 * PEM's parsed expiry. Uploading the same certificate always produces the
 * same expiry, making it the best identity available (the API neither
 * echoes the PEM nor exposes the serial number). If several match, pick the
 * oldest upload for determinism.
 */
const findByExpiry = (zoneId: string, expiresAtMs: number) =>
  customCertificates.listCustomCertificates.items({ zoneId }).pipe(
    Stream.runCollect,
    Effect.map((chunk) =>
      Array.from(chunk)
        .filter((cert) => cert.expiresOn != null && Date.parse(cert.expiresOn) === expiresAtMs)
        .sort((a, b) => (a.uploadedOn ?? "").localeCompare(b.uploadedOn ?? ""))
        .at(0),
    ),
  );

/**
 * Parse the leaf certificate of a PEM bundle. Sync CPU-only Node API,
 * wrapped in `Effect.try` so a malformed PEM surfaces as a typed failure
 * instead of a thrown exception.
 */
class CertificateParseError extends Data.TaggedError("CertificateParseError")<{
  message: string;
  cause?: unknown;
}> {}

const parseCertificate = (pem: string) =>
  Effect.try({
    try: () => {
      const x509 = new crypto.X509Certificate(pem);
      return { expiresAtMs: Date.parse(x509.validTo) };
    },
    catch: (cause) =>
      new CertificateParseError({
        message: `failed to parse certificate PEM: ${cause instanceof Error ? cause.message : String(cause)}`,
        cause,
      }),
  });

/**
 * SHA-256 over the write-only inputs (certificate, private key, CSR id).
 * Persisted in the attributes as the rotation diff baseline because the API
 * never returns the PEM contents.
 */
const hashContent = (news: Props) =>
  Effect.sync(() =>
    crypto
      .createHash("sha256")
      .update(news.certificate)
      .update("\n")
      .update(news.privateKey ? Redacted.value(news.privateKey) : "")
      .update("\n")
      .update((news.customCsrId as string | undefined) ?? "")
      .digest("hex"),
  );

/**
 * Converge the certificate's priority via the prioritize endpoint when an
 * explicit `priority` is desired and differs from the observed value.
 */
const syncPriority = (
  zoneId: string,
  observed: ObservedCertificate,
  priority: number | undefined,
) =>
  Effect.gen(function* () {
    if (priority === undefined || observed.priority === priority) {
      return observed;
    }
    yield* customCertificates.putPrioritize({
      zoneId,
      certificates: [{ id: observed.id, priority }],
    });
    // Re-observe so the returned attributes reflect the final state.
    const fresh = yield* getCertificate(zoneId, observed.id);
    return fresh ?? observed;
  });

const toAttributes = (
  cert: ObservedCertificate,
  meta: { type: Type; contentHash: string },
): Attributes => ({
  certificateId: cert.id,
  zoneId: cert.zoneId,
  hosts: [...(cert.hosts ?? [])],
  issuer: cert.issuer ?? undefined,
  signature: cert.signature ?? undefined,
  expiresOn: cert.expiresOn ?? undefined,
  uploadedOn: cert.uploadedOn ?? undefined,
  modifiedOn: cert.modifiedOn ?? undefined,
  bundleMethod: (cert.bundleMethod as BundleMethod | null | undefined) ?? undefined,
  type: meta.type,
  priority: cert.priority ?? undefined,
  status: cert.status ?? undefined,
  policyRestrictions: cert.policyRestrictions ?? undefined,
  geoRestrictions: cert.geoRestrictions?.label
    ? { label: cert.geoRestrictions.label as "us" | "eu" | "highest_security" }
    : undefined,
  contentHash: meta.contentHash,
});