carom-link 1.0.0

package/src/server/routes/redirect.js

@@ -0,0 +1,141 @@
+import { Router } from 'express';
+import { createHash } from 'crypto';
+import { findBySlug, logClick } from '../../db.js';
+import { scoreRequest } from '../../cloak/detector.js';
+import { generateToken } from '../../cloak/tokens.js';
+import { generateSafePage, generateInterstitialPage } from '../../cloak/safePage.js';
+import { getClientIp } from '../../cloak/ipLookup.js';
+
+/**
+ * Create the redirect router.
+ */
+export function createRedirectRouter(config, db) {
+  const router = Router();
+
+  router.get('/:slug', async (req, res) => {
+    try {
+      const { slug } = req.params;
+
+      // Skip favicon and other common paths
+      if (slug === 'favicon.ico' || slug === 'robots.txt' || slug === 'sitemap.xml') {
+        return res.status(404).end();
+      }
+
+      // Look up the link
+      const link = findBySlug(db, slug);
+      if (!link) {
+        return res.status(404).json({ error: 'Link not found' });
+      }
+
+      // Check expiration
+      if (link.expires_at && new Date(link.expires_at) < new Date()) {
+        return res.status(410).json({ error: 'Link has expired' });
+      }
+
+      const ip = getClientIp(req);
+      const ipHash = createHash('sha256').update(ip + 'carom-salt').digest('hex').substring(0, 16);
+      const userAgent = req.headers['user-agent'] || '';
+      const referer = req.headers['referer'] || '';
+
+      // ── Safe page request (from interstitial fallback) ──
+      if (req.query._safe === '1') {
+        logClick(db, {
+          linkId: link.id,
+          userAgent,
+          ipHash,
+          referer,
+          isBot: true,
+          botScore: 100,
+          botSignals: ['interstitial_fallback'],
+          classification: 'bot',
+        });
+
+        const html = generateSafePage({
+          title: config.shield?.safePage?.title,
+          description: config.shield?.safePage?.description,
+          brand: config.shield?.safePage?.brand,
+          url: `/${slug}`,
+        });
+        return res.status(200).type('html').send(html);
+      }
+
+      // ── Bot protection disabled — straight redirect ──
+      if (!config.shield?.enabled) {
+        logClick(db, {
+          linkId: link.id,
+          userAgent,
+          ipHash,
+          referer,
+          isBot: false,
+          botScore: 0,
+          botSignals: [],
+          classification: 'human',
+        });
+        return res.redirect(301, link.destination_url);
+      }
+
+      // ── Run the bot detection engine ──
+      const result = await scoreRequest(req, {
+        linkCreatedAt: link.created_at,
+        slug,
+        config,
+        db,
+      });
+
+      // Log the click
+      logClick(db, {
+        linkId: link.id,
+        userAgent,
+        ipHash,
+        referer,
+        isBot: result.isBot,
+        botScore: result.score,
+        botSignals: result.signals.map(s => s.name),
+        classification: result.classification,
+      });
+
+      // ── Bot detected — serve safe page ──
+      if (result.isBot) {
+        if (config.verbose) {
+          console.log(`[carom] 🛡 BOT  GET /${slug} score=${result.score} ua="${userAgent.substring(0, 60)}" → safe page`);
+        }
+
+        const html = generateSafePage({
+          title: config.shield?.safePage?.title,
+          description: config.shield?.safePage?.description,
+          brand: config.shield?.safePage?.brand,
+          url: `/${slug}`,
+        });
+        return res.status(200).type('html').send(html);
+      }
+
+      // ── Interstitial mode — serve JS challenge ──
+      if (config.shield?.mode === 'interstitial' && !req.query._t) {
+        if (config.verbose) {
+          console.log(`[carom] 🔒 CHALLENGE GET /${slug} score=${result.score} → interstitial`);
+        }
+
+        const token = generateToken(slug);
+        const html = generateInterstitialPage({
+          slug,
+          token,
+          destinationUrl: link.destination_url,
+          brand: config.shield?.safePage?.brand,
+        });
+        return res.status(200).type('html').send(html);
+      }
+
+      // ── Human — redirect ──
+      if (config.verbose) {
+        console.log(`[carom] 👤 HUMAN GET /${slug} score=${result.score} → 301 redirect`);
+      }
+
+      return res.redirect(301, link.destination_url);
+    } catch (err) {
+      console.error('[carom] Redirect error:', err);
+      res.status(500).json({ error: 'Internal server error' });
+    }
+  });
+
+  return router;
+}

package/src/server/server.js

@@ -0,0 +1,117 @@
+import { createRedirectApp, createAdminApp } from './app.js';
+import { getDb, closeDb } from '../db.js';
+import { writeFileSync, unlinkSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { DEFAULT_DATA_DIR, PID_FILENAME, LOG_DIR } from '../constants.js';
+
+/**
+ * Start the carom servers (redirect + admin).
+ *
+ * @param {object} config - Full config object
+ * @param {object} options - Additional options
+ * @param {string} options.dataDir - Data directory
+ * @param {boolean} options.verbose - Verbose logging
+ * @returns {Promise<{ redirectApp, adminApp, redirectServer, adminServer, db }>}
+ */
+export async function startServer(config, options = {}) {
+  const dataDir = options.dataDir || process.env.CAROM_DATA_DIR || DEFAULT_DATA_DIR;
+  const port = config.port || 3000;
+  const adminPort = config.adminPort || 3001;
+  const host = config.host || 'localhost';
+
+  // Ensure data & log directories exist
+  mkdirSync(dataDir, { recursive: true });
+  mkdirSync(join(dataDir, LOG_DIR), { recursive: true });
+
+  // Initialize database
+  const db = getDb(dataDir);
+
+  // Build full config with runtime fields
+  const fullConfig = { ...config, verbose: options.verbose || false, _dataDir: dataDir };
+
+  // Create both Express apps
+  const redirectApp = createRedirectApp(fullConfig, db);
+  const adminApp = createAdminApp(fullConfig, db);
+
+  // Start both servers
+  return new Promise((resolve, reject) => {
+    let redirectReady = false;
+    let adminReady = false;
+
+    const checkReady = () => {
+      if (redirectReady && adminReady) {
+        // Write PID file
+        const pidPath = join(dataDir, PID_FILENAME);
+        try {
+          writeFileSync(pidPath, String(process.pid));
+        } catch {
+          // Non-fatal
+        }
+        resolve({ redirectApp, adminApp, redirectServer, adminServer, db });
+      }
+    };
+
+    // ── Redirect server (public) ──
+    const redirectServer = redirectApp.listen(port, host, () => {
+      redirectReady = true;
+      checkReady();
+    });
+
+    redirectServer.on('error', (err) => {
+      if (err.code === 'EADDRINUSE') {
+        reject(new Error(`Redirect port ${port} is already in use. Use --port to specify a different port.`));
+      } else {
+        reject(err);
+      }
+    });
+
+    // ── Admin server (dashboard + API) ──
+    const adminServer = adminApp.listen(adminPort, host, () => {
+      adminReady = true;
+      checkReady();
+    });
+
+    adminServer.on('error', (err) => {
+      if (err.code === 'EADDRINUSE') {
+        reject(new Error(`Admin port ${adminPort} is already in use. Use --admin-port to specify a different port.`));
+      } else {
+        reject(err);
+      }
+    });
+
+    // Graceful shutdown — close both servers
+    const shutdown = (signal) => {
+      console.log(`\n[carom] Received ${signal}, shutting down...`);
+
+      let closed = 0;
+      const onClose = () => {
+        closed++;
+        if (closed >= 2) {
+          closeDb();
+
+          // Remove PID file
+          try {
+            unlinkSync(join(dataDir, PID_FILENAME));
+          } catch {
+            // Non-fatal
+          }
+
+          console.log('[carom] Servers stopped.');
+          process.exit(0);
+        }
+      };
+
+      redirectServer.close(onClose);
+      adminServer.close(onClose);
+
+      // Force exit after 5 seconds
+      setTimeout(() => {
+        console.error('[carom] Forced shutdown after timeout.');
+        process.exit(1);
+      }, 5000);
+    };
+
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+  });
+}

package/src/service/launchd.js

@@ -0,0 +1,166 @@
+import { writeFileSync, unlinkSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { execSync } from 'child_process';
+import { DEFAULT_DATA_DIR } from '../constants.js';
+
+const LABEL = 'com.carom';
+const PLIST_DIR = join(homedir(), 'Library', 'LaunchAgents');
+const PLIST_PATH = join(PLIST_DIR, `${LABEL}.plist`);
+
+/**
+ * Generate the launchd plist XML.
+ */
+function generatePlist(config) {
+  const dataDir = config.dataDir || DEFAULT_DATA_DIR;
+  const nodePath = process.execPath;
+  const binPath = join(process.argv[1] || '', '..', '..', 'bin', 'carom.js');
+
+  // Try to find the actual bin path
+  let actualBinPath;
+  try {
+    actualBinPath = execSync('which carom', { encoding: 'utf8' }).trim();
+  } catch {
+    // Fallback: resolve from the current execution
+    actualBinPath = binPath;
+  }
+
+  const args = [nodePath, actualBinPath, 'start'];
+  if (config.port) args.push('--port', String(config.port));
+  if (config.adminPort) args.push('--admin-port', String(config.adminPort));
+  if (config.host && config.host !== 'localhost') args.push('--host', config.host);
+  if (config.apiKey) args.push('--api-key', config.apiKey);
+  if (config.dataDir) args.push('--data-dir', config.dataDir);
+
+  const logDir = join(dataDir, 'logs');
+  const stdoutLog = join(logDir, 'stdout.log');
+  const stderrLog = join(logDir, 'stderr.log');
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LABEL}</string>
+
+  <key>ProgramArguments</key>
+  <array>
+${args.map(a => `    <string>${escapeXml(a)}</string>`).join('\n')}
+  </array>
+
+  <key>RunAtLoad</key>
+  <true/>
+
+  <key>KeepAlive</key>
+  <true/>
+
+  <key>StandardOutPath</key>
+  <string>${escapeXml(stdoutLog)}</string>
+
+  <key>StandardErrorPath</key>
+  <string>${escapeXml(stderrLog)}</string>
+
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>CAROM_DATA_DIR</key>
+    <string>${escapeXml(dataDir)}</string>
+    <key>PATH</key>
+    <string>/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin</string>
+  </dict>
+
+  <key>ThrottleInterval</key>
+  <integer>5</integer>
+</dict>
+</plist>`;
+}
+
+function escapeXml(str) {
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+/**
+ * Install the launchd service.
+ */
+export async function installLaunchd(config) {
+  // Unload existing if present
+  if (existsSync(PLIST_PATH)) {
+    try {
+      execSync(`launchctl unload "${PLIST_PATH}" 2>/dev/null`, { stdio: 'ignore' });
+    } catch {
+      // Ignore
+    }
+  }
+
+  const plist = generatePlist(config);
+  writeFileSync(PLIST_PATH, plist, 'utf8');
+
+  // Load the service
+  execSync(`launchctl load "${PLIST_PATH}"`);
+
+  return {
+    path: PLIST_PATH,
+    label: LABEL,
+    message: `Service installed at ${PLIST_PATH}`,
+  };
+}
+
+/**
+ * Uninstall the launchd service.
+ */
+export async function uninstallLaunchd() {
+  if (!existsSync(PLIST_PATH)) {
+    throw new Error('Service is not installed.');
+  }
+
+  try {
+    execSync(`launchctl unload "${PLIST_PATH}"`, { stdio: 'ignore' });
+  } catch {
+    // May already be unloaded
+  }
+
+  unlinkSync(PLIST_PATH);
+
+  return { message: 'Service uninstalled successfully.' };
+}
+
+/**
+ * Check if the launchd service is installed.
+ */
+export function isLaunchdInstalled() {
+  return existsSync(PLIST_PATH);
+}
+
+/**
+ * Get the launchd service status.
+ */
+export async function getLaunchdStatus() {
+  const installed = isLaunchdInstalled();
+  let running = false;
+  let pid = null;
+
+  if (installed) {
+    try {
+      const output = execSync(`launchctl list | grep ${LABEL}`, { encoding: 'utf8' });
+      const parts = output.trim().split(/\s+/);
+      if (parts[0] && parts[0] !== '-') {
+        pid = parseInt(parts[0], 10);
+        running = !isNaN(pid);
+      }
+    } catch {
+      // Not running
+    }
+  }
+
+  return {
+    installed,
+    running,
+    pid,
+    type: 'launchd',
+    path: PLIST_PATH,
+  };
+}

package/src/service/manager.js

@@ -0,0 +1,79 @@
+import { platform } from 'os';
+import { installLaunchd, uninstallLaunchd, isLaunchdInstalled, getLaunchdStatus } from './launchd.js';
+import { installSystemd, uninstallSystemd, isSystemdInstalled, getSystemdStatus } from './systemd.js';
+
+/**
+ * Detect the current platform and return the appropriate service manager.
+ */
+function getServiceImpl() {
+  const os = platform();
+  if (os === 'darwin') {
+    return {
+      install: installLaunchd,
+      uninstall: uninstallLaunchd,
+      isInstalled: isLaunchdInstalled,
+      getStatus: getLaunchdStatus,
+      type: 'launchd',
+    };
+  } else if (os === 'linux') {
+    return {
+      install: installSystemd,
+      uninstall: uninstallSystemd,
+      isInstalled: isSystemdInstalled,
+      getStatus: getSystemdStatus,
+      type: 'systemd',
+    };
+  } else {
+    return null;
+  }
+}
+
+/**
+ * Install the carom service for auto-start on boot.
+ */
+export async function installService(config) {
+  const impl = getServiceImpl();
+  if (!impl) {
+    throw new Error(`Service installation is not supported on ${platform()}. Use "carom start" to run manually.`);
+  }
+  return impl.install(config);
+}
+
+/**
+ * Uninstall the carom service.
+ */
+export async function uninstallService() {
+  const impl = getServiceImpl();
+  if (!impl) {
+    throw new Error(`Service management is not supported on ${platform()}.`);
+  }
+  return impl.uninstall();
+}
+
+/**
+ * Check if the service is installed.
+ */
+export function isServiceInstalled() {
+  const impl = getServiceImpl();
+  if (!impl) return false;
+  return impl.isInstalled();
+}
+
+/**
+ * Get the service status.
+ */
+export async function getServiceStatus() {
+  const impl = getServiceImpl();
+  if (!impl) {
+    return { installed: false, running: false, type: 'unsupported' };
+  }
+  return impl.getStatus();
+}
+
+/**
+ * Get the service type for the current platform.
+ */
+export function getServiceType() {
+  const impl = getServiceImpl();
+  return impl?.type || 'unsupported';
+}

package/src/service/systemd.js

@@ -0,0 +1,147 @@
+import { writeFileSync, unlinkSync, existsSync } from 'fs';
+import { execSync } from 'child_process';
+import { DEFAULT_DATA_DIR } from '../constants.js';
+
+const SERVICE_NAME = 'carom';
+const UNIT_PATH = `/etc/systemd/system/${SERVICE_NAME}.service`;
+
+/**
+ * Generate the systemd unit file.
+ */
+function generateUnit(config) {
+  const dataDir = config.dataDir || DEFAULT_DATA_DIR;
+  const nodePath = process.execPath;
+
+  let execStart;
+  try {
+    const binPath = execSync('which carom', { encoding: 'utf8' }).trim();
+    execStart = `${nodePath} ${binPath} start`;
+  } catch {
+    execStart = `${nodePath} ${process.argv[1]} start`;
+  }
+
+  if (config.port) execStart += ` --port ${config.port}`;
+  if (config.adminPort) execStart += ` --admin-port ${config.adminPort}`;
+  if (config.host && config.host !== 'localhost') execStart += ` --host ${config.host}`;
+  if (config.apiKey) execStart += ` --api-key ${config.apiKey}`;
+  if (config.dataDir) execStart += ` --data-dir ${config.dataDir}`;
+
+  const user = process.env.USER || process.env.LOGNAME || 'root';
+
+  return `[Unit]
+Description=carom - Link redirect server with bot protection
+After=network.target
+
+[Service]
+Type=simple
+User=${user}
+ExecStart=${execStart}
+Restart=always
+RestartSec=5
+Environment=CAROM_DATA_DIR=${dataDir}
+Environment=NODE_ENV=production
+StandardOutput=append:${dataDir}/logs/stdout.log
+StandardError=append:${dataDir}/logs/stderr.log
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+
+/**
+ * Install the systemd service.
+ */
+export async function installSystemd(config) {
+  const unit = generateUnit(config);
+
+  try {
+    writeFileSync(UNIT_PATH, unit, 'utf8');
+  } catch (err) {
+    if (err.code === 'EACCES') {
+      throw new Error('Permission denied. Run with sudo: sudo carom install');
+    }
+    throw err;
+  }
+
+  execSync('systemctl daemon-reload');
+  execSync(`systemctl enable ${SERVICE_NAME}`);
+  execSync(`systemctl start ${SERVICE_NAME}`);
+
+  return {
+    path: UNIT_PATH,
+    name: SERVICE_NAME,
+    message: `Service installed at ${UNIT_PATH}`,
+  };
+}
+
+/**
+ * Uninstall the systemd service.
+ */
+export async function uninstallSystemd() {
+  if (!existsSync(UNIT_PATH)) {
+    throw new Error('Service is not installed.');
+  }
+
+  try {
+    execSync(`systemctl stop ${SERVICE_NAME}`, { stdio: 'ignore' });
+    execSync(`systemctl disable ${SERVICE_NAME}`, { stdio: 'ignore' });
+  } catch {
+    // May already be stopped
+  }
+
+  try {
+    unlinkSync(UNIT_PATH);
+  } catch (err) {
+    if (err.code === 'EACCES') {
+      throw new Error('Permission denied. Run with sudo: sudo carom uninstall');
+    }
+    throw err;
+  }
+
+  execSync('systemctl daemon-reload');
+
+  return { message: 'Service uninstalled successfully.' };
+}
+
+/**
+ * Check if the systemd service is installed.
+ */
+export function isSystemdInstalled() {
+  return existsSync(UNIT_PATH);
+}
+
+/**
+ * Get the systemd service status.
+ */
+export async function getSystemdStatus() {
+  const installed = isSystemdInstalled();
+  let running = false;
+  let pid = null;
+
+  if (installed) {
+    try {
+      const output = execSync(`systemctl is-active ${SERVICE_NAME}`, { encoding: 'utf8' }).trim();
+      running = output === 'active';
+    } catch {
+      running = false;
+    }
+
+    if (running) {
+      try {
+        const output = execSync(`systemctl show ${SERVICE_NAME} --property=MainPID`, { encoding: 'utf8' }).trim();
+        const match = output.match(/MainPID=(\d+)/);
+        if (match) pid = parseInt(match[1], 10);
+      } catch {
+        // Ignore
+      }
+    }
+  }
+
+  return {
+    installed,
+    running,
+    pid,
+    type: 'systemd',
+    path: UNIT_PATH,
+  };
+}