sanitizeFilename is not pluggable — causes drift between storage adapters and the DB

[lcnogueira]

Summary

sanitizeFilename in payload/shared is invoked at several points in the upload pipeline (signed-URL handlers in storage adapters, server-side adapter upload paths, core document writes) and is not user-configurable. Projects that need custom filename normalization end up reimplementing it in collection hooks, which run at a different point in the pipeline than the storage adapter's call — and the two can drift, producing 404s when the DB filename no longer matches the storage key.

A real bug this caused

We recently debugged a production incident where users could not download files whose names contained mixed casing or non-alphanumeric characters. Root cause was a drift between two sanitizers:

• We had a beforeOperation hook on each upload collection that lowercased filenames and stripped non-alphanumeric characters.
• We had recently enabled clientUploads: true on @payloadcms/storage-s3.

With clientUploads: true, the admin UI first POSTs to /api/storage-s3-generate-signed-url, and the plugin handler calls sanitizeFilename(filename) to build the S3 object key. The document-create request to /api/<collection> comes second, and our hook ran only there. sanitizeFilename is case-preserving; our hook was not. For any filename not already invariant under both, the S3 key and the DB filename diverged, and downloads 404'd — the DB lookup succeeded, but the S3 fetch missed (keys are case-sensitive).

We "fixed" it by deleting our hook entirely. That works only because we didn't actually need the custom transformation. Any user who does need it is stuck in the same trap: reimplement consistently across every write path, or give up.

Proposed change

Make filename sanitization pluggable, per upload collection, with the invariant that the built-in sanitizer always runs after the user's formatter. The user can shape, but cannot produce, an unsafe storage key.

// conceptual
upload: {
  formatFilename?: (
    filename: string,
    args: {
      collectionSlug: string
      req: PayloadRequest
      mimeType: string
      filesize: number
    },
  ) => string | Promise<string>
}

Pseudocode for every call site:

const formatted = formatter ? await formatter(filename, ctx) : filename
const storageKey = sanitizeFilename(formatted) // always last

Two possible layers — asking for a steer

(a) payload/shared + payload core. Make sanitizeFilename pluggable at the upload-collection level in core. Every storage adapter (storage-s3, storage-gcs, storage-azure, storage-vercel-blob, filesystem) inherits the feature with zero changes. The drift-between-adapters-and-DB bug class is resolved once: there is only ever one sanitizer in the system, so the two sides literally cannot disagree.

(b) @payloadcms/storage-s3 only. Add formatFilename as a per-collection option. The plugin reads the formatter in getGenerateSignedURLHandler and injects a beforeOperation hook at config-transform time so the same formatter runs on the DB write path. Both paths route through a single internal helper (applyFormatFilename) to make drift structurally impossible within the plugin. Narrower, faster to ship, but doesn't help other adapters.

Our preference is (a) for the bug-class reason — the same trap is sitting dormant in every other adapter today. We understand (b) may be more palatable depending on appetite for changes in payload/shared.

A concrete use case

The case we have in mind is URL-friendliness: replacing spaces with dashes, normalizing unicode, stripping characters that would otherwise need URL-encoding in the browser. Built-in sanitizeFilename correctly leaves these as-is — they're valid storage keys — so in the clientUploads flow we end up with object keys that work but produce brittle, ugly URLs.

"Why not just improve sanitizeFilename by default?"

We considered this and don't think it's sufficient:

• URL conventions are project-specific. Some teams want kebab-case, some snake_case; some lowercase, some preserve case; some strip accents, some transliterate them. Payload core can't pick one "right" default without breaking someone.
• Pluggability also covers legitimately ctx-dependent cases (tenant or user-ID prefixes for cross-tenant isolation, deterministic renames for cache-busting) that the default sanitizer cannot and should not handle.
• Even if core improved the default, the drift-between-sides problem remains latent for any user who wants to override it — exactly the trap we fell into.

Safety invariant

The built-in sanitizer always runs after the user's formatter, at every call site. This option introduces no new way to corrupt storage keys.

What we'd like from you

A steer on which layer (a or b) you'd be willing to accept, before we open a PR. We're happy to draft the implementation once we know the layer.