Authorization
The gateway is deny-by-default. One authorize hook decides who can do what, and scopes every key - the single most important thing to get right.
Exposing download, list, delete, and move to the browser is a large attack surface. The gateway is deny-by-default: with no authorize and no operations, only capabilities answers and every other verb returns 403.
You open it up with one hook.
createFilesRouter({
files,
authorize: async ({ operation, key, req }) => {
const session = await auth(req);
if (!session) {
throw new FilesError("Unauthorized", "sign in"); // → 401
}
return { keyPrefix: `users/${session.id}/` }; // scope every key to this user
},
});
authorize runs on every request except the proxy-upload PUT of a keyless upload. That request carries the HMAC token presign minted, and the token is what authorizes it, since presign already ran authorize as "upload". It is a bearer token, like a presigned URL: whoever holds it can write the one key presign minted (within the size and type it binds), at the origin, path, and query it was minted under, until it expires, and nothing else. Because that PUT runs no authorize and the browser client sends it without your headers, a per-request files factory must choose the instance from the URL, never from a cookie or header (see Multiple buckets). The complete step that follows does run authorize, and refuses a token whose key lies outside the calling request’s keyPrefix, so one tenant can’t complete another tenant’s upload or read its stored metadata. The token is signed, not encrypted, so its payload (including the minted key) is readable by whoever holds it. Throw to deny — a FilesError maps to its status (Unauthorized → 401, ReadOnly → 403, …). Return a constraint object to allow, optionally narrowing what the caller can do. Return nothing (void) to allow as-is.
The context
authorize(ctx: {
operation: FilesOperation; // "download" | "upload" | "delete" | "list" | …
req: Request; // cookies, headers, session live here
key?: string; // single-key ops (client-supplied, pre-prefix)
keys?: string[]; // bulk ops
from?: string; to?: string; // copy / move
// Parsed op params: url → { expiresIn }; signedUploadUrl → { expiresIn,
// maxSize?, minSize? }; restoreVersion → { versionId }; upload: presign →
// { files: [{ name, size?, type }], expiresIn? }, the keyed PUT →
// { contentType?, size? }, complete → {}; {} for the rest.
params: Readonly<Record<string, unknown>>;
})
operation is the coarse verb, so one predicate covers the bulk and byte variants too (a head-many request authorizes as "head"; presign/complete/the upload PUT all authorize as "upload"). The upload params are what the client declared, enough for a per-user quota or type gate. The presign token then holds the upload to the declared size (capped by maxUploadSize): the proxy PUT and complete refuse a body larger than what authorize approved, so understating the size can’t get past a quota. A client that doesn’t know a file’s size omits size, and that upload is held to maxUploadSize alone; refuse a missing size here if your quota needs one. A content type that isn’t exactly one media type (image/png, text/html) is refused with 422 before authorize runs.
The constraint
return {
keyPrefix?: string; // prepended to every key/from/to; stripped from results
maxExpiresIn?: number; // ceiling on url()/download/upload-URL expiry (seconds)
disposition?: "attachment" | "inline" | string; // download/url Content-Disposition
responseContentType?: string; // download/url Content-Type override (e.g. "application/pdf")
filterKeys?: (key: string) => boolean; // narrow a bulk op; hide keys from versions / restoreVersion / restoreTrashed / complete
maxResults?: number; // clamp a list/search page
context?: TContext; // per-request data for onUploadComplete (the user, the tenant)
};
keyPrefix is the workhorse. It is prepended server-side, so a client that calls download("avatar.jpg") actually reads users/123/avatar.jpg — it literally cannot address outside its scope. The prefix is stripped from list/search results and returned keys, so the client only ever sees relative paths. copy/move re-root both ends under the caller’s prefix: a from that names another tenant’s key just becomes a key inside the caller’s own prefix, so neither end can reach outside the scope.
Keys are checked after the prefix is applied: a .. or . segment, a NUL byte, a leading / or \, or an empty key gets 422, and a backslash counts as a path separator for the .. check (the fs adapter on Windows would resolve ..\u2\secret.txt into a sibling tenant).
The storage prefixes that versioning(), softDelete(), and dedup() keep their own objects under (.versions, .trash, .dedup) are reserved: a key or a list/search prefix inside one gets 403, so a client allowed to delete but not purge can’t hard-delete .trash/notes.txt, forge a version, or read or delete a de-duplicated blob by its hash. Use the plugin verbs (versions, restoreVersion, trashed, restoreTrashed, purge) instead; on a gateway whose Files lacks the plugin, those answer 422 Unsupported (reason capability). The check runs on the resolved key, so under a keyPrefix a tenant’s own users/u1/.trash/… is an ordinary key. It also matches however the key is spelled on a lenient backend: .TRASH/notes.txt (a case-insensitive filesystem or drive) and .trash\notes.txt (a Windows host, where \ is a separator) are refused too. A restoreVersion versionId containing a slash, a backslash, .., or a NUL byte gets 422.
maxExpiresIn is the only expiry ceiling. The router’s defaultExpiresIn is just what applies when the client doesn’t ask, and a client may request a longer expiresIn for url() or an upload. Return maxExpiresIn to cap it. On an adapter that only has permanent links (Vercel Blob public, UploadThing public-read, …), a capped url can’t be honored, so it fails with a 422 Unsupported error. In the default "auto" downloadMode, download proxies the bytes instead of redirecting.
context carries whatever you resolved while authorizing (the signed-in user, the tenant) to the gateway’s lifecycle hook, typed, so onUploadComplete doesn’t re-read the session.
disposition is the server-side override for both proxy downloads and URL minting. The gateway defaults untrusted URLs to attachment; return "inline" only when that operation is safe for the current user, key, and content type. The value can carry a filename (inline; filename="BATCH-123.pdf"): the proxy sends it as given and signed URLs bind it, so a browser’s PDF viewer saves the file under that name (File Preview shows the pattern). A header can’t carry control characters or anything past U+00FF, so the proxy refuses such a value with 422: write a non-ASCII name as an RFC 6266 filename*=UTF-8''….
Some adapters can’t bind a Content-Disposition into their URLs at all (Vercel Blob, Box, Dropbox, the local fs adapter, …; see provider gaps). On those, an "inline" disposition from authorize makes the gateway mint the URL without one, since inline rendering is already your policy; any filename it carried is dropped with it, so use downloadMode: "proxy" where the name matters. Without it, download proxies the bytes to apply attachment (unless downloadMode is "redirect"), and the url operation fails with a 422 Unsupported error rather than hand out a URL that may render inline.
responseContentType overrides the Content-Type a download or url is served with, for objects stored under the wrong type. A PDF written as application/octet-stream downloads even under an "inline" disposition; return { disposition: "inline", responseContentType: "application/pdf" } and it previews. Where the adapter can bind it into a signed URL (capabilities.signedUrl.contentType: S3 and the S3-compatible catalog, Bun’s S3, GCS, Firebase Storage, Azure with a signer), download redirects with it bound. Otherwise download proxies the bytes and sends the header itself (unless downloadMode is "redirect", which surfaces the Unsupported refusal), and the url operation fails with a 422 Unsupported error rather than hand out a URL that serves the stored type. It must be exactly one media type, written in ASCII, or the request fails with 422. Like disposition, it only describes the response: other operations ignore it, so it doesn’t set or restrict the type an upload stores (that’s the upload’s params.contentType). Browsers can’t ask for a content type: only authorize sets it, because a client-chosen text/html would render any stored bytes as a page. The proxy’s sandbox judges the type it actually sends, so overriding to text/html still gets Content-Security-Policy: sandbox.
Recipes
Read-only session — deny every write (including the plugin verbs that restore or purge):
authorize: ({ operation }) => {
const writes = [
"upload", // also covers presign/complete and the explicit-key PUT
"signedUploadUrl",
"delete",
"copy",
"move",
"restoreVersion",
"restoreTrashed",
"purge",
];
if (writes.includes(operation)) {
throw new FilesError("ReadOnly", "read-only"); // → 403
}
return { keyPrefix: "public/" };
};
For defense in depth, also pass files: files.readonly() so writes are refused at the SDK layer even if the hook is misconfigured.
Declarative allow-list — for a simple, uniform policy, skip the hook entirely:
createFilesRouter({
files,
operations: ["list", "head", "url", "download"], // read-only, no prefix scoping
});
operations is a hard gate that runs before authorize. Use both together for “only these verbs, and only under this prefix”.
Origin & CSRF
State-changing actions check the Origin header before mutating storage. When allowedOrigins is omitted, requests with an Origin header must match the route’s own origin; use an array or predicate to allow additional origins:
createFilesRouter({
files,
authorize,
allowedOrigins: ["https://app.example.com"],
});
The gateway reads no cookies except inside your authorize hook, so all authentication is in one place.
What crosses the wire
Errors are serialized to { error: { code, reason?, message } } and the underlying FilesError.cause (provider request IDs, headers) is never included. A message the storage layer wrote (a NotFound, Unauthorized, Conflict, or Provider error from the adapter) can name a filesystem path, an internal hostname, or a bucket, so the client gets its code and status with a fixed message such as not found, and a Provider or Unauthorized one also goes to onError. The SDK’s own refusals (Invalid, Unsupported, ReadOnly) and any FilesError your authorize, files factory, or onUploadComplete throws keep their message, rewritten to name the key the client sent so the keyPrefix never leaks. Anything thrown that isn’t a FilesError or RouterError (a database error from your authorize, say) is answered with a generic 500 (“internal server error”) and handed to the router’s onError, which defaults to console.error. The client rebuilds a FilesError from the envelope, so try/catch in the browser behaves like the SDK.