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:
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`
|
||||
Reference in new issue
Block a user