carom-link 1.0.0

package/README.md

@@ -0,0 +1,221 @@
+# 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
+
+```bash
+# Global install
+npm install -g carom
+
+# Or use npx
+npx carom start
+```
+
+Requires Node.js ≥ 18.
+
+## Quick Start
+
+```bash
+# 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)
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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:
+
+```bash
+# 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
+
+```js
+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

package/bin/carom.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../src/cli/index.js';

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "carom-link",
+  "version": "1.0.0",
+  "description": "Link redirect server with bot and automated traffic protection, plus CLI management",
+  "type": "module",
+  "bin": {
+    "carom": "./bin/carom.js"
+  },
+  "main": "src/server/server.js",
+  "exports": {
+    ".": "./src/server/server.js",
+    "./shield": "./src/cloak/detector.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "public/"
+  ],
+  "scripts": {
+    "start": "node bin/carom.js start",
+    "dev": "node --watch bin/carom.js start --verbose"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "carom",
+    "link",
+    "redirect",
+    "bot-detection",
+    "carrier",
+    "shortener"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "better-sqlite3": "^11.0.0",
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.0",
+    "express": "^4.21.0",
+    "express-rate-limit": "^7.4.0",
+    "helmet": "^8.0.0",
+    "nanoid": "^5.0.0"
+  }
+}