carom-link 1.0.0

package/src/constants.js

@@ -0,0 +1,78 @@
+import { homedir } from 'os';
+import { join } from 'path';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Package version from package.json
+let PKG_VERSION = '1.0.0';
+try {
+  const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+  PKG_VERSION = pkg.version;
+} catch {
+  // fallback
+}
+
+export const VERSION = PKG_VERSION;
+export const PACKAGE_NAME = 'carom';
+
+// Data directory
+export const DEFAULT_DATA_DIR = join(homedir(), '.carom');
+export const DB_FILENAME = 'data.db';
+export const CONFIG_FILENAME = 'config.json';
+export const PID_FILENAME = 'carom.pid';
+export const LOG_DIR = 'logs';
+export const LOG_FILENAME = 'server.log';
+
+// Slug generation
+export const SLUG_ALPHABET = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+export const SLUG_LENGTH = 7;
+
+// Server defaults
+export const DEFAULT_PORT = 3000;
+export const DEFAULT_ADMIN_PORT = 3001;
+export const DEFAULT_HOST = 'localhost';
+
+// Rate limiting
+export const API_RATE_LIMIT = { windowMs: 60_000, max: 100 };
+export const REDIRECT_RATE_LIMIT = { windowMs: 60_000, max: 1000 };
+
+// Bot protection defaults
+export const DEFAULT_SHIELD_CONFIG = {
+  enabled: true,
+  threshold: 40,
+  mode: 'direct', // 'direct' or 'interstitial'
+  safePage: {
+    title: 'Welcome',
+    description: 'Visit our website for more information.',
+    brand: 'YourBrand',
+  },
+};
+
+// Default full config
+export const DEFAULT_CONFIG = {
+  port: DEFAULT_PORT,
+  adminPort: DEFAULT_ADMIN_PORT,
+  host: DEFAULT_HOST,
+  baseUrl: '',
+  apiKey: '',
+  shield: { ...DEFAULT_SHIELD_CONFIG },
+};
+
+// Token settings
+export const TOKEN_SECRET_LENGTH = 32;
+export const TOKEN_EXPIRY_SECONDS = 30;
+
+// IP lookup cache
+export const IP_CACHE_MAX = 10_000;
+export const IP_CACHE_TTL_MS = 3_600_000; // 1 hour
+
+// Velocity tracking
+export const VELOCITY_WINDOW_MS = 10_000;
+export const VELOCITY_THRESHOLD = 5;
+
+// Timing detection
+export const TIMING_FAST_THRESHOLD_MS = 3_000;

package/src/db.js

@@ -0,0 +1,256 @@
+import Database from 'better-sqlite3';
+import { join } from 'path';
+import { mkdirSync } from 'fs';
+import { DEFAULT_DATA_DIR, DB_FILENAME } from './constants.js';
+
+let _db = null;
+
+/**
+ * Get or initialize the SQLite database connection.
+ */
+export function getDb(dataDir) {
+  if (_db) return _db;
+
+  const dir = dataDir || process.env.CAROM_DATA_DIR || DEFAULT_DATA_DIR;
+  mkdirSync(dir, { recursive: true });
+
+  const dbPath = join(dir, DB_FILENAME);
+  _db = new Database(dbPath);
+
+  // Performance settings
+  _db.pragma('journal_mode = WAL');
+  _db.pragma('synchronous = NORMAL');
+  _db.pragma('foreign_keys = ON');
+
+  initTables(_db);
+  return _db;
+}
+
+/**
+ * Close the database connection.
+ */
+export function closeDb() {
+  if (_db) {
+    _db.close();
+    _db = null;
+  }
+}
+
+/**
+ * Create tables if they don't exist.
+ */
+function initTables(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS links (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      slug TEXT UNIQUE NOT NULL,
+      destination_url TEXT NOT NULL,
+      created_at DATETIME DEFAULT (datetime('now')),
+      expires_at DATETIME,
+      active BOOLEAN DEFAULT 1
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_links_slug ON links(slug);
+    CREATE INDEX IF NOT EXISTS idx_links_active ON links(active);
+
+    CREATE TABLE IF NOT EXISTS clicks (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      link_id INTEGER NOT NULL REFERENCES links(id),
+      clicked_at DATETIME DEFAULT (datetime('now')),
+      user_agent TEXT,
+      ip_hash TEXT,
+      referer TEXT,
+      is_bot BOOLEAN DEFAULT 0,
+      bot_score INTEGER DEFAULT 0,
+      bot_signals TEXT,
+      classification TEXT DEFAULT 'human'
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_clicks_link_id ON clicks(link_id);
+    CREATE INDEX IF NOT EXISTS idx_clicks_clicked_at ON clicks(clicked_at);
+    CREATE INDEX IF NOT EXISTS idx_clicks_classification ON clicks(classification);
+
+    CREATE TABLE IF NOT EXISTS rules (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      type TEXT NOT NULL,
+      pattern TEXT NOT NULL,
+      weight INTEGER DEFAULT 30,
+      active BOOLEAN DEFAULT 1,
+      created_at DATETIME DEFAULT (datetime('now')),
+      note TEXT
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_rules_type ON rules(type);
+    CREATE INDEX IF NOT EXISTS idx_rules_active ON rules(active);
+  `);
+}
+
+// ── Link Operations ──
+
+export function createLink(db, { slug, destinationUrl, expiresAt }) {
+  const stmt = db.prepare(`
+    INSERT INTO links (slug, destination_url, expires_at)
+    VALUES (?, ?, ?)
+  `);
+  const result = stmt.run(slug, destinationUrl, expiresAt || null);
+  return findLinkById(db, result.lastInsertRowid);
+}
+
+export function findBySlug(db, slug) {
+  return db.prepare(`
+    SELECT * FROM links WHERE slug = ? AND active = 1
+  `).get(slug);
+}
+
+export function findLinkById(db, id) {
+  return db.prepare('SELECT * FROM links WHERE id = ?').get(id);
+}
+
+export function findLinkByIdOrSlug(db, idOrSlug) {
+  const asInt = parseInt(idOrSlug, 10);
+  if (!isNaN(asInt) && String(asInt) === String(idOrSlug)) {
+    return findLinkById(db, asInt);
+  }
+  return db.prepare('SELECT * FROM links WHERE slug = ?').get(idOrSlug);
+}
+
+export function getLinks(db, { includeInactive = false, limit = 100, offset = 0 } = {}) {
+  const where = includeInactive ? '' : 'WHERE l.active = 1';
+  return db.prepare(`
+    SELECT
+      l.*,
+      COUNT(c.id) AS total_clicks,
+      SUM(CASE WHEN c.classification = 'human' THEN 1 ELSE 0 END) AS human_clicks,
+      SUM(CASE WHEN c.classification = 'bot' THEN 1 ELSE 0 END) AS bot_clicks
+    FROM links l
+    LEFT JOIN clicks c ON c.link_id = l.id
+    ${where}
+    GROUP BY l.id
+    ORDER BY l.created_at DESC
+    LIMIT ? OFFSET ?
+  `).all(limit, offset);
+}
+
+export function getLinkCount(db) {
+  return db.prepare('SELECT COUNT(*) as count FROM links WHERE active = 1').get().count;
+}
+
+export function deactivateLink(db, id) {
+  return db.prepare('UPDATE links SET active = 0 WHERE id = ?').run(id);
+}
+
+// ── Click Operations ──
+
+export function logClick(db, { linkId, userAgent, ipHash, referer, isBot, botScore, botSignals, classification }) {
+  return db.prepare(`
+    INSERT INTO clicks (link_id, user_agent, ip_hash, referer, is_bot, bot_score, bot_signals, classification)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    linkId,
+    userAgent || null,
+    ipHash || null,
+    referer || null,
+    isBot ? 1 : 0,
+    botScore || 0,
+    botSignals ? JSON.stringify(botSignals) : null,
+    classification || 'human'
+  );
+}
+
+export function getClickStats(db, linkId) {
+  const totals = db.prepare(`
+    SELECT
+      COUNT(*) AS total,
+      SUM(CASE WHEN classification = 'human' THEN 1 ELSE 0 END) AS human,
+      SUM(CASE WHEN classification = 'bot' THEN 1 ELSE 0 END) AS bot,
+      SUM(CASE WHEN classification = 'suspicious' THEN 1 ELSE 0 END) AS suspicious
+    FROM clicks WHERE link_id = ?
+  `).get(linkId);
+
+  const recentClicks = db.prepare(`
+    SELECT * FROM clicks
+    WHERE link_id = ?
+    ORDER BY clicked_at DESC
+    LIMIT 50
+  `).all(linkId);
+
+  const topSignals = db.prepare(`
+    SELECT bot_signals, COUNT(*) as count
+    FROM clicks
+    WHERE link_id = ? AND bot_signals IS NOT NULL
+    GROUP BY bot_signals
+    ORDER BY count DESC
+    LIMIT 10
+  `).all(linkId);
+
+  const topUserAgents = db.prepare(`
+    SELECT user_agent, classification, COUNT(*) as count
+    FROM clicks
+    WHERE link_id = ?
+    GROUP BY user_agent, classification
+    ORDER BY count DESC
+    LIMIT 10
+  `).all(linkId);
+
+  const timeline = {
+    last24h: db.prepare(`
+      SELECT COUNT(*) as count FROM clicks
+      WHERE link_id = ? AND clicked_at >= datetime('now', '-1 day')
+    `).get(linkId).count,
+    last7d: db.prepare(`
+      SELECT COUNT(*) as count FROM clicks
+      WHERE link_id = ? AND clicked_at >= datetime('now', '-7 days')
+    `).get(linkId).count,
+    last30d: db.prepare(`
+      SELECT COUNT(*) as count FROM clicks
+      WHERE link_id = ? AND clicked_at >= datetime('now', '-30 days')
+    `).get(linkId).count,
+  };
+
+  return { totals, recentClicks, topSignals, topUserAgents, timeline };
+}
+
+// ── Velocity tracking (in-memory, not DB) ──
+
+const velocityMap = new Map();
+
+export function trackVelocity(slug) {
+  const now = Date.now();
+  if (!velocityMap.has(slug)) {
+    velocityMap.set(slug, []);
+  }
+  const timestamps = velocityMap.get(slug);
+  timestamps.push(now);
+
+  // Clean old entries (older than 10s)
+  const cutoff = now - 10_000;
+  while (timestamps.length > 0 && timestamps[0] < cutoff) {
+    timestamps.shift();
+  }
+
+  return timestamps.length;
+}
+
+// ── Rule Operations ──
+
+export function addRule(db, { type, pattern, weight, note }) {
+  const stmt = db.prepare(`
+    INSERT INTO rules (type, pattern, weight, note)
+    VALUES (?, ?, ?, ?)
+  `);
+  const result = stmt.run(type, pattern, weight || 30, note || null);
+  return db.prepare('SELECT * FROM rules WHERE id = ?').get(result.lastInsertRowid);
+}
+
+export function getRules(db, { includeInactive = false } = {}) {
+  const where = includeInactive ? '' : 'WHERE active = 1';
+  return db.prepare(`SELECT * FROM rules ${where} ORDER BY created_at DESC`).all();
+}
+
+export function removeRule(db, id) {
+  return db.prepare('UPDATE rules SET active = 0 WHERE id = ?').run(id);
+}
+
+export function deleteRule(db, id) {
+  return db.prepare('DELETE FROM rules WHERE id = ?').run(id);
+}

package/src/server/app.js

@@ -0,0 +1,110 @@
+import express from 'express';
+import helmet from 'helmet';
+import cors from 'cors';
+import rateLimit from 'express-rate-limit';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { API_RATE_LIMIT, REDIRECT_RATE_LIMIT } from '../constants.js';
+import { createApiRouter } from './routes/api.js';
+import { createRedirectRouter } from './routes/redirect.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Create the public redirect server.
+ * This is the lightweight, public-facing app that only handles redirects.
+ */
+export function createRedirectApp(config, db) {
+  const app = express();
+
+  app.set('trust proxy', 1);
+
+  app.use(helmet());
+
+  // ── Health check ──
+  app.get('/health', (req, res) => {
+    res.json({ status: 'ok', version: config.version || '1.0.0', role: 'redirect' });
+  });
+
+  // ── Redirect handler (catch-all) ──
+  const redirectLimiter = rateLimit({
+    windowMs: REDIRECT_RATE_LIMIT.windowMs,
+    max: REDIRECT_RATE_LIMIT.max,
+    standardHeaders: true,
+    legacyHeaders: false,
+    message: 'Too many requests.',
+  });
+
+  app.use('/', redirectLimiter, createRedirectRouter(config, db));
+
+  // ── 404 handler ──
+  app.use((req, res) => {
+    res.status(404).json({ error: 'Not found' });
+  });
+
+  // ── Error handler ──
+  app.use((err, req, res, _next) => {
+    console.error('[carom] Redirect error:', err.message);
+    res.status(500).json({ error: 'Internal server error' });
+  });
+
+  return app;
+}
+
+/**
+ * Create the admin server.
+ * Serves the dashboard UI and REST API on a separate port.
+ */
+export function createAdminApp(config, db) {
+  const app = express();
+
+  app.set('trust proxy', 1);
+
+  app.use(helmet({
+    contentSecurityPolicy: false, // Allow inline styles/scripts in dashboard
+  }));
+
+  app.use(cors());
+
+  app.use(express.json());
+  app.use(express.urlencoded({ extended: false }));
+
+  // ── Health check ──
+  app.get('/health', (req, res) => {
+    res.json({ status: 'ok', version: config.version || '1.0.0', role: 'admin' });
+  });
+
+  // ── API routes (rate limited) ──
+  const apiLimiter = rateLimit({
+    windowMs: API_RATE_LIMIT.windowMs,
+    max: API_RATE_LIMIT.max,
+    standardHeaders: true,
+    legacyHeaders: false,
+    message: { error: 'Too many API requests, please slow down.' },
+  });
+
+  app.use('/api', apiLimiter, createApiRouter(config, db));
+
+  // ── Admin dashboard (serve static files) ──
+  const publicDir = join(__dirname, '..', '..', 'public');
+
+  // Serve dashboard at root of admin server (no /dashboard prefix needed)
+  app.use('/', express.static(publicDir));
+  app.get('/', (req, res) => {
+    res.sendFile(join(publicDir, 'index.html'));
+  });
+
+  // ── 404 handler ──
+  app.use((req, res) => {
+    res.status(404).json({ error: 'Not found' });
+  });
+
+  // ── Error handler ──
+  app.use((err, req, res, _next) => {
+    console.error('[carom] Admin error:', err.message);
+    res.status(500).json({ error: 'Internal server error' });
+  });
+
+  return app;
+}

package/src/server/routes/api.js

@@ -0,0 +1,268 @@
+import { Router } from 'express';
+import { saveConfig } from '../../config.js';
+import {
+  createLink, getLinks, getLinkCount, findLinkByIdOrSlug,
+  deactivateLink, getClickStats,
+  addRule, getRules, removeRule,
+} from '../../db.js';
+import { testUserAgent } from '../../cloak/detector.js';
+import { customAlphabet } from 'nanoid';
+import { SLUG_ALPHABET, SLUG_LENGTH } from '../../constants.js';
+
+const generateSlug = customAlphabet(SLUG_ALPHABET, SLUG_LENGTH);
+
+/**
+ * API key authentication middleware.
+ */
+function authMiddleware(config) {
+  return (req, res, next) => {
+    // If no API key configured, allow all
+    if (!config.apiKey) return next();
+
+    const provided = req.headers['x-api-key'] || req.query.apiKey;
+    if (provided !== config.apiKey) {
+      return res.status(401).json({ error: 'Invalid or missing API key. Set x-api-key header.' });
+    }
+    next();
+  };
+}
+
+/**
+ * Create the API router.
+ */
+export function createApiRouter(config, db) {
+  const router = Router();
+
+  // All API routes require auth
+  router.use(authMiddleware(config));
+
+  // ── Links ──
+
+  // Create a new short link
+  router.post('/links', (req, res) => {
+    try {
+      const { url, slug: customSlug, expiresAt } = req.body;
+
+      if (!url) {
+        return res.status(400).json({ error: 'Missing required field: url' });
+      }
+
+      // Validate URL
+      try {
+        new URL(url);
+      } catch {
+        return res.status(400).json({ error: 'Invalid URL format' });
+      }
+
+      // Generate or validate slug
+      let slug = customSlug;
+      if (slug) {
+        // Validate custom slug
+        if (!/^[a-zA-Z0-9_-]+$/.test(slug)) {
+          return res.status(400).json({ error: 'Slug can only contain letters, numbers, hyphens, and underscores' });
+        }
+        // Check for reserved paths
+        const reserved = ['api', 'dashboard', 'health', '_t', '_safe'];
+        if (reserved.includes(slug.toLowerCase())) {
+          return res.status(400).json({ error: `Slug "${slug}" is reserved` });
+        }
+      } else {
+        // Generate unique slug with collision retry
+        let attempts = 0;
+        do {
+          slug = generateSlug();
+          attempts++;
+        } while (attempts < 10 && db.prepare('SELECT 1 FROM links WHERE slug = ?').get(slug));
+
+        if (attempts >= 10) {
+          return res.status(500).json({ error: 'Failed to generate unique slug' });
+        }
+      }
+
+      const link = createLink(db, {
+        slug,
+        destinationUrl: url,
+        expiresAt: expiresAt || null,
+      });
+
+      const baseUrl = config.baseUrl || `http://localhost:${config.port}`;
+      res.status(201).json({
+        ...link,
+        shortUrl: `${baseUrl}/${link.slug}`,
+      });
+    } catch (err) {
+      if (err.message?.includes('UNIQUE constraint')) {
+        return res.status(409).json({ error: 'Slug already exists' });
+      }
+      console.error('[carom] Error creating link:', err);
+      res.status(500).json({ error: 'Failed to create link' });
+    }
+  });
+
+  // List all links
+  router.get('/links', (req, res) => {
+    try {
+      const includeInactive = req.query.all === 'true';
+      const limit = parseInt(req.query.limit, 10) || 100;
+      const offset = parseInt(req.query.offset, 10) || 0;
+      const links = getLinks(db, { includeInactive, limit, offset });
+      const total = getLinkCount(db);
+      const baseUrl = config.baseUrl || `http://localhost:${config.port}`;
+
+      res.json({
+        links: links.map(l => ({
+          ...l,
+          shortUrl: `${baseUrl}/${l.slug}`,
+        })),
+        total,
+        limit,
+        offset,
+      });
+    } catch (err) {
+      console.error('[carom] Error listing links:', err);
+      res.status(500).json({ error: 'Failed to list links' });
+    }
+  });
+
+  // Get link stats
+  router.get('/links/:id/stats', (req, res) => {
+    try {
+      const link = findLinkByIdOrSlug(db, req.params.id);
+      if (!link) {
+        return res.status(404).json({ error: 'Link not found' });
+      }
+      const stats = getClickStats(db, link.id);
+      const baseUrl = config.baseUrl || `http://localhost:${config.port}`;
+      res.json({
+        link: { ...link, shortUrl: `${baseUrl}/${link.slug}` },
+        stats,
+      });
+    } catch (err) {
+      console.error('[carom] Error getting stats:', err);
+      res.status(500).json({ error: 'Failed to get stats' });
+    }
+  });
+
+  // Deactivate a link
+  router.delete('/links/:id', (req, res) => {
+    try {
+      const link = findLinkByIdOrSlug(db, req.params.id);
+      if (!link) {
+        return res.status(404).json({ error: 'Link not found' });
+      }
+      deactivateLink(db, link.id);
+      res.json({ success: true, message: `Link "${link.slug}" deactivated` });
+    } catch (err) {
+      console.error('[carom] Error deactivating link:', err);
+      res.status(500).json({ error: 'Failed to deactivate link' });
+    }
+  });
+
+  // ── Rules ──
+
+  // List detection rules
+  router.get('/rules', (req, res) => {
+    try {
+      const rules = getRules(db);
+      res.json({ rules });
+    } catch (err) {
+      console.error('[carom] Error listing rules:', err);
+      res.status(500).json({ error: 'Failed to list rules' });
+    }
+  });
+
+  // Add a custom rule
+  router.post('/rules', (req, res) => {
+    try {
+      const { type, pattern, weight, note } = req.body;
+      if (!type || !pattern) {
+        return res.status(400).json({ error: 'Missing required fields: type, pattern' });
+      }
+      const validTypes = ['ua_pattern', 'ip_range', 'asn'];
+      if (!validTypes.includes(type)) {
+        return res.status(400).json({ error: `Invalid type. Must be one of: ${validTypes.join(', ')}` });
+      }
+      const rule = addRule(db, { type, pattern, weight, note });
+      res.status(201).json(rule);
+    } catch (err) {
+      console.error('[carom] Error adding rule:', err);
+      res.status(500).json({ error: 'Failed to add rule' });
+    }
+  });
+
+  // Remove a rule
+  router.delete('/rules/:id', (req, res) => {
+    try {
+      const id = parseInt(req.params.id, 10);
+      removeRule(db, id);
+      res.json({ success: true, message: `Rule ${id} removed` });
+    } catch (err) {
+      console.error('[carom] Error removing rule:', err);
+      res.status(500).json({ error: 'Failed to remove rule' });
+    }
+  });
+
+  // Test a user-agent string
+  router.post('/rules/test', (req, res) => {
+    try {
+      const { userAgent } = req.body;
+      if (!userAgent) {
+        return res.status(400).json({ error: 'Missing required field: userAgent' });
+      }
+      const result = testUserAgent(userAgent, db);
+      res.json(result);
+    } catch (err) {
+      console.error('[carom] Error testing UA:', err);
+      res.status(500).json({ error: 'Failed to test user agent' });
+    }
+  });
+
+  // ── Bot Page Configuration ──
+
+  // Get current safe page settings
+  router.get('/config/safe-page', (req, res) => {
+    try {
+      const safePage = config.shield?.safePage || {};
+      res.json({
+        title: safePage.title || 'Welcome',
+        description: safePage.description || 'Visit our website for more information.',
+        brand: safePage.brand || 'Website',
+      });
+    } catch (err) {
+      console.error('[carom] Error getting safe page config:', err);
+      res.status(500).json({ error: 'Failed to get safe page config' });
+    }
+  });
+
+  // Update safe page settings (persisted to disk + applied in-memory)
+  router.put('/config/safe-page', (req, res) => {
+    try {
+      const { title, description, brand } = req.body;
+
+      // Ensure shield.safePage exists
+      if (!config.shield) config.shield = {};
+      if (!config.shield.safePage) config.shield.safePage = {};
+
+      // Apply changes in-memory (live, no restart needed)
+      if (title !== undefined) config.shield.safePage.title = title;
+      if (description !== undefined) config.shield.safePage.description = description;
+      if (brand !== undefined) config.shield.safePage.brand = brand;
+
+      // Persist to config file
+      const dataDir = process.env.CAROM_DATA_DIR || config._dataDir;
+      const configToSave = { shield: { safePage: { ...config.shield.safePage } } };
+      saveConfig(configToSave, dataDir);
+
+      res.json({
+        success: true,
+        safePage: config.shield.safePage,
+        message: 'Bot page settings updated. Changes are live immediately.',
+      });
+    } catch (err) {
+      console.error('[carom] Error updating safe page config:', err);
+      res.status(500).json({ error: 'Failed to update safe page config' });
+    }
+  });
+
+  return router;
+}