import * as certificateAuthorities from "@distilled.cloud/cloudflare/certificate-authorities";
import { Unowned } from "alchemy/AdoptPolicy";
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 Schedule from "effect/Schedule";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";
import { listAllZones } from "../Zone/lookup.ts";
const TypeId = "Cloudflare.CertificateAuthorities.HostnameAssociation" as const;
type TypeId = typeof TypeId;
export type HostnameAssociationProps = {
/**
* Zone whose hostnames should enforce mTLS. Stable — the zone is part of
* the association's identity, so changing it triggers a replacement (the
* old zone's association is cleared).
*/
zoneId: string;
/**
* UUID of an uploaded CA certificate from the account-level mTLS
* Certificate Management store (`Cloudflare.MtlsCertificate.MtlsCertificate` with
* `ca: true`). When omitted, the hostnames are associated with the zone's
* active Cloudflare Managed CA instead.
*
* Stable — the certificate keys the association, so changing it triggers
* a replacement (the old certificate's hostname list is cleared).
*
* @default the active Cloudflare Managed CA
*/
mtlsCertificateId?: string;
/**
* Fully-qualified hostnames in the zone that enforce mTLS for the keyed
* certificate authority. Mutable — the desired list replaces the current
* one in full on update.
*/
hostnames: Array<string>;
};
export type HostnameAssociationAttributes = {
/** Zone the association belongs to. */
zoneId: string;
/**
* The mTLS CA certificate the hostnames are associated with, or
* `undefined` when they are associated with the Cloudflare Managed CA.
*/
mtlsCertificateId: string | undefined;
/** Hostnames currently enforcing mTLS for the keyed CA. */
hostnames: Array<string>;
};
export type HostnameAssociation = Resource<
TypeId,
HostnameAssociationProps,
HostnameAssociationAttributes,
never,
Providers
>;
/**
* The set of hostnames in a Cloudflare zone that enforce mTLS, optionally
* keyed by an uploaded mTLS CA certificate.
*
* Cloudflare models this as a settings singleton per
* `(zone, mtls_certificate_id)` pair — a pure GET/PUT API over
* `/zones/{zone_id}/certificate_authorities/hostname_associations`. With no
* `mtlsCertificateId`, the hostnames are associated with the zone's active
* Cloudflare Managed CA; with one, they are associated with that uploaded CA
* certificate. Destroying the resource clears the association (PUT of an
* empty hostname list).
*
* Safety: when there is no prior state but the keyed association already has
* hostnames, `read` reports the existing list as `Unowned` — the engine
* refuses to take it over (and would otherwise clobber a hand-managed list)
* unless `--adopt` or `adopt(true)` is set.
*
* Note: an mTLS CA certificate cannot be deleted while hostname associations
* still reference it. Pass the certificate id through
* `cert.mtlsCertificateId` so the engine destroys the association before the
* certificate.
* ### Cloudflare Managed CA
* **Example:** Enforce mTLS on a hostname with the Managed CA
* ```typescript
* yield* Cloudflare.CertificateAuthorities.HostnameAssociation("MtlsHosts", {
* zoneId: zone.zoneId,
* hostnames: ["api.example.com"],
* });
* ```
*
* ### Uploaded CA certificate
* **Example:** Associate hostnames with an uploaded CA
* ```typescript
* const ca = yield* Cloudflare.MtlsCertificate.MtlsCertificate("ClientCa", {
* ca: true,
* certificates: caPem,
* });
*
* yield* Cloudflare.CertificateAuthorities.HostnameAssociation("ClientCaHosts", {
* zoneId: zone.zoneId,
* mtlsCertificateId: ca.mtlsCertificateId,
* hostnames: ["api.example.com", "admin.example.com"],
* });
* ```
*
* @see https://developers.cloudflare.com/api/resources/certificate_authorities/subresources/hostname_associations/
*
* @resource
* @product Certificate Authorities
* @category SSL/TLS & Certificates
*/
export const HostnameAssociation = Resource<HostnameAssociation>(TypeId);
/**
* Returns true if the given value is a HostnameAssociation resource.
*/
export const isHostnameAssociation = (value: unknown): value is HostnameAssociation =>
Predicate.hasProperty(value, "Type") && value.Type === TypeId;
/** The hostname list still reads back non-empty after repeated clears. */
export class HostnameAssociationNotCleared extends Data.TaggedError(
"HostnameAssociationNotCleared",
)<{
zoneId: string;
mtlsCertificateId: string | undefined;
hostnames: string[];
}> {
override get message() {
return `The ${this.mtlsCertificateId ?? "Managed CA"} hostname association in zone ${this.zoneId} still lists ${this.hostnames.join(", ")} after repeated clears`;
}
}
export const HostnameAssociationProvider = () =>
Provider.succeed(HostnameAssociation, {
stables: ["zoneId", "mtlsCertificateId"],
list: Effect.fn(function* () {
const { accountId } = yield* yield* CloudflareEnvironment;
// The association is a per-zone settings singleton with no
// account-wide enumeration API. The only enumerable key is the
// zone's active Cloudflare Managed CA (no `mtlsCertificateId`):
// associations keyed by an uploaded CA can't be enumerated because
// there is no API to list the certificate ids in play. Fan out over
// every zone and read its Managed-CA association.
const zones = yield* listAllZones(accountId);
const rows = yield* Effect.forEach(
zones,
(zone) =>
certificateAuthorities.getHostnameAssociation({ zoneId: zone.id }).pipe(
Effect.map((observed): HostnameAssociationAttributes | undefined => {
const hostnames = [...(observed.hostnames ?? [])];
// An empty list is the singleton's "unconfigured"
// state — nothing exists to enumerate (matches `read`).
if (hostnames.length === 0) return undefined;
return {
zoneId: zone.id,
mtlsCertificateId: undefined,
hostnames,
};
}),
// Zones without the mTLS entitlement reject the route
// (Forbidden) or aren't routable (InvalidRoute); skip them.
Effect.catchTag(["Forbidden", "InvalidRoute"], () => Effect.undefined),
),
{ concurrency: 10 },
);
return rows.filter((row): row is HostnameAssociationAttributes => row !== undefined);
}),
diff: Effect.fn(function* ({ olds = {}, news, output }) {
const o = olds as HostnameAssociationProps;
const n = news as HostnameAssociationProps;
// zoneId is Input<string>; compare only once both sides are concrete.
const oldZoneId = output?.zoneId ?? (typeof o.zoneId === "string" ? o.zoneId : undefined);
if (oldZoneId !== undefined && typeof n.zoneId === "string" && oldZoneId !== n.zoneId) {
return { action: "replace" } as const;
}
// mtlsCertificateId keys the association — `undefined` (Managed CA)
// is itself an identity value.
const oldCertId =
output !== undefined
? output.mtlsCertificateId
: typeof o.mtlsCertificateId === "string"
? o.mtlsCertificateId
: undefined;
// A presence flip (Managed CA <-> uploaded CA) is decidable even when
// the new side is an unresolved Input reference — the reference itself
// proves a certificate now keys (or no longer keys) the association.
if ((oldCertId === undefined) !== (n.mtlsCertificateId === undefined)) {
return { action: "replace" } as const;
}
// Both sides keyed by a certificate: compare only once the new side is
// a concrete string (an unresolved Input may still resolve to the same
// id, so we leave that case to the engine's default update).
if (typeof n.mtlsCertificateId === "string" && oldCertId !== n.mtlsCertificateId) {
return { action: "replace" } as const;
}
return undefined;
}),
read: Effect.fn(function* ({ output, olds }) {
const zoneId = output?.zoneId ?? (typeof olds?.zoneId === "string" ? olds.zoneId : undefined);
if (!zoneId) return undefined;
// A CA id that hasn't resolved yet (a certificate created in the same
// deploy) names no association we can observe. Reading with
// `undefined` would read the zone's managed-CA association instead, a
// different singleton, and report it as an unowned conflict.
if (
output === undefined &&
olds?.mtlsCertificateId !== undefined &&
typeof olds.mtlsCertificateId !== "string"
) {
return undefined;
}
const mtlsCertificateId =
output !== undefined
? output.mtlsCertificateId
: typeof olds?.mtlsCertificateId === "string"
? olds.mtlsCertificateId
: undefined;
const observed = yield* certificateAuthorities.getHostnameAssociation({
zoneId,
mtlsCertificateId,
});
const hostnames = [...(observed.hostnames ?? [])];
// An empty list is the singleton's "unconfigured" state — nothing
// exists to refresh or adopt.
if (hostnames.length === 0) return undefined;
const attrs: HostnameAssociationAttributes = {
zoneId,
mtlsCertificateId,
hostnames,
};
// Cold read with a non-empty pre-existing list: the association
// carries no ownership markers, so we cannot prove we created it —
// gate the takeover behind the adopt policy.
return output !== undefined ? attrs : Unowned(attrs);
}),
reconcile: Effect.fn(function* ({ news }) {
// Inputs have been resolved to concrete strings by Plan.
const zoneId = news.zoneId as string;
const mtlsCertificateId = news.mtlsCertificateId as string | undefined;
const desired = (news.hostnames ?? []) as Array<string>;
// 1. Observe — the association always "exists" (possibly empty);
// read the live hostname list.
const observed = yield* certificateAuthorities.getHostnameAssociation({
zoneId,
mtlsCertificateId,
});
const current = [...(observed.hostnames ?? [])];
// 2. Sync — full PUT of the desired list; skip when the observed
// set already matches (order is not significant).
if (hostnameSetEquals(current, desired)) {
return { zoneId, mtlsCertificateId, hostnames: current };
}
const updated = yield* certificateAuthorities.putHostnameAssociation({
zoneId,
mtlsCertificateId,
hostnames: desired,
});
return {
zoneId,
mtlsCertificateId,
hostnames: [...(updated.hostnames ?? desired)],
};
}),
delete: Effect.fn(function* ({ output }) {
// The association is a settings singleton — "delete" means clearing
// the hostname list with a PUT of an empty list, re-sent until the
// clear is visible: Cloudflare sometimes keeps the old list after the
// PUT. An association that outlives its CA survives the CA's delete,
// and a re-upload of the same certificate gets the same id, so the
// stale hostnames would come back attached to the new upload. Failing
// here keeps the CA (deleted after this) in place instead.
const clear = Effect.gen(function* () {
yield* certificateAuthorities.putHostnameAssociation({
zoneId: output.zoneId,
mtlsCertificateId: output.mtlsCertificateId,
hostnames: [],
});
const observed = yield* certificateAuthorities.getHostnameAssociation({
zoneId: output.zoneId,
mtlsCertificateId: output.mtlsCertificateId,
});
const hostnames = [...(observed.hostnames ?? [])];
if (hostnames.length > 0) {
return yield* new HostnameAssociationNotCleared({
zoneId: output.zoneId,
mtlsCertificateId: output.mtlsCertificateId,
hostnames,
});
}
});
yield* clear.pipe(
Effect.retry({
while: (error) => error._tag === "HostnameAssociationNotCleared",
schedule: Schedule.spaced("2 seconds"),
times: 10,
}),
);
}),
});
/** Order-insensitive equality of two hostname lists (exact duplicates kept). */
const hostnameSetEquals = (a: ReadonlyArray<string>, b: ReadonlyArray<string>): boolean => {
if (a.length !== b.length) return false;
const sortedA = [...a].sort();
const sortedB = [...b].sort();
return sortedA.every((v, i) => v === sortedB[i]);
};