Publish FOG design documentation and Merkle tree

1 files changed, 120 insertions, 0 deletions

diff --git a/docs/FOG-SECURITY-TEST-PLAN.md b/docs/FOG-SECURITY-TEST-PLAN.md
new file mode 100644
index 0000000..59188b4
--- /dev/null
+++ b/docs/FOG-SECURITY-TEST-PLAN.md
@@ -0,0 +1,120 @@
+# FOG Security Test Plan
+
+Status: Structural test plan
+
+Date: 2026-08-18
+
+## 1. Purpose and Claim Boundary
+
+This plan defines the security test families required before an operator
+alpha. It supplies test contracts, not passing protocol evidence. Existing
+non-cryptographic fixture results may validate the harness but cannot close a
+protocol-functional gate.
+
+Every retained result must identify the software revision, active profile
+digests, test configuration, host class, seed or corpus digest where relevant,
+start and end dates, pass criteria, observed failures, and artifact SHA-256.
+Private keys, capabilities, packet identifiers, user data, and fine-grained
+production traffic do not belong in test reports.
+
+## 2. Test Levels
+
+| Level | Target | Minimum evidence |
+| --- | --- | --- |
+| Unit | pure codecs, state transitions, bounds, profile registry | deterministic tests and mutation cases |
+| Conformance | canonical bytes and public protocol behavior | vectors consumed by two independent implementations |
+| Integration | adjacent roles and complete route | fixed-profile success and fail-closed cases |
+| Fuzz | every untrusted parser and stateful sequence | retained corpus, crash triage, allocation ceilings |
+| Race | daemon concurrency and persistent state | race detector plus restart and contention cases |
+| Fault | process, network, disk, clock, and key failures | deterministic scenario result and restoration check |
+| Load | authenticated and unauthenticated saturation | CPU, memory, queue, latency, and amplification bounds |
+| Side channel | valid and invalid cryptographic paths | reviewed measurement method and statistical result |
+| Simulation | traffic, topology, compromise, suppression | scenario corpus, sensitivity analysis, confidence bounds |
+
+## 3. Mandatory Adversarial Matrix
+
+| Family | Required scenarios | Required invariant |
+| --- | --- | --- |
+| Replay | duplicate packet, restart, replay-state loss, epoch overlap, reply reuse | no repeated semantic effect; unsafe replay state stops processing |
+| Tagging | mutate every authenticated field, packet truncation and extension, SURB mutation | uniform rejection before service effect |
+| n-1 | suppress background traffic, inject hostile traffic, isolate a target, stop cover process | measured isolation signal and explicit degraded or stopped state |
+| Flooding | pre-auth connections, malformed handshakes, fragments, queue pressure, storage fan-out | bounded CPU, memory, connections, disk, and response amplification |
+| Clock | forward and backward jump, excessive uncertainty, cross-authority disagreement | no fresh state outside validity; coarse fault only |
+| Consensus | stale, rollback, freeze, same-epoch fork, malformed mirror, hard expiry | no merge, downgrade, local synthesis, or trust-on-first-use recovery |
+| Authority | one offline, quorum loss, sign-once restart, online-key compromise, replacement | deterministic liveness loss without invalid consensus |
+| Node loss | entry, each mix layer, courier, reconnect storm, replay database corruption | no layer skip, direct fallback, or undeclared route |
+| Storage loss | one replica, quorum loss, stale replica, lost receipt, tombstone conflict | no fabricated durability or resurrection |
+| Network | fragmentation, reordering at application boundaries, partition, asymmetric loss | strict ordered wire state and bounded randomized recovery |
+| State | crash before and after atomic commit, restore old state, disk full, partial write | commit-before-effect and fail-closed recovery |
+| Supply chain | altered binary, dependency change, revoked release, rollback | verification failure or explicit stop, never silent acceptance |
+
+## 4. Parser and Fuzz Targets
+
+Every versioned object parser must have a dedicated target for empty,
+truncated, oversized, non-canonical, duplicate, unknown-critical, trailing,
+deeply nested, maximum-count, and cross-version input. Stateful fuzzers must
+cover handshake, fragmentation, replay, consensus transition, ratchet,
+capability stream, receipt, tombstone, Composer import, recovery, update, and
+FOG-SX reconstruction sequences.
+
+Fuzz harnesses must enforce the protocol's allocation and work limits. A
+result is incomplete when the fuzzer merely avoids panics but permits
+unbounded memory, CPU, disk, file descriptors, goroutines, or cryptographic
+operations.
+
+## 5. Local Alpha Laboratory Matrix
+
+The local laboratory uses three authority fixtures, two mixes per layer, one
+entry, one courier, and four stores. It must exercise both mix choices in
+every layer and cover at least:
+
+1. all eight combinations of one mix per layer;
+2. loss of either mix in each layer while an allowed alternate remains;
+3. loss of both mixes in a layer with no bypass;
+4. one authority offline with quorum preserved;
+5. two authorities offline with no new consensus;
+6. loss of one store and loss of the required receipt quorum;
+7. partitions on every permitted adjacency and probes on every forbidden edge;
+8. restoration that proves stale replay, consensus, and storage state is not
+   silently reused.
+
+These scenarios validate orchestration and protocol behavior only. They do
+not close operator-independence or anonymity gates.
+
+## 6. Pass and Failure Handling
+
+A test family passes only when all declared cases meet byte-exact or bounded
+numeric criteria and every failure has been triaged. Flaky, skipped, timed-out,
+or infrastructure-invalid cases are not passes. Expected failure tests must
+assert the exact permitted coarse outcome and the absence of forbidden side
+effects.
+
+Security regressions retain the smallest non-secret reproducer. Reports use
+aggregate timing and resource data and must not introduce packet-level
+production telemetry. High-severity unresolved findings keep the affected
+readiness gate open.
+
+## 7. Required Commands by Go Module
+
+Each production or conformance Go module must pass:
+
+```sh
+gofmt -d .
+go test ./...
+go test -race ./...
+go vet ./...
+```
+
+Parser modules additionally run their registered fuzz targets under a
+documented time and resource budget. Cryptographic modules run dependency
+verification, complete-operation benchmarks, invalid-input timing tests, and
+independent vector comparison. Container laboratories validate the effective
+runtime state, not only source manifests.
+
+## 8. Gate Mapping
+
+The retained results map directly to `deploy/alpha/readiness.json`. Partial
+fixture evidence remains described in the gate note while status stays
+`open`. A gate changes to `pass` only after its complete scope has immutable
+evidence. The readiness validator does not run tests or trust filenames; it
+checks the declared status and evidence shape so review remains explicit.