carom-link 1.0.0

package/src/cli/commands/stats.js

@@ -0,0 +1,86 @@
+import chalk from 'chalk';
+import { getDb, findLinkByIdOrSlug, getClickStats } from '../../db.js';
+import { formatTable, formatClassification, formatDate, printError, printInfo, truncate } from '../formatters.js';
+
+/**
+ * Register the `stats` command.
+ */
+export function registerStatsCommand(program) {
+  program
+    .command('stats <idOrSlug>')
+    .description('Show detailed click analytics for a link')
+    .option('--json', 'Output as JSON')
+    .action(async (idOrSlug, options) => {
+      try {
+        const dataDir = program.opts().dataDir;
+        const db = getDb(dataDir);
+
+        const link = findLinkByIdOrSlug(db, idOrSlug);
+        if (!link) {
+          printError(`Link "${idOrSlug}" not found.`);
+          process.exit(1);
+        }
+
+        const stats = getClickStats(db, link.id);
+
+        if (options.json) {
+          console.log(JSON.stringify({ link, stats }, null, 2));
+          process.exit(0);
+        }
+
+        // Header
+        console.log('');
+        console.log(chalk.bold.cyan(`  Link: /${link.slug}`));
+        console.log(chalk.dim(`  Target: ${link.destination_url}`));
+        console.log(chalk.dim(`  Created: ${formatDate(link.created_at)}`));
+        console.log('');
+
+        // Click summary
+        console.log(chalk.bold('  Click Summary'));
+        console.log(chalk.dim('  ─────────────'));
+        console.log(`  Total:      ${chalk.bold(stats.totals.total)}`);
+        console.log(`  Human:      ${chalk.green(stats.totals.human || 0)}`);
+        console.log(`  Bot:        ${chalk.red(stats.totals.bot || 0)}`);
+        console.log(`  Suspicious: ${chalk.yellow(stats.totals.suspicious || 0)}`);
+        console.log('');
+
+        // Timeline
+        console.log(chalk.bold('  Timeline'));
+        console.log(chalk.dim('  ────────'));
+        console.log(`  Last 24h:   ${stats.timeline.last24h}`);
+        console.log(`  Last 7d:    ${stats.timeline.last7d}`);
+        console.log(`  Last 30d:   ${stats.timeline.last30d}`);
+        console.log('');
+
+        // Top user agents
+        if (stats.topUserAgents.length > 0) {
+          console.log(chalk.bold('  Top User Agents'));
+          const uaHeaders = ['USER AGENT', 'TYPE', 'COUNT'];
+          const uaRows = stats.topUserAgents.map(r => [
+            truncate(r.user_agent || '(empty)', 50),
+            formatClassification(r.classification),
+            r.count,
+          ]);
+          console.log(formatTable(uaHeaders, uaRows));
+          console.log('');
+        }
+
+        // Top bot signals
+        if (stats.topSignals.length > 0) {
+          console.log(chalk.bold('  Top Bot Signals'));
+          const sigHeaders = ['SIGNALS', 'COUNT'];
+          const sigRows = stats.topSignals.map(r => [
+            r.bot_signals || '—',
+            r.count,
+          ]);
+          console.log(formatTable(sigHeaders, sigRows));
+          console.log('');
+        }
+
+        process.exit(0);
+      } catch (err) {
+        printError(err.message);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/status.js

@@ -0,0 +1,89 @@
+import chalk from 'chalk';
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { loadConfig } from '../../config.js';
+import { getDb, getLinkCount } from '../../db.js';
+import { getServiceStatus, isServiceInstalled, getServiceType } from '../../service/manager.js';
+import { DEFAULT_DATA_DIR, PID_FILENAME } from '../../constants.js';
+import { printInfo, printError } from '../formatters.js';
+
+/**
+ * Register the `status` command.
+ */
+export function registerStatusCommand(program) {
+  program
+    .command('status')
+    .description('Show carom server status')
+    .action(async () => {
+      try {
+        const dataDir = program.opts().dataDir || DEFAULT_DATA_DIR;
+        const config = loadConfig(dataDir);
+
+        console.log('');
+        console.log(chalk.bold.cyan('  carom Status'));
+        console.log('');
+
+        // Check PID file
+        const pidPath = join(dataDir, PID_FILENAME);
+        let pidRunning = false;
+        let pid = null;
+
+        if (existsSync(pidPath)) {
+          pid = parseInt(readFileSync(pidPath, 'utf8').trim(), 10);
+          try {
+            process.kill(pid, 0); // Test if process exists
+            pidRunning = true;
+          } catch {
+            pidRunning = false;
+          }
+        }
+
+        // Check service status
+        const serviceStatus = await getServiceStatus();
+
+        const running = pidRunning || serviceStatus.running;
+        const displayPid = serviceStatus.pid || pid;
+
+        if (running) {
+          console.log(`  ${chalk.green('●')} ${chalk.bold('carom is running')} ${displayPid ? chalk.dim(`(PID ${displayPid})`) : ''}`);
+        } else {
+          console.log(`  ${chalk.red('●')} ${chalk.bold('carom is not running')}`);
+        }
+
+        console.log(`  ${chalk.dim('Port:')}      ${config.port}`);
+        console.log(`  ${chalk.dim('Host:')}      ${config.host}`);
+        console.log(`  ${chalk.dim('Protection:')}  ${config.shield?.enabled ? chalk.green('ON') : chalk.red('OFF')}`);
+        console.log(`  ${chalk.dim('API Key:')}   ${config.apiKey ? chalk.green('SET') : chalk.yellow('NOT SET')}`);
+
+        // Link count
+        try {
+          const db = getDb(dataDir);
+          const count = getLinkCount(db);
+          console.log(`  ${chalk.dim('Links:')}     ${count}`);
+        } catch {
+          console.log(`  ${chalk.dim('Links:')}     ${chalk.dim('(DB not accessible)')}`);
+        }
+
+        // Service info
+        console.log('');
+        const serviceType = getServiceType();
+        if (serviceStatus.installed) {
+          console.log(`  ${chalk.dim('Service:')}   ${chalk.green('Installed')} (${serviceType})`);
+          console.log(`  ${chalk.dim('Auto-start:')} ${chalk.green('Yes (survives reboots)')}`);
+          if (serviceStatus.path) {
+            console.log(`  ${chalk.dim('Config:')}    ${serviceStatus.path}`);
+          }
+        } else {
+          console.log(`  ${chalk.dim('Service:')}   ${chalk.dim('Not installed')}`);
+          console.log(`  ${chalk.dim('Auto-start:')} ${chalk.dim('No')}`);
+          printInfo(`Run ${chalk.bold('carom install')} to auto-start on boot.`);
+        }
+
+        console.log('');
+        process.exit(0);
+      } catch (err) {
+        printError(err.message);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/uninstall.js

@@ -0,0 +1,28 @@
+import { uninstallService, isServiceInstalled } from '../../service/manager.js';
+import { printSuccess, printError, printInfo } from '../formatters.js';
+
+/**
+ * Register the `uninstall` command.
+ */
+export function registerUninstallCommand(program) {
+  program
+    .command('uninstall')
+    .description('Remove the carom system service')
+    .action(async () => {
+      try {
+        if (!isServiceInstalled()) {
+          printError('carom service is not installed.');
+          process.exit(1);
+        }
+
+        const result = await uninstallService();
+        printSuccess(result.message);
+        printInfo('Your data (database, config, logs) has been preserved in ~/.carom/');
+
+        process.exit(0);
+      } catch (err) {
+        printError(err.message);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/formatters.js

@@ -0,0 +1,132 @@
+import chalk from 'chalk';
+
+/**
+ * Format a table for terminal output.
+ */
+export function formatTable(headers, rows) {
+  if (rows.length === 0) {
+    return chalk.dim('  No results.');
+  }
+
+  // Calculate column widths
+  const widths = headers.map((h, i) => {
+    const maxData = rows.reduce((max, row) => Math.max(max, String(row[i] ?? '').length), 0);
+    return Math.max(h.length, maxData);
+  });
+
+  // Header row
+  const headerLine = headers.map((h, i) => chalk.bold.cyan(h.padEnd(widths[i]))).join('  ');
+  const separator = widths.map(w => chalk.dim('─'.repeat(w))).join('──');
+
+  // Data rows
+  const dataLines = rows.map(row =>
+    row.map((cell, i) => {
+      const str = String(cell ?? '');
+      return str.padEnd(widths[i]);
+    }).join('  ')
+  );
+
+  return [headerLine, separator, ...dataLines].join('\n');
+}
+
+/**
+ * Truncate a string to a max length.
+ */
+export function truncate(str, maxLen = 40) {
+  if (!str) return '';
+  if (str.length <= maxLen) return str;
+  return str.substring(0, maxLen - 1) + '…';
+}
+
+/**
+ * Format a click count with human/bot breakdown.
+ */
+export function formatClicks(human, bot) {
+  const h = chalk.green(String(human || 0));
+  const b = chalk.red(String(bot || 0));
+  return `${h}/${b}`;
+}
+
+/**
+ * Format an active/inactive status badge.
+ */
+export function formatStatus(active) {
+  return active ? chalk.green('✓ active') : chalk.dim('✗ inactive');
+}
+
+/**
+ * Format a classification badge.
+ */
+export function formatClassification(classification) {
+  switch (classification) {
+    case 'human': return chalk.green('👤 human');
+    case 'bot': return chalk.red('🛡 bot');
+    case 'suspicious': return chalk.yellow('⚠ suspicious');
+    default: return chalk.dim(classification || 'unknown');
+  }
+}
+
+/**
+ * Print a banner for server startup.
+ */
+export function printBanner(config, linkCount) {
+  const adminPort = config.adminPort || 3001;
+  const lines = [
+    '',
+    chalk.bold.cyan('  ╔═══════════════════════════════════╗'),
+    chalk.bold.cyan('  ║') + chalk.bold.white('          carom v1.0.0          ') + chalk.bold.cyan('║'),
+    chalk.bold.cyan('  ╚═══════════════════════════════════╝'),
+    '',
+    `  ${chalk.dim('Redirects:')}  ${chalk.white(`http://${config.host}:${config.port}`)}`,
+    `  ${chalk.dim('Admin:')}      ${chalk.white(`http://${config.host}:${adminPort}`)}`,
+    `  ${chalk.dim('API:')}        ${chalk.white(`http://${config.host}:${adminPort}/api`)}`,
+    `  ${chalk.dim('Links:')}      ${chalk.white(linkCount)}`,
+    `  ${chalk.dim('Protection:')} ${config.shield?.enabled ? chalk.green('ON') + chalk.dim(` (threshold: ${config.shield.threshold}, mode: ${config.shield.mode})`) : chalk.red('OFF')}`,
+    `  ${chalk.dim('API Key:')}    ${config.apiKey ? chalk.green('SET') : chalk.yellow('NOT SET (open access)')}`,
+    '',
+    chalk.dim('  Press Ctrl+C to stop.'),
+    '',
+  ];
+  console.log(lines.join('\n'));
+}
+
+/**
+ * Print a success message.
+ */
+export function printSuccess(message) {
+  console.log(chalk.green('✓') + ' ' + message);
+}
+
+/**
+ * Print an error message.
+ */
+export function printError(message) {
+  console.error(chalk.red('✗') + ' ' + message);
+}
+
+/**
+ * Print a warning message.
+ */
+export function printWarning(message) {
+  console.log(chalk.yellow('⚠') + ' ' + message);
+}
+
+/**
+ * Print an info message.
+ */
+export function printInfo(message) {
+  console.log(chalk.blue('ℹ') + ' ' + message);
+}
+
+/**
+ * Format a date string for display.
+ */
+export function formatDate(dateStr) {
+  if (!dateStr) return chalk.dim('—');
+  try {
+    const d = new Date(dateStr);
+    return d.toLocaleDateString() + ' ' + d.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+  } catch {
+    return dateStr;
+  }
+}

package/src/cli/index.js

@@ -0,0 +1,45 @@
+import { Command } from 'commander';
+import { VERSION, PACKAGE_NAME, DEFAULT_DATA_DIR } from '../constants.js';
+import { setConfigDir } from '../config.js';
+import { registerStartCommand } from './commands/start.js';
+import { registerAddCommand } from './commands/add.js';
+import { registerListCommand } from './commands/list.js';
+import { registerRemoveCommand } from './commands/remove.js';
+import { registerStatsCommand } from './commands/stats.js';
+import { registerRulesCommand } from './commands/rules.js';
+import { registerConfigCommand } from './commands/config.js';
+import { registerInstallCommand } from './commands/install.js';
+import { registerUninstallCommand } from './commands/uninstall.js';
+import { registerStatusCommand } from './commands/status.js';
+import { registerLogsCommand } from './commands/logs.js';
+
+const program = new Command();
+
+program
+  .name(PACKAGE_NAME)
+  .description('Link redirect server with bot and automated traffic protection')
+  .version(VERSION)
+  .option('--data-dir <path>', `Data directory (default: ${DEFAULT_DATA_DIR})`, DEFAULT_DATA_DIR)
+  .option('-v, --verbose', 'Verbose logging')
+  .hook('preAction', (thisCommand) => {
+    const opts = thisCommand.opts();
+    if (opts.dataDir) {
+      setConfigDir(opts.dataDir);
+    }
+  });
+
+// Register all commands
+registerStartCommand(program);
+registerAddCommand(program);
+registerListCommand(program);
+registerRemoveCommand(program);
+registerStatsCommand(program);
+registerRulesCommand(program);
+registerConfigCommand(program);
+registerInstallCommand(program);
+registerUninstallCommand(program);
+registerStatusCommand(program);
+registerLogsCommand(program);
+
+// Parse CLI arguments
+program.parse();

package/src/cloak/detector.js

@@ -0,0 +1,243 @@
+import { BOT_UA_PATTERNS } from './patterns.js';
+import { lookupIp, getClientIp } from './ipLookup.js';
+import { validateToken } from './tokens.js';
+import { trackVelocity, getRules } from '../db.js';
+import { VELOCITY_THRESHOLD, TIMING_FAST_THRESHOLD_MS } from '../constants.js';
+
+/**
+ * Score a request for bot likelihood.
+ *
+ * @param {object} req - Express request object
+ * @param {object} options
+ * @param {Date|string} options.linkCreatedAt - When the link was created
+ * @param {string} options.slug - The link slug
+ * @param {object} options.config - Shield config
+ * @param {object} options.db - Database connection (for custom rules)
+ * @returns {Promise<{ score, signals, isBot, classification }>}
+ */
+export async function scoreRequest(req, { linkCreatedAt, slug, config, db }) {
+  const signals = [];
+  let score = 0;
+  const threshold = config?.shield?.threshold || 40;
+
+  const ua = (req.headers['user-agent'] || '').toLowerCase();
+  const ip = getClientIp(req);
+
+  // ── 1. Check for valid JS challenge token (bypass all checks) ──
+  const token = req.query?._t;
+  if (token && validateToken(slug, token)) {
+    return {
+      score: 0,
+      signals: [{ name: 'valid_token', weight: 0, detail: 'JS challenge passed' }],
+      isBot: false,
+      classification: 'human',
+    };
+  }
+
+  // ── 2. User-Agent pattern matching ──
+  if (!ua || ua.length === 0) {
+    score += 15;
+    signals.push({ name: 'ua_missing', weight: 15, detail: 'No User-Agent header' });
+  } else {
+    // Check built-in patterns
+    for (const pattern of BOT_UA_PATTERNS) {
+      if (ua.includes(pattern)) {
+        score += 30;
+        signals.push({ name: 'ua_pattern', weight: 30, detail: `Matched: "${pattern}"` });
+        break; // Only count once for built-in patterns
+      }
+    }
+
+    // Check custom rules from DB
+    if (db) {
+      try {
+        const customRules = getRules(db);
+        for (const rule of customRules) {
+          if (rule.type === 'ua_pattern' && ua.includes(rule.pattern.toLowerCase())) {
+            const w = rule.weight || 30;
+            score += w;
+            signals.push({ name: 'custom_ua_pattern', weight: w, detail: `Custom rule: "${rule.pattern}"` });
+            break;
+          }
+        }
+      } catch {
+        // DB not available, skip custom rules
+      }
+    }
+  }
+
+  // ── 3. Header analysis ──
+  const suspiciousHeaders = analyzeHeaders(req);
+  if (suspiciousHeaders.length > 0) {
+    score += 20;
+    signals.push({
+      name: 'headers_suspicious',
+      weight: 20,
+      detail: suspiciousHeaders.join('; '),
+    });
+  }
+
+  // ── 4. IP / Datacenter check (async) ──
+  try {
+    const ipInfo = await lookupIp(ip);
+    if (ipInfo?.isDatacenter) {
+      score += 25;
+      signals.push({
+        name: 'datacenter_ip',
+        weight: 25,
+        detail: `ASN: ${ipInfo.asn || 'unknown'}, Org: ${ipInfo.org || 'unknown'}`,
+      });
+    }
+
+    // Check custom ASN rules
+    if (db && ipInfo?.asn) {
+      try {
+        const customRules = getRules(db);
+        for (const rule of customRules) {
+          if (rule.type === 'asn' && parseInt(rule.pattern, 10) === ipInfo.asn) {
+            const w = rule.weight || 25;
+            score += w;
+            signals.push({ name: 'custom_asn', weight: w, detail: `Custom ASN rule: ${rule.pattern}` });
+            break;
+          }
+        }
+      } catch {
+        // Skip
+      }
+    }
+  } catch {
+    // IP lookup failed — fail open, don't penalize
+  }
+
+  // ── 5. Timing analysis ──
+  if (linkCreatedAt) {
+    const createdMs = new Date(linkCreatedAt).getTime();
+    const elapsed = Date.now() - createdMs;
+    if (elapsed < TIMING_FAST_THRESHOLD_MS) {
+      score += 15;
+      signals.push({
+        name: 'timing_fast',
+        weight: 15,
+        detail: `Click ${elapsed}ms after link creation (threshold: ${TIMING_FAST_THRESHOLD_MS}ms)`,
+      });
+    }
+  }
+
+  // ── 6. Velocity check ──
+  if (slug) {
+    const hitCount = trackVelocity(slug);
+    if (hitCount >= VELOCITY_THRESHOLD) {
+      score += 15;
+      signals.push({
+        name: 'velocity_high',
+        weight: 15,
+        detail: `${hitCount} hits in 10s window (threshold: ${VELOCITY_THRESHOLD})`,
+      });
+    }
+  }
+
+  // ── Classification ──
+  let classification;
+  if (score >= threshold) {
+    classification = 'bot';
+  } else if (score >= 20) {
+    classification = 'suspicious';
+  } else {
+    classification = 'human';
+  }
+
+  return {
+    score,
+    signals,
+    isBot: classification === 'bot',
+    classification,
+  };
+}
+
+/**
+ * Analyze request headers for bot-like characteristics.
+ */
+function analyzeHeaders(req) {
+  const issues = [];
+  const headers = req.headers;
+
+  // Most real browsers send Accept-Language
+  if (!headers['accept-language']) {
+    issues.push('Missing Accept-Language');
+  }
+
+  // Real browsers typically send a complex Accept header
+  const accept = headers['accept'] || '';
+  if (accept && !accept.includes('text/html') && !accept.includes('*/*')) {
+    issues.push('Unusual Accept header');
+  }
+
+  // Real browsers send Accept-Encoding
+  if (!headers['accept-encoding']) {
+    issues.push('Missing Accept-Encoding');
+  }
+
+  // Check for very short or very generic UA
+  const ua = headers['user-agent'] || '';
+  if (ua && ua.length < 20) {
+    issues.push(`Very short User-Agent (${ua.length} chars)`);
+  }
+
+  // Check for connection: close (many bots do this)
+  if (headers['connection'] === 'close' && !headers['accept-language']) {
+    issues.push('Connection: close without Accept-Language');
+  }
+
+  return issues;
+}
+
+/**
+ * Test a user-agent string against the detection engine.
+ * Used by the CLI `rules test` command.
+ * Returns a simulated score result.
+ */
+export function testUserAgent(userAgent, db) {
+  const signals = [];
+  let score = 0;
+  const ua = (userAgent || '').toLowerCase();
+
+  if (!ua || ua.length === 0) {
+    score += 15;
+    signals.push({ name: 'ua_missing', weight: 15, detail: 'No User-Agent provided' });
+  } else {
+    for (const pattern of BOT_UA_PATTERNS) {
+      if (ua.includes(pattern)) {
+        score += 30;
+        signals.push({ name: 'ua_pattern', weight: 30, detail: `Matched built-in: "${pattern}"` });
+        break;
+      }
+    }
+
+    // Custom rules
+    if (db) {
+      try {
+        const customRules = getRules(db);
+        for (const rule of customRules) {
+          if (rule.type === 'ua_pattern' && ua.includes(rule.pattern.toLowerCase())) {
+            const w = rule.weight || 30;
+            score += w;
+            signals.push({ name: 'custom_ua_pattern', weight: w, detail: `Custom rule: "${rule.pattern}"` });
+            break;
+          }
+        }
+      } catch {
+        // Skip
+      }
+    }
+  }
+
+  // Note: can't test headers, IP, timing, or velocity in offline mode
+  signals.push({ name: 'note', weight: 0, detail: 'Header, IP, timing, and velocity checks only run on live requests' });
+
+  return {
+    score,
+    signals: signals.filter(s => s.weight > 0 || s.name === 'note'),
+    isBot: score >= 40,
+    classification: score >= 40 ? 'bot' : score >= 20 ? 'suspicious' : 'human',
+  };
+}