libp2r2p 0.11.4 → 0.11.5

package/README.md

@@ -915,10 +915,16 @@ local defaults, including a bounded streaming file cache. The optional
 provides reusable DM inbox/outbox and attachment lifecycle without UI coupling,
 including an optional `onSendError` callback identifying the failed outbox message.
 
-Single-recipient private messages now retry NIP-65 read relays in pairs when
+Private messages, including multi-recipient channels, retry NIP-65 read relays
+in pairs per recipient when
 selected relays reject publication or become unreachable while connectivity is
-confirmed. The exact encrypted outer events are reused; explicit per-call and
-channel relay overrides remain authoritative. Successful sends keep first-ACK
+confirmed. The exact encrypted outer events are reused. Optional `fallbackRelays` on
+`createPrivateMessenger` and `createPrivateMessageSession` are tried after the
+primary destinations, including explicit per-call `relays`, channel `sendRelays`
+and channel/global `relays`, as well as explicit `relayToReceivers` maps.
+Retries preserve each encrypted recipient subset; success requires accepted
+publication covering every recipient in that subset. Receive routing adds them from the start for live
+messages, history and files while preserving automatic NIP-65 updates. Successful sends keep first-ACK
 latency, and short-lived channel/recipient preferences avoid recently refused
 relays without changing receive subscriptions. See the
 [session coordinator](private-messenger/session/README.md) for deferred offline

package/package.json

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

package/private-channel/index.js

@@ -37,7 +37,7 @@ const encoder = new TextEncoder()
 const decoder = new TextDecoder()
 const NIP44_V3_SCOPE = ''
 
-const sendToRelays = (...args) => relayPool.sendEvent(...args)
+const sendToRelays = (event, relays) => relayPool.sendEvent(event, relays)
 const getEvents = (...args) => relayPool.getEvents(...args)
 const getLiveEventsGenerator = (...args) => relayPool.getLiveEventsGenerator(...args)
 const getEventsFeedGenerator = (...args) => relayPool.getEventsFeedGenerator(...args)
@@ -540,7 +540,7 @@ export async function publish ({ senderSigner, imkcSigner, privateChannelSigner
     try {
       for (const group of groups) {
         for await (const wrappedEvent of wrapPreparedEvents({ privateChannelSigner, receivers: group.receivers, receiverTag, fileChunkIndex, onPreparedSeed, deletionPubkey: normalizedDeletionPubkey, expirationSeconds, context })) {
-          results.push(await _publish(wrappedEvent, withRecoveryRelays(group.relays, recoveryRelays)))
+          results.push(await _publish(wrappedEvent, withRecoveryRelays(group.relays, recoveryRelays), { receiverPubkeys: receiverPubkeys(group.receivers), primaryRelays: group.relays }))
         }
       }
     } finally {
@@ -550,7 +550,7 @@ export async function publish ({ senderSigner, imkcSigner, privateChannelSigner
   }
 
   for await (const wrappedEvent of wrapEvents({ senderSigner, imkcSigner, privateChannelSigner, privateChannelReaderPubkey, receivers, receiverTag, fileChunkIndex, onPreparedSeed, deletionPubkey: normalizedDeletionPubkey, event, expirationSeconds, temporaryStorageArea, _getIykcProofs })) {
-    results.push(await _publish(wrappedEvent, withRecoveryRelays(relays, recoveryRelays)))
+    results.push(await _publish(wrappedEvent, withRecoveryRelays(relays, recoveryRelays), { receiverPubkeys: receiverPubkeys(receivers), primaryRelays: relays }))
   }
   return results
 }

package/private-messenger/helpers/publication.js

@@ -1,7 +1,8 @@
 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.
+// accepted publication covering its routed recipients. Keep the successful fast
+// path immediate; a partially covered multi-recipient report remains a failure.
 export async function assertMessagePublished (result, event) {
   const reports = result?.delivery?.reports
   const present = Array.isArray(reports) && reports.length > 0

package/private-messenger/helpers/send-routing.js

@@ -1,4 +1,5 @@
 import { normalizeRelayUrl } from '../../url/index.js'
+import { ValidationError } from '../../error/index.js'
 
 const REJECTION_PREFIXES = new Set(['blocked', 'restricted', 'auth-required', 'pow', 'rate-limited', 'error'])
 const TRANSPORT_CATEGORIES = new Set(['connection', 'transport', 'timeout'])
@@ -14,17 +15,60 @@ export function isReplaceableRelayFailure (error) {
   return REJECTION_PREFIXES.has(/^([a-z-]+):/.exec(error?.message || '')?.[1])
 }
 
-export function createSendRelayRouting ({ peer, relaysByPubkey, exclusions, pickRelays, recoveryRelays, publish, publishNymEvent, sendEvent, isOnline, isCurrent, signal, now = Date.now }) {
-  // One finite snapshot, including the existing default pair if NIP-65 is
-  // unavailable. Never invent additional fallback relays.
-  const candidates = [...pickRelays([peer], relaysByPubkey, { relayType: 'read', maxPerPubkey: Infinity }).keys()]
+export function normalizeFallbackRelays (value = []) {
+  if (!Array.isArray(value)) throw new ValidationError('INVALID_FALLBACK_RELAYS')
+  return [...new Set(Array.from(value, normalizeRelayUrl))]
+}
+
+function routeEntries (routes) {
+  return routes instanceof Map ? [...routes] : Object.entries(routes || {})
+}
+
+function routeGroups (routes) {
+  const groups = new Map()
+  for (const [relay, receivers] of routes) {
+    const key = [...receivers].sort().join(',')
+    if (!groups.has(key)) groups.set(key, { receivers, relays: [] })
+    groups.get(key).relays.push(relay)
+  }
+  return [...groups.values()]
+}
+
+export function createSendRelayRouting ({ peer, peers = [peer], relaysByPubkey, primaryRelays, primaryRelayToReceivers, fallbackRelays = [], exclusions, pickRelays, recoveryRelays, publish, publishNymEvent, sendEvent, isOnline, isCurrent, signal, now = Date.now }) {
+  // Keep discovery's defaults when NIP-65 is unavailable. Explicit maps/lists
+  // retain their fanout; configured fallbacks are a separate last-resort stage.
+  const explicit = Boolean(primaryRelays || primaryRelayToReceivers)
+  const primaryRoutes = primaryRelayToReceivers || (primaryRelays
+    ? new Map(primaryRelays.map(relay => [relay, peers]))
+    : pickRelays(peers, relaysByPubkey, { relayType: 'read', maxPerPubkey: Infinity }))
+  const primaryByPeer = Object.fromEntries(peers.map(pubkey => [pubkey, { read: [] }]))
+  for (const [relay, receivers] of routeEntries(primaryRoutes)) {
+    for (const pubkey of Array.isArray(receivers) ? receivers : [receivers]) primaryByPeer[pubkey]?.read.push(normalizeRelayUrl(relay))
+  }
+  const candidates = [...new Set([...Object.values(primaryByPeer).flatMap(value => value.read), ...fallbackRelays])]
   const candidateSet = new Set(candidates)
   for (const [relay, expires] of exclusions) if (expires <= now() || !candidateSet.has(relay)) exclusions.delete(relay)
-  // New attempts may recheck an exhausted list. Each in-flight outer event has
-  // its own tried set, preventing loops during concurrent sends.
-  if (candidates.length && candidates.every(relay => exclusions.has(relay))) exclusions.clear()
-  const select = excluded => pickRelays([peer], relaysByPubkey, { relayType: 'read', excludeRelaysByPubkey: new Map([[peer, [...excluded]]]) })
-  const relayToReceivers = select(exclusions.keys())
+  // A fresh attempt can recheck an exhausted list; each outer event still owns
+  // a tried set so concurrent sends/fragments cannot create a retry loop.
+  if (peers.some(pubkey => {
+    const available = [...primaryByPeer[pubkey].read, ...fallbackRelays]
+    return available.length && available.every(relay => exclusions.has(relay))
+  })) exclusions.clear()
+  const select = (receivers, excluded, staged = false) => {
+    const excludedRelays = [...excluded]
+    const excludeRelaysByPubkey = new Map(receivers.map(pubkey => [pubkey, excludedRelays]))
+    const options = { relayType: 'read', excludeRelaysByPubkey, emptyRelaysFallback: [] }
+    const routes = pickRelays(receivers, primaryByPeer, { ...options, ...(explicit ? { maxPerPubkey: Infinity } : {}) })
+    // For one ciphertext, exhaust the remaining members' primary routes before
+    // using a common fallback. Initial wrapping must nevertheless cover everyone.
+    if (staged && routes.size) return routes
+    const covered = new Set([...routes.values()].flat())
+    const missing = receivers.filter(pubkey => !covered.has(pubkey))
+    const fallback = pickRelays(missing, Object.fromEntries(missing.map(pubkey => [pubkey, { read: fallbackRelays }])), options)
+    for (const [relay, pubkeys] of fallback) routes.set(relay, [...new Set([...(routes.get(relay) || []), ...pubkeys])])
+    return routes
+  }
+  const relayToReceivers = primaryRelayToReceivers || select(peers, exclusions.keys())
   const current = () => !signal?.aborted && isCurrent()
   const rejected = report => (report?.errors || []).filter(item => candidateSet.has(normalized(item.relay)) && isReplaceableRelayFailure(item.reason))
   const remember = errors => { for (const item of errors) exclusions.set(normalized(item.relay), now() + EXCLUSION_MS) }
@@ -33,58 +77,68 @@ export function createSendRelayRouting ({ peer, relaysByPubkey, exclusions, pick
     try { return await isOnline({ signal }) && current() } catch { return false }
   }
 
-  async function send (event, initialRelays) {
+  async function send (event, initialRelays, context = {}) {
+    // This context describes the already encrypted recipient subset. It stays
+    // local: no recipient tags or routing metadata are added to the outer event.
+    const receivers = context.receiverPubkeys || peers
+    const pending = new Set(receivers)
     const mirrors = initialRelays.filter(relay => !candidateSet.has(normalized(relay)))
-    let relays = [...new Set([...select(exclusions.keys()).keys(), ...mirrors])]
+    const initialPrimary = context.primaryRelays || (primaryRelays || peers.length === 1 ? routeEntries(relayToReceivers).map(([relay]) => relay) : [])
+    const first = [...new Set(initialPrimary.map(normalizeRelayUrl))].filter(relay => !exclusions.has(relay))
+    let batch = first.length ? { receivers, relays: first } : null
     const tried = new Set()
     const errors = []
     const summaries = []
-    const finish = result => {
-      if (summaries.length === 1) return result
-      return {
-        ...result,
+    const next = () => routeGroups(select([...pending], new Set([...exclusions.keys(), ...tried]), true))[0]
+    const finish = result => ({
+      ...result,
+      success: summaries.length > 0 && pending.size === 0,
+      total: tried.size,
+      promise: Promise.all(summaries).then(reports => ({
         total: tried.size,
-        promise: Promise.all(summaries).then(reports => ({
-          total: tried.size,
-          success: reports.some(report => report.success),
-          fulfilled: reports.reduce((total, report) => total + (report.fulfilled || 0), 0),
-          succeededRelays: [...new Set(reports.flatMap(report => report.succeededRelays || []))],
-          errors: reports.flatMap(report => report.errors || [])
-        }))
-      }
-    }
-    while (true) {
+        success: summaries.length > 0 && pending.size === 0,
+        fulfilled: reports.reduce((total, report) => total + (report.fulfilled || 0), 0),
+        succeededRelays: [...new Set(reports.flatMap(report => report.succeededRelays || []))],
+        errors: reports.flatMap(report => report.errors || [])
+      }))
+    })
+    let result = { success: false }
+    while ((batch ||= next())) {
       signal?.throwIfAborted()
+      const relays = [...new Set([...batch.relays, ...(summaries.length ? [] : mirrors)])]
       for (const relay of relays) tried.add(normalized(relay))
-      // Republish the exact signed outer event, preserving encryption,
-      // fragments, timestamps and deletion capabilities.
-      const result = await sendEvent(event, relays)
+      // Every relay in this batch serves the same pending recipient subset.
+      // One ACK covers that subset, never unrelated members of the ciphertext.
+      result = await sendEvent(event, relays)
       const settled = Promise.resolve(result.promise)
       summaries.push(settled)
       if (result.success) {
+        for (const pubkey of batch.receivers) pending.delete(pubkey)
         // Keep the first ACK immediate; learn about redundant failures later.
         settled.then(async report => {
           const failed = rejected(report)
           if (failed.length && await online()) remember(failed)
         }).catch(() => {})
-        return finish(result)
+        if (!pending.size) return finish(result)
+      } else {
+        const report = await settled
+        const failed = rejected(report)
+        errors.push(...(report?.errors || []))
+        if (!failed.length || errors.some(item => !isReplaceableRelayFailure(item.reason))) return finish(result)
+        if (!next()) { exclusions.clear(); return finish(result) }
+        if (!await online()) return { ...finish(result), retryWhenAvailable: !signal?.aborted, retryWhenOnline: current() }
+        remember(failed)
       }
-      const report = await settled
-      const failed = rejected(report)
-      errors.push(...(report?.errors || []))
-      if (!failed.length || errors.some(item => !isReplaceableRelayFailure(item.reason))) return finish(result)
-      const next = [...select(new Set([...exclusions.keys(), ...tried])).keys()]
-      if (!next.length) { exclusions.clear(); return finish(result) }
-      if (!await online()) return { ...finish(result), retryWhenAvailable: !signal?.aborted, retryWhenOnline: current() }
-      remember(failed)
-      relays = next
+      if (!current()) return { ...finish(result), retryWhenAvailable: !signal?.aborted, retryWhenOnline: false }
+      batch = null
     }
+    return finish(result)
   }
 
   return {
     relayToReceivers,
-    // A recovery mirror must not reintroduce the recipient's refused relays.
-    recoveryRelays: recoveryRelays.filter(relay => !candidateSet.has(relay) || !exclusions.has(relay)),
+    // A recovery mirror must not reintroduce refused relays or promote a fallback.
+    recoveryRelays: recoveryRelays.filter(relay => !candidateSet.has(normalized(relay)) || !exclusions.has(normalized(relay))),
     _publish: options => (options.nymSigner ? publishNymEvent : publish)({ ...options, _publish: send })
   }
 }

package/private-messenger/index.js

@@ -44,7 +44,8 @@
 
 import * as privateMessage from '../private-message/index.js'
 import { isOnline } from '../network/index.js'
-import { createSendRelayRouting } from './helpers/send-routing.js'
+import { createSendRelayRouting, normalizeFallbackRelays } from './helpers/send-routing.js'
+import { normalizeRelayUrl } from '../url/index.js'
 import { deliveryInfo } from '../private-channel/helpers/rumor.js'
 import { bytesToBase64 } from '../base64/index.js'
 import { ValidationError } from '../error/index.js'
@@ -193,6 +194,7 @@ export class PrivateMessenger {
   }
 
   constructor ({
+    fallbackRelays = [],
     offlineRecoverySeconds = DEFAULT_OFFLINE_RECOVERY_SECONDS,
     staleChannelSeconds = DEFAULT_STALE_CHANNEL_SECONDS,
     identityStorageRetentionSeconds = DEFAULT_IDENTITY_STORAGE_RETENTION_SECONDS,
@@ -226,6 +228,7 @@ export class PrivateMessenger {
     _storageClearInterval = globalThis.clearInterval.bind(globalThis),
     _BroadcastChannel = _indexedDB === globalThis.indexedDB ? globalThis.BroadcastChannel : undefined
   } = {}) {
+    this.fallbackRelays = normalizeFallbackRelays(fallbackRelays)
     this.offlineRecoverySeconds = normalizeOfflineRecoverySeconds(offlineRecoverySeconds)
     this.staleChannelSeconds = normalizeStaleChannelSeconds(staleChannelSeconds)
     this.identityStorageRetentionSeconds = normalizeIdentityStorageRetentionSeconds(identityStorageRetentionSeconds)
@@ -756,42 +759,38 @@ export class PrivateMessenger {
   }
 
   async resolveWatchRelays (channel) {
-    if (!channel.usesNip65WatchRelays && channel.relays.length) return channel.relays
-    return this.readRelaysForPubkey(this.userPubkey)
+    const primary = !channel.usesNip65WatchRelays && channel.relays.length ? channel.relays : await this.readRelaysForPubkey(this.userPubkey)
+    return uniq([...primary, ...this.fallbackRelays].map(normalizeRelayUrl))
   }
 
   async resolveSendRouting ({ channel, receiverPubkeys, relays, relayToReceivers, signal }) {
     const recoveryRelays = await this.recoveryMirrorRelays(channel.pubkey)
-    if (relayToReceivers) return { relayToReceivers, recoveryRelays }
-    if (relays?.length) return { relays: uniq(relays), recoveryRelays }
-    if (channel.sendRelays.length) return { relays: channel.sendRelays, recoveryRelays }
-    if (channel.relays.length) return { relays: channel.relays, recoveryRelays }
-    const recipients = uniq(receiverPubkeys)
-    if (recipients.length === 1) {
-      const peer = recipients[0]
-      const relaysByPubkey = await this._getRelaysByPubkey(recipients)
-      const key = `${channel.pubkey}:${peer}`
-      if (!this.sendRelayExclusions.has(key)) {
-        if (this.sendRelayExclusions.size >= 256) this.sendRelayExclusions.delete(this.sendRelayExclusions.keys().next().value)
-        this.sendRelayExclusions.set(key, { channelPubkey: channel.pubkey, exclusions: new Map() })
-      }
-      const routing = createSendRelayRouting({
-        peer, relaysByPubkey, recoveryRelays,
-        signal: signal ? AbortSignal.any([this.sendRoutingLifetime.signal, signal]) : this.sendRoutingLifetime.signal,
-        exclusions: this.sendRelayExclusions.get(key).exclusions,
-        pickRelays: this._pickRelaysForPubkeys,
-        publish: this._privateChannel.publish || privateChannel.publish,
-        publishNymEvent: this._privateChannel.publishNymEvent || privateChannel.publishNymEvent,
-        sendEvent: (...args) => relayPool.sendEvent(...args),
-        isOnline: this._isOnline,
-        isCurrent: () => !this.closePromise && !this.pauseReasons.size && this.channels.has(channel.pubkey)
-      })
-      if (!relayMapRelays(routing.relayToReceivers).length) throw new ValidationError('NO_RELAYS')
-      return routing
+    if (relayToReceivers && !this.fallbackRelays.length) return { relayToReceivers, recoveryRelays }
+    const fixed = relayToReceivers ? null : relays?.length ? uniq(relays) : channel.sendRelays.length ? channel.sendRelays : channel.relays.length ? channel.relays : null
+    if (fixed && !this.fallbackRelays.length) return { relays: fixed, recoveryRelays }
+    const recipients = uniq(receiverPubkeys?.length ? receiverPubkeys : relayMapReceivers(relayToReceivers))
+    const relaysByPubkey = fixed || relayToReceivers ? undefined : await this._getRelaysByPubkey(recipients)
+    const key = `${channel.pubkey}:${[...recipients].sort().join(',')}`
+    if (!this.sendRelayExclusions.has(key)) {
+      if (this.sendRelayExclusions.size >= 256) this.sendRelayExclusions.delete(this.sendRelayExclusions.keys().next().value)
+      this.sendRelayExclusions.set(key, { channelPubkey: channel.pubkey, exclusions: new Map() })
     }
-    const derived = await this.readRelayToReceivers(recipients)
-    if (!relayMapRelays(derived).length) throw new ValidationError('NO_RELAYS')
-    return { relayToReceivers: derived, recoveryRelays }
+    const routing = createSendRelayRouting({
+      peers: fixed && !recipients.length ? [this.userPubkey] : recipients, relaysByPubkey, recoveryRelays, primaryRelays: fixed?.map(normalizeRelayUrl), primaryRelayToReceivers: relayToReceivers, fallbackRelays: this.fallbackRelays,
+      signal: signal ? AbortSignal.any([this.sendRoutingLifetime.signal, signal]) : this.sendRoutingLifetime.signal,
+      exclusions: this.sendRelayExclusions.get(key).exclusions,
+      pickRelays: this._pickRelaysForPubkeys,
+      publish: this._privateChannel.publish || privateChannel.publish,
+      publishNymEvent: this._privateChannel.publishNymEvent || privateChannel.publishNymEvent,
+      sendEvent: (...args) => relayPool.sendEvent(...args),
+      isOnline: this._isOnline,
+      isCurrent: () => !this.closePromise && !this.pauseReasons.size && this.channels.has(channel.pubkey)
+    })
+    if (!relayMapRelays(routing.relayToReceivers).length) throw new ValidationError('NO_RELAYS')
+    // Fixed lists address the original receiver set as a whole, preserving the
+    // existing encryption grouping instead of inventing per-recipient routes.
+    if (fixed) return { relays: fixed, recoveryRelays: routing.recoveryRelays, _publish: routing._publish }
+    return routing
   }
 
   readState () {
@@ -2330,6 +2329,12 @@ function oldestCreatedAt (events) {
   return oldest
 }
 
+function relayMapReceivers (relayToReceivers) {
+  if (!relayToReceivers) return []
+  const values = relayToReceivers instanceof Map ? [...relayToReceivers.values()] : Object.values(relayToReceivers)
+  return uniq(values.flat())
+}
+
 function relayMapRelays (relayToReceivers) {
   if (!relayToReceivers) return []
   const entries = relayToReceivers instanceof Map ? relayToReceivers.entries() : Object.entries(relayToReceivers)

package/private-messenger/session/README.md

@@ -48,21 +48,53 @@ This is a DM profile; group membership/key derivation is not implemented.
 
 ## Relay fallback
 
-Automatic single-recipient routing uses the recipient's NIP-65 read relays, at
-most two per attempt. On `blocked`, `restricted`, `auth-required`, `pow`,
-`rate-limited`, or `error` rejections, or connection/transport/timeout failures,
-it can try remaining read relays after `isOnline` confirms connectivity. Invalid
-messages, local signer/authentication failures and unknown error text retain their
-original diagnosis. Explicit per-call `relays`/`relayToReceivers`, channel
-`sendRelays`/`relays`, and multi-recipient sends do not enable automatic fallback.
+Both `createPrivateMessenger` and `createPrivateMessageSession` accept an optional
+`fallbackRelays` array (default `[]`) at construction. URLs are normalized,
+deduplicated and copied; invalid values throw `ValidationError`. For example:
+
+```js
+const session = createPrivateMessageSession({
+  owner, signer, eventStore,
+  fallbackRelays: ['wss://relay.44billion.net']
+})
+```
+
+Automatic sends try each recipient's NIP-65 read relays first, at most two per
+recipient per attempt, then the configured fallbacks in pairs. Explicit
+per-call `relays`, channel `sendRelays`/`relays` and global `relays` remain primary
+and also support configured fallbacks, including fixed multi-recipient sends.
+Explicit lists retain their requested initial fanout; no recipient relay lookup
+is added. A relay present in both lists is attempted only once per outer event.
+Automatic multi-recipient sends and explicit `relayToReceivers` maps also support
+fallbacks. Explicit maps retain their precedence over fixed lists, initial fanout
+and encrypted recipient subsets, without consulting recipient NIP-65 lists.
+The session coordinator remains a DM API; multi-recipient channels use
+`createPrivateMessenger` directly.
+
+On `blocked`, `restricted`, `auth-required`, `pow`, `rate-limited`, or `error`
+rejections, or connection/transport/timeout failures, replacement requires
+`isOnline` to confirm connectivity. Invalid messages, local signer/authentication
+failures and unknown error text retain their original diagnosis.
+
+Receive routing always adds the configured fallback relays to the effective
+primary list (explicit `relays` or the owner's NIP-65 read relays). Listen there
+from the start, even when primary relays are healthy: a sender may have used a
+fallback after publication was refused elsewhere. Live watches, historical
+recovery and file-channel reads share this policy. NIP-65 refreshes retain the
+fallbacks; outgoing exclusions never remove them from receive subscriptions.
+No public recipient tags or changes to a user's NIP-65 event are introduced.
 
 Each signed outer event is reused verbatim, including router/carrier fragments
 and deletion capabilities. Native errors from exhausted attempts remain in its
-publication report. One successful relay acknowledgement completes that outer
-event immediately; other acknowledgements may update future routing preferences
-without delaying the send. Preferences are channel/recipient-scoped, in-memory,
+publication report. A shared relay's first ACK covers all members assigned to
+that publication batch. If replacements use different relays for different
+members, every pending member must be covered before the outer event succeeds;
+a partial ACK cannot hide another member's failure. Remaining primary routes are
+exhausted before configured fallbacks. Redundant acknowledgements may update
+future routing preferences without delaying a successfully covered send. Preferences are channel/recipient-scoped, in-memory,
 expire after five minutes, and never alter receive subscriptions. A fresh attempt
-can recheck an exhausted list. No additional public fallback relays are invented.
+can recheck an exhausted list. Additional fallback relays come only from the
+caller configuration; absent NIP-65 lists retain the existing discovery defaults.
 
 When offline/interrupted with alternatives remaining, reports carry
 `retryWhenAvailable: true`. The outbox remains pending and emits no `onSendError`.

package/private-messenger/session/index.js

@@ -8,6 +8,7 @@ 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'
+import { normalizeFallbackRelays } from '../helpers/send-routing.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 }
@@ -17,7 +18,8 @@ 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, 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], onMedia = () => {}, onOutbox = () => {}, onError = () => {}, onSendError = () => {}, Messenger = createPrivateMessenger, openOutbox = createChatOutbox, FileTransfer = createPrivateFileTransfer, _onOnline = onOnline, openDownloads = options => createChatOutbox({ ...options, namespace: 'downloads' }) }) {
+  fallbackRelays = normalizeFallbackRelays(fallbackRelays)
   const userSigner = messengerSigner(signer)
   messageStorage ||= createEventStoreMessageStorage({ eventStore })
   chunkStorage ||= eventStore ? createEventStoreChunkStorage({ eventStore }) : undefined
@@ -74,7 +76,7 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
       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 (!messenger) messenger = await Messenger({ fallbackRelays, 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')