{"_id":"@agenttrustid/sdk","_rev":"2-d3dfb76aa804aa17bbcd814ae9d42c45","name":"@agenttrustid/sdk","dist-tags":{"latest":"0.4.0"},"versions":{"0.3.0":{"name":"@agenttrustid/sdk","version":"0.3.0","keywords":["ai","agents","authentication","authorization","security","mcp","a2a","opaque-tokens","agenttrust"],"author":{"name":"AgentTrust","email":"contact@agenttrust.id"},"license":"Apache-2.0","_id":"@agenttrustid/sdk@0.3.0","maintainers":[{"name":"yaima","email":"contact@agenttrust.id"}],"homepage":"https://agenttrust.id","bugs":{"url":"https://github.com/agenttrustid/sdk/issues"},"dist":{"shasum":"04b00cfeea9d09db29bea838cdf15415452f929c","tarball":"https://registry.npmjs.org/@agenttrustid/sdk/-/sdk-0.3.0.tgz","fileCount":15,"integrity":"sha512-lxjNe6UsW2YxVWqhT4qaYcEav+xGqMDsKdQsVBaOWIzteLwgVx/FhHYWIizUtiYu/f70HitZenXx1sCDUoEuFg==","signatures":[{"sig":"MEYCIQC2qiHdkEGNMP0yQb6zzf8lM6pp4b3dOJrClgntFoML1gIhAPsMj0T9nEAzepPqvvz/WL1wI6nZKfmWu8XO6xaLQfUQ","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":289779},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"gitHead":"4c9dbac26ed944d59e04c1bf1606d0e874556abf","scripts":{"lint":"tsc --noEmit","test":"jest","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"yaima","email":"contact@agenttrust.id"},"repository":{"url":"git+https://github.com/agenttrustid/sdk.git","type":"git","directory":"typescript"},"_npmVersion":"11.9.0","description":"AgentTrust ID SDK — runtime authorization, opaque agent tokens, and Guardian checks for AI agents","directories":{},"_nodeVersion":"25.6.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"ai":"^4.3.19","jest":"^29.5.0","ts-jest":"^29.1.0","typescript":"^5.0.0","@types/jest":"^29.5.0","@types/node":"^20.0.0","@langchain/core":"^0.3.80"},"peerDependencies":{"ai":">=4.0.0","@langchain/core":">=0.2.0"},"peerDependenciesMeta":{"ai":{"optional":true},"@langchain/core":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.3.0_1780860332311_0.9716069962181344","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@agenttrustid/sdk","version":"0.4.0","description":"AgentTrust ID SDK — runtime authorization, opaque agent tokens, and Guardian checks for AI agents","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"scripts":{"build":"tsc","test":"jest","lint":"tsc --noEmit","prepublishOnly":"npm run build"},"publishConfig":{"access":"public"},"keywords":["ai","agents","authentication","authorization","security","mcp","a2a","opaque-tokens","agenttrust"],"author":{"name":"AgentTrust","email":"contact@agenttrust.id"},"license":"Apache-2.0","homepage":"https://agenttrust.id","bugs":{"url":"https://github.com/agenttrustid/sdk/issues"},"repository":{"type":"git","url":"git+https://github.com/agenttrustid/sdk.git","directory":"typescript"},"devDependencies":{"@langchain/core":"^0.3.80","@types/jest":"^29.5.0","@types/node":"^20.0.0","ai":"^4.3.19","jest":"^29.5.0","ts-jest":"^29.1.0","typescript":"^5.0.0"},"peerDependencies":{"@langchain/core":">=0.2.0","ai":">=4.0.0"},"peerDependenciesMeta":{"@langchain/core":{"optional":true},"ai":{"optional":true}},"engines":{"node":">=18.0.0"},"gitHead":"23fb89bcc0cab13a6dfa076d01f0b209391b03ff","_id":"@agenttrustid/sdk@0.4.0","_nodeVersion":"25.6.1","_npmVersion":"11.9.0","dist":{"integrity":"sha512-Hqgq8MCxRZSiafreygtE1/moX+4tRd0oyGIFsn2NzLlP1FhqIgkUD8mvHNzNOAxAjSZ18yOAHy4IYTpk2e/ygQ==","shasum":"fb07c1e9099f3804f585412544ed0dd391eca619","tarball":"https://registry.npmjs.org/@agenttrustid/sdk/-/sdk-0.4.0.tgz","fileCount":15,"unpackedSize":292698,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDBKwDQ1QHCgx+Q2x5A+v3kkQiyJgTpP8Y+ElDEcv4CqwIhAJykP6sDCDytDLWaS5MUztGscx7hnj+qEDvsm7fUnWWF"}]},"_npmUser":{"name":"yaima","email":"contact@agenttrust.id"},"directories":{},"maintainers":[{"name":"yaima","email":"contact@agenttrust.id"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.4.0_1781051801231_0.42509347100852457"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-07T19:25:32.194Z","modified":"2026-06-10T00:36:41.528Z","0.3.0":"2026-06-07T19:25:32.465Z","0.4.0":"2026-06-10T00:36:41.375Z"},"bugs":{"url":"https://github.com/agenttrustid/sdk/issues"},"author":{"name":"AgentTrust","email":"contact@agenttrust.id"},"license":"Apache-2.0","homepage":"https://agenttrust.id","keywords":["ai","agents","authentication","authorization","security","mcp","a2a","opaque-tokens","agenttrust"],"repository":{"type":"git","url":"git+https://github.com/agenttrustid/sdk.git","directory":"typescript"},"description":"AgentTrust ID SDK — runtime authorization, opaque agent tokens, and Guardian checks for AI agents","maintainers":[{"name":"yaima","email":"contact@agenttrust.id"}],"readme":"# AgentTrust ID TypeScript SDK\n\nAuthentication, authorization, and runtime security for AI agents.\n\n[![npm](https://img.shields.io/npm/v/@agenttrustid/sdk?cacheSeconds=300)](https://www.npmjs.com/package/@agenttrustid/sdk)\n[![Node](https://img.shields.io/node/v/@agenttrustid/sdk?cacheSeconds=300)](https://www.npmjs.com/package/@agenttrustid/sdk)\n\n\n## Install\n\n```bash\nnpm install @agenttrustid/sdk\n```\n\nZero runtime dependencies. Uses native `fetch` (Node 18+).\n\n## Quick Start\n\n```typescript\nimport { AgentTrustClient } from '@agenttrustid/sdk';\n\nconst client = new AgentTrustClient({\n  baseUrl: 'http://localhost:8080',\n  apiKey: 'sk_live_...',\n});\n\n// Register an agent\nconst agent = await client.agents.create({\n  name: 'my-agent',\n  framework: 'langchain',\n  capabilities: ['files:read', 'web:search'],\n});\n\n// Issue a short-lived opaque token (prefix `at_`).\n// Tokens are NOT JWTs - they are random opaque strings. They have no\n// signature and cannot be validated client-side. To check a token, call\n// `client.tokens.introspect({ token })`.\nconst token = await client.tokens.issue({\n  agentId: agent.id,\n  scopes: ['files:read'],\n  ttlSeconds: 300,\n});\nconsole.log(token.token); // e.g. \"at_xK3z9...\"\n\n// Server-side validation (for tool providers receiving a token):\nconst result = await client.tokens.introspect({\n  token: token.token,\n  target: 'api.example.com',\n});\nif (result.active) {\n  // Token is valid; agentId, orgId, scopes are populated\n}\n\n// Check an action before executing\nconst result = await client.actions.check({\n  agentId: agent.id,\n  action: 'tool_call',\n  toolName: 'web_search',\n});\nconsole.log(`Allowed: ${result.allowed}, Confidence: ${result.confidence}`);\n```\n\n## AgentTrustGuard\n\nWraps action checking with automatic deny handling and telemetry buffering:\n\n```typescript\nimport { AgentTrustClient, AgentTrustGuard } from '@agenttrustid/sdk';\n\nconst client = new AgentTrustClient({ baseUrl: '...', apiKey: '...' });\nconst agent = await client.agents.create({ name: 'my-agent' });\n\nconst guard = new AgentTrustGuard(client, agent.id, {\n  blockOnDeny: true,  // throw on denied actions (default)\n  failOpen: false,    // block if Guardian unreachable (default)\n});\n\n// Check before tool execution\nconst allowed = await guard.check('web_search', 'query about AI safety');\n\n// Report tool outcome (batched, async)\nguard.report('web_search', true, 150); // tool, success, duration_ms\n\n// Flush before exit\nawait guard.flush();\n```\n\n## Environment Variables\n\n```bash\nexport AGENTTRUST_URL=http://localhost:8080\nexport AGENTTRUST_API_KEY=sk_live_...\n```\n\n```typescript\nconst client = AgentTrustClient.fromEnv();\n```\n\n## Error Handling\n\n```typescript\nimport {\n  AgentTrustError,              // Base error\n  AuthenticationError,   // Invalid API key (401)\n  AuthorizationError,    // Insufficient permissions (403)\n  TokenExpiredError,     // Token has expired\n  AgentRevokedError,     // Agent has been revoked\n  NetworkError,          // Gateway unreachable\n  ValidationError,       // Invalid request (400)\n} from '@agenttrustid/sdk';\n\ntry {\n  await client.actions.check({\n    agentId: '...',\n    action: 'tool_call',\n    toolName: 'delete_all',\n  });\n} catch (error) {\n  if (error instanceof AuthorizationError) {\n    console.log('Action denied by Guardian');\n  } else if (error instanceof TokenExpiredError) {\n    console.log('Token expired, re-issue');\n  } else if (error instanceof AgentRevokedError) {\n    console.log('Agent has been revoked');\n  } else if (error instanceof NetworkError) {\n    console.log('Gateway unreachable');\n  }\n}\n```\n\n## With Express.js\n\n```typescript\nimport express from 'express';\nimport { AgentTrustClient } from '@agenttrustid/sdk';\n\nconst client = AgentTrustClient.fromEnv();\n\nasync function introspect(req: express.Request, res: express.Response, next: express.NextFunction) {\n  const token = req.headers.authorization?.replace('Bearer ', '');\n  if (!token) return res.status(401).json({ error: 'No token' });\n\n  // Opaque `at_` tokens are validated by introspection, not signature checks.\n  const result = await client.tokens.introspect({ token, target: 'api://my-service' });\n  if (!result.active) return res.status(403).json({ error: result.reasoning });\n\n  next();\n}\n\napp.get('/protected', introspect, (req, res) => {\n  res.json({ message: 'Authorized' });\n});\n```\n\n## API Reference\n\n### AgentTrustClient\n\n```typescript\nconst client = new AgentTrustClient({ baseUrl?, authUrl?, auditUrl?, apiKey?, timeout? });\nconst client = AgentTrustClient.fromEnv();\nclient.setApiKey('sk_live_...');       // Set API key on all internal HTTP clients\nawait client.health();                  // { status, service?, version? }\n```\n\n### Agents\n\n```typescript\nawait client.agents.create({ name, framework?, orgId?, capabilities?, metadata? });\nawait client.agents.list(orgId?);\nawait client.agents.get(agentId);\nawait client.agents.revoke(agentId, reason?);  // Revoke an agent and all its credentials\n```\n\n### Tokens\n\n```typescript\nawait client.tokens.issue({ agentId, scopes, ttlSeconds?, sessionId? }, useCache?);\nawait client.tokens.introspect({ token, target?, requiredScopes? });  // POST /api/v1/agent-tokens/introspect\nawait client.tokens.revoke(tokenStr, reason?);\nclient.tokens.clearCache();  // Clear the token cache\n```\n\nTokens are opaque strings prefixed `at_` (e.g. `at_xK3z9...`). They are NOT\nJWTs and have no signature. To validate a token, call `introspect`.\n\nToken caching: `issue()` caches matching token requests internally. Cached tokens are reused\nif they have more than 30 seconds remaining. Pass `useCache: false` as the second argument to\nbypass the cache.\n\n### Actions\n\n```typescript\nconst result = await client.actions.check({\n  agentId,\n  action?,           // defaults to 'tool_call'\n  toolName,\n  toolInputSummary?, // truncated to 200 chars\n  sessionId?,\n});\n// result: { allowed, checkId?, confidence?, guardTier?, latencyMs?, reason? }\n```\n\n### Telemetry\n\n```typescript\nawait client.telemetry.report(agentId, sessionId, events);\n// Or auto-batched via AgentTrustGuard.report()\n```\n\n### AgentTrustGuard\n\n```typescript\nconst guard = new AgentTrustGuard(client, agentId, { blockOnDeny?, failOpen?, sessionId? });\nconst allowed = await guard.check(toolName, inputSummary?);\nguard.report(toolName, success?, durationMs?, errorType?);\nawait guard.flush();\n```\n\n### Agent Cards\n\n```typescript\nawait client.agentCards.generate(agentId);   // Generate a new agent card\nawait client.agentCards.get(agentId);        // Get the current agent card\nawait client.agentCards.publish(agentId);    // Publish (make publicly discoverable)\nawait client.agentCards.getPublic(agentId);  // Get a publicly published card (no auth)\n```\n\n### A2A (Agent-to-Agent)\n\n```typescript\nawait client.a2a.sendTask({ sourceAgentId, targetAgentId, message });\nawait client.a2a.getTask(taskId);\nawait client.a2a.cancelTask(taskId);\n```\n\n### MCP (Model Context Protocol)\n\n```typescript\nawait client.mcp.registerServer({ name, url, capabilities? });\nawait client.mcp.listServers();\nawait client.mcp.removeServer(serverId);\nawait client.mcp.callTool(serverId, agentId, method, params?, sessionId?);\n```\n\n### Delegations\n\n```typescript\nawait client.delegations.create({\n  fromAgentId, toAgentId, scope,\n  ttlSeconds?, restrictions?, parentDelegationId?,\n});\nawait client.delegations.list();\nawait client.delegations.revoke(delegationId);\nawait client.delegations.initSession(delegationId);\n```\n\n### Sessions\n\n```typescript\nawait client.sessions.initSession(agentId, serverId);\nawait client.sessions.getSession(sessionId);\nawait client.sessions.initApiSession(token); // or { token }\n```\n\n### Federation\n\n```typescript\nawait client.federation.registerProvider({ issuer, name, trustLevel? });\nawait client.federation.listProviders();\nawait client.federation.deleteProvider(providerId);\nawait client.federation.verifyToken({ token, issuerHint? });\nawait client.federation.initSession({ token, issuerHint? });\nawait client.federation.issueIDToken(agentId, { audience?, nonce?, ttl? });\n```\n\n### SIEM Streaming\n\n```typescript\nawait client.streaming.create({\n  name,\n  destinationType,\n  endpointUrl,\n  authToken?,\n  batchSize?,\n  flushIntervalSeconds?,\n  filterEventTypes?,\n});\nawait client.streaming.list();\nawait client.streaming.get(destinationId);\nawait client.streaming.update(destinationId, { isActive?, endpointUrl?, authToken? });\nawait client.streaming.delete(destinationId);\nawait client.streaming.deliveryLog(destinationId);\nawait client.streaming.test(destinationId);\n```\n\n## Integrations\n\nThe SDK ships two optional framework integrations. Both rely on **peer\ndependencies** that are NOT installed by default - install only what you\nuse. The corresponding SDK exports always import cleanly; the peer dep is\nonly loaded when you instantiate the integration.\n\n### LangChainJS\n\n```bash\nnpm install @langchain/core\n```\n\n```typescript\nimport { AgentTrustClient, AgentTrustLangChainHandler } from '@agenttrustid/sdk';\n\nconst client = AgentTrustClient.fromEnv();\nconst handler = new AgentTrustLangChainHandler(client, 'agent-id', { blockOnDeny: true });\nawait agentExecutor.invoke({ input: 'find me ...' }, { callbacks: [handler] });\n```\n\n`handleToolStart` checks every tool call through Fast Guard.\n`handleToolEnd` / `handleToolError` report telemetry. `handleChainEnd`\nflushes telemetry on the top-level chain.\n\n### Vercel AI SDK\n\n```bash\nnpm install ai\n```\n\n```typescript\nimport { openai } from '@ai-sdk/openai';\nimport { generateText } from 'ai';\nimport { AgentTrustClient, withAgentTrustVercelAI } from '@agenttrustid/sdk';\n\nconst client = AgentTrustClient.fromEnv();\nconst model = withAgentTrustVercelAI(openai('gpt-4o'), { client, agentId: 'agent-1' });\nconst { text } = await generateText({ model, tools, prompt: 'do the thing' });\n```\n\nThe wrapper applies `LanguageModelV1Middleware` so every tool call the model\nemits is pre-flighted by Guardian. Denied calls are stripped from the model\noutput (and surfaced as a denial line) so the agent loop continues\ngracefully instead of crashing.\n\n## Requirements\n\n- Node.js >= 18.0.0 (native `fetch`)\n- Zero required runtime dependencies\n- Optional peer deps: `@langchain/core` (LangChainJS callback), `ai` (Vercel AI SDK middleware)\n\n## License\n\nApache License 2.0 - see [LICENSE](./LICENSE) in this directory.\n","readmeFilename":"README.md"}