@cero-base/core 1.1.1 → 1.3.0

package/types/network/bluetooth.d.ts

@@ -0,0 +1,162 @@
+/**
+ * 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 a GATT
+ * byte-stream to each discovered peer, and feeds it into `network.inject`. From
+ * there replication and pairing are transport-agnostic (see Network.inject).
+ *
+ * Choreography: the server adds one data characteristic (write + notify) and
+ * advertises. The central connects, discovers the characteristic, subscribes,
+ * then framed bytes flow both ways — central→server as GATT writes, server→
+ * central as notifications — each tagged with an 8-byte session id (bitchat
+ * model). `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).
+     * @param {string} [opts.name]          Local app-user display name, sent to peers over a hello frame.
+     */
+    constructor({ backend, network, uuid, nodeId, tag, cap, scanOptions, keepLinks, name }: {
+        backend: any;
+        network: import("./index.js").Network;
+        uuid: Uint8Array;
+        nodeId: Uint8Array;
+        tag?: string;
+        cap?: number;
+        scanOptions?: {
+            scanMode?: any;
+        };
+        keepLinks?: boolean;
+        name?: string;
+    });
+    backend: any;
+    network: import("./index.js").Network;
+    name: string;
+    nodeId: Uint8Array<ArrayBufferLike>;
+    nodeHex: any;
+    serviceUUID: string;
+    cap: number;
+    scanOptions: {
+        scanMode?: any;
+    };
+    keepLinks: boolean;
+    state: string;
+    central: any;
+    server: any;
+    _dataChar: any;
+    /** sessionId hex → { stream, sid } for server-side (peripheral) sessions */
+    _sessions: Map<any, any>;
+    /** serialized server notify queue: { frame, resolve, reject } */
+    _notifyQueue: any[];
+    _scanning: boolean;
+    _advertising: boolean;
+    _serviceAdded: boolean;
+    /** peripheral id being dialed → its connect-timeout timer */
+    _dialing: Map<any, any>;
+    /** peripheral ids that carry a live channel — never re-dialed (a second
+     * dial's failure would disconnect the peripheral and kill the good link) */
+    _linked: Set<any>;
+    /** peripheral id → retry-after timestamp; failed dials back off */
+    _coolUntil: Map<any, any>;
+    /** peripheral id → consecutive failure count; drives exponential backoff */
+    _failures: Map<any, any>;
+    /** peripheral id → remote peer key, learned at handshake — dial guard */
+    _peerByPeripheral: Map<any, any>;
+    /** live central-side peripheral wrappers — for goodbye + physical hang-up on suspend */
+    _connectedPeripherals: Set<any>;
+    /** last central.connect timestamp — global inter-dial rate limit */
+    _lastDial: number;
+    _scanTimer: any;
+    _suspended: boolean;
+    /** 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;
+    _onWriteRequests(requests: any): void;
+    _onServerFrame(data: any): void;
+    _closeServerSession(sidHex: any, sid: any): void;
+    /** Our hello payload: the local app-user name the peer labels this link with. */
+    _helloPayload(): any;
+    /**
+     * Parse a hello payload. Malformed → null (the caller ignores it).
+     *
+     * @param {Uint8Array} payload
+     * @returns {string | null}
+     */
+    _parseHello(payload: Uint8Array): string | null;
+    /** Stash a peer's name onto a server session + its conn, then refresh mirrors. */
+    _applyPeerName(session: any, payload: any): void;
+    _enqueueNotify(f: any): Promise<any>;
+    _drainNotify(): void;
+    _startScan(): void;
+    _armScanRestart(): void;
+    _stopScan(): void;
+    _onState(raw: any): void;
+    _onDiscover(peripheral: any): void;
+    _onConnect(peripheral: any): void;
+    _startCentralSession(peripheral: any, char: any): void;
+    _onCentralNotify(peripheral: any, data: any): void;
+    _centralSend(peripheral: any, char: any, f: any): any;
+    _writeOnce(peripheral: any, char: any, f: any): Promise<any>;
+    _abortDial(peripheral: any, _reason: any): void;
+    _clearDial(id: any): void;
+    _onCentralError(err: any): void;
+    _onChannel(l2cap: any, isInitiator: any, peripheralId: any): any;
+    _track(conn: any, peripheralId: any, isInitiator: any): void;
+    _untrack(conn: any): void;
+    /**
+     * Best-effort TYPE_CLOSE to every live session — server sessions over the
+     * notify path, central sessions over the write path — reusing the same helpers
+     * a normal stream close uses. Waits up to DRAIN_MS for the frames to flush,
+     * then resolves regardless: suspend must never hang on a wedged radio.
+     *
+     * @returns {Promise<void>}
+     */
+    _sayGoodbye(): Promise<void>;
+    /**
+     * Pause radio activity but KEEP the Server/Central instances and the
+     * registered GATT service alive — the toggle-friendly counterpart to _close.
+     * iOS CoreBluetooth managers can't be destroy()ed (native double-free), so a
+     * fresh transport per toggle leaks a manager whose stale peripheral-manager
+     * keeps a duplicate GATT service registered; remote centrals then subscribe to
+     * the dead service and hear silence. Reuse one instance instead. Idempotent.
+     */
+    suspend(): Promise<void>;
+    /**
+     * Restart advertising + scanning on the SAME Server/Central. `_serviceAdded`
+     * is still true (the service was never removed) so advertising resumes
+     * immediately. Safe to call repeatedly; no-op once closing/closed.
+     */
+    resume(): void;
+}
+import ReadyResource from 'ready-resource';

package/types/network/gatt-stream.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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<import("streamx").DuplexEvents> {
+    /**
+     * @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 }?: {
+        send: (buffer: Uint8Array) => Promise<void>;
+        onclose?: () => void;
+    });
+    _send: (buffer: Uint8Array) => Promise<void>;
+    _onclose: () => void;
+    _write(chunk: any, cb: any): Promise<void>;
+    receive(buffer: any): void;
+    remoteEnd(): void;
+    _destroy(cb: any): void;
+}
+import { Duplex } from 'streamx';

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/CLAUDE.md

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

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>

package/src/network/CLAUDE.md

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

package/src/rpc/CLAUDE.md

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

package/src/storage/CLAUDE.md

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