@manablox/media 0.1.0

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@manablox/media",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "dependencies": {
+    "@manablox/core": "0.1.0",
+    "@manablox/db": "0.1.0",
+    "@manablox/storage": "0.1.0",
+    "sharp": "^0.35.4"
+  },
+  "devDependencies": {
+    "@manablox/config-typescript": "0.0.0",
+    "@types/node": "^26.4.1",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './service.js';
+export * from './signing.js';
+export * from './urls.js';

package/src/service.ts

@@ -0,0 +1,234 @@
+import { createHash } from 'node:crypto';
+import { ManabloxError, type MediaConfig, type MediaPreset } from '@manablox/core';
+import type { AssetRow, Repositories } from '@manablox/db';
+import { buildStorageKey, type StorageDriver } from '@manablox/storage';
+import sharp from 'sharp';
+import { signTransform, transformPath, verifyTransform } from './signing.js';
+
+export interface UploadInput {
+  spaceId: string;
+  filename: string;
+  mimeType: string;
+  body: Buffer;
+  alt?: string;
+  title?: string;
+  actorId?: string | null;
+}
+
+export interface MediaServiceOptions {
+  maxFileSize: number;
+  allowedMimeTypes: string[];
+}
+
+const IMAGE_FORMATS = new Set(['avif', 'webp', 'jpeg', 'png']);
+
+/** Upload, probing, and on-demand image derivatives. */
+export class MediaService {
+  constructor(
+    private readonly repos: Repositories,
+    private readonly storage: StorageDriver,
+    private readonly config: MediaConfig & { signingSecret?: string },
+    private readonly options: MediaServiceOptions,
+  ) {}
+
+  async upload(input: UploadInput): Promise<AssetRow> {
+    if (input.body.byteLength > this.options.maxFileSize) {
+      throw ManabloxError.badRequest('asset.tooLarge', {
+        size: input.body.byteLength,
+        max: this.options.maxFileSize,
+      });
+    }
+
+    // Trust the bytes, not the client's Content-Type: a caller can label a script as
+    // `image/png`. The magic-number probe is what decides.
+    const detected = await detectMimeType(input.body, input.mimeType);
+    if (!this.isAllowed(detected)) {
+      throw ManabloxError.badRequest('asset.mimeType.notAllowed', { mimeType: detected });
+    }
+
+    const checksum = createHash('sha256').update(input.body).digest('hex');
+    const existing = await this.repos.assets.findByChecksum(input.spaceId, checksum);
+    if (existing) return existing;
+
+    const key = buildStorageKey(input.spaceId, input.filename);
+    await this.storage.put(key, input.body, { contentType: detected });
+
+    const dimensions = await probeImage(input.body, detected);
+
+    const asset = await this.repos.assets.create({
+      spaceId: input.spaceId,
+      driver: this.storage.name,
+      key,
+      filename: key.split('/').pop() ?? input.filename,
+      name: input.filename.replace(/\.[^.]+$/, ''),
+      mimeType: detected,
+      size: input.body.byteLength,
+      width: dimensions?.width ?? null,
+      height: dimensions?.height ?? null,
+      checksum,
+      alt: input.alt ?? null,
+      title: input.title ?? null,
+      actorId: input.actorId ?? null,
+    });
+
+    // Eager presets keep the first page view off the transform path.
+    for (const preset of this.config.eager ?? []) {
+      if (this.config.presets?.[preset] && dimensions) {
+        await this.derive(asset, preset, this.config.presets[preset]?.format ?? 'webp').catch(
+          () => undefined,
+        );
+      }
+    }
+
+    return asset;
+  }
+
+  /** Returns bytes for a preset, generating and caching the variant on first request. */
+  async derive(
+    asset: AssetRow,
+    presetName: string,
+    format: string,
+  ): Promise<{ body: Buffer; contentType: string }> {
+    const preset = this.config.presets?.[presetName];
+    if (!preset) throw ManabloxError.notFound('media.preset.notFound', { preset: presetName });
+    if (!IMAGE_FORMATS.has(format)) {
+      throw ManabloxError.badRequest('media.format.unsupported', { format });
+    }
+    if (!asset.mimeType.startsWith('image/')) {
+      throw ManabloxError.badRequest('media.notAnImage', { assetId: asset.id });
+    }
+
+    const variantKey = `${asset.key}.${presetName}.${format}`;
+    const cached = await this.repos.assets.findVariant(asset.id, presetName, format);
+    if (cached && (await this.storage.exists(cached.key))) {
+      return { body: await this.storage.get(cached.key), contentType: `image/${format}` };
+    }
+
+    const source = await this.storage.get(asset.key);
+    const body = await transform(source, preset, format);
+    const meta = await sharp(body).metadata();
+
+    await this.storage.put(variantKey, body, {
+      contentType: `image/${format}`,
+      cacheControl: 'public, max-age=31536000, immutable',
+    });
+
+    await this.repos.assets.addVariant({
+      assetId: asset.id,
+      preset: presetName,
+      format,
+      key: variantKey,
+      width: meta.width ?? null,
+      height: meta.height ?? null,
+      size: body.byteLength,
+    });
+
+    return { body, contentType: `image/${format}` };
+  }
+
+  /** Public URL for a preset — the storage driver's own URL, or a signed transform path. */
+  urlFor(asset: AssetRow, presetName?: string, format = 'webp'): string {
+    if (!presetName) return this.storage.url(asset.key) ?? `/media/${asset.id}/original`;
+
+    const secret = this.config.signingSecret;
+    if (!secret) return `/media/${asset.id}/${presetName}.${format}`;
+
+    const request = { assetId: asset.id, preset: presetName, format };
+    return transformPath(request, signTransform(secret, request));
+  }
+
+  verify(assetId: string, preset: string, format: string, signature: string | undefined): boolean {
+    const secret = this.config.signingSecret;
+    if (!secret) return true;
+    if (!signature) return false;
+    return verifyTransform(secret, { assetId, preset, format }, signature);
+  }
+
+  async delete(assetId: string): Promise<void> {
+    const asset = await this.repos.assets.findById(assetId);
+    if (!asset) return;
+
+    const variants = await this.repos.assets.variants([assetId]);
+    await Promise.all(
+      variants.map((variant) => this.storage.delete(variant.key).catch(() => undefined)),
+    );
+    await this.storage.delete(asset.key).catch(() => undefined);
+    await this.repos.assets.delete(assetId);
+  }
+
+  private isAllowed(mimeType: string): boolean {
+    const allowed = this.options.allowedMimeTypes;
+    if (allowed.length === 0) return true;
+    return allowed.some((entry) =>
+      entry.endsWith('/') ? mimeType.startsWith(entry) : mimeType === entry,
+    );
+  }
+}
+
+async function transform(source: Buffer, preset: MediaPreset, format: string): Promise<Buffer> {
+  const pipeline = sharp(source, { failOn: 'error' }).rotate();
+
+  if (preset.width || preset.height) {
+    pipeline.resize({
+      ...(preset.width ? { width: preset.width } : {}),
+      ...(preset.height ? { height: preset.height } : {}),
+      fit: preset.fit ?? 'inside',
+      withoutEnlargement: true,
+    });
+  }
+
+  const quality = preset.quality ?? 82;
+  switch (format) {
+    case 'avif':
+      return pipeline.avif({ quality }).toBuffer();
+    case 'png':
+      return pipeline.png().toBuffer();
+    case 'jpeg':
+      return pipeline.jpeg({ quality, mozjpeg: true }).toBuffer();
+    default:
+      return pipeline.webp({ quality }).toBuffer();
+  }
+}
+
+async function probeImage(body: Buffer, mimeType: string) {
+  if (!mimeType.startsWith('image/')) return null;
+  try {
+    const meta = await sharp(body).metadata();
+    return meta.width && meta.height ? { width: meta.width, height: meta.height } : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Magic-number sniffing for the formats worth trusting; falls back to the declared type. */
+async function detectMimeType(body: Buffer, declared: string): Promise<string> {
+  const signatures: Array<[string, number[]]> = [
+    ['image/png', [0x89, 0x50, 0x4e, 0x47]],
+    ['image/jpeg', [0xff, 0xd8, 0xff]],
+    ['image/gif', [0x47, 0x49, 0x46, 0x38]],
+    ['application/pdf', [0x25, 0x50, 0x44, 0x46]],
+  ];
+
+  for (const [mimeType, bytes] of signatures) {
+    if (bytes.every((byte, index) => body[index] === byte)) return mimeType;
+  }
+
+  // RIFF....WEBP
+  if (
+    body.subarray(0, 4).toString('ascii') === 'RIFF' &&
+    body.subarray(8, 12).toString('ascii') === 'WEBP'
+  ) {
+    return 'image/webp';
+  }
+  // ISO-BMFF brands: AVIF and HEIC share the ftyp box.
+  if (body.subarray(4, 8).toString('ascii') === 'ftyp') {
+    const brand = body.subarray(8, 12).toString('ascii');
+    if (brand.startsWith('avif')) return 'image/avif';
+    if (brand.startsWith('heic') || brand.startsWith('mif1')) return 'image/heic';
+    if (brand.startsWith('isom') || brand.startsWith('mp4')) return 'video/mp4';
+  }
+
+  // Anything unrecognised keeps its declared type but can still be rejected by the
+  // allowlist — never silently upgraded to something more privileged.
+  return declared;
+}

package/src/signing.ts

@@ -0,0 +1,35 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+export interface TransformRequest {
+  assetId: string;
+  preset: string;
+  format: string;
+}
+
+/**
+ * Signed transform URLs.
+ *
+ * Without a signature, an arbitrary `?w=&h=` endpoint is a denial-of-service amplifier:
+ * anyone can ask for thousands of distinct resizes and force the server to decode the
+ * source image each time. Signing means only URLs the CMS emitted are honoured.
+ */
+export function signTransform(secret: string, request: TransformRequest): string {
+  return createHmac('sha256', secret)
+    .update(`${request.assetId}:${request.preset}:${request.format}`)
+    .digest('base64url')
+    .slice(0, 32);
+}
+
+export function verifyTransform(
+  secret: string,
+  request: TransformRequest,
+  signature: string,
+): boolean {
+  const expected = Buffer.from(signTransform(secret, request));
+  const actual = Buffer.from(signature);
+  return expected.length === actual.length && timingSafeEqual(expected, actual);
+}
+
+export function transformPath(request: TransformRequest, signature: string): string {
+  return `/media/${request.assetId}/${request.preset}.${request.format}?s=${signature}`;
+}

package/src/urls.ts

@@ -0,0 +1,16 @@
+/**
+ * Makes a media URL absolute against the instance's public origin.
+ *
+ * `MediaService.urlFor` returns a storage-driver URL when there is one (S3, a CDN) and a
+ * root-relative path otherwise (`/media/…`). A relative path is fine for a same-origin
+ * admin and broken for everything the delivery API exists to serve: a frontend on its own
+ * domain resolves `/media/…` against *itself* and gets a 404. Found by driving
+ * `apps/example-plain` in a browser against a public instance on another port.
+ *
+ * Already-absolute URLs, protocol-relative URLs and data URIs are returned untouched.
+ */
+export function absoluteMediaUrl(url: string, base: string | undefined): string {
+  if (!base) return url;
+  if (!url.startsWith('/') || url.startsWith('//')) return url;
+  return `${base.replace(/\/+$/, '')}${url}`;
+}

package/test/signing.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest';
+import { signTransform, transformPath, verifyTransform } from '../src/signing.js';
+
+const SECRET = 'a-signing-secret';
+const request = { assetId: 'asset-1', preset: 'thumb', format: 'webp' };
+
+describe('transform signing', () => {
+  it('verifies a signature it produced', () => {
+    expect(verifyTransform(SECRET, request, signTransform(SECRET, request))).toBe(true);
+  });
+
+  /**
+   * Without a signature, `/media/:id/:preset` is a resize amplifier: a caller can force
+   * an unbounded number of distinct decodes. Each component is bound into the MAC.
+   */
+  it('rejects a signature bound to a different asset, preset or format', () => {
+    const signature = signTransform(SECRET, request);
+    expect(verifyTransform(SECRET, { ...request, assetId: 'asset-2' }, signature)).toBe(false);
+    expect(verifyTransform(SECRET, { ...request, preset: 'hero' }, signature)).toBe(false);
+    expect(verifyTransform(SECRET, { ...request, format: 'avif' }, signature)).toBe(false);
+  });
+
+  it('rejects a signature made with another secret', () => {
+    expect(verifyTransform(SECRET, request, signTransform('other', request))).toBe(false);
+  });
+
+  it('rejects malformed signatures without throwing', () => {
+    for (const value of ['', 'x', 'x'.repeat(200)]) {
+      expect(verifyTransform(SECRET, request, value)).toBe(false);
+    }
+  });
+
+  it('builds a path carrying the signature', () => {
+    const signature = signTransform(SECRET, request);
+    expect(transformPath(request, signature)).toBe(`/media/asset-1/thumb.webp?s=${signature}`);
+  });
+});

package/test/urls.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest';
+import { absoluteMediaUrl } from '../src/urls.js';
+
+/**
+ * A relative `/media/…` resolves against whatever origin the *browser* is on, which for
+ * a delivery consumer is the frontend, not the API. Found by driving `example-plain`
+ * against a public instance on another port: every `<img>` 404ed.
+ */
+describe('absoluteMediaUrl', () => {
+  it('prefixes a root-relative path with the public origin', () => {
+    expect(absoluteMediaUrl('/media/a1/original', 'https://cms.example.com')).toBe(
+      'https://cms.example.com/media/a1/original',
+    );
+  });
+
+  it('does not double a trailing slash on the base', () => {
+    expect(absoluteMediaUrl('/media/a1/original', 'https://cms.example.com/')).toBe(
+      'https://cms.example.com/media/a1/original',
+    );
+  });
+
+  it('leaves an absolute URL alone, so an S3 or CDN URL survives', () => {
+    const cdn = 'https://cdn.example.com/uploads/a1.jpg';
+    expect(absoluteMediaUrl(cdn, 'https://cms.example.com')).toBe(cdn);
+    expect(absoluteMediaUrl('//cdn.example.com/a1.jpg', 'https://cms.example.com')).toBe(
+      '//cdn.example.com/a1.jpg',
+    );
+  });
+
+  it('leaves the URL alone when no public origin is configured', () => {
+    expect(absoluteMediaUrl('/media/a1/original', undefined)).toBe('/media/a1/original');
+  });
+
+  it('preserves a signed transform query', () => {
+    expect(absoluteMediaUrl('/media/a1/card.webp?s=abc', 'https://cms.example.com')).toBe(
+      'https://cms.example.com/media/a1/card.webp?s=abc',
+    );
+  });
+});

package/tsconfig.json

@@ -0,0 +1 @@
+{ "extends": "@manablox/config-typescript/library.json", "include": ["src", "test"] }

package/vitest.config.ts

@@ -0,0 +1,2 @@
+import { defineConfig } from 'vitest/config';
+export default defineConfig({ test: { environment: 'node', include: ['test/**/*.test.ts'] } });