From 25356debcce4118cdfa86842029278fde1e64518 Mon Sep 17 00:00:00 2001 From: Gab <24553253+gabrix73@users.noreply.github.com> Date: Tue, 18 Aug 2026 21:43:48 +0200 Subject: Publish FOG design documentation and Merkle tree --- docs/FOG-POC-PRESERVATION.md | 152 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 docs/FOG-POC-PRESERVATION.md (limited to 'docs/FOG-POC-PRESERVATION.md') diff --git a/docs/FOG-POC-PRESERVATION.md b/docs/FOG-POC-PRESERVATION.md new file mode 100644 index 0000000..6c045ee --- /dev/null +++ b/docs/FOG-POC-PRESERVATION.md @@ -0,0 +1,152 @@ +# FOG Proof-of-Concept Preservation + +Status: Required preservation contract + +Date: 2026-08-18 + +## 1. Objective + +The completed local alpha laboratory will be preserved as a reproducible FOG +proof of concept under the Gab Virebent / Virebent identity. It must remain +possible to inspect the topology, rebuild the software, start the isolated +roles, run the demonstration and fault scenarios, verify the results, and +remove the runtime resources without relying on undocumented local state. + +The preserved PoC is functional and educational evidence. It is not an +anonymity, production, post-quantum, durability, or independent-operator claim. + +## 2. Canonical PoC Contents + +The source tree must preserve: + +- exact source code and pinned Go module dependencies; +- the pinned compiler and build-tool version requirements; +- Containerfile and container build context; +- strict machine-readable topology and fault-scenario definitions; +- deterministic manifest and configuration generators; +- test vectors and synthetic non-secret fixtures; +- commands to build, start, demonstrate, verify, stop, and clean up; +- tests for role isolation, permitted and forbidden network edges, alternate + mix paths, authority quorum, node loss, storage loss, and restoration; +- a concise demonstration script or command that emits only coarse, + non-sensitive outcomes; +- a sanitized result manifest containing source revision, tool versions, + configuration digests, image digest, test outcome, and artifact hashes; +- dependency and license inventory, plus an SBOM when the selected build tools + can produce it reproducibly. + +Generated manifests may be retained when they make review easier, but their +source definition and deterministic generator remain authoritative. + +## 3. What Must Not Be Preserved + +The PoC repository, release bundle, image, demonstration output, and supporting +documentation must not contain: + +- private keys, passwords, tokens, credentials, recovery material, or real + operator secrets; +- runtime secret volumes, queue state, replay databases, storage contents, or + Composer state; +- real user messages, contacts, capabilities, identifiers, or traffic traces; +- host login instructions, private addresses, account identifiers, or private + operator inventories; +- container caches, mutable volumes, core dumps, debug logs, or temporary + build directories; +- personal metadata that would link the Virebent identity to unrelated + identities or private accounts. + +Every demonstration run generates ephemeral role-local fixture secrets from +the operating-system CSPRNG and destroys the disposable runtime resources at +cleanup. The saved environment contains only public deterministic inputs and +sanitized aggregate results. + +## 4. Preservation Levels + +### 4.1 Source preservation + +Source, specifications, generators, lock files, tests, and reproduction +instructions are the primary long-term artifact. They belong in the future +FOG repository and a frozen version tag after the Virebent remote and human +Git author identity are confirmed. + +### 4.2 Reproducible build record + +The milestone records exact toolchain versions, dependency hashes, build +arguments, target platform, source revision, binary hashes, and OCI manifest +digest. A future rebuild must be compared against this record. Differences are +reported, never silently accepted. + +### 4.3 Optional executable archive + +At the frozen PoC milestone, one compressed OCI image archive may be attached +to the release or stored in a Virebent-controlled artifact location. It must +not be committed to the source repository. The archive is optional because it +costs storage; the reproducible source is mandatory. Its SHA-256, media type, +platform, size, and creation command are recorded next to the release. + +The archive is created once for the demonstrated platform, not once per +container or node. All local roles reuse the same digest-pinned multi-binary +image. + +## 5. Demonstration Contract + +The preserved PoC must expose one documented, non-interactive top-level +workflow with these phases: + +```text +preflight -> build once -> create disposable secrets -> start roles + -> verify isolation -> run baseline -> run selected faults + -> emit sanitized summary -> destroy disposable resources +``` + +The workflow must fail closed on missing tools, incompatible versions, +unexpected existing resources, invalid topology, image-digest mismatch, +failed containment, incomplete cleanup, or failed tests. It must not download +or execute an unpinned artifact implicitly. + +The default demonstration should finish on one ordinary development host with +bounded CPU, memory, disk, process, and time budgets. A short baseline mode is +required. Longer adversarial and benchmark modes remain explicit opt-ins. + +## 6. Evidence and Public Presentation + +The preserved result states: + +- what behavior was demonstrated; +- exact host and software assumptions; +- which checks passed, failed, or were skipped; +- why co-located containers are not independent operators; +- why the result is not anonymity or production evidence; +- which protocol components are fixtures rather than active FOG profiles. + +Screenshots or video may supplement the machine-readable result but are not +canonical evidence. Before publication they must be checked for usernames, +hostnames, paths, terminal history, notifications, embedded metadata, and +identity leakage. + +## 7. Acceptance Gate + +The PoC preservation task is complete only when a clean environment can follow +the documented workflow using the frozen source, reproduce the expected +sanitized result, and leave no runtime container, network, volume, secret, or +temporary file behind. The final preservation audit must also confirm that no +secret or private identity data entered source or release artifacts. + +The definition gate is preserved in `deploy/alpha/lab-topology.json`, +`deploy/alpha/lab-faults.json`, and the dependency-free `internal/lab` +validator. Its summary is now `runnable: true`: compatible fixtures, +deterministic Compose generation, all eight baseline routes, 102 containment +and exact-network checks, all authority single and quorum losses, all six +single-mix failures, sanitized evidence, and complete disposable-resource +cleanup were demonstrated by one bounded command on 2026-08-18. It is not yet +an accepted preserved PoC. A canonical manifest now records dependency, +external-tool license, source, binary, evidence, and toolchain data with a +domain-separated artifact-set digest. The project license remains +`NOASSERTION`, and repository revision metadata plus independent clean-host +reproduction remain open. + +The same-host clean-filesystem rehearsal now reproduces byte-identical fixture +binaries, complete result, fixed-timestamp OCI image, Compose digest, and +canonical artifact-set digest. It validates the local ceremony but does not +satisfy the independent rebuild requirement because the host and installed +toolchain are shared. -- cgit v1.2.3