@cero-base/core 1.1.0 → 1.2.0

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;

package/types/network/bluetooth.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Derive a stable 128-bit BLE service UUID from a topic. Only devices that
+ * compute the same UUID (same channel / same invite) ever discover each other.
+ *
+ * @param {Uint8Array} topic
+ * @param {string} [tag]  Namespace so channel and invite meshes never collide.
+ * @returns {string}
+ */
+export function toServiceUUID(topic: Uint8Array, tag?: string): string;
+/**
+ * Dual-role BLE transport: advertises + scans one service UUID, opens an L2CAP
+ * channel to each discovered peer, and feeds it into `network.inject`. From
+ * there replication and pairing are transport-agnostic (see Network.inject).
+ *
+ * Choreography mirrors the proven bare-mobile-doctor worklet: server adds a
+ * readable PSM characteristic at startup and answers reads dynamically; the
+ * central connects, reads "<psm>:<nodeId>", tie-breaks, then opens the channel.
+ * `backend` is bare-bluetooth in production and a mock in tests.
+ *
+ * ponytail: capability-handshake DoS link-scoring is deferred — it needs a
+ * replication-progress signal (design §4b). v1 caps links + times out dials.
+ *
+ * @extends ReadyResource
+ */
+export class BluetoothTransport extends ReadyResource {
+    /**
+     * @param {object} opts
+     * @param {any} opts.backend            bare-bluetooth-shaped module (Central, Server, Service, Characteristic).
+     * @param {import('./index.js').Network} opts.network
+     * @param {Uint8Array} opts.uuid        The 32-byte topic the service UUID derives from.
+     * @param {Uint8Array} opts.nodeId      Stable local id (identity/device key) for the initiate tie-break.
+     * @param {string} [opts.tag]           UUID namespace (channel mesh vs invite mesh).
+     * @param {number} [opts.cap]           Max concurrent links; gossip covers the rest.
+     * @param {{ scanMode?: any }} [opts.scanOptions]  Platform scan options (e.g. Android low-power).
+     * @param {boolean} [opts.keepLinks]    On close, stop the radio but leave established links alive (invite rendezvous: the link outlives the QR and carries the initial replication).
+     */
+    constructor({ backend, network, uuid, nodeId, tag, cap, scanOptions, keepLinks }: {
+        backend: any;
+        network: import("./index.js").Network;
+        uuid: Uint8Array;
+        nodeId: Uint8Array;
+        tag?: string;
+        cap?: number;
+        scanOptions?: {
+            scanMode?: any;
+        };
+        keepLinks?: boolean;
+    });
+    backend: any;
+    network: import("./index.js").Network;
+    nodeId: Uint8Array<ArrayBufferLike>;
+    nodeHex: any;
+    serviceUUID: string;
+    cap: number;
+    scanOptions: {
+        scanMode?: any;
+    };
+    keepLinks: boolean;
+    state: string;
+    central: any;
+    server: any;
+    psm: any;
+    _scanning: boolean;
+    _advertising: boolean;
+    _serviceAdded: boolean;
+    /** peripheral id being dialed → its connect-timeout timer */
+    _dialing: Map<any, any>;
+    /** live injected links keyed by remote node id hex */
+    peers: Map<any, any>;
+    /**
+     * Whether we should be the one to open the connection to `peerNodeId`. The
+     * lexicographically smaller id initiates; the larger waits — so a pair
+     * connects once, not twice. Equal (our own reflection) → false.
+     *
+     * @param {Uint8Array} peerNodeId
+     * @returns {boolean}
+     */
+    shouldInitiate(peerNodeId: Uint8Array): boolean;
+    get linkCount(): number;
+    _startServer(Service: any, Characteristic: any): void;
+    _maybeAdvertise(): void;
+    _startScan(): void;
+    _onState(raw: any): void;
+    _onDiscover(peripheral: any): void;
+    _onConnect(peripheral: any): void;
+    _abortDial(peripheral: any, _reason: any): void;
+    _clearDial(id: any): void;
+    _onCentralError(err: any): void;
+    _onChannel(l2cap: any, isInitiator: any, peripheralId: any): void;
+    _track(conn: any, peripheralId: any): void;
+    _untrack(conn: any): void;
+}
+import ReadyResource from 'ready-resource';

package/types/network/index.d.ts

@@ -28,9 +28,44 @@ export class Network extends ReadyResource {
     wakeup: any;
     _replicateables: Set<any>;
     _discoveries: Set<any>;
+    _injected: Set<any>;
+    _blind: any;
+    /**
+     * 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: any, { isInitiator }?: {
+        isInitiator?: boolean;
+    }): any;
+    /**
+     * 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>}
+     */
+    blind(): Promise<any>;
+    /**
+     * 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>}
+     */
+    refreshInjected(): Promise<void>;
     /** @returns {Map<string, any>} Known peers keyed by public-key string. */
     get peers(): Map<string, any>;
-    /** @returns {Set<any>} Live connection streams. */
+    /** @returns {Set<any>} Live connection streams — swarm and injected. */
     get connections(): Set<any>;
     /** @returns {boolean} */
     get suspended(): boolean;

package/types/storage/index.d.ts

@@ -4,6 +4,7 @@
  * @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
@@ -35,7 +36,7 @@ export class Storage extends ReadyResource {
      * @param {string} dir
      * @param {StorageOpts} [opts]
      */
-    constructor(dir: string, { spec, backend, root, store }?: StorageOpts);
+    constructor(dir: string, { spec, backend, root, store, storageKey }?: StorageOpts);
     dir: string;
     spec: {
         database: any;
@@ -47,6 +48,7 @@ export class Storage extends ReadyResource {
         };
     };
     backend: "rocks" | "bee";
+    storageKey: Uint8Array<ArrayBufferLike>;
     ns: string;
     refs: Record<string, {
         kind?: string;
@@ -143,6 +145,10 @@ export type StorageOpts = {
      * Pre-existing Corestore to reuse.
      */
     store?: any;
+    /**
+     * 32-byte key encrypting the backing core at rest (bee backend only).
+     */
+    storageKey?: Uint8Array;
 };
 export type Ref = {
     name: string;

package/src/database/CLAUDE.md

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

package/src/identity/CLAUDE.md

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

package/src/lib/CLAUDE.md

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