@serfab/cadre-core 0.6.0 → 0.8.1

package/dist/control-stream.js

@@ -0,0 +1,104 @@
+/**
+ * Shared control-network stream primitives.
+ *
+ * The cadre control protocols — seed delivery (`seed-bootstrap.ts`), push-wake
+ * (`strand-wake-protocol.ts`), and strand formation (`strand-formation-protocol.ts`)
+ * — all speak 4-byte big-endian length-prefixed JSON frames over a libp2p 3.x
+ * stream. This module lifts the previously-triplicated stream shape, frame
+ * writer, and `withTimeout` wrapper into one place, and adds a timeout-bounded,
+ * abort-on-timeout read-to-EOF helper so a misbehaving peer that opens a stream
+ * and never half-closes its write end cannot pin a receiver forever.
+ *
+ * Dependency-free by design: it imports nothing from the protocol modules, so
+ * the import graph stays acyclic (`control-stream` ← `seed-bootstrap` ←
+ * `strand-wake-protocol`). In particular it returns RAW bytes from
+ * {@link readStreamToEnd} rather than decoding a frame — callers own the
+ * `decodeLengthPrefixedFrame` guard.
+ */
+/** Write a JSON object as a single 4-byte big-endian length-prefixed frame. */
+export function writeFrame(stream, obj) {
+    const body = new TextEncoder().encode(JSON.stringify(obj));
+    const prefix = new Uint8Array(4);
+    new DataView(prefix.buffer).setUint32(0, body.length, false);
+    stream.send(prefix);
+    stream.send(body);
+}
+/**
+ * Reject if `op` does not settle within `ms`. On timeout, invoke `onTimeout`
+ * (used by the sender to abort the in-flight dial/stream so it does not leak)
+ * before rejecting. A throwing `onTimeout` is swallowed so it cannot mask the
+ * timeout rejection. The rejection message is exactly `<label> timed out after
+ * <ms>ms`, so callers fold any domain prefix into `label`.
+ */
+export function withTimeout(ms, label, op, onTimeout) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            try {
+                onTimeout?.();
+            }
+            catch {
+                // Best-effort: a throwing onTimeout must not replace the timeout error.
+            }
+            reject(new Error(`${label} timed out after ${ms}ms`));
+        }, ms);
+        op().then(resolve, reject).finally(() => clearTimeout(timer));
+    });
+}
+/** Normalize a libp2p chunk (Uint8Array or Uint8ArrayList) to a flat Uint8Array. */
+function toBytes(chunk) {
+    return chunk instanceof Uint8Array ? chunk : chunk.subarray();
+}
+/**
+ * Read a stream to EOF, capped at `maxBytes`, bounded by `timeoutMs`, returning
+ * the assembled bytes (the caller decodes via `decodeLengthPrefixedFrame`).
+ *
+ * Implemented as `Promise.race([readLoop, timeout])`:
+ * - The size cap throws synchronously inside `readLoop` (a well-behaved peer may
+ *   have sent a real-but-too-large frame and could still be reading for the ack,
+ *   so this path does NOT abort the stream — it just rejects).
+ * - The timeout path is the true hang: it ALSO calls `stream.abort(err)` to
+ *   release the stuck read. The race guarantees the helper settles at the
+ *   deadline even if `abort()` does not immediately unblock the iterator (e.g. a
+ *   test double whose `abort()` is a no-op).
+ */
+export function readStreamToEnd(stream, opts) {
+    const { maxBytes, timeoutMs, label } = opts;
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            const err = new Error(`${label} read timed out after ${timeoutMs}ms`);
+            // Release the hung read; the race below settles on `err` regardless of
+            // whether abort() promptly unblocks the iterator.
+            try {
+                stream.abort(err);
+            }
+            catch {
+                // Best-effort: a broken/closed stream may reject abort.
+            }
+            reject(err);
+        }, timeoutMs);
+    });
+    const readLoop = collect(stream, maxBytes, label);
+    return Promise.race([readLoop, timeout]).finally(() => clearTimeout(timer));
+}
+/** Accumulate every chunk to EOF, rejecting once the running total exceeds `maxBytes`. */
+async function collect(stream, maxBytes, label) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of stream) {
+        const bytes = toBytes(chunk);
+        chunks.push(bytes);
+        total += bytes.length;
+        if (total > maxBytes) {
+            throw new Error(`${label} message too large: ${total} bytes exceeds max ${maxBytes}`);
+        }
+    }
+    const data = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        data.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return data;
+}
+//# sourceMappingURL=control-stream.js.map

package/dist/control-stream.js.map

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

package/dist/device-token.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Device-token record helpers: the single source of truth for the bytes a node
+ * signs when publishing its own `DeviceToken` row and re-verifies when resolving
+ * another peer's row.
+ *
+ * Modeled directly on {@link peerRecordSignedPayload} (peer-record.ts): the signed
+ * payload is a single SHA-256 digest of a delimited string of the authenticated
+ * fields. It is intentionally NOT JSON-canonicalized — a delimited digest is
+ * trivially deterministic across node/browser/RN (plain string concat + sha256, no
+ * key ordering) and is reconstructable inside the `DeviceToken.AuthorizedUpdate` SQL
+ * constraint from the row's own columns:
+ *
+ *   digest(new.PeerId || '|' || new.Platform || '|' || new.Token || '|'
+ *          || cast(new.UpdatedAt as text))
+ *
+ * Keep {@link deviceTokenSignedPayload} and that constraint byte-for-byte in sync.
+ * The `'|'` delimiter is safe: a base58btc PeerId, a fixed `'fcm'`/`'apns'` platform
+ * string, and a base-10 integer never contain it. The opaque platform token is the
+ * last variable-length field before the integer stamp, so even a token containing a
+ * `'|'` cannot create a collision with a different field split.
+ *
+ * Unlike a peer-address record, a device-token record carries NO public key: the
+ * signature is verified against the `CadrePeer.PublicKey` bound to the same PeerId
+ * (the resolver supplies it), so the key binding is checked exactly once, where the
+ * membership row already lives.
+ */
+import type { DeviceTokenRecord, PushPlatform } from './types.js';
+/**
+ * Build the base64url SHA-256 digest that the self-signature covers. Mirrors the
+ * `DeviceToken.AuthorizedUpdate` constraint exactly; both sides take the default
+ * base64url output of a single `digest(...)`, which round-trips cleanly.
+ */
+export declare function deviceTokenSignedPayload(record: Omit<DeviceTokenRecord, 'sig'>): string;
+/**
+ * Sign a device-token record with the ed25519 private key behind its `peerId`.
+ * Returns a fully-populated {@link DeviceTokenRecord}.
+ *
+ * @param fields - the record fields to sign
+ * @param privateKeyB64 - base64url ed25519 seed (see `authorityKeyFromLibp2p`)
+ */
+export declare function signDeviceTokenRecord(fields: Omit<DeviceTokenRecord, 'sig'>, privateKeyB64: string): DeviceTokenRecord;
+/**
+ * Verify a record's self-signature against the `CadrePeer.PublicKey` (base64url)
+ * bound to its `peerId`. Reconstructs the signed bytes from the record exactly as
+ * {@link signDeviceTokenRecord} produced them. Returns false on a missing key/sig or
+ * any verification failure.
+ */
+export declare function verifyDeviceTokenSignature(record: DeviceTokenRecord, publicKeyB64: string): boolean;
+/** Narrow an arbitrary stored string to a known {@link PushPlatform}. */
+export declare function isPushPlatform(value: string): value is PushPlatform;

package/dist/device-token.js

@@ -0,0 +1,66 @@
+/**
+ * Device-token record helpers: the single source of truth for the bytes a node
+ * signs when publishing its own `DeviceToken` row and re-verifies when resolving
+ * another peer's row.
+ *
+ * Modeled directly on {@link peerRecordSignedPayload} (peer-record.ts): the signed
+ * payload is a single SHA-256 digest of a delimited string of the authenticated
+ * fields. It is intentionally NOT JSON-canonicalized — a delimited digest is
+ * trivially deterministic across node/browser/RN (plain string concat + sha256, no
+ * key ordering) and is reconstructable inside the `DeviceToken.AuthorizedUpdate` SQL
+ * constraint from the row's own columns:
+ *
+ *   digest(new.PeerId || '|' || new.Platform || '|' || new.Token || '|'
+ *          || cast(new.UpdatedAt as text))
+ *
+ * Keep {@link deviceTokenSignedPayload} and that constraint byte-for-byte in sync.
+ * The `'|'` delimiter is safe: a base58btc PeerId, a fixed `'fcm'`/`'apns'` platform
+ * string, and a base-10 integer never contain it. The opaque platform token is the
+ * last variable-length field before the integer stamp, so even a token containing a
+ * `'|'` cannot create a collision with a different field split.
+ *
+ * Unlike a peer-address record, a device-token record carries NO public key: the
+ * signature is verified against the `CadrePeer.PublicKey` bound to the same PeerId
+ * (the resolver supplies it), so the key binding is checked exactly once, where the
+ * membership row already lives.
+ */
+import { digest, sign, verify } from '@optimystic/quereus-plugin-crypto';
+/**
+ * Build the base64url SHA-256 digest that the self-signature covers. Mirrors the
+ * `DeviceToken.AuthorizedUpdate` constraint exactly; both sides take the default
+ * base64url output of a single `digest(...)`, which round-trips cleanly.
+ */
+export function deviceTokenSignedPayload(record) {
+    const joined = `${record.peerId}|${record.platform}|${record.token}|${record.updatedAt}`;
+    return digest([joined], 'sha256', 'base64url');
+}
+/**
+ * Sign a device-token record with the ed25519 private key behind its `peerId`.
+ * Returns a fully-populated {@link DeviceTokenRecord}.
+ *
+ * @param fields - the record fields to sign
+ * @param privateKeyB64 - base64url ed25519 seed (see `authorityKeyFromLibp2p`)
+ */
+export function signDeviceTokenRecord(fields, privateKeyB64) {
+    const payloadDigest = deviceTokenSignedPayload(fields);
+    const sig = sign(payloadDigest, privateKeyB64, 'ed25519', 'base64url', 'base64url', 'base64url');
+    return { peerId: fields.peerId, platform: fields.platform, token: fields.token, updatedAt: fields.updatedAt, sig };
+}
+/**
+ * Verify a record's self-signature against the `CadrePeer.PublicKey` (base64url)
+ * bound to its `peerId`. Reconstructs the signed bytes from the record exactly as
+ * {@link signDeviceTokenRecord} produced them. Returns false on a missing key/sig or
+ * any verification failure.
+ */
+export function verifyDeviceTokenSignature(record, publicKeyB64) {
+    if (!publicKeyB64 || !record.sig) {
+        return false;
+    }
+    const payloadDigest = deviceTokenSignedPayload(record);
+    return verify(payloadDigest, record.sig, publicKeyB64, 'ed25519', 'base64url', 'base64url', 'base64url');
+}
+/** Narrow an arbitrary stored string to a known {@link PushPlatform}. */
+export function isPushPlatform(value) {
+    return value === 'fcm' || value === 'apns';
+}
+//# sourceMappingURL=device-token.js.map

package/dist/device-token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-token.js","sourceRoot":"","sources":["../src/device-token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,mCAAmC,CAAC;AAGzE;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CAAC,MAAsC;IAC7E,MAAM,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;IACzF,OAAO,MAAM,CAAC,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,WAAW,CAAW,CAAC;AAC3D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAAsC,EACtC,aAAqB;IAErB,MAAM,aAAa,GAAG,wBAAwB,CAAC,MAAM,CAAC,CAAC;IACvD,MAAM,GAAG,GAAG,IAAI,CACd,aAAa,EACb,aAAa,EACb,SAAS,EACT,WAAW,EACX,WAAW,EACX,WAAW,CACF,CAAC;IACZ,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC;AACrH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B,CAAC,MAAyB,EAAE,YAAoB;IACxF,IAAI,CAAC,YAAY,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC;QACjC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,aAAa,GAAG,wBAAwB,CAAC,MAAM,CAAC,CAAC;IACvD,OAAO,MAAM,CACX,aAAa,EACb,MAAM,CAAC,GAAG,EACV,YAAY,EACZ,SAAS,EACT,WAAW,EACX,WAAW,EACX,WAAW,CACZ,CAAC;AACJ,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,OAAO,KAAK,KAAK,KAAK,IAAI,KAAK,KAAK,MAAM,CAAC;AAC7C,CAAC"}

package/dist/diagnostics/connection-path.d.ts

@@ -0,0 +1,118 @@
+/**
+ * connection-path.ts — classify each open libp2p connection as relayed
+ * (`/p2p-circuit`) vs direct, tag its transport, and summarise counts plus a
+ * "stuck on relay" condition.
+ *
+ * This is the **canonical** implementation. The web reference app keeps a
+ * deliberate, documented duplicate at
+ * `packages/reference-app-web/src/lib/connection-path.ts` (it does not depend on
+ * `@serfab/cadre-core`). Keep the function signatures and classification table
+ * identical across both copies so a future shared micro-package would be a
+ * drop-in.
+ *
+ * The whole signal is a pure function over `node.getConnections()` + a settle
+ * window + `Date.now()`. A connection's path is derivable from its `remoteAddr`
+ * multiaddr string alone — no I/O, no events, no stateful observer.
+ */
+export type ConnectionPathKind = 'relayed' | 'direct';
+export type ConnectionTransport = 'circuit-relay' | 'webrtc' | 'webrtc-turn' | 'webrtc-direct' | 'websocket' | 'tcp' | 'unknown';
+export interface ConnectionPath {
+    /** remotePeer.toString() */
+    peerId: string;
+    remoteAddr: string;
+    kind: ConnectionPathKind;
+    transport: ConnectionTransport;
+    direction: 'inbound' | 'outbound';
+    /** connection.timeline.open ?? null */
+    openedAtMs: number | null;
+    /** now - openedAtMs */
+    ageMs: number | null;
+    /** relayed && age > settleWindow && no direct conn to same peer */
+    stuckOnRelay: boolean;
+}
+export interface ConnectionPathSummary {
+    total: number;
+    relayed: number;
+    direct: number;
+    stuckOnRelay: number;
+    byTransport: Record<ConnectionTransport, number>;
+    /** best-effort; null when libp2p exposes no byte counter (see classifier docs) */
+    bytesOverRelay: number | null;
+    paths: ConnectionPath[];
+    settleWindowMs: number;
+}
+/**
+ * The minimal connection shape the classifier needs. The stock libp2p
+ * `Connection` (from `@libp2p/interface`) satisfies this structurally, and
+ * tests can build small synthetic objects against it.
+ */
+export interface ConnectionLike {
+    remotePeer?: {
+        toString(): string;
+    };
+    remoteAddr?: {
+        toString(): string;
+    };
+    direction?: 'inbound' | 'outbound';
+    timeline?: {
+        open?: number;
+    };
+    /**
+     * Set externally (by {@link CadreNode}, from a {@link TurnRelayTracker}
+     * observation) when ICE selected a TURN relay candidate for this `/webrtc`
+     * session. `undefined` = unknown (the multiaddr alone cannot reveal it). Only
+     * honoured for the `webrtc` transport — see {@link classifyConnectionPath}.
+     */
+    turnRelayed?: boolean;
+}
+export declare const DEFAULT_SETTLE_WINDOW_MS = 10000;
+interface TransportClass {
+    kind: ConnectionPathKind;
+    transport: ConnectionTransport;
+}
+/**
+ * Classify a remote multiaddr string into a (kind, transport) pair. Order
+ * matters — first match wins:
+ *
+ * | multiaddr contains            | kind    | transport      |
+ * |-------------------------------|---------|----------------|
+ * | `/webrtc-direct`              | direct  | webrtc-direct  |
+ * | `/webrtc`                     | direct  | webrtc         |
+ * | `/p2p-circuit` (no webrtc)    | relayed | circuit-relay  |
+ * | `/ws` (or `/wss`)             | direct  | websocket      |
+ * | `/tcp` (and none of the above)| direct  | tcp            |
+ * | _none_                        | direct  | unknown        |
+ *
+ * Note the ordering: a browser-to-browser WebRTC connection is dialed *over* a
+ * relay for SDP signalling and js-libp2p keeps the circuit prefix in the
+ * connection's remoteAddr — a successful hole-punch reads as
+ * `…/p2p-circuit/webrtc/p2p/…`, i.e. it contains BOTH `/p2p-circuit` and
+ * `/webrtc`. Its data path is nevertheless **direct**, so the WebRTC checks
+ * must come *before* `/p2p-circuit`. Only a connection with no transport after
+ * `/p2p-circuit` (`…/p2p-circuit/p2p/…`) is genuinely relay-carried.
+ */
+export declare function classifyTransport(remoteAddr: string): TransportClass;
+/**
+ * Per-connection classifier. Starts from the pure multiaddr classification, then
+ * applies the TURN override: a `/webrtc` session whose ICE selected a TURN relay
+ * candidate (`conn.turnRelayed === true`, set externally — the multiaddr alone
+ * cannot reveal it) is reclassified `relayed`/`webrtc-turn`. The
+ * `transport === 'webrtc'` guard means a `webrtc-direct` connection is never
+ * promoted (it uses no ICE and so can never be TURN-relayed), and `undefined`
+ * (unknown) degrades safely to the multiaddr result — not relayed.
+ */
+export declare function classifyConnectionPath(conn: ConnectionLike): TransportClass;
+/** An all-zero summary, used when no node/connections are available. */
+export declare function emptyConnectionPathSummary(settleWindowMs?: number): ConnectionPathSummary;
+/**
+ * Build a {@link ConnectionPathSummary} from the node's current connections.
+ *
+ * `stuckOnRelay` per connection is `relayed && ageMs != null && ageMs >
+ * settleWindowMs && no direct connection to the same peer` — the relay-only
+ * silent-failure condition (WebRTC negotiation failed, the connection quietly
+ * stays on the relay). The direct-peer set is the set of `peerId`s that have at
+ * least one `direct` connection, so a peer mid-upgrade (a relayed circuit conn
+ * *and* a direct webrtc conn at once) is correctly not flagged.
+ */
+export declare function summarizeConnectionPaths(conns: Iterable<ConnectionLike> | null | undefined, settleWindowMs?: number): ConnectionPathSummary;
+export {};

package/dist/diagnostics/connection-path.js

@@ -0,0 +1,204 @@
+/**
+ * connection-path.ts — classify each open libp2p connection as relayed
+ * (`/p2p-circuit`) vs direct, tag its transport, and summarise counts plus a
+ * "stuck on relay" condition.
+ *
+ * This is the **canonical** implementation. The web reference app keeps a
+ * deliberate, documented duplicate at
+ * `packages/reference-app-web/src/lib/connection-path.ts` (it does not depend on
+ * `@serfab/cadre-core`). Keep the function signatures and classification table
+ * identical across both copies so a future shared micro-package would be a
+ * drop-in.
+ *
+ * The whole signal is a pure function over `node.getConnections()` + a settle
+ * window + `Date.now()`. A connection's path is derivable from its `remoteAddr`
+ * multiaddr string alone — no I/O, no events, no stateful observer.
+ */
+export const DEFAULT_SETTLE_WINDOW_MS = 10000;
+const ALL_TRANSPORTS = [
+    'circuit-relay',
+    'webrtc',
+    'webrtc-turn',
+    'webrtc-direct',
+    'websocket',
+    'tcp',
+    'unknown',
+];
+/**
+ * Classify a remote multiaddr string into a (kind, transport) pair. Order
+ * matters — first match wins:
+ *
+ * | multiaddr contains            | kind    | transport      |
+ * |-------------------------------|---------|----------------|
+ * | `/webrtc-direct`              | direct  | webrtc-direct  |
+ * | `/webrtc`                     | direct  | webrtc         |
+ * | `/p2p-circuit` (no webrtc)    | relayed | circuit-relay  |
+ * | `/ws` (or `/wss`)             | direct  | websocket      |
+ * | `/tcp` (and none of the above)| direct  | tcp            |
+ * | _none_                        | direct  | unknown        |
+ *
+ * Note the ordering: a browser-to-browser WebRTC connection is dialed *over* a
+ * relay for SDP signalling and js-libp2p keeps the circuit prefix in the
+ * connection's remoteAddr — a successful hole-punch reads as
+ * `…/p2p-circuit/webrtc/p2p/…`, i.e. it contains BOTH `/p2p-circuit` and
+ * `/webrtc`. Its data path is nevertheless **direct**, so the WebRTC checks
+ * must come *before* `/p2p-circuit`. Only a connection with no transport after
+ * `/p2p-circuit` (`…/p2p-circuit/p2p/…`) is genuinely relay-carried.
+ */
+export function classifyTransport(remoteAddr) {
+    const addr = remoteAddr ?? '';
+    if (addr.includes('/webrtc-direct'))
+        return { kind: 'direct', transport: 'webrtc-direct' };
+    if (addr.includes('/webrtc'))
+        return { kind: 'direct', transport: 'webrtc' };
+    if (addr.includes('/p2p-circuit'))
+        return { kind: 'relayed', transport: 'circuit-relay' };
+    if (addr.includes('/ws'))
+        return { kind: 'direct', transport: 'websocket' };
+    if (addr.includes('/tcp'))
+        return { kind: 'direct', transport: 'tcp' };
+    return { kind: 'direct', transport: 'unknown' };
+}
+/** Read a connection's remote address as a string, never throwing. */
+function addrString(conn) {
+    try {
+        return conn.remoteAddr?.toString?.() ?? '';
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Per-connection classifier. Starts from the pure multiaddr classification, then
+ * applies the TURN override: a `/webrtc` session whose ICE selected a TURN relay
+ * candidate (`conn.turnRelayed === true`, set externally — the multiaddr alone
+ * cannot reveal it) is reclassified `relayed`/`webrtc-turn`. The
+ * `transport === 'webrtc'` guard means a `webrtc-direct` connection is never
+ * promoted (it uses no ICE and so can never be TURN-relayed), and `undefined`
+ * (unknown) degrades safely to the multiaddr result — not relayed.
+ */
+export function classifyConnectionPath(conn) {
+    const { kind, transport } = classifyTransport(addrString(conn));
+    if (transport === 'webrtc' && conn.turnRelayed === true) {
+        return { kind: 'relayed', transport: 'webrtc-turn' };
+    }
+    return { kind, transport };
+}
+/**
+ * Best-effort per-connection byte counter. The stock libp2p `Connection`
+ * interface carries no byte counter, so unless a metrics implementation is
+ * wired into the node this returns `null`. Never throws.
+ */
+function readConnectionBytes(conn) {
+    try {
+        const metrics = conn.metrics;
+        if (!metrics)
+            return null;
+        const received = typeof metrics.bytesReceived === 'number' ? metrics.bytesReceived : 0;
+        const sent = typeof metrics.bytesSent === 'number' ? metrics.bytesSent : 0;
+        const total = received + sent;
+        return Number.isFinite(total) ? total : null;
+    }
+    catch {
+        return null;
+    }
+}
+function zeroByTransport() {
+    const out = {};
+    for (const t of ALL_TRANSPORTS)
+        out[t] = 0;
+    return out;
+}
+/** An all-zero summary, used when no node/connections are available. */
+export function emptyConnectionPathSummary(settleWindowMs = DEFAULT_SETTLE_WINDOW_MS) {
+    return {
+        total: 0,
+        relayed: 0,
+        direct: 0,
+        stuckOnRelay: 0,
+        byTransport: zeroByTransport(),
+        bytesOverRelay: null,
+        paths: [],
+        settleWindowMs,
+    };
+}
+/**
+ * Build a {@link ConnectionPathSummary} from the node's current connections.
+ *
+ * `stuckOnRelay` per connection is `relayed && ageMs != null && ageMs >
+ * settleWindowMs && no direct connection to the same peer` — the relay-only
+ * silent-failure condition (WebRTC negotiation failed, the connection quietly
+ * stays on the relay). The direct-peer set is the set of `peerId`s that have at
+ * least one `direct` connection, so a peer mid-upgrade (a relayed circuit conn
+ * *and* a direct webrtc conn at once) is correctly not flagged.
+ */
+export function summarizeConnectionPaths(conns, settleWindowMs = DEFAULT_SETTLE_WINDOW_MS) {
+    const now = Date.now();
+    const list = conns ? Array.from(conns) : [];
+    // First pass: classify each connection and find the set of peers that have at
+    // least one direct connection.
+    const classified = list.map((conn) => {
+        const remoteAddr = addrString(conn);
+        // classifyConnectionPath (not classifyTransport) so the externally-set
+        // turnRelayed hint promotes webrtc → webrtc-turn (relayed).
+        const { kind, transport } = classifyConnectionPath(conn);
+        const openedAtMs = typeof conn.timeline?.open === 'number' ? conn.timeline.open : null;
+        const ageMs = openedAtMs != null ? Math.max(0, now - openedAtMs) : null;
+        const peerId = safePeerId(conn);
+        const direction = conn.direction === 'inbound' ? 'inbound' : 'outbound';
+        return { conn, peerId, remoteAddr, kind, transport, openedAtMs, ageMs, direction };
+    });
+    const directPeerSet = new Set(classified.filter((c) => c.kind === 'direct').map((c) => c.peerId));
+    const byTransport = zeroByTransport();
+    let relayed = 0;
+    let direct = 0;
+    let stuckCount = 0;
+    let bytesOverRelay = null;
+    const paths = classified.map((c) => {
+        byTransport[c.transport] += 1;
+        if (c.kind === 'relayed') {
+            relayed += 1;
+            const bytes = readConnectionBytes(c.conn);
+            if (bytes != null)
+                bytesOverRelay = (bytesOverRelay ?? 0) + bytes;
+        }
+        else {
+            direct += 1;
+        }
+        const stuckOnRelay = c.kind === 'relayed' &&
+            c.ageMs != null &&
+            c.ageMs > settleWindowMs &&
+            !directPeerSet.has(c.peerId);
+        if (stuckOnRelay)
+            stuckCount += 1;
+        return {
+            peerId: c.peerId,
+            remoteAddr: c.remoteAddr,
+            kind: c.kind,
+            transport: c.transport,
+            direction: c.direction,
+            openedAtMs: c.openedAtMs,
+            ageMs: c.ageMs,
+            stuckOnRelay,
+        };
+    });
+    return {
+        total: list.length,
+        relayed,
+        direct,
+        stuckOnRelay: stuckCount,
+        byTransport,
+        bytesOverRelay,
+        paths,
+        settleWindowMs,
+    };
+}
+function safePeerId(conn) {
+    try {
+        return conn.remotePeer?.toString?.() ?? '';
+    }
+    catch {
+        return '';
+    }
+}
+//# sourceMappingURL=connection-path.js.map

package/dist/diagnostics/connection-path.js.map

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

package/dist/diagnostics/webrtc-turn-tracker.d.ts

@@ -0,0 +1,50 @@
+/**
+ * webrtc-turn-tracker.ts — observe whether ICE selected a TURN relay candidate
+ * for each WebRTC session, so a TURN-relayed `/webrtc` connection can be
+ * reclassified `relayed`/`webrtc-turn` instead of silently counted `direct`.
+ *
+ * `@libp2p/webrtc` keeps the underlying `RTCPeerConnection` private and never
+ * surfaces it on the libp2p `Connection`, so the multiaddr classifier
+ * (`connection-path.ts`) cannot see the ICE candidate types. This tracker hooks
+ * `globalThis.RTCPeerConnection` at install time: every connection that reaches
+ * `connectionState === 'connected'` is inspected via `getStats()`, and the
+ * relay/not-relay verdict for the selected candidate pair is pushed onto a FIFO
+ * queue. {@link CadreNode} drains that queue on each `connection:open` to tag the
+ * matching peer (see {@link consume}).
+ *
+ * The correlation between a queued settlement and a `connection:open` is
+ * timing-based and best-effort — it degrades gracefully (unknown → treated as not
+ * relayed, a safe default that never produces a false `relayed`). It is inert on
+ * Node.js / any runtime with no `RTCPeerConnection`.
+ */
+export declare class TurnRelayTracker {
+    private readonly queue;
+    private OriginalRTCPeerConnection;
+    /** One settlement record per connection; guards against repeated `connected` events. */
+    private readonly observed;
+    /**
+     * Wrap `globalThis.RTCPeerConnection` with a subclass that records each
+     * connection's TURN-relay verdict when it settles. Idempotent. A NOP when no
+     * `RTCPeerConnection` exists (Node.js / no WebRTC polyfill) — the tracker stays
+     * inert and {@link consume} always returns `null`.
+     */
+    install(): void;
+    /**
+     * Pop the most recent settled entry within `windowMs` ms of now, returning its
+     * relay verdict (`true`/`false`); `null` when the queue has no matching entry.
+     * Also prunes entries older than the window (they can never match a later
+     * consume). Synchronous and safe to call from a `connection:open` handler.
+     */
+    consume(windowMs: number): boolean | null;
+    /** Restore the original `RTCPeerConnection` and clear the queue. Idempotent. */
+    dispose(): void;
+    /**
+     * Inspect a settled connection's stats and queue its TURN-relay verdict. Any
+     * failure (stats API absent, rejected promise, malformed report) is caught and
+     * recorded as `isRelay: false` — the safe default (unknown → not relayed) keeps
+     * the connection counted rather than dropping it.
+     */
+    private recordSettlement;
+    /** Drop queued entries settled before `cutoffMs` (the queue is in push order). */
+    private pruneOlderThan;
+}