libp2r2p 0.11.0 → 0.11.1

package/private-messenger/file/helpers/catalog.js

@@ -6,7 +6,29 @@ const keyFor = row => `${row.controlChannelPubkey}:${row.fileChannelPubkey}:${ro
 
 // A grant contains no payload, key material or retention reference in the file
 // store. Serialize read/merge/write with other coordinators for this identity.
-export function createFileCatalog ({ messenger, now }) {
+export function createFileCatalog ({ messenger, now, storage }) {
+  if (storage) {
+    const valid = row => {
+      const parent = messenger.channels.get(row.controlChannelPubkey)
+      return parent?.mode === 'seeder' && row.expiresAt > now() && row.sharedAt + messenger.offlineRecoverySecondsFor(parent) > now()
+    }
+    return {
+      ready: Promise.resolve(),
+      async authorize (file, receivers, sharedAt) {
+        const { controlChannelPubkey, fileChannelPubkey, peerPubkey, root, size } = file
+        for (const receiverPubkey of receivers) {
+          const row = { controlChannelPubkey, fileChannelPubkey, peerPubkey, root, size, receiverPubkey, sharedAt, expiresAt: sharedAt + messenger.offlineRecoverySecondsFor(controlChannelPubkey) }
+          if (valid(row)) await storage.put(row)
+        }
+      },
+      async find (controlChannelPubkey, fileChannelPubkey, receiverPubkey) {
+        const row = await storage.find({ controlChannelPubkey, fileChannelPubkey, receiverPubkey })
+        return row && valid(row) ? row : null
+      },
+      prune: () => storage.prune({ now: now() }),
+      async close () {}
+    }
+  }
   const prefix = `${messenger.prefix}:file-authorizations`
   let database
   const db = () => (database ??= createQueue({ prefix, indexedDB: messenger._indexedDB, evictionPolicy: 'reject', indexes: { key: { keyPath: 'key', unique: true }, channel: 'fileChannelPubkey' } }))

package/private-messenger/file/helpers/stream.js

@@ -0,0 +1,31 @@
+import { decodeIrfsChunk } from '../../../irfs/index.js'
+import { ValidationError } from '../../../error/index.js'
+
+export function chunkStream ({ read, root, size, signal, release = async () => {} }) {
+  let index = 0, total, bytes = 0, settled = false, controller
+  const finish = async () => {
+    if (settled) return
+    settled = true; signal?.removeEventListener('abort', abort)
+    await release()
+  }
+  const abort = () => { if (settled) return; controller.error(signal.reason); finish().catch(() => {}) }
+  return new ReadableStream({
+    start (value) { controller = value; signal?.addEventListener('abort', abort, { once: true }); if (signal?.aborted) abort() },
+    async pull () {
+      try {
+        signal?.throwIfAborted()
+        const event = await read(root, index)
+        signal?.throwIfAborted()
+        if (settled) return
+        if (!event) throw new Error('FILE_UNAVAILABLE')
+        const chunk = decodeIrfsChunk(event)
+        if (chunk.root !== root || chunk.index !== index || (total !== undefined && total !== chunk.total)) throw new ValidationError('FILE_CHUNK_DESCRIPTOR_MISMATCH')
+        total = chunk.total; index++; bytes += chunk.contentBytes.length
+        if (index === total && size !== undefined && bytes !== size) throw new ValidationError('FILE_SIZE_MISMATCH')
+        controller.enqueue(chunk.contentBytes)
+        if (index === total) { await finish(); controller.close() }
+      } catch (error) { if (!settled) { await finish(); controller.error(error) } }
+    },
+    cancel: finish
+  }, { highWaterMark: 1 })
+}

package/private-messenger/file/index.js

@@ -1,4 +1,7 @@
 import NMMR from 'nmmr'
+import { chunkStream } from './helpers/stream.js'
+import { createFileCache } from './helpers/cache.js'
+export { createFileCache, DEFAULT_FILE_CACHE_BYTES } from './helpers/cache.js'
 import { createFileCatalog } from './helpers/catalog.js'
 import { ValidationError } from '../../error/index.js'
 import { IRFS_CHUNK_BYTES, decodeIrfsChunk } from '../../irfs/index.js'
@@ -60,10 +63,13 @@ function waitForTransfer (promise, signal) {
   })
 }
 
-// One coordinator per account. Signer derivation and the local IRFS database
-// belong to the caller; recovery, validation and scheduling belong here.
-export function createPrivateFileTransfer ({ messenger, resolveChannel, storage, onError = () => {}, _transport = channelTransport, _messages = messages, _hedgeMs = 2000, _idleMs = 30000, _now = now }) {
-  if (!messenger?.extensions || typeof resolveChannel !== 'function' || !storage?.read || !storage?.save) throw new ValidationError('INVALID_FILE_TRANSFER_OPTIONS')
+// One coordinator per account. The caller resolves signers and may supply
+// storage; recovery, validation and scheduling belong here.
+export function createPrivateFileTransfer ({ messenger, resolveChannel, storage, authorizationStorage, seedStorage, cacheMaxBytes, onError = () => {}, _transport = channelTransport, _messages = messages, _hedgeMs = 2000, _idleMs = 30000, _now = now }) {
+  if (!messenger?.extensions || typeof resolveChannel !== 'function' || (storage && (!storage.read || !storage.save))) throw new ValidationError('INVALID_FILE_TRANSFER_OPTIONS')
+  const ownsStorage = !storage
+  storage ||= createFileCache({ prefix: messenger.prefix, indexedDB: messenger._indexedDB, maxBytes: cacheMaxBytes })
+  const uploadLeases = new Map()
   const registrations = new Map()
   const jobs = new Map()
   const listeners = new Set()
@@ -75,7 +81,7 @@ export function createPrivateFileTransfer ({ messenger, resolveChannel, storage,
   let closed = false
   let queuePromise
   const queue = () => (queuePromise ??= createQueue({ prefix: `${messenger.prefix}:file-seeds`, indexedDB: messenger._indexedDB, maxBytes: 64 * 1024 * 1024, evictionPolicy: 'fifo', indexes: { key: { keyPath: 'key', unique: true }, channel: 'fileChannelPubkey' } }))
-  const catalog = createFileCatalog({ messenger, now: _now })
+  const catalog = createFileCatalog({ messenger, now: _now, storage: authorizationStorage })
   catalog.ready.catch(onError)
   const keyFor = (control, root) => `${control}:${root}`
   const emit = job => { for (const listener of listeners) listener({ root: job.file.root, controlChannelPubkey: job.file.controlChannelPubkey, status: job.status, completed: job.completed, total: job.file.size, error: job.error }) }
@@ -116,6 +122,7 @@ export function createPrivateFileTransfer ({ messenger, resolveChannel, storage,
   }
   async function prune () {
     await catalog.prune()
+    if (seedStorage) { await seedStorage.prune({ now: _now() }); return }
     if (!queuePromise) return
     await (await queue()).removeWhere(row => {
       const parent = messenger.channels.get(row.controlChannelPubkey)
@@ -126,11 +133,13 @@ export function createPrivateFileTransfer ({ messenger, resolveChannel, storage,
     if (messenger.channels.get(file.controlChannelPubkey)?.mode !== 'watchtower' || !seedEnabled(file)) return
     const index = readFileChunkIndex(seed.router)
     if (index === undefined) return
-    const db = await queue()
+    const db = seedStorage ? null : await queue()
     for (const row of compactSeedRouterRows(seed)) {
       if (![file.peerPubkey, messenger.userPubkey].includes(row.receiverPubkey)) continue
       const key = `${file.controlChannelPubkey}:${file.fileChannelPubkey}:${row.receiverPubkey}:${index}`
-      await db.putBy('key', { ...row, key, root: file.root, controlChannelPubkey: file.controlChannelPubkey, fileChannelPubkey: file.fileChannelPubkey, peerPubkey: file.peerPubkey, chunkIndex: index, receivedAt: _now(), expiresAt: _now() + messenger.offlineRecoverySecondsFor(file.controlChannelPubkey) })
+      const record = { ...row, key, root: file.root, controlChannelPubkey: file.controlChannelPubkey, fileChannelPubkey: file.fileChannelPubkey, peerPubkey: file.peerPubkey, chunkIndex: index, receivedAt: _now(), expiresAt: _now() + messenger.offlineRecoverySecondsFor(file.controlChannelPubkey) }
+      if (seedStorage) await seedStorage.put(record)
+      else await db.putBy('key', record)
     }
     await prune()
   }
@@ -151,9 +160,17 @@ export function createPrivateFileTransfer ({ messenger, resolveChannel, storage,
     usable(file)
     const decoded = checked(file, event)
     await catalog.ready
-    const options = { ...sendOptions(file, await routing(file, file.peerPubkey)), receiverPubkeys: [file.peerPubkey], fileChunkIndex: decoded.index, ...(messenger.channels.get(file.controlChannelPubkey)?.mode === 'watchtower' ? { onPreparedSeed: seed => saveSeed(file, seed) } : {}) }
-    const result = event.sig ? await _messages.broadcastEvent({ ...options, event }) : await _messages.broadcastRumor({ ...options, rumor: event })
-    assertPublished(result)
+    if (ownsStorage) {
+      if (!uploadLeases.has(file.root)) uploadLeases.set(file.root, await storage.reserve(file.root, file.size))
+      try { await storage.save(event, file) } catch (error) { await uploadLeases.get(file.root)?.(); uploadLeases.delete(file.root); throw error }
+    }
+    let result
+    try {
+      const options = { ...sendOptions(file, await routing(file, file.peerPubkey)), receiverPubkeys: [file.peerPubkey], fileChunkIndex: decoded.index, ...(messenger.channels.get(file.controlChannelPubkey)?.mode === 'watchtower' ? { onPreparedSeed: seed => saveSeed(file, seed) } : {}) }
+      result = event.sig ? await _messages.broadcastEvent({ ...options, event }) : await _messages.broadcastRumor({ ...options, rumor: event })
+      assertPublished(result)
+    } catch (error) { await uploadLeases.get(file.root)?.(); uploadLeases.delete(file.root); throw error }
+    if (decoded.index === decoded.total - 1) { await uploadLeases.get(file.root)?.(); uploadLeases.delete(file.root) }
     // A scheduler turn between chunks lets queued text/control publications run.
     await new Promise(resolve => setTimeout(resolve, 0))
     return result
@@ -198,9 +215,11 @@ export function createPrivateFileTransfer ({ messenger, resolveChannel, storage,
       return true
     }
     if (messenger.channels.get(controlChannelPubkey)?.mode !== 'watchtower') return true
-    const db = await queue()
+    const db = seedStorage ? null : await queue()
     let packer
-    for await (const seed of db.storedItemsBy('channel', payload.fileChannelPubkey)) {
+    const candidates = seedStorage ? seedStorage.iterate({ controlChannelPubkey, fileChannelPubkey: payload.fileChannelPubkey, receiverPubkey: question.pubkey, indices: [...indices] }) : db.storedItemsBy('channel', payload.fileChannelPubkey)
+    for await (const seed of candidates) {
+      if (seed.expiresAt <= _now() || seed.receivedAt + messenger.offlineRecoverySecondsFor(controlChannelPubkey) <= _now() || (seedStorage && !await seedStorage.has(seed))) continue
       if (seed.controlChannelPubkey !== controlChannelPubkey || seed.receiverPubkey !== question.pubkey || !indices.has(seed.chunkIndex) || !seedEnabled(seed)) continue
       const file = await register(seed)
       usable(file)
@@ -218,7 +237,7 @@ export function createPrivateFileTransfer ({ messenger, resolveChannel, storage,
   async function run (job) {
     const file = job.file
     const signal = job.controller.signal
-    let sub
+    let sub, release
     const historyController = new AbortController()
     let ingest = Promise.resolve()
     let total = file.size === undefined ? undefined : Math.ceil(file.size / IRFS_CHUNK_BYTES)
@@ -286,6 +305,7 @@ export function createPrivateFileTransfer ({ messenger, resolveChannel, storage,
       return ingest
     }
     try {
+      release = await storage.reserve?.(file.root, file.size, { signal })
       job.status = 'downloading'; emit(job)
       // Resume from independently verified local chunks, never from an ACK.
       for (let index = 0; index < (total ?? 1); index++) {
@@ -329,7 +349,7 @@ export function createPrivateFileTransfer ({ messenger, resolveChannel, storage,
           await new Promise(resolve => { const timer = setTimeout(done, Math.min(100, _hedgeMs)); function done () { clearTimeout(timer); signal.removeEventListener('abort', done); resolve() } signal.addEventListener('abort', done, { once: true }) })
         }
       } finally { signal.removeEventListener('abort', stop) }
-    } finally { historyController.abort(); await sub?.close(); await ingest }
+    } finally { historyController.abort(); await sub?.close(); await ingest; await release?.() }
     if (job.completed !== file.size) throw new ValidationError('FILE_SIZE_MISMATCH')
   }
   function pump () {
@@ -366,7 +386,7 @@ export function createPrivateFileTransfer ({ messenger, resolveChannel, storage,
     }
     const key = keyFor(file.controlChannelPubkey, file.root)
     let job = jobs.get(key)
-    if (!job || ['error', 'cancelled', 'paused'].includes(job.status)) {
+    if (!job || ['error', 'cancelled', 'paused', ...(ownsStorage ? ['complete'] : [])].includes(job.status)) {
       const controller = new AbortController()
       const { promise, resolve, reject } = Promise.withResolvers()
       job = { file, controller, resolve, reject, promise, completed: 0, manual, thumbnail, priority: thumbnail ? 2 : manual ? 1 : 0, status: 'queued' }
@@ -404,10 +424,10 @@ export function createPrivateFileTransfer ({ messenger, resolveChannel, storage,
       for (const job of jobs.values()) if (job.pauseRequested && job.status !== 'complete') download(job.file, { manual: job.manual, thumbnail: job.thumbnail }).catch(onError)
     },
     unwatch (channels) { for (const job of jobs.values()) if (channels.includes(job.file.controlChannelPubkey)) cancelJob(job) },
-    async close () { if (closed) return; closed = true; extension.pause(); clearInterval(timer); await Promise.allSettled([...work]); await catalog.close(); if (queuePromise) await (await queuePromise).close(); messenger.extensions.delete(extension); listeners.clear() }
+    async close () { if (closed) return; closed = true; extension.pause(); clearInterval(timer); await Promise.allSettled([...work]); await catalog.close(); for (const release of uploadLeases.values()) await release(); uploadLeases.clear(); if (ownsStorage) await storage.close(); if (queuePromise) await (await queuePromise).close(); messenger.extensions.delete(extension); listeners.clear() }
   }
   const timer = setInterval(() => { prune().catch(onError) }, 60000)
   timer.unref?.()
   messenger.extensions.add(extension)
-  return { register, authorizeSeeding, publishChunk, download, close: extension.close, cancel (control, root) { const job = jobs.get(keyFor(control, root)); if (job) { job.pauseRequested = false; cancelJob(job) } }, observe (listener) { listeners.add(listener); for (const job of jobs.values()) emit(job); return () => listeners.delete(listener) } }
+  return { register, authorizeSeeding, publishChunk, download, readChunk: (root, index) => storage.read(root, index), stream: (descriptor, options = {}) => storage.stream ? storage.stream(descriptor, options) : chunkStream({ read: storage.read.bind(storage), ...descriptor, ...options }), close: extension.close, cancel (control, root) { const job = jobs.get(keyFor(control, root)); if (job) { job.pauseRequested = false; cancelJob(job) } }, observe (listener) { listeners.add(listener); for (const job of jobs.values()) emit(job); return () => listeners.delete(listener) } }
 }

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
@@ -348,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,
@@ -1342,6 +1346,16 @@ export class PrivateMessenger {
   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
@@ -1932,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)
       }
     }
@@ -2108,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()
     })
@@ -2134,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)
@@ -2142,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) {

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

@@ -188,6 +188,7 @@ function storageDatabaseNames (userPubkey) {
     `${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()
+  }
+}