A2A Protocol Bridge (TypeScript)

Inject Grantex grant tokens into Google A2A agent-to-agent communication

Overview

The @grantex/a2a package bridges the Google A2A protocol with Grantex delegated authorization, enabling secure agent-to-agent communication with grant token authentication.

Installation

npm install @grantex/a2a

Client — Calling A2A Agents

Send tasks to remote A2A agents with automatic grant token auth:

import { A2AGrantexClient } from '@grantex/a2a';

const client = new A2AGrantexClient({
  agentUrl: 'https://agent.example.com/a2a',
  grantToken: 'eyJ...', // Grantex grant token
});

// Send a task
const task = await client.sendTask({
  message: { role: 'user', parts: [{ type: 'text', text: 'Search for flights' }] },
});

// Check status
const status = await client.getTask({ id: task.id });

// Cancel
await client.cancelTask({ id: task.id });

The TypeScript client’s synchronous token parsing is an unverified convenience check only. It must never be used as the remote authorization boundary. The A2A server must run the JWKS-backed middleware below before accepting or executing the JSON-RPC request.

Server Middleware — Validating Incoming Tokens

Validate Grantex grant tokens on incoming A2A requests:

import { createA2AAuthMiddleware } from '@grantex/a2a';

const authMiddleware = createA2AAuthMiddleware({
  jwksUri: 'https://grantex.dev/.well-known/jwks.json',
  requiredScopes: ['read', 'write'],
});

// In your A2A handler:
const grant = await authMiddleware(request);
console.log(grant.principalId, grant.scopes);

Agent Card Builder

Generate A2A-compliant agent cards with Grantex auth configuration:

import { buildGrantexAgentCard } from '@grantex/a2a';

const card = buildGrantexAgentCard({
  name: 'Travel Agent',
  description: 'Books flights and hotels',
  url: 'https://travel-agent.example.com/a2a',
  jwksUri: 'https://grantex.dev/.well-known/jwks.json',
  issuer: 'https://grantex.dev',
  requiredScopes: ['travel:read', 'travel:write'],
  delegationAllowed: true,
});

JWT Utilities

Decode grant tokens offline (without verification):

import { decodeJwtPayload, isTokenExpired } from '@grantex/a2a';

const payload = decodeJwtPayload(grantToken);
console.log(payload.sub, payload.scp, payload.bdg);

if (isTokenExpired(payload)) {
  // Token needs refresh
}

Decoded payloads are untrusted display/debug data until separately verified. Do not make an authorization, routing, billing, or audit-attribution decision from decodeJwtPayload() output.

Ownership

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