chat-server/PROTOCOL.md

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:

{ "username": "alice", "password": "password123" }

Response fields include:

• token
• userId
• username
• handle
• publicKey
• encrypted key backup fields

POST /auth/login

Request:

{ "username": "alice", "password": "password123" }

Response includes token + profile/key fields.

POST /auth/join

Request:

{
  "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:

{
  "source": "local_upload",
  "attachmentId": "att_...",
  "status": "uploading|ready|failed"
}

2. External URL:

{
  "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.