537 lines
11 KiB
Markdown
537 lines
11 KiB
Markdown
# ChronoSeal
|
||
|
||
<p align="center">
|
||
<img src="logo/chronoseal.svg" width="220" alt="ChronoSeal Logo">
|
||
</p>
|
||
|
||
<p align="center">
|
||
<strong>Cryptographic attestation daemon and anti-automation framework.</strong>
|
||
</p>
|
||
|
||
<p align="center">
|
||
Privacy-preserving • Unix-native • Lightweight • WASM-powered
|
||
</p>
|
||
|
||
---
|
||
|
||
ChronoSeal is a lightweight cryptographic attestation daemon designed to raise the operational cost of browser automation, scraping, replay attacks, and synthetic interaction.
|
||
|
||
Instead of relying on:
|
||
|
||
* CAPTCHA systems
|
||
* invasive browser fingerprinting
|
||
* telemetry-heavy tracking
|
||
* persistent identifiers
|
||
|
||
ChronoSeal establishes a continuous cryptographic proof-of-runtime continuity using:
|
||
|
||
* WASM execution
|
||
* chained cryptographic heartbeats
|
||
* behavioral entropy validation
|
||
* ephemeral attestation state
|
||
|
||
while remaining completely invisible and frictionless to legitimate human users.
|
||
|
||
---
|
||
|
||
# Features
|
||
|
||
* CLI-first Unix-native architecture
|
||
* Rich operational subcommands
|
||
* Machine-readable JSON/YAML outputs
|
||
* Hardened systemd integration
|
||
* Graceful shutdown and signal handling
|
||
* One-line installation workflow
|
||
* Prometheus-compatible metrics
|
||
* WASM-based client runtime
|
||
* Ed25519 + Blake3 cryptographic chaining
|
||
* Behavioral entropy validation
|
||
* Randomized stack-machine verification
|
||
* Silent rejection model
|
||
* SQLite-backed ephemeral sessions
|
||
* Connection-pooled runtime architecture
|
||
* Lightweight deployment footprint
|
||
* Docker and native deployment support
|
||
|
||
---
|
||
|
||
# Quick Start
|
||
|
||
## Install
|
||
|
||
```bash
|
||
sudo bash scripts/install.sh
|
||
```
|
||
|
||
## Check Status
|
||
|
||
```bash
|
||
chronoseal status --format json
|
||
```
|
||
|
||
## Health Probe
|
||
|
||
```bash
|
||
chronoseal health
|
||
```
|
||
|
||
## View Metrics
|
||
|
||
```bash
|
||
chronoseal metrics
|
||
```
|
||
|
||
## View Logs
|
||
|
||
```bash
|
||
sudo journalctl -u chronoseal -f
|
||
```
|
||
|
||
---
|
||
|
||
# CLI
|
||
|
||
```bash
|
||
chronoseal --help
|
||
```
|
||
|
||
## Available Commands
|
||
|
||
| Command | Description |
|
||
| ------------ | ------------------------------------------ |
|
||
| `run` | Run the ChronoSeal daemon |
|
||
| `status` | Report daemon status |
|
||
| `health` | Perform daemon health probe |
|
||
| `config` | Validate and print effective configuration |
|
||
| `generate` | Generate operational material |
|
||
| `metrics` | Output Prometheus metrics |
|
||
| `stats` | Print runtime statistics |
|
||
| `completion` | Generate shell completions |
|
||
| `version` | Print version/build information |
|
||
|
||
---
|
||
|
||
## Example
|
||
|
||
```bash
|
||
chronoseal status --format json
|
||
```
|
||
|
||
```json
|
||
{
|
||
"running": true,
|
||
"healthy": true,
|
||
"bind": "0.0.0.0:3000",
|
||
"pid_file": "/run/chronoseal.pid",
|
||
"pid": 79459
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
# How It Works
|
||
|
||
ChronoSeal establishes a continuous cryptographic proof-of-presence for browser sessions.
|
||
|
||
The system is inspired by heartbeat validation models used in embedded and distributed systems.
|
||
|
||
## Session Flow
|
||
|
||
```text
|
||
Browser Server
|
||
│ │
|
||
│ WASM loads, generates Ed25519 keypair │
|
||
│ Private key never leaves WASM memory │
|
||
│ │
|
||
├──── POST /init { public_key } ──────────►│
|
||
│◄─── { session_id, salt, opcodes, H0 } ────┤
|
||
│ │
|
||
│ Every 12–25s (randomized): │
|
||
│ ┌─ Collect behavioral entropy │
|
||
│ ├─ Execute VM opcode program │
|
||
│ ├─ Advance Blake3 hash chain │
|
||
│ └─ Sign payload using Ed25519 │
|
||
│ │
|
||
├──── POST /heartbeat { signed_payload } ─►│
|
||
│◄─── { status, next_salt } ────────────────┤
|
||
│ │
|
||
│ Invalid sessions silently rejected │
|
||
```
|
||
|
||
The server validates:
|
||
|
||
* signature authenticity
|
||
* heartbeat continuity
|
||
* replay resistance
|
||
* behavioral entropy
|
||
* timestamp validity
|
||
* fingerprint sanity
|
||
|
||
---
|
||
|
||
# Security Model
|
||
|
||
## What ChronoSeal Protects Against
|
||
|
||
| Threat | Mechanism |
|
||
| ------------------------ | ------------------------------------- |
|
||
| Replay attacks | Blake3 chained heartbeat continuity |
|
||
| Signature forgery | Ed25519 keypair generated inside WASM |
|
||
| Session cloning | Ephemeral session-bound keypairs |
|
||
| Static scraping | Runtime participation requirements |
|
||
| Naive browser automation | Behavioral continuity validation |
|
||
| Timestamp replay | Drift-window enforcement |
|
||
| Session flooding | Per-session rate limiting |
|
||
|
||
---
|
||
|
||
## Silent Rejection Model
|
||
|
||
ChronoSeal intentionally avoids explicit rejection semantics.
|
||
|
||
Invalid sessions may still receive:
|
||
|
||
```json
|
||
{ "status": "ok" }
|
||
```
|
||
|
||
This prevents:
|
||
|
||
* oracle-style probing
|
||
* protocol learning
|
||
* easy automation tuning
|
||
* behavioral enumeration
|
||
|
||
---
|
||
|
||
## What ChronoSeal Does Not Claim
|
||
|
||
ChronoSeal is a cost-raising mechanism, not an impenetrable barrier.
|
||
|
||
A sufficiently motivated adversary with:
|
||
|
||
* real browsers
|
||
* genuine input devices
|
||
* enough reverse engineering effort
|
||
|
||
can eventually bypass the system.
|
||
|
||
The goal is to make automation:
|
||
|
||
* expensive
|
||
* operationally complex
|
||
* difficult to scale
|
||
* harder to replay deterministically
|
||
|
||
---
|
||
|
||
# Architecture
|
||
|
||
```text
|
||
chronoseal-rs/
|
||
├── shared/ Shared types, constants, hash-chain logic
|
||
├── server/ Axum HTTP daemon
|
||
│ ├── routes/ API routes
|
||
│ ├── session.rs Session lifecycle management
|
||
│ ├── crypto.rs Ed25519 verification
|
||
│ ├── trust.rs Behavioral validation
|
||
│ ├── fingerprint/ Browser sanity validation
|
||
│ ├── vm.rs Random opcode generator
|
||
│ ├── ratelimit.rs Token bucket limiter
|
||
│ ├── cleanup.rs Session expiration lifecycle
|
||
│ └── metrics.rs Prometheus metrics
|
||
├── wasm/ Rust → WASM runtime
|
||
│ ├── crypto.rs Signing + hash chaining
|
||
│ └── vm.rs Stack-machine executor
|
||
├── frontend/ Lightweight JS integration
|
||
├── scripts/ Build/install/dev scripts
|
||
└── docs/ Project documentation
|
||
```
|
||
|
||
---
|
||
|
||
# Stack Machine
|
||
|
||
ChronoSeal includes a lightweight randomized stack-machine execution engine.
|
||
|
||
The server generates a randomized opcode program during session initialization.
|
||
|
||
The client executes this program on every heartbeat and includes the resulting stack state in the signed payload.
|
||
|
||
This makes heartbeat payloads structurally dynamic.
|
||
|
||
## Supported Opcodes
|
||
|
||
| Opcode | Mnemonic | Effect |
|
||
| ------ | -------- | ----------------------- |
|
||
| `0x00` | PUSH | Push literal |
|
||
| `0x01` | ADD | Wrapping addition |
|
||
| `0x02` | SUB | Wrapping subtraction |
|
||
| `0x03` | MUL | Wrapping multiplication |
|
||
| `0x04` | XOR | Bitwise XOR |
|
||
| `0x05` | AND | Bitwise AND |
|
||
| `0x06` | OR | Bitwise OR |
|
||
| `0x07` | ROT | Rotate left |
|
||
| `0x08` | NOT | Unary inversion |
|
||
| `0x09` | HASH | Blake3 stack hash |
|
||
|
||
---
|
||
|
||
# Hash Chain
|
||
|
||
ChronoSeal uses Blake3 chained continuity validation.
|
||
|
||
## Initial Hash
|
||
|
||
```text
|
||
H(0) = Blake3( session_id ║ public_key ║ salt₀ )
|
||
```
|
||
|
||
## Heartbeat Progression
|
||
|
||
```text
|
||
H(n) = Blake3(
|
||
saltₙ₋₁ ║
|
||
H(n-1) ║
|
||
timestamp ║
|
||
Blake3(entropy_json) ║
|
||
Blake3(stack_json)
|
||
)
|
||
```
|
||
|
||
Each heartbeat depends on:
|
||
|
||
* prior continuity
|
||
* prior server-issued salt
|
||
* behavioral entropy
|
||
* VM execution result
|
||
* timestamp progression
|
||
|
||
---
|
||
|
||
# Signature Canonicalization
|
||
|
||
Heartbeat payloads are serialized into canonical key order before signing.
|
||
|
||
The server reconstructs payloads identically before:
|
||
|
||
* Ed25519 verification
|
||
* hash progression validation
|
||
|
||
This prevents:
|
||
|
||
* serialization inconsistencies
|
||
* ambiguous signing layouts
|
||
* malformed payload tricks
|
||
|
||
---
|
||
|
||
# SQLite Schema
|
||
|
||
```sql
|
||
CREATE TABLE IF NOT EXISTS sessions (
|
||
session_id TEXT PRIMARY KEY,
|
||
public_key BLOB NOT NULL,
|
||
salt BLOB NOT NULL,
|
||
last_hash BLOB NOT NULL,
|
||
chain_length INTEGER NOT NULL DEFAULT 1,
|
||
created_at INTEGER NOT NULL,
|
||
last_seen INTEGER NOT NULL,
|
||
expires_at INTEGER NOT NULL
|
||
);
|
||
```
|
||
|
||
ChronoSeal intentionally uses ephemeral session persistence.
|
||
|
||
Session continuity is designed to reset transparently.
|
||
|
||
---
|
||
|
||
# Runtime Architecture
|
||
|
||
## Server Runtime
|
||
|
||
* Rust
|
||
* Axum
|
||
* Tokio
|
||
* SQLite
|
||
* `r2d2`
|
||
* `thiserror`
|
||
|
||
## Browser Runtime
|
||
|
||
* Rust → WASM
|
||
* Ed25519 signing
|
||
* Blake3 chaining
|
||
* stack-machine execution
|
||
|
||
---
|
||
|
||
# Deployment
|
||
|
||
## Recommended Installation
|
||
|
||
```bash
|
||
sudo bash scripts/install.sh
|
||
```
|
||
|
||
The installer:
|
||
|
||
* creates `chronoseal` service user
|
||
* builds release artifacts
|
||
* installs frontend assets
|
||
* deploys hardened systemd service
|
||
* enables and starts daemon
|
||
|
||
---
|
||
|
||
## Manual Installation
|
||
|
||
```bash
|
||
bash scripts/build.sh
|
||
|
||
sudo cp target/release/chronoseal /usr/local/bin/
|
||
sudo cp chronoseal.service /etc/systemd/system/
|
||
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable --now chronoseal
|
||
```
|
||
|
||
---
|
||
|
||
## Docker
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
```
|
||
|
||
---
|
||
|
||
# Development
|
||
|
||
## Full Build
|
||
|
||
```bash
|
||
bash scripts/build.sh
|
||
```
|
||
|
||
## Development Mode
|
||
|
||
```bash
|
||
bash scripts/dev.sh
|
||
```
|
||
|
||
## Direct Execution
|
||
|
||
```bash
|
||
cargo run -p server -- run --bind 127.0.0.1:3000
|
||
```
|
||
|
||
---
|
||
|
||
# Prerequisites
|
||
|
||
* Rust stable ≥ 1.87
|
||
* `wasm-pack`
|
||
|
||
Install:
|
||
|
||
```bash
|
||
cargo install wasm-pack
|
||
```
|
||
|
||
---
|
||
|
||
# Configuration
|
||
|
||
## Precedence
|
||
|
||
```text
|
||
CLI flags > CHRONOSEAL_* environment variables > config file > defaults
|
||
```
|
||
|
||
## Default Config Locations
|
||
|
||
```text
|
||
/etc/chronoseal/config.toml
|
||
$XDG_CONFIG_HOME/chronoseal/config.toml
|
||
~/.config/chronoseal/config.toml
|
||
```
|
||
|
||
## Runtime State
|
||
|
||
```text
|
||
~/.local/state/chronoseal/
|
||
```
|
||
|
||
---
|
||
|
||
# Observability
|
||
|
||
ChronoSeal exposes:
|
||
|
||
* health probes
|
||
* runtime statistics
|
||
* Prometheus metrics
|
||
|
||
## Metrics Example
|
||
|
||
```bash
|
||
chronoseal metrics
|
||
```
|
||
|
||
```text
|
||
# HELP chronoseal_sessions Active ChronoSeal sessions
|
||
# TYPE chronoseal_sessions gauge
|
||
chronoseal_sessions 1
|
||
```
|
||
|
||
---
|
||
|
||
# Lightweight Runtime
|
||
|
||
Current release artifacts:
|
||
|
||
```text
|
||
chronoseal ~8.5 MB
|
||
chronoseal_wasm.wasm ~719 KB
|
||
```
|
||
|
||
ChronoSeal intentionally avoids:
|
||
|
||
* heavyweight frontend frameworks
|
||
* Electron-style packaging
|
||
* telemetry-heavy dependencies
|
||
* oversized runtime models
|
||
|
||
---
|
||
|
||
# Philosophy
|
||
|
||
ChronoSeal is intentionally not:
|
||
|
||
* a surveillance framework
|
||
* invasive browser fingerprinting
|
||
* a CAPTCHA replacement
|
||
* a telemetry ecosystem
|
||
|
||
ChronoSeal is:
|
||
|
||
* a cryptographic attestation runtime
|
||
* a behavioral continuity engine
|
||
* a proof-of-runtime framework
|
||
* a lightweight Unix-native daemon
|
||
|
||
---
|
||
|
||
# License
|
||
|
||
[MIT OR Apache-2.0](LICENSE)
|
||
|
||
---
|
||
|
||
# Project
|
||
|
||
GitHub:
|
||
https://github.com/thakares/chronoseal-rs
|