@jskit-ai/uploads-runtime 0.1.1

package/package.descriptor.mjs

@@ -0,0 +1,89 @@
+export default Object.freeze({
+  packageVersion: 1,
+  packageId: "@jskit-ai/uploads-runtime",
+  version: "0.1.1",
+  kind: "runtime",
+  description: "Reusable upload runtime primitives for multipart parsing, policy validation, and blob storage.",
+  dependsOn: [
+    "@jskit-ai/kernel"
+  ],
+  capabilities: {
+    provides: [
+      "runtime.uploads"
+    ],
+    requires: []
+  },
+  runtime: {
+    server: {
+      providerEntrypoint: "src/server/providers/UploadsRuntimeServiceProvider.js",
+      providers: [
+        {
+          entrypoint: "src/server/providers/UploadsRuntimeServiceProvider.js",
+          export: "UploadsRuntimeServiceProvider"
+        }
+      ]
+    },
+    client: {
+      providers: []
+    }
+  },
+  metadata: {
+    apiSummary: {
+      surfaces: [
+        {
+          subpath: "./server/providers/UploadsRuntimeServiceProvider",
+          summary: "Exports uploads runtime server provider."
+        },
+        {
+          subpath: "./server/multipart/registerMultipartSupport",
+          summary: "Exports Fastify multipart registration helper."
+        },
+        {
+          subpath: "./server/multipart/readMultipartFiles",
+          summary: "Exports normalized multipart file parsing helpers."
+        },
+        {
+          subpath: "./server/multipart/readSingleMultipartFile",
+          summary: "Exports a convenience helper for single-file multipart uploads."
+        },
+        {
+          subpath: "./server/policy/uploadPolicy",
+          summary: "Exports upload policy normalization and stream validation helpers."
+        },
+        {
+          subpath: "./server/storage/createUploadStorageService",
+          summary: "Exports raw upload storage helpers backed by jskit.storage."
+        },
+        {
+          subpath: "./shared",
+          summary: "Exports shared upload policy defaults and normalization helpers."
+        },
+        {
+          subpath: "./client",
+          summary: "Exports no client runtime API today (reserved client entrypoint)."
+        }
+      ],
+      containerTokens: {
+        server: [
+          "runtime.uploads"
+        ],
+        client: []
+      }
+    }
+  },
+  mutations: {
+    dependencies: {
+      runtime: {
+        "@fastify/multipart": "^9.4.0",
+        "@jskit-ai/kernel": "0.1.23"
+      },
+      dev: {}
+    },
+    packageJson: {
+      scripts: {}
+    },
+    procfile: {},
+    files: [],
+    text: []
+  }
+});

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@jskit-ai/uploads-runtime",
+  "version": "0.1.1",
+  "type": "module",
+  "scripts": {
+    "test": "node --test"
+  },
+  "exports": {
+    "./client": "./src/client/index.js",
+    "./shared": "./src/shared/index.js",
+    "./server/providers/UploadsRuntimeServiceProvider": "./src/server/providers/UploadsRuntimeServiceProvider.js",
+    "./server/multipart/registerMultipartSupport": "./src/server/multipart/registerMultipartSupport.js",
+    "./server/multipart/readMultipartFiles": "./src/server/multipart/readMultipartFiles.js",
+    "./server/multipart/readSingleMultipartFile": "./src/server/multipart/readSingleMultipartFile.js",
+    "./server/policy/uploadPolicy": "./src/server/policy/uploadPolicy.js",
+    "./server/storage/createUploadStorageService": "./src/server/storage/createUploadStorageService.js"
+  },
+  "dependencies": {
+    "@fastify/multipart": "^9.4.0",
+    "@jskit-ai/kernel": "0.1.23"
+  }
+}

package/src/client/index.js

@@ -0,0 +1 @@
+export {};

package/src/server/multipart/readMultipartFiles.js

@@ -0,0 +1,111 @@
+import { createUploadFieldError } from "../policy/uploadPolicy.js";
+
+function normalizeFieldName(value) {
+  return String(value || "").trim();
+}
+
+function appendField(fields, fieldName, value) {
+  const normalizedFieldName = normalizeFieldName(fieldName);
+  if (!normalizedFieldName) {
+    return;
+  }
+
+  const normalizedValue = value == null ? "" : String(value);
+  if (!Object.hasOwn(fields, normalizedFieldName)) {
+    fields[normalizedFieldName] = {
+      value: normalizedValue,
+      values: [normalizedValue]
+    };
+    return;
+  }
+
+  fields[normalizedFieldName].values.push(normalizedValue);
+}
+
+function toAllowedFieldSet(fieldNames = []) {
+  const normalizedFieldNames = Array.isArray(fieldNames)
+    ? fieldNames.map(normalizeFieldName).filter(Boolean)
+    : [];
+  return normalizedFieldNames.length > 0 ? new Set(normalizedFieldNames) : null;
+}
+
+async function readMultipartFiles(
+  request,
+  {
+    fieldNames = [],
+    maxFiles = Number.POSITIVE_INFINITY,
+    required = false,
+    fieldErrorKey = "",
+    label = "File"
+  } = {}
+) {
+  if (!request || typeof request.parts !== "function") {
+    throw new TypeError("readMultipartFiles requires a request with parts().");
+  }
+
+  const allowedFieldNames = toAllowedFieldSet(fieldNames);
+  const normalizedFieldErrorKey =
+    normalizeFieldName(fieldErrorKey) ||
+    (allowedFieldNames && allowedFieldNames.size === 1 ? [...allowedFieldNames][0] : "file");
+  const normalizedMaxFiles =
+    Number.isInteger(maxFiles) && maxFiles > 0 ? maxFiles : Number.POSITIVE_INFINITY;
+
+  const fields = {};
+  const files = [];
+
+  for await (const part of request.parts()) {
+    if (part?.type === "field") {
+      appendField(fields, part.fieldname, part.value);
+      continue;
+    }
+
+    if (part?.type !== "file") {
+      continue;
+    }
+
+    const fieldName = normalizeFieldName(part.fieldname);
+    if (allowedFieldNames && !allowedFieldNames.has(fieldName)) {
+      if (part.file && typeof part.file.resume === "function") {
+        part.file.resume();
+      }
+      throw createUploadFieldError(
+        normalizedFieldErrorKey,
+        `${label} field "${fieldName || "unknown"}" is not allowed.`
+      );
+    }
+
+    if (files.length >= normalizedMaxFiles) {
+      if (part.file && typeof part.file.resume === "function") {
+        part.file.resume();
+      }
+      throw createUploadFieldError(
+        normalizedFieldErrorKey,
+        normalizedMaxFiles === 1
+          ? `${label} upload allows only one file.`
+          : `${label} upload allows at most ${normalizedMaxFiles} files.`
+      );
+    }
+
+    files.push(
+      Object.freeze({
+        fieldName,
+        fileName: String(part.filename || "").trim(),
+        mimeType: String(part.mimetype || "").trim().toLowerCase(),
+        encoding: String(part.encoding || "").trim().toLowerCase(),
+        stream: part.file,
+        fields
+      })
+    );
+  }
+
+  if (required && files.length === 0) {
+    throw createUploadFieldError(normalizedFieldErrorKey, `${label} file is required.`);
+  }
+
+  return Object.freeze({
+    fields: Object.freeze(fields),
+    files: Object.freeze(files)
+  });
+}
+
+export { readMultipartFiles };

package/src/server/multipart/readSingleMultipartFile.js

@@ -0,0 +1,11 @@
+import { readMultipartFiles } from "./readMultipartFiles.js";
+
+async function readSingleMultipartFile(request, options = {}) {
+  const result = await readMultipartFiles(request, {
+    ...options,
+    maxFiles: 1
+  });
+  return result.files[0] || null;
+}
+
+export { readSingleMultipartFile };

package/src/server/multipart/registerMultipartSupport.js

@@ -0,0 +1,40 @@
+import fastifyMultipart from "@fastify/multipart";
+
+async function registerMultipartSupport(app) {
+  if (!app || typeof app.has !== "function" || typeof app.make !== "function") {
+    throw new Error("registerMultipartSupport requires application has()/make().");
+  }
+
+  if (!app.has("jskit.fastify")) {
+    return;
+  }
+
+  const fastify = app.make("jskit.fastify");
+  if (!fastify || typeof fastify.register !== "function") {
+    throw new Error("registerMultipartSupport requires Fastify register().");
+  }
+
+  if (fastify["jskit.uploads-runtime.multipart.support"] === true) {
+    return;
+  }
+
+  if (typeof fastify.hasContentTypeParser === "function" && fastify.hasContentTypeParser("multipart")) {
+    Object.defineProperty(fastify, "jskit.uploads-runtime.multipart.support", {
+      value: true,
+      configurable: false,
+      enumerable: false,
+      writable: false
+    });
+    return;
+  }
+
+  await fastify.register(fastifyMultipart);
+  Object.defineProperty(fastify, "jskit.uploads-runtime.multipart.support", {
+    value: true,
+    configurable: false,
+    enumerable: false,
+    writable: false
+  });
+}
+
+export { registerMultipartSupport };

package/src/server/policy/uploadPolicy.js

@@ -0,0 +1,76 @@
+import { createValidationError } from "@jskit-ai/kernel/server/runtime/errors";
+import {
+  DEFAULT_IMAGE_UPLOAD_POLICY,
+  normalizeMimeType,
+  normalizeUploadPolicy
+} from "../../shared/uploadPolicy.js";
+
+function createUploadFieldError(fieldName, message) {
+  const normalizedFieldName = String(fieldName || "").trim() || "file";
+  return createValidationError({
+    [normalizedFieldName]: String(message || "").trim() || "Upload is invalid."
+  });
+}
+
+async function readUploadBuffer(
+  stream,
+  {
+    maxBytes = DEFAULT_IMAGE_UPLOAD_POLICY.maxUploadBytes,
+    fieldName = "file",
+    label = "File"
+  } = {}
+) {
+  if (!stream || typeof stream.on !== "function") {
+    throw new TypeError("Upload stream is required.");
+  }
+
+  const chunks = [];
+  let total = 0;
+
+  for await (const chunk of stream) {
+    const bufferChunk = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    total += bufferChunk.length;
+
+    if (total > maxBytes) {
+      throw createUploadFieldError(
+        fieldName,
+        `${label} file is too large. Maximum allowed size is ${Math.floor(maxBytes / (1024 * 1024))}MB.`
+      );
+    }
+
+    chunks.push(bufferChunk);
+  }
+
+  if (chunks.length === 0) {
+    throw createUploadFieldError(fieldName, `${label} file is empty.`);
+  }
+
+  return Buffer.concat(chunks);
+}
+
+function validateUploadMimeType(
+  mimeType,
+  policy = DEFAULT_IMAGE_UPLOAD_POLICY,
+  {
+    fieldName = "file",
+    label = "File"
+  } = {}
+) {
+  const normalizedMimeType = normalizeMimeType(mimeType);
+  const resolvedPolicy = normalizeUploadPolicy(policy);
+  if (resolvedPolicy.allowedMimeTypes.length > 0 && !resolvedPolicy.allowedMimeTypes.includes(normalizedMimeType)) {
+    throw createUploadFieldError(
+      fieldName,
+      `${label} must be one of: ${resolvedPolicy.allowedMimeTypes.join(", ")}.`
+    );
+  }
+
+  return normalizedMimeType;
+}
+
+export {
+  createUploadFieldError,
+  normalizeUploadPolicy,
+  readUploadBuffer,
+  validateUploadMimeType
+};

package/src/server/providers/UploadsRuntimeServiceProvider.js

@@ -0,0 +1,45 @@
+import { registerMultipartSupport } from "../multipart/registerMultipartSupport.js";
+import { readMultipartFiles } from "../multipart/readMultipartFiles.js";
+import { readSingleMultipartFile } from "../multipart/readSingleMultipartFile.js";
+import {
+  createUploadFieldError,
+  readUploadBuffer,
+  validateUploadMimeType
+} from "../policy/uploadPolicy.js";
+import {
+  createUploadStorageService,
+  detectCommonMimeTypeFromBuffer,
+  normalizeStorageKey
+} from "../storage/createUploadStorageService.js";
+
+const UPLOADS_RUNTIME_SERVER_API = Object.freeze({
+  registerMultipartSupport,
+  readMultipartFiles,
+  readSingleMultipartFile,
+  createUploadFieldError,
+  readUploadBuffer,
+  validateUploadMimeType,
+  createUploadStorageService,
+  detectCommonMimeTypeFromBuffer,
+  normalizeStorageKey
+});
+
+class UploadsRuntimeServiceProvider {
+  static id = "runtime.uploads";
+
+  static dependsOn = ["runtime.server"];
+
+  register(app) {
+    if (!app || typeof app.singleton !== "function") {
+      throw new Error("UploadsRuntimeServiceProvider requires application singleton().");
+    }
+
+    app.singleton("runtime.uploads", () => UPLOADS_RUNTIME_SERVER_API);
+  }
+
+  async boot(app) {
+    await registerMultipartSupport(app);
+  }
+}
+
+export { UploadsRuntimeServiceProvider };

package/src/server/storage/createUploadStorageService.js

@@ -0,0 +1,125 @@
+const MIME_TYPE_JPEG = "image/jpeg";
+const MIME_TYPE_PNG = "image/png";
+const MIME_TYPE_WEBP = "image/webp";
+const MIME_TYPE_FALLBACK = "application/octet-stream";
+
+function normalizeStorageKey(value) {
+  const normalized = String(value || "").trim();
+  if (!normalized) {
+    return "";
+  }
+  if (normalized.startsWith("/") || normalized.includes("..")) {
+    return "";
+  }
+  return normalized;
+}
+
+function detectCommonMimeTypeFromBuffer(buffer) {
+  if (!Buffer.isBuffer(buffer) || buffer.length < 4) {
+    return MIME_TYPE_FALLBACK;
+  }
+
+  if (
+    buffer.length >= 3 &&
+    buffer[0] === 0xff &&
+    buffer[1] === 0xd8 &&
+    buffer[2] === 0xff
+  ) {
+    return MIME_TYPE_JPEG;
+  }
+
+  if (
+    buffer.length >= 8 &&
+    buffer[0] === 0x89 &&
+    buffer[1] === 0x50 &&
+    buffer[2] === 0x4e &&
+    buffer[3] === 0x47 &&
+    buffer[4] === 0x0d &&
+    buffer[5] === 0x0a &&
+    buffer[6] === 0x1a &&
+    buffer[7] === 0x0a
+  ) {
+    return MIME_TYPE_PNG;
+  }
+
+  if (
+    buffer.length >= 12 &&
+    buffer[0] === 0x52 &&
+    buffer[1] === 0x49 &&
+    buffer[2] === 0x46 &&
+    buffer[3] === 0x46 &&
+    buffer[8] === 0x57 &&
+    buffer[9] === 0x45 &&
+    buffer[10] === 0x42 &&
+    buffer[11] === 0x50
+  ) {
+    return MIME_TYPE_WEBP;
+  }
+
+  return MIME_TYPE_FALLBACK;
+}
+
+function createUploadStorageService({ storage, mimeTypeDetector = detectCommonMimeTypeFromBuffer } = {}) {
+  if (!storage || typeof storage.getItemRaw !== "function" || typeof storage.setItemRaw !== "function") {
+    throw new TypeError("createUploadStorageService requires a storage binding with getItemRaw()/setItemRaw().");
+  }
+
+  async function saveFile({ storageKey, buffer }) {
+    const normalizedStorageKey = normalizeStorageKey(storageKey);
+    if (!normalizedStorageKey) {
+      throw new TypeError("Upload storage key is required.");
+    }
+    if (!Buffer.isBuffer(buffer)) {
+      throw new TypeError("Upload buffer must be a Buffer instance.");
+    }
+
+    await storage.setItemRaw(normalizedStorageKey, buffer);
+    return Object.freeze({
+      storageKey: normalizedStorageKey
+    });
+  }
+
+  async function readFile(storageKey) {
+    const normalizedStorageKey = normalizeStorageKey(storageKey);
+    if (!normalizedStorageKey) {
+      return null;
+    }
+
+    const value = await storage.getItemRaw(normalizedStorageKey);
+    if (value == null) {
+      return null;
+    }
+
+    const buffer = Buffer.isBuffer(value) ? value : Buffer.from(value);
+    return Object.freeze({
+      storageKey: normalizedStorageKey,
+      buffer,
+      mimeType: mimeTypeDetector(buffer)
+    });
+  }
+
+  async function deleteFile(storageKey) {
+    const normalizedStorageKey = normalizeStorageKey(storageKey);
+    if (!normalizedStorageKey || typeof storage.removeItem !== "function") {
+      return;
+    }
+
+    await storage.removeItem(normalizedStorageKey);
+  }
+
+  return Object.freeze({
+    saveFile,
+    readFile,
+    deleteFile
+  });
+}
+
+export {
+  MIME_TYPE_FALLBACK,
+  MIME_TYPE_JPEG,
+  MIME_TYPE_PNG,
+  MIME_TYPE_WEBP,
+  createUploadStorageService,
+  detectCommonMimeTypeFromBuffer,
+  normalizeStorageKey
+};

package/src/shared/imageUploadDefaults.js

@@ -0,0 +1,7 @@
+const DEFAULT_IMAGE_UPLOAD_ALLOWED_MIME_TYPES = Object.freeze(["image/jpeg", "image/png", "image/webp"]);
+const DEFAULT_IMAGE_UPLOAD_MAX_BYTES = 5 * 1024 * 1024;
+
+export {
+  DEFAULT_IMAGE_UPLOAD_ALLOWED_MIME_TYPES,
+  DEFAULT_IMAGE_UPLOAD_MAX_BYTES
+};

package/src/shared/index.js

@@ -0,0 +1,9 @@
+export {
+  DEFAULT_IMAGE_UPLOAD_ALLOWED_MIME_TYPES,
+  DEFAULT_IMAGE_UPLOAD_MAX_BYTES,
+  DEFAULT_IMAGE_UPLOAD_POLICY,
+  normalizeAllowedMimeTypes,
+  normalizeMaxUploadBytes,
+  normalizeMimeType,
+  normalizeUploadPolicy
+} from "./uploadPolicy.js";

package/src/shared/uploadPolicy.js

@@ -0,0 +1,60 @@
+import {
+  DEFAULT_IMAGE_UPLOAD_ALLOWED_MIME_TYPES,
+  DEFAULT_IMAGE_UPLOAD_MAX_BYTES
+} from "./imageUploadDefaults.js";
+
+function normalizeMimeType(value) {
+  return String(value || "").trim().toLowerCase();
+}
+
+function normalizeAllowedMimeTypes(values = [], fallback = []) {
+  const source = Array.isArray(values) ? values : [];
+  const normalized = source
+    .map(normalizeMimeType)
+    .filter((value, index, array) => value.length > 0 && array.indexOf(value) === index);
+
+  if (normalized.length > 0) {
+    return Object.freeze(normalized);
+  }
+
+  const fallbackValues = Array.isArray(fallback) ? fallback : [];
+  return Object.freeze(
+    fallbackValues
+      .map(normalizeMimeType)
+      .filter((value, index, array) => value.length > 0 && array.indexOf(value) === index)
+  );
+}
+
+function normalizeMaxUploadBytes(value, fallback = DEFAULT_IMAGE_UPLOAD_MAX_BYTES) {
+  const normalized = Number(value);
+  if (Number.isInteger(normalized) && normalized > 0) {
+    return normalized;
+  }
+
+  return Number.isInteger(fallback) && fallback > 0 ? fallback : DEFAULT_IMAGE_UPLOAD_MAX_BYTES;
+}
+
+function normalizeUploadPolicy(policy = {}, defaults = {}) {
+  const source = policy && typeof policy === "object" ? policy : {};
+  const fallback = defaults && typeof defaults === "object" ? defaults : {};
+
+  return Object.freeze({
+    allowedMimeTypes: normalizeAllowedMimeTypes(source.allowedMimeTypes, fallback.allowedMimeTypes),
+    maxUploadBytes: normalizeMaxUploadBytes(source.maxUploadBytes, fallback.maxUploadBytes)
+  });
+}
+
+const DEFAULT_IMAGE_UPLOAD_POLICY = Object.freeze({
+  allowedMimeTypes: DEFAULT_IMAGE_UPLOAD_ALLOWED_MIME_TYPES,
+  maxUploadBytes: DEFAULT_IMAGE_UPLOAD_MAX_BYTES
+});
+
+export {
+  DEFAULT_IMAGE_UPLOAD_ALLOWED_MIME_TYPES,
+  DEFAULT_IMAGE_UPLOAD_MAX_BYTES,
+  DEFAULT_IMAGE_UPLOAD_POLICY,
+  normalizeAllowedMimeTypes,
+  normalizeMaxUploadBytes,
+  normalizeMimeType,
+  normalizeUploadPolicy
+};

package/test/exportsContract.test.js

@@ -0,0 +1,32 @@
+import assert from "node:assert/strict";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { evaluatePackageExportsContract } from "../../../tooling/test-support/exportsContract.mjs";
+
+const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(TEST_DIRECTORY, "..", "..", "..");
+const PACKAGE_DIR = path.join(REPO_ROOT, "packages", "uploads-runtime");
+
+test("uploads-runtime exports are explicit and aligned with usage", () => {
+  const result = evaluatePackageExportsContract({
+    repoRoot: REPO_ROOT,
+    packageDir: PACKAGE_DIR,
+    packageId: "@jskit-ai/uploads-runtime",
+    requiredExports: [
+      "./client",
+      "./shared",
+      "./server/providers/UploadsRuntimeServiceProvider",
+      "./server/multipart/registerMultipartSupport",
+      "./server/multipart/readMultipartFiles",
+      "./server/multipart/readSingleMultipartFile",
+      "./server/policy/uploadPolicy",
+      "./server/storage/createUploadStorageService"
+    ]
+  });
+
+  assert.deepEqual(result.wildcardExports, []);
+  assert.deepEqual(result.missingRequiredExports, []);
+  assert.deepEqual(result.missingExports, []);
+  assert.deepEqual(result.staleExports, []);
+});

package/test/providerRuntime.test.js

@@ -0,0 +1,73 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { UploadsRuntimeServiceProvider } from "../src/server/providers/UploadsRuntimeServiceProvider.js";
+
+function createAppStub({ hasFastify = true, fastify = null } = {}) {
+  const singletons = new Map();
+  const singletonInstances = new Map();
+  const resolvedFastify =
+    fastify ||
+    {
+      register: async () => {},
+      hasContentTypeParser: () => false
+    };
+
+  return {
+    has(token) {
+      if (token === "jskit.fastify") {
+        return hasFastify;
+      }
+      return singletons.has(token) || singletonInstances.has(token);
+    },
+    singleton(token, factory) {
+      singletons.set(token, factory);
+    },
+    make(token) {
+      if (token === "jskit.fastify") {
+        return resolvedFastify;
+      }
+      if (singletonInstances.has(token)) {
+        return singletonInstances.get(token);
+      }
+      const factory = singletons.get(token);
+      if (!factory) {
+        throw new Error(`Unknown token ${String(token)}`);
+      }
+      const instance = factory(this);
+      singletonInstances.set(token, instance);
+      return instance;
+    }
+  };
+}
+
+test("UploadsRuntimeServiceProvider registers runtime uploads api", async () => {
+  const app = createAppStub();
+  const provider = new UploadsRuntimeServiceProvider();
+
+  provider.register(app);
+
+  assert.equal(app.has("runtime.uploads"), true);
+  const runtimeUploads = app.make("runtime.uploads");
+  assert.equal(typeof runtimeUploads.registerMultipartSupport, "function");
+  assert.equal(typeof runtimeUploads.readSingleMultipartFile, "function");
+  assert.equal(typeof runtimeUploads.createUploadStorageService, "function");
+});
+
+test("UploadsRuntimeServiceProvider boots multipart support once", async () => {
+  let registerCount = 0;
+  const app = createAppStub({
+    fastify: {
+      register: async () => {
+        registerCount += 1;
+      },
+      hasContentTypeParser: () => false
+    }
+  });
+
+  const provider = new UploadsRuntimeServiceProvider();
+  provider.register(app);
+  await provider.boot(app);
+  await provider.boot(app);
+
+  assert.equal(registerCount, 1);
+});

package/test/readMultipartFiles.test.js

@@ -0,0 +1,80 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Readable } from "node:stream";
+import { readMultipartFiles } from "../src/server/multipart/readMultipartFiles.js";
+import { readSingleMultipartFile } from "../src/server/multipart/readSingleMultipartFile.js";
+
+function createRequestStub(parts) {
+  return {
+    async *parts() {
+      for (const part of parts) {
+        yield part;
+      }
+    }
+  };
+}
+
+test("readMultipartFiles normalizes fields and files", async () => {
+  const request = createRequestStub([
+    { type: "field", fieldname: "uploadDimension", value: "256" },
+    {
+      type: "file",
+      fieldname: "avatar",
+      filename: "face.png",
+      mimetype: "image/png",
+      encoding: "7bit",
+      file: Readable.from([Buffer.from("png")])
+    }
+  ]);
+
+  const result = await readMultipartFiles(request, {
+    fieldNames: ["avatar"],
+    required: true,
+    label: "Avatar"
+  });
+
+  assert.equal(result.files.length, 1);
+  assert.equal(result.files[0].fieldName, "avatar");
+  assert.equal(result.files[0].fileName, "face.png");
+  assert.equal(result.files[0].mimeType, "image/png");
+  assert.equal(result.fields.uploadDimension.value, "256");
+});
+
+test("readSingleMultipartFile returns the first file and enforces maxFiles", async () => {
+  const request = createRequestStub([
+    {
+      type: "file",
+      fieldname: "avatar",
+      filename: "face.png",
+      mimetype: "image/png",
+      encoding: "7bit",
+      file: Readable.from([Buffer.from("png")])
+    }
+  ]);
+
+  const file = await readSingleMultipartFile(request, {
+    fieldNames: ["avatar"],
+    required: true,
+    label: "Avatar"
+  });
+
+  assert.equal(file?.fileName, "face.png");
+});
+
+test("readMultipartFiles rejects missing required files", async () => {
+  const request = createRequestStub([]);
+
+  await assert.rejects(
+    () =>
+      readMultipartFiles(request, {
+        fieldNames: ["avatar"],
+        required: true,
+        label: "Avatar"
+      }),
+    (error) => {
+      assert.equal(error?.message, "Validation failed.");
+      assert.equal(error?.details?.fieldErrors?.avatar, "Avatar file is required.");
+      return true;
+    }
+  );
+});

package/test/registerMultipartSupport.test.js

@@ -0,0 +1,63 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { registerMultipartSupport } from "../src/server/multipart/registerMultipartSupport.js";
+
+function createAppStub({ hasFastify = true, fastify = null } = {}) {
+  const resolvedFastify =
+    fastify ||
+    {
+      register: async () => {},
+      hasContentTypeParser: () => false
+    };
+
+  return {
+    has(token) {
+      if (token === "jskit.fastify") {
+        return hasFastify;
+      }
+      return false;
+    },
+    make(token) {
+      if (token === "jskit.fastify") {
+        return resolvedFastify;
+      }
+      return null;
+    }
+  };
+}
+
+test("registerMultipartSupport returns early when Fastify is not available", async () => {
+  const app = createAppStub({ hasFastify: false });
+  await assert.doesNotReject(async () => registerMultipartSupport(app));
+});
+
+test("registerMultipartSupport registers multipart parser only once", async () => {
+  let registerCount = 0;
+  const fastify = {
+    register: async () => {
+      registerCount += 1;
+    },
+    hasContentTypeParser: () => false
+  };
+  const app = createAppStub({ fastify });
+
+  await registerMultipartSupport(app);
+  await registerMultipartSupport(app);
+
+  assert.equal(registerCount, 1);
+});
+
+test("registerMultipartSupport skips registration when parser already exists", async () => {
+  let registerCount = 0;
+  const fastify = {
+    register: async () => {
+      registerCount += 1;
+    },
+    hasContentTypeParser: (contentType) => String(contentType || "").trim().toLowerCase() === "multipart"
+  };
+  const app = createAppStub({ fastify });
+
+  await registerMultipartSupport(app);
+
+  assert.equal(registerCount, 0);
+});

package/test/uploadPolicy.test.js

@@ -0,0 +1,67 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Readable } from "node:stream";
+import {
+  normalizeUploadPolicy,
+  readUploadBuffer,
+  validateUploadMimeType
+} from "../src/server/policy/uploadPolicy.js";
+
+test("normalizeUploadPolicy applies defaults and normalization", () => {
+  const policy = normalizeUploadPolicy(
+    {
+      allowedMimeTypes: [" IMAGE/PNG ", "image/png", "image/jpeg"],
+      maxUploadBytes: "123"
+    },
+    {
+      allowedMimeTypes: ["image/webp"],
+      maxUploadBytes: 50
+    }
+  );
+
+  assert.deepEqual(policy.allowedMimeTypes, ["image/png", "image/jpeg"]);
+  assert.equal(policy.maxUploadBytes, 123);
+});
+
+test("validateUploadMimeType rejects unsupported mime types", () => {
+  assert.throws(
+    () =>
+      validateUploadMimeType("application/pdf", {
+        allowedMimeTypes: ["image/png"]
+      }),
+    (error) => {
+      assert.equal(error?.message, "Validation failed.");
+      assert.equal(error?.details?.fieldErrors?.file, "File must be one of: image/png.");
+      return true;
+    }
+  );
+});
+
+test("readUploadBuffer enforces max bytes and empty uploads", async () => {
+  await assert.rejects(
+    () =>
+      readUploadBuffer(Readable.from([Buffer.from("abcdef")]), {
+        maxBytes: 3,
+        fieldName: "avatar",
+        label: "Avatar"
+      }),
+    (error) => {
+      assert.equal(error?.message, "Validation failed.");
+      assert.equal(error?.details?.fieldErrors?.avatar, "Avatar file is too large. Maximum allowed size is 0MB.");
+      return true;
+    }
+  );
+
+  await assert.rejects(
+    () =>
+      readUploadBuffer(Readable.from([]), {
+        fieldName: "avatar",
+        label: "Avatar"
+      }),
+    (error) => {
+      assert.equal(error?.message, "Validation failed.");
+      assert.equal(error?.details?.fieldErrors?.avatar, "Avatar file is empty.");
+      return true;
+    }
+  );
+});

package/test/uploadStorageService.test.js

@@ -0,0 +1,55 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  createUploadStorageService,
+  detectCommonMimeTypeFromBuffer,
+  normalizeStorageKey
+} from "../src/server/storage/createUploadStorageService.js";
+
+function createStorageDouble() {
+  const values = new Map();
+  return {
+    async getItemRaw(key) {
+      return values.has(key) ? values.get(key) : null;
+    },
+    async setItemRaw(key, value) {
+      values.set(key, value);
+    },
+    async removeItem(key) {
+      values.delete(key);
+    }
+  };
+}
+
+test("normalizeStorageKey blocks unsafe paths", () => {
+  assert.equal(normalizeStorageKey("uploads/test"), "uploads/test");
+  assert.equal(normalizeStorageKey("/uploads/test"), "");
+  assert.equal(normalizeStorageKey("../uploads/test"), "");
+});
+
+test("detectCommonMimeTypeFromBuffer recognizes common image types", () => {
+  assert.equal(detectCommonMimeTypeFromBuffer(Buffer.from([0xff, 0xd8, 0xff, 0xdb])), "image/jpeg");
+  assert.equal(
+    detectCommonMimeTypeFromBuffer(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])),
+    "image/png"
+  );
+});
+
+test("createUploadStorageService saves, reads, and deletes raw bytes", async () => {
+  const storage = createStorageDouble();
+  const service = createUploadStorageService({ storage });
+  const payload = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+  const saved = await service.saveFile({
+    storageKey: "uploads/images/face.png",
+    buffer: payload
+  });
+  assert.equal(saved.storageKey, "uploads/images/face.png");
+
+  const loaded = await service.readFile(saved.storageKey);
+  assert.equal(loaded?.mimeType, "image/png");
+  assert.equal(loaded?.buffer?.toString("hex"), payload.toString("hex"));
+
+  await service.deleteFile(saved.storageKey);
+  assert.equal(await service.readFile(saved.storageKey), null);
+});