Документация CertifiEd

• Быстрый старт→

  От логина оператора до активированной лицензии — сквозной путь на curl.

• API Reference→

  Panel и client эндпоинты, авторизация, коды ошибок, rate limits.

• Webhooks→

  События, формат конверта, подпись sha256 и расписание ретраев.

• Клиентский SDK→

  CertifiEd.Client для .NET: оффлайн-проверка, heartbeat, feature-флаги.

• Привязка к железу→

  Режимы none / fixed / firstActivation, перепривязка и seat-лимиты.

• Протокол лицензий→

  Формат токена, оффлайн-маркер, вычисление статуса и grace-период.

Задача#

On-prem ПО, поставляемое клиентам, нуждается в защите от нелицензионного использования — без постоянного доступа в интернет и без передачи контроля в чужие облака.

Как устроено решение#

CertifiEd выпускает криптографически подписанные лицензии (Ed25519). Конфигурация продукта — feature flags и лимиты — живёт внутри подписанного токена, а не отдаётся через API: клиентское приложение валидирует лицензию локально по публичному ключу и работает оффлайн до 30 дней.

• Self-hosted полностью. PostgreSQL, MinIO, observability — на своих серверах. Никаких Cloud KMS, managed-сервисов и SaaS-биллеров.
• Multitenant с первого дня. Дерево компаний произвольной глубины (ltree): корень — прямой клиент, потомки — суб-клиенты и реселлеры. Роль, выданная на узле, действует на всё поддерево.
• Оффлайн — норма. Heartbeat желателен, но не обязателен; grace-период до 30 дней.
• Аудит всего. Каждая мутация попадает в audit_log.

Роли и скоупы#

Глоссарий#

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

Монолит с чистыми границами — Clean Architecture, слои зависят строго в одну сторону.

SharedKernel <- Domain <- Application <- Infrastructure <- Api                                                   <- Client (SDK, token format only)

• SharedKernel — Result<T>, Error, примитивы. Без зависимостей.
• Domain — сущности, enums, value objects. Без зависимостей.
• Application — use-cases, интерфейсы (ISigner, репозитории), DTO.
• Infrastructure — EF Core (Npgsql, snake_case, ltree), EncryptedFileSigner, WebhookDispatchWorker, SMTP.
• Api — ASP.NET Core; два контура в одном процессе.
• Client — SDK, зависит только от формата токена.

Два контура API#

Подробности — в разделе API Reference.

Подпись и ключи#

• Ed25519-keypair на каждый шаблон (NSec.Cryptography).
• Приватные ключи лежат в файлах, зашифрованных AES-256-GCM; master key — переменная окружения CERTIFIED_MASTER_KEY.
• Ротация: новый ключ становится active, старый — rotating, затем retired. При компрометации ключ помечается compromised, лицензии перевыпускаются.

Данные, фоновые задачи, observability#

• PostgreSQL 16: UUIDv7, timestamptz, jsonb, ltree (companies.path) для запросов по поддереву. Heartbeats — кандидат на партиционирование по месяцам.
• Фоновые BackgroundService-воркеры (без Hangfire в v1): доставка webhooks с ретраями и подписью X-CertifiEd-Signature, истечение лицензий, очистка heartbeats.
• Serilog (compact JSON) + OpenTelemetry (traces/metrics, OTLP опционально); health-эндпоинты /health, /health/live, /health/ready.

Развёртывание#

[Caddy / nginx: TLS]   |-- panel.certified.example    -> panel static build   |-- portal.certified.example   -> customer portal   |-- certified.example          -> landing static build   `-- api.certified.example      -> CertifiEd.Api (Kestrel)
[PostgreSQL 16]   [MinIO: backups/export]   [Redis: optional]   [SMTP]

Cloudflare — только edge (TLS / WAF / DNS), без Workers и KV. Всё состояние остаётся в вашем контуре.

Переменные окружения#

Чек-лист прода#

• Бэкапы PostgreSQL (pg_dump + WAL) и CERTIFIED_KEYS_DIR.
• Смена seed-пароля оператора.
• Rate limiting включён: client 100/мин, panel 300/мин.
• OTLP направлен в собственный Grafana-стек, настроен алертинг.
• Партиционирование heartbeats при росте объёма.

Куда дальше#

• Быстрый старт — выпустить первую лицензию за десять минут.
• Протокол лицензий — что именно лежит внутри токена.
• Клиентский SDK — встроить проверку в своё приложение.