@corelicense/node 0.5.0 → 0.5.5

package/docs/integration.md

@@ -0,0 +1,789 @@
+# Tích hợp
+
+Hướng dẫn chi tiết để tích hợp `@corelicense/node` vào hệ thống production — dành cho developer và AI agent generate code.
+
+**Đọc trước:** [Cài đặt](./installation.md)
+
+---
+
+## Mục lục
+
+1. [Kiến trúc & nguyên tắc](#1-kiến-trúc--nguyên-tắc)
+2. [Vòng đời runtime](#2-vòng-đời-runtime)
+3. [Tích hợp Express (đầy đủ)](#3-tích-hợp-express-đầy-đủ)
+4. [Tích hợp Fastify](#4-tích-hợp-fastify)
+5. [Tích hợp NestJS](#5-tích-hợp-nestjs)
+6. [Feature gate, limit & quota](#6-feature-gate-limit--quota)
+7. [Worker & CLI guard](#7-worker--cli-guard)
+8. [Tích hợp sâu — Module Registry & DI](#8-tích-hợp-sâu--module-registry--di)
+9. [Pattern ứng dụng lớn](#9-pattern-ứng-dụng-lớn)
+10. [Xử lý lỗi](#10-xử-lý-lỗi)
+11. [Events & background sync](#11-events--background-sync)
+12. [Bảo mật & dữ liệu gửi server](#12-bảo-mật--dữ-liệu-gửi-server)
+13. [Production checklist](#13-production-checklist)
+14. [Troubleshooting](#14-troubleshooting)
+
+---
+
+## 1. Kiến trúc & nguyên tắc
+
+### Middleware không đủ
+
+HTTP middleware chỉ chặn request. Attacker hoặc bug có thể gọi service/worker trực tiếp. **Tích hợp sâu** nghĩa là:
+
+- Module/service **không được bind** nếu feature tắt trong policy
+- Mỗi lần `get()` / `resolve()` **re-check** license (revoke chặn ngay)
+- Worker/CLI có guard riêng
+- Quota/limit enforce tại điểm tiêu thụ
+
+### Hai lớp bảo vệ
+
+| Lớp | Cơ chế | Khi nào |
+|-----|--------|---------|
+| **HTTP** | `express()` / `fastifyPlugin()` / Nest guards | Mọi request API |
+| **Runtime** | `requireFeature`, registry, DI, worker guard | Service, job, CLI |
+
+### Policy là nguồn sự thật
+
+Policy token (JWT, EdDSA) chứa:
+
+- `status`: `active` | `suspended` | `revoked` | ...
+- `features`: map feature → boolean
+- `limits`: số tối đa (users, workers, ...)
+- `quotas` / usage local: tiêu thụ theo ngày
+
+Admin đổi policy trên server → SDK refresh → runtime cập nhật. **Bind module/service** chỉ xảy ra lúc `bootstrap()` — đổi feature cần **restart app** để mount/unmount module; nhưng `get()`/`resolve()` vẫn chặn ngay khi revoke.
+
+---
+
+## 2. Vòng đời runtime
+
+```
+constructor → boot() → [bootstrap()] → app chạy
+                ↓
+         background check (6h mặc định)
+                ↓
+         syncFromServer (mutex — không race)
+                ↓
+         requireActive() trên mọi gate quan trọng
+```
+
+### `boot()` — bắt buộc trước mọi thứ
+
+```ts
+await license.boot();
+```
+
+- Fail-closed v0.5: nếu license revoked/expired và không còn offline grace → **throw**, process nên exit
+- Gọi `boot()` **một lần** khi process start (trước `listen()`)
+
+### Instance ID
+
+```ts
+instance: {
+  strategy: 'install-id-domain-hash', // khuyến nghị production
+  domain: process.env.APP_DOMAIN,    // ví dụ: app.customer.com
+}
+```
+
+- `install-id`: UUID lưu file trong `cachePath` — ổn định qua restart
+- `domain-hash`: SHA-256 domain — phân biệt deploy theo domain
+- `custom`: `instance.customId` — container/K8s pod id tùy chỉnh
+
+Server đếm **max instances** theo license — mỗi cặp install-id + domain = một instance.
+
+---
+
+## 3. Tích hợp Express (đầy đủ)
+
+### App skeleton
+
+```ts
+import express from 'express';
+import { CoreLicense, loadOptionsFromEnv, registerLicensedRoutes } from '@corelicense/node';
+
+const app = express();
+app.use(express.json());
+
+const license = new CoreLicense(
+  loadOptionsFromEnv({
+    cachePath: './storage/corelicense',
+    instance: { strategy: 'install-id-domain-hash', domain: process.env.APP_DOMAIN },
+    checkIntervalMs: 6 * 60 * 60 * 1000,
+  }),
+);
+
+async function main() {
+  await license.boot();
+
+  // --- Routes KHÔNG cần license ---
+  app.get('/health', (_req, res) => res.json({ ok: true }));
+  app.get('/license/status', async (_req, res) => {
+    res.json(await license.getStatus());
+  });
+
+  // --- Middleware license (toàn app) ---
+  app.use(
+    license.express({
+      allowPaths: ['/health', '/license/status', '/license/reactivate'],
+      mode: 'block',
+    }),
+  );
+
+  // --- Deep integration (tùy chọn) ---
+  const { modules, services, skipped } = await license.bootstrap({
+    modules: [
+      {
+        name: 'automation',
+        feature: 'automation',
+        factory: ({ license }) => new AutomationModule(license),
+      },
+      {
+        name: 'export',
+        feature: 'export',
+        factory: ({ license }) => new ExportModule(license),
+      },
+    ],
+    services: [
+      {
+        name: 'ExportService',
+        feature: 'export',
+        singleton: true,
+        factory: ({ license }) => new ExportService(license),
+      },
+    ],
+  });
+
+  console.log('Skipped (feature off):', skipped);
+
+  // Mount router CHỈ khi module đã registered
+  registerLicensedRoutes(app, modules, [
+    { path: '/api/automation', module: 'automation', router: automationRouter },
+    { path: '/api/export', module: 'export', router: exportRouter },
+  ]);
+
+  // --- Route thường (đã qua middleware requireActive) ---
+  app.get('/api/me', async (_req, res) => {
+    await license.requireFeature('dashboard');
+    res.json({ ok: true });
+  });
+
+  app.listen(process.env.PORT ?? 3000);
+}
+
+main().catch((err) => {
+  console.error('Boot failed:', err);
+  process.exit(1);
+});
+```
+
+### `allowPaths`
+
+Exact match `req.path`. Luôn whitelist:
+
+- `/health` — load balancer
+- `/license/status` — ops dashboard
+- `/license/reactivate` — flow kích hoạt lại (nếu có)
+
+### Middleware response 403
+
+```json
+{
+  "ok": false,
+  "code": "LICENSE_REVOKED",
+  "source": "core-license.requireActive",
+  "message": "..."
+}
+```
+
+Dùng `error.toClientPayload()` — không leak stack trace.
+
+### `registerLicensedRoutes`
+
+- Chỉ `app.use(path, router)` nếu `modules.has(name)`
+- Feature off → route **không tồn tại** (404), không phải 403 — khó discover API bị khóa
+
+---
+
+## 4. Tích hợp Fastify
+
+```ts
+import Fastify from 'fastify';
+import { CoreLicense, loadOptionsFromEnv } from '@corelicense/node';
+
+const app = Fastify({ logger: true });
+
+const license = new CoreLicense(loadOptionsFromEnv({ cachePath: './storage/corelicense' }));
+
+async function main() {
+  await license.boot();
+
+  app.get('/health', async () => ({ ok: true }));
+
+  await app.register(
+    license.fastifyPlugin({
+      allowPaths: ['/health', '/license/status'],
+    }),
+  );
+
+  app.get('/api/data', async () => {
+    await license.requireFeature('api');
+    return { data: [] };
+  });
+
+  await app.listen({ port: 3000, host: '0.0.0.0' });
+}
+
+main().catch((err) => {
+  app.log.error(err);
+  process.exit(1);
+});
+```
+
+Import trực tiếp:
+
+```ts
+import { createFastifyPlugin } from '@corelicense/node/fastify';
+await app.register(createFastifyPlugin(license, { allowPaths: ['/health'] }));
+```
+
+---
+
+## 5. Tích hợp NestJS
+
+### `AppModule`
+
+```ts
+// app.module.ts
+import { Module } from '@nestjs/common';
+import { CoreLicenseModule } from '@corelicense/node/nestjs';
+import { loadOptionsFromEnv } from '@corelicense/node';
+import { AutomationModule } from './automation/automation.module.js';
+
+@Module({
+  imports: [
+    CoreLicenseModule.forRoot({
+      ...loadOptionsFromEnv({
+        cachePath: './storage/corelicense',
+        instance: { strategy: 'install-id-domain-hash', domain: process.env.APP_DOMAIN },
+      }),
+    }),
+    AutomationModule,
+  ],
+})
+export class AppModule {}
+```
+
+`CoreLicenseModule.forRoot()`:
+
+- Tạo `CoreLicense`, gọi `boot()` trong factory
+- Đăng ký `CoreLicenseGuard`, `CoreLicenseFeatureGuard`
+- Đăng ký `CoreLicenseExceptionFilter` → HTTP 403 + `toClientPayload()`
+
+### Controller — license active
+
+```ts
+import { Controller, Get, UseGuards } from '@nestjs/common';
+import { CoreLicense } from '@corelicense/node';
+import { CoreLicenseGuard } from '@corelicense/node/nestjs';
+
+@UseGuards(CoreLicenseGuard)
+@Controller('api')
+export class ApiController {
+  constructor(private readonly license: CoreLicense) {}
+
+  @Get('status')
+  async status() {
+    return this.license.getStatus();
+  }
+}
+```
+
+### Controller — feature cụ thể
+
+```ts
+import {
+  Controller,
+  Get,
+  UseGuards,
+} from '@nestjs/common';
+import {
+  CoreLicenseGuard,
+  CoreLicenseFeatureGuard,
+  RequireFeature,
+} from '@corelicense/node/nestjs';
+
+@RequireFeature('automation')
+@UseGuards(CoreLicenseGuard, CoreLicenseFeatureGuard)
+@Controller('automation')
+export class AutomationController {
+  @Get()
+  list() {
+    return { items: [] };
+  }
+}
+```
+
+### Health controller (không guard)
+
+```ts
+@Controller('health')
+export class HealthController {
+  @Get()
+  health() {
+    return { ok: true };
+  }
+}
+```
+
+Đặt `HealthController` **không** dùng `CoreLicenseGuard` — hoặc dùng global guard với `@SetMetadata` skip (tùy app).
+
+### Inject `CoreLicense` vào service
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { CoreLicense, LicensedService } from '@corelicense/node';
+
+@Injectable()
+export class ExportService extends LicensedService {
+  constructor(license: CoreLicense) {
+    super(license);
+  }
+
+  async exportUsers() {
+    await this.require('export.users');
+    await this.license.consumeQuota('export.users', 1);
+    // business logic...
+  }
+}
+```
+
+---
+
+## 6. Feature gate, limit & quota
+
+### Feature
+
+```ts
+await license.requireFeature('automation');
+await license.requireFeature('export.pdf');
+await license.requireFeature('worker.video');
+```
+
+Policy `features` ví dụ:
+
+```json
+{
+  "automation": true,
+  "export": true,
+  "export.pdf": false,
+  "worker.video": true
+}
+```
+
+`requireFeature` → audit log `feature_allowed`. Throw `FeatureDisabledError` (`FEATURE_DISABLED`).
+
+### Limit (số hiện tại vs trần policy)
+
+```ts
+const running = await jobQueue.countActive();
+await license.checkLimit('maxConcurrentJobs', running);
+
+const userCount = await db.users.count();
+await license.checkLimit('maxUsers', userCount);
+```
+
+Throw khi `currentValue >= limit` trong policy.
+
+### Quota (tiêu thụ tích lũy theo ngày, local cache)
+
+```ts
+await license.consumeQuota('export.daily', 1);
+await license.consumeQuota('api.calls', 10);
+```
+
+- Usage lưu `usage.json` trong `cachePath`
+- Reset theo ngày (UTC date string)
+- `consumeQuota` / `checkLimit` / `getPolicy` đều gọi `requireActive()` trước
+
+### Runtime config
+
+```ts
+const runtime = await license.getRuntimeConfig();
+// {
+//   status: 'active',
+//   modules: { dashboard: true, automation: false, ... },
+//   limits: { maxWorkers: 2, maxUsers: 100 },
+//   policyVersion: 'v3',
+//   workers: { ... }  // nếu policy định nghĩa
+// }
+```
+
+Dùng để **điều kiện hóa UI** hoặc config worker count — không thay thế `requireFeature` cho security.
+
+---
+
+## 7. Worker & CLI guard
+
+### BullMQ / queue worker
+
+```ts
+import { Worker } from 'bullmq';
+
+await license.boot();
+await license.guardWorker('main-worker');
+
+const worker = new Worker('jobs', async (job) => {
+  await license.requireFeature(`job.${job.name}`);
+  await license.consumeQuota(`job.${job.name}`, 1);
+  return processJob(job);
+});
+```
+
+`guardWorker(name)` kiểm tra policy cho phép worker name — throw `WORKER_NOT_ALLOWED`.
+
+### Cron / CLI
+
+```ts
+async function main() {
+  await license.boot();
+  await license.guardCommand('nightly-export');
+  await runExport();
+}
+
+main().catch(console.error);
+```
+
+Throw `COMMAND_NOT_ALLOWED` nếu feature/command không licensed.
+
+---
+
+## 8. Tích hợp sâu — Module Registry & DI
+
+### Khi nào dùng
+
+- App có nhiều module lớn (automation, export, AI, ...)
+- Muốn **không load code** module bị khóa license
+- Muốn mount route / register provider có điều kiện
+
+### `bootstrap()` — một lần sau `boot()`
+
+```ts
+const result = await license.bootstrap({
+  modules: ModuleDefinition[],
+  services: ServiceDefinition[],
+});
+
+// result.modules  → LicensedModuleRegistry
+// result.services → LicensedServiceContainer
+// result.skipped  → [{ name, feature, reason: 'feature_disabled' }]
+```
+
+### `ModuleDefinition`
+
+```ts
+{
+  name: 'automation',           // unique id
+  feature: 'automation',        // key trong policy.features
+  factory: ({ license, runtime }) => new AutomationModule(license),
+}
+```
+
+### `ServiceDefinition`
+
+```ts
+{
+  name: 'ExportService',
+  feature: 'export',
+  singleton: true,              // default true — factory chạy 1 lần
+  factory: ({ license }) => new ExportService(license),
+}
+```
+
+### `modules.get(name)`
+
+```ts
+const automation = await modules.get<AutomationModule>('automation');
+await automation.runJob(payload);
+```
+
+- Module chưa registered → `ModuleNotRegisteredError`
+- Feature off lúc bootstrap → không registered → `ModuleNotLicensedError`
+- **Mỗi `get()`** gọi `requireFeature` — revoke suspend chặn ngay
+
+### `services.resolve(name)`
+
+```ts
+const svc = await services.resolve<ExportService>('ExportService');
+await svc.exportUsers();
+```
+
+- Singleton: instance cache nội bộ, nhưng **mỗi `resolve()` re-check license**
+- Re-check **không** ghi audit (khác `license.requireFeature()`)
+
+### Tự tạo registry (advanced)
+
+```ts
+const modules = license.createLicensedRegistry();
+const services = license.createLicensedContainer();
+
+const ctx = {
+  license,
+  runtime: await license.getRuntimeConfig(),
+};
+
+await modules.bootstrap(definitions, ctx);
+```
+
+### `LicensedService` base class
+
+```ts
+import { LicensedService, CoreLicense } from '@corelicense/node';
+
+export class ExportService extends LicensedService {
+  constructor(license: CoreLicense) {
+    super(license);
+  }
+
+  async exportUsers() {
+    await this.require('export.users');
+    await this.license.consumeQuota('export.users', 1);
+    // ...
+  }
+}
+```
+
+---
+
+## 9. Pattern ứng dụng lớn
+
+### Cấu trúc thư mục gợi ý
+
+```
+src/
+  bootstrap/
+    license.ts          # khởi tạo CoreLicense + boot()
+    modules.ts          # định nghĩa bootstrap modules/services
+  modules/
+    automation/
+      automation.module.ts
+      automation.router.ts
+    export/
+      export.service.ts
+  app.ts                # express + registerLicensedRoutes
+```
+
+### `bootstrap/license.ts`
+
+```ts
+import { CoreLicense, loadOptionsFromEnv } from '@corelicense/node';
+
+let license: CoreLicense;
+
+export async function initLicense() {
+  license = new CoreLicense(loadOptionsFromEnv({ cachePath: './storage/corelicense' }));
+  await license.boot();
+  return license;
+}
+
+export function getLicense() {
+  if (!license) throw new Error('License not initialized');
+  return license;
+}
+```
+
+### `bootstrap/modules.ts`
+
+```ts
+import type { BootstrapResult } from '@corelicense/node';
+import { getLicense } from './license.js';
+import { AutomationModule } from '../modules/automation/automation.module.js';
+import { ExportService } from '../modules/export/export.service.js';
+
+export async function bootstrapApp(): Promise<BootstrapResult> {
+  return getLicense().bootstrap({
+    modules: [
+      { name: 'automation', feature: 'automation', factory: ({ license }) => new AutomationModule(license) },
+    ],
+    services: [
+      { name: 'ExportService', feature: 'export', factory: ({ license }) => new ExportService(license) },
+    ],
+  });
+}
+```
+
+### Graceful shutdown
+
+```ts
+process.on('SIGTERM', () => {
+  license.stopBackgroundCheck();
+  process.exit(0);
+});
+```
+
+### Docker
+
+```dockerfile
+ENV CORELICENSE_KEY=...
+ENV CORELICENSE_PRODUCT_ID=...
+ENV APP_DOMAIN=app.customer.com
+VOLUME ["/app/storage/corelicense"]
+```
+
+Persist `cachePath` — mất volume = mất install-id → tính instance mới.
+
+### Multi-tenant
+
+- **Một license / một deploy** (khuyến nghị): mỗi customer một deployment + key riêng
+- Không share một `CoreLicense` instance cho nhiều tenant — instance ID và policy gắn một license
+
+---
+
+## 10. Xử lý lỗi
+
+### Type guard
+
+```ts
+import {
+  isLicenseError,
+  formatLicenseError,
+  LicenseErrorCode,
+} from '@corelicense/node';
+
+try {
+  await license.boot();
+} catch (error) {
+  if (isLicenseError(error)) {
+    console.error(error.code, error.source, error.message);
+    // CONFIG_MISSING_ENV, LICENSE_REVOKED, OFFLINE_GRACE_EXPIRED, ...
+  }
+  throw error;
+}
+```
+
+### HTTP API
+
+```ts
+if (isLicenseError(error)) {
+  res.status(403).json(error.toClientPayload());
+}
+```
+
+### Mã lỗi thường gặp
+
+| Code | Ý nghĩa |
+|------|---------|
+| `CONFIG_MISSING_ENV` | Thiếu `CORELICENSE_KEY` / `CORELICENSE_PRODUCT_ID` |
+| `LICENSE_REVOKED` | Key bị revoke |
+| `LICENSE_SUSPENDED` | Tạm ngưng |
+| `LICENSE_EXPIRED` | Hết hạn |
+| `OFFLINE_GRACE_EXPIRED` | Server unreachable quá lâu |
+| `FEATURE_DISABLED` | Feature không trong policy |
+| `MODULE_NOT_LICENSED` | Module không bind / feature off |
+| `QUOTA_EXCEEDED` | Vượt quota ngày |
+| `MAX_INSTANCES` | Vượt số instance |
+| `INSTANCE_BLOCKED` | Instance bị block trên admin |
+| `POLICY_SIGNATURE_ERROR` | Token không verify được |
+
+Xem đầy đủ: [API Reference — Error codes](./api-reference.md#error-codes)
+
+---
+
+## 11. Events & background sync
+
+### Event bus
+
+```ts
+license.on('licenseRevoked', (payload) => {
+  console.error('License revoked', payload);
+  process.exit(1);
+});
+
+license.on('policyUpdated', (payload) => {
+  console.log('Policy updated', payload);
+});
+
+license.on('offlineMode', (payload) => {
+  console.warn('Offline mode', payload);
+});
+```
+
+Events: `statusChanged`, `policyUpdated`, `licenseRevoked`, `licenseSuspended`, `offlineMode`
+
+### Background check
+
+`boot()` tự start nếu `checkIntervalMs > 0`. Thủ công:
+
+```ts
+license.startBackgroundCheck();
+license.stopBackgroundCheck();
+```
+
+`syncFromServer` có **mutex** — parallel refresh không race.
+
+### Manual refresh
+
+```ts
+await license.refresh();
+```
+
+Endpoint `refresh` trên License Server.
+
+---
+
+## 12. Bảo mật & dữ liệu gửi server
+
+SDK **chỉ gửi**:
+
+- `productId`, `licenseKey`, `instanceId`
+- SDK metadata (name, version, runtime)
+- `domainHash` (hash, không plain domain nếu cấu hình đúng)
+- `currentPolicyHash` (khi check)
+
+**Không gửi:** database, user data, business logs.
+
+### apiUrl pin (v0.5)
+
+Server có thể trả `apiUrl` trong response. SDK **chỉ chấp nhận** URL trong whitelist (trusted apiUrl, env, embedded key). Redirect độc hại bị reject + audit `api_url_redirect_rejected`.
+
+### Public key
+
+- Mặc định: fetch `GET /v1/public/products/{productId}/keys`
+- Enterprise: pin `CORELICENSE_PUBLIC_KEY`
+
+---
+
+## 13. Production checklist
+
+- [ ] `CORELICENSE_KEY` + `CORELICENSE_PRODUCT_ID` trong env (secret manager)
+- [ ] `APP_DOMAIN` / `instance.domain` set đúng
+- [ ] `cachePath` persist (volume)
+- [ ] `boot()` fail → `process.exit(1)` — không start app “half-licensed”
+- [ ] `/health` trong `allowPaths`
+- [ ] License Server: `SDK_PUBLIC_URL=https://api.corelicense.net`
+- [ ] Policy signer configured trên Go API
+- [ ] Log audit path có rotate
+- [ ] Test revoke: admin revoke → app chặn trong vòng refresh / ngay tại `requireFeature`
+
+---
+
+## 14. Troubleshooting
+
+| Triệu chứng | Nguyên nhân | Xử lý |
+|-------------|-------------|--------|
+| `CONFIG_MISSING_ENV` | Thiếu env | Set `CORELICENSE_*` |
+| `boot()` fail offline | Grace hết | Kết nối server hoặc tạm `offlineGrace: false` chỉ khi hiểu rủi ro |
+| `MAX_INSTANCES` | Quá số instance | Xóa instance cũ trên admin hoặc tăng limit |
+| `POLICY_SIGNATURE_ERROR` | Key rotation / sai pin | Cập nhật public key hoặc bỏ pin |
+| Middleware 403 mọi route | Thiếu `allowPaths` | Thêm `/health`, ... |
+| Module 404 | Feature off | Đúng thiết kế — `registerLicensedRoutes` skip |
+| Nest 403 không JSON chuẩn | Thiếu filter | Dùng `CoreLicenseModule.forRoot()` (đã có filter) |
+
+---
+
+## Liên kết
+
+- [Cài đặt](./installation.md)
+- [API Reference](./api-reference.md)
+- [Client API (License Server)](https://corelicense.net/docs/client-api)
+- [README](../README.md)