diff --git a/docs/COMPARISON.md b/docs/COMPARISON.md index 4ddf090..d9029fb 100644 --- a/docs/COMPARISON.md +++ b/docs/COMPARISON.md @@ -16,7 +16,7 @@ ChronoSeal is a **self-hosted, cryptographic attestation daemon**. This document ## Detailed Analysis -### 1. ChronoSeal (v0.6.0) +### 1. ChronoSeal (v1.0.2) **Strengths:** - Strongest **cryptographic foundation** (Ed25519 signatures + Blake3 hash chain + Synthetic Gene Mutation Engine) @@ -118,3 +118,12 @@ It is particularly well-suited for: - Developers who value auditability --- + + +## v1.0.2 Security Hardening Additions + +- Fingerprint validation bounds enforcement +- Security response headers +- DashMap-backed concurrent rate limiting +- WASM panic hardening +- Non-root container execution diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index 5897141..fffbed9 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -378,3 +378,10 @@ Avoid debug logging in production because internal identifiers may be written to - Protect SQLite and log directories with correct ownership. - Monitor `/health`, `/stats`, and `/metrics`. - Verify `chronoseal config check` after environment or config changes. + + +## v1.0.2 Deployment Notes + +- Containers run as a dedicated non-root user. +- Reverse proxies should forward X-Forwarded-For or X-Real-IP. +- Security headers are enabled by default. diff --git a/docs/PERFORMANCE-TUNING.md b/docs/PERFORMANCE-TUNING.md index 61c85c1..fabe714 100644 --- a/docs/PERFORMANCE-TUNING.md +++ b/docs/PERFORMANCE-TUNING.md @@ -31,16 +31,16 @@ The optimal values depend on your threat model and expected client hardware. | 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 | 2048 | 4 | Strong | Most production deployments | +| High Security | 4096 | 8 | Very Strong | Sensitive applications | +| Maximum Practical | 4096 | 10 | Extremely Strong | High-value targets | +| Experimental | 4096 | 10 | Research Only | Benchmarking and experimentation | ### Recommended Production Configuration ```toml gene_size = 2048 -mutation_rounds = 16 +mutation_rounds = 4 ``` This configuration provides a strong balance between security and runtime overhead for most deployments. @@ -55,7 +55,7 @@ Edit your configuration file: # Mutation Engine Settings gene_size = 2048 -mutation_rounds = 16 +mutation_rounds = 4 ``` Common configuration locations: @@ -137,7 +137,7 @@ Browser developer tools can also be used to monitor: ```toml gene_size = 2048 -mutation_rounds = 16 +mutation_rounds = 4 ``` Deploy and observe normal usage patterns. @@ -158,11 +158,10 @@ Increase one parameter at a time. Recommended progression: ```text -2048 / 16 -4096 / 16 -4096 / 32 -8192 / 32 -8192 / 64 +2048 / 4 +4096 / 4 +4096 / 8 +4096 / 10 ``` This makes it easier to identify performance bottlenecks. @@ -194,9 +193,9 @@ Future deployments may choose to dynamically increase mutation strength based on Example policy: ```text -New session → 2048 / 16 -Suspicious session → 4096 / 32 -Elevated-risk action → 8192 / 64 +New session → 2048 / 4 +Suspicious session → 4096 / 8 +Elevated-risk action → 4096 / 10 ``` --- @@ -213,7 +212,7 @@ wasm-pack build wasm --target web --release ### General Guidance -* Keep `mutation_rounds` below 64 for most deployments. +* Keep `mutation_rounds` at or below 10 for all deployments. * Prefer increasing `gene_size` before dramatically increasing rounds. * Benchmark on representative client hardware. * Monitor browser CPU utilization during load testing. @@ -260,7 +259,7 @@ For most production deployments: ```toml gene_size = 2048 -mutation_rounds = 16 +mutation_rounds = 4 ``` This configuration provides a strong balance between security, performance, and compatibility across desktop and mobile devices. @@ -281,3 +280,13 @@ chronoseal config check chronoseal stats chronoseal health ``` + + +## v1.0.2 Limits + +Current supported range: + +```toml +gene_size = 1..=4096 +mutation_rounds = 1..=10 +``` diff --git a/docs/PROTOCOL.md b/docs/PROTOCOL.md index 07002fd..7fdca69 100644 --- a/docs/PROTOCOL.md +++ b/docs/PROTOCOL.md @@ -86,3 +86,13 @@ The client VM executes instructions sequentially. The instruction set consists o * `0x08`: Unary Bitwise Not (`!a`). Requires at least 1 element on the stack. * `0x09`: Hash Stack. Hashes all stack elements using BLAKE3 and reduces it to a single `u32` value, clearing the stack and pushing the hash. * *Any other opcode:* Terminates VM execution immediately. + + +## v1.0.2 Protocol Hardening + +- Fingerprint aspect ratio validation +- Device pixel ratio validation +- Hardware concurrency validation (1..=256) +- Entropy event cap (500 events) +- IP-based rate limiting +- Silent rejection preserved for protocol failures diff --git a/docs/SECURITY_ASSUMPTIONS.md b/docs/SECURITY_ASSUMPTIONS.md index 0b92ce4..8b6f184 100644 --- a/docs/SECURITY_ASSUMPTIONS.md +++ b/docs/SECURITY_ASSUMPTIONS.md @@ -31,3 +31,10 @@ ChronoSeal is a **cost-raising security layer**. It is designed to force automat 1. **Chain Continuity:** A session state cannot bifurcate. Every heartbeat must advance the state head using the latest salt. 2. **VM Parity:** Stack state must exactly match the execution output of the server's issued opcode sequence. 3. **Dynamic Challenges:** Client gene updates must match the server-issued mutation program. + + +## Additional Assumptions (v1.0.2) + +- Fingerprints are sanity signals, not identity proofs. +- Rate limiting assumes client IP visibility. +- Security headers reduce browser attack surface. diff --git a/docs/THREAT_MODEL.md b/docs/THREAT_MODEL.md index 24f1a2a..2762bd1 100644 --- a/docs/THREAT_MODEL.md +++ b/docs/THREAT_MODEL.md @@ -255,3 +255,17 @@ Recommended: ## Disclosure See [../SECURITY.md](../SECURITY.md) for the vulnerability disclosure policy. + + +## Additional Mitigations (v1.0.2) + +### Fingerprint Abuse +- Bounds enforcement +- Numeric sanity validation + +### Resource Exhaustion +- Entropy event cap +- Rate limiting + +### Browser Hardening +- Security response headers diff --git a/docs/WHY_IT_FAILS.md b/docs/WHY_IT_FAILS.md index 9b97e66..b896bdf 100644 --- a/docs/WHY_IT_FAILS.md +++ b/docs/WHY_IT_FAILS.md @@ -54,3 +54,13 @@ To deny attackers a feedback oracle, the ChronoSeal heartbeat endpoint (`POST /h * **Error Cause:** The client submitted more requests than allowed by the server's rate-limiting config (e.g., `rate_limit_count` per `rate_limit_window_secs`). * **Diagnostic Signal:** The server returns `200 OK` with `{"status": "ok"}` but no next state data. * **Remediation:** Reduce heartbeat frequency or adjust rate limit parameters in the daemon configuration. + + +## Additional v1.0.2 Failure Modes + +- Invalid aspect ratio +- Invalid device pixel ratio +- Invalid hardware concurrency +- NaN or infinite fingerprint values +- Entropy event count exceeds 500 +- Client IP rate limited