microdao-daarion/docs/tasks/TASK_PHASE_MATRIX_PREPARE.md

TASK_PHASE_MATRIX_PREPARE.md

DAARION — PHASE 4: MATRIX PREPARE (Без деплою)

Цей таск підготовчий:
ми створюємо повну структуру й конфіги для Matrix + Element Web + TURN,
але нічого не деплоїмо і не запускаємо.

---

0. Жорсткі обмеження (дуже важливо)

Cursor НЕ МАЄ ПРАВА в цій фазі:

• запускати Synapse, Element, TURN
• змінювати існуючі docker-compose файли
• додавати Matrix у прод-інфру
• змінювати gateway, порти, SSL

Це тільки підготовка файлів для майбутньої PHASE MATRIX FULL.

---

1. Структура каталогів

Створити:

infra/
  matrix/
    synapse/
      homeserver.yaml
      workers.yaml
      log.config
    postgres/
      init.sql
    turn/
      turnserver.conf
    element-web/
      config.json
    gateway/
      matrix.conf
    schemas/
      events/
        matrix_event.schema.json
    README_MATRIX.md

---

2. Synapse — шаблони конфігів

2.1 synapse/homeserver.yaml

Шаблон (без реальних ключів і паролів):

• server_name: "matrix.daarion.space" (placeholder)

• public_baseurl: "https://matrix.daarion.space/" (placeholder)

• database: → Postgres (без реальних паролів)

• listeners::

  • порт 8008 (http)

• registration::

  • enable_registration: false
  • registration_shared_secret: "<TO_BE_FILLED>" (placeholder comment)

• media_store_path: "/data/media" (placeholder)

• federation_domain_whitelist (коментар, не обов'язково)

• modules::

  • залишити секцію порожньою або з коментарями для майбутніх MSC

• log_config: /config/log.config

Важливо: у файлі мають бути коментарі, що це шаблон і реальні значення будуть заповнені в PHASE MATRIX FULL.

2.2 synapse/workers.yaml

Шаблон worker-конфіга:

worker_app: generic_worker

worker_name: worker1

worker_listeners:
  - type: http
    port: 9101
    resources:
      - names: [client, federation]
        compress: false

worker_daemonize: false

worker_log_config: /config/log.config

worker_replication_host: synapse
worker_replication_port: 9093
worker_replication_http_port: 9093

• коментарі, як це буде використовуватись у майбутньому.

2.3 synapse/log.config

Мінімальний logging конфіг (YAML), з рівнем INFO та коментарями.

---

3. Postgres schema init

postgres/init.sql — SQL-шаблон:

• створити БД synapse
• створити роль synapse з паролем 'CHANGE_ME' (коментар, що змінити)
• дати права на БД

create database synapse;
create user synapse with encrypted password 'CHANGE_ME';
grant all privileges on database synapse to synapse;

Коментар: у PHASE MATRIX FULL буде або використовуватись офіційний мигратор Synapse, або helm/compose, а це — лише стартова заготівка.

---

4. TURN/STUN конфіг

turn/turnserver.conf — шаблон для coturn:

• listening-port=3478
• fingerprint
• lt-cred-mech
• realm=daarion.space
• user=matrix:CHANGE_ME
• total-quota=100
• bps-capacity=0

З великими коментарями:

• про використання real secrets
• про те, що TLS/DTLS налаштовуватиметься в PHASE MATRIX FULL

---

5. Element Web конфіг

element-web/config.json — базовий шаблон:

{
  "default_server_config": {
    "m.homeserver": {
      "base_url": "https://matrix.daarion.space",
      "server_name": "daarion.space"
    }
  },
  "brand": "DAARION Matrix",
  "integrations_ui_url": "https://scalar.vector.im/",
  "integrations_rest_url": "https://scalar.vector.im/api",
  "bug_report_endpoint_url": null,
  "features": {},
  "show_labs_settings": true,
  "defaultCountryCode": "UA",
  "disable_custom_urls": true,
  "disable_3pid_login": true
}

З коментарями (у README):

• як і де це буде використовуватись
• що сторінка /element/ буде віддавати цей SPA

---

6. Gateway конфіг (Nginx) — шаблон

gateway/matrix.conf:

# Шаблон. Не підключати до прод nginx поки що.

server {
    listen 80;
    server_name matrix.daarion.space;

    location /_matrix/ {
        proxy_pass http://matrix-homeserver:8008;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
    }

    location /element/ {
        root /var/www/element;
        try_files $uri /index.html;
    }
}

Коментар великими літерами: "ЦЕ ШАБЛОН. НЕ АКТИВУВАТИ, ПОКИ НЕ БУДЕ PHASE MATRIX FULL."

---

7. Schemas — майбутній Bridge

schemas/events/matrix_event.schema.json:

JSON Schema для подій, які:

• Matrix → DAARION (через майбутній bridge)
• DAARION → Matrix

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Matrix Event (Bridge)",
  "type": "object",
  "properties": {
    "event_id": { "type": "string" },
    "room_id": { "type": "string" },
    "sender": { "type": "string" },
    "type": { "type": "string" },
    "origin_server_ts": { "type": "integer" },
    "content": { "type": "object" }
  },
  "required": ["event_id", "room_id", "sender", "type", "content"]
}

---

8. README_MATRIX.md

Документ повинен описати:

8.1. Ролі

• Synapse — Matrix homeserver
• Element Web — клієнт
• TURN — медіа (voice/video, на майбутнє)
• Gateway — HTTP reverse proxy
• Bridge (майбутній) — DAARION City / Agents ↔ Matrix

8.2. Фази

Описати 5 фаз:

1. Phase 4 — Prepare (цей таск)

   • файли, структури, без деплою.

2. Phase 5 — Base Synapse Deploy

   • розгортання Synapse + Postgres + TLS.

3. Phase 6 — Element Web + Gateway

   • деплой статичного SPA, /element/ route, /_matrix/.

4. Phase 7 — Federation + Multi-node

   • кілька нод DAARION Matrix, federation keys, SRV-записи.

5. Phase 8 — DAARION Bridge

   • агентний міст: public rooms ↔ Matrix rooms, presence, events.

8.3. Безпека

• зберігання ключів
• обмеження доступу
• E2EE keys (відповідальність клієнта)
• логування та privacy

---

9. Acceptance Criteria

1. Директорія infra/matrix/ існує з усіма піддиректоріями й файлами.
2. Усі конфіги (homeserver.yaml, workers.yaml, log.config, config.json, turnserver.conf, matrix.conf) — є, містять валідний YAML/JSON/NGINX-синтаксис.
3. postgres/init.sql — є, описує базову схему БД (без реальних паролів).
4. schemas/events/matrix_event.schema.json — валідний JSON Schema.
5. README_MATRIX.md — повністю описує архітектуру, фази, безпеку та майбутні кроки.
6. ЖОДНОГО нового сервісу не додано в docker-compose.
7. ЖОДЕН Matrix-сервіс не запускається в цій фазі.

---

10. Команда для Cursor

"Підготувати структуру та конфіги для Matrix згідно TASK_PHASE_MATRIX_PREPARE.md. НЕ змінювати існуючі docker-compose, НЕ запускати Synapse/Element/Turn, тільки створити файли та README."