@fjall/components-infrastructure 33.1.0 → 34.0.0

package/dist/lib/config/aws/scpPreset.js

@@ -346,9 +346,19 @@ function buildCostControls() {
                     "rds:ModifyDBCluster"
                 ],
                 Resource: "*",
+                // A negated operator over an ABSENT key evaluates true, so without
+                // the Null guard this statement denies every RDS request that names
+                // no instance class: a class-less ModifyDBInstance (the destroy
+                // pre-flight's DeletionProtection flip, a retention or parameter-group
+                // change), and Aurora's CreateDBCluster/ModifyDBCluster, where the
+                // class lives on the instances. The guard limits the deny to requests
+                // that carry a class; the instances still gate Aurora, whose Fjall
+                // construct is Serverless v2 only (`db.serverless`).
+                // https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html
                 Condition: {
+                    Null: { "rds:DatabaseClass": "false" },
                     StringNotLike: {
-                        "rds:DatabaseClass": ["db.t3.*", "db.t4g.*"]
+                        "rds:DatabaseClass": ["db.t3.*", "db.t4g.*", "db.serverless"]
                     }
                 }
             }

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

@@ -11,7 +11,8 @@ export function createBastion(networkStack, appName, stackPrefix, vpc, config) {
         serviceName: `${stackPrefix}Bastion`,
         instanceType,
         vpc,
-        enableSSH: false,
+        // Session Manager only: no sshAccess, so no key pair, no port-22 ingress
+        // and private subnets.
         minCapacity: 1,
         maxCapacity: 1
     });

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

@@ -87,7 +87,10 @@ interface BaseCdnProps {
      * `cloudFrontLogging` column — enterprise logs to the stack's shared,
      * lifecycle-expired access-log bucket under `cloudfront/<id>/`. Set either
      * knob to take over: `enableLogging: false` opts out at any tier,
-     * `logBucket` delivers to a bucket of your own.
+     * `logBucket` delivers to a bucket of your own. Standard logging cannot
+     * deliver into an opt-in region, so a tier- or explicitly-enabled CDN whose
+     * delivery region is opt-in is refused at synth with those two cures — see
+     * {@link CloudFrontDistributionProps.enableLogging}.
      */
     enableLogging?: boolean;
     logBucket?: IBucket;

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

@@ -16,7 +16,6 @@ import { S3Bucket } from "../../resources/aws/storage/s3.js";
 import { Secret } from "../../resources/aws/secrets/secret.js";
 import { LogGroup } from "../../resources/aws/logging/logGroup.js";
 import { StackEncryptionKey } from "../../resources/aws/secrets/stackEncryptionKey.js";
-import { tierDefault } from "../../utils/backupTierMapping.js";
 import { createClickHouseSecurityGroup } from "../../resources/aws/database/clickhouseSecurityGroup.js";
 import { buildMaintenancePreamble, maintenanceOkMarker, maintenanceRun } from "../../resources/aws/database/clickhouseMaintenanceScript.js";
 import { buildClickHouseEntrypointWrapper, buildClickHouseUserData, generateUsersConfigXml } from "../../resources/aws/database/clickhouseUserData.js";
@@ -393,9 +392,8 @@ export class ClickHouseDatabase extends Construct {
         // The maintenance-task log groups sit beside the compute's own container
         // and exec-audit groups and follow the same tier: the stack's shared key
         // at enterprise, nothing otherwise.
-        const taskLogGroupEncryption = tierDefault(props.appBackupTier, "customerManagedKeys")
-            ? { encryptionKey: StackEncryptionKey.of(this).forLogGroups() }
-            : {};
+        const stackKey = StackEncryptionKey.forTier(this, props.appBackupTier);
+        const taskLogGroupEncryption = stackKey === undefined ? {} : { encryptionKey: stackKey.forLogGroups() };
         const backupTaskLogGroup = backupEnabled
             ? new LogGroup(this, "ClickHouseBackupTaskLogGroup", {
                 retention: RetentionDays.TWO_WEEKS,

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

@@ -5,8 +5,8 @@ import { type ComputeType, type IEcsCompute, type ILambdaCompute, type IEc2Compu
 import type App from "../../app.js";
 import { EcsCompute, type EcsComputeProps, type EcsServiceConfig, type ServiceLogAlarm, type EcsContainerConfig, type EcsScalingConfig, type EcsClusterConfig, type EcsRoutingConfig, type EcsCapacityProviderConfig, type ContainerDependency, type EcsMigrationsConfig, ECS_CAPACITY_PROVIDER_CONFIG, getEcsCapacityProviderConfig, ScalingType, type EcsCapacityProvider, type Ec2CapacityConfig, validateEcsProps, buildContainerConfigs, expandMigrationsSugar, type ResolvedScalingConfig, resolveScalingConfig } from "./computeEcs.js";
 import { LambdaCompute, type LambdaComputeProps, type ContainerLambdaProps, type CodeLambdaProps, type FunctionUrlConfig, type ResolvedLambdaDeployment, resolveLambdaDeployment, lambdaImageKey, Architecture, HttpMethod, InvokeMode, type FunctionUrlCorsOptions } from "./computeLambda.js";
-import { Ec2Compute, type Ec2ComputeProps, type SshConfig } from "./computeEc2.js";
-export { EcsCompute, type EcsComputeProps, type EcsServiceConfig, type ServiceLogAlarm, type EcsContainerConfig, type EcsScalingConfig, type EcsClusterConfig, type EcsRoutingConfig, type EcsCapacityProviderConfig, ECS_CAPACITY_PROVIDER_CONFIG, getEcsCapacityProviderConfig, ScalingType, type EcsCapacityProvider, type Ec2CapacityConfig, type ContainerDependency, type EcsMigrationsConfig, validateEcsProps, buildContainerConfigs, expandMigrationsSugar, type ResolvedScalingConfig, resolveScalingConfig, LambdaCompute, type LambdaComputeProps, type ContainerLambdaProps, type CodeLambdaProps, type FunctionUrlConfig, type ResolvedLambdaDeployment, resolveLambdaDeployment, lambdaImageKey, Architecture, HttpMethod, InvokeMode, type FunctionUrlCorsOptions, Ec2Compute, type Ec2ComputeProps, type SshConfig };
+import { Ec2Compute, type Ec2ComputeProps } from "./computeEc2.js";
+export { EcsCompute, type EcsComputeProps, type EcsServiceConfig, type ServiceLogAlarm, type EcsContainerConfig, type EcsScalingConfig, type EcsClusterConfig, type EcsRoutingConfig, type EcsCapacityProviderConfig, ECS_CAPACITY_PROVIDER_CONFIG, getEcsCapacityProviderConfig, ScalingType, type EcsCapacityProvider, type Ec2CapacityConfig, type ContainerDependency, type EcsMigrationsConfig, validateEcsProps, buildContainerConfigs, expandMigrationsSugar, type ResolvedScalingConfig, resolveScalingConfig, LambdaCompute, type LambdaComputeProps, type ContainerLambdaProps, type CodeLambdaProps, type FunctionUrlConfig, type ResolvedLambdaDeployment, resolveLambdaDeployment, lambdaImageKey, Architecture, HttpMethod, InvokeMode, type FunctionUrlCorsOptions, Ec2Compute, type Ec2ComputeProps };
 export type { ComputeType } from "./interfaces/compute.js";
 /**
  * Configuration defaults for each compute type.

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

@@ -3,31 +3,18 @@ import { type IAutoScalingGroup } from "aws-cdk-lib/aws-autoscaling";
 import { Construct } from "constructs";
 import { type IEc2Compute } from "./interfaces/compute.js";
 import { Ec2Instance } from "../../resources/aws/compute/ec2.js";
-/**
- * SSH access configuration for EC2 instances.
- * - Omit: disabled (default)
- * - `{}`: enabled with auto-generated key
- * - `{ keyName: "my-key" }`: enabled with existing key
- * - `false`: explicitly disabled
- */
-export interface SshConfig {
-    /** SSH key pair name */
-    keyName?: string;
-    /** Allowed CIDR blocks for SSH access */
-    allowedCidrs?: string[];
-}
+import { type Ec2SshAccessProps } from "../../resources/aws/compute/ec2SshAccess.js";
 export interface Ec2ComputeProps {
     type: "ec2";
     vpc?: IVpc;
     /** EC2 instance type. Default: "t4g.micro" */
     instanceType?: string;
     /**
-     * SSH access configuration.
-     * - Omit: disabled (default)
-     * - `{}`: enabled with defaults
-     * - `false`: explicitly disabled
+     * SSH access: who may reach port 22 (`allowedIpCidrs`), which key pair
+     * (`keyName`, or omit to mint one) and whether the instances are public
+     * (`public`). Omit for Session Manager-only access, the default.
      */
-    ssh?: SshConfig | false;
+    sshAccess?: Ec2SshAccessProps;
     /** User data script */
     userData?: UserData;
     /** Machine image (AMI) */

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

@@ -1,5 +1,7 @@
 import { Construct } from "constructs";
+import { ec2ServiceName } from "@fjall/util";
 import { Ec2Instance } from "../../resources/aws/compute/ec2.js";
+import { checkRetiredSshProp } from "../../resources/aws/compute/ec2SshAccess.js";
 import { COMPUTE_DEFAULTS } from "./compute.js";
 /**
  * EC2 compute wrapper implementing IEc2Compute.
@@ -11,11 +13,15 @@ export class Ec2Compute extends Construct {
     ec2Instance;
     constructor(scope, id, props) {
         super(scope, id);
-        const enableSSH = props.ssh !== undefined && props.ssh !== false;
+        // The retired `ssh` prop read only its own presence (`keyName` and
+        // `allowedCidrs` were declared and never forwarded); a caller still
+        // passing it gets the translation, or a warning when it asked for the
+        // default.
+        checkRetiredSshProp(this, "Ec2Compute", props);
         const ec2Props = {
-            serviceName: `${id}Service`,
+            serviceName: ec2ServiceName(id),
             instanceType: props.instanceType || COMPUTE_DEFAULTS.EC2.INSTANCE_TYPE,
-            enableSSH,
+            ...(props.sshAccess !== undefined && { sshAccess: props.sshAccess }),
             userData: props.userData,
             machineImage: props.machineImage,
             minCapacity: props.minCapacity || COMPUTE_DEFAULTS.EC2.MIN_CAPACITY,

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

@@ -1,6 +1,6 @@
 import { type ICluster, type IBaseService, type TaskDefinition, type FargateTaskDefinition } from "aws-cdk-lib/aws-ecs";
 import { type Connections, type ISecurityGroup } from "aws-cdk-lib/aws-ec2";
-import { type IGrantable, type IRole, Grant } from "aws-cdk-lib/aws-iam";
+import { type Grant, type IGrantable, type IRole } from "aws-cdk-lib/aws-iam";
 import { type IApplicationLoadBalancer, type ApplicationListener } from "aws-cdk-lib/aws-elasticloadbalancingv2";
 import { Construct } from "constructs";
 import { type IEcsCompute } from "./interfaces/compute.js";
@@ -264,9 +264,9 @@ export declare class EcsCompute extends Construct implements IEcsCompute {
      */
     getEcsCluster(): EcsCluster;
     /**
-     * Grants ecs:ExecuteCommand permission for ECS services.
-     * Uses wildcard resource because ecs:ExecuteCommand targets task ARNs
-     * which are not known until runtime (tasks are ephemeral).
+     * Grant what an ECS Exec caller needs: `ecs:ExecuteCommand` on this
+     * cluster's tasks and, at a tier that encrypts the session, the
+     * `kms:GenerateDataKey` on the stack key the caller must hold.
      */
     grantExecuteCommand(grantee: IGrantable): Grant;
     /**

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

@@ -1,6 +1,6 @@
 import { AwsLogDriver, ContainerImage, DeploymentLifecycleStage, Secret as EcsSecret } from "aws-cdk-lib/aws-ecs";
 import { Peer, Port, SubnetType } from "aws-cdk-lib/aws-ec2";
-import { Effect, Grant, PolicyStatement, ServicePrincipal } from "aws-cdk-lib/aws-iam";
+import { Effect, PolicyStatement, ServicePrincipal } from "aws-cdk-lib/aws-iam";
 import { Annotations, Aws, Stack, Token } from "aws-cdk-lib";
 import { RetentionDays } from "aws-cdk-lib/aws-logs";
 import { StringParameter } from "aws-cdk-lib/aws-ssm";
@@ -1688,16 +1688,12 @@ export class EcsCompute extends Construct {
         return this.ecsCluster;
     }
     /**
-     * Grants ecs:ExecuteCommand permission for ECS services.
-     * Uses wildcard resource because ecs:ExecuteCommand targets task ARNs
-     * which are not known until runtime (tasks are ephemeral).
+     * Grant what an ECS Exec caller needs: `ecs:ExecuteCommand` on this
+     * cluster's tasks and, at a tier that encrypts the session, the
+     * `kms:GenerateDataKey` on the stack key the caller must hold.
      */
     grantExecuteCommand(grantee) {
-        return Grant.addToPrincipal({
-            grantee,
-            actions: ["ecs:ExecuteCommand"],
-            resourceArns: ["*"]
-        });
+        return this.ecsCluster.grantExecuteCommand(grantee);
     }
     /**
      * Get the EC2 instance role for the cluster's underlying ASG. EC2-mode

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

@@ -42,7 +42,7 @@ const COMPUTE_PROP_APPLICABILITY = {
     cmd: ["lambda"],
     workingDirectory: ["lambda"],
     instanceType: ["ec2"],
-    ssh: ["ec2"],
+    sshAccess: ["ec2"],
     userData: ["ec2"],
     machineImage: ["ec2"],
     minCapacity: ["ec2"],

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

@@ -3,15 +3,20 @@ import { type Construct } from "constructs";
 import { type KeyValue } from "../../types.js";
 import { type Connections } from "aws-cdk-lib/aws-ec2";
 import { type IVpc } from "aws-cdk-lib/aws-ec2";
-interface ProxyAgentProps extends StackProps {
+export interface FivetranProxyProps extends StackProps {
     accountId?: string;
     vpc?: IVpc;
     publicKey: string;
     instanceType: string;
+    /**
+     * Source ranges Fivetran connects from, one port-22 ingress rule each.
+     * Fivetran publishes its addresses per region; the proxy ships no
+     * world-open default.
+     */
+    allowedIpCidrs: string[];
     databaseConnection?: Connections;
     tags?: KeyValue;
 }
 export declare class FivetranProxy extends Stack {
-    constructor(scope: Construct, id: string, props: ProxyAgentProps);
+    constructor(scope: Construct, id: string, props: FivetranProxyProps);
 }
-export {};

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

@@ -4,6 +4,10 @@ import { UserData } from "aws-cdk-lib/aws-ec2";
 export class FivetranProxy extends Stack {
     constructor(scope, id, props) {
         super(scope, id, props);
+        if (!Array.isArray(props.allowedIpCidrs) ||
+            props.allowedIpCidrs.length === 0) {
+            throw new Error("FivetranProxy.allowedIpCidrs must list at least one IPv4 CIDR: the ranges Fivetran connects from for your region. The proxy ships no world-open default.");
+        }
         const userData = UserData.forLinux();
         userData.addCommands("groupadd fivetran", "useradd -m -g fivetran fivetran", "mkdir -p /home/fivetran/.ssh", "chown fivetran:fivetran /home/fivetran/.ssh", "chmod 700 /home/fivetran/.ssh", `echo "${props.publicKey}" > /home/fivetran/.ssh/authorized_keys`, "chown fivetran:fivetran /home/fivetran/.ssh/authorized_keys", "chmod 600 /home/fivetran/.ssh/authorized_keys");
         new Ec2Instance(this, "FivetranProxy", {
@@ -11,12 +15,11 @@ export class FivetranProxy extends Stack {
             serviceName: "fivetranProxy",
             vpc: props.vpc,
             instanceType: props.instanceType || "t2.micro",
-            // Not a caller's choice. This proxy exists so Fivetran can reach a
-            // private database over SSH — it provisions the `fivetran` user and its
-            // authorized_keys above — so the instance must be publicly reachable on
-            // port 22. The prop that used to sit here was `props.enableSSH || true`,
-            // which accepted a `false` it could never honour.
-            enableSSH: true,
+            // This proxy exists so Fivetran can reach a private database over SSH
+            // (it provisions the `fivetran` user and its authorized_keys above), so
+            // the instance must be publicly reachable on port 22. `public` is
+            // therefore not the caller's choice; the source range is.
+            sshAccess: { allowedIpCidrs: props.allowedIpCidrs, public: true },
             env: {
                 account: props.env?.account,
                 region: props.env?.region

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

@@ -73,6 +73,14 @@ export interface IEcsCompute extends ICompute, IConnectable {
      * that front this compute. Undefined when there is no load balancer.
      */
     getIngressProfile(): EcsIngressProfile | undefined;
+    /**
+     * Grant an operator principal what an `aws ecs execute-command` session
+     * needs against this cluster: `ecs:ExecuteCommand` scoped to the cluster
+     * and its tasks, plus `kms:GenerateDataKey` on the stack key when the
+     * session channel is key-encrypted (backup tier `enterprise`).
+     * @param grantee The operator principal
+     */
+    grantExecuteCommand(grantee: IGrantable): Grant;
 }
 /**
  * Lambda compute interface.

package/dist/lib/resources/aws/cdn/cloudFront.d.ts

@@ -58,7 +58,23 @@ export interface CloudFrontDistributionProps {
     domainNames?: string[];
     certificate?: ICertificate;
     comment?: string;
+    /**
+     * Standard (legacy) S3 access logging. It cannot deliver to a bucket in an
+     * opt-in region (`af-south-1`, `ap-east-1`, …): CloudFormation rejects the
+     * distribution at deploy, so a concrete opt-in delivery region is refused
+     * at synth instead — cure with `enableLogging: false`, or a `logBucket`
+     * whose region CDK knows to be default-enabled (see `logBucket`).
+     */
     enableLogging?: boolean;
+    /**
+     * Delivery bucket for standard logs; without it CDK creates one in the
+     * distribution's own stack (and region). Its `env.region` is the delivery
+     * region the opt-in refusal on `enableLogging` checks, so an imported
+     * bucket must declare it: `Bucket.fromBucketAttributes(…, { region })`, or
+     * a `Bucket` in a stack pinned to its region. `fromBucketName` and
+     * `fromBucketArn` inherit this stack's region, and a token bucket region
+     * falls back to it.
+     */
     logBucket?: IBucket;
     /** Key prefix for standard logs delivered to `logBucket`. */
     logFilePrefix?: string;

package/dist/lib/resources/aws/cdn/cloudFront.js

@@ -1,8 +1,8 @@
 import { Construct } from "constructs";
-import { CfnOutput, Names, Stack } from "aws-cdk-lib";
+import { CfnOutput, Names, Stack, Token } from "aws-cdk-lib";
 import { toPascalCase } from "../../../utils/capitaliseString.js";
 import { registerCdnAliasTarget } from "../../../utils/cdnAliasTargetRegistry.js";
-import { cdnDomainExportName } from "@fjall/util";
+import { cdnDomainExportName, getRegionInfo, OPT_IN_REGION_CODES } from "@fjall/util";
 import { Distribution, PriceClass, ViewerProtocolPolicy, CachePolicy, OriginRequestPolicy, AllowedMethods, OriginProtocolPolicy, Function as CloudFrontFunction, FunctionCode, FunctionRuntime, FunctionEventType, OriginAccessIdentity, S3OriginAccessControl } from "aws-cdk-lib/aws-cloudfront";
 import { S3BucketOrigin, LoadBalancerV2Origin, HttpOrigin } from "aws-cdk-lib/aws-cloudfront-origins";
 /**
@@ -42,6 +42,55 @@ const URI_REWRITE_FRAGMENTS = {
         " else { var seg = uri.substring(uri.lastIndexOf('/') + 1);" +
         " if (seg.indexOf('.') === -1) { request.uri = uri + '/index.html'; } } }"
 };
+/**
+ * CloudFront standard (legacy) logging cannot deliver to an S3 bucket in an
+ * opt-in region: CDK's `renderLogging` performs no region check and
+ * CloudFormation rejects the distribution at deploy, after the rest of the
+ * stack has been created. The delivery region is known at synth whenever the
+ * bucket's stack is env-pinned, so the refusal lives here — the seam every
+ * distribution crosses, whether built directly or through the `Cdn`
+ * pattern — and names both cures.
+ *
+ * Logging is on exactly when `renderLogging` emits a Logging block:
+ * `enableLogging: true`, or a `logBucket` without an explicit
+ * `enableLogging: false` (that pair is CDK's own contradiction error and is
+ * left to it). The delivery region is the bucket's `env.region` when it is
+ * concrete, else the distribution stack's — the bucket CDK would create.
+ * A token delivery region (an unpinned stack, and no region on the bucket)
+ * cannot be checked and passes. A concrete region `AWS_REGIONS_METADATA`
+ * does not list is refused too — every region launched since 2019 is opt-in,
+ * so an unlisted one cannot be assumed default-enabled — naming the metadata
+ * as the cure. The guard fires whenever the delivery region is concrete and
+ * known to the metadata.
+ */
+function validateStandardLoggingRegion(scope, id, props) {
+    const loggingOn = props.enableLogging === true ||
+        (props.enableLogging === undefined && props.logBucket !== undefined);
+    if (!loggingOn)
+        return;
+    const bucketRegion = props.logBucket?.env.region;
+    const region = bucketRegion !== undefined && !Token.isUnresolved(bucketRegion)
+        ? bucketRegion
+        : Stack.of(scope).region;
+    if (Token.isUnresolved(region))
+        return;
+    if (getRegionInfo(region) === undefined) {
+        throw new Error(`CloudFront distribution '${id}': region ${region} is not in ` +
+            "@fjall/util's AWS_REGIONS_METADATA, so its opt-in status cannot be " +
+            "checked — update the metadata, or set enableLogging: false on this " +
+            "CDN.");
+    }
+    if (!OPT_IN_REGION_CODES.has(region))
+        return;
+    throw new Error(`CloudFront distribution '${id}': standard (legacy) logging cannot ` +
+        `deliver to an S3 bucket in opt-in region ${region} — logging was ` +
+        "enabled explicitly or by the app backup tier's cloudFrontLogging " +
+        "default. Set enableLogging: false on this CDN, or pass a logBucket " +
+        "whose region CDK knows to be default-enabled: " +
+        "Bucket.fromBucketAttributes(…, { region }), or a bucket in a stack " +
+        "pinned to that region (fromBucketName and fromBucketArn inherit this " +
+        "stack's region).");
+}
 export class CloudFrontDistribution extends Construct {
     id;
     distribution;
@@ -53,6 +102,7 @@ export class CloudFrontDistribution extends Construct {
     constructor(scope, id, props) {
         super(scope, id);
         this.id = id;
+        validateStandardLoggingRegion(this, id, props);
         // Sanitise id for CloudFormation output keys (must be alphanumeric)
         const outputName = toPascalCase(id);
         const defaultOrigin = this.createOrigin(props.defaultOrigin);

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

@@ -1,5 +1,6 @@
 import { type BlockDevice, type IMachineImage, type IVpc, type UserData, type ISecurityGroup, type IConnectable, Connections, type SubnetConfiguration, type SubnetSelection } from "aws-cdk-lib/aws-ec2";
 import { Construct } from "constructs";
+import { type Ec2SshAccessProps } from "./ec2SshAccess.js";
 import { Duration, Stack, type StackProps } from "aws-cdk-lib";
 import { type Role } from "aws-cdk-lib/aws-iam";
 import { AutoScalingGroup, Monitoring, type WarmPoolOptions } from "aws-cdk-lib/aws-autoscaling";
@@ -42,6 +43,7 @@ export type Ec2InstanceUpdatePolicyConfig = {
 } | {
     type: "none";
 };
+export { type Ec2SshAccessProps } from "./ec2SshAccess.js";
 export interface Ec2InstanceProps extends StackProps {
     spotCapacityPercentage?: number;
     blockDevices?: BlockDevice[];
@@ -57,7 +59,13 @@ export interface Ec2InstanceProps extends StackProps {
     machineImage?: IMachineImage;
     userData?: UserData;
     role?: Role;
-    enableSSH?: boolean;
+    /**
+     * SSH access: who may reach port 22, which key pair, and whether the
+     * instances are public. Omit for Session Manager-only access. Rejected
+     * alongside a caller-supplied `securityGroup` — the construct adds ingress
+     * only to a security group it owns.
+     */
+    sshAccess?: Ec2SshAccessProps;
     defaultPort?: number;
     /**
      * Caller-supplied EC2 instance monitoring resolution. Routes through the
@@ -79,8 +87,10 @@ export interface Ec2InstanceProps extends StackProps {
     securityGroup?: ISecurityGroup;
     /**
      * CDK `AutoScalingGroupProps.vpcSubnets`. Overrides the default
-     * `enableSSH ? PUBLIC : resolvePrivateSubnetType(vpc)` inference. Use when
-     * the caller needs a precise subnet selection (e.g. AZ pinning).
+     * `sshAccess.public ? PUBLIC : resolvePrivateSubnetType(vpc)` inference.
+     * Use when the caller needs a precise subnet selection (e.g. AZ pinning).
+     * With `sshAccess.public: true` the selection may pin availability zones
+     * but not choose a non-public subnet type, group or list.
      */
     vpcSubnets?: SubnetSelection;
     /** CDK `AutoScalingGroupProps.capacityRebalance`. Absent → CDK default. */
@@ -92,9 +102,9 @@ export interface Ec2InstanceProps extends StackProps {
      */
     warmPool?: WarmPoolOptions;
     /**
-     * CDK `LaunchTemplateProps.associatePublicIpAddress`. When defined,
-     * overrides the `!!keyPair` auto-derivation; otherwise the existing
-     * keyPair-driven default applies.
+     * CDK `LaunchTemplateProps.associatePublicIpAddress`. Absent → `true` only
+     * when `sshAccess.public` is `true`. An explicit `false` alongside
+     * `sshAccess.public: true` is rejected rather than silently overridden.
      */
     associatePublicIpAddress?: boolean;
     /**
@@ -162,11 +172,28 @@ export declare class Ec2Instance extends Construct implements IConnectable {
     private autoScalingGroup;
     private keyPair;
     private persistentDataVolume?;
+    private readonly vpcSubnets;
+    private readonly associatePublicIpAddress;
     readonly connections: Connections;
     constructor(scope: Construct, id: string, props: Ec2InstanceProps);
     private addVpc;
     private addKeyPair;
+    /**
+     * 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.
+     */
+    private addSshIngress;
     private addLaunchTemplate;
+    /**
+     * `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.
+     */
+    private resolveVpcSubnets;
     private addAutoScalingGroup;
     /**
      * Apply `props.tags` to the underlying ASG with

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

@@ -178,9 +178,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/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

package/dist/lib/resources/aws/messaging/sns.js

@@ -1,7 +1,6 @@
 import { Construct } from "constructs";
 import { CfnOutput } from "aws-cdk-lib";
 import { Topic } from "aws-cdk-lib/aws-sns";
-import { tierDefault } from "../../../utils/backupTierMapping.js";
 import { StackEncryptionKey } from "../secrets/stackEncryptionKey.js";
 import { toRemovalPolicy } from "./utils.js";
 export class SNSTopic extends Construct {
@@ -11,10 +10,11 @@ export class SNSTopic extends Construct {
         super(scope, id);
         this.id = id;
         const isFifo = props.fifo === true;
+        const encryptionOverride = props.encryption === undefined
+            ? undefined
+            : props.encryption === "SSE_KMS";
         const masterKey = props.masterKey ??
-            (tierDefault(props.appBackupTier, "customerManagedKeys")
-                ? StackEncryptionKey.of(this).forSnsServicePublishers()
-                : undefined);
+            StackEncryptionKey.forTier(this, props.appBackupTier, encryptionOverride)?.forSnsServicePublishers();
         const topicName = props.topicName
             ? isFifo
                 ? `${props.topicName}.fifo`

package/dist/lib/resources/aws/secrets/stackEncryptionKey.d.ts

@@ -1,5 +1,6 @@
 import type { IKey } from "aws-cdk-lib/aws-kms";
 import type { Construct } from "constructs";
+import { type BackupTier } from "../../../utils/backupTierMapping.js";
 import { CustomerManagedKey } from "./kms.js";
 /**
  * The one customer-managed KMS key an enterprise-tier stack encrypts its
@@ -16,10 +17,12 @@ import { CustomerManagedKey } from "./kms.js";
  * costs $1–3/month; a destroyed key would render the surviving table
  * permanently unreadable after its 30-day pending window.
  *
- * Grant-based consumers (DynamoDB, Lambda `environmentEncryption`, ECS Exec)
- * read `key` directly — the SDK/CDK grants they need ride the resource's own
- * IAM path. Service-side encryptors need a resource-policy admission first:
- * CloudWatch Logs through [[forLogGroups]], SNS service publishers through
+ * Constructs reach it through [[forTier]] — the one place the tier's
+ * `customerManagedKeys` column is read. Grant-based consumers (DynamoDB,
+ * Lambda `environmentEncryption`, ECS Exec) then read `key` directly — the
+ * SDK/CDK grants they need ride the resource's own IAM path. Service-side
+ * encryptors need a resource-policy admission first: CloudWatch Logs through
+ * [[forLogGroups]], SNS service publishers through
  * [[forSnsServicePublishers]]. Each admission is added once per stack.
  */
 export declare class StackEncryptionKey extends CustomerManagedKey {
@@ -28,6 +31,16 @@ export declare class StackEncryptionKey extends CustomerManagedKey {
     private constructor();
     /** The stack's shared key, created on first use. */
     static of(scope: Construct): StackEncryptionKey;
+    /**
+     * The stack's shared key when the tier's `customerManagedKeys` column says
+     * so, else `undefined` — the one place the column is read. A resource with
+     * its own encryption vocabulary (DynamoDB `encryption`, SNS `encryption`)
+     * passes the explicit choice as `override`; `undefined` lets the tier
+     * decide. The key is only created when the answer is yes, so an opt-out at
+     * enterprise mints nothing and an opt-in below enterprise mints the shared
+     * key rather than a per-resource one.
+     */
+    static forTier(scope: Construct, tier: BackupTier | undefined, override?: boolean): StackEncryptionKey | undefined;
     /**
      * The key, with CloudWatch Logs admitted to it. The CDK `LogGroup` sets
      * `KmsKeyId` but adds no key-policy statement, and without one the

package/dist/lib/resources/aws/secrets/stackEncryptionKey.js

@@ -1,5 +1,6 @@
 import { Stack } from "aws-cdk-lib";
 import { PolicyStatement, ServicePrincipal } from "aws-cdk-lib/aws-iam";
+import { tierDefault } from "../../../utils/backupTierMapping.js";
 import { CustomerManagedKey } from "./kms.js";
 const STACK_ENCRYPTION_KEY_ID = "FjallStackEncryptionKey";
 /**
@@ -33,10 +34,12 @@ const SNS_SERVICE_PUBLISHERS = [
  * costs $1–3/month; a destroyed key would render the surviving table
  * permanently unreadable after its 30-day pending window.
  *
- * Grant-based consumers (DynamoDB, Lambda `environmentEncryption`, ECS Exec)
- * read `key` directly — the SDK/CDK grants they need ride the resource's own
- * IAM path. Service-side encryptors need a resource-policy admission first:
- * CloudWatch Logs through [[forLogGroups]], SNS service publishers through
+ * Constructs reach it through [[forTier]] — the one place the tier's
+ * `customerManagedKeys` column is read. Grant-based consumers (DynamoDB,
+ * Lambda `environmentEncryption`, ECS Exec) then read `key` directly — the
+ * SDK/CDK grants they need ride the resource's own IAM path. Service-side
+ * encryptors need a resource-policy admission first: CloudWatch Logs through
+ * [[forLogGroups]], SNS service publishers through
  * [[forSnsServicePublishers]]. Each admission is added once per stack.
  */
 export class StackEncryptionKey extends CustomerManagedKey {
@@ -59,6 +62,19 @@ export class StackEncryptionKey extends CustomerManagedKey {
             return existing;
         return new StackEncryptionKey(stack);
     }
+    /**
+     * The stack's shared key when the tier's `customerManagedKeys` column says
+     * so, else `undefined` — the one place the column is read. A resource with
+     * its own encryption vocabulary (DynamoDB `encryption`, SNS `encryption`)
+     * passes the explicit choice as `override`; `undefined` lets the tier
+     * decide. The key is only created when the answer is yes, so an opt-out at
+     * enterprise mints nothing and an opt-in below enterprise mints the shared
+     * key rather than a per-resource one.
+     */
+    static forTier(scope, tier, override) {
+        const onStackKey = override ?? tierDefault(tier, "customerManagedKeys");
+        return onStackKey ? StackEncryptionKey.of(scope) : undefined;
+    }
     /**
      * The key, with CloudWatch Logs admitted to it. The CDK `LogGroup` sets
      * `KmsKeyId` but adds no key-policy statement, and without one the

package/dist/lib/resources/aws/storage/s3.d.ts

@@ -68,7 +68,8 @@ export interface S3BucketProps extends BucketProps {
      * `S3_VERSIONING_DISABLED` finding `mitigated` rather than `open` on
      * buckets whose contents are rebuilt, not kept. Constructs pass it for the
      * buckets they own (Payload build output and ISR cache, ClickHouse cold
-     * tier); an author may pass it for a disposable bucket of their own.
+     * tier, the stack access-log bucket); an author may pass it for a
+     * disposable bucket of their own.
      */
     versioningExemption?: S3VersioningExemption;
     publicReadAccess?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/components-infrastructure",
-  "version": "33.1.0",
+  "version": "34.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fjall-tech/fjall.git",
@@ -39,7 +39,8 @@
     "clean": "rm -rf ./dist",
     "clean:node": "rm -rf ./node_modules",
     "build:cert-gen-lambda": "node lib/lambda-assets/cert-generator/src/build.mjs",
-    "build": "npm run clean && npm run build:cert-gen-lambda && tsc && cp -r lib/layers dist/lib/layers && mkdir -p dist/lib/lambda-assets/cert-generator/asset && cp lib/lambda-assets/cert-generator/asset/index.js dist/lib/lambda-assets/cert-generator/asset/index.js && cp lib/lambda-assets/cert-generator/asset/package.json dist/lib/lambda-assets/cert-generator/asset/package.json && mkdir -p dist/lib/lambda-assets/identity-store-user/asset && cp lib/lambda-assets/identity-store-user/asset/index.js dist/lib/lambda-assets/identity-store-user/asset/index.js && cp lib/lambda-assets/identity-store-user/asset/package.json dist/lib/lambda-assets/identity-store-user/asset/package.json && mkdir -p dist/lib/lambda-assets/static-site-forms/asset && cp lib/lambda-assets/static-site-forms/asset/index.js dist/lib/lambda-assets/static-site-forms/asset/index.js && cp lib/lambda-assets/static-site-forms/asset/package.json dist/lib/lambda-assets/static-site-forms/asset/package.json && cp lib/resources/aws/compute/lifecycleHookLambda.source.cjs dist/lib/resources/aws/compute/lifecycleHookLambda.source.cjs && cp lib/resources/aws/compute/ec2GracefulTerminationLambda.source.cjs dist/lib/resources/aws/compute/ec2GracefulTerminationLambda.source.cjs && cp lib/resources/aws/compute/persistentDataVolumeLambda.source.cjs dist/lib/resources/aws/compute/persistentDataVolumeLambda.source.cjs && cp lib/patterns/aws/devSubstrate.waker.source.cjs dist/lib/patterns/aws/devSubstrate.waker.source.cjs && node ../../scripts/stamp-build.mjs",
+    "build": "node ../../scripts/run-build.mjs --purpose=build -- npm run build:steps",
+    "build:steps": "npm run clean && npm run build:cert-gen-lambda && tsc && cp -r lib/layers dist/lib/layers && mkdir -p dist/lib/lambda-assets/cert-generator/asset && cp lib/lambda-assets/cert-generator/asset/index.js dist/lib/lambda-assets/cert-generator/asset/index.js && cp lib/lambda-assets/cert-generator/asset/package.json dist/lib/lambda-assets/cert-generator/asset/package.json && mkdir -p dist/lib/lambda-assets/identity-store-user/asset && cp lib/lambda-assets/identity-store-user/asset/index.js dist/lib/lambda-assets/identity-store-user/asset/index.js && cp lib/lambda-assets/identity-store-user/asset/package.json dist/lib/lambda-assets/identity-store-user/asset/package.json && mkdir -p dist/lib/lambda-assets/static-site-forms/asset && cp lib/lambda-assets/static-site-forms/asset/index.js dist/lib/lambda-assets/static-site-forms/asset/index.js && cp lib/lambda-assets/static-site-forms/asset/package.json dist/lib/lambda-assets/static-site-forms/asset/package.json && cp lib/resources/aws/compute/lifecycleHookLambda.source.cjs dist/lib/resources/aws/compute/lifecycleHookLambda.source.cjs && cp lib/resources/aws/compute/ec2GracefulTerminationLambda.source.cjs dist/lib/resources/aws/compute/ec2GracefulTerminationLambda.source.cjs && cp lib/resources/aws/compute/persistentDataVolumeLambda.source.cjs dist/lib/resources/aws/compute/persistentDataVolumeLambda.source.cjs && cp lib/patterns/aws/devSubstrate.waker.source.cjs dist/lib/patterns/aws/devSubstrate.waker.source.cjs && node ../../scripts/stamp-build.mjs",
     "prepack": "node ../../scripts/check-dist-freshness.mjs",
     "prepublishOnly": "node ../../scripts/audit-package-tarball.mjs",
     "watch": "tsc -w",
@@ -79,8 +80,8 @@
   },
   "dependencies": {
     "@aws-sdk/client-organizations": "^3.1098.0",
-    "@fjall/generator": "^33.1.0",
-    "@fjall/util": "^33.1.0",
+    "@fjall/generator": "^34.0.0",
+    "@fjall/util": "^34.0.0",
     "constructs": "^10.7.2",
     "zod": "^4.4.3"
   },