@uploadcn/server 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UploadCN contributors
+
+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,39 @@
-# Temporary Holding Version
+# @uploadcn/server
 
-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.
+A Web-standard (`Request` → `Response`) upload route for [UploadCN](https://uploadcn.dev):
+presigned uploads and multipart signing for Amazon S3, Cloudflare R2 and S3-compatible
+storage. Runs on Node.js, Bun, Deno, Cloudflare Workers and edge runtimes. Signing uses
+Web Crypto via `aws4fetch`. No AWS SDK.
+
+```bash
+npm install @uploadcn/server
+```
+
+```ts
+// app/api/upload/route.ts (Next.js)
+import { createUploadRoute, s3Storage } from "@uploadcn/server"
+
+export const { POST } = createUploadRoute({
+  storage: s3Storage({
+    bucket: process.env.S3_BUCKET!,
+    region: process.env.S3_REGION!,
+    accessKeyId: process.env.S3_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
+  }),
+  maxFileSize: 500 * 1024 * 1024,
+  allowedTypes: ["image/*", "application/pdf"],
+  async authorize({ request }) {
+    // throw new UploadRouteError("Unauthorized", 401)
+  },
+  async onUploadComplete({ key, file }) {
+    // save metadata, enqueue a virus scan…
+  },
+})
+```
+
+Signatures lock the content type and length; completed uploads are verified with `HEAD`
+before `onUploadComplete` runs.
+
+Documentation: https://uploadcn.dev/docs/reference/server
+
+MIT

package/dist/fs.d.ts

@@ -0,0 +1,36 @@
+import { i as UploadStorage } from "./storage-CGGIhRB9.js";
+//#region src/fs.d.ts
+export interface FileSystemStorageOptions {
+  /** Folder where files are written, e.g. `./uploads`. */
+  directory: string;
+  /**
+   * URL where `handler` is mounted, e.g. `/api/files`. Signed upload and
+   * download URLs point here.
+   */
+  baseUrl: string;
+  /** HMAC secret for signed URLs. Use a long random value. */
+  secret: string;
+  /**
+   * Serve files publicly from this URL (e.g. `/uploads` when `directory` is
+   * inside `public/`). Without it, reads use short-lived signed URLs.
+   */
+  publicUrl?: string;
+  /** Largest accepted request body, in bytes. Default 5 GiB. */
+  maxBodySize?: number;
+  /** Lifetime of signed download URLs, in seconds. Default 3600. */
+  downloadExpiresIn?: number;
+}
+/**
+ * Stores uploads on the server's disk — for self-hosted apps, VPSs and
+ * local development. Implements the full presigned and multipart flow, so
+ * every UploadCN adapter and component works unchanged.
+ *
+ * Node.js only. Don't use it on serverless platforms with ephemeral disks.
+ */
+export declare function createFileSystemStorage(options: FileSystemStorageOptions): {
+  storage: UploadStorage;
+  handler: (request: Request) => Promise<Response>;
+  baseUrl: string;
+};
+//#endregion
+//# sourceMappingURL=fs.d.ts.map

package/dist/fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","names":[],"sources":["../src/fs.ts"],"mappings":";;iBAWiB;;EAEf;;;;;EAKA;;EAEA;;;;;EAKA;;EAEA;;EAEA;;;;;;;;;wBAcc,wBAAwB,SAAS;;EAiLf,UAAA,SAAA,YAAU,QAAQ"}

package/dist/fs.js

@@ -0,0 +1,216 @@
+import { t as createUrlSigner } from "./signing-DZiuKRaJ.js";
+import { createHash, randomUUID } from "node:crypto";
+import { createReadStream, createWriteStream } from "node:fs";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+//#region src/fs.ts
+const PARTS = ".parts";
+var BodyTooLarge = class extends Error {};
+/**
+* Stores uploads on the server's disk — for self-hosted apps, VPSs and
+* local development. Implements the full presigned and multipart flow, so
+* every UploadCN adapter and component works unchanged.
+*
+* Node.js only. Don't use it on serverless platforms with ephemeral disks.
+*/
+function createFileSystemStorage(options) {
+	const root = path.resolve(options.directory);
+	const maxBodySize = options.maxBodySize ?? 5 * 1024 ** 3;
+	const { base, sign, verify } = createUrlSigner(options.secret, options.baseUrl);
+	function resolveKey(key) {
+		const normalized = path.posix.normalize(key.replace(/\\/g, "/"));
+		if (!normalized || normalized.startsWith("..") || path.posix.isAbsolute(normalized) || normalized.split("/").includes(PARTS)) throw new Error(`Invalid object key: ${key}`);
+		const target = path.join(root, normalized);
+		if (!target.startsWith(root + path.sep)) throw new Error(`Invalid object key: ${key}`);
+		return target;
+	}
+	function partsDir(uploadId) {
+		if (!/^[\w-]+$/.test(uploadId)) throw new Error("Invalid upload id");
+		return path.join(root, PARTS, uploadId);
+	}
+	/** Streams a request body to disk, enforcing the size limit. */
+	async function writeBody(body, target, expectedSize) {
+		await fs.mkdir(path.dirname(target), { recursive: true });
+		const temporary = `${target}.${randomUUID()}.tmp`;
+		const hash = createHash("sha256");
+		let size = 0;
+		const limit = expectedSize ?? maxBodySize;
+		const meter = new Transform({ transform(chunk, _encoding, callback) {
+			size += chunk.length;
+			if (size > limit) return callback(new BodyTooLarge());
+			hash.update(chunk);
+			callback(null, chunk);
+		} });
+		try {
+			await pipeline(Readable.fromWeb(body), meter, createWriteStream(temporary));
+			if (expectedSize != null && size !== expectedSize) throw new Error("Body size does not match the signed size");
+			await fs.rename(temporary, target);
+		} catch (error) {
+			await fs.rm(temporary, { force: true });
+			throw error;
+		}
+		return {
+			size,
+			etag: `"${size}-${hash.digest("hex").slice(0, 32)}"`
+		};
+	}
+	const storage = {
+		name: "filesystem",
+		async presignPut({ key, contentType, contentLength, expiresIn }) {
+			resolveKey(key);
+			return {
+				url: await sign({
+					key,
+					method: "PUT",
+					size: contentLength,
+					expires: Date.now() + expiresIn * 1e3
+				}),
+				headers: { "content-type": contentType }
+			};
+		},
+		async createMultipart({ key }) {
+			resolveKey(key);
+			const uploadId = randomUUID();
+			await fs.mkdir(partsDir(uploadId), { recursive: true });
+			return { uploadId };
+		},
+		presignPart({ key, uploadId, partNumber, expiresIn }) {
+			return sign({
+				key,
+				method: "PUT",
+				uploadId,
+				partNumber,
+				expires: Date.now() + expiresIn * 1e3
+			});
+		},
+		async listParts({ uploadId }) {
+			const dir = partsDir(uploadId);
+			const entries = await fs.readdir(dir).catch(() => null);
+			if (!entries) return [];
+			const parts = [];
+			for (const entry of entries.filter((name) => name.endsWith(".json"))) parts.push(JSON.parse(await fs.readFile(path.join(dir, entry), "utf8")));
+			return parts.sort((a, b) => a.partNumber - b.partNumber);
+		},
+		async completeMultipart({ key, uploadId, parts }) {
+			const dir = partsDir(uploadId);
+			const target = resolveKey(key);
+			await fs.mkdir(path.dirname(target), { recursive: true });
+			const temporary = `${target}.${randomUUID()}.tmp`;
+			const out = createWriteStream(temporary);
+			let size = 0;
+			try {
+				for (const part of [...parts].sort((a, b) => a.partNumber - b.partNumber)) {
+					const meta = JSON.parse(await fs.readFile(path.join(dir, `${part.partNumber}.json`), "utf8"));
+					if (meta.etag !== part.etag) throw new Error(`Part ${part.partNumber} does not match its ETag`);
+					size += meta.size;
+					await pipeline(createReadStream(path.join(dir, String(part.partNumber))), out, { end: false });
+				}
+				await new Promise((resolve, reject) => out.end((error) => error ? reject(error) : resolve()));
+				await fs.rename(temporary, target);
+			} catch (error) {
+				out.destroy();
+				await fs.rm(temporary, { force: true });
+				throw error;
+			}
+			await fs.rm(dir, {
+				recursive: true,
+				force: true
+			});
+			return { etag: `"${parts.length}-${size}"` };
+		},
+		async abortMultipart({ uploadId }) {
+			await fs.rm(partsDir(uploadId), {
+				recursive: true,
+				force: true
+			});
+		},
+		async headObject(key) {
+			const stat = await fs.stat(resolveKey(key)).catch(() => null);
+			return stat?.isFile() ? { size: stat.size } : null;
+		},
+		async deleteObject(key) {
+			await fs.rm(resolveKey(key), { force: true });
+		},
+		async getObject(key) {
+			const target = resolveKey(key);
+			if (!(await fs.stat(target).catch(() => null))?.isFile()) return null;
+			return Readable.toWeb(createReadStream(target));
+		},
+		async getUrl(key) {
+			resolveKey(key);
+			if (options.publicUrl) return `${options.publicUrl.replace(/\/+$/, "")}/${key.split("/").map(encodeURIComponent).join("/")}`;
+			return sign({
+				key,
+				method: "GET",
+				expires: Date.now() + (options.downloadExpiresIn ?? 3600) * 1e3
+			});
+		}
+	};
+	/**
+	* Handles signed uploads (PUT) and downloads (GET). Mount it at
+	* `baseUrl`, e.g. `export { handler as GET, handler as PUT }`.
+	*/
+	async function handler(request) {
+		if (request.method !== "PUT" && request.method !== "GET") return new Response("Method not allowed", {
+			status: 405,
+			headers: { allow: "GET, PUT" }
+		});
+		const token = await verify(new URL(request.url).searchParams.get("token"));
+		if (!token || token.method !== request.method) return new Response("Invalid or expired signature", { status: 403 });
+		if (request.method === "GET") {
+			const file = resolveKey(token.key);
+			const stat = await fs.stat(file).catch(() => null);
+			if (!stat?.isFile()) return new Response("Not found", { status: 404 });
+			return new Response(Readable.toWeb(createReadStream(file)), { headers: {
+				"content-length": String(stat.size),
+				"content-type": "application/octet-stream",
+				"content-disposition": `inline; filename*=UTF-8''${encodeURIComponent(path.basename(file))}`,
+				"x-content-type-options": "nosniff"
+			} });
+		}
+		if (Number(request.headers.get("content-length") ?? NaN) > maxBodySize) return new Response("Payload too large", { status: 413 });
+		if (!request.body) return new Response("Empty body", { status: 400 });
+		try {
+			if (token.uploadId != null && token.partNumber != null) {
+				const dir = partsDir(token.uploadId);
+				if (!await fs.stat(dir).catch(() => null)) return new Response("Unknown upload", { status: 404 });
+				const { size, etag } = await writeBody(request.body, path.join(dir, String(token.partNumber)));
+				const meta = {
+					partNumber: token.partNumber,
+					etag,
+					size
+				};
+				await fs.writeFile(path.join(dir, `${token.partNumber}.json`), JSON.stringify(meta));
+				return new Response(null, {
+					status: 200,
+					headers: {
+						etag,
+						"access-control-expose-headers": "ETag"
+					}
+				});
+			}
+			const { etag } = await writeBody(request.body, resolveKey(token.key), token.size);
+			return new Response(null, {
+				status: 200,
+				headers: {
+					etag,
+					"access-control-expose-headers": "ETag"
+				}
+			});
+		} catch (error) {
+			if (error instanceof BodyTooLarge) return new Response("Payload too large", { status: 413 });
+			return new Response(error instanceof Error ? error.message : "Upload failed", { status: 400 });
+		}
+	}
+	return {
+		storage,
+		handler,
+		baseUrl: base
+	};
+}
+//#endregion
+export { createFileSystemStorage };
+
+//# sourceMappingURL=fs.js.map

package/dist/fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.js","names":[],"sources":["../src/fs.ts"],"sourcesContent":["import { createHash, randomUUID } from \"node:crypto\"\nimport { createReadStream, createWriteStream } from \"node:fs\"\nimport * as fs from \"node:fs/promises\"\nimport * as path from \"node:path\"\nimport { Readable, Transform } from \"node:stream\"\nimport { pipeline } from \"node:stream/promises\"\nimport type { ReadableStream as NodeReadableStream } from \"node:stream/web\"\n\nimport { createUrlSigner } from \"./signing\"\nimport type { StoragePart, StoredObjectInfo, UploadStorage } from \"./storage\"\n\nexport interface FileSystemStorageOptions {\n  /** Folder where files are written, e.g. `./uploads`. */\n  directory: string\n  /**\n   * URL where `handler` is mounted, e.g. `/api/files`. Signed upload and\n   * download URLs point here.\n   */\n  baseUrl: string\n  /** HMAC secret for signed URLs. Use a long random value. */\n  secret: string\n  /**\n   * Serve files publicly from this URL (e.g. `/uploads` when `directory` is\n   * inside `public/`). Without it, reads use short-lived signed URLs.\n   */\n  publicUrl?: string\n  /** Largest accepted request body, in bytes. Default 5 GiB. */\n  maxBodySize?: number\n  /** Lifetime of signed download URLs, in seconds. Default 3600. */\n  downloadExpiresIn?: number\n}\n\nconst PARTS = \".parts\"\n\nclass BodyTooLarge extends Error {}\n\n/**\n * Stores uploads on the server's disk — for self-hosted apps, VPSs and\n * local development. Implements the full presigned and multipart flow, so\n * every UploadCN adapter and component works unchanged.\n *\n * Node.js only. Don't use it on serverless platforms with ephemeral disks.\n */\nexport function createFileSystemStorage(options: FileSystemStorageOptions) {\n  const root = path.resolve(options.directory)\n  const maxBodySize = options.maxBodySize ?? 5 * 1024 ** 3\n  const { base, sign, verify } = createUrlSigner(\n    options.secret,\n    options.baseUrl\n  )\n\n  function resolveKey(key: string) {\n    const normalized = path.posix.normalize(key.replace(/\\\\/g, \"/\"))\n    if (\n      !normalized ||\n      normalized.startsWith(\"..\") ||\n      path.posix.isAbsolute(normalized) ||\n      normalized.split(\"/\").includes(PARTS)\n    ) {\n      throw new Error(`Invalid object key: ${key}`)\n    }\n    const target = path.join(root, normalized)\n    if (!target.startsWith(root + path.sep)) {\n      throw new Error(`Invalid object key: ${key}`)\n    }\n    return target\n  }\n\n  function partsDir(uploadId: string) {\n    if (!/^[\\w-]+$/.test(uploadId)) throw new Error(\"Invalid upload id\")\n    return path.join(root, PARTS, uploadId)\n  }\n\n  /** Streams a request body to disk, enforcing the size limit. */\n  async function writeBody(\n    body: ReadableStream<Uint8Array>,\n    target: string,\n    expectedSize?: number\n  ) {\n    await fs.mkdir(path.dirname(target), { recursive: true })\n    const temporary = `${target}.${randomUUID()}.tmp`\n    const hash = createHash(\"sha256\")\n    let size = 0\n    const limit = expectedSize ?? maxBodySize\n    const meter = new Transform({\n      transform(chunk: Buffer, _encoding, callback) {\n        size += chunk.length\n        if (size > limit) return callback(new BodyTooLarge())\n        hash.update(chunk)\n        callback(null, chunk)\n      },\n    })\n    try {\n      await pipeline(\n        Readable.fromWeb(body as NodeReadableStream),\n        meter,\n        createWriteStream(temporary)\n      )\n      if (expectedSize != null && size !== expectedSize) {\n        throw new Error(\"Body size does not match the signed size\")\n      }\n      await fs.rename(temporary, target)\n    } catch (error) {\n      await fs.rm(temporary, { force: true })\n      throw error\n    }\n    return { size, etag: `\"${size}-${hash.digest(\"hex\").slice(0, 32)}\"` }\n  }\n\n  const storage: UploadStorage = {\n    name: \"filesystem\",\n    async presignPut({ key, contentType, contentLength, expiresIn }) {\n      resolveKey(key)\n      const url = await sign({\n        key,\n        method: \"PUT\",\n        size: contentLength,\n        expires: Date.now() + expiresIn * 1000,\n      })\n      return { url, headers: { \"content-type\": contentType } }\n    },\n    async createMultipart({ key }) {\n      resolveKey(key)\n      const uploadId = randomUUID()\n      await fs.mkdir(partsDir(uploadId), { recursive: true })\n      return { uploadId }\n    },\n    presignPart({ key, uploadId, partNumber, expiresIn }) {\n      return sign({\n        key,\n        method: \"PUT\",\n        uploadId,\n        partNumber,\n        expires: Date.now() + expiresIn * 1000,\n      })\n    },\n    async listParts({ uploadId }) {\n      const dir = partsDir(uploadId)\n      const entries = await fs.readdir(dir).catch(() => null)\n      if (!entries) return []\n      const parts: StoragePart[] = []\n      for (const entry of entries.filter((name) => name.endsWith(\".json\"))) {\n        parts.push(JSON.parse(await fs.readFile(path.join(dir, entry), \"utf8\")))\n      }\n      return parts.sort((a, b) => a.partNumber - b.partNumber)\n    },\n    async completeMultipart({ key, uploadId, parts }) {\n      const dir = partsDir(uploadId)\n      const target = resolveKey(key)\n      await fs.mkdir(path.dirname(target), { recursive: true })\n      const temporary = `${target}.${randomUUID()}.tmp`\n      const out = createWriteStream(temporary)\n      let size = 0\n      try {\n        for (const part of [...parts].sort(\n          (a, b) => a.partNumber - b.partNumber\n        )) {\n          const meta = JSON.parse(\n            await fs.readFile(path.join(dir, `${part.partNumber}.json`), \"utf8\")\n          ) as StoragePart\n          if (meta.etag !== part.etag) {\n            throw new Error(`Part ${part.partNumber} does not match its ETag`)\n          }\n          size += meta.size\n          await pipeline(\n            createReadStream(path.join(dir, String(part.partNumber))),\n            out,\n            {\n              end: false,\n            }\n          )\n        }\n        await new Promise<void>((resolve, reject) =>\n          out.end((error?: Error | null) => (error ? reject(error) : resolve()))\n        )\n        await fs.rename(temporary, target)\n      } catch (error) {\n        out.destroy()\n        await fs.rm(temporary, { force: true })\n        throw error\n      }\n      await fs.rm(dir, { recursive: true, force: true })\n      return { etag: `\"${parts.length}-${size}\"` }\n    },\n    async abortMultipart({ uploadId }) {\n      await fs.rm(partsDir(uploadId), { recursive: true, force: true })\n    },\n    async headObject(key): Promise<StoredObjectInfo | null> {\n      const stat = await fs.stat(resolveKey(key)).catch(() => null)\n      return stat?.isFile() ? { size: stat.size } : null\n    },\n    async deleteObject(key) {\n      await fs.rm(resolveKey(key), { force: true })\n    },\n    async getObject(key) {\n      const target = resolveKey(key)\n      const stat = await fs.stat(target).catch(() => null)\n      if (!stat?.isFile()) return null\n      return Readable.toWeb(\n        createReadStream(target)\n      ) as unknown as ReadableStream<Uint8Array>\n    },\n    async getUrl(key) {\n      resolveKey(key)\n      if (options.publicUrl) {\n        const prefix = options.publicUrl.replace(/\\/+$/, \"\")\n        return `${prefix}/${key.split(\"/\").map(encodeURIComponent).join(\"/\")}`\n      }\n      return sign({\n        key,\n        method: \"GET\",\n        expires: Date.now() + (options.downloadExpiresIn ?? 3600) * 1000,\n      })\n    },\n  }\n\n  /**\n   * Handles signed uploads (PUT) and downloads (GET). Mount it at\n   * `baseUrl`, e.g. `export { handler as GET, handler as PUT }`.\n   */\n  async function handler(request: Request): Promise<Response> {\n    if (request.method !== \"PUT\" && request.method !== \"GET\") {\n      return new Response(\"Method not allowed\", {\n        status: 405,\n        headers: { allow: \"GET, PUT\" },\n      })\n    }\n    const token = await verify(new URL(request.url).searchParams.get(\"token\"))\n    if (!token || token.method !== request.method) {\n      return new Response(\"Invalid or expired signature\", { status: 403 })\n    }\n\n    if (request.method === \"GET\") {\n      const file = resolveKey(token.key)\n      const stat = await fs.stat(file).catch(() => null)\n      if (!stat?.isFile()) return new Response(\"Not found\", { status: 404 })\n      return new Response(\n        Readable.toWeb(createReadStream(file)) as ReadableStream,\n        {\n          headers: {\n            \"content-length\": String(stat.size),\n            \"content-type\": \"application/octet-stream\",\n            \"content-disposition\": `inline; filename*=UTF-8''${encodeURIComponent(path.basename(file))}`,\n            \"x-content-type-options\": \"nosniff\",\n          },\n        }\n      )\n    }\n\n    const declared = Number(request.headers.get(\"content-length\") ?? NaN)\n    if (declared > maxBodySize) {\n      return new Response(\"Payload too large\", { status: 413 })\n    }\n    if (!request.body) return new Response(\"Empty body\", { status: 400 })\n    try {\n      if (token.uploadId != null && token.partNumber != null) {\n        const dir = partsDir(token.uploadId)\n        const stat = await fs.stat(dir).catch(() => null)\n        if (!stat) return new Response(\"Unknown upload\", { status: 404 })\n        const { size, etag } = await writeBody(\n          request.body,\n          path.join(dir, String(token.partNumber))\n        )\n        const meta: StoragePart = { partNumber: token.partNumber, etag, size }\n        await fs.writeFile(\n          path.join(dir, `${token.partNumber}.json`),\n          JSON.stringify(meta)\n        )\n        return new Response(null, {\n          status: 200,\n          headers: { etag, \"access-control-expose-headers\": \"ETag\" },\n        })\n      }\n      const { etag } = await writeBody(\n        request.body,\n        resolveKey(token.key),\n        token.size\n      )\n      return new Response(null, {\n        status: 200,\n        headers: { etag, \"access-control-expose-headers\": \"ETag\" },\n      })\n    } catch (error) {\n      if (error instanceof BodyTooLarge) {\n        return new Response(\"Payload too large\", { status: 413 })\n      }\n      return new Response(\n        error instanceof Error ? error.message : \"Upload failed\",\n        { status: 400 }\n      )\n    }\n  }\n\n  return { storage, handler, baseUrl: base }\n}\n"],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,193 @@
+import { i as UploadStorage, n as StoragePart, r as StoredObjectInfo, t as PresignedRequest } from "./storage-CGGIhRB9.js";
+import { a as ScanResult, o as Scanner } from "./scan-B8LojfB0.js";
+import { FileDescriptor, FileDescriptor as FileDescriptor$1, StoredObject, UploadRouteAction, UploadRouteAction as UploadRouteAction$1, UploadRouteRequest } from "@uploadcn/core";
+//#region src/route.d.ts
+export declare class UploadRouteError extends Error {
+  readonly status: number;
+  /** `"rejected"` tells the client the file itself was refused (no retry). */
+  readonly code?: "rejected" | undefined;
+  readonly name = "UploadRouteError";
+  constructor(message: string, status?: number,
+  /** `"rejected"` tells the client the file itself was refused (no retry). */
+  code?: "rejected" | undefined);
+}
+interface UploadScanOptions<TAuth> {
+  /** `clamavScanner()`, `virusTotalScanner()`, `httpScanner()` or your own. */
+  scanner: Scanner;
+  /**
+   * What to do when the scanner can't decide, or fails: `"reject"` (default,
+   * fail closed) deletes the file; `"allow"` keeps it.
+   */
+  onUnknown?: "reject" | "allow";
+  /** Files larger than this (bytes) are not scanned and count as unknown. */
+  maxFileSize?: number;
+  /** Every verdict, for logging, alerts or an audit trail. */
+  onResult?: (context: UploadRouteContext<TAuth> & {
+    key: string;
+    file: FileDescriptor$1;
+    result: ScanResult;
+  }) => void | Promise<void>;
+}
+interface UploadRouteContext<TAuth> {
+  request: Request;
+  action: UploadRouteAction$1;
+  /** Value returned by `authorize`. */
+  auth: TAuth;
+}
+interface UploadRouteOptions<TAuth = undefined> {
+  storage: UploadStorage;
+  /**
+   * Runs before every action. Return a value (user, tenant…) to pass along,
+   * or throw `UploadRouteError` to deny. For multipart actions, `key` is
+   * provided so you can verify the caller owns it.
+   */
+  authorize?: (context: {
+    request: Request;
+    action: UploadRouteAction$1;
+    key?: string;
+  }) => TAuth | Promise<TAuth>;
+  /** Largest allowed file in bytes. Enforced by the signature for single PUTs. */
+  maxFileSize?: number;
+  /** Allowed types, in `<input accept>` syntax (`image/*`, `.pdf`…). */
+  allowedTypes?: string | readonly string[];
+  /** Builds the object key. Default: `<uuid>/<sanitized file name>`. */
+  getKey?: (context: UploadRouteContext<TAuth> & {
+    file: FileDescriptor$1;
+    meta: Record<string, unknown>;
+  }) => string | Promise<string>;
+  /** Signed URL lifetime in seconds. Default 3600. */
+  expiresIn?: number;
+  /**
+   * Called once an upload is stored, verified and (with `scan`) found clean:
+   * save metadata, trigger processing. The return value is sent to the
+   * client as `result.data`.
+   */
+  onUploadComplete?: (context: UploadRouteContext<TAuth> & {
+    key: string;
+    url: string;
+    file: FileDescriptor$1;
+    meta: Record<string, unknown>;
+    /** The scan verdict, when `scan` is set. */
+    scan?: ScanResult;
+  }) => unknown;
+  /** Check that the object exists (HEAD) before completing. Default `true`. */
+  verify?: boolean;
+  /**
+   * Scan every upload for malware before it completes. Infected files are
+   * deleted and the client sees the item as rejected. Requires a storage
+   * that can read objects (`s3Storage`, `r2Storage`, `createFileSystemStorage`).
+   */
+  scan?: UploadScanOptions<TAuth>;
+}
+export declare function sanitizeFileName(name: string): string;
+/**
+ * A single POST endpoint that signs uploads for the browser's `s3Adapter`.
+ * It speaks Web standard `Request`/`Response`, so it mounts directly in
+ * Next.js route handlers, TanStack Start server routes, Hono, Remix, Bun,
+ * Deno and Cloudflare Workers.
+ *
+ * @example
+ * // app/api/upload/route.ts
+ * export const { POST } = createUploadRoute({ storage: s3Storage({...}) })
+ */
+export declare function createUploadRoute<TAuth = undefined>(options: UploadRouteOptions<TAuth>): {
+  POST: (request: Request) => Promise<Response>;
+  handler: (request: Request) => Promise<Response>;
+};
+//#endregion
+//#region src/s3.d.ts
+interface S3StorageOptions {
+  bucket: string;
+  /** AWS region, or `"auto"` for R2. */
+  region: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  sessionToken?: string;
+  /**
+   * Custom endpoint for S3-compatible services (R2, MinIO, B2, Spaces…).
+   * Defaults to AWS.
+   */
+  endpoint?: string;
+  /** Use `endpoint/bucket/key` URLs. Defaults to `true` with a custom endpoint. */
+  forcePathStyle?: boolean;
+  /**
+   * Base URL for reading objects (a CDN or public bucket domain). Without
+   * it, `getUrl` returns a signed GET URL valid for `readUrlExpiresIn`.
+   */
+  publicUrl?: string;
+  /** Seconds. Default 3600. */
+  readUrlExpiresIn?: number;
+}
+export declare class S3StorageError extends Error {
+  readonly status: number;
+  readonly code?: string | undefined;
+  readonly name = "S3StorageError";
+  constructor(message: string, status: number, code?: string | undefined);
+}
+/**
+ * Amazon S3 and any S3-compatible service, signed with SigV4 via aws4fetch.
+ * Runs on Node, Bun, Deno, Cloudflare Workers and edge runtimes.
+ */
+export declare function s3Storage(options: S3StorageOptions): UploadStorage;
+interface R2StorageOptions extends Omit<S3StorageOptions, "region" | "endpoint" | "forcePathStyle"> {
+  /** Your Cloudflare account id. */
+  accountId: string;
+  /** `"eu"` or `"fedramp"` for jurisdiction-restricted buckets. */
+  jurisdiction?: "eu" | "fedramp";
+}
+/** Cloudflare R2 through its S3-compatible API. */
+export declare function r2Storage({ accountId, jurisdiction, ...options }: R2StorageOptions): UploadStorage;
+//#endregion
+//#region src/memory.d.ts
+interface MemoryStorageOptions {
+  /**
+   * Absolute or root-relative URL where `handler` is mounted, e.g.
+   * `/api/storage`. Presigned URLs point here.
+   */
+  baseUrl: string;
+  /** HMAC secret used to sign URLs. Use a random value per deployment. */
+  secret: string;
+  /** Largest accepted request body, in bytes. Default 5 GiB. */
+  maxBodySize?: number;
+}
+/**
+ * A development storage that accepts uploads in-process and keeps only
+ * metadata (size, ETag) — the bytes are discarded. It implements the full
+ * presigned + multipart flow with HMAC-signed URLs, so you can build and
+ * test upload UIs without cloud credentials. Not for production.
+ */
+export declare function createMemoryStorage(options: MemoryStorageOptions): {
+  storage: UploadStorage;
+  handler: (request: Request) => Promise<Response>;
+};
+//#endregion
+//#region src/cloudinary.d.ts
+/**
+ * Signs Cloudinary upload parameters with your API secret, for
+ * `cloudinaryAdapter({ sign })`. Run it on the server only.
+ *
+ * @example
+ * // app/api/cloudinary/route.ts
+ * export async function POST(request: Request) {
+ *   const params = await request.json()
+ *   if (params.folder !== "avatars") return new Response(null, { status: 403 })
+ *   return Response.json(
+ *     await signCloudinaryParams(params, {
+ *       apiKey: process.env.CLOUDINARY_API_KEY!,
+ *       apiSecret: process.env.CLOUDINARY_API_SECRET!,
+ *     })
+ *   )
+ * }
+ */
+export declare function signCloudinaryParams(params: Record<string, string | number>, { apiKey, apiSecret, timestamp }: {
+  apiKey: string;
+  apiSecret: string;
+  timestamp?: number;
+}): Promise<{
+  signature: string;
+  timestamp: number;
+  apiKey: string;
+}>;
+//#endregion
+export type { FileDescriptor, MemoryStorageOptions, PresignedRequest, R2StorageOptions, S3StorageOptions, StoragePart, StoredObject, StoredObjectInfo, UploadRouteAction, UploadRouteContext, UploadRouteOptions, UploadRouteRequest, UploadStorage };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":["FileDescriptor","UploadRouteAction"],"sources":["../src/route.ts","../src/s3.ts","../src/memory.ts","../src/cloudinary.ts"],"mappings":";;;;qBAWa,yBAAyB;WAIzB;;WAEA;WALO;EAEhB,YAAA,iBACS,iBAEA;;EAAA;;UAMI,kBAAkB;;EAEjC,SAAS;;;;;EAKT;;EAEA;;EAEA,YACE,SAAS,mBAAmB;IAC1B;IACA,MAAMA;IACN,QAAQ;eAEA;;UAGG,mBAAmB;EAClC,SAAS;EACT,QAAQC;;EAER,MAAM;;UAGS,mBAAmB;EAClC,SAAS;;;;;;EAMT,aAAa;IACX,SAAS;IACT,QAAQA;IACR;QACI,QAAQ,QAAQ;;EAEtB;;EAEA;;EAEA,UACE,SAAS,mBAAmB;IAC1B,MAAMD;IACN,MAAM;iBAEI;;EAEd;;;;;;EAMA,oBACE,SAAS,mBAAmB;IAC1B;IACA;IACA,MAAMA;IACN,MAAM;;IAEN,OAAO;;;EAIX;;;;;;EAMA,OAAO,kBAAkB;;wBAKX,iBAAiB;;;;;;;;;;;wBAyIjB,kBAAkB,mBAChC,SAAS,mBAAmB;EA4HG,OAAA,SAAA,YAAU,QAAQ;EAAlB,UAAA,SAAA,YAAU,QAAQ;;;;UCxWlC;EACf;;EAEA;EACA;EACA;EACA;;;;;EAKA;;EAEA;;;;;EAKA;;EAEA;;qBAoCW,uBAAuB;WAIvB;WACA;WAJO;EAEhB,YAAA,iBACS,gBACA;;;;;;wBAuBG,UAAU,SAAS,mBAAmB;UAoKrC,yBAAyB,KACxC;;EAIA;;EAEA;;;wBAIc,YACd,WACA,iBACG,WACF,mBAAmB;;;UCxQL;;;;;EAKf;;EAEA;;EAEA;;;;;;;;wBASc,oBAAoB,SAAS;;EA2DX,UAAA,SAAA,YAAU,QAAQ;;;;;;;;;;;;;;;;;;;;;wBC/D9B,qBACpB,QAAQ,mCAEN,QACA,WACA;EACG;EAAgB;EAAmB;IAAoB"}