feat: add multipart image uploads

Register Fastify multipart support, validate JPEG/PNG/WebP binary signatures, store upload bytes through ImageStorage, persist metadata after storage succeeds, clean up bytes on metadata failure, and document the upload boundary. Verification: npm test passed 68 tests and integration passed 14 tests. No build script is configured.

apps/api/tests/application/inventory-image-service.test.js

@@ -0,0 +1,58 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { createInventoryImageService } from '../../src/modules/inventory/services/inventory-image-service.js';
+
+const input = {
+  inventoryItemId: 'inventory-item-id',
+  sellerId: 'seller-id',
+  storageKey: 'inventory/item/front.jpg',
+  originalFilename: 'front.jpg',
+  mimeType: 'image/jpeg',
+  fileSize: 4,
+  width: 1200,
+  height: 900,
+  data: Buffer.from([0xff, 0xd8, 0xff, 0x00]),
+};
+
+test('stores validated upload bytes before persisting image metadata', async () => {
+  const stored = [];
+  const service = createInventoryImageService({
+    imageStorage: {
+      async put(value) { stored.push(value); },
+      async delete() {},
+    },
+    inventoryImageRepository: {
+      async createForSeller(image) {
+        return { id: 'image-1', ...image };
+      },
+    },
+  });
+
+  const image = await service.upload(input);
+
+  assert.equal(stored.length, 1);
+  assert.deepEqual(stored[0], { key: input.storageKey, data: input.data });
+  assert.equal(image.id, 'image-1');
+  assert.equal(image.processingStatus, 'PENDING');
+  assert.equal('data' in image, false);
+});
+
+test('removes stored bytes when metadata persistence fails', async () => {
+  const deleted = [];
+  const service = createInventoryImageService({
+    imageStorage: {
+      async put() {},
+      async delete(key) { deleted.push(key); },
+    },
+    inventoryImageRepository: {
+      async createForSeller() { return null; },
+    },
+  });
+
+  await assert.rejects(
+    () => service.upload(input),
+    (error) => error.code === 'INVENTORY_ITEM_NOT_FOUND',
+  );
+  assert.deepEqual(deleted, [input.storageKey]);
+});

apps/api/tests/domain/inventory-image.test.js

@@ -1,7 +1,10 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
 
-import { validateInventoryImageMetadata } from '../../src/modules/inventory/domain/inventory-image.js';
+import {
+  validateImageSignature,
+  validateInventoryImageMetadata,
+} from '../../src/modules/inventory/domain/inventory-image.js';
 
 const validImage = {
   mimeType: 'image/jpeg',
@@ -27,4 +30,22 @@ test('rejects unsupported MIME types, oversized files, and oversized dimensions'
     () => validateInventoryImageMetadata({ ...validImage, width: 10001 }),
     (error) => error.code === 'IMAGE_DIMENSIONS_INVALID',
   );
+});
+
+test('accepts matching image signatures and rejects mismatched bytes', () => {
+  assert.equal(
+    validateImageSignature(Buffer.from([0xff, 0xd8, 0xff, 0x00]), 'image/jpeg'),
+    true,
+  );
+  assert.equal(
+    validateImageSignature(
+      Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+      'image/png',
+    ),
+    true,
+  );
+  assert.throws(
+    () => validateImageSignature(Buffer.from('not-an-image'), 'image/png'),
+    (error) => error.code === 'IMAGE_SIGNATURE_INVALID',
+  );
 });

apps/api/tests/http/listing-routes.test.js

@@ -71,6 +71,16 @@ function createTestApp({ authenticateAdmin, authorizeUnsafeRequest, listing } =
           updatedAt: new Date('2026-09-08T00:00:00.000Z'),
         };
       },
+      async upload(input) {
+        return {
+          id: 'image-upload-1',
+          ...input,
+          data: undefined,
+          processingStatus: 'PENDING',
+          createdAt: new Date('2026-09-08T00:00:00.000Z'),
+          updatedAt: new Date('2026-09-08T00:00:00.000Z'),
+        };
+      },
     },
   });
 
@@ -198,3 +208,45 @@ test('adds inventory image metadata for the authenticated seller', async (testCo
   assert.equal(response.json().data.inventoryItemId, 'inventory-1');
   assert.equal(response.json().data.processingStatus, 'PENDING');
 });
+
+test('accepts a multipart image upload and forwards validated fields', async (testContext) => {
+  const app = createTestApp({
+    authenticateAdmin: async () => ({ sellerId: 'seller-1' }),
+  });
+  testContext.after(() => app.close());
+
+  const boundary = 'pokemon-image-boundary';
+  const prefix = [
+    `--${boundary}`,
+    'Content-Disposition: form-data; name="width"',
+    '',
+    '1200',
+    `--${boundary}`,
+    'Content-Disposition: form-data; name="height"',
+    '',
+    '900',
+    `--${boundary}`,
+    'Content-Disposition: form-data; name="file"; filename="front.jpg"',
+    'Content-Type: image/jpeg',
+    '',
+  ].join('\r\n');
+  const suffix = `\r\n--${boundary}--\r\n`;
+  const payload = Buffer.concat([
+    Buffer.from(`${prefix}\r\n`),
+    Buffer.from([0xff, 0xd8, 0xff, 0x00]),
+    Buffer.from(suffix),
+  ]);
+
+  const response = await app.inject({
+    method: 'POST',
+    url: '/api/v1/admin/inventory/inventory-1/images',
+    headers: {
+      'content-type': `multipart/form-data; boundary=${boundary}`,
+    },
+    payload,
+  });
+
+  assert.equal(response.statusCode, 201);
+  assert.equal(response.json().data.id, 'image-upload-1');
+  assert.equal(response.json().data.originalFilename, 'front.jpg');
+});