libp2r2p 0.10.5 → 0.10.7

package/README.md

@@ -329,6 +329,21 @@ the Schnorr signature on every call; it never adds a cache marker to the
 event. Their `assert…` counterparts return the original event or throw a
 `ValidationError` with a stable code.
 
+NIP-27 text references live in `libp2r2p/nip27`. `extractMedia()` splits
+content into text, URL, profile, event, relay, NIP-05 and hashtag items in
+occurrence order, accepting the optional `@` and `nostr:` mention prefixes
+plus NIP-05 in its standard, root and custom compact spellings.
+`decodeReference()` parses a single reference, and `decodeMediaMetadata()`
+reads the file/media metadata carried in a URL fragment
+(`#m=image/png&dim=640x480&...`).
+
+User references (`npub`, `nprofile`, hex pubkeys and every NIP-05 spelling)
+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.
+
 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
@@ -341,6 +356,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/index.js

@@ -18,6 +18,7 @@ export * as network from './network/index.js'
 export * as nip04 from './nip04/index.js'
 export * as nip05 from './nip05/index.js'
 export * as nip19 from './nip19/index.js'
+export * as nip27 from './nip27/index.js'
 export * as nip44 from './nip44/index.js'
 export * as nip44v3 from './nip44-v3/index.js'
 export * as nip46 from './nip46/index.js'

package/kind/index.js

@@ -88,6 +88,7 @@ export const USER_STATUSES = 30315
 export const I_TAG_TRUSTED_ASSERTION = 30385
 export const CLASSIFIED_LISTING = 30402
 export const DRAFT_CLASSIFIED_LISTING = 30403
+export const SITE_CURATION_SET = 30499
 export const DATE_BASED_CALENDAR_EVENT = 31922
 export const TIME_BASED_CALENDAR_EVENT = 31923
 export const CALENDAR = 31924
@@ -226,6 +227,7 @@ export const eventKinds = /* @__PURE__ */ Object.freeze({
   I_TAG_TRUSTED_ASSERTION,
   CLASSIFIED_LISTING,
   DRAFT_CLASSIFIED_LISTING,
+  SITE_CURATION_SET,
   DATE_BASED_CALENDAR_EVENT,
   TIME_BASED_CALENDAR_EVENT,
   CALENDAR,

package/nip05/helpers/nip05-identifier.js

@@ -0,0 +1,57 @@
+const NIP05_LOCAL = /^[a-z0-9._-]+$/
+const NIP05_DOMAIN = /^[a-z0-9.-]+$/
+
+export function isValidNip05Local (local) {
+  return typeof local === 'string' &&
+    (local === '_' || (local.length <= 64 && NIP05_LOCAL.test(local)))
+}
+
+export function isValidNip05Domain (domain) {
+  return typeof domain === 'string' &&
+    domain.length > 0 &&
+    domain.length <= 253 &&
+    domain.includes('.') &&
+    !domain.startsWith('.') &&
+    !domain.endsWith('.') &&
+    !domain.includes('..') &&
+    NIP05_DOMAIN.test(domain)
+}
+
+export function nip05FromLocalDomain (local, domain) {
+  if (!isValidNip05Local(local) || !isValidNip05Domain(domain)) return null
+  return { local, domain }
+}
+
+// Accepts:
+// - `local@domain` (standard NIP-05)
+// - `domain` with exactly one dot -> root `_@domain`
+// - `local.domain...` with more than one dot -> local part + domain (custom extension)
+export function decodeNip05Identifier (value) {
+  if (typeof value !== 'string') return null
+  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 (!text.includes('.')) return null
+  const firstDot = text.indexOf('.')
+  if (text.slice(firstDot + 1).includes('.')) {
+    return nip05FromLocalDomain(text.slice(0, firstDot), text.slice(firstDot + 1))
+  }
+  return nip05FromLocalDomain('_', text)
+}
+
+// Returns the most compact unambiguous NIP-05 spelling:
+// - root (`_@domain`) becomes `domain` only when the domain has one dot;
+// - a non-root local part becomes `local.domain` unless the local part
+//   itself contains dots, which would make the compact form ambiguous.
+export function compactNip05Raw (local, domain) {
+  if (local === '_') {
+    return domain.split('.').length === 2 ? domain : `_@${domain}`
+  }
+  return local.includes('.') ? `${local}@${domain}` : `${local}.${domain}`
+}

package/nip05/index.js

@@ -1,7 +1,7 @@
 import { normalizeRelayUrl } from '../url/index.js'
+import { decodeNip05Identifier } from './helpers/nip05-identifier.js'
 
 const PUBKEY = /^[0-9a-f]{64}$/
-const LOCAL_PART = /^[a-z0-9._-]+$/
 
 export async function queryProfile (identifier, {
   fetch: fetchImpl = globalThis.fetch,
@@ -9,17 +9,15 @@ export async function queryProfile (identifier, {
   timeoutMs = 5000
 } = {}) {
   if (typeof identifier !== 'string' || typeof fetchImpl !== 'function') return null
-  const normalized = identifier.trim().toLowerCase()
-  const separator = normalized.lastIndexOf('@')
-  if (separator <= 0 || separator === normalized.length - 1) return null
-  const name = normalized.slice(0, separator)
-  const domain = normalized.slice(separator + 1)
-  if (!LOCAL_PART.test(name) || /[/?#@]/.test(domain)) return null
+  const nip05 = decodeNip05Identifier(identifier)
+  if (!nip05) return null
+  const name = nip05.local
+  const domain = nip05.domain
 
   let url
   try {
     url = new URL(`https://${domain}/.well-known/nostr.json`)
-    if (url.hostname !== domain.split(':')[0] || url.username || url.password) return null
+    if (url.hostname !== domain || url.username || url.password) return null
     url.searchParams.set('name', name)
   } catch {
     return null

package/nip27/helpers/user-reference.js

@@ -0,0 +1,79 @@
+import { ValidationError } from '../../error/index.js'
+import { npubDecode, nprofileDecode } from '../../nip19/index.js'
+import { compactNip05Raw, decodeNip05Identifier } from '../../nip05/helpers/nip05-identifier.js'
+
+const HEX_PUBKEY = /^[0-9a-f]{64}$/
+
+// Strips the optional mention prefixes accepted by NIP-21 (`nostr:`) and the
+// social `@` handle marker. Either prefix may appear first.
+function stripReferencePrefix (value) {
+  let text = value.trim()
+  let changed = true
+  while (changed && text) {
+    changed = false
+    if (/^nostr:/i.test(text)) {
+      text = text.slice(6)
+      changed = true
+    }
+    if (text.startsWith('@')) {
+      text = text.slice(1)
+      changed = true
+    }
+  }
+  return text
+}
+
+// Decodes a user reference without performing any network lookup.
+// Returns `{ kind: 'pubkey', pubkey, relays, raw }` for npub/nprofile/hex or
+// `{ kind: 'nip05', local, domain, raw }` for NIP-05 (standard or extended),
+// where `raw` is always the most compact canonical spelling.
+export function decodeUserReference (value) {
+  if (typeof value !== 'string') return null
+  const text = stripReferencePrefix(value)
+  if (!text) return null
+
+  if (HEX_PUBKEY.test(text)) {
+    const raw = text.toLowerCase()
+    return { kind: 'pubkey', pubkey: raw, relays: [], raw }
+  }
+
+  if (text.toLowerCase().startsWith('npub1')) {
+    try {
+      const raw = text.toLowerCase()
+      return { kind: 'pubkey', pubkey: npubDecode(raw), relays: [], raw }
+    } catch {
+      return null
+    }
+  }
+
+  if (text.toLowerCase().startsWith('nprofile1')) {
+    try {
+      const raw = text.toLowerCase()
+      const { pubkey, relays } = nprofileDecode(raw)
+      return { kind: 'pubkey', pubkey, relays, raw }
+    } catch {
+      return null
+    }
+  }
+
+  const nip05 = decodeNip05Identifier(text)
+  if (!nip05) return null
+  const raw = compactNip05Raw(nip05.local, nip05.domain)
+  return { kind: 'nip05', ...nip05, raw }
+}
+
+// Returns the canonical compact spelling for a user reference, either as a
+// string or as a decoded reference object.
+export function encodeUserReference (value) {
+  const ref = typeof value === 'string'
+    ? decodeUserReference(value)
+    : value && typeof value === 'object' &&
+        (value.kind === 'pubkey' || value.kind === 'nip05')
+      ? value
+      : null
+  if (!ref) {
+    throw new ValidationError('INVALID_USER_REFERENCE', { message: 'Invalid user reference' })
+  }
+  if (ref.kind === 'pubkey') return ref.raw ?? ref.pubkey
+  return ref.raw ?? compactNip05Raw(ref.local, ref.domain)
+}

package/nip27/index.js

@@ -0,0 +1,360 @@
+import {
+  naddrDecode,
+  neventDecode,
+  noteDecode,
+  nrelayDecode
+} from '../nip19/index.js'
+import { queryProfile } from '../nip05/index.js'
+import { normalizeRelayUrl } from '../url/index.js'
+import {
+  decodeUserReference,
+  encodeUserReference
+} from './helpers/user-reference.js'
+
+export { decodeUserReference, encodeUserReference }
+
+const BECH32_BODY = '[ac-hj-np-z02-9]'
+const BOUNDARY_PREFIX = /(?<=^|[\s"«„「¡¿:{([])/.source
+const BOUNDARY_SUFFIX = /(?=\.?$|[.,]?\s|\.(?=\.)|\.?["»”」'!?;\])}])/.source
+
+const URL_SOURCE =
+  '(?<url>' +
+  /(?<protocol>https:\/\/)?(?:[-_A-Za-z0-9]{1,30}\.){1,4}[a-z]{2,63}/.source +
+  /(?:(?:\/[-._A-Za-z0-9%@#]{1,300}){0,11}(?<ext>\.[a-z-0-9]{3,4})|(?:\/[-._A-Za-z0-9%@#]{1,300}){0,11})\/?/.source +
+  /(?:\??&?(?:[-_+.A-Za-z0-9%*]{1,30}=[-_+.A-Za-z0-9%*]{1,300}&?){1,40}|\?)?/.source +
+  /(?:(?:#|(?<=#))[-_+.A-Za-z0-9%=&*:~,]{1,4000})?/.source +
+  /(?:\/|(?<![.,]))/.source +
+  ')'
+
+const NIP05_LOCAL = '[a-z0-9._-]{1,64}'
+const NIP05_DOMAIN = '(?:[a-z0-9-]+\\.)+[a-z]{2,63}'
+const NIP05_STANDARD = `(?:@)?(?<nip05>${NIP05_LOCAL}@${NIP05_DOMAIN})`
+const NIP05_AT_ROOT = '@(?<nip05AtRoot>[a-z0-9-]+\\.[a-z]{2,63})'
+const NIP05_AT_CUSTOM = `@(?<nip05AtCustom>${NIP05_LOCAL}\\.${NIP05_DOMAIN})`
+const NIP05_BARE_ROOT = '(?<nip05BareRoot>[a-z0-9-]+\\.[a-z]{2,63})'
+const NIP05_BARE_CUSTOM = `(?<nip05BareCustom>${NIP05_LOCAL}\\.${NIP05_DOMAIN})`
+
+function entitySource (name) {
+  const bodyLength = name === 'npub' ? '58' : (name === 'nrelay' ? '10,5000' : '58,5000')
+  return `(?:@|nostr:)?(?<${name}>${name}1${BECH32_BODY}{${bodyLength}})`
+}
+
+const ENTITY_SOURCES = [
+  entitySource('nrelay'),
+  entitySource('npub'),
+  entitySource('nprofile'),
+  entitySource('note'),
+  entitySource('nevent'),
+  entitySource('naddr')
+]
+
+const HASHTAG_SOURCE = /(?:#(?<hashtag>[^\s.!¡?¿@#$%^&*()=+/,[{\]};:'"><]+))/.source
+
+let regexCache
+function getReferencesRegex (bareNip05) {
+  const key = bareNip05 ? 'bare' : 'handle'
+  regexCache ??= {}
+  if (regexCache[key]) return regexCache[key]
+
+  const nip05Compact = [
+    NIP05_AT_ROOT,
+    NIP05_AT_CUSTOM,
+    ...(bareNip05 ? [NIP05_BARE_ROOT, NIP05_BARE_CUSTOM] : [])
+  ]
+  const alternatives = [
+    URL_SOURCE,
+    NIP05_STANDARD,
+    ...nip05Compact,
+    ...ENTITY_SOURCES,
+    HASHTAG_SOURCE
+  ]
+  // Bare compact NIP-05 forms are ambiguous with plain hostnames/URLs, so
+  // they are placed first only when explicitly requested.
+  if (bareNip05) {
+    alternatives.splice(0, 0, NIP05_BARE_ROOT, NIP05_BARE_CUSTOM)
+  }
+  const source = BOUNDARY_PREFIX + '(?:' + alternatives.join('|') + ')' + BOUNDARY_SUFFIX
+  return (regexCache[key] = new RegExp(source, 'gu'))
+}
+
+// Strips the optional NIP-21 (`nostr:`) and `@` mention prefixes.
+function stripReferencePrefix (value) {
+  let text = value.trim()
+  let changed = true
+  while (changed && text) {
+    changed = false
+    if (/^nostr:/i.test(text)) {
+      text = text.slice(6)
+      changed = true
+    }
+    if (text.startsWith('@')) {
+      text = text.slice(1)
+      changed = true
+    }
+  }
+  return text
+}
+
+function normalizeRelays (relays) {
+  return (relays || [])
+    .map(relay => {
+      try {
+        return normalizeRelayUrl(relay)
+      } catch {
+        return null
+      }
+    })
+    .filter(Boolean)
+}
+
+// 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.
+export function decodeReference (value) {
+  if (typeof value !== 'string') return null
+  const original = value.trim()
+  if (!original) return null
+  const text = stripReferencePrefix(original)
+  if (!text) return null
+
+  const account = decodeUserReference(text)
+  if (account) {
+    return account.kind === 'pubkey'
+      ? {
+          type: 'pubkey',
+          original,
+          value: account.raw,
+          pubkey: account.pubkey,
+          relays: account.relays
+        }
+      : {
+          type: 'nip05',
+          original,
+          value: account.raw,
+          local: account.local,
+          domain: account.domain
+        }
+  }
+
+  if (text.startsWith('note1')) {
+    try {
+      return { type: 'note', original, value: text, id: noteDecode(text) }
+    } catch {
+      return null
+    }
+  }
+  if (text.startsWith('nevent1')) {
+    try {
+      return { type: 'nevent', original, value: text, ...neventDecode(text) }
+    } catch {
+      return null
+    }
+  }
+  if (text.startsWith('naddr1')) {
+    try {
+      return { type: 'naddr', original, value: text, ...naddrDecode(text) }
+    } catch {
+      return null
+    }
+  }
+  if (text.startsWith('nrelay1')) {
+    try {
+      return { type: 'nrelay', original, value: text, relay: nrelayDecode(text) }
+    } catch {
+      return null
+    }
+  }
+  return null
+}
+
+const NIP94_TAGS = {
+  url: [{ key: 'url', type: 'array' }],
+  'aes-256-gcm': ['key', 'iv'],
+  m: ['m'],
+  x: [{ key: 'x', type: 'array' }],
+  ox: ['ox'],
+  size: ['size'],
+  dim: ['dim'],
+  magnet: ['magnet'],
+  i: ['i'],
+  blurhash: ['blurhash'],
+  thumb: ['thumb'],
+  image: ['image'],
+  summary: ['summary'],
+  alt: ['alt'],
+  caption: ['caption']
+}
+
+// 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.
+export function decodeMediaMetadata (url, { extraTags } = {}) {
+  if (typeof url !== 'string' || !url) return {}
+
+  const tags = extraTags ? { ...NIP94_TAGS, ...extraTags } : NIP94_TAGS
+  const tagIndexes = {}
+  const obj = (url.match(/(?<=#)[-_+.A-Za-z0-9%=&*]{1,4000}/)?.[0] || '')
+    .split('&')
+    .filter(Boolean)
+    .reduce((memo, item) => {
+      let [key, value = ''] = item.split('=')
+      key = decodeFragmentValue(key)
+      value = decodeFragmentValue(value)
+      const config = tags[key]
+      if (!config || (tagIndexes[key] ??= 0) === config.length) return memo
+
+      const name = config[tagIndexes[key]]?.key ?? config[tagIndexes[key]]
+      const type = config[tagIndexes[key]]?.type ?? 'string'
+      switch (type) {
+        case 'array': memo[name] ??= []; memo[name].push(value); break
+        case 'string': memo[name] = value; tagIndexes[key]++; break
+        default: break
+      }
+      return memo
+    }, {})
+
+  if ('dim' in obj) {
+    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
+  }
+  return obj
+}
+
+function decodeFragmentValue (value) {
+  try {
+    return decodeURIComponent(value.replace(/\+/g, '%20'))
+  } catch {
+    return 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) }
+    if (!urlItem.m && typeof getMimeType === 'function') {
+      const mime = getMimeType({ url, ext: groups.ext })
+      if (mime) urlItem.m = mime
+    }
+    return { key: 'url', url: urlItem }
+  }
+
+  if (
+    groups.nip05 ||
+    groups.nip05AtRoot ||
+    groups.nip05AtCustom ||
+    groups.nip05BareRoot ||
+    groups.nip05BareCustom
+  ) {
+    const account = decodeUserReference(original)
+    if (!account) return null
+    return {
+      key: 'nip05',
+      nip05: {
+        original,
+        value: account.raw,
+        local: account.local,
+        domain: account.domain
+      }
+    }
+  }
+
+  if (groups.hashtag) {
+    return { key: 'hashtag', hashtag: { value: groups.hashtag } }
+  }
+
+  const ref = decodeReference(original)
+  if (!ref) return null
+  switch (ref.type) {
+    case 'pubkey': {
+      const isNprofile = ref.value.startsWith('nprofile1')
+      const profile = {
+        pubkey: ref.pubkey,
+        relays: normalizeRelays(ref.relays),
+        original,
+        nip19Type: isNprofile ? 'nprofile' : 'npub'
+      }
+      if (!isNprofile) profile.npub = ref.value
+      return { key: 'profile', profile }
+    }
+    case 'note':
+      return { key: 'event', event: { id: ref.id, relays: [], original, nip19Type: 'note' } }
+    case 'nevent':
+      return {
+        key: 'event',
+        event: {
+          id: ref.id,
+          relays: normalizeRelays(ref.relays),
+          original,
+          nip19Type: 'nevent',
+          ...(ref.author !== undefined && { author: ref.author }),
+          ...(ref.kind !== undefined && { kind: ref.kind })
+        }
+      }
+    case 'naddr':
+      return {
+        key: 'event',
+        event: {
+          identifier: ref.identifier,
+          pubkey: ref.pubkey,
+          kind: ref.kind,
+          relays: normalizeRelays(ref.relays),
+          original,
+          nip19Type: 'naddr'
+        }
+      }
+    case 'nrelay':
+      return { key: 'relay', relay: { relay: ref.relay, original, value: ref.value } }
+    default:
+      return null
+  }
+}
+
+// Modernized NIP-27 text-reference extractor. Accepts optional `@` and
+// `nostr:` mention prefixes, NIP-05 (standard, root and custom compact) and
+// keeps the same item shape as the previous text extractor for URLs/entities.
+// Bare compact NIP-05 spellings (`bob.example.com`) are only recognized when
+// `{ 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 []
+  const regex = getReferencesRegex(bareNip05)
+  const items = []
+  let end = 0
+
+  for (const match of content.matchAll(regex)) {
+    const start = match.index
+    if (start > end) {
+      items.push({ key: 'text', text: { value: content.slice(end, start) } })
+    }
+    const original = match[0]
+    end = start + original.length
+    const item = getReferenceItem(original, match.groups, { getMimeType })
+    if (item) items.push(item)
+  }
+
+  if (items.length === 0) {
+    items.push({ key: 'text', text: { value: content } })
+  } else if (end < content.length) {
+    items.push({ key: 'text', text: { value: content.slice(end) } })
+  }
+  return items
+}
+
+// Resolves a user reference to a pubkey and relay hints. NIP-05 lookups go
+// through `queryProfile` (accepting standard, root and compact custom
+// spellings); npub/nprofile/hex are resolved locally.
+export async function resolveUserReference (value, options = {}) {
+  const account = decodeUserReference(value)
+  if (!account) return null
+  if (account.kind === 'pubkey') {
+    return { pubkey: account.pubkey, relays: account.relays, label: account.raw }
+  }
+
+  const result = await queryProfile(`${account.local}@${account.domain}`, options)
+  if (!result) return null
+  return { pubkey: result.pubkey, relays: result.relays, label: account.raw }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libp2r2p",
-  "version": "0.10.5",
+  "version": "0.10.7",
   "description": "Peer-to-relay-to-peer",
   "keywords": [
     "p2r2p",
@@ -31,6 +31,7 @@
     "nip04",
     "nip05",
     "nip19",
+    "nip27",
     "nip44",
     "nip44-v3",
     "nip46",
@@ -71,6 +72,7 @@
     "./nip04": "./nip04/index.js",
     "./nip05": "./nip05/index.js",
     "./nip19": "./nip19/index.js",
+    "./nip27": "./nip27/index.js",
     "./nip44": "./nip44/index.js",
     "./nip44-v3": "./nip44-v3/index.js",
     "./nip46": "./nip46/index.js",

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/app-url.js

@@ -0,0 +1,143 @@
+import { ValidationError } from '../error/index.js'
+import {
+  compactNip05Raw,
+  nip05FromLocalDomain
+} from '../nip05/helpers/nip05-identifier.js'
+import {
+  decodeUserReference,
+  encodeUserReference
+} from '../nip27/helpers/user-reference.js'
+import {
+  NAPP_ENTITY_REGEX,
+  appDecode
+} from '../nip19/index.js'
+
+export const APP_URL_MIN_ENTITY_BODY_LENGTH = 48
+
+const APP_NAME_MAX_LENGTH = 260
+const CHANNEL_BY_PREFIX = { '+': 'main', '++': 'next', '+++': 'draft' }
+const PREFIX_BY_CHANNEL = { main: '+', next: '++', draft: '+++' }
+const KIND_BY_CHANNEL = { main: 35128, next: 35129, draft: 35130 }
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]/
+
+function safeDecode (value) {
+  try {
+    return decodeURIComponent(value)
+  } catch {
+    return null
+  }
+}
+
+function isValidAppName (appName) {
+  return typeof appName === 'string' &&
+    appName.length > 0 &&
+    appName.length <= APP_NAME_MAX_LENGTH &&
+    !appName.startsWith('+') &&
+    !appName.includes('/') &&
+    !CONTROL_CHARS.test(appName)
+}
+
+// Decodes a raw (still percent-encoded) first path segment such as
+// `+apps` or `+caf%C3%A9@bob@example.com` or `+3swFhu...`.
+// Returns:
+// - `{ 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.
+export function decodeAppUrl (segment) {
+  if (typeof segment !== 'string' || !segment) return null
+  const prefixMatch = segment.match(/^\+{1,3}/)
+  if (!prefixMatch) return null
+  const prefix = prefixMatch[0]
+
+  if (NAPP_ENTITY_REGEX.test(segment)) {
+    try {
+      appDecode(segment)
+    } catch {
+      return null
+    }
+    return { type: 'entity', entity: segment }
+  }
+
+  const remainder = segment.slice(prefix.length)
+  if (!remainder) return null
+  const parts = remainder.split('@')
+  let appName
+  let user = null
+
+  if (parts.length === 1) {
+    appName = safeDecode(parts[0])
+  } else if (parts.length === 2) {
+    const tail = safeDecode(parts[1])
+    appName = safeDecode(parts[0])
+    user = tail === null ? null : decodeUserReference(tail)
+  } else {
+    const local = safeDecode(parts[parts.length - 2])
+    const domain = safeDecode(parts[parts.length - 1])
+    const nip05 = nip05FromLocalDomain(local, domain)
+    if (nip05) {
+      user = { kind: 'nip05', ...nip05, raw: compactNip05Raw(local, domain) }
+      appName = parts.slice(0, -2).map(safeDecode).join('@')
+    } else {
+      appName = safeDecode(remainder)
+    }
+  }
+
+  if (appName === null || !isValidAppName(appName)) return null
+  if (!user && appName.length >= APP_URL_MIN_ENTITY_BODY_LENGTH) return null
+
+  return {
+    type: 'named',
+    prefix,
+    channel: CHANNEL_BY_PREFIX[prefix],
+    appName,
+    user
+  }
+}
+
+// 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.
+export function encodeAppUrl ({ appName, channel = 'main', user }) {
+  if (!isValidAppName(appName)) {
+    throw new ValidationError('INVALID_APP_URL_NAME', { message: 'Invalid app URL name' })
+  }
+  const prefix = PREFIX_BY_CHANNEL[channel]
+  if (!prefix) {
+    throw new ValidationError('INVALID_APP_URL_CHANNEL', { message: 'Invalid app URL channel' })
+  }
+  const userRef = decodeUserReference(user)
+  if (!userRef) {
+    throw new ValidationError('INVALID_APP_URL_USER', { message: 'Invalid app URL user' })
+  }
+
+  let encodedAppName = encodeURIComponent(appName)
+  let userText
+  if (userRef.kind === 'nip05') {
+    // Keep `@` raw inside the app name so the verbose NIP-05 form stays
+    // readable (`+my@app@bob@example.com`).
+    encodedAppName = encodedAppName.replace(/%40/g, '@')
+    const appNameHasAt = appName.includes('@')
+    if (userRef.local === '_') {
+      userText = userRef.domain.split('.').length === 2 && !appNameHasAt
+        ? userRef.domain
+        : `_@${userRef.domain}`
+    } else {
+      // Prefer the shorter single-`@` custom NIP-05 form (`bob.example.com`)
+      // unless the app name itself contains `@`, which forces the verbose form.
+      userText = appNameHasAt
+        ? `${userRef.local}@${userRef.domain}`
+        : `${userRef.local}.${userRef.domain}`
+    }
+  } else {
+    userText = encodeUserReference(userRef)
+  }
+
+  return `${prefix}${encodedAppName}@${userText}`
+}
+
+// Convenience for callers that need the manifest kind for a decoded channel.
+export function appUrlKindByChannel (channel) {
+  return KIND_BY_CHANNEL[channel] || null
+}

package/url/index.js

@@ -1,5 +1,7 @@
 import { ValidationError } from '../error/index.js'
 
+export * from './app-url.js'
+
 function isIpv4Address (hostname) {
   const parts = hostname.split('.')
   return parts.length === 4 && parts.every(part =>
@@ -130,7 +132,14 @@ export function normalizeBlossomServerUrl (value) {
   return url.origin
 }
 
-function publicRelayUrlError (value) {
+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}`
@@ -148,28 +157,33 @@ 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 hostError = publicHostError(url, {
-    invalidHostCode: 'INVALID_RELAY_HOST',
-    nonPublicHostCode: 'NON_PUBLIC_RELAY_HOST',
-    nonPublicIpCode: 'NON_PUBLIC_RELAY_IP'
-  })
-  if (hostError) return hostError
+  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) {
-  const code = publicRelayUrlError(value)
+export function assertValidPublicRelayUrl (value, policy) {
+  const code = publicRelayUrlError(value, policy)
   if (code) throw new ValidationError(code)
   return value
 }