@freqhole/haruspex 0.0.0

package/dist/permissions/access.js

@@ -0,0 +1,56 @@
+// role-hierarchy privilege checks + a generic route-auth-style access rule
+// evaluator, parameterized over an injected RoleHierarchy rather than any
+// one app's fixed role enum. a route-auth binding over a specific app's
+// codegen'd auth metadata (e.g. tomb's `RouteAuth`/`routes` types) stays
+// app-side; this subpath only owns the privilege-comparison logic itself.
+/**
+ * does `actualRole` have at least the privilege of `requiredRole`? lower
+ * hierarchy numbers are more privileged, so this holds when `actualRole`'s
+ * level is less than or equal to `requiredRole`'s.
+ */
+export function hasAtLeastRole(hierarchy, actualRole, requiredRole) {
+    return hierarchy[actualRole] <= hierarchy[requiredRole];
+}
+/** is `userId` strictly the resource's owner? */
+export function isOwner(userId, ownerId) {
+    return ownerId !== null && userId === ownerId;
+}
+/**
+ * is `userId` the resource's owner, or does `actualRole` have at least
+ * `requiredRole`'s privilege? owner always passes regardless of role.
+ */
+export function canAccessOwnerOr(hierarchy, userId, ownerId, actualRole, requiredRole) {
+    if (isOwner(userId, ownerId))
+        return true;
+    return hasAtLeastRole(hierarchy, actualRole, requiredRole);
+}
+/** evaluate any `AccessRule` against a caller context. */
+export function canAccess(hierarchy, rule, ctx) {
+    switch (rule.type) {
+        case "public":
+            return true;
+        case "authenticated":
+            return ctx.userRole !== null;
+        case "role":
+            return ctx.userRole !== null && hasAtLeastRole(hierarchy, ctx.userRole, rule.role);
+        case "owner":
+            return ctx.userId !== null && isOwner(ctx.userId, ctx.ownerId);
+        case "owner_or":
+            return (ctx.userId !== null &&
+                ctx.userRole !== null &&
+                canAccessOwnerOr(hierarchy, ctx.userId, ctx.ownerId, ctx.userRole, rule.role));
+    }
+}
+/**
+ * bind a role hierarchy once and get back plain functions that no longer
+ * need it threaded through every call - convenient for a caller that only
+ * ever checks against one hierarchy for its whole lifetime.
+ */
+export function bindRoleHierarchy(hierarchy) {
+    return {
+        hasAtLeastRole: (actualRole, requiredRole) => hasAtLeastRole(hierarchy, actualRole, requiredRole),
+        canAccessOwnerOr: (userId, ownerId, actualRole, requiredRole) => canAccessOwnerOr(hierarchy, userId, ownerId, actualRole, requiredRole),
+        isOwner,
+        canAccess: (rule, ctx) => canAccess(hierarchy, rule, ctx),
+    };
+}

package/dist/permissions/access.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=access.test.d.ts.map

package/dist/permissions/access.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access.test.d.ts","sourceRoot":"","sources":["../../src/permissions/access.test.ts"],"names":[],"mappings":""}

package/dist/permissions/access.test.js

@@ -0,0 +1,72 @@
+import { describe, expect, it } from "vitest";
+import { FREQHOLE_ROLE_HIERARCHY } from "./role-table.js";
+import { bindRoleHierarchy, canAccess, canAccessOwnerOr, hasAtLeastRole, isOwner, } from "./access.js";
+describe("hasAtLeastRole", () => {
+    it("holds when the actual role is at least as privileged", () => {
+        expect(hasAtLeastRole(FREQHOLE_ROLE_HIERARCHY, "admin", "member")).toBe(true);
+        expect(hasAtLeastRole(FREQHOLE_ROLE_HIERARCHY, "root", "root")).toBe(true);
+    });
+    it("fails when the actual role is less privileged", () => {
+        expect(hasAtLeastRole(FREQHOLE_ROLE_HIERARCHY, "viewer", "member")).toBe(false);
+    });
+    it("works against a caller-supplied role table with its own vocabulary", () => {
+        const hierarchy = { owner: 0, editor: 10, reader: 20 };
+        expect(hasAtLeastRole(hierarchy, "editor", "reader")).toBe(true);
+        expect(hasAtLeastRole(hierarchy, "reader", "editor")).toBe(false);
+    });
+});
+describe("isOwner", () => {
+    it("is true only when the ids match and ownerId is set", () => {
+        expect(isOwner("u1", "u1")).toBe(true);
+        expect(isOwner("u1", "u2")).toBe(false);
+        expect(isOwner("u1", null)).toBe(false);
+    });
+});
+describe("canAccessOwnerOr", () => {
+    it("passes for the owner regardless of role", () => {
+        expect(canAccessOwnerOr(FREQHOLE_ROLE_HIERARCHY, "u1", "u1", "viewer", "admin")).toBe(true);
+    });
+    it("falls back to the role check for a non-owner", () => {
+        expect(canAccessOwnerOr(FREQHOLE_ROLE_HIERARCHY, "u1", "u2", "admin", "admin")).toBe(true);
+        expect(canAccessOwnerOr(FREQHOLE_ROLE_HIERARCHY, "u1", "u2", "viewer", "admin")).toBe(false);
+    });
+});
+describe("canAccess", () => {
+    const ctx = (userRole, userId, ownerId) => ({
+        userRole,
+        userId,
+        ownerId,
+    });
+    it("public always passes", () => {
+        expect(canAccess(FREQHOLE_ROLE_HIERARCHY, { type: "public" }, ctx(null, null, null))).toBe(true);
+    });
+    it("authenticated requires a non-null role", () => {
+        expect(canAccess(FREQHOLE_ROLE_HIERARCHY, { type: "authenticated" }, ctx("viewer", "u1", null))).toBe(true);
+        expect(canAccess(FREQHOLE_ROLE_HIERARCHY, { type: "authenticated" }, ctx(null, null, null))).toBe(false);
+    });
+    it("role requires at least the given privilege", () => {
+        const rule = { type: "role", role: "admin" };
+        expect(canAccess(FREQHOLE_ROLE_HIERARCHY, rule, ctx("root", "u1", null))).toBe(true);
+        expect(canAccess(FREQHOLE_ROLE_HIERARCHY, rule, ctx("member", "u1", null))).toBe(false);
+    });
+    it("owner requires the caller to be the resource owner", () => {
+        const rule = { type: "owner" };
+        expect(canAccess(FREQHOLE_ROLE_HIERARCHY, rule, ctx("viewer", "u1", "u1"))).toBe(true);
+        expect(canAccess(FREQHOLE_ROLE_HIERARCHY, rule, ctx("viewer", "u1", "u2"))).toBe(false);
+    });
+    it("owner_or passes for the owner or a sufficiently privileged role", () => {
+        const rule = { type: "owner_or", role: "admin" };
+        expect(canAccess(FREQHOLE_ROLE_HIERARCHY, rule, ctx("viewer", "u1", "u1"))).toBe(true);
+        expect(canAccess(FREQHOLE_ROLE_HIERARCHY, rule, ctx("admin", "u1", "u2"))).toBe(true);
+        expect(canAccess(FREQHOLE_ROLE_HIERARCHY, rule, ctx("member", "u1", "u2"))).toBe(false);
+    });
+});
+describe("bindRoleHierarchy", () => {
+    it("bundles the same behavior without re-threading the hierarchy", () => {
+        const checks = bindRoleHierarchy(FREQHOLE_ROLE_HIERARCHY);
+        expect(checks.hasAtLeastRole("admin", "member")).toBe(true);
+        expect(checks.isOwner("u1", "u1")).toBe(true);
+        expect(checks.canAccessOwnerOr("u1", "u2", "admin", "admin")).toBe(true);
+        expect(checks.canAccess({ type: "role", role: "member" }, { userRole: "admin", userId: "u1", ownerId: null })).toBe(true);
+    });
+});

package/dist/permissions/index.d.ts

@@ -0,0 +1,5 @@
+export type { FreqholeRole, RoleHierarchy } from "./role-table.js";
+export { FREQHOLE_ROLE_HIERARCHY } from "./role-table.js";
+export type { AccessContext, AccessRule, RoleChecks } from "./access.js";
+export { bindRoleHierarchy, canAccess, canAccessOwnerOr, hasAtLeastRole, isOwner, } from "./access.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/permissions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/permissions/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAE1D,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,EACL,iBAAiB,EACjB,SAAS,EACT,gBAAgB,EAChB,cAAc,EACd,OAAO,GACR,MAAM,aAAa,CAAC"}

package/dist/permissions/index.js

@@ -0,0 +1,2 @@
+export { FREQHOLE_ROLE_HIERARCHY } from "./role-table.js";
+export { bindRoleHierarchy, canAccess, canAccessOwnerOr, hasAtLeastRole, isOwner, } from "./access.js";

package/dist/permissions/role-table.d.ts

@@ -0,0 +1,11 @@
+/** a role hierarchy: role name -> privilege level (lower = more privileged). */
+export type RoleHierarchy<TRole extends string> = Record<TRole, number>;
+/** the role names haruspex's own grant model uses (see the rust `Role` enum). */
+export type FreqholeRole = "root" | "admin" | "member" | "viewer";
+/**
+ * the default freqhole role hierarchy - root above admin above member above
+ * viewer. a caller with its own role vocabulary supplies its own
+ * `RoleHierarchy` instead; nothing in this subpath requires this one.
+ */
+export declare const FREQHOLE_ROLE_HIERARCHY: RoleHierarchy<FreqholeRole>;
+//# sourceMappingURL=role-table.d.ts.map

package/dist/permissions/role-table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-table.d.ts","sourceRoot":"","sources":["../../src/permissions/role-table.ts"],"names":[],"mappings":"AAMA,gFAAgF;AAChF,MAAM,MAAM,aAAa,CAAC,KAAK,SAAS,MAAM,IAAI,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AAExE,iFAAiF;AACjF,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAElE;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,aAAa,CAAC,YAAY,CAK/D,CAAC"}

package/dist/permissions/role-table.js

@@ -0,0 +1,16 @@
+// role hierarchy tables: a plain mapping from role name to a privilege
+// level, lower number = higher privilege. every function in ./permissions
+// takes one of these as an explicit argument rather than assuming any
+// fixed set of role names, so an app with its own role vocabulary can use
+// the same privilege-comparison logic haruspex ships by default.
+/**
+ * the default freqhole role hierarchy - root above admin above member above
+ * viewer. a caller with its own role vocabulary supplies its own
+ * `RoleHierarchy` instead; nothing in this subpath requires this one.
+ */
+export const FREQHOLE_ROLE_HIERARCHY = {
+    root: 0,
+    admin: 10,
+    member: 20,
+    viewer: 30,
+};

package/dist/protocol/client.d.ts

@@ -0,0 +1,67 @@
+import { type FriendzMessage } from "./codec.js";
+/** how often to send heartbeat pings to known peers (ms). */
+export declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 30000;
+/** time after last heartbeat before marking a peer offline (ms). */
+export declare const DEFAULT_HEARTBEAT_TIMEOUT_MS = 90000;
+/**
+ * the structural surface this subpath needs from a bidirectional byte
+ * stream to one peer - matches midden's wasm-exported `BiStream`.
+ * `read_message`/`write_message` are already message-boundary-framed by
+ * the underlying transport, so the codec's unframed encodeMessage/
+ * decodeMessage are what this client uses over a BiStreamLike (the
+ * length-delimited FrameReader in codec.ts is for transports without that
+ * built-in framing).
+ */
+export interface BiStreamLike {
+    peer_node_id(): string;
+    alpn(): string;
+    write_message(data: Uint8Array): Promise<void>;
+    read_message(): Promise<Uint8Array | null>;
+    close(): void;
+}
+/** the structural surface this subpath needs from a p2p node to open streams. */
+export interface MiddenNodeLike {
+    node_id(): string;
+    open_bi(peerAddr: string, alpn: string): Promise<BiStreamLike>;
+}
+export interface FriendzClientOptions {
+    /** resolves to the node used to open outbound streams. */
+    getNode: () => Promise<MiddenNodeLike>;
+    /** the alpn to open outbound streams on. default "freqhole-friendz/1". */
+    alpn?: string;
+    localNodeId: string;
+    localUsername: string;
+    heartbeatIntervalMs?: number;
+    heartbeatTimeoutMs?: number;
+    /** called for every decoded message received from any peer. */
+    onMessage?: (message: FriendzMessage, fromNodeId: string) => void;
+    /** called when a peer transitions from offline/unknown to online. */
+    onPeerBecameOnline?: (nodeId: string) => void;
+    /** called when a peer times out or announces going offline. */
+    onPeerWentOffline?: (nodeId: string) => void;
+    /** called when a received message's bytes fail to decode. never throws. */
+    onDecodeError?: (error: unknown, fromNodeId: string) => void;
+}
+export interface FriendzClient {
+    /** send a message to a peer, opening a stream if one isn't already open. */
+    sendMessage(peerNodeId: string, message: FriendzMessage): Promise<void>;
+    /** hand an accepted inbound stream to the client - starts its read loop. */
+    handleIncomingStream(stream: BiStreamLike): void;
+    /** start the periodic heartbeat. getPeerNodeIds is re-read each tick. */
+    startHeartbeat(getPeerNodeIds: () => string[]): void;
+    /** stop the periodic heartbeat. */
+    stopHeartbeat(): void;
+    /** fire-and-forget an offline-announcement to every currently-online peer. */
+    announceOffline(): void;
+    /** is this peer considered online (a heartbeat arrived within the timeout)? */
+    isOnline(nodeId: string): boolean;
+    /** every peer node id currently considered online. */
+    getOnlinePeers(): string[];
+    /** subscribe to online/offline transitions. returns an unsubscribe function. */
+    onOnlineChange(handler: () => void): () => void;
+    /** close every open stream, stop timers, release listeners. */
+    destroy(): void;
+}
+/** create a FriendzClient bound to the given transport + identity. */
+export declare function createFriendzClient(options: FriendzClientOptions): FriendzClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/protocol/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/protocol/client.ts"],"names":[],"mappings":"AAMA,OAAO,EAAgC,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAG/E,6DAA6D;AAC7D,eAAO,MAAM,6BAA6B,QAAS,CAAC;AAEpD,oEAAoE;AACpE,eAAO,MAAM,4BAA4B,QAAS,CAAC;AAEnD;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,YAAY,IAAI,MAAM,CAAC;IACvB,IAAI,IAAI,MAAM,CAAC;IACf,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,YAAY,IAAI,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAC3C,KAAK,IAAI,IAAI,CAAC;CACf;AAED,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC7B,OAAO,IAAI,MAAM,CAAC;IAClB,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAChE;AAED,MAAM,WAAW,oBAAoB;IACnC,0DAA0D;IAC1D,OAAO,EAAE,MAAM,OAAO,CAAC,cAAc,CAAC,CAAC;IACvC,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,+DAA+D;IAC/D,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IAClE,qEAAqE;IACrE,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,+DAA+D;IAC/D,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C,2EAA2E;IAC3E,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9D;AAED,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE,4EAA4E;IAC5E,oBAAoB,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IACjD,yEAAyE;IACzE,cAAc,CAAC,cAAc,EAAE,MAAM,MAAM,EAAE,GAAG,IAAI,CAAC;IACrD,mCAAmC;IACnC,aAAa,IAAI,IAAI,CAAC;IACtB,8EAA8E;IAC9E,eAAe,IAAI,IAAI,CAAC;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IAClC,sDAAsD;IACtD,cAAc,IAAI,MAAM,EAAE,CAAC;IAC3B,gFAAgF;IAChF,cAAc,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IAChD,+DAA+D;IAC/D,OAAO,IAAI,IAAI,CAAC;CACjB;AAcD,sEAAsE;AACtE,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAmLhF"}

package/dist/protocol/client.js

@@ -0,0 +1,195 @@
+// FriendzClient: the presence engine for the unified friendz protocol -
+// per-peer send streams, heartbeats, and online/offline tracking. the
+// transport is an injected structural type (BiStreamLike/MiddenNodeLike),
+// matching the shape of midden's own wasm-exported bidirectional stream
+// api - this subpath never imports midden itself.
+import { encodeMessage, decodeMessage } from "./codec.js";
+/** how often to send heartbeat pings to known peers (ms). */
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 30_000;
+/** time after last heartbeat before marking a peer offline (ms). */
+export const DEFAULT_HEARTBEAT_TIMEOUT_MS = 90_000;
+function coreMessage(message) {
+    return { kind: "core", message };
+}
+function heartbeatMessage(nodeId, username) {
+    return coreMessage({ type: "heartbeat", v: 1, nodeId, username });
+}
+function offlineAnnouncementMessage(nodeId) {
+    return coreMessage({ type: "offline-announcement", v: 1, nodeId });
+}
+/** create a FriendzClient bound to the given transport + identity. */
+export function createFriendzClient(options) {
+    const alpn = options.alpn ?? "freqhole-friendz/1";
+    const heartbeatIntervalMs = options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+    const heartbeatTimeoutMs = options.heartbeatTimeoutMs ?? DEFAULT_HEARTBEAT_TIMEOUT_MS;
+    const streams = new Map();
+    const pendingConnections = new Map();
+    const lastSeen = new Map();
+    const onlineChangeListeners = new Set();
+    let heartbeatTimer = null;
+    let destroyed = false;
+    function emitOnlineChange() {
+        for (const handler of onlineChangeListeners)
+            handler();
+    }
+    function markOnline(nodeId) {
+        const wasOnline = isOnline(nodeId);
+        lastSeen.set(nodeId, Date.now());
+        emitOnlineChange();
+        if (!wasOnline)
+            options.onPeerBecameOnline?.(nodeId);
+    }
+    function markOffline(nodeId) {
+        if (!lastSeen.has(nodeId))
+            return;
+        lastSeen.delete(nodeId);
+        emitOnlineChange();
+        options.onPeerWentOffline?.(nodeId);
+    }
+    function isOnline(nodeId) {
+        const seenAt = lastSeen.get(nodeId);
+        if (seenAt === undefined)
+            return false;
+        return Date.now() - seenAt < heartbeatTimeoutMs;
+    }
+    function getOnlinePeers() {
+        const now = Date.now();
+        const online = [];
+        for (const [nodeId, seenAt] of lastSeen) {
+            if (now - seenAt < heartbeatTimeoutMs)
+                online.push(nodeId);
+        }
+        return online;
+    }
+    async function readLoop(peerId, stream) {
+        try {
+            while (!destroyed) {
+                const data = await stream.read_message();
+                if (!data)
+                    break;
+                try {
+                    const message = decodeMessage(data);
+                    if (message.kind === "core" && message.message.type === "heartbeat") {
+                        markOnline(peerId);
+                    }
+                    if (message.kind === "core" && message.message.type === "offline-announcement") {
+                        markOffline(message.message.nodeId);
+                    }
+                    options.onMessage?.(message, peerId);
+                }
+                catch (err) {
+                    options.onDecodeError?.(err, peerId);
+                }
+            }
+        }
+        catch {
+            // the stream errored (peer gone, transport reset). if it was replaced
+            // by a newer stream already, that's expected - not this peer going
+            // offline, just a reconnect racing this loop's own close.
+            const wasReplaced = streams.get(peerId) !== stream;
+            if (!destroyed && !wasReplaced)
+                markOffline(peerId);
+        }
+        finally {
+            if (streams.get(peerId) === stream)
+                streams.delete(peerId);
+        }
+    }
+    async function openStream(peerNodeId) {
+        const node = await options.getNode();
+        const stream = await node.open_bi(peerNodeId, alpn);
+        streams.set(peerNodeId, stream);
+        void readLoop(peerNodeId, stream);
+        return stream;
+    }
+    async function getOrOpenStream(peerNodeId) {
+        const existing = streams.get(peerNodeId);
+        if (existing)
+            return existing;
+        let pending = pendingConnections.get(peerNodeId);
+        if (!pending) {
+            pending = openStream(peerNodeId);
+            pendingConnections.set(peerNodeId, pending);
+        }
+        try {
+            return await pending;
+        }
+        finally {
+            pendingConnections.delete(peerNodeId);
+        }
+    }
+    async function sendMessage(peerNodeId, message) {
+        const stream = await getOrOpenStream(peerNodeId);
+        await stream.write_message(encodeMessage(message));
+    }
+    function handleIncomingStream(stream) {
+        const peerId = stream.peer_node_id();
+        const existing = streams.get(peerId);
+        if (existing)
+            existing.close();
+        streams.set(peerId, stream);
+        void readLoop(peerId, stream);
+    }
+    function startHeartbeat(getPeerNodeIds) {
+        stopHeartbeat();
+        const tick = async (peerIds) => {
+            const msg = heartbeatMessage(options.localNodeId, options.localUsername);
+            for (const peerId of peerIds) {
+                try {
+                    await sendMessage(peerId, msg);
+                }
+                catch {
+                    // unreachable this tick - the next heartbeat (or an explicit
+                    // reconnect) will retry; nothing to recover here.
+                }
+                const seenAt = lastSeen.get(peerId);
+                if (seenAt !== undefined && Date.now() - seenAt >= heartbeatTimeoutMs) {
+                    markOffline(peerId);
+                }
+            }
+        };
+        void tick(getPeerNodeIds());
+        heartbeatTimer = setInterval(() => {
+            void tick(getPeerNodeIds());
+        }, heartbeatIntervalMs);
+    }
+    function stopHeartbeat() {
+        if (heartbeatTimer) {
+            clearInterval(heartbeatTimer);
+            heartbeatTimer = null;
+        }
+    }
+    function announceOffline() {
+        const msg = offlineAnnouncementMessage(options.localNodeId);
+        for (const peerId of getOnlinePeers()) {
+            sendMessage(peerId, msg).catch(() => {
+                // fire-and-forget - we're shutting down.
+            });
+        }
+    }
+    function onOnlineChange(handler) {
+        onlineChangeListeners.add(handler);
+        return () => onlineChangeListeners.delete(handler);
+    }
+    function destroy() {
+        destroyed = true;
+        stopHeartbeat();
+        for (const [, stream] of streams)
+            stream.close();
+        streams.clear();
+        pendingConnections.clear();
+        lastSeen.clear();
+        onlineChangeListeners.clear();
+    }
+    return {
+        sendMessage,
+        handleIncomingStream,
+        startHeartbeat,
+        stopHeartbeat,
+        announceOffline,
+        isOnline,
+        getOnlinePeers,
+        onOnlineChange,
+        destroy,
+    };
+}

package/dist/protocol/client.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=client.test.d.ts.map

package/dist/protocol/client.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.test.d.ts","sourceRoot":"","sources":["../../src/protocol/client.test.ts"],"names":[],"mappings":""}