auth-agents 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zeliang Cheng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -0,0 +1,114 @@
+interface AuthAgentsConfig {
+    /** Base URL of the Auth-Agents API. Defaults to https://auth.auth-agents.com */
+    baseUrl?: string;
+}
+interface VerifyResult {
+    valid: true;
+    did: string;
+    agent_name: string | null;
+    agent_model: string | null;
+    agent_provider: string | null;
+    agent_purpose: string | null;
+    key_fingerprint: string | null;
+    issued_at: string | null;
+    expires_at: string | null;
+}
+interface VerifyError {
+    valid: false;
+    error: "credential_expired" | "invalid_issuer" | "signature_invalid";
+    message: string;
+}
+type VerifyResponse = VerifyResult | VerifyError;
+interface RegisterInput {
+    agent_name: string;
+    agent_model: string;
+    agent_provider: string;
+    agent_purpose: string;
+    public_key_jwk?: {
+        kty: string;
+        crv: string;
+        x: string;
+    };
+}
+interface RegisterResult {
+    did: string;
+    credential: string;
+    key_fingerprint: string;
+    private_key_jwk?: {
+        kty: string;
+        crv: string;
+        x: string;
+        d: string;
+    };
+    _notice?: string;
+}
+interface ChallengeResult {
+    challenge_id: string;
+    nonce: string;
+    expires_in: number;
+}
+interface AuthVerifyInput {
+    challenge_id: string;
+    did: string;
+    signature: string;
+}
+interface AuthVerifyResult {
+    valid: true;
+    session_token: string;
+    credential: string;
+    agent: {
+        did: string;
+        agent_name: string;
+        agent_model: string;
+        agent_provider: string;
+        agent_purpose: string;
+        key_fingerprint: string;
+    };
+    expires_in: number;
+}
+interface AuthVerifyError {
+    valid: false;
+    error: string;
+    message: string;
+}
+type AuthVerifyResponse = AuthVerifyResult | AuthVerifyError;
+declare class AuthAgents {
+    private baseUrl;
+    constructor(config?: AuthAgentsConfig);
+    /**
+     * Verify a VC-JWT credential issued by Auth-Agents.
+     *
+     * @param credential - The VC-JWT string from the agent
+     * @returns Verified agent identity or error details
+     */
+    verify(credential: string): Promise<VerifyResponse>;
+    /**
+     * Register a new agent identity. The server generates an Ed25519 keypair
+     * and returns a DID, credential, and private key.
+     *
+     * @param input - Agent metadata (name, model, provider, purpose)
+     * @returns DID, credential, and private key (save securely!)
+     */
+    register(input: RegisterInput): Promise<RegisterResult>;
+    /**
+     * Request an authentication challenge nonce.
+     *
+     * @param did - The agent's DID
+     * @returns Challenge ID and nonce to sign
+     */
+    challenge(did: string): Promise<ChallengeResult>;
+    /**
+     * Submit a signed challenge to authenticate and receive a fresh credential.
+     *
+     * @param input - challenge_id, did, and base64url signature
+     * @returns Session token and fresh VC-JWT credential
+     */
+    authenticate(input: AuthVerifyInput): Promise<AuthVerifyResponse>;
+}
+/**
+ * Verify a credential with default settings.
+ * Shorthand for `new AuthAgents().verify(credential)`.
+ */
+declare function verify(credential: string): Promise<VerifyResponse>;
+
+export { AuthAgents, type AuthAgentsConfig, type AuthVerifyError, type AuthVerifyInput, type AuthVerifyResponse, type AuthVerifyResult, type ChallengeResult, type RegisterInput, type RegisterResult, type VerifyError, type VerifyResponse, type VerifyResult, verify };

package/dist/index.d.ts

@@ -0,0 +1,114 @@
+interface AuthAgentsConfig {
+    /** Base URL of the Auth-Agents API. Defaults to https://auth.auth-agents.com */
+    baseUrl?: string;
+}
+interface VerifyResult {
+    valid: true;
+    did: string;
+    agent_name: string | null;
+    agent_model: string | null;
+    agent_provider: string | null;
+    agent_purpose: string | null;
+    key_fingerprint: string | null;
+    issued_at: string | null;
+    expires_at: string | null;
+}
+interface VerifyError {
+    valid: false;
+    error: "credential_expired" | "invalid_issuer" | "signature_invalid";
+    message: string;
+}
+type VerifyResponse = VerifyResult | VerifyError;
+interface RegisterInput {
+    agent_name: string;
+    agent_model: string;
+    agent_provider: string;
+    agent_purpose: string;
+    public_key_jwk?: {
+        kty: string;
+        crv: string;
+        x: string;
+    };
+}
+interface RegisterResult {
+    did: string;
+    credential: string;
+    key_fingerprint: string;
+    private_key_jwk?: {
+        kty: string;
+        crv: string;
+        x: string;
+        d: string;
+    };
+    _notice?: string;
+}
+interface ChallengeResult {
+    challenge_id: string;
+    nonce: string;
+    expires_in: number;
+}
+interface AuthVerifyInput {
+    challenge_id: string;
+    did: string;
+    signature: string;
+}
+interface AuthVerifyResult {
+    valid: true;
+    session_token: string;
+    credential: string;
+    agent: {
+        did: string;
+        agent_name: string;
+        agent_model: string;
+        agent_provider: string;
+        agent_purpose: string;
+        key_fingerprint: string;
+    };
+    expires_in: number;
+}
+interface AuthVerifyError {
+    valid: false;
+    error: string;
+    message: string;
+}
+type AuthVerifyResponse = AuthVerifyResult | AuthVerifyError;
+declare class AuthAgents {
+    private baseUrl;
+    constructor(config?: AuthAgentsConfig);
+    /**
+     * Verify a VC-JWT credential issued by Auth-Agents.
+     *
+     * @param credential - The VC-JWT string from the agent
+     * @returns Verified agent identity or error details
+     */
+    verify(credential: string): Promise<VerifyResponse>;
+    /**
+     * Register a new agent identity. The server generates an Ed25519 keypair
+     * and returns a DID, credential, and private key.
+     *
+     * @param input - Agent metadata (name, model, provider, purpose)
+     * @returns DID, credential, and private key (save securely!)
+     */
+    register(input: RegisterInput): Promise<RegisterResult>;
+    /**
+     * Request an authentication challenge nonce.
+     *
+     * @param did - The agent's DID
+     * @returns Challenge ID and nonce to sign
+     */
+    challenge(did: string): Promise<ChallengeResult>;
+    /**
+     * Submit a signed challenge to authenticate and receive a fresh credential.
+     *
+     * @param input - challenge_id, did, and base64url signature
+     * @returns Session token and fresh VC-JWT credential
+     */
+    authenticate(input: AuthVerifyInput): Promise<AuthVerifyResponse>;
+}
+/**
+ * Verify a credential with default settings.
+ * Shorthand for `new AuthAgents().verify(credential)`.
+ */
+declare function verify(credential: string): Promise<VerifyResponse>;
+
+export { AuthAgents, type AuthAgentsConfig, type AuthVerifyError, type AuthVerifyInput, type AuthVerifyResponse, type AuthVerifyResult, type ChallengeResult, type RegisterInput, type RegisterResult, type VerifyError, type VerifyResponse, type VerifyResult, verify };

package/dist/index.js

@@ -0,0 +1,112 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AuthAgents: () => AuthAgents,
+  verify: () => verify
+});
+module.exports = __toCommonJS(index_exports);
+var DEFAULT_BASE_URL = "https://auth.auth-agents.com";
+var AuthAgents = class {
+  constructor(config) {
+    this.baseUrl = (config?.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+  }
+  // ---- Credential Verification (for websites) ----------------------------
+  /**
+   * Verify a VC-JWT credential issued by Auth-Agents.
+   *
+   * @param credential - The VC-JWT string from the agent
+   * @returns Verified agent identity or error details
+   */
+  async verify(credential) {
+    const res = await fetch(`${this.baseUrl}/v1/credentials/verify`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ credential })
+    });
+    return res.json();
+  }
+  // ---- Agent Registration ------------------------------------------------
+  /**
+   * Register a new agent identity. The server generates an Ed25519 keypair
+   * and returns a DID, credential, and private key.
+   *
+   * @param input - Agent metadata (name, model, provider, purpose)
+   * @returns DID, credential, and private key (save securely!)
+   */
+  async register(input) {
+    const res = await fetch(`${this.baseUrl}/v1/identities`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(input)
+    });
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({}));
+      throw new Error(
+        body.error ?? `Registration failed (${res.status})`
+      );
+    }
+    return res.json();
+  }
+  // ---- Challenge-Response Auth -------------------------------------------
+  /**
+   * Request an authentication challenge nonce.
+   *
+   * @param did - The agent's DID
+   * @returns Challenge ID and nonce to sign
+   */
+  async challenge(did) {
+    const res = await fetch(`${this.baseUrl}/v1/auth/challenge`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ did })
+    });
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({}));
+      throw new Error(
+        body.error ?? `Challenge failed (${res.status})`
+      );
+    }
+    return res.json();
+  }
+  /**
+   * Submit a signed challenge to authenticate and receive a fresh credential.
+   *
+   * @param input - challenge_id, did, and base64url signature
+   * @returns Session token and fresh VC-JWT credential
+   */
+  async authenticate(input) {
+    const res = await fetch(`${this.baseUrl}/v1/auth/verify`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(input)
+    });
+    return res.json();
+  }
+};
+async function verify(credential) {
+  return new AuthAgents().verify(credential);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AuthAgents,
+  verify
+});

package/dist/index.mjs

@@ -0,0 +1,86 @@
+// src/index.ts
+var DEFAULT_BASE_URL = "https://auth.auth-agents.com";
+var AuthAgents = class {
+  constructor(config) {
+    this.baseUrl = (config?.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+  }
+  // ---- Credential Verification (for websites) ----------------------------
+  /**
+   * Verify a VC-JWT credential issued by Auth-Agents.
+   *
+   * @param credential - The VC-JWT string from the agent
+   * @returns Verified agent identity or error details
+   */
+  async verify(credential) {
+    const res = await fetch(`${this.baseUrl}/v1/credentials/verify`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ credential })
+    });
+    return res.json();
+  }
+  // ---- Agent Registration ------------------------------------------------
+  /**
+   * Register a new agent identity. The server generates an Ed25519 keypair
+   * and returns a DID, credential, and private key.
+   *
+   * @param input - Agent metadata (name, model, provider, purpose)
+   * @returns DID, credential, and private key (save securely!)
+   */
+  async register(input) {
+    const res = await fetch(`${this.baseUrl}/v1/identities`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(input)
+    });
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({}));
+      throw new Error(
+        body.error ?? `Registration failed (${res.status})`
+      );
+    }
+    return res.json();
+  }
+  // ---- Challenge-Response Auth -------------------------------------------
+  /**
+   * Request an authentication challenge nonce.
+   *
+   * @param did - The agent's DID
+   * @returns Challenge ID and nonce to sign
+   */
+  async challenge(did) {
+    const res = await fetch(`${this.baseUrl}/v1/auth/challenge`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ did })
+    });
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({}));
+      throw new Error(
+        body.error ?? `Challenge failed (${res.status})`
+      );
+    }
+    return res.json();
+  }
+  /**
+   * Submit a signed challenge to authenticate and receive a fresh credential.
+   *
+   * @param input - challenge_id, did, and base64url signature
+   * @returns Session token and fresh VC-JWT credential
+   */
+  async authenticate(input) {
+    const res = await fetch(`${this.baseUrl}/v1/auth/verify`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(input)
+    });
+    return res.json();
+  }
+};
+async function verify(credential) {
+  return new AuthAgents().verify(credential);
+}
+export {
+  AuthAgents,
+  verify
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "auth-agents",
+  "version": "0.1.0",
+  "description": "Verify AI agent identities with Auth-Agents. DID-based authentication using Ed25519 and Verifiable Credentials.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "auth-agents",
+    "ai-agent",
+    "did",
+    "verifiable-credential",
+    "ed25519",
+    "authentication",
+    "identity",
+    "decentralized-identity"
+  ],
+  "author": "Zeliang Cheng",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AgenthAgent/auth-agents-sdk-node"
+  },
+  "homepage": "https://auth-agents.com",
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  }
+}