@fjall/components-infrastructure 33.0.0 → 34.0.0

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

@@ -155,7 +155,7 @@ export declare const CLICKHOUSE_NATIVE_PORT = 9000;
 export declare const CLICKHOUSE_PROMETHEUS_PORT = 9363;
 /** TLS-mode ClickHouse ports.
  *  HTTPS replaces 8123; secure native protocol replaces 9000.
- *  See aiDocs/patterns/clickhouse-tls-pattern.md § "The contract". */
+ *  See the ClickHouse TLS pattern, § "The contract". */
 export declare const CLICKHOUSE_HTTPS_PORT = 8443;
 export declare const CLICKHOUSE_TCP_SECURE_PORT = 9440;
 /** Mount path inside the ClickHouse container for the materialised TLS cert
@@ -188,8 +188,8 @@ export declare function clickHouseUserSecretName(userName: string): string;
  *  Canonical source is `@fjall/util/migration § userPasswordEnvName` — re-exported
  *  here so the construct-side import chain stays unchanged while the runner
  *  (`webapp/scripts/migration-runner.mjs`) and any future consumer share a single
- *  declaration. Coupled values per `.claude/rules/code-quality.md § "Coupled values:
- *  shared source at 2 occurrences"`. */
+ *  declaration. Coupled values (the shared-source-at-two-occurrences
+ *  rule). */
 export { userPasswordEnvName } from "@fjall/util/migration";
 /** Env var name carrying the SHA-256 of a user's plaintext password.
  *  The container entrypoint wrapper derives this name from the
@@ -305,8 +305,8 @@ export declare const BACKUP_RETENTION_DAYS = 14;
  *  wrote can be read back. Dropped on the way in and on the way out; never
  *  queried by the application. Canonical source is `@fjall/util/migration`
  *  because `@fjall/clickhouse` grants `fjall_maintenance` DROP on exactly
- *  this database — coupled values per `.claude/rules/code-quality.md §
- *  "Coupled values: shared source at 2 occurrences"`. */
+ *  this database — coupled values (the shared-source-at-two-occurrences
+ *  rule). */
 export { CLICKHOUSE_BACKUP_SCRATCH_DATABASE } from "@fjall/util/migration";
 /** The two scheduled maintenance jobs that authenticate as
  *  `fjall_maintenance`. Drives the per-job log-group → metric-filter wiring

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

@@ -175,7 +175,7 @@ export const CLICKHOUSE_NATIVE_PORT = 9000;
 export const CLICKHOUSE_PROMETHEUS_PORT = 9363;
 /** TLS-mode ClickHouse ports.
  *  HTTPS replaces 8123; secure native protocol replaces 9000.
- *  See aiDocs/patterns/clickhouse-tls-pattern.md § "The contract". */
+ *  See the ClickHouse TLS pattern, § "The contract". */
 export const CLICKHOUSE_HTTPS_PORT = 8443;
 export const CLICKHOUSE_TCP_SECURE_PORT = 9440;
 /** Mount path inside the ClickHouse container for the materialised TLS cert
@@ -210,8 +210,8 @@ export function clickHouseUserSecretName(userName) {
  *  Canonical source is `@fjall/util/migration § userPasswordEnvName` — re-exported
  *  here so the construct-side import chain stays unchanged while the runner
  *  (`webapp/scripts/migration-runner.mjs`) and any future consumer share a single
- *  declaration. Coupled values per `.claude/rules/code-quality.md § "Coupled values:
- *  shared source at 2 occurrences"`. */
+ *  declaration. Coupled values (the shared-source-at-two-occurrences
+ *  rule). */
 export { userPasswordEnvName } from "@fjall/util/migration";
 /** Env var name carrying the SHA-256 of a user's plaintext password.
  *  The container entrypoint wrapper derives this name from the
@@ -347,8 +347,8 @@ export const BACKUP_RETENTION_DAYS = 14;
  *  wrote can be read back. Dropped on the way in and on the way out; never
  *  queried by the application. Canonical source is `@fjall/util/migration`
  *  because `@fjall/clickhouse` grants `fjall_maintenance` DROP on exactly
- *  this database — coupled values per `.claude/rules/code-quality.md §
- *  "Coupled values: shared source at 2 occurrences"`. */
+ *  this database — coupled values (the shared-source-at-two-occurrences
+ *  rule). */
 export { CLICKHOUSE_BACKUP_SCRATCH_DATABASE } from "@fjall/util/migration";
 /** The two scheduled maintenance jobs that authenticate as
  *  `fjall_maintenance`. Drives the per-job log-group → metric-filter wiring

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

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

package/dist/lib/resources/aws/iam/identityCenter/user.d.ts

@@ -8,7 +8,7 @@ export interface IdentityStoreUserProviderProps {
  * Shared Provider-framework backend for Custom::FjallIdentityStoreUser —
  * one handler + provider pair serves every declared user in the stack. A
  * plain AwsCustomResource cannot express the create-or-adopt branching the
- * handler implements (aiDocs/designs/2026-07-04-org-user-management-design.md § 2).
+ * handler implements (the 2026-07-04 organisation user-management design, § 2).
  */
 export declare class IdentityStoreUserProvider extends Construct {
     readonly serviceToken: string;

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

@@ -23,7 +23,7 @@ export function identityStoreUserArnPattern(partition) {
  * Shared Provider-framework backend for Custom::FjallIdentityStoreUser —
  * one handler + provider pair serves every declared user in the stack. A
  * plain AwsCustomResource cannot express the create-or-adopt branching the
- * handler implements (aiDocs/designs/2026-07-04-org-user-management-design.md § 2).
+ * handler implements (the 2026-07-04 organisation user-management design, § 2).
  */
 export class IdentityStoreUserProvider extends Construct {
     serviceToken;

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

@@ -5,9 +5,8 @@ import { type Construct } from "constructs";
  *
  * Applies one default: an explicit, stack-shared log group for the deployment
  * handler lambda, so it is CloudFormation-managed and tagged rather than
- * service-auto-created. Per `.claude/rules/generator-standards.md § Wrapper
- * Routing Discipline` and
- * `patterns/infrastructure-wrapper-routing-pattern.md § A3`, `lib/{config,
+ * service-auto-created. Per the Wrapper Routing Discipline rule (generator
+ * standards) and the infrastructure wrapper-routing pattern (§ A3), `lib/{config,
  * patterns}/` MUST instantiate this class rather than the raw CDK construct.
  */
 export declare class BucketDeployment extends CdkBucketDeployment {

package/dist/lib/resources/aws/storage/bucketDeployment.js

@@ -5,9 +5,8 @@ import { stackSingletonLogGroup } from "../logging/singletonLogGroup.js";
  *
  * Applies one default: an explicit, stack-shared log group for the deployment
  * handler lambda, so it is CloudFormation-managed and tagged rather than
- * service-auto-created. Per `.claude/rules/generator-standards.md § Wrapper
- * Routing Discipline` and
- * `patterns/infrastructure-wrapper-routing-pattern.md § A3`, `lib/{config,
+ * service-auto-created. Per the Wrapper Routing Discipline rule (generator
+ * standards) and the infrastructure wrapper-routing pattern (§ A3), `lib/{config,
  * patterns}/` MUST instantiate this class rather than the raw CDK construct.
  */
 export class BucketDeployment extends CdkBucketDeployment {

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

@@ -1,7 +1,8 @@
+import { type S3VersioningExemption } from "@fjall/util/aws";
 import { Bucket, type BucketProps } from "aws-cdk-lib/aws-s3";
 import { type Construct } from "constructs";
 import { type BackupTier } from "../../../utils/backupTierMapping.js";
-export { SDK_PRE_EMPTY_TAG_KEY } from "@fjall/util/aws";
+export { S3_VERSIONING_EXEMPT_TAG_KEY, SDK_PRE_EMPTY_TAG_KEY } from "@fjall/util/aws";
 /**
  * Days a noncurrent object version is retained before lifecycle expiry.
  * The wrapper pairs this automatically when it enables versioning; constructs
@@ -59,6 +60,18 @@ export interface S3BucketProps extends BucketProps {
      * direct `new S3Bucket` construction needs to pass it.
      */
     appBackupTier?: BackupTier;
+    /**
+     * Why this bucket runs unversioned by design. Stamped as the
+     * `fjall:s3:versioning-exempt` tag only when versioning resolves off — a
+     * bucket that versions after all (an explicit `versioned: true`, or a tier
+     * that turns it on) has nothing to exempt — so posture lands the
+     * `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, the stack access-log bucket); an author may pass it for a
+     * disposable bucket of their own.
+     */
+    versioningExemption?: S3VersioningExemption;
     publicReadAccess?: boolean;
     websiteHosting?: WebsiteHostingConfig;
     /**