@cosmicdrift/kumiko-bundled-features 0.1.0

package/src/file-provider-s3/feature.ts

@@ -0,0 +1,169 @@
+// kumiko-feature-version: 1
+//
+// file-provider-s3 — concrete S3-implementation for the
+// file-foundation plugin-API.
+//
+// **Was diese Feature liefert:**
+//   1. Provider-spezifische Tenant-Config (bucket/region/endpoint/
+//      forcePathStyle/accessKeyId) und Secret (s3.secretAccessKey).
+//      Self-contained — file-foundation kennt diese nicht.
+//   2. Plugin-Registration via `r.useExtension("fileProvider", "s3",
+//      { build })`. file-foundation's Factory findet den Plugin via
+//      registry.
+//   3. build(ctx, tenantId) liest config + secret, ruft `createS3Provider`
+//      aus files-provider-s3 auf. Der EINZIGE Cross-Feature-Import
+//      des Plugins — bewusst lokal gehalten.
+//
+// **Pattern-Vorbild:** mirrors mail-transport-smtp.
+//
+// **Boot-Dependencies:** config + secrets + file-foundation.
+
+import type { FileProviderPlugin } from "@cosmicdrift/kumiko-bundled-features/file-foundation";
+import { createS3Provider } from "@cosmicdrift/kumiko-bundled-features/files-provider-s3";
+import {
+  requireDefined,
+  requireNonEmpty,
+} from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
+import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import {
+  access,
+  createTenantConfig,
+  defineFeature,
+  type HandlerContext,
+} from "@cosmicdrift/kumiko-framework/engine";
+import type { FileStorageProvider } from "@cosmicdrift/kumiko-framework/files";
+
+const FEATURE_NAME = "file-provider-s3";
+
+// =============================================================================
+// Feature-definition
+// =============================================================================
+
+export const fileProviderS3Feature = defineFeature(FEATURE_NAME, (r) => {
+  r.requires("config");
+  r.requires("secrets");
+  r.requires("file-foundation");
+
+  const secretAccessKey = r.secret("s3.secretAccessKey", {
+    label: { de: "S3 Secret Access Key", en: "S3 Secret Access Key" },
+    hint: {
+      de: "Privater Teil des S3-Schlüsselpaares. Bei Hetzner Object Storage 'Secret Key', bei AWS S3 'Secret Access Key'.",
+      en: "Private half of the S3 key pair. Hetzner calls it 'Secret Key', AWS calls it 'Secret Access Key'.",
+    },
+    redact: (plaintext) => {
+      if (plaintext.length < 8) return "•".repeat(plaintext.length);
+      return `${plaintext.slice(0, 4)}...${plaintext.slice(-4)}`;
+    },
+    scope: "tenant",
+  });
+
+  const configKeys = r.config({
+    keys: {
+      bucket: createTenantConfig("text", {
+        default: "",
+        write: access.roles("TenantAdmin", "SystemAdmin"),
+        read: access.roles("TenantAdmin", "SystemAdmin"),
+      }),
+      region: createTenantConfig("text", {
+        default: "",
+        write: access.roles("TenantAdmin", "SystemAdmin"),
+        read: access.roles("TenantAdmin", "SystemAdmin"),
+      }),
+      endpoint: createTenantConfig("text", {
+        default: "",
+        write: access.roles("TenantAdmin", "SystemAdmin"),
+        read: access.roles("TenantAdmin", "SystemAdmin"),
+      }),
+      forcePathStyle: createTenantConfig("boolean", {
+        default: false,
+        write: access.roles("TenantAdmin", "SystemAdmin"),
+      }),
+      accessKeyId: createTenantConfig("text", {
+        default: "",
+        write: access.roles("TenantAdmin", "SystemAdmin"),
+        read: access.roles("TenantAdmin", "SystemAdmin"),
+      }),
+    },
+  });
+
+  // Plugin-Registration. entityName "s3" ist was tenants in
+  // file-foundation's `provider` config-key setzen.
+  const plugin: FileProviderPlugin = {
+    build: async (ctx: HandlerContext, tenantId: string) => buildS3Provider(ctx, tenantId),
+  };
+  r.useExtension("fileProvider", "s3", plugin);
+
+  return { configKeys, secretAccessKey };
+});
+
+/** Typed handle for the S3 secret-access-key. */
+export const S3_SECRET_ACCESS_KEY = fileProviderS3Feature.exports.secretAccessKey;
+
+// =============================================================================
+// Internal: build the FileStorageProvider from tenant config + secret
+// =============================================================================
+
+async function buildS3Provider(
+  ctx: HandlerContext,
+  tenantId: string,
+): Promise<FileStorageProvider> {
+  const ctxConfig = ctx.config;
+  if (!ctxConfig) {
+    throw new Error(
+      `${FEATURE_NAME}: ctx.config is missing — feature requires the config-feature mounted in the registry`,
+    );
+  }
+
+  const FILE_HINT = "Set via tenant-admin UI or seed-handler before reading or writing files.";
+  const bucket = requireNonEmpty(
+    await ctxConfig(fileProviderS3Feature.exports.configKeys.bucket),
+    FEATURE_NAME,
+    "bucket",
+    FILE_HINT,
+  );
+  const region = requireNonEmpty(
+    await ctxConfig(fileProviderS3Feature.exports.configKeys.region),
+    FEATURE_NAME,
+    "region",
+    FILE_HINT,
+  );
+  const endpointRaw = requireDefined(
+    await ctxConfig(fileProviderS3Feature.exports.configKeys.endpoint),
+    FEATURE_NAME,
+    "endpoint",
+  ) as string;
+  const endpoint = endpointRaw.length > 0 ? endpointRaw : undefined;
+  const forcePathStyle = requireDefined(
+    await ctxConfig(fileProviderS3Feature.exports.configKeys.forcePathStyle),
+    FEATURE_NAME,
+    "forcePathStyle",
+  ) as boolean;
+  const accessKeyId = requireNonEmpty(
+    await ctxConfig(fileProviderS3Feature.exports.configKeys.accessKeyId),
+    FEATURE_NAME,
+    "accessKeyId",
+    FILE_HINT,
+  );
+
+  const secretAccessKey = await readSecretAccessKey(ctx, tenantId);
+
+  return createS3Provider({
+    bucket,
+    region,
+    accessKeyId,
+    secretAccessKey,
+    ...(endpoint !== undefined && { endpoint }),
+    forcePathStyle,
+  });
+}
+
+async function readSecretAccessKey(ctx: HandlerContext, tenantId: string): Promise<string> {
+  const secrets = requireSecretsContext(ctx, FEATURE_NAME);
+  const branded = await secrets.get(tenantId, S3_SECRET_ACCESS_KEY);
+  if (!branded) {
+    throw new Error(
+      `${FEATURE_NAME}: ${S3_SECRET_ACCESS_KEY.name} not set for tenant ${tenantId} — Tenant-Admin must set it via /api/write/secrets:write:set`,
+    );
+  }
+  return branded.reveal();
+}

package/src/file-provider-s3/index.ts

@@ -0,0 +1,3 @@
+// Public API of the file-provider-s3 bundled-feature.
+
+export { fileProviderS3Feature, S3_SECRET_ACCESS_KEY } from "./feature";

package/src/files-provider-s3/__tests__/env-helper.test.ts

@@ -0,0 +1,161 @@
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { parseS3EnvConfig } from "../env-helper";
+
+// Tests run against real process.env — we snapshot + restore per-test so
+// parallel test files don't leak env vars into one another. vi.stubEnv is
+// intentionally avoided: it only affects Vite-transformed reads, and
+// env-helper reads process.env directly at runtime.
+
+const TOUCHED_KEYS = [
+  "TEST_S3_BUCKET",
+  "TEST_S3_REGION",
+  "TEST_S3_ACCESS_KEY",
+  "TEST_S3_SECRET_KEY",
+  "TEST_S3_ENDPOINT",
+  "TEST_S3_FORCE_PATH_STYLE",
+  "OTHER_BUCKET",
+  "OTHER_REGION",
+  "OTHER_ACCESS_KEY",
+  "OTHER_SECRET_KEY",
+];
+
+const snapshot = new Map<string, string | undefined>();
+
+beforeEach(() => {
+  snapshot.clear();
+  for (const k of TOUCHED_KEYS) {
+    snapshot.set(k, process.env[k]);
+    delete process.env[k];
+  }
+});
+
+afterEach(() => {
+  for (const [k, v] of snapshot) {
+    if (v === undefined) delete process.env[k];
+    else process.env[k] = v;
+  }
+});
+
+function setRequired(prefix = "TEST_S3_"): void {
+  process.env[`${prefix}BUCKET`] = "my-bucket";
+  process.env[`${prefix}REGION`] = "us-east-1";
+  process.env[`${prefix}ACCESS_KEY`] = "access";
+  process.env[`${prefix}SECRET_KEY`] = "secret";
+}
+
+describe("parseS3EnvConfig — required vars", () => {
+  test("throws missing_env when BUCKET is absent", () => {
+    setRequired();
+    delete process.env["TEST_S3_BUCKET"];
+    expect(() => parseS3EnvConfig("TEST_S3_")).toThrow(/missing_env.*TEST_S3_BUCKET/);
+  });
+
+  test("throws missing_env when REGION is absent", () => {
+    setRequired();
+    delete process.env["TEST_S3_REGION"];
+    expect(() => parseS3EnvConfig("TEST_S3_")).toThrow(/missing_env.*TEST_S3_REGION/);
+  });
+
+  test("throws missing_env when ACCESS_KEY is absent", () => {
+    setRequired();
+    delete process.env["TEST_S3_ACCESS_KEY"];
+    expect(() => parseS3EnvConfig("TEST_S3_")).toThrow(/missing_env.*TEST_S3_ACCESS_KEY/);
+  });
+
+  test("throws missing_env when SECRET_KEY is absent", () => {
+    setRequired();
+    delete process.env["TEST_S3_SECRET_KEY"];
+    expect(() => parseS3EnvConfig("TEST_S3_")).toThrow(/missing_env.*TEST_S3_SECRET_KEY/);
+  });
+
+  test("treats empty string as missing (CI that exports VAR='' to unset)", () => {
+    setRequired();
+    process.env["TEST_S3_BUCKET"] = "";
+    expect(() => parseS3EnvConfig("TEST_S3_")).toThrow(/missing_env.*TEST_S3_BUCKET/);
+  });
+
+  test("passes required vars straight through", () => {
+    setRequired();
+    const config = parseS3EnvConfig("TEST_S3_");
+    expect(config.bucket).toBe("my-bucket");
+    expect(config.region).toBe("us-east-1");
+    expect(config.accessKeyId).toBe("access");
+    expect(config.secretAccessKey).toBe("secret");
+  });
+});
+
+describe("parseS3EnvConfig — optional ENDPOINT", () => {
+  test("undefined endpoint → omitted from config (AWS default behaviour)", () => {
+    setRequired();
+    const config = parseS3EnvConfig("TEST_S3_");
+    expect(config.endpoint).toBeUndefined();
+  });
+
+  test("empty-string endpoint → omitted (don't forward '' to SDK)", () => {
+    setRequired();
+    process.env["TEST_S3_ENDPOINT"] = "";
+    const config = parseS3EnvConfig("TEST_S3_");
+    expect(config.endpoint).toBeUndefined();
+  });
+
+  test("non-empty endpoint → forwarded verbatim", () => {
+    setRequired();
+    process.env["TEST_S3_ENDPOINT"] = "https://r2.example.com";
+    const config = parseS3EnvConfig("TEST_S3_");
+    expect(config.endpoint).toBe("https://r2.example.com");
+  });
+});
+
+describe("parseS3EnvConfig — FORCE_PATH_STYLE parsing", () => {
+  test("undefined → config has no forcePathStyle (auto-detect at provider level)", () => {
+    setRequired();
+    const config = parseS3EnvConfig("TEST_S3_");
+    expect(config.forcePathStyle).toBeUndefined();
+  });
+
+  test("'true' → forcePathStyle: true", () => {
+    setRequired();
+    process.env["TEST_S3_FORCE_PATH_STYLE"] = "true";
+    expect(parseS3EnvConfig("TEST_S3_").forcePathStyle).toBe(true);
+  });
+
+  test("'false' → forcePathStyle: false (explicit AWS-style override)", () => {
+    setRequired();
+    process.env["TEST_S3_FORCE_PATH_STYLE"] = "false";
+    expect(parseS3EnvConfig("TEST_S3_").forcePathStyle).toBe(false);
+  });
+
+  test("any other non-'true' value → treated as false (strict parse)", () => {
+    setRequired();
+    process.env["TEST_S3_FORCE_PATH_STYLE"] = "yes";
+    // Only the literal string "true" flips the flag on. Prevents typos
+    // like "True" / "1" from silently enabling a non-default behaviour.
+    expect(parseS3EnvConfig("TEST_S3_").forcePathStyle).toBe(false);
+  });
+});
+
+describe("parseS3EnvConfig — prefix variants", () => {
+  test("custom prefix reads independent env vars", () => {
+    process.env["OTHER_BUCKET"] = "other-bucket";
+    process.env["OTHER_REGION"] = "eu-west-1";
+    process.env["OTHER_ACCESS_KEY"] = "other-access";
+    process.env["OTHER_SECRET_KEY"] = "other-secret";
+
+    const config = parseS3EnvConfig("OTHER_");
+    expect(config.bucket).toBe("other-bucket");
+    expect(config.region).toBe("eu-west-1");
+  });
+
+  test("different prefixes don't bleed config into each other", () => {
+    setRequired("TEST_S3_");
+    process.env["OTHER_BUCKET"] = "other-bucket";
+    process.env["OTHER_REGION"] = "eu-west-1";
+    process.env["OTHER_ACCESS_KEY"] = "other-access";
+    process.env["OTHER_SECRET_KEY"] = "other-secret";
+
+    const a = parseS3EnvConfig("TEST_S3_");
+    const b = parseS3EnvConfig("OTHER_");
+    expect(a.bucket).toBe("my-bucket");
+    expect(b.bucket).toBe("other-bucket");
+  });
+});

package/src/files-provider-s3/__tests__/s3-provider.integration.ts

@@ -0,0 +1,134 @@
+import type { FileStorageProvider } from "@cosmicdrift/kumiko-framework/files";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { createS3ProviderFromEnv } from "../env-helper";
+import { createS3Provider } from "../s3-provider";
+
+// These tests run against the Minio container from docker-compose
+// (kumiko dev starts it alongside postgres/redis/meili). If Minio isn't up
+// the tests fail fast — same as postgres, not env-gated.
+
+function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) throw new Error(`Missing env for S3 integration test: ${name}`);
+  return value;
+}
+
+// Keep all keys under a per-run prefix so repeated test runs don't pollute
+// each other and a stray failure doesn't leak bytes into the next developer's
+// session. Cleanup happens in afterAll via the provider's delete().
+const RUN_PREFIX = `test-run-${generateId()}`;
+const createdKeys: string[] = [];
+
+function uniqueKey(suffix: string): string {
+  const key = `${RUN_PREFIX}/${suffix}`;
+  createdKeys.push(key);
+  return key;
+}
+
+let provider: FileStorageProvider;
+
+beforeAll(() => {
+  // forcePathStyle is deliberately NOT set — resolveForcePathStyle() must
+  // auto-detect path-style from the `endpoint` presence. If auto-detection
+  // regressed, Minio would reject virtual-host-style URLs (bucket.host/key)
+  // and every round-trip below would fail. That's the proof.
+  provider = createS3Provider({
+    endpoint: requireEnv("MINIO_ENDPOINT"),
+    region: requireEnv("MINIO_REGION"),
+    accessKeyId: requireEnv("MINIO_ACCESS_KEY"),
+    secretAccessKey: requireEnv("MINIO_SECRET_KEY"),
+    bucket: requireEnv("MINIO_BUCKET"),
+  });
+});
+
+afterAll(async () => {
+  // Best-effort cleanup — don't fail the suite if a key can't be removed.
+  for (const key of createdKeys) {
+    try {
+      await provider.delete(key);
+    } catch {
+      // ignore: test isolation doesn't depend on clean teardown
+    }
+  }
+});
+
+describe("s3-provider (Minio)", () => {
+  test("write + read round-trip preserves bytes", async () => {
+    const key = uniqueKey("round-trip.bin");
+    const payload = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x01, 0x02, 0x03, 0xff]);
+
+    await provider.write(key, payload, "application/octet-stream");
+    const readBack = await provider.read(key);
+
+    expect(readBack.length).toBe(payload.length);
+    expect(Array.from(readBack)).toEqual(Array.from(payload));
+  });
+
+  test("exists reflects write + delete", async () => {
+    const key = uniqueKey("exists-check.txt");
+
+    expect(await provider.exists(key)).toBe(false);
+
+    await provider.write(key, new TextEncoder().encode("hello"), "text/plain");
+    expect(await provider.exists(key)).toBe(true);
+
+    await provider.delete(key);
+    expect(await provider.exists(key)).toBe(false);
+  });
+
+  test("getSignedUrl returns a URL that fetches the bytes", async () => {
+    const key = uniqueKey("signed-download.txt");
+    const payload = new TextEncoder().encode("signed-url-payload");
+
+    await provider.write(key, payload, "text/plain");
+
+    // getSignedUrl is optional on the contract; the S3 provider always
+    // implements it. Narrow for TS.
+    if (!provider.getSignedUrl) throw new Error("s3 provider should implement getSignedUrl");
+    const url = await provider.getSignedUrl(key, 60, {
+      contentDisposition: 'attachment; filename="original.txt"',
+    });
+
+    expect(url).toMatch(/^https?:\/\//);
+    // The signed URL goes to the MINIO_ENDPOINT, not a virtual-host-style
+    // host — proves forcePathStyle is on.
+    expect(url).toContain("localhost:19000");
+    // Presigner encodes the expiry as X-Amz-Expires.
+    expect(url).toContain("X-Amz-Expires=60");
+    // Content-Disposition override is presigned into the query string.
+    expect(url.toLowerCase()).toContain("response-content-disposition");
+
+    // Fetch through the URL — proves it actually works end-to-end.
+    const response = await fetch(url);
+    expect(response.status).toBe(200);
+    const fetched = new Uint8Array(await response.arrayBuffer());
+    expect(Array.from(fetched)).toEqual(Array.from(payload));
+  });
+
+  test("read throws on missing key", async () => {
+    const key = uniqueKey("never-existed.bin");
+    await expect(provider.read(key)).rejects.toThrow();
+  });
+});
+
+describe("createS3ProviderFromEnv", () => {
+  test("builds a working provider from MINIO_* env vars", async () => {
+    // Construct via env-helper with the MINIO_ prefix to match the docker
+    // container's env. Then prove it works by writing + reading through it.
+    const envProvider = createS3ProviderFromEnv("MINIO_");
+    const key = uniqueKey("env-helper-check.bin");
+    const payload = new Uint8Array([1, 2, 3, 4]);
+
+    await envProvider.write(key, payload);
+    const readBack = await envProvider.read(key);
+    expect(Array.from(readBack)).toEqual(Array.from(payload));
+    await envProvider.delete(key);
+  });
+
+  test("throws for missing required env var", () => {
+    // Any prefix that doesn't map to any env vars should yield a missing_env
+    // error immediately — not a silent misconfiguration at first I/O.
+    expect(() => createS3ProviderFromEnv("NON_EXISTENT_PREFIX_")).toThrow(/missing_env/);
+  });
+});

package/src/files-provider-s3/__tests__/s3-provider.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "vitest";
+import type { S3ProviderConfig } from "../s3-provider";
+import { resolveForcePathStyle } from "../s3-provider";
+
+const baseConfig: S3ProviderConfig = {
+  bucket: "b",
+  region: "us-east-1",
+  accessKeyId: "a",
+  secretAccessKey: "s",
+};
+
+describe("resolveForcePathStyle", () => {
+  test("no endpoint + no override → false (AWS virtual-host default)", () => {
+    expect(resolveForcePathStyle(baseConfig)).toBe(false);
+  });
+
+  test("custom endpoint + no override → true (auto-detect for Minio/R2/etc.)", () => {
+    expect(resolveForcePathStyle({ ...baseConfig, endpoint: "http://localhost:9000" })).toBe(true);
+  });
+
+  test("explicit true override always wins, even without endpoint", () => {
+    expect(resolveForcePathStyle({ ...baseConfig, forcePathStyle: true })).toBe(true);
+  });
+
+  test("explicit false override always wins, even with custom endpoint", () => {
+    // Edge case: someone running a custom endpoint that does support
+    // virtual-host-style (rare, but legal) can opt out.
+    expect(
+      resolveForcePathStyle({
+        ...baseConfig,
+        endpoint: "http://localhost:9000",
+        forcePathStyle: false,
+      }),
+    ).toBe(false);
+  });
+});

package/src/files-provider-s3/env-helper.ts

@@ -0,0 +1,49 @@
+import type { FileStorageProvider } from "@cosmicdrift/kumiko-framework/files";
+import { createS3Provider, type S3ProviderConfig } from "./s3-provider";
+
+// Reads S3 connection details from process.env with a configurable prefix so
+// multi-tenant deploys can wire more than one bucket (S3_* for user-uploads,
+// BACKUP_S3_* for archives, …). Keeps apps out of the boilerplate of hand-
+// rolling a config object.
+//
+// Required vars: <prefix>BUCKET, <prefix>REGION, <prefix>ACCESS_KEY,
+// <prefix>SECRET_KEY. Optional: <prefix>ENDPOINT (for R2/Minio),
+// <prefix>FORCE_PATH_STYLE (explicit override — auto-detected when ENDPOINT
+// is set).
+export function createS3ProviderFromEnv(prefix = "S3_"): FileStorageProvider {
+  return createS3Provider(parseS3EnvConfig(prefix));
+}
+
+// Separated from createS3ProviderFromEnv so the env → config translation is
+// unit-testable without spinning up an S3Client. The returned config is a
+// plain object — pass it to createS3Provider to get a working provider.
+export function parseS3EnvConfig(prefix: string): S3ProviderConfig {
+  const bucket = requireEnv(`${prefix}BUCKET`);
+  const region = requireEnv(`${prefix}REGION`);
+  const accessKeyId = requireEnv(`${prefix}ACCESS_KEY`);
+  const secretAccessKey = requireEnv(`${prefix}SECRET_KEY`);
+  const endpoint = process.env[`${prefix}ENDPOINT`];
+  const forcePathStyleRaw = process.env[`${prefix}FORCE_PATH_STYLE`];
+
+  return {
+    bucket,
+    region,
+    accessKeyId,
+    secretAccessKey,
+    // Empty string treated as "not set" — otherwise a CI that exports
+    // FOO_ENDPOINT="" to unset it would accidentally send an empty
+    // endpoint to the SDK, which blows up deep in the signer.
+    ...(endpoint !== undefined && endpoint !== "" && { endpoint }),
+    ...(forcePathStyleRaw !== undefined && {
+      forcePathStyle: forcePathStyleRaw === "true",
+    }),
+  };
+}
+
+function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (value === undefined || value === "") {
+    throw new Error(`missing_env: ${name} is required to construct the S3 file provider`);
+  }
+  return value;
+}

package/src/files-provider-s3/index.ts

@@ -0,0 +1,3 @@
+export { createS3ProviderFromEnv, parseS3EnvConfig } from "./env-helper";
+export type { S3ProviderConfig } from "./s3-provider";
+export { createS3Provider, resolveForcePathStyle } from "./s3-provider";

package/src/files-provider-s3/s3-provider.ts

@@ -0,0 +1,114 @@
+import {
+  DeleteObjectCommand,
+  GetObjectCommand,
+  HeadObjectCommand,
+  PutObjectCommand,
+  S3Client,
+} from "@aws-sdk/client-s3";
+import { getSignedUrl as presign } from "@aws-sdk/s3-request-presigner";
+import type { FileStorageProvider, SignedUrlOptions } from "@cosmicdrift/kumiko-framework/files";
+
+// Minimal config surface — everything the SDK needs, nothing framework-
+// specific. Apps wire this into `buildServer({ files: { storageProvider } })`
+// the same way they'd pass createLocalProvider in dev.
+//
+// `endpoint` + `forcePathStyle` are the R2/Minio knobs: AWS-S3 uses
+// virtual-host-style URLs (bucket.s3.region.amazonaws.com), Minio and many
+// S3-compat providers need path-style (endpoint/bucket/key). Default
+// forcePathStyle=true whenever a custom endpoint is set — that's the
+// expected shape for every non-AWS provider.
+export type S3ProviderConfig = {
+  readonly bucket: string;
+  readonly region: string;
+  readonly accessKeyId: string;
+  readonly secretAccessKey: string;
+  // Custom endpoint for R2/Minio/DigitalOcean Spaces/etc. Omit for AWS S3.
+  readonly endpoint?: string;
+  // Override auto-detection; mainly for explicit Minio-style tests.
+  readonly forcePathStyle?: boolean;
+};
+
+// Exported for unit testing — the branch logic (explicit override vs.
+// auto-detect from endpoint) is small but load-bearing: Minio/R2 break
+// silently if the virtual-host-style is picked. Keeping it testable
+// without constructing an S3Client means the rule stays honest.
+export function resolveForcePathStyle(config: S3ProviderConfig): boolean {
+  // Explicit override wins; otherwise: custom endpoint → path-style
+  // (that's the shape every non-AWS S3-compatible provider expects),
+  // no endpoint → AWS default virtual-host-style.
+  return config.forcePathStyle ?? config.endpoint !== undefined;
+}
+
+export function createS3Provider(config: S3ProviderConfig): FileStorageProvider {
+  const client = new S3Client({
+    region: config.region,
+    credentials: {
+      accessKeyId: config.accessKeyId,
+      secretAccessKey: config.secretAccessKey,
+    },
+    ...(config.endpoint !== undefined && { endpoint: config.endpoint }),
+    forcePathStyle: resolveForcePathStyle(config),
+  });
+
+  return {
+    async write(key, data, mimeType): Promise<void> {
+      await client.send(
+        new PutObjectCommand({
+          Bucket: config.bucket,
+          Key: key,
+          Body: data,
+          ...(mimeType !== undefined && { ContentType: mimeType }),
+        }),
+      );
+    },
+
+    async read(key): Promise<Uint8Array> {
+      const response = await client.send(new GetObjectCommand({ Bucket: config.bucket, Key: key }));
+      if (!response.Body) {
+        throw new Error(`s3_read_empty_body: ${key}`);
+      }
+      // transformToByteArray is the stream-to-bytes helper the v3 SDK ships
+      // with — avoids us reinventing a ReadableStream reader. Returns a
+      // Uint8Array, which is what FileStorageProvider.read() promises.
+      return response.Body.transformToByteArray();
+    },
+
+    async delete(key): Promise<void> {
+      await client.send(new DeleteObjectCommand({ Bucket: config.bucket, Key: key }));
+    },
+
+    async exists(key): Promise<boolean> {
+      try {
+        await client.send(new HeadObjectCommand({ Bucket: config.bucket, Key: key }));
+        return true;
+      } catch (error) {
+        // S3 SDK throws either NotFound or a generic 404. Check both the
+        // `.name` property (newer SDKs) and the `$metadata.httpStatusCode`
+        // (what the SDK guarantees on every error).
+        const err = error as { name?: string; $metadata?: { httpStatusCode?: number } };
+        if (err.name === "NotFound" || err.$metadata?.httpStatusCode === 404) {
+          return false;
+        }
+        throw error;
+      }
+    },
+
+    async getSignedUrl(
+      key: string,
+      expiresInSeconds: number,
+      options?: SignedUrlOptions,
+    ): Promise<string> {
+      // ResponseContentDisposition is the S3 mechanism for overriding the
+      // Content-Disposition header on the presigned GET — the browser sees
+      // the original filename instead of the UUID storage key.
+      const command = new GetObjectCommand({
+        Bucket: config.bucket,
+        Key: key,
+        ...(options?.contentDisposition !== undefined && {
+          ResponseContentDisposition: options.contentDisposition,
+        }),
+      });
+      return presign(client, command, { expiresIn: expiresInSeconds });
+    },
+  };
+}