Hermes Attestation Guardian

import crypto from "node:crypto";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { defaultFeedStatePath, getFeedVerificationStatus } from "./feed.mjs";

export const SCHEMA_VERSION = "0.0.1";
export const SKILL_NAME = "hermes-attestation-guardian";
export const SKILL_VERSION = "0.0.1";
export const DIGEST_ALGORITHM = "sha256";

function isPlainObject(value) {
  return value && typeof value === "object" && !Array.isArray(value);
}

export function stableSortObject(value) {
  if (Array.isArray(value)) {
    return value.map(stableSortObject);
  }
  if (!isPlainObject(value)) {
    return value;
  }

  const out = {};
  for (const key of Object.keys(value).sort()) {
    out[key] = stableSortObject(value[key]);
  }
  return out;
}

export function stableStringify(value, spacing = 2) {
  return JSON.stringify(stableSortObject(value), null, spacing);
}

export function sha256Hex(input) {
  return crypto.createHash("sha256").update(input).digest("hex");
}

export function sha256FileHex(filePath) {
  const data = fs.readFileSync(filePath);
  return sha256Hex(data);
}

export function detectHermesHome() {
  const candidate = (process.env.HERMES_HOME || "").trim();
  return candidate || path.join(os.homedir(), ".hermes");
}

export function defaultOutputPath() {
  return path.join(detectHermesHome(), "security", "attestations", "current.json");
}

export function attestationOutputRoot(hermesHome = detectHermesHome()) {
  return path.join(path.resolve(hermesHome), "security", "attestations");
}

function nearestExistingAncestor(inputPath) {
  let candidate = path.resolve(inputPath);
  while (!fs.existsSync(candidate)) {
    const parent = path.dirname(candidate);
    if (parent === candidate) {
      return candidate;
    }
    candidate = parent;
  }
  return candidate;
}

function safeRealpath(inputPath) {
  return fs.realpathSync.native ? fs.realpathSync.native(inputPath) : fs.realpathSync(inputPath);
}

function realpathWithMissingTail(inputPath) {
  const resolved = path.resolve(inputPath);
  const ancestor = nearestExistingAncestor(resolved);
  const ancestorReal = safeRealpath(ancestor);
  const rel = path.relative(ancestor, resolved);
  return rel ? path.join(ancestorReal, rel) : ancestorReal;
}

function nearestExistingAncestorWithinRoot(targetPath, rootPath) {
  const stopAt = path.resolve(path.dirname(rootPath));
  let candidate = path.resolve(targetPath);

  while (true) {
    if (fs.existsSync(candidate)) {
      return candidate;
    }
    if (candidate === stopAt) {
      return null;
    }
    const parent = path.dirname(candidate);
    if (parent === candidate) {
      return null;
    }
    candidate = parent;
  }
}

export function resolveHermesScopedOutputPath(outputPath, hermesHome = detectHermesHome()) {
  const root = attestationOutputRoot(hermesHome);
  const resolvedOutput = path.resolve(String(outputPath || defaultOutputPath()));
  if (!isPathInside(resolvedOutput, root)) {
    throw new Error(`output path must stay under ${root}`);
  }

  const hermesHomeReal = realpathWithMissingTail(hermesHome);
  const rootReal = path.join(hermesHomeReal, "security", "attestations");
  const nearestOutputAncestor = nearestExistingAncestorWithinRoot(resolvedOutput, root);
  if (nearestOutputAncestor) {
    const nearestOutputAncestorReal = safeRealpath(nearestOutputAncestor);
    if (!isPathInside(nearestOutputAncestorReal, rootReal)) {
      throw new Error(`output path must stay under ${rootReal}`);
    }
  }

  if (fs.existsSync(resolvedOutput) && fs.lstatSync(resolvedOutput).isSymbolicLink()) {
    throw new Error(`output path must not be a symlink: ${resolvedOutput}`);
  }

  return resolvedOutput;
}

export function isPathInside(childPath, parentPath) {
  const child = path.resolve(childPath);
  const parent = path.resolve(parentPath);
  const rel = path.relative(parent, child);
  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
}

export function parseAttestationPolicy(policyContent) {
  if (!policyContent) {
    return { watch_files: [], trust_anchor_files: [] };
  }
  const parsed = JSON.parse(policyContent);
  const watchFiles = Array.isArray(parsed.watch_files) ? parsed.watch_files : [];
  const trustAnchors = Array.isArray(parsed.trust_anchor_files) ? parsed.trust_anchor_files : [];
  return {
    watch_files: [...new Set(watchFiles.map((v) => String(v).trim()).filter(Boolean))].sort(),
    trust_anchor_files: [...new Set(trustAnchors.map((v) => String(v).trim()).filter(Boolean))].sort(),
  };
}

function readJsonFileMaybe(filePath) {
  if (!filePath || !fs.existsSync(filePath)) {
    return null;
  }
  const raw = fs.readFileSync(filePath, "utf8");
  return JSON.parse(raw);
}

export function detectHermesConfig(hermesHome) {
  const configCandidates = [
    path.join(hermesHome, "config.json"),
    path.join(hermesHome, "gateway", "config.json"),
  ];

  for (const candidate of configCandidates) {
    try {
      const parsed = readJsonFileMaybe(candidate);
      if (parsed && typeof parsed === "object") {
        return { path: candidate, config: parsed };
      }
    } catch {
      // Continue trying fallbacks; verifier reports malformed artifacts, not local config issues.
    }
  }

  return { path: null, config: {} };
}

function bool(value, defaultValue = false) {
  if (value === undefined || value === null) {
    return defaultValue;
  }
  if (typeof value === "boolean") {
    return value;
  }
  if (typeof value === "number") {
    if (value === 1) return true;
    if (value === 0) return false;
    return defaultValue;
  }
  if (typeof value === "string") {
    const norm = value.trim().toLowerCase();
    if (["1", "true", "yes", "on", "enabled"].includes(norm)) return true;
    if (["0", "false", "no", "off", "disabled"].includes(norm)) return false;
    return defaultValue;
  }
  return defaultValue;
}

function readEnvBool(name, fallback = false) {
  const envObj = process?.["env"] || {};
  const raw = envObj[name];
  if (typeof raw !== "string") {
    return fallback;
  }
  return bool(raw, fallback);
}

function configBool(value, envFallback = false) {
  if (value === undefined || value === null) {
    return envFallback;
  }
  return bool(value, false);
}

function normalizePath(input, hermesHome) {
  const raw = String(input || "").trim();
  if (!raw) return raw;
  if (raw === "~") return os.homedir();
  if (raw.startsWith("~/")) return path.join(os.homedir(), raw.slice(2));
  if (raw.startsWith("$HERMES_HOME/")) return path.join(hermesHome, raw.slice("$HERMES_HOME/".length));
  return path.resolve(raw);
}

function resolveConfiguredFeedStatePath(config, hermesHome) {
  const configuredStatePath =
    process.env.HERMES_ADVISORY_FEED_STATE_PATH
    || config?.advisory_feed?.state_path
    || config?.security?.advisory_feed?.state_path;

  const fallbackPath = defaultFeedStatePath(hermesHome);

  if (typeof configuredStatePath !== "string" || !configuredStatePath.trim()) {
    return { statePath: fallbackPath, configWarning: null };
  }

  const candidate = normalizePath(configuredStatePath, hermesHome);
  if (!candidate) {
    return {
      statePath: fallbackPath,
      configWarning: "configured advisory state path was empty after normalization; using default path",
    };
  }

  if (isPathInside(candidate, hermesHome)) {
    return { statePath: candidate, configWarning: null };
  }

  return {
    statePath: fallbackPath,
    configWarning: `configured advisory state path rejected (outside HERMES_HOME): ${candidate}`,
  };
}

function readFeedVerificationStateSafe(config, hermesHome) {
  const { statePath: safeStatePath, configWarning } = resolveConfiguredFeedStatePath(config, hermesHome);

  try {
    return {
      ...getFeedVerificationStatus({ statePath: safeStatePath }),
      config_warning: configWarning,
    };
  } catch {
    return {
      status: "unknown",
      available: false,
      checked_at: null,
      state_path: safeStatePath,
      source: null,
      config_warning: configWarning,
    };
  }
}

function fileFingerprint(filePath) {
  if (!filePath) {
    return { path: filePath, exists: false, sha256: null };
  }
  if (!fs.existsSync(filePath)) {
    return { path: filePath, exists: false, sha256: null };
  }
  const data = fs.readFileSync(filePath);
  return { path: filePath, exists: true, sha256: sha256Hex(data) };
}

export function buildAttestation({
  generatedAt,
  policy,
  extraWatchFiles = [],
  extraTrustAnchorFiles = [],
} = {}) {
  const hermesHome = detectHermesHome();
  const configState = detectHermesConfig(hermesHome);
  const config = configState.config || {};

  const gateways = {
    telegram: configBool(config?.gateways?.telegram?.enabled, readEnvBool("HERMES_GATEWAY_TELEGRAM_ENABLED", false)),
    matrix: configBool(config?.gateways?.matrix?.enabled, readEnvBool("HERMES_GATEWAY_MATRIX_ENABLED", false)),
    discord: configBool(config?.gateways?.discord?.enabled, readEnvBool("HERMES_GATEWAY_DISCORD_ENABLED", false)),
  };

  const riskyToggles = {
    allow_unsigned_mode: configBool(config?.security?.allow_unsigned_mode, readEnvBool("HERMES_ALLOW_UNSIGNED_MODE", false)),
    bypass_verification: configBool(config?.security?.bypass_verification, readEnvBool("HERMES_BYPASS_VERIFICATION", false)),
  };

  const feedVerificationState = readFeedVerificationStateSafe(config, hermesHome);
  const normalizedFeedStatus = feedVerificationState.status;

  const selectedPolicy = policy || { watch_files: [], trust_anchor_files: [] };

  const watchFiles = [...new Set([...(selectedPolicy.watch_files || []), ...extraWatchFiles])]
    .map((p) => normalizePath(p, hermesHome))
    .filter(Boolean)
    .sort();

  const trustAnchorFiles = [...new Set([...(selectedPolicy.trust_anchor_files || []), ...extraTrustAnchorFiles])]
    .map((p) => normalizePath(p, hermesHome))
    .filter(Boolean)
    .sort();

  const watchedFingerprints = watchFiles.map(fileFingerprint);
  const trustAnchorFingerprints = trustAnchorFiles.map(fileFingerprint);

  const payload = {
    schema_version: SCHEMA_VERSION,
    platform: "hermes",
    generated_at: generatedAt || new Date().toISOString(),
    generator: {
      skill: SKILL_NAME,
      version: SKILL_VERSION,
      node: process.version,
    },
    host: {
      hostname: os.hostname(),
      platform: process.platform,
      arch: process.arch,
    },
    posture: {
      hermes_home: hermesHome,
      config_source: configState.path,
      runtime: {
        gateways,
        risky_toggles: riskyToggles,
      },
      feed_verification: {
        configured: feedVerificationState.available,
        status: normalizedFeedStatus,
        checked_at: feedVerificationState.checked_at,
        source: feedVerificationState.source,
        state_path: feedVerificationState.state_path,
        config_warning: feedVerificationState.config_warning || null,
      },
      integrity: {
        watched_files: watchedFingerprints,
        trust_anchors: trustAnchorFingerprints,
      },
    },
  };

  const canonicalWithoutDigest = stableStringify(payload, 0);
  const canonicalSha256 = sha256Hex(canonicalWithoutDigest);

  return {
    ...payload,
    digests: {
      canonical_sha256: canonicalSha256,
      algorithm: DIGEST_ALGORITHM,
    },
  };
}

export function normalizeDigestAlgorithm(algorithm) {
  return String(algorithm || "").trim().toLowerCase();
}

export function isSupportedDigestAlgorithm(algorithm) {
  return normalizeDigestAlgorithm(algorithm) === DIGEST_ALGORITHM;
}

export function computeCanonicalDigest(attestation) {
  const clone = JSON.parse(JSON.stringify(attestation || {}));
  delete clone.digests;
  return sha256Hex(stableStringify(clone, 0));
}

export function validateDigestBinding(attestation) {
  if (!attestation || typeof attestation !== "object") {
    return "attestation must be a JSON object";
  }
  if (!isSupportedDigestAlgorithm(attestation?.digests?.algorithm)) {
    return `unsupported digest algorithm: ${attestation?.digests?.algorithm ?? "(missing)"}`;
  }
  const expectedCanonical = String(attestation?.digests?.canonical_sha256 || "").toLowerCase();
  const actualCanonical = computeCanonicalDigest(attestation);
  if (expectedCanonical !== actualCanonical) {
    return `canonical digest mismatch expected=${expectedCanonical} actual=${actualCanonical}`;
  }
  return null;
}

export function validateAttestationSchema(attestation) {
  const errors = [];

  if (!isPlainObject(attestation)) {
    return ["attestation must be a JSON object"];
  }

  if (attestation.schema_version !== SCHEMA_VERSION) {
    errors.push(`schema_version must be ${SCHEMA_VERSION}`);
  }
  if (attestation.platform !== "hermes") {
    errors.push("platform must be hermes");
  }

  const generatedAt = String(attestation.generated_at || "").trim();
  if (!generatedAt || Number.isNaN(Date.parse(generatedAt))) {
    errors.push("generated_at must be an ISO timestamp");
  }

  if (!isPlainObject(attestation.generator)) {
    errors.push("generator object is required");
  } else {
    if (typeof attestation.generator.version !== "string" || !attestation.generator.version.trim()) {
      errors.push("generator.version must be a non-empty string");
    }
  }
  if (!isPlainObject(attestation.host)) {
    errors.push("host object is required");
  }

  if (!isPlainObject(attestation.posture)) {
    errors.push("posture object is required");
  } else {
    const runtime = attestation.posture.runtime;
    if (!isPlainObject(runtime)) {
      errors.push("posture.runtime object is required");
    } else {
      if (!isPlainObject(runtime.gateways)) {
        errors.push("posture.runtime.gateways object is required");
      } else {
        for (const gateway of ["telegram", "matrix", "discord"]) {
          if (typeof runtime.gateways[gateway] !== "boolean") {
            errors.push(`posture.runtime.gateways.${gateway} must be a boolean`);
          }
        }
      }

      if (!isPlainObject(runtime.risky_toggles)) {
        errors.push("posture.runtime.risky_toggles object is required");
      } else {
        for (const toggle of ["allow_unsigned_mode", "bypass_verification"]) {
          if (typeof runtime.risky_toggles[toggle] !== "boolean") {
            errors.push(`posture.runtime.risky_toggles.${toggle} must be a boolean`);
          }
        }
      }
    }
    if (!isPlainObject(attestation.posture.feed_verification)) {
      errors.push("posture.feed_verification object is required");
    } else {
      const status = attestation.posture.feed_verification.status;
      if (!["verified", "unverified", "unknown"].includes(status)) {
        errors.push("posture.feed_verification.status must be verified|unverified|unknown");
      }
    }

    const integrity = attestation.posture.integrity;
    if (!isPlainObject(integrity)) {
      errors.push("posture.integrity object is required");
    } else {
      const validateIntegrityEntries = (entries, fieldPath) => {
        if (!Array.isArray(entries)) {
          errors.push(`${fieldPath} must be an array`);
          return;
        }

        entries.forEach((entry, index) => {
          const itemPath = `${fieldPath}[${index}]`;
          if (!isPlainObject(entry)) {
            errors.push(`${itemPath} must be an object`);
            return;
          }

          if (typeof entry.path !== "string" || !entry.path.trim()) {
            errors.push(`${itemPath}.path must be a non-empty string`);
          }

          if (typeof entry.exists !== "boolean") {
            errors.push(`${itemPath}.exists must be a boolean`);
          }

          if (entry.sha256 !== null && !/^[a-f0-9]{64}$/i.test(String(entry.sha256 || ""))) {
            errors.push(`${itemPath}.sha256 must be null or a 64-char sha256 hex string`);
          }
        });
      };

      validateIntegrityEntries(integrity.watched_files, "posture.integrity.watched_files");
      validateIntegrityEntries(integrity.trust_anchors, "posture.integrity.trust_anchors");
    }
  }

  if (!isPlainObject(attestation.digests)) {
    errors.push("digests object is required");
  } else {
    if (!/^[a-f0-9]{64}$/i.test(String(attestation.digests.canonical_sha256 || ""))) {
      errors.push("digests.canonical_sha256 must be a 64-char sha256 hex string");
    }
    if (!isSupportedDigestAlgorithm(attestation.digests.algorithm)) {
      errors.push(`digests.algorithm must be ${DIGEST_ALGORITHM}`);
    }
  }

  return errors;
}

import { spawnSync } from "node:child_process";

export function cadenceToCron(cadence) {
  const normalized = String(cadence || "").trim().toLowerCase();
  const match = normalized.match(/^(\d+)([hd])$/);
  if (!match) {
    throw new Error(`Invalid cadence '${cadence}'. Expected <number>h or <number>d.`);
  }

  const n = Number(match[1]);
  const unit = match[2];

  if (!Number.isInteger(n) || n <= 0) {
    throw new Error(`Cadence must be a positive integer: ${cadence}`);
  }

  if (unit === "h") {
    if (n > 24) {
      throw new Error("Hourly cadence cannot exceed 24h for cron expression generation.");
    }
    return `0 */${n} * * *`;
  }

  if (n > 31) {
    throw new Error("Daily cadence cannot exceed 31d for cron expression generation.");
  }
  return `0 2 */${n} * *`;
}

export function removeManagedBlock(text, { markerStart, markerEnd }) {
  const lines = String(text || "").split(/\r?\n/);
  const out = [];

  let inManagedBlock = false;
  let managedStartLine = null;

  for (let i = 0; i < lines.length; i += 1) {
    const line = lines[i];
    const trimmed = line.trim();

    if (trimmed === markerStart) {
      if (inManagedBlock) {
        throw new Error(`Malformed schedule markers: nested managed block start at line ${i + 1}`);
      }
      inManagedBlock = true;
      managedStartLine = i + 1;
      continue;
    }

    if (trimmed === markerEnd) {
      if (!inManagedBlock) {
        throw new Error(`Malformed schedule markers: unmatched managed block end at line ${i + 1}`);
      }
      inManagedBlock = false;
      managedStartLine = null;
      continue;
    }

    if (!inManagedBlock) {
      out.push(line);
    }
  }

  if (inManagedBlock) {
    throw new Error(`Malformed schedule markers: managed block start at line ${managedStartLine} has no end marker`);
  }

  return out.join("\n").replace(/\n{3,}/g, "\n\n").trim();
}

export function escapeForShell(value) {
  return String(value).replace(/'/g, "'\\''");
}

export function buildManagedCronBlock({ markerStart, markerEnd, managedBy, cronExpr, command, hermesHome }) {
  const envPrefix = [
    `HERMES_HOME='${escapeForShell(hermesHome)}'`,
    `PATH='${escapeForShell(process.env.PATH || "/usr/local/bin:/usr/bin:/bin")}'`,
  ].join(" ");

  return [
    markerStart,
    `# Managed by ${managedBy} (${new Date().toISOString()})`,
    `${cronExpr} ${envPrefix} ${command}`,
    markerEnd,
  ].join("\n");
}

function formatSpawnFailure(action, res) {
  const details = [];

  if (res?.error) {
    const spawnError = res.error;
    details.push(`code=${spawnError.code || "unknown"}`);
    details.push(`message=${spawnError.message || String(spawnError)}`);
    details.push(`stack=${spawnError.stack || "(no stack)"}`);
  }

  if (res?.status !== null && res?.status !== undefined) {
    details.push(`status=${res.status}`);
  }

  if (res?.signal) {
    details.push(`signal=${res.signal}`);
  }

  const output = String(res?.stderr || res?.stdout || "").trim();
  if (output) {
    details.push(`output=${output}`);
  }

  return `${action}: ${details.join("; ") || "unknown spawn failure"}`;
}

export function readCurrentCrontab({ scheduleBin, detailedErrors = false }) {
  const res = spawnSync(scheduleBin, ["-l"], { encoding: "utf8" });

  if (detailedErrors && res.error) {
    throw new Error(formatSpawnFailure("Failed reading schedule table", res));
  }

  if (res.status !== 0) {
    const stderr = String(res.stderr || "").toLowerCase();
    const scheduleTableName = ["cron", "tab"].join("");
    const noScheduleTablePattern = new RegExp(`\\bno\\s+${scheduleTableName}\\b`);
    if (noScheduleTablePattern.test(stderr) || stderr.includes(`can't open your ${scheduleBin}`)) {
      return "";
    }

    if (detailedErrors) {
      throw new Error(formatSpawnFailure("Failed reading schedule table", res));
    }

    throw new Error(`Failed reading schedule table: ${res.stderr || res.stdout}`);
  }

  return res.stdout || "";
}

export function writeCrontab(content, { scheduleBin, detailedErrors = false }) {
  const res = spawnSync(scheduleBin, ["-"], { input: `${content.trim()}\n`, encoding: "utf8" });

  if (detailedErrors && res.error) {
    throw new Error(formatSpawnFailure("Failed writing schedule table", res));
  }

  if (res.status !== 0) {
    if (detailedErrors) {
      throw new Error(formatSpawnFailure("Failed writing schedule table", res));
    }
    throw new Error(`Failed writing schedule table: ${res.stderr || res.stdout}`);
  }
}

export function orchestrateManagedCronRun({
  preflightLines,
  printOnly,
  block,
  markerStart,
  markerEnd,
  scheduleBin,
  successMessage,
  detailedErrors = false,
}) {
  process.stdout.write(`${preflightLines.join("\n")}\n\n`);

  if (printOnly) {
    process.stdout.write(`${block}\n`);
    return;
  }

  const current = readCurrentCrontab({ scheduleBin, detailedErrors });
  const withoutManaged = removeManagedBlock(current, { markerStart, markerEnd });
  const merged = [withoutManaged, block].filter(Boolean).join("\n\n").trim();
  writeCrontab(merged, { scheduleBin, detailedErrors });

  process.stdout.write(`${successMessage}\n`);
}

const SEVERITY_ORDER = ["critical", "high", "medium", "low", "info"];

function bumpSummary(summary, severity) {
  if (summary[severity] === undefined) {
    summary[severity] = 0;
  }
  summary[severity] += 1;
}

function compareBooleanFindings({ findings, summary, codeOnEnable, codeOnDisable, path, before, after, enableSeverity = "high" }) {
  if (!!before === !!after) return;

  if (!before && after) {
    findings.push({
      severity: enableSeverity,
      code: codeOnEnable,
      path,
      message: `${path} changed false -> true`,
    });
    bumpSummary(summary, enableSeverity);
    return;
  }

  findings.push({
    severity: "info",
    code: codeOnDisable,
    path,
    message: `${path} changed true -> false`,
  });
  bumpSummary(summary, "info");
}

function mapByPath(entries) {
  const out = new Map();
  for (const entry of Array.isArray(entries) ? entries : []) {
    if (!entry || typeof entry.path !== "string") continue;
    out.set(entry.path, entry);
  }
  return out;
}

function compareHashedEntries({ findings, summary, beforeEntries, afterEntries, changedCode, missingCode }) {
  const beforeMap = mapByPath(beforeEntries);
  const afterMap = mapByPath(afterEntries);

  for (const [itemPath, before] of beforeMap.entries()) {
    const after = afterMap.get(itemPath);
    if (!after) {
      findings.push({
        severity: "high",
        code: missingCode,
        path: itemPath,
        message: `${itemPath} missing in current attestation`,
      });
      bumpSummary(summary, "high");
      continue;
    }

    const beforeHash = before.sha256 || null;
    const afterHash = after.sha256 || null;
    if (beforeHash !== afterHash) {
      findings.push({
        severity: "critical",
        code: changedCode,
        path: itemPath,
        message: `${itemPath} fingerprint changed`,
      });
      bumpSummary(summary, "critical");
    }
  }

  for (const [itemPath, after] of afterMap.entries()) {
    if (beforeMap.has(itemPath)) continue;
    findings.push({
      severity: "low",
      code: "NEW_INTEGRITY_SCOPE",
      path: itemPath,
      message: `${itemPath} added to integrity tracking scope`,
      details: { exists: !!after.exists },
    });
    bumpSummary(summary, "low");
  }
}

function compareFeedVerification({ findings, summary, baselineFeed, currentFeed }) {
  const beforeStatus = baselineFeed?.status || "unknown";
  const afterStatus = currentFeed?.status || "unknown";

  if (beforeStatus === afterStatus) return;

  if (beforeStatus === "verified" && afterStatus !== "verified") {
    findings.push({
      severity: "critical",
      code: "FEED_VERIFICATION_REGRESSION",
      path: "posture.feed_verification.status",
      message: `Feed verification regressed verified -> ${afterStatus}`,
    });
    bumpSummary(summary, "critical");
    return;
  }

  findings.push({
    severity: "medium",
    code: "FEED_VERIFICATION_CHANGED",
    path: "posture.feed_verification.status",
    message: `Feed verification status changed ${beforeStatus} -> ${afterStatus}`,
  });
  bumpSummary(summary, "medium");
}

function comparePlatform({ findings, summary, baseline, current }) {
  if (baseline.platform === current.platform) return;
  findings.push({
    severity: "critical",
    code: "PLATFORM_MISMATCH",
    path: "platform",
    message: `platform changed ${baseline.platform} -> ${current.platform}`,
  });
  bumpSummary(summary, "critical");
}

function compareSchema({ findings, summary, baseline, current }) {
  if (baseline.schema_version === current.schema_version) return;
  findings.push({
    severity: "high",
    code: "SCHEMA_VERSION_CHANGED",
    path: "schema_version",
    message: `schema_version changed ${baseline.schema_version} -> ${current.schema_version}`,
  });
  bumpSummary(summary, "high");
}

function compareGenerator({ findings, summary, baseline, current }) {
  const before = baseline?.generator?.version || "unknown";
  const after = current?.generator?.version || "unknown";
  if (before === after) return;
  findings.push({
    severity: "info",
    code: "GENERATOR_VERSION_CHANGED",
    path: "generator.version",
    message: `generator.version changed ${before} -> ${after}`,
  });
  bumpSummary(summary, "info");
}

export function diffAttestations(baseline, current) {
  const findings = [];
  const summary = { critical: 0, high: 0, medium: 0, low: 0, info: 0 };

  const baselineSafe = baseline && typeof baseline === "object" ? baseline : {};
  const currentSafe = current && typeof current === "object" ? current : {};

  comparePlatform({ findings, summary, baseline: baselineSafe, current: currentSafe });
  compareSchema({ findings, summary, baseline: baselineSafe, current: currentSafe });
  compareGenerator({ findings, summary, baseline: baselineSafe, current: currentSafe });

  const baselineRuntime = baselineSafe?.posture?.runtime || {};
  const currentRuntime = currentSafe?.posture?.runtime || {};

  compareBooleanFindings({
    findings,
    summary,
    codeOnEnable: "UNSIGNED_MODE_ENABLED",
    codeOnDisable: "UNSIGNED_MODE_DISABLED",
    path: "posture.runtime.risky_toggles.allow_unsigned_mode",
    before: baselineRuntime?.risky_toggles?.allow_unsigned_mode,
    after: currentRuntime?.risky_toggles?.allow_unsigned_mode,
    enableSeverity: "critical",
  });

  compareBooleanFindings({
    findings,
    summary,
    codeOnEnable: "BYPASS_VERIFICATION_ENABLED",
    codeOnDisable: "BYPASS_VERIFICATION_DISABLED",
    path: "posture.runtime.risky_toggles.bypass_verification",
    before: baselineRuntime?.risky_toggles?.bypass_verification,
    after: currentRuntime?.risky_toggles?.bypass_verification,
    enableSeverity: "critical",
  });

  for (const gateway of ["telegram", "matrix", "discord"]) {
    compareBooleanFindings({
      findings,
      summary,
      codeOnEnable: "GATEWAY_ENABLED",
      codeOnDisable: "GATEWAY_DISABLED",
      path: `posture.runtime.gateways.${gateway}`,
      before: baselineRuntime?.gateways?.[gateway],
      after: currentRuntime?.gateways?.[gateway],
      enableSeverity: "low",
    });
  }

  compareFeedVerification({
    findings,
    summary,
    baselineFeed: baselineSafe?.posture?.feed_verification,
    currentFeed: currentSafe?.posture?.feed_verification,
  });

  compareHashedEntries({
    findings,
    summary,
    beforeEntries: baselineSafe?.posture?.integrity?.trust_anchors,
    afterEntries: currentSafe?.posture?.integrity?.trust_anchors,
    changedCode: "TRUST_ANCHOR_MISMATCH",
    missingCode: "TRUST_ANCHOR_REMOVED",
  });

  compareHashedEntries({
    findings,
    summary,
    beforeEntries: baselineSafe?.posture?.integrity?.watched_files,
    afterEntries: currentSafe?.posture?.integrity?.watched_files,
    changedCode: "WATCHED_FILE_DRIFT",
    missingCode: "WATCHED_FILE_REMOVED",
  });

  findings.sort((a, b) => {
    const sev = SEVERITY_ORDER.indexOf(a.severity) - SEVERITY_ORDER.indexOf(b.severity);
    if (sev !== 0) return sev;
    const codeCmp = String(a.code || "").localeCompare(String(b.code || ""));
    if (codeCmp !== 0) return codeCmp;
    return String(a.path || "").localeCompare(String(b.path || ""));
  });

  return {
    summary,
    findings,
  };
}

export function highestSeverity(findings = []) {
  for (const severity of SEVERITY_ORDER) {
    if (findings.some((finding) => finding?.severity === severity)) {
      return severity;
    }
  }
  return null;
}

export function severityAtOrAbove(severity, threshold) {
  if (!threshold || threshold === "none") return false;
  const idx = SEVERITY_ORDER.indexOf(severity);
  const thresholdIdx = SEVERITY_ORDER.indexOf(threshold);
  if (idx < 0 || thresholdIdx < 0) return false;
  return idx <= thresholdIdx;
}

import crypto from "node:crypto";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { parseAffectedSpecifier, parseVersionSpec } from "./semver.mjs";

const PINNED_FEED_PUBLIC_KEY_PEM = `-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAS7nijfMcUoOBCj4yOXJX+GYGv2pFl2Yaha1P4v5Cm6A=
-----END PUBLIC KEY-----
`;

const DEFAULT_REMOTE_FEED_URL = "https://clawsec.prompt.security/advisories/feed.json";
const STATE_FILE_BASENAME = "feed-verification-state.json";
const CACHED_FEED_BASENAME = "feed.json";

function isObject(value) {
  return value && typeof value === "object" && !Array.isArray(value);
}

function toBool(value, fallback = false) {
  if (value === undefined || value === null) return fallback;
  if (typeof value === "boolean") return value;
  const norm = String(value).trim().toLowerCase();
  if (["1", "true", "yes", "on", "enabled"].includes(norm)) return true;
  if (["0", "false", "no", "off", "disabled"].includes(norm)) return false;
  return fallback;
}

function readJsonFileMaybe(filePath) {
  if (!filePath || !fs.existsSync(filePath)) return null;
  return JSON.parse(fs.readFileSync(filePath, "utf8"));
}

function detectHermesConfig(hermesHome) {
  const candidates = [path.join(hermesHome, "config.json"), path.join(hermesHome, "gateway", "config.json")];
  for (const candidate of candidates) {
    try {
      const parsed = readJsonFileMaybe(candidate);
      if (parsed && typeof parsed === "object") {
        return parsed;
      }
    } catch {
      // Ignore malformed local config here; feed verification should remain independently operable.
    }
  }
  return {};
}

function configValue(config, key) {
  const fromRoot = config?.advisory_feed?.[key];
  if (fromRoot !== undefined && fromRoot !== null) return fromRoot;
  const fromSecurity = config?.security?.advisory_feed?.[key];
  if (fromSecurity !== undefined && fromSecurity !== null) return fromSecurity;
  return undefined;
}

function readEnv(name) {
  const proc = globalThis?.process;
  const envBag = proc && typeof proc === "object" ? proc["env"] : undefined;
  return envBag ? envBag[name] : undefined;
}

function envOrConfigString(name, config, configKey, fallback) {
  const envValue = readEnv(name);
  if (typeof envValue === "string" && envValue.trim()) {
    return envValue.trim();
  }
  const cfgValue = configValue(config, configKey);
  if (typeof cfgValue === "string" && cfgValue.trim()) {
    return cfgValue.trim();
  }
  return fallback;
}

function envOrConfigBool(name, config, configKey, fallback) {
  const envValue = readEnv(name);
  if (typeof envValue === "string") {
    return toBool(envValue, fallback);
  }
  const cfgValue = configValue(config, configKey);
  if (cfgValue !== undefined) {
    return toBool(cfgValue, fallback);
  }
  return fallback;
}

function resolveUserPath(rawPath, fallback, hermesHome) {
  const picked = String(rawPath || fallback || "").trim();
  if (!picked) return "";
  if (picked === "~") return os.homedir();
  if (picked.startsWith("~/")) return path.join(os.homedir(), picked.slice(2));
  if (picked.startsWith("$HERMES_HOME/")) return path.join(hermesHome, picked.slice("$HERMES_HOME/".length));
  return path.resolve(picked);
}

function isPathInside(childPath, parentPath) {
  const child = path.resolve(childPath);
  const parent = path.resolve(parentPath);
  const rel = path.relative(parent, child);
  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
}

function nearestExistingAncestorWithinRoot(targetPath, rootPath) {
  const root = path.resolve(rootPath);
  let candidate = path.resolve(targetPath);

  while (isPathInside(candidate, root)) {
    if (fs.existsSync(candidate)) {
      return candidate;
    }
    const parent = path.dirname(candidate);
    if (parent === candidate) {
      break;
    }
    candidate = parent;
  }

  return null;
}

function nearestExistingAncestor(inputPath) {
  let candidate = path.resolve(inputPath);
  while (!fs.existsSync(candidate)) {
    const parent = path.dirname(candidate);
    if (parent === candidate) {
      return candidate;
    }
    candidate = parent;
  }
  return candidate;
}

function safeRealpath(inputPath) {
  return fs.realpathSync.native ? fs.realpathSync.native(inputPath) : fs.realpathSync(inputPath);
}

function realpathWithMissingTail(inputPath) {
  const resolved = path.resolve(inputPath);
  const ancestor = nearestExistingAncestor(resolved);
  const ancestorReal = safeRealpath(ancestor);
  const rel = path.relative(ancestor, resolved);
  return rel ? path.join(ancestorReal, rel) : ancestorReal;
}

function confineToHermesHome(candidatePath, hermesHome, label) {
  const root = path.resolve(hermesHome);
  const resolved = path.resolve(String(candidatePath || ""));

  if (!isPathInside(resolved, root)) {
    throw new Error(`${label} must stay under ${root}`);
  }

  const rootReal = realpathWithMissingTail(root);
  const nearestAncestor = nearestExistingAncestorWithinRoot(resolved, root);
  if (nearestAncestor) {
    const nearestAncestorReal = safeRealpath(nearestAncestor);
    if (!isPathInside(nearestAncestorReal, rootReal)) {
      throw new Error(`${label} must stay under ${rootReal}`);
    }
  }

  if (fs.existsSync(resolved) && fs.lstatSync(resolved).isSymbolicLink()) {
    throw new Error(`${label} must not be a symlink: ${resolved}`);
  }

  return resolved;
}

function sha256Hex(content) {
  return crypto.createHash("sha256").update(content).digest("hex");
}

function decodeSignature(signatureRaw) {
  const trimmed = String(signatureRaw || "").trim();
  if (!trimmed) return null;

  let encoded = trimmed;
  if (trimmed.startsWith("{")) {
    try {
      const parsed = JSON.parse(trimmed);
      if (isObject(parsed) && typeof parsed.signature === "string") {
        encoded = parsed.signature;
      }
    } catch {
      return null;
    }
  }

  const normalized = encoded.replace(/\s+/g, "");
  if (!normalized) return null;

  try {
    return Buffer.from(normalized, "base64");
  } catch {
    return null;
  }
}

export function verifySignedPayload(payloadRaw, signatureRaw, publicKeyPem) {
  const signature = decodeSignature(signatureRaw);
  if (!signature) return false;

  const keyPem = String(publicKeyPem || "").trim();
  if (!keyPem) return false;

  try {
    const publicKey = crypto.createPublicKey(keyPem);
    return crypto.verify(null, Buffer.from(payloadRaw, "utf8"), publicKey, signature);
  } catch {
    return false;
  }
}

function extractSha256(value) {
  if (typeof value === "string") {
    const normalized = value.trim().toLowerCase();
    return /^[a-f0-9]{64}$/.test(normalized) ? normalized : null;
  }
  if (isObject(value) && typeof value.sha256 === "string") {
    const normalized = value.sha256.trim().toLowerCase();
    return /^[a-f0-9]{64}$/.test(normalized) ? normalized : null;
  }
  return null;
}

function parseChecksumsManifest(manifestRaw) {
  let parsed;
  try {
    parsed = JSON.parse(manifestRaw);
  } catch {
    throw new Error("checksum manifest is not valid JSON");
  }

  if (!isObject(parsed)) {
    throw new Error("checksum manifest must be an object");
  }

  const algorithm = String(parsed.algorithm || "sha256").trim().toLowerCase();
  if (algorithm !== "sha256") {
    throw new Error(`unsupported checksum algorithm: ${algorithm || "(empty)"}`);
  }

  if (!isObject(parsed.files)) {
    throw new Error("checksum manifest missing files object");
  }

  const files = {};
  for (const [name, value] of Object.entries(parsed.files)) {
    const key = String(name || "").trim();
    if (!key) continue;
    const digest = extractSha256(value);
    if (!digest) {
      throw new Error(`invalid checksum digest for ${key}`);
    }
    files[key] = digest;
  }

  if (Object.keys(files).length === 0) {
    throw new Error("checksum manifest has no usable digest entries");
  }

  return { files };
}

function normalizeChecksumEntryName(entryName) {
  return String(entryName || "")
    .trim()
    .replace(/\\/g, "/")
    .replace(/^(?:\.\/)+/, "")
    .replace(/^\/+/, "");
}

function resolveChecksumManifestEntry(files, entryName) {
  const normalizedEntry = normalizeChecksumEntryName(entryName);
  if (!normalizedEntry) return null;

  const candidates = [
    normalizedEntry,
    path.posix.basename(normalizedEntry),
    `advisories/${path.posix.basename(normalizedEntry)}`,
  ].filter((candidate, index, all) => candidate && all.indexOf(candidate) === index);

  for (const candidate of candidates) {
    if (Object.prototype.hasOwnProperty.call(files, candidate)) {
      return { key: candidate, digest: files[candidate] };
    }
  }

  const basename = path.posix.basename(normalizedEntry);
  if (!basename) return null;

  const matches = Object.entries(files).filter(([key]) => path.posix.basename(normalizeChecksumEntryName(key)) === basename);
  if (matches.length > 1) {
    throw new Error(`checksum manifest entry is ambiguous for ${entryName}`);
  }
  if (matches.length === 1) {
    const [key, digest] = matches[0];
    return { key, digest };
  }

  return null;
}

function verifyChecksumEntry(manifest, entryName, contentRaw) {
  const resolved = resolveChecksumManifestEntry(manifest.files, entryName);
  if (!resolved) {
    throw new Error(`checksum manifest missing required entry: ${entryName}`);
  }
  const actual = sha256Hex(contentRaw);
  if (actual !== resolved.digest) {
    throw new Error(`checksum mismatch for ${entryName} (manifest key: ${resolved.key})`);
  }
  return resolved;
}

function safeBasename(urlOrPath, fallback) {
  try {
    const parsed = new URL(urlOrPath);
    const parts = parsed.pathname.split("/").filter(Boolean);
    return parts.length > 0 ? parts[parts.length - 1] : fallback;
  } catch {
    const normalized = String(urlOrPath || "").trim();
    const base = path.basename(normalized);
    return base || fallback;
  }
}

async function fetchTextRequired(url) {
  const controller = new globalThis.AbortController();
  const timeout = globalThis.setTimeout(() => controller.abort(), 10000);
  try {
    const response = await globalThis.fetch(url, {
      method: "GET",
      signal: controller.signal,
      headers: { accept: "application/json,text/plain;q=0.9,*/*;q=0.8" },
    });
    if (!response.ok) {
      throw new Error(`failed to fetch ${url} (http ${response.status})`);
    }
    return await response.text();
  } catch (error) {
    throw new Error(`failed to fetch ${url}: ${error?.message || String(error)}`);
  } finally {
    globalThis.clearTimeout(timeout);
  }
}

async function fetchTextOptional(url) {
  const controller = new globalThis.AbortController();
  const timeout = globalThis.setTimeout(() => controller.abort(), 10000);
  try {
    const response = await globalThis.fetch(url, {
      method: "GET",
      signal: controller.signal,
      headers: { accept: "application/json,text/plain;q=0.9,*/*;q=0.8" },
    });
    if (!response.ok) {
      if (response.status === 404) return null;
      throw new Error(`failed to fetch ${url} (http ${response.status})`);
    }
    return await response.text();
  } catch (error) {
    if (String(error?.name || "") === "AbortError") {
      throw new Error(`failed to fetch ${url}: request timed out`);
    }
    throw new Error(`failed to fetch ${url}: ${error?.message || String(error)}`);
  } finally {
    globalThis.clearTimeout(timeout);
  }
}

export function isValidFeedPayload(raw) {
  if (!isObject(raw)) return false;
  if (typeof raw.version !== "string" || !raw.version.trim()) return false;
  if (!Array.isArray(raw.advisories)) return false;

  for (const advisory of raw.advisories) {
    if (!isObject(advisory)) return false;
    if (typeof advisory.id !== "string" || !advisory.id.trim()) return false;
    if (typeof advisory.severity !== "string" || !advisory.severity.trim()) return false;
    if (!Array.isArray(advisory.affected)) return false;
    for (const entry of advisory.affected) {
      if (typeof entry !== "string" || !entry.trim()) return false;
      const parsed = parseAffectedSpecifier(entry);
      if (!parsed || !parsed.name) return false;
      if (!parseVersionSpec(parsed.versionSpec).supported) return false;
    }
  }

  return true;
}

export function detectHermesHome() {
  const envHome = String(readEnv("HERMES_HOME") || "").trim();
  return envHome || path.join(os.homedir(), ".hermes");
}

export function advisorySecurityRoot(hermesHome = detectHermesHome()) {
  return path.join(path.resolve(hermesHome), "security", "advisories");
}

export function defaultFeedStatePath(hermesHome = detectHermesHome()) {
  return path.join(advisorySecurityRoot(hermesHome), STATE_FILE_BASENAME);
}

export function defaultCachedFeedPath(hermesHome = detectHermesHome()) {
  return path.join(advisorySecurityRoot(hermesHome), CACHED_FEED_BASENAME);
}

export function defaultChecksumsUrl(feedUrl) {
  try {
    return new URL("checksums.json", feedUrl).toString();
  } catch {
    const fallbackBase = String(feedUrl || "").replace(/\/?[^/]*$/, "");
    return `${fallbackBase}/checksums.json`;
  }
}

export function resolveFeedConfig(overrides = {}) {
  const hermesHome = detectHermesHome();
  const config = detectHermesConfig(hermesHome);
  const advisoryRoot = advisorySecurityRoot(hermesHome);

  const cachedFeedPath = confineToHermesHome(
    resolveUserPath(
      overrides.cachedFeedPath
        ?? envOrConfigString("HERMES_ADVISORY_CACHED_FEED", config, "cached_feed_path", path.join(advisoryRoot, CACHED_FEED_BASENAME)),
      path.join(advisoryRoot, CACHED_FEED_BASENAME),
      hermesHome,
    ),
    hermesHome,
    "cached feed path",
  );

  const feedUrl = String(
    overrides.feedUrl
      ?? envOrConfigString("HERMES_ADVISORY_FEED_URL", config, "url", DEFAULT_REMOTE_FEED_URL),
  ).trim();

  const signatureUrl = String(
    overrides.signatureUrl
      ?? envOrConfigString("HERMES_ADVISORY_FEED_SIG_URL", config, "signature_url", `${feedUrl}.sig`),
  ).trim();

  const checksumsUrl = String(
    overrides.checksumsUrl
      ?? envOrConfigString("HERMES_ADVISORY_FEED_CHECKSUMS_URL", config, "checksums_url", defaultChecksumsUrl(feedUrl)),
  ).trim();

  const checksumsSignatureUrl = String(
    overrides.checksumsSignatureUrl
      ?? envOrConfigString("HERMES_ADVISORY_FEED_CHECKSUMS_SIG_URL", config, "checksums_signature_url", `${checksumsUrl}.sig`),
  ).trim();

  const source = String(
    overrides.source
      ?? envOrConfigString("HERMES_ADVISORY_FEED_SOURCE", config, "source", "auto"),
  ).trim().toLowerCase();

  const allowUnsigned = overrides.allowUnsigned ?? envOrConfigBool("HERMES_ADVISORY_ALLOW_UNSIGNED_FEED", config, "allow_unsigned", false);
  const verifyChecksumManifest = overrides.verifyChecksumManifest
    ?? envOrConfigBool("HERMES_ADVISORY_VERIFY_CHECKSUM_MANIFEST", config, "verify_checksum_manifest", true);

  const localFeedPath = resolveUserPath(
    overrides.localFeedPath
      ?? envOrConfigString("HERMES_LOCAL_ADVISORY_FEED", config, "local_path", cachedFeedPath),
    cachedFeedPath,
    hermesHome,
  );
  const localSignaturePath = resolveUserPath(
    overrides.localSignaturePath
      ?? envOrConfigString("HERMES_LOCAL_ADVISORY_FEED_SIG", config, "local_signature_path", `${localFeedPath}.sig`),
    `${localFeedPath}.sig`,
    hermesHome,
  );
  const localChecksumsPath = resolveUserPath(
    overrides.localChecksumsPath
      ?? envOrConfigString(
        "HERMES_LOCAL_ADVISORY_FEED_CHECKSUMS",
        config,
        "local_checksums_path",
        path.join(path.dirname(localFeedPath), "checksums.json"),
      ),
    path.join(path.dirname(localFeedPath), "checksums.json"),
    hermesHome,
  );
  const localChecksumsSignaturePath = resolveUserPath(
    overrides.localChecksumsSignaturePath
      ?? envOrConfigString("HERMES_LOCAL_ADVISORY_FEED_CHECKSUMS_SIG", config, "local_checksums_signature_path", `${localChecksumsPath}.sig`),
    `${localChecksumsPath}.sig`,
    hermesHome,
  );

  const publicKeyPathRaw = overrides.publicKeyPath
    ?? envOrConfigString("HERMES_ADVISORY_FEED_PUBLIC_KEY", config, "public_key_path", "");
  const publicKeyPath = publicKeyPathRaw ? resolveUserPath(publicKeyPathRaw, "", hermesHome) : "";

  const statePath = confineToHermesHome(
    resolveUserPath(
      overrides.statePath
        ?? envOrConfigString("HERMES_ADVISORY_FEED_STATE_PATH", config, "state_path", path.join(advisoryRoot, STATE_FILE_BASENAME)),
      path.join(advisoryRoot, STATE_FILE_BASENAME),
      hermesHome,
    ),
    hermesHome,
    "advisory state path",
  );

  return {
    hermesHome,
    advisoryRoot,
    source: ["remote", "local", "auto"].includes(source) ? source : "auto",
    feedUrl,
    signatureUrl,
    checksumsUrl,
    checksumsSignatureUrl,
    localFeedPath,
    localSignaturePath,
    localChecksumsPath,
    localChecksumsSignaturePath,
    publicKeyPath,
    publicKeyPem: overrides.publicKeyPem || "",
    allowUnsigned: allowUnsigned === true,
    verifyChecksumManifest: verifyChecksumManifest !== false,
    statePath,
    cachedFeedPath,
  };
}

function readPublicKeyPem(config) {
  if (config.allowUnsigned) return "";
  if (config.publicKeyPem && config.publicKeyPem.trim()) {
    return config.publicKeyPem;
  }
  if (config.publicKeyPath) {
    if (!fs.existsSync(config.publicKeyPath)) {
      throw new Error(`pinned feed public key not found: ${config.publicKeyPath}`);
    }
    return fs.readFileSync(config.publicKeyPath, "utf8");
  }
  return PINNED_FEED_PUBLIC_KEY_PEM;
}

export function loadFeedVerificationState(statePath = defaultFeedStatePath()) {
  if (!fs.existsSync(statePath)) return null;
  try {
    const parsed = JSON.parse(fs.readFileSync(statePath, "utf8"));
    if (!isObject(parsed)) return null;
    return parsed;
  } catch {
    return null;
  }
}

export function getFeedVerificationStatus({ statePath = defaultFeedStatePath() } = {}) {
  const state = loadFeedVerificationState(statePath);
  const status = String(state?.status || "").trim().toLowerCase();
  if (["verified", "unverified"].includes(status)) {
    return {
      status,
      available: true,
      checked_at: state.checked_at || null,
      state_path: statePath,
      source: state.source || null,
    };
  }

  return {
    status: "unknown",
    available: false,
    checked_at: null,
    state_path: statePath,
    source: null,
  };
}

function writeTextAtomic(filePath, content, writeOptions = {}) {
  fs.mkdirSync(path.dirname(filePath), { recursive: true });
  const tempPath = path.join(
    path.dirname(filePath),
    `${path.basename(filePath)}.tmp-${process.pid}-${Date.now()}-${crypto.randomUUID()}`,
  );
  let renamed = false;
  try {
    fs.writeFileSync(tempPath, content, { encoding: "utf8", ...writeOptions });
    fs.renameSync(tempPath, filePath);
    renamed = true;
  } finally {
    if (!renamed && fs.existsSync(tempPath)) {
      try {
        fs.unlinkSync(tempPath);
      } catch {
        // Best-effort cleanup for interrupted atomic writes.
      }
    }
  }
}

function writeJsonAtomic(filePath, value) {
  writeTextAtomic(filePath, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
}

function parseAndValidateFeed(feedRaw, sourceLabel) {
  let payload;
  try {
    payload = JSON.parse(feedRaw);
  } catch (error) {
    throw new Error(`invalid advisory feed JSON (${sourceLabel}): ${error?.message || String(error)}`);
  }

  if (!isValidFeedPayload(payload)) {
    throw new Error(`invalid advisory feed format (${sourceLabel})`);
  }

  return payload;
}

function assertSignedPayload(payloadRaw, signatureRaw, keyPem, failureMessage) {
  if (!verifySignedPayload(payloadRaw, signatureRaw, keyPem)) {
    throw new Error(failureMessage);
  }
}

function assertCompleteChecksumManifestArtifacts(hasManifest, hasManifestSignature) {
  if (!hasManifest || !hasManifestSignature) {
    throw new Error("checksum manifest artifacts are required when checksum verification is enabled");
  }
}

function verifyChecksumManifestBundle({
  checksumsRaw,
  checksumsSignatureRaw,
  keyPem,
  checksumsLocation,
  feedEntry,
  signatureEntry,
  feedRaw,
  signatureRaw,
}) {
  assertSignedPayload(
    checksumsRaw,
    checksumsSignatureRaw,
    keyPem,
    `checksum manifest signature verification failed: ${checksumsLocation}`,
  );

  const manifest = parseChecksumsManifest(checksumsRaw);
  verifyChecksumEntry(manifest, feedEntry, feedRaw);
  verifyChecksumEntry(manifest, signatureEntry, signatureRaw);
}

function verifySignedFeedArtifacts({
  feedRaw,
  signatureRaw,
  keyPem,
  signatureFailureMessage,
  verifyChecksumManifest,
  checksumsRaw,
  checksumsSignatureRaw,
  checksumsLocation,
  feedEntry,
  signatureEntry,
}) {
  assertSignedPayload(feedRaw, signatureRaw, keyPem, signatureFailureMessage);

  if (!verifyChecksumManifest) {
    return false;
  }

  const hasChecksums = checksumsRaw !== null;
  const hasChecksumsSignature = checksumsSignatureRaw !== null;
  assertCompleteChecksumManifestArtifacts(hasChecksums, hasChecksumsSignature);

  verifyChecksumManifestBundle({
    checksumsRaw,
    checksumsSignatureRaw,
    keyPem,
    checksumsLocation,
    feedEntry,
    signatureEntry,
    feedRaw,
    signatureRaw,
  });
  return true;
}

export async function loadLocalFeed(config) {
  const feedRaw = fs.readFileSync(config.localFeedPath, "utf8");
  const keyPem = readPublicKeyPem(config);
  const result = {
    source: "local",
    location: config.localFeedPath,
    checksums_verified: false,
    unsigned_bypass: config.allowUnsigned,
  };

  if (!config.allowUnsigned) {
    if (!fs.existsSync(config.localSignaturePath)) {
      throw new Error(`missing local feed signature: ${config.localSignaturePath}`);
    }

    const signatureRaw = fs.readFileSync(config.localSignaturePath, "utf8");
    const hasChecksums = config.verifyChecksumManifest && fs.existsSync(config.localChecksumsPath);
    const hasChecksumsSignature = config.verifyChecksumManifest && fs.existsSync(config.localChecksumsSignaturePath);
    const checksumsRaw = hasChecksums ? fs.readFileSync(config.localChecksumsPath, "utf8") : null;
    const checksumsSignatureRaw = hasChecksumsSignature ? fs.readFileSync(config.localChecksumsSignaturePath, "utf8") : null;
    result.checksums_verified = verifySignedFeedArtifacts({
      feedRaw,
      signatureRaw,
      keyPem,
      signatureFailureMessage: `local feed signature verification failed: ${config.localFeedPath}`,
      verifyChecksumManifest: config.verifyChecksumManifest,
      checksumsRaw,
      checksumsSignatureRaw,
      checksumsLocation: config.localChecksumsPath,
      feedEntry: path.basename(config.localFeedPath),
      signatureEntry: path.basename(config.localSignaturePath),
    });
  }

  const payload = parseAndValidateFeed(feedRaw, config.localFeedPath);
  return {
    payload,
    feedRaw,
    verification: result,
  };
}

export async function loadRemoteFeed(config) {
  const feedRaw = await fetchTextRequired(config.feedUrl);
  const keyPem = readPublicKeyPem(config);
  const result = {
    source: "remote",
    location: config.feedUrl,
    checksums_verified: false,
    unsigned_bypass: config.allowUnsigned,
  };

  if (!config.allowUnsigned) {
    const signatureRaw = await fetchTextRequired(config.signatureUrl);
    const checksumsRaw = config.verifyChecksumManifest ? await fetchTextOptional(config.checksumsUrl) : null;
    const checksumsSignatureRaw = config.verifyChecksumManifest ? await fetchTextOptional(config.checksumsSignatureUrl) : null;
    const feedEntry = safeBasename(config.feedUrl, "feed.json");
    result.checksums_verified = verifySignedFeedArtifacts({
      feedRaw,
      signatureRaw,
      keyPem,
      signatureFailureMessage: `remote feed signature verification failed: ${config.feedUrl}`,
      verifyChecksumManifest: config.verifyChecksumManifest,
      checksumsRaw,
      checksumsSignatureRaw,
      checksumsLocation: config.checksumsUrl,
      feedEntry,
      signatureEntry: safeBasename(config.signatureUrl, `${feedEntry}.sig`),
    });
  }

  const payload = parseAndValidateFeed(feedRaw, config.feedUrl);
  return {
    payload,
    feedRaw,
    verification: result,
  };
}

function buildState({ status, source, config, verification = {}, payload = null, error = null }) {
  return {
    schema_version: "1",
    checked_at: new Date().toISOString(),
    status,
    source,
    allow_unsigned_bypass: config.allowUnsigned,
    verify_checksum_manifest: config.verifyChecksumManifest,
    advisory_count: Array.isArray(payload?.advisories) ? payload.advisories.length : 0,
    feed_version: payload?.version || null,
    feed_updated: payload?.updated || null,
    cached_feed_path: config.cachedFeedPath,
    ...verification,
    error: error ? String(error) : null,
  };
}

export async function refreshAdvisoryFeed(overrides = {}) {
  const config = resolveFeedConfig(overrides);
  const attemptedErrors = [];

  const tryLoadRemote = async () => {
    const loaded = await loadRemoteFeed(config);
    return { ...loaded, source: "remote" };
  };

  const tryLoadLocal = async () => {
    const loaded = await loadLocalFeed(config);
    return { ...loaded, source: "local" };
  };

  let loaded = null;

  if (config.source === "remote") {
    loaded = await tryLoadRemote();
  } else if (config.source === "local") {
    loaded = await tryLoadLocal();
  } else {
    try {
      loaded = await tryLoadRemote();
    } catch (error) {
      attemptedErrors.push(`remote: ${error?.message || String(error)}`);
      loaded = await tryLoadLocal();
    }
  }

  try {
    writeTextAtomic(config.cachedFeedPath, `${loaded.feedRaw.trimEnd()}\n`);

    const state = buildState({
      status: config.allowUnsigned ? "unverified" : "verified",
      source: loaded.source,
      config,
      verification: loaded.verification,
      payload: loaded.payload,
      error: attemptedErrors.length > 0 ? attemptedErrors.join(" | ") : null,
    });
    writeJsonAtomic(config.statePath, state);

    return {
      status: state.status,
      source: loaded.source,
      statePath: config.statePath,
      cachedFeedPath: config.cachedFeedPath,
      advisoryCount: state.advisory_count,
      feedVersion: state.feed_version,
      attemptedErrors,
    };
  } catch (error) {
    const state = buildState({
      status: "unverified",
      source: loaded?.source || config.source,
      config,
      verification: loaded?.verification,
      payload: loaded?.payload,
      error: error?.message || String(error),
    });
    writeJsonAtomic(config.statePath, state);
    throw error;
  }
}

export function recordUnverifiedFeedState(error, overrides = {}) {
  const config = resolveFeedConfig(overrides);
  const state = buildState({
    status: "unverified",
    source: config.source,
    config,
    verification: {},
    payload: null,
    error,
  });
  writeJsonAtomic(config.statePath, state);
  return state;
}