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

import * as keylessCertificates from "@distilled.cloud/cloudflare/keyless-certificates";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
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 Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";
import { listAllZones } from "../Zone/lookup.ts";

const TypeId = "Cloudflare.KeylessCertificate.KeylessCertificate" as const;
type TypeId = typeof TypeId;

/**
 * How the certificate chain is bundled when the certificate is served.
 * Create-only — Cloudflare has no API to change the bundle method after
 * upload, so changing it triggers a replacement.
 */
export type BundleMethod = "ubiquitous" | "optimal" | "force";

/**
 * Lifecycle status of a Keyless SSL configuration.
 */
export type Status =
  | "active"
  | "deleted"
  // Keep the union open so new Cloudflare statuses aren't blocked by stale
  // types.
  | (string & {});

/**
 * Configuration for reaching the key server through a Cloudflare Tunnel
 * instead of over the public internet.
 */
export interface Tunnel {
  /**
   * Private IP of the key server inside the tunnel's virtual network.
   */
  privateIp: string;
  /**
   * Identifier of the Cloudflare Tunnel virtual network the key server is
   * reachable through (e.g. `VirtualNetwork.vnetId`).
   */
  vnetId: string;
}

export interface Props {
  /**
   * Zone the Keyless SSL certificate is uploaded to. Keyless SSL is a
   * zone-level Enterprise feature.
   *
   * Immutable — moving a Keyless SSL configuration between zones triggers a
   * replacement.
   */
  zoneId: string;
  /**
   * The zone's SSL certificate (or certificate and intermediates) in PEM
   * format. The private key never leaves your key server.
   *
   * Immutable — the PATCH API has no certificate field, so changing the
   * certificate triggers a replacement. Plain `string` (not `string`)
   * so it is statically comparable inside `diff`.
   */
  certificate: string;
  /**
   * Hostname of the externally running gokeyless key server that holds the
   * private key. Mutable — patched in place.
   */
  host: string;
  /**
   * Port Cloudflare uses to communicate with the key server. Mutable —
   * patched in place.
   * @default 24008
   */
  port?: number;
  /**
   * Human readable name for the Keyless SSL configuration. If omitted, a
   * deterministic name is generated from the app, stage, and logical ID.
   * Mutable — patched in place.
   * @default ${app}-${stage}-${id}
   */
  name?: string;
  /**
   * How the certificate chain is bundled: `ubiquitous` (highest probability
   * of broad trust), `optimal` (shortest chain, newest intermediates), or
   * `force` (use the chain exactly as uploaded).
   *
   * Create-only — changing the bundle method triggers a replacement.
   * @default "ubiquitous"
   */
  bundleMethod?: BundleMethod;
  /**
   * Whether the Keyless SSL configuration is on or off. Mutable — patched in
   * place.
   * @default true
   */
  enabled?: boolean;
  /**
   * Reach the key server through a Cloudflare Tunnel virtual network instead
   * of the public internet.
   *
   * Adding or changing the tunnel is patched in place; removing a previously
   * configured tunnel triggers a replacement (the PATCH API cannot clear it).
   */
  tunnel?: Tunnel;
}

export interface Attributes {
  /** Cloudflare-assigned identifier of the Keyless SSL configuration. */
  keylessCertificateId: string;
  /** Zone the Keyless SSL configuration belongs to. */
  zoneId: string;
  /** Human readable name of the Keyless SSL configuration. */
  name: string;
  /** Hostname of the key server holding the private key. */
  host: string;
  /** Port Cloudflare uses to communicate with the key server. */
  port: number;
  /** Whether the Keyless SSL configuration is on or off. */
  enabled: boolean;
  /** Current lifecycle status of the Keyless SSL configuration. */
  status: Status;
  /** Permissions the requesting token has on this Keyless SSL. */
  permissions: string[];
  /** ISO8601 timestamp the Keyless SSL configuration was created. */
  createdOn: string;
  /** ISO8601 timestamp the Keyless SSL configuration was last modified. */
  modifiedOn: string;
  /** Tunnel configuration, when the key server is reached through a Cloudflare Tunnel. */
  tunnel: { privateIp: string; vnetId: string } | undefined;
}

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

/**
 * A zone-level Keyless SSL configuration — serve TLS for a certificate whose
 * private key stays on your own key server instead of being uploaded to
 * Cloudflare.
 *
 * You upload only the certificate (and intermediates); Cloudflare reaches out
 * to an externally running [gokeyless](https://github.com/cloudflare/gokeyless)
 * key server at `host:port` (optionally through a Cloudflare Tunnel) for every
 * private-key operation.
 *
 * Keyless SSL is an **Enterprise-only** feature: on zones without the
 * entitlement, creation fails with the typed `KeylessSslNotAvailable` error
 * (Cloudflare code 1067).
 *
 * `host`, `port`, `name`, `enabled`, and `tunnel` are mutable in place;
 * `certificate` and `bundleMethod` are create-only and trigger a replacement.
 * ### Creating a Keyless SSL configuration
 * **Example:** Basic key server over the public internet
 * ```typescript
 * const keyless = yield* Cloudflare.KeylessCertificate.KeylessCertificate("SiteKeyless", {
 *   zoneId: zone.zoneId,
 *   certificate: certPem, // PEM, private key stays on your key server
 *   host: "keyless.example.com",
 *   port: 24008,
 * });
 * ```
 *
 * **Example:** Read the certificate from disk
 * ```typescript
 * const fs = yield* FileSystem.FileSystem;
 * const certificate = yield* fs.readFileString("certs/site.pem");
 *
 * const keyless = yield* Cloudflare.KeylessCertificate.KeylessCertificate("SiteKeyless", {
 *   zoneId: zone.zoneId,
 *   certificate,
 *   host: "keyless.example.com",
 * });
 * ```
 *
 * ### Reaching the key server through a Cloudflare Tunnel
 * **Example:** Private key server on a tunnel virtual network
 * ```typescript
 * const vnet = yield* Cloudflare.Tunnel.VirtualNetwork("KeylessVnet", {});
 *
 * const keyless = yield* Cloudflare.KeylessCertificate.KeylessCertificate("SiteKeyless", {
 *   zoneId: zone.zoneId,
 *   certificate: certPem,
 *   host: "keyless.internal",
 *   port: 24008,
 *   tunnel: {
 *     privateIp: "10.0.0.10",
 *     vnetId: vnet.vnetId,
 *   },
 * });
 * ```
 *
 * ### Rotation
 * **Example:** Rotate by changing the certificate
 * ```typescript
 * // `certificate` is create-only — changing it replaces the configuration:
 * // the new one is created and the old one is deleted.
 * const keyless = yield* Cloudflare.KeylessCertificate.KeylessCertificate("SiteKeyless", {
 *   zoneId: zone.zoneId,
 *   certificate: rotatedCertPem,
 *   host: "keyless.example.com",
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/ssl/keyless-ssl/
 *
 * @resource
 * @product Keyless Certificates
 * @category SSL/TLS & Certificates
 */
export const KeylessCertificate = Resource<KeylessCertificate>(TypeId, {
  aliases: ["Cloudflare.KeylessCertificate"],
});

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

export const KeylessCertificateProvider = () =>
  Provider.succeed(KeylessCertificate, {
    stables: ["keylessCertificateId", "zoneId", "createdOn"],

    // Keyless SSL is zone-scoped (`/zones/{id}/keyless_certificates`) with no
    // account-wide enumeration API. Fan out over every zone in the account,
    // list its Keyless SSL configurations, and hydrate each into the exact
    // `read` Attributes shape. Zones without the Enterprise entitlement reject
    // the route 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) =>
          keylessCertificates.listKeylessCertificates.pages({ zoneId: zone.id }).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((page) =>
                (page.result ?? [])
                  .filter((keyless) => keyless.status !== "deleted")
                  .map((keyless) =>
                    toAttributes({ ...keyless, permissions: [...keyless.permissions] }, zone.id),
                  ),
              ),
            ),
            // Non-entitled / plan-gated zones reject Keyless SSL listing.
            Effect.catchTag("Forbidden", () => Effect.succeed([])),
          ),
        { concurrency: 10 },
      );
      return rows.flat();
    }),

    diff: Effect.fn(function* ({ olds, news }) {
      // diff runs during plan — `news` may still contain unresolved Outputs.
      if (!isResolved(news)) return undefined;
      // No prior props to compare against — let the engine decide.
      if (olds?.certificate === undefined) return undefined;
      // The PATCH API has no certificate field — rotation replaces.
      if (normalizePem(olds.certificate) !== normalizePem(news.certificate)) {
        return { action: "replace" } as const;
      }
      // bundleMethod is create-only.
      if ((olds.bundleMethod ?? "ubiquitous") !== (news.bundleMethod ?? "ubiquitous")) {
        return { action: "replace" } as const;
      }
      // The PATCH API can set a tunnel but cannot clear one — removing it
      // requires a replacement. (Adding/changing is an in-place update.)
      if (olds.tunnel !== undefined && news.tunnel === undefined) {
        return { action: "replace" } as const;
      }
      // zoneId is Input<string>; compare only once both are concrete.
      if (
        typeof olds.zoneId === "string" &&
        typeof news.zoneId === "string" &&
        olds.zoneId !== news.zoneId
      ) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

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

      // Owned path: refresh by our persisted identifier. Cloudflare keeps a
      // tombstone with status "deleted" for a while — report it as gone.
      if (output?.keylessCertificateId) {
        const observed = yield* getKeylessCertificate(zoneId, output.keylessCertificateId);
        return observed ? toAttributes(observed, zoneId) : undefined;
      }

      // Cold read — recover from lost state by matching the deterministic
      // physical name. Names are not unique on Cloudflare's side; an exact
      // match on our generated/explicit name is the best identity we have.
      const name = yield* createKeylessName(id, olds?.name);
      const match = yield* findByName(zoneId, name);
      return match ? toAttributes(match, zoneId) : undefined;
    }),

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

      // 1. Observe — the identifier cached on `output` is a hint, not a
      //    guarantee: a missing (or tombstoned "deleted") configuration
      //    falls through to the name scan and then to create.
      let observed = output?.keylessCertificateId
        ? yield* getKeylessCertificate(zoneId, output.keylessCertificateId)
        : undefined;

      // 2. Fall back to scanning the zone for a configuration carrying our
      //    deterministic physical name (recovers from lost state).
      if (!observed) {
        observed = yield* findByName(zoneId, name);
      }

      // 3. Ensure — create when missing. Names are not unique on
      //    Cloudflare's side, so there is no AlreadyExists race to
      //    tolerate. On zones without the Enterprise entitlement this
      //    fails with the typed `KeylessSslNotAvailable` error.
      if (!observed) {
        observed = yield* keylessCertificates.createKeylessCertificate({
          zoneId,
          certificate: news.certificate,
          host: news.host,
          port: news.port ?? 24008,
          name,
          bundleMethod: news.bundleMethod,
          tunnel: desiredTunnel,
        });
      }

      // 4. Sync — diff observed cloud state against desired and patch only
      //    when something actually differs; skip the call on a no-op.
      //    `enabled` is create-time defaulted by Cloudflare, so it is only
      //    compared when explicitly configured.
      const desired = {
        name,
        host: news.host,
        port: news.port ?? 24008,
      };
      const dirty =
        observed.name !== desired.name ||
        observed.host !== desired.host ||
        observed.port !== desired.port ||
        (news.enabled !== undefined && observed.enabled !== news.enabled) ||
        (desiredTunnel !== undefined && !sameTunnel(observed.tunnel ?? undefined, desiredTunnel));

      if (dirty) {
        observed = yield* keylessCertificates.patchKeylessCertificate({
          zoneId,
          keylessCertificateId: observed.id,
          ...desired,
          enabled: news.enabled,
          tunnel: desiredTunnel,
        });
      }

      return toAttributes(observed, zoneId);
    }),

    delete: Effect.fn(function* ({ output }) {
      // Deleting an already-gone configuration answers with Cloudflare code
      // 1005 ("Invalid or missing Keyless SSL") — convergence, not failure.
      yield* keylessCertificates
        .deleteKeylessCertificate({
          zoneId: output.zoneId,
          keylessCertificateId: output.keylessCertificateId,
        })
        .pipe(Effect.catchTag("KeylessCertificateNotFound", () => Effect.void));
    }),
  });

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

type ObservedKeyless = keylessCertificates.GetKeylessCertificateResponse;

/**
 * Read a Keyless SSL configuration by id, mapping "gone"
 * (`KeylessCertificateNotFound`, Cloudflare error code 1005 "Invalid or
 * missing Keyless SSL") and the "deleted" tombstone status to `undefined`.
 */
const getKeylessCertificate = (zoneId: string, keylessCertificateId: string) =>
  keylessCertificates.getKeylessCertificate({ zoneId, keylessCertificateId }).pipe(
    Effect.map((observed): ObservedKeyless | undefined =>
      observed.status === "deleted" ? undefined : observed,
    ),
    Effect.catchTag("KeylessCertificateNotFound", () => Effect.undefined),
  );

/**
 * Find a non-deleted Keyless SSL configuration by exact name. Names are not
 * unique on Cloudflare's side; if several carry the same name, pick the
 * oldest for determinism.
 */
const findByName = (zoneId: string, name: string) =>
  keylessCertificates.listKeylessCertificates.items({ zoneId }).pipe(
    Stream.filter((keyless) => keyless.name === name && keyless.status !== "deleted"),
    Stream.runCollect,
    Effect.map((chunk) =>
      Array.from(chunk)
        .sort((a, b) => a.createdOn.localeCompare(b.createdOn))
        .at(0),
    ),
    Effect.map(
      (keyless): ObservedKeyless | undefined =>
        keyless && {
          ...keyless,
          permissions: [...keyless.permissions],
        },
    ),
  );

const createKeylessName = (id: string, name: string | undefined) =>
  Effect.gen(function* () {
    return name ?? (yield* createPhysicalName({ id, lowercase: true }));
  });

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

/**
 * Resolve a tunnel prop to the concrete shape the API expects. Inputs have
 * been resolved to concrete strings by Plan before reconcile runs.
 */
const resolveTunnel = (
  tunnel: Tunnel | undefined,
): { privateIp: string; vnetId: string } | undefined =>
  tunnel === undefined
    ? undefined
    : {
        privateIp: tunnel.privateIp as string,
        vnetId: tunnel.vnetId as string,
      };

const sameTunnel = (
  observed: { privateIp: string; vnetId: string } | undefined,
  desired: { privateIp: string; vnetId: string },
): boolean =>
  observed !== undefined &&
  observed.privateIp === desired.privateIp &&
  observed.vnetId === desired.vnetId;

const toAttributes = (keyless: ObservedKeyless, zoneId: string): Attributes => ({
  keylessCertificateId: keyless.id,
  zoneId,
  name: keyless.name,
  host: keyless.host,
  port: keyless.port,
  enabled: keyless.enabled,
  status: keyless.status as Status,
  permissions: [...keyless.permissions],
  createdOn: keyless.createdOn,
  modifiedOn: keyless.modifiedOn,
  tunnel: keyless.tunnel ?? undefined,
});