magnetk 2.0.0 → 2.1.0

package/README.md

@@ -7,7 +7,6 @@ The professional JavaScript SDK for interacting with the Magnetk P2P network. Th
 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
 ```
 
@@ -25,23 +24,80 @@ console.log(link.fileName); // myfile.zip
 console.log(link.fileHash); // abc123...
 ```
 
+### Generating a Magnetk Link
+
+```javascript
+import { MagnetkLink } from 'magnetk';
+
+const link = new MagnetkLink(
+    '98df9a59...',           // File Hash
+    'app.txt',              // File Name
+    4,                      // File Size (bytes)
+    '12D3KooWDmX2...',      // Seed Peer ID
+    '/ip4/1.2.3.4/tcp/4001' // Relay Multiaddr
+);
+
+console.log(link.toString());
+// Output: magnetk:?dn=app.txt&relay=%2Fip4%2F1.2.3.4...
+```
+
 ### Downloading a File
 
 ```javascript
-import { MagnetkClient } from 'magnetk';
+import { MagnetkClient, CONNECTION_TYPE } from 'magnetk';
 
 const client = new MagnetkClient();
-const magnetURI = 'magnetk:?...';
+const uri = 'magnetk:?xt=urn:sha256:98df9a...&dn=app.txt&relay=/ip4/1.2.3.4/tcp/4001';
+
+try {
+    console.log('Starting P2P download...');
+    await client.download(uri, './downloads/app.txt');
+
+    // Access connection diagnostics
+    const stats = client.lastDownloadStats;
+    console.log(`Success! Connection Type: ${stats.connectionType}`);
+    console.log(`Remote Address: ${stats.remoteAddr}`);
+} catch (err) {
+    console.error('Download failed:', err.message);
+}
+```
+
+### Checking Connection Types
+
+The SDK automatically tracks the quality of your P2P connection:
+- `CONNECTION_TYPE.DIRECT`: High-speed P2P (via STUN discovered public IP).
+- `CONNECTION_TYPE.LOCAL`: Super-fast local transfer (same machine/LAN).
+- `CONNECTION_TYPE.RELAYED`: Connection bridged via relay (fallback).
+
+## Advanced Features
 
-await client.download(magnetURI, './downloads/my_file.zip');
+### NAT Traversal (STUN)
+The SDK integrates STUN to discover your public identity. You can manually check your public IP/Port:
+
+```javascript
+const identity = await client.getPublicIdentity();
+console.log(`Public Identity: ${identity.ip}:${identity.port}`);
+```
+
+### Seeding (Distributing Files)
+To share a file on the Magnetk network, use the high-performance **Go Seeder** included in the toolkit:
+
+```bash
+# Seed a file via the relay
+./bin/seed.exe -relay "/ip4/relay-ip/tcp/4001" -file "path/to/file.zip"
 ```
 
-## Features
+## CLI Interface
+
+For quick operations, use the global `magnetk` command:
 
-- **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.
+```bash
+# Lookup seeds for a hash
+magnetk lookup 98df9a59... --relay 1.2.3.4
+
+# Download a file
+magnetk download "magnetk:?..." --output ./file.zip
+```
 
 ## API Reference
 
@@ -50,8 +106,10 @@ await client.download(magnetURI, './downloads/my_file.zip');
 - `toString()`: Serialize back to string.
 
 ### `MagnetkClient`
-- `download(uri, outputPath)`: High-level download method.
-- `lookupPeer(relayHost, relayPort, fileHash)`: Find seeds for a hash.
+- `download(uri, outputPath)`: High-level P2P download.
+- `getPublicIdentity()`: Resolve public IP via STUN.
+- `lastDownloadStats`: Metadata from the previous download.
+- `lookupPeer(relayHost, relayPort, fileHash)`: Query relay for seeds.
 
 ## License
 MIT

package/client.js

@@ -7,6 +7,7 @@
 
 import net from 'net';
 import fs from 'fs';
+import dgram from 'dgram';
 import { MagnetkLink } from './magnetk.js';
 
 const MSG_TYPE = {
@@ -19,10 +20,69 @@ const MSG_TYPE = {
     MSG_ERROR: 0xFF
 };
 
+export const CONNECTION_TYPE = {
+    DIRECT: 'DIRECT',
+    RELAYED: 'RELAYED',
+    LOCAL: 'LOCAL',
+    UNKNOWN: 'UNKNOWN'
+};
+
 export class MagnetkClient {
     constructor(config = {}) {
         this.config = config;
         this.connections = new Map();
+        this.lastDownloadStats = {
+            connectionType: CONNECTION_TYPE.UNKNOWN,
+            remoteAddr: null,
+            duration: 0,
+            bytesReceived: 0
+        };
+    }
+
+    /**
+     * Retrieves the public IP and port using STUN.
+     * @returns {Promise<{ip: string, port: number}>}
+     */
+    getPublicIdentity(stunServer = 'stun.l.google.com', stunPort = 19302) {
+        return new Promise((resolve, reject) => {
+            const socket = dgram.createSocket('udp4');
+            const message = Buffer.alloc(20);
+            message.writeUInt16BE(0x0001, 0); // Binding Request
+            message.writeUInt16BE(0x0000, 2); // Length
+            message.writeUInt32BE(0x2112A442, 4); // Magic Cookie
+            for (let i = 8; i < 20; i++) message[i] = Math.floor(Math.random() * 256);
+
+            const timeout = setTimeout(() => {
+                socket.close();
+                reject(new Error('STUN discovery timed out'));
+            }, 5000);
+
+            socket.on('message', (msg) => {
+                let offset = 20;
+                while (offset < msg.length) {
+                    const attrType = msg.readUInt16BE(offset);
+                    const attrLen = msg.readUInt16BE(offset + 2);
+                    if (attrType === 0x0020) { // XOR-MAPPED-ADDRESS
+                        const port = msg.readUInt16BE(offset + 6) ^ 0x2112;
+                        const ip = [];
+                        for (let i = 0; i < 4; i++) ip.push(msg[offset + 8 + i] ^ message[4 + i]);
+                        clearTimeout(timeout);
+                        socket.close();
+                        resolve({ ip: ip.join('.'), port });
+                        return;
+                    }
+                    offset += 4 + attrLen;
+                }
+            });
+
+            socket.on('error', (err) => {
+                clearTimeout(timeout);
+                socket.close();
+                reject(err);
+            });
+
+            socket.send(message, 0, message.length, stunPort, stunServer);
+        });
     }
 
     /**
@@ -87,7 +147,7 @@ export class MagnetkClient {
         // 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
+        const discoveryPort = 4003;
 
         console.log(`[Magnetk-JS] Querying relay ${relayHost}:${discoveryPort} for seeds...`);
         let lookupResult;
@@ -95,43 +155,70 @@ export class MagnetkClient {
             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;
-
+        const addressesToTry = [];
         if (lookupResult && lookupResult.found && lookupResult.seeds.length > 0) {
             const seed = lookupResult.seeds[0];
             console.log(`[Magnetk-JS] Found seed: ${seed.peer_id}`);
 
+            // 1. Add transport_addr if present
             if (seed.transport_addr) {
-                const parts = seed.transport_addr.split(':');
-                seedHost = parts[0];
-                seedPort = parseInt(parts[1], 10) || 4002;
+                addressesToTry.push(seed.transport_addr);
+            }
+
+            // 2. Add from multiaddrs (look for /ip4/x.x.x.x/tcp/yyyy)
+            if (seed.addresses) {
+                seed.addresses.forEach(addr => {
+                    const parts = addr.split('/');
+                    if (parts.length >= 5 && parts[1] === 'ip4' && parts[3] === 'tcp') {
+                        addressesToTry.push(`${parts[2]}:${parts[4]}`);
+                    }
+                });
             }
         }
 
-        // 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.
+        // Add localhost fallback as last resort for dev
+        addressesToTry.push('127.0.0.1:4002');
 
-        console.log(`[Magnetk-JS] Connecting to seed at ${seedHost}:${seedPort} (TCP)...`);
+        // Unique addresses only
+        const uniqueAddrs = [...new Set(addressesToTry)];
+        console.log(`[Magnetk-JS] Candidate seeds: [${uniqueAddrs.join(', ')}]`);
 
         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;
+        let connectionType = CONNECTION_TYPE.UNKNOWN;
+        let finalAddr = null;
+
+        for (const addr of uniqueAddrs) {
+            const [host, portStr] = addr.split(':');
+            const port = parseInt(portStr, 10) || 4002;
+
+            try {
+                socket = await this.connect(host, port);
+                finalAddr = addr;
+
+                // Determine connection type
+                if (host === '127.0.0.1' || host === 'localhost') {
+                    connectionType = CONNECTION_TYPE.LOCAL;
+                } else if (host === relayHost) {
+                    connectionType = CONNECTION_TYPE.RELAYED;
+                } else {
+                    connectionType = CONNECTION_TYPE.DIRECT;
+                }
+                break;
+            } catch (e) {
+                console.log(`[Magnetk-JS] Failed to connect to ${addr}.`);
             }
         }
 
+        if (!socket) {
+            throw new Error('All seed connection attempts failed. Possible NAT blocking.');
+        }
+
+        this.lastDownloadStats.connectionType = connectionType;
+        this.lastDownloadStats.remoteAddr = finalAddr;
+        console.log(`[Magnetk-JS] » Final Connection: ${finalAddr} (${connectionType})`);
+
         const writer = new FrameWriter(socket);
         const reader = new FrameReader(socket);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magnetk",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "JavaScript SDK for Magnetk P2P File Transfer System",
   "main": "index.js",
   "bin": {