VerseVDI-Protocol/docs/interface-inventory.md

Phase 3A interface inventory

This inventory records the wire boundary consumed by the closed Connection Server. The Protocol repository owns only schemas, registries, fixtures, and generated bindings; the Server remains the authority for authentication, authorization, persistence, and provider selection.

Existing Server routes adapted by generated contracts

Route	Channel/guard	Contract boundary	Phase 2 behavior
POST /api/v1/auth/refresh	native credential body; rate limited	RefreshRequest -> NativeCredential	opaque refresh rotation and replay-family revocation remain PostgreSQL-owned
POST /api/v1/auth/devices	authenticated browser session + CSRF	DeviceRegistrationRequest -> DeviceChallenge	device challenge remains one-use and hash-backed
POST /api/v1/auth/devices/:id/prove	authenticated browser session + CSRF	DeviceProofRequest -> NativeCredential	canonical Ed25519 proof and native session issuance remain Server-owned
DELETE /api/v1/auth/devices/:id	authenticated browser session + CSRF	no body	principal-scoped device revocation remains Server-owned
GET /api/v1/resources	authenticated browser/native session	ResourceList	assigned desktop and entitled pool projections omit machine/provider data
POST /api/v1/broker/sessions	authenticated session + CSRF	SessionRequest -> BrokerSession	existing assignment, idempotency, queue, and PostgreSQL state machine remain authoritative
GET /api/v1/broker/sessions/:id	authenticated session	BrokerSession	owner-scoped lookup is preserved
POST /api/v1/broker/sessions/:id/allocate	authenticated session + CSRF	ConnectionManifest	gateway-only grant boundary; no provider/direct-host fields
POST /api/v1/broker/sessions/:id/reconnect	authenticated session + CSRF	ReconnectRequest -> ConnectionManifest	device proof, expected version, grant rotation, and monotonic reconnect sequence remain authoritative
POST /api/v1/broker/sessions/:id/cancel	authenticated session + CSRF	no body	existing compensation path remains authoritative

Contract rules

• Unknown fields are rejected for signed/security-sensitive requests and generated decoders are strict.
• Responses are explicit projections; domain, sqlc, provider, VM, and credential structures are never serialized directly.
• Resource projections contain only opaque assignment/pool identifiers and safe state; machine identifiers and provider endpoints are not wire fields.
• A manifest contains only the versioned gateway/tunnel/profile/grant allow-list. The opaque grant is stored as a hash in the Server database and is single-use.
• Events and QUIC/tunnel sources are defined here before any production media or gateway implementation; the Phase 3A claim stops at control contracts and conformance.

Compatibility notes

The existing routes and authentication channels remain unchanged. Phase 3A adds the page member to the resource response and replaces the legacy flat manifest projection with the versioned gateway-only manifest. Both changes are intentional contract changes: the former is additive, and the latter is required to make provider/direct-host fields unrepresentable. The Server integration tests retain the old safe resource members and assert the new allow-list explicitly.