most-box 0.1.9 → 0.2.0

package/server/src/index.js

@@ -17,9 +17,41 @@ import crypto from 'node:crypto'
 import fs from 'node:fs'
 import path from 'node:path'
 
-import { calculateCid, parseMostLink } from './core/cid.js'
+import { calculateCid, parseMostLink, buildMostLink } from './core/cid.js'
 import { normalizeChannelAttachment } from './core/channelAttachment.js'
 import { getCidInfo } from './core/cidTopic.js'
+import {
+  CHAT_FILE_ROOT,
+  TRANSIENT_CHANNEL_TYPES,
+  CHANNEL_DISCOVERY_TIMEOUT,
+  CHANNEL_CANDIDATE_TTL,
+  normalizeChannelDisplayName,
+  normalizeChannelAvatar,
+  normalizeChannelId,
+  createChannelFingerprint,
+  createChannelWriterId,
+  buildChannelKey,
+  normalizeChannelKey,
+  getChannelFingerprintFromKey,
+  uniqueStrings,
+} from './core/channelIdentity.js'
+import { getPathBaseName, getDisplayPathFolder } from './core/displayPath.js'
+import {
+  normalizeOwnerAddress,
+  getOwnerBucketKey,
+  normalizeMetadataBuckets,
+  cloneMetadataRecord,
+} from './core/ownerMetadata.js'
+import {
+  USER_SYNC_SCHEMA_VERSION,
+  USER_SYNC_NAMESPACE_PREFIX,
+  normalizeUserSyncKey,
+  deriveUserSyncId,
+  getUserSyncName,
+  getSyncTimestamp,
+  getNextSyncTimestamp,
+} from './core/userSyncKeys.js'
+import { createOfflineSwarm } from './node/offlineSwarm.js'
 import {
   sanitizeFilename,
   validateAndSanitizePath,
@@ -66,90 +98,6 @@ import {
 } from './config.js'
 
 const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
-const CHAT_FILE_ROOT = 'chat-file'
-const TRANSIENT_CHANNEL_TYPES = new Set(['game'])
-const DEFAULT_OWNER_BUCKET = '__local__'
-const USER_DATA_SCHEMA_VERSION = 1
-const IMPORT_CHECK_TTL_MS = 10 * 60 * 1000
-const IMPORT_CHECK_MAX_FILES = 5000
-
-function normalizeOwnerAddress(address) {
-  const value = String(address || '').trim()
-  return /^0x[a-fA-F0-9]{40}$/.test(value) ? value.toLowerCase() : ''
-}
-
-function getOwnerBucketKey(address) {
-  return normalizeOwnerAddress(address) || DEFAULT_OWNER_BUCKET
-}
-
-function normalizeMetadataBuckets(input) {
-  if (!input || typeof input !== 'object' || Array.isArray(input)) {
-    return {}
-  }
-  const buckets = {}
-  for (const [rawOwner, records] of Object.entries(input)) {
-    const ownerKey =
-      rawOwner === DEFAULT_OWNER_BUCKET
-        ? DEFAULT_OWNER_BUCKET
-        : normalizeOwnerAddress(rawOwner)
-    if (!ownerKey || !Array.isArray(records)) continue
-    buckets[ownerKey] = records.map(record => ({ ...record }))
-  }
-  return buckets
-}
-
-function cloneMetadataRecord(record, ownerAddress = '') {
-  return {
-    ...record,
-    ownerAddress:
-      ownerAddress && ownerAddress !== DEFAULT_OWNER_BUCKET ? ownerAddress : '',
-  }
-}
-
-function getPathBaseName(fileName) {
-  const parts = String(fileName || '').split('/').filter(Boolean)
-  return parts[parts.length - 1] || 'unnamed_file'
-}
-
-function getDisplayPathFolder(fileName) {
-  const parts = String(fileName || '').split('/').filter(Boolean)
-  parts.pop()
-  return parts.join('/')
-}
-
-function buildMostLink(cid, fileName) {
-  return `most://${cid}?filename=${encodeURIComponent(fileName)}`
-}
-
-function normalizeChannelDisplayName(input, fallbackAddress = '') {
-  const value = String(input || '').trim()
-  if (value) return value.slice(0, 50)
-  return fallbackAddress ? fallbackAddress.slice(0, 10) : ''
-}
-
-function normalizeChannelAvatar(input) {
-  const value = String(input || '').trim()
-  return value ? value.slice(0, 4096) : ''
-}
-
-function createOfflineSwarm() {
-  return {
-    connections: new Set(),
-    keyPair: {
-      publicKey: crypto.randomBytes(32),
-    },
-    on() {},
-    join() {
-      return {}
-    },
-    leave() {
-      return Promise.resolve()
-    },
-    destroy() {
-      return Promise.resolve()
-    },
-  }
-}
 
 export class MostBoxEngine extends EventEmitter {
   #store = null
@@ -161,7 +109,6 @@ export class MostBoxEngine extends EventEmitter {
   #initialized = false
   #options = null
   #activeDownloads = new Map()
-  #importChecks = new Map()
   #drivePromises = new Map()
   #fileDiscoveries = new Map()
   #fileMonitors = new Map()
@@ -173,7 +120,15 @@ export class MostBoxEngine extends EventEmitter {
   #channelLocalCoreKey = new Map()
   #channelDiscoveries = new Map()
   #channelChatDiscoveries = new Map()
+  #channelIdDiscoveries = new Map()
   #channelPeers = new Map()
+  #channelCandidateCache = new Map()
+
+  #userSyncSessions = new Map()
+  #userSyncCores = new Map()
+  #userSyncCoreOffsets = new Map()
+  #userSyncDiscoveries = new Map()
+  #userSyncMetadata = { sessions: {}, clocks: {} }
 
   #chatSwarm = null
 
@@ -360,52 +315,19 @@ export class MostBoxEngine extends EventEmitter {
 
     for (const channel of this.#channels) {
       try {
-        const ns = this.#store.namespace(`channel-${channel.name}`)
-        const core = ns.get({
-          key: b4a.from(channel.coreKey, 'hex'),
-          valueEncoding: 'json',
-        })
-        await core.ready()
-        const coreKeyHex = b4a.toString(core.key, 'hex')
-        if (!this.#channelCores.has(channel.name)) {
-          this.#channelCores.set(channel.name, new Map())
-        }
-        this.#channelCores.get(channel.name).set(coreKeyHex, core)
-        this.#channelLocalCoreKey.set(channel.name, coreKeyHex)
-        this.#channelPeers.set(channel.name, new Map())
-        this.#setupChannelAppendListener(core, channel.name)
-        const remoteCoreKeys = Array.isArray(channel.remoteCoreKeys)
-          ? channel.remoteCoreKeys
-          : []
-        for (const remoteCoreKey of remoteCoreKeys) {
-          if (remoteCoreKey && remoteCoreKey !== coreKeyHex) {
-            await this.#openRemoteChannelCore(channel.name, remoteCoreKey)
-          }
-        }
-
-        const discoveryKey = b4a.from(channel.discoveryKey, 'hex')
-        const chatDiscoveryKey = this.#generateChannelChatDiscoveryKey(
-          channel.name
-        )
-        const appDiscovery = this.#swarm.join(discoveryKey, {
-          server: true,
-          client: true,
-        })
-        this.#channelDiscoveries.set(channel.name, appDiscovery)
-        const chatDiscovery = this.#chatSwarm.join(chatDiscoveryKey, {
-          server: true,
-          client: true,
-        })
-        this.#channelChatDiscoveries.set(channel.name, chatDiscovery)
-        console.log(`[MostBox] Rejoined channel: ${channel.name}`)
+        await this.#openChannelRuntime(channel)
+        await this.#joinChannelDiscoveryTopics(channel)
+        console.log(`[MostBox] Rejoined channel: ${channel.channelKey}`)
       } catch (err) {
         console.warn(
-          `[MostBox] Failed to rejoin channel ${channel.name}:`,
+          `[MostBox] Failed to rejoin channel ${channel.channelKey}:`,
           err.message
         )
       }
     }
 
+    this.#userSyncMetadata = this.#loadUserSyncMetadata()
+
     this.#initialized = true
     console.log(`[MostBox] Engine initialized successfully`)
     this.emit('ready')
@@ -462,9 +384,24 @@ export class MostBoxEngine extends EventEmitter {
     this.#channelLocalCoreKey.clear()
     this.#channelDiscoveries.clear()
     this.#channelChatDiscoveries.clear()
+    this.#channelIdDiscoveries.clear()
     this.#channelPeers.clear()
+    this.#channelCandidateCache.clear()
     this.#channels = []
-    this.#importChecks.clear()
+
+    for (const [, coresMap] of this.#userSyncCores) {
+      for (const [, core] of coresMap) {
+        try {
+          await core.close()
+        } catch (err) {
+          console.warn('[MostBox] Failed to close user sync core:', err.message)
+        }
+      }
+    }
+    this.#userSyncSessions.clear()
+    this.#userSyncCores.clear()
+    this.#userSyncCoreOffsets.clear()
+    this.#userSyncDiscoveries.clear()
 
     if (this.#store) {
       await this.#store.close()
@@ -644,13 +581,18 @@ export class MostBoxEngine extends EventEmitter {
     }
 
     // 存储 displayName（用户看到的文件夹路径），不存储 drivePath
-    publishedBucket.push({
+    const now = Date.now()
+    const fileRecord = {
       fileName: safeFileName,
       cid: cidString,
       driveName: name,
-      publishedAt: new Date().toISOString(),
+      size: fileSize,
+      source: 'published',
+      publishedAt: new Date(now).toISOString(),
       starred: false,
-    })
+      syncUpdatedAt: now,
+    }
+    publishedBucket.push(fileRecord)
     this.#savePublishedMetadata()
     this.#upsertHolding({
       cid: cidString,
@@ -667,6 +609,9 @@ export class MostBoxEngine extends EventEmitter {
     }
 
     this.emit('publish:success', result)
+    this.#appendUserSyncOpSoon(ownerAddress, 'file:upsert', {
+      file: this.#formatFileForSync(fileRecord, 'active'),
+    })
     return result
   }
 
@@ -697,8 +642,12 @@ export class MostBoxEngine extends EventEmitter {
 
     try {
       const parsed = parseMostLink(link)
-      if (parsed.error) {
-        throw new ValidationError(parsed.error)
+      if (parsed.errorCode) {
+        throw new ValidationError(
+          parsed.errorCode,
+          parsed.errorCode,
+          parsed.details
+        )
       }
       const cidString = parsed.cid
       console.log(`[MostBox] Parsed CID: ${cidString}`)
@@ -994,22 +943,32 @@ export class MostBoxEngine extends EventEmitter {
           ownerAddress,
           excludeCid: cidString,
         })
+        const savedSize = totalBytes || fs.statSync(savePath).size
+        const syncUpdatedAt =
+          existingIndex !== -1
+            ? getNextSyncTimestamp(publishedBucket[existingIndex].syncUpdatedAt)
+            : Date.now()
         if (existingIndex !== -1) {
           const existing = publishedBucket[existingIndex]
           existing.fileName = sanitizedFileName
           existing.driveName = name
-          existing.publishedAt = new Date().toISOString()
+          existing.size = savedSize
+          existing.source = 'downloaded'
+          existing.publishedAt = new Date(syncUpdatedAt).toISOString()
+          existing.syncUpdatedAt = syncUpdatedAt
         } else {
           publishedBucket.push({
             fileName: sanitizedFileName,
             cid: cidString,
             driveName: name,
-            publishedAt: new Date().toISOString(),
+            size: savedSize,
+            source: 'downloaded',
+            publishedAt: new Date(syncUpdatedAt).toISOString(),
             starred: false,
+            syncUpdatedAt,
           })
         }
         this.#savePublishedMetadata()
-        const savedSize = totalBytes || fs.statSync(savePath).size
         this.#upsertHolding({
           cid: cidString,
           fileName: sanitizedFileName,
@@ -1019,6 +978,10 @@ export class MostBoxEngine extends EventEmitter {
         })
 
         this.emit('download:success', result)
+        const syncedFile = publishedBucket.find(file => file.cid === cidString)
+        this.#appendUserSyncOpSoon(ownerAddress, 'file:upsert', {
+          file: this.#formatFileForSync(syncedFile, 'active'),
+        })
         return result
       }
     } finally {
@@ -1033,8 +996,12 @@ export class MostBoxEngine extends EventEmitter {
     this.#ensureInitialized()
     const ownerAddress = normalizeOwnerAddress(options.ownerAddress)
     const parsed = parseMostLink(link)
-    if (parsed.error) {
-      throw new ValidationError(parsed.error)
+    if (parsed.errorCode) {
+      throw new ValidationError(
+        parsed.errorCode,
+        parsed.errorCode,
+        parsed.details
+      )
     }
 
     const localContent = await this.#getLocalCidContent(parsed.cid, {
@@ -1068,8 +1035,12 @@ export class MostBoxEngine extends EventEmitter {
 
     const timeout = options.timeout || DRIVE_ENTRY_TIMEOUT
     const parsed = parseMostLink(link)
-    if (parsed.error) {
-      throw new ValidationError(parsed.error)
+    if (parsed.errorCode) {
+      throw new ValidationError(
+        parsed.errorCode,
+        parsed.errorCode,
+        parsed.details
+      )
     }
 
     const cidString = parsed.cid
@@ -1155,8 +1126,14 @@ export class MostBoxEngine extends EventEmitter {
       cid: f.cid,
       link: `most://${f.cid}?filename=${encodeURIComponent(f.fileName)}`,
       publishedAt: f.publishedAt,
+      size: Number(f.size) || 0,
       starred: f.starred || false,
       ownerAddress: ownerAddress || '',
+      localAvailable: this.#holdings.some(holding => holding.cid === f.cid),
+      seedStatus: this.#seedStates.get(f.cid)?.status || '',
+      holdingSize:
+        Number(this.#holdings.find(holding => holding.cid === f.cid)?.size) ||
+        0,
     }))
   }
 
@@ -1174,7 +1151,11 @@ export class MostBoxEngine extends EventEmitter {
       throw new Error('File not found')
     }
     files[index].starred = !files[index].starred
+    files[index].syncUpdatedAt = getNextSyncTimestamp(files[index].syncUpdatedAt)
     this.#savePublishedMetadata()
+    this.#appendUserSyncOpSoon(ownerAddress, 'file:upsert', {
+      file: this.#formatFileForSync(files[index], 'active'),
+    })
     return {
       cid,
       starred: files[index].starred,
@@ -1195,8 +1176,9 @@ export class MostBoxEngine extends EventEmitter {
     if (index !== -1) {
       const fileRecord = files[index]
       const holding = this.#holdings.find(item => item.cid === fileRecord.cid)
+      const syncUpdatedAt = getNextSyncTimestamp(fileRecord.syncUpdatedAt)
 
-      trashFiles.push({
+      const trashRecord = {
         fileName: fileRecord.fileName,
         cid: fileRecord.cid,
         driveName:
@@ -1205,13 +1187,18 @@ export class MostBoxEngine extends EventEmitter {
         source: holding?.source || 'published',
         publishedAt: fileRecord.publishedAt,
         starred: fileRecord.starred || false,
-        deletedAt: new Date().toISOString(),
-      })
+        deletedAt: new Date(syncUpdatedAt).toISOString(),
+        syncUpdatedAt,
+      }
+      trashFiles.push(trashRecord)
       this.#saveTrashMetadata()
 
       files.splice(index, 1)
       this.#setPublishedBucket(ownerAddress, files)
       this.#savePublishedMetadata()
+      this.#appendUserSyncOpSoon(ownerAddress, 'file:trash', {
+        file: this.#formatFileForSync(trashRecord, 'trash'),
+      })
 
       if (!this.#hasPublishedReference(fileRecord.cid)) {
         await this.#leaveCidTopic(fileRecord.cid)
@@ -1237,9 +1224,15 @@ export class MostBoxEngine extends EventEmitter {
       cid: f.cid,
       link: `most://${f.cid}?filename=${encodeURIComponent(f.fileName)}`,
       publishedAt: f.publishedAt,
+      size: Number(f.size) || 0,
       starred: f.starred || false,
       ownerAddress: ownerAddress || '',
       deletedAt: f.deletedAt,
+      localAvailable: this.#holdings.some(holding => holding.cid === f.cid),
+      seedStatus: this.#seedStates.get(f.cid)?.status || '',
+      holdingSize:
+        Number(this.#holdings.find(holding => holding.cid === f.cid)?.size) ||
+        0,
     }))
   }
 
@@ -1269,6 +1262,9 @@ export class MostBoxEngine extends EventEmitter {
       trashFiles.splice(index, 1)
       this.#setTrashBucket(ownerAddress, trashFiles)
       this.#saveTrashMetadata()
+      this.#appendUserSyncOpSoon(ownerAddress, 'file:upsert', {
+        file: this.#formatFileForSync(publishedFiles[existingIndex], 'active'),
+      })
       return this.listPublishedFiles({ ownerAddress })
     }
 
@@ -1277,29 +1273,43 @@ export class MostBoxEngine extends EventEmitter {
       excludeCid: fileRecord.cid,
     })
 
-    publishedFiles.push({
+    const syncUpdatedAt = getNextSyncTimestamp(fileRecord.syncUpdatedAt)
+    const publishedRecord = {
       fileName: fileRecord.fileName,
       cid: fileRecord.cid,
       driveName,
       publishedAt: fileRecord.publishedAt,
       starred: fileRecord.starred || false,
-    })
+      size: Number(fileRecord.size) || 0,
+      source: fileRecord.source || 'synced',
+      syncUpdatedAt,
+    }
+    publishedFiles.push(publishedRecord)
     this.#savePublishedMetadata()
 
     trashFiles.splice(index, 1)
     this.#setTrashBucket(ownerAddress, trashFiles)
     this.#saveTrashMetadata()
 
-    await this.#joinCidTopicInternal(fileRecord.cid, {
-      server: true,
-      client: false,
+    const localContent = await this.#getLocalCidContent(fileRecord.cid, {
+      ownerAddress,
+      allowHoldingFallback: true,
     })
-    this.#upsertHolding({
-      cid: fileRecord.cid,
-      fileName: fileRecord.fileName,
-      size: Number(fileRecord.size) || 0,
-      driveName,
-      source: fileRecord.source || 'published',
+    if (localContent) {
+      await this.#joinCidTopicInternal(fileRecord.cid, {
+        server: true,
+        client: false,
+      })
+      this.#upsertHolding({
+        cid: fileRecord.cid,
+        fileName: fileRecord.fileName,
+        size: localContent.size || Number(fileRecord.size) || 0,
+        driveName,
+        source: fileRecord.source || 'published',
+      })
+    }
+    this.#appendUserSyncOpSoon(ownerAddress, 'file:upsert', {
+      file: this.#formatFileForSync(publishedRecord, 'active'),
     })
 
     return this.listPublishedFiles({ ownerAddress })
@@ -1323,6 +1333,10 @@ export class MostBoxEngine extends EventEmitter {
       trashFiles.splice(index, 1)
       this.#setTrashBucket(ownerAddress, trashFiles)
       this.#saveTrashMetadata()
+      this.#appendUserSyncOpSoon(ownerAddress, 'file:delete', {
+        cid: fileRecord.cid,
+        syncUpdatedAt: getNextSyncTimestamp(fileRecord.syncUpdatedAt),
+      })
 
       if (!this.#hasAnyUserReference(fileRecord.cid)) {
         try {
@@ -1349,8 +1363,11 @@ export class MostBoxEngine extends EventEmitter {
     const removedTrash = [...this.#getTrashBucket(ownerAddress)]
     this.#setTrashBucket(ownerAddress, [])
     this.#saveTrashMetadata()
-
     for (const fileRecord of removedTrash) {
+      this.#appendUserSyncOpSoon(ownerAddress, 'file:delete', {
+        cid: fileRecord.cid,
+        syncUpdatedAt: getNextSyncTimestamp(fileRecord.syncUpdatedAt),
+      })
       if (this.#hasAnyUserReference(fileRecord.cid)) continue
       const driveName =
         fileRecord.driveName || this.#getCidInfo(fileRecord.cid).driveName
@@ -1455,8 +1472,12 @@ export class MostBoxEngine extends EventEmitter {
       excludeCid: cid,
     })
     files[index].fileName = safeFileName
-    files[index].publishedAt = new Date().toISOString()
+    files[index].syncUpdatedAt = getNextSyncTimestamp(files[index].syncUpdatedAt)
+    files[index].publishedAt = new Date(files[index].syncUpdatedAt).toISOString()
     this.#savePublishedMetadata()
+    this.#appendUserSyncOpSoon(ownerAddress, 'file:upsert', {
+      file: this.#formatFileForSync(files[index], 'active'),
+    })
     return {
       cid,
       fileName: safeFileName,
@@ -1497,7 +1518,8 @@ export class MostBoxEngine extends EventEmitter {
 
     const updatedFiles = updates.map(({ file, newFileName }) => {
       file.fileName = newFileName
-      file.publishedAt = new Date().toISOString()
+      file.syncUpdatedAt = getNextSyncTimestamp(file.syncUpdatedAt)
+      file.publishedAt = new Date(file.syncUpdatedAt).toISOString()
       return {
         cid: file.cid,
         fileName: file.fileName,
@@ -1507,6 +1529,11 @@ export class MostBoxEngine extends EventEmitter {
 
     if (updatedFiles.length > 0) {
       this.#savePublishedMetadata()
+      for (const { file } of updates) {
+        this.#appendUserSyncOpSoon(ownerAddress, 'file:upsert', {
+          file: this.#formatFileForSync(file, 'active'),
+        })
+      }
     }
 
     return { files: updatedFiles }
@@ -1606,253 +1633,6 @@ export class MostBoxEngine extends EventEmitter {
     }
   }
 
-  exportUserMetadata(ownerAddressInput) {
-    this.#ensureInitialized()
-    const ownerAddress = normalizeOwnerAddress(ownerAddressInput)
-    if (!ownerAddress) {
-      throw new ValidationError('valid owner address is required')
-    }
-
-    const files = this.#getPublishedBucket(ownerAddress).map(file => ({
-      fileName: file.fileName,
-      cid: file.cid,
-      driveName: file.driveName || this.#getCidInfo(file.cid).driveName,
-      publishedAt: file.publishedAt,
-      starred: file.starred || false,
-      link: buildMostLink(file.cid, file.fileName),
-    }))
-    const trashFiles = this.#getTrashBucket(ownerAddress).map(file => ({
-      fileName: file.fileName,
-      cid: file.cid,
-      driveName: file.driveName || this.#getCidInfo(file.cid).driveName,
-      size: Number(file.size) || 0,
-      source: file.source || 'published',
-      publishedAt: file.publishedAt,
-      starred: file.starred || false,
-      deletedAt: file.deletedAt,
-      link: buildMostLink(file.cid, file.fileName),
-    }))
-    const channels = this.#channels
-      .filter(channel => this.#channelHasMember(channel, ownerAddress))
-      .map(channel => ({
-        name: channel.name,
-        type: channel.type,
-        coreKey: channel.coreKey,
-        createdAt: channel.createdAt,
-        lastMessageAt: channel.lastMessageAt || '',
-        member: this.#getChannelMembers(channel).find(
-          member => member.address === ownerAddress
-        ),
-        remark: channel.remarks?.[ownerAddress] || '',
-        pinned: Boolean(channel.pinnedBy?.[ownerAddress]),
-      }))
-
-    return {
-      schemaVersion: USER_DATA_SCHEMA_VERSION,
-      exportedAt: new Date().toISOString(),
-      ownerAddress,
-      files,
-      trashFiles,
-      channels,
-    }
-  }
-
-  async checkUserImport(input = {}, options = {}) {
-    this.#ensureInitialized()
-    const ownerAddress = normalizeOwnerAddress(options.ownerAddress)
-    if (!ownerAddress) {
-      throw new ValidationError('valid owner address is required')
-    }
-
-    const normalized = this.#normalizeUserImportPackage(input)
-    const failures = []
-    const seenPaths = new Set()
-    const checkedActiveCids = new Set()
-    const importedCids = new Set([
-      ...normalized.files.map(file => file.cid),
-      ...normalized.trashFiles.map(file => file.cid),
-    ])
-    const currentCids = this.#collectUserCids(ownerAddress)
-    let requiredBytes = 0
-
-    if (normalized.files.length > IMPORT_CHECK_MAX_FILES) {
-      failures.push({
-        scope: 'package',
-        error: `too many files: max ${IMPORT_CHECK_MAX_FILES}`,
-      })
-    }
-
-    for (const file of normalized.files) {
-      const pathKey = sanitizeFilename(file.fileName).toLowerCase()
-      if (seenPaths.has(pathKey)) {
-        failures.push({
-          cid: file.cid,
-          fileName: file.fileName,
-          error: 'duplicate file path',
-        })
-        continue
-      }
-      seenPaths.add(pathKey)
-
-      const link = buildMostLink(file.cid, file.fileName)
-      try {
-        const result = await this.checkDownloadAvailability(link, {
-          ownerAddress,
-          timeout: options.timeout || DRIVE_ENTRY_TIMEOUT,
-        })
-        if (!checkedActiveCids.has(file.cid) && !result.alreadyExists) {
-          requiredBytes += Number(result.size) || Number(file.size) || 0
-        }
-        checkedActiveCids.add(file.cid)
-      } catch (err) {
-        failures.push({
-          cid: file.cid,
-          fileName: file.fileName,
-          error: err.message,
-          code: err.code || 'UNAVAILABLE',
-        })
-      }
-    }
-
-    let reclaimableBytes = 0
-    for (const cid of currentCids) {
-      if (importedCids.has(cid)) continue
-      const referencedByOtherUser =
-        this.#allPublishedRecords().some(
-          file => file.cid === cid && file.ownerAddress !== ownerAddress
-        ) ||
-        this.#allTrashRecords().some(
-          file => file.cid === cid && file.ownerAddress !== ownerAddress
-        )
-      if (referencedByOtherUser) continue
-      const holding = this.#holdings.find(item => item.cid === cid)
-      reclaimableBytes += Number(holding?.size) || 0
-    }
-    const availableBytes = Math.max(
-      0,
-      this.#options.capacityBytes - this.#getUsedBytes() + reclaimableBytes
-    )
-    if (requiredBytes > availableBytes) {
-      failures.push({
-        scope: 'capacity',
-        error: 'insufficient capacity',
-        requiredBytes,
-        availableBytes,
-      })
-    }
-
-    const ready = failures.length === 0
-    const checkId = `import_${Date.now()}_${crypto.randomBytes(6).toString('hex')}`
-    if (ready) {
-      this.#importChecks.set(checkId, {
-        ownerAddress,
-        packageHash: this.#hashImportPackage(input),
-        expiresAt: Date.now() + IMPORT_CHECK_TTL_MS,
-      })
-    }
-
-    return {
-      ready,
-      checkId: ready ? checkId : '',
-      failures,
-      currentFileCount: this.#getPublishedBucket(ownerAddress).length,
-      currentTrashCount: this.#getTrashBucket(ownerAddress).length,
-      currentCidCount: currentCids.size,
-      importFileCount: normalized.files.length,
-      importTrashCount: normalized.trashFiles.length,
-      requiredBytes,
-      availableBytes,
-    }
-  }
-
-  async importUserMetadata(input = {}, options = {}) {
-    this.#ensureInitialized()
-    const ownerAddress = normalizeOwnerAddress(options.ownerAddress)
-    if (!ownerAddress) {
-      throw new ValidationError('valid owner address is required')
-    }
-
-    const checkId = String(options.checkId || '').trim()
-    const check = this.#importChecks.get(checkId)
-    if (
-      !check ||
-      check.ownerAddress !== ownerAddress ||
-      check.expiresAt < Date.now() ||
-      check.packageHash !== this.#hashImportPackage(input)
-    ) {
-      throw new ValidationError('valid import check is required')
-    }
-    this.#importChecks.delete(checkId)
-
-    const normalized = this.#normalizeUserImportPackage(input)
-    const previousCids = this.#collectUserCids(ownerAddress)
-    const previous = {
-      removedFiles: this.#getPublishedBucket(ownerAddress).length,
-      removedTrashFiles: this.#getTrashBucket(ownerAddress).length,
-    }
-    const now = new Date().toISOString()
-
-    this.#removeUserFromChannels(ownerAddress)
-    this.#setPublishedBucket(
-      ownerAddress,
-      normalized.files.map(file => ({
-        fileName: file.fileName,
-        cid: file.cid,
-        driveName: file.driveName || this.#getCidInfo(file.cid).driveName,
-        publishedAt: file.publishedAt || now,
-        starred: file.starred || false,
-      }))
-    )
-    this.#setTrashBucket(
-      ownerAddress,
-      normalized.trashFiles.map(file => ({
-        fileName: file.fileName,
-        cid: file.cid,
-        driveName: file.driveName || this.#getCidInfo(file.cid).driveName,
-        size: Number(file.size) || 0,
-        source: file.source || 'imported',
-        publishedAt: file.publishedAt || now,
-        starred: file.starred || false,
-        deletedAt: file.deletedAt || now,
-      }))
-    )
-    this.#applyImportedChannels(ownerAddress, normalized.channels)
-    this.#savePublishedMetadata()
-    this.#saveTrashMetadata()
-    this.#saveChannelsMetadata()
-    previous.removedReplicas = await this.#cleanupUnreferencedCids(previousCids)
-
-    const importedFiles = []
-    const failedFiles = []
-    for (const file of normalized.files) {
-      try {
-        const result = await this.pullByCid({
-          link: buildMostLink(file.cid, file.fileName),
-          ownerAddress,
-          timeout: options.timeout,
-        })
-        importedFiles.push({ cid: file.cid, fileName: file.fileName, result })
-      } catch (err) {
-        failedFiles.push({
-          cid: file.cid,
-          fileName: file.fileName,
-          error: err.message,
-          code: err.code || 'IMPORT_PULL_FAILED',
-        })
-      }
-    }
-
-    return {
-      success: failedFiles.length === 0,
-      ownerAddress,
-      replacedFiles: previous.removedFiles,
-      replacedTrashFiles: previous.removedTrashFiles,
-      importedFiles: importedFiles.length,
-      importedTrashFiles: normalized.trashFiles.length,
-      failedFiles,
-    }
-  }
-
   /**
    * 列出当前节点持有的可做种文件副本
    * @returns {Array}
@@ -1904,8 +1684,12 @@ export class MostBoxEngine extends EventEmitter {
 
     if (input.link) {
       const parsed = parseMostLink(input.link)
-      if (parsed.error) {
-        throw new ValidationError(parsed.error)
+      if (parsed.errorCode) {
+        throw new ValidationError(
+          parsed.errorCode,
+          parsed.errorCode,
+          parsed.details
+        )
       }
       const result = await this.downloadFile(input.link, input.taskId || null, {
         timeout: input.timeout,
@@ -1959,6 +1743,8 @@ export class MostBoxEngine extends EventEmitter {
     left.on('error', () => {})
     right.on('error', () => {})
     left.pipe(right).pipe(left)
+    this.#exchangeUserSyncSessions(peerEngine).catch(() => {})
+    peerEngine.#exchangeUserSyncSessions(this).catch(() => {})
 
     return {
       close: () => {
@@ -1968,6 +1754,108 @@ export class MostBoxEngine extends EventEmitter {
     }
   }
 
+  /**
+   * 启动当前账号的隐藏 user.sync 元数据同步。
+   */
+  async startUserSync(ownerAddressInput, input = {}) {
+    this.#ensureInitialized()
+    const ownerAddress = normalizeOwnerAddress(ownerAddressInput)
+    if (!ownerAddress) {
+      throw new ValidationError('valid owner address is required')
+    }
+
+    const syncTopicKey = normalizeUserSyncKey(input.syncTopicKey)
+    const syncCipherKey = normalizeUserSyncKey(input.syncCipherKey)
+    const syncMacKey = normalizeUserSyncKey(input.syncMacKey)
+    if (!syncTopicKey || !syncCipherKey || !syncMacKey) {
+      throw new ValidationError('valid user sync keys are required')
+    }
+
+    const syncId = deriveUserSyncId(syncTopicKey)
+    const syncName = getUserSyncName(syncId)
+    const persisted = this.#userSyncMetadata.sessions?.[ownerAddress]
+    const session = {
+      ownerAddress,
+      syncId,
+      syncName,
+      syncTopicKey,
+      syncCipherKey,
+      syncMacKey,
+      writerId:
+        persisted?.syncId === syncId && persisted?.writerId
+          ? persisted.writerId
+          : createChannelWriterId(),
+      localWriterCoreKey:
+        persisted?.syncId === syncId ? persisted.localWriterCoreKey || '' : '',
+      writerCoreKeys:
+        persisted?.syncId === syncId
+          ? uniqueStrings(persisted.writerCoreKeys)
+          : [],
+      startedAt: new Date().toISOString(),
+    }
+
+    this.#userSyncSessions.set(ownerAddress, session)
+    await this.#openUserSyncRuntime(session)
+    await this.#joinUserSyncDiscovery(session)
+    this.#persistUserSyncSession(session)
+    await this.#appendUserSyncSnapshot(ownerAddress, 'start')
+
+    return this.getUserSyncStatus(ownerAddress)
+  }
+
+  getUserSyncStatus(ownerAddressInput) {
+    this.#ensureInitialized()
+    const ownerAddress = normalizeOwnerAddress(ownerAddressInput)
+    if (!ownerAddress) {
+      throw new ValidationError('valid owner address is required')
+    }
+    const session = this.#userSyncSessions.get(ownerAddress)
+    if (!session) {
+      const persisted = this.#userSyncMetadata.sessions?.[ownerAddress]
+      return {
+        enabled: false,
+        ownerAddress,
+        syncName: persisted?.syncName || '',
+        syncId: persisted?.syncId || '',
+        peerCount: 0,
+        writerCoreKeys: uniqueStrings(persisted?.writerCoreKeys),
+        localWriterCoreKey: persisted?.localWriterCoreKey || '',
+        lastSyncedAt: persisted?.lastSyncedAt || '',
+      }
+    }
+
+    return {
+      enabled: true,
+      ownerAddress,
+      syncName: session.syncName,
+      syncId: session.syncId,
+      peerCount: this.#chatSwarm?.connections?.size || 0,
+      writerCoreKeys: uniqueStrings(session.writerCoreKeys),
+      localWriterCoreKey: session.localWriterCoreKey,
+      lastSyncedAt:
+        this.#userSyncMetadata.sessions?.[ownerAddress]?.lastSyncedAt || '',
+    }
+  }
+
+  async cacheFile(cid, options = {}) {
+    this.#ensureInitialized()
+    const ownerAddress = normalizeOwnerAddress(options.ownerAddress)
+    const fileRecord = this.#getPublishedBucket(ownerAddress).find(
+      item => item.cid === cid
+    )
+    if (!fileRecord) {
+      throw new Error('File not found')
+    }
+    const result = await this.pullByCid({
+      cid,
+      fileName: fileRecord.fileName,
+      ownerAddress,
+      timeout: options.timeout,
+      taskId: options.taskId,
+    })
+    return result
+  }
+
   /**
    * 读取已发布文件的内容（用于预览）
    * Hyperdrive 中用 CID 作为 key 存储
@@ -2162,277 +2050,286 @@ export class MostBoxEngine extends EventEmitter {
   // --- 频道管理 ---
 
   /**
-   * 创建或加入频道
-   * @param {string} name - 频道名
+   * 创建或加入频道。channelId 是用户输入的短 ID，channelKey 是内部唯一身份。
+   * @param {string} channelIdInput - 用户可见短频道 ID
    * @param {string} [type='personal'] - 频道类型
-   * @returns {Promise<{ name: string, key: string }>}
+   * @returns {Promise<object>}
    */
-  async createChannel(name, type = 'personal', options = {}) {
+  async createChannel(channelIdInput, type = 'personal', options = {}) {
     this.#ensureInitialized()
     const ownerAddress = normalizeOwnerAddress(options.ownerAddress)
+    const channelId = normalizeChannelId(channelIdInput)
     const channelType = String(type || 'personal').trim() || 'personal'
+    const selectedChannelKey = normalizeChannelKey(options.channelKey)
+    const selectedFingerprint = String(options.fingerprint || '').trim()
 
-    if (!CHANNEL_NAME_REGEX.test(name)) {
+    if (channelId.includes('.') && channelType !== 'game') {
+      throw new Error('点号为系统保留，不能用于手动频道 ID')
+    }
+    if (channelType === 'game' && !/^game\.[a-z0-9]+\.[a-z0-9]+$/.test(channelId)) {
+      throw new Error('游戏频道必须使用 game.<gameId>.<roomCode> 格式')
+    }
+    if (channelType !== 'game' && !CHANNEL_NAME_REGEX.test(channelId)) {
       throw new Error('频道名只能包含字母、数字、下划线和连字符')
     }
-    if (name.length < CHANNEL_NAME_MIN_LENGTH) {
+    if (channelId.length < CHANNEL_NAME_MIN_LENGTH) {
       throw new Error(`频道名至少 ${CHANNEL_NAME_MIN_LENGTH} 个字符`)
     }
-    if (name.length > CHANNEL_NAME_MAX_LENGTH) {
+    if (channelId.length > CHANNEL_NAME_MAX_LENGTH) {
       throw new Error(`频道名最多 ${CHANNEL_NAME_MAX_LENGTH} 个字符`)
     }
 
-    const existing = this.#channels.find(c => c.name === name)
-    if (existing) {
-      if (this.#upsertChannelMember(existing, options)) {
-        this.#saveChannelsMetadata()
+    if (selectedChannelKey || selectedFingerprint) {
+      const channelKey =
+        selectedChannelKey || buildChannelKey(channelId, selectedFingerprint)
+      const existing = this.#channels.find(c => c.channelKey === channelKey)
+      if (existing) {
+        await this.#mergeChannelWriterCoreKeys(
+          existing,
+          options.writerCoreKeys
+        )
+        if (this.#upsertChannelMember(existing, options)) {
+          existing.syncUpdatedAt = getNextSyncTimestamp(existing.syncUpdatedAt)
+          this.#saveChannelsMetadata()
+          this.#appendUserSyncChannelUpsertSoon(existing, ownerAddress)
+        }
+        return this.#formatChannelForResponse(existing, ownerAddress)
       }
-      return {
-        name: existing.name,
-        key: existing.coreKey,
-        coreKey: existing.coreKey,
-        createdAt: existing.createdAt,
-        type: existing.type,
+
+      const candidate = this.#getCachedChannelCandidate(channelId, channelKey)
+      if (!candidate) {
+        throw new Error('未发现该频道候选，请重新搜索频道')
       }
+      return this.#joinChannelFromCandidate(candidate, channelType, options)
     }
 
-    const ns = this.#store.namespace(`channel-${name}`)
-    const core = ns.get({ name: 'messages', valueEncoding: 'json' })
-    await core.ready()
+    const localCandidates = this.#getLocalChannelCandidates(channelId)
+    const remoteCandidates = options.discover
+      ? await this.#discoverChannelCandidates(channelId, {
+          timeout: options.discoveryTimeout,
+        })
+      : []
+    const candidates = this.#mergeChannelCandidates([
+      ...localCandidates,
+      ...remoteCandidates,
+    ])
 
-    const discoveryKey = this.#generateChannelDiscoveryKey(name)
-    const chatDiscoveryKey = this.#generateChannelChatDiscoveryKey(name)
-    const appDiscovery = this.#swarm.join(discoveryKey, {
-      server: true,
-      client: true,
-    })
-    const chatDiscovery = this.#chatSwarm.join(chatDiscoveryKey, {
-      server: true,
-      client: true,
-    })
-
-    this.#setupChannelAppendListener(core, name)
+    if (candidates.length > 1) {
+      return {
+        conflict: true,
+        channelId,
+        candidates: candidates.map(candidate =>
+          this.#formatChannelCandidateForResponse(candidate, ownerAddress)
+        ),
+      }
+    }
 
-    const channelInfo = {
-      name,
-      discoveryKey: b4a.toString(discoveryKey, 'hex'),
-      coreKey: b4a.toString(core.key, 'hex'),
-      createdAt: new Date().toISOString(),
-      type: channelType,
-      ownerAddress,
-      members: [],
-      remoteCoreKeys: [],
+    if (candidates.length === 1) {
+      const candidate = candidates[0]
+      if (candidate.local) {
+        const existing = this.#channels.find(
+          channel => channel.channelKey === candidate.channelKey
+        )
+        if (existing && this.#upsertChannelMember(existing, options)) {
+          existing.syncUpdatedAt = getNextSyncTimestamp(existing.syncUpdatedAt)
+          this.#saveChannelsMetadata()
+          this.#appendUserSyncChannelUpsertSoon(existing, ownerAddress)
+        }
+        if (existing) return this.#formatChannelForResponse(existing, ownerAddress)
+        const joined = await this.#joinChannelFromCandidate(
+          candidate,
+          channelType,
+          options
+        )
+        const joinedChannel = this.#resolveChannel(joined.channelKey, ownerAddress)
+        this.#appendUserSyncChannelUpsertSoon(joinedChannel, ownerAddress)
+        return joined
+      }
+      const joined = await this.#joinChannelFromCandidate(
+        candidate,
+        channelType,
+        options
+      )
+      const joinedChannel = this.#resolveChannel(joined.channelKey, ownerAddress)
+      this.#appendUserSyncChannelUpsertSoon(joinedChannel, ownerAddress)
+      return joined
     }
-    this.#upsertChannelMember(channelInfo, options)
 
-    this.#channels.push(channelInfo)
-    const coreKeyHex = b4a.toString(core.key, 'hex')
-    if (!this.#channelCores.has(name)) {
-      this.#channelCores.set(name, new Map())
-    }
-    this.#channelCores.get(name).set(coreKeyHex, core)
-    this.#channelLocalCoreKey.set(name, coreKeyHex)
-    this.#channelPeers.set(name, new Map())
-    this.#channelDiscoveries.set(name, appDiscovery)
-    this.#channelChatDiscoveries.set(name, chatDiscovery)
-    this.#saveChannelsMetadata()
+    const channelInfo = await this.#createLocalChannel(channelId, channelType, {
+      ...options,
+      ownerAddress,
+    })
 
-    console.log(`[MostBox] Channel created: ${name}`)
-    this.emit('channel:joined', { name, key: channelInfo.coreKey })
+    console.log(`[MostBox] Channel created: ${channelInfo.channelKey}`)
+    this.emit('channel:joined', {
+      channel: channelInfo.channelKey,
+      channelKey: channelInfo.channelKey,
+      channelId: channelInfo.channelId,
+      key: channelInfo.channelKey,
+    })
+    this.#appendUserSyncChannelUpsertSoon(channelInfo, ownerAddress)
 
-    return {
-      name,
-      key: channelInfo.coreKey,
-      coreKey: channelInfo.coreKey,
-      createdAt: channelInfo.createdAt,
-      type: channelInfo.type,
-    }
+    return this.#formatChannelForResponse(channelInfo, ownerAddress)
   }
 
   /**
-   * 加入已有频道（通过频道名和 coreKey）
-   * @param {string} name - 频道名
-   * @param {string} [coreKey] - 频道的 coreKey（加入他人创建的频道时必填）
-   * @returns {Promise<{ name: string, key: string }>}
+   * 通过已发现候选加入频道。
+   * @param {string} channelIdInput - 用户可见短频道 ID
+   * @param {object|string|null} candidateInput - 候选对象或 channelKey
+   * @returns {Promise<object>}
    */
-  async joinChannel(name, coreKey = null, options = {}) {
+  async joinChannel(channelIdInput, candidateInput = null, options = {}) {
     this.#ensureInitialized()
-    const ownerAddress = normalizeOwnerAddress(options.ownerAddress)
-
-    const existing = this.#channels.find(c => c.name === name)
+    const channelId = normalizeChannelId(channelIdInput)
+    const candidate =
+      candidateInput && typeof candidateInput === 'object'
+        ? candidateInput
+        : candidateInput
+          ? { channelKey: String(candidateInput), channelId }
+          : null
+
+    if (!candidate?.channelKey && !candidate?.fingerprint) {
+      return this.createChannel(channelId, options.type || 'group', options)
+    }
+
+    const channelKey =
+      normalizeChannelKey(candidate.channelKey) ||
+      buildChannelKey(channelId, String(candidate.fingerprint || '').trim())
+    const existing = this.#channels.find(c => c.channelKey === channelKey)
     if (existing) {
+      await this.#mergeChannelWriterCoreKeys(existing, candidate.writerCoreKeys)
       if (this.#upsertChannelMember(existing, options)) {
+        existing.syncUpdatedAt = getNextSyncTimestamp(existing.syncUpdatedAt)
         this.#saveChannelsMetadata()
+        this.#appendUserSyncChannelUpsertSoon(existing, options.ownerAddress)
       }
-      if (coreKey && coreKey !== existing.coreKey) {
-        if (!Array.isArray(existing.remoteCoreKeys)) {
-          existing.remoteCoreKeys = []
-        }
-        if (!existing.remoteCoreKeys.includes(coreKey)) {
-          existing.remoteCoreKeys.push(coreKey)
-          this.#saveChannelsMetadata()
-        }
-        await this.#openRemoteChannelCore(name, coreKey)
-      }
-      return {
-        name: existing.name,
-        key: existing.coreKey,
-        coreKey: existing.coreKey,
-        createdAt: existing.createdAt,
-        type: existing.type,
-      }
+      return this.#formatChannelForResponse(existing, options.ownerAddress)
     }
 
-    if (!coreKey) {
-      throw new Error('加入已有频道需要提供 coreKey')
-    }
-
-    const ns = this.#store.namespace(`channel-${name}`)
-    const remoteCoreKeyHex = b4a.toString(b4a.from(coreKey, 'hex'), 'hex')
-    const localCore = ns.get({
-      name: `messages-${this.getNodeId()}`,
-      valueEncoding: 'json',
-    })
-    await localCore.ready()
-    const localCoreKeyHex = b4a.toString(localCore.key, 'hex')
-
-    const discoveryKey = this.#generateChannelDiscoveryKey(name)
-    const chatDiscoveryKey = this.#generateChannelChatDiscoveryKey(name)
-    const appDiscovery = this.#swarm.join(discoveryKey, {
-      server: true,
-      client: true,
+    const cached = this.#getCachedChannelCandidate(channelId, channelKey)
+    const joined = await this.#joinChannelFromCandidate(cached || candidate, 'group', {
+      ...options,
+      channelKey,
     })
-    const chatDiscovery = this.#chatSwarm.join(chatDiscoveryKey, {
-      server: true,
-      client: true,
-    })
-
-    this.#setupChannelAppendListener(localCore, name)
-
-    const channelInfo = {
-      name,
-      discoveryKey: b4a.toString(discoveryKey, 'hex'),
-      coreKey: localCoreKeyHex,
-      createdAt: new Date().toISOString(),
-      type: 'group',
-      ownerAddress,
-      members: [],
-      remoteCoreKeys:
-        remoteCoreKeyHex === localCoreKeyHex ? [] : [remoteCoreKeyHex],
-    }
-    this.#upsertChannelMember(channelInfo, options)
-
-    this.#channels.push(channelInfo)
-    if (!this.#channelCores.has(name)) {
-      this.#channelCores.set(name, new Map())
-    }
-    this.#channelCores.get(name).set(localCoreKeyHex, localCore)
-    this.#channelLocalCoreKey.set(name, localCoreKeyHex)
-    this.#channelPeers.set(name, new Map())
-    this.#channelDiscoveries.set(name, appDiscovery)
-    this.#channelChatDiscoveries.set(name, chatDiscovery)
-    this.#saveChannelsMetadata()
-    if (remoteCoreKeyHex !== localCoreKeyHex) {
-      await this.#openRemoteChannelCore(name, remoteCoreKeyHex)
-    }
-
-    console.log(`[MostBox] Joined channel: ${name}`)
-    this.emit('channel:joined', { name, key: localCoreKeyHex })
-
-    return {
-      name,
-      key: localCoreKeyHex,
-      coreKey: localCoreKeyHex,
-      createdAt: channelInfo.createdAt,
-      type: channelInfo.type,
-    }
+    const joinedChannel = this.#resolveChannel(
+      joined.channelKey,
+      options.ownerAddress
+    )
+    this.#appendUserSyncChannelUpsertSoon(joinedChannel, options.ownerAddress)
+    return joined
   }
 
   /**
    * 离开频道
-   * @param {string} name - 频道名
+   * @param {string} channelKeyInput - 内部频道 key，或本地唯一短频道 ID
    * @returns {Promise<string[]>} 剩余频道列表
    */
-  async leaveChannel(name, options = {}) {
+  async leaveChannel(channelKeyInput, options = {}) {
     this.#ensureInitialized()
     const ownerAddress = normalizeOwnerAddress(options.ownerAddress)
 
-    const index = this.#channels.findIndex(c => c.name === name)
+    const channel = this.#resolveChannel(channelKeyInput, ownerAddress)
+    const index = this.#channels.findIndex(c => c.channelKey === channel.channelKey)
     if (index === -1) {
       throw new Error('频道不存在')
     }
 
-    const channel = this.#channels[index]
     if (ownerAddress && Array.isArray(channel.members)) {
       channel.members = channel.members.filter(
         member => normalizeOwnerAddress(member?.address) !== ownerAddress
       )
+      const syncUpdatedAt = getNextSyncTimestamp(channel.syncUpdatedAt)
+      channel.syncUpdatedAt = syncUpdatedAt
+      this.#appendUserSyncChannelLeaveSoon(channel, ownerAddress, syncUpdatedAt)
       if (channel.members.length > 0) {
         this.#saveChannelsMetadata()
         return this.listChannels({ ownerAddress })
       }
     }
 
-    const appDiscovery = this.#channelDiscoveries.get(name)
+    const appDiscovery = this.#channelDiscoveries.get(channel.channelKey)
     if (appDiscovery && this.#swarm) {
-      this.#channelDiscoveries.delete(name)
-      this.#swarm.leave(b4a.from(channel.discoveryKey, 'hex')).catch(err => {
+      this.#channelDiscoveries.delete(channel.channelKey)
+      this.#swarm.leave(this.#generateChannelDiscoveryKey(channel.channelKey)).catch(err => {
         console.warn(
-          `[MostBox] Failed to leave app swarm for ${name}:`,
+          `[MostBox] Failed to leave app swarm for ${channel.channelKey}:`,
           err.message
         )
       })
     }
 
-    const chatDiscovery = this.#channelChatDiscoveries.get(name)
+    const chatDiscovery = this.#channelChatDiscoveries.get(channel.channelKey)
     if (chatDiscovery && this.#chatSwarm) {
-      this.#channelChatDiscoveries.delete(name)
-      const chatDiscoveryKey = this.#generateChannelChatDiscoveryKey(name)
+      this.#channelChatDiscoveries.delete(channel.channelKey)
+      const chatDiscoveryKey = this.#generateChannelChatDiscoveryKey(
+        channel.channelKey
+      )
       this.#chatSwarm.leave(chatDiscoveryKey).catch(err => {
         console.warn(
-          `[MostBox] Failed to leave chat swarm for ${name}:`,
+          `[MostBox] Failed to leave chat swarm for ${channel.channelKey}:`,
           err.message
         )
       })
     }
 
-    const coresMap = this.#channelCores.get(name)
+    const hasSameIdChannel = this.#channels.some(
+      (item, itemIndex) =>
+        itemIndex !== index && item.channelId === channel.channelId
+    )
+    if (!hasSameIdChannel) {
+      const idDiscovery = this.#channelIdDiscoveries.get(channel.channelId)
+      if (idDiscovery && this.#chatSwarm) {
+        this.#channelIdDiscoveries.delete(channel.channelId)
+        this.#chatSwarm
+          .leave(this.#generateChannelIdDiscoveryKey(channel.channelId))
+          .catch(err => {
+            console.warn(
+              `[MostBox] Failed to leave channel ID discovery for ${channel.channelId}:`,
+              err.message
+            )
+          })
+      }
+    }
+
+    const coresMap = this.#channelCores.get(channel.channelKey)
     if (coresMap) {
       for (const [, core] of coresMap) {
         try {
           await core.close()
         } catch (err) {
           console.warn(
-            `[MostBox] Failed to close channel core for ${name}:`,
+            `[MostBox] Failed to close channel core for ${channel.channelKey}:`,
             err.message
           )
         }
       }
-      this.#channelCores.delete(name)
+      this.#channelCores.delete(channel.channelKey)
     }
-    this.#channelLocalCoreKey.delete(name)
+    this.#channelLocalCoreKey.delete(channel.channelKey)
 
-    this.#channelPeers.delete(name)
+    this.#channelPeers.delete(channel.channelKey)
     this.#channels.splice(index, 1)
     this.#saveChannelsMetadata()
 
-    console.log(`[MostBox] Left channel: ${name}`)
-    this.emit('channel:left', { name })
+    console.log(`[MostBox] Left channel: ${channel.channelKey}`)
+    this.emit('channel:left', {
+      channel: channel.channelKey,
+      channelKey: channel.channelKey,
+      channelId: channel.channelId,
+      name: channel.channelId,
+    })
 
     return this.listChannels({ ownerAddress })
   }
 
-  setChannelRemark(name, remark, options = {}) {
+  setChannelRemark(channelKeyInput, remark, options = {}) {
     this.#ensureInitialized()
     const ownerAddress = normalizeOwnerAddress(options.ownerAddress)
     if (!ownerAddress) {
       throw new Error('需要登录才能设置备注')
     }
 
-    const channel = this.#channels.find(c => c.name === name)
-    if (!channel) {
-      throw new Error('频道不存在')
-    }
+    const channel = this.#resolveChannel(channelKeyInput, ownerAddress)
 
     const trimmed = (remark || '').trim()
     if (trimmed.length > 50) {
@@ -2449,22 +2346,21 @@ export class MostBoxEngine extends EventEmitter {
       delete channel.remarks[ownerAddress]
     }
 
+    channel.syncUpdatedAt = getNextSyncTimestamp(channel.syncUpdatedAt)
     this.#saveChannelsMetadata()
+    this.#appendUserSyncChannelUpsertSoon(channel, ownerAddress)
     return trimmed
   }
 
-  setChannelPinned(name, pinned, options = {}) {
+  setChannelPinned(channelKeyInput, pinned, options = {}) {
     this.#ensureInitialized()
     const ownerAddress = normalizeOwnerAddress(options.ownerAddress)
     if (!ownerAddress) {
       throw new Error('需要登录才能设置置顶')
     }
 
-    const channel = this.#channels.find(c => c.name === name)
-    if (!channel) {
-      throw new Error('频道不存在')
-    }
-    this.#assertChannelMember(name, ownerAddress)
+    const channel = this.#resolveChannel(channelKeyInput, ownerAddress)
+    this.#assertChannelMember(channel.channelKey, ownerAddress)
 
     if (!channel.pinnedBy) {
       channel.pinnedBy = {}
@@ -2476,13 +2372,15 @@ export class MostBoxEngine extends EventEmitter {
       delete channel.pinnedBy[ownerAddress]
     }
 
+    channel.syncUpdatedAt = getNextSyncTimestamp(channel.syncUpdatedAt)
     this.#saveChannelsMetadata()
+    this.#appendUserSyncChannelUpsertSoon(channel, ownerAddress)
     return Boolean(channel.pinnedBy[ownerAddress])
   }
 
   /**
    * 列出所有频道
-   * @returns {Array<{ name: string, coreKey: string, createdAt: string, lastMessageAt: string, type: string, peerCount: number, remark: string, pinned: boolean }>}
+   * @returns {Array<{ channelId: string, channelKey: string, name: string, createdAt: string, lastMessageAt: string, type: string, peerCount: number, remark: string, pinned: boolean }>}
    */
   listChannels(options = {}) {
     this.#ensureInitialized()
@@ -2500,45 +2398,33 @@ export class MostBoxEngine extends EventEmitter {
         if (excludeType) return c.type !== excludeType
         return true
       })
-      .map(c => ({
-        name: c.name,
-        coreKey: c.coreKey,
-        createdAt: c.createdAt,
-        lastMessageAt: c.lastMessageAt || '',
-        type: c.type,
-        peerCount: (this.#channelPeers.get(c.name) || new Map()).size,
-        remark: ownerAddress && c.remarks ? c.remarks[ownerAddress] || '' : '',
-        pinned: Boolean(ownerAddress && c.pinnedBy?.[ownerAddress]),
-      }))
+      .map(c => this.#formatChannelForResponse(c, ownerAddress))
   }
 
-  getChannelMembers(name, options = {}) {
+  getChannelMembers(channelKeyInput, options = {}) {
     this.#ensureInitialized()
-    this.#assertChannelMember(name, options.ownerAddress)
-
-    const channel = this.#channels.find(c => c.name === name)
-    if (!channel) {
-      throw new Error('频道不存在')
-    }
+    this.#assertChannelMember(channelKeyInput, options.ownerAddress)
+    const channel = this.#resolveChannel(channelKeyInput, options.ownerAddress)
 
     return this.#getChannelMembers(channel)
   }
 
   /**
    * 获取频道消息
-   * @param {string} name - 频道名
+   * @param {string} channelKeyInput - 内部频道 key，或本地唯一短频道 ID
    * @param {object} [options] - 选项
    * @param {number} [options.limit=100] - 消息数量
    * @param {number} [options.offset=0] - 偏移量
    * @returns {Promise<Array>}
    */
-  async getChannelMessages(name, options = {}) {
+  async getChannelMessages(channelKeyInput, options = {}) {
     this.#ensureInitialized()
-    this.#assertChannelMember(name, options.ownerAddress)
+    this.#assertChannelMember(channelKeyInput, options.ownerAddress)
+    const channel = this.#resolveChannel(channelKeyInput, options.ownerAddress)
 
     const { limit = CHANNEL_MESSAGE_LIMIT, offset = 0 } = options
 
-    const coresMap = this.#channelCores.get(name)
+    const coresMap = this.#channelCores.get(channel.channelKey)
     if (!coresMap || coresMap.size === 0) {
       throw new Error('频道未初始化')
     }
@@ -2578,26 +2464,26 @@ export class MostBoxEngine extends EventEmitter {
     return unique
       .slice(start, end)
       .map(({ _coreKey, _index, ...msg }) =>
-        this.#normalizeChannelMessageForResponse(name, msg)
+        this.#normalizeChannelMessageForResponse(channel.channelKey, msg)
       )
   }
 
   /**
    * 发送消息到频道
-   * @param {string} name - 频道名
+   * @param {string} channelKeyInput - 内部频道 key，或本地唯一短频道 ID
    * @param {string} content - 消息内容
    * @param {string} author - 作者 address
    * @param {string} authorName - 作者显示名
    * @param {object} [options.attachment] - 附件元数据
    * @returns {Promise<object>}
    */
-  async sendMessage(name, content, author, authorName, options = {}) {
+  async sendMessage(channelKeyInput, content, author, authorName, options = {}) {
     this.#ensureInitialized()
-    this.#assertChannelMember(name, options.ownerAddress)
-    const channel = this.#channels.find(c => c.name === name)
+    this.#assertChannelMember(channelKeyInput, options.ownerAddress)
+    const channel = this.#resolveChannel(channelKeyInput, options.ownerAddress)
 
-    const localKeyHex = this.#channelLocalCoreKey.get(name)
-    const coresMap = this.#channelCores.get(name)
+    const localKeyHex = this.#channelLocalCoreKey.get(channel.channelKey)
+    const coresMap = this.#channelCores.get(channel.channelKey)
     const core = localKeyHex && coresMap ? coresMap.get(localKeyHex) : null
     if (!core) {
       throw new Error('频道未初始化或无可写 core')
@@ -2643,19 +2529,20 @@ export class MostBoxEngine extends EventEmitter {
       this.#saveChannelsMetadata()
     }
 
-    return message
+    return this.#normalizeChannelMessageForResponse(channel.channelKey, message)
   }
 
   /**
    * 获取频道内在线用户
-   * @param {string} name - 频道名
+   * @param {string} channelKeyInput - 内部频道 key，或本地唯一短频道 ID
    * @returns {Array<{ peerId: string, authorName: string, lastSeen: number }>}
    */
-  getChannelPeers(name, options = {}) {
+  getChannelPeers(channelKeyInput, options = {}) {
     this.#ensureInitialized()
-    this.#assertChannelMember(name, options.ownerAddress)
+    this.#assertChannelMember(channelKeyInput, options.ownerAddress)
+    const channel = this.#resolveChannel(channelKeyInput, options.ownerAddress)
 
-    const peers = this.#channelPeers.get(name)
+    const peers = this.#channelPeers.get(channel.channelKey)
     if (!peers) {
       return []
     }
@@ -2704,6 +2591,366 @@ export class MostBoxEngine extends EventEmitter {
 
   // --- 私有方法 ---
 
+  #resolveChannel(identifier, ownerAddress = '') {
+    const value = normalizeChannelKey(identifier)
+    const owner = normalizeOwnerAddress(ownerAddress)
+    let channel = this.#channels.find(c => c.channelKey === value)
+    if (channel) return channel
+
+    const matches = this.#channels.filter(c => c.channelId === value)
+    const visibleMatches = owner
+      ? matches.filter(c => this.#channelHasMember(c, owner))
+      : matches
+    if (visibleMatches.length === 1) return visibleMatches[0]
+    if (visibleMatches.length > 1) {
+      throw new Error('频道 ID 存在多个候选，请使用 channelKey')
+    }
+    throw new Error('频道不存在')
+  }
+
+  async #createLocalChannel(channelId, type = 'personal', options = {}) {
+    const fingerprint =
+      String(options.fingerprint || '').trim() || createChannelFingerprint()
+    const channelKey = buildChannelKey(channelId, fingerprint)
+    const writerId = String(options.writerId || '').trim() || createChannelWriterId()
+    const ns = this.#store.namespace(`channel-${channelKey}`)
+    const localCore = ns.get({
+      name: `messages-${writerId}`,
+      valueEncoding: 'json',
+    })
+    await localCore.ready()
+    const localWriterCoreKey = b4a.toString(localCore.key, 'hex')
+    const writerCoreKeys = uniqueStrings([
+      ...(Array.isArray(options.writerCoreKeys) ? options.writerCoreKeys : []),
+      localWriterCoreKey,
+    ])
+    const channelInfo = {
+      channelId,
+      fingerprint,
+      channelKey,
+      name: channelId,
+      type: String(type || 'personal').trim() || 'personal',
+      createdAt: options.createdAt || new Date().toISOString(),
+      lastMessageAt: options.lastMessageAt || '',
+      writerId,
+      localWriterCoreKey,
+      writerCoreKeys,
+      members: [],
+      syncUpdatedAt: Date.now(),
+    }
+
+    this.#upsertChannelMember(channelInfo, options)
+    const ownerAddress = normalizeOwnerAddress(options.ownerAddress)
+    const remark = String(options.remark || '').trim()
+    if (ownerAddress && remark) {
+      channelInfo.remarks = { [ownerAddress]: remark.slice(0, 50) }
+    }
+
+    this.#channels.push(channelInfo)
+    await this.#openChannelRuntime(channelInfo)
+    await this.#joinChannelDiscoveryTopics(channelInfo)
+    this.#cacheChannelCandidate(this.#channelToCandidate(channelInfo, true))
+    this.#saveChannelsMetadata()
+    return channelInfo
+  }
+
+  async #joinChannelFromCandidate(candidateInput, type = 'group', options = {}) {
+    const channelId = normalizeChannelId(
+      candidateInput.channelId || options.channelId
+    )
+    const channelKey = normalizeChannelKey(candidateInput.channelKey)
+    const fingerprint =
+      String(candidateInput.fingerprint || '').trim() ||
+      getChannelFingerprintFromKey(channelId, channelKey)
+    if (!channelId || !fingerprint) {
+      throw new Error('频道候选缺少身份信息')
+    }
+    const expectedChannelKey = buildChannelKey(channelId, fingerprint)
+    if (channelKey && channelKey !== expectedChannelKey) {
+      throw new Error('频道候选身份格式不匹配')
+    }
+
+    const existing = this.#channels.find(
+      channel => channel.channelKey === expectedChannelKey
+    )
+    if (existing) {
+      if (this.#upsertChannelMember(existing, options)) {
+        this.#saveChannelsMetadata()
+      }
+      return this.#formatChannelForResponse(existing, options.ownerAddress)
+    }
+
+    const hasSameIdLocal = this.#channels.some(
+      channel => channel.channelId === channelId
+    )
+    const ownerAddress = normalizeOwnerAddress(options.ownerAddress)
+    const remark =
+      ownerAddress && hasSameIdLocal && !String(options.remark || '').trim()
+        ? `${channelId}-网络`
+        : options.remark
+    const channelInfo = await this.#createLocalChannel(channelId, candidateInput.type || type, {
+      ...options,
+      ownerAddress,
+      fingerprint,
+      createdAt: candidateInput.createdAt,
+      lastMessageAt: candidateInput.lastMessageAt,
+      writerCoreKeys: candidateInput.writerCoreKeys,
+      remark,
+    })
+
+    console.log(`[MostBox] Joined channel: ${channelInfo.channelKey}`)
+    this.emit('channel:joined', {
+      channel: channelInfo.channelKey,
+      channelKey: channelInfo.channelKey,
+      channelId: channelInfo.channelId,
+      key: channelInfo.channelKey,
+    })
+
+    return this.#formatChannelForResponse(channelInfo, ownerAddress)
+  }
+
+  async #openChannelRuntime(channel) {
+    const ns = this.#store.namespace(`channel-${channel.channelKey}`)
+    const localCore = channel.localWriterCoreKey
+      ? ns.get({
+          key: b4a.from(channel.localWriterCoreKey, 'hex'),
+          valueEncoding: 'json',
+        })
+      : ns.get({
+          name: `messages-${channel.writerId || createChannelWriterId()}`,
+          valueEncoding: 'json',
+        })
+    await localCore.ready()
+    const localWriterCoreKey = b4a.toString(localCore.key, 'hex')
+    channel.localWriterCoreKey = localWriterCoreKey
+    channel.writerCoreKeys = uniqueStrings([
+      ...(Array.isArray(channel.writerCoreKeys) ? channel.writerCoreKeys : []),
+      localWriterCoreKey,
+    ])
+
+    if (!this.#channelCores.has(channel.channelKey)) {
+      this.#channelCores.set(channel.channelKey, new Map())
+    }
+    this.#channelCores.get(channel.channelKey).set(localWriterCoreKey, localCore)
+    this.#channelLocalCoreKey.set(channel.channelKey, localWriterCoreKey)
+    if (!this.#channelPeers.has(channel.channelKey)) {
+      this.#channelPeers.set(channel.channelKey, new Map())
+    }
+    this.#setupChannelAppendListener(localCore, channel.channelKey)
+
+    for (const writerCoreKey of channel.writerCoreKeys) {
+      if (writerCoreKey && writerCoreKey !== localWriterCoreKey) {
+        await this.#openRemoteChannelCore(channel.channelKey, writerCoreKey)
+      }
+    }
+  }
+
+  async #mergeChannelWriterCoreKeys(channel, writerCoreKeys = []) {
+    const nextKeys = uniqueStrings(writerCoreKeys)
+    if (nextKeys.length === 0) return false
+
+    const previous = new Set(channel.writerCoreKeys || [])
+    let changed = false
+    for (const writerCoreKey of nextKeys) {
+      if (!previous.has(writerCoreKey)) {
+        previous.add(writerCoreKey)
+        changed = true
+      }
+      if (writerCoreKey !== this.#channelLocalCoreKey.get(channel.channelKey)) {
+        await this.#openRemoteChannelCore(channel.channelKey, writerCoreKey)
+      }
+    }
+    if (changed) {
+      channel.writerCoreKeys = [...previous]
+      this.#saveChannelsMetadata()
+    }
+    return changed
+  }
+
+  async #joinChannelDiscoveryTopics(channel) {
+    if (!this.#channelDiscoveries.has(channel.channelKey)) {
+      const appDiscovery = this.#swarm.join(
+        this.#generateChannelDiscoveryKey(channel.channelKey),
+        { server: true, client: true }
+      )
+      this.#channelDiscoveries.set(channel.channelKey, appDiscovery)
+    }
+
+    if (!this.#channelChatDiscoveries.has(channel.channelKey)) {
+      const chatDiscovery = this.#chatSwarm.join(
+        this.#generateChannelChatDiscoveryKey(channel.channelKey),
+        { server: true, client: true }
+      )
+      this.#channelChatDiscoveries.set(channel.channelKey, chatDiscovery)
+    }
+
+    if (!this.#channelIdDiscoveries.has(channel.channelId)) {
+      const idDiscovery = this.#chatSwarm.join(
+        this.#generateChannelIdDiscoveryKey(channel.channelId),
+        { server: true, client: true }
+      )
+      this.#channelIdDiscoveries.set(channel.channelId, idDiscovery)
+    }
+  }
+
+  #getLocalChannelCandidates(channelId, options = {}) {
+    const ownerAddress = normalizeOwnerAddress(options.ownerAddress)
+    return this.#channels
+      .filter(channel => channel.channelId === channelId)
+      .filter(channel => {
+        if (!ownerAddress) return true
+        return this.#channelHasMember(channel, ownerAddress)
+      })
+      .map(channel => this.#channelToCandidate(channel, true))
+  }
+
+  async #discoverChannelCandidates(channelId, options = {}) {
+    if (this.#options.disableNetwork) return []
+    const timeout =
+      Number(options.timeout) >= 0
+        ? Number(options.timeout)
+        : CHANNEL_DISCOVERY_TIMEOUT
+    const hadDiscovery = this.#channelIdDiscoveries.has(channelId)
+    if (!hadDiscovery) {
+      const discovery = this.#chatSwarm.join(
+        this.#generateChannelIdDiscoveryKey(channelId),
+        { server: true, client: true }
+      )
+      this.#channelIdDiscoveries.set(channelId, discovery)
+    }
+    await sleep(timeout)
+    const now = Date.now()
+    const candidates = [
+      ...(this.#channelCandidateCache.get(channelId)?.values() || []),
+    ].filter(
+      candidate =>
+        candidate.local ||
+        !candidate.lastSeen ||
+        now - candidate.lastSeen <= CHANNEL_CANDIDATE_TTL
+    )
+    if (!hadDiscovery && !this.#channels.some(c => c.channelId === channelId)) {
+      this.#channelIdDiscoveries.delete(channelId)
+      this.#chatSwarm
+        .leave(this.#generateChannelIdDiscoveryKey(channelId))
+        .catch(() => {})
+    }
+    return candidates
+  }
+
+  #mergeChannelCandidates(candidates) {
+    const byKey = new Map()
+    for (const candidate of candidates) {
+      if (!candidate?.channelKey) continue
+      const existing = byKey.get(candidate.channelKey)
+      if (!existing) {
+        byKey.set(candidate.channelKey, {
+          ...candidate,
+          writerCoreKeys: uniqueStrings(candidate.writerCoreKeys),
+          onlineCount: Number(candidate.onlineCount) || (candidate.local ? 0 : 1),
+        })
+        continue
+      }
+      byKey.set(candidate.channelKey, {
+        ...existing,
+        ...candidate,
+        local: existing.local || candidate.local,
+        writerCoreKeys: uniqueStrings([
+          ...existing.writerCoreKeys,
+          ...(candidate.writerCoreKeys || []),
+        ]),
+        onlineCount:
+          Math.max(Number(existing.onlineCount) || 0, 0) +
+          (candidate.local ? 0 : 1),
+      })
+    }
+    return [...byKey.values()]
+  }
+
+  #channelToCandidate(channel, local = false) {
+    return {
+      channelId: channel.channelId,
+      fingerprint: channel.fingerprint,
+      channelKey: channel.channelKey,
+      type: channel.type,
+      createdAt: channel.createdAt,
+      lastMessageAt: channel.lastMessageAt || '',
+      writerCoreKeys: uniqueStrings(channel.writerCoreKeys),
+      local,
+      onlineCount: local ? 0 : 1,
+    }
+  }
+
+  #cacheChannelCandidate(candidate) {
+    if (!candidate?.channelId || !candidate?.channelKey) return
+    if (!this.#channelCandidateCache.has(candidate.channelId)) {
+      this.#channelCandidateCache.set(candidate.channelId, new Map())
+    }
+    const cache = this.#channelCandidateCache.get(candidate.channelId)
+    const existing = cache.get(candidate.channelKey)
+    cache.set(candidate.channelKey, {
+      ...existing,
+      ...candidate,
+      writerCoreKeys: uniqueStrings([
+        ...(existing?.writerCoreKeys || []),
+        ...(candidate.writerCoreKeys || []),
+      ]),
+      onlineCount: Math.max(Number(existing?.onlineCount) || 0, 0) + 1,
+      lastSeen: Date.now(),
+    })
+  }
+
+  #getCachedChannelCandidate(channelId, channelKey) {
+    const candidate = this.#channelCandidateCache.get(channelId)?.get(channelKey)
+    if (candidate) return candidate
+    const local = this.#channels.find(channel => channel.channelKey === channelKey)
+    return local ? this.#channelToCandidate(local, true) : null
+  }
+
+  #formatChannelCandidateForResponse(candidate, ownerAddress = '') {
+    const owner = normalizeOwnerAddress(ownerAddress)
+    const localChannel = this.#channels.find(
+      channel => channel.channelKey === candidate.channelKey
+    )
+    const remark =
+      localChannel && owner
+        ? localChannel.remarks?.[owner] || ''
+        : candidate.local
+          ? ''
+          : `${candidate.channelId}-网络`
+    return {
+      channelId: candidate.channelId,
+      fingerprint: candidate.fingerprint,
+      channelKey: candidate.channelKey,
+      name: candidate.channelId,
+      type: candidate.type || 'public',
+      createdAt: candidate.createdAt || '',
+      lastMessageAt: candidate.lastMessageAt || '',
+      remark,
+      local: Boolean(candidate.local),
+      onlineCount: Number(candidate.onlineCount) || 0,
+    }
+  }
+
+  #formatChannelForResponse(channel, ownerAddress = '') {
+    const owner = normalizeOwnerAddress(ownerAddress)
+    return {
+      name: channel.channelId,
+      channelId: channel.channelId,
+      fingerprint: channel.fingerprint,
+      channelKey: channel.channelKey,
+      key: channel.channelKey,
+      coreKey: channel.localWriterCoreKey,
+      localWriterCoreKey: channel.localWriterCoreKey,
+      writerCoreKeys: uniqueStrings(channel.writerCoreKeys),
+      createdAt: channel.createdAt,
+      lastMessageAt: channel.lastMessageAt || '',
+      type: channel.type,
+      peerCount: (this.#channelPeers.get(channel.channelKey) || new Map()).size,
+      remark: owner && channel.remarks ? channel.remarks[owner] || '' : '',
+      pinned: Boolean(owner && channel.pinnedBy?.[owner]),
+    }
+  }
+
   #ensureInitialized() {
     if (!this.#initialized) {
       throw new EngineNotInitializedError()
@@ -2714,10 +2961,7 @@ export class MostBoxEngine extends EventEmitter {
     const normalizedOwner = normalizeOwnerAddress(ownerAddress)
     if (!normalizedOwner) return
 
-    const channel = this.#channels.find(c => c.name === name)
-    if (!channel) {
-      throw new Error('频道不存在')
-    }
+    const channel = this.#resolveChannel(name)
     if (!this.#channelHasMember(channel, normalizedOwner)) {
       throw new PermissionError('未加入该频道')
     }
@@ -2802,35 +3046,47 @@ export class MostBoxEngine extends EventEmitter {
       )
   }
 
-  #normalizeChannelMessageForResponse(channelName, message) {
-    const attachment = message?.attachment
+  #normalizeChannelMessageForResponse(channelKey, message) {
+    const channel = this.#channels.find(item => item.channelKey === channelKey)
+    const authorAddress = normalizeOwnerAddress(message?.author)
+    const member = Array.isArray(channel?.members)
+      ? channel.members.find(
+          item => normalizeOwnerAddress(item?.address) === authorAddress
+        )
+      : null
+    const avatar = normalizeChannelAvatar(member?.avatar)
+    const baseMessage = avatar && message?.avatar !== avatar
+      ? { ...message, avatar }
+      : message
+    const attachment = baseMessage?.attachment
     if (!attachment?.cid || !attachment.fileName) {
-      return message
+      return baseMessage
     }
 
     const oldFileName = sanitizeFilename(String(attachment.fileName))
-    const channelPrefix = `${CHAT_FILE_ROOT}/${channelName}/`
+    const channelPathName = channel?.channelId || channelKey
+    const channelPrefix = `${CHAT_FILE_ROOT}/${channelPathName}/`
     const fileName = oldFileName.startsWith(channelPrefix)
       ? oldFileName
       : `${channelPrefix}${getPathBaseName(oldFileName)}`
     const link = buildMostLink(attachment.cid, fileName)
     const content =
-      typeof message.content === 'string' &&
-      (message.content === attachment.link ||
-        parseMostLink(message.content).cid === attachment.cid)
+      typeof baseMessage.content === 'string' &&
+      (baseMessage.content === attachment.link ||
+        parseMostLink(baseMessage.content).cid === attachment.cid)
         ? link
-        : message.content
+        : baseMessage.content
 
     if (
       fileName === attachment.fileName &&
       link === attachment.link &&
-      content === message.content
+      content === baseMessage.content
     ) {
-      return message
+      return baseMessage
     }
 
     return {
-      ...message,
+      ...baseMessage,
       content,
       attachment: {
         ...attachment,
@@ -2863,114 +3119,803 @@ export class MostBoxEngine extends EventEmitter {
     }
   }
 
-  #hashImportPackage(input) {
-    return crypto
-      .createHash('sha256')
-      .update(JSON.stringify(input || {}))
+  #getUserSyncNamespace(session) {
+    return this.#store.namespace(session.syncName)
+  }
+
+  async #openUserSyncRuntime(session) {
+    const ns = this.#getUserSyncNamespace(session)
+    const localCore = session.localWriterCoreKey
+      ? ns.get({
+          key: b4a.from(session.localWriterCoreKey, 'hex'),
+          valueEncoding: 'json',
+        })
+      : ns.get({
+          name: `writer-${session.writerId}`,
+          valueEncoding: 'json',
+        })
+    await localCore.ready()
+    session.localWriterCoreKey = b4a.toString(localCore.key, 'hex')
+    session.writerCoreKeys = uniqueStrings([
+      ...session.writerCoreKeys,
+      session.localWriterCoreKey,
+    ])
+
+    if (!this.#userSyncCores.has(session.ownerAddress)) {
+      this.#userSyncCores.set(session.ownerAddress, new Map())
+    }
+    this.#userSyncCores
+      .get(session.ownerAddress)
+      .set(session.localWriterCoreKey, localCore)
+    this.#setupUserSyncAppendListener(
+      localCore,
+      session,
+      session.localWriterCoreKey
+    )
+
+    for (const writerCoreKey of session.writerCoreKeys) {
+      if (writerCoreKey && writerCoreKey !== session.localWriterCoreKey) {
+        await this.#openRemoteUserSyncCore(session, writerCoreKey)
+      }
+    }
+  }
+
+  async #joinUserSyncDiscovery(session) {
+    if (this.#userSyncDiscoveries.has(session.ownerAddress)) return
+    const discoveryKey = this.#generateUserSyncDiscoveryKey(session.syncId)
+    const appDiscovery = this.#swarm.join(discoveryKey, {
+      server: true,
+      client: true,
+    })
+    const chatDiscovery = this.#chatSwarm.join(
+      discoveryKey,
+      { server: true, client: true }
+    )
+    this.#userSyncDiscoveries.set(session.ownerAddress, {
+      appDiscovery,
+      chatDiscovery,
+    })
+  }
+
+  async #openRemoteUserSyncCore(session, writerCoreKey) {
+    const normalizedCoreKey = String(writerCoreKey || '').trim()
+    if (
+      !normalizedCoreKey ||
+      normalizedCoreKey === session.localWriterCoreKey
+    ) {
+      return null
+    }
+    if (!this.#userSyncCores.has(session.ownerAddress)) {
+      this.#userSyncCores.set(session.ownerAddress, new Map())
+    }
+    const coresMap = this.#userSyncCores.get(session.ownerAddress)
+    if (coresMap.has(normalizedCoreKey)) return coresMap.get(normalizedCoreKey)
+
+    const ns = this.#getUserSyncNamespace(session)
+    const core = ns.get({
+      key: b4a.from(normalizedCoreKey, 'hex'),
+      valueEncoding: 'json',
+    })
+    await core.ready()
+    coresMap.set(normalizedCoreKey, core)
+    session.writerCoreKeys = uniqueStrings([
+      ...session.writerCoreKeys,
+      normalizedCoreKey,
+    ])
+    this.#persistUserSyncSession(session)
+    this.#setupUserSyncAppendListener(core, session, normalizedCoreKey)
+    return core
+  }
+
+  #setupUserSyncAppendListener(core, session, coreKey) {
+    const offsetKey = `${session.ownerAddress}:${coreKey}`
+    let processing = false
+    const processEntries = async () => {
+      if (processing) return
+      processing = true
+      try {
+        let index = this.#userSyncCoreOffsets.get(offsetKey) || 0
+        while (index < core.length) {
+          const entry = await core.get(index)
+          await this.#applyUserSyncEntry(session, entry)
+          index += 1
+          this.#userSyncCoreOffsets.set(offsetKey, index)
+        }
+      } finally {
+        processing = false
+      }
+    }
+
+    core.on('append', () => {
+      processEntries().catch(err => {
+        console.warn('[MostBox] Failed to process user sync entry:', err.message)
+      })
+    })
+    processEntries().catch(err => {
+      console.warn('[MostBox] Failed to process user sync entries:', err.message)
+    })
+  }
+
+  #encodeUserSyncEntry(session, op) {
+    const nonce = crypto.randomBytes(12)
+    const cipher = crypto.createCipheriv(
+      'aes-256-gcm',
+      Buffer.from(session.syncCipherKey, 'hex'),
+      nonce
+    )
+    const encrypted = Buffer.concat([
+      cipher.update(JSON.stringify(op), 'utf8'),
+      cipher.final(),
+    ])
+    const tag = cipher.getAuthTag()
+    const body = `${nonce.toString('hex')}.${encrypted.toString('hex')}.${tag.toString('hex')}`
+    const mac = crypto
+      .createHmac('sha256', Buffer.from(session.syncMacKey, 'hex'))
+      .update(body)
+      .digest('hex')
+
+    return {
+      type: 'user-sync-op',
+      schemaVersion: USER_SYNC_SCHEMA_VERSION,
+      ownerAddress: session.ownerAddress,
+      syncId: session.syncId,
+      writerCoreKeys: uniqueStrings(session.writerCoreKeys),
+      body,
+      mac,
+      createdAt: new Date(op.timestamp).toISOString(),
+    }
+  }
+
+  #decodeUserSyncEntry(session, entry) {
+    if (
+      !entry ||
+      entry.type !== 'user-sync-op' ||
+      entry.syncId !== session.syncId ||
+      entry.ownerAddress !== session.ownerAddress ||
+      Number(entry.schemaVersion) !== USER_SYNC_SCHEMA_VERSION
+    ) {
+      return null
+    }
+
+    const expectedMac = crypto
+      .createHmac('sha256', Buffer.from(session.syncMacKey, 'hex'))
+      .update(String(entry.body || ''))
       .digest('hex')
+    if (expectedMac !== entry.mac) return null
+
+    const [nonceHex, encryptedHex, tagHex] = String(entry.body || '').split('.')
+    if (!nonceHex || !encryptedHex || !tagHex) return null
+
+    try {
+      const decipher = crypto.createDecipheriv(
+        'aes-256-gcm',
+        Buffer.from(session.syncCipherKey, 'hex'),
+        Buffer.from(nonceHex, 'hex')
+      )
+      decipher.setAuthTag(Buffer.from(tagHex, 'hex'))
+      const decrypted = Buffer.concat([
+        decipher.update(Buffer.from(encryptedHex, 'hex')),
+        decipher.final(),
+      ])
+      return JSON.parse(decrypted.toString('utf8'))
+    } catch {
+      return null
+    }
   }
 
-  #normalizeUserImportPackage(input = {}) {
-    if (!input || typeof input !== 'object') {
-      throw new ValidationError('import package must be an object')
+  async #appendUserSyncOp(ownerAddressInput, kind, payload = {}) {
+    const ownerAddress = normalizeOwnerAddress(ownerAddressInput)
+    const session = this.#userSyncSessions.get(ownerAddress)
+    if (!session?.localWriterCoreKey) return null
+    const coresMap = this.#userSyncCores.get(ownerAddress)
+    const core = coresMap?.get(session.localWriterCoreKey)
+    if (!core) return null
+
+    const op = {
+      opId: `${Date.now()}-${crypto.randomBytes(6).toString('hex')}`,
+      schemaVersion: USER_SYNC_SCHEMA_VERSION,
+      kind,
+      ownerAddress,
+      timestamp: Date.now(),
+      payload,
     }
-    if (Number(input.schemaVersion) !== USER_DATA_SCHEMA_VERSION) {
-      throw new ValidationError('unsupported import package schemaVersion')
+    this.#markUserSyncClockForOp(op)
+    await core.append(this.#encodeUserSyncEntry(session, op))
+    this.#touchUserSyncSession(session)
+    return op
+  }
+
+  #appendUserSyncOpSoon(ownerAddress, kind, payload = {}) {
+    this.#appendUserSyncOp(ownerAddress, kind, payload).catch(err => {
+      console.warn('[MostBox] Failed to append user sync op:', err.message)
+    })
+  }
+
+  async #appendUserSyncSnapshot(ownerAddressInput, reason = 'snapshot') {
+    const ownerAddress = normalizeOwnerAddress(ownerAddressInput)
+    if (!this.#userSyncSessions.has(ownerAddress)) return null
+    const files = this.#getPublishedBucket(ownerAddress).map(file =>
+      this.#formatFileForSync(file, 'active')
+    )
+    const trashFiles = this.#getTrashBucket(ownerAddress).map(file =>
+      this.#formatFileForSync(file, 'trash')
+    )
+    const channels = this.#channels
+      .filter(channel => this.#channelHasMember(channel, ownerAddress))
+      .map(channel => this.#formatChannelForSync(channel, ownerAddress))
+      .filter(Boolean)
+    return this.#appendUserSyncOp(ownerAddress, 'snapshot', {
+      reason,
+      files,
+      trashFiles,
+      channels,
+    })
+  }
+
+  async #applyUserSyncEntry(session, entry) {
+    const op = this.#decodeUserSyncEntry(session, entry)
+    if (!op || op.ownerAddress !== session.ownerAddress) return false
+    if (Array.isArray(entry.writerCoreKeys)) {
+      await this.#mergeUserSyncWriterCoreKeys(session, entry.writerCoreKeys)
     }
+    return this.#applyUserSyncOp(session, op)
+  }
 
-    const normalizeFile = (record, scope) => {
-      if (!record || typeof record !== 'object') {
-        throw new ValidationError(`${scope} record must be an object`)
+  async #applyUserSyncOp(session, op) {
+    let changedFiles = false
+    let changedChannels = false
+    if (op.kind === 'snapshot') {
+      const payload = op.payload || {}
+      for (const file of Array.isArray(payload.files) ? payload.files : []) {
+        changedFiles =
+          this.#applyUserSyncFileRecord(
+            session.ownerAddress,
+            file,
+            'active',
+            getSyncTimestamp(file.syncUpdatedAt, op.timestamp)
+          ) || changedFiles
       }
-      const cid = String(record.cid || '').trim()
-      const { driveName } = this.#getCidInfo(cid)
-      const fileName = sanitizeFilename(record.fileName || cid)
-      if (!fileName || fileName === 'unnamed') {
-        throw new ValidationError(`${scope} fileName is invalid`)
+      for (const file of Array.isArray(payload.trashFiles) ? payload.trashFiles : []) {
+        changedFiles =
+          this.#applyUserSyncFileRecord(
+            session.ownerAddress,
+            file,
+            'trash',
+            getSyncTimestamp(file.syncUpdatedAt, op.timestamp)
+          ) || changedFiles
       }
-      return {
-        cid,
-        fileName,
-        driveName,
-        size: Number(record.size) || 0,
-        source: String(record.source || 'imported'),
-        publishedAt:
-          typeof record.publishedAt === 'string' ? record.publishedAt : '',
-        deletedAt: typeof record.deletedAt === 'string' ? record.deletedAt : '',
-        starred: Boolean(record.starred),
+      for (const channel of Array.isArray(payload.channels) ? payload.channels : []) {
+        changedChannels =
+          (await this.#applyUserSyncChannelRecord(
+            session.ownerAddress,
+            channel,
+            getSyncTimestamp(channel.syncUpdatedAt, op.timestamp)
+          )) || changedChannels
       }
+    } else if (op.kind === 'file:upsert') {
+      changedFiles = this.#applyUserSyncFileRecord(
+        session.ownerAddress,
+        op.payload?.file,
+        'active',
+        getSyncTimestamp(op.payload?.file?.syncUpdatedAt, op.timestamp)
+      )
+    } else if (op.kind === 'file:trash') {
+      changedFiles = this.#applyUserSyncFileRecord(
+        session.ownerAddress,
+        op.payload?.file,
+        'trash',
+        getSyncTimestamp(op.payload?.file?.syncUpdatedAt, op.timestamp)
+      )
+    } else if (op.kind === 'file:delete') {
+      changedFiles = await this.#applyUserSyncFileDelete(
+        session.ownerAddress,
+        op.payload?.cid,
+        getSyncTimestamp(op.payload?.syncUpdatedAt, op.timestamp)
+      )
+    } else if (op.kind === 'channel:upsert') {
+      changedChannels = await this.#applyUserSyncChannelRecord(
+        session.ownerAddress,
+        op.payload?.channel,
+        getSyncTimestamp(op.payload?.channel?.syncUpdatedAt, op.timestamp)
+      )
+    } else if (op.kind === 'channel:leave') {
+      changedChannels = this.#applyUserSyncChannelLeave(
+        session.ownerAddress,
+        op.payload?.channelKey,
+        getSyncTimestamp(op.payload?.syncUpdatedAt, op.timestamp)
+      )
     }
 
-    const files = Array.isArray(input.files)
-      ? input.files.map(record => normalizeFile(record, 'files'))
-      : []
-    const trashFiles = Array.isArray(input.trashFiles)
-      ? input.trashFiles.map(record => normalizeFile(record, 'trashFiles'))
-      : []
-    const channels = Array.isArray(input.channels)
-      ? input.channels
-          .filter(channel => channel && typeof channel === 'object')
-          .map(channel => ({
-            name: String(channel.name || '').trim(),
-            type: String(channel.type || 'personal').trim() || 'personal',
-            coreKey: String(channel.coreKey || '').trim(),
-            createdAt:
-              typeof channel.createdAt === 'string' ? channel.createdAt : '',
-            lastMessageAt:
-              typeof channel.lastMessageAt === 'string'
-                ? channel.lastMessageAt
-                : '',
-            member:
-              channel.member && typeof channel.member === 'object'
-                ? channel.member
-                : null,
-            remark: String(channel.remark || '').slice(0, 50),
-            pinned: Boolean(channel.pinned),
-          }))
-          .filter(channel => CHANNEL_NAME_REGEX.test(channel.name))
-      : []
+    if (changedFiles) {
+      this.#savePublishedMetadata()
+      this.#saveTrashMetadata()
+      this.emit('user:metadata:updated', {
+        ownerAddress: session.ownerAddress,
+        scope: 'files',
+      })
+    }
+    if (changedChannels) {
+      this.#saveChannelsMetadata()
+      this.emit('user:metadata:updated', {
+        ownerAddress: session.ownerAddress,
+        scope: 'channels',
+      })
+    }
+    if (changedFiles || changedChannels) {
+      this.#touchUserSyncSession(session)
+    }
+    return changedFiles || changedChannels
+  }
 
-    return { files, trashFiles, channels }
+  async #mergeUserSyncWriterCoreKeys(session, writerCoreKeys = []) {
+    const nextKeys = uniqueStrings(writerCoreKeys)
+    if (nextKeys.length === 0) return false
+    const previous = new Set(session.writerCoreKeys || [])
+    let changed = false
+    for (const writerCoreKey of nextKeys) {
+      if (!previous.has(writerCoreKey)) {
+        previous.add(writerCoreKey)
+        changed = true
+      }
+      if (writerCoreKey !== session.localWriterCoreKey) {
+        await this.#openRemoteUserSyncCore(session, writerCoreKey)
+      }
+    }
+    if (changed) {
+      session.writerCoreKeys = [...previous]
+      this.#persistUserSyncSession(session)
+    }
+    return changed
   }
 
-  #applyImportedChannels(ownerAddress, channels = []) {
-    const normalizedOwner = normalizeOwnerAddress(ownerAddress)
-    if (!normalizedOwner) return
+  async #exchangeUserSyncSessions(peerEngine) {
+    for (const session of this.#userSyncSessions.values()) {
+      const peerSession = peerEngine.#userSyncSessions.get(session.ownerAddress)
+      if (!peerSession || peerSession.syncId !== session.syncId) continue
+      await this.#mergeUserSyncWriterCoreKeys(
+        session,
+        peerSession.writerCoreKeys
+      )
+      await peerEngine.#mergeUserSyncWriterCoreKeys(
+        peerSession,
+        session.writerCoreKeys
+      )
+    }
+  }
 
-    for (const imported of channels) {
-      let channel = this.#channels.find(item => item.name === imported.name)
-      if (!channel) {
-        const discoveryKey = this.#generateChannelDiscoveryKey(imported.name)
-        channel = {
-          name: imported.name,
-          discoveryKey: b4a.toString(discoveryKey, 'hex'),
-          coreKey: imported.coreKey,
-          createdAt: imported.createdAt || new Date().toISOString(),
-          lastMessageAt: imported.lastMessageAt || '',
-          type: imported.type,
-          members: [],
-          remoteCoreKeys: [],
-        }
-        this.#channels.push(channel)
+  #formatFileForSync(file, state = 'active') {
+    const cid = String(file?.cid || '').trim()
+    if (!cid) return null
+    const { driveName } = this.#getCidInfo(cid)
+    const syncUpdatedAt = getSyncTimestamp(
+      file.syncUpdatedAt || file.deletedAt || file.publishedAt
+    )
+    return {
+      cid,
+      fileName: sanitizeFilename(file.fileName || cid),
+      driveName: file.driveName || driveName,
+      size: Number(file.size) || 0,
+      source: String(file.source || (state === 'active' ? 'published' : 'trash')),
+      publishedAt:
+        typeof file.publishedAt === 'string'
+          ? file.publishedAt
+          : new Date(syncUpdatedAt).toISOString(),
+      deletedAt:
+        typeof file.deletedAt === 'string'
+          ? file.deletedAt
+          : state === 'trash'
+            ? new Date(syncUpdatedAt).toISOString()
+            : '',
+      starred: Boolean(file.starred),
+      syncUpdatedAt,
+    }
+  }
+
+  #formatChannelForSync(channel, ownerAddress) {
+    const owner = normalizeOwnerAddress(ownerAddress)
+    if (
+      !channel ||
+      !owner ||
+      TRANSIENT_CHANNEL_TYPES.has(channel.type) ||
+      !this.#channelHasMember(channel, owner)
+    ) {
+      return null
+    }
+    return {
+      channelId: channel.channelId,
+      fingerprint: channel.fingerprint,
+      channelKey: channel.channelKey,
+      type: channel.type,
+      createdAt: channel.createdAt,
+      lastMessageAt: channel.lastMessageAt || '',
+      writerCoreKeys: uniqueStrings(channel.writerCoreKeys),
+      member: this.#getChannelMembers(channel).find(
+        member => member.address === owner
+      ),
+      remark: channel.remarks?.[owner] || '',
+      pinned: Boolean(channel.pinnedBy?.[owner]),
+      syncUpdatedAt: getSyncTimestamp(
+        channel.syncUpdatedAt || channel.lastMessageAt || channel.createdAt
+      ),
+    }
+  }
+
+  #appendUserSyncChannelUpsertSoon(channel, ownerAddress) {
+    const owner = normalizeOwnerAddress(ownerAddress)
+    const record = this.#formatChannelForSync(channel, owner)
+    if (!record) return
+    this.#appendUserSyncOpSoon(owner, 'channel:upsert', { channel: record })
+  }
+
+  #appendUserSyncChannelLeaveSoon(channel, ownerAddress, syncUpdatedAt = Date.now()) {
+    const owner = normalizeOwnerAddress(ownerAddress)
+    if (!owner || !channel || TRANSIENT_CHANNEL_TYPES.has(channel.type)) return
+    this.#appendUserSyncOpSoon(owner, 'channel:leave', {
+      channelKey: channel.channelKey,
+      syncUpdatedAt,
+    })
+  }
+
+  #normalizeSyncFileRecord(record, state, timestamp) {
+    if (!record || typeof record !== 'object') return null
+    const cid = String(record.cid || '').trim()
+    if (!cid) return null
+    let driveName = ''
+    try {
+      driveName = this.#getCidInfo(cid).driveName
+    } catch {
+      return null
+    }
+    const fileName = sanitizeFilename(record.fileName || cid)
+    if (!fileName || fileName === 'unnamed') return null
+    const syncUpdatedAt = getSyncTimestamp(record.syncUpdatedAt, timestamp)
+    return {
+      cid,
+      fileName,
+      driveName: record.driveName || driveName,
+      size: Number(record.size) || 0,
+      source: String(record.source || (state === 'active' ? 'synced' : 'trash')),
+      publishedAt:
+        typeof record.publishedAt === 'string'
+          ? record.publishedAt
+          : new Date(syncUpdatedAt).toISOString(),
+      deletedAt:
+        typeof record.deletedAt === 'string'
+          ? record.deletedAt
+          : state === 'trash'
+            ? new Date(syncUpdatedAt).toISOString()
+            : '',
+      starred: Boolean(record.starred),
+      syncUpdatedAt,
+    }
+  }
+
+  #applyUserSyncFileRecord(ownerAddress, record, state, timestamp) {
+    const normalized = this.#normalizeSyncFileRecord(record, state, timestamp)
+    if (!normalized) return false
+    const entityKey = `file:${normalized.cid}`
+    if (!this.#shouldApplyUserSyncEntity(ownerAddress, entityKey, normalized.syncUpdatedAt)) {
+      return false
+    }
+
+    const publishedFiles = [...this.#getPublishedBucket(ownerAddress)]
+    const trashFiles = [...this.#getTrashBucket(ownerAddress)]
+    let changed = false
+
+    const publishedIndex = publishedFiles.findIndex(
+      file => file.cid === normalized.cid
+    )
+    const trashIndex = trashFiles.findIndex(file => file.cid === normalized.cid)
+    const localHolding = this.#holdings.find(
+      holding => holding.cid === normalized.cid
+    )
+    const localSource = localHolding?.source || 'synced'
+
+    if (state === 'active') {
+      const nextRecord = {
+        fileName: normalized.fileName,
+        cid: normalized.cid,
+        driveName: normalized.driveName,
+        size: normalized.size,
+        source: localSource,
+        publishedAt: normalized.publishedAt,
+        starred: normalized.starred,
+        syncUpdatedAt: normalized.syncUpdatedAt,
+      }
+      if (publishedIndex === -1) {
+        publishedFiles.push(nextRecord)
+        changed = true
+      } else if (
+        JSON.stringify(publishedFiles[publishedIndex]) !==
+        JSON.stringify(nextRecord)
+      ) {
+        publishedFiles[publishedIndex] = nextRecord
+        changed = true
+      }
+      if (trashIndex !== -1) {
+        trashFiles.splice(trashIndex, 1)
+        changed = true
+      }
+    } else {
+      const nextRecord = {
+        fileName: normalized.fileName,
+        cid: normalized.cid,
+        driveName: normalized.driveName,
+        size: normalized.size,
+        source: localSource,
+        publishedAt: normalized.publishedAt,
+        starred: normalized.starred,
+        deletedAt: normalized.deletedAt || new Date(normalized.syncUpdatedAt).toISOString(),
+        syncUpdatedAt: normalized.syncUpdatedAt,
+      }
+      if (trashIndex === -1) {
+        trashFiles.push(nextRecord)
+        changed = true
+      } else if (
+        JSON.stringify(trashFiles[trashIndex]) !== JSON.stringify(nextRecord)
+      ) {
+        trashFiles[trashIndex] = nextRecord
+        changed = true
+      }
+      if (publishedIndex !== -1) {
+        publishedFiles.splice(publishedIndex, 1)
+        changed = true
+      }
+    }
+
+    if (changed) {
+      this.#setPublishedBucket(ownerAddress, publishedFiles)
+      this.#setTrashBucket(ownerAddress, trashFiles)
+      this.#setUserSyncClock(ownerAddress, entityKey, normalized.syncUpdatedAt)
+    }
+    return changed
+  }
+
+  async #applyUserSyncFileDelete(ownerAddress, cidInput, timestamp) {
+    const cid = String(cidInput || '').trim()
+    if (!cid) return false
+    const syncUpdatedAt = getSyncTimestamp(timestamp)
+    const entityKey = `file:${cid}`
+    if (!this.#shouldApplyUserSyncEntity(ownerAddress, entityKey, syncUpdatedAt)) {
+      return false
+    }
+
+    const publishedFiles = this.#getPublishedBucket(ownerAddress).filter(
+      file => file.cid !== cid
+    )
+    const trashFiles = this.#getTrashBucket(ownerAddress).filter(
+      file => file.cid !== cid
+    )
+    const changed =
+      publishedFiles.length !== this.#getPublishedBucket(ownerAddress).length ||
+      trashFiles.length !== this.#getTrashBucket(ownerAddress).length
+    this.#setPublishedBucket(ownerAddress, publishedFiles)
+    this.#setTrashBucket(ownerAddress, trashFiles)
+    this.#setUserSyncClock(ownerAddress, entityKey, syncUpdatedAt)
+    if (changed && !this.#hasAnyUserReference(cid)) {
+      await this.#cleanupUnreferencedCids([cid])
+    }
+    return changed
+  }
+
+  async #applyUserSyncChannelRecord(ownerAddress, record, timestamp) {
+    if (!record || typeof record !== 'object') return false
+    const channelId = normalizeChannelId(record.channelId)
+    const fingerprint = String(record.fingerprint || '').trim()
+    const expectedChannelKey =
+      channelId && fingerprint ? buildChannelKey(channelId, fingerprint) : ''
+    const recordChannelKey = normalizeChannelKey(record.channelKey)
+    if (recordChannelKey && recordChannelKey !== expectedChannelKey) {
+      return false
+    }
+    const channelKey = recordChannelKey || expectedChannelKey
+    if (!channelId || !fingerprint || !channelKey) return false
+    const syncUpdatedAt = getSyncTimestamp(record.syncUpdatedAt, timestamp)
+    const entityKey = `channel:${channelKey}`
+    if (!this.#shouldApplyUserSyncEntity(ownerAddress, entityKey, syncUpdatedAt)) {
+      return false
+    }
+
+    let channel = this.#channels.find(item => item.channelKey === channelKey)
+    let changed = false
+    if (!channel) {
+      channel = {
+        channelId,
+        fingerprint,
+        channelKey,
+        name: channelId,
+        createdAt:
+          typeof record.createdAt === 'string'
+            ? record.createdAt
+            : new Date(syncUpdatedAt).toISOString(),
+        lastMessageAt:
+          typeof record.lastMessageAt === 'string' ? record.lastMessageAt : '',
+        type: String(record.type || 'personal').trim() || 'personal',
+        writerId: createChannelWriterId(),
+        localWriterCoreKey: '',
+        writerCoreKeys: uniqueStrings(record.writerCoreKeys),
+        members: [],
+        syncUpdatedAt,
+      }
+      this.#channels.push(channel)
+      changed = true
+    } else {
+      const nextKeys = uniqueStrings([
+        ...(channel.writerCoreKeys || []),
+        ...(record.writerCoreKeys || []),
+      ])
+      if (nextKeys.length !== (channel.writerCoreKeys || []).length) {
+        channel.writerCoreKeys = nextKeys
+        changed = true
+      }
+      if (record.lastMessageAt && record.lastMessageAt !== channel.lastMessageAt) {
+        channel.lastMessageAt = record.lastMessageAt
+        changed = true
       }
+      channel.syncUpdatedAt = syncUpdatedAt
+    }
 
+    if (
       this.#upsertChannelMember(channel, {
-        ownerAddress: normalizedOwner,
-        displayName: imported.member?.displayName || imported.member?.name || '',
-        avatar: imported.member?.avatar || '',
+        ownerAddress,
+        displayName:
+          record.member?.displayName || record.remark || '',
+        avatar: record.member?.avatar || '',
+      })
+    ) {
+      changed = true
+    }
+    if (record.remark !== undefined) {
+      channel.remarks = channel.remarks || {}
+      const remark = String(record.remark || '').slice(0, 50)
+      if (remark) channel.remarks[ownerAddress] = remark
+      else delete channel.remarks[ownerAddress]
+      changed = true
+    }
+    channel.pinnedBy = channel.pinnedBy || {}
+    if (record.pinned) {
+      channel.pinnedBy[ownerAddress] = true
+    } else {
+      delete channel.pinnedBy[ownerAddress]
+    }
+    this.#setUserSyncClock(ownerAddress, entityKey, syncUpdatedAt)
+
+    if (!this.#channelLocalCoreKey.get(channel.channelKey)) {
+      await this.#openChannelRuntime(channel)
+      await this.#joinChannelDiscoveryTopics(channel)
+      changed = true
+      this.emit('channel:joined', {
+        channel: channel.channelKey,
+        channelKey: channel.channelKey,
+        channelId: channel.channelId,
+        key: channel.channelKey,
       })
+    }
+    return changed
+  }
 
-      if (imported.remark) {
-        channel.remarks = channel.remarks || {}
-        channel.remarks[normalizedOwner] = imported.remark
+  #applyUserSyncChannelLeave(ownerAddress, channelKeyInput, timestamp) {
+    const channelKey = normalizeChannelKey(channelKeyInput)
+    if (!channelKey) return false
+    const syncUpdatedAt = getSyncTimestamp(timestamp)
+    const entityKey = `channel:${channelKey}`
+    if (!this.#shouldApplyUserSyncEntity(ownerAddress, entityKey, syncUpdatedAt)) {
+      return false
+    }
+    const channel = this.#channels.find(item => item.channelKey === channelKey)
+    if (!channel) {
+      this.#setUserSyncClock(ownerAddress, entityKey, syncUpdatedAt)
+      return false
+    }
+    const before = channel.members?.length || 0
+    channel.members = (channel.members || []).filter(
+      member => normalizeOwnerAddress(member?.address) !== ownerAddress
+    )
+    if (channel.remarks) delete channel.remarks[ownerAddress]
+    if (channel.pinnedBy) delete channel.pinnedBy[ownerAddress]
+    this.#setUserSyncClock(ownerAddress, entityKey, syncUpdatedAt)
+    const changed = before !== channel.members.length
+    if (channel.members.length === 0) {
+      this.#channels = this.#channels.filter(item => item.channelKey !== channelKey)
+    }
+    if (changed) {
+      this.emit('channel:left', {
+        channel: channelKey,
+        channelKey,
+        channelId: channel.channelId,
+        name: channel.channelId,
+      })
+    }
+    return changed
+  }
+
+  #getUserSyncClock(ownerAddress, entityKey) {
+    const owner = normalizeOwnerAddress(ownerAddress)
+    return Number(this.#userSyncMetadata.clocks?.[owner]?.[entityKey]) || 0
+  }
+
+  #setUserSyncClock(ownerAddress, entityKey, timestamp) {
+    const owner = normalizeOwnerAddress(ownerAddress)
+    if (!owner || !entityKey) return
+    this.#userSyncMetadata.clocks = this.#userSyncMetadata.clocks || {}
+    this.#userSyncMetadata.clocks[owner] =
+      this.#userSyncMetadata.clocks[owner] || {}
+    this.#userSyncMetadata.clocks[owner][entityKey] = Math.max(
+      this.#getUserSyncClock(owner, entityKey),
+      getSyncTimestamp(timestamp)
+    )
+    this.#saveUserSyncMetadata()
+  }
+
+  #shouldApplyUserSyncEntity(ownerAddress, entityKey, timestamp) {
+    return getSyncTimestamp(timestamp) > this.#getUserSyncClock(ownerAddress, entityKey)
+  }
+
+  #markUserSyncClockForOp(op) {
+    const ownerAddress = normalizeOwnerAddress(op.ownerAddress)
+    if (!ownerAddress) return
+    if (op.kind === 'file:upsert' || op.kind === 'file:trash') {
+      const cid = op.payload?.file?.cid
+      const timestamp = getSyncTimestamp(
+        op.payload?.file?.syncUpdatedAt,
+        op.timestamp
+      )
+      if (cid) this.#setUserSyncClock(ownerAddress, `file:${cid}`, timestamp)
+    } else if (op.kind === 'file:delete') {
+      const cid = op.payload?.cid
+      const timestamp = getSyncTimestamp(
+        op.payload?.syncUpdatedAt,
+        op.timestamp
+      )
+      if (cid) this.#setUserSyncClock(ownerAddress, `file:${cid}`, timestamp)
+    } else if (op.kind === 'channel:upsert') {
+      const channelKey = op.payload?.channel?.channelKey
+      const timestamp = getSyncTimestamp(
+        op.payload?.channel?.syncUpdatedAt,
+        op.timestamp
+      )
+      if (channelKey) {
+        this.#setUserSyncClock(ownerAddress, `channel:${channelKey}`, timestamp)
       }
-      if (imported.pinned) {
-        channel.pinnedBy = channel.pinnedBy || {}
-        channel.pinnedBy[normalizedOwner] = true
+    } else if (op.kind === 'channel:leave') {
+      const channelKey = op.payload?.channelKey
+      const timestamp = getSyncTimestamp(
+        op.payload?.syncUpdatedAt,
+        op.timestamp
+      )
+      if (channelKey) {
+        this.#setUserSyncClock(ownerAddress, `channel:${channelKey}`, timestamp)
       }
     }
   }
 
+  #persistUserSyncSession(session) {
+    this.#userSyncMetadata.sessions = this.#userSyncMetadata.sessions || {}
+    this.#userSyncMetadata.sessions[session.ownerAddress] = {
+      ownerAddress: session.ownerAddress,
+      syncId: session.syncId,
+      syncName: session.syncName,
+      writerId: session.writerId,
+      localWriterCoreKey: session.localWriterCoreKey,
+      writerCoreKeys: uniqueStrings(session.writerCoreKeys),
+      startedAt: session.startedAt,
+      lastSyncedAt:
+        this.#userSyncMetadata.sessions?.[session.ownerAddress]?.lastSyncedAt ||
+        '',
+      updatedAt: new Date().toISOString(),
+    }
+    this.#saveUserSyncMetadata()
+  }
+
+  #touchUserSyncSession(session) {
+    this.#persistUserSyncSession(session)
+    const persisted = this.#userSyncMetadata.sessions?.[session.ownerAddress]
+    if (persisted) {
+      persisted.lastSyncedAt = new Date().toISOString()
+      this.#saveUserSyncMetadata()
+    }
+  }
+
   #getFileRuntimeStats(cid) {
     const state = this.#fileMonitors.get(cid)
     if (!state) {
@@ -3549,6 +4494,10 @@ export class MostBoxEngine extends EventEmitter {
     return path.join(this.#options.dataPath, 'trash-files.json')
   }
 
+  #getUserSyncMetadataPath() {
+    return path.join(this.#options.dataPath, 'user-sync.json')
+  }
+
   #atomicWrite(filePath, data) {
     const tmpPath = filePath + '.tmp'
     fs.writeFileSync(tmpPath, data, 'utf-8')
@@ -3641,6 +4590,65 @@ export class MostBoxEngine extends EventEmitter {
     }
   }
 
+  #loadUserSyncMetadata() {
+    try {
+      const metadataPath = this.#getUserSyncMetadataPath()
+      if (fs.existsSync(metadataPath)) {
+        const parsed = JSON.parse(fs.readFileSync(metadataPath, 'utf-8'))
+        const sessions = {}
+        for (const [owner, session] of Object.entries(parsed.sessions || {})) {
+          const ownerAddress = normalizeOwnerAddress(owner)
+          const syncId = String(session?.syncId || '').trim()
+          if (!ownerAddress || !syncId) continue
+          sessions[ownerAddress] = {
+            ownerAddress,
+            syncId,
+            syncName: String(session.syncName || getUserSyncName(syncId)),
+            writerId: String(session.writerId || ''),
+            localWriterCoreKey: String(session.localWriterCoreKey || ''),
+            writerCoreKeys: uniqueStrings(session.writerCoreKeys),
+            startedAt: String(session.startedAt || ''),
+            lastSyncedAt: String(session.lastSyncedAt || ''),
+            updatedAt: String(session.updatedAt || ''),
+          }
+        }
+
+        const clocks = {}
+        for (const [owner, records] of Object.entries(parsed.clocks || {})) {
+          const ownerAddress = normalizeOwnerAddress(owner)
+          if (!ownerAddress || !records || typeof records !== 'object') continue
+          clocks[ownerAddress] = {}
+          for (const [entityKey, timestamp] of Object.entries(records)) {
+            const value = Number(timestamp)
+            if (entityKey && Number.isFinite(value) && value > 0) {
+              clocks[ownerAddress][entityKey] = value
+            }
+          }
+        }
+
+        return { sessions, clocks }
+      }
+    } catch (err) {
+      console.warn(
+        'Failed to load user sync metadata, using empty state:',
+        err.message
+      )
+    }
+    return { sessions: {}, clocks: {} }
+  }
+
+  #saveUserSyncMetadata() {
+    try {
+      const metadataPath = this.#getUserSyncMetadataPath()
+      this.#atomicWrite(
+        metadataPath,
+        JSON.stringify(this.#userSyncMetadata, null, 2)
+      )
+    } catch (err) {
+      console.error('Failed to save user sync metadata:', err.message)
+    }
+  }
+
   #getChannelsMetadataPath() {
     return path.join(this.#options.dataPath, 'channels.json')
   }
@@ -3654,7 +4662,37 @@ export class MostBoxEngine extends EventEmitter {
       const metadataPath = this.#getChannelsMetadataPath()
       if (fs.existsSync(metadataPath)) {
         const data = fs.readFileSync(metadataPath, 'utf-8')
-        return JSON.parse(data)
+        const channels = JSON.parse(data)
+        if (!Array.isArray(channels)) return []
+        return channels
+          .filter(channel => channel && typeof channel === 'object')
+          .map(channel => {
+            const channelId = normalizeChannelId(channel.channelId)
+            const fingerprint = String(channel.fingerprint || '').trim()
+            const expectedChannelKey =
+              channelId && fingerprint
+                ? buildChannelKey(channelId, fingerprint)
+                : ''
+            const channelKey = normalizeChannelKey(channel.channelKey)
+            return {
+              ...channel,
+              channelId,
+              fingerprint,
+              channelKey,
+              expectedChannelKey,
+              name: channelId,
+              writerCoreKeys: uniqueStrings(channel.writerCoreKeys),
+            }
+          })
+          .filter(
+            channel =>
+              CHANNEL_NAME_REGEX.test(channel.channelId) &&
+              channel.fingerprint &&
+              channel.channelKey === channel.expectedChannelKey &&
+              channel.writerId &&
+              channel.localWriterCoreKey
+          )
+          .map(({ expectedChannelKey: _expectedChannelKey, ...channel }) => channel)
       }
     } catch (err) {
       console.warn(
@@ -3668,9 +4706,23 @@ export class MostBoxEngine extends EventEmitter {
   #saveChannelsMetadata() {
     try {
       const metadataPath = this.#getChannelsMetadataPath()
-      const persistentChannels = this.#channels.filter(
-        channel => !TRANSIENT_CHANNEL_TYPES.has(channel?.type)
-      )
+      const persistentChannels = this.#channels
+        .filter(channel => !TRANSIENT_CHANNEL_TYPES.has(channel?.type))
+        .map(channel => ({
+          channelId: channel.channelId,
+          fingerprint: channel.fingerprint,
+          channelKey: channel.channelKey,
+          name: channel.channelId,
+          type: channel.type,
+          createdAt: channel.createdAt,
+          lastMessageAt: channel.lastMessageAt || '',
+          writerId: channel.writerId,
+          localWriterCoreKey: channel.localWriterCoreKey,
+          writerCoreKeys: uniqueStrings(channel.writerCoreKeys),
+          members: Array.isArray(channel.members) ? channel.members : [],
+          remarks: channel.remarks,
+          pinnedBy: channel.pinnedBy,
+        }))
       this.#atomicWrite(
         metadataPath,
         JSON.stringify(persistentChannels, null, 2)
@@ -3680,23 +4732,39 @@ export class MostBoxEngine extends EventEmitter {
     }
   }
 
-  #generateChannelDiscoveryKey(name) {
+  #generateChannelDiscoveryKey(channelKey) {
     const hash = crypto
       .createHash('sha256')
-      .update(`${CHANNEL_NAME_PREFIX}${name}`)
+      .update(`${CHANNEL_NAME_PREFIX}channel:${channelKey}`)
       .digest()
     return hash
   }
 
-  #generateChannelChatDiscoveryKey(name) {
+  #generateChannelChatDiscoveryKey(channelKey) {
     const hash = crypto
       .createHash('sha256')
-      .update(`${CHANNEL_NAME_PREFIX}${name}:chat`)
+      .update(`${CHANNEL_NAME_PREFIX}channel:${channelKey}:chat`)
       .digest()
     return hash
   }
 
-  #setupChannelAppendListener(core, channelName) {
+  #generateChannelIdDiscoveryKey(channelId) {
+    const hash = crypto
+      .createHash('sha256')
+      .update(`${CHANNEL_NAME_PREFIX}id:${channelId}:candidates`)
+      .digest()
+    return hash
+  }
+
+  #generateUserSyncDiscoveryKey(syncId) {
+    const hash = crypto
+      .createHash('sha256')
+      .update(`${CHANNEL_NAME_PREFIX}${USER_SYNC_NAMESPACE_PREFIX}${syncId}`)
+      .digest()
+    return hash
+  }
+
+  #setupChannelAppendListener(core, channelKey) {
     let lastCoreLength = core.length
     core.on('append', async () => {
       if (core.length > lastCoreLength) {
@@ -3704,7 +4772,9 @@ export class MostBoxEngine extends EventEmitter {
           try {
             const entry = await core.get(i)
             if (entry && entry.type === 'message') {
-              const channel = this.#channels.find(c => c.name === channelName)
+              const channel = this.#channels.find(
+                c => c.channelKey === channelKey
+              )
               if (channel) {
                 const entryTime = Number(entry.timestamp) || Date.now()
                 const currentTime = Date.parse(channel.lastMessageAt || '') || 0
@@ -3714,16 +4784,18 @@ export class MostBoxEngine extends EventEmitter {
                 }
               }
               this.emit('channel:message', {
-                channel: channelName,
+                channel: channelKey,
+                channelKey,
+                channelId: channel?.channelId || '',
                 message: this.#normalizeChannelMessageForResponse(
-                  channelName,
+                  channelKey,
                   entry
                 ),
               })
             }
           } catch (err) {
             console.error(
-              `[MostBox] Failed to read channel message from ${channelName}:`,
+              `[MostBox] Failed to read channel message from ${channelKey}:`,
               err.message
             )
             continue
@@ -3734,13 +4806,13 @@ export class MostBoxEngine extends EventEmitter {
     })
   }
 
-  async #openRemoteChannelCore(channelName, coreKeyHex) {
-    const coresMap = this.#channelCores.get(channelName)
+  async #openRemoteChannelCore(channelKey, coreKeyHex) {
+    const coresMap = this.#channelCores.get(channelKey)
     if (!coresMap) return
     if (coresMap.has(coreKeyHex)) return
 
     try {
-      const ns = this.#store.namespace(`channel-${channelName}`)
+      const ns = this.#store.namespace(`channel-${channelKey}`)
       const core = ns.get({
         key: b4a.from(coreKeyHex, 'hex'),
         valueEncoding: 'json',
@@ -3748,23 +4820,21 @@ export class MostBoxEngine extends EventEmitter {
       await core.ready()
       const normalizedCoreKey = b4a.toString(core.key, 'hex')
       coresMap.set(normalizedCoreKey, core)
-      this.#setupChannelAppendListener(core, channelName)
-      const channel = this.#channels.find(c => c.name === channelName)
-      if (channel && normalizedCoreKey !== channel.coreKey) {
-        if (!Array.isArray(channel.remoteCoreKeys)) {
-          channel.remoteCoreKeys = []
-        }
-        if (!channel.remoteCoreKeys.includes(normalizedCoreKey)) {
-          channel.remoteCoreKeys.push(normalizedCoreKey)
-          this.#saveChannelsMetadata()
-        }
+      this.#setupChannelAppendListener(core, channelKey)
+      const channel = this.#channels.find(c => c.channelKey === channelKey)
+      if (channel && !channel.writerCoreKeys?.includes(normalizedCoreKey)) {
+        channel.writerCoreKeys = uniqueStrings([
+          ...(channel.writerCoreKeys || []),
+          normalizedCoreKey,
+        ])
+        this.#saveChannelsMetadata()
       }
       console.log(
-        `[MostBox] Opened remote channel core ${normalizedCoreKey.slice(0, 8)}... for ${channelName}`
+        `[MostBox] Opened remote channel core ${normalizedCoreKey.slice(0, 8)}... for ${channelKey}`
       )
     } catch (err) {
       console.warn(
-        `[MostBox] Failed to open remote channel core for ${channelName}:`,
+        `[MostBox] Failed to open remote channel core for ${channelKey}:`,
         err.message
       )
     }
@@ -3774,17 +4844,33 @@ export class MostBoxEngine extends EventEmitter {
     const stream = conn
     let connectedPeerId = null
 
-    const coreKeys = {}
-    for (const [name, localKeyHex] of this.#channelLocalCoreKey) {
-      coreKeys[name] = localKeyHex
-    }
+    const channels = this.#channels.map(channel => ({
+      channelId: channel.channelId,
+      fingerprint: channel.fingerprint,
+      channelKey: channel.channelKey,
+      type: channel.type,
+      createdAt: channel.createdAt,
+      lastMessageAt: channel.lastMessageAt || '',
+      writerCoreKeys: uniqueStrings([
+        ...(channel.writerCoreKeys || []),
+        this.#channelLocalCoreKey.get(channel.channelKey),
+      ]),
+    }))
+    const userSyncSessions = [...this.#userSyncSessions.values()].map(
+      session => ({
+        ownerAddress: session.ownerAddress,
+        syncId: session.syncId,
+        syncName: session.syncName,
+        writerCoreKeys: uniqueStrings(session.writerCoreKeys),
+      })
+    )
 
     const helloMessage = JSON.stringify({
       type: 'channel-hello',
       peerId: this.getNodeId(),
       authorName: this.getNodeId().slice(0, 4),
-      channels: this.#channels.map(c => c.name),
-      coreKeys,
+      channels,
+      userSyncSessions,
     })
 
     try {
@@ -3799,27 +4885,91 @@ export class MostBoxEngine extends EventEmitter {
         if (msg.type === 'channel-hello') {
           connectedPeerId = msg.peerId
 
-          const theirChannels = new Set(msg.channels || [])
-          for (const [name, peers] of this.#channelPeers) {
-            if (theirChannels.has(name)) {
+          const remoteChannels = Array.isArray(msg.channels)
+            ? msg.channels
+                .filter(channel => channel && typeof channel === 'object')
+                .map(channel => ({
+                  channelId: normalizeChannelId(channel.channelId),
+                  fingerprint: String(channel.fingerprint || '').trim(),
+                  channelKey: normalizeChannelKey(channel.channelKey),
+                  type: String(channel.type || 'public').trim() || 'public',
+                  createdAt:
+                    typeof channel.createdAt === 'string'
+                      ? channel.createdAt
+                      : '',
+                  lastMessageAt:
+                    typeof channel.lastMessageAt === 'string'
+                      ? channel.lastMessageAt
+                      : '',
+                  writerCoreKeys: uniqueStrings(channel.writerCoreKeys),
+                }))
+                .filter(
+                  channel =>
+                    channel.channelId &&
+                    channel.fingerprint &&
+                    channel.channelKey
+                )
+            : []
+
+          for (const remoteChannel of remoteChannels) {
+            this.#cacheChannelCandidate({
+              ...remoteChannel,
+              local: false,
+              peerId: msg.peerId,
+              onlineCount: 1,
+            })
+
+            const localChannel = this.#channels.find(
+              channel => channel.channelKey === remoteChannel.channelKey
+            )
+            if (!localChannel) continue
+
+            const peers = this.#channelPeers.get(localChannel.channelKey)
+            if (peers) {
               peers.set(msg.peerId, {
                 peerId: msg.peerId,
                 authorName: msg.authorName,
                 lastSeen: Date.now(),
               })
             }
-          }
 
-          if (msg.coreKeys && typeof msg.coreKeys === 'object') {
-            for (const [channelName, coreKeyHex] of Object.entries(
-              msg.coreKeys
-            )) {
-              if (this.#channelCores.has(channelName) && coreKeyHex) {
-                await this.#openRemoteChannelCore(channelName, coreKeyHex)
+            for (const writerCoreKey of remoteChannel.writerCoreKeys) {
+              if (
+                writerCoreKey &&
+                writerCoreKey !== this.#channelLocalCoreKey.get(localChannel.channelKey)
+              ) {
+                await this.#openRemoteChannelCore(
+                  localChannel.channelKey,
+                  writerCoreKey
+                )
               }
             }
           }
 
+          const remoteUserSyncSessions = Array.isArray(msg.userSyncSessions)
+            ? msg.userSyncSessions
+                .filter(session => session && typeof session === 'object')
+                .map(session => ({
+                  ownerAddress: normalizeOwnerAddress(session.ownerAddress),
+                  syncId: String(session.syncId || '').trim(),
+                  writerCoreKeys: uniqueStrings(session.writerCoreKeys),
+                }))
+                .filter(session => session.ownerAddress && session.syncId)
+            : []
+
+          for (const remoteSession of remoteUserSyncSessions) {
+            const localSession = this.#userSyncSessions.get(
+              remoteSession.ownerAddress
+            )
+            if (!localSession || localSession.syncId !== remoteSession.syncId) {
+              continue
+            }
+            await this.#mergeUserSyncWriterCoreKeys(
+              localSession,
+              remoteSession.writerCoreKeys
+            )
+          }
+
           this.emit('channel:peer:online', {
             peerId: msg.peerId,
             authorName: msg.authorName,