Major architecture update: stable identity, component validation, media indexing, and protocol docs

PROTOCOL.md

@@ -0,0 +1,140 @@
+# Reliquary Protocol (MVP v1)
+
+This document defines the current wire contract used by the server.
+
+## 1. Identity
+- `userId`: immutable opaque ID.
+- `username`: home-server unique, mutable.
+- `handle`: derived string `@username@home`.
+- `homeServer`: canonical public base URL.
+
+## 2. Auth
+
+### `POST /auth/register`
+Request:
+```json
+{ "username": "alice", "password": "password123" }
+```
+Response fields include:
+- `token`
+- `userId`
+- `username`
+- `handle`
+- `publicKey`
+- encrypted key backup fields
+
+### `POST /auth/login`
+Request:
+```json
+{ "username": "alice", "password": "password123" }
+```
+Response includes token + profile/key fields.
+
+### `POST /auth/join`
+Request:
+```json
+{
+  "userId": "opaque_id",
+  "username": "alice",
+  "homeServer": "https://chat.example.com",
+  "timestamp": 1730000000,
+  "signature": "base64..."
+}
+```
+Signature is over `userId:timestamp`.
+
+## 3. Message Components
+
+Each component node must include:
+- `id` (string)
+- `type` (string)
+- `typeVersion` (positive int)
+- `data` (object)
+
+Optional:
+- `fallback`, `modifiers`
+
+Nested components are supported under `data.children`.
+
+## 4. Media Item Sources
+
+Media references support two sources:
+
+1. Local upload:
+```json
+{
+  "source": "local_upload",
+  "attachmentId": "att_...",
+  "status": "uploading|ready|failed"
+}
+```
+
+2. External URL:
+```json
+{
+  "source": "external_url",
+  "url": "https://example.com/image.jpg",
+  "status": "ready"
+}
+```
+
+Optional metadata snapshot:
+- `mimeType`, `sizeBytes`, `width`, `height`, `thumbHash`, `originalFileName`, `caption`.
+
+## 5. Uploads
+
+### `POST /api/uploads/init` (auth)
+Creates pending upload and returns `uploadId` (same ID namespace as attachment ID).
+
+### `PUT /api/uploads/:uploadId` (auth)
+Completes upload with file bytes and returns canonical metadata:
+- `attachmentId`, `url`, `status`, `mimeType`, `sizeBytes`, dimensions, hash.
+
+### `POST /api/uploads` (auth)
+Legacy single-step compatibility endpoint.
+
+### `GET /attachments/:attachmentId`
+Immutable media URL.
+
+## 6. Messages
+
+### `POST /api/messages` (auth)
+Request includes:
+- `channelId`
+- `components` or `componentsJson`
+- optional `content`
+
+Server behavior:
+- validates structure and media refs
+- normalizes media items
+- computes searchable `content`
+- persists `componentsJson`
+
+### `GET /api/messages?channelId=...`
+Returns message list with `componentsJson`.
+
+## 7. Gallery Index
+
+### `GET /api/channels/:channelId/media` (auth)
+Returns indexed media rows for grid views.
+
+Query params:
+- `limit` (default 50, max 100)
+- `before` cursor
+- `kind` (`image|video|file`)
+
+Each row includes:
+- linkage (`messageId`, `channelId`, `authorUserId`)
+- source (`attachmentId` or `externalUrl`)
+- display metadata (`mimeType`, dimensions, filename, etc.)
+
+## 8. Gateway
+
+WebSocket path: `/gateway`
+
+Message events:
+- `message.created`
+- `message.updated`
+- `message.deleted`
+
+Upload resolution can cause `message.updated`.