@fjall/components-infrastructure 2.12.0 → 2.14.0

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

@@ -4,46 +4,208 @@ 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"));
+        const effectiveTrailName = props.trailName || `${id}Trail`;
+        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 {
+            const accountTrailArn = this.trailArn(effectiveTrailName);
+            this.addAccountTrailBucketPolicy(accountTrailArn);
+            this.addAccountTrailKeyPolicy(accountTrailArn, bucketName);
+        }
+        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
+            trailName: effectiveTrailName,
+            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.
-        const autoDeleteResource = this.bucket.node.tryFindChild("AutoDeleteObjectsCustomResource");
-        if (autoDeleteResource) {
-            this.trail.node.addDependency(autoDeleteResource);
-        }
+    }
+    trailArn(trailName) {
+        const { partition, region, account } = Stack.of(this);
+        return `arn:${partition}:cloudtrail:${region}:${account}:trail/${trailName}`;
+    }
+    /**
+     * Canonical CloudTrail delivery policy (ACL probe + log write), scoped to
+     * this trail's ARN via aws:SourceArn so no other trail — including one in
+     * another account — can deliver into or probe the bucket. Emitted from
+     * this construct rather than left to the L2 Trail because draining mode
+     * (omitTrail) skips the L2 construct while the trail being deleted may
+     * still deliver mid-update. Fjall-prefixed sids avoid colliding with the
+     * sid-less statements the L2 Trail adds when it is constructed.
+     */
+    addAccountTrailBucketPolicy(trailArn) {
+        const { account } = Stack.of(this);
+        const cloudTrailPrincipal = new ServicePrincipal("cloudtrail.amazonaws.com");
+        this.bucket.addToResourcePolicy(new PolicyStatement({
+            sid: "FjallCloudTrailAclCheck",
+            principals: [cloudTrailPrincipal],
+            actions: ["s3:GetBucketAcl"],
+            resources: [this.bucket.bucketArn],
+            conditions: {
+                StringEquals: { "aws:SourceArn": trailArn }
+            }
+        }));
+        this.bucket.addToResourcePolicy(new PolicyStatement({
+            sid: "FjallCloudTrailWrite",
+            principals: [cloudTrailPrincipal],
+            actions: ["s3:PutObject"],
+            resources: [this.bucket.arnForObjects(`AWSLogs/${account}/*`)],
+            conditions: {
+                StringEquals: {
+                    "aws:SourceArn": trailArn,
+                    "s3:x-amz-acl": "bucket-owner-full-control"
+                }
+            }
+        }));
+    }
+    /**
+     * Conditioned replacement for the KMS half of the retired grantReadWrite:
+     * `Bucket.grantReadWrite` silently granted the CloudTrail principal
+     * unconditioned Encrypt/Decrypt/ReEncrypt on the CMK because the bucket
+     * carries an encryptionKey. CloudTrail's actual needs are
+     * kms:GenerateDataKey* + kms:DescribeKey (trail-side log encryption,
+     * validated at CreateTrail) plus digest delivery via the bucket's default
+     * SSE-KMS — without these, trail creation fails with
+     * InsufficientEncryptionPolicyException.
+     */
+    addAccountTrailKeyPolicy(trailArn, bucketName) {
+        const { partition } = Stack.of(this);
+        const cloudTrailPrincipal = new ServicePrincipal("cloudtrail.amazonaws.com");
+        this.encryptionKey.key.addToResourcePolicy(new PolicyStatement({
+            sid: "FjallCloudTrailKeyUse",
+            principals: [cloudTrailPrincipal],
+            actions: ["kms:GenerateDataKey*", "kms:DescribeKey"],
+            resources: ["*"],
+            conditions: {
+                StringEquals: { "aws:SourceArn": trailArn }
+            }
+        }));
+        this.encryptionKey.key.addToResourcePolicy(new PolicyStatement({
+            sid: "FjallCloudTrailDigestDelivery",
+            principals: [cloudTrailPrincipal],
+            actions: ["kms:GenerateDataKey*", "kms:Decrypt"],
+            resources: ["*"],
+            conditions: {
+                // Digest files arrive via the bucket's default SSE-KMS. 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}/*`
+                    ]
+                }
+            }
+        }));
+    }
+    /**
+     * 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/messaging/eventbridge.d.ts

@@ -14,8 +14,9 @@ export interface EventBridgeBusProps {
     /** Override the default description ("EventBus <appName> — Fjall app event bus"). */
     description?: string;
     /**
-     * Removal policy. Default resolves via the `env()` helper (production →
-     * RETAIN; non-prod → DESTROY) — D17 explicitly rejects `process.env.NODE_ENV`
+     * Removal policy. Default resolves via `envAwareRemovalPolicyDefault()`
+     * (production → RETAIN; other recognised stages → DESTROY; unrecognised
+     * values fail synth) — D17 explicitly rejects `process.env.NODE_ENV`
      * because it is not set during CDK synth in Fjall's deployment paths.
      * Buses are recreatable in non-prod; production keeps history.
      */

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

@@ -1,7 +1,7 @@
 import { Construct } from "constructs";
 import { CfnOutput } from "aws-cdk-lib";
 import { EventBus } from "aws-cdk-lib/aws-events";
-import { env } from "../../../utils/env.js";
+import { envAwareRemovalPolicyDefault } from "../../../utils/removalPolicy.js";
 import { toRemovalPolicy } from "./utils.js";
 export class EventBridgeBus extends Construct {
     id;
@@ -17,7 +17,7 @@ export class EventBridgeBus extends Construct {
             (props.appName
                 ? `EventBus ${props.appName} — Fjall app event bus`
                 : undefined);
-        const removalPolicyValue = props.removalPolicy ?? env({ default: "DESTROY", production: "RETAIN" });
+        const removalPolicyValue = props.removalPolicy ?? envAwareRemovalPolicyDefault();
         const ownedBus = new EventBus(this, `${id}EventBus`, {
             eventBusName: props.eventBusName,
             description

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

@@ -8,8 +8,11 @@ import { CustomResource } from "../utilities/customResource.js";
 import getAccountId from "../../../utils/getAccountId.js";
 import { accountConstructKey, findAccountNameCollision } from "../../../utils/capitaliseString.js";
 import { FjallLogger } from "../../../utils/validationLogger.js";
+import { formatIpamPairTagValue, IPAM_OPERATIONS_POOL_TAG_KEY } from "@fjall/util/aws";
 const IPAM_TAGS = {
-    OPERATIONS_POOL: "fjall:operations:pool",
+    // Shared with the deploy-core readiness probe, which matches pools by this
+    // key + the pair value format — see @fjall/util/aws ipamTags.
+    OPERATIONS_POOL: IPAM_OPERATIONS_POOL_TAG_KEY,
     COST_ALLOCATION_ENVIRONMENT: "fjall:costAllocation:environment",
     COST_ALLOCATION_ACCOUNT_NAME: "fjall:costAllocation:accountName"
 };
@@ -134,14 +137,14 @@ export class IpamPool extends Construct {
                     allocationResourceTags: [
                         {
                             key: IPAM_TAGS.OPERATIONS_POOL,
-                            value: `${accountId}-${region}`
+                            value: formatIpamPairTagValue(accountId, region)
                         }
                     ],
                     autoImport: true,
                     tags: [
                         {
                             key: IPAM_TAGS.OPERATIONS_POOL,
-                            value: `${accountId}-${region}`
+                            value: formatIpamPairTagValue(accountId, region)
                         },
                         {
                             key: IPAM_TAGS.COST_ALLOCATION_ACCOUNT_NAME,

package/dist/lib/resources/aws/networking/serviceDiscovery.d.ts

@@ -18,9 +18,10 @@ export interface ServiceDiscoveryNamespaceProps {
     /** Override the default description (`"ServiceDiscovery <name> — Fjall private DNS namespace"`). */
     description?: string;
     /**
-     * Removal policy. Default resolves via the `env()` helper (production →
-     * RETAIN; non-prod → DESTROY) — matches the convention codified in D17 of
-     * the EventBridge promotion design. NODE_ENV is intentionally NOT consulted
+     * Removal policy. Default resolves via `envAwareRemovalPolicyDefault()`
+     * (production → RETAIN; other recognised stages → DESTROY; unrecognised
+     * values fail synth) — matches the convention codified in D17 of the
+     * EventBridge promotion design. NODE_ENV is intentionally NOT consulted
      * because it is unset during CDK synth in Fjall's deployment paths.
      */
     removalPolicy?: "DESTROY" | "RETAIN";

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

@@ -1,8 +1,7 @@
 import { Construct } from "constructs";
 import { CfnOutput, Duration } from "aws-cdk-lib";
 import { PrivateDnsNamespace, DnsRecordType } from "aws-cdk-lib/aws-servicediscovery";
-import { env } from "../../../utils/env.js";
-import { toRemovalPolicy } from "../../../utils/removalPolicy.js";
+import { envAwareRemovalPolicyDefault, toRemovalPolicy } from "../../../utils/removalPolicy.js";
 export class ServiceDiscoveryNamespace extends Construct {
     id;
     #namespace;
@@ -12,7 +11,7 @@ export class ServiceDiscoveryNamespace extends Construct {
         this.id = id;
         const description = props.description ??
             `ServiceDiscovery ${props.name} — Fjall private DNS namespace`;
-        const removalPolicyValue = props.removalPolicy ?? env({ default: "DESTROY", production: "RETAIN" });
+        const removalPolicyValue = props.removalPolicy ?? envAwareRemovalPolicyDefault();
         const namespace = new PrivateDnsNamespace(this, `${id}Namespace`, {
             vpc: props.vpc,
             name: props.name,

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

@@ -1,10 +1,18 @@
 import { Bucket, type BucketProps } from "aws-cdk-lib/aws-s3";
 import { type Construct } from "constructs";
 import { type BackupTier } from "../../../utils/backupTierMapping.js";
+export { SDK_PRE_EMPTY_TAG_KEY } from "@fjall/util/aws";
 export interface WebsiteHostingConfig {
     readonly indexDocument: string;
     readonly errorDocument?: string;
 }
+/**
+ * Props for {@link S3Bucket}.
+ *
+ * `autoDeleteObjects` is accepted for source compatibility but always
+ * overridden to `false` (ADR D4.3) — passing `true` raises a synth-time
+ * warning rather than a compile error so older scaffolds keep building.
+ */
 export interface S3BucketProps extends BucketProps {
     backupVaultTier?: BackupTier;
     publicReadAccess?: boolean;

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

@@ -1,7 +1,10 @@
-import { CfnOutput, Duration, RemovalPolicy } from "aws-cdk-lib";
+import { SDK_PRE_EMPTY_TAG_KEY } from "@fjall/util/aws";
+import { Annotations, CfnOutput, Duration, RemovalPolicy, Tags } from "aws-cdk-lib";
 import { BlockPublicAccess, Bucket } from "aws-cdk-lib/aws-s3";
 import { RegionInfo } from "aws-cdk-lib/region-info";
 import { toPascalCase } from "../../../utils/capitaliseString.js";
+import { envAwareRemovalPolicyDefault, toRemovalPolicy } from "../../../utils/removalPolicy.js";
+export { SDK_PRE_EMPTY_TAG_KEY } from "@fjall/util/aws";
 function shouldAutoVersion(tier) {
     return tier === "resilient" || tier === "enterprise";
 }
@@ -10,13 +13,16 @@ export class S3Bucket extends Bucket {
     constructor(scope, id, props = {}) {
         const { websiteHosting, backupVaultTier, ...cdkProps } = props;
         const isPublic = props.publicReadAccess === true || websiteHosting !== undefined;
-        const isRetained = props.removalPolicy === RemovalPolicy.RETAIN;
         const versioned = props.versioned ?? shouldAutoVersion(backupVaultTier);
+        const removalPolicy = props.removalPolicy ?? toRemovalPolicy(envAwareRemovalPolicyDefault());
         super(scope, id, {
             ...cdkProps,
             enforceSSL: true,
-            autoDeleteObjects: !isRetained,
-            removalPolicy: props.removalPolicy ?? RemovalPolicy.DESTROY,
+            // autoDeleteObjects retired (ADR D4.3): the CDK custom resource's deny
+            // policy is the quarantine mechanism — destroy-time emptying is done
+            // SDK-side by deploy-core's pre-empty pass, keyed off the marker tag.
+            autoDeleteObjects: false,
+            removalPolicy,
             publicReadAccess: isPublic,
             ...(isPublic && {
                 blockPublicAccess: new BlockPublicAccess({
@@ -36,6 +42,15 @@ export class S3Bucket extends Bucket {
                 : props.lifecycleRules
         });
         this.backupVaultTier = backupVaultTier;
+        if (props.autoDeleteObjects === true) {
+            Annotations.of(this).addWarningV2("@fjall/components-infrastructure:s3:autoDeleteObjectsIgnored", "autoDeleteObjects: true is ignored — the CDK auto-delete custom " +
+                "resource is retired (ADR D4.3). DESTROY buckets are emptied " +
+                "SDK-side by deploy-core's pre-empty pass via the " +
+                `${SDK_PRE_EMPTY_TAG_KEY} marker tag. Remove the prop.`);
+        }
+        if (removalPolicy === RemovalPolicy.DESTROY) {
+            Tags.of(this).add(SDK_PRE_EMPTY_TAG_KEY, "true");
+        }
         if (websiteHosting) {
             const safeBucket = toPascalCase((props.bucketName ?? id).replace(/[^A-Za-z0-9-]/g, ""));
             new CfnOutput(this, `${safeBucket}WebsiteEndpoint`, {

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

@@ -16,6 +16,12 @@
 type EnvConfig<T> = {
     default: T;
 } & Partial<Record<string, T>>;
+/**
+ * Sentinel returned by `getEnvironment()` when no environment signal exists.
+ * Consumers that need to distinguish "no signal" from "unrecognised value"
+ * (e.g. `envAwareRemovalPolicyDefault()`) compare against this.
+ */
+export declare const UNKNOWN_ENVIRONMENT = "unknown";
 /**
  * Resolve the current deployment environment without App dependency.
  *
@@ -26,8 +32,21 @@ 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;
+/**
+ * True when the environment came from an explicit operator signal
+ * (`ENVIRONMENT` env var or `-c environment=`) rather than account-lookup
+ * inference or the no-signal fallback. Lets consumers distinguish an
+ * explicitly-supplied literal "unknown" from the `UNKNOWN_ENVIRONMENT`
+ * sentinel meaning "no signal at all".
+ */
+export declare function hasExplicitEnvironmentSignal(): boolean;
 /**
  * Resolve an environment-specific value at CDK synth time.
  *

package/dist/lib/utils/env.js

@@ -1,5 +1,12 @@
-import { parseOrgConfig } from "./orgConfigParser.js";
+import { CDK_CONTEXT_KEYS } from "./cdkContext.js";
+import { parseOrgConfig, resolveSynthEnvironment } from "./orgConfigParser.js";
 import { FjallLogger } from "./validationLogger.js";
+/**
+ * Sentinel returned by `getEnvironment()` when no environment signal exists.
+ * Consumers that need to distinguish "no signal" from "unrecognised value"
+ * (e.g. `envAwareRemovalPolicyDefault()`) compare against this.
+ */
+export const UNKNOWN_ENVIRONMENT = "unknown";
 let cachedEnvironment;
 /**
  * Resolve the current deployment environment without App dependency.
@@ -11,6 +18,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) {
@@ -48,9 +60,23 @@ export function getEnvironment() {
     // 5. Fallback
     FjallLogger.warn("[fjall] Could not determine environment. " +
         "Set ENVIRONMENT env var or pass -c environment=<value>.");
-    cachedEnvironment = "unknown";
+    cachedEnvironment = UNKNOWN_ENVIRONMENT;
     return cachedEnvironment;
 }
+/**
+ * True when the environment came from an explicit operator signal
+ * (`ENVIRONMENT` env var or `-c environment=`) rather than account-lookup
+ * inference or the no-signal fallback. Lets consumers distinguish an
+ * explicitly-supplied literal "unknown" from the `UNKNOWN_ENVIRONMENT`
+ * sentinel meaning "no signal at all".
+ */
+export function hasExplicitEnvironmentSignal() {
+    const envVar = process.env.ENVIRONMENT;
+    if (envVar !== undefined && envVar !== "")
+        return true;
+    const ctxValue = parseContextArg("environment");
+    return ctxValue !== undefined && ctxValue !== "";
+}
 /**
  * Resolve an environment-specific value at CDK synth time.
  *
@@ -92,19 +118,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;