libp2r2p 0.6.0 → 0.7.0

package/README.md

@@ -20,10 +20,12 @@ import { createPrivateMessenger } from 'libp2r2p/private-messenger'
 const messenger = await createPrivateMessenger({
   userSigner,
   contentKeySigner,
+  offlineRecoverySeconds: 7 * 24 * 60 * 60,
   channels: [{
     signer: privateChannelSigner,
     relays: ['wss://relay.example'],
-    mode: 'leecher'
+    mode: 'leecher',
+    offlineRecoverySeconds: 30 * 24 * 60 * 60
   }],
   onError: err => console.warn('private messenger failed', err)
 })
@@ -126,45 +128,80 @@ one `['k', '3560']` tag, explicit matching `e` targets, and no `a` tags. A
 regular NIP-09 kind `5` request signed by the outer event's private-channel key
 must not delete a kind `3560` event, whether or not that event has an `s` tag.
 
-### Temporary Send Storage
+### Storage Maintenance
 
 While an outgoing private message is being assembled, the messenger keeps
 encrypted envelope rows and router chunks in `sessionStorage`. They are
 removed when the send finishes, but an interrupted browser operation can leave
 them behind until cleanup runs.
 
-`PrivateMessenger.init()` performs cleanup automatically. Call
-`PrivateMessenger.cleanupTemporaryStorage()` once during app startup when
-messenger initialization may be delayed, such as while an account is locked:
+`PrivateMessenger.init()` awaits storage maintenance automatically. Call
+`PrivateMessenger.maintainStorage()` during app startup when messenger
+initialization may be delayed, such as while an account is locked:
 
 ```js
 import { PrivateMessenger } from 'libp2r2p/private-messenger'
 
-PrivateMessenger.cleanupTemporaryStorage()
+PrivateMessenger.maintainStorage().catch(console.warn)
 ```
 
-Call it before any private-message send using that storage area starts. It
-does not clear persisted messages, recovery material, or channel state. Pass
-`temporaryStorageArea: localStorage` when constructing a messenger to opt into
-a different Storage area.
+Maintenance removes interrupted-send staging, expired receive chunks, and
+storage belonging to inactive principal identities. It also
+resumes any interrupted database-set deletion. An application does not need to
+know database names or enumerate IndexedDB. Pass `temporaryStorageArea` only
+when the messenger was configured to use a Storage area other than the default
+`sessionStorage`.
+
+Each principal signer owns internal message, recovery-seed, and channel-state
+databases. The messenger updates their activity lease while it is open and
+closes all handles in `await messenger.close()`. The complete set is removed
+after 60 days without use, including messages that were never consumed.
+Maintenance runs on every initialization and every six hours while a messenger
+is active; failed deletions remain journaled and retry automatically.
+
+Channel recovery state inside an otherwise active identity retains its separate
+45-day stale-channel cleanup policy. Offline recovery defaults to seven days.
+Set `offlineRecoverySeconds` on an individual channel to override the
+messenger default for its recovery seeds, offline ranges, new outer-event
+expiration, and new incomplete receive groups. Updating a channel applies a
+shorter window immediately to its stored seeds and ranges; increasing it does
+not recreate data already removed.
+
+Set a channel's `offlineRecoverySeconds` to `0` to disable durable recovery for
+that channel. The messenger then stores no recovery seeds, tracks no offline
+ranges, contacts no seeders, publishes no seeder presence, and uses no recovery
+mirror relays. Live delivery remains usable: new outer events retain the
+private-channel two-day technical expiration and incomplete receive groups use
+the one-hour technical TTL. Existing signed events and receive groups retain
+the deadlines chosen when they were created.
 
 Recovery metadata is separate from that temporary send staging. Per-channel
 `lastSeenAt`, offline ranges, and related state are stored in IndexedDB. Raw
-incomplete receive chunks are also stored in IndexedDB, expire after one hour,
-and share a 16 MiB logical budget. Capacity eviction removes whole
+incomplete receive chunks are also stored in IndexedDB and share a 16 MiB
+logical budget. Direct private-channel calls give each new group a one-hour
+TTL; PrivateMessenger groups use the effective recovery window of their
+channel, or one hour when durable recovery is disabled. The TTL is persisted
+per group, so another caller opening the shared database or a later channel
+configuration update cannot change it. Capacity
+eviction removes whole
 least-recently-used message groups so a partial group is never mistaken for a
 complete one. `receivedChunkTtlMs`, `receivedChunkMaxBytes`, and
 `receivedChunkIndexedDB` may be supplied to the private-channel APIs when an
 embedding environment needs different limits or an injected IDB factory.
 Legacy Web Storage recovery records are neither read nor migrated.
 
+The recovery-seed queue has a shared 64 MiB logical budget by default and uses
+FIFO eviction. A channel recovery duration is therefore a maximum retention
+window, not a guarantee that every seed remains available until its deadline.
+
 Signers are expected to expose the Nostr-style methods used by the messenger,
 including `getPublicKey()`, `signEvent(event)`, and the NIP-44 v3 methods
 needed by private channels. For double-DH content-key use, pass a
 `contentKeySigner` or a signer implementation that handles content keys
 internally.
 
-Messages are stored in a bounded, durable IndexedDB queue until consumed:
+Messages are stored in a bounded, durable IndexedDB queue until consumed or
+until the principal identity has been inactive for 60 days:
 
 ```js
 async function handleMessages () {

package/idb-queue/index.js

@@ -274,6 +274,10 @@ export async function createQueue ({
   const waiters = new Set()
   let sessionMaxBytes = configuredMaxBytes
   let revision = 0
+  let closed = false
+  let activeTransactions = 0
+  let closePromise = null
+  const closeWaiters = new Set()
 
   function hasByteLimit () {
     return Number.isFinite(sessionMaxBytes)
@@ -317,17 +321,27 @@ export async function createQueue ({
   }
 
   async function transaction (mode, work) {
-    const tx = db.transaction([ITEMS_STORE, STATE_STORE], mode)
-    const done = transactionDone(tx)
+    if (closed) throw new Error('QUEUE_CLOSED')
+    activeTransactions++
     try {
-      // Keep work limited to IndexedDB requests so the transaction stays active.
-      const value = await work(tx)
-      await done
-      return value
-    } catch (err) {
-      try { tx.abort() } catch {}
-      try { await done } catch {}
-      throw err
+      const tx = db.transaction([ITEMS_STORE, STATE_STORE], mode)
+      const done = transactionDone(tx)
+      try {
+        // Keep work limited to IndexedDB requests so the transaction stays active.
+        const value = await work(tx)
+        await done
+        return value
+      } catch (err) {
+        try { tx.abort() } catch {}
+        try { await done } catch {}
+        throw err
+      }
+    } finally {
+      activeTransactions--
+      if (!activeTransactions) {
+        for (const resolve of closeWaiters) resolve()
+        closeWaiters.clear()
+      }
     }
   }
 
@@ -771,6 +785,17 @@ export async function createQueue ({
     for (const record of (await snapshotStoredItems()).reverse()) yield record.item
   }
 
+  function close () {
+    if (closePromise) return closePromise
+    closed = true
+    wake()
+    closePromise = (activeTransactions
+      ? new Promise(resolve => closeWaiters.add(resolve))
+      : Promise.resolve())
+      .then(() => { db.close() })
+    return closePromise
+  }
+
   async function * storedItemsBy (indexName, query, { direction = 'next' } = {}) {
     direction = validDirection(direction)
     const records = await snapshot(async tx => {
@@ -811,6 +836,7 @@ export async function createQueue ({
     getBy,
     someBy,
     removeBy,
-    storedItemsBy
+    storedItemsBy,
+    close
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libp2r2p",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Peer-to-relay-to-peer",
   "keywords": [
     "p2r2p",

package/private-channel/index.js

@@ -566,8 +566,8 @@ async function decryptRouter ({ content, channelPubkey, channelSigner, channelRe
 
 function readValueFromMap (map, key) {
   if (!map || !key) return null
-  if (map instanceof Map) return map.get(key) || null
-  return map[key] || null
+  if (map instanceof Map) return map.get(key) ?? null
+  return map[key] ?? null
 }
 
 function privateChannelPubkeyList ({ privateChannelPubkey, privateChannelPubkeys }) {
@@ -669,6 +669,7 @@ function createProcessor ({
   onContentKeyUsage,
   onError,
   receivedChunkTtlMs = DEFAULT_RECEIVED_CHUNK_TTL_MS,
+  receivedChunkTtlMsByPubkey,
   receivedChunkMaxBytes = DEFAULT_RECEIVED_CHUNK_MAX_BYTES,
   receivedChunkIndexedDB = globalThis.indexedDB,
   ignoredGroupTtlMs = DEFAULT_IGNORED_GROUP_TTL_MS,
@@ -683,8 +684,11 @@ function createProcessor ({
     ttlMs: ignoredGroupTtlMs,
     maxEntries: ignoredGroupMaxEntries
   })
+  const storeReady = receivedChunks.ready()
+  storeReady.catch(() => {})
 
-  return async function processOuterEvent (outer) {
+  async function processOuterEvent (outer) {
+    await storeReady
     let groupKey = ''
     try {
       const channelPubkey = outer.pubkey || await privateChannelSigner?.getPublicKey?.()
@@ -692,6 +696,7 @@ function createProcessor ({
       const channelReaderSigner = readSignerFromMap(privateChannelReaderSignersByPubkey, channelPubkey) || privateChannelReaderSigner || channelSigner
       const channelReaderPubkey = readValueFromMap(privateChannelReaderPubkeysByPubkey, channelPubkey) || privateChannelReaderPubkey || channelPubkey
       const channelMode = readValueFromMap(modeByPubkey, channelPubkey) || mode
+      const channelReceivedChunkTtlMs = readValueFromMap(receivedChunkTtlMsByPubkey, channelPubkey) ?? receivedChunkTtlMs
       if (!channelPubkey) throw new Error('PRIVATE_CHANNEL_PUBKEY_REQUIRED')
 
       const decrypted = await decryptRouter({
@@ -712,7 +717,8 @@ function createProcessor ({
           routerPubkey: nymCarrierGroupId(carrier),
           index,
           total,
-          contentBytes: encoder.encode(JSON.stringify(carrier))
+          contentBytes: encoder.encode(JSON.stringify(carrier)),
+          ttlMs: channelReceivedChunkTtlMs
         })
         const status = await receivedChunks.status(meta)
         onChunk?.({
@@ -762,7 +768,8 @@ function createProcessor ({
         routerPubkey: router.pubkey,
         index,
         total,
-        contentBytes: base64ToBytes(router.content)
+        contentBytes: base64ToBytes(router.content),
+        ttlMs: channelReceivedChunkTtlMs
       })
       const status = await receivedChunks.status(meta)
       onChunk?.({
@@ -857,6 +864,9 @@ function createProcessor ({
       onError?.(err)
     }
   }
+
+  processOuterEvent.close = () => receivedChunks.close()
+  return processOuterEvent
 }
 
 function shouldIgnoreGroupError (err) {
@@ -882,7 +892,7 @@ function shouldIgnoreGroupError (err) {
   ].includes(err?.message)
 }
 
-export async function fetch ({ receiverSigner, iykcSigner, privateChannelSigner = receiverSigner, privateChannelSignersByPubkey, privateChannelReaderSigner = privateChannelSigner, privateChannelReaderSignersByPubkey, privateChannelReaderPubkey, privateChannelReaderPubkeysByPubkey, privateChannelPubkey, privateChannelPubkeys, receiverPubkey, relays, onChunk, onEvent, onNymEvent, onSeedEvent, onContentKeyUsage, onError, since, until, limit, mode = 'leecher', modeByPubkey, receivedChunkTtlMs = DEFAULT_RECEIVED_CHUNK_TTL_MS, receivedChunkMaxBytes = DEFAULT_RECEIVED_CHUNK_MAX_BYTES, receivedChunkIndexedDB = globalThis.indexedDB, ignoredGroupTtlMs = DEFAULT_IGNORED_GROUP_TTL_MS, ignoredGroupMaxEntries = DEFAULT_IGNORED_GROUP_MAX_ENTRIES, _getEvents = getEvents }) {
+export async function fetch ({ receiverSigner, iykcSigner, privateChannelSigner = receiverSigner, privateChannelSignersByPubkey, privateChannelReaderSigner = privateChannelSigner, privateChannelReaderSignersByPubkey, privateChannelReaderPubkey, privateChannelReaderPubkeysByPubkey, privateChannelPubkey, privateChannelPubkeys, receiverPubkey, relays, onChunk, onEvent, onNymEvent, onSeedEvent, onContentKeyUsage, onError, since, until, limit, mode = 'leecher', modeByPubkey, receivedChunkTtlMs = DEFAULT_RECEIVED_CHUNK_TTL_MS, receivedChunkTtlMsByPubkey, receivedChunkMaxBytes = DEFAULT_RECEIVED_CHUNK_MAX_BYTES, receivedChunkIndexedDB = globalThis.indexedDB, ignoredGroupTtlMs = DEFAULT_IGNORED_GROUP_TTL_MS, ignoredGroupMaxEntries = DEFAULT_IGNORED_GROUP_MAX_ENTRIES, _getEvents = getEvents }) {
   if (!relays?.length) throw new Error('NO_RELAYS')
   const authors = privateChannelPubkeyList({ privateChannelPubkey, privateChannelPubkeys })
   const filter = { kinds: [PRIVATE_BROADCAST_KIND] }
@@ -896,12 +906,16 @@ export async function fetch ({ receiverSigner, iykcSigner, privateChannelSigner
     timeoutAfterFirstEose: null
   })
   events.sort((a, b) => a.created_at - b.created_at)
-  const processOuterEvent = createProcessor({ receiverSigner, iykcSigner, privateChannelSigner, privateChannelSignersByPubkey, privateChannelReaderSigner, privateChannelReaderSignersByPubkey, privateChannelReaderPubkey, privateChannelReaderPubkeysByPubkey, receiverPubkey, mode, modeByPubkey, onChunk, onEvent, onNymEvent, onSeedEvent, onContentKeyUsage, onError, receivedChunkTtlMs, receivedChunkMaxBytes, receivedChunkIndexedDB, ignoredGroupTtlMs, ignoredGroupMaxEntries })
-  for (const event of events) await processOuterEvent(event)
-  return events
+  const processOuterEvent = createProcessor({ receiverSigner, iykcSigner, privateChannelSigner, privateChannelSignersByPubkey, privateChannelReaderSigner, privateChannelReaderSignersByPubkey, privateChannelReaderPubkey, privateChannelReaderPubkeysByPubkey, receiverPubkey, mode, modeByPubkey, onChunk, onEvent, onNymEvent, onSeedEvent, onContentKeyUsage, onError, receivedChunkTtlMs, receivedChunkTtlMsByPubkey, receivedChunkMaxBytes, receivedChunkIndexedDB, ignoredGroupTtlMs, ignoredGroupMaxEntries })
+  try {
+    for (const event of events) await processOuterEvent(event)
+    return events
+  } finally {
+    processOuterEvent.close()
+  }
 }
 
-export function subscribe ({ receiverSigner, iykcSigner, privateChannelSigner = receiverSigner, privateChannelSignersByPubkey, privateChannelReaderSigner = privateChannelSigner, privateChannelReaderSignersByPubkey, privateChannelReaderPubkey, privateChannelReaderPubkeysByPubkey, privateChannelPubkey, privateChannelPubkeys, receiverPubkey, relays, onChunk, onEvent, onNymEvent, onSeedEvent, onContentKeyUsage, onError, since = nowSeconds() - 5, limit, liveOnly = false, mode = 'leecher', modeByPubkey, receivedChunkTtlMs = DEFAULT_RECEIVED_CHUNK_TTL_MS, receivedChunkMaxBytes = DEFAULT_RECEIVED_CHUNK_MAX_BYTES, receivedChunkIndexedDB = globalThis.indexedDB, ignoredGroupTtlMs = DEFAULT_IGNORED_GROUP_TTL_MS, ignoredGroupMaxEntries = DEFAULT_IGNORED_GROUP_MAX_ENTRIES, _liveEventsGenerator = getLiveEventsGenerator, _eventsFeedGenerator = getEventsFeedGenerator }) {
+export function subscribe ({ receiverSigner, iykcSigner, privateChannelSigner = receiverSigner, privateChannelSignersByPubkey, privateChannelReaderSigner = privateChannelSigner, privateChannelReaderSignersByPubkey, privateChannelReaderPubkey, privateChannelReaderPubkeysByPubkey, privateChannelPubkey, privateChannelPubkeys, receiverPubkey, relays, onChunk, onEvent, onNymEvent, onSeedEvent, onContentKeyUsage, onError, since = nowSeconds() - 5, limit, liveOnly = false, mode = 'leecher', modeByPubkey, receivedChunkTtlMs = DEFAULT_RECEIVED_CHUNK_TTL_MS, receivedChunkTtlMsByPubkey, receivedChunkMaxBytes = DEFAULT_RECEIVED_CHUNK_MAX_BYTES, receivedChunkIndexedDB = globalThis.indexedDB, ignoredGroupTtlMs = DEFAULT_IGNORED_GROUP_TTL_MS, ignoredGroupMaxEntries = DEFAULT_IGNORED_GROUP_MAX_ENTRIES, _liveEventsGenerator = getLiveEventsGenerator, _eventsFeedGenerator = getEventsFeedGenerator }) {
   if (!relays?.length) throw new Error('NO_RELAYS')
   if (receiverSigner && !receiverSigner?.nip44DecryptDoubleDH && !receiverSigner?.nip44v3Decrypt) throw new Error('RECEIVER_SIGNER_NIP44V3_DECRYPT_UNSUPPORTED')
   if (!privateChannelReaderSigner && !privateChannelReaderSignersByPubkey && !privateChannelSigner && !privateChannelSignersByPubkey) throw new Error('PRIVATE_CHANNEL_READER_REQUIRED')
@@ -910,17 +924,17 @@ export function subscribe ({ receiverSigner, iykcSigner, privateChannelSigner =
   const filter = { kinds: [PRIVATE_BROADCAST_KIND], since }
   if (authors.length) filter.authors = authors
   if (limit != null) filter.limit = limit
-  const processOuterEvent = createProcessor({ receiverSigner, iykcSigner, privateChannelSigner, privateChannelSignersByPubkey, privateChannelReaderSigner, privateChannelReaderSignersByPubkey, privateChannelReaderPubkey, privateChannelReaderPubkeysByPubkey, receiverPubkey, mode, modeByPubkey, onChunk, onEvent, onNymEvent, onSeedEvent, onContentKeyUsage, onError, receivedChunkTtlMs, receivedChunkMaxBytes, receivedChunkIndexedDB, ignoredGroupTtlMs, ignoredGroupMaxEntries })
+  const processOuterEvent = createProcessor({ receiverSigner, iykcSigner, privateChannelSigner, privateChannelSignersByPubkey, privateChannelReaderSigner, privateChannelReaderSignersByPubkey, privateChannelReaderPubkey, privateChannelReaderPubkeysByPubkey, receiverPubkey, mode, modeByPubkey, onChunk, onEvent, onNymEvent, onSeedEvent, onContentKeyUsage, onError, receivedChunkTtlMs, receivedChunkTtlMsByPubkey, receivedChunkMaxBytes, receivedChunkIndexedDB, ignoredGroupTtlMs, ignoredGroupMaxEntries })
   const controller = new AbortController()
   const events = liveOnly
     ? _liveEventsGenerator(filter, relays, {
-        signal: controller.signal
-      })
+      signal: controller.signal
+    })
     : _eventsFeedGenerator(filter, relays, {
-        signal: controller.signal,
-        timeout: 5000,
-        timeoutAfterFirstEose: null
-      })
+      signal: controller.signal,
+      timeout: 5000,
+      timeoutAfterFirstEose: null
+    })
 
   async function consumeEvents () {
     try {
@@ -930,14 +944,17 @@ export function subscribe ({ receiverSigner, iykcSigner, privateChannelSigner =
       }
     } catch (error) {
       if (!controller.signal.aborted && error?.message !== 'Aborted') onError?.(error)
+    } finally {
+      processOuterEvent.close()
     }
   }
 
-  consumeEvents()
+  const consumePromise = consumeEvents()
 
   return {
     close () {
       controller.abort()
+      return consumePromise
     }
   }
 }

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

@@ -5,7 +5,7 @@ export const DEFAULT_RECEIVED_CHUNK_TTL_MS = 60 * 60 * 1000 // 1 hour
 export const DEFAULT_RECEIVED_CHUNK_MAX_BYTES = 16 * 1024 * 1024 // 16 MiB
 
 const DEFAULT_PREFIX = 'libp2r2p:private-channel:received'
-const DATABASE_VERSION = 1
+const DATABASE_VERSION = 2
 const GROUPS_STORE = 'groups'
 const CHUNKS_STORE = 'chunks'
 const STATE_STORE = 'state'
@@ -16,7 +16,7 @@ const decoder = new TextDecoder()
 /*
 IndexedDB schema, scoped per received-chunk prefix:
 
-database `${prefix}:idb`, version 1
+database `${prefix}:idb`, version 2
 
 groups, keyPath "groupKey"
   groupKey                  `${channelPubkey}:${routerPubkey}`
@@ -28,10 +28,12 @@ groups, keyPath "groupKey"
   receiverPubkeys           deduplicated intended receivers
   byteSize                  logical bytes charged to this group
   createdAt/updatedAt        lifecycle timestamps in milliseconds
+  ttlMs/expiresAt            group-specific retention and absolute expiry
   drainToken/drainUntil      optional drain lease owner and expiry
 
 groups indexes
   byUpdatedAt  updatedAt
+  byExpiresAt  expiresAt
 
 chunks, keyPath ["groupKey", "index"]
   groupKey  owning group coordinate
@@ -80,6 +82,7 @@ function openDatabase (indexedDB, name) {
         groups = tx.objectStore(GROUPS_STORE)
       }
       if (!groups.indexNames.contains('byUpdatedAt')) groups.createIndex('byUpdatedAt', 'updatedAt')
+      if (!groups.indexNames.contains('byExpiresAt')) groups.createIndex('byExpiresAt', 'expiresAt')
 
       let chunks
       if (!db.objectStoreNames.contains(CHUNKS_STORE)) {
@@ -119,12 +122,14 @@ function normalizeReceived (received) {
   )
 }
 
-function normalizeMeta (meta) {
+function normalizeMeta (meta, fallbackTtlMs = DEFAULT_RECEIVED_CHUNK_TTL_MS) {
   if (!meta || typeof meta !== 'object') return null
   const total = Number(meta.total)
   const nextIndex = Number(meta.nextIndex)
   const rowIndex = Number(meta.rowIndex)
   if (!meta.groupKey || !Number.isSafeInteger(total) || total < 1) return null
+  const updatedAt = Number(meta.updatedAt) || Date.now()
+  const ttlMs = Number.isFinite(meta.ttlMs) && meta.ttlMs >= 0 ? meta.ttlMs : fallbackTtlMs
   return {
     groupKey: String(meta.groupKey),
     channelPubkey: String(meta.channelPubkey || ''),
@@ -139,7 +144,9 @@ function normalizeMeta (meta) {
     receiverPubkeys: uniq(meta.receiverPubkeys),
     byteSize: Math.max(0, Number(meta.byteSize) || 0),
     createdAt: Number(meta.createdAt) || Date.now(),
-    updatedAt: Number(meta.updatedAt) || Date.now(),
+    updatedAt,
+    ttlMs,
+    expiresAt: Number(meta.expiresAt) || updatedAt + ttlMs,
     drainToken: typeof meta.drainToken === 'string' ? meta.drainToken : '',
     drainUntil: Math.max(0, Number(meta.drainUntil) || 0)
   }
@@ -180,10 +187,18 @@ export function createReceivedChunkStore ({
   const configuredMaxBytes = Number.isFinite(maxBytes) && maxBytes > 0 ? maxBytes : Infinity
   let dbPromise
   let readyPromise
+  let closed = false
 
   function database () {
+    if (closed) return Promise.reject(new Error('RECEIVED_CHUNK_STORE_CLOSED'))
     dbPromise ||= openDatabase(indexedDB, `${prefix}:idb`)
-    return dbPromise
+    return dbPromise.then(db => {
+      if (closed) {
+        db.close()
+        throw new Error('RECEIVED_CHUNK_STORE_CLOSED')
+      }
+      return db
+    })
   }
 
   async function transaction (storeNames, mode, work) {
@@ -215,7 +230,7 @@ export function createReceivedChunkStore ({
   }
 
   async function deleteGroupInTransaction (tx, groupKey, usage, knownMeta) {
-    const meta = knownMeta || normalizeMeta((await run('get', [groupKey], GROUPS_STORE, null, { tx })).result)
+    const meta = knownMeta || normalizeMeta((await run('get', [groupKey], GROUPS_STORE, null, { tx })).result, configuredTtlMs)
     const keys = (await run('getAllKeys', [globalThis.IDBKeyRange?.only?.(groupKey) ?? groupKey], CHUNKS_STORE, 'byGroup', { tx })).result
     for (const key of keys) await run('delete', [key], CHUNKS_STORE, null, { tx })
     await run('delete', [groupKey], GROUPS_STORE, null, { tx })
@@ -226,19 +241,18 @@ export function createReceivedChunkStore ({
   async function oldestGroupsInTransaction (tx, except = '') {
     const values = (await run('getAll', [], GROUPS_STORE, null, { tx })).result
     return values
-      .map(normalizeMeta)
+      .map(value => normalizeMeta(value, configuredTtlMs))
       .filter(meta => meta && meta.groupKey !== except)
       .sort((left, right) => left.updatedAt - right.updatedAt || left.groupKey.localeCompare(right.groupKey))
   }
 
   async function cleanupStaleRaw (nowMs = Date.now()) {
-    const cutoff = nowMs - configuredTtlMs
     return transaction([GROUPS_STORE, CHUNKS_STORE, STATE_STORE], 'readwrite', async tx => {
       const usage = await readUsage(tx)
       const groups = await oldestGroupsInTransaction(tx)
       let removed = 0
       for (const meta of groups) {
-        if (meta.updatedAt > cutoff && (!Number.isFinite(configuredMaxBytes) || usage.usedBytes <= configuredMaxBytes)) continue
+        if (meta.expiresAt > nowMs && (!Number.isFinite(configuredMaxBytes) || usage.usedBytes <= configuredMaxBytes)) continue
         await deleteGroupInTransaction(tx, meta.groupKey, usage, meta)
         removed++
       }
@@ -247,26 +261,26 @@ export function createReceivedChunkStore ({
     })
   }
 
-  function ready () {
-    readyPromise ||= cleanupStaleRaw()
+  function ready (nowMs = Date.now()) {
+    readyPromise ||= cleanupStaleRaw(nowMs)
     return readyPromise
   }
 
   async function cleanupStale (nowMs = Date.now()) {
-    await ready()
+    await ready(nowMs)
     return cleanupStaleRaw(nowMs)
   }
 
-  async function putOnce ({ channelPubkey, routerPubkey, index, total, contentBytes }) {
+  async function putOnce ({ channelPubkey, routerPubkey, index, total, contentBytes, ttlMs }) {
     const groupKey = groupKeyFor(channelPubkey, routerPubkey)
     const bytes = normalizeBytes(contentBytes)
     const now = Date.now()
+    const groupTtlMs = Number.isFinite(ttlMs) && ttlMs >= 0 ? ttlMs : configuredTtlMs
 
     return transaction([GROUPS_STORE, CHUNKS_STORE, STATE_STORE], 'readwrite', async tx => {
       const usage = await readUsage(tx)
-      let meta = normalizeMeta((await run('get', [groupKey], GROUPS_STORE, null, { tx })).result)
-      const staleCutoff = now - configuredTtlMs
-      if (meta && meta.updatedAt <= staleCutoff) {
+      let meta = normalizeMeta((await run('get', [groupKey], GROUPS_STORE, null, { tx })).result, configuredTtlMs)
+      if (meta && meta.expiresAt <= now) {
         await deleteGroupInTransaction(tx, groupKey, usage, meta)
         meta = null
       }
@@ -289,8 +303,10 @@ export function createReceivedChunkStore ({
           receiverPubkeys: [],
           byteSize: 0,
           createdAt: now,
-          updatedAt: now
-        })
+          updatedAt: now,
+          ttlMs: groupTtlMs,
+          expiresAt: now + groupTtlMs
+        }, configuredTtlMs)
       }
 
       const existing = (await run('get', [[groupKey, index]], CHUNKS_STORE, null, { tx })).result
@@ -304,11 +320,11 @@ export function createReceivedChunkStore ({
         const requiredBytes = bytes.byteLength
         const candidates = await oldestGroupsInTransaction(tx, groupKey)
         for (const candidate of candidates) {
-          if (candidate.updatedAt > staleCutoff) continue
+          if (candidate.expiresAt > now) continue
           await deleteGroupInTransaction(tx, candidate.groupKey, usage, candidate)
         }
         for (const candidate of candidates) {
-          if (candidate.updatedAt <= staleCutoff) continue
+          if (candidate.expiresAt <= now) continue
           if (!Number.isFinite(configuredMaxBytes) || usage.usedBytes + requiredBytes <= configuredMaxBytes) break
           await deleteGroupInTransaction(tx, candidate.groupKey, usage, candidate)
         }
@@ -327,6 +343,7 @@ export function createReceivedChunkStore ({
 
       meta.total = total
       meta.updatedAt = now
+      meta.expiresAt = now + meta.ttlMs
       await run('put', [meta], GROUPS_STORE, null, { tx })
       await writeUsage(tx, usage)
       return { tooLarge: false, meta }
@@ -344,7 +361,7 @@ export function createReceivedChunkStore ({
     })
   }
 
-  async function put ({ channelPubkey, routerPubkey, index, total, contentBytes }) {
+  async function put ({ channelPubkey, routerPubkey, index, total, contentBytes, ttlMs }) {
     if (!channelPubkey || !routerPubkey) throw new Error('RECEIVED_CHUNK_GROUP_REQUIRED')
     if (!Number.isSafeInteger(index) || !Number.isSafeInteger(total) || index < 0 || total < 1 || index >= total) {
       throw new Error('INVALID_RECEIVED_CHUNK_INDEX')
@@ -353,7 +370,7 @@ export function createReceivedChunkStore ({
     await ready()
     while (true) {
       try {
-        const result = await putOnce({ channelPubkey, routerPubkey, index, total, contentBytes: bytes })
+        const result = await putOnce({ channelPubkey, routerPubkey, index, total, contentBytes: bytes, ttlMs })
         if (result.tooLarge) throw new Error('RECEIVED_CHUNK_GROUP_TOO_LARGE')
         return result.meta
       } catch (err) {
@@ -365,12 +382,12 @@ export function createReceivedChunkStore ({
   async function readMeta (groupKey) {
     await ready()
     return transaction([GROUPS_STORE], 'readonly', async tx => {
-      return normalizeMeta((await run('get', [groupKey], GROUPS_STORE, null, { tx })).result)
+      return normalizeMeta((await run('get', [groupKey], GROUPS_STORE, null, { tx })).result, configuredTtlMs)
     })
   }
 
   async function status (metaOrGroupKey) {
-    const meta = typeof metaOrGroupKey === 'string' ? await readMeta(metaOrGroupKey) : normalizeMeta(metaOrGroupKey)
+    const meta = typeof metaOrGroupKey === 'string' ? await readMeta(metaOrGroupKey) : normalizeMeta(metaOrGroupKey, configuredTtlMs)
     if (!meta) return { received: 0, missing: [] }
     const missing = []
     let received = 0
@@ -393,13 +410,15 @@ export function createReceivedChunkStore ({
     while (true) {
       const now = Date.now()
       const result = await transaction([GROUPS_STORE], 'readwrite', async tx => {
-        const meta = normalizeMeta((await run('get', [groupKey], GROUPS_STORE, null, { tx })).result)
+        const meta = normalizeMeta((await run('get', [groupKey], GROUPS_STORE, null, { tx })).result, configuredTtlMs)
         if (!meta) return { meta: null, waitMs: 0 }
         if (meta.drainToken && meta.drainToken !== token && meta.drainUntil > now) {
           return { meta: null, waitMs: Math.min(DRAIN_LEASE_MS, meta.drainUntil - now) }
         }
         meta.drainToken = token
         meta.drainUntil = now + DRAIN_LEASE_MS
+        meta.updatedAt = now
+        meta.expiresAt = now + meta.ttlMs
         await run('put', [meta], GROUPS_STORE, null, { tx })
         return { meta, waitMs: 0 }
       })
@@ -410,7 +429,7 @@ export function createReceivedChunkStore ({
 
   async function readDrainChunk (groupKey, token) {
     return transaction([GROUPS_STORE, CHUNKS_STORE], 'readonly', async tx => {
-      const meta = normalizeMeta((await run('get', [groupKey], GROUPS_STORE, null, { tx })).result)
+      const meta = normalizeMeta((await run('get', [groupKey], GROUPS_STORE, null, { tx })).result, configuredTtlMs)
       if (!meta || meta.drainToken !== token) return { meta: null, bytes: null }
       if (meta.nextIndex >= meta.total) return { meta, bytes: null }
       const chunk = (await run('get', [[groupKey, meta.nextIndex]], CHUNKS_STORE, null, { tx })).result
@@ -420,7 +439,7 @@ export function createReceivedChunkStore ({
 
   async function commitDrainMeta (nextMeta, token) {
     return transaction([GROUPS_STORE], 'readwrite', async tx => {
-      const current = normalizeMeta((await run('get', [nextMeta.groupKey], GROUPS_STORE, null, { tx })).result)
+      const current = normalizeMeta((await run('get', [nextMeta.groupKey], GROUPS_STORE, null, { tx })).result, configuredTtlMs)
       if (!current || current.drainToken !== token) return null
       current.nextIndex = nextMeta.nextIndex
       current.rowIndex = nextMeta.rowIndex
@@ -428,6 +447,7 @@ export function createReceivedChunkStore ({
       current.payloadCiphertext = nextMeta.payloadCiphertext
       current.receiverPubkeys = uniq(nextMeta.receiverPubkeys)
       current.updatedAt = nextMeta.updatedAt
+      current.expiresAt = current.updatedAt + current.ttlMs
       current.drainUntil = Date.now() + DRAIN_LEASE_MS
       await run('put', [current], GROUPS_STORE, null, { tx })
       return current
@@ -436,7 +456,7 @@ export function createReceivedChunkStore ({
 
   async function releaseDrain (groupKey, token) {
     return transaction([GROUPS_STORE], 'readwrite', async tx => {
-      const meta = normalizeMeta((await run('get', [groupKey], GROUPS_STORE, null, { tx })).result)
+      const meta = normalizeMeta((await run('get', [groupKey], GROUPS_STORE, null, { tx })).result, configuredTtlMs)
       if (!meta || meta.drainToken !== token) return false
       meta.drainToken = ''
       meta.drainUntil = 0
@@ -504,7 +524,7 @@ export function createReceivedChunkStore ({
   async function readChunkBytes (groupKey) {
     await ready()
     return transaction([GROUPS_STORE, CHUNKS_STORE], 'readonly', async tx => {
-      const meta = normalizeMeta((await run('get', [groupKey], GROUPS_STORE, null, { tx })).result)
+      const meta = normalizeMeta((await run('get', [groupKey], GROUPS_STORE, null, { tx })).result, configuredTtlMs)
       if (!meta) return { meta: null, chunks: [] }
       const chunks = []
       for (let index = 0; index < meta.total; index++) {
@@ -551,6 +571,12 @@ export function createReceivedChunkStore ({
     })
   }
 
+  function close () {
+    if (closed) return
+    closed = true
+    dbPromise?.then(db => db.close()).catch(() => {})
+  }
+
   return {
     cleanupStale,
     drainAvailable,
@@ -559,7 +585,22 @@ export function createReceivedChunkStore ({
     readChunkContents,
     readEnvelopeBundleContent,
     readEnvelopeBundleText,
+    ready,
     removeGroup,
-    status
+    status,
+    close
+  }
+}
+
+export async function cleanupReceivedChunkStorage ({
+  indexedDB = globalThis.indexedDB,
+  prefix = DEFAULT_PREFIX,
+  now = Date.now()
+} = {}) {
+  const store = createReceivedChunkStore({ prefix, indexedDB })
+  try {
+    return await store.cleanupStale(now)
+  } finally {
+    store.close()
   }
 }