@cosmicdrift/kumiko-samples 0.367.0 → 0.368.0

package/packages/bundled-features/src/file-derivatives/feature.ts

@@ -100,137 +100,142 @@ export function createFileDerivativesFeature(opts: FileDerivativesOptions = {}):
     );
   }
 
-  return defineFeature(FEATURE_NAME, (r) => {
-    r.describe(
-      "Declares the `derivativeRenderer` extension point. `ctx.derivatives.variant(fileRefId, spec, name)` derives a variant of a tracked FileRef the first time it's requested and reuses the stored result afterwards (derive-on-first-use, keyed by a hash of the spec). Mount at least one `derivatives-*` renderer feature alongside this one — without a registered renderer for the FileRef's MIME type, every `variant(...)` call throws. Also declares the `derivativePublicPredicate` extension point (`r.useExtension(EXT_DERIVATIVE_PUBLIC_PREDICATE, '<entityType>', { isPublic })`) and, when `createFileDerivativesFeature({resolveApexTenant})` is passed a host-resolver, mounts an anonymous `GET {basePath}/:fileRefId/:variant` route that serves any variant name the FileRef's field declared in its `variants` for a FileRef whose entityType has a registered predicate returning true — default-deny (404) otherwise, same as an unknown FileRef or an undeclared variant name. The route's only rate-limit (`per: \"ip\"`) depends on the server's `trustedProxyHops` matching the deployment's actual reverse-proxy count — at the default 0 it ignores `x-forwarded-for` entirely, so every caller shares one bucket until that's configured. `publicTenantResolution: \"fileRef\"` keeps resolveApexTenant as the host gate but reads the variant from the FileRef row's own tenant instead of the host's, so one shared platform host serves every tenant's public variants — each FileRef-tenant's own `isPublic` predicate still default-denies. Also declares the `derivativeOverlayResolver` extension point (`r.useExtension(EXT_DERIVATIVE_OVERLAY_RESOLVER, '<entityType>', { resolve })`), used to turn a variant's `overlays[].dataToken` into the actual QR payload for that FileRef's entityType before the variant is rendered — a variant declaring a `qr` overlay throws at request-time if no resolver is registered for the FileRef's entityType.",
-    );
-    r.uiHints({
-      displayLabel: "File Derivatives",
-      category: "storage",
-      recommended: false,
-    });
-    // Needs a storage provider to read the original + write the variant —
-    // without file-foundation there's nothing to derive from or write to.
-    r.requires({ features: ["file-foundation"] });
-    // variant() reads fileRefsTable, which "files" (not file-foundation)
-    // owns — without this, mounting file-derivatives + file-foundation
-    // alone boots fine but fails at request-time with a SQL error the first
-    // time variant() runs.
-    r.requires({ features: ["files"] });
-
-    r.extendsRegistrar(EXT_DERIVATIVE_RENDERER, {
-      onRegister: () => {
-        // No side-effects at register-time — resolution (exact MIME match,
-        // then `<type>/*` wildcard) happens at request-time in
-        // resolveRenderer, mirrors file-foundation's fileProvider point.
-      },
-    });
-    r.extendsRegistrar(EXT_DERIVATIVE_PUBLIC_PREDICATE, {
-      onRegister: () => {
-        // No side-effects at register-time — resolution happens at
-        // request-time in publicVariantQuery, keyed by the FileRef's
-        // entityType.
-      },
-    });
-    r.extendsRegistrar(EXT_DERIVATIVE_OVERLAY_RESOLVER, {
-      onRegister: () => {
-        // No side-effects at register-time — resolution happens in
-        // variant(), keyed by the FileRef's entityType, before the spec
-        // hash is computed.
-      },
-    });
-
-    // Registered ONLY when resolveApexTenant is supplied — r.queryHandler
-    // registers publicVariantQuery into the feature's dispatch table as a
-    // side effect of being called, independent of what's done with its
-    // return value. Calling it unconditionally would make `publicVariant`
-    // (access: ["anonymous", ...]) reachable via the generic `/api` query
-    // dispatch even when the httpRoute below isn't mounted, bypassing the
-    // "tenantId comes from the host, never the payload" invariant that only
-    // `resolveApexTenant` enforces.
-    if (opts.resolveApexTenant) {
-      const resolveApexTenant = opts.resolveApexTenant;
-      const byFileRef = opts.publicTenantResolution === "fileRef";
-      const routeQn = byFileRef ? PUBLIC_VARIANT_BY_FILE_REF_QN : PUBLIC_VARIANT_QN;
-
-      r.queryHandler(publicVariantQuery);
-      // publicVariantByFileRefQuery is the ONLY way "fileRef" mode is
-      // reachable — registered ONLY in that mode for the same reason
-      // publicVariantQuery is gated above: registering it unconditionally
-      // would expose its unsafeRaw, cross-tenant FileRef lookup via the
-      // generic `/api` query dispatch even in default "host" mode.
-      if (byFileRef) {
-        // The handler reads the FileRef-tenant's row to keep a blocked
-        // tenant's public variants from staying reachable — require the
-        // dependency so a missing mount fails boot, not the tenant check
-        // silently no-op-ing at request time.
-        r.requires({ features: ["tenant"] });
-        r.queryHandler(publicVariantByFileRefQuery);
-      }
-
-      r.httpRoute({
-        method: "GET",
-        path: `${basePath}/:fileRefId/:variant`,
-        anonymous: true,
-        handler: async (c, { systemQuery }) => {
-          // `param(...)` is string|undefined here — `path` is a computed
-          // template, so Hono can't infer the param type from a literal.
-          const fileRefId = c.req.param("fileRefId");
-          const variant = c.req.param("variant");
-          // 404, not 400 — a syntactically bad name and "doesn't exist" must
-          // answer identically, no name-oracle. fileRefsTable.id is a UUID
-          // column — a malformed id must fail here, not at the DB. Without
-          // this, an anonymous, internet-facing caller can throw a Postgres
-          // 22P02 on every request (Bun.SQL pools the failed connection), a
-          // DoS primitive with no auth required.
-          if (!fileRefId || !variant || !VARIANT_NAME_RE.test(variant) || !isUuid(fileRefId)) {
-            return c.text("not found", 404);
-          }
-
-          const host = c.req.header("host") ?? new URL(c.req.url).host;
-          const tenantId = await resolveApexTenant(host);
-          if (!tenantId) return c.text("not found", 404);
-
-          let result: PublicVariantQueryResult;
-          try {
-            // @cast-boundary engine-payload — shape comes from
-            // publicVariantQuery's return type (publicVariantByFileRefQuery
-            // returns exactly that, or null, never its own shape).
-            result = (await systemQuery(
-              routeQn,
-              { fileRefId, variant },
-              tenantId,
-            )) as PublicVariantQueryResult;
-          } catch (err) {
-            if (err instanceof RateLimitError) {
-              return c.text("rate limited", 429);
-            }
-            // biome-ignore lint/suspicious/noConsole: ops-visible fallback, no logger wired into HttpRouteHandlerDeps
-            console.error(
-              `file-derivatives: public-variant query failed for fileRefId="${fileRefId}" variant="${variant}"`,
-              err,
-            );
-            return c.text("variant unavailable", 503);
-          }
-          if (!result) return c.text("not found", 404);
-
-          const bytes = Buffer.from(result.dataBase64, "base64");
-          const etag = computeRevisionEtag([tenantId, fileRefId, variant, result.revision]);
-          return cachedResponse(c.req.raw, {
-            body: bytes,
-            etag,
-            cache: { kind: "revalidate", maxAgeSeconds: 60 },
-            // Explicit here, not left to the app-wide security-headers default, so the route stays safe standalone.
-            headers: {
-              "content-type": result.mimeType,
-              vary: "Host",
-              "x-content-type-options": "nosniff",
-            },
-          });
+  return defineFeature(
+    FEATURE_NAME,
+    (r) => {
+      r.describe(
+        "Declares the `derivativeRenderer` extension point. `ctx.derivatives.variant(fileRefId, spec, name)` derives a variant of a tracked FileRef the first time it's requested and reuses the stored result afterwards (derive-on-first-use, keyed by a hash of the spec). Mount at least one `derivatives-*` renderer feature alongside this one — without a registered renderer for the FileRef's MIME type, every `variant(...)` call throws. Also declares the `derivativePublicPredicate` extension point (`r.useExtension(EXT_DERIVATIVE_PUBLIC_PREDICATE, '<entityType>', { isPublic })`) and, when `createFileDerivativesFeature({resolveApexTenant})` is passed a host-resolver, mounts an anonymous `GET {basePath}/:fileRefId/:variant` route that serves any variant name the FileRef's field declared in its `variants` for a FileRef whose entityType has a registered predicate returning true — default-deny (404) otherwise, same as an unknown FileRef or an undeclared variant name. The route's only rate-limit (`per: \"ip\"`) depends on the server's `trustedProxyHops` matching the deployment's actual reverse-proxy count — at the default 0 it ignores `x-forwarded-for` entirely, so every caller shares one bucket until that's configured. `publicTenantResolution: \"fileRef\"` keeps resolveApexTenant as the host gate but reads the variant from the FileRef row's own tenant instead of the host's, so one shared platform host serves every tenant's public variants — each FileRef-tenant's own `isPublic` predicate still default-denies. Also declares the `derivativeOverlayResolver` extension point (`r.useExtension(EXT_DERIVATIVE_OVERLAY_RESOLVER, '<entityType>', { resolve })`), used to turn a variant's `overlays[].dataToken` into the actual QR payload for that FileRef's entityType before the variant is rendered — a variant declaring a `qr` overlay throws at request-time if no resolver is registered for the FileRef's entityType.",
+      );
+      r.uiHints({
+        displayLabel: "File Derivatives",
+        category: "storage",
+        recommended: false,
+      });
+      // Needs a storage provider to read the original + write the variant —
+      // without file-foundation there's nothing to derive from or write to.
+      r.requires({ features: ["file-foundation"] });
+      // variant() reads fileRefsTable, which "files" (not file-foundation)
+      // owns — without this, mounting file-derivatives + file-foundation
+      // alone boots fine but fails at request-time with a SQL error the first
+      // time variant() runs.
+      r.requires({ features: ["files"] });
+
+      r.extendsRegistrar(EXT_DERIVATIVE_RENDERER, {
+        onRegister: () => {
+          // No side-effects at register-time — resolution (exact MIME match,
+          // then `<type>/*` wildcard) happens at request-time in
+          // resolveRenderer, mirrors file-foundation's fileProvider point.
+        },
+      });
+      r.extendsRegistrar(EXT_DERIVATIVE_PUBLIC_PREDICATE, {
+        onRegister: () => {
+          // No side-effects at register-time — resolution happens at
+          // request-time in publicVariantQuery, keyed by the FileRef's
+          // entityType.
         },
       });
-    }
-  });
+      r.extendsRegistrar(EXT_DERIVATIVE_OVERLAY_RESOLVER, {
+        onRegister: () => {
+          // No side-effects at register-time — resolution happens in
+          // variant(), keyed by the FileRef's entityType, before the spec
+          // hash is computed.
+        },
+      });
+
+      // Registered ONLY when resolveApexTenant is supplied — r.queryHandler
+      // registers publicVariantQuery into the feature's dispatch table as a
+      // side effect of being called, independent of what's done with its
+      // return value. Calling it unconditionally would make `publicVariant`
+      // (access: ["anonymous", ...]) reachable via the generic `/api` query
+      // dispatch even when the httpRoute below isn't mounted, bypassing the
+      // "tenantId comes from the host, never the payload" invariant that only
+      // `resolveApexTenant` enforces.
+      if (opts.resolveApexTenant) {
+        const resolveApexTenant = opts.resolveApexTenant;
+        const byFileRef = opts.publicTenantResolution === "fileRef";
+        const routeQn = byFileRef ? PUBLIC_VARIANT_BY_FILE_REF_QN : PUBLIC_VARIANT_QN;
+
+        r.queryHandler(publicVariantQuery);
+        // publicVariantByFileRefQuery is the ONLY way "fileRef" mode is
+        // reachable — registered ONLY in that mode for the same reason
+        // publicVariantQuery is gated above: registering it unconditionally
+        // would expose its unsafeRaw, cross-tenant FileRef lookup via the
+        // generic `/api` query dispatch even in default "host" mode.
+        if (byFileRef) {
+          // The handler reads the FileRef-tenant's row to keep a blocked
+          // tenant's public variants from staying reachable — require the
+          // dependency so a missing mount fails boot, not the tenant check
+          // silently no-op-ing at request time.
+          r.requires({ features: ["tenant"] });
+          r.queryHandler(publicVariantByFileRefQuery);
+        }
+
+        r.httpRoute({
+          method: "GET",
+          path: `${basePath}/:fileRefId/:variant`,
+          anonymous: true,
+          handler: async (c, { systemQuery }) => {
+            // `param(...)` is string|undefined here — `path` is a computed
+            // template, so Hono can't infer the param type from a literal.
+            const fileRefId = c.req.param("fileRefId");
+            const variant = c.req.param("variant");
+            // 404, not 400 — a syntactically bad name and "doesn't exist" must
+            // answer identically, no name-oracle. fileRefsTable.id is a UUID
+            // column — a malformed id must fail here, not at the DB. Without
+            // this, an anonymous, internet-facing caller can throw a Postgres
+            // 22P02 on every request (Bun.SQL pools the failed connection), a
+            // DoS primitive with no auth required.
+            if (!fileRefId || !variant || !VARIANT_NAME_RE.test(variant) || !isUuid(fileRefId)) {
+              return c.text("not found", 404);
+            }
+
+            const host = c.req.header("host") ?? new URL(c.req.url).host;
+            const tenantId = await resolveApexTenant(host);
+            if (!tenantId) return c.text("not found", 404);
+
+            let result: PublicVariantQueryResult;
+            try {
+              // @cast-boundary engine-payload — shape comes from
+              // publicVariantQuery's return type (publicVariantByFileRefQuery
+              // returns exactly that, or null, never its own shape).
+              result = (await systemQuery(
+                routeQn,
+                { fileRefId, variant },
+                tenantId,
+              )) as PublicVariantQueryResult;
+            } catch (err) {
+              if (err instanceof RateLimitError) {
+                return c.text("rate limited", 429);
+              }
+              // biome-ignore lint/suspicious/noConsole: ops-visible fallback, no logger wired into HttpRouteHandlerDeps
+              console.error(
+                `file-derivatives: public-variant query failed for fileRefId="${fileRefId}" variant="${variant}"`,
+                err,
+              );
+              return c.text("variant unavailable", 503);
+            }
+            if (!result) return c.text("not found", 404);
+
+            const bytes = Buffer.from(result.dataBase64, "base64");
+            const etag = computeRevisionEtag([tenantId, fileRefId, variant, result.revision]);
+            return cachedResponse(c.req.raw, {
+              body: bytes,
+              etag,
+              cache: { kind: "revalidate", maxAgeSeconds: 60 },
+              // Explicit here, not left to the app-wide security-headers default, so the route stays safe standalone.
+              headers: {
+                "content-type": result.mimeType,
+                vary: "Host",
+                "x-content-type-options": "nosniff",
+              },
+            });
+          },
+        });
+      }
+    },
+    Object.keys(opts).length === 0 ? { dedupeOptions: {} } : undefined,
+  );
 }
 
+/** @deprecated Use createFileDerivativesFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
 export const fileDerivativesFeature = createFileDerivativesFeature();

package/packages/bundled-features/src/file-derivatives/handlers/public-variant-by-file-ref.query.ts

@@ -1,4 +1,4 @@
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
 import {
   createAnonymousUser,
   defineQueryHandler,

package/packages/bundled-features/src/file-derivatives/handlers/public-variant.query.ts

@@ -23,7 +23,7 @@
 // but this handler's own isPublic gate runs exactly the same either way.
 
 import { computeRevisionEtag } from "@cosmicdrift/kumiko-framework/api";
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
 import { resolveFieldVariant } from "@cosmicdrift/kumiko-framework/derivatives";
 import {
   defineQueryHandler,

package/packages/bundled-features/src/file-foundation/feature.ts

@@ -37,36 +37,45 @@ export {
 
 const FEATURE_NAME = "file-foundation";
 
-export const fileFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
-  r.describe(
-    "Defines the `fileProvider` extension point and a per-tenant `provider` config key that selects which registered storage plugin to use at runtime. Call `createFileProviderForTenant(ctx, tenantId)` to get a `FileStorageProvider` — use this feature together with at least one `file-provider-*` feature; the `files` feature builds on top of it for tracked `FileRef` entities with GDPR hooks.",
-  );
-  r.uiHints({
-    displayLabel: "File Provider Foundation",
-    category: "storage",
-    recommended: false,
-  });
-  r.requires({ features: ["config"] });
+export function createFileFoundationFeature() {
+  return defineFeature(
+    FEATURE_NAME,
+    (r) => {
+      r.describe(
+        "Defines the `fileProvider` extension point and a per-tenant `provider` config key that selects which registered storage plugin to use at runtime. Call `createFileProviderForTenant(ctx, tenantId)` to get a `FileStorageProvider` — use this feature together with at least one `file-provider-*` feature; the `files` feature builds on top of it for tracked `FileRef` entities with GDPR hooks.",
+      );
+      r.uiHints({
+        displayLabel: "File Provider Foundation",
+        category: "storage",
+        recommended: false,
+      });
+      r.requires({ features: ["config"] });
 
-  r.extendsRegistrar(EXT_FILE_PROVIDER, {
-    onRegister: () => {
-      // No side-effects at register-time — registry stores the usage,
-      // factory looks it up at request-time.
-    },
-  });
+      r.extendsRegistrar(EXT_FILE_PROVIDER, {
+        onRegister: () => {
+          // No side-effects at register-time — registry stores the usage,
+          // factory looks it up at request-time.
+        },
+      });
 
-  const providerConfigKey = r.config(
-    "provider",
-    createTenantConfig("text", {
-      default: "",
-      env: FILE_STORAGE_PROVIDER_ENV,
-      write: access.roles("TenantAdmin", "SystemAdmin"),
-      read: access.roles("TenantAdmin", "SystemAdmin", "User"),
-    }),
+      const providerConfigKey = r.config(
+        "provider",
+        createTenantConfig("text", {
+          default: "",
+          env: FILE_STORAGE_PROVIDER_ENV,
+          write: access.roles("TenantAdmin", "SystemAdmin"),
+          read: access.roles("TenantAdmin", "SystemAdmin", "User"),
+        }),
+      );
+      // Readiness gating: provider-plugins' required keys/secrets count only
+      // while their plugin is the one this key selects.
+      r.extensionSelector(EXT_FILE_PROVIDER, providerConfigKey);
+
+      return { providerConfigKey };
+    },
+    { dedupeOptions: {} },
   );
-  // Readiness gating: provider-plugins' required keys/secrets count only
-  // while their plugin is the one this key selects.
-  r.extensionSelector(EXT_FILE_PROVIDER, providerConfigKey);
+}
 
-  return { providerConfigKey };
-});
+/** @deprecated Use createFileFoundationFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
+export const fileFoundationFeature = createFileFoundationFeature();

package/packages/bundled-features/src/file-foundation/index.ts

@@ -1,6 +1,7 @@
 // Public API of the file-foundation bundled-feature.
 
 export {
+  createFileFoundationFeature,
   createFileProviderForTenant,
   type FileProviderContext,
   type FileProviderPlugin,

package/packages/bundled-features/src/file-foundation/read-file-ref-content.ts

@@ -1,5 +1,5 @@
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbRunner, TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { isUuid, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
   createFileContext,

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

@@ -58,27 +58,38 @@ export function clearStorage(tenantId: string): void {
 // =============================================================================
 // Feature-definition
 // =============================================================================
+export function createFileProviderInMemoryFeature() {
+  return defineFeature(
+    FEATURE_NAME,
+    (r) => {
+      r.describe(
+        'Registers an in-process `"inmemory"` provider for `file-foundation` that stores file bytes per tenant in a module-level Map. Use `listKeys(tenantId)` and `clearStorage(tenantId)` in demo apps and tests; not for production (data is lost on restart and grows without bound).',
+      );
+      r.uiHints({
+        displayLabel: "File Provider · In-Memory",
+        category: "storage",
+        recommended: false,
+      });
+      // Kein requires auf "config" oder "secrets" — der
+      // In-Memory-Provider hat keine Config + kein Secret. Nur die
+      // file-foundation muss da sein (Plugin-extension-point).
+      r.requires({ features: ["file-foundation"] });
 
-export const fileProviderInMemoryFeature = defineFeature(FEATURE_NAME, (r) => {
-  r.describe(
-    'Registers an in-process `"inmemory"` provider for `file-foundation` that stores file bytes per tenant in a module-level Map. Use `listKeys(tenantId)` and `clearStorage(tenantId)` in demo apps and tests; not for production (data is lost on restart and grows without bound).',
+      const plugin: FileProviderPlugin = {
+        build: async (
+          _ctx: FileProviderContext,
+          tenantId: string,
+        ): Promise<FileStorageProvider> => {
+          // Returns the per-tenant storage. Identity-stable across calls so
+          // accumulated state is kept.
+          return getOrCreateProviderForTenant(tenantId);
+        }, // @wrapper-known semantic-alias
+      };
+      r.useExtension("fileProvider", "inmemory", plugin);
+    },
+    { dedupeOptions: {} },
   );
-  r.uiHints({
-    displayLabel: "File Provider · In-Memory",
-    category: "storage",
-    recommended: false,
-  });
-  // Kein requires auf "config" oder "secrets" — der
-  // In-Memory-Provider hat keine Config + kein Secret. Nur die
-  // file-foundation muss da sein (Plugin-extension-point).
-  r.requires({ features: ["file-foundation"] });
+}
 
-  const plugin: FileProviderPlugin = {
-    build: async (_ctx: FileProviderContext, tenantId: string): Promise<FileStorageProvider> => {
-      // Returnt den per-tenant Storage. Identitätsstabil zwischen calls
-      // damit accumulated state erhalten bleibt.
-      return getOrCreateProviderForTenant(tenantId);
-    }, // @wrapper-known semantic-alias
-  };
-  r.useExtension("fileProvider", "inmemory", plugin);
-});
+/** @deprecated Use createFileProviderInMemoryFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
+export const fileProviderInMemoryFeature = createFileProviderInMemoryFeature();

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

@@ -1,3 +1,8 @@
 // Public API of the file-provider-inmemory bundled-feature.
 
-export { clearStorage, fileProviderInMemoryFeature, listKeys } from "./feature.js";
+export {
+  clearStorage,
+  createFileProviderInMemoryFeature,
+  fileProviderInMemoryFeature,
+  listKeys,
+} from "./feature.js";

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

@@ -1 +1,10 @@
-[]
+[
+  {
+    "version": "0.368.0",
+    "type": "breaking",
+    "title": "The S3 file providers merge into createFileProviderS3Feature({ fromEnv })",
+    "detail": "createFileProviderS3Feature() mounts the per-tenant config provider as before. createFileProviderS3Feature({ fromEnv: true }) mounts the env-configured provider (feature name, provider key \"s3-env\" and requires unchanged). The S3 client helpers (createS3Provider, createS3ProviderFromEnv, parseS3EnvConfig, resolveForcePathStyle, S3ProviderConfig) move to the new subpath @cosmicdrift/kumiko-bundled-features/file-provider-s3/lib.\n\nThe subpaths file-provider-s3-env and files-provider-s3 keep working as deprecated re-exports and are removed in the first release after 2026-10-29.\n\nold -> new:\n  fileProviderS3EnvFeature from .../file-provider-s3-env -> createFileProviderS3Feature({ fromEnv: true }) from .../file-provider-s3\n  fileProviderS3Feature -> createFileProviderS3Feature()\n  @cosmicdrift/kumiko-bundled-features/files-provider-s3 -> @cosmicdrift/kumiko-bundled-features/file-provider-s3/lib",
+    "migration": "Run `bun kumiko-upgrade --apply`. It rewrites the imports and the env feature mount, and reports `typeof fileProviderS3EnvFeature` and re-exports of it with file and line.",
+    "codemod": "scripts/codemod/s3-imports.ts"
+  }
+]

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

@@ -0,0 +1,62 @@
+// 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 the default 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 { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import type { FileStorageProvider } from "@cosmicdrift/kumiko-framework/files";
+import { createS3ProviderFromEnv } from "./lib/env-helper.js";
+
+const FEATURE_NAME = "file-provider-s3-env";
+
+export function createFileProviderS3EnvFeature() {
+  return 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 requires on "config" or "secrets" — credentials come from
+      // env, not the per-tenant config + secrets store. Only the file-foundation
+      // plugin-extension-point must be mounted.
+      r.requires({ features: ["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);
+    },
+    { dedupeOptions: {} },
+  );
+}