@fjall/components-infrastructure 3.4.1 → 3.6.0

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/devSubstrate.js

@@ -161,6 +161,8 @@ export class DevSubstrate extends Construct {
             databaseName: DEV_SUBSTRATE_DATABASE_NAME,
             clusterIdentifier: devFenceName(props.appKebab),
             credentialsSecretName: `${devFenceName(props.appKebab)}-master`,
+            // Default alias derives from the fixed databaseName — collides account-wide.
+            credentialsKmsAliasName: `cmk/${devFenceName(props.appKebab)}-master`,
             engineVersion: props.engineVersion ?? DEV_AURORA_DEFAULTS.ENGINE_VERSION,
             serverlessV2MinCapacity: DEV_AURORA_DEFAULTS.SERVERLESS_V2_MIN_CAPACITY,
             serverlessV2MaxCapacity: DEV_AURORA_DEFAULTS.SERVERLESS_V2_MAX_CAPACITY,
@@ -205,8 +207,14 @@ export class DevSubstrate extends Construct {
         // createBaseExecutionRole DELIBERATELY omits logs (auto-granted only on the
         // ECS-pattern path via AwsLogDriver.bind()). Slot task-defs reference this
         // shared role by ARN, so that auto-grant never fires — add the log-write grant
-        // explicitly.
-        const slotExecutionRole = createBaseExecutionRole(this, DEV_SUBSTRATE_SLOT_EXEC_ROLE_ID);
+        // explicitly. Path + name pin the role inside the /fjall/dev/ fence: the dev
+        // deploy role's only iam:PassRole grant is on role/fjall/dev/*, so the CDK
+        // defaults (path "/", CFN-generated name) would AccessDeny slot task-def
+        // registration.
+        const slotExecutionRole = createBaseExecutionRole(this, DEV_SUBSTRATE_SLOT_EXEC_ROLE_ID, {
+            path: "/fjall/dev/",
+            roleName: `${devFenceName(props.appKebab)}-slot-exec`
+        });
         const { partition, region, account } = Stack.of(this);
         slotExecutionRole.addToPolicy(new PolicyStatement({
             effect: Effect.ALLOW,
@@ -376,9 +384,11 @@ export class DevSubstrate extends Construct {
      * the hand-created G2 slot service consumes these to place tasks, register a
      * host-header rule, inject DB creds and point a sleeping slot at the waker.
      *
-     * No KMS-alias export: the substrate's Aurora + waker use the AWS-managed default
-     * key (design VF4 — the waker's kms:Decrypt is ViaService-scoped precisely
-     * because there is no per-app CMK), so there is no alias to export.
+     * No KMS-alias export: cluster storage and SSM SecureStrings ride AWS-managed
+     * default keys, and while the master-credentials secret IS CMK-encrypted (the
+     * Secret wrapper mints `cmk/fjall-dev-<app>-master`), no consumer addresses
+     * that key by alias — the provisioner's and waker's kms:Decrypt are
+     * ViaService-scoped (Secrets Manager / SSM), so there is no alias to export.
      *
      * The Aurora slot-SG ingress (A2.5) makes the Database stack depend on the
      * Compute stack. So the two DB exports are scoped under `databaseScope` (the

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/compute/ecsRoles.d.ts

@@ -16,9 +16,16 @@ import type { EcsServiceProps } from "./ecsTypes.js";
  * SHARED or IMPORTED role those auto-grants cannot reach — e.g. the dev
  * substrate's slot exec role, referenced by slot task-defs via ARN — MUST add
  * the explicit `logs` / `secretsmanager` statements itself.
+ *
+ * `path`/`roleName` pin the IAM path and physical name — needed when an IAM
+ * grant fences on the role's path (the dev-role `iam:PassRole` grant on
+ * `role/fjall/dev/*`), since the CDK default is path `/` + a CFN-generated
+ * name no path- or prefix-scoped grant can match.
  */
 export declare function createBaseExecutionRole(scope: Construct, id: string, opts?: {
     ssmSecretsPath?: string;
+    path?: string;
+    roleName?: string;
 }): Role;
 /**
  * Creates the execution role for ECS infrastructure operations.

package/dist/lib/resources/aws/compute/ecsRoles.js

@@ -15,10 +15,17 @@ import { deriveSsmSecretsPath } from "./ecsTaskDefinition.js";
  * SHARED or IMPORTED role those auto-grants cannot reach — e.g. the dev
  * substrate's slot exec role, referenced by slot task-defs via ARN — MUST add
  * the explicit `logs` / `secretsmanager` statements itself.
+ *
+ * `path`/`roleName` pin the IAM path and physical name — needed when an IAM
+ * grant fences on the role's path (the dev-role `iam:PassRole` grant on
+ * `role/fjall/dev/*`), since the CDK default is path `/` + a CFN-generated
+ * name no path- or prefix-scoped grant can match.
  */
 export function createBaseExecutionRole(scope, id, opts = {}) {
     const executionRole = new Role(scope, id, {
-        assumedBy: new ServicePrincipal("ecs-tasks.amazonaws.com")
+        assumedBy: new ServicePrincipal("ecs-tasks.amazonaws.com"),
+        path: opts.path,
+        roleName: opts.roleName
     });
     // GetAuthorizationToken is an account-level API that requires resources: ["*"].
     // The image-pull actions also use "*" because ecrRepository can be a string URI

package/dist/lib/resources/aws/database/rdsAurora.d.ts

@@ -20,6 +20,13 @@ interface RdsProps {
     clusterIdentifier?: string;
     /** Physical name of the generated master-credentials secret. */
     credentialsSecretName?: string;
+    /**
+     * KMS alias for the CMK encrypting the master-credentials secret. Aliases are
+     * account+region-unique, so a caller with a fixed `databaseName` deployed once
+     * per app (e.g. the dev substrate) must pass an app-scoped alias or the second
+     * app's deploy fails on the alias collision.
+     */
+    credentialsKmsAliasName?: string;
     /** Serverless-v2 floor in ACU. 0 enables scale-to-zero (auto-pause). */
     serverlessV2MinCapacity?: number;
     /** Serverless-v2 ceiling in ACU. */

package/dist/lib/resources/aws/database/rdsAurora.js

@@ -100,6 +100,7 @@ export class RdsAurora extends Construct {
             this.databaseCredentials = new Secret(this, `${this.databaseNameValue}Credentials`, {
                 secretName: props.credentialsSecretName ??
                     ResourceNaming.credentialsSecretName(id),
+                aliasName: props.credentialsKmsAliasName,
                 generateSecretString: {
                     secretStringTemplate: JSON.stringify({ username }),
                     excludePunctuation: true,
@@ -151,7 +152,7 @@ export class RdsAurora extends Construct {
         const readers = this.buildReaders(props, piEnabled, performanceInsightsKey, performanceInsightsRetention);
         const engine = props.engine ||
             DatabaseClusterEngine.auroraPostgres({
-                version: AuroraPostgresEngineVersion.of("16.6", "16")
+                version: AuroraPostgresEngineVersion.of("16.10", "16")
             });
         const parameterGroup = new ParameterGroup(this, `${this.databaseNameValue}ParameterGroup`, {
             engine,

package/dist/lib/resources/aws/database/rdsDefaults.d.ts

@@ -16,15 +16,18 @@ export declare const RDS_DEFAULTS: Readonly<{
  * (fast dev-envs Phase 3). `min 0` ACU scales the shared cluster to zero when
  * idle; `enableDataApi` lets slot DDL run over HTTPS with no VPC connection, and
  * is the only mode under which min-0 actually saves (a live pooled connection
- * pins the cluster above 0 ACU). Engine 16.6 satisfies the auto-pause-capable
- * floor (see `MIN_AUTO_PAUSE_POSTGRES_VERSION`).
+ * pins the cluster above 0 ACU). Engine 16.10 satisfies the auto-pause-capable
+ * floor (see `MIN_AUTO_PAUSE_POSTGRES_VERSION`). AWS removes old minors from
+ * the creatable list over time (16.6 rejected with "Cannot find version" by
+ * 2026-07) — pin a mid-window minor, not the oldest available, and expect this
+ * to need a bump roughly yearly.
  */
 export declare const DEV_AURORA_DEFAULTS: Readonly<{
     readonly SERVERLESS_V2_MIN_CAPACITY: 0;
     readonly SERVERLESS_V2_MAX_CAPACITY: 4;
     readonly AUTO_PAUSE_SECONDS: 1200;
     readonly ENABLE_DATA_API: true;
-    readonly ENGINE_VERSION: "16.6";
+    readonly ENGINE_VERSION: "16.10";
 }>;
 /**
  * Bounds AWS enforces on `ServerlessV2ScalingConfiguration.SecondsUntilAutoPause`