@contract-kit/provider-storage-s3 1.0.0

package/src/index.ts

@@ -0,0 +1,906 @@
+import { Readable } from "node:stream";
+import {
+  DeleteObjectCommand,
+  GetObjectCommand,
+  HeadObjectCommand,
+  PutObjectCommand,
+  S3Client,
+  type S3ClientConfig,
+} from "@aws-sdk/client-s3";
+import { createProviderDevtools } from "@contract-kit/devtools";
+import {
+  createProvider,
+  type StorageBody,
+  type StorageMetadata,
+  type StorageObject,
+  type StorageObjectBody,
+  type StoragePort,
+  type StorageVisibility,
+} from "@contract-kit/ports";
+import { z } from "zod";
+
+export type {
+  StorageBody,
+  StorageMetadata,
+  StorageObject,
+  StorageObjectBody,
+  StoragePort,
+  StorageVisibility,
+} from "@contract-kit/ports";
+
+const visibilityMetadataKey = "ck-visibility";
+
+const BooleanString = z
+  .enum(["true", "false"])
+  .transform((value) => value === "true");
+
+const S3StorageConfigSchema = z.object({
+  BUCKET: z.string().min(1),
+  REGION: z.string().min(1).default("us-east-1"),
+  ENDPOINT: z.string().url().optional(),
+  ACCESS_KEY_ID: z.string().min(1).optional(),
+  SECRET_ACCESS_KEY: z.string().min(1).optional(),
+  SESSION_TOKEN: z.string().min(1).optional(),
+  PUBLIC_BASE_URL: z.string().min(1).optional(),
+  FORCE_PATH_STYLE: BooleanString.optional(),
+  KEY_PREFIX: z.string().optional(),
+});
+
+export type S3StorageConfig = z.infer<typeof S3StorageConfigSchema>;
+
+export type S3StorageClient = Pick<S3Client, "send">;
+
+export interface S3StorageOptions {
+  /**
+   * S3 bucket name.
+   */
+  bucket: string;
+
+  /**
+   * S3-compatible client. Omit to create an AWS SDK S3Client from config.
+   */
+  client?: S3StorageClient;
+
+  /**
+   * Region used when creating the default S3Client.
+   *
+   * @default "us-east-1"
+   */
+  region?: string;
+
+  /**
+   * S3-compatible endpoint. Required for R2, MinIO, Spaces, B2, and most
+   * non-AWS object stores.
+   */
+  endpoint?: string;
+
+  /**
+   * Static credentials used when creating the default S3Client.
+   */
+  credentials?: {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+  };
+
+  /**
+   * Use path-style bucket addressing when required by the object store.
+   */
+  forcePathStyle?: boolean;
+
+  /**
+   * Prefix all object keys before sending them to S3.
+   */
+  keyPrefix?: string;
+
+  /**
+   * Base URL used by `publicUrl(...)` for public objects.
+   */
+  publicBaseUrl?: string;
+
+  /**
+   * Additional AWS SDK S3Client config.
+   */
+  clientConfig?: Omit<
+    S3ClientConfig,
+    "region" | "endpoint" | "credentials" | "forcePathStyle"
+  >;
+
+  /**
+   * Optional devtools target. The provider passes existing app ports here
+   * automatically; direct factory users can pass a devtools port explicitly.
+   */
+  devtools?: unknown;
+}
+
+export interface S3StorageProviderOptions
+  extends Omit<S3StorageOptions, "bucket" | "client" | "devtools"> {
+  /**
+   * Provider name. Defaults to "storage-s3".
+   */
+  name?: string;
+
+  /**
+   * Default bucket used when STORAGE_S3_BUCKET is not set.
+   */
+  bucket?: string;
+
+  /**
+   * Optional client factory for tests or custom S3 clients.
+   */
+  createClient?: (config: S3StorageConfig) => S3StorageClient;
+}
+
+type StorageEvent = {
+  operation: string;
+  key: string;
+  summary: string;
+  details?: Record<string, unknown>;
+};
+
+type NodeWebReadableStream = Parameters<typeof Readable.fromWeb>[0];
+
+type TransformableBody = {
+  transformToByteArray?: () => Promise<Uint8Array>;
+  transformToString?: () => Promise<string>;
+  transformToWebStream?: () => ReadableStream<Uint8Array>;
+};
+
+type BodyWithAsyncIterator = AsyncIterable<Uint8Array>;
+
+function copyBytes(bytes: Uint8Array): Uint8Array {
+  return new Uint8Array(bytes);
+}
+
+function bytesToArrayBuffer(bytes: Uint8Array): ArrayBuffer {
+  const buffer = new ArrayBuffer(bytes.byteLength);
+  new Uint8Array(buffer).set(bytes);
+  return buffer;
+}
+
+function bytesToStream(bytes: Uint8Array): ReadableStream<Uint8Array> {
+  const copy = copyBytes(bytes);
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(copy);
+      controller.close();
+    },
+  });
+}
+
+function hasControlCharacter(value: string): boolean {
+  for (const char of value) {
+    const code = char.charCodeAt(0);
+    if (code <= 31 || code === 127) return true;
+  }
+
+  return false;
+}
+
+function validateStorageKey(key: string): void {
+  if (key.length === 0) {
+    throw new Error("Storage key must not be empty.");
+  }
+
+  if (hasControlCharacter(key)) {
+    throw new Error("Storage key must not include control characters.");
+  }
+
+  if (key.startsWith("/")) {
+    throw new Error("Storage key must not start with '/'.");
+  }
+
+  if (key.endsWith("/")) {
+    throw new Error("Storage key must not end with '/'.");
+  }
+
+  if (key.includes("\\")) {
+    throw new Error("Storage key must use '/' separators, not '\\'.");
+  }
+
+  const segments = key.split("/");
+
+  if (segments.some((segment) => segment === "")) {
+    throw new Error("Storage key must not include empty path segments.");
+  }
+
+  if (segments.some((segment) => segment === "." || segment === "..")) {
+    throw new Error("Storage key must not include '.' or '..' segments.");
+  }
+}
+
+function normalizeKeyPrefix(prefix: string | undefined): string {
+  if (!prefix) return "";
+  const normalized = prefix.replace(/^\/+|\/+$/g, "");
+  if (!normalized) return "";
+  validateStorageKey(normalized);
+  return normalized;
+}
+
+function objectKey(prefix: string, key: string): string {
+  validateStorageKey(key);
+  return prefix ? `${prefix}/${key}` : key;
+}
+
+function objectPrefix(keyPrefix: string, prefix: string): string {
+  if (prefix.length === 0) {
+    return keyPrefix ? `${keyPrefix}/` : "";
+  }
+
+  const normalized = prefix.replace(/\/+$/g, "");
+  validateStorageKey(normalized);
+  return `${objectKey(keyPrefix, normalized)}/`;
+}
+
+function joinPublicUrl(baseUrl: string, key: string): string {
+  const base = baseUrl.replace(/\/+$/, "");
+  const encodedKey = key
+    .split("/")
+    .map((part) => encodeURIComponent(part))
+    .join("/");
+
+  return `${base}/${encodedKey}`;
+}
+
+function toPutBody(body: StorageBody): string | Uint8Array | Readable {
+  if (typeof body === "string") return body;
+  if (body instanceof Uint8Array) return copyBytes(body);
+  if (body instanceof ArrayBuffer) return new Uint8Array(body.slice(0));
+  if (body instanceof Blob) {
+    return Readable.fromWeb(body.stream() as unknown as NodeWebReadableStream);
+  }
+
+  return Readable.fromWeb(body as unknown as NodeWebReadableStream);
+}
+
+async function streamToBytes(
+  stream: ReadableStream<Uint8Array>,
+): Promise<Uint8Array> {
+  const reader = stream.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+
+  try {
+    while (true) {
+      const result = await reader.read();
+      if (result.done) break;
+      chunks.push(result.value);
+      size += result.value.byteLength;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+
+  return bytes;
+}
+
+async function asyncIterableToBytes(
+  iterable: BodyWithAsyncIterator,
+): Promise<Uint8Array> {
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+
+  for await (const chunk of iterable) {
+    chunks.push(chunk);
+    size += chunk.byteLength;
+  }
+
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+
+  return bytes;
+}
+
+function isAsyncIterable(value: unknown): value is BodyWithAsyncIterator {
+  return (
+    typeof value === "object" && value !== null && Symbol.asyncIterator in value
+  );
+}
+
+function bodyToStream(body: unknown): ReadableStream<Uint8Array> {
+  if (body instanceof ReadableStream) return body;
+  if (body instanceof Uint8Array) return bytesToStream(body);
+  if (typeof body === "string") {
+    return bytesToStream(new TextEncoder().encode(body));
+  }
+  if (body instanceof Blob) {
+    return body.stream() as unknown as ReadableStream<Uint8Array>;
+  }
+
+  const transformable = body as TransformableBody | null;
+  if (typeof transformable?.transformToWebStream === "function") {
+    return transformable.transformToWebStream();
+  }
+
+  if (body instanceof Readable) {
+    return Readable.toWeb(body) as unknown as ReadableStream<Uint8Array>;
+  }
+
+  throw new Error("S3 object body is not readable.");
+}
+
+async function bodyToBytes(body: unknown): Promise<Uint8Array> {
+  if (body instanceof Uint8Array) return copyBytes(body);
+  if (typeof body === "string") return new TextEncoder().encode(body);
+  if (body instanceof Blob) return new Uint8Array(await body.arrayBuffer());
+
+  const transformable = body as TransformableBody | null;
+  if (typeof transformable?.transformToByteArray === "function") {
+    return copyBytes(await transformable.transformToByteArray());
+  }
+
+  if (typeof transformable?.transformToString === "function") {
+    return new TextEncoder().encode(await transformable.transformToString());
+  }
+
+  if (isAsyncIterable(body)) {
+    return asyncIterableToBytes(body);
+  }
+
+  return streamToBytes(bodyToStream(body));
+}
+
+function createObjectBody(
+  object: StorageObject,
+  body: unknown,
+): StorageObjectBody {
+  let bodyUsed = false;
+
+  function markConsumed(): void {
+    if (bodyUsed) {
+      throw new Error("Storage object body has already been consumed.");
+    }
+
+    bodyUsed = true;
+  }
+
+  return {
+    ...object,
+    get bodyUsed() {
+      return bodyUsed;
+    },
+    stream() {
+      markConsumed();
+      return bodyToStream(body);
+    },
+    async bytes() {
+      markConsumed();
+      return bodyToBytes(body);
+    },
+    async arrayBuffer() {
+      markConsumed();
+      return bytesToArrayBuffer(await bodyToBytes(body));
+    },
+    async text() {
+      markConsumed();
+      if (typeof body === "string") return body;
+
+      const transformable = body as TransformableBody | null;
+      if (typeof transformable?.transformToString === "function") {
+        return transformable.transformToString();
+      }
+
+      return new TextDecoder().decode(await bodyToBytes(body));
+    },
+  };
+}
+
+function metadataWithoutReserved(
+  metadata: Record<string, string> | undefined,
+): StorageMetadata {
+  const result: StorageMetadata = {};
+
+  for (const [key, value] of Object.entries(metadata ?? {})) {
+    if (key.toLowerCase() !== visibilityMetadataKey) {
+      result[key] = value;
+    }
+  }
+
+  return result;
+}
+
+function visibilityFromMetadata(
+  metadata: Record<string, string> | undefined,
+): StorageVisibility {
+  const visibility = metadata?.[visibilityMetadataKey];
+  return visibility === "public" ? "public" : "private";
+}
+
+function metadataForPut(
+  metadata: StorageMetadata | undefined,
+  visibility: StorageVisibility,
+): StorageMetadata {
+  return {
+    ...(metadata ?? {}),
+    [visibilityMetadataKey]: visibility,
+  };
+}
+
+function objectFromHead(
+  key: string,
+  output: {
+    ContentLength?: number;
+    ContentType?: string;
+    CacheControl?: string;
+    Metadata?: Record<string, string>;
+    LastModified?: Date;
+  },
+): StorageObject {
+  return {
+    key,
+    size: output.ContentLength ?? 0,
+    ...(output.ContentType !== undefined
+      ? { contentType: output.ContentType }
+      : {}),
+    ...(output.CacheControl !== undefined
+      ? { cacheControl: output.CacheControl }
+      : {}),
+    metadata: metadataWithoutReserved(output.Metadata),
+    visibility: visibilityFromMetadata(output.Metadata),
+    lastModified: output.LastModified ?? new Date(),
+  };
+}
+
+function isNotFoundError(error: unknown): boolean {
+  if (typeof error !== "object" || error === null) return false;
+  const candidate = error as {
+    name?: string;
+    Code?: string;
+    code?: string;
+    $metadata?: { httpStatusCode?: number };
+  };
+
+  return (
+    candidate.name === "NoSuchKey" ||
+    candidate.name === "NotFound" ||
+    candidate.Code === "NoSuchKey" ||
+    candidate.code === "NoSuchKey" ||
+    candidate.$metadata?.httpStatusCode === 404
+  );
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function createDefaultClient(options: S3StorageOptions): S3StorageClient {
+  return new S3Client({
+    ...options.clientConfig,
+    region: options.region ?? "us-east-1",
+    ...(options.endpoint !== undefined ? { endpoint: options.endpoint } : {}),
+    ...(options.credentials !== undefined
+      ? { credentials: options.credentials }
+      : {}),
+    ...(options.forcePathStyle !== undefined
+      ? { forcePathStyle: options.forcePathStyle }
+      : {}),
+  });
+}
+
+export function createS3Storage(options: S3StorageOptions): StoragePort {
+  const client = options.client ?? createDefaultClient(options);
+  const keyPrefix = normalizeKeyPrefix(options.keyPrefix);
+  const devtools = createProviderDevtools(options.devtools, {
+    providerName: "storage-s3",
+    watcher: "storage",
+  });
+
+  const recordStorageEvent = (event: StorageEvent) => {
+    devtools.custom({
+      name: `storage.${event.operation}`,
+      label: `Storage ${event.operation}`,
+      summary: event.summary,
+      details: {
+        provider: "s3",
+        operation: event.operation,
+        key: event.key,
+        bucket: options.bucket,
+        ...event.details,
+      },
+    });
+  };
+
+  async function statObject(key: string): Promise<StorageObject | null> {
+    const s3Key = objectKey(keyPrefix, key);
+
+    try {
+      const output = (await client.send(
+        new HeadObjectCommand({
+          Bucket: options.bucket,
+          Key: s3Key,
+        }),
+      )) as Parameters<typeof objectFromHead>[1];
+
+      return objectFromHead(key, output);
+    } catch (error) {
+      if (isNotFoundError(error)) return null;
+      throw error;
+    }
+  }
+
+  return {
+    async put(key, body, putOptions) {
+      const startedAt = Date.now();
+
+      try {
+        const s3Key = objectKey(keyPrefix, key);
+        const visibility = putOptions?.visibility ?? "private";
+
+        await client.send(
+          new PutObjectCommand({
+            Bucket: options.bucket,
+            Key: s3Key,
+            Body: toPutBody(body),
+            ...(putOptions?.contentType !== undefined
+              ? { ContentType: putOptions.contentType }
+              : {}),
+            ...(putOptions?.cacheControl !== undefined
+              ? { CacheControl: putOptions.cacheControl }
+              : {}),
+            Metadata: metadataForPut(putOptions?.metadata, visibility),
+          }),
+        );
+
+        const object =
+          (await statObject(key)) ??
+          ({
+            key,
+            size: 0,
+            ...(putOptions?.contentType !== undefined
+              ? { contentType: putOptions.contentType }
+              : {}),
+            ...(putOptions?.cacheControl !== undefined
+              ? { cacheControl: putOptions.cacheControl }
+              : {}),
+            metadata: { ...(putOptions?.metadata ?? {}) },
+            visibility,
+            lastModified: new Date(),
+          } satisfies StorageObject);
+
+        recordStorageEvent({
+          operation: "put",
+          key,
+          summary: "Storage object written",
+          details: {
+            s3Key,
+            size: object.size,
+            visibility: object.visibility,
+            contentType: object.contentType ?? null,
+            metadataKeys: Object.keys(object.metadata),
+            durationMs: Date.now() - startedAt,
+          },
+        });
+
+        return object;
+      } catch (error) {
+        recordStorageEvent({
+          operation: "put.failed",
+          key,
+          summary: "Storage put failed",
+          details: {
+            durationMs: Date.now() - startedAt,
+            error: errorMessage(error),
+          },
+        });
+        throw error;
+      }
+    },
+
+    async get(key) {
+      const startedAt = Date.now();
+
+      try {
+        const s3Key = objectKey(keyPrefix, key);
+        const output = (await client.send(
+          new GetObjectCommand({
+            Bucket: options.bucket,
+            Key: s3Key,
+          }),
+        )) as Parameters<typeof objectFromHead>[1] & { Body?: unknown };
+
+        if (output.Body === undefined) return null;
+        const object = objectFromHead(key, output);
+
+        recordStorageEvent({
+          operation: "get",
+          key,
+          summary: "Storage object read",
+          details: {
+            s3Key,
+            hit: true,
+            size: object.size,
+            durationMs: Date.now() - startedAt,
+          },
+        });
+
+        return createObjectBody(object, output.Body);
+      } catch (error) {
+        if (isNotFoundError(error)) {
+          recordStorageEvent({
+            operation: "get",
+            key,
+            summary: "Storage object missing",
+            details: {
+              hit: false,
+              durationMs: Date.now() - startedAt,
+            },
+          });
+          return null;
+        }
+
+        recordStorageEvent({
+          operation: "get.failed",
+          key,
+          summary: "Storage get failed",
+          details: {
+            durationMs: Date.now() - startedAt,
+            error: errorMessage(error),
+          },
+        });
+        throw error;
+      }
+    },
+
+    async stat(key) {
+      const startedAt = Date.now();
+
+      try {
+        const object = await statObject(key);
+        recordStorageEvent({
+          operation: "stat",
+          key,
+          summary: object ? "Storage object found" : "Storage object missing",
+          details: {
+            hit: object !== null,
+            size: object?.size ?? null,
+            durationMs: Date.now() - startedAt,
+          },
+        });
+        return object;
+      } catch (error) {
+        recordStorageEvent({
+          operation: "stat.failed",
+          key,
+          summary: "Storage stat failed",
+          details: {
+            durationMs: Date.now() - startedAt,
+            error: errorMessage(error),
+          },
+        });
+        throw error;
+      }
+    },
+
+    async delete(key) {
+      const startedAt = Date.now();
+
+      try {
+        const s3Key = objectKey(keyPrefix, key);
+        const existed = (await statObject(key)) !== null;
+
+        await client.send(
+          new DeleteObjectCommand({
+            Bucket: options.bucket,
+            Key: s3Key,
+          }),
+        );
+
+        recordStorageEvent({
+          operation: "delete",
+          key,
+          summary: existed
+            ? "Storage object deleted"
+            : "Storage object missing",
+          details: {
+            s3Key,
+            deleted: existed,
+            durationMs: Date.now() - startedAt,
+          },
+        });
+
+        return existed;
+      } catch (error) {
+        recordStorageEvent({
+          operation: "delete.failed",
+          key,
+          summary: "Storage delete failed",
+          details: {
+            durationMs: Date.now() - startedAt,
+            error: errorMessage(error),
+          },
+        });
+        throw error;
+      }
+    },
+
+    async exists(key) {
+      const startedAt = Date.now();
+
+      try {
+        const exists = (await statObject(key)) !== null;
+        recordStorageEvent({
+          operation: "exists",
+          key,
+          summary: exists ? "Storage object exists" : "Storage object missing",
+          details: {
+            exists,
+            durationMs: Date.now() - startedAt,
+          },
+        });
+        return exists;
+      } catch (error) {
+        recordStorageEvent({
+          operation: "exists.failed",
+          key,
+          summary: "Storage exists failed",
+          details: {
+            durationMs: Date.now() - startedAt,
+            error: errorMessage(error),
+          },
+        });
+        throw error;
+      }
+    },
+
+    async publicUrl(key) {
+      const startedAt = Date.now();
+
+      try {
+        const s3Key = objectKey(keyPrefix, key);
+        const object = await statObject(key);
+        const url =
+          object?.visibility === "public" && options.publicBaseUrl
+            ? joinPublicUrl(options.publicBaseUrl, s3Key)
+            : null;
+
+        recordStorageEvent({
+          operation: "publicUrl",
+          key,
+          summary: url ? "Storage public URL resolved" : "No public URL",
+          details: {
+            s3Key,
+            hit: object !== null,
+            visibility: object?.visibility ?? null,
+            hasPublicUrl: url !== null,
+            durationMs: Date.now() - startedAt,
+          },
+        });
+
+        return url;
+      } catch (error) {
+        recordStorageEvent({
+          operation: "publicUrl.failed",
+          key,
+          summary: "Storage public URL failed",
+          details: {
+            durationMs: Date.now() - startedAt,
+            error: errorMessage(error),
+          },
+        });
+        throw error;
+      }
+    },
+  };
+}
+
+export interface S3StorageProviderPorts {
+  storage: StoragePort;
+  s3Storage: {
+    client: S3StorageClient;
+    bucket: string;
+    keyPrefix: string;
+    objectKey(key: string): string;
+    objectPrefix(prefix: string): string;
+  };
+}
+
+export function createS3StorageProvider(
+  options: S3StorageProviderOptions = {},
+) {
+  const ConfigSchema = S3StorageConfigSchema.extend({
+    BUCKET:
+      options.bucket !== undefined
+        ? z.string().min(1).default(options.bucket)
+        : S3StorageConfigSchema.shape.BUCKET,
+    REGION: z
+      .string()
+      .min(1)
+      .default(options.region ?? "us-east-1"),
+    ENDPOINT:
+      options.endpoint !== undefined
+        ? z.string().url().default(options.endpoint)
+        : S3StorageConfigSchema.shape.ENDPOINT,
+    PUBLIC_BASE_URL:
+      options.publicBaseUrl !== undefined
+        ? z.string().min(1).default(options.publicBaseUrl)
+        : S3StorageConfigSchema.shape.PUBLIC_BASE_URL,
+    FORCE_PATH_STYLE:
+      options.forcePathStyle !== undefined
+        ? BooleanString.default(options.forcePathStyle)
+        : S3StorageConfigSchema.shape.FORCE_PATH_STYLE,
+    KEY_PREFIX:
+      options.keyPrefix !== undefined
+        ? z.string().default(options.keyPrefix)
+        : S3StorageConfigSchema.shape.KEY_PREFIX,
+  });
+
+  return createProvider({
+    name: options.name ?? "storage-s3",
+
+    config: {
+      schema: ConfigSchema,
+      envPrefix: "STORAGE_S3_",
+    },
+
+    async setup({ ports, config }) {
+      if (!config?.BUCKET) {
+        throw new Error(
+          "[s3StorageProvider] Missing S3 storage config. " +
+            "Please set STORAGE_S3_BUCKET.",
+        );
+      }
+
+      const keyPrefix = normalizeKeyPrefix(
+        config.KEY_PREFIX ?? options.keyPrefix,
+      );
+      const client =
+        options.createClient?.(config) ??
+        createDefaultClient({
+          ...options,
+          bucket: config.BUCKET,
+          region: config.REGION ?? options.region,
+          endpoint: config.ENDPOINT ?? options.endpoint,
+          publicBaseUrl: config.PUBLIC_BASE_URL ?? options.publicBaseUrl,
+          forcePathStyle: config.FORCE_PATH_STYLE ?? options.forcePathStyle,
+          keyPrefix,
+          credentials:
+            config.ACCESS_KEY_ID && config.SECRET_ACCESS_KEY
+              ? {
+                  accessKeyId: config.ACCESS_KEY_ID,
+                  secretAccessKey: config.SECRET_ACCESS_KEY,
+                  ...(config.SESSION_TOKEN !== undefined
+                    ? { sessionToken: config.SESSION_TOKEN }
+                    : {}),
+                }
+              : options.credentials,
+        });
+
+      return {
+        ports: {
+          storage: createS3Storage({
+            ...options,
+            bucket: config.BUCKET,
+            client,
+            publicBaseUrl: config.PUBLIC_BASE_URL ?? options.publicBaseUrl,
+            keyPrefix,
+            devtools: ports,
+          }),
+          s3Storage: {
+            client,
+            bucket: config.BUCKET,
+            keyPrefix,
+            objectKey(key) {
+              return objectKey(keyPrefix, key);
+            },
+            objectPrefix(prefix) {
+              return objectPrefix(keyPrefix, prefix);
+            },
+          },
+        } satisfies S3StorageProviderPorts,
+      };
+    },
+  });
+}
+
+export const s3StorageProvider = createS3StorageProvider();