/** * @fileoverview Physical capability definitions for the BASIS Capability Taxonomy. * * AI agents can cause irreversible physical hardware damage today: * - PMFault: CPU bricking via voltage manipulation * - IPMI fan disabling leading to thermal damage * - Malicious firmware updates bricking storage controllers * * This module defines the `physical:` capability namespace with strict * trust tier requirements and mandatory human-in-the-loop controls. * * All physical capabilities carry a PHYSICAL_SAFETY risk category that * is distinct from the standard CRITICAL risk level. Even T7 Autonomous * agents MUST receive human approval before modifying hardware state. * * Restored 0.4.x published surface — consumed by @vorionsys/a3i. * * @module @vorionsys/contracts/canonical/capabilities */ /** * Extended risk category type that includes PHYSICAL_SAFETY. * * PHYSICAL_SAFETY is auto-classified when an action touches physical:* capabilities. * It is orthogonal to the standard LOW/MEDIUM/HIGH/CRITICAL scale — a physical * operation is always treated as requiring human oversight regardless of the * agent's trust tier. * * - Always requires human-in-the-loop, even at T7 * - Mandatory 30-second hold for physical write operations * - Cannot be overridden by policy exceptions */ export type RiskCategory = 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL' | 'PHYSICAL_SAFETY'; /** * All valid risk categories as a constant array. */ export declare const RISK_CATEGORIES: readonly RiskCategory[]; /** * Type guard: checks if a value is a valid RiskCategory. */ export declare function isRiskCategory(value: unknown): value is RiskCategory; /** * Mandatory hold duration (milliseconds) for physical write operations. * Gives human operators time to review and cancel before execution. */ export declare const PHYSICAL_SAFETY_HOLD_MS = 30000; /** * Definition of a single physical capability's governance rules. */ export interface PhysicalCapabilityDef { /** Minimum trust tier (0-7) required for this capability */ readonly minTier: number; /** Whether human approval is mandatory before execution */ readonly requiresHumanApproval: boolean; /** Human-readable description of what this capability controls */ readonly description: string; /** Risk category for this capability */ readonly riskCategory: RiskCategory; } /** * Complete registry of physical capabilities with their governance rules. * * Trust tier mapping: * - T3 (Monitored, 500-649): Read-only sensor data * - T4 (Standard, 650-799): Read-only firmware info * - T5 (Trusted, 800-875): Actuator, power management, network config * - T6 (Certified, 876-950): Cooling/thermal management * - T7 (Autonomous, 951-1000): Firmware updates, voltage, storage firmware, BMC/IPMI */ export declare const PHYSICAL_CAPABILITIES: { readonly 'physical:sensor/read': { readonly minTier: 3; readonly requiresHumanApproval: false; readonly description: "Read sensor data (temperature, voltage, fan speed)"; readonly riskCategory: "MEDIUM"; }; readonly 'physical:actuator/control': { readonly minTier: 5; readonly requiresHumanApproval: true; readonly description: "Control physical actuators (motors, relays, servos)"; readonly riskCategory: "PHYSICAL_SAFETY"; }; readonly 'physical:firmware/read': { readonly minTier: 4; readonly requiresHumanApproval: false; readonly description: "Read firmware version and configuration information"; readonly riskCategory: "HIGH"; }; readonly 'physical:firmware/update': { readonly minTier: 7; readonly requiresHumanApproval: true; readonly description: "Update device firmware (risk: bricking)"; readonly riskCategory: "PHYSICAL_SAFETY"; }; readonly 'physical:power/manage': { readonly minTier: 5; readonly requiresHumanApproval: true; readonly description: "Manage power states (sleep, wake, reboot, shutdown)"; readonly riskCategory: "PHYSICAL_SAFETY"; }; readonly 'physical:power/voltage': { readonly minTier: 7; readonly requiresHumanApproval: true; readonly description: "Modify voltage/frequency settings (risk: CPU bricking via PMFault)"; readonly riskCategory: "PHYSICAL_SAFETY"; }; readonly 'physical:cooling/manage': { readonly minTier: 6; readonly requiresHumanApproval: true; readonly description: "Manage cooling systems (risk: thermal damage if disabled)"; readonly riskCategory: "PHYSICAL_SAFETY"; }; readonly 'physical:network/configure': { readonly minTier: 5; readonly requiresHumanApproval: true; readonly description: "Configure physical network interfaces (NIC, switch ports)"; readonly riskCategory: "PHYSICAL_SAFETY"; }; readonly 'physical:storage/firmware': { readonly minTier: 7; readonly requiresHumanApproval: true; readonly description: "Update storage controller/drive firmware (risk: data loss)"; readonly riskCategory: "PHYSICAL_SAFETY"; }; readonly 'physical:bmc/access': { readonly minTier: 7; readonly requiresHumanApproval: true; readonly description: "Access Baseboard Management Controller / IPMI interface (risk: full hardware control)"; readonly riskCategory: "PHYSICAL_SAFETY"; }; }; /** * Union type of all known physical capability strings. */ export type PhysicalCapability = keyof typeof PHYSICAL_CAPABILITIES; /** * Array of all known physical capability strings, for iteration. */ export declare const ALL_PHYSICAL_CAPABILITIES: readonly PhysicalCapability[]; /** * Checks whether a capability string belongs to the physical namespace. * * @param cap - The capability string to check * @returns True if the capability starts with "physical:" * * @example * ```typescript * isPhysicalCapability('physical:sensor/read'); // true * isPhysicalCapability('data:read/public'); // false * isPhysicalCapability('physical:unknown/thing'); // true (prefix match) * ``` */ export declare function isPhysicalCapability(cap: string): boolean; /** * Checks whether a physical capability requires human approval. * * For known capabilities, returns the configured value. * For unknown physical capabilities, defaults to `true` (safe-by-default). * For non-physical capabilities, returns `false`. * * @param cap - The capability string to check * @returns True if human approval is required */ export declare function requiresHumanApproval(cap: string): boolean; /** * Gets the minimum trust tier required for a physical capability. * * For known capabilities, returns the configured minimum tier. * For unknown physical capabilities, defaults to 7 (highest tier — safe-by-default). * For non-physical capabilities, returns -1 to indicate no physical constraint. * * @param cap - The capability string to check * @returns Minimum trust tier (0-7), or -1 for non-physical capabilities */ export declare function getMinTierForCapability(cap: string): number; /** * Gets the risk category for a physical capability. * * For known capabilities, returns the configured risk category. * For unknown physical capabilities, defaults to PHYSICAL_SAFETY. * For non-physical capabilities, returns null. * * @param cap - The capability string to check * @returns RiskCategory or null for non-physical capabilities */ export declare function getRiskCategoryForCapability(cap: string): RiskCategory | null; /** * Gets the full definition for a physical capability. * * @param cap - The capability string to look up * @returns The capability definition, or undefined if not a known physical capability */ export declare function getPhysicalCapabilityDef(cap: string): PhysicalCapabilityDef | undefined; /** * Checks whether an agent at a given trust tier can execute a physical capability. * * This performs a tier check only — it does NOT check human approval requirements. * Callers must separately check `requiresHumanApproval()` and enforce the * 30-second hold period for physical write operations. * * @param cap - The physical capability to check * @param agentTier - The agent's current trust tier (0-7) * @returns True if the agent's tier meets the minimum requirement */ export declare function canAgentAttemptPhysicalCapability(cap: string, agentTier: number): boolean;