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

package/src/index.mock.ts

@@ -16,7 +16,7 @@ import { mintFileToken, LOCAL_FILE_SECRET } from './tokens.js';
 import { validateBucketName } from './bucket-name.js';
 import type {
 	FileBucketOptions, PutOptions, PutUrlOptions, ScanOptions,
-	FileContent, FileInfo, ExternalBucketRef,
+	FileContent, FileInfo, ExternalBucketRef, CorsRule,
 	FileDownloadClient, FileUploadClient, FileVersionInfo,
 	GetOptionsFor, DeleteOptionsFor, GetUrlOptionsFor,
 } from './types.js';
@@ -40,6 +40,17 @@ export { FileBucketErrors } from './errors.js';
 
 const MAX_KEY_BYTES = 1024; // S3 key limit
 
+// Mirrors of the CDK synth-time-guard constants (index.cdk.ts). Duplicated here
+// rather than imported — the CDK entry (index.cdk.ts) pulls in aws-cdk-lib and
+// must never be imported into the mock runtime. Kept byte-identical to the CDK
+// definitions so the two guards below reject exactly what `cdk synth` rejects.
+
+/** Default number of days after which noncurrent object versions expire. */
+const DEFAULT_NONCURRENT_VERSION_EXPIRATION_DAYS = 90;
+
+/** HTTP methods that mutate bucket state; unsafe to expose to wildcard origins. */
+const MUTATING_CORS_METHODS: ReadonlyArray<CorsRule['allowedMethods'][number]> = ['PUT', 'POST', 'DELETE'];
+
 function blocksError(name: string, message: string): Error {
 	const err = new Error(`${name}: ${message}`);
 	err.name = name;
@@ -94,9 +105,45 @@ export class FileBucket<O extends FileBucketOptions = FileBucketOptions> extends
 		// deployed bucket name), not the `mock-` prefixed local name, to keep
 		// parity with the CDK path.
 		if (!options?.bucket) validateBucketName(this.fullId);
+		// Mirror the CDK's two synth-time guards (index.cdk.ts) VERBATIM so a
+		// local/unit run rejects exactly what `cdk synth` would. Gated on
+		// `!options?.bucket` alongside validateBucketName: the CDK's
+		// external-bucket branch returns before these checks, so a wrapped
+		// bucket bypasses them here too. Plain `throw new Error(...)` (no
+		// `name`, no blocksError factory) to match the CDK path exactly — using
+		// blocksError() would set an `error.name` the CDK guards don't, breaking
+		// mock↔cdk parity.
+		if (!options?.bucket) {
+			// Reject unsafe CORS: a wildcard origin ('*') combined with a mutating
+			// method (PUT/POST/DELETE) lets any site issue state-changing
+			// cross-origin requests.
+			for (const rule of options?.corsRules ?? []) {
+				if (rule.allowedOrigins.includes('*')) {
+					const mutating = rule.allowedMethods.filter(m => MUTATING_CORS_METHODS.includes(m));
+					if (mutating.length > 0) {
+						throw new Error(
+							`FileBucket "${this.fullId}": CORS rule with wildcard origin '*' must not allow mutating method(s) ${mutating.join(', ')}. ` +
+							`Specify explicit allowedOrigins (e.g. 'https://app.example.com') for ${mutating.join(', ')} instead of '*'.`,
+						);
+					}
+				}
+			}
+			// Reject a non-positive or non-integer noncurrent-version expiration.
+			// The FORMAT is validated regardless of `versioned` (matching CDK) so
+			// a malformed value is caught even when versioning is off.
+			if (options?.noncurrentVersionExpirationDays !== undefined) {
+				const days = options.noncurrentVersionExpirationDays;
+				if (!Number.isInteger(days) || days <= 0) {
+					throw new Error(
+						`FileBucket "${this.fullId}": noncurrentVersionExpirationDays must be a positive integer (got ${days}). ` +
+						`Omit it to use the default of ${DEFAULT_NONCURRENT_VERSION_EXPIRATION_DAYS} days.`,
+					);
+				}
+			}
+		}
 		this.log = options?.logger ?? new Logger(this, 'logger', { level: 'error' });
 		this.dataDir = getMockDataDir(this);
-		this.versioned = options?.versioned ?? false;
+		this.versioned = options?.versioned ?? true;
 		this.registerClientMiddleware('@aws-blocks/bb-file-bucket/middleware');
 		this.registerDevAttachment('@aws-blocks/bb-file-bucket/file-server');
 		registerSdkIdentifiers(this.fullId, { bucketName: `mock-${this.fullId}` });

package/src/index.test.ts

@@ -344,8 +344,11 @@ test('versioned: listVersions returns newest first', async () => {
 // ── Static type checks: conditional version types ───────────────────────────
 
 function _conditionalVersionTypeChecks() {
-	const plain = new FileBucket(scope, 'plain');
+	// Explicit opt-out selects the non-versioned option types.
+	const plain = new FileBucket(scope, 'plain', { versioned: false });
 	const versioned = new FileBucket(scope, 'versioned', { versioned: true });
+	// No options now defaults to versioned-aware typings (Default: true).
+	const dflt = new FileBucket(scope, 'dflt');
 
 	// Non-versioned: get/delete accept no options
 	plain.get('file.txt');
@@ -363,4 +366,131 @@ function _conditionalVersionTypeChecks() {
 	versioned.delete('file.txt');
 	versioned.delete('file.txt', { versionId: 'v1' });
 	versioned.getUrl('file.txt', { versionId: 'v1', expiresIn: 600 });
+
+	// Default (no options) is versioned-aware: versionId is accepted.
+	dflt.get('file.txt');
+	dflt.get('file.txt', { versionId: 'v1' });
+	dflt.delete('file.txt', { versionId: 'v1' });
+	dflt.getUrl('file.txt', { versionId: 'v1', expiresIn: 600 });
 }
+
+// ── Versioning on by default (new secure default) ───────────────────────────
+
+test('default (no options) bucket is versioned: put creates versions', async () => {
+	const bucket = new FileBucket(scope, 'default-versioned');
+	await bucket.put('file.txt', 'v1');
+	await bucket.put('file.txt', 'v2');
+	const versions = await bucket.listVersions('file.txt');
+	assert.strictEqual(versions.length, 2);
+	assert.strictEqual(versions[0].isCurrent, true);
+});
+
+test('versioned:false opt-out disables versioning at runtime', async () => {
+	const bucket = new FileBucket(scope, 'optout-versioned', { versioned: false });
+	await bucket.put('file.txt', 'v1');
+	await bucket.put('file.txt', 'v2');
+	const versions = await bucket.listVersions('file.txt');
+	assert.strictEqual(versions.length, 0);
+	const file = await bucket.get('file.txt');
+	assert.ok(file);
+	assert.strictEqual(file.body.toString(), 'v2');
+});
+
+// ── Synth-time validation parity (mock mirrors the CDK's index.cdk.ts guards) ─
+// The mock reproduces the CDK's two synth-time guards VERBATIM so a local/unit
+// run fails the same way `cdk synth` would (mock↔cdk parity). Mirrors the
+// corresponding cases in index.cdk.test.ts.
+
+test('mock: noncurrentVersionExpirationDays of 0 throws', () => {
+	assert.throws(
+		() => new FileBucket(scope, 'uploads', { noncurrentVersionExpirationDays: 0 }),
+		(err: unknown) =>
+			err instanceof Error &&
+			/noncurrentVersionExpirationDays must be a positive integer/.test(err.message) &&
+			/got 0/.test(err.message),
+	);
+});
+
+test('mock: negative noncurrentVersionExpirationDays throws', () => {
+	assert.throws(
+		() => new FileBucket(scope, 'uploads', { noncurrentVersionExpirationDays: -1 }),
+		(err: unknown) =>
+			err instanceof Error &&
+			/noncurrentVersionExpirationDays must be a positive integer/.test(err.message) &&
+			/got -1/.test(err.message),
+	);
+});
+
+test('mock: non-integer noncurrentVersionExpirationDays throws', () => {
+	assert.throws(
+		() => new FileBucket(scope, 'uploads', { noncurrentVersionExpirationDays: 1.5 }),
+		(err: unknown) =>
+			err instanceof Error &&
+			/noncurrentVersionExpirationDays must be a positive integer/.test(err.message),
+	);
+});
+
+test('mock: noncurrentVersionExpirationDays FORMAT is validated even when versioned:false', () => {
+	// Format guard is decoupled from the `versioned` gate (matches CDK): a
+	// malformed value must fail regardless of whether versioning is on.
+	assert.throws(
+		() => new FileBucket(scope, 'uploads', { versioned: false, noncurrentVersionExpirationDays: 0 }),
+		(err: unknown) =>
+			err instanceof Error &&
+			/noncurrentVersionExpirationDays must be a positive integer/.test(err.message) &&
+			/got 0/.test(err.message),
+	);
+});
+
+test('mock: valid noncurrentVersionExpirationDays does not throw', () => {
+	assert.doesNotThrow(
+		() => new FileBucket(scope, 'uploads', { noncurrentVersionExpirationDays: 30 }),
+	);
+});
+
+test('mock: wildcard-origin CORS with a mutating method throws', () => {
+	assert.throws(
+		() =>
+			new FileBucket(scope, 'uploads', {
+				corsRules: [{ allowedOrigins: ['*'], allowedMethods: ['GET', 'PUT'] }],
+			}),
+		(err: unknown) =>
+			err instanceof Error &&
+			/\*/.test(err.message) &&
+			/PUT/.test(err.message),
+	);
+});
+
+test('mock: wildcard-origin CORS with only safe methods is allowed', () => {
+	assert.doesNotThrow(() =>
+		new FileBucket(scope, 'uploads', {
+			corsRules: [{ allowedOrigins: ['*'], allowedMethods: ['GET', 'HEAD'] }],
+		}),
+	);
+});
+
+test('mock: explicit-origin CORS with a mutating method is allowed', () => {
+	assert.doesNotThrow(() =>
+		new FileBucket(scope, 'uploads', {
+			corsRules: [{ allowedOrigins: ['https://app.example.com'], allowedMethods: ['PUT', 'POST'] }],
+		}),
+	);
+});
+
+test('mock: when both guards are tripped, the CORS guard fires first (matches CDK order)', () => {
+	// The CDK (index.cdk.ts) evaluates the CORS guard before the noncurrent
+	// check, so a config that violates BOTH must surface the CORS message — not
+	// the noncurrent one — in the mock too, keeping mock↔cdk parity.
+	assert.throws(
+		() =>
+			new FileBucket(scope, 'uploads', {
+				noncurrentVersionExpirationDays: 0,
+				corsRules: [{ allowedOrigins: ['*'], allowedMethods: ['PUT'] }],
+			}),
+		(err: unknown) =>
+			err instanceof Error &&
+			/CORS rule with wildcard origin/.test(err.message) &&
+			/PUT/.test(err.message) &&
+			!/noncurrentVersionExpirationDays/.test(err.message),
+	);
+});

package/src/types.ts

@@ -10,13 +10,61 @@ import type { ChildLogger } from '@aws-blocks/bb-logger';
 // ── Constructor options ─────────────────────────────────────────────────────
 
 export interface FileBucketOptions {
-	/** Enable object versioning. Default: false. */
+	/**
+	 * Enable object versioning. Default: true. Pass `false` to opt out.
+	 *
+	 * Note for the version-aware method typings (`get`/`delete`/`getUrl`/
+	 * `getFileHandle`): selecting the NON-versioned (optionless) typings
+	 * requires the literal `versioned: false`. A non-literal `boolean` value
+	 * (e.g. one widened from a variable) — or omitting the option entirely —
+	 * resolves to the versioned-aware typings, which match the default-on
+	 * runtime behavior. See {@link GetOptionsFor} et al.
+	 */
 	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. */
+	/**
+	 * Enable S3 server access logging. Default: false (opt-in).
+	 *
+	 * When `true`, a dedicated, locked-down log bucket is provisioned
+	 * (all public access blocked, S3-managed encryption, SSL enforced) and
+	 * the main bucket delivers its access logs there under the
+	 * `access-logs/` prefix. Access logs are expired automatically after the
+	 * stack-wide `logRetention` default (see `BlocksDefaults.logRetention`);
+	 * `RetentionDays.INFINITE` keeps them indefinitely (no expiry rule).
+	 *
+	 * Resolves from the stack `defaults.accessLogging` when omitted, so a
+	 * production-postured stack can opt every FileBucket into logging without
+	 * a per-block option. Ignored by the mock and browser runtimes (no AWS
+	 * resource).
+	 */
+	accessLogging?: boolean;
+	/**
+	 * Days after which NONCURRENT object versions are permanently expired,
+	 * bounding the storage cost that versioning would otherwise let grow
+	 * unbounded. Only applies when versioning is enabled (the default).
+	 * Default: 90.
+	 *
+	 * Must be a positive integer; a non-positive or non-integer value is
+	 * rejected at synth. There is no "disable" sentinel — noncurrent-version
+	 * expiration is always on for a versioned bucket to cap version growth. To
+	 * opt out entirely, disable versioning (`versioned: false`), which drops
+	 * the rule. Ignored by the mock and browser runtimes (no AWS resource).
+	 */
+	noncurrentVersionExpirationDays?: number;
+	/**
+	 * Wrap an existing S3 bucket instead of creating one.
+	 *
+	 * @remarks
+	 * When set, FileBucket binds to the supplied bucket as-is and returns early:
+	 * NONE of the secure defaults this construct normally applies are applied to
+	 * an externally-supplied bucket — not `enforceSSL`, versioning + noncurrent-version
+	 * expiration, server access logging, `blockPublicAccess`, encryption, nor the
+	 * wildcard-CORS guard. You own that bucket's security posture; configure these
+	 * on the bucket itself (or via its own CDK construct) before wrapping it.
+	 */
 	bucket?: ExternalBucketRef;
 	/**
 	 * CDK removal behavior for the underlying S3 bucket. When omitted,
@@ -94,23 +142,31 @@ export interface VersionedGetUrlOptions extends GetUrlOptions {
 /**
  * Resolves the get options type based on whether versioning is enabled.
  * Versioned buckets accept `{ versionId }`, non-versioned accept no options.
+ * Versioning is on by default, so only an explicit `versioned: false` selects
+ * the non-versioned (optionless) shape. A non-literal `boolean` (widened from
+ * a variable) or an absent `versioned` resolves to the versioned-aware shape,
+ * matching the default-on runtime behavior.
  */
 export type GetOptionsFor<O extends FileBucketOptions> =
-	O extends { versioned: true } ? VersionedGetOptions : undefined;
+	O extends { versioned: false } ? undefined : VersionedGetOptions;
 
 /**
  * Resolves the delete options type based on whether versioning is enabled.
  * Versioned buckets accept `{ versionId }`, non-versioned accept no options.
+ * Versioning is on by default, so only an explicit `versioned: false` selects
+ * the non-versioned (optionless) shape.
  */
 export type DeleteOptionsFor<O extends FileBucketOptions> =
-	O extends { versioned: true } ? VersionedDeleteOptions : undefined;
+	O extends { versioned: false } ? undefined : VersionedDeleteOptions;
 
 /**
  * Resolves the getUrl/getFileHandle options type based on whether versioning is enabled.
  * Versioned buckets accept `{ expiresIn, versionId }`, non-versioned accept `{ expiresIn }`.
+ * Versioning is on by default, so only an explicit `versioned: false` selects
+ * the non-versioned shape.
  */
 export type GetUrlOptionsFor<O extends FileBucketOptions> =
-	O extends { versioned: true } ? VersionedGetUrlOptions : GetUrlOptions;
+	O extends { versioned: false } ? GetUrlOptions : VersionedGetUrlOptions;
 
 // ── Return types ────────────────────────────────────────────────────────────
 
@@ -165,6 +221,11 @@ export interface LifecycleRule {
 	transitionToIaDays?: number;
 }
 
+/**
+ * A reference to a pre-existing S3 bucket to wrap via {@link FileBucketOptions.bucket}
+ * (see that field's remarks — a wrapped bucket does not receive FileBucket's
+ * secure defaults). Produced by `FileBucket.fromExisting(bucketName)`.
+ */
 export interface ExternalBucketRef {
 	readonly __brand: 'ExternalBucketRef';
 	readonly bucketName: string;

package/src/version.ts

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