From b22ee5eeaba527631478a63a6b8530b2b39bb856 Mon Sep 17 00:00:00 2001
From: ReaperOfVeriod <reaperofveriod@gmail.com>
Date: Sun, 25 Oct 2026 04:42:23 +0100
Subject: [PATCH] feat: define realtime authentication frame

---
 contracts/v1/realtime-auth-frame.json | 12 ++++++++++++
 docs/contract-testing.md              |  6 ++++++
 fixtures/v1/realtime-auth-frame.json  |  4 ++++
 3 files changed, 22 insertions(+)
 create mode 100644 contracts/v1/realtime-auth-frame.json
 create mode 100644 fixtures/v1/realtime-auth-frame.json

diff --git a/contracts/v1/realtime-auth-frame.json b/contracts/v1/realtime-auth-frame.json
new file mode 100644
index 0000000..254a1de
--- /dev/null
+++ b/contracts/v1/realtime-auth-frame.json
@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://trixie.reaperofveriod.nl/contracts/v1/realtime-auth-frame.json",
+  "title": "Trixie realtime authentication frame",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["frame_type", "token"],
+  "properties": {
+    "frame_type": { "const": "authenticate" },
+    "token": { "type": "string", "minLength": 1 }
+  }
+}
diff --git a/docs/contract-testing.md b/docs/contract-testing.md
index bb87af3..9aa0033 100644
--- a/docs/contract-testing.md
+++ b/docs/contract-testing.md
@@ -10,3 +10,9 @@ deliver it over an authenticated WebSocket or a future compatible transport, but
 the event identity and payload rules remain the same. `event_id` is the stable
 deduplication key for at-least-once delivery.
 
+Browser clients authenticate the WebSocket with the first text frame described
+by `realtime-auth-frame.json`. Session tokens are sent in that frame rather
+than in a URL query parameter. The server closes the connection when the frame
+is missing, malformed, or invalid, and sends `connection.ready` only after
+successful validation.
+
diff --git a/fixtures/v1/realtime-auth-frame.json b/fixtures/v1/realtime-auth-frame.json
new file mode 100644
index 0000000..aa00819
--- /dev/null
+++ b/fixtures/v1/realtime-auth-frame.json
@@ -0,0 +1,4 @@
+{
+  "frame_type": "authenticate",
+  "token": "synthetic-session-token"
+}