pal-explorer-cli 0.4.0

package/lib/commands/pin.js

@@ -0,0 +1,97 @@
+import chalk from 'chalk';
+import crypto from 'crypto';
+import config from '../utils/config.js';
+import readline from 'readline';
+
+function promptPin(prompt) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(prompt, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+export default function pinCommand(program) {
+  const cmd = program
+    .command('pin')
+    .description('manage PIN lock for app security')
+    .addHelpText('after', `
+Examples:
+  $ pe pin status     Show if PIN is set
+  $ pe pin set        Set a new PIN
+  $ pe pin remove     Remove PIN lock
+`)
+    .action(() => {
+      showPinStatus();
+    });
+
+  cmd
+    .command('status')
+    .description('show if PIN lock is enabled')
+    .action(() => {
+      showPinStatus();
+    });
+
+  cmd
+    .command('set')
+    .description('set or update PIN lock')
+    .action(async () => {
+      const pin = await promptPin('Enter new PIN: ');
+      if (!pin || pin.length < 4) {
+        console.log(chalk.red('PIN must be at least 4 characters.'));
+        process.exitCode = 1;
+        return;
+      }
+      const confirm = await promptPin('Confirm PIN: ');
+      if (pin !== confirm) {
+        console.log(chalk.red('PINs do not match.'));
+        process.exitCode = 1;
+        return;
+      }
+      const salt = crypto.randomBytes(16).toString('hex');
+      const hash = crypto.createHash('sha256').update(salt + pin).digest('hex');
+      config.set('pinHash', JSON.stringify({ salt, hash }));
+      console.log(chalk.green('\u2714 PIN lock enabled.'));
+    });
+
+  cmd
+    .command('remove')
+    .description('remove PIN lock')
+    .action(async () => {
+      const existing = config.get('pinHash');
+      if (!existing) {
+        console.log(chalk.gray('No PIN is set.'));
+        return;
+      }
+      const pin = await promptPin('Enter current PIN to remove: ');
+      let match = false;
+      try {
+        const parsed = JSON.parse(existing);
+        if (parsed.salt && parsed.hash) {
+          const hash = crypto.createHash('sha256').update(parsed.salt + pin).digest('hex');
+          match = hash === parsed.hash;
+        }
+      } catch {
+        const hash = crypto.createHash('sha256').update(pin).digest('hex');
+        match = hash === existing;
+      }
+      if (!match) {
+        console.log(chalk.red('Incorrect PIN.'));
+        process.exitCode = 1;
+        return;
+      }
+      config.delete('pinHash');
+      console.log(chalk.green('\u2714 PIN lock removed.'));
+    });
+}
+
+function showPinStatus() {
+  const pinHash = config.get('pinHash');
+  if (pinHash) {
+    console.log(`PIN lock: ${chalk.green('Enabled')}`);
+  } else {
+    console.log(`PIN lock: ${chalk.gray('Not set')}`);
+  }
+}

package/lib/commands/protocol.js

@@ -0,0 +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;
+}

package/lib/commands/rbac.js

@@ -0,0 +1,147 @@
+import chalk from 'chalk';
+
+const BUILTIN_ROLES = {
+  'org-admin': ['view', 'download', 'reshare', 'delete', 'manage', 'audit', 'assign-roles'],
+  'dept-admin': ['view', 'download', 'reshare', 'delete', 'manage'],
+  'admin': ['view', 'download', 'reshare', 'delete', 'manage'],
+  'editor': ['view', 'download', 'reshare'],
+  'viewer': ['view', 'download'],
+  'member': ['view', 'download'],
+  'restricted': ['view'],
+  'external': ['view'],
+};
+
+export default function rbacCommand(program) {
+  const cmd = program
+    .command('rbac')
+    .description('enterprise role-based access control (Enterprise)')
+    .addHelpText('after', `
+Examples:
+  $ pe rbac roles                              List all roles and permissions
+  $ pe rbac assign <publicKey> admin            Assign role to user
+  $ pe rbac assign <publicKey> dept-admin --org acme --dept engineering
+  $ pe rbac revoke <publicKey>                  Remove role assignment
+  $ pe rbac check <publicKey> delete            Check if user has permission
+`)
+    .action(() => { cmd.outputHelp(); });
+
+  cmd
+    .command('roles')
+    .description('list all roles with permissions')
+    .action(async () => {
+      try {
+        console.log('');
+        console.log(chalk.cyan.bold('Flat Roles'));
+        console.log(chalk.gray('─'.repeat(50)));
+        for (const role of ['admin', 'editor', 'viewer', 'restricted']) {
+          const perms = BUILTIN_ROLES[role];
+          console.log(`  ${chalk.white(role)}`);
+          console.log(`    ${chalk.gray(perms.join(', '))}`);
+        }
+
+        console.log('');
+        console.log(chalk.cyan.bold('Enterprise Hierarchical Roles'));
+        console.log(chalk.gray('─'.repeat(50)));
+        for (const role of ['org-admin', 'dept-admin', 'member', 'external']) {
+          const perms = BUILTIN_ROLES[role];
+          const scope = role === 'dept-admin' ? chalk.yellow(' (scoped to dept)') : '';
+          const note = role === 'external' ? chalk.yellow(' (limited)') : '';
+          console.log(`  ${chalk.white(role)}${scope}${note}`);
+          console.log(`    ${chalk.gray(perms.join(', '))}`);
+        }
+        console.log('');
+      } catch (err) {
+        console.error(chalk.red(`Failed to list roles: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  cmd
+    .command('assign <publicKey> <role>')
+    .description('assign role to user')
+    .option('--org <orgId>', 'scope to organization')
+    .option('--dept <deptName>', 'scope to department')
+    .action(async (publicKey, role, opts) => {
+      try {
+        if (!BUILTIN_ROLES[role]) {
+          console.error(chalk.red(`Unknown role "${role}". Valid roles: ${Object.keys(BUILTIN_ROLES).join(', ')}`));
+          process.exitCode = 1;
+          return;
+        }
+
+        const extConfig = (await import('../utils/config.js')).default;
+        const store = extConfig.get('ext_store.enterprise-rbac') || {};
+        const key = `role:${publicKey}`;
+        store[key] = {
+          role,
+          org: opts.org || null,
+          dept: opts.dept || null,
+          assignedAt: new Date().toISOString(),
+        };
+        extConfig.set('ext_store.enterprise-rbac', store);
+
+        let scope = '';
+        if (opts.org) scope += ` org=${chalk.white(opts.org)}`;
+        if (opts.dept) scope += ` dept=${chalk.white(opts.dept)}`;
+        console.log(chalk.green(`✔ Assigned role "${role}" to ${publicKey.slice(0, 16)}...${scope}`));
+      } catch (err) {
+        console.error(chalk.red(`Assign failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  cmd
+    .command('revoke <publicKey>')
+    .description('remove role assignment')
+    .action(async (publicKey) => {
+      try {
+        const extConfig = (await import('../utils/config.js')).default;
+        const store = extConfig.get('ext_store.enterprise-rbac') || {};
+        const key = `role:${publicKey}`;
+
+        if (!store[key]) {
+          console.log(chalk.yellow(`No role assignment found for ${publicKey.slice(0, 16)}...`));
+          return;
+        }
+
+        const oldRole = store[key].role;
+        delete store[key];
+        extConfig.set('ext_store.enterprise-rbac', store);
+        console.log(chalk.green(`✔ Revoked role "${oldRole}" from ${publicKey.slice(0, 16)}...`));
+      } catch (err) {
+        console.error(chalk.red(`Revoke failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  cmd
+    .command('check <publicKey> <permission>')
+    .description('check if user has specific permission')
+    .action(async (publicKey, permission) => {
+      try {
+        const extConfig = (await import('../utils/config.js')).default;
+        const store = extConfig.get('ext_store.enterprise-rbac') || {};
+        const key = `role:${publicKey}`;
+        const assignment = store[key];
+
+        if (!assignment) {
+          console.log(chalk.red(`✘ No role assigned to ${publicKey.slice(0, 16)}...`));
+          process.exitCode = 1;
+          return;
+        }
+
+        const perms = BUILTIN_ROLES[assignment.role] || [];
+        const has = perms.includes(permission);
+
+        if (has) {
+          console.log(chalk.green(`✔ ${publicKey.slice(0, 16)}... HAS "${permission}" (role: ${assignment.role})`));
+        } else {
+          console.log(chalk.red(`✘ ${publicKey.slice(0, 16)}... DOES NOT have "${permission}" (role: ${assignment.role})`));
+          process.exitCode = 1;
+        }
+      } catch (err) {
+        console.error(chalk.red(`Check failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+}

package/lib/commands/recover.js

@@ -0,0 +1,36 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import { recoverIdentity } from '../core/identity.js';
+
+export default function recoverCommand(program) {
+  program
+    .command('recover <mnemonic...>')
+    .description('recover your identity from a BIP-39 mnemonic phrase')
+    .option('-n, --name <name>', 'Name for the recovered identity')
+    .addHelpText('after', `
+Examples:
+  $ pe recover word1 word2 ... word24           Recover from 24-word phrase
+  $ pe recover word1 word2 ... word24 -n alice  Recover with name "alice"
+`)
+    .action(async (words, opts) => {
+      const mnemonic = words.join(' ').trim();
+      const wordCount = mnemonic.split(/\s+/).length;
+      if (wordCount !== 24) {
+        console.log(chalk.red(`Expected 24 words, got ${wordCount}.`));
+        process.exitCode = 1;
+        return;
+      }
+
+      const spinner = ora('Recovering identity...').start();
+      try {
+        const identity = await recoverIdentity(mnemonic, opts.name);
+        spinner.succeed(chalk.green('Identity recovered!'));
+        console.log(chalk.cyan(`Public Key: ${identity.publicKey}`));
+        console.log(chalk.gray('Re-register your handle with `pe register <handle>` to associate it with this key.'));
+      } catch (err) {
+        spinner.fail(chalk.red('Recovery failed'));
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+}