libp2r2p 0.10.17 → 0.10.19

package/README.md

@@ -12,35 +12,95 @@ 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.
 
-## Relay feed lifecycle
-
-`RelayPool.getEventsFeedGenerator(filter, relays, options)` yields events directly,
-including the existing `event.meta.relay` field. By default it combines an initial
-historical query with a live subscription. `live: false` selects history only;
-`filter.limit: 0` selects live only. `getLiveEventsGenerator` exposes the same
-lifecycle controls along with its existing `ready` and `readyRelays` properties.
-
-The returned iterator has a synchronous, idempotent `stopAndDrain()` method. It
-closes subscription input and cancels reconnections and outstanding historical
-queries, while retaining events already accepted by the library's receive
-callbacks. Continue consuming the iterator to obtain those events and observe
-completion. This includes initial history, buffered live events, and both history
-and live buffers from reconnect recovery. Calling it before the first `next()`
-prevents subscriptions from opening. No reception timestamp or new event metadata
-is added. Events rejected by ordinary filtering/deduplication remain excluded.
+## Relay reads and lifecycle
+
+All three `RelayPool` read generators emit typed envelopes. The Nostr event is
+never decorated with `meta`; relay provenance belongs to its enclosing item:
+
+```js
+{ type: 'event', event, relay }
+{ type: 'error', relay, error }
+{ type: 'eose', relays: [{ relay, status, error }] } // error is optional
+```
+
+`eose` means the **initial read attempt is complete**, including empty reads and
+partial results. Its report distinguishes actual relay EOSE from other outcomes:
+
+| Status | Meaning |
+| --- | --- |
+| `eose` | The relay sent EOSE. |
+| `satisfied` | The requested limit or IDs were satisfied, so the read closed early. |
+| `timeout` | The initial operation deadline elapsed. Also emits an error item. |
+| `cutoff` | The grace period after the first qualifying EOSE/early completion elapsed. |
+| `closed` | The subscription ended without EOSE or an explicit error. |
+| `error` | Connection or subscription failed. Also emits an error item. |
+
+Each normalized relay URL gets one report entry, preserving the first spelling
+provided by the caller. An empty relay list emits `{ type: 'eose', relays: [] }`.
+Caller cancellation never fabricates an initial completion. Individual relay
+failures do not prevent other relays from delivering; malformed arguments and
+general operation failures reject the call or iterator read.
+
+`getEvents(filter, relays, options)` resolves to
+`{ result: [{ event, relay }], errors: [{ relay, reason }], success, relays }`.
+Its optional `callback` receives the same event/error/EOSE envelopes immediately.
+`success` retains its existing meaning: an event was received or at least one
+relay completed without an error; it does not mean every relay sent EOSE.
+`getEventsGenerator` emits those envelopes and retains that report as its final
+iterator return value (not visible inside a `for await` loop).
+
+`getEventsFeedGenerator(filter, relays, options)` combines history and live
+subscription by default: history items, one historical `eose`, buffered live
+items, then ongoing live delivery. `live: false` ends after history and its marker;
+`filter.limit: 0` skips history and forwards the live stream's initial marker.
+Internal live/reconnect EOSEs do not produce additional feed markers.
+
+`getLiveEventsGenerator` discards retained events received before each relay's
+EOSE. A ready relay can deliver live events before the aggregate marker. Initial
+`timeout` defaults to 5000 ms (`null` disables it); expiration reports pending
+relays without stopping their connections or subsequent recovery. The grace
+period `timeoutAfterFirstEose` defaults to 500 ms (`null` disables it). Historical
+queries use these same defaults; their grace period starts only when a relay
+with events EOSEs or satisfies its filter. Reconnect-gap reads keep their separate
+`timeoutForReconnectGap` and `timeoutAfterFirstReconnectGapEose` options.
+
+The live iterator retains `ready: Promise<{ relays, errors }>` and the
+`readyRelays` getter. `ready` is the initial readiness snapshot, derived from the
+same outcomes as the marker; its errors use `{ relay, reason }`. `readyRelays`
+tracks currently ready relays and can change after that snapshot. Timeouts and
+cutoffs are not acknowledgements of readiness. Reconnections do not repeat the
+initial marker. Both APIs require consuming the iterator to start its work.
+
+Live and feed iterators have a synchronous, idempotent `stopAndDrain()` method.
+It closes subscription input and cancels reconnections and outstanding historical
+queries, while retaining items already accepted by receive callbacks. Continue
+consuming to obtain those items and completion. This includes initial history,
+buffered live events, and reconnect recovery buffers. Calling it before the
+first `next()` prevents subscriptions from opening. It does not synthesize EOSE.
 
 Aborting `options.signal`, calling `return()` (including a `for await` break), or
-calling `throw()` cancels input and pending delivery instead. An event already
-delivered to the caller cannot be recalled. These operations also interrupt a
-drain. `stopAndDrain()` does not consume the iterator or return a completion
-promise: completion is the iterator's `{ done: true }` result.
+calling `throw()` cancels input and pending delivery instead. An item already
+delivered cannot be recalled. These operations can also interrupt a drain.
+`stopAndDrain()` does not consume the iterator or return a completion promise:
+completion is the iterator's `{ done: true }` result.
 
 ```js
 const stream = relayPool.getEventsFeedGenerator({ authors: [pubkey] }, [relay], { signal })
 // When this relay is removed, call stream.stopAndDrain() from the list handler.
-for await (const event of stream) await store(event)
+for await (const item of stream) {
+  if (item.type === 'event') await store(item.event)
+  else if (item.type === 'error') reportError(item.relay, item.error)
+  else if (item.type === 'eose') initialReadFinished(item.relays)
+}
 ```
 
+Migration from 0.10.18: replace raw live/feed event reads with `item.event` after
+checking `item.type`, replace `event.meta.relay` with the envelope's `relay`, and
+unwrap each `getEvents().result` entry. There is no compatibility flag. Query,
+content-key, private-channel and NIP-46 helpers unwrap pool results internally
+and retain their higher-level event contracts. Count, publication and disconnect
+return formats are unchanged.
+
 ## Private Messenger
 
 The main API is `createPrivateMessenger` from `libp2r2p/private-messenger`.
@@ -146,7 +206,7 @@ if (sent.delivery.deletionSeckey) {
     const deletion = finalizeEvent({
       kind: 5,
       created_at: Math.floor(Date.now() / 1000),
-      tags: [['k', '3560'], ...outerEvents.slice(offset, offset + 100).map(event => ['e', event.id])],
+      tags: [['k', '3560'], ...outerEvents.slice(offset, offset + 100).map(({ event }) => ['e', event.id])],
       content: ''
     }, deletionKey.secretKey)
     await relayPool.sendEvent(deletion, relays)
@@ -478,11 +538,11 @@ from `libp2r2p/relay`.
 `getEvents` and `getEventsGenerator` accept `deduplicateAcrossRelays` (boolean,
 default `true`). With `false`, a matching event is delivered once per relay,
 while repeated IDs from the same relay remain suppressed. Each occurrence owns
-its `meta.relay`; callbacks still run immediately and deadlines, EOSE handling,
-and per-relay filter limits are unchanged. The callback/generator item remains
-`{ type: 'event', event, relay }`, and the completed query remains
-`{ result, errors, success }`. The option does not extend to the live or feed
-generators. Callers that need replication coverage can aggregate the returned
+its envelope's `relay`; callbacks still run immediately and per-relay filter
+limits are unchanged. The callback/generator event item is
+`{ type: 'event', event, relay }`; the completed query is
+`{ result: [{ event, relay }], errors, success, relays }`. The option does not
+extend to the live or feed generators. Callers that need replication coverage can aggregate the returned
 copies by event ID; missing responses do not prove absence from a relay.
 
 Publication errors retain their existing `reason` objects and may expose
@@ -555,3 +615,14 @@ bytes, while integer mode supports fixed-width identifiers.
 In NIP-5A, "no padding" means that no separate padding character such as `=`
 is used. Leading `0` digits are nevertheless required to make every Nsite
 Base36 value exactly 50 characters long.
+
+## Files
+
+[`libp2r2p/irfs`](irfs/README.md) prepares retryable chunk templates from files,
+with explicit cancellation and resource release. [`libp2r2p/nip94`](nip94/README.md)
+builds/interprets file metadata, including the local IRFS profile. NIP-27 extracts
+`https://nostr.alt/nfile1…?localOnly=1` up to the NIP-19 codec's 5,000-character
+limit, retaining the full URL and exposing decoded `url.nfile` and MIME `url.m`.
+
+The NIP-94 extension also carries optional `download` intent; see
+[nip94/README.md](nip94/README.md#download-intent) for event and inline URL forms.

package/content-key/services/iykc-proof.js

@@ -103,7 +103,7 @@ export async function getIykcProofs (pubkeys, {
           timeout: 5000,
           timeoutAfterFirstEose: null
         })
-        return result
+        return result.map(({ event }) => event)
       })
   )
 

package/irfs/README.md

@@ -0,0 +1,35 @@
+# IRFS preparation
+
+`libp2r2p/irfs` prepares an immutable browser `File`/`Blob` or `Uint8Array`.
+It has no signer, publisher, relay pool or launcher dependency.
+
+```js
+import { prepareIrfsFile, decodeIrfsChunk } from 'libp2r2p/irfs'
+const prepared = await prepareIrfsFile(file, { signal })
+try {
+  const created_at = Math.floor(Date.now() / 1000)
+  for await (const template of prepared.chunks({ created_at, signal })) {
+    // Sign/store/publish according to the consuming application's policy.
+    const verified = decodeIrfsChunk(template)
+  }
+  // prepared.chunks({ created_at }) may be iterated again for retry.
+} finally {
+  prepared.close()
+}
+```
+
+The result exposes `root` (hex MMR root), `size`, `total`, `chunks()` and
+idempotent `close()`. Blocks contain at most 51,000 bytes; only the final block
+may be smaller. Templates use kind 34601, deterministic `d` identifiers, an
+`mmr` tag containing decimal index/total and Base93 proof, and Base93 content.
+Use a stable timestamp when identical templates are required across retries.
+`decodeIrfsChunk()` validates the proof, identifier, root and block size.
+
+Preparation retains the immutable input and an in-memory NMMR hash tree, not
+a second copy of file bytes. It creates **no temporary IndexedDB database**.
+`close()` drops its input/tree references and abort-listener registration;
+abort also closes preparation. In-flight Blob reads finish but cannot yield
+another chunk after cancellation. Consumers own any object URLs they create.
+Hash memory scales with chunk count. `onProgress({ completed, total })` reports
+bytes hashed; preparation yields regularly for input/cancellation.
+Empty input raises `ValidationError('EMPTY_IRFS_FILE')` in this version.

package/irfs/index.js

@@ -0,0 +1,74 @@
+import NMMR, { InMemoryMMR } from 'nmmr'
+import { encode, decode } from '../base93/index.js'
+import { bytesToBase16 } from '../base16/index.js'
+import { ValidationError } from '../error/index.js'
+
+export const IRFS_CHUNK_BYTES = 51000
+export const IRFS_CHUNK_KIND = 34601
+
+// Blob/File input is immutable and seekable: retain it instead of copying its
+// bytes to temporary IndexedDB. Only tree hashes and leaf positions stay in RAM.
+export async function prepareIrfsFile (input, { signal, onProgress } = {}) {
+  let blob = input instanceof Uint8Array ? new Blob([input]) : input
+  if (!(blob instanceof Blob)) throw new ValidationError('INVALID_IRFS_FILE')
+  if (!blob.size) throw new ValidationError('EMPTY_IRFS_FILE')
+  let tree = new InMemoryMMR()
+  let positions = []
+  const size = blob.size
+  const total = Math.ceil(size / IRFS_CHUNK_BYTES)
+  let closed = false
+  const check = currentSignal => {
+    signal?.throwIfAborted()
+    currentSignal?.throwIfAborted()
+    if (closed) throw new Error('IRFS preparation closed')
+  }
+  const close = () => {
+    closed = true
+    blob = tree = positions = null
+    signal?.removeEventListener('abort', close)
+  }
+  signal?.addEventListener('abort', close, { once: true })
+  try {
+    for (let index = 0; index < total; index++) {
+      check()
+      const bytes = new Uint8Array(await blob.slice(index * IRFS_CHUNK_BYTES, (index + 1) * IRFS_CHUNK_BYTES).arrayBuffer())
+      check()
+      positions.push(Number(tree.append(bytes).leafIdx))
+      onProgress?.({ completed: Math.min(size, (index + 1) * IRFS_CHUNK_BYTES), total: size })
+      // Yield to input and cancellation even when a Blob read resolves immediately.
+      if (index % 32 === 31) await new Promise(resolve => setTimeout(resolve, 0))
+    }
+    const root = bytesToBase16(tree.bagThePeaks())
+    return {
+      root, size, total, close,
+      async * chunks ({ created_at: createdAt = Math.floor(Date.now() / 1000), signal: readSignal } = {}) {
+        if (!Number.isSafeInteger(createdAt) || createdAt < 0) throw new ValidationError('INVALID_IRFS_TIMESTAMP')
+        for (let index = 0; index < total; index++) {
+          check(readSignal)
+          const bytes = new Uint8Array(await blob.slice(index * IRFS_CHUNK_BYTES, (index + 1) * IRFS_CHUNK_BYTES).arrayBuffer())
+          check(readSignal)
+          const hashes = tree.getProofArray(positions[index])
+          const proof = new Uint8Array(hashes.length * 32)
+          hashes.forEach((hash, offset) => proof.set(hash, offset * 32))
+          yield { kind: IRFS_CHUNK_KIND, created_at: createdAt, tags: [['d', NMMR.deriveChunkId(root, index)], ['mmr', String(index), String(total), encode(proof)]], content: encode(bytes) }
+        }
+      }
+    }
+  } catch (error) { close(); throw error }
+}
+
+export function decodeIrfsChunk (event) {
+  try {
+    if (event?.kind !== IRFS_CHUNK_KIND || !Array.isArray(event.tags)) throw new Error('Invalid kind or tags')
+    const d = event.tags.filter(tag => tag[0] === 'd')
+    const mmr = event.tags.filter(tag => tag[0] === 'mmr')
+    if (d.length !== 1 || d[0].length !== 2 || mmr.length !== 1 || mmr[0].length !== 4) throw new Error('Invalid chunk tags')
+    const [, index, total, encodedProof] = mmr[0]
+    const contentBytes = decode(event.content)
+    const proof = decode(encodedProof)
+    const root = NMMR.calculateRoot({ contentBytes, index, total, proof })
+    if (!contentBytes.length || contentBytes.length > IRFS_CHUNK_BYTES || (Number(index) < Number(total) - 1 && contentBytes.length !== IRFS_CHUNK_BYTES)) throw new Error('Invalid chunk length')
+    if (NMMR.deriveChunkId(root, index) !== d[0][1]) throw new Error('Invalid chunk ID')
+    return { root, index: Number(index), total: Number(total), contentBytes, proof }
+  } catch (cause) { throw new ValidationError('INVALID_IRFS_CHUNK', { cause }) }
+}

package/nip27/index.js

@@ -2,6 +2,7 @@ import { ValidationError } from '../error/index.js'
 import {
   NAPP_ENTITY_REGEX,
   naddrDecode,
+  nfileDecode,
   neventDecode,
   noteDecode,
   nrelayDecode
@@ -75,6 +76,7 @@ function getReferencesRegex (bareNip05) {
     ...(bareNip05 ? [NIP05_BARE_ROOT, NIP05_BARE_CUSTOM] : [])
   ]
   const alternatives = [
+    '(?<nfileUrl>https://nostr[.]alt/(?<nfileEntity>nfile1[ac-hj-np-z02-9]{1,4994})(?:[?]localOnly=1)?(?:#[-_+.A-Za-z0-9%=&*]{1,4000})?)',
     URL_SOURCE,
     APP_SOURCE,
     NIP05_STANDARD,
@@ -203,7 +205,8 @@ const NIP94_TAGS = {
   image: ['image'],
   summary: ['summary'],
   alt: ['alt'],
-  caption: ['caption']
+  caption: ['caption'],
+  download: ['download']
 }
 
 function validateTagConfigs (extraTags) {
@@ -236,11 +239,20 @@ export function decodeMediaMetadata (url, { extraTags } = {}) {
 
   const tags = extraTags ? { ...NIP94_TAGS, ...extraTags } : NIP94_TAGS
   const tagIndexes = {}
+  // Validate against the complete fragment before the generic bounded parser:
+  // punctuation must not turn an invalid value such as 1/foo into a valid 1.
+  const fragment = url.includes('#') ? url.slice(url.indexOf('#') + 1) : ''
+  const downloads = fragment.split('&').filter(item => decodeFragmentValue(item.split('=')[0]) === 'download')
+  if (downloads.length > 1 || downloads.some(item => {
+    const parts = item.split('=')
+    return parts.length !== 2 || !['0', '1'].includes(decodeFragmentValue(parts[1]))
+  })) throw new ValidationError('INVALID_MEDIA_METADATA_DOWNLOAD')
   const obj = (url.match(/(?<=#)[-_+.A-Za-z0-9%=&*]{1,4000}/)?.[0] || '')
     .split('&')
     .filter(Boolean)
     .reduce((memo, item) => {
-      let [key, value = ''] = item.split('=')
+      const parts = item.split('=')
+      let [key, value = ''] = parts
       key = decodeFragmentValue(key)
       value = decodeFragmentValue(value)
       const config = tags[key]
@@ -299,6 +311,14 @@ function getReferenceItem (original, groups, { getMimeType, defaultAppUser }) {
       : { key: 'text', text: { value: original } }
   }
 
+  if (groups.nfileUrl) {
+    try {
+      const file = nfileDecode(groups.nfileEntity)
+      const metadata = tryDecodeMediaMetadata(groups.nfileUrl) || {}
+      return { key: 'url', url: { ...metadata, value: groups.nfileUrl, nfile: file, ...(file.mime ? { m: file.mime } : {}) } }
+    } catch { return { key: 'text', text: { value: original } } }
+  }
+
   if (groups.url) {
     const url = `${groups.protocol ? '' : 'https://'}${groups.url}`
     let mediaMetadata = {}

package/nip46/services/client.js

@@ -75,12 +75,16 @@ export class Nip46Client {
       limit: 0
     }, parsed.relays, {
       signal: controller.signal,
+      timeout: options.timeout ?? DEFAULT_TIMEOUT,
       timeoutAfterFirstEose: options.timeoutAfterFirstEose ?? DEFAULT_TIMEOUT_AFTER_FIRST_EOSE
     })
     const found = Promise.withResolvers()
     const consume = (async () => {
       try {
-        for await (const event of stream) {
+        for await (const item of stream) {
+          if (item.type === 'error') { options.onError?.(item.error); continue }
+          if (item.type !== 'event') continue
+          const { event } = item
           if (!isNip46EventFor(event, clientPubkey)) continue
           const response = decodeNip46Frame(event, clientSecretKey)
           if (response?.result === parsed.secret) {

package/nip46/services/transport.js

@@ -95,14 +95,16 @@ export class Nip46Transport {
     const controller = new AbortController()
     const stream = this.#relayPool.getLiveEventsGenerator(filter, relays, {
       signal: controller.signal,
+      timeout: this.#operationTimeout,
       timeoutAfterFirstEose: this.#timeoutAfterFirstEose
     })
     const context = { controller, stream, relays: [...relays], consume: null }
     this.#contexts.add(context)
     context.consume = (async () => {
       try {
-        for await (const event of stream) {
-          Promise.resolve(onEvent(event)).catch(error => this.#reportError(error))
+        for await (const item of stream) {
+          if (item.type === 'error') this.#reportError(item.error)
+          else if (item.type === 'event') Promise.resolve(onEvent(item.event)).catch(error => this.#reportError(error))
         }
       } catch (error) {
         if (!this.#closed && error?.message !== 'Aborted') this.#reportError(error)

package/nip94/README.md

@@ -0,0 +1,40 @@
+# File metadata
+
+`libp2r2p/nip94` exports `createFileMetadata(options)` and
+`decodeFileMetadata(event)`. The former creates an unsigned kind-1063 template;
+the latter reads and validates its tags without parsing the caption as a URL.
+
+This is an **adaptation/extension of NIP-94**, not a claim that every emitted
+event meets its SHA-256 requirements. `url` and `mime` are required. Options
+include `caption`, `created_at`, `size`, `width`/`height`, `alt`, `root`, `service`,
+`thumbhash`, `sha256`, `originalSha256`, and additional `tags` (e.g. replies).
+The caption becomes `.content`. `root` maps to `r`, dimensions to `dim`, hashes
+to `x`/`ox`; hashes are optional and never synthesized. ThumbHash is transported
+unchanged as Base64, independently of image decoding. No `blurhash` is generated.
+
+For local IRFS files use `service: 'irfs'` and
+`https://nostr.alt/nfile1…?localOnly=1`. Encode the MMR root, MIME and filename
+with `nfileEncode`; relay/author hints are unnecessary. The decoder verifies
+agreement between `r`/`m` and nfile metadata and exposes its `filename`.
+The `r` reference allows storage owners to retain the associated local chunks.
+The module does not encrypt, sign, store or download data.
+
+## Download intent
+
+`download` is an optional extension expressing the author's intended action:
+`'1'` asks clients to download on activation rather than open/play the media.
+It does not prevent thumbnails or enforce server behavior.
+
+For kind 1063, no tag and `['download', '0']` both decode to `download: '0'`;
+`['download']` and `['download', '1']` both decode to `download: '1'`.
+Empty/other values, extra fields and duplicate download tags are invalid.
+`createFileMetadata({ ..., download: '0' | '1' })` emits an explicit value;
+omitting the option emits no download tag. Boolean/numeric options are invalid.
+
+For inline URLs, `nip27.decodeMediaMetadata()` requires an explicit
+`#download=0` or `#download=1` (or `&download=...` after other fragment fields).
+A bare/empty/duplicate/invalid value throws `INVALID_MEDIA_METADATA_DOWNLOAD`;
+`tryDecodeMediaMetadata()` returns null. No fragment means no download property.
+`extractMedia()` carries the string flag for ordinary URLs and nfile URLs,
+including long nfile entities and `?localOnly=1`. Metadata fragments do not
+change the bytes or root of a file; clients strip them from download routes.

package/nip94/index.js

@@ -0,0 +1,55 @@
+import { FILE_METADATA } from '../kind/index.js'
+import { nfileDecode } from '../nip19/index.js'
+import { ValidationError } from '../error/index.js'
+
+// NIP-94 fields plus the IRFS r/service and ThumbHash extensions. SHA-256
+// x/ox are optional in this profile; an MMR root is never substituted for x.
+export function decodeFileMetadata (event) {
+  if (event?.kind !== FILE_METADATA || typeof event.content !== 'string' || !Array.isArray(event.tags)) throw new ValidationError('INVALID_FILE_METADATA')
+  const field = name => {
+    const tags = event.tags.filter(tag => Array.isArray(tag) && tag[0] === name)
+    if (tags.length > 1 || (tags.length && (tags[0].length < 2 || typeof tags[0][1] !== 'string'))) throw new ValidationError('INVALID_FILE_METADATA_TAG')
+    return tags[0]?.[1]
+  }
+  const downloadTags = event.tags.filter(tag => Array.isArray(tag) && tag[0] === 'download')
+  const download = downloadTags[0]
+  if (downloadTags.length > 1 || (download && (download.length > 2 || (download.length === 2 && !['0', '1'].includes(download[1]))))) throw new ValidationError('INVALID_FILE_METADATA_DOWNLOAD')
+  const result = { url: field('url'), mime: field('m'), caption: event.content, download: download ? download.length === 1 ? '1' : download[1] : '0' }
+  let url
+  try { url = new URL(result.url) } catch { throw new ValidationError('INVALID_FILE_METADATA_URL') }
+  if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password) throw new ValidationError('INVALID_FILE_METADATA_URL')
+  if (typeof result.mime !== 'string' || !/^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/.test(result.mime)) throw new ValidationError('INVALID_FILE_METADATA_MIME')
+  for (const [tag, key] of [['r', 'root'], ['service', 'service'], ['thumbhash', 'thumbhash'], ['x', 'sha256'], ['ox', 'originalSha256'], ['alt', 'alt']]) {
+    const value = field(tag)
+    if (value !== undefined) result[key] = value
+  }
+  for (const key of ['root', 'sha256', 'originalSha256']) if (result[key] !== undefined && !/^[0-9a-f]{64}$/.test(result[key])) throw new ValidationError('INVALID_FILE_METADATA_HASH')
+  const size = field('size')
+  if (size !== undefined) {
+    if (!/^(0|[1-9][0-9]*)$/.test(size) || !Number.isSafeInteger(Number(size))) throw new ValidationError('INVALID_FILE_METADATA_SIZE')
+    result.size = Number(size)
+  }
+  const dim = field('dim')
+  if (dim !== undefined) {
+    if (!/^[1-9][0-9]*x[1-9][0-9]*$/.test(dim)) throw new ValidationError('INVALID_FILE_METADATA_DIMENSIONS')
+    ;[result.width, result.height] = dim.split('x').map(Number)
+    if (![result.width, result.height].every(Number.isSafeInteger)) throw new ValidationError('INVALID_FILE_METADATA_DIMENSIONS')
+  }
+  if (result.thumbhash !== undefined && !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(result.thumbhash)) throw new ValidationError('INVALID_FILE_METADATA_THUMBHASH')
+  if (url.origin === 'https://nostr.alt') {
+    const file = nfileDecode(url.pathname.slice(1))
+    if ((result.root && result.root !== file.root) || (file.mime && file.mime !== result.mime)) throw new ValidationError('FILE_METADATA_NFILE_MISMATCH')
+    result.filename = file.filename
+  }
+  return result
+}
+
+export function createFileMetadata ({ caption = '', created_at: createdAt = Math.floor(Date.now() / 1000), tags = [], ...metadata }) {
+  if (!Number.isSafeInteger(createdAt) || createdAt < 0 || !Array.isArray(tags)) throw new ValidationError('INVALID_FILE_METADATA')
+  if (metadata.download !== undefined && !['0', '1'].includes(metadata.download)) throw new ValidationError('INVALID_FILE_METADATA_DOWNLOAD')
+  const fields = [['download', metadata.download], ['url', metadata.url], ['m', metadata.mime], ['r', metadata.root], ['size', metadata.size], ['service', metadata.service], ['thumbhash', metadata.thumbhash], ['x', metadata.sha256], ['ox', metadata.originalSha256], ['alt', metadata.alt]]
+  if (metadata.width !== undefined || metadata.height !== undefined) fields.push(['dim', `${metadata.width}x${metadata.height}`])
+  const event = { kind: FILE_METADATA, created_at: createdAt, content: caption, tags: [...fields.filter(([, value]) => value !== undefined).map(([key, value]) => [key, String(value)]), ...tags.map(tag => [...tag])] }
+  decodeFileMetadata(event)
+  return event
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libp2r2p",
-  "version": "0.10.17",
+  "version": "0.10.19",
   "description": "Peer-to-relay-to-peer",
   "keywords": [
     "p2r2p",
@@ -25,6 +25,7 @@
     "idb",
     "idb-queue",
     "index.js",
+    "irfs",
     "key",
     "kind",
     "network",
@@ -35,6 +36,7 @@
     "nip44",
     "nip44-v3",
     "nip46",
+    "nip94",
     "nip96",
     "nip98",
     "nwt",
@@ -66,6 +68,7 @@
     "./event": "./event/index.js",
     "./idb": "./idb/index.js",
     "./idb-queue": "./idb-queue/index.js",
+    "./irfs": "./irfs/index.js",
     "./key": "./key/index.js",
     "./kind": "./kind/index.js",
     "./network": "./network/index.js",
@@ -76,6 +79,7 @@
     "./nip44": "./nip44/index.js",
     "./nip44-v3": "./nip44-v3/index.js",
     "./nip46": "./nip46/index.js",
+    "./nip94": "./nip94/index.js",
     "./nip96": "./nip96/index.js",
     "./nip98": "./nip98/index.js",
     "./nwt": "./nwt/index.js",
@@ -92,7 +96,8 @@
     "@noble/ciphers": "2.2.0",
     "@noble/curves": "2.2.0",
     "@noble/hashes": "2.2.0",
-    "@scure/base": "2.0.0"
+    "@scure/base": "2.0.0",
+    "nmmr": "2.0.0"
   },
   "devDependencies": {
     "eslint": "^9.39.5",

package/private-channel/index.js

@@ -903,10 +903,11 @@ export async function fetch ({ receiverSigner, iykcSigner, privateChannelSigner
   if (until != null) filter.until = until
   if (limit != null) filter.limit = limit
 
-  const { result: events } = await _getEvents(filter, relays, {
+  const { result } = await _getEvents(filter, relays, {
     timeout: 5000,
     timeoutAfterFirstEose: null
   })
+  const events = result.map(({ event }) => event)
   events.sort((a, b) => a.created_at - b.created_at)
   const processOuterEvent = createProcessor({ receiverSigner, iykcSigner, privateChannelSigner, privateChannelSignersByPubkey, privateChannelReaderSigner, privateChannelReaderSignersByPubkey, privateChannelReaderPubkey, privateChannelReaderPubkeysByPubkey, receiverPubkey, mode, modeByPubkey, onChunk, onEvent, onNymEvent, onSeedEvent, onContentKeyUsage, onError, receivedChunkTtlMs, receivedChunkTtlMsByPubkey, receivedChunkMaxBytes, receivedChunkIndexedDB, ignoredGroupTtlMs, ignoredGroupMaxEntries })
   try {
@@ -940,9 +941,10 @@ export function subscribe ({ receiverSigner, iykcSigner, privateChannelSigner =
 
   async function consumeEvents () {
     try {
-      for await (const outer of events) {
+      for await (const item of events) {
         if (controller.signal.aborted) continue
-        await processOuterEvent(outer)
+        if (item.type === 'error') onError?.(item.error)
+        else if (item.type === 'event') await processOuterEvent(item.event)
       }
     } catch (error) {
       if (!controller.signal.aborted && error?.message !== 'Aborted') onError?.(error)

package/relay/services/events.js

@@ -58,7 +58,7 @@ async function fetchLatestEventsByRelay (relayToAuthors, { kinds, dTagsByPubkey,
       const filter = { kinds, authors: dAuthors }
       if (d) filter['#d'] = [d]
       requests.push(getEvents(filter, [relay])
-        .then(response => ({ requested: new Set(dAuthors), events: response.result || [] })))
+        .then(response => ({ requested: new Set(dAuthors), events: (response.result || []).map(({ event }) => event) })))
     }
   }
 

package/relay/services/query.js

@@ -191,7 +191,7 @@ export function subscribeRelayListUpdates (pubkeys, {
 
   async function consumeRelayListUpdates () {
     try {
-      for await (const event of _eventsFeedGenerator({
+      for await (const item of _eventsFeedGenerator({
         kinds: [10002],
         authors
       }, relays, {
@@ -199,6 +199,9 @@ export function subscribeRelayListUpdates (pubkeys, {
         timeout: 5000,
         timeoutAfterFirstEose: null
       })) {
+        if (item.type === 'error') { console.error('relay-list watch failed:', item.error); continue }
+        if (item.type !== 'event') continue
+        const { event } = item
         if (closed || !authors.includes(event.pubkey)) continue
         const update = cacheRelayListEvent(event, { cacheMs, relayUrlPolicy })
         if (!update || !relayTypeChanged(update.changes, relayType)) continue
@@ -238,7 +241,7 @@ async function loadMissingRelays (missingPubkeys, {
   })
 
   const latestByPubkey = {}
-  for (const event of events || []) {
+  for (const { event } of events || []) {
     if (!missingPubkeys.includes(event.pubkey)) continue
     if (isNewerRelayListEvent(event, latestByPubkey[event.pubkey])) latestByPubkey[event.pubkey] = event
   }

package/relay/services/relay-pool.js

@@ -80,6 +80,17 @@ function getEventsTimeoutError () {
   return new Error('GET_EVENTS_TIMEOUT')
 }
 
+function asError (error) {
+  return error instanceof Error ? error : new Error(String(error))
+}
+
+function assertReadOptions (filter, timeouts) {
+  if (!filter || typeof filter !== 'object' || Array.isArray(filter)) throw new ValidationError('INVALID_FILTER')
+  for (const value of Object.values(timeouts)) {
+    if (value !== null && (!Number.isFinite(value) || value < 0)) throw new ValidationError('INVALID_RELAY_TIMEOUT')
+  }
+}
+
 function normalizedRelayUrls (relays) {
   const urls = []
   const seen = new Set()
@@ -88,7 +99,7 @@ function normalizedRelayUrls (relays) {
     const normalizedUrl = normalizeRelayUrl(relay)
     if (seen.has(normalizedUrl)) continue
     seen.add(normalizedUrl)
-    // Keep the caller's first spelling in reports and metadata while using the
+    // Keep the caller's first spelling in reports and envelopes while using the
     // canonical spelling for pooled connection ownership.
     urls.push(relay)
   }
@@ -342,127 +353,115 @@ export class RelayPool {
   // the operation deadline. Disabling cross-relay deduplication still suppresses
   // repeated ids from the same relay; callbacks remain immediate in both modes.
   async getEvents (filter, relays, { timeout = 5000, timeoutAfterFirstEose = 500, callback, signal, deduplicateAcrossRelays = true } = {}) {
+    assertReadOptions(filter, { timeout, timeoutAfterFirstEose })
     if (typeof deduplicateAcrossRelays !== 'boolean') throw new ValidationError('INVALID_DEDUPLICATE_ACROSS_RELAYS')
-    const urls = normalizedRelayUrls(relays)
-    if (!urls.length) return { result: [], errors: [], success: false }
     if (signal?.aborted) throw new Error('Aborted')
-
+    const urls = normalizedRelayUrls(relays)
     const subscriptions = new Map()
-    const pending = new Set(urls)
-    const normalCloseUrls = new Set()
+    const outcomes = new Map()
     const errors = []
     const events = []
     const eventIds = deduplicateAcrossRelays ? new Set() : null
-    let completed = 0
     let isResolved = false
     let eoseTimer = null
     let timeoutTimer = null
 
     return await new Promise((resolve, reject) => {
-      const closeSubscriptions = () => {
-        for (const sub of subscriptions.values()) sub.close()
-        subscriptions.clear()
-      }
-
       const cleanup = () => {
         clearTimeout(timeoutTimer)
         clearTimeout(eoseTimer)
         signal?.removeEventListener('abort', onAbort)
-        closeSubscriptions()
+        for (const sub of subscriptions.values()) sub.close()
+        subscriptions.clear()
       }
-
-      const finish = () => {
+      const fail = error => {
         if (isResolved) return
         isResolved = true
         cleanup()
-        resolve({
-          result: events,
-          errors,
-          success: events.length > 0 || completed > 0
-        })
+        reject(error)
       }
-
-      const finishIfComplete = () => {
-        if (pending.size === 0) finish()
+      const notify = item => {
+        try { callback?.(item) } catch (error) { fail(error) }
       }
-
-      const settleRelay = (url, reason) => {
-        if (isResolved || !pending.delete(url)) return
-        subscriptions.delete(url)
-        if (reason) {
-          errors.push({ reason, relay: url })
-          if (callback) callback({ type: 'error', error: reason, relay: url })
-        } else {
-          completed++
+      const settleRelay = (relay, status, error) => {
+        if (isResolved || outcomes.has(relay)) return
+        outcomes.set(relay, { relay, status, ...(error ? { error } : {}) })
+        if (error) {
+          errors.push({ relay, reason: error })
+          notify({ type: 'error', relay, error })
         }
-        finishIfComplete()
       }
-
-      const onAbort = () => {
+      const finish = (pendingStatus = 'cutoff') => {
+        if (isResolved) return
+        for (const url of urls) {
+          if (!outcomes.has(url)) settleRelay(url, pendingStatus, pendingStatus === 'timeout' ? getEventsTimeoutError() : undefined)
+        }
+        if (isResolved) return
+        const relays = urls.map(url => outcomes.get(url))
+        notify({ type: 'eose', relays })
         if (isResolved) return
         isResolved = true
         cleanup()
-        reject(new Error('Aborted'))
-      }
-
-      const timeoutPending = () => {
-        if (isResolved) return
-        for (const url of pending) {
-          errors.push({ reason: getEventsTimeoutError(), relay: url })
-        }
-        finish()
+        resolve({
+          result: events,
+          errors,
+          success: events.length > 0 || relays.some(({ status }) => ['eose', 'satisfied', 'closed'].includes(status)),
+          relays
+        })
       }
-
+      const finishIfComplete = () => { if (outcomes.size === urls.length) finish() }
+      const onAbort = () => fail(new Error('Aborted'))
       signal?.addEventListener('abort', onAbort, { once: true })
-      if (timeout !== null) timeoutTimer = maybeUnref(setTimeout(timeoutPending, timeout))
+      if (timeout !== null) timeoutTimer = maybeUnref(setTimeout(() => finish('timeout'), timeout))
+      if (!urls.length) { finish(); return }
 
       for (const url of urls) {
         const seenIds = eventIds ?? new Set()
         this.#getRelay(url).then(relay => {
-          if (isResolved || !pending.has(url)) return
+          if (isResolved || outcomes.has(url)) return
           let hasEvents = false
+          // Subscription callbacks may run before subscribe() returns.
           // eslint-disable-next-line prefer-const
           let sub
-
-          // Actual EOSE and filter satisfaction share the same graceful close path.
-          const handleEose = () => {
-            if (isResolved || !pending.has(url)) return
-            normalCloseUrls.add(url)
-            sub.close()
+          const complete = status => {
+            if (isResolved || outcomes.has(url)) return
+            settleRelay(url, status)
+            sub?.close()
+            subscriptions.delete(url)
             if (hasEvents && timeoutAfterFirstEose !== null && !eoseTimer && !isResolved) {
-              eoseTimer = maybeUnref(setTimeout(finish, timeoutAfterFirstEose))
+              eoseTimer = maybeUnref(setTimeout(() => finish('cutoff'), timeoutAfterFirstEose))
             }
+            finishIfComplete()
           }
-
-          const checkEarlyClose = makeEarlyCloseChecker(filter, handleEose)
+          const checkEarlyClose = makeEarlyCloseChecker(filter, () => complete('satisfied'))
           sub = relay.subscribe([filter], {
-            onevent: (event) => {
-              if (isResolved || !pending.has(url)) return
+            onevent: event => {
+              if (isResolved || outcomes.has(url)) return
               hasEvents = true
               if (!event?.id || !seenIds.has(event.id)) {
                 if (event?.id) seenIds.add(event.id)
-                event.meta = { relay: url }
-                events.push(event)
-                if (callback) callback({ type: 'event', event, relay: url })
+                events.push({ event, relay: url })
+                notify({ type: 'event', event, relay: url })
               }
               checkEarlyClose(event)
             },
             oninvalidevent: () => {
-              if (!isResolved && pending.has(url)) checkEarlyClose()
+              if (!isResolved && !outcomes.has(url)) checkEarlyClose()
             },
             onclose: error => {
-              const reason = normalCloseUrls.delete(url) || error === undefined
-                ? null
-                : error instanceof Error ? error : new Error(String(error))
-              settleRelay(url, reason)
+              if (isResolved || outcomes.has(url)) return
+              const reason = error === undefined ? undefined : asError(error)
+              settleRelay(url, reason ? 'error' : 'closed', reason)
+              subscriptions.delete(url)
+              finishIfComplete()
             },
-            oneose: handleEose
+            oneose: () => complete('eose')
           })
-          if (isResolved || !pending.has(url)) sub.close()
+          if (isResolved || outcomes.has(url)) sub.close()
           else subscriptions.set(url, sub)
         }).catch(error => {
-          const reason = error instanceof Error ? error : new Error(String(error))
-          settleRelay(url, reason)
+          settleRelay(url, 'error', asError(error))
+          finishIfComplete()
         })
       }
     })
@@ -472,39 +471,40 @@ export class RelayPool {
     const queue = []
     let p = Promise.withResolvers()
     let isDone = false
-
-    const userCallback = options.callback
+    let failure
+    const controller = new AbortController()
     const callback = item => {
       queue.push(item)
-      if (userCallback) userCallback(item)
       p.resolve()
       p = Promise.withResolvers()
+      options.callback?.(item)
     }
-
-    // A drain stops receive callbacks without aborting consumption of this queue.
-    const networkSignal = options._stopSignal
-      ? AbortSignal.any([options._stopSignal, ...(options.signal ? [options.signal] : [])])
-      : options.signal
-    const methodPromise = this.getEvents(filter, relays, { ...options, signal: networkSignal, callback })
-      .catch(err => { if (err?.message !== 'Aborted') console.error('Error in getEvents:', err) })
-      .finally(() => {
-        isDone = true
-        p.resolve()
-      })
-
-    // eslint-disable-next-line no-unmodified-loop-condition
-    while (!isDone || queue.length > 0) {
-      if (options.signal?.aborted) break
-      if (queue.length > 0) yield queue.shift()
-      else await p.promise
+    const signal = AbortSignal.any([controller.signal, ...[options.signal, options._stopSignal].filter(Boolean)])
+    // Attach rejection handling immediately, but propagate general failures to
+    // the consumer after accepted deliveries instead of swallowing them.
+    const methodPromise = this.getEvents(filter, relays, { ...options, signal, callback })
+      .catch(error => { if (!signal.aborted) failure = error })
+      .finally(() => { isDone = true; p.resolve() })
+    try {
+      // eslint-disable-next-line no-unmodified-loop-condition
+      while (!isDone || queue.length > 0) {
+        if (options.signal?.aborted) return
+        if (queue.length > 0) yield queue.shift()
+        else await p.promise
+      }
+      const report = await methodPromise
+      if (failure) throw failure
+      return report
+    } finally {
+      controller.abort()
+      queue.length = 0
     }
-
-    return await methodPromise
   }
 
   // Returns a strictly-live stream. `ready` reports the first initial EOSE window,
   // while `readyRelays` follows relays that are currently past their own EOSE.
   getLiveEventsGenerator (filter, relays, options = {}) {
+    assertReadOptions(filter, { timeout: options.timeout === undefined ? 5000 : options.timeout, timeoutAfterFirstEose: options.timeoutAfterFirstEose === undefined ? 500 : options.timeoutAfterFirstEose })
     const ready = Promise.withResolvers()
     const readyRelays = new Set()
     const stream = drainableStream(options => this.#getLiveEventsGenerator(filter, relays, options, { ready, readyRelays }), options)
@@ -528,6 +528,7 @@ export class RelayPool {
   async * #getLiveEventsGenerator (filter, relays, {
     signal,
     _stopSignal,
+    timeout = 5000,
     timeoutAfterFirstEose = 500,
     timeoutForReconnectGap = 5000,
     timeoutAfterFirstReconnectGapEose = 500,
@@ -542,7 +543,8 @@ export class RelayPool {
     const liveSubs = new Map() // url → live sub
     const retryTimers = new Map()
     const initialPending = new Set(urls)
-    const initialErrors = []
+    const initialOutcomes = new Map()
+    let readyTimeout = null
     let readyTimer = null
     let isReady = false
 
@@ -564,14 +566,28 @@ export class RelayPool {
     const seenIds = new Set()
 
     let untilTimer = null
-    const finishReady = () => {
+    const enqueue = item => {
+      queue.push(item)
+      p.resolve()
+      p = Promise.withResolvers()
+    }
+    const finishReady = (pendingStatus = 'cutoff', emit = true) => {
       if (isReady) return
       isReady = true
       clearTimeout(readyTimer)
+      clearTimeout(readyTimeout)
+      for (const relay of initialPending) {
+        const error = pendingStatus === 'timeout' ? getEventsTimeoutError() : undefined
+        initialOutcomes.set(relay, { relay, status: pendingStatus, ...(error ? { error } : {}) })
+        if (error && emit) enqueue({ type: 'error', relay, error })
+      }
+      initialPending.clear()
+      const relays = urls.map(url => initialOutcomes.get(url))
       ready.resolve(Object.freeze({
         relays: Object.freeze([...readyRelays]),
-        errors: Object.freeze([...initialErrors])
+        errors: Object.freeze(relays.filter(item => item.error).map(({ relay, error }) => ({ relay, reason: error })))
       }))
+      if (emit) enqueue({ type: 'eose', relays })
     }
 
     const teardown = (drain = false) => {
@@ -580,7 +596,7 @@ export class RelayPool {
       isDone = true
       if (!drain) queue.length = 0
       clearTimeout(untilTimer)
-      finishReady()
+      finishReady('closed', false)
       gapAc.abort()
       for (const timer of retryTimers.values()) clearTimeout(timer)
       retryTimers.clear()
@@ -597,14 +613,11 @@ export class RelayPool {
         seenIds.add(event.id)
       }
       if (event.created_at > (lastSeenAt ?? 0)) lastSeenAt = event.created_at
-      event.meta = { relay: url }
-      queue.push(event)
-      p.resolve()
-      p = Promise.withResolvers()
+      enqueue({ type: 'event', event, relay: url })
     }
 
     if (signal?.aborted || _stopSignal?.aborted) {
-      finishReady()
+      finishReady('closed', false)
       return
     }
     const abort = () => teardown()
@@ -612,24 +625,35 @@ export class RelayPool {
     signal?.addEventListener('abort', abort, { once: true })
     _stopSignal?.addEventListener('abort', stop, { once: true })
 
+    if (timeout !== null) readyTimeout = maybeUnref(setTimeout(() => finishReady('timeout'), timeout))
+
     const maybeFinishInitialReady = () => {
       if (initialPending.size === 0) finishReady()
     }
 
     const markInitialEose = (url) => {
       readyRelays.add(url)
-      if (isReady) return
-      initialPending.delete(url)
+      if (isReady || !initialPending.delete(url)) return
+      initialOutcomes.set(url, { relay: url, status: 'eose' })
       if (timeoutAfterFirstEose !== null && !readyTimer) {
-        readyTimer = maybeUnref(setTimeout(finishReady, timeoutAfterFirstEose))
+        readyTimer = maybeUnref(setTimeout(() => finishReady('cutoff'), timeoutAfterFirstEose))
       }
       maybeFinishInitialReady()
     }
 
-    const markInitialError = (url, reason) => {
-      if (!initialPending.delete(url)) return
-      initialErrors.push({ relay: url, reason })
-      maybeFinishInitialReady()
+    const reportFailure = (url, error) => {
+      if (isDone) return
+      enqueue({ type: 'error', relay: url, error })
+      if (!isReady && initialPending.delete(url)) {
+        initialOutcomes.set(url, { relay: url, status: 'error', error })
+        maybeFinishInitialReady()
+      }
+    }
+    const reportClosed = url => {
+      if (!isReady && initialPending.delete(url)) {
+        initialOutcomes.set(url, { relay: url, status: 'closed' })
+        maybeFinishInitialReady()
+      }
     }
 
     const scheduleReconnect = (url, reconnectDelay) => {
@@ -645,7 +669,7 @@ export class RelayPool {
     // Schedule teardown when the wall clock reaches filter.until
     if (filterUntil !== null) {
       const msUntil = filterUntil * 1000 - Date.now()
-      untilTimer = maybeUnref(setTimeout(() => teardown(true), Math.max(0, msUntil)))
+      untilTimer = maybeUnref(setTimeout(() => { finishReady('closed'); teardown(true) }, Math.max(0, msUntil)))
     }
 
     // Runs a reconnect gap fill for a single relay and returns a promise that resolves
@@ -662,9 +686,10 @@ export class RelayPool {
       return (async () => {
         for await (const item of gapGen) {
           if (item?.type === 'event') pushEvent(item.event, url, true)
+          else if (item?.type === 'error' && !isDone) enqueue(item)
         }
       })().catch(err => {
-        if (!isDone) console.error(`Reconnect gap fill error for ${url}:`, err)
+        reportFailure(url, asError(err))
       })
     }
 
@@ -697,11 +722,9 @@ export class RelayPool {
             if (liveSubs.get(url) === liveSub) liveSubs.delete(url)
             else if (liveSubs.has(url)) return
             readyRelays.delete(url)
-            if (!liveEose && !isDone) {
-              const reason = error instanceof Error
-                ? error
-                : new Error(error ? String(error) : 'LIVE_SUBSCRIPTION_CLOSED')
-              markInitialError(url, reason)
+            if (!isDone) {
+              if (error !== undefined) reportFailure(url, asError(error))
+              else if (!liveEose) reportClosed(url)
             }
             if (isDone) return
             scheduleReconnect(url, reconnectDelay)
@@ -728,15 +751,19 @@ export class RelayPool {
       }).catch(err => {
         readyRelays.delete(url)
         const reason = err instanceof Error ? err : new Error(String(err))
-        markInitialError(url, reason)
+        reportFailure(url, reason)
         if (isDone) return
-        console.error(`Live subscription error at ${url}:`, reason)
         scheduleReconnect(url, reconnectDelay)
       })
     }
 
     if (!urls.length) {
       finishReady()
+      try { yield queue.shift() } finally {
+        teardown()
+        signal?.removeEventListener('abort', abort)
+        _stopSignal?.removeEventListener('abort', stop)
+      }
       return
     }
 
@@ -773,6 +800,7 @@ export class RelayPool {
   //
   // All underlying generators are injectable for testing.
   getEventsFeedGenerator (filter, relays, options = {}) {
+    assertReadOptions(filter, { timeout: options.timeout === undefined ? 5000 : options.timeout, timeoutAfterFirstEose: options.timeoutAfterFirstEose === undefined ? 500 : options.timeoutAfterFirstEose })
     return drainableStream(options => this.#getEventsFeedGenerator(filter, relays, options), options)
   }
 
@@ -790,14 +818,14 @@ export class RelayPool {
       const gen = _eventsGenerator(filter, relays, { timeout, timeoutAfterFirstEose, signal, _stopSignal })
       for await (const item of gen) {
         if (signal.aborted) return
-        if (item?.type === 'event') yield item.event
+        yield item
       }
       return
     }
 
     // limit:0 means "no stored events, live only" — skip the initial fetch.
     if (filter.limit === 0) {
-      for await (const event of _liveGenerator(filter, relays, { signal, _stopSignal })) {
+      for await (const event of _liveGenerator(filter, relays, { timeout, timeoutAfterFirstEose, signal, _stopSignal })) {
         if (signal.aborted) return
         yield event
       }
@@ -808,19 +836,22 @@ export class RelayPool {
     // buffering incoming events before we query stored ones.
     // Relays always send stored matching events before EOSE (unless limit:0),
     // so the initial fetch + buffering is always needed.
-    const liveGen = _liveGenerator(filter, relays, { signal, _stopSignal })
+    const liveGen = _liveGenerator(filter, relays, { timeout, timeoutAfterFirstEose, signal, _stopSignal })
     const liveBuffer = []
     let liveDone = false
+    let liveFailure
     let liveWake = Promise.withResolvers()
 
     const bgLoop = (async () => {
       try {
         for await (const event of liveGen) {
           if (signal.aborted) break
-          liveBuffer.push(event)
+          if (event.type !== 'eose') liveBuffer.push(event)
           liveWake.resolve()
           liveWake = Promise.withResolvers()
         }
+      } catch (error) {
+        liveFailure = error
       } finally {
         liveDone = true
         liveWake.resolve()
@@ -836,21 +867,23 @@ export class RelayPool {
         if (signal.aborted) return
         if (item?.type === 'event' && !seenIds.has(item.event.id)) {
           seenIds.add(item.event.id)
-          yield item.event
-        }
+          yield item
+        } else if (item?.type !== 'event') yield item
       }
 
       // Flush buffered live events that arrived during the initial fetch, deduping
       // against stored ones (overlap is possible around the fetch's until boundary)
       while (liveBuffer.length > 0) {
         if (signal.aborted) return
-        const event = liveBuffer.shift()
-        if (!seenIds.has(event.id)) {
-          seenIds.add(event.id)
-          yield event
+        const item = liveBuffer.shift()
+        if (item.type !== 'event' || !seenIds.has(item.event.id)) {
+          if (item.type === 'event') seenIds.add(item.event.id)
+          yield item
         }
       }
 
+      seenIds.clear()
+
       // Yield subsequent live events directly — no more overlap with stored events
       // eslint-disable-next-line no-unmodified-loop-condition
       while (!liveDone || liveBuffer.length > 0) {
@@ -860,6 +893,7 @@ export class RelayPool {
         }
         if (!liveDone) await liveWake.promise
       }
+      if (liveFailure) throw liveFailure
     } finally {
       await liveGen.return()
       await bgLoop