@serfab/cadre-core 0.7.1 → 0.9.0

package/dist/diagnostics/webrtc-turn-tracker.js

@@ -0,0 +1,196 @@
+/**
+ * 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`.
+ */
+import debug from 'debug';
+const log = debug('sereus:cadre:turn-tracker');
+/**
+ * Hard cap on the FIFO queue. In steady state every settlement is consumed by a
+ * `connection:open`, so the queue stays tiny; the cap only bounds a pathological
+ * leak (settlements that never get a matching consume).
+ */
+const MAX_QUEUE = 64;
+export class TurnRelayTracker {
+    constructor() {
+        this.queue = [];
+        /** One settlement record per connection; guards against repeated `connected` events. */
+        this.observed = new WeakSet();
+    }
+    /**
+     * 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() {
+        if (this.OriginalRTCPeerConnection) {
+            return; // already installed
+        }
+        const Original = globalThis.RTCPeerConnection;
+        if (typeof Original !== 'function') {
+            log('install: no globalThis.RTCPeerConnection — tracker inert (Node.js / no polyfill)');
+            return;
+        }
+        this.OriginalRTCPeerConnection = Original;
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        const tracker = this;
+        class TrackedRTCPeerConnection extends Original {
+            constructor(...args) {
+                super(...args);
+                try {
+                    this.addEventListener('connectionstatechange', () => {
+                        try {
+                            if (this.connectionState === 'connected' && !tracker.observed.has(this)) {
+                                tracker.observed.add(this);
+                                void tracker.recordSettlement(this);
+                            }
+                        }
+                        catch (error) {
+                            log('connectionstatechange handler failed: %o', error);
+                        }
+                    });
+                }
+                catch (error) {
+                    log('install: failed to attach connectionstatechange listener: %o', error);
+                }
+            }
+        }
+        globalThis.RTCPeerConnection = TrackedRTCPeerConnection;
+        log('install: wrapped globalThis.RTCPeerConnection');
+    }
+    /**
+     * 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) {
+        const now = Date.now();
+        let result = null;
+        // Walk newest → oldest; the most recent in-window settlement is the best
+        // correlation for a just-opened connection.
+        for (let i = this.queue.length - 1; i >= 0; i--) {
+            if (now - this.queue[i].settledAtMs <= windowMs) {
+                result = this.queue[i].isRelay;
+                this.queue.splice(i, 1);
+                break;
+            }
+        }
+        this.pruneOlderThan(now - windowMs);
+        return result;
+    }
+    /** Restore the original `RTCPeerConnection` and clear the queue. Idempotent. */
+    dispose() {
+        if (this.OriginalRTCPeerConnection) {
+            globalThis.RTCPeerConnection = this.OriginalRTCPeerConnection;
+            this.OriginalRTCPeerConnection = undefined;
+        }
+        this.queue.length = 0;
+    }
+    /**
+     * 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.
+     */
+    async recordSettlement(pc) {
+        // Defaults to not-relayed (the safe "unknown" verdict); only the success path
+        // below overrides it, so a getStats failure leaves it false.
+        let isRelay = false;
+        try {
+            const report = await pc.getStats();
+            isRelay = selectedCandidatePairIsRelay(statsToMap(report));
+        }
+        catch (error) {
+            log('recordSettlement: getStats failed, keeping not-relayed default: %o', error);
+        }
+        this.queue.push({ settledAtMs: Date.now(), isRelay });
+        if (this.queue.length > MAX_QUEUE) {
+            this.queue.shift();
+        }
+    }
+    /** Drop queued entries settled before `cutoffMs` (the queue is in push order). */
+    pruneOlderThan(cutoffMs) {
+        while (this.queue.length > 0 && this.queue[0].settledAtMs < cutoffMs) {
+            this.queue.shift();
+        }
+    }
+}
+/** Materialise an `RTCStatsReport` into a plain map keyed by stats id. */
+function statsToMap(report) {
+    const map = new Map();
+    report.forEach((value, key) => {
+        map.set(key, value);
+    });
+    return map;
+}
+/**
+ * Whether the selected ICE candidate pair used a TURN relay candidate on either
+ * end. The pair is the transport's `selectedCandidatePairId` when present, else
+ * the nominated succeeded pair, else any succeeded pair.
+ */
+function selectedCandidatePairIsRelay(stats) {
+    const pair = findSelectedPair(stats);
+    if (!pair) {
+        return false;
+    }
+    const local = pair.localCandidateId ? stats.get(pair.localCandidateId) : undefined;
+    const remote = pair.remoteCandidateId ? stats.get(pair.remoteCandidateId) : undefined;
+    return isRelayCandidate(local) || isRelayCandidate(remote);
+}
+function isRelayCandidate(stat) {
+    return stat?.type === 'local-candidate' || stat?.type === 'remote-candidate'
+        ? stat.candidateType === 'relay'
+        : false;
+}
+function findSelectedPair(stats) {
+    const selectedId = selectedPairIdFromTransport(stats);
+    if (selectedId) {
+        const stat = stats.get(selectedId);
+        if (stat?.type === 'candidate-pair') {
+            return stat;
+        }
+    }
+    let succeeded;
+    for (const stat of stats.values()) {
+        if (stat.type !== 'candidate-pair') {
+            continue;
+        }
+        const pair = stat;
+        if (pair.state !== 'succeeded') {
+            continue;
+        }
+        if (pair.nominated) {
+            return pair; // nominated succeeded pair wins outright
+        }
+        succeeded ?? (succeeded = pair);
+    }
+    return succeeded;
+}
+function selectedPairIdFromTransport(stats) {
+    for (const stat of stats.values()) {
+        if (stat.type === 'transport') {
+            const id = stat.selectedCandidatePairId;
+            if (typeof id === 'string') {
+                return id;
+            }
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=webrtc-turn-tracker.js.map

package/dist/diagnostics/webrtc-turn-tracker.js.map

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

package/dist/ed25519-key.d.ts

@@ -0,0 +1,42 @@
+import type { PrivateKey } from '@libp2p/interface';
+/**
+ * An Ed25519 keypair expressed in the base64url form that
+ * `@optimystic/quereus-plugin-crypto` (`sign`/`verify`/`getPublicKey`) consumes.
+ * Generic bridge type — reused for owner keys, member keys, and any other
+ * seed→public keypair the control/strand databases sign with.
+ */
+export interface Ed25519KeyPair {
+    /** 32-byte Ed25519 seed, base64url-encoded — the crypto-plugin private key. */
+    privateKeyB64: string;
+    /** 32-byte Ed25519 public key, base64url-encoded. */
+    publicKeyB64: string;
+}
+/**
+ * Bridge a libp2p Ed25519 private key into the base64url keypair used by the
+ * control- and strand-database signing constraints.
+ *
+ * libp2p stores an Ed25519 private key as 64 raw bytes: the first 32 are the
+ * seed (the actual scalar source), the last 32 are the public key — see
+ * `@libp2p/crypto`'s `Ed25519PrivateKey`. `@optimystic/quereus-plugin-crypto`
+ * (via `@noble/curves`) treats the 32-byte seed *as* the private key and
+ * derives the public key from it with standard Ed25519. The two derivations
+ * agree, so the node's peer identity and its signing key are one keypair:
+ * `getPublicKey(privateKeyB64)` === `publicKeyB64`.
+ *
+ * @param privateKey - The node's libp2p Ed25519 private key.
+ * @returns The base64url seed/public-key pair for signing operations.
+ * @throws If the key is not Ed25519 or the raw bytes aren't the expected length.
+ */
+export declare function ed25519KeyPairFromLibp2p(privateKey: PrivateKey): Ed25519KeyPair;
+/**
+ * Derive the base64url Ed25519 public key from a base64url 32-byte private seed
+ * — the same derivation the seed-bootstrap signer uses internally
+ * (`SeedBootstrapService` constructor). Use this to enroll a standalone
+ * (non-libp2p) key into the control DB before minting an invite, when the
+ * key is *not* the node's peer identity (so `ed25519KeyPairFromLibp2p`,
+ * which needs a libp2p key object, does not apply).
+ *
+ * @param privateKeyB64 - The base64url-encoded 32-byte Ed25519 seed.
+ * @returns The base64url-encoded Ed25519 public key.
+ */
+export declare function ed25519PublicKeyFromPrivate(privateKeyB64: string): string;

package/dist/ed25519-key.js

@@ -0,0 +1,51 @@
+import { toString as uint8ArrayToString } from 'uint8arrays';
+import { getPublicKey } from '@optimystic/quereus-plugin-crypto';
+/**
+ * Bridge a libp2p Ed25519 private key into the base64url keypair used by the
+ * control- and strand-database signing constraints.
+ *
+ * libp2p stores an Ed25519 private key as 64 raw bytes: the first 32 are the
+ * seed (the actual scalar source), the last 32 are the public key — see
+ * `@libp2p/crypto`'s `Ed25519PrivateKey`. `@optimystic/quereus-plugin-crypto`
+ * (via `@noble/curves`) treats the 32-byte seed *as* the private key and
+ * derives the public key from it with standard Ed25519. The two derivations
+ * agree, so the node's peer identity and its signing key are one keypair:
+ * `getPublicKey(privateKeyB64)` === `publicKeyB64`.
+ *
+ * @param privateKey - The node's libp2p Ed25519 private key.
+ * @returns The base64url seed/public-key pair for signing operations.
+ * @throws If the key is not Ed25519 or the raw bytes aren't the expected length.
+ */
+export function ed25519KeyPairFromLibp2p(privateKey) {
+    if (privateKey.type !== 'Ed25519') {
+        throw new Error(`ed25519KeyPairFromLibp2p requires an Ed25519 key, got ${privateKey.type}`);
+    }
+    const raw = privateKey.raw;
+    if (raw.length !== 64) {
+        throw new Error(`Expected a 64-byte Ed25519 raw private key (seed||public), got ${raw.length} bytes`);
+    }
+    const seed = raw.subarray(0, 32);
+    const publicKeyRaw = privateKey.publicKey.raw;
+    if (publicKeyRaw.length !== 32) {
+        throw new Error(`Expected a 32-byte Ed25519 public key, got ${publicKeyRaw.length} bytes`);
+    }
+    return {
+        privateKeyB64: uint8ArrayToString(seed, 'base64url'),
+        publicKeyB64: uint8ArrayToString(publicKeyRaw, 'base64url'),
+    };
+}
+/**
+ * Derive the base64url Ed25519 public key from a base64url 32-byte private seed
+ * — the same derivation the seed-bootstrap signer uses internally
+ * (`SeedBootstrapService` constructor). Use this to enroll a standalone
+ * (non-libp2p) key into the control DB before minting an invite, when the
+ * key is *not* the node's peer identity (so `ed25519KeyPairFromLibp2p`,
+ * which needs a libp2p key object, does not apply).
+ *
+ * @param privateKeyB64 - The base64url-encoded 32-byte Ed25519 seed.
+ * @returns The base64url-encoded Ed25519 public key.
+ */
+export function ed25519PublicKeyFromPrivate(privateKeyB64) {
+    return getPublicKey(privateKeyB64, 'ed25519', 'base64url', 'base64url');
+}
+//# sourceMappingURL=ed25519-key.js.map

package/dist/ed25519-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ed25519-key.js","sourceRoot":"","sources":["../src/ed25519-key.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AAgBjE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,wBAAwB,CAAC,UAAsB;IAC7D,IAAI,UAAU,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,yDAAyD,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;IAC9F,CAAC;IAED,MAAM,GAAG,GAAG,UAAU,CAAC,GAAG,CAAC;IAC3B,IAAI,GAAG,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,kEAAkE,GAAG,CAAC,MAAM,QAAQ,CAAC,CAAC;IACxG,CAAC;IAED,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACjC,MAAM,YAAY,GAAG,UAAU,CAAC,SAAS,CAAC,GAAG,CAAC;IAC9C,IAAI,YAAY,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,8CAA8C,YAAY,CAAC,MAAM,QAAQ,CAAC,CAAC;IAC7F,CAAC;IAED,OAAO;QACL,aAAa,EAAE,kBAAkB,CAAC,IAAI,EAAE,WAAW,CAAC;QACpD,YAAY,EAAE,kBAAkB,CAAC,YAAY,EAAE,WAAW,CAAC;KAC5D,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,2BAA2B,CAAC,aAAqB;IAC/D,OAAO,YAAY,CAAC,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,CAAW,CAAC;AACpF,CAAC"}

package/dist/hibernation-manager.d.ts

@@ -6,6 +6,17 @@ export interface HibernationCallbacks {
     onIdle: (strandId: string) => Promise<void>;
     onHibernate: (strandId: string) => Promise<void>;
     onWake: (strandId: string) => Promise<void>;
+    /**
+     * Perform a real cohort check-in for a hibernating strand. The implementation
+     * (`CadreNode.handleStrandCheckIn`) resumes the strand, gives it a bounded
+     * window to connect to reachable cohort peers and surface pending activity,
+     * then re-hibernates if still idle. The manager AWAITS this before scheduling
+     * the next (longer-delayed) check-in, so a slow check-in never overlaps the
+     * next tick. After it resolves the manager inspects `instance.status`: a
+     * strand left non-`hibernating` is treated as woken (backoff resets on the
+     * next hibernation); a strand left `hibernating` escalates the backoff.
+     */
+    onCheckIn: (strandId: string) => Promise<void>;
 }
 /**
  * Manages strand hibernation state transitions based on activity.
@@ -20,7 +31,20 @@ export declare class HibernationManager {
     private readonly config;
     private readonly callbacks;
     private readonly timers;
+    /**
+     * Pending check-in timers, one per hibernating strand. Unlike the old fixed
+     * `setInterval`, these are single-shot `setTimeout`s rescheduled by
+     * {@link runCheckIn} with an escalating delay — so a long-running `onCheckIn`
+     * can never overlap the next tick, and the period adapts to the backoff.
+     */
     private readonly checkInTimers;
+    /**
+     * In-flight wake promises keyed by strandId. Coalesces overlapping wake
+     * triggers (two near-simultaneous activities, or activity racing a force wake)
+     * so `onWake` — and the libp2p-node rebuild it drives — runs at most once per
+     * concurrent wake.
+     */
+    private readonly wakePromises;
     private running;
     constructor(config: HibernationConfig, callbacks: HibernationCallbacks);
     /**
@@ -35,6 +59,31 @@ export declare class HibernationManager {
      * Stop managing hibernation
      */
     stop(): void;
+    /**
+     * Whether a strand with this instance's latency hint ever hibernates — `false`
+     * for realtime (Infinity idle timeout, see {@link HIBERNATION_TIMEOUTS}), also
+     * honouring any per-hint `customTimeouts` override. Imperative callers
+     * (`CadreNode.hibernateStrand` / `hibernateAll`) use this as the single source
+     * of truth for "skip realtime", consistent with {@link trackStrand} declining
+     * to track Infinity-timeout strands.
+     */
+    hibernates(instance: StrandInstance): boolean;
+    /**
+     * Imperatively hibernate a tracked strand now, bypassing the idle/hibernate
+     * timers — the mobile background-entry path. Cancels the strand's pending
+     * idle/hibernate AND check-in timers so none can later re-fire `onHibernate`
+     * on the already-quiesced strand or resurrect one the caller means to keep
+     * down, then invokes `onHibernate` (quiesce + mark hibernating).
+     *
+     * Unlike the timer path ({@link handleHibernateTimeout}) it deliberately does
+     * NOT re-arm the check-in chain: a force-hibernate keeps the strand down until
+     * the caller drives the next wake on demand (push-delivered on mobile), so a
+     * stray check-in timer must not bring it back up.
+     *
+     * @returns `true` if the strand was hibernated, `false` (no-op) for a realtime
+     *   strand that never hibernates.
+     */
+    forceHibernate(instance: StrandInstance): Promise<boolean>;
     /**
      * Register a strand for hibernation management
      */
@@ -51,11 +100,41 @@ export declare class HibernationManager {
      * Force wake a hibernating strand
      */
     wakeStrand(strandId: string): Promise<void>;
+    /**
+     * Begin a wake for a strand, or coalesce with one already in flight. Ensures
+     * `onWake` runs at most once per concurrent wake — the returned promise is
+     * shared by all overlapping callers and cleared once it settles. Force-wake
+     * callers await it; activity-driven callers fire-and-forget.
+     */
+    private beginWake;
     private scheduleIdleTransition;
     private handleIdleTimeout;
     private scheduleHibernateTransition;
     private handleHibernateTimeout;
+    /**
+     * Arm the next check-in for a hibernating strand. Each call is a single-shot
+     * `setTimeout` (not a fixed `setInterval`) so the period escalates per
+     * {@link runCheckIn} and a slow `onCheckIn` never overlaps the next tick.
+     *
+     * `delay` is omitted by the chain start ({@link handleHibernateTimeout}),
+     * defaulting to the base `checkInInterval` — which is why backoff naturally
+     * resets to base each fresh hibernation cycle, with no per-strand counter to
+     * clear on wake. Subsequent ticks pass the escalated, capped delay.
+     */
     private scheduleCheckIn;
+    /**
+     * Run a single check-in tick: invoke `onCheckIn` (a real resume → bounded
+     * sync window → re-hibernate-if-idle cycle in `CadreNode`) and AWAIT it before
+     * deciding the next step.
+     *
+     * - If the strand woke during the check-in (`onCheckIn` left it non-
+     *   `hibernating`), stop the chain — the activity path has re-armed the
+     *   idle/hibernate timers, and the next hibernation restarts the chain at the
+     *   base delay (backoff reset).
+     * - Otherwise escalate the delay by `checkInBackoffFactor`, capped at
+     *   `checkInMaxInterval`, and reschedule.
+     */
+    private runCheckIn;
     private clearTimer;
     private clearTimers;
     /**