@longarc/mdash 3.1.1 → 3.1.3

package/src/core/commitment.ts

@@ -1,9 +1,9 @@
 /**
  * mdash v3.0 - Commitment Layer (L1)
- * 
+ *
  * Sub-millisecond cryptographic commitments.
  * "The seal races the attack."
- * 
+ *
  * Target Latency:
  * - Commitment seal: <0.5ms P50, <1ms P99
  * - Merkle proof: <0.1ms
@@ -21,12 +21,24 @@ import {
   deriveKey,
   generateTimestamp,
   constantTimeEqual,
-} from './crypto';
+} from './crypto.js';
 
 // ============================================================================
 // COMMITMENT TYPES
 // ============================================================================
 
+/**
+ * L1 Verification Modes
+ *
+ * - 'claim': Agent self-reports. Cost: Minimal, Trust: Low.
+ *   Uses _v:1 seal (backwards-compatible with all existing commitments).
+ * - 'verified': Inference verification via locality-sensitive hashing.
+ *   Cost: Moderate, Trust: Medium. Uses _v:2 seal.
+ * - 'witnessed': Third-party Warden observes and co-signs.
+ *   Cost: Higher, Trust: High. Uses _v:2 seal.
+ */
+export type VerificationMode = 'claim' | 'verified' | 'witnessed';
+
 export interface Commitment {
   /** Unique commitment identifier */
   id: string;
@@ -39,7 +51,11 @@ export interface Commitment {
   /** HMAC seal binding id + hash + timestamp */
   seal: Seal;
   /** Protocol version for upgrade path */
-  version: 'v3.0';
+  version: 'v3.0' | 'v3.1';
+  /** L1 verification mode (absent on v3.0 commitments, defaults to 'claim') */
+  verification_mode?: VerificationMode;
+  /** Verification evidence: LSH digest for 'verified', witness seal for 'witnessed' */
+  verification_proof?: Hash;
 }
 
 export interface CommitmentProof {
@@ -68,28 +84,28 @@ export class IncrementalMerkleTree {
   private leaves: Hash[] = [];
   private levels: Hash[][] = [];
   private readonly maxDepth: number;
-  
+
   constructor(maxDepth: number = 20) {
     this.maxDepth = maxDepth;
   }
-  
+
   /**
    * Add a leaf to the tree
    * O(log n) operation
    */
   async addLeaf(hash: Hash): Promise<number> {
     const index = this.leaves.length;
-    
+
     if (index >= Math.pow(2, this.maxDepth)) {
       throw new Error(`Tree capacity exceeded: max ${Math.pow(2, this.maxDepth)} leaves`);
     }
-    
+
     this.leaves.push(hash);
     await this.updatePath(index);
-    
+
     return index;
   }
-  
+
   /**
    * Update the Merkle path for a new leaf
    * Incrementally updates only affected nodes
@@ -101,30 +117,30 @@ export class IncrementalMerkleTree {
     }
     let currentHash: Hash = leafHash;
     let currentIndex = leafIndex;
-    
+
     for (let level = 0; level < this.maxDepth; level++) {
       const levelArray = this.levels[level] ?? (this.levels[level] = []);
-      
+
       const siblingIndex = currentIndex ^ 1; // XOR to get sibling
       const parentIndex = currentIndex >> 1; // Divide by 2
-      
+
       // Get sibling hash (empty hash if doesn't exist)
       const siblingHash: Hash = levelArray[siblingIndex] ?? await sha256('');
-      
+
       // Store current hash at this level
       levelArray[currentIndex] = currentHash;
-      
+
       // Compute parent hash
       if (currentIndex % 2 === 0) {
         currentHash = await rollingHash([currentHash, siblingHash]);
       } else {
         currentHash = await rollingHash([siblingHash, currentHash]);
       }
-      
+
       currentIndex = parentIndex;
     }
   }
-  
+
   /**
    * Get the current root hash
    */
@@ -132,12 +148,12 @@ export class IncrementalMerkleTree {
     if (this.leaves.length === 0) {
       return sha256('empty');
     }
-    
+
     // Root is at the top level
     const topLevel = this.levels[this.maxDepth - 1];
     return topLevel?.[0] || await sha256('');
   }
-  
+
   /**
    * Generate Merkle proof for a leaf
    * O(log n) operation
@@ -146,26 +162,26 @@ export class IncrementalMerkleTree {
     if (leafIndex < 0 || leafIndex >= this.leaves.length) {
       throw new Error(`Invalid leaf index: ${leafIndex}`);
     }
-    
+
     const path: MerklePathNode[] = [];
     let currentIndex = leafIndex;
-    
+
     for (let level = 0; level < this.maxDepth; level++) {
       const siblingIndex = currentIndex ^ 1;
       const levelArray = this.levels[level];
       const siblingHash: Hash = levelArray?.[siblingIndex] ?? await sha256('');
-      
+
       path.push({
         hash: siblingHash,
         position: currentIndex % 2 === 0 ? 'right' : 'left',
       });
-      
+
       currentIndex = currentIndex >> 1;
     }
-    
+
     return path;
   }
-  
+
   /**
    * Verify a Merkle proof
    * O(log n) operation
@@ -176,7 +192,7 @@ export class IncrementalMerkleTree {
     expectedRoot: Hash
   ): Promise<boolean> {
     let currentHash = leafHash;
-    
+
     for (const node of proof) {
       if (node.position === 'left') {
         currentHash = await rollingHash([node.hash, currentHash]);
@@ -184,10 +200,10 @@ export class IncrementalMerkleTree {
         currentHash = await rollingHash([currentHash, node.hash]);
       }
     }
-    
+
     return constantTimeEqual(currentHash, expectedRoot);
   }
-  
+
   /**
    * Get tree statistics
    */
@@ -208,92 +224,138 @@ export class CommitmentEngine {
   private key: CryptoKey | null = null;
   private tree: IncrementalMerkleTree;
   private commitments: Map<string, Commitment> = new Map();
-  
+
   constructor(maxTreeDepth: number = 20) {
     this.tree = new IncrementalMerkleTree(maxTreeDepth);
   }
-  
+
   /**
    * Initialize the engine with a seal key
    */
   async initialize(sealKey: string): Promise<void> {
     this.key = await deriveKey(sealKey);
   }
-  
+
   /**
    * Create a commitment for content
    * Target: <0.5ms P50, <1ms P99
+   *
+   * @param content - The content to commit
+   * @param id - Unique commitment identifier
+   * @param options - Optional verification mode configuration
    */
-  async commit<T>(content: T, id: string): Promise<Commitment> {
+  async commit<T>(content: T, id: string, options?: {
+    mode?: VerificationMode;
+    verificationProof?: Hash;
+  }): Promise<Commitment> {
     if (!this.key) {
       throw new Error('Engine not initialized. Call initialize() first.');
     }
-    
+
+    const mode = options?.mode ?? 'claim';
+    const verificationProof = options?.verificationProof;
+
+    // Runtime guard: validate mode is a known value (TypeScript types erased at runtime)
+    const VALID_MODES: readonly VerificationMode[] = ['claim', 'verified', 'witnessed'];
+    if (!VALID_MODES.includes(mode)) {
+      throw new Error('Invalid verification mode');
+    }
+
+    // Validate: 'verified' and 'witnessed' modes require proof
+    if (mode !== 'claim' && !verificationProof) {
+      throw new Error('Enhanced verification mode requires a verification_proof');
+    }
+
     const startTime = performance.now();
-    
+
     // Hash the content
     const contentHash = await sha256Object(content);
     const timestamp = generateTimestamp();
-    
-    // Create the commitment record
-    const commitmentData = {
-      _v: 1, // Protocol version for upgrade path
+
+    // Seal computation bifurcates on mode:
+    // - 'claim' uses _v:1 (exact backwards compatibility)
+    // - 'verified'/'witnessed' use _v:2 (includes verification fields)
+    const isEnhanced = mode !== 'claim';
+
+    const commitmentData = isEnhanced ? {
+      _v: 2,
+      id,
+      content_hash: contentHash,
+      committed_at: timestamp,
+      verification_mode: mode,
+      verification_proof: verificationProof,
+    } : {
+      _v: 1, // Preserved exactly -- existing seals remain valid
       id,
       content_hash: contentHash,
       committed_at: timestamp,
     };
-    
+
     // Seal the commitment
     const seal = await hmacSeal(commitmentData, this.key);
-    
+
     const commitment: Commitment = {
       id,
       operationId: id,
       content_hash: contentHash,
       committed_at: timestamp,
       seal,
-      version: 'v3.0',
+      version: isEnhanced ? 'v3.1' : 'v3.0',
+      ...(isEnhanced ? {
+        verification_mode: mode,
+        verification_proof: verificationProof,
+      } : {}),
     };
-    
+
     // Add to Merkle tree
     await this.tree.addLeaf(contentHash);
-    
+
     // Store commitment
     this.commitments.set(id, commitment);
-    
+
     const elapsed = performance.now() - startTime;
     if (elapsed > 1) {
       console.warn(`Commitment latency exceeded P99: ${elapsed.toFixed(2)}ms`);
     }
-    
+
     return commitment;
   }
-  
+
   /**
    * Get a commitment by ID
    */
   getCommitment(id: string): Commitment | undefined {
     return this.commitments.get(id);
   }
-  
+
   /**
    * Verify a commitment
+   * Handles both _v:1 (claim) and _v:2 (verified/witnessed) seal formats
    */
   async verify(commitment: Commitment): Promise<boolean> {
     if (!this.key) {
       throw new Error('Engine not initialized. Call initialize() first.');
     }
-    
-    const commitmentData = {
+
+    const isEnhanced = commitment.verification_mode && commitment.verification_mode !== 'claim';
+
+    const commitmentData = isEnhanced ? {
+      _v: 2,
+      id: commitment.id,
+      content_hash: commitment.content_hash,
+      committed_at: commitment.committed_at,
+      verification_mode: commitment.verification_mode,
+      verification_proof: commitment.verification_proof,
+    } : {
       _v: 1,
       id: commitment.id,
       content_hash: commitment.content_hash,
       committed_at: commitment.committed_at,
     };
-    
+
     return hmacVerify(commitmentData, commitment.seal, this.key);
   }
-  
+
   /**
    * Generate a proof for a commitment
    */
@@ -302,13 +364,13 @@ export class CommitmentEngine {
     if (!commitment) {
       throw new Error(`Commitment not found: ${id}`);
     }
-    
+
     // Find leaf index
     const leafIndex = Array.from(this.commitments.keys()).indexOf(id);
-    
+
     const merkle_path = await this.tree.getProof(leafIndex);
     const root_hash = await this.tree.getRoot();
-    
+
     return {
       commitment,
       merkle_path,
@@ -316,7 +378,7 @@ export class CommitmentEngine {
       leaf_index: leafIndex,
     };
   }
-  
+
   /**
    * Verify a proof
    */
@@ -326,7 +388,7 @@ export class CommitmentEngine {
     if (!commitmentValid) {
       return false;
     }
-    
+
     // Then verify the Merkle path
     return IncrementalMerkleTree.verifyProof(
       proof.commitment.content_hash,
@@ -334,14 +396,14 @@ export class CommitmentEngine {
       proof.root_hash
     );
   }
-  
+
   /**
    * Get the current Merkle root
    */
   async getRoot(): Promise<Hash> {
     return this.tree.getRoot();
   }
-  
+
   /**
    * Get statistics
    */
@@ -371,7 +433,7 @@ export interface LatencyMetrics {
 export class LatencyMonitor {
   private metrics: Map<string, number[]> = new Map();
   private thresholds: Map<string, { p50: number; p99: number }> = new Map();
-  
+
   constructor() {
     // Default thresholds from v3.0 spec
     this.thresholds.set('commitment_seal', { p50: 0.5, p99: 1 });
@@ -379,7 +441,7 @@ export class LatencyMonitor {
     this.thresholds.set('context_chunk_seal', { p50: 2, p99: 5 });
     this.thresholds.set('checkpoint_create', { p50: 0.5, p99: 1 });
   }
-  
+
   /**
    * Record a latency sample
    */
@@ -389,7 +451,7 @@ export class LatencyMonitor {
     }
     this.metrics.get(operation)!.push(latencyMs);
   }
-  
+
   /**
    * Get metrics for an operation
    */
@@ -398,15 +460,15 @@ export class LatencyMonitor {
     if (!samples || samples.length === 0) {
       return null;
     }
-    
+
     const sorted = [...samples].sort((a, b) => a - b);
     const p50Index = Math.floor(sorted.length * 0.5);
     const p99Index = Math.floor(sorted.length * 0.99);
-    
+
     const threshold = this.thresholds.get(operation);
     const p50 = sorted[p50Index] ?? 0;
     const p99 = sorted[p99Index] ?? 0;
-    
+
     return {
       operation,
       p50_ms: p50,
@@ -415,21 +477,21 @@ export class LatencyMonitor {
       breaches: threshold ? samples.filter(s => s > threshold.p99).length : 0,
     };
   }
-  
+
   /**
    * Check if operation is within SLA
    */
   isWithinSLA(operation: string): boolean {
     const metrics = this.getMetrics(operation);
     const threshold = this.thresholds.get(operation);
-    
+
     if (!metrics || !threshold) {
       return true;
     }
-    
+
     return metrics.p99_ms <= threshold.p99;
   }
-  
+
   /**
    * Clear metrics
    */

package/src/core/crypto.ts

@@ -137,6 +137,12 @@ export async function rollingHash(hashes: Hash[]): Promise<Hash> {
  */
 export function deterministicStringify(obj: unknown): string {
   return JSON.stringify(obj, (_, value) => {
+    // SA-2026-NFC: Normalize Unicode strings to NFC so visually identical
+    // codepoint sequences (e.g. e + combining accent vs precomposed e)
+    // produce identical hashes.
+    if (typeof value === 'string') {
+      return value.normalize('NFC');
+    }
     if (value && typeof value === 'object' && !Array.isArray(value)) {
       return Object.keys(value)
         .sort()
@@ -159,8 +165,15 @@ const HKDF_INFO = 'mdash-seal-v3';
 /**
  * Derive an HMAC key from a master key using HKDF
  * The derived key is non-extractable
+ * 
+ * SECURITY: Requires minimum key length of 32 characters
  */
 export async function deriveKey(masterKey: string): Promise<CryptoKey> {
+  // P5 SECURITY: Enforce minimum key length
+  if (!masterKey || masterKey.length < 32) {
+    throw new Error('Seal key must be at least 32 characters');
+  }
+  
   const subtle = getSubtleCrypto();
   const encoder = new TextEncoder();
   

package/src/index.ts

@@ -3,16 +3,15 @@
  *
  * "The best defense is the fastest seal."
  *
- * Accountability infrastructure for autonomous AI agents.
- * Cryptographic attestation at execution speed.
- *
- * mdash proves. Kiwi runs. Eclair reveals. Roux holds. The Warden reasons.
+ * Cryptographic attestation protocol for autonomous AI agents.
+ * Cryptographic sealing at execution speed.
  *
  * Architecture:
  * - L1: Commitment Layer (<1ms)
  * - L2: TEE Attestation (<10ms)
  * - L3: ZK Proofs (async)
  * - MCCA: Manifold-Constrained Context Architecture
+ * - Context Module (formerly Caret v0.2.0)
  *
  * @version 3.1.0
  * @author Long Arc Studios
@@ -34,8 +33,22 @@ export * from './tee/engine.js';
 // Re-export L3 ZK Proofs
 export * from './zk/engine.js';
 
+// Re-export Provenance
+export * from './provenance/index.js';
+
+// Re-export Accountability Engine (consumer API: warrants + commitments)
+export { AccountabilityEngine } from './accountability/engine.js';
+export type {
+  ActionResult,
+  AuditRecord,
+  AuditSummary,
+  WarrantPermissions,
+  Violation,
+  ViolationType,
+} from './accountability/types.js';
+
 // Re-export MCCA v3 (excluding SourceClass which is already exported from context)
-export { 
+export {
   MCCAEngine,
   ManifoldRegion,
   InfluenceBudget,
@@ -45,6 +58,26 @@ export {
   DEFAULT_CONFIG as MCCA_DEFAULT_CONFIG
 } from './mcca/engine.js';
 
+// ============================================================================
+// CONTEXT MODULE (formerly Caret v0.2.0)
+// ============================================================================
+
+export * as context from './context/index.js';
+
+// Convenience re-exports for common context types
+export type {
+  ContextFragment as CaretFragment,
+  InfluenceBudget as CaretInfluenceBudget,
+  Manifold,
+  Outcome,
+} from './context/types.js';
+
+export {
+  requireInfluence,
+  requireMCCA,
+  createContext,
+} from './context/index.js';
+
 // Import for runtime
 import { CommitmentEngine, LatencyMonitor, Commitment } from './core/commitment.js';
 import { WarrantEngine, WarrantTier, WarrantConstraints, Warrant } from './warrant/engine.js';
@@ -157,7 +190,12 @@ export class MdashProtocol {
     };
     
     const warrant = await this.warrant.checkAuthorization(authParams);
-    if (!warrant) throw new Error(`No valid warrant for agent ${params.agentId}`);
+    if (!warrant) {
+      // P3 SECURITY: Generic error message prevents enumeration attacks
+      // Internal logging should capture specifics
+      console.warn(`[AUTH] Authorization denied for agent ${params.agentId}, action ${params.action}`);
+      throw new Error('Authorization denied');
+    }
     
     const startCheckpoint = await this.checkpoint.onActionStart({
       agent_id: params.agentId,
@@ -181,9 +219,10 @@ export class MdashProtocol {
         agent_id: params.agentId,
         warrant_id: warrant.id,
         action: params.action,
-        error: `Physics validation failed`,
+        error: `Physics validation failed: ${validation.violations.map(v => v.type).join(', ')}`,
       });
-      throw new Error(`Physics validation failed`);
+      // P3 SECURITY: Generic error to user, details logged in checkpoint
+      throw new Error('Authorization denied');
     }
     
     const { attestation } = await this.bridge.commitAndAttest(
@@ -191,6 +230,19 @@ export class MdashProtocol {
       `action:${params.agentId}:${Date.now()}`
     );
     
+    // P1 SECURITY: Re-validate warrant immediately before execution
+    // Closes TOCTOU window between initial authorization and action execution
+    // A revocation could have propagated during physics validation and attestation
+    if (this.warrant.isRevoked(warrant.id)) {
+      await this.checkpoint.onError({
+        agent_id: params.agentId,
+        warrant_id: warrant.id,
+        action: params.action,
+        error: 'Warrant revoked during execution flow',
+      });
+      throw new Error('Authorization denied');
+    }
+    
     let result: T;
     try {
       result = await params.execute();
@@ -307,13 +359,13 @@ export function createMdash(config: MdashConfig): MdashProtocol {
 export const VERSION = {
   protocol: '3.1.0',
   codename: 'Context Unification',
-  releaseDate: '2026-03',
+  releaseDate: '2026-01',
   features: [
     'L1 Commitment Layer (<1ms)',
     'L2 TEE Attestation (AWS Nitro/SGX, <10ms)',
     'L3 ZK Proofs (Plonky2, async)',
     'MCCA v3 (Manifold-Constrained Context Architecture)',
-    'Context Module (unified context primitives)',
+    'Context Module (formerly Caret v0.2.0)',
     'Speculative Warrant Issuance (<10ms activation)',
     'Event-driven Checkpoints',
     'Incremental Merkle Sealing',

package/src/mcca/engine.ts

@@ -393,9 +393,10 @@ export class MCCAEngine {
     const fragment = this.fragments.get(id);
     if (!fragment) return;
 
-    // Update totals
-    this.totalTokens -= fragment.token_count;
-    this.influenceBySource[fragment.source_class] -= fragment.influence;
+    // Update totals (SA-2026-012: floor guard prevents floating-point underflow)
+    this.totalTokens = Math.max(0, this.totalTokens - fragment.token_count);
+    this.influenceBySource[fragment.source_class] =
+      Math.max(0, this.influenceBySource[fragment.source_class] - fragment.influence);
 
     // Remove from indices
     const regionIds = this.fragmentsByRegion.get(fragment.region) || [];
@@ -473,7 +474,7 @@ export class MCCAEngine {
 
     // Commit to L1
     const commitment = await this.commitmentEngine.commit(proofData, `mcca-proof:${id}`);
-    proofData.commitment_id = commitment.operationId;
+    proofData.commitment_id = commitment.id;
 
     const seal = await hmacSeal(proofData, this.key);