@aws-blocks/bb-file-bucket 0.1.0

package/src/paths.ts

@@ -0,0 +1,78 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * On-disk layout for the FileBucket mock.
+ *
+ * Internal data (metadata, version history) is segregated into sibling roots
+ * so it can never collide with user keys:
+ *
+ * ```
+ * .bb-data/{fullId}/content/{key}                    file body (byte-identical)
+ * .bb-data/{fullId}/meta/{key}.json                  sidecar metadata
+ * .bb-data/{fullId}/versions/{key}/{versionId}       version body
+ * .bb-data/{fullId}/versions/{key}/{versionId}.json  version metadata
+ * .bb-data/{fullId}/versions/{key}/__deleted__       delete marker (sentinel)
+ * ```
+ *
+ * Because user content lives only under `content/`, `scan()` can yield every
+ * file it finds with no marker-based filtering — a user key like
+ * `data.__meta__.json` or `logs/__versions__/x` is stored verbatim and is
+ * never confused with internal bookkeeping.
+ *
+ * Both the mock (`index.mock.ts`) and the dev file-server (`file-server.ts`)
+ * import these helpers so the two stay in lockstep.
+ */
+
+import { join } from 'node:path';
+
+/** Subdirectory holding file content, byte-identical to what was written. */
+export const CONTENT_DIR = 'content';
+/** Subdirectory holding sidecar metadata JSON. */
+export const META_DIR = 'meta';
+/** Subdirectory holding version history, one directory per key. */
+export const VERSIONS_DIR = 'versions';
+/** Sentinel filename marking a versioned key as deleted. */
+export const DELETE_MARKER = '__deleted__';
+/** Suffix for version metadata sidecars (internal namespace only). */
+const VERSION_META_SUFFIX = '.json';
+
+/** Root directory under which all user content is stored. */
+export function contentRoot(root: string): string {
+	return join(root, CONTENT_DIR);
+}
+
+/** Absolute path to a file's content. */
+export function contentPath(root: string, key: string): string {
+	return join(root, CONTENT_DIR, key);
+}
+
+/** Absolute path to a file's sidecar metadata. */
+export function metaPath(root: string, key: string): string {
+	return join(root, META_DIR, key + '.json');
+}
+
+/** Directory holding all versions of a single key. */
+export function versionsDirFor(root: string, key: string): string {
+	return join(root, VERSIONS_DIR, key);
+}
+
+/** Absolute path to a specific version's body. */
+export function versionContentPath(root: string, key: string, versionId: string): string {
+	return join(root, VERSIONS_DIR, key, versionId);
+}
+
+/** Absolute path to a specific version's metadata sidecar. */
+export function versionMetaPath(root: string, key: string, versionId: string): string {
+	return join(root, VERSIONS_DIR, key, versionId + VERSION_META_SUFFIX);
+}
+
+/** Absolute path to a key's delete-marker sentinel. */
+export function deleteMarkerPath(root: string, key: string): string {
+	return join(root, VERSIONS_DIR, key, DELETE_MARKER);
+}
+
+/** True if a versions-directory entry is a real version body (not metadata or a sentinel). */
+export function isVersionEntry(entry: string): boolean {
+	return entry !== DELETE_MARKER && !entry.endsWith(VERSION_META_SUFFIX);
+}

package/src/scan.test.ts

@@ -0,0 +1,137 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Tests for scan() correctness — ensures user files are never silently
+ * excluded by internal sidecar/version-directory filtering.
+ */
+
+import { test, describe, beforeEach } from 'node:test';
+import assert from 'node:assert';
+import { rmSync, existsSync, readdirSync } from 'node:fs';
+import { Scope } from '@aws-blocks/core';
+import { FileBucket } from './index.mock.js';
+
+const scope = new Scope('scn');
+
+beforeEach(() => {
+	const dir = '.bb-data';
+	try {
+		if (existsSync(dir)) {
+			for (const entry of readdirSync(dir)) {
+				if (entry.startsWith('scn-')) {
+					rmSync(`${dir}/${entry}`, { recursive: true, force: true });
+				}
+			}
+		}
+	} catch {}
+});
+
+// ── Filenames containing internal marker substrings ─────────────────────────
+
+describe('scan: user files with __versions__ in name', () => {
+	test('file named "my__versions__backup.txt" is listed', async () => {
+		const bucket = new FileBucket(scope, 'scan-v1');
+		await bucket.put('my__versions__backup.txt', 'data');
+		await bucket.put('normal.txt', 'data');
+
+		const files: string[] = [];
+		for await (const f of bucket.scan()) files.push(f.path);
+
+		assert.ok(
+			files.includes('my__versions__backup.txt'),
+			`scan() should include user file with __versions__ in name. Got: ${JSON.stringify(files)}`,
+		);
+	});
+
+	test('file in directory containing __versions__ is listed', async () => {
+		const bucket = new FileBucket(scope, 'scan-v2');
+		await bucket.put('logs/__versions__report/data.csv', 'csv');
+
+		const files: string[] = [];
+		for await (const f of bucket.scan()) files.push(f.path);
+
+		assert.ok(
+			files.includes('logs/__versions__report/data.csv'),
+			`scan() should include file in __versions__-named directory. Got: ${JSON.stringify(files)}`,
+		);
+	});
+
+	test('internal version directories are still excluded', async () => {
+		const bucket = new FileBucket(scope, 'scan-v4', { versioned: true });
+		await bucket.put('doc.txt', 'v1');
+		await bucket.put('doc.txt', 'v2');
+
+		const files: string[] = [];
+		for await (const f of bucket.scan()) files.push(f.path);
+
+		assert.deepStrictEqual(files, ['doc.txt']);
+	});
+});
+
+describe('scan: user files with .__meta__.json in name', () => {
+	test('file named "data.__meta__.json" is listed', async () => {
+		const bucket = new FileBucket(scope, 'scan-m1');
+		await bucket.put('data.__meta__.json', '{"user": "file"}');
+		await bucket.put('normal.txt', 'data');
+
+		const files: string[] = [];
+		for await (const f of bucket.scan()) files.push(f.path);
+
+		assert.ok(
+			files.includes('data.__meta__.json'),
+			`scan() should include user file named "data.__meta__.json". Got: ${JSON.stringify(files)}`,
+		);
+	});
+
+	test('actual sidecar metadata files are excluded', async () => {
+		const bucket = new FileBucket(scope, 'scan-m4');
+		await bucket.put('report.pdf', 'pdf', { contentType: 'application/pdf' });
+
+		const files: string[] = [];
+		for await (const f of bucket.scan()) files.push(f.path);
+
+		// Only the real file, not its sidecar
+		assert.deepStrictEqual(files, ['report.pdf']);
+	});
+
+	test('user file and its own sidecar coexist correctly', async () => {
+		// A user file named "data.__meta__.json" is stored verbatim under the
+		// content root; its metadata lives in the segregated meta root, so there
+		// is no collision and scan() lists exactly the user file.
+		const bucket = new FileBucket(scope, 'scan-m5');
+		await bucket.put('data.__meta__.json', 'user content', { contentType: 'application/json' });
+
+		const file = await bucket.get('data.__meta__.json');
+		assert.ok(file);
+		assert.strictEqual(file.body.toString(), 'user content');
+		assert.strictEqual(file.contentType, 'application/json');
+
+		const files: string[] = [];
+		for await (const f of bucket.scan()) files.push(f.path);
+
+		assert.deepStrictEqual(files, ['data.__meta__.json']);
+	});
+});
+
+describe('scan: segregated on-disk layout', () => {
+	test('content, meta, and versions live under separate roots', async () => {
+		const bucket = new FileBucket(scope, 'scan-layout', { versioned: true });
+		await bucket.put('docs/report.pdf', 'pdf', { contentType: 'application/pdf' });
+
+		const base = `.bb-data/scn-scan-layout`;
+		// User content is byte-identical under content/
+		assert.ok(existsSync(`${base}/content/docs/report.pdf`), 'content/ should hold the file body');
+		// Metadata is segregated under meta/
+		assert.ok(existsSync(`${base}/meta/docs/report.pdf.json`), 'meta/ should hold the sidecar');
+		// Versions are segregated under versions/{key}/
+		assert.ok(existsSync(`${base}/versions/docs/report.pdf/v1`), 'versions/ should hold version bodies');
+
+		// scan() only ever sees the content root — exactly one user file.
+		const files: string[] = [];
+		for await (const f of bucket.scan()) files.push(f.path);
+		assert.deepStrictEqual(files, ['docs/report.pdf']);
+	});
+});
+
+

package/src/tokens.ts

@@ -0,0 +1,61 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { createHmac } from 'node:crypto';
+import { constantTimeEquals } from '@aws-blocks/core/bb-utils';
+
+// ── Token helpers ───────────────────────────────────────────────────────────
+
+export const LOCAL_FILE_SECRET = '__blocks_file_bucket_dev_secret__';
+
+interface FileTokenPayload {
+	fullId: string;
+	path: string;
+	method: 'GET' | 'PUT';
+	contentType?: string;
+	exp: number;
+}
+
+export function mintFileToken(
+	fullId: string,
+	path: string,
+	method: 'GET' | 'PUT',
+	expiresIn: number,
+	secret: string,
+	contentType?: string,
+): string {
+	const payload: FileTokenPayload = {
+		fullId,
+		path,
+		method,
+		exp: Math.floor(Date.now() / 1000) + expiresIn,
+		...(contentType ? { contentType } : {}),
+	};
+	const json = JSON.stringify(payload);
+	const sig = createHmac('sha256', secret).update(json).digest('base64url');
+	return `${Buffer.from(json).toString('base64url')}.${sig}`;
+}
+
+export function validateFileToken(
+	token: string,
+	secret: string,
+	expectedFullId: string,
+	expectedPath: string,
+	expectedMethod: 'GET' | 'PUT',
+): FileTokenPayload | null {
+	try {
+		const [payloadB64, sig] = token.split('.');
+		if (!payloadB64 || !sig) return null;
+		const json = Buffer.from(payloadB64, 'base64url').toString();
+		const expectedSig = createHmac('sha256', secret).update(json).digest('base64url');
+		if (!constantTimeEquals(sig, expectedSig)) return null;
+		const payload: FileTokenPayload = JSON.parse(json);
+		if (payload.exp < Math.floor(Date.now() / 1000)) return null;
+		if (payload.fullId !== expectedFullId) return null;
+		if (payload.path !== expectedPath) return null;
+		if (payload.method !== expectedMethod) return null;
+		return payload;
+	} catch {
+		return null;
+	}
+}

package/src/types.ts

@@ -0,0 +1,206 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Shared types for FileBucket. Imported by mock, aws, and browser entry points.
+ * This file has zero runtime dependencies — types only.
+ */
+import type { ChildLogger } from '@aws-blocks/bb-logger';
+
+// ── Constructor options ─────────────────────────────────────────────────────
+
+export interface FileBucketOptions {
+	/** Enable object versioning. Default: false. */
+	versioned?: boolean;
+	/** CORS rules for browser-based access. */
+	corsRules?: CorsRule[];
+	/** Lifecycle rules for automatic object expiration or transitions. */
+	lifecycleRules?: LifecycleRule[];
+	/** Wrap an existing S3 bucket instead of creating one. */
+	bucket?: ExternalBucketRef;
+	/**
+	 * CDK removal behavior for the underlying S3 bucket. When omitted,
+	 * CDK's default applies (RETAIN — the bucket and its contents are
+	 * preserved on `cdk destroy`).
+	 *
+	 * Pass `'destroy'` for sandbox / ephemeral stacks where the bucket
+	 * should be dropped on teardown. This also enables `autoDeleteObjects`
+	 * so CloudFormation can empty the bucket before deletion — required
+	 * since S3 rejects DELETE on a non-empty bucket.
+	 *
+	 * Pass `'retain'` to set the policy explicitly (identical to omitting
+	 * it today, but robust against stack-layer policy overrides).
+	 *
+	 * Templates that apply `RemovalPolicies.of(stack).destroy()` at the
+	 * top level override this setting.
+	 *
+	 * Ignored by the mock and browser runtimes (no AWS resource to retain).
+	 */
+	removalPolicy?: 'destroy' | 'retain';
+	/** Optional logger for internal operations. When omitted, a default Logger at error level is created. */
+	logger?: ChildLogger;
+}
+
+// ── Method options ──────────────────────────────────────────────────────────
+
+export interface PutOptions {
+	/** MIME type of the file (e.g., `image/png`). */
+	contentType?: string;
+	/** Custom metadata key-value pairs. */
+	metadata?: Record<string, string>;
+	/** Cache-Control header value. */
+	cacheControl?: string;
+}
+
+export interface GetUrlOptions {
+	/** URL expiration in seconds. Default: 3600. */
+	expiresIn?: number;
+}
+
+export interface PutUrlOptions {
+	/** URL expiration in seconds. Default: 3600. */
+	expiresIn?: number;
+	/** Required content type for the upload. */
+	contentType?: string;
+}
+
+export interface ScanOptions {
+	/** Only list files whose keys start with this prefix. */
+	prefix?: string;
+}
+
+// ── Versioning options (extend base options with versionId) ─────────────────
+
+/** Options for get on versioned buckets. */
+export interface VersionedGetOptions {
+	/** Retrieve a specific version. Omit to get the latest. */
+	versionId?: string;
+}
+
+/** Options for delete on versioned buckets. */
+export interface VersionedDeleteOptions {
+	/** Delete a specific version permanently. Omit to place a delete marker. */
+	versionId?: string;
+}
+
+/** Options for getUrl/getFileHandle on versioned buckets. */
+export interface VersionedGetUrlOptions extends GetUrlOptions {
+	/** Generate URL for a specific version. */
+	versionId?: string;
+}
+
+// ── Conditional type helpers ────────────────────────────────────────────────
+
+/**
+ * Resolves the get options type based on whether versioning is enabled.
+ * Versioned buckets accept `{ versionId }`, non-versioned accept no options.
+ */
+export type GetOptionsFor<O extends FileBucketOptions> =
+	O extends { versioned: true } ? VersionedGetOptions : undefined;
+
+/**
+ * Resolves the delete options type based on whether versioning is enabled.
+ * Versioned buckets accept `{ versionId }`, non-versioned accept no options.
+ */
+export type DeleteOptionsFor<O extends FileBucketOptions> =
+	O extends { versioned: true } ? VersionedDeleteOptions : undefined;
+
+/**
+ * Resolves the getUrl/getFileHandle options type based on whether versioning is enabled.
+ * Versioned buckets accept `{ expiresIn, versionId }`, non-versioned accept `{ expiresIn }`.
+ */
+export type GetUrlOptionsFor<O extends FileBucketOptions> =
+	O extends { versioned: true } ? VersionedGetUrlOptions : GetUrlOptions;
+
+// ── Return types ────────────────────────────────────────────────────────────
+
+export interface FileContent {
+	/** The file body as a Buffer. */
+	body: Buffer;
+	/** MIME type of the file. */
+	contentType: string;
+	/** Custom metadata key-value pairs. */
+	metadata: Record<string, string>;
+	/** File size in bytes. */
+	size: number;
+}
+
+export interface FileInfo {
+	/** The object key. */
+	path: string;
+	/** File size in bytes. */
+	size: number;
+	/** Last modification timestamp. */
+	lastModified: Date;
+}
+
+/** Metadata for a single object version. */
+export interface FileVersionInfo {
+	/** The version identifier. */
+	versionId: string;
+	/** When this version was created. */
+	lastModified: Date;
+	/** Size in bytes. */
+	size: number;
+	/** Whether this is the current (latest) version. */
+	isCurrent: boolean;
+}
+
+// ── Infrastructure types ────────────────────────────────────────────────────
+
+export interface CorsRule {
+	allowedOrigins: string[];
+	allowedMethods: ('GET' | 'PUT' | 'POST' | 'DELETE' | 'HEAD')[];
+	allowedHeaders?: string[];
+	exposedHeaders?: string[];
+	maxAge?: number;
+}
+
+export interface LifecycleRule {
+	/** Prefix filter for the rule. */
+	prefix?: string;
+	/** Days after creation to expire objects. */
+	expirationDays?: number;
+	/** Days after creation to transition to Infrequent Access. */
+	transitionToIaDays?: number;
+}
+
+export interface ExternalBucketRef {
+	readonly __brand: 'ExternalBucketRef';
+	readonly bucketName: string;
+}
+
+// ── Client handle types (hydrated by middleware) ────────────────────────────
+
+/** Client-side download handle. Works server-side and serializes via toJSON() for the wire. */
+export interface FileDownloadClient {
+	/** Download the file as a Blob (server) or via fetch (client). */
+	download(): Promise<Blob>;
+	/** Get the presigned URL. */
+	getUrl(): string;
+	/** @internal Transferable serialization — called automatically by JSON.stringify(). */
+	toJSON(): FileDownloadDescriptor;
+}
+
+/** Client-side upload handle. Works server-side and serializes via toJSON() for the wire. */
+export interface FileUploadClient {
+	/** Upload a file body to the presigned URL. */
+	upload(body: Blob | File | ArrayBuffer): Promise<void>;
+	/** Get the presigned URL. */
+	getUrl(): string;
+	/** @internal Transferable serialization — called automatically by JSON.stringify(). */
+	toJSON(): FileUploadDescriptor;
+}
+
+// ── Wire descriptor types ───────────────────────────────────────────────────
+
+export interface FileDownloadDescriptor {
+	readonly __blocks: 'file-bucket/download';
+	readonly url: string;
+}
+
+export interface FileUploadDescriptor {
+	readonly __blocks: 'file-bucket/upload';
+	readonly url: string;
+	readonly contentType?: string;
+}

package/src/url-encoding.test.ts

@@ -0,0 +1,120 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Tests for presigned URL generation — ensures URLs are valid and parseable
+ * for paths containing special characters (#, ?, %, spaces).
+ */
+
+import { test, describe, beforeEach } from 'node:test';
+import assert from 'node:assert';
+import { rmSync, existsSync, readdirSync } from 'node:fs';
+import { Scope } from '@aws-blocks/core';
+import { FileBucket } from './index.mock.js';
+
+const scope = new Scope('enc');
+
+beforeEach(() => {
+	const dir = '.bb-data';
+	try {
+		if (existsSync(dir)) {
+			for (const entry of readdirSync(dir)) {
+				if (entry.startsWith('enc-')) {
+					rmSync(`${dir}/${entry}`, { recursive: true, force: true });
+				}
+			}
+		}
+	} catch {}
+});
+
+describe('getUrl: URL encoding', () => {
+	test('path with # produces valid URL (# encoded as %23)', async () => {
+		const bucket = new FileBucket(scope, 'url-hash');
+		const url = await bucket.getUrl('file#1.txt');
+		const parsed = new URL(url);
+
+		assert.strictEqual(parsed.hash, '', 'Hash fragment should be empty — # must be encoded');
+		assert.ok(parsed.searchParams.has('token'), 'Token must be in query params, not lost in fragment');
+	});
+
+	test('path with ? produces valid URL (? encoded as %3F)', async () => {
+		const bucket = new FileBucket(scope, 'url-question');
+		const url = await bucket.getUrl('what?file.txt');
+		const parsed = new URL(url);
+
+		assert.ok(parsed.searchParams.has('token'), 'Token must be accessible in query params');
+		assert.ok(
+			!parsed.pathname.endsWith('what'),
+			'Pathname should not be truncated at the ? character',
+		);
+	});
+
+	test('path with % literal produces valid URL (% encoded as %25)', async () => {
+		const bucket = new FileBucket(scope, 'url-percent');
+		const url = await bucket.getUrl('100%done.txt');
+		const parsed = new URL(url);
+
+		assert.ok(parsed.searchParams.has('token'), 'Token must be in query params');
+		// % must be encoded as %25 to avoid ambiguity
+		assert.ok(
+			url.includes('100%25done.txt'),
+			`URL should encode % as %25. Got: ${url}`,
+		);
+	});
+
+	test('already-encoded path is not double-encoded', async () => {
+		// A file literally named "file%231.txt" (contains percent-two-three)
+		// should encode to "file%25231.txt" — the % becomes %25
+		const bucket = new FileBucket(scope, 'url-double');
+		const url = await bucket.getUrl('file%231.txt');
+		const parsed = new URL(url);
+
+		assert.ok(parsed.searchParams.has('token'), 'Token must be in query params');
+		assert.ok(
+			url.includes('file%25231.txt'),
+			`Literal % in filename should be encoded to %25. Got: ${url}`,
+		);
+	});
+});
+
+describe('putUrl: URL encoding', () => {
+	test('path with # produces valid URL', async () => {
+		const bucket = new FileBucket(scope, 'put-hash');
+		const url = await bucket.putUrl('upload#1.bin');
+		const parsed = new URL(url);
+
+		assert.strictEqual(parsed.hash, '', 'Hash fragment should be empty');
+		assert.ok(parsed.searchParams.has('token'), 'Token must be in query params');
+	});
+});
+
+describe('getUrl: versioned with special chars', () => {
+	test('versionId param preserved alongside encoded path', async () => {
+		const bucket = new FileBucket(scope, 'url-ver', { versioned: true });
+		await bucket.put('file#1.txt', 'v1');
+		await bucket.put('file#1.txt', 'v2');
+
+		const versions = await bucket.listVersions('file#1.txt');
+		const oldest = versions[versions.length - 1];
+		const url = await bucket.getUrl('file#1.txt', { versionId: oldest.versionId });
+		const parsed = new URL(url);
+
+		assert.ok(parsed.searchParams.has('token'), 'Token in query');
+		assert.strictEqual(parsed.searchParams.get('versionId'), oldest.versionId);
+		assert.strictEqual(parsed.hash, '', 'No fragment');
+	});
+});
+
+describe('FileBucketErrors completeness', () => {
+	test('FileBucketErrors includes FileTooLarge', async () => {
+		const { FileBucketErrors } = await import('./errors.js');
+		assert.ok(
+			'FileTooLarge' in FileBucketErrors,
+			`FileBucketErrors should include FileTooLarge. Keys: ${Object.keys(FileBucketErrors)}`,
+		);
+		assert.strictEqual(
+			(FileBucketErrors as any).FileTooLarge,
+			'EntityTooLarge',
+		);
+	});
+});

package/src/version.ts

@@ -0,0 +1,3 @@
+// Auto-generated by scripts/generate-version.mjs — do not edit manually
+export const BB_NAME = 'FileBucket';
+export const BB_VERSION = '0.1.0';