nx9-chronoseal-rs/README.md

ChronoSeal

Cryptographic attestation daemon and anti-automation framework.

Privacy-preserving • Unix-native • Lightweight • WASM-powered

---

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.

v0.6.0 adds a deterministic synthetic gene mutation chain (hybrid Vec<u8> gene + bounded environment records) to strengthen anti-replay continuity with server/WASM parity. See docs/REFRACTORING-v0.6.0.md for the full refactoring details.

---

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
• Deterministic synthetic gene mutation chain
• Server/WASM mutation parity checks
• Silent rejection model
• SQLite-backed ephemeral sessions
• Configurable runtime DB backend selection (db_type)
• Connection-pooled runtime architecture
• Lightweight deployment footprint
• Docker and native deployment support
• Adaptive trust scoring
• GPLv3 licensed

---

Quick Start

Install

sudo bash scripts/install.sh

Check Status

chronoseal status --format json

Health Probe

chronoseal health

View Metrics

chronoseal metrics

View Logs

sudo journalctl -u chronoseal -f

---

CLI

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
db-type	List database backend support status
metrics	Output Prometheus metrics
stats	Print runtime statistics
completion	Generate shell completions
version	Print version/build information

---

Example

chronoseal status --format 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

Browser                                    Server
  │                                           │
  │  WASM loads, generates Ed25519 keypair    │
  │  Private key never leaves WASM memory     │
  │                                           │
  ├──── POST /init  { public_key } ──────────►│
  │◄─── { session_id, salt, opcodes_b64, H0,  │
  │     mutation_step, mutation_order_b64 } ──┤
  │                                           │
  │ Every 12–25s (randomized):                │
  │  ┌─ Collect behavioral entropy            │
  │  ├─ Execute verification VM opcodes       │
  │  ├─ Preview mutation commitment           │
  │  ├─ Attach mutation_step + commitment     │
  │  ├─ Advance Blake3 hash chain             │
  │  └─ Sign payload using Ed25519            │
  │                                           │
  ├──── POST /hb  { signed_payload } ────────►│
  │◄─── { status, next_salt,                  │
  │     next_mutation_step,                   │
  │     next_mutation_order_b64 } ────────────┤
  │                                           │
  │ Invalid sessions silently rejected        │
  │ (`status=ok` without next_* fields)       │

The server validates:

• signature authenticity
• heartbeat continuity
• replay resistance
• mutation step parity
• mutation commitment parity
• 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
Mutation tampering	Server-side commitment parity checks

---

Silent Rejection Model

ChronoSeal intentionally avoids explicit rejection semantics.

Invalid sessions may still receive:

{ "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

chronoseal-rs/
├── shared/          Shared types, hash chain, gene + mutation engine
├── server/          Axum HTTP daemon
│   ├── routes/      API routes
│   ├── session.rs   Session lifecycle + mutation parity checks
│   ├── 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
│   └── vm_extensions.rs Gene mutation preview/commit
├── 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

Mutation Opcodes (v0.6.0)

Opcode	Mnemonic	Effect
0x23	GENE_LOAD	Push gene[idx]
0x24	GENE_STORE	Pop and store at gene[idx]
0x25	MUTATE_POINT	Apply wrapping byte delta at index
0x26	INSERT	Insert popped byte at index
0x27	DELETE	Delete byte at index and push removed value
0x28	TRANSCRIBE	Push deterministic transcription hash
0x29	APPLY_MUTAGEN	Mix environment symbol quantity into gene byte
0x2A	FINALIZE_GENE_HASH	Push commitment-derived u32
0x2B	CONSUME	Pop amount, subtract environment quantity
0x2C	PRODUCE	Pop amount, add environment quantity

---

Hash Chain

ChronoSeal uses Blake3 chained continuity validation.

Initial Hash

H(0) = Blake3( session_id ║ public_key ║ salt₀ )

Heartbeat Progression

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

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,
    gene                  BLOB     NOT NULL DEFAULT X'',
    environment           BLOB     NOT NULL DEFAULT X'',
    pending_mutation      BLOB     NOT NULL DEFAULT X'',
    pending_mutation_step INTEGER  NOT NULL DEFAULT 0
);

ChronoSeal intentionally uses ephemeral session persistence.

Session continuity is designed to reset transparently.

---

v0.6.0 — Synthetic Gene Mutation System

Overview & Motivation

ChronoSeal v0.6.0 introduces a synthetic mutation chain model to strengthen attestation liveness and anti-replay guarantees while preserving privacy-first behavior. The core model combines:

• a primary byte-oriented gene buffer (Vec<u8>), and
• a bounded secondary environment map (Vec<(u16 symbol, u32 quantity)>).

Each heartbeat now carries deterministic mutation progression evidence (mutation_step, gene_commitment) that is validated server-side against the exact server-issued mutation order. This design increases attacker workload by coupling cryptographic chain continuity with stateful deterministic mutation parity.

Architectural Goals

1. Keep runtime behavior deterministic across server and WASM execution.
2. Preserve ephemerality and low operational complexity.
3. Minimize additional latency on the heartbeat path.
4. Improve protocol resistance against replay and mutation tampering.
5. Maintain a maintainable codebase with explicit invariants and focused modules.

Design Decisions

Shared mutation engine — Mutation opcode semantics live in shared/src/vm_extensions.rs to guarantee server/client parity from one implementation.

Deterministic gene commitment — A domain-separated BLAKE3 commitment (chronoseal/gene/v1) binds both gene bytes and sorted environment records.

Bounded mutation complexity — Mutation program length is capped (MAX_MUTATION_PROGRAM_BYTES) and environment cardinality is capped (MAX_ENV_RECORDS).

Strict validation on ingest — Environment payloads are validated for sortedness, uniqueness, non-zero quantity, and length constraints.

Protocol-level mutation handshake — InitResponse and Heartbeat payloads now include mutation step/order and commitment fields.

DB backend control via db_type — Server CLI/config now supports:

• sqlite-in-memory (default)
• sqlite-in-disk (active; uses db_path)
• valkey (active compatibility mode; currently falls back to in-memory)

Implementation

1. Gene model + deterministic commitment in shared/gene.rs.
2. v0.6.0 mutation opcode set in shared VM extensions.
3. Mutation state persisted per session (gene, environment, pending_mutation, pending_mutation_step).
4. Protocol schema extended for mutation fields in init/heartbeat exchange.
5. Mutation step + commitment parity validated before accepting heartbeat updates.
6. WASM preview/commit mutation lifecycle mirrors server behavior.
7. db_type CLI/config flow and runtime backend initialization strategy.
8. Migration-safe schema extension (column existence checks + index creation).

Testing Strategy

ChronoSeal v0.6.0 test coverage is organized across unit, integration, and randomized/fuzz-style validation.

Unit, integration, and property tests:

• Unit tests for gene invariants and encoding/decoding.
• Unit tests for every mutation opcode with stack-effect assertions.
• Integration tests for full session lifecycle and heartbeat acceptance/rejection paths.
• Table-driven randomized tests and fuzz-style random bytecode tests to validate deterministic failure/success symmetry.

Server-client parity testing:

• Shared opcode engine parity tests across seeded mutation sequences.
• Multi-step mutation chain test (test_mutation_chain) asserting identical server/client final state.
• 10+ heartbeat deterministic simulation tests in session integration suite.

Evasion / attack simulation testing:

• Replay attack simulation.
• Mutation step mismatch rejection.
• Mutation commitment tampering rejection.
• Malformed server mutation payload rejection.
• Stack underflow / unknown opcode / truncated program rejection.

Performance regression testing:

• Bounded execution checks through capped program size and bounded record counts.
• Timing smoke regression test for mutation execution loops.
• End-to-end heartbeat test coverage to detect behavior regressions on hot paths.

Security Analysis

Replay resistance — Heartbeats are now tied to both chain hash and mutation step progression.

Mutation tampering resistance — Server recomputes candidate gene state from authoritative pending mutation program and rejects commitment mismatch.

Protocol ambiguity reduction — Canonical signing payload includes mutation fields, reducing exploitable unsigned state.

Input hardening — Program size limits, stack underflow checks, and strict environment decoding reduce parser abuse and malformed payload amplification.

Deterministic failure semantics — Invalid mutation instructions fail predictably and symmetrically across server and WASM paths.

Performance Considerations

• Mutation instructions are lightweight and mostly O(1); only INSERT/DELETE are O(n) but bounded by max gene size.
• Environment operations use sorted-vector binary search with tight upper bound (MAX_ENV_RECORDS).
• Commitment hashing is linear in gene size and record count, both bounded.
• Shared engine avoids duplicate logic and divergence-induced debugging overhead.

Migration & Backward Compatibility

• Schema migration is additive; new columns are created when missing.
• Existing deployments without mutation fields require updated client+server pair for heartbeat compatibility.
• db_type defaults to in-memory to preserve ephemeral behavior.
• sqlite-in-disk is now directly usable via db_path.
• valkey currently runs in compatibility mode (in-memory fallback) to avoid startup failure while preserving CLI contract.

Risks & Mitigations

Risk	Mitigation
State divergence between server and client	Shared opcode engine + deterministic seeded parity tests + multi-heartbeat integration tests
Mutation opcode abuse via malformed programs	Strict parsing, length caps, explicit underflow/unknown-opcode errors
Performance regressions	Bounded structures, smoke timing tests, focused hot-path validation
Backend confusion during db_type rollout	Explicit CLI command (chronoseal db-type), config output visibility, and clear runtime compatibility behavior

---

Runtime Architecture

Server Runtime

• Rust
• Axum
• Tokio
• SQLite (sqlite-in-memory / sqlite-in-disk)
• db_type=valkey compatibility mode (falls back to in-memory in v0.6.0)
• r2d2
• thiserror

Browser Runtime

• Rust → WASM
• Ed25519 signing
• Blake3 chaining
• Stack-machine execution

---

Deployment

Recommended Installation

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 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

docker compose up -d --build

---

Development

Full Build

bash scripts/build.sh

Development Mode

bash scripts/dev.sh

Direct Execution

cargo run -p server -- run --bind 127.0.0.1:3000

---

Prerequisites

• Rust stable ≥ 1.87
• wasm-pack
• NodeJS (optional frontend tooling)

Install wasm-pack:

cargo install wasm-pack

Build backend:

cargo run -p server --release

Build WASM:

wasm-pack build wasm --target web --release

---

Configuration

Precedence

CLI flags > CHRONOSEAL_* environment variables > config file > defaults

Default Config Locations

/etc/chronoseal/config.toml
$XDG_CONFIG_HOME/chronoseal/config.toml
~/.config/chronoseal/config.toml

Runtime State

~/.local/state/chronoseal/

Database Backend Selection (v0.6.0)

Choose backend with config, env var, or CLI flag:

• Config: db_type = "sqlite-in-memory" | "sqlite-in-disk" | "valkey"
• Env: CHRONOSEAL_DB_TYPE=...
• CLI: chronoseal run --db-type sqlite-in-disk --db-path /var/lib/chronoseal/chronoseal.sqlite

Inspect backend status:

chronoseal db-type --format text

---

Observability

ChronoSeal exposes:

• health probes
• runtime statistics
• Prometheus metrics

Metrics Example

chronoseal metrics

# HELP chronoseal_sessions Active ChronoSeal sessions
# TYPE chronoseal_sessions gauge
chronoseal_sessions 1

---

Lightweight Runtime

Current release artifacts:

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

---

Contributing

Requirements

• Rust stable
• wasm-pack
• NodeJS (optional frontend tooling)

Development Workflow

cargo fmt
cargo clippy
cargo test

Guidelines

• Keep security-sensitive logic inside Rust/WASM
• Avoid placing trust logic in JavaScript
• Preserve silent-failure behavior
• Maintain deterministic protocol serialization

---

Security Policy

Reporting Vulnerabilities

Please do not disclose security vulnerabilities publicly before responsible disclosure.

Contact maintainers privately with:

• reproduction steps
• affected versions
• impact assessment
• proof-of-concept if applicable

Scope

ChronoSeal intentionally operates as:

• anti-automation middleware
• behavioral attestation layer
• cryptographic continuity verifier

Security hardening evolves continuously.

---

Language Breakdown

Language	Share
Rust	82.4%
JavaScript	13.7%
Shell	1.6%
Dockerfile	1.4%
HTML	0.9%

---

License

GPL-3.0

---

Project

GitHub: https://github.com/thakares/chronoseal-rs

Topics: rust · cryptography · wasm · antibot · browser-security · behavioral-analysis · anti-scraping · headless-detection