@grantex/langchain

LangChain integration for the Grantex delegated authorization protocol.

Adds scope-enforced tools and automatic audit logging to any LangChain agent.

Homepage | Docs | Sign Up Free | GitHub

Install

npm install @grantex/langchain @grantex/sdk @langchain/core

Quick Start

Scope-Enforced Tools

Wrap any tool function with createGrantexTool to enforce Grantex scope authorization before execution:

import { createGrantexTool } from '@grantex/langchain';

const tool = createGrantexTool({
  name: 'read_calendar',
  description: 'Read upcoming calendar events',
  grantToken,                     // JWT from Grantex token exchange
  requiredScope: 'calendar:read', // must be in token's scp claim
  func: async (input) => {
    // your tool logic — only runs if scope check passes
    return JSON.stringify(await getCalendarEvents(input));
  },
});

// Use with any LangChain agent
const agent = createToolCallingAgent({ llm, tools: [tool], prompt });

The scope check is offline — it reads the scp claim from the JWT directly, no network call needed. If the token doesn't include the required scope, the tool throws before your function runs.

Audit Logging

Attach GrantexAuditHandler as a LangChain callback to automatically log every tool invocation to the Grantex audit trail:

import { Grantex } from '@grantex/sdk';
import { GrantexAuditHandler } from '@grantex/langchain';

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

const auditHandler = new GrantexAuditHandler({
  client,
  agentId: 'ag_01ABC...',
  grantToken,
});

// Attach to any chain or agent executor
const result = await agentExecutor.invoke(
  { input: 'What meetings do I have today?' },
  { callbacks: [auditHandler] },
);

Each tool call logs:

• tool:<toolName> with status: 'success' on success
• tool:error with status: 'failure' on error

API Reference

createGrantexTool(options)

Creates a LangChain DynamicTool with Grantex scope enforcement.

| Option | Type | Description | |--------|------|-------------| | name | string | Tool name shown to the LLM | | description | string | Tool description shown to the LLM | | grantToken | string | Grantex JWT from token exchange | | requiredScope | string | Scope required to invoke this tool | | func | (input: string) => Promise<string> | Tool implementation |

GrantexAuditHandler

LangChain callback handler that writes tool invocations to the Grantex audit trail.

| Option | Type | Description | |--------|------|-------------| | client | Grantex | Authenticated SDK client | | agentId | string | Agent ID for audit attribution | | grantToken | string | JWT (grant ID extracted from grnt or jti claim) |

Requirements

• Node.js 18+
• @grantex/sdk >= 0.1.0
• @langchain/core >= 0.3.0

Links

• Grantex Protocol
• TypeScript SDK
• Python SDK
• Spec

Grantex Ecosystem

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

• @grantex/sdk — Core TypeScript SDK
• grantex — Python SDK
• @grantex/vercel-ai — Vercel AI SDK integration
• @grantex/autogen — AutoGen integration
• @grantex/mcp — MCP server for Claude Desktop / Cursor / Windsurf

License

Apache 2.0