@cero-base/core 1.1.1 → 1.3.0

package/src/network/gatt-stream.js

@@ -0,0 +1,59 @@
+import { Duplex } from 'streamx'
+
+// iOS caps a single GATT write (and a notify payload) at ATT_MTU − 3 ≈ 182
+// bytes. 150 stays safely under that without negotiating an MTU. Raise later
+// via the peripheral's maximumWriteValueLength + write-without-response.
+const PAYLOAD = 150
+
+/**
+ * A dumb byte-carrying duplex for the GATT transport. Framing and session logic
+ * live in BluetoothTransport; this only fragments outbound writes to fit a GATT
+ * write and pushes inbound payload bytes. NoiseSecretStream wraps it as a raw
+ * duplex, exactly like the old L2CAP channel.
+ *
+ * @extends Duplex
+ */
+export class GattStream extends Duplex {
+  /**
+   * @param {object} opts
+   * @param {(buffer: Uint8Array) => Promise<void>} opts.send  Transmit one payload piece (transport frames it).
+   * @param {() => void} [opts.onclose]  Called once on teardown (send a close frame, disconnect).
+   */
+  constructor({ send, onclose } = {}) {
+    super()
+    this._send = send
+    this._onclose = onclose || null
+  }
+
+  async _write(chunk, cb) {
+    try {
+      for (let offset = 0; offset < chunk.byteLength; offset += PAYLOAD) {
+        await this._send(chunk.subarray(offset, offset + PAYLOAD))
+      }
+      cb(null)
+    } catch (err) {
+      cb(err)
+    }
+  }
+
+  receive(buffer) {
+    this.push(buffer)
+  }
+
+  remoteEnd() {
+    this.push(null)
+  }
+
+  _destroy(cb) {
+    const onclose = this._onclose
+    this._onclose = null
+    if (onclose) {
+      try {
+        onclose()
+      } catch {
+        // teardown is best-effort
+      }
+    }
+    cb(null)
+  }
+}

package/src/network/index.js

@@ -1,4 +1,6 @@
 import Hyperswarm from 'hyperswarm'
+import NoiseSecretStream from '@hyperswarm/secret-stream'
+import BlindPairing from 'blind-pairing'
 import ProtomuxWakeup from 'protomux-wakeup'
 import ReadyResource from 'ready-resource'
 import safetyCatch from 'safety-catch'
@@ -39,6 +41,89 @@ export class Network extends ReadyResource {
 
     this._replicateables = new Set()
     this._discoveries = new Set()
+    this._injected = new Set()
+    this._blind = null
+  }
+
+  /**
+   * Feed an externally-established connection — a Bluetooth L2CAP channel, a
+   * serial link, an in-process pair, any duplex — into the network. A raw
+   * duplex is wrapped in NoiseSecretStream (pass `isInitiator`); a stream
+   * that already IS one is used as-is. From here it gets the exact same
+   * treatment as a swarm connection: wakeup, replication of every attached
+   * core, pairing, and the 'connection' event.
+   *
+   * @param {any} stream  Duplex transport, or a ready NoiseSecretStream.
+   * @param {{ isInitiator?: boolean }} [opts]  Which side initiates the noise handshake (raw duplexes only).
+   * @returns {any} The encrypted connection stream.
+   */
+  inject(stream, { isInitiator } = {}) {
+    if (this.closing || this.closed) throw CeroError.CLOSED('Network')
+    if (!stream) throw CeroError.REQUIRED('stream')
+    // Injected links authenticate with the same long-lived identity as the
+    // swarm — an ephemeral key per link would defeat duplicate-peer detection
+    // (two radios between one pair would look like two different peers).
+    const keyPair = this.identity
+      ? { publicKey: this.identity.publicKey, secretKey: this.identity.secretKey }
+      : (this.swarm?.keyPair ?? undefined)
+    const conn =
+      stream.noiseStream === stream
+        ? stream
+        : new NoiseSecretStream(isInitiator === true, stream, keyPair ? { keyPair } : undefined)
+
+    // blind-pairing picks the lowest-`rtt` unvisited channel to send on; that
+    // field only exists on real udx sockets. A raw injected duplex has none,
+    // so `rtt < Infinity` is always false and pairing never sends a request.
+    // Zero is also the semantically correct RTT for a direct injected link.
+    if (conn.rawStream && conn.rawStream.rtt === undefined) conn.rawStream.rtt = 0
+
+    this._injected.add(conn)
+    conn.on('close', () => this._injected.delete(conn))
+    conn.on('error', safetyCatch) // a dropped radio link must not crash the host
+
+    this.wakeup.addStream(conn)
+    for (const r of this._replicateables) replicateInto(r, conn)
+    this.emit('connection', conn, { injected: true })
+    return conn
+  }
+
+  /**
+   * Lazily create the network-shared BlindPairing. One instance serves every
+   * handle's pairing member — per-handle instances each added their own swarm
+   * and DHT listeners plus a protomux channel per connection.
+   *
+   * @returns {Promise<any>}
+   */
+  async blind() {
+    if (!this._blind) {
+      const blind = new BlindPairing(this.swarm)
+      this._blind = blind.ready().then(() => {
+        // blind-pairing only watches the swarm — injected connections must
+        // reach it too, or offline (e.g. Bluetooth) pairing never completes.
+        // _onconnection is upstream-private; the offline-pairing test pins it.
+        this.on('connection', (conn, info) => {
+          if (info?.injected) blind._onconnection(conn)
+        })
+        for (const conn of this._injected) blind._onconnection(conn)
+        return blind
+      })
+    }
+    return this._blind
+  }
+
+  /**
+   * Re-attach pairing channels on injected connections. blind-pairing only
+   * auto-attaches refs that existed when a connection arrived — swarm peers
+   * meet again over topic joins, injected links (Bluetooth, pipes) don't, so
+   * a member/candidate added later must re-run the attach. Idempotent:
+   * protomux refuses duplicate channels.
+   *
+   * @returns {Promise<void>}
+   */
+  async refreshInjected() {
+    if (!this._blind || !this._injected.size) return
+    const blind = await this._blind
+    for (const conn of this._injected) blind._onconnection(conn)
   }
 
   /** @returns {Map<string, any>} Known peers keyed by public-key string. */
@@ -46,9 +131,10 @@ export class Network extends ReadyResource {
     return this.swarm ? this.swarm.peers : new Map()
   }
 
-  /** @returns {Set<any>} Live connection streams. */
+  /** @returns {Set<any>} Live connection streams — swarm and injected. */
   get connections() {
-    return this.swarm ? this.swarm.connections : new Set()
+    if (!this._injected.size) return this.swarm ? this.swarm.connections : new Set()
+    return new Set([...(this.swarm ? this.swarm.connections : []), ...this._injected])
   }
 
   /** @returns {boolean} */
@@ -129,6 +215,15 @@ export class Network extends ReadyResource {
   }
 
   async _close() {
+    for (const conn of [...this._injected]) {
+      try {
+        conn.destroy()
+      } catch (err) {
+        safetyCatch(err)
+      }
+    }
+    this._injected.clear()
+
     for (const d of [...this._discoveries]) {
       try {
         await d.destroy()
@@ -137,6 +232,15 @@ export class Network extends ReadyResource {
       }
     }
 
+    if (this._blind) {
+      try {
+        await (await this._blind).close()
+      } catch (err) {
+        safetyCatch(err)
+      }
+      this._blind = null
+    }
+
     if (this.swarm) {
       try {
         await this.flush()
@@ -195,9 +299,7 @@ export class Network extends ReadyResource {
   attach(core) {
     if (!core) throw CeroError.REQUIRED('core')
     this._replicateables.add(core)
-    if (this.swarm) {
-      for (const stream of this.swarm.connections) replicateInto(core, stream)
-    }
+    for (const stream of this.connections) replicateInto(core, stream)
   }
 
   /**
@@ -223,13 +325,24 @@ export class Network extends ReadyResource {
     if (!target || typeof target.replicate !== 'function') {
       throw CeroError.INVALID('target must be an object with a replicate(stream) method')
     }
-    if (this.swarm) {
-      for (const stream of this.swarm.connections) replicateInto(target, stream)
-    }
+    for (const stream of this.connections) replicateInto(target, stream)
   }
 }
 
+// Corestore replication is store-wide: N attached bees on one store would
+// re-attach every core AND add N duplicate StreamTracker records per
+// connection. Replicate each root store once per stream; wakeup streams are
+// added at the network level, so skipped bees lose nothing.
+const replicatedRoots = new WeakMap()
+
 function replicateInto(core, stream) {
+  const root = core.store ? core.store.root || core.store : null
+  if (root) {
+    let seen = replicatedRoots.get(stream)
+    if (!seen) replicatedRoots.set(stream, (seen = new WeakSet()))
+    if (seen.has(root)) return
+    seen.add(root)
+  }
   try {
     core.replicate(stream)
   } catch (err) {

package/src/pairing/index.js

@@ -88,13 +88,14 @@ export class Pairing extends ReadyResource {
 
   async _open() {
     await this.network.ready()
-    this._blind = new BlindPairing(this.network.swarm)
-    await this._blind.ready()
+    // shared instance — one set of swarm/DHT listeners for every handle
+    this._blind = await this.network.blind()
 
     this._member = this._blind.addMember({
       discoveryKey: discoveryKey(this.topic),
       onadd: (req) => this._onCandidate(req).catch(this._onerror)
     })
+    await this.network.refreshInjected()
   }
 
   async _close() {
@@ -105,10 +106,8 @@ export class Pairing extends ReadyResource {
       await this._member.close()
       this._member = null
     }
-    if (this._blind) {
-      await this._blind.close()
-      this._blind = null
-    }
+    // the BlindPairing is network-owned and shared — never close it here
+    this._blind = null
     this._invites.clear()
   }
 
@@ -415,6 +414,7 @@ class Candidate {
           onadd: (result) => this._done(result)
         })
         this._candidate.request.on('rejected', (err) => this._fail(fromBlindError(err)))
+        this.pairing.network.refreshInjected().catch(this._onerror ?? (() => {}))
       } catch (err) {
         this._fail(err instanceof CeroError ? err : CeroError.NETWORK_ERROR(err.message))
       }

package/src/rpc/index.js

@@ -108,13 +108,13 @@ export function bindCodec(spec) {
     },
     encodeAction(handle, op, data) {
       const ref = handle?.[op]
-      if (!ref || !ref.schema) throw new Error(`unknown action: ${op}`)
+      if (!ref || !ref.schema) throw CeroError.UNKNOWN('action', op)
       if (data == null) return EMPTY
       return schema.encode(ref.schema, data)
     },
     decodeAction(handle, op, buf) {
       const ref = handle?.[op]
-      if (!ref || !ref.schema) throw new Error(`unknown action: ${op}`)
+      if (!ref || !ref.schema) throw CeroError.UNKNOWN('action', op)
       if (!buf || buf.length === 0) return undefined
       return schema.decode(ref.schema, buf)
     }

package/src/storage/index.js

@@ -1,3 +1,5 @@
+import fs from 'fs'
+
 import HypercoreStorage from 'hypercore-storage'
 import Corestore from 'corestore'
 import HyperDB from 'hyperdb'
@@ -7,12 +9,15 @@ import { ROCKS, BEE, SINGLE, COLLECTION } from '../lib/constants.js'
 import { genId, subscribe } from '../lib/utils.js'
 import { CeroError } from '../lib/errors.js'
 
+const RANGE_OPS = new Set(['gt', 'gte', 'lt', 'lte', 'reverse', 'limit'])
+
 /**
  * @typedef {object} StorageOpts
  * @property {{ database: any, meta?: { ns?: string, refs?: Record<string, { kind?: string }> } }} spec
  * @property {'rocks' | 'bee'} backend
  * @property {any} [root]   Pre-existing HypercoreStorage to reuse.
  * @property {any} [store]  Pre-existing Corestore to reuse.
+ * @property {Uint8Array} [storageKey]  32-byte key encrypting the backing core at rest (bee backend only).
  *
  * @typedef {{ name: string, kind: string }} Ref
  * @typedef {{ id?: string, createdAt: number, updatedAt: number, [k: string]: any }} StoredRow
@@ -31,17 +36,22 @@ export class Storage extends ReadyResource {
    * @param {string} dir
    * @param {StorageOpts} [opts]
    */
-  constructor(dir, { spec, backend, root, store } = {}) {
+  constructor(dir, { spec, backend, root, store, storageKey } = {}) {
     super()
     if (!root && !store && (typeof dir !== 'string' || !dir))
       throw CeroError.REQUIRED('dir, root, or store')
     if (!spec || !spec.database) throw CeroError.REQUIRED('spec.database')
     if (backend !== ROCKS && backend !== BEE)
       throw CeroError.INVALID('backend must be "rocks" or "bee"')
+    if (storageKey && backend === ROCKS)
+      throw CeroError.INVALID('storageKey requires the bee backend')
+    if (storageKey && storageKey.byteLength !== 32)
+      throw CeroError.INVALID('storageKey must be 32 bytes')
 
     this.dir = dir
     this.spec = spec
     this.backend = backend
+    this.storageKey = storageKey || null
     this.ns = spec.meta?.ns || 'cero'
     this.refs = spec.meta?.refs || {}
 
@@ -77,6 +87,7 @@ export class Storage extends ReadyResource {
     if (this._ownsRoot) {
       this.root = new HypercoreStorage(this.dir, { columnFamilies: [this._cf] })
       await this.root.ready()
+      await fs.promises.chmod(this.dir, 0o700)
     }
 
     if (this._ownsStore) {
@@ -90,7 +101,7 @@ export class Storage extends ReadyResource {
       const cf = this.root.rocks.columnFamily(this._cf)
       this.db = HyperDB.rocks(cf, this.spec.database)
     } else {
-      const core = this.store.get({ name: 'local' })
+      const core = this.store.get({ name: 'local', encryptionKey: this.storageKey })
       await core.ready()
       this.db = HyperDB.bee(core, this.spec.database, { extension: false, autoUpdate: true })
     }
@@ -193,9 +204,19 @@ export class Storage extends ReadyResource {
       return { data: (await this.db.get(col, { id: query })) ?? null }
     }
 
+    // hyperdb only honors range/limit operators — equality fields must be
+    // filtered here or they are silently ignored and every row comes back
+    const eq = Object.keys(query || {}).filter((k) => !RANGE_OPS.has(k))
+    if (eq.length) {
+      const rows = await this.db.find(col, {}).toArray()
+      const matched = rows.filter((r) => eq.every((k) => r[k] === query[k]))
+      const data = query.limit != null ? matched.slice(0, query.limit) : matched
+      return { data, total: matched.length, size: data.length }
+    }
+
     const data = await this.db.find(col, query || {}).toArray()
-    // a filter (or limit) caps `data`, so `total` needs a full count; with no
-    // query `data` is already everything — skip the second scan.
+    // a limit caps `data`, so `total` needs a full count; with no query
+    // `data` is already everything — skip the second scan.
     const filtered = query && Object.keys(query).length > 0
     const total = filtered ? (await this.db.find(col, {}).toArray()).length : data.length
     return { data, total, size: data.length }
@@ -212,8 +233,10 @@ export class Storage extends ReadyResource {
     this._guard()
     const ref = this._ref(name)
     const col = this._col(ref)
-    const rows = await this.db.find(col, query || {}).toArray()
-    return { data: rows.length }
+    const eq = Object.keys(query || {}).filter((k) => !RANGE_OPS.has(k))
+    const rows = await this.db.find(col, eq.length ? {} : query || {}).toArray()
+    const matched = eq.length ? rows.filter((r) => eq.every((k) => r[k] === query[k])) : rows
+    return { data: matched.length }
   }
 
   /**
@@ -259,8 +282,7 @@ export class Storage extends ReadyResource {
   async _read(ref, id) {
     if (ref.kind === SINGLE) return this.db.findOne(this._col(ref), {})
     if (id == null) return null
-    const rows = await this.db.find(this._col(ref), {}).toArray()
-    return rows.find((r) => r.id === id) ?? null
+    return (await this.db.get(this._col(ref), { id })) ?? null
   }
 
   /** @param {Ref} ref @param {Record<string, any>} row @returns {Promise<void>} */

package/types/database/dispatch.d.ts

@@ -5,6 +5,7 @@
  * @param {{ dispatch: { Router: Function }, meta?: { refs?: Record<string, { kind?: string, builtin?: boolean, verb?: string }> } }} spec  Generated hyperdispatch spec.
  * @param {string} ns  Namespace prefix for collection and op names.
  * @param {Record<string, Function>} routes  Custom action handlers keyed by route name.
+ * @param {(err: Error) => void} [onerror]  Called when a malformed node is skipped.
  * @returns {{ dispatcher: object, apply: (nodes: Array<{ value: Buffer, key: Buffer }>, view: object, host: object) => Promise<void> }}
  */
 export function makeDispatcher(spec: {
@@ -18,7 +19,7 @@ export function makeDispatcher(spec: {
             verb?: string;
         }>;
     };
-}, ns: string, routes: Record<string, Function>): {
+}, ns: string, routes: Record<string, Function>, onerror?: (err: Error) => void, getDbKey?: () => any): {
     dispatcher: object;
     apply: (nodes: Array<{
         value: Buffer;

package/types/database/index.d.ts

@@ -9,12 +9,13 @@
  * @property {Uint8Array | null} [encryptionKey]                      Optional encryption key; falls back to identity's key.
  * @property {(nodes: any, view: any, host: any) => Promise<void>} [apply]  Override the default apply function.
  * @property {Uint8Array | null} [key]                                Existing autobee key to reopen.
+ * @property {boolean} [passive]                                      Join discovery server-only (reachable but not searching). Flip at runtime with `setActive`.
  * @property {import('../identity/index.js').KeyPair} [keyPair]       Device writer keypair; defaults to identity's keypair.
- * @property {(err: Error) => void} [onerror]                         Called when a background after-hook or onApply callback fails.
+ * @property {(err: Error) => void} [onerror]                         Called when a background after-hook or onApply callback fails, a malformed node is skipped, or the bee errors.
  *
  * @typedef {{ data: any | null }} SingleResult
- * @typedef {{ data: any[], total: number, size: number }} ListResult
- * @typedef {{ gt?: string, gte?: string, lt?: string, lte?: string, reverse?: boolean, limit?: number, search?: string, fields?: string[] }} Query
+ * @typedef {{ data: any[], total: number | null, size: number }} ListResult  `total` is null when a limited read skipped the full count — pass `{ total: true }` to force it.
+ * @typedef {{ gt?: string, gte?: string, lt?: string, lte?: string, reverse?: boolean, limit?: number, search?: string, fields?: string[], total?: boolean }} Query
  * @typedef {{ kind: string, verb: string, name: string }} Ref
  * @typedef {(ctx: any) => any | Promise<any>} HookFn
  */
@@ -58,6 +59,7 @@ export class Database extends ReadyResource {
     encryptionKey: Uint8Array<ArrayBufferLike>;
     applyOverride: (nodes: any, view: any, host: any) => Promise<void>;
     key: Uint8Array<ArrayBufferLike>;
+    passive: boolean;
     keyPair: import("../index.js").KeyPair | {
         publicKey: Uint8Array<ArrayBufferLike>;
         secretKey: Uint8Array<ArrayBufferLike>;
@@ -73,13 +75,22 @@ export class Database extends ReadyResource {
     };
     beforeHooks: Map<any, any>;
     afterHooks: Map<any, any>;
-    updaters: Set<any>;
+    updaters: Map<any, any>;
     onApplyHooks: Set<any>;
     _applySeq: number;
+    _touched: Set<any>;
     txQueue: any[];
     _discovery: import("../network/discovery.js").Discovery;
     /** Open the underlying autobee, wire dispatcher + apply, attach to network. */
     openBee(): Promise<void>;
+    /**
+     * Flip announce mode at runtime — passive stays reachable (server) but
+     * stops actively looking (client). Cheap; use it to demote idle rooms.
+     *
+     * @param {boolean} active
+     * @returns {Promise<void>}
+     */
+    setActive(active: boolean): Promise<void>;
     /** @returns {Uint8Array | null} discovery key of the underlying bee */
     get discoveryKey(): Uint8Array | null;
     /** @returns {Uint8Array | null} this device's local writer key */
@@ -107,12 +118,16 @@ export class Database extends ReadyResource {
      */
     after(op: string, fn: HookFn): () => void;
     /**
-     * Subscribe to local apply notifications. Fires whenever the view updates.
+     * Subscribe to local apply notifications. Fires whenever the view updates;
+     * pass `scope` (a ref name) to fire only when that ref was touched.
      *
      * @param {() => void} fn
+     * @param {string} [scope]
      * @returns {() => void} disposer
      */
-    onUpdate(fn: () => void): () => void;
+    onUpdate(fn: () => void, scope?: string): () => void;
+    _touch(nodes: any): void;
+    _byVerb: Map<any, any>;
     /**
      * Observe every applied op — local AND replicated (apply processes the merged
      * log). The callback receives `{ op, name, row, writerKey, seq }` and runs
@@ -210,6 +225,9 @@ export class Database extends ReadyResource {
      * @returns {Promise<SingleResult | ListResult>}
      */
     get(name: string, query?: string | Query): Promise<SingleResult | ListResult>;
+    _orderReady(name: any, col: any): Promise<any>;
+    _orderOk: Map<any, any>;
+    _total(col: any, query: any, rows: any): Promise<any>;
     /**
      * Number of rows that match `query` (or total if omitted).
      *
@@ -359,21 +377,28 @@ export type DatabaseOpts = {
      * Existing autobee key to reopen.
      */
     key?: Uint8Array | null;
+    /**
+     * Join discovery server-only (reachable but not searching). Flip at runtime with `setActive`.
+     */
+    passive?: boolean;
     /**
      * Device writer keypair; defaults to identity's keypair.
      */
     keyPair?: import("../identity/index.js").KeyPair;
     /**
-     * Called when a background after-hook or onApply callback fails.
+     * Called when a background after-hook or onApply callback fails, a malformed node is skipped, or the bee errors.
      */
     onerror?: (err: Error) => void;
 };
 export type SingleResult = {
     data: any | null;
 };
+/**
+ * `total` is null when a limited read skipped the full count — pass `{ total: true }` to force it.
+ */
 export type ListResult = {
     data: any[];
-    total: number;
+    total: number | null;
     size: number;
 };
 export type Query = {
@@ -385,6 +410,7 @@ export type Query = {
     limit?: number;
     search?: string;
     fields?: string[];
+    total?: boolean;
 };
 export type Ref = {
     kind: string;

package/types/identity/index.d.ts

@@ -125,6 +125,15 @@ export class Identity {
      * @type {Uint8Array}
      */
     seed: Uint8Array;
+    /**
+     * Redacted — secretKey/encryptionKey/seed must never reach JSON.stringify
+     * or a structured logger.
+     *
+     * @returns {{ id: string }}
+     */
+    toJSON(): {
+        id: string;
+    };
     /**
      * Detached Ed25519 signature over `message`.
      *

package/types/lib/errors.d.ts

@@ -42,6 +42,12 @@ export class CeroError extends Error {
      * @param {string} name
      */
     static NOT_READY(resource: string, name: string): CeroError;
+    /**
+     * Operation raced an existing state (e.g. double init).
+     *
+     * @param {string} msg
+     */
+    static CONFLICT(msg: string): CeroError;
     /**
      * Resource has been destroyed.
      *

package/types/lib/utils.d.ts

@@ -39,11 +39,9 @@ export const toId: (key: Uint8Array) => string;
  * @type {(id: string) => Uint8Array}
  */
 export const toKey: (id: string) => Uint8Array;
-/**
- * Test whether a string is a well-formed canonical id.
- *
- * @type {(id: string) => boolean}
- */
-export const isKeyId: (id: string) => boolean;
+/** @type {(dbKey: Uint8Array, writer: Uint8Array, appender: Uint8Array) => Uint8Array} */
+export const addWriterPayload: (dbKey: Uint8Array, writer: Uint8Array, appender: Uint8Array) => Uint8Array;
+/** @type {(dbKey: Uint8Array, writer: Uint8Array) => Uint8Array} */
+export const claimWriterPayload: (dbKey: Uint8Array, writer: Uint8Array) => Uint8Array;
 export function grants(a: any, b: any): boolean;
 export function outranks(a: any, b: any): boolean;