docs: update README and docs for v0.6.0 architecture and deployment, preserve current server/shared/wasm updates

This commit is contained in:
thakares committed 2026-05-29 21:27:11 +05:30
1 parent 6067746898
commit 2b8afd54e0
27 files changed
+1413 -2567

No files matched your search

+44 -27
View File
@@ -1,41 +1,58 @@
# ChronoSeal Design Philosophy
**"Everything is a File" — Unix-Native Software Design**
ChronoSeal is built for operators who value clarity, stability, and Unix-native infrastructure.
ChronoSeal is intentionally built as a **first-class citizen of Linux**. The entire application is designed to behave like a well-engineered native file within the Unix filesystem.
## Core Philosophy
### Why This Philosophy Matters
ChronoSeal is a Unix-first, CLI-first cryptographic attestation daemon. It is intentionally designed to feel like infrastructure software such as `nginx`, `redis-server`, or `systemd` itself.
ChronoSeal is designed so that administrators can operate, monitor, configure, and integrate it using the same reliable, transparent, and trusted tools and patterns they already use on Linux systems — without fighting the operating environment.
### Design priorities
### Core Principles
* **Unix-native operation** — systemd integration, PID files, structured logs, and predictable lifecycle semantics.
* **CLI as source of truth** — all runtime operations available through the command line.
* **Minimal opacity** — no hidden telemetry, no opaque fingerprinting database.
* **Privacy-first** — ephemeral session state and no persistent user profiling.
* **Deterministic runtime behavior** — shared Rust/WASM implementation for the mutation engine and heartbeat protocol.
* **Incremental cost escalation** — make automation painful to scale without claiming impossible security.
* **Operational transparency** — expose health, metrics, status, and config as first-class artifacts.
- **Everything is a File**: The application must be controllable, inspectable, and composable through standard Unix interfaces (CLI, files, signals, pipes, and environment).
- **CLI as Source of Truth**: All operations — starting, stopping, configuring, monitoring, and debugging — must be possible from the command line with excellent discoverability.
- **Behave Like a Native File**: Predictable lifecycle management through commands, signals (`SIGHUP`, `SIGTERM`, `SIGUSR1`), logs, configuration files, and standard process semantics.
- **Composability**: Must work naturally with pipes, redirection, scripts, systemd, Ansible, Docker, and orchestration tools.
- **Observability by Default**: All important state and metrics should be accessible as text or structured data.
- **Minimal Friction, Maximum Durability**: One-line installer, world-class `--help`, proper man pages, and decades-long maintainability are non-negotiable.
- **Respect for the OS**: Follows Linux Filesystem Hierarchy Standard (FHS), XDG Base Directory specification, and hardened systemd practices.
## Execution Model
### Non-Goals
ChronoSeal emphasizes deterministic, stateless request validation with a lightweight server-side session store.
ChronoSeal is **not** designed to be:
- Cloud-first or vendor-specific
- Browser-first or JavaScript-heavy
- Dependency-heavy or framework-driven
- GUI-centric (any graphical interface must be a thin wrapper)
- Telemetry-oriented or privacy-invasive
- Optimized for rapid prototyping at the cost of long-term reliability
* The server persists only the small session state required for continuity.
* The client executes a deterministic WASM runtime for every heartbeat.
* The protocol is intentionally ambiguous on rejection to avoid leaking validation rules.
These non-goals help keep the project focused on stability, simplicity, security, and deep Unix integration.
## Non-Goals
### Development Mindset
ChronoSeal does not aim to be:
- Production robustness, security, and long-term sustainability take clear precedence over development speed.
- Every design decision is evaluated against one question:
**“Does this make ChronoSeal feel like it naturally belongs in `/usr/bin/`?”**
* a tracking platform
* a browser fingerprinting database
* a long-term behavioral analytics engine
* a platform for user profiling
* a SaaS or cloud-first service
This philosophy guided the complete refactoring of ChronoSeal and continues to drive all future development.
Instead, ChronoSeal aims to be an infrastructure layer that raises attacker cost while leaving legitimate users unobstructed.
**Status**: Core architecture and systemd integration completed. Rich CLI, runtime configuration system, and one-line installer are in active development.
## Operational Assumptions
ChronoSeal assumes:
* the host environment is Linux
* systemd is available for service management
* TLS is used in production
* browser clients can execute WASM
* operators can manage native binaries and configuration files
## Privacy and Trust
The project is designed so that the verification mechanism is:
* ephemeral
* difficult to reverse-engineer at scale
* not based on personal identifiers
* not dependent on long-term user history
These choices reflect the belief that the best anti-automation system is one that can be operated without becoming a surveillance platform.