libp2r2p 0.7.0 → 0.9.0

package/relay/services/relay-connection.js

@@ -1,156 +1,257 @@
-import { Relay } from 'nostr-tools/relay'
+import { isValidEvent } from '../../event/index.js'
+import { ValidationError } from '../../error/index.js'
 import { maybeUnref } from '../helpers/timer.js'
 
-function relayError (reason, fallback) {
-  return reason instanceof Error ? reason : new Error(reason || fallback)
+const DEFAULT_CONNECT_TIMEOUT = 3000
+const DEFAULT_OPERATION_TIMEOUT = 30000
+
+function errorFrom (reason, fallback) {
+  return reason instanceof Error ? reason : new Error(String(reason || fallback))
 }
 
-// Relay.auth() caches one authentication promise per connection. NIP-42 permits
-// several pubkeys on one connection, so this adapter tracks AUTH replies by
-// signed auth-event id instead of using Relay.auth().
-export class RelayConnection extends Relay {
-  #challenge = null
-  #pendingAuths = new Map()
-  #countSerial = 0
-  #pendingCounts = new Map()
-
-  constructor (url) {
-    super(url)
-    this.onclose = () => {
-      this.#challenge = null
-      this.#rejectPendingAuths(new Error('AUTH_CONNECTION_CLOSED'))
-      this.#rejectPendingCounts(new Error('COUNT_CONNECTION_CLOSED'))
-    }
+function hasMatchingPrefix (values, candidate) {
+  return !values || values.some(value => typeof value === 'string' && candidate.startsWith(value))
+}
+
+function doesEventMatchFilter (filter, event) {
+  if (filter.ids && !hasMatchingPrefix(filter.ids, event.id)) return false
+  if (filter.authors && !hasMatchingPrefix(filter.authors, event.pubkey)) return false
+  if (filter.kinds && !filter.kinds.includes(event.kind)) return false
+  if (filter.since != null && event.created_at < filter.since) return false
+  if (filter.until != null && event.created_at > filter.until) return false
+  for (const [key, values] of Object.entries(filter)) {
+    if (!key.startsWith('#') || !Array.isArray(values)) continue
+    const name = key.slice(1)
+    if (!event.tags.some(tag => tag[0] === name && values.includes(tag[1]))) return false
   }
+  return true
+}
 
-  #settleAuth (eventId, { success, reason }) {
-    const pending = this.#pendingAuths.get(eventId)
-    if (!pending) return
+function doesEventMatchAnyFilter (filters, event) {
+  return filters.some(filter => doesEventMatchFilter(filter, event))
+}
 
-    this.#pendingAuths.delete(eventId)
-    clearTimeout(pending.timer)
-    if (success) pending.resolve(reason)
-    else pending.reject(relayError(reason, 'AUTH_REJECTED'))
-  }
+async function messageText (data) {
+  if (typeof data === 'string') return data
+  if (data instanceof ArrayBuffer) return new TextDecoder().decode(data)
+  if (ArrayBuffer.isView(data)) return new TextDecoder().decode(data)
+  if (typeof data?.text === 'function') return await data.text()
+  throw new ValidationError('INVALID_RELAY_MESSAGE')
+}
 
-  #rejectPendingAuths (reason) {
-    for (const eventId of [...this.#pendingAuths.keys()]) {
-      this.#settleAuth(eventId, { success: false, reason })
-    }
+export class RelayConnection {
+  #WebSocket
+  #connectPromise = null
+  #challenge = null
+  #serial = 0
+  #subscriptions = new Map()
+  #publishes = new Map()
+  #authentications = new Map()
+  #counts = new Map()
+
+  constructor (url, { WebSocket: WebSocketImpl = globalThis.WebSocket } = {}) {
+    this.url = url
+    this.#WebSocket = WebSocketImpl
+    this.ws = null
+    this.publishTimeout = DEFAULT_OPERATION_TIMEOUT
+    this.onnotice = null
+    this.onerror = null
+    this.onclose = null
+    this.onauth = null
   }
 
-  #settleCount (id, { payload, reason }) {
-    const pending = this.#pendingCounts.get(id)
-    if (!pending) return
+  async connect ({ timeout = DEFAULT_CONNECT_TIMEOUT, signal } = {}) {
+    if (this.ws?.readyState === 1) return
+    if (this.#connectPromise) return await this.#connectPromise
+    if (signal?.aborted) throw new Error('CONNECT_ABORTED')
+    if (typeof this.#WebSocket !== 'function') throw new Error('WEBSOCKET_UNAVAILABLE')
 
-    this.#pendingCounts.delete(id)
-    pending.signal?.removeEventListener('abort', pending.onAbort)
-    if (reason !== undefined) pending.reject(relayError(reason, 'COUNT_REJECTED'))
-    else pending.resolve(payload)
+    this.#connectPromise = new Promise((resolve, reject) => {
+      const socket = new this.#WebSocket(this.url)
+      this.ws = socket
+      let settled = false
+      const finish = (reason) => {
+        if (settled) return
+        settled = true
+        clearTimeout(timer)
+        signal?.removeEventListener('abort', onAbort)
+        if (reason) {
+          try { socket.close() } catch {}
+          reject(reason)
+        } else resolve()
+      }
+      const onAbort = () => finish(new Error('CONNECT_ABORTED'))
+      const timer = timeout === null ? null : maybeUnref(setTimeout(() => finish(new Error('CONNECT_TIMEOUT')), timeout))
+      signal?.addEventListener('abort', onAbort, { once: true })
+
+      socket.onopen = () => finish()
+      socket.onerror = event => {
+        const reason = errorFrom(event?.error, 'CONNECTION_ERROR')
+        if (!settled) finish(reason)
+        else this.onerror?.(reason)
+      }
+      socket.onmessage = event => { this.#handleMessage(event).catch(reason => this.onerror?.(reason)) }
+      socket.onclose = event => {
+        if (!settled) finish(new Error('CONNECTION_CLOSED'))
+        if (this.ws === socket) this.ws = null
+        this.#handleClose(event)
+      }
+    }).finally(() => { this.#connectPromise = null })
+    return await this.#connectPromise
+  }
+
+  send (message) {
+    if (this.ws?.readyState !== 1) throw new Error('CONNECTION_CLOSED')
+    this.ws.send(message)
   }
 
-  #rejectPendingCounts (reason) {
-    for (const id of [...this.#pendingCounts.keys()]) {
-      this.#settleCount(id, { reason })
+  subscribe (filters, handlers = {}) {
+    if (!Array.isArray(filters) || !filters.length) throw new ValidationError('SUBSCRIPTION_FILTERS_REQUIRED')
+    const id = `p2r2p-sub:${++this.#serial}`
+    let closed = false
+    const close = () => {
+      if (closed) return
+      closed = true
+      const subscription = this.#subscriptions.get(id)
+      if (!subscription) return
+      this.#subscriptions.delete(id)
+      try { this.send(JSON.stringify(['CLOSE', id])) } catch {}
+      handlers.onclose?.()
+    }
+    this.#subscriptions.set(id, { filters, handlers, close })
+    try { this.send(JSON.stringify(['REQ', id, ...filters])) } catch (error) {
+      this.#subscriptions.delete(id)
+      throw error
     }
+    return { id, close }
+  }
+
+  publish (event) {
+    if (!isValidEvent(event)) return Promise.reject(new Error('INVALID_EVENT'))
+    return this.#sendEventOperation('EVENT', event, this.#publishes, 'PUBLISH_TIMEOUT')
   }
 
-  // Sends a caller-signed AUTH event and waits for the matching NIP-42 OK.
-  // Each auth event is independent, so different pubkeys can share this socket.
   async authenticate (getAuthEvent) {
     if (!this.#challenge) throw new Error('AUTH_CHALLENGE_MISSING')
+    const event = await getAuthEvent({ relay: this.url, challenge: this.#challenge })
+    if (!isValidEvent(event)) throw new ValidationError('INVALID_AUTH_EVENT')
+    return await this.#sendEventOperation('AUTH', event, this.#authentications, 'AUTH_TIMEOUT')
+  }
 
-    const event = await getAuthEvent({
-      relay: this.url,
-      challenge: this.#challenge
-    })
-    if (typeof event?.id !== 'string' || !event.id) throw new Error('AUTH_EVENT_ID_REQUIRED')
-    const existing = this.#pendingAuths.get(event.id)
-    if (existing) return existing.promise
-
-    let resolveAuth
-    let rejectAuth
-    const promise = new Promise((resolve, reject) => {
-      resolveAuth = resolve
-      rejectAuth = reject
-    })
-    const timer = maybeUnref(setTimeout(() => {
-      this.#settleAuth(event.id, { success: false, reason: new Error('AUTH_TIMEOUT') })
-    }, this.publishTimeout))
-    this.#pendingAuths.set(event.id, {
-      resolve: resolveAuth,
-      reject: rejectAuth,
-      timer,
-      promise
-    })
-
-    Promise.resolve(this.send(JSON.stringify(['AUTH', event]))).catch(reason => {
-      this.#settleAuth(event.id, { success: false, reason })
-    })
-    return promise
+  #sendEventOperation (type, event, map, timeoutCode) {
+    if (map.has(event.id)) return map.get(event.id).promise
+    const deferred = Promise.withResolvers()
+    const timer = maybeUnref(setTimeout(() => this.#settleEvent(map, event.id, new Error(timeoutCode)), this.publishTimeout))
+    map.set(event.id, { ...deferred, timer, promise: deferred.promise })
+    try { this.send(JSON.stringify([type, event])) } catch (error) {
+      this.#settleEvent(map, event.id, error)
+    }
+    return deferred.promise
   }
 
-  // nostr-tools@2.23.5 exposes only Relay.count(), which discards the NIP-45
-  // HLL payload. Keep these requests separate so callers can aggregate it.
   countWithHll (filters, { signal } = {}) {
     if (signal?.aborted) return Promise.reject(new Error('COUNT_ABORTED'))
+    const id = `p2r2p-count:${++this.#serial}`
+    const deferred = Promise.withResolvers()
+    const onAbort = () => this.#settleCount(id, null, new Error('COUNT_ABORTED'))
+    this.#counts.set(id, { ...deferred, signal, onAbort })
+    signal?.addEventListener('abort', onAbort, { once: true })
+    try { this.send(JSON.stringify(['COUNT', id, ...filters])) } catch (error) {
+      this.#settleCount(id, null, error)
+    }
+    return deferred.promise
+  }
 
-    const id = `p2r2p-count:${++this.#countSerial}`
-    let resolveCount
-    let rejectCount
-    const promise = new Promise((resolve, reject) => {
-      resolveCount = resolve
-      rejectCount = reject
-    })
-    const onAbort = () => {
-      this.#settleCount(id, { reason: new Error('COUNT_ABORTED') })
+  #settleEvent (map, id, reason, value) {
+    const pending = map.get(id)
+    if (!pending) return
+    map.delete(id)
+    clearTimeout(pending.timer)
+    if (reason) pending.reject(errorFrom(reason, 'OPERATION_REJECTED'))
+    else pending.resolve(value)
+  }
+
+  #settleCount (id, payload, reason) {
+    const pending = this.#counts.get(id)
+    if (!pending) return
+    this.#counts.delete(id)
+    pending.signal?.removeEventListener('abort', pending.onAbort)
+    if (reason) pending.reject(errorFrom(reason, 'COUNT_REJECTED'))
+    else pending.resolve(payload)
+  }
+
+  async #handleMessage (message) {
+    let data
+    try { data = JSON.parse(await messageText(message.data)) } catch (cause) {
+      if (cause instanceof ValidationError) throw cause
+      throw new ValidationError('INVALID_RELAY_MESSAGE', { cause })
     }
-    this.#pendingCounts.set(id, {
-      resolve: resolveCount,
-      reject: rejectCount,
-      signal,
-      onAbort
-    })
-    signal?.addEventListener('abort', onAbort, { once: true })
+    if (!Array.isArray(data) || typeof data[0] !== 'string') throw new ValidationError('INVALID_RELAY_MESSAGE')
 
-    let message
-    try {
-      message = JSON.stringify(['COUNT', id, ...filters])
-    } catch (error) {
-      this.#settleCount(id, { reason: error })
-      return promise
+    if (data[0] === 'EVENT') {
+      const subscription = this.#subscriptions.get(data[1])
+      if (!subscription) return
+      const event = data[2]
+      if (!isValidEvent(event) || !doesEventMatchAnyFilter(subscription.filters, event)) subscription.handlers.oninvalidevent?.(event)
+      else subscription.handlers.onevent?.(event)
+      return
+    }
+    if (data[0] === 'EOSE') {
+      this.#subscriptions.get(data[1])?.handlers.oneose?.()
+      return
+    }
+    if (data[0] === 'CLOSED') {
+      const id = data[1]
+      const subscription = this.#subscriptions.get(id)
+      if (subscription) {
+        this.#subscriptions.delete(id)
+        subscription.handlers.onclose?.(errorFrom(data[2], 'SUBSCRIPTION_CLOSED'))
+      } else this.#settleCount(id, null, errorFrom(data[2], 'COUNT_CLOSED'))
+      return
+    }
+    if (data[0] === 'OK') {
+      const reason = data[2] === true ? null : errorFrom(data[3], 'EVENT_REJECTED')
+      this.#settleEvent(this.#publishes, data[1], reason, data[3])
+      this.#settleEvent(this.#authentications, data[1], reason, data[3])
+      return
     }
-    Promise.resolve(this.send(message)).catch(reason => {
-      this.#settleCount(id, { reason })
-    })
-    return promise
+    if (data[0] === 'AUTH' && typeof data[1] === 'string') {
+      this.#challenge = data[1]
+      this.onauth?.(data[1])
+      return
+    }
+    if (data[0] === 'COUNT') {
+      this.#settleCount(data[1], data[2])
+      return
+    }
+    if (data[0] === 'NOTICE') this.onnotice?.(String(data[1] ?? ''))
   }
 
-  // Relay assigns this method to its WebSocket handler while connecting. Capture
-  // AUTH and raw COUNT replies before Relay's parser discards COUNT HLL payloads.
-  _onmessage (message) {
-    try {
-      const data = JSON.parse(message.data)
-      if (data[0] === 'AUTH' && typeof data[1] === 'string') {
-        this.#challenge = data[1]
-      } else if (data[0] === 'OK' && typeof data[1] === 'string') {
-        this.#settleAuth(data[1], { success: data[2] === true, reason: data[3] })
-      } else if (data[0] === 'COUNT' && typeof data[1] === 'string') {
-        this.#settleCount(data[1], { payload: data[2] })
-      } else if (data[0] === 'CLOSED' && typeof data[1] === 'string') {
-        this.#settleCount(data[1], { reason: data[2] || 'COUNT_CLOSED' })
-      }
-    } catch {
-      // Relay's own parser below reports malformed relay messages.
+  #handleClose (event) {
+    this.#challenge = null
+    const reason = errorFrom(event?.reason, 'CONNECTION_CLOSED')
+    for (const [id, subscription] of this.#subscriptions) {
+      this.#subscriptions.delete(id)
+      subscription.handlers.onclose?.(reason)
     }
-
-    return super._onmessage(message)
+    for (const id of [...this.#publishes.keys()]) this.#settleEvent(this.#publishes, id, reason)
+    for (const id of [...this.#authentications.keys()]) this.#settleEvent(this.#authentications, id, reason)
+    for (const id of [...this.#counts.keys()]) this.#settleCount(id, null, reason)
+    this.onclose?.(reason)
   }
 
-  close () {
+  async close () {
+    const socket = this.ws
+    this.ws = null
     this.#challenge = null
-    this.#rejectPendingAuths(new Error('AUTH_CONNECTION_CLOSED'))
-    this.#rejectPendingCounts(new Error('COUNT_CONNECTION_CLOSED'))
-    return super.close()
+    const reason = new Error('CONNECTION_CLOSED')
+    for (const [id, subscription] of this.#subscriptions) {
+      this.#subscriptions.delete(id)
+      subscription.handlers.onclose?.()
+    }
+    for (const id of [...this.#publishes.keys()]) this.#settleEvent(this.#publishes, id, reason)
+    for (const id of [...this.#authentications.keys()]) this.#settleEvent(this.#authentications, id, reason)
+    for (const id of [...this.#counts.keys()]) this.#settleCount(id, null, reason)
+    if (socket && socket.readyState < 2) socket.close()
   }
 }

package/relay/services/relay-pool.js

@@ -1,7 +1,8 @@
+import { ValidationError } from '../../error/index.js'
 import { decodeHll, encodeHll, estimateHllCount, mergeHll } from '../helpers/hll.js'
 import { createPublishSettlements, firstFulfillment, publishSummary } from '../helpers/publish.js'
 import { maybeUnref } from '../helpers/timer.js'
-import { normalizeURL } from 'nostr-tools/utils'
+import { normalizeRelayUrl } from '../../url/index.js'
 import { RelayConnection } from './relay-connection.js'
 
 const CONNECTION_TIMEOUT_MS = 3000
@@ -82,7 +83,7 @@ function normalizedRelayUrls (relays) {
   const seen = new Set()
 
   for (const relay of relays || []) {
-    const normalizedUrl = normalizeURL(relay)
+    const normalizedUrl = normalizeRelayUrl(relay)
     if (seen.has(normalizedUrl)) continue
     seen.add(normalizedUrl)
     // Keep the caller's first spelling in reports and metadata while using the
@@ -110,6 +111,11 @@ export class RelayPool {
   #relayTimeouts = new Map()
   #liveSubCounts = new Map() // url -> number of active live subscriptions
   #timeout = 30000 // 30 seconds
+  #createRelay
+
+  constructor ({ _createRelay = url => new RelayConnection(url) } = {}) {
+    this.#createRelay = _createRelay
+  }
 
   #scheduleIdleDisconnect (url) {
     clearTimeout(this.#relayTimeouts.get(url))
@@ -119,15 +125,14 @@ export class RelayPool {
   // Opens a normalized pooled connection. Failed connects are evicted so a later
   // retry creates a fresh RelayConnection instead of reusing broken socket state.
   async #getRelay (url) {
-    const normalizedUrl = normalizeURL(url)
+    const normalizedUrl = normalizeRelayUrl(url)
     let relay = this.#relays.get(normalizedUrl)
     if (!relay) {
-      relay = new RelayConnection(normalizedUrl)
+      relay = this.#createRelay(normalizedUrl)
       this.#relays.set(normalizedUrl, relay)
     }
 
     try {
-      // nostr-tools cancels its socket attempt when this deadline elapses.
       await relay.connect({ timeout: CONNECTION_TIMEOUT_MS })
     } catch (error) {
       if (this.#relays.get(normalizedUrl) === relay) {
@@ -147,7 +152,7 @@ export class RelayPool {
   }
 
   #incrementLiveSub (url) {
-    const normalizedUrl = normalizeURL(url)
+    const normalizedUrl = normalizeRelayUrl(url)
     this.#liveSubCounts.set(normalizedUrl, (this.#liveSubCounts.get(normalizedUrl) ?? 0) + 1)
     // Cancel any pending idle timeout — this relay must stay open
     clearTimeout(this.#relayTimeouts.get(normalizedUrl))
@@ -155,7 +160,7 @@ export class RelayPool {
   }
 
   #decrementLiveSub (url) {
-    const normalizedUrl = normalizeURL(url)
+    const normalizedUrl = normalizeRelayUrl(url)
     const next = (this.#liveSubCounts.get(normalizedUrl) ?? 1) - 1
     if (next <= 0) {
       this.#liveSubCounts.delete(normalizedUrl)
@@ -217,7 +222,7 @@ export class RelayPool {
     signal
   } = {}) {
     if (!filter || typeof filter !== 'object' || Array.isArray(filter)) {
-      throw new Error('COUNT_FILTER_REQUIRED')
+      throw new ValidationError('COUNT_FILTER_REQUIRED')
     }
     if (signal?.aborted) throw new Error('Aborted')
 
@@ -414,8 +419,6 @@ export class RelayPool {
           // Actual EOSE and filter satisfaction share the same graceful close path.
           const handleEose = () => {
             if (isResolved || !pending.has(url)) return
-            // nostr-tools reports "closed by caller" through onclose(). This is a
-            // successful local completion, not a relay failure.
             normalCloseUrls.add(url)
             sub.close()
             if (hasEvents && timeoutAfterFirstEose !== null && !eoseTimer && !isResolved) {

package/temporary-storage/index.js

@@ -1,3 +1,5 @@
+import { ValidationError } from '../error/index.js'
+
 export const TEMPORARY_STORAGE_KEYS_KEY = 'libp2r2p:temporary-storage:keys'
 
 function normalizeKeys (keys) {
@@ -54,7 +56,7 @@ export function createTemporaryStorage ({ storageArea = globalThis.sessionStorag
   }
 
   function setItem (key, value) {
-    if (typeof key !== 'string' || !key || key === TEMPORARY_STORAGE_KEYS_KEY) throw new Error('INVALID_TEMPORARY_STORAGE_KEY')
+    if (typeof key !== 'string' || !key || key === TEMPORARY_STORAGE_KEYS_KEY) throw new ValidationError('INVALID_TEMPORARY_STORAGE_KEY')
     trackTemporaryKey(key)
     storage().setItem(key, value)
   }

package/url/index.js

@@ -0,0 +1,131 @@
+import { ValidationError } from '../error/index.js'
+
+function isIpv4Address (hostname) {
+  const parts = hostname.split('.')
+  return parts.length === 4 && parts.every(part =>
+    /^(?:0|[1-9][0-9]{0,2})$/.test(part) && Number(part) <= 255
+  )
+}
+
+function isPublicIpv4Address (hostname) {
+  const [a, b, c] = hostname.split('.').map(Number)
+  if (a === 0 || a === 10 || a === 127 || a >= 224) return false
+  if (a === 100 && b >= 64 && b <= 127) return false
+  if (a === 169 && b === 254) return false
+  if (a === 172 && b >= 16 && b <= 31) return false
+  if (a === 192 && b === 168) return false
+  if (a === 192 && b === 0 && (c === 0 || c === 2)) return false
+  if (a === 192 && b === 88 && c === 99) return false
+  if (a === 198 && (b === 18 || b === 19 || (b === 51 && c === 100))) return false
+  if (a === 203 && b === 0 && c === 113) return false
+  return true
+}
+
+function parseIpv6Words (hostname) {
+  const value = hostname.replace(/^\[|\]$/g, '').toLowerCase()
+  if (!/^[0-9a-f:]+$/.test(value) || value.split('::').length > 2) return null
+  const [left = '', right = ''] = value.split('::')
+  const leftWords = left ? left.split(':') : []
+  const rightWords = right ? right.split(':') : []
+  const missing = 8 - leftWords.length - rightWords.length
+  if ((value.includes('::') && missing < 1) || (!value.includes('::') && missing !== 0)) return null
+  const words = [...leftWords, ...Array(missing).fill('0'), ...rightWords]
+  if (words.length !== 8 || words.some(word => !/^[0-9a-f]{1,4}$/.test(word))) return null
+  return words.map(word => Number.parseInt(word, 16))
+}
+
+function isPublicIpv6Address (hostname) {
+  const words = parseIpv6Words(hostname)
+  if (!words) return false
+  const first = words[0]
+  if (first === 0) return false
+  if ((first & 0xfe00) === 0xfc00) return false
+  if ((first & 0xffc0) === 0xfe80) return false
+  if ((first & 0xff00) === 0xff00) return false
+  if (first === 0x2001 && words[1] === 0x0db8) return false
+  return true
+}
+
+function removeEmptyQuerySegments (url) {
+  const entries = [...url.searchParams]
+  url.search = ''
+  for (const [key, value] of entries) url.searchParams.append(key, value)
+  url.searchParams.sort()
+}
+
+export function normalizeRelayUrl (value) {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new ValidationError('INVALID_RELAY_URL', { message: 'URL_SHOULD_BE_A_STRING' })
+  }
+  let input = value.trim()
+  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(input)) input = `wss://${input}`
+  let url
+  try {
+    url = new URL(input)
+  } catch (cause) {
+    throw new ValidationError('INVALID_RELAY_URL', { cause })
+  }
+  if (url.protocol === 'http:') url.protocol = 'ws:'
+  else if (url.protocol === 'https:') url.protocol = 'wss:'
+  if (url.protocol !== 'ws:' && url.protocol !== 'wss:') throw new ValidationError('INVALID_RELAY_PROTOCOL')
+  url.pathname = url.pathname.replace(/\/{2,}/g, '/').replace(/\/+$/, '')
+  if (url.pathname === '/') url.pathname = ''
+  if ((url.protocol === 'ws:' && url.port === '80') || (url.protocol === 'wss:' && url.port === '443')) url.port = ''
+  removeEmptyQuerySegments(url)
+  url.hash = ''
+  return url.toString().replace(/^(wss?:\/\/[^/?#]+)\/(?=[?#]|$)/, '$1')
+}
+
+function publicRelayUrlError (value) {
+  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}`
+  try {
+    if (decodeURIComponent(new URL(input).pathname).includes('://')) return 'RELAY_URL_NESTED_SCHEME'
+  } catch {
+    return 'INVALID_RELAY_URL'
+  }
+
+  let normalized
+  try {
+    normalized = normalizeRelayUrl(value)
+  } catch (error) {
+    return error instanceof ValidationError ? error.code : 'INVALID_RELAY_URL'
+  }
+
+  const url = new URL(normalized)
+  if (url.protocol !== 'wss:') 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'
+  }
+
+  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 assertValidPublicRelayUrl (value) {
+  const code = publicRelayUrlError(value)
+  if (code) throw new ValidationError(code)
+  return value
+}

package/web-storage-queue/index.js

@@ -1,3 +1,5 @@
+import { ValidationError } from '../error/index.js'
+
 const encoder = new TextEncoder()
 const DEFAULT_EVICTION_HEADROOM_RATIO = 0.1
 const MAX_EVICTION_HEADROOM_BYTES = 64 * 1024 // 64 KiB
@@ -8,7 +10,7 @@ export function createQueue ({
   maxBytes,
   evictionPolicy = 'opposite-end' // 'opposite-end' = push evicts from head, unshift evicts from tail
 } = {}) {
-  if (!prefix) throw new Error('QUEUE_PREFIX_REQUIRED')
+  if (!prefix) throw new ValidationError('QUEUE_PREFIX_REQUIRED')
   const stateKey = `${prefix}:queue`
   const operationKey = `${prefix}:queue:operation`
   const itemPrefix = `${prefix}:queue:item:`
@@ -44,7 +46,7 @@ export function createQueue ({
     if (policy === 'opposite-end' || policy === undefined || policy === null) return 'opposite-end'
     if (policy === 'fifo' || policy === 'head') return 'head'
     if (policy === 'lifo' || policy === 'tail') return 'tail'
-    throw new Error('QUEUE_INVALID_EVICTION_POLICY')
+    throw new ValidationError('QUEUE_INVALID_EVICTION_POLICY')
   }
 
   function evictionDirectionFor (operation, { index = 0, length = 0 } = {}) {
@@ -251,7 +253,7 @@ export function createQueue ({
 
   function assertIndex (index, length, { allowEnd = false } = {}) {
     const max = allowEnd ? length : length - 1
-    if (!Number.isSafeInteger(index) || index < 0 || index > max) throw new Error('QUEUE_INDEX_OUT_OF_RANGE')
+    if (!Number.isSafeInteger(index) || index < 0 || index > max) throw new ValidationError('QUEUE_INDEX_OUT_OF_RANGE')
   }
 
   function itemForStorage (item) {
@@ -514,7 +516,7 @@ export function createQueue ({
   }
 
   function insertWhere (predicate, item, { appendIfMissing = false } = {}) {
-    if (typeof predicate !== 'function') throw new Error('QUEUE_PREDICATE_REQUIRED')
+    if (typeof predicate !== 'function') throw new ValidationError('QUEUE_PREDICATE_REQUIRED')
     const state = readState()
     const length = lengthFromState(state)
 
@@ -591,7 +593,7 @@ export function createQueue ({
   }
 
   function removeWhere (predicate) {
-    if (typeof predicate !== 'function') throw new Error('QUEUE_PREDICATE_REQUIRED')
+    if (typeof predicate !== 'function') throw new ValidationError('QUEUE_PREDICATE_REQUIRED')
     const state = readState()
     // Bulk predicate removal leaves holes on purpose; shift/pop skip them, and
     // callers that need contiguous positions can use removeAt for compaction.
@@ -613,7 +615,7 @@ export function createQueue ({
   }
 
   function some (predicate) {
-    if (typeof predicate !== 'function') throw new Error('QUEUE_PREDICATE_REQUIRED')
+    if (typeof predicate !== 'function') throw new ValidationError('QUEUE_PREDICATE_REQUIRED')
     const state = readState()
     for (let id = state.head; id < state.tail; id++) {
       const item = readItem(id)