@openvole/volenet 1.0.0 → 1.1.1

package/README.md

@@ -8,19 +8,29 @@ npm install @openvole/volenet
 ```
 
 ```ts
-import { VoleNetManager, createEventBus, generateKeyPair } from '@openvole/volenet'
+import { VoleNetManager, createEventBus } from '@openvole/volenet'
 
 const bus = createEventBus()
-bus.on('volenet:chat', (m) => console.log(`${m.fromName}: ${m.text}`))
+// `room` is present when this arrived as a room post rather than a private message.
+bus.on('volenet:chat', (m) => console.log(`${m.room ?? 'dm'} ${m.fromName}: ${m.text}`))
 
 const net = new VoleNetManager(
   { enabled: true, instanceName: 'my-node', port: 9700, keyPath: './data/net/vole_key' },
   './data',
 )
 await net.start(undefined, bus)
+
 await net.sendChat('some-peer', 'hello')
+
+// A room, through a hub that reads none of it (§7c).
+await net.roomCommand('my-hub', 'room:create', { name: 'valley' })
+const [room] = net.getRooms()
+await net.postToRoom(room.room, 'morning')  // → { sent, held, skipped }
 ```
 
+An identity is generated on first start if `keyPath` has none. `generateKeyPair`, `trustPeer` and
+the rest are exported for anything that manages keys itself.
+
 ## What it gives you
 
 - **Identity that is a keypair, not an account.** Hybrid Ed25519 + ML-DSA-65 signatures, so a
@@ -32,6 +42,10 @@ await net.sendChat('some-peer', 'hello')
 - **Blind relay hubs.** A hub forwards ciphertext for peers that cannot dial each other and keeps
   none of it. An undelivered message waits in the *sender's* outbox; the hub keeps a notice — who
   tried, how often, when — and nothing more.
+- **Rooms.** Several members in one conversation, each post sealed once per member — so there is no
+  room key, and removing somebody stops them reading by construction rather than by a rotation
+  anybody has to remember. Capped at 64 members, which is where sealing per member stops making
+  sense; it refuses there rather than getting quietly slow.
 - **Consent.** Nothing is trusted because it connected. A peer is paired directly, or consented to
   through a hub, before it can say anything to you.
 - **Intermittent peers as a supported shape.** Senders hold what they could not deliver and flush
@@ -46,6 +60,7 @@ Three things a host may provide, and none of them are required:
 | an `EventSink` to `start()` | every event this node raises | it runs silently; `createEventBus()` is there if you have no bus |
 | a `ToolProvider` to `start()` | tools shareable with trusted peers | no tool sharing |
 | `persistPeer` in the config | peers learned at runtime survive a restart | they are live-only |
+| `persistPeerEntry` in the config | a peer named by identity survives too — the only way to record one with no address | live-only |
 
 `setLoggerFactory()` redirects the library's logging into your own logger. Left alone it writes to
 `VOLE_LOG_FILE` when that is set, and is silent otherwise.
@@ -71,5 +86,5 @@ are referenced from the Rust client's source.
 pnpm -C src/volenet test
 ```
 
-204 tests, including end-to-end pairing, relay with consent, held messages, file transfer, and
-byte-level interop with the Rust client.
+213 tests, including end-to-end pairing, relay with consent, held messages, rooms across a
+three-node mesh, file transfer, and byte-level interop with the Rust client.

package/dist/index.d.ts

@@ -76,7 +76,7 @@ declare class RelayNotices {
  * The local node's post-quantum (ML-DSA) signing key, set once at VoleNet start.
  * Module-level because there is exactly one signing identity per process — this lets
  */
-type VoleNetMessageType = 'ping' | 'pong' | 'discover' | 'discover:response' | 'auth:challenge' | 'auth:response' | 'auth:result' | 'task:delegate' | 'task:result' | 'task:status' | 'memory:sync' | 'memory:search' | 'memory:results' | 'session:sync' | 'tool:list' | 'tool:list:response' | 'tool:call' | 'tool:result' | 'leader:heartbeat' | 'leader:claim' | 'leader:ack' | 'chat:message' | 'sealed' | 'sealed:direct' | 'relay:deliver' | 'relay:error' | 'relay:ack' | 'relay:pending' | 'roster' | 'relay:connect-request' | 'relay:connect-accept' | 'relay:connect-deny' | 'file:offer' | 'file:accept' | 'file:reject' | 'file:relay-ready' | 'file:done' | 'file:error' | 'file:cancel' | 'relay:blob:create' | 'relay:blob:grant' | 'relay:blob:deny' | 'relay:blob:fetch' | 'relay:blob:done';
+type VoleNetMessageType = 'ping' | 'pong' | 'discover' | 'discover:response' | 'auth:challenge' | 'auth:response' | 'auth:result' | 'task:delegate' | 'task:result' | 'task:status' | 'memory:sync' | 'memory:search' | 'memory:results' | 'session:sync' | 'tool:list' | 'tool:list:response' | 'tool:call' | 'tool:result' | 'leader:heartbeat' | 'leader:claim' | 'leader:ack' | 'chat:message' | 'sealed' | 'sealed:direct' | 'relay:deliver' | 'room:create' | 'room:join' | 'room:leave' | 'room:invite' | 'room:list' | 'room:list:response' | 'room:info' | 'room:members' | 'room:error' | 'relay:error' | 'relay:ack' | 'relay:pending' | 'roster' | 'relay:connect-request' | 'relay:connect-accept' | 'relay:connect-deny' | 'file:offer' | 'file:accept' | 'file:reject' | 'file:relay-ready' | 'file:done' | 'file:error' | 'file:cancel' | 'relay:blob:create' | 'relay:blob:grant' | 'relay:blob:deny' | 'relay:blob:fetch' | 'relay:blob:done';
 interface VoleNetMessage {
     version: number;
     id: string;
@@ -249,6 +249,11 @@ declare class VoleNetTransport {
      */
     start(): Promise<void>;
     /** Bind the listening port, retrying briefly on EADDRINUSE (covers restart races). */
+    /**
+     * The port actually bound, which is not always the one configured — a host may pass 0 and let
+     * the OS choose. Null before the server is listening.
+     */
+    getPort(): number | null;
     private listen;
     /**
      * Stop the transport.
@@ -703,6 +708,55 @@ declare class RemoteTaskManager {
     dispose(): void;
 }
 
+/** The size past which sealing per member stops being sensible. Enforced by the hub at join. */
+declare const MAX_ROOM_MEMBERS = 64;
+/** How long a room with nobody in it is kept before the hub forgets it. */
+declare const EMPTY_ROOM_TTL_MS: number;
+interface RoomRecord {
+    id: string;
+    name: string;
+    topic?: string;
+    /** Instance ids. Keys are looked up from the hub's own directory when a room is described. */
+    members: string[];
+    createdAt: number;
+    /** When the room last had a member, so an abandoned one can be forgotten. */
+    lastOccupied: number;
+}
+/** A room as a member sees it: enough to fan out a post without asking anything further. */
+interface RoomMember {
+    instanceId: string;
+    name: string;
+    publicKey: string;
+    xPublicKey?: string;
+    mlkemPublicKey?: string;
+}
+interface RoomInfo {
+    room: string;
+    name: string;
+    topic?: string;
+    members: RoomMember[];
+}
+type RoomError = 'full' | 'not-a-member' | 'no-such-room' | 'refused';
+/** The hub's side: who is in what. Persisted, so a restart does not dissolve every room. */
+declare class RoomStore {
+    private readonly file;
+    private rooms;
+    private writing;
+    constructor(file: string);
+    load(now?: number): Promise<void>;
+    get(id: string): RoomRecord | undefined;
+    list(): RoomRecord[];
+    /** Rooms this member belongs to. */
+    forMember(instanceId: string): RoomRecord[];
+    create(name: string, creator: string, topic?: string): Promise<RoomRecord>;
+    /** Add a member. The ceiling is the design's edge, so it is refused rather than stretched. */
+    join(id: string, instanceId: string): Promise<RoomRecord | RoomError>;
+    leave(id: string, instanceId: string): Promise<RoomRecord | RoomError>;
+    /** Drop rooms nobody has been in for the TTL. */
+    sweep(now?: number): Promise<RoomRecord[]>;
+    private persist;
+}
+
 /**
  * VoleNet Sync — memory and session synchronization across peers.
  *
@@ -1048,6 +1102,17 @@ interface VoleNetConfig {
      * live-only, which is the right default for a library.
      */
     persistPeer?: (url: string) => Promise<void>;
+    /**
+     * Remember a peer entry that has no url — one named by identity, as an address-less peer must
+     * be. Separate from `persistPeer` rather than widening it, so a host written against the
+     * earlier callback keeps working.
+     */
+    persistPeerEntry?: (entry: {
+        id?: string;
+        name?: string;
+        trust?: string;
+        allowBrain?: boolean;
+    }) => Promise<void>;
     peers?: Array<{
         /**
          * Where to reach this peer. Also how the entry is matched to a connected peer, by
@@ -1202,6 +1267,20 @@ interface VoleNetConfig {
      */
     files?: VoleNetFilesConfig;
 }
+/**
+ * What a peer asks for when it introduces itself, beyond being trusted at all.
+ *
+ * Trust and permission are separate — the keystore says who may connect, `net.peers` says what
+ * they may then do — and that split used to mean the operator accepted a pair request and then,
+ * separately, hand-edited a config file to make the peer useful. A requester can now say what it
+ * is for, so accepting is one decision made with the reason in front of you.
+ */
+type PairWant = 'brain';
+/** What the operator grants when accepting. Absent means trust only, as before. */
+interface PairGrant {
+    trust?: 'full' | 'tool' | 'read';
+    allowBrain?: boolean;
+}
 /** A hub-vouched mesh member, learned from a relay hub's roster broadcast. */
 interface RosterMember {
     instanceId: string;
@@ -1260,6 +1339,10 @@ declare class VoleNetManager {
     private relayNotices;
     /** Brain answers whose asker had gone by the time they were ready — see result-outbox.ts. */
     private resultOutbox;
+    /** Hub side: who is in which room (§7c). Only a relay hub keeps these. */
+    private roomStore;
+    /** Member side: rooms this node is in, as the hub last described them. */
+    private rooms;
     /** Peers a flush is already running for, so a burst of pings does not send an answer twice. */
     private flushingResults;
     /** The polling timers waiting on delegated tasks, so stopping cancels them. */
@@ -1448,6 +1531,36 @@ declare class VoleNetManager {
     private rosterName;
     private findRosterMember;
     /** Hub: push the current member directory to every connected member. */
+    /** Rooms this node is in, as its hub last described them. */
+    getRooms(): RoomInfo[];
+    /** Ask a hub to make a room, join one, leave one, invite to one, or list what it has. */
+    roomCommand(hubRef: string, type: 'room:create' | 'room:join' | 'room:leave' | 'room:invite' | 'room:list', payload: Record<string, unknown>): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /**
+     * Post to a room: one sealed copy per member.
+     *
+     * There is no room key, so this is the fan-out itself — the same `chat:message` sealed to each
+     * member in turn (§7c). Everything §7 gives a private message therefore applies to each copy:
+     * a member who is away has theirs held in this node's outbox and delivered when they return,
+     * and consent still gates whether they accept anything from us at all.
+     */
+    postToRoom(roomId: string, text: string): Promise<{
+        ok: boolean;
+        sent: number;
+        held: number;
+        skipped: number;
+        error?: string;
+    }>;
+    /** Act on a member's room command and answer it. */
+    private handleRoomCommand;
+    /** A room as its members need to see it: ids *and keys*, since a sender fans out itself. */
+    private describeRoom;
+    /** Tell everyone in a room who is in it now. */
+    private pushRoomMembers;
+    /** Signed, unsealed, straight to one member. Room control is hub business, not private. */
+    private sendToMember;
     private broadcastRoster;
     /** Hand a member that just reconnected everything the hub noted for it while it was away. */
     private sendRelayNotices;
@@ -1537,12 +1650,22 @@ declare class VoleNetManager {
         name: string;
         endpoint?: string;
         note?: string;
+        wants?: PairWant[];
         ts: number;
     }>;
     /** Operator consent: trust the requester's pinned key, live-reload, dial back if possible. */
-    acceptPair(ref: string): Promise<{
+    /**
+     * Accept a pair request, and optionally grant what it asked for in the same act.
+     *
+     * Trusting a key and saying what that key may do were two steps in two places — the second a
+     * hand-edited config file and a restart — which is why a paired peer so often sat there unable
+     * to do the thing it was paired for. A grant writes a `net.peers` entry naming the peer's
+     * identity, live, so it applies without a restart, and asks the host to remember it.
+     */
+    acceptPair(ref: string, grant?: PairGrant): Promise<{
         ok: boolean;
         name?: string;
+        granted?: PairGrant;
         error?: string;
     }>;
     denyPair(ref: string): Promise<{
@@ -1574,7 +1697,7 @@ declare class VoleNetManager {
      * fingerprint client-side), persist + dial the peer, and file the pair request for
      * the other operator. Fully live — no restart needed on this side.
      */
-    initiatePair(url: string, publicKey: string, note?: string): Promise<{
+    initiatePair(url: string, publicKey: string, note?: string, wants?: PairWant[]): Promise<{
         ok: boolean;
         pending?: boolean;
         alreadyTrusted?: boolean;
@@ -1670,4 +1793,4 @@ declare function upsertPeerUrl(peers: PeerEntry[], url: string): {
     replaced?: string;
 };
 
-export { CONTROL_PLANE_PAWS, type ChatEntry, ChatOutbox, DEFAULT_NOTICE_TTL_MS, DEFAULT_OUTBOX_TTL_MS, DEFAULT_RESULT_TTL_MS, type EventBus, type EventSink, type LeaderState, type Logger, type LoggerFactory, MAX_RESULTS_PER_PEER, type MemorySearchRequest, type MemorySearchResult, type MemorySyncEntry, type OutboxEntry, type OutboxKind, type PendingResult, type RelayNotice, RelayNotices, RemoteTaskManager, type RemoteTaskRequest, type RemoteTaskResult, type RemoteToolCallRequest, type RemoteToolCallResult, type RemoteToolInfo, ResultOutbox, type RosterMember, type SealedBox, type SessionSyncEntry, type SharedToolDefinition, type SharedToolEntry, type ToolProvider, type VoleKeyPair, type VoleNetConfig, VoleNetDiscovery, type VoleNetInstance, VoleNetLeader, VoleNetManager, type VoleNetMessage, type VoleNetMessageType, VoleNetSync, VoleNetTransport, addRelayAccept, buildAdvertisedEndpoint, closeLogger, createEventBus, createLogger, createMessage, findEndpointDrift, generateKeyPair, isControlPlanePaw, isSharedTool, loadAuthorizedVoles, loadKeyPair, loadRelayAccepts, parsePublicKey, peerPrefix, removeRelayAccept, revokePeer, seal, setLoggerFactory, trustPeer, unseal, upsertPeerUrl, verifyMessage, withVerifiedCaller };
+export { CONTROL_PLANE_PAWS, type ChatEntry, ChatOutbox, DEFAULT_NOTICE_TTL_MS, DEFAULT_OUTBOX_TTL_MS, DEFAULT_RESULT_TTL_MS, EMPTY_ROOM_TTL_MS, type EventBus, type EventSink, type LeaderState, type Logger, type LoggerFactory, MAX_RESULTS_PER_PEER, MAX_ROOM_MEMBERS, type MemorySearchRequest, type MemorySearchResult, type MemorySyncEntry, type OutboxEntry, type OutboxKind, type PairGrant, type PairWant, type PendingResult, type RelayNotice, RelayNotices, RemoteTaskManager, type RemoteTaskRequest, type RemoteTaskResult, type RemoteToolCallRequest, type RemoteToolCallResult, type RemoteToolInfo, ResultOutbox, type RoomError, type RoomInfo, type RoomMember, type RoomRecord, RoomStore, type RosterMember, type SealedBox, type SessionSyncEntry, type SharedToolDefinition, type SharedToolEntry, type ToolProvider, type VoleKeyPair, type VoleNetConfig, VoleNetDiscovery, type VoleNetInstance, VoleNetLeader, VoleNetManager, type VoleNetMessage, type VoleNetMessageType, VoleNetSync, VoleNetTransport, addRelayAccept, buildAdvertisedEndpoint, closeLogger, createEventBus, createLogger, createMessage, findEndpointDrift, generateKeyPair, isControlPlanePaw, isSharedTool, loadAuthorizedVoles, loadKeyPair, loadRelayAccepts, parsePublicKey, peerPrefix, removeRelayAccept, revokePeer, seal, setLoggerFactory, trustPeer, unseal, upsertPeerUrl, verifyMessage, withVerifiedCaller };