@longarc/mdash 3.0.0

package/src/physics/engine.ts

@@ -0,0 +1,563 @@
+/**
+ * mdash v3.0 - Physics Engine
+ * 
+ * "Physics" = the laws of agent behavior that cannot be violated.
+ * Validates actions against constraints with signed artifacts.
+ * 
+ * Key Concept: Plausibility scoring determines if an action
+ * is physically possible given the warrant and context.
+ */
+
+import {
+  Hash,
+  Seal,
+  Timestamp,
+  WarrantId,
+  CheckpointId,
+  sha256Object,
+  hmacSeal,
+  deriveKey,
+  generateTimestamp,
+} from '../core/crypto';
+
+import { Warrant, WarrantConstraints } from '../warrant/engine';
+
+// ============================================================================
+// PHYSICS TYPES
+// ============================================================================
+
+export type PhysicsViolationType =
+  | 'amount_exceeded'
+  | 'rate_exceeded'
+  | 'domain_forbidden'
+  | 'time_forbidden'
+  | 'delegation_forbidden'
+  | 'scope_violation'
+  | 'causality_violation'
+  | 'invariant_violation';
+
+export interface PhysicsConstraint {
+  /** Constraint type */
+  type: string;
+  /** Constraint parameters */
+  params: Record<string, unknown>;
+  /** Whether violation should block or warn */
+  severity: 'block' | 'warn';
+}
+
+export interface PhysicsAction {
+  /** Action identifier */
+  action_id: string;
+  /** Action type */
+  type: string;
+  /** Agent performing the action */
+  agent_id: string;
+  /** Warrant authorizing the action */
+  warrant_id: WarrantId;
+  /** Action parameters */
+  params: Record<string, unknown>;
+  /** Timestamp */
+  timestamp: Timestamp;
+}
+
+export interface PhysicsValidation {
+  /** Action being validated */
+  action: PhysicsAction;
+  /** Whether action is valid */
+  valid: boolean;
+  /** Plausibility score (0-1) */
+  score: number;
+  /** Violations found */
+  violations: PhysicsViolation[];
+  /** Validation timestamp */
+  validated_at: Timestamp;
+  /** Validation hash (for audit) */
+  hash: Hash;
+}
+
+export interface PhysicsViolation {
+  /** Violation type */
+  type: PhysicsViolationType;
+  /** Constraint that was violated */
+  constraint: PhysicsConstraint;
+  /** Human-readable message */
+  message: string;
+  /** Severity */
+  severity: 'block' | 'warn';
+}
+
+export interface SignedArtifact {
+  /** Artifact type */
+  type: 'validation' | 'constraint' | 'policy';
+  /** Artifact content */
+  content: unknown;
+  /** Content hash */
+  hash: Hash;
+  /** HMAC seal */
+  seal: Seal;
+  /** Creation timestamp */
+  created_at: Timestamp;
+  /** Version for hot-swap */
+  version: string;
+}
+
+// ============================================================================
+// PHYSICS POLICIES
+// ============================================================================
+
+export interface PhysicsPolicy {
+  /** Policy identifier */
+  id: string;
+  /** Policy name */
+  name: string;
+  /** Policy version */
+  version: string;
+  /** Constraints defined by this policy */
+  constraints: PhysicsConstraint[];
+  /** Whether policy is active */
+  active: boolean;
+}
+
+// Default policies
+export const DEFAULT_POLICIES: PhysicsPolicy[] = [
+  {
+    id: 'financial-transfer-v2',
+    name: 'Financial Transfer',
+    version: '2.0',
+    active: true,
+    constraints: [
+      {
+        type: 'max_amount',
+        params: { limit: 100000, currency: 'USD' },
+        severity: 'block',
+      },
+      {
+        type: 'rate_limit',
+        params: { max_per_hour: 10, max_per_day: 50 },
+        severity: 'block',
+      },
+      {
+        type: 'allowlist',
+        params: { field: 'destination', required: true },
+        severity: 'block',
+      },
+    ],
+  },
+  {
+    id: 'data-access-v1',
+    name: 'Data Access',
+    version: '1.0',
+    active: true,
+    constraints: [
+      {
+        type: 'scope_restriction',
+        params: { allowed_tables: [], require_explicit: true },
+        severity: 'block',
+      },
+      {
+        type: 'rate_limit',
+        params: { max_per_minute: 100 },
+        severity: 'warn',
+      },
+    ],
+  },
+  {
+    id: 'external-api-v1',
+    name: 'External API',
+    version: '1.0',
+    active: true,
+    constraints: [
+      {
+        type: 'domain_allowlist',
+        params: { domains: [], require_explicit: true },
+        severity: 'block',
+      },
+      {
+        type: 'rate_limit',
+        params: { max_per_minute: 60 },
+        severity: 'warn',
+      },
+    ],
+  },
+];
+
+// ============================================================================
+// PHYSICS ENGINE
+// ============================================================================
+
+export class PhysicsEngine {
+  private key: CryptoKey | null = null;
+  private policies: Map<string, PhysicsPolicy> = new Map();
+  private validationHistory: PhysicsValidation[] = [];
+  private rateCounters: Map<string, { count: number; windowStart: number }> = new Map();
+  
+  constructor() {
+    // Load default policies
+    for (const policy of DEFAULT_POLICIES) {
+      this.policies.set(policy.id, policy);
+    }
+  }
+  
+  /**
+   * Initialize the engine with a seal key
+   */
+  async initialize(sealKey: string): Promise<void> {
+    this.key = await deriveKey(sealKey);
+  }
+  
+  /**
+   * Validate an action against physics constraints
+   */
+  async validate(
+    action: PhysicsAction,
+    warrant: Warrant
+  ): Promise<PhysicsValidation> {
+    if (!this.key) {
+      throw new Error('Engine not initialized. Call initialize() first.');
+    }
+    
+    const startTime = performance.now();
+    const violations: PhysicsViolation[] = [];
+    
+    // Get policy for the warrant
+    const policy = this.policies.get(warrant.policy_id);
+    if (!policy) {
+      violations.push({
+        type: 'scope_violation',
+        constraint: { type: 'policy_required', params: {}, severity: 'block' },
+        message: `Unknown policy: ${warrant.policy_id}`,
+        severity: 'block',
+      });
+    } else {
+      // Check each constraint
+      for (const constraint of policy.constraints) {
+        const violation = await this.checkConstraint(
+          constraint,
+          action,
+          warrant.constraints
+        );
+        if (violation) {
+          violations.push(violation);
+        }
+      }
+    }
+    
+    // Check warrant-level constraints
+    const warrantViolations = this.checkWarrantConstraints(action, warrant.constraints);
+    violations.push(...warrantViolations);
+    
+    // Check rate limits
+    const rateViolation = this.checkRateLimit(action);
+    if (rateViolation) {
+      violations.push(rateViolation);
+    }
+    
+    // Calculate plausibility score
+    const blockingViolations = violations.filter(v => v.severity === 'block');
+    const score = blockingViolations.length === 0 
+      ? Math.max(0, 1 - violations.length * 0.1)
+      : 0;
+    
+    const now = generateTimestamp();
+    
+    // Create validation record
+    const validationData = {
+      action,
+      valid: blockingViolations.length === 0,
+      score,
+      violations,
+      validated_at: now,
+    };
+    
+    const hash = await sha256Object(validationData);
+    
+    const validation: PhysicsValidation = {
+      ...validationData,
+      hash,
+    };
+    
+    // Store in history
+    this.validationHistory.push(validation);
+    
+    const elapsed = performance.now() - startTime;
+    if (elapsed > 5) {
+      console.warn(`Physics validation exceeded target: ${elapsed.toFixed(2)}ms`);
+    }
+    
+    return validation;
+  }
+  
+  /**
+   * Check a specific constraint
+   */
+  private async checkConstraint(
+    constraint: PhysicsConstraint,
+    action: PhysicsAction,
+    warrantConstraints: WarrantConstraints
+  ): Promise<PhysicsViolation | null> {
+    switch (constraint.type) {
+      case 'max_amount': {
+        const amount = action.params.amount as number | undefined;
+        const limit = warrantConstraints.maxAmount ?? (constraint.params.limit as number);
+        
+        if (amount !== undefined && amount > limit) {
+          return {
+            type: 'amount_exceeded',
+            constraint,
+            message: `Amount ${amount} exceeds limit ${limit}`,
+            severity: constraint.severity,
+          };
+        }
+        break;
+      }
+      
+      case 'domain_allowlist': {
+        const domain = action.params.domain as string | undefined;
+        const allowed = warrantConstraints.allowedDomains ?? (constraint.params.domains as string[]);
+        
+        if (domain && allowed.length > 0 && !allowed.includes(domain)) {
+          return {
+            type: 'domain_forbidden',
+            constraint,
+            message: `Domain ${domain} not in allowlist`,
+            severity: constraint.severity,
+          };
+        }
+        break;
+      }
+      
+      case 'allowlist': {
+        const field = constraint.params.field as string;
+        const value = action.params[field] as string | undefined;
+        const allowed = warrantConstraints.allowedAccounts ?? [];
+        
+        if (constraint.params.required && value && allowed.length > 0) {
+          // Check suffix matching for account numbers
+          const matches = allowed.some(pattern => {
+            if (pattern.startsWith('*')) {
+              return value.endsWith(pattern.slice(1));
+            }
+            return value === pattern;
+          });
+          
+          if (!matches) {
+            return {
+              type: 'scope_violation',
+              constraint,
+              message: `${field} "${value}" not in allowlist`,
+              severity: constraint.severity,
+            };
+          }
+        }
+        break;
+      }
+    }
+    
+    return null;
+  }
+  
+  /**
+   * Check warrant-level constraints
+   */
+  private checkWarrantConstraints(
+    action: PhysicsAction,
+    constraints: WarrantConstraints
+  ): PhysicsViolation[] {
+    const violations: PhysicsViolation[] = [];
+    
+    // Check 2FA requirement
+    if (constraints.require2FA && !action.params.has2FA) {
+      violations.push({
+        type: 'scope_violation',
+        constraint: { type: 'require_2fa', params: {}, severity: 'block' },
+        message: '2FA required but not provided',
+        severity: 'block',
+      });
+    }
+    
+    return violations;
+  }
+  
+  /**
+   * Check rate limits
+   */
+  private checkRateLimit(action: PhysicsAction): PhysicsViolation | null {
+    const key = `${action.agent_id}:${action.type}`;
+    const now = Date.now();
+    const windowMs = 60 * 1000; // 1 minute window
+    
+    let counter = this.rateCounters.get(key);
+    if (!counter || now - counter.windowStart > windowMs) {
+      counter = { count: 0, windowStart: now };
+    }
+    
+    counter.count++;
+    this.rateCounters.set(key, counter);
+    
+    // Default rate limit: 100 actions per minute
+    const limit = 100;
+    if (counter.count > limit) {
+      return {
+        type: 'rate_exceeded',
+        constraint: { type: 'rate_limit', params: { limit }, severity: 'block' },
+        message: `Rate limit exceeded: ${counter.count}/${limit} per minute`,
+        severity: 'block',
+      };
+    }
+    
+    return null;
+  }
+  
+  /**
+   * Create a signed artifact
+   */
+  async createSignedArtifact(
+    type: SignedArtifact['type'],
+    content: unknown,
+    version: string
+  ): Promise<SignedArtifact> {
+    if (!this.key) {
+      throw new Error('Engine not initialized. Call initialize() first.');
+    }
+    
+    const now = generateTimestamp();
+    const hash = await sha256Object({ type, content, version, created_at: now });
+    const seal = await hmacSeal({ hash, type, version }, this.key);
+    
+    return {
+      type,
+      content,
+      hash,
+      seal,
+      created_at: now,
+      version,
+    };
+  }
+  
+  /**
+   * Hot-swap a policy (for runtime updates)
+   */
+  async hotSwapPolicy(policy: PhysicsPolicy): Promise<SignedArtifact> {
+    // Create signed artifact for audit
+    const artifact = await this.createSignedArtifact(
+      'policy',
+      policy,
+      policy.version
+    );
+    
+    // Replace policy
+    this.policies.set(policy.id, policy);
+    
+    return artifact;
+  }
+  
+  /**
+   * Get policy by ID
+   */
+  getPolicy(id: string): PhysicsPolicy | null {
+    return this.policies.get(id) || null;
+  }
+  
+  /**
+   * Get all policies
+   */
+  getAllPolicies(): PhysicsPolicy[] {
+    return Array.from(this.policies.values());
+  }
+  
+  /**
+   * Get validation history for an agent
+   */
+  getValidationHistory(agentId?: string, limit: number = 100): PhysicsValidation[] {
+    let history = this.validationHistory;
+    
+    if (agentId) {
+      history = history.filter(v => v.action.agent_id === agentId);
+    }
+    
+    return history.slice(-limit);
+  }
+  
+  /**
+   * Get plausibility statistics
+   */
+  getStats(): {
+    totalValidations: number;
+    validCount: number;
+    invalidCount: number;
+    averageScore: number;
+    violationsByType: Record<string, number>;
+  } {
+    const total = this.validationHistory.length;
+    const valid = this.validationHistory.filter(v => v.valid).length;
+    const scores = this.validationHistory.map(v => v.score);
+    const avgScore = scores.length > 0 
+      ? scores.reduce((a, b) => a + b, 0) / scores.length 
+      : 0;
+    
+    const violationsByType: Record<string, number> = {};
+    for (const validation of this.validationHistory) {
+      for (const violation of validation.violations) {
+        violationsByType[violation.type] = (violationsByType[violation.type] || 0) + 1;
+      }
+    }
+    
+    return {
+      totalValidations: total,
+      validCount: valid,
+      invalidCount: total - valid,
+      averageScore: avgScore,
+      violationsByType,
+    };
+  }
+}
+
+// ============================================================================
+// CAUSALITY CHECKER
+// ============================================================================
+
+/**
+ * Ensures actions respect causal ordering
+ * "Effect cannot precede cause"
+ */
+export class CausalityChecker {
+  private actionLog: Array<{ action: PhysicsAction; checkpoint: CheckpointId }> = [];
+  
+  /**
+   * Record an action with its checkpoint
+   */
+  record(action: PhysicsAction, checkpoint: CheckpointId): void {
+    this.actionLog.push({ action, checkpoint });
+  }
+  
+  /**
+   * Check if an action would violate causality
+   */
+  checkCausality(
+    _action: PhysicsAction,
+    dependencies: CheckpointId[]
+  ): { valid: boolean; violation?: string } {
+    // All dependencies must be in the log
+    for (const dep of dependencies) {
+      const found = this.actionLog.some(entry => entry.checkpoint === dep);
+      if (!found) {
+        return {
+          valid: false,
+          violation: `Dependency checkpoint ${dep} not found in causal history`,
+        };
+      }
+    }
+    
+    return { valid: true };
+  }
+  
+  /**
+   * Get causal chain for an action
+   */
+  getCausalChain(checkpointId: CheckpointId): PhysicsAction[] {
+    const index = this.actionLog.findIndex(e => e.checkpoint === checkpointId);
+    if (index === -1) return [];
+    
+    return this.actionLog.slice(0, index + 1).map(e => e.action);
+  }
+}