@fjall/components-infrastructure 37.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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/components-infrastructure",
-  "version": "37.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": "^37.0.0",
-    "@fjall/util": "^37.0.0",
+    "@fjall/generator": "^38.0.0",
+    "@fjall/util": "^38.0.0",
     "constructs": "^10.7.2",
     "zod": "^4.4.3"
   },