@darkclaw921/umgt 0.0.0-stage → 0.2.0

package/dist/server/assets.js

@@ -0,0 +1,669 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { createWriteStream } from 'node:fs';
+import { copyFile, lstat, mkdir, mkdtemp, readFile, readdir, realpath, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { basename, dirname, extname, join, relative, resolve, sep } from 'node:path';
+import { homedir } from 'node:os';
+import { pipeline } from 'node:stream/promises';
+import { Transform, Readable } from 'node:stream';
+import yauzl from 'yauzl';
+import { localMediaMetadata, registerAssetMediaRoutes, checkedMediaPath } from './asset-media.js';
+import { curatedAssets } from './asset-catalog.js';
+const MAX_DOWNLOAD = 512 * 1024 * 1024;
+const MAX_EXPANDED = 1024 * 1024 * 1024;
+const allowedHosts = new Set(['api.polyhaven.com', 'dl.polyhaven.org', 'ambientcg.com', 'www.ambientcg.com', 'acg-download.struffelproductions.com', 'acg-media.struffelproductions.com', 'f003.backblazeb2.com', 'f004.backblazeb2.com', 'opengameart.org', 'kenney.nl', 'media.w3.org', 'download.blender.org']);
+const safeExtensions = new Set(['.mp4', '.webm', '.ogv', '.gif', '.png', '.jpg', '.jpeg', '.webp', '.svg', '.bmp', '.tga', '.exr', '.hdr', '.glb', '.gltf', '.bin', '.obj', '.mtl', '.fbx', '.wav', '.ogg', '.mp3', '.flac', '.ttf', '.otf', '.woff', '.woff2', '.txt', '.md', '.json', '.license', '.csv']);
+const licenseUrls = {
+    'CC0-1.0': 'https://creativecommons.org/publicdomain/zero/1.0/',
+    'CC-BY-3.0': 'https://creativecommons.org/licenses/by/3.0/',
+    'CC-BY-4.0': 'https://creativecommons.org/licenses/by/4.0/',
+};
+function httpsUrl(value) {
+    try {
+        const url = new URL(value ?? '');
+        return url.protocol === 'https:' && !url.username && !url.password;
+    }
+    catch {
+        return false;
+    }
+}
+/** Eligibility for recommendations is stricter than an unknown user-upload license. */
+export function isAutoSelectableAsset(asset) {
+    return !!licenseUrls[asset.license] && asset.licenseUrl === licenseUrls[asset.license]
+        && !!asset.author?.trim() && httpsUrl(asset.sourceUrl) && httpsUrl(asset.provenanceUrl)
+        && !!asset.verifiedAt && !!asset.formats?.length
+        && (asset.license === 'CC0-1.0' || !!asset.attribution?.trim());
+}
+async function trustedFetch(input, signal) {
+    signal?.throwIfAborted();
+    let url = new URL(input);
+    for (let i = 0; i < 6; i++) {
+        if (url.protocol !== 'https:' || url.username || url.password || url.port || !allowedHosts.has(url.hostname))
+            throw new Error('Asset URL is outside the trusted provider domains');
+        const response = await fetch(url, { redirect: 'manual', signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000), headers: { 'User-Agent': 'LMGameHub/0.1 (local game development; Poly Haven integration)' } });
+        if (response.status >= 300 && response.status < 400) {
+            const location = response.headers.get('location');
+            await response.body?.cancel();
+            if (!location)
+                throw new Error('Provider returned an invalid redirect');
+            url = new URL(location, url);
+            continue;
+        }
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw new Error(`Provider request failed (${response.status})`);
+        }
+        return response;
+    }
+    throw new Error('Too many asset download redirects');
+}
+async function json(url, signal) {
+    const response = await trustedFetch(url, signal);
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw new Error('Empty provider response');
+    const chunks = [];
+    let length = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        length += value.length;
+        if (length > 24 * 1024 * 1024) {
+            await reader.cancel();
+            throw new Error('Provider response exceeds limit');
+        }
+        chunks.push(value);
+    }
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}
+const searchCache = new Map();
+const polyAsset = (id, record) => ({ id, provider: 'polyhaven', name: record.name, type: ['hdris', 'textures', 'models'][record.type] ?? 'models', thumbnail: record.thumbnail_url && httpsUrl(record.thumbnail_url) ? record.thumbnail_url : undefined, sourceUrl: `https://polyhaven.com/a/${encodeURIComponent(id)}`, provenanceUrl: 'https://polyhaven.com/license', licenseUrl: licenseUrls['CC0-1.0'], verifiedAt: new Date().toISOString(), formats: record.type === 0 ? ['HDR', 'EXR'] : record.type === 1 ? ['JPG', 'PNG'] : ['GLTF'], license: 'CC0-1.0', author: Object.keys(record.authors ?? {}).join(', '), tags: [...(record.categories ?? []), ...(record.tags ?? [])], importMode: 'automatic' });
+function ambientAsset(record) {
+    const downloads = Object.values(record.downloadFolders ?? {}).flatMap(folder => Object.values(folder.downloadFiletypeCategories ?? {}).flatMap(category => category.downloads ?? []));
+    const download = downloads.find(item => item.attribute === '1K-JPG') ?? downloads.filter(item => item.size < MAX_DOWNLOAD).sort((a, b) => a.size - b.size)[0];
+    return { id: record.assetId, provider: 'ambientcg', name: record.displayName || record.assetId, type: record.dataType === 'HDRI' ? 'hdris' : record.dataType === '3DModel' ? 'models' : 'textures', thumbnail: record.previewImage?.['512-PNG'] ?? Object.values(record.previewImage ?? {})[0], sourceUrl: `https://ambientcg.com/view?id=${encodeURIComponent(record.assetId)}`, provenanceUrl: 'https://docs.ambientcg.com/license/', licenseUrl: licenseUrls['CC0-1.0'], verifiedAt: new Date().toISOString(), license: 'CC0-1.0', author: 'ambientCG', tags: record.tags ?? [], downloadUrl: download?.downloadLink, formats: ['ZIP'], importMode: download ? 'automatic' : 'manual' };
+}
+const queryStopWords = new Set(['a', 'an', 'the', 'for', 'with', 'and', 'or', 'game', 'asset', 'assets', 'pack', 'free']);
+function searchTerms(value) {
+    return [...new Set(value.toLowerCase().normalize('NFKC').split(/[^\p{L}\p{N}]+/u).filter(term => term.length > 1 && !queryStopWords.has(term)).map(term => term.replace(/s$/, '')))];
+}
+export async function searchAssets(query, options = {}) {
+    options.signal?.throwIfAborted();
+    const selected = options.provider && options.provider !== 'all' ? [options.provider] : ['polyhaven', 'ambientcg', 'kenney', 'opengameart', 'blender'];
+    const aliases = { 'model': 'models', 'texture': 'textures', '3d': 'models', 'music': 'audio', 'sfx': 'audio', 'sprites': '2d', 'tiles': '2d', 'characters': '2d' };
+    const type = aliases[options.type ?? ''] ?? options.type;
+    const terms = searchTerms(query), warnings = [];
+    const settled = await Promise.allSettled(selected.map(async (provider) => {
+        options.signal?.throwIfAborted();
+        const key = `${provider}:${query}:${type ?? ''}`;
+        const cached = searchCache.get(key);
+        if (cached && cached.until > Date.now())
+            return cached.items;
+        let items;
+        if (provider === 'kenney' || provider === 'opengameart' || provider === 'blender')
+            items = structuredClone(curatedAssets.filter(asset => asset.provider === provider));
+        else if (provider === 'polyhaven') {
+            const filter = ['hdris', 'textures', 'models'].includes(type ?? '') ? `?t=${type}` : '';
+            const records = await json(`https://api.polyhaven.com/assets${filter}`, options.signal);
+            items = Object.entries(records).map(([id, record]) => polyAsset(id, record));
+        }
+        else if (provider === 'ambientcg') {
+            const params = new URLSearchParams({ limit: '30', include: 'downloadData', q: query });
+            const result = await json(`https://ambientcg.com/api/v2/full_json?${params}`, options.signal);
+            items = result.foundAssets.map(ambientAsset);
+        }
+        else
+            throw new Error('Неизвестный провайдер');
+        const ranked = items.filter(asset => !type || type === 'all' || asset.type === type).map(asset => {
+            const haystack = searchTerms(`${asset.name} ${asset.tags.join(' ')} ${asset.type}`).join(' ');
+            return { asset, score: terms.filter(term => haystack.includes(term)).length };
+        });
+        items = ranked.filter(item => provider === 'ambientcg' || !terms.length || item.score > 0).sort((a, b) => b.score - a.score).slice(0, 30).map(item => item.asset);
+        options.signal?.throwIfAborted();
+        if (searchCache.size > 100)
+            searchCache.clear();
+        searchCache.set(key, { until: Date.now() + 300_000, items });
+        return items;
+    }));
+    options.signal?.throwIfAborted();
+    const assets = settled.flatMap((result, index) => { if (result.status === 'fulfilled')
+        return result.value; warnings.push(`${selected[index]}: ${result.reason instanceof Error ? result.reason.message : 'Сервис недоступен'}`); return []; });
+    return { assets: assets.map(catalogMediaMetadata), warnings };
+}
+export async function assetDetails(provider, id, options = {}) {
+    options.signal?.throwIfAborted();
+    if (!/^[a-zA-Z0-9_-]{1,120}$/.test(id))
+        throw Object.assign(new Error('Invalid asset identifier'), { statusCode: 400 });
+    if (provider === 'kenney' || provider === 'opengameart' || provider === 'blender') {
+        const item = curatedAssets.find(asset => asset.provider === provider && asset.id === id);
+        if (item)
+            return catalogMediaMetadata(structuredClone(item));
+    }
+    if (provider === 'polyhaven')
+        return polyAsset(id, await json(`https://api.polyhaven.com/info/${encodeURIComponent(id)}`, options.signal));
+    if (provider === 'ambientcg') {
+        const result = await json(`https://ambientcg.com/api/v2/full_json?assetId=${encodeURIComponent(id)}&include=downloadData`, options.signal);
+        const record = result.foundAssets.find(item => item.assetId === id);
+        if (record)
+            return ambientAsset(record);
+    }
+    throw Object.assign(new Error('Ассет не найден'), { statusCode: 404 });
+}
+async function downloadsFor(asset, signal) {
+    signal?.throwIfAborted();
+    if (asset.provider === 'opengameart' && asset.importMode === 'automatic' && asset.downloadUrl) {
+        return [{ url: asset.downloadUrl, name: decodeURIComponent(basename(new URL(asset.downloadUrl).pathname)) }];
+    }
+    if (asset.provider === 'ambientcg' && asset.downloadUrl) {
+        const url = new URL(asset.downloadUrl);
+        return [{ url: url.href, name: url.searchParams.get('file') ?? `${asset.id}.zip` }];
+    }
+    if (asset.provider === 'polyhaven') {
+        const files = await json(`https://api.polyhaven.com/files/${encodeURIComponent(asset.id)}`, signal);
+        const gltf = files.gltf?.['1k']?.gltf ?? files.gltf?.['2k']?.gltf;
+        if (gltf)
+            return [{ url: gltf.url, name: basename(new URL(gltf.url).pathname), size: gltf.size }, ...Object.entries(gltf.include ?? {}).map(([name, item]) => ({ url: item.url, name, size: item.size }))];
+        const hdri = files.hdri?.['1k']?.hdr ?? files.hdri?.['1k']?.exr;
+        if (hdri)
+            return [{ url: hdri.url, name: basename(new URL(hdri.url).pathname), size: hdri.size }];
+        const textures = Object.values(files).flatMap(resolutions => { const item = resolutions['1k']?.jpg ?? resolutions['1k']?.png; return item ? [{ url: item.url, name: basename(new URL(item.url).pathname), size: item.size }] : []; });
+        if (textures.length)
+            return textures;
+    }
+    throw Object.assign(new Error('Скачайте ассет на сайте источника и импортируйте файл через меню.'), { statusCode: 422 });
+}
+export function safeAssetPath(root, name) {
+    if (!name || name.includes('\\') || name.includes('\0') || /^[a-zA-Z]:/.test(name) || name.startsWith('/') || name.split('/').some(part => part === '..' || part.startsWith('.')))
+        throw new Error('Unsafe asset path');
+    const path = resolve(root, name);
+    const rel = relative(root, path);
+    if (!rel || rel.startsWith('..' + sep) || rel === '..')
+        throw new Error('Unsafe asset path');
+    return path;
+}
+export async function extractZip(archive, destination, signal) {
+    signal?.throwIfAborted();
+    await mkdir(destination, { recursive: true });
+    return new Promise((resolvePromise, reject) => {
+        yauzl.open(archive, { lazyEntries: true, validateEntrySizes: true, strictFileNames: true }, (error, zip) => {
+            if (error || !zip) {
+                reject(error ?? new Error('Invalid archive'));
+                return;
+            }
+            const files = [];
+            let size = 0;
+            let count = 0;
+            let failed = false;
+            const cleanup = () => signal?.removeEventListener('abort', abort);
+            const fail = (error) => { if (failed)
+                return; failed = true; cleanup(); zip.close(); reject(error); };
+            const abort = () => fail(signal?.reason ?? new Error('Import aborted'));
+            signal?.addEventListener('abort', abort, { once: true });
+            if (signal?.aborted) {
+                abort();
+                return;
+            }
+            zip.on('error', fail);
+            zip.on('end', () => { cleanup(); resolvePromise(files); });
+            zip.on('entry', (entry) => {
+                void (async () => {
+                    signal?.throwIfAborted();
+                    count++;
+                    size += entry.uncompressedSize;
+                    if (count > 10_000 || size > MAX_EXPANDED)
+                        throw new Error('Archive exceeds extraction limits');
+                    if (((entry.externalFileAttributes >>> 16) & 0xf000) === 0xa000)
+                        throw new Error('Symlinks are not allowed in asset archives');
+                    const name = entry.fileName.replace(/\/$/, '');
+                    const parts = name.split('/');
+                    const macMetadata = parts[0] === '__MACOSX';
+                    const finderMetadata = parts.at(-1) === '.DS_Store';
+                    // Validate bounds and every path component before skipping known archive metadata.
+                    // AppleDouble entries are allowed only inside __MACOSX, never as game files.
+                    if (macMetadata || finderMetadata) {
+                        safeAssetPath(destination, parts.map((part, index) => (finderMetadata && index === parts.length - 1) || (macMetadata && part.startsWith('._')) ? 'metadata' : part).join('/'));
+                        zip.readEntry();
+                        return;
+                    }
+                    const path = safeAssetPath(destination, name);
+                    if (entry.fileName.endsWith('/')) {
+                        await mkdir(path, { recursive: true });
+                        zip.readEntry();
+                        return;
+                    }
+                    if (!safeExtensions.has(extname(path).toLowerCase())) {
+                        zip.readEntry();
+                        return;
+                    }
+                    await mkdir(dirname(path), { recursive: true });
+                    const stream = await new Promise((resolve, rejectStream) => zip.openReadStream(entry, (error, stream) => error || !stream ? rejectStream(error) : resolve(stream)));
+                    await pipeline(stream, createWriteStream(path, { flags: 'wx' }), { signal });
+                    files.push(entry.fileName);
+                    zip.readEntry();
+                })().catch(fail);
+            });
+            zip.readEntry();
+        });
+    });
+}
+async function downloadFile(item, destination, options) {
+    options.signal?.throwIfAborted();
+    const maximum = Math.min(MAX_DOWNLOAD, options.maxBytes ?? MAX_DOWNLOAD);
+    const cacheDir = options.cacheDir ?? join(homedir(), '.lm-game-hub/cache');
+    await mkdir(cacheDir, { recursive: true });
+    const key = createHash('sha256').update(item.url).digest('hex');
+    const cachePath = join(cacheDir, key);
+    try {
+        const info = await lstat(cachePath);
+        if (info.isFile() && !info.isSymbolicLink() && info.size <= maximum) {
+            await copyFile(cachePath, destination);
+            return;
+        }
+    }
+    catch { /* cache miss */ }
+    const response = await trustedFetch(item.url, options.signal);
+    if (!response.body)
+        throw new Error('Provider returned empty file');
+    const total = Number(response.headers.get('content-length')) || item.size;
+    if (total && total > maximum) {
+        await response.body.cancel();
+        throw new Error('Asset exceeds 512 MiB limit');
+    }
+    let downloaded = 0;
+    let last = 0;
+    const meter = new Transform({ transform(chunk, _encoding, callback) {
+            downloaded += chunk.length;
+            if (downloaded > maximum)
+                return callback(new Error('Asset exceeds 512 MiB limit'));
+            if (Date.now() - last > 150) {
+                last = Date.now();
+                options.emit?.({ downloaded, total, file: item.name });
+            }
+            callback(null, chunk);
+        } });
+    await pipeline(Readable.fromWeb(response.body), meter, createWriteStream(destination, { flags: 'wx' }), { signal: options.signal });
+    options.emit?.({ downloaded, total, file: item.name });
+    const cacheTemporary = `${cachePath}.${randomUUID()}.tmp`;
+    try {
+        await copyFile(destination, cacheTemporary);
+        await rename(cacheTemporary, cachePath);
+    }
+    catch {
+        await rm(cacheTemporary, { force: true }).catch(() => undefined);
+    }
+}
+async function assetWorkspace(project) {
+    const root = await realpath(project.path);
+    const temporary = join(root, '.lm-game-hub/tmp');
+    const assets = join(root, 'assets');
+    for (const path of [join(root, '.lm-game-hub'), temporary, assets]) {
+        try {
+            if ((await lstat(path)).isSymbolicLink())
+                throw new Error('Asset folders cannot be symbolic links outside the managed layout');
+        }
+        catch (error) {
+            if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT'))
+                throw error;
+        }
+        await mkdir(path, { recursive: true });
+    }
+    for (const dir of [temporary, assets])
+        if (!(await realpath(dir)).startsWith(root + sep))
+            throw new Error('Asset folders cannot point outside the project');
+    return { root, stage: await mkdtemp(join(temporary, 'asset-')), assets };
+}
+async function finishImport(project, asset, workspace, files) {
+    if (!files.length)
+        throw new Error('В архиве нет поддерживаемых игровых ресурсов.');
+    if (files.includes('LMGH-ASSET.json') || files.includes('LMGH-CREDITS.txt'))
+        throw new Error('Archive uses a reserved provenance filename');
+    const id = `${asset.provider}-${asset.id}-${randomUUID().slice(0, 8)}`;
+    const directory = join(workspace.assets, id);
+    const record = { ...asset, sourceId: asset.id, id, importedAt: new Date().toISOString(), directory: relative(workspace.root, directory), files, ...localMediaMetadata(project, 'imported', id, files) };
+    if (asset.license.startsWith('CC-BY-')) {
+        await writeFile(join(workspace.stage, 'LMGH-CREDITS.txt'), `${asset.name}\nCreator: ${asset.author}\nSource: ${asset.sourceUrl}\nLicense: ${asset.license} — ${asset.licenseUrl}\n${asset.attribution ?? ''}\nChanges at import: none; archive unpacking only. Record subsequent modifications and include this credit when distributing the game.\n`);
+    }
+    await writeFile(join(workspace.stage, 'LMGH-ASSET.json'), JSON.stringify(record, null, 2));
+    await rename(workspace.stage, directory);
+    return record;
+}
+async function performImport(project, requestedAsset, options = {}) {
+    options.signal?.throwIfAborted();
+    const asset = await assetDetails(requestedAsset.provider, requestedAsset.id, options);
+    if (!isAutoSelectableAsset(asset))
+        throw new Error('Automatic import requires verified CC0 or CC-BY metadata with attribution');
+    const existing = await findExistingImport(project, asset);
+    if (existing)
+        return existing;
+    const downloads = await downloadsFor(asset, options.signal);
+    const workspace = await assetWorkspace(project);
+    const files = [];
+    let totalSize = 0;
+    try {
+        for (const item of downloads) {
+            const target = safeAssetPath(workspace.stage, item.name);
+            await mkdir(dirname(target), { recursive: true });
+            await downloadFile(item, target, options);
+            totalSize += (await stat(target)).size;
+            if (totalSize > MAX_EXPANDED)
+                throw new Error('Asset bundle exceeds 1 GiB limit');
+            if (extname(target).toLowerCase() === '.zip') {
+                files.push(...await extractZip(target, workspace.stage, options.signal));
+                await rm(target);
+            }
+            else {
+                if (!safeExtensions.has(extname(target).toLowerCase()))
+                    throw new Error('Unsupported asset file type');
+                files.push(item.name);
+            }
+        }
+        options.signal?.throwIfAborted();
+        return await finishImport(project, asset, workspace, files);
+    }
+    catch (error) {
+        await rm(workspace.stage, { recursive: true, force: true });
+        throw error;
+    }
+}
+/** Resolve authoritative metadata, then reuse a verified previous import for the same source. */
+export async function importAsset(project, requestedAsset, options = {}) {
+    options.signal?.throwIfAborted();
+    const root = await realpath(project.path);
+    return serializedImport(`provider:${root}:${requestedAsset.provider}:${requestedAsset.id}`, options.signal, () => performImport(project, requestedAsset, options));
+}
+function localMetadata(filename, metadata, id = randomUUID()) {
+    const license = metadata.license ?? 'User supplied — verify license';
+    const asset = { id, provider: 'local', name: metadata.name || filename, type: metadata.type || 'custom', sourceUrl: metadata.sourceUrl ?? '', license,
+        author: metadata.author, licenseUrl: metadata.licenseUrl ?? licenseUrls[license], attribution: metadata.attribution,
+        provenanceUrl: metadata.provenanceUrl, verifiedAt: metadata.verifiedAt, formats: metadata.formats ?? [extname(filename).slice(1).toUpperCase()], tags: metadata.tags ?? [], importMode: 'manual' };
+    if (license.startsWith('CC-BY-') && (!licenseUrls[license] || !asset.author?.trim() || !httpsUrl(asset.sourceUrl) || asset.licenseUrl !== licenseUrls[license])) {
+        throw Object.assign(new Error('CC-BY uploads require a supported 3.0/4.0 license, creator and HTTPS source URL'), { statusCode: 400 });
+    }
+    if (license.startsWith('CC-BY-') && !asset.attribution)
+        asset.attribution = `${asset.name} by ${asset.author}. ${asset.sourceUrl} — ${asset.license}.`;
+    return asset;
+}
+async function receiveLocalFiles(destination, filename, stream, signal) {
+    signal?.throwIfAborted();
+    const safeName = basename(filename.replaceAll('\\', '/')), target = safeAssetPath(destination, safeName);
+    let size = 0;
+    const meter = new Transform({ transform(chunk, _encoding, callback) { size += chunk.length; callback(size > MAX_DOWNLOAD ? new Error('File exceeds 512 MiB limit') : null, chunk); } });
+    await pipeline(stream, meter, createWriteStream(target, { flags: 'wx' }), { signal });
+    if (stream.truncated)
+        throw new Error('File exceeds upload limit');
+    const zipped = extname(target).toLowerCase() === '.zip';
+    if (!zipped && !safeExtensions.has(extname(target).toLowerCase()))
+        throw new Error('Unsupported asset file type');
+    const files = zipped ? await extractZip(target, destination, signal) : [safeName];
+    if (zipped)
+        await rm(target);
+    if (!files.length)
+        throw new Error('В архиве нет поддерживаемых игровых ресурсов.');
+    return files;
+}
+/** Validate an upload outside the game project; only return an opaque project-bound handle. */
+export async function stageLocalAsset(project, filename, stream, metadata = {}, options) {
+    options.signal?.throwIfAborted();
+    const projectPath = await realpath(project.path);
+    await mkdir(options.stagingDir, { recursive: true, mode: 0o700 });
+    if ((await lstat(options.stagingDir)).isSymbolicLink())
+        throw new Error('Upload staging cannot be a symbolic link');
+    const root = await realpath(options.stagingDir);
+    if (root === projectPath || root.startsWith(projectPath + sep))
+        throw new Error('Upload staging must be outside the game project');
+    const handle = randomUUID(), folder = join(root, handle), data = join(folder, 'files');
+    const asset = localMetadata(basename(filename.replaceAll('\\', '/')), metadata, handle);
+    await mkdir(data, { recursive: true, mode: 0o700 });
+    try {
+        const files = await receiveLocalFiles(data, filename, stream, options.signal);
+        options.signal?.throwIfAborted();
+        Object.assign(asset, localMediaMetadata(project, 'staged', handle, files));
+        await writeFile(join(folder, 'manifest.json'), JSON.stringify({ projectId: project.id, projectPath, asset, files }), { flag: 'wx', mode: 0o600 });
+        return { handle, asset };
+    }
+    catch (error) {
+        await rm(folder, { recursive: true, force: true });
+        throw error;
+    }
+}
+async function checkedFile(root, name) {
+    const file = safeAssetPath(root, name);
+    const actual = await realpath(file);
+    if (!actual.startsWith(root + sep) || (await lstat(file)).isSymbolicLink() || !(await stat(file)).isFile())
+        throw new Error('Asset file points outside its managed directory');
+    return file;
+}
+async function validImported(project, record) {
+    try {
+        const root = await realpath(project.path), directory = safeAssetPath(root, record.directory);
+        if (!directory.startsWith(join(root, 'assets') + sep) || (await lstat(directory)).isSymbolicLink())
+            return false;
+        const actual = await realpath(directory);
+        if (!actual.startsWith(root + sep) || !Array.isArray(record.files) || !record.files.length)
+            return false;
+        for (const file of record.files)
+            await checkedFile(actual, file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function findExistingImport(project, asset) {
+    const root = await realpath(project.path), folder = join(root, 'assets');
+    try {
+        if ((await lstat(folder)).isSymbolicLink() || !(await realpath(folder)).startsWith(root + sep))
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    for (const entry of await readdir(folder, { withFileTypes: true })) {
+        if (!entry.isDirectory() || entry.isSymbolicLink())
+            continue;
+        try {
+            const record = JSON.parse(await readFile(await checkedFile(join(folder, entry.name), 'LMGH-ASSET.json'), 'utf8'));
+            if (record.provider === asset.provider && record.sourceId === asset.id && record.sourceUrl === asset.sourceUrl && record.license === asset.license && await validImported(project, record))
+                return { ...record, ...localMediaMetadata(project, 'imported', record.id, record.files) };
+        }
+        catch { /* A user-owned or incomplete directory is not an import receipt. */ }
+    }
+    return undefined;
+}
+const imports = new Map();
+async function serializedImport(key, signal, work) {
+    // Wait for an existing request, then recheck the persisted result. Each caller
+    // keeps its own cancellation semantics instead of sharing an AbortController.
+    while (imports.has(key)) {
+        await imports.get(key)?.catch(() => undefined);
+        signal?.throwIfAborted();
+    }
+    const promise = work();
+    imports.set(key, promise);
+    try {
+        return await promise;
+    }
+    finally {
+        if (imports.get(key) === promise)
+            imports.delete(key);
+    }
+}
+/** Commit validated staged files after the plan gate. Repeated handles reuse verified results. */
+export async function importStagedAsset(project, handle, options) {
+    options.signal?.throwIfAborted();
+    if (!/^[0-9a-f]{8}-[0-9a-f-]{27}$/i.test(handle))
+        throw Object.assign(new Error('Invalid upload handle'), { statusCode: 400 });
+    const root = await realpath(options.stagingDir), folder = join(root, handle);
+    if ((await lstat(options.stagingDir)).isSymbolicLink() || (await lstat(folder)).isSymbolicLink() || !(await realpath(folder)).startsWith(root + sep))
+        throw new Error('Upload staging points outside its managed directory');
+    return serializedImport(`staged:${folder}`, options.signal, async () => {
+        const manifest = JSON.parse(await readFile(await checkedFile(folder, 'manifest.json'), 'utf8'));
+        if (manifest.projectId !== project.id || manifest.projectPath !== await realpath(project.path))
+            throw Object.assign(new Error('Upload belongs to another project'), { statusCode: 409 });
+        const previous = await checkedFile(folder, 'imported.json').then(file => readFile(file, 'utf8')).then(text => JSON.parse(text)).catch(error => { if (error?.code === 'ENOENT')
+            return undefined; throw error; });
+        if (previous) {
+            if (await validImported(project, previous))
+                return previous;
+            throw new Error('Previously imported files have changed or disappeared. Upload the source again.');
+        }
+        const recovered = await findExistingImport(project, manifest.asset);
+        if (recovered) {
+            await writeFile(join(folder, 'imported.json'), JSON.stringify(recovered), { flag: 'wx', mode: 0o600 });
+            return recovered;
+        }
+        if (!Array.isArray(manifest.files) || !manifest.files.length || manifest.files.length > 10_000)
+            throw new Error('Invalid upload manifest');
+        const data = join(folder, 'files');
+        if ((await lstat(data)).isSymbolicLink() || !(await realpath(data)).startsWith(folder + sep))
+            throw new Error('Staged files point outside the upload');
+        const workspace = await assetWorkspace(project);
+        try {
+            let total = 0;
+            for (const name of manifest.files) {
+                options.signal?.throwIfAborted();
+                const source = await checkedFile(data, name), target = safeAssetPath(workspace.stage, name);
+                if (!safeExtensions.has(extname(name).toLowerCase()))
+                    throw new Error('Unsupported staged file type');
+                total += (await stat(source)).size;
+                if (total > MAX_EXPANDED)
+                    throw new Error('Asset bundle exceeds 1 GiB limit');
+                await mkdir(dirname(target), { recursive: true });
+                await copyFile(source, target);
+                options.emit?.({ downloaded: total, file: name });
+            }
+            options.signal?.throwIfAborted();
+            const imported = await finishImport(project, manifest.asset, workspace, manifest.files);
+            await writeFile(join(folder, 'imported.json'), JSON.stringify(imported), { flag: 'wx', mode: 0o600 });
+            return imported;
+        }
+        catch (error) {
+            await rm(workspace.stage, { recursive: true, force: true });
+            throw error;
+        }
+    });
+}
+export async function importLocalAsset(project, filename, stream, metadata = {}) {
+    const workspace = await assetWorkspace(project);
+    try {
+        const asset = localMetadata(basename(filename.replaceAll('\\', '/')), metadata);
+        const files = await receiveLocalFiles(workspace.stage, filename, stream);
+        return await finishImport(project, asset, workspace, files);
+    }
+    catch (error) {
+        await rm(workspace.stage, { recursive: true, force: true });
+        throw error;
+    }
+}
+export function catalogMediaMetadata(asset) {
+    const media = [...(asset.media ?? [])];
+    if (asset.thumbnail && !media.some(item => item.url === asset.thumbnail))
+        media.push({ kind: 'image', url: asset.thumbnail, name: asset.name });
+    if (asset.previewAudioUrl && !media.some(item => item.url === asset.previewAudioUrl))
+        media.push({ kind: 'audio', url: asset.previewAudioUrl, name: asset.name });
+    if (asset.previewVideoUrl && !media.some(item => item.url === asset.previewVideoUrl))
+        media.push({ kind: 'video', url: asset.previewVideoUrl, name: asset.name, poster: asset.thumbnail });
+    return { ...asset, media, ...(['kenney', 'opengameart', 'blender'].includes(asset.provider) && asset.downloadUrl ? { mediaGalleryUrl: `/api/v1/assets/${encodeURIComponent(asset.provider)}/${encodeURIComponent(asset.id)}/media` } : {}) };
+}
+const mediaJobs = new Map();
+/** Lazy official-source preview cache. Never creates a game project or touches its files. */
+export async function prepareProviderMedia(provider, id, options) {
+    options.signal?.throwIfAborted();
+    const asset = await assetDetails(provider, id, { signal: options.signal });
+    if (!['kenney', 'opengameart', 'blender'].includes(provider) || !asset.downloadUrl || !isAutoSelectableAsset(asset))
+        throw Object.assign(new Error('Preview archive is unavailable; open the original source'), { statusCode: 422 });
+    await mkdir(options.mediaDir, { recursive: true, mode: 0o700 });
+    if ((await lstat(options.mediaDir)).isSymbolicLink())
+        throw new Error('Media cache cannot be a symlink');
+    const root = await realpath(options.mediaDir), key = createHash('sha256').update(asset.downloadUrl).digest('hex'), directory = join(root, key);
+    const existing = async () => { try {
+        const folder = await checkedMediaPath(root, key), manifest = JSON.parse(await readFile(await checkedMediaPath(folder, 'media.json'), 'utf8'));
+        if (manifest.sourceUrl !== asset.downloadUrl || !Array.isArray(manifest.files) || manifest.files.length > 10000)
+            throw new Error('Invalid media cache');
+        return { root: folder, files: manifest.files };
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    } };
+    const cached = await existing();
+    if (cached)
+        return cached;
+    while (mediaJobs.has(directory)) {
+        await mediaJobs.get(directory);
+        options.signal?.throwIfAborted();
+        const result = await existing();
+        if (result)
+            return result;
+    }
+    const work = (async () => {
+        const stage = await mkdtemp(join(root, 'preview-'));
+        try {
+            const name = decodeURIComponent(basename(new URL(asset.downloadUrl).pathname)), target = safeAssetPath(stage, name);
+            await downloadFile({ url: asset.downloadUrl, name }, target, { ...options, maxBytes: 64 * 1024 * 1024 });
+            let files;
+            if (extname(name).toLowerCase() === '.zip') {
+                files = await extractZip(target, stage, options.signal);
+                await rm(target);
+            }
+            else {
+                if (!safeExtensions.has(extname(name).toLowerCase()))
+                    throw new Error('Unsupported preview source');
+                files = [name];
+            }
+            options.signal?.throwIfAborted();
+            await writeFile(join(stage, 'media.json'), JSON.stringify({ files, sourceUrl: asset.downloadUrl }), { flag: 'wx' });
+            await rename(stage, directory);
+            return { root: directory, files };
+        }
+        catch (error) {
+            await rm(stage, { recursive: true, force: true });
+            throw error;
+        }
+    })();
+    mediaJobs.set(directory, work);
+    try {
+        return await work;
+    }
+    finally {
+        if (mediaJobs.get(directory) === work)
+            mediaJobs.delete(directory);
+    }
+}
+export async function registerAssetRoutes(app, hub, guards = {}) {
+    registerAssetMediaRoutes(app, hub, (provider, id, signal) => prepareProviderMedia(provider, id, { cacheDir: join(hub.dataDir, 'cache'), mediaDir: join(hub.dataDir, 'provider-media'), signal }));
+    const projectFor = (id) => { const project = hub.store.get('projects', id); if (!project)
+        throw Object.assign(new Error('Project not found'), { statusCode: 404 }); return project; };
+    app.get('/api/v1/assets', request => searchAssets((request.query.q ?? '').slice(0, 200), request.query));
+    app.get('/api/v1/assets/:provider/:id', request => assetDetails(request.params.provider, request.params.id));
+    app.post('/api/v1/projects/:id/assets', async (request) => {
+        const project = projectFor(request.params.id);
+        guards.assertIdle?.(project.id);
+        const { provider, id } = request.body ?? {};
+        if (typeof provider !== 'string' || typeof id !== 'string')
+            throw Object.assign(new Error('provider and id are required'), { statusCode: 400 });
+        const asset = await assetDetails(provider, id);
+        const imported = await importAsset(project, asset, { cacheDir: join(hub.dataDir, 'cache'), emit: progress => hub.events.publish('asset.progress', progress, project.id) });
+        hub.store.project(project.id).put('assets', imported);
+        hub.events.publish('asset.imported', imported, project.id);
+        return imported;
+    });
+    app.post('/api/v1/projects/:id/assets/upload', async (request) => {
+        const project = projectFor(request.params.id);
+        guards.assertIdle?.(project.id);
+        const file = await request.file();
+        if (!file)
+            throw Object.assign(new Error('Select a file'), { statusCode: 400 });
+        const field = (name) => { const value = file.fields[name]; return value && !Array.isArray(value) && value.type === 'field' && typeof value.value === 'string' ? value.value : undefined; };
+        const imported = await importLocalAsset(project, file.filename, file.file, { sourceUrl: field('sourceUrl'), author: field('author'), license: field('license'), licenseUrl: field('licenseUrl'), attribution: field('attribution') });
+        if (file.file.truncated) {
+            await rm(join(project.path, imported.directory), { recursive: true, force: true });
+            throw new Error('File exceeds upload limit');
+        }
+        hub.store.project(project.id).put('assets', imported);
+        hub.events.publish('asset.imported', imported, project.id);
+        return imported;
+    });
+}
+//# sourceMappingURL=assets.js.map