From d5a402770880baf3d3e343fdb9e5633d1c7ef960 Mon Sep 17 00:00:00 2001
From: ReaperOfVeriod <reaperofveriod@gmail.com>
Date: Sun, 25 Oct 2026 04:22:32 +0100
Subject: [PATCH] feat: define administrator auth contracts

---
 README.md                                   |  3 ++-
 contracts/v1/auth-login-request.json        | 12 ++++++++++++
 contracts/v1/auth-login-response.json       | 12 ++++++++++++
 contracts/v1/auth-session-response.json     | 11 +++++++++++
 fixtures/v1/auth-login.response.json        |  4 ++++
 fixtures/v1/auth-session.authenticated.json |  3 +++
 6 files changed, 44 insertions(+), 1 deletion(-)
 create mode 100644 contracts/v1/auth-login-request.json
 create mode 100644 contracts/v1/auth-login-response.json
 create mode 100644 contracts/v1/auth-session-response.json
 create mode 100644 fixtures/v1/auth-login.response.json
 create mode 100644 fixtures/v1/auth-session.authenticated.json

diff --git a/README.md b/README.md
index 9cd9d70..1b9d53c 100644
--- a/README.md
+++ b/README.md
@@ -7,5 +7,6 @@ This repository contains schemas, shared enums, error codes, compatibility fixtu
 The first contract slice is under `contracts/v1/` and `fixtures/v1/`. It covers
 server readiness, health, errors, and the transport-neutral realtime event
 envelope so the client and server can be developed and tested together before
-Twitch integration.
+Twitch integration. It also defines the first administrator authentication
+request and response envelopes; bearer values in fixtures are synthetic only.
 
diff --git a/contracts/v1/auth-login-request.json b/contracts/v1/auth-login-request.json
new file mode 100644
index 0000000..7c58312
--- /dev/null
+++ b/contracts/v1/auth-login-request.json
@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://trixie.invalid/contracts/v1/auth-login-request.json",
+  "title": "Trixie Login Request",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["username", "password"],
+  "properties": {
+    "username": { "type": "string", "minLength": 1 },
+    "password": { "type": "string", "minLength": 1 }
+  }
+}
diff --git a/contracts/v1/auth-login-response.json b/contracts/v1/auth-login-response.json
new file mode 100644
index 0000000..acab4c8
--- /dev/null
+++ b/contracts/v1/auth-login-response.json
@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://trixie.invalid/contracts/v1/auth-login-response.json",
+  "title": "Trixie Login Response",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["session_token", "must_replace_credentials"],
+  "properties": {
+    "session_token": { "type": "string", "minLength": 1 },
+    "must_replace_credentials": { "type": "boolean" }
+  }
+}
diff --git a/contracts/v1/auth-session-response.json b/contracts/v1/auth-session-response.json
new file mode 100644
index 0000000..4f4ab2d
--- /dev/null
+++ b/contracts/v1/auth-session-response.json
@@ -0,0 +1,11 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://trixie.invalid/contracts/v1/auth-session-response.json",
+  "title": "Trixie Session Response",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["authenticated"],
+  "properties": {
+    "authenticated": { "const": true }
+  }
+}
diff --git a/fixtures/v1/auth-login.response.json b/fixtures/v1/auth-login.response.json
new file mode 100644
index 0000000..450f029
--- /dev/null
+++ b/fixtures/v1/auth-login.response.json
@@ -0,0 +1,4 @@
+{
+  "session_token": "fixture-session-token-never-use",
+  "must_replace_credentials": true
+}
diff --git a/fixtures/v1/auth-session.authenticated.json b/fixtures/v1/auth-session.authenticated.json
new file mode 100644
index 0000000..aab331f
--- /dev/null
+++ b/fixtures/v1/auth-session.authenticated.json
@@ -0,0 +1,3 @@
+{
+  "authenticated": true
+}