@spawndotfamily/sdk 0.2.7

package/dist/cli/upload-client.js

@@ -0,0 +1,737 @@
+import { PublishCliError, isRecord, requestJson, validatePublishConfig, } from "./api.js";
+// @ts-ignore Node's runtime modules are available to the CLI without adding a runtime dependency.
+import { createHash } from 'node:crypto';
+// @ts-ignore Node's runtime modules are available to the CLI without adding a runtime dependency.
+import { constants } from 'node:fs';
+// @ts-ignore Node's runtime modules are available to the CLI without adding a runtime dependency.
+import { lstat, open, opendir, realpath } from 'node:fs/promises';
+// @ts-ignore Node's runtime modules are available to the CLI without adding a runtime dependency.
+import { basename, join, relative, resolve, sep } from 'node:path';
+/** The worker contract fixes every upload chunk at eight mebibytes. */
+export const CHUNK_BYTES = 8_388_608;
+/** Safety ceiling for client-side inspection; the platform's default admission is 1 GB. */
+export const STREAM_MAX_TOTAL_BYTES = 8_000_000_000;
+export const STREAM_MAX_FILE_BYTES = 8_000_000_000;
+export const STREAM_MAX_HTML_BYTES = 1_000_000;
+export const STREAM_MAX_FILES = 1_000;
+export const STREAM_MAX_TRAVERSED_ENTRIES = 10_000;
+export const STREAM_MAX_DIRECTORY_DEPTH = 64;
+export const STREAM_MAX_RETRIES = 3;
+const BROWSER_ASSET_EXTENSIONS = new Set([
+    'html',
+    'js',
+    'mjs',
+    'css',
+    'json',
+    'wasm',
+    'data',
+    'pck',
+    'unityweb',
+    'bundle',
+    'png',
+    'jpg',
+    'jpeg',
+    'webp',
+    'gif',
+    'svg',
+    'ico',
+    'avif',
+    'mp3',
+    'ogg',
+    'wav',
+    'mp4',
+    'webm',
+    'woff',
+    'woff2',
+    'ttf',
+    'otf',
+    'txt',
+    'atlas',
+    'bin',
+    'glb',
+    'gltf',
+    'ktx2',
+]);
+const SECRET_NAME = /(^|[._-])(secret|secrets|credential|credentials|private[_-]?key|api[_-]?key|access[_-]?token|auth[_-]?token|password|passwd|token)([._-]|$)/i;
+const SECRET_SUFFIX = /\.(pem|key|p12|pfx|jks|keystore|crt)$/i;
+const PRIVATE_KEY_MARKER = /-----BEGIN(?: [A-Z]+)? PRIVATE KEY-----/;
+const SOURCE_SECRET_MARKER = /(?:["']?(?:publish[_-]?key|private[_-]?key|client[_-]?secret|api[_-]?key|access[_-]?token)["']?\s*[:=]|sp_pub_[A-Za-z0-9_-]{20,})/i;
+function fail(message) {
+    throw new PublishCliError(message);
+}
+function formatLimit(value) {
+    return value.toLocaleString('en-US');
+}
+function hashFactory() {
+    return createHash;
+}
+function validateSourceCommit(value) {
+    if (!/^[0-9a-f]{40}$/i.test(value)) {
+        throw new PublishCliError('sourceCommit must contain exactly 40 hexadecimal characters.');
+    }
+    return value;
+}
+function compareCodePoints(left, right) {
+    const a = Array.from(left, (character) => character.codePointAt(0) ?? 0);
+    const b = Array.from(right, (character) => character.codePointAt(0) ?? 0);
+    const length = Math.min(a.length, b.length);
+    for (let index = 0; index < length; index += 1) {
+        if (a[index] !== b[index])
+            return a[index] - b[index];
+    }
+    return a.length - b.length;
+}
+function snapshot(stat) {
+    return {
+        ino: stat.ino,
+        dev: stat.dev,
+        size: stat.size,
+        ...(typeof stat.mtimeMs === 'number' ? { mtimeMs: stat.mtimeMs } : {}),
+        ...(typeof stat.ctimeMs === 'number' ? { ctimeMs: stat.ctimeMs } : {}),
+    };
+}
+function sameSnapshot(left, right) {
+    return left.ino === right.ino &&
+        left.dev === right.dev &&
+        left.size === right.size &&
+        (left.mtimeMs === undefined || right.mtimeMs === undefined || left.mtimeMs === right.mtimeMs) &&
+        (left.ctimeMs === undefined || right.ctimeMs === undefined || left.ctimeMs === right.ctimeMs);
+}
+function validateSegment(segment) {
+    if (!segment || segment === '.' || segment === '..' || segment.startsWith('.')) {
+        throw new PublishCliError('Hidden files and dot segments are not allowed in browser builds.');
+    }
+    if (['node_modules', '__MACOSX'].includes(segment.toLowerCase())) {
+        throw new PublishCliError('node_modules and __MACOSX are not allowed in browser builds.');
+    }
+    if (SECRET_NAME.test(segment) || SECRET_SUFFIX.test(segment)) {
+        throw new PublishCliError('Source secret files are not allowed in browser builds.');
+    }
+}
+function extensionOf(filePath) {
+    const name = basename(filePath);
+    const dot = name.lastIndexOf('.');
+    return dot > 0 && dot < name.length - 1 ? name.slice(dot + 1).toLowerCase() : '';
+}
+function validateBrowserAsset(filePath) {
+    if (extensionOf(filePath) === 'map') {
+        throw new PublishCliError('Source maps (.map) are not accepted in browser builds.');
+    }
+    if (!BROWSER_ASSET_EXTENSIONS.has(extensionOf(filePath))) {
+        throw new PublishCliError(`Unsupported browser asset extension for ${extensionOf(filePath) || 'file'}.`);
+    }
+}
+function assertRelativePayloadPath(filePath) {
+    if (filePath.length < 1 ||
+        filePath.length > 240 ||
+        filePath.startsWith('/') ||
+        filePath.includes('\\') ||
+        !/^[A-Za-z0-9_][A-Za-z0-9_./ -]*$/.test(filePath)) {
+        throw new PublishCliError('Browser bundle paths must be safe relative POSIX paths.');
+    }
+    const segments = filePath.split('/');
+    if (segments.some((segment) => !segment || segment === '.' || segment === '..')) {
+        throw new PublishCliError('Browser bundle paths cannot contain dot segments.');
+    }
+}
+function inspectTextChunk(bytes, decoder, carry, entry, captureEntry, forbiddenSecret) {
+    const decoded = decoder.decode(bytes, { stream: true });
+    const text = carry.value + decoded;
+    if (PRIVATE_KEY_MARKER.test(text) || SOURCE_SECRET_MARKER.test(text)) {
+        throw new PublishCliError('Private key material is not allowed in browser builds.');
+    }
+    if (forbiddenSecret && text.includes(forbiddenSecret)) {
+        throw new PublishCliError('Publishing credentials must not appear in browser build files.');
+    }
+    carry.value = text.slice(-Math.max(512, forbiddenSecret ? forbiddenSecret.length - 1 : 0));
+    if (captureEntry && entry.value.length <= STREAM_MAX_HTML_BYTES)
+        entry.value += decoded;
+}
+async function inspectFile(absolutePath, stat, isEntry, isHtml, forbiddenSecret) {
+    if (stat.size > STREAM_MAX_FILE_BYTES) {
+        throw new PublishCliError(`A browser asset exceeds the ${formatLimit(STREAM_MAX_FILE_BYTES)} byte file limit.`);
+    }
+    if (isHtml && stat.size > STREAM_MAX_HTML_BYTES) {
+        throw new PublishCliError(`An HTML file exceeds the ${formatLimit(STREAM_MAX_HTML_BYTES)} byte limit.`);
+    }
+    let handle;
+    try {
+        handle = await open(absolutePath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+        const opened = await handle.stat();
+        if (!opened.isFile() || opened.isSymbolicLink() || !sameSnapshot(opened, stat)) {
+            fail('Build file changed while it was being inspected.');
+        }
+        const hash = hashFactory()('sha256');
+        const chunkSha256 = [];
+        let chunkHash = hashFactory()('sha256');
+        let chunkOffset = 0;
+        const buffer = new Uint8Array(Math.min(1_048_576, STREAM_MAX_FILE_BYTES));
+        const decoder = new TextDecoder();
+        const carry = { value: '' };
+        const entry = { value: '' };
+        let bytes = 0;
+        while (bytes < stat.size) {
+            const want = Math.min(buffer.byteLength, stat.size - bytes);
+            const { bytesRead } = await handle.read(buffer, 0, want, bytes);
+            if (bytesRead <= 0)
+                fail('Build file ended while it was being inspected.');
+            const chunk = buffer.subarray(0, bytesRead);
+            hash.update(chunk);
+            let chunkCursor = 0;
+            while (chunkCursor < chunk.byteLength) {
+                const chunkLength = Math.min(chunk.byteLength - chunkCursor, CHUNK_BYTES - chunkOffset);
+                chunkHash.update(chunk.subarray(chunkCursor, chunkCursor + chunkLength));
+                chunkCursor += chunkLength;
+                chunkOffset += chunkLength;
+                if (chunkOffset === CHUNK_BYTES) {
+                    chunkSha256.push(chunkHash.digest('hex'));
+                    chunkHash = hashFactory()('sha256');
+                    chunkOffset = 0;
+                }
+            }
+            inspectTextChunk(chunk, decoder, carry, entry, isEntry, forbiddenSecret);
+            bytes += bytesRead;
+        }
+        const finalText = decoder.decode();
+        const finalScan = carry.value + finalText;
+        if (PRIVATE_KEY_MARKER.test(finalScan) || SOURCE_SECRET_MARKER.test(finalScan)) {
+            throw new PublishCliError('Private key material is not allowed in browser builds.');
+        }
+        if (forbiddenSecret && finalScan.includes(forbiddenSecret)) {
+            throw new PublishCliError('Publishing credentials must not appear in browser build files.');
+        }
+        if (isEntry && finalText && entry.value.length <= STREAM_MAX_HTML_BYTES)
+            entry.value += finalText;
+        const after = await handle.stat();
+        if (!sameSnapshot(after, stat))
+            fail('Build file changed while it was being inspected.');
+        if (chunkOffset > 0)
+            chunkSha256.push(chunkHash.digest('hex'));
+        return { sha256: hash.digest('hex'), bytes, entryText: entry.value, chunkSha256 };
+    }
+    catch (error) {
+        if (error instanceof PublishCliError)
+            throw error;
+        throw new PublishCliError('Unable to read a regular browser build file.');
+    }
+    finally {
+        await handle?.close();
+    }
+}
+async function prepareBrowserBuild(directory, sourceCommit, forbiddenSecret) {
+    if (typeof directory !== 'string' || directory.trim() === '') {
+        throw new PublishCliError('A prebuilt browser directory is required.');
+    }
+    const requestedRoot = resolve(directory);
+    let rootStat;
+    try {
+        rootStat = await lstat(requestedRoot);
+    }
+    catch {
+        throw new PublishCliError('Unable to inspect the browser build directory.');
+    }
+    if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
+        throw new PublishCliError('The browser build path must be an existing directory.');
+    }
+    let root;
+    try {
+        root = await realpath(requestedRoot);
+        const rootNow = await lstat(root);
+        if (!sameSnapshot(rootNow, rootStat))
+            fail('Build directory changed; stop the build watcher and try again.');
+    }
+    catch (error) {
+        if (error instanceof PublishCliError)
+            throw error;
+        throw new PublishCliError('Unable to inspect the browser build directory.');
+    }
+    const files = [];
+    let totalBytes = 0;
+    let traversedEntries = 0;
+    let entryText = '';
+    async function visit(currentDirectory, depth) {
+        if (depth > STREAM_MAX_DIRECTORY_DEPTH) {
+            throw new PublishCliError(`Browser build directory nesting exceeds the ${formatLimit(STREAM_MAX_DIRECTORY_DEPTH)} level limit.`);
+        }
+        let directoryHandle;
+        try {
+            directoryHandle = await opendir(currentDirectory);
+            const entries = [];
+            for await (const entry of directoryHandle) {
+                traversedEntries += 1;
+                if (traversedEntries > STREAM_MAX_TRAVERSED_ENTRIES) {
+                    throw new PublishCliError(`Browser builds may contain at most ${formatLimit(STREAM_MAX_TRAVERSED_ENTRIES)} traversed entries.`);
+                }
+                entries.push(entry);
+            }
+            entries.sort((left, right) => compareCodePoints(left.name, right.name));
+            for (const entry of entries) {
+                validateSegment(entry.name);
+                const absolutePath = join(currentDirectory, entry.name);
+                let stat;
+                try {
+                    stat = await lstat(absolutePath);
+                }
+                catch {
+                    throw new PublishCliError('Unable to inspect the browser build directory.');
+                }
+                if (entry.isSymbolicLink() || stat.isSymbolicLink()) {
+                    throw new PublishCliError('Symlinks are not allowed in browser builds.');
+                }
+                if (stat.isDirectory()) {
+                    await visit(absolutePath, depth + 1);
+                    continue;
+                }
+                if (!stat.isFile())
+                    throw new PublishCliError('Browser builds may contain only regular files.');
+                if (files.length >= STREAM_MAX_FILES) {
+                    throw new PublishCliError(`Browser builds may contain at most ${formatLimit(STREAM_MAX_FILES)} files.`);
+                }
+                let resolvedPath;
+                try {
+                    resolvedPath = await realpath(absolutePath);
+                }
+                catch {
+                    throw new PublishCliError('Unable to inspect the browser build file.');
+                }
+                if (resolvedPath !== absolutePath)
+                    throw new PublishCliError('Symlinked build paths are not accepted.');
+                const relativePath = relative(root, absolutePath).split(sep).join('/');
+                assertRelativePayloadPath(relativePath);
+                validateBrowserAsset(relativePath);
+                if (forbiddenSecret && relativePath.includes(forbiddenSecret)) {
+                    throw new PublishCliError('Publishing credentials must not appear in browser build paths.');
+                }
+                if (!Number.isSafeInteger(stat.size) || stat.size < 0 || stat.size > STREAM_MAX_TOTAL_BYTES - totalBytes) {
+                    throw new PublishCliError(`The browser build exceeds the ${formatLimit(STREAM_MAX_TOTAL_BYTES)} byte decoded size limit.`);
+                }
+                const inspected = await inspectFile(absolutePath, stat, relativePath === 'index.html', extensionOf(relativePath) === 'html', forbiddenSecret);
+                totalBytes += inspected.bytes;
+                if (totalBytes > STREAM_MAX_TOTAL_BYTES) {
+                    throw new PublishCliError(`The browser build exceeds the ${formatLimit(STREAM_MAX_TOTAL_BYTES)} byte decoded size limit.`);
+                }
+                const item = {
+                    path: relativePath,
+                    bytes: inspected.bytes,
+                    sha256: inspected.sha256,
+                    absolutePath,
+                    snapshot: snapshot(stat),
+                    chunkSha256: inspected.chunkSha256,
+                };
+                files.push(item);
+                if (relativePath === 'index.html')
+                    entryText = inspected.entryText;
+            }
+        }
+        catch (error) {
+            if (error instanceof PublishCliError)
+                throw error;
+            throw new PublishCliError('Unable to inspect the browser build directory.');
+        }
+        finally {
+            try {
+                await directoryHandle?.close();
+            }
+            catch {
+                // The directory is already closed after iteration.
+            }
+        }
+    }
+    await visit(root, 0);
+    files.sort((left, right) => compareCodePoints(left.path, right.path));
+    if (!files.some((file) => file.path === 'index.html')) {
+        throw new PublishCliError('Browser builds must contain a root index.html entry file.');
+    }
+    if (!entryText || !/<(?:html|body|canvas|script|div|button)\b/i.test(entryText)) {
+        throw new PublishCliError('The index.html entry must contain a browser page.');
+    }
+    const manifestFiles = files.map(({ path, bytes, sha256 }) => ({ path, bytes, sha256 }));
+    const manifest = {
+        entry: 'index.html',
+        files: manifestFiles,
+        ...(sourceCommit === undefined ? {} : { sourceCommit: validateSourceCommit(sourceCommit) }),
+    };
+    return { ...manifest, bytes: totalBytes, root, rootSnapshot: snapshot(rootStat), preparedFiles: files };
+}
+export async function inspectBrowserBuild(directory, sourceCommit) {
+    const prepared = await prepareBrowserBuild(directory, sourceCommit);
+    return {
+        entry: prepared.entry,
+        files: prepared.files.map(({ path, bytes, sha256 }) => ({ path, bytes, sha256 })),
+        bytes: prepared.bytes,
+        ...(prepared.sourceCommit === undefined ? {} : { sourceCommit: prepared.sourceCommit }),
+    };
+}
+/**
+ * Prepare a local build once for the development launcher. The returned
+ * descriptors retain the canonical root and inspection snapshots so serving
+ * can reopen and verify the same files without rebuilding paths from the
+ * caller's input directory.
+ */
+export async function inspectBrowserBuildForLocal(directory, sourceCommit) {
+    return prepareBrowserBuild(directory, sourceCommit);
+}
+function isLoopbackHost(hostname) {
+    return hostname.toLowerCase() === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]';
+}
+/** Derive the only worker origin accepted when credentials omit an explicit one. */
+export function deriveUploadOrigin(platformOrigin) {
+    const platform = new URL(platformOrigin);
+    if (isLoopbackHost(platform.hostname)) {
+        const hostname = platform.hostname === 'localhost' ? '127.0.0.1' : platform.hostname;
+        const port = platform.port === '3003' ? '3401' : platform.port;
+        const authority = hostname === '[::1]' ? `[${hostname.slice(1, -1)}]` : hostname;
+        return `${platform.protocol}//${authority}${port ? `:${port}` : ''}`;
+    }
+    return `${platform.protocol}//uploads.${platform.hostname}`;
+}
+function trustedUploadOrigin(config) {
+    const expected = config.uploadOrigin ?? deriveUploadOrigin(config.apiUrl);
+    let normalized;
+    try {
+        normalized = new URL(expected);
+    }
+    catch {
+        throw new PublishCliError('The upload origin configuration is invalid.');
+    }
+    if (!['http:', 'https:'].includes(normalized.protocol) || normalized.username || normalized.password || normalized.pathname !== '/' || normalized.search || normalized.hash) {
+        throw new PublishCliError('The upload origin configuration must be an origin.');
+    }
+    const platform = new URL(config.apiUrl);
+    if (normalized.origin === platform.origin) {
+        throw new PublishCliError('The upload origin must be a separate origin.');
+    }
+    if (normalized.protocol !== platform.protocol || (!isLoopbackHost(normalized.hostname) && normalized.protocol !== 'https:')) {
+        throw new PublishCliError('The upload origin must use the platform transport security.');
+    }
+    if (isLoopbackHost(platform.hostname)) {
+        if (!isLoopbackHost(normalized.hostname))
+            throw new PublishCliError('Local uploads must stay on a loopback origin.');
+    }
+    else if (normalized.port || normalized.hostname === platform.hostname) {
+        throw new PublishCliError('The upload origin is not an allowed separate host.');
+    }
+    return normalized.origin;
+}
+function safeUploadId(value) {
+    if (typeof value !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(value)) {
+        throw new PublishCliError('Spawn returned an invalid upload identifier.');
+    }
+    return value;
+}
+function safeTicket(value) {
+    if (typeof value !== 'string' || value.length < 1 || value.length > 8192 || /[\u0000-\u001f\u007f]/.test(value)) {
+        throw new PublishCliError('Spawn returned an invalid upload ticket.');
+    }
+    return value;
+}
+function safeExpiry(value) {
+    const parsed = typeof value === 'number'
+        ? Number.isSafeInteger(value) ? value : NaN
+        : typeof value === 'string' ? Date.parse(value) : NaN;
+    if (!Number.isFinite(parsed) || parsed <= Date.now()) {
+        throw new PublishCliError('Spawn returned an invalid or expired upload session.');
+    }
+    return value;
+}
+function validateUploadSession(value, config) {
+    if (!isRecord(value))
+        throw new PublishCliError('Spawn returned an invalid upload session.');
+    const uploadOrigin = typeof value.uploadOrigin === 'string' ? value.uploadOrigin : '';
+    let parsedOrigin;
+    try {
+        parsedOrigin = new URL(uploadOrigin);
+    }
+    catch {
+        throw new PublishCliError('Spawn returned an invalid upload origin.');
+    }
+    if (!['http:', 'https:'].includes(parsedOrigin.protocol) ||
+        parsedOrigin.username ||
+        parsedOrigin.password ||
+        parsedOrigin.pathname !== '/' ||
+        parsedOrigin.search ||
+        parsedOrigin.hash) {
+        throw new PublishCliError('Spawn returned an invalid upload origin.');
+    }
+    const normalized = parsedOrigin.origin;
+    if (normalized !== trustedUploadOrigin(config)) {
+        throw new PublishCliError('Spawn returned an unexpected upload origin.');
+    }
+    const chunkBytes = value.chunkBytes;
+    if (chunkBytes !== CHUNK_BYTES) {
+        throw new PublishCliError('Spawn returned an unsupported upload chunk size.');
+    }
+    return {
+        uploadId: safeUploadId(value.uploadId),
+        uploadOrigin: normalized,
+        token: safeTicket(value.token),
+        chunkBytes,
+        expiresAt: safeExpiry(value.expiresAt),
+    };
+}
+function uploadPath(session, suffix) {
+    return `${session.uploadOrigin}/v1/uploads/${encodeURIComponent(session.uploadId)}${suffix}`;
+}
+function retryable(error) {
+    if (!(error instanceof Error))
+        return false;
+    return /HTTP (?:408|425|429|5\d\d)|network|timed out|timeout|fetch|aborted|temporar/i.test(error.message);
+}
+async function retryJson(operation, options) {
+    const attempts = Math.max(1, Math.min(options.retries ?? STREAM_MAX_RETRIES, STREAM_MAX_RETRIES));
+    const delay = Math.max(0, Math.min(options.retryDelayMs ?? 100, 2_000));
+    const sleep = options.sleep ?? ((milliseconds) => new Promise((resolveSleep) => setTimeout(resolveSleep, milliseconds)));
+    let lastError;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt + 1 >= attempts || !retryable(error))
+                throw error;
+            await sleep(delay * (2 ** attempt));
+        }
+    }
+    throw lastError instanceof Error ? lastError : new PublishCliError('Spawn upload failed.');
+}
+function validateProgress(value, uploadId, totalBytes) {
+    if (!isRecord(value))
+        throw new PublishCliError('Spawn returned an invalid upload progress response.');
+    if (value.uploadId !== undefined && value.uploadId !== uploadId) {
+        throw new PublishCliError('Spawn returned progress for a different upload.');
+    }
+    for (const key of ['bytes', 'receivedBytes', 'uploadedBytes']) {
+        const bytes = value[key];
+        if (bytes !== undefined && (typeof bytes !== 'number' || !Number.isSafeInteger(bytes) || bytes < 0 || bytes > totalBytes)) {
+            throw new PublishCliError('Spawn returned invalid upload progress.');
+        }
+    }
+    return value;
+}
+function progressFile(value, fileIndex) {
+    if (!Array.isArray(value.files))
+        return undefined;
+    const item = value.files[fileIndex];
+    return isRecord(item) ? item : undefined;
+}
+function receivedChunks(value, fileIndex, fileBytes) {
+    const file = progressFile(value, fileIndex);
+    if (!file)
+        return new Set();
+    const result = new Set();
+    if (file.complete === true || (typeof file.receivedBytes === 'number' && file.receivedBytes >= fileBytes)) {
+        for (let index = 0, offset = 0; offset < fileBytes; index += 1, offset += CHUNK_BYTES)
+            result.add(index);
+    }
+    for (const key of ['receivedChunks', 'uploadedChunks', 'completeChunks', 'chunks']) {
+        const chunks = file[key];
+        if (!Array.isArray(chunks))
+            continue;
+        for (const item of chunks) {
+            const index = typeof item === 'number'
+                ? item
+                : isRecord(item) && typeof item.index === 'number'
+                    ? item.index
+                    : isRecord(item) && typeof item.chunkIndex === 'number'
+                        ? item.chunkIndex
+                        : NaN;
+            if (Number.isSafeInteger(index) && index >= 0 && index < Math.ceil(fileBytes / CHUNK_BYTES))
+                result.add(index);
+        }
+    }
+    return result;
+}
+async function openForUpload(file) {
+    let resolved;
+    try {
+        resolved = await realpath(file.absolutePath);
+    }
+    catch {
+        throw new PublishCliError('Unable to reopen a browser build file.');
+    }
+    if (resolved !== file.absolutePath)
+        throw new PublishCliError('Build file changed to a symlink.');
+    let handle;
+    try {
+        handle = await open(file.absolutePath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+        const current = await handle.stat();
+        if (!current.isFile() || current.isSymbolicLink() || !sameSnapshot(current, file.snapshot)) {
+            throw new PublishCliError('Build file changed after inspection.');
+        }
+        return handle;
+    }
+    catch (error) {
+        await handle?.close().catch(() => undefined);
+        if (error instanceof PublishCliError)
+            throw error;
+        throw new PublishCliError('Unable to reopen a browser build file.');
+    }
+}
+/** Reopen a prepared local file and verify its retained root, metadata, and digest before serving it. */
+export async function openValidatedBuildFile(build, file, cache) {
+    let rootHandle;
+    try {
+        rootHandle = await open(build.root, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0) | (constants.O_DIRECTORY ?? 0));
+        const currentRoot = await rootHandle.stat();
+        if (!currentRoot.isDirectory() || currentRoot.isSymbolicLink() || !sameSnapshot(currentRoot, build.rootSnapshot)) {
+            throw new PublishCliError('Build directory changed after inspection.');
+        }
+    }
+    catch (error) {
+        if (error instanceof PublishCliError)
+            throw error;
+        throw new PublishCliError('Unable to reopen the inspected browser build.');
+    }
+    finally {
+        await rootHandle?.close().catch(() => undefined);
+    }
+    let handle;
+    try {
+        handle = await open(file.absolutePath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+        const current = await handle.stat();
+        if (!current.isFile() || current.isSymbolicLink() || !sameSnapshot(current, file.snapshot)) {
+            throw new PublishCliError('Build file changed after inspection.');
+        }
+        const cachedSnapshot = cache?.snapshot;
+        if (cachedSnapshot && sameSnapshot(current, cachedSnapshot))
+            return handle;
+        let validation = cache?.validation;
+        if (!validation) {
+            validation = (async () => {
+                const hash = hashFactory()('sha256');
+                const buffer = new Uint8Array(Math.min(1_048_576, file.bytes));
+                let bytes = 0;
+                while (bytes < file.bytes) {
+                    const want = Math.min(buffer.byteLength, file.bytes - bytes);
+                    const { bytesRead } = await handle.read(buffer, 0, want, bytes);
+                    if (bytesRead <= 0)
+                        throw new PublishCliError('Build file ended while it was being served.');
+                    hash.update(buffer.subarray(0, bytesRead));
+                    bytes += bytesRead;
+                }
+                const after = await handle.stat();
+                if (!sameSnapshot(after, file.snapshot) || bytes !== file.bytes || hash.digest('hex') !== file.sha256) {
+                    throw new PublishCliError('Build file changed after inspection.');
+                }
+                if (cache)
+                    cache.snapshot = snapshot(after);
+            })();
+            if (cache)
+                cache.validation = validation;
+        }
+        try {
+            await validation;
+        }
+        catch (error) {
+            if (cache?.validation === validation) {
+                cache.validation = undefined;
+                cache.snapshot = undefined;
+            }
+            throw error;
+        }
+        return handle;
+    }
+    catch (error) {
+        await handle?.close().catch(() => undefined);
+        if (error instanceof PublishCliError)
+            throw error;
+        throw new PublishCliError('Unable to reopen the inspected browser build file.');
+    }
+}
+async function uploadFile(session, file, fileIndex, prior, totalBytes, workerConfig, fetchImplementation, options) {
+    const handle = await openForUpload(file);
+    const skipped = receivedChunks(prior, fileIndex, file.bytes);
+    const buffer = new Uint8Array(session.chunkBytes);
+    let offset = 0;
+    let chunkIndex = 0;
+    let progress = prior;
+    try {
+        while (offset < file.bytes) {
+            const length = Math.min(session.chunkBytes, file.bytes - offset);
+            let read = 0;
+            while (read < length) {
+                const result = await handle.read(buffer, read, length - read, offset + read);
+                if (result.bytesRead <= 0)
+                    throw new PublishCliError('Build file ended while it was being uploaded.');
+                read += result.bytesRead;
+            }
+            const actualChunkSha256 = hashFactory()('sha256').update(buffer.subarray(0, length)).digest('hex');
+            if (actualChunkSha256 !== file.chunkSha256[chunkIndex]) {
+                throw new PublishCliError('Build file changed while it was being uploaded.');
+            }
+            if (!skipped.has(chunkIndex)) {
+                const payload = buffer.subarray(0, length);
+                const next = await retryJson(async () => validateProgress(await requestJson(workerConfig, uploadPath(session, `/files/${fileIndex}/chunks/${chunkIndex}`), {
+                    method: 'PUT',
+                    headers: {
+                        Authorization: `Bearer ${session.token}`,
+                        'Content-Type': 'application/octet-stream',
+                        'Content-Length': String(length),
+                    },
+                    body: payload,
+                }, fetchImplementation), session.uploadId, totalBytes), options);
+                progress = next;
+                options.onProgress?.(progress);
+            }
+            offset += length;
+            chunkIndex += 1;
+        }
+        const after = await handle.stat();
+        if (!sameSnapshot(after, file.snapshot))
+            throw new PublishCliError('Build file changed while it was uploaded.');
+        return progress;
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function publishBrowserDirectory(config, directory, sourceCommit, fetchImplementation = globalThis.fetch, options = {}) {
+    const validatedConfig = validatePublishConfig(config);
+    const prepared = await prepareBrowserBuild(directory, sourceCommit ?? options.sourceCommit, validatedConfig.publishKey);
+    const manifest = {
+        entry: prepared.entry,
+        files: prepared.files.map(({ path, bytes, sha256 }) => ({ path, bytes, sha256 })),
+        ...(prepared.sourceCommit === undefined ? {} : { sourceCommit: prepared.sourceCommit }),
+    };
+    const coreBase = validatedConfig.apiUrl.replace(/\/+$/, '');
+    const coreUploadUrl = `${coreBase}/api/v1/publish/${encodeURIComponent(validatedConfig.projectId)}/uploads`;
+    const sessionResponse = await requestJson(validatedConfig, coreUploadUrl, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${validatedConfig.publishKey}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(manifest),
+    }, fetchImplementation);
+    const session = validateUploadSession(sessionResponse, validatedConfig);
+    const workerConfig = {
+        ...validatedConfig,
+        apiUrl: session.uploadOrigin,
+        publishKey: session.token,
+    };
+    let progress = await retryJson(async () => validateProgress(await requestJson(workerConfig, uploadPath(session, ''), {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${session.token}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(manifest),
+    }, fetchImplementation), session.uploadId, prepared.bytes), options);
+    options.onProgress?.(progress);
+    for (const [fileIndex, file] of prepared.preparedFiles.entries()) {
+        progress = await uploadFile(session, file, fileIndex, progress, prepared.bytes, workerConfig, fetchImplementation, options);
+    }
+    const sealed = await retryJson(async () => validateProgress(await requestJson(workerConfig, uploadPath(session, '/seal'), {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${session.token}` },
+    }, fetchImplementation), session.uploadId, prepared.bytes), options);
+    if (sealed.sealed !== true) {
+        throw new PublishCliError('Spawn did not seal the browser build.');
+    }
+    options.onProgress?.(sealed);
+    return requestJson(validatedConfig, `${coreBase}/api/v1/publish/${encodeURIComponent(validatedConfig.projectId)}/uploads/${encodeURIComponent(session.uploadId)}/complete`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${validatedConfig.publishKey}` },
+    }, fetchImplementation);
+}