From 59741761ce4e18dde67e81dee749186a25bd0c7f Mon Sep 17 00:00:00 2001 From: sechmachine <97589681+sechmachine727@users.noreply.github.com> Date: Wed, 29 Jul 2026 23:02:19 +0700 Subject: [PATCH] docs(openspec): archive gateway input feedback contract --- .../.openspec.yaml | 0 .../design.md | 0 .../proposal.md | 0 .../specs/gateway-input-feedback/spec.md | 0 .../tasks.md | 6 +- openspec/specs/gateway-input-feedback/spec.md | 83 +++++++++++++++++++ 6 files changed, 86 insertions(+), 3 deletions(-) rename openspec/changes/{phase3c-apollo-input-feedback => archive/2026-07-29-phase3c-apollo-input-feedback}/.openspec.yaml (100%) rename openspec/changes/{phase3c-apollo-input-feedback => archive/2026-07-29-phase3c-apollo-input-feedback}/design.md (100%) rename openspec/changes/{phase3c-apollo-input-feedback => archive/2026-07-29-phase3c-apollo-input-feedback}/proposal.md (100%) rename openspec/changes/{phase3c-apollo-input-feedback => archive/2026-07-29-phase3c-apollo-input-feedback}/specs/gateway-input-feedback/spec.md (100%) rename openspec/changes/{phase3c-apollo-input-feedback => archive/2026-07-29-phase3c-apollo-input-feedback}/tasks.md (86%) create mode 100644 openspec/specs/gateway-input-feedback/spec.md diff --git a/openspec/changes/phase3c-apollo-input-feedback/.openspec.yaml b/openspec/changes/archive/2026-07-29-phase3c-apollo-input-feedback/.openspec.yaml similarity index 100% rename from openspec/changes/phase3c-apollo-input-feedback/.openspec.yaml rename to openspec/changes/archive/2026-07-29-phase3c-apollo-input-feedback/.openspec.yaml diff --git a/openspec/changes/phase3c-apollo-input-feedback/design.md b/openspec/changes/archive/2026-07-29-phase3c-apollo-input-feedback/design.md similarity index 100% rename from openspec/changes/phase3c-apollo-input-feedback/design.md rename to openspec/changes/archive/2026-07-29-phase3c-apollo-input-feedback/design.md diff --git a/openspec/changes/phase3c-apollo-input-feedback/proposal.md b/openspec/changes/archive/2026-07-29-phase3c-apollo-input-feedback/proposal.md similarity index 100% rename from openspec/changes/phase3c-apollo-input-feedback/proposal.md rename to openspec/changes/archive/2026-07-29-phase3c-apollo-input-feedback/proposal.md diff --git a/openspec/changes/phase3c-apollo-input-feedback/specs/gateway-input-feedback/spec.md b/openspec/changes/archive/2026-07-29-phase3c-apollo-input-feedback/specs/gateway-input-feedback/spec.md similarity index 100% rename from openspec/changes/phase3c-apollo-input-feedback/specs/gateway-input-feedback/spec.md rename to openspec/changes/archive/2026-07-29-phase3c-apollo-input-feedback/specs/gateway-input-feedback/spec.md diff --git a/openspec/changes/phase3c-apollo-input-feedback/tasks.md b/openspec/changes/archive/2026-07-29-phase3c-apollo-input-feedback/tasks.md similarity index 86% rename from openspec/changes/phase3c-apollo-input-feedback/tasks.md rename to openspec/changes/archive/2026-07-29-phase3c-apollo-input-feedback/tasks.md index c14df53..e8abd77 100644 --- a/openspec/changes/phase3c-apollo-input-feedback/tasks.md +++ b/openspec/changes/archive/2026-07-29-phase3c-apollo-input-feedback/tasks.md @@ -14,16 +14,16 @@ - [x] 2.1 Run Protocol validation and the Go, Rust, and Swift conformance consumers against the new fixtures. -- [ ] 2.2 Advance the Data Plane to the final immutable Protocol revision and +- [x] 2.2 Advance the Data Plane to the final immutable Protocol revision and translate only the typed envelopes to provider control packets. - [x] 2.3 Add deterministic host-feedback forwarding and input-release tests without provider endpoint or credential disclosure. -- [ ] 2.4 Advance the Data Plane and Connection Server to the final clipboard +- [x] 2.4 Advance the Data Plane and Connection Server to the final clipboard contract and prove disabled direction, malformed/oversized text, rate, loop, and file/binary rejection against the authenticated provider path. ## 3. Freeze -- [ ] 3.1 Reconcile the canonical specification, OpenSpec tasks, source +- [x] 3.1 Reconcile the canonical specification, OpenSpec tasks, source provenance, and consumer fixture digest before creating a new immutable Protocol release candidate. diff --git a/openspec/specs/gateway-input-feedback/spec.md b/openspec/specs/gateway-input-feedback/spec.md new file mode 100644 index 0000000..b6792ee --- /dev/null +++ b/openspec/specs/gateway-input-feedback/spec.md @@ -0,0 +1,83 @@ +# 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, or controller-state +event. False keyboard/mouse state and zeroed controller state are explicit +releases. Multibyte integer fields SHALL be big-endian. Unknown 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: Invalid input envelope +- **WHEN** a client sends an envelope with an unknown event kind, invalid + length, malformed UTF-8 scalar, 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 and FEC/loss feedback SHALL be valid from the +client to the gateway. 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: Unauthorized or malformed feedback +- **WHEN** feedback is disabled by policy, has an invalid direction/type/length, + or contains a forbidden provider field +- **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.