@saiteja1123/mcp-server 1.1.4 → 1.1.6

package/src/deep-scan/ralph-accept.js

@@ -0,0 +1,510 @@
+import crypto from 'crypto';
+import fs from 'fs/promises';
+import path from 'path';
+import { createArtifactRef, validateRunIdSegment } from './contracts.js';
+import { assertSourceSafePayload, cloneSourceSafe } from './sourceSafe.js';
+
+export const ACCEPTED_RISK_REGISTER_SCHEMA_VERSION = 'accepted_risk_register.v1';
+export const ACCEPTED_RISK_STATE_SCHEMA_VERSION = 'ralph_accepted_risk.v1';
+export const ACCEPTED_RISK_STEPPER_ID = 'ralph.accept';
+export const ACCEPTED_RISK_STEPPER_VERSION = '1.0.0';
+export const ACCEPTED_RISK_STATUSES = Object.freeze(['active', 'expired']);
+export const ACCEPTED_RISK_REPORT_VISIBILITY = Object.freeze(['visible', 'summary_only']);
+export const ACCEPTED_RISK_HIGH_RISK_SEVERITIES = Object.freeze(['critical', 'high']);
+
+const REGISTER_FILE = '.vibesecur/accepted-risks.json';
+const STATE_FILE = 'accepted-risk.json';
+const SHA256 = /^[a-f0-9]{64}$/i;
+const UUIDISH = /^[a-zA-Z0-9_.:-]+$/;
+const SEVERITIES = new Set(['critical', 'high', 'medium', 'low']);
+const HIGH_RISK = new Set(ACCEPTED_RISK_HIGH_RISK_SEVERITIES);
+const nowIso = () => new Date().toISOString();
+
+function stableSort(value) {
+  if (Array.isArray(value)) return value.map(stableSort);
+  if (!value || typeof value !== 'object') return value;
+  return Object.keys(value)
+    .sort()
+    .reduce((acc, key) => {
+      acc[key] = stableSort(value[key]);
+      return acc;
+    }, {});
+}
+
+function stableStringify(value) {
+  return JSON.stringify(stableSort(value));
+}
+
+function sha256(value) {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+function requireString(value, name, { max = 500, pattern = null } = {}) {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`${name} must be a non-empty string`);
+  if (value.length > max) throw new Error(`${name} must be ${max} characters or fewer`);
+  if (pattern && !pattern.test(value)) throw new Error(`${name} has an invalid format`);
+  return value;
+}
+
+function optionalString(value, name, options) {
+  if (value === undefined || value === null) return null;
+  return requireString(value, name, options);
+}
+
+function requireIsoDate(value, name) {
+  requireString(value, name, { max: 40 });
+  if (Number.isNaN(Date.parse(value))) throw new Error(`${name} must be an ISO timestamp`);
+  return value;
+}
+
+function optionalIsoDate(value, name) {
+  if (value === undefined || value === null) return null;
+  return requireIsoDate(value, name);
+}
+
+function asArray(value, name) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new Error(`${name} must be an array`);
+  return value;
+}
+
+function normalizeSeverity(value) {
+  const severity = String(value || 'medium').toLowerCase();
+  return SEVERITIES.has(severity) ? severity : 'medium';
+}
+
+function isHighRisk(severity) {
+  return HIGH_RISK.has(normalizeSeverity(severity));
+}
+
+// A single accepted-risk record is human-authored audit metadata, never source.
+export function validateAcceptedRiskRecord(input = {}) {
+  assertSourceSafePayload(input, 'acceptedRisk.record');
+  const severity = normalizeSeverity(input.severity);
+  const findingKey = optionalString(input.findingKey, 'acceptedRisk.findingKey', { max: 64, pattern: SHA256 });
+  const findingId = optionalString(input.findingId, 'acceptedRisk.findingId', { max: 120, pattern: UUIDISH });
+  if (!findingKey && !findingId) {
+    throw new Error('acceptedRisk record requires findingKey or findingId to attach to a tracked finding');
+  }
+  const reportVisibility = optionalString(input.reportVisibility, 'acceptedRisk.reportVisibility', { max: 40 }) || 'visible';
+  if (!ACCEPTED_RISK_REPORT_VISIBILITY.includes(reportVisibility)) {
+    throw new Error(`acceptedRisk.reportVisibility must be one of ${ACCEPTED_RISK_REPORT_VISIBILITY.join(', ')} (accepted risk is never hidden)`);
+  }
+  const reason = optionalString(input.reason, 'acceptedRisk.reason', { max: 1000 });
+  const reviewer = optionalString(input.reviewer, 'acceptedRisk.reviewer', { max: 255 });
+  const acceptedAt = input.acceptedAt ? requireIsoDate(input.acceptedAt, 'acceptedRisk.acceptedAt') : nowIso();
+  const expiresAt = optionalIsoDate(input.expiresAt, 'acceptedRisk.expiresAt');
+  const reviewBy = optionalIsoDate(input.reviewBy, 'acceptedRisk.reviewBy');
+
+  if (isHighRisk(severity)) {
+    if (!reason) throw new Error('High-risk accepted risk requires an explicit reason');
+    if (!reviewer) throw new Error('High-risk accepted risk requires reviewer metadata');
+    if (!expiresAt) throw new Error('High-risk accepted risk requires an expiresAt review/expiry date');
+  }
+  if (expiresAt && Date.parse(expiresAt) <= Date.parse(acceptedAt)) {
+    throw new Error('acceptedRisk.expiresAt must be after acceptedAt');
+  }
+
+  const record = {
+    riskId: requireString(input.riskId, 'acceptedRisk.riskId', { max: 160, pattern: UUIDISH }),
+    findingKey,
+    findingId,
+    taskId: optionalString(input.taskId, 'acceptedRisk.taskId', { max: 120, pattern: UUIDISH }),
+    severity,
+    reason,
+    reviewer,
+    acceptedAt,
+    expiresAt,
+    reviewBy,
+    reportVisibility,
+    metadata: cloneSourceSafe(input.metadata || {}, 'acceptedRisk.metadata'),
+  };
+  assertSourceSafePayload(record, 'acceptedRisk.record');
+  return record;
+}
+
+export function validateAcceptedRiskRegister(input = {}) {
+  assertSourceSafePayload(input, 'acceptedRiskRegister');
+  const records = asArray(input.records, 'acceptedRiskRegister.records').map(validateAcceptedRiskRecord);
+  const riskIds = new Set();
+  for (const record of records) {
+    if (riskIds.has(record.riskId)) {
+      throw new Error(`acceptedRiskRegister has duplicate riskId ${record.riskId}`);
+    }
+    riskIds.add(record.riskId);
+  }
+  const register = {
+    schemaVersion: requireString(input.schemaVersion, 'acceptedRiskRegister.schemaVersion', { max: 80, pattern: UUIDISH }),
+    generatedAt: input.generatedAt ? requireIsoDate(input.generatedAt, 'acceptedRiskRegister.generatedAt') : nowIso(),
+    updatedAt: input.updatedAt ? requireIsoDate(input.updatedAt, 'acceptedRiskRegister.updatedAt') : nowIso(),
+    records,
+    privacy: cloneSourceSafe(input.privacy || {
+      rawSourceStored: false,
+      secretValuesCaptured: false,
+      complianceCertification: false,
+      artifactStorage: 'local_metadata_only',
+    }, 'acceptedRiskRegister.privacy'),
+  };
+  if (register.schemaVersion !== ACCEPTED_RISK_REGISTER_SCHEMA_VERSION) {
+    throw new Error(`acceptedRiskRegister.schemaVersion must be ${ACCEPTED_RISK_REGISTER_SCHEMA_VERSION}`);
+  }
+  return register;
+}
+
+function isExpired(record, generatedAt) {
+  if (!record.expiresAt) return false;
+  return Date.parse(record.expiresAt) <= Date.parse(generatedAt);
+}
+
+// Returns only ACTIVE (non-expired) accepted-risk records keyed for comparison precedence.
+export function evaluateActiveAcceptedRisk({ register = {}, generatedAt = nowIso() } = {}) {
+  const safeRegister = validateAcceptedRiskRegister({
+    schemaVersion: ACCEPTED_RISK_REGISTER_SCHEMA_VERSION,
+    ...register,
+  });
+  const byFindingKey = new Map();
+  const byFindingId = new Map();
+  const active = [];
+  for (const record of safeRegister.records) {
+    if (isExpired(record, generatedAt)) continue;
+    active.push(record);
+    if (record.findingKey && !byFindingKey.has(record.findingKey)) byFindingKey.set(record.findingKey, record);
+    if (record.findingId && !byFindingId.has(record.findingId)) byFindingId.set(record.findingId, record);
+  }
+  return { active, byFindingKey, byFindingId };
+}
+
+// Index the register for comparison precedence. `known*` cover every record
+// (active or expired) so the register, when present, is authoritative over the
+// legacy AgentFixTask acceptedRiskRef field. `active*` cover only non-expired
+// records that should still mark a finding as accepted risk.
+export function indexAcceptedRiskForComparison({ register = {}, generatedAt = nowIso() } = {}) {
+  const safeRegister = validateAcceptedRiskRegister({
+    schemaVersion: ACCEPTED_RISK_REGISTER_SCHEMA_VERSION,
+    ...register,
+  });
+  const knownByKey = new Map();
+  const knownById = new Map();
+  const activeByKey = new Map();
+  const activeById = new Map();
+  for (const record of safeRegister.records) {
+    if (record.findingKey && !knownByKey.has(record.findingKey)) knownByKey.set(record.findingKey, record);
+    if (record.findingId && !knownById.has(record.findingId)) knownById.set(record.findingId, record);
+    if (isExpired(record, generatedAt)) continue;
+    if (record.findingKey && !activeByKey.has(record.findingKey)) activeByKey.set(record.findingKey, record);
+    if (record.findingId && !activeById.has(record.findingId)) activeById.set(record.findingId, record);
+  }
+  return { knownByKey, knownById, activeByKey, activeById };
+}
+
+export function buildAcceptedRiskStateArtifact({
+  register = {},
+  comparisonArtifact = null,
+  generatedAt = nowIso(),
+  sourceRefs = {},
+} = {}) {
+  const safeRegister = validateAcceptedRiskRegister({
+    schemaVersion: ACCEPTED_RISK_REGISTER_SCHEMA_VERSION,
+    ...register,
+  });
+  const at = requireIsoDate(generatedAt, 'acceptedRiskState.generatedAt');
+
+  // Build a quick lookup of unresolved comparison findings so we can flag
+  // accepted risks whose expiry has reverted a finding to unresolved.
+  const unresolvedStatuses = new Set(['new', 'worsened', 'unchanged', 'manualReview']);
+  const unresolvedByKey = new Set();
+  const unresolvedById = new Set();
+  if (comparisonArtifact && Array.isArray(comparisonArtifact.comparisons)) {
+    for (const row of comparisonArtifact.comparisons) {
+      if (!unresolvedStatuses.has(row.status)) continue;
+      if (row.findingKey) unresolvedByKey.add(row.findingKey);
+      const id = row.current?.id || row.previous?.id;
+      if (id) unresolvedById.add(id);
+    }
+  }
+
+  const records = safeRegister.records.map((record) => {
+    const expired = isExpired(record, at);
+    const stillUnresolved = (record.findingKey && unresolvedByKey.has(record.findingKey))
+      || (record.findingId && unresolvedById.has(record.findingId));
+    return {
+      ...record,
+      status: expired ? 'expired' : 'active',
+      appliedToComparison: !expired,
+      revertedToUnresolved: Boolean(expired && stillUnresolved),
+    };
+  }).sort((a, b) => a.riskId.localeCompare(b.riskId));
+
+  const activeRecords = records.filter((record) => record.status === 'active');
+  const expiredRecords = records.filter((record) => record.status === 'expired');
+
+  const artifact = {
+    schemaVersion: ACCEPTED_RISK_STATE_SCHEMA_VERSION,
+    generatedAt: at,
+    sources: {
+      acceptedRiskRegister: sourceRefs.acceptedRiskRegister || 'accepted_risk_register',
+      ralphComparison: sourceRefs.ralphComparison || null,
+    },
+    summary: {
+      totalRecords: records.length,
+      activeCount: activeRecords.length,
+      expiredCount: expiredRecords.length,
+      highRiskActiveCount: activeRecords.filter((record) => isHighRisk(record.severity)).length,
+      expiredRevertedCount: expiredRecords.filter((record) => record.revertedToUnresolved).length,
+    },
+    reportHandoff: {
+      acceptedRiskVisible: records.length > 0,
+      activeAcceptedRisk: activeRecords.map((record) => ({
+        riskId: record.riskId,
+        findingKey: record.findingKey,
+        findingId: record.findingId,
+        severity: record.severity,
+        reviewer: record.reviewer,
+        expiresAt: record.expiresAt,
+        reportVisibility: record.reportVisibility,
+      })),
+      expiredAcceptedRisk: expiredRecords.map((record) => ({
+        riskId: record.riskId,
+        findingKey: record.findingKey,
+        findingId: record.findingId,
+        severity: record.severity,
+        expiresAt: record.expiresAt,
+        revertedToUnresolved: record.revertedToUnresolved,
+      })),
+      note: 'Accepted risk is shown separately from resolved findings and never removes the underlying finding from history. Expired accepted risk reverts the finding to unresolved.',
+    },
+    records,
+    privacy: {
+      rawSourceStored: false,
+      secretValuesCaptured: false,
+      complianceCertification: false,
+      artifactStorage: 'local_metadata_only',
+    },
+  };
+  return validateAcceptedRiskStateArtifact(artifact);
+}
+
+function validateAcceptedRiskStateRecord(input = {}) {
+  const base = validateAcceptedRiskRecord(input);
+  const status = requireString(input.status, 'acceptedRiskState.record.status', { max: 40 });
+  if (!ACCEPTED_RISK_STATUSES.includes(status)) {
+    throw new Error(`acceptedRiskState.record.status must be one of ${ACCEPTED_RISK_STATUSES.join(', ')}`);
+  }
+  if (isHighRisk(base.severity) && !base.expiresAt) {
+    throw new Error('High-risk accepted-risk state records require expiresAt');
+  }
+  return {
+    ...base,
+    status,
+    appliedToComparison: Boolean(input.appliedToComparison),
+    revertedToUnresolved: Boolean(input.revertedToUnresolved),
+  };
+}
+
+export function validateAcceptedRiskStateArtifact(input = {}) {
+  assertSourceSafePayload(input, 'acceptedRiskStateArtifact');
+  const artifact = {
+    schemaVersion: requireString(input.schemaVersion, 'acceptedRiskState.schemaVersion', { max: 80, pattern: UUIDISH }),
+    generatedAt: requireIsoDate(input.generatedAt, 'acceptedRiskState.generatedAt'),
+    sources: cloneSourceSafe(input.sources || {}, 'acceptedRiskState.sources'),
+    summary: cloneSourceSafe(input.summary || {}, 'acceptedRiskState.summary'),
+    reportHandoff: cloneSourceSafe(input.reportHandoff || {}, 'acceptedRiskState.reportHandoff'),
+    records: asArray(input.records, 'acceptedRiskState.records').map(validateAcceptedRiskStateRecord),
+    privacy: cloneSourceSafe(input.privacy || {}, 'acceptedRiskState.privacy'),
+  };
+  if (artifact.schemaVersion !== ACCEPTED_RISK_STATE_SCHEMA_VERSION) {
+    throw new Error(`acceptedRiskState.schemaVersion must be ${ACCEPTED_RISK_STATE_SCHEMA_VERSION}`);
+  }
+  return artifact;
+}
+
+export function hashAcceptedRiskStateArtifact(artifact) {
+  assertSourceSafePayload(artifact, 'acceptedRiskStateArtifact');
+  return sha256(stableStringify(validateAcceptedRiskStateArtifact(artifact)));
+}
+
+export async function readAcceptedRiskRegister({ rootPath }) {
+  const target = path.join(path.resolve(rootPath), REGISTER_FILE);
+  try {
+    const raw = await fs.readFile(target, 'utf8');
+    const parsed = JSON.parse(raw);
+    return { register: validateAcceptedRiskRegister(parsed), raw, exists: true };
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return {
+        register: validateAcceptedRiskRegister({ schemaVersion: ACCEPTED_RISK_REGISTER_SCHEMA_VERSION, records: [] }),
+        raw: null,
+        exists: false,
+      };
+    }
+    throw error;
+  }
+}
+
+async function writeRegisterFile({ rootPath, register }) {
+  const safeRegister = validateAcceptedRiskRegister(register);
+  const relativeUri = REGISTER_FILE;
+  const target = path.join(path.resolve(rootPath), relativeUri);
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  const serialized = `${JSON.stringify(stableSort(safeRegister), null, 2)}\n`;
+  const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+  await fs.writeFile(tmp, serialized, 'utf8');
+  await fs.rename(tmp, target);
+  return { uri: relativeUri, hash: sha256(serialized) };
+}
+
+// Human/CLI/MCP entrypoint: append or update one accepted-risk record by riskId.
+export async function appendAcceptedRiskRecord({ rootPath, record }) {
+  const newRecord = validateAcceptedRiskRecord({
+    ...record,
+    riskId: record?.riskId || `risk_${crypto.randomUUID()}`,
+  });
+  const { register } = await readAcceptedRiskRegister({ rootPath });
+  const others = register.records.filter((existing) => existing.riskId !== newRecord.riskId);
+  const updated = validateAcceptedRiskRegister({
+    schemaVersion: ACCEPTED_RISK_REGISTER_SCHEMA_VERSION,
+    generatedAt: register.generatedAt,
+    updatedAt: nowIso(),
+    records: [...others, newRecord],
+    privacy: register.privacy,
+  });
+  const written = await writeRegisterFile({ rootPath, register: updated });
+  return { record: newRecord, register: updated, ...written };
+}
+
+export async function writeAcceptedRiskStateArtifact({ rootPath, runId, artifact }) {
+  const safeArtifact = validateAcceptedRiskStateArtifact(artifact);
+  const safeRunId = validateRunIdSegment(runId, 'runId');
+  const relativeUri = `.vibesecur/deep-scans/${safeRunId}/${STATE_FILE}`;
+  const target = path.join(path.resolve(rootPath), relativeUri);
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  const serialized = `${JSON.stringify(stableSort(safeArtifact), null, 2)}\n`;
+  const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+  await fs.writeFile(tmp, serialized, 'utf8');
+  await fs.rename(tmp, target);
+  return { uri: relativeUri, hash: sha256(serialized) };
+}
+
+async function readLocalArtifact({ rootPath, ref, type }) {
+  if (!ref || ref.type !== type || ref.storage !== 'local' || !ref.uri) {
+    throw new Error(`Accepted-risk tracking requires a local ${type} artifact reference`);
+  }
+  const resolvedRoot = path.resolve(rootPath);
+  const target = path.resolve(resolvedRoot, ref.uri);
+  const relative = path.relative(resolvedRoot, target);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error(`Accepted-risk artifact ref for ${type} escapes the bound root`);
+  }
+  const raw = await fs.readFile(target, 'utf8');
+  if (!ref.hash) {
+    throw new Error(`Accepted-risk tracking requires ${type} artifact refs to include a hash`);
+  }
+  const actualHash = sha256(raw);
+  if (actualHash.toLowerCase() !== String(ref.hash).toLowerCase()) {
+    throw new Error(`Accepted-risk ${type} artifact hash mismatch: expected ${ref.hash}, got ${actualHash}`);
+  }
+  const parsed = JSON.parse(raw);
+  assertSourceSafePayload(parsed, `acceptedRisk.${type}`);
+  return parsed;
+}
+
+function findArtifactRef(state, type, preferredKeys = []) {
+  const artifacts = state?.artifacts || {};
+  for (const key of preferredKeys) {
+    if (artifacts[key]?.type === type) return artifacts[key];
+  }
+  return Object.values(artifacts).find((ref) => ref?.type === type) || null;
+}
+
+export function ralphAcceptStepper() {
+  return {
+    id: ACCEPTED_RISK_STEPPER_ID,
+    version: ACCEPTED_RISK_STEPPER_VERSION,
+    title: 'Ralph Accepted Risk Stepper',
+    category: 'ralph_loop',
+    requiredInputs: [],
+    producedArtifacts: ['ralph_accepted_risk'],
+    defaultTimeoutMs: 30000,
+    async run({ runId, config = {}, state = {}, tools = {} }) {
+      const rootPath = tools.rootPath || config.rootPath || '.';
+      const startedAt = nowIso();
+      const { register, exists } = await readAcceptedRiskRegister({ rootPath });
+      if (!exists || register.records.length === 0) {
+        return {
+          stepperId: ACCEPTED_RISK_STEPPER_ID,
+          version: ACCEPTED_RISK_STEPPER_VERSION,
+          status: 'skipped',
+          startedAt,
+          finishedAt: nowIso(),
+          evidence: [],
+          findings: [],
+          artifacts: [],
+          receipts: [],
+          summary: 'Accepted-risk evaluation skipped because no accepted-risk register exists.',
+          skippedReason: 'No .vibesecur/accepted-risks.json register records present.',
+          nextActions: ['Record an accepted risk with deepScanAcceptRisk (MCP) or deep-scan-accept-risk (CLI) before relying on this artifact.'],
+        };
+      }
+
+      const comparisonRef = findArtifactRef(state, 'ralph_comparison', ['ralph.compare']);
+      const comparisonArtifact = comparisonRef
+        ? await readLocalArtifact({ rootPath, ref: comparisonRef, type: 'ralph_comparison' })
+        : null;
+
+      const generatedAt = config.generatedAt || startedAt;
+      const artifact = buildAcceptedRiskStateArtifact({
+        register,
+        comparisonArtifact,
+        generatedAt,
+        sourceRefs: {
+          acceptedRiskRegister: 'accepted_risk_register',
+          ralphComparison: comparisonRef?.id || null,
+        },
+      });
+      const contentHash = hashAcceptedRiskStateArtifact(artifact);
+      const written = await writeAcceptedRiskStateArtifact({ rootPath, runId, artifact });
+      const safeRunId = validateRunIdSegment(runId, 'runId');
+      const ref = createArtifactRef({
+        id: `artifact-${safeRunId}-ralph-accepted-risk`,
+        type: 'ralph_accepted_risk',
+        storage: 'local',
+        uri: written.uri,
+        hash: written.hash,
+        preview: 'Accepted-risk state with reason/reviewer/expiry metadata and active/expired status only.',
+        metadata: {
+          schemaVersion: ACCEPTED_RISK_STATE_SCHEMA_VERSION,
+          contentHash,
+          generatedBy: ACCEPTED_RISK_STEPPER_ID,
+          activeCount: artifact.summary.activeCount,
+          expiredCount: artifact.summary.expiredCount,
+          expiredRevertedCount: artifact.summary.expiredRevertedCount,
+        },
+      });
+
+      return {
+        stepperId: ACCEPTED_RISK_STEPPER_ID,
+        version: ACCEPTED_RISK_STEPPER_VERSION,
+        status: 'passed',
+        startedAt,
+        finishedAt: nowIso(),
+        evidence: [{
+          type: 'hash',
+          label: 'Accepted-risk state artifact hash',
+          hash: ref.hash,
+          preview: 'Accepted-risk state artifact written locally.',
+          summary: `${artifact.summary.activeCount} active, ${artifact.summary.expiredCount} expired accepted-risk record(s).`,
+          metadata: {
+            artifactId: ref.id,
+            contentHash,
+            ralphComparisonArtifactId: comparisonRef?.id || null,
+          },
+        }],
+        findings: [],
+        artifacts: [ref],
+        receipts: [],
+        summary: `Accepted-risk evaluation generated: ${artifact.summary.activeCount} active, ${artifact.summary.expiredCount} expired, ${artifact.summary.expiredRevertedCount} reverted to unresolved.`,
+        nextActions: ['Use accepted-risk state in reports/passports; expired accepted risk must be re-reviewed or fixed before release reliance.'],
+      };
+    },
+  };
+}