carom-link 1.0.0

package/src/cloak/ipLookup.js

@@ -0,0 +1,146 @@
+import { DATACENTER_ASNS, DATACENTER_ORG_PATTERNS } from './patterns.js';
+import { IP_CACHE_MAX, IP_CACHE_TTL_MS } from '../constants.js';
+
+/**
+ * Simple LRU cache for IP lookups.
+ */
+class LRUCache {
+  constructor(maxSize, ttlMs) {
+    this.maxSize = maxSize;
+    this.ttlMs = ttlMs;
+    this.cache = new Map();
+  }
+
+  get(key) {
+    const entry = this.cache.get(key);
+    if (!entry) return null;
+    if (Date.now() - entry.timestamp > this.ttlMs) {
+      this.cache.delete(key);
+      return null;
+    }
+    // Move to end (most recently used)
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+    return entry.value;
+  }
+
+  set(key, value) {
+    if (this.cache.size >= this.maxSize) {
+      // Delete oldest entry
+      const firstKey = this.cache.keys().next().value;
+      this.cache.delete(firstKey);
+    }
+    this.cache.set(key, { value, timestamp: Date.now() });
+  }
+}
+
+const ipCache = new LRUCache(IP_CACHE_MAX, IP_CACHE_TTL_MS);
+
+/**
+ * Check if an IP is a private/reserved address.
+ */
+function isPrivateIp(ip) {
+  if (!ip) return true;
+  return (
+    ip === '127.0.0.1' ||
+    ip === '::1' ||
+    ip.startsWith('10.') ||
+    ip.startsWith('172.16.') || ip.startsWith('172.17.') || ip.startsWith('172.18.') ||
+    ip.startsWith('172.19.') || ip.startsWith('172.2') || ip.startsWith('172.30.') ||
+    ip.startsWith('172.31.') ||
+    ip.startsWith('192.168.') ||
+    ip.startsWith('fc') || ip.startsWith('fd') ||
+    ip.startsWith('fe80')
+  );
+}
+
+/**
+ * Look up IP information using the free ip-api.com service.
+ * Returns { asn, org, isDatacenter, country, isp }
+ */
+async function fetchIpInfo(ip) {
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 3000);
+
+    const response = await fetch(
+      `http://ip-api.com/json/${ip}?fields=status,message,country,isp,org,as,hosting`,
+      { signal: controller.signal }
+    );
+    clearTimeout(timeout);
+
+    if (!response.ok) return null;
+
+    const data = await response.json();
+    if (data.status !== 'success') return null;
+
+    // Parse ASN number from the "as" field (format: "AS16509 Amazon.com, Inc.")
+    let asnNumber = null;
+    if (data.as) {
+      const match = data.as.match(/^AS(\d+)/);
+      if (match) asnNumber = parseInt(match[1], 10);
+    }
+
+    const org = (data.org || data.isp || '').toLowerCase();
+    const isKnownAsn = asnNumber ? DATACENTER_ASNS.has(asnNumber) : false;
+    const isKnownOrg = DATACENTER_ORG_PATTERNS.some(p => org.includes(p));
+
+    return {
+      asn: asnNumber,
+      org: data.org || data.isp || '',
+      isDatacenter: data.hosting === true || isKnownAsn || isKnownOrg,
+      country: data.country || '',
+      isp: data.isp || '',
+      raw: data,
+    };
+  } catch {
+    // Network error, timeout, etc. — fail open
+    return null;
+  }
+}
+
+/**
+ * Look up IP information with caching.
+ * Returns { asn, org, isDatacenter } or null if lookup fails.
+ */
+export async function lookupIp(ip) {
+  if (!ip || isPrivateIp(ip)) {
+    return { asn: null, org: 'private', isDatacenter: false };
+  }
+
+  // Check cache
+  const cached = ipCache.get(ip);
+  if (cached) return cached;
+
+  // Fetch from API
+  const result = await fetchIpInfo(ip);
+  if (result) {
+    ipCache.set(ip, result);
+  }
+
+  return result;
+}
+
+/**
+ * Extract the real client IP from the request,
+ * respecting X-Forwarded-For and other proxy headers.
+ */
+export function getClientIp(req) {
+  // X-Forwarded-For can be comma-separated; take the first (original client)
+  const xff = req.headers['x-forwarded-for'];
+  if (xff) {
+    const first = xff.split(',')[0].trim();
+    if (first) return first;
+  }
+
+  // Other common headers
+  const realIp = req.headers['x-real-ip'];
+  if (realIp) return realIp;
+
+  // CF-Connecting-IP (Cloudflare)
+  const cfIp = req.headers['cf-connecting-ip'];
+  if (cfIp) return cfIp;
+
+  // Fall back to socket
+  return req.socket?.remoteAddress || req.ip || '';
+}

package/src/cloak/patterns.js

@@ -0,0 +1,160 @@
+/**
+ * Built-in bot detection patterns and datacenter ASN database.
+ * These are the default rules that ship with carom.
+ */
+
+// User-Agent substrings that indicate bots/crawlers/scanners
+// All matched case-insensitively
+export const BOT_UA_PATTERNS = [
+  // Generic bot tokens
+  'bot', 'crawl', 'spider', 'scrape',
+  // Preview/prefetch (carriers & messaging apps)
+  'preview', 'prefetch', 'fetch', 'unfurl',
+  // Scanning & monitoring
+  'scan', 'check', 'monitor', 'probe', 'validator',
+  // Headless browsers & automation
+  'headless', 'headlesschrome', 'phantom', 'phantomjs',
+  'selenium', 'puppeteer', 'playwright', 'webdriver',
+  // CLI tools
+  'wget', 'curl', 'httpie',
+  // HTTP libraries
+  'python-requests', 'python-urllib', 'python/',
+  'java/', 'apache-httpclient', 'okhttp',
+  'go-http-client', 'go-http',
+  'node-fetch', 'axios', 'undici', 'got/',
+  'libwww', 'lwp-', 'perl/',
+  'ruby/', 'faraday', 'typhoeus',
+  'php/', 'guzzle',
+  'dart/', 'http.client',
+  'rust/', 'reqwest', 'hyper/',
+  // Social media crawlers
+  'facebookexternalhit', 'facebot',
+  'twitterbot',
+  'linkedinbot',
+  'whatsapp',
+  'telegrambot',
+  'slackbot', 'slack-imgproxy',
+  'discordbot',
+  'pinterestbot',
+  'applebot',
+  // Search engines (detected but may be whitelisted)
+  'googlebot', 'google-inspectiontool',
+  'bingbot', 'msnbot',
+  'yandexbot', 'baiduspider',
+  'duckduckbot', 'sogou',
+  // SEO & marketing tools
+  'semrush', 'ahrefs', 'moz/', 'majestic',
+  'screaming frog', 'sitebulb',
+  // Security scanners
+  'nmap', 'masscan', 'zgrab', 'nuclei',
+  'qualys', 'nessus', 'nikto',
+  // Uptime monitors
+  'uptimerobot', 'pingdom', 'statuscake',
+  'site24x7', 'datadog',
+  // Other known bots
+  'mediapartners-google', 'adsbot-google',
+  'google-read-aloud', 'feedfetcher',
+  'ia_archiver', 'archive.org',
+];
+
+// Known datacenter/cloud provider ASNs
+// Traffic from these is likely automated, not a human on a phone
+export const DATACENTER_ASNS = new Set([
+  // Amazon Web Services
+  16509, 14618, 7224, 8987,
+  // Google Cloud
+  15169, 396982,
+  // Microsoft Azure
+  8075, 8068, 8069, 12076,
+  // DigitalOcean
+  14061, 393406,
+  // Cloudflare
+  13335, 209242,
+  // Akamai
+  20940, 16625, 32787,
+  // Linode / Akamai Cloud
+  63949,
+  // OVHcloud
+  16276,
+  // Hetzner
+  24940, 213230,
+  // Vultr
+  20473,
+  // Oracle Cloud
+  31898,
+  // IBM / SoftLayer
+  36351,
+  // Rackspace
+  33070, 10532,
+  // Scaleway
+  12876,
+  // UpCloud
+  202053,
+  // Contabo
+  40021,
+  // Leaseweb
+  60781, 28753, 16265,
+  // ColoCrossing
+  36352,
+  // QuadraNet
+  8100,
+  // Choopa / Vultr
+  20473,
+  // Fastly
+  54113,
+  // Netlify
+  400587,
+  // Vercel
+  209242,
+  // Render
+  398101,
+  // Railway
+  400587,
+  // Fly.io
+  40509,
+]);
+
+// Known datacenter org name fragments (fallback if ASN not in set)
+export const DATACENTER_ORG_PATTERNS = [
+  'amazon', 'aws', 'ec2',
+  'google cloud', 'google llc',
+  'microsoft', 'azure',
+  'digitalocean',
+  'cloudflare',
+  'akamai',
+  'linode',
+  'ovh',
+  'hetzner',
+  'vultr', 'choopa',
+  'oracle',
+  'ibm', 'softlayer',
+  'rackspace',
+  'scaleway',
+  'contabo',
+  'leaseweb',
+  'fastly',
+  'datacenter', 'data center',
+  'hosting',
+  'colocation', 'colo',
+  'server',
+];
+
+// Bots that should be allowed through (whitelisted)
+// These are verified via reverse DNS, not just UA string
+export const ALLOWED_BOTS = [
+  {
+    name: 'Googlebot',
+    uaPattern: 'googlebot',
+    reverseDnsSuffix: '.googlebot.com',
+  },
+  {
+    name: 'Google (other)',
+    uaPattern: 'google',
+    reverseDnsSuffix: '.google.com',
+  },
+  {
+    name: 'Bingbot',
+    uaPattern: 'bingbot',
+    reverseDnsSuffix: '.search.msn.com',
+  },
+];

package/src/cloak/safePage.js

@@ -0,0 +1,146 @@
+/**
+ * Generates the benign HTML page served to detected bots.
+ * Designed to look like a normal, innocuous web page so carriers
+ * don't flag the domain as suspicious.
+ */
+
+/**
+ * Generate a safe page HTML string.
+ */
+export function generateSafePage({ title, description, brand, url }) {
+  const safeTitle = escapeHtml(title || 'Welcome');
+  const safeDescription = escapeHtml(description || 'Visit our website for more information.');
+  const safeBrand = escapeHtml(brand || 'Website');
+  const safeUrl = escapeHtml(url || '');
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${safeTitle} | ${safeBrand}</title>
+  <meta name="description" content="${safeDescription}">
+  <meta name="robots" content="noindex, nofollow">
+
+  <!-- Open Graph tags for carrier preview cards -->
+  <meta property="og:title" content="${safeTitle}">
+  <meta property="og:description" content="${safeDescription}">
+  <meta property="og:type" content="website">
+  <meta property="og:site_name" content="${safeBrand}">
+
+  <!-- Twitter Card -->
+  <meta name="twitter:card" content="summary">
+  <meta name="twitter:title" content="${safeTitle}">
+  <meta name="twitter:description" content="${safeDescription}">
+
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      background: #f8f9fa;
+      color: #333;
+      min-height: 100vh;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+    }
+    .container {
+      text-align: center;
+      padding: 2rem;
+      max-width: 480px;
+    }
+    .brand {
+      font-size: 1.5rem;
+      font-weight: 700;
+      color: #2c3e50;
+      margin-bottom: 1rem;
+    }
+    .message {
+      font-size: 1rem;
+      color: #666;
+      line-height: 1.6;
+    }
+    .footer {
+      margin-top: 2rem;
+      font-size: 0.8rem;
+      color: #999;
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <div class="brand">${safeBrand}</div>
+    <p class="message">${safeDescription}</p>
+    <div class="footer">&copy; ${new Date().getFullYear()} ${safeBrand}</div>
+  </div>
+</body>
+</html>`;
+}
+
+/**
+ * Generate the interstitial challenge page (for interstitial mode).
+ * This page uses JavaScript to redirect, proving the client can execute JS.
+ */
+export function generateInterstitialPage({ slug, token, destinationUrl, brand }) {
+  const safeBrand = escapeHtml(brand || 'Website');
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Redirecting... | ${safeBrand}</title>
+  <meta name="robots" content="noindex, nofollow">
+  <!-- Fallback for non-JS: slow meta refresh to safe page (bots land here) -->
+  <meta http-equiv="refresh" content="5;url=/${escapeHtml(slug)}?_safe=1">
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      background: #f8f9fa;
+      color: #333;
+      min-height: 100vh;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+    }
+    .container { text-align: center; padding: 2rem; }
+    .spinner {
+      width: 32px; height: 32px;
+      border: 3px solid #e0e0e0;
+      border-top-color: #3498db;
+      border-radius: 50%;
+      animation: spin 0.8s linear infinite;
+      margin: 0 auto 1rem;
+    }
+    @keyframes spin { to { transform: rotate(360deg); } }
+    .message { color: #666; font-size: 0.95rem; }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <div class="spinner"></div>
+    <p class="message">Redirecting you securely...</p>
+  </div>
+  <script>
+    // JS-capable browsers redirect immediately with the signed token
+    (function() {
+      try {
+        window.location.replace('/${escapeHtml(slug)}?_t=${escapeHtml(token)}');
+      } catch(e) {
+        // Fallback: meta refresh will handle it
+      }
+    })();
+  </script>
+</body>
+</html>`;
+}
+
+function escapeHtml(str) {
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}

package/src/cloak/tokens.js

@@ -0,0 +1,67 @@
+import { createHmac, randomBytes } from 'crypto';
+import { TOKEN_EXPIRY_SECONDS, TOKEN_SECRET_LENGTH } from '../constants.js';
+
+// Generate a random secret on startup (or load from config)
+let _secret = null;
+
+function getSecret() {
+  if (!_secret) {
+    _secret = randomBytes(TOKEN_SECRET_LENGTH).toString('hex');
+  }
+  return _secret;
+}
+
+/**
+ * Set the HMAC secret (used when loading from config/env).
+ */
+export function setTokenSecret(secret) {
+  _secret = secret;
+}
+
+/**
+ * Generate a signed token for a slug.
+ * Token format: timestamp.hmac
+ */
+export function generateToken(slug) {
+  const timestamp = Math.floor(Date.now() / 1000);
+  const payload = `${slug}:${timestamp}`;
+  const hmac = createHmac('sha256', getSecret())
+    .update(payload)
+    .digest('hex')
+    .substring(0, 16); // Truncate for URL-friendliness
+  return `${timestamp}.${hmac}`;
+}
+
+/**
+ * Validate a token for a slug.
+ * Returns true if the token is valid and not expired.
+ */
+export function validateToken(slug, token) {
+  if (!token) return false;
+
+  const parts = token.split('.');
+  if (parts.length !== 2) return false;
+
+  const [timestampStr, providedHmac] = parts;
+  const timestamp = parseInt(timestampStr, 10);
+  if (isNaN(timestamp)) return false;
+
+  // Check expiry
+  const now = Math.floor(Date.now() / 1000);
+  if (now - timestamp > TOKEN_EXPIRY_SECONDS) return false;
+
+  // Verify HMAC
+  const payload = `${slug}:${timestamp}`;
+  const expectedHmac = createHmac('sha256', getSecret())
+    .update(payload)
+    .digest('hex')
+    .substring(0, 16);
+
+  // Constant-time comparison
+  if (providedHmac.length !== expectedHmac.length) return false;
+  let match = true;
+  for (let i = 0; i < expectedHmac.length; i++) {
+    if (providedHmac[i] !== expectedHmac[i]) match = false;
+  }
+  return match;
+}

package/src/config.js

@@ -0,0 +1,152 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import { DEFAULT_DATA_DIR, CONFIG_FILENAME, DEFAULT_CONFIG } from './constants.js';
+
+let _configDir = null;
+
+/**
+ * Deep merge two objects. Source values override target values.
+ */
+function deepMerge(target, source) {
+  const result = { ...target };
+  for (const key of Object.keys(source)) {
+    if (
+      source[key] &&
+      typeof source[key] === 'object' &&
+      !Array.isArray(source[key]) &&
+      target[key] &&
+      typeof target[key] === 'object'
+    ) {
+      result[key] = deepMerge(target[key], source[key]);
+    } else {
+      result[key] = source[key];
+    }
+  }
+  return result;
+}
+
+/**
+ * Get a nested value from an object using dot notation.
+ */
+function getNestedValue(obj, path) {
+  return path.split('.').reduce((curr, key) => curr?.[key], obj);
+}
+
+/**
+ * Set a nested value on an object using dot notation.
+ */
+function setNestedValue(obj, path, value) {
+  const keys = path.split('.');
+  const last = keys.pop();
+  let curr = obj;
+  for (const key of keys) {
+    if (curr[key] === undefined || typeof curr[key] !== 'object') {
+      curr[key] = {};
+    }
+    curr = curr[key];
+  }
+  // Try to parse as number/boolean
+  if (value === 'true') value = true;
+  else if (value === 'false') value = false;
+  else if (!isNaN(value) && value !== '') value = Number(value);
+  curr[last] = value;
+}
+
+/**
+ * Get the config directory.
+ */
+function getConfigDir(dataDir) {
+  return dataDir || _configDir || process.env.CAROM_DATA_DIR || DEFAULT_DATA_DIR;
+}
+
+/**
+ * Set the config directory (called early by CLI).
+ */
+export function setConfigDir(dir) {
+  _configDir = dir;
+}
+
+/**
+ * Read config file, merged with defaults and env vars.
+ */
+export function loadConfig(dataDir) {
+  const dir = getConfigDir(dataDir);
+  const configPath = join(dir, CONFIG_FILENAME);
+
+  let fileConfig = {};
+  if (existsSync(configPath)) {
+    try {
+      fileConfig = JSON.parse(readFileSync(configPath, 'utf8'));
+    } catch {
+      // Corrupt config file, use defaults
+    }
+  }
+
+  // Start with defaults, overlay file config
+  let config = deepMerge(DEFAULT_CONFIG, fileConfig);
+
+  // Env vars override everything
+  if (process.env.PORT) config.port = parseInt(process.env.PORT, 10);
+  if (process.env.ADMIN_PORT) config.adminPort = parseInt(process.env.ADMIN_PORT, 10);
+  if (process.env.HOST) config.host = process.env.HOST;
+  if (process.env.BASE_URL) config.baseUrl = process.env.BASE_URL;
+  if (process.env.API_KEY) config.apiKey = process.env.API_KEY;
+  if (process.env.SHIELD_ENABLED !== undefined) config.shield.enabled = process.env.SHIELD_ENABLED === 'true';
+  if (process.env.SHIELD_THRESHOLD) config.shield.threshold = parseInt(process.env.SHIELD_THRESHOLD, 10);
+  if (process.env.SHIELD_MODE) config.shield.mode = process.env.SHIELD_MODE;
+  if (process.env.SAFE_PAGE_TITLE) config.shield.safePage.title = process.env.SAFE_PAGE_TITLE;
+  if (process.env.SAFE_PAGE_DESCRIPTION) config.shield.safePage.description = process.env.SAFE_PAGE_DESCRIPTION;
+  if (process.env.SAFE_PAGE_BRAND) config.shield.safePage.brand = process.env.SAFE_PAGE_BRAND;
+
+  return config;
+}
+
+/**
+ * Save config to file.
+ */
+export function saveConfig(config, dataDir) {
+  const dir = getConfigDir(dataDir);
+  mkdirSync(dir, { recursive: true });
+  const configPath = join(dir, CONFIG_FILENAME);
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Get a specific config value by dot-notation key.
+ */
+export function getConfigValue(key, dataDir) {
+  const config = loadConfig(dataDir);
+  return getNestedValue(config, key);
+}
+
+/**
+ * Set a specific config value by dot-notation key and persist.
+ */
+export function setConfigValue(key, value, dataDir) {
+  const dir = getConfigDir(dataDir);
+  const configPath = join(dir, CONFIG_FILENAME);
+
+  // Read raw file config (not merged with env/defaults)
+  let fileConfig = {};
+  if (existsSync(configPath)) {
+    try {
+      fileConfig = JSON.parse(readFileSync(configPath, 'utf8'));
+    } catch {
+      fileConfig = {};
+    }
+  }
+
+  setNestedValue(fileConfig, key, value);
+  saveConfig(fileConfig, dataDir);
+
+  // Return the full merged config
+  return loadConfig(dataDir);
+}
+
+/**
+ * Reset config to defaults.
+ */
+export function resetConfig(dataDir) {
+  saveConfig({}, dataDir);
+  return loadConfig(dataDir);
+}