@fjall/components-infrastructure 36.0.0 → 38.0.0

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

@@ -0,0 +1,190 @@
+import { CfnResource, Stack } from "aws-cdk-lib";
+import { CfnEventBus, CfnRule } from "aws-cdk-lib/aws-events";
+import { CfnQueue, QueuePolicy } from "aws-cdk-lib/aws-sqs";
+/**
+ * SQS's queue-policy quotas.
+ * @see https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/quotas-policies.html
+ */
+export const QUEUE_POLICY_LIMITS = {
+    MAX_BYTES: 8192,
+    MAX_STATEMENTS: 20
+};
+/** CDK's own ARN estimate, and the context key that tunes it, for a reference this module cannot size. */
+const ARN_SIZE_ESTIMATE_CONTEXT_KEY = "@aws-cdk/aws-iam.arnSizeEstimate";
+const DEFAULT_ARN_SIZE_ESTIMATE = 150;
+const PSEUDO_PARAMETER_MAX_LENGTH = {
+    "AWS::AccountId": 12,
+    "AWS::Partition": 10,
+    "AWS::Region": 16,
+    "AWS::StackName": 128,
+    "AWS::URLSuffix": 16
+};
+const RULE_NAME_MAX_LENGTH = 64;
+const QUEUE_NAME_MAX_LENGTH = 80;
+const EVENT_BUS_NAME_MAX_LENGTH = 256;
+/** `arn:<partition>:<service>:<region>:<account>:` at its longest, without the service. */
+const ARN_PREFIX_MAX_LENGTH = "arn:::::".length +
+    PSEUDO_PARAMETER_MAX_LENGTH["AWS::Partition"] +
+    PSEUDO_PARAMETER_MAX_LENGTH["AWS::Region"] +
+    PSEUDO_PARAMETER_MAX_LENGTH["AWS::AccountId"];
+/**
+ * Refuse, at synthesis, a queue policy SQS would refuse at deploy.
+ *
+ * Every grant to a queue — an EventBridge rule, an SNS subscription, an S3
+ * notification — lands in the queue's one policy, and SQS rejects the whole
+ * policy past its byte or statement quota. CloudFormation only finds out
+ * mid-deploy and rolls the stack back, so the check runs where the growth is
+ * authored.
+ *
+ * The byte count is an upper bound: an ARN CloudFormation has not minted yet
+ * is sized at the longest its partition, region, account and name can be, so
+ * the refusal can arrive a few grants before SQS's would. A reference whose
+ * shape is not known here takes CDK's ARN estimate, tunable through the
+ * `@aws-cdk/aws-iam.arnSizeEstimate` context key.
+ */
+export function validateQueuePolicyQuota(queue) {
+    const policy = queue.node.children.find((child) => child instanceof QueuePolicy);
+    if (policy === undefined)
+        return [];
+    const stack = Stack.of(queue);
+    const document = stack.resolve(policy.document);
+    const statements = isRecord(document) ? document.Statement : undefined;
+    const statementCount = Array.isArray(statements) ? statements.length : 0;
+    const estimator = new PolicySizeEstimator(stack);
+    const bytes = estimator.jsonLength(document);
+    const errors = [];
+    if (statementCount > QUEUE_POLICY_LIMITS.MAX_STATEMENTS) {
+        errors.push(`The resource policy on queue ${queue.node.path} has ${statementCount} statements; SQS allows at most ${QUEUE_POLICY_LIMITS.MAX_STATEMENTS}. Split the grants across queues.`);
+    }
+    if (bytes > QUEUE_POLICY_LIMITS.MAX_BYTES) {
+        const unsized = estimator.unsizedReferences === 0
+            ? ""
+            : ` ${estimator.unsizedReferences} reference(s) this check cannot size are counted at ${estimator.unsizedReferenceBytes} bytes each; if those ARNs are shorter, lower the "${ARN_SIZE_ESTIMATE_CONTEXT_KEY}" context.`;
+        errors.push(`The resource policy on queue ${queue.node.path} may reach ${bytes} bytes; SQS refuses a policy over ${QUEUE_POLICY_LIMITS.MAX_BYTES}. Every EventBridge rule, SNS topic or other source granted this queue adds to the one policy — split them across queues.${unsized}`);
+    }
+    return errors;
+}
+class PolicySizeEstimator {
+    #stack;
+    #resources;
+    #unsizedReferences = 0;
+    constructor(stack) {
+        this.#stack = stack;
+    }
+    /** How many references this estimator has counted at the ARN estimate. */
+    get unsizedReferences() {
+        return this.#unsizedReferences;
+    }
+    get unsizedReferenceBytes() {
+        const configured = this.#stack.node.tryGetContext(ARN_SIZE_ESTIMATE_CONTEXT_KEY);
+        return typeof configured === "number" && configured > 0
+            ? configured
+            : DEFAULT_ARN_SIZE_ESTIMATE;
+    }
+    /** Bytes of `value` serialised as compact JSON, with each intrinsic sized as the string it deploys as. */
+    jsonLength(value) {
+        if (Array.isArray(value)) {
+            return (2 +
+                Math.max(value.length - 1, 0) +
+                value.reduce((sum, item) => sum + this.jsonLength(item), 0));
+        }
+        if (isRecord(value)) {
+            const intrinsic = this.#intrinsicLength(value);
+            if (intrinsic !== undefined)
+                return intrinsic + 2;
+            const entries = Object.entries(value);
+            return (2 +
+                Math.max(entries.length - 1, 0) +
+                entries.reduce((sum, [key, item]) => sum + utf8Length(JSON.stringify(key)) + 1 + this.jsonLength(item), 0));
+        }
+        return utf8Length(JSON.stringify(value) ?? "null");
+    }
+    #intrinsicLength(value) {
+        const keys = Object.keys(value);
+        if (keys.length !== 1)
+            return undefined;
+        const [name] = keys;
+        const argument = value[name];
+        if (name === "Ref" && typeof argument === "string") {
+            return Object.hasOwn(PSEUDO_PARAMETER_MAX_LENGTH, argument)
+                ? PSEUDO_PARAMETER_MAX_LENGTH[argument]
+                : this.#refLength(argument);
+        }
+        if (name === "Fn::Join" && Array.isArray(argument)) {
+            const [separator, parts] = argument;
+            if (typeof separator === "string" && Array.isArray(parts)) {
+                return (separator.length * Math.max(parts.length - 1, 0) +
+                    parts.reduce((sum, part) => sum + this.#stringLength(part), 0));
+            }
+        }
+        if (name === "Fn::GetAtt" && Array.isArray(argument)) {
+            const [logicalId, attribute] = argument;
+            if (typeof logicalId === "string" && attribute === "Arn") {
+                return this.#arnLength(logicalId);
+            }
+        }
+        return name.startsWith("Fn::") ? this.#unknownLength() : undefined;
+    }
+    #stringLength(value) {
+        if (typeof value === "string")
+            return utf8Length(value);
+        const intrinsic = isRecord(value)
+            ? this.#intrinsicLength(value)
+            : undefined;
+        return intrinsic ?? this.#unknownLength();
+    }
+    #arnLength(logicalId) {
+        const resource = this.#resourceByLogicalId(logicalId);
+        if (resource instanceof CfnRule) {
+            const busName = resource.eventBusName;
+            const bus = busName === undefined
+                ? 0
+                : this.#stringLength(this.#stack.resolve(busName)) + 1;
+            return (ARN_PREFIX_MAX_LENGTH +
+                "events".length +
+                "rule/".length +
+                bus +
+                this.#nameLength(resource.name, RULE_NAME_MAX_LENGTH));
+        }
+        if (resource instanceof CfnQueue) {
+            return (ARN_PREFIX_MAX_LENGTH +
+                "sqs".length +
+                this.#nameLength(resource.queueName, QUEUE_NAME_MAX_LENGTH));
+        }
+        return this.#unknownLength();
+    }
+    /** `Ref` on an event bus returns its name; any other resource's `Ref` is not sized here. */
+    #refLength(logicalId) {
+        const resource = this.#resourceByLogicalId(logicalId);
+        return resource instanceof CfnEventBus
+            ? this.#nameLength(resource.name, EVENT_BUS_NAME_MAX_LENGTH)
+            : this.#unknownLength();
+    }
+    /** A name as deployed, or `bound` when CloudFormation will generate it or it resolves to an intrinsic. */
+    #nameLength(value, bound) {
+        if (value === undefined)
+            return bound;
+        const resolved = this.#stack.resolve(value);
+        return typeof resolved === "string" ? utf8Length(resolved) : bound;
+    }
+    #resourceByLogicalId(logicalId) {
+        if (this.#resources === undefined) {
+            const stack = this.#stack;
+            this.#resources = new Map(stack.node
+                .findAll()
+                .filter((construct) => construct instanceof CfnResource && Stack.of(construct) === stack)
+                .map((resource) => [stack.resolve(resource.logicalId), resource]));
+        }
+        return this.#resources.get(logicalId);
+    }
+    #unknownLength() {
+        this.#unsizedReferences++;
+        return this.unsizedReferenceBytes;
+    }
+}
+function utf8Length(value) {
+    return Buffer.byteLength(value, "utf8");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

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

@@ -31,14 +31,14 @@ export interface ScheduleProps {
     /**
      * JSON payload sent to the target on every tick (D5 — typed as
      * `Record<string, unknown>`). Translates to `message` (SQS) or `event`
-     * (Lambda / EventBus) on the underlying adapter. Values may be
-     * `EventField.*` tokens for payload-template substitution.
-     * `scheduledAt: EventField.time` is auto-injected unless the caller
-     * already provides a `scheduledAt` key.
+     * (Lambda) on the underlying adapter. Values may be `EventField.*` tokens
+     * for payload-template substitution. `scheduledAt: EventField.time` is
+     * auto-injected unless the caller already provides a `scheduledAt` key.
      *
      * 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 event-bus targets, which forward the scheduled event
+     * unchanged. Passing `payload` against either throws.
      *
      * @example
      * app.addSchedule("MetricsCollection", {

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

@@ -4,6 +4,7 @@ import { toPascalCase } from "../../../utils/capitaliseString.js";
 import { Queue, QueueEncryption, FifoThroughputLimit, DeduplicationScope } from "aws-cdk-lib/aws-sqs";
 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
@@ -169,6 +170,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/secrets/kms.d.ts

@@ -10,6 +10,14 @@ export type KeyProtectionScope = (typeof KEY_PROTECTION_SCOPES)[number];
  * forgotten (tier-aware alert policy design §8 K4, `KMS_KEY_ORPHAN`).
  */
 export { KMS_RETENTION_TAG_KEY } from "@fjall/util/aws";
+/**
+ * Stamped beside the retention marker, valued with the alias name as `kms
+ * list-aliases` reports it. The alias resource goes with the stack and
+ * CloudFormation tags nothing on a KMS key, so after a stack delete this tag
+ * is the only thing that still says which stack's key a retained key was —
+ * the deploy-test teardown releases retained stack keys by it.
+ */
+export { KMS_ALIAS_TAG_KEY } from "@fjall/util/aws";
 interface CustomerManagedKeyProps {
     description?: string;
     aliasName?: string;

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

@@ -1,4 +1,4 @@
-import { KMS_RETENTION_TAG_KEY } from "@fjall/util/aws";
+import { KMS_ALIAS_TAG_KEY, KMS_RETENTION_TAG_KEY } from "@fjall/util/aws";
 import { CfnOutput, Duration, RemovalPolicy, Tags } from "aws-cdk-lib";
 import { Alias, Key } from "aws-cdk-lib/aws-kms";
 import { Construct } from "constructs";
@@ -17,6 +17,14 @@ export const KEY_PROTECTION_SCOPES = [
  * forgotten (tier-aware alert policy design §8 K4, `KMS_KEY_ORPHAN`).
  */
 export { KMS_RETENTION_TAG_KEY } from "@fjall/util/aws";
+/**
+ * Stamped beside the retention marker, valued with the alias name as `kms
+ * list-aliases` reports it. The alias resource goes with the stack and
+ * CloudFormation tags nothing on a KMS key, so after a stack delete this tag
+ * is the only thing that still says which stack's key a retained key was —
+ * the deploy-test teardown releases retained stack keys by it.
+ */
+export { KMS_ALIAS_TAG_KEY } from "@fjall/util/aws";
 /**
  * How long a scheduled-for-deletion key stays recoverable.
  *
@@ -52,8 +60,10 @@ export class CustomerManagedKey extends Construct {
                 ? PENDING_DELETION_WINDOW
                 : undefined
         });
+        const aliasName = props.aliasName || ResourceNaming.defaultKeyAlias(id);
         if (removalPolicy === RemovalPolicy.RETAIN) {
             Tags.of(this.key).add(KMS_RETENTION_TAG_KEY, props.protects);
+            Tags.of(this.key).add(KMS_ALIAS_TAG_KEY, ResourceNaming.qualifiedKeyAlias(aliasName));
         }
         new CfnOutput(this, `${outputName}KeyArn`, {
             key: `${outputName}Arn`,
@@ -61,7 +71,7 @@ export class CustomerManagedKey extends Construct {
             exportName: stackScopedExportName(this, `${outputName}KeyArn`)
         });
         this.alias = new Alias(this, `${id}KeyAlias`, {
-            aliasName: props.aliasName || ResourceNaming.defaultKeyAlias(id),
+            aliasName,
             targetKey: this.key
         });
         new CfnOutput(this, `${outputName}KeyAliasArn`, {

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

@@ -1,8 +1,9 @@
 import { Stack } from "aws-cdk-lib";
 import { PolicyStatement, ServicePrincipal } from "aws-cdk-lib/aws-iam";
 import { tierDefault } from "../../../utils/backupTierMapping.js";
+import { ResourceNaming } from "../../../utils/resourceNaming.js";
 import { CustomerManagedKey } from "./kms.js";
-const STACK_ENCRYPTION_KEY_ID = "FjallStackEncryptionKey";
+const STACK_ENCRYPTION_KEY_ID = ResourceNaming.stackEncryptionKeyConstructId();
 /**
  * AWS services that publish to an application's SNS topics on the app's
  * behalf and therefore encrypt messages through the topic's key: EventBridge
@@ -48,9 +49,10 @@ export class StackEncryptionKey extends CustomerManagedKey {
     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)`,
-            // KMS alias names are unique per account-region, so the stack name is
-            // the namespace — every stack in the account carries its own key.
-            aliasName: `cmk/${stack.stackName}/${STACK_ENCRYPTION_KEY_ID}`,
+            // Derived through ResourceNaming so the deploy-test teardown, which
+            // finds the retained key by this alias after the stack is gone, cannot
+            // spell it differently.
+            aliasName: ResourceNaming.stackEncryptionKeyAlias(stack.stackName),
             protects: "outlives-stack"
         });
     }

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

@@ -1,22 +1,17 @@
-import { BACKUP_TIERS, BACKUP_TIER_DEFAULTS, type BackupTier, type BackupTierDefaults, tierDefault } from "@fjall/util";
-/** Tag key used by AWS Backup plan selection rules */
-export declare const BACKUP_TIER_TAG_KEY = "fjall:disasterRecovery:tier";
+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 and its defaults table are owned by
- * `@fjall/util` (`BACKUP_TIERS`, `BACKUP_TIER_DEFAULTS`, `tierDefault`) and
- * shared with the generator (`BACKUP_VAULT_TIERS`) and the CLI's synth
- * expectations, so every system derives from one declaration. Re-exported
- * here so construct code keeps one import path for tier concerns.
+ * The application backup tier vocabulary, its defaults table, the DR tag key
+ * and the tier → tag-value map are owned by `@fjall/util` (`BACKUP_TIERS`,
+ * `BACKUP_TIER_DEFAULTS`, `tierDefault`, `BACKUP_TIER_TAG_KEY`,
+ * `BACKUP_TIER_TAG_MAP`) and shared with the generator (`BACKUP_VAULT_TIERS`),
+ * 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.
  */
 export type { BackupTier, BackupTierDefaults };
-export { BACKUP_TIERS, BACKUP_TIER_DEFAULTS, tierDefault };
-/**
- * Shared mapping from application backup tier names to AWS Backup plan tag values.
- *
- * Used by both App.applyBackupTier() (app-level tag) and StandardTagsAspect
- * (per-resource tag) to ensure consistent tier → tag translation.
- */
-export declare const BACKUP_TIER_TAG_MAP: Readonly<Record<BackupTier, string>>;
+export { BACKUP_TIERS, BACKUP_TIER_DEFAULTS, BACKUP_TIER_TAG_KEY, BACKUP_TIER_TAG_MAP, tierDefault };
 /**
  * The tier a resource actually runs under: its own override, else the
  * app-level tier `App.getApp({ backup: { tier } })` declared. The single

package/dist/lib/utils/backupTierMapping.js

@@ -1,18 +1,5 @@
-import { BACKUP_TIERS, BACKUP_TIER_DEFAULTS, tierDefault } from "@fjall/util";
-/** Tag key used by AWS Backup plan selection rules */
-export const BACKUP_TIER_TAG_KEY = "fjall:disasterRecovery:tier";
-export { BACKUP_TIERS, BACKUP_TIER_DEFAULTS, tierDefault };
-/**
- * Shared mapping from application backup tier names to AWS Backup plan tag values.
- *
- * Used by both App.applyBackupTier() (app-level tag) and StandardTagsAspect
- * (per-resource tag) to ensure consistent tier → tag translation.
- */
-export const BACKUP_TIER_TAG_MAP = Object.freeze({
-    standard: "default",
-    resilient: "resilient",
-    enterprise: "enterprise"
-});
+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 };
 /**
  * The tier a resource actually runs under: its own override, else the
  * app-level tier `App.getApp({ backup: { tier } })` declared. The single

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);

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

@@ -77,6 +77,28 @@ export declare class ResourceNaming {
      * reports.
      */
     static defaultKeyAlias(constructId: string): string;
+    /**
+     * Construct id of the one `StackEncryptionKey` an enterprise-tier stack
+     * mints (lib/resources/aws/secrets/stackEncryptionKey.ts). It is also the
+     * alias suffix, so the two are spelled once.
+     */
+    static stackEncryptionKeyConstructId(): string;
+    /**
+     * Alias the stack encryption key is created under. KMS alias names are
+     * unique per account-region, so the stack name is the namespace. Unprefixed
+     * like the other alias helpers; the deploy tests that find the retained key
+     * after its stack is gone derive the reported form through
+     * [[qualifiedKeyAlias]], the same way the construct's alias tag does.
+     */
+    static stackEncryptionKeyAlias(stackName: string): string;
+    /**
+     * An alias name as KMS reports it. The CDK `Alias` prepends `alias/` to a
+     * resolved name that lacks it, and to a token only when the token's
+     * leading literal fragment lacks it — every Fjall alias starts with the
+     * literal `cmk/`, so the two rules agree. An already-qualified name is
+     * returned as it is.
+     */
+    static qualifiedKeyAlias(aliasName: string): string;
     /**
      * S3 bucket holding a VPC's flow logs. `id` is the Network construct id —
      * the network name for an additional VPC, `${stackPrefix}Vpc` for the

package/dist/lib/utils/resourceNaming.js

@@ -1,6 +1,8 @@
 import { toKebab } from "./capitaliseString.js";
 /** ELBv2's hard limit on an Application Load Balancer's name. */
 const LOAD_BALANCER_NAME_MAX_LENGTH = 32;
+/** What `kms list-aliases` prepends to every alias name. */
+const KMS_ALIAS_PREFIX = "alias/";
 /**
  * Centralised resource naming for infrastructure.
  * Ensures consistent, predictable names across constructs and tests.
@@ -127,6 +129,36 @@ export class ResourceNaming {
     static defaultKeyAlias(constructId) {
         return `cmk/${constructId}`;
     }
+    /**
+     * Construct id of the one `StackEncryptionKey` an enterprise-tier stack
+     * mints (lib/resources/aws/secrets/stackEncryptionKey.ts). It is also the
+     * alias suffix, so the two are spelled once.
+     */
+    static stackEncryptionKeyConstructId() {
+        return "FjallStackEncryptionKey";
+    }
+    /**
+     * Alias the stack encryption key is created under. KMS alias names are
+     * unique per account-region, so the stack name is the namespace. Unprefixed
+     * like the other alias helpers; the deploy tests that find the retained key
+     * after its stack is gone derive the reported form through
+     * [[qualifiedKeyAlias]], the same way the construct's alias tag does.
+     */
+    static stackEncryptionKeyAlias(stackName) {
+        return `cmk/${stackName}/${ResourceNaming.stackEncryptionKeyConstructId()}`;
+    }
+    /**
+     * An alias name as KMS reports it. The CDK `Alias` prepends `alias/` to a
+     * resolved name that lacks it, and to a token only when the token's
+     * leading literal fragment lacks it — every Fjall alias starts with the
+     * literal `cmk/`, so the two rules agree. An already-qualified name is
+     * returned as it is.
+     */
+    static qualifiedKeyAlias(aliasName) {
+        return aliasName.startsWith(KMS_ALIAS_PREFIX)
+            ? aliasName
+            : `${KMS_ALIAS_PREFIX}${aliasName}`;
+    }
     /**
      * S3 bucket holding a VPC's flow logs. `id` is the Network construct id —
      * the network name for an additional VPC, `${stackPrefix}Vpc` for the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/components-infrastructure",
-  "version": "36.0.0",
+  "version": "38.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fjall-tech/fjall.git",
@@ -80,8 +80,8 @@
   },
   "dependencies": {
     "@aws-sdk/client-organizations": "^3.1098.0",
-    "@fjall/generator": "^36.0.0",
-    "@fjall/util": "^36.0.0",
+    "@fjall/generator": "^38.0.0",
+    "@fjall/util": "^38.0.0",
     "constructs": "^10.7.2",
     "zod": "^4.4.3"
   },