@keygent-ai/agentic-jwt-sdk

Zero-trust identity, intent binding, and delegation tracking for AI agents. This SDK handles all the cryptography, token lifecycle, and workflow tracking so your agents can make secure API calls with three lines of code.

Install

npm install @keygent-ai/agentic-jwt-sdk

Quick start

import { AgenticShim } from '@keygent-ai/agentic-jwt-sdk';

// 1. Initialize the Shim (once, at app startup)
const shim = new AgenticShim({
  idpBaseUrl: 'https://your-idp.fly.dev',
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  enablePoP: true,
  maxRetries: 3,
  requestTimeoutMs: 10_000,
  tokenCacheTtlSeconds: 60,
  enableWorkflowTracking: true,
});

// 2. Register your agent with the Shim
const agent = await shim.registerAgentWithIDP({
  agentName: 'Data Reader',
  signature: {
    promptTemplate: 'You are a financial data reader...',
    tools: [{
      name: 'fetch_report',
      signature: '(id: string) => Report',
      description: 'Fetch a quarterly report',
    }],
    config: { model: 'gpt-4o', temperature: 0, maxTokens: 4096 },
  },
  approvedWorkflowIds: ['your-workflow-id'],
  permissions: [{ resource: 'reports', actions: ['read'] }],
});

// 3. Make a secure API call (the Shim handles everything)
const response = await shim.secureRequest({
  agentId: agent.agentId,
  url: 'https://api.yourcompany.com/reports/q3',
  method: 'GET',
  intent: { action: 'read_report' },
  workflow: { workflowId, executionId, currentStepId },
  resourceOwner: { sub: 'user:alice', authTime: Date.now() / 1000, authMethod: 'oauth2' },
  scopes: ['reports:read'],
  audience: 'api.yourcompany.com',
});

What happens under the hood

When you call shim.secureRequest(), the Shim:

1. Verifies the agent's identity — computes a SHA-256 checksum of the agent's prompt, tools, and config
2. Requests an Intent Token from the IDP — the IDP runs a 4-part security checkpoint (registration, checksum, workflow authorization, delegation chain)
3. Creates a PoP proof — signs the HTTP request with the agent's ephemeral private key so stolen tokens are useless
4. Injects agentic headers — Authorization, DPoP, X-Shim-Checksum, X-Agent-Id, X-Workflow-Execution-Id
5. Sends the request to the target API
6. Returns the response to your agent

If the agent's prompt has been tampered with (prompt injection), the checksum fails at step 2 and the IDP refuses the token. The agent never reaches the API.

Workflow tracking

Track multi-step agent workflows with delegation chains:

// Start a workflow execution
const execution = shim.tracker.startExecution({
  workflowId: 'vuln-scan',
  clientId: 'your-client-id',
  initiatingAgentId: supervisorId,
  firstStepId: 'step-1',
  resourceOwnerSub: 'user:alice',
});

// Record delegation: Supervisor → Worker
shim.tracker.recordDelegation(execution.executionId, {
  fromAgentId: supervisorId,
  toAgentId: workerId,
  delegatedAction: 'scan_repository',
  delegatedAt: new Date().toISOString(),
  delegatorChecksum: supervisorChecksum,
});

// Advance through steps
shim.tracker.advanceStep(execution.executionId, completedStep, nextStepId);

// Complete
shim.tracker.completeExecution(execution.executionId);

Token caching

The Shim caches intent tokens by agent + action + resource. If the same agent requests the same action within the token's TTL (5 minutes), the cached token is reused without hitting the IDP. This is safe because the checksum is validated at mint time — if the agent's prompt changes, the next mint will fail.

API Reference

AgenticShim

| Method | Description | |--------|-------------| | registerAgent(params) | Register an agent locally with the Shim | | registerAgentWithIDP(params) | Register an agent with both the Shim and the IDP | | registerWorkflowWithIDP(params) | Register a workflow with the IDP | | mintIntentToken(params) | Request an Intent Token from the IDP | | secureRequest(params) | Full pipeline: mint token → PoP proof → headers → send request | | verifyAgentIntegrity(agentId, signature) | Re-verify an agent's checksum at runtime | | getShimChecksum() | Get the Shim library's own integrity hash | | getStats() | Get current Shim state (cached tokens, active executions) |

WorkflowTracker

| Method | Description | |--------|-------------| | startExecution(params) | Begin tracking a new workflow execution | | recordDelegation(executionId, link) | Record agent-to-agent delegation | | advanceStep(executionId, completed, nextStepId) | Move to the next workflow step | | completeExecution(executionId) | Mark workflow as completed | | failExecution(executionId, reason) | Mark workflow as failed | | getDelegationChain(executionId) | Get the current chain of command |

License

MIT