301 lines
14 KiB
HTML
301 lines
14 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover">
|
|
<title>Architecture Overview | ChronoSeal Documentation</title>
|
|
<meta name="description" content="ChronoSeal system architecture, state models, components, validation pipelines, and trust boundaries.">
|
|
<link rel="stylesheet" href="css/chronoseal.css">
|
|
<link rel="stylesheet" href="css/docs.css">
|
|
<link rel="stylesheet" href="css/print.css" media="print">
|
|
<link rel="manifest" href="site.webmanifest">
|
|
<link rel="icon" href="assets/logo.svg" type="image/svg+xml">
|
|
|
|
<!-- Font Awesome for Icons -->
|
|
<link rel="preconnect" href="https://cdnjs.cloudflare.com" crossorigin />
|
|
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css"
|
|
integrity="sha512-iecdLmaskl7CVkqkXNQ/ZH/XLlvWZOJyj7Yy7tcenmpD1ypASozpmT/E0iPtmFIB46ZmdtAc9eNBvH0H/ZpiBw=="
|
|
crossorigin="anonymous"
|
|
referrerpolicy="no-referrer" />
|
|
</head>
|
|
<body>
|
|
|
|
<!-- Floating Background Spheres -->
|
|
<div class="bg-animation">
|
|
<div class="gradient-sphere sphere-1"></div>
|
|
<div class="gradient-sphere sphere-2"></div>
|
|
<div class="gradient-sphere sphere-3"></div>
|
|
</div>
|
|
|
|
<!-- Header / Navbar -->
|
|
<nav class="navbar" id="navbar">
|
|
<div class="nav-container">
|
|
<a href="index.html" class="logo">
|
|
<img class="logobar" src="assets/logo.svg" alt="ChronoSeal Logo">
|
|
<span>ChronoSeal</span>
|
|
</a>
|
|
<div class="nav-links" id="navLinks">
|
|
<a href="philosophy.html">Philosophy</a>
|
|
<a href="architecture.html" class="active">Architecture</a>
|
|
<a href="protocol.html">Protocol</a>
|
|
<a href="comparison.html">Comparison</a>
|
|
<div class="nav-dropdown">
|
|
<a href="#" class="nav-link">More <small>▼</small></a>
|
|
<div class="nav-dropdown-menu">
|
|
<a href="api.html">API Reference</a>
|
|
<a href="deployment.html">Deployment Guide</a>
|
|
<a href="operations.html">Operations Guide</a>
|
|
<a href="testing.html">Testing Strategy</a>
|
|
<a href="performance.html">Performance Tuning</a>
|
|
<a href="threat-model.html">Threat Model</a>
|
|
<a href="security.html">Security Policy</a>
|
|
<a href="privacy.html">Privacy Policy</a>
|
|
</div>
|
|
</div>
|
|
<button class="btn btn-ghost btn-sm btn-icon search-trigger" aria-label="Search" onclick="ChronoSearch.open()">
|
|
<svg fill="none" stroke="currentColor" stroke-width="2" viewBox="0 0 24 24" width="16" height="16"><path stroke-linecap="round" stroke-linejoin="round" d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"></path></svg>
|
|
</button>
|
|
<a href="https://github.com/thakares/chronoseal-rs" class="github-btn" target="_blank" rel="noopener">
|
|
<i class="fab fa-github"></i> GitHub
|
|
</a>
|
|
</div>
|
|
<button class="nav-toggle" id="menuBtn" aria-label="Toggle Navigation">
|
|
<i class="fas fa-bars"></i>
|
|
</button>
|
|
</div>
|
|
</nav>
|
|
|
|
<!-- Doc Page Shell -->
|
|
<div class="doc-page">
|
|
<div class="doc-layout">
|
|
|
|
<!-- Sidebar -->
|
|
<aside class="doc-sidebar">
|
|
<button class="doc-sidebar-toggle">
|
|
<i class="fas fa-bars"></i> Sidebar Menu
|
|
</button>
|
|
<div class="doc-nav-group">
|
|
<div class="doc-nav-label">Core Concepts</div>
|
|
<a href="philosophy.html" class="doc-nav-item">Design Philosophy</a>
|
|
<a href="architecture.html" class="doc-nav-item active">Architecture Overview</a>
|
|
<a href="comparison.html" class="doc-nav-item">ChronoSeal vs Others</a>
|
|
</div>
|
|
<div class="doc-nav-group">
|
|
<div class="doc-nav-label">Protocol & API</div>
|
|
<a href="protocol.html" class="doc-nav-item">Protocol Specification</a>
|
|
<a href="api.html" class="doc-nav-item">API Reference</a>
|
|
</div>
|
|
<div class="doc-nav-group">
|
|
<div class="doc-nav-label">Operations & Security</div>
|
|
<a href="threat-model.html" class="doc-nav-item">Threat Model</a>
|
|
<a href="security.html" class="doc-nav-item">Security Policy</a>
|
|
<a href="privacy.html" class="doc-nav-item">Privacy Policy</a>
|
|
<a href="performance.html" class="doc-nav-item">Performance Tuning</a>
|
|
</div>
|
|
<div class="doc-nav-group">
|
|
<div class="doc-nav-label">Lifecycle & Dev</div>
|
|
<a href="deployment.html" class="doc-nav-item">Deployment Guide</a>
|
|
<a href="operations.html" class="doc-nav-item">Operations Handbook</a>
|
|
<a href="testing.html" class="doc-nav-item">Testing Strategy</a>
|
|
</div>
|
|
</aside>
|
|
|
|
<!-- Main Content Area -->
|
|
<main class="doc-main">
|
|
<nav class="doc-breadcrumb" aria-label="Breadcrumb">
|
|
<a href="index.html">Home</a>
|
|
<span class="sep">/</span>
|
|
<a href="#">Core Concepts</a>
|
|
<span class="sep">/</span>
|
|
<span>Architecture Overview</span>
|
|
</nav>
|
|
|
|
<article class="doc-content">
|
|
<h1>ChronoSeal Architecture</h1>
|
|
<p class="doc-subtitle">ChronoSeal is a Unix-native browser attestation daemon. It validates session continuity by combining cryptographic signatures, hash-chain progression, deterministic VM execution, and a shared Synthetic Gene Mutation Engine.</p>
|
|
|
|
<hr>
|
|
|
|
<h2>System Diagram</h2>
|
|
<p>The following diagram shows the relationship between browser clients, the daemon process, and the shared protocol library:</p>
|
|
|
|
<!-- Inline Architecture Diagram Container -->
|
|
<div id="diagram-architecture" class="arch-diagram" style="margin-top:24px"></div>
|
|
|
|
<h2>Workspace Components</h2>
|
|
<p>The codebase is structured as a Rust workspace containing three runtime crates and static frontend assets:</p>
|
|
|
|
<h3>1. <code>shared/</code> Crate</h3>
|
|
<p>The <strong>determinism boundary</strong> of ChronoSeal. Any execution logic that must agree precisely between the browser WASM runtime and server verification belongs here. Its responsibilities include:</p>
|
|
<ul>
|
|
<li>Wire protocol struct formats for request and response models.</li>
|
|
<li>Blake3 hash-chain progression functions.</li>
|
|
<li>Synthetic gene model definitions and commitments.</li>
|
|
<li>Mutation program bytecode generator, interpreter, and execution tracer.</li>
|
|
</ul>
|
|
|
|
<h3>2. <code>server/</code> Crate</h3>
|
|
<p>Compiles into the <code>chronoseal</code> daemon binary. It manages the server runtime, HTTP API routes, database backends, and verification logic. Key responsibilities:</p>
|
|
<ul>
|
|
<li>CLI command parsing and flag defaults.</li>
|
|
<li>Axum-based web router and health endpoints.</li>
|
|
<li>Verification pipeline (signature verification, timestamp drift checks, rate limit validations).</li>
|
|
<li>Pluggable storage adapters (SQLite memory/disk, Valkey).</li>
|
|
<li>Background cleanup loop for session purges.</li>
|
|
</ul>
|
|
|
|
<h3>3. <code>wasm/</code> Crate</h3>
|
|
<p>Compiles into the browser WebAssembly package (using <code>wasm-pack</code>) used by the frontend. Its key functions include:</p>
|
|
<ul>
|
|
<li>Secure client-side Ed25519 keypair generation and verification.</li>
|
|
<li>Message signing for canonical heartbeat payloads.</li>
|
|
<li>Client-side VM program execution and stack history logging.</li>
|
|
<li>Previewing, committing, and discarding synthetic gene mutations.</li>
|
|
</ul>
|
|
|
|
<h3>4. <code>frontend/</code> Directory</h3>
|
|
<p>Contains static JavaScript (<code>heartbeat.js</code>, <code>app.js</code>) and assets served to browsers to orchestrate background attestation calls without blocking UI rendering.</p>
|
|
|
|
<h2>Session State Model</h2>
|
|
<p>The daemon stores a single <code>SessionRecord</code> in the active database per session, structured as follows:</p>
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Core Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><code>session_id</code></td>
|
|
<td>Random 32-byte session lookup key.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>public_key</code></td>
|
|
<td>Registered Ed25519 public key. Used to verify all heartbeats.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>salt</code></td>
|
|
<td>Current server salt required to verify the next heartbeat.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>last_hash</code></td>
|
|
<td>Current accepted Blake3 hash head. Prevents out-of-order repeats.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>gene</code></td>
|
|
<td>Committed synthetic gene byte buffer.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>pending_mutation</code></td>
|
|
<td>The mutation program compiled by the server for the next heartbeat step.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>pending_mutation_step</code></td>
|
|
<td>Mismatches between this and request steps cause silent rejection.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<div class="doc-alert doc-alert--warn">
|
|
<div class="doc-alert-icon">⚠️</div>
|
|
<div class="doc-alert-body">
|
|
<strong>State Invariant:</strong> The server-side session state advances ONLY after a heartbeat passes all pipeline validations. Failed heartbeats never alter the stored salt, hash, or gene parameters, preventing desynchronization exploits.
|
|
</div>
|
|
</div>
|
|
|
|
<h2>Verification Pipeline</h2>
|
|
<p>Heartbeat verification follows a strict chronological order. If any check fails, execution immediately halts, returning the silent rejection response. The pipeline is:</p>
|
|
<ol>
|
|
<li>Load the session record using the submitted <code>session_id</code>.</li>
|
|
<li>Assert that the session exists and has not expired (<code>now < expires_at</code>).</li>
|
|
<li>Verify the Ed25519 signature against the reconstructed canonical JSON payload.</li>
|
|
<li>Assert the request's <code>prev_hash</code> matches the server-stored <code>last_hash</code>.</li>
|
|
<li>Compare request step with <code>pending_mutation_step</code>.</li>
|
|
<li>Apply the stored <code>pending_mutation</code> to a cloned gene buffer.</li>
|
|
<li>Assert the computed gene commitment matches the request's <code>gene_commitment</code>.</li>
|
|
<li>Assert that the timestamp drift matches liveness bounds (within 30 seconds).</li>
|
|
<li>Assert that mouse activity entropy is present and speed falls within thresholds.</li>
|
|
<li>Assert screen aspect ratio, device pixel ratio, and concurrency parameters match bounds.</li>
|
|
<li>Advance the session's hash head, rotate the salt, compile the next mutation program, and persist.</li>
|
|
</ol>
|
|
</article>
|
|
|
|
<!-- Pager -->
|
|
<nav class="doc-pager" aria-label="Doc navigation Pager">
|
|
<a href="comparison.html" class="doc-pager-link">
|
|
<div class="doc-pager-label">Previous</div>
|
|
<div class="doc-pager-title">ChronoSeal vs Others</div>
|
|
</a>
|
|
<a href="protocol.html" class="doc-pager-link doc-pager-link--next">
|
|
<div class="doc-pager-label">Next</div>
|
|
<div class="doc-pager-title">Protocol Specification</div>
|
|
</a>
|
|
</nav>
|
|
|
|
<div class="doc-meta">
|
|
Last Updated: June 2026 (v1.0.2)
|
|
</div>
|
|
</main>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<!-- Footer -->
|
|
<footer class="footer">
|
|
<div class="footer-content">
|
|
<div class="footer-section">
|
|
<h4>
|
|
<img class="logobar" src="assets/logo.svg" alt="ChronoSeal Logo" style="width: 24px; height: 24px; vertical-align: middle;"> ChronoSeal
|
|
</h4>
|
|
<p>Next-generation browser attestation daemon built for the modern web.</p>
|
|
</div>
|
|
<div class="footer-section">
|
|
<h4>Resources</h4>
|
|
<a href="philosophy.html">Design Philosophy</a>
|
|
<a href="architecture.html">Architecture</a>
|
|
<a href="protocol.html">Protocol</a>
|
|
<a href="api.html">API Reference</a>
|
|
<a href="comparison.html">Comparison</a>
|
|
</div>
|
|
<div class="footer-section">
|
|
<h4>Community</h4>
|
|
<a href="https://github.com/thakares/chronoseal-rs" target="_blank" rel="noopener"><i class="fab fa-github"></i> GitHub</a>
|
|
<a href="deployment.html"><i class="fas fa-rocket"></i> Deployment</a>
|
|
<a href="testing.html"><i class="fas fa-vial"></i> Testing</a>
|
|
</div>
|
|
<div class="footer-section">
|
|
<h4>Legal & Security</h4>
|
|
<a href="security.html">Security Policy</a>
|
|
<a href="privacy.html">Privacy Policy</a>
|
|
<a href="performance.html">Performance Tuning</a>
|
|
<a href="operations.html">Operations Guide</a>
|
|
</div>
|
|
</div>
|
|
<div class="footer-bottom">
|
|
<p>© 2026 ChronoSeal Project. Built with 🦀 Rust and ❤️ for open source.</p>
|
|
</div>
|
|
</footer>
|
|
|
|
<!-- Search Overlay -->
|
|
<div class="search-overlay">
|
|
<div class="search-box">
|
|
<div class="search-input-wrap">
|
|
<svg fill="none" stroke="currentColor" stroke-width="2" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"></path></svg>
|
|
<input type="text" class="search-input" placeholder="Search documentation... (Esc to close)">
|
|
<span class="search-kbd">/</span>
|
|
</div>
|
|
<div class="search-results"></div>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- Back to top -->
|
|
<a href="#" class="back-to-top" aria-label="Back to top">▲</a>
|
|
|
|
<!-- JS Scripts -->
|
|
<script src="js/search.js"></script>
|
|
<script src="js/app.js"></script>
|
|
<script src="js/diagrams.js"></script>
|
|
</body>
|
|
</html>
|