@grantex/vercel-ai weekly downloads statistics

@grantex/vercel-ai

Vercel AI SDK integration for the Grantex delegated authorization protocol.

Adds scope-enforced tools and audit logging to any Vercel AI SDK agent.

Homepage | Docs | Sign Up Free | GitHub

Install

Quick Start

Scope-Enforced Tools

Create Vercel AI SDK tools with Grantex authorization. Before each execution, the wrapper verifies the token against JWKS and checks the verified scope. Invalid or insufficient tokens fail before your tool implementation runs:

Inspect Grant Scopes

Use getGrantScopes to check what scopes a token has before creating tools:

Audit Logging

Wrap tools with withAuditLogging to log every invocation to the Grantex audit trail:

API Reference

createGrantexTool(options)

Creates a Vercel AI SDK tool with Grantex scope enforcement.

| Option | Type | Description |

| name | string | Tool name | | description | string | Tool description | | parameters | z.ZodTypeAny | Zod schema for tool arguments | | grantToken | string | Grantex JWT from token exchange | | jwksUri | string? | JWKS URL; defaults to the Grantex production JWKS | | issuer, issuerDid, audience | string? | Optional JWT claim validation settings | | clockTolerance | number? | Clock tolerance in seconds | | requiredScope | string | Scope required — checked against verified claims before execution | | execute | (args, options) => Promise | Tool implementation |

Throws GrantexScopeError during execution if the verified scope is missing; token verification failures also reject execution.

getGrantScopes(grantToken)

Returns the unverified string[] from the token's scp claim for diagnostics only. Do not use this helper to authorize a call.

withAuditLogging(tool, client, options)

Wraps a Grantex tool with audit logging.

| Option | Type | Description |

| agentId | string | Agent ID for audit attribution | | agentDid | string | Agent DID for audit attribution | | grantId | string | Grant ID for the session | | principalId | string | Principal that authorized the agent | | toolName | string? | Override tool name in audit entries |

GrantexScopeError

Error thrown when a grant token is missing the required scope.

| Property | Type | Description |

| requiredScope | string | The scope that was required | | grantedScopes | string[] | The scopes the token actually has |

Requirements

• Node.js 18+ • @grantex/sdk >= 0.3.11 • ai >= 4.0.0 (Vercel AI SDK) • zod >= 3.0.0

Links

• Grantex Protocol • Vercel AI SDK Docs • TypeScript SDK • Spec

Grantex Ecosystem

This package is part of the Grantex ecosystem. See also:

• @grantex/sdk — Core TypeScript SDK • grantex — Python SDK • @grantex/langchain — LangChain integration • @grantex/autogen — AutoGen integration • @grantex/mcp — MCP server for Claude Desktop / Cursor / Windsurf

License

Apache 2.0

Ownership

Grantex is owned by Orchestrum Technologies LLP. Inventor and owner: Sanjeev Kumar. Ownership contact: sanjeev@orchestrum.in or mishra.sanjeev@gmail.com. Authority hardening requires TypeScript SDK 0.8.1 (currentAuthority), not just a valid JWT signature. Bind the audience and trusted human/agent identities, and check the issuer before every execution. This does not create human consent or automatically consume action decisions/spend caps. Existing offline defaults remain offline. Verify registry availability before installation. See the SDK execution authority guide.