@decentnetwork/peer 0.1.134 → 0.1.136

package/dist/ice-servers.d.ts

@@ -0,0 +1,60 @@
+/**
+ * WebRTC ICE helpers matching Android Carrier WebrtcClient.getIceServers() /
+ * CarrierExtension.getTurnServerInfo() (carrier_get_turn_server).
+ *
+ * Online Android Beagle gathers STUN+TURN against a Carrier bootstrap node's
+ * coturn (UDP/3478) using Carrier long-term credentials. Browser / Node WebRTC
+ * stacks need the same list — not the tokyo.fi.chat static relay used only as
+ * a fallback for the peer SDK's own messaging UDP relay path.
+ */
+import { CARRIER_TURN_PORT, CARRIER_TURN_REALM } from "./turn-creds.js";
+import type { NetworkNode } from "./types/peer.js";
+/** Same shape as Android CarrierExtension.TurnServerInfo / CarrierTurnServer. */
+export interface CarrierTurnServerInfo {
+    server: string;
+    port: number;
+    username: string;
+    password: string;
+    realm: string;
+}
+/** Browser / wrtc RTCIceServer-compatible entry. */
+export interface RtcIceServer {
+    urls: string | string[];
+    username?: string;
+    credential?: string;
+}
+export interface BuildIceServersOptions {
+    /** Bootstrap / bootnodes that run Carrier TURN on port 3478. */
+    bootstrapNodes: NetworkNode[];
+    ourUserid: string;
+    ourSecretKey: Uint8Array;
+    /**
+     * How many bootstrap TURNs to advertise. Android returns one; browsers often
+     * benefit from a few (default 3). Cap with this.
+     */
+    limit?: number;
+    /** Also advertise turn:?transport=tcp (useful for UDP-blocked browsers). */
+    includeTcpTurn?: boolean;
+}
+/**
+ * Derive TURN info for one bootnode — peer analogue of
+ * carrier_get_turn_server / CarrierExtension.getTurnServerInfo().
+ */
+export declare function getTurnServerInfoForBootnode(opts: {
+    bootnode: NetworkNode;
+    ourUserid: string;
+    ourSecretKey: Uint8Array;
+}): CarrierTurnServerInfo;
+/**
+ * Build RTCIceServer entries from TURN info the way Android WebrtcClient does:
+ * stun:host:port + turn:host:port with the same username/password.
+ */
+export declare function iceServersFromTurnInfo(info: CarrierTurnServerInfo, opts?: {
+    includeTcpTurn?: boolean;
+}): RtcIceServer[];
+/**
+ * Build a WebRTC iceServers list from Carrier bootstrap nodes.
+ * Fresh nonce/credentials on every call (same as Android).
+ */
+export declare function getIceServers(opts: BuildIceServersOptions): RtcIceServer[];
+export { CARRIER_TURN_PORT, CARRIER_TURN_REALM };

package/dist/ice-servers.js

@@ -0,0 +1,78 @@
+/**
+ * WebRTC ICE helpers matching Android Carrier WebrtcClient.getIceServers() /
+ * CarrierExtension.getTurnServerInfo() (carrier_get_turn_server).
+ *
+ * Online Android Beagle gathers STUN+TURN against a Carrier bootstrap node's
+ * coturn (UDP/3478) using Carrier long-term credentials. Browser / Node WebRTC
+ * stacks need the same list — not the tokyo.fi.chat static relay used only as
+ * a fallback for the peer SDK's own messaging UDP relay path.
+ */
+import { base58ToBytes } from "./utils/base58.js";
+import { CARRIER_TURN_PORT, CARRIER_TURN_REALM, deriveCarrierTurnCreds } from "./turn-creds.js";
+function bootnodePublicKey(node) {
+    if (node.pkBytes && node.pkBytes.length === 32)
+        return node.pkBytes;
+    if (!node.pk)
+        throw new Error(`bootstrap node ${node.host} has no pk`);
+    return base58ToBytes(node.pk);
+}
+function toTurnServerInfo(creds) {
+    return {
+        server: creds.host,
+        port: creds.port,
+        username: creds.username,
+        password: creds.password,
+        realm: creds.realm
+    };
+}
+/**
+ * Derive TURN info for one bootnode — peer analogue of
+ * carrier_get_turn_server / CarrierExtension.getTurnServerInfo().
+ */
+export function getTurnServerInfoForBootnode(opts) {
+    const creds = deriveCarrierTurnCreds({
+        bootnodeHost: opts.bootnode.host,
+        bootnodePublicKey: bootnodePublicKey(opts.bootnode),
+        ourUserid: opts.ourUserid,
+        ourSecretKey: opts.ourSecretKey
+    });
+    return toTurnServerInfo(creds);
+}
+/**
+ * Build RTCIceServer entries from TURN info the way Android WebrtcClient does:
+ * stun:host:port + turn:host:port with the same username/password.
+ */
+export function iceServersFromTurnInfo(info, opts) {
+    const base = `${info.server}:${info.port}`;
+    const auth = { username: info.username, credential: info.password };
+    const out = [
+        { urls: `stun:${base}`, ...auth },
+        { urls: `turn:${base}`, ...auth }
+    ];
+    if (opts?.includeTcpTurn !== false) {
+        out.push({ urls: `turn:${base}?transport=tcp`, ...auth });
+    }
+    return out;
+}
+/**
+ * Build a WebRTC iceServers list from Carrier bootstrap nodes.
+ * Fresh nonce/credentials on every call (same as Android).
+ */
+export function getIceServers(opts) {
+    const limit = opts.limit ?? 3;
+    const nodes = opts.bootstrapNodes.filter((n) => n?.host && (n.pk || n.pkBytes)).slice(0, limit);
+    if (!nodes.length) {
+        throw new Error("getIceServers: no bootstrap nodes with public keys");
+    }
+    const ice = [];
+    for (const bootnode of nodes) {
+        const info = getTurnServerInfoForBootnode({
+            bootnode,
+            ourUserid: opts.ourUserid,
+            ourSecretKey: opts.ourSecretKey
+        });
+        ice.push(...iceServersFromTurnInfo(info, { includeTcpTurn: opts.includeTcpTurn }));
+    }
+    return ice;
+}
+export { CARRIER_TURN_PORT, CARRIER_TURN_REALM };

package/dist/index.d.ts

@@ -6,6 +6,10 @@ export { NET_PACKET_ONION_ANNOUNCE_REQUEST, NET_PACKET_ONION_ANNOUNCE_RESPONSE,
 export { signDetached, verifyDetached, SIGNATURE_LENGTH } from "./crypto/sign.js";
 export { createCarrierRendezvousAuthProof, RENDEZVOUS_AUTH_KEY_DOMAIN, RENDEZVOUS_AUTH_PROOF_LENGTH } from "./crypto/rendezvous.js";
 export { base58ToBytes, bytesToBase58 } from "./utils/base58.js";
+export { CARRIER_TURN_PORT, CARRIER_TURN_REALM, CARRIER_TURN_USER_SUFFIX, deriveCarrierTurnCreds } from "./turn-creds.js";
+export type { CarrierTurnCreds } from "./turn-creds.js";
+export { getIceServers, getTurnServerInfoForBootnode, iceServersFromTurnInfo } from "./ice-servers.js";
+export type { BuildIceServersOptions, CarrierTurnServerInfo, RtcIceServer } from "./ice-servers.js";
 export { LegacyProtocolNotImplementedError } from "./runtime/errors.js";
 export type { CarrierPacket, FriendMessagePacket, FriendRequestPacket, InviteReqPacket, InviteRspPacket } from "./compat/packet.js";
 export type { ToxDhtCryptoRequest } from "./compat/tox-dht-crypto.js";

package/dist/index.js

@@ -6,4 +6,6 @@ export { NET_PACKET_ONION_ANNOUNCE_REQUEST, NET_PACKET_ONION_ANNOUNCE_RESPONSE,
 export { signDetached, verifyDetached, SIGNATURE_LENGTH } from "./crypto/sign.js";
 export { createCarrierRendezvousAuthProof, RENDEZVOUS_AUTH_KEY_DOMAIN, RENDEZVOUS_AUTH_PROOF_LENGTH } from "./crypto/rendezvous.js";
 export { base58ToBytes, bytesToBase58 } from "./utils/base58.js";
+export { CARRIER_TURN_PORT, CARRIER_TURN_REALM, CARRIER_TURN_USER_SUFFIX, deriveCarrierTurnCreds } from "./turn-creds.js";
+export { getIceServers, getTurnServerInfoForBootnode, iceServersFromTurnInfo } from "./ice-servers.js";
 export { LegacyProtocolNotImplementedError } from "./runtime/errors.js";

package/dist/peer.d.ts

@@ -1,5 +1,6 @@
 import { type BootstrapResult } from "./compat/bootstrap.js";
 import type { FriendRecord } from "./store/friends.js";
+import { type CarrierTurnServerInfo, type RtcIceServer } from "./ice-servers.js";
 import type { CustomPacketEvent, FriendConnectionEvent, FriendRequest, FriendInfoEvent, InlineFileEvent, InviteEvent, InviteResponseEvent, LookupResult, NetworkNode, PeerOptions, SendTextUntilAckOptions, TextMessage } from "./types/peer.js";
 export declare class Peer {
     #private;
@@ -18,6 +19,21 @@ export declare class Peer {
      */
     sign(message: Uint8Array): Uint8Array;
     address(): string;
+    /**
+     * Carrier bootstrap TURN credentials — peer analogue of Android
+     * CarrierExtension.getTurnServerInfo() / carrier_get_turn_server().
+     * Uses the first configured bootstrap node with a public key (fresh nonce
+     * each call). For WebRTC, prefer {@link getIceServers}.
+     */
+    getTurnServerInfo(bootnodeIndex?: number): CarrierTurnServerInfo;
+    /**
+     * RTCIceServer list for browser / native WebRTC, matching Android
+     * WebrtcClient.getIceServers() (Carrier bootstrap STUN+TURN, not tokyo).
+     */
+    getIceServers(opts?: {
+        limit?: number;
+        includeTcpTurn?: boolean;
+    }): RtcIceServer[];
     joinNetwork(): Promise<BootstrapResult>;
     lookup(pubkey: string): Promise<LookupResult>;
     announceSelf(timeoutMs?: number): Promise<NetworkNode[]>;
@@ -87,11 +103,13 @@ export declare class Peer {
     /**
      * Send text and keep retransmitting until the peer explicitly ACKs it.
      *
-     * The receiving peer sends that ACK only after every onText handler returns
-     * successfully. If a handler persists to an inbox, return its write Promise
-     * from the handler; then this method resolves only after that durable write
-     * completed on the far side. Pass a stable deliveryId when retrying an item
-     * from an application outbox across process restarts.
+     * The ACK means the far side's SDK durably received the message — it is
+     * sent BEFORE the peer's onText handlers run, so a peer that is busy in
+     * application code (a model call, a disk-bound job) still ACKs instantly.
+     * It does NOT mean the application processed the message; if you need that,
+     * have the far side send an application-level reply. Pass a stable
+     * deliveryId when retrying an item from an application outbox across
+     * process restarts.
      */
     sendTextUntilAck(pubkey: string, text: string, opts?: SendTextUntilAckOptions): Promise<{
         deliveryId: string;
@@ -99,6 +117,13 @@ export declare class Peer {
     waitForFriendConnected(pubkey: string, timeoutMs?: number): Promise<boolean>;
     onFriendRequest(cb: (req: FriendRequest) => void): void;
     onText(cb: (msg: TextMessage) => unknown | Promise<unknown>): void;
+    /** @internal Test seam: deliver a text message exactly as if it arrived off
+     *  the wire. Exists so the ACK-before-handlers ordering is testable without
+     *  a network — do not use outside tests. */
+    _testDispatchTextMessage(msg: {
+        pubkey: string;
+        text: string;
+    }): Promise<void>;
     /** Files received inline over (bulk)messages — the iOS/C Carrier apps'
      *  native way of sending images/audio online (FileModel JSON envelope). */
     onInlineFile(cb: (evt: InlineFileEvent) => void): void;

package/dist/peer.js

@@ -23,6 +23,7 @@ import { UdpTransport } from "./transport/udp.js";
 import { bytesToHex, concatBytes, randomBytes } from "./utils/bytes.js";
 import { buildBindingRequest, decodeStun, decodeXorMappedAddress, findAttr, STUN_ATTR_XOR_MAPPED_ADDRESS, STUN_BINDING_SUCCESS } from "./stun.js";
 import { TurnClient } from "./turn.js";
+import { getIceServers as buildRtcIceServers, getTurnServerInfoForBootnode } from "./ice-servers.js";
 import { createBoundUdp4Socket, closeDgramSocket } from "./transport/dgram-lifecycle.js";
 // Dedicated TURN relay servers — fixed public relays used as a stable
 // fallback path when direct UDP hole-punch fails or flaps (symmetric NAT,
@@ -34,7 +35,21 @@ import { createBoundUdp4Socket, closeDgramSocket } from "./transport/dgram-lifec
 const TURN_RELAY_SERVERS = (() => {
     const raw = process.env.DECENT_TURN_SERVERS?.trim();
     if (!raw) {
-        return [{ host: "tokyo.fi.chat", port: 3478, username: "allcom", password: "allcompass" }];
+        // MORE THAN ONE, ALWAYS. This list is not a preference — it is the only
+        // way a peer learns its own public endpoint, so when every entry is down
+        // nobody can hole-punch and the WHOLE network silently degrades to TCP
+        // relay. That is not hypothetical: coturn on tokyo core-dumped and stayed
+        // dead for ten days, and with tokyo as the sole entry every link in the
+        // network ran at relay latency (~1200ms instead of ~130ms) the entire
+        // time. Nothing alerted, because the port stayed open.
+        //
+        // Ordered by expected reachability from the biggest population of peers.
+        // A dead entry costs one timeout before the next is tried, so listing a
+        // spare is close to free; having none is a network-wide outage.
+        return [
+            { host: "tokyo.fi.chat", port: 3478, username: "allcom", password: "allcompass" },
+            { host: "gfax.cn", port: 3478, username: "allcom", password: "allcompass" },
+        ];
     }
     return raw
         .split(",")
@@ -817,6 +832,43 @@ export class Peer {
         }
         return carrierAddressFromPublicKey(this.#keyPair.publicKey);
     }
+    /**
+     * Carrier bootstrap TURN credentials — peer analogue of Android
+     * CarrierExtension.getTurnServerInfo() / carrier_get_turn_server().
+     * Uses the first configured bootstrap node with a public key (fresh nonce
+     * each call). For WebRTC, prefer {@link getIceServers}.
+     */
+    getTurnServerInfo(bootnodeIndex = 0) {
+        if (!this.#keyPair) {
+            throw new Error("Peer is not started");
+        }
+        const nodes = this.#opts.bootstrapNodes.filter((n) => n?.host && (n.pk || n.pkBytes));
+        const bootnode = nodes[bootnodeIndex] ?? nodes[0];
+        if (!bootnode) {
+            throw new Error("getTurnServerInfo: no bootstrap nodes configured");
+        }
+        return getTurnServerInfoForBootnode({
+            bootnode,
+            ourUserid: this.userid(),
+            ourSecretKey: this.#keyPair.secretKey
+        });
+    }
+    /**
+     * RTCIceServer list for browser / native WebRTC, matching Android
+     * WebrtcClient.getIceServers() (Carrier bootstrap STUN+TURN, not tokyo).
+     */
+    getIceServers(opts) {
+        if (!this.#keyPair) {
+            throw new Error("Peer is not started");
+        }
+        return buildRtcIceServers({
+            bootstrapNodes: this.#opts.bootstrapNodes,
+            ourUserid: this.userid(),
+            ourSecretKey: this.#keyPair.secretKey,
+            limit: opts?.limit,
+            includeTcpTurn: opts?.includeTcpTurn
+        });
+    }
     async joinNetwork() {
         if (!this.#bootstrap) {
             throw new Error("Peer is not started");
@@ -1316,11 +1368,13 @@ export class Peer {
     /**
      * Send text and keep retransmitting until the peer explicitly ACKs it.
      *
-     * The receiving peer sends that ACK only after every onText handler returns
-     * successfully. If a handler persists to an inbox, return its write Promise
-     * from the handler; then this method resolves only after that durable write
-     * completed on the far side. Pass a stable deliveryId when retrying an item
-     * from an application outbox across process restarts.
+     * The ACK means the far side's SDK durably received the message — it is
+     * sent BEFORE the peer's onText handlers run, so a peer that is busy in
+     * application code (a model call, a disk-bound job) still ACKs instantly.
+     * It does NOT mean the application processed the message; if you need that,
+     * have the far side send an application-level reply. Pass a stable
+     * deliveryId when retrying an item from an application outbox across
+     * process restarts.
      */
     async sendTextUntilAck(pubkey, text, opts = {}) {
         const deliveryId = opts.deliveryId ?? createTextDeliveryId();
@@ -1427,6 +1481,28 @@ export class Peer {
             ? async () => { await this.#sendTextAck(msg.pubkey, deliveryId); }
             : undefined;
         const delivered = { ...msg, text, deliveryId, ack };
+        // ACK BEFORE the handlers, not after. The ACK means "the SDK durably
+        // received this", never "the application finished processing it" — the
+        // two were conflated here and it broke real chat twice over:
+        //
+        //   1. A peer whose handler was slow (beagle-help awaiting a 10s+ model
+        //      call) sent its ACK 10s late — inside sendText's 15s auto window —
+        //      so senders got "ACK timed out" for messages that were delivered
+        //      AND answered. The UI then dropped the sender's own message as
+        //      failed: "对方在回答一个看不见的问题".
+        //   2. The delivery id was only registered after the handlers returned,
+        //      so the sender's 5s retransmits arriving DURING a slow handler
+        //      re-dispatched the same message — the busy peer processed it again
+        //      (and hit its model again), making the overload worse.
+        //
+        // Registering + ACKing up front fixes both: retries hit the dedupe path
+        // and re-ACK, and a busy application can no longer turn into a transport
+        // failure. A handler that needs "processed" semantics must build its own
+        // application-level reply — that is what an answer message is.
+        if (deliveryId) {
+            this.#rememberDeliveredTextId(deliveryId);
+            void ack?.();
+        }
         try {
             for (const handler of this.#textHandlers) {
                 await handler(delivered);
@@ -1434,13 +1510,14 @@ export class Peer {
         }
         catch (error) {
             this.#debugLog(`text handler failed for ${msg.pubkey}: ${error.message}`);
-            return;
-        }
-        if (deliveryId) {
-            this.#rememberDeliveredTextId(deliveryId);
-            await ack?.();
         }
     }
+    /** @internal Test seam: deliver a text message exactly as if it arrived off
+     *  the wire. Exists so the ACK-before-handlers ordering is testable without
+     *  a network — do not use outside tests. */
+    _testDispatchTextMessage(msg) {
+        return this.#dispatchTextMessage(msg);
+    }
     async #sendTextAck(pubkey, deliveryId) {
         try {
             await this.sendText(pubkey, encodeTextAckEnvelope({ t: "ack", id: deliveryId }));

package/dist/types/peer.d.ts

@@ -125,9 +125,10 @@ export type TextMessage = {
     /** Stable id for SDK-level acknowledged delivery. Present only for messages
      *  sent with sendTextUntilAck(). Receivers can persist this id for dedupe. */
     deliveryId?: string;
-    /** Send the delivery ACK. The SDK calls this automatically after all onText
-     *  handlers return successfully; handlers that need durable inbox semantics
-     *  should return a Promise that resolves only after the inbox write is done. */
+    /** Re-send the delivery ACK. The SDK ACKs automatically BEFORE handlers run
+     *  — the ACK means "SDK received", never "application processed", so a slow
+     *  handler (model call, disk job) cannot fake a delivery failure at the
+     *  sender. Kept on the message for idempotent manual re-ACKs only. */
     ack?: () => Promise<void>;
     /** Delivery path: "online" = live net_crypto session (direct/relay), "offline"
      *  = express store-and-forward. Lets the UI color the two differently so a user

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decentnetwork/peer",
-  "version": "0.1.134",
+  "version": "0.1.136",
   "description": "Pure TypeScript port of Elastos Carrier (toxcore-derived) P2P messaging. DHT, onion routing, TCP relay, FlatBuffers app payloads, Express offline relay. Wire-compatible with iOS Beagle and the Carrier C SDK.",
   "type": "module",
   "main": "./dist/index.js",