节点JS客户端
目录
安装
要使用 npm 安装软件包, 请运行以下
$ npm install @frontegg/e10s-client
先决条件
权限客户端与 Frontegg 的 ReBAC 授权引擎交互, 以评价权限和查询访问关系 .
寻找指示 这里
使用量
初始化客户端
import { EntitlementsClientFactory, RequestContextType } from '@frontegg/e10s-client';
const e10sClient = EntitlementsClientFactory.create({
engineEndpoint: 'localhost:50051',
engineToken: 'your-engine-token'
});
配置选项
import { EntitlementsClientFactory } from '@frontegg/e10s-client';
const e10sClient = EntitlementsClientFactory.create({
engineEndpoint: 'localhost:50051',
engineToken: 'your-engine-token',
logging: {
client: customLoggingClient, // Optional: custom logging client
logResults: true // Optional: log all query results
},
fallbackConfiguration: {
// Optional: fallback behavior on errors
defaultFallback: false
}
});
多个Frontegg 实例
一个 SpiceDB 可以服务 Frontegg 的几个实例 。 每个案例都是卖家,SDK
名称空间每个读取到该实例的 schema 前缀, 来源于其 vendorId
(单位:千美元)v_ + 供应商代号 - 改为 _) (中文(简体) ). 配置实例一次, 每选一个
调用 instanceId数字 :
const e10sClient = EntitlementsClientFactory.create({
engineEndpoint: 'localhost:50051',
engineToken: 'your-engine-token',
instances: [
{ instanceId: 'eu', vendorId: '2f9c1a44-7b0e-4a1e-9f8a-1c2d3e4f5a6b' },
{ instanceId: 'us', vendorId: '8b1d0e77-3c5a-4f2b-9d6e-7a8b9c0d1e2f' }
],
defaultInstanceId: 'eu'
});
await e10sClient.isEntitledTo(subjectContext, requestContext, { instanceId: 'us' });
instanceId每一个电话都可以选择 配置一个实例,或defaultInstanceId设置, 可以省略; 否则调用InstanceIdRequiredException。一个未知的ID抛出UnknownInstanceException两者 扩展InstanceResolutionException他们不是被弃绝的 倒计时.- 前缀总是来自
vendorId无法直接设置。 A 类vendorId可能 仅包含a-z, (中文(简体) ),0-9财务报告和审定财务报表-,最多为61个字符,而不是结尾为-任意 其他,包括大写字母和_掷出ConfigurationInputIsInvalidException当客户端被创建时。 一个instanceId必须是a-z, (中文(简体) ),0-9财务报告和审定财务报表-, (中文(简体) ), 以字母或数字开头,以及legacy保留; 其它任何投出ConfigurationInputIsInvalidException当客户端被创建时. - 每个案例都可能带有自己的
fallbackConfiguration;全客户适用 否则. - 与
instances配置, 传递给 SDK 的对象类型不得包含/,因为 sDK应用了前缀本身. 此类型投出InvalidObjectTypeException从isEntitledTo, (中文(简体) ),lookupTargetEntities财务报告和审定财务报表lookupEntities而不是被回答 倒计时。 单位isEntitledToMany只有此项失败: 它作为{ result: false, error: '<reason>' }其它东西都还没解答,请回答 任意result !== true被否认. - 没有
instances配置, 每个读取没有前缀, 并传递有效的对象类型 通过没有改变,所以这样的类型acme/document继续工作,一个普通的名字也一样 你们自己人v_user。这是一次突破性的改变 现有呼叫者在两个案例中, 两者现在都抛出InvalidObjectTypeException而不是被回答 倒置:一个不是有效 SpiceDB 名称的对象类型(见下个点),它曾经是 到达 SpiceDB 后作为已配置的倒置返回返回,并使用名称空格类型,其前缀 从保留供应商前缀开始v_,例如v_acme/document,所以遗留客户端可以 永远不要在共享 SpiceDB 上访问供应商的命名空间 . - 在两种模式中,对象类型必须是有效的 SpiceDB 名称: 3到64个字符,从
a-z,仅包含a-z, (中文(简体) ),0-9财务报告和审定财务报表_,结尾为a-z或者说0-9在遗留模式中 a 之前的每个前缀/遵守同样的规则,但最多为63个字符。 还有什么, 例如Document, (中文(简体) ),my-entity或者说a掷出InvalidObjectTypeException改为 将 SpiceDB 作为分析错误. - 日志有效载荷携带已解决
instanceId(单位:千美元)legacy否时instances已配置).LoggingClient.log财务报告和审定财务报表LoggingClient.error作为可选的线索{ instanceId }参数,所以现有的执行继续工作.
阅读实例计划
const schema = await e10sClient.readSchemaFor({ instanceId: 'us' });
readSchemaFor 只返回该实例 definition 财务报告和审定财务报表 caveat 块,有它的图案
前缀从他们的名字和类型引用中删除。 这是一个只读视图:顶级
指令被删除, 因此无法写入 。 如果计划不能分割成
安全抛出 SchemaParseException 而不是冒险返回另一个实例
定义。 没有 instances 配置它只返回未设置的前缀 definition 财务报告和审定财务报表
caveat 块,没有改变, 从来没有其他供应商的前缀块.
SpiceDB没有读取部分的 schema, 所以每个调用都读取整个 组群 schema 并过滤它
在这里。 处理 readSchemaFor 作为行政电话,并让它远离请求路径.
设定主题背景
主题上下文描述执行动作的用户,如果与 Frontegg 认证,这些动作可以从 Frontegg JWT 取出
const subjectContext: SubjectContext = {
tenantId: 'my-tenant-id',
userId: 'my-user-id', // Optional
permissions: ['read', 'write'], // Optional
attributes: { 'my-custom-attribute': 'some-value' } // Optional
};
查询
权限客户端允许您查询一个功能、权限或路由权限,每个权限都需要不同的上下文信息.
特性查询
const e10sResult = await e10sClient.isEntitledTo(subjectContext, {
type: RequestContextType.Feature,
featureKey: 'my-cool-feature'
});
if (!e10sResult.result) {
console.log(`User is not entitled to "my-cool-feature" feature`);
}
查询权限
const e10sResult = await e10sClient.isEntitledTo(subjectContext, {
type: RequestContextType.Permission,
permissionKey: 'read'
});
if (!e10sResult.result) {
console.log(`User is not entitled to "read" permission`);
}
查询路线
const e10sResult = await e10sClient.isEntitledTo(subjectContext, {
type: RequestContextType.Route,
method: 'GET',
path: '/users'
});
if (!e10sResult.result) {
console.log(`User is not entitled to "GET /users" route`);
}
FGA( 精密授权) 查询
const e10sResult = await e10sClient.isEntitledTo(
{
entityType: 'user',
key: '[email protected]'
},
{
type: RequestContextType.Entity,
entityType: 'document',
key: 'README.md',
action: 'read'
}
);
if (!e10sResult.result) {
console.log(`User is not allowed to read document`);
}
FGA 有时间访问查询( 主动 提醒)
对于使用 active_at 要控制基于时间的访问,请指定 at 参数用于在特定时间点评价访问.
const e10sResult = await e10sClient.isEntitledTo(
{
entityType: 'user',
key: '[email protected]'
},
{
type: RequestContextType.Entity,
entityType: 'document',
key: 'README.md',
action: 'read',
at: '2026-01-15T12:00:00Z'
}
);
if (!e10sResult.result) {
console.log(`User is not allowed to read document at the specified time`);
}
这个 at 参数接受 ISO 8601 格式字符串:
- UTC格式 :
2025-12-31T23:59:59Z - 时区偏移 :
2025-12-31T23:59:59+02:00
若为 at 未提供,它默认为当前协调世界时的时间.
说明: 这个
at参数也支持在 查询操作 同样的格式和行为.
实例
可运行的演示 examples/他们使用 单独 package.json 并且现在 没有 运行时安装 yarn 在雷波根.
cd examples
yarn install # pulls @frontegg/e10s-client@latest from npm
见 实例/读取 用于 Docker/ SpiceDB 设置和演示脚本.
查询操作
客户端提供查询操作,查询ReBAC授权模式,以发现实体之间的访问关系.
FGA 搜索操作支持选项 at 基于时间的存取控制参数(见 基于时间的访问) (中文(简体) ).
查询权利
查找授予租户或用户的所有权益特征密钥.
此检索返回 有效特征应享权利 关于请求的主题:
- 仅当
tenantId答复中载有该租户可获得的专项补助金. - 当两者
tenantId财务报告和审定财务报表userId答复中包含用户的有效特征补助金:租户继承补助金外加用户直接补助金. - 若为
userId但用户不是租户,答复是空的. - 如果同一特性密钥通过租户和用户获得,则在页面回复中返回一次.
在需要租户级权益时,只使用租户科目. 使用主题 userId 当您需要适用于特定用户的特性集时.
贴子 : 对于用户的查询,对租户和用户的补助金进行独立查询并发放。 通过两个流可以达到的特性密钥可能出现在不同的页面上,因此集合多页的调用者在需要时应该将特性密钥跨页复制.
const response = await e10sClient.lookupEntitlements({
subject: {
tenantId: 'tenant-123',
userId: 'user-456', // Optional: include for effective user entitlements
attributes: { plan: 'pro' } // Optional: evaluated by targeting rules
},
criteria: {
type: RequestContextType.Feature
},
limit: 100, // Optional: default 50
cursor: undefined // Optional: pagination cursor
});
console.log(`Found ${response.totalReturned} entitlement features`);
response.entitlements.forEach((entitlement) => {
console.log(`${entitlement.type}:${entitlement.key}`);
// entitlement.permissionship: 'HAS_PERMISSION' | 'CONDITIONAL_PERMISSION' | 'NO_PERMISSION'
});
if (response.cursor) {
const nextPage = await e10sClient.lookupEntitlements({
// ... same params
cursor: response.cursor
});
}
搜索目标实体
查找一个实体(即用户)有权执行特定行动的所有目标实体实例(即文档).
const response = await e10sClient.lookupTargetEntities({
entityType: 'user',
entityId: 'user-123',
TargetEntityType: 'document',
action: 'read',
limit: 100, // Optional: limit number of results (default: 50, max: 1000)
cursor: undefined, // Optional: pagination cursor
at: '2026-01-15T12:00:00Z' // Optional: ISO 8601 timestamp for active_at caveat
});
console.log(`Found ${response.totalReturned} Target Entities`);
response.targets.forEach((target) => {
console.log(`${target.TargetEntityType}:${target.TargetEntityId}`);
// target.permissionship: 'HAS_PERMISSION' | 'CONDITIONAL_PERMISSION' | 'NO_PERMISSION'
});
// For pagination, use the returned cursor
if (response.cursor) {
const nextPage = await e10sClient.lookupTargetEntities({
// ... same params
cursor: response.cursor
});
}
查询实体
查找所有有资格在特定实体实例上执行特定动作的实体(即用户)(即文档)
const response = await e10sClient.lookupEntities({
TargetEntityType: 'document',
TargetEntityId: 'doc-456',
entityType: 'user',
action: 'read',
at: '2026-01-15T12:00:00Z'
});
console.log(`Found ${response.totalReturned} entities`);
response.entities.forEach((entity) => {
console.log(`${entity.entityType}:${entity.entityId}`);
// entity.permissionship: 'HAS_PERMISSION' | 'CONDITIONAL_PERMISSION' | 'NO_PERMISSION'
});
监测
如果启用了监测模式,则只记录实际结果,以下有效载荷将始终返回
{
"result": true,
"monitoring": true
}