@xshieldai/n8n-nodes-kavachos 0.0.0-stage → 1.5.0

package/LICENSE

@@ -0,0 +1,31 @@
+GNU AFFERO GENERAL PUBLIC LICENSE
+Version 3, 19 November 2007
+
+Copyright (C) 2026 ANKR Labs / Capt. Anil Sharma
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+---
+
+The full text of the GNU Affero General Public License v3 is available at:
+https://www.gnu.org/licenses/agpl-3.0.txt
+
+ADDITIONAL TERMS (permitted under AGPL §7):
+
+If you run a modified version of this software as a network service,
+you must make the complete source code of the modified version available
+to all users of that service under the terms of this license.
+
+Commercial use, including SaaS deployments and enterprise integrations,
+requires a separate commercial license. Contact: captain@ankr.in

package/README.md

@@ -1,3 +1,96 @@
-# Temporary Holding Version
+# @xshieldai/n8n-nodes-kavachos
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **🔍 Verification status (2026-10-05 IST — v1.1.2)**
+> - **Tests:** ⚠️ none yet — n8n node test fixtures planned. See [PROOF-STACK.md](https://github.com/rocketlang/aegis/blob/master/PROOF-STACK.md).
+> - **Examples:** ✅ 1 importable workflow, in the repository (not in the npm package): [examples/n8n-governed-agent.json](https://github.com/rocketlang/aegis/blob/master/packages/n8n-nodes-kavachos/examples/n8n-governed-agent.json). Drag into n8n, wire the Aegis API credential pointing at `http://localhost:4850`, run.
+> - **Live demo:** ⚠️ planned (Tier 3)
+> - **Phase-1 limits:** KavachRun is Linux-only; where enforcement is unavailable (non-Linux, or `kavachos` not installed) it **fails closed by default** (`On Non-Linux` = `throw`; `warn`/`skip` are opt-in). KavachGate works on any OS — it's a thin HTTP relay to AEGIS.
+>
+> The KavachGate node's behaviour is end-to-end testable against a live AEGIS instance — start AEGIS, import the example workflow, fire a `rm -rf /` command, watch it block. Automated CI fixtures still to come.
+
+> **Renamed at 1.5.0.** This package was `@xshieldai/n8n-nodes` through 1.4.1. n8n's community-nodes screen
+> only installs a package whose name starts with `n8n-nodes-` after the scope, and refused the old name. The
+> nodes are the same. A workflow saved with the old package names its nodes `@xshieldai/n8n-nodes.kavachGate`
+> and so on: after installing this package, change that prefix to `@xshieldai/n8n-nodes-kavachos.` in the
+> workflow (or re-add the nodes), and remove the old package.
+
+**KavachOS n8n community nodes** — pre-execution DAN gate and kernel enforcement for AI agents.
+
+Part of the **xShieldAI Posture Suite** · [kavachos.xshieldai.com](https://kavachos.xshieldai.com)
+
+---
+
+## Nodes
+
+### KavachGate
+
+Intercepts AI agent actions **before execution**. Calls the Aegis KAVACH HTTP gate to:
+
+1. Classify danger level (DAN 1–4)
+2. Notify approvers via Telegram / WhatsApp (opt-in, requires `webhook_url` in `~/.aegis/config.json`)
+3. Wait for ALLOW or STOP
+4. Block the workflow on STOP or timeout (silence = STOP)
+
+**Framework-neutral**: all policy lives in Aegis (`localhost:4850`). The n8n node is a thin HTTP client.
+
+### KavachRun
+
+Wraps a subprocess in kavachos **kernel enforcement** (seccomp-bpf + cgroup BPF egress firewall).
+
+**Requires `@xshieldai/agent-kernel` 2.5.0 or later** (since 1.3.0). The node starts
+`kavachos run <options> -- <binary> <arguments>`, so the binary's arguments are passed on word for word and
+cannot be read as kavachos options. With an older `kavachos` the node refuses to run. See the changelog.
+
+Since 1.4.0 the node waits for the command without stopping n8n, stops it at **Time Limit (seconds)**, and
+reports what `kavachos` itself said: a refused launch is an error, and `enforced` is true only when no layer
+was reported missing (`egress_constrained`, `path_jail_loaded`). It reads kavachos's own lines for this, so
+it is as true as they are.
+
+**This node runs a command on the n8n host.** Anyone who can edit a workflow that contains it can run a
+program there, as n8n's own Execute Command node can. Install it only where that is acceptable.
+
+- Linux only — where enforcement is unavailable it **fails closed by default** (`On Non-Linux` = `throw`; set `warn` to run unwrapped, or `skip`)
+- Use **after** KavachGate for defense in depth: policy gate + kernel enforcement
+- `trust_mask` controls which syscall groups the process may call
+- `domain` selects the egress allowlist (maritime, logistics, OT, finance, general)
+
+---
+
+## Install
+
+```bash
+# In your n8n data directory
+npm install @xshieldai/n8n-nodes-kavachos
+```
+
+Then restart n8n and add the **Aegis API** credential pointing to your Aegis dashboard (`http://localhost:4850` by default).
+
+---
+
+## Quick Start
+
+1. **Start Aegis**: `npx @xshieldai/aegis` (or `kavachos run --domain=general -- n8n`)
+2. **Add credential**: Aegis API → base URL `http://localhost:4850`
+3. **Import template**: `examples/n8n-governed-agent.json`
+4. **Run**: Trigger → KavachGate → AI Agent → Audit
+
+---
+
+## Gate API
+
+The `KavachGate` node calls:
+
+```
+POST http://localhost:4850/api/v1/kavach/gate
+{ "command": "...", "tool_name": "n8n-agent", "session_id": "...", "dry_run": false }
+
+→ { "allow": true|false, "level": 0-4, "reason": "...", "decision": "ALLOW|STOP|TIMEOUT", "approval_id": "...", "_meta": {...} }
+```
+
+`allow: false` → KavachGate throws (halt workflow) or passes `allow=false` downstream — configurable per node.
+
+---
+
+## License
+
+AGPL-3.0 — governance layer is open. Enterprise Edition (multi-tenant, Merkle ledger, EU AI Act evidence): [xshieldai.com](https://xshieldai.com)

package/dist/credentials/AegisApi.credentials.d.ts

@@ -0,0 +1,7 @@
+import type { ICredentialType, INodeProperties } from "n8n-workflow";
+export declare class AegisApi implements ICredentialType {
+    name: string;
+    displayName: string;
+    documentationUrl: string;
+    properties: INodeProperties[];
+}

package/dist/credentials/AegisApi.credentials.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AegisApi = void 0;
+class AegisApi {
+    constructor() {
+        this.name = "aegisApi";
+        this.displayName = "Aegis API";
+        this.documentationUrl = "https://kavachos.xshieldai.com";
+        this.properties = [
+            {
+                displayName: "Aegis Base URL",
+                name: "baseUrl",
+                type: "string",
+                default: "http://localhost:4850",
+                placeholder: "http://localhost:4850",
+                description: "URL of the Aegis dashboard server (runs POST /api/v1/kavach/gate)",
+            },
+            {
+                displayName: "API Token (optional)",
+                name: "token",
+                type: "string",
+                typeOptions: { password: true },
+                default: "",
+                description: "Bearer token if Aegis dashboard auth is enabled",
+            },
+        ];
+    }
+}
+exports.AegisApi = AegisApi;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { KavachGate } from "./nodes/KavachGate/KavachGate.node";
+export { KavachRun } from "./nodes/KavachRun/KavachRun.node";
+export { KavachBudget } from "./nodes/KavachBudget/KavachBudget.node";
+export { KavachAudit } from "./nodes/KavachAudit/KavachAudit.node";
+export { AegisApi } from "./credentials/AegisApi.credentials";

package/dist/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AegisApi = exports.KavachAudit = exports.KavachBudget = exports.KavachRun = exports.KavachGate = void 0;
+// SPDX-License-Identifier: AGPL-3.0-only
+var KavachGate_node_1 = require("./nodes/KavachGate/KavachGate.node");
+Object.defineProperty(exports, "KavachGate", { enumerable: true, get: function () { return KavachGate_node_1.KavachGate; } });
+var KavachRun_node_1 = require("./nodes/KavachRun/KavachRun.node");
+Object.defineProperty(exports, "KavachRun", { enumerable: true, get: function () { return KavachRun_node_1.KavachRun; } });
+var KavachBudget_node_1 = require("./nodes/KavachBudget/KavachBudget.node");
+Object.defineProperty(exports, "KavachBudget", { enumerable: true, get: function () { return KavachBudget_node_1.KavachBudget; } });
+var KavachAudit_node_1 = require("./nodes/KavachAudit/KavachAudit.node");
+Object.defineProperty(exports, "KavachAudit", { enumerable: true, get: function () { return KavachAudit_node_1.KavachAudit; } });
+var AegisApi_credentials_1 = require("./credentials/AegisApi.credentials");
+Object.defineProperty(exports, "AegisApi", { enumerable: true, get: function () { return AegisApi_credentials_1.AegisApi; } });

package/dist/nodes/KavachAudit/KavachAudit.node.d.ts

@@ -0,0 +1,5 @@
+import type { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription } from "n8n-workflow";
+export declare class KavachAudit implements INodeType {
+    description: INodeTypeDescription;
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+}

package/dist/nodes/KavachAudit/KavachAudit.node.js

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KavachAudit = void 0;
+const n8n_workflow_1 = require("n8n-workflow");
+const shared_1 = require("../shared");
+class KavachAudit {
+    constructor() {
+        this.description = {
+            displayName: "Kavach Audit",
+            name: "kavachAudit",
+            icon: "file:kavach-audit.svg",
+            group: ["transform"],
+            version: 1,
+            subtitle: "Query DAN gate audit log",
+            description: "Queries the AEGIS audit log (kavach_approvals table). Returns gate decisions filtered by " +
+                "session ID, status, DAN level, or date range. Use for compliance reporting or post-incident review.",
+            defaults: { name: "Kavach Audit" },
+            inputs: ["main"],
+            outputs: ["main"],
+            credentials: [
+                {
+                    name: "aegisApi",
+                    required: true,
+                },
+            ],
+            properties: [
+                {
+                    displayName: "Filter by Session ID",
+                    name: "sessionId",
+                    type: "string",
+                    default: "",
+                    placeholder: "exec_abc123",
+                    description: "Return only records for this session. Leave empty for all sessions.",
+                },
+                {
+                    displayName: "Filter by Status",
+                    name: "status",
+                    type: "options",
+                    options: [
+                        { name: "All", value: "all" },
+                        { name: "Pending", value: "pending" },
+                        { name: "Allowed", value: "allow" },
+                        { name: "Stopped", value: "stop" },
+                        { name: "Timed Out", value: "timeout" },
+                    ],
+                    default: "all",
+                    description: "Return only records matching this approval status.",
+                },
+                {
+                    displayName: "Filter by DAN Level",
+                    name: "danLevel",
+                    type: "options",
+                    options: [
+                        { name: "All levels", value: 0 },
+                        { name: "DAN-1 (safe)", value: 1 },
+                        { name: "DAN-2 (elevated)", value: 2 },
+                        { name: "DAN-3 (dangerous)", value: 3 },
+                        { name: "DAN-4 (catastrophic)", value: 4 },
+                    ],
+                    default: 0,
+                    description: "Return only records at this DAN level. 0 = all levels.",
+                },
+                {
+                    displayName: "Limit",
+                    name: "limit",
+                    type: "number",
+                    default: 50,
+                    description: "Maximum number of records to return.",
+                },
+            ],
+        };
+    }
+    async execute() {
+        const items = this.getInputData();
+        const results = [];
+        const credentials = await this.getCredentials("aegisApi");
+        const baseUrl = credentials.baseUrl.replace(/\/$/, "");
+        const token = credentials.token;
+        for (let i = 0; i < items.length; i++) {
+            const sessionId = this.getNodeParameter("sessionId", i).trim();
+            const status = this.getNodeParameter("status", i);
+            const danLevel = this.getNodeParameter("danLevel", i);
+            const limit = this.getNodeParameter("limit", i);
+            const params = new URLSearchParams();
+            if (sessionId)
+                params.set("session_id", sessionId);
+            if (status !== "all")
+                params.set("status", status);
+            if (danLevel > 0)
+                params.set("level", danLevel.toString());
+            params.set("limit", limit.toString());
+            const headers = {};
+            if (token)
+                headers["Authorization"] = `Bearer ${token}`;
+            let auditResult;
+            let reply;
+            try {
+                reply = await (0, shared_1.requestJson)("GET", `${baseUrl}/api/v1/kavach/audit?${params.toString()}`, headers, undefined, 30000);
+            }
+            catch (err) {
+                throw new n8n_workflow_1.NodeOperationError(this.getNode(), err?.message === "TIMEOUT" ? `Aegis audit did not answer within 30 s at ${baseUrl}` : `Cannot reach Aegis audit at ${baseUrl}: ${err?.message ?? err}`, { itemIndex: i });
+            }
+            if (reply.status !== 200 || !reply.json || typeof reply.json !== "object") {
+                throw new n8n_workflow_1.NodeOperationError(this.getNode(), `Aegis audit answered HTTP ${reply.status}: ${reply.text.slice(0, 300)}. On a dashboard with a password the audit needs the API token (dashboard.auth.api_token), set in this credential.`, { itemIndex: i });
+            }
+            auditResult = reply.json;
+            results.push({
+                json: {
+                    ...items[i].json,
+                    kavach_audit: {
+                        records: auditResult.records,
+                        total: auditResult.total,
+                        _meta: auditResult._meta,
+                    },
+                },
+                pairedItem: i,
+            });
+        }
+        return [results];
+    }
+}
+exports.KavachAudit = KavachAudit;

package/dist/nodes/KavachAudit/kavach-audit.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="Kavach Audit">
+  <path d="M32 4 54 12v18c0 14-9 25-22 30C19 55 10 44 10 30V12z" fill="#1f3a5f"/>
+  <path d="M32 9 49 15.5V30c0 11.5-7 20.5-17 24.6C22 50.500 15 41.500 15 30V15.500z" fill="#f4f1e8"/>
+  <path d="M23 23h18M23 31h18M23 39h11" stroke="#1f3a5f" stroke-width="3.500" stroke-linecap="round"/><path d="m37 40 3 3 6-7" fill="none" stroke="#c2532d" stroke-width="3.500" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/dist/nodes/KavachBudget/KavachBudget.node.d.ts

@@ -0,0 +1,5 @@
+import type { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription } from "n8n-workflow";
+export declare class KavachBudget implements INodeType {
+    description: INodeTypeDescription;
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+}

package/dist/nodes/KavachBudget/KavachBudget.node.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KavachBudget = void 0;
+const n8n_workflow_1 = require("n8n-workflow");
+const shared_1 = require("../shared");
+class KavachBudget {
+    constructor() {
+        this.description = {
+            displayName: "Kavach Budget",
+            name: "kavachBudget",
+            icon: "file:kavach-budget.svg",
+            group: ["transform"],
+            version: 1,
+            subtitle: "Budget + valve state",
+            description: "Reads the current AEGIS budget state (daily spend, limit, remaining, breach flag) and " +
+                "gate-valve status. Use to guard expensive workflows or to surface cost data in dashboards.",
+            defaults: { name: "Kavach Budget" },
+            inputs: ["main"],
+            outputs: ["main", "main"],
+            outputNames: ["within budget", "breached"],
+            credentials: [
+                {
+                    name: "aegisApi",
+                    required: true,
+                },
+            ],
+            properties: [
+                {
+                    displayName: "Halt on Breach",
+                    name: "haltOnBreach",
+                    type: "boolean",
+                    default: false,
+                    description: "When true and budget is breached, throw an error instead of routing to the 'breached' output.",
+                },
+            ],
+        };
+    }
+    async execute() {
+        const items = this.getInputData();
+        const withinBudget = [];
+        const breachedItems = [];
+        const credentials = await this.getCredentials("aegisApi");
+        const baseUrl = credentials.baseUrl.replace(/\/$/, "");
+        const token = credentials.token;
+        for (let i = 0; i < items.length; i++) {
+            const haltOnBreach = this.getNodeParameter("haltOnBreach", i);
+            const headers = {};
+            if (token)
+                headers["Authorization"] = `Bearer ${token}`;
+            let state;
+            let reply;
+            try {
+                reply = await (0, shared_1.requestJson)("GET", `${baseUrl}/api/v1/kavach/state`, headers, undefined, 30000);
+            }
+            catch (err) {
+                throw new n8n_workflow_1.NodeOperationError(this.getNode(), err?.message === "TIMEOUT" ? `Aegis state did not answer within 30 s at ${baseUrl}` : `Cannot reach Aegis state at ${baseUrl}: ${err?.message ?? err}`, { itemIndex: i });
+            }
+            if (reply.status !== 200 || !reply.json || typeof reply.json !== "object") {
+                throw new n8n_workflow_1.NodeOperationError(this.getNode(), `Aegis state answered HTTP ${reply.status}: ${reply.text.slice(0, 300)}.`, { itemIndex: i });
+            }
+            state = reply.json;
+            if (!state.budget || typeof state.budget.breached !== "boolean") {
+                throw new n8n_workflow_1.NodeOperationError(this.getNode(), `what answered at ${baseUrl} is not the Aegis budget state`, { itemIndex: i });
+            }
+            const output = {
+                json: {
+                    ...items[i].json,
+                    kavach_budget: {
+                        daily_spent_usd: state.budget.daily_spent_usd,
+                        daily_limit_usd: state.budget.daily_limit_usd,
+                        daily_remaining_usd: state.budget.daily_remaining_usd,
+                        breached: state.budget.breached,
+                        kavach_enabled: state.kavach_enabled,
+                        _meta: state._meta,
+                    },
+                },
+                pairedItem: i,
+            };
+            if (state.budget.breached) {
+                if (haltOnBreach) {
+                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), `KAVACH budget breached: $${state.budget.daily_spent_usd.toFixed(4)} of $${state.budget.daily_limit_usd} daily limit used`, { itemIndex: i });
+                }
+                breachedItems.push(output);
+            }
+            else {
+                withinBudget.push(output);
+            }
+        }
+        return [withinBudget, breachedItems];
+    }
+}
+exports.KavachBudget = KavachBudget;

package/dist/nodes/KavachBudget/kavach-budget.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="Kavach Budget">
+  <path d="M32 4 54 12v18c0 14-9 25-22 30C19 55 10 44 10 30V12z" fill="#1f3a5f"/>
+  <path d="M32 9 49 15.5V30c0 11.5-7 20.5-17 24.6C22 50.500 15 41.500 15 30V15.500z" fill="#f4f1e8"/>
+  <circle cx="32" cy="32" r="12" fill="none" stroke="#1f3a5f" stroke-width="3.500"/><path d="M32 32V22M32 32l8 5" stroke="#c2532d" stroke-width="3.500" stroke-linecap="round"/>
+</svg>

package/dist/nodes/KavachGate/KavachGate.node.d.ts

@@ -0,0 +1,5 @@
+import type { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription } from "n8n-workflow";
+export declare class KavachGate implements INodeType {
+    description: INodeTypeDescription;
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+}

package/dist/nodes/KavachGate/KavachGate.node.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KavachGate = void 0;
+const n8n_workflow_1 = require("n8n-workflow");
+const shared_1 = require("../shared");
+class KavachGate {
+    constructor() {
+        this.description = {
+            displayName: "Kavach Gate",
+            name: "kavachGate",
+            icon: "file:kavach-gate.svg",
+            group: ["transform"],
+            version: 1,
+            subtitle: "Pre-execution DAN gate",
+            description: "Intercepts AI agent actions before execution. Calls the Aegis KAVACH gate to classify danger level (DAN 1-4), notify approvers, and wait for ALLOW/STOP. Blocks the workflow on STOP or timeout.",
+            defaults: { name: "Kavach Gate" },
+            inputs: ["main"],
+            outputs: ["main"],
+            credentials: [
+                {
+                    name: "aegisApi",
+                    required: true,
+                },
+            ],
+            properties: [
+                {
+                    displayName: "Command",
+                    name: "command",
+                    type: "string",
+                    default: "={{ $json.command }}",
+                    required: true,
+                    description: "The command or action the agent wants to execute. Accepts an expression referencing upstream node output.",
+                    placeholder: "prisma migrate reset",
+                },
+                {
+                    displayName: "Tool Name",
+                    name: "toolName",
+                    type: "string",
+                    default: "n8n-agent",
+                    description: "Name of the tool/node calling this gate. Appears in audit records.",
+                },
+                {
+                    displayName: "Session ID",
+                    name: "sessionId",
+                    type: "string",
+                    default: "={{ $execution.id }}",
+                    description: "Workflow execution ID used for audit trail grouping.",
+                },
+                {
+                    displayName: "Dry Run",
+                    name: "dryRun",
+                    type: "boolean",
+                    default: false,
+                    description: "Classify danger level only — no notification sent, no polling. Use for testing the gate without blocking.",
+                },
+                {
+                    displayName: "Wait For A Decision (seconds)",
+                    name: "timeoutSeconds",
+                    type: "number",
+                    default: 660,
+                    description: "How long to wait for the gate's answer. Aegis itself waits up to 600 s for an approver on the lowest level, " +
+                        "so the default is a little longer. No answer in this time is treated as a block.",
+                },
+                {
+                    displayName: "On STOP / Timeout",
+                    name: "onBlock",
+                    type: "options",
+                    options: [
+                        { name: "Throw Error (halt workflow)", value: "throw" },
+                        { name: "Continue with allow=false", value: "continue" },
+                    ],
+                    default: "throw",
+                    description: "What to do when the gate blocks the action. Default: throw error to halt the workflow.",
+                },
+            ],
+        };
+    }
+    async execute() {
+        const items = this.getInputData();
+        const results = [];
+        const credentials = await this.getCredentials("aegisApi");
+        const baseUrl = credentials.baseUrl.replace(/\/$/, "");
+        const token = credentials.token;
+        for (let i = 0; i < items.length; i++) {
+            const command = this.getNodeParameter("command", i);
+            const toolName = this.getNodeParameter("toolName", i);
+            const sessionId = this.getNodeParameter("sessionId", i);
+            const dryRun = this.getNodeParameter("dryRun", i);
+            const onBlock = this.getNodeParameter("onBlock", i);
+            const limit = Number(this.getNodeParameter("timeoutSeconds", i, 660));
+            const timeoutMs = (Number.isFinite(limit) && limit > 0 ? limit : 660) * 1000;
+            if (!command?.trim()) {
+                throw new n8n_workflow_1.NodeOperationError(this.getNode(), "command must not be empty", { itemIndex: i });
+            }
+            const headers = { "Content-Type": "application/json" };
+            if (token)
+                headers["Authorization"] = `Bearer ${token}`;
+            let gateResult;
+            // Three different failures, said as what they are: no answer in time (a block), an answer that is
+            // not the gate's (an error), and Aegis not reachable (an error). Through 1.3.0 all three read
+            // "Cannot reach Aegis gate".
+            let reply;
+            try {
+                reply = await (0, shared_1.requestJson)("POST", `${baseUrl}/api/v1/kavach/gate`, headers, JSON.stringify({ command, tool_name: toolName, session_id: sessionId, dry_run: dryRun }), timeoutMs);
+            }
+            catch (err) {
+                if (err?.message === "TIMEOUT") {
+                    gateResult = { allow: false, reason: `no decision from the Aegis gate within ${timeoutMs / 1000} s`, decision: "TIMEOUT" };
+                    reply = undefined;
+                }
+                else {
+                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), `Cannot reach Aegis gate at ${baseUrl}: ${err?.message ?? err}`, { itemIndex: i });
+                }
+            }
+            if (reply) {
+                if (reply.status !== 200) {
+                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), `Aegis gate answered HTTP ${reply.status}, not a decision: ${reply.text.slice(0, 300)}`, { itemIndex: i });
+                }
+                const j = reply.json;
+                if (!j || typeof j !== "object" || typeof j.allow !== "boolean") {
+                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), `what answered at ${baseUrl} is not the Aegis gate: no true/false "allow" in its answer. Treated as a block.`, { itemIndex: i });
+                }
+                gateResult = j;
+            }
+            gateResult = gateResult;
+            // Only the boolean true is an allow. A string, a number or anything else is not.
+            if (gateResult.allow !== true) {
+                if (onBlock === "throw") {
+                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), `KAVACH blocked action (DAN ${gateResult.level ?? "?"}): ${gateResult.reason}`, { itemIndex: i });
+                }
+                // continue mode — pass allow=false downstream
+            }
+            results.push({
+                json: {
+                    ...items[i].json,
+                    kavach: {
+                        allow: gateResult.allow === true,
+                        level: gateResult.level,
+                        reason: gateResult.reason,
+                        decision: gateResult.decision,
+                        approval_id: gateResult.approval_id,
+                        _meta: gateResult._meta,
+                    },
+                },
+                pairedItem: i,
+            });
+        }
+        return [results];
+    }
+}
+exports.KavachGate = KavachGate;

package/dist/nodes/KavachGate/kavach-gate.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="Kavach Gate">
+  <path d="M32 4 54 12v18c0 14-9 25-22 30C19 55 10 44 10 30V12z" fill="#1f3a5f"/>
+  <path d="M32 9 49 15.5V30c0 11.5-7 20.5-17 24.6C22 50.500 15 41.500 15 30V15.500z" fill="#f4f1e8"/>
+  <path d="M22 44V28a10 10 0 0 1 20 0v16M27 44V30a5 5 0 0 1 10 0v14" fill="none" stroke="#1f3a5f" stroke-width="3.500" stroke-linecap="round"/><path d="M20 44h24" stroke="#c2532d" stroke-width="3.500" stroke-linecap="round"/>
+</svg>

package/dist/nodes/KavachRun/KavachRun.node.d.ts

@@ -0,0 +1,5 @@
+import type { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription } from "n8n-workflow";
+export declare class KavachRun implements INodeType {
+    description: INodeTypeDescription;
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+}

package/dist/nodes/KavachRun/KavachRun.node.js

@@ -0,0 +1,245 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KavachRun = void 0;
+const n8n_workflow_1 = require("n8n-workflow");
+const child_process_1 = require("child_process");
+const shared_1 = require("../shared");
+function isLinux() {
+    return process.platform === "linux";
+}
+function kavachosAvailable() {
+    try {
+        (0, child_process_1.execSync)("which kavachos", { stdio: "pipe" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// kavachos reads a bare "--" as the end of its own options from 2.5.0. Before that, any word starting
+// with "--" among the binary's arguments was read as a kavachos option (a dry run, an unconstrained
+// launch, another trust mask). The arguments of this node often come from an expression, so the node
+// uses "--" and refuses a kavachos that does not know it.
+const KAVACHOS_MIN = "2.5.0";
+function kavachosVersion() {
+    const out = (0, child_process_1.spawnSync)("kavachos", ["version"], { encoding: "utf8", timeout: 15000 });
+    const m = /^kavachos (\d+\.\d+\.\d+)/m.exec(out.stdout ?? "");
+    return m ? m[1] : null;
+}
+function versionAtLeast(have, want) {
+    const h = have.split(".").map((n) => parseInt(n, 10));
+    const w = want.split(".").map((n) => parseInt(n, 10));
+    for (let i = 0; i < 3; i++) {
+        if ((h[i] ?? 0) !== (w[i] ?? 0))
+            return (h[i] ?? 0) > (w[i] ?? 0);
+    }
+    return true;
+}
+class KavachRun {
+    constructor() {
+        this.description = {
+            displayName: "Kavach Run",
+            name: "kavachRun",
+            icon: "file:kavach-run.svg",
+            group: ["transform"],
+            version: 1,
+            subtitle: "Kernel-enforced subprocess (Linux)",
+            description: "Wraps a subprocess in kavachos kernel enforcement (seccomp-bpf + cgroup BPF egress). " +
+                "Linux only — where enforcement is unavailable (non-Linux, or kavachos not installed) it " +
+                "FAILS CLOSED by default (configurable to warn or skip). " +
+                "Use after KavachGate for defense in depth: policy gate + kernel enforcement.",
+            defaults: { name: "Kavach Run" },
+            inputs: ["main"],
+            outputs: ["main"],
+            properties: [
+                {
+                    displayName: "Binary",
+                    name: "binary",
+                    type: "string",
+                    default: "",
+                    required: true,
+                    placeholder: "bun",
+                    description: "The binary to execute under kernel enforcement.",
+                },
+                {
+                    displayName: "Arguments",
+                    name: "args",
+                    type: "string",
+                    default: "",
+                    placeholder: "src/my-agent.ts --port 4900",
+                    description: "Space-separated arguments to pass to the binary.",
+                },
+                {
+                    displayName: "Trust Mask (hex)",
+                    name: "trustMask",
+                    type: "string",
+                    default: "0xFF",
+                    description: "Seccomp-bpf trust mask. Controls which syscall groups the process is allowed to call. " +
+                        "0xFF = infrastructure bits. See KavachOS trust_mask docs.",
+                },
+                {
+                    displayName: "Domain",
+                    name: "domain",
+                    type: "options",
+                    options: [
+                        { name: "general", value: "general" },
+                        { name: "maritime", value: "maritime" },
+                        { name: "logistics", value: "logistics" },
+                        { name: "ot", value: "ot" },
+                        { name: "finance", value: "finance" },
+                    ],
+                    default: "general",
+                    description: "Domain profile — controls egress allowlist and Falco rule set.",
+                },
+                {
+                    displayName: "Enable Falco",
+                    name: "falco",
+                    type: "boolean",
+                    default: false,
+                    description: "Enable Falco CRITICAL rule monitoring (requires Falco installed on host).",
+                },
+                {
+                    displayName: "Time Limit (seconds)",
+                    name: "timeoutSeconds",
+                    type: "number",
+                    default: 300,
+                    description: "The command is stopped after this long and the node fails. n8n keeps running other workflows meanwhile.",
+                },
+                {
+                    displayName: "On Non-Linux",
+                    name: "onNonLinux",
+                    type: "options",
+                    options: [
+                        { name: "Throw Error (fail closed)", value: "throw" },
+                        { name: "Warn and run unwrapped", value: "warn" },
+                        { name: "Skip execution entirely", value: "skip" },
+                    ],
+                    default: "throw",
+                    description: "Behavior when kernel enforcement is unavailable (non-Linux, or kavachos not installed). " +
+                        "Default THROW = fail closed: a defense-in-depth node must not silently run a command " +
+                        "unwrapped. Choose 'warn' to run unwrapped with an enforced:false flag, or 'skip' to not run it.",
+                },
+            ],
+        };
+    }
+    async execute() {
+        const items = this.getInputData();
+        const results = [];
+        for (let i = 0; i < items.length; i++) {
+            const binary = this.getNodeParameter("binary", i);
+            const args = this.getNodeParameter("args", i).trim();
+            const trustMask = this.getNodeParameter("trustMask", i);
+            const domain = this.getNodeParameter("domain", i);
+            const falco = this.getNodeParameter("falco", i);
+            const onNonLinux = this.getNodeParameter("onNonLinux", i);
+            const limit = Number(this.getNodeParameter("timeoutSeconds", i, 300));
+            const timeoutMs = (Number.isFinite(limit) && limit > 0 ? limit : 300) * 1000;
+            if (!binary?.trim()) {
+                throw new n8n_workflow_1.NodeOperationError(this.getNode(), "binary must not be empty", { itemIndex: i });
+            }
+            const linux = isLinux();
+            const hasKavachos = linux && kavachosAvailable();
+            if (!linux || !hasKavachos) {
+                const platform = process.platform;
+                const reason = !linux
+                    ? `KavachRun kernel enforcement not available on ${platform} — requires Linux with seccomp-bpf`
+                    : "kavachos CLI not found — install with: npm install -g @xshieldai/agent-kernel";
+                if (onNonLinux === "throw") {
+                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), reason, { itemIndex: i });
+                }
+                if (onNonLinux === "skip") {
+                    results.push({
+                        json: { ...items[i].json, kavach_run: { skipped: true, reason } },
+                        pairedItem: i,
+                    });
+                    continue;
+                }
+                // warn: run unwrapped with a flag in output
+                process.stderr.write(`[KavachRun] WARNING: ${reason} — running ${binary} unwrapped\n`);
+                const argList = args ? args.split(/\s+/) : [];
+                const proc = await (0, shared_1.runProcess)(binary, argList, timeoutMs);
+                if (proc.error) {
+                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), `${binary} could not be started: ${proc.error}`, { itemIndex: i });
+                }
+                if (proc.timedOut) {
+                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), `${binary} was stopped after ${timeoutMs / 1000} s (the node's time limit)`, { itemIndex: i });
+                }
+                results.push({
+                    json: {
+                        ...items[i].json,
+                        kavach_run: {
+                            enforced: false,
+                            reason,
+                            stdout: proc.stdout,
+                            stderr: proc.stderr,
+                            exit_code: proc.code,
+                            output_truncated: proc.truncated,
+                        },
+                    },
+                    pairedItem: i,
+                });
+                continue;
+            }
+            // Linux + kavachos available. It must be one that reads "--": with an older one the words
+            // below the separator would still be read as its options, so that is a refusal, not a warning.
+            const have = kavachosVersion();
+            if (!have || !versionAtLeast(have, KAVACHOS_MIN)) {
+                throw new n8n_workflow_1.NodeOperationError(this.getNode(), `kavachos ${have ?? "(version not readable)"} is too old for this node: ${KAVACHOS_MIN} or later is needed ` +
+                    `(npm install -g @xshieldai/agent-kernel@latest). Not run.`, { itemIndex: i });
+            }
+            if (/\s/.test(trustMask) || /\s/.test(domain)) {
+                throw new n8n_workflow_1.NodeOperationError(this.getNode(), "trust mask and domain must be single words", { itemIndex: i });
+            }
+            // Everything after "--" is the binary and its arguments, passed on word for word.
+            const kavachArgs = [
+                "run",
+                `--trust-mask=${trustMask}`,
+                `--domain=${domain}`,
+                ...(falco ? ["--falco"] : []),
+                "--",
+                binary,
+                ...(args ? args.split(/\s+/) : []),
+            ];
+            const proc = await (0, shared_1.runProcess)("kavachos", kavachArgs, timeoutMs);
+            if (proc.error) {
+                throw new n8n_workflow_1.NodeOperationError(this.getNode(), `kavachos could not be started: ${proc.error}`, { itemIndex: i });
+            }
+            if (proc.timedOut) {
+                throw new n8n_workflow_1.NodeOperationError(this.getNode(), `the command was stopped after ${timeoutMs / 1000} s (the node's time limit)`, { itemIndex: i });
+            }
+            // What kavachos itself said about this launch. Through 1.3.0 the node wrote "enforced: true"
+            // whenever kavachos had been started, whatever it then did.
+            //   refused        kavachos would not launch the command at all (its exit 3, with its own line)
+            //   unconstrained  it launched, and said the egress gate was NOT in force for this launch
+            const refusal = /^\[kavachos\] launch refused: (.*)$/m.exec(proc.stderr);
+            if (refusal) {
+                throw new n8n_workflow_1.NodeOperationError(this.getNode(), `kavachos refused to launch the command: ${refusal[1]}. Nothing was run.`, { itemIndex: i });
+            }
+            const egressConstrained = !/NOT egress-constrained|egress_enforced=false/.test(proc.stderr);
+            const jailMissing = /path jail .* not loaded/.test(proc.stderr);
+            results.push({
+                json: {
+                    ...items[i].json,
+                    kavach_run: {
+                        // True only when kavachos launched the command and reported no layer missing.
+                        enforced: egressConstrained && !jailMissing,
+                        launched_by_kavachos: true,
+                        egress_constrained: egressConstrained,
+                        path_jail_loaded: !jailMissing,
+                        kavachos_version: have,
+                        trust_mask: trustMask,
+                        domain,
+                        falco_enabled: falco,
+                        stdout: proc.stdout,
+                        stderr: proc.stderr,
+                        exit_code: proc.code,
+                        output_truncated: proc.truncated,
+                    },
+                },
+                pairedItem: i,
+            });
+        }
+        return [results];
+    }
+}
+exports.KavachRun = KavachRun;

package/dist/nodes/KavachRun/kavach-run.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="Kavach Run">
+  <path d="M32 4 54 12v18c0 14-9 25-22 30C19 55 10 44 10 30V12z" fill="#1f3a5f"/>
+  <path d="M32 9 49 15.5V30c0 11.5-7 20.5-17 24.6C22 50.500 15 41.500 15 30V15.500z" fill="#f4f1e8"/>
+  <path d="M26 21v22l18-11z" fill="#c2532d"/><rect x="20" y="17" width="26" height="30" rx="4" fill="none" stroke="#1f3a5f" stroke-width="3"/>
+</svg>

package/dist/nodes/shared.d.ts

@@ -0,0 +1,28 @@
+export interface ProcessResult {
+    stdout: string;
+    stderr: string;
+    /** The exit status, or null when the process was killed or never started. */
+    code: number | null;
+    timedOut: boolean;
+    /** Output beyond the cap was dropped (the process was left to finish). */
+    truncated: boolean;
+    /** Set when the process could not be started at all. */
+    error?: string;
+}
+/**
+ * Run a command and wait for it WITHOUT blocking n8n's event loop. Through 1.3.0 the nodes used a blocking
+ * call with no time limit: every other workflow, and n8n's own interface, stopped until the command ended.
+ */
+export declare function runProcess(command: string, args: string[], timeoutMs: number, maxBytes?: number): Promise<ProcessResult>;
+export interface JsonReply {
+    status: number;
+    /** The parsed body, or undefined when it was not JSON. */
+    json?: unknown;
+    text: string;
+}
+/**
+ * One HTTP request to Aegis with OUR time limit. A redirect is not followed: it comes back as its 3xx status.
+ * (The global fetch gives up waiting for an answer after about five minutes whatever the caller wants, which
+ * is shorter than the gate's own wait for a level-1 approval.)
+ */
+export declare function requestJson(method: "GET" | "POST", url: string, headers: Record<string, string>, body: string | undefined, timeoutMs: number): Promise<JsonReply>;

package/dist/nodes/shared.js

@@ -0,0 +1,139 @@
+"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.runProcess = runProcess;
+exports.requestJson = requestJson;
+// SPDX-License-Identifier: AGPL-3.0-only
+// Shared by the Kavach nodes: running a command without stopping n8n, and asking Aegis with a time limit.
+const child_process_1 = require("child_process");
+const http = __importStar(require("http"));
+const https = __importStar(require("https"));
+/**
+ * Run a command and wait for it WITHOUT blocking n8n's event loop. Through 1.3.0 the nodes used a blocking
+ * call with no time limit: every other workflow, and n8n's own interface, stopped until the command ended.
+ */
+function runProcess(command, args, timeoutMs, maxBytes = 5 * 1024 * 1024) {
+    return new Promise((resolve) => {
+        let stdout = "", stderr = "", size = 0, truncated = false, timedOut = false, done = false;
+        const finish = (r) => { if (done)
+            return; done = true; clearTimeout(timer); resolve({ stdout, stderr, code: null, timedOut, truncated, ...r }); };
+        let child;
+        try {
+            child = (0, child_process_1.spawn)(command, args, { stdio: ["ignore", "pipe", "pipe"] });
+        }
+        catch (e) {
+            resolve({ stdout, stderr, code: null, timedOut, truncated, error: e.message });
+            return;
+        }
+        const timer = setTimeout(() => {
+            timedOut = true;
+            try {
+                child.kill("SIGTERM");
+            }
+            catch { /* already gone */ }
+            setTimeout(() => { try {
+                child.kill("SIGKILL");
+            }
+            catch { /* already gone */ } }, 2000).unref();
+        }, timeoutMs);
+        const take = (which) => (d) => {
+            if (size >= maxBytes) {
+                truncated = true;
+                return;
+            }
+            const room = maxBytes - size, piece = d.length > room ? d.subarray(0, room) : d;
+            if (piece.length < d.length)
+                truncated = true;
+            size += piece.length;
+            if (which === "out")
+                stdout += piece.toString("utf8");
+            else
+                stderr += piece.toString("utf8");
+        };
+        child.stdout?.on("data", take("out"));
+        child.stderr?.on("data", take("err"));
+        child.on("error", (e) => finish({ error: e.message }));
+        child.on("close", (code) => finish({ code }));
+    });
+}
+/**
+ * One HTTP request to Aegis with OUR time limit. A redirect is not followed: it comes back as its 3xx status.
+ * (The global fetch gives up waiting for an answer after about five minutes whatever the caller wants, which
+ * is shorter than the gate's own wait for a level-1 approval.)
+ */
+function requestJson(method, url, headers, body, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        let u;
+        try {
+            u = new URL(url);
+        }
+        catch {
+            reject(new Error(`not a URL: ${url}`));
+            return;
+        }
+        if (u.protocol !== "http:" && u.protocol !== "https:") {
+            reject(new Error(`not an http(s) URL: ${url}`));
+            return;
+        }
+        const lib = u.protocol === "https:" ? https : http;
+        const h = { ...headers };
+        if (body !== undefined)
+            h["Content-Length"] = String(Buffer.byteLength(body));
+        const req = lib.request(u, { method, headers: h }, (res) => {
+            const chunks = [];
+            let size = 0;
+            res.on("data", (d) => { size += d.length; if (size <= 10 * 1024 * 1024)
+                chunks.push(d); });
+            res.on("end", () => {
+                clearTimeout(timer);
+                const text = Buffer.concat(chunks).toString("utf8");
+                let json;
+                try {
+                    json = JSON.parse(text);
+                }
+                catch {
+                    json = undefined;
+                }
+                resolve({ status: res.statusCode ?? 0, json, text });
+            });
+            res.on("error", (e) => { clearTimeout(timer); reject(e); });
+        });
+        const timer = setTimeout(() => { req.destroy(new Error("TIMEOUT")); }, timeoutMs);
+        req.on("error", (e) => { clearTimeout(timer); reject(e); });
+        if (body !== undefined)
+            req.write(body);
+        req.end();
+    });
+}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@xshieldai/n8n-nodes-kavachos",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.5.0",
+  "description": "xShieldAI n8n community nodes — DAN gate, kernel enforcement, budget check, and audit log for AI agents.",
+  "license": "AGPL-3.0-only",
+  "author": "Capt. Anil Sharma <capt.anil.sharma@powerpbox.org>",
+  "homepage": "https://kavachos.xshieldai.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rocketlang/aegis.git",
+    "directory": "packages/n8n-nodes-kavachos"
+  },
+  "keywords": [
+    "n8n-community-node-package",
+    "kavachos",
+    "xshieldai",
+    "ai-governance",
+    "seccomp",
+    "agent-safety"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "n8n": {
+    "n8nNodesApiVersion": 1,
+    "credentials": [
+      "dist/credentials/AegisApi.credentials.js"
+    ],
+    "nodes": [
+      "dist/nodes/KavachGate/KavachGate.node.js",
+      "dist/nodes/KavachRun/KavachRun.node.js",
+      "dist/nodes/KavachBudget/KavachBudget.node.js",
+      "dist/nodes/KavachAudit/KavachAudit.node.js"
+    ]
+  },
+  "scripts": {
+    "build": "tsc && node -e \"const fs=require('fs'),p=require('path');for(const d of fs.readdirSync('nodes',{withFileTypes:true})){if(!d.isDirectory())continue;for(const f of fs.readdirSync(p.join('nodes',d.name))){if(f.endsWith('.svg'))fs.copyFileSync(p.join('nodes',d.name,f),p.join('dist','nodes',d.name,f))}}\"",
+    "dev": "tsc --watch",
+    "prepublishOnly": "node ../../scripts/publish-guard.mjs && npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "n8n-workflow": "^1.0.0",
+    "@types/node": "^20.0.0"
+  },
+  "peerDependencies": {
+    "n8n-workflow": ">=1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}