@manablox/media 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,19 @@
+# `@manablox/media`
+
+Uploads and image transforms: validating a file, storing it through the storage driver, recording the asset, deriving presets with sharp, and signing transform URLs so a public consumer cannot mint a resize.
+
+## Exports
+
+- `MediaService`
+- `signVariant`, `verifyVariant`
+- `absoluteMediaUrl`
+
+## Depends on
+
+@manablox/db, @manablox/storage, sharp
+
+## Test
+
+```sh
+pnpm --filter @manablox/media test
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manablox/media",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "exports": {
     ".": {
@@ -11,9 +11,9 @@
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "dependencies": {
-    "@manablox/core": "0.1.0",
-    "@manablox/db": "0.1.0",
-    "@manablox/storage": "0.1.0",
+    "@manablox/core": "0.2.0",
+    "@manablox/db": "0.2.0",
+    "@manablox/storage": "0.2.0",
     "sharp": "^0.35.4"
   },
   "devDependencies": {

package/src/edits.ts

@@ -0,0 +1,112 @@
+import {
+  type AssetCrop,
+  type AssetImageEdits,
+  type FocalPoint,
+  ManabloxError,
+} from '@manablox/core';
+
+/** The edits kept in an asset's `meta`, read leniently so an odd value is ignored, not fatal. */
+export function readImageEdits(meta: Record<string, unknown> | null | undefined): AssetImageEdits {
+  const edits: AssetImageEdits = {};
+  const crop = meta?.crop as Partial<AssetCrop> | undefined;
+  if (crop && [crop.left, crop.top, crop.width, crop.height].every(isFiniteNumber)) {
+    edits.crop = {
+      left: crop.left as number,
+      top: crop.top as number,
+      width: crop.width as number,
+      height: crop.height as number,
+    };
+  }
+  const focal = meta?.focalPoint as Partial<FocalPoint> | undefined;
+  if (focal && isFiniteNumber(focal.x) && isFiniteNumber(focal.y)) {
+    edits.focalPoint = { x: focal.x as number, y: focal.y as number };
+  }
+  return edits;
+}
+
+/**
+ * Checks edits against the image they apply to. A crop must be a whole-pixel rectangle
+ * inside the image; a focal point is a fraction of the *cropped* image, so it is always
+ * inside the unit square whatever the crop.
+ */
+export function validateImageEdits(
+  edits: AssetImageEdits,
+  image: { width: number; height: number },
+): AssetImageEdits {
+  const out: AssetImageEdits = {};
+
+  if (edits.crop) {
+    const crop = edits.crop;
+    const whole = [crop.left, crop.top, crop.width, crop.height].every(Number.isInteger);
+    const inside =
+      crop.left >= 0 &&
+      crop.top >= 0 &&
+      crop.width >= 1 &&
+      crop.height >= 1 &&
+      crop.left + crop.width <= image.width &&
+      crop.top + crop.height <= image.height;
+    if (!whole || !inside) {
+      throw ManabloxError.badRequest('asset.crop.outOfBounds', { ...crop, ...image });
+    }
+    // A crop that is the whole image is no crop at all.
+    if (
+      crop.left !== 0 ||
+      crop.top !== 0 ||
+      crop.width !== image.width ||
+      crop.height !== image.height
+    ) {
+      out.crop = crop;
+    }
+  }
+
+  if (edits.focalPoint) {
+    const { x, y } = edits.focalPoint;
+    if (!(x >= 0 && x <= 1 && y >= 0 && y <= 1)) {
+      throw ManabloxError.badRequest('asset.focalPoint.outOfBounds', { x, y });
+    }
+    out.focalPoint = { x: round3(x), y: round3(y) };
+  }
+
+  return out;
+}
+
+/**
+ * The window of a source image that a `cover` resize to `target` keeps, placed so the
+ * focal point stays in view — as close to the window's centre as the edges allow.
+ *
+ * `cover` scales the image until both target sides are covered and trims the rest;
+ * which part is trimmed is the whole point of a focal point. Sharp's own `position`
+ * only knows edges and centres, so the window is computed here and extracted before
+ * the resize.
+ */
+export function coverWindow(
+  source: { width: number; height: number },
+  target: { width: number; height: number },
+  focal: FocalPoint = { x: 0.5, y: 0.5 },
+): AssetCrop {
+  const ratio = target.width / target.height;
+  let width = source.width;
+  let height = Math.round(source.width / ratio);
+  if (height > source.height) {
+    height = source.height;
+    width = Math.round(source.height * ratio);
+  }
+  width = Math.max(1, Math.min(width, source.width));
+  height = Math.max(1, Math.min(height, source.height));
+
+  const left = clamp(Math.round(focal.x * source.width - width / 2), 0, source.width - width);
+  const top = clamp(Math.round(focal.y * source.height - height / 2), 0, source.height - height);
+  return { left, top, width, height };
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+function round3(value: number): number {
+  return Math.round(value * 1000) / 1000;
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value);
+}

package/src/index.ts

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

package/src/limits.ts

@@ -0,0 +1,56 @@
+import {
+  mimeTypeAllowed,
+  type SpaceAssetSettings,
+  type StorageConfig,
+  withinInstance,
+} from '@manablox/core';
+
+export interface AssetLimits {
+  /** Empty means every type the instance allows. */
+  allowedMimeTypes: string[];
+  maxFileSize: number;
+}
+
+export { mimeTypeAllowed, withinInstance };
+
+/**
+ * The limits an upload into a space is held to: the space's own where it has set them,
+ * otherwise the instance's. A space setting never widens — an entry outside the
+ * instance's allowlist is dropped, and a larger size is capped.
+ */
+export function resolveAssetLimits(
+  instance: Pick<StorageConfig, 'allowedMimeTypes' | 'maxFileSize'>,
+  space: SpaceAssetSettings | null | undefined,
+  fallbackMaxFileSize = 25 * 1024 * 1024,
+): AssetLimits {
+  const instanceTypes = instance.allowedMimeTypes ?? [];
+  const instanceMax = instance.maxFileSize ?? fallbackMaxFileSize;
+
+  const allowedMimeTypes = space?.allowedMimeTypes
+    ? space.allowedMimeTypes.filter((entry) => withinInstance(entry, instanceTypes))
+    : instanceTypes;
+  const maxFileSize =
+    space?.maxFileSize && space.maxFileSize > 0
+      ? Math.min(space.maxFileSize, instanceMax)
+      : instanceMax;
+
+  return { allowedMimeTypes, maxFileSize };
+}
+
+/** Reads the space's asset settings out of its free-form settings, leniently. */
+export function readSpaceAssetSettings(
+  settings: Record<string, unknown> | null | undefined,
+): SpaceAssetSettings | null {
+  const block = settings?.assets as Partial<SpaceAssetSettings> | undefined;
+  if (!block || typeof block !== 'object') return null;
+  const out: SpaceAssetSettings = {};
+  if (Array.isArray(block.allowedMimeTypes)) {
+    out.allowedMimeTypes = block.allowedMimeTypes.filter(
+      (entry): entry is string => typeof entry === 'string',
+    );
+  }
+  if (typeof block.maxFileSize === 'number' && block.maxFileSize > 0) {
+    out.maxFileSize = block.maxFileSize;
+  }
+  return out;
+}

package/src/service.ts

@@ -1,8 +1,20 @@
 import { createHash } from 'node:crypto';
-import { ManabloxError, type MediaConfig, type MediaPreset } from '@manablox/core';
+import {
+  type AssetImageEdits,
+  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 sharp, { type Metadata } from 'sharp';
+import { coverWindow, readImageEdits, validateImageEdits } from './edits.js';
+import {
+  type AssetLimits,
+  mimeTypeAllowed,
+  readSpaceAssetSettings,
+  resolveAssetLimits,
+} from './limits.js';
 import { signTransform, transformPath, verifyTransform } from './signing.js';
 
 export interface UploadInput {
@@ -15,6 +27,8 @@ export interface UploadInput {
   actorId?: string | null;
 }
 
+export type PresentedAsset = AssetRow & { url: string; thumbnailUrl: string | null };
+
 export interface MediaServiceOptions {
   maxFileSize: number;
   allowedMimeTypes: string[];
@@ -31,18 +45,35 @@ export class MediaService {
     private readonly options: MediaServiceOptions,
   ) {}
 
+  /**
+   * The limits an upload into `spaceId` is held to: the space's own settings, narrowed
+   * to the instance's. The instance's are returned alongside so a settings form can show
+   * the ceiling it cannot exceed.
+   */
+  async limits(spaceId: string): Promise<{ effective: AssetLimits; instance: AssetLimits }> {
+    const space = await this.repos.spaces.findById(spaceId);
+    const instance = resolveAssetLimits(this.options, null, this.options.maxFileSize);
+    const effective = resolveAssetLimits(
+      this.options,
+      readSpaceAssetSettings(space?.settings),
+      this.options.maxFileSize,
+    );
+    return { effective, instance };
+  }
+
   async upload(input: UploadInput): Promise<AssetRow> {
-    if (input.body.byteLength > this.options.maxFileSize) {
+    const { effective: limits } = await this.limits(input.spaceId);
+    if (input.body.byteLength > limits.maxFileSize) {
       throw ManabloxError.badRequest('asset.tooLarge', {
         size: input.body.byteLength,
-        max: this.options.maxFileSize,
+        max: limits.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)) {
+    if (!mimeTypeAllowed(detected, limits.allowedMimeTypes)) {
       throw ManabloxError.badRequest('asset.mimeType.notAllowed', { mimeType: detected });
     }
 
@@ -105,7 +136,7 @@ export class MediaService {
     }
 
     const source = await this.storage.get(asset.key);
-    const body = await transform(source, preset, format);
+    const body = await transform(source, preset, format, readImageEdits(asset.meta));
     const meta = await sharp(body).metadata();
 
     await this.storage.put(variantKey, body, {
@@ -126,15 +157,64 @@ export class MediaService {
     return { body, contentType: `image/${format}` };
   }
 
-  /** Public URL for a preset — the storage driver's own URL, or a signed transform path. */
+  /**
+   * Public URL for a preset — the storage driver's own URL, or a signed transform path.
+   *
+   * A variant URL carries the asset's version, so a crop or focal-point change reaches a
+   * browser or CDN that cached the previous rendering as immutable. The original is
+   * never edited, so its URL stays put.
+   */
+  /**
+   * An asset as a client receives it: the row plus the URLs it needs to show it. The
+   * thumbnail is a rendered variant, which only an image has.
+   */
+  present(asset: AssetRow): PresentedAsset {
+    return {
+      ...asset,
+      url: this.urlFor(asset),
+      thumbnailUrl: asset.mimeType.startsWith('image/')
+        ? this.urlFor(asset, 'thumb', 'webp')
+        : null,
+    };
+  }
+
   urlFor(asset: AssetRow, presetName?: string, format = 'webp'): string {
     if (!presetName) return this.storage.url(asset.key) ?? `/media/${asset.id}/original`;
 
+    const version = `v=${asset.updatedAt.getTime().toString(36)}`;
     const secret = this.config.signingSecret;
-    if (!secret) return `/media/${asset.id}/${presetName}.${format}`;
+    if (!secret) return `/media/${asset.id}/${presetName}.${format}?${version}`;
 
     const request = { assetId: asset.id, preset: presetName, format };
-    return transformPath(request, signTransform(secret, request));
+    return `${transformPath(request, signTransform(secret, request))}&${version}`;
+  }
+
+  /**
+   * Sets an image's crop and focal point. Non-destructive: the original stays as
+   * uploaded, the edits live in `meta`, and every variant derived so far is dropped so
+   * the next request renders through the new edits.
+   */
+  async setImageEdits(assetId: string, edits: AssetImageEdits): Promise<AssetRow> {
+    const asset = await this.repos.assets.findById(assetId);
+    if (!asset) throw ManabloxError.notFound('asset.notFound', { id: assetId });
+    if (!asset.mimeType.startsWith('image/') || !asset.width || !asset.height) {
+      throw ManabloxError.badRequest('asset.notAnImage', { id: assetId });
+    }
+
+    const valid = validateImageEdits(edits, { width: asset.width, height: asset.height });
+    const meta = { ...asset.meta };
+    if (valid.crop) meta.crop = valid.crop;
+    else delete meta.crop;
+    if (valid.focalPoint) meta.focalPoint = valid.focalPoint;
+    else delete meta.focalPoint;
+
+    const variants = await this.repos.assets.variants([assetId]);
+    await Promise.all(
+      variants.map((variant) => this.storage.delete(variant.key).catch(() => undefined)),
+    );
+    await this.repos.assets.deleteVariants(assetId);
+
+    return this.repos.assets.update(assetId, { meta });
   }
 
   verify(assetId: string, preset: string, format: string, signature: string | undefined): boolean {
@@ -155,18 +235,42 @@ export class MediaService {
     await this.storage.delete(asset.key).catch(() => undefined);
     await this.repos.assets.delete(assetId);
   }
+}
+
+/**
+ * Applies the preset through the asset's edits: the crop first, then — for a preset
+ * that fixes both sides with `cover` — the window around the focal point, then the
+ * resize. Both extractions fold into one rectangle, since sharp takes a single one
+ * ahead of a resize.
+ */
+async function transform(
+  source: Buffer,
+  preset: MediaPreset,
+  format: string,
+  edits: AssetImageEdits = {},
+): Promise<Buffer> {
+  const pipeline = sharp(source, { failOn: 'error' }).rotate();
 
-  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,
+  const meta = await pipeline.metadata();
+  const oriented = orientedSize(meta);
+  let region = edits.crop ?? null;
+  const size = region ? { width: region.width, height: region.height } : oriented;
+
+  if (preset.width && preset.height && (preset.fit ?? 'inside') === 'cover' && size) {
+    const window = coverWindow(
+      size,
+      { width: preset.width, height: preset.height },
+      edits.focalPoint ?? undefined,
     );
+    region = {
+      left: (region?.left ?? 0) + window.left,
+      top: (region?.top ?? 0) + window.top,
+      width: window.width,
+      height: window.height,
+    };
   }
-}
 
-async function transform(source: Buffer, preset: MediaPreset, format: string): Promise<Buffer> {
-  const pipeline = sharp(source, { failOn: 'error' }).rotate();
+  if (region) pipeline.extract(region);
 
   if (preset.width || preset.height) {
     pipeline.resize({
@@ -193,13 +297,25 @@ async function transform(source: Buffer, preset: MediaPreset, format: string): P
 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;
+    return orientedSize(await sharp(body).metadata());
   } catch {
     return null;
   }
 }
 
+/**
+ * The size as displayed, not as stored: a phone photo carries an EXIF orientation that
+ * `rotate()` honours, so a crop drawn on the displayed image must be measured against
+ * the rotated dimensions or it lands on the wrong part of the picture.
+ */
+function orientedSize(meta: Metadata): { width: number; height: number } | null {
+  if (!meta.width || !meta.height) return null;
+  const swapped = (meta.orientation ?? 1) >= 5;
+  return swapped
+    ? { width: meta.height, height: meta.width }
+    : { width: meta.width, height: meta.height };
+}
+
 /** 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[]]> = [

package/test/edits.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest';
+import { coverWindow, readImageEdits, validateImageEdits } from '../src/edits.js';
+
+describe('coverWindow', () => {
+  it('keeps the whole width of a wide source for a wider target and centres by default', () => {
+    // 4000×3000 into 16:9 — the height is what gets trimmed.
+    const window = coverWindow({ width: 4000, height: 3000 }, { width: 1600, height: 900 });
+    expect(window).toEqual({ left: 0, top: 375, width: 4000, height: 2250 });
+  });
+
+  it('follows the focal point', () => {
+    const source = { width: 4000, height: 3000 };
+    const target = { width: 1600, height: 900 };
+    expect(coverWindow(source, target, { x: 0.5, y: 0 })).toMatchObject({ top: 0 });
+    expect(coverWindow(source, target, { x: 0.5, y: 1 })).toMatchObject({ top: 750 });
+    expect(coverWindow(source, target, { x: 0.5, y: 0.25 })).toMatchObject({ top: 0 });
+  });
+
+  it('never lets the window leave the image', () => {
+    const window = coverWindow(
+      { width: 1000, height: 1000 },
+      { width: 100, height: 300 },
+      { x: 0.02, y: 0.9 },
+    );
+    expect(window.left).toBe(0);
+    expect(window.left + window.width).toBeLessThanOrEqual(1000);
+    expect(window.top + window.height).toBeLessThanOrEqual(1000);
+    expect(window).toMatchObject({ width: 333, height: 1000 });
+  });
+});
+
+describe('validateImageEdits', () => {
+  const image = { width: 800, height: 600 };
+
+  it('refuses a crop that leaves the image or is not whole pixels', () => {
+    expect(() =>
+      validateImageEdits({ crop: { left: 700, top: 0, width: 200, height: 100 } }, image),
+    ).toThrow(/asset.crop.outOfBounds/);
+    expect(() =>
+      validateImageEdits({ crop: { left: 0.5, top: 0, width: 200, height: 100 } }, image),
+    ).toThrow(/asset.crop.outOfBounds/);
+  });
+
+  it('treats a crop of the whole image as no crop', () => {
+    expect(validateImageEdits({ crop: { left: 0, top: 0, ...image } }, image)).toEqual({});
+  });
+
+  it('keeps a focal point inside the unit square, rounded', () => {
+    expect(validateImageEdits({ focalPoint: { x: 0.33333, y: 1 } }, image)).toEqual({
+      focalPoint: { x: 0.333, y: 1 },
+    });
+    expect(() => validateImageEdits({ focalPoint: { x: 1.2, y: 0 } }, image)).toThrow(
+      /asset.focalPoint.outOfBounds/,
+    );
+  });
+});
+
+describe('readImageEdits', () => {
+  it('ignores malformed values rather than failing a render', () => {
+    expect(readImageEdits({ crop: { left: 'a' }, focalPoint: { x: 0.2, y: 0.4 } })).toEqual({
+      focalPoint: { x: 0.2, y: 0.4 },
+    });
+    expect(readImageEdits(null)).toEqual({});
+  });
+});

package/test/limits.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import { mimeTypeAllowed, resolveAssetLimits, withinInstance } from '../src/limits.js';
+
+const instance = { allowedMimeTypes: ['image/', 'application/pdf'], maxFileSize: 10_000 };
+
+describe('resolveAssetLimits', () => {
+  it('falls back to the instance when the space sets nothing', () => {
+    expect(resolveAssetLimits(instance, null)).toEqual({
+      allowedMimeTypes: ['image/', 'application/pdf'],
+      maxFileSize: 10_000,
+    });
+  });
+
+  it('lets a space narrow, and drops what would widen', () => {
+    const limits = resolveAssetLimits(instance, {
+      allowedMimeTypes: ['image/png', 'video/'],
+      maxFileSize: 50_000,
+    });
+    expect(limits).toEqual({ allowedMimeTypes: ['image/png'], maxFileSize: 10_000 });
+  });
+
+  it('reads an instance with no allowlist as everything', () => {
+    expect(resolveAssetLimits({ maxFileSize: 5 }, { allowedMimeTypes: ['video/'] })).toEqual({
+      allowedMimeTypes: ['video/'],
+      maxFileSize: 5,
+    });
+  });
+});
+
+describe('withinInstance / mimeTypeAllowed', () => {
+  it('a family is inside only as a whole family; an exact type through its family', () => {
+    expect(withinInstance('image/', ['image/'])).toBe(true);
+    expect(withinInstance('image/', ['image/png'])).toBe(false);
+    expect(withinInstance('image/png', ['image/'])).toBe(true);
+    expect(withinInstance('image/png', ['image/jpeg'])).toBe(false);
+  });
+
+  it('matches uploads by exact type or family', () => {
+    expect(mimeTypeAllowed('image/webp', ['image/'])).toBe(true);
+    expect(mimeTypeAllowed('image/webp', ['image/png'])).toBe(false);
+    expect(mimeTypeAllowed('text/plain', [])).toBe(true);
+  });
+});