Gateway
createFilesRouter exposes the whole Files API over one HTTP endpoint. Mount it in Next (or any Web-Request runtime) and the browser bindings talk to it.
createFilesRouter turns a Files instance into an HTTP handler that the browser bindings (React, Vue, Svelte) call. It is framework-agnostic — handle(req: Request): Promise<Response> — and surfaced by thin adapters like files-sdk/next.
import { createFiles } from "files-sdk";
import { r2 } from "files-sdk/r2";
import { createFilesRouter } from "files-sdk/api";
import { createRouteHandler } from "files-sdk/next";
const router = createFilesRouter({
files: createFiles({ adapter: r2({ bucket: "uploads" }) }),
authorize: async ({ req }) => {
/* … */
},
});
export const { GET, POST, PUT } = createRouteHandler(router);
GET serves downloads, POST the JSON verbs, and PUT the upload byte path. The handler is Web-native (Request/Response, crypto.subtle, ReadableStream), so the same code runs on Node and the Edge runtime.
Passing a Files instance (not a raw adapter) is deliberate: its prefix, readonly, plugins, hooks, and receipts all compose for free. Pass files.readonly() for a read-only deployment so writes are refused at the SDK layer too.
Options
createFilesRouter({
// A Files instance, or a per-request factory for multi-tenant apps.
files: Files | ((req: Request) => Files | Promise<Files>),
// Per-operation gate. Deny-by-default when omitted. See /ui/server/authorization.
authorize?: (ctx) => void | Constraint | Promise<void | Constraint>,
// Declarative allow-list — operations permitted without a hook.
operations?: FilesOperation[],
// CSRF/origin allow-list for state-changing actions. Defaults to same-origin.
allowedOrigins?: string[] | ((origin: string) => boolean),
// Expiry for url()/download/upload URLs when the client doesn't ask for one,
// seconds. Default 300. Not a ceiling — cap it with authorize's maxExpiresIn.
defaultExpiresIn?: number,
// Force Content-Disposition: attachment on downloads (proxied, or bound
// into the redirect URL). Default true.
forceDownloadDisposition?: boolean,
maxListLimit?: number, // cap a list page; also the page size a search walks with. Default 1000.
maxSearchResults?: number, // cap a search page. Default 1000.
maxSearchScan?: number, // keys one search reads before answering truncated: true. Default 10000.
maxUploadSize?: number, // reject larger uploads (checked at presign, bound, verified on complete).
// Runs once per verified upload; its result is the client's upload `data`.
// Throw to reject (the object is deleted). See /ui/server/upload-lifecycle.
onUploadComplete?: (ctx) => TData | Promise<TData>,
onRejected?: "delete" | "keep", // rejected objects. Default "delete".
completions?: CompletionStore, // make keyless completions single-use.
completeGracePeriod?: number, // seconds `complete` still accepts an expired upload token. Default 3600.
// Gets every failure whose detail the client doesn't see: anything thrown
// that isn't a FilesError or RouterError (a generic 500), and a storage
// Provider/Unauthorized error (sent with a fixed message). Default console.error.
onError?: (error: unknown, req: Request) => void,
// Limits on client-driven load (see "Request limits" below).
maxBatchSize?: number, // keys[]/files[]/completions[] per request. Default 1000.
maxConcurrency?: number, // ceiling on a bulk op's `concurrency`. Default 16.
maxJsonBodySize?: number, // JSON request body, bytes. Default 1 MiB.
maxSearchPatternLength?: number, // search pattern, characters. Default 256.
maxSearchWildcards?: number, // unbounded wildcards per search pattern. Default 4.
downloadMode?: "auto" | "redirect" | "proxy", // default "auto"
onUnsupportedRange?: "reject" | "ignore", // default "reject" (416)
// HMAC secret for the upload round-trip. Falls back to FILES_API_SECRET,
// then a per-process random (logs a warning — set a stable secret in prod).
secret?: string,
});
How downloads flow
downloadMode: "auto" (the default) picks the cheapest correct path per adapter:
- Redirect to a signed URL — when the adapter can sign (S3, R2, GCS, …) and bind the forced
Content-Dispositioninto the signature, the gateway302s to a short-lived signed URL and the bytes flow directly from storage. Your server never touches them, andRangerequests are handled by the provider. Whenauthorizereturns{ disposition: "inline" }, nothing needs binding, so an adapter that can’t set a disposition is redirected too, with a URL that carries none. - Redirect to the public link — when no disposition must be bound (
forceDownloadDisposition: false, or an inline policy) andauthorizesets nomaxExpiresIn, an adapter with a permanent public link (apublicBaseUrlCDN, a public bucket or blob) is redirected to that link. - Proxy — otherwise: the adapter can’t sign (Vercel Blob in public mode, the filesystem, …), or it signs but can’t bind the forced
attachment(Vercel Blob and UploadThing in private mode, Box, PocketBase, …). The gateway streams the body through itself, setting the disposition itself and answeringRangerequests with206slices when the adapter can read ranges (see below for adapters that can’t). The client’s abort signal is wired through, so a disconnect cancels the upstream read.
The url operation follows the same rules: it signs whenever the adapter can (with your defaultExpiresIn unless the client asks for one), and on an adapter that only has permanent links, a client-requested expiresIn or an authorize maxExpiresIn is answered with a 422 instead of a link that outlives it.
Force one with downloadMode: "redirect" | "proxy". Downloads send Content-Disposition: attachment by default (so a stored .html/SVG can’t execute inline at your origin) unless authorize returns { disposition: "inline" }. The proxy path sets the header itself, and the redirect path binds it into the signed URL. Proxied downloads also send X-Content-Type-Options: nosniff, so the browser won’t sniff stored bytes into a more dangerous type, and Cache-Control: private, no-store, so a shared cache never keeps an authorized response. Except for raster images, audio, video, and PDF, they also carry Content-Security-Policy: sandbox; default-src 'none'; style-src 'unsafe-inline': a stored HTML or SVG file opened inline from your origin gets an opaque origin, loads nothing, and runs no script. A stored content type that isn’t exactly one media type (image/png, text/html, which a browser reads as its last entry) is sandboxed too, and the gateway refuses such a type from a client with 422 (reason: "type") on the keyed upload PUT, presign, and signed-upload-url. A client type must also be ASCII. A stored type that no response header can carry (written outside the gateway with a character past U+00FF, say) is proxied as application/octet-stream.
The proxy’s default attachment names the file after the key’s last segment (Content-Disposition: attachment; filename="report.pdf", plus an RFC 6266 filename* for a non-ASCII name), so a download opened straight from its ?op=download URL saves under its own name. A disposition authorize returns is sent exactly as given; one a header can’t carry (a control character, or one past U+00FF) fails the proxied download with 422 before the object is opened. Proxied downloads also answer HEAD with the headers a GET would send (Content-Length, ETag, Last-Modified, the disposition) and no body, without reading the object. On a full 200 response, the base64 JSON X-Files-Meta header carries the object’s size alongside its key and metadata, so the browser client still knows the size when compression middleware drops Content-Length.
Some adapters can sign a URL but can’t bind a Content-Disposition into it (Vercel Blob in private mode, Box, Dropbox, PocketBase, …), and their url() refuses the option rather than drop it. With downloadMode: "auto", the gateway proxies those downloads instead, so the attachment header still applies. More generally, whenever url() refuses with Unsupported on the signed or the public-link path, auto falls back to the proxy. With downloadMode: "redirect" there is no fallback, and the refusal surfaces as an error. When authorize returns { disposition: "inline" }, inline rendering is already your policy, so the gateway redirects to a URL minted without a disposition.
An authorize responseContentType is handled the same way: auto redirects only when the adapter can bind it into a signed URL (capabilities.signedUrl.contentType), never to the permanent public link, and proxies otherwise with that Content-Type (and the sandbox decision made on it). The url operation fails with a 422 Unsupported error on adapters that can’t bind it.
On the proxy path, Accept-Ranges reflects the adapter: bytes when it can serve ranges, none when it can’t. A Range request that carries an If-Range validator (the ETag or date from an earlier response) only gets a 206 slice while the object is unchanged. If the object changed, the gateway sends the whole new object with a 200, so a resumed download never splices bytes from two versions. Proxied responses carry ETag as a quoted entity-tag (even when the adapter reports it bare, as the S3 family does) and Last-Modified when the adapter knows it, and If-Range matches either the quoted or the bare form.
A ranged request to a non-range adapter gets 416 with the default onUnsupportedRange: "reject", with one exception. A 416 carries a JSON error body (Validation, reason: "range"), which the browser client turns into an Invalid error. bytes=0- (the open-ended range every <video> and <audio> element starts with) is satisfied by the whole body, so it gets the full object with a 200. With onUnsupportedRange: "ignore" any ranged request to a non-range adapter gets the whole object with a 200, and the browser client rejects that instead of treating it as the slice.
The JSON url operation applies the same safe default before calling files.url(): a browser request for responseContentDisposition: "inline" is rewritten to attachment, while an existing attachment; filename="..." value keeps its filename. Return { disposition: "inline" } from authorize only for routes where inline rendering is deliberate server policy.
On an adapter that can’t bind a disposition into its URLs, the gateway can’t guarantee attachment, so the url operation fails with a 422 Unsupported error instead of handing out a URL that may render inline. The message says how to proceed: return { disposition: "inline" } from authorize for routes where inline URLs are acceptable (the URL is then minted without a disposition), or use download, which proxies the bytes and sets Content-Disposition itself.
How uploads flow
A keyless upload(file) runs a three-step protocol so bytes never round-trip through your server when they don’t have to:
- presign — the server mints a key (under the authorized prefix), signs an HMAC token binding the key and size/type constraints, and returns either a real presigned URL or a proxy target. The token holds the upload to the
sizethe client declared (the sizeauthorizeapproved), capped bymaxUploadSize, and it is bound to the endpoint that minted it: the request’s origin, path, and query. A file whose declaredsizeis overmaxUploadSizeis refused up front with422andreason: "size", before anything is signed. A batch is signed at mostmaxConcurrencytargets at a time. A proxy target’s token isn’t capped by the adapter’ssignedUpload.maxExpiresIn, which only limits the provider’s own presigned URLs. A client-requestedexpiresInmust be a positive whole number of seconds, orpresignanswers422. - upload — the client
PUT/POSTs the bytes directly to storage (or proxies through?op=proxyfor non-presigning adapters), reporting progress. Like a presigned URL, the proxyPUTis authorized by its token alone (see Authorization). - complete — the server verifies the token, checks that its key lies under the calling request’s authorized prefix, and
heads the object, then returns the stored metadata. A token minted for another caller’s prefix gets anUnauthorizedentry with no stored metadata. (The token is signed, not encrypted: its payload names the key it was minted for, so treat a token as readable by whoever holds it.) Theheadis the authoritative size check: an object larger than the token allows (the declared size, capped bymaxUploadSize) gets an error entry and is deleted. The server then runsonUploadCompleteand returns the stored metadata with whatever the hook returned.
An explicit upload(key, body) skips presign and streams straight through the gateway, then runs onUploadComplete the same way. The stream reaches the adapter with no known length, so the S3-family adapters on their AWS SDK client need the optional @aws-sdk/lib-storage package for this path.
Request limits
Every JSON request is untrusted input that turns into storage calls, so the gateway bounds how much work one request can ask for:
- Batch size.
keys[](head/exists/deletebulk forms),files[](presign) andcompletions[](complete) are capped atmaxBatchSize(default 1000). A larger request gets413withreason: "count"before any storage call. - Concurrency. A bulk op’s client-supplied
concurrencyis clamped tomaxConcurrency(default 16). - Body size. A JSON body over
maxJsonBodySize(default 1 MiB) gets413withreason: "size". It is refused fromContent-Lengthup front, or as soon as a streamed body passes the cap, without buffering the rest. - Search. A
searchwalks the bucket in pages ofmaxListLimitkeys whateverlimitthe client sends (maxResultscaps the matches), and one request reads at mostmaxSearchScankeys (default 10,000), matching or not, before it stops and answerstruncated: true, so a pattern that matches nothing can’t walk the whole bucket. Patterns are also bounded: at mostmaxSearchPatternLengthcharacters (default 256) andmaxSearchWildcardsunbounded wildcards or quantifiers (default 4).*,**,+, and{n,}each count, and an unanchored regex counts one more. Nested repetition such as(a+)+is always refused. A pattern over either limit gets422before any key is matched. Globs and regexes both run on a backtracking engine, where each wildcard multiplies the worst-case work per key, so this bounds what one request can cost in CPU. Raise the limit if your patterns need more, or lower it ifsearchis open to untrusted users.
Other frameworks
The gateway core accepts any { handle(req: Request): Promise<Response> } consumer, so a binding is a few lines. Ready-made adapters ship for Next.js, Hono, Express, Fastify, Koa, NestJS, Nitro, SvelteKit, Astro, and TanStack Start. For anything else (Elysia, Bun, Deno, …), call router.handle(request) directly from any handler that gives you a Web Request.