146 lines
7.4 KiB
Markdown
146 lines
7.4 KiB
Markdown
# 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
|