feat(large-messages): add optional allowedBuckets allowlist

[phipag]

Summary

Changes

Please provide a summary of what's being changed

Adds an opt-in bucket allowlist to the v2 large messages utility. The S3 bucket in the large-message pointer is supplied by the message sender, so this gives consumers fine-grained, in-application control over which buckets the utility reads from and deletes, complementing plain IAM permissions with a defense-in-depth layer that lives next to their handler configuration.

Configure it through the existing LargeMessageConfig singleton:

LargeMessageConfig.init().withAllowedBuckets(Set.of("my-offload-bucket"));

When a non-empty allowlist is configured, the utility rejects any message whose pointer names a bucket outside the allowlist by throwing LargeMessageProcessingException before any S3 read or delete. An empty allowlist (the default) applies no restriction, so the change is fully backward compatible. It works for both the @LargeMessage annotation and the functional LargeMessages.processLargeMessage(...) API.

Details:

• LargeMessageConfig.withAllowedBuckets(Set<String>) / getAllowedBuckets(), with the test-only reset clearing it.
• LargeMessageProcessor validates the pointer's bucket against the allowlist before fetching/deleting.
• Unit tests covering config behavior plus the annotation and functional paths (match processes; mismatch throws and never touches S3).
• A new largemessage-restricted e2e handler and a negative e2e test asserting an offloaded message from a non-allowlisted bucket is neither processed nor deleted.
• Docs: a security note that the bucket is sender-controlled, a resource-scoped IAM example, and allowedBuckets usage for both APIs.

Please add the issue number below, if no issue is present the PR might get blocked and not be reviewed

Issue number: #2554

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[github-actions]

Dependency Review

The following issues were found:

• ❌ 1 vulnerable package(s)
• ❌ 1 package(s) with incompatible licenses
• ✅ 0 package(s) with invalid SPDX license definitions
• ⚠️ 48 package(s) with unknown licenses.
• ⚠️ 3 packages with OpenSSF Scorecard issues.

View full job summary

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud