@fjall/components-infrastructure 2.31.1 → 2.32.0

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

@@ -0,0 +1,390 @@
+import { CfnOutput, Duration, Stack, Tags } from "aws-cdk-lib";
+import { Port } from "aws-cdk-lib/aws-ec2";
+import { Cluster } from "aws-cdk-lib/aws-ecs";
+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 { SqsDestination } from "aws-cdk-lib/aws-s3-notifications";
+import { Construct } from "constructs";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { DatabaseFactory } from "./database.js";
+import { StorageFactory } from "./storage.js";
+import { MessagingFactory } from "./messaging.js";
+import { createBaseExecutionRole } from "../../resources/aws/compute/ecsRoles.js";
+import { createApplicationLoadBalancer } from "../../resources/aws/compute/applicationLoadBalancer.js";
+import { addRoutingListener } from "../../resources/aws/compute/listenerRouting.js";
+import { createLambdaTargetGroup } from "../../resources/aws/compute/lambdaAlbTarget.js";
+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 { HostedZone } from "../../resources/aws/networking/hostedZone.js";
+import { CrossAccountDelegationRecord } from "../../resources/aws/networking/crossAccountDelegationRecord.js";
+import { DomainCertificate } from "../../resources/aws/networking/domainCertificate.js";
+import { Role } from "../../resources/aws/iam/role.js";
+import { toPascalCase } from "../../utils/capitaliseString.js";
+import { DEV_AURORA_DEFAULTS } from "../../resources/aws/database/rdsDefaults.js";
+import { DEV_APP_TAG_KEY, DEV_TAG_KEY, DEV_TAG_VALUE } from "../../utils/devSubstrateTags.js";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/** Construct id + logical database name for the substrate's shared Aurora. */
+const DEV_SUBSTRATE_DB_ID = "DevSubstrateDb";
+const DEV_SUBSTRATE_DATABASE_NAME = "devsubstrate";
+/** Construct ids for the substrate's S3-drop → SQS event channel. */
+const DEV_SUBSTRATE_DROP_ID = "DevSubstrateDrop";
+const DEV_SUBSTRATE_EVENTS_ID = "DevSubstrateEvents";
+/** Construct ids for the substrate's compute/network layer. */
+const DEV_SUBSTRATE_CLUSTER_ID = "DevSubstrateCluster";
+const DEV_SUBSTRATE_SLOT_SG_ID = "DevSubstrateSlotSg";
+const DEV_SUBSTRATE_SLOT_EXEC_ROLE_ID = "DevSubstrateSlotExecutionRole";
+const DEV_SUBSTRATE_SLOT_ECR_ID = "DevSubstrateSlotEcr";
+/** Construct ids for the substrate's ALB layer. */
+const DEV_SUBSTRATE_ALB_SG_ID = "DevSubstrateAlbSg";
+const DEV_SUBSTRATE_ALB_ID = "DevSubstrateAlb";
+const DEV_SUBSTRATE_HTTP_LISTENER_ID = "DevSubstrateHttpListener";
+/** Construct ids + inline source for the substrate's ALB Lambda waker. */
+const DEV_SUBSTRATE_WAKER_ID = "DevSubstrateWaker";
+const DEV_SUBSTRATE_WAKER_TG_ID = "DevSubstrateWakerTargetGroup";
+const DEV_SUBSTRATE_WAKER_SOURCE_FILE = "devSubstrate.waker.source.cjs";
+const DEV_SUBSTRATE_WAKER_TIMEOUT_SECONDS = 30;
+/** Construct ids for the substrate's delegated `dev.<appDomain>` child zone. */
+const DEV_SUBSTRATE_ZONE_ID = "DevSubstrateZone";
+const DEV_SUBSTRATE_DELEGATION_ID = "DevSubstrateDelegation";
+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";
+/**
+ * Default deploy phase when `phase` is omitted — the cert + :443 listener build.
+ * The two-step guard (design R2) sets `"zone"` explicitly for step 1, so the
+ * safe default for a single-shot deploy is the complete substrate.
+ */
+const DEV_SUBSTRATE_DEFAULT_PHASE = "full";
+/**
+ * The substrate's database mode, surfaced to slot-ops as an export so the
+ * hand-created G2 slot knows whether to wire Aurora Data-API creds or a
+ * point-at-existing `DATABASE_URL`. Only `"aurora"` exists today —
+ * `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`)
+ * scope cluster / secret / repo access to this exact prefix, so a drift here
+ * AccessDenies slot ops — single-sourced so the cluster identifier, the master
+ * secret, the ECS cluster name and the slot ECR repo cannot diverge.
+ */
+const devFenceName = (appKebab) => `fjall-dev-${appKebab}`;
+/**
+ * Compile-time parity guard (design T1 / C2-4). `IDevSubstrateProps` — the
+ * `addDevSubstrate` param — and `DevSubstrateSynthProps` — the versioned params
+ * schema the webapp worker (producer) and the Fjall-owned synth entrypoint
+ * (consumer) both import from `@fjall/util` — MUST stay structurally identical, so
+ * a field added to one but not the other fails HERE as a TS error, not as a silent
+ * stale-params synth at deploy.
+ *
+ * Two guards, because neither alone is sufficient:
+ *   - The bidirectional `extends` pair catches a REQUIRED field added to either
+ *     side and any type drift on a shared field (widened/narrowed value type).
+ *   - The key-set equality catches an OPTIONAL field added to one side only —
+ *     which `extends` misses (an extra optional key stays mutually assignable),
+ *     and which is the common case here since almost every prop is optional.
+ */
+const _devSubstratePropsParity = [true, true];
+const _devSubstratePropsKeyParity = true;
+void _devSubstratePropsParity;
+void _devSubstratePropsKeyParity;
+/**
+ * Shared per-app substrate for ephemeral dev/preview slots (fast dev-envs
+ * Phase 3). Stands up the long-lived infrastructure a customer dev team's slots
+ * share — Aurora (A1), an S3→SQS drop (A2), an ECS cluster + slot SG (A2.5), an
+ * ALB with host-header routing (A3) fronted by a Lambda waker (A4), a delegated
+ * child zone (A5) and a wildcard cert (A6) — fenced to the development account.
+ *
+ * Instantiated ONLY via the internal `App.addDevSubstrate(props)`, which scopes
+ * it under the default compute stack so it actually deploys (design VF2). Every
+ * resource it creates carries `fjall:dev = "true"` (the IAM fence tag) and
+ * `fjall:app = <appId>` (the reaper tag) — including resources created through
+ * the app factories in sibling stacks, which are tagged explicitly since the
+ * `Tags.of(this)` aspect only reaches this construct's own scope subtree.
+ */
+export class DevSubstrate extends Construct {
+    app;
+    appId;
+    constructor(scope, id, app, props) {
+        super(scope, id);
+        this.app = app;
+        this.appId = props.appId;
+        this.#tagFenced(this);
+        const database = this.#createDatabase(props);
+        this.#createEventDrop();
+        const { vpc, slotSecurityGroup, cluster, slotExecutionRole, slotRepository } = this.#createComputeNetwork(props, database);
+        const { loadBalancer, httpListener } = this.#createLoadBalancer(vpc, slotSecurityGroup);
+        const wakerTargetGroup = this.#createWaker(props);
+        const { devDomain, httpsListener } = this.#createDomain(props, loadBalancer);
+        this.#emitExports(database, {
+            vpcId: vpc.vpcId,
+            privateSubnetIds: vpc.privateSubnets.map((subnet) => subnet.subnetId),
+            slotSecurityGroupId: slotSecurityGroup.securityGroupId,
+            clusterName: cluster.clusterName,
+            // Slots attach their host-header rule to the frontmost listener — :443 once
+            // the cert exists (the G2 path), else the :80 fallback.
+            slotListenerArn: (httpsListener ?? httpListener).listenerArn,
+            albCloudWatchName: loadBalancer.loadBalancerFullName,
+            // getSnapshotTarget().arn is the only accessor the RelationalDatabase wrapper
+            // exposes for the cluster ARN; it returns databaseCluster.clusterArn.
+            dbClusterArn: database.getSnapshotTarget().arn,
+            dbSecretArn: database.getCredentials().secret.secretArn,
+            slotExecutionRoleArn: slotExecutionRole.roleArn,
+            slotRepositoryUri: slotRepository.repositoryUri,
+            wakerTargetGroupArn: wakerTargetGroup.targetGroupArn,
+            databaseMode: DEV_SUBSTRATE_DATABASE_MODE,
+            devDomain
+        });
+    }
+    #createDatabase(props) {
+        const database = this.app.addDatabase(DatabaseFactory.build(DEV_SUBSTRATE_DB_ID, {
+            type: "Aurora",
+            databaseName: DEV_SUBSTRATE_DATABASE_NAME,
+            clusterIdentifier: devFenceName(props.appKebab),
+            credentialsSecretName: `${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,
+            serverlessV2AutoPauseDuration: Duration.seconds(DEV_AURORA_DEFAULTS.AUTO_PAUSE_SECONDS),
+            enableDataApi: DEV_AURORA_DEFAULTS.ENABLE_DATA_API
+        }));
+        this.#tagFenced(database);
+        return database;
+    }
+    #createEventDrop() {
+        // Bucket and queue MUST share one stack. The OBJECT_CREATED notification and
+        // its auto-generated SQS queue policy reference each other's ARN, so leaving
+        // the queue on the default Messaging stack synthesises a fatal cross-stack
+        // cycle — both are pinned to the compute stack via stackPlacement.
+        const dropBucket = this.app.addStorage(StorageFactory.build(DEV_SUBSTRATE_DROP_ID, {
+            stackPlacement: "compute",
+            versioned: true,
+            encryption: "AES256"
+        }));
+        this.#tagFenced(dropBucket);
+        const eventQueue = this.app.addMessaging(MessagingFactory.build(DEV_SUBSTRATE_EVENTS_ID, {
+            type: "queue"
+        }), { stackPlacement: "compute" });
+        this.#tagFenced(eventQueue);
+        dropBucket.addObjectCreatedNotification(new SqsDestination(eventQueue.getQueue()));
+    }
+    #createComputeNetwork(props, database) {
+        const vpc = this.app.getVpc();
+        // Every resource below is scoped under `this`, so the Tags.of(this) fence
+        // auto-propagates — unlike the factory-created DB/S3/SQS, which land in sibling
+        // stacks and must be tagged explicitly. Names are pinned inside the fjall-dev-*
+        // fence so the scoped slot-ops role's IAM grants reach them.
+        const cluster = new Cluster(this, DEV_SUBSTRATE_CLUSTER_ID, {
+            vpc,
+            clusterName: devFenceName(props.appKebab)
+        });
+        const slotSecurityGroup = new SecurityGroup(this, DEV_SUBSTRATE_SLOT_SG_ID, {
+            vpc,
+            allowAllOutbound: true,
+            description: "Dev substrate slot tasks"
+        });
+        // 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);
+        const { partition, region, account } = Stack.of(this);
+        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/*:*`
+            ]
+        }));
+        // Slot-SG → Aurora ingress. Dormant in Data-API mode (Data API reaches the
+        // cluster over HTTPS, not the VPC) — live only in the deferred
+        // point-at-existing pooled mode (GAP-7). The rule lands in the Database stack
+        // referencing the compute-stack slot SG (Database → Compute, one-directional),
+        // so it adds no cross-stack cycle.
+        database.connections.allowDefaultPortFrom(slotSecurityGroup, "Dev substrate slot tasks");
+        // The Ecr wrapper force-emits a `${id}RepositoryName` CFN export, and export
+        // names are account+region-global — so the id MUST be app-scoped or two
+        // substrates in one dev account collide at deploy. Matches
+        // getDefaultContainerRegistry's `${stackPrefix}Ecr`.
+        const slotEcrId = `${toPascalCase(this.app.getName())}${DEV_SUBSTRATE_SLOT_ECR_ID}`;
+        const slotEcrRepositoryName = `${devFenceName(props.appKebab)}-slots`;
+        // Adopt-mode is an import only — no CFN resource, so it carries no fence tags.
+        const slotRepository = props.adoptSlotEcr === true
+            ? Repository.fromRepositoryName(this, slotEcrId, slotEcrRepositoryName)
+            : new Ecr(this, slotEcrId, { repositoryName: slotEcrRepositoryName });
+        return {
+            vpc,
+            slotSecurityGroup,
+            cluster,
+            slotExecutionRole,
+            slotRepository
+        };
+    }
+    #createLoadBalancer(vpc, slotSecurityGroup) {
+        const albSecurityGroup = new SecurityGroup(this, DEV_SUBSTRATE_ALB_SG_ID, {
+            vpc,
+            allowAllOutbound: true,
+            description: "Dev substrate ALB"
+        });
+        // No loadBalancerName: the dev-tier slot-ops ELB grants are account-wide
+        // (`elasticloadbalancing:*:<acct>:*`), not name-prefixed, so the ALB needs no
+        // 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), "Dev substrate ALB → slot tasks");
+        // Unconditional 404 default — the substrate's only routes are per-slot
+        // host-header rules, so an unmatched host must 404, never fall through (the ECS
+        // path's 404 is conditional on >=2 routes). The :443 listener + wildcard cert
+        // is phase "full" (A6); open:true opens the custom ALB SG on :80.
+        const httpListener = addRoutingListener(loadBalancer, DEV_SUBSTRATE_HTTP_LISTENER_ID, { port: 80, default404: true });
+        return { loadBalancer, httpListener };
+    }
+    #createWaker(props) {
+        const wakerSecretParam = `/fjall/dev/${props.appKebab}/waker/secret`;
+        const source = readFileSync(path.resolve(__dirname, DEV_SUBSTRATE_WAKER_SOURCE_FILE), "utf-8");
+        const { partition, region, account } = Stack.of(this);
+        // NOT VPC-attached (no `vpc` prop): the waker resumes slots via the AWS
+        // control plane (ECS / Aurora / SSM), never over the VPC, and the ALB invokes
+        // it through the Lambda API — not the network path.
+        const waker = new LambdaFunction(this, DEV_SUBSTRATE_WAKER_ID, {
+            runtime: Runtime.NODEJS_22_X,
+            handler: "index.handler",
+            code: Code.fromInline(source),
+            lambdaDescription: "Dev substrate slot waker",
+            roleDescription: "Execution role for the dev substrate slot waker",
+            timeout: DEV_SUBSTRATE_WAKER_TIMEOUT_SECONDS,
+            environment: { WAKER_SECRET_PARAM: wakerSecretParam },
+            inlinePolicy: [
+                new PolicyStatement({
+                    effect: Effect.ALLOW,
+                    actions: ["ssm:GetParameter"],
+                    resources: [
+                        `arn:${partition}:ssm:${region}:${account}:parameter${wakerSecretParam}`
+                    ]
+                }),
+                // Default-key SecureString: scope kms:Decrypt by ViaService, NOT by a CMK
+                // alias — the AWS-managed alias/aws/ssm never matches a per-app alias, so
+                // an alias-scoped grant would AccessDeny the decrypt (design VF4).
+                new PolicyStatement({
+                    effect: Effect.ALLOW,
+                    actions: ["kms:Decrypt"],
+                    resources: ["*"],
+                    conditions: {
+                        StringEquals: { "kms:ViaService": `ssm.${region}.amazonaws.com` }
+                    }
+                })
+            ]
+        });
+        // Standalone TG, NOT attached to the :80 listener — slot-ops wire it in per
+        // sleeping slot via the exported ARN (A7/§5.4), so the listener keeps its
+        // unmatched-host 404. Rationale + the auto ELB-invoke grant: lambdaAlbTarget.ts.
+        return createLambdaTargetGroup(this, DEV_SUBSTRATE_WAKER_TG_ID, {
+            handler: waker
+        });
+    }
+    #createDomain(props, loadBalancer) {
+        if (props.domain === undefined)
+            return {};
+        const { appDomain, parentDelegationRoleArn } = props.domain;
+        const childZoneName = `dev.${appDomain}`;
+        // The delegated child zone: createDelegationRole:false because the PARENT
+        // account owns the delegation role (this is the child). The HostedZone
+        // wrapper's create path auto-emits the `<zone>-nameservers` CFN export the
+        // parent consumes to point NS records at us — no manual export needed.
+        const childZone = new HostedZone(this, DEV_SUBSTRATE_ZONE_ID, {
+            zoneName: childZoneName,
+            createDelegationRole: false
+        });
+        // Case-1 same-org delegation fires only when a parent role ARN is supplied.
+        // The in-stack custom resource assumes the parent account's DelegationRole by
+        // LITERAL ARN (Role.fromRoleArn) — NOT Fn.importValue, which resolves
+        // same-account only and is exactly why the DomainDelegation pattern cannot go
+        // cross-account (design VD2-a). The parent DelegationRole trusts the whole
+        // org (OrganizationPrincipal), so a sibling dev account can assume it. Absent
+        // ARN ⇒ Case 2 (worker UPSERT, B3b) / Case 3 (manual), handled out of band:
+        // the zone + NS export above is all the substrate emits.
+        if (parentDelegationRoleArn !== undefined) {
+            const parentRole = Role.fromRoleArn(this, DEV_SUBSTRATE_PARENT_ROLE_ID, parentDelegationRoleArn);
+            new CrossAccountDelegationRecord(this, DEV_SUBSTRATE_DELEGATION_ID, {
+                delegationRole: parentRole,
+                delegatedZone: childZone.hostedZone,
+                delegatedZoneName: childZoneName,
+                parentHostedZoneName: appDomain
+            });
+        }
+        // Step 2 of the R2 two-step gate: synthesising the cert before the step-1 NS
+        // has propagated hangs ACM DNS-validation for hours, so "zone" stops here.
+        if ((props.phase ?? DEV_SUBSTRATE_DEFAULT_PHASE) !== "full")
+            return { devDomain: childZoneName };
+        // exportCertificateArn:false — consumed in-stack by the :443 listener (slots
+        // reference the exported LISTENER arn, not the cert), and the wildcard `*.`
+        // would otherwise render an invalid CFN export name.
+        const certificate = new DomainCertificate(this, DEV_SUBSTRATE_CERT_ID, {
+            domainName: `*.${childZoneName}`,
+            hostedZone: childZone.hostedZone,
+            exportCertificateArn: false
+        });
+        // 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 });
+        return { devDomain: childZoneName, httpsListener };
+    }
+    /**
+     * Emit the substrate's cross-stack exports under a `FjallDev<App>DevSubstrate*`
+     * prefix. The scoped slot-ops role has no `ec2:Describe*` / discovery reach, so
+     * 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.
+     *
+     * 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
+     * Database stack) — a Compute-stack output referencing a Database-stack ARN
+     * would invert that edge into a synth-fatal cycle. Every other export is a
+     * Compute-stack (or Compute→Network) same-direction ref and rides `this`.
+     */
+    #emitExports(databaseScope, values) {
+        const prefix = `${toPascalCase(this.app.getName())}DevSubstrate`;
+        const emit = (scope, key, value) => {
+            new CfnOutput(scope, `${prefix}${key}`, {
+                value,
+                exportName: `${prefix}${key}`
+            });
+        };
+        emit(this, "VpcId", values.vpcId);
+        // CFN exports are scalar — comma-join the subnet ids; the consumer splits.
+        emit(this, "PrivateSubnetIds", values.privateSubnetIds.join(","));
+        emit(this, "SlotSecurityGroupId", values.slotSecurityGroupId);
+        emit(this, "ClusterName", values.clusterName);
+        emit(this, "SlotListenerArn", values.slotListenerArn);
+        emit(this, "AlbCloudWatchName", values.albCloudWatchName);
+        emit(databaseScope, "DbClusterArn", values.dbClusterArn);
+        emit(databaseScope, "DbSecretArn", values.dbSecretArn);
+        emit(this, "SlotExecutionRoleArn", values.slotExecutionRoleArn);
+        emit(this, "SlotRepositoryUri", values.slotRepositoryUri);
+        emit(this, "WakerTargetGroupArn", values.wakerTargetGroupArn);
+        emit(this, "DatabaseMode", values.databaseMode);
+        if (values.devDomain !== undefined) {
+            emit(this, "DevDomain", values.devDomain);
+        }
+    }
+    #tagFenced(scope) {
+        Tags.of(scope).add(DEV_TAG_KEY, DEV_TAG_VALUE);
+        Tags.of(scope).add(DEV_APP_TAG_KEY, this.appId);
+    }
+}

package/dist/lib/patterns/aws/devSubstrate.waker.source.cjs

@@ -0,0 +1,13 @@
+"use strict";
+
+// Dev-substrate slot waker, invoked as an ALB Lambda target. Milestone
+// placeholder — the real wake-token check + ECS/Aurora resume land in §5.4.
+// ALB Lambda-target responses MUST carry all five fields; a missing
+// statusDescription or isBase64Encoded 502s at the ALB.
+exports.handler = async () => ({
+  statusCode: 200,
+  statusDescription: "200 OK",
+  isBase64Encoded: false,
+  headers: { "content-type": "text/plain; charset=utf-8" },
+  body: "Slot is warming up. Refresh in a moment."
+});

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

@@ -0,0 +1,17 @@
+import { ApplicationLoadBalancer } from "aws-cdk-lib/aws-elasticloadbalancingv2";
+import { type ISecurityGroup, type IVpc } from "aws-cdk-lib/aws-ec2";
+import type { Construct } from "constructs";
+export interface ApplicationLoadBalancerOptions {
+    readonly vpc: IVpc;
+    /** Public (internet-facing, PUBLIC subnets) vs internal (PRIVATE_WITH_EGRESS). */
+    readonly internetFacing: boolean;
+    readonly loadBalancerName?: string;
+    readonly securityGroup?: ISecurityGroup;
+}
+/**
+ * Context-free Application Load Balancer factory shared by the ECS cluster path
+ * and the dev substrate. Subnet placement is derived from `internetFacing`
+ * (PUBLIC when internet-facing, PRIVATE_WITH_EGRESS when internal) — matching the
+ * ECS path's existing derivation so the extraction is byte-identical.
+ */
+export declare function createApplicationLoadBalancer(scope: Construct, id: string, options: ApplicationLoadBalancerOptions): ApplicationLoadBalancer;

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

@@ -0,0 +1,23 @@
+import { ApplicationLoadBalancer } from "aws-cdk-lib/aws-elasticloadbalancingv2";
+import { SubnetType } from "aws-cdk-lib/aws-ec2";
+/**
+ * Context-free Application Load Balancer factory shared by the ECS cluster path
+ * and the dev substrate. Subnet placement is derived from `internetFacing`
+ * (PUBLIC when internet-facing, PRIVATE_WITH_EGRESS when internal) — matching the
+ * ECS path's existing derivation so the extraction is byte-identical.
+ */
+export function createApplicationLoadBalancer(scope, id, options) {
+    return new ApplicationLoadBalancer(scope, id, {
+        vpc: options.vpc,
+        internetFacing: options.internetFacing,
+        ...(options.securityGroup && { securityGroup: options.securityGroup }),
+        ...(options.loadBalancerName && {
+            loadBalancerName: options.loadBalancerName
+        }),
+        vpcSubnets: {
+            subnetType: options.internetFacing
+                ? SubnetType.PUBLIC
+                : SubnetType.PRIVATE_WITH_EGRESS
+        }
+    });
+}

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

@@ -1,4 +1,4 @@
-import { type ApplicationListener, ApplicationLoadBalancer, type IApplicationTargetGroup, ListenerCondition } from "aws-cdk-lib/aws-elasticloadbalancingv2";
+import { type ApplicationListener, type ApplicationLoadBalancer, type IApplicationTargetGroup } from "aws-cdk-lib/aws-elasticloadbalancingv2";
 import { type ISecurityGroup } from "aws-cdk-lib/aws-ec2";
 import { type ICertificate } from "aws-cdk-lib/aws-certificatemanager";
 import { ARecord, type IHostedZone } from "aws-cdk-lib/aws-route53";
@@ -6,15 +6,9 @@ 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 { EcsConstructContext } from "./ecsContext.js";
-import type { EcsRoutingConfig, EcsServiceProps } from "./ecsTypes.js";
-/** Mutable priority state for ALB rule ordering. */
-export interface PriorityState {
-    nextPriority: number;
-    usedPriorities: Set<number>;
-}
-/** Returns the next unused auto-incremented ALB priority, skipping any manually assigned values. */
-export declare function getNextPriority(state: PriorityState): number;
-export declare function buildRoutingConditions(rule: EcsRoutingConfig | undefined): ListenerCondition[];
+import type { EcsServiceProps } from "./ecsTypes.js";
+import { type PriorityState } from "./hostHeaderListenerRule.js";
+export type { PriorityState } from "./hostHeaderListenerRule.js";
 export declare function addLoadBalancer(ctx: EcsConstructContext, anyServiceUsesEc2: boolean, asgSecurityGroup?: ISecurityGroup): {
     loadBalancer: ApplicationLoadBalancer;
     loadBalancerSecurityGroup?: SecurityGroup;

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

@@ -1,5 +1,5 @@
-import { ApplicationLoadBalancer, ApplicationProtocol, ListenerAction, ListenerCondition } from "aws-cdk-lib/aws-elasticloadbalancingv2";
-import { Port, SubnetType } from "aws-cdk-lib/aws-ec2";
+import { ApplicationProtocol, ListenerAction } from "aws-cdk-lib/aws-elasticloadbalancingv2";
+import { Port } from "aws-cdk-lib/aws-ec2";
 import { CfnOutput, Duration, Fn } from "aws-cdk-lib";
 import { Certificate, CertificateValidation } from "aws-cdk-lib/aws-certificatemanager";
 import { ARecord, HostedZone as AWSHostedZone, RecordTarget } from "aws-cdk-lib/aws-route53";
@@ -7,25 +7,9 @@ import { LoadBalancerTarget } from "aws-cdk-lib/aws-route53-targets";
 import { HostedZone as FjallHostedZone } from "../networking/hostedZone.js";
 import { SecurityGroup } from "../networking/securityGroup.js";
 import { isServiceEc2 } from "./ecsTaskDefinition.js";
-/** Returns the next unused auto-incremented ALB priority, skipping any manually assigned values. */
-export function getNextPriority(state) {
-    while (state.usedPriorities.has(state.nextPriority)) {
-        state.nextPriority++;
-    }
-    const priority = state.nextPriority++;
-    state.usedPriorities.add(priority);
-    return priority;
-}
-export function buildRoutingConditions(rule) {
-    const conditions = [];
-    if (rule?.path) {
-        conditions.push(ListenerCondition.pathPatterns([rule.path]));
-    }
-    if (rule?.host) {
-        conditions.push(ListenerCondition.hostHeaders([rule.host]));
-    }
-    return conditions;
-}
+import { createApplicationLoadBalancer } from "./applicationLoadBalancer.js";
+import { addRoutingListener } from "./listenerRouting.js";
+import { buildRoutingConditions, getNextPriority } from "./hostHeaderListenerRule.js";
 export function addLoadBalancer(ctx, anyServiceUsesEc2, asgSecurityGroup) {
     const props = ctx.props;
     const defaultLoadBalancerName = `${props.clusterName}LoadBalancer`;
@@ -48,18 +32,13 @@ export function addLoadBalancer(ctx, anyServiceUsesEc2, asgSecurityGroup) {
             asgSecurityGroup.connections.allowFrom(loadBalancerSecurityGroup, Port.tcpRange(49152, 65535));
         }
     }
-    const loadBalancer = new ApplicationLoadBalancer(ctx.scope, `${props.clusterName}LoadBalancer`, {
+    const loadBalancer = createApplicationLoadBalancer(ctx.scope, `${props.clusterName}LoadBalancer`, {
         vpc: ctx.cluster.vpc,
         internetFacing: !isInternal,
+        loadBalancerName: truncatedLoadBalancerName,
         ...(loadBalancerSecurityGroup && {
             securityGroup: loadBalancerSecurityGroup
-        }),
-        loadBalancerName: truncatedLoadBalancerName,
-        vpcSubnets: {
-            subnetType: isInternal
-                ? SubnetType.PRIVATE_WITH_EGRESS
-                : SubnetType.PUBLIC
-        }
+        })
     });
     new CfnOutput(ctx.scope, `${ctx.outputName}LoadBalancerDnsName`, {
         key: `${ctx.outputName}LoadBalancerDnsName`,
@@ -112,25 +91,11 @@ export function addLoadBalancerListener(ctx, loadBalancer, certificate) {
         });
     // CDK rejects listeners with neither a default action nor target groups.
     const noServicePorts = servicesWithPorts.length === 0;
-    const defaultAction = willHaveMultipleRoutes || noServicePorts
-        ? ListenerAction.fixedResponse(404, {
-            contentType: "text/plain",
-            messageBody: "Not Found"
-        })
-        : undefined;
-    if (certificate) {
-        return loadBalancer.addListener(`${ctx.props.clusterName}Listener`, {
-            port,
-            certificates: [certificate],
-            ...(defaultAction !== undefined && { defaultAction })
-        });
-    }
-    else {
-        return loadBalancer.addListener(`${ctx.props.clusterName}Listener`, {
-            port,
-            ...(defaultAction !== undefined && { defaultAction })
-        });
-    }
+    return addRoutingListener(loadBalancer, `${ctx.props.clusterName}Listener`, {
+        port,
+        ...(certificate && { certificate }),
+        default404: willHaveMultipleRoutes || noServicePorts
+    });
 }
 export function addHostedZone(ctx, loadBalancer) {
     const props = ctx.props;

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

@@ -1,10 +1,35 @@
 import { Role } from "aws-cdk-lib/aws-iam";
+import type { Construct } from "constructs";
 import type { EcsConstructContext } from "./ecsContext.js";
 import type { EcsServiceProps } from "./ecsTypes.js";
+/**
+ * Builds the base ECS task-execution role shared by every task the platform
+ * runs: the ECR-pull quartet (account-level, so `resources: ["*"]`) and a
+ * ViaService-conditioned `kms:Decrypt` for SSM SecureString / Secrets-Manager
+ * CMK env injection. Pass `ssmSecretsPath` (already derived — no partition/
+ * region/account prefix) to add the path-scoped `ssm:GetParameters` grant.
+ * Trust principal is `ecs-tasks.amazonaws.com`.
+ *
+ * Deliberately omits `logs:*` and `secretsmanager:GetSecretValue`: on the
+ * ECS-pattern path `AwsLogDriver.bind()` and `addContainer({ secrets })`
+ * auto-grant those on the exact LogGroup / secret ARNs. A caller that builds a
+ * 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.
+ */
+export declare function createBaseExecutionRole(scope: Construct, id: string, opts?: {
+    ssmSecretsPath?: string;
+}): Role;
 /**
  * Creates the execution role for ECS infrastructure operations.
  * Used by the ECS agent to pull images, write logs, and inject secrets.
  * NOT used by application code — that's the task role.
+ *
+ * Delegates the ECR/kms/ssm shape to `createBaseExecutionRole`. Logs +
+ * secretsmanager are auto-granted downstream on this path (AwsLogDriver.bind()
+ * on the real LogGroup, addContainer({ secrets }) on the exact secret ARN), so a
+ * hand-rolled `/ecs/{cluster}*` logs or bare `-*` secrets statement here would be
+ * dead (the 2026-06-04 outage shape).
  */
 export declare function createExecutionRole(ctx: EcsConstructContext, serviceName: string): Role;
 /**