@cero-base/core 0.8.9 → 1.0.1

package/src/lib/utils.js

@@ -3,6 +3,8 @@ import { Readable } from 'streamx'
 import z32 from 'z32'
 import { encode, decode, isValid } from 'hypercore-id-encoding'
 
+import { ROLE_PERMS, RANK } from './constants.js'
+
 /**
  * Generate a short opaque id (z32-encoded 16 random bytes).
  *
@@ -33,6 +35,21 @@ export const toKey = decode
  */
 export const isKeyId = isValid
 
+/**
+ * Whether `role` is granted `perm` under the default policy.
+ *
+ * @param {string} role
+ * @param {string} perm
+ * @returns {boolean}
+ */
+export function can(role, perm) {
+  const perms = ROLE_PERMS[role]
+  return !!perms && (perms.includes('*') || perms.includes(perm))
+}
+
+export const grants = (a, b) => RANK[a] != null && RANK[b] != null && RANK[a] >= RANK[b]
+export const outranks = (a, b) => RANK[a] != null && RANK[b] != null && RANK[a] > RANK[b]
+
 /**
  * Stream-of-snapshots primitive. Couples a `get` (returns the latest value)
  * with a `watch` (re-fires on change) and emits the newest snapshot every
@@ -41,24 +58,38 @@ export const isKeyId = isValid
  * @template T
  * @param {object} args
  * @param {() => Promise<T> | T} args.get
- * @param {(fn: () => void) => (() => void) | void} args.watch  Returns an unsubscribe.
+ * @param {(fn: () => void) => (() => void) | void} args.watch
  * @returns {import('streamx').Readable<T>}
  */
 export function subscribe({ get, watch }) {
   let stop = null
+  let version = 0
+  let last
   const stream = new Readable({
     destroy(cb) {
       Promise.resolve(stop?.()).then(() => cb(null), cb)
     }
   })
+
+  const emit = (data) => {
+    const snap = JSON.stringify(data)
+    if (snap === last) return
+    last = snap
+    stream.push(data)
+  }
+
   const push = async () => {
     if (stream.destroyed) return
+    const v = ++version
     try {
-      stream.push(await get())
+      const data = await get()
+      if (v !== version || stream.destroyed) return
+      emit(data)
     } catch (e) {
       stream.destroy(e)
     }
   }
+
   stop = watch(push)
   push()
   return stream

package/src/network/index.js

@@ -227,5 +227,5 @@ function replicateInto(core, stream) {
 }
 
 function isTopic(x) {
-  return (b4a.isBuffer(x) || x instanceof Uint8Array) && x.length === 32
+  return b4a.isBuffer(x) && x.length === 32
 }

package/src/pairing/index.js

@@ -9,7 +9,7 @@ import { Invite } from './invite.js'
 import { getEncoding } from '../lib/spec/index.js'
 import { CeroError } from '../lib/errors.js'
 
-const STATUS_OK = 0
+const STATUS_ACCEPTED = 0
 const STATUS_DENIED = 1
 
 // Wire envelope carried in BlindPairing's `additional.data` on the confirm response.
@@ -25,11 +25,13 @@ const Response = getEncoding('@cero/confirm')
  * @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`.
+ * @property {(err: Error) => void} [onerror]                        Called when a background candidate fails to process.
  *
  * @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).
+ * @property {boolean} [multiUse]                                    Reusable until expiry/revoke; default `false` (consumed on first settle).
  *
  * @typedef {object} JoinOpts
  * @property {any} [userData]                                        Payload sent with the candidate request.
@@ -42,7 +44,7 @@ const Response = getEncoding('@cero/confirm')
  *
  * @typedef {{ key: Uint8Array, encryptionKey: Uint8Array | null, additional: Uint8Array | null }} JoinResult
  *
- * @typedef {object} CandidateOpts
+ * @typedef {object} RequestOpts
  * @property {Pairing} pairing                                       Owning Pairing instance.
  * @property {any} req                                               blind-pairing candidate request being answered.
  * @property {Invite} invite                                         Invite the candidate paired against.
@@ -59,7 +61,14 @@ const Response = getEncoding('@cero/confirm')
  */
 export class Pairing extends ReadyResource {
   /** @param {PairingOpts} [opts] */
-  constructor({ network, identity, topic, inviteEncoding = null, joinerEncoding = null } = {}) {
+  constructor({
+    network,
+    identity,
+    topic,
+    inviteEncoding = null,
+    joinerEncoding = null,
+    onerror = safetyCatch
+  } = {}) {
     super()
     if (!network) throw CeroError.REQUIRED('network')
     if (!identity) throw CeroError.REQUIRED('identity')
@@ -69,6 +78,7 @@ export class Pairing extends ReadyResource {
     this.topic = topic || identity.publicKey
     this.inviteEncoding = inviteEncoding
     this.joinerEncoding = joinerEncoding
+    this._onerror = onerror
 
     this._blind = null
     this._member = null
@@ -83,7 +93,7 @@ export class Pairing extends ReadyResource {
 
     this._member = this._blind.addMember({
       discoveryKey: discoveryKey(this.topic),
-      onadd: (req) => this._onCandidate(req).catch(safetyCatch)
+      onadd: (req) => this._onCandidate(req).catch(this._onerror)
     })
   }
 
@@ -112,7 +122,7 @@ export class Pairing extends ReadyResource {
    */
   static inviteTopic(invite) {
     try {
-      return Invite.parse(invite).blind.discoveryKey
+      return Invite.parse(invite).discoveryKey
     } catch {
       return null
     }
@@ -124,7 +134,7 @@ export class Pairing extends ReadyResource {
    * @param {CreateInviteOpts} [opts]
    * @returns {Promise<string>}
    */
-  async createInvite({ role = '', expiresIn = 0, data = null } = {}) {
+  async createInvite({ role = '', expiresIn = 0, data = null, multiUse = false } = {}) {
     if (this.closing || this.closed) throw CeroError.CLOSED('Pairing')
     if (!this.opened) await this.ready()
 
@@ -138,7 +148,7 @@ export class Pairing extends ReadyResource {
       role,
       expiresIn,
       data,
-      blindInvite: blind.invite,
+      blind: blind.invite,
       encoding: this.inviteEncoding
     })
 
@@ -147,7 +157,8 @@ export class Pairing extends ReadyResource {
       id: blind.id,
       seed: blind.seed,
       publicKey: blind.publicKey,
-      invite
+      invite,
+      multiUse
     })
 
     return invite.toString()
@@ -202,8 +213,8 @@ export class Pairing extends ReadyResource {
 
     if (invite.expired) throw CeroError.EXPIRED()
 
-    const encodedUserData = encodeUserData(userData, this.joinerEncoding)
-    const candidate = new JoinerCandidate(this, invite, encodedUserData, timeout)
+    const data = encodeUserData(userData, this.joinerEncoding)
+    const candidate = new Candidate(this, invite, data, timeout)
     return candidate.start()
   }
 
@@ -250,6 +261,10 @@ export class Pairing extends ReadyResource {
     const id = b4a.toString(req.inviteId, 'hex')
     const record = this._invites.get(id)
     if (!record) return
+    if (record.invite.expired) {
+      this._invites.delete(id)
+      return
+    }
 
     try {
       req.open(record.publicKey)
@@ -260,29 +275,31 @@ export class Pairing extends ReadyResource {
 
     const userData = decodeUserData(req.userData, this.joinerEncoding)
 
-    const candidate = new Candidate({
+    const request = new Request({
       pairing: this,
       req,
       invite: record.invite,
       seed: record.seed,
       userData,
       onsettle: () => {
-        this._invites.delete(id)
+        if (!record.multiUse) this._invites.delete(id)
       }
     })
 
-    this.emit('candidate', candidate)
+    this.emit('candidate', request)
   }
 }
 
 /**
- * Internal — single incoming candidate awaiting host accept/deny. Created by
- * `Pairing` and emitted on the `'candidate'` event so the host can decide.
+ * Internal — a pairing request from an incoming candidate, awaiting the host's
+ * accept/deny. Built in `_onCandidate` and emitted on the `'candidate'` event so
+ * the host can decide via `confirm` / `deny`. (The candidate is the joiner; this
+ * is the host's handle to answer it.)
  *
  * @property {boolean} _settled                       Whether confirm/deny has already run.
  */
-class Candidate {
-  /** @param {CandidateOpts} opts */
+class Request {
+  /** @param {RequestOpts} opts */
   constructor({ pairing, req, invite, seed, userData, onsettle }) {
     this.pairing = pairing
     this._req = req
@@ -302,36 +319,15 @@ class Candidate {
    * @returns {Promise<void>}
    */
   async confirm({ key, encryptionKey = null, additional = null } = {}) {
+    if (this._settled) return
     if (!key || key.length !== 32) throw CeroError.INVALID('key must be a 32-byte buffer')
-    if (encryptionKey !== null && encryptionKey !== undefined && encryptionKey.length !== 32) {
+    if (encryptionKey && encryptionKey.length !== 32) {
       throw CeroError.INVALID('encryptionKey must be a 32-byte buffer')
     }
-    if (
-      additional !== null &&
-      additional !== undefined &&
-      !b4a.isBuffer(additional) &&
-      !(additional instanceof Uint8Array)
-    ) {
+    if (additional && !b4a.isBuffer(additional)) {
       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 }
-    })
+    this._respond({ status: STATUS_ACCEPTED, reason: '', key, encryptionKey, extra: additional })
   }
 
   /**
@@ -342,18 +338,22 @@ class Candidate {
    */
   async deny(reason = '') {
     if (this._settled) return
-    this._settled = true
-    this._onsettle()
-
-    const data = c.encode(Response, {
+    this._respond({
       status: STATUS_DENIED,
-      reason: String(reason || ''),
+      reason,
       key: null,
       encryptionKey: null,
       extra: null
     })
-    const signature = sign(data, keyPair(this._seed).secretKey)
+  }
 
+  // sign the envelope with the per-invite seed and answer the candidate
+  // (callers guard idempotency before this runs)
+  _respond(envelope) {
+    this._settled = true
+    this._onsettle()
+    const data = c.encode(Response, envelope)
+    const signature = sign(data, keyPair(this._seed).secretKey)
     this._req.confirm({
       key: this.pairing.topic,
       encryptionKey: undefined,
@@ -363,8 +363,9 @@ class Candidate {
 }
 
 /**
- * Internal — joiner-side handshake state machine. One-shot: created by
- * `Pairing.join()`, settled exactly once via `_done` or `_fail`.
+ * Internal — the joiner side: a candidate's handshake state machine (this *is* the
+ * blind-pairing `addCandidate`). 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.
@@ -372,7 +373,7 @@ class Candidate {
  * @property {((err: Error) => void) | null} _reject           Promise rejecter, set in `start`.
  * @property {boolean} _settled                       Whether the handshake has already settled.
  */
-class JoinerCandidate {
+class Candidate {
   /**
    * @param {Pairing} pairing
    * @param {Invite} invite
@@ -409,7 +410,7 @@ class JoinerCandidate {
 
       try {
         this._candidate = this.pairing._blind.addCandidate({
-          invite: this.invite.blindInvite,
+          invite: this.invite.blind,
           userData: this.userData,
           onadd: (result) => this._done(result)
         })
@@ -466,10 +467,10 @@ class JoinerCandidate {
   }
 }
 
-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
+function encodeUserData(data, encoding) {
+  if (data == null) return null
+  if (encoding) return c.encode(encoding, data)
+  if (b4a.isBuffer(data)) return data
   throw CeroError.INVALID('userData must be a buffer when no joinerEncoding is provided')
 }
 

package/src/pairing/invite.js

@@ -17,7 +17,7 @@ const SignBody = getEncoding('@cero/invite-body')
  * @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} blind                     Raw blind-pairing invite handed to candidates.
  * @property {Uint8Array} [sig]                     Ed25519 signature over the canonical body.
  * @property {string | null} [_str]                 Cached z32 string form.
  *
@@ -27,7 +27,7 @@ const SignBody = getEncoding('@cero/invite-body')
  * @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 {Uint8Array} blind                     Raw blind-pairing invite to wrap.
  * @property {any} [encoding]                       compact-encoding type used to encode `data`.
  *
  * @typedef {object} ParseInviteOpts
@@ -40,7 +40,7 @@ const SignBody = getEncoding('@cero/invite-body')
  * 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).
+ * @property {Uint8Array} _discoveryKey               Cached discovery key of the wrapped blind invite.
  */
 export class Invite {
   /** @param {InviteFields} fields */
@@ -50,12 +50,12 @@ export class Invite {
     this.role = fields.role
     this.expires = fields.expires
     this.data = fields.data
-    this.blindInvite = fields.blindInvite
+    this.blind = fields.blind
     this.sig = fields.sig
     this._str = fields._str || null
 
-    // decoded blind-pairing invite info (cached)
-    this._blind = null
+    // cached discovery key of the wrapped blind invite
+    this._discoveryKey = null
   }
 
   /**
@@ -68,13 +68,15 @@ export class Invite {
   }
 
   /**
-   * Lazily-decoded view of the underlying blind-pairing invite.
+   * Discovery key of the wrapped blind-pairing invite — the topic it targets.
    *
-   * @returns {any}
+   * @returns {Uint8Array}
    */
-  get blind() {
-    if (!this._blind) this._blind = BlindPairing.decodeInvite(this.blindInvite)
-    return this._blind
+  get discoveryKey() {
+    if (!this._discoveryKey) {
+      this._discoveryKey = BlindPairing.decodeInvite(this.blind).discoveryKey
+    }
+    return this._discoveryKey
   }
 
   /**
@@ -105,18 +107,17 @@ export class Invite {
    * @param {CreateInviteOpts} opts
    * @returns {Invite}
    */
-  static create({ secretKey, publicKey, role, expiresIn, data, blindInvite, encoding }) {
+  static create({ secretKey, publicKey, role, expiresIn, data, blind, 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')
+    if (!b4a.isBuffer(blind)) {
+      throw CeroError.INVALID('blind invite 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 encoded = data == null ? null : encoding ? c.encode(encoding, data) : data
 
     const fields = {
       version: VERSION,
@@ -124,7 +125,7 @@ export class Invite {
       role: role || '',
       expires,
       data: encoded,
-      blindInvite
+      blind
     }
 
     const body = c.encode(SignBody, fields)
@@ -190,7 +191,7 @@ export class Invite {
     try {
       const buf = z32.decode(str)
       const fields = c.decode(Envelope, buf)
-      if (fields.blindInvite) BlindPairing.decodeInvite(fields.blindInvite)
+      if (fields.blind) BlindPairing.decodeInvite(fields.blind)
       return true
     } catch {
       return false

package/src/rpc/client.js

@@ -1,45 +1,7 @@
-import ReadyResource from 'ready-resource'
-import safetyCatch from 'safety-catch'
-import FramedStream from 'framed-stream'
-
-import { bindCodec } from './index.js'
+import { RPCPeer } from './peer.js'
 
 /**
- * Client-side RPC adapter. Mirror of `RPCServer` — wraps an IPC duplex
- * in a length-framed stream and constructs the spec's hrpc binding ready
- * to issue requests. Frames are paused until `_open` runs so handlers
- * registered before `ready()` see a clean slate.
+ * Client-side RPC adapter — issues requests over the framed IPC stream.
+ * All wiring lives in {@link RPCPeer}; this is the client-named role.
  */
-export class RPCClient extends ReadyResource {
-  /**
-   * @param {any} ipc                                Duplex IPC stream (e.g. a socket or pipe).
-   * @param {import('./index.js').Spec} spec         Spec object exposing `rpc` and `schema`.
-   */
-  constructor(ipc, spec) {
-    super()
-    if (!ipc) throw new TypeError('ipc is required')
-    if (!spec) throw new TypeError('spec is required')
-    if (!spec.rpc) throw new TypeError('spec.rpc is required')
-
-    this.ipc = ipc
-    this.spec = spec
-    this.framed = new FramedStream(ipc)
-    this.framed.pause()
-    this.rpc = new spec.rpc(this.framed)
-  }
-
-  async _open() {
-    if (!this.spec.codec) bindCodec(this.spec)
-    this.framed.resume()
-  }
-
-  async _close() {
-    if (this.framed && !this.framed.destroyed) {
-      try {
-        this.framed.destroy()
-      } catch (err) {
-        safetyCatch(err)
-      }
-    }
-  }
-}
+export class RPCClient extends RPCPeer {}

package/src/rpc/index.js

@@ -2,6 +2,7 @@ import b4a from 'b4a'
 import c from 'compact-encoding'
 
 import { getEncoding } from '../lib/spec/index.js'
+import { CeroError } from '../lib/errors.js'
 
 export { RPCServer } from './server.js'
 export { RPCClient } from './client.js'
@@ -44,9 +45,9 @@ const DEFAULT_CREATE = getEncoding('@cero/create')
  * @returns {Spec}
  */
 export function bindCodec(spec) {
-  if (!spec) throw new TypeError('spec is required')
+  if (!spec) throw CeroError.REQUIRED('spec')
   const schema = spec.schema
-  if (!schema) throw new TypeError('spec.schema is required')
+  if (!schema) throw CeroError.REQUIRED('spec.schema')
 
   const ns = spec.meta?.ns
   const ROWS = ns ? `@${ns}/rows` : null
@@ -83,8 +84,11 @@ export function bindCodec(spec) {
       if (!buf || buf.length === 0) return undefined
       const env = decodeEnvelope(schema, QUERY, DEFAULT_QUERY, buf)
       const out = {}
-      // Hyperschema fills optional uint/bool with 0/false defaults; only
-      // include fields the encoder actually wrote (truthy).
+      // Hyperschema fills optional uint/bool with 0/false defaults, so we can only
+      // recover fields the encoder actually wrote (truthy). KNOWN LIMITATION: a
+      // `limit: 0` query (degenerate — "return nothing") is indistinguishable from
+      // "no limit" over the wire and is treated as unset. Falsy cursors (gt: '')
+      // are harmless — an empty-string bound matches everything anyway.
       if (env.gt) out.gt = env.gt
       if (env.gte) out.gte = env.gte
       if (env.lt) out.lt = env.lt

package/src/rpc/peer.js

@@ -0,0 +1,46 @@
+import ReadyResource from 'ready-resource'
+import safetyCatch from 'safety-catch'
+import FramedStream from 'framed-stream'
+
+import { bindCodec } from './index.js'
+import { CeroError } from '../lib/errors.js'
+
+/**
+ * Shared RPC peer: wraps an IPC duplex in a length-framed stream and constructs
+ * the spec's hrpc binding. Frames are paused until `_open` runs so handlers
+ * registered before `ready()` see a clean slate. `RPCClient` and `RPCServer`
+ * are thin named subclasses — identical wiring, distinct roles.
+ */
+export class RPCPeer extends ReadyResource {
+  /**
+   * @param {any} ipc                                Duplex IPC stream (e.g. a socket or pipe).
+   * @param {import('./index.js').Spec} spec         Spec object exposing `rpc` and `schema`.
+   */
+  constructor(ipc, spec) {
+    super()
+    if (!ipc) throw CeroError.REQUIRED('ipc')
+    if (!spec) throw CeroError.REQUIRED('spec')
+    if (!spec.rpc) throw CeroError.REQUIRED('spec.rpc')
+
+    this.ipc = ipc
+    this.spec = spec
+    this.framed = new FramedStream(ipc)
+    this.framed.pause()
+    this.rpc = new spec.rpc(this.framed)
+  }
+
+  async _open() {
+    if (!this.spec.codec) bindCodec(this.spec)
+    this.framed.resume()
+  }
+
+  async _close() {
+    if (this.framed && !this.framed.destroyed) {
+      try {
+        this.framed.destroy()
+      } catch (err) {
+        safetyCatch(err)
+      }
+    }
+  }
+}

package/src/rpc/server.js

@@ -1,45 +1,7 @@
-import ReadyResource from 'ready-resource'
-import safetyCatch from 'safety-catch'
-import FramedStream from 'framed-stream'
-
-import { bindCodec } from './index.js'
+import { RPCPeer } from './peer.js'
 
 /**
- * Server-side RPC adapter. Wraps an IPC duplex in a length-framed stream
- * and instantiates the spec's hrpc binding once `bindCodec` has populated
- * envelope encoders. Reads are paused until `_open` runs so the
- * application has a chance to register handlers before frames flow.
+ * Server-side RPC adapter — serves the spec's handlers over the framed IPC
+ * stream. All wiring lives in {@link RPCPeer}; this is the server-named role.
  */
-export class RPCServer extends ReadyResource {
-  /**
-   * @param {any} ipc                                Duplex IPC stream (e.g. a socket or pipe).
-   * @param {import('./index.js').Spec} spec         Spec object exposing `rpc` and `schema`.
-   */
-  constructor(ipc, spec) {
-    super()
-    if (!ipc) throw new TypeError('ipc is required')
-    if (!spec) throw new TypeError('spec is required')
-    if (!spec.rpc) throw new TypeError('spec.rpc is required')
-
-    this.ipc = ipc
-    this.spec = spec
-    this.framed = new FramedStream(ipc)
-    this.framed.pause()
-    this.rpc = new spec.rpc(this.framed)
-  }
-
-  async _open() {
-    if (!this.spec.codec) bindCodec(this.spec)
-    this.framed.resume()
-  }
-
-  async _close() {
-    if (this.framed && !this.framed.destroyed) {
-      try {
-        this.framed.destroy()
-      } catch (err) {
-        safetyCatch(err)
-      }
-    }
-  }
-}
+export class RPCServer extends RPCPeer {}