network-ai 3.1.0 → 3.1.3

package/README.md

@@ -2,7 +2,8 @@
 
 **The plug-and-play AI agent orchestrator for TypeScript/Node.js -- connect 12 agent frameworks with zero glue code**
 
-[![Release](https://img.shields.io/badge/release-v3.1.0-blue.svg)](https://github.com/jovanSAPFIONEER/Network-AI/releases)
+[![Release](https://img.shields.io/badge/release-v3.1.2-blue.svg)](https://github.com/jovanSAPFIONEER/Network-AI/releases)
+[![ClawHub](https://img.shields.io/badge/ClawHub-network--ai-orange.svg)](https://clawhub.ai/skills/network-ai)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6.svg)](https://typescriptlang.org)
 [![Python](https://img.shields.io/badge/python-3.9+-green.svg)](https://python.org)
@@ -122,6 +123,7 @@ Network-AI wraps your agent swarm with **file-system mutexes**, **atomic commits
 ### Security Module (Defense-in-Depth)
 - **HMAC-Signed Tokens** -- Cryptographic token generation with expiration
 - **Input Sanitization** -- XSS, injection, path traversal, and prototype pollution prevention
+- **Blackboard Path Safety** -- Change ID sanitization prevents directory traversal in atomic commits
 - **Rate Limiting** -- Per-agent request throttling with lockout on failed auth
 - **AES-256-GCM Encryption** -- Encrypt sensitive blackboard entries at rest
 - **Privilege Escalation Prevention** -- Trust-ceiling enforcement
@@ -229,10 +231,10 @@ Copy this skill into your OpenClaw workspace:
 cp -r Network-AI ~/.openclaw/workspace/skills/swarm-orchestrator
 ```
 
-Or install via ClawHub (when available):
+Or install via ClawHub:
 
 ```bash
-openclaw skills install swarm-orchestrator
+clawhub install network-ai
 ```
 
 ## Usage
@@ -618,6 +620,6 @@ If you're using LangGraph, Dify, Flowise, PraisonAI, AutoGen/AG2, CrewAI, or any
 <details>
 <summary>Keywords (for search)</summary>
 
-ai-agents, agentic-ai, multi-agent, multi-agent-systems, multi-agent-system, agent-framework, ai-agent-framework, agentic-framework, agentic-workflow, llm, llm-agents, llm-agent, large-language-models, generative-ai, genai, orchestration, ai-orchestration, swarm, swarm-intelligence, autonomous-agents, agents, ai, typescript, nodejs, mcp, model-context-protocol, a2a, agent-to-agent, function-calling, tool-integration, context-engineering, rag, ai-safety, multi-agents-collaboration, multi-agents, aiagents, aiagentframework, plug-and-play, adapter-registry, blackboard-pattern, agent-coordination, agent-handoffs, token-permissions, budget-tracking, cost-awareness, atomic-commits, hallucination-detection, content-quality-gate, OpenClaw, Clawdbot, Moltbot, Clawdbot Swarm, Moltbot Security, Moltbot multi-agent, OpenClaw skills, AgentSkills, LangChain adapter, LangGraph, AutoGen adapter, AG2, CrewAI adapter, MCP adapter, LlamaIndex adapter, Semantic Kernel adapter, OpenAI Assistants adapter, Haystack adapter, DSPy adapter, Agno adapter, Phidata adapter, Dify, Flowise, PraisonAI, custom-adapter, AES-256 encryption, HMAC tokens, rate limiting, input sanitization, privilege escalation prevention, agentic-rag, deep-research, workflow-orchestration, ai-assistant, ai-tools, developer-tools, open-source
+ai-agents, agentic-ai, multi-agent, multi-agent-systems, multi-agent-system, agent-framework, ai-agent-framework, agentic-framework, agentic-workflow, llm, llm-agents, llm-agent, large-language-models, generative-ai, genai, orchestration, ai-orchestration, swarm, swarm-intelligence, autonomous-agents, agents, ai, typescript, nodejs, mcp, model-context-protocol, a2a, agent-to-agent, function-calling, tool-integration, context-engineering, rag, ai-safety, multi-agents-collaboration, multi-agents, aiagents, aiagentframework, plug-and-play, adapter-registry, blackboard-pattern, agent-coordination, agent-handoffs, token-permissions, budget-tracking, cost-awareness, atomic-commits, hallucination-detection, content-quality-gate, OpenClaw, Clawdbot, Moltbot, Clawdbot Swarm, Moltbot Security, Moltbot multi-agent, OpenClaw skills, AgentSkills, LangChain adapter, LangGraph, AutoGen adapter, AG2, CrewAI adapter, MCP adapter, LlamaIndex adapter, Semantic Kernel adapter, OpenAI Assistants adapter, Haystack adapter, DSPy adapter, Agno adapter, Phidata adapter, Dify, Flowise, PraisonAI, custom-adapter, AES-256 encryption, HMAC tokens, rate limiting, input sanitization, privilege escalation prevention, ClawHub, clawhub, agentic-rag, deep-research, workflow-orchestration, ai-assistant, ai-tools, developer-tools, open-source
 
 </details>

package/SKILL.md

@@ -1,7 +1,13 @@
 ---
-name: swarm-orchestrator
-description: Multi-agent swarm orchestration for complex workflows. Use when coordinating multiple agents, delegating tasks between sessions, managing shared state via blackboard, or enforcing permission walls for DATABASE/PAYMENTS/EMAIL access. Triggers on: agent coordination, task delegation, parallel execution, permission requests, blackboard state management.
-metadata: { "openclaw": { "emoji": "🐝", "homepage": "https://github.com/jovanSAPFIONEER/Network-AI" } }
+name: Network-AI
+description: Multi-agent swarm orchestration for complex workflows. Coordinates multiple agents, decomposes tasks, manages shared state via a local blackboard file, and enforces permission walls before sensitive operations. All execution is local and sandboxed.
+metadata:
+  openclaw:
+    emoji: "\U0001F41D"
+    homepage: https://github.com/jovanSAPFIONEER/Network-AI
+    requires:
+      bins:
+        - python3
 ---
 
 # Swarm Orchestrator Skill
@@ -363,11 +369,12 @@ Sequential processing - output of one feeds into next.
 
 ## Security Considerations
 
-1. **Never bypass the permission wall** for DATABASE/PAYMENTS APIs
+1. **Never bypass the permission wall** for gated resources
 2. **Always include justification** explaining the business need
 3. **Use minimal scope** - request only what you need
 4. **Check token expiry** - tokens are valid for 5 minutes
-5. **Audit trail** - all permission requests are logged
+5. **Validate tokens** - use `python {baseDir}/scripts/validate_token.py TOKEN` to verify grant tokens before use
+6. **Audit trail** - all permission requests are logged
 
 ## 📝 Audit Trail Requirements (MANDATORY)
 
@@ -439,6 +446,9 @@ with open(audit_file, "a") as f:
 Expired permission tokens are automatically tracked. Run periodic cleanup:
 
 ```bash
+# Validate a grant token
+python {baseDir}/scripts/validate_token.py grant_a1b2c3d4e5f6
+
 # List expired tokens (without removing)
 python {baseDir}/scripts/revoke_token.py --list-expired
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "network-ai",
-  "version": "3.1.0",
+  "version": "3.1.3",
   "description": "AI agent orchestration framework for TypeScript/Node.js - plug-and-play multi-agent coordination with 12 frameworks (LangChain, AutoGen, CrewAI, OpenAI Assistants, LlamaIndex, Semantic Kernel, Haystack, DSPy, Agno, MCP, OpenClaw). Built-in security, swarm intelligence, and agentic workflow patterns.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/scripts/blackboard.py

@@ -307,7 +307,38 @@ Last Updated: {datetime.now(timezone.utc).isoformat()}
     # ========================================================================
     # ATOMIC COMMIT WORKFLOW: propose → validate → commit
     # ========================================================================
-    
+
+    @staticmethod
+    def _sanitize_change_id(change_id: str) -> str:
+        """
+        Sanitize change_id to prevent path traversal attacks.
+        Only allows alphanumeric characters, hyphens, underscores, and dots.
+        Rejects any path separators or parent directory references.
+        """
+        if not change_id or not isinstance(change_id, str):
+            raise ValueError("change_id must be a non-empty string")
+        # Strip whitespace
+        sanitized = change_id.strip()
+        # Reject path separators and parent directory traversal
+        if any(c in sanitized for c in ('/', '\\', '..')):
+            raise ValueError(
+                f"Invalid change_id '{change_id}': must not contain path separators or '..'"
+            )
+        # Only allow safe characters: alphanumeric, hyphen, underscore, dot
+        if not re.match(r'^[a-zA-Z0-9_\-\.]+$', sanitized):
+            raise ValueError(
+                f"Invalid change_id '{change_id}': only alphanumeric, hyphen, underscore, and dot allowed"
+            )
+        return sanitized
+
+    def _safe_pending_path(self, change_id: str, suffix: str = ".pending.json") -> Path:
+        """Build a pending-file path and verify it stays inside pending_dir."""
+        safe_id = self._sanitize_change_id(change_id)
+        target = (self.pending_dir / f"{safe_id}{suffix}").resolve()
+        if not str(target).startswith(str(self.pending_dir.resolve())):
+            raise ValueError(f"Path traversal blocked for change_id '{change_id}'")
+        return target
+
     def propose_change(self, change_id: str, key: str, value: Any, 
                        source_agent: str = "unknown", ttl: Optional[int] = None,
                        operation: str = "write") -> dict[str, Any]:
@@ -317,7 +348,7 @@ Last Updated: {datetime.now(timezone.utc).isoformat()}
         The change is written to a .pending file and must be validated
         and committed by the orchestrator before it takes effect.
         """
-        pending_file = self.pending_dir / f"{change_id}.pending.json"
+        pending_file = self._safe_pending_path(change_id)
         
         # Check for duplicate change_id
         if pending_file.exists():
@@ -365,7 +396,7 @@ Last Updated: {datetime.now(timezone.utc).isoformat()}
         - No conflicting changes to the same key
         - Base hash matches (data hasn't changed since proposal)
         """
-        pending_file = self.pending_dir / f"{change_id}.pending.json"
+        pending_file = self._safe_pending_path(change_id)
         
         if not pending_file.exists():
             return {
@@ -439,7 +470,7 @@ Last Updated: {datetime.now(timezone.utc).isoformat()}
         """
         Apply a validated change atomically (Step 3 of atomic commit).
         """
-        pending_file = self.pending_dir / f"{change_id}.pending.json"
+        pending_file = self._safe_pending_path(change_id)
         
         if not pending_file.exists():
             return {
@@ -479,9 +510,10 @@ Last Updated: {datetime.now(timezone.utc).isoformat()}
         change_set["status"] = "committed"
         change_set["committed_at"] = datetime.now(timezone.utc).isoformat()
         
+        safe_id = self._sanitize_change_id(change_id)
         archive_dir = self.pending_dir / "archive"
         archive_dir.mkdir(exist_ok=True)
-        archive_file = archive_dir / f"{change_id}.committed.json"
+        archive_file = archive_dir / f"{safe_id}.committed.json"
         archive_file.write_text(json.dumps(change_set, indent=2))
         
         # Remove pending file
@@ -497,7 +529,7 @@ Last Updated: {datetime.now(timezone.utc).isoformat()}
     
     def abort_change(self, change_id: str) -> dict[str, Any]:
         """Abort a pending change without applying it."""
-        pending_file = self.pending_dir / f"{change_id}.pending.json"
+        pending_file = self._safe_pending_path(change_id)
         
         if not pending_file.exists():
             return {
@@ -510,9 +542,10 @@ Last Updated: {datetime.now(timezone.utc).isoformat()}
         change_set["aborted_at"] = datetime.now(timezone.utc).isoformat()
         
         # Archive the aborted change
+        safe_id = self._sanitize_change_id(change_id)
         archive_dir = self.pending_dir / "archive"
         archive_dir.mkdir(exist_ok=True)
-        archive_file = archive_dir / f"{change_id}.aborted.json"
+        archive_file = archive_dir / f"{safe_id}.aborted.json"
         archive_file.write_text(json.dumps(change_set, indent=2))
         
         pending_file.unlink()