@lunora/storage 1.0.0-alpha.16 → 1.0.0-alpha.160

package/README.md

@@ -34,7 +34,7 @@
 
 ---
 
-R2-backed file storage for Lunora. Wraps a Cloudflare `R2Bucket` binding with a typed API (`upload`/`store`, `download`, `delete`, `list`, `getMetadata`, multipart), worker-signed URLs for app-gated access, and native S3 presigned URLs for direct-to-R2 transfer.
+R2-backed file storage for Lunora. Wraps a Cloudflare `R2Bucket` binding with a typed API (`upload`/`store`, `download`, `head`, `delete`, `list`, `getMetadata`, multipart), worker-signed URLs for app-gated access, and native S3 presigned URLs for direct-to-R2 transfer.
 
 Part of the [Lunora](https://github.com/anolilab/lunora) framework — a type-safe, real-time backend on Cloudflare Workers + Durable Objects with a Vite-first DX.
 
@@ -75,13 +75,15 @@ export default defineApp<Env>()
 import { action, v } from "@/lunora/_generated/server";
 
 // Minting an upload URL is a write capability, so this is an `action`.
-// Queries and mutations get a read-only `ctx.storage`; the full surface
-// (generateUploadUrl/store/delete/multipart) is action-only.
+// Queries and mutations are TYPED with a read-only `ctx.storage`; the full
+// surface (generateUploadUrl/store/delete/getPresignedUrl) is action-only.
+// Multipart and `list` are on a `createStorage` instance, not on any ctx.
 export const uploadAvatar = action.input({ contentType: v.string() }).action(async ({ args, ctx }) => {
     const key = `avatars/${ctx.auth.userId ?? "anonymous"}/profile`;
 
-    // Short-lived signed PUT URL — the client uploads straight to R2 through
-    // your Worker route, with the Content-Type pinned into the signature.
+    // Short-lived signed PUT URL — the client uploads to your Worker route,
+    // which verifies the signature and writes to R2, with the Content-Type
+    // pinned into that signature.
     const url = await ctx.storage.generateUploadUrl(key, { contentType: args.contentType, expiresInSeconds: 60 });
 
     return { key, url };
@@ -95,6 +97,12 @@ import { createStorage } from "@lunora/storage";
 
 const storage = createStorage({
     bucket: env.FILES,
+    // Required. The name this bucket is registered under, bound into every signed
+    // URL's HMAC (and mirrored as `&bucket=`), so a URL minted for one bucket
+    // cannot be replayed against another sharing the signing secret. `"default"`
+    // for a single-bucket app; the registered name for anything reached through
+    // `createBucketStorage`.
+    bucketName: "default",
     publicBaseUrl: "https://cdn.acme.test",
     signingSecret: env.STORAGE_SECRET,
 });
@@ -104,12 +112,12 @@ await storage.upload("uploads/avatar.png", bytes, { contentType: "image/png", ma
 const url = await storage.getSignedUrl("uploads/avatar.png", { expiresInSeconds: 600 });
 ```
 
-> This README covers the basics. For the full API, options, and guides, see the **[documentation](https://lunora.sh/docs/addons/storage)**.
+> This README covers the basics. For the full API, options, and guides, see the **[documentation](https://lunora.sh/docs/packages/storage)**.
 
 ## Related
 
 - [`@lunora/server`](https://www.npmjs.com/package/@lunora/server) — call storage from queries, mutations, and actions.
-- [`@lunora/runtime`](https://www.npmjs.com/package/@lunora/runtime) — the Worker runtime that serves gated `GET /storage/:key` routes.
+- [`@lunora/runtime`](https://www.npmjs.com/package/@lunora/runtime) — the Worker runtime your signed-URL route sits in front of. It ships no public storage route of its own: the route that verifies a signed URL and moves the bytes is yours to add (see the `storage` registry item).
 - [`@lunora/d1`](https://www.npmjs.com/package/@lunora/d1) — store object metadata alongside your data.
 
 ## Supported Node.js Versions

package/dist/index.d.mts

@@ -20,13 +20,27 @@ interface R2S3Credentials {
 }
 /** Options for {@link Storage.getPresignedUrl}. */
 interface PresignedUrlOptions {
-  /** Seconds the URL stays valid; clamped to [1, 604800]. Default 900. */
+  /** Seconds the URL stays valid: 1 to 604800 (7 days); an out-of-range value throws. Default 900. */
   expiresInSeconds?: number;
   /** HTTP method the URL authorizes. Default `GET`. */
   method?: "GET" | "PUT";
 }
 interface LunoraStorageOptions {
   bucket: R2BucketLike;
+  /**
+   * The name this bucket is registered under — the same string a
+   * `defineStorageRule({ bucket })` rule and the generated `StorageBucketName`
+   * union use. Bound into every signed URL's HMAC and mirrored on it as
+   * `&bucket=`, so a URL minted for one bucket can't be replayed against
+   * another sharing the signing secret, and the serving route can resolve
+   * which bucket to read.
+   *
+   * Required, and deliberately without a default: a defaulted name is how
+   * every bucket ended up signing as `"default"` and cross-verifying against
+   * each other. Pass `"default"` for a single-bucket app's `ctx.storage`, and
+   * the registered name for any bucket reached through `createBucketStorage`.
+   */
+  bucketName: string;
   /** Public base URL used by `getSignedUrl()`. Required for signed URLs. */
   publicBaseUrl?: string;
   /**
@@ -45,26 +59,50 @@ interface UploadOptions {
   customMetadata?: Record<string, string>;
   /**
    * Maximum body size in bytes. For `ArrayBuffer`/`Blob` sources the length is
-   * known up front and rejected before the upload starts. For a
-   * `ReadableStream` the length isn't known synchronously, so the stream is
-   * piped through a byte counter that aborts the upload once the limit is
-   * exceeded — this also guards against R2 silently accepting/truncating an
-   * unbounded stream.
+   * known up front and rejected before the upload starts.
+   *
+   * A `ReadableStream` has no length to check, and R2 refuses any stream whose
+   * length it cannot read — so a capped stream is READ INTO MEMORY under the
+   * cap and uploaded as a sized body. Nothing reaches the bucket if the body
+   * crosses the limit.
+   *
+   * `maxSize` is therefore also the memory ceiling for a streamed upload, and
+   * the isolate's ~128 MB is shared by every concurrent request — so on the
+   * stream path `maxSize` is itself capped at 16 MiB and rejected above it.
+   * For objects larger than that use `createMultipartUpload` /
+   * `createUploadHandler`, which upload without ever holding the whole object.
+   * Must be a finite, non-negative number; anything else (`Number(undefined)`
+   * is the usual source) is rejected as a `VALIDATION_ERROR`.
    */
   maxSize?: number;
+  /**
+   * SHA-256 of the body (hex or a 32-byte buffer), recorded with the object.
+   *
+   * R2 only reports a checksum it was given: without this, `list()`/`head()`
+   * return no `sha256` and any later integrity check degrades to comparing
+   * sizes. R2 also verifies the digest itself on write, so supplying it turns
+   * the upload into a checked one.
+   */
+  sha256?: ArrayBuffer | string;
 }
 interface ListOptions {
   cursor?: string;
   /** R2 list delimiter — when set, common prefixes group instead of listing. */
   delimiter?: string;
-  /** Defaults to 100, capped at 1000 (R2 limit). */
+  /**
+   * Defaults to 100, capped at 1000 (R2 limit). A ceiling, not a promise: R2
+   * may return fewer per page to fit the entry metadata.
+   *
+   * Must be a positive integer when given — `0`, `12.5` and `NaN` throw rather
+   * than being coerced into a page size the caller never asked for.
+   */
   limit?: number;
 }
 interface SignedUrlOptions {
   /**
    * Pin the `Content-Type` an uploader must send on a `method: "PUT"` URL.
    * Baked into the HMAC canonical so the signature only authorizes a PUT with
-   * exactly this content-type; mirrored on the URL as `&amp;ct=...`. Ignored for
+   * exactly this content-type; mirrored on the URL as `&ct=...`. Ignored for
    * `GET` URLs (a download has no request body content-type to pin).
    */
   contentType?: string;
@@ -91,6 +129,17 @@ interface ObjectMetadata {
   uploaded?: number;
 }
 interface Storage {
+  /**
+   * The bucket name this accessor operates under — the same value
+   * {@link Storage.getSignedUrl} puts into the HMAC canonical.
+   *
+   * Exposed so everything downstream agrees on one name: `asBucketStorage`
+   * tags a single-bucket storage with it, and `storageRules(...)` matches
+   * `(bucket, operation)` rules against that tag. Without it a
+   * `createStorage({ bucketName: "avatars" })` signed URLs as `avatars` while
+   * the rules engine only ever saw `"default"`.
+   */
+  readonly bucketName: string;
   /**
    * Begin a native R2 **multipart upload** for very large objects — upload
    * parts (each uniform in size except the last), then `complete` with the
@@ -122,10 +171,10 @@ interface Storage {
   }) => Promise<string>;
   /**
    * Read a stored object's metadata (size, content-type, sha256, upload time,
-   * custom metadata) without fetching its body. Returns `null` when the object
-   * is absent. Backed by an R2 HEAD (`bucket.head`) when available, falling
-   * back to a 0-length ranged `get()` otherwise. Mirrors Convex's
-   * `ctx.storage.getMetadata`.
+   * custom metadata) without fetching its body, as a flat serializable shape.
+   * Returns `null` when the object is absent. A projection of
+   * {@link Storage.head}, so it makes the same single body-free read. Mirrors
+   * Convex's `ctx.storage.getMetadata`.
    */
   getMetadata: (key: string) => Promise<ObjectMetadata | null>;
   /**
@@ -138,8 +187,32 @@ interface Storage {
   getPresignedUrl: (key: string, options?: PresignedUrlOptions) => Promise<string>;
   getSignedUrl: (key: string, options?: SignedUrlOptions) => Promise<string>;
   getUrl: (key: string) => string;
+  /**
+   * Read an object's R2 metadata WITHOUT its body — `size` (the full object
+   * size), `etag`, `httpMetadata`, `checksums`, plus the `sha256`/`sha256Base64`
+   * projection `download()` adds. Returns `null` when the object is absent.
+   *
+   * Backed by an R2 HEAD when the binding exposes one, falling back to a
+   * 0-length ranged `get()` otherwise. Prefer this over `download()` whenever
+   * only the metadata is wanted — notably to resolve a `Range` header, where a
+   * plain `download()` starts a full-object body transfer that is then thrown
+   * away. {@link Storage.getMetadata} is the flat, serializable projection of
+   * the same read.
+   */
+  head: (key: string) => Promise<R2ObjectLike | null>;
+  /**
+   * List objects under `prefix`. With `options.delimiter` set, keys sharing a
+   * segment are rolled up into `delimitedPrefixes` (the "folders") and are NOT
+   * in `objects` — a folder browser needs both, so a listing whose `objects` is
+   * empty is not an empty directory.
+   *
+   * A page may hold FEWER objects than `options.limit`: R2 shrinks a page to
+   * fit the per-entry metadata this call asks for. Paginate on `truncated` /
+   * `cursor`, never on `objects.length === limit`.
+   */
   list: (prefix?: string, options?: ListOptions) => Promise<{
     cursor?: string;
+    delimitedPrefixes?: string[];
     objects: R2ObjectLike[];
     truncated?: boolean;
   }>;
@@ -154,12 +227,20 @@ interface Storage {
    * alias for {@link Storage.upload} — it accepts the same {@link UploadOptions}
    * so the `maxSize` / `allowedContentTypes` guards aren't lost behind the alias.
    */
-  store: (key: string, body: ReadableStream | ArrayBuffer | Blob, options?: UploadOptions) => Promise<{
+  store: (key: string, body: ReadableStream | ArrayBuffer | ArrayBufferView | Blob | string, options?: UploadOptions) => Promise<{
     etag: string;
     httpEtag: string;
     key: string;
   }>;
-  upload: (key: string, body: ReadableStream | ArrayBuffer | Blob, options?: UploadOptions) => Promise<{
+  /**
+   * Upload `body` to `key`, returning the stored key + etag.
+   *
+   * The accepted shapes mirror what R2's `put` stores bytes from — a view
+   * (`Uint8Array`) and a `string` included. They are listed here because
+   * `maxSize` measures every one of them; a shape the cap cannot measure is
+   * refused rather than uploaded uncapped.
+   */
+  upload: (key: string, body: ReadableStream | ArrayBuffer | ArrayBufferView | Blob | string, options?: UploadOptions) => Promise<{
     etag: string;
     httpEtag: string;
     key: string;
@@ -185,36 +266,32 @@ interface BucketStorage extends Storage {
  *
  * ```ts
  * storage: (env) => createBucketStorage({
- *     default: createStorage({ bucket: env.FILES }),
- *     avatars: createStorage({ bucket: env.AVATARS }),
+ *     default: createStorage({ bucket: env.FILES, bucketName: "default" }),
+ *     avatars: createStorage({ bucket: env.AVATARS, bucketName: "avatars" }),
  * }),
  * // → ctx.storage.download(key)             // default bucket
  * // → ctx.storage.bucket("avatars").store() // the avatars bucket
  * ```
  *
- * The bare accessor is tagged `"default"` — the canonical name a
- * `defineStorageRule({ bucket: "default" })` rule and the generated
- * `StorageBucketName` union both use — unless `options.default` names another
- * bucket (then the bare accessor takes that name). The binding it delegates to is
- * `options.default`, else the `"default"` key when present, else the first
- * registered bucket. Named buckets are reached with `bucket(name)`.
+ * The bare accessor is tagged with the name of the binding it actually
+ * delegates to: `options.default` when given, else `"default"` when that key
+ * exists (the canonical name a `defineStorageRule({ bucket: "default" })` rule
+ * and the generated `StorageBucketName` union use), else the first registered
+ * bucket. Tag and binding must agree or a `{ bucket: "avatars" }` rule would
+ * gate `bucket("avatars").download()` and not the identical bare
+ * `ctx.storage.download()` reaching the same R2 bucket. Named buckets are
+ * reached with `bucket(name)`.
  */
 declare const createBucketStorage: (buckets: Record<string, Storage>, options?: {
   default?: string;
 }) => BucketStorage;
-/**
- * Compose a per-tenant key from a scope prefix and a caller-supplied key.
- * Both halves are validated — the prefix may not contain `..` or NUL either,
- * and the resulting key must stay under R2's length ceiling. Recommended for
- * any multi-tenant deployment so client-supplied keys can't address peer data.
- */
 declare const scopeKey: (prefix: string, key: string) => string;
 declare const createStorage: (options: LunoraStorageOptions) => Storage;
 /** Parameters accepted by {@link buildPresignedUrl}. */
 interface PresignedUrlParams {
   /** R2 S3 API credentials + bucket/account. */
   credentials: R2S3Credentials;
-  /** Seconds the URL stays valid; clamped to [1, 604800]. Default 900. */
+  /** Seconds the URL stays valid: 1 to 604800 (7 days); an out-of-range value throws. Default 900. */
   expiresInSeconds?: number;
   /** Object key (path-style; not URL-encoded by the caller). */
   key: string;
@@ -235,20 +312,33 @@ declare const buildPresignedUrl: (parameters: PresignedUrlParams) => Promise<str
  * string carrying `exp` (unix seconds), `method` (`GET` or `PUT`) and `sig`
  * (a base64url HMAC).
  *
- * The HMAC canonical includes the URL host so a signature minted for one bucket
- * cannot be replayed against another host on the same signing secret. Even so,
- * the signing secret MUST NOT be shared across buckets/tenants — host binding
- * narrows replay surface but is not a substitute for per-tenant key isolation.
+ * The HMAC canonical includes the URL host AND the `bucketName`, so a signature
+ * minted for one bucket cannot be replayed against another bucket (all buckets
+ * of one `.storage()` declaration share a base URL and signing secret) or
+ * another host. Even so, the signing secret MUST NOT be shared across
+ * tenants — this binding narrows replay surface but is not a substitute for
+ * per-tenant key isolation.
  *
- * The Worker handling `GET /storage/:key` should call {@link verifySignedUrl}
- * to validate the signature + expiry before streaming the R2 body.
+ * The Worker route handling the signed download/upload (mounted at
+ * `publicBaseUrl`'s origin, e.g. `GET /:key`) should call
+ * {@link verifySignedUrl} to validate the signature + expiry before streaming
+ * the R2 body. `baseUrl` must be a bare origin (no path) — see the module
+ * docstring.
  */
-declare const buildSignedUrl: (args: SignedUrlOptions & {
+declare const buildSignedUrl: (args: {
   baseUrl: string;
+  /** The bucket the URL addresses — bound into the HMAC and mirrored as `&bucket=`. */
+  bucketName: string;
   key: string;
   secret: string;
-}) => Promise<string>;
+} & SignedUrlOptions) => Promise<string>;
 interface VerifyResult {
+  /**
+   * The bucket the URL was minted for. The serving route MUST resolve its R2
+   * binding from this (never from a caller-supplied bucket), since one signing
+   * secret covers every bucket of a `.storage()` declaration.
+   */
+  bucketName?: string;
   /** The pinned upload `Content-Type` carried by a PUT URL, when present. */
   contentType?: string;
   key?: string;

package/dist/index.d.ts

@@ -20,13 +20,27 @@ interface R2S3Credentials {
 }
 /** Options for {@link Storage.getPresignedUrl}. */
 interface PresignedUrlOptions {
-  /** Seconds the URL stays valid; clamped to [1, 604800]. Default 900. */
+  /** Seconds the URL stays valid: 1 to 604800 (7 days); an out-of-range value throws. Default 900. */
   expiresInSeconds?: number;
   /** HTTP method the URL authorizes. Default `GET`. */
   method?: "GET" | "PUT";
 }
 interface LunoraStorageOptions {
   bucket: R2BucketLike;
+  /**
+   * The name this bucket is registered under — the same string a
+   * `defineStorageRule({ bucket })` rule and the generated `StorageBucketName`
+   * union use. Bound into every signed URL's HMAC and mirrored on it as
+   * `&bucket=`, so a URL minted for one bucket can't be replayed against
+   * another sharing the signing secret, and the serving route can resolve
+   * which bucket to read.
+   *
+   * Required, and deliberately without a default: a defaulted name is how
+   * every bucket ended up signing as `"default"` and cross-verifying against
+   * each other. Pass `"default"` for a single-bucket app's `ctx.storage`, and
+   * the registered name for any bucket reached through `createBucketStorage`.
+   */
+  bucketName: string;
   /** Public base URL used by `getSignedUrl()`. Required for signed URLs. */
   publicBaseUrl?: string;
   /**
@@ -45,26 +59,50 @@ interface UploadOptions {
   customMetadata?: Record<string, string>;
   /**
    * Maximum body size in bytes. For `ArrayBuffer`/`Blob` sources the length is
-   * known up front and rejected before the upload starts. For a
-   * `ReadableStream` the length isn't known synchronously, so the stream is
-   * piped through a byte counter that aborts the upload once the limit is
-   * exceeded — this also guards against R2 silently accepting/truncating an
-   * unbounded stream.
+   * known up front and rejected before the upload starts.
+   *
+   * A `ReadableStream` has no length to check, and R2 refuses any stream whose
+   * length it cannot read — so a capped stream is READ INTO MEMORY under the
+   * cap and uploaded as a sized body. Nothing reaches the bucket if the body
+   * crosses the limit.
+   *
+   * `maxSize` is therefore also the memory ceiling for a streamed upload, and
+   * the isolate's ~128 MB is shared by every concurrent request — so on the
+   * stream path `maxSize` is itself capped at 16 MiB and rejected above it.
+   * For objects larger than that use `createMultipartUpload` /
+   * `createUploadHandler`, which upload without ever holding the whole object.
+   * Must be a finite, non-negative number; anything else (`Number(undefined)`
+   * is the usual source) is rejected as a `VALIDATION_ERROR`.
    */
   maxSize?: number;
+  /**
+   * SHA-256 of the body (hex or a 32-byte buffer), recorded with the object.
+   *
+   * R2 only reports a checksum it was given: without this, `list()`/`head()`
+   * return no `sha256` and any later integrity check degrades to comparing
+   * sizes. R2 also verifies the digest itself on write, so supplying it turns
+   * the upload into a checked one.
+   */
+  sha256?: ArrayBuffer | string;
 }
 interface ListOptions {
   cursor?: string;
   /** R2 list delimiter — when set, common prefixes group instead of listing. */
   delimiter?: string;
-  /** Defaults to 100, capped at 1000 (R2 limit). */
+  /**
+   * Defaults to 100, capped at 1000 (R2 limit). A ceiling, not a promise: R2
+   * may return fewer per page to fit the entry metadata.
+   *
+   * Must be a positive integer when given — `0`, `12.5` and `NaN` throw rather
+   * than being coerced into a page size the caller never asked for.
+   */
   limit?: number;
 }
 interface SignedUrlOptions {
   /**
    * Pin the `Content-Type` an uploader must send on a `method: "PUT"` URL.
    * Baked into the HMAC canonical so the signature only authorizes a PUT with
-   * exactly this content-type; mirrored on the URL as `&amp;ct=...`. Ignored for
+   * exactly this content-type; mirrored on the URL as `&ct=...`. Ignored for
    * `GET` URLs (a download has no request body content-type to pin).
    */
   contentType?: string;
@@ -91,6 +129,17 @@ interface ObjectMetadata {
   uploaded?: number;
 }
 interface Storage {
+  /**
+   * The bucket name this accessor operates under — the same value
+   * {@link Storage.getSignedUrl} puts into the HMAC canonical.
+   *
+   * Exposed so everything downstream agrees on one name: `asBucketStorage`
+   * tags a single-bucket storage with it, and `storageRules(...)` matches
+   * `(bucket, operation)` rules against that tag. Without it a
+   * `createStorage({ bucketName: "avatars" })` signed URLs as `avatars` while
+   * the rules engine only ever saw `"default"`.
+   */
+  readonly bucketName: string;
   /**
    * Begin a native R2 **multipart upload** for very large objects — upload
    * parts (each uniform in size except the last), then `complete` with the
@@ -122,10 +171,10 @@ interface Storage {
   }) => Promise<string>;
   /**
    * Read a stored object's metadata (size, content-type, sha256, upload time,
-   * custom metadata) without fetching its body. Returns `null` when the object
-   * is absent. Backed by an R2 HEAD (`bucket.head`) when available, falling
-   * back to a 0-length ranged `get()` otherwise. Mirrors Convex's
-   * `ctx.storage.getMetadata`.
+   * custom metadata) without fetching its body, as a flat serializable shape.
+   * Returns `null` when the object is absent. A projection of
+   * {@link Storage.head}, so it makes the same single body-free read. Mirrors
+   * Convex's `ctx.storage.getMetadata`.
    */
   getMetadata: (key: string) => Promise<ObjectMetadata | null>;
   /**
@@ -138,8 +187,32 @@ interface Storage {
   getPresignedUrl: (key: string, options?: PresignedUrlOptions) => Promise<string>;
   getSignedUrl: (key: string, options?: SignedUrlOptions) => Promise<string>;
   getUrl: (key: string) => string;
+  /**
+   * Read an object's R2 metadata WITHOUT its body — `size` (the full object
+   * size), `etag`, `httpMetadata`, `checksums`, plus the `sha256`/`sha256Base64`
+   * projection `download()` adds. Returns `null` when the object is absent.
+   *
+   * Backed by an R2 HEAD when the binding exposes one, falling back to a
+   * 0-length ranged `get()` otherwise. Prefer this over `download()` whenever
+   * only the metadata is wanted — notably to resolve a `Range` header, where a
+   * plain `download()` starts a full-object body transfer that is then thrown
+   * away. {@link Storage.getMetadata} is the flat, serializable projection of
+   * the same read.
+   */
+  head: (key: string) => Promise<R2ObjectLike | null>;
+  /**
+   * List objects under `prefix`. With `options.delimiter` set, keys sharing a
+   * segment are rolled up into `delimitedPrefixes` (the "folders") and are NOT
+   * in `objects` — a folder browser needs both, so a listing whose `objects` is
+   * empty is not an empty directory.
+   *
+   * A page may hold FEWER objects than `options.limit`: R2 shrinks a page to
+   * fit the per-entry metadata this call asks for. Paginate on `truncated` /
+   * `cursor`, never on `objects.length === limit`.
+   */
   list: (prefix?: string, options?: ListOptions) => Promise<{
     cursor?: string;
+    delimitedPrefixes?: string[];
     objects: R2ObjectLike[];
     truncated?: boolean;
   }>;
@@ -154,12 +227,20 @@ interface Storage {
    * alias for {@link Storage.upload} — it accepts the same {@link UploadOptions}
    * so the `maxSize` / `allowedContentTypes` guards aren't lost behind the alias.
    */
-  store: (key: string, body: ReadableStream | ArrayBuffer | Blob, options?: UploadOptions) => Promise<{
+  store: (key: string, body: ReadableStream | ArrayBuffer | ArrayBufferView | Blob | string, options?: UploadOptions) => Promise<{
     etag: string;
     httpEtag: string;
     key: string;
   }>;
-  upload: (key: string, body: ReadableStream | ArrayBuffer | Blob, options?: UploadOptions) => Promise<{
+  /**
+   * Upload `body` to `key`, returning the stored key + etag.
+   *
+   * The accepted shapes mirror what R2's `put` stores bytes from — a view
+   * (`Uint8Array`) and a `string` included. They are listed here because
+   * `maxSize` measures every one of them; a shape the cap cannot measure is
+   * refused rather than uploaded uncapped.
+   */
+  upload: (key: string, body: ReadableStream | ArrayBuffer | ArrayBufferView | Blob | string, options?: UploadOptions) => Promise<{
     etag: string;
     httpEtag: string;
     key: string;
@@ -185,36 +266,32 @@ interface BucketStorage extends Storage {
  *
  * ```ts
  * storage: (env) => createBucketStorage({
- *     default: createStorage({ bucket: env.FILES }),
- *     avatars: createStorage({ bucket: env.AVATARS }),
+ *     default: createStorage({ bucket: env.FILES, bucketName: "default" }),
+ *     avatars: createStorage({ bucket: env.AVATARS, bucketName: "avatars" }),
  * }),
  * // → ctx.storage.download(key)             // default bucket
  * // → ctx.storage.bucket("avatars").store() // the avatars bucket
  * ```
  *
- * The bare accessor is tagged `"default"` — the canonical name a
- * `defineStorageRule({ bucket: "default" })` rule and the generated
- * `StorageBucketName` union both use — unless `options.default` names another
- * bucket (then the bare accessor takes that name). The binding it delegates to is
- * `options.default`, else the `"default"` key when present, else the first
- * registered bucket. Named buckets are reached with `bucket(name)`.
+ * The bare accessor is tagged with the name of the binding it actually
+ * delegates to: `options.default` when given, else `"default"` when that key
+ * exists (the canonical name a `defineStorageRule({ bucket: "default" })` rule
+ * and the generated `StorageBucketName` union use), else the first registered
+ * bucket. Tag and binding must agree or a `{ bucket: "avatars" }` rule would
+ * gate `bucket("avatars").download()` and not the identical bare
+ * `ctx.storage.download()` reaching the same R2 bucket. Named buckets are
+ * reached with `bucket(name)`.
  */
 declare const createBucketStorage: (buckets: Record<string, Storage>, options?: {
   default?: string;
 }) => BucketStorage;
-/**
- * Compose a per-tenant key from a scope prefix and a caller-supplied key.
- * Both halves are validated — the prefix may not contain `..` or NUL either,
- * and the resulting key must stay under R2's length ceiling. Recommended for
- * any multi-tenant deployment so client-supplied keys can't address peer data.
- */
 declare const scopeKey: (prefix: string, key: string) => string;
 declare const createStorage: (options: LunoraStorageOptions) => Storage;
 /** Parameters accepted by {@link buildPresignedUrl}. */
 interface PresignedUrlParams {
   /** R2 S3 API credentials + bucket/account. */
   credentials: R2S3Credentials;
-  /** Seconds the URL stays valid; clamped to [1, 604800]. Default 900. */
+  /** Seconds the URL stays valid: 1 to 604800 (7 days); an out-of-range value throws. Default 900. */
   expiresInSeconds?: number;
   /** Object key (path-style; not URL-encoded by the caller). */
   key: string;
@@ -235,20 +312,33 @@ declare const buildPresignedUrl: (parameters: PresignedUrlParams) => Promise<str
  * string carrying `exp` (unix seconds), `method` (`GET` or `PUT`) and `sig`
  * (a base64url HMAC).
  *
- * The HMAC canonical includes the URL host so a signature minted for one bucket
- * cannot be replayed against another host on the same signing secret. Even so,
- * the signing secret MUST NOT be shared across buckets/tenants — host binding
- * narrows replay surface but is not a substitute for per-tenant key isolation.
+ * The HMAC canonical includes the URL host AND the `bucketName`, so a signature
+ * minted for one bucket cannot be replayed against another bucket (all buckets
+ * of one `.storage()` declaration share a base URL and signing secret) or
+ * another host. Even so, the signing secret MUST NOT be shared across
+ * tenants — this binding narrows replay surface but is not a substitute for
+ * per-tenant key isolation.
  *
- * The Worker handling `GET /storage/:key` should call {@link verifySignedUrl}
- * to validate the signature + expiry before streaming the R2 body.
+ * The Worker route handling the signed download/upload (mounted at
+ * `publicBaseUrl`'s origin, e.g. `GET /:key`) should call
+ * {@link verifySignedUrl} to validate the signature + expiry before streaming
+ * the R2 body. `baseUrl` must be a bare origin (no path) — see the module
+ * docstring.
  */
-declare const buildSignedUrl: (args: SignedUrlOptions & {
+declare const buildSignedUrl: (args: {
   baseUrl: string;
+  /** The bucket the URL addresses — bound into the HMAC and mirrored as `&bucket=`. */
+  bucketName: string;
   key: string;
   secret: string;
-}) => Promise<string>;
+} & SignedUrlOptions) => Promise<string>;
 interface VerifyResult {
+  /**
+   * The bucket the URL was minted for. The serving route MUST resolve its R2
+   * binding from this (never from a caller-supplied bucket), since one signing
+   * secret covers every bucket of a `.storage()` declaration.
+   */
+  bucketName?: string;
   /** The pinned upload `Content-Type` carried by a PUT URL, when present. */
   contentType?: string;
   key?: string;

package/dist/index.mjs

@@ -1 +1 @@
-import{createBucketStorage as o}from"./packem_shared/createBucketStorage-DAip6cEw.mjs";import{createStorage as a,scopeKey as i}from"./packem_shared/createStorage-BDKKnFcV.mjs";import{buildPresignedUrl as f}from"./packem_shared/buildPresignedUrl-TCv-5TAT.mjs";import{b as l,v as p}from"./packem_shared/signed-url-4m6WhCR1.mjs";export{f as buildPresignedUrl,l as buildSignedUrl,o as createBucketStorage,a as createStorage,i as scopeKey,p as verifySignedUrl};
+import{createBucketStorage as o}from"./packem_shared/createBucketStorage-AqIMq050.mjs";import{createStorage as i,scopeKey as d}from"./packem_shared/createStorage-DzyBEGJr.mjs";import{buildPresignedUrl as g}from"./packem_shared/buildPresignedUrl-GEo1eFpq.mjs";import{buildSignedUrl as p,verifySignedUrl as a}from"./packem_shared/buildSignedUrl-Bg2beHZA.mjs";export{g as buildPresignedUrl,p as buildSignedUrl,o as createBucketStorage,i as createStorage,d as scopeKey,a as verifySignedUrl};

package/dist/packem_shared/DEFAULT_MAX_UPLOAD_BYTES-BOaXqwP5.mjs

@@ -0,0 +1 @@
+import{AsyncLocalStorage as A}from"node:async_hooks";import{LunoraError as y}from"@lunora/errors";import{ERRORS as R,parseTusMetadata as I,File as L}from"@visulima/storage";import{Rest as F,Multipart as P,Tus as _}from"@visulima/storage/handler/http/fetch";const f="1.0.0",g=(t,e)=>Response.json({error:e},{headers:{"content-type":"application/json","Tus-Resumable":f},status:t}),M=t=>{try{return{metadata:Object.fromEntries(Object.entries(I(t)))}}catch(e){return{error:e instanceof Error?e.message:"Invalid Upload-Metadata header"}}},k=t=>{const e=new Headers(t.headers),r=e.get("Tus-Extension");return e.delete("Tus-Checksum-Algorithm"),r!==null&&e.set("Tus-Extension",r.split(",").filter(n=>n.trim()!=="checksum").join(",")),new Response(t.body,{headers:e,status:t.status,statusText:t.statusText})},C={declared:{contentType:void 0,metadata:{}}},D=t=>({check:e=>{if(e.method!=="POST"&&e.method!=="PATCH")return C;const r=M(e.headers.get("Upload-Metadata")??"");return"error"in r?{refusal:g(400,{code:"BadRequestError",message:r.error,name:"BadRequestError"})}:!t&&e.headers.has("Upload-Checksum")?{refusal:g(400,{code:R.UNSUPPORTED_CHECKSUM_ALGORITHM,message:"Upload-Checksum is not supported on this upload route: its storage verifies no checksums",name:"BadRequestError"})}:{declared:{contentType:void 0,metadata:r.metadata}}},finish:(e,r)=>e.method==="OPTIONS"&&!t?k(r):r}),z=100*1024*1024,H=16*1024*1024,S=new WeakMap,O=new A,ce=()=>{const t={get:()=>{const e=O.getStore();if(e?.issuer!==t)throw new y("INTERNAL","@lunora/storage: no upload grant from this UploadContext is active. Read it from a storage callback of a request `authorize` admitted with its grant()");return e.context},grant:e=>{const r=Object.freeze({});return S.set(r,{context:e,issuer:t}),r}};return t},m=(t,e,r)=>{const n={"content-type":"application/json"};return t==="tus"&&(n["Tus-Resumable"]=f),Response.json({error:r},{headers:n,status:e})},h=t=>m(t,403,{code:"FORBIDDEN",message:"Upload denied by authorization policy",name:"ForbiddenError"}),w=t=>m(t,413,{code:"REQUEST_ENTITY_TOO_LARGE",message:"Upload exceeds the configured maxFileSize",name:"RequestEntityTooLargeError"}),N={"chunked-rest":new Set(["HEAD","OPTIONS","PATCH","POST","PUT"]),multipart:new Set(["OPTIONS","POST"]),tus:new Set(["DELETE","HEAD","OPTIONS","PATCH","POST"])},E=(t,e)=>{const r=m(t,405,{code:"METHOD_NOT_ALLOWED",message:e,name:"MethodNotAllowedError"});return r.headers.set("Allow",[...N[t]].join(", ")),r},x=["X-HTTP-Method-Override","X-HTTP-Method","X-Method-Override"],v=/^\d+$/u,j=/\.[^.]+$/u,B=/^[\w-]{1,255}$/u,X=(t,e)=>{const r=(new URL(t.url).pathname.split("/").findLast(Boolean)??"").replace(j,""),n=t.headers.get("Content-Length")?.trim()??"",o=v.test(n)?Number(n):Number.NaN;return B.test(r)&&Number.isSafeInteger(o)&&o<=e.maxUploadSize?r:void 0},G=t=>typeof t=="object"&&t!==null&&t.UploadErrorCode===R.FILE_NOT_FOUND,$=async(t,e)=>{try{return await e.getMeta(t),!0}catch(r){return!G(r)}},b=(t,e)=>{if(e==="multipart")return;let r;for(const n of["Upload-Length","X-Total-Size","Content-Length"]){const o=t.headers.get(n);if(o===null)continue;const s=v.test(o.trim())?Number(o):Number.NaN,a=Number.isSafeInteger(s)?s:Number.POSITIVE_INFINITY;(r===void 0||a>r)&&(r=a)}return r},Y=(t,e,r,n)=>{const{method:o}=t;if(!N[e].has(o))return{refusal:E(e,`${o} is not allowed on this upload route: it is write-only. Serve stored files with ctx.storage.download() or a signed URL`)};const s=x.find(u=>t.headers.has(u));if(s!==void 0)return{refusal:E(e,`${s} is not allowed on this upload route: send the request with the method itself`)};const a=b(t,e);return a!==void 0&&a>r?{refusal:w(e)}:n.check(t)},V=t=>{try{const e=JSON.parse(t??"{}");return e!==null&&typeof e=="object"&&!Array.isArray(e)?e:{}}catch{return{}}},W={check:t=>{const e=t.headers.get("Content-Type");return{declared:{contentType:e===null||e===""?"application/octet-stream":e,metadata:V(t.headers.get("X-File-Metadata"))}}},finish:(t,e)=>e},J={check:()=>({declared:{contentType:void 0,metadata:{}}}),finish:(t,e)=>e},K=t=>{const e=new L({contentType:t.contentType,metadata:t.metadata}),r={};for(const[n,o]of Object.entries(t.metadata))r[n]=typeof o=="string"?o:JSON.stringify(o);return{contentType:e.contentType,metadata:r}},Q=(t,e)=>e!=="multipart"&&(t.method==="POST"||t.method==="PUT"),Z=async(t,e,r,n,o)=>{const s=b(e.request,e.protocol);let a;try{a=await t({...e,...K(n),declaredSize:s,granted:r})}catch{return h(e.protocol)}if(a!==void 0)return typeof a!="number"||!Number.isFinite(a)||a<0?h(e.protocol):s===void 0||s>Math.min(a,o)?w(e.protocol):void 0},q=(t,e)=>{if(t!=="tus"||e.headers.has("Tus-Resumable"))return e;const r=new Response(e.body,e);return r.headers.set("Tus-Resumable",f),r},ee=async(t,e)=>{let r;try{r=await t(e)}catch{return h(e.protocol)}if(r instanceof Response)return q(e.protocol,r);if(r===!0)return{granted:void 0};const n=typeof r=="object"&&r!==null?S.get(r):void 0;return n===void 0?h(e.protocol):{granted:n}},te=(t,e)=>t==="chunked-rest"?new F(e):t==="multipart"?new P(e):new _(e),re=(t,e)=>t==="tus"?D(e.checksumTypes.length>0):t==="chunked-rest"?W:J,de=t=>{const e=t.protocol??"tus",r=t.maxFileSize??z;if(!Number.isFinite(r)||r<0)throw new y("VALIDATION_ERROR",`@lunora/storage: maxFileSize must be a finite, non-negative number (received ${String(r)})`);const n={allowMethodOverride:!1,disableTerminationForFinishedUploads:!0,maxChecksumBufferSize:H,maxFileSize:r,storage:t.storage},o=te(e,n),s=re(e,t.storage),{authorize:a,maxFileSizeFor:u}=t;a===void 0&&!t.silent&&!t.public&&console.warn("@lunora/storage: createUploadHandler() has no `authorize` — this mounts an unauthenticated, unbounded-write endpoint. Pass an RLS `authorize` gate, or set `public: true` (or `silent: true`) to confirm this bucket is intentionally open.");const U=async(i,d,l,c)=>{if(u!==void 0&&Q(i,e)){const T=await Z(u,d,l?.context,c,r);if(T!==void 0)return T}const p=e==="chunked-rest"&&i.method==="PUT"?X(i,t.storage):void 0;return p!==void 0&&await $(p,t.storage)?m(e,409,{code:"FileConflict",message:"A file already exists under this name",name:"ConflictError"}):s.finish(i,await o.fetch(i))};return{fetch:async i=>{const d=Y(i,e,r,s);if("refusal"in d)return d.refusal;const l={method:i.method,protocol:e,request:i,url:new URL(i.url)},c=a===void 0?{granted:void 0}:await ee(a,l);return c instanceof Response?c:O.run(c.granted,async()=>U(i,l,c.granted,d.declared))},protocol:e}};export{z as DEFAULT_MAX_UPLOAD_BYTES,ce as createUploadContext,de as createUploadHandler};

package/dist/packem_shared/R2_PART_SIZE-D1p32KXe.mjs

@@ -0,0 +1 @@
+import{N as t,a as o,R as r,o as e,p}from"./r2-upload-part-writer-M7dEI00-.mjs";export{t as NAME_TAKEN,o as R2UploadPartWriter,r as R2_PART_SIZE,e as objectExists,p as putObject};

package/dist/packem_shared/buildPresignedUrl-GEo1eFpq.mjs

@@ -0,0 +1,5 @@
+import{LunoraError as f}from"@lunora/errors";import{b as g,v as D,m as K}from"./internal-B047mSU9.mjs";const $="auto",w="s3",p="AWS4-HMAC-SHA256",R=10080*60,x=900,r=new TextEncoder,z=(t,o)=>t[0]<o[0]?-1:t[0]>o[0]?1:0,i=t=>encodeURIComponent(t).replaceAll(/[!'()*]/gu,o=>`%${o.codePointAt(0)?.toString(16).toUpperCase()??""}`),M=t=>t.split("/").map(o=>i(o)).join("/"),X=async t=>g(await crypto.subtle.digest("SHA-256",r.encode(t))),a=async(t,o)=>{const n=await crypto.subtle.importKey("raw",t,{hash:"SHA-256",name:"HMAC"},!1,["sign"]);return crypto.subtle.sign("HMAC",n,r.encode(o))},_=64,b=new Map,N=async(t,o)=>K(b,`${o}
+${t}`,async()=>{const n=await a(r.encode(`AWS4${t}`),o),d=await a(n,$),s=await a(d,w),c=await a(s,"aws4_request");return crypto.subtle.importKey("raw",c,{hash:"SHA-256",name:"HMAC"},!1,["sign"])},_),O=t=>{const o=t.jurisdiction===void 0?"":`${t.jurisdiction}.`;return`${t.accountId}.${o}r2.cloudflarestorage.com`},P=t=>{const o=`${t.toISOString().replaceAll(/[:-]/gu,"").slice(0,15)}Z`;return{amzDate:o,dateStamp:o.slice(0,8)}},G=async t=>{const{credentials:o,key:n}=t,d=t.method??"GET";let s=x;if(t.expiresInSeconds!==void 0){s=Math.floor(t.expiresInSeconds);const e=D(s,R);if(e!==void 0)throw new f("VALIDATION_ERROR",`@lunora/storage: ${e}`)}const c=O(o),E=new Date(t.now?.()??Date.now()),{amzDate:u,dateStamp:A}=P(E),m=`${A}/${$}/${w}/aws4_request`,y=`/${i(o.bucket)}/${M(n)}`,S=[["X-Amz-Algorithm",p],["X-Amz-Credential",`${o.accessKeyId}/${m}`],["X-Amz-Date",u],["X-Amz-Expires",s.toString()],["X-Amz-SignedHeaders","host"]].map(([e,l])=>[i(e),i(l)]).toSorted(z).map(([e,l])=>`${e}=${l}`).join("&"),h=[d,y,S,`host:${c}
+`,"host","UNSIGNED-PAYLOAD"].join(`
+`),I=[p,u,m,await X(h)].join(`
+`),H=await N(o.secretAccessKey,A),C=g(await crypto.subtle.sign("HMAC",H,r.encode(I)));return`https://${c}${y}?${S}&X-Amz-Signature=${C}`};export{G as buildPresignedUrl};

package/dist/packem_shared/buildSignedUrl-Bg2beHZA.mjs

@@ -0,0 +1,6 @@
+import{LunoraError as f}from"@lunora/errors";import{i as y,c as u,e as p,s as v,t as U,f as N,d as w,v as I,M as $}from"./internal-B047mSU9.mjs";const k=/^\//,b=(e,s,r,t,o,a)=>{const n=`${e}
+${s.toLowerCase()}
+${r}
+${t}
+${String(o)}`;return a===void 0?n:`${n}
+${a}`},x=async e=>{const s=e.method??"GET",r=e.expiresInSeconds??3600,t=I(r,$);if(t!==void 0)throw new f("VALIDATION_ERROR",`@lunora/storage: ${t}`);const o=s==="PUT"?e.contentType:void 0;let a="";try{a=new URL(e.baseUrl).pathname}catch{}if(a!==""&&!y(a))throw new f("VALIDATION_ERROR",`@lunora/storage: baseUrl must not carry a path ("${a}") — the key is verified from the full URL pathname, so a subpath base would make every signed URL fail verification`);if(u(e.key),u(e.bucketName),e.bucketName==="")throw new f("VALIDATION_ERROR","@lunora/storage: bucketName must not be empty");if(e.key==="")throw new f("VALIDATION_ERROR","@lunora/storage: key must not be empty");const n=Math.floor(Date.now()/1e3)+r,c=p(e.baseUrl),i=await v(e.secret,b(s,c,e.bucketName,e.key,n,o)),m=U(e.baseUrl),l=e.key.split("/").map(h=>encodeURIComponent(h)).join("/"),d=o===void 0?"":`&ct=${encodeURIComponent(o)}`;return`${m}/${l}?exp=${String(n)}&method=${s}&bucket=${encodeURIComponent(e.bucketName)}&sig=${i}${d}`},E=async(e,s,r)=>{let t;try{t=e instanceof URL?e:new URL(e)}catch{return{reason:"malformed",valid:!1}}const o=t.searchParams.get("exp"),a=o===null?Number.NaN:Number(o),n=t.searchParams.get("sig"),c=t.searchParams.get("method")??"GET",i=t.searchParams.get("bucket"),m=t.searchParams.get("ct")??void 0;if(!n||!i||!Number.isInteger(a))return{reason:"malformed",valid:!1};if(a<Math.floor(Date.now()/1e3))return{reason:"expired",valid:!1};if(c!=="GET"&&c!=="PUT")return{reason:"malformed",valid:!1};let l,d;try{l=t.pathname.replace(k,"").split("/").map(R=>decodeURIComponent(R)).join("/"),u(l),u(i),d=N(n)}catch{return{reason:"malformed",valid:!1}}const h=r?.expectedHost===void 0?t.host:p(r.expectedHost);return await w(s,b(c,h,i,l,a,m),d)?{bucketName:i,contentType:m,key:l,method:c,valid:!0}:{reason:"bad_signature",valid:!1}};export{x as buildSignedUrl,E as verifySignedUrl};