VerseVDI-Protocol/openspec/specs/gateway-input-feedback/spec.md

gateway-input-feedback Specification

Purpose

Define the provider-neutral typed input, feedback, and text-clipboard envelopes used across the authenticated Verse gateway boundary.

Requirements

Requirement: Typed sequenced input envelope

The input.sequenced.v1 payload SHALL begin with ASCII VGI1, a one-byte event kind, and one-byte payload length. It SHALL contain exactly one bounded keyboard, mouse-button, relative-mouse, UTF-8 scalar, controller-state, absolute-mouse, or high-resolution-scroll event. Absolute mouse kind 0x06 SHALL contain big-endian u16 x, y, viewport width, and viewport height, reject zero viewports and coordinates outside the viewport, and require negotiated input.absolute.v1. Scroll kind 0x07 SHALL contain big-endian signed i16 vertical and horizontal deltas and require negotiated input.scroll.v1. False keyboard/mouse state and zeroed controller state are explicit releases. Unknown or unadvertised kinds, length mismatches, malformed UTF-8, unsupported controller indices, and reserved fields SHALL be rejected before provider translation.

Scenario: Keyboard state change

• WHEN a client sends a valid keyboard press or release envelope
• THEN the gateway forwards the corresponding typed provider input on its reliable keyboard channel and records the pressed state for cleanup.

Scenario: Absolute pointer and scroll

• WHEN an advertised client sends an in-viewport absolute coordinate or signed scroll delta with the exact body length
• THEN the gateway accepts the provider-neutral event without adding it to pressed-state cleanup.

Scenario: Invalid input envelope

• WHEN a client sends an unknown or unadvertised kind, invalid length, malformed UTF-8 scalar, zero viewport, out-of-range coordinate, or nonzero reserved field
• THEN the gateway rejects it without sending provider input or changing pressed state.

Requirement: Explicit input release

The typed input envelope SHALL represent release of each keyboard key, mouse button, and controller state. Gateway cleanup SHALL send a typed release for every accepted pressed state before provider disconnect; it SHALL NOT use an implementation-specific release-all provider command.

Scenario: Tunnel cleanup with pressed input

• WHEN a tunnel closes after accepted pressed keyboard, mouse, or controller input
• THEN the gateway emits the corresponding individual provider release packets reliably before starting provider disconnect.

Requirement: Bounded provider feedback control envelope

The registered bidirectional reliable control.ack.v1 flow SHALL define an ASCII VGF1 envelope with a direction byte, type byte, big-endian payload length, and exact payload bytes. Only host termination, rumble, and HDR feedback SHALL be valid from the gateway to the client. Only IDR, FEC/loss feedback, and client-direction type 0x03 with an empty payload as terminal receipt SHALL be valid from the client to the gateway. The fixed conformance corpus and every generated or native Protocol validator SHALL accept that exact receipt and reject unknown types, wrong direction, nonempty receipt bodies, truncation, and length mismatch. The terminal receipt SHALL be valid only while the same session awaits receipt of its one terminal event and MUST NOT be forwarded to the provider. The envelope SHALL contain no provider address, certificate, credential, or opaque provider packet.

Scenario: Host termination forwarding

• WHEN the Apollo adapter receives an authenticated host termination packet
• THEN the gateway forwards a bounded VGF1 termination envelope over reliable Verse control and reports the provider state separately

Scenario: Terminal event receipt

• WHEN a client receives the reliable typed terminal event
• THEN it sends the fixed empty client-direction type 0x03 receipt and the gateway owns bounded tunnel closure without forwarding the receipt to the provider

Scenario: Unauthorized or malformed feedback

• WHEN feedback is disabled by policy, has an invalid direction/type/length, contains a forbidden provider field, or sends a terminal receipt outside the awaiting-terminal state
• THEN the gateway rejects it without forwarding or provider mutation

Requirement: Policy-bound text clipboard envelope

The reliable clipboard.text.v1 flow SHALL carry only a typed UTF-8 text envelope with exact direction and a 16--128 character canonical unpadded ASCII base64url loop token. The Server SHALL mint the enabled directions, maximum text bytes, and maximum updates per minute in authenticated provider work. The gateway SHALL reject disabled direction, unknown fields, files, file URLs, client folders, binary data, malformed UTF-8, oversized values, rates above policy, and reflected/replayed loop tokens. It SHALL not put clipboard content, provider routes, or credentials in telemetry, audit, state, or errors.

Scenario: Clipboard audit metadata

• WHEN the gateway successfully delivers, suppresses, or rejects a clipboard update
• THEN it sends an authenticated Server audit record with only direction, bounded byte count, outcome, and a fixed reason; it never includes text or the loop token.

Scenario: Clipboard delivery failure

• WHEN provider-to-client control delivery fails
• THEN the gateway does not report the update as forwarded.

Scenario: Reflected clipboard value

• WHEN a client-originated text value returns from the provider with the matching retained token/value pair
• THEN the gateway suppresses the reflected update without a second provider mutation or client delivery.