pal-explorer-cli 0.4.11 → 0.4.13

package/lib/commands/remote.js

@@ -1,368 +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;
-}
+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 pal 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:
+  $ pal remote browse @alice                   List Alice's shares
+  $ pal remote browse @alice --device laptop   List shares from specific device
+  $ pal remote files @alice "Photos"           List files in Alice's "Photos" share
+  $ pal remote download @alice "Photos"        Download Alice's "Photos" share
+  $ pal 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 \`pal 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 \`pal 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 `pal serve` to start seeding and generate magnet links.'));
+          console.log(chalk.gray('  Once seeded, retry: pal 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 `pal 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;
+}