auth-agents 0.1.3 → 0.4.0

package/README.md

@@ -23,10 +23,106 @@ if (result.valid) {
   console.log(result.agent_model)    // "claude-opus-4-6"
   console.log(result.agent_provider) // "Anthropic"
   console.log(result.agent_purpose)  // "Research assistant"
+  console.log(result.key_origin)     // "server_generated" | "client_provided"
   console.log(result.expires_at)     // "2026-02-27T01:58:15.000Z"
 }
 ```
 
+## Identity Registration Flows
+
+Agent Auth supports two registration paths. Both produce the same DID, credential, and challenge-response authentication. The difference is who holds the private key.
+
+### Flow A — Server-Generated Keys (zero friction)
+
+The server generates an Ed25519 key pair. You receive the private key once and must store it securely. `key_origin` will be `"server_generated"`.
+
+```typescript
+import { AuthAgents } from "auth-agents"
+
+const client = new AuthAgents()
+
+// 1. Register — server generates keys
+const identity = await client.register({
+  agent_name: "Claude",
+  agent_model: "claude-opus-4-6",
+  agent_provider: "Anthropic",
+  agent_purpose: "Research assistant",
+})
+// identity.did              — "did:key:z6Mk..."
+// identity.credential       — VC-JWT (present to websites)
+// identity.key_origin       — "server_generated"
+// identity.private_key_jwk  — SAVE THIS. Server does not keep it.
+
+// 2. Request a challenge
+const challenge = await client.challenge(identity.did)
+
+// 3. Sign the nonce with the private key
+const signature = await AuthAgents.signChallenge(
+  identity.private_key_jwk!,
+  challenge.nonce
+)
+
+// 4. Authenticate and receive a fresh credential
+const auth = await client.authenticate({
+  challenge_id: challenge.challenge_id,
+  did: identity.did,
+  signature,
+})
+
+if (auth.valid) {
+  console.log(auth.credential)     // fresh VC-JWT
+  console.log(auth.session_token)  // session ID
+}
+```
+
+### Flow B — Bring Your Own Key (BYOK)
+
+Generate the key pair locally. The private key never leaves your process. `key_origin` will be `"client_provided"`.
+
+```typescript
+import { AuthAgents } from "auth-agents"
+
+const client = new AuthAgents()
+
+// 1. Generate an Ed25519 key pair locally
+const keyPair = await AuthAgents.generateKeyPair()
+// keyPair.publicKeyJwk  — { kty, crv, x }
+// keyPair.privateKeyJwk — { kty, crv, x, d }  ← never sent to server
+
+// 2. Register with your public key (no private_key_jwk returned)
+const identity = await client.register({
+  agent_name: "Claude",
+  agent_model: "claude-opus-4-6",
+  agent_provider: "Anthropic",
+  agent_purpose: "Research assistant",
+  public_key_jwk: keyPair.publicKeyJwk,
+})
+// identity.did        — "did:key:z6Mk..."
+// identity.credential — VC-JWT
+// identity.key_origin — "client_provided"
+
+// 3. Request a challenge
+const challenge = await client.challenge(identity.did)
+
+// 4. Sign the nonce with your private key
+const signature = await AuthAgents.signChallenge(
+  keyPair.privateKeyJwk,
+  challenge.nonce
+)
+
+// 5. Authenticate and receive a fresh credential
+const auth = await client.authenticate({
+  challenge_id: challenge.challenge_id,
+  did: identity.did,
+  signature,
+})
+
+if (auth.valid) {
+  console.log(auth.credential)     // fresh VC-JWT
+  console.log(auth.session_token)  // session ID
+}
+```
+
 ## Website Integration (Next.js)
 
 ```typescript
@@ -51,6 +147,7 @@ export async function POST(request: Request) {
     did: result.did,
     agent_name: result.agent_name,
     agent_model: result.agent_model,
+    key_origin: result.key_origin,
     expires_at: result.expires_at,
   })
 
@@ -80,50 +177,73 @@ app.post("/auth/agent", express.json(), async (req, res) => {
     did: result.did,
     name: result.agent_name,
     model: result.agent_model,
+    key_origin: result.key_origin,
   }
 
   res.json({ authenticated: true, agent_name: result.agent_name })
 })
 ```
 
-## Full Agent Auth Flow
+## API
 
-```typescript
-import { AuthAgents } from "auth-agents"
+### `new AuthAgents(config?)`
 
-const client = new AuthAgents()
+- `config.baseUrl` — API base URL (default: `https://auth.getagentauth.com`)
 
-// 1. Register
-const identity = await client.register({
-  agent_name: "Claude",
-  agent_model: "claude-opus-4-6",
-  agent_provider: "Anthropic",
-  agent_purpose: "Research assistant",
-})
+### `AuthAgents.generateKeyPair()` — Static
 
-// 2. Request challenge
-const challenge = await client.challenge(identity.did)
+Generate a local Ed25519 key pair using the Web Crypto API. No network call.
 
-// 3. Sign nonce and authenticate
-const auth = await client.authenticate({
-  challenge_id: challenge.challenge_id,
-  did: identity.did,
-  signature: signedNonce, // base64url Ed25519 signature of challenge.nonce
-})
-// auth.credential — fresh VC-JWT
-// auth.session_token — session ID
+Returns `Ed25519KeyPair`:
+```typescript
+{
+  publicKeyJwk:  { kty: string; crv: string; x: string }
+  privateKeyJwk: { kty: string; crv: string; x: string; d: string }
+}
 ```
 
-## API
+### `AuthAgents.signChallenge(privateKeyJwk, nonce)` — Static
 
-### `new AuthAgents(config?)`
+Sign an authentication challenge nonce with an Ed25519 private key. No network call.
 
-- `config.baseUrl` — API base URL (default: `https://auth.getagentauth.com`)
+- `privateKeyJwk` — JWK with `d` parameter (the private key from `generateKeyPair()` or from `register()`)
+- `nonce` — the nonce string from `client.challenge()`
+
+Returns a `Promise<string>` — base64url-encoded Ed25519 signature.
 
 ### `client.verify(credential)` — Verify a VC-JWT credential
 
+Returns `VerifyResult` on success:
+```typescript
+{
+  valid: true
+  did: string
+  agent_name: string | null
+  agent_model: string | null
+  agent_provider: string | null
+  agent_purpose: string | null
+  key_fingerprint: string | null
+  key_origin: string | null     // "server_generated" | "client_provided"
+  issued_at: string | null
+  expires_at: string | null
+}
+```
+
 ### `client.register(input)` — Register a new agent identity
 
+`input.public_key_jwk` is optional. Omit it for server-generated keys (Flow A). Provide it for BYOK (Flow B).
+
+Returns `RegisterResult`:
+```typescript
+{
+  did: string
+  credential: string
+  key_fingerprint: string
+  key_origin?: "server_generated" | "client_provided"
+  private_key_jwk?: { kty, crv, x, d }  // only present for server_generated
+}
+```
+
 ### `client.challenge(did)` — Request an auth challenge
 
 ### `client.authenticate(input)` — Submit signed challenge

package/dist/index.d.mts

@@ -2,6 +2,20 @@ interface AuthAgentsConfig {
     /** Base URL of the Agent Auth API. Defaults to https://auth.getagentauth.com */
     baseUrl?: string;
 }
+/** Ed25519 key pair in JWK format, returned by generateKeyPair() */
+interface Ed25519KeyPair {
+    publicKeyJwk: {
+        kty: string;
+        crv: string;
+        x: string;
+    };
+    privateKeyJwk: {
+        kty: string;
+        crv: string;
+        x: string;
+        d: string;
+    };
+}
 interface VerifyResult {
     valid: true;
     did: string;
@@ -12,6 +26,7 @@ interface VerifyResult {
     key_fingerprint: string | null;
     issued_at: string | null;
     expires_at: string | null;
+    key_origin: string | null;
 }
 interface VerifyError {
     valid: false;
@@ -34,6 +49,7 @@ interface RegisterResult {
     did: string;
     credential: string;
     key_fingerprint: string;
+    key_origin?: "server_generated" | "client_provided";
     private_key_jwk?: {
         kty: string;
         crv: string;
@@ -75,6 +91,31 @@ type AuthVerifyResponse = AuthVerifyResult | AuthVerifyError;
 declare class AuthAgents {
     private baseUrl;
     constructor(config?: AuthAgentsConfig);
+    /**
+     * Generate an Ed25519 key pair using the Web Crypto API.
+     * Use the returned public key JWK for BYOK registration and the private key
+     * JWK with signChallenge() to complete headless authentication.
+     *
+     * SECURITY: Store the private key securely. Never transmit it over the wire.
+     *
+     * @returns Ed25519 key pair in JWK format
+     */
+    static generateKeyPair(): Promise<Ed25519KeyPair>;
+    /**
+     * Sign an authentication challenge nonce with an Ed25519 private key.
+     * The nonce is signed as UTF-8 encoded text (NOT hex-decoded bytes).
+     * Returns a base64url-encoded signature string.
+     *
+     * @param privateKeyJwk - The agent's private key in JWK format (must include `d`)
+     * @param nonce - The challenge nonce string returned by client.challenge()
+     * @returns base64url-encoded Ed25519 signature
+     */
+    static signChallenge(privateKeyJwk: {
+        kty: string;
+        crv: string;
+        x: string;
+        d: string;
+    }, nonce: string): Promise<string>;
     /**
      * Verify a VC-JWT credential issued by Agent Auth.
      *
@@ -83,11 +124,12 @@ declare class AuthAgents {
      */
     verify(credential: string): Promise<VerifyResponse>;
     /**
-     * Register a new agent identity. The server generates an Ed25519 keypair
-     * and returns a DID, credential, and private key.
+     * Register a new agent identity. By default the server generates an Ed25519
+     * keypair and returns the private key. Pass `public_key_jwk` to use your own
+     * key (BYOK) — in that case no private key is returned.
      *
-     * @param input - Agent metadata (name, model, provider, purpose)
-     * @returns DID, credential, and private key (save securely!)
+     * @param input - Agent metadata and optional public key JWK for BYOK
+     * @returns DID, credential, key_origin, and private key if server-generated
      */
     register(input: RegisterInput): Promise<RegisterResult>;
     /**
@@ -111,4 +153,4 @@ declare class AuthAgents {
  */
 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 };
+export { AuthAgents, type AuthAgentsConfig, type AuthVerifyError, type AuthVerifyInput, type AuthVerifyResponse, type AuthVerifyResult, type ChallengeResult, type Ed25519KeyPair, type RegisterInput, type RegisterResult, type VerifyError, type VerifyResponse, type VerifyResult, verify };

package/dist/index.d.ts

@@ -2,6 +2,20 @@ interface AuthAgentsConfig {
     /** Base URL of the Agent Auth API. Defaults to https://auth.getagentauth.com */
     baseUrl?: string;
 }
+/** Ed25519 key pair in JWK format, returned by generateKeyPair() */
+interface Ed25519KeyPair {
+    publicKeyJwk: {
+        kty: string;
+        crv: string;
+        x: string;
+    };
+    privateKeyJwk: {
+        kty: string;
+        crv: string;
+        x: string;
+        d: string;
+    };
+}
 interface VerifyResult {
     valid: true;
     did: string;
@@ -12,6 +26,7 @@ interface VerifyResult {
     key_fingerprint: string | null;
     issued_at: string | null;
     expires_at: string | null;
+    key_origin: string | null;
 }
 interface VerifyError {
     valid: false;
@@ -34,6 +49,7 @@ interface RegisterResult {
     did: string;
     credential: string;
     key_fingerprint: string;
+    key_origin?: "server_generated" | "client_provided";
     private_key_jwk?: {
         kty: string;
         crv: string;
@@ -75,6 +91,31 @@ type AuthVerifyResponse = AuthVerifyResult | AuthVerifyError;
 declare class AuthAgents {
     private baseUrl;
     constructor(config?: AuthAgentsConfig);
+    /**
+     * Generate an Ed25519 key pair using the Web Crypto API.
+     * Use the returned public key JWK for BYOK registration and the private key
+     * JWK with signChallenge() to complete headless authentication.
+     *
+     * SECURITY: Store the private key securely. Never transmit it over the wire.
+     *
+     * @returns Ed25519 key pair in JWK format
+     */
+    static generateKeyPair(): Promise<Ed25519KeyPair>;
+    /**
+     * Sign an authentication challenge nonce with an Ed25519 private key.
+     * The nonce is signed as UTF-8 encoded text (NOT hex-decoded bytes).
+     * Returns a base64url-encoded signature string.
+     *
+     * @param privateKeyJwk - The agent's private key in JWK format (must include `d`)
+     * @param nonce - The challenge nonce string returned by client.challenge()
+     * @returns base64url-encoded Ed25519 signature
+     */
+    static signChallenge(privateKeyJwk: {
+        kty: string;
+        crv: string;
+        x: string;
+        d: string;
+    }, nonce: string): Promise<string>;
     /**
      * Verify a VC-JWT credential issued by Agent Auth.
      *
@@ -83,11 +124,12 @@ declare class AuthAgents {
      */
     verify(credential: string): Promise<VerifyResponse>;
     /**
-     * Register a new agent identity. The server generates an Ed25519 keypair
-     * and returns a DID, credential, and private key.
+     * Register a new agent identity. By default the server generates an Ed25519
+     * keypair and returns the private key. Pass `public_key_jwk` to use your own
+     * key (BYOK) — in that case no private key is returned.
      *
-     * @param input - Agent metadata (name, model, provider, purpose)
-     * @returns DID, credential, and private key (save securely!)
+     * @param input - Agent metadata and optional public key JWK for BYOK
+     * @returns DID, credential, key_origin, and private key if server-generated
      */
     register(input: RegisterInput): Promise<RegisterResult>;
     /**
@@ -111,4 +153,4 @@ declare class AuthAgents {
  */
 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 };
+export { AuthAgents, type AuthAgentsConfig, type AuthVerifyError, type AuthVerifyInput, type AuthVerifyResponse, type AuthVerifyResult, type ChallengeResult, type Ed25519KeyPair, type RegisterInput, type RegisterResult, type VerifyError, type VerifyResponse, type VerifyResult, verify };

package/dist/index.js

@@ -29,6 +29,66 @@ var AuthAgents = class {
   constructor(config) {
     this.baseUrl = (config?.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
   }
+  // ---- Static Crypto Helpers ---------------------------------------------
+  /**
+   * Generate an Ed25519 key pair using the Web Crypto API.
+   * Use the returned public key JWK for BYOK registration and the private key
+   * JWK with signChallenge() to complete headless authentication.
+   *
+   * SECURITY: Store the private key securely. Never transmit it over the wire.
+   *
+   * @returns Ed25519 key pair in JWK format
+   */
+  static async generateKeyPair() {
+    const keyPair = await crypto.subtle.generateKey(
+      "Ed25519",
+      true,
+      // extractable
+      ["sign", "verify"]
+    );
+    const publicJwk = await crypto.subtle.exportKey("jwk", keyPair.publicKey);
+    const privateJwk = await crypto.subtle.exportKey("jwk", keyPair.privateKey);
+    return {
+      publicKeyJwk: {
+        kty: publicJwk.kty,
+        crv: publicJwk.crv,
+        x: publicJwk.x
+      },
+      privateKeyJwk: {
+        kty: privateJwk.kty,
+        crv: privateJwk.crv,
+        x: privateJwk.x,
+        d: privateJwk.d
+      }
+    };
+  }
+  /**
+   * Sign an authentication challenge nonce with an Ed25519 private key.
+   * The nonce is signed as UTF-8 encoded text (NOT hex-decoded bytes).
+   * Returns a base64url-encoded signature string.
+   *
+   * @param privateKeyJwk - The agent's private key in JWK format (must include `d`)
+   * @param nonce - The challenge nonce string returned by client.challenge()
+   * @returns base64url-encoded Ed25519 signature
+   */
+  static async signChallenge(privateKeyJwk, nonce) {
+    const key = await crypto.subtle.importKey(
+      "jwk",
+      { ...privateKeyJwk, key_ops: ["sign"] },
+      "Ed25519",
+      false,
+      ["sign"]
+    );
+    const data = new TextEncoder().encode(nonce);
+    const signatureBuffer = await crypto.subtle.sign("Ed25519", key, data);
+    const bytes = new Uint8Array(signatureBuffer);
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++) {
+      binary += String.fromCharCode(bytes[i]);
+    }
+    const base64 = btoa(binary);
+    return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+  }
   // ---- Credential Verification (for websites) ----------------------------
   /**
    * Verify a VC-JWT credential issued by Agent Auth.
@@ -46,11 +106,12 @@ var AuthAgents = class {
   }
   // ---- Agent Registration ------------------------------------------------
   /**
-   * Register a new agent identity. The server generates an Ed25519 keypair
-   * and returns a DID, credential, and private key.
+   * Register a new agent identity. By default the server generates an Ed25519
+   * keypair and returns the private key. Pass `public_key_jwk` to use your own
+   * key (BYOK) — in that case no private key is returned.
    *
-   * @param input - Agent metadata (name, model, provider, purpose)
-   * @returns DID, credential, and private key (save securely!)
+   * @param input - Agent metadata and optional public key JWK for BYOK
+   * @returns DID, credential, key_origin, and private key if server-generated
    */
   async register(input) {
     const res = await fetch(`${this.baseUrl}/v1/identities`, {

package/dist/index.mjs

@@ -4,6 +4,66 @@ var AuthAgents = class {
   constructor(config) {
     this.baseUrl = (config?.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
   }
+  // ---- Static Crypto Helpers ---------------------------------------------
+  /**
+   * Generate an Ed25519 key pair using the Web Crypto API.
+   * Use the returned public key JWK for BYOK registration and the private key
+   * JWK with signChallenge() to complete headless authentication.
+   *
+   * SECURITY: Store the private key securely. Never transmit it over the wire.
+   *
+   * @returns Ed25519 key pair in JWK format
+   */
+  static async generateKeyPair() {
+    const keyPair = await crypto.subtle.generateKey(
+      "Ed25519",
+      true,
+      // extractable
+      ["sign", "verify"]
+    );
+    const publicJwk = await crypto.subtle.exportKey("jwk", keyPair.publicKey);
+    const privateJwk = await crypto.subtle.exportKey("jwk", keyPair.privateKey);
+    return {
+      publicKeyJwk: {
+        kty: publicJwk.kty,
+        crv: publicJwk.crv,
+        x: publicJwk.x
+      },
+      privateKeyJwk: {
+        kty: privateJwk.kty,
+        crv: privateJwk.crv,
+        x: privateJwk.x,
+        d: privateJwk.d
+      }
+    };
+  }
+  /**
+   * Sign an authentication challenge nonce with an Ed25519 private key.
+   * The nonce is signed as UTF-8 encoded text (NOT hex-decoded bytes).
+   * Returns a base64url-encoded signature string.
+   *
+   * @param privateKeyJwk - The agent's private key in JWK format (must include `d`)
+   * @param nonce - The challenge nonce string returned by client.challenge()
+   * @returns base64url-encoded Ed25519 signature
+   */
+  static async signChallenge(privateKeyJwk, nonce) {
+    const key = await crypto.subtle.importKey(
+      "jwk",
+      { ...privateKeyJwk, key_ops: ["sign"] },
+      "Ed25519",
+      false,
+      ["sign"]
+    );
+    const data = new TextEncoder().encode(nonce);
+    const signatureBuffer = await crypto.subtle.sign("Ed25519", key, data);
+    const bytes = new Uint8Array(signatureBuffer);
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++) {
+      binary += String.fromCharCode(bytes[i]);
+    }
+    const base64 = btoa(binary);
+    return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+  }
   // ---- Credential Verification (for websites) ----------------------------
   /**
    * Verify a VC-JWT credential issued by Agent Auth.
@@ -21,11 +81,12 @@ var AuthAgents = class {
   }
   // ---- Agent Registration ------------------------------------------------
   /**
-   * Register a new agent identity. The server generates an Ed25519 keypair
-   * and returns a DID, credential, and private key.
+   * Register a new agent identity. By default the server generates an Ed25519
+   * keypair and returns the private key. Pass `public_key_jwk` to use your own
+   * key (BYOK) — in that case no private key is returned.
    *
-   * @param input - Agent metadata (name, model, provider, purpose)
-   * @returns DID, credential, and private key (save securely!)
+   * @param input - Agent metadata and optional public key JWK for BYOK
+   * @returns DID, credential, key_origin, and private key if server-generated
    */
   async register(input) {
     const res = await fetch(`${this.baseUrl}/v1/identities`, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auth-agents",
-  "version": "0.1.3",
+  "version": "0.4.0",
   "description": "Verify AI agent identities with Agent Auth. DID-based authentication using Ed25519 and Verifiable Credentials.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",