auth-agents 0.4.0 → 0.4.3

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Auth-Agents
-
-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.
+MIT License
+
+Copyright (c) 2026 Auth-Agents
+
+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/README.md

@@ -1,257 +1,278 @@
-# auth-agents
-
-Verify AI agent identities with [Agent Auth](https://getagentauth.com). DID-based authentication using Ed25519 and Verifiable Credentials.
-
-## Install
-
-```bash
-npm install auth-agents
-```
-
-## Quick Start — Verify a Credential
-
-```typescript
-import { AuthAgents } from "auth-agents"
-
-const client = new AuthAgents()
-
-const result = await client.verify("eyJhbGciOiJFZERTQSJ9...")
-
-if (result.valid) {
-  console.log(result.did)            // "did:key:z6Mk..."
-  console.log(result.agent_name)     // "Claude"
-  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
-import { AuthAgents } from "auth-agents"
-
-const authAgents = new AuthAgents()
-
-export async function POST(request: Request) {
-  const { credential } = await request.json()
-
-  const result = await authAgents.verify(credential)
-
-  if (!result.valid) {
-    return Response.json({ error: result.message }, { status: 401 })
-  }
-
-  // Create a session with the verified agent identity
-  const sessionId = crypto.randomUUID()
-  await db.insert("sessions", {
-    session_id: sessionId,
-    did: result.did,
-    agent_name: result.agent_name,
-    agent_model: result.agent_model,
-    key_origin: result.key_origin,
-    expires_at: result.expires_at,
-  })
-
-  return Response.json({ authenticated: true, session_id: sessionId })
-}
-```
-
-## Website Integration (Express.js)
-
-```typescript
-import express from "express"
-import { AuthAgents } from "auth-agents"
-
-const app = express()
-const authAgents = new AuthAgents()
-
-app.post("/auth/agent", express.json(), async (req, res) => {
-  const { credential } = req.body
-  const result = await authAgents.verify(credential)
-
-  if (!result.valid) {
-    return res.status(401).json({ error: result.message })
-  }
-
-  // Agent verified — create session
-  req.session.agent = {
-    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 })
-})
-```
-
-## API
-
-### `new AuthAgents(config?)`
-
-- `config.baseUrl` — API base URL (default: `https://auth.getagentauth.com`)
-
-### `AuthAgents.generateKeyPair()` — Static
-
-Generate a local Ed25519 key pair using the Web Crypto API. No network call.
-
-Returns `Ed25519KeyPair`:
-```typescript
-{
-  publicKeyJwk:  { kty: string; crv: string; x: string }
-  privateKeyJwk: { kty: string; crv: string; x: string; d: string }
-}
-```
-
-### `AuthAgents.signChallenge(privateKeyJwk, nonce)` — Static
-
-Sign an authentication challenge nonce with an Ed25519 private key. No network call.
-
-- `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).
-
+# auth-agents
+
+Verify AI agent identities with [Agent Auth](https://usevigil.dev). DID-based authentication using Ed25519 and Verifiable Credentials.
+
+## Install
+
+```bash
+npm install auth-agents
+```
+
+## Quick Start — Verify a Credential
+
+```typescript
+import { AuthAgents } from "auth-agents"
+
+const client = new AuthAgents()
+
+const result = await client.verify("eyJhbGciOiJFZERTQSJ9...")
+
+if (result.valid) {
+  console.log(result.did)            // "did:key:z6Mk..."
+  console.log(result.agent_name)     // "Claude"
+  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-login/route.ts
+import { AuthAgents } from "auth-agents"
+
+const authAgents = new AuthAgents()
+
+export async function POST(request: Request) {
+  const { credential } = await request.json()
+
+  const result = await authAgents.verify(credential)
+
+  if (!result.valid) {
+    return Response.json({ error: result.message }, { status: 401 })
+  }
+
+  // Create a session with the verified agent identity
+  const sessionId = crypto.randomUUID()
+  await db.insert("sessions", {
+    session_id: sessionId,
+    did: result.did,
+    agent_name: result.agent_name,
+    agent_model: result.agent_model,
+    key_origin: result.key_origin,
+    expires_at: result.expires_at,
+  })
+
+  return Response.json({ authenticated: true, session_id: sessionId })
+}
+```
+
+## Website Integration (Express.js)
+
+```typescript
+import express from "express"
+import { AuthAgents } from "auth-agents"
+
+const app = express()
+const authAgents = new AuthAgents()
+
+app.post("/auth/agent-login", express.json(), async (req, res) => {
+  const { credential } = req.body
+  const result = await authAgents.verify(credential)
+
+  if (!result.valid) {
+    return res.status(401).json({ error: result.message })
+  }
+
+  // Agent verified — create session
+  req.session.agent = {
+    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 })
+})
+```
+
+## API
+
+### `new AuthAgents(config?)`
+
+- `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.
+
+### `AuthAgents.generateKeyPair()` — Static
+
+Generate a local Ed25519 key pair using the Web Crypto API. No network call.
+
+Returns `Ed25519KeyPair`:
+```typescript
+{
+  publicKeyJwk:  { kty: string; crv: string; x: string }
+  privateKeyJwk: { kty: string; crv: string; x: string; d: string }
+}
+```
+
+### `AuthAgents.signChallenge(privateKeyJwk, nonce)` — Static
+
+Sign an authentication challenge nonce with an Ed25519 private key. No network call.
+
+- `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
+
+`input.public_key_jwk` is optional. Omit it for server-generated keys (Flow A). Provide it for BYOK (Flow B).
+You can also pass:
+- `metadata` — key/value metadata map (max key/value sizes enforced server-side)
+
 Returns `RegisterResult`:
 ```typescript
 {
   did: string
-  credential: string
-  key_fingerprint: 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
+Registration always returns a credential with the server default lifetime (24 hours).
+If you need a different lifetime, pass `credential_expires_in` to `client.challenge(...)`.
 
-### `client.authenticate(input)` — Submit signed challenge
+### `client.challenge(did, site_id?, credential_expires_in?)` — Request an auth challenge
 
-## Documentation
+`site_id` is optional and scopes the challenge/session when your deployment uses site-level org provisioning.
 
-Full API reference at [getagentauth.com/docs](https://getagentauth.com/docs/)
+`credential_expires_in` is optional and allows website developers to set the credential lifetime in seconds for the resulting authentication. Use `0` for non-expiring credentials. Min 300, max 2592000.
 
-## License
+### `client.authenticate(input)` — Submit signed challenge
 
-MIT - Agent Auth
+`input` contains `challenge_id`, `did`, and `signature` (base64url-encoded).
+The credential returned from `client.authenticate(...)` uses the lifetime chosen in the preceding `client.challenge(...)` call.
+
+## Documentation
+
+Full API reference at [usevigil.dev/docs](https://usevigil.dev/docs/)
+
+## License
+
+MIT - Agent Auth

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 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() */
@@ -30,7 +30,7 @@ interface VerifyResult {
 }
 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;
@@ -44,6 +44,7 @@ interface RegisterInput {
         crv: string;
         x: string;
     };
+    metadata?: Record<string, string>;
 }
 interface RegisterResult {
     did: string;
@@ -120,7 +121,8 @@ declare class AuthAgents {
      * 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>;
     /**
@@ -136,14 +138,17 @@ declare class AuthAgents {
      * Request an authentication challenge nonce.
      *
      * @param did - The agent's DID
+     * @param site_id - Optional site scope for provisioned deployments
+     * @param credential_expires_in - Optional credential lifetime in seconds (set by website developer). Use 0 for non-expiring. Min 300, max 2592000.
      * @returns Challenge ID and nonce to sign
      */
-    challenge(did: string): Promise<ChallengeResult>;
+    challenge(did: string, site_id?: string, credential_expires_in?: number): 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
+     * @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>;
 }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 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() */
@@ -30,7 +30,7 @@ interface VerifyResult {
 }
 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;
@@ -44,6 +44,7 @@ interface RegisterInput {
         crv: string;
         x: string;
     };
+    metadata?: Record<string, string>;
 }
 interface RegisterResult {
     did: string;
@@ -120,7 +121,8 @@ declare class AuthAgents {
      * 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>;
     /**
@@ -136,14 +138,17 @@ declare class AuthAgents {
      * Request an authentication challenge nonce.
      *
      * @param did - The agent's DID
+     * @param site_id - Optional site scope for provisioned deployments
+     * @param credential_expires_in - Optional credential lifetime in seconds (set by website developer). Use 0 for non-expiring. Min 300, max 2592000.
      * @returns Challenge ID and nonce to sign
      */
-    challenge(did: string): Promise<ChallengeResult>;
+    challenge(did: string, site_id?: string, credential_expires_in?: number): 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
+     * @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>;
 }

package/dist/index.js

@@ -24,10 +24,20 @@ __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 ---------------------------------------------
   /**
@@ -72,6 +82,12 @@ var AuthAgents = class {
    * @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"] },
@@ -94,15 +110,28 @@ var AuthAgents = class {
    * 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 ------------------------------------------------
   /**
@@ -117,12 +146,13 @@ var AuthAgents = class {
     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(() => ({}));
       throw new Error(
-        body.error ?? `Registration failed (${res.status})`
+        body.error_description ?? body.error ?? `Registration failed (${res.status})`
       );
     }
     return res.json();
@@ -132,18 +162,24 @@ var AuthAgents = class {
    * Request an authentication challenge nonce.
    *
    * @param did - The agent's DID
+   * @param site_id - Optional site scope for provisioned deployments
+   * @param credential_expires_in - Optional credential lifetime in seconds (set by website developer). Use 0 for non-expiring. Min 300, max 2592000.
    * @returns Challenge ID and nonce to sign
    */
-  async challenge(did) {
+  async challenge(did, site_id, credential_expires_in) {
+    const payload = { did };
+    if (site_id) payload.site_id = site_id;
+    if (credential_expires_in !== void 0) payload.credential_expires_in = credential_expires_in;
     const res = await fetch(`${this.baseUrl}/v1/auth/challenge`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ did })
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(1e4)
     });
     if (!res.ok) {
       const body = await res.json().catch(() => ({}));
       throw new Error(
-        body.error ?? `Challenge failed (${res.status})`
+        body.error_description ?? body.error ?? `Challenge failed (${res.status})`
       );
     }
     return res.json();
@@ -152,15 +188,28 @@ 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
+   * @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,8 +1,18 @@
 // 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 ---------------------------------------------
   /**
@@ -47,6 +57,12 @@ var AuthAgents = class {
    * @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"] },
@@ -69,15 +85,28 @@ var AuthAgents = class {
    * 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 ------------------------------------------------
   /**
@@ -92,12 +121,13 @@ var AuthAgents = class {
     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(() => ({}));
       throw new Error(
-        body.error ?? `Registration failed (${res.status})`
+        body.error_description ?? body.error ?? `Registration failed (${res.status})`
       );
     }
     return res.json();
@@ -107,18 +137,24 @@ var AuthAgents = class {
    * Request an authentication challenge nonce.
    *
    * @param did - The agent's DID
+   * @param site_id - Optional site scope for provisioned deployments
+   * @param credential_expires_in - Optional credential lifetime in seconds (set by website developer). Use 0 for non-expiring. Min 300, max 2592000.
    * @returns Challenge ID and nonce to sign
    */
-  async challenge(did) {
+  async challenge(did, site_id, credential_expires_in) {
+    const payload = { did };
+    if (site_id) payload.site_id = site_id;
+    if (credential_expires_in !== void 0) payload.credential_expires_in = credential_expires_in;
     const res = await fetch(`${this.baseUrl}/v1/auth/challenge`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ did })
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(1e4)
     });
     if (!res.ok) {
       const body = await res.json().catch(() => ({}));
       throw new Error(
-        body.error ?? `Challenge failed (${res.status})`
+        body.error_description ?? body.error ?? `Challenge failed (${res.status})`
       );
     }
     return res.json();
@@ -127,15 +163,28 @@ 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
+   * @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,46 +1,46 @@
-{
-  "name": "auth-agents",
-  "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",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js"
-    }
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "agent-auth",
-    "getagentauth",
-    "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://getagentauth.com",
-  "devDependencies": {
-    "tsup": "^8.0.0",
-    "typescript": "^5.0.0"
-  }
-}
+{
+  "name": "auth-agents",
+  "version": "0.4.3",
+  "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",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "agent-auth",
+    "usevigil",
+    "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://usevigil.dev",
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  }
+}