@fjall/components-infrastructure 2.15.0 → 2.17.0

package/dist/lib/config/aws/scpPreset.js

@@ -32,6 +32,12 @@ function buildFoundationGuardrails(allowedRegions) {
                 // Deny + NotAction denies everything except the policy-management
                 // scopes a root-task unlock session needs; the AWS root-task policies
                 // constrain those sessions further.
+                // iam:CreateLoginProfile/GetLoginProfile (root-credential recovery on
+                // assume-root sessions) are deliberately NOT carved out — recovery on
+                // this tier is a break-glass SCP detach, not a standing carve-out. Do
+                // not add them without revisiting the decision:
+                // aiDocs/troubleshooting/centralised-root-access-break-glass-runbook.md
+                // § Scenario 3.
                 NotAction: [
                     "s3:GetBucketPolicy",
                     "s3:PutBucketPolicy",
@@ -214,6 +220,9 @@ function buildEncryptionAndAccess() {
             {
                 Sid: "DenyIamUserCreation",
                 Effect: "Deny",
+                // Also blocks iam:CreateLoginProfile for assume-root recovery
+                // sessions (they match none of EXEMPT_ROLE_PATTERNS) — deliberate;
+                // see the DenyRootUserActions note + break-glass runbook § Scenario 3.
                 Action: [
                     "iam:CreateUser",
                     "iam:CreateAccessKey",

package/dist/lib/patterns/aws/storage.d.ts

@@ -2,12 +2,12 @@ import { Construct } from "constructs";
 import { type IBucket, type EventType, type IBucketNotificationDestination, type NotificationKeyFilter } from "aws-cdk-lib/aws-s3";
 import { type IGrantable, type Grant } from "aws-cdk-lib/aws-iam";
 import type App from "../../app.js";
-import { BucketDeployment, type WebsiteHostingConfig } from "../../resources/aws/storage/index.js";
+import { BucketDeployment, type ResourcePolicyStatement, type WebsiteHostingConfig } from "../../resources/aws/storage/index.js";
 import { type BackupTier } from "../../utils/backupTierMapping.js";
 import { type IStorage } from "./interfaces/storage.js";
 import { type IStorageConnector } from "./interfaces/connector.js";
 export { type IStorage, isStorage } from "./interfaces/storage.js";
-export { type WebsiteHostingConfig } from "../../resources/aws/storage/index.js";
+export { type ResourcePolicyStatement, type WebsiteHostingConfig } from "../../resources/aws/storage/index.js";
 export interface CorsRule {
     readonly allowedOrigins: string[];
     readonly allowedMethods: string[];
@@ -40,6 +40,8 @@ export interface S3Props {
     readonly deployment?: S3DeploymentConfig;
     /** When true, sets RemovalPolicy.RETAIN (overriding the env-aware default). Used for imported buckets. */
     readonly retain?: boolean;
+    /** Declarative bucket-policy statements appended to the bucket's resource policy. */
+    readonly resourcePolicyStatements?: ResourcePolicyStatement[];
 }
 export interface StorageBuildProps extends S3Props {
     readonly stackPlacement?: "storage" | "cdn" | "compute";

package/dist/lib/patterns/aws/storage.js

@@ -66,6 +66,7 @@ export class Storage extends Construct {
             backupVaultTier: props.backupVaultTier,
             publicReadAccess: props.publicReadAccess,
             websiteHosting: props.websiteHosting,
+            resourcePolicyStatements: props.resourcePolicyStatements,
             ...(props.cors && { cors: toCorsRules(props.cors) }),
             ...(props.retain && { removalPolicy: RemovalPolicy.RETAIN })
         });

package/dist/lib/resources/aws/compute/ec2GracefulTerminationHandler.js

@@ -43,8 +43,13 @@ export class Ec2GracefulTerminationHandler extends Construct {
         const dataVolumeOwnerLogicalId = resolveOptionalString(props.dataVolumeOwnerLogicalId);
         this.queue = new SQSQueue(this, `${id}Queue`, {
             visibilityTimeout: QUEUE_VISIBILITY_TIMEOUT_SECONDS,
-            deadLetterQueue: { enabled: true, maxReceiveCount: 5 }
+            deadLetterQueue: { enabled: true, maxReceiveCount: 5 },
+            // Transient instance-drain signals — no durable state. Pinned DESTROY
+            // (now also the SQSQueue wrapper default) so a replacing deploy of the
+            // parent Ec2Instance reclaims this queue + DLQ instead of orphaning them.
+            removalPolicy: "DESTROY"
         });
+        const stack = Stack.of(this);
         const ecsPolicies = ecsClusterArn !== undefined
             ? [
                 new PolicyStatement({
@@ -66,6 +71,9 @@ export class Ec2GracefulTerminationHandler extends Construct {
                 })
             ]
             : [];
+        // EIP/ENI mutations cannot be ARN-scoped (the resources are not known at
+        // synth), but the Lambda only ever drains instances in its own region — a
+        // region clamp removes the cross-region blast radius a bare "*" would allow.
         const ec2Policies = new PolicyStatement({
             effect: Effect.ALLOW,
             actions: [
@@ -74,7 +82,10 @@ export class Ec2GracefulTerminationHandler extends Construct {
                 "ec2:DescribeNetworkInterfaces",
                 "ec2:DetachNetworkInterface"
             ],
-            resources: ["*"]
+            resources: ["*"],
+            conditions: {
+                StringEquals: { "aws:RequestedRegion": stack.region }
+            }
         });
         const elbReadPolicy = new PolicyStatement({
             effect: Effect.ALLOW,
@@ -94,7 +105,6 @@ export class Ec2GracefulTerminationHandler extends Construct {
                 }
             }
         });
-        const stack = Stack.of(this);
         // Account/region-scoped wildcard rather than the specific ASG ARN —
         // see PersistentDataVolume for the full deadlock writeup. Same gotcha:
         // a specific ARN creates a CFN Ref to the ASG, the Lambda's IAM Policy

package/dist/lib/resources/aws/compute/ecsImages.js

@@ -1,14 +1,14 @@
 import { CfnParameter, Stack } from "aws-cdk-lib";
 import { ContainerImage } from "aws-cdk-lib/aws-ecs";
 import { Repository } from "aws-cdk-lib/aws-ecr";
+import { imageTagParameterName } from "@fjall/util";
 import { DEFAULT_ECS_FALLBACK_IMAGE } from "./ecsConstants.js";
-import { toPascalCase } from "../../../utils/capitaliseString.js";
 function buildImageTagDescription(serviceName) {
     return `Image tag for ECS service ${serviceName}. Set by fjall deploy to the content-hash tag.`;
 }
 function getOrCreateImageTagParameter(ctx, serviceName) {
     const stack = Stack.of(ctx.scope);
-    const paramLogicalId = `${toPascalCase(serviceName)}ImageTag`;
+    const paramLogicalId = imageTagParameterName(serviceName);
     const description = buildImageTagDescription(serviceName);
     const existing = stack.node.tryFindChild(paramLogicalId);
     if (existing instanceof CfnParameter) {

package/dist/lib/resources/aws/compute/persistentDataVolume.js

@@ -105,7 +105,11 @@ export class PersistentDataVolume extends Construct {
         Tags.of(this.volume).add(PERSISTENT_DATA_VOLUME_TAG_STACK_ID, Aws.STACK_ID);
         this.queue = new SQSQueue(this, `${id}Queue`, {
             visibilityTimeout: QUEUE_VISIBILITY_TIMEOUT_SECONDS,
-            deadLetterQueue: { enabled: true, maxReceiveCount: 5 }
+            deadLetterQueue: { enabled: true, maxReceiveCount: 5 },
+            // Transient volume-attach signals — no durable state (the EBS volume
+            // itself is SNAPSHOT above). Pinned DESTROY (now also the SQSQueue wrapper
+            // default) so a replacing deploy reclaims this queue + DLQ, not orphans.
+            removalPolicy: "DESTROY"
         });
         const sourcePath = path.resolve(__dirname, LAUNCHING_LAMBDA_SOURCE_FILE);
         const source = readFileSync(sourcePath, "utf-8");

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

@@ -7,6 +7,11 @@ export interface SNSTopicProps {
     displayName?: string;
     fifo?: boolean;
     contentBasedDeduplication?: boolean;
+    /**
+     * Removal policy for the topic. Defaults to DESTROY — a topic is a transient
+     * fan-out medium with no durable state (see the constructor). Pass "RETAIN"
+     * only for a topic that must survive stack deletion.
+     */
     removalPolicy?: RemovalPolicyString;
 }
 export declare class SNSTopic extends Construct {

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

@@ -22,7 +22,13 @@ export class SNSTopic extends Construct {
                 ? (props.contentBasedDeduplication ?? true)
                 : undefined
         });
-        this.topic.applyRemovalPolicy(toRemovalPolicy(props.removalPolicy));
+        // An SNS topic is a transient fan-out medium: it holds no durable state
+        // (subscriptions are re-created by the next deploy), so the wrapper defaults
+        // to DESTROY — deliberately NOT the env-aware production->RETAIN of
+        // data-bearing wrappers (S3, EventBus). RETAIN here buys no protection and
+        // orphans the topic on a parent construct's logical-ID churn (the same leak
+        // class fixed for SQS). Durable topics opt into RETAIN via props.removalPolicy.
+        this.topic.applyRemovalPolicy(toRemovalPolicy(props.removalPolicy ?? "DESTROY"));
         new CfnOutput(this, `${id}TopicArn`, {
             key: `${id}TopicArn`,
             value: this.topic.topicArn,

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

@@ -60,6 +60,12 @@ export interface SQSQueueProps {
     contentBasedDeduplication?: boolean;
     fifoThroughputLimit?: "perQueue" | "perMessageGroupId";
     deduplicationScope?: "queue" | "messageGroup";
+    /**
+     * Removal policy for the queue (and its auto-created DLQ, which tracks it).
+     * Defaults to DESTROY — a queue is a transient work medium (see the
+     * constructor). Pass "RETAIN" only for a queue whose contents are
+     * irreplaceable and must survive stack deletion.
+     */
     removalPolicy?: RemovalPolicyString;
 }
 export declare class SQSQueue extends Construct {

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

@@ -83,6 +83,14 @@ export class SQSQueue extends Construct {
         this.id = id;
         // Sanitise id for CloudFormation output keys (must be alphanumeric)
         const outputName = toPascalCase(id);
+        // 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
+        // DESTROY — deliberately NOT the env-aware production->RETAIN of
+        // data-bearing wrappers (S3, EventBus). RETAIN here buys no protection and
+        // orphans the queue on a parent construct's logical-ID churn (the prod
+        // orphan leak). Durable queues opt into RETAIN via props.removalPolicy.
+        const resolvedRemovalPolicy = toRemovalPolicy(props.removalPolicy ?? "DESTROY");
         const isFifo = props.queueType === "fifo";
         const queueName = props.queueName
             ? isFifo
@@ -110,7 +118,7 @@ export class SQSQueue extends Construct {
                     fifo: isFifo,
                     encryption: toEncryption(props.encryption),
                     retentionPeriod: Duration.days(SQS_LIMITS.DEAD_LETTER_QUEUE.DEFAULT_RETENTION_DAYS),
-                    removalPolicy: toRemovalPolicy(props.removalPolicy)
+                    removalPolicy: resolvedRemovalPolicy
                 });
                 deadLetterQueue = {
                     queue: this.dlq,
@@ -156,7 +164,7 @@ export class SQSQueue extends Construct {
             deduplicationScope: isFifo
                 ? toDeduplicationScope(props.deduplicationScope)
                 : undefined,
-            removalPolicy: toRemovalPolicy(props.removalPolicy)
+            removalPolicy: resolvedRemovalPolicy
         });
         new CfnOutput(this, `${outputName}QueueUrl`, {
             key: `${outputName}QueueUrl`,

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

@@ -5,6 +5,7 @@ import { getDomainExportNames } from "@fjall/util";
 import { toPascalCase, getSafeZoneName } from "../../../utils/capitaliseString.js";
 import { DelegationRole } from "../iam/delegationRole.js";
 import { applyCostAllocationTags } from "../../../utils/costAllocationTags.js";
+import { resolveOrgId } from "../../../utils/cdkContext.js";
 export class HostedZoneFactory {
     static import(stack, hostedZoneId, zoneName, opts) {
         const safeZone = toPascalCase(getSafeZoneName(zoneName));
@@ -49,7 +50,17 @@ export class HostedZone extends Construct {
                 value: Fn.join(",", created.hostedZoneNameServers ?? []),
                 exportName: exportNames.nameservers
             });
-            if (props.createDelegationRole !== false) {
+            // Org-gate: a single account has no OrganisationId export, so an org-trusting
+            // delegation role would leave an unresolved Fn::ImportValue and roll the stack
+            // back. Default follows org presence; explicit `true` opts in (and fails fast).
+            const inOrganisation = resolveOrgId(this.node) !== undefined;
+            if (props.createDelegationRole === true && !inOrganisation) {
+                throw new Error(`HostedZone "${props.zoneName}": createDelegationRole was requested but ` +
+                    `this account is not part of an AWS Organization (no "orgId" context). ` +
+                    `Cross-account DNS delegation requires an organisation — omit ` +
+                    `createDelegationRole for single-account setups, or connect an organisation.`);
+            }
+            if (props.createDelegationRole ?? inOrganisation) {
                 this.delegationRole = new DelegationRole(this, `${safeZone}DelegationRole`, {
                     zoneName: props.zoneName,
                     hostedZone: created,

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

@@ -6,6 +6,25 @@ export interface WebsiteHostingConfig {
     readonly indexDocument: string;
     readonly errorDocument?: string;
 }
+/**
+ * A single bucket-policy statement expressed declaratively. {@link S3Bucket}
+ * turns each entry into an `addToResourcePolicy` call at synth.
+ *
+ * Principals are either `"*"` (anonymous / public) or an IAM ARN (account root,
+ * role, or user). Service and Federated principals are not yet modelled — a
+ * remediation that meets one must fall back to report-only rather than dropping
+ * it silently. Mirrors the codemod's `S3ResourcePlanSchema.resourcePolicyStatements`
+ * in `@fjall/generator` — the two shapes must move together.
+ */
+export interface ResourcePolicyStatement {
+    readonly sid?: string;
+    readonly effect: "Allow" | "Deny";
+    readonly principals: string[];
+    readonly actions: string[];
+    /** Defaults to the bucket itself and its objects when omitted. */
+    readonly resources?: string[];
+    readonly conditions?: Record<string, Record<string, string | string[]>>;
+}
 /**
  * Props for {@link S3Bucket}.
  *
@@ -17,6 +36,12 @@ export interface S3BucketProps extends BucketProps {
     backupVaultTier?: BackupTier;
     publicReadAccess?: boolean;
     websiteHosting?: WebsiteHostingConfig;
+    /**
+     * Declarative bucket-policy statements, each appended via
+     * `addToResourcePolicy`. The TLS-only `enforceSSL` deny is always applied
+     * separately and must NOT be listed here.
+     */
+    resourcePolicyStatements?: ResourcePolicyStatement[];
 }
 export declare class S3Bucket extends Bucket {
     readonly backupVaultTier?: BackupTier;

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

@@ -1,6 +1,7 @@
 import { SDK_PRE_EMPTY_TAG_KEY } from "@fjall/util/aws";
 import { Annotations, CfnOutput, Duration, RemovalPolicy, Tags } from "aws-cdk-lib";
 import { BlockPublicAccess, Bucket } 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 { toPascalCase } from "../../../utils/capitaliseString.js";
 import { envAwareRemovalPolicyDefault, toRemovalPolicy } from "../../../utils/removalPolicy.js";
@@ -8,10 +9,15 @@ export { SDK_PRE_EMPTY_TAG_KEY } from "@fjall/util/aws";
 function shouldAutoVersion(tier) {
     return tier === "resilient" || tier === "enterprise";
 }
+function toResourcePolicyPrincipal(identifier) {
+    return identifier === "*"
+        ? new StarPrincipal()
+        : new ArnPrincipal(identifier);
+}
 export class S3Bucket extends Bucket {
     backupVaultTier;
     constructor(scope, id, props = {}) {
-        const { websiteHosting, backupVaultTier, ...cdkProps } = props;
+        const { websiteHosting, backupVaultTier, resourcePolicyStatements, ...cdkProps } = props;
         const isPublic = props.publicReadAccess === true || websiteHosting !== undefined;
         const versioned = props.versioned ?? shouldAutoVersion(backupVaultTier);
         const removalPolicy = props.removalPolicy ?? toRemovalPolicy(envAwareRemovalPolicyDefault());
@@ -42,6 +48,21 @@ export class S3Bucket extends Bucket {
                 : props.lifecycleRules
         });
         this.backupVaultTier = backupVaultTier;
+        for (const statement of resourcePolicyStatements ?? []) {
+            this.addToResourcePolicy(new PolicyStatement({
+                ...(statement.sid !== undefined && { sid: statement.sid }),
+                effect: statement.effect === "Deny" ? Effect.DENY : Effect.ALLOW,
+                principals: statement.principals.map(toResourcePolicyPrincipal),
+                actions: statement.actions,
+                resources: statement.resources ?? [
+                    this.bucketArn,
+                    this.arnForObjects("*")
+                ],
+                ...(statement.conditions !== undefined && {
+                    conditions: statement.conditions
+                })
+            }));
+        }
         if (props.autoDeleteObjects === true) {
             Annotations.of(this).addWarningV2("@fjall/components-infrastructure:s3:autoDeleteObjectsIgnored", "autoDeleteObjects: true is ignored — the CDK auto-delete custom " +
                 "resource is retired (ADR D4.3). DESTROY buckets are emptied " +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/components-infrastructure",
-  "version": "2.15.0",
+  "version": "2.17.0",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "bin": {
@@ -63,8 +63,8 @@
   },
   "dependencies": {
     "@aws-sdk/client-organizations": "^3.1038.0",
-    "@fjall/generator": "^2.15.0",
-    "@fjall/util": "^2.15.0",
+    "@fjall/generator": "^2.17.0",
+    "@fjall/util": "^2.17.0",
     "constructs": "^10.0.0",
     "uuid": "^14.0.0"
   },
@@ -79,5 +79,5 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "gitHead": "b2223855907cb6d467e47df073b2a5b28c684ede"
+  "gitHead": "21cfe1aae339e12183af2813ec81f581b9b77d49"
 }