@gatewaystack/gatewaystack-governance 0.1.0

package/scripts/governance/rate-limit.d.ts

@@ -0,0 +1,5 @@
+import type { Policy } from "./types.js";
+export declare function checkRateLimit(userId: string, session: string | undefined, policy: Policy): {
+    allowed: boolean;
+    detail: string;
+};

package/scripts/governance/rate-limit.js

@@ -0,0 +1,156 @@
+"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.checkRateLimit = checkRateLimit;
+const fs = __importStar(require("fs"));
+const constants_js_1 = require("./constants.js");
+const LOCK_PATH = constants_js_1.RATE_LIMIT_STATE_PATH + ".lock";
+const LOCK_TIMEOUT_MS = 5000;
+const LOCK_RETRY_MS = 50;
+function isLockStale() {
+    try {
+        const pidStr = fs.readFileSync(LOCK_PATH, "utf-8").trim();
+        const pid = parseInt(pidStr, 10);
+        if (isNaN(pid))
+            return true;
+        // process.kill(pid, 0) throws if the process doesn't exist
+        process.kill(pid, 0);
+        return false; // process is alive, lock is valid
+    }
+    catch {
+        return true; // can't read or process is dead — stale lock
+    }
+}
+function acquireLock() {
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        try {
+            // O_EXCL: fail if file exists — atomic advisory lock
+            fs.writeFileSync(LOCK_PATH, String(process.pid), { flag: "wx" });
+            return true;
+        }
+        catch {
+            // Lock file exists — check if the holding process is still alive
+            if (isLockStale()) {
+                try {
+                    fs.unlinkSync(LOCK_PATH);
+                    continue; // retry immediately after clearing stale lock
+                }
+                catch {
+                    // another process beat us to cleanup — retry normally
+                }
+            }
+            // Lock held by a live process — spin-wait
+            const start = Date.now();
+            while (Date.now() - start < LOCK_RETRY_MS) {
+                // busy wait
+            }
+        }
+    }
+    return false;
+}
+function releaseLock() {
+    try {
+        fs.unlinkSync(LOCK_PATH);
+    }
+    catch {
+        // Lock already released or never acquired
+    }
+}
+function loadRateLimitState() {
+    if (fs.existsSync(constants_js_1.RATE_LIMIT_STATE_PATH)) {
+        try {
+            return JSON.parse(fs.readFileSync(constants_js_1.RATE_LIMIT_STATE_PATH, "utf-8"));
+        }
+        catch {
+            return {};
+        }
+    }
+    return {};
+}
+function saveRateLimitState(state) {
+    fs.writeFileSync(constants_js_1.RATE_LIMIT_STATE_PATH, JSON.stringify(state, null, 2));
+}
+function _checkRateLimitInner(userId, session, policy) {
+    const state = loadRateLimitState();
+    const now = Date.now();
+    // Per-user check
+    const userKey = `user:${userId}`;
+    const userState = state[userKey] || { calls: [] };
+    const userWindow = policy.rateLimits.perUser.windowSeconds * 1000;
+    userState.calls = userState.calls.filter((c) => now - c.timestamp < userWindow);
+    if (userState.calls.length >= policy.rateLimits.perUser.maxCalls) {
+        return {
+            allowed: false,
+            detail: `User ${userId} exceeded rate limit: ${policy.rateLimits.perUser.maxCalls} calls per ${policy.rateLimits.perUser.windowSeconds}s (current: ${userState.calls.length})`,
+        };
+    }
+    // Per-session check
+    if (session) {
+        const sessionKey = `session:${session}`;
+        const sessionState = state[sessionKey] || { calls: [] };
+        const sessionWindow = policy.rateLimits.perSession.windowSeconds * 1000;
+        sessionState.calls = sessionState.calls.filter((c) => now - c.timestamp < sessionWindow);
+        if (sessionState.calls.length >= policy.rateLimits.perSession.maxCalls) {
+            return {
+                allowed: false,
+                detail: `Session ${session} exceeded rate limit: ${policy.rateLimits.perSession.maxCalls} calls per ${policy.rateLimits.perSession.windowSeconds}s`,
+            };
+        }
+        sessionState.calls.push({ timestamp: now });
+        state[sessionKey] = sessionState;
+    }
+    userState.calls.push({ timestamp: now });
+    state[userKey] = userState;
+    saveRateLimitState(state);
+    return {
+        allowed: true,
+        detail: `Rate limit OK: ${userState.calls.length}/${policy.rateLimits.perUser.maxCalls} calls in window`,
+    };
+}
+function checkRateLimit(userId, session, policy) {
+    if (!acquireLock()) {
+        return {
+            allowed: false,
+            detail: "Rate limit state lock timeout — concurrent access. Try again.",
+        };
+    }
+    try {
+        return _checkRateLimitInner(userId, session, policy);
+    }
+    finally {
+        releaseLock();
+    }
+}

package/scripts/governance/scope.d.ts

@@ -0,0 +1,5 @@
+import type { Policy } from "./types.js";
+export declare function checkScope(tool: string, roles: string[], policy: Policy): {
+    allowed: boolean;
+    detail: string;
+};

package/scripts/governance/scope.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkScope = checkScope;
+function checkScope(tool, roles, policy) {
+    const toolPolicy = policy.allowedTools[tool];
+    // Deny-by-default: tool must be explicitly allowlisted
+    if (!toolPolicy) {
+        return {
+            allowed: false,
+            detail: `Tool "${tool}" is not in the allowlist. Deny-by-default policy enforced.`,
+        };
+    }
+    // If tool has role restrictions, check them
+    if (toolPolicy.roles && toolPolicy.roles.length > 0) {
+        const hasRole = roles.some((r) => toolPolicy.roles.includes(r));
+        if (!hasRole) {
+            return {
+                allowed: false,
+                detail: `Tool "${tool}" requires roles [${toolPolicy.roles.join(", ")}] but user has [${roles.join(", ")}]`,
+            };
+        }
+    }
+    return {
+        allowed: true,
+        detail: `Tool "${tool}" is allowlisted for roles [${roles.join(", ")}]`,
+    };
+}

package/scripts/governance/types.d.ts

@@ -0,0 +1,73 @@
+export interface Policy {
+    allowedTools: Record<string, {
+        roles?: string[];
+        maxArgsLength?: number;
+        description?: string;
+    }>;
+    rateLimits: {
+        perUser: {
+            maxCalls: number;
+            windowSeconds: number;
+        };
+        perSession: {
+            maxCalls: number;
+            windowSeconds: number;
+        };
+    };
+    identityMap: Record<string, {
+        userId: string;
+        roles: string[];
+    }>;
+    injectionDetection: {
+        enabled: boolean;
+        sensitivity: "low" | "medium" | "high";
+        customPatterns?: string[];
+    };
+    auditLog: {
+        path: string;
+        maxFileSizeMB: number;
+    };
+}
+export interface GovernanceRequest {
+    action: "check" | "log-result" | "self-test";
+    tool?: string;
+    args?: string;
+    user?: string;
+    channel?: string;
+    session?: string;
+    requestId?: string;
+    result?: string;
+    output?: string;
+}
+export interface GovernanceCheckResult {
+    allowed: boolean;
+    reason?: string;
+    requestId: string;
+    identity?: string;
+    roles?: string[];
+    patterns?: string[];
+}
+export interface AuditEntry {
+    timestamp: string;
+    requestId: string;
+    action: string;
+    tool?: string;
+    user?: string;
+    resolvedIdentity?: string;
+    roles?: string[];
+    channel?: string;
+    session?: string;
+    allowed?: boolean;
+    reason?: string;
+    checks?: Record<string, {
+        passed: boolean;
+        detail: string;
+    }>;
+    result?: string;
+    outputSummary?: string;
+}
+export interface RateLimitState {
+    calls: {
+        timestamp: number;
+    }[];
+}

package/scripts/governance/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/scripts/governance/utils.d.ts

@@ -0,0 +1 @@
+export declare function generateRequestId(): string;

package/scripts/governance/utils.js

@@ -0,0 +1,40 @@
+"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.generateRequestId = generateRequestId;
+const crypto = __importStar(require("crypto"));
+function generateRequestId() {
+    return `gov-${Date.now()}-${crypto.randomBytes(4).toString("hex")}`;
+}

package/scripts/governance/validate-policy.d.ts

@@ -0,0 +1,6 @@
+export interface PolicyValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+export declare function validatePolicy(policy: unknown): PolicyValidationResult;

package/scripts/governance/validate-policy.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validatePolicy = validatePolicy;
+function validatePolicy(policy) {
+    const errors = [];
+    const warnings = [];
+    if (typeof policy !== "object" || policy === null) {
+        return { valid: false, errors: ["Policy must be a non-null object"], warnings };
+    }
+    const p = policy;
+    // --- Required top-level fields ---
+    if (!p.allowedTools || typeof p.allowedTools !== "object") {
+        errors.push("Missing or invalid 'allowedTools' (must be an object)");
+    }
+    if (!p.rateLimits || typeof p.rateLimits !== "object") {
+        errors.push("Missing or invalid 'rateLimits' (must be an object)");
+    }
+    else {
+        const rl = p.rateLimits;
+        for (const key of ["perUser", "perSession"]) {
+            if (!rl[key] || typeof rl[key] !== "object") {
+                errors.push(`Missing or invalid 'rateLimits.${key}' (must be an object)`);
+            }
+            else {
+                const bucket = rl[key];
+                if (typeof bucket.maxCalls !== "number" || bucket.maxCalls < 0) {
+                    errors.push(`'rateLimits.${key}.maxCalls' must be a non-negative number`);
+                }
+                if (typeof bucket.windowSeconds !== "number" || bucket.windowSeconds < 0) {
+                    errors.push(`'rateLimits.${key}.windowSeconds' must be a non-negative number`);
+                }
+            }
+        }
+    }
+    if (!p.identityMap || typeof p.identityMap !== "object") {
+        errors.push("Missing or invalid 'identityMap' (must be an object)");
+    }
+    if (!p.injectionDetection || typeof p.injectionDetection !== "object") {
+        errors.push("Missing or invalid 'injectionDetection' (must be an object)");
+    }
+    else {
+        const id = p.injectionDetection;
+        if (typeof id.enabled !== "boolean") {
+            errors.push("'injectionDetection.enabled' must be a boolean");
+        }
+        if (!["low", "medium", "high"].includes(id.sensitivity)) {
+            errors.push("'injectionDetection.sensitivity' must be 'low', 'medium', or 'high'");
+        }
+        // Validate custom patterns
+        if (id.customPatterns !== undefined) {
+            if (!Array.isArray(id.customPatterns)) {
+                errors.push("'injectionDetection.customPatterns' must be an array");
+            }
+            else {
+                for (let i = 0; i < id.customPatterns.length; i++) {
+                    const pat = id.customPatterns[i];
+                    if (typeof pat !== "string") {
+                        warnings.push(`customPatterns[${i}] is not a string`);
+                        continue;
+                    }
+                    try {
+                        new RegExp(pat);
+                    }
+                    catch {
+                        warnings.push(`customPatterns[${i}] is not a valid regex: "${pat}"`);
+                    }
+                }
+            }
+        }
+    }
+    if (!p.auditLog || typeof p.auditLog !== "object") {
+        errors.push("Missing or invalid 'auditLog' (must be an object)");
+    }
+    // --- Warnings (non-fatal) ---
+    // Empty collections
+    if (p.allowedTools && typeof p.allowedTools === "object" && Object.keys(p.allowedTools).length === 0) {
+        warnings.push("'allowedTools' is empty — all tools will be denied");
+    }
+    if (p.identityMap && typeof p.identityMap === "object" && Object.keys(p.identityMap).length === 0) {
+        warnings.push("'identityMap' is empty — all users will be denied");
+    }
+    // Cross-reference: roles referenced by tools but not assigned to any identity
+    if (p.allowedTools && typeof p.allowedTools === "object" &&
+        p.identityMap && typeof p.identityMap === "object") {
+        const allIdentityRoles = new Set();
+        for (const entry of Object.values(p.identityMap)) {
+            if (entry && typeof entry === "object" && Array.isArray(entry.roles)) {
+                for (const r of entry.roles) {
+                    allIdentityRoles.add(r);
+                }
+            }
+        }
+        for (const [toolName, toolConfig] of Object.entries(p.allowedTools)) {
+            if (toolConfig && typeof toolConfig === "object" && Array.isArray(toolConfig.roles)) {
+                for (const role of toolConfig.roles) {
+                    if (!allIdentityRoles.has(role)) {
+                        warnings.push(`Tool "${toolName}" requires role "${role}" but no identity has it`);
+                    }
+                }
+            }
+        }
+    }
+    return { valid: errors.length === 0, errors, warnings };
+}

package/scripts/governance-gateway.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * GatewayStack Governance Gateway for OpenClaw
+ *
+ * Barrel module — re-exports the public API and serves as the CLI entry point.
+ * Implementation lives in ./governance/*.ts modules.
+ */
+export type { Policy, GovernanceCheckResult } from "./governance/types.js";
+export { loadPolicy } from "./governance/policy.js";
+export { validatePolicy } from "./governance/validate-policy.js";
+export { checkGovernance } from "./governance/check.js";

package/scripts/governance-gateway.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * GatewayStack Governance Gateway for OpenClaw
+ *
+ * Barrel module — re-exports the public API and serves as the CLI entry point.
+ * Implementation lives in ./governance/*.ts modules.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkGovernance = exports.validatePolicy = exports.loadPolicy = void 0;
+var policy_js_1 = require("./governance/policy.js");
+Object.defineProperty(exports, "loadPolicy", { enumerable: true, get: function () { return policy_js_1.loadPolicy; } });
+var validate_policy_js_1 = require("./governance/validate-policy.js");
+Object.defineProperty(exports, "validatePolicy", { enumerable: true, get: function () { return validate_policy_js_1.validatePolicy; } });
+var check_js_1 = require("./governance/check.js");
+Object.defineProperty(exports, "checkGovernance", { enumerable: true, get: function () { return check_js_1.checkGovernance; } });
+// CLI entry point
+const cli_js_1 = require("./governance/cli.js");
+const isDirectExecution = require.main === module ||
+    process.argv[1]?.endsWith("governance-gateway.js");
+if (isDirectExecution) {
+    (0, cli_js_1.runGovernanceCheck)((0, cli_js_1.parseArgs)(process.argv));
+}

package/scripts/governance-gateway.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * GatewayStack Governance Gateway for OpenClaw
+ *
+ * Barrel module — re-exports the public API and serves as the CLI entry point.
+ * Implementation lives in ./governance/*.ts modules.
+ */
+
+// Re-export public API
+export type { Policy, GovernanceCheckResult } from "./governance/types.js";
+export { loadPolicy } from "./governance/policy.js";
+export { validatePolicy } from "./governance/validate-policy.js";
+export { checkGovernance } from "./governance/check.js";
+
+// CLI entry point
+import { parseArgs, runGovernanceCheck } from "./governance/cli.js";
+
+const isDirectExecution =
+  require.main === module ||
+  process.argv[1]?.endsWith("governance-gateway.js");
+
+if (isDirectExecution) {
+  runGovernanceCheck(parseArgs(process.argv));
+}

package/src/plugin.d.ts

@@ -0,0 +1,17 @@
+/**
+ * GatewayStack Governance — OpenClaw Plugin
+ *
+ * Registers a `before_tool_call` hook that automatically runs governance
+ * checks on every tool invocation. The agent cannot bypass this — it runs
+ * at the process level before any tool executes.
+ *
+ * Identity mapping uses OpenClaw agent IDs (e.g. "main", "ops", "dev")
+ * rather than human users, since OpenClaw is a single-user personal AI.
+ */
+declare const plugin: {
+    id: string;
+    name: string;
+    description: string;
+    register(api: any): void;
+};
+export default plugin;

package/src/plugin.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * GatewayStack Governance — OpenClaw Plugin
+ *
+ * Registers a `before_tool_call` hook that automatically runs governance
+ * checks on every tool invocation. The agent cannot bypass this — it runs
+ * at the process level before any tool executes.
+ *
+ * Identity mapping uses OpenClaw agent IDs (e.g. "main", "ops", "dev")
+ * rather than human users, since OpenClaw is a single-user personal AI.
+ */
+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 });
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const governance_gateway_js_1 = require("../scripts/governance-gateway.js");
+// Resolve policy path: check plugin directory first, then ~/.openclaw default
+function resolvePolicyPath() {
+    const pluginDir = path.resolve(__dirname, "..");
+    const localPolicy = path.join(pluginDir, "policy.json");
+    // Also check OpenClaw skills directory (for backward compat with skill installs)
+    const openclawSkillPolicy = path.join(os.homedir(), ".openclaw", "skills", "gatewaystack-governance", "policy.json");
+    // Prefer local plugin directory policy
+    try {
+        require("fs").accessSync(localPolicy);
+        return localPolicy;
+    }
+    catch {
+        // Fall through
+    }
+    // Try OpenClaw skills directory
+    try {
+        require("fs").accessSync(openclawSkillPolicy);
+        return openclawSkillPolicy;
+    }
+    catch {
+        // Fall through
+    }
+    // Default to local — will produce a clear error from checkGovernance
+    return localPolicy;
+}
+const plugin = {
+    id: "gatewaystack-governance",
+    name: "GatewayStack Governance",
+    description: "Automatic governance for every tool call — identity, scope, rate limiting, injection detection, and audit logging",
+    register(api) {
+        const policyPath = resolvePolicyPath();
+        api.on("before_tool_call", async (event, ctx) => {
+            const result = await (0, governance_gateway_js_1.checkGovernance)({
+                toolName: event.toolName,
+                args: JSON.stringify(event.params),
+                userId: ctx.agentId ?? "unknown",
+                session: ctx.sessionKey,
+                policyPath,
+            });
+            if (!result.allowed) {
+                return { block: true, blockReason: result.reason };
+            }
+            return {};
+        }, { priority: 0 });
+        if (api.logger) {
+            api.logger.info(`GatewayStack Governance loaded (policy: ${policyPath})`);
+        }
+    },
+};
+exports.default = plugin;