libp2r2p 0.10.28 → 0.11.1

package/private-messenger/index.js

@@ -201,6 +201,7 @@ export class PrivateMessenger {
     maxDynamicRecoverySeeders = DEFAULT_MAX_DYNAMIC_RECOVERY_SEEDERS,
     messageQueueMaxBytes = DEFAULT_MESSAGE_QUEUE_MAX_BYTES,
     seedQueueMaxBytes = DEFAULT_SEED_QUEUE_MAX_BYTES,
+    seedStorage,
     temporaryStorageArea = globalThis.sessionStorage,
     autoDeletionCapability = true,
     _indexedDB = globalThis.indexedDB,
@@ -232,6 +233,7 @@ export class PrivateMessenger {
     this.maxDynamicRecoverySeeders = maxDynamicRecoverySeeders
     this.messageQueueMaxBytes = messageQueueMaxBytes
     this.seedQueueMaxBytes = seedQueueMaxBytes
+    this.seedStorage = seedStorage
     this.temporaryStorageArea = temporaryStorageArea
     this.autoDeletionCapability = normalizeAutoDeletionCapability(autoDeletionCapability)
     this._indexedDB = _indexedDB
@@ -265,6 +267,7 @@ export class PrivateMessenger {
     this.state = { channels: {} }
     this.stateWriteTail = Promise.resolve()
     this.stateWriteError = null
+    this.extensions = new Set()
     this.channels = new Map()
     this.stopByChannel = new Map()
     this.desiredChannels = new Set()
@@ -347,13 +350,15 @@ export class PrivateMessenger {
         indexedDB: this._indexedDB
       })
       this.assertOpen()
-      this.seedQueue = await createQueue({
-        prefix: `${this.prefix}:seeds`,
-        indexes: SEED_QUEUE_INDEXES,
-        maxBytes: this.seedQueueMaxBytes,
-        evictionPolicy: 'fifo',
-        indexedDB: this._indexedDB
-      })
+      this.seedQueue = this.seedStorage
+        ? null
+        : await createQueue({
+          prefix: `${this.prefix}:seeds`,
+          indexes: SEED_QUEUE_INDEXES,
+          maxBytes: this.seedQueueMaxBytes,
+          evictionPolicy: 'fifo',
+          indexedDB: this._indexedDB
+        })
       this.assertOpen()
       this.stateStore = await createChannelStateStore({
         prefix: this.prefix,
@@ -1128,6 +1133,7 @@ export class PrivateMessenger {
 
   unwatch (channels) {
     const pubkeys = channels ? uniq(Array.isArray(channels) ? channels : [channels]) : [...this.desiredChannels]
+    for (const extension of this.extensions) extension.unwatch?.(pubkeys)
     for (const pubkey of pubkeys) this.desiredChannels.delete(pubkey)
     this.recordInterruption(pubkeys)
     for (const controller of this.recoveryControllers) {
@@ -1140,6 +1146,7 @@ export class PrivateMessenger {
     if (typeof reason !== 'string' || !reason.trim()) throw new ValidationError('PAUSE_REASON_REQUIRED')
     this.assertOpen()
     this.pauseReasons.add(reason)
+    for (const extension of this.extensions) extension.pause?.()
     this.recordInterruption(this.desiredChannels)
     for (const controller of this.recoveryControllers) controller.abort()
     return Promise.all([this.stopWatches([...this.desiredChannels]), this.flushStateWrites()])
@@ -1164,6 +1171,7 @@ export class PrivateMessenger {
       if (this.pauseReasons.size || this.closePromise) return
       await this.reconcilePresencePublishers()
       await this.recoverOfflineRanges(channels)
+      for (const extension of this.extensions) await extension.resume?.()
     })()
     this.resumeWork = work
     try { await work } catch (err) {
@@ -1238,6 +1246,7 @@ export class PrivateMessenger {
   async handleAsk (channelPubkey, message) {
     if (message.provenance === 'hearsay') return this.enqueueRumor('message', channelPubkey, message)
     this.trackSeederActivity(channelPubkey, message)
+    for (const extension of this.extensions) if (await extension.handleAsk?.(channelPubkey, message)) return
     if (doesModeStoreRecoverySeeds(this.channels.get(channelPubkey)?.mode) && messageCode(message) === MISSING_MESSAGES_ASK_CODE) {
       await this.replyWithStoredSeeds(channelPubkey, message)
       return
@@ -1329,9 +1338,24 @@ export class PrivateMessenger {
     this.onMessageQueued?.()
   }
 
+  outgoingSeedHandler (channelPubkey) {
+    if (!doesModeStoreRecoverySeeds(this.channels.get(channelPubkey)?.mode) || !this.offlineRecoverySecondsFor(channelPubkey)) return undefined
+    return seed => this.enqueueSeed(channelPubkey, seed)
+  }
+
   async enqueueSeed (channelPubkey, seed) {
     if (!this.offlineRecoverySecondsFor(channelPubkey)) return
     const receivedAt = nowSeconds()
+    if (this.seedStorage) {
+      const rows = seed.recordType === NYM_CARRIER_SEED_RECORD_TYPE || seed.carriers?.length
+        ? [{ recordType: NYM_CARRIER_SEED_RECORD_TYPE, carriers: compactSeedNymCarriers(seed.carriers) }]
+        : compactSeedRouterRows(seed)
+      for (const row of rows) {
+        const time = seedRecordTime(row) || receivedAt
+        await this.seedStorage.put({ ...row, channelPubkey, receivedAt, expiresAt: time + this.offlineRecoverySecondsFor(channelPubkey) })
+      }
+      return
+    }
     if (seed.recordType === NYM_CARRIER_SEED_RECORD_TYPE || seed.carriers?.length) {
       const carriers = compactSeedNymCarriers(seed.carriers)
       const recordTime = nymCarrierRecordTime({ carriers }) || seed.outer?.created_at || receivedAt
@@ -1494,6 +1518,7 @@ export class PrivateMessenger {
       payload,
       error,
       content,
+      onPreparedSeed: this.outgoingSeedHandler(channelPubkey),
       _getIykcProofs: this.contentKeyLookup()
     })
   }
@@ -1520,6 +1545,7 @@ export class PrivateMessenger {
       payload,
       error,
       content,
+      onPreparedSeed: this.outgoingSeedHandler(channelPubkey),
       _getIykcProofs: this.contentKeyLookup()
     })
   }
@@ -1544,6 +1570,7 @@ export class PrivateMessenger {
       payload,
       error,
       content,
+      onPreparedSeed: this.outgoingSeedHandler(channelPubkey),
       _getIykcProofs: this.contentKeyLookup()
     })
   }
@@ -1568,6 +1595,7 @@ export class PrivateMessenger {
       payload,
       error,
       content,
+      onPreparedSeed: this.outgoingSeedHandler(channelPubkey),
       _getIykcProofs: this.contentKeyLookup()
     })
   }
@@ -1588,6 +1616,7 @@ export class PrivateMessenger {
       deletionPubkey,
       autoDeletionCapability: this.autoDeletionCapabilityFor(channel),
       rumor,
+      onPreparedSeed: this.outgoingSeedHandler(channelPubkey),
       _getIykcProofs: this.contentKeyLookup()
     })
   }
@@ -1608,6 +1637,7 @@ export class PrivateMessenger {
       deletionPubkey,
       autoDeletionCapability: this.autoDeletionCapabilityFor(channel),
       event,
+      onPreparedSeed: this.outgoingSeedHandler(channelPubkey),
       _getIykcProofs: this.contentKeyLookup()
     })
   }
@@ -1664,6 +1694,7 @@ export class PrivateMessenger {
       autoDeletionCapability: this.autoDeletionCapabilityFor(channel),
       code: SEEDER_PRESENCE_CODE,
       payload: {},
+      onPreparedSeed: this.outgoingSeedHandler(channelPubkey),
       _getIykcProofs: this.contentKeyLookup()
     })
   }
@@ -1915,7 +1946,9 @@ export class PrivateMessenger {
     })
 
     if (this.offlineRecoverySecondsFor(channelPubkey)) {
-      for await (const seed of this.seedQueue.storedItemsBy('byChannel', channelPubkey)) {
+      for await (const seed of this.seedStorage ? this.seedStorage.iterate({ channelPubkey, receiverPubkey: message.event?.pubkey, since, until }) : this.seedQueue.storedItemsBy('byChannel', channelPubkey)) {
+        if (seedRecordTime(seed) < nowSeconds() - this.offlineRecoverySecondsFor(channelPubkey)) continue
+        if (this.seedStorage && !await this.seedStorage.has(seed)) continue
         await packer.update(seed)
       }
     }
@@ -2091,7 +2124,7 @@ export class PrivateMessenger {
       this.removeChannelState(pubkey)
       await this.flushStateWrites()
       await this.queue.removeBy('byChannel', pubkey)
-      await this.seedQueue.removeBy('byChannel', pubkey)
+      await (this.seedStorage ? this.seedStorage.removeLocal({ channelPubkey: pubkey }) : this.seedQueue.removeBy('byChannel', pubkey))
       await this.touchStorageActivity({ force: true })
       this.ensureRelayListWatcher()
     })
@@ -2117,7 +2150,7 @@ export class PrivateMessenger {
         delete state.channels[pubkey]
         stalePubkeys.push(pubkey)
         await this.queue?.removeBy('byChannel', pubkey)
-        await this.seedQueue?.removeBy('byChannel', pubkey)
+        await (this.seedStorage ? this.seedStorage.removeLocal({ channelPubkey: pubkey }) : this.seedQueue?.removeBy('byChannel', pubkey))
       }
       this.state = state
       if (stalePubkeys.length) await this.removeChannelStates(stalePubkeys)
@@ -2125,6 +2158,7 @@ export class PrivateMessenger {
   }
 
   async pruneStoredSeeds (channelPubkey) {
+    if (this.seedStorage) { await this.seedStorage.prune({ now: nowSeconds() }); return }
     if (!this.seedQueue) return
     const keyRange = globalThis.IDBKeyRange
     if (!channelPubkey) {
@@ -2177,6 +2211,7 @@ export class PrivateMessenger {
       let unwatchError
       try { await unwatchPromise } catch (err) { unwatchError = err }
       await initSettledPromise
+      await Promise.all([...this.extensions].map(extension => extension.close?.()))
       await this.stampActiveChannelActivity()
       await this.queueOperationTail
       await Promise.allSettled([...this.recoveries.values()])

package/private-messenger/recovery/index.js

@@ -193,7 +193,7 @@ function compactNymCarriersFromSeed (seed, { since, until }) {
   }]
 }
 
-function compactRecordsFromSeed (seed, { receiverPubkey, since, until }) {
+export function compactRecordsFromSeed (seed, { receiverPubkey, since, until }) {
   if (seed?.recordType === NYM_CARRIER_SEED_RECORD_TYPE) {
     return compactNymCarriersFromSeed(seed, { since, until })
   }

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

@@ -186,6 +186,9 @@ function storageDatabaseNames (userPubkey) {
   return [
     `${prefix}:idb-queue`,
     `${prefix}:seeds:idb-queue`,
+    `${prefix}:file-seeds:idb-queue`,
+    `${prefix}:file-authorizations:idb-queue`,
+    `${prefix}:file-chunks:idb`,
     `${prefix}:state:idb`
   ]
 }

package/private-messenger/session/README.md

@@ -0,0 +1,39 @@
+# Private message sessions
+
+`createPrivateMessageSession(options)` coordinates one identity's DM inbox,
+outbox and IRFS attachments without presentation state. It builds on
+PrivateMessenger and the file coordinator, not another recovery protocol.
+
+Provide `owner`, a byte-based NIP-44 v3 `signer` with `withSharedKey`, and either
+`eventStore` or a `messageStorage.save(event, { peerPubkey, hearsay })` adapter.
+Optional `chunkStorage` and `recoveryStorage` (`seeds`, `authorizations`) select
+persistence; absent file storage uses the library cache. `mode` defaults to
+`seeder`, `seedersForPeer(peer)` to `[peer]`, and `allowedKinds` to
+`[5, 9, 1063, 34601]`. The DM context is `dm`; file contexts are `dm:media:<root>`.
+`createMessengerSigner` adapts this byte signer to the transport's Base64 API.
+
+Methods: `setPeers`, `setAvailable(boolean)`, `enqueue`, `retry`, `cancel`,
+`download`, `cancelDownload`, and `close`. Callbacks are `onOutbox`, `onMedia`,
+and `onError`. The caller maps its account permissions/connectivity/lock state
+to availability and owns view subscriptions. There are no DOM or UI imports.
+
+`enqueue({ peer, event, context, requiredFiles, deletion })` preserves prepared
+identities. Local message commits and remote stages have independent checkpoints.
+It sends original/thumbnail chunks before announcements, yields for small messages,
+and never interprets relay rejection text as signer permission denial. Inbox ACK
+follows durable storage; failed storage nacks and pauses ingestion. Hearsay cannot
+execute an authoritative deletion. Completion of file recovery means verified,
+persisted indices, not a relay ACK.
+
+`openOutbox` and `openDownloads` inject work storage. Their default is exported as
+`createPrivateSessionStorage({ owner, signer, indexedDB, namespace, prefix })`:
+IDB queue with unique IDs, encrypted payloads, reject-on-capacity and atomic
+existing-only checkpoints. Default prefix is `libp2r2p:private-messenger:session`;
+namespace is `outbox` or `downloads`. These contain pending user work, not a cache;
+no automatic age eviction or synchronization is performed. `close()` releases
+connections without deleting pending work. Apps can preserve existing storage by
+passing their established factories, as Zillion does.
+
+External recovery factories are owned by their caller and must be closed after
+the session. Work storage opened by the session is closed by the session.
+This is a DM profile; group membership/key derivation is not implemented.

package/private-messenger/session/helpers/publication.js

@@ -0,0 +1,40 @@
+import { getEventHash } from '../../../event/index.js'
+
+// A report describes one outer event, not one relay. Each outer event needs
+// at least one relay acknowledgement. Keep the successful fast path immediate.
+export async function assertMessagePublished (result, event) {
+  const reports = result?.delivery?.reports
+  const present = Array.isArray(reports) && reports.length > 0
+  if (present && reports.every(report => report?.success === true)) return
+
+  const failures = present
+    ? await Promise.all(reports.map(async (report, index) => {
+      if (report?.success === true) return null
+      let settled
+      try { settled = await report?.promise } catch (reason) { settled = { errors: [{ reason }] } }
+      // Never retain the broadcast result: it includes plaintext and may carry
+      // delivery.deletionSeckey. Native relay errors retain transport causes.
+      return {
+        index,
+        total: settled?.total ?? report?.total,
+        fulfilled: settled?.fulfilled,
+        errors: (settled?.errors || []).map(({ relay, reason }) => ({ relay, reason }))
+      }
+    })).then(values => values.filter(Boolean))
+    : []
+  const reason = present ? 'RELAY_PUBLICATION_FAILED' : 'NO_DELIVERY_REPORTS'
+  const details = failures.map(report => {
+    const errors = report.errors.map(({ relay, reason }) => {
+      const category = reason?.category ? ` [${reason.category}]` : ''
+      return `${relay || 'unknown relay'}${category}: ${reason?.message || String(reason)}`
+    })
+    return `report ${report.index + 1} (${report.total ?? '?'} relays): ${errors.join('; ') || (report.total === 0 ? 'NO_RELAYS' : 'NO_RELAY_ACKNOWLEDGEMENT')}`
+  })
+  throw Object.assign(new Error(`MESSAGE_NOT_PUBLISHED: ${details.join(' | ') || reason}`), {
+    code: 'MESSAGE_NOT_PUBLISHED',
+    reason,
+    eventId: getEventHash(event),
+    eventKind: event.kind,
+    reports: failures
+  })
+}

package/private-messenger/session/helpers/signer.js

@@ -0,0 +1,13 @@
+import { base64ToBytes, bytesToBase64 } from '../../../base64/index.js'
+
+// The library transport uses its Base64 signer contract. Conversion stays at
+// this adapter; the injected launcher/vault channel always carries raw bytes.
+export function messengerSigner (signer) {
+  return {
+    getPublicKey: () => signer.getPublicKey(),
+    getRelays: () => signer.getRelays(),
+    signEvent: event => signer.signEvent(event),
+    nip44v3Encrypt: (peer, kind, scope, text) => signer.nip44v3.encrypt(peer, kind, scope, base64ToBytes(text).buffer),
+    nip44v3Decrypt: async (peer, kind, scope, ciphertext) => bytesToBase64(new Uint8Array(await signer.nip44v3.decrypt(peer, kind, scope, ciphertext)))
+  }
+}

package/private-messenger/session/helpers/work-storage.js

@@ -0,0 +1,32 @@
+import { createQueue } from '../../../idb-queue/index.js'
+
+// Only ciphertext and opaque event IDs are persisted here. Chunks are committed
+// to the configured file store before an entry is accepted.
+export async function createChatOutbox ({ owner, signer, indexedDB = globalThis.indexedDB, namespace = 'outbox', prefix = 'libp2r2p:private-messenger:session' }) {
+  const queue = await createQueue({
+    prefix: `${prefix}:${namespace}:${owner}`,
+    indexes: { byId: { keyPath: 'id', unique: true } },
+    evictionPolicy: 'reject',
+    indexedDB
+  })
+  return {
+    async put (entry, { existing = false } = {}) {
+      const bytes = new TextEncoder().encode(JSON.stringify(entry)).buffer
+      const ciphertext = await signer.nip44v3.encrypt(owner, 9, `${prefix}:${namespace}`, bytes)
+      return queue.putBy('byId', { id: entry.id, ciphertext }, { existingOnly: existing })
+    },
+    async list () {
+      const entries = []
+      for await (const row of queue.storedItemsBy('byId')) {
+        const bytes = await signer.nip44v3.decrypt(owner, 9, `${prefix}:${namespace}`, row.ciphertext)
+        const entry = JSON.parse(new TextDecoder().decode(bytes))
+        if (entry.id !== row.id) throw new Error('INVALID_OUTBOX_ENTRY')
+        entries.push(entry)
+      }
+      return entries
+    },
+    has: id => queue.someBy('byId', id),
+    remove: id => queue.removeBy('byId', id),
+    close: () => queue.close()
+  }
+}

package/private-messenger/session/index.js

@@ -0,0 +1,307 @@
+import { createEventStoreChunkStorage, createEventStoreMessageStorage } from '../event-store/index.js'
+import { createPrivateFileTransfer } from '../file/index.js'
+import { createPrivateMessenger } from '../index.js'
+import { getEventHash, isValidEvent, isSerializableEvent } from '../../event/index.js'
+import { decodeIrfsChunk, IRFS_CHUNK_BYTES } from '../../irfs/index.js'
+import { decodeFileMetadata } from '../../nip94/index.js'
+import { createChatOutbox } from './helpers/work-storage.js'
+import { messengerSigner } from './helpers/signer.js'
+import { assertMessagePublished } from './helpers/publication.js'
+
+export function wireEvent (value, owner) {
+  const event = { kind: value.kind, created_at: value.created_at, tags: structuredClone(value.tags), content: value.content, pubkey: value.pubkey || owner }
+  if (value.sig) return { ...event, id: value.id, sig: value.sig }
+  return event
+}
+// Relay rejection text must not be interpreted as a local signer denial.
+const retryable = error => error?.code === 'MESSAGE_NOT_PUBLISHED' || !/DENIED|PERMISSION|REVOKED|READ_ONLY|INVALID|BLOCKED|EXPIRED|NOT_IN_PERSONA/i.test(`${error?.code || ''} ${error?.message || ''}`)
+
+export function createPrivateMessageSession ({ owner, signer, eventStore, messageStorage, chunkStorage, recoveryStorage, mode = 'seeder', seedersForPeer = peer => [peer], allowedKinds = [5, 9, 1063, 34601], onMedia = () => {}, onOutbox = () => {}, onError = () => {}, Messenger = createPrivateMessenger, openOutbox = createChatOutbox, FileTransfer = createPrivateFileTransfer, openDownloads = options => createChatOutbox({ ...options, namespace: 'downloads' }) }) {
+  const userSigner = messengerSigner(signer)
+  messageStorage ||= createEventStoreMessageStorage({ eventStore })
+  chunkStorage ||= eventStore ? createEventStoreChunkStorage({ eventStore }) : undefined
+  const peers = new Set()
+  const channels = new Map()
+  const deniedPeers = new Set()
+  const entries = new Map()
+  const cancelled = new Set()
+  let messenger
+  let fileTransfers
+  let downloads
+  const downloadIntents = new Map()
+  const downloadEpochs = new Map()
+  let downloadWriteTail = Promise.resolve()
+  const writeDownloadIntent = operation => {
+    const work = downloadWriteTail.catch(() => {}).then(operation)
+    downloadWriteTail = work
+    return work
+  }
+  let storage
+  let initialized
+  let closed = false
+  let available = false
+  let lifecycle = 0
+  let configuring = Promise.resolve()
+  let sending
+  let draining
+  const idleWaiters = new Set()
+  const settled = () => { if (!sending && !draining) { for (const resolve of idleWaiters) resolve(); idleWaiters.clear() } }
+  const emit = () => onOutbox([...entries.values()].filter(entry => !entry.deletion))
+  const ready = () => (initialized ??= (async () => {
+    storage = await openOutbox({ owner, signer })
+    for (const entry of await storage.list()) entries.set(entry.id, entry)
+    emit()
+  })().catch(async error => { await storage?.close(); storage = null; initialized = null; throw error }))
+  async function configure () {
+    if (closed || !available) return
+    await ready()
+    const version = lifecycle
+    const values = []
+    for (const peer of peers) {
+      if (deniedPeers.has(peer)) continue
+      let channel = channels.get(peer)
+      if (!channel) {
+        try {
+          const scoped = messengerSigner(signer.withSharedKey(peer, 'dm'))
+          channel = { signer: scoped, pubkey: await scoped.getPublicKey(), mode, seeders: seedersForPeer(peer) }
+          channels.set(peer, channel)
+        } catch (error) { if (!retryable(error)) deniedPeers.add(peer); onError(error); continue }
+      }
+      if (closed || !available || version !== lifecycle) return
+      values.push(channel)
+    }
+    if (!messenger) messenger = await Messenger({ seedStorage: recoveryStorage?.seeds, userSigner, channels: [], useContentKeys: false, onMessageQueued: () => drain(), onError })
+    if (closed || !available || version !== lifecycle) { await messenger.pause('signer'); return }
+    await messenger.update({ channels: values })
+    await messenger.resume('signer')
+    if (!fileTransfers) {
+      fileTransfers = FileTransfer({
+        messenger, onError,
+        resolveChannel: ({ peerPubkey, info }) => messengerSigner(signer.withSharedKey(peerPubkey, info)),
+        storage: chunkStorage,
+        seedStorage: recoveryStorage?.seeds,
+        authorizationStorage: recoveryStorage?.authorizations
+      })
+      fileTransfers.observe(state => {
+        const peer = [...channels].find(([, value]) => value.pubkey === state.controlChannelPubkey)?.[0]
+        if (peer) {
+          onMedia({ ...state, peer })
+          if (state.status === 'complete') {
+            const id = intentId({ peer, root: state.root })
+            if (downloadIntents.delete(id)) writeDownloadIntent(() => downloads?.remove(id)).catch(onError)
+          }
+        }
+      })
+      downloads = await openDownloads({ owner, signer })
+      for (const entry of await downloads.list()) downloadIntents.set(entry.id, entry)
+    }
+    for (const entry of downloadIntents.values()) if (peers.has(entry.file.peer)) download(entry.file, { manual: true }).catch(onError)
+    drain(); pump()
+  }
+  function schedule () {
+    const work = configuring.catch(() => {}).then(configure)
+    configuring = work
+    work.catch(onError)
+    return work
+  }
+  async function drain () {
+    if (draining || closed || !available || !messenger) return
+    draining = true
+    const deferred = []
+    try {
+      while (true) {
+        if (closed || !available) break
+        const delivery = await messenger.nextMessage()
+        if (!delivery) break
+        const { message, ack, nack } = delivery
+        try {
+          const peer = [...channels].find(([, value]) => value.pubkey === message.channelPubkey)?.[0]
+          if (!peer) { deferred.push(nack); continue }
+          if (message.senderPubkey !== peer) { await ack(); continue }
+          if (!peers.has(peer)) { deferred.push(nack); continue }
+          const event = wireEvent(message.event, peer)
+          const valid = event.pubkey === peer || message.provenance === 'hearsay' || message.provenance === 'signed'
+          if (!valid || !isSerializableEvent(event) || !allowedKinds.includes(event.kind) || (event.sig && !isValidEvent(event)) || getEventHash(event) !== message.event.id) { await ack(); continue }
+          if (event.kind === 34601) {
+            try { decodeIrfsChunk(event) } catch (error) { onError(error); await ack(); continue }
+          }
+          if (event.kind === 5 && (message.provenance === 'hearsay' || event.pubkey !== peer)) { await ack(); continue }
+          if (!available || closed) { await nack(); break }
+          const saved = await messageStorage.save(event, { peerPubkey: peer, hearsay: message.provenance === 'hearsay' })
+          if (!saved?.result?.ok && !['blocked', 'expired'].includes(saved?.result?.code)) throw Object.assign(new Error('INBOX_STORAGE_FAILED'), { code: saved?.result?.code?.toUpperCase() })
+          await ack()
+        } catch (error) {
+          await nack()
+          onError(error)
+          // Retain the failed record and suspend network ingestion until recovery.
+          await messenger.pause('storage')
+          break
+        }
+      }
+    } finally { await Promise.all(deferred.map(nack => nack())); draining = false; settled() }
+  }
+  async function publish (peer, event) {
+    if (deniedPeers.has(peer)) throw new Error('PERMISSION_DENIED')
+    if (!available || !peers.has(peer) || !channels.has(peer)) throw new Error('CHAT_UNAVAILABLE')
+    const options = { channelPubkey: channels.get(peer)?.pubkey, receiverPubkeys: [peer] }
+    const report = event.sig ? await messenger.broadcastEvent({ ...options, event }) : await messenger.broadcastRumor({ ...options, rumor: event })
+    // Published is relay acceptance, never a peer receipt.
+    await assertMessagePublished(report, event)
+  }
+  async function sendEntry (entry) {
+    entry.status = 'pending'; emit()
+    try {
+      const active = async () => {
+        if (storage.has && !await storage.has(entry.id)) cancelled.add(entry.id)
+        if (closed || !available || cancelled.has(entry.id) || (entry.peer !== owner && !peers.has(entry.peer))) throw new Error('CHAT_UNAVAILABLE')
+      }
+      // Personal copies must commit even if publishing attachment bytes
+      // fails offline. Remote progress remains independently retryable.
+      for (let index = 0; index < entry.events.length; index++) {
+        await active()
+        const event = entry.events[index]
+        if (!entry.localSaved[index]) {
+          const hearsay = !event.sig && event.pubkey !== owner
+          const result = await messageStorage.save(event, { peerPubkey: entry.peer, hearsay })
+          if (result?.result?.code === 'blocked') { cancelled.add(entry.id); await active() }
+          if (!result?.result?.ok) throw Object.assign(new Error('MESSAGE_STORAGE_FAILED'), { code: result?.result?.code?.toUpperCase() })
+          entry.localSaved[index] = true
+          await storage.put(entry, { existing: true })
+        }
+      }
+      // Read/publish one chunk at a time. Progress is durable after each
+      // accepted chunk; replay after interruption keeps its original identity.
+      for (; entry.peer !== owner && entry.fileIndex < entry.files.length; entry.fileIndex++, entry.chunkIndex = 0) {
+        const file = entry.files[entry.fileIndex]
+        await active()
+        await fileTransfers.authorizeSeeding({ controlChannelPubkey: channels.get(entry.peer).pubkey, peerPubkey: entry.peer, root: file.root, size: file.size }, { receiverPubkeys: [entry.peer], sharedAt: entry.event.created_at })
+        for (; entry.chunkIndex < Math.ceil(file.size / IRFS_CHUNK_BYTES); entry.chunkIndex++) {
+          await active()
+          const chunk = chunkStorage ? await chunkStorage.read(file.root, entry.chunkIndex, file) : await fileTransfers.readChunk(file.root, entry.chunkIndex)
+          if (!chunk || decodeIrfsChunk(chunk).root !== file.root) { if (file.optional) break; throw new Error('FILE_UNAVAILABLE') }
+          if (!fileTransfers) throw new Error('FILE_TRANSFER_UNAVAILABLE')
+          await fileTransfers.publishChunk({ controlChannelPubkey: channels.get(entry.peer).pubkey, peerPubkey: entry.peer, root: file.root, size: file.size }, wireEvent(chunk, owner))
+          const completed = entry.files.slice(0, entry.fileIndex).reduce((sum, value) => sum + value.size, 0) + Math.min(file.size, (entry.chunkIndex + 1) * IRFS_CHUNK_BYTES)
+          entry.uploadProgress = { completed, total: entry.files.reduce((sum, value) => sum + value.size, 0) }
+          emit()
+          await active()
+          await storage.put({ ...entry, chunkIndex: entry.chunkIndex + 1 }, { existing: true })
+          // Newly queued text and deletion controls can pass an in-flight file.
+          let admitted = 0
+          for (const pending of entries.values()) {
+            if (closed || !available || admitted >= 8) break
+            if (pending.files.length || pending.failed || cancelled.has(pending.id) || (pending.peer !== owner && !peers.has(pending.peer))) continue
+            admitted++
+            await sendEntry(pending)
+          }
+        }
+      }
+      for (; entry.index < entry.events.length; entry.index++) {
+        await active()
+        const event = entry.events[entry.index]
+        if (entry.peer !== owner) await publish(entry.peer, event)
+        await active()
+        await storage.put({ ...entry, index: entry.index + 1 }, { existing: true })
+      }
+      await storage.remove(entry.id)
+      entries.delete(entry.id)
+      emit()
+    } catch (error) {
+      if (cancelled.has(entry.id)) { await storage.remove(entry.id); entries.delete(entry.id) } else { entry.status = 'error'; entry.failed = true; entry.retryable = retryable(error); await storage.put(entry, { existing: true }).catch(onError); onError(error) }
+      emit()
+    }
+  }
+  async function pump () {
+    if (sending || !available || closed || !messenger || !storage) return
+    sending = true
+    try {
+      for (const entry of entries.values()) {
+        if (closed || !available) break
+        if ((entry.peer !== owner && !peers.has(entry.peer)) || entry.failed || cancelled.has(entry.id)) continue
+        await sendEntry(entry)
+      }
+    } finally { sending = false; settled() }
+  }
+  const intentId = file => getEventHash({ kind: 0, pubkey: owner, created_at: 0, tags: [], content: `${file.peer}:${file.root}` })
+  async function download (file, options = {}) {
+    if (file.peer === owner) return file
+    if (!available || closed || !peers.has(file.peer) || !fileTransfers) throw new Error('CHAT_UNAVAILABLE')
+    const id = intentId(file)
+    if (options.manual) {
+      const epoch = downloadEpochs.get(id) || 0
+      const cancelled = () => { if ((downloadEpochs.get(id) || 0) !== epoch) throw new DOMException('Download cancelled', 'AbortError') }
+      await writeDownloadIntent(async () => {
+        cancelled()
+        await downloads.put({ id, file })
+        cancelled()
+        downloadIntents.set(id, { id, file })
+      })
+    }
+    if (!available || closed || !peers.has(file.peer)) throw new Error('CHAT_UNAVAILABLE')
+    const result = await fileTransfers.download({ controlChannelPubkey: channels.get(file.peer).pubkey, peerPubkey: file.peer, root: file.root, size: file.size, sharedAt: file.sharedAt }, options)
+    if (downloadIntents.delete(id)) await writeDownloadIntent(() => downloads.remove(id))
+    return result
+  }
+  async function cancelDownload (file) {
+    fileTransfers?.cancel(channels.get(file.peer)?.pubkey, file.root)
+    const id = intentId(file)
+    downloadEpochs.set(id, (downloadEpochs.get(id) || 0) + 1)
+    downloadIntents.delete(id)
+    await writeDownloadIntent(() => downloads?.remove(id))
+  }
+  return {
+    download, cancelDownload,
+    async setPeers (values) {
+      peers.clear(); for (const peer of values) if (peer !== owner) peers.add(peer)
+      for (const peer of deniedPeers) if (!peers.has(peer)) deniedPeers.delete(peer)
+      lifecycle++
+      return schedule()
+    },
+    async setAvailable (value) {
+      available = value === true
+      lifecycle++
+      if (!available) { await messenger?.pause('signer'); return }
+      await ready()
+      for (const entry of entries.values()) if (entry.retryable) entry.failed = false
+      await messenger?.resume('storage')
+      return schedule()
+    },
+    async enqueue ({ peer, event, context = [], requiredFiles = [], deletion = false }) {
+      if (closed || !available || (peer !== owner && !peers.has(peer))) throw new Error('CHAT_UNAVAILABLE')
+      await ready()
+      const main = wireEvent(event, owner)
+      const id = getEventHash(main)
+      const events = [...context.map(value => wireEvent(value, owner)), main]
+      const files = events.filter(value => value.kind === 1063).map(value => ({ ...decodeFileMetadata(value), optional: !requiredFiles.includes(getEventHash(value)) })).filter(file => file.service === 'irfs').flatMap(file => [file, ...(file.thumbnail?.root ? [{ ...file.thumbnail, optional: file.optional }] : [])])
+      const entry = { id, peer, event: { ...main, id }, events, files, index: 0, fileIndex: 0, chunkIndex: 0, localSaved: context.map(() => true).concat(false), status: 'pending', deletion }
+      await storage.put(entry)
+      entries.set(id, entry); emit(); pump()
+      return id
+    },
+    async retry (id) {
+      await ready()
+      const entry = entries.get(id)
+      if (entry) { entry.failed = false; if (deniedPeers.delete(entry.peer)) await schedule(); return pump() }
+    },
+    async cancel (id) {
+      cancelled.add(id)
+      await ready()
+      entries.delete(id)
+      await storage.remove(id)
+      emit()
+    },
+    async close () {
+      closed = true; available = false; lifecycle++
+      await Promise.allSettled([configuring, initialized])
+      await messenger?.pause('closed')
+      if (sending || draining) await new Promise(resolve => idleWaiters.add(resolve))
+      await messenger?.close()
+      await storage?.close()
+      await downloadWriteTail.catch(onError)
+      await downloads?.close()
+    }
+  }
+}
+
+export { createChatOutbox as createPrivateSessionStorage } from './helpers/work-storage.js'
+export { messengerSigner as createMessengerSigner } from './helpers/signer.js'