@lunora/cli 1.0.0-alpha.22 → 1.0.0-alpha.221

package/skills/lunora-setup-hyperdrive/SKILL.md

@@ -92,24 +92,41 @@ that's a remote resource only `wrangler hyperdrive create` can mint. Importing
 lunora codegen
 ```
 
-When codegen sees `ctx.sql` used, it adds `sql: SqlClient` to **`ActionCtx`
-only** — never `QueryCtx`/`MutationCtx` — with a JSDoc restating the
-determinism/realtime caveat.
+When codegen sees `ctx.sql` used, it adds `readonly sql: SqlClient` to
+**`ActionCtx` only** — never `QueryCtx`/`MutationCtx` — with a JSDoc restating
+the determinism/realtime caveat, and emits a `.hyperdrive()` method on the
+generated app builder for you to supply the client (step 4).
 
-## Step 4: Use `ctx.sql` from an action
+## Step 4: Wire the client once, on the app builder
 
-```ts
+`ctx.sql` is `readonly` — assigning to it inside a handler is a `TS2540`.
+Codegen cannot build the client for you (turning a connection string into a
+`SqlClient` needs the driver you chose), so it emits a config thunk you fill in
+at the app level. It is called once per shard construction, not per request:
+
+```ts title="src/server/index.ts"
+import type { HyperdriveLike } from "@lunora/hyperdrive";
 import { createHyperdrive, fromPostgresJs } from "@lunora/hyperdrive";
 import postgres from "postgres";
 
-import { action, v } from "@lunora/server";
+import { defineApp } from "../lunora/_generated/app.js";
+
+const app = defineApp<Env>()
+    .shard((env) => env.SHARD)
+    .hyperdrive((env) => fromPostgresJs(postgres(createHyperdrive(env.HYPERDRIVE as HyperdriveLike).connectionString)))
+    .build();
+
+export const ShardDO = app.ShardDO;
+```
+
+Then read it from any action:
 
-export const listLegacyOrders = action.input({ orgId: v.string() }).action(async ({ ctx, args: { orgId } }) => {
-    const { connectionString } = createHyperdrive(ctx.env.HYPERDRIVE);
-    ctx.sql = fromPostgresJs(postgres(connectionString));
+```ts
+import { action, v } from "@/lunora/_generated/server";
 
-    return ctx.sql.query<{ id: string; total: number }>("select id, total from orders where org = $1", [orgId]);
-});
+export const listLegacyOrders = action
+    .input({ orgId: v.string() })
+    .action(async ({ ctx, args: { orgId } }) => ctx.sql.query<{ id: string; total: number }>("select id, total from orders where org = $1", [orgId]));
 ```
 
 The package never rewrites SQL — use your driver's native placeholders (`$1` for
@@ -122,10 +139,13 @@ Postgres change. To make external data reactive, write a projection into a
 `defineSchema` table from the same action — that write _is_ tracked:
 
 ```ts
+import { api } from "@/lunora/_generated/api";
+
 const [row] = await ctx.sql.query<{ id: string; total: number }>("select id, total from orders where id = $1", [id]);
 
-// This write re-runs live queries reading `orders`:
-await ctx.runMutation("orders:upsert", { id: row.id, total: row.total });
+// This write re-runs live queries reading `orders`. Pass the generated
+// reference — `ctx.run*` takes a reference, not a "file:fn" string.
+await ctx.runMutation(api.orders.upsert, { id: row.id, total: row.total });
 ```
 
 ## Common Pitfalls

package/skills/lunora-setup-mail/SKILL.md

@@ -7,8 +7,9 @@ description: Adds transactional email to a Lunora app. Use for sending mail (ver
 
 Wire transactional email into a Lunora app using the `mail` registry item, which
 is built on `@lunora/mail` (a Cloudflare Email Workers transport with
-header-injection-safe address handling) and exposes a `sendEmail` action plus a
-fire-and-forget `queueEmail` action. In dev, every send is captured into the
+header-injection-safe address handling) and exposes a `sendEmail` `internalAction`
+plus a fire-and-forget `queueEmail` `internalAction` — server-only, because a
+client-callable general-purpose mailer is an open relay. In dev, every send is captured into the
 Studio Mail tab instead of going out.
 
 ## When to Use
@@ -21,14 +22,14 @@ Studio Mail tab instead of going out.
 
 - The project has no Lunora backend yet — use `lunora-quickstart` first.
 - Mail is already installed and you just want to send — call
-  `ctx.runAction(api.mail.sendEmail, …)` or `client.action("mail/sendEmail", …)`.
+  `ctx.runAction(internal.mail.sendEmail, …)` from a server handler.
 
 ## Workflow
 
 1. Add the `mail` item.
 2. Configure the `SEND_EMAIL` binding (or a provider) and `MAIL_FROM`.
 3. Regenerate types with `lunora codegen`.
-4. Send mail from a function (or the client); render a React template if needed.
+4. Send mail from a server function; render a React template if needed.
 
 ## Step 1: Add the item
 
@@ -40,8 +41,8 @@ This:
 
 1. Adds `@lunora/mail` and `@lunora/server` to `package.json` (run
    `pnpm install` afterwards).
-2. Copies `lunora/mail/index.ts` (the `sendEmail` / `queueEmail` actions) into
-   your project — it is **yours** to edit.
+2. Copies `lunora/mail/index.ts` (the `sendEmail` / `queueEmail`
+   **`internalAction`s**) into your project — it is **yours** to edit.
 3. Adds a `send_email` binding (`SEND_EMAIL`, with a `destination_address`
    placeholder) to `wrangler.jsonc` and scaffolds `MAIL_FROM` (the default
    sender) into `.dev.vars`.
@@ -71,24 +72,27 @@ verification and forgot-password mail — is intercepted and surfaced in the
 lunora codegen
 ```
 
-The functions surface in the generated `api` as `api.mail.sendEmail` and
-`api.mail.queueEmail`.
+The functions surface in the generated **`internal`** (server-only) namespace as
+`internal.mail.sendEmail` and `internal.mail.queueEmail` — they are deliberately
+**not** in the client-reachable `api`.
 
 ## Step 4: Send mail
 
 ### From another function
 
-`sendEmail` is an **action** (sending is non-transactional network I/O). From a
-mutation, schedule it as a follow-up so the request is not blocked:
+`sendEmail` is an **`internalAction`** (sending is non-transactional network
+I/O). From a mutation, schedule it as a follow-up so the request is not blocked:
 
 ```ts
-import { mutation, v } from "@lunora/server";
+import { internalMutation, v } from "#lunora/_generated/server.js";
 
-import { api } from "./_generated/api";
+import { internal } from "./_generated/api";
 
-export const inviteUser = mutation.input({ email: v.string() }).mutation(async ({ ctx, args: { email } }) => {
-    // ...persist the invite, then send the mail as a follow-up action
-    await ctx.scheduler.runAfter(0, api.mail.sendEmail, {
+export const inviteUser = internalMutation.input({ email: v.string() }).mutation(async ({ ctx, args: { email } }) => {
+    // ...authenticate the caller and persist the invite, then send the mail as a
+    // follow-up action. The recipient is decided server-side — never forward a
+    // client-chosen `to`/`from`/`html` straight through.
+    await ctx.scheduler.runAfter(0, internal.mail.sendEmail, {
         to: email,
         subject: "You're invited",
         html: "<p>Click the link to join.</p>",
@@ -96,15 +100,15 @@ export const inviteUser = mutation.input({ email: v.string() }).mutation(async (
 });
 ```
 
-### From a client
+### Not from a client
 
-```ts
-await client.action("mail/sendEmail", {
-    to: "alice@example.com",
-    subject: "Welcome",
-    text: "Thanks for signing up!",
-});
-```
+There is no `client.action("mail/sendEmail", …)` path, and adding one is the
+mistake this item exists to prevent: a general-purpose mailer that lets the
+caller pick recipient, subject and body is an open relay for phishing through
+your verified domain. If you need a client-callable send, write a
+_purpose-specific_ public `action` that takes only safe business inputs (e.g.
+`{ orderId }`), checks `ctx.auth`/RBAC, derives the recipient server-side,
+rate-limits it (`@lunora/ratelimit`), and calls `internal.mail.sendEmail`.
 
 ### With a React email template
 
@@ -131,8 +135,10 @@ await createMailer({ apiKey: env.RESEND_API_KEY as string, from: env.MAIL_FROM a
 1. **Expecting prod email to "just work".** Dev captures into the Studio;
    production needs the `SEND_EMAIL` binding (a verified destination) or
    `RESEND_API_KEY`.
-2. **Calling `sendEmail` as a query/mutation.** It is an action — invoke it via
-   `ctx.runAction` / `ctx.scheduler.runAfter` / `client.action`, never `ctx.db`.
+2. **Calling `sendEmail` from the client, or as a query/mutation.** It is an
+   `internalAction` — invoke it via `ctx.runAction` / `ctx.scheduler.runAfter`
+   from a server handler. A client `client.action("mail/sendEmail", …)` is not
+   reachable and answers `FUNCTION_NOT_FOUND`.
 3. **Using `queueEmail` without a Queue binding.** It requires a Cloudflare
    Queue producer binding; until you add one, `@lunora/mail` throws
    `` `queue` binding is required for mailer.queue() ``. The item does not add
@@ -145,7 +151,7 @@ await createMailer({ apiKey: env.RESEND_API_KEY as string, from: env.MAIL_FROM a
 - [ ] `lunora registry add mail` run, `pnpm install` done.
 - [ ] `SEND_EMAIL` binding configured (verified destination) or
       `RESEND_API_KEY` set; `MAIL_FROM` set.
-- [ ] `lunora codegen` run so `api.mail.*` is generated.
-- [ ] Mail sent from a function (`ctx.scheduler.runAfter`/`ctx.runAction` with
-      `api.mail.sendEmail`) or the client (`client.action("mail/sendEmail", …)`).
+- [ ] `lunora codegen` run so `internal.mail.*` is generated.
+- [ ] Mail sent from a server function (`ctx.scheduler.runAfter` / `ctx.runAction`
+      with `internal.mail.sendEmail`) — never from the client.
 - [ ] Verified the send appears in the Studio Mail tab in dev.

package/skills/lunora-setup-scheduler/SKILL.md

@@ -31,31 +31,36 @@ which owns the alarm and durable storage.
 
 ## Deferred dispatch — `runAfter` / `runAt`
 
-Available on `ctx.scheduler` in any function. Target functions are passed by
-reference from the generated `api` / `internal` proxy:
+Available on `ctx.scheduler` in a **mutation or an action** — never a `query`,
+which is deterministic and re-runs. Target functions are passed by reference
+from the generated `api` / `internal` proxy (a `"file:fn"` path string also
+works):
 
 ```ts
-import { mutation, v } from "@lunora/server";
+import { mutation, v } from "#lunora/_generated/server.js";
 
 import { internal } from "./_generated/api";
 
 export const startTrial = mutation.input({ userId: v.string() }).mutation(async ({ ctx, args: { userId } }) => {
     // run an internal action 14 days from now
-    const { id } = await ctx.scheduler.runAfter(14 * 24 * 60 * 60 * 1000, internal.billing.endTrial, { userId });
+    const jobId = await ctx.scheduler.runAfter(14 * 24 * 60 * 60 * 1000, internal.billing.endTrial, { userId });
 
-    return { jobId: id };
+    return { jobId };
 });
 ```
 
-- `runAfter(delayMs, fnRef, args, options?)` — run after a delay (`delayMs` must
-  be a non-negative finite number). `runAt(date, fnRef, args, options?)` — run at
-  a `Date` or epoch-ms timestamp.
-- Both return `{ id, scheduledFor }`. Cancel with `ctx.scheduler.cancel(id)`;
+- `runAfter(delayMs, fnRef, args?)` — run after a delay (`delayMs` must be a
+  non-negative finite number). `runAt(timestampMs, fnRef, args?)` — run at an
+  epoch-ms timestamp.
+- Both resolve the job id. Cancel with `ctx.scheduler.cancel(id)`;
   inspect with `ctx.scheduler.get(id)` / `ctx.scheduler.list()`.
-- `options` accepts a `retry` policy (`{ maxAttempts, backoff, baseMs, maxMs }`;
-  DO defaults: `maxAttempts: 5`, `backoff: "exponential"`, `baseMs: 30_000`) and
-  a `shardKey` routing hint. On retry exhaustion the job is dead-lettered, never
-  silently dropped.
+- Those three arguments are the whole `ctx.scheduler` surface. Per-job
+  `RunOptions` — a `retry` policy (`{ maxAttempts, backoff, baseMs, maxMs }`), a
+  `shardKey` routing hint, `pool` — live on `@lunora/scheduler`'s own
+  `createScheduler(...)` client, which you construct yourself when you need them.
+  Jobs scheduled through `ctx.scheduler` take the DO defaults: 5 retries,
+  `backoff: "exponential"`, `baseMs: 30_000`. On retry exhaustion the job is
+  dead-lettered, never silently dropped.
 - The `SchedulerDO` binding (`SCHEDULER`) is **auto-inferred and reconciled**
   into `wrangler.jsonc` by `@lunora/config` once `@lunora/scheduler` is in use —
   run `lunora codegen` / `lunora doctor` to confirm. Scheduled jobs run with no

package/skills/lunora-setup-storage/SKILL.md

@@ -7,12 +7,19 @@ description: Adds R2-backed file storage to a Lunora app. Use for uploads/downlo
 
 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 direct browser uploads, gated
-downloads, delete, and list — so the bytes never proxy through your Worker.
+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) straight to R2.
+- 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.
 
@@ -27,7 +34,8 @@ downloads, delete, and list — so the bytes never proxy through your Worker.
 1. Add the `storage` item.
 2. Configure the `UPLOADS` R2 bucket binding and the signing secret.
 3. Regenerate types with `lunora codegen`.
-4. Verify signed downloads in the Worker's `GET /storage/:key` route.
+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
@@ -51,11 +59,16 @@ This:
 
 ## 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; never share across buckets.   |
-| `STORAGE_PUBLIC_BASE_URL` | var (`.dev.vars` / `wrangler.jsonc`) | Public host/route that fronts the bucket and serves `GET /storage/:key`. |
+| 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.
@@ -70,20 +83,87 @@ The functions surface in the generated `api` as `api.storage.generateUploadUrl`,
 `api.storage.getDownloadUrl`, `api.storage.deleteObject`, and
 `api.storage.listObjects`.
 
-## Step 4: Verify downloads in the Worker
+## 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.
 
-Signed URLs are only as safe as the route that checks them. Gate
-`GET /storage/:key` with `verifySignedUrl` before streaming the R2 body
-(`@lunora/server` also ships `serveStorageObject` to do this):
+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) {
@@ -91,14 +171,64 @@ export default {
                 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: { "content-type": object.httpMetadata?.contentType ?? "application/octet-stream" },
+                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",
+                },
             });
         }
 
@@ -108,6 +238,18 @@ export default {
 };
 ```
 
+**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.
@@ -121,17 +263,23 @@ const { key, url } = await client.action("storage/generateUploadUrl", {
     contentType: file.type,
 });
 
-// 2. upload straight to R2 (no Worker proxy)
+// 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(tenantPrefix(ctx.auth.userId),
-key)`, so a client-supplied key can never address another user's data. The
-functions return the **scoped** key (`<userId>/avatar.png`) alongside the URL;
-persist that, and pass the bare key back in — the component re-scopes it.
+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
 
@@ -143,16 +291,25 @@ persist that, and pass the bare key back in — the component re-scopes it.
    `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.** Use ≥32 chars and a distinct secret per
-   bucket; reusing it lets one bucket's URLs sign for another.
-4. **Proxying bytes through the Worker.** The design uploads/downloads directly
-   to R2 via signed URLs — don't re-route the file body through a function.
+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` set.
+      chars) and `STORAGE_PUBLIC_BASE_URL` (a bare origin) set.
 - [ ] `lunora codegen` run so `api.storage.*` is generated.
-- [ ] `GET /storage/:key` route verifies signed URLs before streaming.
+- [ ] `/storage/*` route added, verifying signed URLs on both `PUT` and `GET`.
 - [ ] Verified a client upload → signed download round-trip.