@fjall/components-infrastructure 3.5.2 → 3.6.0

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

@@ -1,5 +1,5 @@
 import { HostedZone } from "../../resources/aws/networking/hostedZone.js";
-import { DomainCertificate } from "../../resources/aws/networking/domainCertificate.js";
+import { composeDomainCertificates } from "./domainCertificateComposer.js";
 import { composeTypedDnsRecords } from "./dnsRecordComposer.js";
 import { toPascalCase, getSafeZoneName } from "../../utils/capitaliseString.js";
 /**
@@ -27,19 +27,17 @@ export function composeApexDomain(scope, props) {
         costAllocationEnvironment: props.costAllocationEnvironment,
         costAllocationDomain: props.zoneName
     });
-    const certificates = new Map();
-    (props.certificates ?? []).forEach((cert, index) => {
-        const normalised = normaliseCertificate(cert);
-        const safeCertName = toPascalCase(normalised.domainName.split(".").join(""));
-        const dc = new DomainCertificate(scope, `${safeZone}${safeCertName}Cert${index}`, {
-            domainName: normalised.domainName,
-            subjectAlternativeNames: normalised.subjectAlternativeNames,
-            transparencyLogging: normalised.transparencyLogging,
-            hostedZone: hostedZoneConstruct.hostedZone,
-            costAllocationEnvironment: props.costAllocationEnvironment,
-            costAllocationDomain: props.zoneName
-        });
-        certificates.set(normalised.domainName, dc.certificate);
+    // Regional entries mint beside the zone as before; cloudFront entries
+    // mint in us-east-1 (in-stack here, or in the domain-paired
+    // UsEast1Certificates stack) and publish the zone-level export (D3).
+    const certificates = composeDomainCertificates(scope, {
+        certificates: props.certificates,
+        effectiveZoneName: props.zoneName,
+        safeZone,
+        hostedZone: hostedZoneConstruct.hostedZone,
+        hostedZoneId: props.hostedZoneId,
+        costAllocationEnvironment: props.costAllocationEnvironment,
+        costAllocationDomain: props.zoneName
     });
     if (props.records && props.records.length > 0) {
         composeTypedDnsRecords(scope, hostedZoneConstruct.hostedZone, props.zoneName, props.records);
@@ -55,13 +53,3 @@ export function composeApexDomain(scope, props) {
         manualRecords: []
     };
 }
-function normaliseCertificate(cert) {
-    if (typeof cert === "string") {
-        return { domainName: cert };
-    }
-    return {
-        domainName: cert.domainName,
-        subjectAlternativeNames: cert.subjectAlternativeNames,
-        transparencyLogging: cert.transparencyLogging
-    };
-}

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

@@ -10,8 +10,12 @@ export interface DelegatedDomainPatternResult {
 }
 /**
  * Composition for `registrar: "external-delegated"` — the delegated-child
- * topology. Creates a hosted zone for `{delegatedSubdomain}.{zoneName}` and,
- * when `parentDelegationRoleArn` is present, UPSERTs the child NS into the
+ * topology. Creates a hosted zone for `{delegatedSubdomain}.{zoneName}` —
+ * or ADOPTS an existing one when `hostedZoneId` + `adoptedNameServers` are
+ * set (both-or-neither, validated): the zone is imported instead of created
+ * and the delegation UPSERT carries the adopted NS literals, since an
+ * imported zone exposes no `hostedZoneNameServers` attribute. When
+ * `parentDelegationRoleArn` is present, the child NS are UPSERTed into the
  * parent zone via `CrossAccountZoneDelegationRecord` (D8 child-writes
  * delegation; same shape as devSubstrate Case 1). The role ARN MUST be a
  * literal — validated in `validateDomainProps` (VD2-a). When absent, the

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

@@ -2,14 +2,18 @@ import { Annotations } from "aws-cdk-lib";
 import { Role } from "../../resources/aws/iam/index.js";
 import { HostedZone } from "../../resources/aws/networking/hostedZone.js";
 import { CrossAccountDelegationRecord } from "../../resources/aws/networking/crossAccountDelegationRecord.js";
-import { DomainCertificate } from "../../resources/aws/networking/domainCertificate.js";
+import { composeDomainCertificates } from "./domainCertificateComposer.js";
 import { composeTypedDnsRecords } from "./dnsRecordComposer.js";
 import { toPascalCase, getSafeZoneName } from "../../utils/capitaliseString.js";
 import { DOMAIN_DEPLOY_DEFAULT_PHASE } from "../../utils/domainTypes.js";
 /**
  * Composition for `registrar: "external-delegated"` — the delegated-child
- * topology. Creates a hosted zone for `{delegatedSubdomain}.{zoneName}` and,
- * when `parentDelegationRoleArn` is present, UPSERTs the child NS into the
+ * topology. Creates a hosted zone for `{delegatedSubdomain}.{zoneName}` —
+ * or ADOPTS an existing one when `hostedZoneId` + `adoptedNameServers` are
+ * set (both-or-neither, validated): the zone is imported instead of created
+ * and the delegation UPSERT carries the adopted NS literals, since an
+ * imported zone exposes no `hostedZoneNameServers` attribute. When
+ * `parentDelegationRoleArn` is present, the child NS are UPSERTed into the
  * parent zone via `CrossAccountZoneDelegationRecord` (D8 child-writes
  * delegation; same shape as devSubstrate Case 1). The role ARN MUST be a
  * literal — validated in `validateDomainProps` (VD2-a). When absent, the
@@ -26,6 +30,9 @@ export function composeDelegatedDomain(scope, props) {
     const safeZone = toPascalCase(getSafeZoneName(effectiveZone));
     const hostedZoneConstruct = new HostedZone(scope, `${safeZone}HostedZone`, {
         zoneName: effectiveZone,
+        // Adoption path: an existing child zone is imported by id rather than
+        // created (both-or-neither with adoptedNameServers, validated upstream).
+        hostedZoneId: props.hostedZoneId,
         // The PARENT account owns the delegation role — this is the child.
         createDelegationRole: false,
         costAllocationEnvironment: props.costAllocationEnvironment,
@@ -44,6 +51,9 @@ export function composeDelegatedDomain(scope, props) {
             delegatedZone: hostedZoneConstruct.hostedZone,
             delegatedZoneName: effectiveZone,
             parentHostedZoneName: props.zoneName,
+            // Adoption: the imported zone has no NS attribute — the UPSERT uses
+            // the user-declared literals (undefined on the create path).
+            adoptedNameServers: props.adoptedNameServers,
             costAllocationEnvironment: props.costAllocationEnvironment,
             costAllocationDomain: props.zoneName
         });
@@ -55,7 +65,10 @@ export function composeDelegatedDomain(scope, props) {
             `the parent DelegationRole ARN from the managed-domain binding) or ` +
             `add the zone's NS records at the parent registrar manually.`);
     }
-    const nameServers = hostedZoneConstruct.nameServers ?? [];
+    // Created zones surface their synth-time NS tokens; adopted zones surface
+    // the declared literals (authoritative — the same values the delegation
+    // record UPSERTs into the parent).
+    const nameServers = hostedZoneConstruct.nameServers ?? props.adoptedNameServers ?? [];
     const records = props.records ?? [];
     if (records.length > 0) {
         composeTypedDnsRecords(scope, hostedZoneConstruct.hostedZone, effectiveZone, records);
@@ -70,19 +83,17 @@ export function composeDelegatedDomain(scope, props) {
             manualRecords: []
         };
     }
-    const certificates = new Map();
-    (props.certificates ?? []).forEach((cert, index) => {
-        const normalised = normaliseCertificate(cert);
-        const safeCertName = toPascalCase(normalised.domainName.split(".").join(""));
-        const dc = new DomainCertificate(scope, `${safeZone}${safeCertName}Cert${index}`, {
-            domainName: normalised.domainName,
-            subjectAlternativeNames: normalised.subjectAlternativeNames,
-            transparencyLogging: normalised.transparencyLogging,
-            hostedZone: hostedZoneConstruct.hostedZone,
-            costAllocationEnvironment: props.costAllocationEnvironment,
-            costAllocationDomain: props.zoneName
-        });
-        certificates.set(normalised.domainName, dc.certificate);
+    // Regional entries mint beside the zone as before; cloudFront entries
+    // mint in us-east-1 (in-stack here, or in the domain-paired
+    // UsEast1Certificates stack) and publish the zone-level export (D3).
+    const certificates = composeDomainCertificates(scope, {
+        certificates: props.certificates,
+        effectiveZoneName: effectiveZone,
+        safeZone,
+        hostedZone: hostedZoneConstruct.hostedZone,
+        hostedZoneId: props.hostedZoneId,
+        costAllocationEnvironment: props.costAllocationEnvironment,
+        costAllocationDomain: props.zoneName
     });
     return {
         hostedZone: hostedZoneConstruct.hostedZone,
@@ -91,13 +102,3 @@ export function composeDelegatedDomain(scope, props) {
         manualRecords: []
     };
 }
-function normaliseCertificate(cert) {
-    if (typeof cert === "string") {
-        return { domainName: cert };
-    }
-    return {
-        domainName: cert.domainName,
-        subjectAlternativeNames: cert.subjectAlternativeNames,
-        transparencyLogging: cert.transparencyLogging
-    };
-}

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

@@ -0,0 +1,48 @@
+import type { Construct } from "constructs";
+import { type IHostedZone } from "aws-cdk-lib/aws-route53";
+import type { ICertificate } from "aws-cdk-lib/aws-certificatemanager";
+import type { Certificate } from "./interfaces/domain.js";
+export interface DomainCertificateComposition {
+    readonly certificates: readonly Certificate[] | undefined;
+    /**
+     * Zone the export names derive from — the apex `zoneName`, or the
+     * delegated child's `${delegatedSubdomain}.${zoneName}` (mirrors the
+     * Domain construct's `resolveEffectiveZoneName`).
+     */
+    readonly effectiveZoneName: string;
+    /** PascalCase construct-ID prefix shared with the calling composer. */
+    readonly safeZone: string;
+    readonly hostedZone: IHostedZone;
+    /**
+     * Literal zone id when the zone is ADOPTED — the paired us-east-1 stack
+     * re-imports the zone by attributes instead of a runtime lookup (a created
+     * zone's id is a cross-stack token the paired stack must not consume).
+     */
+    readonly hostedZoneId: string | undefined;
+    readonly costAllocationEnvironment: string | undefined;
+    readonly costAllocationDomain: string;
+}
+/**
+ * Certificate composition shared by `composeApexDomain` and
+ * `composeDelegatedDomain`.
+ *
+ * Regional entries mint a `DomainCertificate` beside the zone exactly as
+ * before (byte-stable construct IDs `${safeZone}${safeCertName}Cert${index}`,
+ * per-domain `<domain>-certificate-arn` export). A `cloudFront: true` entry
+ * (D3) instead mints in us-east-1 — the only region CloudFront accepts
+ * viewer certificates from — and publishes the zone-level
+ * `<zone>-us-east-1-certificate-arn` export in place of the per-domain one:
+ *
+ *   - domain stack already in us-east-1 (the fjall.io case): certificate and
+ *     export stay IN-STACK, no extra stack;
+ *   - any other resolved region: certificate and export live in a
+ *     domain-paired `<StackName>UsEast1Certificates` stack. NO CDK
+ *     cross-region references — the ARN is consumed as a LITERAL via D2
+ *     DescribeStacks (`ManagedDomainBinding.usEast1CertificateArn`), so
+ *     neither stack synthesises the export writer/reader machinery.
+ *
+ * An unresolved region or account is a synth-time error naming the cures:
+ * where the certificate must live is unknowable, and guessing would strand
+ * the export CloudFront consumers (patternDomain) fail without.
+ */
+export declare function composeDomainCertificates(scope: Construct, composition: DomainCertificateComposition): Map<string, ICertificate>;

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

@@ -0,0 +1,179 @@
+import { CfnOutput, Stack, Stage, Token } from "aws-cdk-lib";
+import { HostedZone as AWSHostedZone } from "aws-cdk-lib/aws-route53";
+import { getDomainExportNames, getDomainUsEast1CertificatesStackName } from "@fjall/util";
+import { DomainCertificate } from "../../resources/aws/networking/domainCertificate.js";
+import { toPascalCase } from "../../utils/capitaliseString.js";
+const US_EAST_1 = "us-east-1";
+/**
+ * Certificate composition shared by `composeApexDomain` and
+ * `composeDelegatedDomain`.
+ *
+ * Regional entries mint a `DomainCertificate` beside the zone exactly as
+ * before (byte-stable construct IDs `${safeZone}${safeCertName}Cert${index}`,
+ * per-domain `<domain>-certificate-arn` export). A `cloudFront: true` entry
+ * (D3) instead mints in us-east-1 — the only region CloudFront accepts
+ * viewer certificates from — and publishes the zone-level
+ * `<zone>-us-east-1-certificate-arn` export in place of the per-domain one:
+ *
+ *   - domain stack already in us-east-1 (the fjall.io case): certificate and
+ *     export stay IN-STACK, no extra stack;
+ *   - any other resolved region: certificate and export live in a
+ *     domain-paired `<StackName>UsEast1Certificates` stack. NO CDK
+ *     cross-region references — the ARN is consumed as a LITERAL via D2
+ *     DescribeStacks (`ManagedDomainBinding.usEast1CertificateArn`), so
+ *     neither stack synthesises the export writer/reader machinery.
+ *
+ * An unresolved region or account is a synth-time error naming the cures:
+ * where the certificate must live is unknowable, and guessing would strand
+ * the export CloudFront consumers (patternDomain) fail without.
+ */
+export function composeDomainCertificates(scope, composition) {
+    const certificates = new Map();
+    (composition.certificates ?? []).forEach((cert, index) => {
+        const normalised = normaliseCertificate(cert);
+        const safeCertName = toPascalCase(normalised.domainName.split(".").join(""));
+        const certId = `${composition.safeZone}${safeCertName}Cert${index}`;
+        if (normalised.cloudFront !== true) {
+            const dc = new DomainCertificate(scope, certId, {
+                domainName: normalised.domainName,
+                subjectAlternativeNames: normalised.subjectAlternativeNames,
+                transparencyLogging: normalised.transparencyLogging,
+                hostedZone: composition.hostedZone,
+                costAllocationEnvironment: composition.costAllocationEnvironment,
+                costAllocationDomain: composition.costAllocationDomain
+            });
+            certificates.set(normalised.domainName, dc.certificate);
+            return;
+        }
+        certificates.set(normalised.domainName, mintCloudFrontCertificate(scope, composition, normalised, certId));
+    });
+    return certificates;
+}
+function mintCloudFrontCertificate(scope, composition, cert, certId) {
+    const domainStack = Stack.of(scope);
+    const region = Token.isUnresolved(domainStack.region)
+        ? undefined
+        : domainStack.region;
+    if (region === undefined) {
+        throw new Error(`Domain '${composition.effectiveZoneName}': cannot place the ` +
+            `CloudFront certificate for '${cert.domainName}' — the domain ` +
+            "stack's region is unresolved at synth (got a region token), so " +
+            "whether it already deploys to us-east-1 is unknowable. Deploy " +
+            "through the Fjall CLI, or export CDK_DEFAULT_ACCOUNT and " +
+            "CDK_DEFAULT_REGION before synthesising.");
+    }
+    if (region === US_EAST_1) {
+        // In-stack placement (the fjall.io case): the domain stack's home region
+        // already satisfies CloudFront, so no paired stack is minted and the
+        // zone-level export publishes beside the zone.
+        const dc = new DomainCertificate(scope, certId, {
+            domainName: cert.domainName,
+            subjectAlternativeNames: cert.subjectAlternativeNames,
+            transparencyLogging: cert.transparencyLogging,
+            hostedZone: composition.hostedZone,
+            costAllocationEnvironment: composition.costAllocationEnvironment,
+            costAllocationDomain: composition.costAllocationDomain,
+            // The zone-level us-east-1 export below replaces the per-domain
+            // regional export: CloudFront consumers resolve the ARN through
+            // ManagedDomainBinding.usEast1CertificateArn, and a viewer
+            // certificate has no regional (ALB/ECS) consumers to export for.
+            exportCertificateArn: false
+        });
+        emitUsEast1Export(scope, composition, dc);
+        return dc.certificate;
+    }
+    const pairedStack = resolvePairedUsEast1Stack(domainStack, composition, cert);
+    // Re-create the zone reference INSIDE the paired stack: an adopted zone's
+    // literal id travels as-is, while a created zone's id is a cross-stack
+    // token the paired stack must not consume (that would demand
+    // crossRegionReferences) — it re-resolves by lookup on the declared zone
+    // name instead (same split as patternDomain's BYO path).
+    const certZone = composition.hostedZoneId !== undefined
+        ? AWSHostedZone.fromHostedZoneAttributes(pairedStack, `${composition.safeZone}UsEast1CertificateZone`, {
+            hostedZoneId: composition.hostedZoneId,
+            zoneName: composition.effectiveZoneName
+        })
+        : AWSHostedZone.fromLookup(pairedStack, `${composition.safeZone}UsEast1CertificateZone`, { domainName: composition.effectiveZoneName });
+    const dc = new DomainCertificate(pairedStack, certId, {
+        domainName: cert.domainName,
+        subjectAlternativeNames: cert.subjectAlternativeNames,
+        transparencyLogging: cert.transparencyLogging,
+        hostedZone: certZone,
+        costAllocationEnvironment: composition.costAllocationEnvironment,
+        costAllocationDomain: composition.costAllocationDomain,
+        exportCertificateArn: false
+    });
+    emitUsEast1Export(pairedStack, composition, dc);
+    return dc.certificate;
+}
+/**
+ * The zone-level `<zone>-us-east-1-certificate-arn` export
+ * (`getDomainExportNames(...).usEast1CertificateArn` — the SSOT
+ * `DomainService.resolveDomainForApp` reads into
+ * `ManagedDomainBinding.usEast1CertificateArn` for CloudFront consumers).
+ * Scope is the stack that owns the certificate: the domain stack in-region,
+ * the paired stack otherwise.
+ */
+function emitUsEast1Export(scope, composition, dc) {
+    const exports = getDomainExportNames(composition.effectiveZoneName);
+    new CfnOutput(scope, `${composition.safeZone}UsEast1CertificateArn`, {
+        key: `${composition.safeZone}UsEast1CertificateArn`,
+        value: dc.certificateArn,
+        exportName: exports.usEast1CertificateArn
+    });
+}
+/**
+ * The domain-paired us-east-1 certificate stack,
+ * `<StackName>UsEast1Certificates` — the name contract
+ * `DomainService.resolveDomainForApp` derives when the domain stack itself
+ * is not us-east-1. Env-pinned to the domain stack's concrete account:
+ * without one the paired stack cannot be addressed, so an unresolved
+ * account fails synth with the cures.
+ */
+function resolvePairedUsEast1Stack(domainStack, composition, cert) {
+    if (Token.isUnresolved(domainStack.account)) {
+        throw new Error(`Domain '${composition.effectiveZoneName}': the CloudFront ` +
+            `certificate for '${cert.domainName}' needs the paired us-east-1 ` +
+            "certificate stack, which needs a concrete account (got an " +
+            "unresolved account token). Deploy through the Fjall CLI, or " +
+            "export CDK_DEFAULT_ACCOUNT and CDK_DEFAULT_REGION before " +
+            "synthesising.");
+    }
+    const container = Stage.of(domainStack);
+    if (container === undefined) {
+        throw new Error(`Domain '${composition.effectiveZoneName}': the paired us-east-1 ` +
+            "certificate stack must be created beside the domain stack, but " +
+            "the domain stack has no enclosing App/Stage. Synthesise the " +
+            "domain under a CDK App (the Fjall CLI always does).");
+    }
+    // SSOT name contract with the read side (DomainService.resolveDomainForApp
+    // describes this stack with a us-east-1 CloudFormation client).
+    const pairedId = getDomainUsEast1CertificatesStackName(domainStack.stackName);
+    const existing = container.node.tryFindChild(pairedId);
+    if (existing !== undefined) {
+        if (!Stack.isStack(existing)) {
+            throw new Error(`Domain '${composition.effectiveZoneName}': construct '${pairedId}' ` +
+                "already exists beside the domain stack but is not a Stack — the " +
+                "paired us-east-1 certificate stack name is reserved by the D3 " +
+                "contract. Rename the colliding construct.");
+        }
+        return existing;
+    }
+    // Plain env-pinned stack, deliberately WITHOUT crossRegionReferences: the
+    // ARN leaves this stack as a literal through DescribeStacks, never as a
+    // CDK token, so no writer/reader machinery may synthesise.
+    return new Stack(container, pairedId, {
+        env: { account: domainStack.account, region: US_EAST_1 }
+    });
+}
+function normaliseCertificate(cert) {
+    if (typeof cert === "string") {
+        return { domainName: cert };
+    }
+    return {
+        domainName: cert.domainName,
+        subjectAlternativeNames: cert.subjectAlternativeNames,
+        transparencyLogging: cert.transparencyLogging,
+        cloudFront: cert.cloudFront
+    };
+}

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

@@ -86,29 +86,69 @@ function validateRecords(scope, props, effectiveZone) {
 }
 function validateCertificates(props, effectiveZone) {
     const certificates = props.certificates ?? [];
+    let cloudFrontCount = 0;
     for (const cert of certificates) {
         const resolved = normaliseCertificate(cert);
         assertWithinZone(resolved.domainName, effectiveZone);
         for (const san of resolved.subjectAlternativeNames ?? []) {
             assertWithinZone(san, effectiveZone);
         }
+        // D3 CloudFront designation consistency. TS already narrows the prop to
+        // boolean; the runtime check catches JS callers and stale generated code.
+        if (resolved.cloudFront !== undefined &&
+            typeof resolved.cloudFront !== "boolean") {
+            throw new Error(`Domain: certificate '${resolved.domainName}' has a non-boolean ` +
+                `'cloudFront' (received: ${JSON.stringify(resolved.cloudFront)}). ` +
+                `Cure: set cloudFront: true for a CloudFront viewer certificate, ` +
+                `or drop the prop.`);
+        }
+        if (resolved.cloudFront === true) {
+            cloudFrontCount += 1;
+            if (props.registrar === "external-records") {
+                throw new Error(`Domain: certificate '${resolved.domainName}' sets cloudFront: ` +
+                    `true, which registrar 'external-records' does not support — ` +
+                    `there is no Fjall-managed hosted zone to DNS-validate the ` +
+                    `us-east-1 certificate against. Cure: manage the zone with ` +
+                    `registrar 'route53' or 'external-delegated', or drop ` +
+                    `cloudFront and provision an app-owned us-east-1 certificate.`);
+            }
+        }
+    }
+    if (cloudFrontCount > 1) {
+        throw new Error(`Domain: at most one certificate may set cloudFront: true (received ` +
+            `${cloudFrontCount}) — the zone-level ` +
+            `'<zone>-us-east-1-certificate-arn' export is singular. Cure: keep ` +
+            `one CloudFront certificate and move the other names into its ` +
+            `subjectAlternativeNames.`);
     }
 }
 /**
  * D8 delegation-consistency checks for the child-writes shape.
  *
- * `parentDelegationRoleArn` and `phase` belong to the delegated topology
- * (`external-delegated`) only; on any other registrar their presence is a
- * hard error rather than a silent no-op. On the delegated topology the role
- * ARN must be a LITERAL string (VD2-a): an unresolved token means the caller
- * reached for `Fn.importValue`, which resolves same-account only and is
- * exactly the trap that sank the legacy `DomainDelegation` pattern.
+ * `parentDelegationRoleArn`, `phase` and `adoptedNameServers` belong to the
+ * delegated topology (`external-delegated`) only; on any other registrar
+ * their presence is a hard error rather than a silent no-op. On the
+ * delegated topology the role ARN must be a LITERAL string (VD2-a): an
+ * unresolved token means the caller reached for `Fn.importValue`, which
+ * resolves same-account only and is exactly the trap that sank the legacy
+ * `DomainDelegation` pattern. Adoption (`hostedZoneId` +
+ * `adoptedNameServers`) is both-or-neither: an imported zone exposes no
+ * NS attribute, so a one-sided declaration either cannot delegate or
+ * cannot name the zone it delegates to.
  */
 function validateDelegationConfig(props) {
     const arn = props
         .parentDelegationRoleArn;
     const phase = props.phase;
     if (props.registrar !== "external-delegated") {
+        const adoptedNameServers = props
+            .adoptedNameServers;
+        if (adoptedNameServers !== undefined) {
+            throw new Error(`Domain: 'adoptedNameServers' is only supported with registrar: ` +
+                `'external-delegated' (received registrar: '${props.registrar}'). ` +
+                `Cure: adoption of an existing child zone is declared on the ` +
+                `delegated child Domain — move the prop there, or drop it.`);
+        }
         if (arn !== undefined) {
             throw new Error(`Domain: 'parentDelegationRoleArn' is only supported with registrar: ` +
                 `'external-delegated' (received registrar: '${props.registrar}'). ` +
@@ -129,6 +169,7 @@ function validateDelegationConfig(props) {
             `received: '${String(phase)}'. Cure: use 'zone' for step 1 of the ` +
             `two-step delegated deploy, 'full' (or omit) for the complete build.`);
     }
+    validateAdoptionConfig(props);
     if (arn === undefined) {
         return;
     }
@@ -151,13 +192,60 @@ function validateDelegationConfig(props) {
             `output (arn:<partition>:iam::<account>:role/<name>).`);
     }
 }
+/**
+ * Child-zone ADOPTION consistency (external-delegated only). `hostedZoneId`
+ * and `adoptedNameServers` are both-or-neither, and the name servers must be
+ * a non-empty array of literal hostnames: an imported zone exposes no
+ * `hostedZoneNameServers` attribute, so these literals are the ONLY source
+ * the `Custom::CrossAccountZoneDelegation` UPSERT has for the parent NS row
+ * — a token or empty set would delegate the zone to nowhere.
+ */
+function validateAdoptionConfig(props) {
+    const hostedZoneId = props.hostedZoneId;
+    const adoptedNameServers = props
+        .adoptedNameServers;
+    if (hostedZoneId === undefined && adoptedNameServers === undefined) {
+        return;
+    }
+    if (adoptedNameServers === undefined) {
+        throw new Error(`Domain: adopting an existing child zone requires 'adoptedNameServers' ` +
+            `alongside 'hostedZoneId' (both-or-neither). An imported zone ` +
+            `exposes no name-server attribute at synth, so the parent NS UPSERT ` +
+            `needs the live values. Cure: read them once ` +
+            `(aws route53 get-hosted-zone --id ${String(hostedZoneId)}) and ` +
+            `paste the DelegationSet.NameServers literals.`);
+    }
+    if (hostedZoneId === undefined) {
+        throw new Error(`Domain: 'adoptedNameServers' requires 'hostedZoneId' (both-or-neither) ` +
+            `— the literals describe an EXISTING zone to adopt. Cure: set the ` +
+            `adopted zone's hostedZoneId, or drop 'adoptedNameServers' to create ` +
+            `a fresh child zone.`);
+    }
+    if (typeof hostedZoneId !== "string" || hostedZoneId.length === 0) {
+        throw new Error(`Domain: 'hostedZoneId' must be a non-empty string; received: ` +
+            `${JSON.stringify(hostedZoneId)}.`);
+    }
+    if (!Array.isArray(adoptedNameServers) || adoptedNameServers.length === 0) {
+        throw new Error(`Domain: 'adoptedNameServers' must be a non-empty array of NS ` +
+            `hostnames; received: ${JSON.stringify(adoptedNameServers)}. Cure: ` +
+            `paste the adopted zone's DelegationSet.NameServers.`);
+    }
+    for (const ns of adoptedNameServers) {
+        if (typeof ns !== "string" || ns.length === 0 || Token.isUnresolved(ns)) {
+            throw new Error(`Domain: every 'adoptedNameServers' entry must be a literal NS ` +
+                `hostname (no CDK tokens) — the delegation UPSERT writes them ` +
+                `verbatim into the parent zone. Received: ${JSON.stringify(ns)}.`);
+        }
+    }
+}
 function normaliseCertificate(cert) {
     if (typeof cert === "string") {
         return { domainName: cert };
     }
     return {
         domainName: cert.domainName,
-        subjectAlternativeNames: cert.subjectAlternativeNames
+        subjectAlternativeNames: cert.subjectAlternativeNames,
+        cloudFront: cert.cloudFront
     };
 }
 function assertWithinZone(candidate, zoneName) {

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

@@ -39,6 +39,22 @@ export type Certificate = string | {
     readonly domainName: string;
     readonly subjectAlternativeNames?: string[];
     readonly transparencyLogging?: boolean;
+    /**
+     * D3 — CloudFront viewer certificate. CloudFront accepts certificates
+     * from us-east-1 only, so a `cloudFront: true` entry mints its
+     * `DomainCertificate` there — in-stack when the domain stack itself
+     * resolves to us-east-1, otherwise in a domain-paired
+     * `<StackName>UsEast1Certificates` stack — and publishes the
+     * zone-level `<zone>-us-east-1-certificate-arn` export in place of
+     * the per-domain regional export. The ARN reaches CloudFront
+     * consumers as a LITERAL through
+     * `ManagedDomainBinding.usEast1CertificateArn` (D2 DescribeStacks),
+     * never via CDK cross-region references. At most one certificate per
+     * Domain may set it (the zone-level export is singular — put extra
+     * names in `subjectAlternativeNames`); unsupported on registrar
+     * `"external-records"`, which has no hosted zone to validate against.
+     */
+    readonly cloudFront?: boolean;
 };
 export interface DomainCommonProps {
     readonly zoneName: string;
@@ -55,6 +71,23 @@ export interface Route53ApexProps extends DomainCommonProps {
 export interface ExternalDelegatedProps extends DomainCommonProps {
     readonly registrar: "external-delegated";
     readonly delegatedSubdomain: string;
+    /**
+     * Child-zone ADOPTION: hosted zone id of an EXISTING zone for
+     * `{delegatedSubdomain}.{zoneName}`. When present the pattern IMPORTS the
+     * zone instead of creating one. Requires `adoptedNameServers`
+     * (both-or-neither — validated): an imported zone exposes no
+     * `hostedZoneNameServers` attribute at synth, so the parent NS UPSERT
+     * needs the live values as literals.
+     */
+    readonly hostedZoneId?: string;
+    /**
+     * Literal NS hostnames of the adopted zone (from a live
+     * `get-hosted-zone` read). Carried verbatim into the
+     * `Custom::CrossAccountZoneDelegation` UPSERT — the delegation record in
+     * the parent zone must keep pointing at the adopted zone's real name
+     * servers. Only valid together with `hostedZoneId`.
+     */
+    readonly adoptedNameServers?: string[];
     /**
      * D8 — child-writes delegation. LITERAL ARN of the parent zone's
      * DelegationRole (VD2-a: never `Fn.importValue`, which resolves

package/dist/lib/resources/aws/networking/crossAccountDelegationRecord.d.ts

@@ -6,6 +6,16 @@ export interface CrossAccountDelegationRecordProps {
     readonly delegatedZone: IHostedZone;
     readonly delegatedZoneName: string;
     readonly parentHostedZoneName: string;
+    /**
+     * Literal NS hostnames for an ADOPTED (imported) delegated zone. An
+     * imported `IHostedZone` exposes no `hostedZoneNameServers` attribute —
+     * CDK cannot know a live zone's NS at synth — so the custom resource
+     * would UPSERT an empty parent NS row. When set, a facade over the
+     * imported zone supplies these literals instead (see
+     * `withLiteralNameServers`). Omit for created zones, whose NS arrive as
+     * a CloudFormation attribute token.
+     */
+    readonly adoptedNameServers?: string[];
     readonly description?: string;
     readonly costAllocationEnvironment?: string;
     readonly costAllocationDomain?: string;

package/dist/lib/resources/aws/networking/crossAccountDelegationRecord.js

@@ -2,6 +2,29 @@ import { Construct } from "constructs";
 import { Tags } from "aws-cdk-lib";
 import { CrossAccountZoneDelegationRecord as CdkCrossAccountZoneDelegationRecord } from "aws-cdk-lib/aws-route53";
 import { applyCostAllocationTags } from "../../../utils/costAllocationTags.js";
+/**
+ * CDK facade seam for zone adoption. `CrossAccountZoneDelegationRecord`
+ * reads exactly `zoneName` and `hostedZoneNameServers` off its
+ * `delegatedZone`; the facade delegates every access to the imported zone
+ * and overrides only `hostedZoneNameServers` with the user-declared
+ * literals. Methods are bound to the underlying zone so `this`-dependent
+ * internals behave identically. Pinned by the adopted-case synth snapshot
+ * in crossAccountDelegationRecord.test.ts — a CDK upgrade that starts
+ * reading more through this seam trips the pin.
+ */
+function withLiteralNameServers(zone, nameServers) {
+    return new Proxy(zone, {
+        get(target, property) {
+            if (property === "hostedZoneNameServers") {
+                return [...nameServers];
+            }
+            const value = Reflect.get(target, property);
+            return typeof value === "function"
+                ? value.bind(target)
+                : value;
+        }
+    });
+}
 // CDK's CrossAccountZoneDelegationRecord is a custom-resource Lambda: user-level tags
 // on the record itself may not reach AWS. We tag the wrapping Fjall Construct for
 // assertion purposes; create-path tags still propagate to child resources (Lambda,
@@ -14,9 +37,12 @@ export class CrossAccountDelegationRecord extends Construct {
         this.description =
             props.description ??
                 `Fjall-managed cross-account delegation for ${props.delegatedZoneName} in parent ${props.parentHostedZoneName}`;
+        const delegatedZone = props.adoptedNameServers !== undefined
+            ? withLiteralNameServers(props.delegatedZone, props.adoptedNameServers)
+            : props.delegatedZone;
         this.record = new CdkCrossAccountZoneDelegationRecord(this, "Record", {
             delegationRole: props.delegationRole,
-            delegatedZone: props.delegatedZone,
+            delegatedZone,
             parentHostedZoneName: props.parentHostedZoneName
         });
         Tags.of(this).add("fjall:description", this.description);

package/dist/lib/utils/domainTypes.d.ts

@@ -29,15 +29,9 @@ export declare function resolveRecordFqdn(recordName: string, zoneName: string):
 /**
  * Two-step deploy phase for constructs whose certificates must not be issued
  * before their zone's NS delegation has propagated (design R2 cert-hang
- * guard). `"zone"` synthesises the hosted zone (+ delegation record) only;
- * `"full"` additionally issues certificates. Shared by the delegated `Domain`
- * topology and `DevSubstrate` — lowest common layer per generator-standards
- * § Infrastructure Layer Boundaries.
+ * guard) plus its omitted-phase default — homed in `@fjall/util`
+ * (`infra/domainExports.ts`, the lowest common layer) and re-exported here
+ * so construct-side consumers keep their import path. deploy-core's
+ * `orchestration/domain/types.ts` re-exports the same declaration.
  */
-export type DomainDeployPhase = "zone" | "full";
-/**
- * Default deploy phase when `phase` is omitted — the complete build. The
- * two-step guard (R2) sets `"zone"` explicitly for step 1, so the safe
- * default for a single-shot deploy is everything.
- */
-export declare const DOMAIN_DEPLOY_DEFAULT_PHASE: DomainDeployPhase;
+export { DOMAIN_DEPLOY_DEFAULT_PHASE, type DomainDeployPhase } from "@fjall/util";

package/dist/lib/utils/domainTypes.js

@@ -58,8 +58,11 @@ export function resolveRecordFqdn(recordName, zoneName) {
     return `${recordName}.${zoneName}`;
 }
 /**
- * Default deploy phase when `phase` is omitted — the complete build. The
- * two-step guard (R2) sets `"zone"` explicitly for step 1, so the safe
- * default for a single-shot deploy is everything.
+ * Two-step deploy phase for constructs whose certificates must not be issued
+ * before their zone's NS delegation has propagated (design R2 cert-hang
+ * guard) plus its omitted-phase default — homed in `@fjall/util`
+ * (`infra/domainExports.ts`, the lowest common layer) and re-exported here
+ * so construct-side consumers keep their import path. deploy-core's
+ * `orchestration/domain/types.ts` re-exports the same declaration.
  */
-export const DOMAIN_DEPLOY_DEFAULT_PHASE = "full";
+export { DOMAIN_DEPLOY_DEFAULT_PHASE } from "@fjall/util";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/components-infrastructure",
-  "version": "3.5.2",
+  "version": "3.6.0",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "bin": {
@@ -67,8 +67,8 @@
   },
   "dependencies": {
     "@aws-sdk/client-organizations": "^3.1038.0",
-    "@fjall/generator": "^3.5.2",
-    "@fjall/util": "^3.5.2",
+    "@fjall/generator": "^3.6.0",
+    "@fjall/util": "^3.6.0",
     "constructs": "^10.6.0"
   },
   "overrides": {
@@ -82,5 +82,5 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "gitHead": "f59755647b2fd81ff692a3545e8e199d93c3bdf8"
+  "gitHead": "10366db602d7e80669e22825a52071a47e05c3b7"
 }