libp2r2p 0.10.4 → 0.10.6

package/README.md

@@ -264,9 +264,18 @@ import {
 import { generateSecretKey, getPublicKey } from 'libp2r2p/key'
 import { eventKinds, classifyKind } from 'libp2r2p/kind'
 import * as nip44 from 'libp2r2p/nip44'
-import { assertValidPublicRelayUrl, normalizeRelayUrl } from 'libp2r2p/url'
+import {
+  assertValidPublicBlossomServerUrl,
+  assertValidPublicRelayUrl,
+  normalizeBlossomServerUrl,
+  normalizeRelayUrl
+} from 'libp2r2p/url'
 ```
 
+Blossom server normalization accepts root `http:` origins for local
+development. Public Blossom validation additionally requires `https:` and a
+public host, and rejects credentials, paths, query strings and fragments.
+
 `classifyEvent()` from `libp2r2p/event` combines the exact NIP-01 kind
 ranges with tag-defined behavior. The first `d` tag may add `replaceable` or
 `addressable`, while an `expiration` tag equal to `created_at` adds
@@ -332,6 +341,54 @@ Low-level relay sockets, subscriptions, message parsing, and serialization are
 internal implementation details; use `RelayPool` or the `relayPool` singleton
 from `libp2r2p/relay`.
 
+The same public subpath exports `getRelaysByPubkey(pubkeys)`, which discovers
+the latest NIP-65 relay list for every requested pubkey through `seedRelays`,
+normalizes and deduplicates its public relay URLs, and falls back to the first
+two `freeRelays` when no list is available. Its result can be passed directly
+to `pickRelaysForPubkeys(pubkeys, relaysByPubkey)` to batch authors that share
+read or write relays.
+
+`getRelaysByPubkey` accepts a few options:
+
+- `includeEvents` returns each pubkey's latest kind `10002` event alongside its
+  parsed relays (`{ read, write, event }`), for consumers that need the original
+  event (storage, re-signing, freshness tracking).
+- `forceRefresh` re-queries `seedRelays` even when the pubkey is cached, without
+  regressing a newer cached event when the relay returns an older one.
+- `timeout` / `timeoutAfterFirstEose` tune the relay-list query timing. The
+  default opens a short grace window after the first EOSE with events, matching
+  `RelayPool.getEvents`.
+- `emptyRelaysFallback` sets the relays returned when a pubkey has no relay
+  list (default: the first two `freeRelays`); pass `[]` to return empty
+  `read`/`write` arrays instead, keeping the free-relay decision with the
+  caller.
+- `relayUrlPolicy` opts into non-default URL validation: `onion` allows
+  `ws://`/`wss://` `.onion` hosts, `localRelay` allows the standardized
+  `ws://localhost:4869` local relay, and `nostrEntityUrls` stops rejecting
+  public URLs that contain `npub1`/`nprofile1`. All other non-public or
+  insecure URLs stay rejected.
+
+`parseRelayListEvent(event, relayUrlPolicy)` is exported from the same subpath
+for consumers that parse relay-list events they receive outside
+`getRelaysByPubkey`, so routing and persistence always agree on the parsed
+shape.
+
+`pickRelaysForPubkeys` also accepts `excludeRelaysByPubkey` (relays already
+queried per pubkey, as an object or `Map`) and `emptyRelaysFallback` (the
+relays used when a pubkey has no typed relays; pass `[]` to leave that pubkey
+unrouted). Together with `maxPerPubkey: Infinity` these express a second,
+exhaustive pass over the relays that were not yet tried for each author.
+
+For callers that want the whole two-pass flow, `getLatestEventsByPubkey`
+fetches the latest replaceable events (or addressable events when
+`dTagsByPubkey` maps pubkeys to their `d` tags) through NIP-65 write relays:
+the first pass routes through up to `maxPerPubkey` shared relays, and missing
+authors are retried on every remaining relay plus `fallbackRelays` (default:
+the first three `freeRelays`), excluding what was already queried. It accepts
+`relaysByPubkey` to reuse a previous discovery (only missing pubkeys are then
+discovered) and returns `{ events, byPubkey, relaysByPubkey }` so the merged
+relay map can be passed back on later calls.
+
 ## Binary encodings
 
 Base16, Base36, Base62, Base64/Base64URL, and Base93 helpers are available

package/package.json

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

package/relay/helpers/routing.js

@@ -2,15 +2,30 @@ import { freeRelays } from '../constants/index.js'
 
 const DEFAULT_RELAYS_PER_PUBKEY = 2
 
+function excludedRelaysFor (excludeRelaysByPubkey, pubkey) {
+  if (!excludeRelaysByPubkey) return []
+  return excludeRelaysByPubkey instanceof Map
+    ? excludeRelaysByPubkey.get(pubkey) || []
+    : excludeRelaysByPubkey[pubkey] || []
+}
+
 // Given pubkeys and their relay mappings, picks the minimum set of relays
 // that covers all pubkeys (up to maxPerPubkey relays each), preferring
 // relays shared by more pubkeys. Returns Map<relayUrl, pubkey[]>.
-export function pickRelaysForPubkeys (pubkeys, relaysByPubkey, { maxPerPubkey = DEFAULT_RELAYS_PER_PUBKEY, relayType = 'write' } = {}) {
+export function pickRelaysForPubkeys (pubkeys, relaysByPubkey, {
+  maxPerPubkey = DEFAULT_RELAYS_PER_PUBKEY,
+  relayType = 'write',
+  excludeRelaysByPubkey,
+  emptyRelaysFallback = freeRelays.slice(0, DEFAULT_RELAYS_PER_PUBKEY)
+} = {}) {
   const type = relayType === 'read' ? 'read' : 'write'
   const pkToPossibleRelays = new Map()
   for (const pk of pubkeys) {
     const relays = relaysByPubkey[pk]?.[type] || []
-    pkToPossibleRelays.set(pk, new Set(relays.length ? relays : freeRelays.slice(0, DEFAULT_RELAYS_PER_PUBKEY)))
+    const excluded = new Set(excludedRelaysFor(excludeRelaysByPubkey, pk))
+    const candidates = (relays.length ? relays : emptyRelaysFallback)
+      .filter(relay => !excluded.has(relay))
+    pkToPossibleRelays.set(pk, new Set(candidates))
   }
 
   const relayCounts = new Map()

package/relay/index.js

@@ -1,4 +1,5 @@
 export { freeRelays, nappRelays, seedRelays } from './constants/index.js'
 export { pickRelaysForPubkeys } from './helpers/routing.js'
 export { RelayPool, relayPool } from './services/relay-pool.js'
-export { getRelaysByPubkey, subscribeRelayListUpdates } from './services/query.js'
+export { getLatestEventsByPubkey } from './services/events.js'
+export { getRelaysByPubkey, parseRelayListEvent, subscribeRelayListUpdates } from './services/query.js'

package/relay/services/events.js

@@ -0,0 +1,154 @@
+import { freeRelays } from '../constants/index.js'
+import { pickRelaysForPubkeys } from '../helpers/routing.js'
+import { relayPool } from './relay-pool.js'
+import { getRelaysByPubkey } from './query.js'
+
+const DEFAULT_MAX_PER_PUBKEY = 2
+const DEFAULT_FALLBACK_RELAY_COUNT = 3
+
+const getEvents = (...args) => relayPool.getEvents(...args)
+
+function hasOwn (object, key) {
+  return Object.prototype.hasOwnProperty.call(object, key)
+}
+
+function eventAddress (event) {
+  const dTag = event.tags?.find(tag => tag[0] === 'd')
+  return `${event.kind}:${event.pubkey}:${dTag?.[1] ?? ''}`
+}
+
+// NIP-01 ordering for replaceable and addressable events.
+function isNewerEvent (candidate, current) {
+  if (!candidate) return false
+  if (!current) return true
+  if (candidate.created_at !== current.created_at) return candidate.created_at > current.created_at
+  if (typeof candidate.id !== 'string') return false
+  return typeof current.id !== 'string' || candidate.id < current.id
+}
+
+function mergeLatestEvents (target, events) {
+  for (const event of events) {
+    const address = eventAddress(event)
+    if (isNewerEvent(event, target[address])) target[address] = event
+  }
+  return target
+}
+
+// Records which relays were already queried for each pubkey.
+function getSelectedRelaysByPubkey (pubkeys, relayToAuthors) {
+  const selected = Object.fromEntries(pubkeys.map(pubkey => [pubkey, new Set()]))
+  for (const [relay, authors] of relayToAuthors) {
+    for (const pubkey of authors) selected[pubkey]?.add(relay)
+  }
+  return selected
+}
+
+// Fetches batched events and keeps the newest event per address.
+async function fetchLatestEventsByRelay (relayToAuthors, { kinds, dTagsByPubkey, getEvents }) {
+  const requests = []
+  for (const [relay, authors] of relayToAuthors) {
+    const authorsByD = new Map()
+    for (const pubkey of authors) {
+      const d = dTagsByPubkey?.[pubkey] ?? ''
+      if (!authorsByD.has(d)) authorsByD.set(d, [])
+      authorsByD.get(d).push(pubkey)
+    }
+    for (const [d, dAuthors] of authorsByD) {
+      const filter = { kinds, authors: dAuthors }
+      if (d) filter['#d'] = [d]
+      requests.push(getEvents(filter, [relay])
+        .then(response => ({ requested: new Set(dAuthors), events: response.result || [] })))
+    }
+  }
+
+  const results = await Promise.allSettled(requests)
+  const latestByAddress = {}
+  for (const result of results) {
+    if (result.status !== 'fulfilled') continue
+    const { requested, events } = result.value
+    mergeLatestEvents(latestByAddress, events.filter(event =>
+      kinds.includes(event?.kind) && requested.has(event?.pubkey)
+    ))
+  }
+  return latestByAddress
+}
+
+/**
+ * Fetches the latest replaceable (or addressable, with `dTagsByPubkey`) events
+ * for many pubkeys through their NIP-65 relays in two batched passes.
+ *
+ * The first pass routes through up to `maxPerPubkey` relays per author,
+ * preferring relays shared by more authors. Authors still missing after that
+ * pass are retried on every remaining relay plus `fallbackRelays`, excluding
+ * relays already queried for them.
+ *
+ * When `relaysByPubkey` is provided, it is reused as-is for the pubkeys it
+ * covers; only missing pubkeys are discovered, and the merged map is returned
+ * so it can be passed back on a later call.
+ */
+export async function getLatestEventsByPubkey (pubkeys, {
+  kinds,
+  dTagsByPubkey,
+  relayType = 'write',
+  maxPerPubkey = DEFAULT_MAX_PER_PUBKEY,
+  fallbackRelays = freeRelays.slice(0, DEFAULT_FALLBACK_RELAY_COUNT),
+  relaysByPubkey,
+  relayListOptions,
+  _getRelaysByPubkey = getRelaysByPubkey,
+  _getEvents = getEvents
+} = {}) {
+  const authors = [...new Set(pubkeys || [])].filter(Boolean)
+  if (!authors.length) return { events: [], byPubkey: {}, relaysByPubkey: {} }
+  if (!Array.isArray(kinds) || kinds.length === 0) throw new Error('Missing kinds')
+  const type = relayType === 'read' ? 'read' : 'write'
+
+  const relaysByAuthor = { ...(relaysByPubkey || {}) }
+  const missingRelayAuthors = authors.filter(pubkey => !hasOwn(relaysByAuthor, pubkey))
+  if (missingRelayAuthors.length) {
+    let discovered
+    try {
+      discovered = await _getRelaysByPubkey(missingRelayAuthors, relayListOptions)
+    } catch (error) {
+      console.error('Failed to discover publisher relays:', error)
+      discovered = Object.fromEntries(missingRelayAuthors.map(pubkey => [pubkey, { read: [], write: [] }]))
+    }
+    for (const pubkey of missingRelayAuthors) {
+      relaysByAuthor[pubkey] = discovered?.[pubkey] || { read: [], write: [] }
+    }
+  }
+
+  const primaryAuthors = authors.filter(pubkey => relaysByAuthor[pubkey]?.[type]?.length)
+  const primaryRoutes = pickRelaysForPubkeys(primaryAuthors, relaysByAuthor, { maxPerPubkey, relayType })
+  const selectedRelays = getSelectedRelaysByPubkey(authors, primaryRoutes)
+  const latestByAddress = await fetchLatestEventsByRelay(primaryRoutes, {
+    kinds,
+    dTagsByPubkey,
+    getEvents: _getEvents
+  })
+  const foundPubkeys = new Set(Object.values(latestByAddress).map(event => event.pubkey))
+  const missingAuthors = authors.filter(pubkey => !foundPubkeys.has(pubkey))
+
+  if (missingAuthors.length) {
+    const fallbackRelaysByPubkey = Object.fromEntries(missingAuthors.map(pubkey => [
+      pubkey, { [type]: [...new Set([...(relaysByAuthor[pubkey]?.[type] || []), ...fallbackRelays])] }
+    ]))
+    const fallbackRoutes = pickRelaysForPubkeys(missingAuthors, fallbackRelaysByPubkey, {
+      maxPerPubkey: Infinity,
+      relayType,
+      excludeRelaysByPubkey: selectedRelays,
+      emptyRelaysFallback: []
+    })
+    mergeLatestEvents(latestByAddress, Object.values(
+      await fetchLatestEventsByRelay(fallbackRoutes, {
+        kinds,
+        dTagsByPubkey,
+        getEvents: _getEvents
+      })
+    ))
+  }
+
+  const events = Object.values(latestByAddress)
+  const byPubkey = {}
+  for (const event of events) byPubkey[event.pubkey] = event
+  return { events, byPubkey, relaysByPubkey: relaysByAuthor }
+}

package/relay/services/query.js

@@ -1,5 +1,6 @@
 import { freeRelays, seedRelays } from '../constants/index.js'
 import { relayPool } from './relay-pool.js'
+import { isValidPublicRelayUrl, normalizeRelayUrl } from '../../url/index.js'
 
 const QUERY_CACHE_MS = 40 * 60 * 1000
 const RELAY_CACHE_MAX_ITEMS = 500
@@ -8,9 +9,14 @@ const relaysByPubkey = Object.create(null)
 const relayCacheTimersByPubkey = Object.create(null)
 const relayCacheAddedAtByPubkey = Object.create(null)
 const relayCacheEventCreatedAtByPubkey = Object.create(null)
+const relayCacheEventIdByPubkey = Object.create(null)
+const relayCacheEventByPubkey = Object.create(null)
+const relayRequestsByPubkey = new Map()
 
 const getEvents = (...args) => relayPool.getEvents(...args)
 const getEventsFeedGenerator = (...args) => relayPool.getEventsFeedGenerator(...args)
+const RELAY_LIST_QUERY_TIMEOUT_MS = 5000
+const RELAY_LIST_QUERY_TIMEOUT_AFTER_FIRST_EOSE_MS = 500
 
 function hasCachedKey (cache, key) {
   return Object.prototype.hasOwnProperty.call(cache, key)
@@ -28,15 +34,27 @@ function cloneRelays (relays) {
   }
 }
 
+function cloneRelayListEvent (event) {
+  if (!event) return null
+  return { ...event, tags: [...(event.tags || [])] }
+}
+
 // NIP-65 relay-list tags without a marker apply to both read and write use.
-function parseRelayListEvent (event) {
+export function parseRelayListEvent (event, relayUrlPolicy) {
   const out = { read: [], write: [] }
   if (!event || event.kind !== 10002) return out
-  for (const tag of event.tags) {
+  for (const tag of event.tags || []) {
     if (tag[0] !== 'r' || typeof tag[1] !== 'string') continue
-    if (tag[2] === 'read') out.read.push(tag[1])
-    else if (tag[2] === 'write') out.write.push(tag[1])
-    else { out.read.push(tag[1]); out.write.push(tag[1]) }
+    let relay
+    try {
+      relay = normalizeRelayUrl(tag[1])
+    } catch {
+      continue
+    }
+    if (!isValidPublicRelayUrl(relay, relayUrlPolicy)) continue
+    if (tag[2] === 'read') out.read.push(relay)
+    else if (tag[2] === 'write') out.write.push(relay)
+    else { out.read.push(relay); out.write.push(relay) }
   }
   out.read = [...new Set(out.read)]
   out.write = [...new Set(out.write)]
@@ -52,6 +70,16 @@ function relayListCreatedAt (event) {
   return Number.isFinite(event?.created_at) ? event.created_at : 0
 }
 
+function isNewerRelayListEvent (candidate, current) {
+  if (!candidate) return false
+  if (!current) return true
+  const candidateCreatedAt = relayListCreatedAt(candidate)
+  const currentCreatedAt = relayListCreatedAt(current)
+  if (candidateCreatedAt !== currentCreatedAt) return candidateCreatedAt > currentCreatedAt
+  if (typeof candidate.id !== 'string') return false
+  return typeof current.id !== 'string' || candidate.id < current.id
+}
+
 function areRelaySetsEqual (a, b) {
   const left = new Set(a || [])
   const right = new Set(b || [])
@@ -82,12 +110,16 @@ function deleteCachedRelay (pubkey) {
   delete relayCacheTimersByPubkey[pubkey]
   delete relayCacheAddedAtByPubkey[pubkey]
   delete relayCacheEventCreatedAtByPubkey[pubkey]
+  delete relayCacheEventIdByPubkey[pubkey]
+  delete relayCacheEventByPubkey[pubkey]
 }
 
-function setCachedRelays (pubkey, relays, createdAt, cacheMs) {
+function setCachedRelays (pubkey, relays, event, cacheMs) {
   relaysByPubkey[pubkey] = cloneRelays(relays)
   relayCacheAddedAtByPubkey[pubkey] = Date.now()
-  relayCacheEventCreatedAtByPubkey[pubkey] = createdAt
+  relayCacheEventCreatedAtByPubkey[pubkey] = relayListCreatedAt(event)
+  relayCacheEventIdByPubkey[pubkey] = typeof event?.id === 'string' ? event.id : null
+  relayCacheEventByPubkey[pubkey] = event || null
   clearTimeout(relayCacheTimersByPubkey[pubkey])
   if (cacheMs > 0) {
     relayCacheTimersByPubkey[pubkey] = maybeUnref(setTimeout(() => {
@@ -114,20 +146,24 @@ export function clearRelayQueryCache () {
   for (const key of Object.keys(relayCacheTimersByPubkey)) delete relayCacheTimersByPubkey[key]
   for (const key of Object.keys(relayCacheAddedAtByPubkey)) delete relayCacheAddedAtByPubkey[key]
   for (const key of Object.keys(relayCacheEventCreatedAtByPubkey)) delete relayCacheEventCreatedAtByPubkey[key]
+  for (const key of Object.keys(relayCacheEventIdByPubkey)) delete relayCacheEventIdByPubkey[key]
+  for (const key of Object.keys(relayCacheEventByPubkey)) delete relayCacheEventByPubkey[key]
 }
 
-export function cacheRelayListEvent (event, { cacheMs = QUERY_CACHE_MS } = {}) {
+export function cacheRelayListEvent (event, { cacheMs = QUERY_CACHE_MS, relayUrlPolicy } = {}) {
   if (!event || event.kind !== 10002 || !event.pubkey) return null
-  const createdAt = relayListCreatedAt(event)
   const previousCreatedAt = relayCacheEventCreatedAtByPubkey[event.pubkey]
-  if (previousCreatedAt != null && createdAt <= previousCreatedAt) return null
+  const previousEvent = previousCreatedAt == null
+    ? null
+    : { created_at: previousCreatedAt, id: relayCacheEventIdByPubkey[event.pubkey] }
+  if (!isNewerRelayListEvent(event, previousEvent)) return null
 
   const previousRelays = hasCachedKey(relaysByPubkey, event.pubkey)
     ? cloneRelays(relaysByPubkey[event.pubkey])
     : null
-  const relays = parseRelayListEvent(event)
+  const relays = parseRelayListEvent(event, relayUrlPolicy)
   const changes = relaySetChanges(previousRelays, relays)
-  setCachedRelays(event.pubkey, relays, createdAt, cacheMs)
+  setCachedRelays(event.pubkey, relays, event, cacheMs)
   pruneRelayCache()
 
   return {
@@ -144,6 +180,7 @@ export function subscribeRelayListUpdates (pubkeys, {
   onChange,
   relays = seedRelays,
   cacheMs = QUERY_CACHE_MS,
+  relayUrlPolicy,
   _eventsFeedGenerator = getEventsFeedGenerator
 } = {}) {
   const authors = uniquePubkeys(pubkeys, { requireHex: _eventsFeedGenerator === getEventsFeedGenerator })
@@ -163,7 +200,7 @@ export function subscribeRelayListUpdates (pubkeys, {
         timeoutAfterFirstEose: null
       })) {
         if (closed || !authors.includes(event.pubkey)) continue
-        const update = cacheRelayListEvent(event, { cacheMs })
+        const update = cacheRelayListEvent(event, { cacheMs, relayUrlPolicy })
         if (!update || !relayTypeChanged(update.changes, relayType)) continue
         onChange?.({
           ...update,
@@ -183,42 +220,83 @@ export function subscribeRelayListUpdates (pubkeys, {
   }
 }
 
-export async function getRelaysByPubkey (pubkeys, { _getEvents = getEvents, 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(relaysByPubkey, pubkey)) out[pubkey] = cloneRelays(relaysByPubkey[pubkey])
-    else missingPubkeys.push(pubkey)
-  }
-  if (!missingPubkeys.length) return out
-
-  const { result: events } = await _getEvents({
+async function loadMissingRelays (missingPubkeys, {
+  getEvents,
+  cacheMs,
+  timeout = RELAY_LIST_QUERY_TIMEOUT_MS,
+  timeoutAfterFirstEose = RELAY_LIST_QUERY_TIMEOUT_AFTER_FIRST_EOSE_MS,
+  relayUrlPolicy,
+  emptyRelaysFallback = freeRelays.slice(0, 2)
+}) {
+  const { result: events } = await getEvents({
     kinds: [10002],
     authors: missingPubkeys,
     limit: missingPubkeys.length
   }, seedRelays, {
-    timeout: 5000,
-    timeoutAfterFirstEose: null
+    timeout,
+    timeoutAfterFirstEose
   })
 
   const latestByPubkey = {}
-  for (const event of events) {
+  for (const event of events || []) {
     if (!missingPubkeys.includes(event.pubkey)) continue
-    if (!latestByPubkey[event.pubkey] || event.created_at > latestByPubkey[event.pubkey].created_at) {
-      latestByPubkey[event.pubkey] = event
-    }
+    if (isNewerRelayListEvent(event, latestByPubkey[event.pubkey])) latestByPubkey[event.pubkey] = event
   }
 
   for (const pubkey of missingPubkeys) {
-    const relays = latestByPubkey[pubkey]
-      ? parseRelayListEvent(latestByPubkey[pubkey])
-      : { read: freeRelays.slice(0, 2), write: freeRelays.slice(0, 2) }
-    setCachedRelays(pubkey, relays, relayListCreatedAt(latestByPubkey[pubkey]), cacheMs)
-    out[pubkey] = relays
+    const fetchedEvent = latestByPubkey[pubkey]
+    const cachedEvent = relayCacheEventByPubkey[pubkey] || null
+    const event = isNewerRelayListEvent(fetchedEvent, cachedEvent) ? fetchedEvent : cachedEvent
+    const relays = event
+      ? parseRelayListEvent(event, relayUrlPolicy)
+      : { read: [...emptyRelaysFallback], write: [...emptyRelaysFallback] }
+    setCachedRelays(pubkey, relays, event, cacheMs)
   }
   pruneRelayCache()
-  return out
+}
+
+export async function getRelaysByPubkey (pubkeys, {
+  _getEvents = getEvents,
+  cacheMs = QUERY_CACHE_MS,
+  includeEvents = false,
+  forceRefresh = false,
+  timeout = RELAY_LIST_QUERY_TIMEOUT_MS,
+  timeoutAfterFirstEose = RELAY_LIST_QUERY_TIMEOUT_AFTER_FIRST_EOSE_MS,
+  relayUrlPolicy,
+  emptyRelaysFallback = freeRelays.slice(0, 2)
+} = {}) {
+  const pubkeyList = uniquePubkeys(pubkeys, { requireHex: _getEvents === getEvents })
+  if (!pubkeyList.length) return {}
+
+  const loadPubkeys = forceRefresh
+    ? pubkeyList
+    : pubkeyList.filter(pubkey => !hasCachedKey(relaysByPubkey, pubkey))
+  const pubkeysToLoad = loadPubkeys.filter(pubkey => !relayRequestsByPubkey.has(pubkey))
+  if (pubkeysToLoad.length) {
+    const request = loadMissingRelays(pubkeysToLoad, {
+      getEvents: _getEvents,
+      cacheMs,
+      timeout,
+      timeoutAfterFirstEose,
+      relayUrlPolicy,
+      emptyRelaysFallback
+    }).finally(() => {
+      for (const pubkey of pubkeysToLoad) {
+        if (relayRequestsByPubkey.get(pubkey) === request) relayRequestsByPubkey.delete(pubkey)
+      }
+    })
+    for (const pubkey of pubkeysToLoad) relayRequestsByPubkey.set(pubkey, request)
+  }
+
+  await Promise.all([...new Set(
+    loadPubkeys.map(pubkey => relayRequestsByPubkey.get(pubkey)).filter(Boolean)
+  )])
+
+  return Object.fromEntries(pubkeyList
+    .filter(pubkey => hasCachedKey(relaysByPubkey, pubkey))
+    .map(pubkey => {
+      const entry = cloneRelays(relaysByPubkey[pubkey])
+      if (includeEvents) entry.event = cloneRelayListEvent(relayCacheEventByPubkey[pubkey])
+      return [pubkey, entry]
+    }))
 }

package/url/index.js

@@ -53,6 +53,30 @@ function removeEmptyQuerySegments (url) {
   url.searchParams.sort()
 }
 
+function publicHostError (url, {
+  invalidHostCode,
+  nonPublicHostCode,
+  nonPublicIpCode
+}) {
+  const hostname = url.hostname.toLowerCase().replace(/\.+$/, '')
+  if (
+    hostname === 'localhost' ||
+    hostname.endsWith('.localhost') ||
+    hostname.endsWith('.local') ||
+    hostname.endsWith('.onion')
+  ) return nonPublicHostCode
+
+  const unwrappedHostname = hostname.replace(/^\[|\]$/g, '')
+  if (isIpv4Address(unwrappedHostname)) {
+    if (!isPublicIpv4Address(unwrappedHostname)) return nonPublicIpCode
+  } else if (unwrappedHostname.includes(':')) {
+    if (!isPublicIpv6Address(unwrappedHostname)) return nonPublicIpCode
+  } else if (!hostname.includes('.')) {
+    return invalidHostCode
+  }
+  return null
+}
+
 export function normalizeRelayUrl (value) {
   if (typeof value !== 'string' || value.trim().length === 0) {
     throw new ValidationError('INVALID_RELAY_URL', { message: 'URL_SHOULD_BE_A_STRING' })
@@ -76,7 +100,44 @@ export function normalizeRelayUrl (value) {
   return url.toString().replace(/^(wss?:\/\/[^/?#]+)\/(?=[?#]|$)/, '$1')
 }
 
-function publicRelayUrlError (value) {
+// Canonicalizes the origin used by the root-level Blossom HTTP endpoints.
+export function normalizeBlossomServerUrl (value) {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new ValidationError('INVALID_BLOSSOM_SERVER_URL', { message: 'URL_SHOULD_BE_A_STRING' })
+  }
+  const input = value.trim()
+  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(input)) {
+    throw new ValidationError('INVALID_BLOSSOM_SERVER_URL', { message: 'ABSOLUTE_URL_REQUIRED' })
+  }
+  let url
+  try {
+    url = new URL(input)
+  } catch (cause) {
+    throw new ValidationError('INVALID_BLOSSOM_SERVER_URL', { cause })
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new ValidationError('INVALID_BLOSSOM_SERVER_PROTOCOL')
+  }
+  if (url.username || url.password) {
+    throw new ValidationError('BLOSSOM_SERVER_URL_CREDENTIALS_NOT_ALLOWED')
+  }
+  if (!/^\/*$/.test(url.pathname)) {
+    throw new ValidationError('BLOSSOM_SERVER_URL_PATH_NOT_ALLOWED')
+  }
+  if (url.search) throw new ValidationError('BLOSSOM_SERVER_URL_QUERY_NOT_ALLOWED')
+  if (url.hash) throw new ValidationError('BLOSSOM_SERVER_URL_FRAGMENT_NOT_ALLOWED')
+  url.hostname = url.hostname.replace(/\.+$/, '')
+  return url.origin
+}
+
+function isPolicyRelayUrl (url, policy) {
+  const hostname = url.hostname.toLowerCase().replace(/\.+$/, '')
+  if (policy?.onion && hostname.endsWith('.onion')) return true
+  if (policy?.localRelay && hostname === 'localhost' && url.port === '4869' && (url.pathname === '/' || url.pathname === '')) return true
+  return false
+}
+
+function publicRelayUrlError (value, policy = {}) {
   if (typeof value !== 'string' || value.trim().length === 0) return 'INVALID_RELAY_URL'
   let input = value.trim()
   if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(input)) input = `wss://${input}`
@@ -94,38 +155,59 @@ function publicRelayUrlError (value) {
   }
 
   const url = new URL(normalized)
-  if (url.protocol !== 'wss:') return 'INSECURE_RELAY_URL'
+  const policyRelay = isPolicyRelayUrl(url, policy)
+  if (url.protocol !== 'wss:' && !policyRelay) return 'INSECURE_RELAY_URL'
   if (url.username || url.password) return 'RELAY_URL_CREDENTIALS_NOT_ALLOWED'
 
-  const hostname = url.hostname.toLowerCase()
-  if (
-    hostname === 'localhost' ||
-    hostname.endsWith('.localhost') ||
-    hostname.endsWith('.local') ||
-    hostname.endsWith('.onion')
-  ) return 'NON_PUBLIC_RELAY_HOST'
-
-  const unwrappedHostname = hostname.replace(/^\[|\]$/g, '')
-  if (isIpv4Address(unwrappedHostname)) {
-    if (!isPublicIpv4Address(unwrappedHostname)) return 'NON_PUBLIC_RELAY_IP'
-  } else if (unwrappedHostname.includes(':')) {
-    if (!isPublicIpv6Address(unwrappedHostname)) return 'NON_PUBLIC_RELAY_IP'
-  } else if (!hostname.includes('.')) {
-    return 'INVALID_RELAY_HOST'
+  if (!policyRelay) {
+    const hostError = publicHostError(url, {
+      invalidHostCode: 'INVALID_RELAY_HOST',
+      nonPublicHostCode: 'NON_PUBLIC_RELAY_HOST',
+      nonPublicIpCode: 'NON_PUBLIC_RELAY_IP'
+    })
+    if (hostError) return hostError
   }
 
-  const lowerValue = normalized.toLowerCase()
-  if (lowerValue.includes('npub1') || lowerValue.includes('nprofile1')) return 'RELAY_URL_NOSTR_ENTITY_NOT_ALLOWED'
+  if (!policy?.nostrEntityUrls) {
+    const lowerValue = normalized.toLowerCase()
+    if (lowerValue.includes('npub1') || lowerValue.includes('nprofile1')) return 'RELAY_URL_NOSTR_ENTITY_NOT_ALLOWED'
+  }
 
   return null
 }
 
-export function isValidPublicRelayUrl (value) {
-  return publicRelayUrlError(value) === null
+export function isValidPublicRelayUrl (value, policy) {
+  return publicRelayUrlError(value, policy) === null
+}
+
+export function assertValidPublicRelayUrl (value, policy) {
+  const code = publicRelayUrlError(value, policy)
+  if (code) throw new ValidationError(code)
+  return value
+}
+
+function publicBlossomServerUrlError (value) {
+  let normalized
+  try {
+    normalized = normalizeBlossomServerUrl(value)
+  } catch (error) {
+    return error instanceof ValidationError ? error.code : 'INVALID_BLOSSOM_SERVER_URL'
+  }
+  const url = new URL(normalized)
+  if (url.protocol !== 'https:') return 'INSECURE_BLOSSOM_SERVER_URL'
+  return publicHostError(url, {
+    invalidHostCode: 'INVALID_BLOSSOM_SERVER_HOST',
+    nonPublicHostCode: 'NON_PUBLIC_BLOSSOM_SERVER_HOST',
+    nonPublicIpCode: 'NON_PUBLIC_BLOSSOM_SERVER_IP'
+  })
+}
+
+export function isValidPublicBlossomServerUrl (value) {
+  return publicBlossomServerUrlError(value) === null
 }
 
-export function assertValidPublicRelayUrl (value) {
-  const code = publicRelayUrlError(value)
+export function assertValidPublicBlossomServerUrl (value) {
+  const code = publicBlossomServerUrlError(value)
   if (code) throw new ValidationError(code)
   return value
 }