# 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**
   ```bash
   git clone https://git.caileb.com/Caileb/Checkpoint.git
   cd Checkpoint
   ```
2. **Install dependencies**
   ```bash
   npm install
   ```
3. **Set up environment variables** (optional)
   Create a `.env` file in the project root:
   ```ini
   MAXMIND_ACCOUNT_ID=your_account_id
   MAXMIND_LICENSE_KEY=your_license_key
   PORT=8080           # Default: 3000
   ```
4. **Development mode**
   ```bash
   npm run dev
   ```
5. **Start the server**
   ```bash
   npm start
   ```
6. **Daemonize**
   ```bash
   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:
   ```bash
   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

```plaintext
.
├── 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
```