@decentnetwork/beagle 0.1.0

package/dist/embedded-host.d.ts

@@ -0,0 +1,37 @@
+import type { IpcRequest, IpcResponse } from "./ipc.js";
+import type { PeerHost } from "./peer-host.js";
+export interface EmbeddedHostOptions {
+    configDir: string;
+    keyFile: string;
+    bootstrapNodes: {
+        host: string;
+        port: number;
+        pk: string;
+    }[];
+    expressNodes?: {
+        host: string;
+        port: number;
+        pk: string;
+        tls?: boolean;
+    }[];
+    nickname?: string;
+    statusMessage?: string;
+    autoAcceptFriends: boolean;
+    onProfileChange?: (info: {
+        name?: string;
+        description?: string;
+    }) => void;
+    onAutoAcceptChange?: (enabled: boolean) => void;
+}
+export declare class EmbeddedHost implements PeerHost {
+    #private;
+    readonly kind: "embedded";
+    readonly hasVirtualLan = false;
+    constructor(opts: EmbeddedHostOptions);
+    get downloadsDir(): string;
+    get outboxDir(): string;
+    start(): Promise<void>;
+    subscribe(emit: (event: Record<string, unknown>) => void): () => void;
+    stop(): Promise<void>;
+    call(req: IpcRequest): Promise<IpcResponse>;
+}

package/dist/embedded-host.js

@@ -0,0 +1,473 @@
+// Backend A — beagle owns the Carrier peer in-process.
+//
+// No daemon, no TUN, no root. This is the backend a regular user gets: install
+// beagle, run it, chat. It answers exactly the same op set as the decentlan
+// daemon (see ipc.ts), so the HTTP layer and the entire UI are unchanged —
+// which is what makes the two backends interchangeable.
+//
+// What is deliberately NOT here, versus the daemon: virtual IPs, exits, dora,
+// ACL, packet routing. Those are decentlan's job and need privilege beagle
+// refuses to ask for.
+import { EventEmitter } from "node:events";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile, unlink } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import { CarrierNode } from "./carrier-node.js";
+import { MessageStore } from "./message-store.js";
+import { FriendMetaStore } from "./friend-meta.js";
+import { Logger } from "./logger.js";
+/** Files bigger than this are not queued for an offline friend — the bytes sit
+ *  on disk until they reconnect, and an unbounded queue is how you fill a
+ *  user's disk by accident. Live transfers have no such limit. */
+const OUTBOX_MAX_FILE_BYTES = 25 * 1024 * 1024;
+/** Native (iOS/Android) clients receive files only as an inline envelope,
+ *  which is base64 (~1.34x) inside a 16MB bulkmsg cap. */
+const INLINE_MAX_BYTES = 11 * 1024 * 1024;
+const MEDIA_RE = /\.(jpe?g|png|gif|webp|heic|bmp|svg|mp4|mov|m4v|webm|mp3|m4a|wav|aac|ogg|flac)$/i;
+const isMediaFileName = (n) => MEDIA_RE.test(n);
+/** Strip any directory component and characters that would let a peer-supplied
+ *  name escape the downloads directory. A remote peer chooses this string. */
+function sanitizeFileName(name) {
+    const base = basename(String(name || "file")).replace(/[/\\]/g, "_");
+    // Control-character class written with \u escapes on purpose: it was
+    // originally spelled with RAW control bytes, which every viewer renders as an
+    // innocuous "[ -]" -- it reads like a class matching spaces and hyphens, and
+    // that misreading cost a wrong bug diagnosis.
+    // eslint-disable-next-line no-control-regex
+    const cleaned = base.replace(/^\.+/, "").replace(/[\u0000-\u001f\u007f]/g, "");
+    return cleaned.slice(0, 200) || "file";
+}
+export class EmbeddedHost {
+    kind = "embedded";
+    hasVirtualLan = false;
+    #node = new CarrierNode();
+    #messages;
+    #meta;
+    #logger = new Logger({ prefix: "Beagle" });
+    #opts;
+    #events = new EventEmitter();
+    /** Friend requests held for manual accept when auto-accept is off. */
+    #pending = new Map();
+    /** Inbound call signals waiting for the UI's long-poll to collect them. */
+    #callQueue = [];
+    #callWaiters = [];
+    /** fileId -> which chat message it belongs to, so progress can patch it. */
+    #activeSends = new Map();
+    #autoAccept;
+    constructor(opts) {
+        this.#opts = opts;
+        this.#autoAccept = opts.autoAcceptFriends;
+        this.#messages = new MessageStore(resolve(opts.configDir, "messages.json"));
+        this.#meta = new FriendMetaStore(resolve(opts.configDir, "friends-meta.json"));
+    }
+    get downloadsDir() {
+        return resolve(this.#opts.configDir, "downloads");
+    }
+    get outboxDir() {
+        return resolve(this.#opts.configDir, "outbox");
+    }
+    async start() {
+        await this.#node.create({
+            keyFile: this.#opts.keyFile,
+            bootstrapNodes: this.#opts.bootstrapNodes,
+            expressNodes: this.#opts.expressNodes,
+            nickname: this.#opts.nickname,
+            statusMessage: this.#opts.statusMessage,
+            fileResumeDir: resolve(this.#opts.configDir, "file-resume"),
+        });
+        this.#wire();
+        await this.#node.start();
+        await this.#node.join();
+        await mkdir(this.downloadsDir, { recursive: true }).catch(() => undefined);
+    }
+    #wire() {
+        this.#node.on("message", (pubkey, text, via) => {
+            // No status on an inbound message — MessageStore's status field tracks
+            // OUR delivery state (queued|sent|failed). `via` is the inbound signal:
+            // whether it arrived live or was pulled from offline storage.
+            this.#messages.append(pubkey, "in", text, Date.now(), undefined, via);
+            this.#meta.ensure(pubkey);
+            this.#events.emit("event", { type: "chat", userid: pubkey, dir: "in" });
+        });
+        this.#node.on("friend-request", (req) => {
+            const userid = req.userid ?? req.pubkey;
+            if (this.#autoAccept) {
+                void this.#node
+                    .acceptFriendRequest(req.pubkey)
+                    .then(() => this.#logger.info(`auto-accepted friend request from ${userid.slice(0, 8)}`))
+                    .catch((e) => this.#logger.warn(`accept failed: ${e.message}`));
+                return;
+            }
+            this.#pending.set(userid, {
+                userid,
+                pubkey: req.pubkey,
+                name: req.name,
+                hello: req.hello,
+                arrivedAt: Date.now(),
+            });
+            this.#events.emit("event", { type: "friend-request", userid });
+        });
+        this.#node.on("friend-connection", (e) => {
+            this.#events.emit("event", { type: "presence", userid: e.pubkey, status: e.status });
+            if (e.status === "connected")
+                void this.#flushOutbox(e.pubkey);
+        });
+        this.#node.on("call-signal", (evt) => {
+            this.#callQueue.push({ userid: evt.pubkey, data: Buffer.from(evt.data).toString("utf-8") });
+            // Release every long-poll waiting on this queue.
+            const waiters = this.#callWaiters.splice(0);
+            for (const w of waiters)
+                w();
+        });
+        // Inline files (the path native iOS/Android peers use).
+        this.#node.on("inline-file", (f) => {
+            void this.#saveIncoming(f.pubkey, f.name, Buffer.from(f.data));
+        });
+        // toxcore file transfer. The daemon logs an incoming file once, on
+        // completion — no "receiving" chip — and MessageStore's status enum has no
+        // such state anyway (queued|sending|sent|failed|cancelled). Match it.
+        this.#node.on("file-offer", (o) => {
+            this.#logger.info(`incoming "${o.name}" (${o.size}B) from ${o.friendId.slice(0, 8)} — accepting`);
+            try {
+                // Friend-only network: adding the friend was the trust decision.
+                this.#node.acceptFile(o.friendId, o.fileNumber);
+            }
+            catch (e) {
+                this.#logger.warn(`could not accept file: ${e.message}`);
+            }
+        });
+        this.#node.on("file-progress", (p) => {
+            // `sending` is authoritative for direction — no map scanning needed.
+            if (!p.sending)
+                return;
+            const s = this.#activeSends.get(p.fileId);
+            if (s)
+                this.#messages.patchFile(s.peer, s.msgId, { sent: p.received });
+        });
+        this.#node.on("file-complete", (p) => {
+            if (p.sending) {
+                const s = this.#activeSends.get(p.fileId);
+                if (!s)
+                    return;
+                this.#messages.patchFile(s.peer, s.msgId, { status: "sent", sent: p.size });
+                this.#activeSends.delete(p.fileId);
+                void unlink(resolve(this.outboxDir, s.msgId)).catch(() => undefined);
+                this.#events.emit("event", { type: "chat", userid: s.peer, dir: "out" });
+                return;
+            }
+            // Receiving side: data is present here.
+            if (p.data)
+                void this.#saveIncoming(p.friendId, p.name, Buffer.from(p.data));
+        });
+        this.#node.on("file-cancel", (p) => {
+            if (!p.sending)
+                return;
+            const s = this.#activeSends.get(p.fileId);
+            if (!s)
+                return;
+            this.#messages.patchFile(s.peer, s.msgId, { status: "cancelled" });
+            this.#activeSends.delete(p.fileId);
+        });
+    }
+    /** Persist a received file under downloads/ and log it in the thread. */
+    async #saveIncoming(pubkey, name, data) {
+        const safe = sanitizeFileName(name);
+        try {
+            await mkdir(this.downloadsDir, { recursive: true });
+            await writeFile(resolve(this.downloadsDir, safe), data);
+            this.#messages.appendFile(pubkey, "in", { name: safe, size: data.length });
+            this.#meta.ensure(pubkey);
+            this.#events.emit("event", { type: "chat", userid: pubkey, dir: "in" });
+            this.#logger.info(`saved "${safe}" (${data.length}B) from ${pubkey.slice(0, 8)}`);
+        }
+        catch (e) {
+            this.#logger.warn(`could not save incoming file: ${e.message}`);
+        }
+    }
+    /** Deliver anything queued while this friend was offline. */
+    async #flushOutbox(pubkey) {
+        // queuedOutgoing() exists for exactly this — it returns the queued text and
+        // file chips oldest-first. Reading history() and pattern-matching its shape
+        // would couple this to the store's serialization format for no reason.
+        for (const msg of this.#messages.queuedOutgoing(pubkey)) {
+            if (!msg.file)
+                continue;
+            const path = resolve(this.outboxDir, msg.id);
+            if (!existsSync(path))
+                continue;
+            try {
+                const data = await readFile(path);
+                const fileId = this.#node.sendFile(pubkey, new Uint8Array(data), msg.file.name);
+                if (fileId) {
+                    this.#messages.patchFile(pubkey, msg.id, { status: "sending", sent: 0 });
+                    this.#activeSends.set(fileId, { peer: pubkey, msgId: msg.id });
+                    this.#logger.info(`delivering queued "${msg.file.name}" to ${pubkey.slice(0, 8)}`);
+                }
+            }
+            catch (e) {
+                this.#logger.warn(`outbox flush failed: ${e.message}`);
+            }
+        }
+    }
+    subscribe(emit) {
+        const fn = (e) => emit(e);
+        this.#events.on("event", fn);
+        return () => this.#events.off("event", fn);
+    }
+    async stop() {
+        await this.#node.stop();
+    }
+    // -------------------------------------------------------------------------
+    // The op surface — same contract as the daemon's IPC.
+    // -------------------------------------------------------------------------
+    async call(req) {
+        try {
+            const data = await this.#dispatch(req);
+            return { ok: true, data: data ?? {} };
+        }
+        catch (error) {
+            return { ok: false, error: error.message };
+        }
+    }
+    async #dispatch(req) {
+        const uid = (req.userid ?? "");
+        switch (req.op) {
+            case "ping":
+                return { ok: true };
+            case "diag": {
+                const id = this.#node.identity();
+                return {
+                    identity: id,
+                    node: { name: this.#opts.nickname ?? "", backend: "embedded" },
+                    // No TUN in this backend — say so explicitly rather than omitting
+                    // the key, so the UI can distinguish "no LAN" from "unknown".
+                    tun: null,
+                    allocatedIp: null,
+                    dht: this.#node.dhtHealth(),
+                    friends: this.#node.friends().map((f) => ({
+                        ...f,
+                        session: this.#node.sessionStatus(f.pubkey),
+                    })),
+                    ipam: [],
+                    proxy: { enabled: false },
+                };
+            }
+            case "friends-list": {
+                const last = this.#messages.lastMessages();
+                return {
+                    friends: this.#node.friends().map((f) => {
+                        const meta = this.#meta.get(f.carrierId);
+                        const lastMsg = last.get(f.carrierId);
+                        return {
+                            userid: f.carrierId,
+                            alias: meta?.alias,
+                            name: meta?.alias || f.name || f.carrierId,
+                            status: f.status,
+                            lastSeen: f.acceptedAt,
+                            pinned: meta?.pinned ?? false,
+                            lastMessage: lastMsg ? { dir: lastMsg.dir, text: lastMsg.text, ts: lastMsg.ts } : undefined,
+                            unread: this.#messages.unreadCount(f.carrierId, meta?.lastReadTs ?? 0),
+                        };
+                    }),
+                };
+            }
+            case "friend-request":
+                await this.#node.sendFriendRequest(String(req.address ?? ""), req.hello);
+                return {};
+            case "friends-pending":
+                return { pending: [...this.#pending.values()] };
+            case "friends-accept": {
+                const entry = this.#pending.get(uid);
+                if (entry) {
+                    await this.#node.acceptFriendRequest(entry.pubkey);
+                    this.#pending.delete(uid);
+                }
+                return {};
+            }
+            case "friends-reject":
+                this.#pending.delete(uid);
+                return {};
+            case "friends-autoaccept": {
+                this.#autoAccept = Boolean(req.enabled);
+                this.#opts.onAutoAcceptChange?.(this.#autoAccept);
+                return { autoAccept: this.#autoAccept };
+            }
+            case "friend-remove":
+                this.#node.removeFriend(uid);
+                this.#messages.removePeer(uid);
+                this.#meta.remove(uid);
+                return {};
+            case "friend-set-alias":
+                this.#meta.setAlias(uid, req.alias);
+                return {};
+            case "set-profile": {
+                const info = { name: req.name, description: req.description };
+                this.#node.setUserInfo(info);
+                if (info.name)
+                    this.#opts.nickname = info.name;
+                if (info.description !== undefined)
+                    this.#opts.statusMessage = info.description;
+                this.#opts.onProfileChange?.(info);
+                return {};
+            }
+            case "sign": {
+                const sig = this.#node.sign(new TextEncoder().encode(String(req.text ?? "")));
+                return { sig: Buffer.from(sig).toString("hex"), userid: this.#node.identity().userid };
+            }
+            case "chat-send": {
+                const text = String(req.text ?? "");
+                await this.#node.sendText(uid, text);
+                this.#messages.append(uid, "out", text, Date.now(), "sent");
+                this.#meta.ensure(uid);
+                this.#events.emit("event", { type: "chat", userid: uid, dir: "out" });
+                return {};
+            }
+            case "chat-log-local":
+                this.#messages.append(uid, req.dir ?? "in", String(req.text ?? ""), Date.now());
+                this.#meta.ensure(uid);
+                return {};
+            case "file-log-local":
+                this.#messages.appendFile(uid, req.dir ?? "in", {
+                    name: sanitizeFileName(String(req.name ?? "file")),
+                    size: Number(req.size ?? 0),
+                });
+                this.#meta.ensure(uid);
+                return {};
+            case "chat-history":
+                return {
+                    chats: this.#messages.history(req.peer, {
+                        before: req.before,
+                        limit: req.limit,
+                    }),
+                };
+            case "chat-mark-read":
+                this.#meta.markRead(uid, req.ts ?? Date.now());
+                return {};
+            case "file-send":
+                return this.#fileSend(uid, String(req.path ?? ""));
+            case "file-delete": {
+                const removed = this.#messages.deleteMessages(req.peer, req.ids ?? []);
+                for (const m of removed) {
+                    if (!m.file?.name)
+                        continue;
+                    void unlink(resolve(this.downloadsDir, sanitizeFileName(m.file.name))).catch(() => undefined);
+                }
+                return { removed: removed.length };
+            }
+            case "file-cancel": {
+                let cancelled = 0;
+                for (const id of req.ids ?? []) {
+                    for (const [fileId, s] of this.#activeSends) {
+                        if (s.msgId !== id)
+                            continue;
+                        if (this.#node.cancelSend(s.peer, fileId))
+                            cancelled++;
+                        this.#activeSends.delete(fileId);
+                        this.#messages.patchFile(s.peer, id, { status: "failed" });
+                    }
+                }
+                return { cancelled };
+            }
+            case "file-retry": {
+                let retried = 0;
+                for (const id of req.ids ?? []) {
+                    const path = resolve(this.outboxDir, id);
+                    if (!existsSync(path))
+                        continue;
+                    const data = await readFile(path);
+                    const fileId = this.#node.sendFile(req.peer, new Uint8Array(data), `retry-${id}`);
+                    if (fileId) {
+                        this.#activeSends.set(fileId, { peer: req.peer, msgId: id });
+                        this.#messages.patchFile(req.peer, id, { status: "sending", sent: 0 });
+                        retried++;
+                    }
+                }
+                return { retried };
+            }
+            case "call-signal":
+                await this.#node.sendCallSignal(uid, String(req.text ?? req.data ?? ""));
+                return {};
+            case "call-poll":
+                return { signals: await this.#pollCalls() };
+            default:
+                throw new Error(`Unsupported op in embedded backend: ${req.op}`);
+        }
+    }
+    /** Long-poll: return immediately if signals are queued, else hold ~20s. The
+     *  UI re-polls, which gives near-instant offer/answer delivery without a
+     *  WebSocket. Matches the daemon's behaviour exactly so call.jsx is unchanged. */
+    async #pollCalls() {
+        if (this.#callQueue.length)
+            return this.#callQueue.splice(0);
+        await new Promise((res) => {
+            const done = () => {
+                clearTimeout(timer);
+                res();
+            };
+            const timer = setTimeout(() => {
+                const i = this.#callWaiters.indexOf(done);
+                if (i >= 0)
+                    this.#callWaiters.splice(i, 1);
+                res();
+            }, 20_000);
+            timer.unref?.();
+            this.#callWaiters.push(done);
+        });
+        return this.#callQueue.splice(0);
+    }
+    async #fileSend(userid, path) {
+        const data = await readFile(path);
+        const name = basename(path);
+        const safe = sanitizeFileName(name);
+        // Keep a local copy of outgoing media so the sender can preview it too —
+        // the UI uploads to a temp file that is deleted right after send.
+        if (isMediaFileName(safe)) {
+            void (async () => {
+                try {
+                    await mkdir(this.downloadsDir, { recursive: true });
+                    await writeFile(resolve(this.downloadsDir, safe), data);
+                }
+                catch {
+                    // preview cache is best-effort
+                }
+            })();
+        }
+        if (!this.#node.isFriendOnline(userid)) {
+            if (data.length > OUTBOX_MAX_FILE_BYTES) {
+                throw new Error(`Peer is offline — queued files are limited to ${(OUTBOX_MAX_FILE_BYTES / 1024 / 1024) | 0} MB ` +
+                    `(this is ${(data.length / 1024 / 1024).toFixed(1)} MB). Send it once they're online.`);
+            }
+            const msg = this.#messages.appendFile(userid, "out", { name: safe, size: data.length, status: "queued", sent: 0 });
+            if (!msg)
+                throw new Error("Could not queue file");
+            await mkdir(this.outboxDir, { recursive: true });
+            await writeFile(resolve(this.outboxDir, msg.id), data);
+            this.#meta.ensure(userid);
+            this.#events.emit("event", { type: "chat", userid, dir: "out" });
+            return { queued: true, name: safe, size: data.length };
+        }
+        const msg = this.#messages.appendFile(userid, "out", { name: safe, size: data.length, status: "sending", sent: 0 });
+        if (!msg)
+            throw new Error("Could not create file message");
+        await mkdir(this.outboxDir, { recursive: true });
+        await writeFile(resolve(this.outboxDir, msg.id), data);
+        const fileId = this.#node.sendFile(userid, new Uint8Array(data), safe);
+        if (!fileId) {
+            // No transfer slot — try the inline envelope, which is also the only
+            // path a native iOS/Android friend can receive at all.
+            if (data.length > INLINE_MAX_BYTES) {
+                this.#messages.patchFile(userid, msg.id, { status: "failed" });
+                throw new Error(`Could not start the transfer, and the file is too large (${(data.length / 1024 / 1024).toFixed(1)} MB) ` +
+                    `for the inline fallback (limit ${(INLINE_MAX_BYTES / 1024 / 1024).toFixed(1)} MB).`);
+            }
+            await this.#node.sendInlineFile(userid, new Uint8Array(data), safe);
+            this.#messages.patchFile(userid, msg.id, { status: "sent", sent: data.length });
+            this.#events.emit("event", { type: "chat", userid, dir: "out" });
+            return { inline: true, name: safe, size: data.length };
+        }
+        this.#activeSends.set(fileId, { peer: userid, msgId: msg.id });
+        this.#meta.ensure(userid);
+        this.#events.emit("event", { type: "chat", userid, dir: "out" });
+        return { fileId, name: safe, size: data.length };
+    }
+}

package/dist/exits.d.ts

@@ -0,0 +1,7 @@
+export interface DefaultExit {
+    name: string;
+    userid: string;
+    virtual_ip?: string;
+    region?: string;
+}
+export declare const DEFAULT_EXITS: DefaultExit[];

package/dist/exits.js

@@ -0,0 +1,24 @@
+// The official exit-node table, used only by the network panel (which itself
+// only renders when a decentlan daemon is providing the virtual LAN).
+//
+// Shipped as data in this repo rather than imported from @decentnetwork/lan:
+// that package exports only ".", and this is a small static table. Phase 3 of
+// the split moves the whole network panel behind the backend-B check, at which
+// point this file follows it.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import yaml from "js-yaml";
+function load() {
+    try {
+        // dist/exits.js -> ../config/default-exits.yaml
+        const file = resolve(dirname(fileURLToPath(import.meta.url)), "..", "config", "default-exits.yaml");
+        const parsed = yaml.load(readFileSync(file, "utf-8"));
+        return (parsed?.exits ?? []).filter((e) => e && e.userid);
+    }
+    catch {
+        // A missing table degrades the exits list, never the app.
+        return [];
+    }
+}
+export const DEFAULT_EXITS = load();

package/dist/friend-meta.d.ts

@@ -0,0 +1,36 @@
+/**
+ * On-disk friend metadata — local-only UI state that the Carrier friend store
+ * doesn't hold (PRD-DESKTOP-UI §2.2): a local alias, a read cursor for unread
+ * badges, pin/order, and when we added them.
+ *
+ * File: <configDir>/friends-meta.json  ->  { userid: FriendMeta }
+ * Keyed by userid. Identity/accept-state still lives in the Carrier friend
+ * store; this only augments it for display.
+ */
+export interface FriendMeta {
+    userid: string;
+    /** Local display name; falls back to the userid in the UI when absent. */
+    alias?: string;
+    pinned?: boolean;
+    /** ts of the newest message the user has seen — drives unread counts. */
+    lastReadTs?: number;
+    addedAt: number;
+}
+export declare class FriendMetaStore {
+    private path;
+    private byUserid;
+    private logger;
+    private saveTimer?;
+    private dirty;
+    constructor(path: string);
+    private load;
+    get(userid: string): FriendMeta;
+    /** Ensure an entry exists (first time we see a friend). */
+    ensure(userid: string): FriendMeta;
+    setAlias(userid: string, alias: string | undefined): void;
+    markRead(userid: string, ts?: number): void;
+    setPinned(userid: string, pinned: boolean): void;
+    remove(userid: string): void;
+    private scheduleSave;
+    flush(): void;
+}

package/dist/friend-meta.js

@@ -0,0 +1,97 @@
+/**
+ * On-disk friend metadata — local-only UI state that the Carrier friend store
+ * doesn't hold (PRD-DESKTOP-UI §2.2): a local alias, a read cursor for unread
+ * badges, pin/order, and when we added them.
+ *
+ * File: <configDir>/friends-meta.json  ->  { userid: FriendMeta }
+ * Keyed by userid. Identity/accept-state still lives in the Carrier friend
+ * store; this only augments it for display.
+ */
+import { existsSync, readFileSync, writeFileSync, renameSync } from "fs";
+import { Logger } from "./logger.js";
+export class FriendMetaStore {
+    path;
+    byUserid = new Map();
+    logger = new Logger({ prefix: "FriendMeta" });
+    saveTimer;
+    dirty = false;
+    constructor(path) {
+        this.path = path;
+        this.load();
+    }
+    load() {
+        if (!existsSync(this.path))
+            return;
+        try {
+            const raw = JSON.parse(readFileSync(this.path, "utf-8"));
+            for (const [userid, meta] of Object.entries(raw)) {
+                if (meta && typeof meta === "object")
+                    this.byUserid.set(userid, { ...meta, userid });
+            }
+            this.logger.info(`Loaded metadata for ${this.byUserid.size} friends`);
+        }
+        catch (err) {
+            this.logger.warn(`Could not load ${this.path}: ${err}`);
+        }
+    }
+    get(userid) {
+        return this.byUserid.get(userid) ?? { userid, addedAt: Date.now() };
+    }
+    /** Ensure an entry exists (first time we see a friend). */
+    ensure(userid) {
+        let m = this.byUserid.get(userid);
+        if (!m) {
+            m = { userid, addedAt: Date.now() };
+            this.byUserid.set(userid, m);
+            this.scheduleSave();
+        }
+        return m;
+    }
+    setAlias(userid, alias) {
+        const m = this.ensure(userid);
+        m.alias = alias && alias.trim() ? alias.trim() : undefined;
+        this.scheduleSave();
+    }
+    markRead(userid, ts = Date.now()) {
+        const m = this.ensure(userid);
+        if (!m.lastReadTs || ts > m.lastReadTs) {
+            m.lastReadTs = ts;
+            this.scheduleSave();
+        }
+    }
+    setPinned(userid, pinned) {
+        const m = this.ensure(userid);
+        m.pinned = pinned || undefined;
+        this.scheduleSave();
+    }
+    remove(userid) {
+        if (this.byUserid.delete(userid))
+            this.scheduleSave();
+    }
+    scheduleSave() {
+        this.dirty = true;
+        if (this.saveTimer)
+            return;
+        this.saveTimer = setTimeout(() => {
+            this.saveTimer = undefined;
+            this.flush();
+        }, 1000);
+        this.saveTimer.unref?.();
+    }
+    flush() {
+        if (!this.dirty)
+            return;
+        this.dirty = false;
+        try {
+            const obj = {};
+            for (const [u, m] of this.byUserid)
+                obj[u] = m;
+            const tmp = `${this.path}.tmp`;
+            writeFileSync(tmp, JSON.stringify(obj, null, 2), "utf-8");
+            renameSync(tmp, this.path);
+        }
+        catch (err) {
+            this.logger.warn(`Could not save ${this.path}: ${err}`);
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { startBeagleServer, type BeagleServerOptions } from "./server.js";
+export { openPeerHost, defaultConfigDir, decentlanCarrierDir, type PeerHost, type BackendKind } from "./peer-host.js";
+export { ipcCall, ipcSocketPath, daemonIsRunning, type IpcRequest, type IpcResponse, type IpcOp } from "./ipc.js";