@corelicense/node 0.2.0 → 0.5.1

package/dist/types/policy.d.ts

@@ -15,6 +15,7 @@ export interface PolicyTokenPayload {
     licenseId: string;
     productId: string;
     customerId?: string;
+    applicationId?: string;
     instanceId: string;
     status: LicenseStatusValue;
     features: PolicyFeatures;
@@ -28,6 +29,7 @@ export interface Policy {
     licenseId: string;
     productId: string;
     customerId?: string;
+    applicationId?: string;
     instanceId: string;
     status: LicenseStatusValue;
     features: PolicyFeatures;

package/dist/types/policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/types/policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,MAAM,WAAW,cAAc;IAC7B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACrC;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,QAAQ,EAAE,cAAc,CAAC;IACzB,MAAM,EAAE,YAAY,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,MAAM;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,QAAQ,EAAE,cAAc,CAAC;IACzB,MAAM,EAAE,YAAY,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/types/policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,MAAM,WAAW,cAAc;IAC7B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACrC;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,QAAQ,EAAE,cAAc,CAAC;IACzB,MAAM,EAAE,YAAY,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,MAAM;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,QAAQ,EAAE,cAAc,CAAC;IACzB,MAAM,EAAE,YAAY,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/docs/api-reference.md

@@ -0,0 +1,210 @@
+# API Reference
+
+Public API `@corelicense/node` v0.5.1.
+
+---
+
+## CoreLicense
+
+### Constructor
+
+```ts
+new CoreLicense(options: CoreLicenseOptions)
+```
+
+### Lifecycle
+
+| Method | Returns | Mô tả |
+|--------|---------|--------|
+| `boot()` | `Promise<void>` | Khởi tạo, sync server, fail-closed |
+| `refresh()` | `Promise<LicenseStatus>` | Force refresh policy |
+| `startBackgroundCheck()` | `void` | Bật interval sync |
+| `stopBackgroundCheck()` | `void` | Tắt interval |
+
+### License gates
+
+| Method | Mô tả |
+|--------|--------|
+| `requireActive()` | Throw nếu không active |
+| `requireFeature(feature)` | Throw + audit nếu feature off |
+| `checkLimit(name, current)` | Throw nếu vượt limit |
+| `consumeQuota(name, amount?)` | Tiêu thụ quota local |
+| `getStatus()` | Trạng thái hiện tại |
+| `getPolicy()` | Policy đã verify (null nếu chưa có) |
+| `getRuntimeConfig()` | Config derived từ policy |
+
+### HTTP integrations
+
+| Method | Mô tả |
+|--------|--------|
+| `express(options?)` | Express `RequestHandler` |
+| `fastifyPlugin(options?)` | Fastify plugin |
+
+### Worker / CLI
+
+| Method | Mô tả |
+|--------|--------|
+| `guardWorker(name)` | Guard worker process |
+| `guardCommand(name)` | Guard CLI/cron command |
+
+### Deep integration
+
+| Method | Mô tả |
+|--------|--------|
+| `bootstrap(options)` | Register modules + services |
+| `createLicensedRegistry()` | `LicensedModuleRegistry` riêng |
+| `createLicensedContainer()` | `LicensedServiceContainer` riêng |
+
+### Events
+
+```ts
+license.on(event, handler)
+license.off(event, handler)
+```
+
+Events: `statusChanged` | `policyUpdated` | `licenseRevoked` | `licenseSuspended` | `offlineMode`
+
+---
+
+## LicensedModuleRegistry
+
+| Method | Mô tả |
+|--------|--------|
+| `bootstrap(definitions, ctx)` | Register hàng loạt |
+| `registerLicensed(def, ctx)` | Register một module |
+| `has(name)` | Module đã bind? |
+| `get<T>(name)` | Lấy module + re-check license |
+| `list()` | Tên modules đã register |
+
+---
+
+## LicensedServiceContainer
+
+| Method | Mô tả |
+|--------|--------|
+| `bootstrap(definitions, ctx)` | Bind services |
+| `resolve<T>(name)` | Resolve + re-check license |
+| `has(name)` | Service đã bind? |
+
+---
+
+## Helpers
+
+```ts
+loadOptionsFromEnv(overrides?: Partial<CoreLicenseOptions>): CoreLicenseOptions
+resolveApiUrl(options, cachedApiUrl?): string
+parseEmbeddedApiUrl(licenseKey): string | null
+registerLicensedRoutes(app, registry, routes): string[]
+isLicenseError(error): boolean
+formatLicenseError(error): string
+isFeatureEnabled(policy, feature): boolean
+```
+
+---
+
+## Subpath exports
+
+### `@corelicense/node/express`
+
+```ts
+createExpressMiddleware(license, options?): RequestHandler
+```
+
+### `@corelicense/node/fastify`
+
+```ts
+createFastifyPlugin(license, options?): FastifyPluginAsync
+coreLicenseFastifyPlugin
+```
+
+### `@corelicense/node/nestjs`
+
+```ts
+CoreLicenseModule.forRoot(options): DynamicModule
+CoreLicenseGuard
+CoreLicenseFeatureGuard
+CoreLicenseExceptionFilter
+RequireFeature(feature)  // decorator
+REQUIRE_FEATURE_KEY
+```
+
+---
+
+## Types
+
+### `CoreLicenseOptions`
+
+Xem [installation.md](./installation.md#4-corelicenseoptions-constructor).
+
+### `ExpressGuardOptions` / `FastifyGuardOptions`
+
+```ts
+{
+  allowPaths?: string[];
+  mode?: 'block' | 'limited';
+}
+```
+
+### `BootstrapResult`
+
+```ts
+{
+  modules: LicensedModuleRegistry;
+  services: LicensedServiceContainer;
+  registeredModules: string[];
+  registeredServices: string[];
+  skipped: { name: string; feature: string; reason: 'feature_disabled' }[];
+}
+```
+
+### `LicenseStatus`
+
+```ts
+{
+  status: 'active' | 'suspended' | 'revoked' | 'expired' | 'invalid' | 'blocked';
+  policyVersion?: string;
+  expiresAt?: string;
+  // ...
+}
+```
+
+---
+
+## Error codes
+
+Mọi `LicenseError` có `code`, `source`, `message`, `toClientPayload()`, `toJSON()`.
+
+| Code | HTTP (middleware) |
+|------|-------------------|
+| `LICENSE_REVOKED` | 403 |
+| `LICENSE_SUSPENDED` | 403 |
+| `LICENSE_EXPIRED` | 403 |
+| `LICENSE_INVALID` | 403 |
+| `OFFLINE_GRACE_EXPIRED` | 403 |
+| `FEATURE_DISABLED` | 403 |
+| `MODULE_NOT_LICENSED` | 403 |
+| `QUOTA_EXCEEDED` | 403 |
+| `MAX_INSTANCES` | 403 |
+| `INSTANCE_BLOCKED` | 403 |
+| `CONFIG_MISSING_ENV` | — (boot fail) |
+| `POLICY_SIGNATURE_ERROR` | — (boot fail) |
+| `BOOT_NOT_CALLED` | — |
+| `WORKER_NOT_ALLOWED` | — |
+| `COMMAND_NOT_ALLOWED` | — |
+
+Danh sách đầy đủ trong source: `src/errors/codes.ts`
+
+---
+
+## Client API (License Server)
+
+SDK gọi các endpoint (không gọi trực tiếp từ app thường):
+
+| Endpoint | Mô tả |
+|----------|--------|
+| `POST /v1/client/activate` | Lần đầu |
+| `POST /v1/client/check` | Periodic check |
+| `POST /v1/client/refresh` | Force refresh |
+| `GET /v1/public/products/{id}/keys` | Public keys |
+
+Chi tiết: [corelicense.net/docs/client-api](https://corelicense.net/docs/client-api)

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.