fix: land external review findings — hedged endpoints, murmur3, path guards, singleton client

- endpoint: replace the Promise.all fallback round (which waited for the
  slowest endpoint and blasted every candidate at once) with a hedged race:
  preferred endpoint first, 250ms stagger, first success wins, losers are
  cancelled via AbortController; fetchWithTimeout now chains a caller signal
- isInRollout: restore the missing k1 assignment in murmurhash3_32_gc; output
  now matches the canonical murmur3 vectors (rollout buckets reshuffle once)
- provider: only __rnPushyVersionHash wraps options.logger, other __rnPushy*
  payloads no longer hijack it permanently
- iOS: exclude Application Support/rctpushy from iCloud backup
  (NSURLIsExcludedFromBackupKey), including directories created by older
  versions
- iOS/Android/Harmony: server-provided hash/originHash/fileName are validated
  as safe single path components before touching the filesystem
- singleton client: a second different client (appKey/type) or a concurrently
  mounted UpdateProvider throws SINGLETON_VIOLATION; identical re-creation is
  idempotent for fast refresh; setOptions bumps optionsVersion and notifies
  onOptionsChange so runtime option changes reach provider effects

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: sunnylqm

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

@@ -211,12 +211,36 @@ private void enqueue(DownloadTaskParams params) {
         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 void downloadFullUpdate(String url, String hash, DownloadFileListener lis
     }
 
     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 void downloadFile(String url, String hash, String fileName, DownloadFileL
     }
 
     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 void downloadPatchFromApk(String url, String hash, DownloadFileListener l
     }
 
     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 @@ private void persistEditor(SharedPreferences.Editor editor, String reason) {
     }
 
     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.");
         }

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.`);
       }

harmony/pushy/src/test/Validation.test.ets

@@ -1,7 +1,28 @@
 import { describe, it, expect } from '@ohos/hypium';
 import { validateHashInfo, getErrorMessage } from '../main/ets/PushyTurboModule';
+import { isSafePathComponent } from '../main/ets/UpdateContext';
 
 export default function validationTest() {
+  describe('isSafePathComponent', () => {
+    it('accepts a plain hash-like name', 0, () => {
+      expect(isSafePathComponent('a1b2c3d4')).assertEqual(true);
+      expect(isSafePathComponent('origin_hash-1.ppk')).assertEqual(true);
+    });
+
+    it('rejects empty and dot names', 0, () => {
+      expect(isSafePathComponent('')).assertEqual(false);
+      expect(isSafePathComponent('.')).assertEqual(false);
+      expect(isSafePathComponent('..')).assertEqual(false);
+    });
+
+    it('rejects names containing path separators', 0, () => {
+      expect(isSafePathComponent('../etc')).assertEqual(false);
+      expect(isSafePathComponent('a/b')).assertEqual(false);
+      expect(isSafePathComponent('a\\b')).assertEqual(false);
+      expect(isSafePathComponent('a\0b')).assertEqual(false);
+    });
+  });
+
   describe('validateHashInfo', () => {
     it('accepts valid JSON object', 0, () => {
       let threw = false;

ios/RCTPushy/RCTPushy.mm

@@ -139,6 +139,25 @@ static BOOL PushyStringIsBlank(NSString *value) {
     return [[value stringByTrimmingCharactersInSet:[NSCharacterSet whitespaceAndNewlineCharacterSet]] length] == 0;
 }
 
+// Server-provided identifiers (hash/originHash) are used as child names under
+// the download root; anything that could resolve outside of it (path
+// separators, "..", ".") must be rejected before touching the filesystem.
+static BOOL PushyIsSafePathComponent(NSString *value) {
+    if (PushyStringIsBlank(value)) {
+        return NO;
+    }
+    if ([value isEqualToString:@"."] || [value isEqualToString:@".."]) {
+        return NO;
+    }
+    if ([value containsString:@"/"] || [value containsString:@"\\"]) {
+        return NO;
+    }
+    if ([value rangeOfString:@"\0"].location != NSNotFound) {
+        return NO;
+    }
+    return YES;
+}
+
 static void PushyRejectError(RCTPromiseRejectBlock reject, NSError *error) {
     // Prefer the stable cross-platform code (error_codes.h); fall back to the
     // numeric NSError code for system errors that were not classified.
@@ -248,6 +267,7 @@ - (void)applyPatchForHash:(NSString *)hash
                  callback:(void (^)(NSError *error))callback;
 - (BOOL)switchVersion:(NSString *)hash error:(NSError **)error;
 - (BOOL)ensureDirectoryExistsAtPath:(NSString *)path;
++ (void)excludeFromBackup:(NSString *)path;
 - (void)unzipFileAtPath:(NSString *)path
           toDestination:(NSString *)destination
       completionHandler:(void (^)(NSError *error))completionHandler;
@@ -694,12 +714,12 @@ - (void)performUpdate:(PushyType)type options:(NSDictionary *)options callback:(
     NSString *updateUrl = PushyOptionString(options, @"updateUrl");
     NSString *hash = PushyOptionString(options, @"hash");
 
-    if (PushyStringIsBlank(updateUrl) || PushyStringIsBlank(hash)) {
+    if (PushyStringIsBlank(updateUrl) || !PushyIsSafePathComponent(hash)) {
         callback(PushyErrorWithCode(pushy::error_codes::kInvalidOptions, ERROR_OPTIONS));
         return;
     }
     NSString *originHash = PushyOptionString(options, @"originHash");
-    if (type == PushyTypePatchFromPpk && PushyStringIsBlank(originHash)) {
+    if (type == PushyTypePatchFromPpk && !PushyIsSafePathComponent(originHash)) {
         callback(PushyErrorWithCode(pushy::error_codes::kInvalidOptions, ERROR_OPTIONS));
         return;
     }
@@ -893,7 +913,7 @@ - (void)applyPatchForHash:(NSString *)hash
 
 - (BOOL)switchVersion:(NSString *)hash error:(NSError **)error
 {
-    if (PushyStringIsBlank(hash)) {
+    if (!PushyIsSafePathComponent(hash)) {
         if (error != NULL) {
             *error = PushyErrorWithCode(pushy::error_codes::kInvalidOptions, ERROR_OPTIONS);
         }
@@ -922,6 +942,10 @@ - (BOOL)ensureDirectoryExistsAtPath:(NSString *)path
     NSFileManager *fileManager = [NSFileManager defaultManager];
     BOOL isDirectory = NO;
     if ([fileManager fileExistsAtPath:path isDirectory:&isDirectory]) {
+        if (isDirectory) {
+            // Directories created by older versions never got the flag.
+            [RCTPushy excludeFromBackup:path];
+        }
         return isDirectory;
     }
 
@@ -933,10 +957,27 @@ - (BOOL)ensureDirectoryExistsAtPath:(NSString *)path
     if (!success && error != nil) {
         RCTLogWarn(@"Pushy create directory error: %@", error.localizedDescription);
     }
+    if (success) {
+        [RCTPushy excludeFromBackup:path];
+    }
 
     return success;
 }
 
+// Everything under rctpushy is re-downloadable, and Application Support is
+// backed up to iCloud by default — Apple requires such content to be
+// excluded from backups.
++ (void)excludeFromBackup:(NSString *)path
+{
+    NSURL *url = [NSURL fileURLWithPath:path isDirectory:YES];
+    NSError *error = nil;
+    if (![url setResourceValue:@YES
+                        forKey:NSURLIsExcludedFromBackupKey
+                         error:&error]) {
+        RCTLogWarn(@"Pushy exclude from backup error: %@", error.localizedDescription);
+    }
+}
+
 - (void)unzipFileAtPath:(NSString *)path
           toDestination:(NSString *)destination
       completionHandler:(void (^)(NSError *error))completionHandler

src/__tests__/client.test.ts

@@ -1276,21 +1276,84 @@ describe('downloadAndInstallApk apkStatus (JS-3)', () => {
   });
 });
 
-describe('options isolation across instances', () => {
-  test('mutating options on one instance does not affect another instance', async () => {
+describe('client singleton', () => {
+  test('a second client with a different appKey throws SINGLETON_VIOLATION', async () => {
     setupClientMocks();
-    const { Pushy } = await importFreshClient('options-isolation');
-    const client1 = new Pushy({ appKey: 'app-1', debug: true });
-    const client2 = new Pushy({ appKey: 'app-2', debug: false });
+    const { Pushy } = await importFreshClient('singleton-different-appkey');
+    const client1 = new Pushy({ appKey: 'app-1' });
+    expect(client1.options.appKey).toBe('app-1');
 
-    client1.setOptions({ updateStrategy: 'alwaysAlert' });
+    let error: any;
+    try {
+      new Pushy({ appKey: 'app-2' });
+    } catch (e) {
+      error = e;
+    }
+    expect(error?.code).toBe('SINGLETON_VIOLATION');
+  });
 
-    expect(client1.options.appKey).toBe('app-1');
+  test('a Cresc client after a Pushy client throws SINGLETON_VIOLATION', async () => {
+    setupClientMocks();
+    const { Pushy, Cresc } = await importFreshClient('singleton-cross-type');
+    new Pushy({ appKey: 'app-1' });
+
+    let error: any;
+    try {
+      new Cresc({ appKey: 'app-1' });
+    } catch (e) {
+      error = e;
+    }
+    expect(error?.code).toBe('SINGLETON_VIOLATION');
+  });
+
+  test('re-creating the same client is idempotent and applies the new options', async () => {
+    setupClientMocks();
+    const { Pushy } = await importFreshClient('singleton-idempotent');
+    const client1 = new Pushy({ appKey: 'app-1', debug: true });
+    // e.g. dev fast refresh re-running the module that builds the client
+    const client2 = new Pushy({
+      appKey: 'app-1',
+      updateStrategy: 'silentAndNow',
+    });
+
+    expect(client2).toBe(client1);
     expect(client1.options.debug).toBe(true);
-    expect(client1.options.updateStrategy).toBe('alwaysAlert');
+    expect(client1.options.updateStrategy).toBe('silentAndNow');
+  });
+
+  test('setOptions bumps optionsVersion and notifies subscribers', async () => {
+    setupClientMocks();
+    const { Pushy } = await importFreshClient('singleton-options-version');
+    const client = new Pushy({ appKey: 'app-1' });
+    const initialVersion = client.optionsVersion;
+    const listener = mock(() => {});
+    const unsubscribe = client.onOptionsChange(listener);
 
-    expect(client2.options.appKey).toBe('app-2');
-    expect(client2.options.debug).toBe(false);
-    expect(client2.options.updateStrategy).not.toBe('alwaysAlert');
+    client.setOptions({ updateStrategy: 'alwaysAlert' });
+    expect(client.optionsVersion).toBe(initialVersion + 1);
+    expect(listener).toHaveBeenCalledTimes(1);
+
+    unsubscribe();
+    client.setOptions({ updateStrategy: 'silentAndNow' });
+    expect(listener).toHaveBeenCalledTimes(1);
+  });
+
+  test('a second concurrent provider mount claim throws SINGLETON_VIOLATION', async () => {
+    setupClientMocks();
+    const { Pushy } = await importFreshClient('singleton-provider-claim');
+    const client = new Pushy({ appKey: 'app-1' });
+
+    const release = client.claimProviderMount();
+    let error: any;
+    try {
+      client.claimProviderMount();
+    } catch (e) {
+      error = e;
+    }
+    expect(error?.code).toBe('SINGLETON_VIOLATION');
+
+    // After unmount the claim is released and a new provider may mount.
+    release();
+    expect(() => client.claimProviderMount()).not.toThrow();
   });
 });