import * as originCa from "@distilled.cloud/cloudflare/origin-ca-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 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 { findZoneByName, listAllZones } from "../Zone/lookup.ts";
const TypeId = "Cloudflare.OriginCaCertificate.OriginCaCertificate" as const;
type TypeId = typeof TypeId;
/**
* Signature type requested on the certificate: `origin-rsa` (RSA),
* `origin-ecc` (ECDSA), or `keyless-certificate` (for Keyless SSL servers).
*/
export type RequestType = "origin-rsa" | "origin-ecc" | "keyless-certificate";
/**
* Number of days the certificate should be valid for. Cloudflare only
* accepts this fixed set of validity periods.
*/
export type Validity = 7 | 30 | 90 | 365 | 730 | 1095 | 5475;
export interface Props {
/**
* The Certificate Signing Request (CSR) in PEM format (newline-encoded).
* The CSR's key is yours; Cloudflare only signs it. Immutable — changing
* the CSR triggers a replacement (a new certificate is issued and the old
* one is revoked).
*/
csr: string;
/**
* Hostnames or wildcard names (e.g. `*.example.com`) bound to the
* certificate. Hostnames must be fully qualified domain names belonging
* to zones on your account. Immutable — changing the hostnames triggers
* a replacement.
*/
hostnames: string[];
/**
* Signature type desired on the certificate: `origin-rsa` (RSA),
* `origin-ecc` (ECDSA), or `keyless-certificate` (for Keyless SSL
* servers). Immutable — changing the request type triggers a replacement.
*/
requestType: RequestType;
/**
* The number of days for which the certificate should be valid.
* Immutable — changing the validity triggers a replacement.
* @default 5475
*/
requestedValidity?: Validity;
}
export interface Attributes {
/**
* Cloudflare-assigned identifier of the certificate (a long decimal
* serial string). Stable for the lifetime of the certificate.
*/
certificateId: string;
/**
* The signed Origin CA certificate in PEM format (newline-encoded).
* Install this on your origin server alongside the private key that
* produced the CSR.
*/
certificate: string;
/**
* The Certificate Signing Request the certificate was issued for.
*/
csr: string;
/**
* Hostnames or wildcard names bound to the certificate.
*/
hostnames: string[];
/**
* Signature type on the certificate.
*/
requestType: RequestType;
/**
* The number of days the certificate was requested to be valid for.
*/
requestedValidity: number;
/**
* When the certificate expires.
*/
expiresOn: string | undefined;
}
export type OriginCaCertificate = Resource<TypeId, Props, Attributes, never, Providers>;
/**
* A Cloudflare Origin CA certificate — a free certificate signed by
* Cloudflare's Origin CA that encrypts traffic between Cloudflare's edge
* and your origin server. Origin CA certificates are only trusted by
* Cloudflare (not by browsers), so they are used together with proxied
* DNS records.
*
* You supply a CSR (keeping the private key to yourself); Cloudflare signs
* it synchronously and returns the certificate PEM. The endpoints are
* top-level (`/certificates`) — the zone is implied by the hostnames in the
* request, which must belong to zones on your account.
*
* Certificates are fully immutable: there is no update API, so changing any
* property triggers a replacement (a new certificate is issued, then the
* old one is revoked). Destroying the resource revokes the certificate.
* ### Issuing a certificate
* **Example:** RSA certificate for a single hostname
* ```typescript
* const cert = yield* Cloudflare.OriginCaCertificate.OriginCaCertificate("origin-cert", {
* csr: originCsrPem,
* hostnames: ["origin.example.com"],
* requestType: "origin-rsa",
* requestedValidity: 90,
* });
* ```
*
* **Example:** Wildcard ECDSA certificate with the default 15-year validity
* ```typescript
* const cert = yield* Cloudflare.OriginCaCertificate.OriginCaCertificate("wildcard-cert", {
* csr: wildcardCsrPem,
* hostnames: ["example.com", "*.example.com"],
* requestType: "origin-ecc",
* });
* ```
*
* ### Using the certificate
* **Example:** Install the signed PEM on your origin
* ```typescript
* // The signed certificate is returned synchronously on create:
* const pem = cert.certificate; // "-----BEGIN CERTIFICATE-----\n..."
* const expires = cert.expiresOn;
* ```
*
* @see https://developers.cloudflare.com/ssl/origin-configuration/origin-ca/
*
* @resource
* @product Origin CA Certificates
* @category SSL/TLS & Certificates
*/
export const OriginCaCertificate = Resource<OriginCaCertificate>(TypeId, {
aliases: ["Cloudflare.OriginCaCertificate"],
});
/**
* Returns true if the given value is an OriginCaCertificate resource.
*/
export const isOriginCaCertificate = (value: unknown): value is OriginCaCertificate =>
Predicate.hasProperty(value, "Type") && value.Type === TypeId;
export const OriginCaCertificateProvider = () =>
Provider.succeed(OriginCaCertificate, {
// Every prop change is a replacement, so all attributes are stable
// across (non-existent) updates.
stables: [
"certificateId",
"certificate",
"csr",
"hostnames",
"requestType",
"requestedValidity",
"expiresOn",
],
// Origin CA certificates are enumerated per zone (the list endpoint
// requires a `zone_id` query param). Fan out across every zone on the
// account and flatten. The list response omits the csr and requested
// validity, so `toAttributes` fills them with the defaults — matching the
// cold/unowned `read` shape. Origin CA endpoints may require the special
// Origin CA Key auth; a zone we can't enumerate rejects with `Forbidden`,
// which we skip rather than fail (the array stays as complete as the
// credentials allow).
list: Effect.fn(function* () {
const { accountId } = yield* yield* CloudflareEnvironment;
const zones = yield* listAllZones(accountId);
const rows = yield* Effect.forEach(
zones,
(zone) =>
originCa.listOriginCaCertificates.pages({ zoneId: zone.id }).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).flatMap((page) =>
(page.result ?? [])
.filter((cert) => cert.id != null)
.map((cert): Attributes => toAttributes(cert)),
),
),
Effect.catchTag("Forbidden", () => Effect.succeed([] as Attributes[])),
),
{ concurrency: 10 },
);
return rows.flat();
}),
diff: Effect.fn(function* ({ olds, news }) {
const o = olds as Props | undefined;
const n = news as Props;
// No prior props to compare against — let the engine decide.
if (o?.csr === undefined) return undefined;
// There is no update API for Origin CA certificates — every change
// is a replacement.
if (
o.csr !== n.csr ||
o.requestType !== n.requestType ||
(o.requestedValidity ?? DEFAULT_VALIDITY) !== (n.requestedValidity ?? DEFAULT_VALIDITY) ||
!sameHostnames(o.hostnames, n.hostnames)
) {
return { action: "replace" } as const;
}
return undefined;
}),
read: Effect.fn(function* ({ output, olds, previous }) {
// Owned path: refresh by our persisted certificate id. A revoked
// certificate is still returned by GET (with `revokedAt` set) but is
// gone for all practical purposes.
if (output?.certificateId) {
const observed = yield* getCertificate(output.certificateId);
return observed ? toAttributes(observed, { ...olds, ...output }) : undefined;
}
// Cold read — Origin CA certificates have no name or tags, so the
// only identity available is the exact hostname set within the zone
// implied by the hostnames. A match cannot be proven to be ours, so
// brand it `Unowned` and let the engine gate takeover behind the
// adopt policy. Ambiguity (several live certs with the same
// hostnames) means no identity at all — report missing and recreate
// (certificates are free and revocation is harmless).
// Output-valued hostname elements don't survive a `creating`-state
// round-trip (they deserialize as null/undefined) — without a concrete
// hostname there is no identity to search by.
if (typeof olds?.hostnames?.[0] !== "string") return undefined;
const matches = yield* findByHostnames(olds.hostnames);
if (matches.length !== 1) return undefined;
// A replacement issues a new certificate for the same hostnames: the
// one it is replacing is not the replacement.
if (matches[0].id === previous?.certificateId) return undefined;
const observed = yield* getCertificate(matches[0].id!);
return observed ? Unowned(toAttributes(observed, olds)) : undefined;
}),
reconcile: Effect.fn(function* ({ news, output }) {
// Observe — the certificate id cached on `output` is a hint, not a
// guarantee: a missing or revoked certificate falls through to
// "missing" and ensure re-issues.
const observed = output?.certificateId
? yield* getCertificate(output.certificateId)
: undefined;
// Ensure — issue when missing. Issuance is synchronous: the signed
// PEM comes back in the create response. Ids are server-assigned, so
// there is no AlreadyExists race to tolerate.
if (!observed) {
const created = yield* originCa.createOriginCaCertificate({
csr: news.csr,
hostnames: news.hostnames,
requestType: news.requestType,
requestedValidity: news.requestedValidity ?? DEFAULT_VALIDITY,
});
return toAttributes(created, news);
}
// Sync — certificates are immutable; any prop change was already
// routed to replacement by diff, so there is nothing to converge.
// GET omits the csr and requested validity, so fill them from the
// desired props (they are guaranteed equal here).
return toAttributes(observed, news);
}),
delete: Effect.fn(function* ({ output }) {
// Delete = revoke. Idempotent: an unknown id (1101) or an
// already-revoked certificate (1014) both mean "gone".
//
// `CertificateRevocationFailed` (code 1000) is the dual-use generic
// "API errors encountered" Cloudflare returns when a revoke blips —
// most often during the replace-time GC delete, when the old
// certificate is revoked right after its replacement was issued.
// Left untyped it surfaced as `UnknownCloudflareError` and aborted the
// delete, orphaning the old certificate (it is no longer in state, so
// a later `stack.destroy()` cannot reclaim it). Bounded-retry the
// transient failure, then read back: a revoked/absent certificate
// counts as deleted; a still-live one re-raises so the leak is never
// silent.
yield* originCa.deleteOriginCaCertificate({ certificateId: output.certificateId }).pipe(
Effect.retry({
while: (e) => e._tag === "CertificateRevocationFailed",
schedule: Schedule.exponential("500 millis"),
times: 6,
}),
Effect.catchTags({
CertificateNotFound: () => Effect.void,
CertificateAlreadyRevoked: () => Effect.void,
CertificateRevocationFailed: (e) =>
getCertificate(output.certificateId).pipe(
Effect.flatMap((cert) => (cert ? Effect.fail(e) : Effect.void)),
),
}),
);
}),
});
const DEFAULT_VALIDITY = 5475;
/**
* Read a certificate by id, mapping "gone" to `undefined`. Gone is either
* `CertificateNotFound` (Cloudflare error code 1101) or a successful GET of
* an already-revoked certificate (`revokedAt` set).
*/
const getCertificate = (certificateId: string) =>
originCa.getOriginCaCertificate({ certificateId }).pipe(
Effect.map((cert) => (cert.revokedAt ? undefined : cert)),
Effect.catchTag("CertificateNotFound", () => Effect.undefined),
);
/**
* Find live certificates with exactly the given hostname set. The zone is
* implied by the hostnames: resolve the registered zone by walking the
* suffixes of the first hostname (wildcard labels stripped), then scan the
* zone's certificate list. Revoked certificates drop out of the list
* immediately, so every match is live.
*/
const findByHostnames = (hostnames: string[]) =>
Effect.gen(function* () {
const { accountId } = yield* yield* CloudflareEnvironment;
const hostname = hostnames[0].replace(/^\*\./, "");
const zoneId = yield* resolveZoneIdForHostname(accountId, hostname);
if (!zoneId) return [];
const certs = yield* originCa.listOriginCaCertificates.items({ zoneId }).pipe(
Stream.filter((cert) => sameHostnames([...cert.hostnames], hostnames)),
Stream.runCollect,
);
return [...certs].sort((a, b) => (a.id ?? "").localeCompare(b.id ?? ""));
});
/**
* Resolve the zone id for a hostname by trying each suffix of the hostname
* as a zone name (e.g. `a.b.example.com` → `a.b.example.com`,
* `b.example.com`, `example.com`). Returns `undefined` when no zone on the
* account matches.
*/
const resolveZoneIdForHostname = (accountId: string, hostname: string) =>
Effect.gen(function* () {
const parts = hostname.split(".");
for (let i = 0; i < parts.length - 1; i++) {
const name = parts.slice(i).join(".");
const zone = yield* findZoneByName({ accountId, name });
if (zone) return zone.id;
}
return undefined;
});
const sameHostnames = (observed: readonly string[], desired: readonly string[]) =>
observed.length === desired.length &&
[...observed].sort().join(",") === [...desired].sort().join(",");
type CertificateShape = {
id?: string | null;
certificate?: string | null;
csr?: string | null;
hostnames: readonly string[];
requestType?: string | null;
requestedValidity?: number | null;
expiresOn?: string | null;
};
/**
* GET/list responses omit the `csr` and `requested_validity` fields, so
* fill them from the desired props (reconcile) or prior state (read).
*/
const toAttributes = (
cert: CertificateShape,
fallback?: {
csr?: string;
requestType?: RequestType;
requestedValidity?: number;
},
): Attributes => ({
certificateId: cert.id!,
certificate: cert.certificate ?? "",
csr: cert.csr ?? fallback?.csr ?? "",
hostnames: [...cert.hostnames],
requestType: (cert.requestType ?? fallback?.requestType ?? "origin-rsa") as RequestType,
requestedValidity: cert.requestedValidity ?? fallback?.requestedValidity ?? DEFAULT_VALIDITY,
expiresOn: cert.expiresOn ?? undefined,
});