@longarc/mdash 3.0.0

package/src/warrant/engine.ts

@@ -0,0 +1,625 @@
+/**
+ * mdash v3.0 - Warrant System
+ * 
+ * Speculative warrant issuance with cryptographic invalidation.
+ * Target: <10ms activation (cache hit)
+ * 
+ * Invariants:
+ * - WARRANT-INV-001: Speculative warrants expire within 60s if not activated
+ * - WARRANT-INV-002: Revocation propagates to all caches within 100ms
+ * - WARRANT-INV-003: Activated warrants immediately sealed (L1)
+ */
+
+import {
+  Hash,
+  Seal,
+  Timestamp,
+  WarrantId,
+  generateWarrantId,
+  generateTimestamp,
+  sha256Object,
+  hmacSeal,
+  deriveKey,
+} from '../core/crypto.js';
+
+import { CommitmentEngine } from '../core/commitment.js';
+
+// ============================================================================
+// WARRANT TYPES
+// ============================================================================
+
+export type WarrantState = 
+  | 'DRAFT'
+  | 'PENDING'
+  | 'SPECULATIVE'
+  | 'ACTIVE'
+  | 'REVOKED'
+  | 'EXPIRED'
+  | 'ARCHIVED';
+
+export type WarrantTier = 'T1' | 'T2' | 'T3';
+
+export interface WarrantConstraints {
+  /** Maximum number of invocations */
+  maxCalls?: number;
+  /** Maximum execution time (ms) */
+  maxTime?: number;
+  /** Maximum financial exposure */
+  maxAmount?: number;
+  /** Allowed destination accounts (for financial) */
+  allowedAccounts?: string[];
+  /** Required 2FA */
+  require2FA?: boolean;
+  /** Allowed domains */
+  allowedDomains?: string[];
+  /** Custom constraints */
+  custom?: Record<string, unknown>;
+}
+
+export interface Warrant {
+  /** Unique warrant identifier */
+  id: WarrantId;
+  /** Agent this warrant governs */
+  agent_id: string;
+  /** Policy template reference */
+  policy_id: string;
+  /** Current state */
+  state: WarrantState;
+  /** Liability tier */
+  tier: WarrantTier;
+  /** Operational constraints */
+  constraints: WarrantConstraints;
+  /** Creation timestamp */
+  created_at: Timestamp;
+  /** Activation timestamp (null if not yet activated) */
+  activated_at: Timestamp | null;
+  /** Expiration timestamp */
+  expires_at: Timestamp;
+  /** Revocation timestamp (null if not revoked) */
+  revoked_at: Timestamp | null;
+  /** Revocation reason */
+  revocation_reason?: string;
+  /** Issuer identity */
+  issued_by: string;
+  /** HMAC seal */
+  seal: Seal;
+  /** Protocol version */
+  version: 'v3.0';
+}
+
+export interface SpeculativeWarrant extends Warrant {
+  state: 'SPECULATIVE';
+  /** Speculative expiry (60s from creation) */
+  speculative_expires_at: Timestamp;
+  /** Pre-computed activation seal */
+  activation_seal: Seal;
+}
+
+export interface WarrantEvent {
+  warrant_id: WarrantId;
+  event_type: 'created' | 'activated' | 'revoked' | 'expired' | 'archived';
+  timestamp: Timestamp;
+  actor: {
+    type: 'user' | 'system';
+    id: string;
+    email?: string;
+  };
+  reason: string | undefined;
+  previous_state: WarrantState;
+  new_state: WarrantState;
+  hash: Hash;
+  parent_hash: Hash | null;
+}
+
+// ============================================================================
+// WARRANT CACHE - For <10ms activation
+// ============================================================================
+
+interface CacheEntry {
+  warrant: Warrant | SpeculativeWarrant;
+  cached_at: number;
+  ttl_ms: number;
+}
+
+export class WarrantCache {
+  private cache: Map<WarrantId, CacheEntry> = new Map();
+  private speculative: Map<string, WarrantId[]> = new Map(); // agent_id -> warrant_ids
+  private revocations: Set<WarrantId> = new Set();
+  
+  private readonly DEFAULT_TTL = 5 * 60 * 1000; // 5 minutes
+  private readonly SPECULATIVE_TTL = 60 * 1000; // 60 seconds (WARRANT-INV-001)
+  
+  /**
+   * Store a warrant in cache
+   */
+  set(warrant: Warrant | SpeculativeWarrant, ttl?: number): void {
+    const effectiveTtl = warrant.state === 'SPECULATIVE' 
+      ? this.SPECULATIVE_TTL 
+      : (ttl || this.DEFAULT_TTL);
+    
+    this.cache.set(warrant.id, {
+      warrant,
+      cached_at: Date.now(),
+      ttl_ms: effectiveTtl,
+    });
+    
+    // Track speculative warrants by agent
+    if (warrant.state === 'SPECULATIVE') {
+      const existing = this.speculative.get(warrant.agent_id) || [];
+      existing.push(warrant.id);
+      this.speculative.set(warrant.agent_id, existing);
+    }
+  }
+  
+  /**
+   * Get a warrant from cache
+   * Returns null if not found, expired, or revoked
+   */
+  get(id: WarrantId): Warrant | SpeculativeWarrant | null {
+    // Check revocation first (WARRANT-INV-002)
+    if (this.revocations.has(id)) {
+      return null;
+    }
+    
+    const entry = this.cache.get(id);
+    if (!entry) {
+      return null;
+    }
+    
+    // Check TTL
+    if (Date.now() - entry.cached_at > entry.ttl_ms) {
+      this.cache.delete(id);
+      return null;
+    }
+    
+    return entry.warrant;
+  }
+  
+  /**
+   * Get speculative warrants for an agent
+   * For pre-staged activation
+   */
+  getSpeculativeForAgent(agentId: string): SpeculativeWarrant[] {
+    const ids = this.speculative.get(agentId) || [];
+    const warrants: SpeculativeWarrant[] = [];
+    
+    for (const id of ids) {
+      const warrant = this.get(id);
+      if (warrant && warrant.state === 'SPECULATIVE') {
+        warrants.push(warrant as SpeculativeWarrant);
+      }
+    }
+    
+    return warrants;
+  }
+  
+  /**
+   * Record a revocation
+   * Propagates immediately (WARRANT-INV-002)
+   */
+  revoke(id: WarrantId): void {
+    this.revocations.add(id);
+    this.cache.delete(id);
+    
+    // Remove from speculative tracking
+    for (const [agentId, ids] of this.speculative) {
+      const filtered = ids.filter(i => i !== id);
+      if (filtered.length !== ids.length) {
+        this.speculative.set(agentId, filtered);
+      }
+    }
+  }
+  
+  /**
+   * Check if a warrant is revoked
+   */
+  isRevoked(id: WarrantId): boolean {
+    return this.revocations.has(id);
+  }
+  
+  /**
+   * Clear expired entries
+   */
+  cleanup(): number {
+    let removed = 0;
+    const now = Date.now();
+    
+    for (const [id, entry] of this.cache) {
+      if (now - entry.cached_at > entry.ttl_ms) {
+        this.cache.delete(id);
+        removed++;
+      }
+    }
+    
+    return removed;
+  }
+  
+  /**
+   * Get cache statistics
+   */
+  getStats(): {
+    size: number;
+    speculative: number;
+    revocations: number;
+  } {
+    return {
+      size: this.cache.size,
+      speculative: Array.from(this.speculative.values()).flat().length,
+      revocations: this.revocations.size,
+    };
+  }
+}
+
+// ============================================================================
+// WARRANT ENGINE
+// ============================================================================
+
+export class WarrantEngine {
+  private key: CryptoKey | null = null;
+  private cache: WarrantCache;
+  private commitmentEngine: CommitmentEngine;
+  private eventLog: WarrantEvent[] = [];
+  private lastEventHash: Hash | null = null;
+  
+  constructor(commitmentEngine: CommitmentEngine) {
+    this.cache = new WarrantCache();
+    this.commitmentEngine = commitmentEngine;
+  }
+  
+  /**
+   * Initialize the engine with a seal key
+   */
+  async initialize(sealKey: string): Promise<void> {
+    this.key = await deriveKey(sealKey);
+  }
+  
+  /**
+   * Create a speculative warrant (pre-staged)
+   * WARRANT-INV-001: Expires in 60s if not activated
+   */
+  async createSpeculative(params: {
+    agent_id: string;
+    policy_id: string;
+    tier: WarrantTier;
+    constraints: WarrantConstraints;
+    duration_ms: number;
+    issued_by: string;
+  }): Promise<SpeculativeWarrant> {
+    if (!this.key) {
+      throw new Error('Engine not initialized. Call initialize() first.');
+    }
+    
+    const startTime = performance.now();
+    
+    const id = generateWarrantId();
+    const now = generateTimestamp();
+    const expiresAt = new Date(Date.now() + params.duration_ms).toISOString() as Timestamp;
+    const speculativeExpiresAt = new Date(Date.now() + 60000).toISOString() as Timestamp;
+    
+    // Pre-compute activation seal
+    const activationData = {
+      _v: 1,
+      id,
+      agent_id: params.agent_id,
+      activated: true,
+    };
+    const activationSeal = await hmacSeal(activationData, this.key);
+    
+    // Seal the warrant
+    const warrantData = {
+      _v: 1,
+      id,
+      agent_id: params.agent_id,
+      policy_id: params.policy_id,
+      state: 'SPECULATIVE',
+      tier: params.tier,
+      constraints: params.constraints,
+      created_at: now,
+      expires_at: expiresAt,
+      issued_by: params.issued_by,
+    };
+    const seal = await hmacSeal(warrantData, this.key);
+    
+    const warrant: SpeculativeWarrant = {
+      id,
+      agent_id: params.agent_id,
+      policy_id: params.policy_id,
+      state: 'SPECULATIVE',
+      tier: params.tier,
+      constraints: params.constraints,
+      created_at: now,
+      activated_at: null,
+      expires_at: expiresAt,
+      revoked_at: null,
+      issued_by: params.issued_by,
+      seal,
+      version: 'v3.0',
+      speculative_expires_at: speculativeExpiresAt,
+      activation_seal: activationSeal,
+    };
+    
+    // Cache for fast activation
+    this.cache.set(warrant);
+    
+    // Log event
+    await this.logEvent({
+      warrant_id: id,
+      event_type: 'created',
+      actor: { type: 'user', id: params.issued_by },
+      previous_state: 'DRAFT' as WarrantState,
+      new_state: 'SPECULATIVE',
+    });
+    
+    const elapsed = performance.now() - startTime;
+    if (elapsed > 10) {
+      console.warn(`Speculative warrant creation exceeded target: ${elapsed.toFixed(2)}ms`);
+    }
+    
+    return warrant;
+  }
+  
+  /**
+   * Activate a speculative warrant
+   * Target: <10ms (cache hit)
+   * WARRANT-INV-003: Immediately sealed (L1)
+   */
+  async activate(id: WarrantId): Promise<Warrant> {
+    if (!this.key) {
+      throw new Error('Engine not initialized. Call initialize() first.');
+    }
+    
+    const startTime = performance.now();
+    
+    // Try cache first
+    const cached = this.cache.get(id);
+    if (!cached) {
+      throw new Error(`Warrant not found or expired: ${id}`);
+    }
+    
+    if (cached.state !== 'SPECULATIVE') {
+      throw new Error(`Warrant not in SPECULATIVE state: ${cached.state}`);
+    }
+    
+    const specWarrant = cached as SpeculativeWarrant;
+    
+    // Check speculative expiry (WARRANT-INV-001)
+    if (new Date(specWarrant.speculative_expires_at) < new Date()) {
+      this.cache.revoke(id);
+      throw new Error('Speculative warrant expired (60s limit)');
+    }
+    
+    const now = generateTimestamp();
+    
+    // Create activated warrant
+    const activatedWarrant: Warrant = {
+      id: specWarrant.id,
+      agent_id: specWarrant.agent_id,
+      policy_id: specWarrant.policy_id,
+      state: 'ACTIVE',
+      tier: specWarrant.tier,
+      constraints: specWarrant.constraints,
+      created_at: specWarrant.created_at,
+      activated_at: now,
+      expires_at: specWarrant.expires_at,
+      revoked_at: null,
+      issued_by: specWarrant.issued_by,
+      seal: specWarrant.seal, // Original seal preserved
+      version: 'v3.0',
+    };
+    
+    // WARRANT-INV-003: Immediately seal via commitment layer
+    await this.commitmentEngine.commit(activatedWarrant, `warrant:${id}`);
+    
+    // Update cache
+    this.cache.set(activatedWarrant);
+    
+    // Log event
+    await this.logEvent({
+      warrant_id: id,
+      event_type: 'activated',
+      actor: { type: 'system', id: 'warrant-engine' },
+      previous_state: 'SPECULATIVE',
+      new_state: 'ACTIVE',
+    });
+    
+    const elapsed = performance.now() - startTime;
+    if (elapsed > 10) {
+      console.warn(`Warrant activation exceeded target: ${elapsed.toFixed(2)}ms`);
+    }
+    
+    return activatedWarrant;
+  }
+  
+  /**
+   * Revoke a warrant
+   * WARRANT-INV-002: Propagates to all caches within 100ms
+   */
+  async revoke(id: WarrantId, reason: string, actor: { type: 'user' | 'system'; id: string }): Promise<Warrant> {
+    if (!this.key) {
+      throw new Error('Engine not initialized. Call initialize() first.');
+    }
+    
+    const startTime = performance.now();
+    
+    const warrant = this.cache.get(id);
+    if (!warrant) {
+      throw new Error(`Warrant not found: ${id}`);
+    }
+    
+    if (warrant.state === 'REVOKED' || warrant.state === 'ARCHIVED') {
+      throw new Error(`Warrant already ${warrant.state}`);
+    }
+    
+    const previousState = warrant.state;
+    const now = generateTimestamp();
+    
+    // Create revoked warrant
+    const revokedWarrant: Warrant = {
+      ...warrant,
+      state: 'REVOKED',
+      revoked_at: now,
+      revocation_reason: reason,
+    };
+    
+    // Seal revocation
+    await this.commitmentEngine.commit(
+      { warrant_id: id, revoked_at: now, reason },
+      `revocation:${id}`
+    );
+    
+    // WARRANT-INV-002: Immediate cache revocation
+    this.cache.revoke(id);
+    
+    // Log event
+    await this.logEvent({
+      warrant_id: id,
+      event_type: 'revoked',
+      actor,
+      reason,
+      previous_state: previousState,
+      new_state: 'REVOKED',
+    });
+    
+    const elapsed = performance.now() - startTime;
+    if (elapsed > 100) {
+      console.warn(`Warrant revocation exceeded propagation target: ${elapsed.toFixed(2)}ms`);
+    }
+    
+    return revokedWarrant;
+  }
+  
+  /**
+   * Check if an action is authorized by warrant
+   * Returns matching warrant or null
+   */
+  async checkAuthorization(params: {
+    agent_id: string;
+    action: string;
+    amount?: number;
+    domain?: string;
+  }): Promise<Warrant | null> {
+    const startTime = performance.now();
+    
+    // Get speculative warrants for agent
+    const specWarrants = this.cache.getSpeculativeForAgent(params.agent_id);
+    
+    for (const warrant of specWarrants) {
+      // Check constraints
+      if (this.meetsConstraints(warrant.constraints, params)) {
+        // Activate on first matching warrant
+        const activated = await this.activate(warrant.id);
+        
+        const elapsed = performance.now() - startTime;
+        if (elapsed > 10) {
+          console.warn(`Authorization check exceeded target: ${elapsed.toFixed(2)}ms`);
+        }
+        
+        return activated;
+      }
+    }
+    
+    return null;
+  }
+  
+  /**
+   * Check if action meets warrant constraints
+   */
+  private meetsConstraints(
+    constraints: WarrantConstraints,
+    action: { amount?: number; domain?: string }
+  ): boolean {
+    // Check amount limit
+    if (constraints.maxAmount !== undefined && action.amount !== undefined) {
+      if (action.amount > constraints.maxAmount) {
+        return false;
+      }
+    }
+    
+    // Check domain allowlist
+    if (constraints.allowedDomains && action.domain) {
+      if (!constraints.allowedDomains.includes(action.domain)) {
+        return false;
+      }
+    }
+    
+    return true;
+  }
+  
+  /**
+   * Log a warrant event with hash chain
+   */
+  private async logEvent(params: {
+    warrant_id: WarrantId;
+    event_type: WarrantEvent['event_type'];
+    actor: WarrantEvent['actor'];
+    reason?: string;
+    previous_state: WarrantState;
+    new_state: WarrantState;
+  }): Promise<void> {
+    const timestamp = generateTimestamp();
+    
+    const event: WarrantEvent = {
+      warrant_id: params.warrant_id,
+      event_type: params.event_type,
+      timestamp,
+      actor: params.actor,
+      reason: params.reason,
+      previous_state: params.previous_state,
+      new_state: params.new_state,
+      hash: '' as Hash, // Will be computed
+      parent_hash: this.lastEventHash,
+    };
+    
+    // Compute event hash
+    event.hash = await sha256Object({
+      ...event,
+      hash: undefined, // Exclude from hash computation
+    });
+    
+    this.eventLog.push(event);
+    this.lastEventHash = event.hash;
+  }
+  
+  /**
+   * Get event log for a warrant
+   */
+  getEventLog(warrantId?: WarrantId): WarrantEvent[] {
+    if (warrantId) {
+      return this.eventLog.filter(e => e.warrant_id === warrantId);
+    }
+    return [...this.eventLog];
+  }
+  
+  /**
+   * Get cache statistics
+   */
+  getCacheStats(): ReturnType<WarrantCache['getStats']> {
+    return this.cache.getStats();
+  }
+}
+
+// ============================================================================
+// TIER DEFINITIONS
+// ============================================================================
+
+export const TIER_LIMITS: Record<WarrantTier, {
+  maxExposure: number;
+  maxCalls: number;
+  requiresApproval: boolean;
+}> = {
+  T1: {
+    maxExposure: 1000,
+    maxCalls: 100,
+    requiresApproval: false,
+  },
+  T2: {
+    maxExposure: 100000,
+    maxCalls: 1000,
+    requiresApproval: false,
+  },
+  T3: {
+    maxExposure: Infinity,
+    maxCalls: Infinity,
+    requiresApproval: true,
+  },
+};