auth-agents 0.1.3 → 0.4.2

package/README.md

@@ -1,6 +1,6 @@
 # auth-agents
 
-Verify AI agent identities with [Agent Auth](https://getagentauth.com). DID-based authentication using Ed25519 and Verifiable Credentials.
+Verify AI agent identities with [Agent Auth](https://usevigil.dev). DID-based authentication using Ed25519 and Verifiable Credentials.
 
 ## Install
 
@@ -23,14 +23,110 @@ 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
-// app/api/auth/agent/route.ts
+// app/api/auth/agent-login/route.ts
 import { AuthAgents } from "auth-agents"
 
 const authAgents = new AuthAgents()
@@ -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,
   })
 
@@ -67,7 +164,7 @@ import { AuthAgents } from "auth-agents"
 const app = express()
 const authAgents = new AuthAgents()
 
-app.post("/auth/agent", express.json(), async (req, res) => {
+app.post("/auth/agent-login", express.json(), async (req, res) => {
   const { credential } = req.body
   const result = await authAgents.verify(credential)
 
@@ -80,57 +177,96 @@ 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.usevigil.dev`). The SDK enforces HTTPS for all API communication. HTTP is only allowed for `localhost` during development.
 
-// 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
+}
+```
+
+Returns `VerifyError` (HTTP 401) without throwing:
+```typescript
+{
+  valid: false
+  error: "credential_expired" | "invalid_issuer" | "signature_invalid" | "credential_revoked"
+  message: string
+}
+```
+
 ### `client.register(input)` — Register a new agent identity
 
-### `client.challenge(did)` — Request an auth challenge
+`input.public_key_jwk` is optional. Omit it for server-generated keys (Flow A). Provide it for BYOK (Flow B).
+You can also pass:
+- `credential_expires_in` — credential lifetime in seconds (`0` means non-expiring)
+- `metadata` — key/value metadata map (max key/value sizes enforced server-side)
+
+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, site_id?)` — Request an auth challenge
+
+`site_id` is optional and scopes the challenge/session when your deployment uses site-level org provisioning.
 
 ### `client.authenticate(input)` — Submit signed challenge
 
+`input` supports optional `credential_expires_in` to customize the issued credential lifetime (`0` means non-expiring).
+
 ## Documentation
 
-Full API reference at [getagentauth.com/docs](https://getagentauth.com/docs/)
+Full API reference at [usevigil.dev/docs](https://usevigil.dev/docs/)
 
 ## License
 

package/dist/index.d.mts

@@ -1,7 +1,21 @@
 interface AuthAgentsConfig {
-    /** Base URL of the Agent Auth API. Defaults to https://auth.getagentauth.com */
+    /** Base URL of the Agent Auth API. Defaults to https://auth.usevigil.dev */
     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,10 +26,11 @@ interface VerifyResult {
     key_fingerprint: string | null;
     issued_at: string | null;
     expires_at: string | null;
+    key_origin: string | null;
 }
 interface VerifyError {
     valid: false;
-    error: "credential_expired" | "invalid_issuer" | "signature_invalid";
+    error: "credential_expired" | "invalid_issuer" | "signature_invalid" | "credential_revoked";
     message: string;
 }
 type VerifyResponse = VerifyResult | VerifyError;
@@ -29,11 +44,14 @@ interface RegisterInput {
         crv: string;
         x: string;
     };
+    credential_expires_in?: number;
+    metadata?: Record<string, string>;
 }
 interface RegisterResult {
     did: string;
     credential: string;
     key_fingerprint: string;
+    key_origin?: "server_generated" | "client_provided";
     private_key_jwk?: {
         kty: string;
         crv: string;
@@ -51,6 +69,7 @@ interface AuthVerifyInput {
     challenge_id: string;
     did: string;
     signature: string;
+    credential_expires_in?: number;
 }
 interface AuthVerifyResult {
     valid: true;
@@ -75,33 +94,62 @@ 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.
      *
      * @param credential - The VC-JWT string from the agent
-     * @returns Verified agent identity or error details
+     * @returns Verified agent identity. If API returns 401, returns
+     *          `{ valid: false, error, message }` instead of throwing.
      */
     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>;
     /**
      * Request an authentication challenge nonce.
      *
      * @param did - The agent's DID
+     * @param site_id - Optional site scope for provisioned deployments
      * @returns Challenge ID and nonce to sign
      */
-    challenge(did: string): Promise<ChallengeResult>;
+    challenge(did: string, site_id?: 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
+     * @param input - challenge_id, did, base64url signature, and optional credential_expires_in
+     * @returns Session token and fresh VC-JWT credential. If API returns 401,
+     *          returns `{ valid: false, error, message }` instead of throwing.
      */
     authenticate(input: AuthVerifyInput): Promise<AuthVerifyResponse>;
 }
@@ -111,4 +159,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

@@ -1,7 +1,21 @@
 interface AuthAgentsConfig {
-    /** Base URL of the Agent Auth API. Defaults to https://auth.getagentauth.com */
+    /** Base URL of the Agent Auth API. Defaults to https://auth.usevigil.dev */
     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,10 +26,11 @@ interface VerifyResult {
     key_fingerprint: string | null;
     issued_at: string | null;
     expires_at: string | null;
+    key_origin: string | null;
 }
 interface VerifyError {
     valid: false;
-    error: "credential_expired" | "invalid_issuer" | "signature_invalid";
+    error: "credential_expired" | "invalid_issuer" | "signature_invalid" | "credential_revoked";
     message: string;
 }
 type VerifyResponse = VerifyResult | VerifyError;
@@ -29,11 +44,14 @@ interface RegisterInput {
         crv: string;
         x: string;
     };
+    credential_expires_in?: number;
+    metadata?: Record<string, string>;
 }
 interface RegisterResult {
     did: string;
     credential: string;
     key_fingerprint: string;
+    key_origin?: "server_generated" | "client_provided";
     private_key_jwk?: {
         kty: string;
         crv: string;
@@ -51,6 +69,7 @@ interface AuthVerifyInput {
     challenge_id: string;
     did: string;
     signature: string;
+    credential_expires_in?: number;
 }
 interface AuthVerifyResult {
     valid: true;
@@ -75,33 +94,62 @@ 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.
      *
      * @param credential - The VC-JWT string from the agent
-     * @returns Verified agent identity or error details
+     * @returns Verified agent identity. If API returns 401, returns
+     *          `{ valid: false, error, message }` instead of throwing.
      */
     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>;
     /**
      * Request an authentication challenge nonce.
      *
      * @param did - The agent's DID
+     * @param site_id - Optional site scope for provisioned deployments
      * @returns Challenge ID and nonce to sign
      */
-    challenge(did: string): Promise<ChallengeResult>;
+    challenge(did: string, site_id?: 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
+     * @param input - challenge_id, did, base64url signature, and optional credential_expires_in
+     * @returns Session token and fresh VC-JWT credential. If API returns 401,
+     *          returns `{ valid: false, error, message }` instead of throwing.
      */
     authenticate(input: AuthVerifyInput): Promise<AuthVerifyResponse>;
 }
@@ -111,4 +159,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

@@ -24,39 +24,130 @@ __export(index_exports, {
   verify: () => verify
 });
 module.exports = __toCommonJS(index_exports);
-var DEFAULT_BASE_URL = "https://auth.getagentauth.com";
+var DEFAULT_BASE_URL = "https://auth.usevigil.dev";
 var AuthAgents = class {
   constructor(config) {
-    this.baseUrl = (config?.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    const url = (config?.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    try {
+      const parsed = new URL(url);
+      if (parsed.protocol !== "https:" && parsed.hostname !== "localhost" && parsed.hostname !== "127.0.0.1") {
+        throw new Error("AuthAgents: baseUrl must use HTTPS (http://localhost allowed for development)");
+      }
+    } catch (e) {
+      if (e instanceof Error && e.message.startsWith("AuthAgents:")) throw e;
+      throw new Error("AuthAgents: baseUrl must be a valid URL");
+    }
+    this.baseUrl = url;
+  }
+  // ---- 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) {
+    if (!privateKeyJwk?.d) {
+      throw new Error("privateKeyJwk must contain the 'd' (private key) parameter");
+    }
+    if (!nonce) {
+      throw new Error("nonce must not be empty");
+    }
+    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.
    *
    * @param credential - The VC-JWT string from the agent
-   * @returns Verified agent identity or error details
+   * @returns Verified agent identity. If API returns 401, returns
+   *          `{ valid: false, error, message }` instead of throwing.
    */
   async verify(credential) {
     const res = await fetch(`${this.baseUrl}/v1/credentials/verify`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ credential })
+      body: JSON.stringify({ credential }),
+      signal: AbortSignal.timeout(1e4)
     });
-    return res.json();
+    const body = await res.json().catch(() => ({}));
+    if (res.status === 401) {
+      return {
+        valid: false,
+        error: body.error ?? "signature_invalid",
+        message: body.message ?? "Credential verification failed"
+      };
+    }
+    if (!res.ok) {
+      throw new Error(body.error ?? body.message ?? `Verify failed (${res.status})`);
+    }
+    return body;
   }
   // ---- 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`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(input)
+      body: JSON.stringify(input),
+      signal: AbortSignal.timeout(1e4)
     });
     if (!res.ok) {
       const body = await res.json().catch(() => ({}));
@@ -71,13 +162,15 @@ var AuthAgents = class {
    * Request an authentication challenge nonce.
    *
    * @param did - The agent's DID
+   * @param site_id - Optional site scope for provisioned deployments
    * @returns Challenge ID and nonce to sign
    */
-  async challenge(did) {
+  async challenge(did, site_id) {
     const res = await fetch(`${this.baseUrl}/v1/auth/challenge`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ did })
+      body: JSON.stringify(site_id ? { did, site_id } : { did }),
+      signal: AbortSignal.timeout(1e4)
     });
     if (!res.ok) {
       const body = await res.json().catch(() => ({}));
@@ -90,16 +183,29 @@ var AuthAgents = class {
   /**
    * 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
+   * @param input - challenge_id, did, base64url signature, and optional credential_expires_in
+   * @returns Session token and fresh VC-JWT credential. If API returns 401,
+   *          returns `{ valid: false, error, message }` instead of throwing.
    */
   async authenticate(input) {
     const res = await fetch(`${this.baseUrl}/v1/auth/verify`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(input)
+      body: JSON.stringify(input),
+      signal: AbortSignal.timeout(1e4)
     });
-    return res.json();
+    const body = await res.json().catch(() => ({}));
+    if (res.status === 401) {
+      return {
+        valid: false,
+        error: body.error ?? "signature_invalid",
+        message: body.message ?? "Authentication failed"
+      };
+    }
+    if (!res.ok) {
+      throw new Error(body.error ?? body.message ?? `Authentication failed (${res.status})`);
+    }
+    return body;
   }
 };
 async function verify(credential) {

package/dist/index.mjs

@@ -1,37 +1,128 @@
 // src/index.ts
-var DEFAULT_BASE_URL = "https://auth.getagentauth.com";
+var DEFAULT_BASE_URL = "https://auth.usevigil.dev";
 var AuthAgents = class {
   constructor(config) {
-    this.baseUrl = (config?.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    const url = (config?.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    try {
+      const parsed = new URL(url);
+      if (parsed.protocol !== "https:" && parsed.hostname !== "localhost" && parsed.hostname !== "127.0.0.1") {
+        throw new Error("AuthAgents: baseUrl must use HTTPS (http://localhost allowed for development)");
+      }
+    } catch (e) {
+      if (e instanceof Error && e.message.startsWith("AuthAgents:")) throw e;
+      throw new Error("AuthAgents: baseUrl must be a valid URL");
+    }
+    this.baseUrl = url;
+  }
+  // ---- 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) {
+    if (!privateKeyJwk?.d) {
+      throw new Error("privateKeyJwk must contain the 'd' (private key) parameter");
+    }
+    if (!nonce) {
+      throw new Error("nonce must not be empty");
+    }
+    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.
    *
    * @param credential - The VC-JWT string from the agent
-   * @returns Verified agent identity or error details
+   * @returns Verified agent identity. If API returns 401, returns
+   *          `{ valid: false, error, message }` instead of throwing.
    */
   async verify(credential) {
     const res = await fetch(`${this.baseUrl}/v1/credentials/verify`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ credential })
+      body: JSON.stringify({ credential }),
+      signal: AbortSignal.timeout(1e4)
     });
-    return res.json();
+    const body = await res.json().catch(() => ({}));
+    if (res.status === 401) {
+      return {
+        valid: false,
+        error: body.error ?? "signature_invalid",
+        message: body.message ?? "Credential verification failed"
+      };
+    }
+    if (!res.ok) {
+      throw new Error(body.error ?? body.message ?? `Verify failed (${res.status})`);
+    }
+    return body;
   }
   // ---- 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`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(input)
+      body: JSON.stringify(input),
+      signal: AbortSignal.timeout(1e4)
     });
     if (!res.ok) {
       const body = await res.json().catch(() => ({}));
@@ -46,13 +137,15 @@ var AuthAgents = class {
    * Request an authentication challenge nonce.
    *
    * @param did - The agent's DID
+   * @param site_id - Optional site scope for provisioned deployments
    * @returns Challenge ID and nonce to sign
    */
-  async challenge(did) {
+  async challenge(did, site_id) {
     const res = await fetch(`${this.baseUrl}/v1/auth/challenge`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ did })
+      body: JSON.stringify(site_id ? { did, site_id } : { did }),
+      signal: AbortSignal.timeout(1e4)
     });
     if (!res.ok) {
       const body = await res.json().catch(() => ({}));
@@ -65,16 +158,29 @@ var AuthAgents = class {
   /**
    * 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
+   * @param input - challenge_id, did, base64url signature, and optional credential_expires_in
+   * @returns Session token and fresh VC-JWT credential. If API returns 401,
+   *          returns `{ valid: false, error, message }` instead of throwing.
    */
   async authenticate(input) {
     const res = await fetch(`${this.baseUrl}/v1/auth/verify`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(input)
+      body: JSON.stringify(input),
+      signal: AbortSignal.timeout(1e4)
     });
-    return res.json();
+    const body = await res.json().catch(() => ({}));
+    if (res.status === 401) {
+      return {
+        valid: false,
+        error: body.error ?? "signature_invalid",
+        message: body.message ?? "Authentication failed"
+      };
+    }
+    if (!res.ok) {
+      throw new Error(body.error ?? body.message ?? `Authentication failed (${res.status})`);
+    }
+    return body;
   }
 };
 async function verify(credential) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auth-agents",
-  "version": "0.1.3",
+  "version": "0.4.2",
   "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",
@@ -22,7 +22,7 @@
   },
   "keywords": [
     "agent-auth",
-    "getagentauth",
+    "usevigil",
     "auth-agents",
     "ai-agent",
     "did",
@@ -38,7 +38,7 @@
     "type": "git",
     "url": "https://github.com/AgenthAgent/auth-agents-sdk-node"
   },
-  "homepage": "https://getagentauth.com",
+  "homepage": "https://usevigil.dev",
   "devDependencies": {
     "tsup": "^8.0.0",
     "typescript": "^5.0.0"