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

package/README.md

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

package/dist/index.d.mts

@@ -1,134 +1,5 @@
-/**
- * A single-range read against R2: an `{ offset, length }` window (at least one
- * bound required, mirroring R2's own `R2Range`) or a `{ suffix }` tail. The
- * subset of `R2Range` that {@link Storage.download} forwards so a caller can
- * stream just the bytes it needs instead of the whole object.
- */
-type R2RangeLike = {
-  length: number;
-  offset?: number;
-} | {
-  length?: number;
-  offset: number;
-} | {
-  suffix: number;
-};
-/**
- * Minimal projection of `R2Bucket`. Declared structurally so unit tests can
- * pass a plain object double; the real binding satisfies the same shape.
- */
-interface R2BucketLike {
-  /**
-   * Begin a multipart upload (R2 `createMultipartUpload`). Optional so existing
-   * test doubles still satisfy the type; {@link Storage.createMultipartUpload}
-   * throws a clear error when the binding lacks it.
-   */
-  createMultipartUpload?: (key: string, options?: {
-    customMetadata?: Record<string, string>;
-    httpMetadata?: {
-      contentType?: string;
-    };
-  }) => Promise<R2MultipartUploadLike>;
-  delete: (key: string) => Promise<void>;
-  get: (key: string, options?: {
-    range?: R2RangeLike;
-  }) => Promise<R2ObjectBodyLike | null>;
-  /**
-   * Fetch an object's metadata without its body (R2 HEAD). Returns `null` when
-   * the object is absent. Declared optional so existing test doubles that only
-   * implement `get`/`put`/`list`/`delete` still satisfy the type; callers that
-   * need metadata fall back to a 0-length ranged `get()` when `head` is absent.
-   */
-  head?: (key: string) => Promise<R2ObjectLike | null>;
-  list: (options?: {
-    cursor?: string;
-    delimiter?: string;
-    limit?: number;
-    prefix?: string;
-  }) => Promise<{
-    cursor?: string;
-    objects: R2ObjectLike[];
-    truncated?: boolean;
-  }>;
-  put: (key: string, body: ReadableStream | ArrayBuffer | Blob | string | null, options?: {
-    customMetadata?: Record<string, string>;
-    httpMetadata?: {
-      contentType?: string;
-    };
-  }) => Promise<R2ObjectLike>;
-  /** Resume an in-progress multipart upload by id (R2 `resumeMultipartUpload`). Optional; see {@link Storage.resumeMultipartUpload}. */
-  resumeMultipartUpload?: (key: string, uploadId: string) => R2MultipartUploadLike;
-}
-/** One uploaded multipart part — returned by `uploadPart`, required to `complete`. Mirrors R2's `R2UploadedPart`. */
-interface R2UploadedPartLike {
-  etag: string;
-  partNumber: number;
-}
-/**
- * An in-progress multipart upload, mirroring R2's `R2MultipartUpload`. Each part
- * (except the last) must be uniform in size. The object does not guarantee the
- * underlying upload still exists — a parallel `complete`/`abort` can invalidate
- * it — so wrap each call in error handling.
- */
-interface R2MultipartUploadLike {
-  /** Abort the upload, discarding any uploaded parts. */
-  abort: () => Promise<void>;
-  /** Finish the upload from the collected parts; resolves to the stored object. */
-  complete: (uploadedParts: R2UploadedPartLike[]) => Promise<R2ObjectLike>;
-  /** The object key being assembled. */
-  readonly key: string;
-  /** The R2 upload id (persist it to resume across requests). */
-  readonly uploadId: string;
-  /** Upload one part (1-indexed); returns the `{ partNumber, etag }` to pass to `complete`. */
-  uploadPart: (partNumber: number, value: ArrayBuffer | ArrayBufferView | Blob | ReadableStream | string) => Promise<R2UploadedPartLike>;
-}
-interface R2ObjectLike {
-  /**
-   * R2-computed checksums. The real binding exposes `sha256` as an
-   * `ArrayBuffer` (present only when R2 stored a SHA-256 for the object);
-   * declared optional so fakes and non-checksummed objects type-check.
-   */
-  checksums?: {
-    sha256?: ArrayBuffer;
-  };
-  customMetadata?: Record<string, string>;
-  etag: string;
-  /**
-   * The quoted form of {@link R2ObjectLike.etag} (e.g. `"abc123"`), suitable
-   * for emitting directly as an HTTP `ETag` header. The real binding always
-   * provides it; declared optional so existing doubles that only set `etag`
-   * still type-check (callers fall back to quoting `etag`).
-   */
-  httpEtag?: string;
-  httpMetadata?: {
-    contentType?: string;
-  };
-  key: string;
-  /**
-   * Hex-encoded SHA-256 of the object body, surfaced by `download()`/`list()`
-   * when R2 carries a checksum (derived from {@link R2ObjectLike.checksums}).
-   */
-  sha256?: string;
-  /**
-   * Base64-encoded SHA-256 of the object body, surfaced alongside
-   * {@link R2ObjectLike.sha256} from the same checksum. Base64 is the encoding
-   * RFC 9530 digest headers (`Repr-Digest`/`Content-Digest`) require, so HTTP
-   * layers can emit a spec-compliant digest without re-deriving it.
-   */
-  sha256Base64?: string;
-  size: number;
-  /**
-   * When the object was written. The real binding exposes this as a `Date`;
-   * declared optional so fakes that omit it still type-check.
-   * {@link Storage.getMetadata} normalises it to epoch ms.
-   */
-  uploaded?: Date;
-}
-interface R2ObjectBodyLike extends R2ObjectLike {
-  arrayBuffer: () => Promise<ArrayBuffer>;
-  body: ReadableStream | null;
-  text: () => Promise<string>;
-}
+import { R2MultipartUploadLike, R2RangeLike, R2ObjectBodyLike, R2ObjectLike, R2BucketLike } from '@lunora/platform';
+export type { R2BucketLike, R2MultipartUploadLike, R2ObjectBodyLike, R2ObjectLike, R2RangeLike, R2UploadedPartLike } from '@lunora/platform';
 /**
  * R2 S3-API credentials for {@link Storage.getPresignedUrl}. These are an R2 API
  * token's Access Key ID / Secret Access Key (NOT a Cloudflare API token), plus
@@ -149,13 +20,27 @@ interface R2S3Credentials {
 }
 /** Options for {@link Storage.getPresignedUrl}. */
 interface PresignedUrlOptions {
-  /** Seconds the URL stays valid; clamped to [1, 604800]. Default 900. */
+  /** Seconds the URL stays valid: 1 to 604800 (7 days); an out-of-range value throws. Default 900. */
   expiresInSeconds?: number;
   /** HTTP method the URL authorizes. Default `GET`. */
   method?: "GET" | "PUT";
 }
 interface LunoraStorageOptions {
   bucket: R2BucketLike;
+  /**
+   * The name this bucket is registered under — the same string a
+   * `defineStorageRule({ bucket })` rule and the generated `StorageBucketName`
+   * union use. Bound into every signed URL's HMAC and mirrored on it as
+   * `&bucket=`, so a URL minted for one bucket can't be replayed against
+   * another sharing the signing secret, and the serving route can resolve
+   * which bucket to read.
+   *
+   * Required, and deliberately without a default: a defaulted name is how
+   * every bucket ended up signing as `"default"` and cross-verifying against
+   * each other. Pass `"default"` for a single-bucket app's `ctx.storage`, and
+   * the registered name for any bucket reached through `createBucketStorage`.
+   */
+  bucketName: string;
   /** Public base URL used by `getSignedUrl()`. Required for signed URLs. */
   publicBaseUrl?: string;
   /**
@@ -174,26 +59,50 @@ interface UploadOptions {
   customMetadata?: Record<string, string>;
   /**
    * Maximum body size in bytes. For `ArrayBuffer`/`Blob` sources the length is
-   * known up front and rejected before the upload starts. For a
-   * `ReadableStream` the length isn't known synchronously, so the stream is
-   * piped through a byte counter that aborts the upload once the limit is
-   * exceeded — this also guards against R2 silently accepting/truncating an
-   * unbounded stream.
+   * known up front and rejected before the upload starts.
+   *
+   * A `ReadableStream` has no length to check, and R2 refuses any stream whose
+   * length it cannot read — so a capped stream is READ INTO MEMORY under the
+   * cap and uploaded as a sized body. Nothing reaches the bucket if the body
+   * crosses the limit.
+   *
+   * `maxSize` is therefore also the memory ceiling for a streamed upload, and
+   * the isolate's ~128 MB is shared by every concurrent request — so on the
+   * stream path `maxSize` is itself capped at 16 MiB and rejected above it.
+   * For objects larger than that use `createMultipartUpload` /
+   * `createUploadHandler`, which upload without ever holding the whole object.
+   * Must be a finite, non-negative number; anything else (`Number(undefined)`
+   * is the usual source) is rejected as a `VALIDATION_ERROR`.
    */
   maxSize?: number;
+  /**
+   * SHA-256 of the body (hex or a 32-byte buffer), recorded with the object.
+   *
+   * R2 only reports a checksum it was given: without this, `list()`/`head()`
+   * return no `sha256` and any later integrity check degrades to comparing
+   * sizes. R2 also verifies the digest itself on write, so supplying it turns
+   * the upload into a checked one.
+   */
+  sha256?: ArrayBuffer | string;
 }
 interface ListOptions {
   cursor?: string;
   /** R2 list delimiter — when set, common prefixes group instead of listing. */
   delimiter?: string;
-  /** Defaults to 100, capped at 1000 (R2 limit). */
+  /**
+   * Defaults to 100, capped at 1000 (R2 limit). A ceiling, not a promise: R2
+   * may return fewer per page to fit the entry metadata.
+   *
+   * Must be a positive integer when given — `0`, `12.5` and `NaN` throw rather
+   * than being coerced into a page size the caller never asked for.
+   */
   limit?: number;
 }
 interface SignedUrlOptions {
   /**
    * Pin the `Content-Type` an uploader must send on a `method: "PUT"` URL.
    * Baked into the HMAC canonical so the signature only authorizes a PUT with
-   * exactly this content-type; mirrored on the URL as `&amp;ct=...`. Ignored for
+   * exactly this content-type; mirrored on the URL as `&ct=...`. Ignored for
    * `GET` URLs (a download has no request body content-type to pin).
    */
   contentType?: string;
@@ -220,6 +129,17 @@ interface ObjectMetadata {
   uploaded?: number;
 }
 interface Storage {
+  /**
+   * The bucket name this accessor operates under — the same value
+   * {@link Storage.getSignedUrl} puts into the HMAC canonical.
+   *
+   * Exposed so everything downstream agrees on one name: `asBucketStorage`
+   * tags a single-bucket storage with it, and `storageRules(...)` matches
+   * `(bucket, operation)` rules against that tag. Without it a
+   * `createStorage({ bucketName: "avatars" })` signed URLs as `avatars` while
+   * the rules engine only ever saw `"default"`.
+   */
+  readonly bucketName: string;
   /**
    * Begin a native R2 **multipart upload** for very large objects — upload
    * parts (each uniform in size except the last), then `complete` with the
@@ -251,10 +171,10 @@ interface Storage {
   }) => Promise<string>;
   /**
    * Read a stored object's metadata (size, content-type, sha256, upload time,
-   * custom metadata) without fetching its body. Returns `null` when the object
-   * is absent. Backed by an R2 HEAD (`bucket.head`) when available, falling
-   * back to a 0-length ranged `get()` otherwise. Mirrors Convex's
-   * `ctx.storage.getMetadata`.
+   * custom metadata) without fetching its body, as a flat serializable shape.
+   * Returns `null` when the object is absent. A projection of
+   * {@link Storage.head}, so it makes the same single body-free read. Mirrors
+   * Convex's `ctx.storage.getMetadata`.
    */
   getMetadata: (key: string) => Promise<ObjectMetadata | null>;
   /**
@@ -267,8 +187,32 @@ interface Storage {
   getPresignedUrl: (key: string, options?: PresignedUrlOptions) => Promise<string>;
   getSignedUrl: (key: string, options?: SignedUrlOptions) => Promise<string>;
   getUrl: (key: string) => string;
+  /**
+   * Read an object's R2 metadata WITHOUT its body — `size` (the full object
+   * size), `etag`, `httpMetadata`, `checksums`, plus the `sha256`/`sha256Base64`
+   * projection `download()` adds. Returns `null` when the object is absent.
+   *
+   * Backed by an R2 HEAD when the binding exposes one, falling back to a
+   * 0-length ranged `get()` otherwise. Prefer this over `download()` whenever
+   * only the metadata is wanted — notably to resolve a `Range` header, where a
+   * plain `download()` starts a full-object body transfer that is then thrown
+   * away. {@link Storage.getMetadata} is the flat, serializable projection of
+   * the same read.
+   */
+  head: (key: string) => Promise<R2ObjectLike | null>;
+  /**
+   * List objects under `prefix`. With `options.delimiter` set, keys sharing a
+   * segment are rolled up into `delimitedPrefixes` (the "folders") and are NOT
+   * in `objects` — a folder browser needs both, so a listing whose `objects` is
+   * empty is not an empty directory.
+   *
+   * A page may hold FEWER objects than `options.limit`: R2 shrinks a page to
+   * fit the per-entry metadata this call asks for. Paginate on `truncated` /
+   * `cursor`, never on `objects.length === limit`.
+   */
   list: (prefix?: string, options?: ListOptions) => Promise<{
     cursor?: string;
+    delimitedPrefixes?: string[];
     objects: R2ObjectLike[];
     truncated?: boolean;
   }>;
@@ -283,12 +227,20 @@ interface Storage {
    * alias for {@link Storage.upload} — it accepts the same {@link UploadOptions}
    * so the `maxSize` / `allowedContentTypes` guards aren't lost behind the alias.
    */
-  store: (key: string, body: ReadableStream | ArrayBuffer | Blob, options?: UploadOptions) => Promise<{
+  store: (key: string, body: ReadableStream | ArrayBuffer | ArrayBufferView | Blob | string, options?: UploadOptions) => Promise<{
     etag: string;
     httpEtag: string;
     key: string;
   }>;
-  upload: (key: string, body: ReadableStream | ArrayBuffer | Blob, options?: UploadOptions) => Promise<{
+  /**
+   * Upload `body` to `key`, returning the stored key + etag.
+   *
+   * The accepted shapes mirror what R2's `put` stores bytes from — a view
+   * (`Uint8Array`) and a `string` included. They are listed here because
+   * `maxSize` measures every one of them; a shape the cap cannot measure is
+   * refused rather than uploaded uncapped.
+   */
+  upload: (key: string, body: ReadableStream | ArrayBuffer | ArrayBufferView | Blob | string, options?: UploadOptions) => Promise<{
     etag: string;
     httpEtag: string;
     key: string;
@@ -314,36 +266,32 @@ interface BucketStorage extends Storage {
  *
  * ```ts
  * storage: (env) => createBucketStorage({
- *     default: createStorage({ bucket: env.FILES }),
- *     avatars: createStorage({ bucket: env.AVATARS }),
+ *     default: createStorage({ bucket: env.FILES, bucketName: "default" }),
+ *     avatars: createStorage({ bucket: env.AVATARS, bucketName: "avatars" }),
  * }),
  * // → ctx.storage.download(key)             // default bucket
  * // → ctx.storage.bucket("avatars").store() // the avatars bucket
  * ```
  *
- * The bare accessor is tagged `"default"` — the canonical name a
- * `defineStorageRule({ bucket: "default" })` rule and the generated
- * `StorageBucketName` union both use — unless `options.default` names another
- * bucket (then the bare accessor takes that name). The binding it delegates to is
- * `options.default`, else the `"default"` key when present, else the first
- * registered bucket. Named buckets are reached with `bucket(name)`.
+ * The bare accessor is tagged with the name of the binding it actually
+ * delegates to: `options.default` when given, else `"default"` when that key
+ * exists (the canonical name a `defineStorageRule({ bucket: "default" })` rule
+ * and the generated `StorageBucketName` union use), else the first registered
+ * bucket. Tag and binding must agree or a `{ bucket: "avatars" }` rule would
+ * gate `bucket("avatars").download()` and not the identical bare
+ * `ctx.storage.download()` reaching the same R2 bucket. Named buckets are
+ * reached with `bucket(name)`.
  */
 declare const createBucketStorage: (buckets: Record<string, Storage>, options?: {
   default?: string;
 }) => BucketStorage;
-/**
- * Compose a per-tenant key from a scope prefix and a caller-supplied key.
- * Both halves are validated — the prefix may not contain `..` or NUL either,
- * and the resulting key must stay under R2's length ceiling. Recommended for
- * any multi-tenant deployment so client-supplied keys can't address peer data.
- */
 declare const scopeKey: (prefix: string, key: string) => string;
 declare const createStorage: (options: LunoraStorageOptions) => Storage;
 /** Parameters accepted by {@link buildPresignedUrl}. */
 interface PresignedUrlParams {
   /** R2 S3 API credentials + bucket/account. */
   credentials: R2S3Credentials;
-  /** Seconds the URL stays valid; clamped to [1, 604800]. Default 900. */
+  /** Seconds the URL stays valid: 1 to 604800 (7 days); an out-of-range value throws. Default 900. */
   expiresInSeconds?: number;
   /** Object key (path-style; not URL-encoded by the caller). */
   key: string;
@@ -364,20 +312,33 @@ declare const buildPresignedUrl: (parameters: PresignedUrlParams) => Promise<str
  * string carrying `exp` (unix seconds), `method` (`GET` or `PUT`) and `sig`
  * (a base64url HMAC).
  *
- * The HMAC canonical includes the URL host so a signature minted for one bucket
- * cannot be replayed against another host on the same signing secret. Even so,
- * the signing secret MUST NOT be shared across buckets/tenants — host binding
- * narrows replay surface but is not a substitute for per-tenant key isolation.
+ * The HMAC canonical includes the URL host AND the `bucketName`, so a signature
+ * minted for one bucket cannot be replayed against another bucket (all buckets
+ * of one `.storage()` declaration share a base URL and signing secret) or
+ * another host. Even so, the signing secret MUST NOT be shared across
+ * tenants — this binding narrows replay surface but is not a substitute for
+ * per-tenant key isolation.
  *
- * The Worker handling `GET /storage/:key` should call {@link verifySignedUrl}
- * to validate the signature + expiry before streaming the R2 body.
+ * The Worker route handling the signed download/upload (mounted at
+ * `publicBaseUrl`'s origin, e.g. `GET /:key`) should call
+ * {@link verifySignedUrl} to validate the signature + expiry before streaming
+ * the R2 body. `baseUrl` must be a bare origin (no path) — see the module
+ * docstring.
  */
-declare const buildSignedUrl: (args: SignedUrlOptions & {
+declare const buildSignedUrl: (args: {
   baseUrl: string;
+  /** The bucket the URL addresses — bound into the HMAC and mirrored as `&bucket=`. */
+  bucketName: string;
   key: string;
   secret: string;
-}) => Promise<string>;
+} & SignedUrlOptions) => Promise<string>;
 interface VerifyResult {
+  /**
+   * The bucket the URL was minted for. The serving route MUST resolve its R2
+   * binding from this (never from a caller-supplied bucket), since one signing
+   * secret covers every bucket of a `.storage()` declaration.
+   */
+  bucketName?: string;
   /** The pinned upload `Content-Type` carried by a PUT URL, when present. */
   contentType?: string;
   key?: string;
@@ -403,4 +364,4 @@ interface VerifyResult {
 declare const verifySignedUrl: (input: string | URL, secret: string, options?: {
   expectedHost?: string;
 }) => Promise<VerifyResult>;
-export { type BucketStorage, type ListOptions, type LunoraStorageOptions, type ObjectMetadata, type PresignedUrlOptions, type PresignedUrlParams, type R2BucketLike, type R2MultipartUploadLike, type R2ObjectBodyLike, type R2ObjectLike, type R2RangeLike, type R2S3Credentials, type R2UploadedPartLike, type SignedUrlOptions, type Storage, type UploadOptions, type VerifyResult, buildPresignedUrl, buildSignedUrl, createBucketStorage, createStorage, scopeKey, verifySignedUrl };
+export { type BucketStorage, type ListOptions, type LunoraStorageOptions, type ObjectMetadata, type PresignedUrlOptions, type PresignedUrlParams, type R2S3Credentials, type SignedUrlOptions, type Storage, type UploadOptions, type VerifyResult, buildPresignedUrl, buildSignedUrl, createBucketStorage, createStorage, scopeKey, verifySignedUrl };