@deepblend/dsh-blender-host 0.2.20 → 0.3.1

package/lib/artifact-writer.js

@@ -0,0 +1,49 @@
+/** Short, bounded publication leases for emitted artifacts on a local filesystem. */
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { setTimeout } from 'node:timers/promises'
+import { BlenderError, BlenderErrorCode } from '@deepblend/dsh-blender-contracts'
+import { assertProjectWriter, withProjectWriter } from './project-writer.js'
+
+const ownership = new AsyncLocalStorage()
+
+export async function withArtifactWriter(directory, workspaceRoot, action, options = {}) {
+  const { signal, timeoutMs = 10_000 } = options
+  const checkCancelled = () => {
+    if (signal?.aborted) throw new BlenderError(BlenderErrorCode.ABORTED, 'Artifact publication was cancelled.')
+  }
+  checkCancelled()
+  // Only calls in the owning async chain may join its lease. A second Host in
+  // this process must wait just like a second OS process; a global flag is unsafe.
+  if (ownership.getStore()?.has(directory)) {
+    assertProjectWriter(directory)
+    return action()
+  }
+  const deadline = performance.now() + timeoutMs
+  for (;;) {
+    checkCancelled()
+    let entered = false
+    try {
+      // The existing lease primitive also covers dead-owner recovery and release.
+      // The revision directory is a different key from the project decision lock.
+      return await withProjectWriter(directory, workspaceRoot, () => {
+        entered = true
+        const parents = new Set(ownership.getStore() ?? [])
+        parents.add(directory)
+        return ownership.run(parents, action)
+      })
+    } catch (cause) {
+      // Retrying an action could duplicate its file changes. Retry acquisition only.
+      if (entered || cause.code !== BlenderErrorCode.REVISION_CONFLICT) throw cause
+      if (performance.now() >= deadline) {
+        throw new BlenderError(BlenderErrorCode.REVISION_CONFLICT,
+          'Artifact publication could not acquire its revision lease within the wait limit. Retry after the current publisher finishes.',
+          { detail: { ...cause.detail, timeoutMs } })
+      }
+      try { await setTimeout(Math.min(10, Math.max(1, deadline - performance.now())), undefined, { signal }) }
+      catch (cause) {
+        checkCancelled()
+        throw cause
+      }
+    }
+  }
+}

package/lib/asset-bundle.js

@@ -0,0 +1,381 @@
+/** Immutable model resource snapshots. File URIs are resolved only inside a supplied local root. */
+import { createHash, randomUUID } from 'node:crypto';
+import { createReadStream, closeSync, existsSync, openSync, readSync, fstatSync, linkSync, mkdirSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, posix, relative, resolve, sep } from 'node:path';
+import { BlenderError, BlenderErrorCode } from '@deepblend/dsh-blender-contracts';
+import { streamAsset } from './asset-io.js';
+import { fileSha256, removeTree, resolveInside } from './paths.js';
+import { objLibraries, mtlImages } from './obj-resources.js';
+export const BUNDLE_LOCK = '.deepblend-lock.json';
+export const BUNDLE_LIMITS = Object.freeze({ files: 256, lockBytes: 1024 * 1024, jsonBytes: 16 * 1024 * 1024, chunks: 1024 });
+const digest = bytes => createHash('sha256').update(bytes).digest('hex');
+const reject = (message, code = BlenderErrorCode.ASSET_REQUEST_INVALID) => { throw new BlenderError(code, message); };
+export function bundlePath(path) {
+    if (typeof path !== 'string' || !path || path.length > 1024 || path.includes('\\') || /[\0-\x1f]/.test(path)
+        || path.startsWith('/') || path.split('/').some(p => !p || p === '.' || p === '..' || /[:<>"|?*]/.test(p)))
+        reject('Asset bundle members need contained, portable relative paths.');
+    return path;
+}
+export function gltfResources(document, entrypoint, binBytes = null) {
+    if (!document || Array.isArray(document) || document.asset?.version !== '2.0')
+        reject('The glTF JSON must declare version 2.0.', BlenderErrorCode.ASSET_CONTENT_MISMATCH);
+    const paths = new Set();
+    for (const key of ['buffers', 'images']) {
+        if (document[key] !== undefined && !Array.isArray(document[key]))
+            reject(`glTF ${key} must be an array.`);
+        for (const [index, item] of (document[key] ?? []).entries()) {
+            if (!item || typeof item !== 'object' || Array.isArray(item))
+                reject(`Invalid glTF ${key} entry.`);
+            const uri = item.uri;
+            if (uri === undefined) {
+                if (key === 'buffers' && (index !== 0 || binBytes === null || !Number.isSafeInteger(item.byteLength)
+                    || item.byteLength < 0 || item.byteLength > binBytes || binBytes - item.byteLength > 3))
+                    reject('An embedded buffer requires the first GLB buffer and a matching BIN chunk.');
+                continue;
+            }
+            if (typeof uri !== 'string' || !uri)
+                reject('glTF resource URIs must be nonempty strings.');
+            if (uri.startsWith('data:')) {
+                if (!/^data:[^,]*;base64,[A-Za-z0-9+/]*={0,2}$/.test(uri) || uri.split(',')[1].length % 4)
+                    reject('glTF embedded resources need valid base64 data URIs.');
+                continue;
+            }
+            if (uri.startsWith('/') || uri.includes('\\') || /[?#]/.test(uri) || /^[a-z][a-z0-9+.-]*:/i.test(uri))
+                reject('glTF resources must use relative file URIs or embedded data. No dependency URLs are fetched.');
+            let decoded;
+            try {
+                decoded = decodeURIComponent(uri);
+            }
+            catch {
+                reject('A glTF resource URI has invalid percent encoding.');
+            }
+            if (decoded.startsWith('/') || decoded.includes('\\') || /[\0-\x1f]/.test(decoded))
+                reject('Invalid glTF resource path.');
+            const path = bundlePath(posix.normalize(posix.join(posix.dirname(entrypoint), decoded)));
+            if (path === BUNDLE_LOCK)
+                reject('A glTF resource collides with the reserved bundle lock.');
+            paths.add(path);
+        }
+    }
+    // Core buffers/images cover the importer-facing resource graph in this profile.
+    // Refuse additional external URI fields in extensions rather than leave them unlocked.
+    const queue = [{ value: document, extension: false }];
+    for (let index = 0; index < queue.length; index++) {
+        if (index > 500000)
+            reject('The glTF document exceeds the resource inspection limit.', BlenderErrorCode.ASSET_TOO_LARGE);
+        const { value, extension } = queue[index];
+        if (!value || typeof value !== 'object')
+            continue;
+        if (extension && typeof value.uri === 'string' && !/^data:/i.test(value.uri))
+            reject('External URI resources inside glTF extensions need a supported dependency profile.');
+        for (const [key, child] of Object.entries(value))
+            if (child && typeof child === 'object')
+                queue.push({ value: child, extension: extension || key === 'extensions' });
+    }
+    if (paths.size + 1 > BUNDLE_LIMITS.files)
+        reject('The glTF bundle exceeds the resource file limit.', BlenderErrorCode.ASSET_TOO_LARGE);
+    const folded = new Set();
+    for (const path of [entrypoint, ...paths]) {
+        const key = path.toLowerCase();
+        if (folded.has(key) && path !== entrypoint)
+            reject('glTF resource paths collide on case-insensitive filesystems.');
+        folded.add(key);
+    }
+    return [...paths].sort();
+}
+function readBounded(file, limit) {
+    const fd = openSync(file, 'r'), chunks = [];
+    let bytes = 0;
+    try {
+        const buffer = Buffer.alloc(64 * 1024);
+        for (;;) {
+            const size = readSync(fd, buffer, 0, buffer.length, null);
+            if (!size)
+                break;
+            bytes += size;
+            if (bytes > limit)
+                reject('Asset bundle metadata exceeds its byte limit.', BlenderErrorCode.ASSET_TOO_LARGE);
+            chunks.push(Buffer.from(buffer.subarray(0, size)));
+        }
+        return Buffer.concat(chunks, bytes);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function parseJson(bytes) { return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)); }
+function objReference(entrypoint, name) {
+    if (!name || name.startsWith('/') || name.includes('\\') || /^[a-z][a-z0-9+.-]*:/i.test(name))
+        reject('OBJ resources require portable relative file paths. No dependency URLs are fetched.');
+    const path = bundlePath(posix.normalize(posix.join(posix.dirname(entrypoint), name)));
+    if (path === BUNDLE_LOCK) reject('An OBJ resource collides with the reserved bundle lock.');
+    return path;
+}
+/** Includes Blender's same-basename MTL lookup as well as explicit libraries. */
+export function objResources(root, entrypoint, { mainFile, signal, missingCode = BlenderErrorCode.ASSET_MISSING, implicit = true } = {}) {
+    const main = mainFile ?? resolveInside(root, entrypoint, 'OBJ entrypoint');
+    const libraries = new Set(objLibraries(main, { signal }).map(name => objReference(entrypoint, name)));
+    const fallback = entrypoint.replace(/\.[^/.]+$/, '.mtl');
+    if (implicit && existsSync(resolveInside(root, fallback, 'OBJ implicit library'))) libraries.add(fallback);
+    const paths = new Set(libraries), folded = new Map([[entrypoint.toLowerCase(), entrypoint]]);
+    const check = path => {
+        const previous = folded.get(path.toLowerCase());
+        if (previous && previous !== path) reject('OBJ resource paths collide on case-insensitive filesystems.');
+        folded.set(path.toLowerCase(), path);
+        if (new Set([entrypoint, ...paths]).size > BUNDLE_LIMITS.files) reject('The OBJ bundle exceeds the resource file limit.', BlenderErrorCode.ASSET_TOO_LARGE);
+    };
+    for (const library of libraries) {
+        signal?.throwIfAborted(); check(library);
+        const file = resolveInside(root, library, 'OBJ material library');
+        if (!existsSync(file) || !statSync(file).isFile()) reject(`The OBJ material library ${library} is missing.`, missingCode);
+        for (const name of mtlImages(file, { signal })) { const path = objReference(library, name); paths.add(path); check(path); }
+    }
+    for (const path of paths) check(path);
+    return [...paths].sort();
+}
+/** Read only JSON and chunk headers. Large GLB binary payloads stay on disk. */
+export function readGltfDocument(file, { format = 'gltf', signal } = {}) {
+    try {
+        signal?.throwIfAborted();
+        if (format === 'gltf')
+            return { document: parseJson(readBounded(file, BUNDLE_LIMITS.jsonBytes)), binBytes: null };
+        if (format !== 'glb')
+            reject('Unsupported asset bundle format.');
+        const fd = openSync(file, 'r');
+        try {
+            const size = fstatSync(fd).size;
+            const read = (offset, length) => {
+                const bytes = Buffer.alloc(length);
+                let received = 0;
+                while (received < length) {
+                    signal?.throwIfAborted();
+                    const n = readSync(fd, bytes, received, length - received, offset + received);
+                    if (!n)
+                        reject('The GLB is truncated.', BlenderErrorCode.ASSET_CONTENT_MISMATCH);
+                    received += n;
+                }
+                return bytes;
+            };
+            if (size < 20)
+                reject('The GLB header is truncated.', BlenderErrorCode.ASSET_CONTENT_MISMATCH);
+            const header = read(0, 12);
+            if (header.toString('ascii', 0, 4) !== 'glTF' || header.readUInt32LE(4) !== 2 || header.readUInt32LE(8) !== size)
+                reject('The GLB must be a complete version 2 container.', BlenderErrorCode.ASSET_CONTENT_MISMATCH);
+            let offset = 12, document = null, binBytes = null, chunks = 0, jsonSeen = false;
+            while (offset < size) {
+                signal?.throwIfAborted();
+                if (++chunks > BUNDLE_LIMITS.chunks)
+                    reject('The GLB exceeds the chunk inspection limit.', BlenderErrorCode.ASSET_TOO_LARGE);
+                if (offset + 8 > size)
+                    reject('The GLB chunk header is truncated.', BlenderErrorCode.ASSET_CONTENT_MISMATCH);
+                const chunk = read(offset, 8), length = chunk.readUInt32LE(0), kind = chunk.readUInt32LE(4);
+                if (length % 4 || offset + 8 + length > size)
+                    reject('The GLB chunk length is invalid.', BlenderErrorCode.ASSET_CONTENT_MISMATCH);
+                if (chunks === 1 && kind !== 0x4e4f534a)
+                    reject('The first GLB chunk must contain JSON.', BlenderErrorCode.ASSET_CONTENT_MISMATCH);
+                if (kind === 0x4e4f534a) {
+                    if (jsonSeen)
+                        reject('The GLB contains duplicate JSON chunks.', BlenderErrorCode.ASSET_CONTENT_MISMATCH);
+                    if (length > BUNDLE_LIMITS.jsonBytes)
+                        reject('The GLB JSON exceeds 16 MiB.', BlenderErrorCode.ASSET_TOO_LARGE);
+                    jsonSeen = true;
+                    document = parseJson(read(offset + 8, length));
+                }
+                else if (kind === 0x004e4942) {
+                    if (chunks !== 2 || binBytes !== null)
+                        reject('The GLB BIN must be its second chunk.', BlenderErrorCode.ASSET_CONTENT_MISMATCH);
+                    binBytes = length;
+                }
+                offset += 8 + length;
+            }
+            if (!document || Array.isArray(document) || document.asset?.version !== '2.0')
+                reject('The GLB JSON must declare glTF 2.0.', BlenderErrorCode.ASSET_CONTENT_MISMATCH);
+            return { document, binBytes };
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch (error) {
+        signal?.throwIfAborted();
+        if (error instanceof BlenderError)
+            throw error;
+        reject('The glTF metadata cannot be parsed.', BlenderErrorCode.ASSET_CONTENT_MISMATCH);
+    }
+}
+export function verifyAssetBundle(projectRoot, asset) {
+    const match = /^assets\/bundles\/([a-f0-9]{64})\/(.+)$/.exec(asset.path ?? '');
+    if (!match)
+        return null;
+    const root = resolveInside(projectRoot, `assets/bundles/${match[1]}`, 'asset bundle'), lock = resolveInside(root, BUNDLE_LOCK, 'asset bundle lock');
+    if (!existsSync(lock))
+        reject('The asset bundle lock is missing.', BlenderErrorCode.ASSET_MISSING);
+    const bytes = readBounded(lock, BUNDLE_LIMITS.lockBytes);
+    if (digest(bytes) !== match[1])
+        reject('The asset bundle lock changed.', BlenderErrorCode.ASSET_HASH_MISMATCH);
+    let manifest;
+    try {
+        manifest = parseJson(bytes);
+    }
+    catch {
+        reject('The asset bundle lock cannot be parsed.');
+    }
+    if (manifest?.schemaVersion !== 'deepblend.asset-bundle/v1' || manifest.entrypoint !== match[2]
+        || !Array.isArray(manifest.files) || !manifest.files.length || manifest.files.length > BUNDLE_LIMITS.files)
+        reject('The asset bundle lock has an invalid shape or entrypoint.');
+    bundlePath(manifest.entrypoint);
+    const format = manifest.format ?? 'gltf';
+    if (!['gltf', 'glb', 'obj'].includes(format) || (asset.type && asset.type !== format))
+        reject('The asset bundle format does not match its declaration.');
+    const members = new Map(), folded = new Set();
+    let total = 0;
+    for (const member of manifest.files) {
+        if (!member || typeof member !== 'object' || Array.isArray(member))
+            reject('Invalid asset bundle member.');
+        const path = bundlePath(member.path);
+        if (path === BUNDLE_LOCK || members.has(path) || folded.has(path.toLowerCase()) || !/^[a-f0-9]{64}$/.test(member.sha256 ?? '') || !Number.isSafeInteger(member.bytes) || member.bytes < 0)
+            reject('The asset bundle lock contains invalid or duplicate members.');
+        const file = resolveInside(root, path, 'asset bundle member');
+        if (!existsSync(file))
+            reject(`The asset bundle member ${path} is missing.`, BlenderErrorCode.ASSET_MISSING);
+        if (!statSync(file).isFile() || statSync(file).size !== member.bytes || fileSha256(file) !== member.sha256)
+            reject(`The asset bundle member ${path} changed.`, BlenderErrorCode.ASSET_HASH_MISMATCH);
+        members.set(path, member);
+        folded.add(path.toLowerCase());
+        total += member.bytes;
+    }
+    if (!Number.isSafeInteger(total) || total !== manifest.totalBytes || !members.has(manifest.entrypoint)
+        || (asset.sha256 && asset.sha256 !== members.get(manifest.entrypoint).sha256))
+        reject('The asset bundle identity does not agree with its declaration.', BlenderErrorCode.ASSET_HASH_MISMATCH);
+    const content = format === 'obj' ? null : readGltfDocument(resolveInside(root, manifest.entrypoint, 'glTF entrypoint'), { format });
+    const resources = format === 'obj' ? objResources(root, manifest.entrypoint) : gltfResources(content.document, manifest.entrypoint, content.binBytes);
+    for (const path of resources)
+        if (!members.has(path))
+            reject(`The glTF resource ${path} is not locked.`);
+    return manifest;
+}
+export function verifyUnbundledObjAsset(projectRoot, asset) {
+    if (asset.type !== 'obj' || /^assets\/bundles\/[a-f0-9]{64}\//.test(asset.path ?? '')) return;
+    const file = resolveInside(projectRoot, asset.path, 'OBJ asset');
+    const fallback = asset.path.replace(/\.[^/.]+$/, '.mtl');
+    if (objLibraries(file).length || existsSync(resolveInside(projectRoot, fallback, 'OBJ implicit library')))
+        reject('This OBJ has unlocked material resources. Reimport the complete local source with a containing sourceRoot.');
+}
+/** Legacy files can rebuild only when the main file contains all core resources. */
+export function verifyUnbundledGltfAsset(projectRoot, asset) {
+    if (!['gltf', 'glb'].includes(asset.type) || /^assets\/bundles\/[a-f0-9]{64}\//.test(asset.path ?? ''))
+        return;
+    const file = resolveInside(projectRoot, asset.path, 'glTF asset');
+    const content = readGltfDocument(file, { format: asset.type });
+    if (gltfResources(content.document, posix.basename(asset.path), content.binBytes).length)
+        reject('This glTF/GLB has unlocked external resources. Reimport its local source with a containing sourceRoot to create a resource snapshot.');
+}
+/** Dependency identity is encoded in the managed path, independently of main-file SHA. */
+export function assetPreviewVersion(asset) {
+    return /^assets\/bundles\/([a-f0-9]{64})\//.exec(asset.path ?? '')?.[1] ?? asset.sha256;
+}
+/** Copy and reverify a complete immutable snapshot in the disposable preview root. */
+export async function stageAssetBundle(projectRoot, directory, asset, { maxBytes, signal } = {}) {
+    signal?.throwIfAborted();
+    const manifest = verifyAssetBundle(projectRoot, asset);
+    if (!manifest) return false;
+    const prefix = `assets/bundles/${assetPreviewVersion(asset)}`;
+    let total = 0;
+    for (const path of [...manifest.files.map(member => member.path), BUNDLE_LOCK]) {
+        signal?.throwIfAborted();
+        const source = resolveInside(projectRoot, `${prefix}/${path}`, 'preview bundle source');
+        const target = resolveInside(directory, `${prefix}/${path}`, 'preview bundle copy');
+        mkdirSync(dirname(target), { recursive: true });
+        const copied = await streamAsset(createReadStream(source), target, { maxBytes: maxBytes - total, signal, label: path });
+        total += copied.bytes;
+        const expected = manifest.files.find(member => member.path === path);
+        if (expected && (expected.bytes !== copied.bytes || expected.sha256 !== copied.sha256))
+            reject('The asset bundle changed while preparing its preview.', BlenderErrorCode.ASSET_HASH_MISMATCH);
+    }
+    verifyAssetBundle(directory, asset);
+    return true;
+}
+export async function prepareModelBundle({ projectRoot, sourcePath, name, sourceRoot, local, maxBytes, signal, type = 'gltf', stagingRoot }) {
+    if (sourceRoot !== undefined && (!local || typeof sourceRoot !== 'string' || !sourceRoot))
+        reject('sourceRoot requires a local model source directory.');
+    const sourceBase = resolve(sourceRoot ?? dirname(sourcePath)), entrypoint = bundlePath(local ? relative(sourceBase, resolve(sourcePath)).split(sep).join('/') : name);
+    resolveInside(sourceBase, sourcePath, 'model source');
+    const parent = resolveInside(projectRoot, 'assets/bundles', 'asset bundle directory');
+    mkdirSync(parent, { recursive: true });
+    // Browser upload sessions supply a Host-owned staging root on the same
+    // project filesystem. Their partial files stay inside that session.
+    const staging = stagingRoot ? resolveInside(stagingRoot, `.bundle-${randomUUID()}`, 'bundle preparation') : join(parent, `.incoming-${randomUUID()}`);
+    mkdirSync(staging);
+    try {
+        const files = [];
+        let totalBytes = 0;
+        const copy = async (path, sourceOverride) => {
+            signal?.throwIfAborted();
+            const source = resolveInside(sourceBase, sourceOverride ?? path, 'model resource'), target = resolveInside(staging, path, 'staged model resource');
+            if (!existsSync(source) || !statSync(source).isFile())
+                reject(`The local model resource ${path} is missing.`, BlenderErrorCode.ASSET_SOURCE_NOT_FOUND);
+            mkdirSync(dirname(target), { recursive: true });
+            const result = await streamAsset(createReadStream(source), target, { maxBytes: maxBytes - totalBytes, signal, label: path });
+            totalBytes += result.bytes;
+            files.push({ path, ...result });
+        };
+        await copy(entrypoint, local ? undefined : sourcePath);
+        const content = type === 'obj' ? null : readGltfDocument(join(staging, entrypoint), { format: type, signal });
+        if (type === 'obj' && !local && objLibraries(join(staging, entrypoint), { signal }).length)
+            reject('Remote OBJ material dependencies are not fetched. Import a complete local resource directory.');
+        const resources = type === 'obj'
+            ? objResources(sourceBase, entrypoint, { mainFile: join(staging, entrypoint), signal, implicit: local, missingCode: BlenderErrorCode.ASSET_SOURCE_NOT_FOUND })
+            : gltfResources(content.document, entrypoint, content.binBytes);
+        if (!local && resources.length)
+            reject('Remote glTF dependencies are not fetched. Import a local resource directory or a self-contained file.');
+        for (const path of resources)
+            if (path !== entrypoint)
+                await copy(path);
+        if (type === 'obj') {
+            const copied = new Set(files.map(file => file.path));
+            for (const path of objResources(staging, entrypoint, { signal }))
+                if (!copied.has(path)) reject('An OBJ material reference changed during import.', BlenderErrorCode.ASSET_HASH_MISMATCH);
+        }
+        if (type === 'glb' && resources.length === 0) {
+            const main = files[0], relativePath = `assets/raw/${main.sha256}.glb`;
+            return { staging, relativePath, sourceRoot: local ? sourceBase : null, bytes: main.bytes, sha256: main.sha256, bundle: null, publish() {
+                    const destination = resolveInside(projectRoot, relativePath, 'GLB destination');
+                    mkdirSync(dirname(destination), { recursive: true });
+                    try {
+                        linkSync(join(staging, entrypoint), destination);
+                    }
+                    catch (error) {
+                        if (error.code !== 'EEXIST')
+                            throw error;
+                        if (fileSha256(destination) !== main.sha256)
+                            reject('The stored GLB changed.', BlenderErrorCode.ASSET_HASH_MISMATCH);
+                    }
+                    return destination;
+                } };
+        }
+        files.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+        const manifest = { schemaVersion: 'deepblend.asset-bundle/v1', ...(type !== 'gltf' ? { format: type } : {}), entrypoint, files, totalBytes }, lockBytes = Buffer.from(JSON.stringify(manifest) + '\n');
+        if (totalBytes + lockBytes.length > maxBytes)
+            reject('The model bundle and lock exceed assetMaxBytes.', BlenderErrorCode.ASSET_TOO_LARGE);
+        if (lockBytes.length > BUNDLE_LIMITS.lockBytes)
+            reject('The asset bundle lock exceeds its byte limit.', BlenderErrorCode.ASSET_TOO_LARGE);
+        writeFileSync(join(staging, BUNDLE_LOCK), lockBytes, { flag: 'wx' });
+        const bundleSha256 = digest(lockBytes), relativePath = `assets/bundles/${bundleSha256}/${entrypoint}`, main = files.find(file => file.path === entrypoint);
+        return { staging, relativePath, sourceRoot: local ? sourceBase : null, bytes: main.bytes, sha256: main.sha256, bundle: { sha256: bundleSha256, ...manifest }, publish() {
+                const destination = resolveInside(projectRoot, `assets/bundles/${bundleSha256}`, 'asset bundle destination');
+                try {
+                    renameSync(staging, destination);
+                }
+                catch (error) {
+                    if (!['EEXIST', 'ENOTEMPTY'].includes(error.code))
+                        throw error;
+                    verifyAssetBundle(projectRoot, { path: relativePath, sha256: main.sha256, type });
+                }
+                return destination;
+            } };
+    }
+    catch (error) {
+        removeTree(staging);
+        throw error;
+    }
+}

package/lib/asset-io.js

@@ -0,0 +1,24 @@
+/** Bounded asset streaming. The digest covers exactly the bytes written. */
+import { createHash } from 'node:crypto'
+import { createWriteStream } from 'node:fs'
+import { Transform } from 'node:stream'
+import { pipeline } from 'node:stream/promises'
+import { BlenderError, BlenderErrorCode } from '@deepblend/dsh-blender-contracts'
+
+export async function streamAsset(source, target, { maxBytes, signal, label = 'asset', onBytes }) {
+  const hash = createHash('sha256')
+  let bytes = 0
+  const meter = new Transform({
+    transform(chunk, encoding, callback) {
+      bytes += chunk.length
+      try { onBytes?.(bytes) } catch (error) { callback(error); return }
+      if (bytes > maxBytes) return callback(new BlenderError(BlenderErrorCode.ASSET_TOO_LARGE,
+        `${label} exceeds the configured assetMaxBytes of ${maxBytes}; the transfer was stopped.`,
+        { detail: { received: bytes, maxBytes } }))
+      hash.update(chunk)
+      callback(null, chunk)
+    },
+  })
+  await pipeline(source, meter, createWriteStream(target, { flags: 'wx' }), { signal })
+  return { bytes, sha256: hash.digest('hex') }
+}

package/lib/asset-library.js

@@ -0,0 +1,113 @@
+/** Bounded local asset inspection. Original bytes are never rewritten. */
+import { createHash } from 'node:crypto'
+import { createReadStream } from 'node:fs'
+import { open } from 'node:fs/promises'
+import { extname } from 'node:path'
+import { readGltfDocument, gltfResources } from './asset-bundle.js'
+import { BlenderError, BlenderErrorCode, assetContentVerdict } from '@deepblend/dsh-blender-contracts'
+
+export const ASSET_LIBRARY_LIMITS = Object.freeze({
+  maxImagePixels: 64 * 1024 * 1024,
+  maxImageEdge: 8192,
+  maxGlbJsonBytes: 16 * 1024 * 1024,
+  previewWidth: 512,
+  previewHeight: 384,
+  previewSamples: 16,
+})
+
+const MIME_BY_TYPE = Object.freeze({
+  glb: ['model/gltf-binary'], png: ['image/png'], jpg: ['image/jpeg'], jpeg: ['image/jpeg'],
+  hdr: ['image/vnd.radiance', 'image/x-hdr'], exr: ['image/x-exr', 'image/exr'],
+})
+
+function reject(message, code = BlenderErrorCode.ASSET_CONTENT_MISMATCH) {
+  throw new BlenderError(code, message)
+}
+
+export function uploadAssetType(name, mediaType) {
+  const type = extname(name).slice(1).toLowerCase()
+  if (!Object.hasOwn(MIME_BY_TYPE, type)) reject('Choose a GLB, PNG, JPEG, HDR or EXR file.', BlenderErrorCode.ASSET_REQUEST_INVALID)
+  if (mediaType !== undefined && typeof mediaType !== 'string') reject('The upload media type must be text.', BlenderErrorCode.ASSET_REQUEST_INVALID)
+  const mime = (mediaType ?? '').split(';')[0].trim().toLowerCase()
+  if (mime && mime !== 'application/octet-stream' && !MIME_BY_TYPE[type].includes(mime)) {
+    reject('The file extension and upload media type do not agree.')
+  }
+  return type
+}
+
+/** Inspect bounded GLB metadata; the upload profile requires all core resources embedded. */
+export async function inspectSelfContainedGlb(path, { signal } = {}) {
+  const { document, binBytes } = readGltfDocument(path, { format: 'glb', signal })
+  if (gltfResources(document, 'upload.glb', binBytes).length) {
+    reject('Upload a self-contained GLB. External buffers and image files are not copied or fetched.', BlenderErrorCode.ASSET_REQUEST_INVALID)
+  }
+  return {
+    animations: Array.isArray(document.animations) ? document.animations.length : 0,
+    cameras: Array.isArray(document.cameras) ? document.cameras.length : 0,
+    lights: Array.isArray(document.extensions?.KHR_lights_punctual?.lights) ? document.extensions.KHR_lights_punctual.lights.length : 0,
+  }
+}
+
+export async function checkAssetUpload(path, type, { signal } = {}) {
+  signal?.throwIfAborted()
+  const handle = await open(path, 'r')
+  try {
+    const head = Buffer.alloc(512)
+    const { bytesRead } = await handle.read(head, 0, head.length, 0)
+    if (assetContentVerdict(head.subarray(0, bytesRead), type) === 'contradicts') {
+      reject('The uploaded bytes contradict the file extension.')
+    }
+  } finally { await handle.close() }
+  return type === 'glb' ? inspectSelfContainedGlb(path, { signal }) : null
+}
+
+/** Hash incrementally, including while checking large staged model files. */
+export async function hashAssetFile(path, { maxBytes, signal } = {}) {
+  const hash = createHash('sha256')
+  let bytes = 0
+  for await (const chunk of createReadStream(path, { signal })) {
+    bytes += chunk.length
+    if (maxBytes !== undefined && bytes > maxBytes) reject('The asset exceeds the configured byte limit.', BlenderErrorCode.ASSET_TOO_LARGE)
+    hash.update(chunk)
+  }
+  signal?.throwIfAborted()
+  return { bytes, sha256: hash.digest('hex') }
+}
+
+/** Decode the complete stored image, then make a bounded PNG derivative. */
+export async function previewRasterAsset(path, type, outputPath, { signal } = {}) {
+  signal?.throwIfAborted()
+  const { default: sharp } = await import('sharp')
+  const inputOptions = { failOn: 'warning', limitInputPixels: ASSET_LIBRARY_LIMITS.maxImagePixels, sequentialRead: true }
+  const source = sharp(path, inputOptions)
+  // Sharp is both a Promise API and a Duplex. destroy(error) can reject the
+  // operation AND emit a stream error; the latter needs its own listener.
+  // Keep it for the object's lifetime because destroy emits asynchronously.
+  source.on('error', () => {})
+  const abort = () => source.destroy(signal.reason instanceof Error ? signal.reason : new Error('Asset preview cancelled.'))
+  signal?.addEventListener('abort', abort, { once: true })
+  try {
+    const metadata = await source.metadata()
+    const expected = type === 'png' ? 'png' : 'jpeg'
+    if (metadata.format !== expected) reject('The image decoder found a different format from the declared asset type.')
+    if (!Number.isInteger(metadata.width) || !Number.isInteger(metadata.height)
+      || metadata.width < 1 || metadata.height < 1 || metadata.width > ASSET_LIBRARY_LIMITS.maxImageEdge
+      || metadata.height > ASSET_LIBRARY_LIMITS.maxImageEdge || metadata.width * metadata.height > ASSET_LIBRARY_LIMITS.maxImagePixels) {
+      reject('The image exceeds the asset library pixel or edge limit.', BlenderErrorCode.ASSET_TOO_LARGE)
+    }
+    if ((metadata.pages ?? 1) !== 1) reject('Asset library images must contain a single still image.', BlenderErrorCode.ASSET_REQUEST_INVALID)
+    signal?.throwIfAborted()
+    const result = await source.resize({ width: ASSET_LIBRARY_LIMITS.previewWidth, height: ASSET_LIBRARY_LIMITS.previewHeight,
+      fit: 'inside', withoutEnlargement: true }).png().toFile(outputPath)
+    signal?.throwIfAborted()
+    return {
+      image: { width: metadata.width, height: metadata.height, channels: metadata.channels,
+        format: expected, orientation: metadata.orientation ?? 1, colorSpace: metadata.space },
+      preview: { width: result.width, height: result.height, mime: 'image/png', toneMapped: false },
+    }
+  } catch (cause) {
+    signal?.throwIfAborted()
+    if (cause instanceof BlenderError) throw cause
+    throw new BlenderError(BlenderErrorCode.ASSET_CONTENT_MISMATCH, 'The image could not be completely decoded.', { cause })
+  } finally { signal?.removeEventListener('abort', abort) }
+}