@cero-base/tools 1.1.1 → 1.3.0

package/README.md

@@ -22,15 +22,21 @@ cero.use(devtools({ transport: loopback({ port: 9111 }) }))
 
 `devtools(opts)`:
 
-| opt              | default | meaning                                                                             |
-| ---------------- | ------- | ----------------------------------------------------------------------------------- |
-| `transport`      | —       | a `{ accept(handler) }` source of consumer connections (use `loopback({ port })`)   |
-| `bufferSize`     | `1000`  | event ring buffer size (drop-oldest)                                                |
-| `sampleInterval` | `1000`  | stats sampling interval (ms)                                                        |
-| `redact`         | —       | a `(ref, row) => row` masker, or a config `{ fields, match, deny }` (see Redaction) |
+| opt              | default | meaning                                                                              |
+| ---------------- | ------- | ------------------------------------------------------------------------------------ |
+| `transport`      | —       | a `{ accept(handler) }` source of consumer connections (use `loopback({ port })`)    |
+| `bufferSize`     | `1000`  | event ring buffer size (drop-oldest)                                                 |
+| `sampleInterval` | `1000`  | stats sampling interval (ms)                                                         |
+| `redact`         | —       | a `(ref, row) => row` masker, or a config `{ fields, match, deny }` (see Redaction)  |
+| `token`          | random  | auth token gating the tap — printed in the startup banner; `false` disables the gate |
 
 Zero footprint when not registered; all cleanup is bound to the root handle's `close`.
 
+Any local process can dial the loopback port, so the tap requires a per-run token: the first
+frame of a connection must carry it or the connection is dropped. The banner prints the exact
+`cero-tools <port> --token <token>` command. Keep devtools out of production builds regardless —
+the tap is a development tool.
+
 ## Consumer side — connect
 
 ```js
@@ -50,7 +56,7 @@ session.close()
 ## CLI
 
 ```sh
-cero-tools <port> [refs...]
+cero-tools <port> --token <token> [refs...]
 # prints the handle tree + state for each ref, then tails events + stats until Ctrl-C
 ```
 
@@ -64,6 +70,10 @@ devtools({ redact: { fields: ['profile.apiKey'] } })
 devtools({ redact: { match: (key) => key.endsWith('Secret') } })
 ```
 
+The default is a **denylist by field name** — a secret stored under an off-list name (`otp`,
+`recoveryCode`, …) transits unmasked. Add such fields via `fields`/`match`, or pass your own
+`(ref, row) => row` masker for allowlist semantics.
+
 Identity credentials (the seed and keypairs) need no redaction: they're `local` builtins and the inspection surface only serves declared `meta.refs`, so they're never reachable.
 
 ## API

package/bin/cero-tools.js

@@ -3,9 +3,12 @@ import { dial } from '../src/transport.js'
 import { connect } from '../src/connect.js'
 import { formatHandles, formatState, formatError, formatEvent, formatStats } from '../src/format.js'
 
-const arg = process.argv[2]
+const argv = process.argv.slice(2)
+const ti = argv.indexOf('--token')
+const token = ti >= 0 ? argv.splice(ti, 2)[1] : undefined
+const [arg, ...refs] = argv
 if (!arg) {
-  console.log('usage: cero-tools [host:]<port> [refs...]')
+  console.log('usage: cero-tools [host:]<port> [--token <token>] [refs...]')
   process.exit(1)
 }
 
@@ -28,11 +31,11 @@ socket.on('error', (err) => {
   process.exit(1)
 })
 
-const session = await connect(socket)
+const session = await connect(socket, { token })
 
 console.log(formatHandles(await session.handles()))
 
-for (const ref of process.argv.slice(3)) {
+for (const ref of refs) {
   try {
     console.log(formatState(ref, await session.get(ref)))
   } catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cero-base/tools",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "Passive devtools for cero — observe data, events, and p2p/replication stats over a local out-of-band pipe.",
   "type": "module",
   "sideEffects": false,
@@ -21,6 +21,10 @@
     "net": {
       "bare": "bare-net",
       "default": "net"
+    },
+    "crypto": {
+      "bare": "bare-crypto",
+      "default": "crypto"
     }
   },
   "files": [
@@ -28,7 +32,8 @@
     "types",
     "bin",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "!**/CLAUDE.md"
   ],
   "publishConfig": {
     "access": "public"
@@ -50,14 +55,14 @@
   "scripts": {
     "build:types": "rm -rf types && tsc -p .",
     "prepublishOnly": "npm run build:types",
-    "test": "ls test/*.test.js | xargs -P1 -n1 brittle-node"
+    "test": "ls test/*.test.js | xargs -P1 -n1 brittle-node",
+    "test:bare": "npx bare test/bare-smoke.js"
   },
   "dependencies": {
-    "@cero-base/cero": "^1.1.1",
-    "@cero-base/core": "^1.1.1",
+    "@cero-base/cero": "^1.3.0",
     "b4a": "^1.8.1",
+    "bare-crypto": "^1.15.3",
     "bare-net": "^2.3.2",
-    "compact-encoding": "^3.2.0",
     "streamx": "^2.28.0"
   },
   "devDependencies": {
@@ -65,5 +70,15 @@
     "brittle": "^4.0.2",
     "typescript": "^5.9.3"
   },
-  "license": "Apache-2.0"
+  "license": "Apache-2.0",
+  "typesVersions": {
+    "*": {
+      "connect": [
+        "./types/connect.d.ts"
+      ],
+      "stats": [
+        "./types/stats.d.ts"
+      ]
+    }
+  }
 }

package/src/connect.js

@@ -19,13 +19,14 @@ import { Framed } from './protocol.js'
  * @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)
+export async function connect(stream, { token } = {}) {
+  return new Session(stream, { token })
 }
 
 export class Session {
-  constructor(stream) {
+  constructor(stream, { token } = {}) {
     this.stream = stream
+    this.token = token || null
     this.pending = new Map()
     this.streams = new Map()
     this.seq = 0
@@ -67,11 +68,15 @@ export class Session {
     return ++this.seq
   }
 
+  _send(frame) {
+    this.wire.send(this.token ? { token: this.token, ...frame } : frame)
+  }
+
   _request(method, fields) {
     return new Promise((resolve, reject) => {
       const id = this._newId()
       this.pending.set(id, { resolve, reject })
-      this.wire.send({ id, method, ...fields })
+      this._send({ id, method, ...fields })
     })
   }
 
@@ -80,12 +85,12 @@ export class Session {
     const r = new Readable({
       destroy: (cb) => {
         if (this.streams.delete(id))
-          this.wire.send({ id: this._newId(), method: 'cancel', cancelId: id })
+          this._send({ id: this._newId(), method: 'cancel', cancelId: id })
         cb(null)
       }
     })
     this.streams.set(id, r)
-    this.wire.send({ id, method, ...fields })
+    this._send({ id, method, ...fields })
     return r
   }
 

package/src/server.js

@@ -30,6 +30,7 @@ export class TapServer {
     this.redact = opts.redact || ((ref, row) => row)
     this.opts = opts
     this.tracked = new Map()
+    this._authed = !opts.token
     this.wire = new Framed(stream, (req) => this.onRequest(req))
     this._cleanup = () => this._teardown()
     stream.on('close', this._cleanup)
@@ -45,6 +46,12 @@ export class TapServer {
   async onRequest(req) {
     // a malformed frame (JSON null / scalar) has no method — ignore it
     if (!req || typeof req !== 'object') return
+    // token gate: the first frame must carry the tap token — one shot, a
+    // mismatch drops the connection (no probing across attempts)
+    if (!this._authed) {
+      if (req.token !== this.opts.token) return this.stream.destroy()
+      this._authed = true
+    }
     const handler = this[req.method]
     if (!handler || !METHODS.has(req.method)) {
       this._send({

package/src/tap.js

@@ -1,3 +1,5 @@
+import crypto from 'crypto'
+
 import { stats } from './stats.js'
 import { serve } from './server.js'
 import { redact } from './redact.js'
@@ -25,7 +27,7 @@ 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: 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]
+ * @param {{ port?: number, host?: string, token?: string | false, 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 = {}) {
@@ -34,7 +36,12 @@ export function devtools(opts = {}) {
       const events = new Ring(opts.bufferSize ?? 1000)
       const sampler = new Sampler(me, opts.sampleInterval ?? 1000)
       const redactor = makeRedactor(opts.redact)
-      const transport = opts.transport || loopback({ port: opts.port ?? 9111, host: opts.host })
+      // any local process can dial the loopback port — a per-run token gates the
+      // tap so co-tenant processes can't read app data. `token: false` opts out.
+      const token =
+        opts.token === false ? null : opts.token || crypto.randomBytes(16).toString('hex')
+      const transport =
+        opts.transport || loopback({ port: opts.port ?? 9111, host: opts.host, token })
       const offs = []
       const servers = new Set()
 
@@ -51,7 +58,7 @@ export function devtools(opts = {}) {
       me.on('handle', (child) => follow(child), { signal: me.signal })
 
       transport.accept((stream) => {
-        const server = serve(stream, me, { events, stats: sampler, redact: redactor })
+        const server = serve(stream, me, { events, stats: sampler, redact: redactor, token })
         servers.add(server)
         stream.on('close', () => servers.delete(server))
       })

package/src/transport.js

@@ -5,7 +5,7 @@ import net from 'net'
  * plus lifecycle. Each inbound connection's socket is a streamx-compatible
  * Duplex, ready to pass straight to `serve()`.
  *
- * @param {{ port?: number, host?: string }} [opts]
+ * @param {{ port?: number, host?: string, token?: string | null }} [opts]
  * @returns {{ accept(handler: (socket: any) => void): void, ready(): Promise<{ port: number }>, port: number | null, close(): void }}
  */
 export function loopback(opts = {}) {
@@ -34,7 +34,7 @@ export function loopback(opts = {}) {
         })
       })
       ready.catch(() => {}) // ready() may never be called — don't go unhandled
-      server.on('listening', () => console.log(banner(host, server.address().port)))
+      server.on('listening', () => console.log(banner(host, server.address().port, opts.token)))
       server.listen(port, host)
     },
     ready() {
@@ -62,16 +62,17 @@ export function dial(opts = {}) {
 }
 
 // VITE-style startup banner printed when the tap starts listening.
-function banner(host, port) {
+function banner(host, port, token) {
   const e = '\x1b['
   const r = `${e}0m`
   const dim = `${e}2m`
   const bold = `${e}1m`
   const cyan = `${e}36m`
   const green = `${e}32m`
+  const cmd = token ? `cero-tools ${port} --token ${token}` : `cero-tools ${port}`
   return (
     `\n  ${bold}${cyan}cero devtools${r}  ${dim}tap ready${r}\n\n` +
     `  ${green}➜${r}  ${bold}Listening${r}:  ${cyan}${host}:${port}${r}\n` +
-    `  ${green}➜${r}  ${bold}Connect${r}:    ${dim}cero-tools ${port}${r}\n`
+    `  ${green}➜${r}  ${bold}Connect${r}:    ${dim}${cmd}${r}\n`
   )
 }

package/types/connect.d.ts

@@ -13,7 +13,7 @@
  * @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: object): Promise<{
+export function connect(stream: object, { token }?: {}): Promise<{
     handles(): Promise<Handle[]>;
     get(ref: string, query?: Query, handleId?: string): Promise<unknown>;
     count(ref: string, query?: Query, handleId?: string): Promise<number>;
@@ -23,8 +23,9 @@ export function connect(stream: object): Promise<{
     close(): void;
 }>;
 export class Session {
-    constructor(stream: any);
+    constructor(stream: any, { token }?: {});
     stream: any;
+    token: any;
     pending: Map<any, any>;
     streams: Map<any, any>;
     seq: number;
@@ -32,6 +33,7 @@ export class Session {
     _onClose(): void;
     _onMessage(msg: any): void;
     _newId(): number;
+    _send(frame: any): void;
     _request(method: any, fields: any): Promise<any>;
     _stream(method: any, fields: any): Readable<import("streamx").ReadableEvents>;
     /**

package/types/server.d.ts

@@ -34,6 +34,7 @@ export class TapServer {
     redact: any;
     opts: {};
     tracked: Map<any, any>;
+    _authed: boolean;
     wire: Framed;
     _cleanup: () => void;
     /**

package/types/tap.d.ts

@@ -18,12 +18,13 @@
  * 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: 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]
+ * @param {{ port?: number, host?: string, token?: string | false, 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;
+    token?: string | false;
     bufferSize?: number;
     sampleInterval?: number;
     redact?: ((ref: string, row: Record<string, unknown>) => Record<string, unknown>) | {

package/types/transport.d.ts

@@ -3,12 +3,13 @@
  * plus lifecycle. Each inbound connection's socket is a streamx-compatible
  * Duplex, ready to pass straight to `serve()`.
  *
- * @param {{ port?: number, host?: string }} [opts]
+ * @param {{ port?: number, host?: string, token?: string | null }} [opts]
  * @returns {{ accept(handler: (socket: any) => void): void, ready(): Promise<{ port: number }>, port: number | null, close(): void }}
  */
 export function loopback(opts?: {
     port?: number;
     host?: string;
+    token?: string | null;
 }): {
     accept(handler: (socket: any) => void): void;
     ready(): Promise<{

package/src/CLAUDE.md

@@ -1,3 +0,0 @@
-<claude-mem-context>
-
-</claude-mem-context>