@aws-blocks/bb-file-bucket 0.1.0

package/dist/file-server.js

@@ -0,0 +1,169 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+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) {
+    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) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on('data', (chunk) => chunks.push(chunk));
+        req.on('end', () => resolve(Buffer.concat(chunks)));
+        req.on('error', reject);
+    });
+}
+function sendError(res, status, error) {
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error }));
+}
+export function attach(httpServer) {
+    const originalListeners = httpServer.listeners('request').slice();
+    httpServer.removeAllListeners('request');
+    httpServer.on('request', (req, res) => {
+        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 = globalThis.__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(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/dist/file-server.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=file-server.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"file-server.test.d.ts","sourceRoot":"","sources":["../src/file-server.test.ts"],"names":[],"mappings":""}

package/dist/file-server.test.js

@@ -0,0 +1,307 @@
+// 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 { 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;
+let port;
+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((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'));
+    });
+});

package/dist/index.aws.d.ts

@@ -0,0 +1,47 @@
+import { Scope } from '@aws-blocks/core';
+import type { ScopeParent } from '@aws-blocks/core';
+import type { FileBucketOptions, PutOptions, PutUrlOptions, ScanOptions, FileContent, FileInfo, ExternalBucketRef, FileDownloadClient, FileUploadClient, FileVersionInfo, GetOptionsFor, DeleteOptionsFor, GetUrlOptionsFor } from './types.js';
+import type { ChildLogger } from '@aws-blocks/bb-logger';
+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 declare class FileBucket<O extends FileBucketOptions = FileBucketOptions> extends Scope {
+    readonly bbName = "FileBucket";
+    private s3;
+    /** @internal Logger for internal operations. Defaults to error-level when not provided. */
+    protected log: ChildLogger;
+    constructor(scope: ScopeParent, id: string, options?: O);
+    put(path: string, body: Buffer | string, options?: PutOptions): Promise<void>;
+    get(path: string, options?: GetOptionsFor<O>): Promise<FileContent | null>;
+    delete(path: string, options?: DeleteOptionsFor<O>): Promise<void>;
+    deleteBatch(paths: string[]): Promise<void>;
+    getUrl(path: string, options?: GetUrlOptionsFor<O>): Promise<string>;
+    putUrl(path: string, options?: PutUrlOptions): Promise<string>;
+    getFileHandle(path: string, options?: GetUrlOptionsFor<O>): Promise<FileDownloadClient>;
+    createUploadHandle(path: string, options?: PutUrlOptions): Promise<FileUploadClient>;
+    scan(options?: ScanOptions): AsyncIterable<FileInfo>;
+    listVersions(path: string): Promise<FileVersionInfo[]>;
+    restoreVersion(path: string, versionId: string): Promise<void>;
+    static fromExisting(bucketName: string): ExternalBucketRef;
+}
+//# sourceMappingURL=index.aws.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.aws.d.ts","sourceRoot":"","sources":["../src/index.aws.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,KAAK,EAA6C,MAAM,kBAAkB,CAAC;AACpF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,OAAO,KAAK,EACX,iBAAiB,EAAE,UAAU,EAAE,aAAa,EAAE,WAAW,EACzD,WAAW,EAAE,QAAQ,EAAE,iBAAiB,EACxC,kBAAkB,EAAE,gBAAgB,EAAE,eAAe,EACrD,aAAa,EAAE,gBAAgB,EAAE,gBAAgB,EACjD,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,YAAY,EACX,iBAAiB,EAAE,UAAU,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EACxE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,iBAAiB,EACjE,kBAAkB,EAAE,gBAAgB,EAAE,eAAe,EACrD,sBAAsB,EAAE,oBAAoB,EAC5C,mBAAmB,EAAE,sBAAsB,EAAE,sBAAsB,EACnE,aAAa,EAAE,gBAAgB,EAAE,gBAAgB,GACjD,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,UAAU,CAAC,CAAC,SAAS,iBAAiB,GAAG,iBAAiB,CAAE,SAAQ,KAAK;IACrF,QAAQ,CAAC,MAAM,gBAAW;IAC1B,OAAO,CAAC,EAAE,CAAW;IAErB,2FAA2F;IAC3F,SAAS,CAAC,GAAG,EAAE,WAAW,CAAC;gBAEf,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAWjD,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAW7E,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAmB1E,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAOlE,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAW3C,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAUpE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IAM9D,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAavF,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAenF,IAAI,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC;IAarD,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAyBtD,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASpE,MAAM,CAAC,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,iBAAiB;CAG1D"}