libp2r2p 0.10.27 → 0.11.0

package/README.md

@@ -534,6 +534,14 @@ returned events; received messages may already have been queued. This is a
 history completeness failure, not evidence that an outgoing message failed.
 Existing rewatch/resume and relay-list refresh paths retry pending intervals;
 there is no dedicated periodic retry timer for a failed history fetch.
+Subscription relay errors forwarded to `onError` include `relay` when known
+and `operation: 'private-channel.subscribe'`. A per-notification wrapper retains
+the native message, name, code, category and WebSocket close fields; `cause`
+references the untouched original error, including its stack and causes.
+Aggregate errors keep their nested errors. This also works with frozen/shared
+errors without leaking attribution between subscribers. Missing relay metadata
+is not inferred from the selected relay list. This does not change reconnection,
+delivery or error classification; processing errors keep their existing path.
 `lastSeenAt` tracks messages persisted in the incoming queue, not app commits.
 The default recovery window is seven days; recovery still depends on available
 relay/seeder data, and retention limits cannot guarantee indefinite delivery.
@@ -882,3 +890,20 @@ complete per-relay report without delaying the first-success return. Connection
 establishment retains its separate 3-second deadline. PrivateMessenger inherits
 this publication policy, including seeder/recovery messages. A timeout indicates
 missing acknowledgement and cannot prove that the recipient did not receive it.
+
+## Private file channels (0.11)
+
+`libp2r2p/private-messenger/file` provides `createPrivateFileTransfer` for
+separate per-root media channels, bounded indexed recovery and persisted-byte
+progress. [The file API and protocol](private-messenger/file/README.md) document
+signer/storage adapters and lifecycle. All original and thumbnail chunks belong
+to `dm:media:<root>`; small authenticated recovery requests stay on `dm`.
+NIP-94 supports `thumbnail` metadata with unordered `mark`/`size` root extensions.
+
+This release changes the encrypted router recipient tag from `r` to `p` without
+legacy fallback. Upgrade communicating consumers together. Inner ask/reply/tell
+`r` tags, file-reference `r` tags, and carrier 26400 are unchanged. Seeders now
+capture outgoing ordinary-message ciphertext before publishing, even without relay
+echo. For files, seeders instead keep expiring recipient authorizations and serve
+verified local chunks as `irfsChunk_v1`; watchtowers retain ciphertext seeds.
+No group derivation or multi-device seed replication is introduced.

package/nip27/index.js

@@ -201,6 +201,7 @@ const NIP94_TAGS = {
   magnet: ['magnet'],
   i: ['i'],
   blurhash: ['blurhash'],
+  thumbhash: ['thumbhash'],
   thumb: ['thumb'],
   image: ['image'],
   summary: ['summary'],

package/nip94/README.md

@@ -38,3 +38,16 @@ A bare/empty/duplicate/invalid value throws `INVALID_MEDIA_METADATA_DOWNLOAD`;
 `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.
+
+## Thumbnails
+
+`thumbnail: { url, root?, size?, sha256? }` emits a `thumb` tag and, when a root
+is supplied, `['r', root, 'mark thumb', 'size <bytes>']`. `sha256` is the optional
+third thumb-tag value. Original `r` stays unmarked. Decode validates nfile/root
+agreement separately for original and thumbnail.
+
+Only `r[1]` has a fixed position. `parseRootReference(tag)` parses the variadic
+fields by their names; `mark` and `size` may appear in either order. Unknown
+extensions are ignored. Duplicate recognized fields, ambiguous roots and unsafe
+sizes are rejected. ThumbHash remains unchanged Base64, including through
+percent-encoded NIP-27 `thumbhash` fragments; legacy `blurhash` still parses.

package/nip94/index.js

@@ -19,10 +19,36 @@ export function decodeFileMetadata (event) {
   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']]) {
+  for (const [tag, key] of [['service', 'service'], ['thumbhash', 'thumbhash'], ['x', 'sha256'], ['ox', 'originalSha256'], ['alt', 'alt']]) {
     const value = field(tag)
     if (value !== undefined) result[key] = value
   }
+  const roots = event.tags.filter(tag => Array.isArray(tag) && tag[0] === 'r').map(parseRootReference)
+  const originals = roots.filter(ref => ref.mark === undefined)
+  const thumbnails = roots.filter(ref => ref.mark === 'thumb')
+  if (originals.length > 1 || thumbnails.length > 1) throw new ValidationError('INVALID_FILE_METADATA_ROOT_REFERENCE')
+  if (originals.length) result.root = originals[0].root
+  const thumbUrl = field('thumb')
+  if (thumbUrl !== undefined) {
+    const thumbnail = { url: thumbUrl }
+    let parsed
+    try { parsed = new URL(thumbUrl) } catch { throw new ValidationError('INVALID_FILE_METADATA_THUMBNAIL') }
+    if (!['https:', 'http:'].includes(parsed.protocol) || parsed.username || parsed.password) throw new ValidationError('INVALID_FILE_METADATA_THUMBNAIL')
+    if (thumbnails.length) {
+      thumbnail.root = thumbnails[0].root
+      if (thumbnails[0].size !== undefined) thumbnail.size = thumbnails[0].size
+    }
+    const hash = event.tags.find(tag => tag[0] === 'thumb')?.[2]
+    if (hash !== undefined) {
+      if (!/^[0-9a-f]{64}$/.test(hash)) throw new ValidationError('INVALID_FILE_METADATA_HASH')
+      thumbnail.sha256 = hash
+    }
+    if (parsed.origin === 'https://nostr.alt') {
+      const file = nfileDecode(parsed.pathname.slice(1))
+      if (thumbnail.root && thumbnail.root !== file.root) throw new ValidationError('FILE_METADATA_NFILE_MISMATCH')
+    }
+    result.thumbnail = thumbnail
+  } else if (thumbnails.length) throw new ValidationError('INVALID_FILE_METADATA_THUMBNAIL')
   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) {
@@ -49,7 +75,35 @@ export function createFileMetadata ({ caption = '', created_at: createdAt = Math
   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])] }
+  if (metadata.thumbnail !== undefined) {
+    const thumb = metadata.thumbnail
+    if (!thumb || typeof thumb !== 'object') throw new ValidationError('INVALID_FILE_METADATA_THUMBNAIL')
+    fields.push(thumb.sha256 === undefined ? ['thumb', thumb.url] : ['thumb', thumb.url, thumb.sha256])
+    if (thumb.root !== undefined) fields.push(['r', thumb.root, 'mark thumb', ...(thumb.size === undefined ? [] : [`size ${thumb.size}`])])
+  }
+  const event = { kind: FILE_METADATA, created_at: createdAt, content: caption, tags: [...fields.filter(([, value]) => value !== undefined).map(([key, ...values]) => [key, ...values.map(String)]), ...tags.map(tag => [...tag])] }
   decodeFileMetadata(event)
   return event
 }
+
+// Only the root has a fixed position; extensions are unordered key/value fields.
+export function parseRootReference (tag) {
+  if (!Array.isArray(tag) || tag[0] !== 'r' || typeof tag[1] !== 'string' || !/^[0-9a-f]{64}$/.test(tag[1])) throw new ValidationError('INVALID_FILE_METADATA_ROOT_REFERENCE')
+  const result = { root: tag[1] }
+  for (const field of tag.slice(2)) {
+    if (typeof field !== 'string') throw new ValidationError('INVALID_FILE_METADATA_ROOT_REFERENCE')
+    const separator = field.indexOf(' ')
+    const key = separator < 0 ? field : field.slice(0, separator)
+    if (!['mark', 'size'].includes(key)) continue
+    if (Object.hasOwn(result, key) || separator < 0) throw new ValidationError('INVALID_FILE_METADATA_ROOT_REFERENCE')
+    const value = field.slice(separator + 1)
+    if (key === 'mark') {
+      if (!value) throw new ValidationError('INVALID_FILE_METADATA_ROOT_REFERENCE')
+      result.mark = value
+    } else {
+      if (!/^(0|[1-9][0-9]*)$/.test(value) || !Number.isSafeInteger(Number(value))) throw new ValidationError('INVALID_FILE_METADATA_SIZE')
+      result.size = Number(value)
+    }
+  }
+  return result
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libp2r2p",
-  "version": "0.10.27",
+  "version": "0.11.0",
   "description": "Peer-to-relay-to-peer",
   "keywords": [
     "p2r2p",
@@ -86,6 +86,7 @@
     "./private-channel": "./private-channel/index.js",
     "./private-message": "./private-message/index.js",
     "./private-messenger": "./private-messenger/index.js",
+    "./private-messenger/file": "./private-messenger/file/index.js",
     "./private-messenger/recovery": "./private-messenger/recovery/index.js",
     "./relay": "./relay/index.js",
     "./temporary-storage": "./temporary-storage/index.js",

package/private-channel/helpers/chunk-size.js

@@ -16,7 +16,7 @@ function routerPlaintextByteLengthForChunk (jsonlByteLength) {
     kind: ROUTER_KIND,
     pubkey: SAMPLE_PUBKEY,
     created_at: MAX_TIME_SECONDS,
-    tags: [['f', SAMPLE_PUBKEY], ['imkc', SAMPLE_PUBKEY, `${MAX_TIME_SECONDS}:${SAMPLE_SIGNATURE}`], ['c', MAX_CHUNK_TAG_VALUE, MAX_CHUNK_TAG_VALUE], ['r', SAMPLE_PUBKEY]],
+    tags: [['f', SAMPLE_PUBKEY], ['imkc', SAMPLE_PUBKEY, `${MAX_TIME_SECONDS}:${SAMPLE_SIGNATURE}`], ['c', MAX_CHUNK_TAG_VALUE, MAX_CHUNK_TAG_VALUE], ['p', SAMPLE_PUBKEY], ['i', String(Number.MAX_SAFE_INTEGER)]],
     content: 'A'.repeat(base64EncodedByteLength(jsonlByteLength)),
     id: SAMPLE_PUBKEY,
     sig: SAMPLE_SIGNATURE

package/private-channel/helpers/chunks.js

@@ -156,7 +156,7 @@ function setPreparedRow (id, index, row, temporaryStorage) {
   storageFor(temporaryStorage).setItem(rowTempKey(id, index), row)
 }
 
-function readPreparedRow (preparedRows, index) {
+export function readPreparedRow (preparedRows, index) {
   const row = storageFor(preparedRows.temporaryStorage).getItem(rowTempKey(preparedRows.id, index))
   if (typeof row !== 'string') throw new ValidationError('MISSING_PREPARED_ROW')
   return row

package/private-channel/helpers/event.js

@@ -12,7 +12,7 @@ export function eventByteLength (event) {
 }
 
 export function readReceiverTag (event) {
-  return event.tags?.find(t => t[0] === 'r')?.[1] || ''
+  return event.tags?.find(t => t[0] === 'p')?.[1] || ''
 }
 
 export function readSenderTag (event) {
@@ -47,14 +47,18 @@ export function readChunkTag (event) {
   return { index, total }
 }
 
-export function makeRouterEvent ({ pubkey, senderPubkey, imkcPubkey, imkcProof, receiverPubkey, chunkIndex, chunkTotal, content }) {
+export function makeRouterEvent ({ pubkey, senderPubkey, imkcPubkey, imkcProof, receiverPubkey, chunkIndex, chunkTotal, fileChunkIndex, content }) {
   const tags = [['f', senderPubkey]]
   if (imkcPubkey) {
     if (!imkcProof) throw new ValidationError('INVALID_IMKC_PROOF')
     tags.push(['imkc', imkcPubkey, imkcProof])
   }
+  if (fileChunkIndex !== undefined) {
+    if (!Number.isSafeInteger(fileChunkIndex) || fileChunkIndex < 0) throw new ValidationError('INVALID_FILE_CHUNK_INDEX')
+    tags.push(['i', String(fileChunkIndex)])
+  }
   tags.push(['c', String(chunkIndex), String(chunkTotal)])
-  if (receiverPubkey) tags.push(['r', receiverPubkey])
+  if (receiverPubkey) tags.push(['p', receiverPubkey])
   return { kind: ROUTER_KIND, pubkey, created_at: nowSeconds(), tags, content }
 }
 
@@ -67,3 +71,10 @@ export function makeNymCarrierEvent ({ innerId, chunkIndex, chunkTotal, content,
     content
   }
 }
+
+export function readFileChunkIndex (event) {
+  const tags = event.tags?.filter(tag => tag[0] === 'i') || []
+  if (!tags.length) return undefined
+  if (tags.length !== 1 || tags[0].length !== 2 || !/^(0|[1-9][0-9]*)$/.test(tags[0][1]) || !Number.isSafeInteger(Number(tags[0][1]))) throw new ValidationError('INVALID_FILE_CHUNK_INDEX')
+  return Number(tags[0][1])
+}

package/private-channel/helpers/subscription-error.js

@@ -0,0 +1,14 @@
+// Relay errors can be shared by multiple subscriptions or be frozen. Attach
+// consumer context to a new error and retain the untouched original as cause.
+export function subscriptionError (reason, relay) {
+  const message = reason?.message ?? String(reason)
+  const error = reason instanceof AggregateError
+    ? new AggregateError(reason.errors, message, { cause: reason })
+    : new Error(message, { cause: reason })
+  for (const key of ['name', 'code', 'category', 'closeCode', 'closeReason', 'wasClean']) {
+    if (reason?.[key] !== undefined) error[key] = reason[key]
+  }
+  error.operation = 'private-channel.subscribe'
+  if (typeof relay === 'string') error.relay = relay
+  return error
+}

package/private-channel/index.js

@@ -7,6 +7,7 @@ import { getIykcProofs } from '../content-key/index.js'
 import { ValidationError } from '../error/index.js'
 import { normalizeRumor, deliveryInfo } from './helpers/rumor.js'
 import { incompleteFetchError } from './helpers/fetch-error.js'
+import { subscriptionError } from './helpers/subscription-error.js'
 import * as nip44v3 from '../nip44-v3/index.js'
 import { relayPool } from '../relay/index.js'
 import { JSONL_CHUNK_BYTES, NYM_CARRIER_CHUNK_CHARS } from './helpers/chunk-size.js'
@@ -17,12 +18,13 @@ import {
   prepareEnvelopeRows,
   preparedRowIndexesForReceivers,
   readChunkContent,
+  readPreparedRow,
   receiverPubkeys,
   receiverPubkeysWithoutContentKeys,
   writeChunksFromPreparedRows
 } from './helpers/chunks.js'
 import { EXPIRATION_SECONDS, MAX_EVENT_BYTES, NYM_CARRIER_KIND, PRIVATE_BROADCAST_KIND, ROUTER_KIND } from './constants/index.js'
-import { eventByteLength, hasImkcTag, makeNymCarrierEvent, makeRouterEvent, nowSeconds, readChunkTag, readIdTag, readImkcProof, readImkcTag, readReceiverTag, readSenderTag } from './helpers/event.js'
+import { eventByteLength, hasImkcTag, makeNymCarrierEvent, makeRouterEvent, nowSeconds, readChunkTag, readFileChunkIndex, readIdTag, readImkcProof, readImkcTag, readReceiverTag, readSenderTag } from './helpers/event.js'
 import { createReceivedChunkStore, DEFAULT_RECEIVED_CHUNK_MAX_BYTES, DEFAULT_RECEIVED_CHUNK_TTL_MS } from './services/received-chunks.js'
 
 export { EXPIRATION_SECONDS, MAX_EVENT_BYTES, NYM_CARRIER_KIND, PRIVATE_BROADCAST_KIND, ROUTER_KIND } from './constants/index.js'
@@ -130,7 +132,7 @@ async function prepareRoutedMessage ({ senderSigner, imkcSigner, privateChannelS
   }
 }
 
-async function * wrapPreparedEvents ({ privateChannelSigner, receivers, receiverTag, deletionPubkey, expirationSeconds = EXPIRATION_SECONDS, context }) {
+async function * wrapPreparedEvents ({ privateChannelSigner, receivers, receiverTag, fileChunkIndex, onPreparedSeed, deletionPubkey, expirationSeconds = EXPIRATION_SECONDS, context }) {
   const routerSeckey = generateSecretKey()
   const routerPubkey = getPublicKey(routerSeckey)
   const receiverPubkeyList = receiverPubkeys(receivers)
@@ -143,6 +145,13 @@ async function * wrapPreparedEvents ({ privateChannelSigner, receivers, receiver
   const temporaryStorage = context.preparedRows.temporaryStorage
 
   try {
+    if (onPreparedSeed) {
+      const router = makeRouterEvent({ pubkey: routerPubkey, senderPubkey: context.senderPubkey, imkcPubkey: context.imkcPubkey, imkcProof: context.imkcProof, receiverPubkey: routerReceiverTag, chunkIndex: 0, chunkTotal: 1, fileChunkIndex, content: '' })
+      const payloadRow = readPreparedRow(context.preparedRows, 0)
+      for (const rowIndex of rowIndexes) {
+        await onPreparedSeed({ channelPubkey: context.channelPubkey, router, jsonl: `${payloadRow}\n${readPreparedRow(context.preparedRows, rowIndex)}\n` })
+      }
+    }
     for (let index = 0; index < total; index++) {
       const content = readChunkContent(id, index, temporaryStorage)
       const router = finalizeEvent(makeRouterEvent({
@@ -151,6 +160,7 @@ async function * wrapPreparedEvents ({ privateChannelSigner, receivers, receiver
         imkcPubkey: context.imkcPubkey,
         imkcProof: context.imkcProof,
         receiverPubkey: routerReceiverTag,
+        fileChunkIndex,
         chunkIndex: index,
         chunkTotal: total,
         content
@@ -171,7 +181,7 @@ async function * wrapPreparedEvents ({ privateChannelSigner, receivers, receiver
 }
 
 // Streaming version of wrapEvent
-export async function * wrapEvents ({ senderSigner, imkcSigner, privateChannelSigner = senderSigner, privateChannelReaderPubkey, receivers, receiverTag, deletionPubkey, event, expirationSeconds = EXPIRATION_SECONDS, temporaryStorageArea, _getIykcProofs = getIykcProofs }) {
+export async function * wrapEvents ({ senderSigner, imkcSigner, privateChannelSigner = senderSigner, privateChannelReaderPubkey, receivers, receiverTag, fileChunkIndex, onPreparedSeed, deletionPubkey, event, expirationSeconds = EXPIRATION_SECONDS, temporaryStorageArea, _getIykcProofs = getIykcProofs }) {
   const normalizedDeletionPubkey = normalizeDeletionPubkey(deletionPubkey)
   const context = await prepareRoutedMessage({
     senderSigner,
@@ -184,7 +194,7 @@ export async function * wrapEvents ({ senderSigner, imkcSigner, privateChannelSi
     _getIykcProofs
   })
   try {
-    yield * wrapPreparedEvents({ privateChannelSigner, receivers, receiverTag, deletionPubkey: normalizedDeletionPubkey, expirationSeconds, context })
+    yield * wrapPreparedEvents({ privateChannelSigner, receivers, receiverTag, fileChunkIndex, onPreparedSeed, deletionPubkey: normalizedDeletionPubkey, expirationSeconds, context })
   } finally {
     cleanupEnvelopeRows(context.preparedRows)
   }
@@ -414,6 +424,12 @@ export async function unwrapEvent ({ receiverSigner, privateChannelSigner = rece
     channelReaderSigner,
     channelReaderPubkey: privateChannelReaderPubkey
   })
+  return unwrapRouterEvent({ router, receiverSigner, receiverPubkey, channelPubkey })
+}
+
+// Recovery records contain an encrypted recipient row, not the original outer
+// signature. Authenticate the control response before invoking this decoder.
+export async function unwrapRouterEvent ({ router, receiverSigner, receiverPubkey, channelPubkey }) {
   if (router.kind !== ROUTER_KIND) throw new ValidationError('INVALID_ROUTER_KIND')
   if (receiverPubkey && readReceiverTag(router) && readReceiverTag(router) !== receiverPubkey) return null
 
@@ -505,7 +521,7 @@ function withRecoveryRelays (relays, recoveryRelays) {
   return uniq([...(relays || []), ...(recoveryRelays || [])])
 }
 
-export async function publish ({ senderSigner, imkcSigner, privateChannelSigner = senderSigner, privateChannelReaderPubkey, receivers, receiverTag, deletionPubkey, event, relays, relayToReceivers, recoveryRelays, expirationSeconds, temporaryStorageArea, _getIykcProofs = getIykcProofs, _publish = sendToRelays }) {
+export async function publish ({ senderSigner, imkcSigner, privateChannelSigner = senderSigner, privateChannelReaderPubkey, receivers, receiverTag, fileChunkIndex, onPreparedSeed, deletionPubkey, event, relays, relayToReceivers, recoveryRelays, expirationSeconds, temporaryStorageArea, _getIykcProofs = getIykcProofs, _publish = sendToRelays }) {
   const normalizedDeletionPubkey = normalizeDeletionPubkey(deletionPubkey)
   const results = []
   // Relays are grouped only when they have the exact same recipient pubkey set
@@ -523,7 +539,7 @@ export async function publish ({ senderSigner, imkcSigner, privateChannelSigner
     })
     try {
       for (const group of groups) {
-        for await (const wrappedEvent of wrapPreparedEvents({ privateChannelSigner, receivers: group.receivers, receiverTag, deletionPubkey: normalizedDeletionPubkey, expirationSeconds, context })) {
+        for await (const wrappedEvent of wrapPreparedEvents({ privateChannelSigner, receivers: group.receivers, receiverTag, fileChunkIndex, onPreparedSeed, deletionPubkey: normalizedDeletionPubkey, expirationSeconds, context })) {
           results.push(await _publish(wrappedEvent, withRecoveryRelays(group.relays, recoveryRelays)))
         }
       }
@@ -533,7 +549,7 @@ export async function publish ({ senderSigner, imkcSigner, privateChannelSigner
     return results
   }
 
-  for await (const wrappedEvent of wrapEvents({ senderSigner, imkcSigner, privateChannelSigner, privateChannelReaderPubkey, receivers, receiverTag, deletionPubkey: normalizedDeletionPubkey, event, expirationSeconds, temporaryStorageArea, _getIykcProofs })) {
+  for await (const wrappedEvent of wrapEvents({ senderSigner, imkcSigner, privateChannelSigner, privateChannelReaderPubkey, receivers, receiverTag, fileChunkIndex, onPreparedSeed, deletionPubkey: normalizedDeletionPubkey, event, expirationSeconds, temporaryStorageArea, _getIykcProofs })) {
     results.push(await _publish(wrappedEvent, withRecoveryRelays(relays, recoveryRelays)))
   }
   return results
@@ -764,6 +780,7 @@ function createProcessor ({
       const senderPubkey = readSenderTag(router)
       if (receiverPubkey && readReceiverTag(router) && readReceiverTag(router) !== receiverPubkey && senderPubkey !== receiverPubkey) return
       const { index, total } = readChunkTag(router)
+      readFileChunkIndex(router)
       groupKey = receivedChunks.groupKeyFor(channelPubkey, router.pubkey)
       if (ignoredGroups.has(groupKey)) return
 
@@ -772,6 +789,7 @@ function createProcessor ({
       const meta = await receivedChunks.put({
         channelPubkey,
         routerPubkey: router.pubkey,
+        descriptor: JSON.stringify(router.tags.filter(tag => tag[0] !== 'c')),
         index,
         total,
         contentBytes: base64ToBytes(router.content),
@@ -962,7 +980,7 @@ export function subscribe ({ receiverSigner, iykcSigner, privateChannelSigner =
     try {
       for await (const item of events) {
         if (controller.signal.aborted) continue
-        if (item.type === 'error') onError?.(item.error)
+        if (item.type === 'error') onError?.(subscriptionError(item.error, item.relay))
         else if (item.type === 'event') await processOuterEvent(item.event)
       }
     } catch (error) {
@@ -975,6 +993,7 @@ export function subscribe ({ receiverSigner, iykcSigner, privateChannelSigner =
   const consumePromise = consumeEvents()
 
   return {
+    ready: events.ready || Promise.resolve(),
     close () {
       controller.abort()
       return consumePromise

package/private-channel/services/received-chunks.js

@@ -135,6 +135,7 @@ function normalizeMeta (meta, fallbackTtlMs = DEFAULT_RECEIVED_CHUNK_TTL_MS) {
   return {
     groupKey: String(meta.groupKey),
     channelPubkey: String(meta.channelPubkey || ''),
+    descriptor: meta.descriptor,
     routerPubkey: String(meta.routerPubkey || ''),
     total,
     received: normalizeReceived(meta.received),
@@ -274,7 +275,7 @@ export function createReceivedChunkStore ({
     return cleanupStaleRaw(nowMs)
   }
 
-  async function putOnce ({ channelPubkey, routerPubkey, index, total, contentBytes, ttlMs }) {
+  async function putOnce ({ channelPubkey, routerPubkey, index, total, contentBytes, ttlMs, descriptor }) {
     const groupKey = groupKeyFor(channelPubkey, routerPubkey)
     const bytes = normalizeBytes(contentBytes)
     const now = Date.now()
@@ -287,6 +288,7 @@ export function createReceivedChunkStore ({
         await deleteGroupInTransaction(tx, groupKey, usage, meta)
         meta = null
       }
+      if (meta && meta.descriptor !== descriptor) throw new ValidationError('INCONSISTENT_ROUTER_DESCRIPTOR')
       if (meta && meta.total !== total) {
         await deleteGroupInTransaction(tx, groupKey, usage, meta)
         meta = null
@@ -296,6 +298,7 @@ export function createReceivedChunkStore ({
           groupKey,
           channelPubkey,
           routerPubkey,
+          descriptor,
           total,
           received: {},
           receivedCount: 0,
@@ -364,7 +367,7 @@ export function createReceivedChunkStore ({
     })
   }
 
-  async function put ({ channelPubkey, routerPubkey, index, total, contentBytes, ttlMs }) {
+  async function put ({ channelPubkey, routerPubkey, index, total, contentBytes, ttlMs, descriptor }) {
     if (!channelPubkey || !routerPubkey) throw new ValidationError('RECEIVED_CHUNK_GROUP_REQUIRED')
     if (!Number.isSafeInteger(index) || !Number.isSafeInteger(total) || index < 0 || total < 1 || index >= total) {
       throw new ValidationError('INVALID_RECEIVED_CHUNK_INDEX')
@@ -373,7 +376,7 @@ export function createReceivedChunkStore ({
     await ready()
     while (true) {
       try {
-        const result = await putOnce({ channelPubkey, routerPubkey, index, total, contentBytes: bytes, ttlMs })
+        const result = await putOnce({ channelPubkey, routerPubkey, index, total, contentBytes: bytes, ttlMs, descriptor })
         if (result.tooLarge) throw new Error('RECEIVED_CHUNK_GROUP_TOO_LARGE')
         return result.meta
       } catch (err) {

package/private-message/index.js

@@ -517,10 +517,12 @@ async function sendPrivateMessage ({
   temporaryStorageArea,
   deletionPubkey,
   _getIykcProofs,
+  fileChunkIndex,
+  onPreparedSeed,
   _publish = privateChannel.publish
 }) {
   if (!privateChannelSigner?.getPublicKey) throw new ValidationError('PRIVATE_CHANNEL_WRITER_REQUIRED')
-  return _publish({ senderSigner, imkcSigner, privateChannelSigner, privateChannelReaderPubkey, receivers, receiverTag, deletionPubkey, event, relays, relayToReceivers, recoveryRelays, expirationSeconds, temporaryStorageArea, _getIykcProofs })
+  return _publish({ senderSigner, imkcSigner, privateChannelSigner, privateChannelReaderPubkey, receivers, receiverTag, deletionPubkey, event, relays, relayToReceivers, recoveryRelays, expirationSeconds, temporaryStorageArea, fileChunkIndex, onPreparedSeed, _getIykcProofs })
 }
 
 async function sendNymMessage ({
@@ -560,6 +562,8 @@ export async function ask ({
   deletionPubkey,
   deletionSeckey,
   autoDeletionCapability = true,
+  fileChunkIndex,
+  onPreparedSeed,
   _publish = privateChannel.publish,
   _assertWatching
 }) {
@@ -583,7 +587,7 @@ export async function ask ({
     })
   })
   const deletion = resolveDeletionCapability({ deletionPubkey, deletionSeckey, autoDeletionCapability })
-  const reports = await sendPrivateMessage({ senderSigner, imkcSigner, privateChannelSigner, privateChannelReaderPubkey, receivers: [receiverPubkey], receiverTag: receiverPubkey, deletionPubkey: deletion.deletionPubkey, event: wireEvent, relays, relayToReceivers, recoveryRelays, expirationSeconds, temporaryStorageArea, _getIykcProofs, _publish })
+  const reports = await sendPrivateMessage({ senderSigner, imkcSigner, privateChannelSigner, privateChannelReaderPubkey, receivers: [receiverPubkey], receiverTag: receiverPubkey, deletionPubkey: deletion.deletionPubkey, event: wireEvent, relays, relayToReceivers, recoveryRelays, expirationSeconds, temporaryStorageArea, fileChunkIndex, onPreparedSeed, _getIykcProofs, _publish })
 
   return withDelivery({ question }, reports, deletion.deletionSeckey)
 }
@@ -609,6 +613,8 @@ export async function reply ({
   deletionPubkey,
   deletionSeckey,
   autoDeletionCapability = true,
+  fileChunkIndex,
+  onPreparedSeed,
   _publish = privateChannel.publish
 }) {
   if (!question?.id) throw new ValidationError('QUESTION_REQUIRED')
@@ -622,7 +628,7 @@ export async function reply ({
     })
   })
   const deletion = resolveDeletionCapability({ deletionPubkey, deletionSeckey, autoDeletionCapability })
-  const reports = await sendPrivateMessage({ senderSigner, imkcSigner, privateChannelSigner, privateChannelReaderPubkey, receivers: [receiverPubkey], receiverTag: receiverPubkey, deletionPubkey: deletion.deletionPubkey, event: wireEvent, relays, relayToReceivers, recoveryRelays, expirationSeconds, temporaryStorageArea, _getIykcProofs, _publish })
+  const reports = await sendPrivateMessage({ senderSigner, imkcSigner, privateChannelSigner, privateChannelReaderPubkey, receivers: [receiverPubkey], receiverTag: receiverPubkey, deletionPubkey: deletion.deletionPubkey, event: wireEvent, relays, relayToReceivers, recoveryRelays, expirationSeconds, temporaryStorageArea, fileChunkIndex, onPreparedSeed, _getIykcProofs, _publish })
   return withDelivery({ reply: event }, reports, deletion.deletionSeckey)
 }
 
@@ -646,6 +652,8 @@ export async function tell ({
   deletionPubkey,
   deletionSeckey,
   autoDeletionCapability = true,
+  fileChunkIndex,
+  onPreparedSeed,
   _publish = privateChannel.publish
 }) {
   if (!receiverPubkey) throw new ValidationError('RECEIVER_PUBKEY_REQUIRED')
@@ -658,7 +666,7 @@ export async function tell ({
     })
   })
   const deletion = resolveDeletionCapability({ deletionPubkey, deletionSeckey, autoDeletionCapability })
-  const reports = await sendPrivateMessage({ senderSigner, imkcSigner, privateChannelSigner, privateChannelReaderPubkey, receivers: [receiverPubkey], receiverTag: receiverPubkey, deletionPubkey: deletion.deletionPubkey, event: wireEvent, relays, relayToReceivers, recoveryRelays, expirationSeconds, temporaryStorageArea, _getIykcProofs, _publish })
+  const reports = await sendPrivateMessage({ senderSigner, imkcSigner, privateChannelSigner, privateChannelReaderPubkey, receivers: [receiverPubkey], receiverTag: receiverPubkey, deletionPubkey: deletion.deletionPubkey, event: wireEvent, relays, relayToReceivers, recoveryRelays, expirationSeconds, temporaryStorageArea, fileChunkIndex, onPreparedSeed, _getIykcProofs, _publish })
   return withDelivery({ tell: event }, reports, deletion.deletionSeckey)
 }
 
@@ -682,6 +690,8 @@ export async function yell ({
   deletionPubkey,
   deletionSeckey,
   autoDeletionCapability = true,
+  fileChunkIndex,
+  onPreparedSeed,
   _publish = privateChannel.publish
 }) {
   const receivers = uniq(receiverPubkeys)
@@ -695,7 +705,7 @@ export async function yell ({
     })
   })
   const deletion = resolveDeletionCapability({ deletionPubkey, deletionSeckey, autoDeletionCapability })
-  const reports = await sendPrivateMessage({ senderSigner, imkcSigner, privateChannelSigner, privateChannelReaderPubkey, receivers, receiverTag: '', deletionPubkey: deletion.deletionPubkey, event: wireEvent, relays, relayToReceivers, recoveryRelays, expirationSeconds, temporaryStorageArea, _getIykcProofs, _publish })
+  const reports = await sendPrivateMessage({ senderSigner, imkcSigner, privateChannelSigner, privateChannelReaderPubkey, receivers, receiverTag: '', deletionPubkey: deletion.deletionPubkey, event: wireEvent, relays, relayToReceivers, recoveryRelays, expirationSeconds, temporaryStorageArea, fileChunkIndex, onPreparedSeed, _getIykcProofs, _publish })
   return withDelivery({ yell: event }, reports, deletion.deletionSeckey)
 }
 
@@ -715,13 +725,15 @@ export async function broadcastRumor ({
   deletionPubkey,
   deletionSeckey,
   autoDeletionCapability = true,
+  fileChunkIndex,
+  onPreparedSeed,
   _publish = privateChannel.publish
 }) {
   const receivers = uniq(receiverPubkeys)
   if (!receivers.length) throw new ValidationError('NO_RECEIVERS')
   const { event, wireEvent } = await makeOutgoingRumor({ senderSigner, rumor })
   const deletion = resolveDeletionCapability({ deletionPubkey, deletionSeckey, autoDeletionCapability })
-  const reports = await sendPrivateMessage({ senderSigner, imkcSigner, privateChannelSigner, privateChannelReaderPubkey, receivers, receiverTag: '', deletionPubkey: deletion.deletionPubkey, event: wireEvent, relays, relayToReceivers, recoveryRelays, expirationSeconds, temporaryStorageArea, _getIykcProofs, _publish })
+  const reports = await sendPrivateMessage({ senderSigner, imkcSigner, privateChannelSigner, privateChannelReaderPubkey, receivers, receiverTag: '', deletionPubkey: deletion.deletionPubkey, event: wireEvent, relays, relayToReceivers, recoveryRelays, expirationSeconds, temporaryStorageArea, fileChunkIndex, onPreparedSeed, _getIykcProofs, _publish })
   return withDelivery({ rumor: event }, reports, deletion.deletionSeckey)
 }
 
@@ -741,13 +753,15 @@ export async function broadcastEvent ({
   deletionPubkey,
   deletionSeckey,
   autoDeletionCapability = true,
+  fileChunkIndex,
+  onPreparedSeed,
   _publish = privateChannel.publish
 }) {
   const receivers = uniq(receiverPubkeys)
   if (!receivers.length) throw new ValidationError('NO_RECEIVERS')
   const wireEvent = assertValidSignedEvent({ ...event, tags: cloneTags(event?.tags) })
   const deletion = resolveDeletionCapability({ deletionPubkey, deletionSeckey, autoDeletionCapability })
-  const reports = await sendPrivateMessage({ senderSigner, imkcSigner, privateChannelSigner, privateChannelReaderPubkey, receivers, receiverTag: '', deletionPubkey: deletion.deletionPubkey, event: wireEvent, relays, relayToReceivers, recoveryRelays, expirationSeconds, temporaryStorageArea, _getIykcProofs, _publish })
+  const reports = await sendPrivateMessage({ senderSigner, imkcSigner, privateChannelSigner, privateChannelReaderPubkey, receivers, receiverTag: '', deletionPubkey: deletion.deletionPubkey, event: wireEvent, relays, relayToReceivers, recoveryRelays, expirationSeconds, temporaryStorageArea, fileChunkIndex, onPreparedSeed, _getIykcProofs, _publish })
   return withDelivery({ event: wireEvent }, reports, deletion.deletionSeckey)
 }
 

package/private-messenger/file/README.md

@@ -0,0 +1,127 @@
+# 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 and supplies `storage.read(root, index, descriptor)` and
+`storage.save(event, descriptor)`. The latter 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.

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

@@ -0,0 +1,65 @@
+import { ValidationError } from '../../../error/index.js'
+import { createQueue } from '../../../idb-queue/index.js'
+
+const localLocks = new WeakMap()
+const keyFor = row => `${row.controlChannelPubkey}:${row.fileChannelPubkey}:${row.receiverPubkey}`
+
+// A grant contains no payload, key material or retention reference in the file
+// store. Serialize read/merge/write with other coordinators for this identity.
+export function createFileCatalog ({ messenger, now }) {
+  const prefix = `${messenger.prefix}:file-authorizations`
+  let database
+  const db = () => (database ??= createQueue({ prefix, indexedDB: messenger._indexedDB, evictionPolicy: 'reject', indexes: { key: { keyPath: 'key', unique: true }, channel: 'fileChannelPubkey' } }))
+  function lock (work) {
+    if (globalThis.navigator?.locks?.request) return navigator.locks.request(prefix, work)
+    let locks = localLocks.get(messenger._indexedDB)
+    if (!locks) localLocks.set(messenger._indexedDB, (locks = new Map()))
+    const task = (locks.get(prefix) || Promise.resolve()).catch(() => {}).then(work)
+    locks.set(prefix, task.catch(() => {}))
+    return task
+  }
+  function isValid (row) {
+    const parent = messenger.channels.get(row.controlChannelPubkey)
+    return parent?.mode === 'seeder' && row.expiresAt > now() && row.sharedAt + messenger.offlineRecoverySecondsFor(parent) > now()
+  }
+  async function put (file, receiverPubkey, sharedAt, expiresAt) {
+    const { controlChannelPubkey, fileChannelPubkey, peerPubkey, root, size } = file
+    const row = { controlChannelPubkey, fileChannelPubkey, peerPubkey, root, size, receiverPubkey, sharedAt, expiresAt }
+    row.key = keyFor(row)
+    if (!isValid(row)) return
+    const queue = await db()
+    const prior = await queue.getBy('key', row.key)
+    if (prior && (prior.root !== root || prior.peerPubkey !== peerPubkey)) throw new ValidationError('FILE_AUTHORIZATION_CONFLICT')
+    // Replaying an older share cannot shorten or renew a newer grant.
+    if (prior && prior.sharedAt >= sharedAt && isValid(prior)) return
+    await queue.putBy('key', row)
+  }
+  async function pruneUnlocked () {
+    await (await db()).removeWhere(row => !isValid(row))
+  }
+  const ready = lock(pruneUnlocked)
+
+  return {
+    ready,
+    async authorize (file, receivers, sharedAt) {
+      await ready
+      return lock(async () => {
+        await pruneUnlocked()
+        const expiresAt = sharedAt + messenger.offlineRecoverySecondsFor(file.controlChannelPubkey)
+        for (const receiver of receivers) await put(file, receiver, sharedAt, expiresAt)
+      })
+    },
+    async find (controlChannelPubkey, fileChannelPubkey, receiverPubkey) {
+      await ready
+      return lock(async () => {
+        const queue = await db()
+        const key = keyFor({ controlChannelPubkey, fileChannelPubkey, receiverPubkey })
+        const row = await queue.getBy('key', key)
+        if (row && !isValid(row)) { await queue.removeBy('key', key); return null }
+        return row
+      })
+    },
+    async prune () { await ready; return lock(pruneUnlocked) },
+    async close () { await ready.catch(() => {}); await lock(async () => { if (database) await (await database.catch(() => null))?.close() }) }
+  }
+}

package/private-messenger/file/index.js

@@ -0,0 +1,413 @@
+import NMMR from 'nmmr'
+import { createFileCatalog } from './helpers/catalog.js'
+import { ValidationError } from '../../error/index.js'
+import { IRFS_CHUNK_BYTES, decodeIrfsChunk } from '../../irfs/index.js'
+import { createQueue } from '../../idb-queue/index.js'
+import * as channelTransport from '../../private-channel/index.js'
+import * as messages from '../../private-message/index.js'
+import { readFileChunkIndex } from '../../private-channel/helpers/event.js'
+import { compactSeedRouterRows, compactRecordsFromSeed, createEventReplyPacker, ROUTER_SEED_RECORD_TYPE } from '../recovery/index.js'
+
+export const FILE_CHUNKS_REQUEST_CODE = 'fileChunksRequest_p5cc'
+export const FILE_CHUNKS_REPLY_CODE = 'fileChunksReply_p5cc'
+export const IRFS_CHUNK_RECORD_TYPE = 'irfsChunk_v1'
+export const AUTO_DOWNLOAD_BYTES = 1024 * 1024
+export const FILE_REQUEST_CHUNKS = 16
+const HEX = /^[0-9a-f]{64}$/
+const now = () => Math.floor(Date.now() / 1000)
+
+export function fileChannelInfo (root) {
+  if (typeof root !== 'string' || !HEX.test(root)) throw new ValidationError('INVALID_FILE_ROOT')
+  return `dm:media:${root}`
+}
+
+export function decodeMissingRanges (ranges) {
+  if (!Array.isArray(ranges) || !ranges.length) throw new ValidationError('INVALID_FILE_CHUNK_RANGES')
+  const indices = []
+  let previous = -1
+  for (const range of ranges) {
+    if (!Array.isArray(range) || range.length !== 2) throw new ValidationError('INVALID_FILE_CHUNK_RANGES')
+    const [first, last] = range
+    if (![first, last].every(Number.isSafeInteger) || first < 0 || first <= previous || last < first || last - first + 1 > FILE_REQUEST_CHUNKS - indices.length) throw new ValidationError('INVALID_FILE_CHUNK_RANGES')
+    for (let index = first; index <= last; index++) indices.push(index)
+    previous = last
+  }
+  return indices
+}
+
+function rangesFor (indices) {
+  const ranges = []
+  for (const index of indices) {
+    const last = ranges.at(-1)
+    if (last && last[1] + 1 === index) last[1] = index
+    else ranges.push([index, index])
+  }
+  return ranges
+}
+
+function assertPublished (result) {
+  const reports = result?.delivery?.reports
+  if (!Array.isArray(reports) || !reports.length || !reports.every(report => report?.success === true)) throw Object.assign(new Error('FILE_NOT_PUBLISHED'), { code: 'MESSAGE_NOT_PUBLISHED' })
+}
+
+function waitForTransfer (promise, signal) {
+  signal?.throwIfAborted()
+  if (!signal) return promise
+  return new Promise((resolve, reject) => {
+    const aborted = () => reject(signal.reason)
+    signal.addEventListener('abort', aborted, { once: true })
+    promise.then(resolve, reject).finally(() => signal.removeEventListener('abort', aborted))
+  })
+}
+
+// One coordinator per account. Signer derivation and the local IRFS database
+// belong to the caller; recovery, validation and scheduling belong here.
+export function createPrivateFileTransfer ({ messenger, resolveChannel, storage, onError = () => {}, _transport = channelTransport, _messages = messages, _hedgeMs = 2000, _idleMs = 30000, _now = now }) {
+  if (!messenger?.extensions || typeof resolveChannel !== 'function' || !storage?.read || !storage?.save) throw new ValidationError('INVALID_FILE_TRANSFER_OPTIONS')
+  const registrations = new Map()
+  const jobs = new Map()
+  const listeners = new Set()
+  const successes = new Map()
+  const work = new Set()
+  const requests = []
+  let replying = 0
+  let active = 0
+  let closed = false
+  let queuePromise
+  const queue = () => (queuePromise ??= createQueue({ prefix: `${messenger.prefix}:file-seeds`, indexedDB: messenger._indexedDB, maxBytes: 64 * 1024 * 1024, evictionPolicy: 'fifo', indexes: { key: { keyPath: 'key', unique: true }, channel: 'fileChannelPubkey' } }))
+  const catalog = createFileCatalog({ messenger, now: _now })
+  catalog.ready.catch(onError)
+  const keyFor = (control, root) => `${control}:${root}`
+  const emit = job => { for (const listener of listeners) listener({ root: job.file.root, controlChannelPubkey: job.file.controlChannelPubkey, status: job.status, completed: job.completed, total: job.file.size, error: job.error }) }
+  const usable = file => {
+    if (closed) throw new Error('FILE_TRANSFER_CLOSED')
+    messenger.requireWritableChannel(file.controlChannelPubkey)
+    if (!messenger.desiredChannels.has(file.controlChannelPubkey)) throw new Error('FILE_TRANSFER_CHANNEL_UNWATCHED')
+  }
+  async function register ({ controlChannelPubkey, peerPubkey, root, size, sharedAt }) {
+    fileChannelInfo(root)
+    if (!HEX.test(controlChannelPubkey) || !HEX.test(peerPubkey) || (size !== undefined && (!Number.isSafeInteger(size) || size < 1))) throw new ValidationError('INVALID_FILE_TRANSFER_DESCRIPTOR')
+    if (sharedAt !== undefined && (!Number.isSafeInteger(sharedAt) || sharedAt < 0)) throw new ValidationError('INVALID_FILE_SHARED_AT')
+    const key = keyFor(controlChannelPubkey, root)
+    const previous = registrations.get(key)
+    if (previous && (previous.peerPubkey !== peerPubkey || (size !== undefined && previous.size !== undefined && previous.size !== size))) throw new ValidationError('CONFLICTING_FILE_TRANSFER_DESCRIPTOR')
+    const file = previous || { controlChannelPubkey, peerPubkey, root }
+    if (size !== undefined) file.size = size
+    if (sharedAt !== undefined) file.sharedAt = Math.max(file.sharedAt ?? 0, sharedAt)
+    registrations.set(key, file)
+    file.ready ||= (async () => {
+      file.signer = await resolveChannel({ controlChannelPubkey, peerPubkey, root, info: fileChannelInfo(root) })
+      file.fileChannelPubkey = await file.signer.getPublicKey()
+      if (!HEX.test(file.fileChannelPubkey)) throw new ValidationError('INVALID_FILE_CHANNEL_PUBKEY')
+    })().catch(error => { if (registrations.get(key) === file) registrations.delete(key); throw error })
+    await file.ready
+    return file
+  }
+  function seedEnabled (file) {
+    const parent = messenger.channels.get(file.controlChannelPubkey)
+    return ['seeder', 'watchtower'].includes(parent?.mode) && messenger.offlineRecoverySecondsFor(parent) > 0
+  }
+  async function authorizeSeeding (descriptor, { receiverPubkeys, sharedAt } = {}) {
+    if (!Array.isArray(receiverPubkeys) || !receiverPubkeys.length || !receiverPubkeys.every(key => typeof key === 'string' && HEX.test(key))) throw new ValidationError('INVALID_FILE_AUTHORIZATION_RECEIVERS')
+    if (!Number.isSafeInteger(sharedAt) || sharedAt < 0) throw new ValidationError('INVALID_FILE_SHARED_AT')
+    const file = await register(descriptor)
+    usable(file)
+    await catalog.authorize(file, [...new Set(receiverPubkeys)], sharedAt)
+  }
+  async function prune () {
+    await catalog.prune()
+    if (!queuePromise) return
+    await (await queue()).removeWhere(row => {
+      const parent = messenger.channels.get(row.controlChannelPubkey)
+      return parent?.mode !== 'watchtower' || !seedEnabled(row) || row.expiresAt <= _now() || row.receivedAt + messenger.offlineRecoverySecondsFor(parent) <= _now()
+    })
+  }
+  async function saveSeed (file, seed) {
+    if (messenger.channels.get(file.controlChannelPubkey)?.mode !== 'watchtower' || !seedEnabled(file)) return
+    const index = readFileChunkIndex(seed.router)
+    if (index === undefined) return
+    const db = await queue()
+    for (const row of compactSeedRouterRows(seed)) {
+      if (![file.peerPubkey, messenger.userPubkey].includes(row.receiverPubkey)) continue
+      const key = `${file.controlChannelPubkey}:${file.fileChannelPubkey}:${row.receiverPubkey}:${index}`
+      await db.putBy('key', { ...row, key, root: file.root, controlChannelPubkey: file.controlChannelPubkey, fileChannelPubkey: file.fileChannelPubkey, peerPubkey: file.peerPubkey, chunkIndex: index, receivedAt: _now(), expiresAt: _now() + messenger.offlineRecoverySecondsFor(file.controlChannelPubkey) })
+    }
+    await prune()
+  }
+  function checked (file, event, index) {
+    const decoded = decodeIrfsChunk(event)
+    if (decoded.root !== file.root || (index !== undefined && decoded.index !== index) || (file.size !== undefined && (decoded.total !== Math.ceil(file.size / IRFS_CHUNK_BYTES) || (decoded.index === decoded.total - 1 && decoded.contentBytes.length !== file.size - decoded.index * IRFS_CHUNK_BYTES)))) throw new ValidationError('FILE_CHUNK_DESCRIPTOR_MISMATCH')
+    return decoded
+  }
+  async function routing (file, receiverPubkey) {
+    const parent = messenger.requireWritableChannel(file.controlChannelPubkey)
+    return messenger.resolveSendRouting({ channel: parent, receiverPubkeys: [receiverPubkey] })
+  }
+  function sendOptions (file, routes) {
+    return { senderSigner: messenger.userSigner, imkcSigner: messenger.contentKeySigner, privateChannelSigner: file.signer, ...routes, temporaryStorageArea: messenger.temporaryStorageArea, expirationSeconds: messenger.eventExpirationSecondsFor(file.controlChannelPubkey), _getIykcProofs: messenger.contentKeyLookup() }
+  }
+  async function publishChunk (descriptor, event) {
+    const file = await register(descriptor)
+    usable(file)
+    const decoded = checked(file, event)
+    await catalog.ready
+    const options = { ...sendOptions(file, await routing(file, file.peerPubkey)), receiverPubkeys: [file.peerPubkey], fileChunkIndex: decoded.index, ...(messenger.channels.get(file.controlChannelPubkey)?.mode === 'watchtower' ? { onPreparedSeed: seed => saveSeed(file, seed) } : {}) }
+    const result = event.sig ? await _messages.broadcastEvent({ ...options, event }) : await _messages.broadcastRumor({ ...options, rumor: event })
+    assertPublished(result)
+    // A scheduler turn between chunks lets queued text/control publications run.
+    await new Promise(resolve => setTimeout(resolve, 0))
+    return result
+  }
+  async function replyToRequest (controlChannelPubkey, message) {
+    if (message.payload?.code !== FILE_CHUNKS_REQUEST_CODE) return false
+    const question = message.question || message.event
+    if (message.provenance === 'hearsay' || message.senderPubkey !== question?.pubkey || question.tags?.find(tag => tag[0] === 'r')?.[1] !== messenger.userPubkey) return true
+    const payload = message.payload.payload
+    if (!HEX.test(payload?.fileChannelPubkey)) throw new ValidationError('INVALID_FILE_TRANSFER_DESCRIPTOR')
+    const indices = new Set(decodeMissingRanges(payload.missingRanges))
+    await prune()
+    const grant = await catalog.find(controlChannelPubkey, payload.fileChannelPubkey, question.pubkey)
+    if (grant) {
+      const file = await register(grant)
+      usable(file)
+      if (file.fileChannelPubkey !== payload.fileChannelPubkey) throw new ValidationError('FILE_CHANNEL_MISMATCH')
+      const routes = await routing(file, question.pubkey)
+      const packer = createEventReplyPacker({
+        messenger: {
+          reply: async options => {
+            usable(file)
+            if (!await catalog.find(controlChannelPubkey, file.fileChannelPubkey, question.pubkey)) return
+            return _messages.reply({ ...sendOptions(file, routes), ...options })
+          }
+        },
+        channelPubkey: file.fileChannelPubkey, question, receiverPubkey: question.pubkey,
+        code: FILE_CHUNKS_REPLY_CODE, eventsPerChunk: 1, recordsFromInput: record => [record]
+      })
+      for (const index of indices) {
+        usable(file)
+        if (!await catalog.find(controlChannelPubkey, file.fileChannelPubkey, question.pubkey)) break
+        const event = await storage.read(file.root, index, file)
+        if (!event) continue
+        let decoded
+        try { decoded = checked(file, event, index) } catch (error) { if (error instanceof ValidationError) { onError(error); continue } throw error }
+        const proof = event.tags.find(tag => tag[0] === 'mmr')[3]
+        await packer.update({ recordType: IRFS_CHUNK_RECORD_TYPE, index, total: decoded.total, proof, content: event.content })
+        await new Promise(resolve => setTimeout(resolve, 0))
+      }
+      await packer.finalize()
+      return true
+    }
+    if (messenger.channels.get(controlChannelPubkey)?.mode !== 'watchtower') return true
+    const db = await queue()
+    let packer
+    for await (const seed of db.storedItemsBy('channel', payload.fileChannelPubkey)) {
+      if (seed.controlChannelPubkey !== controlChannelPubkey || seed.receiverPubkey !== question.pubkey || !indices.has(seed.chunkIndex) || !seedEnabled(seed)) continue
+      const file = await register(seed)
+      usable(file)
+      if (file.fileChannelPubkey !== payload.fileChannelPubkey) throw new ValidationError('FILE_CHANNEL_MISMATCH')
+      if (!packer) {
+        const routes = await routing(file, question.pubkey)
+        packer = createEventReplyPacker({ messenger: { reply: async options => { usable(file); return _messages.reply({ ...sendOptions(file, routes), ...options }) } }, channelPubkey: file.fileChannelPubkey, question, receiverPubkey: question.pubkey, code: FILE_CHUNKS_REPLY_CODE, eventsPerChunk: 1, recordsFromInput: row => compactRecordsFromSeed(row, { receiverPubkey: question.pubkey }) })
+      }
+      await packer.update(seed)
+      await new Promise(resolve => setTimeout(resolve, 0))
+    }
+    await packer?.finalize()
+    return true
+  }
+  async function run (job) {
+    const file = job.file
+    const signal = job.controller.signal
+    let sub
+    const historyController = new AbortController()
+    let ingest = Promise.resolve()
+    let total = file.size === undefined ? undefined : Math.ceil(file.size / IRFS_CHUNK_BYTES)
+    const persisted = new Set()
+    let lastProgress = Date.now()
+    let requestRoundAt = Date.now()
+    const requestedSeeders = new Set()
+    const validSeeders = new Set([file.peerPubkey, ...messenger.recoverySeeders(file.controlChannelPubkey)])
+    let terminalError
+    const fail = error => { terminalError ||= error }
+    async function accept (event, index, { save = true } = {}) {
+      signal.throwIfAborted()
+      usable(file)
+      const chunk = checked(file, event, index)
+      if (total !== undefined && chunk.total !== total) throw new ValidationError('FILE_CHUNK_TOTAL_MISMATCH')
+      total = chunk.total
+      if (persisted.has(chunk.index)) return
+      if (save) await storage.save(event, file)
+      signal.throwIfAborted()
+      persisted.add(chunk.index)
+      job.completed += chunk.contentBytes.length
+      lastProgress = Date.now()
+      if (chunk.index === total - 1 && file.size === undefined) file.size = (total - 1) * IRFS_CHUNK_BYTES + chunk.contentBytes.length
+      emit(job)
+    }
+    const consume = (event, outer, meta) => {
+      const task = ingest.then(async () => {
+        if (signal.aborted) return
+        if (event.kind === messages.REPLY_KIND) {
+          const reply = messages.parseRumorContent(event)
+          if (reply.code !== FILE_CHUNKS_REPLY_CODE || meta.provenance === 'hearsay' || meta.senderPubkey !== event.pubkey || !validSeeders.has(event.pubkey) || event.tags?.find(tag => tag[0] === 'r')?.[1] !== messenger.userPubkey) return
+          const jsonl = reply.payload?.jsonl
+          if (typeof jsonl !== 'string') throw new ValidationError('INVALID_FILE_CHUNK_REPLY')
+          const rows = jsonl.split('\n').filter(Boolean)
+          if (rows.length > FILE_REQUEST_CHUNKS) throw new ValidationError('INVALID_FILE_CHUNK_REPLY')
+          for (const line of rows) {
+            let record
+            try { record = JSON.parse(line) } catch { throw new ValidationError('INVALID_FILE_CHUNK_REPLY') }
+            if (record.recordType === IRFS_CHUNK_RECORD_TYPE) {
+              if (!Number.isSafeInteger(record.index) || record.index < 0 || !Number.isSafeInteger(record.total) || record.total <= record.index || typeof record.content !== 'string' || record.content.length > 100000 || typeof record.proof !== 'string' || record.proof.length > 8192) throw new ValidationError('INVALID_FILE_CHUNK_REPLY')
+              const chunk = { kind: 34601, created_at: event.created_at, tags: [['d', NMMR.deriveChunkId(file.root, record.index)], ['mmr', String(record.index), String(record.total), record.proof]], content: record.content }
+              await accept(chunk, record.index)
+              successes.set(event.pubkey, Date.now())
+              continue
+            }
+            if (record.recordType !== ROUTER_SEED_RECORD_TYPE) continue
+            const index = readFileChunkIndex(record.router)
+            if (index === undefined) throw new ValidationError('INVALID_FILE_CHUNK_INDEX')
+            const original = await _transport.unwrapRouterEvent({ router: record.router, receiverSigner: messenger.userSigner, receiverPubkey: messenger.userPubkey, channelPubkey: file.fileChannelPubkey })
+            if (original) { await accept(original, index); successes.set(event.pubkey, Date.now()) }
+          }
+        } else {
+          if (meta.senderPubkey !== file.peerPubkey) return
+          const index = readFileChunkIndex(meta.router)
+          if (index === undefined) throw new ValidationError('INVALID_FILE_CHUNK_INDEX')
+          await accept(event, index)
+          // Only direct, validated delivery proves this identity was a recipient.
+          // Local cache hits and recovery replies never create/renew a grant.
+          if (file.sharedAt !== undefined) await authorizeSeeding(file, { receiverPubkeys: [messenger.userPubkey], sharedAt: file.sharedAt })
+        }
+      })
+      // Malformed remote records do not poison the ingestion chain. Operational
+      // persistence failures stop the job so completion cannot outrun storage.
+      ingest = task.catch(error => { if (error instanceof ValidationError) onError(error); else if (!signal.aborted) fail(error) })
+      return ingest
+    }
+    try {
+      job.status = 'downloading'; emit(job)
+      // Resume from independently verified local chunks, never from an ACK.
+      for (let index = 0; index < (total ?? 1); index++) {
+        signal.throwIfAborted()
+        const event = await storage.read(file.root, index, file)
+        if (event) await accept(event, index, { save: false })
+      }
+      if (total !== undefined && persisted.size === total) return
+      const parent = messenger.requireWritableChannel(file.controlChannelPubkey)
+      const relays = await messenger.resolveWatchRelays(parent)
+      const options = { receiverSigner: messenger.userSigner, privateChannelSigner: file.signer, privateChannelPubkey: file.fileChannelPubkey, receiverPubkey: messenger.userPubkey, relays, receivedChunkIndexedDB: messenger._indexedDB, receivedChunkScope: `${messenger.userPubkey}:file:${file.fileChannelPubkey}`, onEvent: consume, onSeedEvent: seed => saveSeed(file, seed), mode: messenger.channels.get(file.controlChannelPubkey)?.mode === 'watchtower' ? 'watchtower' : 'leecher', onError }
+      sub = _transport.subscribe({ ...options, liveOnly: true })
+      const stop = () => { sub?.close() }
+      signal.addEventListener('abort', stop, { once: true })
+      try {
+        await sub.ready
+        signal.throwIfAborted()
+        // Partial/failed history still permits recovery from peers.
+        const history = _transport.fetch({ ...options, signal: AbortSignal.any([signal, historyController.signal]), since: 0 }).catch(error => { if (!signal.aborted) onError(error) })
+        work.add(history); history.finally(() => work.delete(history))
+        const seeders = [...validSeeders].sort((a, b) => (successes.get(b) || 0) - (successes.get(a) || 0) || Math.random() - 0.5)
+        while (true) {
+          signal.throwIfAborted(); usable(file)
+          await ingest
+          if (terminalError) throw terminalError
+          if (total !== undefined && persisted.size === total) break
+          const missing = []
+          for (let index = 0; index < (total ?? 1) && missing.length < FILE_REQUEST_CHUNKS; index++) if (!persisted.has(index)) missing.push(index)
+          const remaining = seeders.filter(peer => !requestedSeeders.has(peer))
+          if (remaining.length && Date.now() >= requestRoundAt) {
+            const peer = remaining[0]
+            requestedSeeders.add(peer)
+            requestRoundAt = Date.now() + _hedgeMs
+            // The request is on dm; its compact reply is on the file channel.
+            await messenger.ask({ channelPubkey: file.controlChannelPubkey, receiverPubkey: peer, code: FILE_CHUNKS_REQUEST_CODE, payload: { fileChannelPubkey: file.fileChannelPubkey, missingRanges: rangesFor(missing) } }).catch(onError)
+          }
+          if (!remaining.length && Date.now() - Math.max(lastProgress, requestRoundAt - _hedgeMs) >= _idleMs) throw new Error('FILE_DOWNLOAD_STALLED')
+          // Start a fresh batch when all positions of the previous batch arrived.
+          if (job.batch?.every(index => persisted.has(index))) { requestedSeeders.clear(); requestRoundAt = Date.now(); job.batch = null }
+          job.batch ||= missing
+          await new Promise(resolve => { const timer = setTimeout(done, Math.min(100, _hedgeMs)); function done () { clearTimeout(timer); signal.removeEventListener('abort', done); resolve() } signal.addEventListener('abort', done, { once: true }) })
+        }
+      } finally { signal.removeEventListener('abort', stop) }
+    } finally { historyController.abort(); await sub?.close(); await ingest }
+    if (job.completed !== file.size) throw new ValidationError('FILE_SIZE_MISMATCH')
+  }
+  function pump () {
+    if (closed) return
+    for (const job of [...jobs.values()].filter(job => job.status === 'queued').sort((a, b) => b.priority - a.priority)) {
+      if (active >= 2) break
+      active++; job.status = 'starting'
+      const task = run(job).then(() => { job.status = 'complete'; emit(job); job.resolve(job.file) }, error => { job.status = job.pauseRequested ? 'paused' : job.controller.signal.aborted ? 'cancelled' : 'error'; job.error = error; emit(job); job.reject(error) }).finally(() => { active--; work.delete(task); pump() })
+      work.add(task)
+    }
+  }
+  async function download (descriptor, { manual = false, thumbnail = false, signal } = {}) {
+    const file = await register(descriptor)
+    usable(file)
+    const existing = jobs.get(keyFor(file.controlChannelPubkey, file.root))
+    if (existing && !['error', 'cancelled', 'paused'].includes(existing.status)) return waitForTransfer(existing.promise, signal)
+    if (!manual && (file.size === undefined || file.size > (thumbnail ? IRFS_CHUNK_BYTES : AUTO_DOWNLOAD_BYTES))) {
+      // Locally complete files need no network consent, including the sender's
+      // own originals and files already downloaded before a restart.
+      let total, completed = 0
+      for (let index = 0; index < (total ?? 1); index++) {
+        signal?.throwIfAborted(); usable(file)
+        const event = await storage.read(file.root, index, file)
+        if (!event) throw new Error('FILE_DOWNLOAD_REQUIRES_ACTION')
+        const chunk = checked(file, event, index)
+        if (total !== undefined && total !== chunk.total) throw new ValidationError('FILE_CHUNK_TOTAL_MISMATCH')
+        total = chunk.total; completed += chunk.contentBytes.length
+      }
+      file.size ??= completed
+      if (completed !== file.size) throw new ValidationError('FILE_SIZE_MISMATCH')
+      const job = { file, completed, status: 'complete', promise: Promise.resolve(file) }
+      jobs.set(keyFor(file.controlChannelPubkey, file.root), job); emit(job)
+      return file
+    }
+    const key = keyFor(file.controlChannelPubkey, file.root)
+    let job = jobs.get(key)
+    if (!job || ['error', 'cancelled', 'paused'].includes(job.status)) {
+      const controller = new AbortController()
+      const { promise, resolve, reject } = Promise.withResolvers()
+      job = { file, controller, resolve, reject, promise, completed: 0, manual, thumbnail, priority: thumbnail ? 2 : manual ? 1 : 0, status: 'queued' }
+      jobs.set(key, job); emit(job); pump()
+    }
+    // A view leaving does not cancel another consumer's shared download.
+    return waitForTransfer(job.promise, signal)
+  }
+  const cancelJob = job => {
+    if (['complete', 'error', 'cancelled'].includes(job.status)) return
+    const error = new DOMException('Download cancelled', 'AbortError')
+    job.controller.abort(error)
+    if (job.status === 'queued') { job.status = job.pauseRequested ? 'paused' : 'cancelled'; job.reject(error); emit(job) }
+  }
+  function drainRequests () {
+    if (closed) return
+    while (replying < 2 && requests.length) {
+      const [channel, message] = requests.shift()
+      replying++
+      const task = replyToRequest(channel, message).catch(error => { if (!(closed && error.message === 'FILE_TRANSFER_CLOSED')) onError(error) }).finally(() => { replying--; work.delete(task); drainRequests() })
+      work.add(task)
+    }
+  }
+  const extension = {
+    handleAsk (channel, message) {
+      if (message.payload?.code !== FILE_CHUNKS_REQUEST_CODE) return false
+      // Never hold the DM dispatcher while publishing a batch of file bytes.
+      // Bound both workers and queued requests; discarded excess is retryable.
+      if (!closed && requests.length < 16) { requests.push([channel, message]); drainRequests() }
+      return true
+    },
+    pause () { requests.length = 0; for (const job of jobs.values()) { if (!['complete', 'error', 'cancelled'].includes(job.status)) job.pauseRequested = true; cancelJob(job) } },
+    async resume () {
+      await Promise.allSettled([...work])
+      for (const job of jobs.values()) if (job.pauseRequested && job.status !== 'complete') download(job.file, { manual: job.manual, thumbnail: job.thumbnail }).catch(onError)
+    },
+    unwatch (channels) { for (const job of jobs.values()) if (channels.includes(job.file.controlChannelPubkey)) cancelJob(job) },
+    async close () { if (closed) return; closed = true; extension.pause(); clearInterval(timer); await Promise.allSettled([...work]); await catalog.close(); if (queuePromise) await (await queuePromise).close(); messenger.extensions.delete(extension); listeners.clear() }
+  }
+  const timer = setInterval(() => { prune().catch(onError) }, 60000)
+  timer.unref?.()
+  messenger.extensions.add(extension)
+  return { register, authorizeSeeding, publishChunk, download, close: extension.close, cancel (control, root) { const job = jobs.get(keyFor(control, root)); if (job) { job.pauseRequested = false; cancelJob(job) } }, observe (listener) { listeners.add(listener); for (const job of jobs.values()) emit(job); return () => listeners.delete(listener) } }
+}

package/private-messenger/index.js

@@ -265,6 +265,7 @@ export class PrivateMessenger {
     this.state = { channels: {} }
     this.stateWriteTail = Promise.resolve()
     this.stateWriteError = null
+    this.extensions = new Set()
     this.channels = new Map()
     this.stopByChannel = new Map()
     this.desiredChannels = new Set()
@@ -1128,6 +1129,7 @@ export class PrivateMessenger {
 
   unwatch (channels) {
     const pubkeys = channels ? uniq(Array.isArray(channels) ? channels : [channels]) : [...this.desiredChannels]
+    for (const extension of this.extensions) extension.unwatch?.(pubkeys)
     for (const pubkey of pubkeys) this.desiredChannels.delete(pubkey)
     this.recordInterruption(pubkeys)
     for (const controller of this.recoveryControllers) {
@@ -1140,6 +1142,7 @@ export class PrivateMessenger {
     if (typeof reason !== 'string' || !reason.trim()) throw new ValidationError('PAUSE_REASON_REQUIRED')
     this.assertOpen()
     this.pauseReasons.add(reason)
+    for (const extension of this.extensions) extension.pause?.()
     this.recordInterruption(this.desiredChannels)
     for (const controller of this.recoveryControllers) controller.abort()
     return Promise.all([this.stopWatches([...this.desiredChannels]), this.flushStateWrites()])
@@ -1164,6 +1167,7 @@ export class PrivateMessenger {
       if (this.pauseReasons.size || this.closePromise) return
       await this.reconcilePresencePublishers()
       await this.recoverOfflineRanges(channels)
+      for (const extension of this.extensions) await extension.resume?.()
     })()
     this.resumeWork = work
     try { await work } catch (err) {
@@ -1238,6 +1242,7 @@ export class PrivateMessenger {
   async handleAsk (channelPubkey, message) {
     if (message.provenance === 'hearsay') return this.enqueueRumor('message', channelPubkey, message)
     this.trackSeederActivity(channelPubkey, message)
+    for (const extension of this.extensions) if (await extension.handleAsk?.(channelPubkey, message)) return
     if (doesModeStoreRecoverySeeds(this.channels.get(channelPubkey)?.mode) && messageCode(message) === MISSING_MESSAGES_ASK_CODE) {
       await this.replyWithStoredSeeds(channelPubkey, message)
       return
@@ -1329,6 +1334,11 @@ export class PrivateMessenger {
     this.onMessageQueued?.()
   }
 
+  outgoingSeedHandler (channelPubkey) {
+    if (!doesModeStoreRecoverySeeds(this.channels.get(channelPubkey)?.mode) || !this.offlineRecoverySecondsFor(channelPubkey)) return undefined
+    return seed => this.enqueueSeed(channelPubkey, seed)
+  }
+
   async enqueueSeed (channelPubkey, seed) {
     if (!this.offlineRecoverySecondsFor(channelPubkey)) return
     const receivedAt = nowSeconds()
@@ -1494,6 +1504,7 @@ export class PrivateMessenger {
       payload,
       error,
       content,
+      onPreparedSeed: this.outgoingSeedHandler(channelPubkey),
       _getIykcProofs: this.contentKeyLookup()
     })
   }
@@ -1520,6 +1531,7 @@ export class PrivateMessenger {
       payload,
       error,
       content,
+      onPreparedSeed: this.outgoingSeedHandler(channelPubkey),
       _getIykcProofs: this.contentKeyLookup()
     })
   }
@@ -1544,6 +1556,7 @@ export class PrivateMessenger {
       payload,
       error,
       content,
+      onPreparedSeed: this.outgoingSeedHandler(channelPubkey),
       _getIykcProofs: this.contentKeyLookup()
     })
   }
@@ -1568,6 +1581,7 @@ export class PrivateMessenger {
       payload,
       error,
       content,
+      onPreparedSeed: this.outgoingSeedHandler(channelPubkey),
       _getIykcProofs: this.contentKeyLookup()
     })
   }
@@ -1588,6 +1602,7 @@ export class PrivateMessenger {
       deletionPubkey,
       autoDeletionCapability: this.autoDeletionCapabilityFor(channel),
       rumor,
+      onPreparedSeed: this.outgoingSeedHandler(channelPubkey),
       _getIykcProofs: this.contentKeyLookup()
     })
   }
@@ -1608,6 +1623,7 @@ export class PrivateMessenger {
       deletionPubkey,
       autoDeletionCapability: this.autoDeletionCapabilityFor(channel),
       event,
+      onPreparedSeed: this.outgoingSeedHandler(channelPubkey),
       _getIykcProofs: this.contentKeyLookup()
     })
   }
@@ -1664,6 +1680,7 @@ export class PrivateMessenger {
       autoDeletionCapability: this.autoDeletionCapabilityFor(channel),
       code: SEEDER_PRESENCE_CODE,
       payload: {},
+      onPreparedSeed: this.outgoingSeedHandler(channelPubkey),
       _getIykcProofs: this.contentKeyLookup()
     })
   }
@@ -2177,6 +2194,7 @@ export class PrivateMessenger {
       let unwatchError
       try { await unwatchPromise } catch (err) { unwatchError = err }
       await initSettledPromise
+      await Promise.all([...this.extensions].map(extension => extension.close?.()))
       await this.stampActiveChannelActivity()
       await this.queueOperationTail
       await Promise.allSettled([...this.recoveries.values()])

package/private-messenger/recovery/index.js

@@ -193,7 +193,7 @@ function compactNymCarriersFromSeed (seed, { since, until }) {
   }]
 }
 
-function compactRecordsFromSeed (seed, { receiverPubkey, since, until }) {
+export function compactRecordsFromSeed (seed, { receiverPubkey, since, until }) {
   if (seed?.recordType === NYM_CARRIER_SEED_RECORD_TYPE) {
     return compactNymCarriersFromSeed(seed, { since, until })
   }

package/private-messenger/services/storage-maintenance.js

@@ -186,6 +186,8 @@ function storageDatabaseNames (userPubkey) {
   return [
     `${prefix}:idb-queue`,
     `${prefix}:seeds:idb-queue`,
+    `${prefix}:file-seeds:idb-queue`,
+    `${prefix}:file-authorizations:idb-queue`,
     `${prefix}:state:idb`
   ]
 }