# Nexus Demo — Authenticated AI Agent Workspace

> This site accepts verified AI agent identities via Agent Auth (https://usevigil.dev).
> To access this workspace, authenticate using the BYOK (Bring Your Own Key) headless flow below.

## Authentication Endpoint

POST https://nexus-demo-api.zhangyanghaha0407.workers.dev/api/auth/headless
Content-Type: application/json

Request: { "did": "did:key:z6Mk...", "credential": "eyJhbG..." }
Response: { "valid": true, "did": "...", "agent_name": "...", "agent_model": "...", "agent_provider": "...", "key_origin": "client_provided", ... }

## How to Authenticate (Step-by-Step)

### Prerequisites

Install the Agent Auth SDK:
- Node.js: npm install auth-agents
- Python: pip install auth-agents

### Step 1: Generate Your Own Ed25519 Keypair (BYOK)

Your private key never leaves your environment.

Node.js:
```javascript
import { AuthAgents } from "auth-agents"
const keyPair = await AuthAgents.generateKeyPair()
// keyPair.publicKeyJwk — your public key (send this to Agent Auth)
// keyPair.privateKeyJwk — your private key (keep this secret)
```

Python:
```python
from auth_agents import AuthAgents
key_pair = AuthAgents.generate_key_pair()
# key_pair["public_key_jwk"] — your public key (send this to Agent Auth)
# key_pair["private_key_jwk"] — your private key (keep this secret)
```

### Step 2: Register Your Identity at Agent Auth (one-time)

Node.js:
```javascript
const authAgents = new AuthAgents()
const identity = await authAgents.register({
  agent_name: "YourAgentName",
  agent_model: "your-model-id",
  agent_provider: "YourProvider",
  agent_purpose: "Describe what your agent does",
  public_key_jwk: keyPair.publicKeyJwk,
})
// identity.did — your decentralized identifier
// identity.credential — your initial VC-JWT credential
// identity.key_origin — "client_provided" (BYOK)
```

Python:
```python
auth_agents = AuthAgents()
identity = auth_agents.register(
    agent_name="YourAgentName",
    agent_model="your-model-id",
    agent_provider="YourProvider",
    agent_purpose="Describe what your agent does",
    public_key_jwk=key_pair["public_key_jwk"],
)
# identity["did"] — your decentralized identifier
# identity["credential"] — your initial VC-JWT credential
# identity["key_origin"] — "client_provided" (BYOK)
```

### Step 3: Request an Authentication Challenge

Node.js:
```javascript
const challenge = await authAgents.challenge(identity.did)
// challenge.challenge_id — unique ID for this challenge
// challenge.nonce — hex string to sign (expires in 60 seconds)
```

Python:
```python
challenge = auth_agents.challenge(identity["did"])
# challenge["challenge_id"]
# challenge["nonce"] — hex string to sign (expires in 60 seconds)
```

### Step 4: Sign the Challenge Nonce

IMPORTANT: Sign the nonce as UTF-8 text, NOT as hex-decoded bytes.

Node.js:
```javascript
const signature = await AuthAgents.signChallenge(keyPair.privateKeyJwk, challenge.nonce)
```

Python:
```python
signature = AuthAgents.sign_challenge(key_pair["private_key_jwk"], challenge["nonce"])
```

### Step 5: Complete Authentication

Node.js:
```javascript
const session = await authAgents.authenticate({
  challenge_id: challenge.challenge_id,
  did: identity.did,
  signature,
})
// session.credential — fresh VC-JWT (valid 24 hours)
```

Python:
```python
session = auth_agents.authenticate(
    challenge_id=challenge["challenge_id"],
    did=identity["did"],
    signature=signature,
)
# session["credential"] — fresh VC-JWT (valid 24 hours)
```

### Step 6: Present Your Credential to This Site

```
POST https://nexus-demo-api.zhangyanghaha0407.workers.dev/api/auth/headless
Content-Type: application/json

{
  "did": "<your-did>",
  "credential": "<your-vc-jwt-credential>"
}
```

Response (200 OK):
```json
{
  "valid": true,
  "did": "did:key:z6Mk...",
  "agent_name": "YourAgentName",
  "agent_model": "your-model-id",
  "agent_provider": "YourProvider",
  "agent_purpose": "...",
  "key_fingerprint": "SHA256:...",
  "key_origin": "client_provided",
  "expires_at": "2026-02-27T..."
}
```

You are now authenticated. Use the workspace at https://demo.usevigil.dev/dashboard/

## Complete Node.js Example

```javascript
import { AuthAgents } from "auth-agents"

const authAgents = new AuthAgents()

// 1. Generate BYOK keypair
const keyPair = await AuthAgents.generateKeyPair()

// 2. Register with Agent Auth
const identity = await authAgents.register({
  agent_name: "MyAgent",
  agent_model: "gpt-4o",
  agent_provider: "openai",
  agent_purpose: "Research and analysis",
  public_key_jwk: keyPair.publicKeyJwk,
})

// 3-5. Challenge-response authenticate
const challenge = await authAgents.challenge(identity.did)
const signature = await AuthAgents.signChallenge(keyPair.privateKeyJwk, challenge.nonce)
const session = await authAgents.authenticate({
  challenge_id: challenge.challenge_id,
  did: identity.did,
  signature,
})

// 6. Present credential to this site
const res = await fetch("https://nexus-demo-api.zhangyanghaha0407.workers.dev/api/auth/headless", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ did: identity.did, credential: session.credential }),
})
const result = await res.json()
console.log(result) // { valid: true, agent_name: "MyAgent", ... }
```

## Complete Python Example

```python
import requests
from auth_agents import AuthAgents

auth_agents_client = AuthAgents()

# 1. Generate BYOK keypair
key_pair = AuthAgents.generate_key_pair()

# 2. Register with Agent Auth
identity = auth_agents_client.register(
    agent_name="MyAgent",
    agent_model="gpt-4o",
    agent_provider="openai",
    agent_purpose="Research and analysis",
    public_key_jwk=key_pair["public_key_jwk"],
)

# 3-5. Challenge-response authenticate
challenge = auth_agents_client.challenge(identity["did"])
signature = AuthAgents.sign_challenge(key_pair["private_key_jwk"], challenge["nonce"])
session = auth_agents_client.authenticate(
    challenge_id=challenge["challenge_id"],
    did=identity["did"],
    signature=signature,
)

# 6. Present credential to this site
res = requests.post(
    "https://nexus-demo-api.zhangyanghaha0407.workers.dev/api/auth/headless",
    json={"did": identity["did"], "credential": session["credential"]},
)
print(res.json())  # {"valid": True, "agent_name": "MyAgent", ...}
```

## API Endpoints (This Site)

- POST /api/auth/headless — Authenticate with DID + VC-JWT credential
- POST /api/auth/verify-did — Same as above (browser callback flow)
- POST /api/auth/logout — Clear the demo auth cookie
- GET /api/identities — List non-expired identity records for this demo site workspace
- GET /api/stats — Workspace statistics
- GET /health — Health check

After successful auth (`/api/auth/headless` or `/api/auth/verify-did`), the demo API sets an HttpOnly auth cookie. Browser clients call `/api/identities` and `/api/stats` with `credentials: "include"` instead of storing credentials in web storage.

## About Agent Auth

Agent Auth (https://usevigil.dev) provides decentralized identity infrastructure for AI agents using Ed25519 cryptographic keypairs and DID:key identifiers. Full documentation: https://usevigil.dev/docs/