@heybox/hb-sdk 0.6.8-alpha.2 → 0.6.9-alpha.0

package/dist/index.esm.js

@@ -1,3 +1,274 @@
+/**
+ * network.request 请求体形态校验与宿主失败诊断文案。
+ *
+ * @remarks
+ * App Host 的 heybox 客户端代发 transport 仅声明 form/json，不支持 multipart。
+ * 本地 Mock 若直接走 fetch 会“能通”，上线后却变成难以理解的 500 network_error。
+ * 因此在 SDK 侧统一提前拒绝 multipart，并在宿主伪装 HTTP 失败时给出可操作提示。
+ */
+/** multipart 不被 App Host 支持时的稳定说明（开发者可见）。 */
+const NETWORK_REQUEST_MULTIPART_UNSUPPORTED_MESSAGE = 'network.request 不支持 multipart/form-data。App Host 客户端代发仅支持 application/x-www-form-urlencoded（form）与 application/json；请将 data 编码为 form 字符串（例如 new URLSearchParams({...}).toString()）并设置 Content-Type: application/x-www-form-urlencoded。文件上传请使用专用上传能力，勿手写 multipart boundary。';
+/**
+ * 读取请求头中的 Content-Type（大小写不敏感）。
+ */
+function readNetworkContentType(headers) {
+    if (!headers) {
+        return undefined;
+    }
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.trim().toLowerCase() === 'content-type' && typeof value === 'string') {
+            return value;
+        }
+    }
+    return undefined;
+}
+/**
+ * 判断 Content-Type 是否声明为 multipart/form-data。
+ */
+function isMultipartContentType(contentType) {
+    return typeof contentType === 'string' && contentType.toLowerCase().includes('multipart/form-data');
+}
+/**
+ * 判断字符串 body 是否像手写 multipart 实体。
+ */
+function looksLikeMultipartBody(data) {
+    if (typeof data !== 'string') {
+        return false;
+    }
+    const trimmed = data.trimStart();
+    return trimmed.startsWith('--') && /content-disposition\s*:\s*form-data/i.test(data);
+}
+/**
+ * 判断公开请求配置是否使用了 Host 不支持的 multipart 形态。
+ */
+function isUnsupportedMultipartNetworkRequest(config) {
+    return isMultipartContentType(readNetworkContentType(config.headers)) || looksLikeMultipartBody(config.data);
+}
+function isPlainObject$2(value) {
+    return Object.prototype.toString.call(value) === '[object Object]';
+}
+/**
+ * 从宿主返回的“完成态”响应中提取更清晰的失败原因。
+ *
+ * @remarks
+ * Host 可能把 transport 不支持等内部错误包装成 HTTP 500 + `{ status: 'network_error', msg }`。
+ * 此时 `status=500` 并不代表目标站点返回了 500。
+ */
+function describeHostNetworkFailure(response) {
+    const data = response.data;
+    const hostStatus = isPlainObject$2(data) && typeof data.status === 'string' ? data.status : undefined;
+    const hostMsg = isPlainObject$2(data) && typeof data.msg === 'string'
+        ? data.msg
+        : isPlainObject$2(data) && typeof data.message === 'string'
+            ? data.message
+            : undefined;
+    const isHostNetworkError = hostStatus === 'network_error';
+    const mentionsUnsupportedShape = typeof hostMsg === 'string' &&
+        (hostMsg.includes('unsupported-request-shape') || hostMsg.includes('unsupported_request_shape'));
+    const requestLooksMultipart = isUnsupportedMultipartNetworkRequest(response.config || {});
+    if (!isHostNetworkError && !mentionsUnsupportedShape && !(requestLooksMultipart && response.status >= 500)) {
+        return undefined;
+    }
+    const lines = [
+        '原因: 这是宿主网络层失败，不是目标 URL 的业务 HTTP 响应。',
+    ];
+    if (hostMsg) {
+        lines.push(`宿主信息: ${hostMsg}`);
+    }
+    if (requestLooksMultipart || mentionsUnsupportedShape) {
+        lines.push(NETWORK_REQUEST_MULTIPART_UNSUPPORTED_MESSAGE);
+    }
+    else if (isHostNetworkError) {
+        lines.push('请检查请求 URL、headers、body 编码与 Host 网络权限；本地 Mock 与 App Host 能力并不完全一致。');
+    }
+    return lines.join(' ');
+}
+
+/**
+ * network.request 诊断日志的纯脱敏工具。
+ *
+ * @remarks
+ * 放在 `core` 而非 `modules/network`：无错误类型依赖，供 SDK 错误文案、
+ * modules observability、devtools Mock Host / proxy 共用，并满足 boundary
+ *（devtools 不得直接 import runtime capability modules）。
+ */
+const DATA_PREVIEW_MAX_CHARS = 500;
+const SENSITIVE_HEADER_NAMES = new Set([
+    'authorization',
+    'cookie',
+    'proxy-authorization',
+    'set-cookie',
+    'token',
+    'x-pkey',
+    'api-key',
+    'apikey',
+    'x-api-key',
+    'x-auth-token',
+    'x-access-token',
+    'session',
+    'session-id',
+    'jwt',
+    'refresh-token',
+    'x-csrf-token',
+]);
+/** 敏感字段名：header / query / body key 共用。 */
+const SENSITIVE_KEY_PATTERN = /(authorization|cookie|password|passwd|secret|token|pkey|private[_-]?key|access[_-]?key|client[_-]?secret|api[_-]?key|apikey|session|jwt|refresh[_-]?token|csrf)/i;
+/**
+ * 脱敏请求 URL：去掉 userinfo，并将 query / fragment 中的敏感参数值替换为 `[redacted]`。
+ */
+function sanitizeNetworkRequestUrl(url) {
+    if (!url) {
+        return url;
+    }
+    try {
+        const parsed = new URL(url);
+        parsed.username = '';
+        parsed.password = '';
+        redactUrlSearchParams(parsed.searchParams);
+        if (parsed.hash && parsed.hash.length > 1) {
+            const hashBody = parsed.hash.slice(1);
+            if (hashBody.includes('=')) {
+                const hashParams = new URLSearchParams(hashBody);
+                if (redactUrlSearchParams(hashParams)) {
+                    parsed.hash = hashParams.toString();
+                }
+            }
+        }
+        return parsed.toString();
+    }
+    catch {
+        return redactSensitivePairsInRawText(url);
+    }
+}
+/**
+ * 脱敏请求/响应头；敏感名（含 heybox 前缀）替换为 `[redacted]`。
+ */
+function sanitizeNetworkHeaders(headers) {
+    if (!headers) {
+        return {};
+    }
+    return Object.fromEntries(Object.entries(headers).map(([key, value]) => [
+        key,
+        isSensitiveNetworkHeaderName(key) ? '[redacted]' : value,
+    ]));
+}
+/**
+ * 预览请求/响应 data：递归脱敏敏感字段，截断长文本与大数组。
+ */
+function previewNetworkData(data) {
+    if (data === undefined) {
+        return undefined;
+    }
+    if (typeof data === 'string') {
+        return previewNetworkStringData(data);
+    }
+    if (typeof data === 'number' || typeof data === 'boolean' || data === null) {
+        return data;
+    }
+    try {
+        const sanitized = sanitizeNetworkDataValue(data);
+        const serialized = JSON.stringify(sanitized);
+        if (serialized === undefined) {
+            return '[unserializable]';
+        }
+        if (serialized.length <= DATA_PREVIEW_MAX_CHARS) {
+            return sanitized;
+        }
+        return truncateText(serialized, DATA_PREVIEW_MAX_CHARS);
+    }
+    catch {
+        return '[unserializable]';
+    }
+}
+/**
+ * 诊断 message 中的 URL 片段做脱敏，避免 error.message 二次泄漏 query secrets。
+ */
+function sanitizeDiagnosticMessage(message) {
+    if (!message) {
+        return message;
+    }
+    return message.replace(/https?:\/\/[^\s]+/gi, matched => sanitizeNetworkRequestUrl(matched.replace(/[),.;]+$/g, '')));
+}
+function isSensitiveNetworkHeaderName(headerName) {
+    const normalized = headerName.trim().toLowerCase();
+    return (SENSITIVE_HEADER_NAMES.has(normalized) ||
+        isSensitiveNetworkKey(normalized) ||
+        normalized.startsWith('x-heybox-') ||
+        normalized.startsWith('x-xhh-'));
+}
+function isSensitiveNetworkKey(key) {
+    return SENSITIVE_KEY_PATTERN.test(key.trim());
+}
+function previewNetworkStringData(data) {
+    const trimmed = data.trim();
+    if ((trimmed.startsWith('{') && trimmed.endsWith('}')) || (trimmed.startsWith('[') && trimmed.endsWith(']'))) {
+        try {
+            return previewNetworkData(JSON.parse(trimmed));
+        }
+        catch {
+            // fall through
+        }
+    }
+    if (trimmed.includes('=') && !trimmed.includes('\n') && trimmed.length <= DATA_PREVIEW_MAX_CHARS * 2) {
+        try {
+            const params = new URLSearchParams(trimmed);
+            if ([...params.keys()].length > 0) {
+                const redacted = Object.fromEntries([...params.entries()].map(([key, value]) => [
+                    key,
+                    isSensitiveNetworkKey(key) ? '[redacted]' : value,
+                ]));
+                return previewNetworkData(redacted);
+            }
+        }
+        catch {
+            // fall through
+        }
+    }
+    return truncateText(redactSensitivePairsInRawText(data), DATA_PREVIEW_MAX_CHARS);
+}
+function sanitizeNetworkDataValue(value) {
+    if (Array.isArray(value)) {
+        return value.slice(0, 20).map(item => sanitizeNetworkDataValue(item));
+    }
+    if (!isPlainObject$1(value)) {
+        if (typeof value === 'string') {
+            return truncateText(value, DATA_PREVIEW_MAX_CHARS);
+        }
+        return value;
+    }
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+        key,
+        isSensitiveNetworkKey(key) ? '[redacted]' : sanitizeNetworkDataValue(item),
+    ]));
+}
+function redactUrlSearchParams(params) {
+    let changed = false;
+    for (const key of [...params.keys()]) {
+        if (isSensitiveNetworkKey(key)) {
+            params.set(key, '[redacted]');
+            changed = true;
+        }
+    }
+    return changed;
+}
+function redactSensitivePairsInRawText(text) {
+    return text.replace(/([?&#]|^|[?&])([^=&#\s]+)=([^&#\s]*)/g, (full, prefix, key, value) => {
+        if (!isSensitiveNetworkKey(key)) {
+            return full;
+        }
+        return `${prefix}${key}=[redacted]`;
+    });
+}
+function truncateText(value, maxChars) {
+    if (value.length <= maxChars) {
+        return value;
+    }
+    return `${value.slice(0, maxChars)}…(truncated, total=${value.length})`;
+}
+function isPlainObject$1(value) {
+    return Object.prototype.toString.call(value) === '[object Object]';
+}
+
 /**
  * SDK 对外抛出的标准 bridge / runtime 错误类型。
  *
@@ -60,7 +331,14 @@ class HbMiniProgramNetworkError extends Error {
      * @param response 已完成请求的标准化网络响应。
      */
     constructor(response) {
-        super(`network.request failed with status ${response.status}`);
+        const method = (response.config.method || 'GET').toUpperCase();
+        // 诊断文案使用脱敏 URL，避免 query 中的 token 等经 error.message 泄漏。
+        const url = sanitizeNetworkRequestUrl(response.config.url || '');
+        const statusText = response.statusText ? ` ${response.statusText}` : '';
+        const baseMessage = `network.request failed with status ${response.status}${statusText}: ${method} ${url}`;
+        // 宿主可能把 transport 不支持等内部错误伪装成 HTTP 500；补充可操作提示。
+        const hostHint = describeHostNetworkFailure(response);
+        super(hostHint ? `${baseMessage}\n${hostHint}` : baseMessage);
         this.name = 'HbMiniProgramNetworkError';
         this.status = response.status;
         this.data = response.data;
@@ -321,7 +599,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.6.8-alpha.2';
+    : '0.6.9-alpha.0';
 
 /**
  * 判断未知数据是否符合小程序 bridge 消息信封。
@@ -888,6 +1166,77 @@ function createStorageModule(requester) {
     };
 }
 
+const LOG_PREFIX = '[hb-sdk][network.request]';
+/**
+ * 记录 `network.request` 失败，保证异常路径在开发者控制台可观测。
+ *
+ * @remarks
+ * - 仅用于诊断，不改变错误抛出语义。
+ * - 会脱敏 token/cookie 等敏感头与字段，并截断 body 预览。
+ * - detail 构造与 logger 调用均包在 try 内，日志失败不得影响业务错误抛出。
+ */
+function logNetworkRequestFailure(config, error, extras) {
+    try {
+        const consoleRef = typeof console === 'undefined' ? undefined : console;
+        const logger = consoleRef?.warn || consoleRef?.error || consoleRef?.log;
+        if (!logger) {
+            return;
+        }
+        const detail = createNetworkRequestFailureLog(config, error, extras);
+        logger.call(consoleRef, LOG_PREFIX, formatNetworkRequestFailureMessage(detail), detail);
+    }
+    catch {
+        // 日志失败不得影响业务错误抛出。
+    }
+}
+function createNetworkRequestFailureLog(config, error, extras) {
+    const method = (config.method || 'GET').toUpperCase();
+    const detail = {
+        kind: extras.kind,
+        method,
+        url: sanitizeNetworkRequestUrl(config.url),
+    };
+    if (typeof extras.status === 'number') {
+        detail.status = extras.status;
+    }
+    else if (error instanceof HbMiniProgramNetworkError) {
+        detail.status = error.status;
+    }
+    if (typeof extras.statusText === 'string' && extras.statusText) {
+        detail.statusText = extras.statusText;
+    }
+    // NetworkError 已有 method/url/status 结构化字段；不再回写 message，避免 raw URL 二次泄漏。
+    if (!(error instanceof HbMiniProgramNetworkError)) {
+        if (error instanceof HbMiniProgramSDKError) {
+            detail.code = error.code;
+            detail.message = sanitizeDiagnosticMessage(error.message);
+        }
+        else if (error instanceof Error) {
+            detail.message = sanitizeDiagnosticMessage(error.message);
+        }
+    }
+    if (config.timeout !== undefined) {
+        detail.timeout = config.timeout;
+    }
+    if (config.withCredentials !== undefined) {
+        detail.withCredentials = config.withCredentials;
+    }
+    const headers = sanitizeNetworkHeaders(extras.headers || config.headers);
+    if (Object.keys(headers).length > 0) {
+        detail.headers = headers;
+    }
+    const dataPreview = previewNetworkData(extras.data !== undefined ? extras.data : config.data);
+    if (dataPreview !== undefined) {
+        detail.dataPreview = dataPreview;
+    }
+    return detail;
+}
+function formatNetworkRequestFailureMessage(detail) {
+    const statusPart = detail.status === undefined ? '' : ` status=${detail.status}`;
+    const codePart = detail.code ? ` code=${detail.code}` : '';
+    return `${detail.kind} ${detail.method} ${detail.url}${statusPart}${codePart}`;
+}
+
 const DEFAULT_VALIDATE_STATUS = status => status >= 200 && status < 300;
 function isPlainObject(value) {
     return Object.prototype.toString.call(value) === '[object Object]';
@@ -931,6 +1280,9 @@ function normalizeHeaders(headers) {
     return Object.fromEntries(Object.entries(headers).flatMap(([key, value]) => (typeof value === 'string' ? [[key, value]] : [])));
 }
 function toNetworkResponse(payload, config) {
+    if (payload == null || typeof payload !== 'object') {
+        throw createSDKError('INVALID_NETWORK_RESPONSE', 'network.request 返回了无效的响应', payload);
+    }
     if (typeof payload.status !== 'number' || Number.isNaN(payload.status)) {
         throw createSDKError('INVALID_NETWORK_RESPONSE', 'network.request 返回了无效的 status', payload);
     }
@@ -965,12 +1317,56 @@ function toNetworkResponse(payload, config) {
  */
 async function request(requester, config) {
     const validateStatus = config.validateStatus || DEFAULT_VALIDATE_STATUS;
-    const responsePayload = await requester.request(NETWORK_REQUEST_METHOD, toRequestPayload(config));
-    const response = toNetworkResponse(responsePayload, config);
-    if (!validateStatus(response.status)) {
-        throw new HbMiniProgramNetworkError(response);
+    try {
+        assertSupportedPublicNetworkRequest(config);
+        const responsePayload = await requester.request(NETWORK_REQUEST_METHOD, toRequestPayload(config));
+        const response = toNetworkResponse(responsePayload, config);
+        if (!validateStatus(response.status)) {
+            const error = new HbMiniProgramNetworkError(response);
+            logNetworkRequestFailure(config, error, {
+                kind: 'http_status',
+                status: response.status,
+                statusText: response.statusText,
+                data: response.data,
+                headers: response.headers,
+            });
+            throw error;
+        }
+        return response;
+    }
+    catch (error) {
+        if (error instanceof HbMiniProgramNetworkError) {
+            throw error;
+        }
+        if (error instanceof HbMiniProgramSDKError && error.code === 'INVALID_PARAMS') {
+            logNetworkRequestFailure(config, error, {
+                kind: 'bridge_error',
+            });
+            throw error;
+        }
+        if (error instanceof HbMiniProgramSDKError && error.code === 'INVALID_NETWORK_RESPONSE') {
+            logNetworkRequestFailure(config, error, {
+                kind: 'invalid_response',
+                data: error.data,
+            });
+            throw error;
+        }
+        logNetworkRequestFailure(config, error, {
+            kind: error instanceof HbMiniProgramSDKError ? 'bridge_error' : 'unknown',
+        });
+        throw error;
+    }
+}
+/**
+ * 在进入 bridge 前拒绝 Host 能力明确不支持的公开请求形态。
+ *
+ * @remarks
+ * 提前失败可避免本地 Mock（fetch）与 App Host（heybox）能力差造成“本地成功、上线 500”。
+ */
+function assertSupportedPublicNetworkRequest(config) {
+    if (isUnsupportedMultipartNetworkRequest(config)) {
+        throw createSDKError('INVALID_PARAMS', NETWORK_REQUEST_MULTIPART_UNSUPPORTED_MESSAGE);
     }
-    return response;
 }
 /**
  * 创建 network 模块。

package/dist/miniapp-publish.cjs.js

@@ -2836,6 +2836,10 @@ const UPDATE_SQUARE_DISPLAY_API_PATH = '/mall/developer/user_miniprogram/square_
 const LIST_USER_MINIPROGRAM_VERSION_API_PATH = '/mall/developer/user_miniprogram/version/list';
 const FNV_OFFSET = 0x811c9dc5;
 const FNV_PRIME = 0x01000193;
+const MINIAPP_UPLOAD_SESSION_REF_LENGTH = 10;
+const MINIAPP_ARTIFACT_SIGNATURE_MAGIC = 'heybox-user-miniprogram-artifact\0v1\0';
+const UNPAIRED_SURROGATE_PATTERN = /[\ud800-\udbff](?![\udc00-\udfff])|(^|[^\ud800-\udbff])[\udc00-\udfff]/;
+const textEncoder = new TextEncoder();
 function normalizeRelativePath(relativePath) {
     return String(relativePath || '')
         .replace(/\\/g, '/')
@@ -2929,6 +2933,202 @@ function shouldUploadDistFile(relativePath) {
     }
     return true;
 }
+/**
+ * 校验构建产物路径和大小，并按路径 UTF-8 字节序排序。
+ *
+ * @param files 待处理的构建产物文件。
+ * @returns 保留输入附加字段的有序文件列表。
+ * @throws 路径不规范、路径重复或文件大小非法时抛出错误。
+ */
+function prepareMiniappArtifactFiles(files) {
+    if (files.length > 0xffffffff) {
+        throw new Error('构建产物文件数量超出签名协议上限');
+    }
+    const usedPaths = new Set();
+    const prepared = files.map(file => {
+        const relativePath = normalizeMiniappArtifactRelativePath(file.relativePath);
+        if (usedPaths.has(relativePath)) {
+            throw new Error(`构建产物包含重复文件路径：${relativePath}`);
+        }
+        usedPaths.add(relativePath);
+        validateArtifactFileSize(file.size, relativePath);
+        return { ...file, relativePath };
+    });
+    return prepared.sort((left, right) => compareBytes(textEncoder.encode(left.relativePath), textEncoder.encode(right.relativePath)));
+}
+/**
+ * 按服务端 session key 前缀校验最终上传路径的 UTF-8 字节长度。
+ *
+ * @param files 待上传的构建产物文件。
+ * @param options 小程序和长度限制配置。
+ * @returns 第一个超长路径的错误提示；全部合法时返回 `undefined`。
+ */
+function validateMiniappUploadPathLengths(files, options) {
+    const maxLength = options.maxLength ?? ACTIVITY_UPLOAD_KEY_MAX_LENGTH;
+    const prefix = `/u/${getMiniProgramUploadAlias(options.miniProgramId)}/${'x'.repeat(MINIAPP_UPLOAD_SESSION_REF_LENGTH)}/`;
+    const prefixLength = textEncoder.encode(prefix).length;
+    const tooLongFile = files.find(file => {
+        const relativePath = normalizeMiniappArtifactRelativePath(file.relativePath);
+        return prefixLength + textEncoder.encode(relativePath).length > maxLength;
+    });
+    return tooLongFile ? `文件路径过长，请缩短构建产物文件名或目录层级：${tooLongFile.relativePath}` : undefined;
+}
+/**
+ * 创建 v1 整包签名头。
+ *
+ * @param fileCount 参与签名的文件数量。
+ * @returns 包含协议标识和文件数量的字节数组。
+ * @throws 文件数量超出协议范围时抛出错误。
+ */
+function createMiniappArtifactSignatureHeader(fileCount) {
+    if (!Number.isInteger(fileCount) || fileCount < 0 || fileCount > 0xffffffff) {
+        throw new Error('构建产物文件数量超出签名协议上限');
+    }
+    return concatBytes(textEncoder.encode(MINIAPP_ARTIFACT_SIGNATURE_MAGIC), encodeUint32BE(fileCount));
+}
+/**
+ * 创建单个文件的 v1 framing header。
+ *
+ * @param file 已规范化或待校验的构建产物文件。
+ * @returns 包含路径长度、路径和文件大小的字节数组。
+ * @throws 文件路径或大小非法时抛出错误。
+ */
+function createMiniappArtifactFileHeader(file) {
+    const relativePath = normalizeMiniappArtifactRelativePath(file.relativePath);
+    validateArtifactFileSize(file.size, relativePath);
+    const pathBytes = textEncoder.encode(relativePath);
+    return concatBytes(encodeUint32BE(pathBytes.length), pathBytes, encodeUint64BE(file.size));
+}
+/**
+ * 校验服务端 session 文件映射，并计算仍需上传的文件。
+ *
+ * @param localFiles 本地构建产物文件。
+ * @param serverFiles 服务端签发的文件映射。
+ * @param uploadedKeys 服务端已确认上传成功的 key。
+ * @returns 完整映射、待上传文件和已确认 key。
+ * @throws 服务端映射与本地产物不一致时抛出错误。
+ */
+function resolveMiniappUploadSessionFiles(localFiles, serverFiles, uploadedKeys) {
+    const preparedFiles = prepareMiniappArtifactFiles(localFiles);
+    if (serverFiles.length !== preparedFiles.length) {
+        throw new Error(`上传会话文件数量异常：期望 ${preparedFiles.length}，实际 ${serverFiles.length}`);
+    }
+    const mappings = new Map();
+    const serverSizes = new Map();
+    const knownKeys = new Set();
+    for (const serverFile of serverFiles) {
+        const relativePath = normalizeMiniappArtifactRelativePath(serverFile.relative_path);
+        if (mappings.has(relativePath)) {
+            throw new Error(`上传会话返回重复文件路径：${relativePath}`);
+        }
+        const key = String(serverFile.key || '');
+        if (!key) {
+            throw new Error(`上传会话未返回文件 key：${relativePath}`);
+        }
+        if (knownKeys.has(key)) {
+            throw new Error(`上传会话返回重复文件 key：${relativePath}`);
+        }
+        const size = Number(serverFile.size);
+        if (!Number.isSafeInteger(size) || size < 0) {
+            throw new Error(`上传会话返回文件大小异常：${relativePath}`);
+        }
+        mappings.set(relativePath, key);
+        serverSizes.set(relativePath, size);
+        knownKeys.add(key);
+    }
+    const files = preparedFiles.map(file => {
+        const key = mappings.get(file.relativePath);
+        if (!key) {
+            throw new Error(`上传会话缺少文件映射：${file.relativePath}`);
+        }
+        if (serverSizes.get(file.relativePath) !== file.size) {
+            throw new Error(`上传会话文件大小与本地构建不一致：${file.relativePath}`);
+        }
+        return { file, key };
+    });
+    const completed = new Set();
+    for (const rawKey of uploadedKeys) {
+        const key = String(rawKey || '');
+        if (!knownKeys.has(key)) {
+            throw new Error('上传会话返回了不属于当前产物的已上传文件');
+        }
+        completed.add(key);
+    }
+    return {
+        files,
+        missingFiles: files.filter(file => !completed.has(file.key)),
+        uploadedKeys: [...completed],
+    };
+}
+function normalizeMiniappArtifactRelativePath(relativePath) {
+    const value = String(relativePath || '');
+    if (!value) {
+        throw new Error('构建产物包含空文件路径');
+    }
+    if (value.includes('\\')) {
+        throw new Error(`构建产物路径不能包含反斜杠：${value}`);
+    }
+    if (value.startsWith('/') || value.endsWith('/') || /^[a-zA-Z]:\//.test(value)) {
+        throw new Error(`构建产物必须使用相对文件路径：${value}`);
+    }
+    if (containsControlCharacter(value) || UNPAIRED_SURROGATE_PATTERN.test(value)) {
+        throw new Error(`构建产物路径包含非法字符：${value}`);
+    }
+    if (value.split('/').some(segment => !segment || segment === '.' || segment === '..')) {
+        throw new Error(`构建产物路径包含非法目录段：${value}`);
+    }
+    if (value.includes(',')) {
+        throw new Error(`构建产物路径不能包含逗号：${value}`);
+    }
+    if (value.includes('*') || value.includes('?')) {
+        throw new Error(`构建产物路径不能包含通配符：${value}`);
+    }
+    return value;
+}
+function containsControlCharacter(value) {
+    for (const character of value) {
+        const code = character.charCodeAt(0);
+        if (code <= 0x1f || (code >= 0x7f && code <= 0x9f)) {
+            return true;
+        }
+    }
+    return false;
+}
+function validateArtifactFileSize(size, relativePath) {
+    if (!Number.isSafeInteger(size) || size < 0) {
+        throw new Error(`构建产物文件大小无效：${relativePath}`);
+    }
+}
+function encodeUint32BE(value) {
+    const bytes = new Uint8Array(4);
+    new DataView(bytes.buffer).setUint32(0, value, false);
+    return bytes;
+}
+function encodeUint64BE(value) {
+    const bytes = new Uint8Array(8);
+    const view = new DataView(bytes.buffer);
+    view.setUint32(0, Math.floor(value / 0x100000000), false);
+    view.setUint32(4, value % 0x100000000, false);
+    return bytes;
+}
+function concatBytes(...parts) {
+    const result = new Uint8Array(parts.reduce((total, part) => total + part.length, 0));
+    let offset = 0;
+    for (const part of parts) {
+        result.set(part, offset);
+        offset += part.length;
+    }
+    return result;
+}
+function compareBytes(left, right) {
+    const length = Math.min(left.length, right.length);
+    for (let index = 0; index < length; index += 1) {
+        if (left[index] !== right[index]) {
+            return left[index] - right[index];
+        }
+    }
+    return left.length - right.length;
+}
 
 exports.ACTIVITY_UPLOAD_KEY_MAX_LENGTH = ACTIVITY_UPLOAD_KEY_MAX_LENGTH;
 exports.CREATE_USER_MINIPROGRAM_API_PATH = CREATE_USER_MINIPROGRAM_API_PATH;
@@ -2955,11 +3155,16 @@ exports.USER_MINIPROGRAM_ACCESS_STATUS_API_PATH = USER_MINIPROGRAM_ACCESS_STATUS
 exports.USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH = USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH;
 exports.USER_MINIPROGRAM_VERSION_PREVIEW_INFO_API_PATH = USER_MINIPROGRAM_VERSION_PREVIEW_INFO_API_PATH;
 exports.WITHDRAW_USER_MINIPROGRAM_VERSION_API_PATH = WITHDRAW_USER_MINIPROGRAM_VERSION_API_PATH;
+exports.createMiniappArtifactFileHeader = createMiniappArtifactFileHeader;
+exports.createMiniappArtifactSignatureHeader = createMiniappArtifactSignatureHeader;
 exports.getMiniProgramUploadAlias = getMiniProgramUploadAlias;
 exports.getMiniappUploadKey = getMiniappUploadKey;
 exports.isValidVersion = isValidMiniappManifestVersion;
 exports.normalizeRelativePath = normalizeRelativePath;
+exports.prepareMiniappArtifactFiles = prepareMiniappArtifactFiles;
 exports.relativePathContainsNodeModulesSegment = relativePathContainsNodeModulesSegment;
+exports.resolveMiniappUploadSessionFiles = resolveMiniappUploadSessionFiles;
 exports.shouldUploadDistFile = shouldUploadDistFile;
+exports.validateMiniappUploadPathLengths = validateMiniappUploadPathLengths;
 exports.validateUploadPaths = validateUploadPaths;
 exports.validateUploadTotalSize = validateUploadTotalSize;