react-native-update 10.55.1 → 10.56.1

package/cpp/update_flow_core/update_flow_core.h

@@ -2,6 +2,7 @@
 
 #include <cstdint>
 #include <string>
+#include <vector>
 
 #include "flow_json.h"
 
@@ -24,6 +25,14 @@ uint32_t Murmur3_32(const std::string& key, uint32_t seed = 0);
 // murmur(uuid) % 100 < rollout — the gray-release bucketing predicate.
 bool IsInRollout(double rollout, const std::string& uuid);
 
+// Whether a failed download attempt should move on to the next mirror of the
+// same artifact. Anything but PATCH_FAILED is: every mirror serves the same
+// bytes, so a patch that could not be applied fails on all of them and only
+// the next strategy can help. An absent code (empty string) is retryable.
+// Mirrors isMirrorRetryableCode; covered by the golden vectors so the native
+// orchestrators' retry loops cannot drift from the TS reference.
+bool IsMirrorRetryableCode(const std::string& code);
+
 // paths × fileName -> candidate URL array; Undefined when fileName is falsy
 // (mirrors joinUrls returning undefined without a file name).
 flowjson::Value JoinUrls(const flowjson::Value& paths,

package/cpp/update_flow_core/update_flow_jni.cpp

@@ -1,10 +1,13 @@
 // JNI surface of the update-flow decision layer for the Android orchestrator
 // (NativeCheckOrchestrator.java). Pure string-in/string-out: every payload is
 // JSON, matching the decision layer's own boundary. A null return means
-// "input did not parse" and the caller skips the check round.
+// "input did not parse" and the caller skips the check round; a C++ exception
+// (bad_alloc/length_error from an oversized body) maps onto that same path —
+// it must never unwind through the JNI boundary.
 #include <jni.h>
 
 #include <cstdint>
+#include <exception>
 #include <limits>
 #include <string>
 #include <vector>
@@ -81,27 +84,35 @@ jstring ToJString(JNIEnv* env, const std::string& value) {
 extern "C" JNIEXPORT jstring JNICALL
 Java_cn_reactnative_modules_update_NativeUpdateFlow_buildCheckRequestBody(
     JNIEnv* env, jclass, jstring inputJson) {
-  bool ok = false;
-  flowjson::Value input = flowjson::Parse(
-      pushy::jni_util::JStringToString(env, inputJson), &ok);
-  if (!ok || !input.IsObject()) {
+  try {
+    bool ok = false;
+    flowjson::Value input = flowjson::Parse(
+        pushy::jni_util::JStringToString(env, inputJson), &ok);
+    if (!ok || !input.IsObject()) {
+      return nullptr;
+    }
+    return ToJString(
+        env, flowjson::Stringify(updateflow::BuildCheckRequestBody(input)));
+  } catch (...) {
     return nullptr;
   }
-  return ToJString(
-      env, flowjson::Stringify(updateflow::BuildCheckRequestBody(input)));
 }
 
 extern "C" JNIEXPORT jstring JNICALL
 Java_cn_reactnative_modules_update_NativeUpdateFlow_orderEndpointCandidates(
     JNIEnv* env, jclass, jstring endpointsJson, jdouble randomSample) {
-  bool ok = false;
-  flowjson::Value endpoints = flowjson::Parse(
-      pushy::jni_util::JStringToString(env, endpointsJson), &ok);
-  if (!ok || !endpoints.IsArray()) {
+  try {
+    bool ok = false;
+    flowjson::Value endpoints = flowjson::Parse(
+        pushy::jni_util::JStringToString(env, endpointsJson), &ok);
+    if (!ok || !endpoints.IsArray()) {
+      return nullptr;
+    }
+    return ToJString(env, flowjson::Stringify(updateflow::OrderEndpointCandidates(
+                              endpoints, randomSample)));
+  } catch (...) {
     return nullptr;
   }
-  return ToJString(env, flowjson::Stringify(updateflow::OrderEndpointCandidates(
-                            endpoints, randomSample)));
 }
 
 extern "C" JNIEXPORT jboolean JNICALL
@@ -110,24 +121,32 @@ Java_cn_reactnative_modules_update_NativeUpdateFlow_isValidCheckResponse(
   if (responseText == nullptr) {
     return JNI_FALSE;
   }
-  return updateflow::IsValidCheckResponse(
-             pushy::jni_util::JStringToString(env, responseText))
-             ? JNI_TRUE
-             : JNI_FALSE;
+  try {
+    return updateflow::IsValidCheckResponse(
+               pushy::jni_util::JStringToString(env, responseText))
+               ? JNI_TRUE
+               : JNI_FALSE;
+  } catch (...) {
+    return JNI_FALSE;
+  }
 }
 
 extern "C" JNIEXPORT jstring JNICALL
 Java_cn_reactnative_modules_update_NativeUpdateFlow_handleCheckResponse(
     JNIEnv* env, jclass, jstring responseText, jstring identityJson,
     jstring afterDownload) {
-  bool ok = false;
-  flowjson::Value identity = flowjson::Parse(
-      pushy::jni_util::JStringToString(env, identityJson), &ok);
-  if (!ok || !identity.IsObject()) {
+  try {
+    bool ok = false;
+    flowjson::Value identity = flowjson::Parse(
+        pushy::jni_util::JStringToString(env, identityJson), &ok);
+    if (!ok || !identity.IsObject()) {
+      return nullptr;
+    }
+    return ToJString(env, flowjson::Stringify(updateflow::HandleCheckResponse(
+                              pushy::jni_util::JStringToString(env, responseText),
+                              identity, false,
+                              pushy::jni_util::JStringToString(env, afterDownload))));
+  } catch (...) {
     return nullptr;
   }
-  return ToJString(env, flowjson::Stringify(updateflow::HandleCheckResponse(
-                            pushy::jni_util::JStringToString(env, responseText),
-                            identity, false,
-                            pushy::jni_util::JStringToString(env, afterDownload))));
 }

package/harmony/hvigor-plugin.ts

@@ -1,34 +1,181 @@
 import fs from 'fs';
 import path from 'path';
 
+// Structural view of the hvigor objects this plugin touches, so the file has
+// no compile-time dependency on @ohos/hvigor typings (it is compiled by the
+// consumer's hvigor, whatever version that is).
+interface HvigorTaskContext {
+  getBuildMode?: () => string;
+}
+
+interface HvigorModuleContext {
+  getBuildMode?: () => string;
+}
+
+interface HvigorTask {
+  name: string;
+  run: (taskContext?: HvigorTaskContext) => void;
+  dependencies?: string[];
+  postDependencies?: string[];
+}
+
+interface HvigorNodeLike {
+  getNodePath?: () => string;
+  getParentNode?: () => HvigorNodeLike | undefined;
+  getContext?: (pluginId: string) => HvigorModuleContext | undefined;
+  registerTask?: (task: HvigorTask) => void;
+}
+
+export const META_RELATIVE_PATH = 'src/main/resources/rawfile/meta.json';
+const TASK_NAME = 'pushyWriteBuildMeta';
+// OhosPluginId.OHOS_HAP_PLUGIN / OHOS_HSP_PLUGIN / OHOS_HAR_PLUGIN.
+const MODULE_PLUGIN_IDS = ['ohosHapPlugin', 'ohosHspPlugin', 'ohosHarPlugin'];
+
+function readVersionName(projectDir: string): string {
+  const appJsonPath = path.resolve(projectDir, 'AppScope/app.json5');
+  if (!fs.existsSync(appJsonPath)) {
+    return '';
+  }
+  const content = fs.readFileSync(appJsonPath, 'utf-8');
+  const match = content.match(
+    /(?:"versionName"|versionName):\s*["']([^"']+)["']/,
+  );
+  return match?.[1] || '';
+}
+
+// Only `hvigorw assemble{Hap,App,Hsp,Har}` (DevEco's Build/Run actions pass
+// the same task) should touch the consumer's source tree; IDE sync
+// (`--sync`), `clean` and friends must not rewrite meta.json.
+export function isAssembleInvocation(argv: string[]): boolean {
+  return argv.some(arg => /^assemble/i.test(arg));
+}
+
+export function resolveBuildMode(
+  node: HvigorNodeLike,
+  taskContext: HvigorTaskContext | undefined,
+  argv: string[],
+): string {
+  if (taskContext && typeof taskContext.getBuildMode === 'function') {
+    return String(taskContext.getBuildMode());
+  }
+  if (typeof node.getContext === 'function') {
+    for (const pluginId of MODULE_PLUGIN_IDS) {
+      try {
+        const context = node.getContext(pluginId);
+        if (context && typeof context.getBuildMode === 'function') {
+          return String(context.getBuildMode());
+        }
+      } catch (e) {
+        // not this module type
+      }
+    }
+  }
+  // `hvigorw assembleHap -p buildMode=release` (DevEco passes the same
+  // property for its build actions); hvigor's default mode is debug.
+  const fromArgv = argv.find(arg => arg.startsWith('buildMode='));
+  return fromArgv ? fromArgv.substring('buildMode='.length) : 'debug';
+}
+
+// The plugin is meant for a module hvigorfile (entry/hvigorfile.ts). When it
+// is applied from the project hvigorfile instead, the node path is the
+// project root (AppScope lives there): fall back to entry/ like the original
+// plugin did, so an existing setup keeps working.
+export function resolveModuleDir(node: HvigorNodeLike, cwd: string): string {
+  const nodePath =
+    typeof node.getNodePath === 'function' ? node.getNodePath() : '';
+  if (!nodePath) {
+    return path.resolve(cwd, 'entry');
+  }
+  if (fs.existsSync(path.join(nodePath, 'AppScope', 'app.json5'))) {
+    console.warn(
+      'reactNativeUpdatePlugin: applied at project level; writing meta.json ' +
+        'into entry/. Apply it from the module hvigorfile instead.',
+    );
+    return path.join(nodePath, 'entry');
+  }
+  return nodePath;
+}
+
+export function resolveProjectDir(
+  node: HvigorNodeLike,
+  moduleDir: string,
+): string {
+  const parent =
+    typeof node.getParentNode === 'function' ? node.getParentNode() : undefined;
+  if (parent && typeof parent.getNodePath === 'function') {
+    const parentPath = parent.getNodePath();
+    if (parentPath) {
+      return parentPath;
+    }
+  }
+  return path.dirname(moduleDir);
+}
+
+// Debug builds get "0" like Android's `pushy_build_time` resValue: a debug
+// rebuild must not look like a new binary and reset the update state.
+export function buildMetaContent(
+  buildMode: string,
+  versionName: string,
+  now: number,
+): { pushy_build_time: string; versionName: string } {
+  return {
+    pushy_build_time: buildMode.toLowerCase() === 'release' ? String(now) : '0',
+    versionName,
+  };
+}
+
+/**
+ * Writes rawfile/meta.json (pushy_build_time + versionName) into the module
+ * this plugin is applied to. The write happens in a build task that runs
+ * before resources are compiled, not in apply(): apply() runs on every hvigor
+ * invocation including IDE sync, and only assemble invocations register the
+ * task at all.
+ */
 export function reactNativeUpdatePlugin() {
   return {
     pluginId: 'reactNativeUpdatePlugin',
-    apply() {
-      const cwd = process.cwd();
-      const metaFilePath = path.resolve(
-        cwd,
-        'entry/src/main/resources/rawfile/meta.json',
-      );
-      fs.mkdirSync(path.dirname(metaFilePath), { recursive: true });
-
-      const moduleJsonPath = path.resolve(cwd, 'AppScope/app.json5');
-      let versionName = '';
-      if (fs.existsSync(moduleJsonPath)) {
-        const content = fs.readFileSync(moduleJsonPath, 'utf-8');
-        const match = content.match(
-          /(?:"versionName"|versionName):\s*["']([^"']+)["']/,
-        );
-        versionName = match?.[1] || '';
+    apply(node?: HvigorNodeLike) {
+      const argv = process.argv;
+      if (!isAssembleInvocation(argv)) {
+        return;
       }
+      const safeNode: HvigorNodeLike = node ?? {};
+      const moduleDir = resolveModuleDir(safeNode, process.cwd());
+      const projectDir = resolveProjectDir(safeNode, moduleDir);
 
-      const metaContent = {
-        pushy_build_time: String(Date.now()),
-        versionName,
+      const writeMeta = (taskContext?: HvigorTaskContext) => {
+        const buildMode = resolveBuildMode(safeNode, taskContext, argv);
+        const metaFilePath = path.resolve(moduleDir, META_RELATIVE_PATH);
+        fs.mkdirSync(path.dirname(metaFilePath), { recursive: true });
+        const metaContent = buildMetaContent(
+          buildMode,
+          readVersionName(projectDir),
+          Date.now(),
+        );
+        fs.writeFileSync(metaFilePath, JSON.stringify(metaContent, null, 2));
+        console.log(`Build time written to ${metaFilePath} (${buildMode})`);
       };
 
-      fs.writeFileSync(metaFilePath, JSON.stringify(metaContent, null, 2));
-      console.log(`Build time written to ${metaFilePath}`);
+      if (typeof safeNode.registerTask === 'function') {
+        try {
+          safeNode.registerTask({
+            name: TASK_NAME,
+            run: writeMeta,
+            dependencies: ['default@PreBuild'],
+            postDependencies: ['default@ProcessResource'],
+          });
+          return;
+        } catch (e) {
+          console.warn(
+            `reactNativeUpdatePlugin: task registration failed (${
+              e instanceof Error ? e.message : String(e)
+            }), writing meta.json at apply time`,
+          );
+        }
+      }
+      // Very old hvigor without task registration: keep the previous
+      // behaviour (write at apply time), still only for assemble builds.
+      writeMeta();
     },
   };
 }

package/harmony/pushy/src/README.md

@@ -0,0 +1,74 @@
+# react-native-update — HarmonyOS module (`pushy`)
+
+Integration notes for the HAR that ships in the `react-native-update` npm
+package (`harmony/pushy.har`). The general setup lives in the project README;
+this file covers what the host app must declare itself.
+
+## Permissions
+
+The HAR does not declare `requestPermissions`: downloads and update checks run
+inside the host app's process, so the **host** must request the network
+permission in its entry `module.json5`:
+
+```json5
+{
+  "module": {
+    "requestPermissions": [
+      { "name": "ohos.permission.INTERNET" }
+    ]
+  }
+}
+```
+
+Without it every check and download fails with a network error.
+
+## No https → http downgrade (`cleartextTrafficPermitted`)
+
+`@ohos.net.http` follows redirects internally and exposes neither a switch nor
+the final URL, so unlike Android/iOS the module cannot itself refuse an
+`https → http` redirect. What it does: when the configured endpoints are all
+`https://`, any `http://` endpoint injected through the remote endpoint list
+and any `http://` artifact URL in a check decision are ignored.
+
+To close the redirect gap, keep cleartext traffic disabled for the app in
+`entry/src/main/resources/base/profile/network_config.json` (and reference it
+from `module.json5` via `"metadata": [{ "name": "network_config", "resource": "$profile:network_config" }]`):
+
+```json
+{
+  "network-security-config": {
+    "base-config": {
+      "cleartextTrafficPermitted": false
+    }
+  }
+}
+```
+
+## Build-time metadata (`hvigor-plugin`)
+
+Apply the plugin from the **module** hvigorfile (`entry/hvigorfile.ts`):
+
+```ts
+import { hapTasks } from '@ohos/hvigor-ohos-plugin';
+import { reactNativeUpdatePlugin } from 'pushy/hvigor-plugin';
+
+export default {
+  system: hapTasks,
+  plugins: [reactNativeUpdatePlugin()],
+};
+```
+
+It writes `src/main/resources/rawfile/meta.json` (`pushy_build_time`,
+`versionName`) into that module during `assemble*` builds only, before
+resources are compiled. Debug builds get `pushy_build_time: "0"` like Android,
+so a debug rebuild does not look like a new binary. Add the generated file to
+`.gitignore`.
+
+## Versioning
+
+`oh-package.json5` `version` mirrors the npm package version;
+`scripts/build-harmony-har.js` rewrites it before `assembleHar` and
+`scripts/check-release-version.js` asserts the committed value matches.
+
+This file is packaged with the npm module (`harmony/pushy/src/`) so it is
+available next to the sources in `node_modules/react-native-update`.

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

@@ -71,8 +71,18 @@ if(TARGET rnoh)
     target_link_libraries(rnoh_pushy PUBLIC rnoh)
 endif()
 
-# Optimize binary size and performance for Release builds
+# Optimize binary size for Release builds of the NAPI library. --gc-sections
+# only drops anything when every function/data item sits in its own section,
+# and the module registers itself through NAPI_MODULE's static constructor,
+# so no symbol needs default visibility. Scoped to rnupdate: rnoh_pushy must
+# keep exporting PushyTurboModule (JSI_EXPORT) for the host's PackageProvider.
 if(NOT CMAKE_BUILD_TYPE STREQUAL "Debug")
-    # Strip debug symbols and perform garbage collection of unused code sections
-    set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -Wl,--gc-sections -s")
+    target_compile_options(rnupdate PRIVATE
+        -ffunction-sections
+        -fdata-sections
+        -fvisibility=hidden
+        -fvisibility-inlines-hidden
+    )
+    # Strip debug symbols and garbage-collect the unused sections.
+    target_link_options(rnupdate PRIVATE -Wl,--gc-sections -s)
 endif()

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

@@ -45,15 +45,21 @@ jsi::Value CallAsync(
     return CallAsync(rt, turboModule, #method_name, args, count);        \
   }
 
+// Only the constants and the RN event plumbing are synchronous. Every
+// Promise-returning spec method (src/NativePushy.ts) MUST be registered
+// with PUSHY_ASYNC_METHOD: a sync registration converts the ArkTS Promise
+// into an empty jsi object and its rejection becomes an unhandled ArkTS
+// rejection, so JS would report e.g. setNeedUpdate as successful while
+// nothing was switched. scripts/check-native-spec-parity.js enforces this.
 PUSHY_SYNC_METHOD(getConstants)
-PUSHY_SYNC_METHOD(setLocalHashInfo)
-PUSHY_SYNC_METHOD(getLocalHashInfo)
-PUSHY_SYNC_METHOD(setUuid)
-PUSHY_SYNC_METHOD(setNeedUpdate)
-PUSHY_SYNC_METHOD(markSuccess)
 PUSHY_SYNC_METHOD(addListener)
 PUSHY_SYNC_METHOD(removeListeners)
 
+PUSHY_ASYNC_METHOD(setLocalHashInfo)
+PUSHY_ASYNC_METHOD(getLocalHashInfo)
+PUSHY_ASYNC_METHOD(setUuid)
+PUSHY_ASYNC_METHOD(setNeedUpdate)
+PUSHY_ASYNC_METHOD(markSuccess)
 PUSHY_ASYNC_METHOD(reloadUpdate)
 PUSHY_ASYNC_METHOD(restartApp)
 PUSHY_ASYNC_METHOD(downloadPatchFromPpk)

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

@@ -667,12 +667,24 @@ struct CleanupWork {
   napi_async_work work = nullptr;
   napi_deferred deferred = nullptr;
   std::string root_dir;
-  std::string keep_current;
-  std::string keep_previous;
+  // Every version that may still be in use: persisted current/last AND the
+  // version this process booted from (two switches without a restart must not
+  // evict the running bundle while its on-demand assets are still served).
+  std::vector<std::string> keep_names;
   int32_t max_age_days = 0;
   pushy::patch::Status status{false, ""};
 };
 
+// Streaming file digest on a worker thread. A full package or bundle is tens
+// of MB; hashing it synchronously on the UI thread (where the TurboModule
+// runs) froze the app for hundreds of ms per archive/bundle/activation.
+struct Sha256FileWork {
+  napi_async_work work = nullptr;
+  napi_deferred deferred = nullptr;
+  std::string path;
+  std::string hex;
+};
+
 napi_value ApplyPatchFromFileSource(napi_env env, napi_callback_info info) {
   napi_value args[1] = {nullptr};
   size_t argc = 1;
@@ -785,10 +797,11 @@ napi_value ApplyPatchFromFileSource(napi_env env, napi_callback_info info) {
   return promise;
 }
 
+// cleanupOldEntries(rootDir, keepNames: string[], maxAgeDays)
 napi_value CleanupOldEntries(napi_env env, napi_callback_info info) {
-  napi_value args[4] = {nullptr, nullptr, nullptr, nullptr};
-  size_t argc = 4;
-  if (!GetArgCount(env, info, &argc, args) || argc < 4) {
+  napi_value args[3] = {nullptr, nullptr, nullptr};
+  size_t argc = 3;
+  if (!GetArgCount(env, info, &argc, args) || argc < 3) {
     ThrowError(env, "Wrong number of arguments");
     return nullptr;
   }
@@ -798,23 +811,18 @@ napi_value CleanupOldEntries(napi_env env, napi_callback_info info) {
   if (!ok) {
     return nullptr;
   }
-  const std::string keep_current = GetString(env, args[1], &ok);
-  if (!ok) {
-    return nullptr;
-  }
-  const std::string keep_previous = GetString(env, args[2], &ok);
-  if (!ok) {
+  std::vector<std::string> keep_names;
+  if (!GetStringArray(env, args[1], &keep_names)) {
     return nullptr;
   }
   int32_t max_age_days = 0;
-  if (!GetInt32(env, args[3], &max_age_days)) {
+  if (!GetInt32(env, args[2], &max_age_days)) {
     return nullptr;
   }
 
   auto* work_data = new CleanupWork();
   work_data->root_dir = root_dir;
-  work_data->keep_current = keep_current;
-  work_data->keep_previous = keep_previous;
+  work_data->keep_names = std::move(keep_names);
   work_data->max_age_days = max_age_days;
 
   napi_value promise = nullptr;
@@ -834,7 +842,7 @@ napi_value CleanupOldEntries(napi_env env, napi_callback_info info) {
           [](napi_env, void* data) {
             auto* w = static_cast<CleanupWork*>(data);
             w->status = pushy::patch::CleanupOldEntries(
-                w->root_dir, w->keep_current, w->keep_previous, w->max_age_days);
+                w->root_dir, w->keep_names, w->max_age_days);
           },
           [](napi_env cb_env, napi_status status, void* data) {
             auto* w = static_cast<CleanupWork*>(data);
@@ -872,6 +880,76 @@ napi_value CleanupOldEntries(napi_env env, napi_callback_info info) {
   return promise;
 }
 
+// sha256HexFileAsync(path) -> Promise<hex>. Rejects when the file cannot be
+// read (Sha256File returns an empty digest in that case).
+napi_value Sha256HexFileAsync(napi_env env, napi_callback_info info) {
+  napi_value args[1] = {nullptr};
+  size_t argc = 1;
+  if (!GetArgCount(env, info, &argc, args) || argc < 1) {
+    ThrowError(env, "sha256HexFileAsync: missing path argument");
+    return nullptr;
+  }
+  bool ok = false;
+  std::string path = GetString(env, args[0], &ok);
+  if (!ok) {
+    return nullptr;
+  }
+  if (path.empty()) {
+    ThrowError(env, "sha256HexFileAsync: path must be a non-empty string");
+    return nullptr;
+  }
+
+  auto* work_data = new Sha256FileWork();
+  work_data->path = std::move(path);
+
+  napi_value promise = nullptr;
+  if (napi_create_promise(env, &work_data->deferred, &promise) != napi_ok) {
+    delete work_data;
+    ThrowError(env, "Unable to create promise");
+    return nullptr;
+  }
+
+  napi_value resource_name = nullptr;
+  napi_create_string_utf8(
+      env, "sha256HexFileAsync", NAPI_AUTO_LENGTH, &resource_name);
+  if (napi_create_async_work(
+          env,
+          nullptr,
+          resource_name,
+          [](napi_env, void* data) {
+            auto* w = static_cast<Sha256FileWork*>(data);
+            w->hex = pushy::digest::Sha256File(w->path);
+          },
+          [](napi_env cb_env, napi_status status, void* data) {
+            auto* w = static_cast<Sha256FileWork*>(data);
+            if (status != napi_ok) {
+              RejectDeferredWithMessage(cb_env, w->deferred, "async work aborted");
+            } else if (w->hex.empty()) {
+              RejectDeferredWithMessage(
+                  cb_env, w->deferred, "sha256HexFileAsync: cannot read file");
+            } else {
+              napi_resolve_deferred(cb_env, w->deferred, NewString(cb_env, w->hex));
+            }
+            napi_delete_async_work(cb_env, w->work);
+            delete w;
+          },
+          work_data,
+          &work_data->work) != napi_ok) {
+    RejectDeferredWithMessage(
+        env, work_data->deferred, "Unable to create async work");
+    delete work_data;
+    return promise;
+  }
+  if (napi_queue_async_work(env, work_data->work) != napi_ok) {
+    napi_delete_async_work(env, work_data->work);
+    RejectDeferredWithMessage(
+        env, work_data->deferred, "Unable to queue async work");
+    delete work_data;
+    return promise;
+  }
+  return promise;
+}
+
 bool ExportFunction(
     napi_env env,
     napi_value exports,
@@ -898,7 +976,8 @@ bool ExportFunction(
 // rawfile 里的 bundle(已整体读入内存,与 pdiff 的读法一致),哈希本身毫秒级。
 static napi_value MakeUtf8String(napi_env env, const std::string& value);
 
-// Streaming file digest (bounded memory) for the install record.
+// Streaming file digest (bounded memory). Synchronous: small files only —
+// archives and bundles go through sha256HexFileAsync.
 static napi_value Sha256HexFile(napi_env env, napi_callback_info info) {
   size_t argc = 1;
   napi_value args[1] = {nullptr};
@@ -909,7 +988,7 @@ static napi_value Sha256HexFile(napi_env env, napi_callback_info info) {
   bool ok = false;
   std::string path = GetString(env, args[0], &ok);
   if (!ok) {
-    ThrowError(env, "sha256HexFile: path must be a string");
+    // GetString already raised the pending exception.
     return nullptr;
   }
   return MakeUtf8String(env, pushy::digest::Sha256File(path));
@@ -1089,8 +1168,13 @@ static napi_value FlowIsValidCheckResponse(napi_env env,
   }
   bool ok = false;
   std::string response_text = GetString(env, args[0], &ok);
+  if (!ok) {
+    // Exception pending (non-string argument): propagate it as a throw
+    // instead of a boolean that the caller would treat as a verdict.
+    return nullptr;
+  }
   napi_value result = nullptr;
-  napi_get_boolean(env, ok && updateflow::IsValidCheckResponse(response_text),
+  napi_get_boolean(env, updateflow::IsValidCheckResponse(response_text),
                    &result);
   return result;
 }
@@ -1135,6 +1219,7 @@ napi_value Init(napi_env env, napi_value exports) {
       !ExportFunction(env, exports, "cleanupOldEntries", CleanupOldEntries) ||
       !ExportFunction(env, exports, "sha256Hex", Sha256Hex) ||
       !ExportFunction(env, exports, "sha256HexFile", Sha256HexFile) ||
+      !ExportFunction(env, exports, "sha256HexFileAsync", Sha256HexFileAsync) ||
       !ExportFunction(env, exports, "crc32", Crc32) ||
       !ExportFunction(env, exports, "getSupportedDiffVersion", GetSupportedDiffVersion) ||
       !ExportFunction(env, exports, "buildCheckRequestBody", FlowBuildCheckRequestBody) ||