import * as ssl from "@distilled.cloud/cloudflare/ssl";
import * as workers from "@distilled.cloud/cloudflare/workers";
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 * 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.Ssl.CertificatePack" as const;
type TypeId = typeof TypeId;
/**
* Certificate Authorities available for Advanced Certificate Manager orders.
*
* - `google` — Google Trust Services
* - `lets_encrypt` — Let's Encrypt (no `cloudflareBranding`)
* - `ssl_com` — SSL.com (supports `email` validation)
*/
export type CertificatePackCertificateAuthority = "google" | "lets_encrypt" | "ssl_com";
/**
* Domain Control Validation method used to prove ownership of the
* certificate's hostnames.
*/
export type CertificatePackValidationMethod = "txt" | "http" | "email";
/**
* Number of days the issued certificates are valid for.
*/
export type CertificatePackValidityDays = 14 | 30 | 90 | 365;
/**
* Status of a certificate pack as reported by Cloudflare.
*/
export type CertificatePackStatus =
| "initializing"
| "pending_validation"
| "deleted"
| "pending_issuance"
| "pending_deployment"
| "pending_deletion"
| "pending_expiration"
| "expired"
| "active"
| "initializing_timed_out"
| "validation_timed_out"
| "issuance_timed_out"
| "deployment_timed_out"
| "deletion_timed_out"
| "pending_cleanup"
| "staging_deployment"
| "staging_active"
| "deactivating"
| "inactive"
| "backup_issued"
| "holding_deployment";
/**
* A Domain Control Validation record for a certificate pack — create the
* indicated TXT/CNAME record (or serve the HTTP token) to complete
* validation when the pack is `pending_validation`.
*/
export interface CertificatePackValidationRecord {
/** Name of the TXT record to create (for `txt` validation). */
txtName?: string;
/** Value of the TXT record (for `txt` validation). */
txtValue?: string;
/** URL that must serve `httpBody` (for `http` validation). */
httpUrl?: string;
/** Body the `httpUrl` must respond with (for `http` validation). */
httpBody?: string;
/** Name of the CNAME record to create (for delegated DCV). */
cname?: string;
/** Target of the CNAME record (for delegated DCV). */
cnameTarget?: string;
/** Approver email addresses (for `email` validation). */
emails?: string[];
/** Validation status of this record. */
status?: string;
}
export interface CertificatePackProps {
/**
* Zone the certificate pack belongs to. Stable — moving a pack to a
* different zone triggers a replacement.
*/
zoneId: string;
/**
* Certificate Authority to order the certificates from.
*
* Immutable — the Cloudflare API has no way to change the CA of an
* existing pack, so changing it triggers a replacement.
*/
certificateAuthority: CertificatePackCertificateAuthority;
/**
* Hostnames the certificates cover. Must contain the zone apex, may
* contain wildcards, and may not exceed 50 hosts.
*
* Immutable — hosts cannot be added to or removed from an existing
* pack, so changing them (order-insensitively) triggers a replacement.
*/
hosts: string[];
/**
* Domain Control Validation method for the order.
*
* Mutable — changed in place on the existing pack via the SSL
* verification API (`PATCH /ssl/verification/{certificatePackId}`).
*/
validationMethod: CertificatePackValidationMethod;
/**
* Validity period of the issued certificates, in days.
*
* Immutable — changing it triggers a replacement (re-order).
*/
validityDays: CertificatePackValidityDays;
/**
* Whether to add Cloudflare branding to the order: a subdomain of
* `sni.cloudflaressl.com` is used as the certificate's Common Name.
*
* Mutable — patched in place.
*
* @default false
*/
cloudflareBranding?: boolean;
}
export interface CertificatePackAttributes {
/** Cloudflare-assigned identifier of the certificate pack. */
certificatePackId: string;
/** Zone the pack belongs to. */
zoneId: string;
/**
* Current status of the pack. Issuance is asynchronous — a freshly
* ordered pack starts in `initializing`/`pending_validation` and only
* reaches `active` once Domain Control Validation completes.
*/
status: CertificatePackStatus;
/** Hostnames the certificates cover. */
hosts: string[];
/** Certificate Authority the pack was ordered from. */
certificateAuthority: string;
/** Domain Control Validation method currently configured. */
validationMethod: string | undefined;
/** Validity period of the issued certificates, in days. */
validityDays: number | undefined;
/** Identifier of the primary certificate in the pack, once issued. */
primaryCertificate: string | undefined;
/**
* Outstanding Domain Control Validation records — create these
* TXT/CNAME records (or serve the HTTP tokens) to complete validation.
*/
validationRecords: CertificatePackValidationRecord[] | undefined;
/** DCV Delegation records for delegated domain validation. */
dcvDelegationRecords: CertificatePackValidationRecord[] | undefined;
}
export type CertificatePack = Resource<
TypeId,
CertificatePackProps,
CertificatePackAttributes,
never,
Providers
>;
/**
* An Advanced Certificate Manager (ACM) certificate pack — an order for
* edge certificates covering a custom set of hostnames in a zone, with a
* choice of Certificate Authority, validation method, and validity period.
*
* Requires the **Advanced Certificate Manager** subscription on the zone;
* ordering without it fails with the typed `AdvancedCertificateManagerRequired`
* error (Cloudflare code 1450).
*
* Issuance is asynchronous: the resource returns as soon as the order is
* placed (status `initializing`/`pending_validation`) and does not wait for
* `active`, because validation may require you to create DNS records first —
* the outstanding records are exported as `validationRecords`.
*
* The pack's `certificateAuthority`, `hosts`, and `validityDays` are
* immutable — changing any of them replaces the pack (a new order).
* `validationMethod` and `cloudflareBranding` are updated in place.
* ### Ordering a certificate pack
* **Example:** Order an advanced certificate for the apex and a wildcard
* ```typescript
* const pack = yield* Cloudflare.Ssl.CertificatePack("ApexCert", {
* zoneId: zone.zoneId,
* certificateAuthority: "google",
* hosts: ["example.com", "*.example.com"],
* validationMethod: "txt",
* validityDays: 90,
* });
* ```
*
* **Example:** Order from Let's Encrypt with a short validity
* ```typescript
* yield* Cloudflare.Ssl.CertificatePack("ShortLivedCert", {
* zoneId: zone.zoneId,
* certificateAuthority: "lets_encrypt",
* hosts: ["example.com", "api.example.com"],
* validationMethod: "http",
* validityDays: 30,
* });
* ```
*
* ### Completing validation
* **Example:** Create the DCV TXT records the order asks for
* ```typescript
* const pack = yield* Cloudflare.Ssl.CertificatePack("ApexCert", {
* zoneId: zone.zoneId,
* certificateAuthority: "google",
* hosts: ["example.com"],
* validationMethod: "txt",
* validityDays: 90,
* });
* // pack.validationRecords contains the txtName/txtValue pairs to create
* // as DNS records so the CA can validate domain control.
* ```
*
* @see https://developers.cloudflare.com/ssl/edge-certificates/advanced-certificate-manager/
*
* @resource
* @product SSL/TLS
* @category SSL/TLS & Certificates
*/
export const CertificatePack = Resource<CertificatePack>(TypeId);
/**
* Returns true if the given value is a CertificatePack resource.
*/
export const isCertificatePack = (value: unknown): value is CertificatePack =>
Predicate.hasProperty(value, "Type") && value.Type === TypeId;
export const CertificatePackProvider = () =>
Provider.succeed(CertificatePack, {
stables: ["certificatePackId", "zoneId"],
diff: Effect.fn(function* ({ olds, news, output }) {
// news is Input<Props> during plan — only compare once resolved.
if (!isResolved(news)) return undefined;
// No prior props to compare against — let the engine decide.
if (olds?.hosts === undefined) return undefined;
// zoneId is the pack's scope; it is Input<string>, so compare only
// once both sides are concrete.
const oldZoneId =
output?.zoneId ?? (typeof olds.zoneId === "string" ? olds.zoneId : undefined);
if (oldZoneId !== undefined && typeof news.zoneId === "string" && oldZoneId !== news.zoneId) {
return { action: "replace" } as const;
}
// The order is immutable in CA, hosts, and validity — any change is
// a re-order (replacement). hosts compare order-insensitively.
if (
olds.certificateAuthority !== news.certificateAuthority ||
olds.validityDays !== news.validityDays ||
!sameHosts(olds.hosts, news.hosts)
) {
return { action: "replace" } as const;
}
// validationMethod / cloudflareBranding are in-place updates.
return undefined;
}),
read: Effect.fn(function* ({ output, olds }) {
const zoneId = output?.zoneId ?? (typeof olds?.zoneId === "string" ? olds.zoneId : undefined);
if (!zoneId) return undefined;
// Owned path: refresh by our persisted pack id.
if (output?.certificatePackId) {
const observed = yield* getPack(zoneId, output.certificatePackId);
if (observed) return toAttributes(zoneId, observed);
return undefined;
}
// Cold lookup (state persistence failed before we saved the id): an
// advanced pack with this exact host set may already exist. Packs
// carry no ownership markers, so report it as `Unowned` and let the
// engine gate takeover behind the adopt policy.
if (olds?.hosts) {
const observed = yield* findByHosts(zoneId, olds.hosts);
if (observed) return Unowned(toAttributes(zoneId, observed));
}
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 pack id cached on `output` is a hint, not a
// guarantee: a missing pack falls through to the host-set scan
// and then to a fresh order.
let observed = output?.certificatePackId
? yield* getPack(zoneId, output.certificatePackId)
: undefined;
// 2. Fall back to scanning the zone for an advanced pack with the
// same host set (recovers from a crash after order-before-save).
if (!observed) {
observed = yield* findByHosts(zoneId, news.hosts);
}
// 3. Ensure — order the pack when missing. Ordering is gated on the
// Advanced Certificate Manager subscription; the typed
// `AdvancedCertificateManagerRequired` error propagates to the
// caller untouched.
if (!observed) {
observed = yield* ssl.createCertificatePack({
zoneId,
type: "advanced",
certificateAuthority: news.certificateAuthority,
hosts: news.hosts,
validationMethod: news.validationMethod,
validityDays: news.validityDays,
cloudflareBranding: news.cloudflareBranding,
});
}
// 4. Sync — diff each mutable aspect of the observed pack against
// the desired props; skip the API entirely on a no-op. A freshly
// ordered pack already matches, so both checks fall through.
if (
news.cloudflareBranding !== undefined &&
(observed.cloudflareBranding ?? false) !== news.cloudflareBranding
) {
observed = yield* ssl.patchCertificatePack({
zoneId,
certificatePackId: observed.id,
cloudflareBranding: news.cloudflareBranding,
});
}
let validationMethod = observed.validationMethod ?? undefined;
if (validationMethod !== news.validationMethod) {
const verification = yield* ssl.patchVerification({
zoneId,
certificatePackId: observed.id,
validationMethod: news.validationMethod,
});
validationMethod = verification.validationMethod ?? validationMethod;
}
return toAttributes(zoneId, observed, validationMethod);
}),
list: Effect.fn(function* () {
const { accountId } = yield* yield* CloudflareEnvironment;
// Certificate packs are zone-scoped; there is no account-wide
// enumeration API. Fan out over every zone in the account and list
// its packs, restricting to `advanced` packs (the only kind this
// resource manages — universal/total_tls packs are not orderable).
const zones = yield* listAllZones(accountId);
// Cloudflare auto-orders an `advanced` pack for every Worker custom
// domain (hosts `[apex, host, *.host]`) and owns its lifecycle — the
// domain's `certId` is that pack's id. Those packs are not ours to
// enumerate (deleting one strips TLS from a live custom domain), so
// exclude them. Only zones that have candidate packs look up their
// custom domains, filtered to that zone.
const workerManagedIn = (zoneId: string) =>
workers.listDomains.items({ accountId, zoneId }).pipe(
Stream.runCollect,
Effect.map((domains) => new Set(Array.from(domains, (d) => d.certId))),
);
const rows = yield* Effect.forEach(
zones,
(zone) =>
ssl.listCertificatePacks.pages({ zoneId: zone.id, status: "all" }).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).flatMap((page) =>
(page.result ?? []).filter(
(pack) => pack.type === "advanced" && !isTombstone(pack),
),
),
),
Effect.flatMap((packs) =>
packs.length === 0
? Effect.succeed([] as CertificatePackAttributes[])
: workerManagedIn(zone.id).pipe(
Effect.map((workerManaged) =>
packs
.filter((pack) => !workerManaged.has(pack.id))
.map((pack) => toAttributes(zone.id, pack)),
),
),
),
// A plan-gated zone (no ACM) rejects the route, and a freshly
// minted token may briefly answer Forbidden — skip either.
Effect.catchTag(["InvalidRoute", "Forbidden"], () =>
Effect.succeed([] as CertificatePackAttributes[]),
),
),
{ concurrency: 10 },
);
return rows.flat();
}),
delete: Effect.fn(function* ({ output }) {
const { zoneId, certificatePackId } = output;
yield* Effect.gen(function* () {
// Observe first — a missing pack (404, code 1408), a `deleted`
// tombstone, or a pack Cloudflare is already deleting are all done.
const observed = yield* getPack(zoneId, certificatePackId);
if (!observed || observed.status === "pending_deletion") return;
yield* ssl
.deleteCertificatePack({ zoneId, certificatePackId })
.pipe(Effect.catchTag("CertificatePackNotFound", () => Effect.void));
}).pipe(
// Cloudflare's certificate service answers a code-less 400 "Bad
// response certificate service" while it is mid-transition on the
// pack (observed on a just-deleted tombstone). Re-observe on a short
// bounded schedule — the next pass usually sees the tombstone and
// returns. If the pack is still live after ~50s, fail honestly
// rather than report a delete that did not happen.
Effect.retry({
while: (e) => e._tag === "CertificatePackNotDeletable",
schedule: Schedule.spaced("5 seconds"),
times: 10,
}),
);
}),
});
// ---------------------------------------------------------------------------
// API helpers
// ---------------------------------------------------------------------------
type ObservedPack =
| ssl.GetCertificatePackResponse
| ssl.CreateCertificatePackResponse
| ssl.PatchCertificatePackResponse
| ssl.ListCertificatePacksResponse["result"][number];
/**
* A deleted pack lingers for a minute or two as a `status: "deleted"`
* tombstone (still returned by get and by list with `status=all`). It is
* gone for every purpose: it cannot be patched, and deleting it again fails
* with `CertificatePackNotDeletable`.
*/
const isTombstone = (pack: { status: string }) => pack.status === "deleted";
/**
* Read a pack by id, mapping "gone" (`CertificatePackNotFound`, Cloudflare
* error code 1408 / HTTP 404, or a `deleted` tombstone) and a deleted zone
* (`InvalidRoute`, code 7003) to `undefined`.
*/
const getPack = (zoneId: string, certificatePackId: string) =>
ssl.getCertificatePack({ zoneId, certificatePackId }).pipe(
Effect.map((pack): ssl.GetCertificatePackResponse | undefined =>
isTombstone(pack) ? undefined : pack,
),
Effect.catchTag(["CertificatePackNotFound", "InvalidRoute"], () => Effect.undefined),
);
/**
* Find an advanced pack by exact host set within the zone. Cloudflare
* rejects a second advanced order for an identical host set, so at most
* one pack can match. Includes non-active (pending) packs.
*/
const findByHosts = (zoneId: string, hosts: string[]) =>
ssl.listCertificatePacks.items({ zoneId, status: "all" }).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).find(
(pack) => pack.type === "advanced" && !isTombstone(pack) && sameHosts(pack.hosts, hosts),
),
),
Effect.catchTag("InvalidRoute", () => Effect.undefined),
);
/** Order-insensitive host set comparison. */
const sameHosts = (a: ReadonlyArray<string>, b: ReadonlyArray<string>): boolean => {
if (a.length !== b.length) return false;
const set = new Set(a);
return b.every((host) => set.has(host));
};
const toRecord = (record: {
cname?: string | null;
cnameTarget?: string | null;
emails?: string[] | null;
httpBody?: string | null;
httpUrl?: string | null;
status?: string | null;
txtName?: string | null;
txtValue?: string | null;
}): CertificatePackValidationRecord => ({
txtName: record.txtName ?? undefined,
txtValue: record.txtValue ?? undefined,
httpUrl: record.httpUrl ?? undefined,
httpBody: record.httpBody ?? undefined,
cname: record.cname ?? undefined,
cnameTarget: record.cnameTarget ?? undefined,
emails: record.emails ?? undefined,
status: record.status ?? undefined,
});
const toAttributes = (
zoneId: string,
pack: ObservedPack,
validationMethod?: string,
): CertificatePackAttributes => ({
certificatePackId: pack.id,
zoneId,
status: pack.status as CertificatePackStatus,
hosts: [...pack.hosts],
certificateAuthority: pack.certificateAuthority ?? "",
validationMethod: validationMethod ?? pack.validationMethod ?? undefined,
validityDays: pack.validityDays ?? undefined,
primaryCertificate: pack.primaryCertificate ?? undefined,
validationRecords: pack.validationRecords?.map(toRecord) ?? undefined,
dcvDelegationRecords: pack.dcvDelegationRecords?.map(toRecord) ?? undefined,
});