@decentnetwork/beagle-service 0.0.0-stage → 0.2.0

package/dist/agent.d.ts

@@ -0,0 +1,18 @@
+import type { Agent, AgentConfig, AgentServers, Users } from "./types.js";
+import { type Logger } from "./util.js";
+/** The public server list the Beagle apps read: bootstrap and Express nodes
+ *  of the Carrier network. Any list in the same format can stand in for it. */
+export declare const DEFAULT_SERVERS_URL = "https://beagle.chat/assets/bgservers.json";
+export interface AgentOptions {
+    config: AgentConfig;
+    users: Users;
+    /** Directory for the agent's files. */
+    dir: string;
+    now?: () => number;
+    log?: Logger;
+    fetch?: typeof fetch;
+}
+/** Bootstrap and Express nodes from a `bgservers.json`-format list. The last
+ *  good answer is kept on disk, so a restart works while the URL is down. */
+export declare function loadServers(source: AgentServers | string | undefined, cacheFile: string, doFetch: typeof fetch, log: Logger): Promise<AgentServers>;
+export declare function createAgent(o: AgentOptions): Promise<Agent>;

package/dist/agent.js

@@ -0,0 +1,448 @@
+import { mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { Outbox } from "./outbox.js";
+import { addressOf, atomicWriteJson, Hub, isUserid, msgOf, readJsonFile } from "./util.js";
+/** The public server list the Beagle apps read: bootstrap and Express nodes
+ *  of the Carrier network. Any list in the same format can stand in for it. */
+export const DEFAULT_SERVERS_URL = "https://beagle.chat/assets/bgservers.json";
+const DAY_MS = 86_400_000;
+/** Bootstrap and Express nodes from a `bgservers.json`-format list. The last
+ *  good answer is kept on disk, so a restart works while the URL is down. */
+export async function loadServers(source, cacheFile, doFetch, log) {
+    if (source && typeof source === "object")
+        return source;
+    const url = source ?? DEFAULT_SERVERS_URL;
+    const node = (n) => ({ host: n.ipv4 ?? n.host, port: Number(n.port), pk: n.publicKey ?? n.pk });
+    const usable = (n) => typeof n.host === "string" && n.host.length > 0 && Number.isFinite(n.port);
+    try {
+        const r = await doFetch(url, { signal: AbortSignal.timeout(10_000) });
+        if (!r.ok)
+            throw new Error(`HTTP ${r.status}`);
+        const list = await r.json();
+        const servers = {
+            bootstrapNodes: (Array.isArray(list?.bootstrapNodes) ? list.bootstrapNodes : []).map(node).filter(usable),
+            expressNodes: (Array.isArray(list?.expressNodes) ? list.expressNodes : []).map(node).filter(usable),
+        };
+        if (!servers.bootstrapNodes.length)
+            throw new Error("the list has no bootstrap nodes");
+        atomicWriteJson(cacheFile, servers);
+        return servers;
+    }
+    catch (e) {
+        const cached = readJsonFile(cacheFile, null);
+        if (cached?.bootstrapNodes?.length) {
+            log(`beagle-service: could not load the server list from ${url} (${msgOf(e)}); using the copy from the last start`);
+            return cached;
+        }
+        throw new Error(`beagle-service: could not load the server list from ${url}: ${msgOf(e)}. Pass agent.servers = { bootstrapNodes, expressNodes } or a reachable URL.`);
+    }
+}
+export async function createAgent(o) {
+    const { config, users, dir } = o;
+    const now = o.now ?? Date.now;
+    const log = o.log ?? (() => { });
+    const hub = new Hub(log);
+    const policy = config.accept ?? "signed-in";
+    const befriendOn = config.befriendOn ?? "never";
+    const holdMs = (config.holdDays ?? 7) * DAY_MS;
+    const timing = config.timing ?? {};
+    const liveAckMs = timing.liveAckMs ?? 4_000;
+    const proofWindowMs = timing.proofWindowMs ?? 15_000;
+    const iso = (t) => new Date(t).toISOString();
+    mkdirSync(dir, { recursive: true });
+    const keyFile = config.keyFile ?? join(dir, "peer.save");
+    mkdirSync(dirname(keyFile), { recursive: true });
+    // ── the peer ──────────────────────────────────────────────────────────────
+    const servers = await loadServers(config.servers, join(dir, "servers.json"), o.fetch ?? fetch, log);
+    if (!servers.expressNodes?.length) {
+        log("beagle-service: no Express node is configured; a message to a friend who is offline will wait until they are back");
+    }
+    const peerOpts = {
+        keyFile,
+        bootstrapNodes: servers.bootstrapNodes,
+        expressNodes: servers.expressNodes ?? [],
+        ...(config.nickname ? { nickname: config.nickname } : {}),
+        ...(config.statusMessage ? { statusMessage: config.statusMessage } : {}),
+        platform: "agent",
+        ...(config.punkId != null ? { punkId: config.punkId } : {}),
+        ...(config.avatarUrl ? { profile: { avatarUrl: config.avatarUrl } } : {}),
+        ...config.peerOptions,
+    };
+    const peer = config.createPeer ? await config.createPeer(peerOpts) : await (await import("@decentnetwork/peer")).Peer.create(peerOpts);
+    // ── state on disk ─────────────────────────────────────────────────────────
+    const pendingFile = join(dir, "pending.json");
+    const askedFile = join(dir, "asked.json");
+    const pending = new Map();
+    for (const e of readJsonFile(pendingFile, []))
+        if (e && typeof e.userid === "string")
+            pending.set(e.userid, e);
+    const asked = readJsonFile(askedFile, {});
+    /** Userids a friend request is being sent to right now. */
+    const asking = new Set();
+    const savePending = () => atomicWriteJson(pendingFile, [...pending.values()]);
+    const saveAsked = () => atomicWriteJson(askedFile, asked);
+    const friendOf = (userid) => peer.friends().find((f) => (f.userid ?? f.pubkey) === userid || f.pubkey === userid);
+    /** Settled both ways as far as this side can know: we accepted them, or a
+     *  session came up after we asked. */
+    const isFriend = (userid) => {
+        const f = friendOf(userid);
+        return !!f && (f.acceptedAt != null || f.status === "online");
+    };
+    const outbox = new Outbox({
+        file: join(dir, "outbox.json"),
+        deadFile: join(dir, "dead-letter.jsonl"),
+        now,
+        log,
+        baseDelayMs: timing.baseDelayMs,
+        maxDelayMs: timing.maxDelayMs,
+        maxAgeMs: (config.maxQueueHours ?? 72) * 3_600_000,
+        onDelivered: (e) => void hub.emit("delivered", e),
+        onDead: (d) => void hub.emit("dead-letter", d),
+        transport: {
+            relation: (userid) => (isFriend(userid) ? "friend" : friendOf(userid) || asked[userid] || asking.has(userid) || pending.has(userid) ? "pending" : "none"),
+            proven: (userid) => {
+                if (friendOf(userid)?.status !== "online")
+                    return false;
+                const s = peer.sessionStatus(userid);
+                return !!s?.established && typeof s.lastPingRecvMs === "number" && Date.now() - s.lastPingRecvMs < proofWindowMs;
+            },
+            sendLive: async (userid, text, deliveryId) => {
+                // A friend that reads the delivery envelope must confirm within the
+                // window; any other gets the SDK's own answer.
+                if ((friendOf(userid)?.protoVersion ?? 0) >= 2) {
+                    await peer.sendTextUntilAck(userid, text, { deliveryId, timeoutMs: liveAckMs, retryIntervalMs: liveAckMs });
+                    return "acked";
+                }
+                return (await peer.sendText(userid, text)).delivery;
+            },
+            sendExpress: async (userid, text, deliveryId) => {
+                await peer.sendTextViaExpress(userid, text, { deliveryId });
+            },
+        },
+    });
+    // ── the friend policy ─────────────────────────────────────────────────────
+    const publicRequest = ({ pubkey: _p, nospam: _n, ...rest }) => rest;
+    async function decide(entry, user) {
+        if (user?.status === "blocked")
+            return "reject";
+        if (policy === "all")
+            return "accept";
+        if (policy === "manual")
+            return "hold";
+        if (policy === "signed-in")
+            return user && user.firstSeen ? "accept" : "hold";
+        if (policy === "registered")
+            return user?.status === "registered" ? "accept" : "hold";
+        try {
+            const v = await policy(publicRequest(entry), user);
+            return v === true ? "accept" : v === "reject" ? "reject" : "hold";
+        }
+        catch (e) {
+            log(`beagle-service: the accept policy threw for ${entry.userid.slice(0, 8)}: ${msgOf(e)}; the request is held`);
+            return "hold";
+        }
+    }
+    /** Userids being accepted right now: a sign-in and a registration can ask
+     *  for the same held request to be looked at in the same moment. */
+    const accepting = new Set();
+    async function acceptEntry(entry) {
+        if (accepting.has(entry.userid))
+            return;
+        accepting.add(entry.userid);
+        try {
+            await peer.acceptFriendRequest(entry.pubkey, {
+                name: entry.name,
+                description: entry.description,
+                hello: entry.hello,
+                address: entry.address,
+                nospam: entry.nospam,
+            });
+        }
+        finally {
+            accepting.delete(entry.userid);
+        }
+        if (pending.delete(entry.userid))
+            savePending();
+        // The request came from that key over the network: its address is at
+        // least as good as the unsigned hint from sign-in.
+        const address = addressOf(entry.userid, entry.address);
+        if (address) {
+            const user = await users.get(entry.userid);
+            if (user && !user.address)
+                await users.update(entry.userid, { address }).catch(() => { });
+        }
+        void hub.emit("friend-accepted", { userid: entry.userid });
+        outbox.kick(entry.userid);
+    }
+    function refuseEntry(entry, why) {
+        try {
+            peer.rejectFriendRequest(entry.pubkey);
+        }
+        catch (e) {
+            log(`beagle-service: rejecting ${entry.userid.slice(0, 8)} failed: ${msgOf(e)}`);
+        }
+        if (pending.delete(entry.userid))
+            savePending();
+        void hub.emit("friend-refused", { userid: entry.userid, why });
+    }
+    async function onRequest(req) {
+        const userid = req.userid ?? req.pubkey;
+        const entry = {
+            userid,
+            pubkey: req.pubkey,
+            ...(req.address ? { address: req.address } : {}),
+            ...(req.nospam != null ? { nospam: req.nospam } : {}),
+            ...(req.name ? { name: req.name } : {}),
+            ...(req.description ? { description: req.description } : {}),
+            ...(req.hello ? { hello: req.hello } : {}),
+            ...(req.punkId != null ? { punkId: req.punkId } : {}),
+            ...(req.avatarUrl ? { avatarUrl: req.avatarUrl } : {}),
+            arrivedAt: iso(now()),
+        };
+        const user = await users.get(userid);
+        const verdict = await decide(entry, user);
+        if (verdict === "accept")
+            return acceptEntry(entry);
+        if (verdict === "reject")
+            return refuseEntry(entry, user?.status === "blocked" ? "blocked" : "policy");
+        // Not allowed yet: keep it. It is looked at again when the sender signs
+        // in, registers or is unblocked, and at every start.
+        pending.set(userid, entry);
+        savePending();
+        void hub.emit("request-held", publicRequest(entry));
+    }
+    /** Look at a held request again; accept it when its sender qualifies now. */
+    async function recheck(userid) {
+        const entry = pending.get(userid);
+        if (!entry)
+            return false;
+        const user = await users.get(userid);
+        const verdict = await decide(entry, user);
+        if (verdict === "accept") {
+            await acceptEntry(entry);
+            return true;
+        }
+        if (verdict === "reject")
+            refuseEntry(entry, user?.status === "blocked" ? "blocked" : "policy");
+        return false;
+    }
+    function sweepHeld() {
+        const t = now();
+        for (const entry of [...pending.values()]) {
+            if (t - Date.parse(entry.arrivedAt) > holdMs)
+                refuseEntry(entry, "expired");
+        }
+    }
+    // ── befriending from our side ─────────────────────────────────────────────
+    async function befriend(userid, opts = {}) {
+        const user = await users.get(userid);
+        if (!user)
+            return { ok: false, reason: "unknown-user" };
+        if (user.status === "blocked")
+            return { ok: false, reason: "blocked" };
+        if (isFriend(userid) && !opts.force)
+            return { ok: true, how: "already-friends" };
+        // They asked first: saying yes is the whole handshake.
+        const held = pending.get(userid);
+        if (held) {
+            await acceptEntry(held);
+            return { ok: true, how: "accepted" };
+        }
+        if (!user.address)
+            return { ok: false, reason: "no-address" };
+        if (asked[userid] && !opts.force)
+            return { ok: true, how: "already-asked" };
+        asking.add(userid);
+        try {
+            await peer.sendFriendRequest(user.address, opts.hello ?? config.hello ?? config.nickname ?? "", opts.force ? { force: true } : undefined);
+            asked[userid] = iso(now());
+            saveAsked();
+            return { ok: true, how: "requested" };
+        }
+        catch (e) {
+            // Not marked as asked, so the next sign-in tries again.
+            log(`beagle-service: friend request to ${userid.slice(0, 8)} failed: ${msgOf(e)}`);
+            return { ok: false, reason: "send-failed", error: msgOf(e) };
+        }
+        finally {
+            asking.delete(userid);
+        }
+    }
+    async function onQualify(user, what) {
+        const wants = befriendOn === what;
+        if (wants)
+            asking.add(user.userid);
+        try {
+            const accepted = await recheck(user.userid);
+            if (wants && !accepted)
+                await befriend(user.userid);
+        }
+        catch (e) {
+            log(`beagle-service: friend handling for ${user.userid.slice(0, 8)} failed: ${msgOf(e)}`);
+        }
+        finally {
+            if (wants)
+                asking.delete(user.userid);
+        }
+    }
+    function unfriend(userid) {
+        if (asked[userid]) {
+            delete asked[userid];
+            saveAsked();
+        }
+        if (!friendOf(userid))
+            return false;
+        const removed = peer.removeFriend(userid);
+        if (removed)
+            void hub.emit("friend-removed", { userid });
+        return removed;
+    }
+    function onBlocked(user) {
+        const held = pending.get(user.userid);
+        if (held)
+            refuseEntry(held, "blocked");
+        try {
+            unfriend(user.userid);
+        }
+        catch (e) {
+            log(`beagle-service: removing blocked ${user.userid.slice(0, 8)} failed: ${msgOf(e)}`);
+        }
+        outbox.dropFor(user.userid, "blocked");
+    }
+    // ── messages ──────────────────────────────────────────────────────────────
+    const messageHandlers = new Set();
+    async function send(userid, text) {
+        if (typeof text !== "string" || text.length === 0)
+            throw new TypeError("beagle-service: agent.send needs a non-empty text");
+        const receipt = (items, state, why) => ({
+            id: items[0].id,
+            deliveryIds: items.map((i) => i.deliveryId),
+            state,
+            ...(why ? { why } : {}),
+        });
+        if (!isUserid(userid))
+            return receipt(outbox.refuse(String(userid), text, "bad-address"), "dead", "bad-address");
+        const user = await users.get(userid);
+        if (user?.status === "blocked")
+            return receipt(outbox.refuse(userid, text, "blocked"), "dead", "blocked");
+        if (!friendOf(userid) && !asked[userid] && !asking.has(userid) && !pending.has(userid)) {
+            return receipt(outbox.refuse(userid, text, "not-a-friend"), "dead", "not-a-friend");
+        }
+        const items = outbox.enqueue(userid, text);
+        // On disk now. Delivery starts on the next turn of the event loop, so the
+        // caller's own `await` continues first.
+        setImmediate(() => void outbox.pump());
+        return receipt(items, "queued");
+    }
+    // Handlers are registered before start(), as the peer expects.
+    peer.onFriendRequest((req) => {
+        void onRequest(req).catch((e) => log(`beagle-service: friend request handling failed: ${msgOf(e)}`));
+    });
+    peer.onFriendConnection((ev) => {
+        if (ev.status === "connected")
+            outbox.kick(ev.pubkey);
+    });
+    peer.onText(async (msg) => {
+        // The SDK has acknowledged receipt already; a slow handler delays nothing.
+        const userid = msg.pubkey;
+        const user = await users.get(userid);
+        if (user?.status === "blocked")
+            return;
+        const message = {
+            userid,
+            user,
+            text: msg.text,
+            ...(msg.deliveryId ? { deliveryId: msg.deliveryId } : {}),
+            ...(msg.via ? { via: msg.via } : {}),
+            reply: (t) => send(userid, t),
+        };
+        for (const cb of [...messageHandlers]) {
+            try {
+                await cb(message);
+            }
+            catch (e) {
+                log(`beagle-service: an onMessage handler threw: ${msgOf(e)}`);
+            }
+        }
+    });
+    const offs = [
+        users.on("sign-in", (user) => void onQualify(user, "sign-in")),
+        users.on("registered", (user) => void onQualify(user, "register")),
+        users.on("unblocked", (user) => void recheck(user.userid).catch(() => { })),
+        users.on("blocked", (user) => onBlocked(user)),
+    ];
+    // ── start ─────────────────────────────────────────────────────────────────
+    await peer.start();
+    let stopped = false;
+    const sleep = (ms) => new Promise((r) => setTimeout(r, ms).unref?.());
+    const ready = (async () => {
+        for (let n = 0; !stopped; n++) {
+            try {
+                await peer.joinNetwork();
+                return;
+            }
+            catch (e) {
+                log(`beagle-service: joining the network failed (${msgOf(e)}); trying again`);
+                await sleep(Math.min(60_000, 5_000 * 2 ** Math.min(n, 4)));
+            }
+        }
+    })();
+    // Requests held from an earlier run: their senders may qualify by now.
+    sweepHeld();
+    for (const userid of [...pending.keys()])
+        void recheck(userid).catch(() => { });
+    const pumpTimer = setInterval(() => void outbox.pump(), timing.pumpMs ?? 3_000);
+    const sweepTimer = setInterval(sweepHeld, 10 * 60_000);
+    pumpTimer.unref?.();
+    sweepTimer.unref?.();
+    setImmediate(() => void outbox.pump());
+    return {
+        userid: peer.userid(),
+        address: peer.address(),
+        nickname: config.nickname,
+        ready,
+        peer,
+        send,
+        onMessage: (cb) => {
+            messageHandlers.add(cb);
+            return () => messageHandlers.delete(cb);
+        },
+        befriend,
+        isFriend,
+        pending: () => [...pending.values()].map(publicRequest),
+        accept: async (userid) => {
+            const entry = pending.get(userid);
+            if (!entry)
+                return false;
+            const user = await users.get(userid);
+            if (user?.status === "blocked") {
+                refuseEntry(entry, "blocked");
+                return false;
+            }
+            await acceptEntry(entry);
+            return true;
+        },
+        reject: async (userid) => {
+            const entry = pending.get(userid);
+            if (!entry)
+                return false;
+            refuseEntry(entry, "manual");
+            return true;
+        },
+        unfriend,
+        outbox: () => outbox.list(),
+        deadLetters: () => outbox.deadLetters(),
+        on: (event, cb) => hub.on(event, cb),
+        stop: async () => {
+            if (stopped)
+                return;
+            stopped = true;
+            clearInterval(pumpTimer);
+            clearInterval(sweepTimer);
+            outbox.stop();
+            for (const off of offs)
+                off();
+            await peer.stop();
+        },
+    };
+}

package/dist/auth.d.ts

@@ -0,0 +1,28 @@
+import type { Auth, HeadersCarrier, OriginsSource, SessionConfig, StateStore, Users } from "./types.js";
+import { type Logger } from "./util.js";
+/** How long a nonce lives, and how far a launch timestamp may be from now. */
+export declare const NONCE_TTL_MS = 120000;
+export declare const LAUNCH_MAX_AGE_MS = 120000;
+/** Turn the configured list into exact origins. Throws on anything that is
+ *  not `scheme://host[:port]`, so a typo is found at start, not as a sign-in
+ *  that never verifies. */
+export declare function normalizeOrigins(list: unknown): Set<string>;
+/** Throw now if the configured origins cannot be used. A function is called once. */
+export declare function checkOrigins(source: OriginsSource | Set<string>): void;
+/** The signing secret: the configured one, else a 32-byte one kept in `file`. */
+export declare function loadSecret(configured: string | undefined, file: string): string;
+export declare function headerOf(req: HeadersCarrier | undefined, name: string): string | undefined;
+export interface AuthOptions {
+    /** A list, a function that returns the list as it is now, or the set
+     *  `normalizeOrigins` made. */
+    origins: OriginsSource | Set<string>;
+    state: StateStore;
+    users: Users;
+    secret: string;
+    /** Binds nonces to this server; see `BeagleServiceConfig.serverId`. */
+    serverId?: string;
+    session?: SessionConfig;
+    now?: () => number;
+    log?: Logger;
+}
+export declare function createAuth(opts: AuthOptions): Auth;