docs: add docs-as-code process and one ADR per feature

docs/docs-as-code.md defines the workflow; docs/adr holds 31 ADRs
(retroactive, reconstructed from code and changelog) with a template and
index. docs/check-docs.sh validates ADR structure, index, cited code
paths, relative links and CLAUDE.md/AGENTS.md sync.
This commit is contained in:
davide committed 2026-11-03 09:45:51 +01:00
1 parent ce8d777c63
commit b292590cdc
36 files changed
+987

No files matched your search

@@ -0,0 +1,24 @@
# 0010. TOFU certificate pinning for indexing servers
- **Status:** Accepted
- **Area:** Network
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
## Context
Indexing servers commonly use self-signed certificates, so CA validation is not available, yet silent MITM substitution must still be detectable.
## Decision
Trust On First Use: the certificate fingerprint is pinned on first successful TLS connection (`CertificatePinStore`, persisted per network in `server-certs.json`). A later mismatch raises `CertificatePinMismatchException` and blocks the connection until the user explicitly resets the pin (GUI, or CLI `reset-certs`). A corrupted pin file must not permanently block reconnection.
## Consequences
- Detects certificate substitution after first contact.
- Does not protect the first connection; users cannot distinguish a legitimate rotation from an attack, so the reset is deliberately manual.
- Reflects `SECURITY.md`; any change to the pinning policy must update it in the same commit.
## References
- `src/Core/Net/CertificatePinStore.cs`
- `SECURITY.md`