@lenso/storage 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LioRael
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,145 @@
-# Temporary Holding Version
+# @lenso/storage
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Private object storage with explicit Lenso instance references. Business methods are ordinary async functions. The package root has no filesystem, AWS SDK, database or Web imports.
+
+| Import                    | Runtime / optional dependency                                      |
+| ------------------------- | ------------------------------------------------------------------ |
+| `@lenso/storage`          | Object types, errors and plugin factory                            |
+| `@lenso/storage/local`    | Bun, dedicated local directory                                     |
+| `@lenso/storage/s3`       | Bun, AWS SDK v3 `client-s3`, `lib-storage`, `s3-request-presigner` |
+| `@lenso/storage/r2`       | Workers native R2 binding, no AWS SDK                              |
+| `@lenso/storage/files`    | Optional authorized file records, database supplied by application |
+| `@lenso/storage/sqlite`   | Drizzle schema/queries for Bun SQLite or D1                        |
+| `@lenso/storage/postgres` | Drizzle schema/queries for Bun SQL PostgreSQL                      |
+| `@lenso/storage/fetch`    | Optional raw Fetch helpers, no listener or implicit routes         |
+
+Install `@lenso/core` and this package. Install the three AWS SDK peers for `/s3`, or `drizzle-orm@0.45.3` for the database subpaths. Do not import `/local` or `/s3` in a Workers entry. Inspect `storage.capabilities` before selecting signing, conditional or range operations; unsupported operations throw `StorageError` with `code: "unsupported"`.
+
+## Multiple instances and object streams
+
+```ts
+import { defineApp, startApp } from "@lenso/core";
+import { createLocalStoragePlugin } from "@lenso/storage/local";
+
+const publicAssets = createLocalStoragePlugin({ id: "publicAssets", root: "./data/assets" });
+const privateFiles = createLocalStoragePlugin({ id: "privateFiles", root: "./data/private" });
+const app = await startApp(defineApp({ plugins: [publicAssets, privateFiles] }));
+try {
+  const storage = app.get(privateFiles); // No global default.
+  await storage.put({
+    key: "contracts/unique-id.pdf",
+    body: request.body!,
+    contentType: "application/pdf",
+    maxBytes: 20 * 1024 * 1024,
+    signal: request.signal,
+  });
+  const download = await storage.get("contracts/unique-id.pdf");
+  const response = new Response(download.body, {
+    headers: { "content-type": download.metadata.contentType },
+  });
+  // Return/consume the response before stopping the app.
+  await response.body!.pipeTo(destination);
+  const metadata = await storage.head("contracts/unique-id.pdf"); // null only for missing
+  const page = await storage.list({ prefix: "contracts/", limit: 100 });
+  if (page.cursor) await storage.list({ prefix: "contracts/", cursor: page.cursor, limit: 100 });
+  await storage.delete("contracts/unique-id.pdf"); // safe retry; provider errors still throw
+} finally {
+  await app.stop();
+}
+```
+
+Object services are **trusted internal APIs**, not public endpoints. Knowing a key grants no application permission. Even `publicAssets` stays private: names never enable public ACLs. All uploads create a new key; an existing key causes `conflict`, not overwrite. Keys are not original filenames. Metadata includes provider size, content type, ETag, timestamp, version and custom metadata where available. Listing cursors are backend-specific, not portable or snapshot guarantees.
+
+## S3-compatible and R2
+
+```ts
+import { createS3StoragePlugin } from "@lenso/storage/s3";
+const privateFiles = createS3StoragePlugin({
+  id: "privateFiles",
+  bucket: "private-files",
+  clientConfig: { region: "us-east-1" }, // SDK credential chain; no credentials in source
+});
+// R2 S3 API uses the same adapter, separately from the binding:
+const r2S3 = createS3StoragePlugin({
+  id: "r2S3",
+  bucket: "files",
+  clientConfig: { region: "auto", endpoint: process.env.R2_S3_ENDPOINT },
+  multipart: false,
+});
+```
+
+S3-compatible providers must honor conditional create (`If-None-Match: *`). Multipart mode additionally requires conditional `CompleteMultipartUpload`. AWS supports it; R2 does not document that condition on completion. Known R2 endpoints select single-PUT mode, which requires `size`; use `multipart: false` explicitly for other providers without conditional multipart completion. The SDK bounds multipart buffering rather than loading the whole object; `maxUploadBytes` exposes this adapter's limit (5 GiB single PUT; 10,000 × 5 MiB multipart parts). Supplied clients remain application-owned; single-PUT clients need `requestChecksumCalculation: "WHEN_REQUIRED"`. Never give an SDK client a payload-logging logger.
+
+```ts
+import { createR2StoragePlugin } from "@lenso/storage/r2";
+const privateFiles = createR2StoragePlugin({ id: "privateFiles", binding: env.PRIVATE_FILES });
+// Native binding upload needs known size and Workers FixedLengthStream.
+await app.get(privateFiles).put({
+  key: crypto.randomUUID(),
+  body: request.body!,
+  size: trustedExpectedSize,
+  maxBytes: serverLimit,
+});
+```
+
+R2 binding has no presigner and no provider request-abort API. Cancellation interrupts the source stream; an already-running platform operation must settle. For R2/local downloads use an application-authorized Fetch endpoint, or separately configure the S3 adapter for R2 presigned URLs. No binding or externally supplied client is closed.
+
+`examples/workers/src/storage.ts` also demonstrates both native binding instances and checks against real Workers `R2Bucket` types. It adds no bucket configuration or routes.
+
+## Optional file records and authorization
+
+Reuse the existing Notes example, not a second application:
+
+```sh
+bun install
+bun run build
+mkdir -p output
+cd examples/notes
+export NOTES_LOGIN_KEYS="$(bun -e 'console.log(JSON.stringify([{subjectId:"local-demo",key:Array.from(crypto.getRandomValues(new Uint8Array(32)),b=>b.toString(16).padStart(2,"0")).join("")}]))')"
+export NOTES_LOGIN_KEY="$(bun -e 'console.log(JSON.parse(process.env.NOTES_LOGIN_KEYS)[0].key)')"
+SQLITE_PATH=../../output/notes-files.sqlite bun run migrate:sqlite
+SQLITE_PATH=../../output/notes-files.sqlite bun run files:migrate
+SQLITE_PATH=../../output/notes-files.sqlite bun run files:demo
+```
+
+`examples/notes/src/files.ts` binds two local instances, the existing Notes database resource, its Auth instance and an owner/tenant policy. The demo verifies the configured login key before deriving its file access context, streams a private upload, gets a stable `fileId`, downloads it and retries deletion. The login-key source and fixed local tenant are application configuration, not a production identity system. No credentials are written to tracked files.
+
+Import `fileSchema` and `createSqliteFileQueries` (or the PostgreSQL equivalents), include the table in your existing database schema, then use `createFilesPlugin({ id, storages, database, queries, authorize })`. `authorize({ access, action, file })` is required for every file operation; omitting it denies access. Owner/tenant fields are application associations, not a user system. Applications authenticate `access` and validate assignments and quota/type policies themselves. The plugin neither creates identities nor assumes future Auth APIs.
+
+Migrations belong to this package at `migrations/sqlite/0001_files.sql` and `migrations/postgres/0001_files.sql`. Execute them explicitly using your database migration process; D1 can use `wrangler d1 migrations apply --local`. Starting the plugin never changes the schema. Object-only use requires no database.
+
+## Direct upload and signed download
+
+```ts
+const files = app.get(filePlugin);
+const { file, link } = await files.beginUpload(access, {
+  storageId: privateFiles.id,
+  filename: "contract.pdf",
+  contentType: "application/pdf",
+  maxBytes: 20 * 1024 * 1024,
+  expiresIn: 300,
+  ownerId: access.ownerId,
+  tenantId: access.tenantId,
+});
+// Send link only to the authorized client, never a logger.
+await fetch(link.url, { method: link.method, headers: link.headers, body: browserFile });
+const ready = await files.completeUpload(access, file.fileId);
+const download = await files.signDownload(access, ready.fileId, 60);
+await fetch(download.url, { headers: download.headers });
+```
+
+Send **all returned headers**. Signed PUT links bind the key, expiry, content type and create-only condition. `maxBytes` is a completion check, **not a provider-enforced upper bound on uploaded traffic**. Completion reads real object metadata and checks existence, size and content type before publishing a ready record; it can verify an already uploaded object after the PUT credential expires. Reads bind the saved ETag where supported. Temporary credentials can expire earlier than the requested TTL. Browser direct access needs application-managed bucket CORS.
+
+URLs are temporary bearer credentials and are not logged by this plugin. Do not put them in analytics, request logs, ordinary RPC/CLI diagnostics or durable file records. A signed link cannot be revoked by removing an application permission. File deletion refuses while its PUT link is live, even after publication: retry after expiry. Failed completion may compensate an invalid object earlier; a still-live PUT can recreate an orphan, but its failed file record cannot become ready. Wait for expiry before reconciling such orphaned keys.
+
+## Raw Fetch, failures and boundaries
+
+`createFileUploadHandler({ files, authenticate, input })` and `createFileDownloadHandler({ files, authenticate, fileId })` return raw Fetch-context handlers usable through `createWebPlugin({ fetch: context => handler, ... })`. Applications choose routes, supply authentication and server-controlled upload limits/owner/tenant inputs. Downloads default to attachment, `nosniff` and `private, no-store`; custom inline serving needs application policy. File bytes stay `ReadableStream`s; metadata, direct-upload initiation/completion and business commands can use the existing typed RPC router. Nothing starts an HTTP server or automatically exposes a private route.
+
+Object write and database commit are separate operations. File states and conditional transitions keep incomplete uploads unpublished; compensation first claims an unpublished failed state, so an ambiguous DB response cannot delete an already committed ready object. Failed deletions remain retryable, including partial local removal. Cleanup/database/provider failures are retained rather than converted to success. Process termination, ambiguous provider writes or an unavailable DB can leave incomplete work for application reconciliation; there is no implicit background worker or cross-resource transaction.
+
+Local roots must be dedicated, application-controlled directories, not upload-selected paths. Traversal and symlinks are rejected, but this is not a sandbox against a hostile process concurrently modifying the filesystem. Do not modify the adapter's on-disk object files manually.
+
+No public bucket provisioning, virus scanning, image processing, thumbnails, deduplication, CDN management, cross-cloud copying, resumable client multipart sessions or Console UI is included.
+
+Official references: [AWS Upload](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-lib-storage/), [Bun Node compatibility](https://bun.com/docs/runtime/nodejs-compat), [R2 binding API](https://developers.cloudflare.com/r2/api/workers/workers-api-reference/), [R2 S3 compatibility](https://developers.cloudflare.com/r2/api/s3/api/), [R2 presigned URLs](https://developers.cloudflare.com/r2/api/s3/presigned-urls/), [Workers FixedLengthStream](https://developers.cloudflare.com/workers/runtime-apis/streams/transformstream/).

package/dist/fetch.d.ts

@@ -0,0 +1,18 @@
+import type { Files, FileUploadInput } from "./files";
+export interface FileFetchContext {
+    request: Request;
+}
+type Authenticate<TAccess> = (request: Request) => TAccess | Promise<TAccess>;
+/** Structurally usable as a Web raw Fetch handler; authentication remains app-owned. */
+export declare function createFileDownloadHandler<TAccess>(options: {
+    files: Files<TAccess>;
+    authenticate: Authenticate<TAccess>;
+    fileId(request: Request): string | null | Promise<string | null>;
+}): (context: FileFetchContext) => Promise<Response | undefined>;
+export declare function createFileUploadHandler<TAccess>(options: {
+    files: Files<TAccess>;
+    authenticate: Authenticate<TAccess>;
+    /** The app chooses storage, ownership, filename and limits, never object keys. */
+    input(request: Request, access: TAccess): FileUploadInput | null | Promise<FileUploadInput | null>;
+}): (context: FileFetchContext) => Promise<Response | undefined>;
+export {};

package/dist/fetch.js

@@ -0,0 +1,98 @@
+import {
+  StorageError2
+} from "./index-0fz1t930.js";
+
+// src/fetch.ts
+var privateDownloadHeaders = {
+  "cache-control": "private, no-store",
+  "content-disposition": "attachment",
+  "x-content-type-options": "nosniff"
+};
+async function respond(operation) {
+  try {
+    return await operation();
+  } catch (error) {
+    if (!(error instanceof StorageError2))
+      throw error;
+    const status = {
+      "invalid-key": 400,
+      "invalid-input": 400,
+      "not-found": 404,
+      forbidden: 403,
+      unsupported: 501,
+      conflict: 409,
+      "too-large": 413,
+      aborted: 499,
+      provider: 502
+    }[error.code];
+    return Response.json({ error: error.code }, {
+      status,
+      headers: { "cache-control": "private, no-store" }
+    });
+  }
+}
+function createFileDownloadHandler(options) {
+  return async ({ request }) => {
+    if (!["GET", "HEAD", "DELETE"].includes(request.method))
+      return;
+    const fileId = await options.fileId(request);
+    if (fileId === null)
+      return;
+    return respond(async () => {
+      const access = await options.authenticate(request);
+      if (request.method === "DELETE") {
+        await options.files.delete(access, fileId);
+        return new Response(null, { status: 204 });
+      }
+      if (request.method === "HEAD") {
+        const file = await options.files.metadata(access, fileId);
+        if (file.state !== "ready")
+          throw new StorageError2("conflict", "File is not ready");
+        return new Response(null, {
+          headers: {
+            ...privateDownloadHeaders,
+            "content-type": file.contentType,
+            "content-length": String(file.size),
+            ...file.etag ? { etag: file.etag } : {}
+          }
+        });
+      }
+      const object = await options.files.read(access, fileId, { signal: request.signal });
+      return new Response(object.body, {
+        headers: {
+          ...privateDownloadHeaders,
+          "content-type": object.metadata.contentType,
+          "content-length": String(object.metadata.size),
+          ...object.metadata.etag ? { etag: object.metadata.etag } : {}
+        }
+      });
+    });
+  };
+}
+function createFileUploadHandler(options) {
+  return async ({ request }) => {
+    if (request.method !== "PUT")
+      return;
+    return respond(async () => {
+      const access = await options.authenticate(request);
+      const input = await options.input(request, access);
+      if (!input)
+        return new Response(null, { status: 404 });
+      if (!request.body)
+        throw new StorageError2("invalid-input", "Upload body required");
+      const file = await options.files.upload(access, {
+        ...input,
+        body: request.body,
+        signal: request.signal
+      });
+      return Response.json(file, {
+        status: 201,
+        headers: { "cache-control": "private, no-store" }
+      });
+    });
+  };
+}
+export {
+  createFileDownloadHandler,
+  createFileUploadHandler
+};

package/dist/files.d.ts

@@ -0,0 +1,68 @@
+import { type Plugin } from "@lenso/core/plugin";
+import { type ObjectStorage, type ObjectDownload, type SignedObjectLink } from "./index";
+export type FileState = "pending" | "uploading" | "ready" | "failed" | "deleting" | "deleted";
+export type FileAction = "upload" | "completeUpload" | "metadata" | "read" | "delete" | "signDownload";
+export interface FileRecord {
+    fileId: string;
+    storageId: string;
+    objectKey: string;
+    filename: string;
+    contentType: string;
+    ownerId: string | null;
+    tenantId: string | null;
+    state: FileState;
+    revision: number;
+    size: number | null;
+    expectedSize: number | null;
+    maxBytes: number | null;
+    etag: string | null;
+    uploadExpiresAt: number | null;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface FileQueries {
+    insert(file: FileRecord): Promise<void>;
+    get(fileId: string): Promise<FileRecord | null>;
+    /** Atomically replace only the matching revision; return false on contention. */
+    transition(fileId: string, revision: number, next: FileRecord): Promise<boolean>;
+}
+export interface FileUploadInput {
+    storageId: string;
+    filename: string;
+    contentType: string;
+    size?: number;
+    maxBytes?: number;
+    ownerId?: string;
+    tenantId?: string;
+    signal?: AbortSignal;
+}
+export interface Files<TAccess> {
+    upload(access: TAccess, input: FileUploadInput & {
+        body: ReadableStream<Uint8Array>;
+    }): Promise<FileRecord>;
+    beginUpload(access: TAccess, input: FileUploadInput & {
+        maxBytes: number;
+        expiresIn: number;
+    }): Promise<{
+        file: FileRecord;
+        link: SignedObjectLink;
+    }>;
+    completeUpload(access: TAccess, fileId: string): Promise<FileRecord>;
+    metadata(access: TAccess, fileId: string): Promise<FileRecord>;
+    read(access: TAccess, fileId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<ObjectDownload>;
+    delete(access: TAccess, fileId: string): Promise<FileRecord>;
+    signDownload(access: TAccess, fileId: string, expiresIn: number): Promise<SignedObjectLink>;
+}
+export declare function createFilesPlugin<TDb, TAccess>(options: {
+    id: string;
+    storages: readonly Plugin<ObjectStorage>[];
+    database: Plugin<TDb>;
+    queries(db: TDb): FileQueries;
+    authorize?: (input: {
+        access: TAccess;
+        action: FileAction;
+        file: Readonly<FileRecord>;
+    }) => boolean | Promise<boolean>;
+}): Plugin<Files<TAccess>>;

package/dist/files.js

@@ -0,0 +1,237 @@
+import {
+  StorageError2,
+  validateContentType2,
+  validateExpiry2
+} from "./index-0fz1t930.js";
+import {
+  validateUpload,
+  checkedUpload
+} from "./index-fa6z0g4w.js";
+
+// src/files.ts
+import { definePlugin } from "@lenso/core/plugin";
+function assertFileReady(file) {
+  if (file.state !== "ready")
+    throw new StorageError2("conflict", "File is not ready");
+}
+function verifyUploadedMetadata(file, object, direct) {
+  if (!object)
+    throw new StorageError2("not-found", "Uploaded object is missing");
+  if (object.key !== file.objectKey || object.contentType !== file.contentType || !Number.isSafeInteger(object.size) || object.size < 0 || file.expectedSize !== null && object.size !== file.expectedSize) {
+    throw new StorageError2("invalid-input", "Uploaded metadata does not match");
+  }
+  if (file.maxBytes !== null && object.size > file.maxBytes) {
+    throw new StorageError2("too-large", "Uploaded object exceeds size limit");
+  }
+  if (direct && !object.etag)
+    throw new StorageError2("unsupported", "Direct uploads require an object etag");
+  return object;
+}
+function createFileDraft(input) {
+  validateUpload({ ...input, key: "validation", body: new ReadableStream });
+  validateContentType2(input.contentType);
+  if (!input.filename)
+    throw new StorageError2("invalid-input", "Filename is required");
+  const now = Date.now();
+  return {
+    fileId: crypto.randomUUID(),
+    objectKey: `files/${crypto.randomUUID()}`,
+    storageId: input.storageId,
+    filename: input.filename,
+    contentType: input.contentType,
+    ownerId: input.ownerId ?? null,
+    tenantId: input.tenantId ?? null,
+    state: "pending",
+    revision: 0,
+    size: null,
+    etag: null,
+    expectedSize: input.size ?? null,
+    maxBytes: input.maxBytes ?? null,
+    uploadExpiresAt: null,
+    createdAt: now,
+    updatedAt: now
+  };
+}
+function createFilesPlugin(options) {
+  return definePlugin({
+    id: options.id,
+    requires: [options.database, ...options.storages],
+    setup(context) {
+      const queries = options.queries(context.get(options.database));
+      const storages = new Map(options.storages.map((ref) => [ref.id, context.get(ref)]));
+      function storage(file) {
+        const result = storages.get(file.storageId);
+        if (!result)
+          throw new StorageError2("invalid-input", "Unknown storage");
+        return result;
+      }
+      async function authorize(access, action, file) {
+        if (!options.authorize || !await options.authorize({ access, action, file: Object.freeze({ ...file }) })) {
+          throw new StorageError2("forbidden", "File operation denied");
+        }
+      }
+      async function load(access, action, fileId) {
+        const file = await queries.get(fileId);
+        if (!file)
+          throw new StorageError2("not-found", "File not found");
+        await authorize(access, action, file);
+        return file;
+      }
+      async function transition(file, patch) {
+        const next = { ...file, ...patch, revision: file.revision + 1, updatedAt: Date.now() };
+        if (!await queries.transition(file.fileId, file.revision, next)) {
+          throw new StorageError2("conflict", "File state changed concurrently");
+        }
+        return next;
+      }
+      async function fail(file, error, cleanup) {
+        const errors = [error];
+        let claimed = false;
+        try {
+          await transition(file, { state: "failed" });
+          claimed = true;
+        } catch (cause) {
+          errors.push(cause);
+          try {
+            const current = await queries.get(file.fileId);
+            claimed = current?.state === "failed" && current.revision === file.revision + 1 && current.storageId === file.storageId && current.objectKey === file.objectKey;
+          } catch (lookupError) {
+            errors.push(lookupError);
+          }
+        }
+        if (cleanup && claimed) {
+          try {
+            await storage(file).delete(file.objectKey);
+          } catch (cause) {
+            errors.push(cause);
+          }
+        }
+        if (errors.length > 1)
+          throw new AggregateError(errors, "Upload and recovery failed");
+        throw error;
+      }
+      return {
+        async upload(access, input) {
+          let file = createFileDraft(input);
+          const objects = storage(file);
+          await authorize(access, "upload", file);
+          await queries.insert(file);
+          file = await transition(file, { state: "uploading" });
+          let checked;
+          let owned = false;
+          try {
+            checked = checkedUpload({ ...input, key: file.objectKey });
+            owned = true;
+            const object = await objects.put({ ...input, key: file.objectKey, body: checked.body });
+            verifyUploadedMetadata(file, object, false);
+            if (object.size !== checked.size())
+              throw new StorageError2("invalid-input", "Adapter did not consume the upload");
+            await checked.cancel();
+            return await transition(file, {
+              state: "ready",
+              size: object.size,
+              etag: object.etag ?? null
+            });
+          } catch (error) {
+            if (error instanceof StorageError2 && (error.code === "conflict" || error.code === "forbidden")) {
+              owned = false;
+            }
+            let failure = error;
+            try {
+              await checked?.cancel(error);
+            } catch (cause) {
+              failure = new AggregateError([error, cause], "Upload and source cleanup failed");
+            }
+            return await fail(file, failure, owned);
+          }
+        },
+        async beginUpload(access, input) {
+          validateExpiry2(input.expiresIn);
+          if (input.maxBytes === undefined)
+            throw new StorageError2("invalid-input", "Direct upload size limit is required");
+          let file = createFileDraft(input);
+          const objects = storage(file);
+          await authorize(access, "upload", file);
+          if (!objects.capabilities.signedUpload || !objects.capabilities.conditionalRead) {
+            throw new StorageError2("unsupported", "Safe direct uploads require signing and conditional reads");
+          }
+          await queries.insert(file);
+          try {
+            const link = await objects.signUpload({
+              key: file.objectKey,
+              expiresIn: input.expiresIn,
+              contentType: file.contentType,
+              maxBytes: input.maxBytes
+            });
+            if (link.method !== "PUT" || !link.conditions.createOnly || !Number.isFinite(link.expiresAt.getTime()) || link.expiresAt.getTime() <= Date.now() || link.expiresAt.getTime() > Date.now() + input.expiresIn * 1000) {
+              throw new StorageError2("unsupported", "Adapter did not issue a bounded create-only upload");
+            }
+            file = await transition(file, { uploadExpiresAt: link.expiresAt.getTime() });
+            return { file, link };
+          } catch (error) {
+            return await fail(file, error, false);
+          }
+        },
+        async completeUpload(access, fileId) {
+          let file = await load(access, "completeUpload", fileId);
+          if (file.state !== "pending" || file.uploadExpiresAt === null) {
+            throw new StorageError2("conflict", "File is not awaiting direct completion");
+          }
+          file = await transition(file, { state: "uploading" });
+          try {
+            const object = verifyUploadedMetadata(file, await storage(file).head(file.objectKey), true);
+            return await transition(file, {
+              state: "ready",
+              size: object.size,
+              etag: object.etag
+            });
+          } catch (error) {
+            return await fail(file, error, true);
+          }
+        },
+        async metadata(access, fileId) {
+          return load(access, "metadata", fileId);
+        },
+        async read(access, fileId, readOptions) {
+          const file = await load(access, "read", fileId);
+          assertFileReady(file);
+          const objects = storage(file);
+          return objects.get(file.objectKey, {
+            ...readOptions,
+            ifMatch: objects.capabilities.conditionalRead ? file.etag ?? undefined : undefined
+          });
+        },
+        async delete(access, fileId) {
+          let file = await load(access, "delete", fileId);
+          if (file.state === "deleted")
+            return file;
+          if (file.state === "uploading")
+            throw new StorageError2("conflict", "Upload is in progress");
+          if (file.uploadExpiresAt !== null && Date.now() < file.uploadExpiresAt) {
+            throw new StorageError2("conflict", "Wait for the upload credential to expire before deleting");
+          }
+          file = await transition(file, { state: "deleting" });
+          await storage(file).delete(file.objectKey);
+          return transition(file, { state: "deleted" });
+        },
+        async signDownload(access, fileId, expiresIn) {
+          validateExpiry2(expiresIn);
+          const file = await load(access, "signDownload", fileId);
+          assertFileReady(file);
+          const link = await storage(file).signDownload({
+            key: file.objectKey,
+            expiresIn,
+            ifMatch: file.etag ?? undefined
+          });
+          if (file.etag && link.conditions.ifMatch !== file.etag) {
+            throw new StorageError2("unsupported", "Signed download cannot pin the published object");
+          }
+          return link;
+        }
+      };
+    }
+  });
+}
+export {
+  createFilesPlugin
+};

package/dist/index-0fz1t930.js

@@ -0,0 +1,64 @@
+// src/index.ts
+import { definePlugin } from "@lenso/core/plugin";
+
+class StorageError2 extends Error {
+  code;
+  constructor(code, message, options) {
+    super(message, options);
+    this.code = code;
+    this.name = "StorageError";
+  }
+}
+function createStoragePlugin2(options) {
+  return definePlugin({
+    id: options.id,
+    requires: options.requires,
+    async setup(context) {
+      return { ...await options.setup(context), id: options.id };
+    }
+  });
+}
+function validateKey2(key) {
+  let unsafeCharacter = false;
+  for (const character of key) {
+    const code = character.charCodeAt(0);
+    if (character === "\\" || code < 32 || code === 127)
+      unsafeCharacter = true;
+  }
+  if (!key || new TextEncoder().encode(key).length > 1024 || unsafeCharacter || key.split("/").some((part) => !part || part === "." || part === "..") || key.startsWith("/") || /^[a-zA-Z]:/.test(key))
+    throw new StorageError2("invalid-key", "Object key must be a relative, nonempty path without traversal");
+}
+function validateContentType2(contentType) {
+  if (!contentType || contentType.length > 1024 || [...contentType].some((character) => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127)) {
+    throw new StorageError2("invalid-input", "Content type must be a nonempty header value without control characters");
+  }
+}
+function validateList2(input) {
+  if (input.prefix)
+    validateKey2(input.prefix.endsWith("/") ? input.prefix.slice(0, -1) : input.prefix);
+  const limit = input.limit ?? 100;
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1000) {
+    throw new StorageError2("invalid-input", "List limit must be between 1 and 1000");
+  }
+  return limit;
+}
+function validateRange2(options, supported) {
+  if (!options.range)
+    return;
+  if (!supported)
+    throw new StorageError2("unsupported", "Range reads are not supported");
+  const { offset, length } = options.range;
+  if (!Number.isSafeInteger(offset) || offset < 0 || length !== undefined && (!Number.isSafeInteger(length) || length <= 0)) {
+    throw new StorageError2("invalid-input", "Range needs a nonnegative offset and positive length");
+  }
+}
+function validateExpiry2(expiresIn) {
+  if (!Number.isSafeInteger(expiresIn) || expiresIn < 1 || expiresIn > 604800) {
+    throw new StorageError2("invalid-input", "Link expiry must be 1 to 604800 seconds; credentials may expire sooner");
+  }
+}
+function unsupportedSigning2() {
+  throw new StorageError2("unsupported", "This adapter cannot issue signed URLs; configure an authorized application Fetch endpoint");
+}
+
+export { StorageError2, createStoragePlugin2, validateKey2, validateContentType2, validateList2, validateRange2, validateExpiry2, unsupportedSigning2 };