feat(protocol): define gateway control envelopes

2026-07-29 17:24:18 +07:00
parent 36f6edffca
commit 0ea21cd3f2
29 changed files with 1445 additions and 41 deletions
@@ -0,0 +1,28 @@
+# Gateway clipboard text v1
+
+`clipboard.text.v1` is a reliable, authenticated gateway-only `ChannelFrame`
+flow. Its UTF-8 JSON payload is a `GatewayClipboardText` object:
+
+```json
+{"direction":"client_to_provider","text":"text","encoding":"utf-8","loop_token":"base64url-token"}
+```
+
+`direction` is exact: the client may send only `client_to_provider`, and the
+gateway may send only `provider_to_client`. The text contains no file name,
+URL, binary value, or client-folder field and is at most the Server-owned
+`clipboard_policy.max_text_bytes` value. `loop_token` is a 16--128 ASCII
+base64url-character token generated by the originating endpoint. An endpoint MUST retain
+recent token/value pairs only for the bounded policy window and MUST suppress a
+matching reflected value; a mismatched, malformed, expired, or replayed token
+is rejected without clipboard mutation.
+
+The gateway receives the policy only in authenticated session work. A disabled
+direction, a rate above `max_updates_per_minute`, invalid UTF-8, an oversized
+payload, or an unknown field fails closed. Clipboard bytes are never emitted to
+provider-state, audit, telemetry, or error payloads.
+
+For every accepted, loop-suppressed, or policy/rate/provider/malformed rejection,
+the gateway sends an mTLS control-plane `GatewayClipboardAudit` record. It contains
+only the session identifier, direction, bounded text-byte count, outcome, and a
+fixed reason code; it contains neither text nor loop token. The Server persists it
+against the broker session using the authenticated gateway identity.