fix: make media uploads reliable across storage backends

[khoinguyenpham04]

What does this PR do?

Fixes media uploads for storage backends, including native Cloudflare R2 bindings, that cannot generate signed upload URLs. The upload negotiation endpoint now returns an authenticated same-origin streaming endpoint in that case, while preserving direct signed uploads for S3-compatible storage.

The upload lifecycle is hardened end to end:

• streams request bodies to storage without buffering full files in Worker memory;
• validates MIME type and exact byte length, including zero-byte files;
• publishes unique upload-attempt keys atomically so concurrent uploads cannot overwrite or confirm different content;
• derives hashes from stored/uploaded bytes and only uses compatible MIME type and size matches for deduplication;
• makes confirmation idempotent and conditionally transitions only pending rows;
• atomically deletes abandoned pending rows before removing their returned storage keys, preventing cleanup from deleting newly confirmed media;
• cleans stale upload attempts and safely releases downloaded storage streams;
• skips server-side image placeholders above the bounded processing limit.

Includes the additive upload-attempt migration, OpenAPI/schema updates, release notes, architecture documentation, and regression coverage for the admin client, upload routes, storage, SQLite, PostgreSQL, and D1 behavior.

Closes #2256
Closes #2265

Type of change

• Bug fix
• Feature (requires maintainer-approved Discussion)
• Refactor (no behavior change)
• Translation
• Documentation
• Performance improvement
• Tests
• Chore (dependencies, CI, tooling)

Checklist

• I have read CONTRIBUTING.md
• pnpm typecheck passes
• pnpm lint passes
• pnpm test passes (or targeted tests for my change)
• pnpm format has been run
• I have added/updated tests for my changes (if applicable)
• User-visible strings in the admin UI are wrapped for translation (if applicable). Do not include messages.po changes except in translation PRs — a workflow extracts catalogs on merge to main. (N/A: no new user-visible admin strings.)
• I have added a changeset (if this PR changes a published package)
• New features link to an approved Discussion: https://github.com/emdash-cms/emdash/discussions/... (N/A: this is a bug fix.)

AI-generated code disclosure

• This PR includes AI-generated code — model/tool: OpenAI Codex (GPT-5)

Screenshots / test output

No visual UI changes.

• Focused core regression suites: 115 passed.
• Final media-focused core suites: 35 passed.
• Admin browser suite: 105 files and 1,247 tests passed.
• Core and admin typechecks passed.
• Type-aware lint and formatting checks passed.
• Full core suite: 5,061 passed; one unrelated existing macOS path-canonicalization assertion differs on /var/... versus /private/var/....

---

Try this PR

Open a fresh playground →

A full working EmDash site, deployed from this branch. Each visit gets its own session-scoped sandbox: no login needed and no shared state. Try the admin, edit content, hit the public site.

_{Tracks fix/media-upload-2265. Updated automatically when the playground redeploys.}

[changeset-bot]

🦋 Changeset detected

Latest commit: ecdf0b2

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 17 packages

Name	Type
emdash	Patch
@emdash-cms/admin	Patch
@emdash-cms/cloudflare	Patch
@emdash-cms/sandbox-workerd	Patch
@emdash-cms/plugin-mcp-smoke	Patch
@emdash-cms/fixture-perf-site	Patch
@emdash-cms/perf-demo-site	Patch
@emdash-cms/cache-demo-site	Patch
@emdash-cms/do-demo-site	Patch
@emdash-cms/do-solo-demo-site	Patch
@emdash-cms/auth	Patch
@emdash-cms/blocks	Patch
@emdash-cms/gutenberg-to-portable-text	Patch
@emdash-cms/x402	Patch
create-emdash	Patch
@emdash-cms/auth-atproto	Patch
@emdash-cms/plugin-embeds	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	docs	ecdf0b2	Jul 30 2026, 11:21 AM

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	emdash-playground	ecdf0b2	Jul 30 2026, 11:20 AM

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	emdash-demo-do	ecdf0b2	Jul 30 2026, 11:21 AM

[github-actions]

Scope check

This PR changes 2,626 lines across 32 files. Large PRs are harder to review and more likely to be closed without review.
This PR spans 4 different areas (area/core, area/admin, area/docs, area/cloudflare). Consider breaking it into smaller, focused PRs.

If this scope is intentional, no action needed. A maintainer will review it. If not, please consider splitting this into smaller PRs.

See CONTRIBUTING.md for contribution guidelines.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	emdash-demo-cache	ecdf0b2	Jul 30 2026, 11:21 AM

[pkg-pr-new]

Open in StackBlitz

@emdash-cms/admin

npm i https://pkg.pr.new/@emdash-cms/admin@2273

@emdash-cms/auth

npm i https://pkg.pr.new/@emdash-cms/auth@2273

@emdash-cms/auth-atproto

npm i https://pkg.pr.new/@emdash-cms/auth-atproto@2273

@emdash-cms/blocks

npm i https://pkg.pr.new/@emdash-cms/blocks@2273

@emdash-cms/cloudflare

npm i https://pkg.pr.new/@emdash-cms/cloudflare@2273

@emdash-cms/contentful-to-portable-text

npm i https://pkg.pr.new/@emdash-cms/contentful-to-portable-text@2273

emdash

npm i https://pkg.pr.new/emdash@2273

create-emdash

npm i https://pkg.pr.new/create-emdash@2273

@emdash-cms/gutenberg-to-portable-text

npm i https://pkg.pr.new/@emdash-cms/gutenberg-to-portable-text@2273

@emdash-cms/plugin-cli

npm i https://pkg.pr.new/@emdash-cms/plugin-cli@2273

@emdash-cms/plugin-types

npm i https://pkg.pr.new/@emdash-cms/plugin-types@2273

@emdash-cms/registry-client

npm i https://pkg.pr.new/@emdash-cms/registry-client@2273

@emdash-cms/registry-lexicons

npm i https://pkg.pr.new/@emdash-cms/registry-lexicons@2273

@emdash-cms/registry-verification

npm i https://pkg.pr.new/@emdash-cms/registry-verification@2273

@emdash-cms/sandbox-workerd

npm i https://pkg.pr.new/@emdash-cms/sandbox-workerd@2273

@emdash-cms/x402

npm i https://pkg.pr.new/@emdash-cms/x402@2273

@emdash-cms/plugin-ai-moderation

npm i https://pkg.pr.new/@emdash-cms/plugin-ai-moderation@2273

@emdash-cms/plugin-atproto

npm i https://pkg.pr.new/@emdash-cms/plugin-atproto@2273

@emdash-cms/plugin-audit-log

npm i https://pkg.pr.new/@emdash-cms/plugin-audit-log@2273

@emdash-cms/plugin-color

npm i https://pkg.pr.new/@emdash-cms/plugin-color@2273

@emdash-cms/plugin-embeds

npm i https://pkg.pr.new/@emdash-cms/plugin-embeds@2273

@emdash-cms/plugin-field-kit

npm i https://pkg.pr.new/@emdash-cms/plugin-field-kit@2273

@emdash-cms/plugin-forms

npm i https://pkg.pr.new/@emdash-cms/plugin-forms@2273

@emdash-cms/plugin-webhook-notifier

npm i https://pkg.pr.new/@emdash-cms/plugin-webhook-notifier@2273

commit: ecdf0b2

[emdashbot]

This is the right change for the stated problem. Uploading to storage backends that cannot produce signed URLs — especially the native Cloudflare R2 binding — needs a same-origin streaming fallback, and the PR adds that path without breaking the S3-style signed-URL flow. The atomic publish-via-upload-attempt table, the cleanup ordering (DB row deleted before storage object), and the size/MIME/hash guards are all sound and well covered by tests.

I reviewed the full diff, the changed routes, the repository/Clean-up code, the admin client, the migration, the OpenAPI updates, and the regression tests. No blocking logic bug, regression, security issue, or AGENTS.md convention violation stood out. The only things I noticed are two comment blocks that drift into PR-style narrative rather than code explanations — worth tightening before merge, but not blockers.

---

Findings

• [suggestion] packages/core/src/astro/routes/api/media/[id]/confirm.ts:187-194

  This comment block narrates the PR’s rationale ("the signed-URL flow uploads directly to storage, so this confirm is the only point at which the server sees the bytes", "buffering a large original into a Worker heap to compute a 32px blurhash would OOM"). It repeats design trade-offs that belong in the PR description rather than the code. Per AGENTS.md, comments should explain non-obvious invariants, not re-state the change proposal.

  		// LQIP is best-effort; oversized images skip server-side placeholders.
  

• [suggestion] packages/admin/src/lib/api/media.ts:16-19

  The constant name already says what it is; the surrounding JSDoc justifies it by pointing at a remote schema and asks readers to "keep in sync". Cross-file notes that require manual synchronization age quickly and violate the comment-discipline rule against justification/narrative. If both sides need the same limit, export it from a shared package; otherwise the name is enough.

  export const MEDIA_SEARCH_MAX_LENGTH = 200;
  

[emdashbot]

This is the right change for the stated problem and the latest revision is clean. The same-origin streaming fallback lets native R2/local storage work without signed URLs, while the S3 signed-URL flow is preserved. The atomic publishPendingStorageKey update, the upload-attempt cleanup table, and the delete-before-storage cleanup ordering all prevent the races this PR targets. MIME-type/size guards on deduplication, optional client hashing, and the 8 MiB LQIP cap are sensible.

I re-read the full diff plus the changed routes, repository, cleanup code, admin client, migration, OpenAPI document, and regression tests. Both comment-style findings from the previous review are fixed: confirm.ts now has only the concise LQIP invariant, and the stale cross-file JSDoc on MEDIA_SEARCH_MAX_LENGTH is gone.

No new blocking logic bug, regression, security issue, or AGENTS.md convention violation stands out. The OpenAPI schema for POST /media/upload-url correctly models the union of upload-target and existing-media responses, the migration indexes follow naming conventions, authorization uses the existing media:upload/media:edit_any permissions, and the extensive concurrency/race test coverage exercises the publication, retry, cleanup, and deletion paths.

[github-actions]

Overlapping PRs

This PR modifies files that are also changed by other open PRs:

• feat(media): show where media is used #2225 (3 shared files)
• feat(admin): explicit collection order in the sidebar #2267 (5 shared files)
• feat(content): filter indexed custom fields #2213 (5 shared files)
• feat(content): support indexed custom field sorting #2212 (4 shared files)
• feat(admin): allow trusted plugins to add content list columns #2195 (4 shared files)
• feat(admin): show configured fields in content lists #2194 (4 shared files)
• feat(core): configurable titleField and dateField per collection #1973 (4 shared files)
• feat: reference field type (storage-less edges + admin UI) #1928 (4 shared files)
• fix: delegate HEIC media to configured image services #2175 (3 shared files)
• Fix R2 publicUrl being ignored for API, local provider, plugins, settings (follow-up to #675) #729 (4 shared files)

This may cause merge conflicts or duplicated work. A maintainer will coordinate.

[emdashbot]

Re-review: no new blockers

This is the right change for the stated problem. The same-origin streaming fallback lets native R2/local storage work without signed URLs, while the S3 signed-URL flow is preserved. The atomic publishPendingStorageKey update, the upload-attempt cleanup table, and the delete-before-storage cleanup ordering all prevent the races this PR targets. MIME-type/size guards on deduplication, optional client hashing, and the 8 MiB LQIP cap remain sensible.

I re-read the full diff plus the changed routes, repository, cleanup code, admin client, migration, OpenAPI document, and regression tests. Both comment-style findings from the previous review are still fixed: confirm.ts has only the concise LQIP invariant, and the stale cross-file JSDoc on MEDIA_SEARCH_MAX_LENGTH is gone.

No new blocking logic bug, regression, security issue, or AGENTS.md convention violation stands out in this revision. The OpenAPI schema for POST /media/upload-url continues to model the union of upload-target and existing-media responses correctly, migration indexes follow naming conventions, authorization uses the existing media:upload/media:edit_any permissions, and the concurrency/race test coverage exercises the publication, retry, cleanup, and deletion paths.

LGTM.