@jaggr2/cdk-cf-dns 0.1.0

package/src/handler/deps.lock.json

@@ -0,0 +1,3 @@
+{
+  "lockfileVersion": 3
+}

package/src/handler/index.ts

@@ -0,0 +1,145 @@
+import type { CloudFormationCustomResourceCreateEvent, CloudFormationCustomResourceDeleteEvent, CloudFormationCustomResourceEvent, CloudFormationCustomResourceUpdateEvent } from 'aws-lambda';
+import {
+  assertSuccess,
+  buildRecordPayload,
+  createRecord,
+  findRecord,
+  getApiToken,
+  isAlreadyExists,
+  isRecordDoesNotExist,
+  log,
+  RECORD_ID_PATTERN,
+  request,
+} from './cloudflare';
+
+/**
+ * Handles the `Create` request type.
+ */
+async function onCreate(event: CloudFormationCustomResourceCreateEvent): Promise<{ PhysicalResourceId: string; Data: Record<string, unknown> }> {
+  const properties = event.ResourceProperties as Record<string, unknown>;
+  const zoneId = String(properties.zoneId);
+  const payload = buildRecordPayload(properties);
+  const token = await getApiToken(String(properties.apiTokenSecretArn));
+
+  log('create', { zoneId, name: payload.name, type: payload.type });
+
+  const response = await request(`/zones/${zoneId}/dns_records`, { method: 'POST', token, body: payload });
+
+  if (isAlreadyExists(response)) {
+    if (!properties.adoptExisting) {
+      throw new Error(
+        `DNS record ${String(payload.name)} (${String(payload.type)}) already exists in zone ${zoneId}. ` +
+          'Either delete it in the Cloudflare dashboard, or set adoptExisting: true to adopt and manage it.',
+      );
+    }
+
+    log('adopt', { zoneId, name: payload.name, type: payload.type });
+    const existing = await findRecord(zoneId, String(payload.name), String(payload.type), token);
+    if (!existing) {
+      throw new Error(`Cloudflare reported ${String(payload.name)} already exists but the lookup found no matching record`);
+    }
+
+    await request(`/zones/${zoneId}/dns_records/${existing.id}`, { method: 'PATCH', token, body: payload });
+    return { PhysicalResourceId: existing.id, Data: { RecordId: existing.id, DomainName: existing.name } };
+  }
+
+  assertSuccess(response);
+  const result = response.body.result as { id: string; name: string };
+  return { PhysicalResourceId: result.id, Data: { RecordId: result.id, DomainName: result.name } };
+}
+
+/**
+ * Handles the `Update` request type.
+ */
+async function onUpdate(event: CloudFormationCustomResourceUpdateEvent): Promise<{ PhysicalResourceId: string; Data: Record<string, unknown> }> {
+  const properties = event.ResourceProperties as Record<string, unknown>;
+  const oldProperties = event.OldResourceProperties as Record<string, unknown>;
+  const zoneId = String(properties.zoneId);
+  const payload = buildRecordPayload(properties);
+  const token = await getApiToken(String(properties.apiTokenSecretArn));
+
+  log('update', { zoneId, name: payload.name, type: payload.type });
+
+  // If the zone changed, the record must be created in the new zone. Returning a
+  // new physical id tells CloudFormation to send a Delete for the old one.
+  if (String(oldProperties.zoneId) !== zoneId) {
+    log('update', { message: 'zone changed; creating in new zone', zoneId });
+    const created = await createRecord(zoneId, payload, token);
+    return { PhysicalResourceId: created.id, Data: { RecordId: created.id, DomainName: created.name } };
+  }
+
+  const physicalId = event.PhysicalResourceId;
+  const response = await request(`/zones/${zoneId}/dns_records/${physicalId}`, { method: 'PATCH', token, body: payload });
+
+  // The record was deleted out-of-band (e.g. in the dashboard); recreate it.
+  if (response.status === 404 || (response.body.success === false && isRecordDoesNotExist(response))) {
+    log('update', { message: 'record not found; recreating', zoneId, name: payload.name });
+    const created = await createRecord(zoneId, payload, token);
+    return { PhysicalResourceId: created.id, Data: { RecordId: created.id, DomainName: created.name } };
+  }
+
+  assertSuccess(response);
+  const result = response.body.result as { id: string; name: string };
+  return { PhysicalResourceId: physicalId, Data: { RecordId: result.id, DomainName: result.name } };
+}
+
+/**
+ * Handles the `Delete` request type. Deleting is idempotent: a missing record
+ * is treated as success so stacks never become undeletable.
+ */
+async function onDelete(event: CloudFormationCustomResourceDeleteEvent): Promise<{ PhysicalResourceId: string; Data: Record<string, unknown> }> {
+  const properties = event.ResourceProperties as Record<string, unknown>;
+  const zoneId = String(properties.zoneId);
+  const physicalId = event.PhysicalResourceId;
+
+  if (properties.retainOnDelete) {
+    log('delete', { message: 'retainOnDelete set; leaving record in Cloudflare', zoneId });
+    return { PhysicalResourceId: physicalId, Data: {} };
+  }
+
+  // A failed Create can leave CloudFormation's arn:... placeholder as the
+  // physical id; never throw in that case.
+  if (!RECORD_ID_PATTERN.test(physicalId)) {
+    log('delete', { message: 'physical id is not a Cloudflare record id; skipping delete', physicalId });
+    return { PhysicalResourceId: physicalId, Data: {} };
+  }
+
+  const token = await getApiToken(String(properties.apiTokenSecretArn));
+  log('delete', { zoneId, physicalId });
+
+  const response = await request(`/zones/${zoneId}/dns_records/${physicalId}`, { method: 'DELETE', token });
+
+  if (response.status === 404 || (response.body.success === false && isRecordDoesNotExist(response))) {
+    log('delete', { message: 'record already gone; treating delete as success', physicalId });
+    return { PhysicalResourceId: physicalId, Data: {} };
+  }
+
+  assertSuccess(response);
+  return { PhysicalResourceId: physicalId, Data: {} };
+}
+
+/**
+ * The Lambda handler for the `Custom::CloudflareDnsRecord` 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 onCreate(event);
+      case 'Update':
+        return await onUpdate(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 DNS custom resource failed during ${event.RequestType}: ${message}`);
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './zone';
+export * from './record';
+export * from './provider';
+export * from './certificate';

package/src/provider.ts

@@ -0,0 +1,223 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as cdk from 'aws-cdk-lib';
+import * as iam from 'aws-cdk-lib/aws-iam';
+import * as lambda from 'aws-cdk-lib/aws-lambda';
+import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
+import * as logs from 'aws-cdk-lib/aws-logs';
+import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager';
+import * as custom_resources from 'aws-cdk-lib/custom-resources';
+import { Construct } from 'constructs';
+
+/**
+ * The stable construct ID used for the shared DNS provider on each Stack.
+ */
+const PROVIDER_ID = 'AcmeCloudflareDnsProvider';
+
+/**
+ * The stable construct ID used for the shared ACM provider on each Stack.
+ */
+const CERTIFICATE_PROVIDER_ID = 'AcmeCloudflareCertificateProvider';
+
+/**
+ * Resolves a handler entry point. When the library is consumed from the
+ * compiled `lib/` output the source lives at `<package>/src/handler/<file>`;
+ * when tests run against `src/` directly it is at `src/handler/<file>`.
+ */
+function handlerEntry(file: string): string {
+  const fromLib = path.join(__dirname, '..', 'src', 'handler', file);
+  if (fs.existsSync(fromLib)) {
+    return fromLib;
+  }
+  return path.join(__dirname, 'handler', file);
+}
+
+/**
+ * Creates the shared handler function with the provider's standard
+ * configuration: Node 22 on ARM, 256 MB, a one-month log group that is deleted
+ * with the stack, and an esbuild bundle with the AWS SDK kept external.
+ */
+function createHandler(scope: Construct, id: string, file: string, timeout: cdk.Duration): { handler: NodejsFunction; role: iam.IRole } {
+  // `NodejsFunction` requires its entry (and lock file) to live under
+  // `projectRoot`. The library is consumed from a different project, so both
+  // are pointed at the package's own root. The handler has no runtime npm
+  // dependencies, so the shipped `deps.lock.json` marker is never actually
+  // read — it only satisfies the path validation.
+  const projectRoot = path.join(__dirname, '..');
+
+  const handler = new NodejsFunction(scope, id, {
+    entry: handlerEntry(file),
+    projectRoot,
+    depsLockFilePath: path.join(projectRoot, 'src', 'handler', 'deps.lock.json'),
+    runtime: lambda.Runtime.NODEJS_22_X,
+    architecture: lambda.Architecture.ARM_64,
+    timeout,
+    memorySize: 256,
+    bundling: {
+      minify: true,
+      sourceMap: true,
+      externalModules: ['@aws-sdk/*'],
+    },
+  });
+
+  const logGroup = new logs.LogGroup(scope, `${id}LogGroup`, {
+    logGroupName: `/aws/lambda/${handler.functionName}`,
+    retention: logs.RetentionDays.ONE_MONTH,
+    removalPolicy: cdk.RemovalPolicy.DESTROY,
+  });
+  logGroup.node.addDependency(handler);
+
+  if (!handler.role) {
+    throw new Error(`Cloudflare provider handler ${id} requires an IAM role`);
+  }
+
+  return { handler, role: handler.role };
+}
+
+/**
+ * The shared custom-resource provider that performs the Cloudflare DNS API
+ * calls.
+ *
+ * One instance exists per stack (a singleton keyed by `Stack`), so a stack with
+ * many records still has exactly one Lambda handler. All records route their
+ * custom-resource events through this handler.
+ */
+export class CloudflareDnsProvider extends Construct {
+  /**
+   * Gets (or lazily creates) the provider for the stack of `scope`.
+   *
+   * @param scope Any construct within the stack that should own the provider.
+   */
+  public static getOrCreate(scope: Construct): CloudflareDnsProvider {
+    const stack = cdk.Stack.of(scope);
+    const existing = stack.node.tryFindChild(PROVIDER_ID) as CloudflareDnsProvider | undefined;
+    if (existing) {
+      return existing;
+    }
+    return new CloudflareDnsProvider(stack, PROVIDER_ID);
+  }
+
+  /**
+   * The custom-resource service token that records use as their `serviceToken`.
+   */
+  public readonly serviceToken: string;
+
+  /**
+   * The IAM role used by the handler. Record constructs grant `GetSecretValue`
+   * on their zone's secret here.
+   */
+  private readonly handlerRole: iam.IRole;
+
+  /**
+   * Secrets that have already been granted, deduplicated by ARN.
+   */
+  private readonly grantedSecrets: Set<string> = new Set();
+
+  private constructor(scope: Construct, id: string) {
+    super(scope, id);
+
+    const { handler, role } = createHandler(this, 'Handler', 'index.ts', cdk.Duration.minutes(2));
+
+    const provider = new custom_resources.Provider(this, 'Provider', {
+      onEventHandler: handler,
+    });
+
+    this.serviceToken = provider.serviceToken;
+    this.handlerRole = role;
+  }
+
+  /**
+   * Grants the provider's handler `secretsmanager:GetSecretValue` on the given
+   * secret. Repeated grants of the same secret are deduplicated.
+   *
+   * @param secret The secret holding a Cloudflare API token.
+   */
+  public grantSecretRead(secret: secretsmanager.ISecret): void {
+    const arn = secret.secretArn;
+    if (this.grantedSecrets.has(arn)) {
+      return;
+    }
+    this.grantedSecrets.add(arn);
+    this.handlerRole.addToPrincipalPolicy(new iam.PolicyStatement({
+      actions: ['secretsmanager:GetSecretValue'],
+      resources: [arn],
+    }));
+  }
+}
+
+/**
+ * The shared custom-resource provider that writes ACM DNS validation records
+ * into Cloudflare.
+ *
+ * Like `CloudflareDnsProvider`, one instance exists per stack. It additionally
+ * grants its handler `acm:DescribeCertificate` on all certificates.
+ */
+export class CloudflareCertificateProvider extends Construct {
+  /**
+   * Gets (or lazily creates) the provider for the stack of `scope`.
+   *
+   * @param scope Any construct within the stack that should own the provider.
+   */
+  public static getOrCreate(scope: Construct): CloudflareCertificateProvider {
+    const stack = cdk.Stack.of(scope);
+    const existing = stack.node.tryFindChild(CERTIFICATE_PROVIDER_ID) as CloudflareCertificateProvider | undefined;
+    if (existing) {
+      return existing;
+    }
+    return new CloudflareCertificateProvider(stack, CERTIFICATE_PROVIDER_ID);
+  }
+
+  /**
+   * The custom-resource service token that the certificate construct uses as
+   * its `serviceToken`.
+   */
+  public readonly serviceToken: string;
+
+  /**
+   * The IAM role used by the handler.
+   */
+  private readonly handlerRole: iam.IRole;
+
+  /**
+   * Secrets that have already been granted, deduplicated by ARN.
+   */
+  private readonly grantedSecrets: Set<string> = new Set();
+
+  private constructor(scope: Construct, id: string) {
+    super(scope, id);
+
+    // ACM validation records can take a while to appear after certificate
+    // creation, so the handler gets a generous timeout to poll for them.
+    const { handler, role } = createHandler(this, 'Handler', 'acm.ts', cdk.Duration.minutes(5));
+
+    role.addToPrincipalPolicy(new iam.PolicyStatement({
+      actions: ['acm:DescribeCertificate'],
+      resources: ['*'],
+    }));
+
+    const provider = new custom_resources.Provider(this, 'Provider', {
+      onEventHandler: handler,
+    });
+
+    this.serviceToken = provider.serviceToken;
+    this.handlerRole = role;
+  }
+
+  /**
+   * Grants the provider's handler `secretsmanager:GetSecretValue` on the given
+   * secret. Repeated grants of the same secret are deduplicated.
+   *
+   * @param secret The secret holding a Cloudflare API token.
+   */
+  public grantSecretRead(secret: secretsmanager.ISecret): void {
+    const arn = secret.secretArn;
+    if (this.grantedSecrets.has(arn)) {
+      return;
+    }
+    this.grantedSecrets.add(arn);
+    this.handlerRole.addToPrincipalPolicy(new iam.PolicyStatement({
+      actions: ['secretsmanager:GetSecretValue'],
+      resources: [arn],
+    }));
+  }
+}