# @north-light/identity 中文文档

规范地址：https://npmcn.com/package/%40north-light/identity/

版本：0\.3\.573
npm 元数据更新时间：2026-11-01T23:54:16.708Z
中文译文更新时间：2026-11-02T01:22:15.385Z
软件包许可：UNLICENSED

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

原始 npm 页面：https://www.npmjs.com/package/%40north-light/identity
原文对照：https://npmcn.com/package/%40north-light/identity/?lang=original
项目主页：https://github.com/Northlight-Systems/crouter#readme
源码仓库：https://github.com/Northlight-Systems/crouter

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

- 包体积（解压后）：34.3 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-10-09T21:01:58.853Z
- 最新版本发布：2026-11-01T23:54:16.530Z
- 已发布版本数：164（近 12 个月 164 个）

## 中文简介

北极光访问令牌验证和范围规则

## 安装

```sh
npm install @north-light/identity
```

也可以使用：`pnpm add @north-light/identity`、`yarn add @north-light/identity`、`bun add @north-light/identity`

## README

# @ northlight /identity -验证目录发出的令牌并评估路由器作用域

![crouter](https://raw.githubusercontent.com/Northlight-Systems/crouter/main/assets/banner.svg)

[![npm](https://img.shields.io/npm/v/@north-light/identity?label=npm)](https://www.npmjs.com/package/@north-light/identity)

`@north-light/identity` 是由路由器运行时共享的令牌合约， [`@north-light/sdk`](https://www.npmjs.com/package/@north-light/sdk) 和 [`@north-light/plugin`](https://www.npmjs.com/package/@north-light/plugin)． 它做两件事：根据目录发布的密钥验证Northlight目录发出的签名jwt（访问令牌、ID令牌、出站提供程序令牌和授权同步通知），并解析和比较范围字符串，例如 `crtr:llm` 或者 `crtr:memory:read:user:work/`． 它仅限esm，仅依赖于 [`jose`](https://github.com/panva/jose)，进口时无副作用。

它是一个验证者，而不是一个身份提供者。它从不发布、签名或存储令牌，也不运行登录流程；目录就是这样做的。大多数应用程序不直接导入它：SDK的OAuth助手和插件工具包 `auth` 为你选择。当您编写自己的接收这些令牌的提供者或服务时，请使用它。

[文档](https://crouter.docs.northlight.ai/docs/concepts/scopes-and-trust) · [插件身份验证](https://crouter.docs.northlight.ai/docs/plugin/deploying) · [拥有众多用户的应用](https://sdk.docs.northlight.ai/docs/guides/many-users) · [克劳特库](https://github.com/Northlight-Systems/crouter)

## 安装

```bash
npm install @north-light/identity
```

## 验证令牌

每个验证者 `{ token, jwks, issuer, audience }` 并返回类型化声明或抛出。 `jwks` 是静态JWKS对象还是 `JwksCache`.

```ts
import { JwksCache, verifyCallToken } from '@north-light/identity';

const issuer = 'https://directory.example.com';
const jwks = new JwksCache(issuer, fetch, `${issuer}/.well-known/jwks.json`);

export async function authorize(request: Request) {
  const token = request.headers.get('authorization')?.replace(/^Bearer /, '') ?? '';
  const verified = await verifyCallToken({
    token,
    jwks,
    issuer,
    audience: 'https://provider.example.com/crtr', // exactly the URL the provider registered
  });
  return (verified.scope ?? '').split(' '); // the provider's `<provider>:<group>` strings the caller holds
}
```

`JwksCache` 为一个颁发者保存最后一个有效密钥集。当令牌命名为 `kid` 它没有读取，它最多每30秒重新读取一次，并发请求共享该读取。刷新失败将保留先前的键。如果省略第三个参数，它会发现 `jwks_uri` 从 `<issuer>/.well-known/openid-configuration`.

| 函数 | 检查 | 返回 |
| --- | --- | --- |
| `verifyCallToken` | `typ: at+jwt`、ES256或RS256带a `kid`签名, `iss`， `aud` (字符串等于 `audience`)， `exp`， `iat`； `sub` 是 `user:<id>`； `client_id` 非空; `scope` 出现时的字符串；这个 `act` 链(最多8节；每节 `sub` 一个 `runtime:`， `app:` 或者 `user:` 校长; `grant` 和 `rev` 只在一个 `app:` 链接, `grant` 需要一个整数 `rev` ≥1，否则 `MissingRevClaimError`）. 没有的令牌 `act` 被拒绝 | `CallToken` （`sub`， `aud`， `chain` 主持人首先, `scope`，并经核实 `claims`） |
| `verifyIdToken` | ES256,签名, `iss`， `aud`， `exp`； `sub` 是 `user:<id>` | `IdTokenClaims` （`email*` 当 `email` 被授予; `name`， `given_name`， `family_name` 当 `profile` ) |
| `verifySyncNotice` | ES256带 `kid`， `purpose: grant_sync`，寿命最长5分钟，时钟公差30秒 | `SyncNoticeClaims` （`jti`， `iat`， `exp`） |

`verifyCallToken` 是对等体、应用程序访问、出站提供商和运行通知令牌的唯一验证者；年长的 `verifyAccessToken`， `verifyMachineToken` 和 `verifyOutboundToken` 被删除，令牌保持其遗留形状(否 `act`)被拒绝。 `verifyCallToken` 不授权：调用方根据返回的链决定授权。

`aud` 必须完全匹配；斜杠差被拒绝。这个 `act` 出站令牌的声明仅用于审计：此包中没有任何内容对其进行授权。

## 解析和比较作用域

```ts
import { parseScope, covers } from '@north-light/identity';

parseScope('crtr:files:rw:user:reports');            // returns the string, typed as Scope
parseScope('crtr:files:rw:user:../etc');             // throws TypeError: Unsupported scope

covers('crtr:memory:rw:user', 'crtr:memory:read:user:work'); // true: rw covers read, no path covers any path
covers('crtr:memory:read:user', 'crtr:memory:rw:user');      // false
covers('crtr:files:rw:user:.', 'crtr:files:read:user:a/b');  // true: `.` is the whole directory
```

语法 `parseScope` 接受:

| 范围 | 意义 |
| --- | --- |
| `crtr:llm`， `crtr:act`， `crtr:schedule` | 模型调用和启动运行；作用于节点，文件和bash；调度cron |
| `crtr:memory:read:user[:path]`， `crtr:memory:rw:user[:path]`， `crtr:memory:manage:user` | 该人的文档，可选地限制为路径； `manage` 涵盖两个访问级别 |
| `crtr:memory:read_private:user` | 只读访问 `public` 和 `private` 文件;没有路径;覆盖了 `manage`只覆盖它自己 |
| `crtr:memory:read|rw:app:<id>[:profile:<profile>[:path]]` | 应用程序的文档 |
| `crtr:files:read|rw:user:<dir>`， `crtr:files:read|rw:app:<id>:<dir>`， `crtr:files:share` | 运行时可以挂载和共享的主机文件 |
| `crtr:conversations:read:app:<id>`， `crtr:objects:read:app:<id>` | 读取另一个应用程序的对话或节点对象 |
| `crtr:peer:<id>` | 同行补助金 |
| `<provider>:<group>` | 功能提供者自己的作用域，例如出站令牌中的作用域 `scope` |

道路是相对的，是拒绝的 `..`， `:`，反斜杠，空格和空段。结束于的内存路径 `/` 覆盖该目录及其下的所有内容；一个文件路径命名一个目录并覆盖它和它下面的所有内容 `.` 意思是整个根。通过 `grantee` 的第二个参数 `parseScope` 也拒绝 `app:` 受让人以外的持票人。 `ENFORCED` 是作用域的集合吗 `crtr sys connect --scopes` 接受生成令牌的时间。每个作用域允许的都在里面 [范围和信任](https://crouter.docs.northlight.ai/docs/concepts/scopes-and-trust).

## 相关

-   [`@north-light/sdk`](https://www.npmjs.com/package/@north-light/sdk)：在其OAuth助手中使用此包进行id -令牌验证和范围验证。
-   [`@north-light/plugin`](https://www.npmjs.com/package/@north-light/plugin)验证在目录中注册的提供程序的目录出站令牌。
-   [主要存储库](https://github.com/Northlight-Systems/crouter): `crtr` CLI, `crtrd` 守护进程。

## 许可证

专有的。版权所有2026 Northlight Systems版权所有。看到 `LICENSE`.

## 常见问题

### @north-light/identity 是什么？

北极光访问令牌验证和范围规则

### 如何安装 @north-light/identity？

在项目目录运行 npm install @north-light/identity，或使用 pnpm add / yarn add / bun add。

### @north-light/identity 支持 TypeScript 吗？

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

### @north-light/identity 支持 ESM 还是 CommonJS？

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

### @north-light/identity 可以商用吗？

@north-light/identity 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @north-light/identity 还在维护吗？

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