Vercel AI SDK

Scope-enforced tools and audit logging for Vercel AI SDK agents.

Install

npm install @grantex/vercel-ai @grantex/sdk ai zod

Scope-Enforced Tools

Create Vercel AI SDK tools with Grantex authorization. The token signature and claims are verified and the required scope is checked at execution time, immediately before the application callback runs:

import { createGrantexTool } from '@grantex/vercel-ai';
import { z } from 'zod';

const readCalendar = createGrantexTool({
  name: 'read_calendar',
  description: 'Read upcoming calendar events',
  parameters: z.object({
    date: z.string().describe('Date in YYYY-MM-DD format'),
  }),
  grantToken,                     // JWT from Grantex token exchange
  requiredScope: 'calendar:read', // checked after JWKS verification at execution
  execute: async (args) => {
    return await getCalendarEvents(args.date);
  },
});

// Use with generateText, streamText, etc.
import { generateText } from 'ai';

const { text } = await generateText({
  model: openai('gpt-4'),
  tools: { read_calendar: readCalendar },
  prompt: 'What meetings do I have today?',
});

Inspect Grant Scopes

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

import { getGrantScopes } from '@grantex/vercel-ai';

const scopes = getGrantScopes(grantToken);
// → ['calendar:read', 'email:send']

Audit Logging

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

import { Grantex } from '@grantex/sdk';
import { createGrantexTool, withAuditLogging } from '@grantex/vercel-ai';

const client = new Grantex({ apiKey: process.env.GRANTEX_API_KEY });

const audited = withAuditLogging(readCalendar, client, {
  agentId: 'ag_01ABC...',
  agentDid: 'did:key:z6Mk...',
  grantId: 'grnt_01XYZ...',
  principalId: 'user_01',
});
// Use audited in place of readCalendar

API Reference

createGrantexTool(options)

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
requiredScope	string	Scope required after JWKS verification at execution time
execute	(args, options) => Promise<Result>	Tool implementation

Execution throws GrantexScopeError if the verified scope is missing and does not call the application implementation.

getGrantScopes(grantToken)

Returns unverified string[] scopes decoded from the token’s scp claim. Use this only for display or debugging; protected tool execution performs signature verification.

withAuditLogging(tool, client, options)

Option	Type	Description
agentId	string	Agent ID for audit attribution
agentDid	string	Agent DID (e.g. did:key:z6Mk...)
grantId	string	Grant ID for the session
principalId	string	Principal ID that granted authorization
toolName	string?	Override tool name in audit entries

GrantexScopeError

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.1.0
• ai >= 4.0.0 (Vercel AI SDK)
• zod >= 3.0.0

Ownership

Grantex is owned by Orchestrum Technologies LLP. Inventor and owner: Sanjeev Kumar. Ownership contact: [e-mail] or [e-mail].