@agentidcard/sdk 1.0.0

package/README.md

@@ -0,0 +1,151 @@
+# @agentidcard/sdk
+
+Official JavaScript SDK for Agent ID Card.
+
+Works in Node.js 18+ and modern browsers (uses WebCrypto API).
+
+## Install
+
+```bash
+npm install @agentidcard/sdk
+```
+
+## Quick start
+
+```js
+import { AilClient, verifyOffline } from "@agentidcard/sdk";
+
+const client = new AilClient({ serverUrl: "https://api.agentidcard.org" });
+
+// 1. Register owner
+const owner = await client.registerOwner({ email: "you@example.com", org: "your_org" });
+
+// 2. Verify email with the OTP sent to the owner's inbox
+await client.verifyEmail({ owner_key_id: owner.owner_key_id, otp: "123456" });
+
+// 3. Register agent (SDK handles signing automatically)
+const agent = await client.registerAgent({
+  owner_key_id: owner.owner_key_id,
+  private_key_jwk: owner.private_key_jwk,
+  payload: {
+    display_name: "MyAgent",
+    role: "assistant",
+    scope: {
+      network: "none",
+      secrets: "none",
+      write_access: false,
+      approval_policy: {
+        irreversible_actions: "human_required",
+        external_posting: "human_required",
+        destructive_file_ops: "human_required",
+      },
+    },
+  },
+});
+
+console.log(agent.ail_id); // AIL-2026-00001
+
+// 4. Verify credential (online)
+const result = await client.verify(agent.credential.token);
+console.log(result.valid, result.display_name);
+
+// 5. Verify offline (no server call)
+const keys = await client.getPublicKeys();
+const offline = await verifyOffline(agent.credential.token, keys.keys[0]);
+```
+
+## Session-based registration
+
+```js
+const login = await client.loginOwner({ email: "you@example.com" });
+
+const session = await client.verifyLogin({
+  owner_key_id: login.owner_key_id,
+  otp: "123456",
+});
+
+const agent = await client.registerAgentWithSession({
+  session_token: session.session_token,
+  payload: {
+    display_name: "OpsAgent",
+    role: "automation",
+    provider: "openai",
+    model: "gpt-5.4",
+    scope: {
+      network: "restricted",
+      secrets: "none",
+      write_access: false,
+      approval_policy: {
+        irreversible_actions: "human_required",
+        external_posting: "human_required",
+        destructive_file_ops: "human_required",
+      },
+    },
+  },
+});
+```
+
+## Build a v1 envelope
+
+```js
+import { buildEnvelope } from "@agentidcard/sdk";
+
+const envelope = buildEnvelope({
+  ail_id: agent.ail_id,
+  credential: agent.credential,
+  signal_glyph: agent.signal_glyph,
+  behavior_fingerprint: agent.behavior_fingerprint,
+  agent: {
+    id: "agent_myagent_01",
+    provider: "anthropic",
+    model: "claude-sonnet-4-6",
+    runtime: "claude_code",
+  },
+  owner: {
+    key_id: owner.owner_key_id,
+    org: "your_org",
+    email_hash: "sha256:...",
+  },
+  scope: agent_scope,
+  delegation: { mode: "direct", chain_depth: 0 },
+  runtime: {
+    session_id: "sess_001",
+    run_id: "run_001",
+    surface: "cli",
+    host: "localhost",
+  },
+});
+```
+
+## Revoke an agent
+
+```js
+await client.revokeAgent({
+  ail_id: agent.ail_id,
+  owner_key_id: owner.owner_key_id,
+  private_key_jwk: owner.private_key_jwk,
+});
+```
+
+## API
+
+### `new AilClient({ serverUrl })`
+
+### `client.registerOwner({ email, org? })`
+### `client.verifyEmail({ owner_key_id, otp })`
+### `client.loginOwner({ email })`
+### `client.verifyLogin({ owner_key_id, otp })`
+### `client.registerAgent({ owner_key_id, private_key_jwk, payload })`
+### `client.registerAgentWithSession({ session_token, payload })`
+### `client.revokeAgent({ ail_id, owner_key_id, private_key_jwk })`
+### `client.verify(token)` - online verification
+### `client.verifyOffline(token)` - offline (fetches JWKS once, caches)
+### `client.getPublicKeys()` - returns JWKS
+
+### `verifyOffline(token, publicKeyJwk)` - standalone offline verification
+
+### `buildEnvelope(options)` - assemble a v1 envelope
+
+### `generateOwnerKeypair()` - generate EC P-256 keypair (returns `{ public_key_jwk, private_key_jwk }`)
+### `signPayload(payload, private_key_jwk)` - sign a payload, returns base64url
+### `canonicalJson(obj)` - canonical JSON serialization

package/index.d.ts

@@ -0,0 +1,122 @@
+export type Jwk = Record<string, unknown>;
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+export interface OwnerRegistrationResponse {
+  owner_key_id: string;
+  public_key_jwk: Jwk;
+  private_key_jwk: Jwk;
+  message?: string;
+}
+
+export interface LoginResponse {
+  owner_key_id: string;
+  message?: string;
+}
+
+export interface VerifyLoginResponse {
+  authenticated: boolean;
+  session_token: string;
+  owner: Record<string, unknown>;
+  agents: Array<Record<string, unknown>>;
+}
+
+export interface AgentRegistrationOptions {
+  display_name: string;
+  role: string;
+  provider?: string | null;
+  model?: string | null;
+  scope: Record<string, unknown>;
+  wallet_address?: string;
+  plan?: string;
+}
+
+export interface CredentialResponse {
+  ail_id: string;
+  credential: Record<string, unknown>;
+  signal_glyph: Record<string, unknown>;
+  behavior_fingerprint: Record<string, unknown>;
+  nft_image_url?: string;
+  nft_metadata_url?: string;
+  nft?: {
+    token_id: string;
+    tx_hash?: string;
+  };
+}
+
+export interface OfflineVerificationResult {
+  valid: boolean;
+  ail_id?: string;
+  display_name?: string;
+  role?: string;
+  owner_org?: string;
+  issued?: string;
+  expires?: string;
+  reason?: string;
+}
+
+export interface AilClientOptions {
+  serverUrl?: string;
+}
+
+export interface ReputationQueryParams {
+  source?: string;
+  season?: number;
+  limit?: number;
+  dimension?: string;
+}
+
+export declare class AilClient {
+  constructor(options?: AilClientOptions);
+  registerOwner(options: { email: string; org?: string }): Promise<OwnerRegistrationResponse>;
+  verifyEmail(options: { owner_key_id: string; otp: string }): Promise<Record<string, unknown>>;
+  loginOwner(options: { email: string }): Promise<LoginResponse>;
+  verifyLogin(options: { owner_key_id: string; otp: string }): Promise<VerifyLoginResponse>;
+  registerAgent(options: {
+    owner_key_id: string;
+    private_key_jwk: Jwk;
+    payload: AgentRegistrationOptions;
+  }): Promise<CredentialResponse>;
+  registerAgentWithSession(options: {
+    session_token: string;
+    payload: AgentRegistrationOptions;
+  }): Promise<CredentialResponse>;
+  revokeAgent(options: {
+    ail_id: string;
+    owner_key_id: string;
+    private_key_jwk: Jwk;
+  }): Promise<Record<string, unknown>>;
+  verify(token: string): Promise<Record<string, unknown>>;
+  verifyOffline(token: string): Promise<OfflineVerificationResult>;
+  getPublicKeys(): Promise<Record<string, unknown>>;
+  getReputation(ailId: string): Promise<Record<string, unknown>>;
+  getReputationHistory(ailId: string, params?: ReputationQueryParams): Promise<Record<string, unknown>>;
+  compareAgents(ailId: string, otherAilId: string): Promise<Record<string, unknown>>;
+  getLeaderboard(params?: ReputationQueryParams): Promise<Record<string, unknown>>;
+  getBadges(ailId: string): Promise<Record<string, unknown>>;
+  getSeasonReport(ailId: string, season: number, params?: { source?: string }): Promise<Record<string, unknown>>;
+  awardBadge(options: {
+    source_name: string;
+    agent_id: string;
+    badge_id: string;
+    private_key_jwk: Jwk;
+    merkle_proof?: string | null;
+  }): Promise<Record<string, unknown>>;
+}
+
+export declare function verifyOffline(token: string, publicKeyJwk: Jwk): Promise<OfflineVerificationResult>;
+export declare function buildEnvelope(options: Record<string, unknown>): Record<string, unknown>;
+export declare function generateOwnerKeypair(): Promise<{ public_key_jwk: Jwk; private_key_jwk: Jwk }>;
+export declare function signPayload(payload: JsonValue | Record<string, unknown>, privateKeyJwk: Jwk): Promise<string>;
+export declare function verifyOwnerSignature(
+  payload: JsonValue | Record<string, unknown>,
+  signatureB64url: string,
+  publicKeyJwk: Jwk
+): Promise<boolean>;
+export declare function canonicalJson(obj: JsonValue | Record<string, unknown>): string;
+export declare function sha256hexAsync(data: string): Promise<string>;

package/index.mjs

@@ -0,0 +1,9 @@
+export { AilClient, verifyOffline } from "./src/client.mjs";
+export { buildEnvelope } from "./src/envelope.mjs";
+export {
+  generateOwnerKeypair,
+  signPayload,
+  verifyOwnerSignature,
+  canonicalJson,
+  sha256hexAsync,
+} from "./src/crypto.mjs";

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@agentidcard/sdk",
+  "version": "1.0.0",
+  "description": "Official JavaScript SDK for Agent ID Card - AI agent identity credentials",
+  "type": "module",
+  "main": "./index.mjs",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.mjs"
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "index.d.ts",
+    "index.mjs",
+    "src/",
+    "README.md"
+  ],
+  "keywords": ["agent-identity", "agentidcard", "ail", "credential", "jwt", "nft", "erc721"],
+  "license": "MIT",
+  "author": "Agent ID Card <contact@agentidcard.org>",
+  "homepage": "https://agentidcard.org",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sinmb79/Agent-Identity-Layer.git",
+    "directory": "sdk/js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "jose": "^5.2.3"
+  }
+}

package/src/client.mjs

@@ -0,0 +1,211 @@
+import { signPayload } from "./crypto.mjs";
+import { jwtVerify, importJWK } from "jose";
+
+/**
+ * AilClient communicates with the Agent ID Card issuance server.
+ *
+ * Usage:
+ *   const client = new AilClient({ serverUrl: "https://api.agentidcard.org" });
+ */
+export class AilClient {
+  constructor({ serverUrl = "https://api.agentidcard.org" } = {}) {
+    this.serverUrl = serverUrl.replace(/\/$/, "");
+  }
+
+  #withQuery(path, params = {}) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+      if (value === undefined || value === null || value === "") continue;
+      search.set(key, String(value));
+    }
+    const query = search.toString();
+    return query ? `${path}?${query}` : path;
+  }
+
+  async #post(path, body) {
+    const res = await fetch(`${this.serverUrl}${path}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    const data = await res.json();
+    if (!res.ok) {
+      const err = new Error(data.message ?? data.error ?? `HTTP ${res.status}`);
+      err.code = data.error;
+      err.status = res.status;
+      throw err;
+    }
+    return data;
+  }
+
+  async #get(path) {
+    const res = await fetch(`${this.serverUrl}${path}`);
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    return res.json();
+  }
+
+  // -------------------------------------------------------------------------
+  // Owner registration and login
+  // -------------------------------------------------------------------------
+
+  /**
+   * Register a new owner and receive their EC P-256 keypair.
+   * Store private_key_jwk securely - it is not kept by the server.
+   */
+  async registerOwner({ email, org }) {
+    return this.#post("/owners/register", { email, org });
+  }
+
+  /**
+   * Verify owner email with the OTP received after registration.
+   */
+  async verifyEmail({ owner_key_id, otp }) {
+    return this.#post("/owners/verify-email", { owner_key_id, otp });
+  }
+
+  /**
+   * Request a login OTP for an existing verified owner.
+   */
+  async loginOwner({ email }) {
+    return this.#post("/owners/login", { email });
+  }
+
+  /**
+   * Verify a login OTP and receive a session token for session-based registration.
+   */
+  async verifyLogin({ owner_key_id, otp }) {
+    return this.#post("/owners/verify-login", { owner_key_id, otp });
+  }
+
+  // -------------------------------------------------------------------------
+  // Agent registration
+  // -------------------------------------------------------------------------
+
+  /**
+   * Register an agent and receive a signed v1 credential.
+   *
+   * The SDK handles signing the payload with the owner's private key automatically.
+   */
+  async registerAgent({ owner_key_id, private_key_jwk, payload }) {
+    const owner_signature = await signPayload(payload, private_key_jwk);
+    return this.#post("/agents/register", { owner_key_id, payload, owner_signature });
+  }
+
+  /**
+   * Register an agent using a session token from verifyLogin.
+   */
+  async registerAgentWithSession({ session_token, payload }) {
+    return this.#post("/agents/register-session", { session_token, payload });
+  }
+
+  // -------------------------------------------------------------------------
+  // Revocation
+  // -------------------------------------------------------------------------
+
+  /**
+   * Revoke an agent credential.
+   * The SDK handles signing the revoke payload automatically.
+   */
+  async revokeAgent({ ail_id, owner_key_id, private_key_jwk }) {
+    const revokePayload = { action: "revoke", ail_id };
+    const owner_signature = await signPayload(revokePayload, private_key_jwk);
+    const res = await fetch(`${this.serverUrl}/agents/${ail_id}/revoke`, {
+      method: "DELETE",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ owner_key_id, owner_signature }),
+    });
+    const data = await res.json();
+    if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);
+    return data;
+  }
+
+  // -------------------------------------------------------------------------
+  // Verification
+  // -------------------------------------------------------------------------
+
+  /**
+   * Verify a credential online (calls the server).
+   */
+  async verify(token) {
+    return this.#post("/verify", { token });
+  }
+
+  /**
+   * Verify a credential offline using the server's public key.
+   * Fetches the JWKS once and caches it.
+   */
+  async verifyOffline(token) {
+    if (!this._cachedJwks) {
+      this._cachedJwks = await this.#get("/keys");
+    }
+    return verifyOffline(token, this._cachedJwks.keys[0]);
+  }
+
+  /**
+   * Fetch the Agent ID Card JWKS (public keys for offline verification).
+   */
+  async getPublicKeys() {
+    return this.#get("/keys");
+  }
+
+  // -------------------------------------------------------------------------
+  // Reputation and achievements
+  // -------------------------------------------------------------------------
+
+  async getReputation(ailId) {
+    return this.#get(`/reputation/${encodeURIComponent(ailId)}`);
+  }
+
+  async getReputationHistory(ailId, params = {}) {
+    return this.#get(this.#withQuery(`/reputation/${encodeURIComponent(ailId)}/history`, params));
+  }
+
+  async compareAgents(ailId, otherAilId) {
+    return this.#get(this.#withQuery(`/reputation/${encodeURIComponent(ailId)}/compare`, { with: otherAilId }));
+  }
+
+  async getLeaderboard(params = {}) {
+    return this.#get(this.#withQuery("/reputation/leaderboard", params));
+  }
+
+  async getBadges(ailId) {
+    return this.#get(`/reputation/${encodeURIComponent(ailId)}/badges`);
+  }
+
+  async getSeasonReport(ailId, season, params = {}) {
+    return this.#get(
+      this.#withQuery(`/reputation/${encodeURIComponent(ailId)}/season/${season}`, params)
+    );
+  }
+
+  async awardBadge({ source_name, agent_id, badge_id, private_key_jwk, merkle_proof = null }) {
+    const payload = { source_name, agent_id, badge_id, merkle_proof };
+    const signature = await signPayload(payload, private_key_jwk);
+    return this.#post("/reputation/badge", { ...payload, signature });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Standalone offline verification (no server required)
+// Provide the public key JWK from GET /keys
+// ---------------------------------------------------------------------------
+export async function verifyOffline(token, publicKeyJwk) {
+  try {
+    const publicKey = await importJWK(publicKeyJwk, "ES256");
+    const { payload } = await jwtVerify(token, publicKey, {
+      issuer: ["agentidcard.org", "22blabs.ai"],
+      algorithms: ["ES256"],
+    });
+    return {
+      valid: true,
+      ail_id: payload.ail_id,
+      display_name: payload.display_name,
+      role: payload.role,
+      owner_org: payload.owner_org,
+      issued: new Date(payload.iat * 1000).toISOString(),
+      expires: new Date(payload.exp * 1000).toISOString(),
+    };
+  } catch (err) {
+    return { valid: false, reason: err.message };
+  }
+}

package/src/crypto.mjs

@@ -0,0 +1,105 @@
+/**
+ * Crypto utilities for the AIL JS SDK.
+ * Uses the WebCrypto API (globalThis.crypto.subtle) — works in Node.js 18+
+ * and all modern browsers.
+ */
+
+import { createHash } from "node:crypto";
+
+// ---------------------------------------------------------------------------
+// Canonical JSON
+// ---------------------------------------------------------------------------
+export function canonicalJson(obj) {
+  return JSON.stringify(obj, (key, value) => {
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+      return Object.fromEntries(
+        Object.entries(value).sort(([a], [b]) => a.localeCompare(b))
+      );
+    }
+    return value;
+  });
+}
+
+// ---------------------------------------------------------------------------
+// SHA-256 hex
+// ---------------------------------------------------------------------------
+export function sha256hex(data) {
+  // Works in Node.js; in browsers, use SubtleCrypto instead
+  try {
+    return createHash("sha256").update(data).digest("hex");
+  } catch {
+    // Browser fallback (sync not available — caller should use sha256hexAsync)
+    throw new Error("Use sha256hexAsync in browser environments.");
+  }
+}
+
+export async function sha256hexAsync(data) {
+  const buf = new TextEncoder().encode(data);
+  const hash = await globalThis.crypto.subtle.digest("SHA-256", buf);
+  return Array.from(new Uint8Array(hash))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+// ---------------------------------------------------------------------------
+// Owner keypair — EC P-256
+// ---------------------------------------------------------------------------
+export async function generateOwnerKeypair() {
+  const { privateKey, publicKey } = await globalThis.crypto.subtle.generateKey(
+    { name: "ECDSA", namedCurve: "P-256" },
+    true,
+    ["sign", "verify"]
+  );
+
+  const private_key_jwk = await globalThis.crypto.subtle.exportKey("jwk", privateKey);
+  const public_key_jwk = await globalThis.crypto.subtle.exportKey("jwk", publicKey);
+
+  // owner_key_id is assigned by the server; return a local placeholder
+  return { public_key_jwk, private_key_jwk };
+}
+
+// ---------------------------------------------------------------------------
+// Sign payload (owner signs registration or revoke payload)
+// Returns base64url IEEE P1363 signature (64 bytes for P-256)
+// ---------------------------------------------------------------------------
+export async function signPayload(payload, privateKeyJwk) {
+  const key = await globalThis.crypto.subtle.importKey(
+    "jwk",
+    privateKeyJwk,
+    { name: "ECDSA", namedCurve: "P-256" },
+    false,
+    ["sign"]
+  );
+  const data = new TextEncoder().encode(canonicalJson(payload));
+  const sig = await globalThis.crypto.subtle.sign(
+    { name: "ECDSA", hash: "SHA-256" },
+    key,
+    data
+  );
+  return Buffer.from(sig).toString("base64url");
+}
+
+// ---------------------------------------------------------------------------
+// Verify owner signature
+// ---------------------------------------------------------------------------
+export async function verifyOwnerSignature(payload, signatureB64url, publicKeyJwk) {
+  try {
+    const key = await globalThis.crypto.subtle.importKey(
+      "jwk",
+      publicKeyJwk,
+      { name: "ECDSA", namedCurve: "P-256" },
+      false,
+      ["verify"]
+    );
+    const data = new TextEncoder().encode(canonicalJson(payload));
+    const sig = Buffer.from(signatureB64url, "base64url");
+    return await globalThis.crypto.subtle.verify(
+      { name: "ECDSA", hash: "SHA-256" },
+      key,
+      sig,
+      data
+    );
+  } catch {
+    return false;
+  }
+}

package/src/envelope.mjs

@@ -0,0 +1,109 @@
+/**
+ * buildEnvelope — assembles a complete v1 AIL envelope from a registered credential.
+ *
+ * Usage:
+ *   const envelope = buildEnvelope({
+ *     ail_id, credential, signal_glyph, behavior_fingerprint,
+ *     agent:      { id, provider, model, runtime },
+ *     owner:      { key_id, org, email_hash },
+ *     scope,
+ *     delegation: { mode, delegated_by, approved_by, chain_depth, task_ref },
+ *     runtime:    { session_id, run_id, surface, host, cwd },
+ *   })
+ */
+export function buildEnvelope({
+  ail_id,
+  credential,
+  signal_glyph,
+  behavior_fingerprint,
+  agent,
+  owner = null,
+  scope,
+  delegation,
+  runtime,
+  extensions = {},
+}) {
+  const now = new Date().toISOString();
+
+  return {
+    version: "ail.v1",
+    ail_id: ail_id ?? null,
+
+    credential: credential ?? null,
+
+    agent: {
+      id: agent.id,
+      display_name: agent.display_name ?? credential?.display_name,
+      role: agent.role ?? credential?.role,
+      provider: agent.provider ?? null,
+      model: agent.model ?? null,
+      runtime: agent.runtime ?? null,
+    },
+
+    owner: owner
+      ? {
+          key_id: owner.key_id,
+          org: owner.org ?? null,
+          email_hash: owner.email_hash ?? null,
+        }
+      : null,
+
+    scope: scope ?? {
+      workspace: [],
+      repos: [],
+      network: "restricted",
+      secrets: "none",
+      write_access: false,
+      approval_policy: {
+        irreversible_actions: "human_required",
+        external_posting: "human_required",
+        destructive_file_ops: "human_required",
+      },
+    },
+
+    signal_glyph: signal_glyph ?? null,
+    behavior_fingerprint: behavior_fingerprint ?? null,
+
+    delegation: {
+      mode: delegation?.mode ?? "direct",
+      delegated_by: delegation?.delegated_by ?? null,
+      approved_by: delegation?.approved_by ?? null,
+      chain_depth: delegation?.chain_depth ?? 0,
+      task_ref: delegation?.task_ref ?? null,
+    },
+
+    runtime: {
+      session_id: runtime?.session_id ?? null,
+      run_id: runtime?.run_id ?? null,
+      surface: runtime?.surface ?? null,
+      host: runtime?.host ?? null,
+      cwd: runtime?.cwd ?? null,
+      time: runtime?.time ?? now,
+    },
+
+    verification: ail_id && credential
+      ? {
+          strength: "cryptographically_signed",
+          issuer: credential.issuer,
+          issuer_key_id: credential.issuer_key_id,
+          token_type: "JWT",
+          signed: true,
+          verify_url: `${getIssuerBase(credential.issuer)}/verify`,
+          evidence: ["22blabs_registry", "owner_key_delegation", "jwt_signature"],
+          attestation_ref: `ail_id:${ail_id}`,
+        }
+      : {
+          strength: "local_runtime_asserted",
+          signed: false,
+          evidence: ["runtime_session_binding"],
+          attestation_ref: null,
+        },
+
+    extensions,
+  };
+}
+
+function getIssuerBase(issuer) {
+  if (!issuer.startsWith("http")) return `https://${issuer}/api`;
+  return issuer;
+}