npm package: @kraken-identity/sdk
Description: Identity & Grip for AI Agents — Auth0 for the agentic era
Author: Kraken
Latest version: 0.1.0

# @kraken-id/sdk

**Identity & Grip for AI Agents.**

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

```bash
npm install @kraken-id/sdk
```

## Quickstart

```typescript
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

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

```typescript
const agent = KrakenAgent.fromEnv();
```

## LangChain Integration

```typescript
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

```typescript
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

```typescript
// 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