@serfab/cadre-core 1.6.0 → 1.7.0

package/dist/strand-peer-book-protocol.js

@@ -0,0 +1,360 @@
+/**
+ * The strand peer book SWAP protocol, `/sereus/strand-peers/1.0.0`, on the STRAND
+ * libp2p node: when two strand peers connect, each sends the other the signed
+ * entries of its strand peer book (`strand-peer-book.ts`) — its own current
+ * addresses, self-signed, plus the freshest signed entry it holds for every other
+ * peer of the strand — and merges what comes back. That closes the two gaps the
+ * node-local book alone leaves: a peer whose relay reservation or address ROTATES is
+ * known to the others by its old address only until they happen to reconnect, and in
+ * a strand of three or more parties a late joiner holds an address only for the party
+ * that invited it. After one swap it holds everyone's.
+ *
+ * Wire shape, modeled on `strand-addr-protocol.ts`: 4-byte big-endian length-prefixed
+ * JSON frames over one stream, one request → one response, the shared
+ * `control-stream.ts` primitives, a read timeout and a concurrency cap on the
+ * receiver, and a {@link MAX_BOOK_FRAME_SIZE} cap on what either side buffers.
+ * Request and response are the same {@link StrandPeerBookFrame}. Only SIGNED entries
+ * ever travel: an entry this node observed or a formation carried is its own
+ * observation, not the peer's statement, and is never forwarded.
+ *
+ * ── Whose signature ──
+ *
+ * Each entry is signed by the named peer's own STRAND TRANSPORT key
+ * (`strand-transport-key.ts`, the key its strand libp2p node runs under), over the
+ * canonical JSON of `{ v: 1, strandId, peerId, addrs, issuedAt }`. Verification needs
+ * no key exchange: an Ed25519 libp2p peer id embeds its public key, so any receiver
+ * checks that the entry for peer X was signed by X. NOT the strand member key, for
+ * four reasons:
+ *
+ * 1. Open strands have no shared member key at all, and the book has to work there.
+ * 2. A member-key signature proves only "some member said this", so any member could
+ *    forge another member's address and cost every peer a 14 s relayed dial per
+ *    launch; a self-signature is a claim only the named peer can make.
+ * 3. On a closed strand the member key is shared by every machine of a party, so it
+ *    cannot identify a machine anyway.
+ * 4. Membership is a separate question, judged at the connection by the revocation
+ *    gate today (`strand-revocation-enforcer.ts`) and by the allowlist later
+ *    (`feat-strand-member-allowlist-admission`); this protocol rides that gate
+ *    (`node.handle` → `authorizeInboundStream` on a closed strand).
+ *
+ * **The book therefore proves "this peer's own claim about where it is", never "this
+ * peer is a member of the strand".** An address grants no authority (the dialed peer
+ * authenticates by peer id at the handshake), so the worst a forged or stale entry
+ * costs is a failed dial, and a self-signature is exactly what bounds who can impose
+ * that cost on whom.
+ *
+ * ── Clocks ──
+ *
+ * `issuedAt` is the signer's clock. It is compared only between entries from the
+ * SAME signer (the store's merge rule), so skew between machines is harmless — except
+ * that a far-future stamp would pin an entry forever, hence the
+ * {@link STRAND_PEER_ISSUED_AT_SKEW_MS} ceiling (reject and log). The store ages an
+ * entry from `max(issuedAt, lastSeenAt)`, so a signer far in the past ages out fast,
+ * which is the right failure for a machine with a broken clock.
+ */
+import debug from 'debug';
+import { peerIdFromString } from '@libp2p/peer-id';
+import { toString as uint8ArrayToString, fromString as uint8ArrayFromString } from 'uint8arrays';
+import { canonicalJson } from './canonical-json.js';
+import { exchangeFrame, readStreamToEnd, withDeadline, writeFrame } from './control-stream.js';
+import { decodeLengthPrefixedFrame } from './seed-bootstrap.js';
+import { groupAddrsByPeerId } from './peer-addr-book.js';
+import { MAX_STRAND_ADDRS } from './strand-formation-protocol.js';
+import { MAX_STRAND_PEERS } from './strand-peer-book.js';
+const log = debug('sereus:cadre:strand-peer-book-protocol');
+/** Protocol id of the strand peer book swap, registered on every running strand node. */
+export const STRAND_PEER_BOOK_PROTOCOL = '/sereus/strand-peers/1.0.0';
+/** Version tag inside every signed payload, so a later payload shape cannot verify as this one. */
+export const SIGNED_STRAND_PEER_ENTRY_VERSION = 1;
+/**
+ * How far ahead of the receiver's clock a signed entry's `issuedAt` may be. Skew
+ * between honest machines is seconds; a stamp further ahead than this is a broken
+ * clock or an attempt to pin an entry, and is rejected rather than held.
+ */
+export const STRAND_PEER_ISSUED_AT_SKEW_MS = 5 * 60 * 1000;
+/**
+ * Cap on one frame's bytes. A typical full frame — {@link MAX_STRAND_PEERS} entries of
+ * {@link MAX_STRAND_ADDRS} addresses at roughly 150 bytes each, plus a peer id and
+ * signature per entry — is about 40 KiB, but nothing bounds a multiaddr's length (a
+ * long DNS name can take one past 300 bytes), so a sender trims its forwarded
+ * entries to fit ({@link trimBookFrameToFit}) rather than trusting the arithmetic;
+ * {@link assertBookFrameFits} is then the invariant check.
+ */
+export const MAX_BOOK_FRAME_SIZE = 64 * 1024;
+/** Default time the receiver waits for the inbound request frame before aborting (ms). */
+const DEFAULT_READ_TIMEOUT_MS = 10000;
+/** Default time the client waits for the whole exchange (ms). */
+const DEFAULT_EXCHANGE_TIMEOUT_MS = 10000;
+/** Default cap on concurrent inbound swap streams a single strand node serves. */
+const DEFAULT_MAX_CONCURRENT = 100;
+/** The bytes a signed entry's signature covers. */
+export function signedStrandPeerEntryPayload(strandId, entry) {
+    return new TextEncoder().encode(canonicalJson({
+        v: SIGNED_STRAND_PEER_ENTRY_VERSION,
+        strandId,
+        peerId: entry.peerId,
+        addrs: entry.addrs,
+        issuedAt: entry.issuedAt
+    }));
+}
+/**
+ * Sign this node's own entry with its strand transport key. `addrs` must already be
+ * bound to the key's peer id (`dialableAddrs` in `strand-peer-observer.ts` does that);
+ * a receiver rejects an entry whose addresses do not all attribute to the signer.
+ */
+export async function signStrandPeerEntry(privateKey, strandId, addrs, issuedAt) {
+    if (privateKey.type !== 'Ed25519') {
+        throw new Error(`signStrandPeerEntry requires an Ed25519 key, got ${privateKey.type}`);
+    }
+    const peerId = privateKey.publicKey.toString();
+    const entry = { peerId, addrs: [...addrs], issuedAt };
+    const sig = await privateKey.sign(signedStrandPeerEntryPayload(strandId, entry));
+    return { ...entry, sig: uint8ArrayToString(sig, 'base64url') };
+}
+/**
+ * Verify one received entry: well-formed, an Ed25519 peer id, every address bound to
+ * that peer id, `issuedAt` not further ahead of `now` than the skew ceiling, and a
+ * valid self-signature. Never throws: junk from a peer is a verdict, not an error.
+ */
+export async function verifySignedStrandPeerEntry(strandId, raw, now) {
+    const shaped = shapeEntry(raw);
+    if (typeof shaped === 'string') {
+        return { ok: false, reason: shaped };
+    }
+    let publicKey;
+    try {
+        const peerId = peerIdFromString(shaped.peerId);
+        if (peerId.type !== 'Ed25519') {
+            return { ok: false, reason: `peer id ${shaped.peerId} is ${peerId.type}, not Ed25519` };
+        }
+        publicKey = peerId.publicKey;
+    }
+    catch (error) {
+        return { ok: false, reason: `peer id ${shaped.peerId} does not parse: ${error.message}` };
+    }
+    const attributed = groupAddrsByPeerId([...shaped.addrs]).get(shaped.peerId)?.length ?? 0;
+    if (attributed !== shaped.addrs.length) {
+        return { ok: false, reason: `${shaped.addrs.length - attributed} addr(s) do not attribute to ${shaped.peerId}` };
+    }
+    if (shaped.issuedAt > now + STRAND_PEER_ISSUED_AT_SKEW_MS) {
+        return { ok: false, reason: `issuedAt ${shaped.issuedAt} is more than ${STRAND_PEER_ISSUED_AT_SKEW_MS} ms ahead of now` };
+    }
+    try {
+        const sig = uint8ArrayFromString(shaped.sig, 'base64url');
+        if (!(await publicKey.verify(signedStrandPeerEntryPayload(strandId, shaped), sig))) {
+            return { ok: false, reason: `signature does not verify for ${shaped.peerId}` };
+        }
+    }
+    catch (error) {
+        return { ok: false, reason: `signature unusable for ${shaped.peerId}: ${error.message}` };
+    }
+    return { ok: true, entry: shaped };
+}
+/** Structural check of untrusted JSON: the fields, their types, the address cap. */
+function shapeEntry(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return 'entry is not an object';
+    const { peerId, addrs, issuedAt, sig } = raw;
+    if (typeof peerId !== 'string' || peerId.length === 0)
+        return 'peerId is not a string';
+    if (!Array.isArray(addrs) || addrs.some((addr) => typeof addr !== 'string' || addr.length === 0)) {
+        return `addrs of ${peerId} is not a list of strings`;
+    }
+    if (addrs.length > MAX_STRAND_ADDRS)
+        return `${peerId} lists ${addrs.length} addrs, over the cap of ${MAX_STRAND_ADDRS}`;
+    if (!Number.isSafeInteger(issuedAt) || issuedAt < 0)
+        return `issuedAt of ${peerId} is not a timestamp`;
+    if (typeof sig !== 'string' || sig.length === 0)
+        return `sig of ${peerId} is not a string`;
+    // A duplicate address is not a protocol error, but the store de-duplicates and the
+    // attribution count above compares lengths, so collapse it here.
+    return { peerId, addrs: [...new Set(addrs)], issuedAt: issuedAt, sig };
+}
+/**
+ * Verify a whole received frame. A frame-level violation — the wrong strand, entries
+ * not a list, more entries than {@link MAX_STRAND_PEERS} — throws, and the caller
+ * refuses the frame. An entry that fails {@link verifySignedStrandPeerEntry} is
+ * dropped INDIVIDUALLY with a debug line; its siblings are kept. An entry naming
+ * `selfPeerId` is dropped too: this node's own statement is authoritative locally
+ * and a remote copy of it is at best redundant. One entry per peer id (the first).
+ */
+export async function verifyStrandPeerBookFrame(strandId, raw, selfPeerId, now) {
+    if (typeof raw !== 'object' || raw === null) {
+        throw new Error('strand peer book frame is not an object');
+    }
+    const { strandId: named, entries } = raw;
+    if (named !== strandId) {
+        throw new Error(`strand peer book frame names strand ${String(named)}, expected ${strandId}`);
+    }
+    if (!Array.isArray(entries)) {
+        throw new Error('strand peer book frame entries is not a list');
+    }
+    if (entries.length > MAX_STRAND_PEERS) {
+        throw new Error(`strand peer book frame carries ${entries.length} entries, over the cap of ${MAX_STRAND_PEERS}`);
+    }
+    const verified = new Map();
+    for (const candidate of entries) {
+        const verdict = await verifySignedStrandPeerEntry(strandId, candidate, now);
+        if (!verdict.ok) {
+            log('strand %s: dropping received entry: %s', strandId, verdict.reason);
+            continue;
+        }
+        if (verdict.entry.peerId === selfPeerId || verified.has(verdict.entry.peerId)) {
+            continue;
+        }
+        verified.set(verdict.entry.peerId, verdict.entry);
+    }
+    return [...verified.values()];
+}
+/** The encoded size of a frame, as {@link writeFrame} would send it (the 4-byte prefix aside). */
+function encodedFrameBytes(frame) {
+    return new TextEncoder().encode(JSON.stringify(frame)).length;
+}
+/**
+ * The frame with its LAST entries dropped until it encodes within
+ * {@link MAX_BOOK_FRAME_SIZE} and {@link MAX_STRAND_PEERS}. Callers list the entries
+ * in the order they would rather keep them (the own entry first, then freshest
+ * first), so what goes is the stalest forwarded statement, and a frame that fits is
+ * returned as is. Dropping an entry is logged: a forwarded peer the recipient never
+ * learns of is worth seeing in a trace.
+ */
+export function trimBookFrameToFit(frame) {
+    let entries = frame.entries.slice(0, MAX_STRAND_PEERS);
+    while (entries.length > 0 && encodedFrameBytes({ strandId: frame.strandId, entries }) > MAX_BOOK_FRAME_SIZE) {
+        entries = entries.slice(0, -1);
+    }
+    if (entries.length === frame.entries.length)
+        return frame;
+    log('strand %s: frame trimmed from %d to %d entr(ies) to fit the caps', frame.strandId, frame.entries.length, entries.length);
+    return { strandId: frame.strandId, entries };
+}
+/**
+ * Refuse to send a frame the receiver would reject: over the entry cap, or over
+ * {@link MAX_BOOK_FRAME_SIZE} once encoded. A caller that built its frame through
+ * {@link trimBookFrameToFit} cannot trip this; it is the invariant check, not a
+ * runtime condition to handle.
+ */
+export function assertBookFrameFits(frame) {
+    if (frame.entries.length > MAX_STRAND_PEERS) {
+        throw new Error(`strand peer book frame carries ${frame.entries.length} entries, over the cap of ${MAX_STRAND_PEERS}`);
+    }
+    const bytes = encodedFrameBytes(frame);
+    if (bytes > MAX_BOOK_FRAME_SIZE) {
+        throw new Error(`strand peer book frame is ${bytes} bytes, over the cap of ${MAX_BOOK_FRAME_SIZE}`);
+    }
+}
+/** Read a stream to EOF and decode its single frame, bounded by `timeoutMs` and the size cap. */
+async function readBookFrame(stream, timeoutMs) {
+    const data = await readStreamToEnd(stream, { maxBytes: MAX_BOOK_FRAME_SIZE, timeoutMs, label: 'Strand peer book' });
+    return JSON.parse(new TextDecoder().decode(decodeLengthPrefixedFrame(data, MAX_BOOK_FRAME_SIZE)));
+}
+/**
+ * Receiver side: registers the protocol on a strand node and, per inbound frame,
+ * verifies and hands over the asker's entries, then answers with the local book.
+ * Registered through `node.handle`, so on a closed strand every inbound stream
+ * passes the revocation gate first — a revoked machine cannot push addresses into
+ * anyone's book.
+ */
+export class StrandPeerBookService {
+    constructor(deps) {
+        this.deps = deps;
+        this.node = null;
+        this.activeStreams = 0;
+        this.readTimeoutMs = deps.readTimeoutMs ?? DEFAULT_READ_TIMEOUT_MS;
+        this.maxConcurrent = deps.maxConcurrent ?? DEFAULT_MAX_CONCURRENT;
+        this.now = deps.now ?? Date.now;
+    }
+    /** In-flight inbound streams. */
+    get activeCount() {
+        return this.activeStreams;
+    }
+    /** Register the handler. Resolves once libp2p has recorded the protocol on the self record. */
+    async initialize(node) {
+        this.node = node;
+        // `runOnLimitedConnection: true`: strand peers reach each other over relayed
+        // (limited) connections as a matter of course, and this is one small frame each way.
+        await node.handle(STRAND_PEER_BOOK_PROTOCOL, (rawStream, rawConnection) => {
+            const remotePeerId = rawConnection.remotePeer.toString();
+            void this.handleStream(rawStream, remotePeerId);
+        }, { runOnLimitedConnection: true });
+        log('[%s] registered %s', this.deps.strandId, STRAND_PEER_BOOK_PROTOCOL);
+    }
+    /** Unregister the handler and release the node reference. */
+    async shutdown() {
+        if (this.node) {
+            await this.node.unhandle(STRAND_PEER_BOOK_PROTOCOL);
+            this.node = null;
+        }
+    }
+    /**
+     * Read the request, merge what verifies, answer with the local book. Every failure
+     * (cap, malformed or oversized frame, wrong strand, read timeout) answers an empty
+     * frame rather than hanging or dropping the stream, so the asker's exchange settles.
+     *
+     * NOTE: the concurrency cap bounds streams in flight, not frames per peer per unit
+     * time — the ten-minute throttle is the CLIENT's, so a connected peer can push a
+     * verified frame, and the persist it costs, as fast as it likes; see
+     * `backlog/debt-strand-peer-book-remote-write-bounds`.
+     */
+    async handleStream(stream, remotePeerId) {
+        if (this.activeStreams >= this.maxConcurrent) {
+            log('[%s] refusing swap from %s: %d streams at the cap', this.deps.strandId, remotePeerId, this.activeStreams);
+            this.reply(stream, []);
+            await closeQuietly(stream);
+            return;
+        }
+        this.activeStreams++;
+        try {
+            const raw = await readBookFrame(stream, this.readTimeoutMs);
+            const entries = await verifyStrandPeerBookFrame(this.deps.strandId, raw, this.deps.selfPeerId, this.now());
+            log('[%s] swap from %s: %d verified entr(ies) received', this.deps.strandId, remotePeerId, entries.length);
+            this.deps.onEntries(entries, remotePeerId);
+            this.reply(stream, this.deps.localEntries(remotePeerId));
+        }
+        catch (error) {
+            log('[%s] swap from %s failed: %o', this.deps.strandId, remotePeerId, error);
+            this.reply(stream, []);
+        }
+        finally {
+            this.activeStreams--;
+            await closeQuietly(stream);
+        }
+    }
+    reply(stream, entries) {
+        try {
+            const frame = { strandId: this.deps.strandId, entries };
+            assertBookFrameFits(frame);
+            writeFrame(stream, frame);
+        }
+        catch (error) {
+            log('[%s] swap reply failed: %o', this.deps.strandId, error);
+        }
+    }
+}
+async function closeQuietly(stream) {
+    try {
+        await stream.close();
+    }
+    catch (error) {
+        log('stream close failed (ignored): %o', error);
+    }
+}
+/**
+ * Client side: open one stream on `connection` — the live connection to the peer,
+ * relayed or not — send `request`, and return the peer's VERIFIED entries. Throws on
+ * any failure (the peer does not speak the protocol, a deadline, a refused frame);
+ * the caller logs and moves on, never retrying before its throttle expires.
+ */
+export async function exchangeStrandPeerBook(connection, request, options) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_EXCHANGE_TIMEOUT_MS;
+    const remotePeerId = connection.remotePeer.toString();
+    assertBookFrameFits(request);
+    // One deadline for the stream open and the exchange together: its signal aborts the
+    // negotiation and resets a live stream, so neither leaks on a timeout.
+    const raw = await withDeadline(timeoutMs, `Strand peer book swap with ${remotePeerId}`, async (signal) => {
+        const stream = await connection.newStream(STRAND_PEER_BOOK_PROTOCOL, { runOnLimitedConnection: true, signal });
+        return exchangeFrame(stream, signal, request, (s) => readBookFrame(s, timeoutMs), 'Strand peer book swap aborted by timeout');
+    });
+    return verifyStrandPeerBookFrame(request.strandId, raw, options.selfPeerId, (options.now ?? Date.now)());
+}
+//# sourceMappingURL=strand-peer-book-protocol.js.map

package/dist/strand-peer-book-protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strand-peer-book-protocol.js","sourceRoot":"","sources":["../src/strand-peer-book-protocol.ts"],"names":[],"mappings":"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"}

package/dist/strand-peer-book-swap.d.ts

@@ -0,0 +1,104 @@
+import type { Libp2p, PrivateKey } from '@libp2p/interface';
+import type { StrandPeerBookStore } from './strand-peer-book.js';
+import { type SignedStrandPeerEntry } from './strand-peer-book-protocol.js';
+/** Minimum gap between two exchanges with ONE peer, unless this node's own entry was re-signed. */
+export declare const STRAND_PEER_BOOK_SWAP_THROTTLE_MS: number;
+/** How long after the last `self:peer:update` the own entry is rebuilt — the event fires in bursts. */
+export declare const OWN_ENTRY_RESIGN_DEBOUNCE_MS = 1000;
+export interface StrandPeerBookSwapDeps {
+    strandId: string;
+    /** The strand's libp2p node. */
+    libp2p: Libp2p;
+    /** This strand network's `/optimystic/<networkName>` prefix — the block-transfer gate. */
+    protocolPrefix: string;
+    /** The node-local book this strand's entries live in. */
+    store: StrandPeerBookStore;
+    /**
+     * The strand transport key the node runs under. Absent — or not the node's own
+     * key — means no own entry is signed; the node still receives and forwards.
+     */
+    privateKey?: PrivateKey;
+    /** The host's declared link round trip, for the exchange deadline (`link-budget.ts`). */
+    linkRoundTripMs?: number;
+}
+export interface StrandPeerBookSwapOptions {
+    /** Default {@link STRAND_PEER_BOOK_SWAP_THROTTLE_MS}. */
+    throttleMs?: number;
+    /** Default {@link OWN_ENTRY_RESIGN_DEBOUNCE_MS}. */
+    debounceMs?: number;
+    /** Whole-exchange deadline; default derived from `linkRoundTripMs`. */
+    timeoutMs?: number;
+    /** Clock, for tests. Default `Date.now`. */
+    now?: () => number;
+}
+export declare class StrandPeerBookSwap {
+    private readonly deps;
+    private readonly service;
+    private readonly selfPeerId;
+    private readonly signingKey;
+    private readonly throttleMs;
+    private readonly debounceMs;
+    private readonly timeoutMs;
+    private readonly now;
+    /** Last exchange per peer id, for the throttle. */
+    private readonly exchangedAt;
+    /** Peers with an exchange in flight, so identify and a walk cannot double up. */
+    private readonly inFlight;
+    /**
+     * Peers whose in-flight exchange carries a since-replaced own entry: one more
+     * exchange follows the moment it settles. Without this a re-sign that lands while
+     * the identify exchange is still on the wire — the relay reservation arriving a
+     * second after the bootstrap dials do, which is routine — would never reach that
+     * peer until the next connection.
+     */
+    private readonly resendAfter;
+    private own;
+    /** The address set the own entry was signed over, canonicalised for comparison. */
+    private ownAddrKey;
+    /** Serialises own-entry refreshes: a burst of triggers signs at most once per change. */
+    private selfChain;
+    private debounceTimer;
+    private readonly onPeerIdentify;
+    private readonly onSelfUpdate;
+    private started;
+    private stopped;
+    constructor(deps: StrandPeerBookSwapDeps, options?: StrandPeerBookSwapOptions);
+    /** This node's current signed entry, or `undefined` before the first signing or without a key. */
+    get ownEntry(): SignedStrandPeerEntry | undefined;
+    /**
+     * Register the receiver, subscribe, sign the own entry, and exchange with the strand
+     * peers already connected — identify for an early peer may have fired before this
+     * object existed.
+     */
+    start(): void;
+    /** Unsubscribe and unregister; an exchange in flight finishes on its own. */
+    stop(): Promise<void>;
+    /** A strand peer that also speaks the swap; never self. */
+    private isSwapPeer;
+    private queueSelfRefresh;
+    /** Re-sign the own entry if the address set changed, then exchange — unthrottled after a re-sign. */
+    private refreshSelf;
+    /** Returns whether a new own entry was signed. */
+    private refreshOwnEntry;
+    /** The greatest `issuedAt` this node has signed: in memory, else the stored own entry's, else 0. */
+    private lastOwnIssuedAt;
+    /** Exchange with every connected, identified strand peer that speaks the swap. */
+    private exchangeWithConnected;
+    /**
+     * One exchange with one peer over `connection`, throttled unless told otherwise (a
+     * re-sign) — in which case an exchange already in flight, which carries the old
+     * entry, is followed by one more once it settles. Never throws.
+     */
+    private exchangeWith;
+    /**
+     * What this node sends `remotePeerId`: its own entry first, then every signed entry
+     * held for anyone else, freshest first, minus the recipient's own — trimmed from the
+     * stale end to the frame's entry and byte caps (the own entry can push the store's
+     * cap over by one, and long addresses can push the bytes over).
+     */
+    private frameFor;
+    /** File verified entries: the sender's own as seen now, a forwarded third party's as never seen. */
+    private accept;
+    /** Fire-and-log, like every book write: visible synchronously, the promise tracks durability. */
+    private remember;
+}