nucleus-core-ts 0.9.751 → 0.9.752

package/dist/src/ElysiaPlugin/index.d.ts

@@ -16,7 +16,7 @@ export { createPaymentRoutes } from './routes/payment';
 export { createMarketplaceRoutes, type MarketplaceRouteConfig } from './routes/payment/marketplace';
 export type { ClientManager, PubSubRouteConfig } from './routes/pubsub';
 export { createPubSubRoutes } from './routes/pubsub';
-export { createCdnRoutes, mergeCdnConfig, mergeStorageConfig, } from './routes/storage';
+export { createCdnRoutes, mergeCdnConfig, mergeStorageConfig, mergeTransformConfig, mergeVideoConfig, } from './routes/storage';
 export type { ProvisionTenantBody, ProvisionTenantResponse, TenantRouteConfig, } from './routes/tenant';
 export { createTenantRoutes } from './routes/tenant';
 export { createSwaggerPlugin, type NucleusSwaggerConfig } from './swagger';

package/dist/src/ElysiaPlugin/routes/chat/types.d.ts

@@ -3,6 +3,7 @@ import type { ChatConfig, ChatService, RealtimeBroadcaster } from 'src/Services/
 import type { Logger } from 'src/Services/Logger';
 import type { TenantRegistry } from 'src/Services/Tenant';
 import type { StorageConfig } from '../storage';
+import type { CdnMediaConfig } from '../storage/mediaPostProcess';
 /** Public configuration accepted by {@link createChatRoutes}. */
 export type ChatRoutesConfig = {
     db: NodePgDatabase;
@@ -14,6 +15,8 @@ export type ChatRoutesConfig = {
     storageConfig: StorageConfig;
     attachmentsAvailable: boolean;
     cdnBasePath: string;
+    /** Resolved CDN transform/video config so uploaded media can be warmed/transcoded (fire-and-forget). */
+    cdnMedia?: CdnMediaConfig;
 };
 /** Per-request resolved service plus the tenant schema tables it was built on. */
 export type ResolvedChatService = {
@@ -28,4 +31,5 @@ export type ChatRouteDeps = {
     storageConfig: StorageConfig;
     attachmentsAvailable: boolean;
     getService: (request: Request) => ResolvedChatService;
+    cdnMedia?: CdnMediaConfig;
 };

package/dist/src/ElysiaPlugin/routes/storage/cdn.d.ts

@@ -1,5 +1,7 @@
 import Elysia from 'elysia';
 import type { Logger } from '../../../Services/Logger';
+import { type TransformConfig, type TransformConfigInput } from './imageTransform';
+import { type VideoConfig } from './videoTransform';
 export interface CdnConfig {
     enabled: boolean;
     basePath: string;
@@ -7,6 +9,19 @@ export interface CdnConfig {
     enableRangeRequests: boolean;
     enableEtag: boolean;
     corsOrigins: string[];
+    transform: TransformConfig;
+    video: VideoConfig;
+}
+/** Raw (deep-partial) shape accepted from config.storage.cdn. */
+export interface CdnConfigInput {
+    enabled?: boolean;
+    basePath?: string;
+    cacheMaxAge?: number;
+    enableRangeRequests?: boolean;
+    enableEtag?: boolean;
+    corsOrigins?: string[];
+    transform?: TransformConfigInput;
+    video?: Partial<VideoConfig>;
 }
 export interface CdnRoutesConfig {
     cdn: CdnConfig;
@@ -19,7 +34,7 @@ export interface CdnRoutesConfig {
         mime_type: string;
     } | null>;
 }
-export declare function mergeCdnConfig(config?: Partial<CdnConfig>): CdnConfig;
+export declare function mergeCdnConfig(config?: CdnConfigInput): CdnConfig;
 export declare function createCdnRoutes(config: CdnRoutesConfig): Elysia<string, {
     decorator: {};
     store: {};

package/dist/src/ElysiaPlugin/routes/storage/imageTransform.d.ts

@@ -0,0 +1,75 @@
+import type { Logger } from '../../../Services/Logger';
+/** Formats a client may request via `?format=`. */
+export type TransformFormat = 'webp' | 'avif' | 'jpeg' | 'png';
+export interface PregenerateConfig {
+    enabled: boolean;
+    widths: number[];
+    formats: TransformFormat[];
+    quality?: number;
+}
+export interface TransformConfig {
+    enabled: boolean;
+    maxWidth: number;
+    maxHeight: number;
+    defaultQuality: number;
+    allowedFormats: TransformFormat[];
+    cacheSubdir: string;
+    maxInputPixels: number;
+    pregenerate: PregenerateConfig;
+}
+/** Raw (deep-partial) shape accepted from config.storage.cdn.transform. */
+export type TransformConfigInput = Partial<Omit<TransformConfig, 'pregenerate'>> & {
+    pregenerate?: Partial<PregenerateConfig>;
+};
+export declare function mergeTransformConfig(config?: TransformConfigInput | undefined): TransformConfig;
+export interface TransformParams {
+    width?: number;
+    height?: number;
+    quality: number;
+    /** Requested output format, or undefined to keep the source format. */
+    format?: TransformFormat;
+}
+/**
+ * True only for raster images we can safely transform. SVG is deliberately excluded — it is served
+ * as a download (stored-XSS defence) and rasterizing untrusted SVG is an SSRF/bomb vector.
+ */
+export declare function isTransformableImage(mimeType: string): boolean;
+/**
+ * Parse `?w=&h=&q=&format=` into a normalized, CLAMPED transform request. Returns null when no
+ * transform is requested (no w/h/q/format), so the caller serves the original bytes untouched.
+ */
+export declare function parseTransformParams(query: Record<string, string | undefined>, config: TransformConfig): TransformParams | null;
+/** Short, filesystem-safe cache key folding in every input that changes the output. */
+export declare function deriveCacheKey(mtimeMs: number, params: TransformParams, outputFormat: TransformFormat): string;
+export interface EnsureDerivativeArgs {
+    sourcePath: string;
+    mimeType: string;
+    params: TransformParams;
+    storagePath: string;
+    config: TransformConfig;
+    logger: Logger;
+}
+/**
+ * Produce (and cache on disk) a transformed image derivative and return its path + content-type +
+ * etag, so the caller can stream it exactly like an original file. Returns null on ANY failure
+ * (sharp missing, non-transformable type, decode error) so the caller falls back to the original —
+ * a broken transform must never break file serving.
+ */
+export declare function ensureDerivative(args: EnsureDerivativeArgs): Promise<{
+    path: string;
+    contentType: string;
+    etag: string;
+} | null>;
+/**
+ * Pre-generate the configured image variants into the SAME derivative cache the on-the-fly path reads,
+ * so the first `?w=&format=` request is already a cache hit. Best-effort: each variant is independent and
+ * any failure is swallowed (logged inside ensureDerivative). Intended to be called fire-and-forget right
+ * after an image is persisted on upload. Returns the number of variants successfully generated/present.
+ */
+export declare function pregenerateImageVariants(args: {
+    sourcePath: string;
+    mimeType: string;
+    storagePath: string;
+    config: TransformConfig;
+    logger: Logger;
+}): Promise<number>;

package/dist/src/ElysiaPlugin/routes/storage/imageTransform.test.d.ts

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

package/dist/src/ElysiaPlugin/routes/storage/index.d.ts

@@ -1,3 +1,6 @@
 export { type CdnConfig, type CdnRoutesConfig, createCdnRoutes, mergeCdnConfig, } from './cdn';
 export { buildFileRecordPayload, type PersistedFile, persistUploadedFiles, } from './file-record';
+export { type CdnMediaConfig, scheduleUploadMediaProcessing, } from './mediaPostProcess';
+export { mergeTransformConfig, type TransformConfig, } from './imageTransform';
+export { mergeVideoConfig, type VideoConfig, } from './videoTransform';
 export { deleteFile, type FileUploadResult, type FormDataParseResult, mergeStorageConfig, parseFormDataBody, type StorageConfig, type StorageConfigInput, uploadFile, uploadFiles, validateFile, } from './helpers';

package/dist/src/ElysiaPlugin/routes/storage/mediaPostProcess.d.ts

@@ -0,0 +1,20 @@
+import type { Logger } from '../../../Services/Logger';
+import type { PersistedFile } from './file-record';
+import { type TransformConfig } from './imageTransform';
+import { type VideoConfig } from './videoTransform';
+/** The resolved CDN media config needed to warm/transcode uploads. */
+export interface CdnMediaConfig {
+    transform: TransformConfig;
+    video: VideoConfig;
+}
+/**
+ * Schedule post-upload media processing for freshly-persisted files — FIRE-AND-FORGET. For each record:
+ * pre-generate the configured image variants (into the on-the-fly derivative cache) and/or kick off an
+ * ffmpeg video transcode + poster. Never awaited by the caller, never throws — a failed or slow transform
+ * must never affect the upload response. Both steps are individually gated by their config `enabled` flags.
+ */
+export declare function scheduleUploadMediaProcessing(records: PersistedFile[], opts: {
+    storagePath: string;
+    media: CdnMediaConfig;
+    logger: Logger;
+}): void;

package/dist/src/ElysiaPlugin/routes/storage/videoTransform.d.ts

@@ -0,0 +1,39 @@
+import type { Logger } from '../../../Services/Logger';
+export interface VideoConfig {
+    enabled: boolean;
+    transcode: boolean;
+    poster: boolean;
+    posterFormat: 'jpeg' | 'webp';
+    crf: number;
+    maxWidth: number;
+    ffmpegPath: string;
+}
+export declare function mergeVideoConfig(config?: Partial<VideoConfig> | undefined): VideoConfig;
+export declare function isTransformableVideo(mimeType: string): boolean;
+/**
+ * Serve-side: return the ready web-optimized MP4 (or poster) derivative for a source video, or null if
+ * it hasn't been generated yet (→ the caller serves the original). `kind: 'poster'` returns the poster.
+ */
+export declare function resolveVideoVariant(args: {
+    sourcePath: string;
+    storagePath: string;
+    cacheSubdir: string;
+    posterFormat: VideoConfig['posterFormat'];
+    kind: 'web' | 'poster';
+}): Promise<{
+    path: string;
+    contentType: string;
+} | null>;
+/**
+ * Upload-side: transcode a just-uploaded video to a web-optimized MP4 (+ poster frame) via ffmpeg.
+ * Best-effort and NON-BLOCKING — intended to be fired-and-forgotten (the caller does not await). All
+ * failures are swallowed/logged; a missing ffmpeg just leaves the original to be served as-is.
+ */
+export declare function processVideoOnUpload(args: {
+    sourcePath: string;
+    mimeType: string;
+    storagePath: string;
+    cacheSubdir: string;
+    config: VideoConfig;
+    logger: Logger;
+}): Promise<void>;

package/dist/src/ElysiaPlugin/routes/storage/videoTransform.test.d.ts

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

package/dist/src/types.d.ts

@@ -1098,6 +1098,69 @@ export interface NucleusConfigOptions {
             enableRangeRequests?: boolean;
             enableEtag?: boolean;
             corsOrigins?: string[];
+            /**
+             * On-the-fly IMAGE resize/compress/re-encode at the serve endpoint, so a frontend can point
+             * `<img>` / `next/image` (with its own optimizer disabled) at `/cdn/{id}?w=800&q=80&format=webp`
+             * and get a resized, compressed, browser-cached derivative. Requires the optional `sharp` peer
+             * dependency (`npm i sharp`); when enabled but sharp is missing, the CDN logs an error and serves
+             * the ORIGINAL bytes (never 500s). Only raster images are transformed — SVG (served as a download),
+             * video, and other types are streamed untouched.
+             */
+            transform?: {
+                /** Enable on-the-fly image transforms. Default false (opt-in — needs `sharp`). */
+                enabled?: boolean;
+                /** Clamp requested width/height so a caller can't force a huge allocation. Defaults 3840. */
+                maxWidth?: number;
+                maxHeight?: number;
+                /** Output quality (1-100) applied when `?q=` is omitted. Default 80. */
+                defaultQuality?: number;
+                /**
+                 * Formats a client may request via `?format=`. When `?format=` is omitted the source format is
+                 * kept (still resized/re-compressed). Default ['webp', 'avif', 'jpeg', 'png'].
+                 */
+                allowedFormats?: ('webp' | 'avif' | 'jpeg' | 'png')[];
+                /** Subdirectory under storage.basePath where generated derivatives are cached. Default '.cache/cdn'. */
+                cacheSubdir?: string;
+                /** Max source pixels sharp will decode — decompression-bomb guard. Default 100000000 (100 MP). */
+                maxInputPixels?: number;
+                /**
+                 * On upload, PRE-GENERATE these image variants (into the same derivative cache the on-the-fly
+                 * path reads) so the first request is already fast. Best-effort + non-blocking.
+                 */
+                pregenerate?: {
+                    /** Default false. Requires transform.enabled + `sharp`. */
+                    enabled?: boolean;
+                    /** Widths to pre-render, e.g. [400, 800, 1200]. Default []. */
+                    widths?: number[];
+                    /** Formats to pre-render, e.g. ['webp']. Default ['webp']. */
+                    formats?: ('webp' | 'avif' | 'jpeg' | 'png')[];
+                    /** Encode quality for the pre-rendered variants. Default = transform.defaultQuality. */
+                    quality?: number;
+                };
+            };
+            /**
+             * VIDEO optimization on upload (opt-in; requires an `ffmpeg` binary on PATH). On upload of a video the
+             * CDN spawns ffmpeg (fire-and-forget) to produce a web-optimized MP4 (H.264 + faststart, optionally
+             * downscaled) and/or a poster frame, cached beside the image derivatives. The transcoded MP4 is then
+             * served at `/cdn/{id}` (range-streamed) once ready; until then the ORIGINAL is served. The poster is
+             * served at `/cdn/{id}?poster=1`. Per-request transcoding is NOT done (too heavy) — only on upload.
+             */
+            video?: {
+                /** Default false. Requires an ffmpeg binary. */
+                enabled?: boolean;
+                /** Transcode uploaded videos to a web-optimized MP4 (H.264 + +faststart). Default true when video.enabled. */
+                transcode?: boolean;
+                /** Extract a poster frame served at ?poster=1. Default true when video.enabled. */
+                poster?: boolean;
+                /** Poster image format. Default 'jpeg'. */
+                posterFormat?: 'jpeg' | 'webp';
+                /** H.264 CRF (0-51, lower = better/bigger). Default 23. */
+                crf?: number;
+                /** Downscale the transcoded video so its width never exceeds this. Default 1920. */
+                maxWidth?: number;
+                /** ffmpeg executable (name on PATH or absolute path). Default 'ffmpeg'. */
+                ffmpegPath?: string;
+            };
         };
         formData?: {
             filesField?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "nucleus-core-ts",
-	"version": "0.9.751",
+	"version": "0.9.752",
 	"description": "Production-ready, enterprise-grade TypeScript framework for building multi-tenant APIs",
 	"author": "Hidayet Can Özcan <hidayetcan@gmail.com>",
 	"license": "SEE LICENSE IN LICENSE",
@@ -51,7 +51,7 @@
 		"test": "bun test src",
 		"build": "bun run scripts/build.ts",
 		"build:quick": "bun run build:js && bun run build:types",
-		"build:js": "bun build ./index.ts ./client.ts ./fe/index.ts ./src/Client/Proxy/index.ts --outdir=dist --target=bun --format=esm --splitting --minify --external react --external react-dom --external gsap --external @gsap/react --external h-state --external three --external @react-three/fiber --external elysia --external drizzle-orm --external drizzle-kit --external ioredis --external googleapis --external @dapr/dapr --external pg --external @xyflow/react --external @xyflow/system --external @azure/communication-email --external @azure/identity --external stripe",
+		"build:js": "bun build ./index.ts ./client.ts ./fe/index.ts ./src/Client/Proxy/index.ts --outdir=dist --target=bun --format=esm --splitting --minify --external react --external react-dom --external gsap --external @gsap/react --external h-state --external three --external @react-three/fiber --external elysia --external drizzle-orm --external drizzle-kit --external ioredis --external googleapis --external @dapr/dapr --external pg --external @xyflow/react --external @xyflow/system --external @azure/communication-email --external @azure/identity --external stripe --external sharp",
 		"build:types": "tsc --declaration --emitDeclarationOnly --outDir dist --skipLibCheck",
 		"version:patch": "bun run scripts/version.ts patch",
 		"version:minor": "bun run scripts/version.ts minor",
@@ -110,6 +110,7 @@
 	},
 	"optionalDependencies": {
 		"@azure/communication-email": "latest",
+		"sharp": "^0.33.0",
 		"stripe": "latest"
 	}
 }

package/schemas/config.nucleus.json

@@ -504,6 +504,49 @@
             },
             "approvalRedirectUrl": {
               "type": "string"
+            },
+            "deviceTrust": {
+              "type": "object",
+              "properties": {
+                "enabled": {
+                  "type": "boolean"
+                },
+                "tokenExpiresIn": {
+                  "type": "string"
+                },
+                "cookieName": {
+                  "type": "string"
+                },
+                "cookiePrefix": {
+                  "type": "string",
+                  "enum": [
+                    "",
+                    "__Secure-",
+                    "__Host-"
+                  ]
+                },
+                "sameSite": {
+                  "type": "string",
+                  "enum": [
+                    "Strict",
+                    "Lax"
+                  ]
+                },
+                "onUnidentifiable": {
+                  "type": "string",
+                  "enum": [
+                    "require_approval",
+                    "deny"
+                  ]
+                },
+                "approvalMethods": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "description": "Remembered-device trust (opt-in). Server-issued hashed device token replaces the spoofable UA fingerprint as the \"known device\" anchor for new-device approval. Never replaces authentication. See docs/superpowers/specs/2026-07-07-device-trust-design.md."
             }
           },
           "required": [
@@ -1132,7 +1175,8 @@
           "type": "array",
           "items": {
             "type": "string"
-          }
+          },
+          "description": "Use `publicPaths` to make a path public. Kept for config back-compat only."
         },
         "publicPaths": {
           "type": "array",
@@ -1224,6 +1268,92 @@
             }
           },
           "description": "Project-specific seed data for roles, claims, and role-claim assignments. Runs AFTER autoSeedClaims (entity-based) and godmin setup. Idempotent — existing items are skipped, only missing ones are created/assigned."
+        },
+        "endpointDiscovery": {
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "type": "boolean"
+            },
+            "runOnBoot": {
+              "type": "boolean",
+              "description": "Run discovery at boot (default true when enabled)."
+            },
+            "services": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "id": {
+                    "type": "string",
+                    "description": "Stable prefix for this service's claim actions (e.g. \"agent\")."
+                  },
+                  "baseUrl": {
+                    "type": "string",
+                    "description": "Base URL reachable from the IDP (e.g. \"http://vorion-agent:8000\")."
+                  },
+                  "openapi": {
+                    "type": "string",
+                    "description": "OpenAPI document path (default \"/openapi.json\")."
+                  },
+                  "exclude": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Path globs to skip, e.g. [\"/health\",\"/api/v1/internal/*\"]."
+                  }
+                },
+                "required": [
+                  "id",
+                  "baseUrl"
+                ]
+              }
+            },
+            "trigger": {
+              "type": "object",
+              "properties": {
+                "enabled": {
+                  "type": "boolean"
+                },
+                "basePath": {
+                  "type": "string"
+                }
+              },
+              "description": "godmin-only on-demand re-discovery endpoint."
+            },
+            "token": {
+              "type": "string",
+              "description": "Shared secret that lets the reverse proxy fetch `/authorization/route-manifest` without a user session (presented as the `x-discovery-token` header). Godmin callers are always allowed. Falls back to the `NUCLEUS_DISCOVERY_TOKEN` env."
+            }
+          },
+          "description": "Auto-discover the endpoints of EXTERNAL (non-nucleus) services from their OpenAPI documents and seed a claim per endpoint, so a nucleus IDP can protect 500+ routes across other services (e.g. FastAPI) with the same role/claim model without hand-writing claims. Full (IDP) mode only. Discovered claim actions are `{serviceId}.{tag}.{operationId}` (idempotent on action; removed endpoints are DEACTIVATED, not deleted). Enforcement happens at the reverse proxy via `HttpProxyTarget.authorize` (see nucleus-core-ts/proxy) consuming the `/authorization/route-manifest` this produces. `serviceId` must not be an HTTP-method word (get/post/put/…)."
+        },
+        "claimGuards": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string",
+                "description": "Key template, e.g. `token_spent_today:{userId}` or a global `feature_flag_x`."
+              },
+              "value": {
+                "type": "string",
+                "enum": [
+                  "int",
+                  "boolean",
+                  "string"
+                ],
+                "description": "Declared value type: drives parsing, valid operators, and threshold parsing."
+              }
+            },
+            "required": [
+              "name",
+              "value"
+            ]
+          },
+          "description": "ClaimGuards — generic, config-driven claim invalidation. Each entry defines a comparable key in the shared Redis/Dapr state and seeds a claim (action = the name up to the first `{`). At assignment time godmin attaches a condition to the guard-claim and selects the claims to invalidate when it holds (`role_claims.scope` JSON `{op,value,invalidates}`); at runtime nucleus reads the key, evaluates the condition, and drops the listed claims. The APP writes the key values. nucleus names no metric/endpoint/window — in Vorion this surfaces as a quota. See docs/specs/2026-07-04-claim-guards-design.md."
         }
       }
     },
@@ -1782,10 +1912,18 @@
           "type": "string",
           "description": "Dapr pubsub component name (default: \"pubsub-redis\")"
         },
+        "daprApiToken": {
+          "type": "string",
+          "description": "Shared secret Dapr presents as the `dapr-api-token` header when POSTing a delivered message to the subscription endpoint. REQUIRED to secure that endpoint — without it (and without the APP_API_TOKEN/DAPR_API_TOKEN env fallback) any caller reaching the route can inject realtime events to any user. Falls back to env APP_API_TOKEN, then DAPR_API_TOKEN."
+        },
         "maxClientsPerUser": {
           "type": "number",
           "description": "Max clients per user (default: 10)"
         },
+        "maxTopicsPerClient": {
+          "type": "number",
+          "description": "Max distinct topics a single client may subscribe to (default: 64). Bounds the in-memory subscription Set against an attacker-controlled `topics` array (memory-exhaustion DoS)."
+        },
         "wsIdleTimeout": {
           "type": "number",
           "description": "WebSocket idle timeout in seconds (default: 120)"
@@ -1877,6 +2015,120 @@
               "items": {
                 "type": "string"
               }
+            },
+            "transform": {
+              "type": "object",
+              "properties": {
+                "enabled": {
+                  "type": "boolean",
+                  "description": "Enable on-the-fly image transforms. Default false (opt-in — needs `sharp`)."
+                },
+                "maxWidth": {
+                  "type": "number",
+                  "description": "Clamp requested width/height so a caller can't force a huge allocation. Defaults 3840."
+                },
+                "maxHeight": {
+                  "type": "number"
+                },
+                "defaultQuality": {
+                  "type": "number",
+                  "description": "Output quality (1-100) applied when `?q=` is omitted. Default 80."
+                },
+                "allowedFormats": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "enum": [
+                      "webp",
+                      "avif",
+                      "jpeg",
+                      "png"
+                    ]
+                  },
+                  "description": "Formats a client may request via `?format=`. When `?format=` is omitted the source format is kept (still resized/re-compressed). Default ['webp', 'avif', 'jpeg', 'png']."
+                },
+                "cacheSubdir": {
+                  "type": "string",
+                  "description": "Subdirectory under storage.basePath where generated derivatives are cached. Default '.cache/cdn'."
+                },
+                "maxInputPixels": {
+                  "type": "number",
+                  "description": "Max source pixels sharp will decode — decompression-bomb guard. Default 100000000 (100 MP)."
+                },
+                "pregenerate": {
+                  "type": "object",
+                  "properties": {
+                    "enabled": {
+                      "type": "boolean",
+                      "description": "Default false. Requires transform.enabled + `sharp`."
+                    },
+                    "widths": {
+                      "type": "array",
+                      "items": {
+                        "type": "number"
+                      },
+                      "description": "Widths to pre-render, e.g. [400, 800, 1200]. Default []."
+                    },
+                    "formats": {
+                      "type": "array",
+                      "items": {
+                        "type": "string",
+                        "enum": [
+                          "webp",
+                          "avif",
+                          "jpeg",
+                          "png"
+                        ]
+                      },
+                      "description": "Formats to pre-render, e.g. ['webp']. Default ['webp']."
+                    },
+                    "quality": {
+                      "type": "number",
+                      "description": "Encode quality for the pre-rendered variants. Default = transform.defaultQuality."
+                    }
+                  },
+                  "description": "On upload, PRE-GENERATE these image variants (into the same derivative cache the on-the-fly path reads) so the first request is already fast. Best-effort + non-blocking."
+                }
+              },
+              "description": "On-the-fly IMAGE resize/compress/re-encode at the serve endpoint, so a frontend can point `<img>` / `next/image` (with its own optimizer disabled) at `/cdn/{id}?w=800&q=80&format=webp` and get a resized, compressed, browser-cached derivative. Requires the optional `sharp` peer dependency (`npm i sharp`); when enabled but sharp is missing, the CDN logs an error and serves the ORIGINAL bytes (never 500s). Only raster images are transformed — SVG (served as a download), video, and other types are streamed untouched."
+            },
+            "video": {
+              "type": "object",
+              "properties": {
+                "enabled": {
+                  "type": "boolean",
+                  "description": "Default false. Requires an ffmpeg binary."
+                },
+                "transcode": {
+                  "type": "boolean",
+                  "description": "Transcode uploaded videos to a web-optimized MP4 (H.264 + +faststart). Default true when video.enabled."
+                },
+                "poster": {
+                  "type": "boolean",
+                  "description": "Extract a poster frame served at ?poster=1. Default true when video.enabled."
+                },
+                "posterFormat": {
+                  "type": "string",
+                  "enum": [
+                    "jpeg",
+                    "webp"
+                  ],
+                  "description": "Poster image format. Default 'jpeg'."
+                },
+                "crf": {
+                  "type": "number",
+                  "description": "H.264 CRF (0-51, lower = better/bigger). Default 23."
+                },
+                "maxWidth": {
+                  "type": "number",
+                  "description": "Downscale the transcoded video so its width never exceeds this. Default 1920."
+                },
+                "ffmpegPath": {
+                  "type": "string",
+                  "description": "ffmpeg executable (name on PATH or absolute path). Default 'ffmpeg'."
+                }
+              },
+              "description": "VIDEO optimization on upload (opt-in; requires an `ffmpeg` binary on PATH). On upload of a video the CDN spawns ffmpeg (fire-and-forget) to produce a web-optimized MP4 (H.264 + faststart, optionally downscaled) and/or a poster frame, cached beside the image derivatives. The transcoded MP4 is then served at `/cdn/{id}` (range-streamed) once ready; until then the ORIGINAL is served. The poster is served at `/cdn/{id}?poster=1`. Per-request transcoding is NOT done (too heavy) — only on upload."
             }
           }
         },