@corelicense/node 0.5.0 → 0.5.5

package/docs/installation.md

@@ -0,0 +1,188 @@
+# Cài đặt
+
+Hướng dẫn cài package, cấu hình môi trường và chạy `boot()` lần đầu.
+
+---
+
+## 1. Cài package
+
+```bash
+npm install @corelicense/node
+```
+
+### Peer dependencies (tùy framework)
+
+Chỉ cài khi dùng integration tương ứng:
+
+```bash
+npm install express              # Express middleware
+npm install fastify              # Fastify plugin
+npm install @nestjs/common @nestjs/core   # NestJS
+```
+
+SDK không bắt buộc peer deps — tree-shake an toàn nếu chỉ dùng `CoreLicense` trực tiếp.
+
+---
+
+## 2. Biến môi trường
+
+### Bắt buộc
+
+| Biến | Mô tả |
+|------|--------|
+| `CORELICENSE_KEY` | License key do admin cấp (`CL-...` hoặc `CL1.<base64url-api>.CL-...`) |
+| `CORELICENSE_PRODUCT_ID` | Product ID trên License Server |
+
+### Tùy chọn
+
+| Biến | Mô tả | Mặc định |
+|------|--------|----------|
+| `CORELICENSE_API_URL` | Override URL License API | `https://api.corelicense.net` |
+| `CORELICENSE_PUBLIC_KEY` | Pin public key (SPKI PEM) — bỏ qua fetch keys | auto-fetch |
+
+**Thứ tự resolve API URL** (không cần set thủ công trên production):
+
+1. `options.apiUrl` / `CORELICENSE_API_URL`
+2. URL nhúng trong key `CL1.<base64url>.CL-...`
+3. Cache `sdk.endpoint.json`
+4. `https://api.corelicense.net`
+
+### Dev local
+
+```env
+CORELICENSE_KEY=CL-AAAAA-BBBBB-CCCCC-DDDDD-EEEEE
+CORELICENSE_PRODUCT_ID=demo
+CORELICENSE_API_URL=http://localhost:8080
+```
+
+### Production
+
+```env
+CORELICENSE_KEY=CL1.xxxxx.CL-AAAAA-BBBBB-...
+CORELICENSE_PRODUCT_ID=my-product
+# Không cần CORELICENSE_API_URL — SDK dùng api.corelicense.net
+```
+
+Server Go production cần `SDK_PUBLIC_URL=https://api.corelicense.net` khi generate key `CL1.*`.
+
+---
+
+## 3. Khởi tạo tối thiểu
+
+```ts
+import { CoreLicense, loadOptionsFromEnv } from '@corelicense/node';
+
+const license = new CoreLicense(
+  loadOptionsFromEnv({
+    cachePath: './storage/corelicense',
+    instance: {
+      strategy: 'install-id-domain-hash',
+      domain: process.env.APP_DOMAIN, // ví dụ: app.example.com
+    },
+    audit: {
+      enabled: true,
+      path: './storage/logs/corelicense.log',
+    },
+  }),
+);
+
+await license.boot();
+```
+
+`loadOptionsFromEnv()` throw `ConfigError` (`CONFIG_MISSING_ENV`) nếu thiếu biến bắt buộc.
+
+---
+
+## 4. `CoreLicenseOptions` (constructor)
+
+| Field | Type | Mặc định | Mô tả |
+|-------|------|----------|--------|
+| `productId` | `string` | — | **Bắt buộc** |
+| `licenseKey` | `string` | — | **Bắt buộc** |
+| `apiUrl` | `string` | auto | License Server base URL |
+| `publicKey` | `string` | — | Pin SPKI PEM |
+| `cachePath` | `string` | `./storage/corelicense` | Thư mục cache |
+| `checkIntervalMs` | `number` | `21600000` (6h) | Background refresh; `0` = tắt |
+| `requestTimeoutMs` | `number` | `5000` | HTTP timeout |
+| `offlineGrace` | `boolean` | `true` | Cho phép dùng cache khi server unreachable |
+| `defaultBlockMode` | `'block' \| 'limited'` | `'limited'` | Middleware mode mặc định |
+| `instance.strategy` | `'install-id-domain-hash' \| 'custom'` | `'install-id-domain-hash'` | Cách tính instance ID |
+| `instance.domain` | `string` | — | Domain app (cho hash) |
+| `instance.customId` | `string` | — | Khi `strategy: 'custom'` |
+| `audit.enabled` | `boolean` | `true` | Ghi audit local |
+| `audit.path` | `string` | `./storage/logs/corelicense.log` | File audit |
+| `appVersion` | `string` | — | Gửi kèm SDK info lên server |
+
+---
+
+## 5. Luồng `boot()`
+
+1. Resolve API URL (pin / cache / env / default)
+2. Tính **instance ID** (install-id + domain hash)
+3. Fetch hoặc dùng **pinned public key**
+4. Load policy token từ cache → verify
+5. Nếu cần: `activate` (lần đầu) hoặc `check` (refresh)
+6. Bật background checker (nếu `checkIntervalMs > 0`)
+7. **`requireActive()`** — fail-closed nếu license không active
+
+**Lưu ý v0.5:** Offline + grace hết hạn → `boot()` **throw**, không cho app chạy “im lặng”.
+
+---
+
+## 6. Pin public key (enterprise)
+
+```ts
+const license = new CoreLicense(
+  loadOptionsFromEnv({
+    publicKey: process.env.CORELICENSE_PUBLIC_KEY,
+  }),
+);
+```
+
+Khi pin, SDK **không** gọi `GET /v1/public/products/{id}/keys`. Sau key rotation trên server, cập nhật `CORELICENSE_PUBLIC_KEY` và restart app.
+
+---
+
+## 7. File trên disk
+
+```
+storage/corelicense/
+  instance.json       # instanceId đã resolve
+  policy.token        # JWT policy (signed)
+  usage.json          # quota usage theo ngày
+  sdk.endpoint.json   # apiUrl tin cậy từ server
+
+storage/logs/
+  corelicense.log     # audit events (JSON lines)
+```
+
+Thêm `storage/` vào `.gitignore` của app khách.
+
+---
+
+## 8. Kiểm tra sau cài
+
+```ts
+const status = await license.getStatus();
+console.log(status); // { status: 'active', ... }
+
+const policy = await license.getPolicy();
+console.log(policy?.features);
+```
+
+HTTP health route (không qua license guard):
+
+```ts
+app.get('/health', (_req, res) => res.json({ ok: true }));
+app.get('/license/status', async (_req, res) => {
+  res.json(await license.getStatus());
+});
+```
+
+---
+
+## 9. Bước tiếp theo
+
+→ [Tích hợp chi tiết](./integration.md) — Express, NestJS, module registry, DI, worker, production checklist.
+
+→ [API Reference](./api-reference.md) — danh sách method và error codes.