libp2r2p 0.7.0 → 0.8.0

package/README.md

@@ -21,6 +21,8 @@ const messenger = await createPrivateMessenger({
   userSigner,
   contentKeySigner,
   offlineRecoverySeconds: 7 * 24 * 60 * 60,
+  staleChannelSeconds: 45 * 24 * 60 * 60,
+  identityStorageRetentionSeconds: 60 * 24 * 60 * 60,
   channels: [{
     signer: privateChannelSigner,
     relays: ['wss://relay.example'],
@@ -152,21 +154,42 @@ know database names or enumerate IndexedDB. Pass `temporaryStorageArea` only
 when the messenger was configured to use a Storage area other than the default
 `sessionStorage`.
 
-Each principal signer owns internal message, recovery-seed, and channel-state
-databases. The messenger updates their activity lease while it is open and
-closes all handles in `await messenger.close()`. The complete set is removed
-after 60 days without use, including messages that were never consumed.
+Each principal signer owns an internal storage set containing message,
+recovery-seed, and channel-state databases. The messenger updates its activity
+lease while it is open and closes all handles in `await messenger.close()`.
+The complete set is removed after `identityStorageRetentionSeconds` without
+use (60 days by default), including messages that were never consumed.
 Maintenance runs on every initialization and every six hours while a messenger
 is active; failed deletions remain journaled and retry automatically.
 
-Channel recovery state inside an otherwise active identity retains its separate
-45-day stale-channel cleanup policy. Offline recovery defaults to seven days.
+Channel recovery state inside an otherwise active identity uses the separate
+`staleChannelSeconds` cleanup policy (45 days by default). Active instances
+record the channels they administer, so a channel remains protected while any
+instance or tab still uses it. Offline recovery defaults to seven days.
 Set `offlineRecoverySeconds` on an individual channel to override the
 messenger default for its recovery seeds, offline ranges, new outer-event
 expiration, and new incomplete receive groups. Updating a channel applies a
 shorter window immediately to its stored seeds and ranges; increasing it does
 not recreate data already removed.
 
+The effective recovery duration is capped by both `staleChannelSeconds` and
+`identityStorageRetentionSeconds`. The requested per-channel value remains
+stored separately, so raising a cap affects new retention decisions without
+recreating data already removed. Both retention policies can be changed by an
+instance at runtime; omitted fields retain their current persisted values:
+
+```js
+await messenger.update({
+  staleChannelSeconds: 30 * 24 * 60 * 60,
+  identityStorageRetentionSeconds: 90 * 24 * 60 * 60
+})
+```
+
+The policies are persisted per principal identity. If multiple instances use
+the same identity, the last confirmed policy update wins and is propagated to
+the others. A zero policy disables durable recovery immediately. Identity
+storage itself remains protected until the final active lease closes.
+
 Set a channel's `offlineRecoverySeconds` to `0` to disable durable recovery for
 that channel. The messenger then stores no recovery seeds, tracks no offline
 ranges, contacts no seeders, publishes no seeder presence, and uses no recovery

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libp2r2p",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Peer-to-relay-to-peer",
   "keywords": [
     "p2r2p",

package/private-messenger/index.js

@@ -3,6 +3,8 @@
 //   userSigner,
 //   contentKeySigner, // optional when userSigner handles content keys internally
 //   nymSigner: optionalDefaultNymSigner,
+//   staleChannelSeconds: optionalStaleChannelRetention,
+//   identityStorageRetentionSeconds: optionalIdentityStorageRetention,
 //   channels: [{ signer: privateChannelSigner, relays, mode: 'leecher', seeders: optionalSeederPubkeys, offlineRecoverySeconds: optionalChannelOverride }],
 //   onContentKeyChange: event => reviewContentKeyUse(event),
 //   onError: err => reportPrivateMessengerError(err)
@@ -30,7 +32,7 @@
 // - Re-watching after reload fetches the gap from lastSeenAt to now.
 // - Browser offline/online events add explicit offline ranges with a small skew.
 // - Recovery defaults to 7 days and can be overridden per channel; zero disables durable recovery.
-// - Channel state not watched for 45 days is pruned.
+// - Channel state not actively leased or watched within the configured stale window is pruned.
 // - Seeders announce presence every 10min and are used for the relay-uncovered left edge of a missed range.
 // - Configured seeders are all asked; auto-discovered seeders are capped to the 8 most recently active.
 // - Seeder/watchtower channels store reconstructed router events in a separate IndexedDB queue and auto-reply to recovery asks.
@@ -47,9 +49,11 @@ import { createChannelStateStore } from './services/channel-state.js'
 import { DEFAULT_STALE_CHANNEL_SECONDS } from './constants/index.js'
 import {
   activatePrivateMessengerStorage,
+  DEFAULT_IDENTITY_STORAGE_RETENTION_SECONDS,
   maintainPrivateMessengerStorage,
   PRIVATE_MESSENGER_STORAGE_HEARTBEAT_MS,
   PRIVATE_MESSENGER_STORAGE_MAINTENANCE_MS,
+  readPrivateMessengerStorage,
   releasePrivateMessengerStorage
 } from './services/storage-maintenance.js'
 import {
@@ -66,6 +70,7 @@ import {
 } from './recovery/index.js'
 
 export { DEFAULT_STALE_CHANNEL_SECONDS } from './constants/index.js'
+export { DEFAULT_IDENTITY_STORAGE_RETENTION_SECONDS } from './services/storage-maintenance.js'
 export {
   compactSeedNymCarriers,
   compactSeedRouterRows,
@@ -81,6 +86,7 @@ export {
 
 const DEFAULT_OFFLINE_RECOVERY_SECONDS = 7 * 24 * 60 * 60
 const MAX_OFFLINE_RECOVERY_SECONDS = Math.floor(Number.MAX_SAFE_INTEGER / 1000)
+const STORAGE_POLICY_BROADCAST_CHANNEL = 'libp2r2p:private-messenger:storage-policy'
 const DEFAULT_OFFLINE_SKEW_SECONDS = 30
 const DEFAULT_RELOAD_GAP_DELAY_MS = 500
 const DEFAULT_SEEDER_PRESENCE_INTERVAL_MS = 10 * 60 * 1000
@@ -125,6 +131,20 @@ function normalizeOfflineRecoverySeconds (value) {
   return value
 }
 
+function normalizeStaleChannelSeconds (value) {
+  if (!Number.isSafeInteger(value) || value < 0 || value > MAX_OFFLINE_RECOVERY_SECONDS) {
+    throw new Error('INVALID_STALE_CHANNEL_SECONDS')
+  }
+  return value
+}
+
+function normalizeIdentityStorageRetentionSeconds (value) {
+  if (!Number.isSafeInteger(value) || value < 0 || value > MAX_OFFLINE_RECOVERY_SECONDS) {
+    throw new Error('INVALID_IDENTITY_STORAGE_RETENTION_SECONDS')
+  }
+  return value
+}
+
 function uniq (values) {
   return [...new Set((values || []).filter(Boolean))]
 }
@@ -142,6 +162,10 @@ function parseJson (raw, fallback) {
   try { return JSON.parse(raw || '') } catch { return fallback }
 }
 
+function sameStateValue (left, right) {
+  return JSON.stringify(left) === JSON.stringify(right)
+}
+
 function storesRecoverySeeds (mode) {
   return mode === 'seeder' || mode === 'watchtower'
 }
@@ -164,6 +188,7 @@ export class PrivateMessenger {
   constructor ({
     offlineRecoverySeconds = DEFAULT_OFFLINE_RECOVERY_SECONDS,
     staleChannelSeconds = DEFAULT_STALE_CHANNEL_SECONDS,
+    identityStorageRetentionSeconds = DEFAULT_IDENTITY_STORAGE_RETENTION_SECONDS,
     offlineSkewSeconds = DEFAULT_OFFLINE_SKEW_SECONDS,
     reloadGapDelayMs = DEFAULT_RELOAD_GAP_DELAY_MS,
     seederPresenceIntervalMs = DEFAULT_SEEDER_PRESENCE_INTERVAL_MS,
@@ -188,10 +213,12 @@ export class PrivateMessenger {
     _setInterval = globalThis.setInterval.bind(globalThis),
     _clearInterval = globalThis.clearInterval.bind(globalThis),
     _storageSetInterval = globalThis.setInterval.bind(globalThis),
-    _storageClearInterval = globalThis.clearInterval.bind(globalThis)
+    _storageClearInterval = globalThis.clearInterval.bind(globalThis),
+    _BroadcastChannel = _indexedDB === globalThis.indexedDB ? globalThis.BroadcastChannel : undefined
   } = {}) {
     this.offlineRecoverySeconds = normalizeOfflineRecoverySeconds(offlineRecoverySeconds)
-    this.staleChannelSeconds = staleChannelSeconds
+    this.staleChannelSeconds = normalizeStaleChannelSeconds(staleChannelSeconds)
+    this.identityStorageRetentionSeconds = normalizeIdentityStorageRetentionSeconds(identityStorageRetentionSeconds)
     this.offlineSkewSeconds = offlineSkewSeconds
     this.reloadGapDelayMs = reloadGapDelayMs
     this.seederPresenceIntervalMs = seederPresenceIntervalMs
@@ -217,6 +244,7 @@ export class PrivateMessenger {
     this._clearInterval = _clearInterval
     this._storageSetInterval = _storageSetInterval
     this._storageClearInterval = _storageClearInterval
+    this._BroadcastChannel = _BroadcastChannel
 
     this.userSigner = null
     this.contentKeySigner = null
@@ -245,6 +273,10 @@ export class PrivateMessenger {
     this.storageHeartbeatTimer = null
     this.storageMaintenanceTimer = null
     this.storageMaintenancePromise = null
+    this.storagePolicyRevision = 0
+    this.storagePolicyNeedsApply = false
+    this.storagePolicyBroadcast = null
+    this.storagePolicyRefreshTail = Promise.resolve()
     this.closePromise = null
     this.initSettledPromise = null
     this.initialized = false
@@ -264,13 +296,20 @@ export class PrivateMessenger {
       this.nymSigner = nymSigner || null
       this.userPubkey = await userSigner.getPublicKey()
       this.prefix = `libp2r2p:private-messenger:${this.userPubkey}`
-      await activatePrivateMessengerStorage({
+      const storageSnapshot = await activatePrivateMessengerStorage({
         userPubkey: this.userPubkey,
         leaseId: this.storageLeaseId,
+        activeChannelPubkeys: [],
+        storagePolicy: {
+          staleChannelSeconds: this.staleChannelSeconds,
+          identityStorageRetentionSeconds: this.identityStorageRetentionSeconds
+        },
         indexedDB: this._indexedDB
       })
+      this.applyStoragePolicySnapshot(storageSnapshot)
       this.storageActive = true
       this.lastStorageTouch = Date.now()
+      this.startStoragePolicyBroadcast()
       this.assertOpen()
       await PrivateMessenger.maintainStorage({
         indexedDB: this._indexedDB,
@@ -302,13 +341,15 @@ export class PrivateMessenger {
       this.assertOpen()
       this.startStorageMaintenance()
       this.state = { channels: await this.stateStore.load() }
-      await this.cleanupStaleChannels()
       await this.update({ userSigner, contentKeySigner, nymSigner: this.nymSigner, channels, relays, mode })
       await this.pruneStoredSeeds()
       this.initialized = true
+      await this.refreshAndApplyStoragePolicy()
+      this.broadcastStoragePolicyChange()
       return this
     } catch (err) {
       this.stopStorageMaintenance()
+      this.stopStoragePolicyBroadcast()
       try { await this.queueOperationTail } catch {}
       try { await this.stateWriteTail } catch {}
       await Promise.allSettled([
@@ -338,10 +379,102 @@ export class PrivateMessenger {
     if (this.closePromise) throw new Error('PRIVATE_MESSENGER_CLOSED')
   }
 
+  applyStoragePolicySnapshot (snapshot) {
+    if (!snapshot) return false
+    const staleChannelSeconds = normalizeStaleChannelSeconds(snapshot.staleChannelSeconds)
+    const identityStorageRetentionSeconds = normalizeIdentityStorageRetentionSeconds(
+      snapshot.identityStorageRetentionSeconds
+    )
+    const policyRevision = Math.max(0, Number(snapshot.policyRevision) || 0)
+    const changed = this.staleChannelSeconds !== staleChannelSeconds ||
+      this.identityStorageRetentionSeconds !== identityStorageRetentionSeconds
+    this.staleChannelSeconds = staleChannelSeconds
+    this.identityStorageRetentionSeconds = identityStorageRetentionSeconds
+    this.storagePolicyRevision = policyRevision
+    if (changed && this.initialized) this.storagePolicyNeedsApply = true
+    return changed
+  }
+
+  startStoragePolicyBroadcast () {
+    if (this.storagePolicyBroadcast || typeof this._BroadcastChannel !== 'function') return
+    try {
+      const channel = new this._BroadcastChannel(STORAGE_POLICY_BROADCAST_CHANNEL)
+      channel.unref?.()
+      channel.onmessage = event => {
+        const message = event?.data
+        if (message?.userPubkey !== this.userPubkey) return
+        if (!Number.isSafeInteger(message.policyRevision) || message.policyRevision <= (this.storagePolicyRevision || 0)) return
+        this.refreshAndApplyStoragePolicy().catch(err => {
+          try { this.onError?.(err) } catch {}
+        })
+      }
+      this.storagePolicyBroadcast = channel
+    } catch {}
+  }
+
+  stopStoragePolicyBroadcast () {
+    const channel = this.storagePolicyBroadcast
+    this.storagePolicyBroadcast = null
+    if (!channel) return
+    channel.onmessage = null
+    channel.close?.()
+  }
+
+  broadcastStoragePolicyChange () {
+    try {
+      this.storagePolicyBroadcast?.postMessage({
+        userPubkey: this.userPubkey,
+        policyRevision: this.storagePolicyRevision || 0
+      })
+    } catch (err) {
+      try { this.onError?.(err) } catch {}
+    }
+  }
+
+  async readStoragePolicySnapshot () {
+    if (!this.userPubkey) return null
+    const snapshot = await readPrivateMessengerStorage({
+      userPubkey: this.userPubkey,
+      indexedDB: this._indexedDB
+    })
+    this.applyStoragePolicySnapshot(snapshot)
+    return snapshot
+  }
+
+  async applyPendingStoragePolicy () {
+    if (!this.storagePolicyNeedsApply || !this.initialized || this.closePromise) return false
+    this.storagePolicyNeedsApply = false
+    try {
+      const channels = [...this.channels.values()]
+      await this.applyRecoveryPolicies(channels)
+      await this.cleanupStaleChannels()
+      const pubkeys = [...this.channels.keys()]
+      if (pubkeys.length) {
+        await this.unwatch(pubkeys)
+        await this.watch(pubkeys)
+      }
+      await this.reconcilePresencePublishers()
+      return true
+    } catch (err) {
+      this.storagePolicyNeedsApply = true
+      throw err
+    }
+  }
+
+  refreshAndApplyStoragePolicy () {
+    const previous = this.storagePolicyRefreshTail || Promise.resolve()
+    const refresh = previous.catch(() => {}).then(async () => {
+      await this.readStoragePolicySnapshot()
+      return this.applyPendingStoragePolicy()
+    })
+    this.storagePolicyRefreshTail = refresh
+    return refresh
+  }
+
   startStorageMaintenance () {
     if (this.storageHeartbeatTimer || this.storageMaintenanceTimer) return
     this.storageHeartbeatTimer = this._storageSetInterval(() => (
-      this.touchStorageActivity({ force: true }).catch(err => {
+      this.runStorageHeartbeat().catch(err => {
         try { this.onError?.(err) } catch {}
       })
     ), PRIVATE_MESSENGER_STORAGE_HEARTBEAT_MS)
@@ -362,13 +495,15 @@ export class PrivateMessenger {
 
   runStorageMaintenance () {
     if (this.storageMaintenancePromise) return this.storageMaintenancePromise
-    const maintenance = Promise.all([
-      PrivateMessenger.maintainStorage({
+    const maintenance = (async () => {
+      await PrivateMessenger.maintainStorage({
         indexedDB: this._indexedDB,
         temporaryStorageArea: this.temporaryStorageArea
-      }),
-      this.pruneStoredSeeds()
-    ]).catch(err => {
+      })
+      await this.refreshAndApplyStoragePolicy()
+      await this.cleanupStaleChannels()
+      await this.pruneStoredSeeds()
+    })().catch(err => {
       try { this.onError?.(err) } catch {}
     }).finally(() => {
       if (this.storageMaintenancePromise === maintenance) this.storageMaintenancePromise = null
@@ -377,6 +512,12 @@ export class PrivateMessenger {
     return maintenance
   }
 
+  async runStorageHeartbeat () {
+    await this.stampActiveChannelActivity()
+    await this.touchStorageActivity({ force: true })
+    await this.applyPendingStoragePolicy()
+  }
+
   async touchStorageActivity ({ force = false } = {}) {
     if (!this.storageActive || this.closePromise) return false
     if (this.storageTouchPromise) return this.storageTouchPromise
@@ -387,9 +528,13 @@ export class PrivateMessenger {
     const touch = activatePrivateMessengerStorage({
       userPubkey: this.userPubkey,
       leaseId: this.storageLeaseId,
+      activeChannelPubkeys: [...this.channels.keys()],
       indexedDB: this._indexedDB,
       now
-    }).then(() => true, err => {
+    }).then(snapshot => {
+      this.applyStoragePolicySnapshot(snapshot)
+      return true
+    }, err => {
       this.lastStorageTouch = previousTouch
       throw err
     }).finally(() => {
@@ -435,8 +580,24 @@ export class PrivateMessenger {
     })
   }
 
-  async update ({ userSigner = this.userSigner, contentKeySigner = this.contentKeySigner, nymSigner = this.nymSigner, channels = [...this.channels.values()], relays = [], mode = 'leecher' } = {}) {
+  async update (options = {}) {
     this.assertOpen()
+    const {
+      userSigner = this.userSigner,
+      contentKeySigner = this.contentKeySigner,
+      nymSigner = this.nymSigner,
+      channels = [...this.channels.values()],
+      relays = [],
+      mode = 'leecher'
+    } = options
+    const updatesStalePolicy = Object.hasOwn(options, 'staleChannelSeconds')
+    const updatesIdentityPolicy = Object.hasOwn(options, 'identityStorageRetentionSeconds')
+    let nextStaleChannelSeconds = updatesStalePolicy
+      ? normalizeStaleChannelSeconds(options.staleChannelSeconds)
+      : this.staleChannelSeconds
+    let nextIdentityStorageRetentionSeconds = updatesIdentityPolicy
+      ? normalizeIdentityStorageRetentionSeconds(options.identityStorageRetentionSeconds)
+      : this.identityStorageRetentionSeconds
     if (userSigner) {
       const userPubkey = await userSigner.getPublicKey?.()
       if (!userPubkey) throw new Error('USER_SIGNER_REQUIRED')
@@ -449,19 +610,48 @@ export class PrivateMessenger {
     const nextChannels = await this.normalizeChannels(channels, { relays, mode })
     this.assertOpen()
     const nextPubkeys = new Set(nextChannels.map(channel => channel.pubkey))
-
-    for (const pubkey of [...this.channels.keys()]) {
-      if (!nextPubkeys.has(pubkey)) {
-        await this.unwatch(pubkey)
-        this.channels.delete(pubkey)
+    const removedPubkeys = [...this.channels.keys()].filter(pubkey => !nextPubkeys.has(pubkey))
+    const updatesStoragePolicy = updatesStalePolicy || updatesIdentityPolicy
+
+    if (updatesStoragePolicy) {
+      const currentPolicy = await this.readStoragePolicySnapshot()
+      if (!updatesStalePolicy) nextStaleChannelSeconds = currentPolicy?.staleChannelSeconds ?? this.staleChannelSeconds
+      if (!updatesIdentityPolicy) {
+        nextIdentityStorageRetentionSeconds = currentPolicy?.identityStorageRetentionSeconds ?? this.identityStorageRetentionSeconds
       }
     }
+
+    if (removedPubkeys.length) {
+      await this.stampChannelActivity(removedPubkeys)
+    }
+
+    const storageSnapshot = await activatePrivateMessengerStorage({
+      userPubkey: this.userPubkey,
+      leaseId: this.storageLeaseId,
+      activeChannelPubkeys: [...nextPubkeys],
+      storagePolicy: updatesStoragePolicy
+        ? {
+            staleChannelSeconds: nextStaleChannelSeconds,
+            identityStorageRetentionSeconds: nextIdentityStorageRetentionSeconds
+          }
+        : undefined,
+      indexedDB: this._indexedDB
+    })
+    this.applyStoragePolicySnapshot(storageSnapshot)
+    this.lastStorageTouch = Date.now()
+    if (updatesStoragePolicy) this.broadcastStoragePolicyChange()
+
+    await this.unwatch([...this.channels.keys()])
+    this.channels.clear()
     for (const channel of nextChannels) this.channels.set(channel.pubkey, channel)
 
-    await this.cleanupStaleChannels()
+    await this.cleanupStaleChannels({ storageSnapshot })
     await this.applyRecoveryPolicies(nextChannels)
     await this.watch()
     await this.reconcilePresencePublishers()
+    if (this.storagePolicyRevision === storageSnapshot.policyRevision) {
+      this.storagePolicyNeedsApply = false
+    }
     return this
   }
 
@@ -551,14 +741,19 @@ export class PrivateMessenger {
     return structuredClone(this.state)
   }
 
-  writeState (state) {
-    this.touchStorageActivity().catch(err => this.onError?.(err))
+  writeState (state, { touchStorage = true } = {}) {
+    if (touchStorage) this.touchStorageActivity().catch(err => this.onError?.(err))
+    const previous = this.state?.channels || {}
     const next = {
       channels: isPlainObject(state?.channels) ? structuredClone(state.channels) : {}
     }
+    const changed = Object.fromEntries(Object.entries(next.channels)
+      .filter(([pubkey, value]) => !sameStateValue(previous[pubkey], value)))
+    const removed = Object.keys(previous).filter(pubkey => !Object.hasOwn(next.channels, pubkey))
     this.state = next
-    const snapshot = structuredClone(next.channels)
-    const write = this.stateWriteTail.then(() => this.stateStore.replace(snapshot))
+    if (!Object.keys(changed).length && !removed.length) return this.stateWriteTail
+    const snapshot = structuredClone(changed)
+    const write = this.stateWriteTail.then(() => this.stateStore.update(snapshot, removed))
     this.stateWriteTail = write.catch(err => {
       try { this.onError?.(err) } catch {}
     })
@@ -569,6 +764,29 @@ export class PrivateMessenger {
     await this.stateWriteTail
   }
 
+  async stampChannelActivity (pubkeys) {
+    if (!this.stateStore || !this.state) return false
+    pubkeys = [...new Set(pubkeys || [])].filter(pubkey => this.state.channels[pubkey])
+    if (!pubkeys.length) return false
+    const lastWatchedAt = nowSeconds()
+    for (const pubkey of pubkeys) {
+      this.state.channels[pubkey] = {
+        ...this.state.channels[pubkey],
+        lastWatchedAt
+      }
+    }
+    const write = this.stateWriteTail.then(() => this.stateStore.touch(pubkeys, lastWatchedAt))
+    this.stateWriteTail = write.catch(err => {
+      try { this.onError?.(err) } catch {}
+    })
+    await write
+    return true
+  }
+
+  stampActiveChannelActivity () {
+    return this.stampChannelActivity([...this.channels.keys()])
+  }
+
   updateChannelState (pubkey, patch) {
     const state = this.readState()
     const current = state.channels[pubkey] || {}
@@ -578,9 +796,19 @@ export class PrivateMessenger {
   }
 
   removeChannelState (pubkey) {
-    const state = this.readState()
-    delete state.channels[pubkey]
-    this.writeState(state)
+    this.removeChannelStates([pubkey])
+  }
+
+  removeChannelStates (pubkeys) {
+    pubkeys = [...new Set(pubkeys || [])]
+    for (const pubkey of pubkeys) delete this.state.channels[pubkey]
+    if (!pubkeys.length) return this.stateWriteTail
+    this.touchStorageActivity().catch(err => this.onError?.(err))
+    const write = this.stateWriteTail.then(() => this.stateStore.update({}, pubkeys))
+    this.stateWriteTail = write.catch(err => {
+      try { this.onError?.(err) } catch {}
+    })
+    return write
   }
 
   markSeen (pubkey, createdAt = nowSeconds()) {
@@ -1270,7 +1498,7 @@ export class PrivateMessenger {
     return channel.autoDeletionCapability ?? this.autoDeletionCapability
   }
 
-  offlineRecoverySecondsFor (channelOrPubkey) {
+  requestedOfflineRecoverySecondsFor (channelOrPubkey) {
     const channel = typeof channelOrPubkey === 'string'
       ? this.channels.get(channelOrPubkey)
       : channelOrPubkey
@@ -1282,6 +1510,18 @@ export class PrivateMessenger {
       : normalizeOfflineRecoverySeconds(persisted)
   }
 
+  offlineRecoverySecondsFor (channelOrPubkey) {
+    return Math.min(
+      this.requestedOfflineRecoverySecondsFor(channelOrPubkey),
+      this.staleChannelSeconds,
+      this.identityStorageRetentionSeconds
+    )
+  }
+
+  staleChannelSecondsForCleanup () {
+    return Math.min(this.staleChannelSeconds, this.identityStorageRetentionSeconds)
+  }
+
   eventExpirationSecondsFor (channel) {
     return this.offlineRecoverySecondsFor(channel) || privateChannel.EXPIRATION_SECONDS
   }
@@ -1297,13 +1537,14 @@ export class PrivateMessenger {
       const now = nowSeconds()
       for (const channel of channels) {
         const current = state.channels[channel.pubkey] || {}
-        const seconds = channel.offlineRecoverySeconds
-        current.offlineRecoverySeconds = seconds
-        if (!seconds) {
+        const requestedSeconds = channel.offlineRecoverySeconds
+        const effectiveSeconds = this.offlineRecoverySecondsFor(channel)
+        current.offlineRecoverySeconds = requestedSeconds
+        if (!effectiveSeconds) {
           delete current.openOfflineStart
           current.offlineRanges = []
         } else {
-          const cutoff = now - seconds
+          const cutoff = now - effectiveSeconds
           current.offlineRanges = mergeRanges((current.offlineRanges || [])
             .filter(range => range.end >= cutoff)
             .map(range => ({ ...range, start: Math.max(range.start, cutoff) })))
@@ -1568,6 +1809,7 @@ export class PrivateMessenger {
       await this.flushStateWrites()
       await this.queue.removeBy('byChannel', pubkey)
       await this.seedQueue.removeBy('byChannel', pubkey)
+      await this.touchStorageActivity({ force: true })
       this.ensureRelayListWatcher()
     })
   }
@@ -1576,19 +1818,26 @@ export class PrivateMessenger {
     return this.runQueueOperation(() => this.queue.clear())
   }
 
-  async cleanupStaleChannels () {
+  async cleanupStaleChannels ({ storageSnapshot } = {}) {
     if (!this.prefix) return
+    storageSnapshot ||= await this.readStoragePolicySnapshot()
+    if (!storageSnapshot) return
+    const activeChannelPubkeys = new Set(storageSnapshot.activeChannelPubkeys || [])
     return this.runQueueOperation(async () => {
-      const state = this.readState()
-      const cutoff = nowSeconds() - this.staleChannelSeconds
+      await this.flushStateWrites()
+      const state = { channels: await this.stateStore.load() }
+      const cutoff = nowSeconds() - this.staleChannelSecondsForCleanup()
+      const stalePubkeys = []
       for (const [pubkey, channel] of Object.entries(state.channels)) {
+        if (activeChannelPubkeys.has(pubkey)) continue
         if ((channel.lastWatchedAt || 0) >= cutoff) continue
         delete state.channels[pubkey]
+        stalePubkeys.push(pubkey)
         await this.queue?.removeBy('byChannel', pubkey)
         await this.seedQueue?.removeBy('byChannel', pubkey)
       }
-      this.writeState(state)
-      await this.flushStateWrites()
+      this.state = state
+      if (stalePubkeys.length) await this.removeChannelStates(stalePubkeys)
     })
   }
 
@@ -1636,15 +1885,18 @@ export class PrivateMessenger {
     this.stopOffline = null
     this.stopOnline = null
     this.stopStorageMaintenance()
+    this.stopStoragePolicyBroadcast()
 
     this.closePromise = (async () => {
       let unwatchError
       try { await unwatchPromise } catch (err) { unwatchError = err }
       await initSettledPromise
+      await this.stampActiveChannelActivity()
       await this.queueOperationTail
       await this.stateWriteTail
       try { await this.storageTouchPromise } catch {}
       await this.storageMaintenancePromise
+      try { await this.storagePolicyRefreshTail } catch {}
       await Promise.all([
         this.queue?.close?.(),
         this.seedQueue?.close?.(),
@@ -1658,6 +1910,12 @@ export class PrivateMessenger {
         })
       }
       this.storageActive = false
+      if (this.identityStorageRetentionSeconds === 0) {
+        await PrivateMessenger.maintainStorage({
+          indexedDB: this._indexedDB,
+          temporaryStorageArea: this.temporaryStorageArea
+        })
+      }
       if (unwatchError) throw unwatchError
     })()
     return this.closePromise

package/private-messenger/services/channel-state.js

@@ -11,12 +11,14 @@ database `${prefix}:state:idb`, version 1
 channels, keyPath "pubkey"
   pubkey  watched channel public key
   value   evolving channel-recovery state, including last-seen/watched times,
-          mode, relays, seeders, effective offline-recovery retention, offline
+          mode, relays, seeders, requested offline-recovery retention, offline
           ranges, active offline-range start,
           per-seeder activity, and sent/received content-key usage
 
-The complete channels snapshot is replaced atomically on each persisted state
-change; value remains an extensible internal object rather than a public schema.
+Changed channel records are upserted individually and explicit removals are
+applied in the same transaction. This prevents one active instance from
+clearing state owned by another instance of the same principal identity.
+`value` remains an extensible internal object rather than a public schema.
 */
 
 function deferred () {
@@ -108,16 +110,34 @@ export async function createChannelStateStore ({ prefix, indexedDB = globalThis.
     })
   }
 
-  async function replace (channels) {
+  async function update (channels, removedPubkeys = []) {
     const snapshot = cloneChannels(channels)
+    const removals = [...new Set(removedPubkeys || [])]
     await runTransaction('readwrite', async tx => {
-      await run('clear', [], CHANNELS_STORE, null, { tx })
+      for (const pubkey of removals) await run('delete', [pubkey], CHANNELS_STORE, null, { tx })
       for (const [pubkey, value] of Object.entries(snapshot)) {
         await run('put', [{ pubkey, value }], CHANNELS_STORE, null, { tx })
       }
     })
   }
 
+  async function touch (pubkeys, lastWatchedAt) {
+    const uniquePubkeys = [...new Set(pubkeys || [])]
+    if (!uniquePubkeys.length) return
+    await runTransaction('readwrite', async tx => {
+      for (const pubkey of uniquePubkeys) {
+        const current = (await run('get', [pubkey], CHANNELS_STORE, null, { tx })).result
+        await run('put', [{
+          pubkey,
+          value: {
+            ...(current?.value && typeof current.value === 'object' ? current.value : {}),
+            lastWatchedAt
+          }
+        }], CHANNELS_STORE, null, { tx })
+      }
+    })
+  }
+
   function close () {
     if (closePromise) return closePromise
     closed = true
@@ -128,5 +148,5 @@ export async function createChannelStateStore ({ prefix, indexedDB = globalThis.
     return closePromise
   }
 
-  return { load, replace, close }
+  return { load, update, touch, close }
 }

package/private-messenger/services/storage-maintenance.js

@@ -1,14 +1,16 @@
 import { run } from '../../idb/index.js'
 import { cleanupReceivedChunkStorage } from '../../private-channel/services/received-chunks.js'
 import { cleanupTemporaryStorage } from '../../temporary-storage/index.js'
+import { DEFAULT_STALE_CHANNEL_SECONDS } from '../constants/index.js'
 
 const REGISTRY_DATABASE = 'libp2r2p:private-messenger:registry:idb'
 const REGISTRY_VERSION = 1
-const BUNDLES_STORE = 'bundles'
+const STORAGE_SETS_STORE = 'storageSets'
 const LEASES_STORE = 'leases'
 const LOCK_NAME = 'libp2r2p:private-messenger:storage-maintenance'
 const LEASE_MS = 2 * 60 * 60 * 1000 // 2 hours
-const RETENTION_MS = 60 * 24 * 60 * 60 * 1000 // 60 days
+const DEFAULT_IDENTITY_STORAGE_RETENTION_SECONDS = 60 * 24 * 60 * 60
+const MAX_RETENTION_SECONDS = Math.floor(Number.MAX_SAFE_INTEGER / 1000)
 const MAX_RETRY_MS = 5 * 60 * 1000
 
 const localLocks = new WeakMap()
@@ -19,19 +21,23 @@ IndexedDB schema, shared by every PrivateMessenger instance on this origin:
 
 database "libp2r2p:private-messenger:registry:idb", version 1
 
-bundles, keyPath "userPubkey"
+storageSets, keyPath "userPubkey"
   userPubkey    primary signer public key and storage-set coordinate
   lastUsedAt    most recent durable activity in milliseconds
   leaseUntil    active-instance lease expiry in milliseconds
   status        "ready" or "delete_pending"
   attempts      consecutive failed storage-set deletions
   nextAttemptAt earliest retry time in milliseconds
+  staleChannelSeconds channel-state retention requested by the last configuring instance
+  identityStorageRetentionSeconds identity database-set retention after its last activity
+  policyRevision monotonically increasing storage-policy revision
 
 leases, keyPath "key"
   key         `${userPubkey}:${leaseId}`
   userPubkey  principal signer public key
   leaseId     per-PrivateMessenger instance identifier
   leaseUntil  instance lease expiry in milliseconds
+  activeChannelPubkeys channels currently administered by that instance
 
 leases indexes
   byUserPubkey  userPubkey
@@ -53,8 +59,8 @@ function openRegistry (indexedDB) {
     request.onblocked = () => reject(new Error('IDB_DATABASE_BLOCKED'))
     request.onupgradeneeded = () => {
       const db = request.result
-      if (!db.objectStoreNames.contains(BUNDLES_STORE)) {
-        db.createObjectStore(BUNDLES_STORE, { keyPath: 'userPubkey' })
+      if (!db.objectStoreNames.contains(STORAGE_SETS_STORE)) {
+        db.createObjectStore(STORAGE_SETS_STORE, { keyPath: 'userPubkey' })
       }
       if (!db.objectStoreNames.contains(LEASES_STORE)) {
         const leases = db.createObjectStore(LEASES_STORE, { keyPath: 'key' })
@@ -72,7 +78,7 @@ function openRegistry (indexedDB) {
 async function withRegistryTransaction (indexedDB, mode, work) {
   const db = await openRegistry(indexedDB)
   try {
-    const tx = db.transaction([BUNDLES_STORE, LEASES_STORE], mode)
+    const tx = db.transaction([STORAGE_SETS_STORE, LEASES_STORE], mode)
     const done = transactionDone(tx)
     try {
       const result = await work(tx)
@@ -100,9 +106,20 @@ async function readLeases (tx, userPubkey) {
   return records.filter(record => record?.userPubkey === userPubkey)
 }
 
-async function refreshLeaseUntil (tx, bundle, now, { removeExpired = false } = {}) {
-  const leases = await readLeases(tx, bundle.userPubkey)
+function normalizeRetentionSeconds (value, fallback) {
+  return Number.isSafeInteger(value) && value >= 0 && value <= MAX_RETENTION_SECONDS
+    ? value
+    : fallback
+}
+
+function normalizeActiveChannelPubkeys (values) {
+  return [...new Set((values || []).filter(value => typeof value === 'string' && value))].sort()
+}
+
+async function refreshLeaseState (tx, storageSet, now, { removeExpired = false } = {}) {
+  const leases = await readLeases(tx, storageSet.userPubkey)
   let leaseUntil = 0
+  const activeChannelPubkeys = new Set()
   for (const lease of leases) {
     const expiresAt = Math.max(0, Number(lease.leaseUntil) || 0)
     if (expiresAt <= now) {
@@ -110,12 +127,18 @@ async function refreshLeaseUntil (tx, bundle, now, { removeExpired = false } = {
       continue
     }
     leaseUntil = Math.max(leaseUntil, expiresAt)
+    for (const pubkey of normalizeActiveChannelPubkeys(lease.activeChannelPubkeys)) {
+      activeChannelPubkeys.add(pubkey)
+    }
+  }
+  storageSet.leaseUntil = leaseUntil
+  return {
+    leaseUntil,
+    activeChannelPubkeys: [...activeChannelPubkeys].sort()
   }
-  bundle.leaseUntil = leaseUntil
-  return leaseUntil
 }
 
-function normalizeBundle (record) {
+function normalizeStorageSet (record) {
   if (!record?.userPubkey) return null
   return {
     userPubkey: String(record.userPubkey),
@@ -123,7 +146,24 @@ function normalizeBundle (record) {
     leaseUntil: Math.max(0, Number(record.leaseUntil) || 0),
     status: record.status === 'delete_pending' ? 'delete_pending' : 'ready',
     attempts: Math.max(0, Math.floor(Number(record.attempts) || 0)),
-    nextAttemptAt: Math.max(0, Number(record.nextAttemptAt) || 0)
+    nextAttemptAt: Math.max(0, Number(record.nextAttemptAt) || 0),
+    staleChannelSeconds: normalizeRetentionSeconds(
+      record.staleChannelSeconds,
+      DEFAULT_STALE_CHANNEL_SECONDS
+    ),
+    identityStorageRetentionSeconds: normalizeRetentionSeconds(
+      record.identityStorageRetentionSeconds,
+      DEFAULT_IDENTITY_STORAGE_RETENTION_SECONDS
+    ),
+    policyRevision: Math.max(0, Math.floor(Number(record.policyRevision) || 0))
+  }
+}
+
+function storagePolicy (storageSet) {
+  return {
+    staleChannelSeconds: storageSet.staleChannelSeconds,
+    identityStorageRetentionSeconds: storageSet.identityStorageRetentionSeconds,
+    policyRevision: storageSet.policyRevision
   }
 }
 
@@ -178,23 +218,29 @@ function retryDelay (attempts) {
   return Math.min(MAX_RETRY_MS, 1000 * (2 ** Math.min(9, Math.max(0, attempts - 1))))
 }
 
-async function markAndListDueBundles (indexedDB, now) {
+async function markAndListDueStorageSets (indexedDB, now) {
   return withRegistryTransaction(indexedDB, 'readwrite', async tx => {
-    const records = (await run('getAll', [], BUNDLES_STORE, null, { tx })).result
+    const records = (await run('getAll', [], STORAGE_SETS_STORE, null, { tx })).result
     const due = []
     for (const raw of records) {
-      const bundle = normalizeBundle(raw)
-      if (!bundle) continue
-      await refreshLeaseUntil(tx, bundle, now, { removeExpired: true })
-      const leaseActive = bundle.leaseUntil > now
-      if (bundle.status === 'ready' && !leaseActive && bundle.lastUsedAt + RETENTION_MS <= now) {
-        bundle.status = 'delete_pending'
-        bundle.attempts = 0
-        bundle.nextAttemptAt = now
+      const storageSet = normalizeStorageSet(raw)
+      if (!storageSet) continue
+      await refreshLeaseState(tx, storageSet, now, { removeExpired: true })
+      const leaseActive = storageSet.leaseUntil > now
+      const retentionMs = storageSet.identityStorageRetentionSeconds * 1000
+      const expired = storageSet.lastUsedAt + retentionMs <= now
+      if (leaseActive || !expired) {
+        storageSet.status = 'ready'
+        storageSet.attempts = 0
+        storageSet.nextAttemptAt = 0
+      } else if (storageSet.status === 'ready') {
+        storageSet.status = 'delete_pending'
+        storageSet.attempts = 0
+        storageSet.nextAttemptAt = now
       }
-      await run('put', [bundle], BUNDLES_STORE, null, { tx })
-      if (bundle.status === 'delete_pending' && !leaseActive && bundle.nextAttemptAt <= now) {
-        due.push(bundle)
+      await run('put', [storageSet], STORAGE_SETS_STORE, null, { tx })
+      if (storageSet.status === 'delete_pending' && !leaseActive && storageSet.nextAttemptAt <= now) {
+        due.push(storageSet)
       }
     }
     return due
@@ -203,35 +249,43 @@ async function markAndListDueBundles (indexedDB, now) {
 
 async function finishDeleteAttempt (indexedDB, attempted, deleted, now) {
   return withRegistryTransaction(indexedDB, 'readwrite', async tx => {
-    const current = normalizeBundle((await run('get', [attempted.userPubkey], BUNDLES_STORE, null, { tx })).result)
-    if (!current || current.status !== 'delete_pending' || current.leaseUntil > now) return false
+    const current = normalizeStorageSet((await run('get', [attempted.userPubkey], STORAGE_SETS_STORE, null, { tx })).result)
+    if (!current || current.status !== 'delete_pending') return false
+    await refreshLeaseState(tx, current, now, { removeExpired: true })
+    if (current.leaseUntil > now) {
+      current.status = 'ready'
+      current.attempts = 0
+      current.nextAttemptAt = 0
+      await run('put', [current], STORAGE_SETS_STORE, null, { tx })
+      return false
+    }
     if (deleted) {
       for (const lease of await readLeases(tx, attempted.userPubkey)) {
         await run('delete', [lease.key], LEASES_STORE, null, { tx })
       }
-      await run('delete', [attempted.userPubkey], BUNDLES_STORE, null, { tx })
+      await run('delete', [attempted.userPubkey], STORAGE_SETS_STORE, null, { tx })
       return true
     }
     current.attempts++
     current.nextAttemptAt = now + retryDelay(current.attempts)
-    await run('put', [current], BUNDLES_STORE, null, { tx })
+    await run('put', [current], STORAGE_SETS_STORE, null, { tx })
     return false
   })
 }
 
 async function maintainRegistry (indexedDB, now) {
-  const due = await markAndListDueBundles(indexedDB, now)
-  for (const bundle of due) {
-    const deleted = await deleteStorageSet(indexedDB, bundle.userPubkey)
-    await finishDeleteAttempt(indexedDB, bundle, deleted, now)
+  const due = await markAndListDueStorageSets(indexedDB, now)
+  for (const storageSet of due) {
+    const deleted = await deleteStorageSet(indexedDB, storageSet.userPubkey)
+    await finishDeleteAttempt(indexedDB, storageSet, deleted, now)
   }
   const nextAttemptAt = await withRegistryTransaction(indexedDB, 'readonly', async tx => {
-    const records = (await run('getAll', [], BUNDLES_STORE, null, { tx })).result
+    const records = (await run('getAll', [], STORAGE_SETS_STORE, null, { tx })).result
     let earliest = Infinity
     for (const raw of records) {
-      const bundle = normalizeBundle(raw)
-      if (bundle?.status !== 'delete_pending' || bundle.leaseUntil > now) continue
-      earliest = Math.min(earliest, bundle.nextAttemptAt)
+      const storageSet = normalizeStorageSet(raw)
+      if (storageSet?.status !== 'delete_pending' || storageSet.leaseUntil > now) continue
+      earliest = Math.min(earliest, storageSet.nextAttemptAt)
     }
     return Number.isFinite(earliest) ? earliest : null
   })
@@ -268,6 +322,8 @@ export async function maintainPrivateMessengerStorage ({
 export function activatePrivateMessengerStorage ({
   userPubkey,
   leaseId,
+  activeChannelPubkeys,
+  storagePolicy: nextPolicy,
   indexedDB = globalThis.indexedDB,
   now = Date.now()
 } = {}) {
@@ -276,22 +332,61 @@ export function activatePrivateMessengerStorage ({
   return withMaintenanceLock(indexedDB, () => withRegistryTransaction(indexedDB, 'readwrite', async tx => {
     userPubkey = String(userPubkey)
     leaseId = String(leaseId)
-    const current = normalizeBundle((await run('get', [userPubkey], BUNDLES_STORE, null, { tx })).result)
+    const current = normalizeStorageSet((await run('get', [userPubkey], STORAGE_SETS_STORE, null, { tx })).result)
+    const currentLease = (await run('get', [leaseKey(userPubkey, leaseId)], LEASES_STORE, null, { tx })).result
+    const channels = activeChannelPubkeys === undefined
+      ? normalizeActiveChannelPubkeys(currentLease?.activeChannelPubkeys)
+      : normalizeActiveChannelPubkeys(activeChannelPubkeys)
     await run('put', [{
       key: leaseKey(userPubkey, leaseId),
       userPubkey,
       leaseId,
-      leaseUntil: now + LEASE_MS
+      leaseUntil: now + LEASE_MS,
+      activeChannelPubkeys: channels
     }], LEASES_STORE, null, { tx })
-    const bundle = {
+    const hasPolicy = nextPolicy !== undefined
+    const storageSet = {
       userPubkey,
       lastUsedAt: now,
       leaseUntil: Math.max(current?.leaseUntil || 0, now + LEASE_MS),
       status: 'ready',
       attempts: 0,
-      nextAttemptAt: 0
+      nextAttemptAt: 0,
+      staleChannelSeconds: hasPolicy
+        ? nextPolicy.staleChannelSeconds
+        : current?.staleChannelSeconds ?? DEFAULT_STALE_CHANNEL_SECONDS,
+      identityStorageRetentionSeconds: hasPolicy
+        ? nextPolicy.identityStorageRetentionSeconds
+        : current?.identityStorageRetentionSeconds ?? DEFAULT_IDENTITY_STORAGE_RETENTION_SECONDS,
+      policyRevision: hasPolicy
+        ? (current?.policyRevision || 0) + 1
+        : current?.policyRevision || 0
+    }
+    await run('put', [storageSet], STORAGE_SETS_STORE, null, { tx })
+    const leaseState = await refreshLeaseState(tx, storageSet, now)
+    return {
+      ...storagePolicy(storageSet),
+      activeChannelPubkeys: leaseState.activeChannelPubkeys
+    }
+  }))
+}
+
+export function readPrivateMessengerStorage ({
+  userPubkey,
+  indexedDB = globalThis.indexedDB,
+  now = Date.now()
+} = {}) {
+  if (!userPubkey) return Promise.reject(new Error('USER_PUBKEY_REQUIRED'))
+  return withMaintenanceLock(indexedDB, () => withRegistryTransaction(indexedDB, 'readwrite', async tx => {
+    userPubkey = String(userPubkey)
+    const storageSet = normalizeStorageSet((await run('get', [userPubkey], STORAGE_SETS_STORE, null, { tx })).result)
+    if (!storageSet) return null
+    const leaseState = await refreshLeaseState(tx, storageSet, now, { removeExpired: true })
+    await run('put', [storageSet], STORAGE_SETS_STORE, null, { tx })
+    return {
+      ...storagePolicy(storageSet),
+      activeChannelPubkeys: leaseState.activeChannelPubkeys
     }
-    await run('put', [bundle], BUNDLES_STORE, null, { tx })
   }))
 }
 
@@ -306,19 +401,20 @@ export function releasePrivateMessengerStorage ({
   return withMaintenanceLock(indexedDB, () => withRegistryTransaction(indexedDB, 'readwrite', async tx => {
     userPubkey = String(userPubkey)
     leaseId = String(leaseId)
-    const current = normalizeBundle((await run('get', [userPubkey], BUNDLES_STORE, null, { tx })).result)
+    const current = normalizeStorageSet((await run('get', [userPubkey], STORAGE_SETS_STORE, null, { tx })).result)
     if (!current) return false
     await run('delete', [leaseKey(userPubkey, leaseId)], LEASES_STORE, null, { tx })
-    await refreshLeaseUntil(tx, current, now, { removeExpired: true })
+    await refreshLeaseState(tx, current, now, { removeExpired: true })
     current.lastUsedAt = now
     current.status = 'ready'
     current.attempts = 0
     current.nextAttemptAt = 0
-    await run('put', [current], BUNDLES_STORE, null, { tx })
+    await run('put', [current], STORAGE_SETS_STORE, null, { tx })
     return true
   }))
 }
 
 export const PRIVATE_MESSENGER_STORAGE_HEARTBEAT_MS = 60 * 60 * 1000
 export const PRIVATE_MESSENGER_STORAGE_MAINTENANCE_MS = 6 * 60 * 60 * 1000
-export const PRIVATE_MESSENGER_STORAGE_RETENTION_MS = RETENTION_MS
+export const PRIVATE_MESSENGER_IDENTITY_STORAGE_RETENTION_MS = DEFAULT_IDENTITY_STORAGE_RETENTION_SECONDS * 1000
+export { DEFAULT_IDENTITY_STORAGE_RETENTION_SECONDS }