@fjall/components-infrastructure 2.12.0 → 2.13.0

package/dist/lib/config/aws/cloudTrail.d.ts

@@ -1,7 +1,20 @@
 import { Construct } from "constructs";
+import type { AccountTrailState } from "../../utils/cdkContext.js";
 export interface ManagementEventsTrailProps {
     accountId: string;
     region: string;
+    /**
+     * "active" (default) synthesises trail + bucket + CMK. "draining" omits the
+     * trail resource so CloudFormation deletes it, while the bucket + CMK keep
+     * their logical IDs and retained history. "removed" never reaches this
+     * construct — Account skips construction entirely.
+     */
+    lifecycleState?: Exclude<AccountTrailState, "removed">;
+    /**
+     * Bucket + CMK survive stack deletion. Default true; Account passes false
+     * for development environments to avoid retained-orphan churn.
+     */
+    retainAuditHistory?: boolean;
 }
 export declare class ManagementEventsTrail extends Construct {
     constructor(scope: Construct, id: string, props: ManagementEventsTrailProps);

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

@@ -1,12 +1,28 @@
+import { CfnOutput } from "aws-cdk-lib";
 import { Construct } from "constructs";
+import { ACCOUNT_TRAIL_NAME, TRAIL_BUCKET_OUTPUT_KEY, TRAIL_KEY_ARN_OUTPUT_KEY } from "@fjall/util/config";
 import { Trail } from "../../resources/aws/logging/cloudTrail.js";
 export class ManagementEventsTrail extends Construct {
     constructor(scope, id, props) {
         super(scope, id);
-        new Trail(this, "ManagementEventsTrail", {
+        const trail = new Trail(this, "ManagementEventsTrail", {
             bucketName: `cloudtrail-management-events-${props.accountId}-${props.region}`,
-            trailName: "managementEvents",
-            isMultiRegionTrail: true
+            trailName: ACCOUNT_TRAIL_NAME,
+            isMultiRegionTrail: true,
+            retainAuditHistory: props.retainAuditHistory ?? true,
+            omitTrail: props.lifecycleState === "draining"
+        });
+        new CfnOutput(this, "TrailBucketNameOutput", {
+            key: TRAIL_BUCKET_OUTPUT_KEY,
+            value: trail.bucket.bucketName,
+            exportName: TRAIL_BUCKET_OUTPUT_KEY,
+            description: "Per-account CloudTrail bucket, read by the org-trail migration reconciler"
+        });
+        new CfnOutput(this, "TrailKeyArnOutput", {
+            key: TRAIL_KEY_ARN_OUTPUT_KEY,
+            value: trail.encryptionKey.key.keyArn,
+            exportName: TRAIL_KEY_ARN_OUTPUT_KEY,
+            description: "Per-account CloudTrail CMK, read by the org-trail migration reconciler"
         });
     }
 }

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

@@ -6,6 +6,7 @@ import { cronSchedule } from "../../resources/aws/messaging/index.js";
 import { AccountPrincipal, Effect, PolicyStatement } from "aws-cdk-lib/aws-iam";
 import { getConfig } from "../../utils/getConfig.js";
 import { toPascalCase } from "../../utils/capitaliseString.js";
+import { BACKUP_VAULT_NAME } from "@fjall/util";
 // Backup retention constants (in days)
 const RETENTION_PERIODS = {
     STANDARD: 90,
@@ -21,7 +22,6 @@ const BACKUP_WINDOWS = {
     COMPLETION: Duration.hours(12),
     COMPLETION_SHORT: Duration.hours(2)
 };
-const BACKUP_VAULT_NAME = "backupVault";
 // Vault lock constants
 const VAULT_LOCK = {
     MIN_RETENTION: Duration.days(365),

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

@@ -2,6 +2,7 @@ import { Construct } from "constructs";
 import { CodeBuildProject } from "../../resources/aws/utilities/codeBuild.js";
 import { BuildSpec } from "aws-cdk-lib/aws-codebuild";
 import { LogGroup } from "../../resources/aws/logging/logGroup.js";
+import { RetentionDays } from "aws-cdk-lib/aws-logs";
 import { RemovalPolicy, Stack } from "aws-cdk-lib";
 import { Role } from "../../resources/aws/iam/role.js";
 import { PolicyDocument, PolicyStatement, ServicePrincipal } from "aws-cdk-lib/aws-iam";
@@ -11,6 +12,7 @@ export class EcrDefaultImage extends Construct {
         super(scope, id);
         const logGroup = new LogGroup(this, `${id}LogGroup`, {
             logGroupName: `/vpc/codebuild/${id}/`,
+            retention: RetentionDays.ONE_MONTH,
             removalPolicy: RemovalPolicy.DESTROY
         });
         const ecrDefaultImageRole = new Role(this, `${id}Role`, {

package/dist/lib/config/aws/organisationTrail.d.ts

@@ -0,0 +1,16 @@
+import { Construct } from "constructs";
+export interface OrganisationTrailProps {
+    orgId: string;
+    managementAccountId: string;
+    region: string;
+}
+/**
+ * Organisation-wide management-events trail, owned by the management account.
+ * Replaces per-account ManagementEventsTrail instances in organisation mode:
+ * AWS records every member's management events into the one bucket under
+ * AWSLogs/<orgId>/<accountId>/, and members cannot stop or alter the shadow
+ * trail AWS materialises for them.
+ */
+export declare class OrganisationTrail extends Construct {
+    constructor(scope: Construct, id: string, props: OrganisationTrailProps);
+}

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

@@ -0,0 +1,32 @@
+import { CfnOutput } from "aws-cdk-lib";
+import { Construct } from "constructs";
+import { ORG_TRAIL_BUCKET_OUTPUT_KEY, ORGANISATION_TRAIL_NAME } from "@fjall/util/config";
+import { Trail } from "../../resources/aws/logging/cloudTrail.js";
+/**
+ * Organisation-wide management-events trail, owned by the management account.
+ * Replaces per-account ManagementEventsTrail instances in organisation mode:
+ * AWS records every member's management events into the one bucket under
+ * AWSLogs/<orgId>/<accountId>/, and members cannot stop or alter the shadow
+ * trail AWS materialises for them.
+ */
+export class OrganisationTrail extends Construct {
+    constructor(scope, id, props) {
+        super(scope, id);
+        const trail = new Trail(this, "OrganisationTrail", {
+            // "org" short form keeps the name inside S3's 63-character limit for
+            // long region names.
+            bucketName: `cloudtrail-org-management-events-${props.managementAccountId}-${props.region}`,
+            trailName: ORGANISATION_TRAIL_NAME,
+            isMultiRegionTrail: true,
+            isOrganizationTrail: true,
+            orgId: props.orgId,
+            retainAuditHistory: true
+        });
+        new CfnOutput(this, "OrganisationTrailBucketNameOutput", {
+            key: ORG_TRAIL_BUCKET_OUTPUT_KEY,
+            value: trail.bucket.bucketName,
+            exportName: ORG_TRAIL_BUCKET_OUTPUT_KEY,
+            description: "Organisation trail bucket, read by the org-trail migration reconciler"
+        });
+    }
+}

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

@@ -18,6 +18,7 @@ export interface AccountProps extends StackProps {
 export declare class Account extends Stack {
     readonly organisationType: OrganisationType;
     protected readonly resolvedRegion: string;
+    protected readonly accountGlobalsConfigured: boolean;
     constructor(scope: Construct, id: string, props: AccountProps);
     /**
      * Whether this account receives the OIDC deploy connector (provider +
@@ -34,6 +35,14 @@ export declare class Account extends Stack {
      * Deliberately separate from the OIDC/IPAM gates — the axes are independent.
      */
     protected createsEcrDefaultImage(): boolean;
+    /**
+     * Whether this account owns its own management-events trail. Standalone,
+     * Platform, and member accounts do (subject to the fjallAccountTrailState
+     * decommission lifecycle); the organisation root overrides to `false`
+     * because its OrganisationTrail records this account's events too.
+     * Deliberately separate from the OIDC/ECR gates — the axes are independent.
+     */
+    protected createsManagementEventsTrail(): boolean;
     enableGuardDuty(props?: GuardDutyDetectorProps): GuardDutyDetector;
     enableSecurityHub(props?: SecurityHubHubProps): SecurityHubHub;
     enableConfigRecorder(props?: ConfigRecorderProps): ConfigRecorder;

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

@@ -4,7 +4,7 @@ import { ManagementEventsTrail } from "../../config/aws/cloudTrail.js";
 import { OidcConnector } from "../../config/aws/oidcConnector.js";
 import { AccountMonitoringRole } from "../../config/aws/accountMonitoringRole.js";
 import { AccountAuditRole } from "../../config/aws/accountAuditRole.js";
-import { CDK_CONTEXT_KEYS } from "../../utils/cdkContext.js";
+import { CDK_CONTEXT_KEYS, resolveAccountTrailState } from "../../utils/cdkContext.js";
 import { getConfig } from "../../utils/getConfig.js";
 import { DisasterRecovery } from "../../config/aws/disasterRecovery.js";
 import { S3BlockPublicAccess } from "../../config/aws/s3BlockPublicAccess.js";
@@ -18,6 +18,7 @@ import { InspectorEnablement } from "../../config/aws/inspectorEnablement.js";
 export class Account extends Stack {
     organisationType = "account";
     resolvedRegion;
+    accountGlobalsConfigured;
     constructor(scope, id, props) {
         const config = getConfig();
         const accountId = props.accountId ?? config.accountId;
@@ -59,6 +60,7 @@ export class Account extends Stack {
         // (OIDC provider/role, FjallMonitoring, FjallAudit) have fixed names that
         // collide across regions, so they are created only in the home region.
         const accountGlobalsConfigured = this.node.tryGetContext("fjallAccountGlobalsConfigured") === "true";
+        this.accountGlobalsConfigured = accountGlobalsConfigured;
         if (this.receivesDeployRole() &&
             fjallOrgId &&
             !oidcAlreadyConfigured &&
@@ -71,17 +73,28 @@ export class Account extends Stack {
         if (fjallOrgId && !accountGlobalsConfigured) {
             new AccountAuditRole(this, "AuditRole", { fjallOrgId });
         }
-        new ManagementEventsTrail(this, "CloudTrail", {
-            accountId: this.account,
-            region: this.resolvedRegion
-        });
+        const environment = config.environment ?? "unknown";
+        // The trail is multi-region, so a non-home-region cascade stack creating
+        // its own copy records every management event a second time — CloudTrail
+        // bills additional copies at $2.00/100k events. Home region only, like
+        // the other account globals above.
+        const trailState = resolveAccountTrailState(this.node);
+        if (!accountGlobalsConfigured &&
+            this.createsManagementEventsTrail() &&
+            trailState !== "removed") {
+            new ManagementEventsTrail(this, "CloudTrail", {
+                accountId: this.account,
+                region: this.resolvedRegion,
+                lifecycleState: trailState,
+                retainAuditHistory: environment !== "development"
+            });
+        }
         if (this.createsEcrDefaultImage()) {
             new EcrDefaultImage(this, "EcrDefaultImage", {
                 region: this.resolvedRegion,
                 accountId: this.account
             });
         }
-        const environment = config.environment ?? "unknown";
         if (config.disasterRecoveryRegion) {
             const isComplianceAccount = environment === "compliance";
             if (environment === "production" || isComplianceAccount) {
@@ -124,6 +137,16 @@ export class Account extends Stack {
     createsEcrDefaultImage() {
         return true;
     }
+    /**
+     * Whether this account owns its own management-events trail. Standalone,
+     * Platform, and member accounts do (subject to the fjallAccountTrailState
+     * decommission lifecycle); the organisation root overrides to `false`
+     * because its OrganisationTrail records this account's events too.
+     * Deliberately separate from the OIDC/ECR gates — the axes are independent.
+     */
+    createsManagementEventsTrail() {
+        return true;
+    }
     enableGuardDuty(props) {
         return new GuardDutyDetector(this, "GuardDuty", props);
     }

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

@@ -47,6 +47,15 @@ export declare class Organisation extends Account {
      * default-ECR-image helper.
      */
     protected createsEcrDefaultImage(): boolean;
+    /**
+     * The organisation root owns the org-wide OrganisationTrail, which records
+     * this account's management events too — an ACTIVE per-account trail here
+     * would be a duplicate paid copy. Returning `false` skips Account's active
+     * synthesis; the root's own constructor instead keeps the legacy construct
+     * in draining form until the lifecycle reaches "org", so pre-existing audit
+     * storage survives the upgrade.
+     */
+    protected createsManagementEventsTrail(): boolean;
     private createAccountReferences;
     private setupOrganisationFeatures;
     private setupCostAllocationTagActivator;

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

@@ -1,10 +1,12 @@
 import App from "../../app.js";
 import { Account } from "./account.js";
 import { IdentityCenter } from "../../config/aws/identityCenter.js";
+import { ManagementEventsTrail } from "../../config/aws/cloudTrail.js";
+import { OrganisationTrail } from "../../config/aws/organisationTrail.js";
 import { ScpPreset } from "../../config/aws/scpPreset.js";
 import { OrganisationResource, OrganisationAccount, CostAllocationTagActivator } from "../../resources/aws/organisation/index.js";
 import { stripAndCamelCase } from "../../utils/stripAndCamelCase.js";
-import { CDK_CONTEXT_KEYS } from "../../utils/cdkContext.js";
+import { CDK_CONTEXT_KEYS, resolveAccountTrailState } from "../../utils/cdkContext.js";
 import { getConfig } from "../../utils/getConfig.js";
 import { extractAccountNames } from "../../utils/accountsUtils.js";
 /**
@@ -39,10 +41,17 @@ export class Organisation extends Account {
             this.accountMap[key.toLowerCase()] = value;
         }
         this.accountsConfig = props.accounts;
-        const orgId = this.node.tryGetContext(CDK_CONTEXT_KEYS.ORG_ID);
-        const rootId = this.node.tryGetContext(CDK_CONTEXT_KEYS.ROOT_ID);
-        const managementAccountId = this.node.tryGetContext(CDK_CONTEXT_KEYS.MANAGEMENT_ACCOUNT_ID) ??
-            this.account;
+        // CDK context is a `??` boundary: `-c key=` legitimately passes "", which
+        // would flow through `??`, defeat the `this.account` fallback, and break
+        // the SSO management-account exclusion downstream.
+        const orgIdCtx = this.node.tryGetContext(CDK_CONTEXT_KEYS.ORG_ID);
+        const rootIdCtx = this.node.tryGetContext(CDK_CONTEXT_KEYS.ROOT_ID);
+        const managementAccountCtx = this.node.tryGetContext(CDK_CONTEXT_KEYS.MANAGEMENT_ACCOUNT_ID);
+        const orgId = typeof orgIdCtx === "string" && orgIdCtx !== "" ? orgIdCtx : undefined;
+        const rootId = typeof rootIdCtx === "string" && rootIdCtx !== "" ? rootIdCtx : undefined;
+        const managementAccountId = (typeof managementAccountCtx === "string" && managementAccountCtx !== ""
+            ? managementAccountCtx
+            : undefined) ?? this.account;
         if (!orgId || !rootId) {
             throw new Error("orgId and rootId must be provided via CDK context. Run deployment through the Fjall CLI.");
         }
@@ -51,6 +60,32 @@ export class Organisation extends Account {
             rootId,
             managementAccountId
         });
+        // Home region only: the trail is multi-region, so an org-region cascade
+        // stack creating a second org-wide trail would duplicate every paid copy
+        // across the whole organisation.
+        if (!this.accountGlobalsConfigured) {
+            new OrganisationTrail(this, "OrganisationCloudTrail", {
+                orgId,
+                managementAccountId,
+                region: this.resolvedRegion
+            });
+            // Already-deployed roots carry a per-account trail whose bucket is
+            // DESTROY + autoDeleteObjects — dropping the construct outright would
+            // delete that audit history, bypassing the acknowledgeTrailHistoryLoss
+            // gate. Keep it in DRAINING form (same "CloudTrail" construct path as
+            // Account ⇒ identical bucket/CMK logical IDs): the trail resource goes,
+            // bucket + CMK flip to RETAIN until the reconciler decommissions them
+            // behind the gate. "removed" (trailLifecycle "org") synthesises nothing.
+            const trailState = resolveAccountTrailState(this.node);
+            if (trailState !== "removed") {
+                new ManagementEventsTrail(this, "CloudTrail", {
+                    accountId: this.account,
+                    region: this.resolvedRegion,
+                    lifecycleState: "draining",
+                    retainAuditHistory: true
+                });
+            }
+        }
         this.createAccountReferences(props);
         this.setupOrganisationFeatures(props.identityCenter ?? true, managementAccountId);
     }
@@ -70,6 +105,17 @@ export class Organisation extends Account {
     createsEcrDefaultImage() {
         return false;
     }
+    /**
+     * The organisation root owns the org-wide OrganisationTrail, which records
+     * this account's management events too — an ACTIVE per-account trail here
+     * would be a duplicate paid copy. Returning `false` skips Account's active
+     * synthesis; the root's own constructor instead keeps the legacy construct
+     * in draining form until the lifecycle reaches "org", so pre-existing audit
+     * storage survives the upgrade.
+     */
+    createsManagementEventsTrail() {
+        return false;
+    }
     createAccountReferences(props) {
         const allNames = extractAccountNames(props.accounts);
         for (const accountName of allNames) {

package/dist/lib/resources/aws/logging/cloudTrail.d.ts

@@ -1,14 +1,39 @@
 import { Stack } from "aws-cdk-lib";
 import * as CloudTrail from "aws-cdk-lib/aws-cloudtrail";
 import { Construct } from "constructs";
+import { CustomerManagedKey } from "../secrets/index.js";
 import { S3Bucket } from "../storage/index.js";
 interface CloudTrailProps extends CloudTrail.TrailProps {
     bucketName: string;
+    /**
+     * Bucket + CMK survive stack deletion (RemovalPolicy.RETAIN, auto-delete
+     * off). The trail resource itself stays DESTROY regardless — a retained
+     * trail keeps logging (and charging) as an unmanaged orphan. Default false
+     * preserves the historical TrailStack behaviour.
+     */
+    retainAuditHistory?: boolean;
+    /**
+     * Draining mode: synthesise only the bucket + CMK so CloudFormation deletes
+     * the trail resource while the retained storage keeps its logical IDs (and
+     * so its history) intact.
+     */
+    omitTrail?: boolean;
 }
+export declare function validateTrailProps(props: CloudTrailProps): void;
 export declare class Trail extends Construct {
-    readonly trail: CloudTrail.Trail;
+    readonly trail?: CloudTrail.Trail;
     readonly bucket: S3Bucket;
+    readonly encryptionKey: CustomerManagedKey;
     constructor(scope: Construct, id: string, props: CloudTrailProps);
+    /**
+     * The CDK L2 Trail contributes no KMS key-policy statements at all — it
+     * only sets kmsKeyId on the CfnTrail (verified in aws-cdk-lib 2.251.0).
+     * These three statements are therefore the entire CloudTrail-facing key
+     * policy: management-trail and member shadow-trail encryption plus S3
+     * digest delivery. None can be narrowed to member-only encryption contexts
+     * without breaking the management trail's own delivery.
+     */
+    private addOrganisationTrailKeyPolicy;
 }
 export declare class TrailStack extends Stack {
     constructor(scope: Construct, id: string, props: CloudTrailProps);

package/dist/lib/resources/aws/logging/cloudTrail.js

@@ -4,46 +4,135 @@ import { Construct } from "constructs";
 import { CustomerManagedKey } from "../secrets/index.js";
 import { S3Bucket } from "../storage/index.js";
 import { BucketEncryption } from "aws-cdk-lib/aws-s3";
-import { ServicePrincipal } from "aws-cdk-lib/aws-iam";
+import { PolicyStatement, ServicePrincipal } from "aws-cdk-lib/aws-iam";
+export function validateTrailProps(props) {
+    if (props.isOrganizationTrail === true) {
+        const missingOrgId = props.orgId === undefined || props.orgId === "";
+        const missingTrailName = props.trailName === undefined || props.trailName === "";
+        if (missingOrgId || missingTrailName) {
+            throw new Error("Organisation trails require both orgId and trailName — without them the CDK Trail construct silently skips the org-wide bucket-policy statement and member delivery fails at runtime.");
+        }
+        if (props.retainAuditHistory !== true) {
+            throw new Error("Organisation trails must set retainAuditHistory: true — organisation-wide audit history must survive stack deletion.");
+        }
+    }
+}
 export class Trail extends Construct {
     trail;
     bucket;
+    encryptionKey;
     constructor(scope, id, props) {
         super(scope, id);
-        const encryptionKey = new CustomerManagedKey(this, `${id}CloudTrailEncryptionKey`, {
+        validateTrailProps(props);
+        const { bucketName, retainAuditHistory, omitTrail, ...trailProps } = props;
+        const storagePolicy = retainAuditHistory === true
+            ? RemovalPolicy.RETAIN
+            : RemovalPolicy.DESTROY;
+        this.encryptionKey = new CustomerManagedKey(this, `${id}CloudTrailEncryptionKey`, {
             aliasName: `cmk/cloudtrail/${id}/encryptionKey`,
-            removalPolicy: RemovalPolicy.DESTROY
+            removalPolicy: storagePolicy
         });
         this.bucket = new S3Bucket(this, `${id}CloudTrailBucket`, {
-            bucketName: props.bucketName,
+            bucketName,
             bucketKeyEnabled: true,
             encryption: BucketEncryption.KMS,
-            encryptionKey: encryptionKey.key,
+            encryptionKey: this.encryptionKey.key,
             versioned: false,
+            removalPolicy: storagePolicy,
             lifecycleRules: [{ expiration: Duration.days(365), enabled: true }]
         });
-        this.bucket.grantReadWrite(new ServicePrincipal("cloudtrail.amazonaws.com"));
+        if (props.isOrganizationTrail === true) {
+            // The L2 Trail emits the organisation-wide bucket policy itself
+            // (AWSLogs/<orgId>/* delivery); granting read/write here would shadow
+            // it with a narrower per-account statement.
+            this.addOrganisationTrailKeyPolicy(props, bucketName);
+        }
+        else {
+            this.bucket.grantReadWrite(new ServicePrincipal("cloudtrail.amazonaws.com"));
+        }
+        if (omitTrail === true) {
+            return;
+        }
         this.trail = new CloudTrail.Trail(this, `${id}CloudTrail`, {
-            ...props,
+            ...trailProps,
             bucket: this.bucket,
             trailName: props.trailName || `${id}Trail`,
-            encryptionKey: encryptionKey.key
+            encryptionKey: this.encryptionKey.key
         });
-        // TODO: Revert to RemovalPolicy.RETAIN for production
+        // Always DESTROY even when storage is retained: a RETAINED trail would
+        // keep logging (and charging) as an unmanaged orphan after stack
+        // deletion. Audit durability lives on the bucket + CMK removal policies.
         this.trail.applyRemovalPolicy(RemovalPolicy.DESTROY);
         // Ensure the autoDeleteObjects custom resource is fully provisioned before
         // the trail starts writing to the bucket. Without this, a create-rollback
         // leaves the bucket non-empty (CloudTrail writes logs immediately) and the
         // auto-delete Lambda was never created — causing ROLLBACK_FAILED.
+        // (No-op in retain mode: auto-delete is off, so the child is absent.)
         const autoDeleteResource = this.bucket.node.tryFindChild("AutoDeleteObjectsCustomResource");
         if (autoDeleteResource) {
             this.trail.node.addDependency(autoDeleteResource);
         }
     }
+    /**
+     * The CDK L2 Trail contributes no KMS key-policy statements at all — it
+     * only sets kmsKeyId on the CfnTrail (verified in aws-cdk-lib 2.251.0).
+     * These three statements are therefore the entire CloudTrail-facing key
+     * policy: management-trail and member shadow-trail encryption plus S3
+     * digest delivery. None can be narrowed to member-only encryption contexts
+     * without breaking the management trail's own delivery.
+     */
+    addOrganisationTrailKeyPolicy(props, bucketName) {
+        const { partition, region, account } = Stack.of(this);
+        const cloudTrailPrincipal = new ServicePrincipal("cloudtrail.amazonaws.com");
+        const managementTrailArn = `arn:${partition}:cloudtrail:${region}:${account}:trail/${props.trailName}`;
+        this.encryptionKey.key.addToResourcePolicy(new PolicyStatement({
+            sid: "AllowOrganisationTrailEncrypt",
+            principals: [cloudTrailPrincipal],
+            actions: ["kms:GenerateDataKey*"],
+            resources: ["*"],
+            conditions: {
+                StringEquals: { "aws:SourceArn": managementTrailArn },
+                // Member shadow trails encrypt under the management account's trail
+                // namespace — one management-scoped wildcard covers every member.
+                StringLike: {
+                    "kms:EncryptionContext:aws:cloudtrail:arn": `arn:${partition}:cloudtrail:*:${account}:trail/*`
+                }
+            }
+        }));
+        this.encryptionKey.key.addToResourcePolicy(new PolicyStatement({
+            sid: "AllowOrganisationTrailDescribeKey",
+            principals: [cloudTrailPrincipal],
+            actions: ["kms:DescribeKey"],
+            resources: ["*"],
+            conditions: {
+                StringEquals: { "aws:SourceArn": managementTrailArn }
+            }
+        }));
+        this.encryptionKey.key.addToResourcePolicy(new PolicyStatement({
+            sid: "AllowOrganisationTrailDigestDelivery",
+            principals: [cloudTrailPrincipal],
+            actions: ["kms:GenerateDataKey*", "kms:Decrypt"],
+            resources: ["*"],
+            conditions: {
+                // Digest files arrive via the bucket's default SSE-KMS. The literal
+                // bucket name (not bucket.bucketArn) avoids a Key↔Bucket
+                // dependency cycle at synth time. Two exact entries (bucket-level
+                // context + per-object contexts) — a bare `${bucketName}*` would
+                // also match sibling bucket NAMES sharing the prefix.
+                StringLike: {
+                    "kms:EncryptionContext:aws:s3:arn": [
+                        `arn:${partition}:s3:::${bucketName}`,
+                        `arn:${partition}:s3:::${bucketName}/*`
+                    ]
+                }
+            }
+        }));
+    }
 }
 export class TrailStack extends Stack {
     constructor(scope, id, props) {
         super(scope, id);
+        validateTrailProps(props);
         new Trail(this, id, {
             ...props
         });

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

@@ -1,9 +1,20 @@
 import type { Node } from "constructs";
+import { ACCOUNT_TRAIL_STATES, type AccountTrailState } from "@fjall/util/config";
 export declare const CDK_CONTEXT_KEYS: {
     readonly ORG_ID: "orgId";
     readonly ROOT_ID: "rootId";
     readonly MANAGEMENT_ACCOUNT_ID: "managementAccountId";
+    readonly ORG_CONFIG: "orgConfig";
+    readonly ACCOUNT_TRAIL_STATE: "fjallAccountTrailState";
 };
+export { ACCOUNT_TRAIL_STATES, type AccountTrailState };
+/**
+ * Resolves the per-account management-events-trail lifecycle state from CDK
+ * context. Unset (or the `-c key=` empty-string boundary) means `active`.
+ * An unrecognised value throws rather than defaulting: a typo arriving
+ * mid-decommission must fail the synth, not silently re-create a trail.
+ */
+export declare function resolveAccountTrailState(node: Node): AccountTrailState;
 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,8 +1,29 @@
+import { ACCOUNT_TRAIL_STATES } from "@fjall/util/config";
 export const CDK_CONTEXT_KEYS = {
     ORG_ID: "orgId",
     ROOT_ID: "rootId",
-    MANAGEMENT_ACCOUNT_ID: "managementAccountId"
+    MANAGEMENT_ACCOUNT_ID: "managementAccountId",
+    ORG_CONFIG: "orgConfig",
+    ACCOUNT_TRAIL_STATE: "fjallAccountTrailState"
 };
+export { ACCOUNT_TRAIL_STATES };
+/**
+ * Resolves the per-account management-events-trail lifecycle state from CDK
+ * context. Unset (or the `-c key=` empty-string boundary) means `active`.
+ * An unrecognised value throws rather than defaulting: a typo arriving
+ * mid-decommission must fail the synth, not silently re-create a trail.
+ */
+export function resolveAccountTrailState(node) {
+    const raw = node.tryGetContext(CDK_CONTEXT_KEYS.ACCOUNT_TRAIL_STATE);
+    if (raw === undefined || raw === "") {
+        return "active";
+    }
+    if (typeof raw === "string" &&
+        ACCOUNT_TRAIL_STATES.includes(raw)) {
+        return raw;
+    }
+    throw new Error(`${CDK_CONTEXT_KEYS.ACCOUNT_TRAIL_STATE} must be one of ${ACCOUNT_TRAIL_STATES.join(", ")}; received "${String(raw)}"`);
+}
 export const DEFAULT_ORG_ID = "default";
 export function resolveOrgId(node, fallback) {
     const raw = node.tryGetContext(CDK_CONTEXT_KEYS.ORG_ID);

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

@@ -26,6 +26,11 @@ type EnvConfig<T> = {
  * 4. `CDK_DEFAULT_ACCOUNT` → providerAccounts lookup
  * 5. `-c accountName=<value>` → providerAccounts lookup
  * 6. `"unknown"` (with warning)
+ *
+ * Deliberately diverges from utils/getConfig.ts, which is App-scoped and
+ * account-aware: there `-c environment` context wins and ENVIRONMENT is a
+ * last-resort fallback. This helper is pre-App and process-wide, so it treats
+ * ENVIRONMENT as the dominant ambient signal.
  */
 export declare function getEnvironment(): string;
 /**

package/dist/lib/utils/env.js

@@ -1,4 +1,5 @@
-import { parseOrgConfig } from "./orgConfigParser.js";
+import { CDK_CONTEXT_KEYS } from "./cdkContext.js";
+import { parseOrgConfig, resolveSynthEnvironment } from "./orgConfigParser.js";
 import { FjallLogger } from "./validationLogger.js";
 let cachedEnvironment;
 /**
@@ -11,6 +12,11 @@ let cachedEnvironment;
  * 4. `CDK_DEFAULT_ACCOUNT` → providerAccounts lookup
  * 5. `-c accountName=<value>` → providerAccounts lookup
  * 6. `"unknown"` (with warning)
+ *
+ * Deliberately diverges from utils/getConfig.ts, which is App-scoped and
+ * account-aware: there `-c environment` context wins and ENVIRONMENT is a
+ * last-resort fallback. This helper is pre-App and process-wide, so it treats
+ * ENVIRONMENT as the dominant ambient signal.
  */
 export function getEnvironment() {
     if (cachedEnvironment !== undefined) {
@@ -92,19 +98,24 @@ function parseContextArg(key) {
  * Get provider accounts from orgConfig in CDK context (-c orgConfig=<json>).
  */
 function getProviderAccountsFromContext() {
-    return parseOrgConfig(parseContextArg("orgConfig")).providerAccounts;
+    return parseOrgConfig(parseContextArg(CDK_CONTEXT_KEYS.ORG_CONFIG))
+        .providerAccounts;
 }
 /**
  * Look up environment from account ID via orgConfig CDK context.
+ * Organisation-tier accounts resolve to "root" (resolveSynthEnvironment).
  */
 function resolveEnvironmentFromAccountId(accountId) {
     const accounts = getProviderAccountsFromContext();
-    return accounts.find((pa) => pa.id === accountId)?.environment ?? undefined;
+    const account = accounts.find((pa) => pa.id === accountId);
+    return account ? resolveSynthEnvironment(account) : undefined;
 }
 /**
  * Look up environment from account name via orgConfig CDK context.
+ * Organisation-tier accounts resolve to "root" (resolveSynthEnvironment).
  */
 function resolveEnvironmentFromAccountName(accountName) {
     const accounts = getProviderAccountsFromContext();
-    return (accounts.find((pa) => pa.name === accountName)?.environment ?? undefined);
+    const account = accounts.find((pa) => pa.name === accountName);
+    return account ? resolveSynthEnvironment(account) : undefined;
 }

package/dist/lib/utils/getConfig.js

@@ -1,5 +1,6 @@
 import App from "../app.js";
-import { parseOrgConfig } from "./orgConfigParser.js";
+import { CDK_CONTEXT_KEYS } from "./cdkContext.js";
+import { parseOrgConfig, resolveSynthEnvironment } from "./orgConfigParser.js";
 import { findAccountNameCollision } from "./capitaliseString.js";
 import { FjallLogger } from "./validationLogger.js";
 export function getConfig(accountName) {
@@ -14,7 +15,7 @@ export function getConfig(accountName) {
     if (!process.env.AWS_REGION)
         FjallLogger.warn("AWS_REGION is not set, defaulting to us-east-1");
     // Primary: read org config from CDK context (injected by CLI/worker)
-    const orgConfigRaw = app.node.tryGetContext("orgConfig");
+    const orgConfigRaw = app.node.tryGetContext(CDK_CONTEXT_KEYS.ORG_CONFIG);
     if (typeof orgConfigRaw !== "string") {
         FjallLogger.warn("No orgConfig context provided — org-level config (accounts, regions) will be empty");
     }
@@ -53,41 +54,60 @@ export function getConfig(accountName) {
     // If unspecified account name - try to retrieve from context
     if (!accountName) {
         const contextAccountName = app.node.tryGetContext("accountName");
-        if (typeof contextAccountName === "string") {
+        if (typeof contextAccountName === "string" && contextAccountName !== "") {
             accountName = contextAccountName;
         }
     }
     // If we have an account name - look for associated provider account
+    let stageIsStructurallyNull = false;
     if (accountName) {
         const providerAccount = providerAccounts.find((pa) => pa.name === accountName);
         if (providerAccount) {
-            config.accountId = providerAccount.id;
-            config.accountName = providerAccount.name;
-            config.environment = providerAccount.environment ?? "unknown";
+            stageIsStructurallyNull = applyProviderAccount(config, providerAccount);
         }
     }
     // If we still don't have an account name - try to retrieve accountId from context
     if (!config.accountName) {
         const accountId = app.node.tryGetContext("accountId");
         // If we find an accountId - retrieve the associated account from config
-        if (typeof accountId === "string") {
+        if (typeof accountId === "string" && accountId !== "") {
             config.accountId = accountId;
             const providerAccount = providerAccounts.find((pa) => pa.id === accountId);
             if (providerAccount) {
-                config.accountName = providerAccount.name;
-                config.environment = providerAccount.environment ?? "unknown";
+                stageIsStructurallyNull = applyProviderAccount(config, providerAccount);
             }
         }
     }
-    // Check for environment from context (highest priority)
+    // Check for environment from context (highest priority). Resolution order
+    // deliberately diverges from utils/env.ts getEnvironment() (pre-App,
+    // process-wide: ENVIRONMENT first): here explicit `-c environment` context
+    // wins, and the ENVIRONMENT env var is a last-resort fallback that must
+    // never override an account-resolved stage — including a structurally-null
+    // one (organisation/platform tiers carry no workload stage).
     const contextEnvironment = app.node.tryGetContext("environment");
-    if (typeof contextEnvironment === "string") {
+    if (typeof contextEnvironment === "string" && contextEnvironment !== "") {
         config.environment = contextEnvironment;
     }
-    else if (process.env.ENVIRONMENT && config.environment === "unknown") {
+    else if (process.env.ENVIRONMENT &&
+        config.environment === "unknown" &&
+        !stageIsStructurallyNull) {
         // Fall back to ENVIRONMENT variable if no other source found
         config.environment = process.env.ENVIRONMENT;
     }
     return config;
 }
+/**
+ * Copy a resolved provider account onto the config. The organisation tier
+ * resolves to "root" (via resolveSynthEnvironment) so scaffolded org gates
+ * fire; other tiers carry their stage verbatim. Returns true when the
+ * environment stays unresolved (structurally-null stage) so the caller can
+ * suppress the ENVIRONMENT env-var fallback.
+ */
+function applyProviderAccount(config, providerAccount) {
+    config.accountId = providerAccount.id;
+    config.accountName = providerAccount.name;
+    const resolved = resolveSynthEnvironment(providerAccount);
+    config.environment = resolved ?? "unknown";
+    return resolved === undefined;
+}
 export default getConfig;

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

@@ -5,6 +5,16 @@ export interface ParsedOrgConfig {
     secondaryRegions: string[];
     disasterRecoveryRegion?: string;
 }
+/**
+ * Resolve a provider account's synth-time environment. The tier/stage
+ * separation (decisions/2026-06-07-account-tier-vs-stage-separation.md) nulls
+ * the wire `environment` for organisation-tier accounts, but scaffolded org
+ * entry points gate on `config.environment === "root"` — decode the tier back
+ * to the historical "root" marker via the sanctioned `accountTier()` decoder.
+ * Workload stages pass through verbatim; a null stage on any other tier stays
+ * unresolved (callers fall back to "unknown").
+ */
+export declare function resolveSynthEnvironment(account: Pick<ProviderAccount, "environment" | "tier">): string | undefined;
 /**
  * Parse orgConfig JSON from CDK context into a validated structure.
  *

package/dist/lib/utils/orgConfigParser.js

@@ -1,6 +1,46 @@
 import { VAULT_LOCK_MODES, S3_BPA_MODES } from "@fjall/util/config";
-import { maskSensitiveOutput } from "@fjall/util";
+import { ACCOUNT_TIERS, STRUCTURAL_ENVIRONMENTS, accountTier, maskSensitiveOutput } from "@fjall/util";
 import { FjallLogger } from "./validationLogger.js";
+function isProviderAccount(item) {
+    if (typeof item !== "object" || item === null)
+        return false;
+    const rec = item;
+    return (typeof rec.id === "string" &&
+        typeof rec.name === "string" &&
+        // null environment (structural accounts) must survive — rejecting it drops the account at synth.
+        (typeof rec.environment === "string" || rec.environment === null) &&
+        (rec.tier === undefined || ACCOUNT_TIERS.includes(rec.tier)) &&
+        (rec.managed === undefined || typeof rec.managed === "boolean") &&
+        (rec.oidcRoleArn === undefined || typeof rec.oidcRoleArn === "string") &&
+        (rec.vaultLock === undefined ||
+            VAULT_LOCK_MODES.includes(rec.vaultLock)) &&
+        (rec.s3BlockPublicAccess === undefined ||
+            S3_BPA_MODES.includes(rec.s3BlockPublicAccess)) &&
+        (rec.acknowledgeImmutableVaultLock === undefined ||
+            typeof rec.acknowledgeImmutableVaultLock === "boolean"));
+}
+/**
+ * Resolve a provider account's synth-time environment. The tier/stage
+ * separation (decisions/2026-06-07-account-tier-vs-stage-separation.md) nulls
+ * the wire `environment` for organisation-tier accounts, but scaffolded org
+ * entry points gate on `config.environment === "root"` — decode the tier back
+ * to the historical "root" marker via the sanctioned `accountTier()` decoder.
+ * Workload stages pass through verbatim; a null stage on any other tier stays
+ * unresolved (callers fall back to "unknown").
+ */
+export function resolveSynthEnvironment(account) {
+    if (accountTier(account) === "organisation") {
+        return STRUCTURAL_ENVIRONMENTS.ROOT;
+    }
+    return account.environment ?? undefined;
+}
+function describeRejectedAccount(item) {
+    if (typeof item !== "object" || item === null)
+        return "<unidentifiable>";
+    const rec = item;
+    const parts = [rec.id, rec.name].filter((v) => typeof v === "string");
+    return parts.length > 0 ? parts.join(" / ") : "<unidentifiable>";
+}
 /**
  * Parse orgConfig JSON from CDK context into a validated structure.
  *
@@ -20,28 +60,12 @@ export function parseOrgConfig(raw) {
             return empty;
         const obj = parsed;
         const providerAccounts = Array.isArray(obj.providerAccounts)
-            ? obj.providerAccounts.filter((item) => typeof item === "object" &&
-                item !== null &&
-                typeof item.id === "string" &&
-                typeof item.name === "string" &&
-                // null environment (structural accounts) must survive — rejecting it drops the account at synth.
-                (typeof item.environment ===
-                    "string" ||
-                    item.environment === null) &&
-                (item.managed === undefined ||
-                    typeof item.managed === "boolean") &&
-                (item.oidcRoleArn === undefined ||
-                    typeof item.oidcRoleArn ===
-                        "string") &&
-                (item.vaultLock === undefined ||
-                    VAULT_LOCK_MODES.includes(item.vaultLock)) &&
-                (item.s3BlockPublicAccess ===
-                    undefined ||
-                    S3_BPA_MODES.includes(item.s3BlockPublicAccess)) &&
-                (item.acknowledgeImmutableVaultLock ===
-                    undefined ||
-                    typeof item
-                        .acknowledgeImmutableVaultLock === "boolean"))
+            ? obj.providerAccounts.filter((item) => {
+                if (isProviderAccount(item))
+                    return true;
+                FjallLogger.warn(`[fjall] Ignoring malformed provider account in orgConfig context: ${describeRejectedAccount(item)}`);
+                return false;
+            })
             : [];
         const primaryRegion = typeof obj.primaryRegion === "string" ? obj.primaryRegion : undefined;
         const secondaryRegions = Array.isArray(obj.secondaryRegions)

package/package.json

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