@fjall/components-infrastructure 33.1.0 → 35.0.0

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

@@ -1,8 +1,11 @@
 import { InstanceType, LaunchTemplate, SubnetType, MachineImage, LaunchTemplateHttpTokens, KeyPair, SecurityGroup, Peer, Port, Connections } from "aws-cdk-lib/aws-ec2";
 import { Construct } from "constructs";
+import { WORLD_OPEN_IPV4_CIDR } from "@fjall/generator";
+import { mintedEc2KeyPairName } from "@fjall/util";
+import { EC2_WORLD_OPEN_SSH_WARNING_ID, checkRetiredSshProp, sshFacesInternet, validateSshAccess, worldOpenSshWarning } from "./ec2SshAccess.js";
 import { resolvePrivateSubnetType } from "../../../utils/vpcUtils.js";
 import { safeEbs } from "./blockDeviceVolume.js";
-import { Duration, Stack, Tags } from "aws-cdk-lib";
+import { Annotations, Duration, Stack, Tags } from "aws-cdk-lib";
 import { AutoScalingGroup, GroupMetrics, InstanceRefreshStrategy, Monitoring, TerminationPolicy, UpdatePolicy, OnDemandAllocationStrategy, SpotAllocationStrategy } from "aws-cdk-lib/aws-autoscaling";
 import { DEFAULT_ROLLING_UPDATE_PAUSE_SECONDS, INSTANCE_REFRESH_DEFAULT_MAX_HEALTHY, INSTANCE_REFRESH_DEFAULT_MIN_HEALTHY, INSTANCE_REFRESH_PDV_MAX_HEALTHY, INSTANCE_REFRESH_PDV_MIN_HEALTHY } from "./ecsConstants.js";
 import { AwsCustomResource } from "../utilities/awsCustomResource.js";
@@ -72,11 +75,19 @@ export class Ec2Instance extends Construct {
     autoScalingGroup;
     keyPair;
     persistentDataVolume;
+    vpcSubnets;
+    associatePublicIpAddress;
     connections;
     constructor(scope, id, props) {
         super(scope, id);
         validateEc2InstanceProps(props);
+        checkRetiredSshProp(this, "Ec2Instance", props);
+        // `sshAccess.public` assigns a public IP unless the caller's own prop
+        // decides; validateEc2InstanceProps has already rejected a contradiction.
+        this.associatePublicIpAddress =
+            props.associatePublicIpAddress ?? props.sshAccess?.public === true;
         this.addVpc(props);
+        this.vpcSubnets = this.resolveVpcSubnets(props);
         this.addKeyPair(props);
         this.addLaunchTemplate(props);
         this.addAutoScalingGroup(props);
@@ -101,13 +112,35 @@ export class Ec2Instance extends Construct {
         }
     }
     addKeyPair(props) {
-        if (!props.enableSSH) {
+        const access = props.sshAccess;
+        if (access === undefined) {
             this.keyPair = undefined;
+            return;
         }
-        else {
-            this.keyPair = new KeyPair(this, "KeyPair", {
-                keyPairName: `${props.serviceName}KeyPair`
-            });
+        this.keyPair =
+            access.keyName !== undefined
+                ? KeyPair.fromKeyPairName(this, "KeyPair", access.keyName)
+                : new KeyPair(this, "KeyPair", {
+                    keyPairName: mintedEc2KeyPairName(props.serviceName)
+                });
+    }
+    /**
+     * One ingress rule per source range. A world-open range still lands (the
+     * caller asked for it) but warns; the wording reads the placement the group
+     * actually resolved to, not `sshAccess.public` alone, because a caller who
+     * owns the placement through public `vpcSubnets` and
+     * `associatePublicIpAddress` exposes it just the same.
+     */
+    addSshIngress(props, access) {
+        const facesInternet = sshFacesInternet({
+            associatePublicIpAddress: this.associatePublicIpAddress,
+            hasPublicSubnets: this.vpc.selectSubnets(this.vpcSubnets).hasPublic
+        });
+        for (const cidr of access.allowedIpCidrs) {
+            if (cidr === WORLD_OPEN_IPV4_CIDR) {
+                Annotations.of(this).addWarningV2(EC2_WORLD_OPEN_SSH_WARNING_ID, worldOpenSshWarning(props.serviceName, facesInternet));
+            }
+            this.asgSecurityGroup.addIngressRule(Peer.ipv4(cidr), Port.tcp(22), `SSH from ${cidr}`);
         }
     }
     addLaunchTemplate(props) {
@@ -120,8 +153,8 @@ export class Ec2Instance extends Construct {
                 description: `Security group for the ${props.serviceName} auto scaling group`
             });
         }
-        if (props.enableSSH) {
-            this.asgSecurityGroup.addIngressRule(Peer.anyIpv4(), Port.tcp(22), "Allow SSH");
+        if (props.sshAccess !== undefined) {
+            this.addSshIngress(props, props.sshAccess);
         }
         this.launchTemplate = new LaunchTemplate(this, "LaunchTemplate", {
             launchTemplateName: `${props.serviceName}LaunchTemplate`,
@@ -144,15 +177,30 @@ export class Ec2Instance extends Construct {
             httpTokens: LaunchTemplateHttpTokens.REQUIRED,
             instanceMetadataTags: true,
             keyPair: this.keyPair,
-            associatePublicIpAddress: props.associatePublicIpAddress ?? !!this.keyPair
+            associatePublicIpAddress: this.associatePublicIpAddress
         });
     }
+    /**
+     * `sshAccess.public` decides the subnet type; an explicit `vpcSubnets` keeps
+     * its other selectors (AZ pinning) — `validateEc2InstanceProps` has already
+     * rejected a selection that contradicts `public: true`, so filling in
+     * `PUBLIC` here only completes an AZ-only pin.
+     */
+    resolveVpcSubnets(props) {
+        const isPublic = props.sshAccess?.public === true;
+        if (props.vpcSubnets === undefined) {
+            return {
+                subnetType: isPublic
+                    ? SubnetType.PUBLIC
+                    : resolvePrivateSubnetType(this.vpc)
+            };
+        }
+        return isPublic
+            ? { ...props.vpcSubnets, subnetType: SubnetType.PUBLIC }
+            : props.vpcSubnets;
+    }
     addAutoScalingGroup(props) {
-        const vpcSubnets = props.vpcSubnets ?? {
-            subnetType: props.enableSSH
-                ? SubnetType.PUBLIC
-                : resolvePrivateSubnetType(this.vpc)
-        };
+        const vpcSubnets = this.vpcSubnets;
         const resolvedUpdatePolicy = resolveUpdatePolicy(props.updatePolicy, props.persistentDataVolume !== undefined);
         const baseAsgProps = {
             vpc: this.vpc,
@@ -282,6 +330,7 @@ export class Ec2Instance extends Construct {
     }
 }
 function validateEc2InstanceProps(props) {
+    validateSshAccess(props);
     if (props.spotCapacityPercentage !== undefined) {
         if (!Number.isInteger(props.spotCapacityPercentage) ||
             props.spotCapacityPercentage < 0 ||

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

@@ -0,0 +1,80 @@
+import { type ISecurityGroup, type SubnetSelection } from "aws-cdk-lib/aws-ec2";
+import { type IConstruct } from "constructs";
+/**
+ * SSH access to the instances. Each field is one decision the construct used
+ * to fold into a single `enableSSH` boolean. Absent → no key pair, no port-22
+ * ingress, private subnets and no public IP; Session Manager remains the
+ * access path.
+ */
+export interface Ec2SshAccessProps {
+    /**
+     * IPv4 source ranges allowed on TCP 22, one ingress rule each. At least one
+     * entry, no duplicates. A literal is validated as dotted-quad/prefix-length
+     * (octets 0–255, prefix 0–32); a CDK token per element such as
+     * `vpc.vpcCidrBlock` passes through to CloudFormation, but the list itself
+     * must be literal at synth (no `valueAsList` / `Fn.split` over a token),
+     * because each range becomes one rule. `"0.0.0.0/0"` synthesises with a
+     * warning that names the instance.
+     */
+    allowedIpCidrs: string[];
+    /**
+     * Existing EC2 key pair name, resolved with `KeyPair.fromKeyPairName`. Omit
+     * to mint one named `${serviceName}KeyPair`; naming that key pair here is
+     * rejected, because the switch to an imported reference would delete it.
+     */
+    keyName?: string;
+    /**
+     * Public subnets and a public IP. Default `false`: the instances stay in
+     * private subnets, so the ranges in `allowedIpCidrs` reach port 22 only from
+     * inside the VPC, a peered VPC or a VPN. `vpcSubnets` may still pin
+     * availability zones; a `vpcSubnets.subnetType` or an
+     * `associatePublicIpAddress` that contradicts `public: true` is rejected.
+     */
+    public?: boolean;
+}
+export declare const EC2_WORLD_OPEN_SSH_WARNING_ID = "@fjall/components-infrastructure:ec2WorldOpenSsh";
+export declare const EC2_RETIRED_SSH_PROP_WARNING_ID = "@fjall/components-infrastructure:ec2RetiredSshProp";
+type RetiredSshOwner = "Ec2Instance" | "Ec2Compute";
+/**
+ * The retired spelling is read at synth, not only at typecheck: a JavaScript
+ * caller, or a spread of an older props object, would otherwise deploy with
+ * no SSH and no signal. A value the pre-34 owner read as SSH on asked for an
+ * exposure the new shape must spell out, so it throws with the translation.
+ * A value it read as off asked for the default and gets it, with a warning
+ * to delete the prop: refusing a no-op would strand every file the pre-34
+ * wizard wrote.
+ */
+export declare function checkRetiredSshProp(scope: IConstruct, owner: RetiredSshOwner, props: object): void;
+/** The fields of `Ec2InstanceProps` the SSH contract reads. */
+export interface SshAccessValidationInput {
+    serviceName: string;
+    sshAccess?: Ec2SshAccessProps;
+    securityGroup?: ISecurityGroup;
+    associatePublicIpAddress?: boolean;
+    vpcSubnets?: SubnetSelection;
+}
+/** Synth-time contract for `sshAccess`; every refusal names the cure. */
+export declare function validateSshAccess(props: SshAccessValidationInput): void;
+/** The placement `Ec2Instance` resolved for the group, as the warning reads it. */
+export interface ResolvedSshPlacement {
+    /** The launch template's setting once `sshAccess.public` and the caller's own prop are reconciled. */
+    associatePublicIpAddress: boolean;
+    /** Whether the subnets the group lands in include public ones (`vpc.selectSubnets(...).hasPublic`). */
+    hasPublicSubnets: boolean;
+}
+/**
+ * Whether port 22 faces the internet. An instance is reachable from outside
+ * only with a public IP AND a subnet routed to an internet gateway, so both
+ * halves of the resolved placement must say public. `public: true` sets
+ * both; a caller who owns the placement through `vpcSubnets` and
+ * `associatePublicIpAddress` reaches the same exposure without the flag,
+ * which is why the warning reads the placement rather than `sshAccess.public`.
+ */
+export declare function sshFacesInternet(placement: ResolvedSshPlacement): boolean;
+/**
+ * The world-open warning: a `0.0.0.0/0` range still lands (the caller asked
+ * for it) but synthesises with an acknowledgeable warning, as
+ * `rdsWorldOpenIngress` does for a database.
+ */
+export declare function worldOpenSshWarning(serviceName: string, facesInternet: boolean): string;
+export {};

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

@@ -0,0 +1,166 @@
+import { Annotations, Token } from "aws-cdk-lib";
+import { SubnetType } from "aws-cdk-lib/aws-ec2";
+import { CIDR_REGEX, WORLD_OPEN_IPV4_CIDR } from "@fjall/generator";
+import { mintedEc2KeyPairName } from "@fjall/util";
+/**
+ * The construct prop and the generator's `Ec2SshAccessSchema` are one contract
+ * spelled twice: the plan's `sshAccess` projects literally into this prop.
+ * This map fails typecheck until both sides agree: a key missing from or
+ * added to either side, or a field whose type drifts between them (`true` is
+ * not assignable to the `never` a drifted field resolves to). Its keys are
+ * also the runtime accept-set for a caller-supplied object.
+ */
+const SSH_ACCESS_FIELD_PARITY = {
+    allowedIpCidrs: true,
+    keyName: true,
+    public: true
+};
+const SSH_ACCESS_KEYS = Object.keys(SSH_ACCESS_FIELD_PARITY);
+export const EC2_WORLD_OPEN_SSH_WARNING_ID = "@fjall/components-infrastructure:ec2WorldOpenSsh";
+export const EC2_RETIRED_SSH_PROP_WARNING_ID = "@fjall/components-infrastructure:ec2RetiredSshProp";
+/**
+ * One retired spelling per owner, read the way its pre-34 owner read it:
+ * `Ec2Instance` tested `enableSSH` for truthiness; `Ec2Compute` treated any
+ * `ssh` other than `undefined` or `false` as SSH on, and forwarded neither
+ * its `keyName` nor its `allowedCidrs`.
+ */
+const RETIRED_SSH_PROPS = {
+    Ec2Instance: {
+        prop: "enableSSH",
+        askedForDefault: (value) => !value,
+        translation: `enableSSH: true meant sshAccess: { allowedIpCidrs: ["${WORLD_OPEN_IPV4_CIDR}"], public: true }.`
+    },
+    Ec2Compute: {
+        prop: "ssh",
+        askedForDefault: (value) => value === undefined || value === false,
+        translation: `ssh: {} meant sshAccess: { allowedIpCidrs: ["${WORLD_OPEN_IPV4_CIDR}"], public: true }; its keyName and allowedCidrs were never forwarded. ` +
+            "Carry them into sshAccess only to have them honoured now: allowedIpCidrs narrows the rule, and naming a key pair switches the group " +
+            "from the key pair this construct mints to the named one, so CloudFormation deletes the minted key pair and its stored private key."
+    }
+};
+/**
+ * The retired spelling is read at synth, not only at typecheck: a JavaScript
+ * caller, or a spread of an older props object, would otherwise deploy with
+ * no SSH and no signal. A value the pre-34 owner read as SSH on asked for an
+ * exposure the new shape must spell out, so it throws with the translation.
+ * A value it read as off asked for the default and gets it, with a warning
+ * to delete the prop: refusing a no-op would strand every file the pre-34
+ * wizard wrote.
+ */
+export function checkRetiredSshProp(scope, owner, props) {
+    const retired = RETIRED_SSH_PROPS[owner];
+    if (!(retired.prop in props))
+        return;
+    const value = props[retired.prop];
+    if (retired.askedForDefault(value)) {
+        Annotations.of(scope).addWarningV2(EC2_RETIRED_SSH_PROP_WARNING_ID, `${owner}.${retired.prop} was removed in @fjall/components-infrastructure 34; ${retired.prop}: ${String(value)} asked for the default (no SSH), which still applies. Delete the prop.`);
+        return;
+    }
+    throw new Error(`${owner}.${retired.prop} was removed in @fjall/components-infrastructure 34. ` +
+        "Declare sshAccess: { allowedIpCidrs: [...], keyName?, public? }, or omit it for Session Manager-only access. " +
+        retired.translation);
+}
+function listTokenError(where) {
+    return new Error(`Ec2Instance.sshAccess.${where} cannot be a list token (CfnParameter.valueAsList, Fn.split over a parameter): ` +
+        "each range becomes one ingress rule, so the list itself must be literal at synth. " +
+        "A token per element, such as vpc.vpcCidrBlock, is fine.");
+}
+/** Synth-time contract for `sshAccess`; every refusal names the cure. */
+export function validateSshAccess(props) {
+    const access = props.sshAccess;
+    if (access === undefined)
+        return;
+    const raw = access;
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        const got = raw === null
+            ? "null"
+            : Array.isArray(raw)
+                ? "an array"
+                : `a ${typeof raw}`;
+        throw new Error(`Ec2Instance.sshAccess must be an object { allowedIpCidrs, keyName?, public? }; got ${got}. Omit it for Session Manager-only access.`);
+    }
+    if (props.securityGroup !== undefined) {
+        throw new Error("Ec2Instance.sshAccess cannot be combined with a caller-supplied securityGroup. " +
+            "sshAccess adds port-22 ingress rules to the ASG security group; routing them onto an " +
+            "externally-owned security group couples this construct's permissions onto a SG whose lifecycle it " +
+            "does not own. Either omit securityGroup (a Fjall-owned SG will be created) or omit sshAccess and " +
+            "add the port-22 rule to your own security group.");
+    }
+    const unknownKey = Object.keys(access).find((key) => !SSH_ACCESS_KEYS.includes(key));
+    if (unknownKey !== undefined) {
+        throw new Error(`Ec2Instance.sshAccess has no field '${unknownKey}'; its fields are ${SSH_ACCESS_KEYS.join(", ")}. ` +
+            "The pre-34 ssh prop's allowedCidrs is allowedIpCidrs here.");
+    }
+    if (Token.isUnresolved(access.allowedIpCidrs)) {
+        throw listTokenError("allowedIpCidrs");
+    }
+    if (!Array.isArray(access.allowedIpCidrs) ||
+        access.allowedIpCidrs.length === 0) {
+        throw new Error("Ec2Instance.sshAccess.allowedIpCidrs must list at least one IPv4 CIDR. " +
+            "SSH that no address can reach is not a configuration — omit sshAccess for no SSH.");
+    }
+    const seen = new Map();
+    access.allowedIpCidrs.forEach((cidr, index) => {
+        if (typeof cidr !== "string" || cidr === "") {
+            throw new Error(`Ec2Instance.sshAccess.allowedIpCidrs[${index}] must be a non-empty IPv4 CIDR string`);
+        }
+        // A list token spread into a literal list ([...ranges.valueAsList, "10.0.0.0/8"])
+        // carries the list marker in one element; the whole-list check above cannot see it.
+        if (Token.isUnresolved([cidr])) {
+            throw listTokenError(`allowedIpCidrs[${index}]`);
+        }
+        if (!Token.isUnresolved(cidr) && !CIDR_REGEX.test(cidr)) {
+            throw new Error(`Ec2Instance.sshAccess.allowedIpCidrs[${index}] '${cidr}' is not an IPv4 CIDR (dotted-quad/prefix-length, e.g. 203.0.113.4/32)`);
+        }
+        const first = seen.get(cidr);
+        if (first !== undefined) {
+            throw new Error(`Ec2Instance.sshAccess.allowedIpCidrs[${index}] duplicates allowedIpCidrs[${first}] ('${cidr}'); each range is one ingress rule and AWS rejects a duplicate rule`);
+        }
+        seen.set(cidr, index);
+    });
+    const minted = mintedEc2KeyPairName(props.serviceName);
+    if (access.keyName === "") {
+        throw new Error(`Ec2Instance.sshAccess.keyName must not be empty; omit it to mint a key pair named ${minted}`);
+    }
+    if (access.keyName === minted) {
+        throw new Error(`Ec2Instance.sshAccess.keyName '${minted}' is the name of the key pair this construct mints for serviceName '${props.serviceName}'. ` +
+            "Omit keyName to keep the managed key pair: naming it switches the construct to an imported reference, and CloudFormation then deletes the managed key pair and its stored private key.");
+    }
+    if (access.public === true) {
+        if (props.associatePublicIpAddress === false) {
+            throw new Error("Ec2Instance.sshAccess.public: true assigns a public IP, but associatePublicIpAddress is false. Drop one of them.");
+        }
+        const selection = props.vpcSubnets;
+        if (selection !== undefined) {
+            if (selection.subnetType !== undefined &&
+                selection.subnetType !== SubnetType.PUBLIC) {
+                throw new Error(`Ec2Instance.sshAccess.public: true places the instances in public subnets, but vpcSubnets.subnetType is ${selection.subnetType}. Drop one of them.`);
+            }
+            if (selection.subnetGroupName !== undefined ||
+                selection.subnets !== undefined) {
+                throw new Error("Ec2Instance.sshAccess.public: true places the instances in the VPC's public subnets; vpcSubnets may pin availabilityZones but cannot select subnets by group name or instance. Set public: false and own the placement, or drop the selector.");
+            }
+        }
+    }
+}
+/**
+ * Whether port 22 faces the internet. An instance is reachable from outside
+ * only with a public IP AND a subnet routed to an internet gateway, so both
+ * halves of the resolved placement must say public. `public: true` sets
+ * both; a caller who owns the placement through `vpcSubnets` and
+ * `associatePublicIpAddress` reaches the same exposure without the flag,
+ * which is why the warning reads the placement rather than `sshAccess.public`.
+ */
+export function sshFacesInternet(placement) {
+    return placement.associatePublicIpAddress && placement.hasPublicSubnets;
+}
+/**
+ * The world-open warning: a `0.0.0.0/0` range still lands (the caller asked
+ * for it) but synthesises with an acknowledgeable warning, as
+ * `rdsWorldOpenIngress` does for a database.
+ */
+export function worldOpenSshWarning(serviceName, facesInternet) {
+    return facesInternet
+        ? `Ec2Instance '${serviceName}': sshAccess.allowedIpCidrs contains '${WORLD_OPEN_IPV4_CIDR}' and the instances are publicly reachable, so port 22 is open to the entire internet. Scope allowedIpCidrs to the addresses that need access (e.g. "203.0.113.4/32").`
+        : `Ec2Instance '${serviceName}': sshAccess.allowedIpCidrs contains '${WORLD_OPEN_IPV4_CIDR}'. The instances are not reachable from the internet as placed, so the rule admits every address that can route to them (the VPC, peered networks, VPNs); scope allowedIpCidrs to the ranges that need access (e.g. "10.0.0.0/8").`;
+}

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

@@ -2,6 +2,7 @@ import { Cluster as CdkCluster, type FargateService, type Ec2Service, type TaskD
 import { Connections, type IConnectable } from "aws-cdk-lib/aws-ec2";
 import { Construct } from "constructs";
 import type { StackBuilder } from "../base/awsStack.js";
+import { Grant, type IGrantable } from "aws-cdk-lib/aws-iam";
 import type { ApplicationListener, ApplicationLoadBalancer } from "aws-cdk-lib/aws-elasticloadbalancingv2";
 import { StackEncryptionKey } from "../secrets/stackEncryptionKey.js";
 import { type EcsClusterProps } from "./ecsTypes.js";
@@ -70,8 +71,8 @@ export default class EcsCluster extends Construct implements IConnectable {
     /**
      * The stack's shared key when the app backup tier encrypts (resolved once,
      * here); undefined otherwise. Read by the patterns layer for the log
-     * groups it creates beside the cluster's own, so the tier is consulted in
-     * one place.
+     * groups it creates beside the cluster's own and by `grantExecuteCommand`,
+     * so the tier is consulted in one place.
      */
     readonly encryptionKey: StackEncryptionKey | undefined;
     private readonly loadBalancerDeletionProtection;
@@ -111,6 +112,14 @@ export default class EcsCluster extends Construct implements IConnectable {
     registerScheduledTaskDefinition(name: string, taskDefinition: TaskDefinition): void;
     /** Get the ECS cluster construct. */
     getCluster(): CdkCluster;
+    /**
+     * Grant what an ECS Exec caller needs on this cluster: `ecs:ExecuteCommand`
+     * on the cluster and its tasks and, when the tier encrypts the session,
+     * `kms:GenerateDataKey` on the stack key — the caller-side half of ECS Exec
+     * encryption (the task role's Decrypt rides CDK's BaseService wiring).
+     * https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-exec.html
+     */
+    grantExecuteCommand(grantee: IGrantable): Grant;
     /**
      * Connectable scoped to the cluster's EC2 capacity security groups alone.
      * Scheduled tasks run on the cluster's instances (bridge/host networking),

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

@@ -1,7 +1,8 @@
 import { Cluster as CdkCluster, ContainerInsights, ExecuteCommandLogging } from "aws-cdk-lib/aws-ecs";
 import { Connections, Port } from "aws-cdk-lib/aws-ec2";
 import { Construct } from "constructs";
-import { CfnOutput, Aspects } from "aws-cdk-lib";
+import { CfnOutput, Aspects, Stack } from "aws-cdk-lib";
+import { Grant } from "aws-cdk-lib/aws-iam";
 import { processConnections } from "../../../utils/connections.js";
 import { tierDefault } from "../../../utils/backupTierMapping.js";
 import { envAwareRemovalPolicyDefault } from "../../../utils/removalPolicy.js";
@@ -91,8 +92,8 @@ export default class EcsCluster extends Construct {
     /**
      * The stack's shared key when the app backup tier encrypts (resolved once,
      * here); undefined otherwise. Read by the patterns layer for the log
-     * groups it creates beside the cluster's own, so the tier is consulted in
-     * one place.
+     * groups it creates beside the cluster's own and by `grantExecuteCommand`,
+     * so the tier is consulted in one place.
      */
     encryptionKey;
     loadBalancerDeletionProtection;
@@ -116,9 +117,7 @@ export default class EcsCluster extends Construct {
         const tier = props.appBackupTier;
         this.containerInsightsEnabled =
             props.containerInsights ?? tierDefault(tier, "containerInsights");
-        this.encryptionKey = tierDefault(tier, "customerManagedKeys")
-            ? StackEncryptionKey.of(this)
-            : undefined;
+        this.encryptionKey = StackEncryptionKey.forTier(this, tier);
         this.loadBalancerDeletionProtection =
             props.cluster?.loadBalancerDeletionProtection ??
                 (tierDefault(tier, "deletionProtection") &&
@@ -254,6 +253,30 @@ export default class EcsCluster extends Construct {
     getCluster() {
         return this.cluster;
     }
+    /**
+     * Grant what an ECS Exec caller needs on this cluster: `ecs:ExecuteCommand`
+     * on the cluster and its tasks and, when the tier encrypts the session,
+     * `kms:GenerateDataKey` on the stack key — the caller-side half of ECS Exec
+     * encryption (the task role's Decrypt rides CDK's BaseService wiring).
+     * https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-exec.html
+     */
+    grantExecuteCommand(grantee) {
+        const exec = Grant.addToPrincipal({
+            grantee,
+            actions: ["ecs:ExecuteCommand"],
+            resourceArns: [
+                this.cluster.clusterArn,
+                Stack.of(this).formatArn({
+                    service: "ecs",
+                    resource: "task",
+                    resourceName: `${this.props.clusterName}/*`
+                })
+            ]
+        });
+        return this.encryptionKey === undefined
+            ? exec
+            : exec.combine(this.encryptionKey.key.grant(grantee, "kms:GenerateDataKey"));
+    }
     /**
      * Connectable scoped to the cluster's EC2 capacity security groups alone.
      * Scheduled tasks run on the cluster's instances (bridge/host networking),

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

@@ -109,6 +109,11 @@ export interface LambdaFunctionProps {
 /**
  * Framework custom-resource handlers are tier-agnostic: the tier-owned
  * knobs are excluded at the type rather than silently ignored.
+ *
+ * Every singleton in this library backs a custom-resource provider, which is
+ * why the constructor marks the hoisted subtree as a deploy-time writer. A
+ * singleton fronting a runtime lambda would need that call moved to the two
+ * writer call sites (`utilities/customResource.ts`, `iam/identityCenter/user.ts`).
  */
 export interface SingletonFunctionProps extends Omit<LambdaFunctionProps, "tracing" | "appBackupTier"> {
     uuid?: string;

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

@@ -18,6 +18,7 @@ import { resolveImportedSecret } from "../secrets/index.js";
 import { validateSsmPathComponent } from "./ecsValidation.js";
 import { toPascalCase } from "../../../utils/capitaliseString.js";
 import { resolvePrivateSubnetType } from "../../../utils/vpcUtils.js";
+import { markDeployTimeWriter } from "../../../utils/resourceTypeTags.js";
 import { createLambdaAlarms } from "../monitoring/index.js";
 function addPoliciesToRole(target, statements) {
     for (const statement of statements) {
@@ -155,6 +156,13 @@ export class SingletonFunction extends singletonFunction {
         addPoliciesToRole(this, props.inlinePolicy);
         applyRoleDescription(this, props.roleDescription);
         applyRolePathAndName(this, props.rolePath, props.roleName);
+        // aws-cdk-lib hoists the singleton's Function — and with it the execution
+        // role — to the stack scope, so a tag applied to this construct or to the
+        // enclosing writer never reaches either. Found the way CDK's own
+        // `ensureLambda` finds it, by the public `constructName`; `findChild`
+        // throws if the hoist ever moves, so a CDK upgrade fails at synth rather
+        // than shipping an unmarked role.
+        markDeployTimeWriter(Stack.of(this).node.findChild(this.constructName));
     }
     /**
      * The Lambda's execution role (auto-generated by CDK)
@@ -178,9 +186,7 @@ export class LambdaFunction extends Function {
         const tracingEnabled = tracing ?? tierDefault(appBackupTier, "lambdaTracing");
         // Grant-based: Lambda encrypts the environment through a KMS grant the
         // deploying role creates, so the execution role needs no key policy.
-        const encryptionKey = tierDefault(appBackupTier, "customerManagedKeys")
-            ? StackEncryptionKey.of(scope)
-            : undefined;
+        const encryptionKey = StackEncryptionKey.forTier(scope, appBackupTier);
         super(scope, id, {
             ...cdkProps,
             vpcSubnets,

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

@@ -66,10 +66,11 @@ export class DynamoDBTable extends Construct {
     constructor(scope, id, props) {
         super(scope, id);
         this.id = id;
+        const stackKey = StackEncryptionKey.forTier(this, props.appBackupTier, props.encryption === undefined
+            ? undefined
+            : props.encryption === "CUSTOMER_MANAGED");
         const encryption = props.encryption ??
-            (tierDefault(props.appBackupTier, "customerManagedKeys")
-                ? "CUSTOMER_MANAGED"
-                : "AWS_MANAGED");
+            (stackKey === undefined ? "AWS_MANAGED" : "CUSTOMER_MANAGED");
         const deletionProtection = props.deletionProtection ??
             tierDefault(props.appBackupTier, "deletionProtection");
         this.table = new Table(this, `${id}Table`, {
@@ -92,9 +93,7 @@ export class DynamoDBTable extends Construct {
                 pointInTimeRecoveryEnabled: props.pointInTimeRecovery ?? true
             },
             encryption: toTableEncryption(encryption),
-            ...(encryption === "CUSTOMER_MANAGED" && {
-                encryptionKey: StackEncryptionKey.of(this).key
-            }),
+            ...(stackKey !== undefined && { encryptionKey: stackKey.key }),
             deletionProtection,
             removalPolicy: toRemovalPolicy(props.removalPolicy),
             timeToLiveAttribute: props.timeToLiveAttribute

package/dist/lib/resources/aws/iam/identityCenter/user.js

@@ -7,6 +7,7 @@ import { Provider } from "aws-cdk-lib/custom-resources";
 import { Construct } from "constructs";
 import { SingletonFunction } from "../../compute/lambda.js";
 import { DEFAULT_FRAMEWORK_LOG_RETENTION, LogGroup } from "../../logging/logGroup.js";
+import { markDeployTimeWriter } from "../../../../utils/resourceTypeTags.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 /**
  * Resolves relative to the compiled location too — the build step copies the
@@ -58,6 +59,7 @@ export class IdentityStoreUserProvider extends Construct {
             })
         });
         this.serviceToken = provider.serviceToken;
+        markDeployTimeWriter(this);
     }
 }
 /**

package/dist/lib/resources/aws/logging/accessLogBucket.d.ts

@@ -15,8 +15,10 @@ export declare const ACCESS_LOG_RETENTION_DAYS = 90;
  * tier-aware: ELB log delivery requires SSE-S3 (it cannot write to a
  * KMS-encrypted bucket), CloudFront standard logging requires ACLs enabled
  * (`OBJECT_WRITER` ownership, the CDK's own logging-bucket shape), and
- * versioning would only multiply expired log objects. The bucket takes the
- * env-aware removal policy like every other bucket: production RETAINs its
- * audit evidence, non-production DESTROYs.
+ * versioning would only multiply expired log objects — the `access-logs`
+ * exemption marker tells posture so, landing `S3_VERSIONING_DISABLED`
+ * `mitigated` rather than `open`. The bucket takes the env-aware removal
+ * policy like every other bucket: production RETAINs its audit evidence,
+ * non-production DESTROYs.
  */
 export declare function stackAccessLogBucket(scope: Construct): S3Bucket;

package/dist/lib/resources/aws/logging/accessLogBucket.js

@@ -17,9 +17,11 @@ export const ACCESS_LOG_RETENTION_DAYS = 90;
  * tier-aware: ELB log delivery requires SSE-S3 (it cannot write to a
  * KMS-encrypted bucket), CloudFront standard logging requires ACLs enabled
  * (`OBJECT_WRITER` ownership, the CDK's own logging-bucket shape), and
- * versioning would only multiply expired log objects. The bucket takes the
- * env-aware removal policy like every other bucket: production RETAINs its
- * audit evidence, non-production DESTROYs.
+ * versioning would only multiply expired log objects — the `access-logs`
+ * exemption marker tells posture so, landing `S3_VERSIONING_DISABLED`
+ * `mitigated` rather than `open`. The bucket takes the env-aware removal
+ * policy like every other bucket: production RETAINs its audit evidence,
+ * non-production DESTROYs.
  */
 export function stackAccessLogBucket(scope) {
     const stack = Stack.of(scope);
@@ -30,6 +32,7 @@ export function stackAccessLogBucket(scope) {
         encryption: BucketEncryption.S3_MANAGED,
         objectOwnership: ObjectOwnership.OBJECT_WRITER,
         versioned: false,
+        versioningExemption: "access-logs",
         lifecycleRules: [
             {
                 id: "ExpireAccessLogs",

package/dist/lib/resources/aws/messaging/sns.d.ts

@@ -24,13 +24,23 @@ export interface SNSTopicProps {
      */
     signatureVersion?: "1" | "2";
     /**
-     * KMS key for server-side encryption at rest. Absent ⇒ the app backup
-     * tier decides: enterprise encrypts with the stack's shared
-     * [[StackEncryptionKey]] (its SNS service publishers admitted); every other
-     * tier stays unencrypted — the accessible default (a customer-managed key
-     * costs $1–3/month per account-region once annual rotation accrues), so
-     * the SNS_TOPIC_NOT_ENCRYPTED posture finding stands as the signpost to
-     * the tier rather than being silently pre-paid.
+     * Server-side encryption at rest. Absent ⇒ the app backup tier decides
+     * through its `customerManagedKeys` column: `"SSE_KMS"` at enterprise,
+     * `"NONE"` at every other tier. `"SSE_KMS"` encrypts with the stack's
+     * shared [[StackEncryptionKey]] (its SNS service publishers admitted)
+     * unless `masterKey` brings a key of your own; `"NONE"` at enterprise is
+     * the auditable opt-out — it sits in the declaration, so the
+     * SNS_TOPIC_NOT_ENCRYPTED finding it leaves is a choice, not an omission.
+     * Below enterprise the topic stays unencrypted by default — the accessible
+     * default (a customer-managed key costs $1–3/month per account-region once
+     * annual rotation accrues), so the finding stands as the signpost to the
+     * tier rather than being silently pre-paid.
+     */
+    encryption?: "SSE_KMS" | "NONE";
+    /**
+     * Bring your own KMS key for encryption at rest. Beats `encryption` and
+     * the tier: the topic encrypts with this key and the stack's shared key is
+     * not minted for it.
      *
      * Every AWS service principal that publishes to the topic needs
      * `kms:Decrypt` + `kms:GenerateDataKey*` on this key's RESOURCE policy or