@ gentleduck/ iam (英语)
现代ABAC/RBAC访问控制引擎. 框架-不可知核与集成为Express,NestJS,Hono,Next.js,React,和Vue.
麻省理工学院 - 说吧 更改日志 - 说吧 警卫 - 说吧 文档
TypeScript的型号安全授权引擎. RBAC + ABAC 具有政策引擎,条件评价,范围化作用,以及特快,雀巢JS,Hono,Next.js,React,Vue,和香草JS的集成.
一次运行中的依赖性(uuid只有Drizzle计划帮手才进来 树能震动 - 看 模块大小 下面是每个单元的实际数字.
安装
npm install @gentleduck/iam
# or
bun add @gentleduck/iam
快开始
import { createIam } from '@gentleduck/iam/core'
import { IamMemoryAdapter } from '@gentleduck/iam/adapters/memory'
const access = createIam({
actions: ['create', 'read', 'update', 'delete'] as const,
resources: ['post', 'comment', 'user'] as const,
roles: ['viewer', 'editor', 'admin'] as const,
})
const viewer = access.defineRole('viewer').grant('read', 'post').grant('read', 'comment').build()
const editor = access.defineRole('editor').inherits('viewer').grant('update', 'post').build()
const admin = access.defineRole('admin').inherits('editor').grantCRUD('post').grantCRUD('comment').build()
const policy = access
.definePolicy('blog')
.rule('owner-edit', (r) => r.allow().on('update').of('post').when((w) => w.isOwner()))
.build()
const adapter = new IamMemoryAdapter({
policies: [policy],
roles: [viewer, editor, admin],
assignments: { 'user-1': ['editor'] },
})
const engine = access.createEngine({ adapter })
const allowed = await engine.can('user-1', 'read', { type: 'post', attributes: {} })
// true
业绩
以其他5个联署材料授权图书馆为基准,使用vitest板凳
(单位:千美元)bun run bench) (中文(简体) ). 本节中的每个数字均以下列数值计量: 5.6.0 (简体中文) 一个
机器在一次运行中,此后没有重新计量;将其读作比率
而不是当下读取您的硬件。 重新运行 bun run bench
在引用其中任何一个之前。 两种不同的东西被测量 - 保持它们
分开.
只有规则匹配 (没有适配器,没有引擎包装), ops/sec:
| 图书馆 | 行动/秒 | 对CASL |
|---|---|---|
| @ casl/ 可读性 | ~17.0M (单位:千美元) | 基线 |
| 轻而易举 | ~ 5.0M (单位:千米) | 3.4x 较慢 |
| @rbac/rbac (英语) | 约3.3M | 5.2x 慢点 |
@ gentleduck/ iam (英语) iamEvaluateFast() | ~7.6M) 坐标: | 2.2x 慢点 |
| 访问控制 | ~1.3M (单位:千美元) | 12.8x 较慢 |
| 凸轮 | ~ 208K 键 | 82x 慢点 |
engine.can() - 真正的入口,完整的堆放(适应器+钩子+)
专题分辨率+汇编的表格:
| 模式 | 行动/秒 | 对CASL |
|---|---|---|
mode: 'production' (编译表 | ~1.15亿 | ~14x 慢点 |
@casl/可读性(可预建, .can()(中文(简体) ) | ~17.0M (单位:千美元) | 基线 |
mode: 'development' 运行同一汇总的判决书表格,并 (单位:千美元)
运行口译,以恢复 reason编号 :policy编号 :rule 来源
表格在编译时擦去,并申明两者一致。 这大概要花很多钱
2.4x在同一台机上生产. 这就是目的:发展就是发展
表格/解释的分歧应浮出水面,生产是
第二评价员将纯粹是间接费用.
CASL是一个更窄的工具:一个平整的规则集,完全同步,没有持久性
层. engine.can() 还运行一个政策引擎( 4个结合算法)
区域局角色继承、适配器/缓冲/
残废层 和生命周期钩 - 这是 async。这一差距是:
地面的成本,而不是低效率的追逐.
实际不是瓶颈:~1.15M操作/秒为~0.87μs每检查一次 在一个核心上 - 网络, DB, 及其周围的串行化成本超过 在任何真实的要求中,检查本身。 吞吐量不会下降 目录大小 ; 编译表为 O(1) 索引查询 不论存在多少角色或政策。 到底发生了什么 约束大小为目录 形状 - 角色数,非常广 动作 x 资源网格, 以及深层层资源类型 不是原始请求吞吐量。 过去32个角色的32位赠与面罩不能 所以引擎会发出一次警告,然后回到 翻译:仍然正确,不再使用O(1).
对于最小的捆绑,仅导入您通过子路径使用的东西:
// Engine-only (skip adapters, server middleware, client wrappers)
import { IamEngine, iamEvaluatePolicyFast } from '@gentleduck/iam/core'
// Each adapter, server adapter, and client wrapper is a separate entry
import { IamMemoryAdapter } from '@gentleduck/iam/adapters/memory'
import { iamAdminRouter } from '@gentleduck/iam/server/express'
import { createIamAccessControl } from '@gentleduck/iam/client/react'
// Validator (12 KB) - lazy-loaded by engine.admin.savePolicy on first
// call, or imported directly for standalone validation tooling
import { validatePolicy } from '@gentleduck/iam/core/validate'
// Fluent builder (9 KB) - config-time only, separate subpath
import { definePolicy, defineRole } from '@gentleduck/iam/core/builder'
import * from '@gentleduck/iam' 拉起所有管子(~41 KB)
g. 使用子路径导入 + 抖出树来的实际部署
在15-25 KB时.
特征
- 非洲区域局+非洲区域局 在一个引擎中合并
- 政策引擎 包含4个政策内部算法(默认覆盖、允许覆盖、第一匹配、最高优先级)和3个交叉政策组合模式(和/允许覆盖/第一适用)
- 19个条件操作员 (eq, neq, gt, lt, in, 包含, 起始 with, 匹配, 存在, 子集 of, before, between, gt, and more)
- 范围化的作用 多租户系统
- 开发/程序模式数字 :
check()返回一个IDecision(一) 在发展中,在生产中;can()返回两者中的布尔值 - 解释 API: 完整的评价追踪,确切显示批准或拒绝批准的原因
- 生命周期钩数字 :
beforeEvaluate, (中文(简体) ),afterEvaluate, (中文(简体) ),onDeny, (中文(简体) ),onError, (中文(简体) ),onPolicyError, (中文(简体) ),onMetrics - 类型安全配置:在编译时验证行动、资源、作用和范围
SRE 原始人类
engine.preload()- 在靴子上取暖;{ validator: true }也验证每个存储行engine.healthCheck()- 说吧/healthz- 已准备好的探测器,适配器耐用性+缓存命中率engine.stats.get()编号 :engine.stats.reset()- 缓存击中/ 漏掉每个缓存的计数器engine.cache.invalidate()编号 :invalidatePolicies()编号 :invalidateRoles(id?)编号 :invalidateSubject(id)- 有目标的缓存冲engine.admin.export()编号 :import(snapshot, { mode })- 计划化政策+促进环境的作用简介engine.dispose()- 关闭时解除交叉无效订阅IConfig.adapterTimeoutMs- 说吧AbortController- 每一次适配器呼叫、决定路径和engine.admin相同(违约5 s)IConfig.hookTimeoutMs- 在承诺下捆绑回钩(默认5 s;0无限期等待)IConfig.maxPolicies编号 :maxRoles- 关闭的负载时封盖IConfig.allowFailOpen- 何时要求明确选择加入defaultEffect实值'allow',在每个模式下IConfig.invalidator- 跨事件缓存验证广播机createIamRedisInvalidator时间@gentleduck/iam/invalidators/redis- 酒吧/子助手,自带过滤器iamCreateMetricsAggregator时间@gentleduck/iam/observability/metrics- 第50页/第95页/第99页onMetrics事件- HttpAdapter 重试 + 按请求超时 + 断路器 (退后、退后、门槛、冷却)
- 需求
authorize回调 在每个管理员路由器上( Express, Hono, Next, Nest)
一体化
服务器中间软件
// Express
import { iamGuard, iamAdminRouter } from '@gentleduck/iam/server/express'
app.delete('/posts/:id', iamGuard(engine, 'delete', 'post'), handler)
app.use('/admin', iamAdminRouter(engine, { authorize: (req) => isAdmin(req) })(() => express.Router()))
// Hono
import { iamGuard, iamBindAdminRouter } from '@gentleduck/iam/server/hono'
app.delete('/posts/:id', iamGuard(engine, 'delete', 'post'), handler)
iamBindAdminRouter(adminApp, engine, { authorize: (c) => isAdmin(c) })
// NestJS
import { iamNestAccessGuard, IamAuthorize, createIamAdminOperations } from '@gentleduck/iam/server/nest'
@IamAuthorize({ action: 'delete', resource: 'post' })
// Next.js
import { withIamAccess, createIamAdminHandlers } from '@gentleduck/iam/server/next'
export const DELETE = withIamAccess(engine, 'delete', 'post', handler, {
getUserId: async () => (await auth()).userId, // required - headers are spoofable
})
客户端库
// React
import { createIamAccessControl } from '@gentleduck/iam/client/react'
const { AccessProvider, useAccess, Can, Cannot } = createIamAccessControl(React)
// Vue
import { createIamVueAccess } from '@gentleduck/iam/client/vue'
const { useAccess, Can, Cannot } = createIamVueAccess(vue)
// Vanilla JS
import { IamAccessClient } from '@gentleduck/iam/client/vanilla'
const client = await IamAccessClient.fromServer('/api/permissions')
client.can('read', 'post') // boolean
数据库适配器
import { IamMemoryAdapter } from '@gentleduck/iam/adapters/memory'
import { IamFileAdapter } from '@gentleduck/iam/adapters/file'
import { IamPrismaAdapter } from '@gentleduck/iam/adapters/prisma'
import { IamDrizzleAdapter } from '@gentleduck/iam/adapters/drizzle'
import { IamRedisAdapter } from '@gentleduck/iam/adapters/redis'
import { IamHttpAdapter } from '@gentleduck/iam/adapters/http'
交易
写作和阅读可以运行在您拥有的交易上. withTransaction(tx) 返回视图
与您的交易控件绑定的引擎; 控件对 duck-iam 是不透明的, 并交接
直接回到你的适配器.
let pending
await db.transaction(async (tx) => {
const perms = engine.withTransaction(tx)
await perms.admin.assignRole(userId, 'admin', orgId)
await tx.insert(members).values({ userId, orgId })
pending = perms.pending
})
await pending.flush() // invalidate and broadcast only after the commit
写字经过 .admin,与 engine.admin因此,有一个写
表面而不是两个.
在绑定视图上读取与交易本地缓存对齐运行,所以它们可以看到交易的 拥有未承付的赠款; 共享引擎不断从其温暖的缓存中解答 交易从不污染。 一个空的本地缓存总是漏入绑定适配器, 使交易中的复写正确.
缓存无效不会在交易中开火 - 包括 config.invalidator
舰队广播。 他们缓冲 pending,去重复,并开火 flush()A级
因此,回滚赠款从不驱逐另一个节点的缓存,因为一个没有的字
发生. pending.discard() 将缓冲器降为明确的回滚路径.
withTransaction 需要一个执行的适配器 withClient细雨和棱镜
适配器这样做; 内存、 文件、 redis 和 http 不 - 他们没有交易可加入 - &
withTransaction 而不是默默地离开你的书写.
批次写
assignRoles, (中文(简体) ), revokeRoles 财务报告和审定财务报表 moveRoleScopes 列表并逐行报告结果.
(单位:千美元)invalidateSubjects 也需要列表,但它是一个缓存滴,而不是一个写入
返回时 void. ) (中文(简体) )
const result = await engine.admin.assignRoles([
{ subjectId: 'u1', roleId: 'admin' },
{ subjectId: 'u2', roleId: 'editor', scope: 'org-1' },
])
result.applied // 2
result.outcomes // one entry per input row, in input order
每行在写出之前都会被验证,所以一个错误的行会中止批次
半应用。 每个受影响的主体一次被宣布无效,尽管有许多行将其命名.
细雨适配器会把写作崩溃成一个 INSERT 和一个 DELETE - 那个 DELETE
需求 or 在适配器中 ops,并逐行取消没有它。 无适配器
基于设置的形式循环,因此每个适配器都支持每个批量的形式.
每个结果都带有它回答的一行, 所以没有什么可以分析一个ID回一个三, 和两行结构相同的条目分开:
const result = await engine.admin.assignRoles(rows)
result.outcomes.map((o) => o.row) // the rows you passed in, same objects, same order
两个角色都是一流的 所以每一行都是 ok: 已授予一个主题角色
持有是成功,而不是错过, 完全像一行 assignRole 治疗之. changed
带更细的回答:
const again = await engine.admin.assignRoles([{ subjectId: 'u1', roleId: 'admin' }])
again.applied // 1 - the grant is in place
// `ok` is always `true`: a malformed row aborts the whole batch before any write, so
// there is no failed-row arm to narrow on. Read `value` directly.
const [outcome] = again.outcomes
outcome?.value.changed // false - this call is not what put it there
changed | 含义 |
|---|---|
true | 此行用于写入所作的声明 |
false | ,该行已经处于请求状态,或者该批次中较早的一行已经用于此写入 |
| 缺席 | 适配器不能说,也没有猜到 |
它没有出现在 MySQL上,因为它没有 RETURNING,并且在每个适配器上循环
单行法,返回 void也不付额外阅读费.
每次写作都记在一行的账上 也就是第一行 名单
同一三次报告 true 接下来 false 而不是两行都要求写
一次创建数据库并撤销 {u1, admin} 并行 {u1, admin, scope: 'org-1'} 贷方
通配符行,它已经覆盖了更窄的一行。 两者均被驳回
老实回答.
可操作性
import { createIamRedisInvalidator } from '@gentleduck/iam/invalidators/redis'
import { iamCreateMetricsAggregator } from '@gentleduck/iam/observability/metrics'
const metrics = iamCreateMetricsAggregator()
const engine = new IamEngine({
adapter,
invalidator: createIamRedisInvalidator({ client: redis }),
hooks: { onMetrics: metrics.record },
})
await engine.preload()
app.get('/healthz', async (_, res) => res.json(await engine.healthCheck()))
app.get('/metrics', (_, res) => res.json(metrics.snapshot()))
无效者 client 需要两个 Redis 连接, 而不是一个 - 订阅
连接不能发布其他命令 - 并使用 secret 用于HMAC-SHA256
信封签名,应当设置在生产中.
见 生产部署指南 用于缓存 TTL 权衡,多节点无效模式,故障关闭默认,以及 SLO 目标.
模块大小( gzipped)
按5.6.0计算,与上述业绩数字相同.
| 模块 | 大小 |
|---|---|
| 核心引擎(典型的导入) | ~ 15 KB 键 |
core/validate (只管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管 | 12个KB |
core/builder (仅限配置时间) | 9个KB |
core/explain (dev-mode 跟踪) | 单独块 |
| 每个适配器 | 1.7 - 6 KB (韩语) |
| 每个服务器中间软件 | 2.4 - 3.7 KB (韩语) |
| 每个客户端库 | 1.2 - 2.0 KB (韩语) |
基准中的"完整"捆绑头条(~41 KB)是最糟糕的
"进口一切"的号码 什么 import * from '@gentleduck/iam'
会拉出。 现实部署最终达到15-25KB,因为适配器,
服务器中间软件,客户端位于子路径导入和
校验器仅在管理员写入路径运行时才懒惰地装入 。 见
基准页
用于每个标注的测量.
文档
- 引用( 从这里开始) :
docs/reference/- 11页 以子系统覆盖包子系统,对源写入. 发动机及其 配置、操作员表、角色和范围、验证、构建者和痕迹 适配器,四个服务器集成,客户端,devtools,以及操作. - 站点 : (原始内容存档于2012-10-10). sweetduck.org/duck-iam
- 所编译的引擎内部(圆卡桶,角色比特马斯克,所编译的表格,并有图表):
docs/compiled-engine-explained.md - 引擎重写设计历史 + 已知限制 :
docs/engine-rewrite.md - 开发工具:导入
@gentleduck/iam/dt检查应用程序内的政策评价 - 兄弟姐妹重现 :
@gentleduck/auth, (中文(简体) ),@gentleduck/ui, (中文(简体) ),@gentleduck/upload, (中文(简体) ),@gentleduck/md
捐款
Repo 中的 PR 核对表 + 样式注释 CONTRIBUTING.md。 。 。 .
安全披露: SECURITY.md。 。 。 .
许可证
麻省理工学院. 见 LICENSE。 。 。 .