@vdoninja/ninja-p2p 0.1.2 → 0.2.0

package/dist/protocol.js

@@ -6,6 +6,31 @@
  * internals — it can be extracted and reused by any bot.
  */
 import { randomBytes, randomUUID } from "node:crypto";
+/**
+ * Messages that are only worth delivering right now.
+ *
+ * Transfer traffic is high volume and stateful: a chunk request replayed from
+ * an offline queue minutes later asks for something the requester already has,
+ * while replaying half of a simple file transfer cannot restore its missing
+ * half. A history ring full of chunks also evicts every real message a peer
+ * asking for history actually wanted. Swarm state is re-announced; a rejected
+ * simple transfer fails explicitly and can be retried from the start.
+ */
+export const TRANSIENT_MESSAGE_TYPES = new Set([
+    "file_offer",
+    "file_chunk",
+    "file_complete",
+    "swarm_offer",
+    "swarm_manifest_request",
+    "swarm_manifest_page",
+    "swarm_announce",
+    "swarm_request",
+    "swarm_chunk",
+    "swarm_have",
+]);
+export function isTransientType(type) {
+    return TRANSIENT_MESSAGE_TYPES.has(type);
+}
 // ── Helpers ──────────────────────────────────────────────────────────────────
 /** Generate a short unique message ID. */
 export function createMessageId() {
@@ -37,13 +62,24 @@ export function isValidEnvelope(data) {
     if (typeof data !== "object" || data === null)
         return false;
     const d = data;
+    const from = typeof d.from === "object" && d.from !== null
+        ? d.from
+        : null;
     return (d.v === 1 &&
-        typeof d.id === "string" &&
-        typeof d.type === "string" &&
-        typeof d.from === "object" &&
-        d.from !== null &&
-        typeof d.from.streamId === "string" &&
-        typeof d.ts === "number");
+        isBoundedText(d.id, 128) &&
+        isBoundedText(d.type, 64) &&
+        from !== null &&
+        isBoundedText(from.streamId, 128) &&
+        isBoundedText(from.role, 64) &&
+        isBoundedText(from.name, 256) &&
+        isBoundedText(from.instanceId, 128) &&
+        typeof d.ts === "number" &&
+        Number.isFinite(d.ts) &&
+        (d.to === null || d.to === undefined || isBoundedText(d.to, 128)) &&
+        (d.topic === null || d.topic === undefined || isBoundedText(d.topic, 256)));
+}
+function isBoundedText(value, maxLength) {
+    return typeof value === "string" && value.length > 0 && value.length <= maxLength && !value.includes("\0");
 }
 /** Parse raw data received from a data channel into an envelope. Returns null on failure. */
 export function parseEnvelope(raw) {

package/dist/shared-folders.js

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readdirSync, realpathSync, statSync } from "node:fs";
 import path from "node:path";
 export function parseSharedFolderSpecs(rawValues, cwd = process.cwd()) {
     const shares = [];
@@ -114,11 +114,30 @@ function resolveSharedPath(share, relativePath) {
     if (!existsSync(target)) {
         throw new Error(`shared path does not exist: ${normalized || "."}`);
     }
+    // The check above is lexical, so a symlink sitting inside the share and
+    // pointing outside it would still pass. Compare the real paths too, or
+    // `--share docs=./docs` could hand out anything the link reaches.
+    assertRealPathContained(share.path, target);
     return {
         filePath: target,
         path: normalized,
     };
 }
+function assertRealPathContained(shareRoot, target) {
+    let realRoot;
+    let realTarget;
+    try {
+        realRoot = realpathSync(shareRoot);
+        realTarget = realpathSync(target);
+    }
+    catch {
+        // If either path cannot be resolved, refuse rather than guess.
+        throw new Error("shared path escapes the declared folder");
+    }
+    if (realTarget !== realRoot && !realTarget.startsWith(`${realRoot}${path.sep}`)) {
+        throw new Error("shared path escapes the declared folder");
+    }
+}
 function normalizeRelativeSharePath(relativePath) {
     const raw = relativePath.replace(/\\/g, "/").trim();
     if (!raw)

package/dist/social-stream.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Social Stream Ninja Bridge
+ *
+ * Pipes live chat from Twitch, YouTube, Kick and everything else Social Stream
+ * Ninja aggregates into a ninja-p2p room as topic events, and lets agents in
+ * that room talk back out to every connected platform at once.
+ *
+ * This uses SSN's documented WebSocket API and requires no changes to SSN
+ * itself. Channel 4 carries chat from the extension; channel 1 is where the
+ * extension listens for commands, so the bridge joins as `in=4, out=1`.
+ *
+ * See docs/social-stream-bridge.md for setup and for the direct WebRTC path
+ * that would remove the relay entirely.
+ */
+export declare const DEFAULT_SSN_HOST = "wss://io.socialstream.ninja";
+export declare const DEFAULT_SSN_IN_CHANNEL = 4;
+export declare const DEFAULT_SSN_OUT_CHANNEL = 1;
+export declare const DEFAULT_SSN_TOPIC = "social";
+export type SocialMessage = {
+    id: string | null;
+    platform: string;
+    author: string;
+    text: string;
+    avatar: string | null;
+    donation: string | null;
+    membership: string | null;
+    event: string | null;
+    sourceName: string | null;
+    moderator: boolean;
+    bot: boolean;
+};
+/** Minimal WebSocket surface, so tests can inject a fake. */
+export type SocialSocket = {
+    send(data: string): void;
+    close(): void;
+    onopen: ((event?: unknown) => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onerror: ((event?: unknown) => void) | null;
+    onclose: ((event?: unknown) => void) | null;
+};
+export type SocialSocketFactory = (url: string) => SocialSocket;
+type SocialSocketConstructor = new (url: string) => SocialSocket;
+export type SocialStreamBridgeOptions = {
+    session: string;
+    host?: string;
+    inChannel?: number;
+    outChannel?: number;
+    onMessage: (message: SocialMessage) => void;
+    log?: (message: string) => void;
+    socketFactory?: SocialSocketFactory;
+    /** Reconnect backoff steps in ms; the last value repeats. */
+    backoffMs?: number[];
+};
+export declare function buildSocialStreamUrl(session: string, host?: string, inChannel?: number, outChannel?: number): string;
+/**
+ * Convert one raw SSN payload into a flat message, or null if it is not chat.
+ *
+ * The channel carries far more than chat — callbacks, waitlist state, poll
+ * updates, queue sizes. Everything SSN considers a message has `chatname`, so
+ * that is the gate. Anything without it is control traffic an agent should not
+ * be woken for.
+ */
+export declare function normalizeSocialMessage(raw: unknown): SocialMessage | null;
+/** A one-line human summary, useful for logs and chat relays. */
+export declare function describeSocialMessage(message: SocialMessage): string;
+export declare class SocialStreamBridge {
+    private readonly options;
+    private readonly socketFactory;
+    private readonly log;
+    private readonly backoffMs;
+    private socket;
+    private attempt;
+    private connected;
+    private closed;
+    private retryTimer;
+    constructor(options: SocialStreamBridgeOptions);
+    get url(): string;
+    isConnected(): boolean;
+    connect(): void;
+    /**
+     * Send a chat message out to every platform SSN is connected to.
+     * Returns false when the socket is not ready, so callers can report honestly
+     * rather than silently dropping an agent's reply.
+     */
+    sendChat(text: string): boolean;
+    sendAction(action: string, value?: unknown): boolean;
+    close(): void;
+    private scheduleReconnect;
+}
+/**
+ * Pick the platform WebSocket when present, with `ws` as the Node 20 fallback.
+ *
+ * Node 20 is the package's supported floor but does not expose WebSocket by
+ * default. The bridge used to advertise Node 20 support and then fail at
+ * runtime on exactly that version.
+ */
+export declare function resolveSocialSocketConstructor(platform?: SocialSocketConstructor | null | undefined, load?: () => unknown): SocialSocketConstructor;
+export {};

package/dist/social-stream.js

@@ -0,0 +1,254 @@
+/**
+ * Social Stream Ninja Bridge
+ *
+ * Pipes live chat from Twitch, YouTube, Kick and everything else Social Stream
+ * Ninja aggregates into a ninja-p2p room as topic events, and lets agents in
+ * that room talk back out to every connected platform at once.
+ *
+ * This uses SSN's documented WebSocket API and requires no changes to SSN
+ * itself. Channel 4 carries chat from the extension; channel 1 is where the
+ * extension listens for commands, so the bridge joins as `in=4, out=1`.
+ *
+ * See docs/social-stream-bridge.md for setup and for the direct WebRTC path
+ * that would remove the relay entirely.
+ */
+import { createRequire } from "node:module";
+export const DEFAULT_SSN_HOST = "wss://io.socialstream.ninja";
+export const DEFAULT_SSN_IN_CHANNEL = 4;
+export const DEFAULT_SSN_OUT_CHANNEL = 1;
+export const DEFAULT_SSN_TOPIC = "social";
+const requireFromHere = createRequire(import.meta.url);
+export function buildSocialStreamUrl(session, host = DEFAULT_SSN_HOST, inChannel = DEFAULT_SSN_IN_CHANNEL, outChannel = DEFAULT_SSN_OUT_CHANNEL) {
+    const trimmedHost = host.replace(/\/+$/, "");
+    return `${trimmedHost}/join/${encodeURIComponent(session)}/${inChannel}/${outChannel}`;
+}
+/**
+ * Convert one raw SSN payload into a flat message, or null if it is not chat.
+ *
+ * The channel carries far more than chat — callbacks, waitlist state, poll
+ * updates, queue sizes. Everything SSN considers a message has `chatname`, so
+ * that is the gate. Anything without it is control traffic an agent should not
+ * be woken for.
+ */
+export function normalizeSocialMessage(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return null;
+    const data = raw;
+    const author = asText(data.chatname);
+    if (!author)
+        return null;
+    const message = asText(data.chatmessage);
+    // chatmessage may carry sanitized emote markup unless textonly is set.
+    // Agents want words, so strip tags but keep the original shape intact.
+    const text = data.textonly === true ? message : stripHtml(message);
+    return {
+        id: asText(data.id) || null,
+        platform: asText(data.type).toLowerCase() || "unknown",
+        author,
+        text,
+        avatar: asText(data.chatimg) || null,
+        donation: asText(data.hasDonation) || null,
+        membership: asText(data.membership) || null,
+        event: typeof data.event === "string" && data.event.trim() ? data.event.trim() : null,
+        sourceName: asText(data.sourceName) || null,
+        moderator: data.moderator === true,
+        bot: data.bot === true,
+    };
+}
+/** A one-line human summary, useful for logs and chat relays. */
+export function describeSocialMessage(message) {
+    const parts = [`[${message.platform}] ${message.author}`];
+    if (message.donation)
+        parts.push(`(${message.donation})`);
+    if (message.event)
+        parts.push(`<${message.event}>`);
+    return `${parts.join(" ")}: ${message.text}`;
+}
+export class SocialStreamBridge {
+    options;
+    socketFactory;
+    log;
+    backoffMs;
+    socket = null;
+    attempt = 0;
+    connected = false;
+    closed = false;
+    retryTimer = null;
+    constructor(options) {
+        if (!options.session.trim()) {
+            throw new Error("social stream bridge requires a session id");
+        }
+        this.options = options;
+        this.socketFactory = options.socketFactory ?? defaultSocketFactory;
+        this.log = options.log ?? (() => { });
+        this.backoffMs = options.backoffMs ?? [1000, 2000, 5000, 10_000, 30_000];
+    }
+    get url() {
+        return buildSocialStreamUrl(this.options.session, this.options.host, this.options.inChannel, this.options.outChannel);
+    }
+    isConnected() {
+        return this.connected;
+    }
+    connect() {
+        if (this.closed || this.socket)
+            return;
+        let socket;
+        try {
+            socket = this.socketFactory(this.url);
+        }
+        catch (error) {
+            this.log(`[ssn] connect failed: ${errorMessage(error)}`);
+            this.scheduleReconnect();
+            return;
+        }
+        this.socket = socket;
+        socket.onopen = () => {
+            this.connected = true;
+            this.attempt = 0;
+            this.log(`[ssn] connected to session ${this.options.session}`);
+        };
+        socket.onmessage = (event) => {
+            const payload = parseJson(event?.data);
+            if (payload === undefined)
+                return;
+            const message = normalizeSocialMessage(payload);
+            if (!message)
+                return;
+            try {
+                this.options.onMessage(message);
+            }
+            catch (error) {
+                this.log(`[ssn] handler error: ${errorMessage(error)}`);
+            }
+        };
+        socket.onerror = () => {
+            this.log("[ssn] socket error");
+        };
+        socket.onclose = () => {
+            this.connected = false;
+            this.socket = null;
+            if (this.closed)
+                return;
+            this.log("[ssn] disconnected");
+            this.scheduleReconnect();
+        };
+    }
+    /**
+     * Send a chat message out to every platform SSN is connected to.
+     * Returns false when the socket is not ready, so callers can report honestly
+     * rather than silently dropping an agent's reply.
+     */
+    sendChat(text) {
+        return this.sendAction("sendChat", text);
+    }
+    sendAction(action, value) {
+        if (!this.socket || !this.connected)
+            return false;
+        try {
+            const payload = { action };
+            if (value !== undefined)
+                payload.value = value;
+            this.socket.send(JSON.stringify(payload));
+            return true;
+        }
+        catch (error) {
+            this.log(`[ssn] send failed: ${errorMessage(error)}`);
+            return false;
+        }
+    }
+    close() {
+        this.closed = true;
+        this.connected = false;
+        if (this.retryTimer) {
+            clearTimeout(this.retryTimer);
+            this.retryTimer = null;
+        }
+        const socket = this.socket;
+        this.socket = null;
+        try {
+            socket?.close();
+        }
+        catch { /* best effort */ }
+    }
+    scheduleReconnect() {
+        if (this.closed || this.retryTimer)
+            return;
+        const delay = this.backoffMs[Math.min(this.attempt, this.backoffMs.length - 1)];
+        this.attempt += 1;
+        this.log(`[ssn] reconnecting in ${delay}ms`);
+        this.retryTimer = setTimeout(() => {
+            this.retryTimer = null;
+            this.connect();
+        }, delay);
+        if (typeof this.retryTimer.unref === "function")
+            this.retryTimer.unref();
+    }
+}
+/**
+ * Pick the platform WebSocket when present, with `ws` as the Node 20 fallback.
+ *
+ * Node 20 is the package's supported floor but does not expose WebSocket by
+ * default. The bridge used to advertise Node 20 support and then fail at
+ * runtime on exactly that version.
+ */
+export function resolveSocialSocketConstructor(platform = globalThis.WebSocket, load = () => requireFromHere("ws")) {
+    if (platform)
+        return platform;
+    let loaded;
+    try {
+        loaded = load();
+    }
+    catch (error) {
+        throw new Error(`no WebSocket implementation available: ${errorMessage(error)}`);
+    }
+    const module = loaded;
+    const implementation = typeof module === "function"
+        ? module
+        : module.WebSocket ?? module.default;
+    if (typeof implementation !== "function") {
+        throw new Error("the ws package did not export a WebSocket constructor");
+    }
+    return implementation;
+}
+function defaultSocketFactory(url) {
+    const Impl = resolveSocialSocketConstructor();
+    return new Impl(url);
+}
+function parseJson(data) {
+    const text = typeof data === "string"
+        ? data
+        : (data && typeof data.toString === "function")
+            ? String(data)
+            : null;
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function stripHtml(value) {
+    return value
+        .replace(/<br\s*\/?>/gi, " ")
+        .replace(/<[^>]*>/g, "")
+        .replace(/&nbsp;/gi, " ")
+        .replace(/&amp;/gi, "&")
+        .replace(/&lt;/gi, "<")
+        .replace(/&gt;/gi, ">")
+        .replace(/&quot;/gi, '"')
+        .replace(/&#39;/gi, "'")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+function asText(value) {
+    if (typeof value === "string")
+        return value.trim();
+    if (typeof value === "number" && Number.isFinite(value))
+        return String(value);
+    return "";
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/swarm-manager.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Swarm Manager
+ *
+ * Binds swarm sessions to a live room. It routes swarm messages to the right
+ * file, drives the request pump, and keeps peers informed about what it holds.
+ *
+ * One behaviour worth calling out: when a download completes, the manager
+ * immediately reopens the finished file as a seed session. A peer that just
+ * finished is the swarm's newest full source, and dropping out at that moment
+ * is exactly what starves a swarm.
+ */
+import type { VDOBridge } from "./vdo-bridge.js";
+import { ChunkMap, type SwarmManifest, type SwarmManifestSummary } from "./swarm.js";
+import { SwarmSession, type SwarmProgress } from "./swarm-session.js";
+export declare const DEFAULT_PUMP_INTERVAL_MS = 250;
+export declare const DEFAULT_ANNOUNCE_INTERVAL_MS = 5000;
+/** Floor on how often one peer can be answered about one file. */
+export declare const ANNOUNCE_REPLY_MIN_INTERVAL_MS = 1000;
+/** Consecutive timeouts, with nothing delivered between, before rebuilding a path. */
+export declare const UNRESPONSIVE_TIMEOUT_THRESHOLD = 3;
+/** Floor between rebuild attempts for one peer, so a dead peer is not hammered. */
+export declare const REVIVE_MIN_INTERVAL_MS = 20000;
+/** Retry a lost manifest page request without flooding the control channel. */
+export declare const MANIFEST_REQUEST_RETRY_MS = 2000;
+/** Bound both request messages and the burst of page responses they trigger. */
+export declare const MANIFEST_PAGES_PER_REQUEST = 8;
+export type SwarmCompletion = {
+    fileId: string;
+    manifest: SwarmManifest;
+    savedPath: string;
+};
+export type SwarmManagerOptions = {
+    bridge: VDOBridge;
+    /** Where finished files land. */
+    downloadDir: string;
+    /** Where in-progress `.part` files live. */
+    workDir: string;
+    pumpIntervalMs?: number;
+    announceIntervalMs?: number;
+    /** Outstanding chunk requests allowed per peer. */
+    maxInFlightPerPeer?: number;
+    /** Outstanding chunk requests allowed across all peers, as a memory bound. */
+    maxInFlightTotal?: number;
+    log?: (message: string) => void;
+    onComplete?: (completion: SwarmCompletion) => void;
+    onProgress?: (progress: SwarmProgress) => void;
+    onError?: (message: string, manifest?: SwarmManifestSummary) => void;
+};
+export type SwarmOfferInfo = SwarmManifestSummary & {
+    manifestReady: boolean;
+};
+export declare class SwarmManager {
+    private readonly bridge;
+    private readonly downloadDir;
+    private readonly workDir;
+    private readonly pumpIntervalMs;
+    private readonly announceIntervalMs;
+    private readonly maxInFlightPerPeer?;
+    private readonly maxInFlightTotal?;
+    private readonly log;
+    private readonly onComplete?;
+    private readonly onProgress?;
+    private readonly onError?;
+    private readonly sessions;
+    private readonly offers;
+    /** Files asked for before their offer arrived. */
+    private readonly wanted;
+    private readonly seeding;
+    /** `fileId:peerId` -> when we last answered that peer's announce. */
+    private readonly lastAnnounceReply;
+    /** peerId -> when its connection was last rebuilt. */
+    private readonly lastRevive;
+    private pumpTimer;
+    private announceTimer;
+    private coalesceTimer;
+    private started;
+    constructor(options: SwarmManagerOptions);
+    start(): void;
+    stop(): void;
+    /** Publish a local file to the room and start serving it. */
+    seed(filePath: string, chunkSize?: number): SwarmManifest;
+    /**
+     * Ask for a file by content id. If its offer has not arrived yet the request
+     * is remembered, so `fetch` before the seeder announces still works.
+     */
+    fetch(fileId: string): boolean;
+    knownOffers(): SwarmOfferInfo[];
+    /**
+     * Find an offer by full content id, an unambiguous id prefix, or exact file
+     * name. A 64-character hex id is not something anyone types by hand.
+     */
+    resolveOffer(query: string): SwarmOfferInfo | null;
+    progress(): SwarmProgress[];
+    sessionFor(fileId: string): SwarmSession | undefined;
+    private pump;
+    /**
+     * Rebuild the connection to a peer that keeps timing out without delivering.
+     *
+     * The case this exists for is a path that every layer believes is healthy: a
+     * signalling blip leaves the peer connection reporting `open`, the sender's
+     * `send()` succeeds, and the bytes are simply dropped. Waiting it out took
+     * around a minute; the swarm has the evidence to act much sooner, because a
+     * run of timeouts with nothing delivered in between says so.
+     *
+     * Deliberately conservative: a peer must miss several requests in a row, and
+     * rebuilding is rate-limited, because a genuinely slow peer must not be
+     * disconnected for being slow.
+     */
+    private reviveUnresponsive;
+    /**
+     * Re-plan as soon as a request slot frees, instead of waiting for the timer.
+     *
+     * The interval alone caps throughput hard: with four requests in flight and a
+     * 250ms tick, a slot that frees 10ms after a pump sits idle for the other
+     * 240ms. Measured against a real 5 MB transfer that ceiling was 16 chunks/s
+     * and we were getting 9.6. Pumping on arrival removes the ceiling and leaves
+     * round-trip time as the governor.
+     *
+     * The short coalescing delay matters too: chunks arrive in bursts, and
+     * planning is O(chunks x peers), so replanning once per burst beats
+     * replanning once per chunk.
+     */
+    private schedulePump;
+    private announceAll;
+    /**
+     * Answer a peer's announce with our own bitfield when we can serve it.
+     *
+     * Without this a fresh downloader knows a file exists but not who holds any
+     * of it, so it sits idle until the next periodic announce comes round.
+     * Measured on a 5 MB transfer that stall was 2.6 s of a 4.0 s total — the
+     * transfer itself was never the slow part. Replying on demand takes the same
+     * transfer to 1.0 s without making the room any chattier at rest.
+     *
+     * Three things keep this from becoming an announce storm: we only reply if we
+     * actually hold something the peer lacks, the reply is unicast rather than
+     * broadcast, and each peer gets at most one reply per file per second.
+     */
+    private answerAnnounce;
+    /** Tell one peer everything we can offer, then what we currently hold. */
+    private greetPeer;
+    private broadcastOffer;
+    private handleOffer;
+    private handleManifestRequest;
+    private handleManifestPage;
+    private handleAnnounce;
+    private handleHave;
+    private handleRequest;
+    private requestManifestPages;
+    private guard;
+    private reportError;
+    private handleChunk;
+    private startDownload;
+    private completeSession;
+    private sendFor;
+    private sendChunkAsBase64;
+    /**
+     * Route a frame off the shared binary lane.
+     *
+     * Anything that is not one of our chunk frames is left alone: the lane is the
+     * application's, and another feature may well be using it too.
+     */
+    private handleBinary;
+}
+export { ChunkMap };