@aws-blocks/bb-file-bucket 0.1.1 → 0.1.3

package/DESIGN.md

@@ -0,0 +1,95 @@
+# FileBucket — Design
+
+Design document for FileBucket. For usage, see [README.md](./README.md).
+
+**Package:** `@aws-blocks/bb-file-bucket`
+**Type:** Primitive (new infrastructure)
+**AWS Service:** Amazon S3
+
+## Design Decisions
+
+**D-FB-1: Buffer body type instead of ReadableStream**
+**Decision:** `put()` accepts `Buffer | string`, `get()` returns `Buffer` in `FileContent.body`.
+**Rationale:** ReadableStream adds complexity for the common case (small-to-medium files). Buffer is simpler to work with in Lambda (where the entire response must be buffered anyway). For large files, presigned URLs (`getUrl`/`putUrl`) are the recommended pattern. This favors client-safe return types.
+
+**D-FB-2: Segregated internal storage in mock**
+**Decision:** The mock stores user content, sidecar metadata, and version history under separate sibling roots inside `.bb-data/{fullId}/`:
+```
+content/{key}                     file body (byte-identical to what was written)
+meta/{key}.json                   sidecar metadata
+versions/{key}/{versionId}        version body
+versions/{key}/{versionId}.json   version metadata
+versions/{key}/__deleted__        delete marker (sentinel)
+```
+**Rationale:** Keeps file content byte-identical (no wrapping format) while guaranteeing internal bookkeeping can never collide with user keys. An earlier design co-located metadata as `{path}.__meta__.json` next to each file and relied on marker substrings, which meant a user key like `data.__meta__.json` or a directory named `x.__versions__/` could be silently hidden or shadowed by `scan()`. Because user content now lives only under `content/`, `scan()` walks that one root and yields everything with no marker-based filtering — arbitrary keys are supported, matching S3 semantics.
+
+**D-FB-3: deleteBatch chunks at 1,000**
+**Decision:** `deleteBatch()` internally chunks into groups of 1,000 and issues separate `DeleteObjects` calls.
+**Rationale:** S3 `DeleteObjects` API supports max 1,000 keys per request. Chunking is transparent to the caller. Batch methods handle pagination internally.
+
+**D-FB-4: Presigned URL default expiry of 3600 seconds**
+**Decision:** Both `getUrl` and `putUrl` default to 1 hour expiry.
+**Rationale:** Matches the S3 SDK default. Long enough for typical browser upload/download flows, short enough to limit exposure.
+
+**D-FB-5: scan returns AsyncIterable**
+**Decision:** `scan()` returns `AsyncIterable<FileInfo>` with internal pagination.
+**Rationale:** AsyncIterable is used for unbounded result sets. S3 `ListObjectsV2` paginates at 1,000 keys; the iterable handles continuation tokens transparently.
+
+**D-FB-6: Versioning is opt-in with runtime API support**
+**Decision:** `versioned: true` enables S3 object versioning and unlocks version-aware methods (`listVersions`, `restoreVersion`, optional `versionId` on `get`/`delete`/`getUrl`/`getFileHandle`). Without the flag, the API surface is unchanged.
+**Rationale:** Versioning adds storage cost and complexity. Making it opt-in keeps the default simple. When enabled, the runtime API exposes the full version lifecycle — listing, retrieving specific versions, permanent deletion of individual versions, and restoring old versions. `restoreVersion` is implemented as a CopyObject from the old version (S3 has no native restore), which creates a new version that becomes current.
+
+**D-FB-7: Mock versioning uses filesystem directories**
+**Decision:** Versioned mock stores each version in `versions/{key}/v{n}` with monotonic IDs. Delete markers are `versions/{key}/__deleted__` sentinel files.
+**Rationale:** Simple, inspectable, and matches the S3 semantics closely enough for local development. Monotonic IDs (`v1`, `v2`, ...) are deterministic and easy to reason about in tests, unlike S3's opaque version IDs. Version history lives under the segregated `versions/` root (see D-FB-2), so it never appears in `scan()` or collides with a user key.
+
+**D-FB-8: Bucket name validated at synth — error, never truncate/hash**
+**Decision:** The derived bucket name (`scope.fullId`) is validated against S3's naming rules (`bucket-name.ts`) before the bucket is constructed. An invalid name throws a `ValidationFailed` error with an actionable message. The same validator runs in the mock constructor so local dev (`bb dev`) fails identically — parity. `FileBucket.fromExisting(...)` skips validation since the name is externally owned.
+**Rationale:** S3 bucket names are globally unique and immutable. Truncating to fit 63 chars risks collisions, and a name that shifts between deploys (e.g. after a hash input changes) would orphan or replace the customer's data — a far worse outcome than a fast, fixable synth error. Erroring puts the fix in the developer's hands (shorten a scope id once; the name is then stable forever) and matches the manual-shortening pattern already used in `bb-agent`. This deliberately differs from DynamoDB-backed BBs (KVStore/DistributedTable) which `substring(0, 255)` — DynamoDB's 255 limit is generous and table names are internal, disposable, and not globally unique, so silent truncation is acceptable there.
+
+## Infrastructure (CDK)
+
+Creates a single S3 bucket:
+
+- **Bucket name:** Derived from `scope.fullId` (the bucket id joined to its parent scope ids with `-`). Validated at synth against S3's naming rules — see D-FB-6.
+- **Block public access:** All four settings enabled (BLOCK_ALL)
+- **Encryption:** S3-managed keys (SSE-S3)
+- **Versioning:** Disabled by default, enabled via `options.versioned`
+- **CORS:** Configured from `options.corsRules` if provided
+- **Lifecycle rules:** Configured from `options.lifecycleRules` if provided
+- **Removal policy:** DESTROY (sandbox), configurable for production
+- **Auto-delete objects:** Enabled when removal policy is DESTROY
+- **Permissions:** `grantReadWrite` to the parent scope's handler automatically
+
+## Mock Implementation
+
+- Files stored on the local filesystem at `.bb-data/{scope.fullId}/` via `getMockDataDir()` from core.
+- Internal data is segregated into sibling roots so it can never collide with user keys (see D-FB-2):
+  - `content/{key}` — file body, byte-identical to what was written.
+  - `meta/{key}.json` — sidecar metadata.
+  - `versions/{key}/{versionId}` (+ `.json` sidecars, `__deleted__` marker) — version history.
+- Path mapping for both the mock and the dev file-server is centralized in `paths.ts` so they stay in lockstep.
+- Data persists across dev server restarts. Customers can wipe with `rm -rf .bb-data`.
+- Presigned URLs are served by the dev file-server at `/.bb-file-bucket/{scope.fullId}/{path}?token=...`. The path segments are URL-encoded; the server decodes them and validates an HMAC token scoped to method, path, and expiry. The HMAC secret (`LOCAL_FILE_SECRET` in `tokens.ts`) is a **per-process random value** — the token-minting mock and the validating dev file-server share the same in-process module instance, so tokens are unforgeable without being a hardcoded, source-visible literal.
+- Downloads are served with `X-Content-Type-Options: nosniff` and `Content-Disposition: attachment`. The stored body and its `Content-Type` are caller-controlled, so serving them inline would make the dev file-server a stored-XSS vector (an uploaded `text/html`/SVG payload executing in the app origin). Forcing a download + disabling MIME sniffing keeps local dev no weaker than S3-behind-CloudFront.
+- `scan()` recursively walks only the `content/` root and yields every file it finds — no marker-based filtering — so user keys are unrestricted.
+- The dev file-server's PUT handler delegates to the registered `FileBucket` instance (via a process-global registry) so uploads get versioning, key validation, and metadata. There is no direct-write fallback; an unregistered bucket fails loud with a 500.
+- Key length validated against S3's 1,024-byte limit (warns, does not reject).
+- Versioning fully supported: each `put` writes to `versions/{key}/v{n}`, delete without `versionId` places a `__deleted__` sentinel, `listVersions` reads the versions directory, `restoreVersion` copies an old version via `put`.
+
+### Mock vs AWS Behavior Differences
+
+| Behavior Difference | Impact | Mitigation |
+|------------|--------|------------|
+| No lifecycle rules | Objects never expire or transition locally | No mitigation — lifecycle rules are a background S3 process |
+| No CORS enforcement | Browser requests succeed regardless of origin locally | No mitigation — CORS is enforced by the browser + S3, not the mock |
+| No storage classes | Transition rules have no effect locally | No mitigation — storage classes are a cost optimization |
+| No multipart upload | Large files use simple write locally | No mitigation — mock uses `fs.writeFile` regardless of size |
+| Presigned URLs are localhost-only | URLs only work against the local dev server | No mitigation — expected behavior for local development |
+| No IAM enforcement | Permission errors only surface in AWS | No mitigation — IAM is handled by CDK grants automatically |
+| Filesystem path limits | Some OS path length limits differ from S3 key limits (1,024 bytes) | Mock validates key length and warns when it exceeds 1,024 bytes |
+| Path-traversal keys rejected locally | The mock maps keys onto the real filesystem, so it rejects keys that escape the bucket's content root (e.g. `../escape.txt`). S3 has no filesystem and treats `..` as a literal key segment, so it accepts such keys. A pathological key containing `..` that "works" on S3 will throw `ValidationFailed` locally. | Intentional — the guard prevents a local key from clobbering files outside `.bb-data`. Avoid `..` segments in keys (also S3 best practice). Covered by `src/path-containment.test.ts`. |
+| Non-atomic `put()` | On a versioned bucket, `put()` performs several separate `writeFileSync` calls (version body, version metadata, current body, current metadata, delete-marker cleanup). A crash or process kill mid-`put()` can leave torn state — a body with no metadata sidecar, or a version body with no `.json`. Real S3 `PutObject` is atomic per object. | No mitigation today — the filesystem layout has no transaction boundary. Acceptable for a dev mock (re-running `put()` heals it). See Open Question 4 (storage engine). |
+| Monotonic version IDs | Mock uses `v1`, `v2`, ... vs S3's opaque IDs | No impact — customer code should treat version IDs as opaque strings |
+| Content-Type signed into presigned PUT URLs | When `putUrl`/`createUploadHandle` are given a `contentType`, the AWS SDK signs `content-type` as a required header, so real S3 returns `403 SignatureDoesNotMatch` if the uploaded request's `Content-Type` differs from (or omits) the signed value. The dev file-server enforces the same check (`src/file-server.ts`) so an upload that would fail in prod also fails locally with 403, rather than silently succeeding. Uploads via `createUploadHandle().upload()` always send the signed header, so the typed-handle path round-trips in both environments. Covered by `src/file-server.test.ts`. |
+| Adjacent slashes in keys collapsed | The mock maps keys onto the filesystem via `path.join`, which collapses `//` to `/` (e.g. a key built from a URL-shaped value like `uploads/https://issuer:sub/f.txt`). A later `scan({ prefix })` whose prefix still contains `//` won't match the stored single-slash path, so the file appears "missing" locally. S3 treats keys as opaque byte strings and preserves `//`, so the same prefix matches in production. | Avoid embedding raw URL-shaped values (e.g. an OIDC `userId` of `${iss}:${sub}`) directly in keys — `encodeURIComponent()` the segment first. See the FileBucket README best-practices note. |

package/README.md

@@ -6,6 +6,8 @@ File storage backed by Amazon S3.
 
 **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`.
 
+> Design & mock parity details: [DESIGN.md](./DESIGN.md)
+
 ## API
 
 ```typescript
@@ -46,6 +48,39 @@ const bucket = new FileBucket(scope, id, options?)
 | `metadata` | `Record<string, string>` | Custom metadata key-value pairs. |
 | `cacheControl` | `string` | Cache-Control header value. |
 
+### CorsRule
+
+CORS configuration for browser-based access. Supplied via the `corsRules` option.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `allowedOrigins` | `string[]` | Origins permitted to make cross-origin requests (e.g., `['https://app.example.com']`). |
+| `allowedMethods` | `('GET' \| 'PUT' \| 'POST' \| 'DELETE' \| 'HEAD')[]` | HTTP methods permitted for cross-origin requests. |
+| `allowedHeaders` | `string[]` | Optional. Request headers permitted in the actual request. |
+| `exposedHeaders` | `string[]` | Optional. Response headers exposed to the browser. |
+| `maxAge` | `number` | Optional. Seconds the browser may cache the preflight response. |
+
+### LifecycleRule
+
+Lifecycle configuration for automatic expiration or storage-class transitions. Supplied via the `lifecycleRules` option.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `prefix` | `string` | Optional. Prefix filter — the rule applies only to keys starting with this prefix. Omit to apply to all objects. |
+| `expirationDays` | `number` | Optional. Days after creation to expire (delete) objects. |
+| `transitionToIaDays` | `number` | Optional. Days after creation to transition objects to Infrequent Access storage. |
+
+### FileVersionInfo
+
+Returned by `listVersions()` — one entry per object version, newest first.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `versionId` | `string` | The version identifier. |
+| `lastModified` | `Date` | When this version was created. |
+| `size` | `number` | Size in bytes. |
+| `isCurrent` | `boolean` | Whether this is the current (latest) version. |
+
 ### Error Handling
 
 `get()` returns `null` for a missing file — it does **not** throw `FileNotFound`. Check for null:

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

@@ -1 +1 @@
-{"version":3,"file":"file-server.d.ts","sourceRoot":"","sources":["../src/file-server.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAmC,MAAM,WAAW,CAAC;AAyCzE,wBAAgB,MAAM,CAAC,UAAU,EAAE,MAAM,QAkJxC"}
+{"version":3,"file":"file-server.d.ts","sourceRoot":"","sources":["../src/file-server.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAmC,MAAM,WAAW,CAAC;AAyCzE,wBAAgB,MAAM,CAAC,UAAU,EAAE,MAAM,QAiKxC"}

package/dist/file-server.js

@@ -116,7 +116,22 @@ export function attach(httpServer) {
                 catch { }
             }
             const body = readFileSync(readPath);
-            res.writeHead(200, { 'Content-Type': contentType, 'Content-Length': body.length.toString() });
+            // The stored object body and its Content-Type are attacker-controlled
+            // (any client with a presigned PUT can upload arbitrary bytes under an
+            // arbitrary content type). Serving that back inline turns the dev file
+            // server into a stored-XSS vector: an uploaded `text/html` (or sniffed
+            // HTML/SVG) payload would execute in the origin of the local app.
+            // `nosniff` stops the browser from MIME-sniffing octet-streams into
+            // HTML, and `Content-Disposition: attachment` forces a download rather
+            // than inline rendering — so an uploaded document can never run as a
+            // page. Real S3 objects served through CloudFront are hardened the same
+            // way; this keeps local dev from being weaker than production.
+            res.writeHead(200, {
+                'Content-Type': contentType,
+                'Content-Length': body.length.toString(),
+                'X-Content-Type-Options': 'nosniff',
+                'Content-Disposition': 'attachment',
+            });
             res.end(body);
         }
         else if (req.method === 'PUT') {

package/dist/file-server.test.js

@@ -60,6 +60,28 @@ describe('file-server: basic GET/PUT', () => {
         assert.strictEqual(getRes.status, 200, `GET failed: ${getRes.status}`);
         assert.strictEqual(await getRes.text(), 'hello world');
     });
+    test('GET hardens against stored XSS: nosniff + attachment disposition', async () => {
+        // A client uploads an HTML payload under a text/html content type — the
+        // classic stored-XSS setup. When the dev server serves it back it must
+        // never let the browser render it inline in the app's origin.
+        const bucket = new FileBucket(scope, 'fs-xss');
+        const putUrl = await bucket.putUrl('payload.html', { contentType: 'text/html' });
+        const adjustedPut = putUrl.replace(/localhost:\d+/, `localhost:${port}`);
+        const putRes = await fetch(adjustedPut, {
+            method: 'PUT',
+            body: '<script>alert(document.domain)</script>',
+            headers: { 'Content-Type': 'text/html' },
+        });
+        assert.strictEqual(putRes.status, 200, `PUT failed: ${putRes.status}`);
+        const getUrl = await bucket.getUrl('payload.html');
+        const adjustedGet = getUrl.replace(/localhost:\d+/, `localhost:${port}`);
+        const getRes = await fetch(adjustedGet);
+        assert.strictEqual(getRes.status, 200, `GET failed: ${getRes.status}`);
+        assert.strictEqual(getRes.headers.get('x-content-type-options'), 'nosniff', 'GET must send X-Content-Type-Options: nosniff');
+        assert.match(getRes.headers.get('content-disposition') ?? '', /^attachment/, 'GET must force download via Content-Disposition: attachment');
+        // consume the body so the socket closes cleanly
+        await getRes.arrayBuffer();
+    });
     test('GET non-existent file returns 404', async () => {
         const bucket = new FileBucket(scope, 'fs-404');
         const url = await bucket.getUrl('missing.txt');
@@ -72,6 +94,21 @@ describe('file-server: basic GET/PUT', () => {
         const res = await fetch(url);
         assert.strictEqual(res.status, 403);
     });
+    test('a token forged with the former hardcoded secret is rejected', async () => {
+        // The signing secret used to be a fixed, source-visible literal, so anyone
+        // could mint a valid token offline for any fullId/path without ever calling
+        // getUrl()/putUrl(). It is now a per-process random secret. A token signed
+        // with the old literal must no longer validate.
+        const bucket = new FileBucket(scope, 'fs-forge');
+        const putUrl = await bucket.putUrl('secret.txt', { contentType: 'text/plain' });
+        const adjustedPut = putUrl.replace(/localhost:\d+/, `localhost:${port}`);
+        await fetch(adjustedPut, { method: 'PUT', body: 'data', headers: { 'Content-Type': 'text/plain' } });
+        const forged = mintFileToken('fsrv-fs-forge', 'secret.txt', 'GET', 3600, '__blocks_file_bucket_dev_secret__');
+        const url = `http://localhost:${port}/.bb-file-bucket/fsrv-fs-forge/secret.txt?token=${forged}`;
+        const res = await fetch(url);
+        await res.arrayBuffer();
+        assert.strictEqual(res.status, 403, 'a token forged with the old hardcoded secret must be rejected');
+    });
     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

package/dist/tokens.d.ts

@@ -1,4 +1,20 @@
-export declare const LOCAL_FILE_SECRET = "__blocks_file_bucket_dev_secret__";
+/**
+ * Per-process HMAC secret for signing local presigned-URL tokens.
+ *
+ * The mock bucket (which mints tokens) and the dev file server (which validates
+ * them) both import this module and run in the *same* dev-server process, so a
+ * value generated once at module load is shared between them via the ESM module
+ * cache — no configuration needed.
+ *
+ * This deliberately replaces a previously hardcoded literal. A fixed, source-
+ * visible secret let anyone forge a valid token for any `fullId`/path/method and
+ * hit the dev file server without ever calling `getUrl()`/`putUrl()`, defeating
+ * the point of signing. A random per-process secret makes tokens unforgeable
+ * while keeping the local round-trip working, since both ends share this value.
+ * Tokens do not need to survive a dev-server restart (presigned URLs are short-
+ * lived and re-minted on demand), so per-process randomness is sufficient.
+ */
+export declare const LOCAL_FILE_SECRET: string;
 interface FileTokenPayload {
     fullId: string;
     path: string;

package/dist/tokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,iBAAiB,sCAAsC,CAAC;AAErE,UAAU,gBAAgB;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,KAAK,GAAG,KAAK,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;CACZ;AAED,wBAAgB,aAAa,CAC5B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,KAAK,GAAG,KAAK,EACrB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,WAAW,CAAC,EAAE,MAAM,GAClB,MAAM,CAWR;AAED,wBAAgB,iBAAiB,CAChC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,KAAK,GAAG,KAAK,GAC3B,gBAAgB,GAAG,IAAI,CAgBzB"}
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,iBAAiB,QAAwC,CAAC;AAEvE,UAAU,gBAAgB;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,KAAK,GAAG,KAAK,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;CACZ;AAED,wBAAgB,aAAa,CAC5B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,KAAK,GAAG,KAAK,EACrB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,WAAW,CAAC,EAAE,MAAM,GAClB,MAAM,CAWR;AAED,wBAAgB,iBAAiB,CAChC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,KAAK,GAAG,KAAK,GAC3B,gBAAgB,GAAG,IAAI,CAgBzB"}

package/dist/tokens.js

@@ -1,9 +1,25 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
-import { createHmac } from 'node:crypto';
+import { createHmac, randomBytes } from 'node:crypto';
 import { constantTimeEquals } from '@aws-blocks/core/bb-utils';
 // ── Token helpers ───────────────────────────────────────────────────────────
-export const LOCAL_FILE_SECRET = '__blocks_file_bucket_dev_secret__';
+/**
+ * Per-process HMAC secret for signing local presigned-URL tokens.
+ *
+ * The mock bucket (which mints tokens) and the dev file server (which validates
+ * them) both import this module and run in the *same* dev-server process, so a
+ * value generated once at module load is shared between them via the ESM module
+ * cache — no configuration needed.
+ *
+ * This deliberately replaces a previously hardcoded literal. A fixed, source-
+ * visible secret let anyone forge a valid token for any `fullId`/path/method and
+ * hit the dev file server without ever calling `getUrl()`/`putUrl()`, defeating
+ * the point of signing. A random per-process secret makes tokens unforgeable
+ * while keeping the local round-trip working, since both ends share this value.
+ * Tokens do not need to survive a dev-server restart (presigned URLs are short-
+ * lived and re-minted on demand), so per-process randomness is sufficient.
+ */
+export const LOCAL_FILE_SECRET = randomBytes(32).toString('base64url');
 export function mintFileToken(fullId, path, method, expiresIn, secret, contentType) {
     const payload = {
         fullId,

package/dist/version.d.ts

@@ -1,3 +1,3 @@
 export declare const BB_NAME = "FileBucket";
-export declare const BB_VERSION = "0.1.1";
+export declare const BB_VERSION = "0.1.3";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -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.1';
+export const BB_VERSION = '0.1.3';

package/package.json

@@ -1,6 +1,15 @@
 {
   "name": "@aws-blocks/bb-file-bucket",
-  "version": "0.1.1",
+  "version": "0.1.3",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aws-devtools-labs/aws-blocks.git",
+    "directory": "packages/bb-file-bucket"
+  },
+  "homepage": "https://github.com/aws-devtools-labs/aws-blocks/tree/main/packages/bb-file-bucket#readme",
+  "bugs": {
+    "url": "https://github.com/aws-devtools-labs/aws-blocks/issues"
+  },
   "author": "Amazon Web Services",
   "license": "Apache-2.0",
   "type": "module",
@@ -41,8 +50,8 @@
     "test": "node --test dist/index.test.js dist/index.cdk.test.js dist/scan.test.js dist/file-server.test.js dist/url-encoding.test.js dist/path-containment.test.js dist/bucket-name.test.js"
   },
   "dependencies": {
-    "@aws-blocks/bb-logger": "^0.1.1",
-    "@aws-blocks/core": "^0.1.1",
+    "@aws-blocks/bb-logger": "^0.1.3",
+    "@aws-blocks/core": "^0.1.17",
     "@aws-sdk/client-s3": "^3.0.0",
     "@aws-sdk/s3-request-presigner": "^3.0.0"
   },

package/src/file-server.test.ts

@@ -72,6 +72,38 @@ describe('file-server: basic GET/PUT', () => {
 		assert.strictEqual(await getRes.text(), 'hello world');
 	});
 
+	test('GET hardens against stored XSS: nosniff + attachment disposition', async () => {
+		// A client uploads an HTML payload under a text/html content type — the
+		// classic stored-XSS setup. When the dev server serves it back it must
+		// never let the browser render it inline in the app's origin.
+		const bucket = new FileBucket(scope, 'fs-xss');
+		const putUrl = await bucket.putUrl('payload.html', { contentType: 'text/html' });
+		const adjustedPut = putUrl.replace(/localhost:\d+/, `localhost:${port}`);
+		const putRes = await fetch(adjustedPut, {
+			method: 'PUT',
+			body: '<script>alert(document.domain)</script>',
+			headers: { 'Content-Type': 'text/html' },
+		});
+		assert.strictEqual(putRes.status, 200, `PUT failed: ${putRes.status}`);
+
+		const getUrl = await bucket.getUrl('payload.html');
+		const adjustedGet = getUrl.replace(/localhost:\d+/, `localhost:${port}`);
+		const getRes = await fetch(adjustedGet);
+		assert.strictEqual(getRes.status, 200, `GET failed: ${getRes.status}`);
+		assert.strictEqual(
+			getRes.headers.get('x-content-type-options'),
+			'nosniff',
+			'GET must send X-Content-Type-Options: nosniff',
+		);
+		assert.match(
+			getRes.headers.get('content-disposition') ?? '',
+			/^attachment/,
+			'GET must force download via Content-Disposition: attachment',
+		);
+		// consume the body so the socket closes cleanly
+		await getRes.arrayBuffer();
+	});
+
 	test('GET non-existent file returns 404', async () => {
 		const bucket = new FileBucket(scope, 'fs-404');
 		const url = await bucket.getUrl('missing.txt');
@@ -87,6 +119,23 @@ describe('file-server: basic GET/PUT', () => {
 		assert.strictEqual(res.status, 403);
 	});
 
+	test('a token forged with the former hardcoded secret is rejected', async () => {
+		// The signing secret used to be a fixed, source-visible literal, so anyone
+		// could mint a valid token offline for any fullId/path without ever calling
+		// getUrl()/putUrl(). It is now a per-process random secret. A token signed
+		// with the old literal must no longer validate.
+		const bucket = new FileBucket(scope, 'fs-forge');
+		const putUrl = await bucket.putUrl('secret.txt', { contentType: 'text/plain' });
+		const adjustedPut = putUrl.replace(/localhost:\d+/, `localhost:${port}`);
+		await fetch(adjustedPut, { method: 'PUT', body: 'data', headers: { 'Content-Type': 'text/plain' } });
+
+		const forged = mintFileToken('fsrv-fs-forge', 'secret.txt', 'GET', 3600, '__blocks_file_bucket_dev_secret__');
+		const url = `http://localhost:${port}/.bb-file-bucket/fsrv-fs-forge/secret.txt?token=${forged}`;
+		const res = await fetch(url);
+		await res.arrayBuffer();
+		assert.strictEqual(res.status, 403, 'a token forged with the old hardcoded secret must be rejected');
+	});
+
 	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

package/src/file-server.ts

@@ -141,7 +141,22 @@ export function attach(httpServer: Server) {
 			}
 
 			const body = readFileSync(readPath);
-			res.writeHead(200, { 'Content-Type': contentType, 'Content-Length': body.length.toString() });
+			// The stored object body and its Content-Type are attacker-controlled
+			// (any client with a presigned PUT can upload arbitrary bytes under an
+			// arbitrary content type). Serving that back inline turns the dev file
+			// server into a stored-XSS vector: an uploaded `text/html` (or sniffed
+			// HTML/SVG) payload would execute in the origin of the local app.
+			// `nosniff` stops the browser from MIME-sniffing octet-streams into
+			// HTML, and `Content-Disposition: attachment` forces a download rather
+			// than inline rendering — so an uploaded document can never run as a
+			// page. Real S3 objects served through CloudFront are hardened the same
+			// way; this keeps local dev from being weaker than production.
+			res.writeHead(200, {
+				'Content-Type': contentType,
+				'Content-Length': body.length.toString(),
+				'X-Content-Type-Options': 'nosniff',
+				'Content-Disposition': 'attachment',
+			});
 			res.end(body);
 		} else if (req.method === 'PUT') {
 			const valid = validateFileToken(token, LOCAL_FILE_SECRET, fullId, path, 'PUT');

package/src/tokens.ts

@@ -1,12 +1,28 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import { createHmac } from 'node:crypto';
+import { createHmac, randomBytes } from 'node:crypto';
 import { constantTimeEquals } from '@aws-blocks/core/bb-utils';
 
 // ── Token helpers ───────────────────────────────────────────────────────────
 
-export const LOCAL_FILE_SECRET = '__blocks_file_bucket_dev_secret__';
+/**
+ * Per-process HMAC secret for signing local presigned-URL tokens.
+ *
+ * The mock bucket (which mints tokens) and the dev file server (which validates
+ * them) both import this module and run in the *same* dev-server process, so a
+ * value generated once at module load is shared between them via the ESM module
+ * cache — no configuration needed.
+ *
+ * This deliberately replaces a previously hardcoded literal. A fixed, source-
+ * visible secret let anyone forge a valid token for any `fullId`/path/method and
+ * hit the dev file server without ever calling `getUrl()`/`putUrl()`, defeating
+ * the point of signing. A random per-process secret makes tokens unforgeable
+ * while keeping the local round-trip working, since both ends share this value.
+ * Tokens do not need to survive a dev-server restart (presigned URLs are short-
+ * lived and re-minted on demand), so per-process randomness is sufficient.
+ */
+export const LOCAL_FILE_SECRET = randomBytes(32).toString('base64url');
 
 interface FileTokenPayload {
 	fullId: 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.1';
+export const BB_VERSION = '0.1.3';