libp2r2p 0.10.28 → 0.11.1

package/README.md

@@ -890,3 +890,26 @@ 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.
+
+Private-message consumers can now substitute recovery persistence through
+[`private-messenger/event-store`](private-messenger/event-store/README.md), or use
+local defaults, including a bounded streaming file cache. The optional
+[`private-messenger/session`](private-messenger/session/README.md) coordinator
+provides reusable DM inbox/outbox and attachment lifecycle without UI coupling.

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.28",
+  "version": "0.11.1",
   "description": "Peer-to-relay-to-peer",
   "keywords": [
     "p2r2p",
@@ -86,7 +86,10 @@
     "./private-channel": "./private-channel/index.js",
     "./private-message": "./private-message/index.js",
     "./private-messenger": "./private-messenger/index.js",
+    "./private-messenger/event-store": "./private-messenger/event-store/index.js",
+    "./private-messenger/file": "./private-messenger/file/index.js",
     "./private-messenger/recovery": "./private-messenger/recovery/index.js",
+    "./private-messenger/session": "./private-messenger/session/index.js",
     "./relay": "./relay/index.js",
     "./temporary-storage": "./temporary-storage/index.js",
     "./url": "./url/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/index.js

@@ -18,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'
@@ -131,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)
@@ -144,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({
@@ -152,6 +160,7 @@ async function * wrapPreparedEvents ({ privateChannelSigner, receivers, receiver
         imkcPubkey: context.imkcPubkey,
         imkcProof: context.imkcProof,
         receiverPubkey: routerReceiverTag,
+        fileChunkIndex,
         chunkIndex: index,
         chunkTotal: total,
         content
@@ -172,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,
@@ -185,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)
   }
@@ -415,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
 
@@ -506,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
@@ -524,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)))
         }
       }
@@ -534,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
@@ -765,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
 
@@ -773,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),
@@ -976,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/event-store/README.md

@@ -0,0 +1,110 @@
+# Event-store adapters
+
+`createPersonalCopyRecoveryStorage({ eventStore, signer })` returns `seeds`,
+`authorizations`, and `close()`. Pass these to `PrivateMessenger` (`seedStorage`)
+and `createPrivateFileTransfer` (`seedStorage`, `authorizationStorage`). The owner
+signer and event store must address the same identity. There is no `window` access
+and no launcher-specific private database API.
+
+The signer exposes `getPublicKey`, `obfuscate(value, kind, scope)`, and byte-based
+`nip44v3.decrypt(peer, kind, scope, ciphertext)`. The store exposes the existing
+`query`, `addPersonalCopy`, and `remove` API. Queries require `&tags`, `!ids`,
+`search:sort:desc`, and the personal-copy mirrors used by 44billion. Returned
+wrappers remain encrypted until the adapter decrypts them. The adapter bounds memoized obfuscations (256) and decrypted grants (128); every
+grant use still queries the store, so removal is immediately effective. Permission, lock,
+read-only, quota and operational failures propagate; they are not empty results.
+Expiry cleanup uses the signed wrapper expiration preserved by personal copies,
+without decrypting the archive; the store may also purge expired wrappers itself.
+
+## Contracts and ownership
+
+- Seeds: `put(record)`, `iterate(query)`, `has(record)`, `removeLocal(query)`,
+  `prune({ now })`, and `revoke(records)`.
+- Authorizations: the same operations plus `find(query)`, choosing the newest
+  valid share, then the shorter expiry and lexicographically smaller record ID.
+- `iterate` is an async generator. Queries can name `recordId`, `channelPubkey`,
+  `receiverPubkey`, `since`/`until`, or the file tuple `controlChannelPubkey`,
+  `fileChannelPubkey`, `receiverPubkey`, and `indices`. `signal` cancels reads.
+- The messenger/coordinator never closes caller-owned adapters. Close their
+  owner factory after the consumers. No ciphertext is duplicated into a local
+  library queue. Limits and storage admission belong to the event store.
+- `createEventStoreChunkStorage({ eventStore })` implements `read`/`save` for
+  IRFS chunks. Reconstruction saves an owner template, not a forged announcer
+  identity. NostrDB keeps the usual deduplicated payloads and root references.
+- `createEventStoreMessageStorage({ eventStore })` implements
+  `save(event, { peerPubkey, hearsay })`, preserving the DM context/provenance.
+
+Local defaults remain available when the corresponding adapter is omitted.
+Registration, cache reads and recovery requests never grant file access. A grant
+neither pins chunks nor contains signer material. Synced timestamps never renew
+retention. Missing channel configuration is not a distributed revocation.
+
+## Immutable inner events
+
+Recovery data uses self-authored kind 30078 templates, `content: ''`, personal
+copy context `''`, and no hearsay. Coordinates are
+`libp2r2p:recovery:seed:<id>` / `libp2r2p:recovery:grant:<id>` (no schema version
+in `d`). Data changes create another snapshot. Imports preserve authored times;
+identical writes query their coordinate and do not re-encrypt/revise it.
+
+`id` is lowercase SHA-256 of UTF-8 `JSON.stringify([type, bodyTags])`, where
+`type` is `seed` or `grant` and body tags follow the fixed encoder order below.
+`d`, `t`, `s`, `D`, and CRDT decorations are derived, not hash inputs. The body
+includes expiration. Original strings starting with `%` or `~` escape that first
+character as `%25` or `%7E`; decoding reverses exactly one prefix. This protects
+preserved strings from CRDT metadata interpretation. Numbers are canonical
+nonnegative decimal strings. The decoder rebuilds and verifies all tags and the
+coordinate, tolerating only the store's reserved CRDT decorations.
+
+Grant body, in order: `c` (control channel), `channel` (data channel), `peer`,
+`p` (recipient), `root`, optional `size`, `shared`, `expiration`. There is no `r`
+root reference: a grant must not retain file bytes. Creation time is `shared`.
+
+Router seed body: `c` (data/ordinary channel), `type=routerEnvelopeRow_v1`, `p`,
+`router` (pubkey, original timestamp), numbered `router-tag` entries (original
+transport `c` removed), `payload`, `key`, optional `iykc` (remaining envelope
+fields), optional `event` (known inner ID), `range` (first/last), optional `file`
+(control channel, peer, root) plus `received`, and `expiration`. Kind 26300 is
+implied by the record type. The original router's `i` supplies the file index.
+The wire reply still reconstructs the existing JSONL rows; no network codec was
+replaced. File seed creation time is `received`; ordinary seed time is range end.
+
+Carrier seed body: `c`, `type=nymCarrier_v1`, numbered `carrier` entries containing
+kind/pubkey/timestamp/ID/signature/content, their numbered `carrier-tag` entries
+with `carrierIndex:tagIndex` identities, `range`, `expiration`. Signatures and
+original tag order are verified/preserved. Range/creation time uses the maximum
+carrier timestamp, as the existing recovery codec does.
+
+All snapshots have `t=libp2r2p:recovery:<type>` and selector `s`. Selector hashes
+use the same UTF-8 JSON/SHA-256 operation on:
+
+- `['grant', control, data, recipient]`
+- `['seed', channel, recipientOrEmpty]`
+- `['file', control, data, recipient, chunkIndex]`
+
+Ordinary seeds also carry every UTC Unix day in their interval (`D`, 86400 seconds
+per day). More than 32 days uses the literal `D='*'`. Queries include their days
+and `*`, then verify exact interval overlap. Wide/unbounded queries skip the day
+prefilter. They never filter wrapper `created_at` with the recovery interval.
+Snapshots do not invent an interval between independent observations. The local
+IDB implementation retains its existing logical min/max compaction.
+
+## Deletion and synchronization
+
+`revoke(records)` writes owner-authored kind-5 personal copies in context `''`,
+with `a` targets for the **inner** 30078 coordinates and advisory `k=30078`.
+Batches contain at most 100 targets. Their timestamp covers stored versions and
+expiration is the latest target expiry. The normal NostrDB private-deletion path
+applies local removal and synced tombstones. There is no custom `state` tag.
+Local eviction/removal and expiry do not publish a deletion. Once a tombstone
+expires, its original targets are expired too. Do not reauthor synced snapshots.
+
+Sync transports must keep **their own recovery seeds local**. Persisting seeds
+of the transport that synchronizes seeds into that same event store creates a
+recursive stream of new synchronization data. Consumer chat sessions may use
+these adapters while the vault's synchronization messenger keeps its default.
+
+No legacy seed migration or automatic local-to-event-store copying is performed.
+A newly configured adapter records new captures/shares. Paired devices still
+need the same channel configuration, identity keys, mode and locally available
+chunks to serve a synced grant. Watchtowers need only their preserved envelopes.