# 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`.