@lenso/storage 0.0.0-stage → 0.1.1

package/dist/index-fa6z0g4w.js

@@ -0,0 +1,89 @@
+import {
+  StorageError2,
+  validateContentType2
+} from "./index-0fz1t930.js";
+
+// src/stream.ts
+function validateUpload(input) {
+  if (input.contentType !== undefined)
+    validateContentType2(input.contentType);
+  for (const [name, value] of [
+    ["size", input.size],
+    ["maxBytes", input.maxBytes]
+  ]) {
+    if (value !== undefined && (!Number.isSafeInteger(value) || value < 0)) {
+      throw new StorageError2("invalid-input", `${name} must be a nonnegative safe integer`);
+    }
+  }
+  if (input.size !== undefined && input.maxBytes !== undefined && input.size > input.maxBytes) {
+    throw new StorageError2("too-large", "Upload exceeds the size limit");
+  }
+  input.signal?.throwIfAborted();
+}
+function checkedUpload(input) {
+  validateUpload(input);
+  const reader = input.body.getReader();
+  let bytes = 0;
+  let ended = false;
+  let cancellation;
+  let controller;
+  const detach = () => input.signal?.removeEventListener("abort", abort);
+  function cancel(reason) {
+    if (cancellation)
+      return cancellation;
+    if (ended)
+      return Promise.resolve();
+    ended = true;
+    detach();
+    cancellation = reader.cancel(reason).catch((error) => {
+      if (error !== reason)
+        throw error;
+    }).finally(() => reader.releaseLock());
+    return cancellation;
+  }
+  function abort() {
+    const error = new StorageError2("aborted", "Upload cancelled");
+    controller.error(error);
+    cancel(error).catch(() => {});
+  }
+  const body = new ReadableStream({
+    start(value) {
+      controller = value;
+      input.signal?.addEventListener("abort", abort, { once: true });
+      if (input.signal?.aborted)
+        abort();
+    },
+    async pull(value) {
+      try {
+        const chunk = await reader.read();
+        if (ended)
+          return;
+        if (chunk.done) {
+          if (input.size !== undefined && bytes !== input.size) {
+            throw new StorageError2("invalid-input", "Upload size differs from declared size");
+          }
+          ended = true;
+          detach();
+          reader.releaseLock();
+          value.close();
+          return;
+        }
+        bytes += chunk.value.byteLength;
+        if (input.maxBytes !== undefined && bytes > input.maxBytes) {
+          throw new StorageError2("too-large", "Upload exceeds the size limit");
+        }
+        if (input.size !== undefined && bytes > input.size) {
+          throw new StorageError2("invalid-input", "Upload exceeds its declared size");
+        }
+        value.enqueue(chunk.value);
+      } catch (error) {
+        value.error(error);
+        await cancel(error).catch(() => {});
+      }
+    },
+    cancel
+  }, { highWaterMark: 0 });
+  return { body, size: () => bytes, cancel };
+}
+
+export { validateUpload, checkedUpload };

package/dist/index.d.ts

@@ -0,0 +1,116 @@
+import { type Plugin, type PluginContext } from "@lenso/core/plugin";
+export type StorageErrorCode = "invalid-key" | "invalid-input" | "not-found" | "forbidden" | "unsupported" | "conflict" | "too-large" | "aborted" | "provider";
+export declare class StorageError extends Error {
+    readonly code: StorageErrorCode;
+    constructor(code: StorageErrorCode, message: string, options?: ErrorOptions);
+}
+export interface StorageCapabilities {
+    readonly provider: "local" | "s3" | "r2-binding";
+    readonly signedUpload: boolean;
+    readonly signedDownload: boolean;
+    readonly rangeRead: boolean;
+    readonly conditionalRead: boolean;
+    readonly pagination: "key" | "opaque";
+    readonly uploadCancellation: "abort" | "stream-only";
+    readonly uploadRequiresSize: boolean;
+    readonly maxUploadBytes?: number;
+}
+export interface ObjectMetadata {
+    key: string;
+    size: number;
+    contentType: string;
+    etag?: string;
+    lastModified?: Date;
+    versionId?: string;
+    customMetadata?: Record<string, string>;
+}
+/** Uploads create a new key, never replace an existing object. */
+export interface PutObjectInput {
+    key: string;
+    body: ReadableStream<Uint8Array>;
+    contentType?: string;
+    size?: number;
+    maxBytes?: number;
+    customMetadata?: Record<string, string>;
+    signal?: AbortSignal;
+}
+export interface ReadObjectOptions {
+    range?: {
+        offset: number;
+        length?: number;
+    };
+    ifMatch?: string;
+    signal?: AbortSignal;
+}
+export interface ObjectDownload {
+    metadata: ObjectMetadata;
+    body: ReadableStream<Uint8Array>;
+    range?: {
+        offset: number;
+        length: number;
+    };
+}
+export interface ListObjectsInput {
+    prefix?: string;
+    cursor?: string;
+    limit?: number;
+    signal?: AbortSignal;
+}
+export interface ObjectPage {
+    objects: ObjectMetadata[];
+    cursor?: string;
+}
+/** URLs and headers are temporary credentials. Never log this result. */
+export interface SignedObjectLink {
+    url: string;
+    method: "GET" | "PUT";
+    headers: Record<string, string>;
+    expiresAt: Date;
+    conditions: {
+        contentType?: string;
+        ifMatch?: string;
+        createOnly?: boolean;
+        maxBytes?: number;
+        sizeEnforcement: "completion-check" | "none";
+    };
+}
+export interface SignUploadInput {
+    key: string;
+    expiresIn: number;
+    contentType: string;
+    maxBytes?: number;
+}
+export interface SignDownloadInput {
+    key: string;
+    expiresIn: number;
+    ifMatch?: string;
+}
+export interface ObjectStorage {
+    readonly id: string;
+    readonly capabilities: StorageCapabilities;
+    put(input: PutObjectInput): Promise<ObjectMetadata>;
+    get(key: string, options?: ReadObjectOptions): Promise<ObjectDownload>;
+    head(key: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<ObjectMetadata | null>;
+    /** Idempotent. "absent-or-deleted" backends cannot atomically report prior existence. */
+    delete(key: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        outcome: "deleted" | "not-found" | "absent-or-deleted";
+    }>;
+    list(input?: ListObjectsInput): Promise<ObjectPage>;
+    signUpload(input: SignUploadInput): Promise<SignedObjectLink>;
+    signDownload(input: SignDownloadInput): Promise<SignedObjectLink>;
+}
+export declare function createStoragePlugin(options: {
+    id: string;
+    requires?: readonly Plugin<unknown>[];
+    setup(context: PluginContext): Omit<ObjectStorage, "id"> | Promise<Omit<ObjectStorage, "id">>;
+}): Plugin<ObjectStorage>;
+export declare function validateKey(key: string): void;
+export declare function validateContentType(contentType: string): void;
+export declare function validateList(input: ListObjectsInput): number;
+export declare function validateRange(options: ReadObjectOptions, supported: boolean): void;
+export declare function validateExpiry(expiresIn: number): void;
+export declare function unsupportedSigning(): never;

package/dist/index.js

@@ -0,0 +1,20 @@
+import {
+  StorageError2,
+  createStoragePlugin2,
+  validateKey2,
+  validateContentType2,
+  validateList2,
+  validateRange2,
+  validateExpiry2,
+  unsupportedSigning2
+} from "./index-0fz1t930.js";
+export {
+  StorageError2 as StorageError,
+  createStoragePlugin2 as createStoragePlugin,
+  unsupportedSigning2 as unsupportedSigning,
+  validateContentType2 as validateContentType,
+  validateExpiry2 as validateExpiry,
+  validateKey2 as validateKey,
+  validateList2 as validateList,
+  validateRange2 as validateRange
+};

package/dist/local.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Use a trusted, dedicated directory, not a user-writable shared tree.
+ * O_NOFOLLOW protects opened files; portable path APIs cannot prevent concurrent
+ * hostile writers from swapping ancestor directories between checks and use.
+ * Each SHA-256 key directory contains payload and metadata.json. A nonempty
+ * directory rename publishes both atomically and cannot replace another object.
+ */
+export declare function createLocalStoragePlugin(options: {
+    id: string;
+    root: string;
+}): import("@lenso/core/plugin").Plugin<import("./index").ObjectStorage>;

package/dist/local.js

@@ -0,0 +1,457 @@
+import {
+  StorageError2,
+  createStoragePlugin2,
+  validateKey2,
+  validateList2,
+  validateRange2,
+  unsupportedSigning2
+} from "./index-0fz1t930.js";
+import {
+  checkedUpload
+} from "./index-fa6z0g4w.js";
+
+// src/local.ts
+import { constants } from "node:fs";
+import {
+  lstat,
+  mkdir,
+  mkdtemp,
+  open,
+  readdir,
+  rename,
+  rm
+} from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { dirname, join, parse, resolve } from "node:path";
+var objectName = (key) => createHash("sha256").update(key).digest("hex");
+var temporary = /^\.tmp-[A-Za-z0-9]+$/;
+var metadataLimit = 64 * 1024;
+function code(error) {
+  return error?.code;
+}
+function storageError(error) {
+  if (error instanceof StorageError2)
+    return error;
+  const value = code(error);
+  return new StorageError2(value === "ENOENT" ? "not-found" : value === "ELOOP" || value === "EACCES" || value === "EPERM" ? "forbidden" : error?.name === "AbortError" ? "aborted" : "provider", "Local storage operation failed", { cause: error });
+}
+async function directory(path) {
+  let stat;
+  try {
+    stat = await lstat(path);
+  } catch (error) {
+    throw storageError(error);
+  }
+  if (!stat.isDirectory() || stat.isSymbolicLink()) {
+    throw new StorageError2("forbidden", "Storage directories must not be symlinks");
+  }
+}
+async function ancestry(root) {
+  const paths = [];
+  for (let path = root;; path = dirname(path)) {
+    paths.unshift(path);
+    if (path === parse(path).root)
+      break;
+  }
+  for (const path of paths)
+    await directory(path);
+}
+function createLocalStoragePlugin(options) {
+  return createStoragePlugin2({
+    id: options.id,
+    async setup(context) {
+      const root = resolve(options.root);
+      const lifetime = new AbortController;
+      const handles = new Set;
+      const operations = new Set;
+      context.onCleanup(async () => {
+        lifetime.abort();
+        const results = await Promise.allSettled(operations);
+        const closed = await Promise.allSettled([...handles].map((handle) => handle.close()));
+        handles.clear();
+        const failures = [...results, ...closed].filter((result) => result.status === "rejected" && !(result.reason instanceof StorageError2 && result.reason.code === "aborted" && !(result.reason.cause instanceof AggregateError)));
+        if (failures.length)
+          throw new StorageError2("provider", "Local storage cleanup failed", {
+            cause: new AggregateError(failures.map((failure) => failure.reason))
+          });
+      });
+      const paths = [];
+      for (let path = root;path !== parse(path).root; path = dirname(path))
+        paths.unshift(path);
+      await directory(parse(root).root);
+      for (const path of paths) {
+        try {
+          await mkdir(path, { mode: 448 });
+        } catch (error) {
+          if (code(error) !== "EEXIST")
+            throw storageError(error);
+        }
+        await directory(path);
+      }
+      const signalFor = (signal) => signal ? AbortSignal.any([signal, lifetime.signal]) : lifetime.signal;
+      function run(signal, action) {
+        const task = (async () => {
+          try {
+            const combined = signalFor(signal);
+            combined.throwIfAborted();
+            await ancestry(root);
+            return await action(combined);
+          } catch (error) {
+            throw storageError(error);
+          }
+        })();
+        operations.add(task);
+        task.finally(() => operations.delete(task)).catch(() => {});
+        return task;
+      }
+      async function safeOpen(path) {
+        let handle;
+        try {
+          handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        } catch (error) {
+          if (code(error) === "ENOENT")
+            throw new StorageError2("provider", "Incomplete stored object", { cause: error });
+          throw error;
+        }
+        handles.add(handle);
+        try {
+          const stat = await handle.stat();
+          if (!stat.isFile() || stat.nlink !== 1) {
+            throw new StorageError2("forbidden", "Storage files must be regular files without additional hard links");
+          }
+          return handle;
+        } catch (error) {
+          await close(handle, error);
+          throw error;
+        }
+      }
+      async function close(handle, failure) {
+        try {
+          await handle.close();
+          handles.delete(handle);
+        } catch (error) {
+          throw new StorageError2(failure instanceof StorageError2 ? failure.code : "provider", "Storage file cleanup failed", {
+            cause: new AggregateError([...failure === undefined ? [] : [failure], error])
+          });
+        }
+      }
+      async function load(name, expectedKey) {
+        const path = join(root, name);
+        await directory(path);
+        const identity = await lstat(path);
+        const entries = await readdir(path);
+        if (entries.length !== 2 || !entries.includes("payload") || !entries.includes("metadata.json")) {
+          throw new StorageError2("forbidden", "Unexpected object directory entries");
+        }
+        const metadataFile = await safeOpen(join(path, "metadata.json"));
+        let metadata;
+        try {
+          if ((await metadataFile.stat()).size > metadataLimit) {
+            throw new StorageError2("provider", "Object metadata exceeds its representation limit");
+          }
+          const value = JSON.parse(await metadataFile.readFile("utf8"));
+          if (typeof value.key !== "string")
+            throw new StorageError2("provider", "Invalid stored key");
+          validateKey2(value.key);
+          if (objectName(value.key) !== name || expectedKey !== undefined && value.key !== expectedKey || !Number.isSafeInteger(value.size) || value.size < 0 || typeof value.contentType !== "string" || !/^"[a-f0-9]{64}"$/.test(value.etag) || typeof value.lastModified !== "string" || !Number.isFinite(Date.parse(value.lastModified)) || value.customMetadata !== undefined && (value.customMetadata === null || typeof value.customMetadata !== "object" || Array.isArray(value.customMetadata) || Object.values(value.customMetadata).some((entry) => typeof entry !== "string"))) {
+            throw new StorageError2("provider", "Invalid stored metadata");
+          }
+          metadata = { ...value, lastModified: new Date(value.lastModified) };
+        } finally {
+          await close(metadataFile);
+        }
+        const payload = await safeOpen(join(path, "payload"));
+        try {
+          if ((await payload.stat()).size !== metadata.size) {
+            throw new StorageError2("provider", "Stored payload size differs from metadata");
+          }
+          const current = await lstat(path);
+          if (current.dev !== identity.dev || current.ino !== identity.ino || current.isSymbolicLink()) {
+            throw new StorageError2("conflict", "Object changed while opening its snapshot");
+          }
+          return { metadata, payload };
+        } catch (error) {
+          await close(payload, error);
+          throw error;
+        }
+      }
+      async function put(input, signal) {
+        validateKey2(input.key);
+        const contentType = input.contentType ?? "application/octet-stream";
+        if (typeof contentType !== "string" || input.customMetadata !== undefined && (input.customMetadata === null || typeof input.customMetadata !== "object" || Array.isArray(input.customMetadata) || Object.values(input.customMetadata).some((value) => typeof value !== "string"))) {
+          throw new StorageError2("invalid-input", "Invalid upload metadata");
+        }
+        const upload = checkedUpload({ ...input, signal });
+        let temp;
+        let failure;
+        try {
+          temp = await mkdtemp(join(root, ".tmp-"));
+          const payload = await open(join(temp, "payload"), constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 384);
+          handles.add(payload);
+          const hash = createHash("sha256");
+          const reader = upload.body.getReader();
+          try {
+            for (;; ) {
+              const chunk = await reader.read();
+              if (chunk.done)
+                break;
+              hash.update(chunk.value);
+              let offset = 0;
+              while (offset < chunk.value.byteLength) {
+                signal.throwIfAborted();
+                const { bytesWritten } = await payload.write(chunk.value, offset, chunk.value.byteLength - offset);
+                if (!bytesWritten)
+                  throw new StorageError2("provider", "Upload write made no progress");
+                offset += bytesWritten;
+              }
+            }
+            await payload.sync();
+          } catch (error) {
+            failure = storageError(error);
+            throw failure;
+          } finally {
+            reader.releaseLock();
+            await close(payload, failure);
+          }
+          const metadata = {
+            key: input.key,
+            size: upload.size(),
+            contentType,
+            etag: `"${hash.digest("hex")}"`,
+            lastModified: new Date,
+            ...input.customMetadata === undefined ? {} : { customMetadata: { ...input.customMetadata } }
+          };
+          const serialized = JSON.stringify(metadata);
+          if (Buffer.byteLength(serialized) > metadataLimit)
+            throw new StorageError2("invalid-input", "Upload metadata is too large");
+          const file = await open(join(temp, "metadata.json"), "wx", 384);
+          handles.add(file);
+          try {
+            await file.writeFile(serialized);
+            await file.sync();
+          } finally {
+            await close(file);
+          }
+          signal.throwIfAborted();
+          await ancestry(root);
+          const destination = join(root, objectName(input.key));
+          try {
+            await lstat(destination);
+            await directory(destination);
+            throw new StorageError2("conflict", "Object already exists");
+          } catch (error) {
+            if (code(error) !== "ENOENT")
+              throw error;
+          }
+          try {
+            await rename(temp, destination);
+          } catch (error) {
+            if (["EEXIST", "ENOTEMPTY"].includes(code(error) ?? ""))
+              throw new StorageError2("conflict", "Object already exists", { cause: error });
+            throw error;
+          }
+          temp = undefined;
+          return metadata;
+        } catch (error) {
+          failure = storageError(error);
+          throw failure;
+        } finally {
+          const cleanup = await Promise.allSettled([
+            upload.cancel(failure),
+            ...temp ? [rm(temp, { recursive: true })] : []
+          ]);
+          const errors = cleanup.filter((result) => result.status === "rejected");
+          if (errors.length) {
+            throw new StorageError2(failure instanceof StorageError2 ? failure.code : "provider", "Upload cleanup failed", {
+              cause: new AggregateError([
+                ...failure ? [failure] : [],
+                ...errors.map((error) => error.reason)
+              ])
+            });
+          }
+        }
+      }
+      return {
+        capabilities: {
+          provider: "local",
+          signedUpload: false,
+          signedDownload: false,
+          rangeRead: true,
+          conditionalRead: true,
+          pagination: "key",
+          uploadCancellation: "abort",
+          uploadRequiresSize: false
+        },
+        put: (input) => run(input.signal, (signal) => put(input, signal)),
+        get: (key, readOptions = {}) => run(readOptions.signal, async (signal) => {
+          validateKey2(key);
+          validateRange2(readOptions, true);
+          const { metadata, payload } = await load(objectName(key), key);
+          try {
+            if (readOptions.ifMatch !== undefined && readOptions.ifMatch !== metadata.etag) {
+              throw new StorageError2("conflict", "Object etag does not match");
+            }
+            const offset = readOptions.range?.offset ?? 0;
+            if (readOptions.range && offset >= metadata.size)
+              throw new StorageError2("invalid-input", "Range starts outside the object");
+            const length = Math.min(readOptions.range?.length ?? metadata.size - offset, metadata.size - offset);
+            let position = offset;
+            let ended = false;
+            let controller;
+            const finish = async () => {
+              if (ended)
+                return;
+              ended = true;
+              signal.removeEventListener("abort", abort);
+              await close(payload);
+            };
+            const abort = () => {
+              controller.error(new StorageError2("aborted", "Download cancelled"));
+              finish().catch(() => {});
+            };
+            const body = new ReadableStream({
+              start(value) {
+                controller = value;
+                signal.addEventListener("abort", abort, { once: true });
+                if (signal.aborted)
+                  abort();
+              },
+              async pull(value) {
+                try {
+                  if (position === offset + length) {
+                    await finish();
+                    value.close();
+                    return;
+                  }
+                  const buffer = new Uint8Array(Math.min(64 * 1024, offset + length - position));
+                  const { bytesRead } = await payload.read(buffer, 0, buffer.length, position);
+                  if (ended)
+                    return;
+                  if (!bytesRead)
+                    throw new StorageError2("provider", "Unexpected end of stored payload");
+                  position += bytesRead;
+                  value.enqueue(buffer.subarray(0, bytesRead));
+                } catch (error) {
+                  if (!ended)
+                    value.error(storageError(error));
+                  await finish();
+                }
+              },
+              cancel: finish
+            }, { highWaterMark: 0 });
+            return {
+              metadata,
+              body,
+              ...readOptions.range ? { range: { offset, length } } : {}
+            };
+          } catch (error) {
+            await close(payload, error);
+            throw error;
+          }
+        }),
+        head: (key, headOptions = {}) => run(headOptions.signal, async () => {
+          validateKey2(key);
+          try {
+            const { metadata, payload } = await load(objectName(key), key);
+            await close(payload);
+            return metadata;
+          } catch (error) {
+            if (error instanceof StorageError2 && error.code === "not-found")
+              return null;
+            if (code(error) === "ENOENT")
+              throw new StorageError2("provider", "Incomplete stored object", { cause: error });
+            throw error;
+          }
+        }),
+        delete: (key, deleteOptions = {}) => run(deleteOptions.signal, async (signal) => {
+          validateKey2(key);
+          const tomb = join(root, `.delete-${objectName(key)}`);
+          async function removeTomb() {
+            try {
+              await directory(tomb);
+            } catch (error) {
+              if (error instanceof StorageError2 && error.code === "not-found")
+                return false;
+              throw error;
+            }
+            for (const entry of await readdir(tomb)) {
+              if (entry !== "payload" && entry !== "metadata.json") {
+                throw new StorageError2("forbidden", "Unexpected deletion directory entry");
+              }
+              let stat;
+              try {
+                stat = await lstat(join(tomb, entry));
+              } catch (error) {
+                if (code(error) === "ENOENT")
+                  continue;
+                throw error;
+              }
+              if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) {
+                throw new StorageError2("forbidden", "Unsafe deletion directory entry");
+              }
+            }
+            signal.throwIfAborted();
+            try {
+              await rm(tomb, { recursive: true });
+            } catch (error) {
+              if (code(error) !== "ENOENT")
+                throw error;
+            }
+            return true;
+          }
+          const recovered = await removeTomb();
+          try {
+            const { payload } = await load(objectName(key), key);
+            await close(payload);
+          } catch (error) {
+            if (error instanceof StorageError2 && error.code === "not-found") {
+              return { outcome: recovered ? "deleted" : "not-found" };
+            }
+            if (code(error) === "ENOENT")
+              throw new StorageError2("provider", "Incomplete stored object", { cause: error });
+            throw error;
+          }
+          signal.throwIfAborted();
+          try {
+            await rename(join(root, objectName(key)), tomb);
+          } catch (error) {
+            if (code(error) !== "ENOENT")
+              throw error;
+            const removed = await removeTomb();
+            return { outcome: recovered || removed ? "deleted" : "not-found" };
+          }
+          await removeTomb();
+          return { outcome: "deleted" };
+        }),
+        list: (input = {}) => run(input.signal, async (signal) => {
+          const limit = validateList2(input);
+          if (input.cursor !== undefined)
+            validateKey2(input.cursor);
+          const objects = [];
+          for (const name of await readdir(root)) {
+            signal.throwIfAborted();
+            await directory(join(root, name));
+            if (temporary.test(name) || /^\.delete-[a-f0-9]{64}$/.test(name))
+              continue;
+            if (!/^[a-f0-9]{64}$/.test(name))
+              throw new StorageError2("forbidden", "Unexpected storage root entry");
+            const { metadata, payload } = await load(name);
+            await close(payload);
+            if (metadata.key.startsWith(input.prefix ?? "") && (input.cursor === undefined || metadata.key > input.cursor))
+              objects.push(metadata);
+          }
+          objects.sort((a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
+          return {
+            objects: objects.slice(0, limit),
+            ...objects.length > limit ? { cursor: objects[limit - 1].key } : {}
+          };
+        }),
+        signUpload: async () => unsupportedSigning2(),
+        signDownload: async () => unsupportedSigning2()
+      };
+    }
+  });
+}
+export {
+  createLocalStoragePlugin
+};