feat(storage): service worker streaming for zip download (#7044)

* feat(storage): service worker streaming zip download

Replace the in-memory blob-based zip download with a service worker
streaming architecture for StorageBrowser multi-file downloads.
Falls back to blob collection when the SW is unavailable.

Key changes:
- Add download-sw.ts service worker with skipWaiting + clients.claim
- Add zipdownload handler with WeakMap-scoped batch state (no singleton)
- Stream files sequentially into zip via zip.js (concurrency=1)
- MessageChannel handshake for SW stream transfer + keepalive pings
- Blob fallback with inline cleanup (no fire-and-forget race)
- composedDownloadHandler routes single-file vs multi-file downloads
- useServiceWorkerRegistration hook for automatic SW registration
- copy-serviceworker bin script for npm consumers
- Documentation for SW setup across frameworks
- Comprehensive test suite with deterministic async flushing

* fix(storage): verify message origin in download SW, raise size limit

- Add same-origin verification to the service worker message handler,
  addressing CodeQL finding 'Missing origin verification in postMessage
  handler'. Cross-origin messages are now rejected before any stream is
  stored or acknowledged.
- Add a regression test asserting foreign-origin messages are ignored;
  update existing message mocks to carry the same-origin value.
- Raise createStorageBrowser size-limit 130 kB -> 131 kB to accommodate
  the SW streaming code (was over by 21 B).
- Add changeset for the feature.

* docs(storage): note download-only progress in changeset

Address review feedback: document that per-file progress is download-only
by design (reflects S3 read bytes, not zip finalization), since level:0
storage makes the finalization phase near-instant.

* fix(storage): address review feedback on SW streaming download

- download-sw.ts: decode the request pathname before the pendingStreams
  lookup so folder names with spaces / URL-unsafe characters resolve
  (blocker: browser percent-encodes the id in the <a> navigation while the
  stream is keyed by the unencoded id).
- download-sw.ts: use RFC 5987 'filename*=UTF-8''...' Content-Disposition so
  quotes/backslashes/UTF-8 in S3 keys are handled without escaping issues.
- zipdownload.ts: guard the getRegistration().then() callback with a
  cancelled check so a keepalive interval is never created after the batch
  was reset (fixes an interval leak when cancel races swReady).
- zipdownload.ts: drop fragile substring matching on zip.js internal error
  messages; flag cancellation from batchAbort.signal.aborted or the standard
  AbortError name only.
- useServiceWorkerRegistration.ts: warn in development when SW registration
  fails (surfaces the common 'forgot copy-serviceworker' setup mistake).
- copy-serviceworker.js: drop redundant existsSync before recursive mkdirSync
  (also closes a TOCTOU window).
- tests: SW round-trip test for unencoded-store/encoded-request + RFC 5987
  assertions; genuine early-exit cancelled-path test; space-in-folder test.
- Revert an unintended workflow change (reusable-build-system-test-react-native.yml)
  that a prior rebase resolution pulled in; file now matches main.

* fix(storage): stop cancel resurrection + leaked timestamp in SW filename

- zipdownload.ts: cancelBatch() no longer calls reset() synchronously. The
  cancelled flag and the batchMap entry share one key, so deleting the entry
  let the next queued file (concurrency: 1) miss the cancelled early-exit and
  build a fresh batch — resurrecting the download (files 2..N still zipped).
  The entry is now kept (tombstoned, keepalive stopped) until batchDone ===
  batchTotal, so remaining files drain through the early-exit. reset() remains
  the sole map-deleter, for both the cancel and completion paths.
- download-sw.ts / zipdownload.ts: the SW filename is now sent explicitly
  (`${folder}.zip`) in the postMessage and stored alongside the stream. The
  Content-Disposition header uses it instead of deriving from downloadId, which
  embeds Date.now() for map-key uniqueness. Previously the same-origin
  Content-Disposition (which wins over the anchor download attr) saved
  e.g. photos-1720080000000.zip on the SW path while the blob fallback saved
  photos.zip — now both agree and no timestamp leaks.
- useServiceWorkerRegistration.ts: drop process.env.NODE_ENV guard (TS2591
  'Cannot find name process' in the browser rollup build — no node types) and
  warn unconditionally; a SW registration failure is a real degradation.
- tests: SW explicit-filename precedence; UI-cancel no-resurrection guard
  (exactly one ZipWriter constructed across a cancelled 2-file batch).

Author: bobbor

.changeset/sw-streaming-download.md

@@ -0,0 +1,18 @@
+---
+'@aws-amplify/ui-react-storage': minor
+---
+
+feat(storage): service worker streaming zip download
+
+Replace the in-memory blob-based zip download with a service worker streaming
+architecture for `StorageBrowser` multi-file downloads. Files are streamed
+sequentially into a zip archive delivered via a service worker, removing the
+memory ceiling of the previous blob approach. Falls back to blob collection
+when the service worker is unavailable (unsupported browser, missing file, or
+insecure context).
+
+Note: per-file progress is now reported download-only by design — it reflects
+bytes read from S3, not zip finalization. Because entries are stored without
+compression (`level: 0`), the write/finalization phase is near-instant, so
+progress transitions directly from downloading to complete without a separate
+"zipping"/finishing phase.

.gitignore

@@ -43,3 +43,4 @@ coverage/
 # Vite
 vite.config.js.timestamp-*
 vite.config.ts.timestamp-*
+*.tgz

docs/src/pages/[platform]/connected-components/storage/storage-browser/react.mdx

@@ -283,6 +283,79 @@ interface Config {
 </ExampleCode>
 </Example>
 
+### Download Service Worker
+
+The `StorageBrowser` component uses a [Service Worker](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) to enable streaming zip downloads for multi-file selections. This allows downloading large batches of files without memory limitations, as the zip is streamed directly to disk rather than being assembled in memory.
+
+#### Setup
+
+The service worker file must be served from your application's public directory. The `@aws-amplify/ui-react-storage` package includes a CLI tool to copy it for you:
+
+<Example>
+<ExampleCode>
+```bash
+npx @aws-amplify/ui-react-storage copy-serviceworker public
+```
+</ExampleCode>
+</Example>
+
+This copies `download-sw.js` into `<target>/amplify-storage-download/download-sw.js`, making it available under the service worker's scope path.
+
+#### Framework setup
+
+**Next.js / Vite / Create React App:**
+
+Run the copy command once after installing the package. The file will be served automatically from the `public/` folder.
+
+**Amplify Hosting (amplify.yml):**
+
+Add the copy step to your build spec so the service worker is available on every deploy:
+
+<Example>
+<ExampleCode>
+```yaml
+frontend:
+  phases:
+    preBuild:
+      commands:
+        - npx @aws-amplify/ui-react-storage copy-serviceworker public
+    build:
+      commands:
+        - npm run build
+```
+</ExampleCode>
+</Example>
+
+**npm scripts (recommended):**
+
+Add it to your `postinstall` or `prebuild` script so it stays up to date automatically:
+
+<Example>
+<ExampleCode>
+```json
+{
+  "scripts": {
+    "prebuild": "npx @aws-amplify/ui-react-storage copy-serviceworker public"
+  }
+}
+```
+</ExampleCode>
+</Example>
+
+#### How it works
+
+When a user downloads multiple files, the `StorageBrowser` component:
+
+1. Registers the service worker at `/amplify-storage-download/download-sw.js` with scope `/amplify-storage-download/`
+2. Streams each file from S3 into a zip archive
+3. Delivers the zip via the service worker, enabling streaming to disk without size limits
+
+If the service worker is not available (e.g., unsupported browser, missing file, or insecure context), the component automatically falls back to an in-memory blob-based download.
+
+<Message colorTheme="info" variation="filled" heading="Service Worker scope">
+The service worker is registered with scope `/amplify-storage-download/`. It only intercepts requests within this scope and does not affect other parts of your application.
+</Message>
+
 ## Customization
 
 ### Pagination

packages/react-storage/bin/copy-serviceworker.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const SW_FILENAME = 'download-sw.js';
+const SW_SOURCE = path.resolve(__dirname, '..', 'dist', SW_FILENAME);
+
+const targetDir = process.argv[2];
+
+if (!targetDir) {
+  console.error(
+    'Usage: npx @aws-amplify/ui-react-storage copy-serviceworker <target-dir>\n' +
+      'Example: npx @aws-amplify/ui-react-storage copy-serviceworker public'
+  );
+  process.exit(1);
+}
+
+if (!fs.existsSync(SW_SOURCE)) {
+  console.error(
+    `Error: Service worker source not found at ${SW_SOURCE}\n` +
+      'Make sure the package is properly installed.'
+  );
+  process.exit(1);
+}
+
+const resolvedTarget = path.resolve(targetDir, 'amplify-storage-download');
+
+// `recursive: true` is a no-op when the directory already exists, so no
+// existence check is needed (and skipping it avoids a TOCTOU window).
+fs.mkdirSync(resolvedTarget, { recursive: true });
+
+const dest = path.join(resolvedTarget, SW_FILENAME);
+fs.copyFileSync(SW_SOURCE, dest);
+console.log(`✅ Copied ${SW_FILENAME} → ${dest}`);

packages/react-storage/eslint.config.js

@@ -32,6 +32,8 @@ module.exports = defineConfig([
     '**/coverage',
     '**/dist',
     '**/node_modules',
+    '**/service-worker',
+    '**/bin',
   ]),
   {
     extends: compat.extends('@aws-amplify/amplify-ui/jest'),

packages/react-storage/package.json

@@ -20,6 +20,9 @@
     "./styles.css": "./dist/styles.css"
   },
   "types": "dist/types/index.d.ts",
+  "bin": {
+    "copy-serviceworker": "./bin/copy-serviceworker.js"
+  },
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -28,6 +31,7 @@
   },
   "files": [
     "dist",
+    "bin",
     "LICENSE",
     "browser"
   ],
@@ -43,7 +47,7 @@
     "size": "yarn size-limit",
     "test": "jest",
     "test:watch": "yarn test --watch",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit && tsc --project tsconfig.sw.json --noEmit"
   },
   "dependencies": {
     "@aws-amplify/ui": "6.15.4",
@@ -69,7 +73,7 @@
       "name": "createStorageBrowser",
       "path": "dist/esm/browser.mjs",
       "import": "{ createStorageBrowser }",
-      "limit": "130 kB",
+      "limit": "131 kB",
       "ignore": [
         "@aws-amplify/storage"
       ]

packages/react-storage/rollup.config.mjs

@@ -62,6 +62,21 @@ const config = defineConfig([
     },
     plugins: [styles({ mode: ['extract'] })],
   },
+  // Service Worker — standalone IIFE, no externals, self-contained
+  {
+    input: 'src/components/StorageBrowser/service-worker/download-sw.ts',
+    output: {
+      file: 'dist/download-sw.js',
+      format: 'iife',
+    },
+    plugins: [
+      typescript({
+        declaration: false,
+        sourceMap: false,
+        tsconfig: 'tsconfig.sw.json',
+      }),
+    ],
+  },
 ]);
 
 export default config;