@beechcms/core 0.8.0 → 0.9.0

package/dist/media/file-types.d.ts

@@ -25,6 +25,10 @@ export interface FileTypeDefinition {
     readonly magicBytes?: readonly number[];
     /** Custom signature matching function for formats with complex, variable, or offset headers. */
     readonly matchSignature?: (bytes: Uint8Array) => boolean;
+    /** Minimum buffer length `matchSignature` needs to decide; defaults to a short generic prefix check. */
+    readonly minSignatureLength?: number;
+    /** Label for formats sharing one signature (ZIP, OLE2), used when the exact format is ambiguous. */
+    readonly signatureFamily?: string;
 }
 /**
  * Checks whether a byte buffer starts with a specified byte prefix.
@@ -81,6 +85,14 @@ export declare function getFileTypeByExtension(ext: string | null | undefined):
  * @returns The matching FileTypeDefinition, or undefined if unsupported.
  */
 export declare function getFileTypeByMime(mime: string | null | undefined): FileTypeDefinition | undefined;
+/**
+ * Canonicalizes a declared MIME type to its registered primary form (e.g. 'image/jpg' -> 'image/jpeg').
+ * Unrecognized MIME types pass through unchanged (lowercased, parameters stripped).
+ *
+ * @param mime - The declared MIME string (e.g. 'image/jpg' or 'image/png; charset=utf-8').
+ * @returns The canonical primary MIME type, or the normalised input if unrecognized.
+ */
+export declare function canonicalizeMime(mime: string): string;
 /**
  * Extracts a lowercase file extension from a URL string or query parameters.
  *

package/dist/media/file-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-types.d.ts","sourceRoot":"","sources":["../../src/media/file-types.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,UAAU,GAAG,KAAK,CAAA;AAErD;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,CAAA;AAE3D;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,uDAAuD;IACvD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;IACrC,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAA;IAC/B,qFAAqF;IACrF,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,sEAAsE;IACtE,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACvC,gGAAgG;IAChG,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAA;CACzD;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAMrF;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,kBAAkB,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAKxF;AA6CD;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAgMnE,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,MAAM,CAA4B,CAAA;AAErF;;GAEG;AACH,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EAAmC,CAAA;AAIzF,8CAA8C;AAC9C,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAEhD,CAAA;AAED,iDAAiD;AACjD,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAEnD,CAAA;AAED,gDAAgD;AAChD,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAElD,CAAA;AAED,0CAA0C;AAC1C,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAE7C,CAAA;AAED,6CAA6C;AAC7C,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAEhD,CAAA;AAED,4CAA4C;AAC5C,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAE/C,CAAA;AAMD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,kBAAkB,GAAG,SAAS,CAIrG;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,kBAAkB,GAAG,SAAS,CAMjG;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAgB3D;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAO/F;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CASxE"}
+{"version":3,"file":"file-types.d.ts","sourceRoot":"","sources":["../../src/media/file-types.ts"],"names":[],"mappings":"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"}

package/dist/media/file-types.js

@@ -61,6 +61,7 @@ const OLE_DOCUMENT_DEFINITION = {
     isBinary: true,
     magicBytes: [...OLE_MAGIC],
     matchSignature: matchOleSignature,
+    signatureFamily: 'OLE2 container',
 };
 /** Common shared definition for OpenXML Office files. */
 const OPENXML_DOCUMENT_DEFINITION = {
@@ -68,6 +69,7 @@ const OPENXML_DOCUMENT_DEFINITION = {
     isBinary: true,
     magicBytes: [0x50, 0x4B, 0x03, 0x04],
     matchSignature: matchZipSignature,
+    signatureFamily: 'ZIP container',
 };
 /**
  * Single source of truth registry for all supported file types in BeechCMS.
@@ -97,6 +99,7 @@ export const SUPPORTED_FILE_TYPES = {
         category: 'image',
         isBinary: true,
         magicBytes: [0x47, 0x49, 0x46, 0x38],
+        minSignatureLength: 6,
         matchSignature: (bytes) => bytes.length >= 6 &&
             bytes[0] === 0x47 && bytes[1] === 0x49 && bytes[2] === 0x46 && bytes[3] === 0x38 &&
             (bytes[4] === 0x37 || bytes[4] === 0x39) && bytes[5] === 0x61,
@@ -108,6 +111,7 @@ export const SUPPORTED_FILE_TYPES = {
         category: 'image',
         isBinary: true,
         magicBytes: [0x52, 0x49, 0x46, 0x46],
+        minSignatureLength: 12,
         matchSignature: (bytes) => bytes.length >= 12 &&
             bytes[0] === 0x52 && bytes[1] === 0x49 && bytes[2] === 0x46 && bytes[3] === 0x46 &&
             bytes[8] === 0x57 && bytes[9] === 0x45 && bytes[10] === 0x42 && bytes[11] === 0x50,
@@ -119,6 +123,7 @@ export const SUPPORTED_FILE_TYPES = {
         category: 'image',
         isBinary: true,
         magicBytes: [0x66, 0x74, 0x79, 0x70],
+        minSignatureLength: 12,
         matchSignature: (bytes) => {
             if (bytes.length < 12)
                 return false;
@@ -222,6 +227,7 @@ export const SUPPORTED_FILE_TYPES = {
         isBinary: true,
         magicBytes: [0x50, 0x4B, 0x03, 0x04],
         matchSignature: matchZipSignature,
+        signatureFamily: 'ZIP container',
     },
     '7z': {
         extension: '7z',
@@ -238,6 +244,7 @@ export const SUPPORTED_FILE_TYPES = {
         category: 'archive',
         isBinary: true,
         magicBytes: [0x75, 0x73, 0x74, 0x61, 0x72], // 'ustar'
+        minSignatureLength: 512,
         matchSignature: (bytes) => {
             if (bytes.length < 512)
                 return false;
@@ -297,6 +304,8 @@ export function getFileTypeByExtension(ext) {
     if (!ext)
         return undefined;
     const normalised = ext.replace(/^\./, '').toLowerCase().trim();
+    if (!Object.hasOwn(SUPPORTED_FILE_TYPES, normalised))
+        return undefined;
     return SUPPORTED_FILE_TYPES[normalised];
 }
 /**
@@ -311,6 +320,17 @@ export function getFileTypeByMime(mime) {
     const normalised = mime.split(';')[0].trim().toLowerCase();
     return Object.values(SUPPORTED_FILE_TYPES).find((def) => def.mimeTypes.some((m) => m.toLowerCase() === normalised));
 }
+/**
+ * Canonicalizes a declared MIME type to its registered primary form (e.g. 'image/jpg' -> 'image/jpeg').
+ * Unrecognized MIME types pass through unchanged (lowercased, parameters stripped).
+ *
+ * @param mime - The declared MIME string (e.g. 'image/jpg' or 'image/png; charset=utf-8').
+ * @returns The canonical primary MIME type, or the normalised input if unrecognized.
+ */
+export function canonicalizeMime(mime) {
+    const normalised = mime.split(';')[0].trim().toLowerCase();
+    return getFileTypeByMime(normalised)?.primaryMime ?? normalised;
+}
 /**
  * Extracts a lowercase file extension from a URL string or query parameters.
  *
@@ -320,10 +340,10 @@ export function getFileTypeByMime(mime) {
 export function extensionFromUrl(url) {
     try {
         const parsed = new URL(url);
-        const path = parsed.pathname;
-        const dot = path.lastIndexOf('.');
-        if (dot >= 0 && dot < path.length - 1) {
-            return path.slice(dot + 1).toLowerCase();
+        const segment = parsed.pathname.slice(parsed.pathname.lastIndexOf('/') + 1);
+        const dot = segment.lastIndexOf('.');
+        if (dot >= 0 && dot < segment.length - 1) {
+            return segment.slice(dot + 1).toLowerCase();
         }
         const param = parsed.searchParams.get('fm') || parsed.searchParams.get('format') || parsed.searchParams.get('ext');
         if (param && /^[a-z0-9]+$/i.test(param)) {

package/dist/media/image-transformer.d.ts

@@ -0,0 +1,34 @@
+/** Pixel dimensions of an image. */
+export interface MediaDimensions {
+    readonly width: number;
+    readonly height: number;
+}
+/** Output MIME types the transform path may emit. AVIF is deliberately absent (v1). */
+export type ImageOutputMime = 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp';
+/**
+ * A fully resolved transformation. Every number here comes from a pre-registered preset or from
+ * MEDIA_QUALITY_VALUES — never from the request.
+ */
+export interface ImageTransformSpec {
+    readonly width: number;
+    /** Present for crop presets only; scale presets derive height from the source aspect ratio. */
+    readonly height?: number;
+    readonly fit: 'cover' | 'scale-down';
+    readonly outputMime: ImageOutputMime;
+    readonly quality: number;
+}
+export interface TransformedImage {
+    readonly body: ReadableStream<Uint8Array>;
+    readonly contentType: string;
+}
+/**
+ * Port for edge image transformation. The API injects a Cloudflare Images adapter when the
+ * `IMAGES` binding exists and `null` otherwise; handlers never see the binding itself.
+ */
+export interface IImageTransformer {
+    /** Reads the source's pixel dimensions. Rejects when the stream is not a raster image. */
+    probe(source: ReadableStream<Uint8Array>): Promise<MediaDimensions>;
+    /** Applies the spec and returns the encoded variant. */
+    transform(source: ReadableStream<Uint8Array>, spec: ImageTransformSpec): Promise<TransformedImage>;
+}
+//# sourceMappingURL=image-transformer.d.ts.map

package/dist/media/image-transformer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-transformer.d.ts","sourceRoot":"","sources":["../../src/media/image-transformer.ts"],"names":[],"mappings":"AAGA,oCAAoC;AACpC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,uFAAuF;AACvF,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,WAAW,GAAG,WAAW,GAAG,YAAY,CAAA;AAErF;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,+FAA+F;IAC/F,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,YAAY,CAAA;IACpC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAA;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,CAAA;IACzC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,0FAA0F;IAC1F,KAAK,CAAC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;IACnE,wDAAwD;IACxD,SAAS,CAAC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;CACnG"}

package/dist/media/image-transformer.js

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+export {};

package/dist/media/magic-bytes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"magic-bytes.d.ts","sourceRoot":"","sources":["../../src/media/magic-bytes.ts"],"names":[],"mappings":"AAWA;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,qEAAqE;IACrE,KAAK,EAAE,OAAO,CAAA;IACd,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAiBD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,WAAW,GAAG,UAAU,EAChC,YAAY,EAAE,MAAM,GACnB,0BAA0B,CAgD5B"}
+{"version":3,"file":"magic-bytes.d.ts","sourceRoot":"","sources":["../../src/media/magic-bytes.ts"],"names":[],"mappings":"AAWA;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,qEAAqE;IACrE,KAAK,EAAE,OAAO,CAAA;IACd,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAkBD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,WAAW,GAAG,UAAU,EAChC,YAAY,EAAE,MAAM,GACnB,0BAA0B,CA0D5B"}

package/dist/media/magic-bytes.js

@@ -2,18 +2,19 @@
 // Copyright (c) 2024–2026 Flavio De Musso
 import { SUPPORTED_FILE_TYPES, getFileTypeByMime, BLOCKED_IMAGE_MIME_TYPES, matchesFileSignature, } from './file-types.js';
 /**
- * Iterates across supported binary definitions to find any matching file signature.
+ * Finds the binary formats matching the buffer, one per distinct MIME type.
  *
  * @param bytes - The raw byte buffer to analyze.
- * @returns The matching FileTypeDefinition if recognized, or undefined.
+ * @returns Matching definitions (empty if unrecognized).
  */
-function detectBinaryType(bytes) {
+function detectBinaryTypes(bytes) {
+    const matches = new Map();
     for (const def of Object.values(SUPPORTED_FILE_TYPES)) {
-        if (def.isBinary && matchesFileSignature(def, bytes)) {
-            return def;
+        if (def.isBinary && !matches.has(def.primaryMime) && matchesFileSignature(def, bytes)) {
+            matches.set(def.primaryMime, def);
         }
     }
-    return undefined;
+    return [...matches.values()];
 }
 /**
  * Validates that an uploaded file's binary content matches its declared MIME type,
@@ -45,7 +46,7 @@ export function verifyMagicBytes(buffer, declaredMime) {
         return { valid: true, detectedMime: declaredDef.primaryMime };
     }
     // If buffer is smaller than the minimum bytes needed for initial signature inspection (typically 4, or 2-3 for short signatures)
-    const minInspectionLength = Math.min(4, declaredDef.magicBytes?.length ?? 4);
+    const minInspectionLength = declaredDef.minSignatureLength ?? Math.min(4, declaredDef.magicBytes?.length ?? 4);
     if (bytes.length < minInspectionLength) {
         return { valid: false, error: 'File buffer too small for signature inspection' };
     }
@@ -54,13 +55,22 @@ export function verifyMagicBytes(buffer, declaredMime) {
         return { valid: true, detectedMime: declaredDef.primaryMime };
     }
     // Signature mismatch: check if it matches another known binary signature
-    const detectedDef = detectBinaryType(bytes);
-    if (detectedDef) {
+    const detected = detectBinaryTypes(bytes);
+    if (detected.length === 1) {
+        const [detectedDef] = detected;
         return {
             valid: false,
             detectedMime: detectedDef.primaryMime,
             error: `Signature mismatch: file is ${detectedDef.extension.toUpperCase()} but declared as ${declaredMime}`,
         };
     }
+    if (detected.length > 1) {
+        // Shared signature: exact format unknowable
+        const family = detected[0].signatureFamily ?? 'shared-signature format';
+        return {
+            valid: false,
+            error: `Signature mismatch: file is a ${family} but declared as ${declaredMime}`,
+        };
+    }
     return { valid: false, error: `Unrecognized file signature for declared MIME ${declaredMime}` };
 }

package/dist/media/media-transform.d.ts

@@ -0,0 +1,92 @@
+import type { ImageOutputMime, ImageTransformSpec, MediaDimensions } from './image-transformer.js';
+/** Default ceiling, in pixels, on either side of a derived variant. Covers native 32:9 ultrawide panels. */
+export declare const DEFAULT_MEDIA_MAX_DIMENSION = 5120;
+/** MEDIA_MAX_DIMENSION may lower the ceiling freely but raise it only this far. */
+export declare const ABSOLUTE_MAX_MEDIA_DIMENSION = 8192;
+export type MediaOutputFormat = 'original' | 'webp' | 'jpeg';
+export type MediaQuality = 'low' | 'medium' | 'high';
+export declare const MEDIA_OUTPUT_FORMATS: readonly MediaOutputFormat[];
+export declare const MEDIA_QUALITIES: readonly MediaQuality[];
+export declare const DEFAULT_MEDIA_FORMAT: MediaOutputFormat;
+export declare const DEFAULT_MEDIA_QUALITY: MediaQuality;
+/** Encoder quality per enum value. `medium` ≈ 82 per the brief. */
+export declare const MEDIA_QUALITY_VALUES: Readonly<Record<MediaQuality, number>>;
+export type MediaPreset = {
+    readonly kind: 'crop';
+    readonly width: number;
+    readonly height: number;
+} | {
+    readonly kind: 'scale';
+    readonly width: number;
+};
+export type MediaPresetCatalog = ReadonlyMap<string, MediaPreset>;
+export declare const DEFAULT_MEDIA_SCALE_WIDTHS: readonly [320, 480, 640, 768, 1024, 1280, 1536, 1920, 2560, 3840, 5120];
+export declare const DEFAULT_MEDIA_PRESETS: Readonly<Record<string, MediaPreset>>;
+/** Raster sources the transform path accepts. Everything else — SVG, PDF, video, AVIF, BMP, ICO — is refused. */
+export declare const TRANSFORMABLE_MEDIA_MIME_TYPES: readonly ImageOutputMime[];
+/** Parameters of the discarded free-form contract. Their presence is an error, never ignored. */
+export declare const FORBIDDEN_MEDIA_TRANSFORM_PARAMS: readonly string[];
+export type MediaTransformErrorCode = 'media_param_forbidden' | 'media_param_duplicated' | 'media_preset_required' | 'media_format_invalid' | 'media_quality_invalid' | 'media_preset_unknown' | 'media_not_transformable' | 'media_dimension_exceeded';
+export interface MediaTransformRequest {
+    readonly preset: string;
+    readonly format: MediaOutputFormat;
+    readonly quality: MediaQuality;
+}
+export type MediaTransformQuery = {
+    readonly kind: 'none';
+} | {
+    readonly kind: 'invalid';
+    readonly code: MediaTransformErrorCode;
+} | {
+    readonly kind: 'transform';
+    readonly request: MediaTransformRequest;
+};
+/** Thrown by buildMediaPresetCatalog on any malformed MEDIA_PRESETS entry. Fail closed, never fall back. */
+export declare class MediaPresetCatalogError extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+/**
+ * Classifies a media query string. Pure: does not consult the catalog (that is env-dependent and
+ * resolved by the caller), so an unknown-but-well-formed preset name returns `transform`.
+ */
+export declare function parseMediaTransformQuery(params: URLSearchParams): MediaTransformQuery;
+/**
+ * Canonical query for a request: fixed order preset → format → quality, defaults omitted.
+ * `@beechcms/client` emits exactly this string; the server recomputes it and never trusts the client's.
+ */
+export declare function canonicalMediaTransformQuery(request: MediaTransformRequest): string;
+/**
+ * Builds the active catalog: DEFAULT_MEDIA_PRESETS merged by name with `overrides`
+ * (the parsed MEDIA_PRESETS JSON). An override value of `null` removes a preset.
+ * Defaults larger than `maxDimension` are dropped (they could only ever 400); an operator-supplied
+ * preset larger than `maxDimension` is an error.
+ *
+ * @throws {MediaPresetCatalogError} on any malformed override.
+ */
+export declare function buildMediaPresetCatalog(overrides: unknown, maxDimension: number): MediaPresetCatalog;
+export declare function isTransformableMime(mime: string | null | undefined): boolean;
+/**
+ * Output dimensions of a scale preset (`fit=scale-down`: never upscales). Returns `null` when either
+ * side would exceed `maxDimension` — the pathological-aspect-ratio guard of brief §4. Never truncates.
+ */
+export declare function deriveScaleOutput(presetWidth: number, source: MediaDimensions, maxDimension: number): MediaDimensions | null;
+/**
+ * Identity of a preset's *definition*, so redefining a name never reuses an old variant.
+ * A scale preset's validity depends on the effective dimension ceiling (its height derives from the
+ * source), so the ceiling is part of its identity; a crop preset is validated at catalog build.
+ */
+export declare function mediaPresetSignature(preset: MediaPreset, maxDimension: number): string;
+/** Precondition: `isTransformableMime(sourceMime)` is true. */
+export declare function buildImageTransformSpec(preset: MediaPreset, request: MediaTransformRequest, sourceMime: string): ImageTransformSpec;
+/**
+ * Strong ETag of a variant: source identity (key + size — keys are never overwritten) plus the
+ * canonical request plus the preset definition (and the ceiling for scale presets). Format: `"mv1-<32 hex>"`.
+ */
+export declare function computeMediaVariantEtag(source: {
+    readonly key: string;
+    readonly size: number;
+}, request: MediaTransformRequest, preset: MediaPreset, maxDimension: number): Promise<string>;
+/** RFC 9110 §13.1.2: `*` matches; otherwise weak comparison against a comma-separated list. */
+export declare function ifNoneMatchMatches(header: string | null | undefined, etag: string | null | undefined): boolean;
+//# sourceMappingURL=media-transform.d.ts.map

package/dist/media/media-transform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-transform.d.ts","sourceRoot":"","sources":["../../src/media/media-transform.ts"],"names":[],"mappings":"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"}

package/dist/media/media-transform.js

@@ -0,0 +1,197 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { sha256hex } from '../engine/privacy/policies.js';
+import { canonicalizeMime } from './file-types.js';
+/** Default ceiling, in pixels, on either side of a derived variant. Covers native 32:9 ultrawide panels. */
+export const DEFAULT_MEDIA_MAX_DIMENSION = 5120;
+/** MEDIA_MAX_DIMENSION may lower the ceiling freely but raise it only this far. */
+export const ABSOLUTE_MAX_MEDIA_DIMENSION = 8192;
+export const MEDIA_OUTPUT_FORMATS = ['original', 'webp', 'jpeg'];
+export const MEDIA_QUALITIES = ['low', 'medium', 'high'];
+export const DEFAULT_MEDIA_FORMAT = 'original';
+export const DEFAULT_MEDIA_QUALITY = 'medium';
+/** Encoder quality per enum value. `medium` ≈ 82 per the brief. */
+export const MEDIA_QUALITY_VALUES = Object.freeze({ low: 60, medium: 82, high: 92 });
+export const DEFAULT_MEDIA_SCALE_WIDTHS = [320, 480, 640, 768, 1024, 1280, 1536, 1920, 2560, 3840, 5120];
+export const DEFAULT_MEDIA_PRESETS = Object.freeze({
+    thumbnail: { kind: 'crop', width: 200, height: 200 },
+    avatar: { kind: 'crop', width: 128, height: 128 },
+    card: { kind: 'crop', width: 400, height: 300 },
+    'og-image': { kind: 'crop', width: 1200, height: 630 },
+    hero: { kind: 'crop', width: 1920, height: 800 },
+    ...Object.fromEntries(DEFAULT_MEDIA_SCALE_WIDTHS.map((width) => [`w-${width}`, { kind: 'scale', width }])),
+});
+/** Raster sources the transform path accepts. Everything else — SVG, PDF, video, AVIF, BMP, ICO — is refused. */
+export const TRANSFORMABLE_MEDIA_MIME_TYPES = ['image/jpeg', 'image/png', 'image/gif', 'image/webp'];
+/** Parameters of the discarded free-form contract. Their presence is an error, never ignored. */
+export const FORBIDDEN_MEDIA_TRANSFORM_PARAMS = ['w', 'h', 'width', 'height', 'fit', 'q'];
+/** Thrown by buildMediaPresetCatalog on any malformed MEDIA_PRESETS entry. Fail closed, never fall back. */
+export class MediaPresetCatalogError extends Error {
+    reason;
+    constructor(reason) {
+        super(`Invalid media preset catalog: ${reason}`);
+        this.reason = reason;
+        this.name = 'MediaPresetCatalogError';
+    }
+}
+const PRESET_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/;
+const SCALE_NAME_PATTERN = /^w-([1-9]\d*)$/;
+const invalid = (code) => ({ kind: 'invalid', code });
+/**
+ * Classifies a media query string. Pure: does not consult the catalog (that is env-dependent and
+ * resolved by the caller), so an unknown-but-well-formed preset name returns `transform`.
+ */
+export function parseMediaTransformQuery(params) {
+    if (FORBIDDEN_MEDIA_TRANSFORM_PARAMS.some((name) => params.has(name)))
+        return invalid('media_param_forbidden');
+    const presets = params.getAll('preset');
+    const formats = params.getAll('format');
+    const qualities = params.getAll('quality');
+    if (presets.length > 1 || formats.length > 1 || qualities.length > 1)
+        return invalid('media_param_duplicated');
+    if (presets.length === 0 && formats.length === 0 && qualities.length === 0)
+        return { kind: 'none' };
+    const preset = presets[0];
+    if (!preset)
+        return invalid('media_preset_required');
+    const format = formats[0] ?? DEFAULT_MEDIA_FORMAT;
+    if (!MEDIA_OUTPUT_FORMATS.includes(format))
+        return invalid('media_format_invalid');
+    const quality = qualities[0] ?? DEFAULT_MEDIA_QUALITY;
+    if (!MEDIA_QUALITIES.includes(quality))
+        return invalid('media_quality_invalid');
+    if (!PRESET_NAME_PATTERN.test(preset))
+        return invalid('media_preset_unknown');
+    return { kind: 'transform', request: { preset, format: format, quality: quality } };
+}
+/**
+ * Canonical query for a request: fixed order preset → format → quality, defaults omitted.
+ * `@beechcms/client` emits exactly this string; the server recomputes it and never trusts the client's.
+ */
+export function canonicalMediaTransformQuery(request) {
+    let query = `preset=${encodeURIComponent(request.preset)}`;
+    if (request.format !== DEFAULT_MEDIA_FORMAT)
+        query += `&format=${request.format}`;
+    if (request.quality !== DEFAULT_MEDIA_QUALITY)
+        query += `&quality=${request.quality}`;
+    return query;
+}
+function isPositiveIntegerAtMost(value, max) {
+    return typeof value === 'number' && Number.isInteger(value) && value > 0 && value <= max;
+}
+function parsePresetEntry(name, value, maxDimension) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new MediaPresetCatalogError(`preset "${name}" must be an object or null`);
+    }
+    const entry = value;
+    const scaleMatch = SCALE_NAME_PATTERN.exec(name);
+    if (entry.kind === 'crop') {
+        if (Object.keys(entry).some((field) => !['kind', 'width', 'height'].includes(field))) {
+            throw new MediaPresetCatalogError(`preset "${name}" has unknown fields`);
+        }
+        if (scaleMatch)
+            throw new MediaPresetCatalogError(`"${name}" is reserved for scale presets`);
+        if (!isPositiveIntegerAtMost(entry.width, maxDimension) || !isPositiveIntegerAtMost(entry.height, maxDimension)) {
+            throw new MediaPresetCatalogError(`preset "${name}" needs integer width/height in 1..${maxDimension}`);
+        }
+        return { kind: 'crop', width: entry.width, height: entry.height };
+    }
+    if (entry.kind === 'scale') {
+        if (Object.keys(entry).some((field) => !['kind', 'width'].includes(field))) {
+            throw new MediaPresetCatalogError(`preset "${name}" has unknown fields (scale presets never take a height)`);
+        }
+        if (!isPositiveIntegerAtMost(entry.width, maxDimension)) {
+            throw new MediaPresetCatalogError(`preset "${name}" needs an integer width in 1..${maxDimension}`);
+        }
+        if (name !== `w-${entry.width}`)
+            throw new MediaPresetCatalogError(`scale preset "${name}" must be named "w-${entry.width}"`);
+        return { kind: 'scale', width: entry.width };
+    }
+    throw new MediaPresetCatalogError(`preset "${name}" has kind other than "crop" | "scale"`);
+}
+/**
+ * Builds the active catalog: DEFAULT_MEDIA_PRESETS merged by name with `overrides`
+ * (the parsed MEDIA_PRESETS JSON). An override value of `null` removes a preset.
+ * Defaults larger than `maxDimension` are dropped (they could only ever 400); an operator-supplied
+ * preset larger than `maxDimension` is an error.
+ *
+ * @throws {MediaPresetCatalogError} on any malformed override.
+ */
+export function buildMediaPresetCatalog(overrides, maxDimension) {
+    const catalog = new Map();
+    for (const [name, preset] of Object.entries(DEFAULT_MEDIA_PRESETS)) {
+        const largest = preset.kind === 'crop' ? Math.max(preset.width, preset.height) : preset.width;
+        if (largest <= maxDimension)
+            catalog.set(name, preset);
+    }
+    if (overrides === undefined)
+        return catalog;
+    if (typeof overrides !== 'object' || overrides === null || Array.isArray(overrides)) {
+        throw new MediaPresetCatalogError('MEDIA_PRESETS must be a JSON object keyed by preset name');
+    }
+    for (const [name, value] of Object.entries(overrides)) {
+        if (!PRESET_NAME_PATTERN.test(name))
+            throw new MediaPresetCatalogError(`"${name}" is not a valid preset name`);
+        if (value === null) {
+            catalog.delete(name);
+            continue;
+        }
+        catalog.set(name, parsePresetEntry(name, value, maxDimension));
+    }
+    return catalog;
+}
+export function isTransformableMime(mime) {
+    if (!mime)
+        return false;
+    return TRANSFORMABLE_MEDIA_MIME_TYPES.includes(canonicalizeMime(mime));
+}
+/**
+ * Output dimensions of a scale preset (`fit=scale-down`: never upscales). Returns `null` when either
+ * side would exceed `maxDimension` — the pathological-aspect-ratio guard of brief §4. Never truncates.
+ */
+export function deriveScaleOutput(presetWidth, source, maxDimension) {
+    if (source.width <= 0 || source.height <= 0)
+        return null;
+    const output = source.width <= presetWidth
+        ? { width: source.width, height: source.height }
+        : { width: presetWidth, height: Math.max(1, Math.round((source.height * presetWidth) / source.width)) };
+    return output.width > maxDimension || output.height > maxDimension ? null : output;
+}
+/**
+ * Identity of a preset's *definition*, so redefining a name never reuses an old variant.
+ * A scale preset's validity depends on the effective dimension ceiling (its height derives from the
+ * source), so the ceiling is part of its identity; a crop preset is validated at catalog build.
+ */
+export function mediaPresetSignature(preset, maxDimension) {
+    return preset.kind === 'crop' ? `crop:${preset.width}x${preset.height}` : `scale:${preset.width}@${maxDimension}`;
+}
+/** Precondition: `isTransformableMime(sourceMime)` is true. */
+export function buildImageTransformSpec(preset, request, sourceMime) {
+    const outputMime = request.format === 'webp'
+        ? 'image/webp'
+        : request.format === 'jpeg'
+            ? 'image/jpeg'
+            : canonicalizeMime(sourceMime);
+    const quality = MEDIA_QUALITY_VALUES[request.quality];
+    return preset.kind === 'crop'
+        ? { width: preset.width, height: preset.height, fit: 'cover', outputMime, quality }
+        : { width: preset.width, fit: 'scale-down', outputMime, quality };
+}
+/**
+ * Strong ETag of a variant: source identity (key + size — keys are never overwritten) plus the
+ * canonical request plus the preset definition (and the ceiling for scale presets). Format: `"mv1-<32 hex>"`.
+ */
+export async function computeMediaVariantEtag(source, request, preset, maxDimension) {
+    const digest = await sha256hex(`${source.key}\n${source.size}\n${canonicalMediaTransformQuery(request)}\n${mediaPresetSignature(preset, maxDimension)}`);
+    return `"mv1-${digest.slice(0, 32)}"`;
+}
+/** RFC 9110 §13.1.2: `*` matches; otherwise weak comparison against a comma-separated list. */
+export function ifNoneMatchMatches(header, etag) {
+    if (!header || !etag)
+        return false;
+    const target = etag.replace(/^W\//, '');
+    return header.split(',').some((candidate) => {
+        const trimmed = candidate.trim();
+        return trimmed === '*' || trimmed.replace(/^W\//, '') === target;
+    });
+}

package/dist/media/media.repository.d.ts

@@ -14,6 +14,11 @@ export interface MediaRepository {
      * Tracks a new file upload in the database.
      */
     trackUpload(media: Omit<MediaObject, 'created_at'>): Promise<void>;
+    /**
+     * Registers a file and counts its bytes toward total storage in one atomic step.
+     * Returns false, counting nothing, when the key is already registered.
+     */
+    registerUpload(media: Omit<MediaObject, 'created_at'>): Promise<boolean>;
     /**
      * Retrieves tracking info for a file by its key.
      */

package/dist/media/media.repository.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"media.repository.d.ts","sourceRoot":"","sources":["../../src/media/media.repository.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnE;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAEnD;;OAEG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpC;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,WAAW,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEnG;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/C;;OAEG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/C;;OAEG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzC;;OAEG;IACH,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACpC"}
+{"version":3,"file":"media.repository.d.ts","sourceRoot":"","sources":["../../src/media/media.repository.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnE;;;OAGG;IACH,cAAc,CAAC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEzE;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAEnD;;OAEG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpC;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,WAAW,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEnG;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/C;;OAEG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/C;;OAEG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzC;;OAEG;IACH,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACpC"}

package/dist/media.repository.d.ts

@@ -0,0 +1,61 @@
+/**
+ * MediaRepository - Interface for tracking media assets in the database.
+ */
+export interface MediaObject {
+    key: string;
+    filename: string;
+    mime_type: string;
+    size_bytes: number;
+    uploaded_by: string;
+    created_at: number;
+}
+export interface MediaRepository {
+    /**
+     * Tracks a new file upload in the database.
+     */
+    trackUpload(media: Omit<MediaObject, 'created_at'>): Promise<void>;
+    /**
+     * Retrieves tracking info for a file by its key.
+     */
+    getByKey(key: string): Promise<MediaObject | null>;
+    /**
+     * Removes tracking info for a file.
+     */
+    untrack(key: string): Promise<void>;
+    /**
+     * Lists all tracked media with pagination.
+     */
+    list(options: {
+        limit: number;
+        offset: number;
+    }): Promise<{
+        items: MediaObject[];
+        total: number;
+    }>;
+    /**
+     * Gets the total number of tracked media objects.
+     */
+    count(): Promise<number>;
+}
+/**
+ * SystemStatsRepository - Interface for managing global system metrics.
+ */
+export interface SystemStatsRepository {
+    /**
+     * Increments the total storage counter.
+     */
+    incrementStorage(bytes: number): Promise<void>;
+    /**
+     * Decrements the total storage counter.
+     */
+    decrementStorage(bytes: number): Promise<void>;
+    /**
+     * Sets a specific value for a storage stat (e.g. after a full sync).
+     */
+    setStorage(bytes: number): Promise<void>;
+    /**
+     * Gets the current total storage usage in bytes.
+     */
+    getStorageUsage(): Promise<number>;
+}
+//# sourceMappingURL=media.repository.d.ts.map

package/dist/media.repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media.repository.d.ts","sourceRoot":"","sources":["../src/media.repository.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnE;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAEnD;;OAEG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpC;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,WAAW,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEnG;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/C;;OAEG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/C;;OAEG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzC;;OAEG;IACH,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACpC"}

package/dist/media.repository.js

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+export {};