libp2r2p 0.6.0 → 0.8.0

package/README.md

@@ -20,10 +20,14 @@ import { createPrivateMessenger } from 'libp2r2p/private-messenger'
 const messenger = await createPrivateMessenger({
   userSigner,
   contentKeySigner,
+  offlineRecoverySeconds: 7 * 24 * 60 * 60,
+  staleChannelSeconds: 45 * 24 * 60 * 60,
+  identityStorageRetentionSeconds: 60 * 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 +130,101 @@ 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 an internal storage set containing message,
+recovery-seed, and channel-state databases. The messenger updates its activity
+lease while it is open and closes all handles in `await messenger.close()`.
+The complete set is removed after `identityStorageRetentionSeconds` without
+use (60 days by default), 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 uses the separate
+`staleChannelSeconds` cleanup policy (45 days by default). Active instances
+record the channels they administer, so a channel remains protected while any
+instance or tab still uses it. 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.
+
+The effective recovery duration is capped by both `staleChannelSeconds` and
+`identityStorageRetentionSeconds`. The requested per-channel value remains
+stored separately, so raising a cap affects new retention decisions without
+recreating data already removed. Both retention policies can be changed by an
+instance at runtime; omitted fields retain their current persisted values:
+
+```js
+await messenger.update({
+  staleChannelSeconds: 30 * 24 * 60 * 60,
+  identityStorageRetentionSeconds: 90 * 24 * 60 * 60
+})
+```
+
+The policies are persisted per principal identity. If multiple instances use
+the same identity, the last confirmed policy update wins and is propagated to
+the others. A zero policy disables durable recovery immediately. Identity
+storage itself remains protected until the final active lease closes.
+
+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.8.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
     }
   }
 }