netzilo 4.3.14

package/dist/trust.js

@@ -0,0 +1,299 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installTrust = installTrust;
+exports.installRouting = installRouting;
+exports.uninstallRouting = uninstallRouting;
+/**
+ * In-process CA trust + traffic routing for the embedded MITM proxy.
+ *
+ * The MITM proxy signs intercepted TLS with a per-install Netzilo CA (written
+ * by the native client to <configDir>/netzilo-ca.pem when advanced governance
+ * is on). For the host process to accept those connections, the process's TLS
+ * stack must trust that CA, and its outbound traffic must actually reach the
+ * proxy:
+ *
+ *   CA trust:
+ *     - There is no reliable, Node-version-independent way to change the
+ *       DEFAULT trust store for `fetch()`/undici at runtime. The mechanism
+ *       that actually works, confirmed against a real intercepted LLM call:
+ *       pass the CA directly into undici's EnvHttpProxyAgent via its
+ *       `connect`/`requestTls` options (both accept the same shape as
+ *       `tls.ConnectionOptions`, including `ca`) — see installRouting()
+ *       below, which is where the CA is actually consumed. NODE_EXTRA_CA_CERTS
+ *       is still set as a best-effort extra (helps subprocesses that inherit
+ *       the env; Node only guarantees it's read at process bootstrap, so it
+ *       is NOT relied on for this process's own fetch() calls).
+ *
+ *   Traffic routing:
+ *     - Most Node HTTP clients do NOT read HTTP_PROXY/HTTPS_PROXY
+ *       automatically. We (a) set the env vars anyway, which covers
+ *       subprocesses (curl, git) and any library that opts into
+ *       proxy-from-env, and (b) — when the optional `undici` peer dependency
+ *       is present — install `EnvHttpProxyAgent` as undici's global
+ *       dispatcher, which IS the mechanism Node's global `fetch` honors. Note
+ *       this does not cover libraries that build their own http.Agent without
+ *       consulting undici or the proxy env vars.
+ *
+ *       IMPORTANT for consumers: `undici` must be resolvable from THIS
+ *       package's own require() — i.e. present in a node_modules directory
+ *       that is an ancestor of where netzilo itself is installed. A normal
+ *       `npm install undici` in a real consuming project satisfies this via
+ *       npm's normal hoisting; it does NOT work if netzilo is linked in via a
+ *       nested/isolated layout (e.g. a local `file:` dependency, or pnpm's
+ *       strict non-hoisted node_modules) unless undici is installed at the
+ *       location netzilo's own require() resolves from.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const tls = __importStar(require("tls"));
+let trustApplied = false;
+// The combined (public roots + Netzilo CA) PEM content, read by
+// installRouting() to configure undici's TLS trust for the MITM'd traffic.
+// This — not any global Node API — is the actual trust mechanism that works.
+let combinedCaPem = null;
+const CA_FILENAME = "netzilo-ca.pem";
+function readFile(p) {
+    try {
+        return fs.readFileSync(p);
+    }
+    catch {
+        return Buffer.alloc(0);
+    }
+}
+function normalize(pem) {
+    // Whitespace-insensitive key for per-cert dedupe (base64 body + markers).
+    return pem.toString("utf8").replace(/\s+/g, "");
+}
+function contains(haystack, needle) {
+    if (!needle.toString("utf8").trim()) {
+        return false;
+    }
+    return normalize(haystack).includes(normalize(needle));
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Make the current process trust the MITM CA. Idempotent; no-op if the CA
+ * isn't present (MITM disabled). Never throws — trust setup must not break
+ * the agent. Returns true if trust was applied.
+ */
+async function installTrust(configDir, waitSecs = 10.0) {
+    if (trustApplied) {
+        return true;
+    }
+    try {
+        const caPath = path.join(configDir, CA_FILENAME);
+        // The native client writes the CA asynchronously during startup, so wait
+        // briefly for it when MITM is enabled.
+        const deadline = Date.now() + Math.max(0, waitSecs) * 1000;
+        while (!fs.existsSync(caPath) && Date.now() < deadline) {
+            await sleep(250);
+        }
+        const caPem = readFile(caPath);
+        if (!caPem.toString("utf8").trim()) {
+            // eslint-disable-next-line no-console
+            console.log(`netzilo.trust: no MITM CA at ${caPath} — skipping (MITM off?)`);
+            return false;
+        }
+        // Build a combined bundle = Node's default roots + the Netzilo CA, so we
+        // never narrow trust to the CA alone.
+        const defaultRoots = tls.rootCertificates ? tls.rootCertificates.join("\n") : "";
+        const combined = contains(Buffer.from(defaultRoots), caPem)
+            ? defaultRoots
+            : `${defaultRoots}\n${caPem.toString("utf8")}`;
+        const combinedPath = path.join(configDir, "ca-bundle.pem");
+        try {
+            const tmp = `${combinedPath}.tmp`;
+            fs.writeFileSync(tmp, combined);
+            fs.renameSync(tmp, combinedPath);
+        }
+        catch (exc) {
+            // eslint-disable-next-line no-console
+            console.warn("netzilo.trust: cannot write combined bundle:", exc);
+        }
+        // The actual trust mechanism for this process's own fetch()/undici calls:
+        // stash the combined PEM for installRouting() to hand to undici's
+        // EnvHttpProxyAgent via its connect/requestTls options. See the module
+        // comment for why this — not a global Node TLS API — is what works.
+        combinedCaPem = combined;
+        // Best-effort extras: cover subprocesses (curl, git, a spawned scripting
+        // tool) that read these at their own startup, and this process's own
+        // fetch() IF this module happens to load before any TLS context is
+        // created (Node's docs say NODE_EXTRA_CA_CERTS is read at bootstrap, so
+        // this is not relied upon — installRouting()'s explicit `ca` option is).
+        process.env.NODE_EXTRA_CA_CERTS = caPath;
+        process.env.SSL_CERT_FILE = combinedPath;
+        process.env.REQUESTS_CA_BUNDLE = combinedPath; // covers spawned Python-based tools
+        process.env.CURL_CA_BUNDLE = combinedPath; // covers spawned curl
+        trustApplied = true;
+        return true;
+    }
+    catch (exc) {
+        // eslint-disable-next-line no-console
+        console.warn("netzilo.trust: install failed (MITM HTTPS may not verify):", exc);
+        return false;
+    }
+}
+let routed = false;
+// Original values of the env vars we override, captured at install time so
+// uninstallRouting() can restore them exactly (undefined = was unset).
+const priorProxyEnv = {};
+const PROXY_VARS = [
+    "HTTP_PROXY",
+    "http_proxy",
+    "HTTPS_PROXY",
+    "https_proxy",
+    "ALL_PROXY",
+    "all_proxy",
+    "NO_PROXY",
+    "no_proxy",
+];
+// Hosts that must NEVER be proxied: localhost (the proxy + gateway live here)
+// and the Netzilo CONTROL PLANE (.netzilo.com — management/admin/signal).
+// Routing those through our own unified proxy would loop.
+//
+// NOTE: .netzilo.network (ZTNA peer/resource FQDNs) is deliberately NOT
+// excluded — those MUST go through the proxy so the native client resolves
+// the magic-DNS name and tunnels the connection to the peer.
+const NO_PROXY_BASE = "127.0.0.1,localhost,::1,.netzilo.com";
+/**
+ * Route this process's (and subprocesses') traffic through the unified proxy
+ * so it can be governed. Sets standard proxy env vars (covers subprocesses
+ * and any proxy-env-aware library) and, when the optional `undici` peer
+ * dependency is installed, wires undici's EnvHttpProxyAgent as the global
+ * dispatcher — the mechanism Node's global fetch() actually honors.
+ *
+ * Idempotent; never throws. Returns true if applied.
+ */
+function installRouting(unifiedPort, extraNoProxy) {
+    if (routed) {
+        return true;
+    }
+    try {
+        if (!unifiedPort) {
+            return false;
+        }
+        const proxy = `http://127.0.0.1:${unifiedPort}`;
+        const socks = `socks5h://127.0.0.1:${unifiedPort}`;
+        let noProxy = NO_PROXY_BASE;
+        if (extraNoProxy) {
+            noProxy = `${noProxy},${extraNoProxy}`;
+        }
+        for (const existing of [process.env.NO_PROXY, process.env.no_proxy]) {
+            if (existing) {
+                noProxy = `${noProxy},${existing}`;
+            }
+        }
+        for (const v of PROXY_VARS) {
+            priorProxyEnv[v] = process.env[v];
+        }
+        process.env.HTTPS_PROXY = proxy;
+        process.env.https_proxy = proxy;
+        process.env.ALL_PROXY = socks;
+        process.env.all_proxy = socks;
+        // Drop any inherited HTTP_PROXY so plaintext HTTP routes via SOCKS5
+        // instead (a plaintext GET through the HTTP-CONNECT proxy produces no
+        // graph edge; SOCKS5 yields a CONNECTS edge instead).
+        delete process.env.HTTP_PROXY;
+        delete process.env.http_proxy;
+        process.env.NO_PROXY = noProxy;
+        process.env.no_proxy = noProxy;
+        // Wire Node's global fetch() (undici under the hood) to honor the env
+        // vars just set, AND to trust the MITM CA for the tunneled TLS connection
+        // — undici does its own certificate verification independent of Node's
+        // global tls settings, so the CA has to be handed to it directly via
+        // connect/requestTls (both accept the same shape as tls.ConnectionOptions,
+        // confirmed against undici's own type definitions). Optional: only
+        // attempted if `undici` is resolvable.
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const undici = require("undici");
+            if (undici.EnvHttpProxyAgent && undici.setGlobalDispatcher) {
+                const tlsOpts = combinedCaPem ? { ca: combinedCaPem } : undefined;
+                undici.setGlobalDispatcher(new undici.EnvHttpProxyAgent(tlsOpts ? { connect: tlsOpts, requestTls: tlsOpts } : undefined));
+                // eslint-disable-next-line no-console
+                console.log(`netzilo.trust: wired undici EnvHttpProxyAgent as global fetch dispatcher${tlsOpts ? " (with MITM CA trust)" : " (no MITM CA available — TLS verification may fail)"}`);
+            }
+        }
+        catch {
+            // eslint-disable-next-line no-console
+            console.log("netzilo.trust: `undici` not resolvable — proxy env vars are set (covers " +
+                "subprocesses and proxy-aware libraries), but Node's global fetch() may " +
+                "bypass the proxy. `npm install undici` (resolvable from netzilo's own " +
+                "require() — see module comment) to also cover fetch().");
+        }
+        routed = true;
+        // eslint-disable-next-line no-console
+        console.log(`netzilo.trust: routing HTTPS via ${proxy}, all else via ${socks} (NO_PROXY=${noProxy})`);
+        return true;
+    }
+    catch (exc) {
+        // eslint-disable-next-line no-console
+        console.warn("netzilo.trust: routing setup failed:", exc);
+        return false;
+    }
+}
+/**
+ * Restore the proxy env vars to their pre-install values. Called on stop() so
+ * a long-lived host process that keeps running after stop() does not keep
+ * routing traffic to the (now closed) egress port. Idempotent; never throws.
+ */
+function uninstallRouting() {
+    if (!routed) {
+        return;
+    }
+    try {
+        for (const [v, orig] of Object.entries(priorProxyEnv)) {
+            if (orig === undefined) {
+                delete process.env[v];
+            }
+            else {
+                process.env[v] = orig;
+            }
+        }
+    }
+    catch (exc) {
+        // eslint-disable-next-line no-console
+        console.warn("netzilo.trust: routing teardown failed:", exc);
+    }
+    finally {
+        for (const k of Object.keys(priorProxyEnv)) {
+            delete priorProxyEnv[k];
+        }
+        routed = false;
+    }
+}

package/dist/wrapTool.d.ts

@@ -0,0 +1,22 @@
+export declare class NetziloBlockedError extends Error {
+    toolName: string;
+    reason: string;
+    constructor(toolName: string, reason: string);
+}
+export interface WrapToolOptions {
+    /** Attribution tag for events (default: "node-agent"). */
+    source?: string;
+    /** If false, a scanner error re-throws instead of failing open. Default true. */
+    failOpen?: boolean;
+}
+/**
+ * Wrap an async tool function with pre-call gating and post-call reporting.
+ *
+ * - Before the call: runs isAllowed(name, args) — throws NetziloBlockedError
+ *   if the policy blocks it.
+ * - After the call: string results are passed through checkResponse() so
+ *   redaction rules (e.g. AWS-key / PII scrubbing) apply to tool OUTPUT before
+ *   the agent's LLM ever sees it; non-string results are reported as-is via
+ *   reportResult() for observability without being altered.
+ */
+export declare function wrapTool<Args extends Record<string, unknown>, Result>(name: string, fn: (args: Args) => Promise<Result>, opts?: WrapToolOptions): (args: Args) => Promise<Result>;

package/dist/wrapTool.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NetziloBlockedError = void 0;
+exports.wrapTool = wrapTool;
+/**
+ * netzilo/wrapTool — framework-agnostic tool gating.
+ *
+ * Every Node agent framework's "tool" boils down to an async function the
+ * model calls with some arguments. Rather than bind to one framework's
+ * specific hook API (which drifts release to release — LangChain.js,
+ * LlamaIndex.TS, the Vercel AI SDK, and raw OpenAI/Anthropic tool-use loops
+ * all shape this differently), wrapTool() gates at that common boundary: wrap
+ * your tool function once, and every call is pre-checked (block/redact) and
+ * post-reported through the same in-process scanner + AIDR pipeline used
+ * throughout this SDK.
+ *
+ *     import { wrapTool } from "netzilo/wrapTool";
+ *
+ *     const getOrderStatus = wrapTool(
+ *       "get_order_status",
+ *       async (args: { orderId: string }) => fetchOrder(args.orderId)
+ *     );
+ *
+ *     // register `getOrderStatus` with LangChain's tool(), the Vercel AI
+ *     // SDK's tool(), or any framework's tool registry exactly as you would
+ *     // the original function — the governance is transparent to the caller.
+ *
+ * A blocked call throws NetziloBlockedError instead of invoking the wrapped
+ * function; a redacted call proceeds with the wrapped function's OWN return
+ * value passed back through checkResponse() so text output can be sanitized
+ * too.
+ */
+const index_1 = require("./index");
+class NetziloBlockedError extends Error {
+    constructor(toolName, reason) {
+        super(`netzilo blocked tool call "${toolName}": ${reason || "policy violation"}`);
+        this.name = "NetziloBlockedError";
+        this.toolName = toolName;
+        this.reason = reason;
+    }
+}
+exports.NetziloBlockedError = NetziloBlockedError;
+/**
+ * Wrap an async tool function with pre-call gating and post-call reporting.
+ *
+ * - Before the call: runs isAllowed(name, args) — throws NetziloBlockedError
+ *   if the policy blocks it.
+ * - After the call: string results are passed through checkResponse() so
+ *   redaction rules (e.g. AWS-key / PII scrubbing) apply to tool OUTPUT before
+ *   the agent's LLM ever sees it; non-string results are reported as-is via
+ *   reportResult() for observability without being altered.
+ */
+function wrapTool(name, fn, opts = {}) {
+    const source = opts.source ?? "node-agent";
+    const failOpen = opts.failOpen ?? true;
+    return async (args) => {
+        try {
+            const { allowed, reason } = (0, index_1.isAllowed)(name, args, { source });
+            if (!allowed) {
+                throw new NetziloBlockedError(name, reason);
+            }
+        }
+        catch (err) {
+            if (err instanceof NetziloBlockedError || !failOpen) {
+                throw err;
+            }
+            // Scanner not running / transient error: fail open rather than break
+            // the agent, matching evaluate()'s own fail-open contract.
+        }
+        const result = await fn(args);
+        try {
+            if (typeof result === "string") {
+                const { redactedResponse } = (0, index_1.checkResponse)(result, { source });
+                if (redactedResponse !== null) {
+                    return redactedResponse;
+                }
+                (0, index_1.reportResult)(name, result, { source });
+            }
+            else {
+                (0, index_1.reportResult)(name, JSON.stringify(result, (_k, v) => (v === undefined ? null : v)), {
+                    source,
+                });
+            }
+        }
+        catch {
+            // Observability/redaction must never break the agent's happy path.
+        }
+        return result;
+    };
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "netzilo",
+  "version": "4.3.14",
+  "description": "Netzilo AI Detection & Response (AIDR) — governance for Node.js/TypeScript AI agents.",
+  "license": "Commercial",
+  "author": "Netzilo",
+  "keywords": [
+    "ai",
+    "agent",
+    "governance",
+    "security",
+    "aidr",
+    "netzilo"
+  ],
+  "homepage": "https://www.netzilo.com",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./wrapTool": "./dist/wrapTool.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "koffi": "^2.9.0"
+  },
+  "optionalDependencies": {
+    "netzilo-darwin-arm64": "4.3.14",
+    "netzilo-darwin-x64": "4.3.14",
+    "netzilo-linux-arm64": "4.3.14",
+    "netzilo-linux-x64": "4.3.14",
+    "netzilo-windows-x64": "4.3.14"
+  },
+  "peerDependencies": {
+    "undici": "^8.5.0"
+  },
+  "peerDependenciesMeta": {
+    "undici": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.5.0"
+  }
+}