@fulcrum-governance/sdk 0.1.1 → 0.1.3

package/dist/instrumentation/autoGovern.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Auto-governance activation for TypeScript/Node.js.
+ *
+ * This module provides the main entry point for activating Fulcrum governance.
+ * It patches Node.js builtins and framework decorators at runtime.
+ */
+import type { InstrumentationConfig, Decision, Metrics } from './types';
+import { PolicyEvaluator } from './evaluator';
+/**
+ * Activate Fulcrum governance for TypeScript/Node.js.
+ *
+ * This function should be called BEFORE importing frameworks that use
+ * tools. It patches builtins and library exports.
+ *
+ * @example
+ * ```typescript
+ * import { activate } from 'fulcrum/instrumentation';
+ * activate({ apiKey: 'flk_...', tenantId: 'my-tenant' });
+ *
+ * // Now import frameworks - they will be governed
+ * import fetch from 'node-fetch';
+ * ```
+ */
+export declare function activate(userConfig?: InstrumentationConfig): void;
+/**
+ * Deactivate Fulcrum governance.
+ *
+ * This stops the policy evaluator and removes patches where possible.
+ * Note: Some patches cannot be fully reverted.
+ */
+export declare function deactivate(): void;
+/**
+ * Check if Fulcrum governance is currently active.
+ */
+export declare function isActive(): boolean;
+/**
+ * Get the active policy evaluator (for internal use by patches).
+ */
+export declare function getEvaluator(): PolicyEvaluator | null;
+/**
+ * Get the active configuration (for internal use by patches).
+ */
+export declare function getConfig(): Required<InstrumentationConfig> | null;
+/**
+ * Record a metric value (for internal use by patches).
+ */
+export declare function recordMetric(metric: keyof Metrics, increment?: number): void;
+/**
+ * Get current metrics counters.
+ */
+export declare function getMetrics(): Metrics;
+/**
+ * Evaluate a tool call against policies.
+ *
+ * This is the main entry point for patches to check governance.
+ */
+export declare function evaluateCall(toolName: string, actionType: string, resource?: string, toolArgs?: Record<string, unknown>, metadata?: Record<string, unknown>): Decision;

package/dist/instrumentation/autoGovern.js

@@ -0,0 +1,319 @@
+"use strict";
+/**
+ * Auto-governance activation for TypeScript/Node.js.
+ *
+ * This module provides the main entry point for activating Fulcrum governance.
+ * It patches Node.js builtins and framework decorators at runtime.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.activate = activate;
+exports.deactivate = deactivate;
+exports.isActive = isActive;
+exports.getEvaluator = getEvaluator;
+exports.getConfig = getConfig;
+exports.recordMetric = recordMetric;
+exports.getMetrics = getMetrics;
+exports.evaluateCall = evaluateCall;
+const types_1 = require("./types");
+const evaluator_1 = require("./evaluator");
+// Global state
+let evaluator = null;
+let config = null;
+let active = false;
+const metrics = {
+    governedCalls: 0,
+    ungovernedCalls: 0,
+    deniedCalls: 0,
+    allowedCalls: 0,
+    patchFailures: 0,
+};
+/**
+ * Activate Fulcrum governance for TypeScript/Node.js.
+ *
+ * This function should be called BEFORE importing frameworks that use
+ * tools. It patches builtins and library exports.
+ *
+ * @example
+ * ```typescript
+ * import { activate } from 'fulcrum/instrumentation';
+ * activate({ apiKey: 'flk_...', tenantId: 'my-tenant' });
+ *
+ * // Now import frameworks - they will be governed
+ * import fetch from 'node-fetch';
+ * ```
+ */
+function activate(userConfig = {}) {
+    if (active) {
+        console.warn('[fulcrum] Governance already active');
+        return;
+    }
+    // Create configuration
+    config = { ...types_1.DEFAULT_CONFIG, ...userConfig };
+    // Log validation warnings
+    if (!config.apiKey) {
+        console.warn('[fulcrum] api_key not set - operating in offline mode');
+    }
+    if (!config.tenantId) {
+        console.warn('[fulcrum] tenant_id not set - required for policy evaluation');
+    }
+    // Create and start evaluator
+    evaluator = new evaluator_1.PolicyEvaluator(config);
+    evaluator.start();
+    // Apply patches
+    applyPatches();
+    active = true;
+    console.info(`[fulcrum] Governance activated (patches: ${[...config.enabledPatches].join(', ')})`);
+}
+/**
+ * Deactivate Fulcrum governance.
+ *
+ * This stops the policy evaluator and removes patches where possible.
+ * Note: Some patches cannot be fully reverted.
+ */
+function deactivate() {
+    if (!active)
+        return;
+    // Stop evaluator
+    if (evaluator) {
+        evaluator.stop();
+        evaluator = null;
+    }
+    // Restore originals
+    restoreOriginals();
+    active = false;
+    config = null;
+    console.info('[fulcrum] Governance deactivated');
+}
+/**
+ * Check if Fulcrum governance is currently active.
+ */
+function isActive() {
+    return active;
+}
+/**
+ * Get the active policy evaluator (for internal use by patches).
+ */
+function getEvaluator() {
+    return evaluator;
+}
+/**
+ * Get the active configuration (for internal use by patches).
+ */
+function getConfig() {
+    return config;
+}
+/**
+ * Record a metric value (for internal use by patches).
+ */
+function recordMetric(metric, increment = 1) {
+    metrics[metric] += increment;
+}
+/**
+ * Get current metrics counters.
+ */
+function getMetrics() {
+    return { ...metrics };
+}
+/**
+ * Evaluate a tool call against policies.
+ *
+ * This is the main entry point for patches to check governance.
+ */
+function evaluateCall(toolName, actionType, resource, toolArgs = {}, metadata) {
+    if (!evaluator) {
+        recordMetric('ungovernedCalls');
+        return {
+            action: 'allow',
+            reason: 'Evaluator not initialized',
+        };
+    }
+    const request = {
+        toolName,
+        actionType,
+        resource,
+        toolArgs,
+        metadata,
+    };
+    const decision = evaluator.evaluate(request);
+    // Record metrics
+    recordMetric('governedCalls');
+    if (decision.action === 'allow') {
+        recordMetric('allowedCalls');
+    }
+    else if (decision.action === 'deny') {
+        recordMetric('deniedCalls');
+    }
+    return decision;
+}
+// Store original functions for restoration
+const originals = new Map();
+function applyPatches() {
+    if (!config)
+        return;
+    // Patch global fetch if enabled
+    if (config.enabledPatches.has('fetch') && typeof globalThis.fetch === 'function') {
+        patchFetch();
+    }
+    // Patch fs module if enabled
+    if (config.enabledPatches.has('fs')) {
+        patchFs();
+    }
+    // Patch child_process if enabled
+    if (config.enabledPatches.has('childProcess')) {
+        patchChildProcess();
+    }
+}
+function patchFetch() {
+    try {
+        const originalFetch = globalThis.fetch;
+        originals.set('fetch', originalFetch);
+        globalThis.fetch = async function governedFetch(input, init) {
+            const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+            const method = init?.method || 'GET';
+            const decision = evaluateCall('fetch', 'http_request', url, { method, url }, { headers: init?.headers });
+            if (decision.action === 'deny') {
+                throw new Error(`HTTP request to '${url}' blocked by Fulcrum policy: ${decision.reason}`);
+            }
+            return originalFetch(input, init);
+        };
+        console.debug('[fulcrum] Patched global fetch');
+    }
+    catch (err) {
+        console.warn(`[fulcrum] Failed to patch fetch: ${err instanceof Error ? err.message : err}`);
+        recordMetric('patchFailures');
+    }
+}
+function patchFs() {
+    try {
+        // Dynamic import to avoid issues if fs is not available
+        const fs = require('fs');
+        const originalReadFile = fs.readFile;
+        const originalWriteFile = fs.writeFile;
+        const originalReadFileSync = fs.readFileSync;
+        const originalWriteFileSync = fs.writeFileSync;
+        originals.set('fs.readFile', originalReadFile);
+        originals.set('fs.writeFile', originalWriteFile);
+        originals.set('fs.readFileSync', originalReadFileSync);
+        originals.set('fs.writeFileSync', originalWriteFileSync);
+        fs.readFile = function governedReadFile(path, ...args) {
+            const decision = evaluateCall('fs.readFile', 'file_read', String(path), { path });
+            if (decision.action === 'deny') {
+                const callback = args[args.length - 1];
+                if (typeof callback === 'function') {
+                    callback(new Error(`File read '${path}' blocked by Fulcrum policy: ${decision.reason}`));
+                    return;
+                }
+                throw new Error(`File read '${path}' blocked by Fulcrum policy: ${decision.reason}`);
+            }
+            return originalReadFile(path, ...args);
+        };
+        fs.writeFile = function governedWriteFile(path, data, ...args) {
+            const decision = evaluateCall('fs.writeFile', 'file_write', String(path), { path });
+            if (decision.action === 'deny') {
+                const callback = args[args.length - 1];
+                if (typeof callback === 'function') {
+                    callback(new Error(`File write '${path}' blocked by Fulcrum policy: ${decision.reason}`));
+                    return;
+                }
+                throw new Error(`File write '${path}' blocked by Fulcrum policy: ${decision.reason}`);
+            }
+            return originalWriteFile(path, data, ...args);
+        };
+        fs.readFileSync = function governedReadFileSync(path, options) {
+            const decision = evaluateCall('fs.readFileSync', 'file_read', String(path), { path });
+            if (decision.action === 'deny') {
+                throw new Error(`File read '${path}' blocked by Fulcrum policy: ${decision.reason}`);
+            }
+            return originalReadFileSync(path, options);
+        };
+        fs.writeFileSync = function governedWriteFileSync(path, data, options) {
+            const decision = evaluateCall('fs.writeFileSync', 'file_write', String(path), { path });
+            if (decision.action === 'deny') {
+                throw new Error(`File write '${path}' blocked by Fulcrum policy: ${decision.reason}`);
+            }
+            return originalWriteFileSync(path, data, options);
+        };
+        console.debug('[fulcrum] Patched fs module');
+    }
+    catch (err) {
+        console.warn(`[fulcrum] Failed to patch fs: ${err instanceof Error ? err.message : err}`);
+        recordMetric('patchFailures');
+    }
+}
+function patchChildProcess() {
+    try {
+        const childProcess = require('child_process');
+        const originalSpawn = childProcess.spawn;
+        const originalExec = childProcess.exec;
+        const originalExecSync = childProcess.execSync;
+        originals.set('child_process.spawn', originalSpawn);
+        originals.set('child_process.exec', originalExec);
+        originals.set('child_process.execSync', originalExecSync);
+        childProcess.spawn = function governedSpawn(command, args, options) {
+            const decision = evaluateCall('child_process.spawn', 'shell_execute', command, { command, args });
+            if (decision.action === 'deny') {
+                throw new Error(`Command '${command}' blocked by Fulcrum policy: ${decision.reason}`);
+            }
+            return originalSpawn(command, args, options);
+        };
+        childProcess.exec = function governedExec(command, ...args) {
+            const decision = evaluateCall('child_process.exec', 'shell_execute', command, { command });
+            if (decision.action === 'deny') {
+                const callback = args[args.length - 1];
+                if (typeof callback === 'function') {
+                    callback(new Error(`Command '${command}' blocked by Fulcrum policy: ${decision.reason}`));
+                    return;
+                }
+                throw new Error(`Command '${command}' blocked by Fulcrum policy: ${decision.reason}`);
+            }
+            return originalExec(command, ...args);
+        };
+        childProcess.execSync = function governedExecSync(command, options) {
+            const decision = evaluateCall('child_process.execSync', 'shell_execute', command, { command });
+            if (decision.action === 'deny') {
+                throw new Error(`Command '${command}' blocked by Fulcrum policy: ${decision.reason}`);
+            }
+            return originalExecSync(command, options);
+        };
+        console.debug('[fulcrum] Patched child_process module');
+    }
+    catch (err) {
+        console.warn(`[fulcrum] Failed to patch child_process: ${err instanceof Error ? err.message : err}`);
+        recordMetric('patchFailures');
+    }
+}
+function restoreOriginals() {
+    // Restore fetch
+    if (originals.has('fetch')) {
+        globalThis.fetch = originals.get('fetch');
+    }
+    // Restore fs
+    try {
+        const fs = require('fs');
+        if (originals.has('fs.readFile'))
+            fs.readFile = originals.get('fs.readFile');
+        if (originals.has('fs.writeFile'))
+            fs.writeFile = originals.get('fs.writeFile');
+        if (originals.has('fs.readFileSync'))
+            fs.readFileSync = originals.get('fs.readFileSync');
+        if (originals.has('fs.writeFileSync'))
+            fs.writeFileSync = originals.get('fs.writeFileSync');
+    }
+    catch {
+        // fs not available
+    }
+    // Restore child_process
+    try {
+        const childProcess = require('child_process');
+        if (originals.has('child_process.spawn'))
+            childProcess.spawn = originals.get('child_process.spawn');
+        if (originals.has('child_process.exec'))
+            childProcess.exec = originals.get('child_process.exec');
+        if (originals.has('child_process.execSync'))
+            childProcess.execSync = originals.get('child_process.execSync');
+    }
+    catch {
+        // child_process not available
+    }
+    originals.clear();
+}

package/dist/instrumentation/evaluator.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Policy evaluator for SDK instrumentation.
+ *
+ * This module provides a lightweight policy evaluation client that:
+ * 1. Caches policies locally for fast evaluation
+ * 2. Syncs with fulcrum-server periodically
+ * 3. Fails open (allow) on errors to avoid crashing agents
+ */
+import type { InstrumentationConfig, Decision, EvaluationRequest, Policy } from './types';
+/**
+ * Lightweight policy evaluator for SDK use.
+ */
+export declare class PolicyEvaluator {
+    private config;
+    private policies;
+    private lastSync;
+    private syncError;
+    private syncInterval;
+    private running;
+    constructor(config?: InstrumentationConfig);
+    /**
+     * Start the background policy sync.
+     */
+    start(): void;
+    /**
+     * Stop the background policy sync.
+     */
+    stop(): void;
+    /**
+     * Evaluate a request against cached policies.
+     *
+     * This method is designed to be fast (<1ms) and fail-safe.
+     * On any error, it returns ALLOW with a warning.
+     */
+    evaluate(request: EvaluationRequest): Decision;
+    private evaluateInternal;
+    private policyApplies;
+    private ruleMatches;
+    private conditionMatches;
+    private getFieldValue;
+    private getRuleAction;
+    private syncPolicies;
+    /**
+     * Manually update the policy cache (for testing).
+     */
+    updatePolicies(policies: Policy[]): void;
+    get policyCount(): number;
+    get lastSyncTime(): number;
+    get syncErrorMessage(): string | null;
+}

package/dist/instrumentation/evaluator.js

@@ -0,0 +1,218 @@
+"use strict";
+/**
+ * Policy evaluator for SDK instrumentation.
+ *
+ * This module provides a lightweight policy evaluation client that:
+ * 1. Caches policies locally for fast evaluation
+ * 2. Syncs with fulcrum-server periodically
+ * 3. Fails open (allow) on errors to avoid crashing agents
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PolicyEvaluator = void 0;
+const types_1 = require("./types");
+/**
+ * Lightweight policy evaluator for SDK use.
+ */
+class PolicyEvaluator {
+    constructor(config = {}) {
+        this.policies = [];
+        this.lastSync = 0;
+        this.syncError = null;
+        this.syncInterval = null;
+        this.running = false;
+        this.config = { ...types_1.DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Start the background policy sync.
+     */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        // Initial sync
+        this.syncPolicies().catch((err) => {
+            console.warn('[fulcrum] Initial policy sync failed:', err.message);
+        });
+        // Periodic sync
+        this.syncInterval = setInterval(() => this.syncPolicies().catch(() => { }), this.config.policySyncInterval * 1000);
+        console.info('[fulcrum] Policy evaluator started');
+    }
+    /**
+     * Stop the background policy sync.
+     */
+    stop() {
+        if (!this.running)
+            return;
+        this.running = false;
+        if (this.syncInterval) {
+            clearInterval(this.syncInterval);
+            this.syncInterval = null;
+        }
+        console.info('[fulcrum] Policy evaluator stopped');
+    }
+    /**
+     * Evaluate a request against cached policies.
+     *
+     * This method is designed to be fast (<1ms) and fail-safe.
+     * On any error, it returns ALLOW with a warning.
+     */
+    evaluate(request) {
+        try {
+            return this.evaluateInternal(request);
+        }
+        catch (err) {
+            console.warn(`[fulcrum] Policy evaluation error (failing open): ${err instanceof Error ? err.message : err}`);
+            return {
+                action: 'allow',
+                reason: `Evaluation error (fail-open): ${err instanceof Error ? err.message : err}`,
+            };
+        }
+    }
+    evaluateInternal(request) {
+        if (this.policies.length === 0) {
+            return {
+                action: 'allow',
+                reason: 'No policies loaded',
+            };
+        }
+        // Evaluate policies in priority order
+        for (const policy of this.policies) {
+            if (policy.status !== 'active')
+                continue;
+            if (!this.policyApplies(policy, request))
+                continue;
+            for (const rule of policy.rules) {
+                if (!rule.enabled)
+                    continue;
+                if (this.ruleMatches(rule, request)) {
+                    const action = this.getRuleAction(rule);
+                    return {
+                        action,
+                        reason: rule.name || 'Matched rule',
+                        matchedPolicyId: policy.policyId,
+                        matchedRuleId: rule.ruleId,
+                    };
+                }
+            }
+        }
+        return {
+            action: 'allow',
+            reason: 'No rules matched',
+        };
+    }
+    policyApplies(policy, request) {
+        const scope = policy.scope;
+        if (!scope)
+            return true;
+        if (scope.applyToAll)
+            return true;
+        if (scope.toolNames && scope.toolNames.length > 0) {
+            if (!scope.toolNames.includes(request.toolName)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    ruleMatches(rule, request) {
+        if (rule.conditions.length === 0)
+            return true;
+        // All conditions must match (implicit AND)
+        return rule.conditions.every((condition) => this.conditionMatches(condition, request));
+    }
+    conditionMatches(condition, request) {
+        const fieldValue = this.getFieldValue(condition.field, request);
+        if (fieldValue === undefined)
+            return false;
+        const value = condition.value || '';
+        const values = condition.values || [];
+        switch (condition.operator) {
+            case 'equals':
+                return String(fieldValue) === value;
+            case 'not_equals':
+                return String(fieldValue) !== value;
+            case 'contains':
+                return String(fieldValue).includes(value);
+            case 'starts_with':
+                return String(fieldValue).startsWith(value);
+            case 'ends_with':
+                return String(fieldValue).endsWith(value);
+            case 'in':
+                return values.includes(String(fieldValue));
+            case 'not_in':
+                return !values.includes(String(fieldValue));
+            case 'matches':
+                try {
+                    return new RegExp(value).test(String(fieldValue));
+                }
+                catch {
+                    return false;
+                }
+            default:
+                console.warn(`[fulcrum] Unknown operator: ${condition.operator}`);
+                return false;
+        }
+    }
+    getFieldValue(field, request) {
+        if (field === 'tool_name')
+            return request.toolName;
+        if (field === 'action_type')
+            return request.actionType;
+        if (field === 'resource')
+            return request.resource;
+        if (field.startsWith('args.')) {
+            const argName = field.slice(5);
+            return request.toolArgs[argName];
+        }
+        if (field.startsWith('metadata.')) {
+            const metaName = field.slice(9);
+            return request.metadata?.[metaName];
+        }
+        return undefined;
+    }
+    getRuleAction(rule) {
+        if (rule.actions.length === 0)
+            return 'allow';
+        const actionType = rule.actions[0].actionType;
+        const actionMap = {
+            allow: 'allow',
+            deny: 'deny',
+            warn: 'warn',
+            escalate: 'escalate',
+            require_approval: 'require_approval',
+        };
+        return actionMap[actionType] || 'allow';
+    }
+    async syncPolicies() {
+        if (!this.config.apiKey || !this.config.tenantId) {
+            return;
+        }
+        // TODO: Implement actual HTTP/gRPC call to fulcrum-server
+        // For now, this is a no-op placeholder
+        //
+        // Example implementation:
+        // const response = await fetch(`${this.config.serverUrl}/api/v1/policies`, {
+        //   headers: { Authorization: `Bearer ${this.config.apiKey}` },
+        // });
+        // const data = await response.json();
+        // this.policies = data.policies;
+        this.lastSync = Date.now();
+        this.syncError = null;
+    }
+    /**
+     * Manually update the policy cache (for testing).
+     */
+    updatePolicies(policies) {
+        this.policies = [...policies];
+        this.lastSync = Date.now();
+    }
+    get policyCount() {
+        return this.policies.length;
+    }
+    get lastSyncTime() {
+        return this.lastSync;
+    }
+    get syncErrorMessage() {
+        return this.syncError;
+    }
+}
+exports.PolicyEvaluator = PolicyEvaluator;

package/dist/instrumentation/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Fulcrum Auto-Instrumentation for TypeScript/Node.js.
+ *
+ * This module provides zero-code-change governance for AI agent tool calls.
+ * It patches Node.js builtins and framework decorators at runtime.
+ *
+ * @example
+ * ```typescript
+ * // IMPORTANT: activate BEFORE importing frameworks
+ * import { activate } from 'fulcrum/instrumentation';
+ * activate({ apiKey: 'flk_...', tenantId: 'tenant-123' });
+ *
+ * // Now import your frameworks - they will be automatically governed
+ * import { tool } from '@langchain/core/tools';
+ * import fetch from 'node-fetch';
+ * ```
+ *
+ * The instrumentation patches:
+ * - global fetch (file access)
+ * - node:fs (file operations)
+ * - child_process (shell commands)
+ * - node-fetch, axios (HTTP clients)
+ *
+ * All patches are fail-safe: governance errors never crash your agent.
+ */
+export { activate, deactivate, isActive } from './autoGovern';
+export { PolicyEvaluator } from './evaluator';
+export type { InstrumentationConfig, Decision, EvaluationRequest, Action } from './types';