@aws-blocks/bb-file-bucket 0.1.0

package/src/bucket-name.test.ts

@@ -0,0 +1,103 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Tests for the shared S3 bucket-name validator and its enforcement in the
+ * mock entry point. The CDK side is covered in index.cdk.test.ts; this file
+ * pins the validator rules and the local-dev (mock) parity behavior.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert';
+import { Scope, isBlocksError } from '@aws-blocks/core';
+import { validateBucketName } from './bucket-name.js';
+import { FileBucket } from './index.mock.js';
+
+// ── Validator unit tests ─────────────────────────────────────────────────────
+
+test('accepts a valid lowercase hyphenated name', () => {
+	assert.doesNotThrow(() => validateBucketName('myapp-uploads'));
+});
+
+test('accepts a name at exactly 63 characters', () => {
+	const name = 'a'.repeat(63);
+	assert.doesNotThrow(() => validateBucketName(name));
+});
+
+test('rejects a name over 63 characters with an actionable message', () => {
+	const name = 'a'.repeat(64);
+	assert.throws(
+		() => validateBucketName(name),
+		(err: unknown) =>
+			isBlocksError(err, 'ValidationFailed') &&
+			/64 characters/.test((err as Error).message) &&
+			/63-character limit/.test((err as Error).message) &&
+			/Shorten/.test((err as Error).message),
+	);
+});
+
+test('rejects a name under 3 characters', () => {
+	assert.throws(
+		() => validateBucketName('ab'),
+		(err: unknown) => isBlocksError(err, 'ValidationFailed') && /at least 3/.test((err as Error).message),
+	);
+});
+
+test('rejects uppercase characters', () => {
+	assert.throws(
+		() => validateBucketName('MyApp-Uploads'),
+		(err: unknown) => isBlocksError(err, 'ValidationFailed') && /lowercase/.test((err as Error).message),
+	);
+});
+
+test('rejects underscores', () => {
+	assert.throws(
+		() => validateBucketName('my_app_uploads'),
+		(err: unknown) => isBlocksError(err, 'ValidationFailed'),
+	);
+});
+
+test('rejects a name not starting with a letter or number', () => {
+	assert.throws(
+		() => validateBucketName('-myapp'),
+		(err: unknown) => isBlocksError(err, 'ValidationFailed') && /begin and end/.test((err as Error).message),
+	);
+});
+
+test('rejects a name not ending with a letter or number', () => {
+	assert.throws(
+		() => validateBucketName('myapp-'),
+		(err: unknown) => isBlocksError(err, 'ValidationFailed') && /begin and end/.test((err as Error).message),
+	);
+});
+
+test('rejects adjacent dots', () => {
+	assert.throws(
+		() => validateBucketName('my..app'),
+		(err: unknown) => isBlocksError(err, 'ValidationFailed') && /adjacent dots/.test((err as Error).message),
+	);
+});
+
+// ── Mock parity: construction enforces the same rules ────────────────────────
+
+test('mock: constructing a FileBucket with a too-long derived name throws', () => {
+	// Parent id + child id joined with "-" must exceed 63 chars.
+	const longParent = new Scope('p'.repeat(60));
+	assert.throws(
+		() => new FileBucket(longParent, 'uploads'),
+		(err: unknown) => isBlocksError(err, 'ValidationFailed') && /63-character limit/.test((err as Error).message),
+	);
+});
+
+test('mock: constructing a FileBucket with a valid derived name succeeds', () => {
+	const parent = new Scope('shortapp');
+	assert.doesNotThrow(() => new FileBucket(parent, 'uploads'));
+});
+
+test('mock: fromExisting bypasses derived-name validation', () => {
+	// An over-long scope chain would normally fail, but fromExisting wraps an
+	// externally-named bucket so the derived name is not used.
+	const longParent = new Scope('p'.repeat(60));
+	assert.doesNotThrow(() =>
+		new FileBucket(longParent, 'uploads', { bucket: FileBucket.fromExisting('preexisting-bucket-123') }),
+	);
+});

package/src/bucket-name.ts

@@ -0,0 +1,83 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * S3 bucket-name validation, shared by the CDK (synth) and mock (local dev)
+ * entry points so a name that would be rejected by CloudFormation fails the
+ * same way during `bb dev` — long before a deploy is attempted.
+ *
+ * Bucket names are derived from the scope chain (`scope.fullId`). Because S3
+ * bucket names are globally unique and immutable, we deliberately error rather
+ * than silently truncate/hash: a truncated name could collide, and a name that
+ * shifts between deploys would orphan or replace the customer's data. The fix
+ * belongs in the developer's hands — shorten a scope id once and the name is
+ * stable forever.
+ *
+ * Rules enforced (AWS general-purpose bucket naming):
+ * - 3–63 characters
+ * - lowercase letters, numbers, dots (`.`), and hyphens (`-`) only
+ * - must begin and end with a letter or number
+ * - must not contain two adjacent dots
+ *
+ * @see https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html
+ */
+
+const MIN_LEN = 3;
+const MAX_LEN = 63;
+
+function blocksError(name: string, message: string): Error {
+	const err = new Error(`${name}: ${message}`);
+	err.name = name;
+	return err;
+}
+
+/**
+ * Validate an auto-derived S3 bucket name. Throws a `ValidationFailed` error
+ * with an actionable message when the name violates an S3 naming rule.
+ *
+ * @param name - The bucket name (the scope's `fullId`).
+ * @throws {Error} With name `ValidationFailed` if the name is invalid.
+ */
+export function validateBucketName(name: string): void {
+	const hint =
+		`FileBucket names are derived from the scope chain (id of the bucket ` +
+		`plus its parent scopes, joined with "-"). Shorten the FileBucket id ` +
+		`or a parent scope id, or pass an existing bucket via ` +
+		`FileBucket.fromExisting(...).`;
+
+	if (name.length > MAX_LEN) {
+		throw blocksError(
+			'ValidationFailed',
+			`Derived bucket name "${name}" is ${name.length} characters, ` +
+				`exceeding S3's ${MAX_LEN}-character limit. ${hint}`,
+		);
+	}
+	if (name.length < MIN_LEN) {
+		throw blocksError(
+			'ValidationFailed',
+			`Derived bucket name "${name}" is ${name.length} characters; ` +
+				`S3 requires at least ${MIN_LEN}. ${hint}`,
+		);
+	}
+	if (!/^[a-z0-9.-]+$/.test(name)) {
+		throw blocksError(
+			'ValidationFailed',
+			`Derived bucket name "${name}" contains characters that are invalid ` +
+				`for an S3 bucket. Use only lowercase letters, numbers, dots (.), ` +
+				`and hyphens (-). ${hint}`,
+		);
+	}
+	if (!/^[a-z0-9]/.test(name) || !/[a-z0-9]$/.test(name)) {
+		throw blocksError(
+			'ValidationFailed',
+			`Derived bucket name "${name}" must begin and end with a lowercase ` +
+				`letter or number. ${hint}`,
+		);
+	}
+	if (name.includes('..')) {
+		throw blocksError(
+			'ValidationFailed',
+			`Derived bucket name "${name}" must not contain two adjacent dots. ${hint}`,
+		);
+	}
+}

package/src/errors.ts

@@ -0,0 +1,22 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Typed error constants for FileBucket. Use with `isBlocksError()` in catch blocks.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const file = await bucket.get('missing.txt');
+ * } catch (e: unknown) {
+ *   if (isBlocksError(e, FileBucketErrors.FileNotFound)) {
+ *     // file does not exist
+ *   }
+ *   throw e;
+ * }
+ * ```
+ */
+export const FileBucketErrors = {
+	FileNotFound: 'NoSuchKey',
+	FileTooLarge: 'EntityTooLarge',
+} as const;

package/src/file-server.test.ts

@@ -0,0 +1,381 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Tests for the dev file-server attachment — presigned URL serving,
+ * path encoding/decoding, and versioning integration.
+ */
+
+import { test, describe, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert';
+import { rmSync, existsSync, readdirSync } from 'node:fs';
+import { createServer } from 'node:http';
+import type { Server } from 'node:http';
+import { Scope } from '@aws-blocks/core';
+import { FileBucket } from './index.mock.js';
+import { attach } from './file-server.js';
+import { mintFileToken, LOCAL_FILE_SECRET } from './tokens.js';
+
+const scope = new Scope('fsrv');
+
+let server: Server;
+let port: number;
+
+beforeEach(async () => {
+	const dir = '.bb-data';
+	try {
+		if (existsSync(dir)) {
+			for (const entry of readdirSync(dir)) {
+				if (entry.startsWith('fsrv-')) {
+					rmSync(`${dir}/${entry}`, { recursive: true, force: true });
+				}
+			}
+		}
+	} catch {}
+	server = createServer((_req, res) => {
+		res.writeHead(404);
+		res.end('not found');
+	});
+	attach(server);
+	port = await new Promise<number>((resolve) => {
+		server.listen(0, () => {
+			const addr = server.address();
+			resolve(typeof addr === 'object' && addr ? addr.port : 0);
+		});
+	});
+});
+
+afterEach(() => {
+	server.close();
+});
+
+// ── Basic presigned URL round-trip ──────────────────────────────────────────
+
+describe('file-server: basic GET/PUT', () => {
+	test('PUT then GET via presigned URLs', async () => {
+		const bucket = new FileBucket(scope, 'fs-basic');
+		const putUrl = await bucket.putUrl('hello.txt', { contentType: 'text/plain' });
+		const adjustedPut = putUrl.replace(/localhost:\d+/, `localhost:${port}`);
+
+		const putRes = await fetch(adjustedPut, {
+			method: 'PUT',
+			body: 'hello world',
+			headers: { 'Content-Type': 'text/plain' },
+		});
+		assert.strictEqual(putRes.status, 200, `PUT failed: ${putRes.status}`);
+
+		const getUrl = await bucket.getUrl('hello.txt');
+		const adjustedGet = getUrl.replace(/localhost:\d+/, `localhost:${port}`);
+
+		const getRes = await fetch(adjustedGet);
+		assert.strictEqual(getRes.status, 200, `GET failed: ${getRes.status}`);
+		assert.strictEqual(await getRes.text(), 'hello world');
+	});
+
+	test('GET non-existent file returns 404', async () => {
+		const bucket = new FileBucket(scope, 'fs-404');
+		const url = await bucket.getUrl('missing.txt');
+		const adjusted = url.replace(/localhost:\d+/, `localhost:${port}`);
+
+		const res = await fetch(adjusted);
+		assert.strictEqual(res.status, 404);
+	});
+
+	test('invalid token returns 403', async () => {
+		const url = `http://localhost:${port}/.bb-file-bucket/root-test/file.txt?token=invalid.token`;
+		const res = await fetch(url);
+		assert.strictEqual(res.status, 403);
+	});
+
+	test('PUT for an unregistered bucket fails loud (500), no silent write', async () => {
+		// Mint a structurally valid token for a fullId that has no FileBucket
+		// instance registered. The server must refuse rather than fall back to
+		// an unversioned direct write.
+		const unknownId = 'fsrv-unregistered';
+		const token = mintFileToken(unknownId, 'orphan.txt', 'PUT', 3600, LOCAL_FILE_SECRET, 'text/plain');
+		const url = `http://localhost:${port}/.bb-file-bucket/${unknownId}/orphan.txt?token=${token}`;
+
+		const res = await fetch(url, {
+			method: 'PUT',
+			body: 'should not be written',
+			headers: { 'Content-Type': 'text/plain' },
+		});
+		assert.strictEqual(res.status, 500, `Expected 500 for unregistered bucket, got ${res.status}`);
+	});
+});
+
+// ── Content-Type parity with S3 presigned PUT ───────────────────────────────
+
+describe('file-server: Content-Type signing parity', () => {
+	test('PUT with a Content-Type that differs from the signed value returns 403', async () => {
+		const bucket = new FileBucket(scope, 'fs-ct1');
+		// URL is signed for image/png …
+		const putUrl = await bucket.putUrl('avatar', { contentType: 'image/png' });
+		const adjusted = putUrl.replace(/localhost:\d+/, `localhost:${port}`);
+
+		// … but the client uploads with image/jpeg. Real S3 rejects this with
+		// SignatureDoesNotMatch; the mock must do the same so the failure shows
+		// up locally instead of only in prod.
+		const res = await fetch(adjusted, {
+			method: 'PUT',
+			body: 'fake png bytes',
+			headers: { 'Content-Type': 'image/jpeg' },
+		});
+		assert.strictEqual(res.status, 403, `Expected 403 for mismatched Content-Type, got ${res.status}`);
+
+		// And nothing was written.
+		assert.strictEqual(await bucket.get('avatar'), null, 'mismatched upload must not be stored');
+	});
+
+	test('PUT omitting Content-Type when one was signed returns 403', async () => {
+		const bucket = new FileBucket(scope, 'fs-ct2');
+		const putUrl = await bucket.putUrl('doc.pdf', { contentType: 'application/pdf' });
+		const adjusted = putUrl.replace(/localhost:\d+/, `localhost:${port}`);
+
+		// node-fetch/undici defaults a string body to text/plain; send an empty
+		// body with no explicit Content-Type isn't reliable across runtimes, so
+		// assert the realistic case: a wrong/absent signed header is rejected.
+		const res = await fetch(adjusted, {
+			method: 'PUT',
+			body: new Blob(['data']), // Blob with no type → Content-Type omitted by undici
+		});
+		assert.strictEqual(res.status, 403, `Expected 403 when signed Content-Type is missing, got ${res.status}`);
+	});
+
+	test('PUT with a matching Content-Type succeeds and stores it', async () => {
+		const bucket = new FileBucket(scope, 'fs-ct3');
+		const putUrl = await bucket.putUrl('report.csv', { contentType: 'text/csv' });
+		const adjusted = putUrl.replace(/localhost:\d+/, `localhost:${port}`);
+
+		const res = await fetch(adjusted, {
+			method: 'PUT',
+			body: 'a,b,c',
+			headers: { 'Content-Type': 'text/csv' },
+		});
+		assert.strictEqual(res.status, 200, `Expected 200 for matching Content-Type, got ${res.status}`);
+
+		const file = await bucket.get('report.csv');
+		assert.ok(file, 'matching upload should be stored');
+		assert.strictEqual(file.contentType, 'text/csv');
+		assert.strictEqual(file.body.toString(), 'a,b,c');
+	});
+
+	test('createUploadHandle round-trips because it sends the signed Content-Type', async () => {
+		// The typed handle path sets the request header from the same value it
+		// signs, so it stays consistent across mock and prod. This pins that the
+		// new enforcement does not regress the happy path.
+		const bucket = new FileBucket(scope, 'fs-ct4');
+		const handle = await bucket.createUploadHandle('photo.jpg', { contentType: 'image/jpeg' });
+		const adjusted = handle.getUrl().replace(/localhost:\d+/, `localhost:${port}`);
+
+		const res = await fetch(adjusted, {
+			method: 'PUT',
+			body: 'jpeg bytes',
+			headers: { 'Content-Type': 'image/jpeg' },
+		});
+		assert.strictEqual(res.status, 200, `Expected 200, got ${res.status}`);
+
+		const file = await bucket.get('photo.jpg');
+		assert.ok(file);
+		assert.strictEqual(file.contentType, 'image/jpeg');
+	});
+
+	test('PUT without a signed Content-Type accepts any request header', async () => {
+		// putUrl without contentType signs no content-type, mirroring an S3
+		// presigned URL that did not include it — any upload header is allowed.
+		const bucket = new FileBucket(scope, 'fs-ct5');
+		const putUrl = await bucket.putUrl('blob.bin');
+		const adjusted = putUrl.replace(/localhost:\d+/, `localhost:${port}`);
+
+		const res = await fetch(adjusted, {
+			method: 'PUT',
+			body: 'anything',
+			headers: { 'Content-Type': 'application/x-custom' },
+		});
+		assert.strictEqual(res.status, 200, `Expected 200 when no Content-Type was signed, got ${res.status}`);
+
+		const file = await bucket.get('blob.bin');
+		assert.ok(file);
+		assert.strictEqual(file.contentType, 'application/x-custom');
+	});
+});
+
+// ── Path encoding/decoding ──────────────────────────────────────────────────
+
+describe('file-server: URL-encoded paths', () => {
+	test('GET with spaces in path (encoded as %20)', async () => {
+		const bucket = new FileBucket(scope, 'fs-enc1');
+		await bucket.put('my folder/my file.txt', 'spaced content', { contentType: 'text/plain' });
+
+		const token = mintFileToken('fsrv-fs-enc1', 'my folder/my file.txt', 'GET', 3600, LOCAL_FILE_SECRET);
+		const encodedPath = 'my%20folder/my%20file.txt';
+		const url = `http://localhost:${port}/.bb-file-bucket/fsrv-fs-enc1/${encodedPath}?token=${token}`;
+
+		const res = await fetch(url);
+		assert.strictEqual(res.status, 200, `Expected 200, got ${res.status}: ${await res.clone().text()}`);
+		assert.strictEqual(await res.text(), 'spaced content');
+	});
+
+	test('GET with # in filename (encoded as %23)', async () => {
+		const bucket = new FileBucket(scope, 'fs-enc2');
+		await bucket.put('file#1.txt', 'hash content', { contentType: 'text/plain' });
+
+		const token = mintFileToken('fsrv-fs-enc2', 'file#1.txt', 'GET', 3600, LOCAL_FILE_SECRET);
+		const url = `http://localhost:${port}/.bb-file-bucket/fsrv-fs-enc2/file%231.txt?token=${token}`;
+
+		const res = await fetch(url);
+		assert.strictEqual(res.status, 200, `Expected 200, got ${res.status}: ${await res.clone().text()}`);
+		assert.strictEqual(await res.text(), 'hash content');
+	});
+
+	test('GET with + in filename (should not decode as space)', async () => {
+		const bucket = new FileBucket(scope, 'fs-enc3');
+		await bucket.put('a+b.txt', 'plus content', { contentType: 'text/plain' });
+
+		const token = mintFileToken('fsrv-fs-enc3', 'a+b.txt', 'GET', 3600, LOCAL_FILE_SECRET);
+		const url = `http://localhost:${port}/.bb-file-bucket/fsrv-fs-enc3/a%2Bb.txt?token=${token}`;
+
+		const res = await fetch(url);
+		assert.strictEqual(res.status, 200, `Expected 200, got ${res.status}: ${await res.clone().text()}`);
+		assert.strictEqual(await res.text(), 'plus content');
+	});
+
+	test('GET with unicode characters (encoded)', async () => {
+		const bucket = new FileBucket(scope, 'fs-enc4');
+		await bucket.put('文件/数据.txt', 'unicode content', { contentType: 'text/plain' });
+
+		const token = mintFileToken('fsrv-fs-enc4', '文件/数据.txt', 'GET', 3600, LOCAL_FILE_SECRET);
+		const encodedPath = encodeURIComponent('文件') + '/' + encodeURIComponent('数据.txt');
+		const url = `http://localhost:${port}/.bb-file-bucket/fsrv-fs-enc4/${encodedPath}?token=${token}`;
+
+		const res = await fetch(url);
+		assert.strictEqual(res.status, 200, `Expected 200, got ${res.status}: ${await res.clone().text()}`);
+		assert.strictEqual(await res.text(), 'unicode content');
+	});
+
+	test('PUT with spaces in path (encoded)', async () => {
+		const bucket = new FileBucket(scope, 'fs-enc5');
+		const token = mintFileToken('fsrv-fs-enc5', 'dir name/file name.txt', 'PUT', 3600, LOCAL_FILE_SECRET, 'text/plain');
+		const encodedPath = 'dir%20name/file%20name.txt';
+		const url = `http://localhost:${port}/.bb-file-bucket/fsrv-fs-enc5/${encodedPath}?token=${token}`;
+
+		const putRes = await fetch(url, {
+			method: 'PUT',
+			body: 'uploaded with spaces',
+			headers: { 'Content-Type': 'text/plain' },
+		});
+		assert.strictEqual(putRes.status, 200, `PUT failed: ${putRes.status}`);
+
+		// Verify via bucket API
+		const file = await bucket.get('dir name/file name.txt');
+		assert.ok(file, 'File should exist after presigned PUT');
+		assert.strictEqual(file.body.toString(), 'uploaded with spaces');
+	});
+});
+
+// ── Versioning integration ──────────────────────────────────────────────────
+
+describe('file-server: versioning', () => {
+	test('PUT via presigned URL creates a new version', async () => {
+		const bucket = new FileBucket(scope, 'fs-ver1', { versioned: true });
+		await bucket.put('doc.txt', 'v1-api', { contentType: 'text/plain' });
+
+		const vBefore = await bucket.listVersions('doc.txt');
+		assert.strictEqual(vBefore.length, 1);
+
+		// Upload v2 via presigned URL
+		const putUrl = await bucket.putUrl('doc.txt', { contentType: 'text/plain' });
+		const adjusted = putUrl.replace(/localhost:\d+/, `localhost:${port}`);
+		const res = await fetch(adjusted, {
+			method: 'PUT',
+			body: 'v2-presigned',
+			headers: { 'Content-Type': 'text/plain' },
+		});
+		assert.strictEqual(res.status, 200);
+
+		const vAfter = await bucket.listVersions('doc.txt');
+		assert.strictEqual(
+			vAfter.length, 2,
+			`Expected 2 versions after presigned PUT, got ${vAfter.length}`,
+		);
+
+		const current = await bucket.get('doc.txt');
+		assert.ok(current);
+		assert.strictEqual(current.body.toString(), 'v2-presigned');
+	});
+
+	test('GET with versionId via presigned URL returns specific version', async () => {
+		const bucket = new FileBucket(scope, 'fs-ver2', { versioned: true });
+		await bucket.put('doc.txt', 'v1', { contentType: 'text/plain' });
+		await bucket.put('doc.txt', 'v2', { contentType: 'text/plain' });
+
+		const versions = await bucket.listVersions('doc.txt');
+		const oldVersion = versions[versions.length - 1];
+
+		const url = await bucket.getUrl('doc.txt', { versionId: oldVersion.versionId });
+		const adjusted = url.replace(/localhost:\d+/, `localhost:${port}`);
+
+		const res = await fetch(adjusted);
+		assert.strictEqual(res.status, 200);
+		assert.strictEqual(await res.text(), 'v1');
+	});
+
+	test('rejects a traversal versionId (path-traversal guard)', async () => {
+		const bucket = new FileBucket(scope, 'fs-ver-traversal', { versioned: true });
+		await bucket.put('doc.txt', 'secret-contents', { contentType: 'text/plain' });
+
+		// Start from a legitimate presigned GET URL, then tamper with versionId.
+		const url = await bucket.getUrl('doc.txt');
+		const adjusted = url.replace(/localhost:\d+/, `localhost:${port}`);
+		const malicious = `${adjusted}${adjusted.includes('?') ? '&' : '?'}versionId=${encodeURIComponent('../../../../../../etc/passwd')}`;
+
+		const res = await fetch(malicious);
+		assert.strictEqual(res.status, 400, 'traversal versionId must be rejected with 400');
+		const body = await res.text();
+		assert.ok(!body.includes('root:'), 'must not leak /etc/passwd contents');
+	});
+
+	test('rejects a prefix-bypass versionId (anchored regex guard)', async () => {
+		const bucket = new FileBucket(scope, 'fs-ver-prefix-bypass', { versioned: true });
+		await bucket.put('doc.txt', 'secret-contents', { contentType: 'text/plain' });
+
+		// Attempt to bypass with a versionId that starts valid but appends traversal.
+		const url = await bucket.getUrl('doc.txt');
+		const adjusted = url.replace(/localhost:\d+/, `localhost:${port}`);
+		const malicious = `${adjusted}${adjusted.includes('?') ? '&' : '?'}versionId=${encodeURIComponent('v1/../../../etc/passwd')}`;
+
+		const res = await fetch(malicious);
+		assert.strictEqual(res.status, 400, 'prefix-bypass versionId must be rejected with 400');
+	});
+
+	test('multiple presigned PUTs each create a version', async () => {
+		const bucket = new FileBucket(scope, 'fs-ver3', { versioned: true });
+
+		for (let i = 1; i <= 3; i++) {
+			const putUrl = await bucket.putUrl('counter.txt', { contentType: 'text/plain' });
+			const adjusted = putUrl.replace(/localhost:\d+/, `localhost:${port}`);
+			await fetch(adjusted, {
+				method: 'PUT',
+				body: `version-${i}`,
+				headers: { 'Content-Type': 'text/plain' },
+			});
+		}
+
+		const versions = await bucket.listVersions('counter.txt');
+		assert.strictEqual(
+			versions.length, 3,
+			`Expected 3 versions, got ${versions.length}`,
+		);
+	});
+});
+
+// ── CORS headers ────────────────────────────────────────────────────────────
+
+describe('file-server: CORS', () => {
+	test('OPTIONS request returns CORS headers', async () => {
+		const url = `http://localhost:${port}/.bb-file-bucket/any/path?token=x`;
+		const res = await fetch(url, { method: 'OPTIONS' });
+		assert.strictEqual(res.status, 200);
+		assert.ok(res.headers.get('access-control-allow-methods')?.includes('PUT'));
+	});
+});