react-native-update 10.49.0 → 10.50.0

package/BUNDLEHASH_MIGRATION.md

@@ -4,7 +4,9 @@
 > - DB：pushy 北京 RDS 与 cresc Cloud SQL 均已加 `packages.bundleHash` 列（幂等 runner 在 `scripts/migrate-add-package-bundle-hash.ts`；cresc 经一次性 Cloud Run Job 进 VPC 执行）
 > - 服务：pushy `p`/`s1` @ `2026.7.29-a2ecac26`，cresc api/worker/dailyjob @ `2026.7.29-3aabff91`，线上带 `bundleHash` 冒烟均通过
 > - **`bundleHashJudge.enabled` 仍为关**——待 CLI/客户端发版、覆盖率起来后再开
-> - 客户端与 CLI 已提交**未发版**（npm 发布是独立决策）；Phase 2 遗留见 §4.5，Phase 3 待观察期后
+> - **客户端与 CLI 已发版（2026-07-30）**：`react-native-update@10.49.0`、`react-native-update-cli@2.20.3`。全链路（客户端上报 → CLI 注册 → 服务端判定基建）就位，仅待覆盖率与开开关
+> - **`bundleHashJudge.enabled` 已于 2026-08-03 双端开启**（pushy + cresc，redis `config_dynamic`，回退=写回 false）。同日：CLI 2.21.2 补全 copiesCrc（§4.2.1 第 2 条）并随两服务端部署；客户端三端 CRC 校验 + fallback 遥测（§4.2.1 第 3/4 条）已实现、待随下个客户端版本发布
+> - Phase 2 遗留见 §4.5，Phase 3 待观察期后
 > 依据：`BUNDLEHASH_DESIGN.md`（设计定稿）。本文只讲**怎么落地**，不重复论证为什么。
 > 下游：`NATIVE_CHECKUPDATE_DESIGN.md` 的协议下沉必须等本迁移完成，否则协议下沉后再改协议要返工。
 
@@ -203,6 +205,12 @@ await addFileFromZipEntry(...);       // 只有新文件才打进 patch 包
 3. 客户端拷贝时校验，不符 → fallback full。代价退化为一次 pdiff 下载，**永不装出坏包**
 4. 给该 fallback 加遥测
 
+**已全部落地（2026-08-03）**：
+- 第 2 条：CLI 2.21.2（同路径分支补记 CRC；两服务端已 bump 部署，worker 新生成的 pdiff 均带全量 copiesCrc）
+- 第 3 条（三端）：Android `BundledResourceCopier` 路径命中也比 CRC，不符 → 内容定位 → 仍无 → 抛错；iOS/共享 C++ `CopyOperation.expected_crc` 在 `ApplyPatchFromFileSource` 拷贝前校验（`digest::Crc32File`，NIST/check-value 测试锚定）；Harmony pdiff 拷贝声明 CRC 的条目改走字节路径经 NAPI `crc32` 校验。三端不符均使整次 pdiff 失败，JS 策略链自动落 full
+- 第 4 条：新增本地事件 `downloadFallback`（增量策略失败但后续策略救回），失败码为 PATCH_FAILED 时映射服务端 `patch_fail`（网络噪音不上报）。为此补齐了 Android（`PatchFailedException`：下载完成后的失败 reject 为 PATCH_FAILED，此前一律 DOWNLOAD_FAILED）与 Harmony（patch 阶段 `error.code='PATCH_FAILED'`）的稳定码
+- 注意：存量已生成的 pdiff 只有 moved 条目的 CRC，客户端只校验有声明的条目——旧 pdiff 行为不变，随版本滚动自然收敛
+
 若遥测显示这一行的 pdiff 失败率显著，再引入**精确**判据（如"copies 含非 metro 资源"），而不是用恒为 true 的粗标记一刀切。
 
 ### 4.3 开关与灰度
@@ -236,7 +244,7 @@ cresc-server 是独立仓库（结构同构、历史独立，`handleCheckUpdate`
 
 ### 4.5 Phase 2 遗留（不阻塞开启开关）
 
-- 控制台 unknownBundle 聚合面板（§7 触达第 3 条，主渠道）——需 admin 侧配合。曾考虑挂在 `classifyCheckUpdateResult` 的 hitType 上，否决：hitType 是"下发了什么产物"维度，混入二进制身份维度不干净，应独立埋点
+- ~~控制台 unknownBundle 聚合面板~~ **已实现（2026-08-01，四端部署）**：最终形态不是独立的 bundleStatus"内容判定"维度（首版上线后即废弃——它依赖开关开启+双侧 hash+恰好有更新流动，观测窗口太窄、零数据），而是**请求侧合并进原生包面板**：客户端报了 bundleHash 就记 `packageVersion_bundleHash`（admin 图例把 64 位 hex 截 8 位展示），否则回退 `packageVersion_buildTime`，同一 attribute。全量流量可见、与开关/判定结果解耦；未注册人群在面板上直接带 packageVersion 上下文。代价是丢失 matched/rebuiltSameJs 区分——那只有教育用途，unknownBundle 占比（§4.6 的推进指标）不受影响。曾考虑挂在 `classifyCheckUpdateResult` 的 hitType 上，否决：hitType 是"下发了什么产物"维度，混入二进制身份维度不干净
 - `digests` 下发 + `__diff.json` copies 附摘要——与客户端 Phase 3 的消费侧同波次做
 - ~~CLI 上传冲突提示~~ **已实现（改判为无需动 CLI）**：`(appId, name)` 唯一约束下重复上传本来就 409，在两台服务器的冲突分支里用 bundleHash 增强语义——内容一致 →"无需重复上传"、内容不同 →"重打包且 JS 有变，请提升原生版本号"、任一侧无 hash → 通用文案不变。查询仅发生在冲突路径。cresc 3 条路由级用例覆盖；pushy 无路由级测试脚手架，靠同构代码 + cresc 用例 + tsc 兜底
 
@@ -252,6 +260,18 @@ Phase 2 的收益与 Phase 0/1 的覆盖率成正比，但**不需要等覆盖
 
 ## 5. Phase 3 — 收尾（客户端）
 
+> **定位修订（2026-08-03）：buildTime 不删，永久保留作 fallback。**
+> 理由：服务端分支与客户端双上报的保留成本≈0，而删除的伤害面（bundleHash
+> 空串设备失去二进制身份 → 重打包检测失明 / 双缺请求拿不到 full）明确存在
+> 且只能靠空串率数据压低，收益（构建注入清理、协议更干净）不急迫。注入的
+> pnpm 老毛病若再发作，修注入本身而不是删身份。
+> Phase 3 因此收缩为一件事：**§5.1 的 SyncBinaryVersion 迁移**——改为
+> `bundleHash || buildTime`（bundleHash 优先、buildTime 兜底，schema 认领式
+> 迁移照做）。不做它，rebuiltSameJs 的收益只兑现一半：服务端已不 block、照发
+> pdiff，但客户端 buildTime 一变仍清状态回内置包再白下载一遍；hash 优先后
+> 同 JS 重打包做到真正无感。§5.2 的 digests/copies 摘要照旧待做；§5.3 的
+> 降级序列与"删构建注入"**取消**。
+
 ### 5.1 `SyncBinaryVersion` 迁移有个状态危险，必须处理
 
 设计文档写"`SyncBinaryVersion` 改 `(packageVersion, bundleHash)`"。直接改会出事：

package/android/src/main/java/cn/reactnative/modules/update/BundledResourceCopier.java

@@ -96,6 +96,13 @@ final class BundledResourceCopier {
             // failures (disk full, corrupt archive) that must fail the update,
             // not skips — otherwise the update activates with missing resources.
             ArrayList<String> failedCopies = new ArrayList<String>();
+            // Entries whose manifest-declared CRC32 could not be satisfied by
+            // any installed archive: the path-matched file has different bytes
+            // and no entry anywhere carries the expected content. Copying would
+            // install a wrong resource (rebuilt binary with drifted assets), so
+            // these fail the whole patch — the JS strategy chain then falls
+            // back to the full package.
+            ArrayList<String> crcMismatches = new ArrayList<String>();
 
             for (String fromPath : new ArrayList<String>(remainingFiles.keySet())) {
                 ArrayList<File> targets = remainingFiles.get(fromPath);
@@ -107,6 +114,7 @@ final class BundledResourceCopier {
                 String actualSourcePath = fromPath;
                 SafeZipFile matchedZipFile = null;
                 ResolvedResourceSource resolvedResource = null;
+                Long wantedCrc = crcByFrom != null ? crcByFrom.get(fromPath) : null;
 
                 if (entry == null) {
                     String normalizedFrom = normalizeResPath(fromPath);
@@ -117,21 +125,39 @@ final class BundledResourceCopier {
                     }
                 }
 
+                // Verify a path-matched entry against the manifest-declared
+                // CRC32: a rebuilt binary can keep the path but drift the
+                // content. On mismatch, discard the path match and try to
+                // locate the expected content elsewhere. An entry with an
+                // unknown CRC (-1) cannot be verified and is accepted as-is.
+                if (entry != null && wantedCrc != null
+                    && entry.getCrc() != -1L && entry.getCrc() != wantedCrc.longValue()) {
+                    entry = null;
+                    actualSourcePath = fromPath;
+                }
+
                 // Content (CRC32) match: robust across APK/AAB packaging because
                 // the checksum is over the uncompressed file content, not its
                 // path. Preferred over the resource-id heuristic below.
-                if (entry == null && crcByFrom != null) {
-                    Long wantedCrc = crcByFrom.get(fromPath);
-                    if (wantedCrc != null) {
-                        ZipSource matched = crcToEntry.get(wantedCrc);
-                        if (matched != null) {
-                            entry = matched.entry;
-                            matchedZipFile = matched.zipFile;
-                            actualSourcePath = matched.entry.getName();
-                        }
+                if (entry == null && wantedCrc != null) {
+                    ZipSource matched = crcToEntry.get(wantedCrc);
+                    if (matched != null) {
+                        entry = matched.entry;
+                        matchedZipFile = matched.zipFile;
+                        actualSourcePath = matched.entry.getName();
                     }
                 }
 
+                // A declared CRC that no installed entry satisfies is a hard
+                // content mismatch. The resource-id heuristic below cannot be
+                // trusted here: the content index above already covers every
+                // entry, so anything the heuristic finds has the wrong bytes.
+                if (entry == null && wantedCrc != null) {
+                    crcMismatches.add(fromPath);
+                    remainingFiles.remove(fromPath);
+                    continue;
+                }
+
                 if (entry == null) {
                     resolvedResource = resolveBundledResource(fromPath);
                     if (resolvedResource != null) {
@@ -189,6 +215,13 @@ final class BundledResourceCopier {
                 remainingFiles.remove(fromPath);
             }
 
+            if (!crcMismatches.isEmpty()) {
+                throw new IOException(
+                    "Bundled resource content mismatch (crc32) for "
+                        + crcMismatches.size() + " entries: " + crcMismatches
+                );
+            }
+
             if (!failedCopies.isEmpty()) {
                 throw new IOException(
                     "Failed to copy " + failedCopies.size()

package/android/src/main/java/cn/reactnative/modules/update/DownloadTask.java

@@ -77,6 +77,9 @@ class DownloadTask implements Runnable {
     private final byte[] buffer = new byte[DOWNLOAD_CHUNK_SIZE];
     private final BundledResourceCopier bundledResourceCopier;
     private String hash;
+    // Set once downloadFile() returns: failures after this point in a patch
+    // task are patch-application failures, not download failures.
+    private boolean downloadPhaseCompleted = false;
 
     DownloadTask(Context context, DownloadTaskParams params) {
         this.context = context.getApplicationContext();
@@ -160,6 +163,7 @@ class DownloadTask implements Runnable {
             }
         }
 
+        downloadPhaseCompleted = true;
     }
 
     private byte[] readBytes(InputStream input) throws IOException {
@@ -408,6 +412,12 @@ class DownloadTask implements Runnable {
         }
     }
 
+    private boolean isPatchTask(int taskType) {
+        return taskType == DownloadTaskParams.TASK_TYPE_PATCH_FULL
+            || taskType == DownloadTaskParams.TASK_TYPE_PATCH_FROM_APK
+            || taskType == DownloadTaskParams.TASK_TYPE_PATCH_FROM_PPK;
+    }
+
     @Override
     public void run() {
         int taskType = params.type;
@@ -436,7 +446,18 @@ class DownloadTask implements Runnable {
             cleanUpAfterFailure(taskType);
 
             if (params.listener != null) {
-                params.listener.onDownloadFailed(error);
+                // A patch task that failed after its artifact was fully
+                // downloaded (unzip / hdiff / resource copy, incl. copiesCrc
+                // verification) is a patch failure, not a download failure —
+                // the module maps the exception type to PATCH_FAILED.
+                Throwable classified = error;
+                if (downloadPhaseCompleted
+                    && isPatchTask(taskType)
+                    && !(error instanceof PatchFailedException)) {
+                    classified = new PatchFailedException(
+                        String.valueOf(error.getMessage()), error);
+                }
+                params.listener.onDownloadFailed(classified);
             }
             return;
         }

package/android/src/main/java/cn/reactnative/modules/update/PatchFailedException.java

@@ -0,0 +1,16 @@
+package cn.reactnative.modules.update;
+
+import java.io.IOException;
+
+/**
+ * A download task failure that happened after the artifact was fully
+ * downloaded — unzip, hdiff apply, or bundled-resource copy (including the
+ * copiesCrc content verification). UpdateModuleImpl rejects these with
+ * PATCH_FAILED instead of DOWNLOAD_FAILED so the JS layer and server-side
+ * telemetry can separate patch health from network health.
+ */
+class PatchFailedException extends IOException {
+    PatchFailedException(String message, Throwable cause) {
+        super(message, cause);
+    }
+}

package/android/src/main/java/cn/reactnative/modules/update/UpdateContext.java

@@ -211,12 +211,36 @@ public class UpdateContext {
         executor.execute(new DownloadTask(context, params));
     }
 
+    // Server-provided identifiers (hash/originHash/fileName) become child
+    // names under rootDir; anything that could resolve outside of it (path
+    // separators, "..", ".") must be rejected before touching the filesystem.
+    static boolean isSafePathComponent(String name) {
+        return name != null
+                && !name.isEmpty()
+                && !name.equals(".")
+                && !name.equals("..")
+                && !name.contains("/")
+                && !name.contains("\\")
+                && name.indexOf('\0') < 0;
+    }
+
+    private static boolean rejectUnsafeComponent(String name, DownloadFileListener listener) {
+        if (isSafePathComponent(name)) {
+            return false;
+        }
+        listener.onDownloadFailed(new IllegalArgumentException("Invalid path component: " + name));
+        return true;
+    }
+
     public interface DownloadFileListener {
         void onDownloadCompleted(DownloadTaskParams params);
         void onDownloadFailed(Throwable error);
     }
 
     public void downloadFullUpdate(String url, String hash, DownloadFileListener listener) {
+        if (rejectUnsafeComponent(hash, listener)) {
+            return;
+        }
         DownloadTaskParams params = new DownloadTaskParams();
         params.type = DownloadTaskParams.TASK_TYPE_PATCH_FULL;
         params.url = url;
@@ -228,6 +252,9 @@ public class UpdateContext {
     }
 
     public void downloadFile(String url, String hash, String fileName, DownloadFileListener listener) {
+        if (rejectUnsafeComponent(fileName, listener)) {
+            return;
+        }
         DownloadTaskParams params = new DownloadTaskParams();
         params.type = DownloadTaskParams.TASK_TYPE_PLAIN_DOWNLOAD;
         params.url = url;
@@ -246,6 +273,9 @@ public class UpdateContext {
     }
 
     public void downloadPatchFromApk(String url, String hash, DownloadFileListener listener) {
+        if (rejectUnsafeComponent(hash, listener)) {
+            return;
+        }
         DownloadTaskParams params = new DownloadTaskParams();
         params.type = DownloadTaskParams.TASK_TYPE_PATCH_FROM_APK;
         params.url = url;
@@ -257,6 +287,9 @@ public class UpdateContext {
     }
 
     public void downloadPatchFromPpk(String url, String hash, String originHash, DownloadFileListener listener) {
+        if (rejectUnsafeComponent(hash, listener) || rejectUnsafeComponent(originHash, listener)) {
+            return;
+        }
         DownloadTaskParams params = new DownloadTaskParams();
         params.type = DownloadTaskParams.TASK_TYPE_PATCH_FROM_PPK;
         params.url = url;
@@ -312,6 +345,9 @@ public class UpdateContext {
     }
 
     public void switchVersion(String hash) {
+        if (!isSafePathComponent(hash)) {
+            throw new IllegalArgumentException("Invalid hash: " + hash);
+        }
         if (!new File(rootDir, hash+"/index.bundlejs").exists()) {
             throw new IllegalStateException("Bundle version " + hash + " not found.");
         }

package/android/src/main/java/cn/reactnative/modules/update/UpdateModuleImpl.java

@@ -41,11 +41,20 @@ public class UpdateModuleImpl {
 
             @Override
             public void onDownloadFailed(Throwable error) {
-                promise.reject(ErrorCodes.DOWNLOAD_FAILED, error);
+                promise.reject(downloadErrorCode(error), error);
             }
         });
     }
 
+    // Post-download failures (unzip / hdiff / resource copy, incl. copiesCrc
+    // verification) reject as PATCH_FAILED so JS-side telemetry can separate
+    // patch health from network health. DownloadTask wraps them.
+    private static String downloadErrorCode(Throwable error) {
+        return error instanceof PatchFailedException
+            ? ErrorCodes.PATCH_FAILED
+            : ErrorCodes.DOWNLOAD_FAILED;
+    }
+
     public static void downloadAndInstallApk(
         final ReactApplicationContext reactContext,
         UpdateContext updateContext,
@@ -84,7 +93,7 @@ public class UpdateModuleImpl {
 
             @Override
             public void onDownloadFailed(Throwable error) {
-                promise.reject(ErrorCodes.DOWNLOAD_FAILED, error);
+                promise.reject(downloadErrorCode(error), error);
             }
         });
     }
@@ -107,7 +116,7 @@ public class UpdateModuleImpl {
 
                 @Override
                 public void onDownloadFailed(Throwable error) {
-                    promise.reject(ErrorCodes.DOWNLOAD_FAILED, error);
+                    promise.reject(downloadErrorCode(error), error);
                 }
             });
         } catch (Exception e) {

package/cpp/patch_core/digest.cpp

@@ -173,5 +173,58 @@ std::string Sha256File(const std::string& path) {
   return hasher.HexDigest();
 }
 
+namespace {
+
+struct Crc32TableHolder {
+  uint32_t table[256];
+
+  Crc32TableHolder() {
+    for (uint32_t i = 0; i < 256; i++) {
+      uint32_t value = i;
+      for (int bit = 0; bit < 8; bit++) {
+        value = (value & 1u) ? (value >> 1) ^ 0xEDB88320u : value >> 1;
+      }
+      table[i] = value;
+    }
+  }
+};
+
+const uint32_t* Crc32Table() {
+  // Function-local static: thread-safe one-time construction (C++11).
+  static const Crc32TableHolder holder;
+  return holder.table;
+}
+
+}  // namespace
+
+void Crc32::Update(const uint8_t* data, size_t length) {
+  const uint32_t* table = Crc32Table();
+  uint32_t state = state_;
+  for (size_t i = 0; i < length; i++) {
+    state = table[(state ^ data[i]) & 0xFFu] ^ (state >> 8);
+  }
+  state_ = state;
+}
+
+bool Crc32File(const std::string& path, uint32_t* out) {
+  std::FILE* file = std::fopen(path.c_str(), "rb");
+  if (file == nullptr) {
+    return false;
+  }
+  Crc32 crc;
+  uint8_t buffer[64 * 1024];
+  size_t read = 0;
+  while ((read = std::fread(buffer, 1, sizeof(buffer), file)) > 0) {
+    crc.Update(buffer, read);
+  }
+  const bool failed = std::ferror(file) != 0;
+  std::fclose(file);
+  if (failed) {
+    return false;
+  }
+  *out = crc.Value();
+  return true;
+}
+
 }  // namespace digest
 }  // namespace pushy

package/cpp/patch_core/digest.h

@@ -39,5 +39,23 @@ class Sha256 {
 // digest, or an empty string if the file cannot be read.
 std::string Sha256File(const std::string& path);
 
+// Streaming CRC32 (IEEE 802.3, reflected polynomial 0xEDB88320 — the zip /
+// zlib checksum). Used to verify pdiff copy sources against the CRCs the CLI
+// records from the origin package's zip entries (copiesCrc in __diff.json):
+// the values must be byte-compatible with what any zip tool would report.
+class Crc32 {
+ public:
+  void Update(const uint8_t* data, size_t length);
+
+  uint32_t Value() const { return state_ ^ 0xFFFFFFFFu; }
+
+ private:
+  uint32_t state_ = 0xFFFFFFFFu;
+};
+
+// CRC32 of a file on disk (streaming, bounded memory). Returns false if the
+// file cannot be read.
+bool Crc32File(const std::string& path, uint32_t* out);
+
 }  // namespace digest
 }  // namespace pushy

package/cpp/patch_core/patch_core.cpp

@@ -1,5 +1,7 @@
 #include "patch_core.h"
 
+#include "digest.h"
+
 #include <cerrno>
 #include <cstdio>
 #include <cstring>
@@ -532,8 +534,22 @@ Status ApplyPatchFromFileSource(
   }
 
   for (const CopyOperation& copy : options.manifest.copies) {
+    const std::string source_path = JoinPath(options.source_root, copy.from);
+    if (copy.has_expected_crc) {
+      uint32_t actual_crc = 0;
+      if (!digest::Crc32File(source_path, &actual_crc)) {
+        return Status::Error("Failed to read copy source " + source_path);
+      }
+      if (actual_crc != copy.expected_crc) {
+        // Rebuilt binary with drifted content at an unchanged path. Fail the
+        // patch — the caller falls back to the full package; never install a
+        // resource whose bytes differ from what the diff was generated against.
+        return Status::Error(
+            "Copy source content mismatch (crc32): " + copy.from);
+      }
+    }
     Status copy_status = CopyFile(
-        JoinPath(options.source_root, copy.from),
+        source_path,
         JoinPath(options.target_root, copy.to),
         true);
     if (!copy_status) {

package/cpp/patch_core/patch_core.h

@@ -1,5 +1,6 @@
 #pragma once
 
+#include <cstdint>
 #include <ctime>
 #include <string>
 #include <vector>
@@ -20,6 +21,13 @@ struct Status {
 struct CopyOperation {
   std::string from;
   std::string to;
+  // Manifest-declared CRC32 of the source content (__diff.json copiesCrc,
+  // present in pdiff manifests from CLI >= 2.21.2). When set, the copy source
+  // is verified before copying; a mismatch fails the whole patch so the JS
+  // strategy chain falls back to the full package instead of installing a
+  // wrong resource from a rebuilt binary.
+  bool has_expected_crc = false;
+  uint32_t expected_crc = 0;
 };
 
 struct PatchManifest {

package/cpp/patch_core/tests/patch_core_test.cpp

@@ -814,6 +814,102 @@ void TestSha256File() {
       "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) {
@@ -848,6 +944,9 @@ int main(int argc, char** argv) {
       {"Sha256KnownVectors", TestSha256KnownVectors},
       {"Sha256StreamingMatchesOneShot", TestSha256StreamingMatchesOneShot},
       {"Sha256File", TestSha256File},
+      {"Crc32KnownVectors", TestCrc32KnownVectors},
+      {"Crc32File", TestCrc32File},
+      {"ApplyPatchCopiesVerifyExpectedCrc", TestApplyPatchCopiesVerifyExpectedCrc},
   };
 
   int failures = 0;

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

@@ -936,6 +936,52 @@ static napi_value Sha256Hex(napi_env env, napi_callback_info info) {
   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;
@@ -954,6 +1000,7 @@ napi_value Init(napi_env env, napi_value exports) {
       !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;
   }