pal-explorer-cli 0.4.12 → 0.4.13

package/lib/commands/protocol.js

@@ -1,357 +1,357 @@
-import chalk from 'chalk';
-import { getIdentity } from '../core/identity.js';
-import { listShares, getShareKey } from '../core/shares.js';
-import { getSharePolicy, setSharePolicy, listPolicies } from '../core/sharePolicy.js';
-import { getFriends } from '../core/users.js';
-import config from '../utils/config.js';
-
-export default function protocolCommand(program) {
-  const proto = program
-    .command('protocol')
-    .description('pAL/1.0 protocol management')
-    .addHelpText('after', `
-Examples:
-  $ pe protocol info                     Show protocol version and capabilities
-  $ pe protocol policy list              List all share policies
-  $ pe protocol policy set <id>          Set policy on a share
-  $ pe protocol route <peer>             Probe routes to a peer
-  $ pe protocol envelope <file>          Inspect a PAL envelope
-  $ pe protocol keys                     Show protocol key info
-`);
-
-  // ── pe protocol info ──
-  proto
-    .command('info')
-    .description('show protocol version, capabilities, and stats')
-    .action(async () => {
-      try {
-        const { PROTOCOL_VERSION, PROTOCOL_NAME } = await import('../protocol/index.js');
-        const identity = await getIdentity();
-        const { isPro } = await import('../core/pro.js');
-        const { getRelayLimits } = await import('../protocol/router.js');
-        const { FREE_POLICY_LIMITS, PRO_POLICY_LIMITS } = await import('../protocol/policy.js');
-
-        console.log('');
-        console.log(chalk.cyan.bold('PAL Protocol'));
-        console.log(`  Protocol:      ${chalk.white(PROTOCOL_NAME)}`);
-        console.log(`  Version:       ${chalk.white(PROTOCOL_VERSION)}`);
-        console.log(`  Tier:          ${isPro() ? chalk.green('Pro') : chalk.yellow('Free')}`);
-
-        console.log('');
-        console.log(chalk.cyan.bold('Capabilities'));
-        const caps = ['share', 'sync', 'chat', 'relay'];
-        if (isPro()) caps.push('delta-sync', 'receipts');
-        console.log(`  Supported:     ${caps.map(c => chalk.green(c)).join(', ')}`);
-
-        console.log('');
-        console.log(chalk.cyan.bold('Relay Limits'));
-        const limits = getRelayLimits();
-        console.log(`  Bandwidth:     ${limits.bandwidth ? (limits.bandwidth / 1024 / 1024) + ' MB/s' : chalk.green('Unlimited')}`);
-        console.log(`  Session:       ${limits.sessionDuration ? (limits.sessionDuration / 3600) + 'h' : chalk.green('Unlimited')}`);
-        console.log(`  Concurrent:    ${limits.concurrent}`);
-
-        console.log('');
-        console.log(chalk.cyan.bold('Policy Limits'));
-        const pl = isPro() ? PRO_POLICY_LIMITS : FREE_POLICY_LIMITS;
-        console.log(`  Max expiry:    ${pl.maxExpiry ? (pl.maxExpiry / 3600000) + 'h' : chalk.green('Unlimited')}`);
-        console.log(`  IP restrict:   ${pl.allowIPRestriction ? chalk.green('Yes') : chalk.gray('Pro only')}`);
-        console.log(`  Schedule:      ${pl.allowScheduleWindow ? chalk.green('Yes') : chalk.gray('Pro only')}`);
-        console.log(`  Receipts:      ${pl.allowReceipts ? chalk.green('Yes') : chalk.gray('Pro only')}`);
-
-        if (identity) {
-          console.log('');
-          console.log(chalk.cyan.bold('Identity'));
-          console.log(`  Public Key:    ${chalk.yellow(identity.publicKey?.slice(0, 32) + '...')}`);
-          console.log(`  Handle:        ${chalk.white(identity.handle || 'Not registered')}`);
-        }
-
-        console.log('');
-      } catch (err) {
-        console.error(chalk.red('Error:'), err.message);
-        process.exitCode = 1;
-      }
-    });
-
-  // ── pe protocol policy ──
-  const policy = proto
-    .command('policy')
-    .description('manage share policies');
-
-  policy
-    .command('list')
-    .description('list all share policies')
-    .action(async () => {
-      try {
-        const policies = listPolicies();
-        const shares = listShares();
-        const entries = Object.entries(policies);
-
-        if (entries.length === 0) {
-          console.log(chalk.gray('No policies configured. Use `pe protocol policy set <shareId>` to add one.'));
-          return;
-        }
-
-        console.log('');
-        for (const [shareId, p] of entries) {
-          const share = shares.find(s => s.id === shareId);
-          const name = share?.name || share?.path?.split(/[/\\]/).pop() || shareId.slice(0, 8);
-          console.log(chalk.cyan.bold(`${name}`));
-          console.log(`  Share ID:      ${chalk.gray(shareId)}`);
-          if (p.expiresAt) {
-            const expired = new Date(p.expiresAt) < new Date();
-            console.log(`  Expires:       ${expired ? chalk.red(p.expiresAt) : chalk.white(p.expiresAt)}`);
-          }
-          if (p.maxDownloads != null) {
-            console.log(`  Downloads:     ${chalk.white(p.downloadCount || 0)} / ${chalk.white(p.maxDownloads)}`);
-          }
-          if (p.allowedIPs?.length) {
-            console.log(`  Allowed IPs:   ${chalk.white(p.allowedIPs.join(', '))}`);
-          }
-          if (p.scheduleWindow) {
-            console.log(`  Schedule:      ${chalk.white(p.scheduleWindow.start + ' - ' + p.scheduleWindow.end)}`);
-          }
-          console.log('');
-        }
-      } catch (err) {
-        console.error(chalk.red('Error:'), err.message);
-        process.exitCode = 1;
-      }
-    });
-
-  policy
-    .command('set <shareId>')
-    .description('set or update policy on a share')
-    .option('--expires <duration>', 'Expiry duration (e.g. 24h, 7d, 30d)')
-    .option('--max-downloads <n>', 'Maximum number of downloads', parseInt)
-    .option('--allowed-ips <ips...>', 'Restrict to specific IPs or CIDRs')
-    .option('--schedule <window>', 'Transfer window (e.g. 22:00-06:00)')
-    .option('--require-receipt', 'Require signed download receipt (Pro)')
-    .option('--no-redistribute', 'Disallow redistribution')
-    .action(async (shareId, options) => {
-      try {
-        const { validatePolicy } = await import('../protocol/policy.js');
-        const policyData = {};
-
-        if (options.expires) {
-          const ms = parseDuration(options.expires);
-          if (!ms) {
-            console.log(chalk.red('Invalid duration. Use e.g. 24h, 7d, 30d'));
-            process.exitCode = 1;
-            return;
-          }
-          policyData.expiresAt = new Date(Date.now() + ms).toISOString();
-        }
-
-        if (options.maxDownloads != null) policyData.maxDownloads = options.maxDownloads;
-        if (options.allowedIps) policyData.allowedIPs = options.allowedIps;
-        if (options.schedule) {
-          const [start, end] = options.schedule.split('-');
-          if (!start || !end) {
-            console.log(chalk.red('Invalid schedule. Use format: HH:MM-HH:MM'));
-            process.exitCode = 1;
-            return;
-          }
-          policyData.scheduleWindow = { start: start.trim(), end: end.trim(), timezone: 'UTC' };
-        }
-        if (options.requireReceipt) policyData.requireReceipt = true;
-        if (options.redistribute === false) policyData.allowRedistribute = false;
-
-        const validation = validatePolicy(policyData);
-        if (!validation.valid) {
-          for (const err of validation.errors) {
-            console.log(chalk.red(`  ${err}`));
-          }
-          process.exitCode = 1;
-          return;
-        }
-
-        setSharePolicy(shareId, policyData);
-        console.log(chalk.green(`Policy updated for share ${shareId.slice(0, 8)}...`));
-
-        const updated = getSharePolicy(shareId);
-        if (updated.expiresAt) console.log(`  Expires:        ${chalk.white(updated.expiresAt)}`);
-        if (updated.maxDownloads) console.log(`  Max downloads:  ${chalk.white(updated.maxDownloads)}`);
-        if (updated.allowedIPs) console.log(`  Allowed IPs:    ${chalk.white(updated.allowedIPs.join(', '))}`);
-      } catch (err) {
-        console.error(chalk.red('Error:'), err.message);
-        process.exitCode = 1;
-      }
-    });
-
-  policy
-    .command('remove <shareId>')
-    .description('remove policy from a share')
-    .action(async (shareId) => {
-      try {
-        const { removeSharePolicy } = await import('../core/sharePolicy.js');
-        removeSharePolicy(shareId);
-        console.log(chalk.green(`Policy removed for share ${shareId.slice(0, 8)}...`));
-      } catch (err) {
-        console.error(chalk.red('Error:'), err.message);
-        process.exitCode = 1;
-      }
-    });
-
-  // ── pe protocol route ──
-  proto
-    .command('route <peer>')
-    .description('probe connectivity routes to a peer')
-    .action(async (peer) => {
-      try {
-        const { probeRoutes, selectRoute, ROUTE_PRIORITY } = await import('../protocol/router.js');
-
-        // Resolve peer — could be handle or public key
-        let targetPK = peer;
-        if (peer.length !== 64) {
-          const friends = getFriends();
-          const pal = friends.find(f => f.name === peer || f.handle === peer);
-          if (pal) {
-            targetPK = pal.id;
-          } else {
-            console.log(chalk.red(`Peer '${peer}' not found. Use a pal name, handle, or public key.`));
-            process.exitCode = 1;
-            return;
-          }
-        }
-
-        console.log(chalk.cyan(`Probing routes to ${peer}...`));
-        console.log('');
-
-        const results = await probeRoutes(targetPK);
-        for (const route of ROUTE_PRIORITY) {
-          const r = results[route];
-          if (!r) continue;
-          const icon = r.reachable ? chalk.green('●') : chalk.red('●');
-          const latency = r.latency != null ? chalk.gray(` (${r.latency}ms)`) : '';
-          const addr = r.address ? chalk.gray(` ${r.address}`) : '';
-          console.log(`  ${icon} ${route.toUpperCase()}${addr}${latency}`);
-        }
-
-        const best = selectRoute(results);
-        console.log('');
-        if (best) {
-          console.log(`  Recommended: ${chalk.green.bold(best.type.toUpperCase())}`);
-        } else {
-          console.log(chalk.red('  No reachable route found.'));
-        }
-        console.log('');
-      } catch (err) {
-        console.error(chalk.red('Error:'), err.message);
-        process.exitCode = 1;
-      }
-    });
-
-  // ── pe protocol envelope ──
-  proto
-    .command('envelope <file>')
-    .description('inspect a PAL/1.0 envelope from a JSON file')
-    .option('--verify', 'Verify signature')
-    .option('--decrypt', 'Decrypt payload (requires identity)')
-    .action(async (file, options) => {
-      try {
-        const fs = await import('fs');
-        const pathMod = await import('path');
-        const resolvedPath = pathMod.resolve(file);
-        if (!resolvedPath.endsWith('.json')) {
-          console.log(chalk.red('Only .json envelope files are supported.'));
-          process.exitCode = 1;
-          return;
-        }
-        const cwd = process.cwd();
-        if (!resolvedPath.startsWith(cwd) && !resolvedPath.startsWith(pathMod.resolve(process.env.HOME || process.env.USERPROFILE || ''))) {
-          console.log(chalk.red('Path must be within working directory or home folder.'));
-          process.exitCode = 1;
-          return;
-        }
-        const data = JSON.parse(fs.readFileSync(resolvedPath, 'utf8'));
-
-        console.log('');
-        console.log(chalk.cyan.bold('PAL Envelope'));
-        console.log(`  Version:   ${chalk.white('PAL/' + data.v)}`);
-        console.log(`  Type:      ${chalk.yellow(data.type)}`);
-        console.log(`  From:      ${chalk.white(data.from?.slice(0, 16) + '...')}`);
-        console.log(`  To:        ${data.to ? chalk.white(data.to.slice(0, 16) + '...') : chalk.gray('broadcast')}`);
-        console.log(`  ID:        ${chalk.gray(data.id)}`);
-        console.log(`  Timestamp: ${chalk.white(data.ts)}`);
-        console.log(`  Encrypted: ${data.payload?._enc ? chalk.yellow('Yes') : chalk.gray('No')}`);
-
-        if (options.verify) {
-          const { verify } = await import('../protocol/envelope.js');
-          const result = verify(data);
-          console.log(`  Signature: ${result.valid ? chalk.green('Valid ✓') : chalk.red('Invalid ✗')}`);
-          if (!result.valid) {
-            for (const e of result.errors) console.log(`    ${chalk.red(e)}`);
-          }
-        }
-
-        if (options.decrypt && data.payload?._enc) {
-          const { decrypt } = await import('../protocol/envelope.js');
-          const identity = await getIdentity();
-          if (!identity?.privateKey) {
-            console.log(chalk.red('  Cannot decrypt: no identity found'));
-          } else {
-            try {
-              const keyPair = {
-                publicKey: Buffer.from(identity.publicKey, 'hex'),
-                privateKey: Buffer.from(identity.privateKey, 'hex'),
-              };
-              const payload = decrypt(data, keyPair);
-              console.log('');
-              console.log(chalk.cyan.bold('Decrypted Payload'));
-              console.log(JSON.stringify(payload, null, 2));
-            } catch (e) {
-              console.log(chalk.red(`  Decryption failed: ${e.message}`));
-            }
-          }
-        }
-
-        if (!data.payload?._enc) {
-          console.log('');
-          console.log(chalk.cyan.bold('Payload'));
-          console.log(JSON.stringify(data.payload, null, 2));
-        }
-
-        console.log('');
-      } catch (err) {
-        console.error(chalk.red('Error:'), err.message);
-        process.exitCode = 1;
-      }
-    });
-
-  // ── pe protocol keys ──
-  proto
-    .command('keys')
-    .description('show protocol key info')
-    .action(async () => {
-      try {
-        const identity = await getIdentity();
-        if (!identity) {
-          console.log(chalk.gray('No identity. Run `pe init <name>` first.'));
-          return;
-        }
-
-        const sodium = (await import('sodium-native')).default;
-        const edPK = Buffer.from(identity.publicKey, 'hex');
-        const curve25519PK = Buffer.alloc(sodium.crypto_box_PUBLICKEYBYTES);
-        sodium.crypto_sign_ed25519_pk_to_curve25519(curve25519PK, edPK);
-
-        console.log('');
-        console.log(chalk.cyan.bold('Protocol Keys'));
-        console.log(`  Ed25519 PK (signing):    ${chalk.yellow(identity.publicKey)}`);
-        console.log(`  Curve25519 PK (encrypt): ${chalk.yellow(curve25519PK.toString('hex'))}`);
-        console.log(`  Private key:             ${chalk.gray('stored in OS credential manager')}`);
-        console.log('');
-      } catch (err) {
-        console.error(chalk.red('Error:'), err.message);
-        process.exitCode = 1;
-      }
-    });
-}
-
-function parseDuration(s) {
-  const m = s.match(/^(\d+)(h|d|m|w)$/);
-  if (!m) return null;
-  const n = parseInt(m[1]);
-  const unit = { m: 60000, h: 3600000, d: 86400000, w: 604800000 }[m[2]];
-  return n * unit;
-}
+import chalk from 'chalk';
+import { getIdentity } from '../core/identity.js';
+import { listShares, getShareKey } from '../core/shares.js';
+import { getSharePolicy, setSharePolicy, listPolicies } from '../core/sharePolicy.js';
+import { getFriends } from '../core/users.js';
+import config from '../utils/config.js';
+
+export default function protocolCommand(program) {
+  const proto = program
+    .command('protocol')
+    .description('pAL/1.0 protocol management')
+    .addHelpText('after', `
+Examples:
+  $ pal protocol info                     Show protocol version and capabilities
+  $ pal protocol policy list              List all share policies
+  $ pal protocol policy set <id>          Set policy on a share
+  $ pal protocol route <peer>             Probe routes to a peer
+  $ pal protocol envelope <file>          Inspect a PAL envelope
+  $ pal protocol keys                     Show protocol key info
+`);
+
+  // ── pal protocol info ──
+  proto
+    .command('info')
+    .description('show protocol version, capabilities, and stats')
+    .action(async () => {
+      try {
+        const { PROTOCOL_VERSION, PROTOCOL_NAME } = await import('../protocol/index.js');
+        const identity = await getIdentity();
+        const { isPro } = await import('../core/pro.js');
+        const { getRelayLimits } = await import('../protocol/router.js');
+        const { FREE_POLICY_LIMITS, PRO_POLICY_LIMITS } = await import('../protocol/policy.js');
+
+        console.log('');
+        console.log(chalk.cyan.bold('PAL Protocol'));
+        console.log(`  Protocol:      ${chalk.white(PROTOCOL_NAME)}`);
+        console.log(`  Version:       ${chalk.white(PROTOCOL_VERSION)}`);
+        console.log(`  Tier:          ${isPro() ? chalk.green('Pro') : chalk.yellow('Free')}`);
+
+        console.log('');
+        console.log(chalk.cyan.bold('Capabilities'));
+        const caps = ['share', 'sync', 'chat', 'relay'];
+        if (isPro()) caps.push('delta-sync', 'receipts');
+        console.log(`  Supported:     ${caps.map(c => chalk.green(c)).join(', ')}`);
+
+        console.log('');
+        console.log(chalk.cyan.bold('Relay Limits'));
+        const limits = getRelayLimits();
+        console.log(`  Bandwidth:     ${limits.bandwidth ? (limits.bandwidth / 1024 / 1024) + ' MB/s' : chalk.green('Unlimited')}`);
+        console.log(`  Session:       ${limits.sessionDuration ? (limits.sessionDuration / 3600) + 'h' : chalk.green('Unlimited')}`);
+        console.log(`  Concurrent:    ${limits.concurrent}`);
+
+        console.log('');
+        console.log(chalk.cyan.bold('Policy Limits'));
+        const pl = isPro() ? PRO_POLICY_LIMITS : FREE_POLICY_LIMITS;
+        console.log(`  Max expiry:    ${pl.maxExpiry ? (pl.maxExpiry / 3600000) + 'h' : chalk.green('Unlimited')}`);
+        console.log(`  IP restrict:   ${pl.allowIPRestriction ? chalk.green('Yes') : chalk.gray('Pro only')}`);
+        console.log(`  Schedule:      ${pl.allowScheduleWindow ? chalk.green('Yes') : chalk.gray('Pro only')}`);
+        console.log(`  Receipts:      ${pl.allowReceipts ? chalk.green('Yes') : chalk.gray('Pro only')}`);
+
+        if (identity) {
+          console.log('');
+          console.log(chalk.cyan.bold('Identity'));
+          console.log(`  Public Key:    ${chalk.yellow(identity.publicKey?.slice(0, 32) + '...')}`);
+          console.log(`  Handle:        ${chalk.white(identity.handle || 'Not registered')}`);
+        }
+
+        console.log('');
+      } catch (err) {
+        console.error(chalk.red('Error:'), err.message);
+        process.exitCode = 1;
+      }
+    });
+
+  // ── pal protocol policy ──
+  const policy = proto
+    .command('policy')
+    .description('manage share policies');
+
+  policy
+    .command('list')
+    .description('list all share policies')
+    .action(async () => {
+      try {
+        const policies = listPolicies();
+        const shares = listShares();
+        const entries = Object.entries(policies);
+
+        if (entries.length === 0) {
+          console.log(chalk.gray('No policies configured. Use `pal protocol policy set <shareId>` to add one.'));
+          return;
+        }
+
+        console.log('');
+        for (const [shareId, p] of entries) {
+          const share = shares.find(s => s.id === shareId);
+          const name = share?.name || share?.path?.split(/[/\\]/).pop() || shareId.slice(0, 8);
+          console.log(chalk.cyan.bold(`${name}`));
+          console.log(`  Share ID:      ${chalk.gray(shareId)}`);
+          if (p.expiresAt) {
+            const expired = new Date(p.expiresAt) < new Date();
+            console.log(`  Expires:       ${expired ? chalk.red(p.expiresAt) : chalk.white(p.expiresAt)}`);
+          }
+          if (p.maxDownloads != null) {
+            console.log(`  Downloads:     ${chalk.white(p.downloadCount || 0)} / ${chalk.white(p.maxDownloads)}`);
+          }
+          if (p.allowedIPs?.length) {
+            console.log(`  Allowed IPs:   ${chalk.white(p.allowedIPs.join(', '))}`);
+          }
+          if (p.scheduleWindow) {
+            console.log(`  Schedule:      ${chalk.white(p.scheduleWindow.start + ' - ' + p.scheduleWindow.end)}`);
+          }
+          console.log('');
+        }
+      } catch (err) {
+        console.error(chalk.red('Error:'), err.message);
+        process.exitCode = 1;
+      }
+    });
+
+  policy
+    .command('set <shareId>')
+    .description('set or update policy on a share')
+    .option('--expires <duration>', 'Expiry duration (e.g. 24h, 7d, 30d)')
+    .option('--max-downloads <n>', 'Maximum number of downloads', parseInt)
+    .option('--allowed-ips <ips...>', 'Restrict to specific IPs or CIDRs')
+    .option('--schedule <window>', 'Transfer window (e.g. 22:00-06:00)')
+    .option('--require-receipt', 'Require signed download receipt (Pro)')
+    .option('--no-redistribute', 'Disallow redistribution')
+    .action(async (shareId, options) => {
+      try {
+        const { validatePolicy } = await import('../protocol/policy.js');
+        const policyData = {};
+
+        if (options.expires) {
+          const ms = parseDuration(options.expires);
+          if (!ms) {
+            console.log(chalk.red('Invalid duration. Use e.g. 24h, 7d, 30d'));
+            process.exitCode = 1;
+            return;
+          }
+          policyData.expiresAt = new Date(Date.now() + ms).toISOString();
+        }
+
+        if (options.maxDownloads != null) policyData.maxDownloads = options.maxDownloads;
+        if (options.allowedIps) policyData.allowedIPs = options.allowedIps;
+        if (options.schedule) {
+          const [start, end] = options.schedule.split('-');
+          if (!start || !end) {
+            console.log(chalk.red('Invalid schedule. Use format: HH:MM-HH:MM'));
+            process.exitCode = 1;
+            return;
+          }
+          policyData.scheduleWindow = { start: start.trim(), end: end.trim(), timezone: 'UTC' };
+        }
+        if (options.requireReceipt) policyData.requireReceipt = true;
+        if (options.redistribute === false) policyData.allowRedistribute = false;
+
+        const validation = validatePolicy(policyData);
+        if (!validation.valid) {
+          for (const err of validation.errors) {
+            console.log(chalk.red(`  ${err}`));
+          }
+          process.exitCode = 1;
+          return;
+        }
+
+        setSharePolicy(shareId, policyData);
+        console.log(chalk.green(`Policy updated for share ${shareId.slice(0, 8)}...`));
+
+        const updated = getSharePolicy(shareId);
+        if (updated.expiresAt) console.log(`  Expires:        ${chalk.white(updated.expiresAt)}`);
+        if (updated.maxDownloads) console.log(`  Max downloads:  ${chalk.white(updated.maxDownloads)}`);
+        if (updated.allowedIPs) console.log(`  Allowed IPs:    ${chalk.white(updated.allowedIPs.join(', '))}`);
+      } catch (err) {
+        console.error(chalk.red('Error:'), err.message);
+        process.exitCode = 1;
+      }
+    });
+
+  policy
+    .command('remove <shareId>')
+    .description('remove policy from a share')
+    .action(async (shareId) => {
+      try {
+        const { removeSharePolicy } = await import('../core/sharePolicy.js');
+        removeSharePolicy(shareId);
+        console.log(chalk.green(`Policy removed for share ${shareId.slice(0, 8)}...`));
+      } catch (err) {
+        console.error(chalk.red('Error:'), err.message);
+        process.exitCode = 1;
+      }
+    });
+
+  // ── pal protocol route ──
+  proto
+    .command('route <peer>')
+    .description('probe connectivity routes to a peer')
+    .action(async (peer) => {
+      try {
+        const { probeRoutes, selectRoute, ROUTE_PRIORITY } = await import('../protocol/router.js');
+
+        // Resolve peer — could be handle or public key
+        let targetPK = peer;
+        if (peer.length !== 64) {
+          const friends = getFriends();
+          const pal = friends.find(f => f.name === peer || f.handle === peer);
+          if (pal) {
+            targetPK = pal.id;
+          } else {
+            console.log(chalk.red(`Peer '${peer}' not found. Use a pal name, handle, or public key.`));
+            process.exitCode = 1;
+            return;
+          }
+        }
+
+        console.log(chalk.cyan(`Probing routes to ${peer}...`));
+        console.log('');
+
+        const results = await probeRoutes(targetPK);
+        for (const route of ROUTE_PRIORITY) {
+          const r = results[route];
+          if (!r) continue;
+          const icon = r.reachable ? chalk.green('●') : chalk.red('●');
+          const latency = r.latency != null ? chalk.gray(` (${r.latency}ms)`) : '';
+          const addr = r.address ? chalk.gray(` ${r.address}`) : '';
+          console.log(`  ${icon} ${route.toUpperCase()}${addr}${latency}`);
+        }
+
+        const best = selectRoute(results);
+        console.log('');
+        if (best) {
+          console.log(`  Recommended: ${chalk.green.bold(best.type.toUpperCase())}`);
+        } else {
+          console.log(chalk.red('  No reachable route found.'));
+        }
+        console.log('');
+      } catch (err) {
+        console.error(chalk.red('Error:'), err.message);
+        process.exitCode = 1;
+      }
+    });
+
+  // ── pal protocol envelope ──
+  proto
+    .command('envelope <file>')
+    .description('inspect a PAL/1.0 envelope from a JSON file')
+    .option('--verify', 'Verify signature')
+    .option('--decrypt', 'Decrypt payload (requires identity)')
+    .action(async (file, options) => {
+      try {
+        const fs = await import('fs');
+        const pathMod = await import('path');
+        const resolvedPath = pathMod.resolve(file);
+        if (!resolvedPath.endsWith('.json')) {
+          console.log(chalk.red('Only .json envelope files are supported.'));
+          process.exitCode = 1;
+          return;
+        }
+        const cwd = process.cwd();
+        if (!resolvedPath.startsWith(cwd) && !resolvedPath.startsWith(pathMod.resolve(process.env.HOME || process.env.USERPROFILE || ''))) {
+          console.log(chalk.red('Path must be within working directory or home folder.'));
+          process.exitCode = 1;
+          return;
+        }
+        const data = JSON.parse(fs.readFileSync(resolvedPath, 'utf8'));
+
+        console.log('');
+        console.log(chalk.cyan.bold('PAL Envelope'));
+        console.log(`  Version:   ${chalk.white('PAL/' + data.v)}`);
+        console.log(`  Type:      ${chalk.yellow(data.type)}`);
+        console.log(`  From:      ${chalk.white(data.from?.slice(0, 16) + '...')}`);
+        console.log(`  To:        ${data.to ? chalk.white(data.to.slice(0, 16) + '...') : chalk.gray('broadcast')}`);
+        console.log(`  ID:        ${chalk.gray(data.id)}`);
+        console.log(`  Timestamp: ${chalk.white(data.ts)}`);
+        console.log(`  Encrypted: ${data.payload?._enc ? chalk.yellow('Yes') : chalk.gray('No')}`);
+
+        if (options.verify) {
+          const { verify } = await import('../protocol/envelope.js');
+          const result = verify(data);
+          console.log(`  Signature: ${result.valid ? chalk.green('Valid ✓') : chalk.red('Invalid ✗')}`);
+          if (!result.valid) {
+            for (const e of result.errors) console.log(`    ${chalk.red(e)}`);
+          }
+        }
+
+        if (options.decrypt && data.payload?._enc) {
+          const { decrypt } = await import('../protocol/envelope.js');
+          const identity = await getIdentity();
+          if (!identity?.privateKey) {
+            console.log(chalk.red('  Cannot decrypt: no identity found'));
+          } else {
+            try {
+              const keyPair = {
+                publicKey: Buffer.from(identity.publicKey, 'hex'),
+                privateKey: Buffer.from(identity.privateKey, 'hex'),
+              };
+              const payload = decrypt(data, keyPair);
+              console.log('');
+              console.log(chalk.cyan.bold('Decrypted Payload'));
+              console.log(JSON.stringify(payload, null, 2));
+            } catch (e) {
+              console.log(chalk.red(`  Decryption failed: ${e.message}`));
+            }
+          }
+        }
+
+        if (!data.payload?._enc) {
+          console.log('');
+          console.log(chalk.cyan.bold('Payload'));
+          console.log(JSON.stringify(data.payload, null, 2));
+        }
+
+        console.log('');
+      } catch (err) {
+        console.error(chalk.red('Error:'), err.message);
+        process.exitCode = 1;
+      }
+    });
+
+  // ── pal protocol keys ──
+  proto
+    .command('keys')
+    .description('show protocol key info')
+    .action(async () => {
+      try {
+        const identity = await getIdentity();
+        if (!identity) {
+          console.log(chalk.gray('No identity. Run `pal init <name>` first.'));
+          return;
+        }
+
+        const sodium = (await import('sodium-native')).default;
+        const edPK = Buffer.from(identity.publicKey, 'hex');
+        const curve25519PK = Buffer.alloc(sodium.crypto_box_PUBLICKEYBYTES);
+        sodium.crypto_sign_ed25519_pk_to_curve25519(curve25519PK, edPK);
+
+        console.log('');
+        console.log(chalk.cyan.bold('Protocol Keys'));
+        console.log(`  Ed25519 PK (signing):    ${chalk.yellow(identity.publicKey)}`);
+        console.log(`  Curve25519 PK (encrypt): ${chalk.yellow(curve25519PK.toString('hex'))}`);
+        console.log(`  Private key:             ${chalk.gray('stored in OS credential manager')}`);
+        console.log('');
+      } catch (err) {
+        console.error(chalk.red('Error:'), err.message);
+        process.exitCode = 1;
+      }
+    });
+}
+
+function parseDuration(s) {
+  const m = s.match(/^(\d+)(h|d|m|w)$/);
+  if (!m) return null;
+  const n = parseInt(m[1]);
+  const unit = { m: 60000, h: 3600000, d: 86400000, w: 604800000 }[m[2]];
+  return n * unit;
+}