A conforming-client implementation for the Entangled v1.0 protocol, built toward a full section 10 client with an eventual egui GUI.
The protocol specification lives at github.com/samjanny/entangled.
entangled-core is a verifier: it
covers per-document validation and signature verification and deliberately stops
there. The section 10 client concerns - the validation-pipeline ordering, the
Stage 7 trust-state machine (TOFU pinning, externally-verified identity,
Changed/mismatch detection), publisher-history persistence, consent, transport
over a carrier such as Tor, and image fetch/decode - are left to an embedding
client. This repository is that client.
The repository is a cargo workspace. The discipline mirrors the rest of the Entangled crate family: a pure, golden-testable brain plus a thin I/O / toolkit shell, so the security-critical logic is verified on data, not pixels.
entangled-core entangled-engine entangled-client (this repo)
verifier primitives Scene IR + lowering -> pure brain + (later) egui shell
crates/entangled-client- the pure brain. The section 10 validation-pipeline driver and the I/O seams (traits) a shell implements. No I/O, no toolkit,#![forbid(unsafe_code)].crates/entangled-client-gui- the eframe/egui shell: renders a verified document's content (Scene) and the chrome. Read-only viewer for now; not yet a conforming client.crates/entangled-client-store- filesystem-backedIdentityStore/HistoryStoreimplementations of the brain's persistence seams, with authenticated integrity by default and optional passphrase encryption.crates/entangled-transport-tor(later tranche) - the Tor transport behind the client'sTransporttrait.
Built in tranches, each a shippable increment toward full section 10 conformance:
- Pipeline driver (done): sequence the core's verification chain in section 10 order; report a structured outcome under section 11 error precedence. Pure, no I/O.
- Anti-downgrade / canary-conflict / runtime-rotation history. (done)
- Stage 7 trust-state machine + PIP + chrome model; the egui shell. (done; three-flavor retention per section 10:298, corpus trust vectors 210-215)
- Images (hash-verify-before-decode, media-type allowlist, pixel budget). (policy layer done and corpus-driven, vectors 240-245 and 269; the shell's real pixel decoder is the open item)
- Transport (Tor) behind the
Transporttrait. - Forms and submit.
- State and consent (section 07).
- Historical content, origin migration, reduced modes; full section 10 audit.
Transport (Tor), filesystem persistence, and image decode all sit behind traits, so the brain stays testable without any of them.
A goal of this client is to be OS-sandboxable (seccomp-bpf, namespaces,
bubblewrap/firejail, platform sandboxes) as defence in depth: it processes
authenticated-but-potentially-hostile publisher content over a hostile network.
The architecture is built to make that practical - the pure brain performs no
I/O and touches no syscalls, and every resource access (clock, transport,
persistence, image decode) goes through a trait whose implementation lives in
the shell. The syscall surface to confine is therefore exactly the shell's trait
impls. A CI guard rejects std::net / std::fs / SystemTime / toolkit imports
in the brain crate so this property cannot erode.
The spec does not mandate a process sandbox; section 03 separately recommends isolating the image decoder (hash verification authenticates bytes but does not make decoding safe). A concrete seccomp/bubblewrap profile and decoder isolation are documented as the shell and image tranches land.
cargo build --workspace
cargo test --workspace
cargo clippy --all-targets -- -D warnings
cargo fmt --checkRequires the sibling repo entangled-api checked out alongside this one (the
path dependency in Cargo.toml assumes that layout). entangled-engine joins
as a sibling once the GUI member consumes the Scene IR.
Dual-licensed under either of:
- MIT License
- Apache License, Version 2.0
at your option.