@decentnetwork/peer 0.1.0

package/dist/runtime/errors.d.ts

@@ -0,0 +1,3 @@
+export declare class LegacyProtocolNotImplementedError extends Error {
+    constructor(area: string);
+}

package/dist/runtime/errors.js

@@ -0,0 +1,6 @@
+export class LegacyProtocolNotImplementedError extends Error {
+    constructor(area) {
+        super(`${area} is not implemented: legacy Carrier/toxcore wire compatibility is still unresolved`);
+        this.name = "LegacyProtocolNotImplementedError";
+    }
+}

package/dist/runtime/events.d.ts

@@ -0,0 +1,4 @@
+export type PeerEventMap = {
+    friendRequest: unknown;
+    text: unknown;
+};

package/dist/runtime/events.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/lifecycle.d.ts

@@ -0,0 +1,7 @@
+export type LifecycleState = "stopped" | "started";
+export declare class Lifecycle {
+    #private;
+    get state(): LifecycleState;
+    markStarted(): void;
+    markStopped(): void;
+}

package/dist/runtime/lifecycle.js

@@ -0,0 +1,12 @@
+export class Lifecycle {
+    #state = "stopped";
+    get state() {
+        return this.#state;
+    }
+    markStarted() {
+        this.#state = "started";
+    }
+    markStopped() {
+        this.#state = "stopped";
+    }
+}

package/dist/store/config.d.ts

@@ -0,0 +1,2 @@
+import type { PeerOptions } from "../types/peer.js";
+export type StoredPeerConfig = PeerOptions;

package/dist/store/config.js

@@ -0,0 +1 @@
+export {};

package/dist/store/friends.d.ts

@@ -0,0 +1,13 @@
+export type FriendRecord = {
+    pubkey: string;
+    userid?: string;
+    address?: string;
+    nospam?: number;
+    name?: string;
+    description?: string;
+    status: "requested" | "offline" | "online";
+    remoteHost?: string;
+    remotePort?: number;
+    hello?: string;
+    acceptedAt?: number;
+};

package/dist/store/friends.js

@@ -0,0 +1 @@
+export {};

package/dist/store/state.d.ts

@@ -0,0 +1,3 @@
+export type PeerState = {
+    pubkey?: string;
+};

package/dist/store/state.js

@@ -0,0 +1 @@
+export {};

package/dist/transport/socket.d.ts

@@ -0,0 +1,4 @@
+export type TransportEndpoint = {
+    host: string;
+    port: number;
+};

package/dist/transport/socket.js

@@ -0,0 +1 @@
+export {};

package/dist/transport/tcp.d.ts

@@ -0,0 +1,3 @@
+export declare class TcpTransport {
+    start(): Promise<never>;
+}

package/dist/transport/tcp.js

@@ -0,0 +1,5 @@
+export class TcpTransport {
+    async start() {
+        throw new Error("TCP transport is not implemented yet");
+    }
+}

package/dist/transport/udp.d.ts

@@ -0,0 +1,24 @@
+import { type RemoteInfo } from "node:dgram";
+import { EventEmitter } from "node:events";
+export type UdpDatagram = {
+    data: Buffer;
+    remote: RemoteInfo;
+};
+export type UdpTransportOptions = {
+    host?: string;
+    port?: number;
+};
+export declare class UdpTransport extends EventEmitter {
+    #private;
+    constructor();
+    get bound(): boolean;
+    start(opts?: UdpTransportOptions): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * The OS-assigned local UDP port (after bind). Useful so the peer layer
+     * can recognize and skip its own address in friend endpoint candidates
+     * (some toxcore peers echo our address back inside DHT-PK extras).
+     */
+    localPort(): number | undefined;
+    send(data: Buffer, host: string, port: number): Promise<void>;
+}

package/dist/transport/udp.js

@@ -0,0 +1,90 @@
+import dgram from "node:dgram";
+import { EventEmitter } from "node:events";
+export class UdpTransport extends EventEmitter {
+    #socket;
+    #bound = false;
+    constructor() {
+        super();
+        // A long-running peer connects to ~9 bootstrap nodes and ~3 TCP
+        // relays, each of which attaches a `datagram` listener for its
+        // own routing. Plus the Peer class itself, the announce loop, the
+        // friend connection probe, etc. Node's default of 10 trips
+        // immediately ("51 datagram listeners added to [UdpTransport]");
+        // raise on this instance to suppress the warning. Real leaks
+        // would still trigger via the test suite's stricter checks.
+        this.setMaxListeners(100);
+    }
+    get bound() {
+        return this.#bound;
+    }
+    async start(opts = {}) {
+        if (this.#socket) {
+            return;
+        }
+        const socket = dgram.createSocket("udp4");
+        this.#socket = socket;
+        socket.on("message", (data, remote) => {
+            this.emit("datagram", { data, remote });
+        });
+        socket.on("error", (error) => this.emit("error", error));
+        await new Promise((resolve, reject) => {
+            const cleanup = () => {
+                socket.off("listening", onListening);
+                socket.off("error", onError);
+            };
+            const onListening = () => {
+                cleanup();
+                this.#bound = true;
+                resolve();
+            };
+            const onError = (error) => {
+                cleanup();
+                reject(error);
+            };
+            socket.once("listening", onListening);
+            socket.once("error", onError);
+            socket.bind(opts.port ?? 0, opts.host);
+        });
+    }
+    async stop() {
+        const socket = this.#socket;
+        if (!socket) {
+            return;
+        }
+        this.#socket = undefined;
+        this.#bound = false;
+        await new Promise((resolve) => socket.close(() => resolve()));
+    }
+    /**
+     * The OS-assigned local UDP port (after bind). Useful so the peer layer
+     * can recognize and skip its own address in friend endpoint candidates
+     * (some toxcore peers echo our address back inside DHT-PK extras).
+     */
+    localPort() {
+        try {
+            const addr = this.#socket?.address();
+            if (addr && typeof addr === "object" && "port" in addr) {
+                return addr.port;
+            }
+        }
+        catch {
+            // ignore
+        }
+        return undefined;
+    }
+    async send(data, host, port) {
+        const socket = this.#socket;
+        if (!socket || !this.#bound) {
+            throw new Error("UDP transport is not started");
+        }
+        await new Promise((resolve, reject) => {
+            socket.send(data, port, host, (error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve();
+            });
+        });
+    }
+}

package/dist/types/bootstrap.d.ts

@@ -0,0 +1,2 @@
+import type { NetworkNode } from "./peer.js";
+export type BootstrapNode = NetworkNode;

package/dist/types/bootstrap.js

@@ -0,0 +1 @@
+export {};

package/dist/types/dht.d.ts

@@ -0,0 +1,3 @@
+export type DhtPeerRecord = {
+    pubkey: string;
+};

package/dist/types/dht.js

@@ -0,0 +1 @@
+export {};

package/dist/types/friend.d.ts

@@ -0,0 +1 @@
+export type FriendId = string;

package/dist/types/friend.js

@@ -0,0 +1 @@
+export {};

package/dist/types/message.d.ts

@@ -0,0 +1 @@
+export type MessageId = string;

package/dist/types/message.js

@@ -0,0 +1 @@
+export {};

package/dist/types/peer.d.ts

@@ -0,0 +1,51 @@
+export type CompatibilityMode = "legacy";
+export type NetworkNode = {
+    host: string;
+    port: number;
+    pk?: string;
+    /**
+     * True if this entry was learned from a packed-nodes record with
+     * family = TCP_FAMILY_IPV4 (130) or TCP_FAMILY_IPV6 (138). Such nodes
+     * should be added to the TCP relay client pool rather than treated
+     * as UDP DHT nodes — iOS Beagle peers advertise their reachable
+     * relays this way in DHT-PK extras.
+     */
+    isTcp?: boolean;
+};
+export type PeerOptions = {
+    keyFile: string;
+    friendStoreFile?: string;
+    bootstrapNodes: NetworkNode[];
+    expressNodes?: NetworkNode[];
+    compatibilityMode?: CompatibilityMode;
+    debugLabel?: string;
+};
+export type FriendRequest = {
+    pubkey: string;
+    address?: string;
+    userid?: string;
+    nospam?: number;
+    name?: string;
+    description?: string;
+    hello?: string;
+};
+export type FriendConnectionStatus = "connected" | "disconnected";
+export type FriendConnectionEvent = {
+    pubkey: string;
+    status: FriendConnectionStatus;
+};
+export type FriendInfoEvent = {
+    pubkey: string;
+    userid?: string;
+    name?: string;
+    description?: string;
+};
+export type TextMessage = {
+    pubkey: string;
+    text: string;
+};
+export type LookupResult = {
+    pubkey: string;
+    status: "unknown";
+    records: [];
+};

package/dist/types/peer.js

@@ -0,0 +1 @@
+export {};

package/dist/types/session.d.ts

@@ -0,0 +1 @@
+export type SessionId = string;

package/dist/types/session.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/base58.d.ts

@@ -0,0 +1,2 @@
+export declare function base58ToBytes(value: string): Uint8Array;
+export declare function bytesToBase58(bytes: Uint8Array): string;

package/dist/utils/base58.js

@@ -0,0 +1,51 @@
+const ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+const BASE = BigInt(58);
+const indexes = new Map([...ALPHABET].map((char, index) => [char, BigInt(index)]));
+export function base58ToBytes(value) {
+    if (!value) {
+        throw new Error("base58 value is required");
+    }
+    let num = 0n;
+    for (const char of value) {
+        const digit = indexes.get(char);
+        if (digit === undefined) {
+            throw new Error(`invalid base58 character: ${char}`);
+        }
+        num = num * BASE + digit;
+    }
+    const bytes = [];
+    while (num > 0n) {
+        bytes.push(Number(num & 0xffn));
+        num >>= 8n;
+    }
+    bytes.reverse();
+    for (const char of value) {
+        if (char !== "1") {
+            break;
+        }
+        bytes.unshift(0);
+    }
+    return Uint8Array.from(bytes);
+}
+export function bytesToBase58(bytes) {
+    if (!bytes.length) {
+        return "";
+    }
+    let num = 0n;
+    for (const byte of bytes) {
+        num = (num << 8n) + BigInt(byte);
+    }
+    let encoded = "";
+    while (num > 0n) {
+        const rem = Number(num % BASE);
+        encoded = ALPHABET[rem] + encoded;
+        num /= BASE;
+    }
+    for (const byte of bytes) {
+        if (byte !== 0) {
+            break;
+        }
+        encoded = "1" + encoded;
+    }
+    return encoded || "1";
+}

package/dist/utils/bytes.d.ts

@@ -0,0 +1,4 @@
+export declare function bytesToHex(bytes: Uint8Array): string;
+export declare function hexToBytes(hex: string): Uint8Array;
+export declare function concatBytes(parts: Uint8Array[]): Uint8Array;
+export declare function randomBytes(length: number): Uint8Array;

package/dist/utils/bytes.js

@@ -0,0 +1,31 @@
+export function bytesToHex(bytes) {
+    return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+export function hexToBytes(hex) {
+    if (hex.length % 2 !== 0) {
+        throw new Error("hex string must have an even length");
+    }
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < bytes.length; i++) {
+        const value = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+        if (Number.isNaN(value)) {
+            throw new Error("invalid hex string");
+        }
+        bytes[i] = value;
+    }
+    return bytes;
+}
+export function concatBytes(parts) {
+    const total = parts.reduce((size, part) => size + part.length, 0);
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
+}
+export function randomBytes(length) {
+    return nodeRandomBytes(length);
+}
+import { randomBytes as nodeRandomBytes } from "node:crypto";

package/docs/INSTALL.md

@@ -0,0 +1,103 @@
+# Installing `@decentnetwork/peer`
+
+A pure TypeScript / Node.js implementation of the Elastos Carrier
+(toxcore-derived) peer-to-peer protocol. Use it as a library in
+your own Node app, or run the bundled `decent-peer` CLI for ad-hoc
+identity / friend / messaging operations.
+
+## Requirements
+
+- **Node.js 20 or newer** (uses modern WebStreams + AbortController).
+- Any OS Node runs on. No native compilation; all crypto is pure JS.
+- Outbound network — TCP and/or UDP to public Carrier bootstrap
+  nodes (port 33445 + 443). No inbound port needed.
+
+## Install (as a library)
+
+```bash
+npm install @decentnetwork/peer
+# or
+pnpm add @decentnetwork/peer
+# or
+yarn add @decentnetwork/peer
+```
+
+Then in your code:
+
+```ts
+import { Peer } from "@decentnetwork/peer";
+
+const peer = await Peer.create({
+  keyFile: "./my-peer.save",
+  compatibilityMode: "legacy",
+  bootstrapNodes: [
+    { host: "47.100.103.201", port: 33445,
+      pk: "CX1XH419p4xJ5SV4KvDxBeKYSRdMJW9QpdWJY8owUxHd" },
+    // ... more, see USAGE_GUIDE.md
+  ],
+});
+await peer.start();
+await peer.joinNetwork();
+console.log("my address:", peer.address());
+```
+
+See [`USAGE_GUIDE.md`](USAGE_GUIDE.md) for the full programmatic
+API with copy-paste-ready examples for every common task
+(friending, text messages, binary packets, offline relay).
+
+## Install (CLI, globally)
+
+```bash
+npm install -g @decentnetwork/peer
+```
+
+That puts `decent-peer` on your `$PATH`:
+
+```bash
+decent-peer --help
+decent-peer identity   # print address + userid
+decent-peer join       # sit in the network until killed (useful for testing)
+```
+
+The CLI is mostly for diagnostics; production usage almost always
+embeds the library directly.
+
+## Configuration
+
+The library is configured per-call (no global config file).
+Persistent state lives in the **key file** you pass to
+`Peer.create`. That file holds:
+
+- The keypair (Ed25519 + X25519-derived)
+- A separate "friends" file alongside it (`<keyFile>.friends.json`)
+  with the friend store
+
+Treat both like SSH private keys — back them up; deleting them
+gives this peer a brand-new identity.
+
+Knobs:
+
+| option / env | what |
+|---|---|
+| `Peer.create({ keyFile })` | path to the identity file (created if missing) |
+| `Peer.create({ bootstrapNodes })` | DHT entry points |
+| `Peer.create({ expressNodes })` | optional HTTPS offline-message relays |
+| `Peer.create({ compatibilityMode: "legacy" })` | required for interop with iOS Beagle and the Carrier C SDK |
+| `DECENT_DEBUG=1` env var | verbose protocol logs |
+| `DECENT_EXPRESS_PULL_INTERVAL_MS` | offline-relay poll cadence (default 4000) |
+| `DECENT_FRIEND_CONNECTION_LOOP_MS` | friend-connection tick (default 250) |
+
+## Upgrading
+
+`npm install @decentnetwork/peer@latest` (or `-g` for the CLI).
+The keypair file format is stable; upgrades preserve identity and
+friends.
+
+## See also
+
+- [`USAGE_GUIDE.md`](USAGE_GUIDE.md) — programmatic API guide,
+  copy-paste examples for every common task
+- Protocol-level reference (DHT / onion / TCP relay / FlatBuffers
+  message kinds): not shipped in this tarball — see
+  `docs/PROTOCOL_OVERVIEW.md` in the GitHub repo.
+- Project page: https://github.com/0xli/peer