@remix-run/file-storage-s3 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Shopify Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,47 @@
-# Placeholder Package
+# file-storage-s3
 
-This package is a placeholder published at `0.0.0` to reserve the npm name and configure CI publish permissions.
+S3 backend for [`remix/file-storage`](https://github.com/remix-run/remix/tree/main/packages/file-storage).
+Use this package when you want the `FileStorage` API backed by AWS S3 or an S3-compatible provider.
+
+## Features
+
+- **S3-Compatible API** - Works with AWS S3 and S3-compatible APIs (e.g. MinIO, LocalStack)
+- **Metadata Preservation** - Preserves `File` metadata (`name`, `type`, `lastModified`)
+- **Runtime-Agnostic Signing** - Uses [`aws4fetch`](https://github.com/mhart/aws4fetch) for SigV4 signing
+
+## Installation
+
+```sh
+npm i remix
+```
+
+## Usage
+
+```ts
+import { createS3FileStorage } from 'remix/file-storage-s3'
+
+let storage = createS3FileStorage({
+  accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+  bucket: 'my-app-uploads',
+  region: 'us-east-1',
+})
+
+await storage.set(
+  'uploads/hello.txt',
+  new File(['hello world'], 'hello.txt', { type: 'text/plain' }),
+)
+let file = await storage.get('uploads/hello.txt')
+await storage.remove('uploads/hello.txt')
+```
+
+For S3-compatible providers such as MinIO and LocalStack, set `endpoint` and `forcePathStyle: true`.
+
+## Related Packages
+
+- [`file-storage`](https://github.com/remix-run/remix/tree/main/packages/file-storage) - Core `FileStorage` interface and filesystem/memory backends
+- [`form-data-parser`](https://github.com/remix-run/remix/tree/main/packages/form-data-parser) - Parses `multipart/form-data` uploads into `FileUpload` objects
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { type S3FileStorageOptions, createS3FileStorage } from './lib/s3.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -0,0 +1 @@
+export { createS3FileStorage } from "./lib/s3.js";

package/dist/lib/s3.d.ts

@@ -0,0 +1,47 @@
+import type { FileStorage } from '@remix-run/file-storage';
+export interface S3FileStorageOptions {
+    /**
+     * AWS access key ID used to sign S3 requests.
+     */
+    accessKeyId: string;
+    /**
+     * AWS secret access key used to sign S3 requests.
+     */
+    secretAccessKey: string;
+    /**
+     * Bucket name used for all file storage operations.
+     */
+    bucket: string;
+    /**
+     * AWS region for request signing.
+     */
+    region: string;
+    /**
+     * Custom S3-compatible endpoint URL. Defaults to AWS S3 for the given region.
+     */
+    endpoint?: string;
+    /**
+     * Whether to use path-style bucket URLs (`/bucket/key`). Defaults to `true` when `endpoint` is
+     * provided and `false` otherwise.
+     */
+    forcePathStyle?: boolean;
+    /**
+     * Optional session token for temporary credentials.
+     */
+    sessionToken?: string;
+    /**
+     * Optional fetch implementation.
+     */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * Creates an S3-backed implementation of `FileStorage`.
+ *
+ * This works with AWS S3 and S3-compatible providers (for example MinIO or LocalStack) by
+ * overriding the `endpoint` option.
+ *
+ * @param options Configuration for the S3 backend
+ * @returns A `FileStorage` implementation backed by S3
+ */
+export declare function createS3FileStorage(options: S3FileStorageOptions): FileStorage;
+//# sourceMappingURL=s3.d.ts.map

package/dist/lib/s3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3.d.ts","sourceRoot":"","sources":["../../src/lib/s3.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAgB,WAAW,EAA2B,MAAM,yBAAyB,CAAA;AAUjG,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;OAEG;IACH,eAAe,EAAE,MAAM,CAAA;IACvB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IACd;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IACd;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;CAChC;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,WAAW,CAgL9E"}

package/dist/lib/s3.js

@@ -0,0 +1,292 @@
+import { AwsClient } from 'aws4fetch';
+const CONTENTS_PATTERN = /<Contents>([\s\S]*?)<\/Contents>/g;
+/**
+ * Creates an S3-backed implementation of `FileStorage`.
+ *
+ * This works with AWS S3 and S3-compatible providers (for example MinIO or LocalStack) by
+ * overriding the `endpoint` option.
+ *
+ * @param options Configuration for the S3 backend
+ * @returns A `FileStorage` implementation backed by S3
+ */
+export function createS3FileStorage(options) {
+    let endpoint = new URL(options.endpoint ?? `https://s3.${options.region}.amazonaws.com`);
+    let forcePathStyle = options.forcePathStyle ?? options.endpoint != null;
+    let aws = new AwsClient({
+        accessKeyId: options.accessKeyId,
+        secretAccessKey: options.secretAccessKey,
+        sessionToken: options.sessionToken,
+        service: 's3',
+        region: options.region,
+    });
+    async function s3Fetch(url, init) {
+        let request = await aws.sign(url, init);
+        if (options.fetch != null) {
+            return options.fetch(request);
+        }
+        return fetch(request);
+    }
+    function getBucketUrl() {
+        return createBucketUrl(endpoint, options.bucket, forcePathStyle);
+    }
+    function getObjectUrl(key) {
+        return createObjectUrl(endpoint, options.bucket, forcePathStyle, key);
+    }
+    async function putFile(key, file) {
+        let body = await file.arrayBuffer();
+        let headers = new Headers();
+        if (file.type !== '') {
+            headers.set('content-type', file.type);
+        }
+        headers.set('x-amz-meta-file-name', encodeMetadataValue(file.name));
+        headers.set('x-amz-meta-file-last-modified', String(file.lastModified));
+        let response = await s3Fetch(getObjectUrl(key), {
+            method: 'PUT',
+            headers,
+            body,
+        });
+        await assertOk(response, `PUT "${key}"`);
+        return new File([body], file.name, {
+            lastModified: file.lastModified,
+            type: file.type,
+        });
+    }
+    async function getFileMetadata(object) {
+        let response = await s3Fetch(getObjectUrl(object.key), { method: 'HEAD' });
+        if (response.status === 404) {
+            return {
+                key: object.key,
+                lastModified: object.lastModified,
+                name: getDefaultFileName(object.key),
+                size: object.size,
+                type: '',
+            };
+        }
+        await assertOk(response, `HEAD "${object.key}"`);
+        return {
+            key: object.key,
+            lastModified: parseEpochMillis(response.headers.get('x-amz-meta-file-last-modified')) ??
+                object.lastModified,
+            name: decodeMetadataValue(response.headers.get('x-amz-meta-file-name')) ??
+                getDefaultFileName(object.key),
+            size: parseInteger(response.headers.get('content-length')) ?? object.size,
+            type: response.headers.get('content-type') ?? '',
+        };
+    }
+    return {
+        async get(key) {
+            let response = await s3Fetch(getObjectUrl(key), { method: 'GET' });
+            if (response.status === 404) {
+                return null;
+            }
+            await assertOk(response, `GET "${key}"`);
+            let body = await response.arrayBuffer();
+            return new File([body], decodeMetadataValue(response.headers.get('x-amz-meta-file-name')) ??
+                getDefaultFileName(key), {
+                lastModified: parseEpochMillis(response.headers.get('x-amz-meta-file-last-modified')) ??
+                    parseHttpDate(response.headers.get('last-modified')) ??
+                    0,
+                type: response.headers.get('content-type') ?? '',
+            });
+        },
+        async has(key) {
+            let response = await s3Fetch(getObjectUrl(key), { method: 'HEAD' });
+            if (response.status === 404) {
+                return false;
+            }
+            await assertOk(response, `HEAD "${key}"`);
+            return true;
+        },
+        async list(options) {
+            let { cursor, includeMetadata = false, limit = 32, prefix } = options ?? {};
+            if (limit <= 0) {
+                return {
+                    files: [],
+                };
+            }
+            let url = getBucketUrl();
+            url.searchParams.set('encoding-type', 'url');
+            url.searchParams.set('list-type', '2');
+            url.searchParams.set('max-keys', String(limit));
+            if (cursor !== undefined) {
+                url.searchParams.set('continuation-token', cursor);
+            }
+            if (prefix !== undefined) {
+                url.searchParams.set('prefix', prefix);
+            }
+            let response = await s3Fetch(url, { method: 'GET' });
+            await assertOk(response, 'LIST');
+            let xml = await response.text();
+            let objects = parseListedObjects(xml);
+            let nextCursor = parseNextCursor(xml);
+            if (!includeMetadata) {
+                return {
+                    cursor: nextCursor,
+                    files: objects.map((object) => ({ key: object.key })),
+                };
+            }
+            let files = await Promise.all(objects.map((object) => getFileMetadata(object)));
+            return {
+                cursor: nextCursor,
+                files: files,
+            };
+        },
+        put(key, file) {
+            return putFile(key, file);
+        },
+        async remove(key) {
+            let response = await s3Fetch(getObjectUrl(key), { method: 'DELETE' });
+            if (response.status === 404) {
+                return;
+            }
+            await assertOk(response, `DELETE "${key}"`);
+        },
+        async set(key, file) {
+            await putFile(key, file);
+        },
+    };
+}
+function createBucketUrl(endpoint, bucket, forcePathStyle) {
+    let url = new URL(endpoint.toString());
+    if (forcePathStyle) {
+        url.pathname = joinPath(endpoint.pathname, encodeURIComponent(bucket));
+    }
+    else {
+        url.hostname = `${bucket}.${endpoint.hostname}`;
+        url.pathname = joinPath(endpoint.pathname);
+    }
+    return url;
+}
+function createObjectUrl(endpoint, bucket, forcePathStyle, key) {
+    let url = new URL(endpoint.toString());
+    if (forcePathStyle) {
+        url.pathname = joinPath(endpoint.pathname, encodeURIComponent(bucket), encodeS3Key(key));
+    }
+    else {
+        url.hostname = `${bucket}.${endpoint.hostname}`;
+        url.pathname = joinPath(endpoint.pathname, encodeS3Key(key));
+    }
+    return url;
+}
+function encodeS3Key(key) {
+    return key
+        .split('/')
+        .map((segment) => encodeURIComponent(segment))
+        .join('/');
+}
+function encodeMetadataValue(value) {
+    return encodeURIComponent(value);
+}
+function decodeMetadataValue(value) {
+    if (value == null || value === '') {
+        return undefined;
+    }
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+function getDefaultFileName(key) {
+    let lastSlashIndex = key.lastIndexOf('/');
+    let fileName = lastSlashIndex >= 0 ? key.slice(lastSlashIndex + 1) : key;
+    return fileName === '' ? key : fileName;
+}
+function parseListedObjects(xml) {
+    CONTENTS_PATTERN.lastIndex = 0;
+    let objects = [];
+    for (let match of xml.matchAll(CONTENTS_PATTERN)) {
+        let entry = match[1] ?? '';
+        let encodedKey = readXmlTag(entry, 'Key');
+        if (encodedKey == null) {
+            continue;
+        }
+        let key = decodeS3Key(encodedKey);
+        let size = parseInteger(readXmlTag(entry, 'Size')) ?? 0;
+        let lastModified = parseHttpDate(readXmlTag(entry, 'LastModified')) ?? 0;
+        objects.push({
+            key,
+            lastModified,
+            size,
+        });
+    }
+    return objects;
+}
+function parseNextCursor(xml) {
+    if (readXmlTag(xml, 'IsTruncated') !== 'true') {
+        return undefined;
+    }
+    return readXmlTag(xml, 'NextContinuationToken');
+}
+function decodeS3Key(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+function readXmlTag(xml, tagName) {
+    let pattern = new RegExp(`<${tagName}>([\\s\\S]*?)</${tagName}>`);
+    let match = xml.match(pattern);
+    if (match == null || match[1] == null) {
+        return undefined;
+    }
+    return decodeXmlEntities(match[1]);
+}
+function decodeXmlEntities(value) {
+    return value
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&apos;/g, "'");
+}
+function parseInteger(value) {
+    if (value == null || value === '') {
+        return undefined;
+    }
+    let parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function parseEpochMillis(value) {
+    let parsed = parseInteger(value);
+    return parsed != null ? parsed : undefined;
+}
+function parseHttpDate(value) {
+    if (value == null || value === '') {
+        return undefined;
+    }
+    let parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function joinPath(basePath, ...parts) {
+    let normalizedBasePath = basePath.replace(/\/+$/g, '');
+    let normalizedParts = parts
+        .filter((part) => part != null && part !== '')
+        .map((part) => part.replace(/^\/+|\/+$/g, ''));
+    let joined = [normalizedBasePath, ...normalizedParts].filter((part) => part !== '').join('/');
+    if (joined === '') {
+        return '/';
+    }
+    return joined.startsWith('/') ? joined : `/${joined}`;
+}
+async function assertOk(response, operation) {
+    if (response.ok) {
+        return;
+    }
+    let message = `${response.status} ${response.statusText}`;
+    try {
+        let body = await response.text();
+        let s3Message = readXmlTag(body, 'Message');
+        if (s3Message != null && s3Message !== '') {
+            message = `${message} (${s3Message})`;
+        }
+    }
+    catch {
+        // Ignore body parse errors and keep the status-only message.
+    }
+    throw new Error(`S3 request failed for ${operation}: ${message}`);
+}

package/package.json

@@ -1,14 +1,48 @@
 {
   "name": "@remix-run/file-storage-s3",
-  "version": "0.0.0",
-  "description": "Placeholder package for Remix CI/OIDC setup",
-  "license": "MIT",
+  "version": "0.1.0",
+  "description": "S3 backend for @remix-run/file-storage",
+  "author": "Michael Jackson <mjijackson@gmail.com>",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/remix-run/remix.git",
     "directory": "packages/file-storage-s3"
   },
-  "publishConfig": {
-    "access": "public"
+  "homepage": "https://github.com/remix-run/remix/tree/main/packages/file-storage-s3#readme",
+  "license": "MIT",
+  "files": [
+    "LICENSE",
+    "README.md",
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "aws4fetch": "^1.0.20",
+    "@remix-run/file-storage": "^0.13.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "@typescript/native-preview": "7.0.0-dev.20251125.1"
+  },
+  "keywords": [
+    "file",
+    "storage",
+    "s3",
+    "aws"
+  ],
+  "scripts": {
+    "build": "tsgo -p tsconfig.build.json",
+    "clean": "git clean -fdX",
+    "test": "node --disable-warning=ExperimentalWarning --test",
+    "typecheck": "tsgo --noEmit"
   }
-}
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { type S3FileStorageOptions, createS3FileStorage } from './lib/s3.ts'

package/src/lib/s3.ts

@@ -0,0 +1,411 @@
+import { AwsClient } from 'aws4fetch'
+
+import type { FileMetadata, FileStorage, ListOptions, ListResult } from '@remix-run/file-storage'
+
+const CONTENTS_PATTERN = /<Contents>([\s\S]*?)<\/Contents>/g
+
+type ListedObject = {
+  key: string
+  lastModified: number
+  size: number
+}
+
+export interface S3FileStorageOptions {
+  /**
+   * AWS access key ID used to sign S3 requests.
+   */
+  accessKeyId: string
+  /**
+   * AWS secret access key used to sign S3 requests.
+   */
+  secretAccessKey: string
+  /**
+   * Bucket name used for all file storage operations.
+   */
+  bucket: string
+  /**
+   * AWS region for request signing.
+   */
+  region: string
+  /**
+   * Custom S3-compatible endpoint URL. Defaults to AWS S3 for the given region.
+   */
+  endpoint?: string
+  /**
+   * Whether to use path-style bucket URLs (`/bucket/key`). Defaults to `true` when `endpoint` is
+   * provided and `false` otherwise.
+   */
+  forcePathStyle?: boolean
+  /**
+   * Optional session token for temporary credentials.
+   */
+  sessionToken?: string
+  /**
+   * Optional fetch implementation.
+   */
+  fetch?: typeof globalThis.fetch
+}
+
+/**
+ * Creates an S3-backed implementation of `FileStorage`.
+ *
+ * This works with AWS S3 and S3-compatible providers (for example MinIO or LocalStack) by
+ * overriding the `endpoint` option.
+ *
+ * @param options Configuration for the S3 backend
+ * @returns A `FileStorage` implementation backed by S3
+ */
+export function createS3FileStorage(options: S3FileStorageOptions): FileStorage {
+  let endpoint = new URL(options.endpoint ?? `https://s3.${options.region}.amazonaws.com`)
+  let forcePathStyle = options.forcePathStyle ?? options.endpoint != null
+
+  let aws = new AwsClient({
+    accessKeyId: options.accessKeyId,
+    secretAccessKey: options.secretAccessKey,
+    sessionToken: options.sessionToken,
+    service: 's3',
+    region: options.region,
+  })
+
+  async function s3Fetch(url: URL, init?: RequestInit): Promise<Response> {
+    let request = await aws.sign(url, init)
+
+    if (options.fetch != null) {
+      return options.fetch(request)
+    }
+
+    return fetch(request)
+  }
+
+  function getBucketUrl(): URL {
+    return createBucketUrl(endpoint, options.bucket, forcePathStyle)
+  }
+
+  function getObjectUrl(key: string): URL {
+    return createObjectUrl(endpoint, options.bucket, forcePathStyle, key)
+  }
+
+  async function putFile(key: string, file: File): Promise<File> {
+    let body = await file.arrayBuffer()
+    let headers = new Headers()
+
+    if (file.type !== '') {
+      headers.set('content-type', file.type)
+    }
+
+    headers.set('x-amz-meta-file-name', encodeMetadataValue(file.name))
+    headers.set('x-amz-meta-file-last-modified', String(file.lastModified))
+
+    let response = await s3Fetch(getObjectUrl(key), {
+      method: 'PUT',
+      headers,
+      body,
+    })
+    await assertOk(response, `PUT "${key}"`)
+
+    return new File([body], file.name, {
+      lastModified: file.lastModified,
+      type: file.type,
+    })
+  }
+
+  async function getFileMetadata(object: ListedObject): Promise<FileMetadata> {
+    let response = await s3Fetch(getObjectUrl(object.key), { method: 'HEAD' })
+
+    if (response.status === 404) {
+      return {
+        key: object.key,
+        lastModified: object.lastModified,
+        name: getDefaultFileName(object.key),
+        size: object.size,
+        type: '',
+      }
+    }
+
+    await assertOk(response, `HEAD "${object.key}"`)
+
+    return {
+      key: object.key,
+      lastModified:
+        parseEpochMillis(response.headers.get('x-amz-meta-file-last-modified')) ??
+        object.lastModified,
+      name:
+        decodeMetadataValue(response.headers.get('x-amz-meta-file-name')) ??
+        getDefaultFileName(object.key),
+      size: parseInteger(response.headers.get('content-length')) ?? object.size,
+      type: response.headers.get('content-type') ?? '',
+    }
+  }
+
+  return {
+    async get(key: string): Promise<File | null> {
+      let response = await s3Fetch(getObjectUrl(key), { method: 'GET' })
+
+      if (response.status === 404) {
+        return null
+      }
+
+      await assertOk(response, `GET "${key}"`)
+
+      let body = await response.arrayBuffer()
+
+      return new File(
+        [body],
+        decodeMetadataValue(response.headers.get('x-amz-meta-file-name')) ??
+          getDefaultFileName(key),
+        {
+          lastModified:
+            parseEpochMillis(response.headers.get('x-amz-meta-file-last-modified')) ??
+            parseHttpDate(response.headers.get('last-modified')) ??
+            0,
+          type: response.headers.get('content-type') ?? '',
+        },
+      )
+    },
+    async has(key: string): Promise<boolean> {
+      let response = await s3Fetch(getObjectUrl(key), { method: 'HEAD' })
+
+      if (response.status === 404) {
+        return false
+      }
+
+      await assertOk(response, `HEAD "${key}"`)
+
+      return true
+    },
+    async list<opts extends ListOptions>(options?: opts): Promise<ListResult<opts>> {
+      let { cursor, includeMetadata = false, limit = 32, prefix } = options ?? {}
+
+      if (limit <= 0) {
+        return {
+          files: [] as ListResult<opts>['files'],
+        }
+      }
+
+      let url = getBucketUrl()
+      url.searchParams.set('encoding-type', 'url')
+      url.searchParams.set('list-type', '2')
+      url.searchParams.set('max-keys', String(limit))
+
+      if (cursor !== undefined) {
+        url.searchParams.set('continuation-token', cursor)
+      }
+      if (prefix !== undefined) {
+        url.searchParams.set('prefix', prefix)
+      }
+
+      let response = await s3Fetch(url, { method: 'GET' })
+      await assertOk(response, 'LIST')
+
+      let xml = await response.text()
+      let objects = parseListedObjects(xml)
+      let nextCursor = parseNextCursor(xml)
+
+      if (!includeMetadata) {
+        return {
+          cursor: nextCursor,
+          files: objects.map((object) => ({ key: object.key })) as ListResult<opts>['files'],
+        }
+      }
+
+      let files = await Promise.all(objects.map((object) => getFileMetadata(object)))
+
+      return {
+        cursor: nextCursor,
+        files: files as ListResult<opts>['files'],
+      }
+    },
+    put(key: string, file: File): Promise<File> {
+      return putFile(key, file)
+    },
+    async remove(key: string): Promise<void> {
+      let response = await s3Fetch(getObjectUrl(key), { method: 'DELETE' })
+
+      if (response.status === 404) {
+        return
+      }
+
+      await assertOk(response, `DELETE "${key}"`)
+    },
+    async set(key: string, file: File): Promise<void> {
+      await putFile(key, file)
+    },
+  }
+}
+
+function createBucketUrl(endpoint: URL, bucket: string, forcePathStyle: boolean): URL {
+  let url = new URL(endpoint.toString())
+
+  if (forcePathStyle) {
+    url.pathname = joinPath(endpoint.pathname, encodeURIComponent(bucket))
+  } else {
+    url.hostname = `${bucket}.${endpoint.hostname}`
+    url.pathname = joinPath(endpoint.pathname)
+  }
+
+  return url
+}
+
+function createObjectUrl(endpoint: URL, bucket: string, forcePathStyle: boolean, key: string): URL {
+  let url = new URL(endpoint.toString())
+
+  if (forcePathStyle) {
+    url.pathname = joinPath(endpoint.pathname, encodeURIComponent(bucket), encodeS3Key(key))
+  } else {
+    url.hostname = `${bucket}.${endpoint.hostname}`
+    url.pathname = joinPath(endpoint.pathname, encodeS3Key(key))
+  }
+
+  return url
+}
+
+function encodeS3Key(key: string): string {
+  return key
+    .split('/')
+    .map((segment) => encodeURIComponent(segment))
+    .join('/')
+}
+
+function encodeMetadataValue(value: string): string {
+  return encodeURIComponent(value)
+}
+
+function decodeMetadataValue(value: string | null): string | undefined {
+  if (value == null || value === '') {
+    return undefined
+  }
+
+  try {
+    return decodeURIComponent(value)
+  } catch {
+    return value
+  }
+}
+
+function getDefaultFileName(key: string): string {
+  let lastSlashIndex = key.lastIndexOf('/')
+  let fileName = lastSlashIndex >= 0 ? key.slice(lastSlashIndex + 1) : key
+  return fileName === '' ? key : fileName
+}
+
+function parseListedObjects(xml: string): ListedObject[] {
+  CONTENTS_PATTERN.lastIndex = 0
+
+  let objects: ListedObject[] = []
+
+  for (let match of xml.matchAll(CONTENTS_PATTERN)) {
+    let entry = match[1] ?? ''
+    let encodedKey = readXmlTag(entry, 'Key')
+
+    if (encodedKey == null) {
+      continue
+    }
+
+    let key = decodeS3Key(encodedKey)
+    let size = parseInteger(readXmlTag(entry, 'Size')) ?? 0
+    let lastModified = parseHttpDate(readXmlTag(entry, 'LastModified')) ?? 0
+
+    objects.push({
+      key,
+      lastModified,
+      size,
+    })
+  }
+
+  return objects
+}
+
+function parseNextCursor(xml: string): string | undefined {
+  if (readXmlTag(xml, 'IsTruncated') !== 'true') {
+    return undefined
+  }
+
+  return readXmlTag(xml, 'NextContinuationToken')
+}
+
+function decodeS3Key(value: string): string {
+  try {
+    return decodeURIComponent(value)
+  } catch {
+    return value
+  }
+}
+
+function readXmlTag(xml: string, tagName: string): string | undefined {
+  let pattern = new RegExp(`<${tagName}>([\\s\\S]*?)</${tagName}>`)
+  let match = xml.match(pattern)
+
+  if (match == null || match[1] == null) {
+    return undefined
+  }
+
+  return decodeXmlEntities(match[1])
+}
+
+function decodeXmlEntities(value: string): string {
+  return value
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&apos;/g, "'")
+}
+
+function parseInteger(value: string | null | undefined): number | undefined {
+  if (value == null || value === '') {
+    return undefined
+  }
+
+  let parsed = Number(value)
+  return Number.isFinite(parsed) ? parsed : undefined
+}
+
+function parseEpochMillis(value: string | null): number | undefined {
+  let parsed = parseInteger(value)
+  return parsed != null ? parsed : undefined
+}
+
+function parseHttpDate(value: string | null | undefined): number | undefined {
+  if (value == null || value === '') {
+    return undefined
+  }
+
+  let parsed = Date.parse(value)
+  return Number.isFinite(parsed) ? parsed : undefined
+}
+
+function joinPath(basePath: string, ...parts: (string | undefined)[]): string {
+  let normalizedBasePath = basePath.replace(/\/+$/g, '')
+  let normalizedParts = parts
+    .filter((part): part is string => part != null && part !== '')
+    .map((part) => part.replace(/^\/+|\/+$/g, ''))
+
+  let joined = [normalizedBasePath, ...normalizedParts].filter((part) => part !== '').join('/')
+  if (joined === '') {
+    return '/'
+  }
+
+  return joined.startsWith('/') ? joined : `/${joined}`
+}
+
+async function assertOk(response: Response, operation: string): Promise<void> {
+  if (response.ok) {
+    return
+  }
+
+  let message = `${response.status} ${response.statusText}`
+
+  try {
+    let body = await response.text()
+    let s3Message = readXmlTag(body, 'Message')
+
+    if (s3Message != null && s3Message !== '') {
+      message = `${message} (${s3Message})`
+    }
+  } catch {
+    // Ignore body parse errors and keep the status-only message.
+  }
+
+  throw new Error(`S3 request failed for ${operation}: ${message}`)
+}