Websocket Fixes & New Config Examples

config/checkpoint.toml.example

@@ -0,0 +1,123 @@
+# =============================================================================
+# CHECKPOINT SECURITY CONFIGURATION
+# =============================================================================
+# This configuration controls the checkpoint security middleware that protects
+# your services with proof-of-work challenges and token-based authentication.
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# CORE SETTINGS
+# -----------------------------------------------------------------------------
+[Core]
+# Enable or disable the checkpoint system entirely
+Enabled = true
+
+# Cookie name for storing checkpoint tokens
+CookieName = "checkpoint_token"
+
+# Cookie domain (empty = host-only cookie for localhost)
+# Set to ".yourdomain.com" for all subdomains
+CookieDomain = ""
+
+# Enable URL path sanitization to prevent path traversal attacks
+SanitizeURLs = true
+
+# -----------------------------------------------------------------------------
+# PROOF OF WORK SETTINGS
+# -----------------------------------------------------------------------------
+[ProofOfWork]
+# Number of leading zeros required in the SHA-256 hash
+Difficulty = 4
+
+# Random salt length in bytes
+SaltLength = 16
+
+# Time allowed to solve a challenge before it expires
+ChallengeExpiration = "3m"
+
+# Maximum attempts per IP address per hour
+MaxAttemptsPerHour = 10
+
+# -----------------------------------------------------------------------------
+# PROOF OF SPACE-TIME SETTINGS (Optional additional verification)
+# -----------------------------------------------------------------------------
+[ProofOfSpaceTime]
+# Enable consistency checks for PoS-Time verification
+Enabled = true
+
+# Maximum allowed ratio between slowest and fastest PoS runs
+ConsistencyRatio = 1.35
+
+# -----------------------------------------------------------------------------
+# TOKEN SETTINGS
+# -----------------------------------------------------------------------------
+[Token]
+# How long tokens remain valid
+Expiration = "24h"
+
+# Maximum age for used nonces before cleanup
+MaxNonceAge = "24h"
+
+# -----------------------------------------------------------------------------
+# STORAGE PATHS
+# -----------------------------------------------------------------------------
+[Storage]
+# HMAC secret storage location
+SecretPath = "./data/checkpoint_secret.json"
+
+# Token database directory
+TokenDBPath = "./db/tokenstore"
+
+# Interstitial page templates (in order of preference)
+InterstitialTemplates = [
+  "/pages/interstitial/page.html",
+  "/pages/ipfilter/default.html"
+]
+
+# -----------------------------------------------------------------------------
+# EXCLUSION RULES
+# -----------------------------------------------------------------------------
+# Define which requests should bypass the checkpoint system.
+# Each rule can specify:
+#   - Path (required): URL path or prefix to match
+#   - Hosts (optional): Specific hostnames this rule applies to
+#   - UserAgents (optional): User-Agent patterns to match
+# -----------------------------------------------------------------------------
+
+[[Exclusion]]
+# Skip checkpoint for all API endpoints
+Path = "/api"
+Hosts = ["api.example.com"]  # Optional: only for specific hosts
+
+[[Exclusion]]
+# Allows Git operations
+Path = "/info/refs"
+Hosts = ["git.example.com"]
+
+[[Exclusion]]
+# Skip checkpoint for metrics endpoint
+Path = "/metrics"
+
+# [[Exclusion]]
+# Example: Mobile app API with specific user agent
+# Path = "/mobile-api"
+# UserAgents = ["MyApp/", "Dart/"]
+
+# -----------------------------------------------------------------------------
+# BYPASS KEYS
+# -----------------------------------------------------------------------------
+# Special keys that can bypass the checkpoint when provided
+
+[[BypassKeys]]
+# Query parameter bypass
+Type = "query"
+Key = "bypass_key"
+Value = "your-secret-key-here"
+Hosts = ["music.example.com"]  # Optional: restrict to specific hosts
+
+[[BypassKeys]]
+# Header bypass
+Type = "header"
+Key = "X-Bypass-Token"
+Value = "another-secret-key"
+# Hosts = []  # If empty or omitted, applies to all hosts