@kraken-id/sdk

Identity & Grip for AI Agents.

Zero runtime dependencies. Node.js 18+, Deno, Bun, Cloudflare Workers, Vercel Edge.

npm install @kraken-id/sdk

Quickstart

import { KrakenAgent } from "@kraken-id/sdk";

// Register once, store the credentials
const agent = await KrakenAgent.register({
  name: "my-agent",
  scopes: ["calendar:read", "email:send"],
  org: "acme",
  apiUrl: "http://localhost:8080",
});
// [kraken] Agent registered: 8deaa3b9-...
// [kraken] Secret (save this — shown once): 8f96c558...

// From stored credentials
const agent = new KrakenAgent("agent_id", "secret", {
  apiUrl: "http://localhost:8080",
});

// Auth headers — auto-refreshes before expiry
const resp = await fetch(url, {
  headers: await agent.authHeaders(),
});

From environment variables

export KRAKEN_AGENT_ID=8deaa3b9-c8e9-43e5-b776-ee4cbd505b8b
export KRAKEN_SECRET=8f96c558...
export KRAKEN_API_URL=https://api.getkraken.com

const agent = KrakenAgent.fromEnv();

LangChain Integration

import { KrakenAgent } from "@kraken-id/sdk";
import { krakenTool } from "@kraken-id/sdk/langchain";
import { tool } from "@langchain/core/tools";
import { z } from "zod";

const agent = KrakenAgent.fromEnv();

const calendarTool = krakenTool(agent, {
  requiredScopes: ["calendar:read"],
  tool: tool(
    async ({ date }) => `Events on ${date}: standup at 9am`,
    {
      name: "read_calendar",
      description: "Read calendar events for a date",
      schema: z.object({ date: z.string() }),
    }
  ),
});

// If agent is revoked, next tool call throws KrakenRevocationError

Vercel AI SDK Integration

import { KrakenAgent } from "@kraken-id/sdk";
import { krakenTool } from "@kraken-id/sdk/vercel-ai";
import { generateText, tool } from "ai";
import { z } from "zod";

const agent = KrakenAgent.fromEnv();

const result = await generateText({
  model,
  tools: {
    readCalendar: krakenTool(agent, {
      requiredScopes: ["calendar:read"],
      tool: tool({
        description: "Read calendar events",
        parameters: z.object({ date: z.string() }),
        execute: async ({ date }) => `Events on ${date}`,
      }),
    }),
  },
  prompt: "What's on my calendar today?",
});

Token lifecycle

• Ed25519-signed JWTs, 15-minute TTL
• getToken() auto-refreshes 60s before expiry (background setTimeout)
• Revocation propagates globally in <100ms via Redis pub/sub
• destroy() cancels the refresh timer (useful in tests and short-lived processes)

API

// Construction
new KrakenAgent(agentId, secret, options?)
KrakenAgent.register(options)          // async — hits the API
KrakenAgent.fromEnv()                  // sync — reads process.env

// Token operations
agent.issueToken(scopes?)              // fresh token, always hits network
agent.getToken(scopes?)               // cached, auto-refresh
agent.authHeaders(scopes?)            // { Authorization: "Bearer eyJ..." }
agent.validate(token?)                // validate against server

// Utilities
agent.withScope(...scopes)            // new agent with different scopes
agent.destroy()                       // cancel refresh timer

License

Apache 2.0