@cero-base/core 0.2.0 → 0.4.1

package/src/pairing/index.js

@@ -0,0 +1,482 @@
+import BlindPairing from 'blind-pairing'
+import ReadyResource from 'ready-resource'
+import safetyCatch from 'safety-catch'
+import b4a from 'b4a'
+import c from 'compact-encoding'
+import { discoveryKey, keyPair, sign } from 'hypercore-crypto'
+
+import { Invite } from './invite.js'
+import { getEncoding } from '../lib/spec/index.js'
+import { CeroError } from '../lib/errors.js'
+
+const STATUS_OK = 0
+const STATUS_DENIED = 1
+
+// Wire envelope carried in BlindPairing's `additional.data` on the confirm response.
+// We piggyback on the confirm path for *both* success and deny — blind-pairing's
+// native deny() has no payload field, and its discoveryKey check pins the wire
+// `key` to the invite, so the real resource key flows through this envelope.
+const Response = getEncoding('@cero/confirm')
+
+/**
+ * @typedef {object} PairingOpts
+ * @property {import('../network/index.js').Network} network         Network to host the BlindPairing member.
+ * @property {import('../identity/index.js').Identity} identity      Identity used to sign invites and derive the topic.
+ * @property {Uint8Array} [topic]                                    Optional override topic; defaults to `identity.publicKey`.
+ * @property {any} [inviteEncoding]                                  compact-encoding type for the invite payload `data`.
+ * @property {any} [joinerEncoding]                                  compact-encoding type for the joiner-supplied `userData`.
+ *
+ * @typedef {object} CreateInviteOpts
+ * @property {string} [role]                                         Role tag bound into the invite.
+ * @property {number} [expiresIn]                                    TTL in ms; `0`/omitted = no expiry.
+ * @property {any} [data]                                            Arbitrary payload (encoded via `inviteEncoding` when set).
+ *
+ * @typedef {object} JoinOpts
+ * @property {any} [userData]                                        Payload sent with the candidate request.
+ * @property {number} [timeout]                                      Deadline for the handshake, in ms. Defaults to 30000.
+ *
+ * @typedef {object} ConfirmOpts
+ * @property {Uint8Array} [key]                                      32-byte resource key delivered to the joiner; required at runtime.
+ * @property {Uint8Array | null} [encryptionKey]                     Optional 32-byte symmetric key.
+ * @property {Uint8Array | null} [additional]                        Extra opaque bytes piggybacked on the response.
+ *
+ * @typedef {{ key: Uint8Array, encryptionKey: Uint8Array | null, additional: Uint8Array | null }} JoinResult
+ *
+ * @typedef {object} CandidateOpts
+ * @property {Pairing} pairing                                       Owning Pairing instance.
+ * @property {any} req                                               blind-pairing candidate request being answered.
+ * @property {Invite} invite                                         Invite the candidate paired against.
+ * @property {Uint8Array} seed                                       Per-invite seed used to sign the response.
+ * @property {any} userData                                          Decoded joiner payload (raw bytes when no encoding).
+ * @property {() => void} onsettle                                   Called once when the candidate is confirmed or denied.
+ */
+
+/**
+ * Blind-pairing membership wrapper. Hosts invites, dispatches incoming
+ * candidates to the application for accept/deny, and provides the joiner
+ * side of the handshake. All wire payloads are signed and routed through
+ * the supplied network.
+ */
+export class Pairing extends ReadyResource {
+  /** @param {PairingOpts} [opts] */
+  constructor({ network, identity, topic, inviteEncoding = null, joinerEncoding = null } = {}) {
+    super()
+    if (!network) throw CeroError.REQUIRED('network')
+    if (!identity) throw CeroError.REQUIRED('identity')
+
+    this.network = network
+    this.identity = identity
+    this.topic = topic || identity.publicKey
+    this.inviteEncoding = inviteEncoding
+    this.joinerEncoding = joinerEncoding
+
+    this._blind = null
+    this._member = null
+    this._invites = new Map() // inviteId.hex → record
+    this._candidates = new Set() // active joiner candidates
+  }
+
+  async _open() {
+    await this.network.ready()
+    this._blind = new BlindPairing(this.network.swarm)
+    await this._blind.ready()
+
+    this._member = this._blind.addMember({
+      discoveryKey: discoveryKey(this.topic),
+      onadd: (req) => this._onCandidate(req).catch(safetyCatch)
+    })
+  }
+
+  async _close() {
+    for (const candidate of [...this._candidates]) candidate._fail(CeroError.CLOSED('Pairing'))
+    this._candidates.clear()
+
+    if (this._member) {
+      await this._member.close()
+      this._member = null
+    }
+    if (this._blind) {
+      await this._blind.close()
+      this._blind = null
+    }
+    this._invites.clear()
+  }
+
+  /**
+   * Mint a new pairing invite. Returns its canonical wire form (z32 string).
+   *
+   * @param {CreateInviteOpts} [opts]
+   * @returns {Promise<string>}
+   */
+  async createInvite({ role = '', expiresIn = 0, data = null } = {}) {
+    if (this.closing || this.closed) throw CeroError.CLOSED('Pairing')
+    if (!this.opened) await this.ready()
+
+    // Rendezvous key matches the Member topic so candidates land on the right
+    // Pairing instance (per-handle keys avoid identity-wide collisions).
+    const blind = BlindPairing.createInvite(this.topic)
+
+    const invite = Invite.create({
+      secretKey: this.identity.secretKey,
+      publicKey: this.identity.publicKey,
+      role,
+      expiresIn,
+      data,
+      blindInvite: blind.invite,
+      encoding: this.inviteEncoding
+    })
+
+    const id = b4a.toString(blind.id, 'hex')
+    this._invites.set(id, {
+      id: blind.id,
+      seed: blind.seed,
+      publicKey: blind.publicKey,
+      invite
+    })
+
+    return invite.toString()
+  }
+
+  /**
+   * Forget a previously-minted invite. New candidates carrying it will be
+   * dropped silently.
+   *
+   * @param {string} inviteStr
+   * @returns {boolean}
+   */
+  revoke(inviteStr) {
+    for (const [id, record] of this._invites) {
+      if (record.invite.toString() === inviteStr) {
+        this._invites.delete(id)
+        return true
+      }
+    }
+    return false
+  }
+
+  /**
+   * Cheap structural test for a candidate invite string.
+   *
+   * @param {unknown} str
+   * @returns {boolean}
+   */
+  static isInvite(str) {
+    return Invite.isInvite(str)
+  }
+
+  /**
+   * Joiner side — start a pairing handshake against `inviteStr` and resolve
+   * with the host's response when the host confirms.
+   *
+   * @param {string} inviteStr
+   * @param {JoinOpts} [opts]
+   * @returns {Promise<JoinResult>}
+   */
+  async join(inviteStr, { userData = null, timeout = 30000 } = {}) {
+    if (this.closing || this.closed) throw CeroError.CLOSED('Pairing')
+    if (!this.opened) await this.ready()
+
+    let invite
+    try {
+      invite = Invite.parse(inviteStr, { encoding: this.inviteEncoding })
+    } catch (err) {
+      if (err instanceof CeroError) throw err
+      throw CeroError.INVALID_INVITE(err.message)
+    }
+
+    if (invite.expired) throw CeroError.EXPIRED()
+
+    const encodedUserData = encodeUserData(userData, this.joinerEncoding)
+    const candidate = new JoinerCandidate(this, invite, encodedUserData, timeout)
+    return candidate.start()
+  }
+
+  /**
+   * Whether the underlying blind-pairing layer is suspended.
+   *
+   * @returns {boolean}
+   */
+  get suspended() {
+    return this._blind?.suspended === true
+  }
+
+  /**
+   * Pause blind-pairing — keeps state, drops sockets. Idempotent.
+   *
+   * @returns {Promise<void>}
+   */
+  async suspend() {
+    if (!this._blind || this.closing || this.closed) return
+    if (this._blind.suspended) return
+    try {
+      await this._blind.suspend()
+    } catch (err) {
+      safetyCatch(err)
+    }
+  }
+
+  /**
+   * Resume a suspended blind-pairing layer. Idempotent.
+   *
+   * @returns {Promise<void>}
+   */
+  async resume() {
+    if (!this._blind || this.closing || this.closed) return
+    if (!this._blind.suspended) return
+    try {
+      await this._blind.resume()
+    } catch (err) {
+      safetyCatch(err)
+    }
+  }
+
+  async _onCandidate(req) {
+    const id = b4a.toString(req.inviteId, 'hex')
+    const record = this._invites.get(id)
+    if (!record) return
+
+    try {
+      req.open(record.publicKey)
+    } catch (err) {
+      safetyCatch(err)
+      return
+    }
+
+    const userData = decodeUserData(req.userData, this.joinerEncoding)
+
+    const candidate = new Candidate({
+      pairing: this,
+      req,
+      invite: record.invite,
+      seed: record.seed,
+      userData,
+      onsettle: () => {
+        this._invites.delete(id)
+      }
+    })
+
+    this.emit('candidate', candidate)
+  }
+}
+
+/**
+ * Internal — single incoming candidate awaiting host accept/deny. Created by
+ * `Pairing` and emitted on the `'candidate'` event so the host can decide.
+ *
+ * @property {boolean} _settled                       Whether confirm/deny has already run.
+ */
+class Candidate {
+  /** @param {CandidateOpts} opts */
+  constructor({ pairing, req, invite, seed, userData, onsettle }) {
+    this.pairing = pairing
+    this._req = req
+    this._seed = seed
+    this._settled = false
+    this._onsettle = onsettle
+
+    this.invite = invite
+    this.userData = userData
+    this.publicKey = req.publicKey
+  }
+
+  /**
+   * Accept the candidate and reveal the resource key. Idempotent.
+   *
+   * @param {ConfirmOpts} opts
+   * @returns {Promise<void>}
+   */
+  async confirm({ key, encryptionKey = null, additional = null } = {}) {
+    if (!key || key.length !== 32) throw CeroError.INVALID('key must be a 32-byte buffer')
+    if (encryptionKey !== null && encryptionKey !== undefined && encryptionKey.length !== 32) {
+      throw CeroError.INVALID('encryptionKey must be a 32-byte buffer')
+    }
+    if (
+      additional !== null &&
+      additional !== undefined &&
+      !b4a.isBuffer(additional) &&
+      !(additional instanceof Uint8Array)
+    ) {
+      throw CeroError.INVALID('additional must be a buffer')
+    }
+    if (this._settled) return
+    this._settled = true
+    this._onsettle()
+
+    const data = c.encode(Response, {
+      status: STATUS_OK,
+      reason: '',
+      key,
+      encryptionKey: encryptionKey || null,
+      extra: additional || null
+    })
+    const signature = sign(data, keyPair(this._seed).secretKey)
+
+    this._req.confirm({
+      key: this.pairing.topic,
+      encryptionKey: undefined,
+      additional: { data, signature }
+    })
+  }
+
+  /**
+   * Reject the candidate with an optional reason. Idempotent.
+   *
+   * @param {string} [reason]
+   * @returns {Promise<void>}
+   */
+  async deny(reason = '') {
+    if (this._settled) return
+    this._settled = true
+    this._onsettle()
+
+    const data = c.encode(Response, {
+      status: STATUS_DENIED,
+      reason: String(reason || ''),
+      key: null,
+      encryptionKey: null,
+      extra: null
+    })
+    const signature = sign(data, keyPair(this._seed).secretKey)
+
+    this._req.confirm({
+      key: this.pairing.topic,
+      encryptionKey: undefined,
+      additional: { data, signature }
+    })
+  }
+}
+
+/**
+ * Internal — joiner-side handshake state machine. One-shot: created by
+ * `Pairing.join()`, settled exactly once via `_done` or `_fail`.
+ *
+ * @property {any} _candidate                         blind-pairing addCandidate handle (null until started).
+ * @property {ReturnType<typeof setTimeout> | null} _timer   Pending timeout, if any.
+ * @property {((result: JoinResult) => void) | null} _resolve   Promise resolver, set in `start`.
+ * @property {((err: Error) => void) | null} _reject           Promise rejecter, set in `start`.
+ * @property {boolean} _settled                       Whether the handshake has already settled.
+ */
+class JoinerCandidate {
+  /**
+   * @param {Pairing} pairing
+   * @param {Invite} invite
+   * @param {Uint8Array | null} encodedUserData
+   * @param {number} timeout
+   */
+  constructor(pairing, invite, encodedUserData, timeout) {
+    this.pairing = pairing
+    this.invite = invite
+    this.userData = encodedUserData
+    this.timeout = timeout
+    this._candidate = null
+    this._timer = null
+    this._resolve = null
+    this._reject = null
+    this._settled = false
+  }
+
+  /**
+   * Kick off the handshake; returns a promise that settles with the host response.
+   *
+   * @returns {Promise<JoinResult>}
+   */
+  start() {
+    this.pairing._candidates.add(this)
+
+    return new Promise((resolve, reject) => {
+      this._resolve = resolve
+      this._reject = reject
+
+      if (this.timeout > 0) {
+        this._timer = setTimeout(() => this._fail(CeroError.TIMEOUT()), this.timeout)
+      }
+
+      try {
+        this._candidate = this.pairing._blind.addCandidate({
+          invite: this.invite.blindInvite,
+          userData: this.userData,
+          onadd: (result) => this._done(result)
+        })
+        this._candidate.request.on('rejected', (err) => this._fail(fromBlindError(err)))
+      } catch (err) {
+        this._fail(err instanceof CeroError ? err : CeroError.NETWORK_ERROR(err.message))
+      }
+    })
+  }
+
+  _done(result) {
+    if (this._settled) return
+
+    let envelope = null
+    const buf = result?.data ?? null
+    if (buf) {
+      try {
+        envelope = c.decode(Response, buf)
+      } catch {
+        envelope = null
+      }
+    }
+
+    if (envelope && envelope.status === STATUS_DENIED) {
+      this._fail(CeroError.DENIED(envelope.reason || null))
+      return
+    }
+
+    if (!envelope) {
+      this._fail(CeroError.NETWORK_ERROR('malformed pairing response'))
+      return
+    }
+
+    this._settled = true
+    this.pairing._candidates.delete(this)
+    clearTimeout(this._timer)
+
+    this._resolve({
+      key: envelope.key,
+      encryptionKey: envelope.encryptionKey,
+      additional: envelope.extra
+    })
+
+    this._candidate.close().catch(safetyCatch)
+  }
+
+  _fail(err) {
+    if (this._settled) return
+    this._settled = true
+    this.pairing._candidates.delete(this)
+    clearTimeout(this._timer)
+    if (this._candidate) this._candidate.close().catch(safetyCatch)
+    this._reject(err)
+  }
+}
+
+function encodeUserData(userData, encoding) {
+  if (userData === null || userData === undefined) return null
+  if (encoding) return c.encode(encoding, userData)
+  if (b4a.isBuffer(userData) || userData instanceof Uint8Array) return userData
+  throw CeroError.INVALID('userData must be a buffer when no joinerEncoding is provided')
+}
+
+function decodeUserData(buf, encoding) {
+  if (!buf || buf.length === 0) return null
+  if (!encoding) return buf
+  try {
+    return c.decode(encoding, buf)
+  } catch {
+    return buf
+  }
+}
+
+function fromBlindError(err) {
+  if (!err || !err.code) return CeroError.DENIED(err?.message || null)
+  switch (err.code) {
+    case 'INVITE_EXPIRED':
+      return CeroError.EXPIRED(err.message)
+    case 'INVITE_USED':
+      return CeroError.DENIED('used', err.message)
+    case 'PAIRING_REJECTED':
+      return CeroError.DENIED(null, err.message)
+    default:
+      return CeroError.DENIED(err.message)
+  }
+}

package/src/pairing/invite.js

@@ -0,0 +1,199 @@
+import BlindPairing from 'blind-pairing'
+import sodium from 'sodium-universal'
+import b4a from 'b4a'
+import z32 from 'z32'
+import c from 'compact-encoding'
+
+import { getEncoding } from '../lib/spec/index.js'
+import { CeroError } from '../lib/errors.js'
+
+const VERSION = 1
+const Envelope = getEncoding('@cero/invite')
+const SignBody = getEncoding('@cero/invite-body')
+
+/**
+ * @typedef {object} InviteFields
+ * @property {Uint8Array} publicKey                 Signer's long-lived public key.
+ * @property {string} role                          Optional role tag baked into the signed body.
+ * @property {number} expires                       Absolute expiry timestamp; `0` means never.
+ * @property {Uint8Array | null} data               Encoded payload (raw or via `encoding`).
+ * @property {Uint8Array} blindInvite               Raw blind-pairing invite handed to candidates.
+ * @property {Uint8Array} [sig]                     Ed25519 signature over the canonical body.
+ * @property {string | null} [_str]                 Cached z32 string form.
+ *
+ * @typedef {object} CreateInviteOpts
+ * @property {Uint8Array} secretKey                 64-byte Ed25519 secret key used to sign.
+ * @property {Uint8Array} publicKey                 32-byte Ed25519 public key matching `secretKey`.
+ * @property {string} role                          Optional role tag for the joiner.
+ * @property {number} expiresIn                     TTL in ms from now; `0` means never expires.
+ * @property {any} data                             Caller payload; encoded via `encoding` when provided.
+ * @property {Uint8Array} blindInvite               Raw blind-pairing invite to wrap.
+ * @property {any} [encoding]                       compact-encoding type used to encode `data`.
+ *
+ * @typedef {object} ParseInviteOpts
+ * @property {any} [encoding]                       compact-encoding type used to decode the embedded payload.
+ */
+
+/**
+ * Signed, expirable pairing invite. Wraps a blind-pairing invite with a
+ * role, optional payload and an Ed25519 signature so the host can be
+ * authenticated by the joiner before any handshake happens.
+ *
+ * @property {any} [_rawData]                         Decoded payload kept alongside the encoded `data` for convenience.
+ * @property {any} _blind                             Lazily-decoded blind-pairing invite view (cache).
+ */
+export class Invite {
+  /** @param {InviteFields} fields */
+  constructor(fields) {
+    this.version = VERSION
+    this.publicKey = fields.publicKey
+    this.role = fields.role
+    this.expires = fields.expires
+    this.data = fields.data
+    this.blindInvite = fields.blindInvite
+    this.sig = fields.sig
+    this._str = fields._str || null
+
+    // decoded blind-pairing invite info (cached)
+    this._blind = null
+  }
+
+  /**
+   * Whether the invite is past its TTL (always `false` when `expires === 0`).
+   *
+   * @returns {boolean}
+   */
+  get expired() {
+    return this.expires > 0 && Date.now() > this.expires
+  }
+
+  /**
+   * Lazily-decoded view of the underlying blind-pairing invite.
+   *
+   * @returns {any}
+   */
+  get blind() {
+    if (!this._blind) this._blind = BlindPairing.decodeInvite(this.blindInvite)
+    return this._blind
+  }
+
+  /**
+   * Verify the embedded signature against the encoded body.
+   *
+   * @returns {boolean}
+   */
+  verify() {
+    const body = c.encode(SignBody, this)
+    return sodium.crypto_sign_verify_detached(this.sig, body, this.publicKey)
+  }
+
+  /**
+   * Serialise to the canonical z32 wire form (cached).
+   *
+   * @returns {string}
+   */
+  toString() {
+    if (this._str) return this._str
+    const buf = c.encode(Envelope, this)
+    this._str = z32.encode(buf)
+    return this._str
+  }
+
+  /**
+   * Build and sign a new invite envelope wrapping a blind-pairing invite.
+   *
+   * @param {CreateInviteOpts} opts
+   * @returns {Invite}
+   */
+  static create({ secretKey, publicKey, role, expiresIn, data, blindInvite, encoding }) {
+    if (!secretKey || secretKey.length !== 64)
+      throw CeroError.INVALID('secretKey must be a 64-byte buffer')
+    if (!publicKey || publicKey.length !== 32)
+      throw CeroError.INVALID('publicKey must be a 32-byte buffer')
+    if (!b4a.isBuffer(blindInvite) && !(blindInvite instanceof Uint8Array)) {
+      throw CeroError.INVALID('blindInvite must be a buffer')
+    }
+
+    const expires = expiresIn ? Date.now() + expiresIn : 0
+    const encoded =
+      data === undefined || data === null ? null : encoding ? c.encode(encoding, data) : data
+
+    const fields = {
+      version: VERSION,
+      publicKey,
+      role: role || '',
+      expires,
+      data: encoded,
+      blindInvite
+    }
+
+    const body = c.encode(SignBody, fields)
+    const sig = b4a.alloc(64)
+    sodium.crypto_sign_detached(sig, body, secretKey)
+    fields.sig = sig
+
+    const inv = new Invite(fields)
+    inv._rawData = data // remember decoded form for convenience
+    return inv
+  }
+
+  /**
+   * Parse a z32 invite string, verify its signature and (optionally) decode
+   * its payload.
+   *
+   * @param {string} str
+   * @param {ParseInviteOpts} [opts]
+   * @returns {Invite}
+   */
+  static parse(str, { encoding } = {}) {
+    if (typeof str !== 'string') throw CeroError.INVALID_INVITE('invite must be a string')
+
+    let buf
+    try {
+      buf = z32.decode(str)
+    } catch {
+      throw CeroError.INVALID_INVITE('invite is not valid z32')
+    }
+
+    let fields
+    try {
+      fields = c.decode(Envelope, buf)
+    } catch {
+      throw CeroError.INVALID_INVITE('invite envelope failed to decode')
+    }
+
+    if (fields.version !== VERSION) throw CeroError.INVALID_INVITE('unknown invite version')
+
+    const inv = new Invite({ ...fields, _str: str })
+    if (!inv.verify()) throw CeroError.INVALID_INVITE('invite signature is invalid')
+
+    if (encoding && inv.data) {
+      try {
+        inv._rawData = c.decode(encoding, inv.data)
+      } catch {
+        throw CeroError.INVALID_INVITE('invite data failed to decode')
+      }
+    }
+
+    return inv
+  }
+
+  /**
+   * Cheap structural test — does `str` decode as an invite envelope? Does not
+   * verify the signature.
+   *
+   * @param {unknown} str
+   * @returns {boolean}
+   */
+  static isInvite(str) {
+    if (typeof str !== 'string') return false
+    try {
+      const buf = z32.decode(str)
+      const fields = c.decode(Envelope, buf)
+      if (fields.blindInvite) BlindPairing.decodeInvite(fields.blindInvite)
+      return true
+    } catch {
+      return false
+    }
+  }
+}