@lunora/storage 1.0.0-alpha.13 → 1.0.0-alpha.131

package/dist/upload.d.mts

@@ -1,9 +1,24 @@
+import { BaseStorageOptions } from '@visulima/storage';
+import { R2BucketLike } from '@lunora/platform';
 import { Tus } from '@visulima/storage/handler/http/fetch';
 import { AwsLightStorage } from '@visulima/storage/provider/aws-light';
+/**
+ * An R2 binding with the multipart API: a Worker's `env.BUCKET` (and
+ * miniflare's). The provider also relies on `put`'s `onlyIf` preconditions,
+ * which every R2 binding honors.
+ */
+type R2UploadBucket = R2BucketLike & Required<Pick<R2BucketLike, "createMultipartUpload" | "resumeMultipartUpload">>;
 /** Resumable upload wire protocols the handler can speak. */
 type UploadProtocol = "chunked-rest" | "multipart" | "tus";
+/**
+ * Default ceiling applied to `maxFileSize` when the caller doesn't supply one
+ * (100 MiB). Without SOME cap, an unauthenticated or loosely-authorized
+ * handler accepts an unbounded request body — pass an explicit `maxFileSize`
+ * to raise or lower this for your app.
+ */
+declare const DEFAULT_MAX_UPLOAD_BYTES: number;
 type UploadHandlerOptions = ConstructorParameters<typeof Tus>[0];
-/** A `@visulima/storage` storage provider (e.g. {@link createR2UploadStorage} or a memory provider in tests). */
+/** A `@visulima/storage` storage provider (e.g. `createR2UploadStorage` or a memory provider in tests). */
 type UploadStorage = UploadHandlerOptions["storage"];
 /**
  * The context handed to {@link CreateUploadHandlerOptions.authorize}. Everything
@@ -20,19 +35,128 @@ interface UploadAuthzContext {
   /** The parsed request URL (query params, upload-id path segment). */
   url: URL;
 }
+declare const GRANTED: unique symbol;
+/**
+ * A grant `authorize` answers to admit a request and hand the rest of it a
+ * `Context`. Opaque: only {@link UploadContext.grant} issues one, so a value
+ * the gate builds by hand, or picks up by mistake (`{ valid: false, context }`),
+ * is not a grant and is denied.
+ */
+interface UploadGrant<Context = unknown> {
+  readonly [GRANTED]: Context;
+}
+/** What {@link CreateUploadHandlerOptions.authorize} answers: allow, deny, a grant, or the response to refuse with. */
+type UploadAuthorizeResult<Context = unknown> = boolean | Response | UploadGrant<Context>;
+/**
+ * A typed channel from `authorize` to the storage provider's callbacks
+ * (`filename`, `onCreate`, `onComplete`, …), which get only the file.
+ * `authorize` answers `grant(context)`, and the callbacks read the context back
+ * with `get()`, so one handler and one provider serve every caller.
+ */
+interface UploadContext<Context> {
+  /**
+   * The context the current request was granted. Throws when there is none:
+   * outside an upload request, or when `authorize` answered `true` or a grant
+   * from another `UploadContext`.
+   */
+  get: () => Context;
+  /** A grant that admits the request and carries `context` to {@link UploadContext.get}. */
+  grant: (context: Context) => UploadGrant<Context>;
+}
+/**
+ * Create an {@link UploadContext}, typed by what `authorize` grants:
+ *
+ * ```ts
+ * const caller = createUploadContext<{ userId: string }>();
+ *
+ * filename: (file) => `uploads/${caller.get().userId}/${file.id}`,
+ * authorize: async ({ request }) => caller.grant({ userId: await userIdFrom(request) }),
+ * ```
+ */
+declare const createUploadContext: <Context>() => UploadContext<Context>;
+/**
+ * The context handed to {@link CreateUploadHandlerOptions.maxFileSizeFor}: the
+ * authorization context plus what the create request declares about the file.
+ * Everything here comes from the client, so it caps an upload by what the
+ * client SAYS it is; `allowMIME` on the provider is what checks the type.
+ */
+interface UploadSizeContext<Context = unknown> extends UploadAuthzContext {
+  /**
+   * The declared MIME type, resolved the way the stored file's type is: on
+   * chunked REST the request's `Content-Type`; on TUS the `Upload-Metadata`
+   * `mimeType`, else `type`, else `filetype`; else
+   * `application/octet-stream`.
+   */
+  contentType: string;
+  /**
+   * The largest size the request declares (`Upload-Length`, `X-Total-Size`,
+   * `Content-Length`). A declared size that is not a non-negative integer
+   * reads as `Infinity`.
+   */
+  declaredSize: number | undefined;
+  /** The context `authorize` granted this request, or `undefined` when it answered `true` or there is no `authorize`. */
+  granted: Context | undefined;
+  /** The decoded TUS `Upload-Metadata`, or the chunked-REST `X-File-Metadata` JSON, as strings. */
+  metadata: Record<string, string>;
+}
 /** Options for {@link createUploadHandler}. */
-interface CreateUploadHandlerOptions {
+interface CreateUploadHandlerOptions<Context = unknown> {
   /**
    * The RLS gate. Runs before every upload request and denies fail-closed:
-   * returning `false` **or throwing** yields a `403`. Omit only for a fully
-   * public bucket — the whole point of this handler over the admin path is
-   * that uploads are gated by *your* per-user policy, not an admin token.
+   * only `true` or an {@link UploadGrant} (from {@link UploadContext.grant})
+   * lets the request through; `false`, anything else, **or throwing** yields
+   * a `403`. A `Response` is answered instead of the `403`, for a refusal of
+   * your own (say a `429` with `Retry-After`): it is passed through as it
+   * is, except that a TUS route adds `Tus-Resumable` when it has none. It is
+   * meant for 4xx/5xx; a 2xx would tell the client an upload happened. Omit
+   * only for a fully public bucket — the whole point of this handler over
+   * the admin path is that uploads are gated by *your* per-user policy, not
+   * an admin token.
+   *
+   * Omitting it mounts an unauthenticated, unbounded-write endpoint, so
+   * doing so logs a one-time warning (per handler) unless `silent`/`public`
+   * says the omission is intentional.
+   */
+  authorize?: (context: UploadAuthzContext) => UploadAuthorizeResult<Context> | Promise<UploadAuthorizeResult<Context>>;
+  /**
+   * Maximum accepted file size in bytes. Forwarded to the multipart parser
+   * (protocol `"multipart"`) and, for `"tus"`/`"chunked-rest"`, enforced by
+   * this handler itself against the largest size the request declares across
+   * `Upload-Length` (TUS), `X-Total-Size` (chunked REST) and `Content-Length`
+   * — see {@link declaredUploadSize}. Defaults to
+   * {@link DEFAULT_MAX_UPLOAD_BYTES} (100 MiB) — pass this to raise or lower
+   * the ceiling; there is no unbounded option. Must be a finite, non-negative
+   * number: anything else (notably a `NaN` from an unset env var) throws at
+   * construction rather than disabling the cap.
    */
-  authorize?: (context: UploadAuthzContext) => boolean | Promise<boolean>;
-  /** Maximum accepted file size in bytes (forwarded to the multipart parser). */
   maxFileSize?: number;
+  /**
+   * A per-upload size cap, below `maxFileSize`: return the most bytes this
+   * upload may hold (say 10 MiB for `image/*`, 2 GiB for `video/*`), or
+   * `undefined` to leave `maxFileSize` as the only cap. It can only lower the
+   * cap, never raise it past `maxFileSize`.
+   *
+   * Runs after `authorize`, on the requests that create an upload (`POST`,
+   * and the chunked-REST `PUT`) of the `"tus"` and `"chunked-rest"`
+   * protocols; later chunks are bounded by the size declared at creation.
+   * Not applied to `"multipart"`, whose size is only known once the form is
+   * parsed. A create that declares no size is refused (`413`) when this
+   * returns a cap, since there is nothing to check it against. Throwing, or
+   * returning something that is not a finite, non-negative number, denies the
+   * request (`403`), fail-closed like `authorize`.
+   */
+  maxFileSizeFor?: (context: UploadSizeContext<Context>) => number | undefined | Promise<number | undefined>;
   /** Which protocol to speak. Default `"tus"` (the resumable, pause/resume-capable one). */
   protocol?: UploadProtocol;
+  /**
+   * Set when omitting `authorize` is intentional (a fully public upload
+   * bucket) — suppresses the one-time "no authorize gate" warning that would
+   * otherwise print when the handler is constructed. Has no effect when
+   * `authorize` is provided.
+   */
+  public?: boolean;
+  /** Suppress the one-time default-open-authorize warning. Alias of `public`. */
+  silent?: boolean;
   /** The storage provider the bytes land in (R2 in prod, memory in tests). */
   storage: UploadStorage;
 }
@@ -47,6 +171,62 @@ interface UploadHandler {
   /** The protocol this handler speaks. */
   protocol: UploadProtocol;
 }
+/**
+ * Build an RLS-gated resumable upload handler over a `@visulima/storage`
+ * provider. Mount its {@link UploadHandler.fetch} on the route your client
+ * uploads to and drive it with `@visulima/storage-client`.
+ */
+declare const createUploadHandler: <Context = unknown>(options: CreateUploadHandlerOptions<Context>) => UploadHandler;
+/** Every part of an R2 multipart upload but the last is exactly this size: R2's 5 MiB minimum. */
+declare const R2_PART_SIZE: number;
+/**
+ * `T` without its index signatures. `BaseStorageOptions` has a
+ * `[key: string]: unknown` one, and `Omit` over it maps over `string`, which
+ * erases every declared option (each would be `unknown`).
+ */
+type DeclaredKeys<T> = { [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K]; };
+/**
+ * Options for {@link createR2BindingUploadStorage}. A type alias, not an
+ * interface: an interface gets no implicit index signature, so it would not
+ * pass to `AbstractBaseStorage`'s constructor.
+ */
+type R2BindingUploadStorageOptions = Omit<DeclaredKeys<BaseStorageOptions>, "metaStorage"> & {
+  /**
+   * Key prefix the upload state objects and buffered segments are stored
+   * under, in the same bucket. Default `"_lunora/uploads/"`. No uploaded
+   * object may be named under it.
+   *
+   * The state of a finished upload stays (a few hundred bytes, so a `HEAD`
+   * can still answer that the upload is complete), and so does the state of
+   * one that was abandoned. Both accumulate: add an R2 object lifecycle rule
+   * that deletes objects under this prefix after a few days, longer than
+   * any upload you expect to take.
+   */
+  statePrefix?: string;
+  /**
+   * The scope a request's upload state is kept under, appended to `statePrefix`: the state of an upload
+   * is then readable only by requests in the same scope. Read it from the request's grant, e.g.
+   * `() => \`${caller.get().userId}/\``. Must return a string ending in `/`, or `""` for the unscoped root.
+   *
+   * `list()` reads only the unscoped root, so an upload kept under a scope is not listed.
+   */
+  stateScope?: () => string;
+};
+/**
+ * Build a resumable-upload provider for `createUploadHandler` over a Worker's
+ * R2 binding: no S3 credentials, and the same behaviour under `wrangler dev` /
+ * miniflare as in production.
+ *
+ * Speaks TUS (without the `checksum`, `concatenation` and
+ * `creation-defer-length` extensions), chunked REST, and multipart forms.
+ *
+ * Chunked-REST chunks have to arrive one at a time and in order. A chunk at any
+ * offset other than the upload's current one, or one sent while another is
+ * still streaming, is a `409` and stores nothing, and it never counts towards
+ * completion. The bundled `@visulima/storage-client` chunked-REST client
+ * sends one chunk at a time (since 1.0.8), so its uploads complete here.
+ */
+declare const createR2BindingUploadStorage: (bucket: R2UploadBucket, options?: R2BindingUploadStorageOptions) => UploadStorage;
 /** R2 (S3-compatible) credentials + bucket for {@link createR2UploadStorage}. */
 interface R2UploadStorageOptions {
   /** R2 S3 API Access Key ID (from an R2 API token). */
@@ -56,9 +236,11 @@ interface R2UploadStorageOptions {
   /** Target R2 bucket name. */
   bucket: string;
   /**
-   * Explicit R2 S3 endpoint. Defaults to
-   * `https://&lt;accountId>.r2.cloudflarestorage.com`. Pass this to pin a
-   * jurisdiction (e.g. `&lt;accountId>.eu.r2.cloudflarestorage.com`).
+   * Explicit R2 S3 account endpoint, an absolute `https://` URL. The bucket
+   * is appended as a path segment, unless the endpoint already names it
+   * (as its last path segment, or as the host's first label). Defaults to
+   * `https://<accountId>.r2.cloudflarestorage.com`. Pass this to pin a
+   * jurisdiction (e.g. `https://<accountId>.eu.r2.cloudflarestorage.com`).
    */
   endpoint?: string;
   /** Client-side multipart part size (bytes or a size string like `"16MB"`). */
@@ -70,13 +252,7 @@ interface R2UploadStorageOptions {
   path?: string;
 }
 /**
- * Build an RLS-gated resumable upload handler over a `@visulima/storage`
- * provider. Mount its {@link UploadHandler.fetch} on the route your client
- * uploads to and drive it with `@visulima/storage-client`.
- */
-declare const createUploadHandler: (options: CreateUploadHandlerOptions) => UploadHandler;
-/**
- * Build an R2-backed storage provider for {@link createUploadHandler} using
+ * Build an R2-backed storage provider for `createUploadHandler` using
  * `@visulima/storage`'s dependency-light `aws-light` provider (`aws4fetch`, no
  * AWS SDK). R2's S3 region alias is always `auto`.
  *
@@ -84,8 +260,56 @@ declare const createUploadHandler: (options: CreateUploadHandlerOptions) => Uplo
  * same credential shape `@lunora/storage`'s presigned-URL helpers take. In a
  * Worker the `aws-light` provider needs `nodejs_compat` (it imports
  * `node:stream`).
+ *
+ * The bucket is addressed path-style, `<endpoint>/<bucket>/<key>`.
+ *
+ * Each chunk becomes one multipart part, so every chunk but the last has to be
+ * the same size and at least 5 MiB, and chunks have to arrive in order (an
+ * out-of-order or repeated one is a `409`). The R2 binding provider
+ * (`./r2-binding-upload-storage`) has neither limit, needs no S3 credentials
+ * and runs under `wrangler dev` too.
+ *
+ * The provider takes no `@visulima/storage` limits of its own (its upload cap
+ * is the 5 TB default), so `maxFileSize` / `maxFileSizeFor` on the handler are
+ * the caps that apply.
  */
 declare const createR2UploadStorage: (options: R2UploadStorageOptions & {
   secretAccessKey: string;
 }) => AwsLightStorage;
-export { type CreateUploadHandlerOptions, type R2UploadStorageOptions, type UploadAuthzContext, type UploadHandler, type UploadProtocol, type UploadStorage, createR2UploadStorage, createUploadHandler };
+export { type CreateUploadHandlerOptions, DEFAULT_MAX_UPLOAD_BYTES,
+/**
+ * `@lunora/storage/upload` — the RLS-gated, non-admin resumable upload handler.
+ *
+ * A separate subpath so the base `@lunora/storage` entry stays lean: the
+ * `@visulima/storage` handler dependency only loads for apps that mount an
+ * end-user upload endpoint. Pair with `@visulima/storage-client` (or the
+ * `@lunora/react` / `@lunora/vue` / … `useUpload` re-exports) on the client.
+ *
+ * On Workers this subpath statically imports `node:async_hooks` (the grant
+ * scope) and, through the R2 providers, `node:stream`, so it needs Node.js
+ * compatibility to load at all: the import fails at load time otherwise, and
+ * the subpath never reaches `createUploadHandler` / `createUploadContext`. A
+ * `compatibility_date` of `2026-08-04` or later enables `nodejs_compat` by
+ * default; earlier dates need `nodejs_compat` in `compatibility_flags`.
+ * `nodejs_als` alone satisfies the `AsyncLocalStorage` import but not
+ * `node:stream`, so it is not enough for this subpath. Node.js is unaffected.
+ */
+type R2BindingUploadStorageOptions,
+/**
+ * `@lunora/storage/upload` — the RLS-gated, non-admin resumable upload handler.
+ *
+ * A separate subpath so the base `@lunora/storage` entry stays lean: the
+ * `@visulima/storage` handler dependency only loads for apps that mount an
+ * end-user upload endpoint. Pair with `@visulima/storage-client` (or the
+ * `@lunora/react` / `@lunora/vue` / … `useUpload` re-exports) on the client.
+ *
+ * On Workers this subpath statically imports `node:async_hooks` (the grant
+ * scope) and, through the R2 providers, `node:stream`, so it needs Node.js
+ * compatibility to load at all: the import fails at load time otherwise, and
+ * the subpath never reaches `createUploadHandler` / `createUploadContext`. A
+ * `compatibility_date` of `2026-08-04` or later enables `nodejs_compat` by
+ * default; earlier dates need `nodejs_compat` in `compatibility_flags`.
+ * `nodejs_als` alone satisfies the `AsyncLocalStorage` import but not
+ * `node:stream`, so it is not enough for this subpath. Node.js is unaffected.
+ */
+type R2UploadBucket, type R2UploadStorageOptions, R2_PART_SIZE, type UploadAuthorizeResult, type UploadAuthzContext, type UploadContext, type UploadGrant, type UploadHandler, type UploadProtocol, type UploadSizeContext, type UploadStorage, createR2BindingUploadStorage, createR2UploadStorage, createUploadContext, createUploadHandler };

package/dist/upload.d.ts

@@ -1,9 +1,24 @@
+import { BaseStorageOptions } from '@visulima/storage';
+import { R2BucketLike } from '@lunora/platform';
 import { Tus } from '@visulima/storage/handler/http/fetch';
 import { AwsLightStorage } from '@visulima/storage/provider/aws-light';
+/**
+ * An R2 binding with the multipart API: a Worker's `env.BUCKET` (and
+ * miniflare's). The provider also relies on `put`'s `onlyIf` preconditions,
+ * which every R2 binding honors.
+ */
+type R2UploadBucket = R2BucketLike & Required<Pick<R2BucketLike, "createMultipartUpload" | "resumeMultipartUpload">>;
 /** Resumable upload wire protocols the handler can speak. */
 type UploadProtocol = "chunked-rest" | "multipart" | "tus";
+/**
+ * Default ceiling applied to `maxFileSize` when the caller doesn't supply one
+ * (100 MiB). Without SOME cap, an unauthenticated or loosely-authorized
+ * handler accepts an unbounded request body — pass an explicit `maxFileSize`
+ * to raise or lower this for your app.
+ */
+declare const DEFAULT_MAX_UPLOAD_BYTES: number;
 type UploadHandlerOptions = ConstructorParameters<typeof Tus>[0];
-/** A `@visulima/storage` storage provider (e.g. {@link createR2UploadStorage} or a memory provider in tests). */
+/** A `@visulima/storage` storage provider (e.g. `createR2UploadStorage` or a memory provider in tests). */
 type UploadStorage = UploadHandlerOptions["storage"];
 /**
  * The context handed to {@link CreateUploadHandlerOptions.authorize}. Everything
@@ -20,19 +35,128 @@ interface UploadAuthzContext {
   /** The parsed request URL (query params, upload-id path segment). */
   url: URL;
 }
+declare const GRANTED: unique symbol;
+/**
+ * A grant `authorize` answers to admit a request and hand the rest of it a
+ * `Context`. Opaque: only {@link UploadContext.grant} issues one, so a value
+ * the gate builds by hand, or picks up by mistake (`{ valid: false, context }`),
+ * is not a grant and is denied.
+ */
+interface UploadGrant<Context = unknown> {
+  readonly [GRANTED]: Context;
+}
+/** What {@link CreateUploadHandlerOptions.authorize} answers: allow, deny, a grant, or the response to refuse with. */
+type UploadAuthorizeResult<Context = unknown> = boolean | Response | UploadGrant<Context>;
+/**
+ * A typed channel from `authorize` to the storage provider's callbacks
+ * (`filename`, `onCreate`, `onComplete`, …), which get only the file.
+ * `authorize` answers `grant(context)`, and the callbacks read the context back
+ * with `get()`, so one handler and one provider serve every caller.
+ */
+interface UploadContext<Context> {
+  /**
+   * The context the current request was granted. Throws when there is none:
+   * outside an upload request, or when `authorize` answered `true` or a grant
+   * from another `UploadContext`.
+   */
+  get: () => Context;
+  /** A grant that admits the request and carries `context` to {@link UploadContext.get}. */
+  grant: (context: Context) => UploadGrant<Context>;
+}
+/**
+ * Create an {@link UploadContext}, typed by what `authorize` grants:
+ *
+ * ```ts
+ * const caller = createUploadContext<{ userId: string }>();
+ *
+ * filename: (file) => `uploads/${caller.get().userId}/${file.id}`,
+ * authorize: async ({ request }) => caller.grant({ userId: await userIdFrom(request) }),
+ * ```
+ */
+declare const createUploadContext: <Context>() => UploadContext<Context>;
+/**
+ * The context handed to {@link CreateUploadHandlerOptions.maxFileSizeFor}: the
+ * authorization context plus what the create request declares about the file.
+ * Everything here comes from the client, so it caps an upload by what the
+ * client SAYS it is; `allowMIME` on the provider is what checks the type.
+ */
+interface UploadSizeContext<Context = unknown> extends UploadAuthzContext {
+  /**
+   * The declared MIME type, resolved the way the stored file's type is: on
+   * chunked REST the request's `Content-Type`; on TUS the `Upload-Metadata`
+   * `mimeType`, else `type`, else `filetype`; else
+   * `application/octet-stream`.
+   */
+  contentType: string;
+  /**
+   * The largest size the request declares (`Upload-Length`, `X-Total-Size`,
+   * `Content-Length`). A declared size that is not a non-negative integer
+   * reads as `Infinity`.
+   */
+  declaredSize: number | undefined;
+  /** The context `authorize` granted this request, or `undefined` when it answered `true` or there is no `authorize`. */
+  granted: Context | undefined;
+  /** The decoded TUS `Upload-Metadata`, or the chunked-REST `X-File-Metadata` JSON, as strings. */
+  metadata: Record<string, string>;
+}
 /** Options for {@link createUploadHandler}. */
-interface CreateUploadHandlerOptions {
+interface CreateUploadHandlerOptions<Context = unknown> {
   /**
    * The RLS gate. Runs before every upload request and denies fail-closed:
-   * returning `false` **or throwing** yields a `403`. Omit only for a fully
-   * public bucket — the whole point of this handler over the admin path is
-   * that uploads are gated by *your* per-user policy, not an admin token.
+   * only `true` or an {@link UploadGrant} (from {@link UploadContext.grant})
+   * lets the request through; `false`, anything else, **or throwing** yields
+   * a `403`. A `Response` is answered instead of the `403`, for a refusal of
+   * your own (say a `429` with `Retry-After`): it is passed through as it
+   * is, except that a TUS route adds `Tus-Resumable` when it has none. It is
+   * meant for 4xx/5xx; a 2xx would tell the client an upload happened. Omit
+   * only for a fully public bucket — the whole point of this handler over
+   * the admin path is that uploads are gated by *your* per-user policy, not
+   * an admin token.
+   *
+   * Omitting it mounts an unauthenticated, unbounded-write endpoint, so
+   * doing so logs a one-time warning (per handler) unless `silent`/`public`
+   * says the omission is intentional.
+   */
+  authorize?: (context: UploadAuthzContext) => UploadAuthorizeResult<Context> | Promise<UploadAuthorizeResult<Context>>;
+  /**
+   * Maximum accepted file size in bytes. Forwarded to the multipart parser
+   * (protocol `"multipart"`) and, for `"tus"`/`"chunked-rest"`, enforced by
+   * this handler itself against the largest size the request declares across
+   * `Upload-Length` (TUS), `X-Total-Size` (chunked REST) and `Content-Length`
+   * — see {@link declaredUploadSize}. Defaults to
+   * {@link DEFAULT_MAX_UPLOAD_BYTES} (100 MiB) — pass this to raise or lower
+   * the ceiling; there is no unbounded option. Must be a finite, non-negative
+   * number: anything else (notably a `NaN` from an unset env var) throws at
+   * construction rather than disabling the cap.
    */
-  authorize?: (context: UploadAuthzContext) => boolean | Promise<boolean>;
-  /** Maximum accepted file size in bytes (forwarded to the multipart parser). */
   maxFileSize?: number;
+  /**
+   * A per-upload size cap, below `maxFileSize`: return the most bytes this
+   * upload may hold (say 10 MiB for `image/*`, 2 GiB for `video/*`), or
+   * `undefined` to leave `maxFileSize` as the only cap. It can only lower the
+   * cap, never raise it past `maxFileSize`.
+   *
+   * Runs after `authorize`, on the requests that create an upload (`POST`,
+   * and the chunked-REST `PUT`) of the `"tus"` and `"chunked-rest"`
+   * protocols; later chunks are bounded by the size declared at creation.
+   * Not applied to `"multipart"`, whose size is only known once the form is
+   * parsed. A create that declares no size is refused (`413`) when this
+   * returns a cap, since there is nothing to check it against. Throwing, or
+   * returning something that is not a finite, non-negative number, denies the
+   * request (`403`), fail-closed like `authorize`.
+   */
+  maxFileSizeFor?: (context: UploadSizeContext<Context>) => number | undefined | Promise<number | undefined>;
   /** Which protocol to speak. Default `"tus"` (the resumable, pause/resume-capable one). */
   protocol?: UploadProtocol;
+  /**
+   * Set when omitting `authorize` is intentional (a fully public upload
+   * bucket) — suppresses the one-time "no authorize gate" warning that would
+   * otherwise print when the handler is constructed. Has no effect when
+   * `authorize` is provided.
+   */
+  public?: boolean;
+  /** Suppress the one-time default-open-authorize warning. Alias of `public`. */
+  silent?: boolean;
   /** The storage provider the bytes land in (R2 in prod, memory in tests). */
   storage: UploadStorage;
 }
@@ -47,6 +171,62 @@ interface UploadHandler {
   /** The protocol this handler speaks. */
   protocol: UploadProtocol;
 }
+/**
+ * Build an RLS-gated resumable upload handler over a `@visulima/storage`
+ * provider. Mount its {@link UploadHandler.fetch} on the route your client
+ * uploads to and drive it with `@visulima/storage-client`.
+ */
+declare const createUploadHandler: <Context = unknown>(options: CreateUploadHandlerOptions<Context>) => UploadHandler;
+/** Every part of an R2 multipart upload but the last is exactly this size: R2's 5 MiB minimum. */
+declare const R2_PART_SIZE: number;
+/**
+ * `T` without its index signatures. `BaseStorageOptions` has a
+ * `[key: string]: unknown` one, and `Omit` over it maps over `string`, which
+ * erases every declared option (each would be `unknown`).
+ */
+type DeclaredKeys<T> = { [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K]; };
+/**
+ * Options for {@link createR2BindingUploadStorage}. A type alias, not an
+ * interface: an interface gets no implicit index signature, so it would not
+ * pass to `AbstractBaseStorage`'s constructor.
+ */
+type R2BindingUploadStorageOptions = Omit<DeclaredKeys<BaseStorageOptions>, "metaStorage"> & {
+  /**
+   * Key prefix the upload state objects and buffered segments are stored
+   * under, in the same bucket. Default `"_lunora/uploads/"`. No uploaded
+   * object may be named under it.
+   *
+   * The state of a finished upload stays (a few hundred bytes, so a `HEAD`
+   * can still answer that the upload is complete), and so does the state of
+   * one that was abandoned. Both accumulate: add an R2 object lifecycle rule
+   * that deletes objects under this prefix after a few days, longer than
+   * any upload you expect to take.
+   */
+  statePrefix?: string;
+  /**
+   * The scope a request's upload state is kept under, appended to `statePrefix`: the state of an upload
+   * is then readable only by requests in the same scope. Read it from the request's grant, e.g.
+   * `() => \`${caller.get().userId}/\``. Must return a string ending in `/`, or `""` for the unscoped root.
+   *
+   * `list()` reads only the unscoped root, so an upload kept under a scope is not listed.
+   */
+  stateScope?: () => string;
+};
+/**
+ * Build a resumable-upload provider for `createUploadHandler` over a Worker's
+ * R2 binding: no S3 credentials, and the same behaviour under `wrangler dev` /
+ * miniflare as in production.
+ *
+ * Speaks TUS (without the `checksum`, `concatenation` and
+ * `creation-defer-length` extensions), chunked REST, and multipart forms.
+ *
+ * Chunked-REST chunks have to arrive one at a time and in order. A chunk at any
+ * offset other than the upload's current one, or one sent while another is
+ * still streaming, is a `409` and stores nothing, and it never counts towards
+ * completion. The bundled `@visulima/storage-client` chunked-REST client
+ * sends one chunk at a time (since 1.0.8), so its uploads complete here.
+ */
+declare const createR2BindingUploadStorage: (bucket: R2UploadBucket, options?: R2BindingUploadStorageOptions) => UploadStorage;
 /** R2 (S3-compatible) credentials + bucket for {@link createR2UploadStorage}. */
 interface R2UploadStorageOptions {
   /** R2 S3 API Access Key ID (from an R2 API token). */
@@ -56,9 +236,11 @@ interface R2UploadStorageOptions {
   /** Target R2 bucket name. */
   bucket: string;
   /**
-   * Explicit R2 S3 endpoint. Defaults to
-   * `https://&lt;accountId>.r2.cloudflarestorage.com`. Pass this to pin a
-   * jurisdiction (e.g. `&lt;accountId>.eu.r2.cloudflarestorage.com`).
+   * Explicit R2 S3 account endpoint, an absolute `https://` URL. The bucket
+   * is appended as a path segment, unless the endpoint already names it
+   * (as its last path segment, or as the host's first label). Defaults to
+   * `https://<accountId>.r2.cloudflarestorage.com`. Pass this to pin a
+   * jurisdiction (e.g. `https://<accountId>.eu.r2.cloudflarestorage.com`).
    */
   endpoint?: string;
   /** Client-side multipart part size (bytes or a size string like `"16MB"`). */
@@ -70,13 +252,7 @@ interface R2UploadStorageOptions {
   path?: string;
 }
 /**
- * Build an RLS-gated resumable upload handler over a `@visulima/storage`
- * provider. Mount its {@link UploadHandler.fetch} on the route your client
- * uploads to and drive it with `@visulima/storage-client`.
- */
-declare const createUploadHandler: (options: CreateUploadHandlerOptions) => UploadHandler;
-/**
- * Build an R2-backed storage provider for {@link createUploadHandler} using
+ * Build an R2-backed storage provider for `createUploadHandler` using
  * `@visulima/storage`'s dependency-light `aws-light` provider (`aws4fetch`, no
  * AWS SDK). R2's S3 region alias is always `auto`.
  *
@@ -84,8 +260,56 @@ declare const createUploadHandler: (options: CreateUploadHandlerOptions) => Uplo
  * same credential shape `@lunora/storage`'s presigned-URL helpers take. In a
  * Worker the `aws-light` provider needs `nodejs_compat` (it imports
  * `node:stream`).
+ *
+ * The bucket is addressed path-style, `<endpoint>/<bucket>/<key>`.
+ *
+ * Each chunk becomes one multipart part, so every chunk but the last has to be
+ * the same size and at least 5 MiB, and chunks have to arrive in order (an
+ * out-of-order or repeated one is a `409`). The R2 binding provider
+ * (`./r2-binding-upload-storage`) has neither limit, needs no S3 credentials
+ * and runs under `wrangler dev` too.
+ *
+ * The provider takes no `@visulima/storage` limits of its own (its upload cap
+ * is the 5 TB default), so `maxFileSize` / `maxFileSizeFor` on the handler are
+ * the caps that apply.
  */
 declare const createR2UploadStorage: (options: R2UploadStorageOptions & {
   secretAccessKey: string;
 }) => AwsLightStorage;
-export { type CreateUploadHandlerOptions, type R2UploadStorageOptions, type UploadAuthzContext, type UploadHandler, type UploadProtocol, type UploadStorage, createR2UploadStorage, createUploadHandler };
+export { type CreateUploadHandlerOptions, DEFAULT_MAX_UPLOAD_BYTES,
+/**
+ * `@lunora/storage/upload` — the RLS-gated, non-admin resumable upload handler.
+ *
+ * A separate subpath so the base `@lunora/storage` entry stays lean: the
+ * `@visulima/storage` handler dependency only loads for apps that mount an
+ * end-user upload endpoint. Pair with `@visulima/storage-client` (or the
+ * `@lunora/react` / `@lunora/vue` / … `useUpload` re-exports) on the client.
+ *
+ * On Workers this subpath statically imports `node:async_hooks` (the grant
+ * scope) and, through the R2 providers, `node:stream`, so it needs Node.js
+ * compatibility to load at all: the import fails at load time otherwise, and
+ * the subpath never reaches `createUploadHandler` / `createUploadContext`. A
+ * `compatibility_date` of `2026-08-04` or later enables `nodejs_compat` by
+ * default; earlier dates need `nodejs_compat` in `compatibility_flags`.
+ * `nodejs_als` alone satisfies the `AsyncLocalStorage` import but not
+ * `node:stream`, so it is not enough for this subpath. Node.js is unaffected.
+ */
+type R2BindingUploadStorageOptions,
+/**
+ * `@lunora/storage/upload` — the RLS-gated, non-admin resumable upload handler.
+ *
+ * A separate subpath so the base `@lunora/storage` entry stays lean: the
+ * `@visulima/storage` handler dependency only loads for apps that mount an
+ * end-user upload endpoint. Pair with `@visulima/storage-client` (or the
+ * `@lunora/react` / `@lunora/vue` / … `useUpload` re-exports) on the client.
+ *
+ * On Workers this subpath statically imports `node:async_hooks` (the grant
+ * scope) and, through the R2 providers, `node:stream`, so it needs Node.js
+ * compatibility to load at all: the import fails at load time otherwise, and
+ * the subpath never reaches `createUploadHandler` / `createUploadContext`. A
+ * `compatibility_date` of `2026-08-04` or later enables `nodejs_compat` by
+ * default; earlier dates need `nodejs_compat` in `compatibility_flags`.
+ * `nodejs_als` alone satisfies the `AsyncLocalStorage` import but not
+ * `node:stream`, so it is not enough for this subpath. Node.js is unaffected.
+ */
+type R2UploadBucket, type R2UploadStorageOptions, R2_PART_SIZE, type UploadAuthorizeResult, type UploadAuthzContext, type UploadContext, type UploadGrant, type UploadHandler, type UploadProtocol, type UploadSizeContext, type UploadStorage, createR2BindingUploadStorage, createR2UploadStorage, createUploadContext, createUploadHandler };

package/dist/upload.mjs

@@ -1 +1 @@
-import{createR2UploadStorage as r,createUploadHandler as o}from"./packem_shared/createR2UploadStorage-BSgOjRvv.mjs";export{r as createR2UploadStorage,o as createUploadHandler};
+import{createR2BindingUploadStorage as r}from"./packem_shared/createR2BindingUploadStorage-Vjs0vyJJ.mjs";import{createR2UploadStorage as t}from"./packem_shared/createR2UploadStorage-DGB1xJiD.mjs";import{DEFAULT_MAX_UPLOAD_BYTES as d,createUploadContext as U,createUploadHandler as l}from"./packem_shared/DEFAULT_MAX_UPLOAD_BYTES-BOaXqwP5.mjs";import{R}from"./packem_shared/r2-upload-part-writer-SdQlWaAu.mjs";export{d as DEFAULT_MAX_UPLOAD_BYTES,R as R2_PART_SIZE,r as createR2BindingUploadStorage,t as createR2UploadStorage,U as createUploadContext,l as createUploadHandler};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/storage",
-  "version": "1.0.0-alpha.13",
+  "version": "1.0.0-alpha.131",
   "description": "R2-backed storage for Lunora: typed buckets and signed URLs",
   "keywords": [
     "cloudflare",
@@ -50,8 +50,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/errors": "1.0.0-alpha.9",
-    "@visulima/storage": "1.0.5",
+    "@lunora/errors": ">=1.0.0-alpha.51 <2.0.0-0",
+    "@lunora/platform": "1.0.0-alpha.63",
+    "@visulima/storage": "2.0.37",
     "aws4fetch": "1.0.20"
   },
   "engines": {

package/dist/packem_shared/buildPresignedUrl-TCv-5TAT.mjs

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