uncloud-p2p 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mathew Perkins
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1 @@
+# uncloud-p2p

package/dist/files.d.ts

@@ -0,0 +1,11 @@
+import { UncloudP2P } from "./index";
+export interface NodeFile {
+    MD5: string;
+    MimeType: string;
+    Name: string;
+    SizeBytes: number;
+}
+export declare function ListFiles(p2p: UncloudP2P): Promise<NodeFile[]>;
+export declare function LoadFileText(p2p: UncloudP2P, file: string): Promise<string>;
+export declare function LoadFileBytes(p2p: UncloudP2P, file: string): Promise<Uint8Array<ArrayBuffer>>;
+export declare function LoadFile(p2p: UncloudP2P, file: string): Promise<Blob>;

package/dist/files.js

@@ -0,0 +1,28 @@
+"use strict";
+// util functions that wrap the core of uncloudp2p
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ListFiles = ListFiles;
+exports.LoadFileText = LoadFileText;
+exports.LoadFileBytes = LoadFileBytes;
+exports.LoadFile = LoadFile;
+const uncloudproto_1 = require("./uncloudproto");
+async function ListFiles(p2p) {
+    try {
+        const resp = await p2p.sendCommand(uncloudproto_1.Actions.CLIENT_TO_NODE_LIST_FILES, null);
+        return resp;
+    }
+    catch (err) {
+        throw new Error(`failed to retreive file list from node: ${err}`);
+    }
+}
+async function LoadFileText(p2p, file) {
+    const blob = await p2p.downloadToMemory(file);
+    return await blob.text();
+}
+async function LoadFileBytes(p2p, file) {
+    const blob = await p2p.downloadToMemory(file);
+    return await blob.bytes();
+}
+async function LoadFile(p2p, file) {
+    return await p2p.downloadToMemory(file);
+}

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+import { Action } from "./uncloudproto";
+export interface IceCandidate {
+    candidate: string;
+    sdpMid: string | null;
+    sdpMLineIndex: number | null;
+}
+export interface IceExchangePayload {
+    sdp: string;
+    candidates: IceCandidate[];
+}
+export type ConnectionState = "idle" | "gathering" | "signaling" | "connecting" | "connected" | "disconnected" | "error";
+interface P2POptions {
+    nodeId: string;
+    baseUrl?: string;
+    iceServers?: RTCIceServer[];
+    onStateChange?: (state: ConnectionState) => void;
+    onMessage?: (data: string) => void;
+    onLog?: (message: string, type?: "info" | "error" | "success" | "warn") => void;
+}
+export declare class UncloudP2P {
+    private pc;
+    private dc;
+    private localCandidates;
+    private options;
+    private pendingRequests;
+    private pendingDownloads;
+    constructor(options: P2POptions);
+    private log;
+    /**
+     * Initializes the PeerConnection and starts the ICE gathering process.
+     */
+    connect(): Promise<void>;
+    /**
+     * Hits the exchange endpoint to swap SDP and ICE candidates.
+     */
+    private performExchange;
+    sendCommand<T = any>(action: Action, body: any, timeoutMs?: number): Promise<T>;
+    private setupControlChannelHooks;
+    private setupDownloadChannelHooks;
+    private saveBlob;
+    downloadFile(fileName: string): Promise<void>;
+    downloadToMemory(fileName: string): Promise<Blob>;
+    /**
+     * Returns a promise that resolves when the control channel is open.
+     */
+    waitForOpen(timeoutMs?: number): Promise<void>;
+    private updateState;
+    private handleError;
+    disconnect(): void;
+}
+export {};

package/dist/index.js

@@ -0,0 +1,257 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UncloudP2P = void 0;
+const uncloudproto_1 = require("./uncloudproto");
+class UncloudP2P {
+    constructor(options) {
+        this.pc = null;
+        this.dc = null;
+        this.localCandidates = [];
+        this.pendingRequests = new Map();
+        this.pendingDownloads = new Map();
+        this.options = {
+            baseUrl: "https://uncloud.mpsoftware.io",
+            iceServers: [{ urls: "stun:stun.l.google.com:19302" }],
+            ...options,
+        };
+    }
+    log(msg, type = "info") {
+        this.options.onLog?.(msg, type);
+    }
+    /**
+     * Initializes the PeerConnection and starts the ICE gathering process.
+     */
+    async connect() {
+        try {
+            this.updateState("gathering");
+            this.pc = new RTCPeerConnection({
+                iceServers: this.options.iceServers,
+            });
+            // Create the persistent CONTROL_STREAM immediately (Offer side)
+            this.dc = this.pc.createDataChannel(uncloudproto_1.StreamNames.CONTROL_STREAM, {
+                ordered: true,
+            });
+            this.setupControlChannelHooks(this.dc);
+            // ICE Gathering Logic
+            this.pc.onicecandidate = async (e) => {
+                if (!e.candidate) {
+                    this.log("ICE gathering complete, performing exchange...", "info");
+                    await this.performExchange();
+                }
+                else {
+                    this.localCandidates.push({
+                        candidate: e.candidate.candidate,
+                        sdpMid: e.candidate.sdpMid,
+                        sdpMLineIndex: e.candidate.sdpMLineIndex,
+                    });
+                }
+            };
+            // Incoming data handler
+            this.pc.ondatachannel = (event) => {
+                const channel = event.channel;
+                if (channel.label === uncloudproto_1.StreamNames.NODE_TO_CLIENT_FILE_TRANSFER) {
+                    this.log("Inbound file stream detected", "info");
+                    this.setupDownloadChannelHooks(channel);
+                }
+            };
+            const offer = await this.pc.createOffer();
+            await this.pc.setLocalDescription(offer);
+        }
+        catch (err) {
+            this.handleError(err);
+        }
+    }
+    /**
+     * Hits the exchange endpoint to swap SDP and ICE candidates.
+     */
+    async performExchange() {
+        if (!this.pc || !this.pc.localDescription)
+            return;
+        this.updateState("signaling");
+        const payload = {
+            sdp: this.pc.localDescription.sdp,
+            candidates: this.localCandidates,
+        };
+        try {
+            const endpoint = `${this.options.baseUrl}/api/public/node/${this.options.nodeId}/exchangeCandidates`;
+            const response = await fetch(endpoint, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(payload),
+            });
+            if (!response.ok)
+                throw new Error(`HTTP error! status: ${response.status}`);
+            const nodeResponse = await response.json();
+            await this.pc.setRemoteDescription(new RTCSessionDescription({ type: "answer", sdp: nodeResponse.sdp }));
+            for (const cand of nodeResponse.candidates) {
+                await this.pc.addIceCandidate(cand);
+            }
+            this.updateState("connecting");
+        }
+        catch (err) {
+            this.handleError(err);
+        }
+    }
+    async sendCommand(action, body, timeoutMs = 5000) {
+        if (!this.dc || this.dc.readyState !== "open") {
+            throw new Error("P2P Control channel is not open");
+        }
+        const message = (0, uncloudproto_1.newMessage)(action, body);
+        const correlationId = message.correlationId;
+        return new Promise((resolve, reject) => {
+            // 1. Set up the timeout to prevent hanging promises
+            const timeout = window.setTimeout(() => {
+                if (this.pendingRequests.has(correlationId)) {
+                    this.pendingRequests.delete(correlationId);
+                    reject(new Error(`Command ${action} timed out after ${timeoutMs}ms`));
+                }
+            }, timeoutMs);
+            // 2. Store the callbacks
+            this.pendingRequests.set(correlationId, { resolve, reject, timeout });
+            this.dc.send(message.toJSON());
+        });
+    }
+    setupControlChannelHooks(channel) {
+        channel.onopen = () => this.updateState("connected");
+        channel.onclose = () => this.updateState("disconnected");
+        channel.onmessage = (e) => {
+            try {
+                const response = JSON.parse(e.data);
+                // Check if this is a response to a pending command
+                if (response.correlationId &&
+                    this.pendingRequests.has(response.correlationId)) {
+                    const pending = this.pendingRequests.get(response.correlationId);
+                    clearTimeout(pending.timeout);
+                    this.pendingRequests.delete(response.correlationId);
+                    if (response.error) {
+                        pending.reject(response.error);
+                    }
+                    else {
+                        pending.resolve(response.body);
+                    }
+                    return;
+                }
+                // Otherwise, treat as a standard broadcast message
+                this.options.onMessage?.(e.data);
+            }
+            catch (err) {
+                this.log("Failed to parse incoming P2P message", "error");
+            }
+        };
+    }
+    setupDownloadChannelHooks(channel) {
+        let metadata = null;
+        let receivedSize = 0;
+        const chunks = [];
+        channel.binaryType = "arraybuffer";
+        channel.onmessage = (event) => {
+            if (typeof event.data === "string") {
+                metadata = JSON.parse(event.data).body;
+                return;
+            }
+            if (event.data instanceof ArrayBuffer) {
+                chunks.push(new Uint8Array(event.data));
+                receivedSize += event.data.byteLength;
+                if (metadata && receivedSize >= metadata.size) {
+                    const finalBlob = new Blob(chunks);
+                    // 3. Check if this was a "To Memory" request
+                    const pending = this.pendingDownloads.get(metadata.name);
+                    if (pending) {
+                        pending.resolve(finalBlob);
+                        this.pendingDownloads.delete(metadata.name);
+                    }
+                    else {
+                        // Default behavior: Trigger browser save
+                        this.saveBlob(chunks, metadata.name);
+                    }
+                    channel.close();
+                }
+            }
+        };
+        channel.onerror = () => {
+            if (metadata)
+                this.pendingDownloads
+                    .get(metadata.name)
+                    ?.reject(new Error("Channel error"));
+        };
+    }
+    saveBlob(chunks, fileName) {
+        const blob = new Blob(chunks);
+        const url = URL.createObjectURL(blob);
+        const a = document.createElement("a");
+        a.href = url;
+        a.download = fileName;
+        a.click();
+        URL.revokeObjectURL(url);
+        this.log(`Download complete: ${fileName}`, "success");
+    }
+    async downloadFile(fileName) {
+        this.log(`Requesting download: ${fileName}...`);
+        // Request the file via the established Control Channel
+        return this.sendCommand(uncloudproto_1.Actions.NODE_TO_CLIENT_FILE_TRANSFER, {
+            name: fileName,
+        });
+    }
+    async downloadToMemory(fileName) {
+        this.log(`Downloading ${fileName} to memory...`);
+        return new Promise(async (resolve, reject) => {
+            // 1. Store the promise callbacks indexed by filename
+            // Note: If you expect multiple concurrent downloads of the same name,
+            // you'd need a more unique ID here.
+            this.pendingDownloads.set(fileName, { resolve, reject });
+            try {
+                // 2. Trigger the request
+                await this.sendCommand(uncloudproto_1.Actions.NODE_TO_CLIENT_FILE_TRANSFER, {
+                    name: fileName,
+                });
+            }
+            catch (err) {
+                this.pendingDownloads.delete(fileName);
+                reject(err);
+            }
+        });
+    }
+    /**
+     * Returns a promise that resolves when the control channel is open.
+     */
+    async waitForOpen(timeoutMs = 10000) {
+        if (this.dc && this.dc.readyState === "open")
+            return;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new Error("Timeout waiting for P2P channel to open"));
+            }, timeoutMs);
+            // Check every 100ms or use the existing onopen hook
+            const checkInterval = setInterval(() => {
+                if (this.dc && this.dc.readyState === "open") {
+                    clearInterval(checkInterval);
+                    clearTimeout(timer);
+                    resolve();
+                }
+                // If we hit an error state, stop checking
+                if (this.pc?.iceConnectionState === "failed" ||
+                    this.pc?.iceConnectionState === "closed") {
+                    clearInterval(checkInterval);
+                    clearTimeout(timer);
+                    reject(new Error("P2P Connection failed before channel opened"));
+                }
+            }, 100);
+        });
+    }
+    updateState(state) {
+        this.options.onStateChange?.(state);
+    }
+    handleError(err) {
+        this.log(`P2P Error: ${err.message || err}`, "error");
+        this.updateState("error");
+    }
+    disconnect() {
+        this.dc?.close();
+        this.pc?.close();
+        this.pc = null;
+        this.dc = null;
+        this.localCandidates = [];
+        this.updateState("idle");
+    }
+}
+exports.UncloudP2P = UncloudP2P;

package/dist/uncloudproto.d.ts

@@ -0,0 +1,34 @@
+type Version = number;
+export declare const WEBRTC_CONTROL_PROTO_VERSION: Version;
+export declare class ControlMessage<T = unknown> {
+    version: Version;
+    action: Action;
+    correlationId: string;
+    body?: T | undefined;
+    constructor(version: Version, action: Action, correlationId: string, body?: T | undefined);
+    toJSON(): string;
+}
+export interface FileMetadata {
+    name: string;
+    size: number;
+}
+export declare function newMessage<T>(action: Action, body?: T): ControlMessage<T>;
+export declare function newMessageJSON<T>(action: Action, body?: T): string;
+export declare const StreamNames: {
+    readonly CONTROL_STREAM: "control_stream";
+    readonly CLIENT_TO_NODE_FILE_TRANSFER: "client_to_node_file_transfer";
+    readonly NODE_TO_CLIENT_FILE_TRANSFER: "node_to_client_file_transfer";
+};
+export type StreamName = (typeof StreamNames)[keyof typeof StreamNames];
+export declare const Actions: {
+    CLIENT_TO_NODE_FILE_TRANSFER: string;
+    NODE_TO_CLIENT_FILE_TRANSFER: string;
+    CLIENT_TO_NODE_LIST_FILES: string;
+};
+export type Action = (typeof Actions)[keyof typeof Actions];
+export type PendingRequest = {
+    resolve: (value: any) => void;
+    reject: (reason: any) => void;
+    timeout: number;
+};
+export {};

package/dist/uncloudproto.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Actions = exports.StreamNames = exports.ControlMessage = exports.WEBRTC_CONTROL_PROTO_VERSION = void 0;
+exports.newMessage = newMessage;
+exports.newMessageJSON = newMessageJSON;
+exports.WEBRTC_CONTROL_PROTO_VERSION = 1;
+class ControlMessage {
+    constructor(version, action, correlationId, body) {
+        this.version = version;
+        this.action = action;
+        this.correlationId = correlationId;
+        this.body = body;
+    }
+    toJSON() {
+        return JSON.stringify({
+            version: this.version,
+            action: this.action,
+            correlationId: this.correlationId,
+            body: this.body,
+        });
+    }
+}
+exports.ControlMessage = ControlMessage;
+function newMessage(action, body) {
+    const correlationId = crypto.randomUUID();
+    return new ControlMessage(exports.WEBRTC_CONTROL_PROTO_VERSION, action, correlationId, body);
+}
+function newMessageJSON(action, body) {
+    return JSON.stringify(newMessage(action, body));
+}
+// COPY ME FROM SERVER SIDE
+// THEY MUST MATCH
+exports.StreamNames = {
+    CONTROL_STREAM: "control_stream",
+    CLIENT_TO_NODE_FILE_TRANSFER: "client_to_node_file_transfer",
+    NODE_TO_CLIENT_FILE_TRANSFER: "node_to_client_file_transfer",
+};
+// COPY ME FROM SERVER SIDE
+// THEY MUST MATCH
+exports.Actions = {
+    CLIENT_TO_NODE_FILE_TRANSFER: "client_to_node_file_transfer",
+    NODE_TO_CLIENT_FILE_TRANSFER: "node_to_client_file_transfer",
+    CLIENT_TO_NODE_LIST_FILES: "client_to_node_list_files",
+};

package/example/index.html

@@ -0,0 +1,59 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Uncloud P2P Demo</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+  </head>
+  <body class="bg-zinc-950 text-zinc-100 font-sans min-h-screen p-12">
+    <div
+      class="max-w-2xl mx-auto border border-zinc-800 bg-zinc-900 p-8 rounded-xl"
+    >
+      <h1 class="text-2xl font-black uppercase tracking-widest mb-6">
+        P2P Node Connection
+      </h1>
+
+      <div class="flex gap-2 mb-8">
+        <input
+          id="nodeId"
+          type="text"
+          placeholder="Enter Node ID"
+          class="bg-black border border-zinc-800 px-4 py-2 rounded flex-1 font-mono text-sm focus:border-yellow-400 outline-none"
+        />
+        <button
+          id="connectBtn"
+          class="bg-zinc-100 text-black px-6 py-2 rounded font-bold uppercase text-xs hover:bg-yellow-400 transition-colors"
+        >
+          Connect
+        </button>
+      </div>
+
+      <div class="space-y-4">
+        <div
+          class="flex justify-between items-center border-b border-zinc-800 pb-2"
+        >
+          <span class="text-[10px] font-mono text-zinc-500 uppercase"
+            >Status</span
+          >
+          <span
+            id="status"
+            class="text-xs font-black uppercase tracking-tighter text-zinc-600"
+            >Idle</span
+          >
+        </div>
+
+        <div
+          id="logs"
+          class="bg-black p-4 h-48 overflow-y-auto font-mono text-[11px] text-zinc-400 space-y-1 rounded border border-zinc-800"
+        >
+          <div class="text-zinc-600 italic">
+            // Connection logs will appear here...
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <script type="module" src="./main.ts"></script>
+  </body>
+</html>

package/example/main.ts

@@ -0,0 +1,64 @@
+import { UncloudP2P, ConnectionState } from "../src/index";
+import { Actions } from "../src/uncloudproto";
+import { ListFiles, LoadFileText } from "../src/files";
+
+const statusEl = document.getElementById("status")!;
+const logsEl = document.getElementById("logs")!;
+const connectBtn = document.getElementById("connectBtn") as HTMLButtonElement;
+const nodeIdInput = document.getElementById("nodeId") as HTMLInputElement;
+
+function log(msg: string, type: string = "info") {
+  const div = document.createElement("div");
+  const colors = {
+    info: "text-zinc-400",
+    success: "text-emerald-400",
+    error: "text-red-500",
+    warn: "text-yellow-400",
+  };
+  div.className = colors[type as keyof typeof colors];
+  div.textContent = `[${new Date().toLocaleTimeString()}] ${msg}`;
+  logsEl.appendChild(div);
+  logsEl.scrollTop = logsEl.scrollHeight;
+}
+
+const updateStatusUI = (state: ConnectionState) => {
+  statusEl.textContent = state;
+  const colors: Record<string, string> = {
+    connected: "text-emerald-500",
+    error: "text-red-500",
+    connecting: "text-yellow-400",
+    idle: "text-zinc-600",
+  };
+  statusEl.className = `text-xs font-black uppercase tracking-tighter ${colors[state] || "text-zinc-400"}`;
+};
+
+connectBtn.onclick = async () => {
+  const nodeId = nodeIdInput.value.trim();
+  if (!nodeId) return alert("Please enter a Node ID");
+
+  const p2p = new UncloudP2P({
+    baseUrl: "http://localhost:3001",
+    nodeId: nodeId,
+    onStateChange: updateStatusUI,
+    onLog: (msg, type) => log(msg, type),
+    onMessage: (data) => log(`Message: ${data}`, "success"),
+  });
+
+  log(`Initializing connection to ${nodeId}...`);
+  await p2p.connect();
+  await p2p.waitForOpen();
+
+  try {
+    const files = await ListFiles(p2p);
+
+    files.forEach((file) => {
+      log(`${file.Name} (${(file.SizeBytes / 1024).toFixed(2)} KB)`, "info");
+    });
+  } catch (err) {
+    console.error("Command failed: ", err);
+  }
+
+  const text = await LoadFileText(p2p, "test/dst/file.txt");
+
+  log(text, "info");
+};

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "uncloud-p2p",
+  "version": "1.0.0",
+  "description": "Public Peer to Peer File Reader",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "dev": "vite example"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mperkins808/uncloud-p2p.git"
+  },
+  "author": "Mathew Perkins",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "vite": "^8.0.11"
+  }
+}

package/src/files.ts

@@ -0,0 +1,44 @@
+// util functions that wrap the core of uncloudp2p
+
+import { Actions, FileMetadata } from "./uncloudproto";
+import { UncloudP2P } from "./index";
+
+export interface NodeFile {
+  MD5: string;
+  MimeType: string;
+  Name: string;
+  SizeBytes: number;
+}
+
+export async function ListFiles(p2p: UncloudP2P): Promise<NodeFile[]> {
+  try {
+    const resp = await p2p.sendCommand<NodeFile[]>(
+      Actions.CLIENT_TO_NODE_LIST_FILES,
+      null,
+    );
+
+    return resp;
+  } catch (err) {
+    throw new Error(`failed to retreive file list from node: ${err}`);
+  }
+}
+
+export async function LoadFileText(
+  p2p: UncloudP2P,
+  file: string,
+): Promise<string> {
+  const blob = await p2p.downloadToMemory(file);
+  return await blob.text();
+}
+
+export async function LoadFileBytes(
+  p2p: UncloudP2P,
+  file: string,
+): Promise<Uint8Array<ArrayBuffer>> {
+  const blob = await p2p.downloadToMemory(file);
+  return await blob.bytes();
+}
+
+export async function LoadFile(p2p: UncloudP2P, file: string): Promise<Blob> {
+  return await p2p.downloadToMemory(file);
+}

package/src/index.ts

@@ -0,0 +1,351 @@
+import {
+  StreamNames,
+  newMessageJSON,
+  Actions,
+  PendingRequest,
+  Action,
+  newMessage,
+} from "./uncloudproto";
+
+export interface IceCandidate {
+  candidate: string;
+  sdpMid: string | null;
+  sdpMLineIndex: number | null;
+}
+
+export interface IceExchangePayload {
+  sdp: string;
+  candidates: IceCandidate[];
+}
+
+export type ConnectionState =
+  | "idle"
+  | "gathering"
+  | "signaling"
+  | "connecting"
+  | "connected"
+  | "disconnected"
+  | "error";
+
+interface P2POptions {
+  nodeId: string;
+  baseUrl?: string; // Allow setting the API base URL
+  iceServers?: RTCIceServer[];
+  onStateChange?: (state: ConnectionState) => void;
+  onMessage?: (data: string) => void;
+  onLog?: (
+    message: string,
+    type?: "info" | "error" | "success" | "warn",
+  ) => void;
+}
+
+export class UncloudP2P {
+  private pc: RTCPeerConnection | null = null;
+  private dc: RTCDataChannel | null = null;
+  private localCandidates: IceCandidate[] = [];
+  private options: P2POptions;
+  private pendingRequests: Map<string, PendingRequest> = new Map();
+  private pendingDownloads: Map<
+    string,
+    { resolve: (blob: Blob) => void; reject: (err: any) => void }
+  > = new Map();
+
+  constructor(options: P2POptions) {
+    this.options = {
+      baseUrl: "https://uncloud.mpsoftware.io",
+      iceServers: [{ urls: "stun:stun.l.google.com:19302" }],
+      ...options,
+    };
+  }
+
+  private log(
+    msg: string,
+    type: "info" | "error" | "success" | "warn" = "info",
+  ) {
+    this.options.onLog?.(msg, type);
+  }
+
+  /**
+   * Initializes the PeerConnection and starts the ICE gathering process.
+   */
+  public async connect(): Promise<void> {
+    try {
+      this.updateState("gathering");
+
+      this.pc = new RTCPeerConnection({
+        iceServers: this.options.iceServers,
+      });
+
+      // Create the persistent CONTROL_STREAM immediately (Offer side)
+      this.dc = this.pc.createDataChannel(StreamNames.CONTROL_STREAM, {
+        ordered: true,
+      });
+      this.setupControlChannelHooks(this.dc);
+
+      // ICE Gathering Logic
+      this.pc.onicecandidate = async (e) => {
+        if (!e.candidate) {
+          this.log("ICE gathering complete, performing exchange...", "info");
+          await this.performExchange();
+        } else {
+          this.localCandidates.push({
+            candidate: e.candidate.candidate,
+            sdpMid: e.candidate.sdpMid,
+            sdpMLineIndex: e.candidate.sdpMLineIndex,
+          });
+        }
+      };
+
+      // Incoming data handler
+      this.pc.ondatachannel = (event) => {
+        const channel = event.channel;
+        if (channel.label === StreamNames.NODE_TO_CLIENT_FILE_TRANSFER) {
+          this.log("Inbound file stream detected", "info");
+          this.setupDownloadChannelHooks(channel);
+        }
+      };
+
+      const offer = await this.pc.createOffer();
+      await this.pc.setLocalDescription(offer);
+    } catch (err) {
+      this.handleError(err);
+    }
+  }
+
+  /**
+   * Hits the exchange endpoint to swap SDP and ICE candidates.
+   */
+  private async performExchange() {
+    if (!this.pc || !this.pc.localDescription) return;
+
+    this.updateState("signaling");
+
+    const payload: IceExchangePayload = {
+      sdp: this.pc.localDescription.sdp,
+      candidates: this.localCandidates,
+    };
+
+    try {
+      const endpoint = `${this.options.baseUrl}/api/public/node/${this.options.nodeId}/exchangeCandidates`;
+
+      const response = await fetch(endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+      });
+
+      if (!response.ok)
+        throw new Error(`HTTP error! status: ${response.status}`);
+
+      const nodeResponse: IceExchangePayload = await response.json();
+
+      await this.pc.setRemoteDescription(
+        new RTCSessionDescription({ type: "answer", sdp: nodeResponse.sdp }),
+      );
+
+      for (const cand of nodeResponse.candidates) {
+        await this.pc.addIceCandidate(cand);
+      }
+
+      this.updateState("connecting");
+    } catch (err) {
+      this.handleError(err);
+    }
+  }
+
+  public async sendCommand<T = any>(
+    action: Action,
+    body: any,
+    timeoutMs: number = 5000,
+  ): Promise<T> {
+    if (!this.dc || this.dc.readyState !== "open") {
+      throw new Error("P2P Control channel is not open");
+    }
+
+    const message = newMessage(action, body);
+    const correlationId = message.correlationId;
+
+    return new Promise((resolve, reject) => {
+      // 1. Set up the timeout to prevent hanging promises
+      const timeout = window.setTimeout(() => {
+        if (this.pendingRequests.has(correlationId)) {
+          this.pendingRequests.delete(correlationId);
+          reject(new Error(`Command ${action} timed out after ${timeoutMs}ms`));
+        }
+      }, timeoutMs);
+
+      // 2. Store the callbacks
+      this.pendingRequests.set(correlationId, { resolve, reject, timeout });
+
+      this.dc!.send(message.toJSON());
+    });
+  }
+
+  private setupControlChannelHooks(channel: RTCDataChannel) {
+    channel.onopen = () => this.updateState("connected");
+    channel.onclose = () => this.updateState("disconnected");
+
+    channel.onmessage = (e) => {
+      try {
+        const response = JSON.parse(e.data);
+
+        // Check if this is a response to a pending command
+        if (
+          response.correlationId &&
+          this.pendingRequests.has(response.correlationId)
+        ) {
+          const pending = this.pendingRequests.get(response.correlationId)!;
+
+          clearTimeout(pending.timeout);
+          this.pendingRequests.delete(response.correlationId);
+
+          if (response.error) {
+            pending.reject(response.error);
+          } else {
+            pending.resolve(response.body);
+          }
+          return;
+        }
+
+        // Otherwise, treat as a standard broadcast message
+        this.options.onMessage?.(e.data);
+      } catch (err) {
+        this.log("Failed to parse incoming P2P message", "error");
+      }
+    };
+  }
+
+  private setupDownloadChannelHooks(channel: RTCDataChannel) {
+    let metadata: { name: string; size: number } | null = null;
+    let receivedSize = 0;
+    const chunks: Uint8Array[] = [];
+
+    channel.binaryType = "arraybuffer";
+
+    channel.onmessage = (event) => {
+      if (typeof event.data === "string") {
+        metadata = JSON.parse(event.data).body;
+        return;
+      }
+
+      if (event.data instanceof ArrayBuffer) {
+        chunks.push(new Uint8Array(event.data));
+        receivedSize += event.data.byteLength;
+
+        if (metadata && receivedSize >= metadata.size) {
+          const finalBlob = new Blob(chunks as any);
+
+          // 3. Check if this was a "To Memory" request
+          const pending = this.pendingDownloads.get(metadata.name);
+          if (pending) {
+            pending.resolve(finalBlob);
+            this.pendingDownloads.delete(metadata.name);
+          } else {
+            // Default behavior: Trigger browser save
+            this.saveBlob(chunks, metadata.name);
+          }
+
+          channel.close();
+        }
+      }
+    };
+
+    channel.onerror = () => {
+      if (metadata)
+        this.pendingDownloads
+          .get(metadata.name)
+          ?.reject(new Error("Channel error"));
+    };
+  }
+
+  private saveBlob(chunks: Uint8Array[], fileName: string) {
+    const blob = new Blob(chunks as any);
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = fileName;
+    a.click();
+    URL.revokeObjectURL(url);
+    this.log(`Download complete: ${fileName}`, "success");
+  }
+
+  public async downloadFile(fileName: string): Promise<void> {
+    this.log(`Requesting download: ${fileName}...`);
+
+    // Request the file via the established Control Channel
+    return this.sendCommand(Actions.NODE_TO_CLIENT_FILE_TRANSFER, {
+      name: fileName,
+    });
+  }
+
+  public async downloadToMemory(fileName: string): Promise<Blob> {
+    this.log(`Downloading ${fileName} to memory...`);
+
+    return new Promise(async (resolve, reject) => {
+      // 1. Store the promise callbacks indexed by filename
+      // Note: If you expect multiple concurrent downloads of the same name,
+      // you'd need a more unique ID here.
+      this.pendingDownloads.set(fileName, { resolve, reject });
+
+      try {
+        // 2. Trigger the request
+        await this.sendCommand(Actions.NODE_TO_CLIENT_FILE_TRANSFER, {
+          name: fileName,
+        });
+      } catch (err) {
+        this.pendingDownloads.delete(fileName);
+        reject(err);
+      }
+    });
+  }
+
+  /**
+   * Returns a promise that resolves when the control channel is open.
+   */
+  public async waitForOpen(timeoutMs: number = 10000): Promise<void> {
+    if (this.dc && this.dc.readyState === "open") return;
+
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        reject(new Error("Timeout waiting for P2P channel to open"));
+      }, timeoutMs);
+
+      // Check every 100ms or use the existing onopen hook
+      const checkInterval = setInterval(() => {
+        if (this.dc && this.dc.readyState === "open") {
+          clearInterval(checkInterval);
+          clearTimeout(timer);
+          resolve();
+        }
+
+        // If we hit an error state, stop checking
+        if (
+          this.pc?.iceConnectionState === "failed" ||
+          this.pc?.iceConnectionState === "closed"
+        ) {
+          clearInterval(checkInterval);
+          clearTimeout(timer);
+          reject(new Error("P2P Connection failed before channel opened"));
+        }
+      }, 100);
+    });
+  }
+
+  private updateState(state: ConnectionState) {
+    this.options.onStateChange?.(state);
+  }
+
+  private handleError(err: any) {
+    this.log(`P2P Error: ${err.message || err}`, "error");
+    this.updateState("error");
+  }
+
+  public disconnect() {
+    this.dc?.close();
+    this.pc?.close();
+    this.pc = null;
+    this.dc = null;
+    this.localCandidates = [];
+    this.updateState("idle");
+  }
+}

package/src/uncloudproto.ts

@@ -0,0 +1,69 @@
+type Version = number;
+
+export const WEBRTC_CONTROL_PROTO_VERSION: Version = 1;
+
+export class ControlMessage<T = unknown> {
+  constructor(
+    public version: Version,
+    public action: Action,
+    public correlationId: string,
+    public body?: T,
+  ) {}
+
+  toJSON(): string {
+    return JSON.stringify({
+      version: this.version,
+      action: this.action,
+      correlationId: this.correlationId,
+      body: this.body,
+    });
+  }
+}
+
+export interface FileMetadata {
+  name: string;
+  size: number;
+}
+
+export function newMessage<T>(action: Action, body?: T): ControlMessage<T> {
+  const correlationId = crypto.randomUUID();
+
+  return new ControlMessage(
+    WEBRTC_CONTROL_PROTO_VERSION,
+    action,
+    correlationId,
+    body,
+  );
+}
+
+export function newMessageJSON<T>(action: Action, body?: T): string {
+  return JSON.stringify(newMessage<T>(action, body));
+}
+
+// COPY ME FROM SERVER SIDE
+// THEY MUST MATCH
+
+export const StreamNames = {
+  CONTROL_STREAM: "control_stream",
+  CLIENT_TO_NODE_FILE_TRANSFER: "client_to_node_file_transfer",
+  NODE_TO_CLIENT_FILE_TRANSFER: "node_to_client_file_transfer",
+} as const;
+
+export type StreamName = (typeof StreamNames)[keyof typeof StreamNames];
+
+// COPY ME FROM SERVER SIDE
+// THEY MUST MATCH
+
+export const Actions = {
+  CLIENT_TO_NODE_FILE_TRANSFER: "client_to_node_file_transfer",
+  NODE_TO_CLIENT_FILE_TRANSFER: "node_to_client_file_transfer",
+  CLIENT_TO_NODE_LIST_FILES: "client_to_node_list_files",
+};
+
+export type Action = (typeof Actions)[keyof typeof Actions];
+
+export type PendingRequest = {
+  resolve: (value: any) => void;
+  reject: (reason: any) => void;
+  timeout: number;
+};

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "lib": ["DOM", "ES2020"],
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+  },
+  "include": ["src/**/*"],
+}