BEEOS CLOUD / DEVELOPER REFERENCE

Execution grant verification

Verify the execution grants delivered with runtime methods against Cloud's published keys.

Deliveries can carry a signed execution grant. These verifiers fetch the published key set, check the signature and the issuer, audience and purpose claims, and return the decoded grant. This capability exists only in the TypeScript package.

CloudGatewayGrantJwksVerifier

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

Verifier for Cloud execution grants. It accepts a grant only when issuer, audience and purpose match the Cloud grant domain; grants for other purposes are rejected.

class CloudGatewayGrantJwksVerifier
new CloudGatewayGrantJwksVerifier(readonly verifier: RuntimeJwksVerifier)

TypeScript · Constructor

Parameter	Type	Required	Default	Description
`verifier`	RuntimeJwksVerifier	yes		The JWKS verifier that holds the keys.

Properties

Name	Type	Description
`readonly keysetProvenance`	`string`	URL of the key set that this verifier trusts.

refresh

Reloads the keys when the cache has expired or force is set, then checks that the key set document comes from the expected issuer, audience and purpose.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`force`	`boolean`	no	`false`	Reload even if the cache is still valid.

Returns Promise<void>

verifyAndDecodeGrant

Verifies the signature and the issuer, audience and purpose of a grant and returns it decoded, or null when it is not valid.

verifyAndDecodeGrant(jwt: string): VerifiedDecodedExecutionGrant | null

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`jwt`	`string`	yes		The grant as a compact JWT string.

Returns VerifiedDecodedExecutionGrant | null

CoreExecutionAuthorizationVerifier

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

Crypto adapter returns claims only after alg/kid/signature verification of the exact compact JWT bytes.

interface CoreExecutionAuthorizationVerifier

verifyAndDecodeGrant

Returns null unless compact JWT signature, alg and kid are trusted.

verifyAndDecodeGrant(compactJwt: string): VerifiedDecodedExecutionGrant | null

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`compactJwt`	`string`	yes		The compact JWT of the execution grant, exactly as it was received.

Returns VerifiedDecodedExecutionGrant | null

verifyAndDecodeBoundary

Returns null unless compact JWT signature, alg and kid are trusted.

verifyAndDecodeBoundary(compactJwt: string): VerifiedDecodedExecutionBoundary | null

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`compactJwt`	`string`	yes		The compact JWT of the execution boundary, exactly as it was received.

Returns VerifiedDecodedExecutionBoundary | null

GatewayGrantJwksVerifier

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

Verifier for gateway execution grants. It accepts a grant only when issuer, audience and purpose match the gateway grant.

class GatewayGrantJwksVerifier
new GatewayGrantJwksVerifier(readonly verifier: RuntimeJwksVerifier)

TypeScript · Constructor

Parameter	Type	Required	Default	Description
`verifier`	RuntimeJwksVerifier	yes		The JWKS verifier that holds the keys.

Properties

Name	Type	Description
`readonly purpose`	`"gateway-runtime-grant"`	Fixed purpose of this verifier: `gateway-runtime-grant`.
`readonly keysetProvenance`	`string`	URL of the key set that this verifier trusts.

refresh

Reloads the keys when the cache has expired or force is set, then checks that the key set document comes from the expected issuer, audience and purpose.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`force`	`boolean`	no	`false`	Reload even if the cache is still valid.

Returns Promise<void>

trustedKeyMaterials

Returns the fingerprints of the trusted public keys.

trustedKeyMaterials(): readonly RuntimeJwksKeyMaterial[]

TypeScript · Parameters

No parameters.

Returns readonly RuntimeJwksKeyMaterial[]

responseProvenance

Returns where the key set document came from, or undefined before the first load.

responseProvenance(): RuntimeJwksDocumentProvenance | undefined

TypeScript · Parameters

No parameters.

Returns RuntimeJwksDocumentProvenance | undefined

verifyAndDecodeGrant

Verifies the signature and the issuer, audience and purpose of a grant and returns it decoded, or null when it is not valid.

verifyAndDecodeGrant(jwt: string): VerifiedDecodedExecutionGrant | null

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`jwt`	`string`	yes		The grant as a compact JWT string.

Returns VerifiedDecodedExecutionGrant | null

MessageServiceBoundaryJwksVerifier

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

Verifier for execution boundary assertions. It accepts an assertion only when issuer and audience match the message service boundary.

class MessageServiceBoundaryJwksVerifier
new MessageServiceBoundaryJwksVerifier(readonly verifier: RuntimeJwksVerifier)

TypeScript · Constructor

Parameter	Type	Required	Default	Description
`verifier`	RuntimeJwksVerifier	yes		The JWKS verifier that holds the keys.

Properties

Name	Type	Description
`readonly purpose`	`"message-service-execution-boundary"`	Fixed purpose of this verifier: `message-service-execution-boundary`.
`readonly keysetProvenance`	`string`	URL of the key set that this verifier trusts.

refresh

Reloads the keys when the cache has expired or force is set, then checks that the key set document comes from the expected issuer, audience and purpose.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`force`	`boolean`	no	`false`	Reload even if the cache is still valid.

Returns Promise<void>

trustedKeyMaterials

Returns the fingerprints of the trusted public keys.

trustedKeyMaterials(): readonly RuntimeJwksKeyMaterial[]

TypeScript · Parameters

No parameters.

Returns readonly RuntimeJwksKeyMaterial[]

responseProvenance

Returns where the key set document came from, or undefined before the first load.

responseProvenance(): RuntimeJwksDocumentProvenance | undefined

TypeScript · Parameters

No parameters.

Returns RuntimeJwksDocumentProvenance | undefined

verifyAndDecodeBoundary

Verifies the signature and the issuer and audience of a boundary assertion and returns it decoded, or null when it is not valid.

verifyAndDecodeBoundary(jwt: string): VerifiedDecodedExecutionBoundary | null

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`jwt`	`string`	yes		The boundary assertion as a compact JWT string.

Returns VerifiedDecodedExecutionBoundary | null

RuntimeJwksVerifier

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

RS256-only JWKS verifier with bounded cache lifetime and explicit refresh.

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

TypeScript · Constructor

Parameter	Type	Required	Default	Description
`jwksUrl`	`string`	yes		URL of the JWKS document.
`fetcher`	RuntimeJwksFetch	no	`fetch`	Function used to download the document. Defaults to the global `fetch`.
`ttlMs`	`number`	no	`5 * 60_000`	How long loaded keys are cached, in milliseconds. Defaults to 300000 (5 minutes).
`now`	`() => number`	no	`Date.now`	Clock in milliseconds; replace it in tests. Defaults to `Date.now`.

Properties

Name	Type	Description
`readonly keysetUrl`	`string`	Normalised URL of the JWKS document.

refresh

Reloads the keys when none are loaded, the cache has expired, or force is set. Only RSA keys with use: sig, alg: RS256 and at least 2048 bits are trusted. Rejects when the download fails or no trusted key is found.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`force`	`boolean`	no	`false`	Reload even if the cache is still valid.

Returns Promise<void>

hasKid

Tells whether a key with this kid is trusted.

hasKid(kid: string): boolean

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`kid`	`string`	yes		Key id to look for.

Returns boolean

trustedKids

Returns the sorted key ids of all trusted keys.

trustedKids(): readonly string[]

TypeScript · Parameters

No parameters.

Returns readonly string[]

trustedKeyMaterials

Returns the fingerprints of the trusted public keys.

trustedKeyMaterials(): readonly RuntimeJwksKeyMaterial[]

TypeScript · Parameters

No parameters.

Returns readonly RuntimeJwksKeyMaterial[]

documentProvenance

Returns where the document came from (URL, ETag, issuer, audience, purpose, maximum claim lifetime), or undefined before the first load.

documentProvenance(): RuntimeJwksDocumentProvenance | undefined

TypeScript · Parameters

No parameters.

Returns RuntimeJwksDocumentProvenance | undefined

verifyAndDecodeGrant

Verifies the RS256 signature of an execution grant with the trusted keys and returns it decoded, or null. It does not validate the claims; use verifyAndValidateGrant for that.

verifyAndDecodeGrant(compactJwt: string): VerifiedDecodedExecutionGrant | null

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`compactJwt`	`string`	yes		The grant as a compact JWT string.

Returns VerifiedDecodedExecutionGrant | null

verifyAndValidateGrant

Verifies the signature of an execution grant and then validates its claims against the expected invocation context. Use this method rather than verifyAndDecodeGrant: a valid signature alone is not authorization. Returns null when anything does not match.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`compactJwt`	`string`	yes		The grant as a compact JWT string.
`expected`	RuntimeInvocationValidationContext & { activeFence: RuntimeInvocationFence; }	yes		The invocation context that the claims must match, including the active fence.

Returns VerifiedDecodedExecutionGrant | null

verifyAndDecodeBoundary

Verifies the RS256 signature of an execution boundary assertion and returns it decoded, or null.

verifyAndDecodeBoundary(compactJwt: string): VerifiedDecodedExecutionBoundary | null

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`compactJwt`	`string`	yes		The assertion as a compact JWT string.

Returns VerifiedDecodedExecutionBoundary | null

SplitIssuerRuntimeAuthorizationVerifier

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

Combines a grant verifier and a boundary verifier whose key sets come from different sources. The constructor and refresh throw when the two key sets share a URL, a response ETag or public-key material.

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

TypeScript · Constructor

Parameter	Type	Required	Default	Description
`grant`	GatewayGrantJwksVerifier	yes		Verifier for gateway execution grants.
`boundary`	MessageServiceBoundaryJwksVerifier	yes		Verifier for execution boundary assertions.

Properties

Name	Type	Description
`readonly grant`	GatewayGrantJwksVerifier	The grant verifier.
`readonly boundary`	MessageServiceBoundaryJwksVerifier	The boundary verifier.

refresh

Refreshes both verifiers and checks that their key sets are distinct.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`force`	`boolean`	no	`false`	Reload even if the caches are still valid.

Returns Promise<void>

verifyAndDecodeGrant

Verifies a grant with the grant verifier.

verifyAndDecodeGrant(jwt: string): VerifiedDecodedExecutionGrant | null

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`jwt`	`string`	yes		The grant as a compact JWT string.

Returns VerifiedDecodedExecutionGrant | null

verifyAndDecodeBoundary

Verifies a boundary assertion with the boundary verifier.

verifyAndDecodeBoundary(jwt: string): VerifiedDecodedExecutionBoundary | null

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`jwt`	`string`	yes		The assertion as a compact JWT string.

Returns VerifiedDecodedExecutionBoundary | null

createCloudGrantVerifier

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

Creates the verifier for Cloud execution grants. It fetches the key set from Agent Gateway at /.well-known/runtime-execution-grant-jwks.json.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`agentGatewayUrl`	`string`	yes		Base URL of Agent Gateway.
`fetcher`	RuntimeJwksFetch	no		Optional function used to download the key set; defaults to the global `fetch`.

Returns CloudGatewayGrantJwksVerifier

warmGrantJwks

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

Loads the keys of a JWKS-backed verifier for the first time, retrying while Cloud is still starting. Resolves true once keys are loaded and false when the retry budget is used up. You can keep working either way, because every verification refreshes the keys first.

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 · Parameters

Parameter	Type	Required	Default	Description
`verifier`	`{ refresh(force?: boolean): Promise<void> }`	yes		Any object with a `refresh(force)` method, for example a JWKS verifier.
`options`	{ policy?: BackoffPolicy; signal?: AbortSignal; onRetry?: (info: { attempt: number; delayMs: number; error: unknown }) => void }	no	`{}`	Optional `policy` (default `STARTUP_BACKOFF`), `signal` and `onRetry` callback.

Returns Promise<boolean>

BeeOS CloudBack to documentation