@fjall/components-infrastructure 14.1.0 → 14.2.0

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

@@ -0,0 +1,174 @@
+/**
+ * Synth-time ingress profile for an ECS cluster's ALB (design 2026-08-18
+ * cdn-app-origin, D2). The profile is the one sanctioned answer to "what
+ * does this cluster's listener actually do?" for downstream constructs —
+ * today the `Cdn` construct-reference origin lane, which needs a TLS-valid
+ * origin hostname, certificate coverage, and a forwarding verdict without
+ * re-deriving any of it from props.
+ *
+ * P5 (model the machinery, don't paraphrase it): every fact here is exported
+ * from the SAME computation the emitting code uses — `default404` is the
+ * predicate `addLoadBalancerListener` passes to the listener factory, the
+ * rule structure mirrors `registerServiceWithALB`'s exact branching
+ * (including the single-service conditions-dropped branch), and the covered
+ * SAN set is the one `addHostedZone` mints. Never recompute these facts from
+ * cluster props elsewhere; extend the profile instead.
+ */
+import type { IApplicationLoadBalancer } from "aws-cdk-lib/aws-elasticloadbalancingv2";
+import type { IHostedZone } from "aws-cdk-lib/aws-route53";
+import type { EcsServiceProps } from "./ecsTypes.js";
+/**
+ * What the certificates ATTACHED to the cluster's listener are known to
+ * cover at synth:
+ *
+ * - `enumerated` — every attached certificate's host set is synth-known
+ *   (cluster-minted certs, or managed certs described by the D5 coverage
+ *   context). `hostnames` is complete: a non-matching name is provably
+ *   uncovered.
+ * - `partial` — `hostnames` collects the known certs' hosts, but at least
+ *   one attached certificate is opaque (imported ARN with no coverage
+ *   context), so a non-matching name may still be covered.
+ * - `unknown` — only opaque certificates are attached.
+ */
+export type CertificateCoverage = {
+    kind: "enumerated";
+    hostnames: string[];
+} | {
+    kind: "partial";
+    hostnames: string[];
+} | {
+    kind: "unknown";
+};
+export type CoverageAnswer = "covered" | "unknown" | "not-covered";
+/**
+ * One listener rule as it will actually be emitted. `host` and `path` are
+ * ANDed when both present (`buildRoutingConditions`). Rules the emitter
+ * DROPS — a single ports-bearing service with ≤1 routing rule loses its
+ * conditions and becomes the listener default (`registerServiceWithALB`) —
+ * are deliberately absent here, exactly as they are absent from the ALB.
+ */
+export interface EcsIngressRule {
+    host?: string;
+    path?: string;
+    kind: "forward" | "redirect";
+}
+export interface EcsIngressProfile {
+    loadBalancer: IApplicationLoadBalancer;
+    /** `cluster.loadBalancer === "internal"` — unreachable as a CloudFront origin. */
+    internal: boolean;
+    /** 443 iff a certificate resolved — the cluster ALB has exactly one listener. */
+    listenerPort: 443 | 80;
+    /**
+     * The cluster's resolved zone — the SAME `IHostedZone` instance the
+     * cluster's own records claim with, so a downstream record (the Cdn's
+     * origin record) claims under the identical zone identity. The DNS claim
+     * registry keys on the literal hosted-zone ID; a name-derived re-import
+     * would register under a different key and silently defeat same-name
+     * collision detection.
+     */
+    hostedZone?: IHostedZone;
+    zoneName?: string;
+    domainName?: string;
+    /** Every `services[].routing[].host`, deduped, in declaration order. */
+    routedHosts: string[];
+    redirectHosts: string[];
+    /**
+     * The listener's actual default-action predicate: `true` → fixed-404
+     * default; `false` → the sole target group IS the default action and the
+     * listener forwards EVERY hostname.
+     */
+    default404: boolean;
+    rules: EcsIngressRule[];
+    certificateCoverage: CertificateCoverage;
+}
+/**
+ * Zone-derived profile ingredients assembled by `addHostedZone`, where the
+ * zone, hosts, and certificate coverage are already computed for emission.
+ */
+export interface EcsIngressZoneFacts {
+    hostedZone: IHostedZone;
+    zoneName: string;
+    domainName: string;
+    routedHosts: string[];
+    redirectHosts: string[];
+    /** False when `apexRecord: "none"` yielded the domainName record. */
+    apexRecordMinted: boolean;
+    certificateCoverage: CertificateCoverage;
+}
+/**
+ * The listener's default-action predicate — the SINGLE home of the
+ * computation `addLoadBalancerListener` passes to the listener factory as
+ * `default404`. `true` when ≥2 routes will exist (the emitter then attaches
+ * a fixed-404 default and conditions every rule) or when no service has a
+ * port (CDK rejects a listener with neither a default action nor targets).
+ */
+export declare function computeListenerDefault404(services: EcsServiceProps[]): boolean;
+/**
+ * The listener's rule structure as `registerServiceWithALB` and
+ * `addRedirectHostRules` will emit it. Mirrors the emitters' branching
+ * exactly: a single ports-bearing service with ≤1 rule contributes NO
+ * conditioned rule (its target group is the listener default — even a
+ * declared `routing.host` does not gate it), and every redirect host
+ * contributes a host-matched 301 rule.
+ */
+export declare function enumerateListenerRules(services: EcsServiceProps[], redirectHosts: string[]): EcsIngressRule[];
+/** Lowercase and strip the trailing dot — DNS names are case-insensitive. */
+export declare function normaliseDnsName(name: string): string;
+/**
+ * RFC 6125 certificate-name match: exact, or a single-label `*.` wildcard
+ * (matches exactly one additional label — `*.example.com` covers
+ * `a.example.com`, never `example.com` or `a.b.example.com`). DNS names
+ * compare ASCII case-insensitively (RFC 6125 §6.4.1 via RFC 4343).
+ */
+export declare function certNameMatches(pattern: string, hostname: string): boolean;
+/**
+ * Does the listener's attached-certificate set cover `hostname`?
+ * Fail closed where decidable, honest where opaque (P3): only `enumerated`
+ * coverage may answer `not-covered`; a miss under `partial`/`unknown` is
+ * `unknown` because an opaque certificate may still cover the name.
+ */
+export declare function certificateCovers(coverage: CertificateCoverage, hostname: string): CoverageAnswer;
+export type ForwardingVerdict = {
+    verdict: "forwards";
+} | {
+    verdict: "partial";
+    patterns: string[];
+} | {
+    verdict: "none";
+};
+/**
+ * Would the listener forward `Host: <hostname>` requests, for all paths?
+ * Computed on the real rule model, never a flattened hostname list:
+ *
+ * - no fixed-404 default → the default action forwards every hostname;
+ * - a host-only rule for the hostname, a host-matched catch-all `/*` path
+ *   rule, or a host-less catch-all `/*` path rule, forwards all of its
+ *   paths;
+ * - rules that involve the hostname only together with a narrower path
+ *   condition (ANDed host+path, or host-less non-catch-all paths) forward
+ *   SOME paths — `partial`, with the patterns named so the caller can
+ *   surface them;
+ * - otherwise every request answers the fixed-404 default — `none`.
+ *
+ * Hostnames compare case-insensitively (DNS, RFC 4343) — the rule model
+ * carries the declared spelling, the caller's hostname may differ in case.
+ */
+export declare function forwardingVerdict(profile: EcsIngressProfile, hostname: string): ForwardingVerdict;
+export declare function buildIngressProfile(options: {
+    loadBalancer: IApplicationLoadBalancer;
+    internal: boolean;
+    services: EcsServiceProps[];
+    certificateAttached: boolean;
+    zoneFacts?: EcsIngressZoneFacts;
+}): EcsIngressProfile;
+/**
+ * W3 (design 2026-08-18 cdn-app-origin): a cluster whose listener default is
+ * fixed-404 while its `domainName` has a minted apex record and NO rule
+ * forwards it answers 404 on its own primary domain — usually the aftermath
+ * of adding a second routing rule (which flips the default action from
+ * forward to 404, `computeListenerDefault404`). A warning, not an error:
+ * pre-existing clusters can already be in this state, and narrowing them is
+ * not this check's mandate. Partial forwarding (path-split services) is the
+ * normal multi-route shape and does not warn.
+ */
+export declare function warnWhenRecordedApexUnforwarded(profile: EcsIngressProfile, apexRecordMinted: boolean, clusterName: string): void;

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

@@ -0,0 +1,195 @@
+/**
+ * Synth-time ingress profile for an ECS cluster's ALB (design 2026-08-18
+ * cdn-app-origin, D2). The profile is the one sanctioned answer to "what
+ * does this cluster's listener actually do?" for downstream constructs —
+ * today the `Cdn` construct-reference origin lane, which needs a TLS-valid
+ * origin hostname, certificate coverage, and a forwarding verdict without
+ * re-deriving any of it from props.
+ *
+ * P5 (model the machinery, don't paraphrase it): every fact here is exported
+ * from the SAME computation the emitting code uses — `default404` is the
+ * predicate `addLoadBalancerListener` passes to the listener factory, the
+ * rule structure mirrors `registerServiceWithALB`'s exact branching
+ * (including the single-service conditions-dropped branch), and the covered
+ * SAN set is the one `addHostedZone` mints. Never recompute these facts from
+ * cluster props elsewhere; extend the profile instead.
+ */
+import { FjallLogger } from "../../../utils/validationLogger.js";
+function normaliseRoutingRules(routing) {
+    return Array.isArray(routing) ? routing : routing ? [routing] : [];
+}
+function servicesWithPorts(services) {
+    return services.filter((s) => s.containers.some((c) => c.port !== undefined));
+}
+/**
+ * The listener's default-action predicate — the SINGLE home of the
+ * computation `addLoadBalancerListener` passes to the listener factory as
+ * `default404`. `true` when ≥2 routes will exist (the emitter then attaches
+ * a fixed-404 default and conditions every rule) or when no service has a
+ * port (CDK rejects a listener with neither a default action nor targets).
+ */
+export function computeListenerDefault404(services) {
+    const withPorts = servicesWithPorts(services);
+    const willHaveMultipleRoutes = withPorts.length > 1 ||
+        withPorts.some((s) => normaliseRoutingRules(s.routing).length > 1);
+    return willHaveMultipleRoutes || withPorts.length === 0;
+}
+/**
+ * The listener's rule structure as `registerServiceWithALB` and
+ * `addRedirectHostRules` will emit it. Mirrors the emitters' branching
+ * exactly: a single ports-bearing service with ≤1 rule contributes NO
+ * conditioned rule (its target group is the listener default — even a
+ * declared `routing.host` does not gate it), and every redirect host
+ * contributes a host-matched 301 rule.
+ */
+export function enumerateListenerRules(services, redirectHosts) {
+    const withPorts = servicesWithPorts(services);
+    const isSingleService = withPorts.length === 1;
+    const rules = [];
+    for (const service of withPorts) {
+        const routingRules = normaliseRoutingRules(service.routing);
+        if (isSingleService && routingRules.length <= 1)
+            continue;
+        for (const rule of routingRules) {
+            if (rule.host === undefined && rule.path === undefined)
+                continue;
+            rules.push({
+                ...(rule.host !== undefined && { host: rule.host }),
+                ...(rule.path !== undefined && { path: rule.path }),
+                kind: "forward"
+            });
+        }
+    }
+    for (const host of redirectHosts) {
+        rules.push({ host, kind: "redirect" });
+    }
+    return rules;
+}
+/** Lowercase and strip the trailing dot — DNS names are case-insensitive. */
+export function normaliseDnsName(name) {
+    return name.toLowerCase().replace(/\.$/, "");
+}
+/**
+ * RFC 6125 certificate-name match: exact, or a single-label `*.` wildcard
+ * (matches exactly one additional label — `*.example.com` covers
+ * `a.example.com`, never `example.com` or `a.b.example.com`). DNS names
+ * compare ASCII case-insensitively (RFC 6125 §6.4.1 via RFC 4343).
+ */
+export function certNameMatches(pattern, hostname) {
+    const p = pattern.toLowerCase();
+    const h = hostname.toLowerCase();
+    if (p === h)
+        return true;
+    if (!p.startsWith("*."))
+        return false;
+    const suffix = p.slice(1); // ".example.com"
+    if (!h.endsWith(suffix))
+        return false;
+    const label = h.slice(0, h.length - suffix.length);
+    return label.length > 0 && !label.includes(".");
+}
+/**
+ * Does the listener's attached-certificate set cover `hostname`?
+ * Fail closed where decidable, honest where opaque (P3): only `enumerated`
+ * coverage may answer `not-covered`; a miss under `partial`/`unknown` is
+ * `unknown` because an opaque certificate may still cover the name.
+ */
+export function certificateCovers(coverage, hostname) {
+    if (coverage.kind === "unknown")
+        return "unknown";
+    if (coverage.hostnames.some((p) => certNameMatches(p, hostname))) {
+        return "covered";
+    }
+    return coverage.kind === "enumerated" ? "not-covered" : "unknown";
+}
+/**
+ * Would the listener forward `Host: <hostname>` requests, for all paths?
+ * Computed on the real rule model, never a flattened hostname list:
+ *
+ * - no fixed-404 default → the default action forwards every hostname;
+ * - a host-only rule for the hostname, a host-matched catch-all `/*` path
+ *   rule, or a host-less catch-all `/*` path rule, forwards all of its
+ *   paths;
+ * - rules that involve the hostname only together with a narrower path
+ *   condition (ANDed host+path, or host-less non-catch-all paths) forward
+ *   SOME paths — `partial`, with the patterns named so the caller can
+ *   surface them;
+ * - otherwise every request answers the fixed-404 default — `none`.
+ *
+ * Hostnames compare case-insensitively (DNS, RFC 4343) — the rule model
+ * carries the declared spelling, the caller's hostname may differ in case.
+ */
+export function forwardingVerdict(profile, hostname) {
+    if (!profile.default404)
+        return { verdict: "forwards" };
+    const wanted = normaliseDnsName(hostname);
+    const partial = [];
+    for (const rule of profile.rules) {
+        if (rule.kind !== "forward")
+            continue;
+        const hostMatches = rule.host !== undefined && normaliseDnsName(rule.host) === wanted;
+        if (hostMatches && (rule.path === undefined || rule.path === "/*")) {
+            return { verdict: "forwards" };
+        }
+        if (rule.host === undefined && rule.path === "/*") {
+            return { verdict: "forwards" };
+        }
+        if (hostMatches && rule.path !== undefined) {
+            partial.push(`Host=${rule.host} AND Path=${rule.path}`);
+        }
+        else if (rule.host === undefined && rule.path !== undefined) {
+            partial.push(`Path=${rule.path} (any host)`);
+        }
+    }
+    return partial.length > 0
+        ? { verdict: "partial", patterns: partial }
+        : { verdict: "none" };
+}
+export function buildIngressProfile(options) {
+    const { zoneFacts } = options;
+    const redirectHosts = zoneFacts?.redirectHosts ?? [];
+    return {
+        loadBalancer: options.loadBalancer,
+        internal: options.internal,
+        listenerPort: options.certificateAttached ? 443 : 80,
+        ...(zoneFacts !== undefined && {
+            hostedZone: zoneFacts.hostedZone,
+            zoneName: zoneFacts.zoneName,
+            domainName: zoneFacts.domainName
+        }),
+        routedHosts: zoneFacts?.routedHosts ?? [],
+        redirectHosts,
+        default404: computeListenerDefault404(options.services),
+        rules: enumerateListenerRules(options.services, redirectHosts),
+        certificateCoverage: zoneFacts?.certificateCoverage ?? {
+            // No domain → no certificates attached: the attached set is fully
+            // known (empty), which is the honest enumerated answer, not "unknown".
+            kind: "enumerated",
+            hostnames: []
+        }
+    };
+}
+/**
+ * W3 (design 2026-08-18 cdn-app-origin): a cluster whose listener default is
+ * fixed-404 while its `domainName` has a minted apex record and NO rule
+ * forwards it answers 404 on its own primary domain — usually the aftermath
+ * of adding a second routing rule (which flips the default action from
+ * forward to 404, `computeListenerDefault404`). A warning, not an error:
+ * pre-existing clusters can already be in this state, and narrowing them is
+ * not this check's mandate. Partial forwarding (path-split services) is the
+ * normal multi-route shape and does not warn.
+ */
+export function warnWhenRecordedApexUnforwarded(profile, apexRecordMinted, clusterName) {
+    if (!profile.default404)
+        return;
+    if (profile.domainName === undefined || !apexRecordMinted)
+        return;
+    if (forwardingVerdict(profile, profile.domainName).verdict !== "none")
+        return;
+    FjallLogger.warn(`Cluster '${clusterName}': the listener's default action is a fixed 404 ` +
+        `and no routing rule forwards '${profile.domainName}', but its alias ` +
+        "record is minted — requests to the cluster's own domain will answer " +
+        "404 Not Found. Multiple routing rules flip the listener default from " +
+        "forward to 404; keep a forwarding path for the domain, e.g. a " +
+        'routing rule { path: "/*" } on the service that should serve it.');
+}

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

@@ -20,9 +20,18 @@
  * layer (generator-standards § Infrastructure Layer Boundaries).
  */
 import type { Node } from "constructs";
-import type { ManagedDomainBinding } from "@fjall/util";
+import type { ManagedDomainBinding, ManagedDomainCoverage } from "@fjall/util";
 export declare const MANAGED_DOMAIN_CONTEXT_PREFIX: "fjall:managedDomain:";
 export declare function getManagedDomainContextKey(zoneName: string): string;
+/**
+ * Companion channel to the binding (design 2026-08-18 cdn-app-origin, D5):
+ * the hostnames covered by exactly the certificates the same zone's binding
+ * names. A SEPARATE key on purpose — the binding parser above fails closed
+ * on unknown fields, so coverage could never ride the binding JSON without
+ * breaking older engines fed by a newer CLI.
+ */
+export declare const MANAGED_DOMAIN_COVERAGE_CONTEXT_PREFIX: "fjall:managedDomainCoverage:";
+export declare function getManagedDomainCoverageContextKey(zoneName: string): string;
 /**
  * Read the CLI-injected {@link ManagedDomainBinding} for `domainName`,
  * walking exact → parent zones (mirroring the CLI's
@@ -35,3 +44,19 @@ export declare function getManagedDomainContextKey(zoneName: string): string;
  * `context` prefixes every error, e.g. `Static site 'marketing'`.
  */
 export declare function readInjectedManagedDomainBinding(node: Node, domainName: string, context: string): ManagedDomainBinding | undefined;
+/**
+ * Read the CLI-injected {@link ManagedDomainCoverage} for the zone a binding
+ * already resolved to. Exact-key lookup on purpose (no parent-zone walk):
+ * the CLI injects coverage for precisely the zones it injects bindings for,
+ * and the caller passes the binding's own `zoneName`.
+ *
+ * Absent → undefined (a domain stack that predates the hosts outputs, or a
+ * bare-CDK synth) — consumers treat that as coverage-unknown and warn, never
+ * as not-covered. A present-but-corrupt value still throws (repo posture:
+ * corrupt context fails the synth rather than falling through), but UNKNOWN
+ * FIELDS ARE IGNORED, unlike the binding parser: coverage is advisory
+ * validation input, and forward tolerance here is what lets a future CLI add
+ * coverage fields without breaking older engines — the exact trap that
+ * forced this channel off the binding JSON in the first place.
+ */
+export declare function readInjectedManagedDomainCoverage(node: Node, zoneName: string, context: string): ManagedDomainCoverage | undefined;

package/dist/lib/utils/managedDomainContext.js

@@ -23,6 +23,17 @@ export const MANAGED_DOMAIN_CONTEXT_PREFIX = "fjall:managedDomain:";
 export function getManagedDomainContextKey(zoneName) {
     return `${MANAGED_DOMAIN_CONTEXT_PREFIX}${zoneName}`;
 }
+/**
+ * Companion channel to the binding (design 2026-08-18 cdn-app-origin, D5):
+ * the hostnames covered by exactly the certificates the same zone's binding
+ * names. A SEPARATE key on purpose — the binding parser above fails closed
+ * on unknown fields, so coverage could never ride the binding JSON without
+ * breaking older engines fed by a newer CLI.
+ */
+export const MANAGED_DOMAIN_COVERAGE_CONTEXT_PREFIX = "fjall:managedDomainCoverage:";
+export function getManagedDomainCoverageContextKey(zoneName) {
+    return `${MANAGED_DOMAIN_COVERAGE_CONTEXT_PREFIX}${zoneName}`;
+}
 const REQUIRED_STRING_FIELDS = ["zoneName", "hostedZoneId"];
 const OPTIONAL_STRING_FIELDS = [
     "certificateArn",
@@ -56,6 +67,64 @@ export function readInjectedManagedDomainBinding(node, domainName, context) {
     }
     return undefined;
 }
+/**
+ * Read the CLI-injected {@link ManagedDomainCoverage} for the zone a binding
+ * already resolved to. Exact-key lookup on purpose (no parent-zone walk):
+ * the CLI injects coverage for precisely the zones it injects bindings for,
+ * and the caller passes the binding's own `zoneName`.
+ *
+ * Absent → undefined (a domain stack that predates the hosts outputs, or a
+ * bare-CDK synth) — consumers treat that as coverage-unknown and warn, never
+ * as not-covered. A present-but-corrupt value still throws (repo posture:
+ * corrupt context fails the synth rather than falling through), but UNKNOWN
+ * FIELDS ARE IGNORED, unlike the binding parser: coverage is advisory
+ * validation input, and forward tolerance here is what lets a future CLI add
+ * coverage fields without breaking older engines — the exact trap that
+ * forced this channel off the binding JSON in the first place.
+ */
+export function readInjectedManagedDomainCoverage(node, zoneName, context) {
+    const key = getManagedDomainCoverageContextKey(zoneName);
+    const raw = node.tryGetContext(key);
+    if (raw === undefined)
+        return undefined;
+    let value = raw;
+    if (typeof raw === "string") {
+        try {
+            value = JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`${context}: CDK context '${key}' is not valid JSON (got '${raw}'). ` +
+                "The value must be a JSON ManagedDomainCoverage " +
+                "({ certificateHosts?, usEast1CertificateHosts? }) — re-run the " +
+                "deploy through the Fjall CLI, or correct the hand-set context " +
+                "entry.");
+        }
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`${context}: CDK context '${key}' must be a JSON object ` +
+            `ManagedDomainCoverage (got ${JSON.stringify(value)}). Re-run the ` +
+            "deploy through the Fjall CLI, or correct the hand-set context entry.");
+    }
+    const record = value;
+    const coverage = {};
+    for (const field of [
+        "certificateHosts",
+        "usEast1CertificateHosts"
+    ]) {
+        const fieldValue = record[field];
+        if (fieldValue === undefined)
+            continue;
+        if (!Array.isArray(fieldValue) ||
+            fieldValue.some((h) => typeof h !== "string" || h === "")) {
+            throw new Error(`${context}: CDK context '${key}' field '${field}' must be an array ` +
+                `of non-empty strings when present (got ` +
+                `${JSON.stringify(fieldValue)}). Re-run the deploy through the ` +
+                "Fjall CLI, or correct the hand-set context entry.");
+        }
+        coverage[field] = fieldValue;
+    }
+    return coverage;
+}
 function parseManagedDomainBinding(raw, zoneName, key, context) {
     let value = raw;
     if (typeof raw === "string") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/components-infrastructure",
-  "version": "14.1.0",
+  "version": "14.2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fjall-tech/fjall.git",
@@ -80,8 +80,8 @@
   },
   "dependencies": {
     "@aws-sdk/client-organizations": "^3.1098.0",
-    "@fjall/generator": "^14.1.0",
-    "@fjall/util": "^14.1.0",
+    "@fjall/generator": "^14.2.0",
+    "@fjall/util": "^14.2.0",
     "constructs": "^10.7.2"
   },
   "overrides": {