pal-explorer-cli 0.4.0

package/lib/commands/api-keys.js

@@ -0,0 +1,131 @@
+import chalk from 'chalk';
+import config from '../utils/config.js';
+import { getIdentity } from '../core/identity.js';
+
+const DISCOVERY_URL = process.env.PAL_DISCOVERY_URL || config.get('discoveryUrl') || 'http://localhost:3000';
+
+export default function apiKeysCommand(program) {
+  const cmd = program
+    .command('api-keys')
+    .description('manage API keys (Pro)')
+    .addHelpText('after', `
+Examples:
+  $ pe api-keys                   List your API keys
+  $ pe api-keys create "my-bot"   Create a new API key
+  $ pe api-keys revoke <keyId>    Revoke an API key
+`)
+    .action(async () => {
+      try {
+        const identity = await getIdentity();
+        if (!identity?.publicKey) {
+          console.log(chalk.red('No identity. Run `pe init` first.'));
+          process.exitCode = 1;
+          return;
+        }
+
+        const res = await fetch(`${DISCOVERY_URL}/api/v1/keys/${encodeURIComponent(identity.publicKey)}`, {
+          signal: AbortSignal.timeout(5000),
+        });
+
+        if (!res.ok) {
+          console.log(chalk.red('Failed to fetch API keys.'));
+          process.exitCode = 1;
+          return;
+        }
+
+        const keys = await res.json();
+        if (!Array.isArray(keys) || keys.length === 0) {
+          console.log(chalk.gray('No API keys. Use `pe api-keys create <name>` to create one.'));
+          return;
+        }
+
+        console.log('');
+        console.log(chalk.cyan('API Keys:'));
+        for (const k of keys) {
+          const status = k.revoked ? chalk.red('revoked') : chalk.green('active');
+          console.log(`  ${chalk.white(k.id)}  [${status}]  ${chalk.yellow(k.name || 'unnamed')}`);
+          console.log(`    Created: ${chalk.gray(k.createdAt || 'unknown')}`);
+          if (k.lastUsed) console.log(`    Last used: ${chalk.gray(k.lastUsed)}`);
+        }
+      } catch (err) {
+        console.log(chalk.red(`Error: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  cmd
+    .command('create <name>')
+    .description('create a new API key')
+    .action(async (name) => {
+      try {
+        const identity = await getIdentity();
+        if (!identity?.publicKey) {
+          console.log(chalk.red('No identity. Run `pe init` first.'));
+          process.exitCode = 1;
+          return;
+        }
+
+        const res = await fetch(`${DISCOVERY_URL}/api/v1/keys`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ publicKey: identity.publicKey, name }),
+          signal: AbortSignal.timeout(10000),
+        });
+
+        if (!res.ok) {
+          const err = await res.json().catch(() => ({}));
+          console.log(chalk.red(`Failed: ${err.error || res.statusText}`));
+          process.exitCode = 1;
+          return;
+        }
+
+        const key = await res.json();
+        console.log(chalk.green(`✔ API key created: ${key.id}`));
+        const apiKey = key.key || key.secret;
+        if (apiKey) {
+          console.log(chalk.yellow('  Key (save it — shown only once):'));
+          console.log(`  ${chalk.white(apiKey)}`);
+          try {
+            const keytar = (await import('keytar')).default;
+            await keytar.setPassword('palexplorer', 'apiKey', apiKey);
+          } catch {
+            config.set('apiKey', apiKey);
+          }
+        }
+      } catch (err) {
+        console.log(chalk.red(`Error: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  cmd
+    .command('revoke <keyId>')
+    .description('revoke an API key')
+    .action(async (keyId) => {
+      try {
+        const identity = await getIdentity();
+        if (!identity?.publicKey) {
+          console.log(chalk.red('No identity. Run `pe init` first.'));
+          process.exitCode = 1;
+          return;
+        }
+
+        const res = await fetch(`${DISCOVERY_URL}/api/v1/keys/${encodeURIComponent(identity.publicKey)}/${encodeURIComponent(keyId)}`, {
+          method: 'DELETE',
+          signal: AbortSignal.timeout(10000),
+        });
+
+        if (!res.ok) {
+          const err = await res.json().catch(() => ({}));
+          console.log(chalk.red(`Failed: ${err.error || res.statusText}`));
+          process.exitCode = 1;
+          return;
+        }
+
+        console.log(chalk.green(`✔ API key ${keyId} revoked.`));
+      } catch (err) {
+        console.log(chalk.red(`Error: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+}

package/lib/commands/audit.js

@@ -0,0 +1,235 @@
+import chalk from 'chalk';
+import { createHash } from 'crypto';
+import path from 'path';
+import os from 'os';
+
+function isPrivateIP(hostname) {
+  if (hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1') return true;
+  const parts = hostname.split('.').map(Number);
+  if (parts.length === 4) {
+    if (parts[0] === 10) return true;
+    if (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31) return true;
+    if (parts[0] === 192 && parts[1] === 168) return true;
+    if (parts[0] === 169 && parts[1] === 254) return true;
+    if (parts[0] === 0) return true;
+  }
+  return false;
+}
+
+function validateWebhookUrl(url) {
+  let parsed;
+  try { parsed = new URL(url); } catch { throw new Error('Invalid URL'); }
+  if (parsed.protocol !== 'https:') throw new Error('Webhook URL must use HTTPS');
+  if (isPrivateIP(parsed.hostname)) throw new Error('Webhook URL must not point to private/internal addresses');
+  return url;
+}
+
+function validateOutputPath(filePath) {
+  const resolved = path.resolve(filePath);
+  const home = os.homedir();
+  const cwd = process.cwd();
+  if (!resolved.startsWith(home) && !resolved.startsWith(cwd)) {
+    throw new Error('Output path must be within home directory or current working directory');
+  }
+  if (resolved.includes('..')) {
+    throw new Error('Path traversal not allowed');
+  }
+  return resolved;
+}
+
+export default function auditCommand(program) {
+  const cmd = program
+    .command('audit')
+    .description('tamper-proof audit logging (Enterprise)')
+    .addHelpText('after', `
+Examples:
+  $ pe audit export --format json -o audit.json
+  $ pe audit export --from 2026-01-01 --to 2026-03-20 --format csv
+  $ pe audit verify                            Verify hash chain integrity
+  $ pe audit alerts --webhook https://hooks.example.com/audit
+  $ pe audit siem --endpoint https://siem.example.com/ingest
+`)
+    .action(() => { cmd.outputHelp(); });
+
+  cmd
+    .command('export')
+    .description('export audit log')
+    .option('--format <json|csv>', 'output format', 'json')
+    .option('--from <date>', 'start date (ISO format)')
+    .option('--to <date>', 'end date (ISO format)')
+    .option('-o, --output <path>', 'output file path')
+    .action(async (opts) => {
+      try {
+        const extConfig = (await import('../utils/config.js')).default;
+        const store = extConfig.get('ext_store.advanced-audit') || {};
+        let entries = store.auditLog || [];
+
+        if (opts.from) {
+          const fromDate = new Date(opts.from).getTime();
+          entries = entries.filter(e => new Date(e.timestamp).getTime() >= fromDate);
+        }
+        if (opts.to) {
+          const toDate = new Date(opts.to).getTime();
+          entries = entries.filter(e => new Date(e.timestamp).getTime() <= toDate);
+        }
+
+        if (!entries.length) {
+          console.log(chalk.gray('No audit log entries found.'));
+          return;
+        }
+
+        let output;
+        if (opts.format === 'csv') {
+          const header = 'id,timestamp,action,user,details,hash';
+          const rows = entries.map(e =>
+            `${e.id},${e.timestamp},${e.action},${e.user},"${JSON.stringify(e.details).replace(/"/g, '""')}",${e.hash}`
+          );
+          output = [header, ...rows].join('\n');
+        } else {
+          output = JSON.stringify(entries, null, 2);
+        }
+
+        if (opts.output) {
+          const validatedPath = validateOutputPath(opts.output);
+          const fs = await import('fs');
+          fs.writeFileSync(validatedPath, output, 'utf8');
+          console.log(chalk.green(`✔ Exported ${entries.length} entries to ${validatedPath}`));
+        } else {
+          console.log(output);
+        }
+      } catch (err) {
+        console.error(chalk.red(`Export failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  cmd
+    .command('verify')
+    .description('verify hash chain integrity of audit log')
+    .action(async () => {
+      try {
+        const extConfig = (await import('../utils/config.js')).default;
+        const store = extConfig.get('ext_store.advanced-audit') || {};
+        const entries = store.auditLog || [];
+
+        if (!entries.length) {
+          console.log(chalk.gray('No audit log entries to verify.'));
+          return;
+        }
+
+        let valid = true;
+        let checked = 0;
+
+        for (let i = 0; i < entries.length; i++) {
+          const entry = entries[i];
+          const previousHash = entry.previousHash || '';
+          const data = `${entry.timestamp}${entry.action}${entry.user}${JSON.stringify(entry.details)}${previousHash}`;
+          const expectedHash = createHash('sha256').update(data).digest('hex');
+
+          if (entry.hash !== expectedHash) {
+            console.log(chalk.red(`✘ Entry ${i} (${entry.id}) hash mismatch`));
+            console.log(chalk.red(`  Expected: ${expectedHash}`));
+            console.log(chalk.red(`  Got:      ${entry.hash}`));
+            valid = false;
+          }
+
+          if (i > 0 && entry.previousHash !== entries[i - 1].hash) {
+            console.log(chalk.red(`✘ Entry ${i} (${entry.id}) chain broken — previousHash does not match`));
+            valid = false;
+          }
+
+          checked++;
+        }
+
+        if (valid) {
+          console.log(chalk.green(`✔ Audit log integrity verified (${checked} entries)`));
+        } else {
+          console.log(chalk.red(`✘ Audit log integrity check FAILED`));
+          process.exitCode = 1;
+        }
+      } catch (err) {
+        console.error(chalk.red(`Verify failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  cmd
+    .command('alerts')
+    .description('configure real-time alerts')
+    .option('--webhook <url>', 'set alert webhook URL')
+    .option('--disable', 'disable alerts')
+    .action(async (opts) => {
+      try {
+        const extConfig = (await import('../utils/config.js')).default;
+        const config = extConfig.get('ext.advanced-audit') || {};
+
+        if (opts.disable) {
+          config.realTimeAlerts = false;
+          config.alertWebhook = null;
+          extConfig.set('ext.advanced-audit', config);
+          console.log(chalk.green('✔ Real-time alerts disabled'));
+          return;
+        }
+
+        if (opts.webhook) {
+          validateWebhookUrl(opts.webhook);
+          config.realTimeAlerts = true;
+          config.alertWebhook = opts.webhook;
+          extConfig.set('ext.advanced-audit', config);
+          console.log(chalk.green('✔ Real-time alerts enabled'));
+          console.log(`  Webhook: ${chalk.white(opts.webhook)}`);
+          return;
+        }
+
+        console.log('');
+        console.log(chalk.cyan.bold('Alert Configuration'));
+        console.log(chalk.gray('─'.repeat(40)));
+        console.log(`  Enabled: ${config.realTimeAlerts ? chalk.green('yes') : chalk.red('no')}`);
+        console.log(`  Webhook: ${config.alertWebhook ? chalk.white(config.alertWebhook) : chalk.gray('not set')}`);
+        console.log('');
+      } catch (err) {
+        console.error(chalk.red(`Alerts failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  cmd
+    .command('siem')
+    .description('configure SIEM forwarding')
+    .option('--endpoint <url>', 'set SIEM endpoint')
+    .option('--disable', 'disable SIEM forwarding')
+    .action(async (opts) => {
+      try {
+        const extConfig = (await import('../utils/config.js')).default;
+        const config = extConfig.get('ext.advanced-audit') || {};
+
+        if (opts.disable) {
+          config.siem = false;
+          config.siemEndpoint = null;
+          extConfig.set('ext.advanced-audit', config);
+          console.log(chalk.green('✔ SIEM forwarding disabled'));
+          return;
+        }
+
+        if (opts.endpoint) {
+          validateWebhookUrl(opts.endpoint);
+          config.siem = true;
+          config.siemEndpoint = opts.endpoint;
+          extConfig.set('ext.advanced-audit', config);
+          console.log(chalk.green('✔ SIEM forwarding enabled'));
+          console.log(`  Endpoint: ${chalk.white(opts.endpoint)}`);
+          return;
+        }
+
+        console.log('');
+        console.log(chalk.cyan.bold('SIEM Configuration'));
+        console.log(chalk.gray('─'.repeat(40)));
+        console.log(`  Enabled:  ${config.siem ? chalk.green('yes') : chalk.red('no')}`);
+        console.log(`  Endpoint: ${config.siemEndpoint ? chalk.white(config.siemEndpoint) : chalk.gray('not set')}`);
+        console.log('');
+      } catch (err) {
+        console.error(chalk.red(`SIEM failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+}

package/lib/commands/auth.js

@@ -0,0 +1,137 @@
+import chalk from 'chalk';
+import readline from 'readline';
+import { getExtension, loadExtension, deployBundledExtensions, BUNDLED_DIR } from '../core/extensions.js';
+import path from 'path';
+import fs from 'fs';
+
+export default function authCommand(program) {
+  const auth = program
+    .command('auth')
+    .description('manage account linking and identity verification');
+
+  auth
+    .command('login [email]')
+    .description('login with email OTP to link your account')
+    .action(async (email) => {
+      // 1. Ensure extension is loaded
+      let ext = getExtension('@palexplorer/auth-email');
+      if (!ext) {
+        console.log(chalk.blue('Loading auth-email extension...'));
+        deployBundledExtensions();
+        const appDir = path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, '$1'));
+        const extPath = path.resolve(appDir, '../../extensions/@palexplorer/auth-email');
+        const manifest = JSON.parse(fs.readFileSync(path.join(extPath, 'extension.json'), 'utf8'));
+        await loadExtension(extPath, { ...manifest, bundled: true });
+        ext = getExtension('@palexplorer/auth-email');
+      }
+
+      if (!ext || !ext.ctx?.auth) {
+        console.log(chalk.red('Error: auth-email extension not available.'));
+        process.exitCode = 1;
+        return;
+      }
+
+      const authExt = ext.ctx.auth;
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+      const ask = (q) => new Promise(r => rl.question(q, r));
+
+      try {
+        let targetEmail = email;
+        if (!targetEmail) {
+          targetEmail = await ask('Enter your email address: ');
+        }
+
+        if (!targetEmail || !targetEmail.includes('@')) {
+          console.log(chalk.red('Invalid email address.'));
+          rl.close();
+          process.exitCode = 1;
+          return;
+        }
+
+        console.log(chalk.blue(`Sending verification code to ${targetEmail}...`));
+        await authExt.requestVerificationCode(targetEmail);
+        console.log(chalk.green('✔ Code sent! Please check your inbox.'));
+
+        const code = await ask('Enter the 6-digit code: ');
+        if (!code || code.length !== 6) {
+          console.log(chalk.red('Invalid code format.'));
+          rl.close();
+          process.exitCode = 1;
+          return;
+        }
+
+        console.log(chalk.blue('Verifying...'));
+        await authExt.confirmCode(targetEmail, code);
+        console.log(chalk.green(`✔ Email ${targetEmail} verified successfully!`));
+
+        console.log(chalk.blue('Linking your Palexplorer identity...'));
+        await authExt.linkIdentity();
+        console.log(chalk.green('✔ Identity linked! You now have a verified badge.'));
+
+        rl.close();
+      } catch (err) {
+        rl.close();
+        console.log(chalk.red(`Login failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  auth
+    .command('google')
+    .description('link your account using Google')
+    .action(async () => {
+      const { getIdentity } = await import('../core/identity.js');
+      const { getPrimaryServer } = await import('../core/discoveryClient.js');
+      const identity = await getIdentity();
+      if (!identity?.publicKey) {
+        console.log(chalk.red('No identity found. Run `pe init` first.'));
+        process.exitCode = 1; return;
+      }
+      const baseUrl = getPrimaryServer();
+      const returnUrl = encodeURIComponent('palexplorer://auth-callback');
+      const url = `${baseUrl}/auth/google?publicKey=${encodeURIComponent(identity.publicKey)}&return_url=${returnUrl}`;
+      console.log(chalk.blue('Opening browser for Google login...'));
+      console.log(chalk.gray(`URL: ${url}`));
+      const { default: open } = await import('open');
+      await open(url);
+    });
+
+  auth
+    .command('github')
+    .description('link your account using GitHub')
+    .action(async () => {
+      const { getIdentity } = await import('../core/identity.js');
+      const { getPrimaryServer } = await import('../core/discoveryClient.js');
+      const identity = await getIdentity();
+      if (!identity?.publicKey) {
+        console.log(chalk.red('No identity found. Run `pe init` first.'));
+        process.exitCode = 1; return;
+      }
+      const baseUrl = getPrimaryServer();
+      const returnUrl = encodeURIComponent('palexplorer://auth-callback');
+      const url = `${baseUrl}/auth/github?publicKey=${encodeURIComponent(identity.publicKey)}&return_url=${returnUrl}`;
+      console.log(chalk.blue('Opening browser for GitHub login...'));
+      console.log(chalk.gray(`URL: ${url}`));
+      const { default: open } = await import('open');
+      await open(url);
+    });
+
+  auth
+    .command('status')
+    .description('show current authentication status')
+    .action(async () => {
+      let ext = getExtension('@palexplorer/auth-email');
+      if (!ext || !ext.ctx?.config) {
+        console.log(chalk.gray('Authentication extension not loaded.'));
+        return;
+      }
+
+      const verifiedEmail = ext.ctx.config.get('verifiedEmail');
+      if (verifiedEmail) {
+        console.log(chalk.green(`✔ Verified: ${verifiedEmail}`));
+        console.log(chalk.gray(`  Token: ${ext.ctx.config.get('verifiedToken').slice(0, 32)}...`));
+      } else {
+        console.log(chalk.yellow('! Not verified. Run `pe auth login` to link an email.'));
+      }
+    });
+}

package/lib/commands/backup.js

@@ -0,0 +1,76 @@
+import chalk from 'chalk';
+import fs from 'fs';
+import path from 'path';
+import { createBackup, restoreBackup } from '../core/backup.js';
+
+export default function backupCommand(program) {
+  const cmd = program
+    .command('backup')
+    .description('create and restore encrypted backups (Pro)')
+    .addHelpText('after', `
+Examples:
+  $ pe backup create                          Create backup (prompted for password)
+  $ pe backup create --password "s3cret"      Create with password
+  $ pe backup create -o ~/backup.json         Custom output path
+  $ pe backup restore ./palexplorer-backup.json
+`)
+    .action(() => {
+      cmd.outputHelp();
+    });
+
+  cmd
+    .command('create')
+    .description('create an encrypted backup of identity, shares, pals, and settings')
+    .option('-o, --output <path>', 'Output file path')
+    .option('-p, --password <password>', 'Encryption password')
+    .action(async (opts) => {
+      try {
+        const password = opts.password || process.env.PE_BACKUP_PASSWORD;
+        if (!password) {
+          console.log(chalk.red('Password required. Use --password or PE_BACKUP_PASSWORD env var.'));
+          process.exitCode = 1;
+          return;
+        }
+
+        const backupData = await createBackup(password);
+        const outPath = opts.output || `palexplorer-backup-${new Date().toISOString().slice(0, 10)}.json`;
+        const resolved = path.resolve(outPath);
+        fs.writeFileSync(resolved, backupData, 'utf8');
+        console.log(chalk.green(`✔ Backup created: ${resolved}`));
+      } catch (err) {
+        console.log(chalk.red(`Backup failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  cmd
+    .command('restore <file>')
+    .description('restore from an encrypted backup file')
+    .option('-p, --password <password>', 'Decryption password')
+    .action(async (file, opts) => {
+      try {
+        const resolved = path.resolve(file);
+        if (!fs.existsSync(resolved)) {
+          console.log(chalk.red(`File not found: ${resolved}`));
+          process.exitCode = 1;
+          return;
+        }
+
+        const password = opts.password || process.env.PE_BACKUP_PASSWORD;
+        if (!password) {
+          console.log(chalk.red('Password required. Use --password or PE_BACKUP_PASSWORD env var.'));
+          process.exitCode = 1;
+          return;
+        }
+
+        const data = fs.readFileSync(resolved, 'utf8');
+        const result = await restoreBackup(data, password);
+        console.log(chalk.green('✔ Backup restored successfully.'));
+        if (result.sharesRestored) console.log(`  Shares: ${chalk.white(result.sharesRestored)}`);
+        if (result.palsRestored) console.log(`  Pals: ${chalk.white(result.palsRestored)}`);
+      } catch (err) {
+        console.log(chalk.red(`Restore failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+}