docs: comprehensive ARCHITECTURE, DEPLOYMENT, API, and THREAT_MODEL

ARCHITECTURE.md
- Full component map with ASCII diagram
- Complete session lifecycle (init + heartbeat + failure path)
- Cryptographic protocol spec (hash chain formula, canonical JSON)
- Stack machine instruction set table with stack effects
- Behavioral validation thresholds
- SQLite schema, threat model summary, module reference

DEPLOYMENT.md
- Build instructions (WASM + server + convenience script)
- native binary, systemd (with hardened sandbox notes), Docker
- nginx, Nginx Proxy Manager, and HAProxy reverse proxy configs
- Integration options (sidecar vs proxy-only)
- Full configuration table with all constants
- Observability (RUST_LOG levels), health check, security checklist

API.md
- Full /init and /hb request/response schemas with field tables
- Canonical signing payload specification
- Complete validation rules table (all 13 rejection conditions)
- Hash chain byte-level specification
- WASM exported function reference

THREAT_MODEL.md
- Four attacker profiles (script kiddie → sophisticated adversary)
- Eight attack vectors with mitigations (replay, forgery, hijack, DoS…)
- Explicit out-of-scope limitations
- Operational security notes (CORS, TLS, log level, SQLite)
This commit is contained in:
thakares committed 2026-05-09 18:11:15 +05:30
1 parent 4b27a342d1
commit 2840ddfc58
1 file changed
+17 -17
+17 -17
View File
@@ -47,22 +47,22 @@ synchronisation burden alone makes scaled operation expensive.
┌─────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────┐
│ Browser │ │ Browser │
│ │ │ │
│ ┌─────────────┐ ┌──────────────┐ ┌─────────────┐ │ │ ┌─────────────┐ ┌──────────────┐ ┌─────────────┐ │
│ │ entropy.js │ │ heartbeat.js │ │ transport.js│ │ │ │ entropy.js │ │ heartbeat.js │ │ transport.js│ │
│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │
│ │ mousemove │──►│ orchestrates │──►│ fetch POST │ │ │ │ mousemove │──►│ orchestrates │──►│ fetch POST │ │
│ │ event ring │ │ init + HB │ │ /init /hb │ │ │ │ event ring │ │ init + HB │ │ /init /hb │ │
│ └─────────────┘ └──────┬───────┘ └─────────────┘ │ │ └─────────────┘ └──────┬───────┘ └─────────────┘ │
│ │ │ │ │ │
│ ┌──────▼───────────────────────┐ │ │ ┌──────▼───────────────────────┐ │
│ │ WASM Module (antibot_wasm) │ │ │ │ WASM Module (antibot_wasm) │ │
│ │ │ │ │ │ │ │
│ │ crypto.rs vm.rs │ │ │ │ crypto.rs vm.rs │ │
│ │ ├ generate_keypair() │ │ │ │ ├ generate_keypair() │ │
│ │ ├ sign_message() │ │ │ │ ├ sign_message() │ │
│ │ ├ compute_next_hash() │ │ │ │ ├ compute_next_hash() │ │
│ │ └ run_program() │ │ │ │ └ run_program() │ │
│ └───────────────────────────────┘ │ │ └──────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────┘
│ HTTPS │ HTTPS
┌─────────────────────────▼───────────────────────────────┐ ┌─────────────────────────▼───────────────────────────────┐
@@ -71,7 +71,7 @@ synchronisation burden alone makes scaled operation expensive.
│ routes/init.rs routes/heartbeat.rs │ │ routes/init.rs routes/heartbeat.rs │
│ │ │ │ │ │ │ │
│ └──────────┬───────────────┘ │ │ └──────────┬───────────────┘ │
│ ▼ │ │ ▼ │
│ session.rs │ │ session.rs │
│ ├ create_session() │ │ ├ create_session() │
│ └ verify_heartbeat() │ │ └ verify_heartbeat() │
@@ -111,7 +111,7 @@ Client Server
│ │ opcodes = generate_random_program(8..=16) │ │ opcodes = generate_random_program(8..=16)
│ │ INSERT INTO sessions … │ │ INSERT INTO sessions …
│ │ │ │
│◄── { session_id, salt, opcodes_b64, │ │◄── { session_id, salt, opcodes_b64, │
│ initial_hash, expires_at } ───────┤ │ initial_hash, expires_at } ───────┤
│ │ │ │
│ prevHash = initial_hash │ │ prevHash = initial_hash │
@@ -138,7 +138,7 @@ Client Server
│ sig = sign_message( │ │ sig = sign_message( │
│ JSON.stringify(signable, keys.sort))│ │ JSON.stringify(signable, keys.sort))│
│ │ │ │
├─── { session_id, prev_hash, timestamp,│ ├─── { session_id, prev_hash, timestamp, │
│ entropy_data, stack_state, │ │ entropy_data, stack_state, │
│ fingerprint, signature } ────────►│ │ fingerprint, signature } ────────►│
│ │ 1. Rate limit check │ │ 1. Rate limit check