fix(bb-file-bucket): only enable autoDeleteObjects in sandbox mode

An explicit removalPolicy: 'destroy' previously enabled autoDeleteObjects
in any stack, including prod. CDK's L2 s3.Bucket implements auto-delete via
a hidden Custom::S3AutoDeleteObjects Lambda whose delete behavior stack-level
retention Aspects (RemovalPolicies.of(stack).retain()) cannot override, so a
"retained" prod bucket was silently emptied on cdk destroy.

autoDeleteObjects is now gated on sandbox mode (isSandbox && destroy). In prod,
'destroy' still sets RemovalPolicy.DESTROY but no auto-empty Lambda, so S3
rejects deleting a non-empty bucket and retention Aspects stay effective.

Updates the removalPolicy JSDoc and adds 4 CDK synth regression tests.

Author: pjkroker

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

@@ -0,0 +1,5 @@
+---
+"@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.

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

@@ -31,8 +31,12 @@ class StubBlocksStack extends cdk.Stack {
   }
 }
 
-function setup(): { stack: StubBlocksStack; parent: Scope } {
-  const app = new cdk.App();
+function setup(opts?: { sandbox?: boolean }): { stack: StubBlocksStack; parent: Scope } {
+  // Sandbox mode is read via `stack.node.tryGetContext('sandboxMode')`, so
+  // seed it on the app context when requested.
+  const app = new cdk.App(
+    opts?.sandbox ? { context: { sandboxMode: 'true' } } : undefined,
+  );
   // S3 bucket names must be lowercase. The default-mode FileBucket derives
   // its bucket name from the scope chain, so keep ids lowercase.
   const stack = new StubBlocksStack(app, 'teststack');
@@ -82,3 +86,48 @@ test('CDK: fromExisting skips derived-name validation even when the chain is ove
     }),
   );
 });
+
+// ── removalPolicy / autoDeleteObjects (R6 regression) ────────────────────────
+//
+// autoDeleteObjects provisions a hidden `Custom::S3AutoDeleteObjects` Lambda
+// whose delete behavior stack-level retention Aspects cannot override. It must
+// be attached ONLY in sandbox mode — never to a prod bucket, even with an
+// explicit `removalPolicy: 'destroy'` — or a "retained" prod bucket would be
+// silently emptied on `cdk destroy`.
+
+test('CDK: sandbox default enables DESTROY + auto-delete Lambda', () => {
+  const { stack, parent } = setup({ sandbox: true });
+  new FileBucket(parent, 'uploads');
+  const template = Template.fromStack(stack);
+  // Sandbox cleanup ergonomics preserved: bucket is dropped and auto-emptied.
+  template.hasResource('AWS::S3::Bucket', { DeletionPolicy: 'Delete' });
+  template.resourceCountIs('Custom::S3AutoDeleteObjects', 1);
+});
+
+test('CDK: non-sandbox explicit destroy sets DESTROY but NO auto-delete Lambda (regression)', () => {
+  const { stack, parent } = setup();
+  new FileBucket(parent, 'uploads', { removalPolicy: 'destroy' });
+  const template = Template.fromStack(stack);
+  // Bucket is marked for deletion, but the un-overridable auto-delete Lambda
+  // must NOT be present in a prod stack — this is the core fix.
+  template.hasResource('AWS::S3::Bucket', { DeletionPolicy: 'Delete' });
+  template.resourceCountIs('Custom::S3AutoDeleteObjects', 0);
+});
+
+test('CDK: non-sandbox explicit retain sets RETAIN and no auto-delete Lambda', () => {
+  const { stack, parent } = setup();
+  new FileBucket(parent, 'uploads', { removalPolicy: 'retain' });
+  const template = Template.fromStack(stack);
+  template.hasResource('AWS::S3::Bucket', { DeletionPolicy: 'Retain' });
+  template.resourceCountIs('Custom::S3AutoDeleteObjects', 0);
+});
+
+test('CDK: non-sandbox default omits DESTROY (Aspect-overridable RETAIN) and no auto-delete Lambda', () => {
+  const { stack, parent } = setup();
+  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);
+  template.resourceCountIs('Custom::S3AutoDeleteObjects', 0);
+});

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

@@ -46,11 +46,20 @@ export class FileBucket<O extends FileBucketOptions = FileBucketOptions> extends
 		// In sandbox mode, default to DESTROY + autoDeleteObjects so
 		// `cdk destroy` can fully clean up without manual bucket emptying.
 		// Explicit `removalPolicy` from the customer takes precedence.
-		// `autoDeleteObjects: true` is only valid paired with DESTROY (CDK
-		// validates this at construct time), so we tie the two together.
 		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
+		// `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 name is derived from the scope chain. Validate against S3's
 		// naming rules at synth so an invalid name fails here rather than at
 		// `cdk deploy` (where CloudFormation rejects it with a cryptic error).
@@ -66,7 +75,7 @@ export class FileBucket<O extends FileBucketOptions = FileBucketOptions> extends
 				: options?.removalPolicy === 'retain'
 					? RemovalPolicy.RETAIN
 					: undefined,
-			autoDeleteObjects: destroy,
+			autoDeleteObjects,
 			cors: options?.corsRules?.map((rule: CorsRule) => ({
 				allowedOrigins: rule.allowedOrigins,
 				allowedMethods: rule.allowedMethods.map(m => httpMethodMap[m]),

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

@@ -23,10 +23,16 @@ export interface FileBucketOptions {
 	 * CDK's default applies (RETAIN — the bucket and its contents are
 	 * preserved on `cdk destroy`).
 	 *
-	 * Pass `'destroy'` for sandbox / ephemeral stacks where the bucket
-	 * should be dropped on teardown. This also enables `autoDeleteObjects`
-	 * so CloudFormation can empty the bucket before deletion — required
-	 * since S3 rejects DELETE on a non-empty bucket.
+	 * 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.
+	 *
+	 * 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.
 	 *
 	 * Pass `'retain'` to set the policy explicitly (identical to omitting
 	 * it today, but robust against stack-layer policy overrides).