Protocol: split client session authority

openspec/changes/phase-3d-client-safe-session-authority/.openspec.yaml

@@ -0,0 +1,4 @@
+schema: spec-driven
+created: 2026-08-12
+goal: Split client-facing session authority from the provider-bearing
+  Server-to-gateway authority for the coordinated RC4 hard cut.

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

@@ -0,0 +1,41 @@
+## 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.

openspec/changes/phase-3d-client-safe-session-authority/proposal.md

@@ -0,0 +1,23 @@
+## Why
+
+The gateway currently serializes the provider-bearing Server-to-gateway `SessionAuthority` to clients, crossing provider identity into a client trust boundary that forbids it. RC4 must make that boundary structural before the pre-release client set is qualified.
+
+## What Changes
+
+- Add a strict provider-free `ClientSessionAuthority` with the seven session, gateway, audience, reconnect, expiry, and capability fields shared with `SessionAuthority`.
+- Keep `SessionAuthority` and `ProviderSessionWork` unchanged for the authenticated Server-to-gateway control plane.
+- **BREAKING** Replace the gateway-to-client RC3 response shape with `ClientSessionAuthority` as a coordinated RC4 hard cut; no mixed RC3/RC4 compatibility is claimed.
+
+## Capabilities
+
+### New Capabilities
+
+- `gateway-transport-and-admission`: Defines the distinct client-facing authority and its provider-free gateway admission boundary.
+
+### Modified Capabilities
+
+None.
+
+## Impact
+
+Protocol JSON Schema, tunnel Protobuf, generated Go/Rust/Swift bindings, and consumer Protocol pins advance together to `v1.0.0-phase3d-macos-rc.4`. `VERSION`, global compatibility history, and the Server-to-gateway provider authority remain unchanged.

openspec/changes/phase-3d-client-safe-session-authority/specs/gateway-transport-and-admission/spec.md

@@ -0,0 +1,30 @@
+## ADDED Requirements
+
+### Requirement: Client-facing authority is provider-free
+The gateway-to-client acknowledgement SHALL use `ClientSessionAuthority` version `"1"` containing exactly `version`, `session_id`, `gateway_id`, `audience`, `reconnect_sequence`, `expires_at`, and `capabilities`. The contract SHALL reject missing required fields, unknown fields including provider identities and routes, invalid or noncanonical expiry timestamps, and trailing JSON values.
+
+#### Scenario: Gateway acknowledges an admitted client
+- **WHEN** provider work succeeds and gateway and client capabilities intersect
+- **THEN** the gateway returns a valid `ClientSessionAuthority` containing the selected capabilities and no provider-bearing field
+
+#### Scenario: Client receives provider-bearing authority
+- **WHEN** a client authority payload contains `provider_profile`, `provider_identity`, a provider route, or any unknown key
+- **THEN** the strict client authority decoder rejects the payload
+
+#### Scenario: Client receives incomplete or malformed authority
+- **WHEN** a client authority omits any required binding, has an invalid expiry, or is followed by another JSON value
+- **THEN** the strict client authority decoder rejects the payload
+
+### Requirement: Server-to-gateway authority remains provider-bound
+The authenticated Server-to-gateway control plane SHALL continue to use the existing provider-bearing `SessionAuthority` for admission, provider work, release, and cleanup. `SessionAuthority` and `ProviderSessionWork` fields and semantics MUST remain unchanged by this change.
+
+#### Scenario: Gateway performs provider work
+- **WHEN** the Server admits a gateway session and the gateway requests provider work
+- **THEN** the original provider-bearing `SessionAuthority` continues to bind provider work and subsequent release or cleanup
+
+### Requirement: RC4 is a coordinated hard cut
+The RC4 gateway and client SHALL use `ClientSessionAuthority`; mixed RC3/RC4 gateway-client compatibility SHALL NOT be claimed. RC4 SHALL NOT add optional provider fields, a dual decoder, or response negotiation for RC3.
+
+#### Scenario: RC4 candidate is qualified
+- **WHEN** the Protocol RC4 tag is pinned by Server, gateway, and client
+- **THEN** qualification uses only that exact coordinated set

openspec/changes/phase-3d-client-safe-session-authority/tasks.md

@@ -0,0 +1,10 @@
+## 1. Contract and regressions
+
+- [x] 1.1 Add RED-first Go, Swift, Rust, and Protobuf regressions for the strict provider-free authority.
+- [x] 1.2 Add the exact seven-field JSON Schema and Protobuf `ClientSessionAuthority` without changing existing authority contracts.
+- [x] 1.3 Regenerate Go, Rust, Swift, Protobuf, and manifest outputs using repository tooling.
+
+## 2. Verification
+
+- [x] 2.1 Pass focused Go and generated-contract regressions.
+- [x] 2.2 Pass strict OpenSpec validation, full `make verify`, second-generation cleanliness, and diff checks.