Checkpoint

Secure, extensible, high-performance Node.js middleware server for proof-of-work security, IP filtering, reverse proxying, and real-time analytics.

Features:

• 🔐 Checkpoint Security: Enforce proof-of-work (PoW) and proof-of-space-time (PoST) challenges before granting access.
• 🌎 IP & Geo-Blocking: Block or allow traffic based on country, continent, or ASN using MaxMind GeoIP2.
• 🔀 Reverse Proxy: Route incoming requests to backend services based on hostname mappings.
• 📊 Real-time Stats: Collect detailed metrics and browse via built-in web UI or API.
• 🧩 Plugin Architecture: Easily extend and customize via modular plugins.
• 🛠️ Flexible Configuration: Manage settings in TOML files and via environment variables.
• ⚙️ Daemon & PM2 Support: Run as a background service with built-in daemon mode or PM2.
• 📂 Data Persistence: Secure token storage with LevelDB + TTL and HMAC protection.

🚀 Quick Start

1. Clone the repository

   git clone https://git.caileb.com/Caileb/Checkpoint.git
   cd Checkpoint
   

2. Install dependencies

   npm install
   

3. Set up environment variables (optional) Create a .env file in the project root:

   MAXMIND_ACCOUNT_ID=your_account_id
   MAXMIND_LICENSE_KEY=your_license_key
   PORT=8080           # Default: 3000
   

4. Development mode

   npm run dev
   

5. Start the server

   npm start
   

6. Daemonize

   npm run daemon     # Start in background
   npm run stop       # Stop daemon
   npm run restart    # Restart daemon
   npm run logs       # Show logs
   

   Or use PM2 directly:

   pm2 start index.js --name checkpoint
   

⚙️ Configuration

All core settings are stored in the config/ directory as TOML files:

• checkpoint.toml — PoW/PoST parameters, tokens, exclusions, interstitial templates.
• ipfilter.toml — Country, continent, ASN filtering rules and custom block pages.
• proxy.toml — Hostname-to-backend mappings and timeouts.
• stats.toml — Metrics TTL and paths for UI/API.

Override any setting via environment variables or by editing these files directly.

📂 Directory Structure

.
├── config/                # TOML configuration files
├── data/                  # Runtime data (secrets, snapshots)
├── db/                    # LevelDB token stores
├── plugins/               # Plugin modules (checkpoint, ipfilter, proxy, stats)
├── pages/                 # Static assets and UI templates
│   ├── interstitial/      # Proof-of-work challenge pages
│   ├── ipfilter/          # Custom block pages
│   └── stats/             # Statistics web UI
├── utils/                 # Internal utilities (logging, network, proof, time)
├── index.js               # Core server & plugin loader
├── checkpoint.js          # Checkpoint security middleware
├── package.json           # Project metadata & scripts
└── README.md              # This file