feat: per-sender tokens for GitLab webhook (team isolation) (#20)

Author: lavr

README.md

@@ -15,7 +15,7 @@ CLI и HTTP-сервер для отправки сообщений в корп
 - **Отправка сообщений** из CLI, скриптов, пайплайнов CI/CD
 - **API-запросы** — произвольные вызовы eXpress BotX API из командной строки с автоаутентификацией
 - **HTTP-сервер** с API для отправки и приёма вебхуков
-- **Alertmanager, Grafana и GitLab** — готовые эндпоинты для мониторинга; универсальный приёмник любых событий GitLab с фильтрами и шаблонами ([examples/gitlab/](examples/gitlab/))
+- **Alertmanager, Grafana и GitLab** — готовые эндпоинты для мониторинга; универсальный приёмник любых событий GitLab с фильтрами, шаблонами и изоляцией команд по своим токенам ([examples/gitlab/](examples/gitlab/))
 - **Асинхронная очередь** — RabbitMQ или Kafka для надёжной доставки
 - **Секреты** — поддержка переменных окружения и HashiCorp Vault
 - **Kubernetes-ready** — Docker, Helm chart, бинарник
@@ -167,7 +167,7 @@ chats:
 
 ## Интеграции
 
-В режиме веб-сервера есть методы для интеграции с alertmanager, grafana и gitlab (универсальный приёмник любых событий GitLab с фильтрами `only`/`exclude`, шаблонами по типам и `error_events`).
+В режиме веб-сервера есть методы для интеграции с alertmanager, grafana и gitlab (универсальный приёмник любых событий GitLab с фильтрами `only`/`exclude`, шаблонами по типам и `error_events`). Несколько команд могут делить один GitLab-эндпоинт с изоляцией по своим `X-Gitlab-Token` — см. [senders](docs/integrations.md#изоляция-команд-senders-несколько-токенов) и пример [examples/gitlab/config-senders.yaml](examples/gitlab/config-senders.yaml).
 
 Пример конфига alertmanager:
 

docs/commands.md

@@ -711,9 +711,9 @@ express-botx config validate --format json
 
 Проверки:
 - Неизвестные ключи в YAML (предупреждения)
-- Обязательные поля: `host` и `id` для ботов, `secret` или `token` (но не оба)
+- Обязательные поля: `host` и `id` для ботов, `secret` или `token` (но не оба); для `server.gitlab` — `secret`/`secret_token` или непустой `senders` (у каждого sender'а — секрет и непустой `chats`; байт-идентичные значения токенов — одинаковые литералы или одинаковые `env:`/`vault:` ссылки — не дублируются, разные ссылки на одно значение проверяются на старте `serve`)
 - Форматы: UUID для `id` и `chat_id`, длительности (`timeout`, `retry_backoff`), допустимые enum-значения (`cache.type`, `queue.driver`, `routing_mode`)
-- Перекрёстные ссылки: `bot` в чате ссылается на существующего бота, не более одного чата по умолчанию, `default_chat_id` в alertmanager/grafana/gitlab ссылается на существующий алиас
+- Перекрёстные ссылки: `bot` в чате ссылается на существующего бота, не более одного чата по умолчанию, `default_chat_id` в alertmanager/grafana/gitlab и чаты в `server.gitlab.routes`/`senders` ссылаются на существующие алиасы
 
 Флаги:
 

docs/configuration.md

@@ -82,6 +82,11 @@ server:
           branch:  ["main", "release/*"]
         chats: [backend-mrs, releases]    # совпало → в оба чата (объединение+дедуп)
         stop: true                        # совпав, оборвать перебор правил
+    senders:                              # опционально — изоляция команд по своему X-Gitlab-Token
+      - secret: env:TEAM_A_GITLAB_TOKEN   # токен команды A (literal/env:/vault:)
+        chats: [team-a]                   # события по этому токену уходят ТОЛЬКО сюда
+      - secret: env:TEAM_B_GITLAB_TOKEN
+        chats: [team-b, team-b-alerts]
 ```
 
 Секция `server.gitlab` (обязательна для включения эндпоинта `/api/v1/gitlab`).
@@ -92,14 +97,15 @@ server:
 
 | Поле | Описание |
 |---|---|
-| `secret` / `secret_token` | Ожидаемое значение заголовка `X-Gitlab-Token`. Ссылка `literal` / `env:VAR` / `vault:path#key`. Обязательно. |
+| `secret` / `secret_token` | Ожидаемое значение заголовка `X-Gitlab-Token`. Ссылка `literal` / `env:VAR` / `vault:path#key`. Обязателен `secret` **или** непустой `senders` (иначе ручка осталась бы без auth). |
 | `default_chat_id` | UUID или алиас чата по умолчанию (должен существовать в `chats`). |
 | `events.only` | Allowlist event-ключей. Запись матчит полный `kind.subtype`, голый `kind` или `kind.*`. Пустой → пропускать всё. |
 | `events.exclude` | Denylist event-ключей (та же грануляция). Всегда выигрывает над `only`. |
 | `templates` | Мапа `event-ключ → inline Go-шаблон`. Переопределяет встроенные дефолты. |
 | `template_files` | Мапа `event-ключ → путь к файлу шаблона`. Один ключ нельзя задать и в `templates`, и в `template_files`. |
 | `error_events` | Список event-ключей, доставляемых с `notification.status=error` (та же грануляция матчинга). |
 | `routes` | Опциональный упорядоченный список правил роутинга. Событие уходит в чаты **всех** совпавших правил (объединение+дедуп), `stop:true` обрывает перебор. Каждое правило: `match` (селектор → паттерны glob/`/regex/`; `event` — по event-ключу), `chats` (непустой список алиасов/UUID), `stop`. Без секции — прежнее поведение (один чат). Подробнее и приоритет чатов — в [docs/integrations.md](integrations.md#роутинг-событий-по-чатам-routes). |
+| `senders` | Опциональный список дополнительных входящих токенов с жёсткой привязкой к чатам (изоляция команд). Каждый элемент: `secret`/`secret_token` (ссылка `literal`/`env:`/`vault:`, обязателен) и непустой `chats` (алиасы/UUID существующих чатов). Совпал sender-токен → событие уходит **только** в его `chats`; `?chat_id`, `?bot`, `routes` и `default_chat_id` игнорируются. Глобальные `events.only/exclude`, `templates` и `error_events` применяются как обычно. Дубликаты разрезолвленных токенов (sender↔sender, sender↔`secret`) — ошибка на старте. Подробнее — в [docs/integrations.md](integrations.md#изоляция-команд-senders-несколько-токенов). |
 
 ## Переменные окружения
 
@@ -220,7 +226,7 @@ express-botx config chat list                             # покажет (defa
 Приоритет выбора чата в HTTP-сервере:
 - `/send`: `chat_id` из запроса → чат по умолчанию → ошибка
 - `/alertmanager`, `/grafana`: `?chat_id=` → `default_chat_id` из конфига вебхука → чат по умолчанию → единственный чат → ошибка
-- `/gitlab`: `?chat_id=` → `routes` (все совпавшие правила, объединение+дедуп) → `default_chat_id` → чат по умолчанию → единственный чат → `200 {ignored}`
+- `/gitlab`: `?chat_id=` → `routes` (все совпавшие правила, объединение+дедуп) → `default_chat_id` → чат по умолчанию → единственный чат → `200 {ignored}`; при совпадении sender-токена (`server.gitlab.senders`) цели — всегда `chats` этого sender'а, остальное игнорируется
 
 ## Формат host
 

docs/integrations.md

@@ -174,6 +174,8 @@ generic-декодером, а событие сводится к **event-клю
 
 Аутентификация — по заголовку `X-Gitlab-Token` (GitLab не умеет ставить
 `Authorization`/`X-API-Key`), поэтому эндпоинт не использует обычные `api_keys`.
+Помимо общего `secret` можно завести несколько изолированных токенов команд —
+см. [senders](#изоляция-команд-senders-несколько-токенов).
 
 ### Event-ключ и деривация субтипа
 
@@ -383,6 +385,61 @@ server:
         chats: [hotfixes]
 ```
 
+### Изоляция команд: senders (несколько токенов)
+
+Когда один эндпоинт обслуживает несколько команд, `?chat_id`/`routes` не дают
+изоляции: любой, кто знает общий секрет, может отправить событие в чужой чат.
+`server.gitlab.senders` — опциональный список **дополнительных** входящих
+токенов, каждый жёстко привязан к своему набору чатов:
+
+```yaml
+server:
+  gitlab:
+    secret: env:GITLAB_WEBHOOK_TOKEN     # общий дефолтный токен (опционален при senders)
+    default_chat_id: dev
+    senders:
+      - secret: env:TEAM_A_GITLAB_TOKEN  # literal / env: / vault: — как обычный secret
+        chats: [team-a]
+      - secret: env:TEAM_B_GITLAB_TOKEN
+        chats: [team-b, team-b-alerts]
+```
+
+**Резолв аутентификации.** Входящий `X-Gitlab-Token` сверяется со всеми
+sender-токенами и с дефолтным `secret` (constant-time, без early-exit):
+
+- совпал **sender-токен** → событие уходит **только** в `chats` этого sender'а
+  (fan-out, best-effort — как у `routes`); `?chat_id=`, `?bot=`, `routes` и
+  `default_chat_id` **игнорируются** — команда A не может отправить в чаты
+  команды B или от имени чужого бота, даже подставив `?chat_id`/`?bot`;
+- совпал **дефолтный `secret`** → прежнее поведение без изменений
+  (`?chat_id` → `routes` → `default_chat_id` → …);
+- не совпал ни один → `401`.
+
+Глобальные `events.only/exclude`, `templates`/`template_files` и `error_events`
+применяются к sender-событиям как обычно (отфильтрованное событие → `200
+{ignored}` и для sender'а). Своих `routes`/фильтров/шаблонов у sender'а нет —
+его скоуп только чаты.
+
+**Правила конфигурации:**
+
+- Каждый sender: непустой `secret`/`secret_token` + непустой `chats`
+  (алиасы/UUID существующих чатов из секции `chats`).
+- Должен быть задан общий `secret` **или** хотя бы один sender — иначе ручка
+  осталась бы без аутентификации (ошибка валидации).
+- Дефолтный `secret` опционален: можно оставить только senders (тогда
+  неизвестный токен всегда получает `401`), а можно смешанный режим — общий
+  токен для большинства + изолированные senders для чувствительных команд.
+- Значения токенов задаются ссылками `env:`/`vault:` — в общем YAML только
+  ссылки, команды не видят секреты друг друга.
+- Дубликаты **разрезолвленных** значений (sender↔sender или sender↔дефолт) —
+  ошибка на старте: аутентификация была бы неоднозначной. Байт-идентичные
+  строки в конфиге (один литерал или одна и та же `env:`/`vault:` ссылка
+  дважды) ловит уже `config validate`.
+
+В GitLab каждая команда настраивает свой webhook как обычно
+([Настройка GitLab](#настройка-gitlab)), указывая в **Secret token** значение
+своего sender-токена.
+
 ### Проверка вручную
 
 ```bash

examples/gitlab/README.md

@@ -13,6 +13,9 @@ then filtered and rendered by a per-event template registry.
 - `config-routing.yaml` — same endpoint with `server.gitlab.routes`: one event
   fans out to multiple chats by project/event/branch (all-match + `stop`, with a
   `default_chat_id` fallback).
+- `config-senders.yaml` — same endpoint with `server.gitlab.senders`: two teams
+  with their own `X-Gitlab-Token` values, each isolated to its own chats, plus
+  the shared default `secret` (mixed mode).
 - `webhook-merge-request-open.json` — MR opened (`merge_request.open`).
 - `webhook-merge-request-merge.json` — MR merged (`merge_request.merge`).
 - `webhook-note.json` — comment on an MR (`note.MergeRequest`).
@@ -48,7 +51,9 @@ without sending a message.
 In a group or project: **Settings → Webhooks → Add new webhook**
 
 - **URL:** `http://express-botx:8080/api/v1/gitlab` (optionally `?chat_id=<alias>`)
-- **Secret token:** same value as `server.gitlab.secret`
+- **Secret token:** same value as `server.gitlab.secret` — or, when using
+  `server.gitlab.senders`, your team's own sender token
+  (see [Per-team tokens](#per-team-tokens-senders))
 - **Triggers:** enable whichever events you want — or all of them, since filtering
   now happens in express-botx via `events.only` / `events.exclude`.
 
@@ -78,3 +83,17 @@ back to `default_chat_id`. Delivery is best-effort: `200` with `{results,errors}
 once at least one chat is delivered, `502` if they all fail. See the
 [routing section](../../docs/integrations.md#роутинг-событий-по-чатам-routes)
 for the full model and chat-selection priority.
+
+## Per-team tokens (senders)
+
+`config-senders.yaml` adds `server.gitlab.senders` — extra incoming
+`X-Gitlab-Token` values, each hard-bound to its own chats. A request
+authenticated with a sender token is delivered **only** to that sender's chats
+(`?chat_id=`, `routes` and `default_chat_id` are ignored), so teams sharing one
+endpoint cannot post into each other's chats. The global `events` filter,
+templates and `error_events` apply as usual; the default `secret` keeps its
+ordinary behaviour and may be omitted when only senders are used. Token values
+are `env:`/`vault:` references — the shared YAML never contains plaintext
+secrets, and duplicate resolved tokens fail at startup. See the
+[senders section](../../docs/integrations.md#изоляция-команд-senders-несколько-токенов)
+for details.

examples/gitlab/config-senders.yaml

@@ -0,0 +1,68 @@
+# Example config for the universal GitLab webhook endpoint (/api/v1/gitlab)
+# with per-sender tokens (`server.gitlab.senders`) — team isolation.
+#
+# Several teams share one endpoint, each with its OWN X-Gitlab-Token bound to
+# its own chats. An event authenticated with a sender token is delivered ONLY
+# to that sender's chats: ?chat_id=, routes and default_chat_id are ignored
+# for it, so team A cannot post into team B's chats even on purpose. The
+# global events filter, templates and error_events still apply.
+#
+# The default `secret` stays fully functional (mixed mode): webhooks using it
+# keep the ordinary behaviour (?chat_id -> routes -> default_chat_id -> ...).
+# It may also be omitted entirely — then only the sender tokens authenticate.
+# At least one of `secret` / `senders` is required (the endpoint must not be
+# left without auth). Duplicate resolved token values (sender vs sender, or
+# sender vs the default secret) fail at startup.
+#
+# Token values are secret references (env:/vault:), so the shared YAML holds
+# only references and teams never see each other's secrets.
+
+bots:
+  mybot:
+    host: "env:BOT_HOST"
+    id: "env:BOT_ID"
+    secret: "env:BOT_SECRET"
+
+chats:
+  dev:
+    id: "env:DEV_CHAT_ID"
+    bot: mybot
+    default: true
+  team-a:
+    id: "env:TEAM_A_CHAT_ID"
+    bot: mybot
+  team-b:
+    id: "env:TEAM_B_CHAT_ID"
+    bot: mybot
+  team-b-alerts:
+    id: "env:TEAM_B_ALERTS_CHAT_ID"
+    bot: mybot
+
+server:
+  listen: ":8080"
+  base_path: /api/v1
+  gitlab:
+    # Shared default token — small teams keep using it as before.
+    secret: "env:GITLAB_WEBHOOK_TOKEN"
+    default_chat_id: dev
+
+    # Isolated per-team tokens. Each team sets its own value as the webhook's
+    # "Secret token" in GitLab; events for that token go only to its chats.
+    senders:
+      - secret: "env:TEAM_A_GITLAB_TOKEN"
+        chats: [team-a]
+      - secret: "env:TEAM_B_GITLAB_TOKEN"
+        chats: [team-b, team-b-alerts]   # fan-out to both, best-effort
+
+    # Global filter/templates/error_events apply to sender events too.
+    events:
+      only:
+        - "merge_request.*"
+        - "pipeline.failed"
+        - "build.failed"
+        - "push"
+      exclude:
+        - "merge_request.update"
+    error_events:
+      - "pipeline.failed"
+      - "build.failed"

internal/cmd/bot.go

@@ -573,10 +573,10 @@ func runBotRm(args []string, deps Deps) error {
 }
 
 type botTokenResult struct {
-	Name    string `json:"name,omitempty"`
-	Token   string `json:"token,omitempty"`
-	Status  string `json:"status,omitempty"`
-	Error   string `json:"error,omitempty"`
+	Name   string `json:"name,omitempty"`
+	Token  string `json:"token,omitempty"`
+	Status string `json:"status,omitempty"`
+	Error  string `json:"error,omitempty"`
 }
 
 func runBotToken(args []string, deps Deps) error {

internal/cmd/cmd.go

@@ -211,7 +211,6 @@ func refreshToken(cfg *config.Config, cache token.Cache) (string, error) {
 	return tok, nil
 }
 
-
 func newCache(cfg config.CacheConfig) token.Cache {
 	switch cfg.Type {
 	case "file":

internal/cmd/send.go

@@ -8,9 +8,9 @@ import (
 	"flag"
 	"fmt"
 	"io"
-	"sync"
 	"os"
 	"path/filepath"
+	"sync"
 
 	"github.com/lavr/express-botx/internal/botapi"
 	"github.com/lavr/express-botx/internal/config"