feat(cloud-sync): enhance keyless sync utilities and improve documentation

- Add a guideline to avoid using JSON.stringify() for cryptographic operations, promoting the use of stringUtils.stableStringify() for deterministic serialization.
- Refactor keylessCloudSyncUtils to export functions directly, improving usability and clarity.
- Update BIP32 key documentation to clarify encryption states and usage.
- Clean up ServiceMasterPassword and CloudSyncItemBuilder by removing unnecessary checks and improving error handling.
- Adjust keyless sync constants to reflect updated derivation paths for better clarity and consistency.

Author: sidmorizon

CLAUDE.md

@@ -69,6 +69,7 @@ OneKey is an open-source multi-chain crypto wallet with a monorepo architecture
 - ❌ **NEVER** modify auto-generated files (`translations.ts`, locale JSON files)
 - ❌ **NEVER** bypass TypeScript types with `any` or `@ts-ignore` without documented justification
 - ❌ **NEVER** commit code that fails linting or TypeScript compilation
+- ❌ **NEVER** use `JSON.stringify()` for cryptographic operations → ALWAYS use `stringUtils.stableStringify()` for deterministic serialization when computing hashes or signatures
 
 ## Git Basics
 

packages/core/src/secret/bip32.ts

@@ -15,31 +15,8 @@ export type IBip32ExtendedKeySerialized = {
 /**
  * BIP32 Extended Key
  *
- * Represents a BIP32 hierarchical deterministic key pair with chain code.
- *
- * **Key Encryption State:**
- * The `key` field can be in two states depending on context:
- *
- * 1. **Unencrypted (Raw Private Key):**
- *    - During BIP32 derivation calculations (CKDPriv, CKDPub)
- *    - Internal processing within secret module
- *    - Should NEVER be exposed outside the secret module
- *
- * 2. **Encrypted (AES-256 Encrypted Private Key):**
- *    - When returned by `batchGetPrivateKeys()` or similar functions
- *    - When stored or passed between modules
- *    - Encryption method: AES-256-CBC with PBKDF2
- *      - Random salt (32 bytes) + Random IV (16 bytes)
- *      - Format: `[salt(32) + iv(16) + encrypted_data]`
- *    - Must be decrypted with `decryptAsync({ password, data: key })` before use
- *
- * **For Public Keys:**
- * When this type represents a public key (via `deriver.N()`):
- * - `key` contains the raw public key (unencrypted, as public keys are meant to be public)
- * - No encryption is applied
- *
- * @see batchGetKeys() in secret/index.ts for encryption logic
- * @see encryptAsync() in secret/encryptors/aes256.ts for encryption implementation
+ * key 字段：模块内推导为明文私钥；跨模块返回/存储为 AES-256 加密。
+ * 公钥场景不加密。
  */
 export type IBip32ExtendedKey = {
   key: Buffer;

packages/kit-bg/src/services/ServiceMasterPassword/ServiceMasterPassword.tsx

@@ -1021,9 +1021,6 @@ class ServiceMasterPassword extends ServiceBase {
                       serverPwdHash: pwdHash,
                     },
                   );
-                if (!oldLocalItem) {
-                  return;
-                }
                 if (!oldLocalItem.rawDataJson) {
                   throw new OneKeyLocalError('No raw data json');
                 }

packages/kit-bg/src/services/ServicePrimeCloudSync/ServicePrimeCloudSync.tsx

@@ -93,12 +93,7 @@ import { CloudSyncFlowManagerWallet } from './CloudSyncFlowManager/CloudSyncFlow
 import cloudSyncItemBuilder from './cloudSyncItemBuilder';
 // Keyless backend API is not available yet; use mock storage for Keyless mode.
 import { keylessMockApi } from './keylessCloudSyncMockApi';
-import {
-  buildKeylessSignatureHeader,
-  computeDataHash,
-  deriveKeylessCredential,
-  isKeylessPwdHash,
-} from './keylessCloudSyncUtils';
+import keylessCloudSyncUtils from './keylessCloudSyncUtils';
 
 import type { RealmSchemaCloudSyncItem } from '../../dbs/local/realm/schemas/RealmSchemaCloudSyncItem';
 import type { IPrimeCloudSyncPersistAtomData } from '../../states/jotai/atoms';
@@ -185,11 +180,12 @@ class ServicePrimeCloudSync extends ServiceBase {
     }
 
     try {
-      const keylessCredential = await deriveKeylessCredential({
-        hdCredential: credential.credential,
-        password,
-        keylessWalletId: keylessWallet.id,
-      });
+      const keylessCredential =
+        await keylessCloudSyncUtils.deriveKeylessCredential({
+          hdCredential: credential.credential,
+          password,
+          keylessWalletId: keylessWallet.id,
+        });
 
       this.keylessCredentialCache = keylessCredential;
       return keylessCredential;
@@ -258,12 +254,15 @@ class ServicePrimeCloudSync extends ServiceBase {
       return null;
     }
 
-    const signatureHeader = await buildKeylessSignatureHeader({
-      signingPrivateKey: keylessCredential.signingPrivateKey,
-      signingPublicKey: keylessCredential.signingPublicKey,
-      password,
-      dataHash: computeDataHash(stringUtils.stableStringify(postData)),
-    });
+    const signatureHeader =
+      await keylessCloudSyncUtils.buildKeylessSignatureHeader({
+        signingPrivateKey: keylessCredential.signingPrivateKey,
+        signingPublicKey: keylessCredential.signingPublicKey,
+        password,
+        dataHash: keylessCloudSyncUtils.computeDataHash(
+          stringUtils.stableStringify(postData),
+        ),
+      });
     return {
       publicKey: keylessCredential.signingPublicKey,
       signatureHeader,
@@ -2336,7 +2335,7 @@ class ServicePrimeCloudSync extends ServiceBase {
     // Skip Lock items with keyless pwdHash
     if (
       localItem.dataType === EPrimeCloudSyncDataType.Lock &&
-      isKeylessPwdHash(localItem.pwdHash)
+      keylessCloudSyncUtils.isKeylessPwdHash(localItem.pwdHash)
     ) {
       return null;
     }
@@ -2361,13 +2360,13 @@ class ServicePrimeCloudSync extends ServiceBase {
     shouldDecrypt?: boolean; // decrypt the data to rawDataJson
     syncCredential: ICloudSyncCredential | undefined;
     serverPwdHash: string;
-  }): Promise<IDBCloudSyncItem | null> {
+  }): Promise<IDBCloudSyncItem> {
     // Skip Lock items with keyless pwdHash
     if (
       serverItem.dataType === EPrimeCloudSyncDataType.Lock &&
-      isKeylessPwdHash(serverItem.pwdHash)
+      keylessCloudSyncUtils.isKeylessPwdHash(serverItem.pwdHash)
     ) {
-      return null;
+      throw new OneKeyError('Lock item not support for keyless mode');
     }
     const localItem: IDBCloudSyncItem = {
       id: serverItem.key,

packages/kit-bg/src/services/ServicePrimeCloudSync/cloudSyncItemBuilder.ts

@@ -24,11 +24,7 @@ import type {
   ICloudSyncRawDataJson,
 } from '@onekeyhq/shared/types/prime/primeCloudSyncTypes';
 
-import {
-  decryptWithKeylessKey,
-  encryptWithKeylessKey,
-  isKeylessPwdHash,
-} from './keylessCloudSyncUtils';
+import keylessCloudSyncUtils from './keylessCloudSyncUtils';
 
 import type {
   IDBCloudSyncItem,
@@ -50,7 +46,7 @@ class CloudSyncItemBuilder {
     const { keylessCredential } = syncCredential;
     if (keylessCredential) {
       // pwdHash is precomputed in deriveKeylessCredential
-      return keylessCredential.pwdHash;
+      return keylessCredential.pwdHash || '';
     }
 
     // Fallback to OneKey ID mode
@@ -213,7 +209,7 @@ class CloudSyncItemBuilder {
       const { keylessCredential } = syncCredential;
       // Use keyless encryption if keylessCredential is available
       if (keylessCredential) {
-        encryptedData = await encryptWithKeylessKey({
+        encryptedData = await keylessCloudSyncUtils.encryptWithKeylessKey({
           rawData,
           encryptionKey: keylessCredential.encryptionKey,
         });
@@ -251,20 +247,25 @@ class CloudSyncItemBuilder {
 
     if (syncCredential && item.data) {
       let decryptedData: string | undefined;
+      const credentialPwdHash: string | undefined =
+        this.getPwdHash(syncCredential);
 
       // Determine decryption method based on pwdHash prefix
-      if (isKeylessPwdHash(item.pwdHash) && syncCredential.keylessCredential) {
+      if (
+        keylessCloudSyncUtils.isKeylessPwdHash(item.pwdHash) &&
+        syncCredential.keylessCredential
+      ) {
         // Keyless decryption
         try {
-          decryptedData = await decryptWithKeylessKey({
+          decryptedData = await keylessCloudSyncUtils.decryptWithKeylessKey({
             encryptedData: item.data,
             encryptionKey: syncCredential.keylessCredential.encryptionKey,
           });
         } catch (error) {
           console.error('decryptSyncItem keyless decrypt error', error, item);
           throw new IncorrectMasterPassword();
         }
-      } else if (!isKeylessPwdHash(item.pwdHash)) {
+      } else if (!keylessCloudSyncUtils.isKeylessPwdHash(item.pwdHash)) {
         // OneKey ID decryption
         let credentialToUse = syncCredential;
         if (item.dataType === EPrimeCloudSyncDataType.Lock) {
@@ -296,7 +297,9 @@ class CloudSyncItemBuilder {
 
       try {
         if (decryptedData) {
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-return
           rawDataJson = JSON.parse(decryptedData) as ICloudSyncRawDataJson;
+          item.pwdHash = credentialPwdHash || '';
         }
       } catch (error) {
         console.error('decryptSyncItem jsonParse error', error, item);

packages/kit-bg/src/services/ServicePrimeCloudSync/keylessCloudSyncUtils.ts

@@ -5,9 +5,6 @@
  * Uses the unique Keyless wallet mnemonic to derive keys for operations.
  */
 
-import { sha256 } from '@noble/hashes/sha256';
-import { sha512 } from '@noble/hashes/sha512';
-
 import {
   batchGetPrivateKeys,
   decryptStringAsync,
@@ -27,7 +24,9 @@ import {
   KEYLESS_SYNC_ENCRYPTION_CONTEXT,
 } from '@onekeyhq/shared/src/consts/keylessCloudSyncConsts';
 import { OneKeyLocalError } from '@onekeyhq/shared/src/errors';
+import appCrypto from '@onekeyhq/shared/src/appCrypto';
 import bufferUtils from '@onekeyhq/shared/src/utils/bufferUtils';
+import stringUtils from '@onekeyhq/shared/src/utils/stringUtils';
 import type {
   IKeylessCloudSyncCredential,
   IKeylessCloudSyncSignMessage,
@@ -42,10 +41,12 @@ import type {
  * @param encryptionKey - Keyless encryption key (hex string)
  * @returns pwdHash string with 'keyless-' prefix
  */
-export function computeKeylessPwdHash(encryptionKey: string): string {
+function computeKeylessPwdHash(encryptionKey: string): string {
   const context: string = KEYLESS_PWDHASH_CONTEXT;
   const hashInput = `${context}:${encryptionKey}`;
-  const hash = sha512(bufferUtils.toBuffer(hashInput, 'utf8'));
+  const hash = appCrypto.hash.sha512Sync(
+    bufferUtils.toBuffer(hashInput, 'utf8'),
+  );
   const prefix: string = KEYLESS_PWDHASH_PREFIX;
   return `${prefix}${bufferUtils.bytesToHex(hash)}`;
 }
@@ -56,7 +57,7 @@ export function computeKeylessPwdHash(encryptionKey: string): string {
  * @param pwdHash - pwdHash string to check
  * @returns true if pwdHash starts with 'keyless-' prefix
  */
-export function isKeylessPwdHash(pwdHash: string): boolean {
+function isKeylessPwdHash(pwdHash: string): boolean {
   return pwdHash.startsWith(KEYLESS_PWDHASH_PREFIX);
 }
 
@@ -68,7 +69,7 @@ export function isKeylessPwdHash(pwdHash: string): boolean {
  * @param keylessWalletId - Keyless wallet ID
  * @returns Keyless sync credentials containing signing and encryption keys
  */
-export async function deriveKeylessCredential({
+async function deriveKeylessCredential({
   hdCredential,
   password,
   keylessWalletId,
@@ -83,7 +84,7 @@ export async function deriveKeylessCredential({
     'secp256k1',
     hdCredential,
     password,
-    KEYLESS_SYNC_DERIVATION_PATH_PREFIX, // "m/44'/1919'/0'"
+    KEYLESS_SYNC_DERIVATION_PATH_PREFIX, // "m/44'/38716591'/98351420'"
     ['0/0', '0/1'],
   );
 
@@ -132,7 +133,7 @@ export async function deriveKeylessCredential({
  * @param encryptionKey - Encryption key (hex)
  * @returns Encrypted data (hex string)
  */
-export async function encryptWithKeylessKey({
+async function encryptWithKeylessKey({
   rawData,
   encryptionKey,
 }: {
@@ -156,7 +157,7 @@ export async function encryptWithKeylessKey({
  * @param encryptionKey - Encryption key (hex)
  * @returns Decrypted raw data (UTF8 string)
  */
-export async function decryptWithKeylessKey({
+async function decryptWithKeylessKey({
   encryptedData,
   encryptionKey,
 }: {
@@ -198,7 +199,7 @@ function generateNonce(): string {
  * @param dataHash - Data hash to include when uploading (optional)
  * @returns Base64 encoded signature Header value
  */
-export async function buildKeylessSignatureHeader({
+async function buildKeylessSignatureHeader({
   signingPrivateKey,
   signingPublicKey,
   password,
@@ -220,8 +221,11 @@ export async function buildKeylessSignatureHeader({
   };
 
   // Compute message hash
-  const messageString = JSON.stringify(signMessage);
-  const messageHash = sha256(bufferUtils.toBuffer(messageString, 'utf8'));
+  // Use stableStringify to ensure consistent serialization regardless of property order
+  const messageString = stringUtils.stableStringify(signMessage);
+  const messageHash = appCrypto.hash.sha256Sync(
+    bufferUtils.toBuffer(messageString, 'utf8'),
+  );
 
   // Encrypt private key before signing (sign function expects encrypted key)
   const encryptedPrivateKey = await encryptAsync({
@@ -247,7 +251,7 @@ export async function buildKeylessSignatureHeader({
 
   // Base64 encode
   return bufferUtils.bytesToBase64(
-    bufferUtils.toBuffer(JSON.stringify(headerPayload), 'utf8'),
+    bufferUtils.toBuffer(stringUtils.stableStringify(headerPayload), 'utf8'),
   );
 }
 
@@ -257,8 +261,8 @@ export async function buildKeylessSignatureHeader({
  * @param data - Data to hash
  * @returns Hash value (hex string)
  */
-export function computeDataHash(data: string): string {
-  const hash = sha256(bufferUtils.toBuffer(data, 'utf8'));
+function computeDataHash(data: string): string {
+  const hash = appCrypto.hash.sha256Sync(bufferUtils.toBuffer(data, 'utf8'));
   return bufferUtils.bytesToHex(hash);
 }
 
@@ -268,7 +272,7 @@ export function computeDataHash(data: string): string {
  * @param signatureHeader - Base64 encoded signature Header
  * @returns Parsed signature payload
  */
-export function parseSignatureHeader(
+function parseSignatureHeader(
   signatureHeader: string,
 ): IKeylessCloudSyncSignaturePayload | null {
   try {
@@ -280,3 +284,14 @@ export function parseSignatureHeader(
     return null;
   }
 }
+
+export default {
+  computeKeylessPwdHash,
+  isKeylessPwdHash,
+  deriveKeylessCredential,
+  encryptWithKeylessKey,
+  decryptWithKeylessKey,
+  buildKeylessSignatureHeader,
+  computeDataHash,
+  parseSignatureHeader,
+};

packages/shared/src/consts/keylessCloudSyncConsts.ts

@@ -1,17 +1,19 @@
 /**
  * Keyless Cloud Sync Constants
  *
- * Keyless-specific derivation paths (BIP44 coin type 1919 = OneKey custom)
+ * Keyless-specific derivation paths
  */
 
 /** Keyless sync derivation path prefix */
-export const KEYLESS_SYNC_DERIVATION_PATH_PREFIX = "m/44'/1919'/0'";
+export const KEYLESS_SYNC_DERIVATION_PATH_PREFIX = "m/44'/38716591'/98351420'";
 
 /** Keyless signing key derivation path */
-export const KEYLESS_SYNC_DERIVATION_PATH_SIGNING = "m/44'/1919'/0'/0/0";
+export const KEYLESS_SYNC_DERIVATION_PATH_SIGNING =
+  "m/44'/38716591'/98351420'/0/0";
 
 /** Keyless encryption key derivation path */
-export const KEYLESS_SYNC_DERIVATION_PATH_ENCRYPTION = "m/44'/1919'/0'/0/1";
+export const KEYLESS_SYNC_DERIVATION_PATH_ENCRYPTION =
+  "m/44'/38716591'/98351420'/0/1";
 
 /** HTTP Header name for Keyless signature */
 export const KEYLESS_SYNC_SIGNATURE_HEADER = 'X-Keyless-Sync-Signature';