@fjall/components-infrastructure 37.0.0 → 39.0.0

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

@@ -1,6 +1,7 @@
 import { Construct } from "constructs";
 import { type IQueue } from "aws-cdk-lib/aws-sqs";
 import { type IGrantable, type Grant } from "aws-cdk-lib/aws-iam";
+import { type IKey } from "aws-cdk-lib/aws-kms";
 import type { ITopic } from "aws-cdk-lib/aws-sns";
 import { type RemovalPolicyString } from "./utils.js";
 import { type SqsAlarmThresholds } from "../monitoring/index.js";
@@ -57,8 +58,42 @@ export interface SQSQueueProps {
         maxReceiveCount?: number;
         queue?: IQueue;
     };
+    /**
+     * Server-side encryption at rest. Defaults to `"SSE_SQS"` — the SQS-owned
+     * managed key, which is free, needs no key policy and satisfies
+     * `sqs-queue-not-encrypted`.
+     *
+     * `"SSE_KMS"` encrypts with a customer-managed key: `masterKey` when you
+     * bring one, else the stack's shared {@link StackEncryptionKey} with the
+     * SQS senders admitted to it. It deliberately does NOT fall through to
+     * what CDK would do unaided — mint an implicit `AWS::KMS::Key` that is
+     * `DeletionPolicy: Retain` with no alias and no tags, admitting only the
+     * account root. Such a key is invisible to every Fjall teardown sweep
+     * (they find keys by the alias tag `CustomerManagedKey` stamps), so it
+     * outlives the stack as a charge nothing can attribute — and because its
+     * policy admits no service principal, no EventBridge rule, S3 notification
+     * or SNS subscription could send to the queue either.
+     *
+     * Unlike SNS, this does not follow the app's backup tier. `"SSE_SQS"` is
+     * real encryption at rest at every tier and costs nothing, and the tier's
+     * `customerManagedKeys` column enumerates the resources it owns (DynamoDB
+     * tables, SNS topics, Lambda environment, ECS Exec, log groups) — queues
+     * are not among them, so the opt-in here is the caller's.
+     */
     encryption?: "SSE_SQS" | "SSE_KMS" | "NONE";
-    kmsKeyArn?: string;
+    /**
+     * Bring your own KMS key. Implies `encryption: "SSE_KMS"` when no
+     * encryption is stated, and is REFUSED beside `"SSE_SQS"` or `"NONE"`
+     * rather than silently ignored.
+     *
+     * Every AWS service principal that sends to the queue needs `kms:Decrypt`
+     * + `kms:GenerateDataKey*` on this key's RESOURCE policy or its sends are
+     * dropped without an error — the key policy is the only place a service
+     * principal can be admitted. The stack key's own admission
+     * ({@link StackEncryptionKey.forSqsServicePublishers}) is not applied to a
+     * key you brought: it is yours to scope.
+     */
+    masterKey?: IKey;
     contentBasedDeduplication?: boolean;
     fifoThroughputLimit?: "perQueue" | "perMessageGroupId";
     deduplicationScope?: "queue" | "messageGroup";

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

@@ -2,8 +2,10 @@ import { Construct } from "constructs";
 import { CfnOutput, Duration } from "aws-cdk-lib";
 import { toPascalCase } from "../../../utils/capitaliseString.js";
 import { Queue, QueueEncryption, FifoThroughputLimit, DeduplicationScope } from "aws-cdk-lib/aws-sqs";
+import { StackEncryptionKey } from "../secrets/stackEncryptionKey.js";
 import { toRemovalPolicy } from "./utils.js";
 import { createSqsDlqAlarms } from "../monitoring/index.js";
+import { validateQueuePolicyQuota } from "./queuePolicyQuota.js";
 /**
  * AWS SQS service limits and defaults.
  * @see https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-quotas.html
@@ -55,6 +57,33 @@ function toEncryption(encryption) {
             return QueueEncryption.SQS_MANAGED;
     }
 }
+/**
+ * The queue's encryption mode and key, refusing the two combinations CDK
+ * would otherwise resolve quietly.
+ *
+ * A `masterKey` with no stated encryption means `"SSE_KMS"` — nobody hands a
+ * key to an unencrypted queue. A `masterKey` BESIDE `"SSE_SQS"` or `"NONE"`
+ * is a contradiction this wrapper used to warn about and then ignore; it
+ * throws now, because a queue that discards the key it was handed is
+ * indistinguishable at synth from one that honoured it, and the discrepancy
+ * only surfaces as an unreadable message months later.
+ */
+function resolveQueueEncryption(scope, props) {
+    if (props.masterKey !== undefined &&
+        props.encryption !== undefined &&
+        props.encryption !== "SSE_KMS") {
+        throw new Error(`'masterKey' is only meaningful with encryption: "SSE_KMS", and this ` +
+            `queue asks for "${props.encryption}". Set encryption: "SSE_KMS" to ` +
+            `encrypt with the key, or drop 'masterKey' to keep "${props.encryption}".`);
+    }
+    if (props.encryption !== "SSE_KMS" && props.masterKey === undefined) {
+        return { encryption: toEncryption(props.encryption) };
+    }
+    return {
+        encryption: QueueEncryption.KMS,
+        masterKey: props.masterKey ?? StackEncryptionKey.of(scope).forSqsServicePublishers()
+    };
+}
 function toFifoThroughputLimit(limit) {
     switch (limit) {
         case "perQueue":
@@ -84,6 +113,10 @@ export class SQSQueue extends Construct {
         this.id = id;
         // Sanitise id for CloudFormation output keys (must be alphanumeric)
         const outputName = toPascalCase(id);
+        // Resolved once and shared by the queue and its auto-created DLQ: one
+        // key for the pair, not one apiece. A dead-lettered message is the same
+        // message, so a second key would buy no isolation and double the charge.
+        const { encryption, masterKey } = resolveQueueEncryption(this, props);
         // SQS queues are transient work mediums: their contents (job messages,
         // failed-delivery copies) regenerate from a source of truth held elsewhere
         // (Postgres, the producing schedule/rule), so the wrapper defaults to
@@ -117,7 +150,8 @@ export class SQSQueue extends Construct {
                 this.dlq = new Queue(this, `${id}DeadLetterQueue`, {
                     queueName: dlqName,
                     fifo: isFifo,
-                    encryption: toEncryption(props.encryption),
+                    encryption,
+                    encryptionMasterKey: masterKey,
                     enforceSSL: true,
                     retentionPeriod: Duration.days(SQS_LIMITS.DEAD_LETTER_QUEUE.DEFAULT_RETENTION_DAYS),
                     removalPolicy: resolvedRemovalPolicy
@@ -156,7 +190,8 @@ export class SQSQueue extends Construct {
                 ? Duration.seconds(props.deliveryDelay)
                 : undefined,
             deadLetterQueue,
-            encryption: toEncryption(props.encryption),
+            encryption,
+            encryptionMasterKey: masterKey,
             enforceSSL: true,
             contentBasedDeduplication: isFifo
                 ? (props.contentBasedDeduplication ?? true)
@@ -169,6 +204,9 @@ export class SQSQueue extends Construct {
                 : undefined,
             removalPolicy: resolvedRemovalPolicy
         });
+        this.node.addValidation({
+            validate: () => [this.queue, this.dlq].flatMap((queue) => queue === undefined ? [] : validateQueuePolicyQuota(queue))
+        });
         new CfnOutput(this, `${outputName}QueueUrl`, {
             key: `${outputName}QueueUrl`,
             value: this.queue.queueUrl,

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

@@ -30,15 +30,16 @@ export interface SubscriptionProps {
     /**
      * Optional JSON payload that overrides the matched event detail before
      * delivery to the target (D5 — typed as `Record<string, unknown>`).
-     * Translates to `message` (SQS) or `event` (Lambda / EventBus / CodeBuild)
-     * on the underlying adapter. Values may be `EventField.*` tokens for
+     * Translates to `message` (SQS) or `event` (Lambda / CodeBuild) on the
+     * underlying adapter. Values may be `EventField.*` tokens for
      * payload-template substitution (e.g.
      * `EventField.fromPath("$.detail.repository.name")`). When omitted, the
      * full matched event is forwarded verbatim — the common pub/sub case.
      *
      * Not supported on ECS targets — CDK's `EcsTask` adapter ignores arbitrary
      * input; use container command/environment overrides on the task definition
-     * instead. Passing `payload` against an ECS target throws.
+     * instead. Nor on log-group targets, whose metric filters read the matched
+     * event untransformed. Passing `payload` against either throws.
      */
     payload?: Record<string, unknown>;
     /**

package/dist/lib/resources/aws/networking/vpc.js

@@ -1,4 +1,5 @@
 import { CfnOutput, Duration, RemovalPolicy, Stack } from "aws-cdk-lib";
+import { vpcCidrExportName } from "@fjall/util";
 import * as ec2 from "aws-cdk-lib/aws-ec2";
 import * as s3 from "aws-cdk-lib/aws-s3";
 import { LogGroup } from "../logging/logGroup.js";
@@ -30,14 +31,15 @@ export class Vpc extends ec2.Vpc {
         });
         this.hasNatGateways = natGateways !== 0;
         this.addInterfaceEndpoints(id, props, this.hasNatGateways);
-        // Export names are unique per account+region, so the id is load-bearing:
-        // without it a stack holding two VPCs emits the name twice and
-        // CloudFormation rejects the template. The `-vpc-cidr` suffix must stay
-        // last — the webapp finds a linked app's CIDR by ListExports + suffix
-        // filter (webapp app/.server/services/infrastructure/captureVpcCidr.ts).
+        // The export name is a contract owned by @fjall/util's stackExportNames
+        // module: the fjall.io webapp reads it by DescribeStacks on the app's
+        // Network stack and rebuilds this exact name — no ListExports, no suffix
+        // filter. The construct id is load-bearing because export names are
+        // unique per account+region: a stack holding two VPCs would otherwise
+        // emit one name twice and CloudFormation rejects the template.
         new CfnOutput(this, "VpcCidrBlock", {
             value: this.vpcCidrBlock,
-            exportName: `${Stack.of(this).stackName}${id}-vpc-cidr`
+            exportName: vpcCidrExportName(Stack.of(this).stackName, id)
         });
     }
     static gatewayEndpoints(props) {
@@ -184,6 +186,10 @@ export class Vpc extends ec2.Vpc {
                 bucketName: ResourceNaming.vpcFlowLogBucketName(id, Stack.of(scope).account),
                 encryption: s3.BucketEncryption.S3_MANAGED,
                 versioned: true,
+                // VPC delivers flow-log objects here continuously and the rules below
+                // age them out; a backup plan would copy a log stream that already has
+                // its own retention, so the bucket is versioned but not a source.
+                backupExemption: "log-delivery",
                 // Custom lifecycleRules bypass S3Bucket's automatic
                 // noncurrentVersionExpiration pairing — carried explicitly, or
                 // noncurrent versions accumulate forever. The no-retentionDays branch

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

@@ -23,11 +23,28 @@ import { CustomerManagedKey } from "./kms.js";
  * 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.
+ * [[forSnsServicePublishers]], SQS senders through
+ * [[forSqsServicePublishers]]. Each admission is added once per stack.
+ *
+ * A resource may also reach the key WITHOUT the tier, through [[of]]: an SQS
+ * queue declaring `encryption: "SSE_KMS"` encrypts with the stack key at
+ * every tier, because the alternative CDK offers is an implicit key that
+ * RETAINs with no alias and no tags and is therefore invisible to every
+ * teardown sweep. Queues are not a tier-owned resource — `SSE_SQS` is free
+ * encryption at rest and is what the tier column's absence of SQS means —
+ * so the opt-in is the caller's, not the tier's.
+ *
+ * PROBE SCOPE = DELETE SCOPE. The deploy-test teardown releases a retained
+ * stack key only after re-reading every resource class that can name it
+ * (`probeStackKeyReferrers`, deploy-tests/lib/kmsKeys.mts). A construct that
+ * starts encrypting a new kind of resource with this key extends that walk
+ * in the same change, or the teardown schedules deletion of a key something
+ * still needs.
  */
 export declare class StackEncryptionKey extends CustomerManagedKey {
     private logsAdmitted;
     private snsPublishersAdmitted;
+    private sqsPublishersAdmitted;
     private constructor();
     /** The stack's shared key, created on first use. */
     static of(scope: Construct): StackEncryptionKey;
@@ -57,4 +74,12 @@ export declare class StackEncryptionKey extends CustomerManagedKey {
      * immutable.
      */
     forSnsServicePublishers(): IKey;
+    /**
+     * The key, with the SQS-sending AWS services admitted to it
+     * ([[SQS_SERVICE_PUBLISHERS]]). Without the admission their sends to an
+     * encrypted queue fail silently: SQS drops the message rather than
+     * returning an error to the service, so the loss surfaces as a consumer
+     * that never runs.
+     */
+    forSqsServicePublishers(): IKey;
 }

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

@@ -20,6 +20,25 @@ const SNS_SERVICE_PUBLISHERS = [
     "cloudwatch.amazonaws.com",
     "s3.amazonaws.com"
 ];
+/**
+ * AWS services that send to an application's SQS queues on the app's behalf
+ * and therefore encrypt the message through the queue's key: EventBridge
+ * rule targets and rule dead-letter queues, S3 event notifications, and SNS
+ * topic subscriptions. Each needs `kms:Decrypt` + `kms:GenerateDataKey*` on
+ * the key's RESOURCE policy for the same reason the SNS set does — an
+ * identity policy cannot admit a service principal — and cannot be narrowed
+ * by `aws:SourceAccount` / `aws:SourceArn` for the same reason either: a
+ * send the key refuses is DROPPED, not rejected, so a condition that fails
+ * to match loses messages silently.
+ *
+ * CloudWatch is deliberately absent, and the difference from the SNS set is
+ * the point: an alarm action can target a topic but never a queue.
+ */
+const SQS_SERVICE_PUBLISHERS = [
+    "events.amazonaws.com",
+    "s3.amazonaws.com",
+    "sns.amazonaws.com"
+];
 /**
  * The one customer-managed KMS key an enterprise-tier stack encrypts its
  * tier-owned resources with: DynamoDB tables, SNS topics, Lambda environment
@@ -41,11 +60,28 @@ const SNS_SERVICE_PUBLISHERS = [
  * 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.
+ * [[forSnsServicePublishers]], SQS senders through
+ * [[forSqsServicePublishers]]. Each admission is added once per stack.
+ *
+ * A resource may also reach the key WITHOUT the tier, through [[of]]: an SQS
+ * queue declaring `encryption: "SSE_KMS"` encrypts with the stack key at
+ * every tier, because the alternative CDK offers is an implicit key that
+ * RETAINs with no alias and no tags and is therefore invisible to every
+ * teardown sweep. Queues are not a tier-owned resource — `SSE_SQS` is free
+ * encryption at rest and is what the tier column's absence of SQS means —
+ * so the opt-in is the caller's, not the tier's.
+ *
+ * PROBE SCOPE = DELETE SCOPE. The deploy-test teardown releases a retained
+ * stack key only after re-reading every resource class that can name it
+ * (`probeStackKeyReferrers`, deploy-tests/lib/kmsKeys.mts). A construct that
+ * starts encrypting a new kind of resource with this key extends that walk
+ * in the same change, or the teardown schedules deletion of a key something
+ * still needs.
  */
 export class StackEncryptionKey extends CustomerManagedKey {
     logsAdmitted = false;
     snsPublishersAdmitted = false;
+    sqsPublishersAdmitted = false;
     constructor(stack) {
         super(stack, STACK_ENCRYPTION_KEY_ID, {
             description: `Encrypts the enterprise-tier resources of ${stack.stackName} (DynamoDB tables, SNS topics, Lambda environment, ECS Exec sessions, log groups)`,
@@ -129,4 +165,23 @@ export class StackEncryptionKey extends CustomerManagedKey {
         }
         return this.key;
     }
+    /**
+     * The key, with the SQS-sending AWS services admitted to it
+     * ([[SQS_SERVICE_PUBLISHERS]]). Without the admission their sends to an
+     * encrypted queue fail silently: SQS drops the message rather than
+     * returning an error to the service, so the loss surfaces as a consumer
+     * that never runs.
+     */
+    forSqsServicePublishers() {
+        if (!this.sqsPublishersAdmitted) {
+            this.key.addToResourcePolicy(new PolicyStatement({
+                sid: "AllowSqsServicePublishers",
+                principals: SQS_SERVICE_PUBLISHERS.map((service) => new ServicePrincipal(service)),
+                actions: ["kms:Decrypt", "kms:GenerateDataKey*"],
+                resources: ["*"]
+            }));
+            this.sqsPublishersAdmitted = true;
+        }
+        return this.key;
+    }
 }

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

@@ -1,4 +1,4 @@
-import { type S3VersioningExemption } from "@fjall/util/aws";
+import { type S3BackupExemption, 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";
@@ -72,6 +72,26 @@ export interface S3BucketProps extends BucketProps {
      * disposable bucket of their own.
      */
     versioningExemption?: S3VersioningExemption;
+    /**
+     * Why this VERSIONED bucket is not a backup source. Stamped as the
+     * `fjall:s3:backup-exempt` tag only when versioning resolves on — an
+     * unversioned bucket is already outside every plan and has nothing to
+     * exempt.
+     *
+     * It is the counterpart of `versioningExemption`, which cannot express this
+     * case: that tag is stamped only when versioning is OFF. A log-delivery
+     * bucket must stay versioned and must stay out of the backup plan, and
+     * without a marker posture cannot tell it from a bucket that lost its tier
+     * by omission — so it raises a finding whose own auto-remediation cannot
+     * clear it.
+     *
+     * It beats a resolved tier, and the pair is not a contradiction: the tier
+     * says what the APP is, this says what THIS BUCKET is — the same
+     * narrower-statement-wins shape as an explicit `versioned` beating the
+     * tier's versioning column. A construct that owns a log-delivery bucket
+     * inside a tiered app passes both, and the bucket stays out of the plan.
+     */
+    backupExemption?: S3BackupExemption;
     publicReadAccess?: boolean;
     websiteHosting?: WebsiteHostingConfig;
     /**

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

@@ -1,9 +1,9 @@
-import { S3_VERSIONING_EXEMPT_TAG_KEY, SDK_PRE_EMPTY_TAG_KEY } from "@fjall/util/aws";
+import { S3_BACKUP_EXEMPT_TAG_KEY, S3_VERSIONING_EXEMPT_TAG_KEY, SDK_PRE_EMPTY_TAG_KEY } from "@fjall/util/aws";
 import { Annotations, CfnOutput, Duration, RemovalPolicy, Tags } from "aws-cdk-lib";
 import { BlockPublicAccess, Bucket, BucketEncryption } from "aws-cdk-lib/aws-s3";
 import { ArnPrincipal, Effect, PolicyStatement, StarPrincipal } from "aws-cdk-lib/aws-iam";
 import { RegionInfo } from "aws-cdk-lib/region-info";
-import { resolveEffectiveBackupTier, shouldAutoVersion } from "../../../utils/backupTierMapping.js";
+import { resolveEffectiveBackupTier, shouldAutoVersion, tagBackupTier } from "../../../utils/backupTierMapping.js";
 import { toPascalCase } from "../../../utils/capitaliseString.js";
 import { bucketWebsiteEndpointExportName, bucketWebsiteHostedZoneIdExportName } from "@fjall/util";
 import { envAwareRemovalPolicyDefault, toRemovalPolicy } from "../../../utils/removalPolicy.js";
@@ -26,10 +26,16 @@ export class S3Bucket extends Bucket {
     /** The tier the bucket runs under: `backupVaultTier`, else `appBackupTier`. */
     effectiveBackupTier;
     constructor(scope, id, props = {}) {
-        const { websiteHosting, backupVaultTier, appBackupTier, resourcePolicyStatements, aliasTargetName, appName, versioningExemption, ...cdkProps } = props;
+        const { websiteHosting, backupVaultTier, appBackupTier, resourcePolicyStatements, aliasTargetName, appName, versioningExemption, backupExemption, ...cdkProps } = props;
         const isPublic = props.publicReadAccess === true || websiteHosting !== undefined;
         const effectiveBackupTier = resolveEffectiveBackupTier(backupVaultTier, appBackupTier);
         const versioned = props.versioned ?? shouldAutoVersion(effectiveBackupTier);
+        // Read twice — to publish this bucket's object events, and to tag it into
+        // the plan. A bucket selected by one and not the other is the silent
+        // failure below, so both read one value rather than two copies.
+        const isBackupSource = versioned &&
+            backupExemption === undefined &&
+            effectiveBackupTier !== undefined;
         const removalPolicy = props.removalPolicy ?? toRemovalPolicy(envAwareRemovalPolicyDefault());
         // Mirrors the CDK Bucket's own resolution: an encryptionKey with no
         // explicit encryption infers KMS. DSSE is excluded deliberately — S3
@@ -37,6 +43,21 @@ export class S3Bucket extends Bucket {
         const kmsEncryption = props.encryption === BucketEncryption.KMS ||
             props.encryption === BucketEncryption.KMS_MANAGED ||
             (props.encryption === undefined && props.encryptionKey !== undefined);
+        // The one shape CDK answers by minting a key nobody asked for: a
+        // `DeletionPolicy: Retain` `AWS::KMS::Key` with no alias and no tags,
+        // beside a bucket that is usually DESTROY. Every Fjall teardown sweep
+        // finds keys by the alias tag `CustomerManagedKey` stamps, so that key
+        // is invisible to all of them and outlives the app forever. The
+        // patterns layer refuses it in plan vocabulary (`validateStorageProps`);
+        // this is the same refusal for anything constructing the bucket
+        // directly.
+        if (props.encryption === BucketEncryption.KMS &&
+            props.encryptionKey === undefined) {
+            throw new Error(`BucketEncryption.KMS needs an 'encryptionKey'. Pass the key to ` +
+                `encrypt with, or use BucketEncryption.KMS_MANAGED for AWS's own ` +
+                `key or BucketEncryption.S3_MANAGED for SSE-S3 — either of which ` +
+                `leaves no key behind when the bucket goes.`);
+        }
         super(scope, id, {
             ...cdkProps,
             enforceSSL: true,
@@ -62,6 +83,19 @@ export class S3Bucket extends Bucket {
                 : (props.blockPublicAccess ?? BlockPublicAccess.BLOCK_ALL),
             ...(props.bucketKeyEnabled === undefined &&
                 kmsEncryption && { bucketKeyEnabled: true }),
+            // AWS Backup builds an S3 bucket's point-in-time window from the object
+            // events S3 publishes to the default EventBridge bus, and the
+            // bucket-level setting that publishes them is off unless asked for.
+            // With it off AWS Backup's managed rule stays enabled and receives
+            // nothing: the snapshot rules keep succeeding, the plan keeps reporting
+            // healthy, and the window stops advancing past the first full backup.
+            // AWS documents that as silent — "no notification, alert, or backup job
+            // failure is generated by AWS Backup" — and says it cannot detect the
+            // setting being turned off, so nothing downstream recovers it either.
+            // An explicit prop still wins: turning it off chooses snapshots over a
+            // window, and the tier tag the plan selects on is untouched.
+            ...(props.eventBridgeEnabled === undefined &&
+                isBackupSource && { eventBridgeEnabled: true }),
             ...(websiteHosting && {
                 websiteIndexDocument: websiteHosting.indexDocument,
                 websiteErrorDocument: websiteHosting.errorDocument ?? "error.html"
@@ -115,6 +149,58 @@ export class S3Bucket extends Bucket {
         if (versioningExemption !== undefined && !versioned) {
             Tags.of(this).add(S3_VERSIONING_EXEMPT_TAG_KEY, versioningExemption);
         }
+        // AWS Backup requires versioning on an S3 source: an unversioned bucket
+        // carrying the tag fails every job it is selected for, for ever. So the
+        // enrolment follows versioning, not the tier — the standard tier does not
+        // version buckets and therefore does not enrol them, and its plan covers
+        // the database and volume types instead.
+        //
+        // A versioned bucket is therefore a source unless it says why not. The
+        // three arms below are exhaustive over a versioned bucket by design: it
+        // is enrolled, or it is exempt and says so in a tag posture can read, or
+        // it is neither and that is a mistake we refuse to make silently. The
+        // last arm is the one that matters: `tagBackupTier` no-ops on an
+        // undefined tier, so before it existed a construct that simply forgot to
+        // thread `appBackupTier` dropped its bucket out of every plan with
+        // nothing anywhere to say so.
+        if (versioned && backupExemption !== undefined) {
+            // `appBackupTier` beside an exemption is the ordinary case and says
+            // nothing contradictory: the tier says what the app is, the exemption
+            // says what this bucket is. `backupVaultTier` is different — it is a
+            // statement about THIS bucket, so the two are opposite answers to one
+            // question, and the resolution below (the exemption wins) is a guess at
+            // which the author meant. Silently guessing is the class this arm exists
+            // to end, so the guess is said out loud.
+            if (backupVaultTier !== undefined) {
+                Annotations.of(this).addWarningV2("@fjall/components-infrastructure:s3:backupExemptionBeatsBucketTier", `This bucket declares both \`backupVaultTier: ` +
+                    `"${backupVaultTier}"\` and \`backupExemption: ` +
+                    `"${backupExemption}"\`, which say opposite things about the ` +
+                    `same bucket. The exemption wins: the bucket is tagged ` +
+                    `${S3_BACKUP_EXEMPT_TAG_KEY} and enrolled in no backup plan, and ` +
+                    `the tier is not applied. Drop whichever is wrong — an ` +
+                    `\`appBackupTier\` beside an exemption is not this case.`);
+            }
+            Tags.of(this).add(S3_BACKUP_EXEMPT_TAG_KEY, backupExemption);
+        }
+        else if (isBackupSource) {
+            tagBackupTier(this, effectiveBackupTier);
+        }
+        else if (versioned) {
+            Annotations.of(this).addWarningV2("@fjall/components-infrastructure:s3:backupTierUnresolved", `This bucket is versioned but carries no backup tier, so it is in no ` +
+                `backup plan. Pass \`appBackupTier\` (the StorageFactory and ` +
+                `BuildkiteFactory paths fill it from the App) to enrol it, or pass ` +
+                `\`backupExemption\` to record that it is not a backup source.`);
+        }
+        else if (effectiveBackupTier !== undefined &&
+            shouldAutoVersion(effectiveBackupTier) &&
+            versioningExemption === undefined) {
+            // The carve-out is the cure this message itself names: a bucket that
+            // already recorded why it runs unversioned has answered the question.
+            Annotations.of(this).addWarningV2("@fjall/components-infrastructure:s3:backupTierNotEnrolled", `versioned: false leaves this bucket out of the ` +
+                `${effectiveBackupTier} backup plan — AWS Backup cannot protect an ` +
+                `unversioned bucket. Drop the override to restore the tier's ` +
+                `versioning, or keep it and record why with versioningExemption.`);
+        }
         if (websiteHosting) {
             if (appName === undefined) {
                 // Refusing beats falling back to a bucket-only export name: the

package/dist/lib/utils/backupTierMapping.d.ts

@@ -1,3 +1,4 @@
+import { type IConstruct } from "constructs";
 import { BACKUP_TIERS, BACKUP_TIER_DEFAULTS, BACKUP_TIER_TAG_KEY, BACKUP_TIER_TAG_MAP, type BackupTier, type BackupTierDefaults, tierDefault } from "@fjall/util";
 /**
  * The application backup tier vocabulary, its defaults table, the DR tag key
@@ -7,8 +8,8 @@ import { BACKUP_TIERS, BACKUP_TIER_DEFAULTS, BACKUP_TIER_TAG_KEY, BACKUP_TIER_TA
  * the CLI's synth expectations and the webapp's posture rules (which read the
  * tag back from discovered resources), so every system derives from one
  * declaration. Re-exported here so construct code keeps one import path for
- * tier concerns: `App.applyBackupTier()` (app-level tag), `StandardTagsAspect`
- * (per-resource tag) and `BackupPlan` (selection key) all read the same pair.
+ * tier concerns: `tagBackupTier()` (the per-resource tag) and `BackupPlan`
+ * (the selection key) read the same pair.
  */
 export type { BackupTier, BackupTierDefaults };
 export { BACKUP_TIERS, BACKUP_TIER_DEFAULTS, BACKUP_TIER_TAG_KEY, BACKUP_TIER_TAG_MAP, tierDefault };
@@ -21,3 +22,23 @@ export { BACKUP_TIERS, BACKUP_TIER_DEFAULTS, BACKUP_TIER_TAG_KEY, BACKUP_TIER_TA
 export declare function resolveEffectiveBackupTier(resourceTier: BackupTier | undefined, appTier: BackupTier | undefined): BackupTier | undefined;
 /** Tiers whose S3 buckets version by default. */
 export declare function shouldAutoVersion(tier: BackupTier | undefined): boolean;
+/**
+ * Stamp the disaster-recovery tier tag that enrols a resource in the matching
+ * AWS Backup plan. `BackupSelection` selects on this tag alone — it carries no
+ * resource-type filter — so where this is called IS the selection scope, and
+ * only the five backup-eligible resources call it: the RDS primary instance,
+ * the Aurora cluster, the DynamoDB table, the ClickHouse data volume and a
+ * versioned bucket.
+ *
+ * Pass the construct that must carry the tag. An L2 whose only taggable member
+ * is the resource itself (a bucket, a volume, a table) may be passed directly;
+ * where the L2 owns taggable siblings the L1 is required, because a tag on the
+ * L2 propagates to every child — an Aurora cluster's member instances and an
+ * RDS instance's subnet group are the two that matter, and AWS Backup protects
+ * the Aurora cluster, never its members.
+ *
+ * Called at construction, never from an aspect: `Tags.of(...)` inside an
+ * aspect's `visit()` is an aspect adding an aspect, which aws-cdk-lib drops
+ * silently under `aspectStabilization: false`.
+ */
+export declare function tagBackupTier(resource: IConstruct | undefined, tier: BackupTier | undefined): void;

package/dist/lib/utils/backupTierMapping.js

@@ -1,3 +1,4 @@
+import { Tags } from "aws-cdk-lib";
 import { BACKUP_TIERS, BACKUP_TIER_DEFAULTS, BACKUP_TIER_TAG_KEY, BACKUP_TIER_TAG_MAP, tierDefault } from "@fjall/util";
 export { BACKUP_TIERS, BACKUP_TIER_DEFAULTS, BACKUP_TIER_TAG_KEY, BACKUP_TIER_TAG_MAP, tierDefault };
 /**
@@ -13,3 +14,27 @@ export function resolveEffectiveBackupTier(resourceTier, appTier) {
 export function shouldAutoVersion(tier) {
     return tierDefault(tier, "s3Versioned");
 }
+/**
+ * Stamp the disaster-recovery tier tag that enrols a resource in the matching
+ * AWS Backup plan. `BackupSelection` selects on this tag alone — it carries no
+ * resource-type filter — so where this is called IS the selection scope, and
+ * only the five backup-eligible resources call it: the RDS primary instance,
+ * the Aurora cluster, the DynamoDB table, the ClickHouse data volume and a
+ * versioned bucket.
+ *
+ * Pass the construct that must carry the tag. An L2 whose only taggable member
+ * is the resource itself (a bucket, a volume, a table) may be passed directly;
+ * where the L2 owns taggable siblings the L1 is required, because a tag on the
+ * L2 propagates to every child — an Aurora cluster's member instances and an
+ * RDS instance's subnet group are the two that matter, and AWS Backup protects
+ * the Aurora cluster, never its members.
+ *
+ * Called at construction, never from an aspect: `Tags.of(...)` inside an
+ * aspect's `visit()` is an aspect adding an aspect, which aws-cdk-lib drops
+ * silently under `aspectStabilization: false`.
+ */
+export function tagBackupTier(resource, tier) {
+    if (resource === undefined || tier === undefined)
+        return;
+    Tags.of(resource).add(BACKUP_TIER_TAG_KEY, BACKUP_TIER_TAG_MAP[tier]);
+}

package/dist/lib/utils/cdkContext.d.ts

@@ -1,5 +1,6 @@
 import type { Node } from "constructs";
 import { ACCOUNT_TRAIL_STATES, type AccountTrailState } from "@fjall/util/config";
+import { type BackupVaultVerdict } from "@fjall/util";
 export declare const CDK_CONTEXT_KEYS: {
     readonly ORG_ID: "orgId";
     readonly ROOT_ID: "rootId";
@@ -7,6 +8,7 @@ export declare const CDK_CONTEXT_KEYS: {
     readonly ORG_CONFIG: "orgConfig";
     readonly ACCOUNT_TRAIL_STATE: "fjallAccountTrailState";
     readonly DEV_OU_ID: "fjallDevOuId";
+    readonly BACKUP_VAULT: "fjallBackupVault";
 };
 export { ACCOUNT_TRAIL_STATES, type AccountTrailState };
 /**
@@ -16,6 +18,18 @@ export { ACCOUNT_TRAIL_STATES, type AccountTrailState };
  * mid-decommission must fail the synth, not silently re-create a trail.
  */
 export declare function resolveAccountTrailState(node: Node): AccountTrailState;
+/**
+ * Reads the backup-vault ownership verdict the deploy engine injects before
+ * synth (`-c fjallBackupVault=<json>`; the wire contract is
+ * `BackupVaultVerdictSchema` in @fjall/util). Unset, or the `-c key=`
+ * empty-string boundary, is `absent` — the create template, which is what a
+ * synth with no engine in front of it (a local `cdk synth`, a construct test)
+ * has always produced. Malformed context is a LOUD synth error, never a
+ * default: a mis-read verdict would either re-CREATE a colliding fixed-name
+ * vault or declare a re-owned vault against the wrong key, and
+ * `EncryptionKeyArn` is create-only, so that second mistake replaces the vault.
+ */
+export declare function readBackupVaultVerdict(node: Node): BackupVaultVerdict;
 export declare const DEFAULT_ORG_ID: "default";
 export declare function resolveOrgId(node: Node, fallback: string): string;
 export declare function resolveOrgId(node: Node): string | undefined;

package/dist/lib/utils/cdkContext.js

@@ -1,11 +1,13 @@
 import { ACCOUNT_TRAIL_STATES } from "@fjall/util/config";
+import { BACKUP_VAULT_CONTEXT_KEY, BackupVaultVerdictSchema } from "@fjall/util";
 export const CDK_CONTEXT_KEYS = {
     ORG_ID: "orgId",
     ROOT_ID: "rootId",
     MANAGEMENT_ACCOUNT_ID: "managementAccountId",
     ORG_CONFIG: "orgConfig",
     ACCOUNT_TRAIL_STATE: "fjallAccountTrailState",
-    DEV_OU_ID: "fjallDevOuId"
+    DEV_OU_ID: "fjallDevOuId",
+    BACKUP_VAULT: BACKUP_VAULT_CONTEXT_KEY
 };
 export { ACCOUNT_TRAIL_STATES };
 /**
@@ -25,6 +27,41 @@ export function resolveAccountTrailState(node) {
     }
     throw new Error(`${CDK_CONTEXT_KEYS.ACCOUNT_TRAIL_STATE} must be one of ${ACCOUNT_TRAIL_STATES.join(", ")}; received "${String(raw)}"`);
 }
+const ABSENT_BACKUP_VAULT = { state: "absent" };
+/**
+ * Reads the backup-vault ownership verdict the deploy engine injects before
+ * synth (`-c fjallBackupVault=<json>`; the wire contract is
+ * `BackupVaultVerdictSchema` in @fjall/util). Unset, or the `-c key=`
+ * empty-string boundary, is `absent` — the create template, which is what a
+ * synth with no engine in front of it (a local `cdk synth`, a construct test)
+ * has always produced. Malformed context is a LOUD synth error, never a
+ * default: a mis-read verdict would either re-CREATE a colliding fixed-name
+ * vault or declare a re-owned vault against the wrong key, and
+ * `EncryptionKeyArn` is create-only, so that second mistake replaces the vault.
+ */
+export function readBackupVaultVerdict(node) {
+    const raw = node.tryGetContext(CDK_CONTEXT_KEYS.BACKUP_VAULT);
+    if (raw === undefined || raw === "") {
+        return ABSENT_BACKUP_VAULT;
+    }
+    let value = raw;
+    if (typeof raw === "string") {
+        // `-c key=value` always arrives as a string; tests may set the object form.
+        try {
+            value = JSON.parse(raw);
+        }
+        catch (error) {
+            throw new Error(`${CDK_CONTEXT_KEYS.BACKUP_VAULT} context is not valid JSON: ` +
+                `${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+    }
+    const parsed = BackupVaultVerdictSchema.safeParse(value);
+    if (!parsed.success) {
+        throw new Error(`${CDK_CONTEXT_KEYS.BACKUP_VAULT} context is malformed — refusing to ` +
+            `synth a backup vault whose ownership is unknown: ${parsed.error.message}`);
+    }
+    return parsed.data;
+}
 export const DEFAULT_ORG_ID = "default";
 export function resolveOrgId(node, fallback) {
     const raw = node.tryGetContext(CDK_CONTEXT_KEYS.ORG_ID);