@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/file-provider-s3/changes.json

@@ -0,0 +1 @@
+[]

package/packages/bundled-features/src/file-provider-s3/feature.ts

@@ -0,0 +1,176 @@
+// 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 {
+  FileProviderContext,
+  FileProviderPlugin,
+} from "@cosmicdrift/kumiko-bundled-features/file-foundation";
+import { createS3Provider } from "@cosmicdrift/kumiko-bundled-features/files-provider-s3";
+import {
+  requireDefined,
+  requireNonEmpty,
+  requireSecretSet,
+} from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
+import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import { access, createTenantConfig, defineFeature } 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.describe(
+    'Registers itself as the `"s3"` provider for `file-foundation` and owns the per-tenant config keys (`bucket`, `region`, `endpoint`, `forcePathStyle`, `accessKeyId`) and the encrypted `s3.secretAccessKey` secret. Compatible with any S3-compatible object store (AWS S3, Hetzner Object Storage); set credentials via the admin UI or a seed handler before the first file operation.',
+  );
+  r.uiHints({
+    displayLabel: "File Provider · S3",
+    category: "storage",
+    recommended: false,
+  });
+  r.requires("config");
+  r.requires("secrets");
+  r.requires("file-foundation");
+
+  const secretAccessKey = r.secret("s3.secretAccessKey", {
+    label: { en: "S3 secret access key" },
+    hint: {
+      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",
+    // required: true ↔ the missing-secret throw in readSecretAccessKey — keep in sync.
+    required: true,
+  });
+
+  // required: true ↔ the requireNonEmpty calls in buildS3Provider — keep in sync.
+  const configKeys = r.config({
+    keys: {
+      bucket: createTenantConfig("text", {
+        required: true,
+        default: "",
+        write: access.roles("TenantAdmin", "SystemAdmin"),
+        read: access.roles("TenantAdmin", "SystemAdmin"),
+      }),
+      region: createTenantConfig("text", {
+        required: true,
+        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", {
+        required: true,
+        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: FileProviderContext, tenantId: string) => buildS3Provider(ctx, tenantId), // @wrapper-known semantic-alias
+  };
+  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: FileProviderContext,
+  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; // @cast-boundary engine-payload
+  const endpoint = endpointRaw.length > 0 ? endpointRaw : undefined;
+  const forcePathStyle = requireDefined(
+    await ctxConfig(fileProviderS3Feature.exports.configKeys.forcePathStyle),
+    FEATURE_NAME,
+    "forcePathStyle",
+  ) as boolean; // @cast-boundary engine-payload
+  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: FileProviderContext, tenantId: string): Promise<string> {
+  const secrets = requireSecretsContext(ctx, FEATURE_NAME);
+  const branded = await secrets.get(tenantId, S3_SECRET_ACCESS_KEY);
+  return requireSecretSet(branded, FEATURE_NAME, S3_SECRET_ACCESS_KEY.name).reveal();
+}

package/packages/bundled-features/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.js";

package/packages/bundled-features/src/file-provider-s3-env/changes.json

@@ -0,0 +1 @@
+[]

package/packages/bundled-features/src/file-provider-s3-env/feature.ts

@@ -0,0 +1,58 @@
+// kumiko-feature-version: 1
+//
+// file-provider-s3-env — S3 file provider configured entirely from
+// process.env. ONE shared bucket for ALL tenants: wire it by setting the
+// `S3_*` env vars + mounting — no per-tenant admin seeding and no
+// `secrets`-feature dependency.
+//
+// **vs file-provider-s3:** the config-based `"s3"` provider owns per-tenant
+// config keys + an encrypted `s3.secretAccessKey` secret (per-tenant
+// buckets, admin-seeded). This `"s3-env"` provider reads one credential set
+// from env and serves every tenant from one bucket — the
+// Hetzner-Object-Storage / single-bucket deploy case. Tenant isolation
+// still holds: file keys carry the tenant (export ZIPs:
+// `exports/<tenantId>/<jobId>.zip`) or are globally-unique UUIDs (fileRefs).
+//
+// **Pattern-Vorbild:** mirrors file-provider-inmemory (zero admin seeding,
+// only the file-foundation plugin-point required).
+//
+// **Env vars** (read by createS3ProviderFromEnv, prefix `S3_`):
+//   required — S3_BUCKET, S3_REGION, S3_ACCESS_KEY, S3_SECRET_KEY
+//   optional — S3_ENDPOINT (S3-compat stores incl. Hetzner Object Storage),
+//              S3_FORCE_PATH_STYLE
+// Missing required vars throw on the FIRST file op (inside the export cron).
+// The user-data-rights boot guard surfaces that at boot instead.
+
+import type {
+  FileProviderContext,
+  FileProviderPlugin,
+} from "@cosmicdrift/kumiko-bundled-features/file-foundation";
+import { createS3ProviderFromEnv } from "@cosmicdrift/kumiko-bundled-features/files-provider-s3";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import type { FileStorageProvider } from "@cosmicdrift/kumiko-framework/files";
+
+const FEATURE_NAME = "file-provider-s3-env";
+
+export const fileProviderS3EnvFeature = defineFeature(FEATURE_NAME, (r) => {
+  r.describe(
+    'Registers an `"s3-env"` provider for `file-foundation` that reads one S3 credential set from `process.env` (`S3_BUCKET`/`S3_REGION`/`S3_ACCESS_KEY`/`S3_SECRET_KEY`, optional `S3_ENDPOINT`/`S3_FORCE_PATH_STYLE`) and serves every tenant from one shared bucket — no per-tenant config or secret seeding. Use this for single-bucket S3-compatible deploys (e.g. Hetzner Object Storage); use `file-provider-s3` instead when each tenant needs its own bucket/credentials.',
+  );
+  r.uiHints({
+    displayLabel: "File Provider · S3 (env)",
+    category: "storage",
+    recommended: false,
+  });
+  // No r.requires("config") / r.requires("secrets") — credentials come from
+  // env, not the per-tenant config + secrets store. Only the file-foundation
+  // plugin-extension-point must be mounted.
+  r.requires("file-foundation");
+
+  const plugin: FileProviderPlugin = {
+    // tenantId ignored: one shared bucket serves all tenants (isolation via
+    // tenant-prefixed / UUID keys). Built fresh per call like file-provider-s3;
+    // the S3 client opens no connection at construction.
+    build: async (_ctx: FileProviderContext, _tenantId: string): Promise<FileStorageProvider> =>
+      createS3ProviderFromEnv(), // @wrapper-known semantic-alias
+  };
+  r.useExtension("fileProvider", "s3-env", plugin);
+});

package/packages/bundled-features/src/file-provider-s3-env/index.ts

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

package/packages/bundled-features/src/files/README.md

@@ -0,0 +1,50 @@
+# files
+
+Schema-Sicht der framework-internen `file_refs`-Tabelle als bundled-feature.
+Sprint-1.5 Refactor (Pre-Sprint-2).
+
+## Was es macht
+
+Deklariert `r.entity("fileRef", ...)` für die DB-Tabelle die das
+Framework via `createFileRoutes` (multipart-Upload + binary-Download)
+bewirtschaftet. Das öffnet die Tür für Cross-Feature-Hooks:
+
+- **Sprint 2** (`user-data-rights-defaults`) registriert `r.useExtension(EXT_USER_DATA, "fileRef", { export, delete })` — Forget-Flow + Daten-Export fassen die Files automatisch an. ✅ done
+- **Sprint 5** (`tenant-lifecycle`) wird `r.useExtension(EXT_TENANT_DATA, "fileRef", { destroy })` registrieren — Tenant-Destroy löscht alle FileRefs.
+
+## Was es NICHT macht
+
+- **Keine Upload-/Download-Routes** — die bleiben in
+  `framework/src/api/server.ts` via `options.files`-Bootstrap.
+  Multipart-Form-Body und Binary-Streaming passen nicht ins Write/Query-
+  Handler-Pattern; ein Refactor zu `r.httpRoute` wäre orthogonal zu
+  diesem Sprint.
+- **Kein eigener Drizzle-Table-Build** — die `file_refs`-Tabelle
+  existiert schon in `framework/src/files/file-ref-table.ts`. Diese
+  Entity ist nur die Schema-Sicht für Cross-Feature-Hooks; Drizzle-
+  Queries laufen weiter über `fileRefsTable` aus
+  `@cosmicdrift/kumiko-framework/files`.
+
+## PII-Annotations (Sprint 0.1+0.7)
+
+```ts
+fileName     → personal: "self", find: "none"  (Originalname enthält oft Personen-Bezug)
+storageKey   → kein PII-Marker (interner UUID-Key, trifft die Heuristik nicht)
+mimeType     → kein PII-Marker
+size         → kein PII-Marker
+entityType   → kein PII-Marker
+entityId     → kein PII-Marker
+fieldName    → kein PII-Marker
+insertedAt   → kein PII-Marker (Audit-Timestamp, Framework-managed Base-Column)
+insertedById → kein PII-Marker (User-Reference, Framework-managed Base-Column, kein Eigen-PII)
+```
+
+`fileName: personal: "self"` heißt: Sprint 3 Crypto-Shredding verschlüsselt den
+Wert mit dem Author-Subject-Key (für File-INHALTE: separates
+Subject-Resolver-Pattern via `subjectField` — siehe storage-encryption.md
+Sprint 4).
+
+## Tests
+
+`__tests__/files.integration.test.ts` — 5 Tests die beweisen dass die Feature-
+Definition clean lädt + die PII-Markers + Tabellenname stimmen.

package/packages/bundled-features/src/files/changes.json

@@ -0,0 +1 @@
+[]

package/packages/bundled-features/src/files/feature.ts

@@ -0,0 +1,7 @@
+// files — full Event-Sourcing für File-Metadata. Die Implementierung (Entity,
+// files:event:*-Events, Inline-Projektion) lebt seit dem ES-Umbau im
+// Framework neben file-routes + fileRefsTable, weil file-routes hart davon
+// abhängt (appendDomainEventCore verlangt registrierte Events + Projektion).
+// Dieses Modul re-exportiert nur, damit der App-Import-Pfad
+// `@cosmicdrift/kumiko-bundled-features/files` stabil bleibt.
+export { createFilesFeature, fileRefEntity } from "@cosmicdrift/kumiko-framework/files";

package/packages/bundled-features/src/files/index.ts

@@ -0,0 +1 @@
+export { createFilesFeature, fileRefEntity } from "./feature.js";

package/packages/bundled-features/src/files-provider-s3/changes.json

@@ -0,0 +1 @@
+[]

package/packages/bundled-features/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.js";
+
+// 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/packages/bundled-features/src/files-provider-s3/index.ts

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

package/packages/bundled-features/src/files-provider-s3/s3-provider.ts

@@ -0,0 +1,196 @@
+import {
+  assertSafeStorageKey,
+  type FileStorageProvider,
+  type SignedUrlOptions,
+} from "@cosmicdrift/kumiko-framework/files";
+
+// =============================================================================
+// Operator-Pflicht-Setup (Multipart-Upload-Cleanup)
+// =============================================================================
+//
+// `writeStream` nutzt Bun's S3-Writer fuer echtes multipart-streaming. S3
+// created dabei eine Multipart-Upload-Session mit einer Upload-ID; bei
+// normaler Completion wird sie geschlossen. Wird der Export-Worker mid-write
+// gecancelt (Pod-Restart, K8s-OOM-Kill, Process-Signal), bleibt die Session
+// in S3 OFFEN und berechnet Storage-Kosten fuer die bereits hochgeladenen
+// Parts — bis sie via Lifecycle-Rule abgebrochen werden.
+//
+// **Pflicht-Operator-Setup auf jedem Bucket:**
+//
+//   {
+//     "Rules": [{
+//       "ID": "AbortIncompleteMultipartUploads",
+//       "Status": "Enabled",
+//       "AbortIncompleteMultipartUpload": { "DaysAfterInitiation": 7 },
+//       "Filter": {}
+//     }]
+//   }
+//
+// AWS-CLI: `aws s3api put-bucket-lifecycle-configuration --bucket <name>
+// --lifecycle-configuration file://lifecycle.json`. Hetzner Object Storage
+// + R2 + Minio supporten dieselbe Syntax.
+//
+// =============================================================================
+// Operator-Pflicht-Setup (IAM: list permission)
+// =============================================================================
+//
+// GDPR-forget/tenant-destroy erasure (user-data-rights-defaults) calls
+// `list()` to find derivative/variant keys alongside the original. A bucket
+// policy granting only `s3:DeleteObject` (no `s3:ListBucket`) makes every
+// forget run fail — grant both, not just delete.
+
+const STREAM_PART_SIZE = 5 * 1024 * 1024;
+
+// `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;
+};
+
+// A single S3 list() page, generalized just enough that collectPaginatedKeys
+// can be tested against a fake sequence of pages, no live bucket needed.
+type S3ListPage = {
+  readonly contents?: ReadonlyArray<{ readonly key: string }>;
+  readonly isTruncated?: boolean;
+};
+
+// Exported for unit testing — the loop is the load-bearing part of `list`:
+// S3 caps a page at 1000 keys, and a derivative set for a heavily-rendered
+// original can exceed that. Owns only the isTruncated/startAfter pagination;
+// `fetchPage` closes over prefix/maxKeys/credentials.
+export async function collectPaginatedKeys(
+  fetchPage: (startAfter: string | undefined) => Promise<S3ListPage>,
+): Promise<readonly string[]> {
+  const keys: string[] = [];
+  let startAfter: string | undefined;
+  for (;;) {
+    const page = await fetchPage(startAfter);
+    const contents = page.contents ?? [];
+    for (const obj of contents) keys.push(obj.key);
+    if (!page.isTruncated || contents.length === 0) break;
+    startAfter = contents[contents.length - 1]?.key;
+  }
+  return keys;
+}
+
+// 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.
+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;
+}
+
+// Bun's `virtualHostedStyle` is the strict inverse of the `forcePathStyle` knob
+// this config exposes — the seam that silently breaks Minio/R2 if the `!` drifts.
+export function resolveVirtualHostedStyle(config: S3ProviderConfig): boolean {
+  return !resolveForcePathStyle(config);
+}
+
+export function createS3Provider(config: S3ProviderConfig): FileStorageProvider {
+  const client = new Bun.S3Client({
+    region: config.region,
+    accessKeyId: config.accessKeyId,
+    secretAccessKey: config.secretAccessKey,
+    bucket: config.bucket,
+    ...(config.endpoint !== undefined && { endpoint: config.endpoint }),
+    virtualHostedStyle: resolveVirtualHostedStyle(config),
+  });
+
+  return {
+    async write(key, data, mimeType): Promise<void> {
+      assertSafeStorageKey(key);
+      await client.write(key, data, mimeType !== undefined ? { type: mimeType } : undefined);
+    },
+
+    async writeStream(key, source, options): Promise<void> {
+      assertSafeStorageKey(key);
+      // Echtes multipart-streaming via Bun's S3-Writer — partSize steuert die
+      // Part-Boundary intern (AWS/R2 verlangen non-final Parts >= 5 MiB,
+      // sonst EntityTooSmall beim CompleteMultipartUpload). Manuelles flush()
+      // hier wuerde genau diese Garantie brechen, sobald die Source-Chunks
+      // nicht auf partSize aufgehen.
+      const writer = client.file(key).writer({
+        ...(options?.mimeType !== undefined && { type: options.mimeType }),
+        retry: 3,
+        queueSize: 4,
+        partSize: STREAM_PART_SIZE,
+      });
+      for await (const chunk of source) {
+        // Await applies Backpressure und bounded die in-flight Queue auf
+        // queueSize, statt unbegrenzt zu puffern.
+        await writer.write(chunk);
+      }
+      await writer.end();
+    },
+
+    async read(key): Promise<Uint8Array> {
+      assertSafeStorageKey(key);
+      return new Uint8Array(await client.file(key).arrayBuffer());
+    },
+
+    readStream(key): AsyncIterable<Uint8Array> {
+      assertSafeStorageKey(key);
+      // Lazy: erst beim ersten chunk-pull wird der GET-Request abgesetzt.
+      // Existiert der Key nicht, faellt der Error genau dort (nicht beim
+      // readStream-Aufruf) — gleiches Lazy-Verhalten wie inmemory + local.
+      return {
+        async *[Symbol.asyncIterator]() {
+          for await (const chunk of client.file(key).stream()) {
+            yield chunk;
+          }
+        },
+      };
+    },
+
+    async delete(key): Promise<void> {
+      assertSafeStorageKey(key);
+      await client.delete(key);
+    },
+
+    async exists(key): Promise<boolean> {
+      assertSafeStorageKey(key);
+      return client.exists(key);
+    },
+
+    async list(prefix): Promise<readonly string[]> {
+      return collectPaginatedKeys((startAfter) =>
+        client.list({
+          prefix,
+          maxKeys: 1000,
+          ...(startAfter !== undefined && { startAfter }),
+        }),
+      );
+    },
+
+    async getSignedUrl(
+      key: string,
+      expiresInSeconds: number,
+      options?: SignedUrlOptions,
+    ): Promise<string> {
+      assertSafeStorageKey(key);
+      // contentDisposition wird von Bun als response-content-disposition
+      // Query-Param signiert (Response-Override fuer den GET-Download) —
+      // der Browser sieht den Original-Dateinamen statt des UUID-Keys.
+      return client.presign(key, {
+        expiresIn: expiresInSeconds,
+        method: "GET",
+        ...(options?.contentDisposition !== undefined && {
+          contentDisposition: options.contentDisposition,
+        }),
+      });
+    },
+  };
+}

package/packages/bundled-features/src/files-tenant-data/changes.json

@@ -0,0 +1,9 @@
+[
+  {
+    "version": "0.275.0",
+    "type": "breaking",
+    "title": "sweepOrphanedDerivativesJob takes the raw DbConnection as a third argument; the job declares escapeHatch (fw#2914).",
+    "detail": "JobContext.db is now a tenant-filtered TenantDb. The sweep checks fileRef owners of every tenant, so its registration declares `escapeHatch` and passes `ctx.db.unsafeRaw(reason)` to `sweepOrphanedDerivativesJob(payload, ctx, db)`. Without the raw runner, the foreign-tenant owner lookup would be narrowed away and every derivative would look orphaned.",
+    "migration": "Direct callers of the exported `sweepOrphanedDerivativesJob` pass the raw `DbConnection` as the third argument. Apps that only mount the feature need no change."
+  }
+]