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
1 parent
6067746898
commit
2b8afd54e0
27 files changed
+1413
-2567
No files matched your search
+92
-89
@@ -1,115 +1,118 @@
|
||||
# ChronoSeal v0.6.0 — Synthetic Gene Mutation System
|
||||
# ChronoSeal v0.6.0 — Refactoring and System Upgrade
|
||||
|
||||
## 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)>`).
|
||||
ChronoSeal v0.6.0 is a major architecture and protocol update that transforms the project from a lightweight heartbeat service into a mature Unix-native attestation daemon with deterministic mutation parity and pluggable storage backends.
|
||||
|
||||
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.
|
||||
## Summary of Changes
|
||||
|
||||
## 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.
|
||||
* Introduced the **Synthetic Gene Mutation Engine** for deterministic mutation parity across server and WASM.
|
||||
* Added server-side validation of `mutation_step` and `gene_commitment`.
|
||||
* Centralized shared protocol logic in `shared/` for server/WASM parity.
|
||||
* Added support for multiple storage backend modes: `sqlite-in-memory`, `sqlite-disk`, and `valkey` compatibility.
|
||||
* Hardened runtime architecture with `systemd` readiness, graceful shutdown, PID file support, and structured logging.
|
||||
* Expanded CLI with rich subcommands and effective runtime configuration.
|
||||
* Preserved silent rejection semantics while improving anti-replay and liveness guarantees.
|
||||
|
||||
## Design Decisions
|
||||
1. **Shared mutation engine**
|
||||
Mutation opcode semantics live in `shared/src/vm_extensions.rs` to guarantee server/client parity from one implementation.
|
||||
## Why This Refactor?
|
||||
|
||||
2. **Deterministic gene commitment**
|
||||
A domain-separated BLAKE3 commitment (`chronoseal/gene/v1`) binds both gene bytes and sorted environment records.
|
||||
The previous model relied on heartbeat continuity and behavioral entropy alone. v0.6.0 strengthens the protocol by adding a second, deterministic state progression channel:
|
||||
|
||||
3. **Bounded mutation complexity**
|
||||
Mutation program length is capped (`MAX_MUTATION_PROGRAM_BYTES`) and environment cardinality is capped (`MAX_ENV_RECORDS`).
|
||||
* each heartbeat now includes a mutation step and commitment
|
||||
* the server authoritatively selects the next mutation program
|
||||
* the client must preview and commit the same state locally in WASM
|
||||
* the server rejects any mismatch silently
|
||||
|
||||
4. **Strict validation on ingest**
|
||||
Environment payloads are validated for sortedness, uniqueness, non-zero quantity, and length constraints.
|
||||
This raises the cost of developing a successful automation attack because the attacker must now maintain both a valid chain and a valid mutation progression state.
|
||||
|
||||
5. **Protocol-level mutation handshake**
|
||||
`InitResponse` and `Heartbeat` payloads now include mutation step/order and commitment fields.
|
||||
## Core Architecture Changes
|
||||
|
||||
6. **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)
|
||||
### Shared Protocol Code
|
||||
|
||||
## Implementation Plan
|
||||
1. Add gene model + deterministic commitment in `shared/gene.rs`.
|
||||
2. Implement v0.6.0 mutation opcode set in shared VM extensions.
|
||||
3. Persist mutation state per session (`gene`, `environment`, `pending_mutation`, `pending_mutation_step`).
|
||||
4. Extend protocol schema for mutation fields in init/heartbeat exchange.
|
||||
5. Validate mutation step + commitment parity before accepting heartbeat updates.
|
||||
6. Add WASM preview/commit mutation lifecycle mirroring server behavior.
|
||||
7. Add `db_type` CLI/config flow and runtime backend initialization strategy.
|
||||
8. Add migration-safe schema extension (column existence checks + index creation).
|
||||
`shared/` now contains:
|
||||
|
||||
## Testing Strategy (detailed section)
|
||||
ChronoSeal v0.6.0 test coverage is organized across unit, integration, and randomized/fuzz-style validation.
|
||||
* gene model and commitment hashing
|
||||
* mutation opcode semantics
|
||||
* request/response payload structures
|
||||
* canonical signing support
|
||||
* VM execution logic shared by server and WASM
|
||||
|
||||
1. **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.
|
||||
Moving mutation semantics into `shared/` eliminates subtle server/client divergence bugs and enables deterministic cross-runtime testing.
|
||||
|
||||
2. **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.
|
||||
### Mutation Handshake
|
||||
|
||||
3. **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.
|
||||
v0.6.0 adds the following data to the protocol:
|
||||
|
||||
4. **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.
|
||||
* `mutation_step`
|
||||
* `mutation_order_b64`
|
||||
* `gene_commitment`
|
||||
* `next_mutation_step`
|
||||
* `next_mutation_order_b64`
|
||||
|
||||
## Security Analysis
|
||||
1. **Replay resistance**
|
||||
Heartbeats are now tied to both chain hash and mutation step progression.
|
||||
These fields are now part of the session initialization and heartbeat exchange.
|
||||
|
||||
2. **Mutation tampering resistance**
|
||||
Server recomputes candidate gene state from authoritative pending mutation program and rejects commitment mismatch.
|
||||
### Server Session State
|
||||
|
||||
3. **Protocol ambiguity reduction**
|
||||
Canonical signing payload includes mutation fields, reducing exploitable unsigned state.
|
||||
The session schema now stores:
|
||||
|
||||
4. **Input hardening**
|
||||
Program size limits, stack underflow checks, and strict environment decoding reduce parser abuse and malformed payload amplification.
|
||||
* committed gene bytes
|
||||
* committed environment records
|
||||
* pending mutation order
|
||||
* pending mutation step
|
||||
|
||||
5. **Deterministic failure semantics**
|
||||
Invalid mutation instructions fail predictably and symmetrically across server and WASM paths.
|
||||
The server advances this state only after a heartbeat is accepted.
|
||||
|
||||
## Performance Considerations
|
||||
1. Mutation instructions are lightweight and mostly O(1); only `INSERT`/`DELETE` are O(n) but bounded by max gene size.
|
||||
2. Environment operations use sorted-vector binary search with tight upper bound (`MAX_ENV_RECORDS`).
|
||||
3. Commitment hashing is linear in gene size and record count, both bounded.
|
||||
4. Shared engine avoids duplicate logic and divergence-induced debugging overhead.
|
||||
### Deterministic WASM Preview
|
||||
|
||||
## Migration & Backward Compatibility
|
||||
1. Schema migration is additive; new columns are created when missing.
|
||||
2. Existing deployments without mutation fields require updated client+server pair for heartbeat compatibility.
|
||||
3. `db_type` defaults to in-memory to preserve ephemeral behavior.
|
||||
4. `sqlite-in-disk` is now directly usable via `db_path`.
|
||||
5. `valkey` currently runs in compatibility mode (in-memory fallback) to avoid startup failure while preserving CLI contract.
|
||||
The WASM runtime exposes:
|
||||
|
||||
## Risks & Mitigations
|
||||
1. **Risk: State divergence between server and client**
|
||||
Mitigation: shared opcode engine + deterministic seeded parity tests + multi-heartbeat integration tests.
|
||||
* `init_gene_state()`
|
||||
* `preview_gene_commitment()`
|
||||
* `commit_gene_preview()`
|
||||
* `discard_gene_preview()`
|
||||
* `current_gene_commitment()`
|
||||
|
||||
2. **Risk: Mutation opcode abuse via malformed programs**
|
||||
Mitigation: strict parsing, length caps, explicit underflow/unknown-opcode errors.
|
||||
This makes the client-side mutation lifecycle explicit and deterministic.
|
||||
|
||||
3. **Risk: Performance regressions**
|
||||
Mitigation: bounded structures, smoke timing tests, and focused hot-path validation.
|
||||
### Backend Abstraction
|
||||
|
||||
4. **Risk: Backend confusion during `db_type` rollout**
|
||||
Mitigation: explicit CLI command (`chronoseal db-type`), config output visibility, and clear runtime compatibility behavior.
|
||||
The server runtime now supports a configurable `db_type`.
|
||||
|
||||
* `sqlite-in-memory` — default runtime storage with ephemeral session semantics
|
||||
* `sqlite-disk` — persistent SQLite storage for stateful deployments
|
||||
* `valkey` — compatibility mode for alternative storage backends
|
||||
|
||||
This abstraction makes ChronoSeal easier to operate in both stateless and stateful environments.
|
||||
|
||||
### CLI and Service Integration
|
||||
|
||||
v0.6.0 improves the CLI surface with operational commands and service introspection.
|
||||
|
||||
* `chronoseal run`
|
||||
* `chronoseal status`
|
||||
* `chronoseal health`
|
||||
* `chronoseal config`
|
||||
* `chronoseal metrics`
|
||||
* `chronoseal stats`
|
||||
* `chronoseal db-type`
|
||||
* `chronoseal completion`
|
||||
* `chronoseal version`
|
||||
|
||||
The runtime now includes PID file handling and graceful termination.
|
||||
|
||||
## Testing and Validation
|
||||
|
||||
The refactor includes extensive tests for:
|
||||
|
||||
* server/WASM parity across mutation sequences
|
||||
* malformed mutation payload rejection
|
||||
* replay attack rejection
|
||||
* mutation step mismatch rejection
|
||||
* stateful session update semantics
|
||||
* runtime database mode validation
|
||||
|
||||
The codebase now supports deterministic table-driven tests and fuzz-style random program validation.
|
||||
|
||||
## Operational Impact
|
||||
|
||||
This release makes ChronoSeal suitable for production deployment in Linux environments and for integration into existing web application stacks.
|
||||
|
||||
The combination of deterministic mutation parity and shared protocol implementation improves both security and maintainability.
|
||||
Reference in new issue
Block a user