network-ai 5.12.6 → 5.12.7

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.12.6-blue.svg)](https://github.com/Jovancoding/Network-AI/releases)
+[![Release](https://img.shields.io/badge/release-v5.12.7-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-3269%20passing-brightgreen.svg)](#testing)
 [![Adapters](https://img.shields.io/badge/frameworks-29%20supported-blueviolet.svg)](#adapter-system)

package/SKILL.md

@@ -787,8 +787,8 @@ This skill is scanned on every publish. The following Notes are flagged by desig
 | **ASI06** Memory and Context Poisoning (audit log free text) | Low | `justification` field in permission requests and `data/audit_log.jsonl` store agent-provided free-text strings locally — PII or secrets placed there will persist on disk | Do not include PII, secrets, or credentials in justification text; restrict access to `data/` on shared machines; rotate/delete `audit_log.jsonl` when no longer needed |
 | **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 |
-| **SkillSpector** Description-Behavior Mismatch (`McpStreamableServer` network exposure) | Medium, 94% | SKILL.md content discusses `McpStreamableServer` — a native HTTP/MCP server binding a TCP port. Scanner flags this as contradicting the 'zero network calls' / local-only positioning of the bundle. | The Python skill bundle makes zero network calls. `McpStreamableServer` is in the optional npm package only and is never auto-started. Disclosed in the skill overview: *"Only start the separate npm MCP server if you intentionally want a local network control surface."* The `bundle_scope` YAML field distinguishes the two components. |
-| **SkillSpector** Context-Inappropriate Capability (MCP control surface breadth) | Medium, 90% | Same finding — the HTTP MCP server exposes 22 privileged tools (blackboard write, token ops, agent_spawn, fsm_transition, audit_query). Scanner flags this as elevating the attack surface of a local orchestration skill. | Server requires a non-empty bearer secret before `listen()` binds (fail-closed). Running it is opt-in (`NETWORK_AI_MCP_SECRET=<secret> npx network-ai-server`). Binds `127.0.0.1` by default. All controls documented in `SUPPLY_CHAIN.md §5a`. |
+| **SkillSpector** Description-Behavior Mismatch (`McpStreamableServer` network exposure) | ~~Medium~~ Resolved | The trigger was `comment.txt` — an in-progress draft GitHub-issue note describing the optional `McpStreamableServer` HTTP/MCP server (a native server binding a TCP port) — being bundled into the published ClawHub skill. Its prose contradicted the bundle's 'zero network calls' / local-only positioning. | Fixed in v5.12.7 — `comment.txt` added to `.clawhubignore` (the ignore file ClawHub actually honours; the earlier `.clawignore` entry was never read by the CLI). New `scripts/clawhub-check.js` guard (`npm run clawhub:check`) fails the release if any non-allowlisted file would be bundled, so draft notes can no longer leak. The Python skill bundle itself still makes zero network calls; `McpStreamableServer` is in the optional npm package only and is never auto-started. |
+| **SkillSpector** Context-Inappropriate Capability (MCP control surface breadth) | ~~Medium~~ Resolved | Same root cause — `comment.txt` enumerated the HTTP MCP server's 22 privileged tools (blackboard write, token ops, agent_spawn, fsm_transition, audit_query), which the scanner read as a broad remote-control surface inside a local skill. | Fixed in v5.12.7 — `comment.txt` excluded from the bundle (see row above) and enforced by the `clawhub:check` guard. The HTTP MCP server itself remains opt-in: it requires a non-empty bearer secret before `listen()` binds (fail-closed), runs only via `NETWORK_AI_MCP_SECRET=<secret> npx network-ai-server`, binds `127.0.0.1` by default, and is documented in `SUPPLY_CHAIN.md §5a`. |
 | **SkillSpector** Context-Inappropriate Capability (`_load_signing_key()` token minting) | Medium, 92% | `scripts/check_permission.py` mints, HMAC-signs, persists, and lists grant tokens — a de facto local authorization artifact that downstream components may be tempted to treat as real credentials. | Token advisory-only warnings appear in source, SKILL.md, and SECURITY.md. Every grant response includes the advisory notice. Tokens are labeled `grant_{uuid4().hex}`; the HMAC signature only proves local origin, not external identity. Platform-level authentication is required before any destructive action (PAYMENTS, DATABASE, FILE_EXPORT). See ASI03 rows above. |
 | **SkillSpector** Intent-Code Divergence (`FILE_EXPORT` missing from `HIGH_RISK_RESOURCES`) | ~~Low~~ Resolved | Comment stated `FILE_EXPORT` requires `--confirm-high-risk` but `HIGH_RISK_RESOURCES` only contained `PAYMENTS` and `DATABASE`; file export requests could receive advisory grants without the extra acknowledgment | Fixed in v5.11.0 — `FILE_EXPORT` added to `HIGH_RISK_RESOURCES` in `check_permission.py`; now requires `--confirm-high-risk` consistent with the documented policy |
 | **SkillSpector** Description-Behavior Mismatch (`ensure_data_dir()` ignoring env scope) | ~~Medium~~ Resolved | `ensure_data_dir()` always created the fixed top-level `data/` directory instead of the active env-specific path, breaking environment isolation when `NETWORK_AI_ENV` is set | Fixed in v5.11.0 — `ensure_data_dir()` now delegates to `_resolve_data_dir()` so audit log and grant files are always written to the correct env-scoped directory |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "network-ai",
-  "version": "5.12.6",
+  "version": "5.12.7",
   "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",
@@ -72,7 +72,8 @@
     "revoke-token": "python scripts/revoke_token.py",
     "socket:check": "node scripts/socket-check.js",
     "socket:check:local": "node scripts/socket-check.js --local",
-    "codeql:check": "node scripts/codeql-check.js"
+    "codeql:check": "node scripts/codeql-check.js",
+    "clawhub:check": "node scripts/clawhub-check.js"
   },
   "keywords": [
     "ai-agents",

package/scripts/clawhub-check.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+/**
+ * clawhub-check.js — ClawHub bundle hygiene guard for network-ai
+ *
+ * Verifies that a `clawhub publish .` from the repo root would bundle ONLY the
+ * intended Python-skill files — no draft notes, secrets, logs, TypeScript/npm
+ * docs, or Node tooling.
+ *
+ * ClawHub honours `.clawhubignore` (gitignore-style denylist) — NOT `.clawignore`
+ * and NOT `.gitignore`. This script replicates that exclusion against the repo,
+ * then asserts the surviving set is exactly the allowlist below. Any extra file
+ * is a leak that SkillSpector (NVIDIA, run by ClawHub on every publish) will
+ * scan — so we fail BEFORE publishing, not after.
+ *
+ * Usage:   node scripts/clawhub-check.js   |   npm run clawhub:check
+ * Exit:    0 = bundle clean   1 = leak, secret, or missing required file
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+
+// Files that SHOULD be in the published ClawHub skill bundle.
+const ALLOW_FILES = new Set([
+  'SKILL.md',
+  'swarm-blackboard.md',
+  'requirements.txt',
+  'skill.json',
+  '.clawhubignore',
+  '.clawignore',
+  'scripts/blackboard.py',
+  'scripts/check_permission.py',
+  'scripts/context_manager.py',
+  'scripts/revoke_token.py',
+  'scripts/swarm_guard.py',
+  'scripts/validate_token.py',
+]);
+
+// Directories allowed in the bundle (descended into for per-file checks).
+const ALLOW_DIRS = new Set(['scripts']);
+
+// Files that MUST be present (and not excluded) for the skill to function.
+const REQUIRED = [
+  'SKILL.md',
+  'swarm-blackboard.md',
+  'requirements.txt',
+  'scripts/blackboard.py',
+  'scripts/check_permission.py',
+  'scripts/context_manager.py',
+  'scripts/revoke_token.py',
+  'scripts/swarm_guard.py',
+  'scripts/validate_token.py',
+];
+
+// Hard-deny: these must NEVER appear in a bundle, even if mis-allowlisted.
+const SECRET_RE = /(^|\/)\.env(\.|$)|\.(log|pem|key|p12|pfx)$/i;
+
+// Directories never walked (and excluded by .clawhubignore anyway).
+const SKIP_DIRS = new Set(['.git', 'node_modules', 'dist']);
+
+const c = {
+  reset: '\x1b[0m', bold: '\x1b[1m', red: '\x1b[31m',
+  green: '\x1b[32m', yellow: '\x1b[33m', cyan: '\x1b[36m', gray: '\x1b[90m',
+};
+
+// ── Load .clawhubignore ──────────────────────────────────────────────────────
+
+const ignPath = path.join(ROOT, '.clawhubignore');
+if (!fs.existsSync(ignPath)) {
+  console.error(`${c.red}.clawhubignore not found — cannot verify bundle.${c.reset}`);
+  process.exit(1);
+}
+const patterns = fs.readFileSync(ignPath, 'utf8')
+  .split(/\r?\n/)
+  .map(l => l.trim())
+  .filter(l => l && !l.startsWith('#'));
+
+/** Convert a simple glob (only `*` is special, no `/`) to an anchored RegExp. */
+function globToRe(glob) {
+  let re = '';
+  for (const ch of glob) {
+    if (ch === '*') re += '[^/]*';
+    else re += ch.replace(/[.+^${}()|[\]\\?]/g, '\\$&');
+  }
+  return new RegExp('^' + re + '$');
+}
+
+/** Mirror .clawhubignore (gitignore-style) exclusion for one repo-relative path. */
+function isExcluded(relPath, isDir) {
+  const base = relPath.split('/').pop();
+  for (const pat of patterns) {
+    const dirPat = pat.endsWith('/');
+    const core = dirPat ? pat.slice(0, -1) : pat;
+    if (core.includes('/')) {
+      // Full-path pattern (e.g. "scripts/*.js")
+      if (globToRe(core).test(relPath)) return true;
+      if (relPath.startsWith(core + '/')) return true;
+    } else {
+      // Basename pattern (e.g. "*.ts", "comment.txt", "assets/")
+      if (core === base || core === relPath) return true;
+      if (core.includes('*') && globToRe(core).test(base)) return true;
+      if (dirPat && isDir && core === base) return true;
+    }
+  }
+  return false;
+}
+
+// ── Walk repo (root depth-1 + allowed subdirs) ───────────────────────────────
+
+const bundle = [];
+const leaks = [];
+
+for (const name of fs.readdirSync(ROOT)) {
+  if (SKIP_DIRS.has(name)) continue;
+  const isDir = fs.statSync(path.join(ROOT, name)).isDirectory();
+
+  if (isExcluded(name, isDir)) continue;
+
+  if (isDir) {
+    if (ALLOW_DIRS.has(name)) {
+      for (const child of fs.readdirSync(path.join(ROOT, name))) {
+        const crel = `${name}/${child}`;
+        const cIsDir = fs.statSync(path.join(ROOT, name, child)).isDirectory();
+        if (isExcluded(crel, cIsDir)) continue;
+        bundle.push(crel);
+        if (!ALLOW_FILES.has(crel)) leaks.push(crel);
+      }
+    } else {
+      // A non-allowlisted directory survived exclusion → leak.
+      bundle.push(name + '/');
+      leaks.push(name + '/  (directory — exclude in .clawhubignore)');
+    }
+  } else {
+    bundle.push(name);
+    if (!ALLOW_FILES.has(name)) leaks.push(name);
+  }
+}
+
+// ── Report ───────────────────────────────────────────────────────────────────
+
+console.log(`\n${c.bold}${c.cyan}ClawHub Bundle Hygiene Check${c.reset}`);
+console.log(`${c.gray}${'─'.repeat(50)}${c.reset}`);
+console.log(`Would publish ${bundle.length} item(s):`);
+const leakSet = new Set(leaks.map(l => l.split('  ')[0]));
+for (const b of [...bundle].sort()) {
+  const ok = !leakSet.has(b);
+  console.log(`  ${ok ? c.green + '✓' + c.reset : c.red + '✗' + c.reset} ${b}`);
+}
+
+const secretLeaks = bundle.filter(b => SECRET_RE.test(b));
+const missing = REQUIRED.filter(r => !fs.existsSync(path.join(ROOT, r)) || isExcluded(r, false));
+
+console.log(`\n${c.gray}${'─'.repeat(50)}${c.reset}`);
+let fail = false;
+
+if (leaks.length) {
+  fail = true;
+  console.log(`${c.red}${c.bold}LEAK${c.reset} — ${leaks.length} unintended item(s) would be published:`);
+  for (const l of leaks) console.log(`  ${c.red}• ${l}${c.reset}`);
+  console.log(`  ${c.gray}Add each to .clawhubignore (or to ALLOW_FILES here if genuinely intended).${c.reset}`);
+}
+if (secretLeaks.length) {
+  fail = true;
+  console.log(`${c.red}${c.bold}SECRET${c.reset} — secret/log file(s) in bundle: ${secretLeaks.join(', ')}`);
+}
+if (missing.length) {
+  fail = true;
+  console.log(`${c.red}${c.bold}MISSING${c.reset} — required skill file(s) absent or excluded: ${missing.join(', ')}`);
+}
+
+if (fail) process.exit(1);
+console.log(`${c.green}${c.bold}PASS${c.reset} — bundle contains only the intended Python-skill files.`);
+process.exit(0);