dosh/docs/PROTOCOL_VERSIONING.md

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.