@fjall/components-infrastructure 36.0.0 → 38.0.0

package/dist/lib/app.d.ts

@@ -211,6 +211,34 @@ export declare class App extends CdkApp {
      * Custom::CrossRegionExportWriter/Reader pair is pinned by template test.
      */
     getUsEast1CertificateStack(): AwsStack;
+    /**
+     * Retrieve the app-owned us-east-1 CloudFront logging stack — named
+     * `${this.name}UsEast1CdnLogging`.
+     *
+     * CloudWatch Logs accepts CloudFront standard-logging (v2) delivery
+     * sources, destinations and deliveries in us-east-1 only, so a logging
+     * CDN whose app deploys to another region creates them here; the
+     * distribution ARN and the log bucket ARN reach this stack through CDK
+     * cross-region references, which makes it a CONSUMER of the Cdn stack —
+     * it deploys after the Cdn stack and is destroyed before it, the mirror
+     * of the certificate stack. A CDN in a us-east-1 app never creates it.
+     *
+     * Everything crossing the boundary is a value the export writer requires
+     * stable under an unchanged logical id: the distribution ARN and the
+     * bucket ARN both are. Never route a per-synth value (a timestamp, an
+     * asset hash) through this stack's references.
+     */
+    getUsEast1CdnLoggingStack(): AwsStack;
+    /**
+     * The two us-east-1 stacks share a shape: no stack dependencies of their
+     * own (the CDK cross-region reference adds the consumer→producer edge),
+     * env-pinned to the deploying account (cross-region references resolve
+     * only between env-pinned stacks) and `crossRegionReferences: true` — the
+     * flag must be on BOTH the producing and the consuming stack, and the
+     * emitted Custom::CrossRegionExportWriter/Reader pair is pinned by
+     * template test.
+     */
+    private getUsEast1Stack;
     /**
      * Get a VPC by name. If no name is provided, returns the default VPC.
      *

package/dist/lib/app.js

@@ -312,11 +312,43 @@ export class App extends CdkApp {
      * Custom::CrossRegionExportWriter/Reader pair is pinned by template test.
      */
     getUsEast1CertificateStack() {
-        const key = `${this.stackPrefix}UsEast1Certificates`;
+        return this.getUsEast1Stack("UsEast1Certificates", "certificate");
+    }
+    /**
+     * Retrieve the app-owned us-east-1 CloudFront logging stack — named
+     * `${this.name}UsEast1CdnLogging`.
+     *
+     * CloudWatch Logs accepts CloudFront standard-logging (v2) delivery
+     * sources, destinations and deliveries in us-east-1 only, so a logging
+     * CDN whose app deploys to another region creates them here; the
+     * distribution ARN and the log bucket ARN reach this stack through CDK
+     * cross-region references, which makes it a CONSUMER of the Cdn stack —
+     * it deploys after the Cdn stack and is destroyed before it, the mirror
+     * of the certificate stack. A CDN in a us-east-1 app never creates it.
+     *
+     * Everything crossing the boundary is a value the export writer requires
+     * stable under an unchanged logical id: the distribution ARN and the
+     * bucket ARN both are. Never route a per-synth value (a timestamp, an
+     * asset hash) through this stack's references.
+     */
+    getUsEast1CdnLoggingStack() {
+        return this.getUsEast1Stack("UsEast1CdnLogging", "CloudFront logging");
+    }
+    /**
+     * The two us-east-1 stacks share a shape: no stack dependencies of their
+     * own (the CDK cross-region reference adds the consumer→producer edge),
+     * env-pinned to the deploying account (cross-region references resolve
+     * only between env-pinned stacks) and `crossRegionReferences: true` — the
+     * flag must be on BOTH the producing and the consuming stack, and the
+     * emitted Custom::CrossRegionExportWriter/Reader pair is pinned by
+     * template test.
+     */
+    getUsEast1Stack(suffix, purpose) {
+        const key = `${this.stackPrefix}${suffix}`;
         if (!this.stacks[key]) {
             const account = process.env.CDK_DEFAULT_ACCOUNT;
             if (!account) {
-                throw new Error(`App '${this.name}': the us-east-1 certificate stack needs a ` +
+                throw new Error(`App '${this.name}': the us-east-1 ${purpose} stack needs a ` +
                     "concrete account (got CDK_DEFAULT_ACCOUNT undefined). " +
                     "Cross-region references resolve only between env-pinned stacks " +
                     "— deploy through the Fjall CLI, or export CDK_DEFAULT_ACCOUNT " +

package/dist/lib/config/aws/disasterRecovery.d.ts

@@ -12,8 +12,7 @@ export interface DisasterRecoveryProps {
     customBackupPlans?: CustomBackupPlanConfig[];
 }
 export declare class DisasterRecovery extends Construct {
-    readonly backupVault?: BackupVault;
-    private readonly vaultRef;
+    readonly backupVault: BackupVault;
     readonly backupPlans: {
         standard: BackupPlan;
         resilient: BackupPlan;

package/dist/lib/config/aws/disasterRecovery.js

@@ -1,12 +1,14 @@
-import { CfnOutput, Duration, RemovalPolicy } from "aws-cdk-lib";
+import { Annotations, CfnOutput, Duration, RemovalPolicy } from "aws-cdk-lib";
 import { Construct } from "constructs";
 import { BackupVault, BackupPlan } from "../../resources/aws/backup/index.js";
 import { BackupPlanRule, BackupVault as Vault } from "aws-cdk-lib/aws-backup";
-import { cronSchedule } from "../../resources/aws/messaging/index.js";
 import { AccountPrincipal, Effect, PolicyStatement } from "aws-cdk-lib/aws-iam";
+import { Key } from "aws-cdk-lib/aws-kms";
+import { cronSchedule } from "../../resources/aws/messaging/index.js";
 import { getConfig } from "../../utils/getConfig.js";
 import { toPascalCase } from "../../utils/capitaliseString.js";
-import { BACKUP_VAULT_NAME } from "@fjall/util";
+import { readBackupVaultVerdict } from "../../utils/cdkContext.js";
+import { BACKUP_VAULT_NAME, isReownedBackupVault } from "@fjall/util";
 // Backup retention constants (in days)
 const RETENTION_PERIODS = {
     STANDARD: 90,
@@ -28,11 +30,13 @@ const VAULT_LOCK = {
     MAX_RETENTION: Duration.days(36500),
     GRACE_PERIOD: Duration.days(3)
 };
+function liveLockMode(lock) {
+    if (lock === null)
+        return "none";
+    return lock.lockDate !== undefined ? "compliance" : "governance";
+}
 export class DisasterRecovery extends Construct {
-    // Set in create-mode only; in adopt-mode the existing vault is referenced, not created.
     backupVault;
-    // Vault the plans write to: created vault (create-mode) or imported handle (adopt-mode).
-    vaultRef;
     backupPlans;
     customBackupPlans;
     constructor(scope, id, props) {
@@ -41,9 +45,10 @@ export class DisasterRecovery extends Construct {
         const providerAccounts = config.providerAccounts;
         const account = providerAccounts.find((pa) => pa.id === props.accountId);
         const isComplianceAccount = account?.environment === "compliance";
-        // Set by the deploy orchestration after probing DescribeBackupVault: adopt the
-        // retained fixed-name vault by reference rather than re-CREATE it (which collides).
-        const adoptExistingVault = this.node.tryGetContext("fjallAdoptBackupVault") === "true";
+        // Injected by the deploy engine after probing the live vault and the account
+        // stack; unset (a bare synth) is the create template.
+        const verdict = readBackupVaultVerdict(this.node);
+        const reOwned = isReownedBackupVault(verdict);
         const disasterRecoveryRegion = config.disasterRecoveryRegion;
         // Look up compliance account for cross-account replication
         // Skip if the compliance account (prevent self-replication)
@@ -58,9 +63,11 @@ export class DisasterRecovery extends Construct {
         // permanently-immutable compliance lock. See
         // decisions/2026-06-03-backup-vault-lock-mode-by-intent.md.
         const vaultLock = account?.vaultLock ?? (isComplianceAccount ? "governance" : "none");
-        // Adopt-mode references an already-locked vault and applies no lock config,
-        // so it is exempt from the acknowledgement gate.
-        if (!adoptExistingVault &&
+        // Fjall never issues a lock call against a vault it did not create: a
+        // re-owned vault declares no lock and the intent only warns when it
+        // differs, so the acknowledgement gate guards only a lock this template
+        // creates.
+        if (!reOwned &&
             vaultLock === "compliance" &&
             account?.acknowledgeImmutableVaultLock !== true) {
             throw new Error(`Account "${account?.name ?? props.accountId}" requests vaultLock: ` +
@@ -69,7 +76,7 @@ export class DisasterRecovery extends Construct {
                 `compliance lock cannot be removed by anyone, including AWS or the ` +
                 `root user. Set the acknowledgement explicitly to proceed.`);
         }
-        const lockConfiguration = vaultLock === "compliance"
+        const intendedLockConfiguration = vaultLock === "compliance"
             ? {
                 minRetention: VAULT_LOCK.MIN_RETENTION,
                 maxRetention: VAULT_LOCK.MAX_RETENTION,
@@ -81,20 +88,33 @@ export class DisasterRecovery extends Construct {
                     maxRetention: VAULT_LOCK.MAX_RETENTION
                 }
                 : undefined;
-        if (adoptExistingVault) {
-            this.vaultRef = Vault.fromBackupVaultName(this, "BackupVault", BACKUP_VAULT_NAME);
-        }
-        else {
-            this.backupVault = new BackupVault(this, "BackupVault", {
-                vaultName: BACKUP_VAULT_NAME,
-                removalPolicy: RemovalPolicy.RETAIN,
-                lockConfiguration: lockConfiguration
-            });
-            this.vaultRef = this.backupVault.vault;
+        const lockConfiguration = reOwned ? undefined : intendedLockConfiguration;
+        const liveLocked = verdict.state !== "absent" && verdict.lock !== null;
+        if (verdict.state !== "absent" && reOwned) {
+            const liveMode = liveLockMode(verdict.lock);
+            if (liveMode !== vaultLock) {
+                Annotations.of(this).addWarningV2("fjall:backupVault:lockIntentNotApplied", `Backup vault "${BACKUP_VAULT_NAME}" is re-owned: Fjall does not ` +
+                    `manage the lock of a vault it did not create. Its live lock ` +
+                    `(${liveMode}) stays as it is and the configured vaultLock ` +
+                    `(${vaultLock}) is not applied — align the configured vaultLock ` +
+                    `with the live lock, or change the live lock with the AWS Backup ` +
+                    `API where it is still changeable.`);
+            }
         }
-        // Cross-account access policy — create-mode only. addToAccessPolicy is unavailable
-        // on an imported vault, and a live (locked) vault retains the grant written at creation.
-        if (this.backupVault && isComplianceAccount) {
+        this.backupVault = new BackupVault(this, "BackupVault", {
+            vaultName: BACKUP_VAULT_NAME,
+            removalPolicy: RemovalPolicy.RETAIN,
+            lockConfiguration,
+            ...(verdict.state !== "absent" &&
+                reOwned && {
+                encryptionKey: Key.fromKeyArn(this, "BackupVaultLiveKey", verdict.keyArn)
+            }),
+            importIdentityOnly: verdict.state === "unowned"
+        });
+        const vault = this.backupVault.vault;
+        // Cross-account copy grant. Declared in every mode; the wrapper strips it
+        // from the import pass, and the converge deploy applies it.
+        if (isComplianceAccount) {
             const allAccounts = providerAccounts;
             const productionAccounts = allAccounts.filter((acc) => acc.environment === "production");
             if (productionAccounts.length > 0) {
@@ -104,7 +124,7 @@ export class DisasterRecovery extends Construct {
                     actions: ["backup:CopyIntoBackupVault"],
                     resources: ["*"]
                 });
-                this.backupVault.vault.addToAccessPolicy(copyStatement);
+                vault.addToAccessPolicy(copyStatement);
             }
         }
         // Construct cross-region replication vault ARN (same account, DR region)
@@ -118,19 +138,19 @@ export class DisasterRecovery extends Construct {
                 planName: "standard",
                 rules: this.createStandardBackupRules("standard"),
                 tagValue: "default",
-                backupVault: this.vaultRef
+                backupVault: vault
             }),
             resilient: new BackupPlan(this, "ResilientBackupPlan", {
                 planName: "resilient",
                 rules: this.createResilientBackupRules("resilient", replicationVaultArn),
                 tagValue: "resilient",
-                backupVault: this.vaultRef
+                backupVault: vault
             }),
             enterprise: new BackupPlan(this, "EnterpriseBackupPlan", {
                 planName: "enterprise",
                 rules: this.createEnterpriseBackupRules("enterprise", replicationVaultArn, disasterRecoveryVaultArn),
                 tagValue: "enterprise",
-                backupVault: this.vaultRef
+                backupVault: vault
             })
         };
         // Create custom backup plans if provided
@@ -140,7 +160,7 @@ export class DisasterRecovery extends Construct {
                     planName: config.planName,
                     rules: config.rules,
                     tagValue: config.tagValue,
-                    backupVault: this.vaultRef
+                    backupVault: vault
                 });
             });
         }
@@ -157,7 +177,7 @@ export class DisasterRecovery extends Construct {
                 exportName: `${id}ReplicationRegion`
             });
         }
-        if (vaultLock !== "none") {
+        if (reOwned ? liveLocked : lockConfiguration !== undefined) {
             new CfnOutput(this, "VaultLockEnabled", {
                 key: "VaultLockEnabled",
                 value: "true",

package/dist/lib/patterns/aws/cdn.d.ts

@@ -4,7 +4,7 @@ import { type IApplicationLoadBalancer } from "aws-cdk-lib/aws-elasticloadbalanc
 import { type ICertificate } from "aws-cdk-lib/aws-certificatemanager";
 import { type ICachePolicy, type IResponseHeadersPolicy } from "aws-cdk-lib/aws-cloudfront";
 import type App from "../../app.js";
-import { CloudFrontDistribution, type CachePolicyPreset, type AccessGateConfig } from "../../resources/aws/cdn/index.js";
+import { CloudFrontDistribution, type CloudFrontLogFormat, type CachePolicyPreset, type AccessGateConfig } from "../../resources/aws/cdn/index.js";
 import { type ICdn } from "./interfaces/cdn.js";
 import { type StaticSiteRouting, type CloudFrontPriceClass } from "@fjall/util";
 import { type BackupTier } from "../../utils/backupTierMapping.js";
@@ -83,17 +83,17 @@ interface BaseCdnProps {
     certificateArn?: string;
     comment?: string;
     /**
-     * Standard (S3) access logging. Default: the app backup tier's
-     * `cloudFrontLogging` column — enterprise logs to the stack's shared,
-     * lifecycle-expired access-log bucket under `cloudfront/<id>/`. Set either
-     * knob to take over: `enableLogging: false` opts out at any tier,
-     * `logBucket` delivers to a bucket of your own. Standard logging cannot
-     * deliver into an opt-in region, so a tier- or explicitly-enabled CDN whose
-     * delivery region is opt-in is refused at synth with those two cures — see
-     * {@link CloudFrontDistributionProps.enableLogging}.
+     * Standard logging (v2): access logs delivered through CloudWatch Logs.
+     * Default: the app backup tier's `cloudFrontLogging` column — enterprise
+     * logs to the stack's shared, lifecycle-expired access-log bucket under
+     * `cloudfront/<id>`, as JSON. An object takes over at any tier (its
+     * `bucket`, `prefix` and `format` each default as above); `false` opts
+     * out at any tier. The delivery resources live in the CDN stack when the
+     * app deploys to us-east-1 and in the app's `UsEast1CdnLogging` stack
+     * otherwise (CloudWatch Logs accepts them there only), so a logging CDN
+     * outside us-east-1 needs the `App` — the factory path fills it.
      */
-    enableLogging?: boolean;
-    logBucket?: IBucket;
+    logging?: CdnLoggingConfig | false;
     priceClass?: CloudFrontPriceClass;
     forwardHostHeader?: boolean;
     accessGate?: false | AccessGateConfig;
@@ -104,6 +104,14 @@ interface BaseCdnProps {
      */
     appBackupTier?: BackupTier;
 }
+export interface CdnLoggingConfig {
+    /** Bucket the logs land in; defaults to the stack's access-log bucket. */
+    bucket?: IBucket;
+    /** Key prefix (no leading or trailing slash); defaults to `cloudfront/<id>`. */
+    prefix?: string;
+    /** CloudWatch Logs output format; defaults to `json`. */
+    format?: CloudFrontLogFormat;
+}
 /**
  * S3 origin CDN props - use with S3 bucket
  */

package/dist/lib/patterns/aws/cdn.js

@@ -1,7 +1,7 @@
-import { Fn, Token } from "aws-cdk-lib";
+import { Fn, Stack, Token } from "aws-cdk-lib";
 import { Certificate } from "aws-cdk-lib/aws-certificatemanager";
 import { CloudFrontTarget, LoadBalancerTarget } from "aws-cdk-lib/aws-route53-targets";
-import { CloudFrontDistribution } from "../../resources/aws/cdn/index.js";
+import { assertNoLegacyLoggingProps, CLOUDFRONT_LOG_DELIVERY_REGION, CloudFrontDistribution } from "../../resources/aws/cdn/index.js";
 import { AliasRecord } from "../../resources/aws/networking/index.js";
 import { tierDefault } from "../../utils/backupTierMapping.js";
 import { stackAccessLogBucket } from "../../resources/aws/logging/index.js";
@@ -12,31 +12,54 @@ import { isStorage } from "./storage.js";
 import { CdnEcsOriginResolver, cdnOriginRefusal, internalAlbMessage, normaliseDnsName } from "./cdnAppOrigin.js";
 import { isCompute, isEcsCompute, isLambdaCompute } from "./compute.js";
 /**
- * An explicit `enableLogging` or `logBucket` is the override and passes
- * through untouched; otherwise the tier decides, and a tier-enabled CDN logs
- * to the stack's shared access-log bucket under its own prefix.
+ * `false` is off at any tier; an object is on at any tier with its own
+ * defaults filled; `undefined` lets the tier decide, and a tier-enabled CDN
+ * logs to the stack's shared access-log bucket under its own prefix.
  */
 function resolveCdnLogging(scope, id, props) {
-    if (props.enableLogging !== undefined || props.logBucket !== undefined) {
-        return {
-            enableLogging: props.enableLogging,
-            logBucket: props.logBucket,
-            logFilePrefix: undefined
-        };
-    }
-    if (!tierDefault(props.appBackupTier, "cloudFrontLogging")) {
-        return {
-            enableLogging: undefined,
-            logBucket: undefined,
-            logFilePrefix: undefined
-        };
+    if (props.logging === false)
+        return undefined;
+    if (props.logging === undefined &&
+        !tierDefault(props.appBackupTier, "cloudFrontLogging")) {
+        return undefined;
     }
+    const config = props.logging ?? {};
     return {
-        enableLogging: true,
-        logBucket: stackAccessLogBucket(scope),
-        logFilePrefix: `cloudfront/${id}/`
+        bucket: config.bucket ?? stackAccessLogBucket(scope),
+        ...(config.prefix !== undefined && { prefix: config.prefix }),
+        ...(config.format !== undefined && { format: config.format }),
+        ...resolveLogDeliveryScope(scope, id, props.app)
     };
 }
+/**
+ * CloudWatch Logs accepts CloudFront delivery resources in us-east-1 only.
+ * A CDN stack already there hosts them itself; any other region hands them
+ * to the app's `UsEast1CdnLogging` stack, whose distribution and bucket
+ * ARNs arrive through CDK cross-region references — which need both stacks
+ * env-pinned, so a token region is refused here with the cure rather than
+ * by CloudFormation with a region error after the CDN stack has deployed.
+ */
+function resolveLogDeliveryScope(scope, id, app) {
+    const region = Stack.of(scope).region;
+    if (Token.isUnresolved(region)) {
+        throw new Error(`CDN '${id}': standard logging (v2) needs a concrete region at synth ` +
+            "— the delivery resources go to us-east-1 and reach the " +
+            "distribution through cross-region references, which resolve only " +
+            "between env-pinned stacks — but this stack's region is a token. " +
+            "Deploy through the Fjall CLI, or export CDK_DEFAULT_ACCOUNT and " +
+            "CDK_DEFAULT_REGION before synthesising; or set logging: false.");
+    }
+    if (region === CLOUDFRONT_LOG_DELIVERY_REGION)
+        return {};
+    if (app === undefined) {
+        throw new Error(`CDN '${id}': standard logging (v2) from region ${region} places its ` +
+            "delivery resources in the app's us-east-1 logging stack, but 'app' " +
+            "is unset. Create the CDN through the factory path — " +
+            "app.addCdn(CdnFactory.build(...)) — which fills it, pass 'app' " +
+            "explicitly, or set logging: false.");
+    }
+    return { deliveryScope: app.getUsEast1CdnLoggingStack().getStack() };
+}
 /**
  * The distribution's own alias names, normalised — consumed by the
  * origin-loop guard and by the ECS origin resolver (auto-resolution excludes
@@ -59,7 +82,10 @@ function collectAliasNames(props) {
  * Validates CDN props — synth-time hard errors for shapes CloudFormation
  * would only reject at deploy.
  */
-function validateCdnProps(props) {
+function validateCdnProps(id, props) {
+    // The pattern rebuilds the distribution props field by field, so the
+    // resource-layer refusal never sees a legacy key given here.
+    assertNoLegacyLoggingProps(`CDN '${id}'`, props, "logging: { bucket?, prefix?, format? } | false");
     const hasCertificate = !!(props.certificate || props.certificateArn);
     // domainConfig is the managed-domain authority for the viewer config —
     // mixing it with the literal surface would give the alias list and the
@@ -251,7 +277,7 @@ const ROUTING_CDN_BEHAVIOUR = {
 };
 export class Cdn extends CloudFrontDistribution {
     constructor(scope, id, props) {
-        validateCdnProps(props);
+        validateCdnProps(id, props);
         // Zone + certificate resolve BEFORE super() — the viewer certificate is
         // part of the distribution's props — so their constructs land on the CDN
         // stack (`scope`) under `${id}`-prefixed IDs, the pattern convention.
@@ -476,6 +502,7 @@ export class Cdn extends CloudFrontDistribution {
                 originRequestPolicy: props.originRequestPolicy
             }
             : {};
+        const logging = resolveCdnLogging(scope, id, props);
         return {
             distributionProps: {
                 appName,
@@ -486,7 +513,7 @@ export class Cdn extends CloudFrontDistribution {
                 domainNames,
                 certificate,
                 comment: props.comment,
-                ...resolveCdnLogging(scope, id, props),
+                ...(logging !== undefined && { logging }),
                 priceClass: props.priceClass,
                 forwardHostHeader: props.forwardHostHeader ?? impliedForwardHostHeader,
                 accessGate: props.accessGate,
@@ -699,7 +726,8 @@ export class CdnFactory {
             // The App is the only place the app name is known here; without it the
             // export falls back to the construct id and the Domain import misses.
             // The App instance itself rides along for domainConfig resolution
-            // (certificate placement needs app.getUsEast1CertificateStack()).
+            // (certificate placement needs app.getUsEast1CertificateStack()) and
+            // for log-delivery placement (app.getUsEast1CdnLoggingStack()).
             return new Cdn(scope, id, {
                 ...props,
                 appName: props.appName ?? app.getName(),

package/dist/lib/patterns/aws/domain.js

@@ -99,9 +99,9 @@ export class Domain extends Construct {
         }
     }
     /**
-     * Re-publish the domain's effective zone name under a predictable export
-     * key so downstream consumers (Phase 2, Phase 3 eject) can resolve the
-     * managed zone without knowing the registrar discriminant. The `Zone` and
+     * Re-publish the domain's effective zone name under a predictable output
+     * key (mirrored byte-for-byte by the eject template) so a stack reader can
+     * name the zone without knowing the registrar discriminant. The `Zone` and
      * `HostedZoneId` outputs on the inner `HostedZone` construct cover the
      * Route53-backed paths; this output covers external-records mode where no
      * hosted zone exists.

package/dist/lib/patterns/aws/externalRecordsPattern.d.ts

@@ -7,12 +7,15 @@ export interface ExternalRecordsPatternResult {
 }
 /**
  * Composition for `registrar: "external-records"`. No Route53 hosted zone is
- * created; certificates still use ACM DNS validation (the user must paste the
- * validation records at their external registrar) and any user-declared
- * records are emitted as `ManualRecord` entries with per-record `CfnOutput`s
- * so Phase 2 can resolve token values after deploy.
+ * created. Certificates use ACM DNS validation with no zone to write to, so
+ * their validation CNAMEs must be created at the external registrar — and
+ * those records do not exist at synth: ACM chooses them when CloudFormation
+ * creates the certificate, and `AWS::CertificateManager::Certificate`
+ * returns only its ARN. They are therefore never `ManualRecord` entries:
+ * they are read from ACM (`DescribeCertificate`) once the certificate is
+ * pending, while CloudFormation waits for the records to resolve.
  *
- * Ordering invariant: certificate-validation entries come first so the user
- * adds them before the app records (ACM can't issue until validation resolves).
+ * User-declared records become `ManualRecord` entries, each with a
+ * `CfnOutput` triple keyed by its position in `records`.
  */
 export declare function composeExternalRecords(scope: Construct, props: ExternalRecordsProps): ExternalRecordsPatternResult;

package/dist/lib/patterns/aws/externalRecordsPattern.js

@@ -6,58 +6,35 @@ import { resolveRecordFqdn } from "../../utils/domainTypes.js";
 const MANUAL_RECORD_TTL_SECONDS = 300;
 /**
  * Composition for `registrar: "external-records"`. No Route53 hosted zone is
- * created; certificates still use ACM DNS validation (the user must paste the
- * validation records at their external registrar) and any user-declared
- * records are emitted as `ManualRecord` entries with per-record `CfnOutput`s
- * so Phase 2 can resolve token values after deploy.
+ * created. Certificates use ACM DNS validation with no zone to write to, so
+ * their validation CNAMEs must be created at the external registrar — and
+ * those records do not exist at synth: ACM chooses them when CloudFormation
+ * creates the certificate, and `AWS::CertificateManager::Certificate`
+ * returns only its ARN. They are therefore never `ManualRecord` entries:
+ * they are read from ACM (`DescribeCertificate`) once the certificate is
+ * pending, while CloudFormation waits for the records to resolve.
  *
- * Ordering invariant: certificate-validation entries come first so the user
- * adds them before the app records (ACM can't issue until validation resolves).
+ * User-declared records become `ManualRecord` entries, each with a
+ * `CfnOutput` triple keyed by its position in `records`.
  */
 export function composeExternalRecords(scope, props) {
     const safeZone = toPascalCase(getSafeZoneName(props.zoneName));
     const certificates = new Map();
     const manualRecords = [];
-    // 1. Certificates — ACM DNS validation emits CNAMEs the user must paste at
-    //    their registrar. Capture the validation records as ManualRecord
-    //    entries (cert-validation first per ordering invariant).
     const normalisedCerts = (props.certificates ?? []).map(normaliseCertificate);
     normalisedCerts.forEach((cert, index) => {
         const safeCertName = toPascalCase(cert.domainName.split(".").join(""));
         const acm = new AcmCertificate(scope, `${safeZone}${safeCertName}Cert${index}`, {
             domainName: cert.domainName,
             subjectAlternativeNames: cert.subjectAlternativeNames,
-            // No hosted zone to validate against — ACM emits tokens for the user
-            // to resolve via `describeStackResources` or deploy output.
             validation: CertificateValidation.fromDns(),
             transparencyLoggingEnabled: cert.transparencyLogging ?? true
         });
         certificates.set(cert.domainName, acm);
-        const certNames = [
-            cert.domainName,
-            ...(cert.subjectAlternativeNames ?? [])
-        ];
-        certNames.forEach((name, nameIndex) => {
-            // `domainValidationOption` returns a token CNAME name/value pair. Using
-            // `attrDomainValidationOptions` returns an array token; per-name lookup
-            // uses index. CDK exposes the first validation option via
-            // `certificate.certificateArn` only — we fall back to emitting a
-            // predictable CfnOutput pointing to the attribute for Phase 2.
-            const record = {
-                name: `_acme-challenge.${name}`,
-                type: "CNAME",
-                value: `<ACM-validation-token-for-${name}>`,
-                ttl: MANUAL_RECORD_TTL_SECONDS,
-                reason: "certificate-validation"
-            };
-            manualRecords.push(record);
-            emitManualRecordOutputs(scope, safeZone, manualRecords.length - 1, record, `CertValidation${safeCertName}${nameIndex}`);
-        });
     });
-    // 2. User-declared records. Typed targets resolve to token strings via
-    //    `resolveTargetToDnsName`. Apex ALIAS was already rejected by
-    //    `validateDomainProps`, so all records here are safe to emit as manual
-    //    entries.
+    // Typed targets resolve to token strings via `resolveTargetToDnsName`.
+    // Apex ALIAS was already rejected by `validateDomainProps`, so all records
+    // here are safe to emit as manual entries.
     const records = props.records ?? [];
     records.forEach((record, index) => {
         const fqdn = resolveRecordFqdn(record.name, props.zoneName);
@@ -67,11 +44,10 @@ export function composeExternalRecords(scope, props) {
                 name: fqdn,
                 type: "CNAME",
                 value,
-                ttl: MANUAL_RECORD_TTL_SECONDS,
-                reason: "user-declared"
+                ttl: MANUAL_RECORD_TTL_SECONDS
             };
             manualRecords.push(manual);
-            emitManualRecordOutputs(scope, safeZone, manualRecords.length - 1, manual, `UserRecord${index}`);
+            emitManualRecordOutputs(scope, safeZone, index, manual);
             return;
         }
         const rawValue = record.value;
@@ -80,11 +56,10 @@ export function composeExternalRecords(scope, props) {
             name: fqdn,
             type: narrowManualType(record.type),
             value: joined,
-            ttl: record.ttl ?? MANUAL_RECORD_TTL_SECONDS,
-            reason: "user-declared"
+            ttl: record.ttl ?? MANUAL_RECORD_TTL_SECONDS
         };
         manualRecords.push(manual);
-        emitManualRecordOutputs(scope, safeZone, manualRecords.length - 1, manual, `UserRecord${index}`);
+        emitManualRecordOutputs(scope, safeZone, index, manual);
     });
     return { certificates, manualRecords };
 }
@@ -115,17 +90,18 @@ function narrowManualType(type) {
             return "TXT";
     }
 }
-function emitManualRecordOutputs(scope, safeZone, index, record, discriminator) {
-    new CfnOutput(scope, `${safeZone}ManualRecord${discriminator}Name`, {
+function emitManualRecordOutputs(scope, safeZone, index, record) {
+    const idPrefix = `${safeZone}ManualRecordUserRecord${index}`;
+    new CfnOutput(scope, `${idPrefix}Name`, {
         key: `${safeZone}ManualRecord${index}Name`,
         value: record.name,
-        description: `External-records manual DNS entry (${record.reason})`
+        description: "External-records manual DNS entry (user-declared)"
     });
-    new CfnOutput(scope, `${safeZone}ManualRecord${discriminator}Type`, {
+    new CfnOutput(scope, `${idPrefix}Type`, {
         key: `${safeZone}ManualRecord${index}Type`,
         value: record.type
     });
-    new CfnOutput(scope, `${safeZone}ManualRecord${discriminator}Value`, {
+    new CfnOutput(scope, `${idPrefix}Value`, {
         key: `${safeZone}ManualRecord${index}Value`,
         value: record.value
     });

package/dist/lib/patterns/aws/interfaces/domain.d.ts

@@ -158,15 +158,18 @@ export interface ExternalRecordsProps extends DomainCommonProps {
 }
 export type DomainProps = Route53ApexProps | ExternalDelegatedProps | ExternalRecordsProps;
 /**
- * Manual record emitted by `registrar: "external-records"` mode for the user
- * to paste at their external registrar. For typed targets the `value` is a
- * CloudFormation token (`Fn::ImportValue`) at synth time; Phase 2 resolves the
- * concrete value via `describeStackResources` after deploy.
+ * A user-declared record that `registrar: "external-records"` mode reports
+ * for the user to create at their external registrar, one per `records`
+ * entry, in declaration order. For typed targets the `value` is a
+ * CloudFormation token (`Fn::ImportValue`) at synth time; the concrete host
+ * is the deployed stack's `ManualRecord<index>Value` output.
+ *
+ * Certificate-validation records are never manual records: ACM chooses them
+ * at deploy time, so no synth-time value exists (see `composeExternalRecords`).
  */
 export interface ManualRecord {
     readonly name: string;
     readonly type: "A" | "AAAA" | "CNAME" | "TXT";
     readonly value: string;
     readonly ttl: number;
-    readonly reason: "certificate-validation" | "user-declared";
 }