@fjall/components-infrastructure 3.5.2 → 3.6.1

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

@@ -361,6 +361,7 @@ export class ClickHouseDatabase extends Construct {
             clickHouseContainerSecrets[userPasswordEnvName(name)] =
                 userSecret.getImport("password");
         }
+        const resolvedAlertsTopic = resolveAlertsTopic(this, "AlertsTopic", props.alertsTopic);
         const ecsCompute = new EcsCompute(this, "Compute", {
             type: "ecs",
             vpc,
@@ -393,7 +394,10 @@ export class ClickHouseDatabase extends Construct {
                             deviceName: CLICKHOUSE_EBS_DEVICE_NAME,
                             availabilityZone: dataAz,
                             iops: CLICKHOUSE_EBS_IOPS,
-                            throughputMbps: CLICKHOUSE_EBS_THROUGHPUT_MBPS
+                            throughputMbps: CLICKHOUSE_EBS_THROUGHPUT_MBPS,
+                            ...(resolvedAlertsTopic !== undefined && {
+                                alarmTopic: resolvedAlertsTopic
+                            })
                         },
                         userData,
                         desiredCapacity: 1,
@@ -492,7 +496,6 @@ export class ClickHouseDatabase extends Construct {
         // asgName is the CloudWatch dimension the host metrics key off, so without
         // it the alarms cannot be built; no topic is the default, so skip silently
         // rather than throw.
-        const resolvedAlertsTopic = resolveAlertsTopic(this, "AlertsTopic", props.alertsTopic);
         const asgName = ecsCompute.getAutoScalingGroupName();
         if (resolvedAlertsTopic !== undefined && asgName !== undefined) {
             createClickHouseAlarms({

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

@@ -5,6 +5,7 @@ import { Repository } from "aws-cdk-lib/aws-ecr";
 import { Effect, PolicyStatement } from "aws-cdk-lib/aws-iam";
 import { Code, Runtime } from "aws-cdk-lib/aws-lambda";
 import { PublicHostedZone } from "aws-cdk-lib/aws-route53";
+import { LoadBalancerTarget } from "aws-cdk-lib/aws-route53-targets";
 import { SqsDestination } from "aws-cdk-lib/aws-s3-notifications";
 import { Construct } from "constructs";
 import { readFileSync } from "node:fs";
@@ -20,6 +21,7 @@ import { createLambdaTargetGroup } from "../../resources/aws/compute/lambdaAlbTa
 import { LambdaFunction } from "../../resources/aws/compute/lambda.js";
 import { Ecr } from "../../resources/aws/storage/ecr.js";
 import { SecurityGroup } from "../../resources/aws/networking/securityGroup.js";
+import { AliasRecord } from "../../resources/aws/networking/dnsRecord/aliasRecord.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";
@@ -56,6 +58,7 @@ const DEV_SUBSTRATE_PARENT_ROLE_ID = "DevSubstrateParentDelegationRole";
 /** Construct ids for the substrate's wildcard cert + :443 HTTPS listener (A6). */
 const DEV_SUBSTRATE_CERT_ID = "DevSubstrateCertificate";
 const DEV_SUBSTRATE_HTTPS_LISTENER_ID = "DevSubstrateHttpsListener";
+const DEV_SUBSTRATE_WILDCARD_ALIAS_ID = "DevSubstrateWildcardAlias";
 // Default deploy phase when `phase` is omitted — the cert + :443 listener
 // build. Shared with the delegated `Domain` topology via
 // `DOMAIN_DEPLOY_DEFAULT_PHASE` (utils/domainTypes.ts): the R2 two-step guard
@@ -68,13 +71,6 @@ const DEV_SUBSTRATE_HTTPS_LISTENER_ID = "DevSubstrateHttpsListener";
  * `point-at-existing` (GAP-7) is deferred, so this is a fixed value for now.
  */
 const DEV_SUBSTRATE_DATABASE_MODE = "aurora";
-/**
- * The container port slots serve HTTP on. Fjall owns the slot image, so this is a
- * fixed contract: the ALB → slot-SG ingress opens exactly this port and the
- * host-header rules a slot registers (§5.4) forward to it. The public :80 ALB
- * front listener is separate.
- */
-const DEV_SUBSTRATE_SLOT_PORT = 8080;
 /**
  * Physical-name prefix pinning every substrate resource inside the `fjall-dev-*`
  * fence. Load-bearing: the dev-tier IAM grants (`@fjall/generator devRolePolicies`)
@@ -210,17 +206,24 @@ export class DevSubstrate extends Construct {
         // 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.
+        // registration. ssmSecretsPath grants the slot parameter tree — the worker
+        // writes DATABASE_URL + FJALL_* under /fjall/dev/<app>/<slot>/ and slot
+        // task-defs inject them via this role; without it the task dies at
+        // ResourceInitializationError on ssm:GetParameters.
         const slotExecutionRole = createBaseExecutionRole(this, DEV_SUBSTRATE_SLOT_EXEC_ROLE_ID, {
+            ssmSecretsPath: `/fjall/dev/${props.appKebab}`,
             path: "/fjall/dev/",
             roleName: `${devFenceName(props.appKebab)}-slot-exec`
         });
         const { partition, region, account } = Stack.of(this);
+        // Whole app dev-fence subtree, not /slots/* — the worker names each slot's
+        // log group /fjall/dev/<app>/<slot> (the slot base path), so a /slots/*
+        // scope would deny CreateLogStream at task start.
         slotExecutionRole.addToPolicy(new PolicyStatement({
             effect: Effect.ALLOW,
             actions: ["logs:CreateLogStream", "logs:PutLogEvents"],
             resources: [
-                `arn:${partition}:logs:${region}:${account}:log-group:/fjall/dev/${props.appKebab}/slots/*:*`
+                `arn:${partition}:logs:${region}:${account}:log-group:/fjall/dev/${props.appKebab}/*:*`
             ]
         }));
         // Slot-SG → Aurora ingress. Dormant in Data-API mode (Data API reaches the
@@ -258,7 +261,11 @@ export class DevSubstrate extends Construct {
         // fence-pinned name — the reaper finds it by the subtree fence tags. A pinned
         // name would only reintroduce the 32-char ALB-name truncation dance.
         const loadBalancer = createApplicationLoadBalancer(this, DEV_SUBSTRATE_ALB_ID, { vpc, internetFacing: true, securityGroup: albSecurityGroup });
-        slotSecurityGroup.connections.allowFrom(albSecurityGroup, Port.tcp(DEV_SUBSTRATE_SLOT_PORT), 
+        // All-TCP, not a pinned port: the worker registers each slot's target group
+        // on the per-slot `buildSpec.containerPort` (default 3000, `--port`
+        // overridable), chosen at provision time — synth cannot know it. Scope stays
+        // tight because the source is the substrate's own ALB SG.
+        slotSecurityGroup.connections.allowFrom(albSecurityGroup, Port.allTcp(), 
         // EC2 SG-rule descriptions reject non-ASCII (allowed set is
         // `a-zA-Z0-9. _-:/()#,@[]+=&;{}!$*` — no arrow, em-dash, or even `>`).
         "Dev substrate ALB to slot tasks");
@@ -376,6 +383,17 @@ export class DevSubstrate extends Construct {
         // Unconditional 404 as on :80 (per-slot rules attach out of band, §5.4). open
         // (CDK default) adds the :443 ingress to the ALB SG.
         const httpsListener = addRoutingListener(loadBalancer, DEV_SUBSTRATE_HTTPS_LISTENER_ID, { port: 443, certificate: certificate.certificate, default404: true });
+        // GAP-4: one wildcard ALIAS resolves every slot host to the ALB — routing
+        // happens per-slot via host-header rules, so no per-slot DNS write is ever
+        // needed. Phase-gated with the cert (the record is useless before :443
+        // exists) and created in adopt mode too: the adopted zone predates the
+        // substrate, but the record targets the substrate's own ALB.
+        new AliasRecord(this, DEV_SUBSTRATE_WILDCARD_ALIAS_ID, {
+            zone: childZone,
+            zoneName: childZoneName,
+            recordName: "*",
+            target: new LoadBalancerTarget(loadBalancer)
+        });
         return { devDomain: childZoneName, httpsListener };
     }
     /**

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
+    };
+}