@aws-blocks/bb-file-bucket 0.1.0

package/src/file-server.ts

@@ -0,0 +1,203 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Dev server attachment for FileBucket.
+ * Serves token-gated GET/PUT requests at /.bb-file-bucket/{fullId}/{path}?token=...
+ * Mirrors S3 presigned URL behavior: method-scoped, time-limited, path-specific.
+ *
+ * Storage layout mirrors `index.mock.ts` via the shared `paths.ts` helpers, so
+ * user content (under `content/`) is never confused with internal metadata or
+ * version bookkeeping. PUT always delegates to the registered FileBucket
+ * instance so uploads get versioning, key validation, and metadata handling —
+ * there is no direct-write fallback.
+ */
+
+import type { Server, IncomingMessage, ServerResponse } from 'node:http';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isBlocksError } from '@aws-blocks/core';
+import { validateFileToken, LOCAL_FILE_SECRET } from './tokens.js';
+import { assertContainedPath } from './mock-utils.js';
+import { contentRoot, contentPath, metaPath, versionContentPath, versionMetaPath } from './paths.js';
+
+const PREFIX = '/.bb-file-bucket/';
+
+function parseUrl(url: string): { fullId: string; path: string; token: string; versionId?: string } | null {
+	if (!url.startsWith(PREFIX)) return null;
+	const [pathPart, query] = url.slice(PREFIX.length).split('?');
+	if (!pathPart || !query) return null;
+	const params = new URLSearchParams(query);
+	const token = params.get('token');
+	if (!token) return null;
+	const slashIdx = pathPart.indexOf('/');
+	if (slashIdx === -1) return null;
+	return {
+		fullId: pathPart.slice(0, slashIdx),
+		path: decodeURIComponent(pathPart.slice(slashIdx + 1)),
+		token,
+		versionId: params.get('versionId') ?? undefined,
+	};
+}
+
+function collectBody(req: IncomingMessage): Promise<Buffer> {
+	return new Promise((resolve, reject) => {
+		const chunks: Buffer[] = [];
+		req.on('data', (chunk: Buffer) => chunks.push(chunk));
+		req.on('end', () => resolve(Buffer.concat(chunks)));
+		req.on('error', reject);
+	});
+}
+
+function sendError(res: ServerResponse, status: number, error: string): void {
+	res.writeHead(status, { 'Content-Type': 'application/json' });
+	res.end(JSON.stringify({ error }));
+}
+
+export function attach(httpServer: Server) {
+	const originalListeners = httpServer.listeners('request').slice() as Array<(req: IncomingMessage, res: ServerResponse) => void>;
+	httpServer.removeAllListeners('request');
+
+	httpServer.on('request', (req: IncomingMessage, res: ServerResponse) => {
+		const url = req.url || '';
+		if (!url.startsWith(PREFIX)) {
+			// Pass through to original handlers
+			for (const listener of originalListeners) {
+				listener(req, res);
+			}
+			return;
+		}
+
+		// CORS for browser uploads/downloads
+		const origin = req.headers.origin || '*';
+		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();
+			return;
+		}
+
+		const parsed = parseUrl(url);
+		if (!parsed) {
+			sendError(res, 400, 'Invalid file URL');
+			return;
+		}
+
+		const { fullId, path, token, versionId } = parsed;
+		const dataDir = join(process.cwd(), '.bb-data', fullId);
+
+		try {
+			// User keys live under the content root; validate against it so a
+			// traversal attempt can't escape into internal meta/version storage.
+			assertContainedPath(contentRoot(dataDir), path);
+		} catch (err) {
+			const message = isBlocksError(err, 'ValidationFailed') ? err.message : 'Invalid path: traversal detected';
+			sendError(res, 400, message);
+			return;
+		}
+
+		// versionId is attacker-controlled and is joined into a filesystem path
+		// (versionContentPath). It must match the generated format (`v<n>`);
+		// anything else (e.g. `../../../etc/passwd`) is rejected so it can't be
+		// used for path traversal / arbitrary file read.
+		if (versionId !== undefined && !/^v\d{1,10}$/.test(versionId)) {
+			sendError(res, 400, 'Invalid versionId');
+			return;
+		}
+
+		if (req.method === 'GET') {
+			const valid = validateFileToken(token, LOCAL_FILE_SECRET, fullId, path, 'GET');
+			if (!valid) {
+				sendError(res, 403, 'Invalid or expired token');
+				return;
+			}
+
+			// Resolve the file to read — specific version or current
+			let readPath = contentPath(dataDir, path);
+			let metaFilePath = metaPath(dataDir, path);
+			if (versionId) {
+				const vPath = versionContentPath(dataDir, path, versionId);
+				if (existsSync(vPath)) {
+					readPath = vPath;
+					metaFilePath = versionMetaPath(dataDir, path, versionId);
+				}
+			}
+
+			if (!existsSync(readPath)) {
+				sendError(res, 404, 'NoSuchKey');
+				return;
+			}
+
+			let contentType = 'application/octet-stream';
+			if (existsSync(metaFilePath)) {
+				try {
+					const meta = JSON.parse(readFileSync(metaFilePath, 'utf8'));
+					contentType = meta.contentType ?? contentType;
+				} catch {}
+			}
+
+			const body = readFileSync(readPath);
+			res.writeHead(200, { 'Content-Type': contentType, 'Content-Length': body.length.toString() });
+			res.end(body);
+		} else if (req.method === 'PUT') {
+			const valid = validateFileToken(token, LOCAL_FILE_SECRET, fullId, path, 'PUT');
+			if (!valid) {
+				sendError(res, 403, 'Invalid or expired token');
+				return;
+			}
+
+			// PUT delegates to the registered FileBucket instance, which owns the
+			// storage layout (content/meta/versions) plus versioning and key
+			// validation. The dev server and the buckets share a process, so the
+			// instance is always registered in practice; if it's missing, fail
+			// loud rather than silently writing an unversioned object.
+			const registry: Map<string, { put?: unknown }> | undefined = (globalThis as any).__BLOCKS_FILE_BUCKET_REGISTRY__;
+			const bucket = registry?.get(fullId);
+			if (!bucket || typeof bucket.put !== 'function') {
+				sendError(res, 500, `No FileBucket registered for "${fullId}" — cannot handle upload`);
+				return;
+			}
+
+			// Content-Type parity with real S3: when a presigned PUT URL is
+			// minted with a contentType, the AWS SDK adds `content-type` to the
+			// signed headers, so S3 returns 403 SignatureDoesNotMatch if the
+			// uploaded request's Content-Type differs from (or omits) the signed
+			// value. The mock used to ignore the request header entirely and
+			// accept any upload, masking a failure that only surfaced in prod.
+			// Enforce the same check here so a mismatch fails loudly in local dev.
+			const requestContentType = req.headers['content-type'];
+			if (valid.contentType !== undefined && requestContentType !== valid.contentType) {
+				sendError(
+					res,
+					403,
+					`SignatureDoesNotMatch: request Content-Type ${
+						requestContentType === undefined ? '(missing)' : `"${requestContentType}"`
+					} does not match the signed Content-Type "${valid.contentType}". ` +
+						`Send the same Content-Type header that was used to create the upload URL.`,
+				);
+				return;
+			}
+
+			collectBody(req).then(async (body) => {
+				// When a contentType was signed, it equals the (now validated)
+				// request header. Otherwise fall back to whatever the request
+				// sent, then octet-stream — matching S3's stored content type.
+				const contentType = valid.contentType || requestContentType || 'application/octet-stream';
+				await (bucket.put as (p: string, b: Buffer, o: { contentType: string }) => Promise<void>)(
+					path, body, { contentType },
+				);
+				res.writeHead(200);
+				res.end();
+			}).catch((err) => {
+				sendError(res, 500, err instanceof Error ? err.message : String(err));
+			});
+		} else {
+			res.writeHead(405);
+			res.end();
+		}
+	});
+}

package/src/index.aws.ts

@@ -0,0 +1,219 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+	S3Client,
+	PutObjectCommand,
+	GetObjectCommand,
+	DeleteObjectCommand,
+	DeleteObjectsCommand,
+	ListObjectsV2Command,
+	ListObjectVersionsCommand,
+	CopyObjectCommand,
+} from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+import { Scope, registerSdkIdentifiers, getSdkIdentifiers } from '@aws-blocks/core';
+import type { ScopeParent } from '@aws-blocks/core';
+import { BB_NAME, BB_VERSION } from './version.js';
+import type {
+	FileBucketOptions, PutOptions, PutUrlOptions, ScanOptions,
+	FileContent, FileInfo, ExternalBucketRef,
+	FileDownloadClient, FileUploadClient, FileVersionInfo,
+	GetOptionsFor, DeleteOptionsFor, GetUrlOptionsFor,
+} from './types.js';
+import { Logger } from '@aws-blocks/bb-logger';
+import type { ChildLogger } from '@aws-blocks/bb-logger';
+
+// Re-export public types
+export { FileBucketErrors } from './errors.js';
+export type {
+	FileBucketOptions, PutOptions, GetUrlOptions, PutUrlOptions, ScanOptions,
+	FileContent, FileInfo, CorsRule, LifecycleRule, ExternalBucketRef,
+	FileDownloadClient, FileUploadClient, FileVersionInfo,
+	FileDownloadDescriptor, FileUploadDescriptor,
+	VersionedGetOptions, VersionedDeleteOptions, VersionedGetUrlOptions,
+	GetOptionsFor, DeleteOptionsFor, GetUrlOptionsFor,
+} from './types.js';
+
+/**
+ * File storage backed by Amazon S3.
+ *
+ * **When to use:** You need to store, retrieve, or serve binary files —
+ * user uploads, generated reports, images, videos, or static assets.
+ *
+ * **When NOT to use:** If you need structured key-value data with conditional
+ * writes, use `KVStore`. If you need queryable records with indexes, use
+ * `DistributedTable`.
+ *
+ * **Best practices:**
+ * - Use path prefixes to organize files (e.g., `uploads/{userId}/`, `reports/`)
+ * - Set `contentType` on `put()` to ensure correct MIME handling on download
+ * - Use `getFileHandle` / `createUploadHandle` for ergonomic browser file transfers
+ * - Use presigned URLs (`getUrl` / `putUrl`) when you need direct URL control
+ * - Prefer `scan({ prefix })` over unscoped `scan()` to limit enumeration cost
+ *
+ * **Scaling:** S3 scales automatically. No provisioned throughput. Costs are
+ * per-request plus storage. Individual objects up to 5 TB. For objects larger
+ * than ~100 MB, consider multipart upload.
+ */
+export class FileBucket<O extends FileBucketOptions = FileBucketOptions> extends Scope {
+	readonly bbName = BB_NAME;
+	private s3: S3Client;
+
+	/** @internal Logger for internal operations. Defaults to error-level when not provided. */
+	protected log: ChildLogger;
+
+	constructor(scope: ScopeParent, id: string, options?: O) {
+		super(id, { parent: scope, bbName: BB_NAME, bbVersion: BB_VERSION });
+		this.log = options?.logger ?? new Logger(this, 'logger', { level: 'error' });
+		this.registerClientMiddleware('@aws-blocks/bb-file-bucket/middleware');
+		const bucketName = options?.bucket ? options.bucket.bucketName : this.fullId;
+		registerSdkIdentifiers(this.fullId, { bucketName });
+		this.s3 = new S3Client({
+			customUserAgent: this.buildUserAgentChain(),
+		});
+	}
+
+	async put(path: string, body: Buffer | string, options?: PutOptions): Promise<void> {
+		await this.s3.send(new PutObjectCommand({
+			Bucket: getSdkIdentifiers(this).bucketName,
+			Key: path,
+			Body: typeof body === 'string' ? Buffer.from(body) : body,
+			ContentType: options?.contentType,
+			Metadata: options?.metadata,
+			CacheControl: options?.cacheControl,
+		}));
+	}
+
+	async get(path: string, options?: GetOptionsFor<O>): Promise<FileContent | null> {
+		try {
+			const result = await this.s3.send(new GetObjectCommand({
+				Bucket: getSdkIdentifiers(this).bucketName, Key: path,
+				...(options ? { VersionId: (options as any).versionId } : {}),
+			}));
+			const bytes = await result.Body!.transformToByteArray();
+			return {
+				body: Buffer.from(bytes),
+				contentType: result.ContentType ?? 'application/octet-stream',
+				metadata: result.Metadata ?? {},
+				size: result.ContentLength ?? bytes.length,
+			};
+		} catch (e: any) {
+			if (e.name === 'NoSuchKey') return null;
+			throw e;
+		}
+	}
+
+	async delete(path: string, options?: DeleteOptionsFor<O>): Promise<void> {
+		await this.s3.send(new DeleteObjectCommand({
+			Bucket: getSdkIdentifiers(this).bucketName, Key: path,
+			...(options ? { VersionId: (options as any).versionId } : {}),
+		}));
+	}
+
+	async deleteBatch(paths: string[]): Promise<void> {
+		const CHUNK_SIZE = 1000;
+		for (let i = 0; i < paths.length; i += CHUNK_SIZE) {
+			const chunk = paths.slice(i, i + CHUNK_SIZE);
+			await this.s3.send(new DeleteObjectsCommand({
+				Bucket: getSdkIdentifiers(this).bucketName,
+				Delete: { Objects: chunk.map(Key => ({ Key })), Quiet: true },
+			}));
+		}
+	}
+
+	async getUrl(path: string, options?: GetUrlOptionsFor<O>): Promise<string> {
+		const opts = options as any;
+		return getSignedUrl(this.s3, new GetObjectCommand({
+			Bucket: getSdkIdentifiers(this).bucketName, Key: path,
+			...(opts?.versionId ? { VersionId: opts.versionId } : {}),
+		}), {
+			expiresIn: opts?.expiresIn ?? 3600,
+		});
+	}
+
+	async putUrl(path: string, options?: PutUrlOptions): Promise<string> {
+		return getSignedUrl(this.s3, new PutObjectCommand({
+			Bucket: getSdkIdentifiers(this).bucketName, Key: path, ContentType: options?.contentType,
+		}), { expiresIn: options?.expiresIn ?? 3600 });
+	}
+
+	async getFileHandle(path: string, options?: GetUrlOptionsFor<O>): Promise<FileDownloadClient> {
+		const url = await this.getUrl(path, options);
+		return {
+			download: async () => {
+				const res = await fetch(url);
+				if (!res.ok) throw new Error(`Download failed: ${res.status}`);
+				return res.blob();
+			},
+			getUrl: () => url,
+			toJSON: () => ({ __blocks: 'file-bucket/download' as const, url }),
+		};
+	}
+
+	async createUploadHandle(path: string, options?: PutUrlOptions): Promise<FileUploadClient> {
+		const url = await this.putUrl(path, options);
+		const contentType = options?.contentType;
+		return {
+			upload: async (body: Blob | File | ArrayBuffer) => {
+				const headers: Record<string, string> = {};
+				if (contentType) headers['Content-Type'] = contentType;
+				const res = await fetch(url, { method: 'PUT', body, headers });
+				if (!res.ok) throw new Error(`Upload failed: ${res.status}`);
+			},
+			getUrl: () => url,
+			toJSON: () => ({ __blocks: 'file-bucket/upload' as const, url, contentType }),
+		};
+	}
+
+	async *scan(options?: ScanOptions): AsyncIterable<FileInfo> {
+		let continuationToken: string | undefined;
+		do {
+			const result = await this.s3.send(new ListObjectsV2Command({
+				Bucket: getSdkIdentifiers(this).bucketName, Prefix: options?.prefix, ContinuationToken: continuationToken,
+			}));
+			for (const obj of result.Contents ?? []) {
+				yield { path: obj.Key!, size: obj.Size ?? 0, lastModified: obj.LastModified ?? new Date() };
+			}
+			continuationToken = result.NextContinuationToken;
+		} while (continuationToken);
+	}
+
+	async listVersions(path: string): Promise<FileVersionInfo[]> {
+		const versions: FileVersionInfo[] = [];
+		let keyMarker: string | undefined;
+		let versionIdMarker: string | undefined;
+		do {
+			const result = await this.s3.send(new ListObjectVersionsCommand({
+				Bucket: getSdkIdentifiers(this).bucketName, Prefix: path, KeyMarker: keyMarker, VersionIdMarker: versionIdMarker,
+			}));
+			for (const v of result.Versions ?? []) {
+				if (v.Key !== path) continue; // prefix match may include other keys
+				versions.push({
+					versionId: v.VersionId!,
+					lastModified: v.LastModified ?? new Date(),
+					size: v.Size ?? 0,
+					isCurrent: v.IsLatest ?? false,
+				});
+			}
+			keyMarker = result.NextKeyMarker;
+			versionIdMarker = result.NextVersionIdMarker;
+		} while (keyMarker);
+		// Newest first
+		versions.sort((a, b) => b.lastModified.getTime() - a.lastModified.getTime());
+		return versions;
+	}
+
+	async restoreVersion(path: string, versionId: string): Promise<void> {
+		const encodedPath = path.split('/').map(s => encodeURIComponent(s)).join('/');
+		await this.s3.send(new CopyObjectCommand({
+			Bucket: getSdkIdentifiers(this).bucketName,
+			Key: path,
+			CopySource: `${getSdkIdentifiers(this).bucketName}/${path}?versionId=${versionId}`,
+		}));
+	}
+
+	static fromExisting(bucketName: string): ExternalBucketRef {
+		return { __brand: 'ExternalBucketRef' as const, bucketName };
+	}
+}

package/src/index.browser.ts

@@ -0,0 +1,7 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+// Browser stub - FileBucket runs server-side only
+export class FileBucket {
+  constructor(...args: any[]) {}
+}

package/src/index.cdk.test.ts

@@ -0,0 +1,84 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * CDK-side regression tests for FileBucket.
+ *
+ * History: FileBucket.fromExisting was advertised in types but the CDK
+ * constructor unconditionally provisioned a new S3 bucket. These tests pin
+ * the fix.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert';
+import * as cdk from 'aws-cdk-lib';
+import type { Construct } from 'constructs';
+import { Template } from 'aws-cdk-lib/assertions';
+import { Scope, DEFAULT_NODE_RUNTIME } from '@aws-blocks/core/cdk';
+import { FileBucket } from './index.cdk.js';
+
+class StubBlocksStack extends cdk.Stack {
+  public readonly handler: cdk.aws_lambda.Function;
+  public readonly id: string;
+  constructor(scope: Construct, id: string) {
+    super(scope, id);
+    this.id = id;
+    (globalThis as any).CURRENT_BLOCKS_STACK = this;
+    this.handler = new cdk.aws_lambda.Function(this, 'StubHandler', {
+      runtime: DEFAULT_NODE_RUNTIME,
+      handler: 'index.handler',
+      code: cdk.aws_lambda.Code.fromInline('exports.handler = async () => {};'),
+    });
+  }
+}
+
+function setup(): { stack: StubBlocksStack; parent: Scope } {
+  const app = new cdk.App();
+  // 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');
+  const parent = new Scope('app');
+  return { stack, parent };
+}
+
+test('CDK: default FileBucket provisions an S3 bucket', () => {
+  const { stack, parent } = setup();
+  new FileBucket(parent, 'uploads');
+  const template = Template.fromStack(stack);
+  template.resourceCountIs('AWS::S3::Bucket', 1);
+});
+
+test('CDK: FileBucket.fromExisting does NOT provision a bucket (regression)', () => {
+  const { stack, parent } = setup();
+  new FileBucket(parent, 'uploads', {
+    bucket: FileBucket.fromExisting('preexisting-bucket-123'),
+  });
+  const template = Template.fromStack(stack);
+  template.resourceCountIs('AWS::S3::Bucket', 0);
+});
+
+test('CDK: FileBucket.fromExisting returns a branded ref', () => {
+  const ref = FileBucket.fromExisting('foo');
+  assert.strictEqual(ref.bucketName, 'foo');
+  assert.strictEqual(ref.__brand, 'ExternalBucketRef');
+});
+
+test('CDK: default FileBucket with an over-long derived name throws at synth', () => {
+  const { parent } = setup();
+  // parent id "app" + "-" + a 60-char id => 64 chars, over the S3 limit.
+  assert.throws(
+    () => new FileBucket(parent, 'u'.repeat(60)),
+    (err: unknown) =>
+      err instanceof Error &&
+      err.name === 'ValidationFailed' &&
+      /63-character limit/.test(err.message),
+  );
+});
+
+test('CDK: fromExisting skips derived-name validation even when the chain is over-long', () => {
+  const { parent } = setup();
+  assert.doesNotThrow(() =>
+    new FileBucket(parent, 'u'.repeat(60), {
+      bucket: FileBucket.fromExisting('preexisting-bucket-123'),
+    }),
+  );
+});

package/src/index.cdk.ts

@@ -0,0 +1,89 @@
+// 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 { Scope } from '@aws-blocks/core/cdk';
+import type { ScopeParent } from '@aws-blocks/core';
+import type { FileBucketOptions, CorsRule, LifecycleRule, ExternalBucketRef } from './types.js';
+import { validateBucketName } from './bucket-name.js';
+
+export { FileBucketErrors } from './errors.js';
+export type { FileBucketOptions, PutOptions, GetUrlOptions, PutUrlOptions, ScanOptions, FileContent, FileInfo, CorsRule, LifecycleRule, ExternalBucketRef } from './types.js';
+
+const httpMethodMap: Record<string, s3.HttpMethods> = {
+	GET: s3.HttpMethods.GET,
+	PUT: s3.HttpMethods.PUT,
+	POST: s3.HttpMethods.POST,
+	DELETE: s3.HttpMethods.DELETE,
+	HEAD: s3.HttpMethods.HEAD,
+};
+
+export class FileBucket<O extends FileBucketOptions = FileBucketOptions> extends Scope {
+	private bucket: s3.IBucket;
+
+	/**
+	 * Reference an existing S3 bucket instead of provisioning a new one.
+	 * Mirrors the same factory exposed by the runtime build so the same code
+	 * works in both contexts.
+	 */
+	static fromExisting(bucketName: string): ExternalBucketRef {
+		return { __brand: 'ExternalBucketRef' as const, bucketName };
+	}
+
+	constructor(scope: ScopeParent, id: string, options?: O) {
+		super(id, { parent: scope });
+
+		if (options?.bucket) {
+			// `fromExisting`: don't provision; bind to the pre-existing bucket and
+			// grant read/write to the Blocks runtime Lambda.
+			this.bucket = s3.Bucket.fromBucketName(this, 'bucket', options.bucket.bucketName);
+			this.bucket.grantReadWrite(this.handler);
+			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);
+
+		// 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).
+		validateBucketName(this.fullId);
+
+		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,
+			autoDeleteObjects: destroy,
+			cors: options?.corsRules?.map((rule: CorsRule) => ({
+				allowedOrigins: rule.allowedOrigins,
+				allowedMethods: rule.allowedMethods.map(m => httpMethodMap[m]),
+				allowedHeaders: rule.allowedHeaders,
+				exposedHeaders: rule.exposedHeaders,
+				maxAge: rule.maxAge,
+			})),
+			lifecycleRules: options?.lifecycleRules?.map((rule: LifecycleRule) => ({
+				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.grantReadWrite(this.handler);
+	}
+}