@fjall/components-infrastructure 29.0.0 → 31.0.0

package/dist/lib/app.d.ts

@@ -55,7 +55,10 @@ export interface IAppOptions {
     /**
      * Backup configuration for automatic AWS Backup enrolment.
      * - Object with tier: Tags all resources with `fjall:disasterRecovery:tier`
-     * - false: Explicitly disabled (no backup tag)
+     *   and sets the app backup tier that resource defaults derive from — S3
+     *   buckets version by default at `resilient`/`enterprise`; a per-bucket
+     *   `backupVaultTier` overrides the tier for that bucket.
+     * - false: Explicitly disabled (no backup tag, no tier-derived defaults)
      */
     backup?: {
         tier: BackupTier;
@@ -107,14 +110,24 @@ export declare class App extends CdkApp {
     private bastion?;
     private networkDisabled;
     private globalTags;
+    private backupTier?;
+    private backupTierObserved;
     private aspectApplied;
     private resourceInventory?;
     private manifestCollector;
     private constructor();
-    private applyBackupTag;
+    private applyBackupTier;
     private initialiseTunnel;
     private initialiseNetwork;
     getName(): string;
+    /**
+     * The app-level backup tier from `backup: { tier }`, or undefined when no
+     * backup is declared. Factories thread it to resources whose defaults derive
+     * from it (S3 versioning); a per-resource `backupVaultTier` overrides it.
+     * Reading it pins the tier: a `backup` applied on a later `getApp` call
+     * throws, so no resource can carry the tier's tag without its defaults.
+     */
+    getBackupTier(): BackupTier | undefined;
     static getApp(name?: string, options?: IAppOptions): App;
     static getInstance(name?: string, options?: IAppOptions): App;
     /**
@@ -345,10 +358,10 @@ export declare class App extends CdkApp {
      * Add a storage resource (S3) to the default storage stack using the factory pattern.
      *
      * @example
-     * // Private bucket (default)
-     * const assets = app.addStorage(StorageFactory.build("Assets", {
-     *   versioned: true
-     * }));
+     * // Private bucket (default). Versioning follows the app backup tier
+     * // (`backup: { tier }` — on at resilient/enterprise); `versioned` or a
+     * // per-bucket `backupVaultTier` overrides it.
+     * const assets = app.addStorage(StorageFactory.build("Assets"));
      *
      * @example
      * // Website bucket

package/dist/lib/app.js

@@ -48,6 +48,8 @@ export class App extends CdkApp {
     bastion;
     networkDisabled = false;
     globalTags = {};
+    backupTier;
+    backupTierObserved = false;
     aspectApplied = false;
     resourceInventory;
     manifestCollector;
@@ -64,9 +66,9 @@ export class App extends CdkApp {
         // Initialise manifest collector for build-time service discovery
         this.manifestCollector = getManifestCollector(this.name);
         this.initialiseStandardTags();
-        // Apply backup tier tag if configured
+        // Apply backup tier if configured
         if (options?.backup && typeof options.backup === "object") {
-            this.applyBackupTag(options.backup.tier);
+            this.applyBackupTier(options.backup.tier);
         }
         // Initialise network immediately if configured
         if (options?.network === false) {
@@ -83,7 +85,14 @@ export class App extends CdkApp {
             this.eventBusOverride = options.eventBus;
         }
     }
-    applyBackupTag(tier) {
+    applyBackupTier(tier) {
+        if (this.backupTierObserved) {
+            throw new Error(`Backup tier "${tier}" applied after a resource already resolved the app's tier: ` +
+                `that resource would carry the tier's disaster-recovery tag without its versioning default. ` +
+                `Pass \`backup\` on the first App.getApp("${this.name}") call, before addStorage(), ` +
+                `addBuildkite() or a Payload pattern.`);
+        }
+        this.backupTier = tier;
         this.globalTags[BACKUP_TIER_TAG_KEY] = BACKUP_TIER_TAG_MAP[tier];
     }
     initialiseTunnel(config) {
@@ -109,6 +118,17 @@ export class App extends CdkApp {
     getName() {
         return this.name;
     }
+    /**
+     * The app-level backup tier from `backup: { tier }`, or undefined when no
+     * backup is declared. Factories thread it to resources whose defaults derive
+     * from it (S3 versioning); a per-resource `backupVaultTier` overrides it.
+     * Reading it pins the tier: a `backup` applied on a later `getApp` call
+     * throws, so no resource can carry the tier's tag without its defaults.
+     */
+    getBackupTier() {
+        this.backupTierObserved = true;
+        return this.backupTier;
+    }
     static getApp(name, options) {
         return App.getInstance(name, options);
     }
@@ -145,11 +165,11 @@ export class App extends CdkApp {
                 !App.instance.networkDisabled) {
                 App.instance.initialiseNetwork(options.network);
             }
-            // Apply backup tag if configured and not already set
+            // Apply backup tier if configured and not already set
             if (options?.backup &&
                 typeof options.backup === "object" &&
-                !App.instance.globalTags[BACKUP_TIER_TAG_KEY]) {
-                App.instance.applyBackupTag(options.backup.tier);
+                App.instance.backupTier === undefined) {
+                App.instance.applyBackupTier(options.backup.tier);
             }
             // Initialise tunnel if configured and not already created
             if (options?.tunnel && !App.instance.bastion) {
@@ -557,10 +577,10 @@ export class App extends CdkApp {
      * Add a storage resource (S3) to the default storage stack using the factory pattern.
      *
      * @example
-     * // Private bucket (default)
-     * const assets = app.addStorage(StorageFactory.build("Assets", {
-     *   versioned: true
-     * }));
+     * // Private bucket (default). Versioning follows the app backup tier
+     * // (`backup: { tier }` — on at resilient/enterprise); `versioned` or a
+     * // per-bucket `backupVaultTier` overrides it.
+     * const assets = app.addStorage(StorageFactory.build("Assets"));
      *
      * @example
      * // Website bucket

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

@@ -0,0 +1,124 @@
+import { type BoundaryStatement, type GovernancePreset } from "@fjall/generator";
+import { Construct } from "constructs";
+/**
+ * The deploy-role permissions boundary is an ACCOUNT-GLOBAL IAM singleton, not
+ * a stack-owned resource. Once `cdk bootstrap --custom-permissions-boundary`
+ * caps a `cfn-exec-role` with it, the policy has a referrer OUTSIDE every
+ * stack: a native `AWS::IAM::ManagedPolicy` can then never be deleted
+ * (`DeleteConflict` → DELETE_FAILED for the account stack AND the customer's
+ * Quick-Create stack), while `DeletionPolicy: Retain` breaks the next
+ * re-connect (`CreatePolicy` → `EntityAlreadyExists`). This custom resource is
+ * the adopt-or-create shape the OIDC provider already uses: it publishes the
+ * SSoT tier document by name, converges an existing policy in place
+ * (`CreatePolicyVersion` + `SetAsDefault`), and ACKs Delete without touching
+ * the policy — end-of-life removal is deploy-core's reference-counted sweep
+ * (`deleteDeployBoundaryIfUnreferenced`) once no role is bounded by it.
+ *
+ * The writer is a confused deputy by construction — CloudFormation invokes it
+ * under whatever principal drives the stack, including the bounded deploy
+ * role — so it trusts NOTHING in the request: it publishes only a document
+ * whose canonical digest is one of the SSoT tiers, and it never drops a Deny
+ * ACTION the live document carries (the tiers are cumulative, so a tier
+ * upgrade is self-service and a downgrade is an administrator action,
+ * matching the opt-out semantics). The ratchet compares Deny action sets, not
+ * statement scope: a default hand-published outside fjall that is tighter
+ * only by Resource or Condition converges back to the SSoT tier on the next
+ * deploy — the tier, not the hand edit, is the contract. Its execution role
+ * can act on the one policy ARN only.
+ */
+export declare const DEPLOY_BOUNDARY_RESOURCE_TYPE = "Custom::FjallDeployBoundary";
+/**
+ * Execution-role description of the singleton's writer Lambda. The role is
+ * deliberately NOT bounded: a writer capped by the boundary it maintains could
+ * never re-version it (FjallDenyBoundaryPolicyTamper denies exactly that).
+ */
+export declare const DEPLOY_BOUNDARY_WRITER_ROLE_DESCRIPTION = "Fjall deploy boundary writer";
+/**
+ * Set at `CreatePolicy` only — IAM descriptions are immutable — and
+ * byte-identical in the Quick-Create twin so an adopted policy reads the same
+ * whichever renderer created it.
+ */
+export declare const DEPLOY_BOUNDARY_DESCRIPTION = "Fjall deploy-role permissions boundary - hard cap on the OIDC deploy role and the CDK cfn-exec-role";
+/** Every IAM action the writer holds — on the one boundary policy ARN, never `*`. */
+export declare const DEPLOY_BOUNDARY_WRITER_ACTIONS: string[];
+/** CloudFormation's inline-code ceiling (`ZipFile` / `Code.fromInline`). */
+export declare const DEPLOY_BOUNDARY_CODE_LIMIT_BYTES = 4096;
+/**
+ * Writer Lambda budget — one converge is at most eight IAM calls. Coupled
+ * with the Quick-Create twin's `Timeout`; the template parity test pins both.
+ */
+export declare const DEPLOY_BOUNDARY_WRITER_TIMEOUT_SECONDS = 60;
+/**
+ * CloudFormation's own wait for the writer's response — a lost response must
+ * fail the stack in minutes, not the default hour. Coupled with the twin's
+ * `ServiceTimeout`; the template parity test pins both.
+ */
+export declare const DEPLOY_BOUNDARY_SERVICE_TIMEOUT_SECONDS = 300;
+export interface DeployBoundaryDocument {
+    Version: "2012-10-17";
+    Statement: BoundaryStatement[];
+}
+export interface PolicyTag {
+    Key: string;
+    Value: string;
+}
+export declare function deployBoundaryDocument(tier: GovernancePreset): DeployBoundaryDocument;
+/**
+ * Mirrors the Quick-Create twin's per-resource Tags block (the CDK account
+ * stack tags natively-rendered resources itself; a policy the writer creates
+ * through the SDK must carry them explicitly).
+ */
+export declare function deployBoundaryPolicyTags(fjallOrgId: string): PolicyTag[];
+export declare function boundaryDocumentDigest(document: unknown): string;
+/**
+ * The allow-list the writer embeds. A tier added to `GOVERNANCE_PRESETS`
+ * without a digest here fails typecheck (`satisfies Record<GovernancePreset>`),
+ * and the Quick-Create twin pins these literals byte-for-byte.
+ */
+export declare const SECURITY_TIER_DIGESTS: {
+    foundation: string;
+    compliance: string;
+    hardened: string;
+};
+/**
+ * Handler algorithm shared VERBATIM by both renderers (the Quick-Create twin
+ * embeds this exact text inside its own cfn-response wrapper; the template
+ * parity test pins the bytes, and both wrappers must stay under
+ * `DEPLOY_BOUNDARY_CODE_LIMIT_BYTES`, which is why the algorithm carries no
+ * comments of its own). Node 24 runtime — `@aws-sdk/client-iam` and `crypto`
+ * come from the Lambda runtime, nothing is bundled.
+ *
+ * `ALLOWED` is the digest allow-list (SSoT tiers only); `denied` is the
+ * loosening ratchet — the requested document must deny every ACTION the live
+ * one denies (the tiers are cumulative, so a tier upgrade always passes and a
+ * downgrade always fails). It compares action sets only: a live default that
+ * is tighter by Resource, Condition or `NotAction` converges back to the tier.
+ * The live no-op check runs BEFORE the tier gate: a CloudFormation rollback
+ * re-presents the previous release's document, whose digest a newer writer no
+ * longer allow-lists — when it already IS the live default nothing is
+ * published, so the confused-deputy guard loses nothing and the rollback
+ * lands. The create race is retried once (`retried`), so IAM read-after-write
+ * lag surfaces as a failure instead of spinning to the Lambda timeout.
+ * Five is IAM's per-policy version ceiling: at five, the oldest non-default
+ * version is dropped before the new default is published.
+ * `GetPolicyVersion` returns the document URL-encoded, hence the decode.
+ */
+export declare const DEPLOY_BOUNDARY_HANDLER_CORE: string;
+/**
+ * CDK rendering — the provider framework turns a resolved object into the
+ * SUCCESS response and a thrown error into FAILED with the message as Reason.
+ * Delete is an ACK: the policy may still cap cfn-exec roles the stack never
+ * owned, and the next connect adopts it.
+ */
+export declare const DEPLOY_BOUNDARY_HANDLER: string;
+export interface DeployBoundarySingletonProps {
+    fjallOrgId: string;
+    /** Governance tier selecting the boundary CONTENT (`SECURITY_TIER_TO_BOUNDARY`). */
+    tier: GovernancePreset;
+}
+export declare class DeployBoundarySingleton extends Construct {
+    readonly policyName: string;
+    /** `Fn::GetAtt` on the writer — referencing it orders the role after the policy. */
+    readonly policyArn: string;
+    constructor(scope: Construct, id: string, props: DeployBoundarySingletonProps);
+}

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

@@ -0,0 +1,257 @@
+import { SECURITY_TIER_TO_BOUNDARY, deployBoundaryName } from "@fjall/generator";
+import { Aws, Duration } from "aws-cdk-lib";
+import * as iam from "aws-cdk-lib/aws-iam";
+import { Runtime } from "aws-cdk-lib/aws-lambda";
+import { Construct } from "constructs";
+import { createHash } from "node:crypto";
+import { CustomResource } from "../../resources/aws/utilities/customResource.js";
+/**
+ * The deploy-role permissions boundary is an ACCOUNT-GLOBAL IAM singleton, not
+ * a stack-owned resource. Once `cdk bootstrap --custom-permissions-boundary`
+ * caps a `cfn-exec-role` with it, the policy has a referrer OUTSIDE every
+ * stack: a native `AWS::IAM::ManagedPolicy` can then never be deleted
+ * (`DeleteConflict` → DELETE_FAILED for the account stack AND the customer's
+ * Quick-Create stack), while `DeletionPolicy: Retain` breaks the next
+ * re-connect (`CreatePolicy` → `EntityAlreadyExists`). This custom resource is
+ * the adopt-or-create shape the OIDC provider already uses: it publishes the
+ * SSoT tier document by name, converges an existing policy in place
+ * (`CreatePolicyVersion` + `SetAsDefault`), and ACKs Delete without touching
+ * the policy — end-of-life removal is deploy-core's reference-counted sweep
+ * (`deleteDeployBoundaryIfUnreferenced`) once no role is bounded by it.
+ *
+ * The writer is a confused deputy by construction — CloudFormation invokes it
+ * under whatever principal drives the stack, including the bounded deploy
+ * role — so it trusts NOTHING in the request: it publishes only a document
+ * whose canonical digest is one of the SSoT tiers, and it never drops a Deny
+ * ACTION the live document carries (the tiers are cumulative, so a tier
+ * upgrade is self-service and a downgrade is an administrator action,
+ * matching the opt-out semantics). The ratchet compares Deny action sets, not
+ * statement scope: a default hand-published outside fjall that is tighter
+ * only by Resource or Condition converges back to the SSoT tier on the next
+ * deploy — the tier, not the hand edit, is the contract. Its execution role
+ * can act on the one policy ARN only.
+ */
+export const DEPLOY_BOUNDARY_RESOURCE_TYPE = "Custom::FjallDeployBoundary";
+/**
+ * Execution-role description of the singleton's writer Lambda. The role is
+ * deliberately NOT bounded: a writer capped by the boundary it maintains could
+ * never re-version it (FjallDenyBoundaryPolicyTamper denies exactly that).
+ */
+export const DEPLOY_BOUNDARY_WRITER_ROLE_DESCRIPTION = "Fjall deploy boundary writer";
+/**
+ * Set at `CreatePolicy` only — IAM descriptions are immutable — and
+ * byte-identical in the Quick-Create twin so an adopted policy reads the same
+ * whichever renderer created it.
+ */
+export const DEPLOY_BOUNDARY_DESCRIPTION = "Fjall deploy-role permissions boundary - hard cap on the OIDC deploy role and the CDK cfn-exec-role";
+/** Every IAM action the writer holds — on the one boundary policy ARN, never `*`. */
+export const DEPLOY_BOUNDARY_WRITER_ACTIONS = [
+    "iam:GetPolicy",
+    "iam:GetPolicyVersion",
+    "iam:ListPolicyVersions",
+    "iam:CreatePolicy",
+    "iam:CreatePolicyVersion",
+    "iam:DeletePolicyVersion",
+    "iam:TagPolicy"
+];
+/** CloudFormation's inline-code ceiling (`ZipFile` / `Code.fromInline`). */
+export const DEPLOY_BOUNDARY_CODE_LIMIT_BYTES = 4096;
+/**
+ * Writer Lambda budget — one converge is at most eight IAM calls. Coupled
+ * with the Quick-Create twin's `Timeout`; the template parity test pins both.
+ */
+export const DEPLOY_BOUNDARY_WRITER_TIMEOUT_SECONDS = 60;
+/**
+ * CloudFormation's own wait for the writer's response — a lost response must
+ * fail the stack in minutes, not the default hour. Coupled with the twin's
+ * `ServiceTimeout`; the template parity test pins both.
+ */
+export const DEPLOY_BOUNDARY_SERVICE_TIMEOUT_SECONDS = 300;
+export function deployBoundaryDocument(tier) {
+    return { Version: "2012-10-17", Statement: SECURITY_TIER_TO_BOUNDARY[tier] };
+}
+/**
+ * Mirrors the Quick-Create twin's per-resource Tags block (the CDK account
+ * stack tags natively-rendered resources itself; a policy the writer creates
+ * through the SDK must carry them explicitly).
+ */
+export function deployBoundaryPolicyTags(fjallOrgId) {
+    return [
+        { Key: "fjall:managed", Value: "true" },
+        { Key: "fjall:org-id", Value: fjallOrgId },
+        { Key: "fjall:costAllocation:owner", Value: fjallOrgId },
+        { Key: "fjall:costAllocation:service", Value: "OidcConnector" },
+        { Key: "fjall:costAllocation:environment", Value: "root" }
+    ];
+}
+/**
+ * Canonical form for digesting: keys sorted recursively, a one-element array
+ * collapsed to its scalar (IAM treats `Action: ["x"]` and `Action: "x"` as
+ * the same document, and returns whichever spelling it stored). MUST stay in
+ * lockstep with `canonical` inside the handler — the handler-execution tests
+ * pin both against the same fixtures.
+ */
+function canonicalise(value) {
+    if (Array.isArray(value)) {
+        return value.length === 1
+            ? canonicalise(value[0])
+            : value.map((entry) => canonicalise(entry));
+    }
+    if (value !== null && typeof value === "object") {
+        const record = value;
+        const sorted = {};
+        for (const key of Object.keys(record).sort()) {
+            sorted[key] = canonicalise(record[key]);
+        }
+        return sorted;
+    }
+    return value;
+}
+export function boundaryDocumentDigest(document) {
+    return createHash("sha256")
+        .update(JSON.stringify(canonicalise(document)))
+        .digest("hex");
+}
+/**
+ * The allow-list the writer embeds. A tier added to `GOVERNANCE_PRESETS`
+ * without a digest here fails typecheck (`satisfies Record<GovernancePreset>`),
+ * and the Quick-Create twin pins these literals byte-for-byte.
+ */
+export const SECURITY_TIER_DIGESTS = {
+    foundation: boundaryDocumentDigest(deployBoundaryDocument("foundation")),
+    compliance: boundaryDocumentDigest(deployBoundaryDocument("compliance")),
+    hardened: boundaryDocumentDigest(deployBoundaryDocument("hardened"))
+};
+const ALLOWED_DIGEST_LITERALS = Object.values(SECURITY_TIER_DIGESTS)
+    .map((digest) => `'${digest}'`)
+    .join(", ");
+/**
+ * Handler algorithm shared VERBATIM by both renderers (the Quick-Create twin
+ * embeds this exact text inside its own cfn-response wrapper; the template
+ * parity test pins the bytes, and both wrappers must stay under
+ * `DEPLOY_BOUNDARY_CODE_LIMIT_BYTES`, which is why the algorithm carries no
+ * comments of its own). Node 24 runtime — `@aws-sdk/client-iam` and `crypto`
+ * come from the Lambda runtime, nothing is bundled.
+ *
+ * `ALLOWED` is the digest allow-list (SSoT tiers only); `denied` is the
+ * loosening ratchet — the requested document must deny every ACTION the live
+ * one denies (the tiers are cumulative, so a tier upgrade always passes and a
+ * downgrade always fails). It compares action sets only: a live default that
+ * is tighter by Resource, Condition or `NotAction` converges back to the tier.
+ * The live no-op check runs BEFORE the tier gate: a CloudFormation rollback
+ * re-presents the previous release's document, whose digest a newer writer no
+ * longer allow-lists — when it already IS the live default nothing is
+ * published, so the confused-deputy guard loses nothing and the rollback
+ * lands. The create race is retried once (`retried`), so IAM read-after-write
+ * lag surfaces as a failure instead of spinning to the Lambda timeout.
+ * Five is IAM's per-policy version ceiling: at five, the oldest non-default
+ * version is dropped before the new default is published.
+ * `GetPolicyVersion` returns the document URL-encoded, hence the decode.
+ */
+export const DEPLOY_BOUNDARY_HANDLER_CORE = `const { IAMClient, GetPolicyCommand, GetPolicyVersionCommand, CreatePolicyCommand, CreatePolicyVersionCommand, ListPolicyVersionsCommand, DeletePolicyVersionCommand } = require('@aws-sdk/client-iam');
+const { createHash } = require('crypto');
+const ALLOWED = [${ALLOWED_DIGEST_LITERALS}];
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.length === 1 ? canonical(value[0]) : value.map(canonical);
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const key of Object.keys(value).sort()) out[key] = canonical(value[key]);
+    return out;
+  }
+  return value;
+}
+const digest = (doc) => createHash('sha256').update(JSON.stringify(canonical(doc))).digest('hex');
+const denied = (doc) => new Set([].concat(doc.Statement).filter((s) => s.Effect === 'Deny').flatMap((s) => [].concat(s.Action || [])));
+const reason = (err) => String(err && err.name ? err.name + ': ' + err.message : err).slice(0, 512);
+
+async function converge(iam, props, retried) {
+  const doc = props.PolicyDocument;
+  const wanted = digest(doc);
+  const arn = props.PolicyArn;
+  const body = JSON.stringify(doc);
+  let policy;
+  try {
+    policy = (await iam.send(new GetPolicyCommand({ PolicyArn: arn }))).Policy;
+  } catch (err) {
+    if (err.name !== 'NoSuchEntityException') throw err;
+  }
+  const live = policy && JSON.parse(decodeURIComponent((await iam.send(new GetPolicyVersionCommand({ PolicyArn: arn, VersionId: policy.DefaultVersionId }))).PolicyVersion.Document));
+  if (live && digest(live) === wanted) return arn;
+  if (!ALLOWED.includes(wanted)) throw new Error('PolicyDocument is not a Fjall boundary tier (digest ' + wanted + ')');
+  if (!live) {
+    try {
+      await iam.send(new CreatePolicyCommand({ PolicyName: props.PolicyName, Description: props.Description, PolicyDocument: body, Tags: props.PolicyTags }));
+      return arn;
+    } catch (err) {
+      if (err.name !== 'EntityAlreadyExistsException' || retried) throw err;
+      return converge(iam, props, true);
+    }
+  }
+  const keep = denied(doc);
+  const lost = [...denied(live)].find((action) => !keep.has(action));
+  if (lost) throw new Error('Refusing to loosen the live boundary (it denies ' + lost + '). Loosening is an administrator action: iam create-policy-version --set-as-default, then retry.');
+  const versions = (await iam.send(new ListPolicyVersionsCommand({ PolicyArn: arn }))).Versions || [];
+  if (versions.length >= 5) {
+    const oldest = versions.filter((v) => !v.IsDefaultVersion).sort((a, b) => new Date(a.CreateDate) - new Date(b.CreateDate))[0];
+    await iam.send(new DeletePolicyVersionCommand({ PolicyArn: arn, VersionId: oldest.VersionId }));
+  }
+  await iam.send(new CreatePolicyVersionCommand({ PolicyArn: arn, PolicyDocument: body, SetAsDefault: true }));
+  return arn;
+}
+`;
+/**
+ * CDK rendering — the provider framework turns a resolved object into the
+ * SUCCESS response and a thrown error into FAILED with the message as Reason.
+ * Delete is an ACK: the policy may still cap cfn-exec roles the stack never
+ * owned, and the next connect adopts it.
+ */
+export const DEPLOY_BOUNDARY_HANDLER = `${DEPLOY_BOUNDARY_HANDLER_CORE}
+exports.handler = async (event) => {
+  const props = event.ResourceProperties;
+  const physicalId = event.PhysicalResourceId || props.PolicyArn;
+  if (event.RequestType === 'Delete') return { PhysicalResourceId: physicalId };
+  try {
+    const arn = await converge(new IAMClient({}), props);
+    return { PhysicalResourceId: arn, Data: { PolicyArn: arn } };
+  } catch (err) {
+    throw new Error(reason(err));
+  }
+};`;
+export class DeployBoundarySingleton extends Construct {
+    policyName;
+    /** `Fn::GetAtt` on the writer — referencing it orders the role after the policy. */
+    policyArn;
+    constructor(scope, id, props) {
+        super(scope, id);
+        this.policyName = deployBoundaryName(props.fjallOrgId);
+        const policyArn = `arn:${Aws.PARTITION}:iam::${Aws.ACCOUNT_ID}:policy/${this.policyName}`;
+        const writer = new CustomResource(this, "Policy", {
+            runtime: Runtime.NODEJS_24_X,
+            timeout: Duration.seconds(DEPLOY_BOUNDARY_WRITER_TIMEOUT_SECONDS),
+            serviceTimeout: Duration.seconds(DEPLOY_BOUNDARY_SERVICE_TIMEOUT_SECONDS),
+            lambdaDescription: "Adopt-or-create the account-global Fjall deploy-role permissions boundary",
+            roleDescription: DEPLOY_BOUNDARY_WRITER_ROLE_DESCRIPTION,
+            resourceType: DEPLOY_BOUNDARY_RESOURCE_TYPE,
+            inlinePolicy: [
+                new iam.PolicyStatement({
+                    effect: iam.Effect.ALLOW,
+                    actions: DEPLOY_BOUNDARY_WRITER_ACTIONS,
+                    resources: [policyArn]
+                })
+            ],
+            inlineCode: DEPLOY_BOUNDARY_HANDLER,
+            // Key order mirrors the Quick-Create twin — the document last, so the
+            // console shows the identity before the ceiling (the template parity
+            // test pins the twin's order).
+            properties: {
+                PolicyName: this.policyName,
+                PolicyArn: policyArn,
+                Description: DEPLOY_BOUNDARY_DESCRIPTION,
+                PolicyTags: deployBoundaryPolicyTags(props.fjallOrgId),
+                PolicyDocument: deployBoundaryDocument(props.tier)
+            }
+        });
+        this.policyArn = writer.resource.getAtt("PolicyArn").toString();
+    }
+}

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

@@ -2,6 +2,7 @@ export * from "./identityCenter.js";
 export * from "./identityCentreConfig.js";
 export * from "./ipam.js";
 export * from "./ecrDefaultImage.js";
+export * from "./deployBoundarySingleton.js";
 export * from "./oidcConnector.js";
 export * from "./platform.js";
 export * from "./accountMonitoringRole.js";

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

@@ -2,6 +2,7 @@ export * from "./identityCenter.js";
 export * from "./identityCentreConfig.js";
 export * from "./ipam.js";
 export * from "./ecrDefaultImage.js";
+export * from "./deployBoundarySingleton.js";
 export * from "./oidcConnector.js";
 export * from "./platform.js";
 export * from "./accountMonitoringRole.js";

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

@@ -5,12 +5,28 @@ export interface OidcConnectorProps {
     fjallOrgId: string;
     /**
      * Governance tier selecting the deploy-role permissions-boundary CONTENT.
-     * When set, a `FjallDeployBoundary${fjallOrgId}` customer-managed policy is
-     * created and attached to the deploy role as its permissions boundary — the
-     * hard cap that survives CDK's assume-role hand-off (unlike a session policy).
-     * Absent ⇒ no boundary (today's behaviour — backward-compatible).
+     * The connector ALWAYS publishes the `FjallDeployBoundary${fjallOrgId}`
+     * customer-managed policy (adopt-or-create — an account-global singleton
+     * shared with the Quick-Create stack and the bootstrapped cfn-exec roles)
+     * and attaches it to the deploy role as its
+     * permissions boundary — the hard cap that survives CDK's assume-role
+     * hand-off (unlike a session policy). Absent ⇒ `DEFAULT_DEPLOY_BOUNDARY_TIER`
+     * (the ceiling the Quick-Create template ships), so a CDK-rendered account
+     * never carries a looser cap than a template-connected one. Set it only to
+     * select a DIFFERENT tier; `deployRoleBoundary: false` is the sole path to
+     * an uncapped role, and combining the two throws at synth.
      */
     securityTier?: GovernancePreset;
+    /**
+     * Opt-out of the deploy-role permissions boundary. `false` renders no
+     * `FjallDeployBoundary${fjallOrgId}` policy and leaves the deploy role
+     * uncapped. Absent or `true` ⇒ the boundary renders at `securityTier` or
+     * the default. Mirrors the Quick-Create template's
+     * `FjallPermissionsBoundary` parameter: both surfaces default ON and opt
+     * OUT, so "no boundary" is always a visible choice in the account's own
+     * infrastructure code, never a consequence of leaving a prop unset.
+     */
+    deployRoleBoundary?: boolean;
     /**
      * Workload STAGE of the connected account (the wire `environment` value —
      * never the account TIER axis). When `"development"`, the connector

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

@@ -1,4 +1,4 @@
-import { DEV_BOUNDARY_POLICY_NAME, DEV_DEPLOY_POLICY_NAME, DEV_PROVISIONER_POLICY_NAME, DEV_SYNC_WRITER_POLICY_NAME, FJALL_OIDC_AUDIENCE, FJALL_OIDC_ISSUER_DOMAIN, FJALL_OIDC_PLACEHOLDER_THUMBPRINT, SECURITY_TIER_TO_BOUNDARY, buildDevBoundaryStatements, buildDevDeployPolicyStatements, buildDevDeployTrustStatements, buildDevProvisionerPolicyStatements, buildDevProvisionerTrustStatements, buildDevSyncWriterPolicyStatements, buildDevSyncWriterTrustStatements, buildNarrowedDeployTrustStatements, deployBoundaryName, devDeployRoleName, devProvisionerRoleName, devSyncWriterRoleName } from "@fjall/generator";
+import { DEFAULT_DEPLOY_BOUNDARY_TIER, DEPLOY_ROLE_PATH, DEV_BOUNDARY_POLICY_NAME, DEV_DEPLOY_POLICY_NAME, DEV_PROVISIONER_POLICY_NAME, DEV_SYNC_WRITER_POLICY_NAME, FJALL_OIDC_AUDIENCE, FJALL_OIDC_ISSUER_DOMAIN, FJALL_OIDC_PLACEHOLDER_THUMBPRINT, buildDevBoundaryStatements, buildDevDeployPolicyStatements, buildDevDeployTrustStatements, buildDevProvisionerPolicyStatements, buildDevProvisionerTrustStatements, buildDevSyncWriterPolicyStatements, buildDevSyncWriterTrustStatements, buildNarrowedDeployTrustStatements, deployRoleName, devDeployRoleName, devProvisionerRoleName, devSyncWriterRoleName } from "@fjall/generator";
 import { Aws, CfnOutput, Duration, Stack } from "aws-cdk-lib";
 import * as iam from "aws-cdk-lib/aws-iam";
 import { Runtime } from "aws-cdk-lib/aws-lambda";
@@ -6,6 +6,7 @@ import { Construct } from "constructs";
 import { ManagedPolicy } from "../../resources/aws/iam/managedPolicy.js";
 import { Role } from "../../resources/aws/iam/role.js";
 import { CustomResource } from "../../resources/aws/utilities/customResource.js";
+import { DeployBoundarySingleton } from "./deployBoundarySingleton.js";
 /**
  * The `https://fjall.io` OIDC provider is an account-global IAM singleton
  * (one per account+URL). Both this construct AND the Quick-Create template can
@@ -67,6 +68,21 @@ function applyTrustDocument(role, statements) {
         Statement: statements
     };
 }
+/**
+ * Default-on: an absent tier resolves to the SSoT default, `deployRoleBoundary:
+ * false` is the only route to no boundary, and naming a tier alongside the
+ * opt-out is a contradiction that fails at synth rather than silently picking
+ * a side.
+ */
+function resolveDeployBoundaryTier(props) {
+    if (props.deployRoleBoundary === false) {
+        if (props.securityTier !== undefined) {
+            throw new Error(`OidcConnector: securityTier "${props.securityTier}" selects the deploy-role boundary content, but deployRoleBoundary: false renders no boundary — remove one of them`);
+        }
+        return undefined;
+    }
+    return props.securityTier ?? DEFAULT_DEPLOY_BOUNDARY_TIER;
+}
 export class OidcConnector extends Construct {
     deployRoleArn;
     constructor(scope, id, props) {
@@ -104,15 +120,16 @@ export class OidcConnector extends Construct {
         const providerArn = providerResource.resource
             .getAtt("ProviderArn")
             .toString();
-        // Permissions boundary (hard cap). Created here — in the account-connection
-        // stack that runs BEFORE any bootstrap/deploy — because
+        // Permissions boundary (hard cap). Published here — in the account-
+        // connection stack that runs BEFORE any bootstrap/deploy — because
         // `cdk bootstrap --custom-permissions-boundary <name>` LOOKS THE POLICY UP
-        // by name; it never creates it. So the policy must exist by name first.
-        const deployBoundary = props.securityTier !== undefined
-            ? new ManagedPolicy(this, "DeployBoundary", {
-                managedPolicyName: deployBoundaryName(props.fjallOrgId),
-                description: "Fjall deploy-role permissions boundary — hard cap on the OIDC deploy role and the CDK cfn-exec-role",
-                statements: SECURITY_TIER_TO_BOUNDARY[props.securityTier].map((statement) => iam.PolicyStatement.fromJson(statement))
+        // by name; it never creates it. Account-global adopt-or-create, not a
+        // stack-owned ManagedPolicy: see DeployBoundarySingleton for why.
+        const boundaryTier = resolveDeployBoundaryTier(props);
+        const deployBoundary = boundaryTier !== undefined
+            ? new DeployBoundarySingleton(this, "DeployBoundary", {
+                fjallOrgId: props.fjallOrgId,
+                tier: boundaryTier
             })
             : undefined;
         // Concrete when env.account is set, a token otherwise — both render. Feeds
@@ -131,8 +148,8 @@ export class OidcConnector extends Construct {
             })
         };
         const deployRole = new Role(this, "DeployRole", {
-            roleName: `FjallDeploy${props.fjallOrgId}`,
-            path: "/fjall/",
+            roleName: deployRoleName(props.fjallOrgId),
+            path: DEPLOY_ROLE_PATH,
             maxSessionDuration: Duration.hours(1),
             // Placeholder — applyTrustDocument below replaces the whole rendered
             // AssumeRolePolicyDocument with the SSoT's G4 condition split.
@@ -141,7 +158,7 @@ export class OidcConnector extends Construct {
                 iam.ManagedPolicy.fromAwsManagedPolicyName("AdministratorAccess")
             ],
             ...(deployBoundary !== undefined && {
-                permissionsBoundary: deployBoundary
+                permissionsBoundary: iam.ManagedPolicy.fromManagedPolicyArn(this, "DeployBoundaryRef", deployBoundary.policyArn)
             })
         });
         applyTrustDocument(deployRole, buildNarrowedDeployTrustStatements(trustParams));

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

@@ -1,10 +1,12 @@
+import { DEPLOY_ROLE_PATH, deployRoleName } from "@fjall/generator";
 import { Construct } from "constructs";
 import { OrganisationPolicy } from "../../resources/aws/organisation/organisationPolicy.js";
 // Path prefix `/fjall/` is load-bearing: without it, a member-account admin
 // could bypass protect-* SCPs by creating a `FjallDeploy*` role at the
-// default path.
+// default path. Derived from the generator SSoT so the exemption, the role the
+// connector renders and the boundary's self-protection name the same role.
 const EXEMPT_ROLE_PATTERNS = [
-    "arn:aws:iam::*:role/fjall/FjallDeploy*",
+    `arn:aws:iam::*:role${DEPLOY_ROLE_PATH}${deployRoleName("*")}`,
     "arn:aws:iam::*:role/OrganizationAccountAccessRole",
     // The account-level S3 Block Public Access manager Lambda re-applies BPA on
     // every deploy; its PutAccountPublicAccessBlock must survive

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

@@ -21,12 +21,30 @@ export interface AccountProps extends StackProps {
      * Governance tier selecting the deploy-role permissions-boundary CONTENT
      * (Phase E, seam 1). Forwarded to the account's `OidcConnector`, which
      * creates `FjallDeployBoundary${fjallOrgId}` from
-     * `SECURITY_TIER_TO_BOUNDARY[securityTier]`. Undefined ⇒ no boundary
-     * (backward-compatible). Sourced from the generated `account/infrastructure.ts`
-     * (the `--security` dial baked in at generation time — the tier is not
-     * persisted anywhere the deploy flow could read it).
+     * `SECURITY_TIER_TO_BOUNDARY[securityTier]`. Undefined ⇒ the boundary still
+     * renders, at `DEFAULT_DEPLOY_BOUNDARY_TIER` (the ceiling the Quick-Create
+     * template ships) — the tier only ever changes WHICH ceiling, never whether
+     * there is one (`deployRoleBoundary: false` does that). Sourced from the
+     * generated `account/infrastructure.ts` (the `--security` dial baked in at
+     * generation time — the tier is not persisted anywhere the deploy flow could
+     * read it).
      */
     securityTier?: GovernancePreset;
+    /**
+     * Opt-out of the deploy-role permissions boundary, forwarded to the
+     * account's `OidcConnector`. `false` renders no boundary policy and an
+     * uncapped FjallDeploy role; absent or `true` ⇒ the boundary renders at
+     * `securityTier` or the default. Combining `false` with a `securityTier`
+     * throws at synth. Sourced from the generated `account/infrastructure.ts`,
+     * same as `securityTier`.
+     *
+     * Deliberately NOT named `permissionsBoundary`: `AccountProps` extends CDK's
+     * `StackProps`, whose `permissionsBoundary` is a different mechanism (a
+     * `PermissionsBoundary` applied to EVERY role in the stack — the shape the
+     * deferred E3b "app roles inherit the boundary" work would use). This knob
+     * governs only the FjallDeploy role.
+     */
+    deployRoleBoundary?: boolean;
     /**
      * Delivery endpoints for the account's shared alarm topic. Undefined ⇒
      * the topic synthesises with no subscribers and every alarm transition is

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

@@ -122,6 +122,9 @@ export class Account extends Stack {
                 ...(props.securityTier !== undefined && {
                     securityTier: props.securityTier
                 }),
+                ...(props.deployRoleBoundary !== undefined && {
+                    deployRoleBoundary: props.deployRoleBoundary
+                }),
                 ...(props.machineTrustMode !== undefined && {
                     machineTrustMode: props.machineTrustMode
                 })

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

@@ -1,8 +1,14 @@
 import { type IVpc } from "aws-cdk-lib/aws-ec2";
 import { Construct } from "constructs";
+import { type BackupTier } from "../../../utils/backupTierMapping.js";
 import { type BuildkitePropsInput } from "./schema.js";
 export type BuildkiteConstructProps = BuildkitePropsInput & {
     readonly vpc: IVpc;
+    /**
+     * The owning app's backup tier — `BuildkiteFactory` fills it from the App
+     * so the artefact bucket's versioning default follows the tier.
+     */
+    readonly appBackupTier?: BackupTier;
 };
 /**
  * Self-hosted Buildkite agent fleet on the pinned Elastic CI Stack AMIs —

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

@@ -37,7 +37,7 @@ export class Buildkite extends Construct {
     autoScalingGroupName;
     constructor(scope, id, props) {
         super(scope, id);
-        const { vpc, ...plainProps } = props;
+        const { vpc, appBackupTier, ...plainProps } = props;
         const config = validateBuildkiteProps(plainProps);
         // Deliberate asymmetry: the agent token is load-bearing (boot + scaler),
         // so underivable throws; the api-key hook and per-pipeline job secrets
@@ -88,10 +88,14 @@ export class Buildkite extends Construct {
                 owner: config.costAllocationOwner
             })
         });
-        const artifactBucket = new S3Bucket(this, `${id}ArtifactBucket`);
+        // Artefacts are write-once keys, so versioning follows the app backup tier
+        // at negligible cost; the bucket is otherwise scratch output and keeps the
+        // wrapper's env-aware default (DESTROY + pre-empty off prod).
+        const artifactBucket = new S3Bucket(this, `${id}ArtifactBucket`, {
+            appBackupTier
+        });
         // Secrets (SSH deploy keys, git credentials) must survive stack teardown
-        // and accidental overwrite; the artifact bucket is scratch output and
-        // keeps the wrapper's env-aware default (DESTROY + pre-empty off prod).
+        // and accidental overwrite.
         const managedSecretsBucket = new S3Bucket(this, `${id}ManagedSecretsBucket`, { versioned: true, removalPolicy: RemovalPolicy.RETAIN });
         if (fjallApiKeyParameterName !== undefined ||
             pipelineSecretsPrefix !== undefined) {

package/dist/lib/patterns/aws/buildkite/factory.d.ts

@@ -10,10 +10,10 @@ import type { BuildkitePropsInput } from "./schema.js";
  */
 export type BuildkiteFactoryFn = (app: App, scope: Construct) => Buildkite;
 /**
- * Resolve construct props from plain-data input: VPC injection plus the three
+ * Resolve construct props from plain-data input: VPC injection plus the
  * app-level defaults (cost-allocation environment, shared alarm topic,
- * applicationId). Single source for both `App.addBuildkite` entry paths
- * (design § D2) — explicit props always win.
+ * applicationId, backup tier). Single source for both `App.addBuildkite`
+ * entry paths (design § D2) — explicit props always win.
  */
 export declare function resolveBuildkiteConstructProps(app: App, props: BuildkitePropsInput): BuildkiteConstructProps;
 /**

package/dist/lib/patterns/aws/buildkite/factory.js

@@ -3,10 +3,10 @@ import { UNKNOWN_ENVIRONMENT } from "../../../utils/env.js";
 import { getConfig } from "../../../utils/getConfig.js";
 import { Buildkite } from "./buildkite.js";
 /**
- * Resolve construct props from plain-data input: VPC injection plus the three
+ * Resolve construct props from plain-data input: VPC injection plus the
  * app-level defaults (cost-allocation environment, shared alarm topic,
- * applicationId). Single source for both `App.addBuildkite` entry paths
- * (design § D2) — explicit props always win.
+ * applicationId, backup tier). Single source for both `App.addBuildkite`
+ * entry paths (design § D2) — explicit props always win.
  */
 export function resolveBuildkiteConstructProps(app, props) {
     const configEnvironment = getConfig().environment;
@@ -24,7 +24,10 @@ export function resolveBuildkiteConstructProps(app, props) {
     if (constructProps.applicationId === undefined) {
         constructProps.applicationId = app.getName();
     }
-    return constructProps;
+    const appBackupTier = app.getBackupTier();
+    return appBackupTier === undefined
+        ? constructProps
+        : { ...constructProps, appBackupTier };
 }
 /**
  * Factory for the self-hosted Buildkite agent fleet — the codemod add path

package/dist/lib/patterns/aws/interfaces/pattern.d.ts

@@ -201,7 +201,12 @@ export interface PayloadComputeConfig {
  * S3 bucket configuration for pattern sub-buckets.
  */
 export interface PatternStorageBucketConfig {
-    /** Enable versioning. Default: false */
+    /**
+     * Bucket versioning. Absent, the pattern decides: the media bucket follows
+     * the app backup tier (on at `resilient`/`enterprise`), while assets (build
+     * output, pruned per deploy) and cache (ISR, regenerated at runtime) stay
+     * off at every tier. An explicit value always wins.
+     */
     versioned?: boolean;
 }
 /**
@@ -210,9 +215,7 @@ export interface PatternStorageBucketConfig {
  *
  * @example
  * storage: {
- *   assets: { versioned: true },
- *   cache: { versioned: false },
- *   media: { versioned: true }
+ *   media: { versioned: true } // force on below the resilient tier
  * }
  */
 export interface PayloadStorageConfig {

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

@@ -219,6 +219,7 @@ export class Payload extends Construct {
     createAssetsBucket() {
         const assetsConfig = this.props.storage?.assets ?? {};
         const assetsProps = {
+            // Build output, pruned on every deploy — versioning would only bill for churn.
             versioned: assetsConfig.versioned ?? false,
             deployment: {
                 source: `${PAYLOAD_DEFAULTS.SOURCE}/${PAYLOAD_DEFAULTS.OPENNEXT.ASSETS}`,
@@ -234,6 +235,7 @@ export class Payload extends Construct {
     createCacheBucket() {
         const cacheConfig = this.props.storage?.cache ?? {};
         const cacheProps = {
+            // ISR cache, regenerated at runtime — versioning would only bill for churn.
             versioned: cacheConfig.versioned ?? false,
             deployment: {
                 source: `${PAYLOAD_DEFAULTS.SOURCE}/${PAYLOAD_DEFAULTS.OPENNEXT.CACHE}`,
@@ -244,8 +246,11 @@ export class Payload extends Construct {
     }
     createMediaBucket() {
         const mediaConfig = this.props.storage?.media ?? {};
+        // Customer uploads: versioning follows the app backup tier unless set here.
         const mediaProps = {
-            versioned: mediaConfig.versioned ?? false
+            ...(mediaConfig.versioned !== undefined && {
+                versioned: mediaConfig.versioned
+            })
         };
         return this.app.addStorage(StorageFactory.build(`${this.props.name}-media`, mediaProps));
     }

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

@@ -33,6 +33,11 @@ export interface S3Props {
     readonly bucketName?: string;
     readonly publicReadAccess?: boolean;
     readonly websiteHosting?: WebsiteHostingConfig;
+    /**
+     * Bucket versioning. Defaults from the effective backup tier — the
+     * per-bucket `backupVaultTier`, else the app's `backup: { tier }` — on at
+     * `resilient`/`enterprise`, off otherwise. An explicit value always wins.
+     */
     readonly versioned?: boolean;
     readonly encryption?: "AES256" | "KMS";
     readonly kmsKeyArn?: string;
@@ -42,6 +47,10 @@ export interface S3Props {
      * false to opt out. Ignored for non-KMS encryption.
      */
     readonly bucketKeyEnabled?: boolean;
+    /**
+     * Per-bucket backup tier override. Beats the app-level tier for both the
+     * `fjall:disasterRecovery:tier` tag and the versioning default.
+     */
     readonly backupVaultTier?: BackupTier;
     readonly cors?: CorsRule[];
     readonly deployment?: S3DeploymentConfig;
@@ -64,6 +73,12 @@ export interface S3Props {
      * construction.
      */
     readonly appName?: string;
+    /**
+     * The owning app's backup tier (`App.getApp({ backup: { tier } })`), which
+     * the versioning default follows. `StorageFactory` fills it from the App as
+     * it does `appName`; pass it only for direct `new Storage(...)` construction.
+     */
+    readonly appBackupTier?: BackupTier;
 }
 export interface StorageBuildProps extends S3Props {
     readonly stackPlacement?: "storage" | "cdn" | "compute";

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

@@ -84,6 +84,7 @@ export class Storage extends Construct {
                 bucketKeyEnabled: props.bucketKeyEnabled
             }),
             backupVaultTier: props.backupVaultTier,
+            appBackupTier: props.appBackupTier,
             publicReadAccess: props.publicReadAccess,
             websiteHosting: props.websiteHosting,
             resourcePolicyStatements: props.resourcePolicyStatements,
@@ -218,12 +219,14 @@ export class StorageFactory {
         const { stackPlacement, ...s3Props } = props;
         const fn = (app, scope) => {
             validateStorageProps(s3Props);
-            // The App is the only place the app name is known here; website-hosting
-            // buckets need it for their (app, bucket)-keyed exports — the same fill
-            // CdnFactory performs for Cdn.
+            // The App is the only place the app name and backup tier are known
+            // here: website-hosting buckets need the name for their (app,
+            // bucket)-keyed exports (the same fill CdnFactory performs for Cdn), and
+            // the bucket's versioning default follows the tier.
             return new Storage(scope, id, {
                 ...s3Props,
-                appName: s3Props.appName ?? app.getName()
+                appName: s3Props.appName ?? app.getName(),
+                appBackupTier: s3Props.appBackupTier ?? app.getBackupTier()
             });
         };
         if (stackPlacement) {

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

@@ -46,7 +46,19 @@ export interface ResourcePolicyStatement {
  * `bucketKeyEnabled: true` (pass `false` to opt out).
  */
 export interface S3BucketProps extends BucketProps {
+    /**
+     * Per-bucket backup tier override. Beats `appBackupTier` for both the
+     * `fjall:disasterRecovery:tier` tag and the versioning default.
+     */
     backupVaultTier?: BackupTier;
+    /**
+     * The owning app's backup tier (`App.getApp({ backup: { tier } })`). The
+     * versioning default follows the effective tier — this, unless
+     * `backupVaultTier` overrides it — on at `resilient`/`enterprise`. The
+     * `StorageFactory` and `BuildkiteFactory` paths fill it from the App; only
+     * direct `new S3Bucket` construction needs to pass it.
+     */
+    appBackupTier?: BackupTier;
     publicReadAccess?: boolean;
     websiteHosting?: WebsiteHostingConfig;
     /**
@@ -80,5 +92,7 @@ export interface S3BucketProps extends BucketProps {
 }
 export declare class S3Bucket extends Bucket {
     readonly backupVaultTier?: BackupTier;
+    /** The tier the bucket runs under: `backupVaultTier`, else `appBackupTier`. */
+    readonly effectiveBackupTier?: BackupTier;
     constructor(scope: Construct, id: string, props?: S3BucketProps);
 }

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

@@ -3,6 +3,7 @@ import { Annotations, CfnOutput, Duration, RemovalPolicy, Tags } from "aws-cdk-l
 import { BlockPublicAccess, Bucket, BucketEncryption } from "aws-cdk-lib/aws-s3";
 import { ArnPrincipal, Effect, PolicyStatement, StarPrincipal } from "aws-cdk-lib/aws-iam";
 import { RegionInfo } from "aws-cdk-lib/region-info";
+import { resolveEffectiveBackupTier, shouldAutoVersion } from "../../../utils/backupTierMapping.js";
 import { toPascalCase } from "../../../utils/capitaliseString.js";
 import { bucketWebsiteEndpointExportName, bucketWebsiteHostedZoneIdExportName } from "@fjall/util";
 import { envAwareRemovalPolicyDefault, toRemovalPolicy } from "../../../utils/removalPolicy.js";
@@ -15,9 +16,6 @@ export { SDK_PRE_EMPTY_TAG_KEY } from "@fjall/util/aws";
  * every site so the retention window cannot drift.
  */
 export const NONCURRENT_VERSION_EXPIRY_DAYS = 30;
-function shouldAutoVersion(tier) {
-    return tier === "resilient" || tier === "enterprise";
-}
 function toResourcePolicyPrincipal(identifier) {
     return identifier === "*"
         ? new StarPrincipal()
@@ -25,10 +23,13 @@ function toResourcePolicyPrincipal(identifier) {
 }
 export class S3Bucket extends Bucket {
     backupVaultTier;
+    /** The tier the bucket runs under: `backupVaultTier`, else `appBackupTier`. */
+    effectiveBackupTier;
     constructor(scope, id, props = {}) {
-        const { websiteHosting, backupVaultTier, resourcePolicyStatements, aliasTargetName, appName, ...cdkProps } = props;
+        const { websiteHosting, backupVaultTier, appBackupTier, resourcePolicyStatements, aliasTargetName, appName, ...cdkProps } = props;
         const isPublic = props.publicReadAccess === true || websiteHosting !== undefined;
-        const versioned = props.versioned ?? shouldAutoVersion(backupVaultTier);
+        const effectiveBackupTier = resolveEffectiveBackupTier(backupVaultTier, appBackupTier);
+        const versioned = props.versioned ?? shouldAutoVersion(effectiveBackupTier);
         const removalPolicy = props.removalPolicy ?? toRemovalPolicy(envAwareRemovalPolicyDefault());
         // Mirrors the CDK Bucket's own resolution: an encryptionKey with no
         // explicit encryption infers KMS. DSSE is excluded deliberately — S3
@@ -86,6 +87,7 @@ export class S3Bucket extends Bucket {
             ]
         });
         this.backupVaultTier = backupVaultTier;
+        this.effectiveBackupTier = effectiveBackupTier;
         for (const statement of resourcePolicyStatements ?? []) {
             this.addToResourcePolicy(new PolicyStatement({
                 ...(statement.sid !== undefined && { sid: statement.sid }),

package/dist/lib/resources/aws/utilities/customResource.d.ts

@@ -12,9 +12,12 @@ interface CustomResourceProps {
     /** Fixed name for the handler's execution role (account-global — see LambdaFunctionProps). */
     roleName?: string;
     inlinePolicy: PolicyStatement[];
-    properties?: {
-        [key: string]: string;
-    };
+    /**
+     * Passed to CloudFormation as the custom resource's properties verbatim —
+     * nested objects and lists survive intact (CFN forwards the JSON to the
+     * handler unchanged; only scalar leaves are coerced to strings).
+     */
+    properties?: Record<string, unknown>;
     /**
      * CloudFormation resource type for the custom resource (must begin with
      * `Custom::`). Defaults to `AWS::CloudFormation::CustomResource`; set a
@@ -27,6 +30,12 @@ interface CustomResourceProps {
     assetOptions?: AssetOptions;
     handler?: string;
     timeout?: Duration;
+    /**
+     * CloudFormation's own wait for the handler's response. Unset, a lost
+     * response stalls the stack for an hour; set it below the stack's patience
+     * for handlers whose failure must surface fast.
+     */
+    serviceTimeout?: Duration;
 }
 export declare class CustomResource extends Construct {
     readonly response: string;

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

@@ -65,6 +65,9 @@ export class CustomResource extends Construct {
             properties: props.properties,
             ...(props.resourceType !== undefined && {
                 resourceType: props.resourceType
+            }),
+            ...(props.serviceTimeout !== undefined && {
+                serviceTimeout: props.serviceTimeout
             })
         });
         this.response = this.resource.getAtt("Response").toString();

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

@@ -5,7 +5,16 @@ export type BackupTier = "standard" | "resilient" | "enterprise";
 /**
  * Shared mapping from application backup tier names to AWS Backup plan tag values.
  *
- * Used by both App.applyBackupTag() (app-level tag) and StandardTagsAspect
- * (per-resource override tag) to ensure consistent tier → tag translation.
+ * Used by both App.applyBackupTier() (app-level tag) and StandardTagsAspect
+ * (per-resource tag) to ensure consistent tier → tag translation.
  */
 export declare const BACKUP_TIER_TAG_MAP: Readonly<Record<BackupTier, string>>;
+/**
+ * The tier a resource actually runs under: its own override, else the
+ * app-level tier `App.getApp({ backup: { tier } })` declared. The single
+ * resolution every tier-derived default reads (S3 versioning, the DR tag),
+ * so the derivations cannot drift.
+ */
+export declare function resolveEffectiveBackupTier(resourceTier: BackupTier | undefined, appTier: BackupTier | undefined): BackupTier | undefined;
+/** Tiers whose S3 buckets version by default. */
+export declare function shouldAutoVersion(tier: BackupTier | undefined): boolean;

package/dist/lib/utils/backupTierMapping.js

@@ -3,11 +3,24 @@ export const BACKUP_TIER_TAG_KEY = "fjall:disasterRecovery:tier";
 /**
  * Shared mapping from application backup tier names to AWS Backup plan tag values.
  *
- * Used by both App.applyBackupTag() (app-level tag) and StandardTagsAspect
- * (per-resource override tag) to ensure consistent tier → tag translation.
+ * Used by both App.applyBackupTier() (app-level tag) and StandardTagsAspect
+ * (per-resource tag) to ensure consistent tier → tag translation.
  */
 export const BACKUP_TIER_TAG_MAP = Object.freeze({
     standard: "default",
     resilient: "resilient",
     enterprise: "enterprise"
 });
+/**
+ * The tier a resource actually runs under: its own override, else the
+ * app-level tier `App.getApp({ backup: { tier } })` declared. The single
+ * resolution every tier-derived default reads (S3 versioning, the DR tag),
+ * so the derivations cannot drift.
+ */
+export function resolveEffectiveBackupTier(resourceTier, appTier) {
+    return resourceTier ?? appTier;
+}
+/** Tiers whose S3 buckets version by default. */
+export function shouldAutoVersion(tier) {
+    return tier === "resilient" || tier === "enterprise";
+}

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

@@ -22,10 +22,13 @@ export declare class StandardTagsAspect implements IAspect {
      */
     private addIpamPoolTag;
     /**
-     * Add disaster recovery tier tag to S3 buckets with backupVaultTier property.
-     * This serves as a per-resource override when `backupVaultTier` is set on a
-     * specific S3 bucket. CDK child tags override parent tags, so this takes
-     * precedence over the app-level backup tag set via `App.getApp({ backup })`.
+     * Add the disaster recovery tier tag to S3 buckets from the bucket's
+     * effective tier — the per-bucket `backupVaultTier` override, else the
+     * app-level tier the factory threaded in. CDK child tags override parent
+     * tags, so an override wins over the app-level tag set via
+     * `App.getApp({ backup })`; an inherited app tier writes the value that tag
+     * already carries. The same resolution decides the bucket's versioning
+     * default (`S3Bucket`).
      *
      * Tag format: fjall:disasterRecovery:tier = "{tier}"
      *

package/dist/lib/utils/standardTagsAspect.js

@@ -54,10 +54,13 @@ export class StandardTagsAspect {
         }
     }
     /**
-     * Add disaster recovery tier tag to S3 buckets with backupVaultTier property.
-     * This serves as a per-resource override when `backupVaultTier` is set on a
-     * specific S3 bucket. CDK child tags override parent tags, so this takes
-     * precedence over the app-level backup tag set via `App.getApp({ backup })`.
+     * Add the disaster recovery tier tag to S3 buckets from the bucket's
+     * effective tier — the per-bucket `backupVaultTier` override, else the
+     * app-level tier the factory threaded in. CDK child tags override parent
+     * tags, so an override wins over the app-level tag set via
+     * `App.getApp({ backup })`; an inherited app tier writes the value that tag
+     * already carries. The same resolution decides the bucket's versioning
+     * default (`S3Bucket`).
      *
      * Tag format: fjall:disasterRecovery:tier = "{tier}"
      *
@@ -70,8 +73,8 @@ export class StandardTagsAspect {
         let construct = resource;
         while (construct) {
             const backupConstruct = construct;
-            if (backupConstruct.backupVaultTier) {
-                const tier = backupConstruct.backupVaultTier;
+            if (backupConstruct.effectiveBackupTier) {
+                const tier = backupConstruct.effectiveBackupTier;
                 const tagValue = BACKUP_TIER_TAG_MAP[tier];
                 Tags.of(resource).add(BACKUP_TIER_TAG_KEY, tagValue);
                 break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/components-infrastructure",
-  "version": "29.0.0",
+  "version": "31.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fjall-tech/fjall.git",
@@ -78,8 +78,8 @@
   },
   "dependencies": {
     "@aws-sdk/client-organizations": "^3.1098.0",
-    "@fjall/generator": "^29.0.0",
-    "@fjall/util": "^29.0.0",
+    "@fjall/generator": "^31.0.0",
+    "@fjall/util": "^31.0.0",
     "constructs": "^10.7.2",
     "zod": "^4.4.3"
   },