@longarc/mdash 3.1.2 → 3.1.3

package/src/accountability/engine.ts

@@ -0,0 +1,230 @@
+/**
+ * mdash v3.1 — AccountabilityEngine
+ *
+ * Unified consumer API: warrants + commitments in one class.
+ * Composes CommitmentEngine (attestation) and WarrantEngine (warrant lifecycle).
+ *
+ * Consumer story: import { AccountabilityEngine } from '@longarc/mdash'
+ * One class, full accountability lifecycle.
+ */
+
+import { CommitmentEngine } from '../core/commitment.js';
+import type { Commitment } from '../core/commitment.js';
+import { WarrantEngine } from '../warrant/engine.js';
+import type { WarrantId } from '../core/crypto.js';
+import type {
+  WarrantPermissions,
+  Violation,
+  ViolationType,
+  ActionResult,
+  AuditRecord,
+  AuditSummary,
+} from './types.js';
+
+interface ManagedWarrant {
+  agentId: string;
+  permissions: WarrantPermissions;
+  issuedAt: number;
+  status: 'ACTIVE' | 'EXPIRED' | 'REVOKED';
+  executionCount: number;
+  infraWarrantId: WarrantId;
+}
+
+export class AccountabilityEngine {
+  private commitmentEngine: CommitmentEngine;
+  private warrantEngine: WarrantEngine;
+  private managedWarrants: Map<string, ManagedWarrant> = new Map();
+  private auditLog: AuditRecord[] = [];
+  private actionCounters: Map<string, number> = new Map();
+
+  constructor() {
+    this.commitmentEngine = new CommitmentEngine();
+    this.warrantEngine = new WarrantEngine(this.commitmentEngine);
+  }
+
+  async initialize(sealKey: string): Promise<void> {
+    await this.commitmentEngine.initialize(sealKey);
+    await this.warrantEngine.initialize(sealKey);
+  }
+
+  async issueWarrant(agentId: string, permissions: WarrantPermissions): Promise<void> {
+    // Create a crypto-sealed infrastructure warrant via WarrantEngine
+    const speculative = await this.warrantEngine.createSpeculative({
+      agent_id: agentId,
+      policy_id: 'accountability-default',
+      tier: 'T1',
+      constraints: {
+        maxCalls: permissions.maxExecutions,
+      },
+      duration_ms: permissions.ttlMs,
+      issued_by: 'accountability-engine',
+    });
+
+    // Activate immediately — consumer warrants are active on issuance
+    const activated = await this.warrantEngine.activate(speculative.id);
+
+    this.managedWarrants.set(agentId, {
+      agentId,
+      permissions,
+      issuedAt: Date.now(),
+      status: 'ACTIVE',
+      executionCount: 0,
+      infraWarrantId: activated.id,
+    });
+  }
+
+  revokeWarrant(agentId: string): void {
+    const managed = this.managedWarrants.get(agentId);
+    if (!managed) return;
+
+    managed.status = 'REVOKED';
+
+    // Best-effort infrastructure-level revocation (fire-and-forget)
+    this.warrantEngine
+      .revoke(managed.infraWarrantId, 'Consumer API revocation', {
+        type: 'system',
+        id: 'accountability-engine',
+      })
+      .catch(() => {
+        // Infra warrant may have already expired from cache — local state is authoritative
+      });
+  }
+
+  async executeAction(
+    agentId: string,
+    action: string,
+    params: unknown,
+  ): Promise<ActionResult> {
+    const managed = this.managedWarrants.get(agentId);
+
+    // No warrant issued for this agent
+    if (!managed) {
+      return this.deny(agentId, action, 'NO_WARRANT', `No warrant found for agent '${agentId}'`);
+    }
+
+    // Check infrastructure-level revocation (propagates across caches)
+    if (this.warrantEngine.isRevoked(managed.infraWarrantId)) {
+      managed.status = 'REVOKED';
+    }
+
+    // Revoked
+    if (managed.status === 'REVOKED') {
+      return this.deny(
+        agentId, action, 'WARRANT_REVOKED',
+        `Warrant for agent '${agentId}' has been revoked`,
+        managed.infraWarrantId,
+      );
+    }
+
+    // Expired
+    if (Date.now() - managed.issuedAt > managed.permissions.ttlMs) {
+      managed.status = 'EXPIRED';
+      return this.deny(
+        agentId, action, 'WARRANT_EXPIRED',
+        `Warrant for agent '${agentId}' has expired`,
+        managed.infraWarrantId,
+      );
+    }
+
+    // Execution limit
+    if (
+      managed.permissions.maxExecutions !== undefined &&
+      managed.executionCount >= managed.permissions.maxExecutions
+    ) {
+      return this.deny(
+        agentId, action, 'EXECUTION_LIMIT_REACHED',
+        `Agent '${agentId}' has reached execution limit of ${managed.permissions.maxExecutions}`,
+        managed.infraWarrantId,
+      );
+    }
+
+    // Forbidden action (explicit deny takes precedence)
+    if (managed.permissions.forbiddenActions.includes(action)) {
+      return this.deny(
+        agentId, action, 'FORBIDDEN_ACTION',
+        `Action '${action}' is explicitly forbidden for agent '${agentId}'`,
+        managed.infraWarrantId,
+      );
+    }
+
+    // Not in allowed list
+    if (!managed.permissions.allowedActions.includes(action)) {
+      return this.deny(
+        agentId, action, 'UNAUTHORIZED_ACTION',
+        `Action '${action}' is not in the allowed list for agent '${agentId}'`,
+        managed.infraWarrantId,
+      );
+    }
+
+    // ── AUTHORIZED — commit attestation ──
+
+    managed.executionCount++;
+
+    const count = (this.actionCounters.get(agentId) || 0) + 1;
+    this.actionCounters.set(agentId, count);
+    const commitId = `${agentId}-action-${count}`;
+
+    const commitment = await this.commitmentEngine.commit(
+      { agentId, action, params, timestamp: Date.now() },
+      commitId,
+    );
+
+    const verified = await this.commitmentEngine.verify(commitment);
+
+    this.auditLog.push({
+      type: 'ATTESTED_ACTION',
+      agentId,
+      action,
+      timestamp: Date.now(),
+      commitId,
+      contentHash: commitment.content_hash,
+      verified,
+      warrantId: managed.infraWarrantId,
+    });
+
+    return { executed: true, commitment, verified };
+  }
+
+  getAuditSummary(): AuditSummary {
+    const authorized = this.auditLog.filter(r => r.type === 'ATTESTED_ACTION').length;
+    const denied = this.auditLog.filter(r => r.type !== 'ATTESTED_ACTION').length;
+    return {
+      total: this.auditLog.length,
+      authorized,
+      denied,
+      log: [...this.auditLog],
+    };
+  }
+
+  async verifyCommitment(commitment: Commitment): Promise<boolean> {
+    return this.commitmentEngine.verify(commitment);
+  }
+
+  private deny(
+    agentId: string,
+    action: string,
+    type: ViolationType,
+    detail: string,
+    warrantId?: WarrantId,
+  ): ActionResult {
+    const violation: Violation = {
+      type,
+      agentId,
+      action,
+      timestamp: Date.now(),
+      detail,
+      warrantId,
+    };
+
+    this.auditLog.push({
+      type,
+      agentId,
+      action,
+      timestamp: Date.now(),
+      detail,
+      warrantId,
+    });
+
+    return { executed: false, violation };
+  }
+}

package/src/accountability/types.ts

@@ -0,0 +1,58 @@
+/**
+ * mdash v3.1 — Accountability Engine Types
+ *
+ * Consumer-facing types for the unified accountability API.
+ * Warrants + Commitments in a single lifecycle.
+ */
+
+import type { Commitment } from '../core/commitment.js';
+
+export interface WarrantPermissions {
+  allowedActions: string[];
+  forbiddenActions: string[];
+  ttlMs: number;
+  maxExecutions?: number;
+}
+
+export type ViolationType =
+  | 'FORBIDDEN_ACTION'
+  | 'UNAUTHORIZED_ACTION'
+  | 'WARRANT_EXPIRED'
+  | 'WARRANT_REVOKED'
+  | 'EXECUTION_LIMIT_REACHED'
+  | 'NO_WARRANT';
+
+export interface Violation {
+  type: ViolationType;
+  agentId: string;
+  action: string;
+  timestamp: number;
+  detail: string;
+  warrantId?: string;
+}
+
+export interface ActionResult {
+  executed: boolean;
+  commitment?: Commitment;
+  verified?: boolean;
+  violation?: Violation;
+}
+
+export interface AuditRecord {
+  type: 'ATTESTED_ACTION' | ViolationType;
+  agentId: string;
+  action: string;
+  timestamp: number;
+  commitId?: string;
+  contentHash?: string;
+  verified?: boolean;
+  detail?: string;
+  warrantId?: string;
+}
+
+export interface AuditSummary {
+  total: number;
+  authorized: number;
+  denied: number;
+  log: AuditRecord[];
+}

package/src/checkpoint/engine.ts

@@ -315,6 +315,10 @@ export class CheckpointEngine {
     this.commitmentEngine.commit(checkpoint, commitmentId).then(() => {
       checkpoint.commitment_id = commitmentId;
       checkpoint.status = 'sealed';
+    }).catch((error) => {
+      // SA-2026-010: Log commitment failures instead of silently swallowing
+      checkpoint.status = 'failed';
+      console.error(`[Checkpoint] L1 commit failed for ${id}: ${error}`);
     });
     
     // Store and index