magnetk 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Magnetk Contributors
+
+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,57 @@
+# Magnetk JavaScript SDK
+
+The professional JavaScript SDK for interacting with the Magnetk P2P network. This SDK allows you to parse/generate Magnetk links and download files via TCP using the Magnetk binary protocol.
+
+## Installation
+
+If using as a standalone folder, simply place the `magnetk` folder into your `node_modules` or clone it into your project.
+
+```bash
+# If published to npm (future)
+npm install magnetk-sdk-js
+```
+
+## Usage
+
+### Parsing a Magnetk Link
+
+```javascript
+import { MagnetkLink } from 'magnetk';
+
+const uri = 'magnetk:?xt=urn:sha256:abc123...&dn=myfile.zip&xl=1048576&relay=1.2.3.4';
+const link = MagnetkLink.parse(uri);
+
+console.log(link.fileName); // myfile.zip
+console.log(link.fileHash); // abc123...
+```
+
+### Downloading a File
+
+```javascript
+import { MagnetkClient } from 'magnetk';
+
+const client = new MagnetkClient();
+const magnetURI = 'magnetk:?...';
+
+await client.download(magnetURI, './downloads/my_file.zip');
+```
+
+## Features
+
+- **Pure JavaScript**: No native dependencies required for core protocol handling.
+- **Fast TCP Discovery**: Connects directly to Magnetk Relay nodes to find seeds.
+- **Binary Framing**: Efficient data transfer using the Magnetk framed protocol.
+- **Magnet Link Support**: Full support for `magnetk:?` URI scheme.
+
+## API Reference
+
+### `MagnetkLink`
+- `static parse(uri)`: Create a link object from string.
+- `toString()`: Serialize back to string.
+
+### `MagnetkClient`
+- `download(uri, outputPath)`: High-level download method.
+- `lookupPeer(relayHost, relayPort, fileHash)`: Find seeds for a hash.
+
+## License
+MIT

package/cli.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+
+/**
+ * Magnetk CLI
+ * 
+ * Usage:
+ *   magnetk lookup <file_hash> [--relay <host>]
+ *   magnetk download <magnetk_uri> [--output <path>]
+ */
+
+import { MagnetkClient } from './client.js';
+import path from 'path';
+import os from 'os';
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (!command || command === '--help' || command === '-h' || command === 'help') {
+    showHelp();
+    process.exit(0);
+}
+
+const client = new MagnetkClient();
+
+async function run() {
+    try {
+        switch (command) {
+            case 'lookup': {
+                const fileHash = args[1];
+                if (!fileHash) {
+                    console.error('Error: Missing file hash.');
+                    showHelp();
+                    process.exit(1);
+                }
+
+                const relayArg = args.indexOf('--relay');
+                const relay = relayArg !== -1 ? args[relayArg + 1] : '69.169.109.243';
+                const port = 4003; // Default JS discovery port
+
+                const result = await client.lookupPeer(relay, port, fileHash);
+
+                if (result.found && result.seeds.length > 0) {
+                    console.log(`\nFound ${result.seeds.length} seed(s) on relay ${relay}:`);
+                    result.seeds.forEach((seed, i) => {
+                        console.log(`  [${i + 1}] Peer ID: ${seed.peer_id}`);
+                        console.log(`      Transport: ${seed.transport_addr || 'MsQuic/QUIC'}`);
+                    });
+
+                    // Generate a sample link if possible
+                    if (result.seeds.length > 0) {
+                        const seed = result.seeds[0];
+                        const xt = `urn:sha256:${fileHash}`;
+                        const relayAddr = `/ip4/${relay}/tcp/4001/p2p/${seed.peer_id}`; // Simplified
+                        const link = `magnetk:?xt=${xt}&relay=${encodeURIComponent(relayAddr)}&dn=downloaded_file`;
+                        console.log(`\nGenerated Magnetk Link:\n${link}\n`);
+                    }
+                } else {
+                    console.log(`\nNo seeds found for hash: ${fileHash}`);
+                }
+                break;
+            }
+
+            case 'download': {
+                const magnetURI = args[1];
+                if (!magnetURI) {
+                    console.error('Error: Missing Magnetk link.');
+                    showHelp();
+                    process.exit(1);
+                }
+
+                const outputArg = args.indexOf('--output');
+                const outputPath = outputArg !== -1 ? args[outputArg + 1] : path.join(os.homedir(), 'Desktop', 'downloaded_file');
+
+                console.log(`\n--- Magnetk P2P Download ---`);
+                console.log(`Target: ${outputPath}`);
+
+                await client.download(magnetURI, outputPath);
+                break;
+            }
+
+            default:
+                console.error(`Unknown command: ${command}`);
+                showHelp();
+                process.exit(1);
+        }
+    } catch (err) {
+        console.error(`\n[CLI Error] ${err.message}`);
+        process.exit(1);
+    }
+}
+
+function showHelp() {
+    console.log(`
+Magnetk SDK CLI v2.0.0
+----------------------
+A high-performance P2P file transfer utility.
+
+Usage:
+  magnetk <command> [options]
+
+Commands:
+  lookup <hash>       Search the relay for seeds hosting a specific file hash.
+  download <link>     Download a file using a Magnetk URI.
+
+Options:
+  --relay <host>      Specify a relay IP (default: 69.169.109.243)
+  --output <path>     Path where to save the downloaded file (default: Desktop)
+  --help, -h          Show this help message
+
+Examples:
+  magnetk lookup abc123hash
+  magnetk download "magnetk:?xt=urn:sha256:abc123hash&relay=..."
+`);
+}
+
+run();

package/client.js

@@ -0,0 +1,249 @@
+/**
+ * Magnet JS SDK - Client
+ * 
+ * Provides methods for discovery and file download using the binary framing protocol over TCP.
+ * Note: Currently supports fetching metadata/manifest. Full QUIC download requires C++ bindings.
+ */
+
+import net from 'net';
+import fs from 'fs';
+import { MagnetkLink } from './magnetk.js';
+
+const MSG_TYPE = {
+    MSG_LOOKUP_PEER: 0x03,
+    MSG_LOOKUP_RESULT: 0x04,
+    MSG_MANIFEST_REQ: 0x10,
+    MSG_MANIFEST_RES: 0x11,
+    MSG_CHUNK_REQ: 0x20,
+    MSG_CHUNK_RES: 0x21,
+    MSG_ERROR: 0xFF
+};
+
+export class MagnetkClient {
+    constructor(config = {}) {
+        this.config = config;
+        this.connections = new Map();
+    }
+
+    /**
+     * Connects to a seed via TCP.
+     * @param {string} host 
+     * @param {number} port 
+     * @returns {Promise<net.Socket>}
+     */
+    connect(host, port) {
+        return new Promise((resolve, reject) => {
+            const socket = net.createConnection(port, host, () => {
+                console.log(`[Magnetk-JS] Connected to ${host}:${port}`);
+                resolve(socket);
+            });
+            socket.on('error', (err) => {
+                console.error(`[Magnetk-JS] Connection error: ${err.message}`);
+                reject(err);
+            });
+        });
+    }
+
+    /**
+     * Look up seeds for a file hash from the relay.
+     * @param {string} relayHost 
+     * @param {number} relayPort 
+     * @param {string} fileHash 
+     * @returns {Promise<Object>}
+     */
+    async lookupPeer(relayHost, relayPort, fileHash) {
+        console.log(`[Magnetk-JS] Looking up seeds for ${fileHash.substring(0, 10)} on relay ${relayHost}:${relayPort}...`);
+        const socket = await this.connect(relayHost, relayPort);
+        const writer = new FrameWriter(socket);
+        const reader = new FrameReader(socket);
+
+        try {
+            await writer.writeJSON(MSG_TYPE.MSG_LOOKUP_PEER, { file_hash: fileHash });
+            const frame = await reader.readFrame();
+
+            if (frame.type === MSG_TYPE.MSG_LOOKUP_RESULT) {
+                const result = JSON.parse(frame.payload.toString());
+                return result;
+            } else if (frame.type === MSG_TYPE.MSG_ERROR) {
+                const err = JSON.parse(frame.payload.toString());
+                throw new Error(`Relay error: ${err.message}`);
+            } else {
+                throw new Error(`Unexpected response type: 0x${frame.type.toString(16)}`);
+            }
+        } finally {
+            socket.end();
+        }
+    }
+
+    /**
+     * Downloads a file from a magnetk link.
+     * @param {string} magnetURI 
+     * @param {string} outputPath 
+     */
+    async download(magnetURI, outputPath) {
+        const ml = MagnetkLink.parse(magnetURI);
+        console.log(`[Magnetk-JS] Starting download for: ${ml.fileName}`);
+
+        // 1. Resolve seed address from the Relay
+        // We extract the relay host from the Magnetk Link
+        const relayHost = ml.relayAddr.split('/')[2];
+        const discoveryPort = 4003; // New TCP discovery port on relay
+
+        console.log(`[Magnetk-JS] Querying relay ${relayHost}:${discoveryPort} for seeds...`);
+        let lookupResult;
+        try {
+            lookupResult = await this.lookupPeer(relayHost, discoveryPort, ml.fileHash);
+        } catch (e) {
+            console.error(`[Magnetk-JS] Initial lookup failed: ${e.message}`);
+            console.log(`[Magnetk-JS] Attempting fallback to direct connection...`);
+        }
+
+        let seedHost = relayHost; // Default to relay as fallback (unlikely to work for data)
+        let seedPort = 4002;
+
+        if (lookupResult && lookupResult.found && lookupResult.seeds.length > 0) {
+            const seed = lookupResult.seeds[0];
+            console.log(`[Magnetk-JS] Found seed: ${seed.peer_id}`);
+
+            if (seed.transport_addr) {
+                const parts = seed.transport_addr.split(':');
+                seedHost = parts[0];
+                seedPort = parseInt(parts[1], 10) || 4002;
+            }
+        }
+
+        // SPECIAL CASE for local testing:
+        // If the seed host is exactly the same as the relay host, and the connection refused,
+        // it's likely because the seeder is actually LOCAL to the user's PC.
+        // We'll try to connect to localhost if the direct connection fails.
+
+        console.log(`[Magnetk-JS] Connecting to seed at ${seedHost}:${seedPort} (TCP)...`);
+
+        let socket;
+        try {
+            socket = await this.connect(seedHost, seedPort);
+        } catch (e) {
+            if (seedHost !== '127.0.0.1' && seedHost !== 'localhost') {
+                console.log(`[Magnetk-JS] Connection to ${seedHost} failed. Trying LOCALHOST fallback for development...`);
+                socket = await this.connect('127.0.0.1', 4002);
+                seedHost = '127.0.0.1';
+            } else {
+                throw e;
+            }
+        }
+
+        const writer = new FrameWriter(socket);
+        const reader = new FrameReader(socket);
+
+        try {
+            // STEP 1: Request manifest
+            console.log(`[Magnetk-JS] Requesting manifest for ${ml.fileHash.substring(0, 10)}...`);
+            await writer.writeJSON(MSG_TYPE.MSG_MANIFEST_REQ, { file_hash: ml.fileHash });
+
+            const manifestFrame = await reader.readFrame();
+            if (manifestFrame.type !== MSG_TYPE.MSG_MANIFEST_RES) {
+                throw new Error(`Unexpected manifest response type: 0x${manifestFrame.type.toString(16)}`);
+            }
+
+            const manifest = JSON.parse(manifestFrame.payload.toString());
+            console.log(`[Magnetk-JS] Manifest received: ${manifest.file_name}, ${manifest.total_chunks} chunks, total size: ${manifest.file_size} bytes`);
+
+            // STEP 2: Prepare output file
+            const fd = fs.openSync(outputPath, 'w');
+
+            // STEP 3: Request and write chunks
+            for (let i = 0; i < manifest.total_chunks; i++) {
+                process.stdout.write(`\r[Magnetk-JS] Downloading chunk ${i + 1}/${manifest.total_chunks}...`);
+
+                await writer.writeJSON(MSG_TYPE.MSG_CHUNK_REQ, {
+                    file_hash: ml.fileHash,
+                    chunk_indices: [i]
+                });
+
+                const chunkFrame = await reader.readFrame();
+                if (chunkFrame.type !== MSG_TYPE.MSG_CHUNK_RES) {
+                    throw new Error(`Unexpected chunk response type: 0x${chunkFrame.type.toString(16)}`);
+                }
+
+                // Chunk payload format: [4 bytes: index][raw data]
+                const index = chunkFrame.payload.readUInt32BE(0);
+                const data = chunkFrame.payload.slice(4);
+
+                // Write to file at correct offset
+                const offset = i * manifest.chunk_size;
+                fs.writeSync(fd, data, 0, data.length, offset);
+            }
+
+            fs.closeSync(fd);
+            console.log(`\n[Magnetk-JS] ✓ Download complete: ${outputPath}`);
+
+        } catch (err) {
+            console.error(`[Magnetk-JS] Download failed: ${err.message}`);
+            throw err;
+        } finally {
+            socket.end();
+        }
+    }
+}
+
+class FrameWriter {
+    constructor(socket) {
+        this.socket = socket;
+    }
+
+    async writeFrame(type, payload) {
+        const header = Buffer.alloc(5);
+        header.writeUInt32BE(payload.length, 0);
+        header.writeUInt8(type, 4);
+
+        this.socket.write(header);
+        this.socket.write(payload);
+    }
+
+    async writeJSON(type, obj) {
+        const payload = Buffer.from(JSON.stringify(obj));
+        await this.writeFrame(type, payload);
+    }
+}
+
+class FrameReader {
+    constructor(socket) {
+        this.socket = socket;
+        this.buffer = Buffer.alloc(0);
+        this.pendingResolve = null;
+        this.socket.on('data', (chunk) => this._onData(chunk));
+    }
+
+    _onData(chunk) {
+        this.buffer = Buffer.concat([this.buffer, chunk]);
+        this._tryResolve();
+    }
+
+    _tryResolve() {
+        if (!this.pendingResolve) return;
+
+        if (this.buffer.length >= 5) {
+            const len = this.buffer.readUInt32BE(0);
+            const type = this.buffer.readUInt8(4);
+
+            if (this.buffer.length >= 5 + len) {
+                const payload = this.buffer.slice(5, 5 + len);
+                this.buffer = this.buffer.slice(5 + len);
+
+                const resolve = this.pendingResolve;
+                this.pendingResolve = null;
+                resolve({ type, payload });
+
+                // Try again for any buffered data
+                this._tryResolve();
+            }
+        }
+    }
+
+    readFrame() {
+        return new Promise((resolve) => {
+            this.pendingResolve = resolve;
+            this._tryResolve();
+        });
+    }
+}

package/index.js

@@ -0,0 +1,2 @@
+export * from './client.js';
+export * from './magnetk.js';

package/magnetk.js

@@ -0,0 +1,53 @@
+/**
+ * Magnetk Link Parser and Generator for Magnetk P2P
+ */
+export class MagnetkLink {
+    constructor(fileHash, fileName, fileSize, seedId, relayAddr) {
+        this.fileHash = fileHash;
+        this.fileName = fileName;
+        this.fileSize = fileSize;
+        this.seedId = seedId;
+        this.relayAddr = relayAddr;
+    }
+
+    /**
+     * Parses a magnetk URI string.
+     * Format: magnetk:?xt=urn:sha256:<hash>&dn=<name>&xl=<size>&xs=<seed_id>&relay=<relay_addr>
+     * @param {string} uri 
+     * @returns {MagnetkLink}
+     */
+    static parse(uri) {
+        if (!uri.startsWith('magnetk:?')) {
+            throw new Error('Invalid magnet link: must start with magnetk:?');
+        }
+
+        const params = new URLSearchParams(uri.slice(9)); // slicing 'magnetk:?' length is 9? No. 'magnet:?' is 8. 'magnetk:?' is 9. Correct.
+        const xt = params.get('xt');
+        if (!xt || !xt.startsWith('urn:sha256:')) {
+            throw new Error('Invalid magnet link: missing xt (urn:sha256:...)');
+        }
+
+        const fileHash = xt.split(':')[2];
+        const fileName = params.get('dn') || 'unknown_file';
+        const fileSize = parseInt(params.get('xl') || '0', 10);
+        const seedId = params.get('xs') || '';
+        const relayAddr = params.get('relay') || '';
+
+        return new MagnetkLink(fileHash, fileName, fileSize, seedId, relayAddr);
+    }
+
+    /**
+     * Generates a magnetk URI string.
+     * @returns {string}
+     */
+    toString() {
+        const parts = [];
+        parts.push(`xt=urn:sha256:${this.fileHash}`);
+        if (this.fileName) parts.push(`dn=${encodeURIComponent(this.fileName)}`);
+        if (this.fileSize > 0) parts.push(`xl=${this.fileSize}`);
+        if (this.seedId) parts.push(`xs=${encodeURIComponent(this.seedId)}`);
+        if (this.relayAddr) parts.push(`relay=${this.relayAddr}`); // Multiaddr usually kept raw
+
+        return `magnetk:?${parts.join('&')}`;
+    }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "magnetk",
+  "version": "2.0.0",
+  "description": "JavaScript SDK for Magnetk P2P File Transfer System",
+  "main": "index.js",
+  "bin": {
+    "magnetk": "cli.js"
+  },
+  "type": "module",
+  "files": [
+    "client.js",
+    "magnetk.js",
+    "index.js",
+    "utils.js",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "scripts": {
+    "test": "node test.js"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "minimist": "^1.2.8"
+  },
+  "keywords": [
+    "magnetk",
+    "p2p",
+    "quic",
+    "file-transfer",
+    "sdk"
+  ],
+  "author": "Magnetk Contributors",
+  "license": "MIT"
+}

package/utils.js

@@ -0,0 +1,38 @@
+export class MagnetkLink {
+    constructor(fileHash, fileName, relayAddr = '', seedID = '') {
+        this.fileHash = fileHash;
+        this.fileName = fileName;
+        this.relayAddr = relayAddr;
+        this.seedID = seedID;
+    }
+
+    toString() {
+        let link = `magnetk:?xt=urn:sha256:${this.fileHash}&dn=${encodeURIComponent(this.fileName)}`;
+        if (this.relayAddr) {
+            link += `&relay=${encodeURIComponent(this.relayAddr)}`;
+        }
+        if (this.seedID) {
+            link += `&xs=${encodeURIComponent(this.seedID)}`;
+        }
+        return link;
+    }
+
+    static parse(linkStr) {
+        if (!linkStr.startsWith('magnetk:?')) {
+            throw new Error('Invalid magnet link: must start with magnetk:?');
+        }
+
+        const params = new URLSearchParams(linkStr.substring(9));
+        const xt = params.get('xt');
+        if (!xt || !xt.startsWith('urn:sha256:')) {
+            throw new Error('Invalid magnet link: missing sha256 hash');
+        }
+
+        const fileHash = xt.substring(11);
+        const fileName = params.get('dn') || '';
+        const relayAddr = params.get('relay') || '';
+        const seedID = params.get('xs') || '';
+
+        return new MagnetkLink(fileHash, fileName, relayAddr, seedID);
+    }
+}