ezshare-cli 1.0.0

package/dist/utils/crypto.js

@@ -0,0 +1,236 @@
+/**
+ * Crypto utilities for HyperStream
+ *
+ * Uses AES-256-GCM with chunked encryption for true streaming support.
+ * Each chunk is independently authenticated, allowing fail-fast on corruption.
+ *
+ * Stream format:
+ *   [4 bytes: nonce prefix]     <- sent once at start
+ *   [chunks...]
+ *   [4 bytes: 0x00000000]       <- end marker
+ *
+ * Chunk format:
+ *   [4 bytes: plaintext length, big-endian]
+ *   [ciphertext]
+ *   [16 bytes: GCM auth tag]
+ *
+ * Nonce construction for chunk N:
+ *   [4-byte random prefix][8-byte big-endian counter N]
+ *
+ * This ensures unique nonces across all chunks and sessions.
+ */
+import { Transform } from 'node:stream';
+import { createCipheriv, createDecipheriv, randomBytes, hkdfSync, } from 'node:crypto';
+// Constants
+const ALGORITHM = 'aes-256-gcm';
+const CHUNK_SIZE = 64 * 1024; // 64KB chunks - good balance of overhead vs latency
+const NONCE_PREFIX_SIZE = 4;
+const NONCE_SIZE = 12; // 4 prefix + 8 counter (standard GCM nonce)
+const TAG_SIZE = 16; // GCM authentication tag
+const LENGTH_SIZE = 4; // uint32 for chunk length
+const KEY_SIZE = 32; // AES-256
+// HKDF parameters for key derivation
+const HKDF_SALT = 'hyperstream-v1';
+const HKDF_INFO = 'aes-256-gcm';
+/**
+ * Derive AES-256 key from topic using HKDF-SHA256
+ *
+ * Never use the topic directly as a key - always derive through HKDF
+ * for proper cryptographic key derivation with domain separation.
+ */
+export function deriveKey(topic) {
+    if (topic.length !== KEY_SIZE) {
+        throw new Error(`Topic must be ${KEY_SIZE} bytes, got ${topic.length}`);
+    }
+    return Buffer.from(hkdfSync('sha256', topic, HKDF_SALT, HKDF_INFO, KEY_SIZE));
+}
+/**
+ * Generate a random topic key for sharing
+ *
+ * @returns Object with raw topic buffer and display-friendly base64url string
+ */
+export function generateTopicKey() {
+    const topic = randomBytes(KEY_SIZE);
+    const displayKey = topic.toString('base64url');
+    return { topic, displayKey };
+}
+/**
+ * Parse a display key back to a topic buffer
+ *
+ * @param displayKey - base64url encoded topic key
+ * @throws Error if key is invalid length
+ */
+export function parseTopicKey(displayKey) {
+    const topic = Buffer.from(displayKey, 'base64url');
+    if (topic.length !== KEY_SIZE) {
+        throw new Error(`Invalid key: expected ${KEY_SIZE} bytes, got ${topic.length}`);
+    }
+    return topic;
+}
+/**
+ * Construct nonce from prefix and counter
+ */
+function makeNonce(prefix, counter) {
+    const nonce = Buffer.alloc(NONCE_SIZE);
+    prefix.copy(nonce, 0, 0, NONCE_PREFIX_SIZE);
+    nonce.writeBigUInt64BE(counter, NONCE_PREFIX_SIZE);
+    return nonce;
+}
+/**
+ * Encrypt a single chunk with AES-256-GCM
+ */
+function encryptChunk(key, noncePrefix, counter, plaintext) {
+    const nonce = makeNonce(noncePrefix, counter);
+    const cipher = createCipheriv(ALGORITHM, key, nonce);
+    const ciphertext = Buffer.concat([
+        cipher.update(plaintext),
+        cipher.final(),
+    ]);
+    const tag = cipher.getAuthTag();
+    // Output format: [length][ciphertext][tag]
+    const output = Buffer.alloc(LENGTH_SIZE + ciphertext.length + TAG_SIZE);
+    output.writeUInt32BE(plaintext.length, 0);
+    ciphertext.copy(output, LENGTH_SIZE);
+    tag.copy(output, LENGTH_SIZE + ciphertext.length);
+    return output;
+}
+/**
+ * Decrypt a single chunk with AES-256-GCM
+ *
+ * @throws Error if authentication fails (wrong key or corrupted data)
+ */
+function decryptChunk(key, noncePrefix, counter, ciphertext, tag) {
+    const nonce = makeNonce(noncePrefix, counter);
+    const decipher = createDecipheriv(ALGORITHM, key, nonce);
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}
+/**
+ * Create an encrypting transform stream
+ *
+ * Buffers input data and encrypts in CHUNK_SIZE chunks.
+ * Outputs:
+ *   1. Nonce prefix (4 bytes) - sent first
+ *   2. Encrypted chunks
+ *   3. End marker (4 zero bytes) - sent last
+ *
+ * @param key - 32-byte AES key (use deriveKey to get this from topic)
+ */
+export function createEncryptStream(key) {
+    const noncePrefix = randomBytes(NONCE_PREFIX_SIZE);
+    let counter = 0n;
+    let buffer = Buffer.alloc(0);
+    let headerSent = false;
+    return new Transform({
+        transform(chunk, _encoding, callback) {
+            try {
+                // Send nonce prefix header on first data
+                if (!headerSent) {
+                    this.push(noncePrefix);
+                    headerSent = true;
+                }
+                buffer = Buffer.concat([buffer, chunk]);
+                // Process complete chunks
+                while (buffer.length >= CHUNK_SIZE) {
+                    const plaintext = buffer.subarray(0, CHUNK_SIZE);
+                    buffer = buffer.subarray(CHUNK_SIZE);
+                    const encrypted = encryptChunk(key, noncePrefix, counter, plaintext);
+                    counter++;
+                    this.push(encrypted);
+                }
+                callback();
+            }
+            catch (err) {
+                callback(err instanceof Error ? err : new Error(String(err)));
+            }
+        },
+        flush(callback) {
+            try {
+                // Encrypt any remaining buffered data
+                if (buffer.length > 0) {
+                    const encrypted = encryptChunk(key, noncePrefix, counter, buffer);
+                    this.push(encrypted);
+                }
+                // Send end marker (length = 0)
+                const endMarker = Buffer.alloc(LENGTH_SIZE, 0);
+                this.push(endMarker);
+                callback();
+            }
+            catch (err) {
+                callback(err instanceof Error ? err : new Error(String(err)));
+            }
+        },
+    });
+}
+/**
+ * Create a decrypting transform stream
+ *
+ * Parses and decrypts the encrypted stream format.
+ * Expects:
+ *   1. Nonce prefix (4 bytes)
+ *   2. Encrypted chunks
+ *   3. End marker (4 zero bytes)
+ *
+ * @param key - 32-byte AES key (use deriveKey to get this from topic)
+ * @throws Propagates authentication errors if data is corrupted
+ */
+export function createDecryptStream(key) {
+    let noncePrefix = null;
+    let counter = 0n;
+    let buffer = Buffer.alloc(0);
+    let chunkLength = null;
+    let ended = false;
+    return new Transform({
+        transform(chunk, _encoding, callback) {
+            if (ended) {
+                return callback();
+            }
+            buffer = Buffer.concat([buffer, chunk]);
+            try {
+                // Phase 1: Read nonce prefix (once)
+                if (noncePrefix === null) {
+                    if (buffer.length < NONCE_PREFIX_SIZE) {
+                        return callback(); // Need more data
+                    }
+                    noncePrefix = Buffer.from(buffer.subarray(0, NONCE_PREFIX_SIZE));
+                    buffer = buffer.subarray(NONCE_PREFIX_SIZE);
+                }
+                // Phase 2: Process chunks
+                while (!ended) {
+                    // Read chunk length if not yet known
+                    if (chunkLength === null) {
+                        if (buffer.length < LENGTH_SIZE) {
+                            return callback(); // Need more data
+                        }
+                        chunkLength = buffer.readUInt32BE(0);
+                        buffer = buffer.subarray(LENGTH_SIZE);
+                        // Check for end marker
+                        if (chunkLength === 0) {
+                            ended = true;
+                            return callback();
+                        }
+                    }
+                    // Wait for complete chunk (ciphertext + tag)
+                    const neededBytes = chunkLength + TAG_SIZE;
+                    if (buffer.length < neededBytes) {
+                        return callback(); // Need more data
+                    }
+                    // Extract ciphertext and tag
+                    const ciphertext = buffer.subarray(0, chunkLength);
+                    const tag = buffer.subarray(chunkLength, neededBytes);
+                    buffer = buffer.subarray(neededBytes);
+                    // Decrypt and output
+                    const plaintext = decryptChunk(key, noncePrefix, counter, ciphertext, tag);
+                    counter++;
+                    chunkLength = null;
+                    this.push(plaintext);
+                }
+                callback();
+            }
+            catch (err) {
+                // Authentication failures will be caught here
+                callback(err instanceof Error ? err : new Error(String(err)));
+            }
+        },
+    });
+}

package/dist/utils/fileSystem.js

@@ -0,0 +1,89 @@
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * Read a directory and return sorted file entries
+ * @param dirPath - Path to directory to read
+ * @param showHidden - Whether to include hidden files (default: false)
+ * @returns Array of file entries sorted (directories first, then alphabetically)
+ */
+export async function readDirectory(dirPath, showHidden = false) {
+    try {
+        const entries = await readdir(dirPath, { withFileTypes: true });
+        const fileEntries = [];
+        for (const entry of entries) {
+            const name = entry.name;
+            const isHidden = name.startsWith('.');
+            // Skip hidden files unless showHidden is true
+            if (isHidden && !showHidden) {
+                continue;
+            }
+            const fullPath = join(dirPath, name);
+            let size;
+            // Get size for files
+            if (entry.isFile()) {
+                try {
+                    const stats = await stat(fullPath);
+                    size = stats.size;
+                }
+                catch {
+                    // If we can't stat the file, skip the size
+                    size = undefined;
+                }
+            }
+            fileEntries.push({
+                name,
+                path: fullPath,
+                isDirectory: entry.isDirectory(),
+                size,
+                isHidden,
+            });
+        }
+        // Sort: directories first, then files, both alphabetically
+        fileEntries.sort((a, b) => {
+            // Directories come before files
+            if (a.isDirectory && !b.isDirectory)
+                return -1;
+            if (!a.isDirectory && b.isDirectory)
+                return 1;
+            // Within same type, sort alphabetically (case-insensitive)
+            return a.name.toLowerCase().localeCompare(b.name.toLowerCase());
+        });
+        return fileEntries;
+    }
+    catch (error) {
+        // If directory can't be read, return empty array
+        console.error(`Error reading directory ${dirPath}:`, error);
+        return [];
+    }
+}
+/**
+ * Get information about a specific file or directory
+ * @param filePath - Path to file or directory
+ * @returns FileEntry with file information
+ */
+export async function getFileInfo(filePath) {
+    const stats = await stat(filePath);
+    const name = filePath.split('/').pop() || filePath;
+    return {
+        name,
+        path: filePath,
+        isDirectory: stats.isDirectory(),
+        size: stats.isFile() ? stats.size : undefined,
+        isHidden: name.startsWith('.'),
+    };
+}
+/**
+ * Format bytes to human-readable file size
+ * @param bytes - Size in bytes
+ * @returns Formatted string like "1.5 MB", "500 KB", etc.
+ */
+export function formatFileSize(bytes) {
+    if (bytes === 0)
+        return '0 B';
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    const k = 1024;
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    // Limit to 2 decimal places and remove trailing zeros
+    const value = parseFloat((bytes / Math.pow(k, i)).toFixed(2));
+    return `${value} ${units[i]}`;
+}

package/dist/utils/network.js

@@ -0,0 +1,98 @@
+import Hyperswarm from 'hyperswarm';
+import { appendFileSync } from 'node:fs';
+const CONNECTION_TIMEOUT = 30000; // 30 seconds
+const LOG_FILE = '/tmp/ezshare_debug.log';
+function debugLog(message) {
+    const timestamp = new Date().toISOString();
+    const logLine = `[${timestamp}] ${message}\n`;
+    try {
+        appendFileSync(LOG_FILE, logLine);
+    }
+    catch (e) {
+        // Ignore file write errors
+    }
+    console.error(message); // Use stderr to avoid Ink interference
+}
+/**
+ * Create a sender swarm that announces to the DHT and waits for a peer connection
+ * @param topic - The topic buffer to join (32 bytes)
+ * @returns Swarm instance and a function to wait for the first peer connection
+ */
+export async function createSenderSwarm(topic) {
+    const swarm = new Hyperswarm();
+    debugLog('[Sender] Creating sender swarm...');
+    debugLog('[Sender] Topic hash: ' + topic.toString('hex'));
+    debugLog('[Sender] Topic base64url: ' + topic.toString('base64url'));
+    // Enable both server and client for better NAT traversal
+    const discovery = swarm.join(topic, { server: true, client: true });
+    debugLog('[Sender] Announcing to DHT...');
+    // Wait for the topic to be fully announced to the DHT
+    await discovery.flushed();
+    debugLog('[Sender] DHT announcement complete, waiting for peer...');
+    // Create a promise that resolves when a peer connects
+    const waitForPeer = () => {
+        return new Promise((resolve, reject) => {
+            // Set timeout for connection
+            const timeout = setTimeout(() => {
+                reject(new Error(`Connection timeout after ${CONNECTION_TIMEOUT / 1000}s. ` +
+                    'Peer may not be online or DHT discovery failed. ' +
+                    'Ensure both peers are started within a few seconds of each other.'));
+            }, CONNECTION_TIMEOUT);
+            swarm.once('connection', (socket) => {
+                clearTimeout(timeout);
+                debugLog('[Sender] Peer connected!');
+                resolve(socket);
+            });
+            // Debug: log peer discovery
+            swarm.on('peer-add', () => {
+                debugLog('[Sender] Peer discovered via DHT');
+            });
+        });
+    };
+    return { swarm, waitForPeer };
+}
+/**
+ * Create a receiver swarm that connects to a sender
+ * @param topic - The topic buffer to join (32 bytes)
+ * @returns Swarm instance and a function to wait for the first peer connection
+ */
+export async function createReceiverSwarm(topic) {
+    const swarm = new Hyperswarm();
+    debugLog('[Receiver] Creating receiver swarm...');
+    debugLog('[Receiver] Topic hash: ' + topic.toString('hex'));
+    debugLog('[Receiver] Topic base64url: ' + topic.toString('base64url'));
+    // CRITICAL: Register connection listener BEFORE joining/flushing
+    // Otherwise we miss the connection event in the race condition
+    const connectionPromise = new Promise((resolve, reject) => {
+        // Set timeout for connection
+        const timeout = setTimeout(() => {
+            reject(new Error(`Connection timeout after ${CONNECTION_TIMEOUT / 1000}s. ` +
+                'Could not find or connect to sender. ' +
+                'Ensure sender is running and you entered the correct share key.'));
+        }, CONNECTION_TIMEOUT);
+        swarm.once('connection', (socket) => {
+            clearTimeout(timeout);
+            debugLog('[Receiver] Connected to peer!');
+            resolve(socket);
+        });
+        // Debug: log peer discovery
+        swarm.on('peer-add', () => {
+            debugLog('[Receiver] Peer discovered via DHT, connecting...');
+        });
+    });
+    // Enable both server and client for better NAT traversal
+    swarm.join(topic, { server: true, client: true });
+    debugLog('[Receiver] Looking up peers in DHT...');
+    // Flush the swarm to start connecting
+    await swarm.flush();
+    debugLog('[Receiver] DHT lookup complete, waiting for connection...');
+    return { swarm, connectionPromise };
+}
+/**
+ * Clean up and destroy a swarm instance
+ * @param swarm - The Hyperswarm instance to clean up
+ */
+export async function cleanupSwarm(swarm) {
+    // Destroy the swarm and close all connections
+    await swarm.destroy();
+}

package/dist/utils/tar.js

@@ -0,0 +1,169 @@
+import { createReadStream, createWriteStream } from 'node:fs';
+import { readdir, stat, mkdir } from 'node:fs/promises';
+import { join, dirname, relative } from 'node:path';
+import tarStream from 'tar-stream';
+/**
+ * Get metadata about the transfer source (file or directory)
+ * @param sourcePath - Path to file or directory
+ * @returns Metadata including total size, file count, and whether it's a directory
+ */
+export async function getTransferMetadata(sourcePath) {
+    const stats = await stat(sourcePath);
+    if (!stats.isDirectory()) {
+        // Single file
+        return {
+            totalSize: stats.size,
+            fileCount: 1,
+            isDirectory: false,
+        };
+    }
+    // Directory - walk recursively to count files and total size
+    let totalSize = 0;
+    let fileCount = 0;
+    async function walk(currentPath) {
+        const entries = await readdir(currentPath, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = join(currentPath, entry.name);
+            if (entry.isDirectory()) {
+                await walk(fullPath);
+            }
+            else if (entry.isFile()) {
+                const fileStats = await stat(fullPath);
+                totalSize += fileStats.size;
+                fileCount++;
+            }
+        }
+    }
+    await walk(sourcePath);
+    return {
+        totalSize,
+        fileCount,
+        isDirectory: true,
+    };
+}
+/**
+ * Create a readable stream that packs a file or directory into tar format
+ * @param sourcePath - Path to file or directory to pack
+ * @returns Readable stream of tar data
+ */
+export function createPackStream(sourcePath) {
+    const pack = tarStream.pack();
+    // Start packing asynchronously
+    (async () => {
+        try {
+            const stats = await stat(sourcePath);
+            if (!stats.isDirectory()) {
+                // Single file - add it directly
+                const relativeName = sourcePath.split('/').pop() || 'file';
+                const fileStream = createReadStream(sourcePath);
+                const entry = pack.entry({
+                    name: relativeName,
+                    size: stats.size,
+                    mode: stats.mode,
+                    mtime: stats.mtime,
+                });
+                fileStream.pipe(entry);
+                await new Promise((resolve, reject) => {
+                    entry.on('finish', resolve);
+                    entry.on('error', reject);
+                    fileStream.on('error', reject);
+                });
+                pack.finalize();
+                return;
+            }
+            // Directory - walk recursively and add all files and directories
+            async function addDirectory(currentPath, basePath) {
+                const entries = await readdir(currentPath, { withFileTypes: true });
+                for (const entry of entries) {
+                    const fullPath = join(currentPath, entry.name);
+                    const relativePath = relative(basePath, fullPath);
+                    if (entry.isDirectory()) {
+                        // Add directory entry
+                        const dirStats = await stat(fullPath);
+                        await new Promise((resolve, reject) => {
+                            pack.entry({
+                                name: relativePath + '/',
+                                type: 'directory',
+                                mode: dirStats.mode,
+                                mtime: dirStats.mtime,
+                            }, (err) => {
+                                if (err)
+                                    reject(err);
+                                else
+                                    resolve();
+                            });
+                        });
+                        // Recursively add subdirectory contents
+                        await addDirectory(fullPath, basePath);
+                    }
+                    else if (entry.isFile()) {
+                        // Add file entry
+                        const fileStats = await stat(fullPath);
+                        const fileStream = createReadStream(fullPath);
+                        const tarEntry = pack.entry({
+                            name: relativePath,
+                            size: fileStats.size,
+                            mode: fileStats.mode,
+                            mtime: fileStats.mtime,
+                        });
+                        fileStream.pipe(tarEntry);
+                        await new Promise((resolve, reject) => {
+                            tarEntry.on('finish', resolve);
+                            tarEntry.on('error', reject);
+                            fileStream.on('error', reject);
+                        });
+                    }
+                }
+            }
+            await addDirectory(sourcePath, dirname(sourcePath));
+            pack.finalize();
+        }
+        catch (error) {
+            pack.destroy(error);
+        }
+    })();
+    return pack;
+}
+/**
+ * Create a writable stream that extracts tar data to a destination directory
+ * @param destPath - Destination directory for extracted files
+ * @returns Writable stream that accepts tar data
+ */
+export function createExtractStream(destPath) {
+    const extract = tarStream.extract();
+    extract.on('entry', (header, stream, next) => {
+        const outputPath = join(destPath, header.name);
+        // Ensure parent directory exists
+        (async () => {
+            try {
+                const parentDir = dirname(outputPath);
+                await mkdir(parentDir, { recursive: true });
+                if (header.type === 'file') {
+                    // Write file
+                    const writeStream = createWriteStream(outputPath, {
+                        mode: header.mode,
+                    });
+                    stream.pipe(writeStream);
+                    await new Promise((resolve, reject) => {
+                        writeStream.on('finish', resolve);
+                        writeStream.on('error', reject);
+                        stream.on('error', reject);
+                    });
+                }
+                else if (header.type === 'directory') {
+                    // Create directory
+                    await mkdir(outputPath, { recursive: true, mode: header.mode });
+                    stream.resume(); // Drain the stream
+                }
+                else {
+                    stream.resume(); // Skip unsupported types
+                }
+                next();
+            }
+            catch (error) {
+                next(error);
+            }
+        })();
+    });
+    return extract;
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "ezshare-cli",
+  "version": "1.0.0",
+  "description": "Secure P2P file transfer CLI with end-to-end encryption - No servers, no signups, just share",
+  "type": "module",
+  "bin": {
+    "ezshare": "bin/ezshare.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.tsx",
+    "test": "tsx --test src/**/*.test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "p2p",
+    "file-transfer",
+    "file-sharing",
+    "hyperswarm",
+    "cli",
+    "decentralized",
+    "encrypted",
+    "dht",
+    "peer-to-peer",
+    "secure-transfer",
+    "no-server"
+  ],
+  "author": "Blake",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yulchanshin/ezsharecli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yulchanshin/ezsharecli/issues"
+  },
+  "homepage": "https://github.com/yulchanshin/ezsharecli#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@inkjs/ui": "^2.0.0",
+    "hyperswarm": "^4.16.0",
+    "ink": "^6.6.0",
+    "meow": "^14.0.0",
+    "pump": "^3.0.3",
+    "simple-zstd": "^2.0.0",
+    "tar-stream": "^3.1.7"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.5",
+    "@types/react": "^19.2.7",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}