@siduri-x/core 1.0.5 → 1.0.8

package/dist/action-executor.d.ts

@@ -0,0 +1,12 @@
+import { ActionIntent, ActionExecutionResult, ActionPolicyEngine, HandsOrgan, RequestContext } from './index';
+export interface ActionExecutionParams {
+    actionIntents?: ActionIntent[];
+    requestContext: RequestContext;
+    actionPolicy: ActionPolicyEngine;
+    hands?: HandsOrgan;
+}
+/**
+ * Executes proposed actions under the primary security invariant:
+ * "Brain proposes; the policy layer authorizes; Hands executes; the audit layer records."
+ */
+export declare function executeActionIntents(params: ActionExecutionParams): Promise<ActionExecutionResult[]>;

package/dist/action-executor.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeActionIntents = executeActionIntents;
+/**
+ * Executes proposed actions under the primary security invariant:
+ * "Brain proposes; the policy layer authorizes; Hands executes; the audit layer records."
+ */
+async function executeActionIntents(params) {
+    const { actionIntents, requestContext, actionPolicy, hands } = params;
+    const actionResults = [];
+    if (!hands ||
+        !actionIntents ||
+        actionIntents.length === 0 ||
+        typeof hands.executeAction !== 'function') {
+        return actionResults;
+    }
+    for (const rawAction of actionIntents) {
+        // 1. Context Propagation: Attach request provenance to ActionIntent
+        const actionWithContext = {
+            ...rawAction,
+            context: requestContext,
+            executionId: rawAction.executionId ||
+                `exec-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+        };
+        // 2. Action Policy Authorization Boundary Check
+        const { decision, capability } = await actionPolicy.evaluateAction(actionWithContext, requestContext);
+        if (!decision.allowed || !capability) {
+            // Action was rejected by policy
+            actionResults.push({
+                actionId: actionWithContext.actionId,
+                executionId: decision.executionId,
+                toolName: actionWithContext.toolName,
+                lifecycle: 'REJECTED',
+                success: false,
+                error: `Action authorization rejected by policy: ${decision.reason}`,
+                decision,
+            });
+            continue;
+        }
+        // 3. Hands Execution (only authorized actions execute with AuthorizationCapability)
+        const res = await hands.executeAction(actionWithContext, capability);
+        actionResults.push({
+            ...res,
+            decision,
+        });
+        // 4. Audit recording for execution outcome
+        await actionPolicy.recordAudit(actionWithContext, requestContext, decision, res.lifecycle, res.result, res.error, res.durationMs);
+    }
+    return actionResults;
+}

package/dist/action-policy.d.ts

@@ -0,0 +1,45 @@
+import { RequestContext } from './context';
+import { ActionIntent, ActionPolicyDecision, ActionAuditEvent, ToolDefinition, ActionRiskLevel, ActionLifecycleState } from './action';
+import { AuthorizationCapability, ActionStore } from './capability';
+export interface ActionPolicyRule {
+    toolNamePattern: string | RegExp;
+    riskLevel?: ActionRiskLevel;
+    requiredCapabilities?: string[];
+    allowedRoles?: string[];
+    allowedChannels?: string[];
+    requiresExplicitApproval?: boolean;
+}
+export interface ActionPolicyEngineOptions {
+    rules?: ActionPolicyRule[];
+    defaultRiskLevel?: ActionRiskLevel;
+    defaultRequireApprovalForHighRisk?: boolean;
+    store?: ActionStore;
+    secretKey?: string;
+}
+export interface ApproveActionOptions {
+    executionId: string;
+    approverActorId: string;
+    reason?: string;
+}
+export declare class ActionPolicyEngine {
+    private readonly toolRegistry;
+    private readonly rules;
+    private readonly store;
+    private readonly defaultRiskLevel;
+    private readonly defaultRequireApprovalForHighRisk;
+    private readonly secretKey;
+    private readonly approvedExecutions;
+    constructor(options?: ActionPolicyEngineOptions);
+    registerToolDefinition(tool: ToolDefinition): void;
+    unregisterToolDefinition(toolName: string): boolean;
+    getRegisteredTools(): ToolDefinition[];
+    findToolDefinition(toolName: string): ToolDefinition | undefined;
+    evaluateAction(action: ActionIntent, context?: RequestContext): Promise<{
+        decision: ActionPolicyDecision;
+        capability?: AuthorizationCapability;
+    }>;
+    approveAction(options: ApproveActionOptions): Promise<boolean>;
+    recordAudit(action: ActionIntent, context: RequestContext | undefined, decision: ActionPolicyDecision | undefined, lifecycle: ActionLifecycleState, result?: unknown, error?: string, durationMs?: number): Promise<ActionAuditEvent>;
+    getAuditLog(): Promise<ActionAuditEvent[]>;
+    getStore(): ActionStore;
+}

package/dist/action-policy.js

@@ -0,0 +1,219 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActionPolicyEngine = void 0;
+const capability_1 = require("./capability");
+class ActionPolicyEngine {
+    toolRegistry = new Map();
+    rules = [];
+    store;
+    defaultRiskLevel;
+    defaultRequireApprovalForHighRisk;
+    secretKey;
+    approvedExecutions = new Set();
+    constructor(options = {}) {
+        this.rules = options.rules ?? [];
+        this.defaultRiskLevel = options.defaultRiskLevel ?? 'HIGH';
+        this.defaultRequireApprovalForHighRisk = options.defaultRequireApprovalForHighRisk ?? true;
+        this.store = options.store ?? new capability_1.InMemoryActionStore();
+        this.secretKey = (0, capability_1.getOrGenerateLocalActionPolicySecret)(options.secretKey);
+    }
+    registerToolDefinition(tool) {
+        const key = tool.providerId ? `${tool.providerId}/${tool.name}` : tool.name;
+        this.toolRegistry.set(key, tool);
+        // Also index by bare name if unique
+        if (!this.toolRegistry.has(tool.name)) {
+            this.toolRegistry.set(tool.name, tool);
+        }
+    }
+    unregisterToolDefinition(toolName) {
+        return this.toolRegistry.delete(toolName);
+    }
+    getRegisteredTools() {
+        const set = new Set(this.toolRegistry.values());
+        return Array.from(set);
+    }
+    findToolDefinition(toolName) {
+        return this.toolRegistry.get(toolName);
+    }
+    async evaluateAction(action, context) {
+        const effectiveContext = action.context || context;
+        const executionId = action.executionId || `exec-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        action.executionId = executionId;
+        const toolDef = this.findToolDefinition(action.toolName);
+        const paramsHash = (0, capability_1.computeParametersHash)(action.parameters);
+        // Rule: Unknown tools/actions must not be implicitly authorized
+        if (!toolDef) {
+            const decision = {
+                allowed: false,
+                reason: `Tool "${action.toolName}" is not registered or known in action policy`,
+                riskLevel: 'CRITICAL',
+                executionId,
+                decisionCode: 'REJECTED_UNKNOWN_TOOL',
+            };
+            await this.recordAudit(action, effectiveContext, decision, 'REJECTED');
+            return { decision };
+        }
+        const riskLevel = toolDef.riskLevel || this.defaultRiskLevel;
+        const requiredCaps = toolDef.requiredCapabilities || [];
+        // Check request context presence
+        if (!effectiveContext) {
+            const decision = {
+                allowed: false,
+                reason: 'Missing RequestContext: Actions cannot be authorized without request context',
+                riskLevel,
+                requiredCapabilities: requiredCaps,
+                executionId,
+                decisionCode: 'REJECTED_UNAUTHORIZED',
+            };
+            await this.recordAudit(action, undefined, decision, 'REJECTED');
+            return { decision };
+        }
+        // Role check if tool restricts roles (supports administrator/owner role parity)
+        if (toolDef.allowedRoles && toolDef.allowedRoles.length > 0) {
+            const actorRole = effectiveContext.actor.authorizationRole || effectiveContext.actor.role || 'owner';
+            const normalizedActorRoles = new Set([actorRole.toLowerCase()]);
+            if (actorRole.toLowerCase() === 'administrator' || actorRole.toLowerCase() === 'owner') {
+                normalizedActorRoles.add('administrator');
+                normalizedActorRoles.add('owner');
+                normalizedActorRoles.add('admin');
+            }
+            const isAuthorizedRole = toolDef.allowedRoles.some((r) => normalizedActorRoles.has(r.toLowerCase()));
+            if (!isAuthorizedRole) {
+                const decision = {
+                    allowed: false,
+                    reason: `Actor role "${actorRole}" is not authorized to execute tool "${action.toolName}"`,
+                    riskLevel,
+                    requiredCapabilities: requiredCaps,
+                    executionId,
+                    decisionCode: 'REJECTED_UNAUTHORIZED',
+                };
+                await this.recordAudit(action, effectiveContext, decision, 'REJECTED');
+                return { decision };
+            }
+        }
+        // Channel check if tool restricts channels
+        if (toolDef.allowedChannels && toolDef.allowedChannels.length > 0) {
+            const channel = effectiveContext.conversation.channel || 'direct';
+            if (!toolDef.allowedChannels.includes(channel)) {
+                const decision = {
+                    allowed: false,
+                    reason: `Tool "${action.toolName}" cannot be executed in channel "${channel}"`,
+                    riskLevel,
+                    requiredCapabilities: requiredCaps,
+                    executionId,
+                    decisionCode: 'REJECTED_CHANNEL_RESTRICTED',
+                };
+                await this.recordAudit(action, effectiveContext, decision, 'REJECTED');
+                return { decision };
+            }
+        }
+        // Capability check
+        const actorCaps = effectiveContext.actor.capabilities || [];
+        const missingCaps = requiredCaps.filter((cap) => !actorCaps.includes(cap));
+        if (missingCaps.length > 0) {
+            const decision = {
+                allowed: false,
+                reason: `Actor is missing required capabilities: [${missingCaps.join(', ')}]`,
+                riskLevel,
+                requiredCapabilities: requiredCaps,
+                executionId,
+                decisionCode: 'REJECTED_MISSING_CAPABILITY',
+            };
+            await this.recordAudit(action, effectiveContext, decision, 'REJECTED');
+            return { decision };
+        }
+        // Risk level approval check
+        const requiresExplicitApproval = toolDef.requiresApproval ??
+            (this.defaultRequireApprovalForHighRisk && (riskLevel === 'HIGH' || riskLevel === 'CRITICAL'));
+        let isApproved = this.approvedExecutions.has(executionId);
+        if (!isApproved && typeof this.store.isActionApproved === 'function') {
+            isApproved = await this.store.isActionApproved(executionId);
+            if (isApproved) {
+                this.approvedExecutions.add(executionId);
+            }
+        }
+        if (requiresExplicitApproval && !isApproved) {
+            const decision = {
+                allowed: false,
+                reason: `Action "${action.toolName}" has risk level ${riskLevel} and requires explicit approval`,
+                riskLevel,
+                requiredCapabilities: requiredCaps,
+                executionId,
+                decisionCode: 'REJECTED_HIGH_RISK_UNAPPROVED',
+            };
+            await this.recordAudit(action, effectiveContext, decision, 'POLICY_CHECKED');
+            return { decision };
+        }
+        const decision = {
+            allowed: true,
+            reason: 'Action authorized by policy',
+            riskLevel,
+            requiredCapabilities: requiredCaps,
+            executionId,
+            decisionCode: 'ALLOWED_POLICY',
+        };
+        // Issue cryptographic/structural AuthorizationCapability
+        const issuedAt = new Date().toISOString();
+        const expiresAt = new Date(Date.now() + 60_000).toISOString();
+        const providerId = toolDef.providerId || 'builtin';
+        const capabilityPayload = {
+            executionId,
+            actionId: action.actionId,
+            toolName: action.toolName,
+            providerId,
+            parametersHash: paramsHash,
+            companionId: effectiveContext.companionId,
+            actorId: effectiveContext.actor.actorId,
+            sessionId: effectiveContext.actor.sessionId,
+            channel: effectiveContext.conversation.channel,
+            correlationId: effectiveContext.conversation.correlationId,
+            riskLevel,
+            issuedAt,
+            expiresAt,
+        };
+        const signature = (0, capability_1.signCapabilityPayload)(capabilityPayload, this.secretKey);
+        const capability = {
+            ...capabilityPayload,
+            allowed: true,
+            signature,
+        };
+        await this.recordAudit(action, effectiveContext, decision, 'APPROVED');
+        return { decision, capability };
+    }
+    async approveAction(options) {
+        this.approvedExecutions.add(options.executionId);
+        if (typeof this.store.saveApproval === 'function') {
+            await this.store.saveApproval(options.executionId, options.approverActorId, options.reason);
+        }
+        return true;
+    }
+    async recordAudit(action, context, decision, lifecycle, result, error, durationMs) {
+        const event = {
+            executionId: action.executionId || decision?.executionId || 'unknown',
+            actionId: action.actionId,
+            toolName: action.toolName,
+            companionId: context?.companionId || 'unknown',
+            actorId: context?.actor.actorId,
+            sessionId: context?.actor.sessionId,
+            channel: context?.conversation.channel,
+            correlationId: context?.conversation.correlationId,
+            riskLevel: decision?.riskLevel || 'LOW',
+            lifecycle,
+            decision,
+            parametersHash: (0, capability_1.computeParametersHash)(action.parameters),
+            resultHash: result !== undefined ? (0, capability_1.computeParametersHash)(result) : undefined,
+            timestamp: new Date().toISOString(),
+            durationMs,
+            error,
+        };
+        await this.store.appendAudit(event);
+        return event;
+    }
+    async getAuditLog() {
+        return this.store.getAuditLog();
+    }
+    getStore() {
+        return this.store;
+    }
+}
+exports.ActionPolicyEngine = ActionPolicyEngine;

package/dist/action-policy.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/action-policy.test.js

@@ -0,0 +1,193 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const action_policy_1 = require("./action-policy");
+const capability_1 = require("./capability");
+describe('ActionPolicyEngine Boundary', () => {
+    let engine;
+    let sampleContext;
+    beforeEach(() => {
+        engine = new action_policy_1.ActionPolicyEngine({
+            defaultRiskLevel: 'HIGH',
+            defaultRequireApprovalForHighRisk: true,
+            secretKey: 'test_secret_key',
+        });
+        sampleContext = {
+            companionId: 'companion-1',
+            actor: {
+                actorId: 'user-1',
+                sessionId: 'sess-1',
+                authorizationRole: 'operator',
+                capabilities: ['web:search', 'calc:basic'],
+                authenticated: true,
+            },
+            conversation: {
+                channel: 'direct',
+                correlationId: 'corr-1',
+            },
+        };
+        const searchTool = {
+            name: 'search_web',
+            providerId: 'builtin',
+            description: 'Search the web',
+            inputSchema: { type: 'object', properties: { query: { type: 'string' } }, required: ['query'] },
+            riskLevel: 'LOW',
+            requiredCapabilities: ['web:search'],
+            allowedChannels: ['direct', 'public', 'private'],
+        };
+        const deleteTool = {
+            name: 'delete_database',
+            providerId: 'admin',
+            description: 'Delete entire database',
+            inputSchema: { type: 'object' },
+            riskLevel: 'CRITICAL',
+            requiredCapabilities: ['admin:delete'],
+            allowedRoles: ['administrator'],
+            requiresApproval: true,
+        };
+        engine.registerToolDefinition(searchTool);
+        engine.registerToolDefinition(deleteTool);
+    });
+    it('approves an authorized low-risk action and issues a signed AuthorizationCapability', async () => {
+        const action = {
+            actionId: 'act-1',
+            toolName: 'builtin/search_web',
+            parameters: { query: 'Antigravity' },
+            context: sampleContext,
+        };
+        const { decision, capability } = await engine.evaluateAction(action);
+        expect(decision.allowed).toBe(true);
+        expect(decision.decisionCode).toBe('ALLOWED_POLICY');
+        expect(decision.riskLevel).toBe('LOW');
+        expect(capability).toBeDefined();
+        expect(capability?.allowed).toBe(true);
+        expect(capability?.toolName).toBe('builtin/search_web');
+        expect(capability?.actionId).toBe('act-1');
+        expect(capability?.signature).toBeDefined();
+        expect((0, capability_1.verifyCapabilitySignature)(capability, 'test_secret_key')).toBe(true);
+    });
+    it('rejects an unknown tool/action by default and issues no capability', async () => {
+        const action = {
+            actionId: 'act-2',
+            toolName: 'unregistered_tool',
+            parameters: {},
+            context: sampleContext,
+        };
+        const { decision, capability } = await engine.evaluateAction(action);
+        expect(decision.allowed).toBe(false);
+        expect(decision.decisionCode).toBe('REJECTED_UNKNOWN_TOOL');
+        expect(decision.riskLevel).toBe('CRITICAL');
+        expect(capability).toBeUndefined();
+    });
+    it('rejects action if request context is missing', async () => {
+        const action = {
+            actionId: 'act-3',
+            toolName: 'builtin/search_web',
+            parameters: { query: 'test' },
+            // No context provided
+        };
+        const { decision, capability } = await engine.evaluateAction(action);
+        expect(decision.allowed).toBe(false);
+        expect(decision.decisionCode).toBe('REJECTED_UNAUTHORIZED');
+        expect(decision.reason).toContain('Missing RequestContext');
+        expect(capability).toBeUndefined();
+    });
+    it('rejects action when actor lacks required capability', async () => {
+        const action = {
+            actionId: 'act-4',
+            toolName: 'admin/delete_database',
+            parameters: {},
+            context: sampleContext, // has 'web:search' and 'calc:basic', not 'admin:delete'
+        };
+        const { decision, capability } = await engine.evaluateAction(action);
+        expect(decision.allowed).toBe(false);
+        expect(decision.decisionCode).toBe('REJECTED_UNAUTHORIZED'); // operator is not administrator
+        expect(capability).toBeUndefined();
+    });
+    it('rejects high/critical risk action requiring explicit approval before approval is granted, and allows after approval', async () => {
+        const adminContext = {
+            ...sampleContext,
+            actor: {
+                ...sampleContext.actor,
+                authorizationRole: 'administrator',
+                capabilities: ['admin:delete'],
+            },
+        };
+        const action = {
+            actionId: 'act-5',
+            toolName: 'admin/delete_database',
+            parameters: {},
+            context: adminContext,
+            executionId: 'exec-admin-delete-1',
+        };
+        // First attempt: unapproved
+        const res1 = await engine.evaluateAction(action);
+        expect(res1.decision.allowed).toBe(false);
+        expect(res1.decision.decisionCode).toBe('REJECTED_HIGH_RISK_UNAPPROVED');
+        expect(res1.capability).toBeUndefined();
+        // Grant explicit approval
+        engine.approveAction({
+            executionId: 'exec-admin-delete-1',
+            approverActorId: 'admin-super-user',
+        });
+        // Second attempt: approved
+        const res2 = await engine.evaluateAction(action);
+        expect(res2.decision.allowed).toBe(true);
+        expect(res2.decision.decisionCode).toBe('ALLOWED_POLICY');
+        expect(res2.capability).toBeDefined();
+        expect((0, capability_1.verifyCapabilitySignature)(res2.capability, 'test_secret_key')).toBe(true);
+    });
+    it('records structured tamper-evident audit log entries with hash chaining', async () => {
+        const action = {
+            actionId: 'act-audit',
+            toolName: 'builtin/search_web',
+            parameters: { query: 'Audit Test' },
+            context: sampleContext,
+        };
+        await engine.evaluateAction(action);
+        const auditLogs = await engine.getAuditLog();
+        expect(auditLogs.length).toBeGreaterThan(0);
+        const log = auditLogs.find((l) => l.actionId === 'act-audit');
+        expect(log).toBeDefined();
+        expect(log?.actorId).toBe('user-1');
+        expect(log?.toolName).toBe('builtin/search_web');
+        expect(log?.parametersHash).toBeDefined();
+        expect(log?.resultHash).toBeDefined();
+    });
+    it('supports single-owner role parity between owner and administrator', async () => {
+        const ownerTool = {
+            name: 'builtin/owner_tool',
+            description: 'Owner only tool',
+            inputSchema: {},
+            riskLevel: 'LOW',
+            allowedRoles: ['owner'],
+        };
+        engine.registerToolDefinition(ownerTool);
+        // Context with authorizationRole: 'administrator'
+        const adminContext = {
+            ...sampleContext,
+            actor: {
+                ...sampleContext.actor,
+                authorizationRole: 'administrator',
+            },
+        };
+        const actionWithAdmin = {
+            actionId: 'act-owner-admin',
+            toolName: 'builtin/owner_tool',
+            parameters: {},
+            context: adminContext,
+        };
+        const res = await engine.evaluateAction(actionWithAdmin);
+        expect(res.decision.allowed).toBe(true);
+        expect(res.capability).toBeDefined();
+        // Context with authorizationRole: 'operator' (non-owner) is rejected
+        const operatorAction = {
+            actionId: 'act-owner-op',
+            toolName: 'builtin/owner_tool',
+            parameters: {},
+            context: sampleContext, // has authorizationRole: 'operator'
+        };
+        const resOp = await engine.evaluateAction(operatorAction);
+        expect(resOp.decision.allowed).toBe(false);
+        expect(resOp.decision.decisionCode).toBe('REJECTED_UNAUTHORIZED');
+    });
+});

package/dist/action.d.ts

@@ -0,0 +1,72 @@
+import { RequestContext } from './context';
+export type ActionRiskLevel = 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+export type ActionLifecycleState = 'PROPOSED' | 'VALIDATED' | 'POLICY_CHECKED' | 'APPROVED' | 'EXECUTING' | 'COMPLETED' | 'REJECTED' | 'FAILED' | 'CANCELLED' | 'TIMED_OUT';
+export interface ActionIntent {
+    actionId: string;
+    toolName: string;
+    parameters: Record<string, unknown>;
+    description?: string;
+    context?: RequestContext;
+    executionId?: string;
+}
+export interface ActionPolicyDecision {
+    allowed: boolean;
+    reason: string;
+    riskLevel: ActionRiskLevel;
+    requiredCapabilities?: string[];
+    executionId: string;
+    decisionCode: 'ALLOWED_AUTO' | 'ALLOWED_POLICY' | 'REJECTED_UNKNOWN_TOOL' | 'REJECTED_UNAUTHORIZED' | 'REJECTED_MISSING_CAPABILITY' | 'REJECTED_HIGH_RISK_UNAPPROVED' | 'REJECTED_CHANNEL_RESTRICTED' | 'REJECTED_COMPANION_MISMATCH' | 'REJECTED_POLICY';
+}
+export interface ActionAuditEvent {
+    executionId: string;
+    actionId: string;
+    toolName: string;
+    providerId?: string;
+    companionId: string;
+    actorId?: string;
+    sessionId?: string;
+    channel?: string;
+    correlationId?: string;
+    riskLevel: ActionRiskLevel;
+    lifecycle: ActionLifecycleState;
+    decision?: ActionPolicyDecision;
+    parametersHash?: string;
+    resultHash?: string;
+    eventHash?: string;
+    previousEventHash?: string;
+    timestamp: string;
+    durationMs?: number;
+    error?: string;
+}
+export interface ActionExecutionResult {
+    actionId: string;
+    executionId: string;
+    toolName: string;
+    lifecycle: ActionLifecycleState;
+    success: boolean;
+    result?: unknown;
+    error?: string;
+    decision?: ActionPolicyDecision;
+    durationMs?: number;
+}
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    providerId?: string;
+    riskLevel?: ActionRiskLevel;
+    requiredCapabilities?: string[];
+    allowedRoles?: string[];
+    allowedChannels?: string[];
+    timeoutMs?: number;
+    requiresApproval?: boolean;
+}
+export interface ToolExecutionOptions {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export interface HandsOrgan {
+    listTools(): Promise<ToolDefinition[]>;
+    executeAction(action: ActionIntent, authorization: any, // AuthorizationCapability required
+    options?: ToolExecutionOptions): Promise<ActionExecutionResult>;
+}

package/dist/action.js

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

package/dist/adversarial.test.d.ts

@@ -0,0 +1 @@
+export {};