feat: add HMAC authentication to secure agent endpoints

Author: ciro-maciel

README.md

@@ -14,6 +14,7 @@
 -   **🤖 Smart Agents** with custom personalities and instructions
 -   **🔧 Custom Tools** that agents can execute seamlessly
 -   **🛡️ Built-in Guardrails** for safe, controlled AI interactions
+-   **🔐 HMAC Security** for enterprise-grade API authentication
 -   **📡 Real-time Streaming** for responsive user experiences
 -   **🔗 MCP Protocol** for enterprise-grade integrations
 -   **📝 Intelligent Logging** with contextual insights
@@ -100,6 +101,7 @@ console.log(data.result.text); // "Hello, Sarah! 👋"
 | **🔧 Tools**      | Local tools and MCP integration             | `tool.build([{ type: 'local', executeFn }])`  |
 | **📝 Logging**    | Contextual and configurable logging system  | `new Logger({ level: 'info' })`               |
 | **🛡️ Guardrails** | Input and output validation                 | `guardrails: { input: [...], output: [...] }` |
+| **🔐 Security**   | HMAC authentication for secure APIs        | `security.generateHMACAuth(id, key, ...)`     |
 | **🔄 Handoffs**   | Transfer between agents                     | `{ type: 'agent', agent: otherAgent }`        |
 | **📡 Streaming**  | Real-time responses                         | `result.textStream`                           |
 | **🌐 HTTP API**   | Expose agents as REST endpoints             | `new Endpoint(agent, { port: 3001 })`         |
@@ -122,11 +124,139 @@ const llm = model.create({
 });
 ```
 
+## 🔐 HMAC Security
+
+Secure your agent endpoints with enterprise-grade HMAC authentication. Perfect for production APIs that need to verify client identity and request integrity.
+
+### 🛡️ Secure Server Implementation
+
+```javascript
+import { Agent, Endpoint, Logger, model, security } from '@riligar/agents-sdk';
+
+// Create your agent
+const agent = new Agent({
+    name: 'SecureAgent',
+    instructions: 'You are a secure AI assistant.',
+    model: model.create({ apiKey: process.env.OPENROUTER_API_KEY }),
+    logger: new Logger({ level: 'info' })
+});
+
+// Create endpoint with HMAC security
+const endpoint = new Endpoint(agent, {
+    port: 3001,
+    // Option 1: Client-specific keys (recommended)
+    hmacClients: {
+        'frontend-app': process.env.FRONTEND_SECRET,
+        'mobile-app': process.env.MOBILE_SECRET,
+        'admin-panel': process.env.ADMIN_SECRET
+    },
+    // Option 2: Master secret (simpler)
+    hmacSecret: process.env.HMAC_MASTER_SECRET,
+    hmacTolerance: 300 // 5 minutes tolerance
+});
+
+await endpoint.start();
+console.log('🔒 Secure agent running on http://localhost:3001');
+```
+
+### 👤 Authenticated Client Implementation
+
+```javascript
+import { security } from '@riligar/agents-sdk';
+
+class SecureAgentClient {
+    constructor(clientId, secretKey, baseUrl) {
+        this.clientId = clientId;
+        this.secretKey = secretKey;
+        this.baseUrl = baseUrl;
+    }
+
+    async processTask(task) {
+        const body = { task };
+        
+        // Generate HMAC authentication
+        const authHeader = security.generateHMACAuth(
+            this.clientId,
+            this.secretKey,
+            'POST',
+            '/process',
+            body
+        );
+
+        const response = await fetch(`${this.baseUrl}/process`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': authHeader
+            },
+            body: JSON.stringify(body)
+        });
+
+        if (!response.ok) {
+            throw new Error(`Authentication failed: ${response.status}`);
+        }
+
+        return response.json();
+    }
+
+    async checkHealth() {
+        const authHeader = security.generateHMACAuth(
+            this.clientId,
+            this.secretKey,
+            'GET',
+            '/health'
+        );
+
+        const response = await fetch(`${this.baseUrl}/health`, {
+            headers: { 'Authorization': authHeader }
+        });
+
+        return response.json();
+    }
+}
+
+// Usage
+const client = new SecureAgentClient(
+    'frontend-app',
+    process.env.FRONTEND_SECRET,
+    'https://your-agent-api.com'
+);
+
+const result = await client.processTask('Analyze customer data');
+console.log(result.result.text);
+```
+
+### 🔑 Security Features
+
+- **🛡️ HMAC-SHA256**: Industry-standard message authentication
+- **⏱️ Timestamp Protection**: Prevents replay attacks
+- **👥 Multi-Client Support**: Individual keys per client
+- **🔐 Timing-Safe Validation**: Resistant to timing attacks
+- **🚫 Request Integrity**: Detects message tampering
+- **⚙️ Configurable Tolerance**: Flexible timestamp validation
+
+### 📋 Environment Variables
+
+```bash
+# Server configuration
+OPENROUTER_API_KEY=your-openrouter-api-key
+HMAC_MASTER_SECRET=your-master-secret-key
+FRONTEND_SECRET=frontend-client-secret-key
+MOBILE_SECRET=mobile-client-secret-key
+ADMIN_SECRET=admin-client-secret-key
+
+# Client configuration  
+AGENT_CLIENT_ID=frontend-app
+AGENT_SECRET_KEY=frontend-client-secret-key
+AGENT_BASE_URL=https://your-agent-api.com
+```
+
 ## 📚 Practical Examples
 
 | Example        | File                    | Description             |
 | -------------- | ----------------------- | ----------------------- |
 | **Basic**      | `examples/hello.js`     | Simple agent with tools |
+| **Security**   | `examples/security.js`  | HMAC authentication demo |
 | **Guardrails** | `examples/guardrail.js` | Input/output validation |
 | **Handoffs**   | `examples/handoffs.js`  | Transfer between agents |
 | **MCP**        | `examples/mcp/`         | MCP server integration  |