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

import * as clientCertificates from "@distilled.cloud/cloudflare/client-certificates";
import { Unowned } from "alchemy/AdoptPolicy";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import * as Predicate from "effect/Predicate";
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.ClientCertificate.ClientCertificate" as const;
type TypeId = typeof TypeId;

/**
 * Lifecycle status of a client certificate. `pending_reactivation` and
 * `pending_revocation` are in-progress asynchronous transitions.
 */
export type Status =
  | "active"
  | "pending_reactivation"
  | "pending_revocation"
  | "revoked"
  // Keep the union open so new Cloudflare statuses aren't blocked by stale
  // types.
  | (string & {});

export interface Props {
  /**
   * Zone the client certificate is issued under. Client certificates are a
   * zone-level API Shield feature.
   *
   * Immutable — moving a certificate between zones triggers a replacement.
   */
  zoneId: string;
  /**
   * The Certificate Signing Request (CSR) in PEM format. Must be
   * newline-encoded. Cloudflare's Managed CA signs this CSR and returns the
   * client certificate.
   *
   * Immutable — the API has no way to re-sign a certificate, so changing the
   * CSR triggers a replacement. Plain `string` (not `string`) so it is
   * statically comparable inside `diff`.
   */
  csr: string;
  /**
   * The number of days the client certificate will be valid after the
   * `issuedOn` date.
   *
   * Immutable — changing the validity triggers a replacement.
   */
  validityDays: number;
}

export interface Attributes {
  /** Cloudflare-assigned identifier of the client certificate. */
  clientCertificateId: string;
  /** Zone the certificate was issued under. */
  zoneId: string;
  /** The signed client certificate in PEM format. */
  certificate: string;
  /** The CSR the certificate was issued from, as echoed by Cloudflare. */
  csr: string;
  /** Common Name parsed from the CSR. */
  commonName: string | undefined;
  /** Country parsed from the CSR. */
  country: string | undefined;
  /** State parsed from the CSR. */
  state: string | undefined;
  /** Location parsed from the CSR. */
  location: string | undefined;
  /** Organization parsed from the CSR. */
  organization: string | undefined;
  /** Organizational Unit parsed from the CSR. */
  organizationalUnit: string | undefined;
  /** ISO8601 date the certificate expires. */
  expiresOn: string | undefined;
  /** ISO8601 date the certificate was issued by the Managed CA. */
  issuedOn: string | undefined;
  /** SHA-256 fingerprint of the certificate. */
  fingerprintSha256: string | undefined;
  /** The serial number on the issued certificate. */
  serialNumber: string | undefined;
  /** The type of hash used for the certificate signature. */
  signature: string | undefined;
  /** Subject Key Identifier. */
  ski: string | undefined;
  /** Current lifecycle status of the certificate. */
  status: Status;
  /** The number of days the certificate is valid after `issuedOn`. */
  validityDays: number;
  /** Identifier of the Certificate Authority that issued the certificate. */
  certificateAuthorityId: string | undefined;
  /** Name of the Certificate Authority that issued the certificate. */
  certificateAuthorityName: string | undefined;
}

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

/**
 * A zone-level API Shield mTLS client certificate signed by the Cloudflare
 * Managed CA.
 *
 * You submit a Certificate Signing Request (CSR) plus a validity period;
 * Cloudflare signs it and returns the client certificate PEM, which clients
 * then present when connecting to API Shield mTLS-protected hostnames.
 *
 * Client certificates are immutable: there is no API to change the CSR or
 * validity, so any prop change triggers a replacement. Deleting the resource
 * revokes the certificate — revoked certificates remain listed on the zone in
 * `revoked` status but are treated as deleted by this resource.
 *
 * Safety: client certificates carry no ownership markers. When there is no
 * prior state, `read` scans the zone for a non-revoked certificate issued
 * from the same CSR and reports it as `Unowned`, so the engine refuses to
 * take it over unless `--adopt` (or `adopt(true)`) is set.
 * ### Issuing a client certificate
 * **Example:** Sign a CSR with the Cloudflare Managed CA
 * ```typescript
 * const cert = yield* Cloudflare.ClientCertificate.ClientCertificate("ApiClient", {
 *   zoneId: zone.zoneId,
 *   csr: clientCsrPem,
 *   validityDays: 365,
 * });
 * // cert.certificate is the signed client certificate PEM
 * ```
 *
 * **Example:** Read the CSR from disk
 * ```typescript
 * const fs = yield* FileSystem.FileSystem;
 * const csr = yield* fs.readFileString("certs/client.csr");
 *
 * const cert = yield* Cloudflare.ClientCertificate.ClientCertificate("ApiClient", {
 *   zoneId: zone.zoneId,
 *   csr,
 *   validityDays: 90,
 * });
 * ```
 *
 * ### Rotation
 * **Example:** Rotate by changing the CSR
 * ```typescript
 * // csr and validityDays are immutable — changing either replaces the
 * // certificate: a new one is signed and the old one is revoked.
 * const cert = yield* Cloudflare.ClientCertificate.ClientCertificate("ApiClient", {
 *   zoneId: zone.zoneId,
 *   csr: rotatedCsrPem,
 *   validityDays: 365,
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/ssl/client-certificates/
 *
 * @resource
 * @product Client Certificates
 * @category SSL/TLS & Certificates
 */
export const ClientCertificate = Resource<ClientCertificate>(TypeId, {
  aliases: ["Cloudflare.ClientCertificate"],
});

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

export const ClientCertificateProvider = () =>
  Provider.succeed(ClientCertificate, {
    // Everything Cloudflare returns at issuance is fixed for the lifetime of
    // the certificate — only `status` changes (revocation/reactivation).
    stables: [
      "clientCertificateId",
      "zoneId",
      "certificate",
      "csr",
      "commonName",
      "country",
      "state",
      "location",
      "organization",
      "organizationalUnit",
      "expiresOn",
      "issuedOn",
      "fingerprintSha256",
      "serialNumber",
      "signature",
      "ski",
      "validityDays",
      "certificateAuthorityId",
      "certificateAuthorityName",
    ],

    // Client certificates are a zone-scoped API Shield feature. Fan out over
    // every zone in the account, exhaustively paginate each zone's
    // certificates, and hydrate each into the same Attributes shape `read`
    // produces. Revoked certificates stay listed forever but revocation is the
    // delete semantic, so they are filtered out. Zones where API Shield is not
    // entitled reject with the typed `Forbidden` error — skip them.
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const zones = yield* listAllZones(accountId);
      const rows = yield* Effect.forEach(
        zones,
        (zone) =>
          clientCertificates.listClientCertificates.pages({ zoneId: zone.id, status: "all" }).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((page) =>
                (page.result ?? [])
                  .filter((cert) => !isGone(cert.status))
                  .map((cert): Attributes => toAttributes(cert, zone.id)),
              ),
            ),
            Effect.catchTag("Forbidden", () => Effect.succeed([])),
          ),
        { concurrency: 10 },
      );
      return rows.flat();
    }),

    diff: Effect.fn(function* ({ olds = {}, news }) {
      const o = olds as Props;
      const n = news as Props;
      // No prior props to compare against — let the engine decide.
      if (o.csr === undefined) return undefined;
      // The API has no update for csr/validityDays — every change replaces.
      if (normalizePem(o.csr) !== normalizePem(n.csr)) {
        return { action: "replace" } as const;
      }
      if (o.validityDays !== n.validityDays) {
        return { action: "replace" } as const;
      }
      // zoneId is Input<string>; compare only once both are concrete.
      if (typeof o.zoneId === "string" && typeof n.zoneId === "string" && o.zoneId !== n.zoneId) {
        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. A revoked (or
      // asynchronously revoking) certificate stays listed on the zone forever
      // — revocation is the delete semantic, so report it as gone.
      if (output?.clientCertificateId) {
        const observed = yield* getCertificate(zoneId, output.clientCertificateId);
        if (observed && !isGone(observed.status)) {
          return toAttributes(observed, zoneId);
        }
        return undefined;
      }

      // Adoption path: a non-revoked certificate issued from the same CSR
      // (with the same validity) may already exist on the zone. Client
      // certificates carry no ownership markers, so we cannot prove we
      // created it — brand it `Unowned` so the engine refuses takeover
      // unless `adopt` is set.
      if (olds?.csr !== undefined && olds.validityDays !== undefined) {
        const observed = yield* findByCsr(zoneId, olds.csr, olds.validityDays);
        if (observed) return Unowned(toAttributes(observed, 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 cached on `output` is a hint, not a
      //    guarantee. A missing or revoked certificate (revocation is the
      //    delete semantic; the certificate cannot serve mTLS) falls
      //    through to the CSR scan and then to create.
      let observed = output?.clientCertificateId
        ? yield* getCertificate(zoneId, output.clientCertificateId)
        : undefined;
      if (observed && isGone(observed.status)) observed = undefined;

      // 2. Fall back to scanning the zone for a non-revoked certificate
      //    issued from the same CSR with the same validity. Matching on
      //    BOTH props matters: a replacement keeps one of them while
      //    changing the other, so the old certificate never matches the new
      //    desired state and cannot be mistaken for it. Ownership has
      //    already been verified upstream — `read` reports existing
      //    certificates as `Unowned` and the engine gates takeover behind
      //    the adopt policy before reconcile ever runs.
      if (!observed) {
        observed = yield* findByCsr(zoneId, news.csr, news.validityDays);
      }

      // 3. Ensure — sign the CSR when missing. Cloudflare happily signs the
      //    same CSR multiple times (each issuance is a distinct
      //    certificate), so there is no AlreadyExists race to tolerate.
      if (!observed) {
        observed = yield* clientCertificates.createClientCertificate({
          zoneId,
          csr: news.csr,
          validityDays: news.validityDays,
        });
      }

      // 4. There is no sync step: csr/validityDays are immutable and every
      //    other attribute is derived at issuance.
      return toAttributes(observed, zoneId);
    }),

    delete: Effect.fn(function* ({ output }) {
      // DELETE revokes the certificate. Revoked certificates remain listed
      // on the zone — observe first and treat already-revoked (or already
      // revoking) as done so delete is idempotent.
      const observed = yield* getCertificate(output.zoneId, output.clientCertificateId);
      if (!observed || isGone(observed.status)) {
        return;
      }
      yield* clientCertificates
        .deleteClientCertificate({
          zoneId: output.zoneId,
          clientCertificateId: output.clientCertificateId,
        })
        .pipe(
          // Races with an out-of-band revoke/delete are convergence, not
          // failure.
          Effect.catchTags({
            ClientCertificateNotFound: () => Effect.void,
            ClientCertificateAlreadyRevoked: () => Effect.void,
          }),
        );
    }),
  });

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

type ObservedCertificate = clientCertificates.GetClientCertificateResponse;

/**
 * Read a certificate by id, mapping "gone" (`ClientCertificateNotFound`,
 * Cloudflare error code 1415 `Invalid Certificate ID in request`) to
 * `undefined`.
 */
const getCertificate = (zoneId: string, clientCertificateId: string) =>
  clientCertificates.getClientCertificate({ zoneId, clientCertificateId }).pipe(
    Effect.map((cert): ObservedCertificate | undefined => cert),
    Effect.catchTag("ClientCertificateNotFound", () => Effect.undefined),
  );

/**
 * Find a non-revoked certificate issued from the given CSR with the given
 * validity. Cloudflare echoes the CSR back on every certificate, so an exact
 * (whitespace-normalized) CSR + validity match is the only identity available
 * for cold reads — certificates have no names or tags. Both props are matched
 * so a replacement (which changes at least one of them) can never mistake the
 * outgoing certificate for the desired one.
 */
const findByCsr = (zoneId: string, csr: string, validityDays: number) =>
  clientCertificates.listClientCertificates.items({ zoneId, status: "all" }).pipe(
    Stream.filter(
      (cert) =>
        !isGone(cert.status) &&
        cert.validityDays === validityDays &&
        typeof cert.csr === "string" &&
        normalizePem(cert.csr) === normalizePem(csr),
    ),
    Stream.runHead,
    Effect.map(Option.getOrUndefined),
    Effect.map((cert): ObservedCertificate | undefined => cert),
  );

/**
 * A certificate is "gone" once it is `revoked` or asynchronously transitioning
 * to it (`pending_revocation`). Revocation is the delete semantic, and a
 * revoking certificate can no longer serve mTLS — so it must never be adopted,
 * reused, listed, or treated as live. Without this, a prior run's async revoke
 * leaves a `pending_revocation` certificate that a fresh deploy would otherwise
 * mistake for an existing live certificate matching the CSR.
 */
const isGone = (status: string | null | undefined): boolean =>
  status === "revoked" || status === "pending_revocation";

/** Normalize PEM content for comparison (CRLF + trailing-newline noise). */
const normalizePem = (pem: string | undefined): string | undefined =>
  pem?.replace(/\r\n/g, "\n").trim();

const toAttributes = (cert: ObservedCertificate, zoneId: string): Attributes => ({
  clientCertificateId: cert.id!,
  zoneId,
  certificate: cert.certificate ?? "",
  csr: cert.csr ?? "",
  commonName: cert.commonName ?? undefined,
  country: cert.country ?? undefined,
  state: cert.state ?? undefined,
  location: cert.location ?? undefined,
  organization: cert.organization ?? undefined,
  organizationalUnit: cert.organizationalUnit ?? undefined,
  expiresOn: cert.expiresOn ?? undefined,
  issuedOn: cert.issuedOn ?? undefined,
  fingerprintSha256: cert.fingerprintSha256 ?? undefined,
  serialNumber: cert.serialNumber ?? undefined,
  signature: cert.signature ?? undefined,
  ski: cert.ski ?? undefined,
  status: (cert.status ?? "active") as Status,
  validityDays: cert.validityDays ?? 0,
  certificateAuthorityId: cert.certificateAuthority?.id ?? undefined,
  certificateAuthorityName: cert.certificateAuthority?.name ?? undefined,
});