Storage
Public images on Cloudflare R2: an upload kind per image an owner has (an avatar, a logo), one hardened upload route, safe serving, and cleanup when owners or images go.
The kit stores public images in a Cloudflare R2 bucket (STORAGE), for the user or organization that owns them: an avatar, a logo. You describe each image as an upload kind; the kit does the rest:
POST /api/uploads/<kind>takes one image, checks it, re-encodes it and points the owner at it.DELETE /api/uploads/<kind>clears it.GET /api/files/<key>serves it to anyone with the URL.- Deleted owners' images are purged, and leftovers are swept weekly.
The app ships with one kind, user-avatar (the user's picture, uploaded from Profile). Add yours: Adding an Upload Kind.
Images Are Public to Anyone With the URL
A stored image is served without a session, to anyone who has its URL. URLs are unguessable (/api/files/<kind>/<ownerId>/<random uuid>.webp) and nothing lists them, but anyone you share a URL with, or who sees it in a page, can load it. Storage is for images you'd show on a profile or in a header, never for private files (documents, receipts, attachments): those need a session-checked download route, which this does not provide.
What Happens to an Upload
In this order, each step before any later one runs:
- Rate limits (
uploads: 10 a minute per visitor;uploadsAll: 300 a minute for everyone). - Signed in.
- The kind exists.
- The caller may write it: a user kind is always the caller's own image; an organization kind needs the kind's
permissionin the caller's active organization. - The body: at most the kind's
maxBytes(2 MB by default), exactly onefilefield. Nothing above reads it. - The bytes are a PNG, JPEG or WebP (by their contents, never the file name or declared type), at most 4096 pixels a side and 2048 × 2048 pixels in all, not animated.
- Re-encoded to lossless WebP, shrunk to the kind's
maxDimension(512 by default), never upscaled. Only the pixels survive: EXIF, GPS and anything else in the file are gone. - Stored under a new key; the owner column moves to it only if nobody changed it since step 1; then the old image is deleted.
The owner is always taken from the session (the user, or the verified active organization), never from the request.
Answers
| Status | Body code | When |
|---|---|---|
| 200 | { "url": "/api/files/…" } | Stored; the owner points at url |
| 204 | Removed (also when there was nothing to remove) | |
| 400 | invalid_request | No file, an empty one, several, a text field, a broken or abandoned body |
| 400 | unsupported_type | Not a PNG, JPEG or WebP (SVG, GIF, HTML…) |
| 400 | too_large_dimensions | Over 4096 px a side or 2048 × 2048 px in all |
| 400 | animated_not_supported | An animated WebP |
| 400 | invalid_image | The file can't be decoded |
| 401 | unauthenticated | Signed out |
| 403 | forbidden | An organization kind with no active organization, or without the kind's permission |
| 404 | unknown_kind | No such kind |
| 404 | not_found | The owner was deleted meanwhile |
| 409 | conflict | Another upload or removal for the same owner won the race; try again |
| 413 | too_large | Over the kind's maxBytes |
| 429 | RATE_LIMITED | Over a rate limit (Retry-After says when to come back) |
| 500 | storage_unavailable | R2 or the database failed; nothing changed |
| 503 | unbound | The Worker has no STORAGE bucket (Running Storage) |
Known Limits
- EXIF orientation is ignored by the server. A phone JPEG that is sideways in its pixels and upright only through its EXIF tag is stored sideways when posted directly.
@kit/storage/clientredraws an image it has to shrink, which applies the rotation; one that already fits goes up as it is. - A replaced image may still show in a browser that cached the old URL until the page using the owner's URL reloads; the new image has a new URL.
- Lossless WebP only: a 512 px photo is about 150–300 KB.