most-box 0.1.0 → 0.1.2

package/server/src/index.js

@@ -14,11 +14,12 @@ import Corestore from 'corestore'
 import Hyperdrive from 'hyperdrive'
 import b4a from 'b4a'
 import crypto from 'node:crypto'
-import { CID } from 'multiformats/cid'
 import fs from 'node:fs'
 import path from 'node:path'
 
 import { calculateCid, parseMostLink } from './core/cid.js'
+import { normalizeChannelAttachment } from './core/channelAttachment.js'
+import { getCidInfo } from './core/cidTopic.js'
 import {
   sanitizeFilename,
   validateAndSanitizePath,
@@ -33,6 +34,8 @@ import {
   PeerNotFoundError,
   IntegrityError,
   PermissionError,
+  ConflictError,
+  StorageCapacityError,
   EngineNotInitializedError,
 } from './utils/errors.js'
 import {
@@ -51,6 +54,8 @@ import {
   DOWNLOAD_POLL_INTERVAL_MIN,
   DOWNLOAD_POLL_INTERVAL_MAX,
   DRIVE_UPDATE_INTERVAL,
+  HOLDING_REJOIN_BATCH_SIZE,
+  HOLDING_REJOIN_BATCH_DELAY,
   PROGRESS_THROTTLE,
   DEFAULT_READ_LIMIT,
   CHANNEL_NAME_MIN_LENGTH,
@@ -61,19 +66,51 @@ import {
   MAX_MESSAGE_LENGTH,
 } from './config.js'
 
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
+
+function normalizeOwnerAddress(address) {
+  const value = String(address || '').trim()
+  return /^0x[a-fA-F0-9]{40}$/.test(value) ? value.toLowerCase() : ''
+}
+
+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
   #swarm = null
   #drives = new Map()
   #publishedFiles = []
+  #holdings = []
   #trashFiles = []
   #initialized = false
   #options = null
   #activeDownloads = new Map()
   #drivePromises = new Map()
+  #fileDiscoveries = new Map()
+  #fileMonitors = new Map()
+  #seedStates = new Map()
+  #holdingResumeTask = null
 
   #channels = []
   #channelCores = new Map()
+  #channelLocalCoreKey = new Map()
   #channelDiscoveries = new Map()
   #channelChatDiscoveries = new Map()
   #channelPeers = new Map()
@@ -85,7 +122,9 @@ export class MostBoxEngine extends EventEmitter {
    * @param {object} options - 配置选项
    * @param {string} options.dataPath - 存储 P2P 数据的路径（必填）
    * @param {string} [options.downloadPath] - 默认下载路径（可选，默认为 dataPath/downloads）
-   * @param {number} [options.maxFileSize] - 最大文件大小（字节）（默认：100GB）
+   * @param {number} [options.maxFileSize] - 最大文件大小（字节）（默认：10GB）
+   * @param {number} [options.capacityBytes] - 节点存储容量上限（字节）（默认：100GB）
+   * @param {boolean} [options.disableNetwork] - 测试用：跳过真实 Hyperswarm 网络
    */
   constructor(options) {
     super()
@@ -99,6 +138,9 @@ export class MostBoxEngine extends EventEmitter {
       downloadPath:
         options.downloadPath || path.join(options.dataPath, 'downloads'),
       maxFileSize: options.maxFileSize || MAX_FILE_SIZE,
+      capacityBytes: options.capacityBytes || 100 * 1024 * 1024 * 1024,
+      downloadTimeout: options.downloadTimeout || DOWNLOAD_TIMEOUT,
+      disableNetwork: options.disableNetwork === true,
     }
   }
 
@@ -157,14 +199,19 @@ export class MostBoxEngine extends EventEmitter {
     }
 
     console.log(`[MostBox] Initializing Hyperswarm...`)
-    this.#swarm = new Hyperswarm({
-      maxPeers: MAX_PEERS,
-      bootstrap: SWARM_BOOTSTRAP,
-      firewall: () => false,
-      connectionKeepAlive: SWARM_KEEP_ALIVE_INTERVAL,
-      randomPunchInterval: SWARM_RANDOM_PUNCH_INTERVAL,
-      handshakeTimeout: CONNECTION_TIMEOUT,
-    })
+    if (this.#options.disableNetwork) {
+      this.#swarm = createOfflineSwarm()
+      this.#chatSwarm = createOfflineSwarm()
+    } else {
+      this.#swarm = new Hyperswarm({
+        maxPeers: MAX_PEERS,
+        bootstrap: SWARM_BOOTSTRAP,
+        firewall: () => false,
+        connectionKeepAlive: SWARM_KEEP_ALIVE_INTERVAL,
+        randomPunchInterval: SWARM_RANDOM_PUNCH_INTERVAL,
+        handshakeTimeout: CONNECTION_TIMEOUT,
+      })
+    }
 
     this.#swarm.on('error', err => {
       if (
@@ -190,14 +237,16 @@ export class MostBoxEngine extends EventEmitter {
       this.emit('connection', conn)
     })
 
-    this.#chatSwarm = new Hyperswarm({
-      maxPeers: MAX_PEERS,
-      bootstrap: SWARM_BOOTSTRAP,
-      firewall: () => false,
-      connectionKeepAlive: SWARM_KEEP_ALIVE_INTERVAL,
-      randomPunchInterval: SWARM_RANDOM_PUNCH_INTERVAL,
-      handshakeTimeout: CONNECTION_TIMEOUT,
-    })
+    if (!this.#options.disableNetwork) {
+      this.#chatSwarm = new Hyperswarm({
+        maxPeers: MAX_PEERS,
+        bootstrap: SWARM_BOOTSTRAP,
+        firewall: () => false,
+        connectionKeepAlive: SWARM_KEEP_ALIVE_INTERVAL,
+        randomPunchInterval: SWARM_RANDOM_PUNCH_INTERVAL,
+        handshakeTimeout: CONNECTION_TIMEOUT,
+      })
+    }
 
     this.#chatSwarm.on('error', err => {
       if (
@@ -230,6 +279,17 @@ export class MostBoxEngine extends EventEmitter {
       `[MostBox] Loaded ${this.#publishedFiles.length} published files`
     )
 
+    this.#holdings = this.#loadHoldingsMetadata()
+    console.log(`[MostBox] Loaded ${this.#holdings.length} node holdings`)
+
+    for (const holding of this.#holdings) {
+      this.#setSeedState(holding.cid, {
+        status: 'queued',
+        topic: holding.topic,
+        driveName: holding.driveName,
+      })
+    }
+
     this.#trashFiles = this.#loadTrashMetadata()
     console.log(`[MostBox] Loaded ${this.#trashFiles.length} trash files`)
 
@@ -244,9 +304,22 @@ export class MostBoxEngine extends EventEmitter {
           valueEncoding: 'json',
         })
         await core.ready()
-        this.#channelCores.set(channel.name, core)
+        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(
@@ -274,6 +347,7 @@ export class MostBoxEngine extends EventEmitter {
     this.#initialized = true
     console.log(`[MostBox] Engine initialized successfully`)
     this.emit('ready')
+    this.#resumeHoldingsInBackground()
 
     return this
   }
@@ -293,21 +367,15 @@ export class MostBoxEngine extends EventEmitter {
     }
     this.#activeDownloads.clear()
 
+    await Promise.allSettled(
+      [...this.#fileMonitors.values()].map(item => this.#closeFileMonitor(item))
+    )
+    this.#fileMonitors.clear()
     await Promise.allSettled([...this.#drives.values()].map(d => d.close()))
     this.#drives.clear()
-
-    for (const core of this.#channelCores.values()) {
-      try {
-        await core.close()
-      } catch (err) {
-        console.warn('[MostBox] Failed to close channel core:', err.message)
-      }
-    }
-    this.#channelCores.clear()
-    this.#channelDiscoveries.clear()
-    this.#channelChatDiscoveries.clear()
-    this.#channelPeers.clear()
-    this.#channels = []
+    this.#fileDiscoveries.clear()
+    this.#seedStates.clear()
+    this.#holdingResumeTask = null
 
     if (this.#swarm) {
       await this.#swarm.destroy()
@@ -319,6 +387,22 @@ export class MostBoxEngine extends EventEmitter {
       this.#chatSwarm = null
     }
 
+    for (const [, coresMap] of this.#channelCores) {
+      for (const [, core] of coresMap) {
+        try {
+          await core.close()
+        } catch (err) {
+          console.warn('[MostBox] Failed to close channel core:', err.message)
+        }
+      }
+    }
+    this.#channelCores.clear()
+    this.#channelLocalCoreKey.clear()
+    this.#channelDiscoveries.clear()
+    this.#channelChatDiscoveries.clear()
+    this.#channelPeers.clear()
+    this.#channels = []
+
     if (this.#store) {
       await this.#store.close()
       this.#store = null
@@ -359,10 +443,13 @@ export class MostBoxEngine extends EventEmitter {
    * Hyperdrive 中存储 key 为 '/' + cid，metadata 中存储 displayName（用户看到的路径）
    * @param {string|Buffer} content - 文件路径（字符串）或内容（Buffer）
    * @param {string} [fileName] - 文件名（Buffer 输入时必填）
+   * @param {object} [options] - 发布选项
+   * @param {string|null} [options.localPath] - 持有记录中的本地路径
    * @returns {Promise<{ cid: string, link: string, fileName: string }>}
    */
-  async publishFile(content, fileName) {
+  async publishFile(content, fileName, options = {}) {
     this.#ensureInitialized()
+    const ownerAddress = normalizeOwnerAddress(options.ownerAddress)
 
     let cleanPath = null
     let safeFileName
@@ -402,6 +489,8 @@ export class MostBoxEngine extends EventEmitter {
       )
     }
 
+    this.#checkCapacity(fileSize)
+
     this.emit('publish:progress', {
       stage: 'calculating-cid',
       file: safeFileName,
@@ -409,24 +498,37 @@ export class MostBoxEngine extends EventEmitter {
 
     const { cid: rootCid } = await calculateCid(content)
     const cidString = rootCid.toString()
+    const { driveName: name } = this.#getCidInfo(cidString)
+    const holdingLocalPath =
+      options.localPath === undefined ? cleanPath : options.localPath
 
     // 检查相同内容是否已存在
     const existingIndex = this.#publishedFiles.findIndex(
-      f => f.cid === cidString
+      f => f.cid === cidString && this.#recordMatchesOwner(f, ownerAddress)
     )
     if (existingIndex !== -1) {
       const existing = this.#publishedFiles[existingIndex]
+      await this.#joinCidTopicInternal(cidString, {
+        server: true,
+        client: false,
+      })
+      this.#upsertHolding({
+        cid: cidString,
+        fileName: existing.fileName,
+        size: fileSize,
+        localPath: holdingLocalPath,
+        driveName: name,
+        source: 'published',
+      })
       return {
         cid: cidString,
-        link: `most://${cidString}`,
+        link: `most://${cidString}?filename=${encodeURIComponent(existing.fileName)}`,
         fileName: existing.fileName,
         alreadyExists: true,
       }
     }
 
     // 获取或创建该 CID 对应的 drive
-    const hashHex = b4a.toString(rootCid.multihash.digest, 'hex')
-    const name = `drive-${hashHex}`
     let drive = this.#drives.get(name)
 
     if (!drive) {
@@ -434,12 +536,11 @@ export class MostBoxEngine extends EventEmitter {
         server: true,
         client: false,
       })
-      const discovery = this.#swarm.join(drive.discoveryKey, {
-        server: true,
-        client: false,
-      })
-      await discovery.flushed()
     }
+    await this.#joinCidTopicInternal(cidString, {
+      server: true,
+      client: false,
+    })
 
     this.emit('publish:progress', { stage: 'uploading', file: safeFileName })
 
@@ -488,8 +589,17 @@ export class MostBoxEngine extends EventEmitter {
       driveName: name,
       publishedAt: new Date().toISOString(),
       starred: false,
+      ownerAddress,
     })
     this.#savePublishedMetadata()
+    this.#upsertHolding({
+      cid: cidString,
+      fileName: safeFileName,
+      size: fileSize,
+      localPath: holdingLocalPath,
+      driveName: name,
+      source: 'published',
+    })
 
     const result = {
       cid: cidString,
@@ -505,13 +615,19 @@ export class MostBoxEngine extends EventEmitter {
    * 从 P2P 网络下载文件
    * @param {string} link - most:// 链接
    * @param {string} [taskId] - 用于取消的任务 ID
+   * @param {object} [options] - 下载选项
+   * @param {number} [options.timeout] - 等待 P2P 内容的超时时间（毫秒）
+   * @param {number} [options.streamReadTimeout] - 下载流无进度超时时间（毫秒）
    * @returns {Promise<{ taskId: string, fileName: string, savedPath: string, alreadyExists?: boolean }>}
    */
-  async downloadFile(link, taskId = null) {
+  async downloadFile(link, taskId = null, options = {}) {
     this.#ensureInitialized()
+    const ownerAddress = normalizeOwnerAddress(options.ownerAddress)
 
     taskId =
       taskId || `dl_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`
+    const downloadTimeout = options.timeout || this.#options.downloadTimeout
+    const streamReadTimeout = options.streamReadTimeout ?? STREAM_READ_TIMEOUT
 
     console.log(
       `[MostBox] Starting download for link: ${link} (taskId: ${taskId})`
@@ -527,10 +643,32 @@ export class MostBoxEngine extends EventEmitter {
       }
       const cidString = parsed.cid
       console.log(`[MostBox] Parsed CID: ${cidString}`)
+      const { driveName: name } = this.#getCidInfo(cidString)
 
-      const existingFile = this.#publishedFiles.find(f => f.cid === cidString)
+      const existingFile = this.#publishedFiles.find(
+        f => f.cid === cidString && this.#recordMatchesOwner(f, ownerAddress)
+      )
       if (existingFile) {
         console.log(`[MostBox] File already exists: ${existingFile.fileName}`)
+        const existingHolding = this.#holdings.find(
+          item => item.cid === cidString
+        )
+        const existingSize = Number(existingFile.size)
+        await this.#joinCidTopicInternal(cidString, {
+          server: true,
+          client: false,
+        })
+        this.#upsertHolding({
+          cid: cidString,
+          fileName: existingFile.fileName,
+          size:
+            existingHolding?.size ??
+            (Number.isFinite(existingSize) ? existingSize : 0),
+          localPath:
+            existingHolding?.localPath || existingFile.localPath || null,
+          driveName: existingFile.driveName || name,
+          source: existingHolding?.source || 'published',
+        })
         return {
           taskId,
           fileName: existingFile.fileName,
@@ -540,12 +678,8 @@ export class MostBoxEngine extends EventEmitter {
 
       const linkFileName = parsed.fileName
 
-      const parsedCid = CID.parse(cidString)
-      const hashHex = b4a.toString(parsedCid.multihash.digest, 'hex')
-
       if (taskState.aborted) throw new Error('Download cancelled')
 
-      const name = `drive-${hashHex}`
       let drive = this.#drives.get(name)
 
       if (!drive) {
@@ -556,35 +690,35 @@ export class MostBoxEngine extends EventEmitter {
         })
 
         this.emit('download:status', { taskId, status: 'connecting' })
-
-        console.log(`[MostBox] Joining swarm for drive discovery...`)
-        await this.#swarm
-          .join(drive.discoveryKey, { server: true, client: true })
-          .flushed()
-        console.log(`[MostBox] Swarm join flushed`)
       } else {
         console.log(`[MostBox] Using existing drive: ${name}`)
       }
+      await this.#joinCidTopicInternal(cidString, {
+        server: false,
+        client: true,
+      })
 
       if (taskState.aborted) throw new Error('Download cancelled')
 
       this.emit('download:status', { taskId, status: 'finding-peers' })
 
       console.log(
-        `[MostBox] Waiting for drive content (timeout: ${DOWNLOAD_TIMEOUT / 1000}s)...`
+        `[MostBox] Waiting for drive entry /${cidString} (timeout: ${downloadTimeout / 1000}s)...`
       )
-      const entries = await this.#waitForDriveContent(
+      const driveKey = '/' + cidString
+      const entry = await this.#waitForDriveEntry(
         drive,
-        DOWNLOAD_TIMEOUT,
+        driveKey,
+        downloadTimeout,
         taskId,
         taskState
       )
 
-      if (entries.length === 0) {
-        console.log(`[MostBox] No entries found after timeout`)
+      if (!entry) {
+        console.log(`[MostBox] Expected drive entry ${driveKey} not found`)
 
         const peerCount = this.#swarm.connections.size
-        let errorMessage = 'No files found in drive. '
+        let errorMessage = `Expected file ${driveKey} was not found. `
 
         if (peerCount === 0) {
           errorMessage +=
@@ -606,10 +740,10 @@ export class MostBoxEngine extends EventEmitter {
       if (taskState.aborted) throw new Error('Download cancelled')
 
       console.log(
-        `[MostBox] Found ${entries.length} entries, starting download...`
+        `[MostBox] Found expected entry ${driveKey}, starting download...`
       )
 
-      const targetDir = this.#options.dataPath
+      const targetDir = this.#options.downloadPath
 
       const writableCheck = await checkDirectoryWritable(targetDir)
       if (!writableCheck.writable) {
@@ -617,6 +751,7 @@ export class MostBoxEngine extends EventEmitter {
       }
 
       // 下载文件
+      const entries = [entry]
       for (const entry of entries) {
         const cleanKey = entry.key.replace(/^[\/\\]/, '')
         const sanitizedFileName = linkFileName
@@ -633,7 +768,15 @@ export class MostBoxEngine extends EventEmitter {
           // 忽略
         }
 
+        if (totalBytes > 0) {
+          this.#checkCapacity(totalBytes)
+        }
+
         const savePath = path.join(targetDir, sanitizedFileName)
+        fs.mkdirSync(path.dirname(savePath), { recursive: true })
+        if (fs.existsSync(savePath)) {
+          throw new ConflictError(`已有同名文件: ${sanitizedFileName}`)
+        }
 
         this.emit('download:status', {
           taskId,
@@ -652,14 +795,54 @@ export class MostBoxEngine extends EventEmitter {
         let lastProgressUpdate = 0
 
         await new Promise((resolve, reject) => {
+          let settled = false
+          let readTimer = null
+
+          const clearReadTimer = () => {
+            if (readTimer) {
+              clearTimeout(readTimer)
+              readTimer = null
+            }
+          }
+
+          const fail = err => {
+            if (settled) return
+            settled = true
+            clearReadTimer()
+            rs.destroy(err)
+            ws.destroy()
+            fs.unlink(savePath, () => {})
+            reject(err)
+          }
+
+          const complete = () => {
+            if (settled) return
+            settled = true
+            clearReadTimer()
+            resolve()
+          }
+
+          const resetReadTimer = () => {
+            clearReadTimer()
+            if (streamReadTimeout > 0) {
+              readTimer = setTimeout(() => {
+                fail(
+                  new Error(
+                    `Download stalled: no data received for ${streamReadTimeout / 1000}s`
+                  )
+                )
+              }, streamReadTimeout)
+            }
+          }
+
+          resetReadTimer()
+
           rs.on('data', chunk => {
             if (taskState.aborted) {
-              rs.destroy()
-              ws.destroy()
-              fs.unlink(savePath, () => {})
-              reject(new Error('Download cancelled'))
+              fail(new Error('Download cancelled'))
               return
             }
+            resetReadTimer()
             loadedBytes += chunk.length
             const now = Date.now()
             if (
@@ -678,9 +861,19 @@ export class MostBoxEngine extends EventEmitter {
           })
 
           rs.pipe(ws)
-          ws.on('finish', resolve)
-          ws.on('error', reject)
-          rs.on('error', reject)
+          ws.on('finish', complete)
+          ws.on('error', fail)
+          rs.on('error', fail)
+          rs.on('close', () => {
+            if (taskState.aborted) {
+              fail(new Error('Download cancelled'))
+            }
+          })
+          ws.on('close', () => {
+            if (taskState.aborted) {
+              fail(new Error('Download cancelled'))
+            }
+          })
         })
 
         if (taskState.aborted) throw new Error('Download cancelled')
@@ -688,13 +881,12 @@ export class MostBoxEngine extends EventEmitter {
         this.emit('download:status', { taskId, status: 'verifying' })
 
         const { cid: downloadedCid } = await calculateCid(savePath)
-        const expectedHash = b4a.toString(parsedCid.multihash.digest, 'hex')
-        const actualHash = b4a.toString(downloadedCid.multihash.digest, 'hex')
+        const downloadedCidString = downloadedCid.toString()
 
-        if (expectedHash !== actualHash) {
+        if (downloadedCidString !== cidString) {
           fs.unlinkSync(savePath)
           throw new IntegrityError(
-            `File content CID mismatch. File may be corrupted or tampered.`
+            `File content CID mismatch. Expected ${cidString}, got ${downloadedCidString}.`
           )
         }
 
@@ -710,7 +902,17 @@ export class MostBoxEngine extends EventEmitter {
             writeStream.on('error', reject)
             readStream.on('error', reject)
           })
+          const verifyEntry = await drive.entry(driveKey)
+          if (!verifyEntry || !verifyEntry.value || !verifyEntry.value.blob) {
+            throw new IntegrityError(
+              `Failed to write file to Hyperdrive for seeding: ${driveKey}`
+            )
+          }
         }
+        await this.#joinCidTopicInternal(cidString, {
+          server: true,
+          client: false,
+        })
 
         const result = {
           taskId,
@@ -720,7 +922,7 @@ export class MostBoxEngine extends EventEmitter {
 
         // 将下载的文件添加到已发布文件列表（displayName 用原始文件名）
         const existingIndex = this.#publishedFiles.findIndex(
-          f => f.cid === cidString
+          f => f.cid === cidString && this.#recordMatchesOwner(f, ownerAddress)
         )
         if (existingIndex !== -1) {
           const existing = this.#publishedFiles[existingIndex]
@@ -735,9 +937,19 @@ export class MostBoxEngine extends EventEmitter {
             driveName: name,
             publishedAt: new Date().toISOString(),
             starred: false,
+            ownerAddress,
           })
         }
         this.#savePublishedMetadata()
+        const savedSize = totalBytes || fs.statSync(savePath).size
+        this.#upsertHolding({
+          cid: cidString,
+          fileName: sanitizedFileName,
+          size: savedSize,
+          localPath: savePath,
+          driveName: name,
+          source: 'downloaded',
+        })
 
         this.emit('download:success', result)
         return result
@@ -747,6 +959,84 @@ export class MostBoxEngine extends EventEmitter {
     }
   }
 
+  /**
+   * 检测 most:// 链接当前是否能找到可下载内容，但不读取文件内容。
+   * @param {string} link - most:// 链接
+   * @param {object} [options] - 检测选项
+   * @param {number} [options.timeout] - 等待 P2P 内容的超时时间（毫秒）
+   * @returns {Promise<{ available: boolean, cid: string, fileName: string, size: number|null, alreadyExists?: boolean }>}
+   */
+  async checkDownloadAvailability(link, options = {}) {
+    this.#ensureInitialized()
+    const ownerAddress = normalizeOwnerAddress(options.ownerAddress)
+
+    const timeout = options.timeout || DRIVE_ENTRY_TIMEOUT
+    const parsed = parseMostLink(link)
+    if (parsed.error) {
+      throw new ValidationError(parsed.error)
+    }
+
+    const cidString = parsed.cid
+    const { driveName: name } = this.#getCidInfo(cidString)
+    const existingFile = this.#publishedFiles.find(
+      f => f.cid === cidString && this.#recordMatchesOwner(f, ownerAddress)
+    )
+    if (existingFile) {
+      return {
+        available: true,
+        cid: cidString,
+        fileName: existingFile.fileName,
+        size: Number(existingFile.size) || null,
+        alreadyExists: true,
+      }
+    }
+
+    const writableCheck = await checkDirectoryWritable(
+      this.#options.downloadPath
+    )
+    if (!writableCheck.writable) {
+      throw new PermissionError(writableCheck.error)
+    }
+
+    let drive = this.#drives.get(name)
+
+    if (!drive) {
+      drive = await this.#getOrCreateDrive(name, {
+        server: true,
+        client: true,
+      })
+    }
+
+    await this.#joinCidTopicInternal(cidString, {
+      server: false,
+      client: true,
+    })
+
+    const driveKey = '/' + cidString
+    const entry = await this.#waitForDriveEntry(drive, driveKey, timeout)
+
+    if (!entry) {
+      throw new PeerNotFoundError(
+        '当前没有发现可下载的在线种子，请稍后重试或确认发布者在线'
+      )
+    }
+
+    let size = null
+    try {
+      const stat = await drive.entry(entry.key)
+      if (stat?.value?.blob) {
+        size = stat.value.blob.byteLength || 0
+      }
+    } catch {}
+
+    return {
+      available: true,
+      cid: cidString,
+      fileName: parsed.fileName,
+      size,
+    }
+  }
+
   /**
    * 列出所有已发布文件
    * @param {object} [options] - 筛选选项
@@ -756,6 +1046,11 @@ export class MostBoxEngine extends EventEmitter {
   listPublishedFiles(options = {}) {
     this.#ensureInitialized()
     let files = this.#publishedFiles
+    const ownerAddress = normalizeOwnerAddress(options.ownerAddress)
+
+    if (ownerAddress) {
+      files = files.filter(f => this.#recordMatchesOwner(f, ownerAddress))
+    }
 
     if (options.starred === true) {
       files = files.filter(f => f.starred === true)
@@ -764,9 +1059,10 @@ export class MostBoxEngine extends EventEmitter {
     return files.map(f => ({
       fileName: f.fileName,
       cid: f.cid,
-      link: `most://${f.cid}`,
+      link: `most://${f.cid}?filename=${encodeURIComponent(f.fileName)}`,
       publishedAt: f.publishedAt,
       starred: f.starred || false,
+      ownerAddress: f.ownerAddress || '',
     }))
   }
 
@@ -775,9 +1071,12 @@ export class MostBoxEngine extends EventEmitter {
    * @param {string} cid - 文件的 CID
    * @returns {object} 更新后的文件信息
    */
-  toggleStarred(cid) {
+  toggleStarred(cid, options = {}) {
     this.#ensureInitialized()
-    const index = this.#publishedFiles.findIndex(f => f.cid === cid)
+    const ownerAddress = normalizeOwnerAddress(options.ownerAddress)
+    const index = this.#publishedFiles.findIndex(
+      f => f.cid === cid && this.#recordMatchesOwner(f, ownerAddress)
+    )
     if (index === -1) {
       throw new Error('File not found')
     }
@@ -794,40 +1093,62 @@ export class MostBoxEngine extends EventEmitter {
    * @param {string} cid - 要删除文件的 CID
    * @returns {Promise<Array>} 更新后的已发布文件列表
    */
-  async deletePublishedFile(cid) {
+  async deletePublishedFile(cid, options = {}) {
     this.#ensureInitialized()
-    const index = this.#publishedFiles.findIndex(f => f.cid === cid)
+    const ownerAddress = normalizeOwnerAddress(options.ownerAddress)
+    const index = this.#publishedFiles.findIndex(
+      f => f.cid === cid && this.#recordMatchesOwner(f, ownerAddress)
+    )
     if (index !== -1) {
       const fileRecord = this.#publishedFiles[index]
+      const holding = this.#holdings.find(item => item.cid === fileRecord.cid)
 
       this.#trashFiles.push({
         fileName: fileRecord.fileName,
         cid: fileRecord.cid,
-        driveName: fileRecord.driveName,
+        driveName:
+          fileRecord.driveName || this.#getCidInfo(fileRecord.cid).driveName,
+        size: holding?.size ?? fileRecord.size ?? 0,
+        localPath: holding?.localPath || fileRecord.localPath || null,
+        source: holding?.source || 'published',
         publishedAt: fileRecord.publishedAt,
         starred: fileRecord.starred || false,
+        ownerAddress: fileRecord.ownerAddress || ownerAddress,
         deletedAt: new Date().toISOString(),
       })
       this.#saveTrashMetadata()
 
       this.#publishedFiles.splice(index, 1)
       this.#savePublishedMetadata()
+
+      if (!this.#hasPublishedReference(fileRecord.cid)) {
+        await this.#leaveCidTopic(fileRecord.cid)
+        await this.#closeDriveForSeed(
+          fileRecord.driveName || this.#getCidInfo(fileRecord.cid).driveName
+        )
+        this.#removeHolding(fileRecord.cid)
+      }
     }
-    return this.listPublishedFiles()
+    return this.listPublishedFiles({ ownerAddress })
   }
 
   /**
    * 列出回收站中的所有文件
    * @returns {Array} 回收站文件
    */
-  listTrashFiles() {
+  listTrashFiles(options = {}) {
     this.#ensureInitialized()
-    return this.#trashFiles.map(f => ({
+    const ownerAddress = normalizeOwnerAddress(options.ownerAddress)
+    const files = ownerAddress
+      ? this.#trashFiles.filter(f => this.#recordMatchesOwner(f, ownerAddress))
+      : this.#trashFiles
+    return files.map(f => ({
       fileName: f.fileName,
       cid: f.cid,
-      link: `most://${f.cid}`,
+      link: `most://${f.cid}?filename=${encodeURIComponent(f.fileName)}`,
       publishedAt: f.publishedAt,
       starred: f.starred || false,
+      ownerAddress: f.ownerAddress || '',
       deletedAt: f.deletedAt,
     }))
   }
@@ -835,20 +1156,21 @@ export class MostBoxEngine extends EventEmitter {
   /**
    * 从回收站恢复文件
    * @param {string} cid - 要恢复文件的 CID
-   * @returns {Array} 更新后的已发布文件列表
+   * @returns {Promise<Array>} 更新后的已发布文件列表
    */
-  restoreTrashFile(cid) {
+  async restoreTrashFile(cid, options = {}) {
     this.#ensureInitialized()
-    const index = this.#trashFiles.findIndex(f => f.cid === cid)
+    const ownerAddress = normalizeOwnerAddress(options.ownerAddress)
+    const index = this.#trashFiles.findIndex(
+      f => f.cid === cid && this.#recordMatchesOwner(f, ownerAddress)
+    )
     if (index === -1) {
       throw new Error('File not found in trash')
     }
 
     const fileRecord = this.#trashFiles[index]
 
-    const parsedCid = CID.parse(fileRecord.cid)
-    const hashHex = b4a.toString(parsedCid.multihash.digest, 'hex')
-    const driveName = `drive-${hashHex}`
+    const { driveName } = this.#getCidInfo(fileRecord.cid)
 
     this.#publishedFiles.push({
       fileName: fileRecord.fileName,
@@ -856,13 +1178,27 @@ export class MostBoxEngine extends EventEmitter {
       driveName,
       publishedAt: fileRecord.publishedAt,
       starred: fileRecord.starred || false,
+      ownerAddress: fileRecord.ownerAddress || ownerAddress,
     })
     this.#savePublishedMetadata()
 
     this.#trashFiles.splice(index, 1)
     this.#saveTrashMetadata()
 
-    return this.listPublishedFiles()
+    await this.#joinCidTopicInternal(fileRecord.cid, {
+      server: true,
+      client: false,
+    })
+    this.#upsertHolding({
+      cid: fileRecord.cid,
+      fileName: fileRecord.fileName,
+      size: Number(fileRecord.size) || 0,
+      localPath: fileRecord.localPath || null,
+      driveName,
+      source: fileRecord.source || 'published',
+    })
+
+    return this.listPublishedFiles({ ownerAddress })
   }
 
   /**
@@ -870,68 +1206,81 @@ export class MostBoxEngine extends EventEmitter {
    * @param {string} cid - 要永久删除文件的 CID
    * @returns {Promise<Array>} 更新后的回收站列表
    */
-  async permanentDeleteTrashFile(cid) {
+  async permanentDeleteTrashFile(cid, options = {}) {
     this.#ensureInitialized()
-    const index = this.#trashFiles.findIndex(f => f.cid === cid)
+    const ownerAddress = normalizeOwnerAddress(options.ownerAddress)
+    const index = this.#trashFiles.findIndex(
+      f => f.cid === cid && this.#recordMatchesOwner(f, ownerAddress)
+    )
     if (index !== -1) {
       const fileRecord = this.#trashFiles[index]
-      const driveName = fileRecord.driveName
+      const driveName =
+        fileRecord.driveName || this.#getCidInfo(fileRecord.cid).driveName
+
+      this.#trashFiles.splice(index, 1)
+      this.#saveTrashMetadata()
 
-      const drive = this.#drives.get(driveName)
-      if (drive) {
+      if (!this.#hasAnyUserReference(fileRecord.cid)) {
         try {
+          const drive = await this.#getOrCreateDrive(driveName)
           await drive.del('/' + fileRecord.cid)
         } catch {
           // 文件可能不存在于驱动器中
         }
-
-        await this.#swarm.leave(drive.discoveryKey)
-        await drive.close()
-        this.#drives.delete(driveName)
+        await this.#closeDriveForSeed(driveName)
+        await this.#leaveCidTopic(fileRecord.cid)
+        this.#removeHolding(fileRecord.cid)
       }
-
-      this.#trashFiles.splice(index, 1)
-      this.#saveTrashMetadata()
     }
-    return this.listTrashFiles()
+    return this.listTrashFiles({ ownerAddress })
   }
 
   /**
    * 清空回收站 — 永久删除所有回收站文件
    * @returns {Promise<Array>} 清空后的回收站列表
    */
-  async emptyTrash() {
+  async emptyTrash(options = {}) {
     this.#ensureInitialized()
+    const ownerAddress = normalizeOwnerAddress(options.ownerAddress)
+    const remainingTrash = []
+    const removedTrash = []
 
     for (const fileRecord of this.#trashFiles) {
-      const driveName = fileRecord.driveName
-
-      const drive = this.#drives.get(driveName)
-      if (drive) {
-        try {
-          await drive.del('/' + fileRecord.cid)
-        } catch {
-          // 文件可能不存在
-        }
-
-        await this.#swarm.leave(drive.discoveryKey)
-        await drive.close()
-        this.#drives.delete(driveName)
+      if (ownerAddress && !this.#recordMatchesOwner(fileRecord, ownerAddress)) {
+        remainingTrash.push(fileRecord)
+        continue
       }
+      removedTrash.push(fileRecord)
     }
 
-    this.#trashFiles = []
+    this.#trashFiles = remainingTrash
     this.#saveTrashMetadata()
 
-    return []
+    for (const fileRecord of removedTrash) {
+      if (this.#hasAnyUserReference(fileRecord.cid)) continue
+      const driveName =
+        fileRecord.driveName || this.#getCidInfo(fileRecord.cid).driveName
+      try {
+        const drive = await this.#getOrCreateDrive(driveName)
+        await drive.del('/' + fileRecord.cid)
+      } catch {
+        // 文件可能不存在
+      }
+      await this.#closeDriveForSeed(driveName)
+      await this.#leaveCidTopic(fileRecord.cid)
+      this.#removeHolding(fileRecord.cid)
+    }
+
+    return this.listTrashFiles({ ownerAddress })
   }
 
   /**
    * 获取存储统计信息
    * @returns {Promise<{ total: number, used: number, free: number, fileCount: number, trashCount: number }>}
    */
-  async getStorageStats() {
+  async getStorageStats(options = {}) {
     this.#ensureInitialized()
+    const ownerAddress = normalizeOwnerAddress(options.ownerAddress)
 
     let totalSize = 0
     let freeSize = 0
@@ -982,8 +1331,16 @@ export class MostBoxEngine extends EventEmitter {
       total: totalSize,
       used: usedSize,
       free: freeSize,
-      fileCount: this.#publishedFiles.length,
-      trashCount: this.#trashFiles.length,
+      fileCount: ownerAddress
+        ? this.#publishedFiles.filter(f =>
+            this.#recordMatchesOwner(f, ownerAddress)
+          ).length
+        : this.#publishedFiles.length,
+      trashCount: ownerAddress
+        ? this.#trashFiles.filter(f =>
+            this.#recordMatchesOwner(f, ownerAddress)
+          ).length
+        : this.#trashFiles.length,
     }
   }
 
@@ -994,9 +1351,12 @@ export class MostBoxEngine extends EventEmitter {
    * @param {string} newFileName - 新文件路径
    * @returns {object} 更新后的文件信息
    */
-  moveFile(cid, newFileName) {
+  moveFile(cid, newFileName, options = {}) {
     this.#ensureInitialized()
-    const index = this.#publishedFiles.findIndex(f => f.cid === cid)
+    const ownerAddress = normalizeOwnerAddress(options.ownerAddress)
+    const index = this.#publishedFiles.findIndex(
+      f => f.cid === cid && this.#recordMatchesOwner(f, ownerAddress)
+    )
     if (index === -1) {
       throw new Error('File not found')
     }
@@ -1007,7 +1367,7 @@ export class MostBoxEngine extends EventEmitter {
     return {
       cid,
       fileName: safeFileName,
-      link: `most://${cid}`,
+      link: `most://${cid}?filename=${encodeURIComponent(safeFileName)}`,
     }
   }
 
@@ -1018,13 +1378,17 @@ export class MostBoxEngine extends EventEmitter {
    * @param {string} newPath - 新文件夹路径
    * @returns {object} 更新后的文件信息
    */
-  renameFolder(oldPath, newPath) {
+  renameFolder(oldPath, newPath, options = {}) {
     this.#ensureInitialized()
+    const ownerAddress = normalizeOwnerAddress(options.ownerAddress)
     const prefix = oldPath + '/'
     const updatedFiles = []
 
     for (const file of this.#publishedFiles) {
-      if (file.fileName.startsWith(prefix)) {
+      if (
+        file.fileName.startsWith(prefix) &&
+        this.#recordMatchesOwner(file, ownerAddress)
+      ) {
         const remainder = file.fileName.substring(prefix.length)
         const newFileName = sanitizeFilename(
           remainder ? newPath + '/' + remainder : newPath
@@ -1034,7 +1398,7 @@ export class MostBoxEngine extends EventEmitter {
         updatedFiles.push({
           cid: file.cid,
           fileName: file.fileName,
-          link: `most://${file.cid}`,
+          link: `most://${file.cid}?filename=${encodeURIComponent(file.fileName)}`,
         })
       }
     }
@@ -1054,85 +1418,337 @@ export class MostBoxEngine extends EventEmitter {
     const task = this.#activeDownloads.get(taskId)
     if (task) {
       task.aborted = true
-      if (task.readStream) task.readStream.destroy()
+      const err = new Error('Download cancelled')
+      if (task.readStream) task.readStream.destroy(err)
       if (task.writeStream) task.writeStream.destroy()
     }
   }
 
-  getPublishedFiles() {
-    return this.#publishedFiles
+  hasDownloadNameConflict(fileName) {
+    this.#ensureInitialized()
+    const sanitizedFileName = sanitizeFilename(fileName)
+    const savePath = path.join(this.#options.downloadPath, sanitizedFileName)
+    return fs.existsSync(savePath)
   }
 
-  /**
-   * 读取已发布文件的内容（用于预览）
-   * Hyperdrive 中用 CID 作为 key 存储
-   * @param {string} cid - 文件的 CID
-   * @param {number} [offset=0] - 读取起始位置
-   * @param {number} [limit=10000] - 最大读取字节数
-   */
-  async readFileContent(cid, offset = 0, limit = DEFAULT_READ_LIMIT) {
-    this.#ensureInitialized()
+  setMaxFileSize(maxFileSize) {
+    const parsed = Number(maxFileSize)
+    if (!Number.isFinite(parsed) || parsed < 0) {
+      throw new ValidationError('maxFileSize must be a non-negative number')
+    }
+    this.#options.maxFileSize = Math.floor(parsed)
+  }
 
-    const fileRecord = this.#publishedFiles.find(f => f.cid === cid)
-    if (!fileRecord) {
-      throw new Error('File not found')
+  getPublishedFiles(options = {}) {
+    const ownerAddress = normalizeOwnerAddress(options.ownerAddress)
+    return ownerAddress
+      ? this.#publishedFiles.filter(f =>
+          this.#recordMatchesOwner(f, ownerAddress)
+        )
+      : this.#publishedFiles
+  }
+
+  listUsers() {
+    this.#ensureInitialized()
+    const users = new Map()
+    const ensure = address => {
+      const ownerAddress = normalizeOwnerAddress(address)
+      if (!ownerAddress) return null
+      if (!users.has(ownerAddress)) {
+        users.set(ownerAddress, {
+          address: ownerAddress,
+          fileCount: 0,
+          trashCount: 0,
+          cidCount: 0,
+          cids: new Set(),
+        })
+      }
+      return users.get(ownerAddress)
     }
 
-    const drive = await this.#getDriveForFile(fileRecord)
+    for (const file of this.#publishedFiles) {
+      const entry = ensure(file.ownerAddress)
+      if (!entry) continue
+      entry.fileCount += 1
+      entry.cids.add(file.cid)
+    }
+    for (const file of this.#trashFiles) {
+      const entry = ensure(file.ownerAddress)
+      if (!entry) continue
+      entry.trashCount += 1
+      entry.cids.add(file.cid)
+    }
+
+    return [...users.values()].map(user => ({
+      address: user.address,
+      fileCount: user.fileCount,
+      trashCount: user.trashCount,
+      cidCount: user.cids.size,
+    }))
+  }
 
-    // Hyperdrive 中 key 为 '/' + cid
-    const driveKey = '/' + cid
-    const entry = await drive.entry(driveKey, {
-      wait: true,
-      timeout: DRIVE_ENTRY_TIMEOUT,
-    })
-    if (!entry || !entry.value) {
-      throw new Error('File content not available')
+  async clearUserData(ownerAddressInput) {
+    this.#ensureInitialized()
+    const ownerAddress = normalizeOwnerAddress(ownerAddressInput)
+    if (!ownerAddress) {
+      throw new ValidationError('valid owner address is required')
     }
 
-    const chunks = []
-    const stream = drive.createReadStream(driveKey, {
-      start: offset,
-      end: offset + limit - 1,
-    })
+    const affectedCids = new Set()
+    const beforeFiles = this.#publishedFiles.length
+    const beforeTrash = this.#trashFiles.length
 
-    const timeoutPromise = new Promise((_, reject) => {
-      setTimeout(
-        () => reject(new Error('Stream read timeout')),
-        STREAM_READ_TIMEOUT
-      )
+    this.#publishedFiles = this.#publishedFiles.filter(file => {
+      if (this.#recordMatchesOwner(file, ownerAddress)) {
+        affectedCids.add(file.cid)
+        return false
+      }
+      return true
     })
-
-    const readPromise = (async () => {
-      for await (const chunk of stream) {
-        chunks.push(chunk)
+    this.#trashFiles = this.#trashFiles.filter(file => {
+      if (this.#recordMatchesOwner(file, ownerAddress)) {
+        affectedCids.add(file.cid)
+        return false
       }
-    })()
+      return true
+    })
+    this.#channels = this.#channels
+      .map(channel => ({
+        ...channel,
+        members: Array.isArray(channel.members)
+          ? channel.members.filter(
+              member => normalizeOwnerAddress(member) !== ownerAddress
+            )
+          : [],
+      }))
+      .filter(channel => channel.members.length > 0)
 
-    await Promise.race([readPromise, timeoutPromise])
+    this.#savePublishedMetadata()
+    this.#saveTrashMetadata()
+    this.#saveChannelsMetadata()
 
-    const content = Buffer.concat(chunks).toString('utf8')
-    const hasMore =
-      chunks.length > 0 && chunks[chunks.length - 1].length === limit
+    let removedReplicas = 0
+    for (const cid of affectedCids) {
+      if (this.#hasAnyUserReference(cid)) continue
+      const driveName = this.#getCidInfo(cid).driveName
+      try {
+        const drive = await this.#getOrCreateDrive(driveName)
+        await drive.del('/' + cid)
+      } catch {}
+      await this.#closeDriveForSeed(driveName)
+      await this.#leaveCidTopic(cid)
+      this.#removeHolding(cid)
+      removedReplicas += 1
+    }
 
-    return { content, hasMore }
+    return {
+      ownerAddress,
+      removedFiles: beforeFiles - this.#publishedFiles.length,
+      removedTrashFiles: beforeTrash - this.#trashFiles.length,
+      removedReplicas,
+    }
   }
 
   /**
-   * 读取已发布文件的原始内容（用于预览/下载）
-   * Hyperdrive 中用 CID 作为 key 存储
-   * @param {string} cid - 文件的 CID
-   * @param {object} [options] - 选项
-   * @param {number} [options.offset=0] - 读取起始位置
-   * @param {number} [options.limit] - 最大读取字节数，不指定则读取到末尾
-   * @param {number} [options.timeout=10000] - 流读取超时（毫秒）
-   * @returns {Promise<{buffer: Buffer, fileName: string, totalSize: number}>}
+   * 列出当前节点持有的可做种文件副本
+   * @returns {Array}
    */
-  async readFileRaw(cid, options = {}) {
+  listHoldings() {
     this.#ensureInitialized()
-
-    const fileRecord = this.#publishedFiles.find(f => f.cid === cid)
-    if (!fileRecord) {
+    return this.#holdings.map(holding => {
+      const seedState = this.#seedStates.get(holding.cid)
+      const status =
+        seedState?.status ||
+        (this.#fileDiscoveries.has(holding.cid) ? 'active' : 'queued')
+      return {
+        ...holding,
+        joined: status === 'active' && this.#fileDiscoveries.has(holding.cid),
+        seedStatus: status,
+        seedError: seedState?.error,
+        seedStatusUpdatedAt: seedState?.updatedAt,
+        ...this.#getFileRuntimeStats(holding.cid),
+        link: `most://${holding.cid}?filename=${encodeURIComponent(holding.fileName || holding.cid)}`,
+      }
+    })
+  }
+
+  /**
+   * 手动记录节点已持有的文件副本
+   * @param {object} record - 持有记录
+   */
+  async addHolding(record) {
+    this.#ensureInitialized()
+    const holding = this.#normalizeHolding(record)
+    await this.#joinCidTopicInternal(holding.cid, {
+      server: true,
+      client: false,
+    })
+    return this.#upsertHolding(holding)
+  }
+
+  /**
+   * 按 CID digest topic 拉取完整文件副本
+   * @param {object} input - 拉取参数
+   * @param {string} [input.link] - most:// 链接
+   * @param {string} [input.cid] - 文件 CID
+   * @param {string} [input.fileName] - 保存文件名
+   * @param {string} [input.taskId] - 下载任务 ID
+   * @param {number} [input.timeout] - 等待 P2P 内容的超时时间
+   */
+  async pullByCid(input = {}) {
+    this.#ensureInitialized()
+
+    if (input.link) {
+      const parsed = parseMostLink(input.link)
+      if (parsed.error) {
+        throw new ValidationError(parsed.error)
+      }
+      const result = await this.downloadFile(input.link, input.taskId || null, {
+        timeout: input.timeout,
+        ownerAddress: input.ownerAddress,
+      })
+      return {
+        ...result,
+        cid: parsed.cid,
+      }
+    }
+
+    const cid = input.cid
+    if (!cid) {
+      throw new ValidationError('cid is required')
+    }
+
+    this.#getCidInfo(cid)
+    const fileName = sanitizeFilename(input.fileName || `${cid}.bin`)
+    const link = `most://${cid}?filename=${encodeURIComponent(fileName)}`
+    const result = await this.downloadFile(link, input.taskId || null, {
+      timeout: input.timeout,
+      ownerAddress: input.ownerAddress,
+    })
+
+    return {
+      ...result,
+      cid,
+    }
+  }
+
+  /**
+   * 按 CID digest 加入文件 topic
+   * @param {string} cid - 文件 CID
+   * @param {object} [options] - Hyperswarm join 选项
+   */
+  async joinCidTopic(cid, options = {}) {
+    this.#ensureInitialized()
+    return this.#joinCidTopicInternal(cid, options)
+  }
+
+  /**
+   * 用内存复制流连接两个本地引擎，供本地集成测试和诊断使用。
+   */
+  replicateWith(peerEngine) {
+    this.#ensureInitialized()
+    peerEngine.#ensureInitialized()
+
+    const left = this.#store.replicate(true, { live: true })
+    const right = peerEngine.#store.replicate(false, { live: true })
+
+    left.on('error', () => {})
+    right.on('error', () => {})
+    left.pipe(right).pipe(left)
+
+    return {
+      close: () => {
+        left.destroy()
+        right.destroy()
+      },
+    }
+  }
+
+  /**
+   * 读取已发布文件的内容（用于预览）
+   * Hyperdrive 中用 CID 作为 key 存储
+   * @param {string} cid - 文件的 CID
+   * @param {number} [offset=0] - 读取起始位置
+   * @param {number} [limit=10000] - 最大读取字节数
+   */
+  async readFileContent(
+    cid,
+    offset = 0,
+    limit = DEFAULT_READ_LIMIT,
+    options = {}
+  ) {
+    this.#ensureInitialized()
+    const ownerAddress = normalizeOwnerAddress(options.ownerAddress)
+
+    const fileRecord = this.#publishedFiles.find(
+      f =>
+        f.cid === cid &&
+        (options.public || this.#recordMatchesOwner(f, ownerAddress))
+    )
+    if (!fileRecord) {
+      throw new Error('File not found')
+    }
+
+    const drive = await this.#getDriveForFile(fileRecord)
+
+    // Hyperdrive 中 key 为 '/' + cid
+    const driveKey = '/' + cid
+    const entry = await drive.entry(driveKey, {
+      wait: true,
+      timeout: DRIVE_ENTRY_TIMEOUT,
+    })
+    if (!entry || !entry.value) {
+      throw new Error('File content not available')
+    }
+
+    const chunks = []
+    const stream = drive.createReadStream(driveKey, {
+      start: offset,
+      end: offset + limit - 1,
+    })
+
+    const timeoutPromise = new Promise((_, reject) => {
+      setTimeout(
+        () => reject(new Error('Stream read timeout')),
+        STREAM_READ_TIMEOUT
+      )
+    })
+
+    const readPromise = (async () => {
+      for await (const chunk of stream) {
+        chunks.push(chunk)
+      }
+    })()
+
+    await Promise.race([readPromise, timeoutPromise])
+
+    const content = Buffer.concat(chunks).toString('utf8')
+    const hasMore =
+      chunks.length > 0 && chunks[chunks.length - 1].length === limit
+
+    return { content, hasMore }
+  }
+
+  /**
+   * 读取已发布文件的原始内容（用于预览/下载）
+   * Hyperdrive 中用 CID 作为 key 存储
+   * @param {string} cid - 文件的 CID
+   * @param {object} [options] - 选项
+   * @param {number} [options.offset=0] - 读取起始位置
+   * @param {number} [options.limit] - 最大读取字节数，不指定则读取到末尾
+   * @param {number} [options.timeout=10000] - 流读取超时（毫秒）
+   * @returns {Promise<{buffer: Buffer, fileName: string, totalSize: number}>}
+   */
+  async readFileRaw(cid, options = {}) {
+    this.#ensureInitialized()
+    const ownerAddress = normalizeOwnerAddress(options.ownerAddress)
+
+    const fileRecord = this.#publishedFiles.find(
+      f =>
+        f.cid === cid &&
+        (options.public || this.#recordMatchesOwner(f, ownerAddress))
+    )
+    if (!fileRecord) {
       throw new Error('File not found')
     }
 
@@ -1215,8 +1831,9 @@ export class MostBoxEngine extends EventEmitter {
    * @param {string} [type='personal'] - 频道类型
    * @returns {Promise<{ name: string, key: string }>}
    */
-  async createChannel(name, type = 'personal') {
+  async createChannel(name, type = 'personal', options = {}) {
     this.#ensureInitialized()
+    const ownerAddress = normalizeOwnerAddress(options.ownerAddress)
 
     if (!CHANNEL_NAME_REGEX.test(name)) {
       throw new Error('频道名只能包含字母、数字、下划线和连字符')
@@ -1230,6 +1847,13 @@ export class MostBoxEngine extends EventEmitter {
 
     const existing = this.#channels.find(c => c.name === name)
     if (existing) {
+      if (ownerAddress && !Array.isArray(existing.members)) {
+        existing.members = []
+      }
+      if (ownerAddress && !existing.members.includes(ownerAddress)) {
+        existing.members.push(ownerAddress)
+        this.#saveChannelsMetadata()
+      }
       return { name: existing.name, key: existing.coreKey }
     }
 
@@ -1243,12 +1867,10 @@ export class MostBoxEngine extends EventEmitter {
       server: true,
       client: true,
     })
-    await appDiscovery.flushed()
     const chatDiscovery = this.#chatSwarm.join(chatDiscoveryKey, {
       server: true,
       client: true,
     })
-    await chatDiscovery.flushed()
 
     this.#setupChannelAppendListener(core, name)
 
@@ -1258,10 +1880,18 @@ export class MostBoxEngine extends EventEmitter {
       coreKey: b4a.toString(core.key, 'hex'),
       createdAt: new Date().toISOString(),
       type,
+      ownerAddress,
+      members: ownerAddress ? [ownerAddress] : [],
+      remoteCoreKeys: [],
     }
 
     this.#channels.push(channelInfo)
-    this.#channelCores.set(name, core)
+    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)
@@ -1279,11 +1909,29 @@ export class MostBoxEngine extends EventEmitter {
    * @param {string} [coreKey] - 频道的 coreKey（加入他人创建的频道时必填）
    * @returns {Promise<{ name: string, key: string }>}
    */
-  async joinChannel(name, coreKey = null) {
+  async joinChannel(name, coreKey = null, options = {}) {
     this.#ensureInitialized()
+    const ownerAddress = normalizeOwnerAddress(options.ownerAddress)
 
     const existing = this.#channels.find(c => c.name === name)
     if (existing) {
+      if (ownerAddress && !Array.isArray(existing.members)) {
+        existing.members = []
+      }
+      if (ownerAddress && !existing.members.includes(ownerAddress)) {
+        existing.members.push(ownerAddress)
+        this.#saveChannelsMetadata()
+      }
+      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 }
     }
 
@@ -1292,11 +1940,13 @@ export class MostBoxEngine extends EventEmitter {
     }
 
     const ns = this.#store.namespace(`channel-${name}`)
-    const core = ns.get({
-      key: b4a.from(coreKey, 'hex'),
+    const remoteCoreKeyHex = b4a.toString(b4a.from(coreKey, 'hex'), 'hex')
+    const localCore = ns.get({
+      name: `messages-${this.getNodeId()}`,
       valueEncoding: 'json',
     })
-    await core.ready()
+    await localCore.ready()
+    const localCoreKeyHex = b4a.toString(localCore.key, 'hex')
 
     const discoveryKey = this.#generateChannelDiscoveryKey(name)
     const chatDiscoveryKey = this.#generateChannelChatDiscoveryKey(name)
@@ -1304,34 +1954,43 @@ export class MostBoxEngine extends EventEmitter {
       server: true,
       client: true,
     })
-    await appDiscovery.flushed()
     const chatDiscovery = this.#chatSwarm.join(chatDiscoveryKey, {
       server: true,
       client: true,
     })
-    await chatDiscovery.flushed()
 
-    this.#setupChannelAppendListener(core, name)
+    this.#setupChannelAppendListener(localCore, name)
 
     const channelInfo = {
       name,
       discoveryKey: b4a.toString(discoveryKey, 'hex'),
-      coreKey,
+      coreKey: localCoreKeyHex,
       createdAt: new Date().toISOString(),
       type: 'group',
+      ownerAddress,
+      members: ownerAddress ? [ownerAddress] : [],
+      remoteCoreKeys:
+        remoteCoreKeyHex === localCoreKeyHex ? [] : [remoteCoreKeyHex],
     }
 
     this.#channels.push(channelInfo)
-    this.#channelCores.set(name, core)
+    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: coreKey })
+    this.emit('channel:joined', { name, key: localCoreKeyHex })
 
-    return { name, key: coreKey }
+    return { name, key: localCoreKeyHex }
   }
 
   /**
@@ -1339,8 +1998,9 @@ export class MostBoxEngine extends EventEmitter {
    * @param {string} name - 频道名
    * @returns {Promise<string[]>} 剩余频道列表
    */
-  async leaveChannel(name) {
+  async leaveChannel(name, options = {}) {
     this.#ensureInitialized()
+    const ownerAddress = normalizeOwnerAddress(options.ownerAddress)
 
     const index = this.#channels.findIndex(c => c.name === name)
     if (index === -1) {
@@ -1348,46 +2008,54 @@ export class MostBoxEngine extends EventEmitter {
     }
 
     const channel = this.#channels[index]
+    if (ownerAddress && Array.isArray(channel.members)) {
+      channel.members = channel.members.filter(
+        member => normalizeOwnerAddress(member) !== ownerAddress
+      )
+      if (channel.members.length > 0) {
+        this.#saveChannelsMetadata()
+        return this.listChannels({ ownerAddress })
+      }
+    }
 
     const appDiscovery = this.#channelDiscoveries.get(name)
     if (appDiscovery && this.#swarm) {
-      try {
-        await this.#swarm.leave(b4a.from(channel.discoveryKey, 'hex'))
-      } catch (err) {
+      this.#channelDiscoveries.delete(name)
+      this.#swarm.leave(b4a.from(channel.discoveryKey, 'hex')).catch(err => {
         console.warn(
           `[MostBox] Failed to leave app swarm for ${name}:`,
           err.message
         )
-      }
-      this.#channelDiscoveries.delete(name)
+      })
     }
 
     const chatDiscovery = this.#channelChatDiscoveries.get(name)
     if (chatDiscovery && this.#chatSwarm) {
-      try {
-        const chatDiscoveryKey = this.#generateChannelChatDiscoveryKey(name)
-        await this.#chatSwarm.leave(chatDiscoveryKey)
-      } catch (err) {
+      this.#channelChatDiscoveries.delete(name)
+      const chatDiscoveryKey = this.#generateChannelChatDiscoveryKey(name)
+      this.#chatSwarm.leave(chatDiscoveryKey).catch(err => {
         console.warn(
           `[MostBox] Failed to leave chat swarm for ${name}:`,
           err.message
         )
-      }
-      this.#channelChatDiscoveries.delete(name)
+      })
     }
 
-    const core = this.#channelCores.get(name)
-    if (core) {
-      try {
-        await core.close()
-      } catch (err) {
-        console.warn(
-          `[MostBox] Failed to close channel core for ${name}:`,
-          err.message
-        )
+    const coresMap = this.#channelCores.get(name)
+    if (coresMap) {
+      for (const [, core] of coresMap) {
+        try {
+          await core.close()
+        } catch (err) {
+          console.warn(
+            `[MostBox] Failed to close channel core for ${name}:`,
+            err.message
+          )
+        }
       }
       this.#channelCores.delete(name)
     }
+    this.#channelLocalCoreKey.delete(name)
 
     this.#channelPeers.delete(name)
     this.#channels.splice(index, 1)
@@ -1396,23 +2064,61 @@ export class MostBoxEngine extends EventEmitter {
     console.log(`[MostBox] Left channel: ${name}`)
     this.emit('channel:left', { name })
 
-    return this.listChannels()
+    return this.listChannels({ ownerAddress })
+  }
+
+  setChannelRemark(name, 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 trimmed = (remark || '').trim()
+    if (trimmed.length > 50) {
+      throw new Error('备注最多 50 个字符')
+    }
+
+    if (!channel.remarks) {
+      channel.remarks = {}
+    }
+
+    if (trimmed) {
+      channel.remarks[ownerAddress] = trimmed
+    } else {
+      delete channel.remarks[ownerAddress]
+    }
+
+    this.#saveChannelsMetadata()
+    return trimmed
   }
 
   /**
    * 列出所有频道
-   * @returns {Array<{ name: string, coreKey: string, createdAt: string, type: string, peerCount: number }>}
+   * @returns {Array<{ name: string, coreKey: string, createdAt: string, type: string, peerCount: number, remark: string }>}
    */
-  listChannels() {
+  listChannels(options = {}) {
     this.#ensureInitialized()
+    const ownerAddress = normalizeOwnerAddress(options.ownerAddress)
 
-    return this.#channels.map(c => ({
-      name: c.name,
-      coreKey: c.coreKey,
-      createdAt: c.createdAt,
-      type: c.type,
-      peerCount: (this.#channelPeers.get(c.name) || new Map()).size,
-    }))
+    return this.#channels
+      .filter(c => {
+        if (!ownerAddress) return true
+        return Array.isArray(c.members) && c.members.includes(ownerAddress)
+      })
+      .map(c => ({
+        name: c.name,
+        coreKey: c.coreKey,
+        createdAt: c.createdAt,
+        type: c.type,
+        peerCount: (this.#channelPeers.get(c.name) || new Map()).size,
+        remark: ownerAddress && c.remarks ? c.remarks[ownerAddress] || '' : '',
+      }))
   }
 
   /**
@@ -1425,29 +2131,48 @@ export class MostBoxEngine extends EventEmitter {
    */
   async getChannelMessages(name, options = {}) {
     this.#ensureInitialized()
+    this.#assertChannelMember(name, options.ownerAddress)
 
     const { limit = CHANNEL_MESSAGE_LIMIT, offset = 0 } = options
 
-    const core = this.#channelCores.get(name)
-    if (!core) {
+    const coresMap = this.#channelCores.get(name)
+    if (!coresMap || coresMap.size === 0) {
       throw new Error('频道未初始化')
     }
 
-    const messages = []
-    const total = core.length
-    const start = Math.max(0, total - offset - limit)
-    const end = total - offset
-
-    for (let i = start; i < end; i++) {
-      try {
-        const entry = await core.get(i)
-        messages.push(entry)
-      } catch {
-        break
+    const allMessages = []
+    for (const [coreKeyHex, core] of coresMap) {
+      for (let i = 0; i < core.length; i++) {
+        try {
+          const entry = await core.get(i)
+          if (entry && entry.type === 'message') {
+            allMessages.push({
+              ...entry,
+              _coreKey: coreKeyHex,
+              _index: i,
+            })
+          }
+        } catch {
+          break
+        }
       }
     }
 
-    return messages
+    const seen = new Set()
+    const unique = allMessages.filter(m => {
+      const key = `${m._coreKey}:${m.author}:${m.timestamp}:${m.content}`
+      if (seen.has(key)) return false
+      seen.add(key)
+      return true
+    })
+
+    unique.sort((a, b) => a.timestamp - b.timestamp)
+
+    const total = unique.length
+    const start = Math.max(0, total - offset - limit)
+    const end = total - offset
+
+    return unique.slice(start, end).map(({ _coreKey, _index, ...msg }) => msg)
   }
 
   /**
@@ -1456,14 +2181,18 @@ export class MostBoxEngine extends EventEmitter {
    * @param {string} content - 消息内容
    * @param {string} author - 作者 address
    * @param {string} authorName - 作者显示名
+   * @param {object} [options.attachment] - 附件元数据
    * @returns {Promise<object>}
    */
-  async sendMessage(name, content, author, authorName) {
+  async sendMessage(name, content, author, authorName, options = {}) {
     this.#ensureInitialized()
+    this.#assertChannelMember(name, options.ownerAddress)
 
-    const core = this.#channelCores.get(name)
+    const localKeyHex = this.#channelLocalCoreKey.get(name)
+    const coresMap = this.#channelCores.get(name)
+    const core = localKeyHex && coresMap ? coresMap.get(localKeyHex) : null
     if (!core) {
-      throw new Error('频道未初始化')
+      throw new Error('频道未初始化或无可写 core')
     }
 
     if (!content || !content.trim()) {
@@ -1474,6 +2203,10 @@ export class MostBoxEngine extends EventEmitter {
     if (trimmed.length > MAX_MESSAGE_LENGTH) {
       throw new Error(`消息内容不能超过 ${MAX_MESSAGE_LENGTH} 字符`)
     }
+    const attachment = normalizeChannelAttachment(options.attachment)
+    if (attachment && trimmed !== attachment.link) {
+      throw new ValidationError('attachment content must match link')
+    }
 
     const message = {
       type: 'message',
@@ -1482,11 +2215,12 @@ export class MostBoxEngine extends EventEmitter {
       content: trimmed,
       timestamp: Date.now(),
     }
+    if (attachment) {
+      message.attachment = attachment
+    }
 
     await core.append(message)
 
-    this.emit('channel:message', { channel: name, message })
-
     return message
   }
 
@@ -1495,8 +2229,9 @@ export class MostBoxEngine extends EventEmitter {
    * @param {string} name - 频道名
    * @returns {Array<{ peerId: string, authorName: string, lastSeen: number }>}
    */
-  getChannelPeers(name) {
+  getChannelPeers(name, options = {}) {
     this.#ensureInitialized()
+    this.#assertChannelMember(name, options.ownerAddress)
 
     const peers = this.#channelPeers.get(name)
     if (!peers) {
@@ -1553,6 +2288,429 @@ export class MostBoxEngine extends EventEmitter {
     }
   }
 
+  #assertChannelMember(name, ownerAddress) {
+    const normalizedOwner = normalizeOwnerAddress(ownerAddress)
+    if (!normalizedOwner) return
+
+    const channel = this.#channels.find(c => c.name === name)
+    if (!channel) {
+      throw new Error('频道不存在')
+    }
+    if (
+      !Array.isArray(channel.members) ||
+      !channel.members.includes(normalizedOwner)
+    ) {
+      throw new PermissionError('未加入该频道')
+    }
+  }
+
+  #getCidInfo(cid) {
+    return getCidInfo(cid)
+  }
+
+  #setSeedState(cid, patch = {}) {
+    const previous = this.#seedStates.get(cid) || {}
+    const next = {
+      ...previous,
+      cid,
+      ...patch,
+      updatedAt: new Date().toISOString(),
+    }
+    this.#seedStates.set(cid, next)
+    this.emit('seed:state', next)
+    return next
+  }
+
+  #clearSeedState(cid) {
+    if (this.#seedStates.delete(cid)) {
+      this.emit('seed:state:removed', { cid })
+    }
+  }
+
+  #getFileRuntimeStats(cid) {
+    const state = this.#fileMonitors.get(cid)
+    if (!state) {
+      return {
+        peerCount: 0,
+        lastServedAt: null,
+        totalServedBytes: 0,
+      }
+    }
+
+    return {
+      peerCount: state.peerCount || 0,
+      lastServedAt: state.lastServedAt || null,
+      totalServedBytes: state.totalServedBytes || 0,
+    }
+  }
+
+  async #ensureFileMonitor(cid, drive = null) {
+    const existing = this.#fileMonitors.get(cid)
+    if (existing) return existing
+
+    const { driveName } = this.#getCidInfo(cid)
+    const monitoredDrive = drive || (await this.#getOrCreateDrive(driveName))
+    const monitor = monitoredDrive.monitor('/' + cid)
+    const state = {
+      cid,
+      monitor,
+      peerCount: 0,
+      lastServedAt: null,
+      totalServedBytes: 0,
+      uploadBytes: 0,
+      uploadBlocks: 0,
+      lastMetricsEmittedAt: 0,
+      cleanup: null,
+    }
+    this.#fileMonitors.set(cid, state)
+
+    const emitMetrics = (force = false) => {
+      const now = Date.now()
+      if (!force && now - state.lastMetricsEmittedAt < 1000) return
+      state.lastMetricsEmittedAt = now
+      this.emit('seed:metrics', {
+        cid,
+        ...this.#getFileRuntimeStats(cid),
+      })
+    }
+
+    const updatePeerCount = () => {
+      const nextPeerCount = Number(monitor.peers) || 0
+      if (nextPeerCount !== state.peerCount) {
+        state.peerCount = nextPeerCount
+        emitMetrics(true)
+      }
+    }
+
+    const updateTransferStats = () => {
+      updatePeerCount()
+      const uploadStats = monitor.uploadStats || {}
+      const uploadBytes = Number(uploadStats.monitoringBytes) || 0
+      const uploadBlocks = Number(uploadStats.blocks) || 0
+      const servedMore =
+        uploadBytes > state.uploadBytes || uploadBlocks > state.uploadBlocks
+
+      if (servedMore) {
+        state.lastServedAt = new Date().toISOString()
+        state.totalServedBytes = uploadBytes
+      }
+
+      state.uploadBytes = uploadBytes
+      state.uploadBlocks = uploadBlocks
+      if (servedMore) emitMetrics()
+    }
+
+    monitor.on('update', updateTransferStats)
+    try {
+      await monitor.ready()
+      const blobs = monitor.blobs
+      const onPeerUpdate = () => {
+        updatePeerCount()
+      }
+      blobs?.core?.on('peer-add', onPeerUpdate)
+      blobs?.core?.on('peer-remove', onPeerUpdate)
+      state.cleanup = () => {
+        blobs?.core?.off('peer-add', onPeerUpdate)
+        blobs?.core?.off('peer-remove', onPeerUpdate)
+      }
+      updateTransferStats()
+    } catch (err) {
+      this.#fileMonitors.delete(cid)
+      monitor.off('update', updateTransferStats)
+      await monitor.close().catch(() => {})
+      throw err
+    }
+
+    return state
+  }
+
+  async #closeFileMonitor(state) {
+    if (!state) return
+    try {
+      state.cleanup?.()
+      await state.monitor.close()
+    } catch {}
+  }
+
+  #resumeHoldingsInBackground() {
+    if (this.#holdingResumeTask || this.#holdings.length === 0) {
+      return
+    }
+
+    const holdings = [...this.#holdings]
+    this.#holdingResumeTask = (async () => {
+      for (
+        let index = 0;
+        index < holdings.length && this.#initialized;
+        index += HOLDING_REJOIN_BATCH_SIZE
+      ) {
+        const batch = holdings.slice(index, index + HOLDING_REJOIN_BATCH_SIZE)
+        await Promise.allSettled(
+          batch.map(async holding => {
+            if (!this.#holdings.some(current => current.cid === holding.cid)) {
+              return
+            }
+            await this.#joinCidTopicInternal(holding.cid, {
+              server: true,
+              client: false,
+            })
+            console.log(`[MostBox] Rejoined CID topic: ${holding.cid}`)
+          })
+        )
+
+        if (
+          index + HOLDING_REJOIN_BATCH_SIZE < holdings.length &&
+          this.#initialized
+        ) {
+          await sleep(HOLDING_REJOIN_BATCH_DELAY)
+        }
+      }
+    })()
+      .catch(err => {
+        console.warn('[MostBox] Failed to resume holdings:', err.message)
+      })
+      .finally(() => {
+        this.#holdingResumeTask = null
+      })
+  }
+
+  #normalizeHolding(record = {}) {
+    const cid = record.cid
+    if (!cid) {
+      throw new ValidationError('cid is required')
+    }
+
+    const { topicHex, driveName } = this.#getCidInfo(cid)
+    if (record.topic && record.topic !== topicHex) {
+      throw new ValidationError('topic must match CID digest')
+    }
+
+    const size = Number(record.size)
+    if (!Number.isFinite(size) || size < 0) {
+      throw new ValidationError('size must be a non-negative number')
+    }
+
+    return {
+      cid,
+      fileName: record.fileName || cid,
+      size,
+      localPath: record.localPath || null,
+      topic: topicHex,
+      driveName: record.driveName || driveName,
+      source: record.source || 'manual',
+    }
+  }
+
+  #upsertHolding(record) {
+    const holding = this.#normalizeHolding(record)
+    const now = new Date().toISOString()
+    const index = this.#holdings.findIndex(f => f.cid === holding.cid)
+    const next =
+      index === -1
+        ? { ...holding, createdAt: now, updatedAt: now }
+        : { ...this.#holdings[index], ...holding, updatedAt: now }
+
+    if (index === -1) {
+      this.#holdings.push(next)
+    } else {
+      this.#holdings[index] = next
+    }
+
+    this.#saveHoldingsMetadata()
+    this.emit('holding:updated', next)
+    this.#ensureFileMonitor(next.cid).catch(err => {
+      this.#setSeedState(next.cid, {
+        status: 'error',
+        error: err.message,
+      })
+    })
+    const seedState = this.#seedStates.get(next.cid)
+    return {
+      ...next,
+      joined: this.#fileDiscoveries.has(next.cid),
+      seedStatus:
+        seedState?.status ||
+        (this.#fileDiscoveries.has(next.cid) ? 'active' : 'queued'),
+      seedError: seedState?.error,
+      seedStatusUpdatedAt: seedState?.updatedAt,
+      ...this.#getFileRuntimeStats(next.cid),
+    }
+  }
+
+  #removeHolding(cid) {
+    const before = this.#holdings.length
+    this.#holdings = this.#holdings.filter(holding => holding.cid !== cid)
+    if (this.#holdings.length !== before) {
+      this.#saveHoldingsMetadata()
+      this.emit('holding:removed', { cid })
+    }
+    this.#closeFileMonitor(this.#fileMonitors.get(cid))
+    this.#fileMonitors.delete(cid)
+    this.#clearSeedState(cid)
+  }
+
+  async #joinCidTopicInternal(cid, options = {}) {
+    const { topic, topicHex, driveName } = this.#getCidInfo(cid)
+    const requestedServer = options.server !== false
+    const requestedClient = options.client === true
+    this.#setSeedState(cid, {
+      status: 'joining',
+      topic: topicHex,
+      driveName,
+      error: undefined,
+    })
+
+    try {
+      const drive = await this.#getOrCreateDrive(driveName)
+
+      const existing = this.#fileDiscoveries.get(cid)
+      if (existing) {
+        const nextServer = existing.server || requestedServer
+        const nextClient = existing.client || requestedClient
+        const needsRoleUpgrade =
+          nextServer !== existing.server || nextClient !== existing.client
+
+        if (!needsRoleUpgrade) {
+          if (this.#holdings.some(holding => holding.cid === cid)) {
+            this.#ensureFileMonitor(cid, drive).catch(err => {
+              this.#setSeedState(cid, {
+                status: 'error',
+                error: err.message,
+              })
+            })
+          }
+          this.#setSeedState(cid, {
+            status: 'active',
+            topic: topicHex,
+            driveName,
+            error: undefined,
+          })
+          return {
+            cid,
+            topic: topicHex,
+            driveName,
+            joined: true,
+          }
+        }
+
+        await this.#swarm.leave(topic).catch(err => {
+          console.warn(
+            `[MostBox] Failed to upgrade CID topic role for ${cid}:`,
+            err.message
+          )
+        })
+        this.#fileDiscoveries.delete(cid)
+      }
+
+      const server = existing?.server || requestedServer
+      const client = existing?.client || requestedClient
+      const discovery = this.#swarm.join(topic, {
+        server,
+        client,
+      })
+
+      this.#fileDiscoveries.set(cid, {
+        discovery,
+        topic: topicHex,
+        driveName,
+        server,
+        client,
+      })
+      this.#setSeedState(cid, {
+        status: 'active',
+        topic: topicHex,
+        driveName,
+        error: undefined,
+      })
+      if (this.#holdings.some(holding => holding.cid === cid)) {
+        this.#ensureFileMonitor(cid, drive).catch(err => {
+          this.#setSeedState(cid, {
+            status: 'error',
+            error: err.message,
+          })
+        })
+      }
+      this.emit('file:topic:joined', { cid, topic: topicHex, driveName })
+
+      return {
+        cid,
+        topic: topicHex,
+        driveName,
+        joined: true,
+      }
+    } catch (err) {
+      this.#setSeedState(cid, {
+        status: 'error',
+        topic: topicHex,
+        driveName,
+        error: err.message,
+      })
+      throw err
+    }
+  }
+
+  async #leaveCidTopic(cid) {
+    const existing = this.#fileDiscoveries.get(cid)
+    if (!existing || !this.#swarm) {
+      this.#setSeedState(cid, { status: 'paused' })
+      return
+    }
+
+    this.#fileDiscoveries.delete(cid)
+    this.#swarm.leave(b4a.from(existing.topic, 'hex')).catch(err => {
+      console.warn(`[MostBox] Failed to leave CID topic ${cid}:`, err.message)
+    })
+    this.#setSeedState(cid, {
+      status: 'paused',
+      topic: existing.topic,
+      driveName: existing.driveName,
+    })
+  }
+
+  async #closeDriveForSeed(driveName) {
+    const drive = this.#drives.get(driveName)
+    if (!drive) {
+      return null
+    }
+
+    await drive.close()
+    this.#drives.delete(driveName)
+    return drive
+  }
+
+  #recordMatchesOwner(record, ownerAddress) {
+    const normalizedOwner = normalizeOwnerAddress(ownerAddress)
+    if (!normalizedOwner) return !record.ownerAddress
+    return normalizeOwnerAddress(record.ownerAddress) === normalizedOwner
+  }
+
+  #hasPublishedReference(cid) {
+    return this.#publishedFiles.some(file => file.cid === cid)
+  }
+
+  #hasAnyUserReference(cid) {
+    return (
+      this.#publishedFiles.some(file => file.cid === cid) ||
+      this.#trashFiles.some(file => file.cid === cid)
+    )
+  }
+
+  #getUsedBytes() {
+    return this.#holdings.reduce((sum, h) => sum + (h.size || 0), 0)
+  }
+
+  #checkCapacity(additionalBytes) {
+    const used = this.#getUsedBytes()
+    const capacity = this.#options.capacityBytes
+    if (used + additionalBytes > capacity) {
+      const usedGB = (used / (1024 * 1024 * 1024)).toFixed(2)
+      const capacityGB = (capacity / (1024 * 1024 * 1024)).toFixed(2)
+      throw new StorageCapacityError(
+        `Storage capacity exceeded: used ${usedGB} GB, capacity ${capacityGB} GB`
+      )
+    }
+  }
+
   async #getOrCreateDrive(name, _options = { server: true, client: false }) {
     if (this.#drives.has(name)) return this.#drives.get(name)
     if (this.#drivePromises.has(name)) return this.#drivePromises.get(name)
@@ -1575,11 +2733,6 @@ export class MostBoxEngine extends EventEmitter {
   }
 
   async #syncDrive(drive, timeout = DRIVE_SYNC_TIMEOUT) {
-    const done = drive.findingPeers()
-    this.#swarm
-      .join(drive.discoveryKey, { server: true, client: true })
-      .flushed()
-      .then(done, done)
     try {
       const updated = await Promise.race([
         drive.update(),
@@ -1597,6 +2750,10 @@ export class MostBoxEngine extends EventEmitter {
     return path.join(this.#options.dataPath, 'published-files.json')
   }
 
+  #getHoldingsMetadataPath() {
+    return path.join(this.#options.dataPath, 'node-holdings.json')
+  }
+
   #getTrashMetadataPath() {
     return path.join(this.#options.dataPath, 'trash-files.json')
   }
@@ -1636,6 +2793,32 @@ export class MostBoxEngine extends EventEmitter {
     }
   }
 
+  #loadHoldingsMetadata() {
+    try {
+      const metadataPath = this.#getHoldingsMetadataPath()
+      if (fs.existsSync(metadataPath)) {
+        const data = fs.readFileSync(metadataPath, 'utf-8')
+        const parsed = JSON.parse(data)
+        return parsed.map(record => this.#normalizeHolding(record))
+      }
+    } catch (err) {
+      console.warn(
+        'Failed to load node holdings metadata, using empty list:',
+        err.message
+      )
+    }
+    return []
+  }
+
+  #saveHoldingsMetadata() {
+    try {
+      const metadataPath = this.#getHoldingsMetadataPath()
+      this.#atomicWrite(metadataPath, JSON.stringify(this.#holdings, null, 2))
+    } catch (err) {
+      console.error('Failed to save node holdings metadata:', err.message)
+    }
+  }
+
   #loadTrashMetadata() {
     try {
       const metadataPath = this.#getTrashMetadataPath()
@@ -1736,15 +2919,57 @@ export class MostBoxEngine extends EventEmitter {
     })
   }
 
+  async #openRemoteChannelCore(channelName, coreKeyHex) {
+    const coresMap = this.#channelCores.get(channelName)
+    if (!coresMap) return
+    if (coresMap.has(coreKeyHex)) return
+
+    try {
+      const ns = this.#store.namespace(`channel-${channelName}`)
+      const core = ns.get({
+        key: b4a.from(coreKeyHex, 'hex'),
+        valueEncoding: 'json',
+      })
+      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()
+        }
+      }
+      console.log(
+        `[MostBox] Opened remote channel core ${normalizedCoreKey.slice(0, 8)}... for ${channelName}`
+      )
+    } catch (err) {
+      console.warn(
+        `[MostBox] Failed to open remote channel core for ${channelName}:`,
+        err.message
+      )
+    }
+  }
+
   async #handleChannelConnection(conn) {
     const stream = conn
     let connectedPeerId = null
 
+    const coreKeys = {}
+    for (const [name, localKeyHex] of this.#channelLocalCoreKey) {
+      coreKeys[name] = localKeyHex
+    }
+
     const helloMessage = JSON.stringify({
       type: 'channel-hello',
       peerId: this.getNodeId(),
       authorName: this.getNodeId().slice(0, 4),
       channels: this.#channels.map(c => c.name),
+      coreKeys,
     })
 
     try {
@@ -1769,6 +2994,17 @@ export class MostBoxEngine extends EventEmitter {
               })
             }
           }
+
+          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)
+              }
+            }
+          }
+
           this.emit('channel:peer:online', {
             peerId: msg.peerId,
             authorName: msg.authorName,
@@ -1796,14 +3032,21 @@ export class MostBoxEngine extends EventEmitter {
   }
 
   /**
-   * 等待驱动器内容从对等节点或本地可用
+   * 等待指定 Hyperdrive key 从对等节点或本地可用。
    * @param {Hyperdrive} drive - 要检查的驱动器
+   * @param {string} key - 期望的 Hyperdrive key，固定为 /<cid>
    * @param {number} timeout - 最大等待时间（毫秒）
    * @param {string} [taskId] - 用于取消的任务 ID
    * @param {object} [taskState] - 任务状态对象
-   * @returns {Promise<Array>} - 条目列表
+   * @returns {Promise<object|null>} - Hyperdrive entry
    */
-  async #waitForDriveContent(drive, timeout, taskId = null, taskState = null) {
+  async #waitForDriveEntry(
+    drive,
+    key,
+    timeout,
+    taskId = null,
+    taskState = null
+  ) {
     const startTime = Date.now()
     let pollInterval = DOWNLOAD_POLL_INTERVAL_MIN
     let lastPeerCount = 0
@@ -1811,15 +3054,12 @@ export class MostBoxEngine extends EventEmitter {
     let bootstrapNodesChecked = false
     let lastUpdateTime = 0
 
-    const localEntries = []
     try {
-      for await (const entry of drive.list()) {
-        localEntries.push(entry)
-      }
-      if (localEntries.length > 0) {
-        console.log(`[MostBox] Found ${localEntries.length} entries locally`)
-        this.emit('download:status', { taskId, status: 'syncing' })
-        return localEntries
+      const localEntry = await drive.entry(key)
+      if (localEntry) {
+        console.log(`[MostBox] Found expected entry ${key} locally`)
+        if (taskId) this.emit('download:status', { taskId, status: 'syncing' })
+        return localEntry
       }
     } catch {}
 
@@ -1853,32 +3093,32 @@ export class MostBoxEngine extends EventEmitter {
 
       await tryUpdateDrive()
 
-      const entries = []
       try {
-        for await (const entry of drive.list()) {
-          entries.push(entry)
+        const entry = await drive.entry(key)
+        if (entry) {
+          console.log(`[MostBox] Found ${key} after ${elapsed}s`)
+          if (taskId) {
+            this.emit('download:status', { taskId, status: 'syncing' })
+          }
+          return entry
         }
       } catch {}
 
-      if (entries.length > 0) {
-        console.log(
-          `[MostBox] Found ${entries.length} entries after ${elapsed}s`
-        )
-        this.emit('download:status', { taskId, status: 'syncing' })
-        return entries
-      }
-
       if (hasPeers) {
         const newStatus = 'syncing'
         if (lastStatus !== newStatus) {
-          this.emit('download:status', { taskId, status: newStatus })
+          if (taskId) {
+            this.emit('download:status', { taskId, status: newStatus })
+          }
           lastStatus = newStatus
         }
         pollInterval = Math.min(pollInterval + 200, DOWNLOAD_POLL_INTERVAL_MAX)
       } else {
         const newStatus = 'finding-peers'
         if (lastStatus !== newStatus) {
-          this.emit('download:status', { taskId, status: newStatus })
+          if (taskId) {
+            this.emit('download:status', { taskId, status: newStatus })
+          }
           lastStatus = newStatus
         }
         pollInterval = DOWNLOAD_POLL_INTERVAL_MIN
@@ -1912,36 +3152,34 @@ export class MostBoxEngine extends EventEmitter {
 
     await tryUpdateDrive()
 
-    const entries = []
     try {
-      for await (const entry of drive.list()) {
-        entries.push(entry)
+      const entry = await drive.entry(key)
+      if (entry) {
+        console.log(`[MostBox] Found ${key} on final attempt`)
+        return entry
       }
     } catch (err) {
       console.log(`[MostBox] Final attempt failed: ${err.message}`)
     }
 
-    console.log(`[MostBox] Final entry count: ${entries.length}`)
-
-    if (entries.length === 0) {
-      const peerCount = this.#swarm.connections.size
-      console.log(`[MostBox] Diagnostic information:`)
-      console.log(`[MostBox] - Peer count: ${peerCount}`)
-      console.log(`[MostBox] - Bootstrap nodes: ${SWARM_BOOTSTRAP.length}`)
-      console.log(`[MostBox] - Timeout: ${timeout / 1000}s`)
+    const peerCount = this.#swarm.connections.size
+    console.log(`[MostBox] Diagnostic information:`)
+    console.log(`[MostBox] - Expected key: ${key}`)
+    console.log(`[MostBox] - Peer count: ${peerCount}`)
+    console.log(`[MostBox] - Bootstrap nodes: ${SWARM_BOOTSTRAP.length}`)
+    console.log(`[MostBox] - Timeout: ${timeout / 1000}s`)
 
-      if (peerCount === 0) {
-        console.log(
-          `[MostBox] Suggestion: Check network connectivity and firewall settings`
-        )
-      } else {
-        console.log(
-          `[MostBox] Suggestion: Publisher may be offline or file may have been removed`
-        )
-      }
+    if (peerCount === 0) {
+      console.log(
+        `[MostBox] Suggestion: Check network connectivity and firewall settings`
+      )
+    } else {
+      console.log(
+        `[MostBox] Suggestion: Publisher may be offline or file may have been removed`
+      )
     }
 
-    return entries
+    return null
   }
 }