Licensing Service

@nx/licensing phát hành license từ các policy tái sử dụng, gắn chúng với thiết bị qua activation, xác thực lúc runtime, và ký chứng chỉ Ed25519 mà LicenseMiddleware của @nx/core xác minh offline. Nó không sở hữu schema nào (mọi bảng nằm trong @nx/core) và chỉ phụ thuộc @nx/core. Billing, subscription, hoá đơn, đo lường sử dụng và dunning rõ ràng nằm ngoài phạm vi.

1. Tham chiếu nhanh

Thuộc tính	Giá trị
Package	@nx/licensing
Code	SVC-00140-LICENSING
Type	Microservice
Runtime	Bun
Base Class	VerifierApplication
Location	packages/licensing
Base Path	/v1/api/licensing
Dev Port	31120
Container Port	3000 (ngoài 31120)
Snowflake ID	11
DB Schema	licensing (5 bảng)
Binding Namespace	@nx/licensing
Run Modes	startup, migrate (env RUN_MODE)

SVC-00140-LICENSING đã đăng ký trong enum ServiceCodes của core. Nó được gán lại từ SVC-00110 (thuộc @nx/outreach) để giải quyết va chạm; SVC-00120 thuộc helpdesk nên licensing nhận SVC-00140. Xem ADR-0002.

2. Mục đích & Phạm vi

Bao gồm	Loại trừ
Template policy (TRIAL / SUBSCRIPTION / PERPETUAL)	Billing, hoá đơn, dunning
Feature flag có kiểu (PolicyFeature, giá trị đa hình)	Tích hợp subscription / thanh toán
Phát hành, gia hạn, đình chỉ, khôi phục, thu hồi license	Cưỡng chế runtime theo từng feature (consumer làm việc đó)
Kích hoạt thiết bị (gắn fingerprint, giới hạn seat)	Đo lường sử dụng / heartbeat reaper
Pipeline xác thực runtime (POST /validation/validate)	UI license (việc của frontend)
Ký chứng chỉ Ed25519 + phân phối Redis	Xác minh chứng chỉ (do middleware @nx/core làm)
Phát hành free-trial tự phục vụ
Log audit vòng đời LicenseEvent

3. Tech Stack

External:

Library	Mục đích
@venizia/ignis	IoC container, DI, VerifierApplication, ControllerFactory
@venizia/ignis-helpers	Logger, DefaultRedisHelper, applicationEnvironment, AES helper
@hono/zod-openapi	Sinh OpenAPI từ Zod schema
@scalar/hono-api-reference	OpenAPI explorer tại /doc
hono	HTTP server (qua IGNIS)
drizzle-orm	Truy cập DB qua PostgresCoreDataSource
pg	Driver PostgreSQL
node:crypto	Ed25519 sign/verify, AES-256-GCM (trong cert helper của @nx/core)

bullmq và @platformatic/kafka được liệt kê trong package.json nhưng không được wire — application không đăng ký component Kafka, Queue, WebSocket hay Mail nào (xem §8).

Internal:

Package	Mục đích
@nx/core	Schema Policy/License/Activation/PolicyFeature/LicenseEvent + repository (re-export), VerifierApplication, LicenseCertSignerHelper, LicenseMiddleware, LicenseStatuses/PolicyTypes/DurationUnits, Redis helper. Package này không sở hữu định nghĩa schema nào.

4. Cấu trúc dự án

packages/licensing/
├── src/
│   ├── application.ts            # subclass VerifierApplication
│   ├── index.ts                  # bootstrapApplication()
│   ├── migrate.ts                # bootstrapMigration()
│   ├── common/                   # constants, keys, rest-paths, types
│   ├── controllers/              # 5 controller (policy, policy-feature, license, activation, validation)
│   ├── datasources/              # binding PostgresCoreDataSource
│   ├── errors/                   # lỗi license / activation / policy / duration
│   ├── migrations/processes/     # 4 seed (permissions, free-trial, role-perms, guest-perms)
│   ├── models/requests/          # zod request schema
│   ├── repositories/             # re-export từ @nx/core
│   └── services/licensing/       # 3 service + base dùng chung
├── package.json
└── tsconfig.json

5. Kiến trúc

Đường tin cậy: licensing ký chứng chỉ Ed25519 và ghi vào Redis; mọi service khác xác minh offline với public key đóng gói trong @nx/core. Không service nào gọi licensing để kiểm tra runtime. Chi tiết: xem Architecture.

6. Ảnh chụp Domain

ERD đầy đủ + bảng theo từng entity: xem Domain Model.

7. Tổng quan bề mặt

REST controllers — tham chiếu đầy đủ render trực tiếp từ /v1/api/licensing/doc/openapi.json (Scalar viewer tại /doc, portal gateway):

Controller	Base path	Ghi chú
PolicyController	/policies	CRUD (soft-delete theo status, không hard delete)
PolicyFeatureController	/policy-features	CRUD
LicenseController	/licenses	CRUD + issue / suspend / reinstate / renew / revoke / free-trial. Route read tạm bỏ qua authz ⚠️ (ADR-0003)
ActivationController	/activations	CRUD
ValidationController	/validation	validate stateless (trả về cert)

Bề mặt async — xem API Events:

Hướng	Kênh	Số lượng
Inbound	Kafka	0 (không consumer)
Outbound	Kafka	0 (không producer)
Inbound / Outbound	BullMQ	0 (không queue)
Outbound	WebSocket	0 (không component WS)

Kênh async xuyên service duy nhất là Redis: licensing SET một cert đã ký tại lic:certs:<entityType>:<entityId>; consumer GET nó qua LicenseMiddleware.

8. Components

Component	Đăng ký	Mục đích
Redis cache	useCacheRedis({ bindingKey: BindingKeys.APPLICATION_REDIS_CACHE })	Phân phối chứng chỉ + cache permission authorization

Không component Kafka, Queue (BullMQ), WebSocket, hay Mail nào được đăng ký. configureComponents() chỉ gọi super.configureComponents() + useCacheRedis(...).

9. Services

Service	File	Một dòng
LicenseManagementService	services/licensing/license-management.service.ts	Issue / renew / suspend / reinstate / revoke; free trial tự phục vụ. Mọi mutation transactional + row-lock; re-publish chứng chỉ sau commit
ActivationService	services/licensing/activation.service.ts	activate() (fast-path idempotent → tx + lock → kiểm giới hạn) và deactivate()
ValidationService	services/licensing/validation.service.ts	Pipeline validate(): status → expiry/grace → features → activation → result code
LicensingBaseService	services/licensing/licensing-base.service.ts	Base dùng chung (không bind như service): sinh key, giải feature, publishCertificate(), logEvent()

10. Repositories

Tất cả re-export từ @nx/core — package này không định nghĩa repository class nào và không thêm method tuỳ chỉnh.

Repository	Table	Source
PolicyRepository	licensing.Policy	@nx/core
PolicyFeatureRepository	licensing.PolicyFeature	@nx/core
LicenseRepository	licensing.License	@nx/core
ActivationRepository	licensing.Activation	@nx/core
LicenseEventRepository	licensing.LicenseEvent	@nx/core

Cũng bind cho seed authorization: MigrationRepository, PermissionRepository, PolicyDefinitionRepository, RoleRepository (tất cả @nx/core).

11. Entry Points

File	Mục đích
src/index.ts	Entry service → bootstrapApplication()
src/migrate.ts	Entry migration → bootstrapMigration()
src/application.ts	Application extends VerifierApplication

12. Configuration

Env vars + feature flag + dữ liệu seed: xem Configuration.

13. Operations

Triển khai + observability + bảo mật + runbook + hướng dẫn thao tác: xem Operations.

14. Trang liên quan

Khái niệm — vì sao/như thế nào:

• Architecture
• Domain Model
• Integration — đường tin cậy với LicenseMiddleware của @nx/core

Tham chiếu — tra cứu:

• API Events
• Configuration
• Operations
• REST endpoints — OpenAPI trực tiếp tại /v1/api/licensing/doc/openapi.json

Tính năng — đào sâu:

• Policies & Features
• License Lifecycle
• Validation & Activation
• Certificate System

Decisions:

• Danh mục ADR