@comapeo/core 1.0.0

package/src/invite-api.js

@@ -0,0 +1,450 @@
+import { TypedEmitter } from 'tiny-typed-emitter'
+import { pEvent } from 'p-event'
+import { InviteResponse_Decision } from './generated/rpc.js'
+import { assert, keyToId, noop } from './utils.js'
+import HashMap from './lib/hashmap.js'
+import timingSafeEqual from './lib/timing-safe-equal.js'
+import { Logger } from './logger.js'
+/** @import { MapBuffers } from './types.js' */
+/**
+ * @import {
+ *   Invite as InviteRpcMessage,
+ *   InviteCancel,
+ *   ProjectJoinDetails
+ * } from './generated/rpc.js'
+ */
+
+// There are three slightly different invite types:
+//
+// - InviteRpcMessage comes from the protobuf.
+// - InviteInternal adds a locally-generated receive timestamp.
+// - Invite is the externally-facing type.
+
+/**
+ * @internal
+ * @typedef {InviteRpcMessage & { receivedAt: number }} InviteInternal
+ */
+
+/** @typedef {MapBuffers<InviteInternal>} Invite */
+
+/**
+ * @typedef {(
+ *  'accepted' |
+ *  'rejected' |
+ *  'canceled' |
+ *  'accepted other' |
+ *  'connection error' |
+ *  'internal error'
+ * )} InviteRemovalReason
+ */
+
+/**
+ * Manage pending invite state.
+ */
+class PendingInvites {
+  /**
+   * @internal
+   * @typedef {object} PendingInvite
+   * @prop {string} peerId
+   * @prop {InviteInternal} invite
+   * @prop {boolean} isAccepting
+   */
+
+  /** @type {HashMap<Buffer, PendingInvite>} */
+  #byInviteId = new HashMap(keyToId)
+
+  /**
+   * @returns {Iterable<PendingInvite>} the pending invites, in insertion order
+   */
+  invites() {
+    return this.#byInviteId.values()
+  }
+
+  /**
+   * @param {PendingInvite} pendingInvite
+   * @throws if adding a duplicate invite ID
+   * @returns {void}
+   */
+  add(pendingInvite) {
+    const {
+      invite: { inviteId },
+    } = pendingInvite
+    assert(!this.#byInviteId.has(inviteId), 'Added duplicate invite')
+    this.#byInviteId.set(inviteId, pendingInvite)
+  }
+
+  /**
+   * @param {Buffer} inviteId
+   * @returns {void}
+   */
+  markAccepting(inviteId) {
+    const pendingInvite = this.#byInviteId.get(inviteId)
+    assert(
+      !!pendingInvite,
+      `Couldn't find invite for ${inviteId.toString('hex')}`
+    )
+    this.#byInviteId.set(inviteId, { ...pendingInvite, isAccepting: true })
+  }
+
+  /**
+   * @param {Buffer} inviteId
+   * @returns {boolean}
+   */
+  hasInviteId(inviteId) {
+    return this.#byInviteId.has(inviteId)
+  }
+
+  /**
+   * @param {Readonly<Buffer>} projectInviteId
+   * @returns {boolean}
+   */
+  isAcceptingForProject(projectInviteId) {
+    for (const { invite, isAccepting } of this.invites()) {
+      if (isAccepting && invite.projectInviteId.equals(projectInviteId)) {
+        return true
+      }
+    }
+    return false
+  }
+
+  /**
+   * @param {Buffer} inviteId
+   * @returns {undefined | PendingInvite}
+   */
+  getByInviteId(inviteId) {
+    return this.#byInviteId.get(inviteId)
+  }
+
+  /**
+   * @param {Buffer} inviteId
+   * @returns {boolean} `true` if an invite existed and was deleted, `false` otherwise
+   */
+  deleteByInviteId(inviteId) {
+    return this.#byInviteId.delete(inviteId)
+  }
+
+  /**
+   * @param {Readonly<Buffer>} projectInviteId
+   * @returns {PendingInvite[]} the pending invites that were deleted
+   */
+  deleteByProjectInviteId(projectInviteId) {
+    /** @type {PendingInvite[]} */
+    const result = []
+
+    for (const pendingInvite of this.invites()) {
+      if (pendingInvite.invite.projectInviteId.equals(projectInviteId)) {
+        result.push(pendingInvite)
+      }
+    }
+
+    for (const { invite } of result) this.deleteByInviteId(invite.inviteId)
+
+    return result
+  }
+}
+
+/**
+ * @typedef {Object} InviteApiEvents
+ * @property {(invite: Invite) => void} invite-received
+ * @property {(invite: Invite, removalReason: InviteRemovalReason) => void} invite-removed
+ */
+
+/**
+ * @extends {TypedEmitter<InviteApiEvents>}
+ */
+export class InviteApi extends TypedEmitter {
+  #getProjectByInviteId
+  #addProject
+  #pendingInvites = new PendingInvites()
+  #l
+
+  /**
+   * @param {Object} options
+   * @param {import('./local-peers.js').LocalPeers} options.rpc
+   * @param {object} options.queries
+   * @param {(projectInviteId: Readonly<Buffer>) => undefined | { projectPublicId: string }} options.queries.getProjectByInviteId
+   * @param {(projectDetails: Pick<ProjectJoinDetails, 'projectKey' | 'encryptionKeys'> & { projectName: string }) => Promise<string>} options.queries.addProject
+   * @param {Logger} [options.logger]
+   */
+  constructor({ rpc, queries, logger }) {
+    super()
+
+    this.#l = Logger.create('InviteApi', logger)
+
+    this.rpc = rpc
+    this.#getProjectByInviteId = queries.getProjectByInviteId
+    this.#addProject = queries.addProject
+
+    this.rpc.on('invite', (...args) => {
+      try {
+        this.#handleInviteRpcMessage(...args)
+      } catch (err) {
+        console.error('Error handling invite', err)
+      }
+    })
+
+    this.rpc.on('invite-cancel', (_peerId, inviteCancel) => {
+      try {
+        this.#handleInviteCancel(inviteCancel)
+      } catch (err) {
+        console.error('Error handling invite cancel', err)
+      }
+    })
+  }
+
+  /**
+   * @param {string} peerId
+   * @param {InviteRpcMessage} inviteRpcMessage
+   */
+  #handleInviteRpcMessage(peerId, inviteRpcMessage) {
+    const invite = { ...inviteRpcMessage, receivedAt: Date.now() }
+
+    this.#l.log('Received invite %h from %S', invite.inviteId, peerId)
+
+    const isAlreadyMember = Boolean(
+      this.#getProjectByInviteId(invite.projectInviteId)
+    )
+    if (isAlreadyMember) {
+      this.#l.log('Invite %h: already in project', invite.inviteId)
+      this.rpc
+        .sendInviteResponse(peerId, {
+          decision: InviteResponse_Decision.ALREADY,
+          inviteId: invite.inviteId,
+        })
+        .catch(noop)
+      return
+    }
+
+    const hasAlreadyReceivedThisInvite = this.#pendingInvites.hasInviteId(
+      invite.inviteId
+    )
+    if (hasAlreadyReceivedThisInvite) {
+      this.#l.log('Invite %h: already received this invite', invite.inviteId)
+      return
+    }
+
+    this.#pendingInvites.add({ peerId, invite, isAccepting: false })
+    this.emit('invite-received', internalToExternal(invite))
+  }
+
+  /**
+   * @param {InviteCancel} inviteCancel
+   */
+  #handleInviteCancel(inviteCancel) {
+    const { inviteId } = inviteCancel
+
+    this.#l.log('Received invite cancel for invite ID %h', inviteId)
+
+    const pendingInvite = this.#pendingInvites.getByInviteId(inviteId)
+    if (!pendingInvite) {
+      this.#l.log(
+        'Received invite cancel for %h but no such invite exists',
+        inviteId
+      )
+      return
+    }
+    const { invite, isAccepting } = pendingInvite
+
+    if (isAccepting) {
+      this.#l.log(
+        "Received invite cancel for %h but we're already accepting",
+        inviteId
+      )
+      return
+    }
+
+    this.#pendingInvites.deleteByInviteId(inviteId)
+    this.emit('invite-removed', internalToExternal(invite), 'canceled')
+  }
+
+  /**
+   * @returns {Array<Invite>}
+   */
+  getPending() {
+    return [...this.#pendingInvites.invites()].map(({ invite }) =>
+      internalToExternal(invite)
+    )
+  }
+
+  /**
+   * Attempt to accept the invite.
+   *
+   * This can fail if the invitor has canceled the invite or if you cannot
+   * connect to the invitor's device.
+   *
+   * If the invite is accepted and you had other invites to the same project,
+   * those invites are removed, and the invitors are told that you're already
+   * part of this project.
+   *
+   * @param {Pick<Invite, 'inviteId'>} invite
+   * @returns {Promise<string>}
+   */
+  async accept({ inviteId: inviteIdString }) {
+    const inviteId = Buffer.from(inviteIdString, 'hex')
+
+    const pendingInvite = this.#pendingInvites.getByInviteId(inviteId)
+    if (!pendingInvite) {
+      throw new Error(`Cannot find invite ID ${inviteIdString}`)
+    }
+
+    const { peerId, invite } = pendingInvite
+    const { projectName, projectInviteId } = invite
+
+    /** @param {InviteRemovalReason} removalReason */
+    const removePendingInvite = (removalReason) => {
+      const didDelete = this.#pendingInvites.deleteByInviteId(inviteId)
+      if (didDelete) {
+        this.emit('invite-removed', internalToExternal(invite), removalReason)
+      }
+    }
+
+    // This is probably impossible in the UI, but it's theoretically possible
+    // to join a project while an invite is pending, so we need to check this.
+    const existingProject = this.#getProjectByInviteId(projectInviteId)
+    if (existingProject) {
+      this.#l.log(
+        "Went to accept invite %h but we're already in the project",
+        inviteId
+      )
+      const pendingInvitesDeleted =
+        this.#pendingInvites.deleteByProjectInviteId(projectInviteId)
+      for (const pendingInvite of pendingInvitesDeleted) {
+        this.rpc
+          .sendInviteResponse(pendingInvite.peerId, {
+            decision: InviteResponse_Decision.ALREADY,
+            inviteId: pendingInvite.invite.inviteId,
+          })
+          .catch(noop)
+        this.emit(
+          'invite-removed',
+          internalToExternal(pendingInvite.invite),
+          'accepted'
+        )
+      }
+      return existingProject.projectPublicId
+    }
+
+    assert(
+      !this.#pendingInvites.isAcceptingForProject(projectInviteId),
+      `Cannot double-accept invite for project ${projectInviteId
+        .toString('hex')
+        .slice(0, 7)}`
+    )
+    this.#pendingInvites.markAccepting(inviteId)
+
+    const projectDetailsAbortController = new AbortController()
+
+    const projectDetailsPromise =
+      /** @type {typeof pEvent<'got-project-details', [string, ProjectJoinDetails]>} */ (
+        pEvent
+      )(this.rpc, 'got-project-details', {
+        multiArgs: true,
+        filter: ([projectDetailsPeerId, details]) =>
+          // This peer ID check is probably superfluous because the invite ID
+          // should be unguessable, but might be useful if someone forwards an
+          // invite message (or if there's an unforeseen bug).
+          timingSafeEqual(projectDetailsPeerId, peerId) &&
+          timingSafeEqual(inviteId, details.inviteId),
+        signal: projectDetailsAbortController.signal,
+      })
+        .then((args) => args?.[1])
+        .catch(noop)
+
+    this.#l.log('Sending accept response for invite %h', inviteId)
+
+    try {
+      await this.rpc.sendInviteResponse(peerId, {
+        decision: InviteResponse_Decision.ACCEPT,
+        inviteId,
+      })
+    } catch (e) {
+      projectDetailsAbortController.abort()
+      removePendingInvite('connection error')
+      throw new Error('Could not accept invite: Peer disconnected')
+    }
+
+    /** @type {string} */ let projectPublicId
+
+    try {
+      const details = await projectDetailsPromise
+      assert(details, 'Expected project details')
+      projectPublicId = await this.#addProject({ ...details, projectName })
+    } catch (e) {
+      removePendingInvite('internal error')
+      throw new Error('Failed to join project')
+    }
+
+    const pendingInvitesDeleted =
+      this.#pendingInvites.deleteByProjectInviteId(projectInviteId)
+
+    for (const pendingInvite of pendingInvitesDeleted) {
+      const isPendingInviteWeJustAccepted =
+        // Unlike the above, these don't need to be timing-safe, because
+        // it's unlikely this method is vulnerable to timing attacks.
+        peerId === pendingInvite.peerId &&
+        inviteId.equals(pendingInvite.invite.inviteId)
+      if (isPendingInviteWeJustAccepted) continue
+
+      this.#l.log(
+        'Sending "already" response for invite %h to %S',
+        inviteId,
+        pendingInvite.peerId
+      )
+
+      this.rpc
+        .sendInviteResponse(pendingInvite.peerId, {
+          decision: InviteResponse_Decision.ALREADY,
+          inviteId: pendingInvite.invite.inviteId,
+        })
+        .catch(noop)
+      this.emit(
+        'invite-removed',
+        internalToExternal(pendingInvite.invite),
+        'accepted other'
+      )
+    }
+
+    this.emit('invite-removed', internalToExternal(invite), 'accepted')
+
+    return projectPublicId
+  }
+
+  /**
+   * @param {Pick<Invite, 'inviteId'>} invite
+   * @returns {void}
+   */
+  reject({ inviteId: inviteIdString }) {
+    const inviteId = Buffer.from(inviteIdString, 'hex')
+
+    const pendingInvite = this.#pendingInvites.getByInviteId(inviteId)
+    assert(!!pendingInvite, `Cannot find invite ${inviteId}`)
+
+    const { peerId, invite, isAccepting } = pendingInvite
+
+    assert(!isAccepting, `Cannot reject ${inviteIdString}`)
+
+    this.#l.log('Rejecting invite %h', inviteId)
+
+    this.rpc
+      .sendInviteResponse(peerId, {
+        decision: InviteResponse_Decision.REJECT,
+        inviteId: invite.inviteId,
+      })
+      .catch(noop)
+
+    this.#pendingInvites.deleteByInviteId(inviteId)
+    this.emit('invite-removed', internalToExternal(invite), 'rejected')
+  }
+}
+
+/**
+ * @param {InviteInternal} internal
+ * @returns {Invite}
+ */
+function internalToExternal(internal) {
+  return {
+    ...internal,
+    inviteId: internal.inviteId.toString('hex'),
+    projectInviteId: internal.projectInviteId.toString('hex'),
+  }
+}

package/src/lib/hashmap.js

@@ -0,0 +1,91 @@
+/** @typedef {string | number | bigint | boolean | undefined | symbol | null} Primitive */
+
+/**
+ * `Map` uses same-value-zero equality for keys, which makes it more difficult
+ * to use reference types like buffers.
+ *
+ * `HashMap` is very similar to `Map`, but accepts a hash function for keys.
+ * This function should return a primitive, such as a number or string, which
+ * will be used as the key.
+ *
+ * It doesn't contain all the functionality of `Map` because we don't need it,
+ * but it should be fairly easy to update as needed.
+ *
+ * @template K
+ * @template {unknown} V
+ * @example
+ * const join = (arr) => arr.join(' ')
+ *
+ * const map = new HashMap(join)
+ *
+ * map.set([1, 2], 3)
+ * map.get([1, 2])
+ * // => 3
+ */
+export default class HashMap {
+  #hash
+
+  /** @type {Map<Primitive, V>} */
+  #realMap = new Map()
+
+  /**
+   * @param {(key: K) => Primitive} hash
+   * @param {Iterable<[K, V]>} [iterable=[]]
+   */
+  constructor(hash, iterable = []) {
+    this.#hash = hash
+    for (const [key, value] of iterable) this.set(key, value)
+  }
+
+  /**
+   * @returns {number}
+   */
+  get size() {
+    return this.#realMap.size
+  }
+
+  /**
+   * @param {K} key The key to remove.
+   * @returns {boolean} `true` if the key was present and removed, `false` otherwise.
+   */
+  delete(key) {
+    const realKey = this.#hash(key)
+    return this.#realMap.delete(realKey)
+  }
+
+  /**
+   * @param {K} key The key to look up.
+   * @returns {undefined | V} The element associated with `key`, or `undefined` if it's not present.
+   */
+  get(key) {
+    const realKey = this.#hash(key)
+    return this.#realMap.get(realKey)
+  }
+
+  /**
+   * @param {K} key The key to look up.
+   * @returns {boolean} `true` if `key` is present in the map, `false` otherwise.
+   */
+  has(key) {
+    const realKey = this.#hash(key)
+    return this.#realMap.has(realKey)
+  }
+
+  /**
+   * @param {K} key The key to update.
+   * @param {V} value The value to add at `key`.
+   * @returns {this} The map.
+   */
+  set(key, value) {
+    const realKey = this.#hash(key)
+    this.#realMap.set(realKey, value)
+    return this
+  }
+
+  /**
+   * @returns {IterableIterator<V>}
+   */
+  values() {
+    return this.#realMap.values()
+  }
+}

package/src/lib/hypercore-helpers.js

@@ -0,0 +1,18 @@
+import { assert } from '../utils.js'
+
+/**
+ * @param {import('hypercore')<'binary', any>} core Core to unreplicate. Must be ready.
+ * @param {import('protomux')} protomux
+ */
+export function unreplicate(core, protomux) {
+  assert(core.discoveryKey, 'Core should have a discovery key')
+  protomux.unpair({
+    protocol: 'hypercore/alpha',
+    id: core.discoveryKey,
+  })
+  for (const channel of protomux) {
+    if (channel.protocol !== 'hypercore/alpha') continue
+    if (!channel.id.equals(core.discoveryKey)) continue
+    channel.close()
+  }
+}

package/src/lib/noise-secret-stream-helpers.js

@@ -0,0 +1,37 @@
+/** @import { Duplex as NodeDuplex } from 'node:stream' */
+/** @import { Duplex as StreamxDuplex } from 'streamx' */
+/** @import NoiseSecretStream from '@hyperswarm/secret-stream' */
+
+/**
+ * @internal
+ * @typedef {NodeDuplex | StreamxDuplex} RawStream
+ */
+
+/**
+ * @template {RawStream} [T=RawStream]
+ * @typedef {NoiseSecretStream<T> & { destroyed: true }} DestroyedNoiseStream
+ */
+
+/**
+ * @template {RawStream} [T=RawStream]
+ * @typedef {NoiseSecretStream<T> & {
+ *   publicKey: Buffer,
+ *   remotePublicKey: Buffer,
+ *   handshake: Buffer,
+ *   destroyed: false
+ * }} OpenedNoiseStream
+ */
+
+/**
+ * Utility to await a NoiseSecretStream to open, that returns a stream with the
+ * correct types for publicKey and remotePublicKey (which can be null before
+ * stream is opened)
+ *
+ * @template {RawStream} T
+ * @param {NoiseSecretStream<T>} stream
+ * @returns {Promise<OpenedNoiseStream<T> | DestroyedNoiseStream<T>>}
+ */
+export async function openedNoiseSecretStream(stream) {
+  await stream.opened
+  return /** @type {OpenedNoiseStream<T> | DestroyedNoiseStream<T>} */ (stream)
+}

package/src/lib/ponyfills.js

@@ -0,0 +1,25 @@
+/**
+ * Ponyfill of `AbortSignal.any()`.
+ *
+ * [0]: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/any_static
+ *
+ * @param {Iterable<AbortSignal>} iterable
+ * @returns {AbortSignal}
+ */
+export function abortSignalAny(iterable) {
+  for (const signal of iterable) {
+    if (signal.aborted) return AbortSignal.abort(signal.reason)
+  }
+
+  /** @type {Array<() => unknown>} */
+  const listeners = []
+  const controller = new AbortController()
+
+  for (const signal of iterable) {
+    const listener = () => controller.abort(signal.reason)
+    signal.addEventListener('abort', listener)
+    listeners.push(listener)
+  }
+
+  return controller.signal
+}

package/src/lib/string.js

@@ -0,0 +1,7 @@
+/**
+ * Returns `true` if the string is empty or only contains whitespace, `false` otherwise.
+ *
+ * @param {string} str
+ * @returns {boolean}
+ */
+export const isBlank = (str) => !str.trim()

package/src/lib/timing-safe-equal.js

@@ -0,0 +1,34 @@
+import * as crypto from 'node:crypto'
+
+/**
+ * @param {string | NodeJS.ArrayBufferView} value
+ * @returns {NodeJS.ArrayBufferView}
+ */
+const bufferify = (value) =>
+  // We use UTF-16 because it's the only supported encoding that doesn't
+  // touch surrogate pairs. See [this post][0] for more details.
+  //
+  // [0]: https://evanhahn.com/crypto-timingsafeequal-with-strings/
+  typeof value === 'string' ? Buffer.from(value, 'utf16le') : value
+
+/**
+ * Compare two values in constant time.
+ *
+ * Useful when you want to avoid leaking data.
+ *
+ * Like `crypto.timingSafeEqual`, but works with strings and doesn't throw if
+ * lengths differ.
+ *
+ * @template {string | NodeJS.ArrayBufferView} T
+ * @param {T} a
+ * @param {T} b
+ * @returns {boolean}
+ */
+export default function timingSafeEqual(a, b) {
+  const bufferA = bufferify(a)
+  const bufferB = bufferify(b)
+  return (
+    bufferA.byteLength === bufferB.byteLength &&
+    crypto.timingSafeEqual(bufferA, bufferB)
+  )
+}