@decentnetwork/lan 0.1.0

package/dist/carrier/peer-manager.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Manages Carrier peer identity and connections
+ * Wraps @decentnetwork/peer SDK
+ */
+import { EventEmitter } from "events";
+import { PacketSession } from "./packet-session.js";
+import type { PeerIdentity, RemotePeer } from "./types.js";
+import type { BootstrapNode } from "../types.js";
+export interface PeerManagerOptions {
+    keyFile: string;
+    bootstrapNodes: BootstrapNode[];
+    expressNodes?: BootstrapNode[];
+}
+export declare class PeerManager extends EventEmitter {
+    private peer;
+    private identity;
+    private sessions;
+    private sessionCounter;
+    private logger;
+    constructor();
+    create(opts: PeerManagerOptions): Promise<void>;
+    start(): Promise<void>;
+    joinNetwork(): Promise<void>;
+    announceSelf(timeoutMs?: number): Promise<void>;
+    /**
+     * Accept a pending friend request while the daemon is running.
+     * Replaces the daemon-down `friend-accept --wait` ceremony — the
+     * running daemon can just call this in response to an incoming
+     * onFriendRequest event. Idempotent: re-accepting an already-accepted
+     * pubkey is a no-op at the SDK level.
+     */
+    acceptFriendRequest(pubkey: string): Promise<void>;
+    /**
+     * Send an outbound friend request to a Carrier address (NOT a bare
+     * userid — sendFriendRequest needs the address form because it
+     * includes the recipient's nospam token). Used by DoraIntegration
+     * to auto-friend every peer in the roster.
+     *
+     * The SDK is idempotent for already-accepted peers (it short-
+     * circuits via the `acceptedAt` cache), so callers can spam this
+     * on every roster refresh without re-prompting iOS Beagle users.
+     */
+    sendFriendRequest(address: string, hello?: string): Promise<void>;
+    /**
+     * Returns true if the given userid is already an accepted friend of
+     * this peer. Lets DoraIntegration skip sendFriendRequest for peers
+     * we've already established a session with.
+     */
+    isFriend(userid: string): boolean;
+    stop(): Promise<void>;
+    getIdentity(): PeerIdentity;
+    /**
+     * Returns the userid (base58) — this is the identifier used in the
+     * friend store, in onText callbacks, and as the argument to sendText().
+     * Despite the historical name "pubkey", this is NOT the hex public key.
+     */
+    getPubkey(): string;
+    /**
+     * Returns the hex-encoded raw public key (32 bytes hex).
+     * Use this for cryptographic operations, not for friend lookups.
+     */
+    getHexPubkey(): string;
+    getAddress(): string;
+    getFriends(): RemotePeer[];
+    /**
+     * Check if a specific friend is currently online (direct UDP path established).
+     * Returns false for unknown pubkeys.
+     */
+    isFriendOnline(pubkey: string): boolean;
+    /**
+     * Actively wait for a friend to come online. The SDK uses this signal to
+     * accelerate route discovery + UDP holepunching for that friend.
+     * Returns true if the friend went online within the timeout.
+     */
+    waitForFriendConnected(pubkey: string, timeoutMs?: number): Promise<boolean>;
+    /**
+     * Trigger the SDK's session-establishment path for a peer by issuing a
+     * dummy sendText. peer.sendText() internally calls #initiateSession when
+     * no session exists. We swallow the resulting "friend offline" error.
+     *
+     * This is a workaround for the SDK quirk where one side's friendOnline
+     * notification never fires, leaving the friend perpetually "offline" even
+     * when both sides are connected to the same TCP relays.
+     */
+    kickSessionEstablishment(pubkey: string): Promise<void>;
+    /**
+     * Send a raw text payload to a friend. Used by application-layer
+     * protocols (e.g. dora) that ride on the same Carrier text channel as
+     * our base64-encoded packet frames but carry a different wire prefix
+     * (DORA:). Packet-router code never calls this directly — it goes
+     * through PacketSession.
+     */
+    sendText(pubkey: string, text: string): Promise<void>;
+    /**
+     * Open an outbound packet session (initiator).
+     * Sends HANDSHAKE_REQ and waits for HANDSHAKE_ACK.
+     */
+    openPacketSession(pubkey: string): Promise<PacketSession>;
+    closePacketSession(pubkey: string): void;
+    /**
+     * Get an existing session for a peer (for routing logic).
+     */
+    getSession(pubkey: string): PacketSession | null;
+    /**
+     * Internal: Create and register a session.
+     */
+    private createSession;
+    /**
+     * Send a HANDSHAKE_ACK frame to a peer.
+     */
+    private sendHandshakeAck;
+    private setupEventHandlers;
+}

package/dist/carrier/peer-manager.js

@@ -0,0 +1,392 @@
+/**
+ * Manages Carrier peer identity and connections
+ * Wraps @decentnetwork/peer SDK
+ */
+import { Peer } from "@decentnetwork/peer";
+import { EventEmitter } from "events";
+import { PacketSession } from "./packet-session.js";
+import { FrameCodec } from "./frame.js";
+import { FRAME_OPCODE_HANDSHAKE_ACK, } from "./types.js";
+import { Logger } from "../utils/logger.js";
+// Dora wire-prefix. Kept inline (rather than imported from @decentnetwork/dora) to
+// avoid coupling peer-manager — a transport-layer module — to an
+// application-protocol package. The prefix is part of decentlan's text
+// channel contract and must match the constant defined in dora's types.ts.
+const DORA_PREFIX = "DORA:";
+export class PeerManager extends EventEmitter {
+    peer = null;
+    identity = null;
+    sessions = new Map();
+    sessionCounter = 1;
+    logger;
+    constructor() {
+        super();
+        this.logger = new Logger({ prefix: "PeerManager" });
+    }
+    async create(opts) {
+        this.logger.info("Creating Peer instance");
+        this.peer = await Peer.create({
+            keyFile: opts.keyFile,
+            compatibilityMode: "legacy",
+            bootstrapNodes: opts.bootstrapNodes,
+            expressNodes: opts.expressNodes,
+        });
+        this.setupEventHandlers();
+        this.logger.info("Peer instance created (not yet started)");
+    }
+    async start() {
+        if (!this.peer) {
+            throw new Error("Peer not created. Call create() first.");
+        }
+        this.logger.info("Starting Peer");
+        await this.peer.start();
+        // Identity is only available after start()
+        this.identity = {
+            pubkey: this.peer.pubkey(),
+            address: this.peer.address(),
+            userid: this.peer.userid(),
+        };
+        this.logger.info(`Peer started: ${this.identity.address}`);
+    }
+    async joinNetwork() {
+        if (!this.peer) {
+            throw new Error("Peer not created. Call create() first.");
+        }
+        this.logger.info("Joining Carrier network");
+        await this.peer.joinNetwork();
+        this.logger.info("Joined Carrier network");
+    }
+    async announceSelf(timeoutMs) {
+        if (!this.peer) {
+            throw new Error("Peer not created. Call create() first.");
+        }
+        this.logger.info("Announcing self on DHT");
+        await this.peer.announceSelf(timeoutMs);
+        this.logger.info("Announced self on DHT");
+    }
+    /**
+     * Accept a pending friend request while the daemon is running.
+     * Replaces the daemon-down `friend-accept --wait` ceremony — the
+     * running daemon can just call this in response to an incoming
+     * onFriendRequest event. Idempotent: re-accepting an already-accepted
+     * pubkey is a no-op at the SDK level.
+     */
+    async acceptFriendRequest(pubkey) {
+        if (!this.peer) {
+            throw new Error("Peer not created. Call create() first.");
+        }
+        await this.peer.acceptFriendRequest(pubkey);
+        this.logger.info(`Accepted friend request from ${pubkey}`);
+    }
+    /**
+     * Send an outbound friend request to a Carrier address (NOT a bare
+     * userid — sendFriendRequest needs the address form because it
+     * includes the recipient's nospam token). Used by DoraIntegration
+     * to auto-friend every peer in the roster.
+     *
+     * The SDK is idempotent for already-accepted peers (it short-
+     * circuits via the `acceptedAt` cache), so callers can spam this
+     * on every roster refresh without re-prompting iOS Beagle users.
+     */
+    async sendFriendRequest(address, hello) {
+        if (!this.peer) {
+            throw new Error("Peer not created. Call create() first.");
+        }
+        await this.peer.sendFriendRequest(address, hello);
+    }
+    /**
+     * Returns true if the given userid is already an accepted friend of
+     * this peer. Lets DoraIntegration skip sendFriendRequest for peers
+     * we've already established a session with.
+     */
+    isFriend(userid) {
+        if (!this.peer)
+            return false;
+        // FriendRecord stores both pubkey (hex) and userid (base58). The
+        // dora roster gives us userid; match on either form to be safe
+        // against older friends.json entries that only set `pubkey`.
+        return this.peer
+            .friends()
+            .some((f) => f.userid === userid || f.pubkey === userid);
+    }
+    async stop() {
+        if (!this.peer) {
+            return;
+        }
+        this.logger.info("Stopping Peer");
+        // Close all sessions
+        for (const session of this.sessions.values()) {
+            session.close();
+        }
+        this.sessions.clear();
+        await this.peer.stop();
+        this.logger.info("Peer stopped");
+    }
+    getIdentity() {
+        if (!this.identity) {
+            throw new Error("Peer not created. Call create() first.");
+        }
+        return this.identity;
+    }
+    /**
+     * Returns the userid (base58) — this is the identifier used in the
+     * friend store, in onText callbacks, and as the argument to sendText().
+     * Despite the historical name "pubkey", this is NOT the hex public key.
+     */
+    getPubkey() {
+        if (!this.peer) {
+            throw new Error("Peer not created. Call create() first.");
+        }
+        return this.peer.userid();
+    }
+    /**
+     * Returns the hex-encoded raw public key (32 bytes hex).
+     * Use this for cryptographic operations, not for friend lookups.
+     */
+    getHexPubkey() {
+        if (!this.peer) {
+            throw new Error("Peer not created. Call create() first.");
+        }
+        return this.peer.pubkey();
+    }
+    getAddress() {
+        if (!this.peer) {
+            throw new Error("Peer not created. Call create() first.");
+        }
+        return this.peer.address();
+    }
+    getFriends() {
+        if (!this.peer) {
+            throw new Error("Peer not created. Call create() first.");
+        }
+        return this.peer.friends().map((friend) => ({
+            pubkey: friend.pubkey,
+            name: friend.name,
+            status: friend.status === "online" ? "online" : "offline",
+            lastSeen: friend.acceptedAt,
+        }));
+    }
+    /**
+     * Check if a specific friend is currently online (direct UDP path established).
+     * Returns false for unknown pubkeys.
+     */
+    isFriendOnline(pubkey) {
+        if (!this.peer)
+            return false;
+        const friend = this.peer.friends().find((f) => f.pubkey === pubkey);
+        return friend?.status === "online";
+    }
+    /**
+     * Actively wait for a friend to come online. The SDK uses this signal to
+     * accelerate route discovery + UDP holepunching for that friend.
+     * Returns true if the friend went online within the timeout.
+     */
+    async waitForFriendConnected(pubkey, timeoutMs = 60000) {
+        if (!this.peer)
+            return false;
+        return this.peer.waitForFriendConnected(pubkey, timeoutMs);
+    }
+    /**
+     * Trigger the SDK's session-establishment path for a peer by issuing a
+     * dummy sendText. peer.sendText() internally calls #initiateSession when
+     * no session exists. We swallow the resulting "friend offline" error.
+     *
+     * This is a workaround for the SDK quirk where one side's friendOnline
+     * notification never fires, leaving the friend perpetually "offline" even
+     * when both sides are connected to the same TCP relays.
+     */
+    async kickSessionEstablishment(pubkey) {
+        if (!this.peer)
+            return;
+        try {
+            await this.peer.sendText(pubkey, "");
+        }
+        catch {
+            // expected when friend isn't online yet — the call still triggered
+            // #initiateSession internally, which is the side effect we want.
+        }
+    }
+    /**
+     * Send a raw text payload to a friend. Used by application-layer
+     * protocols (e.g. dora) that ride on the same Carrier text channel as
+     * our base64-encoded packet frames but carry a different wire prefix
+     * (DORA:). Packet-router code never calls this directly — it goes
+     * through PacketSession.
+     */
+    async sendText(pubkey, text) {
+        if (!this.peer) {
+            throw new Error("Peer not created. Call create() first.");
+        }
+        await this.peer.sendText(pubkey, text);
+    }
+    /**
+     * Open an outbound packet session (initiator).
+     * Sends HANDSHAKE_REQ and waits for HANDSHAKE_ACK.
+     */
+    async openPacketSession(pubkey) {
+        const existing = this.sessions.get(pubkey);
+        if (existing && existing.isConnected()) {
+            return existing;
+        }
+        const sessionId = this.sessionCounter++;
+        const session = this.createSession(pubkey, sessionId);
+        try {
+            await session.handshake();
+        }
+        catch (error) {
+            this.sessions.delete(pubkey);
+            throw error;
+        }
+        // Emit session-opened so PacketRouter can attach its "packet" listener.
+        // The responder side already emits this when handling handshake-req;
+        // the initiator side needs to emit it after the handshake completes.
+        this.emit("session-opened", { pubkey, sessionId });
+        return session;
+    }
+    closePacketSession(pubkey) {
+        const session = this.sessions.get(pubkey);
+        if (session) {
+            session.close();
+            this.sessions.delete(pubkey);
+        }
+    }
+    /**
+     * Get an existing session for a peer (for routing logic).
+     */
+    getSession(pubkey) {
+        return this.sessions.get(pubkey) || null;
+    }
+    /**
+     * Internal: Create and register a session.
+     */
+    createSession(pubkey, sessionId) {
+        const session = new PacketSession({
+            peerId: pubkey,
+            sessionId,
+            sendText: async (text) => {
+                if (!this.peer) {
+                    throw new Error("Peer not available");
+                }
+                await this.peer.sendText(pubkey, text);
+            },
+            onClose: () => {
+                this.sessions.delete(pubkey);
+            },
+        });
+        // Listen for handshake requests on this session — auto-respond with ACK
+        session.on("handshake-req", async () => {
+            this.logger.info(`Received HANDSHAKE_REQ from ${pubkey}, sending ACK`);
+            try {
+                await this.sendHandshakeAck(pubkey, sessionId);
+                session.acceptIncoming(); // Mark session as active (responder side)
+                this.emit("session-opened", { pubkey, sessionId });
+            }
+            catch (error) {
+                this.logger.error(`Failed to send HANDSHAKE_ACK to ${pubkey}:`, error);
+            }
+        });
+        this.sessions.set(pubkey, session);
+        return session;
+    }
+    /**
+     * Send a HANDSHAKE_ACK frame to a peer.
+     */
+    async sendHandshakeAck(pubkey, sessionId) {
+        if (!this.peer) {
+            throw new Error("Peer not available");
+        }
+        const frame = FrameCodec.encode(new Uint8Array(0), sessionId, FRAME_OPCODE_HANDSHAKE_ACK);
+        const frameBase64 = Buffer.from(frame).toString("base64");
+        await this.peer.sendText(pubkey, frameBase64);
+    }
+    setupEventHandlers() {
+        if (!this.peer) {
+            return;
+        }
+        // Friend connection events
+        this.peer.onFriendConnection((event) => {
+            const evt = {
+                pubkey: event.pubkey,
+                status: event.status === "connected" ? "connected" : "disconnected",
+                timestamp: Date.now(),
+            };
+            this.emit("friend-connection", evt);
+            this.logger.info(`Friend ${event.pubkey} ${event.status}`);
+            // If a friend goes offline (or, more importantly, comes BACK
+            // online after we already had a session — e.g. they restarted
+            // their daemon), the Carrier crypto session under us has
+            // rotated. Our cached PacketSession is bound to the previous
+            // session's frame-sequence state. Sending DATA frames through
+            // it produces ciphertext the new peer can't decrypt; the
+            // packets land in their PeerManager.onText but no session
+            // matches and they're dropped silently. Result: 100% loss
+            // that looks like "the link is up but pings time out."
+            //
+            // Fix: drop our PacketSession on every friend-status change.
+            // The next outbound packet triggers a fresh handshake (or the
+            // remote auto-creates from our HANDSHAKE_REQ); fast, clean,
+            // no stale-session lingering.
+            const existing = this.sessions.get(event.pubkey);
+            if (existing) {
+                this.logger.debug(`Closing stale packet session to ${event.pubkey} on friend-${event.status}`);
+                existing.close();
+                this.sessions.delete(event.pubkey);
+            }
+        });
+        // Text messages contain our framed packets
+        this.peer.onText((message) => {
+            try {
+                // Silently skip empty messages — kickSessionEstablishment sends
+                // an empty sendText to trigger the SDK's #initiateSession path,
+                // and the receiver doesn't need to log a warning for that.
+                if (message.text.length === 0) {
+                    return;
+                }
+                // Dora messages share the same text channel as packet frames but
+                // carry a `DORA:` ASCII prefix that's not valid base64. Route them
+                // to whoever is subscribed (DoraClient/DoraServer in daemon).
+                if (message.text.startsWith(DORA_PREFIX)) {
+                    this.emit("dora-message", message.pubkey, message.text);
+                    return;
+                }
+                const frameData = Buffer.from(message.text, "base64");
+                const frame = FrameCodec.decode(new Uint8Array(frameData));
+                if (!frame) {
+                    this.logger.warn(`Invalid frame from ${message.pubkey}`);
+                    return;
+                }
+                let session = this.sessions.get(message.pubkey);
+                // For HANDSHAKE_REQ: always create or REPLACE the session with the
+                // new sessionId. Without this, after a Carrier session drop + re-pair
+                // the peer's new HANDSHAKE_REQ would be dropped because the existing
+                // local session has the old sessionId — so the responder never sends
+                // HANDSHAKE_ACK and the initiator times out forever.
+                if (FrameCodec.isHandshakeRequest(frame.opcode)) {
+                    if (session && session.getSessionId() !== frame.sessionId) {
+                        this.logger.info(`Replacing stale session for ${message.pubkey} (old=${session.getSessionId()}, new=${frame.sessionId})`);
+                        session.close();
+                        session = undefined;
+                    }
+                    if (!session) {
+                        this.logger.info(`Auto-creating session for inbound peer ${message.pubkey} (sessionId=${frame.sessionId})`);
+                        session = this.createSession(message.pubkey, frame.sessionId);
+                    }
+                }
+                if (session) {
+                    session.handleIncomingFrame(frame);
+                }
+                else {
+                    this.logger.debug(`No session for peer ${message.pubkey}, ignoring frame opcode=0x${frame.opcode.toString(16)}`);
+                }
+            }
+            catch (error) {
+                this.logger.error(`Error processing frame from ${message.pubkey}:`, error);
+            }
+        });
+        // Friend requests
+        this.peer.onFriendRequest((request) => {
+            this.logger.info(`Friend request from ${request.pubkey}`);
+            this.emit("friend-request", request);
+        });
+    }
+}

package/dist/carrier/types.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Carrier-specific constants and re-exports
+ * Shared types live in src/types.ts (single source of truth)
+ */
+export type { PeerIdentity, RemotePeer, FriendConnectionEvent, PacketFrame, } from "../types.js";
+export declare const FRAME_OPCODE_HANDSHAKE_REQ = 1;
+export declare const FRAME_OPCODE_HANDSHAKE_ACK = 2;
+export declare const FRAME_OPCODE_DATA = 16;
+export declare const FRAME_MAGIC = 170;
+export declare const FRAME_HEADER_SIZE = 6;

package/dist/carrier/types.js

@@ -0,0 +1,11 @@
+/**
+ * Carrier-specific constants and re-exports
+ * Shared types live in src/types.ts (single source of truth)
+ */
+// Frame protocol opcodes
+export const FRAME_OPCODE_HANDSHAKE_REQ = 0x01;
+export const FRAME_OPCODE_HANDSHAKE_ACK = 0x02;
+export const FRAME_OPCODE_DATA = 0x10;
+// Frame structure
+export const FRAME_MAGIC = 0xaa;
+export const FRAME_HEADER_SIZE = 6; // magic(1) + length(2) + sessionId(2) + opcode(1)