Agent Id Js

@开放代理id/sdk

JavaScript/TypeScript SDK 打开代理ID --在链上注册、签名和验证AI代理身份。

安装

npm install @open-agent-id/sdk

需要Node.js>=18。

快速开始

最常见的用例是向出站请求添加代理身份验证标头：

import { signAgentAuth } from "@open-agent-id/sdk";

const headers = signAgentAuth(
  "did:oaid:base:0x1234567890abcdef1234567890abcdef12345678",
  privateKey, // Uint8Array (32 bytes)
);
// Returns object with:
//   "X-Agent-DID":       "did:oaid:base:0x1234..."
//   "X-Agent-Timestamp": "1708123456"
//   "X-Agent-Nonce":     "a3f1b2c4d5e6f7089012abcd"
//   "X-Agent-Signature": ""

const res = await fetch("https://api.example.com/v1/tasks", {
  method: "POST",
  headers,
  body: JSON.stringify({ task: "search" }),
});

注册表客户端

import { RegistryClient } from "@open-agent-id/sdk";

const client = new RegistryClient(); // defaults to https://api.openagentid.org

所有方法

钱包身份验证流程

// 1. Request challenge
const { challengeId, challengeText } = await client.requestChallenge(walletAddress);

// 2. Sign the challenge text with your wallet (e.g. via ethers.js)
// const walletSignature = await wallet.signMessage(challengeText);

// 3. Verify and get auth token
const token = await client.verifyWallet(walletAddress, challengeId, walletSignature);

注册代理

const agent = await client.registerAgent(token, {
  name: "my-agent",
  publicKey: base64urlPublicKey,
  capabilities: ["search", "summarize"],
});

查找并列出代理商

const info = await client.getAgent("did:oaid:base:0x1234...");
const { agents, nextCursor } = await client.listAgents(token);

管理代理

await client.updateAgent(did, { token }, { name: "new-name" });
await client.rotateKey(did, token, newPublicKey);
await client.revokeAgent(did, token);
await client.deployWallet(did, token);

信用评分

const credit = await client.getCredit("did:oaid:base:0x1234567890abcdef1234567890abcdef12345678");
console.log(credit.credit_score); // 300
console.log(credit.level);       // "verified"

HTTP签名

签署HTTP请求

import { signHttpRequest, verifyHttpSignature } from "@open-agent-id/sdk";

const headers = await signHttpRequest(
  privateKey,          // Uint8Array (32 bytes)
  "POST",
  "https://api.example.com/v1/tasks",
  new TextEncoder().encode('{"task":"search"}'),
);
// headers = {
//   "X-Agent-Timestamp": "1708123456",
//   "X-Agent-Nonce": "a3f1b2c4d5e6f7089012abcd",
//   "X-Agent-Signature": ""
// }

验证HTTP签名

const valid = verifyHttpSignature(
  publicKey,           // Uint8Array (32 bytes)
  "POST",
  "https://api.example.com/v1/tasks",
  bodyBytes,           // Uint8Array | null
  timestamp,           // number (unix seconds)
  nonce,               // string
  signature,           // Uint8Array
);

使用签名守护进程

import { Signer, Agent } from "@open-agent-id/sdk";

const signer = await Signer.connect("/tmp/oaid-signer.sock");
const agent = new Agent({
  keyId: "default",
  signer,
  did: "did:oaid:base:0x1234567890abcdef1234567890abcdef12345678",
});

const res = await agent.http.post("https://api.example.com/v1/tasks", {
  task: "search",
});

消息签名

签署P2P消息

import { signMessage, verifyMessageSignature } from "@open-agent-id/sdk";

const signature = await signMessage(
  privateKey,
  "task.request",                          // message type
  "msg-001",                               // message ID
  "did:oaid:base:0xaaaa...aaaa",           // from DID
  ["did:oaid:base:0xbbbb...bbbb"],         // to DIDs
  null,                                    // ref
  null,                                    // timestamp (auto)
  null,                                    // expiresAt
  { task: "summarize", url: "https://..." }, // body
);

E2E加密

import { encryptFor, decryptFrom } from "@open-agent-id/sdk";

// Encrypt for another agent (NaCl box: X25519-XSalsa20-Poly1305)
const ciphertext = encryptFor(plaintext, recipientEd25519Pub, senderEd25519Priv);

// Decrypt
const decrypted = decryptFrom(ciphertext, senderEd25519Pub, recipientEd25519Priv);

DID实用程序

import { validateDid, parseDid, formatDid } from "@open-agent-id/sdk";

validateDid("did:oaid:base:0x1234...abcd");  // true

parseDid("did:oaid:base:0x1234...abcd");
// { method: "oaid", chain: "base", agentAddress: "0x1234...abcd" }

formatDid("base", "0x1234...abcd");
// "did:oaid:base:0x1234...abcd"

规范助手

import { canonicalUrl, canonicalJson } from "@open-agent-id/sdk";

canonicalUrl("https://API.example.com/path?b=2&a=1");
// "https://api.example.com/path?a=1&b=2"

canonicalJson({ z: 1, a: 2 });
// '{"a":2,"z":1}'

测试

npm install
npm run build   # compile TypeScript
npm test        # run tests with vitest

许可证

阿帕奇-2.0