libp2r2p 0.11.9 → 0.11.11

package/README.md

@@ -532,15 +532,26 @@ are attached. These diagnostics reach the messenger's `onError` unchanged.
 A single incomplete relay keeps the interval pending even if another relay
 returned events; received messages may already have been queued. This is a
 history completeness failure, not evidence that an outgoing message failed.
-Existing rewatch/resume and relay-list refresh paths retry pending intervals;
-there is no dedicated periodic retry timer for a failed history fetch.
+Rewatch/resume, relay-list refresh and reload-gap paths schedule bounded retries
+for pending intervals (1s doubling to 30s). Recovery tracks per-relay coverage in
+memory: a tier where some relay returned events and EOSE retries the remaining
+relays a few times (3), an empty-EOSE tier gets more attempts (6), and an
+all-failed tier gets the most (10) before coverage from EOSE relays is accepted
+and the uncovered subranges plus the pre-oldest left edge are requested from
+seeders. Offline attempts never consume the budget, mark coverage or contact
+seeders; they wait for connectivity. The per-relay tracker is process-local, so a
+restart falls back to the persisted whole interval.
 `private-channel.fetchHistory(options)` (0.11.6) is the complete-interval API
 used by messenger recovery. It accepts the signers, processor/fragment options,
 callbacks and abort signal of `fetch`, plus inclusive `since`/`until` bounds
 (defaults: 0 and the start time of the call). It returns only
 `{ oldestCreatedAt, receivedEventCount, relays }`; an empty scan has a null oldest
-time. No complete-history event array is retained. `fetch` keeps its existing
-single-query array contract and optional limit.
+time. Passing `partial: true` (used by messenger recovery) returns per-relay
+`covered`/`pending`/`events` plus `pendingByRelay`, `anyEose`, `anyEoseWithEvents`
+and `allFailed` instead of throwing on partial failure, and `resume` restricts
+each relay to the given pending subranges. No complete-history event array is
+retained. `fetch` keeps its existing single-query array contract and optional
+limit.
 
 History queries each relay independently with limit 16. A response with 16 events
 or status `satisfied` is saturated, even if it already reports EOSE or contains

package/content-key/services/iykc-proof.js

@@ -2,11 +2,13 @@ import { CONTENT_KEY_KIND, parseContentKeyEvent } from '../event/index.js'
 import { pickRelaysForPubkeys, getRelaysByPubkey, relayPool } from '../../relay/index.js'
 
 const QUERY_CACHE_MS = 40 * 60 * 1000
+const NEGATIVE_CACHE_MS = 5 * 60 * 1000
 const IYKC_CACHE_MAX_ITEMS = 10000
 const HEX_PUBKEY = /^[0-9a-f]{64}$/i
 const contentKeysByPubkey = Object.create(null)
 const iykcCacheTimersByPubkey = Object.create(null)
 const iykcCacheAddedAtByPubkey = Object.create(null)
+const inFlightByPubkey = new Map()
 
 const getEvents = (...args) => relayPool.getEvents(...args)
 
@@ -68,42 +70,30 @@ export function clearContentKeyCache () {
   for (const key of Object.keys(contentKeysByPubkey)) delete contentKeysByPubkey[key]
   for (const key of Object.keys(iykcCacheTimersByPubkey)) delete iykcCacheTimersByPubkey[key]
   for (const key of Object.keys(iykcCacheAddedAtByPubkey)) delete iykcCacheAddedAtByPubkey[key]
+  inFlightByPubkey.clear()
 }
 
-export async function getIykcProofs (pubkeys, {
-  _getEvents = getEvents,
-  _getRelaysByPubkey = getRelaysByPubkey,
-  cacheMs = QUERY_CACHE_MS
-} = {}) {
-  const pubkeyList = uniquePubkeys(pubkeys, { requireHex: _getEvents === getEvents })
-  if (!pubkeyList.length) return {}
-
-  const out = {}
-  const missingPubkeys = []
-  for (const pubkey of pubkeyList) {
-    if (!hasCachedKey(contentKeysByPubkey, pubkey)) {
-      missingPubkeys.push(pubkey)
-      continue
-    }
-    const cached = cloneContentKey(contentKeysByPubkey[pubkey])
-    if (cached) out[pubkey] = cached
-  }
-  if (!missingPubkeys.length) return out
-
-  const relaysByPubkey = await _getRelaysByPubkey(missingPubkeys, { _getEvents, cacheMs })
-  const relayToAuthors = pickRelaysForPubkeys(missingPubkeys, relaysByPubkey)
+async function queryContentKeyProofs (pubkeyList, { _getEvents, _getRelaysByPubkey, cacheMs, negativeCacheMs }) {
+  const relaysByPubkey = await _getRelaysByPubkey(pubkeyList, { _getEvents, cacheMs })
+  const relayToAuthors = pickRelaysForPubkeys(pubkeyList, relaysByPubkey)
   const eventGroups = await Promise.all(
     [...relayToAuthors.entries()]
       .map(async ([relay, authors]) => {
-        const { result } = await _getEvents({
-          kinds: [CONTENT_KEY_KIND],
-          authors,
-          limit: authors.length
-        }, [relay], {
-          timeout: 5000,
-          timeoutAfterFirstEose: null
-        })
-        return result.map(({ event }) => event)
+        try {
+          const { result } = await _getEvents({
+            kinds: [CONTENT_KEY_KIND],
+            authors,
+            limit: authors.length
+          }, [relay], {
+            timeout: 5000,
+            timeoutAfterFirstEose: null
+          })
+          return result.map(({ event }) => event)
+        } catch {
+          // Discovery is best-effort: a failing relay group must not fail an
+          // otherwise publishable message.
+          return []
+        }
       })
   )
 
@@ -116,14 +106,67 @@ export async function getIykcProofs (pubkeys, {
     }
   }
 
-  for (const pubkey of missingPubkeys) {
+  const out = {}
+  for (const pubkey of pubkeyList) {
     const entry = latestByPubkey[pubkey]
     const proof = entry
       ? { iykcPubkey: entry.iykcPubkey, iykcProof: entry.iykcProof }
       : null
-    setCachedValue(contentKeysByPubkey, iykcCacheTimersByPubkey, iykcCacheAddedAtByPubkey, pubkey, cloneContentKey(proof), cacheMs)
-    if (proof) out[pubkey] = proof
+    if (proof) {
+      setCachedValue(contentKeysByPubkey, iykcCacheTimersByPubkey, iykcCacheAddedAtByPubkey, pubkey, cloneContentKey(proof), cacheMs)
+      out[pubkey] = proof
+    } else if (negativeCacheMs > 0) {
+      // Misses expire quickly so a peer that publishes a key right after a
+      // prefetch is picked up without waiting for the positive cache window.
+      setCachedValue(contentKeysByPubkey, iykcCacheTimersByPubkey, iykcCacheAddedAtByPubkey, pubkey, null, negativeCacheMs)
+    }
   }
   pruneCache(contentKeysByPubkey, iykcCacheTimersByPubkey, iykcCacheAddedAtByPubkey, IYKC_CACHE_MAX_ITEMS)
   return out
 }
+
+export async function getIykcProofs (pubkeys, {
+  _getEvents = getEvents,
+  _getRelaysByPubkey = getRelaysByPubkey,
+  cacheMs = QUERY_CACHE_MS,
+  negativeCacheMs = NEGATIVE_CACHE_MS
+} = {}) {
+  const pubkeyList = uniquePubkeys(pubkeys, { requireHex: _getEvents === getEvents })
+  if (!pubkeyList.length) return {}
+
+  const out = {}
+  const waiting = []
+  const toQuery = []
+  for (const pubkey of pubkeyList) {
+    if (hasCachedKey(contentKeysByPubkey, pubkey)) {
+      const cached = cloneContentKey(contentKeysByPubkey[pubkey])
+      if (cached) out[pubkey] = cached
+      continue
+    }
+    const pending = inFlightByPubkey.get(pubkey)
+    if (pending) waiting.push([pubkey, pending])
+    else toQuery.push(pubkey)
+  }
+
+  if (toQuery.length) {
+    const query = queryContentKeyProofs(toQuery, { _getEvents, _getRelaysByPubkey, cacheMs, negativeCacheMs })
+    for (const pubkey of toQuery) inFlightByPubkey.set(pubkey, query)
+    try {
+      Object.assign(out, await query)
+    } finally {
+      for (const pubkey of toQuery) {
+        if (inFlightByPubkey.get(pubkey) === query) inFlightByPubkey.delete(pubkey)
+      }
+    }
+  }
+
+  for (const [pubkey, pending] of waiting) {
+    const found = await pending.catch(() => null)
+    if (found?.[pubkey]) out[pubkey] = found[pubkey]
+    else {
+      const cached = cloneContentKey(contentKeysByPubkey[pubkey])
+      if (cached) out[pubkey] = cached
+    }
+  }
+  return out
+}

package/helpers/ranges.js

@@ -0,0 +1,31 @@
+// Inclusive integer ranges [start, end]. Merge treats adjacent ranges as one.
+export function mergeRanges (ranges = []) {
+  const sorted = (ranges || [])
+    .filter(range => range && Number.isFinite(range.start) && Number.isFinite(range.end) && range.end >= range.start)
+    .map(range => ({ start: range.start, end: range.end }))
+    .sort((a, b) => a.start - b.start || a.end - b.end)
+  const out = []
+  for (const range of sorted) {
+    const last = out[out.length - 1]
+    if (!last || range.start > last.end + 1) out.push(range)
+    else last.end = Math.max(last.end, range.end)
+  }
+  return out
+}
+
+// Parts of `range` not covered by `covered`.
+export function subtractRanges (range, covered = []) {
+  if (!range || range.end < range.start) return []
+  const merged = mergeRanges(covered)
+  const out = []
+  let cursor = range.start
+  for (const entry of merged) {
+    if (entry.end < cursor) continue
+    if (entry.start > range.end) break
+    if (entry.start > cursor) out.push({ start: cursor, end: Math.min(entry.start - 1, range.end) })
+    cursor = Math.max(cursor, entry.end + 1)
+    if (cursor > range.end) break
+  }
+  if (cursor <= range.end) out.push({ start: cursor, end: range.end })
+  return out
+}

package/package.json

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

package/private-channel/helpers/history.js

@@ -1,6 +1,7 @@
 import { ValidationError } from '../../error/index.js'
 import { normalizeRelayUrl } from '../../url/index.js'
 import { createAbortableSemaphore } from '../../helpers/abortable-semaphore.js'
+import { mergeRanges } from '../../helpers/ranges.js'
 import { incompleteFetchError } from './fetch-error.js'
 
 const PAGE_SIZE = 16
@@ -23,7 +24,7 @@ function acquireRelay (relay, signal) {
 
 // Queries bounded temporal leaves, oldest first. A saturated one-second leaf
 // cannot be split using standard NIP-01; expand it only up to the safe ceiling.
-export async function readHistory ({ filter, relays, receiverPubkey, signal, getEvents, processEvent, acquirePage }) {
+export async function readHistory ({ filter, relays, receiverPubkey, signal, getEvents, processEvent, acquirePage, partial = false, resume = null }) {
   const since = filter.since ?? 0
   const until = filter.until ?? Math.floor(Date.now() / 1000)
   if (![since, until].every(value => Number.isSafeInteger(value) && value >= 0) || since > until) throw new ValidationError('INVALID_PRIVATE_CHANNEL_HISTORY_RANGE')
@@ -44,7 +45,10 @@ export async function readHistory ({ filter, relays, receiverPubkey, signal, get
     }
   }
   for (const relay of urls) {
-    const intervals = [{ since, until, limit: PAGE_SIZE }]
+    const relayStartCount = receivedEventCount
+    const intervals = resumeIntervalsFor({ resume, relay, since, until })
+      .map(interval => ({ since: interval.start, until: interval.end, limit: PAGE_SIZE }))
+    const covered = []
     let outcome = { relay, status: 'eose' }
     while (intervals.length) {
       signal?.throwIfAborted()
@@ -77,6 +81,7 @@ export async function readHistory ({ filter, relays, receiverPubkey, signal, get
           signal?.throwIfAborted()
           errors.push({ relay, reason: error })
           outcome = { relay, status: 'error', error }
+          intervals.push(interval)
           break
         } finally { elapsedMs += performance.now() - started }
         signal?.throwIfAborted()
@@ -85,6 +90,7 @@ export async function readHistory ({ filter, relays, receiverPubkey, signal, get
           await process(page.result)
           errors.push(...(page.errors ?? []))
           outcome = status ?? { relay, status: 'error' }
+          intervals.push(interval)
           break
         }
         if (status.status === 'satisfied' || page.result.length >= interval.limit) {
@@ -98,10 +104,12 @@ export async function readHistory ({ filter, relays, receiverPubkey, signal, get
             const error = pageLimitError()
             errors.push({ relay, reason: error })
             outcome = { relay, status: 'error', error }
+            intervals.push(interval)
             break
           }
         } else {
           await process(page.result)
+          covered.push({ start: interval.since, end: interval.until })
         }
         signal?.throwIfAborted()
       } finally {
@@ -109,9 +117,34 @@ export async function readHistory ({ filter, relays, receiverPubkey, signal, get
         releaseRelay?.()
       }
     }
-    report.push(outcome)
+    report.push({
+      ...outcome,
+      ...(partial
+        ? {
+            covered: mergeRanges(covered),
+            pending: mergeRanges(intervals.map(interval => ({ start: interval.since, end: interval.until }))),
+            events: receivedEventCount - relayStartCount
+          }
+        : {})
+    })
   }
   signal?.throwIfAborted()
+  if (partial) {
+    const pendingByRelay = {}
+    for (const entry of report) {
+      if (entry.pending?.length) pendingByRelay[entry.relay] = entry.pending
+    }
+    return {
+      oldestCreatedAt,
+      receivedEventCount,
+      elapsedMs: Math.round(elapsedMs),
+      relays: report,
+      pendingByRelay,
+      anyEose: report.some(entry => entry.status === 'eose'),
+      anyEoseWithEvents: report.some(entry => entry.status === 'eose' && (entry.events ?? 0) > 0),
+      allFailed: report.every(entry => entry.status !== 'eose')
+    }
+  }
   if (errors.length || report.some(item => item.status !== 'eose')) {
     const error = incompleteFetchError({ errors, report, receivedEventCount, elapsedMs: Math.round(elapsedMs), request: { relays: urls, channelPubkeys: filter.authors ?? [], receiverPubkey, since, until, limit: PAGE_SIZE, timeoutMs: TIMEOUT_MS } })
     error.operation = 'private-channel.fetchHistory'
@@ -119,3 +152,14 @@ export async function readHistory ({ filter, relays, receiverPubkey, signal, get
   }
   return { oldestCreatedAt, receivedEventCount, relays: report }
 }
+
+function resumeIntervalsFor ({ resume, relay, since, until }) {
+  const pending = resume && Object.prototype.hasOwnProperty.call(resume, relay) ? resume[relay] : null
+  const intervals = Array.isArray(pending) ? pending : [{ start: since, end: until }]
+  return mergeRanges(intervals
+    .map(interval => ({
+      start: Math.max(since, Math.floor(Number(interval?.start))),
+      end: Math.min(until, Math.floor(Number(interval?.end)))
+    }))
+    .filter(interval => Number.isSafeInteger(interval.start) && Number.isSafeInteger(interval.end) && interval.end >= interval.start))
+}

package/private-channel/helpers/lookup-warning.js

@@ -0,0 +1,29 @@
+export const LOOKUP_WARNING_INTERVAL_MS = 30_000
+
+// Best-effort discovery can fail on every message while a relay or the
+// network is unavailable. Keep the first failure visible, then debounce
+// repeats and report how many were suppressed on the next log.
+export function createLookupWarningLogger ({
+  intervalMs = LOOKUP_WARNING_INTERVAL_MS,
+  label = 'private-messenger content-key lookup failed',
+  warn = (...args) => console.warn(...args),
+  now = Date.now
+} = {}) {
+  let warnedAt = null
+  let suppressed = 0
+  return (error, context = '') => {
+    const current = now()
+    if (warnedAt !== null && current - warnedAt < intervalMs) {
+      suppressed++
+      return false
+    }
+    const count = suppressed
+    warnedAt = current
+    suppressed = 0
+    warn(
+      `${label}${context ? ` (${context})` : ''}${count ? ` [${count} repeated failures suppressed]` : ''}`,
+      error?.message ?? error
+    )
+    return true
+  }
+}

package/private-channel/index.js

@@ -9,6 +9,7 @@ import { normalizeRumor, deliveryInfo } from './helpers/rumor.js'
 import { incompleteFetchError } from './helpers/fetch-error.js'
 import { readHistory } from './helpers/history.js'
 import { subscriptionError } from './helpers/subscription-error.js'
+import { createLookupWarningLogger } from './helpers/lookup-warning.js'
 import * as nip44v3 from '../nip44-v3/index.js'
 import { relayPool } from '../relay/index.js'
 import { JSONL_CHUNK_BYTES, NYM_CARRIER_CHUNK_CHARS } from './helpers/chunk-size.js'
@@ -35,6 +36,7 @@ const HEX_SECKEY = /^[0-9a-f]{64}$/i
 const HEX_PUBKEY = /^[0-9a-f]{64}$/i
 const encoder = new TextEncoder()
 const decoder = new TextDecoder()
+const warnLookupFailure = createLookupWarningLogger()
 const NIP44_V3_SCOPE = ''
 
 const sendToRelays = (event, relays) => relayPool.sendEvent(event, relays)
@@ -110,7 +112,19 @@ async function prepareRoutedMessage ({ senderSigner, imkcSigner, privateChannelS
   const useDoubleDh = typeof senderSigner.nip44EncryptDoubleDH === 'function'
   const channelPubkey = await privateChannelSigner.getPublicKey()
   const channelReaderPubkey = privateChannelReaderPubkey || channelPubkey
-  const receiverContentKeys = useDoubleDh ? await _getIykcProofs(receiverPubkeysWithoutContentKeys(receivers)) : {}
+  let receiverContentKeys = {}
+  if (useDoubleDh) {
+    const receiversWithoutContentKeys = receiverPubkeysWithoutContentKeys(receivers)
+    try {
+      receiverContentKeys = await _getIykcProofs(receiversWithoutContentKeys) || {}
+    } catch (error) {
+      // Content-key discovery is best-effort; without a proof the row still
+      // works in sender-content mode instead of failing the send. Keep
+      // failures visible without logging on every message during an outage.
+      warnLookupFailure(error, `recipients: ${receiversWithoutContentKeys.length}`)
+      receiverContentKeys = {}
+    }
+  }
   const preparedRows = await prepareEnvelopeRows({
     senderSigner,
     imkcSigner: useDoubleDh ? imkcSigner : null,
@@ -390,13 +404,18 @@ async function unwrapRecipientEnvelope ({ payloadCiphertext, envelope, receiverS
     if (envelope.iykcPubkey) {
       assertValidEnvelopeIykcProof(envelope)
     }
+    // In self-encryption the advertised sender content key is also our own.
+    // Rows written without a content-key lookup (useContentKeys: false) carry
+    // no iykc pubkey, so hand imkc to the signer as the receiver's own key.
+    const ownContentPubkey = envelope.iykcPubkey ||
+      (senderPubkey && receiverPubkey && senderPubkey === receiverPubkey ? imkcPubkey : '')
     messageSeckey = base64ToText(await receiverSigner.nip44DecryptDoubleDH(
       senderPubkey,
       ROUTER_KIND,
       rowScope,
       envelope.ciphertext,
       imkcPubkey,
-      envelope.iykcPubkey || ''
+      ownContentPubkey
     ))
   } else {
     if (!receiverSigner?.nip44v3Decrypt) throw new ValidationError('RECEIVER_SIGNER_NIP44V3_DECRYPT_UNSUPPORTED')
@@ -953,12 +972,12 @@ export async function fetch ({ signal, receiverSigner, iykcSigner, privateChanne
 
 // Complete interval recovery with bounded pages and one fragment processor.
 // Existing fetch() retains its one-query/event-array contract.
-export async function fetchHistory ({ receiverSigner, privateChannelSigner = receiverSigner, _getEvents = getEvents, _acquirePage, ...options }) {
+export async function fetchHistory ({ receiverSigner, privateChannelSigner = receiverSigner, _getEvents = getEvents, _acquirePage, partial = false, resume = null, ...options }) {
   const authors = privateChannelPubkeyList(options)
   const filter = { kinds: [PRIVATE_BROADCAST_KIND], ...(authors.length ? { authors } : {}), since: options.since, until: options.until }
   const processOuterEvent = createProcessor({ ...options, receiverSigner, privateChannelSigner, onError: error => { options.onError?.(error); throw error } })
   try {
-    return await readHistory({ filter, relays: options.relays, receiverPubkey: options.receiverPubkey, signal: options.signal, getEvents: _getEvents, processEvent: processOuterEvent, acquirePage: _acquirePage })
+    return await readHistory({ filter, relays: options.relays, receiverPubkey: options.receiverPubkey, signal: options.signal, getEvents: _getEvents, processEvent: processOuterEvent, acquirePage: _acquirePage, partial, resume })
   } finally { processOuterEvent.close() }
 }
 

package/private-messenger/file/index.js

@@ -243,6 +243,16 @@ export function createPrivateFileTransfer ({ messenger, resolveChannel, storage,
     const requestedSeeders = new Set()
     const validSeeders = new Set([file.peerPubkey, ...messenger.recoverySeeders(file.controlChannelPubkey)])
     let terminalError
+    let lastError = null
+    const reportError = error => {
+      lastError = {
+        name: error?.name || 'Error',
+        message: error?.message ?? String(error),
+        code: error?.code || '',
+        at: Date.now()
+      }
+      onError(error)
+    }
     const fail = error => { terminalError ||= error }
     async function accept (event, index, { save = true } = {}) {
       signal.throwIfAborted()
@@ -297,7 +307,7 @@ export function createPrivateFileTransfer ({ messenger, resolveChannel, storage,
       })
       // Malformed remote records do not poison the ingestion chain. Operational
       // persistence failures stop the job so completion cannot outrun storage.
-      ingest = task.catch(error => { if (error instanceof ValidationError) onError(error); else if (!signal.aborted) fail(error) })
+      ingest = task.catch(error => { if (error instanceof ValidationError) reportError(error); else if (!signal.aborted) fail(error) })
       return ingest
     }
     try {
@@ -312,7 +322,7 @@ export function createPrivateFileTransfer ({ messenger, resolveChannel, storage,
       if (total !== undefined && persisted.size === total) return
       const parent = messenger.requireWritableChannel(file.controlChannelPubkey)
       const relays = await messenger.resolveWatchRelays(parent)
-      const options = { receiverSigner: messenger.userSigner, privateChannelSigner: file.signer, privateChannelPubkey: file.fileChannelPubkey, receiverPubkey: messenger.userPubkey, relays, receivedChunkIndexedDB: messenger._indexedDB, receivedChunkScope: `${messenger.userPubkey}:file:${file.fileChannelPubkey}`, onEvent: consume, onSeedEvent: seed => saveSeed(file, seed), mode: messenger.channels.get(file.controlChannelPubkey)?.mode === 'watchtower' ? 'watchtower' : 'leecher', onError }
+      const options = { receiverSigner: messenger.userSigner, privateChannelSigner: file.signer, privateChannelPubkey: file.fileChannelPubkey, receiverPubkey: messenger.userPubkey, relays, receivedChunkIndexedDB: messenger._indexedDB, receivedChunkScope: `${messenger.userPubkey}:file:${file.fileChannelPubkey}`, onEvent: consume, onSeedEvent: seed => saveSeed(file, seed), mode: messenger.channels.get(file.controlChannelPubkey)?.mode === 'watchtower' ? 'watchtower' : 'leecher', onError: reportError }
       sub = _transport.subscribe({ ...options, liveOnly: true })
       const stop = () => { sub?.close() }
       signal.addEventListener('abort', stop, { once: true })
@@ -323,7 +333,7 @@ export function createPrivateFileTransfer ({ messenger, resolveChannel, storage,
         const history = _transport.fetch({ ...options, signal: AbortSignal.any([signal, historyController.signal]), since: 0 }).catch(error => {
           // Completion aborts the remaining history read in finally. Only its
           // own cancellation is expected; genuine history failures stay visible.
-          if (!signal.aborted && !(historyController.signal.aborted && error === historyController.signal.reason)) onError(error)
+          if (!signal.aborted && !(historyController.signal.aborted && error === historyController.signal.reason)) reportError(error)
         })
         work.add(history); history.finally(() => work.delete(history))
         const seeders = [...validSeeders].sort((a, b) => (successes.get(b) || 0) - (successes.get(a) || 0) || Math.random() - 0.5)
@@ -340,9 +350,33 @@ export function createPrivateFileTransfer ({ messenger, resolveChannel, storage,
             requestedSeeders.add(peer)
             requestRoundAt = Date.now() + _hedgeMs
             // The request is on dm; its compact reply is on the file channel.
-            await messenger.ask({ channelPubkey: file.controlChannelPubkey, receiverPubkey: peer, code: FILE_CHUNKS_REQUEST_CODE, payload: { fileChannelPubkey: file.fileChannelPubkey, missingRanges: rangesFor(missing) } }).catch(onError)
+            await messenger.ask({ channelPubkey: file.controlChannelPubkey, receiverPubkey: peer, code: FILE_CHUNKS_REQUEST_CODE, payload: { fileChannelPubkey: file.fileChannelPubkey, missingRanges: rangesFor(missing) } }).catch(reportError)
+          }
+          if (!remaining.length && Date.now() - Math.max(lastProgress, requestRoundAt - _hedgeMs) >= _idleMs) {
+            const details = {
+              operation: 'file-download-stall',
+              ownerPubkey: messenger.userPubkey,
+              root: file.root,
+              peerPubkey: file.peerPubkey,
+              total,
+              persisted: persisted.size,
+              missingRanges: rangesFor(missing),
+              missingCount: total === undefined ? null : total - persisted.size,
+              seeders: [...validSeeders],
+              requestedSeeders: [...requestedSeeders],
+              lastProgressAt: new Date(lastProgress).toISOString(),
+              lastProgressAgoMs: Date.now() - lastProgress,
+              elapsedMs: Date.now() - Math.max(lastProgress, requestRoundAt - _hedgeMs),
+              lastError
+            }
+            const error = new Error('FILE_DOWNLOAD_STALLED')
+            error.code = 'FILE_DOWNLOAD_STALLED'
+            error.operation = details.operation
+            error.elapsedMs = details.elapsedMs
+            error.details = details
+            console.warn('private-messenger file download stalled', details)
+            throw error
           }
-          if (!remaining.length && Date.now() - Math.max(lastProgress, requestRoundAt - _hedgeMs) >= _idleMs) throw new Error('FILE_DOWNLOAD_STALLED')
           // Start a fresh batch when all positions of the previous batch arrived.
           if (job.batch?.every(index => persisted.has(index))) { requestedSeeders.clear(); requestRoundAt = Date.now(); job.batch = null }
           job.batch ||= missing

package/private-messenger/helpers/recovery-retry.js

@@ -24,3 +24,19 @@ export function recoveryRetryDelay (errors, delay) {
   errors.forEach(visit)
   return retry && !blocked ? Math.max(delay, retryAt - Date.now()) : null
 }
+
+// Permanent per-relay failures must stop that relay's retries instead of
+// consuming the range retry budget.
+export function isPermanentRecoveryError (error) {
+  const seen = new Set()
+  const visit = value => {
+    if (!value || seen.has(value)) return false
+    seen.add(value)
+    if (value.code === 'PRIVATE_CHANNEL_HISTORY_PAGE_LIMIT' || value.name === 'ValidationError' ||
+        /^(auth-required:|restricted:|blocked:|invalid:|pow:)/.test(value.message || '')) return true
+    for (const child of value.errors || []) if (visit(child)) return true
+    for (const entry of value.relays || []) if (visit(entry.error)) return true
+    return visit(value.cause)
+  }
+  return visit(error)
+}

package/private-messenger/index.js

@@ -1,4 +1,3 @@
-import { recoveryRetryDelay } from './helpers/recovery-retry.js'
 // Expected use:
 // const messenger = await createPrivateMessenger({
 //   userSigner,
@@ -44,9 +43,12 @@ import { recoveryRetryDelay } from './helpers/recovery-retry.js'
 // - For other event-list replies, use createEventReplyPacker({ messenger, question, code }).update(event).
 
 import { createAbortableSemaphore } from '../helpers/abortable-semaphore.js'
+import { mergeRanges, subtractRanges } from '../helpers/ranges.js'
 import * as privateMessage from '../private-message/index.js'
 import { isOnline } from '../network/index.js'
 import { createSendRelayRouting, normalizeFallbackRelays } from './helpers/send-routing.js'
+import { incompleteFetchError } from '../private-channel/helpers/fetch-error.js'
+import { recoveryRetryDelay, isPermanentRecoveryError } from './helpers/recovery-retry.js'
 import { normalizeRelayUrl } from '../url/index.js'
 import { deliveryInfo } from '../private-channel/helpers/rumor.js'
 import { bytesToBase64 } from '../base64/index.js'
@@ -122,6 +124,13 @@ const SEED_QUEUE_INDEXES = {
 const encoder = new TextEncoder()
 const noContentKeys = async () => ({})
 
+export const RECOVERY_RELAY_RETRY_LIMITS = Object.freeze({
+  partial: 3,
+  emptyEose: 6,
+  allFailed: 10
+})
+const RECOVERY_ONLINE_CACHE_MS = 5000
+
 function textToBase64 (text) {
   return bytesToBase64(encoder.encode(text))
 }
@@ -289,6 +298,8 @@ export class PrivateMessenger {
     this.recoveries = new Map()
     this.recoveryAdmission = createAbortableSemaphore(2)
     this.recoveryControllers = new Set()
+    this.recoveryRanges = new Map()
+    this.recoveryOnline = { at: 0, value: true }
     this.resumeWork = null
     this.capacityTimer = null
     this.capacityCheck = null
@@ -664,6 +675,7 @@ export class PrivateMessenger {
 
     if (removedPubkeys.length) {
       await this.stampChannelActivity(removedPubkeys)
+      for (const pubkey of removedPubkeys) this.dropRecoveryRanges(pubkey)
     }
 
     const storageSnapshot = await activatePrivateMessengerStorage({
@@ -1174,7 +1186,211 @@ export class PrivateMessenger {
     this.liveRecoveryTimers.delete(pubkey)
   }
 
+  async checkRecoveryOnline () {
+    const now = Date.now()
+    if (now - this.recoveryOnline.at < RECOVERY_ONLINE_CACHE_MS) return this.recoveryOnline.value
+    let value = true
+    try {
+      if (globalThis.navigator?.onLine === false) value = false
+      else if (this._isOnline !== isOnline || typeof globalThis.document !== 'undefined') {
+        value = (await this._isOnline()) !== false
+      }
+    } catch { value = false }
+    this.recoveryOnline = { at: Date.now(), value }
+    return value
+  }
+
+  recoveryRangeKey (channelPubkey, range) {
+    return `${channelPubkey}:${range.start}:${range.end}`
+  }
+
+  recoveryRangeRecord (channelPubkey, range) {
+    const key = this.recoveryRangeKey(channelPubkey, range)
+    let record = this.recoveryRanges.get(key)
+    if (!record) {
+      record = {
+        key,
+        channelPubkey,
+        start: range.start,
+        end: range.end,
+        covered: [],
+        oldestCreatedAt: null,
+        relays: new Map(),
+        tier: '',
+        everEose: false,
+        everEoseWithEvents: false,
+        attempts: 0,
+        lastErrors: []
+      }
+      this.recoveryRanges.set(key, record)
+    }
+    return record
+  }
+
+  reconcileRecoveryRelays (record, relays) {
+    const current = new Set(relays)
+    for (const relay of [...record.relays.keys()]) {
+      if (!current.has(relay)) record.relays.delete(relay)
+    }
+    for (const relay of current) {
+      if (record.relays.has(relay)) continue
+      record.relays.set(relay, {
+        pending: [{ start: record.start, end: record.end }],
+        covered: [],
+        attempts: 0,
+        dead: false,
+        eose: false,
+        events: 0,
+        error: null
+      })
+    }
+  }
+
+  recoveryRelayPlan (record) {
+    const plan = {}
+    let hasWork = false
+    for (const [relay, state] of record.relays) {
+      if (state.dead || state.eose || !state.pending?.length) continue
+      plan[relay] = state.pending
+      hasWork = true
+    }
+    return hasWork ? plan : null
+  }
+
+  hasActiveRecoveryRelays (channelPubkey) {
+    for (const record of this.recoveryRanges.values()) {
+      if (record.channelPubkey !== channelPubkey) continue
+      if (this.recoveryRecordActive(record)) return true
+    }
+    return false
+  }
+
+  recoveryRecordActive (record) {
+    for (const state of record.relays.values()) {
+      if (!state.dead && !state.eose && state.pending?.length) return true
+    }
+    return false
+  }
+
+  hasPendingRecovery (channelPubkey) {
+    return (this.readState().channels[channelPubkey]?.offlineRanges || []).length > 0
+  }
+
+  dropRecoveryRanges (channelPubkey) {
+    for (const [key, record] of this.recoveryRanges) {
+      if (record.channelPubkey === channelPubkey) this.recoveryRanges.delete(key)
+    }
+  }
+
+  pruneRecoveryRanges (channelPubkey, ranges) {
+    const keep = new Set((ranges || []).map(range => this.recoveryRangeKey(channelPubkey, range)))
+    for (const [key, record] of this.recoveryRanges) {
+      if (record.channelPubkey === channelPubkey && !keep.has(key)) this.recoveryRanges.delete(key)
+    }
+  }
+
+  updateRecoveryRecord (record, history) {
+    record.covered = mergeRanges([
+      ...record.covered,
+      ...(history.relays || []).flatMap(entry => entry.covered || [])
+    ])
+    if (history.oldestCreatedAt != null) {
+      record.oldestCreatedAt = record.oldestCreatedAt == null
+        ? history.oldestCreatedAt
+        : Math.min(record.oldestCreatedAt, history.oldestCreatedAt)
+    }
+    const byRelay = new Map((history.relays || []).map(entry => [entry.relay, entry]))
+    for (const [relay, state] of record.relays) {
+      const entry = byRelay.get(relay)
+      if (!entry) continue
+      const relayErrors = [...(entry.errors || [])]
+      if (entry.error) relayErrors.push(entry.error)
+      state.error = relayErrors[0] || null
+      const done = entry.status === 'eose' && !(entry.pending?.length)
+      state.covered = mergeRanges([...(state.covered || []), ...(entry.covered || [])])
+      state.eose = done
+      state.pending = done ? [] : subtractRanges({ start: record.start, end: record.end }, state.covered)
+      state.events += entry.events || 0
+      if (done) {
+        state.attempts = 0
+        record.everEose = true
+        if (state.events > 0) record.everEoseWithEvents = true
+      }
+    }
+    record.tier = record.everEoseWithEvents ? 'partial' : record.everEose ? 'emptyEose' : 'allFailed'
+    record.lastErrors = (history.relays || []).flatMap(entry => [...(entry.errors || []), ...(entry.error ? [entry.error] : [])])
+  }
+
+  applyRecoveryRetryBudget (record) {
+    const limit = RECOVERY_RELAY_RETRY_LIMITS[record.tier] ?? RECOVERY_RELAY_RETRY_LIMITS.allFailed
+    for (const state of record.relays.values()) {
+      if (state.eose || state.dead || !state.pending?.length) continue
+      state.attempts++
+      if (state.attempts >= limit || isPermanentRecoveryError(state.error)) state.dead = true
+    }
+    record.attempts++
+  }
+
+  recoveryIncompleteError (record, history, range) {
+    const errors = []
+    for (const entry of history.relays || []) {
+      for (const reason of entry.errors || []) errors.push({ relay: entry.relay, reason })
+      if (entry.error) errors.push({ relay: entry.relay, reason: entry.error })
+    }
+    const error = incompleteFetchError({
+      errors,
+      report: (history.relays || []).map(entry => ({
+        relay: entry.relay,
+        status: entry.status,
+        ...(entry.error ? { error: entry.error } : {})
+      })),
+      receivedEventCount: history.receivedEventCount || 0,
+      elapsedMs: history.elapsedMs || 0,
+      request: {
+        relays: [...record.relays.keys()],
+        channelPubkeys: [record.channelPubkey],
+        receiverPubkey: this.userPubkey,
+        since: range.start,
+        until: range.end,
+        limit: 16,
+        timeoutMs: 5000
+      }
+    })
+    error.operation = 'private-channel.fetchHistory'
+    return error
+  }
+
+  isPartialRecoveryHistory (history) {
+    return Boolean(history) && !Array.isArray(history) &&
+      Array.isArray(history.relays) &&
+      history.pendingByRelay !== undefined &&
+      typeof history.anyEose === 'boolean'
+  }
+
+  async finalizeRecoveryRange ({ channelPubkey, range, record }) {
+    if (!await this.checkRecoveryOnline()) return { complete: false, failures: [], offline: true }
+    const uncovered = subtractRanges({ start: range.start, end: range.end }, record.covered)
+    const oldest = record.oldestCreatedAt
+    const leftEdge = oldest == null
+      ? [{ start: range.start, end: range.end }]
+      : oldest > range.start
+        ? [{ start: range.start, end: Math.min(oldest, range.end) }]
+        : []
+    const seedRanges = mergeRanges([...uncovered, ...leftEdge])
+    const failures = []
+    for (const seedRange of seedRanges) {
+      const attempt = await this.#askSeedersForMissingRangeAttempt(channelPubkey, seedRange.start, seedRange.end)
+      failures.push(...attempt.failures.map(failure => failure.error))
+    }
+    record.lastErrors = failures
+    return { complete: failures.length === 0, failures }
+  }
+
   scheduleLiveRecovery (pubkey) {
+    return this.scheduleOfflineRecovery(pubkey)
+  }
+
+  scheduleOfflineRecovery (pubkey, { startDelayMs = 0 } = {}) {
     const current = this.liveRecoveryTimers.get(pubkey)
     if (current) { current.again = true; return }
     const work = { delay: 1000, timer: null, again: false }
@@ -1199,7 +1415,11 @@ export class PrivateMessenger {
         }
         if (!isCurrent()) return
         const pending = this.readState().channels[pubkey]?.offlineRanges?.length
-        const retry = pending ? recoveryRetryDelay(errors, Math.min(30000, work.delay * (0.8 + Math.random() * 0.4))) : null
+        let retry = null
+        if (pending) {
+          retry = recoveryRetryDelay(errors, Math.min(30000, work.delay * (0.8 + Math.random() * 0.4)))
+          if (retry === null && this.hasActiveRecoveryRelays(pubkey)) retry = Math.min(30000, work.delay)
+        }
         if (work.again || retry !== null) {
           schedule(work.again ? 0 : retry)
           work.delay = Math.min(30000, work.delay * 2)
@@ -1207,7 +1427,7 @@ export class PrivateMessenger {
       }, delay)
       work.timer?.unref?.()
     }
-    schedule(0)
+    schedule(startDelayMs)
   }
 
   recordInterruption (channels, at = nowSeconds()) {
@@ -1242,6 +1462,7 @@ export class PrivateMessenger {
     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)
+    for (const pubkey of pubkeys) this.dropRecoveryRanges(pubkey)
     this.recordInterruption(pubkeys)
     for (const controller of this.recoveryControllers) {
       if (pubkeys.includes(controller.channelPubkey)) controller.abort()
@@ -1278,6 +1499,9 @@ export class PrivateMessenger {
       if (this.pauseReasons.size || this.closePromise) return
       await this.reconcilePresencePublishers()
       await this.recoverOfflineRanges(channels)
+      for (const pubkey of channels) {
+        if (this.hasPendingRecovery(pubkey)) this.scheduleOfflineRecovery(pubkey, { startDelayMs: 1000 })
+      }
       for (const extension of this.extensions) await extension.resume?.()
     })()
     this.resumeWork = work
@@ -1348,6 +1572,9 @@ export class PrivateMessenger {
     }
     await this.watch(channelPubkeys, { scheduleReloadGap: false })
     await this.recoverOfflineRanges(channelPubkeys)
+    for (const pubkey of channelPubkeys) {
+      if (this.hasPendingRecovery(pubkey)) this.scheduleOfflineRecovery(pubkey, { startDelayMs: 1000 })
+    }
   }
 
   async handleAsk (channelPubkey, message) {
@@ -1928,6 +2155,9 @@ export class PrivateMessenger {
       }
       this.writeState(state)
       await this.flushStateWrites()
+      for (const channel of channels) {
+        if (!this.offlineRecoverySecondsFor(channel)) this.dropRecoveryRanges(channel.pubkey)
+      }
       for (const channel of channels) await this.pruneStoredSeeds(channel.pubkey)
     })
   }
@@ -1968,6 +2198,9 @@ export class PrivateMessenger {
       if ((this.watchRevisionByChannel.get(pubkey) || 0) !== revision) return
       if (start != null) this.addOfflineRange(pubkey, Math.max(0, start - this.offlineSkewSeconds), nowSeconds())
       try { await this.recoverOfflineRanges([pubkey]) } catch (err) { this.onError?.(err) }
+      if (!this.closePromise && !this.pauseReasons.size && this.desiredChannels.has(pubkey) && this.hasPendingRecovery(pubkey)) {
+        this.scheduleOfflineRecovery(pubkey, { startDelayMs: 1000 })
+      }
     }, this.reloadGapDelayMs)
     this.reloadGapTimers.set(pubkey, { timer, token, revision })
   }
@@ -2156,13 +2389,20 @@ export class PrivateMessenger {
     const failures = []
     const state = this.readState()
     const now = nowSeconds()
+    const online = await this.checkRecoveryOnline()
 
     for (const pubkey of uniq(channels)) {
       const channel = this.channels.get(pubkey)
       const current = state.channels[pubkey]
-      if (!channel || !current?.offlineRanges?.length) continue
+      if (!channel || !current?.offlineRanges?.length) {
+        this.dropRecoveryRanges(pubkey)
+        continue
+      }
       const recoverySeconds = this.offlineRecoverySecondsFor(channel)
-      if (!recoverySeconds) continue
+      if (!recoverySeconds) {
+        this.dropRecoveryRanges(pubkey)
+        continue
+      }
       const minStart = now - recoverySeconds
       const processedRanges = new Set(current.offlineRanges.map(range => `${range.start}:${range.end}`))
 
@@ -2170,6 +2410,7 @@ export class PrivateMessenger {
       let recoveredThrough = current.recoveredThrough || 0
       for (const range of current.offlineRanges) {
         if (range.end < minStart) continue
+        if (!online) { remaining.push(range); continue }
         const watchRevision = this.watchRevisionByChannel.get(pubkey) || 0
         const controller = new AbortController()
         controller.channelPubkey = pubkey
@@ -2178,38 +2419,81 @@ export class PrivateMessenger {
           if (this.pauseReasons.size || this.closePromise || !this.desiredChannels.has(pubkey)) throw new Error('PRIVATE_MESSENGER_PAUSED')
           const fetchRelays = await this.resolveWatchRelays(channel)
           controller.signal.throwIfAborted()
-          const history = await this._privateChannel.fetchHistory({
-            _acquirePage: signal => this.recoveryAdmission.acquire(signal),
-            signal: controller.signal,
-            receivedChunkScope: this.storageLeaseId,
-            receiverSigner: this.userSigner,
-            iykcSigner: this.contentKeySigner,
-            privateChannelSigner: channel.signer,
-            privateChannelReaderSigner: channel.readerSigner,
-            privateChannelReaderPubkey: channel.readerPubkey,
-            privateChannelPubkeys: [pubkey],
-            receiverPubkey: this.userPubkey,
-            relays: fetchRelays,
-            since: Math.max(0, range.start),
-            until: range.end,
-            mode: channel.mode,
-            modeByPubkey: { [pubkey]: channel.mode },
-            receivedChunkTtlMs: this.receivedChunkTtlMsFor(channel),
-            receivedChunkIndexedDB: this._indexedDB,
-            onEvent: (event, outer, meta) => this.receive(pubkey, () => this.enqueueRumor(eventType(event), pubkey, { event, outer, meta, payload: parseEventContent(event) }), { event, outer }),
-            onNymEvent: (event, outer, meta) => this.receive(pubkey, () => this.enqueueRumor('nym', pubkey, { event, outer, meta, payload: parseEventContent(event) }), { event, outer }),
-            onSeedEvent: seed => this.receive(pubkey, () => this.enqueueSeed(pubkey, seed), seed),
-            onContentKeyUsage: usage => this.handleContentKeyUsage(pubkey, usage),
-            onError: err => { throw err }
-          })
-          controller.signal.throwIfAborted()
-          const attempt = await this.#askSeedersForRelayLeftEdgeAttempt(pubkey, range, history.oldestCreatedAt)
+          const record = this.recoveryRangeRecord(pubkey, range)
+          this.reconcileRecoveryRelays(record, fetchRelays)
+          const plan = this.recoveryRelayPlan(record)
+          if (plan) {
+            const history = await this._privateChannel.fetchHistory({
+              _acquirePage: signal => this.recoveryAdmission.acquire(signal),
+              signal: controller.signal,
+              receivedChunkScope: this.storageLeaseId,
+              receiverSigner: this.userSigner,
+              iykcSigner: this.contentKeySigner,
+              privateChannelSigner: channel.signer,
+              privateChannelReaderSigner: channel.readerSigner,
+              privateChannelReaderPubkey: channel.readerPubkey,
+              privateChannelPubkeys: [pubkey],
+              receiverPubkey: this.userPubkey,
+              relays: Object.keys(plan),
+              since: Math.max(0, range.start),
+              until: range.end,
+              partial: true,
+              resume: plan,
+              mode: channel.mode,
+              modeByPubkey: { [pubkey]: channel.mode },
+              receivedChunkTtlMs: this.receivedChunkTtlMsFor(channel),
+              receivedChunkIndexedDB: this._indexedDB,
+              onEvent: (event, outer, meta) => this.receive(pubkey, () => this.enqueueRumor(eventType(event), pubkey, { event, outer, meta, payload: parseEventContent(event) }), { event, outer }),
+              onNymEvent: (event, outer, meta) => this.receive(pubkey, () => this.enqueueRumor('nym', pubkey, { event, outer, meta, payload: parseEventContent(event) }), { event, outer }),
+              onSeedEvent: seed => this.receive(pubkey, () => this.enqueueSeed(pubkey, seed), seed),
+              onContentKeyUsage: usage => this.handleContentKeyUsage(pubkey, usage),
+              onError: err => { throw err }
+            })
+            controller.signal.throwIfAborted()
+            if (this.isPartialRecoveryHistory(history)) {
+              this.updateRecoveryRecord(record, history)
+              this.applyRecoveryRetryBudget(record)
+              if ((history.relays || []).some(entry => entry.status !== 'eose' || entry.pending?.length)) {
+                const error = this.recoveryIncompleteError(record, history, range)
+                this.onError?.(error)
+                failures.push(error)
+              }
+            } else {
+              // Legacy fetch seam (tests/custom channels): resolves only when
+              // the whole range was read, so treat it as fully relay-covered.
+              record.covered = mergeRanges([...record.covered, { start: range.start, end: range.end }])
+              if (history?.oldestCreatedAt != null) {
+                record.oldestCreatedAt = record.oldestCreatedAt == null
+                  ? history.oldestCreatedAt
+                  : Math.min(record.oldestCreatedAt, history.oldestCreatedAt)
+              }
+              for (const state of record.relays.values()) {
+                state.eose = true
+                state.pending = []
+              }
+              record.tier = 'partial'
+              record.lastErrors = []
+            }
+          }
           const lifecycleChanged = controller.signal.aborted || this.closePromise || !this.channels.has(pubkey) || !this.stopByChannel.has(pubkey) ||
             (this.watchRevisionByChannel.get(pubkey) || 0) !== watchRevision
-          failures.push(...attempt.failures.map(failure => failure.error))
-          if (lifecycleChanged || attempt.failures.length) remaining.push(range)
-          else recoveredThrough = Math.max(recoveredThrough, range.end)
+          if (lifecycleChanged) {
+            remaining.push(range)
+            continue
+          }
+          if (this.recoveryRecordActive(record)) {
+            remaining.push(range)
+            continue
+          }
+          const result = await this.finalizeRecoveryRange({ channelPubkey: pubkey, range, record })
+          failures.push(...result.failures)
+          if (result.complete) recoveredThrough = Math.max(recoveredThrough, range.end)
+          else remaining.push(range)
         } catch (err) {
+          const record = this.recoveryRanges.get(this.recoveryRangeKey(pubkey, range))
+          if (record && isPermanentRecoveryError(err)) {
+            for (const state of record.relays.values()) state.dead = true
+          }
           if (!(controller.liveInterrupted && err === controller.signal.reason)) this.onError?.(err)
           failures.push(err)
           remaining.push(range)
@@ -2223,6 +2507,7 @@ export class PrivateMessenger {
         recoveredThrough: Math.max(fresh.channels[pubkey]?.recoveredThrough || 0, recoveredThrough),
         offlineRanges: mergeRanges(concurrentRanges.concat(remaining))
       }
+      this.pruneRecoveryRanges(pubkey, remaining)
       this.writeState(fresh)
       await this.flushStateWrites()
     }
@@ -2232,6 +2517,7 @@ export class PrivateMessenger {
   async clearChannel (pubkey) {
     await this.unwatch(pubkey)
     await this._privateMessage.clearChannelState?.(pubkey)
+    this.dropRecoveryRanges(pubkey)
     return this.runQueueOperation(async () => {
       this.channels.delete(pubkey)
       this.removeChannelState(pubkey)
@@ -2265,6 +2551,7 @@ export class PrivateMessenger {
         await this.queue?.removeBy('byChannel', pubkey)
         await (this.seedStorage ? this.seedStorage.removeLocal({ channelPubkey: pubkey }) : this.seedQueue?.removeBy('byChannel', pubkey))
       }
+      for (const pubkey of stalePubkeys) this.dropRecoveryRanges(pubkey)
       this.state = state
       if (stalePubkeys.length) await this.removeChannelStates(stalePubkeys)
     })
@@ -2355,22 +2642,13 @@ export class PrivateMessenger {
           temporaryStorageArea: this.temporaryStorageArea
         })
       }
+      this.recoveryRanges.clear()
       if (unwatchError) throw unwatchError
     })()
     return this.closePromise
   }
 }
 
-function mergeRanges (ranges) {
-  const out = []
-  for (const range of ranges) {
-    const last = out[out.length - 1]
-    if (!last || range.start > last.end + 1) out.push({ ...range })
-    else last.end = Math.max(last.end, range.end)
-  }
-  return out
-}
-
 function eventType (event) {
   if (event.kind === privateMessage.ASK_KIND) return 'ask'
   if (event.kind === privateMessage.REPLY_KIND) return 'reply'

package/private-messenger/session/README.md

@@ -9,11 +9,18 @@ Provide `owner`, a byte-based NIP-44 v3 `signer` with `withSharedKey`, and eithe
 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>`.
+`[5, 9, 1063, 34601]`. `useContentKeys` defaults to `true`: the coordinator looks
+up recipients' published content-key proofs (kind 18716) while sending and falls
+back to sender-content whenever a proof is missing or the lookup fails. Misses
+are cached for 5 minutes (found proofs for 40), so a later prefetch picks up a
+key published after an earlier miss. Set it to `false` when the signer owns that discovery. 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`,
+Methods: `setPeers`, `setAvailable(boolean)`, `prefetchContentKeys(peers?)`,
+`enqueue`, `retry`, `cancel`, `download`, `cancelDownload`, and `close`.
+`prefetchContentKeys` warms the content-key lookup cache for the owner and the
+given peers (default: current peers); it is best-effort and never rejects.
+Callbacks are `onOutbox`, `onMedia`,
 `onError`, and optional `onSendError(error, { id, peer })`. The caller maps its
 account permissions/connectivity/lock state to availability and owns view subscriptions. There are no DOM or UI imports.
 

package/private-messenger/session/index.js

@@ -3,6 +3,7 @@ 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 { getIykcProofs } from '../../content-key/index.js'
 import { onOnline } from '../../network/index.js'
 import { decodeFileMetadata } from '../../nip94/index.js'
 import { createChatOutbox } from './helpers/work-storage.js'
@@ -18,8 +19,16 @@ export function wireEvent (value, owner) {
 // 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, fallbackRelays = [], mode = 'seeder', seedersForPeer = peer => [peer], allowedKinds = [5, 9, 1063, 34601], onMedia = () => {}, onOutbox = () => {}, onError = () => {}, onSendError = () => {}, Messenger = createPrivateMessenger, openOutbox = createChatOutbox, FileTransfer = createPrivateFileTransfer, _onOnline = onOnline, openDownloads = options => createChatOutbox({ ...options, namespace: 'downloads' }) }) {
+export function createPrivateMessageSession ({ owner, signer, eventStore, messageStorage, chunkStorage, recoveryStorage, fallbackRelays = [], mode = 'seeder', seedersForPeer = peer => [peer], allowedKinds = [5, 9, 1063, 34601], useContentKeys = true, onMedia = () => {}, onOutbox = () => {}, onError = () => {}, onSendError = () => {}, Messenger = createPrivateMessenger, openOutbox = createChatOutbox, FileTransfer = createPrivateFileTransfer, _onOnline = onOnline, _getIykcProofs = getIykcProofs, openDownloads = options => createChatOutbox({ ...options, namespace: 'downloads' }) }) {
   fallbackRelays = normalizeFallbackRelays(fallbackRelays)
+  const reportedErrors = new WeakSet()
+  const reportError = error => {
+    if (error && (typeof error === 'object' || typeof error === 'function')) {
+      if (reportedErrors.has(error)) return
+      reportedErrors.add(error)
+    }
+    onError(error)
+  }
   const userSigner = messengerSigner(signer)
   messageStorage ||= createEventStoreMessageStorage({ eventStore })
   chunkStorage ||= eventStore ? createEventStoreChunkStorage({ eventStore }) : undefined
@@ -36,6 +45,7 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
   let downloads
   const downloadIntents = new Map()
   const downloadEpochs = new Map()
+  const activeDownloads = new Map()
   let downloadWriteTail = Promise.resolve()
   const writeDownloadIntent = operation => {
     const work = downloadWriteTail.catch(() => {}).then(operation)
@@ -71,18 +81,18 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
           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 }
+        } catch (error) { if (!retryable(error)) deniedPeers.add(peer); reportError(error); continue }
       }
       if (closed || !available || version !== lifecycle) return
       values.push(channel)
     }
-    if (!messenger) messenger = await Messenger({ fallbackRelays, seedStorage: recoveryStorage?.seeds, userSigner, channels: [], useContentKeys: false, onMessageQueued: () => drain(), onError })
+    if (!messenger) messenger = await Messenger({ fallbackRelays, seedStorage: recoveryStorage?.seeds, userSigner, channels: [], useContentKeys, onMessageQueued: () => drain(), onError: reportError })
     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,
+        messenger, onError: reportError,
         resolveChannel: ({ peerPubkey, info }) => messengerSigner(signer.withSharedKey(peerPubkey, info)),
         storage: chunkStorage,
         seedStorage: recoveryStorage?.seeds,
@@ -94,20 +104,30 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
           onMedia({ ...state, peer })
           if (state.status === 'complete') {
             const id = intentId({ peer, root: state.root })
-            if (downloadIntents.delete(id)) writeDownloadIntent(() => downloads?.remove(id)).catch(onError)
+            if (downloadIntents.delete(id)) writeDownloadIntent(() => downloads?.remove(id)).catch(reportError)
           }
         }
       })
       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)
+    for (const entry of downloadIntents.values()) {
+      if (!peers.has(entry.file.peer) || activeDownloads.has(entry.id)) continue
+      const work = download(entry.file, { manual: true })
+        .catch(error => {
+          // A failed intent stays queued for the next configure; report each
+          // real attempt once even if configure runs while it is in flight.
+          if (downloadIntents.has(entry.id)) reportError(error)
+        })
+        .finally(() => { if (activeDownloads.get(entry.id) === work) activeDownloads.delete(entry.id) })
+      activeDownloads.set(entry.id, work)
+    }
     drain(); pump()
   }
   function schedule () {
     const work = configuring.catch(() => {}).then(configure)
     configuring = work
-    work.catch(onError)
+    work.catch(reportError)
     return work
   }
   async function drain () {
@@ -129,7 +149,7 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
           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 }
+            try { decodeIrfsChunk(event) } catch (error) { reportError(error); await ack(); continue }
           }
           if (event.kind === 5 && (message.provenance === 'hearsay' || event.pubkey !== peer)) { await ack(); continue }
           if (!available || closed) { await nack(); break }
@@ -138,7 +158,7 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
           await ack()
         } catch (error) {
           await nack()
-          onError(error)
+          reportError(error)
           // Retain the failed record and suspend network ingestion until recovery.
           await messenger.pause('storage')
           break
@@ -217,8 +237,8 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
     } catch (error) {
       if (cancelled.has(entry.id)) { await storage.remove(entry.id); entries.delete(entry.id) } else {
         entry.status = error.retryWhenAvailable ? 'pending' : 'error'; entry.failed = true; entry.retryable = retryable(error)
-        await storage.put(entry, { existing: true }).catch(onError)
-        onError(error)
+        await storage.put(entry, { existing: true }).catch(reportError)
+        reportError(error)
         // The failed wire event may be a quote or file chunk. Report the
         // owning outbox item separately, without mutating the native error.
         if (error.retryWhenOnline) offlineSends.add(entry.id)
@@ -284,6 +304,24 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
   }
   return {
     download, cancelDownload,
+    // Peers-based so callers can prefetch as soon as a chat route opens, before
+    // the shared-key channel exists. When group chats get real membership, add
+    // a thin prefetchChannelContentKeys(channelPubkey) wrapper that resolves
+    // the channel's receivers and delegates here.
+    async prefetchContentKeys (values = [...peers]) {
+      if (closed || !useContentKeys) return {}
+      const requested = [...new Set([owner, ...(Array.isArray(values) ? values : [values])])]
+        .filter(value => typeof value === 'string' && value)
+      if (!requested.length) return {}
+      try {
+        return await _getIykcProofs(requested)
+      } catch (error) {
+        // Prefetch only warms the lookup cache; callers must keep working with
+        // sender-content until a proof is available. Keep the failure visible.
+        console.warn('private-messenger content-key prefetch failed', error?.message ?? error)
+        return {}
+      }
+    },
     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)
@@ -329,14 +367,14 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
     },
     async close () {
       closed = true; available = false; lifecycle++
-      stopOnlineRetry(); offlineSends.clear()
+      stopOnlineRetry(); offlineSends.clear(); activeDownloads.clear()
       for (const controller of sendControllers.values()) controller.abort()
       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 downloadWriteTail.catch(reportError)
       await downloads?.close()
     }
   }