@cero-base/tools 0.8.10 → 1.0.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/bin/cero-tools.js

@@ -13,6 +13,11 @@ const [hostPart, portPart] = arg.includes(':') ? arg.split(':') : [undefined, ar
 const host = hostPart
 const port = Number(portPart)
 
+if (!Number.isInteger(port) || port < 1 || port > 65535) {
+  console.error(`invalid port '${portPart}' — expected an integer 1–65535`)
+  process.exit(1)
+}
+
 const socket = dial({ host, port })
 socket.on('error', (err) => {
   console.error(

package/package.json

@@ -1,8 +1,17 @@
 {
   "name": "@cero-base/tools",
-  "version": "0.8.10",
+  "version": "1.0.1",
   "description": "Passive devtools for cero — observe data, events, and p2p/replication stats over a local out-of-band pipe.",
   "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lekinox/cero-base.git",
+    "directory": "packages/tools"
+  },
   "main": "./src/index.js",
   "types": "./types/index.d.ts",
   "bin": {
@@ -44,17 +53,17 @@
     "test": "ls test/*.test.js | xargs -P1 -n1 brittle-node"
   },
   "dependencies": {
-    "@cero-base/cero": "^0.8.10",
-    "@cero-base/core": "^0.8.10",
+    "@cero-base/cero": "^1.0.1",
+    "@cero-base/core": "^1.0.1",
     "b4a": "^1.8.1",
-    "bare-net": "^2.3.1",
-    "compact-encoding": "^3.1.0",
-    "streamx": "^2.22.0"
+    "bare-net": "^2.3.2",
+    "compact-encoding": "^3.2.0",
+    "streamx": "^2.28.0"
   },
   "devDependencies": {
     "@hyperswarm/testnet": "^3.1.4",
-    "brittle": "^4.0.0",
-    "typescript": "^5.7.0"
+    "brittle": "^4.0.2",
+    "typescript": "^5.9.3"
   },
   "license": "Apache-2.0"
 }

package/src/connect.js

@@ -2,14 +2,22 @@ import { Readable } from 'streamx'
 
 import { Framed } from './protocol.js'
 
+/**
+ * @typedef {object} Query  Opaque query filter passed to the server.
+ */
+
+/**
+ * @typedef {Record<string, unknown>} Handle  A handle descriptor returned by the server.
+ */
+
 /**
  * Consumer SDK for a tap server reached over a local Duplex `stream`. Returns
  * a session exposing read methods (`handles`/`get`/`count`) and stream methods
  * (`watch`/`events`/`stats`). Stream methods return a streamx Readable that
  * cancels its server-side source when destroyed.
  *
- * @param {any} stream  A streamx Duplex connected to a tap server.
- * @returns {Promise<{ handles(): Promise<any>, get(ref: string, query?: any, handleId?: string): Promise<any>, count(ref: string, query?: any, handleId?: string): Promise<any>, watch(ref: string, query?: any, handleId?: string): import('streamx').Readable, events(): import('streamx').Readable, stats(): import('streamx').Readable, close(): void }>}
+ * @param {object} stream  A streamx Duplex connected to a tap server.
+ * @returns {Promise<{ handles(): Promise<Handle[]>, get(ref: string, query?: Query, handleId?: string): Promise<unknown>, count(ref: string, query?: Query, handleId?: string): Promise<number>, watch(ref: string, query?: Query, handleId?: string): import('streamx').Readable, events(): import('streamx').Readable, stats(): import('streamx').Readable, close(): void }>}
  */
 export async function connect(stream) {
   return new Session(stream)
@@ -22,6 +30,18 @@ export class Session {
     this.streams = new Map()
     this.seq = 0
     this.wire = new Framed(stream, (msg) => this._onMessage(msg))
+    stream.on('error', () => {}) // a transport error shouldn't crash the consumer
+    stream.on('close', () => this._onClose())
+  }
+
+  // The transport dropped — fail in-flight requests and end live streams instead
+  // of leaving them hung and the maps leaking.
+  _onClose() {
+    for (const { reject } of this.pending.values())
+      reject(new TapError('connection closed', 'CLOSED'))
+    this.pending.clear()
+    for (const r of this.streams.values()) r.push(null)
+    this.streams.clear()
   }
 
   _onMessage(msg) {
@@ -69,30 +89,74 @@ export class Session {
     return r
   }
 
+  /**
+   * Lists the handles exposed by the server.
+   *
+   * @returns {Promise<Handle[]>} Resolves to the handle descriptors.
+   */
   handles() {
     return this._request('handles', {})
   }
 
+  /**
+   * Reads the current value for `ref`.
+   *
+   * @param {string} ref  Reference to read.
+   * @param {Query} [query]  Optional query filter.
+   * @param {string} [handleId]  Optional handle to scope the read.
+   * @returns {Promise<unknown>} Resolves to the value.
+   */
   get(ref, query, handleId) {
     return this._request('get', { ref, query, handleId })
   }
 
+  /**
+   * Counts entries matching `ref`.
+   *
+   * @param {string} ref  Reference to count.
+   * @param {Query} [query]  Optional query filter.
+   * @param {string} [handleId]  Optional handle to scope the count.
+   * @returns {Promise<number>} Resolves to the count.
+   */
   count(ref, query, handleId) {
     return this._request('count', { ref, query, handleId })
   }
 
+  /**
+   * Watches `ref` for changes, emitting frames as they arrive.
+   *
+   * @param {string} ref  Reference to watch.
+   * @param {Query} [query]  Optional query filter.
+   * @param {string} [handleId]  Optional handle to scope the watch.
+   * @returns {import('streamx').Readable} Cancels its server-side source when destroyed.
+   */
   watch(ref, query, handleId) {
     return this._stream('watch', { ref, query, handleId })
   }
 
+  /**
+   * Streams server events.
+   *
+   * @returns {import('streamx').Readable} Cancels its server-side source when destroyed.
+   */
   events() {
     return this._stream('events', {})
   }
 
+  /**
+   * Streams server stats.
+   *
+   * @returns {import('streamx').Readable} Cancels its server-side source when destroyed.
+   */
   stats() {
     return this._stream('stats', {})
   }
 
+  /**
+   * Closes the session by ending the underlying stream.
+   *
+   * @returns {void}
+   */
   close() {
     this.stream.end()
   }

package/src/format.js

@@ -23,7 +23,7 @@ function shortRow(row) {
 
 function shortKey(key) {
   if (key == null) return ''
-  if (b4a.isBuffer(key) || key instanceof Uint8Array) return b4a.toString(key, 'hex').slice(0, 8)
+  if (b4a.isBuffer(key)) return b4a.toString(key, 'hex').slice(0, 8)
   return String(key).slice(0, 8)
 }
 

package/src/protocol.js

@@ -1,9 +1,12 @@
 import b4a from 'b4a'
 
 const BYTES = '$b'
+// Cap a single frame and the outbound backlog so a bogus length prefix or a
+// stuck consumer can't grow host memory without bound (devtools is never essential).
+const MAX_FRAME = 16 * 1024 * 1024
 
 function toWire(v) {
-  if (b4a.isBuffer(v) || v instanceof Uint8Array) return { [BYTES]: b4a.toString(v, 'hex') }
+  if (b4a.isBuffer(v)) return { [BYTES]: b4a.toString(v, 'hex') }
   if (Array.isArray(v)) return v.map(toWire)
   if (v && typeof v === 'object') {
     const o = {}
@@ -40,6 +43,10 @@ export class Framed {
     this.buf = b4a.concat([this.buf, chunk])
     while (this.buf.length >= 4) {
       const len = new DataView(this.buf.buffer, this.buf.byteOffset, 4).getUint32(0, true)
+      if (len > MAX_FRAME) {
+        this.stream.destroy() // oversized/garbage prefix — drop the connection
+        return
+      }
       if (this.buf.length < 4 + len) break
       const body = b4a.toString(this.buf.subarray(4, 4 + len))
       this.buf = this.buf.subarray(4 + len)
@@ -53,7 +60,17 @@ export class Framed {
     }
   }
 
+  /**
+   * Encode `obj` to wire form and write it as one length-prefixed frame.
+   * @param {object} obj - message to send
+   * @returns {void}
+   */
   send(obj) {
+    // drop a consumer that has stopped reading rather than buffer unbounded
+    if ((this.stream.writableLength ?? 0) > MAX_FRAME) {
+      this.stream.destroy()
+      return
+    }
     const body = b4a.from(JSON.stringify(toWire(obj)))
     const head = b4a.alloc(4)
     new DataView(head.buffer, head.byteOffset, 4).setUint32(0, body.length, true)

package/src/redact.js

@@ -1,7 +1,8 @@
 import b4a from 'b4a'
 
 // Obvious secret-ish field names, masked by default once redaction is enabled.
-const DEFAULT_DENY = /^(seed|secret|secretkey|password|passphrase|token|private|privatekey)$/i
+const DEFAULT_DENY =
+  /^(seed|secret|secretkey|password|passphrase|token|private|privatekey|encryptionkey|mnemonic)$/i
 
 /**
  * Build a row masker for devtools. A field is masked when its dotted path is in
@@ -18,7 +19,7 @@ export function redact(config = {}) {
   const deny = config.deny === false ? null : config.deny || DEFAULT_DENY
   const match = typeof config.match === 'function' ? config.match : null
 
-  const isBytes = (v) => b4a.isBuffer(v) || v instanceof Uint8Array
+  const isBytes = (v) => b4a.isBuffer(v)
   const mask = (v) =>
     isBytes(v) ? `‹redacted:bytes(${v.length})›` : `‹redacted:${v === null ? 'null' : typeof v}›`
 

package/src/server.js

@@ -2,15 +2,21 @@ import { get, count, watch } from '@cero-base/cero'
 
 import { Framed } from './protocol.js'
 
+/**
+ * A decoded request frame. Carries the correlation `id` and `method`, plus the
+ * per-method fields a handler reads: `ref`, `handleId`, `query`, `cancelId`.
+ * @typedef {{ id?: string, method?: string, ref?: string, handleId?: string, query?: object, cancelId?: string }} ReqFrame
+ */
+
 /**
  * Read-only inspection server over a local Duplex `stream`. Serves the live
  * handle tree rooted at `me`, exposing only MAIN refs declared in each
  * handle's `spec.meta.refs` — local secret refs (master/keypair/
  * handle-keypairs) are never reachable, since they live in `meta.local.refs`.
  *
- * @param {any} stream  A streamx Duplex carrying length-prefixed JSON frames.
- * @param {any} me  The live root cero handle.
- * @param {{ events?: { snapshot(): any, subscribe(fn: (e: any) => void): () => void }, stats?: { snapshot(): any, subscribe(fn: (s: any) => void): () => void }, redact?: (ref: string, row: any) => any }} [opts]
+ * @param {object} stream  A streamx Duplex carrying length-prefixed JSON frames.
+ * @param {object} me  The live root cero handle.
+ * @param {{ events?: { snapshot(): unknown, subscribe(fn: (e: object) => void): () => void }, stats?: { snapshot(): unknown, subscribe(fn: (s: object) => void): () => void }, redact?: (ref: string, row: Record<string, unknown>) => Record<string, unknown> }} [opts]
  * @returns {{ close(): void }}
  */
 export function serve(stream, me, opts) {
@@ -27,9 +33,18 @@ export class TapServer {
     this.wire = new Framed(stream, (req) => this.onRequest(req))
     this._cleanup = () => this._teardown()
     stream.on('close', this._cleanup)
+    // an inbound socket reset (client kill / ECONNRESET) must tear down, not crash the host
+    stream.on('error', this._cleanup)
   }
 
+  /**
+   * Dispatch an inbound request frame to its named method handler.
+   * @param {ReqFrame} req  A decoded request frame, expected to carry `id` and `method`.
+   * @returns {Promise<void>}
+   */
   async onRequest(req) {
+    // a malformed frame (JSON null / scalar) has no method — ignore it
+    if (!req || typeof req !== 'object') return
     const handler = this[req.method]
     if (!handler || !METHODS.has(req.method)) {
       this._send({
@@ -47,6 +62,11 @@ export class TapServer {
     }
   }
 
+  /**
+   * Reply with the root handle and its direct children as `{ id, type }` rows.
+   * @param {ReqFrame} req  A request frame carrying `id`.
+   * @returns {void}
+   */
   handles(req) {
     const me = this.me
     const data = [
@@ -56,6 +76,11 @@ export class TapServer {
     this._send({ id: req.id, ok: true, data })
   }
 
+  /**
+   * Read a ref once and reply with the redacted result.
+   * @param {ReqFrame} req  A request frame carrying `id`, `ref`, `handleId` and `query`.
+   * @returns {Promise<void>}
+   */
   async get(req) {
     const ref = this._resolveRef(req)
     const r = await get(ref, req.query)
@@ -65,11 +90,21 @@ export class TapServer {
     this._send({ id: req.id, ok: true, data: { ...r, data } })
   }
 
+  /**
+   * Count rows for a ref and reply with the total.
+   * @param {ReqFrame} req  A request frame carrying `id`, `ref`, `handleId` and `query`.
+   * @returns {Promise<void>}
+   */
   async count(req) {
     const ref = this._resolveRef(req)
     this._send({ id: req.id, ok: true, data: (await count(ref, req.query)).data })
   }
 
+  /**
+   * Stream redacted live updates for a ref until cancelled or the stream ends.
+   * @param {ReqFrame} req  A request frame carrying `id`, `ref`, `handleId` and `query`.
+   * @returns {void}
+   */
   watch(req) {
     const ref = this._resolveRef(req)
     const s = watch(ref, req.query)
@@ -79,16 +114,36 @@ export class TapServer {
       this._send({ id: req.id, frame: { ...d, data } })
     })
     s.on('end', () => this._send({ id: req.id, end: true }))
+    // a watch-stream error must not crash the host — end the client stream cleanly
+    s.on('error', () => {
+      this._drop(req.id)
+      this._send({ id: req.id, end: true })
+    })
   }
 
+  /**
+   * Stream the events source snapshot then live events.
+   * @param {ReqFrame} req  A request frame carrying `id`.
+   * @returns {void}
+   */
   events(req) {
     this._source(req, this.opts.events)
   }
 
+  /**
+   * Stream the stats source snapshot then live stats.
+   * @param {ReqFrame} req  A request frame carrying `id`.
+   * @returns {void}
+   */
   stats(req) {
     this._source(req, this.opts.stats)
   }
 
+  /**
+   * Stop a tracked stream by id and release its resources.
+   * @param {ReqFrame} req  A request frame carrying `cancelId`.
+   * @returns {void}
+   */
   cancel(req) {
     this._drop(req.cancelId)
   }
@@ -137,6 +192,10 @@ export class TapServer {
     this.tracked.clear()
   }
 
+  /**
+   * Tear down all tracked streams and destroy the underlying stream.
+   * @returns {void}
+   */
   close() {
     this._teardown()
     this.stream.destroy()

package/src/tap.js

@@ -3,6 +3,21 @@ import { serve } from './server.js'
 import { redact } from './redact.js'
 import { loopback } from './transport.js'
 
+/**
+ * An applied-op event fed into the ring buffer. `op` is the dispatch verb
+ * prefix, `name` the ref name, `row` the decoded value, `writerKey` the source
+ * writer's key and `seq` a monotonic apply counter. After redaction `row` is
+ * replaced with its masked copy; the rest is spread through unchanged.
+ *
+ * @typedef {{ op: string, name: string, row: Record<string, unknown>, writerKey: Buffer, seq: number }} OpEvent
+ */
+
+/**
+ * A periodic `stats(me)` sample. See `stats()` for the field meanings.
+ *
+ * @typedef {{ handleId: string, network: { connections: number, peers: number, dht: object | null }, bee: { local: number }, cores: Array<{ length: number, byteLength: number, peers: number }>, at: number }} StatsSample
+ */
+
 /**
  * `cero.use(devtools())` tap extension. Bound to the root handle's lifecycle,
  * it feeds every applied op into a bounded ring buffer, samples `stats(me)` on
@@ -10,8 +25,8 @@ import { loopback } from './transport.js'
  * consumers. By default it serves a loopback TCP server on `port` (9111); pass
  * a custom `transport` to serve it some other way. Nothing touches the app swarm.
  *
- * @param {{ port?: number, host?: string, bufferSize?: number, sampleInterval?: number, redact?: ((ref: string, row: any) => any) | { fields?: string[], match?: Function, deny?: RegExp | false }, transport?: { accept(handler: (stream: any) => void): void } }} [opts]
- * @returns {{ setup(me: any): () => void }}
+ * @param {{ port?: number, host?: string, bufferSize?: number, sampleInterval?: number, redact?: ((ref: string, row: Record<string, unknown>) => Record<string, unknown>) | { fields?: string[], match?: (key: string, value: unknown, path: string) => boolean, deny?: RegExp | false }, transport?: { accept(handler: (stream: object) => void): void } }} [opts]
+ * @returns {{ setup(me: object): () => void }}
  */
 export function devtools(opts = {}) {
   return {
@@ -53,8 +68,9 @@ export function devtools(opts = {}) {
 }
 
 function makeRedactor(opt) {
-  if (!opt) return null
-  return typeof opt === 'function' ? opt : redact(opt)
+  if (opt === false) return null // explicit opt-out only; redaction is on by default
+  if (typeof opt === 'function') return opt
+  return redact(opt || undefined)
 }
 
 /** Bounded ring buffer with snapshot + live subscription. */
@@ -65,16 +81,30 @@ class Ring {
     this.subs = new Set()
   }
 
+  /**
+   * Append an event, evicting the oldest if over capacity, then notify subscribers.
+   * @param {OpEvent} e
+   * @returns {void}
+   */
   push(e) {
     this.items.push(e)
     if (this.items.length > this.max) this.items.shift()
     for (const fn of this.subs) fn(e)
   }
 
+  /**
+   * Copy of the buffered events.
+   * @returns {OpEvent[]}
+   */
   snapshot() {
     return this.items.slice()
   }
 
+  /**
+   * Subscribe to pushed events.
+   * @param {(e: OpEvent) => void} fn
+   * @returns {() => boolean} unsubscribe
+   */
   subscribe(fn) {
     this.subs.add(fn)
     return () => this.subs.delete(fn)
@@ -92,15 +122,28 @@ class Sampler {
     }, interval)
   }
 
+  /**
+   * Most recent stats sample.
+   * @returns {StatsSample}
+   */
   snapshot() {
     return this.latest
   }
 
+  /**
+   * Subscribe to each new stats sample.
+   * @param {(latest: StatsSample) => void} fn
+   * @returns {() => boolean} unsubscribe
+   */
   subscribe(fn) {
     this.subs.add(fn)
     return () => this.subs.delete(fn)
   }
 
+  /**
+   * Stop the sampling interval.
+   * @returns {void}
+   */
   stop() {
     clearInterval(this.timer)
   }

package/src/transport.js

@@ -12,26 +12,34 @@ export function loopback(opts = {}) {
   const host = opts.host ?? '127.0.0.1'
   const base = opts.port ?? 0
   let server = null
+  let ready = null
   return {
     accept(handler) {
-      server = net.createServer((socket) => handler(socket))
+      server = net.createServer((socket) => {
+        socket.on('error', () => {}) // an inbound reset must not crash the host
+        handler(socket)
+      })
       let port = base
       let tries = 0
-      // A taken port (e.g. a second app instance) bumps to the next one rather
-      // than crashing the app — devtools is never essential.
-      server.on('error', (err) => {
-        if (err.code === 'EADDRINUSE' && base && tries++ < 10) server.listen(++port, host)
-        else console.error(`[devtools] tap could not start: ${err.message}`)
+      // ready() resolves when listening, rejects on a terminal bind failure
+      // (so a caller awaiting it can't hang forever).
+      ready = new Promise((resolve, reject) => {
+        server.on('listening', () => resolve({ port: server.address().port }))
+        // A taken port (e.g. a second app instance) bumps to the next one rather
+        // than crashing the app — devtools is never essential.
+        server.on('error', (err) => {
+          if (err.code === 'EADDRINUSE' && base && tries++ < 10) return server.listen(++port, host)
+          console.error(`[devtools] tap could not start: ${err.message}`)
+          reject(err)
+        })
       })
+      ready.catch(() => {}) // ready() may never be called — don't go unhandled
       server.on('listening', () => console.log(banner(host, server.address().port)))
       server.listen(port, host)
     },
     ready() {
-      return new Promise((resolve, reject) => {
-        if (!server) return reject(new Error('accept() not called'))
-        if (server.listening) return resolve({ port: server.address().port })
-        server.once('listening', () => resolve({ port: server.address().port }))
-      })
+      if (!server) return Promise.reject(new Error('accept() not called'))
+      return ready
     },
     get port() {
       return server?.listening ? server.address().port : null

package/types/connect.d.ts

@@ -1,19 +1,25 @@
+/**
+ * @typedef {object} Query  Opaque query filter passed to the server.
+ */
+/**
+ * @typedef {Record<string, unknown>} Handle  A handle descriptor returned by the server.
+ */
 /**
  * Consumer SDK for a tap server reached over a local Duplex `stream`. Returns
  * a session exposing read methods (`handles`/`get`/`count`) and stream methods
  * (`watch`/`events`/`stats`). Stream methods return a streamx Readable that
  * cancels its server-side source when destroyed.
  *
- * @param {any} stream  A streamx Duplex connected to a tap server.
- * @returns {Promise<{ handles(): Promise<any>, get(ref: string, query?: any, handleId?: string): Promise<any>, count(ref: string, query?: any, handleId?: string): Promise<any>, watch(ref: string, query?: any, handleId?: string): import('streamx').Readable, events(): import('streamx').Readable, stats(): import('streamx').Readable, close(): void }>}
+ * @param {object} stream  A streamx Duplex connected to a tap server.
+ * @returns {Promise<{ handles(): Promise<Handle[]>, get(ref: string, query?: Query, handleId?: string): Promise<unknown>, count(ref: string, query?: Query, handleId?: string): Promise<number>, watch(ref: string, query?: Query, handleId?: string): import('streamx').Readable, events(): import('streamx').Readable, stats(): import('streamx').Readable, close(): void }>}
  */
-export function connect(stream: any): Promise<{
-    handles(): Promise<any>;
-    get(ref: string, query?: any, handleId?: string): Promise<any>;
-    count(ref: string, query?: any, handleId?: string): Promise<any>;
-    watch(ref: string, query?: any, handleId?: string): any;
-    events(): any;
-    stats(): any;
+export function connect(stream: object): Promise<{
+    handles(): Promise<Handle[]>;
+    get(ref: string, query?: Query, handleId?: string): Promise<unknown>;
+    count(ref: string, query?: Query, handleId?: string): Promise<number>;
+    watch(ref: string, query?: Query, handleId?: string): import("streamx").Readable;
+    events(): import("streamx").Readable;
+    stats(): import("streamx").Readable;
     close(): void;
 }>;
 export class Session {
@@ -23,16 +29,70 @@ export class Session {
     streams: Map<any, any>;
     seq: number;
     wire: Framed;
+    _onClose(): void;
     _onMessage(msg: any): void;
     _newId(): number;
     _request(method: any, fields: any): Promise<any>;
-    _stream(method: any, fields: any): any;
-    handles(): Promise<any>;
-    get(ref: any, query: any, handleId: any): Promise<any>;
-    count(ref: any, query: any, handleId: any): Promise<any>;
-    watch(ref: any, query: any, handleId: any): any;
-    events(): any;
-    stats(): any;
+    _stream(method: any, fields: any): Readable<import("streamx").ReadableEvents>;
+    /**
+     * Lists the handles exposed by the server.
+     *
+     * @returns {Promise<Handle[]>} Resolves to the handle descriptors.
+     */
+    handles(): Promise<Handle[]>;
+    /**
+     * Reads the current value for `ref`.
+     *
+     * @param {string} ref  Reference to read.
+     * @param {Query} [query]  Optional query filter.
+     * @param {string} [handleId]  Optional handle to scope the read.
+     * @returns {Promise<unknown>} Resolves to the value.
+     */
+    get(ref: string, query?: Query, handleId?: string): Promise<unknown>;
+    /**
+     * Counts entries matching `ref`.
+     *
+     * @param {string} ref  Reference to count.
+     * @param {Query} [query]  Optional query filter.
+     * @param {string} [handleId]  Optional handle to scope the count.
+     * @returns {Promise<number>} Resolves to the count.
+     */
+    count(ref: string, query?: Query, handleId?: string): Promise<number>;
+    /**
+     * Watches `ref` for changes, emitting frames as they arrive.
+     *
+     * @param {string} ref  Reference to watch.
+     * @param {Query} [query]  Optional query filter.
+     * @param {string} [handleId]  Optional handle to scope the watch.
+     * @returns {import('streamx').Readable} Cancels its server-side source when destroyed.
+     */
+    watch(ref: string, query?: Query, handleId?: string): import("streamx").Readable;
+    /**
+     * Streams server events.
+     *
+     * @returns {import('streamx').Readable} Cancels its server-side source when destroyed.
+     */
+    events(): import("streamx").Readable;
+    /**
+     * Streams server stats.
+     *
+     * @returns {import('streamx').Readable} Cancels its server-side source when destroyed.
+     */
+    stats(): import("streamx").Readable;
+    /**
+     * Closes the session by ending the underlying stream.
+     *
+     * @returns {void}
+     */
     close(): void;
 }
+/**
+ * Opaque query filter passed to the server.
+ */
+export type Query = object;
+/**
+ * A handle descriptor returned by the server.
+ */
+export type Handle = Record<string, unknown>;
 import { Framed } from './protocol.js';
+import { Readable } from 'streamx';

package/types/protocol.d.ts

@@ -8,5 +8,10 @@ export class Framed {
     onMessage: any;
     buf: any;
     _onData(chunk: any): void;
-    send(obj: any): void;
+    /**
+     * Encode `obj` to wire form and write it as one length-prefixed frame.
+     * @param {object} obj - message to send
+     * @returns {void}
+     */
+    send(obj: object): void;
 }

package/types/server.d.ts

@@ -1,24 +1,29 @@
+/**
+ * A decoded request frame. Carries the correlation `id` and `method`, plus the
+ * per-method fields a handler reads: `ref`, `handleId`, `query`, `cancelId`.
+ * @typedef {{ id?: string, method?: string, ref?: string, handleId?: string, query?: object, cancelId?: string }} ReqFrame
+ */
 /**
  * Read-only inspection server over a local Duplex `stream`. Serves the live
  * handle tree rooted at `me`, exposing only MAIN refs declared in each
  * handle's `spec.meta.refs` — local secret refs (master/keypair/
  * handle-keypairs) are never reachable, since they live in `meta.local.refs`.
  *
- * @param {any} stream  A streamx Duplex carrying length-prefixed JSON frames.
- * @param {any} me  The live root cero handle.
- * @param {{ events?: { snapshot(): any, subscribe(fn: (e: any) => void): () => void }, stats?: { snapshot(): any, subscribe(fn: (s: any) => void): () => void }, redact?: (ref: string, row: any) => any }} [opts]
+ * @param {object} stream  A streamx Duplex carrying length-prefixed JSON frames.
+ * @param {object} me  The live root cero handle.
+ * @param {{ events?: { snapshot(): unknown, subscribe(fn: (e: object) => void): () => void }, stats?: { snapshot(): unknown, subscribe(fn: (s: object) => void): () => void }, redact?: (ref: string, row: Record<string, unknown>) => Record<string, unknown> }} [opts]
  * @returns {{ close(): void }}
  */
-export function serve(stream: any, me: any, opts?: {
+export function serve(stream: object, me: object, opts?: {
     events?: {
-        snapshot(): any;
-        subscribe(fn: (e: any) => void): () => void;
+        snapshot(): unknown;
+        subscribe(fn: (e: object) => void): () => void;
     };
     stats?: {
-        snapshot(): any;
-        subscribe(fn: (s: any) => void): () => void;
+        snapshot(): unknown;
+        subscribe(fn: (s: object) => void): () => void;
     };
-    redact?: (ref: string, row: any) => any;
+    redact?: (ref: string, row: Record<string, unknown>) => Record<string, unknown>;
 }): {
     close(): void;
 };
@@ -31,20 +36,76 @@ export class TapServer {
     tracked: Map<any, any>;
     wire: Framed;
     _cleanup: () => void;
-    onRequest(req: any): Promise<void>;
-    handles(req: any): void;
-    get(req: any): Promise<void>;
-    count(req: any): Promise<void>;
-    watch(req: any): void;
-    events(req: any): void;
-    stats(req: any): void;
-    cancel(req: any): void;
+    /**
+     * Dispatch an inbound request frame to its named method handler.
+     * @param {ReqFrame} req  A decoded request frame, expected to carry `id` and `method`.
+     * @returns {Promise<void>}
+     */
+    onRequest(req: ReqFrame): Promise<void>;
+    /**
+     * Reply with the root handle and its direct children as `{ id, type }` rows.
+     * @param {ReqFrame} req  A request frame carrying `id`.
+     * @returns {void}
+     */
+    handles(req: ReqFrame): void;
+    /**
+     * Read a ref once and reply with the redacted result.
+     * @param {ReqFrame} req  A request frame carrying `id`, `ref`, `handleId` and `query`.
+     * @returns {Promise<void>}
+     */
+    get(req: ReqFrame): Promise<void>;
+    /**
+     * Count rows for a ref and reply with the total.
+     * @param {ReqFrame} req  A request frame carrying `id`, `ref`, `handleId` and `query`.
+     * @returns {Promise<void>}
+     */
+    count(req: ReqFrame): Promise<void>;
+    /**
+     * Stream redacted live updates for a ref until cancelled or the stream ends.
+     * @param {ReqFrame} req  A request frame carrying `id`, `ref`, `handleId` and `query`.
+     * @returns {void}
+     */
+    watch(req: ReqFrame): void;
+    /**
+     * Stream the events source snapshot then live events.
+     * @param {ReqFrame} req  A request frame carrying `id`.
+     * @returns {void}
+     */
+    events(req: ReqFrame): void;
+    /**
+     * Stream the stats source snapshot then live stats.
+     * @param {ReqFrame} req  A request frame carrying `id`.
+     * @returns {void}
+     */
+    stats(req: ReqFrame): void;
+    /**
+     * Stop a tracked stream by id and release its resources.
+     * @param {ReqFrame} req  A request frame carrying `cancelId`.
+     * @returns {void}
+     */
+    cancel(req: ReqFrame): void;
     _resolveRef(req: any): any;
     _source(req: any, src: any): void;
     _track(id: any, off: any): void;
     _drop(id: any): void;
     _send(obj: any): void;
     _teardown(): void;
+    /**
+     * Tear down all tracked streams and destroy the underlying stream.
+     * @returns {void}
+     */
     close(): void;
 }
+/**
+ * A decoded request frame. Carries the correlation `id` and `method`, plus the
+ * per-method fields a handler reads: `ref`, `handleId`, `query`, `cancelId`.
+ */
+export type ReqFrame = {
+    id?: string;
+    method?: string;
+    ref?: string;
+    handleId?: string;
+    query?: object;
+    cancelId?: string;
+};
 import { Framed } from './protocol.js';

package/types/tap.d.ts

@@ -1,3 +1,16 @@
+/**
+ * An applied-op event fed into the ring buffer. `op` is the dispatch verb
+ * prefix, `name` the ref name, `row` the decoded value, `writerKey` the source
+ * writer's key and `seq` a monotonic apply counter. After redaction `row` is
+ * replaced with its masked copy; the rest is spread through unchanged.
+ *
+ * @typedef {{ op: string, name: string, row: Record<string, unknown>, writerKey: Buffer, seq: number }} OpEvent
+ */
+/**
+ * A periodic `stats(me)` sample. See `stats()` for the field meanings.
+ *
+ * @typedef {{ handleId: string, network: { connections: number, peers: number, dht: object | null }, bee: { local: number }, cores: Array<{ length: number, byteLength: number, peers: number }>, at: number }} StatsSample
+ */
 /**
  * `cero.use(devtools())` tap extension. Bound to the root handle's lifecycle,
  * it feeds every applied op into a bounded ring buffer, samples `stats(me)` on
@@ -5,22 +18,55 @@
  * consumers. By default it serves a loopback TCP server on `port` (9111); pass
  * a custom `transport` to serve it some other way. Nothing touches the app swarm.
  *
- * @param {{ port?: number, host?: string, bufferSize?: number, sampleInterval?: number, redact?: ((ref: string, row: any) => any) | { fields?: string[], match?: Function, deny?: RegExp | false }, transport?: { accept(handler: (stream: any) => void): void } }} [opts]
- * @returns {{ setup(me: any): () => void }}
+ * @param {{ port?: number, host?: string, bufferSize?: number, sampleInterval?: number, redact?: ((ref: string, row: Record<string, unknown>) => Record<string, unknown>) | { fields?: string[], match?: (key: string, value: unknown, path: string) => boolean, deny?: RegExp | false }, transport?: { accept(handler: (stream: object) => void): void } }} [opts]
+ * @returns {{ setup(me: object): () => void }}
  */
 export function devtools(opts?: {
     port?: number;
     host?: string;
     bufferSize?: number;
     sampleInterval?: number;
-    redact?: ((ref: string, row: any) => any) | {
+    redact?: ((ref: string, row: Record<string, unknown>) => Record<string, unknown>) | {
         fields?: string[];
-        match?: Function;
+        match?: (key: string, value: unknown, path: string) => boolean;
         deny?: RegExp | false;
     };
     transport?: {
-        accept(handler: (stream: any) => void): void;
+        accept(handler: (stream: object) => void): void;
     };
 }): {
-    setup(me: any): () => void;
+    setup(me: object): () => void;
+};
+/**
+ * An applied-op event fed into the ring buffer. `op` is the dispatch verb
+ * prefix, `name` the ref name, `row` the decoded value, `writerKey` the source
+ * writer's key and `seq` a monotonic apply counter. After redaction `row` is
+ * replaced with its masked copy; the rest is spread through unchanged.
+ */
+export type OpEvent = {
+    op: string;
+    name: string;
+    row: Record<string, unknown>;
+    writerKey: Buffer;
+    seq: number;
+};
+/**
+ * A periodic `stats(me)` sample. See `stats()` for the field meanings.
+ */
+export type StatsSample = {
+    handleId: string;
+    network: {
+        connections: number;
+        peers: number;
+        dht: object | null;
+    };
+    bee: {
+        local: number;
+    };
+    cores: Array<{
+        length: number;
+        byteLength: number;
+        peers: number;
+    }>;
+    at: number;
 };