libp2r2p 0.11.0 → 0.11.1

package/README.md

@@ -907,3 +907,9 @@ capture outgoing ordinary-message ciphertext before publishing, even without rel
 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libp2r2p",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "description": "Peer-to-relay-to-peer",
   "keywords": [
     "p2r2p",
@@ -86,8 +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-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.

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

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

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

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

package/private-messenger/file/README.md

@@ -3,8 +3,9 @@
 `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.
+channel signers. An optional adapter supplies `storage.read(root, index, descriptor)`
+and `storage.save(event, descriptor)`; otherwise the library uses its bounded local
+cache. `save` must resolve only after persistence.
 The descriptor is `{ controlChannelPubkey, peerPubkey, root, size?, sharedAt? }`.
 `sharedAt` is a stable sharing timestamp, never a read/retry timestamp.
 
@@ -125,3 +126,27 @@ the same pair/root.
 Multi-device seed synchronization and group-channel derivation remain separate
 follow-ups. Applications own durable manual-download intent, metadata retention
 and UI policy. Removing one message must not delete a root retained by another.
+
+## Optional persistence (0.11.1)
+
+`storage`, `authorizationStorage`, and `seedStorage` are optional. The latter two
+use the semantic contracts in `private-messenger/event-store`; omitted stores
+retain their existing indexed local implementation. External stores are owned by
+the caller. Synced grants are checked against the current channel mode/retention
+before serving, and are never deleted globally because a channel is not loaded.
+
+With no chunk adapter, `createFileCache` owns
+`<messenger prefix>:file-chunks:idb` (files and chunks stores). Its default
+`cacheMaxBytes` is 256 MiB of useful decoded bytes; physical IndexedDB overhead is
+additional. Deduplication uses root/index. FIFO root eviction discards inactive
+files to admit new data. Durable renewable reservations protect active transfers
+and readers across tabs; stale reservations expire after two minutes. A blocked
+transfer waits with cancellation. Unknown sizes reserve the budget exclusively;
+an individual oversized file raises `FILE_EXCEEDS_CACHE_CAPACITY`. Physical quota
+failures try discarding additional inactive roots before propagating.
+
+Outgoing chunks are saved before publication; this does not authorize recipients.
+`readChunk(root, index)` reads local data. `stream(descriptor, { signal })` uses
+bounded sequential reads and backpressure, not a whole-file Blob. Cancel streams
+when unused. Cache eviction can remove a previously completed file, so new
+requests recheck persisted indices. The cache is included in identity cleanup.

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

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