@fjall/components-infrastructure 14.1.0 → 14.2.0

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

@@ -0,0 +1,251 @@
+/**
+ * ECS construct-reference origin resolution for the `Cdn` pattern (design
+ * 2026-08-18 cdn-app-origin, D3). Given a fronted ECS compute, resolve a
+ * TLS-valid ORIGIN HOSTNAME from the compute's own ingress profile, decide
+ * who owns its DNS record (P1: the construct that declares a hostname owns
+ * its record — a `routing[].host` hostname is the compute's; a derived or
+ * free hostname is the Cdn's), and validate certificate coverage and
+ * listener forwarding at synth — fail closed where decidable, warn where
+ * opaque or partial (P3).
+ *
+ * The resolver is memoized per compute within one `Cdn`: the default origin
+ * and every behaviour referencing the same compute share one resolution and
+ * at most one record.
+ */
+import { Token } from "aws-cdk-lib";
+import { certificateCovers, forwardingVerdict, normaliseDnsName } from "../../resources/aws/compute/ingressProfile.js";
+export { normaliseDnsName };
+import { DNS_APEX } from "@fjall/util";
+import { isWithinZone } from "../../utils/domainTypes.js";
+import { FjallLogger } from "../../utils/validationLogger.js";
+/**
+ * Relative record label for `domain` within `zoneName` (the staticSite
+ * `recordLabelFor` convention): the zone apex maps to the canonical apex
+ * label, sub-names drop the zone suffix.
+ */
+export function recordLabelWithin(domain, zoneName) {
+    if (domain === zoneName) {
+        return DNS_APEX;
+    }
+    const suffix = `.${zoneName}`;
+    return domain.endsWith(suffix) ? domain.slice(0, -suffix.length) : domain;
+}
+const SHARED_CURE = "declare the hostname as a routing host on the receiving service " +
+    "(services[].routing[].host) — one declaration adds the certificate SAN " +
+    "(cluster-minted certificates), the listener rule, and the DNS record. " +
+    "CAUTION: adding a SECOND routing rule to a service flips the listener " +
+    "default action from forward to fixed-404, so a cluster serving its " +
+    "domain through the default action must keep a forwarding path for it, " +
+    'e.g. routing: [{ path: "/*" }, { host: "<origin hostname>" }].';
+export class CdnEcsOriginResolver {
+    options;
+    resolutions = new Map();
+    warnedUnknownCoverage = false;
+    constructor(options) {
+        this.options = options;
+    }
+    resolve(compute) {
+        const memoized = this.resolutions.get(compute);
+        if (memoized !== undefined) {
+            return memoized;
+        }
+        const resolution = this.resolveFresh(compute);
+        this.resolutions.set(compute, resolution);
+        return resolution;
+    }
+    /** Every Cdn-owned record the resolutions so far require, one per compute. */
+    getRecordPlans() {
+        const plans = [];
+        for (const resolution of this.resolutions.values()) {
+            if (resolution.recordPlan !== undefined) {
+                plans.push(resolution.recordPlan);
+            }
+        }
+        return plans;
+    }
+    resolveFresh(compute) {
+        const { cdnId } = this.options;
+        const profile = compute.getIngressProfile();
+        if (profile === undefined) {
+            // E1 — pre-existing shape, kept: a cluster with no ALB cannot origin.
+            throw new Error(`CDN '${cdnId}': the ECS compute origin has no load balancer. ` +
+                "Enable loadBalancer in the compute configuration, or front a " +
+                "different resource.");
+        }
+        if (profile.internal) {
+            // E2 — CloudFront has no path into a VPC-internal ALB.
+            throw new Error(`CDN '${cdnId}': the ECS compute origin's load balancer is internal ` +
+                "— CloudFront reaches origins over the public internet and cannot " +
+                "address an internal ALB. Make the cluster's load balancer " +
+                'internet-facing (drop loadBalancer: "internal"), or front a ' +
+                "different resource.");
+        }
+        const { hostname, computeOwnsRecord } = this.selectHostname(compute, profile);
+        // Origin-loop guard (C4, extended): the resolved hostname must not be
+        // one of the distribution's own alias names.
+        if (this.options.aliasNames.has(normaliseDnsName(hostname))) {
+            throw new Error(`CDN '${cdnId}': resolved origin hostname '${hostname}' is also one ` +
+                "of the distribution's own domain names — once DNS points that " +
+                "name at the distribution, every request loops CloudFront → " +
+                "CloudFront. Pick a dedicated origin hostname (originHostname), " +
+                "or serve the alias from the compute directly.");
+        }
+        if (profile.listenerPort === 80) {
+            // E4 — no certificate anywhere: the listener serves HTTP only, and a
+            // CloudFront origin fetch over HTTPS has nothing to shake hands with.
+            throw new Error(`CDN '${cdnId}': the ECS compute origin's listener serves HTTP only ` +
+                "(the cluster has no domain, so no certificate resolved). A " +
+                "CloudFront origin needs a TLS-valid HTTPS origin. Give the " +
+                "cluster a domain (cluster.domainConfig), or use originType " +
+                '"alb" with protocolPolicy "HTTP_ONLY" if plaintext origin ' +
+                "traffic is acceptable.");
+        }
+        // Record-ownership feasibility BEFORE coverage/forwarding (design D3
+        // step 3): an out-of-zone hostname's only real cures are an in-zone
+        // name or originRecord: "none" — deciding coverage first would hand the
+        // user E6's routing-host cure, which ECS itself refuses out-of-zone.
+        let recordPlan;
+        if (!computeOwnsRecord && this.effectiveOriginRecord(compute) !== "none") {
+            // The Cdn owns the record (P1). Zone facts are guaranteed here: a
+            // 443 listener implies a domain, which implies zone identity.
+            if (profile.hostedZone === undefined ||
+                profile.zoneName === undefined ||
+                !isWithinZone(hostname, profile.zoneName)) {
+                // E5 — a record we cannot mint: outside the cluster's zone.
+                throw new Error(`CDN '${cdnId}': originHostname '${hostname}' is outside the ECS ` +
+                    `origin's hosted zone ('${profile.zoneName ?? "none"}'), so its ` +
+                    "record cannot be minted here. Use a hostname inside the zone, " +
+                    'or set originRecord: "none" and manage the record where the ' +
+                    "zone lives.");
+            }
+            recordPlan = {
+                hostname,
+                hostedZone: profile.hostedZone,
+                zoneName: profile.zoneName,
+                recordName: recordLabelWithin(hostname, profile.zoneName),
+                loadBalancer: profile.loadBalancer
+            };
+        }
+        const coverage = certificateCovers(profile.certificateCoverage, hostname);
+        if (coverage === "not-covered") {
+            // E6 — provably uncovered: every attached certificate is enumerated
+            // and none matches. TLS to the origin fails on every request.
+            throw new Error(`CDN '${cdnId}': no certificate on the ECS origin's listener covers ` +
+                `'${hostname}' (attached certificates cover: ` +
+                `${profile.certificateCoverage.kind === "unknown" ? "unknown" : profile.certificateCoverage.hostnames.join(", ") || "nothing"}). ` +
+                `Every origin fetch would fail TLS validation. Cure: ${SHARED_CURE}`);
+        }
+        if (coverage === "unknown" && !this.warnedUnknownCoverage) {
+            this.warnedUnknownCoverage = true;
+            // W1 — opaque certificates: not decidable at synth, so warn once.
+            FjallLogger.warn(`CDN '${cdnId}': cannot verify that the ECS origin's listener ` +
+                `certificates cover '${hostname}' (imported certificate ARNs are ` +
+                "opaque at synth). If the cluster uses a managed domain, redeploy " +
+                "the domain stack with engine >= 14.2.0 so it publishes " +
+                "certificate-coverage outputs and this becomes checkable; for " +
+                "imported certificates, verify the SANs cover the hostname — TLS " +
+                "fails at runtime if not.");
+        }
+        const verdict = forwardingVerdict(profile, hostname);
+        if (verdict.verdict === "none") {
+            // E7 — the listener's default action is a fixed 404 and no rule
+            // forwards the hostname: every origin fetch answers 404.
+            throw new Error(`CDN '${cdnId}': the ECS origin's listener would answer 404 for ` +
+                `'${hostname}' — its default action is a fixed 404 and no routing ` +
+                `rule forwards that hostname. Cure: ${SHARED_CURE}`);
+        }
+        if (verdict.verdict === "partial") {
+            // W2 — some paths forward, others hit the fixed-404 default.
+            FjallLogger.warn(`CDN '${cdnId}': origin traffic for '${hostname}' forwards only for ` +
+                `some paths (matching rules: ${verdict.patterns.join("; ")}); ` +
+                "requests outside those patterns answer the listener's fixed-404 " +
+                "default. Verify the patterns against the distribution's " +
+                "behaviours.");
+        }
+        return {
+            hostname,
+            // The hostname is certificate-covered, so the resource layer's
+            // HTTPS_ONLY default is exactly right — no protocol override.
+            originConfig: { type: "http", domainName: hostname },
+            ...(recordPlan !== undefined && { recordPlan }),
+            computeOwnsRecord
+        };
+    }
+    explicitHostnameFor(compute) {
+        return this.options.overrides?.get(compute)?.originHostname;
+    }
+    effectiveOriginRecord(compute) {
+        return this.options.overrides?.get(compute)?.originRecord;
+    }
+    selectHostname(compute, profile) {
+        const { cdnId } = this.options;
+        const explicit = this.explicitHostnameFor(compute);
+        const originRecord = this.effectiveOriginRecord(compute);
+        if (explicit !== undefined) {
+            if (Token.isUnresolved(explicit)) {
+                throw new Error(`CDN '${cdnId}': originHostname must be a literal hostname (got ` +
+                    "an unresolved token). Coverage, forwarding, and the origin " +
+                    "record are synth-time decisions — pass the concrete name.");
+            }
+            // DNS names are case-insensitive (RFC 4343): every membership test
+            // compares normalised, so a case-differing spelling cannot slip past
+            // the redirect/ownership guards the way it cannot slip past ACM.
+            const explicitNormalised = normaliseDnsName(explicit);
+            if (profile.redirectHosts.some((host) => normaliseDnsName(host) === explicitNormalised)) {
+                // E10 — redirect hosts never serve traffic: the listener answers
+                // them with a 301 to the cluster domain, so an origin pointed there
+                // loops every viewer request through CloudFront → 301 → CloudFront.
+                throw new Error(`CDN '${cdnId}': originHostname '${explicit}' is a redirectHosts ` +
+                    "entry on the ECS origin — the listener 301s it to " +
+                    `'${profile.domainName ?? "the cluster domain"}' and it never ` +
+                    "serves traffic. Use a served hostname: a routing host, or the " +
+                    "derived origin name (omit originHostname).");
+            }
+            const computeOwnsRecord = profile.routedHosts.some((host) => normaliseDnsName(host) === explicitNormalised);
+            if (computeOwnsRecord && originRecord !== undefined) {
+                // E8 — the compute already owns that hostname's record.
+                throw new Error(`CDN '${cdnId}': originRecord is set, but originHostname ` +
+                    `'${explicit}' is a routing host — the compute already owns its ` +
+                    "record (P1: the construct that declares a hostname owns its " +
+                    "record). Drop originRecord.");
+            }
+            return { hostname: explicit, computeOwnsRecord };
+        }
+        // Auto-resolution: routed hosts that are not the distribution's own
+        // aliases. (Redirect hosts can never appear — ECS enforces
+        // serve-XOR-redirect at synth.)
+        const candidates = profile.routedHosts.filter((host) => !this.options.aliasNames.has(normaliseDnsName(host)));
+        if (candidates.length === 1 && candidates[0] !== undefined) {
+            if (originRecord !== undefined) {
+                // E8 — same ownership rule as the explicit arm.
+                throw new Error(`CDN '${cdnId}': originRecord is set, but the origin resolved to ` +
+                    `routing host '${candidates[0]}' — the compute already owns its ` +
+                    "record. Drop originRecord.");
+            }
+            return { hostname: candidates[0], computeOwnsRecord: true };
+        }
+        if (candidates.length > 1) {
+            // E3 — ambiguous: several served hostnames could be the origin.
+            throw new Error(`CDN '${cdnId}': the ECS origin serves several hostnames ` +
+                `(${candidates.join(", ")}) and the origin is ambiguous. Set ` +
+                "originHostname — on the distribution for its default origin, or " +
+                "on the behaviour entry — to the one the distribution should " +
+                "fetch from.");
+        }
+        if (profile.domainName === undefined) {
+            // E4 — nothing to derive from (and nothing a viewer could reach over
+            // TLS anyway; the no-domain listener is HTTP-only, so an explicit
+            // originHostname would only trade this error for the port-80 one —
+            // the catalogue cures are the honest ones).
+            throw new Error(`CDN '${cdnId}': the ECS compute origin has no domain to derive an ` +
+                "origin hostname from (and no certificate, so nothing serves " +
+                "HTTPS). Give the cluster a domain (cluster.domainConfig), or " +
+                'use originType "alb" with protocolPolicy "HTTP_ONLY" if ' +
+                "plaintext origin traffic is acceptable.");
+        }
+        return {
+            hostname: `origin.${profile.domainName}`,
+            computeOwnsRecord: false
+        };
+    }
+}

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

@@ -5,7 +5,7 @@ import { type IApplicationLoadBalancer, type ApplicationListener } from "aws-cdk
 import { Construct } from "constructs";
 import { type IEcsCompute } from "./interfaces/compute.js";
 import { type SecretImport } from "../../resources/aws/secrets/index.js";
-import EcsCluster, { type EcsClusterProps } from "../../resources/aws/compute/ecs.js";
+import EcsCluster, { type EcsClusterProps, type EcsIngressProfile } from "../../resources/aws/compute/ecs.js";
 export { ScalingType } from "./computeEcsTypes.js";
 export type { EcsCapacityProvider, Ec2CapacityConfig, RemoteConnectionSpec, EcsCapacityProviderConfig, EcsContainerConfig, ContainerDependency, ContainerVolume, EcsScheduledTaskConfig, EcsLifecycleHookMigrationsConfig, EcsPostDeployMigrationsConfig, EcsHookMigrationsConfig, EcsMigrationsConfig, EcsMigrationsMode, EcsCircuitBreakerConfig, EcsScalingConfig, EcsClusterConfig, EcsRoutingConfig, EcsServiceConfig, ServiceLogAlarm, EcsComputeProps } from "./computeEcsTypes.js";
 import { ScalingType, type EcsCapacityProviderConfig, type EcsCapacityProvider, type EcsContainerConfig, type EcsScalingConfig, type EcsServiceConfig, type EcsComputeProps, type QueueScalingConfig } from "./computeEcsTypes.js";
@@ -227,6 +227,14 @@ export declare class EcsCompute extends Construct implements IEcsCompute {
     getCluster(): ICluster;
     /** Get the Application Load Balancer if one was created. */
     getLoadBalancer(): IApplicationLoadBalancer | undefined;
+    /**
+     * Synth-time ingress profile (design 2026-08-18 cdn-app-origin, D2):
+     * listener facts, zone identity, and certificate coverage for constructs
+     * that front this compute — the `Cdn` construct-reference origin lane
+     * resolves its origin hostname against it. Undefined when the compute has
+     * no load balancer.
+     */
+    getIngressProfile(): EcsIngressProfile | undefined;
     /** Get a specific service by name. */
     getService(name: string): IBaseService | undefined;
     /** Get all services in the cluster. */

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

@@ -1653,6 +1653,16 @@ export class EcsCompute extends Construct {
     getLoadBalancer() {
         return this.ecsCluster.getLoadBalancer();
     }
+    /**
+     * Synth-time ingress profile (design 2026-08-18 cdn-app-origin, D2):
+     * listener facts, zone identity, and certificate coverage for constructs
+     * that front this compute — the `Cdn` construct-reference origin lane
+     * resolves its origin hostname against it. Undefined when the compute has
+     * no load balancer.
+     */
+    getIngressProfile() {
+        return this.ecsCluster.getIngressProfile();
+    }
     /** Get a specific service by name. */
     getService(name) {
         return this.ecsCluster.getService(name);

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

@@ -3,6 +3,7 @@ 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";
+import { FjallLogger } from "../../utils/validationLogger.js";
 const US_EAST_1 = "us-east-1";
 /**
  * Certificate composition shared by `composeApexDomain` and
@@ -42,6 +43,21 @@ export function composeDomainCertificates(scope, composition) {
                 costAllocationEnvironment: composition.costAllocationEnvironment,
                 costAllocationDomain: composition.costAllocationDomain
             });
+            // D5 (design 2026-08-18 cdn-app-origin): publish the hostnames this
+            // certificate covers beside its ARN export — SAME per-certificate
+            // identity, so a consumer can bind coverage for exactly the
+            // certificates whose ARNs it binds, never a zone-level aggregate
+            // (which would list hostnames of certificates that are not on the
+            // consumer's listener and over-claim coverage).
+            const serialisedHosts = JSON.stringify(certificateHosts(normalised));
+            if (hostsOutputWithinCfnLimit(serialisedHosts, normalised.domainName)) {
+                new CfnOutput(scope, `${certId}Hosts`, {
+                    key: `${certId}Hosts`,
+                    value: serialisedHosts,
+                    exportName: getDomainExportNames(normalised.domainName)
+                        .certificateHosts
+                });
+            }
             certificates.set(normalised.domainName, dc.certificate);
             return;
         }
@@ -80,6 +96,7 @@ function mintCloudFrontCertificate(scope, composition, cert, certId) {
             exportCertificateArn: false
         });
         emitUsEast1Export(scope, composition, dc);
+        emitUsEast1HostsOutput(scope, composition, cert);
         return dc.certificate;
     }
     const pairedStack = resolvePairedUsEast1Stack(domainStack, composition, cert);
@@ -104,8 +121,60 @@ function mintCloudFrontCertificate(scope, composition, cert, certId) {
         exportCertificateArn: false
     });
     emitUsEast1Export(pairedStack, composition, dc);
+    // The hosts output lands on the MAIN domain stack even though the
+    // certificate lives in the paired stack: the SAN list is a synth-time
+    // literal (no cross-region reference), and the CLI's existing main-stack
+    // DescribeStacks read must reach it without touching the paired-stack
+    // reader (design 2026-08-18 cdn-app-origin, D5).
+    emitUsEast1HostsOutput(domainStack, composition, cert);
     return dc.certificate;
 }
+/** Hostnames a certificate covers: its domainName plus every SAN, deduped. */
+function certificateHosts(cert) {
+    return [
+        ...new Set([cert.domainName, ...(cert.subjectAlternativeNames ?? [])])
+    ];
+}
+/**
+ * Guard on CloudFormation's 1024-byte output-value limit (1000-byte
+ * threshold for headroom under the hard cap): a certificate with enough —
+ * or long enough — SANs would otherwise fail the WHOLE domain-stack deploy
+ * with an opaque CFN error. Per the D5 fail-open contract the hosts output
+ * is SKIPPED instead: the deploy keeps succeeding, and consumers see
+ * coverage-unknown for this certificate (W1 — its coverage stays
+ * unverifiable at CDN synth), never a false verdict.
+ */
+const HOSTS_OUTPUT_MAX_BYTES = 1000;
+function hostsOutputWithinCfnLimit(serialisedHosts, certificateDomainName) {
+    const bytes = Buffer.byteLength(serialisedHosts, "utf8");
+    if (bytes <= HOSTS_OUTPUT_MAX_BYTES)
+        return true;
+    FjallLogger.warn(`Certificate '${certificateDomainName}': its hosts list serialises to ` +
+        `${bytes} bytes, over the ${HOSTS_OUTPUT_MAX_BYTES}-byte guard for ` +
+        "CloudFormation's 1024-byte output-value limit, so its " +
+        "certificate-hosts output is skipped and the certificate's coverage " +
+        "stays unverifiable at CDN synth (W1) — the deploy itself keeps " +
+        "succeeding. Trim the certificate's SAN list, or split the hosts " +
+        "across multiple certificates.");
+    return false;
+}
+/**
+ * The zone-level `<zone>-us-east-1-certificate-hosts` output (D5 companion
+ * to `emitUsEast1Export`): the hostnames the viewer certificate covers,
+ * always minted on the MAIN domain stack so the D2 DescribeStacks read
+ * reaches it in one call regardless of where the certificate itself lives.
+ */
+function emitUsEast1HostsOutput(scope, composition, cert) {
+    const serialisedHosts = JSON.stringify(certificateHosts(cert));
+    if (!hostsOutputWithinCfnLimit(serialisedHosts, cert.domainName))
+        return;
+    const exports = getDomainExportNames(composition.effectiveZoneName);
+    new CfnOutput(scope, `${composition.safeZone}UsEast1CertificateHosts`, {
+        key: `${composition.safeZone}UsEast1CertificateHosts`,
+        value: serialisedHosts,
+        exportName: exports.usEast1CertificateHosts
+    });
+}
 /**
  * The zone-level `<zone>-us-east-1-certificate-arn` export
  * (`getDomainExportNames(...).usEast1CertificateArn` — the SSOT

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

@@ -19,6 +19,7 @@ import { type IAutoScalingGroup } from "aws-cdk-lib/aws-autoscaling";
 import { type ISecurityGroup, type IConnectable } from "aws-cdk-lib/aws-ec2";
 import { type IGrantable, type Grant } from "aws-cdk-lib/aws-iam";
 import { type Construct } from "constructs";
+import type { EcsIngressProfile } from "../../../resources/aws/compute/ingressProfile.js";
 /**
  * Compute type discriminator.
  * Used to determine which specific interface applies.
@@ -66,6 +67,12 @@ export interface IEcsCompute extends ICompute, IConnectable {
      * for HTTPS, 80 for HTTP); does not indicate protocol.
      */
     getPrimaryListenerPort(): number | undefined;
+    /**
+     * Synth-time ingress profile (design 2026-08-18 cdn-app-origin, D2):
+     * listener facts, zone identity, and certificate coverage for constructs
+     * that front this compute. Undefined when there is no load balancer.
+     */
+    getIngressProfile(): EcsIngressProfile | undefined;
 }
 /**
  * Lambda compute interface.

package/dist/lib/resources/aws/compute/ecs.d.ts

@@ -4,11 +4,13 @@ import { Construct } from "constructs";
 import type { StackBuilder } from "../base/awsStack.js";
 import type { ApplicationListener, ApplicationLoadBalancer } from "aws-cdk-lib/aws-elasticloadbalancingv2";
 import { type EcsClusterProps } from "./ecsTypes.js";
+import { type EcsIngressProfile } from "./ingressProfile.js";
 export * from "./ecsTypes.js";
 export * from "./ecsConstants.js";
 export * from "./ecsContext.js";
 export * from "./ecsTaskDefinition.js";
 export * from "./ecsNetworking.js";
+export * from "./ingressProfile.js";
 export { CapacityProviderDependencyAspect } from "./ecsCapacityProviderAspect.js";
 export { validateEcsClusterProps, validateEcsDomainConfig, validateSsmPathComponent } from "./ecsValidation.js";
 export * from "./ecsServiceFactory.js";
@@ -54,6 +56,7 @@ export default class EcsCluster extends Construct implements IConnectable {
     private loadBalancer?;
     private loadBalancerListener?;
     private certificate?;
+    private ingressProfile?;
     private asgState;
     private services;
     private scheduledTaskDefinitions;
@@ -69,6 +72,14 @@ export default class EcsCluster extends Construct implements IConnectable {
     getLoadBalancer(): ApplicationLoadBalancer | undefined;
     /** Get the load balancer's listener. Undefined if disabled. */
     getListener(): ApplicationListener | undefined;
+    /**
+     * Synth-time ingress profile (design 2026-08-18 cdn-app-origin, D2):
+     * listener facts (default-action predicate, rule structure, port), the
+     * cluster's zone identity, and certificate coverage — for downstream
+     * constructs that front this cluster. Undefined when the cluster has no
+     * load balancer.
+     */
+    getIngressProfile(): EcsIngressProfile | undefined;
     /** Get a specific service by name. */
     getService(name: string): FargateService | Ec2Service | undefined;
     /** Get all services in this cluster. */

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

@@ -12,12 +12,14 @@ import { validateEcsClusterProps } from "./ecsValidation.js";
 import { createExecutionRole, createTaskRole, createTaskDefinition, addContainersToTask, isServiceFargate, isServiceEc2 } from "./ecsTaskDefinition.js";
 import { addLoadBalancer, addLoadBalancerListener, addHostedZone, addDirectAccessOutputs, addRedirectHostRules, registerServiceWithALB } from "./ecsNetworking.js";
 import { createService, addServiceScaling, getOrCreateAsgCapacityProvider } from "./ecsServiceFactory.js";
+import { buildIngressProfile, warnWhenRecordedApexUnforwarded } from "./ingressProfile.js";
 // Re-export all types/enums/constants so existing consumers are not broken
 export * from "./ecsTypes.js";
 export * from "./ecsConstants.js";
 export * from "./ecsContext.js";
 export * from "./ecsTaskDefinition.js";
 export * from "./ecsNetworking.js";
+export * from "./ingressProfile.js";
 export { CapacityProviderDependencyAspect } from "./ecsCapacityProviderAspect.js";
 export { validateEcsClusterProps, validateEcsDomainConfig, validateSsmPathComponent } from "./ecsValidation.js";
 export * from "./ecsServiceFactory.js";
@@ -64,6 +66,7 @@ export default class EcsCluster extends Construct {
     loadBalancer;
     loadBalancerListener;
     certificate;
+    ingressProfile;
     // EC2-specific (mutable state shared with ecsServiceFactory)
     asgState = {
         providers: new Map(),
@@ -113,6 +116,20 @@ export default class EcsCluster extends Construct {
             if (hzResult?.redirectRules !== undefined) {
                 addRedirectHostRules(this.ctx, this.loadBalancerListener, hzResult.redirectRules, this.priorityState);
             }
+            // D2 (design 2026-08-18 cdn-app-origin): the synth-time answer to
+            // "what does this cluster's listener actually do?", assembled from the
+            // same facts the emitters above used — never re-derived from props by
+            // downstream consumers (the Cdn construct-reference origin lane).
+            this.ingressProfile = buildIngressProfile({
+                loadBalancer: this.loadBalancer,
+                internal: props.cluster?.loadBalancer === "internal",
+                services: props.services,
+                certificateAttached: this.certificate !== undefined,
+                zoneFacts: hzResult?.ingress
+            });
+            if (hzResult?.ingress !== undefined) {
+                warnWhenRecordedApexUnforwarded(this.ingressProfile, hzResult.ingress.apexRecordMinted, props.clusterName);
+            }
         }
         else if (this.directAccessEnabled) {
             addDirectAccessOutputs(this.ctx, this.asgState.autoScalingGroup);
@@ -154,6 +171,16 @@ export default class EcsCluster extends Construct {
     getListener() {
         return this.loadBalancerListener;
     }
+    /**
+     * Synth-time ingress profile (design 2026-08-18 cdn-app-origin, D2):
+     * listener facts (default-action predicate, rule structure, port), the
+     * cluster's zone identity, and certificate coverage — for downstream
+     * constructs that front this cluster. Undefined when the cluster has no
+     * load balancer.
+     */
+    getIngressProfile() {
+        return this.ingressProfile;
+    }
     /** Get a specific service by name. */
     getService(name) {
         return this.services.get(name)?.service;

package/dist/lib/resources/aws/compute/ecsNetworking.d.ts

@@ -5,6 +5,7 @@ import { type ARecord, type IHostedZone } from "aws-cdk-lib/aws-route53";
 import type { AutoScalingGroup } from "aws-cdk-lib/aws-autoscaling";
 import type { ContainerDefinition, FargateService, Ec2Service } from "aws-cdk-lib/aws-ecs";
 import { SecurityGroup } from "../networking/securityGroup.js";
+import { type EcsIngressZoneFacts } from "./ingressProfile.js";
 import type { EcsConstructContext } from "./ecsContext.js";
 import type { EcsServiceProps } from "./ecsTypes.js";
 import { type PriorityState } from "./hostHeaderListenerRule.js";
@@ -40,6 +41,7 @@ export declare function addHostedZone(ctx: EcsConstructContext, loadBalancer?: A
     aRecord?: ARecord;
     additionalListenerCertificates?: IListenerCertificate[];
     redirectRules?: EcsRedirectRuleConfig;
+    ingress?: EcsIngressZoneFacts;
 };
 export declare function addDirectAccessOutputs(ctx: EcsConstructContext, autoScalingGroup?: AutoScalingGroup): void;
 export declare function registerServiceWithALB(ctx: EcsConstructContext, listener: ApplicationListener, serviceName: string, serviceProps: EcsServiceProps, service: FargateService | Ec2Service, primaryContainer: ContainerDefinition, priorityState: PriorityState): IApplicationTargetGroup;

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

@@ -9,7 +9,8 @@ import { DomainCertificate } from "../networking/domainCertificate.js";
 import { AliasRecord } from "../networking/dnsRecord/aliasRecord.js";
 import { SecurityGroup } from "../networking/securityGroup.js";
 import { DNS_APEX, isManagedDomainBinding, isWithinZone } from "../../../utils/domainTypes.js";
-import { readInjectedManagedDomainBinding } from "../../../utils/managedDomainContext.js";
+import { readInjectedManagedDomainBinding, readInjectedManagedDomainCoverage } from "../../../utils/managedDomainContext.js";
+import { computeListenerDefault404 } from "./ingressProfile.js";
 import { ResourceNaming } from "../../../utils/resourceNaming.js";
 import { stackScopedExportName } from "../../../utils/exportNaming.js";
 import { registerAlbAliasTarget } from "../../../utils/albAliasTargetRegistry.js";
@@ -99,24 +100,15 @@ export function addLoadBalancer(ctx, anyServiceUsesEc2, asgSecurityGroup) {
 }
 export function addLoadBalancerListener(ctx, loadBalancer, certificate, additionalCertificates) {
     const port = certificate ? 443 : 80;
-    const servicesWithPorts = ctx.props.services.filter((s) => s.containers.some((c) => c.port !== undefined));
-    const willHaveMultipleRoutes = servicesWithPorts.length > 1 ||
-        servicesWithPorts.some((s) => {
-            const rules = Array.isArray(s.routing)
-                ? s.routing
-                : s.routing
-                    ? [s.routing]
-                    : [];
-            return rules.length > 1;
-        });
-    // CDK rejects listeners with neither a default action nor target groups.
-    const noServicePorts = servicesWithPorts.length === 0;
     return addRoutingListener(loadBalancer, `${ctx.props.clusterName}Listener`, {
         port,
         ...(certificate && { certificate }),
         ...(additionalCertificates !== undefined &&
             additionalCertificates.length > 0 && { additionalCertificates }),
-        default404: willHaveMultipleRoutes || noServicePorts
+        // Single home for the default-action predicate (ingressProfile.ts): the
+        // ingress profile exports the same value, so downstream verdicts model
+        // the listener the emitter actually built (design cdn-app-origin, P5).
+        default404: computeListenerDefault404(ctx.props.services)
     });
 }
 /**
@@ -302,6 +294,10 @@ export function addHostedZone(ctx, loadBalancer) {
         }
     }
     const subjectAlternativeNames = [...routedHosts, ...redirectHosts].filter((h) => h !== domainName);
+    // Captured BEFORE the BYO override below: whether the managed lane
+    // attached the binding's (or export fallback's) certificate — the D5
+    // coverage context describes exactly that certificate, never a BYO one.
+    const managedCertificateAttached = certificate !== undefined;
     if (domainConfig?.certificate) {
         certificate = domainConfig.certificate;
     }
@@ -333,6 +329,62 @@ export function addHostedZone(ctx, loadBalancer) {
         }).certificate;
     }
     const additionalListenerCertificates = resolveAdditionalListenerCertificates(ctx.scope, props.clusterName, domainConfig?.additionalCertificates, managed);
+    // D5 certificate coverage (design 2026-08-18 cdn-app-origin): fold the SAN
+    // set of every certificate the listener will carry, where knowable at
+    // synth. The cluster-minted certificate's set is the literal minted above;
+    // managed certificates are described by the CLI-injected coverage context
+    // (absent → opaque, a domain stack predating the hosts outputs); BYO
+    // imports are opaque by nature. Fail-open to "partial"/"unknown", never to
+    // a false "covered" — consumers (the Cdn origin lane) error only on
+    // enumerated non-coverage and warn on opacity.
+    //
+    // Provenance gate: the coverage context describes the zone's CURRENT
+    // certificates — the same D2 resolution that produces an injected binding.
+    // An EXPLICIT `domainConfig.managedDomain` BINDING may pin an OLDER
+    // certificateArn (or usEast1CertificateArn) the current coverage does not
+    // describe, so folding it would over-claim and invert P3 (TLS fails at
+    // runtime after E6 passes the hostname as covered). Explicit bindings
+    // therefore stay opaque, exactly as if no coverage context existed. The
+    // explicit EXPORTS form is unaffected: Fn.importValue resolves at deploy
+    // to the zone's current certificate — the one the coverage describes.
+    const explicitPinnedBinding = domainConfig?.managedDomain !== undefined &&
+        isManagedDomainBinding(domainConfig.managedDomain);
+    const injectedCoverage = managed && !explicitPinnedBinding
+        ? readInjectedManagedDomainCoverage(ctx.scope.node, managed.zoneName, `Cluster '${props.clusterName}'`)
+        : undefined;
+    const knownCertificateHosts = [];
+    let anyOpaqueCertificate = false;
+    if (domainConfig?.certificate) {
+        anyOpaqueCertificate = true;
+    }
+    else if (managedCertificateAttached) {
+        if (injectedCoverage?.certificateHosts !== undefined) {
+            knownCertificateHosts.push(...injectedCoverage.certificateHosts);
+        }
+        else {
+            anyOpaqueCertificate = true;
+        }
+    }
+    else {
+        knownCertificateHosts.push(domainName, ...subjectAlternativeNames);
+    }
+    for (const source of domainConfig?.additionalCertificates ?? []) {
+        if ("certificateArn" in source) {
+            anyOpaqueCertificate = true;
+        }
+        else if (injectedCoverage?.usEast1CertificateHosts !== undefined) {
+            knownCertificateHosts.push(...injectedCoverage.usEast1CertificateHosts);
+        }
+        else {
+            anyOpaqueCertificate = true;
+        }
+    }
+    const dedupedCertificateHosts = [...new Set(knownCertificateHosts)];
+    const certificateCoverage = anyOpaqueCertificate
+        ? dedupedCertificateHosts.length > 0
+            ? { kind: "partial", hostnames: dedupedCertificateHosts }
+            : { kind: "unknown" }
+        : { kind: "enumerated", hostnames: dedupedCertificateHosts };
     let aRecord;
     if (loadBalancer) {
         const routingPolicy = domainConfig?.routingPolicy;
@@ -430,7 +482,16 @@ export function addHostedZone(ctx, loadBalancer) {
         }),
         ...(redirectHosts.length > 0 && {
             redirectRules: { hostFqdns: redirectHosts, targetHost: domainName }
-        })
+        }),
+        ingress: {
+            hostedZone,
+            zoneName,
+            domainName,
+            routedHosts,
+            redirectHosts,
+            apexRecordMinted: loadBalancer !== undefined && domainConfig?.apexRecord !== "none",
+            certificateCoverage
+        }
     };
 }
 const US_EAST_1 = "us-east-1";