50 lines
4.2 KiB
Markdown
50 lines
4.2 KiB
Markdown
 
|
# Conclusion: detz safe-C++ playbook: overflow-safe parsing, cheap release hardening, a sanitizer test net, no new dependency
|
||
|
|
|
||
|
|
## Metadata
|
||
|
|
|
||
|
|
| Field | Value |
|
||
|
|
|---|---|
|
||
|
|
| Institute | Molodetz Institute — Research & Retrieval Division |
|
||
|
|
| Subject | safe-cpp-practices |
|
||
|
|
| Document type | Conclusion |
|
||
|
|
| Tier | N/A |
|
||
|
|
| Date decided | 2026-10-27 |
|
||
|
|
| Decided by | retoor, advised by tai (agent, Claude Opus 4.8) |
|
||
|
|
| Status | Active |
|
||
|
|
| Confidence | High |
|
||
|
|
|
||
|
|
## Question / problem statement
|
||
|
|
|
||
|
|
How does detz write fast, object-oriented C++ that a hostile or buggy peer can never crash or corrupt, without slowing development to a crawl or adding heavy dependencies?
|
||
|
|
|
||
|
|
## Conclusion
|
||
|
|
|
||
|
|
Four layers, cheapest first. (1) Design: parse untrusted bytes through a checked reader that validates every length against remaining bytes with overflow-safe arithmetic (`len <= size - pos`, never `pos + len <= size`), reads lengths into an unsigned type, rejects negatives, and never lets a wire value drive an allocation or slice before it is bounded; guard every varint shift against >= 64 bits; wrap every top-level read/dispatch loop so no exception escapes. RAII and the rule of zero keep resource bugs from existing. (2) Release hardening (cheap, always on): the overflow-safe checks plus libstdc++ fast assertions and fortification per the OpenSSF guide, so a residual bad index is a defined, located failure not undefined behavior. (3) Test net (free at dev time, run in CI): an ASan+UBSan+_GLIBCXX_ASSERTIONS build of the parsers plus a hostile-input and random-fuzz test, via tools/san-whatsapp.sh. (4) Capture: record the exact bytes of any frame that breaks a parser so an unreproducible wire bug becomes a one-paste deterministic fix. No GSL, no new runtime dependency; std::span-style checked views and OpenSSL/zlib already linked.
|
||
|
|
|
||
|
|
## Supporting sources
|
||
|
|
|
||
|
|
- [openssf-compiler-hardening-guide](../openssf-compiler-hardening-guide.md): the cheap release-hardening flag set (_GLIBCXX_ASSERTIONS, fortification, stack-protector).
|
||
|
|
- [integer-overflow-size-checks](../integer-overflow-size-checks.md): the `len <= size - pos` guard and validate-before-allocate rule, the root-cause cure.
|
||
|
|
- [libfuzzer-sanitizer-ci](../libfuzzer-sanitizer-ci.md): the sanitizer+fuzz test net and the regression-corpus/capture pattern.
|
||
|
|
- [sanitizer-overhead-maturity-ladder](../sanitizer-overhead-maturity-ladder.md): why sanitizers are test-only and hardening is release: the overhead numbers and the ladder.
|
||
|
|
- [cpp-core-guidelines-bounds-gsl](../cpp-core-guidelines-bounds-gsl.md): span-over-pointer+length and explicit checked narrowing instead of silent int->size_t.
|
||
|
|
- [std-span-no-default-bounds-check](../std-span-no-default-bounds-check.md): why the reader must validate itself and not trust span/subspan to bounds-check.
|
||
|
|
|
||
|
|
## Alternatives considered and rejected
|
||
|
|
|
||
|
|
Adopt GSL wholesale (span/narrow/not_null): rejected as a new dependency; CLAUDE.md says fewer moving parts, and std::span plus a small checked reader covers the need. Turn on sanitizers in release: rejected, 2-3x cost; they are the test net, not the shipping config. Rewrite the wire layer in a memory-safe language: rejected, the project is C++ and the crypto/wire core is proven; the goal is safe C++, not not-C++.
|
||
|
|
|
||
|
|
## Risks / open questions
|
||
|
|
|
||
|
|
Hardening and sanitizers catch memory and UB bugs, not logic bugs; byte-exact golden vectors and the live handshake cover correctness separately. clang-tidy (the narrowing-conversion static layer) is not wired yet, so an implicit narrowing can still be introduced between sanitizer runs; that is the named next ratchet step. ed25519 ref10 is excluded from UBSan for intentional shift idioms, a small unsanitized island.
|
||
|
|
|
||
|
|
## Action taken
|
||
|
|
|
||
|
|
Applied to detz::wa in this session: overflow-safe checks in WaBinary and WaProto (commit f16c5c6), the varint shift guard (this session, caught by the sanitizer net that this research prescribed), the frame-capture hook, tests/whatsapp_test.cpp test_hostile, and tools/san-whatsapp.sh. Documented in docs/cpp-safety.md and docs/whatsapp.md section 13, with the standing rule added to AGENTS.md. clang-tidy ratchet recorded as the next step, not yet wired.
|
||
|
|
|
||
|
|
## Changelog
|
||
|
|
|
||
|
|
| Date | Change |
|
||
|
|
|---|---|
|
||
|
|
| 2026-10-27 | Initial conclusion recorded. |
|