@modern-admin/feature-upload 0.2.1 → 0.3.2

package/src/mime.ts

@@ -0,0 +1,42 @@
+/**
+ * Server-side MIME allow-list matching.
+ *
+ * `UploadPropertyConfig.mimeTypes` uses the same syntax as the HTML `accept`
+ * attribute — exact types (`image/jpeg`), type wildcards (`image/*`), or the
+ * catch-all wildcard (`*`, or its explicit `type`/`subtype` form). The
+ * frontend enforces it for UX; the server
+ * re-checks it so a hand-crafted request cannot store a disallowed type.
+ *
+ * Note: the matched MIME is the *declared* `Content-Type` from the multipart
+ * part, which a client can spoof. This is defense-in-depth (it stops the
+ * trivial "bypass the frontend accept filter" attack and pairs with the size
+ * limits), not content sniffing — magic-byte inspection would need a decoder
+ * per format and is intentionally out of scope here.
+ */
+
+/** Normalise a raw MIME to `type/subtype`, lower-cased, without parameters. */
+function normalizeType(raw: string): string {
+  return raw.split(';')[0]!.trim().toLowerCase()
+}
+
+/**
+ * True when `type` matches at least one pattern in `patterns`. An empty or
+ * omitted pattern list allows everything (no restriction configured).
+ */
+export function mimeMatches(type: string, patterns: readonly string[] | null | undefined): boolean {
+  if (!patterns || patterns.length === 0) return true
+  const t = normalizeType(type)
+  if (!t) return false
+  const [tMain, tSub] = t.split('/')
+  for (const raw of patterns) {
+    const p = normalizeType(raw)
+    if (p === '*' || p === '*/*') return true
+    const [pMain, pSub] = p.split('/')
+    if (pSub === '*') {
+      if (pMain === tMain) return true
+    } else if (pMain === tMain && pSub === tSub) {
+      return true
+    }
+  }
+  return false
+}

package/src/nest/upload-sweeper.service.ts

@@ -36,6 +36,15 @@ export class UploadSweeperService implements OnModuleInit, OnModuleDestroy {
   onModuleInit(): void {
     const interval = this.options.sweepIntervalMs ?? DEFAULT_SWEEP_INTERVAL_MS
     if (interval <= 0) return
+    if (!this.options.acknowledgeSingleInstance) {
+      console.warn(
+        '[modern-admin/feature-upload] The pending-upload registry and sweeper are ' +
+          'in-process (single-instance). Behind a load balancer with ≥2 replicas the ' +
+          'sweeper can delete a just-saved file (see PendingUploadsRegistry docs). ' +
+          'Run single-instance until a shared store lands, or pass ' +
+          '`acknowledgeSingleInstance: true` to silence this warning.',
+      )
+    }
     this.timer = setInterval(() => {
       void PendingUploadsRegistry.sweep()
     }, interval)

package/src/nest/upload.controller.ts

@@ -29,10 +29,12 @@ import {
   Inject,
   InternalServerErrorException,
   NotFoundException,
+  PayloadTooLargeException,
   Post,
   Param,
   Query,
   Req,
+  UnsupportedMediaTypeException,
   UseGuards,
 } from '@nestjs/common'
 import { ApiCookieAuth, ApiTags } from '@nestjs/swagger'
@@ -46,15 +48,46 @@ import {
 import { MODERN_ADMIN, ModernAdminAuthGuard } from '@modern-admin/nest'
 import { UploadProviderRegistry } from '../registry.js'
 import { PendingUploadsRegistry } from '../pending-registry.js'
+import { isUnsafeKey, sanitizeFilename } from '../path-safety.js'
+import { mimeMatches } from '../mime.js'
 import { UPLOAD_MODULE_OPTIONS, type ModernAdminUploadModuleOptions } from './upload.tokens.js'
 import type { UploadedFile, UploadedFileInfo } from '../types.js'
 
-/** Reads every file from a multipart/form-data stream using busboy. */
-function parseAllFiles(req: IncomingMessage): Promise<UploadedFile[]> {
+/** Default hard cap on a single buffered file (bytes) — 25 MiB. */
+const DEFAULT_MAX_FILE_SIZE = 25 * 1024 * 1024
+/** Default cap on files per multipart request for `isArray` properties. */
+const DEFAULT_MAX_FILES = 20
+
+/** Server-side limits enforced while parsing a multipart upload. */
+interface ParseLimits {
+  /** Hard per-file byte cap. Streams exceeding it are rejected (413). */
+  maxFileSize: number
+  /** Max files per request. Excess files are rejected (400). */
+  maxFiles: number
+  /** Allowed MIME patterns (HTML `accept` syntax). Empty ⇒ no restriction. */
+  mimeTypes?: string[]
+}
+
+/**
+ * Reads every file from a multipart/form-data stream using busboy, enforcing
+ * size / count / MIME limits *as it streams* so a hostile request cannot
+ * buffer unbounded bytes into memory before any check runs.
+ */
+function parseAllFiles(req: IncomingMessage, limits: ParseLimits): Promise<UploadedFile[]> {
   return new Promise((resolve, reject) => {
     let bb: ReturnType<typeof Busboy>
     try {
-      bb = Busboy({ headers: req.headers as Record<string, string> })
+      bb = Busboy({
+        headers: req.headers as Record<string, string>,
+        limits: {
+          fileSize: limits.maxFileSize,
+          files: limits.maxFiles,
+          // The upload endpoint carries no data fields — keep them tightly
+          // bounded so field spam cannot buffer memory either.
+          fields: 10,
+          fieldSize: 100 * 1024,
+        },
+      })
     } catch {
       reject(new BadRequestException('Request is not multipart/form-data'))
       return
@@ -67,6 +100,10 @@ function parseAllFiles(req: IncomingMessage): Promise<UploadedFile[]> {
     let settled = false
     let firstError: unknown
 
+    const fail = (err: unknown): void => {
+      firstError = firstError ?? err
+    }
+
     const tryResolve = (): void => {
       if (settled || !finished || pending > 0) return
       settled = true
@@ -77,33 +114,59 @@ function parseAllFiles(req: IncomingMessage): Promise<UploadedFile[]> {
 
     bb.on('file', (_fieldname, stream, info) => {
       pending++
+      // Reject a disallowed MIME up front — don't buffer a single byte of it.
+      const mimeType = info.mimeType || 'application/octet-stream'
+      if (!mimeMatches(mimeType, limits.mimeTypes)) {
+        fail(new UnsupportedMediaTypeException(`File type "${mimeType}" is not allowed`))
+        stream.resume() // drain so busboy keeps parsing the rest of the body
+        stream.on('close', () => {
+          pending--
+          tryResolve()
+        })
+        return
+      }
       const chunks: Buffer[] = []
       stream.on('data', (chunk: Buffer) => chunks.push(chunk))
+      // Busboy emits 'limit' when the per-file byte cap is exceeded.
+      stream.on('limit', () => {
+        fail(new PayloadTooLargeException(`File exceeds the maximum size of ${limits.maxFileSize} bytes`))
+      })
       stream.on('end', () => {
-        const buffer = Buffer.concat(chunks)
-        files.push({
-          originalName: info.filename || 'upload',
-          mimeType: info.mimeType || 'application/octet-stream',
-          size: buffer.length,
-          buffer,
-        })
+        // `truncated` is set when the fileSize limit tripped mid-stream.
+        if (!(stream as { truncated?: boolean }).truncated) {
+          const buffer = Buffer.concat(chunks)
+          files.push({
+            // Sanitise before the name can steer key generation (extname /
+            // custom uploadPath) — strips separators and traversal segments.
+            originalName: sanitizeFilename(info.filename),
+            mimeType,
+            size: buffer.length,
+            buffer,
+          })
+        }
         pending--
         tryResolve()
       })
       stream.on('error', (err) => {
-        firstError = firstError ?? err
+        fail(err)
         pending--
         tryResolve()
       })
     })
 
+    // Busboy stops emitting files past the `files` limit — surface it as a 400
+    // rather than silently dropping the extras.
+    bb.on('filesLimit', () => {
+      fail(new BadRequestException(`Too many files — at most ${limits.maxFiles} allowed`))
+    })
+
     bb.on('finish', () => {
       finished = true
       tryResolve()
     })
 
     bb.on('error', (err: unknown) => {
-      firstError = firstError ?? err
+      fail(err)
       finished = true
       tryResolve()
     })
@@ -137,8 +200,20 @@ export class UploadController {
   ): Promise<UploadedFileInfo[]> {
     const { providerId, registered } = this.resolveProperty(resourceId, field)
 
-    // 1 — Parse the multipart body (collect every file).
-    const files = await parseAllFiles(req)
+    // 1 — Parse the multipart body (collect every file), enforcing size /
+    //     count / MIME limits while streaming so nothing unbounded is buffered.
+    const moduleMax = this.moduleOptions.maxFileSize ?? DEFAULT_MAX_FILE_SIZE
+    // Per-property maxSize tightens the cap but can never raise it above the
+    // module-wide hard bound.
+    const maxFileSize = Math.min(moduleMax, registered.maxSize ?? Number.POSITIVE_INFINITY)
+    const maxFiles = registered.isArray
+      ? (this.moduleOptions.maxFiles ?? DEFAULT_MAX_FILES)
+      : 1
+    const files = await parseAllFiles(req, {
+      maxFileSize,
+      maxFiles,
+      ...(registered.mimeTypes ? { mimeTypes: registered.mimeTypes } : {}),
+    })
 
     // 2 — If the property is single-value, only the first file is honoured.
     //     The frontend sends one anyway; this is a safety bound.
@@ -150,6 +225,11 @@ export class UploadController {
     const results: UploadedFileInfo[] = []
     for (const file of accepted) {
       const computedKey = registered.uploadPath ? registered.uploadPath(file.originalName) : undefined
+      // A custom `uploadPath` could still produce a traversal/absolute key —
+      // reject at the boundary (the provider also contains it defensively).
+      if (computedKey !== undefined && isUnsafeKey(computedKey)) {
+        throw new BadRequestException('Computed upload key is not allowed')
+      }
       const key = await registered.provider.upload(file, computedKey)
       // Track as pending — it will be confirmed by `new.after`/`edit.after`
       // when the form is saved, or cleaned up by the sweeper when the TTL
@@ -178,6 +258,7 @@ export class UploadController {
     @Query('key') key: string,
   ): Promise<void> {
     if (!key) throw new BadRequestException('Missing "key" query parameter')
+    if (isUnsafeKey(key)) throw new BadRequestException('Invalid "key" query parameter')
     // Validate that the resource/field is actually upload-enabled. This avoids
     // leaking the existence of arbitrary resource ids to unauthenticated callers
     // (the auth guard already requires authentication).

package/src/nest/upload.module.ts

@@ -18,6 +18,11 @@
  * The module depends on `MODERN_ADMIN` and `ModernAdminAuthGuard` being
  * available in the DI tree, which is satisfied when `ModernAdminModule.forRoot`
  * is registered with `global: true` (the recommended default).
+ *
+ * ⚠️ Single-instance: the pending-upload registry + sweeper are in-process.
+ * Behind a load balancer with ≥2 replicas the sweeper can delete a just-saved
+ * file (see `PendingUploadsRegistry` docs). The sweeper warns once at startup;
+ * pass `acknowledgeSingleInstance: true` to silence it once understood.
  */
 
 import { type DynamicModule, Module } from '@nestjs/common'

package/src/nest/upload.tokens.ts

@@ -21,4 +21,27 @@ export interface ModernAdminUploadModuleOptions {
    * just never expire).
    */
   sweepIntervalMs?: number
+  /**
+   * Hard upper bound (bytes) on a single uploaded file, applied by the
+   * multipart parser regardless of per-property `maxSize`. Files are buffered
+   * in memory, so this caps memory use per request and blocks OOM-style DoS.
+   * A property's own `maxSize` still applies when it is *smaller* than this.
+   * Default: 25 MiB.
+   */
+  maxFileSize?: number
+  /**
+   * Maximum number of files accepted in a single multipart request for an
+   * `isArray` property. Single-value properties always cap at 1. Default: 20.
+   */
+  maxFiles?: number
+  /**
+   * Suppress the single-instance startup warning.
+   *
+   * `PendingUploadsRegistry` is an in-process `Map`: behind a load balancer
+   * with ≥2 replicas the confirm/sweeper lifecycle can delete a just-saved
+   * file (see the class docs). The sweeper logs a warning once at startup to
+   * make this loud. Set `true` once you have confirmed a single-instance
+   * deployment (or accepted the risk) to silence it.
+   */
+  acknowledgeSingleInstance?: boolean
 }

package/src/path-safety.ts

@@ -0,0 +1,73 @@
+/**
+ * Path-safety helpers shared by the upload providers and the upload
+ * entry points (REST controller + GraphQL extension).
+ *
+ * Storage keys and filenames are attacker-controllable in two ways:
+ *
+ *   1. **Upload** — the client-supplied `originalName` flows into key
+ *      generation (default `uuid + extname`, or a custom `uploadPath`). A raw
+ *      name like `../../evil.sh` must never be able to steer the key outside
+ *      the intended storage space.
+ *   2. **Delete** — a `type: 'file'` property is just a string in the DB. An
+ *      attacker who can edit a record can write `../../../../etc/passwd` into
+ *      it; the next edit/delete would call `provider.delete(key)` with that
+ *      value. Without containment the local provider's `unlink` escapes the
+ *      upload directory.
+ *
+ * Defense is layered: keys are rejected at the transport boundary
+ * (`isUnsafeKey`), filenames are sanitised before they can influence a key
+ * (`sanitizeFilename`), and the local provider resolves every path against its
+ * upload directory (`resolveWithinDir`) as the authoritative backstop.
+ */
+
+import { resolve, sep } from 'node:path'
+
+/**
+ * True when `key` must be refused: empty, containing a NUL byte, absolute
+ * (POSIX `/…` or Windows `C:\…`), or containing a `..` traversal segment.
+ *
+ * Forward and back slashes are both treated as separators so a key crafted on
+ * one platform cannot escape on another. Legitimate nested keys
+ * (`avatars/2024/uuid.jpg`) and prefixes are allowed — only traversal and
+ * absolute paths are rejected.
+ */
+export function isUnsafeKey(key: unknown): boolean {
+  if (typeof key !== 'string' || key.length === 0) return true
+  if (key.includes('\0')) return true
+  const normalized = key.replace(/\\/g, '/')
+  if (normalized.startsWith('/')) return true // POSIX absolute
+  if (/^[a-zA-Z]:/.test(normalized)) return true // Windows drive-absolute
+  return normalized.split('/').some((segment) => segment === '..')
+}
+
+/**
+ * Reduce a client-supplied filename to a safe basename that cannot influence
+ * the directory a key resolves into. Strips any directory components (either
+ * separator), NUL bytes, and leading dots (so `..` / hidden-traversal names
+ * collapse). Falls back to `'upload'` when nothing safe remains.
+ */
+export function sanitizeFilename(name: unknown): string {
+  if (typeof name !== 'string' || name.length === 0) return 'upload'
+  const base = name.replace(/\\/g, '/').split('/').pop() ?? ''
+  const cleaned = base
+    .replace(/\0/g, '')
+    .replace(/^\.+/, '') // no leading dots → no bare '..' / hidden traversal
+    .trim()
+  return cleaned.length > 0 ? cleaned : 'upload'
+}
+
+/**
+ * Resolve `key` against `baseDir` and guarantee the result stays inside it.
+ * Throws when the resolved path escapes the directory (traversal / absolute
+ * key). Returns the absolute, contained path for the caller to read/write.
+ */
+export function resolveWithinDir(baseDir: string, key: string): string {
+  const base = resolve(baseDir)
+  const full = resolve(base, key)
+  if (full !== base && !full.startsWith(base + sep)) {
+    throw new Error(
+      `[modern-admin/feature-upload] refusing to access "${key}" outside the upload directory`,
+    )
+  }
+  return full
+}

package/src/pending-registry.ts

@@ -27,13 +27,28 @@
  * The registry is a process-level singleton (same pattern as
  * `UploadProviderRegistry`).
  *
+ * ⚠️ SINGLE-INSTANCE ONLY (until a shared store lands).
+ * ------------------------------------------------------
+ * This `Map` lives in one process's memory. Behind a load balancer with ≥2
+ * replicas it is UNSAFE and can lose data:
+ *
+ *   1. Replica A handles `POST /upload` → `track(key)` in A's map only.
+ *   2. Replica B handles the form save → `confirm(key)` is a no-op (B never
+ *      saw the pending entry).
+ *   3. A's sweeper still considers the key pending; once the TTL elapses it
+ *      DELETES the file the record now references → broken/missing upload.
+ *
+ * The provider *registry* key is deterministic (`up_<resourceId>_<prop>`), so
+ * uploads still ROUTE correctly across replicas — but the pending lifecycle
+ * above does not. Run the upload feature single-instance, OR set a large
+ * `pendingTtlMs` to widen the confirm window, until the roadmap item below
+ * replaces this with a shared store.
+ *
  * TODO(roadmap): swap the in-process `Map` for a Redis-backed store and move
  * the sweeper driver (`UploadSweeperService`) onto BullMQ. This is required
  * for multi-instance deployments where one Nest replica serves the upload
- * request and a different replica processes the form submission — without a
- * shared store the second replica would not see the pending entry, the
- * confirm hook would no-op, and the file would be swept on the originator.
- * BullMQ also gives us crash-safe scheduling and retries.
+ * request and a different replica processes the form submission. BullMQ also
+ * gives us crash-safe scheduling and retries.
  */
 
 import { UploadProviderRegistry } from './registry.js'

package/src/providers/local.ts

@@ -10,8 +10,9 @@
  */
 
 import { mkdir, writeFile, unlink } from 'node:fs/promises'
-import { join, extname, dirname } from 'node:path'
+import { extname, dirname } from 'node:path'
 import { uuidv7 } from '@modern-admin/core'
+import { resolveWithinDir } from '../path-safety.js'
 import type { IUploadProvider, UploadedFile } from '../types.js'
 
 export interface LocalUploadOptions {
@@ -36,7 +37,9 @@ export class LocalUploadProvider implements IUploadProvider {
 
   async upload(file: UploadedFile, key?: string): Promise<string> {
     const resolvedKey = key ?? `${uuidv7()}${extname(file.originalName)}`
-    const dest = join(this.options.uploadDir, resolvedKey)
+    // Contain the key inside uploadDir — refuses traversal/absolute keys
+    // (e.g. a malicious `uploadPath` or `../../evil.sh`).
+    const dest = resolveWithinDir(this.options.uploadDir, resolvedKey)
     // Create the full directory tree (handles nested keys like 'avatars/2024/01/uuid.jpg').
     await mkdir(dirname(dest), { recursive: true })
     await writeFile(dest, file.buffer)
@@ -49,8 +52,17 @@ export class LocalUploadProvider implements IUploadProvider {
   }
 
   async delete(key: string): Promise<void> {
+    let dest: string
     try {
-      await unlink(join(this.options.uploadDir, key))
+      // Refuse to unlink anything outside uploadDir — a `type: 'file'` value
+      // is an arbitrary DB string, so `key` may be attacker-controlled
+      // (`../../../../app/src/main.ts`). Never delete outside the directory.
+      dest = resolveWithinDir(this.options.uploadDir, key)
+    } catch {
+      return
+    }
+    try {
+      await unlink(dest)
     } catch (err) {
       if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err
     }

package/src/providers/s3.ts

@@ -28,6 +28,7 @@
 
 import { extname } from 'node:path'
 import { uuidv7 } from '@modern-admin/core'
+import { isUnsafeKey } from '../path-safety.js'
 import type { IUploadProvider, UploadedFile } from '../types.js'
 
 export interface S3UploadOptions {
@@ -120,6 +121,14 @@ export class S3UploadProvider implements IUploadProvider {
   }
 
   async upload(file: UploadedFile, key?: string): Promise<string> {
+    // Reject traversal / absolute keys before they reach the bucket. Keys
+    // legitimately contain `/` separators (prefixes), but never `..` or a
+    // leading slash.
+    if (key !== undefined && isUnsafeKey(key)) {
+      throw new Error(
+        `[modern-admin/feature-upload] refusing to upload with unsafe key "${key}"`,
+      )
+    }
     const c = await this.client()
     const ext = extname(file.originalName)
     const prefix = this.options.prefix ? `${this.options.prefix}/` : ''
@@ -163,6 +172,11 @@ export class S3UploadProvider implements IUploadProvider {
   }
 
   async getUrl(key: string): Promise<string> {
+    if (isUnsafeKey(key)) {
+      throw new Error(
+        `[modern-admin/feature-upload] refusing to build a URL for unsafe key "${key}"`,
+      )
+    }
     if (this.options.signed) {
       return this.signedUrl(key)
     }
@@ -170,6 +184,9 @@ export class S3UploadProvider implements IUploadProvider {
   }
 
   async delete(key: string): Promise<void> {
+    // A `type: 'file'` value is an arbitrary DB string — never issue a
+    // DeleteObject for a traversal/absolute key.
+    if (isUnsafeKey(key)) return
     try {
       const sdk = await import('@aws-sdk/client-s3' as string)
       const c = await this.client()

package/src/registry.ts

@@ -19,6 +19,14 @@ export interface RegisteredUploadConfig {
   uploadPath?: (filename: string) => string
   /** True for multi-file properties — controller will accept N files per request. */
   isArray?: boolean
+  /**
+   * Allowed MIME patterns (HTML `accept` syntax). Enforced server-side by the
+   * upload controller / GraphQL resolver — a request whose file declares a
+   * non-matching type is rejected. `undefined`/empty means no restriction.
+   */
+  mimeTypes?: string[]
+  /** Maximum accepted file size in bytes. Enforced server-side (per file). */
+  maxSize?: number
 }
 
 const _registry = new Map<string, RegisteredUploadConfig>()

package/src/types.ts

@@ -83,10 +83,18 @@ export interface UploadPropertyConfig {
   /**
    * Allowed MIME type patterns (same syntax as the HTML `accept` attribute).
    * Examples: `['image/*']`, `['image/jpeg', 'application/pdf']`.
-   * Enforcement is advisory on the frontend; the controller does not re-validate.
+   * Enforced both on the frontend (UX) and server-side — the upload controller
+   * / GraphQL resolver rejects a file whose declared type does not match. The
+   * server match is on the *declared* Content-Type (defense-in-depth, not
+   * content sniffing).
    */
   mimeTypes?: string[]
-  /** Maximum upload size in bytes. Advisory (frontend warning only). */
+  /**
+   * Maximum upload size in bytes. Enforced server-side per file (the multipart
+   * parser aborts an oversized stream) in addition to the frontend warning.
+   * A module-wide hard cap (`ModernAdminUploadModule.forRoot({ maxFileSize })`,
+   * default 25 MiB) always applies on top, even when this is unset.
+   */
   maxSize?: number
   /**
    * Treat the property as an array of file keys (multi-file upload).

package/src/upload-feature.ts

@@ -26,7 +26,7 @@
  * })
  */
 
-import { uuidv7, type ActionRequest, type ActionResponse, type FeatureFn, type ResourceOptions } from '@modern-admin/core'
+import { appendAfterHook, uuidv7, type ActionRequest, type ActionResponse, type FeatureFn, type ResourceOptions } from '@modern-admin/core'
 import type { UploadFeatureOptions, UploadPropertyConfig } from './types.js'
 import { UploadProviderRegistry } from './registry.js'
 import { PendingUploadsRegistry } from './pending-registry.js'
@@ -44,25 +44,6 @@ type HookFn = (
   context: unknown,
 ) => ActionResponse | Promise<ActionResponse>
 
-/** Normalise a hook value (fn | fn[] | undefined) into an array. */
-function toArray(hook: unknown): HookFn[] {
-  if (!hook) return []
-  return Array.isArray(hook) ? (hook as HookFn[]) : [hook as HookFn]
-}
-
-/**
- * Merge `after` hooks from an existing action override with new hooks,
- * producing an array that runs all of them in order.
- * If `existing` already defines `after`, the new hooks are appended.
- */
-function mergeAfterHook(
-  existing: Record<string, unknown> | undefined,
-  newHook: HookFn,
-): HookFn[] {
-  const existing_after = toArray(existing?.after)
-  return [...existing_after, newHook]
-}
-
 // ─── Value helpers ────────────────────────────────────────────────────────────
 
 /** Return non-empty file keys for the given value (handles single + array). */
@@ -77,20 +58,34 @@ function toKeys(value: unknown): string[] {
 // ─── Feature function ─────────────────────────────────────────────────────────
 
 export function uploadFeature(options: UploadFeatureOptions): FeatureFn {
-  // Register configs immediately — before the FeatureFn is called.
-  const registered = new Map<string, RegisteredProp>()
-
-  for (const [propPath, config] of Object.entries(options.properties)) {
-    const providerId = `up_${uuidv7().replace(/-/g, '')}`
-    UploadProviderRegistry.register(providerId, {
-      provider: config.provider,
-      uploadPath: config.uploadPath,
-      isArray: config.isArray ?? false,
-    })
-    registered.set(propPath, { providerId, config })
-  }
+  // Precompute per-property config plus a process-local fallback id, used only
+  // when the FeatureFn is invoked without a resource (e.g. unit tests calling
+  // it directly). In production the id is derived from `resource.id()` below.
+  const props = Object.entries(options.properties).map(([propPath, config]) => ({
+    propPath,
+    config,
+    fallbackId: `up_${uuidv7().replace(/-/g, '')}`,
+  }))
+
+  return (resourceOptions: ResourceOptions, resource?): ResourceOptions => {
+    // Register providers with a DETERMINISTIC id derived from the resource id
+    // + property path. Every replica behind a load balancer computes the same
+    // id, so a property served by replica A resolves on replica B's registry
+    // (a per-process UUID would 500 on the "wrong" replica). Registration
+    // happens here (at bootstrap decorate time), before any request is served.
+    const registered = new Map<string, RegisteredProp>()
+    for (const { propPath, config, fallbackId } of props) {
+      const providerId = resource ? `up_${resource.id()}_${propPath}` : fallbackId
+      UploadProviderRegistry.register(providerId, {
+        provider: config.provider,
+        uploadPath: config.uploadPath,
+        isArray: config.isArray ?? false,
+        ...(config.mimeTypes ? { mimeTypes: config.mimeTypes } : {}),
+        ...(config.maxSize != null ? { maxSize: config.maxSize } : {}),
+      })
+      registered.set(propPath, { providerId, config })
+    }
 
-  return (resourceOptions: ResourceOptions): ResourceOptions => {
     // --- Property overrides ---
     const propOverrides: ResourceOptions['properties'] = {}
     for (const [propPath, { providerId, config }] of registered) {
@@ -184,15 +179,15 @@ export function uploadFeature(options: UploadFeatureOptions): FeatureFn {
     const actionOverrides = {
       new: {
         ...existingNew,
-        after: mergeAfterHook(existingNew, newAfterHook),
+        after: appendAfterHook(existingNew, newAfterHook),
       },
       edit: {
         ...existingEdit,
-        after: mergeAfterHook(existingEdit, editAfterHook),
+        after: appendAfterHook(existingEdit, editAfterHook),
       },
       delete: {
         ...existingDelete,
-        after: mergeAfterHook(existingDelete, deleteAfterHook),
+        after: appendAfterHook(existingDelete, deleteAfterHook),
       },
     } as ResourceOptions['actions']