@agentpki/sdk — TypeScript SDK

Cryptographic identity for AI agents. PASETO v4 passports, Ed25519 signing, RFC 9421 HTTP Message Signatures.

• Spec: https://agentpki.dev/spec/v0.1
• Live demo: agentpki.dev (click "Try it live")
• Companion Python SDK: agentpki

Install

npm install @agentpki/sdk
# or
pnpm add @agentpki/sdk
# or
yarn add @agentpki/sdk

Works in browsers, Cloudflare Workers, Bun, Deno, and Node 18+. Zero runtime dependencies beyond @noble/curves (audited zero-dep crypto).

Quickstart

import {
  generateKeyPair,
  signPassport,
  verifyPassport,
} from '@agentpki/sdk';

const { privateKey, publicKey } = generateKeyPair();
const now = Math.floor(Date.now() / 1000);

const token = signPassport(
  {
    v: 1,
    iss: 'example.com',
    sub: 'agent:example.com/research-bot-v1',
    iat: now,
    exp: now + 3600,
    jti: 'a'.repeat(32),
    tier: 1,
    scope: ['read:articles', 'read:public-data'],
  },
  { privateKey, kid: 'example-2026-q2' },
);

const result = verifyPassport(token, publicKey);
console.log(result.valid);                    // true
console.log(result.payload?.sub);             // "agent:example.com/research-bot-v1"

Make signed HTTP requests

The AgentPKI client wraps fetch and attaches a passport (and optional RFC 9421 signature) to every outbound request.

import { AgentPKI } from '@agentpki/sdk';

const client = new AgentPKI({
  passportProvider: async () => ({
    token: await fetchFreshPassport(),   // your code
    cnfPrivateKey: signingKey,           // 32-byte Ed25519 seed
  }),
  mode: 'B',                             // RFC 9421 Mode B (recommended)
});

const res = await client.fetch('https://example.com/api/article/123');

Verify on the server side

import {
  resolveIssuerDirectory,
  selectKey,
  decodePublicKey,
  verifyPassport,
  parsePassport,
} from '@agentpki/sdk';

const { footer } = parsePassport(token);
const directory  = await resolveIssuerDirectory('anthropic.com');
const selection  = selectKey(directory, footer?.kid);
if (selection.status !== 'current') throw new Error('key unavailable');
const pubKey     = decodePublicKey(selection.key.pubkey);
const result     = verifyPassport(token, pubKey);

if (result.valid) {
  // result.payload is now trusted: iss, sub, scope, tier, etc.
}

API surface

Passport

• signPassport(payload, opts) → string (PASETO v4.public token)
• parsePassport(token) → { payload, footer? } (NOT authenticated; for inspection only)
• verifyPassport(token, publicKey, opts?) → VerifyResult

Directory

• resolveIssuerDirectory(issuer, opts?) → Promise<IssuerDirectory>
• selectKey(doc, kid, now?) → KeySelection
• decodePublicKey(pubkeyB64) → Uint8Array

HTTP Message Signatures (RFC 9421)

• buildSignatureBase(components, meta) → { base, signatureInput }
• signRequest(components, meta, privateKey) → { signatureInput, signature }
• verifyRequestSignature(components, meta, publicKey, signatureB64) → boolean

Keys

• generateKeyPair() → { privateKey, publicKey } (32-byte each)
• getPublicKey(privateKey) → Uint8Array
• publicKeyToSpki(publicKey) → Uint8Array (RFC 8410 DER envelope)
• publicKeyToSpkiBase64(publicKey) → string

Client

• new AgentPKI(opts) → instance with .fetch(input, init?)

Framework integrations

• Vercel AI SDK — drop-in identity for agents built with ai + @ai-sdk/openai. Three runnable examples (research, commerce, multi-agent).
• Mastra — @mastra/core integration. Research + multi-agent examples.
• LangChain JS — @langchain/langgraph ReAct agents. Research + multi-agent examples.
• Cloudflare Agents SDK — agents package, Durable Object–backed. Stateful agent with signed /fetch endpoint.

Round-trip sanity check

git clone https://github.com/agentpki/sdk-typescript
cd sdk-typescript
pnpm install
pnpm example

Should print 21/21 ✓ — covering keygen, signing, parsing, verify, tamper detection, expiry enforcement, lifetime cap, and RFC 9421 round-trip with body-tamper detection.

License

MIT. Spec it implements is Apache 2.0.