# 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.

*Canonical: https://makerkit.dev/docs/void-cloudflare/storage/overview*

---

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](../account/profile)). Add yours: [Adding an Upload Kind](./upload-kinds).

## 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:

1. Rate limits (`uploads`: 10 a minute per visitor; `uploadsAll`: 300 a minute for everyone).
2. Signed in.
3. The kind exists.
4. The caller may write it: a user kind is always the caller's own image; an organization kind needs the kind's `permission` in the caller's active organization.
5. The body: at most the kind's `maxBytes` (2 MB by default), exactly one `file` field. Nothing above reads it.
6. 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.
7. 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.
8. 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](./running)) |

## 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/client` redraws 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.
