@lunora/storage 1.0.0-alpha.7 → 1.0.0-alpha.71

package/dist/packem_shared/createBucketStorage-AqIMq050.mjs

@@ -0,0 +1 @@
+import{LunoraError as n}from"@lunora/errors";const g=(e,a={})=>{const o=Object.keys(e),[u]=o;if(u===void 0)throw new n("INTERNAL","@lunora/storage: createBucketStorage requires at least one bucket");if(a.default!==void 0&&!Object.hasOwn(e,a.default))throw new n("INTERNAL",`@lunora/storage: default bucket "${a.default}" is not in the bucket map (have: ${o.join(", ")})`);const t=a.default??(e.default?"default":u),c=e[t];if(c===void 0)throw new n("INTERNAL",`@lunora/storage: default bucket "${t}" is not in the bucket map (have: ${o.join(", ")})`);const s=[...new Set([t,...o])],d=r=>{const f=Object.hasOwn(e,r)?e[r]:void 0,i=r===t?c:f;if(!i)throw new n("INTERNAL",`@lunora/storage: no bucket registered for "${r}". Known buckets: ${s.join(", ")}`);return{...i,bucket:l=>d(l),bucketName:r}};return d(t)};export{g as createBucketStorage};

package/dist/packem_shared/createStorage-YPzdUgGl.mjs

@@ -0,0 +1 @@
+import{LunoraError as n}from"@lunora/errors";import{t as U,h as M,a as I,b as f}from"./internal-B5yyxF10.mjs";import{buildPresignedUrl as S}from"./buildPresignedUrl-U55ktL8x.mjs";import{buildSignedUrl as _}from"./buildSignedUrl-czz1xjLU.mjs";const w=1024,v=1e3,k=100,A=16*1024*1024,D=e=>{const a=e.checksums?.sha256;if(a===void 0)return e;const c=f(a),l=I(new Uint8Array(a));return new Proxy(e,{get(u,s){if(s==="sha256")return c;if(s==="sha256Base64")return l;const d=Reflect.get(u,s,u);return typeof d=="function"?d.bind(u):d},has(u,s){return s==="sha256"||s==="sha256Base64"||Reflect.has(u,s)}})},B=e=>{const a=e.checksums?.sha256;return{contentType:e.httpMetadata?.contentType,customMetadata:e.customMetadata,key:e.key,sha256:a===void 0?void 0:f(a),size:e.size,uploaded:e.uploaded===void 0?void 0:e.uploaded.getTime()}},y=e=>{const a=e.checksums?.sha256;return{checksums:e.checksums,customMetadata:e.customMetadata,etag:e.etag,httpEtag:e.httpEtag,httpMetadata:e.httpMetadata,key:e.key,sha256:a===void 0?void 0:f(a),sha256Base64:a===void 0?void 0:I(new Uint8Array(a)),size:e.size,uploaded:e.uploaded}},O=async(e,a)=>{let c=0;const l=s=>s instanceof ArrayBuffer?new Uint8Array(s):ArrayBuffer.isView(s)?new Uint8Array(s.buffer,s.byteOffset,s.byteLength):void 0,u=new TransformStream({transform(s,d){const m=l(s);if(m===void 0){d.error(new n("VALIDATION_ERROR","@lunora/storage: stream chunk is not a byte chunk; cannot enforce maxSize"));return}if(c+=m.byteLength,c>a){d.error(new n("PAYLOAD_TOO_LARGE",`@lunora/storage: stream body exceeds maxSize (> ${String(a)} bytes)`));return}d.enqueue(m)}});return await new Response(e.pipeThrough(u)).blob()},V=new TextEncoder,R=e=>V.encode(e).length,x=e=>{if(e instanceof ArrayBuffer||ArrayBuffer.isView(e))return e.byteLength;if(typeof e=="string")return R(e);if(typeof e!="object"||e===null)return;const{size:a}=e;return typeof a=="number"?a:void 0},$=async(e,a)=>{if(!Number.isFinite(a)||a<0)throw new n("VALIDATION_ERROR",`@lunora/storage: maxSize must be a finite, non-negative number (received ${String(a)})`);if(e instanceof ReadableStream){if(a>A)throw new n("VALIDATION_ERROR",`@lunora/storage: maxSize ${String(a)} exceeds the ${String(A)}-byte ceiling for a streamed body, which must be buffered to be capped — use createMultipartUpload() or createUploadHandler() for objects this large`);return await O(e,a)}const c=x(e);if(c===void 0)throw new n("VALIDATION_ERROR","@lunora/storage: cannot measure body length, so maxSize cannot be enforced");if(c>a)throw new n("PAYLOAD_TOO_LARGE",`@lunora/storage: body exceeds maxSize (${String(c)} > ${String(a)})`);return e},i=e=>{if(typeof e!="string"||e.length===0)throw new n("VALIDATION_ERROR","@lunora/storage: key must be a non-empty string");if(R(e)>w)throw new n("VALIDATION_ERROR",`@lunora/storage: key exceeds ${String(w)}-byte limit`);if(e.includes("\0"))throw new n("VALIDATION_ERROR","@lunora/storage: key contains NUL byte");if(M(e))throw new n("VALIDATION_ERROR","@lunora/storage: key contains a control character (including CR/LF)");if(e.startsWith("/"))throw new n("VALIDATION_ERROR","@lunora/storage: key must not start with `/`");if(e.split("/").includes(".."))throw new n("VALIDATION_ERROR","@lunora/storage: key contains a `..` path component")},C=e=>{if(e.allowedContentTypes!==void 0){if(e.contentType===void 0)throw new n("VALIDATION_ERROR","@lunora/storage: contentType is required when allowedContentTypes is set");if(!e.allowedContentTypes.includes(e.contentType))throw new n("VALIDATION_ERROR",`@lunora/storage: contentType "${e.contentType}" not in allowedContentTypes`)}},F=(e,a)=>{i(e),i(a);const l=`${e.endsWith("/")?e.slice(0,-1):e}/${a}`;if(R(l)>w)throw new n("VALIDATION_ERROR",`@lunora/storage: scoped key exceeds ${String(w)}-byte limit`);return l},X=e=>{if(!e.bucket)throw new n("INTERNAL","@lunora/storage: `bucket` is required");if(typeof e.bucketName!="string"||e.bucketName==="")throw new n("INTERNAL",'@lunora/storage: `bucketName` is required — pass the name this bucket is registered under (`"default"` for a single-bucket app)');const a=async(r,t,o={})=>{i(r),C(o);const g=o.maxSize===void 0?t:await $(t,o.maxSize),h=await e.bucket.put(r,g,{customMetadata:o.customMetadata,httpMetadata:o.contentType?{contentType:o.contentType}:void 0,...o.sha256===void 0?{}:{sha256:o.sha256}});return{etag:h.etag,httpEtag:h.httpEtag??`"${h.etag}"`,key:h.key}},c=async(r,t={})=>{i(r);const o=await(t.range?e.bucket.get(r,{range:t.range}):e.bucket.get(r));return o&&D(o)},l=async r=>{i(r),await e.bucket.delete(r)},u=async r=>{i(r);let t;if(e.bucket.head)t=await e.bucket.head(r);else{const o=await e.bucket.get(r);await o?.body?.cancel(),t=o}return t&&y(t)},s=async r=>{const t=await u(r);return t&&B(t)},d=async(r,t={})=>{if(r?.includes("\0"))throw new n("VALIDATION_ERROR","@lunora/storage: prefix contains NUL byte");if(t.limit!==void 0&&(!Number.isInteger(t.limit)||t.limit<=0))throw new n("VALIDATION_ERROR",`@lunora/storage: list limit must be a positive integer (received ${String(t.limit)})`);const o=Math.min(t.limit??k,v),g=await e.bucket.list({cursor:t.cursor,delimiter:t.delimiter,include:["customMetadata","httpMetadata"],limit:o,prefix:r}),{delimitedPrefixes:h}=g;return{cursor:g.cursor,delimitedPrefixes:h,objects:g.objects.map(E=>y(E)),truncated:g.truncated}},m=r=>{if(!e.publicBaseUrl)throw new n("INTERNAL","@lunora/storage: `publicBaseUrl` is required for getUrl()");i(r);const t=r.split("/").map(o=>encodeURIComponent(o)).join("/");return`${U(e.publicBaseUrl)}/${t}`},T=async(r,t={})=>{if(!e.publicBaseUrl)throw new n("INTERNAL","@lunora/storage: `publicBaseUrl` is required for getSignedUrl()");if(!e.signingSecret)throw new n("INTERNAL","@lunora/storage: `signingSecret` is required for getSignedUrl()");return i(r),_({baseUrl:e.publicBaseUrl,bucketName:e.bucketName,contentType:t.contentType,expiresInSeconds:t.expiresInSeconds,key:r,method:t.method,secret:e.signingSecret})},b=async(r,t={})=>{if(i(r),!e.bucket.createMultipartUpload)throw new n("INTERNAL","@lunora/storage: bucket binding does not support multipart uploads (createMultipartUpload)");return e.bucket.createMultipartUpload(r,{customMetadata:t.customMetadata,httpMetadata:t.contentType?{contentType:t.contentType}:void 0})},N=(r,t)=>{if(i(r),typeof t!="string"||t.length===0)throw new n("VALIDATION_ERROR","@lunora/storage: resumeMultipartUpload requires a non-empty uploadId");if(!e.bucket.resumeMultipartUpload)throw new n("INTERNAL","@lunora/storage: bucket binding does not support multipart uploads (resumeMultipartUpload)");return e.bucket.resumeMultipartUpload(r,t)},L=async(r,t={})=>{if(!e.s3)throw new n("INTERNAL","@lunora/storage: `s3` credentials are required for getPresignedUrl() — pass { accountId, accessKeyId, secretAccessKey, bucket }");return i(r),S({credentials:e.s3,expiresInSeconds:t.expiresInSeconds,key:r,method:t.method})},p=async(r,t={})=>T(r,{contentType:t.contentType,expiresInSeconds:t.expiresInSeconds,method:"PUT"});return{bucketName:e.bucketName,createMultipartUpload:b,delete:l,download:c,generateUploadUrl:p,getMetadata:s,getPresignedUrl:L,getSignedUrl:T,getUrl:m,head:u,list:d,resumeMultipartUpload:N,store:a,upload:a}};export{X as createStorage,F as scopeKey};

package/dist/packem_shared/internal-B5yyxF10.mjs

@@ -0,0 +1 @@
+const p=t=>{let n="";for(let r=0;r<t.length;r+=32768)n+=String.fromCharCode(...t.subarray(r,r+32768));return btoa(n)},d=t=>{const n=atob(t),e=new Uint8Array(n.length);for(let r=0;r<n.length;r+=1)e[r]=n.codePointAt(r)??0;return e},s="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_",u=t=>{let n="",e=0;const r=t.length-2;for(;e<r;e+=3){const o=t[e]<<16|t[e+1]<<8|t[e+2];n+=s.charAt(o>>18&63)+s.charAt(o>>12&63)+s.charAt(o>>6&63)+s.charAt(o&63)}const c=t.length-e;if(c===1){const o=t[e]<<16;n+=s.charAt(o>>18&63)+s.charAt(o>>12&63)}else if(c===2){const o=t[e]<<16|t[e+1]<<8;n+=s.charAt(o>>18&63)+s.charAt(o>>12&63)+s.charAt(o>>6&63)}return n},_=t=>{const n=t.replaceAll("-","+").replaceAll("_","/"),e=n+"=".repeat((4-n.length%4)%4);return d(e)},A=(t,n)=>{if(t.size<n)return;const e=t.keys().next().value;e!==void 0&&t.delete(e)},f=(t,n,e,r)=>{const c=t.get(n);if(c!==void 0)return c;A(t,r);const o=e().catch(h=>{throw t.get(n)===o&&t.delete(n),h});return t.set(n,o),o},a=new TextEncoder,w=10080*60,g=/^[a-z][a-z0-9+\-.]*:\/\//i,y=Array.from({length:32},(t,n)=>n),i=new RegExp(`[${y.map(t=>String.fromCodePoint(t)).join("")}]`,"u"),C=64,S=new Map,l=async t=>f(S,t,async()=>crypto.subtle.importKey("raw",a.encode(t),{hash:"SHA-256",name:"HMAC"},!1,["sign","verify"]),C),m=t=>{try{return new URL(t).host}catch{return t.replace(g,"").split("/")[0]??""}},H=t=>{if(i.test(t))throw new TypeError("hmac-url: value must not contain control characters (including CR/LF)")},R=t=>i.test(t),E=/^\/+$/u,x=t=>E.test(t),L=(t,n)=>{if(!Number.isFinite(t)||t<=0)return"expiresInSeconds must be a positive finite number";if(t>n){const e=` (${String(n/86400)} days)`;return`expiresInSeconds must not exceed ${String(n)} seconds${e}`}},T=async(t,n)=>{const e=await l(t),r=await crypto.subtle.sign("HMAC",e,a.encode(n));return u(new Uint8Array(r))},O=async(t,n,e)=>{const r=await l(t);return crypto.subtle.verify("HMAC",r,e,a.encode(n))},v=t=>{const n=new Uint8Array(t);let e="";for(const r of n)e+=r.toString(16).padStart(2,"0");return e},M=t=>{let n=t.length;for(;n>0&&t[n-1]==="/";)n-=1;return t.slice(0,n)};export{w as M,p as a,v as b,H as c,O as d,m as e,_ as f,R as h,x as i,T as s,M as t,L as v};

package/dist/upload.d.mts

@@ -0,0 +1,175 @@
+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";
+/**
+ * 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). */
+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.
+   *
+   * 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) => boolean | Promise<boolean>;
+  /**
+   * 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.
+   */
+  maxFileSize?: number;
+  /** 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;
+}
+/** 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://<accountId>.r2.cloudflarestorage.com`. Pass this to pin a
+   * jurisdiction (e.g. `<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 {
+/**
+ * `@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.
+ */
+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.
+ */
+type R2UploadStorageOptions,
+/**
+ * `@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.
+ */
+type UploadAuthzContext,
+/**
+ * `@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.
+ */
+type UploadHandler,
+/**
+ * `@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.
+ */
+type UploadProtocol,
+/**
+ * `@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.
+ */
+type UploadStorage, createR2UploadStorage, createUploadHandler };

package/dist/upload.d.ts

@@ -0,0 +1,175 @@
+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";
+/**
+ * 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). */
+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.
+   *
+   * 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) => boolean | Promise<boolean>;
+  /**
+   * 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.
+   */
+  maxFileSize?: number;
+  /** 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;
+}
+/** 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://<accountId>.r2.cloudflarestorage.com`. Pass this to pin a
+   * jurisdiction (e.g. `<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 {
+/**
+ * `@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.
+ */
+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.
+ */
+type R2UploadStorageOptions,
+/**
+ * `@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.
+ */
+type UploadAuthzContext,
+/**
+ * `@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.
+ */
+type UploadHandler,
+/**
+ * `@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.
+ */
+type UploadProtocol,
+/**
+ * `@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.
+ */
+type UploadStorage, createR2UploadStorage, createUploadHandler };

package/dist/upload.mjs

@@ -0,0 +1 @@
+import{DEFAULT_MAX_UPLOAD_BYTES as r,createR2UploadStorage as o,createUploadHandler as t}from"./packem_shared/DEFAULT_MAX_UPLOAD_BYTES-CO3auxph.mjs";export{r as DEFAULT_MAX_UPLOAD_BYTES,o as createR2UploadStorage,t as createUploadHandler};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/storage",
-  "version": "1.0.0-alpha.7",
+  "version": "1.0.0-alpha.71",
   "description": "R2-backed storage for Lunora: typed buckets and signed URLs",
   "keywords": [
     "cloudflare",
@@ -40,13 +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.3"
+    "@lunora/errors": "1.0.0-alpha.37",
+    "@lunora/platform": "1.0.0-alpha.32",
+    "@visulima/storage": "2.0.8",
+    "aws4fetch": "1.0.20"
   },
   "engines": {
     "node": "^22.15.0 || >=24.11.0"

package/dist/packem_shared/buildPresignedUrl-DzPwi1bY.mjs

@@ -1,70 +0,0 @@
-const REGION = "auto";
-const SERVICE = "s3";
-const ALGORITHM = "AWS4-HMAC-SHA256";
-const MIN_EXPIRES_SECONDS = 1;
-const MAX_EXPIRES_SECONDS = 7 * 24 * 60 * 60;
-const DEFAULT_EXPIRES_SECONDS = 900;
-const textEncoder = new TextEncoder();
-const compareEntries = (a, b) => {
-  if (a[0] < b[0]) {
-    return -1;
-  }
-  return a[0] > b[0] ? 1 : 0;
-};
-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 encodeRfc3986 = (value) => encodeURIComponent(value).replaceAll(/[!'()*]/gu, (char) => `%${char.codePointAt(0)?.toString(16).toUpperCase() ?? ""}`);
-const encodeKey = (key) => key.split("/").map((segment) => encodeRfc3986(segment)).join("/");
-const sha256Hex = async (input) => toHex(await crypto.subtle.digest("SHA-256", textEncoder.encode(input)));
-const hmac = async (key, message) => {
-  const cryptoKey = await crypto.subtle.importKey("raw", key, { hash: "SHA-256", name: "HMAC" }, false, ["sign"]);
-  return crypto.subtle.sign("HMAC", cryptoKey, textEncoder.encode(message));
-};
-const deriveSigningKey = async (secretAccessKey, dateStamp) => {
-  const dateKey = await hmac(textEncoder.encode(`AWS4${secretAccessKey}`), dateStamp);
-  const regionKey = await hmac(dateKey, REGION);
-  const serviceKey = await hmac(regionKey, SERVICE);
-  return hmac(serviceKey, "aws4_request");
-};
-const endpointHost = (credentials) => {
-  const infix = credentials.jurisdiction === void 0 ? "" : `${credentials.jurisdiction}.`;
-  return `${credentials.accountId}.${infix}r2.cloudflarestorage.com`;
-};
-const formatAmzDate = (date) => {
-  const amzDate = `${date.toISOString().replaceAll(/[:-]/gu, "").slice(0, 15)}Z`;
-  return { amzDate, dateStamp: amzDate.slice(0, 8) };
-};
-const buildPresignedUrl = async (parameters) => {
-  const { credentials, key } = parameters;
-  const method = parameters.method ?? "GET";
-  const requested = parameters.expiresInSeconds ?? DEFAULT_EXPIRES_SECONDS;
-  const normalised = Number.isFinite(requested) ? requested : DEFAULT_EXPIRES_SECONDS;
-  const expires = Math.min(Math.max(MIN_EXPIRES_SECONDS, Math.floor(normalised)), MAX_EXPIRES_SECONDS);
-  const host = endpointHost(credentials);
-  const date = new Date(parameters.now?.() ?? Date.now());
-  const { amzDate, dateStamp } = formatAmzDate(date);
-  const credentialScope = `${dateStamp}/${REGION}/${SERVICE}/aws4_request`;
-  const canonicalUri = `/${encodeRfc3986(credentials.bucket)}/${encodeKey(key)}`;
-  const query = [
-    ["X-Amz-Algorithm", ALGORITHM],
-    ["X-Amz-Credential", `${credentials.accessKeyId}/${credentialScope}`],
-    ["X-Amz-Date", amzDate],
-    ["X-Amz-Expires", expires.toString()],
-    ["X-Amz-SignedHeaders", "host"]
-  ];
-  const canonicalQuery = query.map(([name, value]) => [encodeRfc3986(name), encodeRfc3986(value)]).toSorted(compareEntries).map(([name, value]) => `${name}=${value}`).join("&");
-  const canonicalRequest = [method, canonicalUri, canonicalQuery, `host:${host}
-`, "host", "UNSIGNED-PAYLOAD"].join("\n");
-  const stringToSign = [ALGORITHM, amzDate, credentialScope, await sha256Hex(canonicalRequest)].join("\n");
-  const signingKey = await deriveSigningKey(credentials.secretAccessKey, dateStamp);
-  const signature = toHex(await hmac(signingKey, stringToSign));
-  return `https://${host}${canonicalUri}?${canonicalQuery}&X-Amz-Signature=${signature}`;
-};
-
-export { buildPresignedUrl };

package/dist/packem_shared/buildSignedUrl-DX535yKv.mjs

@@ -1,116 +0,0 @@
-import { LunoraError } from '@lunora/errors';
-
-const textEncoder = new TextEncoder();
-const MAX_EXPIRES_IN_SECONDS = 7 * 24 * 60 * 60;
-const SCHEME_PREFIX_RE = /^[a-z][a-z0-9+\-.]*:\/\//i;
-const LEADING_SLASH_RE = /^\//;
-const toBase64Url = (bytes) => {
-  const binary = String.fromCodePoint(...bytes);
-  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
-};
-const fromBase64Url = (input) => {
-  const padded = input.replaceAll("-", "+").replaceAll("_", "/") + "===".slice((input.length + 3) % 4);
-  const binary = atob(padded);
-  const bytes = new Uint8Array(binary.length);
-  for (let index = 0; index < binary.length; index += 1) {
-    bytes[index] = binary.codePointAt(index) ?? 0;
-  }
-  return bytes;
-};
-const KEY_CACHE_MAX = 64;
-const keyCache = /* @__PURE__ */ new Map();
-const importHmacKey = async (secret) => {
-  const cached = keyCache.get(secret);
-  if (cached) {
-    return cached;
-  }
-  if (keyCache.size >= KEY_CACHE_MAX) {
-    const oldest = keyCache.keys().next().value;
-    if (oldest !== void 0) {
-      keyCache.delete(oldest);
-    }
-  }
-  const keyPromise = crypto.subtle.importKey("raw", textEncoder.encode(secret), { hash: "SHA-256", name: "HMAC" }, false, ["sign", "verify"]);
-  keyCache.set(secret, keyPromise);
-  return keyPromise;
-};
-const canonicalize = (method, host, key, exp, contentType) => {
-  const base = `${method}
-${host.toLowerCase()}
-${key}
-${String(exp)}`;
-  return contentType === void 0 ? base : `${base}
-${contentType}`;
-};
-const extractHost = (input) => {
-  try {
-    return new URL(input).host;
-  } catch {
-    const noScheme = input.replace(SCHEME_PREFIX_RE, "");
-    return noScheme.split("/")[0] ?? "";
-  }
-};
-const buildSignedUrl = async (args) => {
-  const method = args.method ?? "GET";
-  const expiresInSeconds = args.expiresInSeconds ?? 60 * 60;
-  if (!Number.isFinite(expiresInSeconds) || expiresInSeconds <= 0) {
-    throw new LunoraError("INTERNAL", "@lunora/storage: expiresInSeconds must be a positive finite number");
-  }
-  if (expiresInSeconds > MAX_EXPIRES_IN_SECONDS) {
-    throw new LunoraError("INTERNAL", `@lunora/storage: expiresInSeconds must not exceed ${String(MAX_EXPIRES_IN_SECONDS)} (7 days)`);
-  }
-  const contentType = method === "PUT" ? args.contentType : void 0;
-  const exp = Math.floor(Date.now() / 1e3) + expiresInSeconds;
-  const host = extractHost(args.baseUrl);
-  const cryptoKey = await importHmacKey(args.secret);
-  const signature = await crypto.subtle.sign("HMAC", cryptoKey, textEncoder.encode(canonicalize(method, host, args.key, exp, contentType)));
-  const sig = toBase64Url(new Uint8Array(signature));
-  const base = args.baseUrl.endsWith("/") ? args.baseUrl.slice(0, -1) : args.baseUrl;
-  const safeKey = args.key.split("/").map((segment) => encodeURIComponent(segment)).join("/");
-  const ctParameter = contentType === void 0 ? "" : `&ct=${encodeURIComponent(contentType)}`;
-  return `${base}/${safeKey}?exp=${String(exp)}&method=${method}&sig=${sig}${ctParameter}`;
-};
-const verifySignedUrl = async (input, secret, options) => {
-  let url;
-  try {
-    url = input instanceof URL ? input : new URL(input);
-  } catch {
-    return { reason: "malformed", valid: false };
-  }
-  const expRaw = url.searchParams.get("exp");
-  const exp = expRaw === null ? Number.NaN : Number(expRaw);
-  const sig = url.searchParams.get("sig");
-  const method = url.searchParams.get("method") ?? "GET";
-  const contentType = url.searchParams.get("ct") ?? void 0;
-  if (!sig || !Number.isInteger(exp)) {
-    return { reason: "malformed", valid: false };
-  }
-  if (exp < Math.floor(Date.now() / 1e3)) {
-    return { reason: "expired", valid: false };
-  }
-  if (method !== "GET" && method !== "PUT") {
-    return { reason: "malformed", valid: false };
-  }
-  let key;
-  let sigBytes;
-  try {
-    key = url.pathname.replace(LEADING_SLASH_RE, "").split("/").map((segment) => decodeURIComponent(segment)).join("/");
-    sigBytes = fromBase64Url(sig);
-  } catch {
-    return { reason: "malformed", valid: false };
-  }
-  const host = options?.expectedHost === void 0 ? url.host : extractHost(options.expectedHost);
-  const cryptoKey = await importHmacKey(secret);
-  const valid = await crypto.subtle.verify(
-    "HMAC",
-    cryptoKey,
-    sigBytes,
-    textEncoder.encode(canonicalize(method, host, key, exp, contentType))
-  );
-  if (!valid) {
-    return { reason: "bad_signature", valid: false };
-  }
-  return { contentType, key, method, valid: true };
-};
-
-export { buildSignedUrl, verifySignedUrl };

package/dist/packem_shared/createBucketStorage-JYdrS4e5.mjs

@@ -1,28 +0,0 @@
-import { LunoraError } from '@lunora/errors';
-
-const createBucketStorage = (buckets, options = {}) => {
-  const names = Object.keys(buckets);
-  const [firstName] = names;
-  if (firstName === void 0) {
-    throw new LunoraError("INTERNAL", "@lunora/storage: createBucketStorage requires at least one bucket");
-  }
-  if (options.default !== void 0 && !buckets[options.default]) {
-    throw new LunoraError("INTERNAL", `@lunora/storage: default bucket "${options.default}" is not in the bucket map (have: ${names.join(", ")})`);
-  }
-  const defaultTag = options.default ?? "default";
-  const defaultBinding = buckets[defaultTag] ?? buckets[firstName];
-  if (defaultBinding === void 0) {
-    throw new LunoraError("INTERNAL", `@lunora/storage: default bucket "${defaultTag}" is not in the bucket map (have: ${names.join(", ")})`);
-  }
-  const addressable = [.../* @__PURE__ */ new Set([defaultTag, ...names])];
-  const make = (name) => {
-    const target = name === defaultTag ? defaultBinding : buckets[name];
-    if (!target) {
-      throw new LunoraError("INTERNAL", `@lunora/storage: no bucket registered for "${name}". Known buckets: ${addressable.join(", ")}`);
-    }
-    return { ...target, bucket: (next) => make(next), bucketName: name };
-  };
-  return make(defaultTag);
-};
-
-export { createBucketStorage };