VerseVDI-Protocol/openspec/changes/phase-3d-client-safe-session-authority/design.md

Context

RC3 uses one provider-bearing SessionAuthority for both the authenticated Server-to-gateway control plane and the gateway-to-client acknowledgement. Provider profile and identity are valid inputs to gateway provider work and release, but they are forbidden at the client boundary. Existing strict RC3 clients require those fields, so changing the client shape is intentionally incompatible.

Goals / Non-Goals

Goals:

• Make provider disclosure structurally impossible in the client-facing authority type.
• Preserve the provider-bound Server-to-gateway admission, work, release, and cleanup contract.
• Produce strict, matching JSON Schema, Protobuf, Go, Rust, and Swift contracts.

Non-Goals:

• Supporting mixed RC3/RC4 gateway and client pairings.
• Changing SessionAuthority, ProviderSessionWork, VERSION, or global compatibility history.
• Adding response negotiation, optional provider fields, or permissive decoding.

Decisions

1. Add ClientSessionAuthority with exactly version, session_id, gateway_id, audience, reconnect_sequence, expires_at, and capabilities. Reusing the common validation bounds keeps the new acknowledgement session-bound without representing provider data.
2. Keep the existing provider-bearing SessionAuthority unchanged for Server-to-gateway operations. Deleting its provider fields would broaden the security-sensitive change into Server admission and provider-work validation.
3. Treat RC4 as a coordinated hard cut. A dual decoder would still accept the forbidden RC3 shape and is unnecessary for an unreleased candidate.
4. Use the existing generator unchanged. The JSON Schema definition is sufficient to generate strict Go, Rust, and Swift types; the matching Protobuf message uses fields 1 through 7.

Risks / Trade-offs

• [RC3 and RC4 clients are not wire-compatible] → Pin and qualify Server, gateway, and client as one exact RC4 set; retain RC3 as an immutable rollback set.
• [A future gateway could serialize the wrong authority type] → Consumer gateway tests must capture the raw acknowledgement and require ClientSessionAuthority with no provider-bearing keys.
• [Strict decoding rejects future additive fields] → Version a future client authority explicitly instead of weakening this v1 decoder.

Migration Plan

1. Publish the verified immutable Protocol RC4 tag.
2. Repin Data, Server, and macOS to the exact RC4 commit.
3. Change gateway egress and client decoders together, then qualify the exact all-RC4 set.
4. Roll back only as the complete immutable RC3 set; do not retag or mix candidates.

Open Questions

None for this pre-release hard cut. Evidence of deployed RC3 coexistence would require a separate negotiated-version design and blocks this migration model.