@fjall/components-infrastructure 38.0.0 → 39.0.0

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

@@ -2,6 +2,7 @@ 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";
@@ -56,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":
@@ -85,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
@@ -118,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
@@ -157,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)

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

@@ -1,35 +1,38 @@
 import type { Construct } from "constructs";
 /**
- * Qualify a CloudFormation export name with the stack that emits it.
+ * Construct-side adapter for the stack-qualified export names whose contract
+ * is `@fjall/util`'s `stackExportNames` module.
  *
- * Export names are unique per account per region, so a name built only from a
- * construct id or a cluster name is shared by every app that happens to use
- * the same id — and the ids inside a pattern are literals the app author never
- * chooses. Two apps then collide, and the second one fails at CloudFormation
- * execution ("Export with name X is already exported by stack Y") after its
- * first resources exist, so it rolls back rather than refusing up front.
+ * Export names are unique per account per region, so a name built only from
+ * a construct id or a cluster name is shared by every app that happens to use
+ * the same id — and the ids inside a pattern are literals the app author
+ * never chooses. Two apps then collide, and the second one fails at
+ * CloudFormation execution ("Export with name X is already exported by stack
+ * Y") after its first resources exist, so it rolls back rather than refusing
+ * up front. Stack names are already unique per account+region and Fjall
+ * derives them from the app name, so qualifying with the stack makes the
+ * export unique AND puts the app name in it.
  *
- * Stack names are already unique per account+region (CloudFormation enforces
- * it) and Fjall derives them from the app name, so prefixing with the stack
- * name makes the export globally unique AND puts the app name in it.
+ * `@fjall/util` owns the composition — `stackScopedExportName` and the
+ * builders on top of it (`deployableServiceExportName`,
+ * `deployableClusterExportName`, `clusterArnExportName`,
+ * `vpcCidrExportName`) — so the runtime consumers that read an export back
+ * (deploy-core's `EcsServiceResolver`, the fjall.io webapp's VPC CIDR
+ * capture) rebuild the exact name through the same function the construct
+ * emitted it with. This helper only supplies the stack: a construct passes
+ * itself and the suffix is qualified with the stack it lives in. An export a
+ * consumer rebuilds by whole name goes through its specific builder with
+ * `Stack.of(this).stackName`, never through this generic form.
  *
- * The suffix must stay last. Consumers match these by suffix and by app-name
- * token, never by whole string — `EcsServiceResolver` filters on
- * `endsWith("deployableservice")` (deploy-core
- * services/infrastructure/EcsServiceResolver.ts) and the webapp finds a linked
- * app's CIDR by `ListExports` + a `-vpc-cidr` suffix filter
- * (webapp app/.server/services/infrastructure/captureVpcCidr.ts). Prefixing is
- * transparent to both; changing the tail is not.
- *
- * NOT for exports a consumer reconstructs by whole name. Those are contracts
- * with their own vocabulary module and must keep their exact spelling:
- * `getDomainExportNames` (@fjall/util), `EXPORT_NAMES`
- * (patterns/aws/targets/targetResolution.ts), `SHARED_ALARM_TOPIC_EXPORT_NAME`,
- * the CloudTrail output keys, and `${toPascalCase(appName)}EcrRepositoryName`
- * (read by `resolveEcrRepositoryName` in the CLI). Account-level singletons
- * (`AccountId`, `Environment`, `OrganisationId`, `FjallAuditRoleArn`, …) also
- * keep their bare names: exactly one is meant to exist, so a collision there
- * correctly reports a duplicate deployment.
+ * NOT for exports a consumer reconstructs from its own vocabulary module.
+ * Those keep their exact spelling: `getDomainExportNames` (@fjall/util),
+ * `EXPORT_NAMES` (patterns/aws/targets/targetResolution.ts),
+ * `SHARED_ALARM_TOPIC_EXPORT_NAME`, the CloudTrail output keys, and
+ * `${toPascalCase(appName)}EcrRepositoryName` (read by
+ * `resolveEcrRepositoryName` in the CLI). Account-level singletons
+ * (`AccountId`, `Environment`, `OrganisationId`, `FjallAuditRoleArn`, …)
+ * also keep their bare names: exactly one is meant to exist, so a collision
+ * there correctly reports a duplicate deployment.
  */
 export declare function stackScopedExportName(scope: Construct, suffix: string): string;
 /**

package/dist/lib/utils/exportNaming.js

@@ -1,38 +1,42 @@
 import { Stack } from "aws-cdk-lib";
+import { stackScopedExportName as qualifyWithStack } from "@fjall/util";
 /**
- * Qualify a CloudFormation export name with the stack that emits it.
+ * Construct-side adapter for the stack-qualified export names whose contract
+ * is `@fjall/util`'s `stackExportNames` module.
  *
- * Export names are unique per account per region, so a name built only from a
- * construct id or a cluster name is shared by every app that happens to use
- * the same id — and the ids inside a pattern are literals the app author never
- * chooses. Two apps then collide, and the second one fails at CloudFormation
- * execution ("Export with name X is already exported by stack Y") after its
- * first resources exist, so it rolls back rather than refusing up front.
+ * Export names are unique per account per region, so a name built only from
+ * a construct id or a cluster name is shared by every app that happens to use
+ * the same id — and the ids inside a pattern are literals the app author
+ * never chooses. Two apps then collide, and the second one fails at
+ * CloudFormation execution ("Export with name X is already exported by stack
+ * Y") after its first resources exist, so it rolls back rather than refusing
+ * up front. Stack names are already unique per account+region and Fjall
+ * derives them from the app name, so qualifying with the stack makes the
+ * export unique AND puts the app name in it.
  *
- * Stack names are already unique per account+region (CloudFormation enforces
- * it) and Fjall derives them from the app name, so prefixing with the stack
- * name makes the export globally unique AND puts the app name in it.
+ * `@fjall/util` owns the composition — `stackScopedExportName` and the
+ * builders on top of it (`deployableServiceExportName`,
+ * `deployableClusterExportName`, `clusterArnExportName`,
+ * `vpcCidrExportName`) — so the runtime consumers that read an export back
+ * (deploy-core's `EcsServiceResolver`, the fjall.io webapp's VPC CIDR
+ * capture) rebuild the exact name through the same function the construct
+ * emitted it with. This helper only supplies the stack: a construct passes
+ * itself and the suffix is qualified with the stack it lives in. An export a
+ * consumer rebuilds by whole name goes through its specific builder with
+ * `Stack.of(this).stackName`, never through this generic form.
  *
- * The suffix must stay last. Consumers match these by suffix and by app-name
- * token, never by whole string — `EcsServiceResolver` filters on
- * `endsWith("deployableservice")` (deploy-core
- * services/infrastructure/EcsServiceResolver.ts) and the webapp finds a linked
- * app's CIDR by `ListExports` + a `-vpc-cidr` suffix filter
- * (webapp app/.server/services/infrastructure/captureVpcCidr.ts). Prefixing is
- * transparent to both; changing the tail is not.
- *
- * NOT for exports a consumer reconstructs by whole name. Those are contracts
- * with their own vocabulary module and must keep their exact spelling:
- * `getDomainExportNames` (@fjall/util), `EXPORT_NAMES`
- * (patterns/aws/targets/targetResolution.ts), `SHARED_ALARM_TOPIC_EXPORT_NAME`,
- * the CloudTrail output keys, and `${toPascalCase(appName)}EcrRepositoryName`
- * (read by `resolveEcrRepositoryName` in the CLI). Account-level singletons
- * (`AccountId`, `Environment`, `OrganisationId`, `FjallAuditRoleArn`, …) also
- * keep their bare names: exactly one is meant to exist, so a collision there
- * correctly reports a duplicate deployment.
+ * NOT for exports a consumer reconstructs from its own vocabulary module.
+ * Those keep their exact spelling: `getDomainExportNames` (@fjall/util),
+ * `EXPORT_NAMES` (patterns/aws/targets/targetResolution.ts),
+ * `SHARED_ALARM_TOPIC_EXPORT_NAME`, the CloudTrail output keys, and
+ * `${toPascalCase(appName)}EcrRepositoryName` (read by
+ * `resolveEcrRepositoryName` in the CLI). Account-level singletons
+ * (`AccountId`, `Environment`, `OrganisationId`, `FjallAuditRoleArn`, …)
+ * also keep their bare names: exactly one is meant to exist, so a collision
+ * there correctly reports a duplicate deployment.
  */
 export function stackScopedExportName(scope, suffix) {
-    return `${Stack.of(scope).stackName}${suffix}`;
+    return qualifyWithStack(Stack.of(scope).stackName, suffix);
 }
 /**
  * Export name for the account's IPAM private default scope.