# Сервер синхронизации Верстак — руководство

## 1. Зачем нужен сервер

Сервер позволяет синхронизировать данные между несколькими устройствами (например, рабочий ПК и ноутбук), а также хранить резервную копию vault'ов.

Он не обязателен — Верстак работает полностью локально и без сервера.

## 2. Установка

### Быстрая установка (systemd)

```bash
# Сборка бинарника
go build -o verstak-server ./cmd/verstak-server/

# Установка (от root)
sudo ./verstak-server/install.sh \
  --port 47732 \
  --admin-user admin \
  --admin-pass 'мой-надёжный-пароль'
```

Скрипт:
- создаёт системного пользователя `verstak`;
- копирует бинарник в `/usr/local/bin/verstak-server`;
- создаёт `/var/lib/verstak-server` для данных;
- записывает админа в конфиг;
- устанавливает systemd-сервис `verstak-server.service`;
- запускает и включает автозапуск.

### Ручной запуск (для тестирования)

```bash
# Одной командой
./verstak-server \
  --port 47732 \
  --data ./server-data \
  --admin-user admin \
  --admin-pass 'мой-надёжный-пароль'
```

Флаги:
| Флаг | По умолчанию | Описание |
|---|---|---|
| `--port` | `47732` | Порт сервера |
| `--data` | `./data` | Директория для данных (SQLite + blobs) |
| `--admin-user` | — | Имя администратора (создаётся при первом запуске) |
| `--admin-pass` | — | Пароль администратора |

Если не указать `--admin-user` и `--admin-pass`, сервер запустится, но админ-панель будет недоступна (некому будет логиниться).

## 3. Админ-панель

### Как открыть

Откройте в браузере: `http://<сервер>:47732/admin/login`

Войдите с логином и паролем, указанными при установке.

### Что там есть

- **Дашборд** — статистика: количество устройств, количество операций, список API-ключей, форма настройки SMTP.
- **Управление API-ключами** — просмотр, создание и удаление ключей устройств.
- **Настройка SMTP** — сервер, порт, логин, пароль, email отправителя, URL сервера (для ссылок в письмах). SMTP нужен для отправки писем подтверждения email и сброса пароля.

Сессия живёт 24 часа. После перезапуска сервера все сессии сбрасываются (хранятся в памяти).

### Несколько админов

Можно запустить сервер с другими `--admin-user`/`--admin-pass` — добавится второй администратор. Повторный запуск с тем же именем меняет пароль.

## 4. Регистрация пользователей

### Как зарегистрироваться

Откройте в браузере: `http://<сервер>:47732/register`

Форма принимает:
- **Логин** — латинские буквы и цифры
- **Email** — для подтверждения и сброса пароля
- **Пароль** — минимум 8 символов, латинские буквы и цифры

После отправки формы на email приходит письмо с ссылкой подтверждения (если SMTP настроен). Если SMTP не настроен, подтверждение происходит автоматически, и можно сразу логиниться.

### Как войти

`http://<сервер>:47732/login` — форма логина принимает логин или email.

### Личный кабинет

После входа — `/dashboard` — список устройств пользователя с полными API-ключами, кнопками копирования и удаления, форма добавления нового устройства.

## 5. API-ключи (устройства)

### Что такое API-ключ

API-ключ — это токен, который клиент (Верстак на вашем ноутбуке или ПК) использует для доступа к серверу. Без ключа push/pull/blobs не работают.

### Как создать

#### Через веб-интерфейс пользователя

1. Зайти в `/login`, войти.
2. В `/dashboard` ввести имя устройства и нажать "Connect".
3. Скопировать сгенерированный ключ.

#### Через админ-панель

1. Зайти в `/admin/login`.
2. В разделе "API Keys" ввести имя устройства и нажать "Create".
3. Скопировать сгенерированный ключ.

#### Через API (требует логин+пароль пользователя)

```bash
curl -X POST http://localhost:47732/api/v1/device/register \
  -H "Content-Type: application/json" \
  -d '{"name":"мой-ноутбук","username":"ivan","password":"пароль-пользователя"}'
```
Ответ: `{"device_id":"...","api_key":"..."}`

### Как использовать

Ключ передаётся в заголовке `Authorization: Bearer <ключ>`:
```bash
curl -X POST http://localhost:47732/api/v1/sync/push \
  -H "Authorization: Bearer b10c5d8e3f2a..." \
  -H "Content-Type: application/json" \
  -d '{"device_id":"b10c5d8e3f2a","ops":[...]}'
```

В GUI Верстак достаточно указать URL сервера, логин и пароль — устройство зарегистрируется автоматически.

### Один ключ на все устройства или отдельный на каждое?

**На каждое устройство — отдельный ключ.** Так вы сможете отозвать доступ конкретному устройству (удалить ключ в личном кабинете), не затронув остальные.

Технически один и тот же ключ можно использовать на нескольких устройствах, но:
- его нельзя будет удалить, не отключив все устройства разом;
- в логах сервера все операции будут выглядеть как от одного устройства;
- это не поддерживаемый сценарий.

**Рекомендация:** создавайте отдельный ключ для каждого клиента (ПК, ноутбук, телефон).

## 6. Настройка клиента

### CLI
```bash
verstak sync push --vault /путь/к/vault
verstak sync pull --vault /путь/к/vault
verstak sync status --vault /путь/к/vault
```

Перед использованием нужно указать URL сервера и API-ключ в `.verstak/config.yml` внутри vault:
```yaml
sync:
  server_url: http://мой-сервер:47732
  api_key: мой-ключ
  device_id: id-устройства   # опционально
  auto_sync: false
```

API-ключ и device_id можно получить, зарегистрировав устройство через API:
```bash
curl -s http://сервер:47732/api/v1/device/register \
  -H "Content-Type: application/json" \
  -d '{"name":"мой-пк","username":"ivan","password":"мой-пароль"}' | jq .
```

### GUI
В графическом интерфейсе нажмите на иконку шестерёнки в левом нижнем углу → откроется окно настроек синхронизации. Укажите URL сервера, логин и пароль, нажмите "Test Connection" для проверки, затем "Сохранить". Кнопка "Синхронизировать" (или пункт меню в сайдбаре) запускает push + pull.

## 7. Безопасность

Сервер **не поддерживает HTTPS**. В production используйте reverse proxy (nginx, Caddy) для терминирования TLS.

Что стоит учесть:
- Регистрация устройств требует аутентификации пользователя.
- Подтверждение email обязательно, если настроен SMTP (иначе подтверждение автоматическое).
- Нет logout'а для админа — сессия живёт 24 часа или до перезапуска сервера.
- Нет rate limiting'а — возможен перебор пароля.
- Пароли хранятся в bcrypt — база данных не должна быть общедоступной.
- SMTP-пароль хранится в открытом виде в конфиге сервера.

Рекомендации для production:
- Закрыть порт сервера фаерволом (только доверенные IP).
- Использовать VPN (WireGuard/OpenVPN) для доступа между устройствами.
- Поставить nginx/Caddy перед сервером с HTTPS.
- Настроить SMTP для полноценного подтверждения email и сброса пароля.

## 8. Полный API

### Открытые endpoint'ы

| Метод | Путь | Описание |
|---|---|---|
| GET | `/api/v1/health` | Проверка здоровья сервера |

### Требуют API-ключ (Authorization: Bearer)

| Метод | Путь | Описание |
|---|---|---|
| POST | `/api/v1/sync/push` | Отправить операции на сервер |
| POST | `/api/v1/sync/pull` | Получить операции с сервера |
| POST | `/api/v1/blobs/` | Загрузить blob (multipart) |
| GET | `/api/v1/blobs/{sha256}` | Скачать blob |

### Требуют логин+пароль (body JSON)

| Метод | Путь | Описание |
|---|---|---|
| POST | `/api/v1/auth/register` | Регистрация (username, email, password) |
| GET | `/api/v1/auth/confirm?token=` | Подтверждение email |
| POST | `/api/v1/auth/login` | Вход, возвращает Bearer-токен |
| POST | `/api/v1/auth/forgot` | Запрос сброса пароля (email) |
| POST | `/api/v1/auth/reset` | Сброс пароля (token, password) |
| POST | `/api/v1/device/register` | Регистрация устройства (name, username, password) |

### Требуют сессию пользователя (Bearer token или cookie)

| Метод | Путь | Описание |
|---|---|---|
| GET | `/api/v1/user/devices` | Список устройств пользователя |

### Требуют сессию админа (cookie)

| Метод | Путь | Описание |
|---|---|---|
| GET/POST | `/admin/login` | Страница входа / отправка формы |
| GET | `/admin/dashboard` | Дашборд |
| GET | `/admin/api/keys` | Список API-ключей (JSON) |
| POST | `/admin/api/keys` | Создать ключ |
| DELETE | `/admin/api/keys/{id}` | Удалить ключ |
| POST | `/admin/api/smtp` | Сохранить SMTP-конфигурацию |

### Пользовательский веб-интерфейс (cookie)

| Метод | Путь | Описание |
|---|---|---|
| GET/POST | `/register` | Форма регистрации |
| GET/POST | `/login` | Форма входа |
| GET | `/dashboard` | Личный кабинет (устройства) |
| GET | `/logout` | Выход |