GET /_system/federation/admin — read-эндпоинт топологии федерации

1. Зачем

Панель строит граф федерации пула: кто на кого проксит, где связь односторонняя, где маршрут без авторизации. Сейчас собрать это с инстанса нельзя за один вызов:

• federationSecrets (GraphQL) отдаёт секреты (inbound/outbound, kbUrl, revokedAt, subgraphCount), но не отдаёт сами scope-сабграфы и не отдаёт KB-ноты;
• KB-ноты (mcp_federation_kb_url во frontmatter) наружу не отдаются вообще — а это «куда инстанс реально проксит», особенно для публичных пиров (у них только KB-нота, без секрета);
• инстанс не отдаёт собственную идентичность (kb_id / mcp_url).

Эндпоинт закрывает всё это одним admin-only GET-ом.

2. Контракт

GET /_system/federation/admin
Cookie: <session-cookie>              // admin-сессия, см. ниже
Accept: application/json

Как клиент получает admin-сессию. Эндпоинт не вводит новой авторизации — обычный checkAdmin по UserToken(), который читает session-cookie (или t2g_ personal token). Внешний клиент (панель) получает cookie тем же путём, что и браузер: POST /_system/hat с HAT-JWT ({e, ae:true}, подпись JWT_SECRET инстанса) → инстанс ставит Set-Cookie → клиент переиспользует её для этого GET и для admin-GraphQL-мутаций. Никакого Bearer-admin-JWT trip2g не принимает (UserToken() пропускает не-t2g_ Bearer в anonymous).

{
  "self": {
    "name": "alice",
    "kb_id": "alice.team.io",
    "mcp_url": "https://alice.team.io/_system/mcp",
    "subgraphs": [
      {"id": 1, "name": "internal"},
      {"id": 2, "name": "public"}
    ]
  },
  "outbound": [
    {
      "id": 12,
      "kid": "bob-2026",
      "kb_url": "https://bob.team.io/_system/mcp",
      "revoked_at": null,
      "subgraphs": [{"id": 1, "name": "internal"}]
    }
  ],
  "inbound": [
    {
      "id": 7,
      "kid": "carol-2026",
      "revoked_at": null,
      "subgraphs": [{"id": 1, "name": "internal"}]
    }
  ],
  "kb_notes": [
    {
      "kb_id": "bob",
      "kb_url": "https://bob.team.io/_system/mcp",
      "description": "Use when: Bob's work-status updates.",
      "path": "federation/bob.md"
    }
  ]
}

3. Реализация

• Новый case internal/case/admin/federationtopology/ (или handler internal/case/system/federation/), по существующему паттерну admin-кейсов.
• Роут: зарегистрировать GET /_system/federation/admin рядом с /_system/hat, /_system/mcp (там же, где регистрируются /_system/*). Группа /_system/federation/ — под будущие сиблинги.
• Сборка ответа:
  1. self.subgraphs ← ListAllSubgraphs.
  2. outbound/inbound ← расширить выборку секретов, чтобы тянуть не subgraphCount, а сами строки scope (federation_secret_subgraphs JOIN subgraphs → []{id,name} на секрет). Можно отдельным запросом «scope по всем kid» + сшивка в памяти, чтобы не плодить N+1.
  3. kb_notes ← NoteViews.MCPFederationNotes из загруженного vault.
  4. self.name/kb_id/mcp_url ← из конфигурации инстанса (базовый URL) + дефолт kb_id = host.
• Сериализация: easyjson по конвенции пакета (как internal/federation/types.go).

4. Безопасность

• admin-only, checkAdmin. Без admin → 401/403.
• Секреты в hex НЕ отдаём. Только kid, kb_url, revoked_at, scope. secretHex показывается один раз при создании (существующий createInbound flow) и сюда не попадает.
• Эндпоинт read-only; все мутации остаются в GraphQL (createInbound/OutboundFederationSecret, addFederationSecretSubgraph, removeFederationSecretSubgraph, revokeFederationSecret, updateNotes).

5. Тестирование

• Unit на сборку ответа: фикстуры секретов (inbound/outbound, revoked, с/без scope) + KB-нот + сабграфов → ожидаемый JSON.
• Auth: не-admin → 403, аноним → 401, admin → 200.
• N+1: scope подтягивается батчем, проверить число запросов.
• Совместимость: поля только добавляются; existing federationSecrets GraphQL не трогаем.
• gofmt -w . + go test ./....

6. Вне scope

• Запись через этот эндпоинт (только GET).
• Health/latency пиров (панель меряет сама при краулинге).
• Пагинация (объёмы федерации малы; при необходимости добавить позже).

7. На будущее: /_system/federation/public (зарезервировано)

Отдельный публичный сиблинг, не реализуется в этом спеке — путь резервируется, чтобы не ломать namespace позже.

• Права: аноним/любой (без checkAdmin).
• Отдаёт только то, что хаб и так раскрывает в рантайме федерации: публичную маршрутизацию — free: true KB-ноты / публичные пиры (как их видит анонимный MCP-вызов через accessibleKBNotes()).
• Никогда не отдаёт: сабграфы, scope секретов, kid, inbound-секреты, hidden-сабграфы, непубличные KB-ноты.
• Назначение — публичный discovery сети (другой хаб/директория узнаёт, куда этот хаб федерится публично), без раскрытия приватной топологии.

Раздельные пути (а не один эндпоинт с переключением по роли) гарантируют, что публичный код физически не имеет доступа к admin-выборкам.