aap-agentkit

AAP SDK for signing assertions and calling APIs. Use this on the client/agent side to generate Ed25519 keypairs, sign AAP assertions, and create X-AAP-Assertion / X-AAP-Signature headers for outgoing requests.

Install

npm install aap-agentkit

Quick Start

const { generateKeyPair, createSignedHeaders } = require('aap-agentkit');

// Generate Ed25519 keypair and agentId
const kp = generateKeyPair();
console.log(kp.agentId);         // e.g. agt_MCowBQYDK2Vw
console.log(kp.publicKeyBase64); // for registration with your registry

// Create signed headers for an API call
const { headers, assertion } = createSignedHeaders({
  url: 'https://api.example.com/workorders',
  method: 'POST',
  body: { title: 'Fix leak' },
  intent: 'workorders.create',
  audience: 'https://api.example.com',
  agentId: kp.agentId,
  privateKey: kp.privateKey,
});

// Use headers in fetch/axios
const res = await fetch('https://api.example.com/workorders', {
  method: 'POST',
  headers: { ...headers, 'Content-Type': 'application/json' },
  body: JSON.stringify({ title: 'Fix leak' }),
});

API

| Function | Description | |----------|-------------| | generateKeyPair() | Returns { publicKey, privateKey, publicKeyBase64, agentId } | | createSignedHeaders(options) | Returns { headers, assertion } with X-AAP-Assertion and X-AAP-Signature | | signAssertion(assertion, privateKey) | Sign an assertion object; returns base64url signature | | register(options) | Register agent with registry (agentName, publicKeyBase64, requestedAudiences, requestedIntents) |

Principal-Actor Model (v0.1)

To act on behalf of a user, pass subject and optionally chain:

createSignedHeaders({
  url: '...',
  intent: 'workorders.create',
  audience: 'https://api.example.com',
  agentId: kp.agentId,
  privateKey: kp.privateKey,
  subject: 'usr_789',  // on-behalf-of user
  chain: [{ t: 'user', id: 'usr_789' }, { t: 'agent', id: kp.agentId }],
});

Server-Side

Use aap-guard on your Express API to verify these assertions.