feat(s3): support bucketNamePrefix and bucketNamespace properties

[kawaaaas]

Issue # (if applicable)

N/A

Reason for this change

The L1 AWS::S3::Bucket resource added BucketNamePrefix and BucketNamespace properties, enabling account-regional bucket naming. AWS recommends creating new S3 buckets in the account-regional namespace, as bucket names are scoped to the account and region, reducing the risk of name conflicts and preventing other accounts from claiming the same name. This is particularly useful for anyone creating new S3 buckets. The L2 Bucket construct should expose these new properties.

Description of changes

• Added bucketNamePrefix and bucketNamespace props to BucketProps
• Added BucketNamespace enum (GLOBAL, ACCOUNT_REGIONAL)
• Added prop combination validation:
  • bucketName + bucketNamePrefix → error (mutually exclusive)
  • bucketName + bucketNamespace (except GLOBAL) → error (use bucketNamePrefix with bucketNamespace instead)
  • bucketNamePrefix without bucketNamespace: ACCOUNT_REGIONAL → error (prefix requires account-regional namespace)
  • bucketNamespace: ACCOUNT_REGIONAL without bucketNamePrefix → error (account-regional namespace requires a prefix)
• Added prefix format validation:
  • Must only contain lowercase letters, numbers, and hyphens
  • Must start and end with a lowercase letter or number
  • Must be 37 characters or fewer
• Passed bucketNamePrefix and bucketNamespace through to the CfnBucket resource
• Updated README with documentation and usage example
• Added unit tests covering all valid/invalid combinations
• Added integration test

Design decisions:

• Although CloudFormation allows bucketName with bucketNamespace: account-regional, this is functionally equivalent to specifying bucketNamePrefix with account-regional namespace. Supporting both paths would increase validation complexity for no practical benefit, and AWS recommends using bucketNamePrefix for account-regional buckets. Therefore, bucketName + bucketNamespace is treated as an error.

• The maximum prefix length is validated at 37 characters. The account-regional suffix format is -<accountId(12)>-<region>-an, and the S3 bucket name limit is 63 characters. The suffix length varies by region name length; 37 is the maximum prefix length for the shortest region code (us-east-1, 9 chars → 26-char suffix). Longer region codes (e.g. ap-northeast-1) will have a shorter effective limit, which CloudFormation enforces at deploy time.

• When bucketNamespace: account-regional is specified without bucketName or bucketNamePrefix, CloudFormation's auto-generated bucket name does not include the required account-regional suffix (-<accountId>-<region>-an), causing the S3 API to reject the request:
  Resource handler returned message: "The requested bucket name did not include the account-regional namespace suffix, but the provided x-amz-bucket-namespace header value is account-regional. Specify -[accountId]-[region]-an as the bucket name suffix to create a bucket in your account-regional namespace, or remove the header. (Service: S3, Status Code: 400)"
  Therefore, the L2 construct validates that bucketNamePrefix is required when bucketNamespace is ACCOUNT_REGIONAL, failing early with a clear error message rather than deferring to a CloudFormation deployment failure. This means that for account-regional buckets, users must explicitly specify a bucketNamePrefix rather than relying on CloudFormation's recommended auto-generated naming.

Describe any new or updated permissions being added

None

Description of how you validated changes

Add both unit and integ tests

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