pumuki 6.3.26 → 6.3.28

package/integrations/gate/evaluateAiGate.ts

@@ -3,8 +3,26 @@ import { readEvidenceResult } from '../evidence/readEvidence';
 import { captureRepoState } from '../evidence/repoState';
 import type { RepoState } from '../evidence/schema';
 import { resolvePolicyForStage } from './stagePolicies';
-import { realpathSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
 import type { SkillsStage } from '../config/skillsLock';
+import type { ResolvedStagePolicy } from './stagePolicies';
+import {
+  readMcpAiGateReceipt,
+  resolveMcpAiGateReceiptPath,
+  type McpAiGateReceiptReadResult,
+} from '../mcp/aiGateReceipt';
+import {
+  resolveEvidenceSigningConfig,
+  verifyEvidenceIntegrity,
+  type EvidenceIntegrityVerification,
+} from '../evidence/integrity';
+import {
+  applyAiGateWaivers,
+  type AppliedAiGateWaiver,
+} from './waivers';
+import { emitStructuredTelemetry } from '../telemetry/structuredTelemetry';
 
 export type AiGateStage = 'PRE_WRITE' | 'PRE_COMMIT' | 'PRE_PUSH' | 'CI';
 
@@ -23,16 +41,39 @@ export type AiGateCheckResult = {
     resolved_stage: SkillsStage;
     block_on_or_above: 'INFO' | 'WARN' | 'ERROR' | 'CRITICAL';
     warn_on_or_above: 'INFO' | 'WARN' | 'ERROR' | 'CRITICAL';
-    trace: {
-      source: 'default' | 'skills.policy' | 'hard-mode';
-      bundle: string;
-      hash: string;
-    };
+    trace: ResolvedStagePolicy['trace'];
   };
   evidence: {
     kind: EvidenceReadResult['kind'];
     max_age_seconds: number;
     age_seconds: number | null;
+    source: 'local_file_ai_evidence';
+    path: string;
+    digest: string | null;
+    generated_at: string | null;
+    integrity: {
+      status: EvidenceIntegrityVerification['status'];
+      code: string | null;
+      payload_hash: string | null;
+      previous_chain_hash: string | null;
+      chain_hash: string | null;
+      signature_present: boolean;
+      signature_key_id: string | null;
+      signature_verified: boolean | null;
+    };
+  };
+  mcp_receipt: {
+    required: boolean;
+    kind: 'disabled' | McpAiGateReceiptReadResult['kind'];
+    path: string;
+    max_age_seconds: number | null;
+    age_seconds: number | null;
+  };
+  waivers: {
+    path: string;
+    status: 'none' | 'applied' | 'invalid';
+    invalid_reason: string | null;
+    applied: AppliedAiGateWaiver[];
   };
   repo_state: RepoState;
   violations: AiGateViolation[];
@@ -40,16 +81,22 @@ export type AiGateCheckResult = {
 
 type AiGateDependencies = {
   now: () => number;
+  env: NodeJS.ProcessEnv;
   readEvidenceResult: (repoRoot: string) => EvidenceReadResult;
+  readMcpAiGateReceipt: (repoRoot: string) => McpAiGateReceiptReadResult;
   captureRepoState: (repoRoot: string) => RepoState;
   resolvePolicyForStage: (stage: SkillsStage, repoRoot: string) => ReturnType<typeof resolvePolicyForStage>;
+  emitStructuredTelemetry: typeof emitStructuredTelemetry;
 };
 
 const defaultDependencies: AiGateDependencies = {
   now: () => Date.now(),
+  env: process.env,
   readEvidenceResult,
+  readMcpAiGateReceipt,
   captureRepoState,
   resolvePolicyForStage,
+  emitStructuredTelemetry,
 };
 
 const DEFAULT_MAX_AGE_SECONDS: Readonly<Record<AiGateStage, number>> = {
@@ -203,20 +250,49 @@ const collectPreWriteCoherenceViolations = (params: {
   return violations;
 };
 
+const toIntegritySummary = (verification: EvidenceIntegrityVerification): {
+  status: EvidenceIntegrityVerification['status'];
+  code: string | null;
+  payload_hash: string | null;
+  previous_chain_hash: string | null;
+  chain_hash: string | null;
+  signature_present: boolean;
+  signature_key_id: string | null;
+  signature_verified: boolean | null;
+} => ({
+  status: verification.status,
+  code: verification.code,
+  payload_hash: verification.payloadHash,
+  previous_chain_hash: verification.previousChainHash,
+  chain_hash: verification.chainHash,
+  signature_present: verification.signature.present,
+  signature_key_id: verification.signature.keyId,
+  signature_verified: verification.signature.verified,
+});
+
 const collectEvidenceViolations = (
   result: EvidenceReadResult,
   repoRoot: string,
   repoState: RepoState,
   stage: AiGateStage,
   nowMs: number,
-  maxAgeSecondsByStage: Readonly<Record<AiGateStage, number>>
-): { violations: AiGateViolation[]; ageSeconds: number | null } => {
+  maxAgeSecondsByStage: Readonly<Record<AiGateStage, number>>,
+  verification: EvidenceIntegrityVerification
+): {
+  violations: AiGateViolation[];
+  ageSeconds: number | null;
+  integrity: ReturnType<typeof toIntegritySummary>;
+} => {
   const violations: AiGateViolation[] = [];
   const maxAgeSeconds = maxAgeSecondsByStage[stage];
 
   if (result.kind === 'missing') {
     violations.push(toErrorViolation('EVIDENCE_MISSING', '.ai_evidence.json is missing.'));
-    return { violations, ageSeconds: null };
+    return {
+      violations,
+      ageSeconds: null,
+      integrity: toIntegritySummary(verification),
+    };
   }
 
   if (result.kind === 'invalid') {
@@ -226,13 +302,30 @@ const collectEvidenceViolations = (
         `.ai_evidence.json is invalid${result.version ? ` (version=${result.version})` : ''}.`
       )
     );
-    return { violations, ageSeconds: null };
+    return {
+      violations,
+      ageSeconds: null,
+      integrity: toIntegritySummary(verification),
+    };
+  }
+
+  if (!verification.ok) {
+    violations.push(
+      toErrorViolation(
+        verification.code ?? 'EVIDENCE_INTEGRITY_INVALID',
+        verification.message ?? 'Evidence integrity verification failed.'
+      )
+    );
   }
 
   const ageSeconds = toTimestampAgeSeconds(result.evidence.timestamp, nowMs);
   if (ageSeconds === null) {
     violations.push(toErrorViolation('EVIDENCE_TIMESTAMP_INVALID', 'Evidence timestamp is invalid.'));
-    return { violations, ageSeconds: null };
+    return {
+      violations,
+      ageSeconds: null,
+      integrity: toIntegritySummary(verification),
+    };
   }
 
   if (ageSeconds > maxAgeSeconds) {
@@ -259,7 +352,40 @@ const collectEvidenceViolations = (
     );
   }
 
-  return { violations, ageSeconds };
+  return {
+    violations,
+    ageSeconds,
+    integrity: toIntegritySummary(verification),
+  };
+};
+
+const resolveEvidenceSourceDetails = (
+  repoRoot: string,
+  result: EvidenceReadResult
+): {
+  source: 'local_file_ai_evidence';
+  path: string;
+  digest: string | null;
+  generated_at: string | null;
+} => {
+  const evidencePath = resolve(repoRoot, '.ai_evidence.json');
+  let digest: string | null = null;
+
+  if (existsSync(evidencePath)) {
+    try {
+      const buffer = readFileSync(evidencePath);
+      digest = createHash('sha256').update(buffer).digest('hex');
+    } catch {
+      digest = null;
+    }
+  }
+
+  return {
+    source: 'local_file_ai_evidence',
+    path: evidencePath,
+    digest,
+    generated_at: result.kind === 'valid' ? result.evidence.timestamp : null,
+  };
 };
 
 const collectGitflowViolations = (
@@ -288,12 +414,126 @@ const toPolicyStage = (stage: AiGateStage): SkillsStage => {
   return stage;
 };
 
+const collectMcpReceiptViolations = (params: {
+  required: boolean;
+  stage: AiGateStage;
+  repoRoot: string;
+  nowMs: number;
+  maxAgeSecondsByStage: Readonly<Record<AiGateStage, number>>;
+  readMcpAiGateReceipt: (repoRoot: string) => McpAiGateReceiptReadResult;
+}): {
+  required: boolean;
+  kind: 'disabled' | McpAiGateReceiptReadResult['kind'];
+  path: string;
+  maxAgeSeconds: number | null;
+  ageSeconds: number | null;
+  violations: AiGateViolation[];
+} => {
+  const path = resolveMcpAiGateReceiptPath(params.repoRoot);
+  if (!params.required || params.stage !== 'PRE_WRITE') {
+    return {
+      required: params.required,
+      kind: 'disabled',
+      path,
+      maxAgeSeconds: null,
+      ageSeconds: null,
+      violations: [],
+    };
+  }
+
+  const maxAgeSeconds = params.maxAgeSecondsByStage[params.stage];
+  const receiptRead = params.readMcpAiGateReceipt(params.repoRoot);
+  if (receiptRead.kind === 'missing') {
+    return {
+      required: true,
+      kind: 'missing',
+      path: receiptRead.path,
+      maxAgeSeconds,
+      ageSeconds: null,
+      violations: [
+        toErrorViolation(
+          'MCP_ENTERPRISE_RECEIPT_MISSING',
+          'MCP receipt is missing. Call tool ai_gate_check in pumuki-enterprise MCP before PRE_WRITE.'
+        ),
+      ],
+    };
+  }
+
+  if (receiptRead.kind === 'invalid') {
+    return {
+      required: true,
+      kind: 'invalid',
+      path: receiptRead.path,
+      maxAgeSeconds,
+      ageSeconds: null,
+      violations: [
+        toErrorViolation(
+          'MCP_ENTERPRISE_RECEIPT_INVALID',
+          `MCP receipt is invalid: ${receiptRead.reason}`
+        ),
+      ],
+    };
+  }
+
+  const violations: AiGateViolation[] = [];
+  if (toCanonicalPath(receiptRead.receipt.repo_root) !== toCanonicalPath(params.repoRoot)) {
+    violations.push(
+      toErrorViolation(
+        'MCP_ENTERPRISE_RECEIPT_REPO_ROOT_MISMATCH',
+        `MCP receipt repo root mismatch (${receiptRead.receipt.repo_root} != ${params.repoRoot}).`
+      )
+    );
+  }
+  if (receiptRead.receipt.stage !== params.stage) {
+    violations.push(
+      toErrorViolation(
+        'MCP_ENTERPRISE_RECEIPT_STAGE_MISMATCH',
+        `MCP receipt stage mismatch (${receiptRead.receipt.stage} != ${params.stage}).`
+      )
+    );
+  }
+  const ageSeconds = toTimestampAgeSeconds(receiptRead.receipt.issued_at, params.nowMs);
+  if (ageSeconds === null) {
+    violations.push(
+      toErrorViolation(
+        'MCP_ENTERPRISE_RECEIPT_TIMESTAMP_INVALID',
+        'MCP receipt issued_at timestamp is invalid.'
+      )
+    );
+  } else if (ageSeconds > maxAgeSeconds) {
+    violations.push(
+      toErrorViolation(
+        'MCP_ENTERPRISE_RECEIPT_STALE',
+        `MCP receipt is stale (${ageSeconds}s > ${maxAgeSeconds}s for ${params.stage}).`
+      )
+    );
+  }
+  if (isTimestampFuture(receiptRead.receipt.issued_at, params.nowMs)) {
+    violations.push(
+      toErrorViolation(
+        'MCP_ENTERPRISE_RECEIPT_TIMESTAMP_FUTURE',
+        'MCP receipt timestamp is in the future.'
+      )
+    );
+  }
+
+  return {
+    required: true,
+    kind: 'valid',
+    path: receiptRead.path,
+    maxAgeSeconds,
+    ageSeconds,
+    violations,
+  };
+};
+
 export const evaluateAiGate = (
   params: {
     repoRoot: string;
     stage: AiGateStage;
     maxAgeSecondsByStage?: Readonly<Record<AiGateStage, number>>;
     protectedBranches?: ReadonlyArray<string>;
+    requireMcpReceipt?: boolean;
   },
   dependencies: Partial<AiGateDependencies> = {}
 ): AiGateCheckResult => {
@@ -305,6 +545,34 @@ export const evaluateAiGate = (
   const protectedBranches = new Set(params.protectedBranches ?? Array.from(DEFAULT_PROTECTED_BRANCHES));
   const nowMs = activeDependencies.now();
   const evidenceResult = activeDependencies.readEvidenceResult(params.repoRoot);
+  const evidenceSourceDetails = resolveEvidenceSourceDetails(
+    params.repoRoot,
+    evidenceResult
+  );
+  const evidenceIntegrityVerification: EvidenceIntegrityVerification =
+    evidenceResult.kind === 'valid'
+      ? verifyEvidenceIntegrity(evidenceResult.evidence, {
+        signatureConfig: resolveEvidenceSigningConfig(activeDependencies.env),
+        enforceSignature: false,
+      })
+      : {
+        ok: false,
+        status: evidenceResult.kind === 'missing' ? 'missing' : 'invalid',
+        code: evidenceResult.kind === 'missing'
+          ? 'EVIDENCE_INTEGRITY_MISSING'
+          : 'EVIDENCE_INTEGRITY_UNAVAILABLE',
+        message: evidenceResult.kind === 'missing'
+          ? 'Evidence integrity metadata is missing.'
+          : 'Evidence integrity cannot be verified from invalid payload.',
+        payloadHash: null,
+        previousChainHash: null,
+        chainHash: null,
+        signature: {
+          present: false,
+          keyId: null,
+          verified: null,
+        },
+      };
   const repoState = activeDependencies.captureRepoState(params.repoRoot);
   const policyStage = toPolicyStage(params.stage);
   const resolvedPolicy = activeDependencies.resolvePolicyForStage(
@@ -317,13 +585,42 @@ export const evaluateAiGate = (
     repoState,
     params.stage,
     nowMs,
-    maxAgeSecondsByStage
+    maxAgeSecondsByStage,
+    evidenceIntegrityVerification
   );
+  const mcpReceiptAssessment = collectMcpReceiptViolations({
+    required: params.requireMcpReceipt ?? false,
+    stage: params.stage,
+    repoRoot: params.repoRoot,
+    nowMs,
+    maxAgeSecondsByStage,
+    readMcpAiGateReceipt: activeDependencies.readMcpAiGateReceipt,
+  });
   const gitflowViolations = collectGitflowViolations(repoState, protectedBranches);
-  const violations = [...evidenceAssessment.violations, ...gitflowViolations];
+  const baseViolations = [
+    ...evidenceAssessment.violations,
+    ...gitflowViolations,
+    ...mcpReceiptAssessment.violations,
+  ];
+  const waiverAssessment = applyAiGateWaivers({
+    repoRoot: params.repoRoot,
+    stage: params.stage,
+    branch: repoState.git.branch,
+    violations: baseViolations,
+    now: new Date(nowMs),
+  });
+  const violations = [...waiverAssessment.violations];
+  if (waiverAssessment.status === 'invalid') {
+    violations.push(
+      toErrorViolation(
+        'WAIVER_POLICY_INVALID',
+        `Waiver file is invalid: ${waiverAssessment.invalid_reason ?? 'unknown_error'}.`
+      )
+    );
+  }
   const blocked = violations.some((violation) => violation.severity === 'ERROR');
 
-  return {
+  const result: AiGateCheckResult = {
     stage: params.stage,
     status: blocked ? 'BLOCKED' : 'ALLOWED',
     allowed: !blocked,
@@ -338,8 +635,78 @@ export const evaluateAiGate = (
       kind: evidenceResult.kind,
       max_age_seconds: maxAgeSecondsByStage[params.stage],
       age_seconds: evidenceAssessment.ageSeconds,
+      source: evidenceSourceDetails.source,
+      path: evidenceSourceDetails.path,
+      digest: evidenceSourceDetails.digest,
+      generated_at: evidenceSourceDetails.generated_at,
+      integrity: evidenceAssessment.integrity,
+    },
+    mcp_receipt: {
+      required: mcpReceiptAssessment.required,
+      kind: mcpReceiptAssessment.kind,
+      path: mcpReceiptAssessment.path,
+      max_age_seconds: mcpReceiptAssessment.maxAgeSeconds,
+      age_seconds: mcpReceiptAssessment.ageSeconds,
+    },
+    waivers: {
+      path: waiverAssessment.path,
+      status: waiverAssessment.status,
+      invalid_reason: waiverAssessment.invalid_reason,
+      applied: [...waiverAssessment.applied],
     },
     repo_state: repoState,
     violations,
   };
+
+  activeDependencies.emitStructuredTelemetry({
+    repoRoot: params.repoRoot,
+    env: activeDependencies.env,
+    event: {
+      schema_version: '1',
+      timestamp: new Date(nowMs).toISOString(),
+      source: 'pumuki',
+      channel: 'ai_gate',
+      event: 'ai_gate.evaluated',
+      stage: result.stage,
+      repo_root: params.repoRoot,
+      status: result.status,
+      decision: result.allowed ? 'ALLOW' : 'BLOCK',
+      policy: {
+        source: result.policy.trace.source,
+        bundle: result.policy.trace.bundle,
+        hash: result.policy.trace.hash,
+        version: result.policy.trace.version ?? 'n/a',
+        signature: result.policy.trace.signature ?? 'n/a',
+      },
+      evidence: {
+        kind: result.evidence.kind,
+        age_seconds: result.evidence.age_seconds,
+        max_age_seconds: result.evidence.max_age_seconds,
+        source: result.evidence.source,
+        path: result.evidence.path,
+        digest: result.evidence.digest,
+        generated_at: result.evidence.generated_at,
+        integrity_status: result.evidence.integrity.status,
+        chain_hash: result.evidence.integrity.chain_hash,
+      },
+      metrics: {
+        violations_total: result.violations.length,
+        violations_error: result.violations.filter((violation) => violation.severity === 'ERROR').length,
+        violations_warn: result.violations.filter((violation) => violation.severity === 'WARN').length,
+      },
+      mcp_receipt: {
+        required: result.mcp_receipt.required,
+        kind: result.mcp_receipt.kind,
+        age_seconds: result.mcp_receipt.age_seconds,
+        max_age_seconds: result.mcp_receipt.max_age_seconds,
+      },
+      waivers: {
+        status: result.waivers.status,
+        applied: result.waivers.applied.length,
+        path: result.waivers.path,
+      },
+    },
+  });
+
+  return result;
 };

package/integrations/gate/stagePolicies.ts

@@ -44,6 +44,8 @@ export type ResolvedStagePolicy = {
     source: 'default' | 'skills.policy' | 'hard-mode';
     bundle: string;
     hash: string;
+    version?: string;
+    signature?: string;
   };
 };
 
@@ -181,6 +183,8 @@ const hardModePolicyProfileByStage: Record<
 };
 
 const HARD_MODE_CONFIG_PATH = '.pumuki/hard-mode.json';
+const POLICY_TRACE_VERSION_DEFAULT = 'policy-as-code/default@1.0';
+const POLICY_TRACE_VERSION_HARD_MODE = 'policy-as-code/hard-mode@1.0';
 
 const toHardModeProfileName = (value: unknown): HardModeProfileName | null => {
   if (typeof value !== 'string') {
@@ -287,6 +291,26 @@ const createPolicyTraceHash = (params: {
     .digest('hex');
 };
 
+const createPolicyTraceSignature = (params: {
+  version: string;
+  source: 'default' | 'skills.policy' | 'hard-mode';
+  bundle: string;
+  hash: string;
+  sourcePolicyHash?: string;
+}): string => {
+  return createHash('sha256')
+    .update(
+      JSON.stringify({
+        version: params.version,
+        source: params.source,
+        bundle: params.bundle,
+        hash: params.hash,
+        sourcePolicyHash: params.sourcePolicyHash ?? null,
+      })
+    )
+    .digest('hex');
+};
+
 export const resolvePolicyForStage = (
   stage: SkillsStage,
   repoRoot: string = process.cwd()
@@ -301,16 +325,25 @@ export const resolvePolicyForStage = (
     const bundle = profileName
       ? `gate-policy.hard-mode.${profileName}.${stage}`
       : `gate-policy.hard-mode.${stage}`;
+    const hash = createPolicyTraceHash({
+      stage,
+      source: 'hard-mode',
+      blockOnOrAbove: hardModePolicy.blockOnOrAbove,
+      warnOnOrAbove: hardModePolicy.warnOnOrAbove,
+      sourcePolicyHash: profileName ?? undefined,
+    });
     return {
       policy: hardModePolicy,
       trace: {
         source: 'hard-mode',
         bundle,
-        hash: createPolicyTraceHash({
-          stage,
+        hash,
+        version: POLICY_TRACE_VERSION_HARD_MODE,
+        signature: createPolicyTraceSignature({
+          version: POLICY_TRACE_VERSION_HARD_MODE,
           source: 'hard-mode',
-          blockOnOrAbove: hardModePolicy.blockOnOrAbove,
-          warnOnOrAbove: hardModePolicy.warnOnOrAbove,
+          bundle,
+          hash,
           sourcePolicyHash: profileName ?? undefined,
         }),
       },
@@ -322,16 +355,25 @@ export const resolvePolicyForStage = (
   const stageOverride = loadedPolicy?.stages[stage];
 
   if (!stageOverride) {
+    const hash = createPolicyTraceHash({
+      stage,
+      source: 'default',
+      blockOnOrAbove: defaults.blockOnOrAbove,
+      warnOnOrAbove: defaults.warnOnOrAbove,
+    });
+    const bundle = `gate-policy.default.${stage}`;
     return {
       policy: defaults,
       trace: {
         source: 'default',
-        bundle: `gate-policy.default.${stage}`,
-        hash: createPolicyTraceHash({
-          stage,
+        bundle,
+        hash,
+        version: POLICY_TRACE_VERSION_DEFAULT,
+        signature: createPolicyTraceSignature({
+          version: POLICY_TRACE_VERSION_DEFAULT,
           source: 'default',
-          blockOnOrAbove: defaults.blockOnOrAbove,
-          warnOnOrAbove: defaults.warnOnOrAbove,
+          bundle,
+          hash,
         }),
       },
     };
@@ -343,17 +385,30 @@ export const resolvePolicyForStage = (
     warnOnOrAbove: stageOverride.warnOnOrAbove,
   };
 
+  const sourcePolicyHash = createSkillsPolicyDeterministicHash(loadedPolicy);
+  const bundle = `gate-policy.skills.policy.${stage}`;
+  const version = `policy-as-code/skills.policy@${loadedPolicy.version}`;
+  const hash = createPolicyTraceHash({
+    stage,
+    source: 'skills.policy',
+    blockOnOrAbove: resolvedPolicy.blockOnOrAbove,
+    warnOnOrAbove: resolvedPolicy.warnOnOrAbove,
+    sourcePolicyHash,
+  });
+
   return {
     policy: resolvedPolicy,
     trace: {
       source: 'skills.policy',
-      bundle: `gate-policy.skills.policy.${stage}`,
-      hash: createPolicyTraceHash({
-        stage,
+      bundle,
+      hash,
+      version,
+      signature: createPolicyTraceSignature({
+        version,
         source: 'skills.policy',
-        blockOnOrAbove: resolvedPolicy.blockOnOrAbove,
-        warnOnOrAbove: resolvedPolicy.warnOnOrAbove,
-        sourcePolicyHash: createSkillsPolicyDeterministicHash(loadedPolicy),
+        bundle,
+        hash,
+        sourcePolicyHash,
       }),
     },
   };