Add launch hardening gates

2026-06-18 09:45:27 -04:00
parent 25d9a6aefa
commit d0d6f59cdf
11 changed files with 583 additions and 61 deletions
@@ -0,0 +1,40 @@
+# Dosh Protocol Versioning
+
+Dosh v1 uses a deliberately simple compatibility policy: **single-version,
+fail-closed, explicit error**.
+
+The wire header carries `protocol::VERSION`. The native handshake carries
+`native::NATIVE_PROTOCOL_VERSION`. A peer that speaks any other version is rejected
+before application data is accepted:
+
+- foreign wire `VERSION` packets get an `AttachReject` with
+  `protocol version mismatch - upgrade dosh`;
+- foreign native handshake `protocol_version` values get the same named upgrade
+  error with local/remote versions;
+- there is no silent downgrade, compatibility fallback, or best-effort decoding.
+
+## When To Bump
+
+Bump `protocol::VERSION` when a change affects packet framing, packet kind meaning,
+serialized protocol structs carried outside native handshake negotiation, or anything
+an older peer could misparse.
+
+Bump `native::NATIVE_PROTOCOL_VERSION` when a change affects native handshake
+transcripts, native auth semantics, algorithm negotiation, attach tickets, or any
+field that is signed or key-derived by native auth.
+
+If both layers are affected, bump both.
+
+## Compatibility Window
+
+Native v1 supports exactly the current version. That keeps the implementation small
+and makes security review tractable. Multi-version negotiation can be added later
+only with an explicit downgrade-resistance design:
+
+- negotiated version must be transcript-bound;
+- the selected version must be visible in diagnostics;
+- tests must prove an active attacker cannot force an older mutually supported
+  version;
+- unsupported peers must still get the same named upgrade error.
+
+Until that exists, the public policy is: upgrade both sides together.