@dcasegr/skein 0.0.0-stage → 0.1.2

package/dist/host/p2p.d.ts

@@ -0,0 +1,337 @@
+import type { Libp2p, PeerId } from "@libp2p/interface";
+import type { PrivateKey } from "@bsv/sdk";
+import type { Store } from "../runtime/store.ts";
+import { CID } from "multiformats/cid";
+import { Liveness, type Live, type LiveBeat } from "./liveness.ts";
+export type DhtMode = "off" | "client" | "server";
+/** The host-wide settings: every node gets these. */
+export interface P2PHostConfig {
+    listen: string[];
+    bootstrap: string[];
+    dht: DhtMode;
+    relays: string[];
+    mdns: boolean;
+    /** PEM certificate and key for the WebSocket listener (WSS). */
+    tls?: {
+        cert: string;
+        key: string;
+    };
+}
+/** One instance's libp2p config (the genesis's `libp2p`): what the router subscribes and serves for it. */
+export interface P2PInstanceConfig {
+    topics: string[];
+    protocols: string[];
+    /** This instance's listen addresses (over the host's): a fixed port belongs to one node. */
+    listen?: string[];
+}
+/** The default listeners: loopback TCP and WebSocket, ports chosen by the OS (plain WS on loopback: dev only). */
+export declare const DEFAULT_LISTEN: string[];
+/** What the front door is called with for an inbound message or stream frame (#51). */
+export interface InboundCall {
+    transport: "libp2p";
+    topic?: string;
+    protocol?: string;
+    /** The publisher's peer ID (topics) or the remote peer's (streams): its multihash bytes. */
+    from: Uint8Array;
+    seqno?: Uint8Array;
+    signature?: Uint8Array;
+    body: Uint8Array;
+}
+/** The front door's answer: the verdict for GossipSub; for a stream frame, what to write back and whether to close. */
+export interface InboundAnswer {
+    verdict: "accept" | "reject" | "ignore";
+    body?: Uint8Array;
+    close?: boolean;
+    reason?: string;
+}
+/** A frame read from a dialled stream, or its end. */
+export type Frame = {
+    body: Uint8Array;
+} | {
+    closed: true;
+    error?: string;
+};
+/** The stream protocol a signed message travels on to an instance (#70). */
+export declare const MESSAGE_PROTOCOL = "/skein/message/1.0.0";
+/**
+ * The overlay's receive row (skein-overlay etc/app.json; the settled sync design, David 2026-10-30):
+ * the host's OWN entry for the BEEFs it fetched (sync.ts `deliver` → Router.p2pInbound), never served
+ * to peers ("not a good door to have": a node takes BEEFs only from paths it chose). Whatever rows an
+ * instance declares, no node handles it inbound.
+ */
+export declare const RECEIVE_PROTOCOL = "/skein/overlay/beef/1.0.0";
+export interface P2POptions {
+    host: P2PHostConfig;
+    /** The instance's peer key (signer.ts peerKey). */
+    keyOf(handle: string): PrivateKey;
+    /** One front-door call for an inbound message or frame (Router.p2pInbound). */
+    inbound(handle: string, call: InboundCall): Promise<InboundAnswer>;
+    log?(source: string, line: string): void;
+    /**
+     * Signs `data` with the instance's signer (#126 beacons), as the host signs
+     * an intention request (Router's `sign`: [2, "metanet handles envelope"],
+     * key ID `send`, counterparty anyone). With `identity` (the instance's
+     * identity key, 33 bytes). Absent: a beacon publishes nothing.
+     */
+    sign?(handle: string, data: Uint8Array): Promise<Uint8Array>;
+    identity?(handle: string): Promise<Uint8Array | undefined>;
+    /** How often topics are re-advertised and looked up in the DHT, and bootstrap peers redialled (ms). */
+    discoveryMs?: number;
+    /**
+     * Protocols the host itself serves on every node, beside /skein/message/1.0.0: each inbound frame
+     * answered by the handler, its answer written back; nothing reaches the front door. (The router
+     * names none: the overlay's sync, its one user under #150, is a row an app declares since #154.)
+     */
+    hostProtocols?: Record<string, (handle: string, remote: PeerId, frame: Uint8Array) => Promise<Uint8Array>>;
+    /** Each beat the liveness tool newly keeps from another peer (shruggr/skein#150). */
+    beat?(handle: string, topic: string, beat: LiveBeat): void;
+}
+/** A bsv secp256k1 key as a libp2p private key. */
+export declare function libp2pKey(k: PrivateKey): import("@libp2p/interface").PrivateKey;
+/** The peer ID of a key: the identity multihash of its protobuf (secp256k1, compressed). */
+export declare function peerIdOf(k: PrivateKey): PeerId;
+/** The compressed secp256k1 key a peer ID embeds (hex), or undefined for another kind. */
+export declare function keyOfPeerId(id: string | Uint8Array): string | undefined;
+/** A topic name's rendezvous CID: v1 raw over sha2-256 of the name (go-libp2p's nsToCid). */
+export declare function topicCid(topic: string): Promise<CID>;
+/** The host-wide settings: the environment's SKEIN_LIBP2P_*, else $SKEIN_HOME/host.env's. */
+export declare function hostP2PConfig(vars: Record<string, string | undefined>, home?: string): P2PHostConfig;
+/** The libp2p config a genesis carries (`libp2p: {topics?, protocols?, listen?}`), or undefined: no node. */
+export declare function libp2pOf(g: Record<string, unknown> | null | undefined): P2PInstanceConfig | undefined;
+/**
+ * An instance's libp2p config as it stands (#72, #77): the genesis's
+ * (libp2pOf: a tree names what its node subscribes in `config.libp2p`),
+ * plus the topics and protocols named by the dispatch table's `libp2p`
+ * rows added since the genesis (an app's install; address: a topic) — a
+ * genesis topic row alone subscribes nothing, as a route alone did not — and
+ * every stream protocol a `libp2p` row names (`/<protocol>`), whatever
+ * installed it, the genesis included (#155: an image-born instance serves its
+ * sync row; the overlay's receive row stays unserved, P2PHost), plus the
+ * topics the apps subscribed (#119, `subscribed`).
+ * `beacons` (#126): an app's beacon (or its liveness, #138: P2PHost.liveness
+ * subscribes those topics itself) needs the node, and adds no topic.
+ * Undefined: no node — the genesis declares none and nothing needs one.
+ */
+export declare function libp2pConfig(g: Record<string, unknown> | null | undefined, rows: Array<Record<string, unknown>>, subscribed?: string[], beacons?: boolean): P2PInstanceConfig | undefined;
+export interface Subscription {
+    app: string;
+    topic: string;
+    program: string;
+    fn: string;
+    filter?: string;
+}
+export type SubscriptionEvent = {
+    event: "subscribe";
+    sub: Subscription;
+} | {
+    event: "unsubscribe";
+    app: string;
+    topic: string;
+};
+export declare const isTopic: (t: unknown) => t is string;
+/** A `subscribe` / `unsubscribe` event record, read (subscriptions.zig eventOf); or why it is not one this host follows. */
+export declare function subscriptionEvent(rec: Record<string, unknown>): SubscriptionEvent | {
+    refused: string;
+};
+/** Fold subscription events in order (subscriptions.zig apply). */
+export declare function foldSubscriptions(events: Iterable<SubscriptionEvent>, into?: Subscription[]): Subscription[];
+/** The topics the subscriptions take (each once): what the node subscribes for the apps. */
+export declare const subscribedTopics: (subs: Subscription[]) => string[];
+/**
+ * The subscriptions, folded from the store's log (#119, the host's recovery
+ * at hydrate; subscriptions.zig fold): the `subscribe` / `unsubscribe`
+ * records each step's update lists in `emitted`, in log order — by the entry
+ * the step processed (`input`'s `n`), the step's time, its thread's start,
+ * the thread's CID, its place in the thread and in `emitted`. Read only.
+ */
+export declare function subscriptionsOf(store: Pick<Store, "get" | "chains" | "edges">): Promise<Subscription[]>;
+/**
+ * The beacons standing (#126), folded from the store's log as the
+ * subscriptions are: the `beacon` / `unbeacon` records the steps' updates
+ * list, in log order, keyed by (app, topic). Read only.
+ */
+export declare function beaconsOf(store: Pick<Store, "get" | "chains" | "edges">): Promise<Beacon[]>;
+/**
+ * An emitted event's place in the log (the fold order, subscriptions.zig): the entry its step
+ * processed (`n`, the update's `input`), the step's time (`at`, the update's), its thread (origin),
+ * its place in the thread (`seq`), the event record's place in the update's `emitted` (`i`) and
+ * the record's CID.
+ */
+export interface EmittedAt {
+    n: number;
+    at: number;
+    thread: CID;
+    seq: number;
+    i: number;
+    record: CID;
+}
+/** The event records the steps' updates list in `emitted` that `read` takes, in log order (the kernel's fold order, subscriptions.zig); `read` gets each one's place too. */
+export declare function emittedEvents<T>(store: Pick<Store, "get" | "chains" | "edges">, read: (rec: Record<string, unknown>, place: EmittedAt) => T | undefined): Promise<T[]>;
+export interface Beacon {
+    app: string;
+    topic: string;
+    every: number;
+    body: Uint8Array;
+}
+/**
+ * A beat as published (#126): dag-cbor {body, at, sender, signature}. `at`:
+ * the beat's time (ms since the epoch, the host's clock); `sender`: the
+ * instance's identity key (33 bytes); `signature`: the instance's (DER),
+ * [2, "metanet handles envelope"] / `send` / counterparty anyone, over
+ * sha2-256 of beaconPreimage — dag-cbor {kind: "beacon", topic, body, at,
+ * sender}: the topic is signed, not carried. A receiver checks the signature
+ * (beaconProblem) and `at` against its own clock.
+ */
+export interface BeaconBeat {
+    body: Uint8Array;
+    at: number;
+    sender: Uint8Array;
+    signature: Uint8Array;
+}
+/** What a beat's signature covers. */
+export declare function beaconPreimage(topic: string, b: Omit<BeaconBeat, "signature">): Uint8Array;
+/** A beat's frame for `topic`, signed by `sign` (the instance's signer). */
+export declare function beaconFrame(topic: string, body: Uint8Array, at: number, sender: Uint8Array, sign: (data: Uint8Array) => Promise<Uint8Array>): Promise<Uint8Array>;
+/** A beat read from a frame on `topic`, its signature checked against its sender; or why it is not one. */
+export declare function beaconBeat(topic: string, frame: Uint8Array): BeaconBeat | {
+    problem: string;
+};
+export type BeaconEvent = {
+    event: "beacon";
+    beacon: Beacon;
+} | {
+    event: "unbeacon";
+    app: string;
+    topic: string;
+};
+/** A `beacon` / `unbeacon` event record, read; or why it is not one this host follows. */
+export declare function beaconEvent(rec: Record<string, unknown>): BeaconEvent | {
+    refused: string;
+};
+/** Fold beacon events in order: a beacon replaces the app's own on the topic, an unbeacon removes it. */
+export declare function foldBeacons(events: Iterable<BeaconEvent>, into?: Beacon[]): Beacon[];
+/** The answer to a stream whose first frame names no topic where several instances declare its protocol (#160). */
+export declare const TOPIC_REQUIRED = "topic required";
+export declare class P2PHost {
+    readonly o: P2POptions;
+    /** The liveness tool's state (#138): the apps' liveness and the beats kept, in memory. */
+    readonly live: Liveness;
+    /** The nodes, by peer ID (#160: one per key). */
+    private nodes;
+    /** Each handle's node. */
+    private byHandle;
+    /** Each handle's peer ID, as derived (keyOf). */
+    private ids;
+    /** Each key's declares, in order (one at a time). */
+    private starting;
+    private stopped;
+    constructor(o: P2POptions);
+    private say;
+    /** A node's name in a log line: its one handle (as before #160), else its first. */
+    private nameOf;
+    /** The node of an instance, if it has one. */
+    node(handle: string): Libp2p | undefined;
+    /** An instance's peer ID (derived: whether or not its node runs). */
+    peerId(handle: string): string;
+    /** The handles on `handle`'s node (#160: one in a master-key host; every one sharing its key in a one-key host). */
+    handlesOn(handle: string): string[];
+    /** How many nodes run (#160: one per key). */
+    nodeCount(): number;
+    /** Where an instance's node listens (with /p2p/<id>). */
+    addrs(handle: string): string[];
+    /**
+     * `handle`'s libp2p config is this: its key's node started (once) with its peer key, the handle's
+     * topics subscribed with the validator, its protocols handled. Declared again, the handle is brought
+     * to the new config. No config: the handle leaves its node; the node stops with its last handle.
+     */
+    declare(handle: string, config: P2PInstanceConfig | undefined): Promise<void>;
+    /** The topics and protocols an instance's node serves for it now. */
+    served(handle: string): {
+        topics: string[];
+        protocols: string[];
+    } | undefined;
+    /** Bring `handle` on a running node to `config` (joining it if it is new there): subscribe and handle what is new, unsubscribe and unhandle what no handle takes any more. */
+    private reconfigure;
+    private subscribe;
+    /** The topics `handle` takes: its config's and its apps' liveness topics (#138). */
+    private takes;
+    /** Subscribe what the handles' configs and liveness tools (#138) take, unsubscribe the rest: the topics added and removed. */
+    private resubscribe;
+    /** Handle the protocols the handles declare, unhandle those none declares any more (the host's own aside). */
+    private rehandle;
+    /** The topics `handle`'s node subscribes for it now: its config's and its apps' liveness topics (#138). */
+    listening(handle: string): string[];
+    /**
+     * The liveness `handle`'s apps keep (#138, liveness.ts): the tool keeps it, and the node subscribes
+     * each topic (not admitting its messages) and leaves those no liveness nor config takes. One line
+     * when a topic is taken or left. No node: kept for when it starts.
+     */
+    liveness(handle: string, lives: Live[]): void;
+    /** Whether the host serves `protocol` on every node itself (/skein/message/1.0.0, `hostProtocols`). */
+    private hostServed;
+    private handleHostProtocol;
+    private handleProtocol;
+    private start;
+    /** Keep the bootstrap peers connected; with the DHT on, advertise each topic and dial its providers. */
+    private discover;
+    private pubsub;
+    /**
+     * The topic validator: for every handle on the node that takes the topic, one front-door call (or,
+     * for a topic only its apps' liveness takes, #138, the liveness tool's verdict alone: nothing
+     * admitted); GossipSub's verdict (async: forwarding waits on it) is Accept if any handle accepts,
+     * Reject only if every one rejects, else Ignore (#160).
+     */
+    private validate;
+    /** One handle's verdict on a topic message (the validator as it was per node before #160). */
+    private validateFor;
+    /**
+     * Which handle an inbound stream on `protocol` is for (#160), by its first frame: the handles that
+     * declare the protocol (every handle declares /skein/message/1.0.0); the frame's `topic` (dag-cbor
+     * {topic, …}) picks the one among them that takes it; a frame naming none, or a topic none of them
+     * takes, goes to the one handle that declares the protocol; with several, a problem.
+     */
+    private streamHandle;
+    /** An inbound stream on a handled protocol: its first frame picks the handle (#160); each frame one front-door call, its answer's body written back. */
+    private serve;
+    private nodeOf;
+    /**
+     * The beacons `handle`'s node beats (#126): each a new frame (beaconFrame:
+     * the body, the beat's time, the instance's signature) published on its topic
+     * every `every` ms — the topic not subscribed; nothing logged per beat (a
+     * failed beat is dropped: the next one is the retry). The FIRST beacon on a
+     * topic publishes at once. A beacon REPLACING one (the same app and topic, a
+     * new body and/or `every`; the settled sync design, David 2026-10-30) swaps
+     * what the next beat carries and leaves the timer alone — no publish now, no
+     * reset — unless `every` changed, when the timer is reset to the new
+     * interval (still no publish now). One line when a beacon starts or stops.
+     * No node: nothing beats.
+     */
+    beacons(handle: string, beacons: Beacon[]): void;
+    /** Publish `body` on `topic` from `handle`'s node (signed with its peer key): the message's seqno, and how many peers took it. */
+    publish(handle: string, topic: string, body: Uint8Array): Promise<{
+        seqno: Uint8Array;
+        recipients: number;
+    }>;
+    /** Open a stream from `handle`'s node to a peer (a peer ID, or a multiaddr with /p2p/<id>): its id; each frame read from it, and its end, to `frames`. */
+    dial(handle: string, peer: string, protocol: string, frames: (f: Frame) => void): Promise<number>;
+    /**
+     * One request to a peer on `protocol` (a host protocol, shruggr/skein#150): a stream opened, one
+     * frame written, one frame read back, the stream closed. → the answer's bytes.
+     */
+    request(handle: string, peer: string, protocol: string, body: Uint8Array, timeoutMs?: number): Promise<Uint8Array>;
+    /** The protocols `handle`'s node handles inbound now (the libp2p node's own registry: its rows', the host's, /skein/message/1.0.0). */
+    handledProtocols(handle: string): string[];
+    /** The addresses `handle`'s node knows for `peer` (its peer store), as multiaddr strings. */
+    peerAddrs(handle: string, peer: string): Promise<string[]>;
+    /** Dial `peer` from `handle`'s node, at `addrs` when given (a start's persisted peers), else as the peer store knows it. */
+    connect(handle: string, peer: string, addrs?: string[]): Promise<void>;
+    /** The peers `handle`'s node knows subscribe `topic` (GossipSub's view), as peer ID strings. */
+    subscribers(handle: string, topic: string): string[];
+    /** Write one length-prefixed frame on a dialled stream. */
+    send(handle: string, id: number, body: Uint8Array): Promise<void>;
+    /** Close a dialled stream (our side), and forget it. */
+    close(handle: string, id: number): Promise<void>;
+    /** `handle` leaves its node (its beats stopped, its liveness forgotten); the node stops with its last handle, else follows the handles left. */
+    private drop;
+    stop(): Promise<void>;
+}