@teneo-protocol/sdk 1.0.0

package/dist/utils/signature-verifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature-verifier.js","sourceRoot":"","sources":["../../src/utils/signature-verifier.ts"],"names":[],"mappings":"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"}

package/dist/utils/ssrf-validator.d.ts

@@ -0,0 +1,36 @@
+/**
+ * SSRF (Server-Side Request Forgery) Validator
+ * Prevents webhook URLs from pointing to internal/private network resources
+ *
+ * This utility blocks:
+ * - Private IP ranges (RFC1918: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
+ * - Loopback addresses (127.0.0.0/8, ::1)
+ * - Link-local addresses (169.254.0.0/16, fe80::/10)
+ * - Cloud metadata endpoints (AWS, GCP, Azure, DigitalOcean)
+ * - IPv6 private ranges (fc00::/7, fd00::/8)
+ * - Multicast and broadcast addresses
+ */
+/**
+ * Check if an IP address is in a private range
+ * Supports both IPv4 and IPv6
+ */
+export declare function isPrivateIP(hostname: string): boolean;
+/**
+ * Check if a hostname is a blocked cloud metadata endpoint
+ */
+export declare function isCloudMetadataEndpoint(hostname: string): boolean;
+/**
+ * Check if a hostname is an allowed localhost exception
+ * Only true localhost addresses, not bind-all addresses
+ */
+export declare function isLocalhostException(hostname: string): boolean;
+/**
+ * Validate a webhook URL for SSRF vulnerabilities
+ * Throws an error if the URL is unsafe
+ *
+ * @param url - The webhook URL to validate
+ * @param allowLocalhost - Whether to allow localhost URLs (for development)
+ * @throws Error if URL is unsafe or invalid
+ */
+export declare function validateWebhookUrl(url: string, allowLocalhost?: boolean): void;
+//# sourceMappingURL=ssrf-validator.d.ts.map

package/dist/utils/ssrf-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssrf-validator.d.ts","sourceRoot":"","sources":["../../src/utils/ssrf-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAyCH;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAqCrD;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAOjE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAI9D;AAkBD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,cAAc,GAAE,OAAe,GAAG,IAAI,CAkFrF"}

package/dist/utils/ssrf-validator.js

@@ -0,0 +1,195 @@
+"use strict";
+/**
+ * SSRF (Server-Side Request Forgery) Validator
+ * Prevents webhook URLs from pointing to internal/private network resources
+ *
+ * This utility blocks:
+ * - Private IP ranges (RFC1918: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
+ * - Loopback addresses (127.0.0.0/8, ::1)
+ * - Link-local addresses (169.254.0.0/16, fe80::/10)
+ * - Cloud metadata endpoints (AWS, GCP, Azure, DigitalOcean)
+ * - IPv6 private ranges (fc00::/7, fd00::/8)
+ * - Multicast and broadcast addresses
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPrivateIP = isPrivateIP;
+exports.isCloudMetadataEndpoint = isCloudMetadataEndpoint;
+exports.isLocalhostException = isLocalhostException;
+exports.validateWebhookUrl = validateWebhookUrl;
+const url_1 = require("url");
+/**
+ * Blocked hostnames that should never be accessible via webhooks
+ * Includes cloud provider metadata endpoints and localhost variations
+ */
+const BLOCKED_HOSTNAMES = [
+    // AWS metadata endpoints
+    "169.254.169.254",
+    "fd00:ec2::254",
+    "instance-data",
+    "instance-data.ec2.internal",
+    // Google Cloud metadata
+    "metadata.google.internal",
+    "metadata.google.com",
+    // Azure metadata
+    "169.254.169.254", // Same as AWS
+    // DigitalOcean metadata
+    "169.254.169.254", // Same as AWS/Azure
+    // Kubernetes metadata
+    "kubernetes.default",
+    "kubernetes.default.svc",
+    "kubernetes.default.svc.cluster.local",
+    // Localhost bind-all (not safe for webhooks)
+    "0.0.0.0",
+    "[::]",
+    "::"
+];
+/**
+ * Localhost hostnames that are allowed for development
+ */
+const LOCALHOST_HOSTNAMES = ["localhost", "127.0.0.1", "::1", "[::1]"];
+/**
+ * Check if an IP address is in a private range
+ * Supports both IPv4 and IPv6
+ */
+function isPrivateIP(hostname) {
+    // Remove IPv6 brackets if present
+    const cleanHostname = hostname.replace(/^\[|\]$/g, "");
+    // IPv4 private ranges (RFC1918)
+    if (/^10\./.test(cleanHostname))
+        return true;
+    if (/^192\.168\./.test(cleanHostname))
+        return true;
+    if (/^172\.(1[6-9]|2[0-9]|3[0-1])\./.test(cleanHostname))
+        return true; // 172.16-31
+    // IPv4 loopback (127.0.0.0/8)
+    if (/^127\./.test(cleanHostname))
+        return true;
+    // IPv4 link-local (169.254.0.0/16)
+    if (/^169\.254\./.test(cleanHostname))
+        return true;
+    // IPv4 multicast (224.0.0.0/4)
+    if (/^2(2[4-9]|3[0-9])\./.test(cleanHostname))
+        return true;
+    // IPv4 broadcast
+    if (cleanHostname === "255.255.255.255")
+        return true;
+    // IPv6 private ranges
+    // Link-local (fe80::/10)
+    if (/^fe[89ab][0-9a-f]:/i.test(cleanHostname))
+        return true;
+    // Unique local addresses (fc00::/7)
+    if (/^f[cd][0-9a-f]{2}:/i.test(cleanHostname))
+        return true;
+    // IPv6 loopback (::1)
+    if (cleanHostname === "::1")
+        return true;
+    if (cleanHostname === "0:0:0:0:0:0:0:1")
+        return true;
+    // IPv6 unspecified (::)
+    if (cleanHostname === "::")
+        return true;
+    if (cleanHostname === "0:0:0:0:0:0:0:0")
+        return true;
+    return false;
+}
+/**
+ * Check if a hostname is a blocked cloud metadata endpoint
+ */
+function isCloudMetadataEndpoint(hostname) {
+    const cleanHostname = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    return BLOCKED_HOSTNAMES.some((blocked) => cleanHostname === blocked.toLowerCase() || cleanHostname.endsWith(`.${blocked.toLowerCase()}`));
+}
+/**
+ * Check if a hostname is an allowed localhost exception
+ * Only true localhost addresses, not bind-all addresses
+ */
+function isLocalhostException(hostname) {
+    const cleanHostname = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    return LOCALHOST_HOSTNAMES.some((allowed) => cleanHostname === allowed.toLowerCase());
+}
+/**
+ * Check if hostname resolves to a Kubernetes service
+ * Blocks internal k8s service discovery
+ */
+function isKubernetesService(hostname) {
+    const cleanHostname = hostname.toLowerCase();
+    // Block .svc, .svc.cluster, .svc.cluster.local
+    if (cleanHostname.includes(".svc"))
+        return true;
+    // Block direct kubernetes service names
+    if (cleanHostname.startsWith("kubernetes"))
+        return true;
+    return false;
+}
+/**
+ * Validate a webhook URL for SSRF vulnerabilities
+ * Throws an error if the URL is unsafe
+ *
+ * @param url - The webhook URL to validate
+ * @param allowLocalhost - Whether to allow localhost URLs (for development)
+ * @throws Error if URL is unsafe or invalid
+ */
+function validateWebhookUrl(url, allowLocalhost = false) {
+    let parsed;
+    try {
+        parsed = new url_1.URL(url);
+    }
+    catch (error) {
+        throw new Error(`Invalid webhook URL: ${error.message}`);
+    }
+    const hostname = parsed.hostname;
+    // Check protocol first (basic validation)
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+        throw new Error(`Webhook URL must use HTTP or HTTPS protocol (got: ${parsed.protocol})`);
+    }
+    // Block cloud metadata endpoints FIRST (before any other checks)
+    if (isCloudMetadataEndpoint(hostname)) {
+        throw new Error(`Webhook URL blocked for security: ${hostname} is a cloud metadata endpoint. ` +
+            "This could expose sensitive credentials and secrets.");
+    }
+    // Block Kubernetes services
+    if (isKubernetesService(hostname)) {
+        throw new Error(`Webhook URL blocked for security: ${hostname} appears to be a Kubernetes service. ` +
+            "Internal service discovery is not allowed for webhooks.");
+    }
+    // Check localhost BEFORE private IP check (localhost is specific case of private IP)
+    if (isLocalhostException(hostname)) {
+        if (allowLocalhost) {
+            return; // Localhost is allowed for development
+        }
+        else {
+            throw new Error(`Webhook URL blocked: ${hostname} is a localhost address. ` +
+                "Set allowInsecureWebhooks=true to allow localhost webhooks for testing.");
+        }
+    }
+    // Block private IP ranges
+    if (isPrivateIP(hostname)) {
+        throw new Error(`Webhook URL blocked for security: ${hostname} is a private IP address. ` +
+            "Webhooks cannot point to internal network resources. " +
+            "Use a publicly accessible endpoint or set allowInsecureWebhooks=true for testing.");
+    }
+    // For non-HTTPS, only allow localhost (which already passed checks above)
+    if (parsed.protocol === "http:") {
+        throw new Error("Webhook URL must use HTTPS for non-localhost endpoints. " +
+            "Use HTTPS or set allowInsecureWebhooks=true for testing with localhost.");
+    }
+    // Additional safety: block ports that are commonly internal
+    if (parsed.port) {
+        const port = parseInt(parsed.port, 10);
+        const dangerousPorts = [
+            22, // SSH
+            23, // Telnet
+            25, // SMTP
+            3306, // MySQL
+            5432, // PostgreSQL
+            6379, // Redis
+            9200, // Elasticsearch
+            27017 // MongoDB
+        ];
+        if (dangerousPorts.includes(port)) {
+            throw new Error(`Webhook URL blocked for security: Port ${port} is commonly used for internal services. ` +
+                "Use a different port or set allowInsecureWebhooks=true for testing.");
+        }
+    }
+}
+//# sourceMappingURL=ssrf-validator.js.map

package/dist/utils/ssrf-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssrf-validator.js","sourceRoot":"","sources":["../../src/utils/ssrf-validator.ts"],"names":[],"mappings":"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"}

package/examples/.env.example

@@ -0,0 +1,17 @@
+# Teneo SDK Examples - Environment Configuration
+# Copy this file to .env and fill in your actual values
+
+# Required: WebSocket URL for Teneo network
+WS_URL=wss://developer.chatroom.teneo-protocol.ai/ws
+
+# Required: Your Ethereum private key (keep this secret!)
+PRIVATE_KEY=your-private-key-here
+
+# Optional: Your wallet address (auto-derived from private key if not provided)
+WALLET_ADDRESS=0x...
+
+# Optional: Default room to join on connection
+DEFAULT_ROOM=general
+
+# Optional: Additional room ID (for multi-room examples)
+ROOM_ID=your-room-id-here

package/examples/basic-usage.ts

@@ -0,0 +1,211 @@
+/**
+ * Basic usage example for Teneo Protocol SDK
+ * Demonstrates connection, authentication, and sending messages to agents
+ */
+
+import { TeneoSDK, SDKConfigBuilder, SecurePrivateKey } from "../src";
+
+// Load configuration from environment variables
+const WS_URL =
+  process.env.WS_URL;
+const PRIVATE_KEY = process.env.PRIVATE_KEY || "";
+const WALLET_ADDRESS = process.env.WALLET_ADDRESS;
+const DEFAULT_ROOM = process.env.DEFAULT_ROOM || "general";
+
+async function main() {
+  // Validate required configuration
+  if (!PRIVATE_KEY) {
+    console.error("ERROR: PRIVATE_KEY environment variable is required");
+    console.error("Set it with: export PRIVATE_KEY='your-private-key'");
+    process.exit(1);
+  }
+
+  // SEC-3: Encrypt private key in memory for enhanced security
+  const secureKey = new SecurePrivateKey(PRIVATE_KEY);
+  console.log("✓ Private key encrypted in memory (SEC-3)");
+
+  // Build configuration using fluent API
+  const config = new SDKConfigBuilder()
+    .withWebSocketUrl(WS_URL)
+    .withAuthentication(secureKey, WALLET_ADDRESS) // Use encrypted key
+    .withAutoJoinRooms([DEFAULT_ROOM]) // Auto-join default room on connect
+    .withReconnection({ enabled: true, delay: 5000, maxAttempts: 10 }) // Enable reconnection
+    .withResponseFormat({ format: "both", includeMetadata: true }) // Get both raw and humanized responses with metadata
+    .withLogging("debug") // Enable debug logging
+    .build();
+
+  // Create SDK instance
+  const sdk = new TeneoSDK(config);
+
+  // Set up event listeners
+  setupEventListeners(sdk);
+
+  try {
+    // Connect to Teneo network
+    console.log("\n→ Connecting to Teneo network...");
+    await sdk.connect();
+    console.log("✓ SDK is connected and authenticated!");
+
+    // Show current subscriptions
+    const subscribed = sdk.getSubscribedRooms();
+    console.log(
+      `\n→ Currently subscribed to ${subscribed.length} room(s): ${subscribed.join(", ")}`
+    );
+
+    // Subscribe to additional room if available
+    const rooms = sdk.getRooms();
+    if (rooms.length > 1) {
+      const additionalRoom = rooms.find((r) => r.id !== DEFAULT_ROOM);
+      if (additionalRoom) {
+        console.log(
+          `\n→ Subscribing to additional room: ${additionalRoom.name || additionalRoom.id}`
+        );
+        await sdk.subscribeToRoom(additionalRoom.id);
+
+        // Show updated subscriptions
+        const updatedSubscriptions = sdk.getSubscribedRooms();
+        console.log(`✓ Now subscribed to: ${updatedSubscriptions.join(", ")}`);
+      }
+    }
+
+    // Get list of available agents
+    const agents = sdk.getAgents();
+    console.log(`\n→ Available agents: ${agents.length}`);
+    agents.forEach((agent) => {
+      console.log(`  • ${agent.name}: ${agent.description || "No description"}`);
+    });
+
+    // PERF-3: Demonstrate indexed agent lookups (O(1) complexity)
+    console.log("\n→ Testing indexed agent lookups (PERF-3):");
+
+    // Search by capability (O(1))
+    const weatherAgents = sdk.findAgentsByCapability("weather-forecast");
+    if (weatherAgents.length > 0) {
+      console.log(`  ✓ Found ${weatherAgents.length} agent(s) with weather capability`);
+    }
+
+    // Search by name (O(k) where k = tokens)
+    const searchResults = sdk.findAgentsByName("agent");
+    if (searchResults.length > 0) {
+      console.log(`  ✓ Found ${searchResults.length} agent(s) matching name search`);
+    }
+
+    // Search by status (O(1))
+    const onlineAgents = sdk.findAgentsByStatus("online");
+    console.log(`  ✓ ${onlineAgents.length} agent(s) currently online`);
+
+    // Send message to the room
+    console.log("\n→ Sending message to room...");
+    const response = await sdk.sendMessage("Hello from the Teneo SDK!", {
+      room: DEFAULT_ROOM,
+      waitForResponse: true,
+      timeout: 30000
+    });
+
+    if (response && response.humanized) {
+      console.log("✓ Response received:", response.humanized.substring(0, 200));
+    } else if (response) {
+      console.log("✓ Response received (no humanized content)");
+    }
+
+    // Wait for some messages
+    console.log("\n→ Listening for messages (press Ctrl+C to exit)...");
+    console.log("  Watch the event logs above for real-time updates");
+    await new Promise((resolve) => setTimeout(resolve, 60000));
+  } catch (error) {
+    console.error("\n✗ Error:", error);
+  } finally {
+    // Clean up
+    console.log("\n→ Disconnecting...");
+    sdk.disconnect();
+    sdk.destroy();
+    console.log("✓ Cleanup complete");
+  }
+}
+
+function setupEventListeners(sdk: TeneoSDK) {
+  // Connection events
+  sdk.on("connection:open", () => {
+    console.log("[CONNECTION] Connected to WebSocket");
+  });
+
+  sdk.on("connection:close", (code, reason) => {
+    console.log(`[CONNECTION] Disconnected: ${code} - ${reason}`);
+  });
+
+  sdk.on("connection:reconnecting", (attempt) => {
+    console.log(`[CONNECTION] Reconnecting... (attempt ${attempt})`);
+  });
+
+  sdk.on("connection:reconnected", () => {
+    console.log("[CONNECTION] Reconnected successfully");
+  });
+
+  // Authentication events
+  sdk.on("auth:challenge", (challenge) => {
+    console.log(`[AUTH] Authentication challenge received: ${challenge.substring(0, 10)}...`);
+  });
+
+  sdk.on("auth:success", (state) => {
+    console.log(`[AUTH] Authenticated as: ${state.walletAddress}`);
+    console.log(`[AUTH]    Whitelisted: ${state.isWhitelisted}`);
+    console.log(`[AUTH]    Rooms: ${state.rooms?.join(", ") || "None"}`);
+  });
+
+  sdk.on("auth:error", (error) => {
+    console.log(`[AUTH] Authentication failed: ${error}`);
+  });
+
+  // Agent events
+  sdk.on("agent:selected", (data) => {
+    console.log(`\n[AGENT] Coordinator selected: ${data.agentName}`);
+    console.log(`[AGENT]    Reasoning: ${data.reasoning}`);
+    if (data.command) {
+      console.log(`[AGENT]    Command: ${data.command}`);
+    }
+  });
+
+  sdk.on("agent:response", (response) => {
+    console.log(`\n[AGENT] Response from ${response.agentName || response.agentId}:`);
+    console.log(`[AGENT]    Content: ${response.humanized || response.content}`);
+    if (response.error) {
+      console.log(`[AGENT]    Error: ${response.error}`);
+    }
+  });
+
+  sdk.on("agent:list", (agents) => {
+    console.log(`\n[AGENT] Agent list updated: ${agents.length} agents`);
+  });
+
+  // Room events
+  sdk.on("room:subscribed", (data) => {
+    console.log(`[ROOM] Subscribed to room: ${data.roomId}`);
+  });
+
+  sdk.on("room:unsubscribed", (data) => {
+    console.log(`[ROOM] Unsubscribed from room: ${data.roomId}`);
+  });
+
+  // Webhook events
+  sdk.on("webhook:sent", (_payload, url) => {
+    console.log(`[WEBHOOK] Webhook sent to ${url}`);
+  });
+
+  sdk.on("webhook:error", (error, url) => {
+    console.log(`[WEBHOOK] Webhook error for ${url}: ${error.message}`);
+  });
+
+  // Error events
+  sdk.on("error", (error) => {
+    console.error(`[ERROR] SDK Error: ${error.message}`);
+  });
+
+  sdk.on("warning", (warning) => {
+    console.warn(`[WARNING] ${warning}`);
+  });
+}
+
+// Run the example
+if (require.main === module) {
+  main().catch(console.error);
+}

package/examples/production-dashboard/.env.example

@@ -0,0 +1,153 @@
+# Teneo Production Dashboard - Environment Configuration
+# Copy this file to .env and fill in your values
+
+# ============================================================================
+# REQUIRED: Teneo Network Connection
+# ============================================================================
+
+# WebSocket URL for Teneo AI Network
+WS_URL=wss://developer.chatroom.teneo-protocol.ai/ws
+
+# Ethereum Private Key (with 0x prefix)
+# IMPORTANT: Never commit your actual private key to version control!
+PRIVATE_KEY=0x
+
+# Ethereum Wallet Address (with 0x prefix)
+# If not provided, will be derived from the private key
+WALLET_ADDRESS=0x
+
+# ============================================================================
+# OPTIONAL: Room Configuration
+# ============================================================================
+
+# Default room to join on connection
+# Leave empty to not auto-join any room
+DEFAULT_ROOM=general
+
+# Comma-separated list of rooms to auto-join
+# Example: general,support,tech-help
+# AUTO_JOIN_ROOMS=general,support
+
+# ============================================================================
+# OPTIONAL: Server Configuration
+# ============================================================================
+
+# Port for the dashboard server (default: 3000)
+PORT=3000
+
+# Node environment (development | production)
+NODE_ENV=development
+
+# ============================================================================
+# OPTIONAL: Security Features
+# ============================================================================
+
+# Enable message signature verification (true | false)
+# Verifies Ethereum signatures on incoming messages from agents
+# Recommended: true for production
+ENABLE_SIGNATURE_VERIFICATION=false
+
+# Comma-separated list of trusted agent Ethereum addresses
+# Only messages signed by these addresses will be accepted (if verification enabled)
+# Leave empty to allow all signed messages
+# Example: 0xAgent1...,0xAgent2...,0xAgent3...
+TRUSTED_ADDRESSES=
+
+# Require signatures for specific message types (comma-separated)
+# Options: task_response,agent_selected,message,error
+# Default: task_response,agent_selected
+# REQUIRE_SIGNATURES_FOR=task_response,agent_selected
+
+# Strict signature mode (true | false)
+# true: Reject ALL unsigned messages
+# false: Warn about unsigned messages but allow them
+# STRICT_SIGNATURE_MODE=false
+
+# ============================================================================
+# OPTIONAL: Webhook Configuration
+# ============================================================================
+
+# Webhook URL to receive SDK events
+# Auto-configured to localhost for development
+# For production, use your publicly accessible webhook endpoint
+# Example: https://api.example.com/webhooks/teneo
+WEBHOOK_URL=http://localhost:3000/webhook
+
+# Webhook authentication header (optional)
+# WEBHOOK_AUTH_TOKEN=your-secret-token
+
+# Max webhook retries on failure (0-10)
+WEBHOOK_RETRIES=3
+
+# Webhook timeout in milliseconds (1000-60000)
+WEBHOOK_TIMEOUT=10000
+
+# ============================================================================
+# OPTIONAL: SDK Performance Tuning
+# ============================================================================
+
+# Enable agent caching (true | false)
+ENABLE_CACHE=true
+
+# Cache timeout in milliseconds (default: 300000 = 5 minutes)
+CACHE_TIMEOUT=300000
+
+# Maximum cache size (default: 100)
+MAX_CACHE_SIZE=100
+
+# ============================================================================
+# OPTIONAL: Connection Settings
+# ============================================================================
+
+# Enable automatic reconnection (true | false)
+ENABLE_RECONNECTION=true
+
+# Reconnection delay in milliseconds (100-60000)
+RECONNECT_DELAY=5000
+
+# Maximum reconnection attempts (0-100, 0 = infinite)
+MAX_RECONNECT_ATTEMPTS=10
+
+# Connection timeout in milliseconds (1000-120000)
+CONNECTION_TIMEOUT=30000
+
+# ============================================================================
+# OPTIONAL: Logging
+# ============================================================================
+
+# Log level (debug | info | warn | error | silent)
+# debug: Very verbose, shows all SDK operations
+# info: Normal operations and important events
+# warn: Warnings and potential issues
+# error: Errors only
+# silent: No logging
+LOG_LEVEL=info
+
+# ============================================================================
+# NOTES
+# ============================================================================
+
+# 1. Environment Precedence:
+#    - Environment variables override .env file values
+#    - .env file overrides default SDK values
+#
+# 2. Security Best Practices:
+#    - Never commit .env file to git (already in .gitignore)
+#    - Use different private keys for dev/prod
+#    - Enable signature verification in production
+#    - Use HTTPS webhooks in production
+#
+# 3. Development Tips:
+#    - Set LOG_LEVEL=debug for troubleshooting
+#    - Disable signature verification for local testing
+#    - Use localhost webhooks for development
+#
+# 4. Production Checklist:
+#    ✓ Use production WebSocket URL
+#    ✓ Use secure private key (from secrets manager)
+#    ✓ Enable signature verification
+#    ✓ Set trusted agent addresses
+#    ✓ Use HTTPS webhook URLs
+#    ✓ Set LOG_LEVEL=info or warn
+#    ✓ Enable all security features
+#    ✓ Use environment variables (not .env file)

package/examples/production-dashboard/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@teneo/production-dashboard-example",
+  "version": "1.0.0",
+  "description": "Production-ready dashboard example for Teneo Protocol SDK using Hono and Bun",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "bun --watch server.ts",
+    "start": "bun run server.ts",
+    "build": "bun build server.ts --outdir dist --target bun",
+    "serve": "bun run dist/server.js"
+  },
+  "dependencies": {
+    "hono": "^4.0.0",
+    "@hono/node-server": "^1.8.0",
+    "dotenv": "^16.4.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "engines": {
+    "bun": ">=1.0.0",
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "teneo",
+    "sdk",
+    "dashboard",
+    "hono",
+    "bun",
+    "websocket",
+    "ai",
+    "agents",
+    "example",
+    "production"
+  ],
+  "author": "Teneo",
+  "license": "MIT"
+}