@aws-blocks/bb-file-bucket 0.1.5 → 0.2.0

package/DESIGN.md

@@ -38,6 +38,7 @@ versions/{key}/__deleted__        delete marker (sentinel)
 **D-FB-6: Versioning is opt-in with runtime API support**
 **Decision:** `versioned: true` enables S3 object versioning and unlocks version-aware methods (`listVersions`, `restoreVersion`, optional `versionId` on `get`/`delete`/`getUrl`/`getFileHandle`). Without the flag, the API surface is unchanged.
 **Rationale:** Versioning adds storage cost and complexity. Making it opt-in keeps the default simple. When enabled, the runtime API exposes the full version lifecycle — listing, retrieving specific versions, permanent deletion of individual versions, and restoring old versions. `restoreVersion` is implemented as a CopyObject from the old version (S3 has no native restore), which creates a new version that becomes current.
+**Update:** The **default flipped to ON** — see D-FB-10. The runtime API described here is unchanged; only the default value of `versioned` and its typing gate changed.
 
 **D-FB-7: Mock versioning uses filesystem directories**
 **Decision:** Versioned mock stores each version in `versions/{key}/v{n}` with monotonic IDs. Delete markers are `versions/{key}/__deleted__` sentinel files.
@@ -47,17 +48,47 @@ versions/{key}/__deleted__        delete marker (sentinel)
 **Decision:** The derived bucket name (`scope.fullId`) is validated against S3's naming rules (`bucket-name.ts`) before the bucket is constructed. An invalid name throws a `ValidationFailed` error with an actionable message. The same validator runs in the mock constructor so local dev (`bb dev`) fails identically — parity. `FileBucket.fromExisting(...)` skips validation since the name is externally owned.
 **Rationale:** S3 bucket names are globally unique and immutable. Truncating to fit 63 chars risks collisions, and a name that shifts between deploys (e.g. after a hash input changes) would orphan or replace the customer's data — a far worse outcome than a fast, fixable synth error. Erroring puts the fix in the developer's hands (shorten a scope id once; the name is then stable forever) and matches the manual-shortening pattern already used in `bb-agent`. This deliberately differs from DynamoDB-backed BBs (KVStore/DistributedTable) which `substring(0, 255)` — DynamoDB's 255 limit is generous and table names are internal, disposable, and not globally unique, so silent truncation is acceptable there.
 
+**D-FB-9: TLS enforced unconditionally (enforceSSL)**
+**Decision:** Every provisioned bucket (the data bucket and the opt-in access-log bucket) sets `enforceSSL: true`, so CDK attaches a bucket policy denying any request where `aws:SecureTransport` is `false`. Not configurable.
+**Rationale:** All FileBucket traffic — SDK calls and presigned URLs alike — is already HTTPS, so enforcing TLS closes the in-transit exposure gap with zero functional cost. There is no legitimate reason a FileBucket consumer needs plaintext S3 access, so this is a hard default rather than an option. Covered by the `enforces SSL` CDK test.
+
+**D-FB-10: Versioning default ON — supersedes D-FB-6's opt-in default**
+**Decision:** `versioned` now defaults to `true`; consumers opt out with the literal `versioned: false`. The version-aware runtime API and its option typings (`GetOptionsFor` et al.) remain unchanged in shape, but the conditional types now select the non-versioned (optionless) form only for the literal `versioned: false` — a non-literal `boolean` or an absent value resolves to the versioned-aware form, matching the new runtime default.
+**Rationale:** Accidental overwrites and deletes are unrecoverable without versioning; defaulting it on makes the safe choice the default and matches the "secure by default" posture of D-FB-9. This is a **behavior/breaking change** for existing consumers (buckets that were non-versioned by default now enable versioning, which adds storage cost for prior versions), so it ships with a `minor` changeset bump under the pre-1.0 (0.x) convention that a minor signals a breaking change. The literal-`false` typing gate is a deliberate consequence of `extends { versioned: false }`: TypeScript cannot narrow a widened `boolean` to the `false` branch, so the versioned-aware typings are the safe fallback.
+
+**D-FB-11: Opt-in server access logging with a dedicated locked-down log bucket**
+**Decision:** `accessLogging: true` provisions a second, dedicated S3 bucket (all public access blocked, S3-managed encryption, `enforceSSL`) that receives the main bucket's server access logs under the `access-logs/` prefix. Logs expire via a lifecycle rule after `logRetentionDays` (default `DEFAULT_ACCESS_LOG_RETENTION_DAYS = 90`). `logRetentionDays` is validated at synth: when access logging is enabled, a non-positive or non-integer value throws — a degenerate `Duration.days(0)`/negative lifecycle would otherwise only surface at deploy. The value is inert (and therefore not validated) when `accessLogging` is off.
+**Rationale:** Access logging is off by default because it has a real cost (extra bucket, log storage) and most consumers don't need an audit trail; making it opt-in keeps the default lean. The log bucket is kept **separate** from the data bucket so log delivery can't loop back onto the bucket being logged. Validating `logRetentionDays` at synth follows the same fail-fast principle as D-FB-8 (bucket name) and the CORS guard (D-FB-12): misconfiguration fails loud at synth, not minutes into a deploy.
+**Update (superseded by D-FB-13):** The per-block `logRetentionDays` option was **removed**. Access-log retention is no longer configured per-block; it now derives from the framework-wide `scope.defaults.logRetention` (`RetentionDays.ONE_WEEK` in sandbox / `ONE_YEAR` in production; `RetentionDays.INFINITE` omits the expiry rule so logs are kept indefinitely). The `accessLogging` toggle itself likewise falls back to `scope.defaults.accessLogging` when not set per-block. The dedicated locked-down log bucket and its separation from the data bucket (the substance of this decision) are unchanged — only the *source* of the retention/enable posture moved from a per-block number to the stack `BlocksDefaults`. The synth-time validation that formerly guarded `logRetentionDays` no longer applies (there is no per-block retention input); the equivalent guard now lives on `noncurrentVersionExpirationDays` — see D-FB-14.
+
+**D-FB-12: Wildcard-origin CORS + mutating method rejected at synth**
+**Decision:** A CORS rule whose `allowedOrigins` includes `'*'` and whose `allowedMethods` includes a mutating method (`PUT`/`POST`/`DELETE`, the `MUTATING_CORS_METHODS` set) throws a synth-time `Error`. Wildcard + safe methods (`GET`/`HEAD`) is allowed; explicit origins + mutating methods is allowed.
+**Rationale:** A wildcard origin on a state-changing method lets any website issue authenticated cross-origin writes/deletes against the bucket — a CSRF-shaped exposure. Rather than silently deploying it, FileBucket fails loud at synth with an actionable message pointing the developer at explicit origins. A hard error (not a warning) was chosen deliberately: this PR supersedes the prior behavior where such a rule deployed unchallenged, and the user opted for the strict gate over a soft warning.
+
+**D-FB-13: Posture knobs route through the framework `BlocksDefaults` — supersedes the per-block `logRetentionDays` and the `sandboxMode`-context removal read**
+**Decision:** `removalPolicy`, `accessLogging`, and access-log retention are resolved from the stack-wide `BlocksDefaults` model (exposed as `scope.defaults`) rather than from per-block day-numbers or a `sandboxMode` CDK context read. Each posture knob follows the framework's `options?.field ?? scope.defaults.field` contract (the same pattern `bb-kv-store` uses for `removalPolicy`/`deletionProtection`, and documented on the `Scope.defaults` getter in `@aws-blocks/core/cdk`):
+- `removalPolicy` — an explicit per-block `'destroy'|'retain'` still wins; when omitted it falls back to `scope.defaults.removalPolicy` (`DESTROY` in the sandbox preset, `RETAIN` in production). This replaces the previous `sandboxMode`-derived removal.
+- `accessLogging` — falls back to `scope.defaults.accessLogging` when not set per-block, so a production-postured stack can opt every FileBucket into logging without a per-block flag.
+- **access-log retention** — derives from `scope.defaults.logRetention` (a `RetentionDays` enum: `ONE_WEEK` sandbox / `ONE_YEAR` production). `RetentionDays` is a numeric enum whose member value *is* the day count, so it maps directly to `Duration.days(...)`; the one non-day member `INFINITE` omits the lifecycle expiry rule (logs kept forever) rather than expiring at a spurious 9999 days.
+**Rationale:** Addresses review comment (C): posture should come from the one stack-level model every block already consumes, not from a grab-bag of per-block numbers and a legacy `sandboxMode` context flag. Centralizing on `BlocksDefaults` means a stack picks `BlocksPresets.sandbox`/`.production` once and every FileBucket inherits a coherent removal + logging + retention posture, while per-block overrides remain available for the knobs that still accept them (`removalPolicy`, `accessLogging`). This also removes the last consumer of the `sandboxMode` context read from this package.
+
+**D-FB-14: Noncurrent-version expiration bounded by default (90 days)**
+**Decision:** When versioning is enabled (the default — D-FB-10), the main bucket gets a lifecycle rule (`ExpireNoncurrentVersions`) that permanently expires **noncurrent** object versions after `noncurrentVersionExpirationDays` (default `DEFAULT_NONCURRENT_VERSION_EXPIRATION_DAYS = 90`). The value's FORMAT is validated at synth whenever the option is provided, regardless of `versioned`: a non-positive or non-integer value throws (a degenerate `Duration.days(0)`/negative would otherwise only surface at deploy — same fail-fast principle as D-FB-8/D-FB-12). The rule itself is only APPLIED when versioning is on. There is no "disable" sentinel; to drop the rule entirely, disable versioning (`versioned: false`), which removes it along with versioning. The rule is inert on the mock and browser runtimes (no AWS resource).
+**Rationale:** Addresses review comment (A): defaulting versioning ON (D-FB-10) makes overwrites/deletes recoverable but lets prior versions accrue storage cost without bound. Capping noncurrent versions at 90 days by default keeps the safe-by-default posture affordable — the common case (recover from a recent bad write) is well within 90 days, while stale versions no longer pile up indefinitely. It pairs with, and offsets the cost concern raised by, the versioning-default-on change rather than reopening that decision.
+
 ## Infrastructure (CDK)
 
-Creates a single S3 bucket:
+Creates a single S3 bucket (plus a dedicated log bucket when `accessLogging` is enabled):
 
 - **Bucket name:** Derived from `scope.fullId` (the bucket id joined to its parent scope ids with `-`). Validated at synth against S3's naming rules — see D-FB-6.
 - **Block public access:** All four settings enabled (BLOCK_ALL)
 - **Encryption:** S3-managed keys (SSE-S3)
-- **Versioning:** Disabled by default, enabled via `options.versioned`
-- **CORS:** Configured from `options.corsRules` if provided
-- **Lifecycle rules:** Configured from `options.lifecycleRules` if provided
-- **Removal policy:** DESTROY (sandbox), configurable for production
+- **TLS:** Enforced unconditionally (`enforceSSL: true`) — a bucket policy denies any request where `aws:SecureTransport` is `false`. Not configurable. See D-FB-9.
+- **Versioning:** Enabled by default (secure default); opt out via `options.versioned: false`. See D-FB-10. When on, a lifecycle rule expires noncurrent versions after `options.noncurrentVersionExpirationDays` (default 90, validated as a positive integer at synth) to bound version-storage cost. See D-FB-14.
+- **Server access logging:** Enabled per-block via `options.accessLogging`, falling back to `scope.defaults.accessLogging` when omitted; when on, provisions a separate, locked-down log bucket whose logs expire after the stack posture's `scope.defaults.logRetention` (`ONE_WEEK` sandbox / `ONE_YEAR` production; `INFINITE` = no expiry). See D-FB-11 and D-FB-13.
+- **CORS:** Configured from `options.corsRules` if provided. A wildcard origin (`'*'`) combined with a mutating method (PUT/POST/DELETE) is rejected at synth. See D-FB-12.
+- **Lifecycle rules:** Configured from `options.lifecycleRules` if provided (merged with the noncurrent-version expiration rule above)
+- **Removal policy:** Resolved from `options.removalPolicy` (`'destroy'|'retain'`) when set, else the stack posture default `scope.defaults.removalPolicy` (DESTROY sandbox / RETAIN production) — replacing the former `sandboxMode` context read. See D-FB-13.
 - **Auto-delete objects:** Enabled when removal policy is DESTROY
 - **Permissions:** `grantReadWrite` to the parent scope's handler automatically
 

package/README.md

@@ -33,12 +33,16 @@ const bucket = new FileBucket(scope, id, options?)
 
 | Option | Type | Description |
 |--------|------|-------------|
-| `versioned` | `boolean` | Enable S3 object versioning. Default: `false`. |
-| `corsRules` | `CorsRule[]` | CORS rules for browser-based access. |
+| `versioned` | `boolean` | Enable S3 object versioning. **Default: `true`.** Pass `versioned: false` to opt out. Note: the version-aware method typings (`versionId` on `get`/`delete`/`getUrl`/`getFileHandle`) are selected only by the literal `versioned: false`; a non-literal `boolean` or an absent value resolves to the versioned-aware typings. |
+| `noncurrentVersionExpirationDays` | `number` | Days after which **noncurrent** (superseded) object versions are permanently expired, bounding the storage cost that versioning would otherwise let grow unbounded. Only applies when versioning is enabled (the default). **Default: `90`.** Must be a positive integer — a non-positive or non-integer value throws at synth. There is no disable sentinel; to drop the rule entirely, disable versioning (`versioned: false`). Ignored by the mock and browser runtimes. |
+| `corsRules` | `CorsRule[]` | CORS rules for browser-based access. See [CorsRule](#corsrule) for the wildcard-origin synth guard. |
 | `lifecycleRules` | `LifecycleRule[]` | Lifecycle rules for automatic expiration or storage class transitions. |
+| `accessLogging` | `boolean` | Enable S3 server access logging. **Default: falls back to the stack posture (`BlocksDefaults.accessLogging`)** when omitted — so a production-postured stack can opt every FileBucket into logging without a per-block flag. When enabled, a dedicated, locked-down log bucket is provisioned (all public access blocked, S3-managed encryption, SSL enforced) and the main bucket delivers its access logs there under the `access-logs/` prefix. Access logs expire automatically after the stack posture's `logRetention` (`ONE_WEEK` in sandbox / `ONE_YEAR` in production; `RetentionDays.INFINITE` keeps them indefinitely). Ignored by the mock and browser runtimes. |
 | `bucket` | `ExternalBucketRef` | Wrap an existing S3 bucket instead of creating one. |
 | `logger` | `ChildLogger` | Optional logger for internal operations. When omitted, a default error-level logger is created. |
-| `removalPolicy` | `'destroy' \| 'retain'` | CDK removal behavior for the underlying S3 bucket. When omitted, CDK's default (RETAIN) applies; pass `'destroy'` for sandbox / ephemeral stacks. Ignored by the mock and browser runtimes. |
+| `removalPolicy` | `'destroy' \| 'retain'` | CDK removal behavior for the underlying S3 bucket. When omitted, it falls back to the stack posture default (`BlocksDefaults.removalPolicy` — `DESTROY` in sandbox, `RETAIN` in production); pass `'destroy'` or `'retain'` to set it explicitly per-block. `'destroy'` also enables `autoDeleteObjects` so the bucket can be emptied on teardown. Ignored by the mock and browser runtimes. |
+
+All FileBucket-provisioned buckets **enforce TLS unconditionally** (`enforceSSL: true`) — CDK attaches a bucket policy denying any request where `aws:SecureTransport` is `false`, closing the in-transit exposure gap. This is not configurable.
 
 ### PutOptions
 
@@ -60,6 +64,8 @@ CORS configuration for browser-based access. Supplied via the `corsRules` option
 | `exposedHeaders` | `string[]` | Optional. Response headers exposed to the browser. |
 | `maxAge` | `number` | Optional. Seconds the browser may cache the preflight response. |
 
+> **Wildcard origins and mutating methods:** a CORS rule that combines a wildcard origin (`'*'`) with a mutating method (`PUT`, `POST`, or `DELETE`) **throws at synth** — it would let any site issue state-changing cross-origin requests. Specify explicit origins (e.g. `['https://app.example.com']`) for mutating methods. A wildcard origin with only safe methods (`GET`/`HEAD`) is allowed.
+
 ### LifecycleRule
 
 Lifecycle configuration for automatic expiration or storage-class transitions. Supplied via the `lifecycleRules` option.
@@ -184,8 +190,12 @@ const bucket = new FileBucket(scope, 'legacy', {
 });
 ```
 
+> **A wrapped bucket does not receive FileBucket's secure defaults.** When you supply `bucket`, FileBucket binds to the existing bucket as-is and returns early — none of the secure defaults it normally applies are applied: not `enforceSSL`, versioning / noncurrent-version expiration, server access logging, `blockPublicAccess`, encryption, nor the wildcard-CORS guard. You own that bucket's security posture; configure these on the bucket itself (or via its own CDK construct) before wrapping it.
+
 ### Versioned Bucket
 
+Versioning is **on by default**, so the version-aware methods (`listVersions`, `restoreVersion`, and optional `versionId` on `get`/`delete`/`getUrl`/`getFileHandle`) are available without any option. Pass `versioned: false` to opt out (which also removes the `versionId` option typings). The example below passes `versioned: true` explicitly for clarity:
+
 ```typescript
 const bucket = new FileBucket(scope, 'docs', { versioned: true });
 
@@ -205,6 +215,18 @@ export const api = new ApiNamespace(scope, 'api', (context) => ({
 }));
 ```
 
+### Access Logging
+
+Opt in to S3 server access logging. A dedicated, locked-down log bucket is provisioned and access logs expire automatically after the stack posture's `logRetention` (`ONE_WEEK` in sandbox, `ONE_YEAR` in production):
+
+```typescript
+// Logs delivered to a separate locked-down bucket.
+// Retention follows the stack posture's logRetention default — not a per-block option.
+const bucket = new FileBucket(scope, 'uploads', {
+  accessLogging: true,
+});
+```
+
 ## Best Practices
 
 - Use path prefixes to organize files (e.g., `uploads/{userId}/`, `reports/`). If a segment can contain URL-shaped or special characters (e.g. an OIDC `userId` of `${iss}:${sub}` like `https://issuer:sub`), wrap it in `encodeURIComponent()` first — the local mock normalizes `//` in keys via the filesystem, so an un-encoded `//` makes `scan({ prefix })` miss the file locally even though it works against S3.
@@ -213,6 +235,7 @@ export const api = new ApiNamespace(scope, 'api', (context) => ({
 - Prefer `scan({ prefix })` over unscoped `scan()` to limit enumeration cost
 - For browser uploads/downloads returned from API methods, prefer `createUploadHandle`/`getFileHandle` over raw presigned URLs — they encode the fetch protocol into typed methods so the client can't misuse them
 - Use `deleteBatch()` instead of looping `delete()` for bulk operations
+- Versioning is **on by default**; noncurrent (superseded) versions are automatically expired after **90 days** (`noncurrentVersionExpirationDays`, default `90`) so version history doesn't grow storage cost unbounded. Tune the window per-block, or disable versioning (`versioned: false`) to drop the expiration rule along with versioning.
 
 ## Scaling & Cost (AWS)
 

package/dist/file-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-server.d.ts","sourceRoot":"","sources":["../src/file-server.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAmC,MAAM,WAAW,CAAC;AAyCzE,wBAAgB,MAAM,CAAC,UAAU,EAAE,MAAM,QAiKxC"}
+{"version":3,"file":"file-server.d.ts","sourceRoot":"","sources":["../src/file-server.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAmC,MAAM,WAAW,CAAC;AAyCzE,wBAAgB,MAAM,CAAC,UAAU,EAAE,MAAM,QA0KxC"}

package/dist/file-server.js

@@ -53,10 +53,19 @@ export function attach(httpServer) {
         }
         // CORS for browser uploads/downloads
         const origin = req.headers.origin || '*';
+        // Reflecting the request Origin (falling back to '*') is intentional: it
+        // lets a localhost cross-port dev server (e.g. Vite/webpack on a different
+        // port) call this local file-server. This dev file-server is local tooling
+        // only and NEVER deploys to AWS / production.
+        // It is safe because Access-Control-Allow-Credentials is deliberately NOT
+        // set, so the reflected origin carries no ambient credentials: presigned-URL
+        // auth is a query-string token, not a cookie / ambient session. That is what
+        // makes reflecting an arbitrary origin here safe.
+        // WARNING: do not re-add Access-Control-Allow-Credentials and do not
+        // 'tighten' this reflection without understanding the above.
         res.setHeader('Access-Control-Allow-Origin', origin);
         res.setHeader('Access-Control-Allow-Methods', 'GET, PUT, OPTIONS');
         res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
-        res.setHeader('Access-Control-Allow-Credentials', 'true');
         if (req.method === 'OPTIONS') {
             res.writeHead(200);
             res.end();

package/dist/file-server.test.js

@@ -42,6 +42,22 @@ beforeEach(async () => {
 afterEach(() => {
     server.close();
 });
+// ── CORS headers ────────────────────────────────────────────────────────────
+describe('file-server: CORS headers', () => {
+    test('OPTIONS preflight does NOT send Access-Control-Allow-Credentials', async () => {
+        // Reflecting an arbitrary Origin together with credentials:true is an
+        // unsafe combination; the dev server must not advertise credentialed CORS.
+        const res = await fetch(`http://localhost:${port}/.bb-file-bucket/fsrv-cors/ping.txt`, {
+            method: 'OPTIONS',
+            headers: { Origin: 'https://evil.example.com' },
+        });
+        assert.strictEqual(res.status, 200);
+        assert.strictEqual(res.headers.get('access-control-allow-credentials'), null, 'dev server must not send Access-Control-Allow-Credentials');
+        // The other CORS headers remain intact.
+        assert.strictEqual(res.headers.get('access-control-allow-origin'), 'https://evil.example.com');
+        assert.ok(res.headers.get('access-control-allow-methods'));
+    });
+});
 // ── Basic presigned URL round-trip ──────────────────────────────────────────
 describe('file-server: basic GET/PUT', () => {
     test('PUT then GET via presigned URLs', async () => {

package/dist/index.cdk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.cdk.d.ts","sourceRoot":"","sources":["../src/index.cdk.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAA2B,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGhG,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,YAAY,EAAE,iBAAiB,EAAE,UAAU,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAU9K,qBAAa,UAAU,CAAC,CAAC,SAAS,iBAAiB,GAAG,iBAAiB,CAAE,SAAQ,KAAK;IACrF,OAAO,CAAC,MAAM,CAAa;IAE3B;;;;OAIG;IACH,MAAM,CAAC,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,iBAAiB;gBAI9C,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;CAsDvD"}
+{"version":3,"file":"index.cdk.d.ts","sourceRoot":"","sources":["../src/index.cdk.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAA2B,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGhG,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,YAAY,EAAE,iBAAiB,EAAE,UAAU,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAgB9K,qBAAa,UAAU,CAAC,CAAC,SAAS,iBAAiB,GAAG,iBAAiB,CAAE,SAAQ,KAAK;IACrF,OAAO,CAAC,MAAM,CAAa;IAE3B;;;;OAIG;IACH,MAAM,CAAC,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,iBAAiB;gBAI9C,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;CAwJvD"}

package/dist/index.cdk.js

@@ -1,8 +1,8 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 import * as s3 from 'aws-cdk-lib/aws-s3';
-import * as cdk from 'aws-cdk-lib';
 import { Duration, RemovalPolicy } from 'aws-cdk-lib';
+import { RetentionDays } from 'aws-cdk-lib/aws-logs';
 import { Scope } from '@aws-blocks/core/cdk';
 import { validateBucketName } from './bucket-name.js';
 export { FileBucketErrors } from './errors.js';
@@ -13,6 +13,10 @@ const httpMethodMap = {
     DELETE: s3.HttpMethods.DELETE,
     HEAD: s3.HttpMethods.HEAD,
 };
+/** Default number of days after which noncurrent object versions expire. */
+const DEFAULT_NONCURRENT_VERSION_EXPIRATION_DAYS = 90;
+/** HTTP methods that mutate bucket state; unsafe to expose to wildcard origins. */
+const MUTATING_CORS_METHODS = ['PUT', 'POST', 'DELETE'];
 export class FileBucket extends Scope {
     bucket;
     /**
@@ -32,28 +36,120 @@ export class FileBucket extends Scope {
             this.bucket.grantReadWrite(this.executionRole);
             return;
         }
-        // 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);
+        // Resolve durability from the per-block option (a `'destroy'|'retain'`
+        // string, normalized to a CDK RemovalPolicy) falling back to the
+        // stack-wide `defaults`. This replaces the old `sandboxMode` context
+        // read — the sandbox posture now flows in through the chosen preset,
+        // exactly like bb-kv-store. Explicit `removalPolicy` from the customer
+        // still takes precedence. `autoDeleteObjects: true` is only valid paired
+        // with DESTROY (CDK validates this at construct time), so we derive the
+        // two from the same resolved policy.
+        const removalPolicy = options?.removalPolicy === 'destroy'
+            ? RemovalPolicy.DESTROY
+            : options?.removalPolicy === 'retain'
+                ? RemovalPolicy.RETAIN
+                : this.defaults.removalPolicy;
+        const destroy = removalPolicy === RemovalPolicy.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).
+        // Run this first: an unusable bucket name is the most fundamental synth
+        // error, so surface it before the option-level guards below.
         validateBucketName(this.fullId);
+        // Reject unsafe CORS at synth: a wildcard origin ('*') combined with a
+        // mutating method (PUT/POST/DELETE) lets any site issue state-changing
+        // cross-origin requests. Fail loud here rather than deploying it.
+        for (const rule of options?.corsRules ?? []) {
+            if (rule.allowedOrigins.includes('*')) {
+                const mutating = rule.allowedMethods.filter(m => MUTATING_CORS_METHODS.includes(m));
+                if (mutating.length > 0) {
+                    throw new Error(`FileBucket "${this.fullId}": CORS rule with wildcard origin '*' must not allow mutating method(s) ${mutating.join(', ')}. ` +
+                        `Specify explicit allowedOrigins (e.g. 'https://app.example.com') for ${mutating.join(', ')} instead of '*'.`);
+                }
+            }
+        }
+        // Reject a non-positive or non-integer noncurrent-version expiration at
+        // synth whenever the option is provided. A zero, negative, or fractional
+        // value would produce a degenerate lifecycle expiration
+        // (Duration.days(0) / negative) that only surfaces at deploy. The FORMAT
+        // is validated regardless of `versioned` so a malformed value is caught
+        // even when versioning is off; the rule itself is only APPLIED when
+        // versioning is on (see the main-bucket lifecycle rules below).
+        if (options?.noncurrentVersionExpirationDays !== undefined) {
+            const days = options.noncurrentVersionExpirationDays;
+            if (!Number.isInteger(days) || days <= 0) {
+                throw new Error(`FileBucket "${this.fullId}": noncurrentVersionExpirationDays must be a positive integer (got ${days}). ` +
+                    `Omit it to use the default of ${DEFAULT_NONCURRENT_VERSION_EXPIRATION_DAYS} days.`);
+            }
+        }
+        // Versioning stays on by default (secure default): a posture-driven
+        // `versioned` default would require a new `BlocksDefaults` field in
+        // core, which is out of scope for this change, so we keep the
+        // default-on and bound its cost with a noncurrent-version expiration
+        // below.
+        const versioned = options?.versioned ?? true;
+        // Opt-in server access logging: provision a dedicated, locked-down log
+        // bucket and expire its logs after the framework retention. Kept
+        // separate from the data bucket so log delivery can't loop back on it.
+        // Resolves from the stack `defaults.accessLogging` when no per-block
+        // option is given, so a production-postured stack opts every FileBucket
+        // in without a per-block flag.
+        const accessLogging = options?.accessLogging ?? this.defaults.accessLogging;
+        let serverAccessLogsBucket;
+        if (accessLogging) {
+            // The access-log lifecycle expiry derives from the framework-wide
+            // `logRetention` default (a `RetentionDays` enum). `RetentionDays`
+            // is a numeric enum whose member value IS the day count
+            // (ONE_WEEK === 7, ONE_YEAR === 365), so it maps directly to
+            // `Duration.days(...)`. The one non-day member is INFINITE (=== 9999,
+            // "retain forever"): for it we omit the lifecycle rule so logs are
+            // never expired, rather than expiring them at a spurious 9999 days.
+            const logRetention = this.defaults.logRetention;
+            const logLifecycleRules = logRetention === RetentionDays.INFINITE
+                ? undefined
+                : [{ id: 'expire-access-logs', expiration: Duration.days(logRetention) }];
+            serverAccessLogsBucket = new s3.Bucket(this, 'access-logs', {
+                blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
+                encryption: s3.BucketEncryption.S3_MANAGED,
+                enforceSSL: true,
+                removalPolicy,
+                autoDeleteObjects: destroy,
+                lifecycleRules: logLifecycleRules,
+            });
+        }
+        // Main-bucket lifecycle rules: the noncurrent-version expiration (only
+        // when versioning is on, to bound version-storage growth) merged with
+        // any customer-supplied lifecycle rules into a single array.
+        const lifecycleRules = [];
+        if (versioned) {
+            lifecycleRules.push({
+                id: 'ExpireNoncurrentVersions',
+                enabled: true,
+                noncurrentVersionExpiration: Duration.days(options?.noncurrentVersionExpirationDays ?? DEFAULT_NONCURRENT_VERSION_EXPIRATION_DAYS),
+            });
+        }
+        for (const rule of options?.lifecycleRules ?? []) {
+            lifecycleRules.push({
+                prefix: rule.prefix,
+                expiration: rule.expirationDays ? Duration.days(rule.expirationDays) : undefined,
+                transitions: rule.transitionToIaDays ? [{
+                        storageClass: s3.StorageClass.INFREQUENT_ACCESS,
+                        transitionAfter: Duration.days(rule.transitionToIaDays),
+                    }] : undefined,
+            });
+        }
         this.bucket = new s3.Bucket(this, 'bucket', {
             bucketName: this.fullId,
             blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
             encryption: s3.BucketEncryption.S3_MANAGED,
-            versioned: options?.versioned ?? false,
-            removalPolicy: destroy
-                ? RemovalPolicy.DESTROY
-                : options?.removalPolicy === 'retain'
-                    ? RemovalPolicy.RETAIN
-                    : undefined,
+            // All FileBucket traffic (SDK calls + presigned URLs) is HTTPS, so
+            // enforce TLS to close the in-transit exposure gap unconditionally.
+            enforceSSL: true,
+            versioned,
+            removalPolicy,
             autoDeleteObjects: destroy,
+            serverAccessLogsBucket,
+            serverAccessLogsPrefix: serverAccessLogsBucket ? 'access-logs/' : undefined,
             cors: options?.corsRules?.map((rule) => ({
                 allowedOrigins: rule.allowedOrigins,
                 allowedMethods: rule.allowedMethods.map(m => httpMethodMap[m]),
@@ -61,14 +157,7 @@ export class FileBucket extends Scope {
                 exposedHeaders: rule.exposedHeaders,
                 maxAge: rule.maxAge,
             })),
-            lifecycleRules: options?.lifecycleRules?.map((rule) => ({
-                prefix: rule.prefix,
-                expiration: rule.expirationDays ? Duration.days(rule.expirationDays) : undefined,
-                transitions: rule.transitionToIaDays ? [{
-                        storageClass: s3.StorageClass.INFREQUENT_ACCESS,
-                        transitionAfter: Duration.days(rule.transitionToIaDays),
-                    }] : undefined,
-            })),
+            lifecycleRules: lifecycleRules.length > 0 ? lifecycleRules : undefined,
         });
         this.bucket.grantReadWrite(this.executionRole);
     }