@grantex/strands

@grantex/strands

Strands Agents SDK integration for the Grantex delegated authorization protocol.

Create Strands tools that verify Grantex grant tokens and enforce scopes before tool execution.

Homepage | Docs | GitHub

Install

npm install @grantex/strands @grantex/sdk @strands-agents/sdk zod

Quick Start

import { Agent } from '@strands-agents/sdk';
import { createGrantexTool } from '@grantex/strands';
import { z } from 'zod';

const readCalendar = createGrantexTool({
  name: 'read_calendar',
  description: 'Read upcoming calendar events',
  inputSchema: z.object({
    date: z.string().describe('Date in YYYY-MM-DD format'),
  }),
  grantToken,
  requiredScope: 'calendar:read',
  callback: async ({ date }) => {
    return `events for ${date}`;
  },
});

const agent = new Agent({
  tools: [readCalendar],
});

If the verified grant token does not include the required scope, the tool throws GrantexScopeError before invoking your callback.

Enforcement Modes

Verified mode is the default. It verifies the grant token against JWKS and checks the verified scp claim:

const tool = createGrantexTool({
  name: 'read_calendar',
  description: 'Read upcoming calendar events',
  inputSchema: z.object({ date: z.string() }),
  grantToken,
  requiredScope: 'calendar:read',
  callback: async ({ date }) => getCalendarEvents(date),
});

Online mode delegates enforcement to a Grantex client:

const tool = createGrantexTool({
  name: 'read_calendar',
  description: 'Read upcoming calendar events',
  inputSchema: z.object({ date: z.string() }),
  grantToken,
  requiredScope: 'calendar:read',
  client: grantexClient,
  connector: 'calendar',
  online: true,
  callback: async ({ date }) => getCalendarEvents(date),
});

API Reference

createGrantexTool(options)

Creates a Strands-compatible tool with Grantex scope enforcement.

Option	Type	Description
name	string	Tool name
description	string	Tool description
inputSchema	z.ZodType	Zod schema for tool input
grantToken	string	JWT grant token from Grantex
requiredScope	string	Scope that must be present in the token
callback	(input, context?) => Promise<Result> | Result	Tool implementation
jwksUri	string	JWKS URL used to verify the grant token
issuer, issuerDid, audience	string	Optional JWT claim validation settings
clockTolerance	number	Clock tolerance in seconds for token verification
client	GrantexEnforcer	Grantex client instance for online mode
connector	string	Connector name for online mode
online	boolean	Use client.enforce() instead of JWKS-backed local verification
amount	number	Optional capped-amount value for online enforcement

getGrantScopes(grantToken)

Returns the scopes embedded in a grant token. Invalid tokens return an empty array. This helper decodes the token payload only; it does not verify the signature.

GrantexScopeError

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

Requirements

• Node.js 20+
• @grantex/sdk >= 0.3.11
• @strands-agents/sdk >= 1.6.0
• zod >= 4.1.12

Grantex Ecosystem

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

• @grantex/sdk - Core TypeScript SDK
• @grantex/langchain - LangChain integration
• @grantex/vercel-ai - Vercel AI SDK integration
• @grantex/autogen - AutoGen integration

License

Apache 2.0