carom

Link redirect server with bot and automated traffic protection, plus CLI management.

Wrap destination URLs behind your own clean domain. When a link is clicked, real humans get a fast 301 redirect. Automated scanners — carrier pre-fetchers, security crawlers, bot scrapers — see a benign safe page instead.

Install

# Global install
npm install -g carom

# Or use npx
npx carom start

Requires Node.js ≥ 18.

Quick Start

# Start the server
carom start --port 3000

# Create a link
carom add https://example.com/landing-page my-slug
# → http://localhost:3000/my-slug

# List your links
carom ls

# Check click analytics
carom stats my-slug

How Bot Protection Works

Every request to a short link is scored by the detection engine:

| Signal | Weight | What it detects | |--------|--------|-----------------| | ua_pattern | +30 | Known bot/crawler User-Agent substrings (80+ patterns) | | ua_missing | +15 | No User-Agent header at all | | headers_suspicious | +20 | Missing Accept-Language, unusual Accept header | | datacenter_ip | +25 | IP belongs to a cloud provider (AWS, GCP, Azure, etc.) | | timing_fast | +15 | Click arrives <3s after link creation | | velocity_high | +15 | Same slug hit 5+ times in 10s window | | Custom rules | configurable | Your own UA patterns, IP ranges, or ASNs |

Score ≥ 40 (default) → Bot → Serve safe page (HTTP 200) Score < 40 → Human → 301 redirect to destination

CLI Reference

carom <command> [options]

Commands:
  start                    Start the redirect server
  add <url> [slug]         Create a new short link
  ls                       List all links with click stats
  rm <id|slug>             Deactivate a link
  stats <id|slug>          Show detailed click analytics
  rules ls                 List detection rules
  rules add <pattern>      Add custom bot pattern
  rules rm <id>            Remove a custom rule
  rules test <ua>          Test a user-agent string
  config ls                Show current config
  config set <key> <val>   Set a config value
  config reset             Reset to defaults
  install                  Install as system service (auto-start on boot)
  uninstall                Remove system service
  status                   Show server status
  logs                     Tail server logs

Global Options:
  --data-dir <path>        Data directory (default: ~/.carom)
  --port <number>          Server port (default: 3000)
  --host <addr>            Bind address (default: localhost)
  --api-key <key>          API key for the REST API
  -v, --verbose            Verbose logging

Service Management (Survives Reboots)

# Install as a system service
carom install --port 3000 --api-key your-secret-key
# macOS: creates ~/Library/LaunchAgents/com.carom.plist
# Linux: creates /etc/systemd/system/carom.service

# Check status
carom status

# View logs
carom logs

# Remove service (keeps data)
carom uninstall

REST API

All API endpoints require the x-api-key header (if an API key is configured).

Links

# Create a link
curl -X POST http://localhost:3000/api/links \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-key" \
  -d '{"url": "https://example.com", "slug": "my-link"}'

# List links
curl http://localhost:3000/api/links -H "x-api-key: your-key"

# Get link stats
curl http://localhost:3000/api/links/1/stats -H "x-api-key: your-key"

# Delete link
curl -X DELETE http://localhost:3000/api/links/1 -H "x-api-key: your-key"

Detection Rules

# List rules
curl http://localhost:3000/api/rules -H "x-api-key: your-key"

# Add a custom rule
curl -X POST http://localhost:3000/api/rules \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-key" \
  -d '{"type": "ua_pattern", "pattern": "CarrierIQ", "weight": 30}'

# Test a user-agent
curl -X POST http://localhost:3000/api/rules/test \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-key" \
  -d '{"userAgent": "curl/8.0"}'

Admin Dashboard

Access the web dashboard at http://localhost:3000/dashboard when the server is running.

Features:

• Create and manage short links
• View click analytics with human/bot breakdown
• Add and manage detection rules
• Test user-agent strings against the detection engine

Configuration

Config is stored in ~/.carom/config.json. Set values via CLI or env vars:

# Via CLI
carom config set shield.threshold 50
carom config set shield.mode interstitial
carom config set baseUrl https://yourdomain.com

# Via environment variables
SHIELD_ENABLED=true
SHIELD_THRESHOLD=40
SHIELD_MODE=direct
BASE_URL=https://yourdomain.com
API_KEY=your-secret
PORT=3000

Configuration Keys

| Key | Default | Description | |-----|---------|-------------| | port | 3000 | Server port | | host | localhost | Bind address | | baseUrl | (empty) | Public URL for generated short links | | apiKey | (empty) | API key (empty = open access) | | shield.enabled | true | Enable/disable bot protection | | shield.threshold | 40 | Bot score threshold (0-100) | | shield.mode | direct | direct or interstitial | | shield.safePage.title | Welcome | Safe page title | | shield.safePage.description | Visit our website... | Safe page description | | shield.safePage.brand | YourBrand | Safe page brand name |

Programmatic Usage

import { startServer } from 'carom';

const { app, server, db } = await startServer({
  port: 3000,
  host: 'localhost',
  apiKey: 'my-key',
  shield: {
    enabled: true,
    threshold: 40,
    mode: 'direct',
  },
});

Data Storage

All data is stored in ~/.carom/ (configurable via --data-dir):

~/.carom/
├── data.db          # SQLite database (links, clicks, rules)
├── config.json      # Configuration
├── carom.pid   # PID file (when running)
└── logs/
    ├── stdout.log   # Server output
    └── stderr.log   # Error output

License

MIT