EvoFirewall/docs/architecture.md

Архитектура EvoFirewall

Централизованный control plane для firewall-агентов (Linux nft/ipset, MikroTik address-list).

Компоненты

Компонент	Путь	Роль
Web SPA	apps/web	ReUI Frame, TanStack Router/Query
API	apps/api	Fastify 5, JWT + agent tokens
DB	packages/db	Drizzle + SQLite WAL
Shared	packages/shared	Zod-контракты, RBAC helpers
UI	packages/ui	shadcn primitives @evofw/ui
Agents	apps/api/src/agent-scripts	install.sh, sync, MikroTik RSC

Потоки

1. Enroll — POST /v1/agent/enroll + одноразовый X-EvoFW-Enrollment-Credential конкретной install-ссылки → pending agent; глобальный seed не передаётся клиенту
2. Approve — UI/API → status approved
3. Policy — GET /v1/agent/policy → deny/allow CIDRs + default_action + optional port_rules + hash (apply_version: 3) + script_sha256 (Linux; не в policy.hash)
4. Linux self-update — timer: GET /v1/agent/sync-script (ETag / If-None-Match) → при новой версии заменить /usr/local/sbin/evofw-firewall.sh и exec до policy
5. Apply — agent пишет kernel rules (L3 + L4 port ACL на nft), POST /v1/agent/apply-report + stats + optional host_firewall snapshot
6. Lists refresh — cron каждые 5 мин (json_url / domains / evobgp_community)

Политика

• Именованные наборы правил (policy_sets); агенту назначается M:N через agent_policy_sets
• Правило в наборе: action: deny | allow + ровно один источник — IP-список (list_id), CIDR или DNS-имя (hostname → A/AAAA, кэш в policy_rule_resolved)
• Evaluate: правила всех назначенных enabled-наборов (sort + priority) + ip_overrides
• Цепочка ядра всегда: deny → allow → default_action (accept | drop на агенте)
• На Linux nft: deny → Port ACL (close / open / implicit drop для портов с open) → allow → default_action на hooks prerouting (priority mangle, fib daddr type local, до Docker DNAT), input и forward (ct status dnat). open по списку = входящие на публичный порт только с разрешённых src (хост и Docker -p); исходящий клиентский 80/443 не режется.
• Exact overlap: allow \ deny (conflicts_dropped); deny wins
• Overrides, смена наборов, default_action, Port ACL и refresh DNS/lists бампят policy_generation

Auth

• Portal SSO app id fw, permissions fw:*
• Agent bearer token (sha256 hash в БД)

Деплой

Один alpine-контейнер (evofw / алиас evofirewall): Fastify отдаёт API, SPA и install-ссылки GET /{slug}. Сборка — docker buildx bake из deploy/docker. Релизы: releasing.md.