libp2r2p 0.10.9 → 0.10.11

package/README.md

@@ -8,6 +8,10 @@ the transport and discovery surface. The package was born to distribute the
 private messenger reference implementation, and it also carries a few Nostr
 power-ups used by that messenger.
 
+For remote-work scheduling, see [`libp2r2p/network`](network/README.md):
+`isOnline` probes connectivity and `onOnline` shares recovery monitoring,
+including retries when the browser omits its native `online` event.
+
 ## Private Messenger
 
 The main API is `createPrivateMessenger` from `libp2r2p/private-messenger`.
@@ -342,13 +346,17 @@ are handled by `libp2r2p/nip27`: `decodeUserReference()` returns the decoded
 form with its canonical compact spelling, `encodeUserReference()` returns
 that canonical spelling, and `resolveUserReference()` resolves it to a
 pubkey. `libp2r2p/nip05` keeps only `queryProfile()`, the NIP-05 lookup, which
-accepts the compact custom forms directly.
+accepts the compact custom forms directly. The decoders (`decodeReference`,
+`decodeMediaMetadata`, `decodeUserReference`, `decodeAppUrl`) throw
+`ValidationError` with a stable code; each has a `tryDecode…` counterpart
+that returns `null` when the value cannot be decoded.
 
 Public validity checks consistently use a non-throwing `is…` predicate plus an
 `assert…` counterpart when callers need the exact reason. Strict codecs,
 decoders, token validation, and malformed public arguments also throw
-`ValidationError` from `libp2r2p/error`. Network, timeout, abort, quota, and
-closed-state failures remain ordinary operational errors.
+`ValidationError` from `libp2r2p/error`; probing code can use the
+non-throwing `tryDecode…` variants instead of catching. Network, timeout,
+abort, quota, and closed-state failures remain ordinary operational errors.
 
 NIP-04 remains available at
 `libp2r2p/nip04` only for compatibility with older Nostr applications.

package/network/README.md

@@ -0,0 +1,20 @@
+# Connectivity
+
+`isOnline({ signal } = {})` returns a boolean after probing public connectivity
+endpoints, or immediately returns `false` when the browser reports offline.
+Concurrent calls without a signal share one check. A supplied abort signal
+cancels the caller's independent check. Each endpoint has a five-second timeout.
+
+`onOnline(handler)` returns an idempotent unsubscribe function. It notifies
+asynchronously after confirmed initial connectivity and each detected recovery.
+The native `online` event only triggers a check; it is not sufficient evidence.
+Listeners share a monitor with retries at 5, 15, 30, then 60 seconds (20% jitter),
+checks on focus/visibility/network changes, and a 60-second interval while online.
+Unsubscribing the last listener removes timers/listeners and aborts its probe.
+Handler failures are isolated and logged. `createConnectivityMonitor(options)`
+creates an independent monitor with an optional custom `check({ signal })`.
+
+Successful probes do not guarantee a particular relay or HTTP server is reachable.
+Handle request failures, cancellations, and timeouts separately. Browsers can
+suspend background tabs, so recovery notification has no wall-clock guarantee.
+Consumers should keep their own work queues but should not duplicate probe loops.

package/network/index.js

@@ -1,25 +1,31 @@
-export async function isOnline () {
-  if (typeof navigator !== 'undefined' && typeof navigator.onLine === 'boolean') {
-    if (!navigator.onLine) return false
-  }
-  return hasInternetConnectivity()
-}
+import { ValidationError } from '../error/index.js'
 
+const RETRY_DELAYS = [5000, 15000, 30000, 60000]
 const CONNECTIVITY_PROBE_URLS = [
   { url: 'https://www.gstatic.com/generate_204' },
   { url: 'https://connectivitycheck.gstatic.com/generate_204' },
   { url: 'https://captive.apple.com/hotspot-detect.html' },
   { method: 'GET', url: 'https://connectivity-check.ubuntu.com' }
 ]
+let sharedCheck
+
+// Treat the browser's offline flag as a fast failure; confirm online status with a probe.
+export async function isOnline ({ signal } = {}) {
+  if (signal?.aborted) throw signal.reason
+  if (globalThis.navigator?.onLine === false) return false
+  if (signal) return hasInternetConnectivity(signal)
+  sharedCheck ??= hasInternetConnectivity().finally(() => { sharedCheck = null })
+  return sharedCheck
+}
 
-async function hasInternetConnectivity () {
-  const candidates = shuffle(CONNECTIVITY_PROBE_URLS)
-  for (const candidate of candidates) {
+async function hasInternetConnectivity (signal) {
+  for (const candidate of shuffle(CONNECTIVITY_PROBE_URLS)) {
+    if (signal?.aborted) throw signal.reason
     try {
-      await ping(candidate.url, { method: candidate.method })
+      await ping(candidate.url, { method: candidate.method, signal })
       return true
-    } catch (err) {
-      console.warn('connectivity probe failed', candidate.url, err?.message ?? err)
+    } catch {
+      if (signal?.aborted) throw signal.reason
     }
   }
   return false
@@ -34,35 +40,143 @@ function shuffle (list) {
   return copy
 }
 
-async function ping (url, { method = 'HEAD', timeout = 5000 } = {}) {
-  const abortController = typeof AbortController === 'function' ? new AbortController() : null
-  let timerId = null
-
-  const fetchPromise = fetch(url, {
-    method,
-    mode: 'no-cors',
-    cache: 'no-store',
-    redirect: 'follow',
-    signal: abortController?.signal
-  })
-
-  const completionPromise = fetchPromise.finally(() => {
-    if (timerId != null) clearTimeout(timerId)
-  })
-
-  const timeoutPromise = new Promise((_resolve, reject) => {
-    timerId = setTimeout(() => {
-      if (abortController) abortController.abort()
+// Bound each probe and release its timer and abort listener on every exit path.
+async function ping (url, { method = 'HEAD', timeout = 5000, signal } = {}) {
+  const controller = new AbortController()
+  let timer
+  let onAbort
+  const stopped = new Promise((_resolve, reject) => {
+    onAbort = () => {
+      controller.abort(signal.reason)
+      reject(signal.reason)
+    }
+    signal?.addEventListener('abort', onAbort, { once: true })
+    timer = setTimeout(() => {
+      controller.abort()
       reject(new Error('PING_TIMEOUT'))
     }, timeout)
+    if (signal?.aborted) onAbort()
   })
+  try {
+    await Promise.race([
+      fetch(url, { method, mode: 'no-cors', cache: 'no-store', redirect: 'follow', signal: controller.signal }),
+      stopped
+    ])
+  } finally {
+    clearTimeout(timer)
+    signal?.removeEventListener('abort', onAbort)
+  }
+}
 
-  await Promise.race([completionPromise, timeoutPromise])
-  return true
+// A monitor owns one probe loop, regardless of how many consumers subscribe.
+export function createConnectivityMonitor ({
+  check = isOnline,
+  eventTarget = globalThis.window,
+  document = globalThis.document,
+  _setTimeout = globalThis.setTimeout,
+  _clearTimeout = globalThis.clearTimeout,
+  _random = Math.random,
+  reportError = error => console.error('Online listener failed', error)
+} = {}) {
+  if (typeof check !== 'function') throw new ValidationError('INVALID_CONNECTIVITY_CHECK')
+  const listeners = new Set()
+  const setTimer = (...args) => Reflect.apply(_setTimeout, globalThis, args)
+  const clearTimer = (...args) => Reflect.apply(_clearTimeout, globalThis, args)
+  let session
+
+  function deliver (entry, current) {
+    if (entry.delivered || !listeners.has(entry) || session !== current) return
+    entry.delivered = true
+    try { Promise.resolve(entry.handler()).catch(reportError) } catch (error) { reportError(error) }
+  }
+
+  function schedule (current) {
+    if (session !== current || !listeners.size) return
+    const delay = current.online ? 60000 : RETRY_DELAYS[Math.min(current.retry++, RETRY_DELAYS.length - 1)]
+    current.timer = setTimer(() => {
+      current.timer = null
+      return probe(current)
+    }, Math.round(delay * (0.8 + _random() * 0.4)))
+    current.timer?.unref?.()
+  }
+
+  async function probe (current) {
+    if (session !== current || current.pending) return
+    if (current.timer != null) clearTimer(current.timer)
+    current.timer = null
+    current.pending = true
+    try {
+      const online = await check({ signal: current.controller.signal })
+      if (session !== current) return
+      current.online = online === true && globalThis.navigator?.onLine !== false
+      if (current.online) {
+        current.retry = 0
+        for (const entry of [...listeners]) deliver(entry, current)
+      } else {
+        for (const entry of listeners) entry.delivered = false
+      }
+    } catch {
+      if (session !== current) return
+      current.online = false
+      for (const entry of listeners) entry.delivered = false
+    } finally {
+      current.pending = false
+      schedule(current)
+    }
+  }
+
+  function start () {
+    const current = { online: false, retry: 0, timer: null, pending: false, controller: new AbortController() }
+    session = current
+    current.wake = () => { probe(current) }
+    current.connectionChanged = () => {
+      current.online = false
+      current.retry = 0
+      for (const entry of listeners) entry.delivered = false
+      current.wake()
+    }
+    current.visible = () => { if (document?.visibilityState !== 'hidden') current.wake() }
+    eventTarget?.addEventListener('online', current.connectionChanged)
+    eventTarget?.addEventListener('offline', current.connectionChanged)
+    eventTarget?.addEventListener('focus', current.wake)
+    document?.addEventListener('visibilitychange', current.visible)
+    queueMicrotask(current.wake)
+  }
+
+  function stop () {
+    const current = session
+    session = null
+    if (current.timer != null) clearTimer(current.timer)
+    current.controller.abort()
+    eventTarget?.removeEventListener('online', current.connectionChanged)
+    eventTarget?.removeEventListener('offline', current.connectionChanged)
+    eventTarget?.removeEventListener('focus', current.wake)
+    document?.removeEventListener('visibilitychange', current.visible)
+  }
+
+  // Notify once on confirmed initial connectivity, then after each detected reconnection.
+  function onOnline (handler) {
+    if (typeof handler !== 'function') throw new ValidationError('INVALID_ONLINE_HANDLER')
+    const entry = { handler, delivered: false }
+    listeners.add(entry)
+    if (!session) start()
+    else {
+      const current = session
+      queueMicrotask(() => { probe(current) })
+    }
+    return () => {
+      if (!listeners.delete(entry)) return
+      if (!listeners.size) stop()
+    }
+  }
+
+  return { onOnline }
 }
 
+let defaultMonitor
+
+// Share probes, capped backoff and wake-up listeners across callers in this realm.
 export function onOnline (handler) {
-  const listener = () => handler()
-  window.addEventListener('online', listener)
-  return () => window.removeEventListener('online', listener)
+  defaultMonitor ??= createConnectivityMonitor()
+  return defaultMonitor.onOnline(handler)
 }

package/nip05/helpers/nip05-identifier.js

@@ -1,3 +1,5 @@
+import { ValidationError } from '../../error/index.js'
+
 const NIP05_LOCAL = /^[a-z0-9._-]+$/
 const NIP05_DOMAIN = /^[a-z0-9.-]+$/
 
@@ -26,23 +28,36 @@ export function nip05FromLocalDomain (local, domain) {
 // - `local@domain` (standard NIP-05)
 // - `domain` with exactly one dot -> root `_@domain`
 // - `local.domain...` with more than one dot -> local part + domain (custom extension)
+// Throws `ValidationError('INVALID_NIP05_IDENTIFIER')` for malformed input.
 export function decodeNip05Identifier (value) {
-  if (typeof value !== 'string') return null
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new ValidationError('INVALID_NIP05_IDENTIFIER', { message: 'IDENTIFIER_SHOULD_BE_A_NON_EMPTY_STRING' })
+  }
   const text = value.trim().toLowerCase()
-  if (!text) return null
 
   const at = text.lastIndexOf('@')
   if (at !== -1) {
-    if (at === 0 || at === text.length - 1 || text.includes('@', at + 1)) return null
-    return nip05FromLocalDomain(text.slice(0, at), text.slice(at + 1))
+    if (at === 0 || at === text.length - 1 || text.includes('@', at + 1)) {
+      throw new ValidationError('INVALID_NIP05_IDENTIFIER', { message: 'INVALID_NIP05_FORMAT' })
+    }
+    const result = nip05FromLocalDomain(text.slice(0, at), text.slice(at + 1))
+    if (!result) {
+      throw new ValidationError('INVALID_NIP05_IDENTIFIER', { message: 'INVALID_NIP05_LOCAL_OR_DOMAIN' })
+    }
+    return result
   }
 
-  if (!text.includes('.')) return null
+  if (!text.includes('.')) {
+    throw new ValidationError('INVALID_NIP05_IDENTIFIER', { message: 'INVALID_NIP05_FORMAT' })
+  }
   const firstDot = text.indexOf('.')
-  if (text.slice(firstDot + 1).includes('.')) {
-    return nip05FromLocalDomain(text.slice(0, firstDot), text.slice(firstDot + 1))
+  const result = text.slice(firstDot + 1).includes('.')
+    ? nip05FromLocalDomain(text.slice(0, firstDot), text.slice(firstDot + 1))
+    : nip05FromLocalDomain('_', text)
+  if (!result) {
+    throw new ValidationError('INVALID_NIP05_IDENTIFIER', { message: 'INVALID_NIP05_LOCAL_OR_DOMAIN' })
   }
-  return nip05FromLocalDomain('_', text)
+  return result
 }
 
 // Returns the most compact unambiguous NIP-05 spelling:

package/nip05/index.js

@@ -1,3 +1,4 @@
+import { ValidationError } from '../error/index.js'
 import { normalizeRelayUrl } from '../url/index.js'
 import { decodeNip05Identifier } from './helpers/nip05-identifier.js'
 
@@ -8,9 +9,11 @@ export async function queryProfile (identifier, {
   signal,
   timeoutMs = 5000
 } = {}) {
-  if (typeof identifier !== 'string' || typeof fetchImpl !== 'function') return null
+  if (typeof identifier !== 'string' || !identifier.trim()) {
+    throw new ValidationError('INVALID_NIP05_IDENTIFIER', { message: 'IDENTIFIER_SHOULD_BE_A_NON_EMPTY_STRING' })
+  }
+  if (typeof fetchImpl !== 'function') return null
   const nip05 = decodeNip05Identifier(identifier)
-  if (!nip05) return null
   const name = nip05.local
   const domain = nip05.domain
 

package/nip27/helpers/user-reference.js

@@ -26,11 +26,17 @@ function stripReferencePrefix (value) {
 // Decodes a user reference without performing any network lookup.
 // Returns `{ type: 'pubkey', pubkey, relays, raw }` for npub/nprofile/hex or
 // `{ type: 'nip05', local, domain, raw }` for NIP-05 (standard or extended),
-// where `raw` is always the most compact canonical spelling.
+// where `raw` is always the most compact canonical spelling. Throws
+// `ValidationError('INVALID_USER_REFERENCE')` when the value cannot be
+// decoded; use `tryDecodeUserReference` when a null result is preferred.
 export function decodeUserReference (value) {
-  if (typeof value !== 'string') return null
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new ValidationError('INVALID_USER_REFERENCE', { message: 'USER_REFERENCE_SHOULD_BE_A_NON_EMPTY_STRING' })
+  }
   const text = stripReferencePrefix(value)
-  if (!text) return null
+  if (!text) {
+    throw new ValidationError('INVALID_USER_REFERENCE', { message: 'EMPTY_USER_REFERENCE' })
+  }
 
   if (HEX_PUBKEY.test(text)) {
     const raw = text.toLowerCase()
@@ -41,8 +47,8 @@ export function decodeUserReference (value) {
     try {
       const raw = text.toLowerCase()
       return { type: 'pubkey', pubkey: npubDecode(raw), relays: [], raw }
-    } catch {
-      return null
+    } catch (cause) {
+      throw new ValidationError('INVALID_USER_REFERENCE', { message: 'INVALID_NPUB', cause })
     }
   }
 
@@ -51,17 +57,32 @@ export function decodeUserReference (value) {
       const raw = text.toLowerCase()
       const { pubkey, relays } = nprofileDecode(raw)
       return { type: 'pubkey', pubkey, relays, raw }
-    } catch {
-      return null
+    } catch (cause) {
+      throw new ValidationError('INVALID_USER_REFERENCE', { message: 'INVALID_NPROFILE', cause })
     }
   }
 
-  const nip05 = decodeNip05Identifier(text)
-  if (!nip05) return null
+  let nip05
+  try {
+    nip05 = decodeNip05Identifier(text)
+  } catch (cause) {
+    throw new ValidationError('INVALID_USER_REFERENCE', { message: 'INVALID_NIP05', cause })
+  }
   const raw = compactNip05Raw(nip05.local, nip05.domain)
   return { type: 'nip05', ...nip05, raw }
 }
 
+// Non-throwing variant of `decodeUserReference`: returns the decoded
+// reference or `null` when the value is not a valid user reference.
+export function tryDecodeUserReference (value) {
+  try {
+    return decodeUserReference(value)
+  } catch (error) {
+    if (error instanceof ValidationError) return null
+    throw error
+  }
+}
+
 // Returns the canonical compact spelling for a user reference, either as a
 // string or as a decoded reference object.
 export function encodeUserReference (value) {

package/nip27/index.js

@@ -1,3 +1,4 @@
+import { ValidationError } from '../error/index.js'
 import {
   naddrDecode,
   neventDecode,
@@ -8,10 +9,11 @@ import { queryProfile } from '../nip05/index.js'
 import { normalizeRelayUrl } from '../url/index.js'
 import {
   decodeUserReference,
-  encodeUserReference
+  encodeUserReference,
+  tryDecodeUserReference
 } from './helpers/user-reference.js'
 
-export { decodeUserReference, encodeUserReference }
+export { decodeUserReference, encodeUserReference, tryDecodeUserReference }
 
 const BECH32_BODY = '[ac-hj-np-z02-9]'
 const BOUNDARY_PREFIX = /(?<=^|[\s"«„「¡¿:{([])/.source
@@ -107,18 +109,30 @@ function normalizeRelays (relays) {
     .filter(Boolean)
 }
 
+function looksLikeUserReference (text) {
+  return /^[0-9a-f]{64}$/i.test(text) ||
+    /^(?:npub1|nprofile1)/i.test(text) ||
+    text.includes('@') ||
+    /^[a-z0-9._-]+(?:\.[a-z0-9-]+)+$/i.test(text)
+}
+
 // Parses a single NIP-27-style reference (with optional `@`/`nostr:`
 // prefixes): NIP-05 (including the custom compact forms), npub/nprofile/hex
-// accounts, note/nevent/naddr events and nrelay relays.
+// accounts, note/nevent/naddr events and nrelay relays. Throws
+// `ValidationError` when the value cannot be decoded; use
+// `tryDecodeReference` when a null result is preferred.
 export function decodeReference (value) {
-  if (typeof value !== 'string') return null
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new ValidationError('INVALID_REFERENCE', { message: 'REFERENCE_SHOULD_BE_A_NON_EMPTY_STRING' })
+  }
   const original = value.trim()
-  if (!original) return null
   const text = stripReferencePrefix(original)
-  if (!text) return null
+  if (!text) {
+    throw new ValidationError('INVALID_REFERENCE', { message: 'EMPTY_REFERENCE' })
+  }
 
-  const account = decodeUserReference(text)
-  if (account) {
+  if (looksLikeUserReference(text)) {
+    const account = decodeUserReference(text)
     return account.type === 'pubkey'
       ? {
           type: 'pubkey',
@@ -137,34 +151,29 @@ export function decodeReference (value) {
   }
 
   if (text.startsWith('note1')) {
-    try {
-      return { type: 'note', original, value: text, id: noteDecode(text) }
-    } catch {
-      return null
-    }
+    return { type: 'note', original, value: text, id: noteDecode(text) }
   }
   if (text.startsWith('nevent1')) {
-    try {
-      return { type: 'nevent', original, value: text, ...neventDecode(text) }
-    } catch {
-      return null
-    }
+    return { type: 'nevent', original, value: text, ...neventDecode(text) }
   }
   if (text.startsWith('naddr1')) {
-    try {
-      return { type: 'naddr', original, value: text, ...naddrDecode(text) }
-    } catch {
-      return null
-    }
+    return { type: 'naddr', original, value: text, ...naddrDecode(text) }
   }
   if (text.startsWith('nrelay1')) {
-    try {
-      return { type: 'nrelay', original, value: text, relay: nrelayDecode(text) }
-    } catch {
-      return null
-    }
+    return { type: 'nrelay', original, value: text, relay: nrelayDecode(text) }
+  }
+  throw new ValidationError('INVALID_REFERENCE', { message: 'UNRECOGNIZED_REFERENCE' })
+}
+
+// Non-throwing variant of `decodeReference`: returns the decoded reference
+// or `null` when the value is not a valid reference.
+export function tryDecodeReference (value) {
+  try {
+    return decodeReference(value)
+  } catch (error) {
+    if (error instanceof ValidationError) return null
+    throw error
   }
-  return null
 }
 
 const NIP94_TAGS = {
@@ -185,11 +194,33 @@ const NIP94_TAGS = {
   caption: ['caption']
 }
 
+function validateTagConfigs (extraTags) {
+  if (!extraTags || typeof extraTags !== 'object' || Array.isArray(extraTags)) {
+    throw new ValidationError('INVALID_MEDIA_METADATA_TAGS', { message: 'EXTRA_TAGS_SHOULD_BE_AN_OBJECT' })
+  }
+  for (const [key, config] of Object.entries(extraTags)) {
+    const valid = Array.isArray(config) && config.length > 0 && config.every(entry =>
+      typeof entry === 'string' ||
+      (entry && typeof entry === 'object' && typeof entry.key === 'string' &&
+        (entry.type === undefined || entry.type === 'string' || entry.type === 'array'))
+    )
+    if (!valid) {
+      throw new ValidationError('INVALID_MEDIA_METADATA_TAGS', { message: `INVALID_TAG_CONFIG:${key}` })
+    }
+  }
+}
+
 // Decodes the file/media metadata carried in a URL fragment
 // (`#m=image/png&dim=640x480&alt=...`). Kept generic on purpose: the old
-// draft number (54) was taken by an unrelated NIP.
+// draft number (54) was taken by an unrelated NIP. Throws
+// `ValidationError` for invalid URLs, tag configs or malformed `dim` values;
+// use `tryDecodeMediaMetadata` when a null result is preferred. A URL
+// without a metadata fragment still decodes to `{}`.
 export function decodeMediaMetadata (url, { extraTags } = {}) {
-  if (typeof url !== 'string' || !url) return {}
+  if (typeof url !== 'string' || !url.trim()) {
+    throw new ValidationError('INVALID_MEDIA_METADATA_URL', { message: 'URL_SHOULD_BE_A_NON_EMPTY_STRING' })
+  }
+  if (extraTags !== undefined) validateTagConfigs(extraTags)
 
   const tags = extraTags ? { ...NIP94_TAGS, ...extraTags } : NIP94_TAGS
   const tagIndexes = {}
@@ -217,12 +248,26 @@ export function decodeMediaMetadata (url, { extraTags } = {}) {
     const { width, height } = obj.dim.match(
       /(?<width>[1-9]{1}[0-9]{0,10})(?:\s*[xX]\s*)(?<height>[1-9]{1}[0-9]{0,10})/
     )?.groups ?? {}
-    if (width !== undefined) obj.width = width
-    if (height !== undefined) obj.height = height
+    if (width === undefined || height === undefined) {
+      throw new ValidationError('INVALID_MEDIA_METADATA_DIM', { message: 'DIM_SHOULD_BE_WIDTHxHEIGHT' })
+    }
+    obj.width = width
+    obj.height = height
   }
   return obj
 }
 
+// Non-throwing variant of `decodeMediaMetadata`: returns the decoded
+// metadata or `null` when the URL/tags/dim cannot be decoded.
+export function tryDecodeMediaMetadata (url, options) {
+  try {
+    return decodeMediaMetadata(url, options)
+  } catch (error) {
+    if (error instanceof ValidationError) return null
+    throw error
+  }
+}
+
 function decodeFragmentValue (value) {
   try {
     return decodeURIComponent(value.replace(/\+/g, '%20'))
@@ -234,7 +279,13 @@ function decodeFragmentValue (value) {
 function getReferenceItem (original, groups, { getMimeType }) {
   if (groups.url) {
     const url = `${groups.protocol ? '' : 'https://'}${groups.url}`
-    const urlItem = { value: url, ...(groups.ext && { ext: groups.ext }), ...decodeMediaMetadata(url) }
+    let mediaMetadata = {}
+    try {
+      mediaMetadata = decodeMediaMetadata(url)
+    } catch (error) {
+      if (!(error instanceof ValidationError)) throw error
+    }
+    const urlItem = { value: url, ...(groups.ext && { ext: groups.ext }), ...mediaMetadata }
     if (!urlItem.m && typeof getMimeType === 'function') {
       const mime = getMimeType({ url, ext: groups.ext })
       if (mime) urlItem.m = mime
@@ -249,7 +300,7 @@ function getReferenceItem (original, groups, { getMimeType }) {
     groups.nip05BareRoot ||
     groups.nip05BareCustom
   ) {
-    const account = decodeUserReference(original)
+    const account = tryDecodeUserReference(original)
     if (!account) return null
     return {
       key: 'nip05',
@@ -266,7 +317,13 @@ function getReferenceItem (original, groups, { getMimeType }) {
     return { key: 'hashtag', hashtag: { value: groups.hashtag } }
   }
 
-  const ref = decodeReference(original)
+  let ref
+  try {
+    ref = decodeReference(original)
+  } catch (error) {
+    if (!(error instanceof ValidationError)) throw error
+    return null
+  }
   if (!ref) return null
   switch (ref.type) {
     case 'pubkey': {
@@ -320,7 +377,9 @@ function getReferenceItem (original, groups, { getMimeType }) {
 // `{ bareNip05: true }` is passed, since they are otherwise indistinguishable
 // from plain hostnames; prefixed forms (`@bob.example.com`) always work.
 export function extractMedia (content, { bareNip05 = false, getMimeType } = {}) {
-  if (typeof content !== 'string') return []
+  if (typeof content !== 'string') {
+    throw new ValidationError('INVALID_MEDIA_CONTENT', { message: 'CONTENT_SHOULD_BE_A_STRING' })
+  }
   const regex = getReferencesRegex(bareNip05)
   const items = []
   let end = 0
@@ -349,7 +408,6 @@ export function extractMedia (content, { bareNip05 = false, getMimeType } = {})
 // spellings); npub/nprofile/hex are resolved locally.
 export async function resolveUserReference (value, options = {}) {
   const account = decodeUserReference(value)
-  if (!account) return null
   if (account.type === 'pubkey') {
     return { pubkey: account.pubkey, relays: account.relays, label: account.raw }
   }

package/package.json

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

package/relay/services/events.js

@@ -1,3 +1,4 @@
+import { ValidationError } from '../../error/index.js'
 import { freeRelays } from '../constants/index.js'
 import { pickRelaysForPubkeys } from '../helpers/routing.js'
 import { relayPool } from './relay-pool.js'
@@ -99,7 +100,9 @@ export async function getLatestEventsByPubkey (pubkeys, {
 } = {}) {
   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')
+  if (!Array.isArray(kinds) || kinds.length === 0) {
+    throw new ValidationError('MISSING_EVENT_KINDS', { message: 'Missing kinds' })
+  }
   const type = relayType === 'read' ? 'read' : 'write'
 
   const relaysByAuthor = { ...(relaysByPubkey || {}) }

package/url/app-url.js

@@ -5,7 +5,8 @@ import {
 } from '../nip05/helpers/nip05-identifier.js'
 import {
   decodeUserReference,
-  encodeUserReference
+  encodeUserReference,
+  tryDecodeUserReference
 } from '../nip27/helpers/user-reference.js'
 import {
   NAPP_ENTITY_REGEX,
@@ -55,8 +56,10 @@ function isValidAppName (appName) {
 // `naddr` already carries the event kind, so it does not need the `+`/`++`/
 // `+++` channel prefix (a leading prefix is still tolerated). Only site
 // manifests are app URLs; the result is canonicalized to the `appEncode`
-// entity so downstream code keeps working unchanged.
-function tryDecodeNaddr (value) {
+// entity so downstream code keeps working unchanged. Throws
+// `ValidationError('INVALID_APP_URL_NADDR')` for malformed naddr or
+// naddr that is not a site manifest.
+function decodeNaddrSegment (value) {
   if (typeof value !== 'string' || !value) return null
   const body = value.replace(/^\+{1,3}/, '')
   if (!body.startsWith(NADDR_PREFIX)) return null
@@ -64,10 +67,12 @@ function tryDecodeNaddr (value) {
   let decoded
   try {
     decoded = naddrDecode(body)
-  } catch {
-    return null
+  } catch (cause) {
+    throw new ValidationError('INVALID_APP_URL_NADDR', { message: 'INVALID_NADDR', cause })
+  }
+  if (!SITE_MANIFEST_KINDS.has(decoded.kind)) {
+    throw new ValidationError('INVALID_APP_URL_NADDR', { message: 'NOT_SITE_MANIFEST' })
   }
-  if (!SITE_MANIFEST_KINDS.has(decoded.kind)) return null
 
   try {
     return {
@@ -79,8 +84,8 @@ function tryDecodeNaddr (value) {
         relays: decoded.relays
       })
     }
-  } catch {
-    return null
+  } catch (cause) {
+    throw new ValidationError('INVALID_APP_URL_NADDR', { message: 'INVALID_APP_ENTITY', cause })
   }
 }
 
@@ -90,27 +95,34 @@ function tryDecodeNaddr (value) {
 // - `{ type: 'entity', entity }` for NIP-19 app entities;
 // - `{ type: 'named', prefix, channel, appName, user }` for named URLs
 //   (`user` is null when no user part is present or it is invalid);
-// - `null` when the segment is not a valid app URL.
+// Throws `ValidationError` when the segment is not a valid app URL; use
+// `tryDecodeAppUrl` when a null result is preferred.
 export function decodeAppUrl (segment) {
-  if (typeof segment !== 'string' || !segment) return null
-  const decodedNaddr = tryDecodeNaddr(segment)
+  if (typeof segment !== 'string' || !segment) {
+    throw new ValidationError('INVALID_APP_URL', { message: 'URL_SEGMENT_SHOULD_BE_A_NON_EMPTY_STRING' })
+  }
+  const decodedNaddr = decodeNaddrSegment(segment)
   if (decodedNaddr) return decodedNaddr
 
   const prefixMatch = segment.match(/^\+{1,3}/)
-  if (!prefixMatch) return null
+  if (!prefixMatch) {
+    throw new ValidationError('INVALID_APP_URL', { message: 'MISSING_APP_URL_PREFIX' })
+  }
   const prefix = prefixMatch[0]
 
   if (NAPP_ENTITY_REGEX.test(segment)) {
     try {
       appDecode(segment)
-    } catch {
-      return null
+    } catch (cause) {
+      throw new ValidationError('INVALID_APP_URL_ENTITY', { message: 'INVALID_APP_ENTITY', cause })
     }
     return { type: 'entity', entity: segment }
   }
 
   const remainder = segment.slice(prefix.length)
-  if (!remainder) return null
+  if (!remainder) {
+    throw new ValidationError('INVALID_APP_URL', { message: 'MISSING_APP_NAME' })
+  }
   const parts = remainder.split('@')
   let appName
   let user = null
@@ -120,7 +132,7 @@ export function decodeAppUrl (segment) {
   } else if (parts.length === 2) {
     const tail = safeDecode(parts[1])
     appName = safeDecode(parts[0])
-    user = tail === null ? null : decodeUserReference(tail)
+    user = tail === null ? null : tryDecodeUserReference(tail)
   } else {
     const local = safeDecode(parts[parts.length - 2])
     const domain = safeDecode(parts[parts.length - 1])
@@ -133,8 +145,12 @@ export function decodeAppUrl (segment) {
     }
   }
 
-  if (appName === null || !isValidAppName(appName)) return null
-  if (!user && appName.length >= APP_URL_MIN_ENTITY_BODY_LENGTH) return null
+  if (appName === null || !isValidAppName(appName)) {
+    throw new ValidationError('INVALID_APP_URL_NAME', { message: 'Invalid app URL name' })
+  }
+  if (!user && appName.length >= APP_URL_MIN_ENTITY_BODY_LENGTH) {
+    throw new ValidationError('INVALID_APP_URL_ENTITY', { message: 'ENTITY_LIKE_URL_WITHOUT_USER' })
+  }
 
   return {
     type: 'named',
@@ -145,6 +161,17 @@ export function decodeAppUrl (segment) {
   }
 }
 
+// Non-throwing variant of `decodeAppUrl`: returns the decoded app URL or
+// `null` when the segment is not a valid app URL.
+export function tryDecodeAppUrl (segment) {
+  try {
+    return decodeAppUrl(segment)
+  } catch (error) {
+    if (error instanceof ValidationError) return null
+    throw error
+  }
+}
+
 // Encodes a named app URL segment. `user` is a decoded user reference:
 // NIP-05 (`bob@example.com`, `_@example.com`, `example.com` or the custom
 // `bob.xyz.example.com` form), npub, nprofile or hex pubkey.
@@ -156,7 +183,15 @@ export function encodeAppUrl ({ appName, channel = 'main', user }) {
   if (!prefix) {
     throw new ValidationError('INVALID_APP_URL_CHANNEL', { message: 'Invalid app URL channel' })
   }
-  const userRef = decodeUserReference(user)
+  let userRef
+  try {
+    userRef = decodeUserReference(user)
+  } catch (cause) {
+    if (cause instanceof ValidationError) {
+      throw new ValidationError('INVALID_APP_URL_USER', { message: cause.message ?? 'Invalid app URL user', cause })
+    }
+    throw cause
+  }
   if (!userRef) {
     throw new ValidationError('INVALID_APP_URL_USER', { message: 'Invalid app URL user' })
   }