@jaggr2/cdk-cf-dns 0.1.0

package/lib/zone.js

@@ -0,0 +1,90 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CloudflareZone = void 0;
+const cdk = __importStar(require("aws-cdk-lib"));
+const constructs_1 = require("constructs");
+/**
+ * A reference to an existing Cloudflare zone.
+ *
+ * Zones are not created by this library; they must already exist in the
+ * Cloudflare account. Use `CloudflareZone.fromZoneId()` to reference one.
+ */
+class CloudflareZone extends constructs_1.Construct {
+    /**
+     * Reference an existing Cloudflare zone by its Zone ID.
+     *
+     * @param scope The scope in which to define this construct.
+     * @param id    The scoped construct ID.
+     * @param attrs The zone attributes.
+     */
+    static fromZoneId(scope, id, attrs) {
+        return new CloudflareZone(scope, id, attrs);
+    }
+    zoneId;
+    zoneName;
+    apiToken;
+    constructor(scope, id, attrs) {
+        super(scope, id);
+        if (attrs.zoneId === undefined || attrs.zoneId === '') {
+            throw new Error('CloudflareZone requires a zoneId');
+        }
+        if (attrs.apiToken === undefined) {
+            throw new Error('CloudflareZone requires an apiToken secret');
+        }
+        this.zoneId = validateNoToken(attrs.zoneId, 'zoneId');
+        this.zoneName = attrs.zoneName === undefined ? undefined : validateNoToken(attrs.zoneName, 'zoneName');
+        this.apiToken = attrs.apiToken;
+    }
+}
+exports.CloudflareZone = CloudflareZone;
+/**
+ * Validates a string value that may be a CDK token. Tokens are never validated
+ * with patterns (a regex would break on `${Token[...]}`); only the syntactic
+ * sanity of resolved values is checked.
+ */
+function validateNoToken(value, field) {
+    if (cdk.Token.isUnresolved(value)) {
+        return value;
+    }
+    if (value.length === 0) {
+        throw new Error(`CloudflareZone ${field} must not be empty`);
+    }
+    if (/[^A-Za-z0-9._-]/.test(value)) {
+        throw new Error(`CloudflareZone ${field} contains invalid characters: ${value}`);
+    }
+    return value;
+}
+//# sourceMappingURL=zone.js.map

package/lib/zone.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zone.js","sourceRoot":"","sources":["../src/zone.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,iDAAmC;AAEnC,2CAAuC;AA0DvC;;;;;GAKG;AACH,MAAa,cAAe,SAAQ,sBAAS;IAC3C;;;;;;OAMG;IACI,MAAM,CAAC,UAAU,CAAC,KAAgB,EAAE,EAAU,EAAE,KAA+B;QACpF,OAAO,IAAI,cAAc,CAAC,KAAK,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC;IAC9C,CAAC;IAEe,MAAM,CAAS;IACf,QAAQ,CAAU;IAClB,QAAQ,CAAyB;IAEjD,YAAoB,KAAgB,EAAE,EAAU,EAAE,KAA+B;QAC/E,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAEjB,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;YACtD,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;QACtD,CAAC;QACD,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YACjC,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;QAChE,CAAC;QAED,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,KAAK,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QACtD,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,KAAK,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QACvG,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;IACjC,CAAC;CACF;AA9BD,wCA8BC;AAED;;;;GAIG;AACH,SAAS,eAAe,CAAC,KAAa,EAAE,KAAa;IACnD,IAAI,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;QAClC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,kBAAkB,KAAK,oBAAoB,CAAC,CAAC;IAC/D,CAAC;IACD,IAAI,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,kBAAkB,KAAK,iCAAiC,KAAK,EAAE,CAAC,CAAC;IACnF,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@jaggr2/cdk-cf-dns",
+  "version": "0.1.0",
+  "description": "Manage Cloudflare DNS records as CloudFormation resources from AWS CDK, so Route 53 hosted zones are no longer needed.",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib",
+    "src",
+    "API.md"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "aws",
+    "cdk",
+    "cloudformation",
+    "cloudflare",
+    "dns",
+    "route53"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jaggr2/cdk-cf-dns.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc -w",
+    "test": "jest",
+    "test:update": "jest -u",
+    "lint": "eslint . --ext .ts",
+    "docs": "ts-node scripts/generate-api-md.ts",
+    "package": "npm run build && npm pack"
+  },
+  "peerDependencies": {
+    "aws-cdk-lib": "^2.x",
+    "constructs": "^10.x"
+  },
+  "devDependencies": {
+    "@aws-sdk/client-acm": "^3.700.0",
+    "@aws-sdk/client-secrets-manager": "^3.700.0",
+    "@types/aws-lambda": "^8.10.162",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.10.5",
+    "@typescript-eslint/eslint-plugin": "^8.20.0",
+    "@typescript-eslint/parser": "^8.20.0",
+    "aws-cdk-lib": "^2.180.0",
+    "constructs": "^10.8.1",
+    "esbuild": "^0.28.2",
+    "eslint": "^8.57.1",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.5",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  }
+}

package/src/certificate.ts

@@ -0,0 +1,74 @@
+import * as acm from 'aws-cdk-lib/aws-certificatemanager';
+import * as cdk from 'aws-cdk-lib';
+import { Construct } from 'constructs';
+import { CloudflareCertificateProvider } from './provider';
+import { ICloudflareZone } from './zone';
+
+/**
+ * Properties for a Cloudflare-validated ACM certificate.
+ */
+export interface CloudflareValidatedCertificateProps {
+  /**
+   * The primary domain name the certificate covers.
+   */
+  readonly domainName: string;
+
+  /**
+   * Additional domain names the certificate should cover.
+   *
+   * @default - no additional names
+   */
+  readonly subjectAlternativeNames?: string[];
+
+  /**
+   * The Cloudflare zone where the DNS validation CNAMEs are written.
+   */
+  readonly zone: ICloudflareZone;
+}
+
+/**
+ * An ACM certificate whose DNS validation records are written into Cloudflare
+ * automatically, removing the manual copy-paste step.
+ *
+ * CloudFormation does not expose the validation `ResourceRecord` as a
+ * certificate attribute, so a custom resource calls `acm:DescribeCertificate`,
+ * polls until the records are populated (they are absent for a few seconds
+ * after creation), and writes each unique CNAME into Cloudflare.
+ *
+ * Note: if the certificate is attached to CloudFront it must live in
+ * `us-east-1`; this construct does not solve cross-region certificates.
+ */
+export class CloudflareValidatedCertificate extends Construct {
+  /**
+   * The underlying ACM certificate.
+   */
+  public readonly certificate: acm.Certificate;
+
+  public constructor(scope: Construct, id: string, props: CloudflareValidatedCertificateProps) {
+    super(scope, id);
+
+    // Create the certificate with DNS validation but no hosted zone: the
+    // validation records are written to Cloudflare by the custom resource.
+    this.certificate = new acm.Certificate(this, 'Certificate', {
+      domainName: props.domainName,
+      subjectAlternativeNames: props.subjectAlternativeNames,
+      validation: acm.CertificateValidation.fromDns(),
+    });
+
+    const provider = CloudflareCertificateProvider.getOrCreate(this);
+    provider.grantSecretRead(props.zone.apiToken);
+
+    const validation = new cdk.CustomResource(this, 'DnsValidation', {
+      serviceToken: provider.serviceToken,
+      resourceType: 'Custom::CloudflareCertificateDnsValidation',
+      properties: {
+        certificateArn: this.certificate.certificateArn,
+        zoneId: props.zone.zoneId,
+        apiTokenSecretArn: props.zone.apiToken.secretArn,
+      },
+    });
+
+    // The validation resource can only read records once the certificate exists.
+    validation.node.addDependency(this.certificate);
+  }
+}

package/src/handler/acm.ts

@@ -0,0 +1,160 @@
+import { ACMClient, DescribeCertificateCommand } from '@aws-sdk/client-acm';
+import type { CloudFormationCustomResourceCreateEvent, CloudFormationCustomResourceDeleteEvent, CloudFormationCustomResourceEvent, CloudFormationCustomResourceUpdateEvent } from 'aws-lambda';
+import { assertSuccess, findRecord, getApiToken, isAlreadyExists, log, request } from './cloudflare';
+
+const acmClient = new ACMClient({});
+
+/**
+ * A single ACM DNS validation CNAME (name/value pair).
+ */
+interface ValidationRecord {
+  name: string;
+  value: string;
+}
+
+/**
+ * Sleeps for the given number of milliseconds.
+ */
+async function sleep(ms: number): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Describes the certificate and returns the deduplicated DNS validation records
+ * that ACM currently exposes. A wildcard SAN and its apex share one record, so
+ * records are deduplicated on the name/value pair.
+ */
+async function describeValidationRecords(certificateArn: string): Promise<ValidationRecord[]> {
+  const response = await acmClient.send(new DescribeCertificateCommand({ CertificateArn: certificateArn }));
+  const options = response.Certificate?.DomainValidationOptions ?? [];
+  const records: ValidationRecord[] = [];
+
+  for (const option of options) {
+    const resourceRecord = option.ResourceRecord;
+    if (resourceRecord?.Name && resourceRecord.Value) {
+      const name = resourceRecord.Name.replace(/\.$/, '');
+      const value = resourceRecord.Value.replace(/\.$/, '');
+      const duplicate = records.some((r) => r.name === name && r.value === value);
+      if (!duplicate) {
+        records.push({ name, value });
+      }
+    }
+  }
+
+  return records;
+}
+
+/**
+ * Polls ACM until the validation `ResourceRecord`s are populated. They are
+ * absent for a few seconds after the certificate is created, so the handler
+ * retries until they appear or the deadline is reached.
+ */
+async function pollValidationRecords(
+  certificateArn: string,
+  delaySeconds: number,
+  timeoutSeconds: number,
+): Promise<ValidationRecord[]> {
+  const deadline = Date.now() + timeoutSeconds * 1000;
+
+  while (Date.now() < deadline) {
+    const records = await describeValidationRecords(certificateArn);
+    if (records.length > 0) {
+      return records;
+    }
+    await sleep(delaySeconds * 1000);
+  }
+
+  throw new Error(`Timed out waiting for ACM DNS validation records for ${certificateArn}`);
+}
+
+/**
+ * Creates (or adopts) a CNAME validation record in Cloudflare. Validation
+ * records must never be proxied and must use a plain TTL.
+ */
+async function upsertCname(zoneId: string, name: string, value: string, token: string): Promise<void> {
+  const payload: Record<string, unknown> = {
+    name,
+    type: 'CNAME',
+    content: value,
+    ttl: 60,
+    proxied: false,
+  };
+
+  const response = await request(`/zones/${zoneId}/dns_records`, { method: 'POST', token, body: payload });
+
+  if (isAlreadyExists(response)) {
+    log('validation', { message: 'validation record already exists; adopting', zoneId, name });
+    const existing = await findRecord(zoneId, name, 'CNAME', token);
+    if (!existing) {
+      throw new Error(`Cloudflare reported ${name} already exists but the lookup found no matching record`);
+    }
+    await request(`/zones/${zoneId}/dns_records/${existing.id}`, { method: 'PATCH', token, body: payload });
+    return;
+  }
+
+  assertSuccess(response);
+}
+
+/**
+ * Handles both `Create` and `Update`: reads the certificate's validation
+ * records from ACM and writes each unique CNAME into Cloudflare.
+ */
+async function onUpsert(
+  event: CloudFormationCustomResourceCreateEvent | CloudFormationCustomResourceUpdateEvent,
+): Promise<{ PhysicalResourceId: string; Data: Record<string, unknown> }> {
+  const properties = event.ResourceProperties as Record<string, unknown>;
+  const certificateArn = String(properties.certificateArn);
+  const zoneId = String(properties.zoneId);
+  const token = await getApiToken(String(properties.apiTokenSecretArn));
+  const delaySeconds = Number(properties.pollDelaySeconds ?? 5);
+  const timeoutSeconds = Number(properties.pollTimeoutSeconds ?? 120);
+
+  log('validation', { certificateArn, zoneId });
+
+  const records = await pollValidationRecords(certificateArn, delaySeconds, timeoutSeconds);
+  for (const record of records) {
+    await upsertCname(zoneId, record.name, record.value, token);
+  }
+
+  log('validation', { message: `wrote ${records.length} validation record(s)`, names: records.map((r) => r.name) });
+  return {
+    PhysicalResourceId: certificateArn,
+    Data: { ValidationRecords: records.map((r) => r.name) },
+  };
+}
+
+/**
+ * Handles `Delete`. The validation CNAMEs are left in Cloudflare — they are
+ * harmless after issuance and cleaning them up would add fragile delete logic.
+ */
+async function onDelete(event: CloudFormationCustomResourceDeleteEvent): Promise<{ PhysicalResourceId: string; Data: Record<string, unknown> }> {
+  log('validation', { message: 'delete; leaving validation records in Cloudflare' });
+  return { PhysicalResourceId: event.PhysicalResourceId, Data: {} };
+}
+
+/**
+ * The Lambda handler for the `Custom::CloudflareCertificateDnsValidation`
+ * custom resource.
+ *
+ * @param event The CloudFormation custom resource event.
+ * @returns The custom resource result with `PhysicalResourceId` and `Data`.
+ */
+export async function handler(event: CloudFormationCustomResourceEvent): Promise<{ PhysicalResourceId: string; Data: Record<string, unknown> }> {
+  try {
+    log('event', { requestType: event.RequestType });
+
+    switch (event.RequestType) {
+      case 'Create':
+        return await onUpsert(event);
+      case 'Update':
+        return await onUpsert(event);
+      case 'Delete':
+        return await onDelete(event);
+      default:
+        throw new Error(`Unsupported RequestType: ${(event as { RequestType?: string }).RequestType}`);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Cloudflare ACM DNS validation custom resource failed during ${event.RequestType}: ${message}`);
+  }
+}

package/src/handler/cloudflare.ts

@@ -0,0 +1,305 @@
+import { GetSecretValueCommand, SecretsManagerClient } from '@aws-sdk/client-secrets-manager';
+
+/**
+ * Shared helpers for the Lambda handlers. This module is bundled into each
+ * handler entry point by esbuild; it is never imported by CDK library code.
+ */
+
+/**
+ * The base URL for the Cloudflare API v4.
+ */
+export const CF_BASE_URL = 'https://api.cloudflare.com/client/v4';
+
+/**
+ * How many attempts the retrying HTTP helper makes before giving up.
+ */
+export const MAX_ATTEMPTS = 5;
+
+/**
+ * Base backoff delay in milliseconds, doubled each attempt with full jitter.
+ */
+export const BACKOFF_BASE_MS = 500;
+
+/**
+ * Upper bound for a single backoff sleep in milliseconds.
+ */
+export const BACKOFF_CAP_MS = 4000;
+
+/**
+ * A regular expression matching strings that look like Cloudflare credentials
+ * (API tokens are 40 characters, global API keys 37). Anything matching is
+ * redacted from logs.
+ */
+const TOKEN_PATTERN = /[A-Za-z0-9_-]{37,}/g;
+
+/**
+ * Cloudflare record IDs are 32 lowercase hex characters.
+ */
+export const RECORD_ID_PATTERN = /^[a-f0-9]{32}$/;
+
+/**
+ * The shape of a Cloudflare API response envelope.
+ */
+export interface CloudflareResponse {
+  success: boolean;
+  errors: Array<{ code: number; message: string }>;
+  messages: Array<{ code: number; message: string }>;
+  result: unknown;
+}
+
+/**
+ * A DNS record as returned by the Cloudflare API.
+ */
+export interface CloudflareDnsRecord {
+  id: string;
+  name: string;
+  type: string;
+}
+
+const secretCache = new Map<string, string>();
+let secretsClient: SecretsManagerClient | undefined;
+
+/**
+ * Redacts strings that look like Cloudflare credentials (and known token
+ * values) from arbitrary log payloads.
+ *
+ * @param value The value to redact.
+ * @returns A copy of `value` with token-shaped strings replaced.
+ */
+export function redact(value: unknown): unknown {
+  if (typeof value === 'string') {
+    return value.replace(TOKEN_PATTERN, '[REDACTED]');
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => redact(item));
+  }
+  if (value !== null && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [key, item] of Object.entries(value)) {
+      out[key] = redact(item);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Logs a message to CloudWatch with all token-shaped strings redacted.
+ */
+export function log(...args: unknown[]): void {
+  console.log(...args.map((arg) => redact(arg)));
+}
+
+/**
+ * Resolves the Cloudflare API token from Secrets Manager, caching it per ARN so
+ * warm invocations skip the API call. Supports the secret being either a raw
+ * string or a JSON blob with an `apiToken` key.
+ *
+ * @param secretArn The ARN of the secret holding the token.
+ */
+export async function getApiToken(secretArn: string): Promise<string> {
+  const cached = secretCache.get(secretArn);
+  if (cached !== undefined) {
+    return cached;
+  }
+
+  if (!secretsClient) {
+    secretsClient = new SecretsManagerClient({});
+  }
+
+  const response = await secretsClient.send(new GetSecretValueCommand({ SecretId: secretArn }));
+  const secretString = response.SecretString;
+  if (secretString === undefined) {
+    throw new Error(`Secret ${secretArn} has no SecretString; store the API token as a raw string or a JSON blob with an "apiToken" key`);
+  }
+
+  let token = secretString;
+  try {
+    const parsed: unknown = JSON.parse(secretString);
+    if (parsed !== null && typeof parsed === 'object' && typeof (parsed as Record<string, unknown>).apiToken === 'string') {
+      token = (parsed as Record<string, unknown>).apiToken as string;
+    }
+  } catch {
+    // Not JSON: treat the raw string as the token.
+  }
+
+  if (token.length === 0) {
+    throw new Error(`Secret ${secretArn} resolved to an empty API token`);
+  }
+
+  secretCache.set(secretArn, token);
+  return token;
+}
+
+/**
+ * A Cloudflare API error, carrying the HTTP status and the error payload so the
+ * lifecycle logic can inspect specific error codes.
+ */
+export class CloudflareApiError extends Error {
+  public readonly status: number;
+  public readonly errors: Array<{ code: number; message: string }>;
+
+  public constructor(status: number, errors: Array<{ code: number; message: string }>) {
+    const details = errors.map((error) => `${error.code}: ${error.message}`).join('; ');
+    super(`Cloudflare API error (HTTP ${status}): ${String(redact(details))}`);
+    this.status = status;
+    this.errors = errors;
+  }
+}
+
+/**
+ * Performs an HTTP request against the Cloudflare API with retries.
+ *
+ * Retries with exponential backoff + full jitter on HTTP 429, 5xx and network
+ * errors, honouring the `Retry-After` header when present.
+ *
+ * @param path    The API path, e.g. `/zones/{id}/dns_records`.
+ * @param options Request options. A resolved token is sent as `token`.
+ */
+export async function request(
+  path: string,
+  options: { method: string; token?: string; body?: unknown },
+): Promise<{ status: number; body: CloudflareResponse }> {
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+  };
+  if (options.token !== undefined) {
+    headers['Authorization'] = `Bearer ${options.token}`;
+  }
+
+  const url = `${CF_BASE_URL}${path}`;
+  const body = options.body === undefined ? undefined : JSON.stringify(options.body);
+
+  let lastError: Error | undefined;
+
+  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+    try {
+      const response = await fetch(url, {
+        method: options.method,
+        headers,
+        body,
+      });
+
+      const text = await response.text();
+      let parsed: CloudflareResponse;
+      try {
+        parsed = JSON.parse(text) as CloudflareResponse;
+      } catch {
+        parsed = {
+          success: false,
+          errors: [{ code: 0, message: `Non-JSON response (HTTP ${response.status}): ${truncate(text, 500)}` }],
+          messages: [],
+          result: null,
+        };
+      }
+
+      const retryable = response.status === 429 || response.status >= 500;
+      if (retryable && attempt < MAX_ATTEMPTS - 1) {
+        await sleepForRetry(response, attempt);
+        continue;
+      }
+
+      return { status: response.status, body: parsed };
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+      if (attempt < MAX_ATTEMPTS - 1) {
+        log('retry', { path, attempt, reason: `network error: ${lastError.message}` });
+        await sleepForRetry(undefined, attempt);
+      }
+    }
+  }
+
+  throw lastError ?? new Error(`Request to ${path} failed after ${MAX_ATTEMPTS} attempts`);
+}
+
+/**
+ * Sleeps for a backoff interval, honouring `Retry-After` when the server
+ * provided one and otherwise using exponential backoff with full jitter.
+ */
+async function sleepForRetry(response: Response | undefined, attempt: number): Promise<void> {
+  let delayMs: number;
+
+  const retryAfter = response?.headers.get('Retry-After');
+  if (retryAfter !== null && retryAfter !== undefined) {
+    const seconds = Number.parseInt(retryAfter, 10);
+    delayMs = Number.isFinite(seconds) ? Math.min(seconds * 1000, BACKOFF_CAP_MS) : BACKOFF_CAP_MS;
+  } else {
+    const cap = Math.min(BACKOFF_CAP_MS, BACKOFF_BASE_MS * 2 ** attempt);
+    delayMs = Math.random() * cap;
+  }
+
+  await new Promise((resolve) => setTimeout(resolve, delayMs));
+}
+
+/**
+ * Truncates a long string for inclusion in an error message.
+ */
+function truncate(value: string, max: number): string {
+  return value.length > max ? `${value.slice(0, max)}...` : value;
+}
+
+/**
+ * Throws a descriptive error when the Cloudflare response has `success: false`.
+ */
+export function assertSuccess(response: { status: number; body: CloudflareResponse }): void {
+  if (!response.body.success) {
+    throw new CloudflareApiError(response.status, response.body.errors);
+  }
+}
+
+/**
+ * Returns true when the response indicates the record already exists.
+ */
+export function isAlreadyExists(response: { status: number; body: CloudflareResponse }): boolean {
+  if (response.body.success) {
+    return false;
+  }
+  return response.body.errors.some((error) => {
+    const codeMatches = error.code === 81053 || error.code === 81057;
+    const messageMatches = /already exists/i.test(error.message);
+    return codeMatches || messageMatches;
+  });
+}
+
+/**
+ * Returns true when the response indicates the record no longer exists.
+ */
+export function isRecordDoesNotExist(response: { status: number; body: CloudflareResponse }): boolean {
+  return response.body.errors.some((error) => error.code === 81044);
+}
+
+/**
+ * Builds the DNS record payload sent to the Cloudflare API from the custom
+ * resource properties.
+ */
+export function buildRecordPayload(properties: Record<string, unknown>): Record<string, unknown> {
+  const record = (properties.record ?? {}) as Record<string, unknown>;
+  const payload: Record<string, unknown> = {};
+
+  for (const key of ['name', 'type', 'content', 'data', 'ttl', 'proxied', 'priority', 'comment', 'tags']) {
+    if (record[key] !== undefined) {
+      payload[key] = record[key];
+    }
+  }
+
+  return payload;
+}
+
+/**
+ * Creates a DNS record and returns the Cloudflare record.
+ */
+export async function createRecord(zoneId: string, payload: Record<string, unknown>, token: string): Promise<CloudflareDnsRecord> {
+  const response = await request(`/zones/${zoneId}/dns_records`, { method: 'POST', token, body: payload });
+  assertSuccess(response);
+  return response.body.result as CloudflareDnsRecord;
+}
+
+/**
+ * Looks up a record by name and type in the zone.
+ */
+export async function findRecord(zoneId: string, name: string, type: string, token: string): Promise<CloudflareDnsRecord | undefined> {
+  const response = await request(`/zones/${zoneId}/dns_records?name=${encodeURIComponent(name)}&type=${type}`, { method: 'GET', token });
+  assertSuccess(response);
+  const results = response.body.result as CloudflareDnsRecord[];
+  return results[0];
+}