@lunora/storage 1.0.0-alpha.2 → 1.0.0-alpha.21

package/dist/upload.d.mts

@@ -0,0 +1,118 @@
+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 request's declared size (`Upload-Length`
+   * / `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.
+   */
+  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 { type CreateUploadHandlerOptions, DEFAULT_MAX_UPLOAD_BYTES, type R2UploadStorageOptions, type UploadAuthzContext, type UploadHandler, type UploadProtocol, type UploadStorage, createR2UploadStorage, createUploadHandler };

package/dist/upload.d.ts

@@ -0,0 +1,118 @@
+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 request's declared size (`Upload-Length`
+   * / `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.
+   */
+  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 { type CreateUploadHandlerOptions, DEFAULT_MAX_UPLOAD_BYTES, type R2UploadStorageOptions, type UploadAuthzContext, type UploadHandler, type UploadProtocol, 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-CeVvqDXZ.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.2",
+  "version": "1.0.0-alpha.21",
   "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,21 @@
       "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.15",
+    "@lunora/platform": "1.0.0-alpha.6",
+    "@visulima/storage": "1.0.5",
+    "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-ZzB16yPl.mjs

@@ -1,107 +0,0 @@
-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 keyCache = /* @__PURE__ */ new Map();
-const importHmacKey = async (secret) => {
-  const cached = keyCache.get(secret);
-  if (cached) {
-    return cached;
-  }
-  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 Error("@lunora/storage: expiresInSeconds must be a positive finite number");
-  }
-  if (expiresInSeconds > MAX_EXPIRES_IN_SECONDS) {
-    throw new Error(`@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-4Xk7-5CN.mjs

@@ -1,26 +0,0 @@
-const createBucketStorage = (buckets, options = {}) => {
-  const names = Object.keys(buckets);
-  const [firstName] = names;
-  if (firstName === void 0) {
-    throw new Error("@lunora/storage: createBucketStorage requires at least one bucket");
-  }
-  if (options.default !== void 0 && !buckets[options.default]) {
-    throw new Error(`@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 Error(`@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 Error(`@lunora/storage: no bucket registered for "${name}". Known buckets: ${addressable.join(", ")}`);
-    }
-    return { ...target, bucket: (next) => make(next), bucketName: name };
-  };
-  return make(defaultTag);
-};
-
-export { createBucketStorage };