@vgai/editor 0.2.0

package/server/asset-library-routes.ts

@@ -0,0 +1,833 @@
+/**
+ * Asset Library — server proxy routes for browsing and downloading
+ * CC0 assets from Poly Haven and ambientCG.
+ *
+ * Mounted as an Express Router under /__editor/asset-library/*.
+ * Proxies external API calls (avoids CORS) and streams downloads
+ * into the project's public/asset-library/ directory.
+ */
+
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { createWriteStream } from 'node:fs';
+import { copyFile, mkdir, readdir, stat, unlink, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, relative } from 'node:path';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import type { Router } from 'express';
+import express from 'express';
+import {
+  cloudAssetObjectUrl,
+  findCloudAsset,
+  loadCloudAssetManifest,
+  parseCloudAssetObjectUrl,
+} from './cloud-asset-catalog';
+import { broadcast } from './editor-sse';
+import {
+  findLocalAsset,
+  getLocalAssetLibraryRoot,
+  loadLocalAssetCatalog,
+  localAssetMatchesType,
+  localAssetSlug,
+  resolveCatalogFile,
+  searchLocalCatalog,
+} from './local-asset-catalog';
+import { isAllowedAssetHost, isAllowedAssetSource, isPathInside } from './server-utils';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface OnlineAsset {
+  id: string;
+  source: 'polyhaven' | 'ambientcg' | 'local';
+  name: string;
+  type: 'model' | 'animation' | 'source' | 'hdri' | 'texture' | 'material';
+  thumbnailUrl: string;
+  categories: string[];
+  tags: string[];
+  downloadCount?: number;
+  license?: string;
+  author?: string;
+  sourceUrl?: string;
+  cloudHosted?: boolean;
+}
+
+interface AssetFileOption {
+  label: string;
+  format: string;
+  url: string;
+  sizeBytes?: number;
+  /** Additional files that must be downloaded alongside the main URL (GLTF includes). */
+  includes?: { relativePath: string; url: string; size: number }[];
+}
+
+// ---------------------------------------------------------------------------
+// In-memory cache with TTL
+// ---------------------------------------------------------------------------
+
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+interface CacheEntry<T> {
+  data: T;
+  timestamp: number;
+}
+
+const cache = new Map<string, CacheEntry<unknown>>();
+
+function getCached<T>(key: string): T | null {
+  const entry = cache.get(key);
+  if (!entry) return null;
+  if (Date.now() - entry.timestamp > CACHE_TTL_MS) {
+    cache.delete(key);
+    return null;
+  }
+  return entry.data as T;
+}
+
+function setCache<T>(key: string, data: T): void {
+  cache.set(key, { data, timestamp: Date.now() });
+}
+
+// ---------------------------------------------------------------------------
+// Poly Haven helpers
+// ---------------------------------------------------------------------------
+
+const PH_HEADERS = { 'User-Agent': 'VGAI-Engine/1.0' };
+
+/** Map Poly Haven asset type strings to our unified types. */
+function phTypeToUnified(phType: string): OnlineAsset['type'] {
+  if (phType === 'hdris') return 'hdri';
+  if (phType === 'textures') return 'texture';
+  return 'model';
+}
+
+interface PHAssetEntry {
+  name: string;
+  type: number; // 0=hdri, 1=texture, 2=model — but we use the query type
+  categories: string[];
+  tags: string[];
+  thumbnail_url?: string;
+  download_count?: number;
+}
+
+async function searchPolyHaven(
+  type: string,
+  category?: string,
+): Promise<{ assets: OnlineAsset[]; total: number }> {
+  const cacheKey = `ph:${type}:${category ?? ''}`;
+  const cached = getCached<{ assets: OnlineAsset[]; total: number }>(cacheKey);
+  if (cached) return cached;
+
+  let url = `https://api.polyhaven.com/assets?type=${type}`;
+  if (category) url += `&categories=${category}`;
+
+  const res = await fetch(url, { headers: PH_HEADERS });
+  if (!res.ok) throw new Error(`Poly Haven API error: ${res.status}`);
+
+  const data = (await res.json()) as Record<string, PHAssetEntry>;
+  const assets: OnlineAsset[] = Object.entries(data).map(([id, entry]) => ({
+    id,
+    source: 'polyhaven' as const,
+    name: entry.name,
+    type: phTypeToUnified(type),
+    thumbnailUrl: `https://cdn.polyhaven.com/asset_img/thumbs/${id}.png?width=256`,
+    categories: entry.categories ?? [],
+    tags: entry.tags ?? [],
+    ...(entry.download_count != null ? { downloadCount: entry.download_count } : {}),
+  }));
+
+  const result = { assets, total: assets.length };
+  setCache(cacheKey, result);
+  return result;
+}
+
+interface PHFileInfo {
+  url: string;
+  size: number;
+  md5?: string;
+  include?: Record<string, { url: string; size: number }>;
+}
+
+type PHFilesResponse = Record<string, Record<string, Record<string, PHFileInfo>>>;
+
+async function getPolyHavenFiles(id: string): Promise<AssetFileOption[]> {
+  const cacheKey = `ph-files:${id}`;
+  const cached = getCached<AssetFileOption[]>(cacheKey);
+  if (cached) return cached;
+
+  const res = await fetch(`https://api.polyhaven.com/files/${id}`, { headers: PH_HEADERS });
+  if (!res.ok) throw new Error(`Poly Haven files API error: ${res.status}`);
+
+  const data = (await res.json()) as PHFilesResponse;
+  const files: AssetFileOption[] = [];
+
+  // Models: GLTF with included files (bin + textures)
+  if (data['gltf']) {
+    for (const [resolution, formats] of Object.entries(data['gltf'])) {
+      const gltfInfo = formats['gltf'];
+      if (!gltfInfo) continue;
+
+      const includes: { relativePath: string; url: string; size: number }[] = [];
+      let totalSize = gltfInfo.size;
+
+      if (gltfInfo.include) {
+        for (const [relPath, fileInfo] of Object.entries(gltfInfo.include)) {
+          includes.push({ relativePath: relPath, url: fileInfo.url, size: fileInfo.size });
+          totalSize += fileInfo.size;
+        }
+      }
+
+      const entry: AssetFileOption = {
+        label: `GLTF ${resolution}`,
+        format: 'gltf',
+        url: gltfInfo.url,
+        sizeBytes: totalSize,
+      };
+      if (includes.length > 0) entry.includes = includes;
+      files.push(entry);
+    }
+  }
+
+  // HDRIs
+  if (data['hdri']) {
+    for (const [resolution, formats] of Object.entries(data['hdri'])) {
+      for (const [fmt, info] of Object.entries(formats)) {
+        files.push({
+          label: `${fmt.toUpperCase()} ${resolution}`,
+          format: fmt,
+          url: info.url,
+          sizeBytes: info.size,
+        });
+      }
+    }
+  }
+
+  setCache(cacheKey, files);
+  return files;
+}
+
+// ---------------------------------------------------------------------------
+// ambientCG helpers
+// ---------------------------------------------------------------------------
+
+interface ACGAsset {
+  assetId: string;
+  displayName: string;
+  dataType: string;
+  tags: string[];
+  previewImage?: { [key: string]: string };
+  downloadFolders?: Record<
+    string,
+    {
+      downloadFiletypeCategories: Record<
+        string,
+        {
+          downloads: Array<{
+            attribute: string;
+            downloadLink: string;
+            zipContent?: string[];
+            fileSizeInBytes?: number;
+            fileName?: string;
+          }>;
+        }
+      >;
+    }
+  >;
+}
+
+interface ACGResponse {
+  foundAssets: ACGAsset[];
+  numberOfResults: number;
+}
+
+function acgTypeParam(type: string): string {
+  // ambientCG types: Material, HDRI, etc.
+  if (type === 'materials') return 'Material';
+  if (type === 'hdris') return 'HDRI';
+  return type;
+}
+
+async function searchAmbientCG(
+  type: string,
+  q?: string,
+  offset = 0,
+  limit = 48,
+): Promise<{ assets: OnlineAsset[]; total: number }> {
+  const cacheKey = `acg:${type}:${q ?? ''}:${offset}:${limit}`;
+  const cached = getCached<{ assets: OnlineAsset[]; total: number }>(cacheKey);
+  if (cached) return cached;
+
+  const params = new URLSearchParams({
+    type: acgTypeParam(type),
+    limit: String(limit),
+    offset: String(offset),
+    include: 'previewData,downloadData,tagData',
+    sort: 'Popular',
+  });
+  if (q) params.set('q', q);
+
+  const res = await fetch(`https://ambientcg.com/api/v2/full_json?${params}`);
+  if (!res.ok) throw new Error(`ambientCG API error: ${res.status}`);
+
+  const data = (await res.json()) as ACGResponse;
+  const assets: OnlineAsset[] = data.foundAssets.map((a) => ({
+    id: a.assetId,
+    source: 'ambientcg' as const,
+    name: a.displayName,
+    type: type === 'hdris' ? ('hdri' as const) : ('material' as const),
+    thumbnailUrl: a.previewImage?.['256-PNG'] ?? '',
+    categories: [],
+    tags: a.tags ?? [],
+  }));
+
+  // Cache raw data for file extraction later
+  for (const a of data.foundAssets) {
+    setCache(`acg-raw:${a.assetId}`, a);
+  }
+
+  const result = { assets, total: data.numberOfResults };
+  setCache(cacheKey, result);
+  return result;
+}
+
+function getAmbientCGFiles(id: string): AssetFileOption[] {
+  const raw = getCached<ACGAsset>(`acg-raw:${id}`);
+  if (!raw || !raw.downloadFolders) return [];
+
+  const files: AssetFileOption[] = [];
+  for (const folder of Object.values(raw.downloadFolders)) {
+    for (const [_category, cat] of Object.entries(folder.downloadFiletypeCategories)) {
+      for (const dl of cat.downloads) {
+        const entry: AssetFileOption = {
+          label: dl.attribute || dl.fileName || 'Download',
+          format: dl.downloadLink.endsWith('.zip') ? 'zip' : 'unknown',
+          url: dl.downloadLink,
+        };
+        if (dl.fileSizeInBytes != null) entry.sizeBytes = dl.fileSizeInBytes;
+        files.push(entry);
+      }
+    }
+  }
+  return files;
+}
+
+// ---------------------------------------------------------------------------
+// Router factory
+// ---------------------------------------------------------------------------
+
+export function createAssetLibraryRouter(getPublicRoot: () => string): Router {
+  const router = express.Router();
+  router.use(express.json());
+
+  // ---- Search ----
+  router.get('/search', async (req, res) => {
+    const source = req.query['source'] as string;
+    const type = req.query['type'] as string;
+    const q = (req.query['q'] as string) ?? '';
+    const category = req.query['category'] as string | undefined;
+    const offset = Number.parseInt((req.query['offset'] as string) ?? '0', 10);
+    const limit = Number.parseInt((req.query['limit'] as string) ?? '48', 10);
+
+    if (!source || !type) {
+      res.status(400).json({ error: 'Missing source or type.' });
+      return;
+    }
+
+    try {
+      let result: { assets: OnlineAsset[]; total: number };
+
+      if (source === 'local') {
+        const catalog = await loadLocalAssetCatalog();
+        const cloudManifest = await loadCloudAssetManifest();
+        const cloudIds = new Set(cloudManifest?.assets.map((asset) => asset.id) ?? []);
+        const localResult = searchLocalCatalog(catalog, {
+          q,
+          type,
+          offset,
+          limit,
+          ...(category ? { category } : {}),
+        });
+        result = {
+          total: localResult.total,
+          assets: localResult.assets.map((asset) => ({
+            id: asset.id,
+            source: 'local' as const,
+            name: asset.name,
+            type: asset.type,
+            thumbnailUrl: '/__editor/asset-library/local-placeholder.svg',
+            categories: asset.categories,
+            tags: asset.tags,
+            license: asset.license,
+            author: asset.author,
+            sourceUrl: asset.sourceUrl,
+            cloudHosted: cloudIds.has(asset.id),
+          })),
+        };
+      } else if (source === 'polyhaven') {
+        result = await searchPolyHaven(type, category);
+        // Client-side text filter (PH API doesn't have text search)
+        if (q) {
+          const lower = q.toLowerCase();
+          result = {
+            assets: result.assets.filter(
+              (a) =>
+                a.name.toLowerCase().includes(lower) ||
+                a.tags.some((t) => t.toLowerCase().includes(lower)),
+            ),
+            total: 0, // will be set below
+          };
+          result.total = result.assets.length;
+        }
+        // Manual pagination for PH (returns all at once)
+        result = {
+          assets: result.assets.slice(offset, offset + limit),
+          total: result.total,
+        };
+      } else if (source === 'ambientcg') {
+        result = await searchAmbientCG(type, q || undefined, offset, limit);
+      } else {
+        res.status(400).json({ error: `Unknown source: ${source}` });
+        return;
+      }
+
+      res.json(result);
+    } catch (err) {
+      res.status(502).json({ error: `Upstream API error: ${err}` });
+    }
+  });
+
+  // ---- File options for an asset ----
+  router.get('/files', async (req, res) => {
+    const source = req.query['source'] as string;
+    const id = req.query['id'] as string;
+
+    if (!source || !id) {
+      res.status(400).json({ error: 'Missing source or id.' });
+      return;
+    }
+
+    try {
+      let files: AssetFileOption[];
+
+      if (source === 'local') {
+        const asset = await findLocalAsset(id);
+        const cloudAsset = await findCloudAsset(id);
+        const cloudFiles: AssetFileOption[] =
+          cloudAsset?.files.map((file, index) => ({
+            label: `Cloud · ${file.label}`,
+            format: file.format,
+            url: cloudAssetObjectUrl(id, index),
+            sizeBytes: file.main.sizeBytes,
+            ...(file.dependencies.length > 0
+              ? {
+                  includes: file.dependencies.map((dependency, dependencyIndex) => ({
+                    relativePath: dependency.relativePath,
+                    url: cloudAssetObjectUrl(id, index, dependencyIndex),
+                    size: dependency.sizeBytes,
+                  })),
+                }
+              : {}),
+          })) ?? [];
+        const localFiles = asset
+          ? (
+              await Promise.all(
+                asset.files.map(async (file, index): Promise<AssetFileOption | null> => {
+                  try {
+                    await stat(resolveCatalogFile(getLocalAssetLibraryRoot(), file.path));
+                    return {
+                      label: `SSD · ${file.label}`,
+                      format: file.format,
+                      url: `vgai-local:${asset.id}:${index}`,
+                      sizeBytes: file.sizeBytes,
+                    };
+                  } catch {
+                    return null;
+                  }
+                }),
+              )
+            ).filter((file): file is AssetFileOption => file !== null)
+          : [];
+        files = [...cloudFiles, ...localFiles];
+      } else if (source === 'polyhaven') {
+        files = await getPolyHavenFiles(id);
+      } else if (source === 'ambientcg') {
+        files = getAmbientCGFiles(id);
+        // If not cached, do a fresh search to populate
+        if (files.length === 0) {
+          await searchAmbientCG('materials', id, 0, 1);
+          files = getAmbientCGFiles(id);
+        }
+      } else {
+        res.status(400).json({ error: `Unknown source: ${source}` });
+        return;
+      }
+
+      res.json({ files });
+    } catch (err) {
+      res.status(502).json({ error: `Upstream API error: ${err}` });
+    }
+  });
+
+  // ---- Download ----
+  router.post('/download', async (req, res) => {
+    const body = req.body as {
+      source: string;
+      id: string;
+      name: string;
+      url: string;
+      format: string;
+      includes?: { relativePath: string; url: string; size: number }[];
+    };
+    const { source, id, name, url, format } = body;
+    const includes = body.includes ?? [];
+
+    if (!source || !id || !url) {
+      res.status(400).json({ error: 'Missing required fields.' });
+      return;
+    }
+
+    // S1: only allow known sources — `source` is used as a path segment below.
+    if (!isAllowedAssetSource(source)) {
+      res.status(400).json({ error: `Unknown source: ${source}` });
+      return;
+    }
+
+    if (source === 'local') {
+      try {
+        const asset = await findLocalAsset(id);
+        if (!asset) {
+          res.status(404).json({ error: 'Local asset not found.' });
+          return;
+        }
+        const publicRoot = getPublicRoot();
+        const assetSlug = localAssetSlug(asset);
+        const destDir = join(publicRoot, 'asset-library', 'local', assetSlug);
+        const cloudRoute = parseCloudAssetObjectUrl(url, id);
+        if (cloudRoute && cloudRoute.dependencyIndex === undefined) {
+          const cloudAsset = await findCloudAsset(id);
+          const cloudFile = cloudAsset?.files[cloudRoute.fileIndex];
+          if (!cloudAsset || !cloudFile || cloudAsset.source !== asset.source) {
+            res.status(404).json({ error: 'Cloud asset file not found.' });
+            return;
+          }
+          const mainDestination = join(destDir, cloudFile.main.relativePath);
+          if (!isPathInside(destDir, mainDestination)) {
+            res.status(400).json({ error: 'Invalid cloud asset path.' });
+            return;
+          }
+          await downloadRemoteFile(
+            url,
+            mainDestination,
+            cloudFile.main.sha256,
+            cloudFile.main.sizeBytes,
+          );
+          for (const [dependencyIndex, dependency] of cloudFile.dependencies.entries()) {
+            const destination = join(destDir, dependency.relativePath);
+            if (!isPathInside(destDir, destination)) {
+              res
+                .status(400)
+                .json({ error: `Invalid dependency path: ${dependency.relativePath}` });
+              return;
+            }
+            await downloadRemoteFile(
+              cloudAssetObjectUrl(id, cloudRoute.fileIndex, dependencyIndex),
+              destination,
+              dependency.sha256,
+              dependency.sizeBytes,
+            );
+          }
+          await writeAssetProvenance(destDir, {
+            id: asset.id,
+            name: asset.name,
+            source: asset.source,
+            sourceUrl: asset.sourceUrl,
+            author: asset.author,
+            license: asset.license,
+            delivery: 'cloudflare-r2',
+            attribution: cloudAsset.attribution,
+            sha256: cloudFile.main.sha256,
+          });
+          const resultPath = `asset-library/local/${assetSlug}/${cloudFile.main.relativePath}`;
+          broadcast('assets-changed', {});
+          res.json({ ok: true, path: resultPath });
+          return;
+        }
+
+        const match = url.match(/^vgai-local:([a-f0-9]{24}):(\d+)$/);
+        const selectedFile = match?.[1] === asset.id ? asset.files[Number(match[2])] : undefined;
+        if (!selectedFile) {
+          res.status(404).json({ error: 'Local asset file not found.' });
+          return;
+        }
+        const libraryRoot = getLocalAssetLibraryRoot();
+        const mainSource = resolveCatalogFile(libraryRoot, selectedFile.path);
+        const sourceDirectory = dirname(mainSource);
+        await mkdir(destDir, { recursive: true });
+        await copyFile(mainSource, join(destDir, basename(mainSource)));
+        for (const dependency of selectedFile.dependencies ?? []) {
+          const dependencySource = resolveCatalogFile(libraryRoot, dependency);
+          const dependencyRelative = relative(sourceDirectory, dependencySource);
+          if (dependencyRelative.startsWith('..')) continue;
+          const dependencyDestination = join(destDir, dependencyRelative);
+          await mkdir(dirname(dependencyDestination), { recursive: true });
+          await copyFile(dependencySource, dependencyDestination);
+        }
+        await writeAssetProvenance(destDir, {
+          id: asset.id,
+          name: asset.name,
+          source: asset.source,
+          sourceUrl: asset.sourceUrl,
+          author: asset.author,
+          license: asset.license,
+          delivery: 'local-ssd',
+          originalPath: selectedFile.path,
+        });
+
+        const resultPath = `asset-library/local/${assetSlug}/${basename(mainSource)}`;
+        broadcast('assets-changed', {});
+        res.json({ ok: true, path: resultPath });
+      } catch (error) {
+        res.status(500).json({ error: `Local asset copy failed: ${error}` });
+      }
+      return;
+    }
+
+    // S2: restrict the main download URL (and includes) to allowlisted CDNs,
+    // blocking SSRF to private / link-local addresses.
+    if (!isAllowedAssetHost(url)) {
+      res.status(400).json({ error: 'Download URL host is not allowed.' });
+      return;
+    }
+    for (const inc of includes) {
+      if (!isAllowedAssetHost(inc.url)) {
+        res.status(400).json({ error: 'Included file URL host is not allowed.' });
+        return;
+      }
+    }
+
+    const publicRoot = getPublicRoot();
+    const slug = (name || id)
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-|-$/g, '');
+    const destDir = join(publicRoot, 'asset-library', source, slug);
+
+    // Skip if already downloaded
+    try {
+      await stat(destDir);
+      const existing = await readdir(destDir);
+      if (existing.length > 0) {
+        // Find the main file (gltf/glb/hdr/exr, not textures)
+        const mainFile = existing.find((f) => /\.(gltf|glb|hdr|exr)$/i.test(f)) ?? existing[0]!;
+        res.json({
+          ok: true,
+          path: `asset-library/${source}/${slug}/${mainFile}`,
+          alreadyExists: true,
+        });
+        return;
+      }
+    } catch {
+      // Doesn't exist yet — continue
+    }
+
+    try {
+      await mkdir(destDir, { recursive: true });
+
+      /** Download a single file to a destination path. */
+      async function downloadFile(fileUrl: string, destPath: string): Promise<void> {
+        await mkdir(join(destPath, '..'), { recursive: true });
+        const response = await fetch(fileUrl);
+        if (!response.ok || !response.body) {
+          throw new Error(`Download failed: ${response.status} for ${fileUrl}`);
+        }
+        const nodeStream = Readable.fromWeb(response.body as import('stream/web').ReadableStream);
+        await pipeline(nodeStream, createWriteStream(destPath));
+      }
+
+      const isZip = format === 'zip' || url.endsWith('.zip');
+      const ext = isZip ? 'zip' : url.split('.').pop() || format || 'bin';
+      const fileName = `${slug}.${ext}`;
+      const filePath = join(destDir, fileName);
+
+      // Download main file
+      await downloadFile(url, filePath);
+
+      // Download included files (GLTF bin + textures)
+      for (const inc of includes) {
+        const incPath = join(destDir, inc.relativePath);
+        // S1: ensure each relativePath stays inside destDir (reject `..` escapes).
+        if (!isPathInside(destDir, incPath)) {
+          res.status(400).json({ error: `Invalid include path: ${inc.relativePath}` });
+          return;
+        }
+        await downloadFile(inc.url, incPath);
+      }
+
+      let resultPath = `asset-library/${source}/${slug}/${fileName}`;
+
+      // Extract ZIPs
+      if (isZip) {
+        await new Promise<void>((resolve, reject) => {
+          execFile('unzip', ['-o', filePath, '-d', destDir], (err) => {
+            if (err) reject(err);
+            else resolve();
+          });
+        });
+        await unlink(filePath).catch(() => {});
+        const extracted = await readdir(destDir);
+        const mainFile = extracted.find((f) => !f.endsWith('.zip')) ?? extracted[0];
+        if (mainFile) {
+          resultPath = `asset-library/${source}/${slug}/${mainFile}`;
+        }
+      }
+
+      broadcast('assets-changed', {});
+
+      res.json({ ok: true, path: resultPath });
+    } catch (err) {
+      res.status(500).json({ error: `Download failed: ${err}` });
+    }
+  });
+
+  // ---- Categories for Poly Haven ----
+  router.get('/categories', async (req, res) => {
+    const source = req.query['source'] as string | undefined;
+    const type = req.query['type'] as string;
+    if (!type) {
+      res.status(400).json({ error: 'Missing type.' });
+      return;
+    }
+
+    if (source === 'local') {
+      try {
+        const catalog = await loadLocalAssetCatalog();
+        const categories = [
+          ...new Set(
+            catalog.assets
+              .filter((asset) => localAssetMatchesType(asset, type))
+              .flatMap((asset) => asset.categories),
+          ),
+        ].sort();
+        res.json({ categories });
+      } catch (error) {
+        res.status(503).json({ error: `Local catalog unavailable: ${error}` });
+      }
+      return;
+    }
+
+    const cacheKey = `ph-cats:${type}`;
+    const cached = getCached<string[]>(cacheKey);
+    if (cached) {
+      res.json({ categories: cached });
+      return;
+    }
+
+    try {
+      const response = await fetch(`https://api.polyhaven.com/categories/${type}`, {
+        headers: PH_HEADERS,
+      });
+      if (!response.ok) throw new Error(`${response.status}`);
+      const data = (await response.json()) as Record<string, number>;
+      const categories = Object.keys(data).sort();
+      setCache(cacheKey, categories);
+      res.json({ categories });
+    } catch (err) {
+      res.status(502).json({ error: `Upstream API error: ${err}` });
+    }
+  });
+
+  router.get('/local-placeholder.svg', (_req, res) => {
+    res
+      .type('image/svg+xml')
+      .send(
+        '<svg xmlns="http://www.w3.org/2000/svg" width="256" height="256" viewBox="0 0 256 256"><rect width="256" height="256" fill="#181818"/><path d="M64 82l64-36 64 36v76l-64 38-64-38z" fill="#252a31" stroke="#579eff" stroke-width="8"/><path d="M64 82l64 38 64-38M128 120v76" fill="none" stroke="#579eff" stroke-width="8"/><text x="128" y="226" text-anchor="middle" fill="#9aa4b2" font-family="sans-serif" font-size="18">LOCAL ASSET</text></svg>',
+      );
+  });
+
+  // ---- List already-downloaded assets ----
+  router.get('/downloaded', async (_req, res) => {
+    const publicRoot = getPublicRoot();
+    const libraryDir = join(publicRoot, 'asset-library');
+    const downloaded: { source: string; slug: string; path: string }[] = [];
+
+    try {
+      const sources = await readdir(libraryDir).catch(() => [] as string[]);
+      for (const source of sources) {
+        const sourceDir = join(libraryDir, source);
+        const sourceStat = await stat(sourceDir).catch(() => null);
+        if (!sourceStat?.isDirectory()) continue;
+
+        const slugs = await readdir(sourceDir).catch(() => [] as string[]);
+        for (const slug of slugs) {
+          const slugDir = join(libraryDir, source, slug);
+          const slugStat = await stat(slugDir).catch(() => null);
+          if (!slugStat?.isDirectory()) continue;
+
+          const files = await readdir(slugDir).catch(() => [] as string[]);
+          // Find the main asset file
+          const mainFile = files.find((f) => /\.(gltf|glb|hdr|exr)$/i.test(f)) ?? files[0];
+          if (mainFile) {
+            downloaded.push({
+              source,
+              slug,
+              path: `asset-library/${source}/${slug}/${mainFile}`,
+            });
+          }
+        }
+      }
+    } catch {
+      // Directory might not exist yet
+    }
+
+    res.json({ downloaded });
+  });
+
+  return router;
+}
+
+export async function downloadRemoteFile(
+  url: string,
+  destination: string,
+  expectedSha256: string,
+  expectedSizeBytes: number,
+): Promise<void> {
+  await mkdir(dirname(destination), { recursive: true });
+  const response = await fetch(url, { signal: AbortSignal.timeout(120_000) });
+  if (!response.ok || !response.body) {
+    throw new Error(`Download failed: ${response.status} for ${url}`);
+  }
+  const hash = createHash('sha256');
+  let sizeBytes = 0;
+  const verifier = new Transform({
+    transform(chunk: Buffer, _encoding, callback) {
+      hash.update(chunk);
+      sizeBytes += chunk.length;
+      callback(null, chunk);
+    },
+  });
+  const nodeStream = Readable.fromWeb(response.body as import('stream/web').ReadableStream);
+  try {
+    await pipeline(nodeStream, verifier, createWriteStream(destination));
+    const actualSha256 = hash.digest('hex');
+    if (actualSha256 !== expectedSha256 || sizeBytes !== expectedSizeBytes) {
+      throw new Error(
+        `Cloud asset integrity mismatch: expected ${expectedSha256}/${expectedSizeBytes}, got ${actualSha256}/${sizeBytes}`,
+      );
+    }
+  } catch (error) {
+    await unlink(destination).catch(() => undefined);
+    throw error;
+  }
+}
+
+async function writeAssetProvenance(
+  destination: string,
+  provenance: Record<string, unknown>,
+): Promise<void> {
+  await mkdir(destination, { recursive: true });
+  await writeFile(
+    join(destination, '_VGAI_ASSET.json'),
+    `${JSON.stringify(provenance, null, 2)}\n`,
+  );
+}