From fc2d693518ead8a831b0f12b1957ef691a2b7227 Mon Sep 17 00:00:00 2001 From: Sunil Thakares Date: Fri, 29 May 2026 22:34:13 +0530 Subject: [PATCH] Add comparison and performance tuning documentation --- docs/COMPARISON.md | 120 ++++++++++++++++ docs/PERFORMANCE-TUNING.md | 283 +++++++++++++++++++++++++++++++++++++ 2 files changed, 403 insertions(+) create mode 100644 docs/COMPARISON.md create mode 100644 docs/PERFORMANCE-TUNING.md diff --git a/docs/COMPARISON.md b/docs/COMPARISON.md new file mode 100644 index 0000000..4ddf090 --- /dev/null +++ b/docs/COMPARISON.md @@ -0,0 +1,120 @@ +# ChronoSeal vs Popular Anti-Bot Systems (2026) + +ChronoSeal is a **self-hosted, cryptographic attestation daemon**. This document compares it honestly with leading commercial solutions. + +## Quick Comparison + +| Solution | Type | Core Method | Privacy | Self-Hosted | Crypto Strength | Behavioral Analysis | Cost | Best For | +|----------------------------|-------------------|--------------------------------------|---------|-------------|-----------------|---------------------|---------------|------------------------------| +| **ChronoSeal** | Self-hosted Daemon| Ed25519 + Blake3 + **Gene Mutation** | Excellent | Yes | Very High | Light + Tunable | Free | Privacy + Control | +| Cloudflare Bot Management | Cloud Edge | JS Challenges + ML Fingerprinting | Medium | No | Medium | Strong | Freemium | Easy mass protection | +| Akamai Bot Manager | Enterprise Edge | Behavioral + Device Fingerprinting | Low | Hybrid | Medium | Very Strong | Very High | Large enterprises | +| HUMAN (PerimeterX) | Cloud SaaS | Behavioral Biometrics + ML | Low | No | Medium | Very Strong | Enterprise | Sophisticated bot defense | +| DataDome | Cloud SaaS | Real-time ML + Behavioral | Medium | No | Medium | Strong | Enterprise | E-commerce scraping | +| reCAPTCHA v3 | Google Service | Risk scoring + invisible challenges | Poor | No | Low | Medium | Free → Paid | Simple bot filtering | +| Kasada | Cloud SaaS | Proof-of-Work + Behavioral | Medium | No | High | Strong | Enterprise | Advanced automation | + +## Detailed Analysis + +### 1. ChronoSeal (v0.6.0) + +**Strengths:** +- Strongest **cryptographic foundation** (Ed25519 signatures + Blake3 hash chain + Synthetic Gene Mutation Engine) +- Fully **deterministic** server ↔ WASM parity +- Completely **invisible** to users with silent rejection +- Excellent **privacy** — no third-party tracking or fingerprint databases +- Highly **tunable** mutation strength (`gene_size` + `mutation_rounds`) +- Full control and auditability + +**Weaknesses:** +- Requires self-hosting and maintenance +- No global threat intelligence network like Cloudflare + +--- + +### 2. Cloudflare Bot Management + +**Strengths:** +- Extremely easy to deploy +- Excellent scale and global threat intelligence +- Good detection rates + +**Weaknesses vs ChronoSeal:** +- Relies heavily on fingerprinting and JS challenges +- Sends data to Cloudflare (privacy impact) +- Less transparent and auditable +- Vendor lock-in + +**Winner:** ChronoSeal for privacy-conscious teams + +--- + +### 3. Enterprise Solutions (Akamai, HUMAN, DataDome, Kasada) + +**Strengths:** +- Sophisticated ML + behavioral analysis +- Large threat intelligence databases +- Professional support + +**Weaknesses vs ChronoSeal:** +- Extremely expensive +- Black-box systems (limited visibility) +- Heavy data collection (privacy concerns) +- Vendor dependency + +**Winner:** ChronoSeal for teams wanting transparency and control + +--- + +### 4. reCAPTCHA v3 + +**Strengths:** +- Free tier available +- Easy integration + +**Weaknesses:** +- Heavy Google tracking +- Increasingly bypassed +- Poor privacy + +**Winner:** ChronoSeal by a large margin + +--- + +## When to Choose ChronoSeal + +**Choose ChronoSeal if you want:** + +- Maximum privacy +- Strong cryptographic guarantees +- Full control over your infrastructure +- Tunable defense strength +- No third-party data sharing +- Open source transparency + +**Choose Commercial Solutions if you want:** + +- Zero maintenance +- Massive global threat intelligence +- Enterprise support & SLAs +- Quick deployment at huge scale + +## Technical Differentiation + +ChronoSeal’s unique advantage is the **Synthetic Gene Mutation Engine** — a deterministic, server-controlled mutation sequence that both server and browser WASM must execute in sync. This creates a second synchronized state channel that is extremely difficult for automation to maintain at scale. + +No commercial solution currently offers equivalent cryptographic + mutation-based attestation in a self-hosted package. + +--- + +## Conclusion + +**ChronoSeal** is currently one of the strongest **open-source/self-hosted** anti-bot solutions available. It trades ease-of-use and global scale for **privacy, transparency, cryptographic strength, and control**. + +It is particularly well-suited for: +- Privacy-focused organizations +- High-value content platforms +- Teams that want to avoid vendor lock-in +- Developers who value auditability + +--- diff --git a/docs/PERFORMANCE-TUNING.md b/docs/PERFORMANCE-TUNING.md new file mode 100644 index 0000000..61c85c1 --- /dev/null +++ b/docs/PERFORMANCE-TUNING.md @@ -0,0 +1,283 @@ +# ChronoSeal Performance Tuning Guide + +ChronoSeal uses a deterministic Synthetic Gene Mutation Engine to strengthen browser session continuity validation. This guide explains how to tune the mutation engine for an appropriate balance between security strength, resource consumption, and user experience. + +The primary tuning parameters are: + +* `gene_size` — size of the synthetic gene buffer +* `mutation_rounds` — number of mutation iterations executed per heartbeat + +--- + +## Understanding the Mutation Engine + +For every accepted heartbeat, ChronoSeal executes a server-generated mutation program against a synthetic gene buffer. + +Increasing mutation complexity raises the computational cost of reproducing valid session state while also increasing CPU utilization on both the server and browser runtime. + +General effects: + +* Larger `gene_size` increases mutation state complexity. +* Higher `mutation_rounds` increase computational work per heartbeat. +* Both increase memory access and CPU consumption. +* Excessive values may negatively impact lower-end mobile devices. + +The optimal values depend on your threat model and expected client hardware. + +--- + +## Recommended Configurations + +| Profile | `gene_size` | `mutation_rounds` | Security Level | Recommended Usage | +| ----------------- | ----------- | ----------------- | ---------------- | -------------------------------- | +| Default | 512 | 4 | Moderate | Development and testing | +| Recommended | 2048 | 16 | Strong | Most production deployments | +| High Security | 4096 | 32 | Very Strong | Sensitive applications | +| Maximum Practical | 8192 | 64 | Extremely Strong | High-value targets | +| Experimental | 65536 | 65536 | Research Only | Benchmarking and experimentation | + +### Recommended Production Configuration + +```toml +gene_size = 2048 +mutation_rounds = 16 +``` + +This configuration provides a strong balance between security and runtime overhead for most deployments. + +--- + +## Configuration + +Edit your configuration file: + +```toml +# Mutation Engine Settings + +gene_size = 2048 +mutation_rounds = 16 +``` + +Common configuration locations: + +```text +/etc/chronoseal/config.toml +~/.config/chronoseal/config.toml +``` + +Restart ChronoSeal: + +```bash +sudo systemctl restart chronoseal +``` + +Validate the effective configuration: + +```bash +chronoseal config check --format yaml +``` + +--- + +## Performance Monitoring + +### Server-Side Monitoring + +View service logs: + +```bash +sudo journalctl -u chronoseal -f +``` + +Inspect runtime statistics: + +```bash +chronoseal stats --format json +``` + +Enable additional diagnostics when required: + +```bash +CHRONOSEAL_LOG=debug chronoseal run +``` + +Avoid debug logging in production environments. + +--- + +### Browser-Side Monitoring + +Measure mutation execution time: + +```javascript +console.time("gene-mutation"); + +const commitment = preview_gene_commitment( + order_b64, + session_id, + mutation_step, + mutation_rounds +); + +console.timeEnd("gene-mutation"); +``` + +Browser developer tools can also be used to monitor: + +* JavaScript execution time +* WASM execution time +* CPU utilization +* Memory consumption + +--- + +## Tuning Strategy + +### Step 1: Start with Recommended Values + +```toml +gene_size = 2048 +mutation_rounds = 16 +``` + +Deploy and observe normal usage patterns. + +### Step 2: Monitor Heartbeat Success Rates + +Watch for: + +* heartbeat failures +* increased browser CPU usage +* elevated mobile device latency +* increased battery consumption + +### Step 3: Increase Gradually + +Increase one parameter at a time. + +Recommended progression: + +```text +2048 / 16 +4096 / 16 +4096 / 32 +8192 / 32 +8192 / 64 +``` + +This makes it easier to identify performance bottlenecks. + +### Step 4: Test Mobile Devices + +Always test on: + +* Android devices +* iPhones +* older laptops +* low-power CPUs + +Desktop-only validation can be misleading. + +--- + +## Advanced Deployment Strategies + +### Risk-Based Mutation Strength + +Future deployments may choose to dynamically increase mutation strength based on: + +* session age +* failed heartbeat history +* suspicious behavior signals +* protected resource sensitivity + +Example policy: + +```text +New session → 2048 / 16 +Suspicious session → 4096 / 32 +Elevated-risk action → 8192 / 64 +``` + +--- + +## Performance Recommendations + +### WASM Builds + +Always use optimized builds: + +```bash +wasm-pack build wasm --target web --release +``` + +### General Guidance + +* Keep `mutation_rounds` below 64 for most deployments. +* Prefer increasing `gene_size` before dramatically increasing rounds. +* Benchmark on representative client hardware. +* Monitor browser CPU utilization during load testing. +* Re-evaluate settings after major algorithm changes. + +### Storage Performance + +For maximum throughput: + +```toml +db_type = "sqlite-in-memory" +``` + +For persistence: + +```toml +db_type = "sqlite-in-disk" +``` + +Choose based on operational requirements rather than mutation settings. + +--- + +## Security Considerations + +Higher values increase the cost of reproducing valid session state but do not provide absolute protection against determined attackers. + +ChronoSeal remains a cost-raising attestation layer rather than a complete anti-abuse solution. + +Mutation tuning should be considered alongside: + +* heartbeat timing controls +* signature validation +* hash-chain continuity +* behavioral trust checks +* rate limiting +* session expiration + +--- + +## Recommended Starting Point + +For most production deployments: + +```toml +gene_size = 2048 +mutation_rounds = 16 +``` + +This configuration provides a strong balance between security, performance, and compatibility across desktop and mobile devices. + +--- + +## Related Documentation + +* `docs/ARCHITECTURE.md` +* `docs/API.md` +* `docs/THREAT_MODEL.md` +* `docs/REFRACTORING-v0.6.0.md` + +For diagnostics: + +```bash +chronoseal config check +chronoseal stats +chronoseal health +```