chore(s3): use BucketReflection for L1-backed property access

[mrgrain]

Reason for this change

Properties like isWebsite, disallowPublicAccess, and bucketWebsiteDomainName on the Bucket class are computed eagerly from constructor props and cached as plain fields. This means the values are frozen at construction time and won't reflect any mutations made to the underlying CfnBucket resource afterwards. It also means each of these properties has its own bespoke derivation logic scattered across the constructor, making it harder to reason about where the source of truth lives.

Description of changes

This introduces BucketReflection, a new class that reads bucket configuration directly from the L1 CfnBucket resource at access time rather than caching prop-derived values. By reading from the L1, the reflection getters provide a single source of truth that stays consistent regardless of whether the bucket was created as an L2 construct, imported, or built directly as a CfnBucket.

The Bucket class is refactored to delegate bucketWebsiteDomainName, isWebsite, and disallowPublicAccess through BucketReflection getters. The disallowPublicAccess setter is now a no-op since the value is derived from the CfnBucket resource via reflection.

BucketReflection is deliberately kept as a non-exported internal class while we iterate on the API shape. Once the pattern stabilizes, it can be promoted to a public API.

Beyond the initial three properties, BucketReflection also exposes policy and encryptionKey getters that search the construct tree for the associated CfnBucketPolicy and CfnKey resources. The previous private helper functions (tryFindBucketPolicyForBucket, tryFindKmsKeyforBucket, tryFindBucketConstruct) in lib/private/reflections.ts are consolidated into BucketReflection and the file is deleted. Internal consumers in default-traits.ts are updated to use BucketReflection instead.

BucketReflection.of() gracefully handles custom IBucketRef implementations that don't have an underlying CfnBucket in the construct tree. The bucket getter throws lazily on access when no L1 is found, while policy falls back to searching from the original IBucketRef, and encryptionKey/disallowPublicAccess return safe defaults. This ensures the class works across L1, L2, and custom bucket implementations.

To support safe property traversal on L1 resources — where any nested value might be an unresolved CDK token — this adds a resolvedGet utility to core/lib/helpers-internal. It walks a dot-separated property path and returns a caller-specified fallback whenever it encounters an IResolvable, rather than silently returning a token object that would be misinterpreted as a truthy value. This distinction between "not configured" (undefined) and "configured but unreadable" (fallback) is important for reflection getters that need to make boolean decisions based on L1 property values.

Describe any new or updated permissions being added

No new permissions.

Description of how you validated changes

Existing tests in bucket-reflection.test.ts (renamed from reflections.test.ts) are updated to use the BucketReflection public API instead of the deleted private helpers. Additional tests verify behavior with custom IBucketRef implementations that lack a CfnBucket: the bucket getter throws, policy still finds associated policies, and encryptionKey returns undefined. New unit tests for resolvedGet cover simple paths, numeric indexing, missing segments, null segments, and resolvable token handling at root, intermediate, and leaf positions.

Checklist

• My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[aws-cdk-automation]

(This review is outdated)

[rix0rrr]

We need to do make a decision about CFN intrinsics and tokens.

techincally speaking, the value of websiteConfiguration could be Fn.if(someCondition, {}, Aws.NO_VALUE).

In that case, we would return true, even though the correct answer is false (but the correct answer from CDK's point of view is "don't know").

How about returning a

class Answer {
  public readonly isTrue: boolean;
  public readonly isFalse: boolean;
  public readonly isUnknown: boolean;
}

Value?

[mrgrain]

I mean we already have that with true false and undefined. The issue here is more that the existing code used this check, but never allowed it to be a Fn. Will fix.

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-03-25 11:22 UTC · Rule: default-squash
• ✅ Checks passed · in-place
• ✅ Merged — 2026-03-25 11:53 UTC · at dcb90b507f2dad819e12f617dcc4f9d5c9cc6806

This pull request spent 31 minutes 8 seconds in the queue, including 30 minutes 58 seconds running CI.

Required conditions to merge

• #approved-reviews-by >= 1 [🛡 GitHub branch protection]
  • chore(s3): use BucketReflection for L1-backed property access #37210
• #changes-requested-reviews-by = 0 [🛡 GitHub branch protection]
  • chore(s3): use BucketReflection for L1-backed property access #37210
• any of [🛡 GitHub branch protection]:
  • check-success = validate-pr
  • check-neutral = validate-pr
  • check-skipped = validate-pr
• any of [🛡 GitHub branch protection]:
  • check-success = build
  • check-neutral = build
  • check-skipped = build

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

[github-actions]

Comments on closed issues and PRs are hard for our team to see.
If you need help, please open a new issue that references this one.