network-ai 5.5.0 → 5.5.2

package/INTEGRATION_GUIDE.md

@@ -564,4 +564,4 @@ Run these before declaring the integration production-ready:
 
 ---
 
-*Network-AI v5.5.0 · MIT License · https://github.com/Jovancoding/Network-AI*
+*Network-AI v5.5.2 · MIT License · https://github.com/Jovancoding/Network-AI*

package/README.md

@@ -5,7 +5,7 @@
 [![Website](https://img.shields.io/badge/website-network--ai.org-4b9df2?style=flat&logo=web&logoColor=white)](https://network-ai.org/)
 [![CI](https://github.com/Jovancoding/Network-AI/actions/workflows/ci.yml/badge.svg)](https://github.com/Jovancoding/Network-AI/actions/workflows/ci.yml)
 [![CodeQL](https://github.com/Jovancoding/Network-AI/actions/workflows/codeql.yml/badge.svg)](https://github.com/Jovancoding/Network-AI/actions/workflows/codeql.yml)
-[![Release](https://img.shields.io/badge/release-v5.5.0-blue.svg)](https://github.com/Jovancoding/Network-AI/releases)
+[![Release](https://img.shields.io/badge/release-v5.5.2-blue.svg)](https://github.com/Jovancoding/Network-AI/releases)
 [![npm](https://img.shields.io/npm/dw/network-ai.svg?label=npm%20downloads)](https://www.npmjs.com/package/network-ai)
 [![Tests](https://img.shields.io/badge/tests-3093%20passing-brightgreen.svg)](#testing)
 [![Adapters](https://img.shields.io/badge/frameworks-29%20supported-blueviolet.svg)](#adapter-system)

package/SKILL.md

@@ -710,7 +710,9 @@ This skill is scanned on every publish. The following Notes are flagged by desig
 | Finding | Confidence | Why it recurs | Documented control |
 |---------|------------|---------------|--------------------|
 | **ASI01** Agent Goal Hijack | High | Orchestrator skill forces 3-sub-task decomposition by design | Use this skill only when multi-agent orchestration is desired; disable for simple one-shot tasks |
-| **ASI03** Identity and Privilege Abuse | High | Grant tokens are advisory only — caller identity is not cryptographically verified | Tokens are explicitly marked advisory in SKILL.md and source; require separate platform auth and human approval before any real database, payment, email, or export action |
+| **ASI03** Identity and Privilege Abuse (advisory tokens) | High | Grant tokens are advisory only — caller identity is not cryptographically verified | Tokens are explicitly marked advisory in SKILL.md and source; require separate platform auth and human approval before any real database, payment, email, or export action |
+| **ASI03** Identity and Privilege Abuse (token integrity) | ~~High~~ Resolved | Token payload had no integrity protection — active_grants.json could be edited to forge elevated grants | Fixed in v5.5.2 — `check_permission.py` HMAC-SHA256 signs each grant (`_sig` field, stdlib `hmac`+`hashlib`, key at `data/.signing_key`); `validate_token.py` verifies before accepting; tampered tokens rejected with `"Token signature invalid"` |
+| **ASI03** Identity and Privilege Abuse (env-scoped paths) | ~~High~~ Resolved | `revoke_token.py` resolved `GRANTS_FILE`/`AUDIT_LOG` at module load from root `data/`, ignoring `NETWORK_AI_ENV` — revoking tokens in one env could silently miss env-specific grant files | Fixed in v5.5.1 — `_resolve_data_dir()` added, `--env` CLI argument introduced, paths re-resolved in `main()` before file I/O; consistent with `check_permission.py` and `validate_token.py` |
 | **ASI06** Memory and Context Poisoning | High | Persistent `data/project-context.json` is injected into agent sessions by design | `_validate_context()` runs injection-pattern detection before every inject; do not store secrets/credentials; review `data/project-context.json` before use; clear `data/` between projects |
 | **ASI07** Insecure Inter-Agent Communication | High | Blackboard is local file-based; origin/identity depends on local file access, not authenticated messaging | Run in a trusted workspace; restrict file permissions on `data/`; review blackboard changes before relying on them for important decisions |
 | **ASI08** Cascading Failures | ~~High~~ Resolved | `os` was referenced before import in `swarm_guard.py` — fixed in v5.4.4; `import os` now present | Fixed — `swarm_guard.py` now imports `os` at module level; budget/health guard starts correctly |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "network-ai",
-  "version": "5.5.0",
+  "version": "5.5.2",
   "description": "AI agent orchestration framework for TypeScript/Node.js - 29 adapters (LangChain, AutoGen, CrewAI, OpenAI Assistants, LlamaIndex, Semantic Kernel, Haystack, DSPy, Agno, MCP, OpenClaw, A2A, Codex, MiniMax, NemoClaw, APS, Copilot, LangGraph, Anthropic Computer Use, OpenAI Agents SDK, Vertex AI, Pydantic AI, Browser Agent, Hermes, Orchestrator, RLM + streaming variants). Built-in CLI, security, swarm intelligence, real-time streaming, and agentic workflow patterns.",
   "homepage": "https://network-ai.org",
   "main": "dist/index.js",

package/scripts/check_permission.py

@@ -1,9 +1,11 @@
 #!/usr/bin/env python3
 # SECURITY: This script makes NO network calls and spawns NO subprocesses.
 # All I/O is local file operations only:
-#   READS:  data/active_grants.json, data/audit_log.jsonl
-#   WRITES: data/active_grants.json, data/audit_log.jsonl
-# Imports used: argparse, json, re, sys, uuid, datetime, pathlib, typing
+#   READS:  data[/<env>]/active_grants.json, data[/<env>]/audit_log.jsonl,
+#           data[/<env>]/.signing_key (HMAC key; auto-created on first run)
+#   WRITES: data[/<env>]/active_grants.json, data[/<env>]/audit_log.jsonl,
+#           data[/<env>]/.signing_key (on first run only; chmod 0o600)
+# Imports used: argparse, json, re, sys, uuid, hmac, hashlib, datetime, pathlib, typing
 # No imports of: requests, socket, subprocess, urllib, http, ssl, ftplib, smtplib
 """
 AuthGuardian Permission Checker
@@ -28,6 +30,8 @@ Examples:
 """
 
 import argparse
+import hashlib
+import hmac
 import json
 import re
 import sys
@@ -264,6 +268,51 @@ def generate_grant_token() -> str:
     return f"grant_{uuid.uuid4().hex}"
 
 
+def _load_signing_key() -> bytes:
+    """
+    Load or create the local HMAC-SHA256 signing key for grant tokens.
+
+    The key is stored at data[/<env>]/.signing_key as a 32-byte hex string.
+    It is auto-generated with os.urandom(32) on first use and restricted to
+    mode 0o600.  It lives inside the env-scoped data dir so multi-environment
+    deployments each have an independent key.
+    """
+    key_file = _DATA_DIR / ".signing_key"
+    if key_file.exists():
+        try:
+            return bytes.fromhex(key_file.read_text().strip())
+        except (ValueError, OSError):
+            pass  # Corrupt key file — regenerate below
+    key = os.urandom(32)
+    _DATA_DIR.mkdir(parents=True, exist_ok=True)
+    key_file.write_text(key.hex())
+    try:
+        key_file.chmod(0o600)  # Restrict to owner; no-op on Windows
+    except OSError:
+        pass
+    return key
+
+
+def _sign_grant(grant: dict[str, Any]) -> str:
+    """
+    Return an HMAC-SHA256 hex signature over the canonical grant fields.
+
+    Covered fields: token, agent_id, resource_type, scope, expires_at, granted_at.
+    Storing this in the grant record lets validate_token.py detect any
+    post-issuance tampering of active_grants.json.
+    """
+    payload = "|".join([
+        grant.get("token", ""),
+        grant.get("agent_id", ""),
+        grant.get("resource_type", ""),
+        grant.get("scope") or "",
+        grant.get("expires_at", ""),
+        grant.get("granted_at", ""),
+    ])
+    key = _load_signing_key()
+    return hmac.new(key, payload.encode("utf-8"), hashlib.sha256).hexdigest()
+
+
 def log_audit(action: str, details: dict[str, Any]) -> None:
     """Append entry to audit log."""
     ensure_data_dir()
@@ -412,7 +461,7 @@ def evaluate_permission(
     token = generate_grant_token()
     expires_at = (datetime.now(timezone.utc) + timedelta(minutes=GRANT_TOKEN_TTL_MINUTES)).isoformat()
     restrictions = RESTRICTIONS.get(resource_type, [])
-    
+
     grant: dict[str, Any] = {
         "token": token,
         "agent_id": agent_id,
@@ -425,6 +474,9 @@ def evaluate_permission(
         "unknown_agent": unknown_agent,
     }
 
+    # Sign the grant — lets validate_token.py detect tampered grant records
+    grant["_sig"] = _sign_grant(grant)
+
     # Save grant and log
     save_grant(grant)
     log_audit("permission_granted", grant)

package/scripts/revoke_token.py

@@ -1,9 +1,9 @@
 #!/usr/bin/env python3
 # SECURITY: This script makes NO network calls and spawns NO subprocesses.
 # All I/O is local file operations only:
-#   READS:  data/active_grants.json, data/audit_log.jsonl
-#   WRITES: data/active_grants.json, data/audit_log.jsonl
-# Imports used: argparse, json, sys, datetime, pathlib, typing
+#   READS:  data[/<env>]/active_grants.json, data[/<env>]/audit_log.jsonl
+#   WRITES: data[/<env>]/active_grants.json, data[/<env>]/audit_log.jsonl
+# Imports used: argparse, json, os, re, sys, datetime, pathlib, typing
 # No imports of: requests, socket, subprocess, urllib, http, ssl, ftplib, smtplib
 """
 Revoke Grant Token & TTL Enforcement
@@ -22,13 +22,27 @@ Example:
 
 import argparse
 import json
+import os
+import re
 import sys
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
-GRANTS_FILE = Path(__file__).parent.parent / "data" / "active_grants.json"
-AUDIT_LOG = Path(__file__).parent.parent / "data" / "audit_log.jsonl"
+
+def _resolve_data_dir(env: str = "") -> Path:
+    """Return the active data directory, scoped to <env> when set."""
+    _env = env or os.environ.get("NETWORK_AI_ENV", "")
+    base = Path(__file__).parent.parent / "data"
+    if _env:
+        if not re.match(r'^[a-zA-Z0-9_-]+$', _env):
+            raise ValueError(f"Invalid NETWORK_AI_ENV value: {_env!r}")
+        return base / _env
+    return base
+
+
+GRANTS_FILE = _resolve_data_dir() / "active_grants.json"
+AUDIT_LOG = _resolve_data_dir() / "audit_log.jsonl"
 
 
 def log_audit(action: str, details: dict[str, Any]) -> None:
@@ -186,9 +200,20 @@ def main():
     parser.add_argument("--list-expired", action="store_true",
                         help="List expired tokens without removing")
     parser.add_argument("--json", action="store_true", help="Output as JSON")
-    
+    parser.add_argument(
+        "--env",
+        default="",
+        help="Target environment (dev|st|sit|qa|sandbox|preprod|prod). Overrides NETWORK_AI_ENV."
+    )
+
     args = parser.parse_args()
-    
+
+    # Re-resolve data paths if --env was provided explicitly
+    global GRANTS_FILE, AUDIT_LOG
+    if args.env:
+        GRANTS_FILE = _resolve_data_dir(args.env) / "active_grants.json"
+        AUDIT_LOG = _resolve_data_dir(args.env) / "audit_log.jsonl"
+
     # Handle --list-expired
     if args.list_expired:
         result = list_expired_tokens()

package/scripts/validate_token.py

@@ -1,9 +1,9 @@
 #!/usr/bin/env python3
 # SECURITY: This script makes NO network calls and spawns NO subprocesses.
 # All I/O is local file operations only:
-#   READS:  data/active_grants.json
+#   READS:  data[/<env>]/active_grants.json, data[/<env>]/.signing_key
 #   WRITES: none
-# Imports used: argparse, json, sys, datetime, pathlib, typing
+# Imports used: argparse, json, sys, hmac, hashlib, datetime, pathlib, typing
 # No imports of: requests, socket, subprocess, urllib, http, ssl, ftplib, smtplib
 """
 Validate Grant Token
@@ -18,11 +18,13 @@ Example:
 """
 
 import argparse
+import hashlib
+import hmac
 import json
 import sys
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any
+from typing import Any, Optional
 
 def _resolve_data_dir(env: str = "") -> Path:
     """Return the active data directory, scoped to <env> when set."""
@@ -38,6 +40,47 @@ def _resolve_data_dir(env: str = "") -> Path:
 GRANTS_FILE = _resolve_data_dir() / "active_grants.json"
 
 
+def _load_signing_key() -> "Optional[bytes]":
+    """
+    Load the local HMAC-SHA256 signing key used by check_permission.py.
+    Returns None if the key file does not exist or cannot be read.
+    """
+    key_file = GRANTS_FILE.parent / ".signing_key"
+    if not key_file.exists():
+        return None
+    try:
+        return bytes.fromhex(key_file.read_text().strip())
+    except (ValueError, OSError):
+        return None
+
+
+def _verify_grant_sig(grant: "dict[str, Any]") -> "Optional[bool]":
+    """
+    Verify the HMAC-SHA256 signature stored in a grant record.
+
+    Returns:
+      True  — signature present and valid
+      False — signature present but invalid (tampered)
+      None  — no signature (pre-v5.5.2 token) or key unavailable
+    """
+    stored_sig = grant.get("_sig")
+    if not stored_sig:
+        return None  # Backward-compatible: unsigned token from before v5.5.2
+    key = _load_signing_key()
+    if key is None:
+        return None  # Key not present — cannot verify; treat as unverified
+    payload = "|".join([
+        grant.get("token", ""),
+        grant.get("agent_id", ""),
+        grant.get("resource_type", ""),
+        grant.get("scope") or "",
+        grant.get("expires_at", ""),
+        grant.get("granted_at", ""),
+    ])
+    expected = hmac.new(key, payload.encode("utf-8"), hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, stored_sig)
+
+
 def validate_token(token: str) -> dict[str, Any]:
     """Validate a grant token and return its details."""
     if not GRANTS_FILE.exists():
@@ -61,7 +104,15 @@ def validate_token(token: str) -> dict[str, Any]:
         }
     
     grant = grants[token]
-    
+
+    # Guard against tampered grant records (checks HMAC-SHA256 signature)
+    sig_result = _verify_grant_sig(grant)
+    if sig_result is False:
+        return {
+            "valid": False,
+            "reason": "Token signature invalid — grant record may have been tampered with",
+        }
+
     # Check expiration
     expires_at = grant.get("expires_at")
     if expires_at:
@@ -80,7 +131,8 @@ def validate_token(token: str) -> dict[str, Any]:
     
     return {
         "valid": True,
-        "grant": grant
+        "grant": grant,
+        "sig_verified": sig_result is True,
     }