Add @uppy/s3 provider plugin + Companion S3 provider (prototype)

[kvz]

What

Browse and manage S3-compatible object storage (AWS S3, Cloudflare R2, MinIO, Transloadit Storage) from the Dashboard, on the same footing as Box/Dropbox/WebDAV — the same widget that powers the Console File Library (content#5810) and that customers can embed.

1. @uppy/s3 + Companion S3 provider — simple-auth ({ bucket, prefix } session), ListObjectsV2 + pagination, download; reuses Companion's s3 options so R2/MinIO is configuration only. Safe by default: browsing needs s3.browsableBuckets / COMPANION_AWS_BROWSABLE_BUCKETS, mutations additionally s3.mutableBuckets / COMPANION_AWS_MUTABLE_BUCKETS.
2. Mutations + actions slot — Companion Provider gains deleteItem/moveItem/createFolder (+ POST /:provider/mutate/*): moves never overwrite, folders cannot move into themselves, non-empty folders cannot be deleted, folder moves walk the tree with delimiter listings and copy before deleting (≤ 1000 entries). ProviderViews gains per-item "⋯" actions (keyboard-navigable native popover, one open at a time), toolbarActions, refreshCurrentFolder(), and native <dialog> prompt()/confirm() — no window.prompt. @uppy/s3 ships Rename/move…, Delete, New folder with toasts.
3. @uppy/transloadit-storage — TransloaditStorage extends S3: workspace slug as bucket (dev) or a server-issued grant; Copy Smart CDN URL via a getSmartCdnUrl(key) callback (sign on your server — the plugin holds no credentials); storeUploads (an installed @uppy/transloadit stores uploads into the open folder; you sign via signAssembly; buildStoreAssemblyParams/createStoreAssemblyOptions exported); Download; reopenAfterUpload; "Storing…" instead of "Encoding…".
4. Manager mode (mode: 'manager', the standalone default): clicking a file opens a styled detail modal (preview via getPreviewUrl, size/type/date, the same actions as the "⋯" menu — defined once); checkboxes hide behind a Select multiple toggle with a bulk Move…/Delete footer; S3.openFolderPath(key) gives embedders typed deep-link folder restores (serialized with the panel's own first load); onUploadRequest lets the host open its own upload UI (the Console opens a Dashboard modal with remote sources) and S3.refreshListing() re-lists afterwards. Picker mode is byte-identical to before: every new capability is behind an option with a no-op default.
5. Trust model: server-issued storage grants. POST /s3/simple-auth accepts { form: { grant } }, an HS256 JWT your backend mints (s3.grantSecret / COMPANION_AWS_GRANT_SECRET). Companion re-checks bucket/prefix/scopes/expiry on every operation (expired → 401 → @uppy/s3 re-grants via getGrant() and retries once); read-only grants hide mutations; once a secret is set, client-supplied buckets are refused unless s3.allowBucketAuth (dev). The grant wire contract (claims, decode, HS256 mint/verify) lives in @transloadit/utils@4.8.0 (decodeStorageGrant in the browser, verifyStorageGrant in Companion) — one codec shared with api2's POST /storage/grants and the Console.
6. Theming: --uppy-color-primary(-hover), --uppy-color-secondary, --uppy-color-danger, --uppy-font-family CSS custom properties, falling back to the current palette.

Tested

Companion unit tests 135/135 (S3 provider incl. grants, mutation gating, collisions, folder moves), @uppy/s3 browser tests 10/10 with msw (auto-connect, stale session, menu, dialogs, rename/move/delete → exact Companion requests), @uppy/transloadit-storage known-answer signing tests, core/dashboard suites green, typecheck + Biome clean, changesets added. End to end: the Console File Library e2e suite (7/7) and Opus user-test PASS on all four DAM use-case tutorials — after every round on this branch (regression recipe: content repodocs/dam-use-case-validation.md).

Notes for reviewers

• The native <dialog>/popover primitives feature-detect down to the iOS ≥ 13.4 end of browserslist; menu positioning stays JS (CSS anchor positioning is not in Firefox stable).
• mockCompanion (@uppy/s3/mockCompanion) is one in-memory S3 provider used by this package's browser tests and the Console's Playwright suite — no separate fakes.
• Fixed here because this branch surfaced it: generic build:css in turbo.json missed dependsOn: ["^build:css"], so dashboard css could serve a stale cache when only core's provider-views scss changed.

Known follow-ups (not in this PR)

Docs / uppy bundle inclusion; image thumbnails in rows (natural fit: builtin/storage-preview signed URLs); a supported initialPanel option (embedders call showPanel() and get a one-frame source-chooser flash); duplicate Informers on app-level errors; #939393 secondary text fails WCAG AA (measured 3.07:1 / 2.55:1 — #666 fixes it); 44px mobile touch targets; a rare post-upload /s3/list 401 in rapid fresh contexts (regrant-retry may race reopenAfterUpload); Companion providers still carrying private withErrorHandling copies (parked: fold into a provider base-class PR only if all eight migrate together).

History

Built in reviewed iterations (provider → mutations → trust model → manager mode → DRY): details in the commit messages and the converged LoC/DRY plan ~/code/dam-loc-round4-proposal.md. Every round ended with the full e2e + use-case regression suite green.

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: 984eb72

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

This PR includes changesets to release 6 packages

Name	Type
@uppy/companion	Minor
@uppy/core	Minor
@uppy/s3	Minor
@uppy/transloadit-storage	Minor
@uppy/locales	Minor
uppy	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

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​@​transloadit/​utils@​4.8.0

View full report

[remcohaszing]

I feel like these functions should be merged, the function should be named readString, and the implementation should be the one from readNullableString.

Whether or not an empty string is accepted, can be based on a booliness check.

const value = readString(object, 'key')

if (!value) {
  // value is null or an empty string
}

if (value == null) {
  // value is null
}

I also prefer to avoid null, but this hasn’t been applied to Uppy so far.

[remcohaszing]

export type A = B creates a new type A, that is equivalent of B with default generic options.

Typically, a better approach is something like:

export type { B as A}

But should we even have the type S3GrantScope at all?

[remcohaszing]

I could be wrong, but it looks like this yields a status 200 response with a body of {"ok": false, "message": "…"}. Is this correct? If so, I think we should return a proper status code instead.

[kvz]

Not quite — parsed.ok === false goes through res.status(400).json(...) two lines up; the res.json(await run(...)) is the success path. The ParsedInput union is only the parser's return shape, not the HTTP body.

[remcohaszing]

You can’t depend on prototype names (such as error names). They may be different if minified. This is also prone to bugs due to internal refactors.

It’s better to use an instanceof check.

[remcohaszing]

I noticed below that you default these values to an empty array. There’s a nice formal JSDoc notation to communicate this.

Suggested change

	/**
	* Buckets that the S3 *provider* (browsing/importing files from S3 in the
	* Dashboard) is allowed to list and download from. Use `['*']` to allow any
	* bucket the credentials can access (e.g. when an upstream proxy already
	* enforces authorization). Unset/empty disables S3 browsing entirely.
	*/
	browsableBuckets?: string[] | undefined
	/**
	* Buckets the S3 provider may *change* (delete, rename/move, create
	* folders) from the Dashboard. Separate from `browsableBuckets` so a
	* read-only browser is the default; `['*']` allows every browsable bucket.
	*/
	mutableBuckets?: string[] | undefined
	/**
	* Buckets that the S3 *provider* (browsing/importing files from S3 in the
	* Dashboard) is allowed to list and download from. Use `['*']` to allow any
	* bucket the credentials can access (e.g. when an upstream proxy already
	* enforces authorization). Unset/empty disables S3 browsing entirely.
	*
	* @default []
	*/
	browsableBuckets?: string[] | undefined
	/**
	* Buckets the S3 provider may *change* (delete, rename/move, create
	* folders) from the Dashboard. Separate from `browsableBuckets` so a
	* read-only browser is the default; `['*']` allows every browsable bucket.
	*
	* @default []
	*/
	mutableBuckets?: string[] | undefined

[remcohaszing]

Let’s stick to the default include patterns to avoid needsless complexity in the configuration.

Suggested change

include: ['src/**/*.test.{ts,tsx}'],

[remcohaszing]

Why is this cast to never? A return type of never means the function always throws.

[remcohaszing]

Can you revoke object URLs while they’re still in use? If so, TIL.

[remcohaszing]

IMO the void keyword doesn’t really add anything useful (ever).

Suggested change

	void this.view.refreshCurrentFolder()
	this.view.refreshCurrentFolder()

[remcohaszing]

Suggested change

"types": "types/index.d.ts",

[kvz]

Thanks for the thorough pass, @remcohaszing. Addressed in two commits: 012983f applies your suggestion blocks as-is (co-authored)