@lunora/storage 1.0.0-alpha.10 → 1.0.0-alpha.11

package/dist/packem_shared/createR2UploadStorage-BfLIpWdf.mjs

@@ -0,0 +1,54 @@
+import { Rest, Multipart, Tus } from '@visulima/storage/handler/http/fetch';
+import { AwsLightStorage } from '@visulima/storage/provider/aws-light';
+
+const TUS_RESUMABLE = "1.0.0";
+const denyResponse = (protocol) => {
+  const headers = { "content-type": "application/json" };
+  if (protocol === "tus") {
+    headers["Tus-Resumable"] = TUS_RESUMABLE;
+  }
+  return Response.json({ error: { code: "FORBIDDEN", message: "Upload denied by authorization policy", name: "ForbiddenError" } }, { headers, status: 403 });
+};
+const instantiateHandler = (protocol, handlerOptions) => {
+  if (protocol === "chunked-rest") {
+    return new Rest(handlerOptions);
+  }
+  if (protocol === "multipart") {
+    return new Multipart(handlerOptions);
+  }
+  return new Tus(handlerOptions);
+};
+const createUploadHandler = (options) => {
+  const protocol = options.protocol ?? "tus";
+  const handlerOptions = {
+    storage: options.storage,
+    ...options.maxFileSize === void 0 ? {} : { maxFileSize: options.maxFileSize }
+  };
+  const handler = instantiateHandler(protocol, handlerOptions);
+  const { authorize } = options;
+  const fetch = async (request) => {
+    if (authorize !== void 0) {
+      try {
+        const allowed = await authorize({ method: request.method, protocol, request, url: new URL(request.url) });
+        if (!allowed) {
+          return denyResponse(protocol);
+        }
+      } catch {
+        return denyResponse(protocol);
+      }
+    }
+    return handler.fetch(request);
+  };
+  return { fetch, protocol };
+};
+const createR2UploadStorage = (options) => new AwsLightStorage({
+  accessKeyId: options.accessKeyId,
+  bucket: options.bucket,
+  endpoint: options.endpoint ?? `https://${options.accountId}.r2.cloudflarestorage.com`,
+  path: options.path ?? "/",
+  region: "auto",
+  secretAccessKey: options.secretAccessKey,
+  ...options.partSize === void 0 ? {} : { partSize: options.partSize }
+});
+
+export { createR2UploadStorage, createUploadHandler };

package/dist/upload.d.mts

@@ -0,0 +1,91 @@
+import { Tus } from '@visulima/storage/handler/http/fetch';
+import { AwsLightStorage } from '@visulima/storage/provider/aws-light';
+/** Resumable upload wire protocols the handler can speak. */
+type UploadProtocol = "chunked-rest" | "multipart" | "tus";
+type UploadHandlerOptions = ConstructorParameters<typeof Tus>[0];
+/** A `@visulima/storage` storage provider (e.g. {@link createR2UploadStorage} or a memory provider in tests). */
+type UploadStorage = UploadHandlerOptions["storage"];
+/**
+ * The context handed to {@link CreateUploadHandlerOptions.authorize}. Everything
+ * needed to make an RLS decision: the raw `request` (headers/cookies/auth), the
+ * `method`, the parsed `url`, and which `protocol` the handler speaks.
+ */
+interface UploadAuthzContext {
+  /** The upload method being invoked (`POST` create, `PATCH` chunk, `HEAD` resume, `DELETE`). */
+  method: string;
+  /** The protocol this handler is mounted for. */
+  protocol: UploadProtocol;
+  /** The inbound request — inspect headers/cookies to resolve the caller's identity. */
+  request: Request;
+  /** The parsed request URL (query params, upload-id path segment). */
+  url: URL;
+}
+/** Options for {@link createUploadHandler}. */
+interface CreateUploadHandlerOptions {
+  /**
+   * 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.
+   */
+  authorize?: (context: UploadAuthzContext) => boolean | Promise<boolean>;
+  /** Maximum accepted file size in bytes (forwarded to the multipart parser). */
+  maxFileSize?: number;
+  /** Which protocol to speak. Default `"tus"` (the resumable, pause/resume-capable one). */
+  protocol?: UploadProtocol;
+  /** The storage provider the bytes land in (R2 in prod, memory in tests). */
+  storage: UploadStorage;
+}
+/** The object returned by {@link createUploadHandler}. */
+interface UploadHandler {
+  /**
+   * Handle one upload request. Runs the RLS gate, then delegates to the
+   * `@visulima/storage` protocol handler. Wire this into your Worker's routing
+   * for the path the client uploads to.
+   */
+  fetch: (request: Request) => Promise<Response>;
+  /** The protocol this handler speaks. */
+  protocol: UploadProtocol;
+}
+/** R2 (S3-compatible) credentials + bucket for {@link createR2UploadStorage}. */
+interface R2UploadStorageOptions {
+  /** R2 S3 API Access Key ID (from an R2 API token). */
+  accessKeyId: string;
+  /** Cloudflare account id — used to derive the R2 S3 endpoint host. */
+  accountId: string;
+  /** 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`).
+   */
+  endpoint?: string;
+  /** Client-side multipart part size (bytes or a size string like `"16MB"`). */
+  partSize?: number | string;
+  /**
+   * Path prefix the handler is mounted on (must match the client endpoint's
+   * path). Default `"/"`.
+   */
+  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
+ * `@visulima/storage`'s dependency-light `aws-light` provider (`aws4fetch`, no
+ * AWS SDK). R2's S3 region alias is always `auto`.
+ *
+ * Requires an R2 **S3 API** token's Access Key ID / Secret Access Key — the
+ * same credential shape `@lunora/storage`'s presigned-URL helpers take. In a
+ * Worker the `aws-light` provider needs `nodejs_compat` (it imports
+ * `node:stream`).
+ */
+declare const createR2UploadStorage: (options: R2UploadStorageOptions & {
+  secretAccessKey: string;
+}) => AwsLightStorage;
+export { type CreateUploadHandlerOptions, type R2UploadStorageOptions, type UploadAuthzContext, type UploadHandler, type UploadProtocol, type UploadStorage, createR2UploadStorage, createUploadHandler };

package/dist/upload.d.ts

@@ -0,0 +1,91 @@
+import { Tus } from '@visulima/storage/handler/http/fetch';
+import { AwsLightStorage } from '@visulima/storage/provider/aws-light';
+/** Resumable upload wire protocols the handler can speak. */
+type UploadProtocol = "chunked-rest" | "multipart" | "tus";
+type UploadHandlerOptions = ConstructorParameters<typeof Tus>[0];
+/** A `@visulima/storage` storage provider (e.g. {@link createR2UploadStorage} or a memory provider in tests). */
+type UploadStorage = UploadHandlerOptions["storage"];
+/**
+ * The context handed to {@link CreateUploadHandlerOptions.authorize}. Everything
+ * needed to make an RLS decision: the raw `request` (headers/cookies/auth), the
+ * `method`, the parsed `url`, and which `protocol` the handler speaks.
+ */
+interface UploadAuthzContext {
+  /** The upload method being invoked (`POST` create, `PATCH` chunk, `HEAD` resume, `DELETE`). */
+  method: string;
+  /** The protocol this handler is mounted for. */
+  protocol: UploadProtocol;
+  /** The inbound request — inspect headers/cookies to resolve the caller's identity. */
+  request: Request;
+  /** The parsed request URL (query params, upload-id path segment). */
+  url: URL;
+}
+/** Options for {@link createUploadHandler}. */
+interface CreateUploadHandlerOptions {
+  /**
+   * 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.
+   */
+  authorize?: (context: UploadAuthzContext) => boolean | Promise<boolean>;
+  /** Maximum accepted file size in bytes (forwarded to the multipart parser). */
+  maxFileSize?: number;
+  /** Which protocol to speak. Default `"tus"` (the resumable, pause/resume-capable one). */
+  protocol?: UploadProtocol;
+  /** The storage provider the bytes land in (R2 in prod, memory in tests). */
+  storage: UploadStorage;
+}
+/** The object returned by {@link createUploadHandler}. */
+interface UploadHandler {
+  /**
+   * Handle one upload request. Runs the RLS gate, then delegates to the
+   * `@visulima/storage` protocol handler. Wire this into your Worker's routing
+   * for the path the client uploads to.
+   */
+  fetch: (request: Request) => Promise<Response>;
+  /** The protocol this handler speaks. */
+  protocol: UploadProtocol;
+}
+/** R2 (S3-compatible) credentials + bucket for {@link createR2UploadStorage}. */
+interface R2UploadStorageOptions {
+  /** R2 S3 API Access Key ID (from an R2 API token). */
+  accessKeyId: string;
+  /** Cloudflare account id — used to derive the R2 S3 endpoint host. */
+  accountId: string;
+  /** 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`).
+   */
+  endpoint?: string;
+  /** Client-side multipart part size (bytes or a size string like `"16MB"`). */
+  partSize?: number | string;
+  /**
+   * Path prefix the handler is mounted on (must match the client endpoint's
+   * path). Default `"/"`.
+   */
+  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
+ * `@visulima/storage`'s dependency-light `aws-light` provider (`aws4fetch`, no
+ * AWS SDK). R2's S3 region alias is always `auto`.
+ *
+ * Requires an R2 **S3 API** token's Access Key ID / Secret Access Key — the
+ * same credential shape `@lunora/storage`'s presigned-URL helpers take. In a
+ * Worker the `aws-light` provider needs `nodejs_compat` (it imports
+ * `node:stream`).
+ */
+declare const createR2UploadStorage: (options: R2UploadStorageOptions & {
+  secretAccessKey: string;
+}) => AwsLightStorage;
+export { type CreateUploadHandlerOptions, type R2UploadStorageOptions, type UploadAuthzContext, type UploadHandler, type UploadProtocol, type UploadStorage, createR2UploadStorage, createUploadHandler };

package/dist/upload.mjs

@@ -0,0 +1 @@
+export { createR2UploadStorage, createUploadHandler } from './packem_shared/createR2UploadStorage-BfLIpWdf.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/storage",
-  "version": "1.0.0-alpha.10",
+  "version": "1.0.0-alpha.11",
   "description": "R2-backed storage for Lunora: typed buckets and signed URLs",
   "keywords": [
     "cloudflare",
@@ -40,13 +40,19 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs"
     },
+    "./upload": {
+      "types": "./dist/upload.d.ts",
+      "import": "./dist/upload.mjs"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@lunora/errors": "1.0.0-alpha.6"
+    "@lunora/errors": "1.0.0-alpha.7",
+    "@visulima/storage": "1.0.5",
+    "aws4fetch": "1.0.20"
   },
   "engines": {
     "node": "^22.15.0 || >=24.11.0"