import * as dns from "@distilled.cloud/cloudflare/dns";
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 { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";
import { listAllZones } from "../Zone/lookup.ts";
const TypeId = "Cloudflare.DNS.Dnssec" as const;
type TypeId = typeof TypeId;
/**
* Live DNSSEC status as Cloudflare reports it. `pending` /
* `pending-disabled` are the eventually-consistent transitions toward
* `active` / `disabled`; reaching `active` additionally requires the DS
* record to be submitted at the registrar.
*/
export type DnssecStatus =
| "active"
| "pending"
| "disabled"
| "pending-disabled"
| "error"
| (string & {});
/**
* The user-desired DNSSEC state — Cloudflare's PATCH endpoint only
* accepts these two values.
*/
export type DnssecDesiredStatus = "active" | "disabled";
export interface DnssecProps {
/**
* Zone whose DNSSEC configuration is managed. Stable — DNSSEC is a
* per-zone singleton, so changing the zone triggers a replacement
* (the old zone's DNSSEC is restored to its pre-management state).
*/
zoneId: string;
/**
* Desired DNSSEC state. `"active"` signs the zone; `"disabled"` turns
* signing off. Activation is eventually consistent — Cloudflare
* reports `pending` until the registrar-side DS record is in place.
*
* Mutable — patched in place.
*
* @default "active"
*/
status?: DnssecDesiredStatus;
/**
* Enable multi-signer DNSSEC, allowing multiple providers to serve a
* DNSSEC-signed zone at the same time (required for user-managed
* DNSKEY records).
*
* Mutable — patched in place.
*
* @default false
*/
dnssecMultiSigner?: boolean;
/**
* Allow Cloudflare to transfer in a pre-signed zone (signatures
* included) from an external provider without signing on the fly.
*
* Mutable — patched in place.
*
* @default false
*/
dnssecPresigned?: boolean;
/**
* Use NSEC3 together with DNSSEC. Combined with `dnssecPresigned`,
* enables NSEC3 records when transferring in from an external
* provider (live signing with NSEC3 requires Foundation DNS).
*
* Mutable — patched in place.
*
* @default false
*/
dnssecUseNsec3?: boolean;
}
export interface DnssecAttributes {
/** Zone whose DNSSEC configuration is managed. */
zoneId: string;
/**
* Live DNSSEC status. Stays `pending` until the DS record is
* submitted at the registrar — that final hop is outside Cloudflare's
* (and Alchemy's) control.
*/
status: DnssecStatus;
/** Whether multi-signer DNSSEC is enabled. */
dnssecMultiSigner: boolean | undefined;
/** Whether pre-signed zone transfers are enabled. */
dnssecPresigned: boolean | undefined;
/** Whether NSEC3 is enabled. */
dnssecUseNsec3: boolean | undefined;
/** DNSSEC algorithm key code (e.g. `"13"`). */
algorithm: string | undefined;
/** Digest hash for the DS record. */
digest: string | undefined;
/** Digest algorithm name (e.g. `"SHA256"`). */
digestAlgorithm: string | undefined;
/** Coded digest algorithm type (e.g. `"2"`). */
digestType: string | undefined;
/**
* Full DS record string — this is what users paste at their registrar
* to complete DNSSEC activation.
*/
ds: string | undefined;
/** DNSKEY flags field (e.g. `257` for KSK). */
flags: number | undefined;
/** DS key tag. */
keyTag: number | undefined;
/** Algorithm key type (e.g. `"ECDSAP256SHA256"`). */
keyType: string | undefined;
/** Public key for the DS record. */
publicKey: string | undefined;
/** When DNSSEC was last modified. */
modifiedOn: string | undefined;
/**
* The desired-state family DNSSEC was in before Alchemy first managed
* it (`pending` normalises to `active`, `pending-disabled` to
* `disabled`). Restored on destroy.
*/
initialStatus: DnssecDesiredStatus;
/** `dnssecMultiSigner` before Alchemy first managed the zone. */
initialMultiSigner: boolean | undefined;
/** `dnssecPresigned` before Alchemy first managed the zone. */
initialPresigned: boolean | undefined;
/** `dnssecUseNsec3` before Alchemy first managed the zone. */
initialUseNsec3: boolean | undefined;
}
export type Dnssec = Resource<TypeId, DnssecProps, DnssecAttributes, never, Providers>;
/**
* DNSSEC configuration for a Cloudflare zone
* (`/zones/{zone_id}/dnssec`).
*
* DNSSEC is a per-zone singleton — it always exists in either an
* enabled or disabled state, so this resource never creates or deletes
* anything physical. Reconcile patches the configuration toward the
* desired state; destroy restores the state the zone had before
* Alchemy first managed it (enabled stays enabled, previously-disabled
* zones are deactivated again).
*
* Activation is eventually consistent: after enabling, Cloudflare
* reports `pending` until the `ds` attribute (the DS record) is
* submitted at the domain's registrar. The reconciler polls with
* bounded retries for the zone to leave the `disabled` state but does
* not wait for full `active` — that depends on the registrar.
*
* Safety: when there is no prior state and DNSSEC is already enabled
* on the zone, `read` reports it as `Unowned` and the engine refuses
* to take it over unless `--adopt` (or `adopt(true)`) is set.
* ### Enabling DNSSEC
* **Example:** Sign the zone
* ```typescript
* const dnssec = yield* Cloudflare.DNS.Dnssec("ZoneDnssec", {
* zoneId: zone.zoneId,
* });
* // Paste `dnssec.ds` at your registrar to complete activation.
* ```
*
* **Example:** Multi-signer DNSSEC
* ```typescript
* yield* Cloudflare.DNS.Dnssec("ZoneDnssec", {
* zoneId: zone.zoneId,
* dnssecMultiSigner: true,
* });
* ```
*
* ### Disabling DNSSEC
* **Example:** Keep DNSSEC explicitly off
* ```typescript
* yield* Cloudflare.DNS.Dnssec("ZoneDnssec", {
* zoneId: zone.zoneId,
* status: "disabled",
* });
* ```
*
* @resource
* @product DNS
* @category Domains & DNS
*/
export const Dnssec = Resource<Dnssec>(TypeId, {
aliases: ["Cloudflare.Dns.Dnssec"],
});
/**
* Returns true if the given value is a Dnssec resource.
*/
export const issec = (value: unknown): value is Dnssec =>
Predicate.hasProperty(value, "Type") && value.Type === TypeId;
export const DnssecProvider = () =>
Provider.succeed(Dnssec, {
stables: [
"zoneId",
"initialStatus",
"initialMultiSigner",
"initialPresigned",
"initialUseNsec3",
],
list: Effect.fn(function* () {
const { accountId } = yield* yield* CloudflareEnvironment;
// No account-wide API for this zone singleton — enumerate every
// zone in the account and read its DNSSEC config (every zone has
// one). Disabled zones are "not created" for this resource (same
// as a cold `read`), so they're skipped; the observed state of an
// active zone becomes its captured initial state.
const allZones = yield* listAllZones(accountId);
const rows = yield* Effect.forEach(
allZones.map((zone) => zone.id),
(zoneId) =>
dns.getDnssec({ zoneId }).pipe(
Effect.map((observed) =>
statusFamily(observed.status) === "disabled"
? undefined
: toAttributes(zoneId, observed, captureInitial(observed)),
),
// Plan-gated or partial zones reject the route; skip them.
Effect.catchTag("InvalidRoute", () => Effect.undefined),
),
{ concurrency: 10 },
);
return rows.filter((row): row is DnssecAttributes => row !== undefined);
}),
diff: Effect.fn(function* ({ olds = {}, news, output }) {
const o = olds as DnssecProps;
const n = news as DnssecProps;
// zoneId is the resource's identity (DNSSEC is a zone singleton).
// It 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;
}
return undefined;
}),
read: Effect.fn(function* ({ output, olds }) {
const zoneId = output?.zoneId ?? (typeof olds?.zoneId === "string" ? olds.zoneId : undefined);
if (!zoneId) return undefined;
const observed = yield* dns.getDnssec({ zoneId }).pipe(
// Zone deleted out-of-band — DNSSEC config is gone with it.
Effect.catchTag("InvalidRoute", () => Effect.undefined),
);
if (observed === undefined) return undefined;
if (output !== undefined) {
// Owned path — refresh, keeping the captured pre-management state.
return toAttributes(zoneId, observed, {
status: output.initialStatus,
multiSigner: output.initialMultiSigner,
presigned: output.initialPresigned,
useNsec3: output.initialUseNsec3,
});
}
// Cold read: DNSSEC disabled means "not created" for this resource.
if (statusFamily(observed.status) === "disabled") return undefined;
// DNSSEC is enabled but we have no state and no ownership markers
// exist — gate takeover behind the adopt policy.
return Unowned(toAttributes(zoneId, observed, captureInitial(observed)));
}),
reconcile: Effect.fn(function* ({ news, output }) {
// Inputs have been resolved to concrete strings by Plan.
const zoneId = news.zoneId as string;
const desiredStatus: DnssecDesiredStatus = news.status ?? "active";
// 1. Observe — DNSSEC config always exists for a live zone.
let observed = yield* dns.getDnssec({ zoneId });
// 2. Capture — the pre-management state, restored on destroy.
// `output` (including an adoption read) already carries it;
// otherwise this is our first touch.
const initial: InitialDnssec =
output !== undefined
? {
status: output.initialStatus,
multiSigner: output.initialMultiSigner,
presigned: output.initialPresigned,
useNsec3: output.initialUseNsec3,
}
: captureInitial(observed);
// 3. Sync — patch only when the observed state differs from the
// desired one.
if (!matchesDesired(observed, news, desiredStatus)) {
observed = yield* dns.patchDnssec({
zoneId,
status: desiredStatus,
dnssecMultiSigner: news.dnssecMultiSigner,
dnssecPresigned: news.dnssecPresigned,
dnssecUseNsec3: news.dnssecUseNsec3,
});
}
// 4. Wait — activation/deactivation is eventually consistent.
// Poll (bounded) for the status to reach the desired family;
// "active" is satisfied by `pending` since full activation
// requires the registrar-side DS record.
if (statusFamily(observed.status) !== desiredStatus) {
observed = yield* dns.getDnssec({ zoneId }).pipe(
Effect.repeat({
schedule: Schedule.spaced("2 seconds"),
until: (o) => statusFamily(o.status) === desiredStatus,
times: 15,
}),
);
}
return toAttributes(zoneId, observed, initial);
}),
delete: Effect.fn(function* ({ output }) {
const zoneId = output.zoneId;
// Observe — if the zone itself is gone, so is its DNSSEC config.
const observed = yield* dns
.getDnssec({ zoneId })
.pipe(Effect.catchTag("InvalidRoute", () => Effect.undefined));
if (observed === undefined) return;
if (output.initialStatus === "disabled") {
// The zone had DNSSEC off before we managed it — deactivate.
// Cloudflare's DELETE endpoint only clears DNSSEC records *after*
// signing has been disabled, so deactivation goes through PATCH.
// Skip the call when it's already off (idempotent re-delete).
if (statusFamily(observed.status) === "disabled") return;
yield* dns
.patchDnssec({ zoneId, status: "disabled" })
.pipe(Effect.catchTag("InvalidRoute", () => Effect.void));
return;
}
// The zone had DNSSEC on before we managed it — restore the
// enabled state and the flags it had at capture time.
if (
statusFamily(observed.status) === "active" &&
flag(observed.dnssecMultiSigner) === flag(output.initialMultiSigner) &&
flag(observed.dnssecPresigned) === flag(output.initialPresigned) &&
flag(observed.dnssecUseNsec3) === flag(output.initialUseNsec3)
) {
return;
}
yield* dns
.patchDnssec({
zoneId,
status: "active",
dnssecMultiSigner: output.initialMultiSigner,
dnssecPresigned: output.initialPresigned,
dnssecUseNsec3: output.initialUseNsec3,
})
.pipe(Effect.catchTag("InvalidRoute", () => Effect.void));
}),
});
interface InitialDnssec {
readonly status: DnssecDesiredStatus;
readonly multiSigner: boolean | undefined;
readonly presigned: boolean | undefined;
readonly useNsec3: boolean | undefined;
}
/**
* Collapse Cloudflare's five-state live status into the two-state
* desired family (`pending` is on its way to `active`,
* `pending-disabled` / `error` / unknown collapse to `disabled`).
*/
const statusFamily = (status: string | null | undefined): DnssecDesiredStatus =>
status === "active" || status === "pending" ? "active" : "disabled";
const flag = (v: boolean | null | undefined): boolean => v ?? false;
const captureInitial = (observed: dns.GetDnssecResponse): InitialDnssec => ({
status: statusFamily(observed.status),
multiSigner: observed.dnssecMultiSigner ?? undefined,
presigned: observed.dnssecPresigned ?? undefined,
useNsec3: observed.dnssecUseNsec3 ?? undefined,
});
const matchesDesired = (
observed: dns.GetDnssecResponse,
news: DnssecProps,
desiredStatus: DnssecDesiredStatus,
): boolean => {
if (statusFamily(observed.status) !== desiredStatus) return false;
if (
news.dnssecMultiSigner !== undefined &&
news.dnssecMultiSigner !== flag(observed.dnssecMultiSigner)
) {
return false;
}
if (
news.dnssecPresigned !== undefined &&
news.dnssecPresigned !== flag(observed.dnssecPresigned)
) {
return false;
}
if (news.dnssecUseNsec3 !== undefined && news.dnssecUseNsec3 !== flag(observed.dnssecUseNsec3)) {
return false;
}
return true;
};
const undef = <T>(v: T | null | undefined): T | undefined => (v == null ? undefined : v);
const toAttributes = (
zoneId: string,
observed: dns.GetDnssecResponse | dns.PatchDnssecResponse,
initial: InitialDnssec,
): DnssecAttributes => ({
zoneId,
status: observed.status ?? "disabled",
dnssecMultiSigner: undef(observed.dnssecMultiSigner),
dnssecPresigned: undef(observed.dnssecPresigned),
dnssecUseNsec3: undef(observed.dnssecUseNsec3),
algorithm: undef(observed.algorithm),
digest: undef(observed.digest),
digestAlgorithm: undef(observed.digestAlgorithm),
digestType: undef(observed.digestType),
ds: undef(observed.ds),
flags: undef(observed.flags),
keyTag: undef(observed.keyTag),
keyType: undef(observed.keyType),
publicKey: undef(observed.publicKey),
modifiedOn: undef(observed.modifiedOn),
initialStatus: initial.status,
initialMultiSigner: initial.multiSigner,
initialPresigned: initial.presigned,
initialUseNsec3: initial.useNsec3,
});