@longarc/mdash 3.1.2 → 3.1.3

package/src/physics/engine.ts

@@ -289,6 +289,7 @@ export class PhysicsEngine {
   
   /**
    * Check a specific constraint
+   * P4 SECURITY: Explicit presence checks prevent trust escalation
    */
   private async checkConstraint(
     constraint: PhysicsConstraint,
@@ -298,8 +299,38 @@ export class PhysicsEngine {
     switch (constraint.type) {
       case 'max_amount': {
         const amount = action.params.amount as number | undefined;
-        const limit = warrantConstraints.maxAmount ?? (constraint.params.limit as number);
-        
+
+        // SA-2026-011: Explicit NaN and negative rejection
+        // NaN > X is always false in JS, bypassing maxAmount constraints.
+        // Negative amounts have no floor without explicit check.
+        if (amount !== undefined) {
+          if (typeof amount !== 'number' || isNaN(amount)) {
+            return {
+              type: 'amount_exceeded',
+              constraint,
+              message: 'Amount is not a valid number',
+              severity: 'block',
+            };
+          }
+          if (amount < 0) {
+            return {
+              type: 'amount_exceeded',
+              constraint,
+              message: 'Negative amounts are not permitted',
+              severity: 'block',
+            };
+          }
+        }
+
+        // P4 SECURITY: Explicit presence check - warrant must define maxAmount
+        // or policy default applies. Explicitly passing undefined is NOT the same
+        // as not having the constraint.
+        const hasWarrantLimit = Object.prototype.hasOwnProperty.call(warrantConstraints, 'maxAmount')
+          && warrantConstraints.maxAmount !== undefined;
+        const limit = hasWarrantLimit
+          ? warrantConstraints.maxAmount!
+          : (constraint.params.limit as number);
+
         if (amount !== undefined && amount > limit) {
           return {
             type: 'amount_exceeded',
@@ -313,7 +344,13 @@ export class PhysicsEngine {
       
       case 'domain_allowlist': {
         const domain = action.params.domain as string | undefined;
-        const allowed = warrantConstraints.allowedDomains ?? (constraint.params.domains as string[]);
+        
+        // P4 SECURITY: Same pattern - explicit presence check
+        const hasWarrantDomains = Object.prototype.hasOwnProperty.call(warrantConstraints, 'allowedDomains')
+          && warrantConstraints.allowedDomains !== undefined;
+        const allowed = hasWarrantDomains
+          ? warrantConstraints.allowedDomains!
+          : (constraint.params.domains as string[]);
         
         if (domain && allowed.length > 0 && !allowed.includes(domain)) {
           return {

package/src/provenance/api-handler.ts

@@ -0,0 +1,248 @@
+/**
+ * mdash v3.1 - Provenance API Handler
+ *
+ * Wires HTTP request/response types to the ProvenanceEngine.
+ * This is the door: external parties call through here to
+ * attest, verify, and inspect model provenance.
+ */
+
+import { ProvenanceEngine } from './provenance-engine.js';
+import type {
+  AttestRequest,
+  AttestResponse,
+  VerifyRequest,
+  VerifyResponse,
+  ChainResponse,
+} from './api-types.js';
+
+export class ProvenanceApiHandler {
+  private engine: ProvenanceEngine;
+
+  constructor(engine: ProvenanceEngine) {
+    this.engine = engine;
+  }
+
+  /**
+   * Handle POST /provenance/attest
+   *
+   * Validates the request, creates the identity attestation,
+   * and returns the attestation ID and L1 hash.
+   */
+  async handleAttest(req: AttestRequest): Promise<{ status: number; body: AttestResponse }> {
+    // Validate required fields
+    const missing: string[] = [];
+    if (!req.model?.name) missing.push('model.name');
+    if (!req.model?.version) missing.push('model.version');
+    if (!req.model?.provider) missing.push('model.provider');
+    if (!req.deployment?.environment) missing.push('deployment.environment');
+
+    if (missing.length > 0) {
+      return {
+        status: 400,
+        body: {
+          attestationId: '',
+          l1Hash: '',
+          timestamp: '',
+          status: 'error',
+          error: `Missing required fields: ${missing.join(', ')}`,
+        },
+      };
+    }
+
+    // Check for duplicate (409)
+    const existing = this.engine.getIdentity(req.model.name, req.model.version);
+    if (existing) {
+      return {
+        status: 409,
+        body: {
+          attestationId: existing.id,
+          l1Hash: existing.attestation.l1Hash,
+          timestamp: existing.attestation.timestamp,
+          status: 'error',
+          error: `Attestation for ${req.model.name}:${req.model.version} already exists`,
+        },
+      };
+    }
+
+    try {
+      const constraints = {
+        safetyTier: req.constraints.safetyTier,
+        authorizedDomains: req.constraints.authorizedDomains,
+        excludedDomains: req.constraints.excludedDomains,
+        maxContextWindow: req.constraints.maxContextWindow,
+        reasoningEnabled: req.constraints.reasoningEnabled,
+        custom: req.constraints.custom || {},
+      };
+
+      const attestation = await this.engine.createIdentityAttestation(
+        req.model,
+        constraints,
+        req.deployment
+      );
+
+      return {
+        status: 201,
+        body: {
+          attestationId: attestation.id,
+          l1Hash: attestation.attestation.l1Hash,
+          timestamp: attestation.attestation.timestamp,
+          status: 'created',
+        },
+      };
+    } catch (err) {
+      return {
+        status: 500,
+        body: {
+          attestationId: '',
+          l1Hash: '',
+          timestamp: '',
+          status: 'error',
+          error: err instanceof Error ? err.message : 'Internal error',
+        },
+      };
+    }
+  }
+
+  /**
+   * Handle POST /provenance/verify
+   *
+   * Validates the request, runs provenance verification,
+   * and returns the chain verdict with optional ZK proof.
+   */
+  async handleVerify(req: VerifyRequest): Promise<{ status: number; body: VerifyResponse }> {
+    if (!req.modelName) {
+      return {
+        status: 400,
+        body: {
+          status: 'error',
+          chain: { isComplete: false, confidence: 0, assessment: '', flags: [] },
+          timestamp: '',
+          responseHash: '',
+          error: 'Missing required field: modelName',
+        },
+      };
+    }
+
+    try {
+      const response = await this.engine.verifyProvenance({
+        queryType: req.queryType || 'full_chain',
+        modelName: req.modelName,
+        modelVersion: req.modelVersion,
+        timeWindow: req.timeWindow,
+        requireHardwareAttestation: req.requireHardwareAttestation || false,
+        generateZkProof: req.generateZkProof || false,
+      });
+
+      const isVerified = response.chain.verdict.isComplete;
+      const isPartial = !isVerified && response.chain.verdict.confidence > 0;
+      const httpStatus = isVerified ? 200 : (response.chain.verdict.flags.includes('no_identity') ? 404 : 200);
+
+      let verifyStatus: VerifyResponse['status'];
+      if (isVerified) {
+        verifyStatus = 'verified';
+      } else if (isPartial) {
+        verifyStatus = 'partial';
+      } else {
+        verifyStatus = 'unverified';
+      }
+
+      return {
+        status: httpStatus,
+        body: {
+          status: verifyStatus,
+          chain: {
+            isComplete: response.chain.verdict.isComplete,
+            confidence: response.chain.verdict.confidence,
+            assessment: response.chain.verdict.assessment,
+            flags: response.chain.verdict.flags,
+          },
+          zkProof: response.zkProof,
+          timestamp: response.timestamp,
+          responseHash: response.responseHash,
+        },
+      };
+    } catch (err) {
+      return {
+        status: 500,
+        body: {
+          status: 'error',
+          chain: { isComplete: false, confidence: 0, assessment: '', flags: [] },
+          timestamp: '',
+          responseHash: '',
+          error: err instanceof Error ? err.message : 'Internal error',
+        },
+      };
+    }
+  }
+
+  /**
+   * Handle GET /provenance/chain/:modelId
+   *
+   * Retrieves the full provenance chain for a model.
+   * modelId format: "name:version"
+   */
+  async handleGetChain(modelId: string): Promise<{ status: number; body: ChainResponse }> {
+    const [modelName, modelVersion] = modelId.split(':');
+
+    const chain = this.engine.getChain(modelName, modelVersion);
+    if (!chain) {
+      // Try verifying to build a minimal chain from identity
+      const identity = this.engine.getIdentity(modelName, modelVersion);
+      if (!identity) {
+        return {
+          status: 404,
+          body: {
+            modelId,
+            identity: { name: modelName || '', version: modelVersion || '', provider: '', attestedAt: '', l1Hash: '' },
+            warrants: { total: 0, active: 0, revoked: 0, chainHash: '' },
+            behavior: { totalSessions: 0, totalActions: 0, violations: 0 },
+            verdict: { isComplete: false, confidence: 0, assessment: 'Model not found', flags: ['no_identity'] },
+            chainAttestation: { l1Hash: '', timestamp: '' },
+          },
+        };
+      }
+
+      // Build minimal chain from identity alone
+      const minimalChain = await this.engine.buildProvenanceChain(identity, [], []);
+      return {
+        status: 200,
+        body: this.mapChainResponse(modelId, minimalChain),
+      };
+    }
+
+    return {
+      status: 200,
+      body: this.mapChainResponse(modelId, chain),
+    };
+  }
+
+  private mapChainResponse(
+    modelId: string,
+    chain: import('./types.js').ProvenanceChain
+  ): ChainResponse {
+    return {
+      modelId,
+      identity: {
+        name: chain.identity.model.name,
+        version: chain.identity.model.version,
+        provider: chain.identity.model.provider,
+        attestedAt: chain.identity.attestation.timestamp,
+        l1Hash: chain.identity.attestation.l1Hash,
+      },
+      warrants: {
+        total: chain.warrantHistory.totalWarrants,
+        active: chain.warrantHistory.activeWarrants,
+        revoked: chain.warrantHistory.revokedWarrants,
+        chainHash: chain.warrantHistory.warrantChainHash,
+      },
+      behavior: {
+        totalSessions: chain.behavioralRecord.totalSessions,
+        totalActions: chain.behavioralRecord.totalActions,
+        violations: chain.behavioralRecord.violations,
+        latestDriftScore: chain.behavioralRecord.latestDriftReport?.compositeScore,
+      },
+      verdict: chain.verdict,
+      chainAttestation: chain.chainAttestation,
+    };
+  }
+}

package/src/provenance/api-types.ts

@@ -0,0 +1,112 @@
+/**
+ * mdash v3.1 - Provenance API Types
+ *
+ * HTTP request/response types for the provenance API surface.
+ * These types define the contract between external callers
+ * and the ProvenanceEngine.
+ */
+
+/**
+ * POST /provenance/attest
+ * Called by model providers to register a model's identity.
+ */
+export interface AttestRequest {
+  model: {
+    name: string;
+    version: string;
+    manifestHash?: string;
+    provider: string;
+  };
+  constraints: {
+    safetyTier: string;
+    authorizedDomains: string[];
+    excludedDomains: string[];
+    maxContextWindow: number;
+    reasoningEnabled: boolean;
+    custom?: Record<string, string | number | boolean>;
+  };
+  deployment: {
+    environment: string;
+    region?: string;
+    tenantId?: string;
+  };
+}
+
+export interface AttestResponse {
+  attestationId: string;
+  l1Hash: string;
+  timestamp: string;
+  status: 'created' | 'error';
+  error?: string;
+}
+
+/**
+ * POST /provenance/verify
+ * Called by verifiers to check a model's provenance.
+ */
+export interface VerifyRequest {
+  modelName: string;
+  modelVersion?: string;
+  queryType: 'identity' | 'constraints' | 'behavior' | 'full_chain';
+  timeWindow?: {
+    start: string;
+    end: string;
+  };
+  requireHardwareAttestation?: boolean;
+  generateZkProof?: boolean;
+}
+
+export interface VerifyResponse {
+  status: 'verified' | 'unverified' | 'partial' | 'error';
+  chain: {
+    isComplete: boolean;
+    confidence: number;
+    assessment: string;
+    flags: string[];
+  };
+  zkProof?: {
+    claim: string;
+    proof: string;
+    verificationKey: string;
+  };
+  timestamp: string;
+  responseHash: string;
+  error?: string;
+}
+
+/**
+ * GET /provenance/chain/:modelId
+ * Called by regulators to retrieve the full provenance chain.
+ */
+export interface ChainResponse {
+  modelId: string;
+  identity: {
+    name: string;
+    version: string;
+    provider: string;
+    attestedAt: string;
+    l1Hash: string;
+  };
+  warrants: {
+    total: number;
+    active: number;
+    revoked: number;
+    chainHash: string;
+  };
+  behavior: {
+    totalSessions: number;
+    totalActions: number;
+    violations: number;
+    latestDriftScore?: number;
+  };
+  verdict: {
+    isComplete: boolean;
+    confidence: number;
+    assessment: string;
+    flags: string[];
+  };
+  chainAttestation: {
+    l1Hash: string;
+    timestamp: string;
+  };
+}

package/src/provenance/index.ts

@@ -0,0 +1,19 @@
+export type {
+  ModelIdentityAttestation,
+  ProvenanceChain,
+  ProvenanceQuery,
+  ProvenanceResponse,
+  GlossEntry,
+} from './types.js';
+
+export { ProvenanceEngine } from './provenance-engine.js';
+export type { DriftReportInput } from './provenance-engine.js';
+
+export { ProvenanceApiHandler } from './api-handler.js';
+export type {
+  AttestRequest,
+  AttestResponse,
+  VerifyRequest,
+  VerifyResponse,
+  ChainResponse,
+} from './api-types.js';