libp2r2p 0.10.28 → 0.11.1

package/private-messenger/event-store/helpers/codec.js

@@ -0,0 +1,136 @@
+import { sha256 } from '@noble/hashes/sha2.js'
+import { bytesToHex } from '../../../base16/index.js'
+import { ValidationError } from '../../../error/index.js'
+import { isValidEvent } from '../../../event/index.js'
+
+const encoder = new TextEncoder()
+const HEX = /^[0-9a-f]{64}$/
+const DAY = 86400
+export const PREFIX = 'libp2r2p:recovery:'
+export const digest = value => bytesToHex(sha256(encoder.encode(JSON.stringify(value))))
+const fail = () => { throw new ValidationError('INVALID_RECOVERY_RECORD') }
+const hex = value => { if (!HEX.test(value || '')) fail(); return value }
+const integer = value => { const n = Number(value); if (!Number.isSafeInteger(n) || n < 0 || String(n) !== String(value)) fail(); return n }
+// Protect original values from NostrDB's reserved CRDT metadata syntax.
+const escape = value => String(value).replace(/^%/, '%25').replace(/^~/, '%7E')
+const unescape = value => value.startsWith('%25') ? `%${value.slice(3)}` : value.startsWith('%7E') ? `~${value.slice(3)}` : value
+export function days (since, until) {
+  const first = Math.floor(since / DAY), last = Math.floor(until / DAY)
+  return last - first >= 32 ? ['*'] : Array.from({ length: Math.max(0, last - first + 1) }, (_, i) => String(first + i))
+}
+export function selector (type, row) {
+  return digest(type === 'grant'
+    ? ['grant', row.controlChannelPubkey, row.fileChannelPubkey, row.receiverPubkey]
+    : row.fileChannelPubkey
+      ? ['file', row.controlChannelPubkey, row.fileChannelPubkey, row.receiverPubkey, row.chunkIndex]
+      : ['seed', row.channelPubkey, row.receiverPubkey || ''])
+}
+function body (type, row) {
+  const tags = []
+  const add = (name, ...values) => tags.push([name, ...values.map(escape)])
+  const expires = integer(row.expiresAt)
+  if (type === 'grant') {
+    add('c', hex(row.controlChannelPubkey)); add('channel', hex(row.fileChannelPubkey))
+    add('peer', hex(row.peerPubkey)); add('p', hex(row.receiverPubkey)); add('root', hex(row.root))
+    if (row.size !== undefined) { if (!integer(row.size)) fail(); add('size', row.size) }
+    add('shared', integer(row.sharedAt))
+    if (expires <= row.sharedAt) fail()
+  } else if (type === 'seed') {
+    add('c', hex(row.fileChannelPubkey || row.channelPubkey))
+    add('type', row.recordType)
+    if (row.recordType === 'routerEnvelopeRow_v1') {
+      const payload = JSON.parse(row.payloadRow), envelope = JSON.parse(row.row)
+      if (!Array.isArray(payload) || payload.length !== 1 || typeof payload[0] !== 'string' || !Array.isArray(envelope) || envelope.length < 2 || envelope.length > 4 || !envelope.every(v => typeof v === 'string') || envelope[0] !== row.receiverPubkey) fail()
+      add('p', hex(row.receiverPubkey))
+      if (row.router?.kind !== 26300) fail()
+      add('router', hex(row.router.pubkey), integer(row.router.created_at))
+      if (!Array.isArray(row.router.tags)) fail()
+      row.router.tags.filter(tag => tag[0] !== 'c').forEach((tag, i) => {
+        if (!Array.isArray(tag) || !tag.length || !tag.every(v => typeof v === 'string')) fail()
+        add('router-tag', i, ...tag)
+      })
+      add('payload', payload[0]); add('key', envelope[1])
+      if (envelope.length > 2) add('iykc', ...envelope.slice(2))
+      if (row.innerEventId) add('event', hex(row.innerEventId))
+      const first = integer(row.firstSeenAt ?? row.router.created_at), last = integer(row.lastSeenAt ?? row.router.created_at)
+      if (first > last) fail()
+      add('range', first, last)
+      if (row.fileChannelPubkey) {
+        add('file', hex(row.controlChannelPubkey), hex(row.peerPubkey), hex(row.root))
+        add('received', integer(row.receivedAt))
+        const index = row.router.tags.find(tag => tag[0] === 'i')?.[1]
+        if (integer(index) !== row.chunkIndex) fail()
+      }
+    } else if (row.recordType === 'nymCarrier_v1') {
+      if (!row.carriers?.length) fail()
+      row.carriers.forEach((carrier, i) => {
+        if (!isValidEvent(carrier) || carrier.kind !== 26400) fail()
+        add('carrier', i, carrier.kind, carrier.pubkey, carrier.created_at, carrier.id, carrier.sig, carrier.content)
+        carrier.tags.forEach((tag, j) => add('carrier-tag', `${i}:${j}`, ...tag))
+      })
+      const at = Math.max(...row.carriers.map(c => c.created_at))
+      add('range', at, at)
+    } else fail()
+  } else fail()
+  add('expiration', expires)
+  return tags
+}
+export function encodeRecord (type, row) {
+  try {
+    const tags = body(type, row)
+    const id = digest([type, tags])
+    const range = tags.find(t => t[0] === 'range')
+    const recordedAt = type === 'grant' ? row.sharedAt : row.fileChannelPubkey ? row.receivedAt : Number(range[2])
+    return { kind: 30078, created_at: recordedAt, tags: [['d', `${PREFIX}${type}:${id}`], ['t', `${PREFIX}${type}`], ['s', selector(type, row)], ...tags, ...(type === 'seed' && !row.fileChannelPubkey ? days(Number(range[1]), Number(range[2])).map(day => ['D', day]) : [])], content: '' }
+  } catch (error) { if (error instanceof ValidationError) throw error; fail() }
+}
+export function decodeRecord (event) {
+  try {
+    if (event?.kind !== 30078 || event.content !== '' || !Array.isArray(event.tags)) fail()
+    const tags = event.tags.filter(t => !['~', 'z', 'zz'].includes(t[0])).map(t => {
+      if (!Array.isArray(t) || !t.every(v => typeof v === 'string')) fail()
+      return t.filter((v, i) => i === 0 || !v.startsWith('~')).map((v, i) => i ? unescape(v) : v)
+    })
+    const one = (name, required = true) => {
+      const matches = tags.filter(t => t[0] === name)
+      if (matches.length > 1 || (required && !matches.length)) fail()
+      return matches[0]?.slice(1)
+    }
+    const coordinate = one('d')[0]
+    const type = coordinate?.startsWith(`${PREFIX}grant:`) ? 'grant' : coordinate?.startsWith(`${PREFIX}seed:`) ? 'seed' : fail()
+    const row = { expiresAt: integer(one('expiration')[0]), recordId: coordinate }
+    if (type === 'grant') {
+      Object.assign(row, { controlChannelPubkey: one('c')[0], fileChannelPubkey: one('channel')[0], peerPubkey: one('peer')[0], receiverPubkey: one('p')[0], root: one('root')[0], sharedAt: integer(one('shared')[0]) })
+      const size = one('size', false); if (size) row.size = integer(size[0])
+    } else {
+      row.channelPubkey = one('c')[0]; row.recordType = one('type')[0]
+      const range = one('range'); row.firstSeenAt = integer(range[0]); row.lastSeenAt = integer(range[1])
+      if (row.recordType === 'routerEnvelopeRow_v1') {
+        row.receiverPubkey = one('p')[0]
+        const router = one('router')
+        const list = tags.filter(t => t[0] === 'router-tag').sort((a, b) => Number(a[1]) - Number(b[1]))
+        list.forEach((t, i) => { if (t[1] !== String(i)) fail() })
+        row.router = { kind: 26300, pubkey: router[0], created_at: integer(router[1]), tags: list.map(t => t.slice(2)) }
+        row.payloadRow = JSON.stringify(one('payload'))
+        const envelope = [row.receiverPubkey, ...one('key'), ...(one('iykc', false) || [])]
+        row.row = JSON.stringify(envelope); row.iykcPubkey = envelope[2] || ''
+        row.innerEventId = one('event', false)?.[0] || ''
+        const file = one('file', false)
+        if (file) Object.assign(row, { controlChannelPubkey: file[0], peerPubkey: file[1], root: file[2], fileChannelPubkey: row.channelPubkey, chunkIndex: integer(row.router.tags.find(t => t[0] === 'i')?.[1]), receivedAt: integer(one('received')[0]) })
+      } else if (row.recordType === 'nymCarrier_v1') {
+        row.carriers = tags.filter(t => t[0] === 'carrier').sort((a, b) => Number(a[1]) - Number(b[1])).map((t, i) => {
+          if (t[1] !== String(i)) fail()
+          const original = tags.filter(v => v[0] === 'carrier-tag' && v[1].startsWith(`${i}:`)).sort((a, b) => Number(a[1].split(':')[1]) - Number(b[1].split(':')[1]))
+          original.forEach((v, j) => { if (v[1] !== `${i}:${j}`) fail() })
+          return { kind: integer(t[2]), pubkey: t[3], created_at: integer(t[4]), id: t[5], sig: t[6], content: t[7], tags: original.map(v => v.slice(2)) }
+        })
+      } else fail()
+    }
+    const encoded = encodeRecord(type, row)
+    // Compare the complete semantic tag multiset, including derived indices.
+    const canonical = list => list.map(t => JSON.stringify(t)).sort()
+    const cleanEncoded = encoded.tags.map(t => t.map((v, i) => i ? unescape(v) : v))
+    if (JSON.stringify(canonical(tags)) !== JSON.stringify(canonical(cleanEncoded))) fail()
+    return { type, row }
+  } catch (error) { if (error instanceof ValidationError) throw error; fail() }
+}

package/private-messenger/event-store/index.js

@@ -0,0 +1,176 @@
+import NMMR from 'nmmr'
+import { chunkStream } from '../file/helpers/stream.js'
+import { ValidationError } from '../../error/index.js'
+import { decodeIrfsChunk } from '../../irfs/index.js'
+import { encodeRecord, decodeRecord, selector, days, PREFIX } from './helpers/codec.js'
+export { encodeRecord as encodeRecoveryRecord, decodeRecord as decodeRecoveryRecord } from './helpers/codec.js'
+
+const nowSeconds = () => Math.floor(Date.now() / 1000)
+function assertOptions (eventStore, signer) {
+  if (!eventStore?.query || !eventStore?.addPersonalCopy || !signer?.getPublicKey || !signer?.obfuscate || !signer?.nip44v3?.decrypt) throw new ValidationError('INVALID_EVENT_STORE_OPTIONS')
+}
+function committed (value) {
+  if (!value?.result?.ok) throw Object.assign(new Error(value?.result?.message || 'EVENT_STORE_WRITE_FAILED'), { code: value?.result?.code || 'EVENT_STORE_WRITE_FAILED' })
+  return value
+}
+// Bound each page and retain only the IDs at the timestamp boundary.
+async function * pages (eventStore, filter, signal) {
+  let until = filter.until, excluded = []
+  while (true) {
+    signal?.throwIfAborted()
+    const { results } = await eventStore.query({ ...filter, ...(until === undefined ? {} : { until }), ...(excluded.length ? { '!ids': excluded } : {}), limit: 128, search: 'sort:desc' })
+    if (!results.length) return
+    for (const event of results) { signal?.throwIfAborted(); yield event }
+    const boundary = results.at(-1).created_at
+    const ids = results.filter(e => e.created_at === boundary).map(e => e.id)
+    excluded = boundary === until ? [...excluded, ...ids] : ids
+    until = boundary
+    if (results.length < 128) return
+  }
+}
+export function createPersonalCopyRecoveryStorage ({ eventStore, signer, now = nowSeconds }) {
+  assertOptions(eventStore, signer)
+  let closed = false
+  let opening
+  const ready = () => (opening ??= Promise.all([signer.getPublicKey(), signer.obfuscate('', '1006', '')]).catch(error => { opening = undefined; throw error }))
+  const check = () => { if (closed) throw new Error('RECOVERY_STORAGE_CLOSED') }
+  const mirrors = new Map(), grants = new Map()
+  const mirror = (name, value) => {
+    const key = `${name}:${value}`
+    if (!mirrors.has(key)) {
+      if (mirrors.size >= 256) mirrors.delete(mirrors.keys().next().value)
+      const promise = Promise.resolve().then(() => signer.obfuscate(value, '1006', `#${name}`)).catch(error => { if (mirrors.get(key) === promise) mirrors.delete(key); throw error })
+      mirrors.set(key, promise)
+    }
+    return mirrors.get(key)
+  }
+  async function filterFor (type) {
+    check()
+    const [owner, context] = await ready()
+    return { kinds: [1006], authors: [owner], '#k': ['30078'], '#c': [context], '#v': ['0', '1'], '&o': [await mirror('t', `${PREFIX}${type}`)] }
+  }
+  async function read (wrapper) {
+    check()
+    // Query the store before every use; only decryption of an immutable wrapper
+    // is cached. A removed wrapper therefore cannot authorize another reply.
+    const cached = grants.get(wrapper.id)
+    if (cached) return { ...cached, row: { ...cached.row }, wrapper }
+    const [owner] = await ready()
+    const bytes = await signer.nip44v3.decrypt(owner, 30078, '', wrapper.content)
+    const decoded = decodeRecord(JSON.parse(new TextDecoder().decode(bytes)))
+    if (decoded.type === 'grant') {
+      if (grants.size >= 128) grants.delete(grants.keys().next().value)
+      grants.set(wrapper.id, { ...decoded, row: { ...decoded.row } })
+    }
+    return { ...decoded, wrapper }
+  }
+  async function * records (type, query = {}) {
+    const filter = await filterFor(type)
+    if (query.recordId) filter['&o'].push(await mirror('d', query.recordId))
+    else if (query.fileChannelPubkey && query.receiverPubkey) {
+      const indices = type === 'seed' ? query.indices : [undefined]
+      if (indices?.length) filter['#o'] = await Promise.all(indices.map(chunkIndex => mirror('s', selector(type, { ...query, chunkIndex }))))
+    } else if (query.channelPubkey) {
+      filter['&o'].push(await mirror('c', query.channelPubkey))
+      if (Number.isFinite(query.since) && Number.isFinite(query.until)) {
+        const buckets = days(query.since, query.until)
+        // A wide query must include daily records too, so skip the day prefilter.
+        if (!buckets.includes('*')) filter['#o'] = await Promise.all([...buckets, '*'].map(d => mirror('D', d)))
+      }
+    }
+    for await (const wrapper of pages(eventStore, filter, query.signal)) {
+      const { row } = await read(wrapper)
+      if (query.channelPubkey && row.channelPubkey !== query.channelPubkey) continue
+      if (query.controlChannelPubkey && row.controlChannelPubkey !== query.controlChannelPubkey) continue
+      if (query.fileChannelPubkey && row.fileChannelPubkey !== query.fileChannelPubkey) continue
+      if (query.receiverPubkey && row.receiverPubkey && row.receiverPubkey !== query.receiverPubkey) continue
+      if (query.indices && !query.indices.includes(row.chunkIndex)) continue
+      if (query.since !== undefined && row.lastSeenAt < query.since) continue
+      if (query.until !== undefined && row.firstSeenAt > query.until) continue
+      if (!query.includeExpired && row.expiresAt <= now()) continue
+      yield { row, wrapper }
+    }
+  }
+  function store (type) {
+    return {
+      async put (row) {
+        check()
+        const event = encodeRecord(type, row)
+        if (row.expiresAt <= now()) return
+        const recordId = event.tags[0][1]
+        const existing = records(type, { recordId, includeExpired: true })
+        try { const first = await existing.next(); if (!first.done) return first.value.row } finally { await existing.return() }
+        const saved = committed(await eventStore.addPersonalCopy(event, { context: '' }))
+        // A pending kind-5 tombstone can reject the insertion; do not cache it.
+        if (saved.result.stored === false && saved.result.code === 'blocked') return
+        return { ...row, recordId }
+      },
+      async * iterate (query = {}) { for await (const { row } of records(type, query)) yield row },
+      async has (row) {
+        const iterator = records(type, { recordId: row.recordId || encodeRecord(type, row).tags[0][1] })
+        try { return !(await iterator.next()).done } finally { await iterator.return() }
+      },
+      async removeLocal (query = {}) {
+        for await (const { wrapper } of records(type, { ...query, includeExpired: true })) await eventStore.remove([['e', wrapper.id]])
+      },
+      async prune ({ now: at = now() } = {}) {
+        // Personal copies preserve the inner expiration on their signed wrapper.
+        // Cleanup must not decrypt the entire seed archive on startup/request.
+        for await (const wrapper of pages(eventStore, await filterFor(type))) {
+          const expiry = Number(wrapper.tags.find(tag => tag[0] === 'expiration')?.[1])
+          if (Number.isSafeInteger(expiry) && expiry <= at) await eventStore.remove([['e', wrapper.id]])
+        }
+      },
+      async revoke (rows) {
+        check()
+        const [owner] = await ready()
+        for (let i = 0; i < rows.length; i += 100) {
+          const group = rows.slice(i, i + 100).filter(row => row.expiresAt > now())
+          if (!group.length) continue
+          const tags = []; let createdAt = now(), expiresAt = 0
+          for (const row of group) {
+            const recordId = row.recordId || encodeRecord(type, row).tags[0][1]
+            for await (const { wrapper } of records(type, { recordId })) createdAt = Math.max(createdAt, wrapper.created_at)
+            tags.push(['a', `30078:${owner}:${recordId}`]); expiresAt = Math.max(expiresAt, row.expiresAt)
+          }
+          if (expiresAt <= createdAt) continue
+          committed(await eventStore.addPersonalCopy({ kind: 5, created_at: createdAt, tags: [...tags, ['k', '30078'], ['expiration', String(expiresAt)]], content: '' }, { context: '' }))
+        }
+      }
+    }
+  }
+  const seeds = store('seed'), authorizations = store('grant')
+  authorizations.find = async query => {
+    let best
+    for await (const row of authorizations.iterate(query)) if (!best || row.sharedAt > best.sharedAt || (row.sharedAt === best.sharedAt && (row.expiresAt < best.expiresAt || (row.expiresAt === best.expiresAt && row.recordId < best.recordId)))) best = row
+    return best
+  }
+  return { seeds, authorizations, close () { closed = true; mirrors.clear(); grants.clear() } }
+}
+
+export function createEventStoreChunkStorage ({ eventStore }) {
+  if (!eventStore?.query || !eventStore?.addPersonalCopy) throw new ValidationError('INVALID_EVENT_STORE_OPTIONS')
+  const storage = {
+    async read (root, index) {
+      const { results } = await eventStore.query({ kinds: [34601], '#d': [NMMR.deriveChunkId(root, index)], limit: 1 })
+      return results[0]
+    },
+    async save (event, descriptor) {
+      const decoded = decodeIrfsChunk(event)
+      if (decoded.root !== descriptor.root) throw new ValidationError('FILE_CHUNK_DESCRIPTOR_MISMATCH')
+      committed(await eventStore.addPersonalCopy({ kind: 34601, created_at: event.created_at, tags: structuredClone(event.tags), content: event.content }, { context: `dm:${descriptor.peerPubkey}` }))
+    }
+  }
+  storage.stream = (descriptor, { signal } = {}) => chunkStream({ read: storage.read, ...descriptor, signal })
+  return storage
+}
+export function createEventStoreMessageStorage ({ eventStore }) {
+  if (!eventStore?.addPersonalCopy) throw new ValidationError('INVALID_EVENT_STORE_OPTIONS')
+  return {
+    async save (event, { peerPubkey, hearsay = false } = {}) {
+      const result = await eventStore.addPersonalCopy(event, { context: `dm:${peerPubkey}`, hearsay })
+      if (!result?.result?.ok && !['blocked', 'expired'].includes(result?.result?.code)) committed(result)
+      return result
+    }
+  }
+}

package/private-messenger/file/README.md

@@ -0,0 +1,152 @@
+# Private file transfer
+
+`createPrivateFileTransfer({ messenger, resolveChannel, storage, onError })`
+creates one account coordinator attached to an initialized PrivateMessenger.
+It does not create permanent watched channels for files. The application resolves
+channel signers. An optional adapter supplies `storage.read(root, index, descriptor)`
+and `storage.save(event, descriptor)`; otherwise the library uses its bounded local
+cache. `save` must resolve only after persistence.
+The descriptor is `{ controlChannelPubkey, peerPubkey, root, size?, sharedAt? }`.
+`sharedAt` is a stable sharing timestamp, never a read/retry timestamp.
+
+For one-to-one chats, resolve the signer with
+`withSharedKey(peerPubkey, fileChannelInfo(root))`: the canonical context is
+`dm:media:<lowercase MMR root>`. Original and thumbnail roots use separate
+channels under the same convention. Do not put this context in a public tag or
+append it to the thumbnail URL. This is not a group-key derivation scheme.
+
+- `register(descriptor)` resolves and checks the file channel without watching it.
+- `authorizeSeeding(descriptor, { receiverPubkeys, sharedAt })` durably grants
+  the listed identities indexed recovery of this root on this control/data pair.
+  The application calls it for an explicit share, using its persisted message
+  timestamp (standalone 1063 uses its own timestamp). Registration, cache hits
+  and incoming requests never grant access. Missing router `p` is not a wildcard.
+- `publishChunk(descriptor, event)` checks a 34601 proof and the descriptor,
+  captures ciphertext only in watchtower mode, and publishes to the recipient's relays.
+  Every wrapper must receive at least one relay acceptance. Yield between calls
+  so text/control sends can run. Publish all file chunks before announcing 1063/9.
+- `download(descriptor, { manual, thumbnail, signal })` returns the verified,
+  persisted file descriptor. Automatic originals are limited to 1 MiB and
+  automatic thumbnails to 51,000 bytes. Larger/unknown originals require action;
+  already complete local files remain accessible. Unknown-size manual downloads
+  bootstrap their total from a verified chunk and learn size from the last one.
+- `observe(callback)` returns an unsubscribe function. Updates include control
+  channel, root, status, persisted useful bytes (`completed`), total and errors.
+- `cancel(controlChannelPubkey, root)` cancels the shared transfer; individual
+  caller signals only stop that caller waiting. Partial chunks are retained.
+- `close()` releases subscriptions, timers and storage. Messenger pause/unwatch/
+  close also stop work; resume restarts paused transfers, never explicit cancels.
+
+There are at most two active downloads per coordinator; thumbnails precede
+manual originals, then small automatic originals. Open live input before reading
+history or asking seeders. A failed historical read does not block peer recovery.
+Deduplication and completion depend on verified, persisted chunk indices, not
+publication ACKs or a terminal response. Ordinary DM left-edge temporal recovery
+is unchanged.
+
+## Recovery protocol
+
+The authenticated direct request travels on the conversation's `dm` channel:
+
+```js
+{ code: 'fileChunksRequest_p5cc', payload: {
+  fileChannelPubkey,
+  missingRanges: [[0, 15]] // inclusive, sorted, disjoint; at most 16 indices
+} }
+```
+
+A seeder replies from `storage.read`, skipping unavailable indices and validating
+local proofs before sending. Each JSONL record is:
+
+```js
+{ recordType: 'irfsChunk_v1', index, total, proof, content }
+```
+
+`proof` and `content` use Base93. The receiver reconstructs a 34601 template,
+checks its proof against the expected root, and persists it without claiming the
+original announcer authored the reconstructed event. The outer reply remains
+individually encrypted for its recipient. Watchtowers continue replying with
+`routerEnvelopeRow_v1`; they need not decrypt original bytes.
+
+The reply travels on the **file** channel, with code `fileChunksReply_p5cc` and
+the existing compact-record JSONL packer's `index`, `isLast`, and `jsonl` fields.
+The inner reply's `q` references the request event. No new terminal availability
+message is required and `isLast` never establishes file completeness. Late
+responses from authorized seeders remain useful during an active download.
+Seed replies run outside the DM dispatcher, with at most two reply workers and
+sixteen queued requests; workers yield between records so control traffic can
+continue. Requests discarded at the queue bound can be retried.
+
+Request one seeder first and another after two seconds, recalculating missing
+indices. A new persisted chunk resets the inactivity clock; duplicates do not.
+After contacting all selected seeders, 30 seconds without progress makes the
+transfer retryable. Each new attempt rechecks local storage and relay history.
+
+Router 26300 uses `p` for its optional recipient, `f` for transport sender,
+optional `imkc`, `c` for outer fragmentation, and `i` for the IRFS chunk index.
+Repeat `i` across every fragment. It survives seed compaction, and must agree
+with the validated 34601. It is encrypted within the router, never a public tag.
+Carrier 26400 continues to use only `id`/`c`; inner control recipient `r` and
+NIP-94 file-reference `r` are unchanged. There is no router `r` read fallback.
+The existing 65,536-byte event ceiling includes the additional router overhead.
+
+## Storage and scope
+
+Seeder authorizations live in
+`libp2r2p:private-messenger:<owner>:file-authorizations:idb-queue`, with `key`
+(unique control/data/recipient) and `channel` indexes. Records hold root, peer,
+optional size, recipient, `sharedAt`, and absolute `expiresAt`; no ciphertext,
+chunk bytes, signer or file-retention reference. The queue rejects capacity
+failures instead of silently evicting grants. Grants survive restart and expire
+at the original sharing time plus parent retention (default seven days), subject
+to a subsequently shorter parent policy. Only a newer explicit share renews them.
+
+Direct validated, persisted deliveries may authorize their actual local receiver
+using the descriptor's `sharedAt`. Cache reads and recovery replies never renew
+or create grants. Applications must not infer authorization for a third-party
+announcer from its knowledge of a root. Group membership/revocation is not part
+of this DM implementation; future group requests also need current membership.
+
+Serving requires both live authorization and locally available chunks. The
+catalog never pins NostrDB roots or recreates missing bytes. Checks run before
+reads and again before each publication. Shared cleanup removes invalid grants
+at startup and every minute while running; expired grants are immediately
+unusable even before physical cleanup. Identity cleanup includes the catalog.
+
+Watchtower ciphertext remains in
+`libp2r2p:private-messenger:<owner>:file-seeds:idb-queue`, with its existing
+64 MiB FIFO budget and parent retention. The authorization catalog starts empty;
+there is no migration or compatibility path for unpublished seeder file seeds.
+
+Seed responses require the matching control/data channel pair and requester.
+A channel holder can group traffic by its public channel author; no plaintext
+root/index tag is exposed. This does not hide timing or repeated transfers of
+the same pair/root.
+
+Multi-device seed synchronization and group-channel derivation remain separate
+follow-ups. Applications own durable manual-download intent, metadata retention
+and UI policy. Removing one message must not delete a root retained by another.
+
+## Optional persistence (0.11.1)
+
+`storage`, `authorizationStorage`, and `seedStorage` are optional. The latter two
+use the semantic contracts in `private-messenger/event-store`; omitted stores
+retain their existing indexed local implementation. External stores are owned by
+the caller. Synced grants are checked against the current channel mode/retention
+before serving, and are never deleted globally because a channel is not loaded.
+
+With no chunk adapter, `createFileCache` owns
+`<messenger prefix>:file-chunks:idb` (files and chunks stores). Its default
+`cacheMaxBytes` is 256 MiB of useful decoded bytes; physical IndexedDB overhead is
+additional. Deduplication uses root/index. FIFO root eviction discards inactive
+files to admit new data. Durable renewable reservations protect active transfers
+and readers across tabs; stale reservations expire after two minutes. A blocked
+transfer waits with cancellation. Unknown sizes reserve the budget exclusively;
+an individual oversized file raises `FILE_EXCEEDS_CACHE_CAPACITY`. Physical quota
+failures try discarding additional inactive roots before propagating.
+
+Outgoing chunks are saved before publication; this does not authorize recipients.
+`readChunk(root, index)` reads local data. `stream(descriptor, { signal })` uses
+bounded sequential reads and backpressure, not a whole-file Blob. Cancel streams
+when unused. Cache eviction can remove a previously completed file, so new
+requests recheck persisted indices. The cache is included in identity cleanup.

package/private-messenger/file/helpers/cache.js

@@ -0,0 +1,159 @@
+import { chunkStream } from './stream.js'
+import { ValidationError } from '../../../error/index.js'
+import { decodeIrfsChunk, IRFS_CHUNK_BYTES } from '../../../irfs/index.js'
+
+export const DEFAULT_FILE_CACHE_BYTES = 256 * 1024 * 1024
+const request = value => new Promise((resolve, reject) => { value.onsuccess = () => resolve(value.result); value.onerror = () => reject(value.error) })
+const done = tx => new Promise((resolve, reject) => { tx.oncomplete = resolve; tx.onabort = () => reject(tx.error || new Error('FILE_CACHE_ABORTED')); tx.onerror = () => {} })
+
+// Payload budget is useful decoded bytes, not the browser's physical disk usage.
+// Files and chunk mutations commit together; durable leases fence other tabs.
+export function createFileCache ({ prefix, indexedDB = globalThis.indexedDB, maxBytes = DEFAULT_FILE_CACHE_BYTES, now = Date.now }) {
+  if (!indexedDB?.open || !prefix || !Number.isSafeInteger(maxBytes) || maxBytes < 1) throw new ValidationError('INVALID_FILE_CACHE_OPTIONS')
+  let closed = false
+  const tokens = new Map()
+  const waiters = new Set()
+  const dbPromise = new Promise((resolve, reject) => {
+    const opening = indexedDB.open(`${prefix}:file-chunks:idb`, 1)
+    opening.onerror = () => reject(opening.error)
+    opening.onupgradeneeded = () => {
+      opening.result.createObjectStore('files', { keyPath: 'root' })
+      opening.result.createObjectStore('chunks', { keyPath: ['root', 'index'] }).createIndex('root', 'root')
+    }
+    opening.onsuccess = () => { opening.result.onversionchange = () => opening.result.close(); resolve(opening.result) }
+  })
+  const notify = () => { for (const wake of waiters) wake() }
+  const assertOpen = () => { if (closed) throw new Error('FILE_CACHE_CLOSED') }
+  async function transaction (work) {
+    assertOpen()
+    const db = await dbPromise
+    assertOpen()
+    const tx = db.transaction(['files', 'chunks'], 'readwrite')
+    const completion = done(tx)
+    try { const result = await work(tx.objectStore('files'), tx.objectStore('chunks')); await completion; return result } catch (error) { try { tx.abort() } catch {} await completion.catch(() => {}); throw error }
+  }
+  async function removeRoot (files, chunks, root) {
+    await new Promise((resolve, reject) => {
+      const cursor = chunks.index('root').openCursor(root)
+      cursor.onerror = () => reject(cursor.error)
+      cursor.onsuccess = () => { if (!cursor.result) return resolve(); cursor.result.delete(); cursor.result.continue() }
+    })
+    await request(files.delete(root))
+  }
+  const live = file => Object.fromEntries(Object.entries(file.leases || {}).filter(([, lease]) => lease.until > now()))
+  const cost = file => Math.max(file.used, ...Object.values(file.leases || {}).map(v => v.size))
+  async function attempt (root, size, token) {
+    return transaction(async (files, chunks) => {
+      const all = await request(files.getAll())
+      for (const file of all) file.leases = live(file)
+      let file = all.find(f => f.root === root)
+      if (!file) { file = { root, used: 0, createdAt: now(), leases: {} }; all.push(file) }
+      file.leases[token] = { size, until: now() + 120000 }
+      let total = all.reduce((sum, f) => sum + cost(f), 0)
+      const victims = all.filter(f => f.root !== root && !Object.keys(f.leases).length).sort((a, b) => a.createdAt - b.createdAt || a.root.localeCompare(b.root))
+      if (total - victims.reduce((sum, f) => sum + cost(f), 0) > maxBytes) return false
+      for (const victim of victims) {
+        if (total <= maxBytes) break
+        await removeRoot(files, chunks, victim.root); total -= cost(victim)
+      }
+      await request(files.put(file)); return true
+    })
+  }
+  async function wait (signal) {
+    signal?.throwIfAborted(); assertOpen()
+    await new Promise((resolve, reject) => {
+      const finish = error => { clearTimeout(timer); waiters.delete(wake); signal?.removeEventListener('abort', abort); error ? reject(error) : resolve() }
+      const wake = () => finish(), abort = () => finish(signal.reason)
+      const timer = setTimeout(wake, 250)
+      waiters.add(wake); signal?.addEventListener('abort', abort, { once: true })
+    })
+  }
+  async function reserve (root, size, { signal } = {}) {
+    if (!/^[0-9a-f]{64}$/.test(root)) throw new ValidationError('INVALID_FILE_ROOT')
+    size ??= maxBytes
+    if (!Number.isSafeInteger(size) || size < 1) throw new ValidationError('INVALID_FILE_SIZE')
+    if (size > maxBytes) throw Object.assign(new Error('FILE_EXCEEDS_CACHE_CAPACITY'), { code: 'FILE_EXCEEDS_CACHE_CAPACITY', maxBytes })
+    const token = crypto.randomUUID()
+    while (true) {
+      signal?.throwIfAborted(); assertOpen()
+      if (await attempt(root, size, token)) break
+      await wait(signal)
+    }
+    tokens.set(token, root)
+    let released = false
+    return async () => {
+      if (released) return
+      released = true; tokens.delete(token)
+      if (!closed) {
+        await transaction(async files => {
+          const file = await request(files.get(root)); if (!file) return
+          delete file.leases[token]; await request(files.put(file))
+        })
+      }
+      notify()
+    }
+  }
+  const timer = setInterval(() => {
+    if (!tokens.size || closed) return
+    transaction(async files => {
+      for (const [token, root] of tokens) {
+        const file = await request(files.get(root))
+        if (file?.leases[token]) { file.leases[token].until = now() + 120000; await request(files.put(file)) }
+      }
+    }).catch(() => {})
+  }, 30000)
+  timer.unref?.()
+  const api = {
+    maxBytes, reserve,
+    async read (root, index) {
+      assertOpen(); const db = await dbPromise
+      const tx = db.transaction('chunks', 'readonly')
+      const row = await request(tx.objectStore('chunks').get([root, index]))
+      return row?.event
+    },
+    async save (event, descriptor) {
+      const decoded = decodeIrfsChunk(event)
+      if (decoded.root !== descriptor.root) throw new ValidationError('FILE_CHUNK_DESCRIPTOR_MISMATCH')
+      if (descriptor.size !== undefined && (decoded.total !== Math.ceil(descriptor.size / IRFS_CHUNK_BYTES) || (decoded.index === decoded.total - 1 && decoded.contentBytes.length !== descriptor.size - decoded.index * IRFS_CHUNK_BYTES))) throw new ValidationError('FILE_CHUNK_DESCRIPTOR_MISMATCH')
+      const actualSize = decoded.index === decoded.total - 1 ? decoded.index * IRFS_CHUNK_BYTES + decoded.contentBytes.length : undefined
+      if (actualSize > maxBytes || decoded.index * IRFS_CHUNK_BYTES + decoded.contentBytes.length > maxBytes) throw Object.assign(new Error('FILE_EXCEEDS_CACHE_CAPACITY'), { code: 'FILE_EXCEEDS_CACHE_CAPACITY' })
+      const release = await reserve(decoded.root, descriptor.size ?? actualSize)
+      try {
+        while (true) {
+          try {
+            await transaction(async (files, chunks) => {
+              const file = await request(files.get(decoded.root))
+              const prior = await request(chunks.get([decoded.root, decoded.index]))
+              file.used += decoded.contentBytes.length - (prior?.bytes || 0)
+              await request(chunks.put({ root: decoded.root, index: decoded.index, bytes: decoded.contentBytes.length, event: structuredClone(event) }))
+              await request(files.put(file))
+            })
+            break
+          } catch (error) {
+            if (error?.name !== 'QuotaExceededError') throw error
+            const removed = await transaction(async (files, chunks) => {
+              const candidates = (await request(files.getAll())).filter(f => f.root !== decoded.root && !Object.keys(live(f)).length).sort((a, b) => a.createdAt - b.createdAt)
+              if (!candidates.length) return false
+              await removeRoot(files, chunks, candidates[0].root)
+              return true
+            })
+            if (!removed) throw error
+          }
+        }
+      } finally { await release() }
+    },
+    async stream (descriptor, { signal } = {}) {
+      const release = await reserve(descriptor.root, descriptor.size, { signal })
+      return chunkStream({ read: api.read, root: descriptor.root, size: descriptor.size, signal, release })
+    },
+    async close () {
+      if (closed) return
+      clearInterval(timer)
+      await transaction(async files => {
+        for (const [token, root] of tokens) { const file = await request(files.get(root)); if (file) { delete file.leases[token]; await request(files.put(file)) } }
+      })
+      closed = true; tokens.clear(); notify(); (await dbPromise).close()
+    }
+  }
+  return api
+}