react-native-update 10.48.3 → 10.50.0

package/cpp/patch_core/tests/patch_core_test.cpp

@@ -1,4 +1,5 @@
 #include "../archive_patch_core.h"
+#include "../digest.h"
 #include "../patch_core.h"
 #include "../state_core.h"
 
@@ -747,6 +748,168 @@ void TestStateCoreSwitchToSameVersion() {
   Expect(!switched.first_time_ok, "first_time_ok should be false");
 }
 
+// NIST FIPS 180-4 vectors. These anchor the C++ implementation (iOS/Harmony)
+// and, by transitivity, Android's java.security.MessageDigest and the CLI's
+// node:crypto to the same standard — the bundleHash produced on any of them
+// must be byte-identical for the same input.
+void TestSha256KnownVectors() {
+  {
+    pushy::digest::Sha256 hasher;
+    ExpectEq(
+        hasher.HexDigest(),
+        "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+        "sha256 of empty input");
+  }
+  {
+    pushy::digest::Sha256 hasher;
+    const char* input = "abc";
+    hasher.Update(reinterpret_cast<const uint8_t*>(input), 3);
+    ExpectEq(
+        hasher.HexDigest(),
+        "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad",
+        "sha256 of \"abc\"");
+  }
+  {
+    pushy::digest::Sha256 hasher;
+    const std::string input =
+        "abcdbcdecdefdefgefghfghighijhijkijkljklmklmnlmnomnopnopq";
+    hasher.Update(
+        reinterpret_cast<const uint8_t*>(input.data()), input.size());
+    ExpectEq(
+        hasher.HexDigest(),
+        "248d6a61d20638b8e5c026930c3e6039a33ce45964ff2167f6ecedd419db06c1",
+        "sha256 of NIST two-block message");
+  }
+}
+
+void TestSha256StreamingMatchesOneShot() {
+  // One million 'a' (NIST long vector), fed in deliberately awkward chunk
+  // sizes to cross every buffer boundary case in Update.
+  const std::string chunk(4096 + 37, 'a');
+  size_t remaining = 1000000;
+  pushy::digest::Sha256 hasher;
+  while (remaining > 0) {
+    const size_t take = remaining < chunk.size() ? remaining : chunk.size();
+    hasher.Update(reinterpret_cast<const uint8_t*>(chunk.data()), take);
+    remaining -= take;
+  }
+  ExpectEq(
+      hasher.HexDigest(),
+      "cdc76e5c9914fb9281a1c7e284d73e67f1809a48a497200e046d39ccc7112cd0",
+      "sha256 of one million 'a' fed in odd-sized chunks");
+}
+
+void TestSha256File() {
+  TempDir temp;
+  const std::string dir = temp.path;
+  const std::string path = dir + "/input.bin";
+  WriteFile(path, "abc");
+  ExpectEq(
+      pushy::digest::Sha256File(path),
+      "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad",
+      "Sha256File over a small file");
+  ExpectEq(
+      pushy::digest::Sha256File(dir + "/missing.bin"),
+      "",
+      "Sha256File over a missing file returns empty");
+}
+
+void TestCrc32KnownVectors() {
+  {
+    pushy::digest::Crc32 crc;
+    Expect(crc.Value() == 0x00000000u, "crc32 of empty input");
+  }
+  {
+    // The classic check value: crc32("123456789") == 0xCBF43926.
+    pushy::digest::Crc32 crc;
+    const char* input = "123456789";
+    crc.Update(reinterpret_cast<const uint8_t*>(input), 9);
+    Expect(crc.Value() == 0xCBF43926u, "crc32 check value of \"123456789\"");
+  }
+  {
+    // Streaming in awkward chunks must match the one-shot value.
+    const std::string input(100000, 'a');
+    pushy::digest::Crc32 one_shot;
+    one_shot.Update(
+        reinterpret_cast<const uint8_t*>(input.data()), input.size());
+    pushy::digest::Crc32 streamed;
+    size_t offset = 0;
+    size_t chunk = 1;
+    while (offset < input.size()) {
+      const size_t take =
+          offset + chunk > input.size() ? input.size() - offset : chunk;
+      streamed.Update(
+          reinterpret_cast<const uint8_t*>(input.data()) + offset, take);
+      offset += take;
+      chunk = chunk * 2 + 1;
+    }
+    Expect(
+        streamed.Value() == one_shot.Value(),
+        "crc32 streaming matches one-shot");
+  }
+}
+
+void TestCrc32File() {
+  TempDir temp;
+  const std::string dir = temp.path;
+  const std::string path = dir + "/input.bin";
+  WriteFile(path, "123456789");
+  uint32_t value = 0;
+  Expect(pushy::digest::Crc32File(path, &value), "Crc32File should read");
+  Expect(value == 0xCBF43926u, "Crc32File check value");
+  Expect(
+      !pushy::digest::Crc32File(dir + "/missing.bin", &value),
+      "Crc32File over a missing file returns false");
+}
+
+void TestApplyPatchCopiesVerifyExpectedCrc() {
+  TempDir temp;
+  const std::string source = JoinPath(temp.path, "origin");
+  const std::string target = JoinPath(temp.path, "target");
+  const std::string patch = JoinPath(temp.path, "bundle.patch");
+
+  WriteFile(JoinPath(source, "index.bundlejs"), "old bundle");
+  WriteFile(JoinPath(source, "assets/keep.txt"), "123456789");
+  WriteFile(patch, "unused patch");
+
+  FakeBundlePatcher patcher("patched bundle");
+  FileSourcePatchOptions options;
+  options.source_root = source;
+  options.target_root = target;
+  options.origin_bundle_path = JoinPath(source, "index.bundlejs");
+  options.bundle_patch_path = patch;
+  options.bundle_output_path = JoinPath(target, "index.bundlejs");
+  options.enable_merge = false;
+  CopyOperation copy;
+  copy.from = "assets/keep.txt";
+  copy.to = "assets/keep.txt";
+  copy.has_expected_crc = true;
+  copy.expected_crc = 0xCBF43926u;  // crc32("123456789")
+  options.manifest.copies.push_back(copy);
+
+  Status status = ApplyPatchFromFileSource(options, patcher);
+  Expect(status.ok, status.message);
+  ExpectEq(
+      ReadFile(JoinPath(target, "assets/keep.txt")),
+      "123456789",
+      "verified copy content");
+
+  // Same manifest applied on a "rebuilt" source whose file drifted: the copy
+  // must fail the whole patch (caller falls back to full), not copy silently.
+  WriteFile(JoinPath(source, "assets/keep.txt"), "drifted-bytes");
+  const std::string target2 = JoinPath(temp.path, "target2");
+  options.target_root = target2;
+  options.bundle_output_path = JoinPath(target2, "index.bundlejs");
+  Status mismatch = ApplyPatchFromFileSource(options, patcher);
+  Expect(!mismatch.ok, "drifted copy source must fail the patch");
+  Expect(
+      mismatch.message.find("crc32") != std::string::npos,
+      "mismatch error should mention crc32");
+  Expect(
+      !Exists(JoinPath(target2, "assets/keep.txt")),
+      "drifted content must not be copied");
+}
+
 }  // namespace
 
 int main(int argc, char** argv) {
@@ -778,6 +941,12 @@ int main(int argc, char** argv) {
       {"StateCoreRollbackToEmptyVersion", TestStateCoreRollbackToEmptyVersion},
       {"StateCoreResolveLaunchNoCurrentVersion", TestStateCoreResolveLaunchNoCurrentVersion},
       {"StateCoreSwitchToSameVersion", TestStateCoreSwitchToSameVersion},
+      {"Sha256KnownVectors", TestSha256KnownVectors},
+      {"Sha256StreamingMatchesOneShot", TestSha256StreamingMatchesOneShot},
+      {"Sha256File", TestSha256File},
+      {"Crc32KnownVectors", TestCrc32KnownVectors},
+      {"Crc32File", TestCrc32File},
+      {"ApplyPatchCopiesVerifyExpectedCrc", TestApplyPatchCopiesVerifyExpectedCrc},
   };
 
   int failures = 0;

package/harmony/pushy/src/main/cpp/CMakeLists.txt

@@ -27,6 +27,7 @@ set(LZMA_DIR ${ANDROID_JNI_DIR}/lzma)
 set(HDP_SOURCES
      ${CMAKE_CURRENT_SOURCE_DIR}/pushy.cpp
      ${PATCH_CORE_DIR}/archive_patch_core.cpp
+     ${PATCH_CORE_DIR}/digest.cpp
      ${PATCH_CORE_DIR}/hbc_transform.cpp
      ${PATCH_CORE_DIR}/hbc_transform_wire.cpp
      ${PATCH_CORE_DIR}/patch_core.cpp

package/harmony/pushy/src/main/cpp/pushy.cpp

@@ -6,6 +6,7 @@
 #include <vector>
 
 #include "archive_patch_core.h"
+#include "digest.h"
 #include "hbc_transform_wire.h"
 #include "patch_core.h"
 #include "state_core.h"
@@ -890,6 +891,97 @@ bool ExportFunction(
 }  // namespace
 
 
+// sha256(Uint8Array | ArrayBuffer) -> 小写 hex。同步：bundleHash 的输入是
+// rawfile 里的 bundle(已整体读入内存,与 pdiff 的读法一致),哈希本身毫秒级。
+static napi_value Sha256Hex(napi_env env, napi_callback_info info) {
+  size_t argc = 1;
+  napi_value args[1] = {nullptr};
+  if (!GetArgCount(env, info, &argc, args) || argc < 1) {
+    ThrowError(env, "sha256Hex: missing data argument");
+    return nullptr;
+  }
+
+  void* data = nullptr;
+  size_t length = 0;
+  bool is_typedarray = false;
+  napi_is_typedarray(env, args[0], &is_typedarray);
+  if (is_typedarray) {
+    napi_typedarray_type type;
+    napi_value arraybuffer = nullptr;
+    size_t offset = 0;
+    if (napi_get_typedarray_info(
+            env, args[0], &type, &length, &data, &arraybuffer, &offset) !=
+        napi_ok) {
+      ThrowError(env, "sha256Hex: cannot read typed array");
+      return nullptr;
+    }
+  } else {
+    bool is_arraybuffer = false;
+    napi_is_arraybuffer(env, args[0], &is_arraybuffer);
+    if (!is_arraybuffer ||
+        napi_get_arraybuffer_info(env, args[0], &data, &length) != napi_ok) {
+      ThrowError(env, "sha256Hex: expected Uint8Array or ArrayBuffer");
+      return nullptr;
+    }
+  }
+
+  pushy::digest::Sha256 hasher;
+  if (length > 0) {
+    hasher.Update(static_cast<const uint8_t*>(data), length);
+  }
+  const std::string hex = hasher.HexDigest();
+
+  napi_value result = nullptr;
+  napi_create_string_utf8(env, hex.c_str(), hex.size(), &result);
+  return result;
+}
+
+// CRC32(zip/zlib 多项式)。同步:输入是已在内存的 rawfile 资源字节,用于
+// pdiff 拷贝前与 __diff.json copiesCrc 比对(不符则整次 patch 失败落 full)。
+static napi_value Crc32(napi_env env, napi_callback_info info) {
+  size_t argc = 1;
+  napi_value args[1] = {nullptr};
+  if (!GetArgCount(env, info, &argc, args) || argc < 1) {
+    ThrowError(env, "crc32: missing data argument");
+    return nullptr;
+  }
+
+  void* data = nullptr;
+  size_t length = 0;
+  bool is_typedarray = false;
+  napi_is_typedarray(env, args[0], &is_typedarray);
+  if (is_typedarray) {
+    napi_typedarray_type type;
+    napi_value arraybuffer = nullptr;
+    size_t offset = 0;
+    if (napi_get_typedarray_info(
+            env, args[0], &type, &length, &data, &arraybuffer, &offset) !=
+        napi_ok) {
+      ThrowError(env, "crc32: cannot read typed array");
+      return nullptr;
+    }
+  } else {
+    bool is_arraybuffer = false;
+    napi_is_arraybuffer(env, args[0], &is_arraybuffer);
+    if (!is_arraybuffer ||
+        napi_get_arraybuffer_info(env, args[0], &data, &length) != napi_ok) {
+      ThrowError(env, "crc32: expected Uint8Array or ArrayBuffer");
+      return nullptr;
+    }
+  }
+
+  pushy::digest::Crc32 crc;
+  if (length > 0) {
+    crc.Update(static_cast<const uint8_t*>(data), length);
+  }
+
+  napi_value result = nullptr;
+  // CRC32 fits a double exactly (32-bit unsigned), matching the JSON number
+  // representation in the manifest.
+  napi_create_double(env, static_cast<double>(crc.Value()), &result);
+  return result;
+}
+
 // 原生 patch 内核可消费的 diff 轨道版本(2 = hdiffv2 轨道)
 static napi_value GetSupportedDiffVersion(napi_env env, napi_callback_info) {
   napi_value result = nullptr;
@@ -907,6 +999,8 @@ napi_value Init(napi_env env, napi_value exports) {
       !ExportFunction(env, exports, "buildCopyGroups", BuildCopyGroups) ||
       !ExportFunction(env, exports, "applyPatchFromFileSource", ApplyPatchFromFileSource) ||
       !ExportFunction(env, exports, "cleanupOldEntries", CleanupOldEntries) ||
+      !ExportFunction(env, exports, "sha256Hex", Sha256Hex) ||
+      !ExportFunction(env, exports, "crc32", Crc32) ||
       !ExportFunction(env, exports, "getSupportedDiffVersion", GetSupportedDiffVersion)) {
     return nullptr;
   }

package/harmony/pushy/src/main/ets/DownloadTask.ts

@@ -15,6 +15,10 @@ import NativePatchCore, {
 export interface PatchManifestArrays {
   copyFroms: string[];
   copyTos: string[];
+  // 与 copyFroms/copyTos 逐位对齐的 copiesCrc(CLI >= 2.21.2 的 pdiff
+  // manifest 携带,键是 to);无声明时为 null。拷贝前用它校验包内资源内容,
+  // 不符则整次 patch 失败落 full——重打包二进制不能静默拷出漂移的资源。
+  copyCrcs: (number | null)[];
   deletes: string[];
   // __diff.json 中对应 bundle patch 条目的 hbcTransform 元数据(原始 JSON
   // 字符串);为空时 native 走现状路径
@@ -27,6 +31,7 @@ export function parseManifestToArrays(
 ): PatchManifestArrays {
   const copyFroms: string[] = [];
   const copyTos: string[] = [];
+  const copyCrcs: (number | null)[] = [];
   const deletesValue = manifest.deletes;
   const deletes = Array.isArray(deletesValue)
     ? deletesValue.map(item => String(item))
@@ -35,6 +40,11 @@ export function parseManifestToArrays(
       : [];
 
   const copies = (manifest.copies || {}) as Record<string, string>;
+  const copiesCrcValue = manifest.copiesCrc;
+  const copiesCrc =
+    copiesCrcValue && typeof copiesCrcValue === 'object'
+      ? (copiesCrcValue as Record<string, number>)
+      : ({} as Record<string, number>);
   for (const [to, rawFrom] of Object.entries(copies)) {
     let from = String(rawFrom || '');
     if (normalizeResourceCopies) {
@@ -45,6 +55,8 @@ export function parseManifestToArrays(
     }
     copyFroms.push(from);
     copyTos.push(to);
+    const crc = copiesCrc[to];
+    copyCrcs.push(typeof crc === 'number' && Number.isFinite(crc) ? crc : null);
   }
 
   const hbcTransform = manifest.hbcTransform as
@@ -62,6 +74,7 @@ export function parseManifestToArrays(
   return {
     copyFroms,
     copyTos,
+    copyCrcs,
     deletes,
     hbcTransformMeta,
   };
@@ -229,6 +242,7 @@ export class DownloadTask {
       return {
         copyFroms: [],
         copyTos: [],
+        copyCrcs: [],
         deletes: [],
         hbcTransformMeta: '',
       };
@@ -534,6 +548,20 @@ export class DownloadTask {
 
   private async doPatchFromApp(params: DownloadTaskParams): Promise<void> {
     await this.downloadFile(params);
+    try {
+      await this.doPatchFromAppAfterDownload(params);
+    } catch (error: any) {
+      // 下载已完成,之后的失败都是 patch 应用失败(解压/hpatch/资源拷贝,
+      // 含 copiesCrc 校验)。打上稳定码,JS 层遥测按 patch_fail 归类,
+      // 而不是混进网络失败。
+      error.code = 'PATCH_FAILED';
+      throw error;
+    }
+  }
+
+  private async doPatchFromAppAfterDownload(
+    params: DownloadTaskParams,
+  ): Promise<void> {
     await this.recreateDirectory(params.unzipDirectory);
 
     await zlib.decompressFile(params.targetFile, params.unzipDirectory);
@@ -566,12 +594,22 @@ export class DownloadTask {
       `${params.unzipDirectory}/bundle.harmony.js`,
       manifestArrays.hbcTransformMeta,
     );
+    // 组按 from 聚合;同一 from 的内容必然一致,所以每组一个 CRC 即可
+    // (与 manifest 逐位对齐的 copyCrcs 里取第一个非空值)。
+    const crcByFrom = new Map<string, number>();
+    manifestArrays.copyFroms.forEach((from, index) => {
+      const crc = manifestArrays.copyCrcs[index];
+      if (crc !== null && !crcByFrom.has(from)) {
+        crcByFrom.set(from, crc);
+      }
+    });
     await this.copyFromResource(
       NativePatchCore.buildCopyGroups(
         manifestArrays.copyFroms,
         manifestArrays.copyTos,
       ),
       params.unzipDirectory,
+      crcByFrom,
     );
     try {
       if (fileIo.accessSync(params.targetFile)) {
@@ -584,6 +622,18 @@ export class DownloadTask {
 
   private async doPatchFromPpk(params: DownloadTaskParams): Promise<void> {
     await this.downloadFile(params);
+    try {
+      await this.doPatchFromPpkAfterDownload(params);
+    } catch (error: any) {
+      // 同 doPatchFromApp:下载完成后的失败按 patch 失败归类。
+      error.code = 'PATCH_FAILED';
+      throw error;
+    }
+  }
+
+  private async doPatchFromPpkAfterDownload(
+    params: DownloadTaskParams,
+  ): Promise<void> {
     await this.recreateDirectory(params.unzipDirectory);
 
     await zlib.decompressFile(params.targetFile, params.unzipDirectory);
@@ -626,6 +676,7 @@ export class DownloadTask {
   private async copyFromResource(
     copyGroups: CopyGroupResult[],
     targetRoot: string,
+    crcByFrom?: Map<string, number>,
   ): Promise<void> {
     let currentFrom = '';
     try {
@@ -637,6 +688,7 @@ export class DownloadTask {
         if (targets.length === 0) {
           continue;
         }
+        const expectedCrc = crcByFrom?.get(currentFrom);
 
         if (currentFrom.startsWith('resources/base/media/')) {
           // Strip only the final extension: 'icon.round.png' -> 'icon.round',
@@ -645,6 +697,7 @@ export class DownloadTask {
             .replace('resources/base/media/', '')
             .replace(/\.[^.]+$/, '');
           const mediaBuffer = await resourceManager.getMediaByName(mediaName);
+          this.verifyCopySourceCrc(mediaBuffer, expectedCrc, currentFrom);
           const parentDirs = [
             ...new Set(
               targets.map(t => t.substring(0, t.lastIndexOf('/'))).filter(Boolean),
@@ -658,6 +711,22 @@ export class DownloadTask {
           );
           continue;
         }
+
+        if (expectedCrc !== undefined) {
+          // 声明了 CRC 的条目改走字节路径:读出内容先校验再落盘。
+          // 重打包的二进制里同名 rawfile 内容可能已漂移,fd 直拷会把
+          // 错误字节静默装进版本目录。
+          const rawContent =
+            await resourceManager.getRawFileContent(currentFrom);
+          this.verifyCopySourceCrc(rawContent, expectedCrc, currentFrom);
+          const [firstTarget, ...restTargets] = targets;
+          await this.writeFileContent(firstTarget, rawContent);
+          await Promise.all(
+            restTargets.map(target => this.copySandboxFile(firstTarget, target)),
+          );
+          continue;
+        }
+
         const fromContent = await resourceManager.getRawFd(currentFrom);
         try {
           const [firstTarget, ...restTargets] = targets;
@@ -697,6 +766,22 @@ export class DownloadTask {
     }
   }
 
+  // pdiff 拷贝源内容校验(__diff.json copiesCrc):不符即抛错,整次 patch
+  // 失败后 JS 策略链自动回退 full,绝不把漂移的资源装进版本目录。
+  private verifyCopySourceCrc(
+    content: Uint8Array,
+    expectedCrc: number | undefined,
+    from: string,
+  ): void {
+    if (expectedCrc === undefined) {
+      return;
+    }
+    const actualCrc = NativePatchCore.crc32(content);
+    if (actualCrc !== expectedCrc) {
+      throw new Error(`resource content mismatch (crc32): ${from}`);
+    }
+  }
+
   private async doCleanUp(params: DownloadTaskParams): Promise<void> {
     try {
       await NativePatchCore.cleanupOldEntries(

package/harmony/pushy/src/main/ets/NativePatchCore.ts

@@ -80,6 +80,10 @@ interface NativePatchCoreBindings {
     keepPrevious: string,
     maxAgeDays: number,
   ): Promise<void>;
+  /** sha256(小写 hex)。同步:输入是已在内存的 rawfile bundle,哈希毫秒级 */
+  sha256Hex(data: Uint8Array): string;
+  /** CRC32(zip/zlib 多项式)。pdiff 拷贝前与 copiesCrc 比对用 */
+  crc32(data: Uint8Array | ArrayBuffer): number;
   /** 原生 patch 内核可消费的 diff 轨道版本(2 = hdiffv2 轨道) */
   getSupportedDiffVersion(): number;
 }

package/harmony/pushy/src/main/ets/PushyTurboModule.ts

@@ -233,6 +233,17 @@ export class PushyTurboModule extends UITurboModule {
     }
   }
 
+  async getBundleHash(): Promise<string> {
+    logger.debug(TAG, ',call getBundleHash');
+    try {
+      return this.context.getBundleHash();
+    } catch (error) {
+      // 空串 = "未知",服务端回退 buildTime 启发式;该方法永不 reject。
+      logger.error(TAG, `getBundleHash failed: ${getErrorMessage(error)}`);
+      return '';
+    }
+  }
+
   async resetToPackagedBundle(): Promise<void> {
     logger.debug(TAG, ',call resetToPackagedBundle');
     try {

package/harmony/pushy/src/main/ets/UpdateContext.ts

@@ -20,6 +20,27 @@ type FlushablePreferences = preferences.Preferences & {
   flushSync?: () => void;
 };
 
+// 服务端下发的 hash/originHash/fileName 会拼进 rootDir 作为子路径；凡是可能
+// 逃出 rootDir 的值（路径分隔符、".."、"."）必须在触碰文件系统前拒绝。
+export function isSafePathComponent(name: string): boolean {
+  return (
+    typeof name === 'string' &&
+    name.length > 0 &&
+    name !== '.' &&
+    name !== '..' &&
+    !name.includes('/') &&
+    !name.includes('\\') &&
+    !name.includes('\0')
+  );
+}
+
+function assertSafePathComponent(name: string): string {
+  if (!isSafePathComponent(name)) {
+    throw Error(`Invalid path component: ${name}`);
+  }
+  return name;
+}
+
 export class UpdateContext {
   private context: common.UIAbilityContext;
   private rootDir: string;
@@ -296,7 +317,7 @@ export class UpdateContext {
     const params = new DownloadTaskParams();
     params.type = type;
     params.url = url;
-    params.hash = hash;
+    params.hash = assertSafePathComponent(hash);
     return params;
   }
 
@@ -474,7 +495,7 @@ export class UpdateContext {
       url,
       hash,
     );
-    params.targetFile = this.rootDir + '/' + fileName;
+    params.targetFile = this.rootDir + '/' + assertSafePathComponent(fileName);
     await this.executeTask(params);
   }
 
@@ -488,7 +509,7 @@ export class UpdateContext {
       url,
       hash,
     );
-    params.originHash = originHash;
+    params.originHash = assertSafePathComponent(originHash);
     params.targetFile = `${this.rootDir}/${originHash}_${hash}.ppk.patch`;
     params.unzipDirectory = `${this.rootDir}/${hash}`;
     params.originDirectory = `${this.rootDir}/${params.originHash}`;
@@ -516,7 +537,7 @@ export class UpdateContext {
 
   public switchVersion(hash: string): void {
     try {
-      const bundlePath = this.getBundlePath(hash);
+      const bundlePath = this.getBundlePath(assertSafePathComponent(hash));
       if (!fileIo.accessSync(bundlePath)) {
         throw Error(`Bundle version ${hash} not found.`);
       }
@@ -632,4 +653,58 @@ export class UpdateContext {
   public getIsUsingBundleUrl(): boolean {
     return UpdateContext.isUsingBundleUrl;
   }
+
+  // bundleHash 缓存:"<packageVersion>|<updateTime>|<sha256hex>"。键标识当前
+  // 安装的二进制,每次(覆盖)安装 updateTime 都会变,每个安装只算一次。
+  private static readonly KEY_BUNDLE_HASH_CACHE = 'bundleHashCache';
+
+  private getBundleUpdateTime(): number {
+    try {
+      const bundleInfo = bundleManager.getBundleInfoForSelfSync(
+        this.getBundleFlags(),
+      );
+      return bundleInfo?.updateTime ?? 0;
+    } catch (error) {
+      console.error('Failed to get bundle update time:', error);
+      return 0;
+    }
+  }
+
+  /**
+   * bundleHash = 二进制内嵌 JS bundle 的 sha256 —— 标识二进制本身,与当前运行
+   * 的热更版本无关。哈希对象与 pdiff 的源读取完全一致:rawfile 的
+   * bundle.harmony.js(DownloadTask.doPatchFromApp 同一读法)。懒计算 + 缓存;
+   * 永不失败——空串表示"未知",服务端回退 buildTime 启发式。
+   */
+  public async getBundleHash(): Promise<string> {
+    if (UpdateContext.DEBUG) {
+      // debug 下 bundle 由 metro 提供,与 dev 删 buildTime 的行为对齐。
+      return '';
+    }
+    const cachePrefix = `${this.getPackageVersion()}|${this.getBundleUpdateTime()}|`;
+    const cached = this.readString(UpdateContext.KEY_BUNDLE_HASH_CACHE);
+    if (cached.startsWith(cachePrefix)) {
+      return cached.slice(cachePrefix.length);
+    }
+    let hash = '';
+    try {
+      // 异步读:TurboModule 跑在 UI 线程,同步读几 MB 会卡主线程一次。C++
+      // 哈希本身毫秒级,同步无妨。
+      const content =
+        await this.context.resourceManager.getRawFileContent('bundle.harmony.js');
+      hash = NativePatchCore.sha256Hex(content);
+    } catch (error) {
+      // rawfile 缺 bundle(未打包 release bundle)是合法的"未知",不是错误。
+      console.info('Cannot hash embedded bundle:', error);
+      return '';
+    }
+    if (hash) {
+      this.preferences.putSync(
+        UpdateContext.KEY_BUNDLE_HASH_CACHE,
+        cachePrefix + hash,
+      );
+      this.flushPreferences('cache bundle hash');
+    }
+    return hash;
+  }
 }