pal-explorer-cli 0.4.0

package/lib/commands/register.js

@@ -0,0 +1,171 @@
+import chalk from 'chalk';
+import config from '../utils/config.js';
+import { setIdentityHandle, getIdentity } from '../core/identity.js';
+import { getPrimaryServer, postTo, parseHandle } from '../core/discoveryClient.js';
+import { updateProfileHandle } from '../core/users.js';
+
+export default function registerCommand(program) {
+  program
+    .command('register <handle>')
+    .description('register your identity with a handle on the discovery network')
+    .option('--email <email>', 'Verify ownership via email OTP (required for first registration)')
+    .option('--server <url>', 'Register on a specific discovery server')
+    .addHelpText('after', `
+Examples:
+  $ pe register alice               Register handle @alice (direct signature)
+  $ pe register alice --email a@b   Register with email OTP verification
+  $ pe register alice --server https://custom.com   Register on specific server
+`)
+    .action(async (handle, opts) => {
+      handle = handle.replace(/^@/, '');
+      const identity = await getIdentity();
+      if (!identity) {
+        console.log(chalk.red('No identity found. Run `pe init <name>` first.'));
+        process.exitCode = 1; return;
+      }
+
+      if (!/^[a-zA-Z0-9_-]{3,32}$/.test(handle)) {
+        console.log(chalk.red('Handle must be 3-32 characters: letters, numbers, hyphens, underscores only.'));
+        process.exitCode = 1; return;
+      }
+
+      const serverUrl = opts.server || getPrimaryServer();
+
+      if (opts.email) {
+        // OTP flow: request OTP sent to email
+        console.log(chalk.blue(`Sending OTP to ${opts.email}...`));
+        try {
+          const res = await postTo(serverUrl, '/otp/send', { handle, publicKey: identity.publicKey });
+          const data = await res.json();
+          if (!res.ok) {
+            console.log(chalk.red(`Failed: ${data.error}`));
+            process.exitCode = 1; return;
+          }
+          console.log(chalk.green('OTP sent. Run `pe verify <code>` with the code from your email.'));
+          config.set('_pendingRegistration', { handle, publicKey: identity.publicKey, email: opts.email, serverUrl });
+        } catch {
+          console.log(chalk.red(`Could not reach discovery server at ${serverUrl}`));
+          process.exitCode = 1;
+        }
+        return;
+      }
+
+      // Challenge-response registration
+      const sodium = (await import('sodium-native')).default;
+      const privateKey = Buffer.from(identity.privateKey, 'hex');
+
+      try {
+        process.stdout.write(chalk.gray(`Registering @${handle} on ${serverUrl}... `));
+
+        // Step 1: Request challenge from server
+        const challengeRes = await postTo(serverUrl, '/register/challenge', { handle, publicKey: identity.publicKey });
+        const challengeData = await challengeRes.json();
+        if (!challengeRes.ok || !challengeData.challengeId) {
+          console.log(chalk.red(`\nFailed: ${challengeData.error || 'Could not get challenge'}`));
+          if (challengeData.suggestions?.length > 0) {
+            console.log(chalk.yellow('Available alternatives:'));
+            for (const s of challengeData.suggestions) {
+              console.log(chalk.white(`  @${s}`));
+            }
+          }
+          process.exitCode = 1; return;
+        }
+
+        // Step 2: Sign challenge and complete registration
+        const message = `register:${handle}:${challengeData.nonce}`;
+        const sig = Buffer.alloc(sodium.crypto_sign_BYTES);
+        sodium.crypto_sign_detached(sig, Buffer.from(message), privateKey);
+
+        const res = await postTo(serverUrl, '/register', { challengeId: challengeData.challengeId, signature: sig.toString('hex') });
+        const result = await res.json();
+        if (res.status === 403 && result.code === 'VANITY_HANDLE_PRO_REQUIRED') {
+          console.log(chalk.red(`\nVanity handle "@${handle}" requires Pro.`));
+          console.log(chalk.yellow('Short custom handles (3-15 chars) are a Pro feature.'));
+          console.log(chalk.gray('Upgrade: pe billing upgrade'));
+          console.log(chalk.gray('Or use an auto-generated handle instead.'));
+          process.exitCode = 1; return;
+        }
+        if (result.success) {
+          console.log(chalk.green('done.'));
+          // Store full federated handle if registered on non-primary server
+          const primary = getPrimaryServer();
+          const fullHandle = (opts.server && opts.server !== primary)
+            ? `${handle}@${serverUrl.replace(/^https?:\/\//, '')}`
+            : handle;
+          console.log(chalk.green(`Registered as @${fullHandle}`));
+          setIdentityHandle(fullHandle);
+          updateProfileHandle(identity.publicKey, fullHandle);
+          config.delete('_pendingRegistration');
+
+          // Publish to DHT for decentralized fallback
+          try {
+            const { DHTDiscovery } = await import('../core/dhtDiscovery.js');
+            const dht = new DHTDiscovery();
+            const dhtHash = await dht.publish(handle, identity.publicKey, identity.privateKey);
+            const cache = config.get('handleCache') || {};
+            if (!cache[handle]) cache[handle] = {};
+            cache[handle].dhtHash = dhtHash;
+            config.set('handleCache', cache);
+            console.log(chalk.gray(`Published to DHT (hash: ${dhtHash.slice(0, 12)}...)`));
+            dht.destroy();
+          } catch (err) {
+            console.log(chalk.yellow(`DHT publish skipped: ${err.message}`));
+          }
+        } else {
+          console.log(chalk.red(`\nFailed: ${result.error}`));
+          process.exitCode = 1;
+        }
+      } catch {
+        console.log(chalk.red(`\nCould not reach discovery server at ${serverUrl}`));
+        process.exitCode = 1;
+      }
+    });
+
+  program
+    .command('verify <code>')
+    .description('complete OTP email verification for handle registration')
+    .addHelpText('after', `
+Examples:
+  $ pe verify 123456                Complete OTP verification
+`)
+    .action(async (code) => {
+      const pending = config.get('_pendingRegistration');
+      if (!pending?.handle) {
+        console.log(chalk.red('No pending registration. Run `pe register <handle> --email <email>` first.'));
+        process.exitCode = 1; return;
+      }
+
+      const identity = await getIdentity();
+      if (!identity?.privateKey) {
+        console.log(chalk.red('No identity found.'));
+        process.exitCode = 1; return;
+      }
+
+      const serverUrl = pending.serverUrl || getPrimaryServer();
+      const sodium = (await import('sodium-native')).default;
+      const privateKey = Buffer.from(identity.privateKey, 'hex');
+      const now = Date.now();
+      const message = `${pending.handle}:${code}:${now}`;
+      const sig = Buffer.alloc(sodium.crypto_sign_BYTES);
+      sodium.crypto_sign_detached(sig, Buffer.from(message), privateKey);
+
+      try {
+        process.stdout.write(chalk.gray(`Verifying @${pending.handle}... `));
+        const res = await postTo(serverUrl, '/otp/verify', { handle: pending.handle, code, signature: sig.toString('hex'), timestamp: now });
+        const result = await res.json();
+        if (result.success) {
+          console.log(chalk.green('done.'));
+          console.log(chalk.green(`Handle @${pending.handle} verified and registered.`));
+          setIdentityHandle(pending.handle);
+          updateProfileHandle(identity.publicKey, pending.handle);
+          config.delete('_pendingRegistration');
+        } else {
+          console.log(chalk.red(`\nVerification failed: ${result.error}`));
+          process.exitCode = 1;
+        }
+      } catch {
+        console.log(chalk.red(`\nCould not reach discovery server at ${serverUrl}`));
+        process.exitCode = 1;
+      }
+    });
+}

package/lib/commands/relay.js

@@ -0,0 +1,131 @@
+import chalk from 'chalk';
+import crypto from 'crypto';
+
+export default function relayCommand(program) {
+  const cmd = program
+    .command('relay')
+    .description('manage the TURN relay server extension')
+    .addHelpText('after', `
+Examples:
+  $ pe relay start                   Start the relay server
+  $ pe relay stop                    Stop the relay server
+  $ pe relay status                  Show relay status
+  $ pe relay credentials             Generate TURN credentials (default 1h TTL)
+  $ pe relay credentials 3600       Generate credentials with custom TTL (seconds)
+`)
+    .action(() => {
+      cmd.outputHelp();
+    });
+
+  cmd
+    .command('start')
+    .description('start the TURN relay server')
+    .action(async () => {
+      try {
+        const extConfig = (await import('../utils/config.js')).default;
+        const cfg = extConfig.get('ext.relay') || {};
+
+        if (!cfg.secret) {
+          cfg.secret = crypto.randomBytes(32).toString('hex');
+          extConfig.set('ext.relay', { ...cfg });
+        }
+
+        const port = cfg.port || 3478;
+        const realm = cfg.realm || 'palexplorer';
+
+        const store = extConfig.get('ext_store.relay') || {};
+        store.running = true;
+        store.activeAllocations = store.activeAllocations || {};
+        extConfig.set('ext_store.relay', store);
+
+        console.log(chalk.green(`✔ Relay server started`));
+        console.log(`  Port:  ${chalk.white(port)}`);
+        console.log(`  Realm: ${chalk.white(realm)}`);
+      } catch (err) {
+        console.log(chalk.red(`Failed to start relay: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  cmd
+    .command('stop')
+    .description('stop the TURN relay server')
+    .action(async () => {
+      try {
+        const extConfig = (await import('../utils/config.js')).default;
+        const store = extConfig.get('ext_store.relay') || {};
+        store.running = false;
+        store.activeAllocations = {};
+        extConfig.set('ext_store.relay', store);
+
+        console.log(chalk.green(`✔ Relay server stopped`));
+      } catch (err) {
+        console.log(chalk.red(`Failed to stop relay: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  cmd
+    .command('status')
+    .description('show relay server status')
+    .action(async () => {
+      try {
+        const extConfig = (await import('../utils/config.js')).default;
+        const cfg = extConfig.get('ext.relay') || {};
+        const store = extConfig.get('ext_store.relay') || {};
+
+        const running = store.running || false;
+        const port = cfg.port || 3478;
+        const realm = cfg.realm || 'palexplorer';
+        const maxBandwidth = cfg.maxBandwidth || 'unlimited';
+        const allocations = Object.keys(store.activeAllocations || {}).length;
+
+        console.log('');
+        console.log(chalk.cyan.bold('TURN Relay Status'));
+        console.log(`  Status:      ${running ? chalk.green('running') : chalk.red('stopped')}`);
+        console.log(`  Port:        ${chalk.white(port)}`);
+        console.log(`  Realm:       ${chalk.white(realm)}`);
+        console.log(`  Bandwidth:   ${chalk.white(maxBandwidth)}`);
+        console.log(`  Allocations: ${chalk.white(allocations)}`);
+        console.log(`  Secret:      ${cfg.secret ? chalk.gray(cfg.secret.slice(0, 8) + '...') : chalk.yellow('not set')}`);
+        console.log('');
+      } catch (err) {
+        console.log(chalk.red(`Failed to get status: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  cmd
+    .command('credentials [ttl]')
+    .description('generate TURN credentials (HMAC-SHA1 based)')
+    .action(async (ttl) => {
+      try {
+        const extConfig = (await import('../utils/config.js')).default;
+        const cfg = extConfig.get('ext.relay') || {};
+
+        if (!cfg.secret) {
+          cfg.secret = crypto.randomBytes(32).toString('hex');
+          extConfig.set('ext.relay', { ...cfg });
+        }
+
+        const credentialTTL = parseInt(ttl, 10) || cfg.credentialTTL || 3600;
+        const timestamp = Math.floor(Date.now() / 1000) + credentialTTL;
+        const username = `${timestamp}:palexplorer`;
+        const password = crypto
+          .createHmac('sha1', cfg.secret)
+          .update(username)
+          .digest('base64');
+
+        console.log('');
+        console.log(chalk.cyan.bold('TURN Credentials'));
+        console.log(`  Username: ${chalk.white(username)}`);
+        console.log(`  Password: ${chalk.white(password)}`);
+        console.log(`  TTL:      ${chalk.white(credentialTTL + 's')}`);
+        console.log(`  Expires:  ${chalk.gray(new Date(timestamp * 1000).toISOString())}`);
+        console.log('');
+      } catch (err) {
+        console.log(chalk.red(`Failed to generate credentials: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+}

package/lib/commands/remote.js

@@ -0,0 +1,368 @@
+import chalk from 'chalk';
+import path from 'path';
+import fs from 'fs';
+import { requireIdentity, auditLog } from '../core/permissions.js';
+import { getFriends } from '../core/users.js';
+import { formatSize } from '../utils/format.js';
+import { printJson, parseCommaList } from '../utils/cli.js';
+import { getTorrentMetadata, destroyClient, TORRENT_TIMEOUT_LONG } from '../utils/torrent.js';
+import { sendRequest, sendAuthenticatedRequest } from '../core/signalingServer.js';
+import { getNearbyPeers, getCachedPeerAddress } from '../core/mdnsService.js';
+import { getIdentity } from '../core/identity.js';
+
+// Verify a cached address is still alive via quick TCP probe
+async function verifyPeerAlive(ip, port = 7474) {
+  try {
+    const r = await sendRequest(ip, port, { type: 'status' }, 3000);
+    return r.ok && r.protocol === 'PAL/1.0';
+  } catch { return false; }
+}
+
+// Resolve a pal's IP and signaling port via mDNS (LAN) or discovery server (device registration)
+async function resolvePeerAddress(pal) {
+  // Strategy 1: mDNS — check if peer is on LAN (only works when pe serve is running in same process)
+  const nearby = getNearbyPeers();
+  const mdnsPeer = nearby.find(p =>
+    p.publicKey === pal.publicKey || p.publicKey === pal.id ||
+    p.handle === pal.handle || p.name === pal.name
+  );
+  if (mdnsPeer && mdnsPeer.ip && mdnsPeer.ip !== 'unknown') {
+    return { ip: mdnsPeer.ip, port: 7474, source: 'mDNS' };
+  }
+
+  // Strategy 2: Cached peer address (persisted from previous mDNS/discovery)
+  // MEDIUM-3 fix: only look up by public key identifiers
+  const cached = getCachedPeerAddress([pal.publicKey, pal.id]);
+  if (cached && cached.ip) {
+    const alive = await verifyPeerAlive(cached.ip, cached.port || 7474);
+    if (alive) {
+      return { ip: cached.ip, port: cached.port || 7474, source: 'cache' };
+    }
+  }
+
+  // Strategy 3: Discovery server — get device IP (NOT share lists)
+  const handle = pal.handle || pal.name;
+  if (handle) {
+    try {
+      const { getPrimaryServer } = await import('../core/discoveryClient.js');
+      const serverUrl = getPrimaryServer();
+      const devicesRes = await fetch(`${serverUrl}/devices/${encodeURIComponent(handle)}`, {
+        signal: AbortSignal.timeout(5000)
+      });
+      if (devicesRes.ok) {
+        const { devices = [] } = await devicesRes.json();
+        for (const device of devices) {
+          if (device.ip) {
+            return { ip: device.ip, port: 7474, source: 'discovery', device };
+          }
+          if (device.serveUrl) {
+            try {
+              const url = new URL(device.serveUrl);
+              return { ip: url.hostname, port: 7474, source: 'discovery', device };
+            } catch {}
+          }
+        }
+      }
+    } catch {}
+  }
+
+  // Strategy 4: Check if pal has a known IP in their friend record
+  if (pal.ip) {
+    return { ip: pal.ip, port: 7474, source: 'friend-record' };
+  }
+
+  return null;
+}
+
+// Query a peer's share list via TCP signaling (PAL/1.0) with authentication
+async function queryPeerShares(ip, port = 7474, timeout = 5000) {
+  // Try authenticated request first for full share list access
+  try {
+    const identity = await getIdentity();
+    if (identity?.privateKey && identity?.publicKey) {
+      const response = await sendAuthenticatedRequest(
+        ip, port, { type: 'share_list' }, identity.privateKey, identity.publicKey, timeout
+      );
+      if (response.ok) return response;
+    }
+  } catch {}
+
+  // Fallback to unauthenticated (will only see public shares)
+  const response = await sendRequest(ip, port, { type: 'share_list' }, timeout);
+  if (!response.ok) {
+    throw new Error(response.error || 'Peer refused share list request');
+  }
+  return response;
+}
+
+export default function remoteCommand(program) {
+  const remote = program
+    .command('remote')
+    .description('browse and download from pals\' shares')
+    .addHelpText('after', `
+Examples:
+  $ pe remote browse @alice                   List Alice's shares
+  $ pe remote browse @alice --device laptop   List shares from specific device
+  $ pe remote files @alice "Photos"           List files in Alice's "Photos" share
+  $ pe remote download @alice "Photos"        Download Alice's "Photos" share
+  $ pe remote download @alice "Photos" --files "pic1.jpg,pic2.jpg"
+`);
+
+  // ── browse ──────────────────────────────────────────────────────────────
+  remote
+    .command('browse <handle>')
+    .description('list shares from a pal')
+    .option('--device <deviceName>', 'Filter by device name')
+    .option('--json', 'Output as JSON')
+    .action(async (handle, opts) => {
+      try {
+        requireIdentity();
+        handle = handle.replace(/^@/, '');
+
+        const friends = getFriends();
+        const pal = friends.find(f => f.handle === handle || f.name === handle || f.id === handle || f.publicKey === handle);
+        if (!pal) {
+          console.error(chalk.red(`@${handle} is not in your pals. Run \`pe pal add\` first.`));
+          process.exitCode = 1;
+          return;
+        }
+
+        console.log(chalk.dim(`Looking for @${handle}...`));
+        const addr = await resolvePeerAddress(pal);
+        if (!addr) {
+          console.log(chalk.yellow(`Could not find @${handle}. The pal might be offline.`));
+          console.log(chalk.dim(`  Tried: mDNS (LAN), discovery server (device lookup)`));
+          process.exitCode = 1;
+          return;
+        }
+
+        console.log(chalk.dim(`Found @${handle} via ${addr.source} (${addr.ip}:${addr.port})`));
+
+        let peerData;
+        try {
+          peerData = await queryPeerShares(addr.ip, addr.port);
+        } catch (err) {
+          console.log(chalk.yellow(`Could not connect to @${handle} at ${addr.ip}:${addr.port}`));
+          console.log(chalk.dim(`  Error: ${err.message}`));
+          console.log(chalk.dim(`  The pal might not be running \`pe serve\``));
+          process.exitCode = 1;
+          return;
+        }
+
+        const allShares = (peerData.shares || []).map(s => ({
+          ...s,
+          device: peerData.deviceName,
+          deviceId: peerData.deviceId,
+        }));
+
+        if (opts.device) {
+          const filtered = allShares.filter(s => s.device === opts.device);
+          if (filtered.length === 0) {
+            console.log(chalk.dim(`No shares from device "${opts.device}".`));
+            return;
+          }
+        }
+
+        if (opts.json || program.opts().json) { printJson(allShares); return; }
+
+        if (allShares.length === 0) {
+          console.log(chalk.dim(`No shares available from @${handle}.`));
+          return;
+        }
+
+        console.log(chalk.bold(`\n  Shares from @${chalk.cyan(handle)}:\n`));
+        for (const share of allShares) {
+          const vis = share.visibility === 'private' ? chalk.yellow('private') : chalk.green('public');
+          const dev = chalk.dim(`[${share.device}]`);
+          console.log(`  ${chalk.bold(share.name)}  ${vis}  ${dev}`);
+          if (share.magnet) console.log(chalk.dim(`    ${share.magnet.slice(0, 60)}...`));
+        }
+        console.log(chalk.dim(`\n  ${allShares.length} share${allShares.length !== 1 ? 's' : ''} total\n`));
+
+        auditLog('remote.browse', { handle, shareCount: allShares.length });
+      } catch (err) {
+        console.error(chalk.red(err.message));
+        process.exitCode = 1;
+      }
+    });
+
+  // ── files ───────────────────────────────────────────────────────────────
+  remote
+    .command('files <handle> <shareName>')
+    .description('list files in a remote share')
+    .option('--depth <n>', 'Recursive depth for folder listing (1-5, default: 2)', parseInt)
+    .option('--json', 'Output as JSON')
+    .action(async (handle, shareName, opts) => {
+      try {
+        requireIdentity();
+        handle = handle.replace(/^@/, '');
+
+        const share = await findShareFromPeer(handle, shareName);
+        if (!share) {
+          console.error(chalk.red(`Share "${shareName}" not found from @${handle}.`));
+          process.exitCode = 1;
+          return;
+        }
+
+        if (!share.magnet) {
+          console.error(chalk.red('Share not seeded yet. The pal needs to run `pe serve` to start seeding and generate magnet links.'));
+          console.log(chalk.gray('  Once seeded, retry: pe remote files @' + handle + ' "' + shareName + '"'));
+          process.exitCode = 1;
+          return;
+        }
+
+        // Fast path: get file list directly from peer via TCP signaling
+        let files;
+        if (share.peerIp) {
+          try {
+            console.log(chalk.dim('Querying file list from peer...'));
+            const fileResp = await sendRequest(share.peerIp, 7474, {
+              type: 'share_files', shareId: share.id
+            }, 5000);
+            if (fileResp.ok && fileResp.files?.length > 0) {
+              files = fileResp.files;
+            }
+          } catch { /* fall through to BitTorrent */ }
+        }
+
+        // Fallback: get file list from BitTorrent metadata
+        if (!files) {
+          const directPeers = share.peerIp && share.peerTorrentPort
+            ? [{ ip: share.peerIp, torrentPort: share.peerTorrentPort }] : [];
+          console.log(chalk.dim('Connecting to swarm to get file list...'));
+          let torrent, client;
+          try {
+            ({ torrent, client } = await getTorrentMetadata(share.magnet, { lanPeers: directPeers }));
+            files = torrent.files.map(f => ({ name: f.name, path: f.path, size: f.length }));
+            torrent.destroy();
+            await destroyClient(client);
+          } catch (err) {
+            console.error(chalk.red(`Failed to get file list: ${err.message}`));
+            process.exitCode = 1;
+            return;
+          }
+        }
+
+        if (opts.json || program.opts().json) { printJson(files); return; }
+
+        console.log(chalk.bold(`\n  Files in "${shareName}" from @${chalk.cyan(handle)}:\n`));
+        for (const f of files) {
+          const type = f.isDir ? chalk.blue('DIR ') : chalk.gray('FILE');
+          const indent = '  '.repeat(((f.path || f.name).split('/').length - 1));
+          console.log(`  ${indent}${type}  ${f.path || f.name}  ${chalk.dim(formatSize(f.size || 0))}`);
+        }
+        console.log(chalk.dim(`\n  ${files.length} file${files.length !== 1 ? 's' : ''}\n`));
+
+        auditLog('remote.files', { handle, shareName, fileCount: files.length });
+      } catch (err) {
+        console.error(chalk.red(err.message));
+        process.exitCode = 1;
+      }
+    });
+
+  // ── download ────────────────────────────────────────────────────────────
+  remote
+    .command('download <handle> <shareName>')
+    .description('download a share from a pal')
+    .option('-o, --output <dir>', 'Output directory', '.')
+    .option('--files <files>', 'Comma-separated file names to download (selective)')
+    .option('--json', 'Output as JSON')
+    .action(async (handle, shareName, opts) => {
+      try {
+        requireIdentity();
+        handle = handle.replace(/^@/, '');
+
+        const share = await findShareFromPeer(handle, shareName);
+        if (!share) {
+          console.error(chalk.red(`Share "${shareName}" not found from @${handle}.`));
+          process.exitCode = 1;
+          return;
+        }
+
+        if (!share.magnet) {
+          console.error(chalk.red('Share has no magnet link — the pal needs to run `pe serve` to generate magnets.'));
+          process.exitCode = 1;
+          return;
+        }
+
+        const outputDir = path.resolve(opts.output);
+        fs.mkdirSync(outputDir, { recursive: true });
+
+        const selectedFiles = parseCommaList(opts.files).length > 0 ? parseCommaList(opts.files) : null;
+
+        // P2P download via WebTorrent (BitTorrent swarm) — inject direct peer for fast discovery
+        const directPeers = share.peerIp && share.peerTorrentPort
+          ? [{ ip: share.peerIp, torrentPort: share.peerTorrentPort }] : [];
+        if (directPeers.length) console.log(chalk.dim(`Direct peer: ${share.peerIp}:${share.peerTorrentPort}`));
+        console.log(chalk.dim('Connecting to swarm and downloading...'));
+        const { torrent, client } = await getTorrentMetadata(share.magnet, { path: outputDir, timeout: TORRENT_TIMEOUT_LONG, lanPeers: directPeers });
+
+        if (selectedFiles) {
+          for (const file of torrent.files) {
+            if (!selectedFiles.some(sf => file.name === sf || file.path.includes(sf))) {
+              file.deselect();
+            }
+          }
+        }
+
+        await new Promise((resolve) => {
+          torrent.on('done', resolve);
+          const interval = setInterval(() => {
+            const pct = (torrent.progress * 100).toFixed(1);
+            const speed = (torrent.downloadSpeed / 1048576).toFixed(1);
+            process.stdout.write(`\r  ${chalk.cyan(pct + '%')}  ${chalk.dim(speed + ' MB/s')}  ${chalk.dim(torrent.numPeers + ' peers')}`);
+          }, 500);
+          torrent.on('done', () => { clearInterval(interval); process.stdout.write('\n'); });
+        });
+
+        const downloaded = torrent.files
+          .filter(f => !selectedFiles || selectedFiles.some(sf => f.name === sf || f.path.includes(sf)))
+          .map(f => ({ name: f.name, path: f.path, size: f.length }));
+
+        torrent.destroy();
+        await destroyClient(client);
+
+        if (opts.json || program.opts().json) { printJson({ success: true, files: downloaded, outputDir }); return; }
+
+        console.log(chalk.green(`\n  Downloaded ${downloaded.length} file${downloaded.length !== 1 ? 's' : ''} to ${outputDir}\n`));
+        for (const f of downloaded) {
+          console.log(`  ${chalk.gray('✓')} ${f.path} ${chalk.dim(`(${formatSize(f.size)})`)}`);
+        }
+        console.log();
+
+        auditLog('remote.download', { handle, shareName, fileCount: downloaded.length, outputDir });
+      } catch (err) {
+        console.error(chalk.red(err.message));
+        process.exitCode = 1;
+      }
+    });
+}
+
+// Find a specific share from a peer via P2P signaling
+async function findShareFromPeer(handle, shareName) {
+  const friends = getFriends();
+  const pal = friends.find(f => f.handle === handle || f.name === handle || f.id === handle || f.publicKey === handle);
+  if (!pal) return null;
+
+  const addr = await resolvePeerAddress(pal);
+  if (!addr) return null;
+
+  try {
+    const peerData = await queryPeerShares(addr.ip, addr.port);
+    const match = (peerData.shares || []).find(s => s.name === shareName);
+    if (match) {
+      // HIGH-2 fix: only trust torrentPort from authenticated responses
+      // (queryPeerShares already attempts auth — torrentPort is only present
+      // in authenticated friend responses from the server)
+      return {
+        ...match,
+        device: peerData.deviceName,
+        deviceId: peerData.deviceId,
+        peerIp: addr.ip,
+        peerTorrentPort: peerData.torrentPort || null,
+      };
+    }
+  } catch {}
+
+  return null;
+}