82 lines
No EOL
3.1 KiB
Markdown
82 lines
No EOL
3.1 KiB
Markdown
# 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
|
|
``` |