feat(bb-file-bucket): add explicit autoDeleteObjects opt-in escape hatch

Layers on the sandbox-only autoDeleteObjects gating with an explicit
per-bucket override. autoDeleteObjects now resolves to
`destroy && (options?.autoDeleteObjects ?? isSandbox)`, so a genuinely
ephemeral prod bucket can opt into auto-empty (true) while the safe
sandbox-only default is preserved. The `destroy &&` guard keeps CDK's
construct-time invariant that auto-delete requires DESTROY.

- types.ts: add FileBucketOptions.autoDeleteObjects with footgun JSDoc;
  cross-reference from removalPolicy docs
- index.cdk.test.ts: add opt-in/opt-out/invariant tests; strengthen the
  non-sandbox default assertion to a positive DeletionPolicy: Retain check
- changeset: document the behavior change and the new opt-in

Author: ahmedhamouda78

.changeset/bb-file-bucket-removal-policy.md

@@ -2,4 +2,8 @@
 "@aws-blocks/bb-file-bucket": patch
 ---
 
-Fix `FileBucket` silently dropping bucket contents in non-sandbox stacks. Previously an explicit `removalPolicy: 'destroy'` enabled `autoDeleteObjects` in any stack, which provisions a hidden `Custom::S3AutoDeleteObjects` Lambda whose delete behavior cannot be overridden by stack-level retention Aspects (`RemovalPolicies.of(stack).retain()`). `autoDeleteObjects` is now enabled only in sandbox mode, so prod buckets honor retention.
+Fix `FileBucket` silently dropping bucket contents in non-sandbox stacks. Previously an explicit `removalPolicy: 'destroy'` enabled `autoDeleteObjects` in any stack, which provisions a hidden `Custom::S3AutoDeleteObjects` Lambda whose delete behavior cannot be overridden by stack-level retention Aspects (`RemovalPolicies.of(stack).retain()`). `autoDeleteObjects` now defaults to sandbox-only, so prod buckets honor retention.
+
+Behavior change: in a non-sandbox stack, `removalPolicy: 'destroy'` now sets `RemovalPolicy.DESTROY` without auto-empty. `cdk destroy` on a non-empty prod bucket will fail with `DELETE_FAILED` (S3 rejects deleting a non-empty bucket) instead of silently wiping it. Callers relying on `'destroy'` for full teardown of a populated prod bucket should either empty it first or opt in explicitly (below).
+
+New `FileBucketOptions.autoDeleteObjects?: boolean` escape hatch: defaults to sandbox-only behavior, but can be set `true` to force auto-empty for a genuinely-ephemeral prod bucket, or `false` to disable it even in sandbox. Only takes effect when the bucket is being destroyed.

packages/bb-file-bucket/src/index.cdk.test.ts

@@ -127,7 +127,41 @@ test('CDK: non-sandbox default omits DESTROY (Aspect-overridable RETAIN) and no
   new FileBucket(parent, 'uploads');
   const template = Template.fromStack(stack);
   // No explicit removalPolicy → CDK default RETAIN, driven by Aspects.
-  const buckets = template.findResources('AWS::S3::Bucket', { DeletionPolicy: 'Delete' });
-  assert.strictEqual(Object.keys(buckets).length, 0);
+  // Assert the positive default (RETAIN) so the intent is load-bearing rather
+  // than relying on the absence of a 'Delete' policy.
+  template.hasResource('AWS::S3::Bucket', { DeletionPolicy: 'Retain' });
+  template.resourceCountIs('Custom::S3AutoDeleteObjects', 0);
+});
+
+// ── autoDeleteObjects explicit opt-in / opt-out (escape hatch) ───────────────
+//
+// The sandbox-only default can be overridden per-bucket. Opting in lets a
+// genuinely-ephemeral prod bucket auto-empty on destroy; opting out disables
+// auto-empty even in sandbox. The DESTROY invariant still holds — auto-delete
+// never appears without the bucket being destroyed.
+
+test('CDK: non-sandbox destroy with autoDeleteObjects:true opts into the auto-delete Lambda', () => {
+  const { stack, parent } = setup();
+  new FileBucket(parent, 'uploads', { removalPolicy: 'destroy', autoDeleteObjects: true });
+  const template = Template.fromStack(stack);
+  template.hasResource('AWS::S3::Bucket', { DeletionPolicy: 'Delete' });
+  template.resourceCountIs('Custom::S3AutoDeleteObjects', 1);
+});
+
+test('CDK: sandbox default with autoDeleteObjects:false opts out of the auto-delete Lambda', () => {
+  const { stack, parent } = setup({ sandbox: true });
+  new FileBucket(parent, 'uploads', { autoDeleteObjects: false });
+  const template = Template.fromStack(stack);
+  // Sandbox still drops the bucket, but the caller disabled auto-empty.
+  template.hasResource('AWS::S3::Bucket', { DeletionPolicy: 'Delete' });
+  template.resourceCountIs('Custom::S3AutoDeleteObjects', 0);
+});
+
+test('CDK: autoDeleteObjects:true without destroy does NOT provision the auto-delete Lambda', () => {
+  const { stack, parent } = setup();
+  // No destroy → auto-delete cannot apply (invariant: auto-delete requires DESTROY).
+  new FileBucket(parent, 'uploads', { autoDeleteObjects: true });
+  const template = Template.fromStack(stack);
+  template.hasResource('AWS::S3::Bucket', { DeletionPolicy: 'Retain' });
   template.resourceCountIs('Custom::S3AutoDeleteObjects', 0);
 });

packages/bb-file-bucket/src/index.cdk.ts

@@ -49,16 +49,18 @@ export class FileBucket<O extends FileBucketOptions = FileBucketOptions> extends
 		const isSandbox = cdk.Stack.of(this).node.tryGetContext('sandboxMode') === 'true';
 		const destroy = options?.removalPolicy === 'destroy' || (isSandbox && options?.removalPolicy === undefined);
 
-		// `autoDeleteObjects` is enabled ONLY in sandbox mode — never in a prod
-		// stack, even with an explicit `removalPolicy: 'destroy'`. CDK's L2
+		// `autoDeleteObjects` defaults to sandbox-only — never in a prod stack,
+		// even with an explicit `removalPolicy: 'destroy'`, unless the caller
+		// deliberately opts in via `options.autoDeleteObjects: true`. CDK's L2
 		// `s3.Bucket` implements auto-delete via a hidden
 		// `Custom::S3AutoDeleteObjects` Lambda with a hardcoded delete behavior
 		// that stack-level retention Aspects (`RemovalPolicies.of(stack).retain()`)
 		// cannot override. Attaching it to a prod bucket would silently empty the
-		// bucket on `cdk destroy` even when the stack intends to retain it. In
-		// prod, `'destroy'` sets DESTROY without auto-empty; S3 rejects deleting a
-		// non-empty bucket, which is the correct, safe behavior.
-		const autoDeleteObjects = isSandbox && destroy;
+		// bucket on `cdk destroy` even when the stack intends to retain it, so the
+		// safe default is sandbox-only. It only ever applies when the bucket is
+		// actually being destroyed (`destroy`), preserving CDK's construct-time
+		// invariant that auto-delete requires DESTROY.
+		const autoDeleteObjects = destroy && (options?.autoDeleteObjects ?? isSandbox);
 
 		// Bucket name is derived from the scope chain. Validate against S3's
 		// naming rules at synth so an invalid name fails here rather than at

packages/bb-file-bucket/src/types.ts

@@ -24,15 +24,18 @@ export interface FileBucketOptions {
 	 * preserved on `cdk destroy`).
 	 *
 	 * Pass `'destroy'` to drop the bucket on teardown (`RemovalPolicy.DESTROY`).
-	 * `autoDeleteObjects` (which empties the bucket before deletion) is enabled
-	 * **only in sandbox mode**. In a prod stack, `'destroy'` sets DESTROY but
-	 * does NOT auto-empty — S3 rejects deleting a non-empty bucket, so a
-	 * populated prod bucket is preserved rather than silently wiped.
+	 * By default `autoDeleteObjects` (which empties the bucket before deletion)
+	 * is enabled **only in sandbox mode**. In a prod stack, `'destroy'` sets
+	 * DESTROY but does NOT auto-empty — S3 rejects deleting a non-empty bucket,
+	 * so a populated prod bucket is preserved rather than silently wiped. To
+	 * opt a genuinely-ephemeral prod bucket into auto-empty behavior, set
+	 * {@link autoDeleteObjects} explicitly.
 	 *
-	 * Why sandbox-only: CDK implements `autoDeleteObjects` via a hidden
-	 * `Custom::S3AutoDeleteObjects` Lambda whose delete behavior stack-level
-	 * retention Aspects (`RemovalPolicies.of(stack).retain()`) cannot override.
-	 * Keeping it out of prod stacks ensures those Aspects remain effective.
+	 * Why sandbox-only by default: CDK implements `autoDeleteObjects` via a
+	 * hidden `Custom::S3AutoDeleteObjects` Lambda whose delete behavior
+	 * stack-level retention Aspects (`RemovalPolicies.of(stack).retain()`)
+	 * cannot override. Keeping it out of prod stacks by default ensures those
+	 * Aspects remain effective unless a caller deliberately opts out.
 	 *
 	 * Pass `'retain'` to set the policy explicitly (identical to omitting
 	 * it today, but robust against stack-layer policy overrides).
@@ -43,6 +46,25 @@ export interface FileBucketOptions {
 	 * Ignored by the mock and browser runtimes (no AWS resource to retain).
 	 */
 	removalPolicy?: 'destroy' | 'retain';
+	/**
+	 * Explicitly control whether the bucket is emptied before deletion via
+	 * CDK's `autoDeleteObjects`. Only takes effect when the bucket is being
+	 * destroyed (`removalPolicy: 'destroy'`, or sandbox default).
+	 *
+	 * When omitted, defaults to sandbox-only: auto-empty is enabled in sandbox
+	 * mode and disabled in prod. Set `true` to force auto-empty for a
+	 * deliberately-ephemeral prod bucket, or `false` to disable it even in
+	 * sandbox.
+	 *
+	 * ⚠️ Enabling this provisions a hidden `Custom::S3AutoDeleteObjects` Lambda
+	 * whose delete behavior stack-level retention Aspects
+	 * (`RemovalPolicies.of(stack).retain()`) cannot override. Only opt in for a
+	 * bucket you genuinely intend to be throwaway — this is a deliberate,
+	 * visible footgun rather than the default.
+	 *
+	 * Ignored by the mock and browser runtimes.
+	 */
+	autoDeleteObjects?: boolean;
 	/** Optional logger for internal operations. When omitted, a default Logger at error level is created. */
 	logger?: ChildLogger;
 }