@quark-fw/plugin-uploads 0.0.0-stage → 0.1.22

package/package.json

@@ -1,6 +1,40 @@
 {
-  "name": "@quark-fw/plugin-uploads",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@quark-fw/plugin-uploads",
+	"version": "0.1.22",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"type": "module",
+	"scripts": {
+		"build": "echo raw-src package, no build",
+		"test": "vitest run"
+	},
+	"files": [
+		"src"
+	],
+	"keywords": [
+		"quark",
+		"uploads",
+		"images",
+		"s3"
+	],
+	"author": "",
+	"license": "ISC",
+	"description": "File uploads for the Quark framework: local/S3 storage, image variants via sharp, cached image serving route, authorize/onSaved hooks (published as raw TS sources; consumers run tsx)",
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@quark-fw/plugin": "0.1.22",
+		"@types/busboy": "^1.5.4",
+		"busboy": "^1.6.0",
+		"express": "^5.2.1",
+		"sharp": "^0.34.0"
+	},
+	"peerDependencies": {
+		"@quark-fw/core": "0.1.22"
+	},
+	"devDependencies": {
+		"@types/express": "^5.0.6",
+		"vitest": "^5.0.0"
+	}
+}

package/src/global.d.ts

@@ -0,0 +1,38 @@
+import "@quark-fw/core/src/global.d.ts";
+import type { Request } from "express";
+import type {
+	UploadStorage,
+	StoredFile,
+} from "@quark-fw/plugin-uploads/src/storage.js";
+import type {
+	StoredImage,
+	VariantsConfig,
+} from "@quark-fw/plugin-uploads/src/images.js";
+
+export {};
+
+declare global {
+	interface Quark {
+		uploads: {
+			/** выбранное хранилище (local по умолчанию, s3 по UPLOAD_DRIVER) */
+			storage: UploadStorage;
+			/** максимальный размер файла в байтах */
+			maxFileSize: number;
+			/** варианты картинок (UPLOAD_VARIANTS); без них сохраняется только оригинал */
+			variants?: VariantsConfig;
+			/** префикс ключей картинок, которые отдаёт маршрут /img (по умолчанию "img/") */
+			imageKeyPrefix: string;
+			/** кто может загружать; по умолчанию — любой залогиненный (req.user) */
+			authorize?: (req: Request) => boolean | Promise<boolean>;
+			/** ключ для нового файла; по умолчанию YYYY-MM/<uuid><ext> */
+			keyFor?: (file: {
+				mimeType: string;
+				originalName: string;
+			}) => string;
+			/** замена элемента ответа (например запись таблицы Image) */
+			onSaved?: (
+				file: StoredFile | StoredImage,
+			) => unknown | Promise<unknown>;
+		};
+	}
+}

package/src/handleUpload.test.ts

@@ -0,0 +1,256 @@
+import { afterAll, beforeAll, beforeEach, expect, test, vi } from "vitest";
+import express from "express";
+import crypto from "node:crypto";
+import sharp from "sharp";
+import { createImageServer } from "./serve.js";
+import fs from "node:fs";
+import http, { type Server } from "node:http";
+import type { AddressInfo } from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { handleUpload } from "./handleUpload.js";
+import { setUploadHeaders } from "./helpers.js";
+import { Readable } from "node:stream";
+import {
+	createLocalStorage,
+	type StoredFile,
+	type UploadStorage,
+} from "./storage.js";
+
+let server: Server;
+let base: string;
+let saved: string[];
+let deleted: string[];
+// save(), которые начались, но ещё не завершились (ни успехом, ни ошибкой)
+let inFlight = 0;
+const dir = fs.mkdtempSync(path.join(os.tmpdir(), "quark-uploads-"));
+
+// хранилище в памяти: сохраняет, дочитав поток, и запоминает удаления
+const memoryStorage: UploadStorage = {
+	name: "memory",
+	async save({ key, stream, mimeType, originalName }): Promise<StoredFile> {
+		inFlight += 1;
+		try {
+			const chunks: Buffer[] = [];
+			for await (const chunk of stream) chunks.push(chunk as Buffer);
+			const body = Buffer.concat(chunks);
+			blobs.set(key, body);
+			saved.push(key);
+			return {
+				key,
+				url: `/m/${key}`,
+				size: body.length,
+				mimeType,
+				originalName,
+			};
+		} finally {
+			inFlight -= 1;
+		}
+	},
+	async delete(key) {
+		deleted.push(key);
+	},
+	async read(key) {
+		const body = blobs.get(key);
+		if (!body) throw new Error("not found");
+		return Readable.from(body);
+	},
+};
+// содержимое сохранённых файлов — для теста раздачи вариантов
+const blobs = new Map<string, Buffer>();
+
+beforeAll(async () => {
+	(globalThis as { quark?: unknown }).quark = {
+		uploads: {
+			storage: memoryStorage,
+			maxFileSize: 1024,
+			imageKeyPrefix: "img/",
+			variants: { "32": { width: 32, format: "webp" } },
+			keyFor: ({ mimeType }: { mimeType: string }) =>
+				mimeType.startsWith("image/")
+					? `img/${crypto.randomUUID().slice(0, 8)}`
+					: `files/${crypto.randomUUID().slice(0, 8)}.txt`,
+		},
+	};
+	fs.writeFileSync(path.join(dir, "evil.html"), "<script>1</script>");
+	fs.writeFileSync(path.join(dir, "pic.png"), "png");
+
+	const app = express();
+	app.use((req, _res, next) => {
+		(req as { user?: unknown }).user = { id: "u1" };
+		next();
+	});
+	app.post("/api/files", handleUpload);
+	app.use(
+		"/img",
+		createImageServer({ storage: memoryStorage, keyPrefix: "img/" }),
+	);
+	app.use(
+		"/uploads",
+		express.static(dir, { index: false, setHeaders: setUploadHeaders }),
+	);
+	server = app.listen(0);
+	await new Promise((resolve) => server.once("listening", resolve));
+	base = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
+});
+
+beforeEach(() => {
+	saved = [];
+	deleted = [];
+});
+
+afterAll(() => {
+	server.close();
+	fs.rmSync(dir, { recursive: true, force: true });
+	delete (globalThis as { quark?: unknown }).quark;
+});
+
+const multipart = (body: string) =>
+	fetch(`${base}/api/files`, {
+		method: "POST",
+		headers: { "content-type": "multipart/form-data; boundary=X" },
+		body,
+		signal: AbortSignal.timeout(3000),
+	});
+
+const part = (name: string, content: string) =>
+	`--X\r\nContent-Disposition: form-data; name="f"; filename="${name}"\r\n` +
+	`Content-Type: text/plain\r\n\r\n${content}\r\n`;
+
+test("корректная загрузка отвечает списком файлов", async () => {
+	const res = await multipart(part("a.txt", "hello") + "--X--\r\n");
+	expect(res.status).toBe(200);
+	const { files } = (await res.json()) as { files: StoredFile[] };
+	expect(files).toHaveLength(1);
+	expect(files[0]!.size).toBe(5);
+});
+
+test("имя файла в UTF-8 не искажается", async () => {
+	const res = await multipart(part("фото.txt", "hi") + "--X--\r\n");
+	expect(res.status).toBe(200);
+	const { files } = (await res.json()) as { files: StoredFile[] };
+	expect(files[0]!.originalName).toBe("фото.txt");
+});
+
+test("оборванный multipart — 400, процесс жив", async () => {
+	// нет закрывающей границы: busboy эмитит error «Unexpected end of form»
+	const res = await multipart(part("a.txt", "hello"));
+	expect(res.status).toBe(400);
+	// сервер продолжает отвечать
+	const again = await multipart(part("b.txt", "ok") + "--X--\r\n");
+	expect(again.status).toBe(200);
+});
+
+test("обрыв соединения посреди файла не оставляет висящий save()", async () => {
+	const { port } = new URL(base);
+	const req = http.request({
+		host: "127.0.0.1",
+		port,
+		path: "/api/files",
+		method: "POST",
+		headers: {
+			"content-type": "multipart/form-data; boundary=X",
+			"content-length": "100000",
+		},
+	});
+	req.on("error", () => {});
+	req.write(part("big.bin", "x".repeat(100)));
+	await vi.waitFor(() => expect(inFlight).toBe(1));
+	req.destroy();
+	// поток файла закрыт вместе с запросом — save() завершился
+	await vi.waitFor(() => expect(inFlight).toBe(0), { timeout: 2000 });
+});
+
+test("html отдаётся скачиванием и с nosniff", async () => {
+	const res = await fetch(`${base}/uploads/evil.html`);
+	expect(res.headers.get("content-disposition")).toBe("attachment");
+	expect(res.headers.get("x-content-type-options")).toBe("nosniff");
+});
+
+test("картинка отдаётся inline", async () => {
+	const res = await fetch(`${base}/uploads/pic.png`);
+	expect(res.headers.get("content-disposition")).toBeNull();
+	expect(res.headers.get("x-content-type-options")).toBe("nosniff");
+});
+
+test("локальное хранилище удаляет недописанный файл при ошибке потока", async () => {
+	const storage = createLocalStorage({ dir });
+	const stream = new Readable({ read() {} });
+	stream.push("partial");
+	setTimeout(() => stream.destroy(new Error("aborted")), 10);
+
+	await expect(
+		storage.save({
+			key: "2026-09/partial.bin",
+			stream,
+			mimeType: "application/octet-stream",
+			originalName: "partial.bin",
+		}),
+	).rejects.toThrow("aborted");
+	expect(fs.existsSync(path.join(dir, "2026-09/partial.bin"))).toBe(false);
+});
+
+test("картинка с вариантами: размеры, превью рядом с оригиналом, раздача через /img", async () => {
+	const png = await sharp({
+		create: { width: 64, height: 48, channels: 3, background: "#3366cc" },
+	})
+		.png()
+		.toBuffer();
+	const body = Buffer.concat([
+		Buffer.from(
+			'--X\r\nContent-Disposition: form-data; name="f"; filename="pic.png"\r\nContent-Type: image/png\r\n\r\n',
+		),
+		png,
+		Buffer.from("\r\n--X--\r\n"),
+	]);
+	const res = await fetch(`${base}/api/files`, {
+		method: "POST",
+		headers: { "content-type": "multipart/form-data; boundary=X" },
+		body,
+	});
+	expect(res.status).toBe(200);
+	const { files } = (await res.json()) as {
+		files: {
+			key: string;
+			width: number;
+			height: number;
+			variants: Record<string, { key: string }>;
+		}[];
+	};
+	expect(files[0]!.width).toBe(64);
+	expect(files[0]!.height).toBe(48);
+	const variant = files[0]!.variants["32"]!;
+	expect(variant.key).toBe(`${files[0]!.key}/32.webp`);
+
+	const served = await fetch(
+		`${base}/img/${files[0]!.key.replace("img/", "")}/32.webp`,
+	);
+	expect(served.status).toBe(200);
+	expect(served.headers.get("content-type")).toBe("image/webp");
+	expect(served.headers.get("cache-control")).toContain("immutable");
+	const meta = await sharp(
+		Buffer.from(await served.arrayBuffer()),
+	).metadata();
+	expect(meta.width).toBe(32);
+	expect(meta.height).toBe(24);
+
+	// оригинал без расширения маршрут не отдаёт, мусорный путь — 404
+	expect(
+		(await fetch(`${base}/img/${files[0]!.key.replace("img/", "")}`))
+			.status,
+	).toBe(404);
+	expect((await fetch(`${base}/img/../etc/passwd`)).status).toBe(404);
+});
+
+test("authorize запрещает загрузку", async () => {
+	const uploads = (
+		globalThis as { quark: { uploads: { authorize?: () => boolean } } }
+	).quark.uploads;
+	uploads.authorize = () => false;
+	try {
+		const res = await multipart(part("a.txt", "hello") + "--X--\r\n");
+		expect(res.status).toBe(403);
+	} finally {
+		delete uploads.authorize;
+	}
+});

package/src/handleUpload.ts

@@ -0,0 +1,148 @@
+import busboy from "busboy";
+import type { Request, Response } from "express";
+import crypto from "node:crypto";
+import { safeExtension } from "./helpers.js";
+import { isImageMime, saveImage, type StoredImage } from "./images.js";
+import type { StoredFile } from "./storage.js";
+import {} from "@quark-fw/plugin-uploads/src/global.js";
+
+export const handleUpload = async (req: Request, res: Response) => {
+	const uploads = quark.uploads;
+	// по умолчанию загрузка только для залогиненных: файлы стоят денег и
+	// места; приложение сужает правило через quark.uploads.authorize
+	const allowed = uploads.authorize
+		? await uploads.authorize(req)
+		: !!(req as { user?: unknown }).user;
+	if (!allowed) {
+		res.status(403).json({ error: "Загрузка запрещена" });
+		return;
+	}
+
+	const contentType = req.headers["content-type"] ?? "";
+	if (!contentType.includes("multipart/form-data")) {
+		res.status(400).json({ error: "Ожидается multipart/form-data" });
+		return;
+	}
+
+	const parser = busboy({
+		headers: req.headers,
+		limits: { fileSize: uploads.maxFileSize, files: 20 },
+		// браузеры шлют имя файла в UTF-8, а busboy по умолчанию читает его
+		// как latin1 — кириллица превращалась в «Ð¤Ð¾Ñ‚Ð¾»
+		defParamCharset: "utf8",
+	});
+
+	const saved: (StoredFile | StoredImage)[] = [];
+	const pending: Promise<void>[] = [];
+	let tooLarge = false;
+	let failure: unknown;
+
+	parser.on("file", (_field, stream, info) => {
+		if (tooLarge) {
+			stream.resume();
+			return;
+		}
+		stream.on("limit", () => {
+			tooLarge = true;
+			stream.resume();
+		});
+
+		const mimeType = info.mimeType || "application/octet-stream";
+		const originalName = info.filename ?? "file";
+		const key = uploads.keyFor
+			? uploads.keyFor({ mimeType, originalName })
+			: `${new Date().toISOString().slice(0, 7)}/${crypto.randomUUID()}${safeExtension(originalName)}`;
+
+		// Картинка с вариантами: файл буферизуется — размеры и превью считаются
+		// из целого; остальное стримится в хранилище как раньше.
+		const task =
+			uploads.variants && isImageMime(mimeType)
+				? (async () => {
+						const chunks: Buffer[] = [];
+						for await (const chunk of stream)
+							chunks.push(chunk as Buffer);
+						if (tooLarge) return;
+						saved.push(
+							await saveImage(uploads.storage, {
+								key,
+								body: Buffer.concat(chunks),
+								mimeType,
+								originalName,
+								variants: uploads.variants,
+							}),
+						);
+					})()
+				: uploads.storage
+						.save({ key, stream, mimeType, originalName })
+						.then((file) => {
+							saved.push(file);
+						});
+
+		pending.push(
+			task.catch((e) => {
+				failure = e;
+			}),
+		);
+	});
+
+	// Ответ ровно один: error и close у busboy могут прийти оба, а без
+	// обработчика error оборванный клиентом multipart роняет процесс.
+	let finished = false;
+	const finish = async (parseError?: unknown) => {
+		if (finished) return;
+		finished = true;
+		try {
+			await Promise.all(pending);
+
+			if (parseError || tooLarge) {
+				await Promise.all(
+					saved.map((f) => uploads.storage.delete(f.key)),
+				);
+			}
+			if (parseError) {
+				res.status(400).json({
+					error: "Некорректный multipart-запрос",
+				});
+				return;
+			}
+			if (tooLarge) {
+				res.status(413).json({
+					error: `Файл больше ${uploads.maxFileSize} байт`,
+				});
+				return;
+			}
+			if (failure) {
+				console.error("[uploads]", failure);
+				res.status(500).json({ error: "Не удалось сохранить файл" });
+				return;
+			}
+			// приложение может заменить ответ своей записью (например строкой
+			// таблицы Image) — клиент получает то, что вернул onSaved
+			const files = uploads.onSaved
+				? await Promise.all(saved.map((f) => uploads.onSaved!(f)))
+				: saved;
+			res.json({ files });
+		} catch (e) {
+			// сбой удаления хранилища — не необработанный reject в close
+			console.error("[uploads]", e);
+			if (!res.headersSent) {
+				res.status(500).json({ error: "Не удалось сохранить файл" });
+			}
+		}
+	};
+
+	parser.on("error", (e) => {
+		req.unpipe(parser);
+		req.resume();
+		void finish(e);
+	});
+	parser.on("close", () => void finish());
+
+	// Обрыв соединения pipe парсеру не передаёт: поток текущего файла ждал бы
+	// данных вечно — save() висит, а у локального диска открыт дескриптор и
+	// лежит недописанный файл. Уничтожаем парсер — он закрывает поток файла.
+	req.on("close", () => {
+		if (!req.complete) parser.destroy(new Error("Request aborted"));
+	});
+	req.pipe(parser);
+};

package/src/helpers.ts

@@ -0,0 +1,67 @@
+// Хелперы uploads-плагина: выбор хранилища и лимиты. Без quark — модуль
+// пригоден для скриптов приложений, работающих отдельным процессом.
+import type { ServerResponse } from "node:http";
+import path from "node:path";
+import {
+	createLocalStorage,
+	createS3Storage,
+	type UploadStorage,
+} from "./storage.js";
+
+export const MAX_FILE_SIZE =
+	Number(process.env.UPLOAD_MAX_SIZE) || 10 * 1024 * 1024;
+export const uploadsDir = path.join(process.cwd(), "uploads");
+
+/**
+ * Хранилище из окружения: UPLOAD_DRIVER=s3 → UPLOAD_S3_BUCKET, UPLOAD_S3_REGION,
+ * UPLOAD_S3_ENDPOINT, UPLOAD_S3_ACCESS_KEY, UPLOAD_S3_SECRET_KEY,
+ * UPLOAD_S3_PUBLIC_URL, UPLOAD_S3_ACL; иначе локальный диск uploads/.
+ */
+export function createStorage(): UploadStorage {
+	if (process.env.UPLOAD_DRIVER === "s3") {
+		return createS3Storage({
+			bucket: process.env.UPLOAD_S3_BUCKET!,
+			region: process.env.UPLOAD_S3_REGION,
+			endpoint: process.env.UPLOAD_S3_ENDPOINT,
+			accessKeyId: process.env.UPLOAD_S3_ACCESS_KEY!,
+			secretAccessKey: process.env.UPLOAD_S3_SECRET_KEY!,
+			publicBaseUrl: process.env.UPLOAD_S3_PUBLIC_URL,
+			acl: process.env.UPLOAD_S3_ACL,
+		});
+	}
+	return createLocalStorage({ dir: uploadsDir });
+}
+
+// расширение берём из имени файла, но чистим — имя приходит от клиента
+export const safeExtension = (name: string) => {
+	const ext = path.extname(name).toLowerCase();
+	return /^\.[a-z0-9]{1,8}$/.test(ext) ? ext : "";
+};
+
+// Типы, которые браузер безопасно показывает inline. html/svg/xml и прочее,
+// отданное с домена приложения, исполнилось бы как его страница (stored
+// XSS через загрузку), поэтому всё вне списка отдаётся только скачиванием.
+const INLINE_TYPES: Record<string, string> = {
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".gif": "image/gif",
+	".webp": "image/webp",
+	".avif": "image/avif",
+	".pdf": "application/pdf",
+};
+
+/**
+ * MIME для inline-отдачи по расширению ключа или undefined — тогда файл
+ * только скачивается. Тип берётся из расширения, а не из присланного
+ * клиентом mimeType: тот подделывается («картинка» с text/html).
+ */
+export const inlineType = (key: string): string | undefined =>
+	INLINE_TYPES[path.extname(key).toLowerCase()];
+
+/** заголовки отдачи локального файла (setHeaders у express.static) */
+export const setUploadHeaders = (res: ServerResponse, filePath: string) => {
+	res.setHeader("X-Content-Type-Options", "nosniff");
+	if (!inlineType(filePath))
+		res.setHeader("Content-Disposition", "attachment");
+};

package/src/images.ts

@@ -0,0 +1,170 @@
+// Варианты изображений (превью) через sharp. Модуль без side-effects и без
+// quark: его используют и HTTP-обработчик плагина, и скрипты приложений
+// (парсеры, миграции), работающие отдельным процессом.
+import { Readable } from "node:stream";
+import type { StoredFile, UploadStorage } from "./storage.js";
+
+export type ImageFormat = "webp" | "jpeg" | "avif" | "png";
+
+export type VariantSpec = {
+	/** ширина, высота подбирается по пропорции; картинка не растягивается */
+	width: number;
+	/** формат (по умолчанию webp) */
+	format?: ImageFormat;
+	quality?: number;
+};
+
+export type VariantsConfig = Record<string, VariantSpec>;
+
+export type ProcessedVariant = {
+	name: string;
+	buffer: Buffer;
+	mimeType: string;
+	width: number;
+	height: number;
+	/** расширение файла варианта, например "webp" */
+	ext: string;
+};
+
+export type ProcessedImage = {
+	width: number;
+	height: number;
+	variants: ProcessedVariant[];
+};
+
+export type StoredImage = StoredFile & {
+	width: number | null;
+	height: number | null;
+	/** сохранённые варианты: имя → файл */
+	variants: Record<string, StoredFile>;
+};
+
+const MIME: Record<ImageFormat, string> = {
+	webp: "image/webp",
+	jpeg: "image/jpeg",
+	avif: "image/avif",
+	png: "image/png",
+};
+
+export const isImageMime = (mimeType: string) =>
+	/^image\/(png|jpe?g|gif|webp|avif|heic|heif|tiff)$/i.test(mimeType);
+
+/** Ключ варианта рядом с оригиналом: img/<id> → img/<id>/<name>.<ext> */
+export const variantKey = (baseKey: string, name: string, ext: string) =>
+	`${baseKey}/${name}.${ext}`;
+
+/**
+ * Разбирает UPLOAD_VARIANTS: JSON `{"400":{"width":400},"800":{"width":800,"format":"webp"}}`
+ * или короткая форма "400,800" (webp). Пусто — вариантов нет.
+ */
+export function parseVariants(
+	raw: string | undefined,
+): VariantsConfig | undefined {
+	if (!raw?.trim()) return undefined;
+	if (raw.trim().startsWith("{")) return JSON.parse(raw) as VariantsConfig;
+	const config: VariantsConfig = {};
+	for (const part of raw.split(",")) {
+		const width = Number(part.trim());
+		if (Number.isInteger(width) && width > 0)
+			config[String(width)] = { width, format: "webp" };
+	}
+	return Object.keys(config).length ? config : undefined;
+}
+
+// sharp — нативный модуль; грузим лениво, чтобы приложения без картинок
+// его не инициализировали
+const loadSharp = async () => (await import("sharp")).default;
+
+/** Размеры оригинала и варианты заданных ширин. */
+export async function processImage(
+	buffer: Buffer,
+	variants: VariantsConfig,
+): Promise<ProcessedImage> {
+	const sharp = await loadSharp();
+	const source = sharp(buffer, { failOn: "none" }).rotate(); // EXIF-поворот → реальная ориентация
+	const meta = await source.metadata();
+	const width = meta.width ?? 0;
+	const height = meta.height ?? 0;
+	const out: ProcessedVariant[] = [];
+	for (const [name, spec] of Object.entries(variants)) {
+		const format = spec.format ?? "webp";
+		// по одному варианту за раз: несколько параллельных пайплайнов на
+		// больших оригиналах выедают память в контейнере
+		const { data, info } = await source
+			.clone()
+			.resize({ width: spec.width, withoutEnlargement: true })
+			.toFormat(format, { quality: spec.quality ?? 80 })
+			.toBuffer({ resolveWithObject: true });
+		out.push({
+			name,
+			buffer: data,
+			mimeType: MIME[format],
+			width: info.width,
+			height: info.height,
+			ext: format,
+		});
+	}
+	return { width, height, variants: out };
+}
+
+/**
+ * Сохраняет оригинал под `key` и варианты под `key/<name>.<ext>`; возвращает
+ * оригинал с размерами и картой вариантов. Не картинка или без вариантов —
+ * сохраняется только оригинал.
+ */
+export async function saveImage(
+	storage: UploadStorage,
+	{
+		key,
+		body,
+		mimeType,
+		originalName,
+		variants,
+	}: {
+		key: string;
+		body: Buffer;
+		mimeType: string;
+		originalName: string;
+		variants?: VariantsConfig;
+	},
+): Promise<StoredImage> {
+	const original = await storage.save({
+		key,
+		stream: Readable.from(body),
+		mimeType,
+		originalName,
+	});
+	if (!variants || !isImageMime(mimeType)) {
+		return { ...original, width: null, height: null, variants: {} };
+	}
+	const processed = await processImage(body, variants);
+	const saved: Record<string, StoredFile> = {};
+	for (const variant of processed.variants) {
+		saved[variant.name] = await storage.save({
+			key: variantKey(key, variant.name, variant.ext),
+			stream: Readable.from(variant.buffer),
+			mimeType: variant.mimeType,
+			originalName: `${originalName}.${variant.name}.${variant.ext}`,
+		});
+	}
+	return {
+		...original,
+		width: processed.width,
+		height: processed.height,
+		variants: saved,
+	};
+}
+
+/** Удаляет оригинал и все варианты из конфигурации. */
+export async function deleteImage(
+	storage: UploadStorage,
+	key: string,
+	variants?: VariantsConfig,
+): Promise<void> {
+	await storage.delete(key);
+	for (const [name, spec] of Object.entries(variants ?? {})) {
+		await storage
+			.delete(variantKey(key, name, spec.format ?? "webp"))
+			.catch(() => {});
+	}
+}

package/src/index.ts

@@ -0,0 +1,68 @@
+import { QuarkPlugin } from "@quark-fw/plugin";
+import express from "express";
+import { registerHttpMiddleware } from "@quark-fw/plugin/http.js";
+import {
+	createStorage,
+	MAX_FILE_SIZE,
+	setUploadHeaders,
+	uploadsDir,
+} from "./helpers.js";
+import { handleUpload } from "./handleUpload.js";
+import { parseVariants } from "./images.js";
+import { createImageServer } from "./serve.js";
+import {} from "@quark-fw/plugin-uploads/src/global.js";
+
+export { createLocalStorage, createS3Storage } from "./storage.js";
+export type { StoredFile, UploadStorage } from "./storage.js";
+export { createStorage } from "./helpers.js";
+export {
+	deleteImage,
+	isImageMime,
+	parseVariants,
+	processImage,
+	saveImage,
+	variantKey,
+} from "./images.js";
+export type {
+	ProcessedImage,
+	StoredImage,
+	VariantSpec,
+	VariantsConfig,
+} from "./images.js";
+export { createImageServer } from "./serve.js";
+
+// Плагин: quark.uploads (хранилище, лимиты, варианты) + маршруты
+// POST /api/files (загрузка), GET /img/<id>/<variant> (раздача превью с
+// неизменяемым кэшем), /uploads (статика локального диска).
+// Приложение дополняет: authorize, keyFor, onSaved — до onInit.
+await quark.registerPlugin({
+	name: "uploads",
+	extend(quark) {
+		quark.uploads = {
+			storage: createStorage(),
+			maxFileSize: MAX_FILE_SIZE,
+			variants: parseVariants(process.env.UPLOAD_VARIANTS),
+			imageKeyPrefix: process.env.UPLOAD_IMAGE_PREFIX ?? "img/",
+		};
+	},
+	onInit(quark) {
+		registerHttpMiddleware("/api/files", handleUpload);
+		registerHttpMiddleware(
+			"/img",
+			createImageServer({
+				storage: quark.uploads.storage,
+				keyPrefix: quark.uploads.imageKeyPrefix,
+			}),
+		);
+		// локальные файлы отдаём статикой (для s3 URL ведёт напрямую в бакет)
+		if (quark.uploads.storage.name === "local") {
+			registerHttpMiddleware(
+				"/uploads",
+				express.static(uploadsDir, {
+					index: false,
+					setHeaders: setUploadHeaders,
+				}),
+			);
+		}
+	},
+} satisfies QuarkPlugin);

package/src/serve.ts

@@ -0,0 +1,60 @@
+import type { Request, Response } from "express";
+import type { UploadStorage } from "./storage.js";
+import { inlineType } from "./helpers.js";
+
+/**
+ * Раздача вариантов изображений с домена приложения: GET /img/<id>/<name>.<ext>
+ * → ключ `<prefix><id>/<name>.<ext>` из хранилища. Хеш в адресе не нужен —
+ * вариант неизменяем, поэтому кэшируется навсегда (и браузером, и CDN перед
+ * приложением). Оригиналы без расширения этим маршрутом не отдаются: их тип
+ * неизвестен, а отдавать с домена приложения что попало нельзя.
+ */
+export function createImageServer({
+	storage,
+	keyPrefix,
+}: {
+	storage: UploadStorage;
+	keyPrefix: string;
+}) {
+	return async (req: Request, res: Response) => {
+		if (req.method !== "GET" && req.method !== "HEAD") {
+			res.status(405).end();
+			return;
+		}
+		// /<id>/<variant>.<ext>; id и имя варианта — только безопасные символы
+		const match =
+			/^\/([A-Za-z0-9_-]+)\/([A-Za-z0-9_-]+\.[a-z0-9]{1,8})$/.exec(
+				req.path,
+			);
+		if (!match) {
+			res.status(404).end();
+			return;
+		}
+		const key = `${keyPrefix}${match[1]}/${match[2]}`;
+		const mimeType = inlineType(key);
+		if (!mimeType) {
+			res.status(404).end();
+			return;
+		}
+		let stream;
+		try {
+			stream = await storage.read(key);
+		} catch {
+			res.status(404).end();
+			return;
+		}
+		res.setHeader("Content-Type", mimeType);
+		res.setHeader("Cache-Control", "public, max-age=31536000, immutable");
+		res.setHeader("X-Content-Type-Options", "nosniff");
+		if (req.method === "HEAD") {
+			stream.destroy();
+			res.end();
+			return;
+		}
+		stream.on("error", () => {
+			if (!res.headersSent) res.status(404);
+			res.end();
+		});
+		stream.pipe(res);
+	};
+}

package/src/storage.ts

@@ -0,0 +1,193 @@
+import fs from "node:fs";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+// цикл с helpers.ts безопасен: inlineType вызывается только внутри save
+import { inlineType } from "./helpers.js";
+
+export type StoredFile = {
+	/** ключ в хранилище (например "2026/08/<uuid>.png") */
+	key: string;
+	/** публичный URL файла */
+	url: string;
+	size: number;
+	mimeType: string;
+	originalName: string;
+};
+
+export interface UploadStorage {
+	readonly name: string;
+	save(args: {
+		key: string;
+		stream: Readable;
+		mimeType: string;
+		originalName: string;
+	}): Promise<StoredFile>;
+	delete(key: string): Promise<void>;
+	/** поток содержимого по ключу; отсутствующий ключ — reject */
+	read(key: string): Promise<Readable>;
+}
+
+/** Локальный диск: файлы кладутся в uploads/ и отдаются как /uploads/<key>. */
+export function createLocalStorage({
+	dir = path.join(process.cwd(), "uploads"),
+	publicPath = "/uploads",
+}: { dir?: string; publicPath?: string } = {}): UploadStorage {
+	return {
+		name: "local",
+		async save({ key, stream, mimeType, originalName }) {
+			const target = path.join(dir, key);
+			fs.mkdirSync(path.dirname(target), { recursive: true });
+			try {
+				await pipeline(stream, fs.createWriteStream(target));
+			} catch (error) {
+				// недописанный файл (обрыв клиента, лимит) никому не
+				// принадлежит — без удаления он копится на диске
+				fs.rmSync(target, { force: true });
+				throw error;
+			}
+			return {
+				key,
+				url: `${publicPath}/${key.replace(/\\/g, "/")}`,
+				size: fs.statSync(target).size,
+				mimeType,
+				originalName,
+			};
+		},
+		async delete(key) {
+			fs.rmSync(path.join(dir, key), { force: true });
+		},
+		async read(key) {
+			const target = path.join(dir, key);
+			// существование проверяем заранее: ошибка открытия потока приходила
+			// бы асинхронно уже после начала ответа
+			await fs.promises.access(target, fs.constants.R_OK);
+			return fs.createReadStream(target);
+		},
+	};
+}
+
+/**
+ * S3-совместимое хранилище (AWS, Yandex Object Storage, Cloudflare R2, MinIO).
+ * SDK импортируется динамически, чтобы пакет не тянул aws-зависимости, когда
+ * драйвер не используется.
+ */
+export function createS3Storage(config: {
+	bucket: string;
+	region?: string;
+	endpoint?: string;
+	accessKeyId: string;
+	secretAccessKey: string;
+	publicBaseUrl?: string;
+	/** например public-read — для бакетов, которые читают напрямую, минуя приложение */
+	acl?: string;
+}): UploadStorage {
+	/*
+	 * @aws-sdk/client-s3 — ОПЦИОНАЛЬНАЯ зависимость: её типов может не быть на
+	 * этапе проверки, поэтому здесь описано ровно то, чем пользуется этот
+	 * файл, а не полный интерфейс SDK.
+	 */
+	type S3Command = object;
+	type S3Client = { send(command: S3Command): Promise<unknown> };
+	type S3Sdk = {
+		S3Client: new (config: Record<string, unknown>) => S3Client;
+		PutObjectCommand: new (input: Record<string, unknown>) => S3Command;
+		DeleteObjectCommand: new (input: Record<string, unknown>) => S3Command;
+		GetObjectCommand: new (input: Record<string, unknown>) => S3Command;
+	};
+
+	let sdkPromise: Promise<S3Sdk> | undefined;
+	let clientPromise: Promise<S3Client> | undefined;
+
+	// спецификатор в переменной: TypeScript не резолвит модуль на этапе
+	// проверки, поэтому @aws-sdk/client-s3 остаётся ОПЦИОНАЛЬНОЙ зависимостью
+	const sdkName = "@aws-sdk/client-s3";
+
+	const getSdk = async () => {
+		sdkPromise ??= import(sdkName).catch(() => {
+			throw new Error(
+				"[uploads] драйвер s3 требует пакет @aws-sdk/client-s3 (npm i @aws-sdk/client-s3)",
+			);
+		});
+		return sdkPromise;
+	};
+
+	const getClient = async () => {
+		clientPromise ??= (async () => {
+			const sdk = await getSdk();
+			return new sdk.S3Client({
+				region: config.region ?? "us-east-1",
+				endpoint: config.endpoint,
+				forcePathStyle: !!config.endpoint,
+				credentials: {
+					accessKeyId: config.accessKeyId,
+					secretAccessKey: config.secretAccessKey,
+				},
+			});
+		})();
+		return clientPromise;
+	};
+
+	const base =
+		config.publicBaseUrl ??
+		(config.endpoint
+			? `${config.endpoint.replace(/\/$/, "")}/${config.bucket}`
+			: `https://${config.bucket}.s3.amazonaws.com`);
+
+	return {
+		name: "s3",
+		async save({ key, stream, mimeType, originalName }) {
+			const client = await getClient();
+			const { PutObjectCommand } = await getSdk();
+			const chunks: Buffer[] = [];
+			for await (const chunk of stream) chunks.push(chunk as Buffer);
+			const body = Buffer.concat(chunks);
+
+			// бакет может стоять за доменом приложения (publicBaseUrl), поэтому
+			// правила отдачи те же, что у локального диска. Ключ без расширения
+			// (img/<id>) доверяет присланному типу, если он картиночный.
+			const inline =
+				inlineType(key) ??
+				(/^image\/(png|jpeg|gif|webp|avif)$/.test(mimeType)
+					? mimeType
+					: undefined);
+			await client.send(
+				new PutObjectCommand({
+					Bucket: config.bucket,
+					Key: key,
+					Body: body,
+					ContentType: inline ?? "application/octet-stream",
+					...(inline ? {} : { ContentDisposition: "attachment" }),
+					...(config.acl ? { ACL: config.acl } : {}),
+				}),
+			);
+
+			return {
+				key,
+				url: `${base}/${key}`,
+				size: body.length,
+				mimeType,
+				originalName,
+			};
+		},
+		async delete(key) {
+			const client = await getClient();
+			const { DeleteObjectCommand } = await getSdk();
+			await client.send(
+				new DeleteObjectCommand({ Bucket: config.bucket, Key: key }),
+			);
+		},
+		async read(key) {
+			const client = await getClient();
+			const { GetObjectCommand } = await getSdk();
+			const result = (await client.send(
+				new GetObjectCommand({ Bucket: config.bucket, Key: key }),
+			)) as {
+				Body?: Readable;
+			};
+			if (!result.Body)
+				throw new Error(`[uploads] empty body for ${key}`);
+			return result.Body;
+		},
+	};
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.