overarch-linux-arm64 0.8.0

package/dist/src/security/policy.d.ts

@@ -0,0 +1,220 @@
+export type ActionRiskTier = 'safe' | 'danger';
+/**
+ * CCHCFAI Action States
+ */
+export declare enum ActionState {
+    SUGGEST = "SUGGEST",
+    REQUEST_APPROVAL = "REQUEST_APPROVAL",
+    EXECUTE = "EXECUTE",
+    DENY = "DENY",
+    ESCALATE = "ESCALATE",
+    STOP = "STOP"
+}
+/**
+ * CCHCFAI Capability Taxonomy
+ */
+export declare enum Capability {
+    READ_FILES = "READ_FILES",
+    WRITE_FILES = "WRITE_FILES",
+    DELETE_FILES = "DELETE_FILES",
+    EXECUTE_COMMANDS = "EXECUTE_COMMANDS",
+    NETWORK_ACCESS = "NETWORK_ACCESS",
+    BROWSER_ACCESS = "BROWSER_ACCESS",
+    APPLICATION_CONTROL = "APPLICATION_CONTROL",
+    CAMERA_ACCESS = "CAMERA_ACCESS",
+    MICROPHONE_ACCESS = "MICROPHONE_ACCESS",
+    MESSAGE_SENDING = "MESSAGE_SENDING",
+    ACCOUNT_ACCESS = "ACCOUNT_ACCESS",
+    SYSTEM_CONFIGURATION = "SYSTEM_CONFIGURATION",
+    INSTALLATION = "INSTALLATION"
+}
+/**
+ * CCHCFAI Risk Levels (R0 - R5)
+ */
+export declare enum RiskLevel {
+    R0 = "R0",// Informational / Read-only / Query
+    R1 = "R1",// Low-risk / Reversible local action
+    R2 = "R2",// Persistent change / Workspace modification
+    R3 = "R3",// External consequence / Network interaction
+    R4 = "R4",// High-impact / Destructive / Privilege modification
+    R5 = "R5"
+}
+/**
+ * Written Classification Rubric for Overarch CCHCFAI Policy Engine
+ */
+export declare const POLICY_CLASSIFICATION_RUBRIC: {
+    readonly R0: {
+        readonly name: "Informational & Read-Only";
+        readonly description: "Read-only inspections, queries, directory listings, diffs, symbol extraction, search. Zero state modification.";
+        readonly capabilities: readonly [Capability.READ_FILES, Capability.NETWORK_ACCESS];
+        readonly defaultState: ActionState.EXECUTE;
+        readonly approvalRequired: false;
+        readonly reversible: true;
+        readonly examples: readonly ["readFile", "readSlice", "listDirectory", "fileSearch", "gitStatus", "gitLog", "web_search"];
+    };
+    readonly R1: {
+        readonly name: "Low-Risk Reversible Local Mutation";
+        readonly description: "Workspace file additions and edits in non-sensitive paths. Readily revertible via git or checkpoint manager.";
+        readonly capabilities: readonly [Capability.WRITE_FILES];
+        readonly defaultState: ActionState.EXECUTE;
+        readonly approvalRequired: false;
+        readonly reversible: true;
+        readonly examples: readonly ["writeFile (workspace code)", "editFile (src/component.ts)", "patchSection (README.md)"];
+    };
+    readonly R2: {
+        readonly name: "Persistent Workspace Mutation";
+        readonly description: "Package installations, git commits, running test/build commands, stateful tool configurations.";
+        readonly capabilities: readonly [Capability.EXECUTE_COMMANDS, Capability.INSTALLATION];
+        readonly defaultState: ActionState.REQUEST_APPROVAL;
+        readonly approvalRequired: true;
+        readonly reversible: true;
+        readonly examples: readonly ["runShell (npm test)", "executeCommand (npm run build)", "runShell (git commit -m \"update\")"];
+    };
+    readonly R3: {
+        readonly name: "External Consequence & Network Interaction";
+        readonly description: "Pushing changes to remote repositories, sending external network requests, publishing packages, webhooks.";
+        readonly capabilities: readonly [Capability.NETWORK_ACCESS, Capability.MESSAGE_SENDING];
+        readonly defaultState: ActionState.REQUEST_APPROVAL;
+        readonly approvalRequired: true;
+        readonly reversible: false;
+        readonly examples: readonly ["runShell (git push)", "runShell (npm publish)", "curl / POST to external API"];
+    };
+    readonly R4: {
+        readonly name: "High-Impact / Destructive / Privilege Modification";
+        readonly description: "File deletions, modifying secret/credential files (.env, id_rsa, .ssh), modifying system configurations.";
+        readonly capabilities: readonly [Capability.DELETE_FILES, Capability.SYSTEM_CONFIGURATION, Capability.ACCOUNT_ACCESS];
+        readonly defaultState: ActionState.REQUEST_APPROVAL;
+        readonly approvalRequired: true;
+        readonly reversible: false;
+        readonly examples: readonly ["deleteFile (workspace file)", "writeFile (.env)", "writeFile (~/.ssh/id_rsa)", "Remove-Item single file"];
+    };
+    readonly R5: {
+        readonly name: "Prohibited / Catastrophic / Critical System Damage";
+        readonly description: "Catastrophic destruction, recursive root/system deletions, volume format, fork bombs, encoded bypass execution, shutdown.";
+        readonly capabilities: readonly [Capability.EXECUTE_COMMANDS, Capability.SYSTEM_CONFIGURATION];
+        readonly defaultState: ActionState.DENY;
+        readonly approvalRequired: false;
+        readonly prohibited: true;
+        readonly reversible: false;
+        readonly examples: readonly ["rm -rf /", "del /s /q C:\\", "Remove-Item -Recurse -Force C:\\", "Format-Volume -DriveLetter C", "powershell -EncodedCommand ...", ":(){ :|:& };:", "shutdown /s /t 0"];
+    };
+};
+/**
+ * Test Corpus of Real Commands Mapped to Risk Levels & Expected Behavior
+ */
+export declare const POLICY_TEST_CORPUS: {
+    command: string;
+    capability: Capability;
+    riskLevel: RiskLevel;
+    expectedState: ActionState;
+    category: string;
+}[];
+export interface ApprovalRequest {
+    id: string;
+    toolName: string;
+    capability: Capability;
+    riskLevel: RiskLevel;
+    description: string;
+    impact: string;
+    rollbackPossible: boolean;
+    timestamp: number;
+}
+export interface CchcfaiEvaluation {
+    actionState: ActionState;
+    riskLevel: RiskLevel;
+    capability: Capability;
+    allowed: boolean;
+    tier: ActionRiskTier;
+    reason?: string;
+    approvalRequired: boolean;
+}
+export interface PolicyCheckResult {
+    allowed: boolean;
+    tier: ActionRiskTier;
+    reason?: string;
+    actionState?: ActionState;
+    riskLevel?: RiskLevel;
+}
+export interface OverarchPolicyConfig {
+    capabilities?: Partial<Record<Capability, ActionState>>;
+    maxAutoApproveRisk?: RiskLevel;
+    safeOnly?: boolean;
+    customDeniedPatterns?: string[];
+}
+export interface PolicyOptions {
+    safeOnly?: boolean;
+    allowedTools?: string[];
+    deniedTools?: string[];
+    grantedCapabilities?: Capability[];
+    configPath?: string;
+}
+/**
+ * CCHCFAI Standalone Policy Engine.
+ * Evaluates whether an agent action falls into SAFE or DANGER tier,
+ * enforces strict policy boundaries and CCHCFAI action states without touching agent runtime internals.
+ */
+export declare class PolicyEngine {
+    private safeOnly;
+    private childProcesses;
+    private userConfig;
+    private sessionApprovals;
+    private static instance;
+    private static signalHandlerRegistered;
+    constructor(options?: PolicyOptions);
+    static getInstance(options?: PolicyOptions): PolicyEngine;
+    setSafeOnly(safeOnly: boolean): void;
+    isSafeOnly(): boolean;
+    /**
+     * Load user-editable overarch.policy.json configuration.
+     */
+    loadPolicyConfigFile(customPath?: string, explicitSafeOnly?: boolean): OverarchPolicyConfig | null;
+    setPolicyConfig(config: OverarchPolicyConfig): void;
+    getPolicyConfig(): OverarchPolicyConfig | null;
+    /**
+     * Approve a tool or capability for the remainder of the active session.
+     */
+    approveForSession(toolName: string, capability?: Capability): void;
+    isApprovedForSession(toolName: string, capability?: Capability): boolean;
+    clearSessionApprovals(): void;
+    /**
+     * Decomposes potentially chained commands and checks for R5 prohibited patterns.
+     */
+    checkProhibitedCommand(rawCommand: string): {
+        prohibited: boolean;
+        pattern?: string;
+        segment?: string;
+    };
+    /**
+     * Evaluates if a given tool invocation is SAFE or DANGER.
+     */
+    classifyAction(toolName: string, params?: Record<string, any>): {
+        tier: ActionRiskTier;
+        reason?: string;
+    };
+    /**
+     * Maps a tool invocation to the CCHCFAI Capability taxonomy.
+     */
+    mapToolToCapability(toolName: string, params?: Record<string, any>): Capability;
+    /**
+     * Evaluates action according to CCHCFAI standards (Action State, Risk Level, Capability).
+     * Enforces fail-closed defaults and append-only audit logging.
+     */
+    evaluateCchcfai(toolName: string, params?: Record<string, any>): CchcfaiEvaluation;
+    /**
+     * Pre-execution policy check. Returns whether the action is permitted under current settings
+     * and records decision in the append-only audit log.
+     */
+    checkPolicy(toolName: string, params?: Record<string, any>): PolicyCheckResult;
+    /**
+     * Track spawned child process PID for emergency stop cleanup.
+     */
+    registerProcess(pid: number): void;
+    unregisterProcess(pid: number): void;
+    /**
+     * Silent emergency stop: Immediately halts all child processes and process tree cleanly.
+     * On Windows, uses taskkill /F /T to terminate the entire process tree.
+     */
+    terminateAllProcesses(): void;
+    private setupSilentEmergencyStop;
+}
+export declare const policyEngine: PolicyEngine;