libp2r2p 0.0.1

package/nip46/services/transport.js

@@ -0,0 +1,265 @@
+import { getPublicKey } from 'nostr-tools'
+import { relayPool as defaultRelayPool } from '../../relay/index.js'
+import { DEFAULT_TIMEOUT, DEFAULT_TIMEOUT_AFTER_FIRST_EOSE } from '../constants/index.js'
+import { createNip46Event, requestError } from '../helpers/frame.js'
+
+const RETIRE_CONTEXT_AFTER_MS = 5000
+const SEEN_EVENT_LIMIT = 500
+
+function requestId () {
+  const bytes = new Uint8Array(8)
+  globalThis.crypto.getRandomValues(bytes)
+  return [...bytes].map(byte => byte.toString(16).padStart(2, '0')).join('')
+}
+
+function requestExtension (value) {
+  if (value === undefined || value === null) return null
+  if (typeof value !== 'object' || Array.isArray(value)) throw new Error('NIP46_REQUEST_EXTENSION_REQUIRED')
+  for (const key of ['id', 'method', 'params']) {
+    if (Object.hasOwn(value, key)) throw new Error(`NIP46_REQUEST_EXTENSION_CANNOT_SET_${key.toUpperCase()}`)
+  }
+  return value
+}
+
+export function waitForNip46 (promise, { timeout = null, signal, label = 'NIP46_TIMEOUT' } = {}) {
+  if (signal?.aborted) return Promise.reject(new Error('Aborted'))
+  if (timeout === null && !signal) return Promise.resolve(promise)
+
+  return new Promise((resolve, reject) => {
+    let timer = null
+    let settled = false
+    const finish = (fn, value) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      signal?.removeEventListener('abort', onAbort)
+      fn(value)
+    }
+    const onAbort = () => finish(reject, new Error('Aborted'))
+
+    if (timeout !== null) timer = setTimeout(() => finish(reject, new Error(label)), timeout)
+    signal?.addEventListener('abort', onAbort, { once: true })
+    Promise.resolve(promise).then(
+      value => finish(resolve, value),
+      error => finish(reject, error)
+    )
+  })
+}
+
+export function sameRelays (left, right) {
+  if (left.length !== right.length) return false
+  const values = new Set(left)
+  return right.every(value => values.has(value))
+}
+
+// Owns the shared encrypted RPC mechanics while client/server classes enforce
+// their different connection and authorization rules.
+export class Nip46Transport {
+  #secretKey
+  #pubkey
+  #relayPool
+  #networkTimeout
+  #timeoutAfterFirstEose
+  #onError
+  #contexts = new Set()
+  #activeContext = null
+  #retireTimers = new Set()
+  #pending = new Map()
+  #seenEventIds = new Set()
+  #closed = false
+
+  constructor (secretKey, {
+    relayPool = defaultRelayPool,
+    networkTimeout = DEFAULT_TIMEOUT,
+    timeoutAfterFirstEose = DEFAULT_TIMEOUT_AFTER_FIRST_EOSE,
+    onError
+  } = {}) {
+    if (!(secretKey instanceof Uint8Array)) throw new Error('NIP46_SECRET_KEY_REQUIRED')
+    if (!relayPool?.getLiveEventsGenerator || !relayPool?.sendEvent) throw new Error('RELAY_POOL_REQUIRED')
+    this.#secretKey = secretKey
+    this.#pubkey = getPublicKey(secretKey)
+    this.#relayPool = relayPool
+    this.#networkTimeout = networkTimeout
+    this.#timeoutAfterFirstEose = timeoutAfterFirstEose
+    this.#onError = onError
+  }
+
+  get pubkey () { return this.#pubkey }
+  get closed () { return this.#closed }
+  get activeContext () { return this.#activeContext }
+  get readyRelays () { return this.#activeContext?.stream.readyRelays || Object.freeze([]) }
+
+  openContext ({ filter, relays, onEvent }) {
+    if (this.#closed) throw new Error('NIP46_CLOSED')
+    const controller = new AbortController()
+    const stream = this.#relayPool.getLiveEventsGenerator(filter, relays, {
+      signal: controller.signal,
+      timeoutAfterFirstEose: this.#timeoutAfterFirstEose
+    })
+    const context = { controller, stream, relays: [...relays], consume: null }
+    this.#contexts.add(context)
+    context.consume = (async () => {
+      try {
+        for await (const event of stream) {
+          Promise.resolve(onEvent(event)).catch(error => this.#reportError(error))
+        }
+      } catch (error) {
+        if (!this.#closed && error?.message !== 'Aborted') this.#reportError(error)
+      }
+    })()
+    return context
+  }
+
+  async awaitContextReady (context, { timeout = this.#networkTimeout, signal } = {}) {
+    const report = await waitForNip46(context.stream.ready, {
+      timeout,
+      signal,
+      label: 'NIP46_LISTENER_TIMEOUT'
+    })
+    if (!context.stream.readyRelays.length) {
+      throw requestError(report.errors?.[0]?.reason || 'NIP46_NO_READY_RELAYS')
+    }
+    return context.stream.readyRelays
+  }
+
+  activateContext (context, { retirePrevious = true } = {}) {
+    const previous = this.#activeContext
+    this.#activeContext = context
+    if (retirePrevious && previous && previous !== context) this.retireContext(previous)
+    return previous
+  }
+
+  retireContext (context, delay = RETIRE_CONTEXT_AFTER_MS) {
+    if (!context || !this.#contexts.has(context)) return
+    const timer = setTimeout(() => {
+      this.#retireTimers.delete(timer)
+      this.closeContext(context)
+    }, delay)
+    this.#retireTimers.add(timer)
+  }
+
+  async closeContext (context) {
+    if (!context || !this.#contexts.delete(context)) return
+    context.controller.abort()
+    try {
+      await context.consume
+    } catch {
+      // Unexpected stream failures are reported by the consume loop.
+    }
+  }
+
+  isNewEvent (event) {
+    if (!event?.id) return true
+    if (this.#seenEventIds.has(event.id)) return false
+    if (this.#seenEventIds.size >= SEEN_EVENT_LIMIT) {
+      this.#seenEventIds.delete(this.#seenEventIds.values().next().value)
+    }
+    this.#seenEventIds.add(event.id)
+    return true
+  }
+
+  async sendRequest (peerPubkey, method, params = [], {
+    timeout = null,
+    signal,
+    extension
+  } = {}) {
+    if (this.#closed) throw new Error('NIP46_CLOSED')
+    if (typeof method !== 'string' || !method) throw new Error('NIP46_METHOD_REQUIRED')
+    if (!Array.isArray(params) || !params.every(param => typeof param === 'string')) {
+      throw new Error('NIP46_PARAMS_REQUIRED')
+    }
+    if (signal?.aborted) throw new Error('Aborted')
+    const context = this.#activeContext
+    if (!context) throw new Error('NIP46_LISTENER_UNAVAILABLE')
+    await this.awaitContextReady(context, { signal })
+
+    const id = requestId()
+    const response = Promise.withResolvers()
+    const extra = requestExtension(extension)
+    this.#pending.set(id, { ...response, peerPubkey })
+
+    try {
+      await this.publish(peerPubkey, { id, method, params, ...(extra || {}) }, { context })
+      return await waitForNip46(response.promise, {
+        timeout,
+        signal,
+        label: 'NIP46_REQUEST_TIMEOUT'
+      })
+    } finally {
+      const pending = this.#pending.get(id)
+      if (pending?.promise === response.promise) this.#pending.delete(id)
+    }
+  }
+
+  receiveResponse (peerPubkey, response, { onAuthUrl } = {}) {
+    if (!response || typeof response.id !== 'string') return false
+    const pending = this.#pending.get(response.id)
+    if (!pending || pending.peerPubkey !== peerPubkey) return false
+
+    if (response.result === 'auth_url') {
+      try {
+        onAuthUrl?.(typeof response.error === 'string' ? response.error : '')
+      } catch (error) {
+        this.#reportError(error)
+      }
+      return true
+    }
+
+    this.#pending.delete(response.id)
+    if (Object.hasOwn(response, 'error') && response.error !== null && response.error !== undefined) {
+      pending.reject(requestError(response.error))
+    } else if (Object.hasOwn(response, 'result')) {
+      pending.resolve(response.result)
+    } else {
+      pending.reject(new Error('NIP46_INVALID_RESPONSE'))
+    }
+    return true
+  }
+
+  reply (peerPubkey, id, result, error = null, options) {
+    return this.publish(peerPubkey, { id, result, error }, options)
+  }
+
+  async publish (peerPubkey, payload, { context = this.#activeContext } = {}) {
+    if (this.#closed) throw new Error('NIP46_CLOSED')
+    if (!context) throw new Error('NIP46_LISTENER_UNAVAILABLE')
+    await this.awaitContextReady(context)
+    const relays = context.stream.readyRelays
+    if (!relays.length) throw new Error('NIP46_NO_READY_RELAYS')
+    const event = createNip46Event({ secretKey: this.#secretKey, recipientPubkey: peerPubkey, payload })
+    const published = await this.#relayPool.sendEvent(event, relays, {
+      timeout: this.#networkTimeout,
+      timeoutUntilFirstFulfillment: null
+    })
+    if (!published.success) {
+      const report = await published.promise
+      throw requestError(report.errors?.[0]?.reason || 'NIP46_PUBLISH_FAILED')
+    }
+    return event
+  }
+
+  async close () {
+    if (this.#closed) return
+    this.#closed = true
+    for (const timer of this.#retireTimers) clearTimeout(timer)
+    this.#retireTimers.clear()
+    const contexts = [...this.#contexts]
+    for (const context of contexts) context.controller.abort()
+    await Promise.all(contexts.map(context => this.closeContext(context)))
+    this.#activeContext = null
+    for (const pending of this.#pending.values()) pending.reject(new Error('NIP46_CLOSED'))
+    this.#pending.clear()
+  }
+
+  #reportError (error) {
+    try {
+      if (this.#onError) {
+        Promise.resolve(this.#onError(error)).catch(callbackError => {
+          console.error('NIP46 onError failed:', callbackError)
+        })
+      } else console.error('NIP46 stream failed:', error)
+    } catch (callbackError) {
+      console.error('NIP46 onError failed:', callbackError)
+    }
+  }
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "libp2r2p",
+  "version": "0.0.1",
+  "description": "Peer-to-relay-to-peer",
+  "keywords": [
+    "p2r2p",
+    "p2p",
+    "nostr"
+  ],
+  "license": "MIT",
+  "author": "arthurfranca",
+  "type": "module",
+  "sideEffects": false,
+  "scripts": {
+    "test": "node --test --experimental-test-module-mocks 'tests/**/*.test.js'",
+    "test:only": "node --test --test-only --experimental-test-module-mocks 'tests/**/*.test.js'"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./base16": "./base16/index.js",
+    "./base64": "./base64/index.js",
+    "./content-key": "./content-key/index.js",
+    "./content-key/event": "./content-key/event/index.js",
+    "./double-dh": "./double-dh/index.js",
+    "./ecdh": "./ecdh/index.js",
+    "./idb": "./idb/index.js",
+    "./idb-queue": "./idb-queue/index.js",
+    "./key": "./key/index.js",
+    "./network": "./network/index.js",
+    "./nip44-v3": "./nip44-v3/index.js",
+    "./nip46": "./nip46/index.js",
+    "./private-channel": "./private-channel/index.js",
+    "./private-message": "./private-message/index.js",
+    "./private-messenger": "./private-messenger/index.js",
+    "./private-messenger/recovery": "./private-messenger/recovery/index.js",
+    "./relay": "./relay/index.js",
+    "./temporary-storage": "./temporary-storage/index.js",
+    "./web-storage-queue": "./web-storage-queue/index.js"
+  },
+  "dependencies": {
+    "@noble/ciphers": "2.2.0",
+    "@noble/curves": "2.2.0",
+    "@noble/hashes": "2.2.0",
+    "nostr-tools": "2.23.5"
+  },
+  "devDependencies": {
+    "fake-indexeddb": "6.2.5"
+  }
+}

package/private-channel/constants/index.js

@@ -0,0 +1,5 @@
+export const PRIVATE_BROADCAST_KIND = 3560
+export const ROUTER_KIND = 26300
+export const NYM_CARRIER_KIND = 26400
+export const MAX_EVENT_BYTES = 65536
+export const EXPIRATION_SECONDS = 2 * 24 * 60 * 60

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

@@ -0,0 +1,61 @@
+import { MAX_EVENT_BYTES, PRIVATE_BROADCAST_KIND, ROUTER_KIND } from '../constants/index.js'
+import { eventByteLength } from './event.js'
+import { payloadByteLength as nip44v3PayloadByteLength } from '../../nip44-v3/index.js'
+
+const MAX_TIME_SECONDS = 9999999999
+const MAX_CHUNK_TAG_VALUE = '9999999999'
+const SAMPLE_PUBKEY = 'f'.repeat(64)
+const SAMPLE_SIGNATURE = 'f'.repeat(128)
+
+function base64EncodedByteLength (byteLength) {
+  return Math.ceil(byteLength / 3) * 4
+}
+
+function routerPlaintextByteLengthForChunk (jsonlByteLength) {
+  return eventByteLength({
+    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]],
+    content: 'A'.repeat(base64EncodedByteLength(jsonlByteLength)),
+    id: SAMPLE_PUBKEY,
+    sig: SAMPLE_SIGNATURE
+  })
+}
+
+function outerEventByteLengthForChunk (jsonlByteLength) {
+  const contentByteLength = nip44v3PayloadByteLength(routerPlaintextByteLengthForChunk(jsonlByteLength), 0)
+  if (!Number.isFinite(contentByteLength)) return Infinity
+
+  return eventByteLength({
+    kind: PRIVATE_BROADCAST_KIND,
+    created_at: MAX_TIME_SECONDS,
+    // Reserve the deletion capability tag used by high-level private sends.
+    tags: [['s', SAMPLE_PUBKEY], ['expiration', String(MAX_TIME_SECONDS)]],
+    content: 'A'.repeat(contentByteLength),
+    pubkey: SAMPLE_PUBKEY,
+    id: SAMPLE_PUBKEY,
+    sig: SAMPLE_SIGNATURE
+  })
+}
+
+function maxJsonlChunkByteSize () {
+  let min = 1
+  let max = MAX_EVENT_BYTES
+
+  while (min < max) {
+    const mid = Math.ceil((min + max) / 2)
+    if (outerEventByteLengthForChunk(mid) <= MAX_EVENT_BYTES) min = mid
+    else max = mid - 1
+  }
+
+  return min
+}
+
+// NIP-44 v3 padding has large size jumps, so derive this from the actual signed
+// event shapes instead of estimating a flat overhead.
+export const JSONL_CHUNK_BYTES = maxJsonlChunkByteSize()
+// Nym carrier content is a base64 slice of the inner event JSON. The router
+// budget is more conservative because routers carry extra tags, so it is safe
+// to reuse it as the maximum carrier content length.
+export const NYM_CARRIER_CHUNK_CHARS = JSONL_CHUNK_BYTES

package/private-channel/helpers/chunks.js

@@ -0,0 +1,282 @@
+import { generateSecretKey, getPublicKey } from 'nostr-tools'
+import { bytesToBase64, base64ToBytes } from '../../base64/index.js'
+import { bytesToHex } from '../../base16/index.js'
+import { verifyIykcProof } from '../../content-key/event/index.js'
+import * as nip44v3 from '../../nip44-v3/index.js'
+import { JSONL_CHUNK_BYTES } from './chunk-size.js'
+import { ROUTER_KIND } from '../constants/index.js'
+import { createTemporaryStorage } from '../../temporary-storage/index.js'
+
+const encoder = new TextEncoder()
+const decoder = new TextDecoder()
+const STORAGE_PREFIX = 'libp2r2p:private-channel:'
+
+function appendBytes (left, right) {
+  const out = new Uint8Array(left.length + right.length)
+  out.set(left)
+  out.set(right, left.length)
+  return out
+}
+
+function tempKey (id, index) {
+  return `${STORAGE_PREFIX}${id}:${index}`
+}
+
+function rowTempKey (id, index) {
+  return `${STORAGE_PREFIX}${id}:row:${index}`
+}
+
+function normalizeContentKey ({ receiverPubkey, iykcPubkey = '', iykcProof = '' } = {}) {
+  if (!iykcPubkey) return { iykcPubkey: '', iykcProof: '' }
+  if (!verifyIykcProof({ receiverPubkey, iykcPubkey, iykcProof })) throw new Error('INVALID_IYKC_PROOF')
+  return { iykcPubkey, iykcProof }
+}
+
+function receiverRecord (receiver, receiverContentKeys) {
+  if (typeof receiver === 'string') {
+    const fetchedContentKey = normalizeContentKey({ receiverPubkey: receiver, ...receiverContentKeys[receiver] })
+    return {
+      receiverPubkey: receiver,
+      ...fetchedContentKey
+    }
+  }
+
+  if (Array.isArray(receiver)) {
+    const [receiverPubkey, iykcPubkey = '', iykcProof = ''] = receiver
+    const explicitContentKey = normalizeContentKey({ receiverPubkey, iykcPubkey, iykcProof })
+    const fetchedContentKey = normalizeContentKey({ receiverPubkey, ...receiverContentKeys[receiverPubkey] })
+    const contentKey = explicitContentKey.iykcPubkey ? explicitContentKey : fetchedContentKey
+    return {
+      receiverPubkey,
+      ...contentKey
+    }
+  }
+
+  const receiverPubkey = receiver?.receiverPubkey || receiver?.pubkey || ''
+  const explicitContentKey = normalizeContentKey({ receiverPubkey, ...receiver })
+  const fetchedContentKey = normalizeContentKey({ receiverPubkey, ...receiverContentKeys[receiverPubkey] })
+  const resolvedContentKey = explicitContentKey.iykcPubkey ? explicitContentKey : fetchedContentKey
+  return {
+    receiverPubkey,
+    ...resolvedContentKey
+  }
+}
+
+function buildRecipientRow ({ receiverPubkey, iykcPubkey, iykcProof }, ciphertext) {
+  const line = [receiverPubkey, ciphertext]
+  if (iykcPubkey) line.push(iykcPubkey, iykcProof)
+  return JSON.stringify(line)
+}
+
+function buildPayloadRow (ciphertext) {
+  return JSON.stringify([ciphertext])
+}
+
+function encryptedPayload ({ messageSecretKey, event }) {
+  const messagePubkey = getPublicKey(messageSecretKey)
+  return nip44v3.encrypt(messageSecretKey, messagePubkey, ROUTER_KIND, '', JSON.stringify(event))
+}
+
+function appendLine (chunk, line, id, chunkIndex, temporaryStorage) {
+  while (line.length) {
+    const available = JSONL_CHUNK_BYTES - chunk.length
+    chunk = appendBytes(chunk, line.slice(0, available))
+    line = line.slice(available)
+    if (chunk.length === JSONL_CHUNK_BYTES) {
+      temporaryStorage.setItem(tempKey(id, chunkIndex++), bytesToBase64(chunk))
+      chunk = new Uint8Array()
+    }
+  }
+  return { chunk, chunkIndex }
+}
+
+function appendRow (chunk, row, id, chunkIndex, temporaryStorage) {
+  return appendLine(chunk, encoder.encode(`${row}\n`), id, chunkIndex, temporaryStorage)
+}
+
+function joinByteChunks (parts) {
+  let length = 0
+  const decoded = parts.map(part => {
+    const bytes = base64ToBytes(part)
+    length += bytes.length
+    return bytes
+  })
+  const out = new Uint8Array(length)
+  let offset = 0
+  for (const bytes of decoded) {
+    out.set(bytes, offset)
+    offset += bytes.length
+  }
+  return out
+}
+
+function storageFor (temporaryStorage) {
+  return temporaryStorage || createTemporaryStorage()
+}
+
+export function readChunkContent (id, index, temporaryStorage) {
+  return storageFor(temporaryStorage).getItem(tempKey(id, index))
+}
+
+export function decodeChunkLines (content) {
+  return decodeChunkText(content).split('\n').filter(Boolean)
+}
+
+export function decodeChunkText (content) {
+  return decoder.decode(base64ToBytes(content))
+}
+
+export function joinChunksAsBase64 (parts) {
+  return bytesToBase64(joinByteChunks(parts))
+}
+
+export function receiverPubkeys (receivers) {
+  return receivers.map(receiver => receiverRecord(receiver, {}).receiverPubkey).filter(Boolean)
+}
+
+export function receiverPubkeysWithoutContentKeys (receivers) {
+  return receivers
+    .map(receiver => receiverRecord(receiver, {}))
+    .filter(receiver => receiver.receiverPubkey && !receiver.iykcPubkey)
+    .map(receiver => receiver.receiverPubkey)
+}
+
+function temporaryId () {
+  return `${Date.now()}:${Math.random().toString(16).slice(2)}`
+}
+
+function cleanupPreparedRows (id, totalRows, temporaryStorage) {
+  const keys = []
+  for (let i = 0; i < totalRows; i++) keys.push(rowTempKey(id, i))
+  storageFor(temporaryStorage).removeItems(keys)
+}
+
+function setPreparedRow (id, index, row, temporaryStorage) {
+  storageFor(temporaryStorage).setItem(rowTempKey(id, index), row)
+}
+
+function readPreparedRow (preparedRows, index) {
+  const row = storageFor(preparedRows.temporaryStorage).getItem(rowTempKey(preparedRows.id, index))
+  if (typeof row !== 'string') throw new Error('MISSING_PREPARED_ROW')
+  return row
+}
+
+async function prepareEnvelopeRowsOnce ({ id, senderSigner, receivers, receiverContentKeys = {}, event, rowScope = '', temporaryStorage }) {
+  const useDoubleDh = typeof senderSigner?.nip44EncryptDoubleDH === 'function'
+  let foundOwnContentPubkey = false
+  let usedOwnContentPubkey = ''
+  const messageSecretKey = generateSecretKey()
+  const messageSeckey = bytesToHex(messageSecretKey)
+  const rowIndexes = []
+  const receiverPubkeys = []
+  const receiverRowIndexesByPubkey = {}
+
+  setPreparedRow(id, 0, buildPayloadRow(encryptedPayload({ messageSecretKey, event })), temporaryStorage)
+
+  for (const receiver of receivers) {
+    const row = receiverRecord(receiver, useDoubleDh ? receiverContentKeys : {})
+    let ciphertext
+    if (useDoubleDh) {
+      const encrypted = await senderSigner.nip44EncryptDoubleDH(
+        row.receiverPubkey,
+        ROUTER_KIND,
+        rowScope,
+        bytesToBase64(encoder.encode(messageSeckey)),
+        row.iykcPubkey
+      )
+      ciphertext = encrypted[0]
+      const nextContentPubkey = encrypted[1] || ''
+      if (foundOwnContentPubkey && nextContentPubkey !== usedOwnContentPubkey) {
+        throw new Error('INCONSISTENT_IMKC_PUBKEY')
+      }
+      foundOwnContentPubkey = true
+      if (nextContentPubkey) usedOwnContentPubkey = nextContentPubkey
+    } else {
+      ciphertext = await senderSigner.nip44v3Encrypt(row.receiverPubkey, ROUTER_KIND, rowScope, bytesToBase64(encoder.encode(messageSeckey)))
+    }
+    const rowIndex = rowIndexes.length + 1
+    setPreparedRow(id, rowIndex, buildRecipientRow(row, ciphertext), temporaryStorage)
+    rowIndexes.push(rowIndex)
+    receiverPubkeys.push(row.receiverPubkey)
+    if (row.receiverPubkey && receiverRowIndexesByPubkey[row.receiverPubkey] === undefined) {
+      receiverRowIndexesByPubkey[row.receiverPubkey] = rowIndex
+    }
+  }
+
+  return {
+    id,
+    totalRows: rowIndexes.length + 1,
+    rowIndexes,
+    receiverPubkeys,
+    receiverRowIndexesByPubkey,
+    ownContentPubkey: usedOwnContentPubkey,
+    temporaryStorage
+  }
+}
+
+export async function prepareEnvelopeRows ({ temporaryStorageArea, ...options } = {}) {
+  const temporaryStorage = createTemporaryStorage({ storageArea: temporaryStorageArea })
+  const maxRows = (options.receivers?.length || 0) + 1
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const id = temporaryId()
+    try {
+      return await prepareEnvelopeRowsOnce({ ...options, id, temporaryStorage })
+    } catch (err) {
+      cleanupPreparedRows(id, maxRows, temporaryStorage)
+      if (err?.message === 'INCONSISTENT_IMKC_PUBKEY' && attempt === 0) continue
+      throw err
+    }
+  }
+}
+
+export function cleanupEnvelopeRows (preparedRows) {
+  if (!preparedRows?.id || !Number.isSafeInteger(preparedRows.totalRows)) return
+  cleanupPreparedRows(preparedRows.id, preparedRows.totalRows, preparedRows.temporaryStorage)
+}
+
+export function preparedRowIndexesForReceivers (preparedRows, receivers) {
+  const indexes = []
+  const seen = new Set()
+  for (const receiver of receivers || []) {
+    const pubkey = receiverRecord(receiver, {}).receiverPubkey
+    const index = preparedRows?.receiverRowIndexesByPubkey?.[pubkey]
+    if (!pubkey || index === undefined) throw new Error('MISSING_PREPARED_RECEIVER')
+    if (seen.has(index)) continue
+    seen.add(index)
+    indexes.push(index)
+  }
+  return indexes
+}
+
+export function writeChunksFromPreparedRows (preparedRows, rowIndexes = preparedRows?.rowIndexes || []) {
+  const temporaryStorage = storageFor(preparedRows?.temporaryStorage)
+  const id = temporaryId()
+  let chunk = new Uint8Array()
+  let chunkIndex = 0
+  try {
+    ;({ chunk, chunkIndex } = appendRow(chunk, readPreparedRow(preparedRows, 0), id, chunkIndex, temporaryStorage))
+    for (const rowIndex of rowIndexes) {
+      ;({ chunk, chunkIndex } = appendRow(chunk, readPreparedRow(preparedRows, rowIndex), id, chunkIndex, temporaryStorage))
+    }
+    if (chunk.length || chunkIndex === 0) temporaryStorage.setItem(tempKey(id, chunkIndex++), bytesToBase64(chunk))
+    return { id, total: chunkIndex, ownContentPubkey: preparedRows.ownContentPubkey || '' }
+  } catch (err) {
+    cleanupChunks(id, chunkIndex + 1, temporaryStorage)
+    throw err
+  }
+}
+
+export async function writeChunks (options) {
+  const preparedRows = await prepareEnvelopeRows(options)
+  try {
+    return writeChunksFromPreparedRows(preparedRows)
+  } finally {
+    cleanupEnvelopeRows(preparedRows)
+  }
+}
+
+export function cleanupChunks (id, total, temporaryStorage) {
+  const keys = []
+  for (let i = 0; i < total; i++) keys.push(tempKey(id, i))
+  storageFor(temporaryStorage).removeItems(keys)
+}