@fjall/components-infrastructure 33.0.0 → 34.0.0

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

@@ -182,8 +182,8 @@ export interface EcsContainerConfig {
  *   per service. Suitable for high-replica services where the init-container
  *   tax dominates rollout time.
  *
- * @see aiDocs/decisions/2026-04-29-ecs-init-container-over-runtask.md
- * @see aiDocs/plans/2026-04-29-ecs-factory-hardening.md § 4.3.4 — threshold
+ * @see the 2026-04-29 decision: ECS init container over RunTask
+ * @see the 2026-04-29 ECS factory-hardening plan, § 4.3.4 — threshold
  *   guidance for choosing between modes.
  * @see https://aws.amazon.com/blogs/containers/announcing-amazon-ecs-deployment-lifecycle-hooks/
  */
@@ -223,7 +223,7 @@ export type EcsMigrationsMode = "init-container" | "lifecycle-hook" | "post-depl
  *   mode: "lifecycle-hook"
  * }
  *
- * @see aiDocs/decisions/2026-04-29-ecs-init-container-over-runtask.md
+ * @see the 2026-04-29 decision: ECS init container over RunTask
  */
 /**
  * Discriminated on `mode`. The init-container variant keeps its narrow surface
@@ -237,8 +237,8 @@ export type EcsMigrationsMode = "init-container" | "lifecycle-hook" | "post-depl
  * lifecycle-hook-only field — is a typecheck error. This protects against
  * the Pitfall-5 trap (silent field drift across union variants).
  *
- * @see aiDocs/designs/2026-05-12-migration-runner-abstraction-choice.md
- * @see .claude/rules/typescript-standards.md § "Pitfall 5"
+ * @see the 2026-05-12 migration-runner abstraction-choice design
+ * @see the TypeScript standards, Zod Pitfall 5 (three-way option drift)
  */
 export type EcsMigrationsConfig = EcsInitContainerMigrationsConfig | EcsLifecycleHookMigrationsConfig | EcsPostDeployMigrationsConfig;
 /**

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/patterns/aws/payload.js

@@ -217,8 +217,10 @@ export class Payload extends Construct {
     createAssetsBucket() {
         const assetsConfig = this.props.storage?.assets ?? {};
         const assetsProps = {
-            // Build output, pruned on every deploy — versioning would only bill for churn.
+            // Build output, pruned on every deploy — versioning would only bill for
+            // churn; the exemption stamp tells posture the omission is by design.
             versioned: assetsConfig.versioned ?? false,
+            versioningExemption: "build-output",
             deployment: {
                 source: `${PAYLOAD_DEFAULTS.SOURCE}/${PAYLOAD_DEFAULTS.OPENNEXT.ASSETS}`,
                 prune: true,
@@ -233,8 +235,10 @@ export class Payload extends Construct {
     createCacheBucket() {
         const cacheConfig = this.props.storage?.cache ?? {};
         const cacheProps = {
-            // ISR cache, regenerated at runtime — versioning would only bill for churn.
+            // ISR cache, regenerated at runtime — versioning would only bill for
+            // churn; the exemption stamp tells posture the omission is by design.
             versioned: cacheConfig.versioned ?? false,
+            versioningExemption: "isr-cache",
             deployment: {
                 source: `${PAYLOAD_DEFAULTS.SOURCE}/${PAYLOAD_DEFAULTS.OPENNEXT.CACHE}`,
                 prune: false // ISR adds files at runtime

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

@@ -2,6 +2,7 @@ import { Construct } from "constructs";
 import { type EventType, type IBucketNotificationDestination, type NotificationKeyFilter } from "aws-cdk-lib/aws-s3";
 import { type IDistribution } from "aws-cdk-lib/aws-cloudfront";
 import { type IGrantable, type Grant } from "aws-cdk-lib/aws-iam";
+import { type S3VersioningExemption } from "@fjall/util/aws";
 import type App from "../../app.js";
 import { BucketDeployment, S3Bucket, type ResourcePolicyStatement, type WebsiteHostingConfig } from "../../resources/aws/storage/index.js";
 import { type BackupTier } from "../../utils/backupTierMapping.js";
@@ -39,6 +40,13 @@ export interface S3Props {
      * `resilient`/`enterprise`, off otherwise. An explicit value always wins.
      */
     readonly versioned?: boolean;
+    /**
+     * Why this bucket runs unversioned by design (`build-output`, `isr-cache`,
+     * `cold-tier`) — see `S3BucketProps.versioningExemption`. Stamped as the
+     * `fjall:s3:versioning-exempt` tag when versioning resolves off; a bucket
+     * that versions after all is not stamped.
+     */
+    readonly versioningExemption?: S3VersioningExemption;
     readonly encryption?: "AES256" | "KMS";
     readonly kmsKeyArn?: string;
     /**

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

@@ -78,6 +78,7 @@ export class Storage extends Construct {
             aliasTargetName: props.bucketName ?? id,
             appName: props.appName,
             versioned: props.versioned,
+            versioningExemption: props.versioningExemption,
             encryption: toBucketEncryption(props.encryption),
             encryptionKey,
             ...(props.bucketKeyEnabled !== undefined && {

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/cdn/responseHeadersPolicy.d.ts

@@ -40,7 +40,7 @@ export interface SecurityHeadersPolicyProps {
  * Wrapped on the description + SOC2-defaults trigger (NOT taggability — the
  * resource is not taggable): it owns Fjall's uniform security-header defaults
  * so every consumer inherits the same posture in one edit. Per
- * `.claude/rules/generator-standards.md § Wrapper Routing Discipline`,
+ * the Wrapper Routing Discipline rule (generator standards),
  * `lib/{config,patterns}/` instantiate this class, never the raw L2.
  *
  * Defaults (all `override:true`): HSTS 730d+includeSubdomains+preload,

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

@@ -18,7 +18,7 @@ const DEFAULT_COMMENT = "Fjall security headers policy";
  * Wrapped on the description + SOC2-defaults trigger (NOT taggability — the
  * resource is not taggable): it owns Fjall's uniform security-header defaults
  * so every consumer inherits the same posture in one edit. Per
- * `.claude/rules/generator-standards.md § Wrapper Routing Discipline`,
+ * the Wrapper Routing Discipline rule (generator standards),
  * `lib/{config,patterns}/` instantiate this class, never the raw L2.
  *
  * Defaults (all `override:true`): HSTS 730d+includeSubdomains+preload,

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";
@@ -27,7 +28,7 @@ export type Ec2InstancePersistentDataVolumeConfig = Omit<PersistentDataVolumePro
  *   `AutoScalingScheduledAction.IgnoreUnmodifiedGroupSizeProperties`
  *   regardless. For callers owning rollout externally.
  *
- * See `aiDocs/troubleshooting/clickhouse-rolling-update-window.md` for the
+ * See the ClickHouse rolling-update-window troubleshooting note for the
  * ClickHouse-specific downtime expectations.
  */
 export type Ec2InstanceUpdatePolicyConfig = {
@@ -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;
     /**
@@ -127,7 +137,7 @@ export interface Ec2InstanceProps extends StackProps {
      * ASG `UpdatePolicy` resolution. Absent → `UpdatePolicy.instanceRefresh`
      * (0/100 with `persistentDataVolume`, 100/200 otherwise). See
      * `Ec2InstanceUpdatePolicyConfig` for the variant menu and
-     * `aiDocs/troubleshooting/clickhouse-rolling-update-window.md` for the
+     * the ClickHouse rolling-update-window troubleshooting note for the
      * downtime-window runbook.
      */
     updatePolicy?: Ec2InstanceUpdatePolicyConfig;
@@ -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";
@@ -17,7 +20,7 @@ import { PersistentDataVolume } from "./persistentDataVolume.js";
  * `encrypted: true` enforces EBS encryption at the wrapper layer rather than
  * relying on the AWS account-level "encryption by default" setting — the
  * propagation contract documented in
- * `.claude/rules/generator-standards.md § "Wrapper Routing Discipline"`.
+ * the Wrapper Routing Discipline rule (generator standards).
  */
 const DEFAULT_ROOT_DEVICE_NAME = "/dev/xvda";
 const DEFAULT_ROOT_VOLUME_SIZE_GIB = 30;
@@ -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 {};