# @faiber/faiber-idp 中文文档

规范地址：https://npmcn.com/package/%40faiber/faiber-idp/

版本：2\.8\.0
npm 元数据更新时间：2026-11-14T09:45:04.684Z
中文译文更新时间：2026-11-14T09:11:09.290Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40faiber/faiber-idp
原文对照：https://npmcn.com/package/%40faiber/faiber-idp/?lang=original

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

- 包体积（解压后）：499 kB，44 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-07-18T14:29:09.445Z
- 最新版本发布：2026-11-14T09:45:04.487Z
- 近 30 天下载量：3830（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：66（近 12 个月 66 个）

## 中文简介

认证、会话、用户、角色、权限、OAuth身份和身份设置.

## 安装

```sh
npm install @faiber/faiber-idp
```

也可以使用：`pnpm add @faiber/faiber-idp`、`yarn add @faiber/faiber-idp`、`bun add @faiber/faiber-idp`

## README

# @faiber/faiber-idp

认证、会话、用户、角色、权限、OAuth身份和身份设置.

## 安装

```bash
npm install @faiber/faiber-idp
```

## 配置

```ts
import { FaiberClient, MemoryTokenProvider } from "@faiber/sdk-core";
import { IdpApi } from "@faiber/faiber-idp";

const tokens = new MemoryTokenProvider();
const client = new FaiberClient("idp", {
  domains: { idp: process.env.FAIBER_IDP_URL! },
  tokenProvider: tokens,
  axios: { timeout: 15_000, withCredentials: true },
});
const api = new IdpApi(client);

const login = await api.login({
  grant_type: "password",
  username: "admin@example.com",
  password: "secret",
  client_id: "2",
  client_secret: "client-secret",
  device_id: "my-stable-device-id",
});
await tokens.setTokens({
  accessToken: login.data.data.access_token,
  refreshToken: login.data.data.refresh_token,
});
```

## 完全能力

这个包从身份和访问服务中暴露出114个挂载操作. 通用工作流程有简洁的方法 `api`;每个已注册后端路由在 `api.operations`。生成的操作输入、查询、响应、路径、动词和许可合同从 `operations.types`。 。 。 .

| 区域 | 业务 | HTTP 方法 |
| --- | --: | --- |
| `acl` | 10个 | `DELETE`, (中文(简体) ), `GET`, (中文(简体) ), `PATCH`, (中文(简体) ), `POST`, (中文(简体) ), `PUT` |
| `auth` | 27个 | `DELETE`, (中文(简体) ), `GET`, (中文(简体) ), `OPTIONS`, (中文(简体) ), `POST` |
| `custom-oauth` | 第8条 | `DELETE`, (中文(简体) ), `GET`, (中文(简体) ), `POST`, (中文(简体) ), `PUT` |
| `effective-permissions` | 1个 | `GET` |
| `identity-authority` | 10个 | `GET`, (中文(简体) ), `POST`, (中文(简体) ), `PUT` |
| `integration` | 1个 | `GET` |
| `oauth-clients` | 6个 | `DELETE`, (中文(简体) ), `GET`, (中文(简体) ), `POST`, (中文(简体) ), `PUT` |
| `oidc` | 第11个 | `GET`, (中文(简体) ), `POST` |
| `router` | 2个 | `GET` |
| `settings` | 第7条 | `GET`, (中文(简体) ), `POST`, (中文(简体) ), `PUT` |
| `visibility` | 6个 | `GET`, (中文(简体) ), `POST`, (中文(简体) ), `PUT` |
| `user` | 27个 | `DELETE`, (中文(简体) ), `GET`, (中文(简体) ), `PATCH`, (中文(简体) ), `POST`, (中文(简体) ), `PUT` |

遗留的令牌登录、网络登录、账户登录和OTP登录编码为 `application/x-www-form-urlencoded`。 。 。 . `api.operations.authBrowserLoginPost` 接受注册的公共客户端、密码或OTP证书,以及匹配的 HTTPS Origin; 它返回一个 HttpOnly 会话 cookie, 在回复中没有客户端的秘密或无记名符号 。 坚持和再利用稳定、非秘密 `device_id` 用于遗留的符号登录,以便境内流离失所者能够区分物理设备。 使用 `api.sessions()` 以列表当前会话和 `api.revokeSession(sessionId)` 取消一个。 角色指派使用角色UUID.

## 认证和授权

使用一个 `TokenProvider` 以转发已签名用户的 Bearer 令牌,或启用 `withCredentials` 用于安全的 Http 只有饼干会话。 每个行动的JSDoc都记录了本土操作员的许可和证书要求. 受保护的用户和ACL呼叫重新验证活动本地主,客户端和会话状态. SDK不嵌入 API 密钥,证书,本地主机 URL,沙盒主机,或生产主机.

## 投入、询问、答复和运输

所有方法都返回完整的Axios响应,包括状态,头,以及请求ID. 请求机构和查询对象被命名为导出接口. 管理用户 pagination 使用本地 `page` 财务报告和审定财务报表 `per_page` 键(默认值1和20;每页最多100个)。 链接计费用途 `page` 财务报告和审定财务报表 `page_size`。用户目录搜索需要至少3个被剪切的字符,并返回最多10个被遮住的匹配。 标准 Axios 请求选项、信头、超时、适配器、拦截器和 `AbortSignal` 取消被支持为最后参数.

一般性的REST资源得到能力保障。 调用未注册的遗留方法 `UnsupportedOperationError` 在发送请求之前, 而不是生成后端 `405`。 。 。 .

## 错误和取消

```ts
try {
  await api.client.get("/health", undefined, { signal: AbortSignal.timeout(5_000) });
} catch (error) {
  // Axios errors retain response.status and the service error body.
}
```

使用 `@faiber/faiber-ts-sdk` 当一个应用程序需要多个具有一个配置的Faiber服务时.

管理下的用户答复包括: `created_at`,UTC登记时间戳,无效 `display_name`,以及 `linked_providers`登记统计数据仍可通过输入用户登记 -- -- 统计系统提供.

### 手提和当前用户密码

`operations.authExchangeHandoffTokenPost({token, client_id})` 使用单用交接代码并返回一个符号信封. `authIssueHandoffTokenPost` 只有服务器且需要 `x-infera-handoff-secret`;从不将这个秘密放入浏览器代码. `authOtpLoginPost` 将其命名的输入作为 URL- 编码格式数据发送, 包括 `otp_code`。 。 。 .

`operations.userStatusGet()` 返回时 `{data:{has_password}}`。 。 。 . `userSavePut({password})` 只替换认证账户的密码并保存 OAuth 身份;密码必须包含 8–128 个字符。 website OAuth birdtrap 接受一个犬形HTTPS起源,需要管理员或可信赖的联邦服务.

## OIDC 服务路径

发现用途 `/.well-known/openid-configuration`; 授权、 令牌、 用户信息、 JWKS、 撤销、 内置和登录使用 `/oauth2/*` 在服务根。 这些路径没有 `/api/v1` 前缀。 所生成的OIDC方法使用共享客户端和窗体-编码符号/撤销输入. 内部单用符号生成需要目标用户在URL中的UUID. 只通过服务器 `x-infera-idp-service-token` 当前身份项目和所配置的内部主机的标题 。 仅主办者就被拒绝. 缺失/无效证书返回401;缺失的证书配置以503关闭失败. 永远不要在浏览器中显示项目证书或平台衍生出种子 .

### 目前的赠款和发挥积极作用的成员

`api.authority.currentPermissions(userId, { service })` 阅读该境内流离失所者目前提供的赠款。 两者都要求 `idp:user:read` 财务报告和审定财务报表 `idp:acl:read`;其修订和观察时间并不准许资源进入或证明有理由缓存许可。 消费服务仍必须强制实行所有权和目前的许可. `service` 是实际存储的 IDP 许可命名空间;对于 Messor来说,这是 `message`,不能从SDK包名中推断出.

`api.authority.activeRoleUsers({ role_name, page, per_page })` 需求 `idp:user:read` 并且总是请求允许在准确的,对案件敏感的本地角色名称中拥有当前活跃成员的账户。 可选 `role_id` 必须确定同样的作用。 它保存 Axios 的全部响应和支持 `AbortSignal`、超时和正常认证选项.

```ts
const controller = new AbortController();
const response = await api.authority.activeRoleUsers(
  { role_name: 'reviewer', page: 1, per_page: 25 },
  { signal: controller.signal },
);
const members = response.data.data.users;
```

这些方法要求境内流离失所者执行目前的赠款和角色过滤合同. `activeRoleUsers` 检查本地过滤器确认并返回活动成员, 丢弃 `IdpRoleFilterError` 有代码 `idp_role_filter_unconfirmed` 当服务器不确认范围时。 它不会产生未过滤的倒置请求. 原生HTTP和认证失败仍然是Axios错误. 每页有100个用户,境内流离失所者在最后一页之后会提出要求.

### 修改角色权限

读取 `api.authority.roleGrants(roleId)` 使用 `idp:acl:read`,检查返回的 权限,然后调用 `api.authority.changeRoleGrants(roleId, { expected_revision: snapshot.revision, add: [permissionId], remove: [] })` 两者 `idp:acl:read` 财务报告和审定财务报表 `idp:acl:update`。使用本地角色并允许UUID. 这在解剖学上保留了无关的赠款. Axios 的全部反应保留 状态、请求信头和私人 `no-store` 缓存政策。 订正为 冲突符号,从不授权证书或许可缓存.

Stale 修订版返回409:获取新快照并明确审查/重新基准 计划的变化。 绝不用新版本自动重试 。 无效, 不活跃或重复的添加和重叠的添加/移动设置返回400; 内置管理角色被保护406。 合并增加/搬迁有限 改为 `max_delta_entries` (目前为4096). 无法获取/超大快照返回503. 信号,超时和认证使用共享的客户端选项. 遗产 角色替换方法有意取代整个权限集 不得用于最小的添加剂改变。 混合的老年服务作家必须 在部署期间进行测试; 减少赠款需要重新审查 修订和删除的只是该行动仍然拥有的添加.

## 新增成员和有意替换

`roleMemberships(userId)` 读取所有存储的会籍行,包括不活动行和重复行,并进行不透明的观察修订. `addRoleMemberships(userId, { add_role_ids })` 在已经活跃的本地用户中添加1–128个独特的本地活跃角色UUID. 它保留现有成员;它从未激活账户。 服务器在目标锁定下重新检查当前读取/更新ACL权限. 两人都称返回完整的Axios响应.

```ts
await api.addRoleMemberships(userId, { add_role_ids: [reviewerRoleId] });
const observed = (await api.roleMemberships(userId)).data.data;
// Only for an intentional full replacement reviewed against this exact snapshot:
await api.changeRoles(userId, { roles: reviewedRoleIds }, observed.revision);
```

替换助手,包括生成的 PATCH/PUT 操作,需要抓取的修订版并按引用内容发送 `If-Match`。一个 stale 修订版返回 409;缺少后端先决条件返回 428. 冲突结束后刷新复议 。 永远不要拿新的修订 仅仅为了提交一个节省下来的僵硬的角色联盟。 这个SDK不会自动做到这一点. 境内流离失所者审计的迁移和后端激活要求它们分开的释放门.

## 原生反应和更新行为

`login`, (中文(简体) ), `accountLogin`, (中文(简体) ), `otpLogin`,以及 `refresh` 返回符号信封. `webLogin`, (中文(简体) ), `logout`,以及 `revokeSession` 仅返回 `{status, message}`。 。 。 . `providers()` 返回时 `{data:{providers:string[]}}`· ; `register()` 返回时 `{data:{user:{user_id, created}}}`。用户删除和强制用户退出返回 `data.user`,而角色删除返回时 `data.id` 财务报告和审定财务报表 `data.name`。 。 。 .

管理 `users.update`编号 :`users.replace` 财务报告和审定财务报表 `updateUser` 在此后端中清除省略、无效或空的标识符字段。 包括您打算保留的每一部电话、电子邮件和国家代码。 自我标识更新只填充缺失的标识符;它们拒绝以409来替换已存在的值.

行政遗产 `changePassword` 操作在插入新的密码身份之前删除所有本地身份行。 现用户 `operations.userSavePut` 操作保存其他登录身份。 已经接受 `current_password` 字段不由此后端检查;当前活动会话授权替换.

OIDC和本地授权,OAuth调回,sord-login和浏览器交接操作返回HTTP重定向. 浏览器客户端一般会导航到这些授权URL;一个Axios呼叫可能跟随重定向并接收目的地页面. OIDC令牌/用户-info/发现/JWKS/透视反应为生JSON. 登录/后通道登录返回为空 204,撤销返回为空 200. 登录页面资产下载返回带 Axios 的字节 `responseType: "arraybuffer"`; 上传需要第一个命名的多段字段 `file`,PNG/JPEG/WebP带有匹配的签名,并有1字节–8个米B.

公共登记拒绝角色分配;使用管理的创建或审查的成员流程。 需要正式成员替换 `idp:acl:update` 和抓取的修订版;读取快照需要 `idp:acl:read`以及添加剂成员更新要求。 这个 `users/sync` 操作者没有会话/ACL的守护并触发下游发布;部署网关政策决定其曝光.

### 作用目标可见度

读取 `sdk.idp.visibility.roleScope(roleId)` 并保存一个共同的目标作用列表:

```ts
const { data: response } = await sdk.idp.visibility.roleScope(supportRoleId);
await sdk.idp.visibility.saveRoleScope(supportRoleId, {
  revision: response.data.revision,
  target_role_ids: [studentRoleId, teacherRoleId],
}, { signal: abortController.signal });
```

管理要求 `idp:visibility:assign`。正常的 YAML 支持权限 控制读取、编辑、删除、密码更改和其他动作。 从未保存此瞄准镜 更改这些权限. `null` 删除角色限制; `[]` 不允许任何目标. 配置范围结合了各积极角色;未配置角色和直接角色 权限不能删除已配置的限制。 如果没有角色有配置范围, 现有权限保留不受限制的目标访问。 角色目录充满活力.

需要修改; HTTP 409 之后重新装入并审查, 并处理无效的 UUID 作为HTTP 422. 答复保留Axios元数据和共享认证/注销. 旧的 `.rules/.save` 动作赠与方法被折旧; 使用 `.roleScope/.saveRoleScope`。 。 。 . 在使用这些方法之前部署相应的境内流离失所者角色目标范围后端.

### 明确的联系人所有权

`contactVerification.facts(userId, options)` 是一个仅靠后端的集成. 通过共享传输配置服务 熊鼠证书; 从不发运 它是一个浏览器。 它返回标准信封 `user_id` 财务报告和审定财务报表 `contact_verified`,而不暴露接触值。 人口密集的接触区 或活动账户不足:当前联系人必须匹配记录 检察官办公室成功或经信任的OAuth供应商明确核实的断言. 更改联系人会使旧匹配无效 。 将出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出入出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出等等等等等等.

## 常见问题

### @faiber/faiber-idp 是什么？

认证、会话、用户、角色、权限、OAuth身份和身份设置\.

### 如何安装 @faiber/faiber-idp？

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

### @faiber/faiber-idp 支持 TypeScript 吗？

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

### @faiber/faiber-idp 支持 ESM 还是 CommonJS？

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

### @faiber/faiber-idp 可以商用吗？

@faiber/faiber-idp 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @faiber/faiber-idp 的下载量有多少？

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

### @faiber/faiber-idp 还在维护吗？

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