libp2r2p 0.10.6 → 0.10.8

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

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.6",
+  "version": "0.10.8",
   "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/url/app-url.js

@@ -0,0 +1,192 @@
+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,
+  appEncode,
+  naddrDecode
+} from '../nip19/index.js'
+import {
+  DRAFT_SITE_MANIFEST,
+  MAIN_SITE_MANIFEST,
+  NEXT_SITE_MANIFEST
+} from '../kind/index.js'
+
+export const APP_URL_MIN_ENTITY_BODY_LENGTH = 48
+
+const SITE_MANIFEST_KINDS = new Set([
+  MAIN_SITE_MANIFEST,
+  NEXT_SITE_MANIFEST,
+  DRAFT_SITE_MANIFEST
+])
+const NADDR_PREFIX = 'naddr1'
+
+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)
+}
+
+// `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) {
+  if (typeof value !== 'string' || !value) return null
+  const body = value.replace(/^\+{1,3}/, '')
+  if (!body.startsWith(NADDR_PREFIX)) return null
+
+  let decoded
+  try {
+    decoded = naddrDecode(body)
+  } catch {
+    return null
+  }
+  if (!SITE_MANIFEST_KINDS.has(decoded.kind)) return null
+
+  try {
+    return {
+      type: 'entity',
+      entity: appEncode({
+        dTag: decoded.identifier,
+        pubkey: decoded.pubkey,
+        kind: decoded.kind,
+        relays: decoded.relays
+      })
+    }
+  } catch {
+    return null
+  }
+}
+
+// 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 decodedNaddr = tryDecodeNaddr(segment)
+  if (decodedNaddr) return decodedNaddr
+
+  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 =>