BEEOS CLOUD / DEVELOPER REFERENCE

执行授权校验

用 Cloud 发布的公钥校验随运行时方法下发的执行授权。

投递可携带带签名的执行授权。这些校验器拉取已发布的公钥集，校验签名及 issuer、audience、purpose 声明，并返回解码后的授权。该能力仅存在于 TypeScript 包。

CloudGatewayGrantJwksVerifier

TypeScript @beeos-ai/cloud-harness-sdk · 仅 TypeScript

Cloud 执行授权的验证器。只有签发方、受众和用途都符合 Cloud 授权域时才接受授权；其他用途的授权会被拒绝。

class CloudGatewayGrantJwksVerifier
new CloudGatewayGrantJwksVerifier(readonly verifier: RuntimeJwksVerifier)

TypeScript · 构造

参数	类型	必填	默认值	说明
`verifier`	RuntimeJwksVerifier	是		持有密钥的 JWKS 验证器。

属性

名称	类型	说明
`readonly keysetProvenance`	`string`	该验证器所信任的密钥集的 URL。

refresh

在缓存过期或设置 force 时重新加载密钥，然后检查密钥集文档的签发方、受众和用途是否符合预期。

async refresh(force = false): Promise<void>

TypeScript · 参数

参数	类型	必填	默认值	说明
`force`	`boolean`	否	`false`	即使缓存仍有效也重新加载。

返回值 Promise<void>

verifyAndDecodeGrant

验证授权的签名以及签发方、受众和用途，返回解码后的授权；无效时返回 null。

verifyAndDecodeGrant(jwt: string): VerifiedDecodedExecutionGrant | null

TypeScript · 参数

参数	类型	必填	默认值	说明
`jwt`	`string`	是		紧凑 JWT 字符串形式的授权。

返回值 VerifiedDecodedExecutionGrant | null

CoreExecutionAuthorizationVerifier

TypeScript @beeos-ai/beeos-types · 仅 TypeScript

密码适配器只有在对完全一致的紧凑 JWT 字节完成 alg、kid 与签名校验之后，才返回其中的声明。

interface CoreExecutionAuthorizationVerifier

verifyAndDecodeGrant

除非紧凑 JWT 的签名、alg 与 kid 均可信，否则返回 null。

verifyAndDecodeGrant(compactJwt: string): VerifiedDecodedExecutionGrant | null

TypeScript · 参数

参数	类型	必填	默认值	说明
`compactJwt`	`string`	是		执行授权的紧凑 JWT，保持收到时的原样。

返回值 VerifiedDecodedExecutionGrant | null

verifyAndDecodeBoundary

除非紧凑 JWT 的签名、alg 与 kid 均可信，否则返回 null。

verifyAndDecodeBoundary(compactJwt: string): VerifiedDecodedExecutionBoundary | null

TypeScript · 参数

参数	类型	必填	默认值	说明
`compactJwt`	`string`	是		执行边界的紧凑 JWT，保持收到时的原样。

返回值 VerifiedDecodedExecutionBoundary | null

GatewayGrantJwksVerifier

TypeScript @beeos-ai/cloud-harness-sdk · 仅 TypeScript

网关执行授权的验证器。只有签发方、受众和用途都符合网关授权时才接受授权。

class GatewayGrantJwksVerifier
new GatewayGrantJwksVerifier(readonly verifier: RuntimeJwksVerifier)

TypeScript · 构造

参数	类型	必填	默认值	说明
`verifier`	RuntimeJwksVerifier	是		持有密钥的 JWKS 验证器。

属性

名称	类型	说明
`readonly purpose`	`"gateway-runtime-grant"`	该验证器固定的用途：`gateway-runtime-grant`。
`readonly keysetProvenance`	`string`	该验证器所信任的密钥集的 URL。

refresh

在缓存过期或设置 force 时重新加载密钥，然后检查密钥集文档的签发方、受众和用途是否符合预期。

async refresh(force = false): Promise<void>

TypeScript · 参数

参数	类型	必填	默认值	说明
`force`	`boolean`	否	`false`	即使缓存仍有效也重新加载。

返回值 Promise<void>

trustedKeyMaterials

返回受信公钥的指纹。

trustedKeyMaterials(): readonly RuntimeJwksKeyMaterial[]

TypeScript · 参数

无参数。

返回值 readonly RuntimeJwksKeyMaterial[]

responseProvenance

返回密钥集文档的来源；首次加载前为 undefined。

responseProvenance(): RuntimeJwksDocumentProvenance | undefined

TypeScript · 参数

无参数。

返回值 RuntimeJwksDocumentProvenance | undefined

verifyAndDecodeGrant

验证授权的签名以及签发方、受众和用途，返回解码后的授权；无效时返回 null。

verifyAndDecodeGrant(jwt: string): VerifiedDecodedExecutionGrant | null

TypeScript · 参数

参数	类型	必填	默认值	说明
`jwt`	`string`	是		紧凑 JWT 字符串形式的授权。

返回值 VerifiedDecodedExecutionGrant | null

MessageServiceBoundaryJwksVerifier

TypeScript @beeos-ai/cloud-harness-sdk · 仅 TypeScript

执行边界断言（execution boundary assertion）的验证器。只有签发方和受众都符合消息服务边界时才接受断言。

class MessageServiceBoundaryJwksVerifier
new MessageServiceBoundaryJwksVerifier(readonly verifier: RuntimeJwksVerifier)

TypeScript · 构造

参数	类型	必填	默认值	说明
`verifier`	RuntimeJwksVerifier	是		持有密钥的 JWKS 验证器。

属性

名称	类型	说明
`readonly purpose`	`"message-service-execution-boundary"`	该验证器固定的用途：`message-service-execution-boundary`。
`readonly keysetProvenance`	`string`	该验证器所信任的密钥集的 URL。

refresh

在缓存过期或设置 force 时重新加载密钥，然后检查密钥集文档的签发方、受众和用途是否符合预期。

async refresh(force = false): Promise<void>

TypeScript · 参数

参数	类型	必填	默认值	说明
`force`	`boolean`	否	`false`	即使缓存仍有效也重新加载。

返回值 Promise<void>

trustedKeyMaterials

返回受信公钥的指纹。

trustedKeyMaterials(): readonly RuntimeJwksKeyMaterial[]

TypeScript · 参数

无参数。

返回值 readonly RuntimeJwksKeyMaterial[]

responseProvenance

返回密钥集文档的来源；首次加载前为 undefined。

responseProvenance(): RuntimeJwksDocumentProvenance | undefined

TypeScript · 参数

无参数。

返回值 RuntimeJwksDocumentProvenance | undefined

verifyAndDecodeBoundary

验证边界断言的签名以及签发方和受众，返回解码后的断言；无效时返回 null。

verifyAndDecodeBoundary(jwt: string): VerifiedDecodedExecutionBoundary | null

TypeScript · 参数

参数	类型	必填	默认值	说明
`jwt`	`string`	是		紧凑 JWT 字符串形式的边界断言。

返回值 VerifiedDecodedExecutionBoundary | null

RuntimeJwksVerifier

TypeScript @beeos-ai/cloud-harness-sdk · 仅 TypeScript

仅支持 RS256 的 JWKS 验证器，缓存有时效上限，并支持显式刷新。

class RuntimeJwksVerifier implements CoreExecutionAuthorizationVerifier
new RuntimeJwksVerifier(readonly jwksUrl: string, readonly fetcher: RuntimeJwksFetch = fetch, readonly ttlMs = 5 * 60_000, readonly now: () => number = Date.now)

TypeScript · 构造

参数	类型	必填	默认值	说明
`jwksUrl`	`string`	是		JWKS 文档的 URL。
`fetcher`	RuntimeJwksFetch	否	`fetch`	用于下载文档的函数，默认是全局 `fetch`。
`ttlMs`	`number`	否	`5 * 60_000`	已加载密钥的缓存时长，单位毫秒，默认 300000（5 分钟）。
`now`	`() => number`	否	`Date.now`	毫秒时钟，测试时可替换，默认 `Date.now`。

属性

名称	类型	说明
`readonly keysetUrl`	`string`	JWKS 文档规范化后的 URL。

refresh

在尚未加载密钥、缓存已过期或设置了 force 时重新加载密钥。只信任 use: sig、alg: RS256 且至少 2048 位的 RSA 密钥。下载失败或没有可信密钥时拒绝。

async refresh(force = false): Promise<void>

TypeScript · 参数

参数	类型	必填	默认值	说明
`force`	`boolean`	否	`false`	即使缓存仍有效也重新加载。

返回值 Promise<void>

hasKid

判断是否信任具有该 kid 的密钥。

hasKid(kid: string): boolean

TypeScript · 参数

参数	类型	必填	默认值	说明
`kid`	`string`	是		要查找的密钥 ID。

返回值 boolean

trustedKids

返回所有受信密钥的密钥 ID（已排序）。

trustedKids(): readonly string[]

TypeScript · 参数

无参数。

返回值 readonly string[]

trustedKeyMaterials

返回受信公钥的指纹。

trustedKeyMaterials(): readonly RuntimeJwksKeyMaterial[]

TypeScript · 参数

无参数。

返回值 readonly RuntimeJwksKeyMaterial[]

documentProvenance

返回文档的来源（URL、ETag、签发方、受众、用途、声明最长有效期）；首次加载前为 undefined。

documentProvenance(): RuntimeJwksDocumentProvenance | undefined

TypeScript · 参数

无参数。

返回值 RuntimeJwksDocumentProvenance | undefined

verifyAndDecodeGrant

用受信密钥验证执行授权的 RS256 签名，返回解码后的授权，否则返回 null。它不校验声明；校验请用 verifyAndValidateGrant。

verifyAndDecodeGrant(compactJwt: string): VerifiedDecodedExecutionGrant | null

TypeScript · 参数

参数	类型	必填	默认值	说明
`compactJwt`	`string`	是		紧凑 JWT 字符串形式的授权。

返回值 VerifiedDecodedExecutionGrant | null

verifyAndValidateGrant

验证执行授权（execution grant）的签名，再按预期的调用上下文校验其声明。请使用本方法而不是 verifyAndDecodeGrant：仅有签名有效并不等于授权。任何一项不匹配都返回 null。

verifyAndValidateGrant(compactJwt: string, expected: RuntimeInvocationValidationContext & { activeFence: RuntimeInvocationFence; }): VerifiedDecodedExecutionGrant | null

TypeScript · 参数

参数	类型	必填	默认值	说明
`compactJwt`	`string`	是		紧凑 JWT 字符串形式的授权。
`expected`	RuntimeInvocationValidationContext & { activeFence: RuntimeInvocationFence; }	是		声明必须匹配的调用上下文，包括当前生效的 fence。

返回值 VerifiedDecodedExecutionGrant | null

verifyAndDecodeBoundary

验证执行边界断言的 RS256 签名，返回解码后的断言，否则返回 null。

verifyAndDecodeBoundary(compactJwt: string): VerifiedDecodedExecutionBoundary | null

TypeScript · 参数

参数	类型	必填	默认值	说明
`compactJwt`	`string`	是		紧凑 JWT 字符串形式的断言。

返回值 VerifiedDecodedExecutionBoundary | null

SplitIssuerRuntimeAuthorizationVerifier

TypeScript @beeos-ai/cloud-harness-sdk · 仅 TypeScript

把授权验证器和边界验证器组合起来，两者的密钥集必须来自不同来源。两个密钥集共用 URL、响应 ETag 或公钥材料时，构造函数和 refresh 会抛出错误。

class SplitIssuerRuntimeAuthorizationVerifier implements CoreExecutionAuthorizationVerifier
new SplitIssuerRuntimeAuthorizationVerifier(readonly grant: GatewayGrantJwksVerifier, readonly boundary: MessageServiceBoundaryJwksVerifier)

TypeScript · 构造

参数	类型	必填	默认值	说明
`grant`	GatewayGrantJwksVerifier	是		网关执行授权的验证器。
`boundary`	MessageServiceBoundaryJwksVerifier	是		执行边界断言的验证器。

属性

名称	类型	说明
`readonly grant`	GatewayGrantJwksVerifier	授权验证器。
`readonly boundary`	MessageServiceBoundaryJwksVerifier	边界验证器。

refresh

刷新两个验证器，并检查它们的密钥集互不相同。

async refresh(force = false): Promise<void>

TypeScript · 参数

参数	类型	必填	默认值	说明
`force`	`boolean`	否	`false`	即使缓存仍有效也重新加载。

返回值 Promise<void>

verifyAndDecodeGrant

用授权验证器验证一个授权。

verifyAndDecodeGrant(jwt: string): VerifiedDecodedExecutionGrant | null

TypeScript · 参数

参数	类型	必填	默认值	说明
`jwt`	`string`	是		紧凑 JWT 字符串形式的授权。

返回值 VerifiedDecodedExecutionGrant | null

verifyAndDecodeBoundary

用边界验证器验证一个边界断言。

verifyAndDecodeBoundary(jwt: string): VerifiedDecodedExecutionBoundary | null

TypeScript · 参数

参数	类型	必填	默认值	说明
`jwt`	`string`	是		紧凑 JWT 字符串形式的断言。

返回值 VerifiedDecodedExecutionBoundary | null

createCloudGrantVerifier

TypeScript @beeos-ai/cloud-harness-sdk · 仅 TypeScript

创建 Cloud 执行授权的验证器。它从 Agent Gateway 的 /.well-known/runtime-execution-grant-jwks.json 获取密钥集。

function createCloudGrantVerifier(agentGatewayUrl: string, fetcher?: RuntimeJwksFetch): CloudGatewayGrantJwksVerifier

TypeScript · 参数

参数	类型	必填	默认值	说明
`agentGatewayUrl`	`string`	是		Agent Gateway 的基础 URL。
`fetcher`	RuntimeJwksFetch	否		可选的、用于下载密钥集的函数，默认是全局 `fetch`。

返回值 CloudGatewayGrantJwksVerifier

warmGrantJwks

TypeScript @beeos-ai/cloud-harness-sdk · 仅 TypeScript

首次加载基于 JWKS 的验证器的密钥，并在 Cloud 仍在启动时重试。密钥加载成功时返回 true，重试预算用尽时返回 false。两种情况下你都可以继续工作，因为每次验证都会先刷新密钥。

async function warmGrantJwks(verifier: { refresh(force?: boolean): Promise<void> }, options: { policy?: BackoffPolicy; signal?: AbortSignal; onRetry?: (info: { attempt: number; delayMs: number; error: unknown }) => void } = {}): Promise<boolean>

TypeScript · 参数

参数	类型	必填	默认值	说明
`verifier`	`{ refresh(force?: boolean): Promise<void> }`	是		任何带有 `refresh(force)` 方法的对象，例如 JWKS 验证器。
`options`	{ policy?: BackoffPolicy; signal?: AbortSignal; onRetry?: (info: { attempt: number; delayMs: number; error: unknown }) => void }	否	`{}`	可选的 `policy`（默认 `STARTUP_BACKOFF`）、`signal` 与 `onRetry` 回调。

返回值 Promise<boolean>

BeeOS Cloud返回文档首页