nx9-chronoseal-rs/docs/ARCHITECTURE.md

ChronoSeal Architecture

ChronoSeal is a Unix-native cryptographic attestation daemon that validates browser session continuity through deterministic VM execution, chained cryptographic state, and a shared Synthetic Gene Mutation Engine.

Overview

ChronoSeal is designed as a production-grade infrastructure component, not as a consumer-facing widget. It is a lightweight daemon that can be operated, monitored, and integrated like any other native Linux service.

Key characteristics:

• Unix-native daemon with systemd-compatible lifecycle
• CLI-first control plane and configuration
• Shared Rust/WASM runtime for server/client parity
• Modular storage backend abstraction (sqlite-in-memory, sqlite-disk, valkey)
• Silent rejection semantics for attacker resilience
• Privacy-preserving ephemeral session state

Core Components

shared/

Shared protocol and runtime primitives used by both the server and the browser runtime:

• Cryptographic primitives: Blake3, Ed25519
• Hash chain logic and session commitment handling
• Synthetic gene model and deterministic mutation engine
• Serialization, encoding, and canonical signing helpers

server/

The server crate implements the runtime daemon:

• routes/init.rs — session initialization API
• routes/heartbeat.rs — heartbeat verification API
• session.rs — session lifecycle, mutation parity, and heartbeat validation
• storage.rs — backend abstraction and persistence
• crypto.rs — signature verification and key handling
• trust.rs — behavioral entropy and sanity validation
• ratelimit.rs — per-session request throttling
• cleanup.rs — expiration and eviction tasks
• runtime.rs — daemon bootstrap, metrics, and state management

wasm/

The client runtime crate compiles to WebAssembly and powers attestation in the browser.

• crypto.rs — in-WASM signing and hash computation
• vm.rs — randomized opcode VM execution
• vm_extensions.rs — synthetic gene mutation preview and commit lifecycle

frontend/

Static browser integration code that loads the WASM module, orchestrates init/heartbeat flow, and collects browser entropy.

v0.6.0 Innovation

The primary innovation in v0.6.0 is the Synthetic Gene Mutation Engine.

This layer adds a deterministic, shared server/WASM mutation handshake to the existing heartbeat continuity model.

Key v0.6.0 behavior:

• mutation_order_b64 is issued at session initialization and after every accepted heartbeat
• mutation_step is tracked on both client and server
• gene_commitment is computed locally in WASM and validated by the server
• mutation state is persisted per session and advanced only on accepted heartbeats
• scalar mutation programs are deterministic and bounded in cost

This makes replay and tampering attacks significantly more expensive while preserving the existing privacy-first and silent-failure semantics.

Architecture Diagram

Browser                                Server
  ┌──────────────────────────────────────────────────────────────┐
  │ frontend/ + WASM runtime                                      │
  │  - generate_keypair()                                         │
  │  - sign_message()                                             │
  │  - compute_next_hash()                                        │
  │  - run_program()                                              │
  │  - preview_gene_commitment()                                  │
  │  - commit_gene_preview()                                      │
  │                                                              │
  │  POST /init ->                                              │
  │  POST /hb   ->                                              │
  └──────────────────────────────────────────────────────────────┘
                       │
                       ▼
  ┌──────────────────────────────────────────────────────────────┐
  │ server/                                                      │
  │  - signature validation                                       │
  │  - hash chain continuity                                      │
  │  - rate limiting                                              │
  │  - behavioral trust checks                                    │
  │  - mutation step validation                                   │
  │  - gene commitment verification                               │
  │  - session persistence                                        │
  │  - metrics and health                                          │
  └──────────────────────────────────────────────────────────────┘
                       │
                       ▼
  ┌──────────────────────────────────────────────────────────────┐
  │ storage backends                                              │
  │  - sqlite-in-memory                                            │
  │  - sqlite-disk                                                 │
  │  - valkey compatibility mode                                   │
  └──────────────────────────────────────────────────────────────┘

Storage Backends

ChronoSeal supports pluggable backend modes using the db_type configuration option.

• sqlite-in-memory — default ephemeral session storage. No persistence across restarts.
• sqlite-disk — persisted SQLite database on disk through db_path.
• valkey — compatibility mode for alternative storage backends, currently supported alongside SQLite compatibility semantics.

Runtime Philosophy

ChronoSeal is intentionally designed to behave like traditional Unix infrastructure software:

• explicit CLI operations (run, status, health, config, metrics, stats, db-type)
• structured logging for journalctl
• PID file management and graceful shutdown
• systemd sandbox support
• runtime configuration via TOML and CLI overrides
• clear separation of protocol, persistence, and runtime concerns

Integration Points

• Browser clients consume the WASM module and call /init and /hb
• Existing sites can proxy these API routes through their own web server
• Frontend assets can be served by ChronoSeal directly or mounted in a sidecar deployment
• TLS termination should be handled by a reverse proxy in production

Operating Assumptions

ChronoSeal is not a general-purpose authentication service. It is a cryptographic attestation and anti-automation layer intended to be integrated with existing site logic.

It assumes:

• browser clients can execute WASM
• heartbeats will arrive every 12–25 seconds
• session state can be safely persisted in SQLite or Valkey
• service operators want Unix-native systemd deployment and observability