libp2r2p 0.10.17 → 0.10.18

package/README.md

@@ -555,3 +555,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/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/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.18",
   "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",