@fjall/components-infrastructure 2.11.1 → 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/config/aws/s3BlockPublicAccess.d.ts

@@ -1,9 +1,27 @@
 import { Construct } from "constructs";
+export interface S3BlockPublicAccessProps {
+    /**
+     * Account whose account-level S3 Block Public Access is managed. Taken as a
+     * prop rather than read from `Stack.of(this).account` — that is a synth token
+     * that never matches a provider-account id when looking up config.
+     */
+    accountId: string;
+}
 /**
- * Enables S3 Block Public Access at the account level via a Custom Resource.
- * All four public access flags are set to true (block all public access).
- * Stack deletion does NOT revert this setting — security features are preserved.
+ * Manages account-level S3 Block Public Access via a Custom Resource.
+ *
+ * Off by default: Fjall observes-and-flags exposed buckets through the posture
+ * layer rather than hard-blocking at the account level. Set
+ * `s3BlockPublicAccess: "enforced"` on a provider account to switch all four
+ * flags on. The flags ride in the custom resource's properties (not hardcoded
+ * in the handler) so a config change reconciles on the next deploy. Stack
+ * deletion is a no-op — the account-level setting is left as-is.
+ *
+ * The handler runs under a fixed `/fjall/FjallS3BpaManager` role so the
+ * DenyS3PublicAccessChanges SCP can exempt its PutAccountPublicAccessBlock by
+ * ARN pattern. The role name is account-global, so this construct is created
+ * only in an account's home region (see Account's accountGlobals gate).
  */
 export declare class S3BlockPublicAccess extends Construct {
-    constructor(scope: Construct, id: string);
+    constructor(scope: Construct, id: string, props: S3BlockPublicAccessProps);
 }

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

@@ -1,23 +1,41 @@
 import { Duration } from "aws-cdk-lib";
 import { Effect, PolicyStatement } from "aws-cdk-lib/aws-iam";
 import { Runtime } from "aws-cdk-lib/aws-lambda";
-import { Stack } from "aws-cdk-lib";
 import { Construct } from "constructs";
 import { CustomResource } from "../../resources/aws/utilities/customResource.js";
+import { getConfig } from "../../utils/getConfig.js";
 /**
- * Enables S3 Block Public Access at the account level via a Custom Resource.
- * All four public access flags are set to true (block all public access).
- * Stack deletion does NOT revert this setting — security features are preserved.
+ * Manages account-level S3 Block Public Access via a Custom Resource.
+ *
+ * Off by default: Fjall observes-and-flags exposed buckets through the posture
+ * layer rather than hard-blocking at the account level. Set
+ * `s3BlockPublicAccess: "enforced"` on a provider account to switch all four
+ * flags on. The flags ride in the custom resource's properties (not hardcoded
+ * in the handler) so a config change reconciles on the next deploy. Stack
+ * deletion is a no-op — the account-level setting is left as-is.
+ *
+ * The handler runs under a fixed `/fjall/FjallS3BpaManager` role so the
+ * DenyS3PublicAccessChanges SCP can exempt its PutAccountPublicAccessBlock by
+ * ARN pattern. The role name is account-global, so this construct is created
+ * only in an account's home region (see Account's accountGlobals gate).
  */
 export class S3BlockPublicAccess extends Construct {
-    constructor(scope, id) {
+    constructor(scope, id, props) {
         super(scope, id);
+        const account = getConfig().providerAccounts.find((pa) => pa.id === props.accountId);
+        const enforce = (account?.s3BlockPublicAccess ?? "off") === "enforced";
         new CustomResource(this, "S3BlockPublicAccess", {
             runtime: Runtime.NODEJS_22_X,
             timeout: Duration.minutes(5),
-            lambdaDescription: "Enables S3 Block Public Access at account level",
+            lambdaDescription: "Manages S3 Block Public Access at account level",
+            rolePath: "/fjall/",
+            roleName: "FjallS3BpaManager",
             properties: {
-                AccountId: Stack.of(this).account
+                AccountId: props.accountId,
+                BlockPublicAcls: String(enforce),
+                IgnorePublicAcls: String(enforce),
+                BlockPublicPolicy: String(enforce),
+                RestrictPublicBuckets: String(enforce)
             },
             inlinePolicy: [
                 new PolicyStatement({
@@ -32,20 +50,22 @@ export class S3BlockPublicAccess extends Construct {
             inlineCode: `
 const { S3ControlClient, PutPublicAccessBlockCommand } = require('@aws-sdk/client-s3-control');
 
+const toBool = (v) => v === 'true' || v === true;
+
 exports.handler = async (event) => {
   const physicalResourceId = event.PhysicalResourceId || event.LogicalResourceId || 's3-block-public-access';
   if (event.RequestType === 'Delete') {
     return { PhysicalResourceId: physicalResourceId };
   }
-  const accountId = event.ResourceProperties.AccountId;
+  const props = event.ResourceProperties;
   const client = new S3ControlClient({});
   await client.send(new PutPublicAccessBlockCommand({
-    AccountId: accountId,
+    AccountId: props.AccountId,
     PublicAccessBlockConfiguration: {
-      BlockPublicAcls: true,
-      IgnorePublicAcls: true,
-      BlockPublicPolicy: true,
-      RestrictPublicBuckets: true
+      BlockPublicAcls: toBool(props.BlockPublicAcls),
+      IgnorePublicAcls: toBool(props.IgnorePublicAcls),
+      BlockPublicPolicy: toBool(props.BlockPublicPolicy),
+      RestrictPublicBuckets: toBool(props.RestrictPublicBuckets)
     }
   }));
   return { PhysicalResourceId: physicalResourceId };

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

@@ -5,7 +5,12 @@ import { OrganisationPolicy } from "../../resources/aws/organisation/organisatio
 // default path.
 const EXEMPT_ROLE_PATTERNS = [
     "arn:aws:iam::*:role/fjall/FjallDeploy*",
-    "arn:aws:iam::*:role/OrganizationAccountAccessRole"
+    "arn:aws:iam::*:role/OrganizationAccountAccessRole",
+    // The account-level S3 Block Public Access manager Lambda re-applies BPA on
+    // every deploy; its PutAccountPublicAccessBlock must survive
+    // DenyS3PublicAccessChanges. Pathed under /fjall/ so a member admin cannot
+    // forge an exempt role at the default path.
+    "arn:aws:iam::*:role/fjall/FjallS3BpaManager*"
 ];
 const SCP_BYTE_LIMIT = 5120;
 const IAM_POLICY_VERSION = "2012-10-17";

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 +
@@ -27,6 +28,21 @@ export declare class Account extends Stack {
      * independent, and Platform must take one but not the other.
      */
     protected receivesDeployRole(): boolean;
+    /**
+     * Whether this account creates the default-ECR-image helper (the CodeBuild
+     * project that seeds a placeholder application image). App-hosting accounts
+     * need it; the organisation root runs no workloads and overrides to `false`.
+     * 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,15 +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
-        });
-        new EcrDefaultImage(this, "EcrDefaultImage", {
-            region: this.resolvedRegion,
-            accountId: this.account
-        });
         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
+            });
+        }
         if (config.disasterRecoveryRegion) {
             const isComplianceAccount = environment === "compliance";
             if (environment === "production" || isComplianceAccount) {
@@ -95,7 +110,12 @@ export class Account extends Stack {
             exportName: "Environment",
             description: "Environment type for this account (e.g., production, staging, development)"
         });
-        new S3BlockPublicAccess(this, "S3BlockPublicAccess");
+        // Account-level S3 Block Public Access is account-global and runs under a
+        // fixed-name role, so (like the OIDC/Monitoring/Audit globals above) it is
+        // created only in the home region to avoid a cross-region role collision.
+        if (!accountGlobalsConfigured) {
+            new S3BlockPublicAccess(this, "S3BlockPublicAccess", { accountId });
+        }
         new EbsDefaultEncryption(this, "EbsDefaultEncryption");
     }
     /**
@@ -108,6 +128,25 @@ export class Account extends Stack {
     receivesDeployRole() {
         return this.constructor === Account;
     }
+    /**
+     * Whether this account creates the default-ECR-image helper (the CodeBuild
+     * project that seeds a placeholder application image). App-hosting accounts
+     * need it; the organisation root runs no workloads and overrides to `false`.
+     * Deliberately separate from the OIDC/IPAM gates — the axes are independent.
+     */
+    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

@@ -1,21 +1,21 @@
-import { type Environment, Stack, type StackProps } from "aws-cdk-lib";
+import { type Environment } from "aws-cdk-lib";
+import { type Construct } from "constructs";
+import { Account, type AccountProps } from "./account.js";
 import { type CustomPermissionSets } from "../../config/aws/identityCenter.js";
 import { ScpPreset } from "../../config/aws/scpPreset.js";
 import type { ScpPresetProps } from "../../config/aws/scpPreset.js";
 import { OrganisationResource } from "../../resources/aws/organisation/index.js";
-type ExtendedStackProps = Omit<StackProps, "env"> & {
-    env?: Required<Pick<Environment, "region" | "account">> & Partial<Omit<Environment, "region" | "account">>;
-};
 export type AccountsConfig = {
     readonly [key: string]: readonly string[] | string | AccountsConfig;
 };
-export interface OrganisationProps extends ExtendedStackProps {
+export interface OrganisationProps extends AccountProps {
     organisationName: string;
     accounts: AccountsConfig;
     orgEmail: string;
     accountIds?: Record<string, string>;
     identityCenter?: boolean;
     allowedRegions?: string[];
+    env?: Required<Pick<Environment, "region" | "account">> & Partial<Omit<Environment, "region" | "account">>;
 }
 /**
  * Organisation CDK stack.
@@ -27,14 +27,35 @@ export interface OrganisationProps extends ExtendedStackProps {
  * - Identity Centre configuration
  * - Cost allocation tag auto-activation (daily Lambda)
  */
-export declare class Organisation extends Stack {
+export declare class Organisation extends Account {
     readonly organisationType: "organisation";
     private org;
     private accountRefs;
     private accountMap;
     private accountsConfig;
     private identityCenter?;
-    constructor(id: string, props: OrganisationProps);
+    constructor(scope: Construct, id: string, props: OrganisationProps);
+    /**
+     * The organisation root's OIDC deploy connector is owned by the customer-run
+     * Quick-Create CloudFormation stack, never the inherited Account connector.
+     * Returning `false` is also the short-circuit first clause of Account's OIDC
+     * gate, so no `OidcConnector` is synthesised on the root stack.
+     */
+    protected receivesDeployRole(): boolean;
+    /**
+     * The organisation root runs no application workloads, so it needs no
+     * 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;
@@ -45,4 +66,3 @@ export declare class Organisation extends Stack {
     getAccounts(): Record<string, string>;
     enableScps(props: ScpPresetProps): ScpPreset;
 }
-export {};

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

@@ -1,10 +1,12 @@
-import { Stack } from "aws-cdk-lib";
 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";
 /**
@@ -17,23 +19,20 @@ import { extractAccountNames } from "../../utils/accountsUtils.js";
  * - Identity Centre configuration
  * - Cost allocation tag auto-activation (daily Lambda)
  */
-export class Organisation extends Stack {
+export class Organisation extends Account {
     organisationType = "organisation";
     org;
     accountRefs = [];
     accountMap;
     accountsConfig;
     identityCenter;
-    constructor(id, props) {
+    constructor(scope, id, props) {
         const config = getConfig();
-        const env = props.env ?? {
-            region: config.region,
-            account: config.accountId ?? ""
-        };
-        if (!env.account) {
-            throw new Error("Organisation requires an account ID. Provide it via env.account or ensure CDK context includes accountId.");
+        const accountId = props.accountId ?? props.env?.account ?? config.accountId;
+        if (!accountId) {
+            throw new Error("Organisation requires an account ID. Provide it via env.account, accountId, or ensure CDK context includes accountId.");
         }
-        super(App.getInstance(), id, { ...props, env });
+        super(scope, id, { ...props, accountId });
         // Normalise account map keys to lowercase for case-insensitive lookups.
         // providerAccounts stores names as lowercase; ACCOUNTS config uses PascalCase.
         const rawMap = props.accountIds ?? config.accountIds ?? {};
@@ -42,10 +41,17 @@ export class Organisation extends Stack {
             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.");
         }
@@ -54,9 +60,62 @@ export class Organisation extends Stack {
             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);
     }
+    /**
+     * The organisation root's OIDC deploy connector is owned by the customer-run
+     * Quick-Create CloudFormation stack, never the inherited Account connector.
+     * Returning `false` is also the short-circuit first clause of Account's OIDC
+     * gate, so no `OidcConnector` is synthesised on the root stack.
+     */
+    receivesDeployRole() {
+        return false;
+    }
+    /**
+     * The organisation root runs no application workloads, so it needs no
+     * default-ECR-image helper.
+     */
+    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/patterns/aws/organisationFactory.js

@@ -1,3 +1,4 @@
+import App from "../../app.js";
 import { Organisation } from "./organisation.js";
 import { Platform } from "./platform.js";
 import { Account } from "./account.js";
@@ -5,7 +6,7 @@ export class OrganisationFactory {
     static build(id, props) {
         switch (props.type) {
             case "organisation":
-                return new Organisation(id, props);
+                return new Organisation(App.getInstance(), id, props);
             case "platform":
                 return (scope) => new Platform(scope, id, props);
             case "account":

package/dist/lib/resources/aws/compute/lambda.d.ts

@@ -15,6 +15,17 @@ export interface LambdaFunctionProps {
     handler: string;
     lambdaDescription?: string;
     roleDescription?: string;
+    /**
+     * Fixed IAM path for the auto-generated execution role (e.g. "/fjall/").
+     * Used with roleName to produce an SCP-exemptable ARN.
+     */
+    rolePath?: string;
+    /**
+     * Fixed name for the auto-generated execution role. Account-global — only set
+     * on a Lambda confined to one (account, region) stack, else regional
+     * duplicates collide on the role name.
+     */
+    roleName?: string;
     runtime: Runtime;
     /** Lambda CPU architecture. Default: x86_64 */
     architecture?: Architecture;

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

@@ -31,6 +31,24 @@ function applyRoleDescription(fn, description) {
     if (cfnRole !== undefined)
         cfnRole.description = description;
 }
+/**
+ * Pin a fixed IAM path and/or name onto CDK's auto-generated Lambda execution
+ * role. Reaches the L1 CfnRole (FunctionProps exposes neither) so a stable,
+ * predictable ARN can be matched by an SCP exemption pattern. A fixed name is
+ * account-global, so only set one on a Lambda that lives in a single
+ * (account, region) stack — never one duplicated across regions.
+ */
+function applyRolePathAndName(fn, rolePath, roleName) {
+    if (rolePath === undefined && roleName === undefined)
+        return;
+    const cfnRole = fn.role?.node.defaultChild;
+    if (cfnRole === undefined)
+        return;
+    if (rolePath !== undefined)
+        cfnRole.path = rolePath;
+    if (roleName !== undefined)
+        cfnRole.roleName = roleName;
+}
 /**
  * AWS Parameters and Secrets Lambda Extension configuration.
  * @see https://docs.aws.amazon.com/systems-manager/latest/userguide/ps-integration-lambda-extensions.html
@@ -61,6 +79,7 @@ export class SingletonFunction extends singletonFunction {
         });
         addPoliciesToRole(this, props.inlinePolicy);
         applyRoleDescription(this, props.roleDescription);
+        applyRolePathAndName(this, props.rolePath, props.roleName);
     }
     /**
      * The Lambda's execution role (auto-generated by CDK)
@@ -91,6 +110,7 @@ export class LambdaFunction extends Function {
         });
         addPoliciesToRole(this, props.inlinePolicy);
         applyRoleDescription(this, props.roleDescription);
+        applyRolePathAndName(this, props.rolePath, props.roleName);
         this.addSecretsSupport(props.secrets, props.ssmSecretsPath, props.secretsImport, props.appName, props.functionName, props.architecture);
         // Sanitise id for CloudFormation output keys (must be alphanumeric)
         const outputName = toPascalCase(id);

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/resources/aws/utilities/customResource.d.ts

@@ -7,6 +7,10 @@ interface CustomResourceProps {
     runtime: Runtime;
     roleDescription?: string;
     lambdaDescription?: string;
+    /** Fixed IAM path for the handler's execution role (e.g. "/fjall/"). */
+    rolePath?: string;
+    /** Fixed name for the handler's execution role (account-global — see LambdaFunctionProps). */
+    roleName?: string;
     inlinePolicy: PolicyStatement[];
     properties?: {
         [key: string]: string;

package/dist/lib/resources/aws/utilities/customResource.js

@@ -39,6 +39,8 @@ export class CustomResource extends Construct {
                 timeout,
                 lambdaDescription: props.lambdaDescription ?? `${id} lambda`,
                 roleDescription: props.roleDescription ?? `${id} custom resource lambda`,
+                rolePath: props.rolePath,
+                roleName: props.roleName,
                 inlinePolicy: props.inlinePolicy
             })
             : new SingletonFunction(this, `${id}Lambda`, {
@@ -47,6 +49,8 @@ export class CustomResource extends Construct {
                 runtime: props.runtime,
                 lambdaDescription: props.lambdaDescription ?? `${id} lambda`,
                 roleDescription: props.roleDescription ?? `${id} custom resource lambda`,
+                rolePath: props.rolePath,
+                roleName: props.roleName,
                 inlinePolicy: props.inlinePolicy
             });
         const provider = new Provider(this, `${id}Provider`, {

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;
+    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;
+    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;
+            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;
+                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 } from "@fjall/util/config";
-import { maskSensitiveOutput } from "@fjall/util";
+import { VAULT_LOCK_MODES, S3_BPA_MODES } from "@fjall/util/config";
+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,22 +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" &&
-                typeof item.environment === "string" &&
-                (item.managed === undefined ||
-                    typeof item.managed === "boolean") &&
-                (item.oidcRoleArn === undefined ||
-                    typeof item.oidcRoleArn ===
-                        "string") &&
-                (item.vaultLock === undefined ||
-                    VAULT_LOCK_MODES.includes(item.vaultLock)) &&
-                (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.11.1",
+  "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.11.1",
-    "@fjall/util": "^2.11.1",
+    "@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": "69823c3d7f2eacba419657464381119c5b5b5fd6"
+  "gitHead": "5b16c5731256628f829d4168c65cf165b3516f9a"
 }