---
name: lunora-setup-storage
description: Adds R2-backed file storage to a Lunora app. Use for uploads/downloads via `lunora registry add storage`, signed PUT/GET URLs, the `UPLOADS` R2 bucket binding, `STORAGE_SIGNING_SECRET`, per-tenant key scoping, and verifying downloads in the Worker.
---

# Lunora Setup Storage

Wire R2-backed file storage into a Lunora app using the `storage` registry item,
which is built on `@lunora/storage` (an R2 adapter plus HMAC signed-URL helpers)
and exposes idiomatic Lunora functions for browser uploads, gated downloads,
delete, and list — with no bucket credential in the client.

A worker-signed URL points at **your Worker**, not at R2:
`${STORAGE_PUBLIC_BASE_URL}/<key>?exp&method&bucket&sig`. The `/storage/*` route
you add in step 4 is what verifies the signature and moves the bytes, for both
the upload and the download. (The no-Worker-in-the-path variant is
`@lunora/storage`'s S3 presigned URL, `getPresignedUrl` — it needs S3 credentials
on the bucket and enforces none of your rules.)

## When to Use

- Uploading user files (avatars, attachments) into R2 under your own gate.
- Serving private/gated downloads via short-lived signed URLs.
- Listing or deleting a caller's stored objects.

## When Not to Use

- The project has no Lunora backend yet — use `lunora-quickstart` first.
- Storage is already installed and you just want to upload — call
  `client.action("storage/generateUploadUrl", …)` and `PUT` to the returned URL.

## Workflow

1. Add the `storage` item.
2. Configure the `UPLOADS` R2 bucket binding and the signing secret.
3. Regenerate types with `lunora codegen`.
4. Add the `/storage/*` route to the Worker — it verifies signatures and serves
   both the signed `PUT` and the signed `GET`.
5. Upload/download from the client.

## Step 1: Add the item

```bash
lunora registry add storage
```

This:

1. Adds `@lunora/storage` and `@lunora/server` to `package.json` (run
   `pnpm install` afterwards).
2. Adds an R2 bucket binding to `wrangler.jsonc` (`r2_buckets`, binding
   **`UPLOADS`**, `bucket_name: "replace-me-uploads"` — rename it to a real
   bucket). It **merges** into any existing `r2_buckets`.
3. Scaffolds `STORAGE_SIGNING_SECRET` (a secret) and `STORAGE_PUBLIC_BASE_URL`
   into `.dev.vars`.
4. Copies `lunora/storage/index.ts` (the `generateUploadUrl` /
   `getDownloadUrl` / `deleteObject` / `listObjects` functions) into your
   project — it is **yours** to edit.

## Step 2: Configure the binding + secrets

| Name                      | Where                                | Notes                                                                                                                                  |
| ------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `UPLOADS`                 | `wrangler.jsonc` → `r2_buckets[]`    | The R2 bucket binding. Point `bucket_name` at a real bucket.                                                                           |
| `STORAGE_SIGNING_SECRET`  | secret (`.dev.vars` / `secret put`)  | HMAC secret for signed URLs. Min 32 chars, enforced — a shorter one throws on the first call. Never share across tenants.              |
| `STORAGE_PUBLIC_BASE_URL` | var (`.dev.vars` / `wrangler.jsonc`) | **Bare origin** running the `/storage/*` route (scaffolded `http://localhost:8787`). A base carrying a path is rejected by the signer. |

`STORAGE_PUBLIC_BASE_URL` must be `https://` anywhere but local dev. A signed URL
_is_ a bearer credential and the object bytes stream through it, so a plaintext
origin hands both to anyone on the path. Only `http://localhost` /
`http://127.0.0.1` belong in `.dev.vars`.

Generate a real signing secret with `openssl rand -base64 32` and write it with
`wrangler secret put STORAGE_SIGNING_SECRET` for production.

## Step 3: Regenerate types

```bash
lunora codegen
```

The functions surface in the generated `api` as `api.storage.generateUploadUrl`,
`api.storage.getDownloadUrl`, `api.storage.deleteObject`, and
`api.storage.listObjects`.

## Step 4: Add the `/storage/*` route to the Worker

**Required, not optional.** Without it a minted URL hits the Lunora catch-all and
every upload and download 404s — and it is the only thing checking the signature,
so skipping the check lets anyone read any key.

`@lunora/server`'s `serveStorageObject(ctx, key, request, authorize)` handles
the download half (`Range`/206, `ETag`, `nosniff`, and
`content-disposition: attachment` for anything outside a small inline-safe set —
raster images plus `audio/mpeg`, `audio/ogg`, `audio/wav`, `video/mp4`,
`video/webm`, with `image/svg+xml` deliberately excluded). It verifies nothing on
its own — its required `authorize` gate is where `verifySignedUrl` goes — and it
does not handle the upload. Reach for it from an `httpAction`, where `ctx.storage`
is in scope, whenever you want `Range` seeking or conditional requests.

The route below is the standalone version — a plain worker `fetch` with only the
R2 binding to hand, so it serves whole objects and skips `Range`/`ETag`. Both
verbs, by hand:

```ts
import { isSafeHeaderValue } from "@lunora/server";
import { verifySignedUrl } from "@lunora/storage";

/** Cap what a single signed PUT may store. */
const MAX_UPLOAD_BYTES = 25 * 1024 * 1024;

/**
 * Origins allowed to upload cross-origin. Leave it empty when
 * `STORAGE_PUBLIC_BASE_URL` is your app's own origin — then `cors` is inert and
 * no browser ever preflights these routes.
 */
const ALLOWED_ORIGINS = new Set(["https://app.example.com"]);

/**
 * Types safe to render in the browser. Everything else downloads — an uploader
 * who pinned `text/html` or `image/svg+xml` must never get a same-origin script.
 * (`serveStorageObject` applies this same list.)
 */
const INLINE_SAFE = new Set([
    "audio/mpeg",
    "audio/ogg",
    "audio/wav",
    "image/apng",
    "image/avif",
    "image/gif",
    "image/jpeg",
    "image/png",
    "image/webp",
    "video/mp4",
    "video/webm",
]);

export default {
    async fetch(request: Request, env: Env): Promise<Response> {
        const url = new URL(request.url);

        if (url.pathname.startsWith("/storage/")) {
            const origin = request.headers.get("origin");
            // `vary` rides on EVERY response, allowed origin or not: a shared
            // cache keyed on the URL alone would otherwise replay one origin's
            // `access-control-allow-origin` to another.
            const cors = {
                vary: "origin",
                ...(origin !== null && ALLOWED_ORIGINS.has(origin)
                    ? { "access-control-allow-headers": "content-type", "access-control-allow-methods": "GET, PUT", "access-control-allow-origin": origin }
                    : {}),
            };

            // Before the verb check and the signature check: a preflight carries
            // neither the signed method nor any credentials, so answering it
            // later would 405 every cross-origin upload.
            if (request.method === "OPTIONS") {
                return new Response(null, { headers: cors, status: 204 });
            }

            // The method is signed, so a GET URL cannot be replayed as a PUT —
            // check the verb anyway rather than relying on that alone.
            if (request.method !== (url.searchParams.get("method") ?? "GET")) {
                return new Response("method not allowed", { status: 405 });
            }

            const result = await verifySignedUrl(url, env.STORAGE_SIGNING_SECRET);

            if (!result.valid || result.key === undefined) {
                // Expose only `valid` — a precise reason is a signing oracle.
                return new Response("forbidden", { status: 403 });
            }

            if (request.method === "PUT") {
                // Store the content type the SIGNATURE pins, never the request's
                // own header: the allowlist ran when the URL was minted, so
                // trusting the header lets a caller mint for `image/png` and PUT
                // `text/html` — stored XSS on this origin.
                if (result.contentType === undefined) {
                    return new Response("upload URL carries no content type", { status: 400 });
                }

                // A declared length is the contract: R2 takes `request.body` as a
                // stream, so there is nothing to measure before the write, and
                // treating an ABSENT header as oversized would 413 every valid
                // streamed upload. Demand it (411) and enforce it (413).
                const declared = request.headers.get("content-length");

                if (declared === null) {
                    return new Response("content-length required", { status: 411 });
                }

                const length = Number(declared);

                if (!Number.isFinite(length) || length > MAX_UPLOAD_BYTES) {
                    return new Response("upload too large", { status: 413 });
                }

                await env.UPLOADS.put(result.key, request.body, { httpMetadata: { contentType: result.contentType } });

                // The preflight's answer does not carry over: without CORS
                // headers HERE too the browser passes preflight and then rejects
                // the actual response.
                return new Response(null, { headers: cors, status: 204 });
            }

            const object = await env.UPLOADS.get(result.key);

            if (!object) {
                return new Response("not found", { status: 404 });
            }

            // The stored content type came off an uploader-signed URL, so it is
            // attacker-influenced: a CR/LF/NUL in it either throws inside
            // `Headers` (an unhandled 500) or, on a permissive runtime, splits
            // the response. Reject the value rather than reflect it — this is
            // exactly what `isSafeHeaderValue` does inside `serveStorageObject`.
            const rawContentType = object.httpMetadata?.contentType;
            const contentType = rawContentType !== undefined && isSafeHeaderValue(rawContentType) ? rawContentType : "application/octet-stream";

            return new Response(object.body, {
                headers: {
                    ...cors,
                    // The URL expires; a cached copy would not. Without this a
                    // browser or CDN can keep serving private bytes past `exp`,
                    // with `verifySignedUrl` never consulted again.
                    "cache-control": "private, no-store",
                    ...(INLINE_SAFE.has(contentType.split(";")[0]?.trim().toLowerCase() ?? "") ? {} : { "content-disposition": "attachment" }),
                    "content-type": contentType,
                    "x-content-type-options": "nosniff",
                },
            });
        }

        // ... your Lunora handler
        return new Response("not found", { status: 404 });
    },
};
```

**Why the CORS lines are there.** If `STORAGE_PUBLIC_BASE_URL` is not your app's
own origin, the browser `PUT` below is preflighted (`PUT` is not a simple method,
and `content-type: image/png` is not a safelisted value). Answering `OPTIONS` is
only half of it: the browser also reads
`access-control-allow-origin` off the **real** response, so the 204 and the
download response carry `...cors` too — a route that answers only the preflight
passes it and then fails the request it was preflighting.

Keep `STORAGE_PUBLIC_BASE_URL` same-origin if you would rather not maintain an
allowlist; then `ALLOWED_ORIGINS` can be empty and `cors` never adds a header
beyond `vary: origin`.

`verifySignedUrl` checks expiry, then the HMAC. On a host-rewrite / CDN topology
pass `{ expectedHost }` (the `STORAGE_PUBLIC_BASE_URL` host) so the signature
canonicalizes against the host it was minted for.

## Step 5: Upload / download from the client

```ts
// 1. ask the server for a signed PUT URL
const { key, url } = await client.action("storage/generateUploadUrl", {
    key: "avatar.png",
    contentType: file.type,
});

// 2. upload it — the URL points at your Worker's `/storage/*` route, which
//    verifies the signature and writes to R2. The content type is pinned into
//    the signature (and carried on the URL as `&ct=`); that signed value is what
//    gets stored, so the request's own `content-type` header is not read and
//    cannot override it.
await fetch(url, { method: "PUT", headers: { "content-type": file.type }, body: file });

// 3. later, get a signed GET URL to display it
const { url: downloadUrl } = await client.action("storage/getDownloadUrl", { key: "avatar.png" });
```

Every key is scoped per-tenant with `scopeKey(requireOwner(ctx.auth.userId),
key)` — `requireOwner` returns `storage/<userId>` — so a client-supplied key can
never address another user's data, and the `storage/` prefix is what lands the
minted URL on the `/storage/*` route. The functions return the **scoped** key
(`storage/<userId>/avatar.png`) alongside the URL; persist that, and pass the
bare key back in — the component re-scopes it.

## Common Pitfalls

1. **Skipping `verifySignedUrl` on the download route.** Without it, anyone can
   read any key. Always verify before streaming.
2. **Placeholder bucket name.** `lunora init` and `lunora add storage` prompt for
   the bucket name (or take `--bucket <name>`), but the low-level
   `lunora registry add storage` writes the placeholder
   `bucket_name: "replace-me-uploads"` — rename it to a real R2 bucket. (R2 names
   are lowercase alphanumeric + hyphens, 3–63 chars; wrangler rejects anything
   else on `dev`/`deploy`.)
3. **Short / shared signing secret.** ≥32 chars is enforced (the item throws on
   the first call below it). Cross-_bucket_ replay is not a risk here — the
   bucket name is part of the HMAC canonical and rides on the URL as `&bucket=`,
   so a URL minted for one bucket never verifies against another under the same
   secret. Cross-_tenant_ reuse is the real hazard: one secret shared between two
   apps lets either mint URLs the other's route will honour, so keep a distinct
   secret per deployment.
4. **Base URL with a path.** `STORAGE_PUBLIC_BASE_URL` must be a bare origin. The
   key is verified from the whole URL pathname, so a subpath base would make
   every minted URL fail verification — `buildSignedUrl` rejects it up front.
5. **Routing the body through a Lunora function.** Uploads and downloads go
   through the thin `/storage/*` route, which streams to and from R2 — don't
   read the file into a `query`/`mutation`/`action` argument or return value.

## Checklist

- [ ] `lunora registry add storage` run, `pnpm install` done.
- [ ] `UPLOADS` bucket bound to a real bucket; `STORAGE_SIGNING_SECRET` (≥32
      chars) and `STORAGE_PUBLIC_BASE_URL` (a bare origin) set.
- [ ] `lunora codegen` run so `api.storage.*` is generated.
- [ ] `/storage/*` route added, verifying signed URLs on both `PUT` and `GET`.
- [ ] Verified a client upload → signed download round-trip.