# @eventcatalog/license 中文文档

规范地址：https://npmcn.com/package/%40eventcatalog/license/

版本：0\.0\.9
npm 元数据更新时间：2026-09-30T14:51:17.049Z
中文译文更新时间：2026-11-14T01:05:39.493Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40eventcatalog/license
原文对照：https://npmcn.com/package/%40eventcatalog/license/?lang=original
项目主页：https://github.com/eventcatalog/license#readme
源码仓库：https://github.com/eventcatalog/license

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：48.6 kB，22 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=16\.0\.0
- 运行依赖：4 个
- 首次发布：2025-09-03T16:02:08.551Z
- 最新版本发布：2026-09-30T14:51:16.687Z
- 近 30 天下载量：92473（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 2 个）

## 中文简介

事件Catalog 的许可证验证

## 安装

```sh
npm install @eventcatalog/license
```

也可以使用：`pnpm add @eventcatalog/license`、`yarn add @eventcatalog/license`、`bun add @eventcatalog/license`

## README

# @ eventcatalog/ 许可证

EventCatalog 许可证核查库,支持离线JWT核查和在线许可证密钥验证.

## 特征

-   **双重核查模式** - 离线JWT标志和在线许可证钥匙
-   **Ed25519 签名** - 利用工业标准椭圆曲线加密进行离线核查
-   **基于JWT的离线许可证** - 有自定义事件Catalog债权的标准代号格式
-   **在线许可证密钥验证** - 与 EventCatalog API 实时核实
-   **输入验证** - 安全许可钥匙格式验证
-   **缓存** - 为业绩而缓存的核查结果
-   **机器装订** - 基于指纹的可选许可证绑定(离线模式)
-   **强化错误处理** - 不同故障情况的结构错误代码
-   **类型脚本** - 全面安全和情报支持

## 安装

```bash
npm install @eventcatalog/license
```

## 快速启动

### 离线 JWT 核查

```typescript
import { verifyOfflineLicense, isFeatureEnabled } from '@eventcatalog/license';

// Verify offline JWT license (auto-locates license file)
try {
  const entitlements = await verifyOfflineLicense();
  console.log('License valid for:', entitlements.org);
} catch (error) {
  console.error('License verification failed:', error.message);
}

// Check if a plugin is enabled
if (isFeatureEnabled('@eventcatalog/generator-asyncapi')) {
  console.log('AsyncAPI generator is licensed');
}
```

### 在线许可证密钥验证

```typescript
import { verifyOnlineLicense } from '@eventcatalog/license';

// Verify online license key
try {
  const isValid = await verifyOnlineLicense('XXXX-XXXX-XXXX-XXXX-XXXX-XXXX', '@eventcatalog/eventcatalog-scale');
  if (isValid) {
    console.log('License key is valid');
  }
} catch (error) {
  console.error('License key verification failed:', error.message);
}
```

### 事件Catalog 企业

Event Catalog 企业许可证仅限离线。 添加 `@eventcatalog/eventcatalog-enterprise` 向JWT许可证申请 `plugins` 索赔, 然后使用计划助手 :

```typescript
import { isEventCatalogEnterpriseEnabled } from '@eventcatalog/license';

if (await isEventCatalogEnterpriseEnabled()) {
  console.log('EventCatalog Enterprise is licensed');
}
```

帮助者使用标准 [离线许可证的发现](https://npmcn.com/package/%40eventcatalog/license/#readme-license-discovery) 流动和返回 `false` 当没有离线许可证时。 它不使用一个 在线许可密钥.

## API 参考

### `verifyOfflineLicense(opts?: VerifyOptions): Promise<Entitlements>`

认证离线的JWT许可证和返回应享权利。 第一次成功核实后,结果会被缓存.

**选项 :**

-   `licensePath?: string` - 自定义许可文件路径(自动发现)
-   `audience?: string` - 预期JWT观众(默认:"EventCatalog")
-   `issuer?: string` - 预期JWT发行人(默认:"EventCatalog Ltd")
-   `clockTolerance?: string` - 时钟skew容忍度(默认:"12h")
-   `currentVersion?: string` - 用于范围验证的事件Catalog 版本
-   `fingerprintProvider?: () => string | null` - 机器指纹提供者

**有选项的示例:**

```typescript
const entitlements = await verifyOfflineLicense({
  licensePath: '/custom/path/license.jwt',
  audience: 'MyEventCatalog',
  clockTolerance: '24h',
  fingerprintProvider: () => getMachineId(),
});
```

### `verifyOnlineLicense(key: string, plugin: string): Promise<boolean>`

使用 EventCatalog API 在线验证许可证密钥 。 事件目录 企业不为此函数所支持,因为它是离线的 计划.

**参数:**

-   `key: string` - 格式的许可密钥 `XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`
-   `plugin: string` - 用于对照的插件标识符

**支持的插件 :**

-   `@eventcatalog/eventcatalog-starter`
-   `@eventcatalog/eventcatalog-scale`

**示例**

```typescript
const isValid = await verifyOnlineLicense('XXXX-XXXX-XXXX-XXXX-XXXX-XXXX', '@eventcatalog/eventcatalog-scale');
```

### `isEventCatalogEnterpriseEnabled(): Promise<boolean>`

核实在JWT线外发现的并检查 `@eventcatalog/eventcatalog-enterprise` 权利。 回返 `false` 无 在无离线许可时进行网络请求.

```typescript
const isEnterpriseEnabled = await isEventCatalogEnterpriseEnabled();
```

### `hasCommercialLicense(): Promise<boolean>`

验证发现的离线JWT(签名、发行人、受众、, `nbf`编号 :`exp`(中文(简体) ) 返回时 `true` 只有当它有一个 `exp` 未通过的索赔。 与 `verifyOfflineLicense`中,过期检查没有应用时钟容忍度。 回返 `false` 而不是在找不到许可证文件或核查失败时投掷.

```typescript
if (await hasCommercialLicense()) {
  console.log('Commercial license is active');
}
```

### `isFeatureEnabled(name: string): boolean`

检查当前许可证中是否启用了插件或特性 .

```typescript
// Check string plugin names
if (isFeatureEnabled('@eventcatalog/generator-openapi')) {
  // Enable OpenAPI generator
}

// Also works with object-style plugin specs in license
```

### `getEntitlements(): Entitlements | null`

返回目前缓存的应享权利而无需重新核查.

```typescript
const entitlements = getEntitlements();
if (entitlements?.org) {
  console.log(`License for: ${entitlements.org}`);
}
```

## 许可证发现

许可证文件在此顺序中 :

1.  `EC_LICENSE` 环境变量( 文件路径)
2.  `./license.jwt` (当前目录)
3.  `/etc/eventcatalog/license.jwt` (全系统)

## 环境变量

### `EC_LICENSE`

许可文件路径( 覆盖自动发现) .

```bash
export EC_LICENSE="/path/to/my/license.jwt"
```

### `EC_PUBLIC_KEY_PATH`

自定义公钥 PEM 文件的路径( 覆盖捆绑的密钥) .

```bash
export EC_PUBLIC_KEY_PATH="/path/to/custom/public.pem"
```

## 许可证格式

许可证是JWT标牌,标牌和事件Catalog具体索赔:

**标准索赔:**

-   `iss` - 发行人("EventCatalog Ltd")
-   `aud` - 观众("EventCatalog")
-   `iat` - 发布时标
-   `nbf` - 不是在时间戳之前
-   `exp` - 过期时间戳

**事件Catalog索赔:**

-   `licenseId` - 独特的许可证标识符
-   `org` - 组织名称
-   `plugins` - 已启用插件阵列
-   `fingerprint` - 机器绑定指纹(可选)

**示例有效载荷:**

```json
{
  "iss": "EventCatalog Ltd",
  "aud": "EventCatalog",
  "iat": 1672531200,
  "nbf": 1672531200,
  "exp": 1735689600,
  "licenseId": "ec_2025_000001",
  "org": "Acme Corp",
  "plugins": [
    "@eventcatalog/generator-asyncapi",
    {
      "name": "@eventcatalog/generator-openapi",
      "versionRange": "^1.0.0"
    }
  ]
}
```

### 离线许可证出错

| 错误代码 | 消息 | 说明 |
| --- | --- | --- |
| `LICENSE_EXPIRED` | 驾照过期了 | JWT 过期时间 |
| `LICENSE_NOT_YET_VALID` | 许可证尚未有效 | 尚未激活的 JWT 令牌 |
| `LICENSE_VALIDATION_FAILED` | 许可证验证失败 - 无效的发行者或受众 | 2\. JWT索赔审定失败 |
| `LICENSE_SIGNATURE_INVALID` | 许可证签名验证失败 - 无效或被篡改的许可证 | 数字签名验证失败 |
| `LICENSE_FILE_NOT_FOUND` | 未找到许可证文件 | 在发现地点没有发现许可证文件 |
| `LICENSE_FILE_EMPTY` | 许可证文件为空 | 许可证文件已存在,但没有内容 |
| `LICENSE_FINGERPRINT_MISMATCH` | 许可证指纹不匹配 - 许可证绑在不同的机器上 | 机器装订违规 |

### 在线许可证错误

| 错误代码 | 消息 | 说明 |
| --- | --- | --- |
| `INVALID_LICENSE_KEY_FORMAT` | 无效的许可密钥格式 。 预期格式: | 许可证密钥不符合要求的格式 |

## 大楼

```bash
# Install dependencies
npm install

# Build TypeScript
npm run build

# The compiled package will be in ./dist/
```

## 发展

软件包结构 :

```
eventcatalog-license/
├── src/
│   ├── index.ts      # Public API exports
│   ├── types.ts      # TypeScript type definitions
│   ├── key.ts        # Public key loading & validation
│   └── verify.ts     # Verification logic (offline & online)
├── assets/
│   └── ec-ed25519-public.pem  # Public key for offline verification
└── dist/             # Compiled output
```

### 测试许可证核查

#### 离线 JWT 测试

1.  创建测试许可证文件 :
    
    ```bash
    echo "your.jwt.token.here" > license.jwt
    ```
    
2.  程序测试:
    
    ```typescript
    import { verifyOfflineLicense } from '@eventcatalog/license';
    
    try {
      const entitlements = await verifyOfflineLicense();
      console.log('✓ Valid license:', entitlements);
    } catch (error) {
      console.error('✗ Invalid license:', error.message);
    }
    ```
    

#### 在线许可证密钥测试

```typescript
import { verifyOnlineLicense } from '@eventcatalog/license';

try {
  const isValid = await verifyOnlineLicense('XXXX-XXXX-XXXX-XXXX-XXXX-XXXX', '@eventcatalog/eventcatalog-scale');
  console.log('✓ License key valid:', isValid);
} catch (error) {
  console.error('✗ License key invalid:', error.message);
}
```

## 许可证

麻省理工学院

## 常见问题

### @eventcatalog/license 是什么？

事件Catalog 的许可证验证

### 如何安装 @eventcatalog/license？

在项目目录运行 npm install @eventcatalog/license，或使用 pnpm add / yarn add / bun add。

### @eventcatalog/license 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @eventcatalog/license 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @eventcatalog/license 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=16\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @eventcatalog/license 可以商用吗？

@eventcatalog/license 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @eventcatalog/license 的下载量有多少？

根据 npm 官方下载统计，@eventcatalog/license 在 2026/10/14 – 2026/11/12 这 30 天内被下载 92,473 次，日均约 3,082 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @eventcatalog/license 还在维护吗？

最新版本 0\.0\.9 发布于 2026/09/30（1 个月前）；至今共发布 9 个版本，其中过去 12 个月发布了 2 个；首次发布于 2025/09/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。