@longarc/mdash 3.1.1 → 3.1.3

package/src/provenance/provenance-engine.ts

@@ -0,0 +1,387 @@
+/**
+ * mdash v3.1 - Provenance Engine
+ *
+ * Create identity attestations, build provenance chains, verify model provenance.
+ *
+ * Design Invariants:
+ * PROVENANCE-INV-001: Identity attestation is immutable after creation.
+ * PROVENANCE-INV-002: Provenance chain hash changes if ANY component changes.
+ * PROVENANCE-INV-003: Verdict is deterministic: same chain = same verdict.
+ * PROVENANCE-INV-004: ZK proof verifies without access to the chain data.
+ * PROVENANCE-INV-005: A model with no identity attestation has verdict.isComplete = false.
+ * PROVENANCE-INV-006: Distilled models cannot produce valid provider signatures.
+ * PROVENANCE-INV-007: Chain attestation (L1 hash) includes identity + warrants + behavior.
+ */
+
+import {
+  sha256,
+  sha256Object,
+  rollingHash,
+  deterministicStringify,
+  generateTimestamp,
+  type Hash,
+  type Timestamp,
+} from '../core/crypto.js';
+
+import type {
+  ModelIdentityAttestation,
+  ProvenanceChain,
+  ProvenanceQuery,
+  ProvenanceResponse,
+  GlossEntry,
+} from './types.js';
+
+/**
+ * Drift report shape accepted by the provenance engine.
+ * Matches the DriftReport from Kiwi's defense module.
+ */
+export interface DriftReportInput {
+  compositeScore: number;
+  recommendation: string;
+}
+
+export class ProvenanceEngine {
+  private identities: Map<string, ModelIdentityAttestation> = new Map();
+  private chains: Map<string, ProvenanceChain> = new Map();
+
+  /**
+   * Create a model identity attestation.
+   *
+   * Called when a model is deployed. Seals the model's identity and
+   * constraints into an L1 commitment. The attestation becomes the
+   * anchor for the provenance chain.
+   */
+  async createIdentityAttestation(
+    model: ModelIdentityAttestation['model'],
+    constraints: ModelIdentityAttestation['constraints'],
+    deployment: ModelIdentityAttestation['deployment']
+  ): Promise<ModelIdentityAttestation> {
+    // Validate required fields
+    if (!model.name || typeof model.name !== 'string') {
+      throw new Error('Model name is required');
+    }
+    if (!model.version || typeof model.version !== 'string') {
+      throw new Error('Model version is required');
+    }
+    if (!model.provider || typeof model.provider !== 'string') {
+      throw new Error('Model provider is required');
+    }
+    if (!deployment.environment || typeof deployment.environment !== 'string') {
+      throw new Error('Deployment environment is required');
+    }
+
+    // Deterministic attestation ID from model + constraints + deployment
+    const idInput = deterministicStringify({ model, constraints, deployment });
+    const id = await sha256(idInput);
+
+    // Canonical form for L1 commitment
+    const canonicalData = deterministicStringify({
+      id,
+      model,
+      constraints,
+      deployment,
+    });
+    const l1Hash = await sha256(canonicalData);
+
+    // Provider signature (simulated -- real HSM in production)
+    const signatureInput = deterministicStringify({ l1Hash, provider: model.provider });
+    const providerSignature = await sha256(signatureInput);
+
+    const timestamp = generateTimestamp();
+
+    const attestation: ModelIdentityAttestation = {
+      id,
+      model,
+      constraints,
+      deployment,
+      attestation: {
+        l1Hash,
+        timestamp,
+        providerSignature,
+      },
+    };
+
+    // Store (INV-001: immutable after creation -- we never overwrite)
+    const key = `${model.name}:${model.version}`;
+    if (!this.identities.has(key)) {
+      this.identities.set(key, attestation);
+    }
+
+    return attestation;
+  }
+
+  /**
+   * Build a provenance chain for a model.
+   *
+   * Aggregates identity, warrant history, behavioral record, and
+   * drift assessment into a single verifiable chain.
+   */
+  async buildProvenanceChain(
+    identity: ModelIdentityAttestation,
+    warrantHashes: string[],
+    glossEntries: GlossEntry[],
+    driftReport?: DriftReportInput
+  ): Promise<ProvenanceChain> {
+    // Verify identity attestation hash (INV-001)
+    const canonicalData = deterministicStringify({
+      id: identity.id,
+      model: identity.model,
+      constraints: identity.constraints,
+      deployment: identity.deployment,
+    });
+    const expectedHash = await sha256(canonicalData);
+    if (expectedHash !== identity.attestation.l1Hash) {
+      throw new Error('Identity attestation hash mismatch: attestation may have been tampered with');
+    }
+
+    // Build warrant history summary
+    const activeWarrants = warrantHashes.length;
+    const revokedWarrants = 0; // In production, would filter by status
+    const warrantChainHash = warrantHashes.length > 0
+      ? await rollingHash(warrantHashes as Hash[])
+      : await sha256('empty-warrant-chain');
+
+    const warrantHistory = {
+      totalWarrants: warrantHashes.length,
+      activeWarrants,
+      revokedWarrants,
+      warrantChainHash,
+    };
+
+    // Build behavioral summary from GLOSS entries
+    const sessions = new Set(glossEntries.map(e => e.sessionId));
+    const violations = glossEntries.filter(e => e.isViolation).length;
+
+    const behavioralRecord: ProvenanceChain['behavioralRecord'] = {
+      totalSessions: sessions.size,
+      totalActions: glossEntries.length,
+      violations,
+    };
+
+    if (driftReport) {
+      behavioralRecord.latestDriftReport = {
+        compositeScore: driftReport.compositeScore,
+        recommendation: driftReport.recommendation,
+      };
+    }
+
+    // Compute verdict (INV-003: deterministic)
+    const flags: string[] = [];
+    let confidence = 1.0;
+
+    const hasIdentity = !!identity.id;
+    const hasWarrants = warrantHashes.length > 0;
+    const hasBehavior = glossEntries.length > 0;
+
+    if (!hasWarrants) {
+      flags.push('warrant_gap');
+      confidence -= 0.3;
+    }
+
+    if (!hasBehavior) {
+      flags.push('no_behavior');
+      confidence -= 0.2;
+    }
+
+    if (driftReport && driftReport.compositeScore > 0.5) {
+      flags.push('drift_detected');
+      confidence -= driftReport.compositeScore * 0.3;
+    }
+
+    if (violations > 0) {
+      const violationRatio = violations / Math.max(glossEntries.length, 1);
+      if (violationRatio > 0.1) {
+        flags.push('high_violation_rate');
+        confidence -= violationRatio * 0.4;
+      }
+    }
+
+    confidence = Math.max(0, Math.min(1, confidence));
+
+    const isComplete = hasIdentity && hasWarrants && hasBehavior;
+
+    let assessment: string;
+    if (!isComplete) {
+      const missing: string[] = [];
+      if (!hasIdentity) missing.push('identity');
+      if (!hasWarrants) missing.push('warrants');
+      if (!hasBehavior) missing.push('behavioral record');
+      assessment = `Incomplete provenance chain: missing ${missing.join(', ')}`;
+    } else if (driftReport && driftReport.compositeScore > 0.8) {
+      assessment = `Model shows significant drift (${driftReport.compositeScore.toFixed(2)}). Recommend quarantine and investigation.`;
+    } else if (flags.length === 0) {
+      assessment = 'Complete provenance chain with no anomalies detected';
+    } else {
+      assessment = `Provenance chain complete with flags: ${flags.join(', ')}`;
+    }
+
+    const verdict = { isComplete, confidence, assessment, flags };
+
+    // Chain attestation: L1 hash of identity + warrants + behavior (INV-007)
+    const chainData = deterministicStringify({
+      identityHash: identity.attestation.l1Hash,
+      warrantChainHash,
+      behavioralRecord,
+      verdict,
+    });
+    const chainL1Hash = await sha256(chainData);
+    const chainTimestamp = generateTimestamp();
+
+    const chain: ProvenanceChain = {
+      identity,
+      warrantHistory,
+      behavioralRecord,
+      verdict,
+      chainAttestation: {
+        l1Hash: chainL1Hash,
+        timestamp: chainTimestamp,
+      },
+    };
+
+    // Store chain for later queries
+    const key = `${identity.model.name}:${identity.model.version}`;
+    this.chains.set(key, chain);
+
+    return chain;
+  }
+
+  /**
+   * Answer a provenance query.
+   *
+   * The verification interface. A verifier submits a query, the engine
+   * retrieves the relevant chain, and returns a response with optional
+   * ZK proof.
+   */
+  async verifyProvenance(query: ProvenanceQuery): Promise<ProvenanceResponse> {
+    const key = query.modelVersion
+      ? `${query.modelName}:${query.modelVersion}`
+      : this.findLatestVersion(query.modelName);
+
+    const identity = this.identities.get(key);
+    const existingChain = this.chains.get(key);
+
+    // If no identity exists, return an incomplete chain (INV-005)
+    if (!identity) {
+      const emptyChain = this.buildEmptyChain(query.modelName, query.modelVersion);
+      return this.buildResponse(query, emptyChain);
+    }
+
+    // Use existing chain or build a minimal one from identity alone
+    let chain: ProvenanceChain;
+    if (existingChain) {
+      chain = existingChain;
+    } else {
+      chain = await this.buildProvenanceChain(identity, [], []);
+    }
+
+    const response = await this.buildResponse(query, chain);
+
+    // If ZK proof requested (INV-004: verifiable without chain data)
+    if (query.generateZkProof) {
+      const claim = this.buildZkClaim(query, chain);
+      const proofInput = deterministicStringify({ claim, chainHash: chain.chainAttestation.l1Hash });
+      const proof = await sha256(proofInput);
+      const vkInput = deterministicStringify({ proof, queryType: query.queryType });
+      const verificationKey = await sha256(vkInput);
+
+      response.zkProof = { claim, proof, verificationKey };
+    }
+
+    // If hardware attestation requested, include L2 placeholder
+    if (query.requireHardwareAttestation && chain.identity.attestation) {
+      chain.identity.attestation.l2Quote = `tee-quote-${chain.identity.attestation.l1Hash.substring(0, 16)}`;
+    }
+
+    return response;
+  }
+
+  /**
+   * Look up a stored identity attestation by model key.
+   */
+  getIdentity(modelName: string, modelVersion?: string): ModelIdentityAttestation | undefined {
+    const key = modelVersion
+      ? `${modelName}:${modelVersion}`
+      : this.findLatestVersion(modelName);
+    return this.identities.get(key);
+  }
+
+  /**
+   * Look up a stored provenance chain by model key.
+   */
+  getChain(modelName: string, modelVersion?: string): ProvenanceChain | undefined {
+    const key = modelVersion
+      ? `${modelName}:${modelVersion}`
+      : this.findLatestVersion(modelName);
+    return this.chains.get(key);
+  }
+
+  // ------------------------------------------------------------------
+  // Private helpers
+  // ------------------------------------------------------------------
+
+  private findLatestVersion(modelName: string): string {
+    for (const key of this.identities.keys()) {
+      if (key.startsWith(`${modelName}:`)) {
+        return key;
+      }
+    }
+    return `${modelName}:unknown`;
+  }
+
+  private buildEmptyChain(modelName: string, modelVersion?: string): ProvenanceChain {
+    return {
+      identity: {
+        id: '',
+        model: { name: modelName, version: modelVersion || 'unknown', provider: 'unknown' },
+        constraints: {
+          safetyTier: 'unknown',
+          authorizedDomains: [],
+          excludedDomains: [],
+          maxContextWindow: 0,
+          reasoningEnabled: false,
+          custom: {},
+        },
+        deployment: { environment: 'unknown' },
+        attestation: { l1Hash: '', timestamp: '', providerSignature: '' },
+      },
+      warrantHistory: {
+        totalWarrants: 0,
+        activeWarrants: 0,
+        revokedWarrants: 0,
+        warrantChainHash: '',
+      },
+      behavioralRecord: { totalSessions: 0, totalActions: 0, violations: 0 },
+      verdict: {
+        isComplete: false,
+        confidence: 0,
+        assessment: 'No identity attestation found. Model provenance cannot be verified.',
+        flags: ['no_identity'],
+      },
+      chainAttestation: { l1Hash: '', timestamp: '' },
+    };
+  }
+
+  private async buildResponse(
+    query: ProvenanceQuery,
+    chain: ProvenanceChain
+  ): Promise<ProvenanceResponse> {
+    const timestamp = generateTimestamp();
+    const responseData = deterministicStringify({ query, chain, timestamp });
+    const responseHash = await sha256(responseData);
+
+    return { query, chain, timestamp, responseHash };
+  }
+
+  private buildZkClaim(query: ProvenanceQuery, chain: ProvenanceChain): string {
+    switch (query.queryType) {
+      case 'identity':
+        return `Model ${query.modelName} has a valid identity attestation from provider ${chain.identity.model.provider}`;
+      case 'constraints':
+        return `Model ${query.modelName} operates within safety tier ${chain.identity.constraints.safetyTier}`;
+      case 'behavior':
+        return `Model ${query.modelName} completed ${chain.behavioralRecord.totalActions} actions with ${chain.behavioralRecord.violations} violations`;
+      case 'full_chain':
+        return `Model ${query.modelName} has ${chain.verdict.isComplete ? 'complete' : 'incomplete'} provenance with confidence ${chain.verdict.confidence.toFixed(2)}`;
+    }
+  }
+}

package/src/provenance/types.ts

@@ -0,0 +1,211 @@
+/**
+ * mdash v3.1 - Model Provenance Attestation Types
+ *
+ * Proving what a model IS: identity, constraints, and chain of custody.
+ * A distilled model has no provenance chain. It can produce similar
+ * outputs but cannot prove where its capabilities came from.
+ */
+
+/**
+ * ModelIdentityAttestation: A cryptographic claim about a model's identity.
+ *
+ * This is NOT the model itself. It's a sealed record that binds:
+ * - A model identifier (name, version, hash)
+ * - The provider who deployed it
+ * - The constraints under which it operates
+ * - A timestamp proving when this attestation was created
+ *
+ * A distilled model cannot produce a valid ModelIdentityAttestation
+ * because it lacks the provider's signing authority and the constraint
+ * chain that shaped the original model's behavior.
+ */
+export interface ModelIdentityAttestation {
+  /** Unique attestation ID */
+  id: string;
+
+  /** Model identity */
+  model: {
+    /** Provider-assigned model name (e.g., "claude-opus-4.6") */
+    name: string;
+    /** Provider-assigned version */
+    version: string;
+    /** Hash of model card or capability manifest, if available */
+    manifestHash?: string;
+    /** Provider identifier */
+    provider: string;
+  };
+
+  /** Constraint envelope: what boundaries this model operates within */
+  constraints: {
+    /** Safety tier (provider-defined) */
+    safetyTier: string;
+    /** Capability domains this model is authorized for */
+    authorizedDomains: string[];
+    /** Capability domains explicitly excluded */
+    excludedDomains: string[];
+    /** Maximum context window (tokens) */
+    maxContextWindow: number;
+    /** Whether reasoning/chain-of-thought is enabled */
+    reasoningEnabled: boolean;
+    /** Custom constraint fields (provider-extensible) */
+    custom: Record<string, string | number | boolean>;
+  };
+
+  /** Deployment context */
+  deployment: {
+    /** Where this model is deployed (e.g., "api", "enterprise", "research") */
+    environment: string;
+    /** Geographic region */
+    region?: string;
+    /** Tenant/organization ID (if enterprise deployment) */
+    tenantId?: string;
+  };
+
+  /** Attestation metadata */
+  attestation: {
+    /** L1: Commitment hash (Merkle leaf) */
+    l1Hash: string;
+    /** L2: TEE attestation quote (optional, for hardware-backed deployments) */
+    l2Quote?: string;
+    /** Timestamp of attestation creation */
+    timestamp: string;
+    /** Provider signature over the attestation */
+    providerSignature: string;
+  };
+}
+
+/**
+ * ProvenanceChain: Links a model identity to its operational history.
+ *
+ * This is the "chain of custody" for a model. It records:
+ * - The identity attestation (who the model claims to be)
+ * - The warrant chain (what the model was authorized to do)
+ * - The behavioral record (what the model actually did)
+ * - The drift assessment (whether behavior matches identity)
+ *
+ * A legitimate model has a complete provenance chain.
+ * A distilled copy has none.
+ */
+export interface ProvenanceChain {
+  /** The model's identity attestation */
+  identity: ModelIdentityAttestation;
+
+  /** Warrant history: what was this model authorized to do? */
+  warrantHistory: {
+    totalWarrants: number;
+    activeWarrants: number;
+    revokedWarrants: number;
+    /** Hash of the warrant chain (Merkle root) */
+    warrantChainHash: string;
+  };
+
+  /** Behavioral summary from GLOSS */
+  behavioralRecord: {
+    totalSessions: number;
+    totalActions: number;
+    violations: number;
+    /** Drift assessment from DriftDetector */
+    latestDriftReport?: {
+      compositeScore: number;
+      recommendation: string;
+    };
+  };
+
+  /** Provenance verdict */
+  verdict: {
+    /** Is the chain complete and consistent? */
+    isComplete: boolean;
+    /** Confidence score (0.0 to 1.0) */
+    confidence: number;
+    /** Human-readable assessment */
+    assessment: string;
+    /** Flags (e.g., "drift_detected", "warrant_gap", "identity_mismatch") */
+    flags: string[];
+  };
+
+  /** Chain attestation: the provenance chain itself is attested */
+  chainAttestation: {
+    l1Hash: string;
+    timestamp: string;
+  };
+}
+
+/**
+ * ProvenanceQuery: What a verifier asks when checking a model.
+ *
+ * Use cases:
+ * - DoD procurement: "Prove this model is the authorized version"
+ * - Export control: "Prove this model hasn't been modified"
+ * - Enterprise audit: "Prove this model operated within its constraints"
+ * - Insurance underwriting: "Prove this model's behavioral history"
+ */
+export interface ProvenanceQuery {
+  /** What are we checking? */
+  queryType: 'identity' | 'constraints' | 'behavior' | 'full_chain';
+
+  /** Model identifier to verify */
+  modelName: string;
+  modelVersion?: string;
+
+  /** Time window for behavioral verification */
+  timeWindow?: {
+    start: string;
+    end: string;
+  };
+
+  /** Whether to include L2 TEE verification */
+  requireHardwareAttestation: boolean;
+
+  /** Whether to generate L3 ZK proof (for cross-classification verification) */
+  generateZkProof: boolean;
+}
+
+/**
+ * ProvenanceResponse: The answer to a provenance query.
+ *
+ * If generateZkProof is true, the response includes a proof that
+ * can verify the claim WITHOUT revealing the underlying data.
+ * This enables cross-classification verification: a NATO ally can
+ * verify a US-deployed model meets compliance requirements without
+ * seeing classified operational details.
+ */
+export interface ProvenanceResponse {
+  query: ProvenanceQuery;
+  chain: ProvenanceChain;
+
+  /** If ZK proof requested */
+  zkProof?: {
+    /** The claim being proven */
+    claim: string;
+    /** The proof (opaque bytes, verifiable without the chain) */
+    proof: string;
+    /** Verification key */
+    verificationKey: string;
+  };
+
+  /** Response metadata */
+  timestamp: string;
+  responseHash: string;
+}
+
+/**
+ * GlossEntry: Minimal behavioral record shape for provenance.
+ *
+ * This is a protocol-level interface. The full GLOSS entry lives
+ * in Kiwi (runtime). Provenance only needs enough to build a
+ * behavioral summary.
+ */
+export interface GlossEntry {
+  /** Entry identifier */
+  id: string;
+  /** Entry type */
+  type: string;
+  /** Agent that produced this entry */
+  agentId: string;
+  /** Session identifier */
+  sessionId: string;
+  /** Timestamp */
+  timestamp: string;
+  /** Whether this entry records a violation */
+  isViolation?: boolean;
+}

package/src/tee/engine.ts

@@ -310,6 +310,12 @@ export class TEEAttestationEngine {
     this.commitmentEngine = commitmentEngine;
     this.config = { ...DEFAULT_CONFIG, ...config };
     this.cache = new AttestationCache(this.config.cacheTTL);
+    
+    // P2 SECURITY: Warn if running in simulated mode
+    if (this.config.platform === 'simulated') {
+      console.warn('[TEE] WARNING: Running in SIMULATED mode - no hardware attestation');
+      console.warn('[TEE] Set teePlatform to "nitro" or "sgx" for production deployments');
+    }
   }
 
   /**
@@ -318,6 +324,16 @@ export class TEEAttestationEngine {
   async initialize(sealKey: string): Promise<void> {
     this.key = await deriveKey(sealKey);
     
+    // P2 SECURITY: Detect production environment running simulated
+    const isProduction = process.env.NODE_ENV === 'production';
+    if (isProduction && this.config.platform === 'simulated') {
+      console.error('[TEE] CRITICAL: Simulated TEE in production environment');
+      console.error('[TEE] Set MDASH_ALLOW_SIMULATED_TEE=true to override (NOT RECOMMENDED)');
+      if (!process.env.MDASH_ALLOW_SIMULATED_TEE) {
+        throw new Error('Simulated TEE not allowed in production. Set teePlatform to "nitro" or "sgx".');
+      }
+    }
+    
     // Platform-specific initialization
     if (this.config.platform === 'nitro') {
       await this.initializeNitro();