@lunora/storage 1.0.0-alpha.1 → 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/packem_shared/{scopeKey-Bs_iJ1Mx.mjs → createStorage-Bu6GJB25.mjs}

@@ -1,17 +1,11 @@
-import { buildPresignedUrl } from './buildPresignedUrl-DzPwi1bY.mjs';
-import { buildSignedUrl } from './buildSignedUrl-ZzB16yPl.mjs';
+import { LunoraError } from '@lunora/errors';
+import { t as trimTrailingSlashes, a as toHex } from './internal-Dqk0MrAj.mjs';
+import { buildPresignedUrl } from './buildPresignedUrl-B5f1wvz6.mjs';
+import { buildSignedUrl } from './buildSignedUrl-rt-6azia.mjs';
 
 const MAX_KEY_LENGTH = 1024;
 const MAX_LIST_LIMIT = 1e3;
 const DEFAULT_LIST_LIMIT = 100;
-const toHex = (buffer) => {
-  const bytes = new Uint8Array(buffer);
-  let out = "";
-  for (const byte of bytes) {
-    out += byte.toString(16).padStart(2, "0");
-  }
-  return out;
-};
 const toBase64 = (buffer) => {
   const bytes = new Uint8Array(buffer);
   let binary = "";
@@ -54,17 +48,37 @@ const toMetadata = (object) => {
     uploaded: object.uploaded === void 0 ? void 0 : object.uploaded.getTime()
   };
 };
+const toListObject = (object) => {
+  const raw = object.checksums?.sha256;
+  return {
+    checksums: object.checksums,
+    customMetadata: object.customMetadata,
+    etag: object.etag,
+    httpEtag: object.httpEtag,
+    httpMetadata: object.httpMetadata,
+    key: object.key,
+    sha256: raw === void 0 ? void 0 : toHex(raw),
+    sha256Base64: raw === void 0 ? void 0 : toBase64(raw),
+    size: object.size,
+    uploaded: object.uploaded
+  };
+};
 const enforceStreamMaxSize = (stream, maxSize) => {
   let seen = 0;
   const byteLengthOf = (chunk) => {
     if (chunk instanceof ArrayBuffer) {
       return chunk.byteLength;
     }
-    return ArrayBuffer.isView(chunk) ? chunk.byteLength : 0;
+    return ArrayBuffer.isView(chunk) ? chunk.byteLength : void 0;
   };
   const counter = new TransformStream({
     transform(chunk, controller) {
-      seen += byteLengthOf(chunk);
+      const length = byteLengthOf(chunk);
+      if (length === void 0) {
+        controller.error(new Error("@lunora/storage: stream chunk is not a byte chunk; cannot enforce maxSize"));
+        return;
+      }
+      seen += length;
       if (seen > maxSize) {
         controller.error(new Error(`@lunora/storage: stream body exceeds maxSize (> ${String(maxSize)} bytes)`));
         return;
@@ -74,30 +88,23 @@ const enforceStreamMaxSize = (stream, maxSize) => {
   });
   return stream.pipeThrough(counter);
 };
-const trimTrailingSlashes = (value) => {
-  let end = value.length;
-  while (end > 0 && value[end - 1] === "/") {
-    end -= 1;
-  }
-  return value.slice(0, end);
-};
 const validateKey = (key) => {
   if (typeof key !== "string" || key.length === 0) {
-    throw new Error("@lunora/storage: key must be a non-empty string");
+    throw new LunoraError("VALIDATION_ERROR", "@lunora/storage: key must be a non-empty string");
   }
   if (key.length > MAX_KEY_LENGTH) {
-    throw new Error(`@lunora/storage: key exceeds ${String(MAX_KEY_LENGTH)}-byte limit`);
+    throw new LunoraError("VALIDATION_ERROR", `@lunora/storage: key exceeds ${String(MAX_KEY_LENGTH)}-byte limit`);
   }
   if (key.includes("\0")) {
-    throw new Error("@lunora/storage: key contains NUL byte");
+    throw new LunoraError("VALIDATION_ERROR", "@lunora/storage: key contains NUL byte");
   }
   if (key.startsWith("/")) {
-    throw new Error("@lunora/storage: key must not start with `/`");
+    throw new LunoraError("VALIDATION_ERROR", "@lunora/storage: key must not start with `/`");
   }
   const segments = key.split("/");
   for (const segment of segments) {
     if (segment === "..") {
-      throw new Error("@lunora/storage: key contains a `..` path component");
+      throw new LunoraError("VALIDATION_ERROR", "@lunora/storage: key contains a `..` path component");
     }
   }
 };
@@ -107,22 +114,22 @@ const scopeKey = (prefix, key) => {
   const trimmedPrefix = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
   const composed = `${trimmedPrefix}/${key}`;
   if (composed.length > MAX_KEY_LENGTH) {
-    throw new Error(`@lunora/storage: scoped key exceeds ${String(MAX_KEY_LENGTH)}-byte limit`);
+    throw new LunoraError("VALIDATION_ERROR", `@lunora/storage: scoped key exceeds ${String(MAX_KEY_LENGTH)}-byte limit`);
   }
   return composed;
 };
 const createStorage = (options) => {
   if (!options.bucket) {
-    throw new Error("@lunora/storage: `bucket` is required");
+    throw new LunoraError("INTERNAL", "@lunora/storage: `bucket` is required");
   }
   const upload = async (key, body, uploadOptions = {}) => {
     validateKey(key);
     if (uploadOptions.allowedContentTypes !== void 0) {
       if (uploadOptions.contentType === void 0) {
-        throw new Error("@lunora/storage: contentType is required when allowedContentTypes is set");
+        throw new LunoraError("VALIDATION_ERROR", "@lunora/storage: contentType is required when allowedContentTypes is set");
       }
       if (!uploadOptions.allowedContentTypes.includes(uploadOptions.contentType)) {
-        throw new Error(`@lunora/storage: contentType "${uploadOptions.contentType}" not in allowedContentTypes`);
+        throw new LunoraError("VALIDATION_ERROR", `@lunora/storage: contentType "${uploadOptions.contentType}" not in allowedContentTypes`);
       }
     }
     let putBody = body;
@@ -134,7 +141,7 @@ const createStorage = (options) => {
         size = body.size;
       }
       if (size !== void 0 && size > uploadOptions.maxSize) {
-        throw new Error(`@lunora/storage: body exceeds maxSize (${String(size)} > ${String(uploadOptions.maxSize)})`);
+        throw new LunoraError("PAYLOAD_TOO_LARGE", `@lunora/storage: body exceeds maxSize (${String(size)} > ${String(uploadOptions.maxSize)})`);
       }
       if (body instanceof ReadableStream) {
         putBody = enforceStreamMaxSize(body, uploadOptions.maxSize);
@@ -166,16 +173,16 @@ const createStorage = (options) => {
   };
   const list = async (prefix, listOptions = {}) => {
     if (prefix?.includes("\0")) {
-      throw new Error("@lunora/storage: prefix contains NUL byte");
+      throw new LunoraError("VALIDATION_ERROR", "@lunora/storage: prefix contains NUL byte");
     }
     const requested = listOptions.limit ?? DEFAULT_LIST_LIMIT;
     const limit = Math.min(Math.max(1, Math.floor(requested)), MAX_LIST_LIMIT);
     const result = await options.bucket.list({ cursor: listOptions.cursor, delimiter: listOptions.delimiter, limit, prefix });
-    return { cursor: result.cursor, objects: result.objects.map((object) => withSha256(object)), truncated: result.truncated };
+    return { cursor: result.cursor, objects: result.objects.map((object) => toListObject(object)), truncated: result.truncated };
   };
   const getUrl = (key) => {
     if (!options.publicBaseUrl) {
-      throw new Error("@lunora/storage: `publicBaseUrl` is required for getUrl()");
+      throw new LunoraError("INTERNAL", "@lunora/storage: `publicBaseUrl` is required for getUrl()");
     }
     validateKey(key);
     const safeKey = key.split("/").map((segment) => encodeURIComponent(segment)).join("/");
@@ -183,10 +190,10 @@ const createStorage = (options) => {
   };
   const getSignedUrl = async (key, signedOptions = {}) => {
     if (!options.publicBaseUrl) {
-      throw new Error("@lunora/storage: `publicBaseUrl` is required for getSignedUrl()");
+      throw new LunoraError("INTERNAL", "@lunora/storage: `publicBaseUrl` is required for getSignedUrl()");
     }
     if (!options.signingSecret) {
-      throw new Error("@lunora/storage: `signingSecret` is required for getSignedUrl()");
+      throw new LunoraError("INTERNAL", "@lunora/storage: `signingSecret` is required for getSignedUrl()");
     }
     validateKey(key);
     return buildSignedUrl({
@@ -201,7 +208,7 @@ const createStorage = (options) => {
   const createMultipartUpload = async (key, multipartOptions = {}) => {
     validateKey(key);
     if (!options.bucket.createMultipartUpload) {
-      throw new Error("@lunora/storage: bucket binding does not support multipart uploads (createMultipartUpload)");
+      throw new LunoraError("INTERNAL", "@lunora/storage: bucket binding does not support multipart uploads (createMultipartUpload)");
     }
     return options.bucket.createMultipartUpload(key, {
       customMetadata: multipartOptions.customMetadata,
@@ -211,16 +218,19 @@ const createStorage = (options) => {
   const resumeMultipartUpload = (key, uploadId) => {
     validateKey(key);
     if (typeof uploadId !== "string" || uploadId.length === 0) {
-      throw new Error("@lunora/storage: resumeMultipartUpload requires a non-empty uploadId");
+      throw new LunoraError("VALIDATION_ERROR", "@lunora/storage: resumeMultipartUpload requires a non-empty uploadId");
     }
     if (!options.bucket.resumeMultipartUpload) {
-      throw new Error("@lunora/storage: bucket binding does not support multipart uploads (resumeMultipartUpload)");
+      throw new LunoraError("INTERNAL", "@lunora/storage: bucket binding does not support multipart uploads (resumeMultipartUpload)");
     }
     return options.bucket.resumeMultipartUpload(key, uploadId);
   };
   const getPresignedUrl = async (key, presignedOptions = {}) => {
     if (!options.s3) {
-      throw new Error("@lunora/storage: `s3` credentials are required for getPresignedUrl() — pass { accountId, accessKeyId, secretAccessKey, bucket }");
+      throw new LunoraError(
+        "INTERNAL",
+        "@lunora/storage: `s3` credentials are required for getPresignedUrl() — pass { accountId, accessKeyId, secretAccessKey, bucket }"
+      );
     }
     validateKey(key);
     return buildPresignedUrl({

package/dist/packem_shared/internal-Dqk0MrAj.mjs

@@ -0,0 +1,17 @@
+const toHex = (buffer) => {
+  const bytes = new Uint8Array(buffer);
+  let out = "";
+  for (const byte of bytes) {
+    out += byte.toString(16).padStart(2, "0");
+  }
+  return out;
+};
+const trimTrailingSlashes = (value) => {
+  let end = value.length;
+  while (end > 0 && value[end - 1] === "/") {
+    end -= 1;
+  }
+  return value.slice(0, end);
+};
+
+export { toHex as a, trimTrailingSlashes as t };

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.1",
+  "version": "1.0.0-alpha.11",
   "description": "R2-backed storage for Lunora: typed buckets and signed URLs",
   "keywords": [
     "cloudflare",
@@ -25,7 +25,7 @@
     "directory": "packages/storage"
   },
   "files": [
-    "dist",
+    "./dist",
     "__assets__",
     "README.md",
     "LICENSE.md"
@@ -40,11 +40,20 @@
       "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.7",
+    "@visulima/storage": "1.0.5",
+    "aws4fetch": "1.0.20"
+  },
   "engines": {
     "node": "^22.15.0 || >=24.11.0"
   }