@nebulacomponents/citable 1.19.0 → 1.20.0

package/src/shared/runPackageVerifier.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { readJson, sha256File } from './io.js';
+import { sha256 } from './io.js';
 import { validateAgainst } from './schemaValidator.js';
 
 export class RunVerificationError extends Error {
@@ -12,6 +12,17 @@ export class RunVerificationError extends Error {
   }
 }
 
+function readStableBytes(file, runDir, relative) {
+  const first = fs.readFileSync(file);
+  const second = fs.readFileSync(file);
+  if (!first.equals(second)) {
+    throw new RunVerificationError(`Artifact changed while being verified: ${relative}`, {
+      code: 'PACKAGE_MUTATION', runDir, file: relative,
+    });
+  }
+  return first;
+}
+
 /**
  * Verifies the cryptographic and structural integrity of an audit run evidence package.
  *
@@ -28,13 +39,24 @@ export function verifyRunPackage(runDir, options = {}) {
     requireFindings = true,
     requireCompleted = false,
     requireChecksums = true,
+    ignoredFiles = [],
   } = options;
 
   if (!runDir || !fs.existsSync(runDir)) {
     throw new RunVerificationError(`Run directory not found: ${runDir}`, { code: 'RUN_NOT_FOUND', runDir });
   }
+  let rootStat;
+  try { rootStat = fs.lstatSync(runDir); } catch (error) {
+    throw new RunVerificationError(`Run directory cannot be inspected: ${error.message}`, { code: 'RUN_NOT_FOUND', runDir });
+  }
+  if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
+    throw new RunVerificationError(`Run path is not a real directory: ${runDir}`, { code: 'RUN_PATH_INVALID', runDir });
+  }
 
   const manifestPath = path.join(runDir, 'manifest.json');
+  if (fs.existsSync(manifestPath) && fs.lstatSync(manifestPath).isSymbolicLink()) {
+    throw new RunVerificationError('Run manifest.json is a symbolic link', { code: 'PACKAGE_SYMLINK', runDir, file: 'manifest.json' });
+  }
   if (!fs.existsSync(manifestPath)) {
     throw new RunVerificationError(`Run package is missing manifest.json at ${manifestPath}`, {
       code: 'MANIFEST_MISSING',
@@ -44,7 +66,7 @@ export function verifyRunPackage(runDir, options = {}) {
 
   let manifest;
   try {
-    manifest = readJson(manifestPath);
+    manifest = JSON.parse(readStableBytes(manifestPath, runDir, 'manifest.json').toString('utf8'));
   } catch (err) {
     throw new RunVerificationError(`Run manifest.json is invalid JSON: ${err.message}`, {
       code: 'MANIFEST_INVALID',
@@ -53,6 +75,12 @@ export function verifyRunPackage(runDir, options = {}) {
   }
 
   const schemaValidation = validateAgainst('run.schema.json', manifest);
+  if (Object.prototype.hasOwnProperty.call(manifest, 'schema_version')
+    && ![1, 2].includes(manifest.schema_version)) {
+    throw new RunVerificationError(`Unsupported run manifest schema_version: ${String(manifest.schema_version)}`, {
+      code: 'MANIFEST_SCHEMA_UNSUPPORTED', runDir, schema_version: manifest.schema_version,
+    });
+  }
   if (!schemaValidation.valid) {
     throw new RunVerificationError(`Run manifest violates run.schema.json: ${schemaValidation.errors.join('; ')}`, {
       code: 'MANIFEST_SCHEMA_INVALID',
@@ -69,42 +97,94 @@ export function verifyRunPackage(runDir, options = {}) {
     });
   }
 
+  // A sealed run is closed-world: every regular file except the checksum
+  // index itself must be listed, and every listed path must be safe.  Do not
+  // use stat() here because it follows symlinks and could verify bytes outside
+  // the package directory.
+  const packageFiles = [];
+  const walk = (directory) => {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const absolute = path.join(directory, entry.name);
+      const relative = path.relative(runDir, absolute).split(path.sep).join('/');
+      if (entry.isSymbolicLink()) {
+        throw new RunVerificationError(`Run package contains symbolic link: ${relative}`, {
+          code: 'PACKAGE_SYMLINK', runDir, file: relative,
+        });
+      }
+      if (entry.isDirectory()) walk(absolute);
+      else if (entry.isFile()) packageFiles.push(relative);
+      else throw new RunVerificationError(`Run package contains unsupported filesystem entry: ${relative}`, {
+        code: 'PACKAGE_ENTRY_INVALID', runDir, file: relative,
+      });
+    }
+  };
+  walk(runDir);
+  const ignored = new Set(ignoredFiles);
+
   // Verify checksums.json
   const checksumsPath = path.join(runDir, 'checksums.json');
   let checksumsVerified = false;
+  let artifactHashes = {};
+  const artifactBytes = new Map();
+  const retainedArtifactNames = new Set(['findings.json', 'coverage.json', 'summary.json']);
   if (fs.existsSync(checksumsPath)) {
+    if (fs.lstatSync(checksumsPath).isSymbolicLink()) throw new RunVerificationError('checksums.json is a symbolic link', { code: 'PACKAGE_SYMLINK', runDir, file: 'checksums.json' });
     let checksums;
     try {
-      checksums = readJson(checksumsPath);
+      checksums = JSON.parse(readStableBytes(checksumsPath, runDir, 'checksums.json').toString('utf8'));
     } catch (err) {
       throw new RunVerificationError(`checksums.json is invalid JSON: ${err.message}`, {
         code: 'CHECKSUMS_INVALID',
         runDir,
       });
     }
+    artifactHashes = checksums;
 
     const tamperedFiles = [];
     const missingFiles = [];
 
+    const safePath = (value) => typeof value === 'string'
+      && value.length > 0
+      && !path.isAbsolute(value)
+      && !value.includes('\\')
+      && !value.split('/').includes('..')
+      && !value.split('/').includes('')
+      && !/^[a-z][a-z0-9+.-]*:/i.test(value);
     for (const [relPath, expectedHash] of Object.entries(checksums)) {
+      if (!safePath(relPath) || relPath === 'checksums.json') {
+        throw new RunVerificationError(`unsafe checksum path (escapes the run package): ${relPath}`, {
+          code: 'CHECKSUM_PATH_INVALID', runDir, file: relPath,
+        });
+      }
       const artifactPath = path.join(runDir, relPath);
       if (!fs.existsSync(artifactPath)) {
         missingFiles.push(relPath);
         continue;
       }
-      const actualHash = sha256File(artifactPath);
+      const artifactStat = fs.lstatSync(artifactPath);
+      if (artifactStat.isSymbolicLink() || !artifactStat.isFile()) {
+        throw new RunVerificationError(`checksum artifact is not a regular file: ${relPath}`, { code: 'PACKAGE_SYMLINK', runDir, file: relPath });
+      }
+      const bytes = readStableBytes(artifactPath, runDir, relPath);
+      if (retainedArtifactNames.has(relPath)) artifactBytes.set(relPath, bytes);
+      const actualHash = sha256(bytes);
       if (actualHash !== expectedHash) {
         tamperedFiles.push({ file: relPath, expected: expectedHash, actual: actualHash });
       }
     }
 
-    if (tamperedFiles.length > 0 || missingFiles.length > 0) {
+    const expectedFiles = Object.keys(checksums).sort();
+    const actualFiles = packageFiles.filter((file) => file !== 'checksums.json' && !ignored.has(file)).sort();
+    const unexpectedFiles = actualFiles.filter((file) => !expectedFiles.includes(file));
+    const unlistedFiles = expectedFiles.filter((file) => !actualFiles.includes(file));
+    if (tamperedFiles.length > 0 || missingFiles.length > 0 || unexpectedFiles.length > 0 || unlistedFiles.length > 0) {
       throw new RunVerificationError(
-        `Cryptographic verification failed for run package: ${tamperedFiles.length} tampered files, ${missingFiles.length} missing files`,
+        `Cryptographic verification failed for run package (checksum mismatch; integrity failed; completeness failure; unsealed): ${tamperedFiles.length} tampered files, ${missingFiles.length + unlistedFiles.length} missing files, ${unexpectedFiles.length} unexpected files`,
         {
           code: 'CHECKSUM_MISMATCH',
           tamperedFiles,
-          missingFiles,
+          missingFiles: [...missingFiles, ...unlistedFiles],
+          unexpectedFiles,
           runDir,
         }
       );
@@ -122,10 +202,19 @@ export function verifyRunPackage(runDir, options = {}) {
   let findings = null;
   if (fs.existsSync(findingsPath)) {
     try {
-      findings = readJson(findingsPath);
+      if (fs.lstatSync(findingsPath).isSymbolicLink()) throw new Error('findings.json is a symbolic link');
+      const findingsBytes = artifactBytes.get('findings.json') || readStableBytes(findingsPath, runDir, 'findings.json');
+      artifactBytes.set('findings.json', findingsBytes);
+      findings = JSON.parse(findingsBytes.toString('utf8'));
       if (!Array.isArray(findings)) {
         throw new Error('findings.json must contain an array of findings');
       }
+      for (const [index, finding] of findings.entries()) {
+        const findingValidation = validateAgainst('finding.schema.json', finding);
+        if (!findingValidation.valid) {
+          throw new Error(`finding[${index}] violates finding.schema.json: ${findingValidation.errors.join('; ')}`);
+        }
+      }
     } catch (err) {
       throw new RunVerificationError(`findings.json is malformed: ${err.message}`, {
         code: 'FINDINGS_MALFORMED',
@@ -149,5 +238,7 @@ export function verifyRunPackage(runDir, options = {}) {
     findingsPath: fs.existsSync(findingsPath) ? findingsPath : null,
     findingsCount: Array.isArray(findings) ? findings.length : 0,
     findings,
+    artifactHashes,
+    artifactBytes,
   };
 }

package/src/shared/verifiedRunLoader.js

@@ -0,0 +1,129 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readJson, sha256File } from './io.js';
+import { verifyRunPackage, RunVerificationError } from './runPackageVerifier.js';
+import { validateAgainst } from './schemaValidator.js';
+
+export const VERIFIED_RUN_LOADER_VERSION = 'verified-run-loader-v1';
+
+export class VerifiedRunLoadError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = 'VerifiedRunLoadError';
+    this.code = details.code || 'VERIFIED_RUN_LOAD_FAILED';
+    this.details = details;
+  }
+}
+
+function readContractArtifact(runDir, file, schema, { required = true, bytes = null } = {}) {
+  const filePath = path.join(runDir, file);
+  if (!fs.existsSync(filePath)) {
+    if (required) throw new VerifiedRunLoadError(`Verified run is missing ${file}`, { code: 'ARTIFACT_MISSING', file });
+    return null;
+  }
+  if (fs.lstatSync(filePath).isSymbolicLink()) {
+    throw new VerifiedRunLoadError(`${file} is a symbolic link`, { code: 'PACKAGE_SYMLINK', file });
+  }
+  let value;
+  try {
+    value = bytes ? JSON.parse(bytes.toString('utf8')) : readJson(filePath);
+  } catch (error) {
+    throw new VerifiedRunLoadError(`${file} is invalid JSON: ${error.message}`, { code: 'ARTIFACT_INVALID', file });
+  }
+  const validation = schema ? validateAgainst(schema, value) : { valid: true, errors: [] };
+  if (!validation.valid) {
+    throw new VerifiedRunLoadError(`${file} violates ${schema}: ${validation.errors.join('; ')}`, {
+      code: 'ARTIFACT_SCHEMA_INVALID', file, errors: validation.errors,
+    });
+  }
+  return value;
+}
+
+function readFindingsArtifact(runDir, bytes = null) {
+  const findings = readContractArtifact(runDir, 'findings.json', null, { bytes });
+  if (!Array.isArray(findings)) throw new VerifiedRunLoadError('findings.json must contain an array of findings', { code: 'ARTIFACT_SCHEMA_INVALID', file: 'findings.json' });
+  for (const [index, finding] of findings.entries()) {
+    const validation = validateAgainst('finding.schema.json', finding);
+    if (!validation.valid) throw new VerifiedRunLoadError(`findings.json finding[${index}] violates finding.schema.json: ${validation.errors.join('; ')}`, { code: 'ARTIFACT_SCHEMA_INVALID', file: 'findings.json' });
+  }
+  return findings;
+}
+
+/**
+ * Load a run only after its closed-world checksum seal and execution contracts
+ * have been verified. Consumers must use this API rather than reading
+ * findings.json directly: the returned findings are bound to the verified
+ * package, manifest, and (when present) coverage artifact.
+ *
+ * Legacy packages can be opened explicitly for migration. Their coverage is
+ * indeterminate and never receives a synthesized complete default.
+ */
+export function loadVerifiedRun(runDir, {
+  requireCompletedExecution = true,
+  allowLegacy = false,
+  requireCoverage = !allowLegacy,
+} = {}) {
+  try {
+    let verification;
+    try {
+      verification = verifyRunPackage(runDir, {
+      requireFindings: true,
+      requireCompleted: requireCompletedExecution,
+      requireChecksums: !allowLegacy,
+      });
+    } catch (error) {
+      if (!allowLegacy || !['CHECKSUMS_MISSING', 'MANIFEST_MISSING'].includes(error.code)) throw error;
+      const manifestPath = path.join(runDir, 'manifest.json');
+      const manifest = fs.existsSync(manifestPath) ? readJson(manifestPath) : { run_id: path.basename(runDir), status: 'incomplete' };
+      const findings = readFindingsArtifact(runDir);
+      const coverageFile = path.join(runDir, 'coverage.json');
+      const coverage = fs.existsSync(coverageFile) ? readContractArtifact(runDir, 'coverage.json', 'audit-coverage.schema.json') : null;
+      const summary = readContractArtifact(runDir, 'summary.json', 'summary.schema.json', { required: false });
+      return {
+        verified: false, verification_version: VERIFIED_RUN_LOADER_VERSION,
+        integrity_mode: 'legacy_unverified', package_dir: path.resolve(runDir),
+        package_hash: null, manifest, findings, findingsCount: findings.length,
+        coverage, summary, legacy: true,
+        coverage_status: coverage?.coverage_status || 'indeterminate', determination_status: 'indeterminate',
+        checksumsVerified: false,
+        artifactHashes: {
+          ...(fs.existsSync(path.join(runDir, 'manifest.json')) ? { 'manifest.json': sha256File(path.join(runDir, 'manifest.json')) } : {}),
+          'findings.json': sha256File(path.join(runDir, 'findings.json')),
+          ...(fs.existsSync(coverageFile) ? { 'coverage.json': sha256File(coverageFile) } : {}),
+        },
+      };
+    }
+
+    const coveragePath = path.join(runDir, 'coverage.json');
+    const hasCoverage = fs.existsSync(coveragePath);
+    if (!hasCoverage && !allowLegacy && requireCoverage) {
+      throw new VerifiedRunLoadError('Verified run is missing coverage.json; use explicit legacy mode to open historical packages', {
+        code: 'COVERAGE_MISSING',
+      });
+    }
+    const coverage = hasCoverage ? readContractArtifact(runDir, 'coverage.json', 'audit-coverage.schema.json', { bytes: verification.artifactBytes.get('coverage.json') }) : null;
+    const summary = readContractArtifact(runDir, 'summary.json', 'summary.schema.json', { required: false, bytes: verification.artifactBytes.get('summary.json') });
+
+    return {
+      ...verification,
+      verified: hasCoverage,
+      verification_version: VERIFIED_RUN_LOADER_VERSION,
+      integrity_mode: hasCoverage ? 'sealed' : 'legacy_unverified',
+      package_dir: path.resolve(runDir),
+      package_hash: verification.checksumsVerified ? sha256File(path.join(runDir, 'checksums.json')) : null,
+      findings: verification.findings,
+      coverage,
+      summary,
+      legacy: !hasCoverage,
+      coverage_status: coverage?.coverage_status || 'indeterminate',
+      determination_status: coverage ? verification.manifest.determination_status : 'indeterminate',
+      artifactHashes: verification.artifactHashes,
+    };
+  } catch (error) {
+    if (error instanceof VerifiedRunLoadError) throw error;
+    if (error instanceof RunVerificationError) {
+      throw new VerifiedRunLoadError(error.message, { code: error.code, cause: error });
+    }
+    throw new VerifiedRunLoadError(error.message, { cause: error });
+  }
+}