@mikeargento/bitgraph-audit 0.1.0

package/src/audit.ts

@@ -0,0 +1,136 @@
+// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+
+/**
+ * Audit orchestrator: the full offline pipeline in canonical order.
+ *
+ *   ingest -> verify tiers -> reconstruct -> classify anomalies ->
+ *   analyze authorities -> identify anchors -> verify witnesses ->
+ *   derive temporal bounds -> validate attestations
+ *
+ * Deterministic given the same bundle: the only wall-clock read in the
+ * entire pipeline is the runMetadata.startedAt stamp taken here. Every
+ * other value in the AuditResult, and in both reports built from it, is a
+ * pure function of the bundle contents and the tool version. Certificate
+ * validity windows during attestation validation are evaluated at each
+ * attestation document's OWN timestamp, never the clock.
+ *
+ * Zero network access, as everywhere in this package.
+ */
+
+import { readFileSync } from "node:fs";
+import { ingestBundle } from "./ingest.js";
+import { verifyObservedProofs } from "./verify-tiers.js";
+import { reconstructChains } from "./reconstruct.js";
+import { classifyAnomalies } from "./anomalies.js";
+import { analyzeAuthorities } from "./authority.js";
+import { identifyAnchors } from "./anchors.js";
+import { verifyAnchorWitnesses } from "./witness.js";
+import { deriveTemporalBounds } from "./temporal.js";
+import { validateAttestations } from "./attestation.js";
+import type { AuditOptions, AuditResult, ExitFlags } from "./types.js";
+
+let cachedToolVersion: string | undefined;
+
+/** The audit package's own version, read once from its package.json. */
+export function auditToolVersion(): string {
+  if (cachedToolVersion === undefined) {
+    const raw = readFileSync(new URL("../package.json", import.meta.url), "utf8");
+    cachedToolVersion = (JSON.parse(raw) as { version: string }).version;
+  }
+  return cachedToolVersion;
+}
+
+/**
+ * Run the complete audit pipeline over a bundle (directory, .tar, .tar.gz,
+ * or .tgz) and return everything every stage produced.
+ */
+export async function runAudit(bundlePath: string, options?: AuditOptions): Promise<AuditResult> {
+  // The ONLY wall-clock read in the pipeline. See AuditRunMetadata.
+  const startedAt = new Date().toISOString();
+
+  const ingest = await ingestBundle(bundlePath);
+  const verification = await verifyObservedProofs(
+    ingest,
+    options?.trustAnchors !== undefined ? { trustAnchors: options.trustAnchors } : undefined
+  );
+  const reconstruction = await reconstructChains(ingest);
+  const anomalies = await classifyAnomalies(ingest, reconstruction);
+  const authorities = analyzeAuthorities(ingest);
+  const anchors = identifyAnchors(ingest);
+  const witnesses = await verifyAnchorWitnesses(ingest, anchors);
+  // Populates EpochRecord.anchorBounds on the reconstruction result.
+  const temporal = deriveTemporalBounds(ingest, reconstruction, anchors, witnesses);
+  const attestations = await validateAttestations(
+    ingest,
+    authorities,
+    options?.trustedRootCaDer !== undefined
+      ? { trustedRootCaDer: options.trustedRootCaDer }
+      : undefined
+  );
+
+  return {
+    runMetadata: {
+      toolVersion: auditToolVersion(),
+      startedAt,
+      bundlePath,
+      container: ingest.container,
+    },
+    ingest,
+    verification,
+    reconstruction,
+    anomalies,
+    authorities,
+    anchors,
+    witnesses,
+    temporal,
+    attestations,
+  };
+}
+
+/**
+ * Anchor witness verification-failure codes: every finding the witness
+ * stage emits is a failure (verifyAnchorWitnesses records findings only for
+ * unverified outcomes), so any witness finding is a genuine problem with
+ * supplied evidence and sets bit 2. The three anchor-stage findings
+ * (anchor-metadata-disagreement, anchor-metadata-only-claim,
+ * anchor-title-unparseable) are informational: the signed body governs and
+ * none is a verification failure, so they never set an exit bit.
+ */
+const WITNESS_VERIFICATION_FAILURE_CODES: ReadonlySet<string> = new Set([
+  "witness-malformed",
+  "witness-rlp-invalid",
+  "witness-header-shape",
+  "witness-hash-mismatch",
+  "witness-digest-mismatch",
+  "witness-block-number-mismatch",
+  "witness-claimed-hash-mismatch",
+  "witness-anchor-invalid",
+  "witness-unmatched",
+]);
+
+/**
+ * Derive the CLI exit bit flags from an audit result. Semantics are
+ * documented on the ExitFlags type: bit 1 is verification failures
+ * (including unsupported-version rejections), bit 2 is chain or authority
+ * anomalies, divergences between valid proofs, or anchor witness
+ * verification failures. artifact-unavailable is never a failure by itself;
+ * attestation results and informational anchor findings never set bits;
+ * benign ingest findings never set bits.
+ */
+export function computeExitFlags(result: AuditResult): ExitFlags {
+  const verificationFailures =
+    result.verification.failed > 0 || result.ingest.counts.unsupportedVersion > 0;
+  const witnessVerificationFailures = result.witnesses.findings.some((f) =>
+    WITNESS_VERIFICATION_FAILURE_CODES.has(f.code)
+  );
+  const chainAnomaliesOrDivergences =
+    result.anomalies.anomalies.length > 0 ||
+    result.anomalies.divergences.length > 0 ||
+    result.authorities.anomalies.length > 0 ||
+    witnessVerificationFailures;
+  return {
+    verificationFailures,
+    chainAnomaliesOrDivergences,
+    code: (verificationFailures ? 1 : 0) | (chainAnomaliesOrDivergences ? 2 : 0),
+  };
+}

package/src/authority.ts

@@ -0,0 +1,165 @@
+// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+
+/**
+ * bitgraph-audit authority analysis
+ *
+ * Groups observed proofs by the authority facets of the record: declared
+ * measurement, signer key, epochId, chainId, and attestation presence.
+ * Flags intra-epoch changes that a single healthy enclave boot cannot
+ * produce (one boot means one keypair and one measurement per epoch):
+ *
+ *   - mid-epoch-signer-change: two or more distinct signer keys within
+ *     one epochId.
+ *   - mid-epoch-measurement-change: two or more distinct declared
+ *     measurements within one epochId.
+ *
+ * The same signer key appearing across different epochs is NORMAL epoch
+ * transition evidence and is surfaced without an anomaly.
+ *
+ * Measurement honesty: everything here reads DECLARED values, which are
+ * self-reported fields inside the signed body (environment.measurement).
+ * A declared measurement is never conflated with an attested measurement:
+ * attestation validation belongs to a later stage, which populates the
+ * typed AuthorityGroup.attested extension point after cryptographically
+ * validating attestation documents offline. attestationPresent records
+ * only that a document exists; presence alone proves nothing.
+ *
+ * Dimension discipline: grouping and flags cover all observed proofs
+ * regardless of verification outcome. An authority anomaly never changes
+ * a proof's verification status; per-proof statuses live on the observed
+ * proofs themselves.
+ */
+
+import type {
+  AuthorityAnalysis,
+  AuthorityGroup,
+  ChainAnomaly,
+  IngestResult,
+  ObservedProof,
+  SignerEpochSpan,
+} from "./types.js";
+import { pushMap } from "./validity.js";
+
+/**
+ * Analyze authority structure over every observed proof (including
+ * chainless proofs, which group with epochId absent). Read-only and
+ * deterministic.
+ */
+export function analyzeAuthorities(ingest: IngestResult): AuthorityAnalysis {
+  // -----------------------------------------------------------------------
+  // Grouping.
+  // -----------------------------------------------------------------------
+  const groupsByKey = new Map<string, AuthorityGroup>();
+  for (const proof of ingest.proofs) {
+    const mapKey = JSON.stringify([
+      proof.measurement ?? null,
+      proof.publicKeyB64 ?? null,
+      proof.epochId ?? null,
+      proof.chainId,
+      proof.hasAttestation,
+    ]);
+    const existing = groupsByKey.get(mapKey);
+    if (existing !== undefined) {
+      existing.proofHashes.push(proof.proofHash);
+      continue;
+    }
+    groupsByKey.set(mapKey, {
+      ...(proof.measurement !== undefined ? { measurement: proof.measurement } : {}),
+      ...(proof.publicKeyB64 !== undefined ? { publicKeyB64: proof.publicKeyB64 } : {}),
+      ...(proof.epochId !== undefined ? { epochId: proof.epochId } : {}),
+      chainId: proof.chainId,
+      attestationPresent: proof.hasAttestation,
+      proofHashes: [proof.proofHash],
+      // attested is deliberately left undefined: the attestation
+      // validation stage (Phase 4c) fills it. Declared measurement above
+      // is self-reported and never treated as attested.
+    });
+  }
+  const groups = [...groupsByKey.values()].sort(compareGroups);
+
+  // -----------------------------------------------------------------------
+  // Intra-epoch flags. epochId is boot-scoped: one enclave boot generates
+  // one keypair and one measurement, shared across every chain it serves,
+  // so the flags aggregate per epochId across chains.
+  // -----------------------------------------------------------------------
+  const byEpoch = new Map<string, ObservedProof[]>();
+  for (const proof of ingest.proofs) {
+    if (proof.epochId === undefined) continue;
+    pushMap(byEpoch, proof.epochId, proof);
+  }
+
+  const anomalies: ChainAnomaly[] = [];
+  for (const [epochId, proofs] of [...byEpoch.entries()].sort(([a], [b]) =>
+    a < b ? -1 : a > b ? 1 : 0
+  )) {
+    const keys = new Set<string>();
+    const measurements = new Set<string>();
+    for (const proof of proofs) {
+      if (proof.publicKeyB64 !== undefined) keys.add(proof.publicKeyB64);
+      if (proof.measurement !== undefined) measurements.add(proof.measurement);
+    }
+
+    if (keys.size >= 2) {
+      anomalies.push({
+        code: "mid-epoch-signer-change",
+        proofHashes: proofs.map((p) => p.proofHash),
+        message:
+          `${keys.size} distinct signer keys appear within epoch ${epochId}. A single enclave boot ` +
+          `generates exactly one keypair per epoch, so multiple keys under one epochId cannot come ` +
+          `from one healthy authority lifecycle. All key groups are preserved for adjudication.`,
+        details: {
+          epochId,
+          publicKeysB64: [...keys].sort(),
+        },
+      });
+    }
+
+    if (measurements.size >= 2) {
+      anomalies.push({
+        code: "mid-epoch-measurement-change",
+        proofHashes: proofs.map((p) => p.proofHash),
+        message:
+          `${measurements.size} distinct declared measurements appear within epoch ${epochId}. A ` +
+          `single enclave boot has exactly one measurement, so multiple declared measurements under ` +
+          `one epochId cannot come from one healthy authority lifecycle. Declared measurements are ` +
+          `self-reported; attestation validation is reported separately.`,
+        details: {
+          epochId,
+          measurements: [...measurements].sort(),
+        },
+      });
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  // Cross-epoch same-signer spans: normal transition evidence.
+  // -----------------------------------------------------------------------
+  const epochsByKey = new Map<string, Set<string>>();
+  for (const proof of ingest.proofs) {
+    if (proof.publicKeyB64 === undefined || proof.epochId === undefined) continue;
+    const set = epochsByKey.get(proof.publicKeyB64);
+    if (set === undefined) epochsByKey.set(proof.publicKeyB64, new Set([proof.epochId]));
+    else set.add(proof.epochId);
+  }
+  const sharedSignersAcrossEpochs: SignerEpochSpan[] = [...epochsByKey.entries()]
+    .filter(([, epochs]) => epochs.size >= 2)
+    .map(([publicKeyB64, epochs]) => ({ publicKeyB64, epochIds: [...epochs].sort() }))
+    .sort((a, b) => (a.publicKeyB64 < b.publicKeyB64 ? -1 : a.publicKeyB64 > b.publicKeyB64 ? 1 : 0));
+
+  return { groups, anomalies, sharedSignersAcrossEpochs };
+}
+
+function compareGroups(a: AuthorityGroup, b: AuthorityGroup): number {
+  if (a.chainId !== b.chainId) return a.chainId < b.chainId ? -1 : 1;
+  const ea = a.epochId ?? "";
+  const eb = b.epochId ?? "";
+  if (ea !== eb) return ea < eb ? -1 : 1;
+  const ka = a.publicKeyB64 ?? "";
+  const kb = b.publicKeyB64 ?? "";
+  if (ka !== kb) return ka < kb ? -1 : 1;
+  const ma = a.measurement ?? "";
+  const mb = b.measurement ?? "";
+  if (ma !== mb) return ma < mb ? -1 : 1;
+  if (a.attestationPresent !== b.attestationPresent) return a.attestationPresent ? -1 : 1;
+  return 0;
+}

package/src/aws-nitro-root-ca.ts

@@ -0,0 +1,47 @@
+// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+
+/**
+ * AWS Nitro Enclaves Root CA G1
+ *
+ * Source: https://aws-nitro-enclaves.amazonaws.com/AWS_NitroEnclaves_Root-G1.zip
+ * Subject: CN=aws.nitro-enclaves, O=Amazon, OU=AWS, C=US
+ * Validity: 2019-10-28 to 2049-10-28
+ * SHA-256 fingerprint (DER):
+ *   641a0321a3e244efe456463195d606317ed7cdcc3c1756e09893f3c68f79bb5b
+ *
+ * This is the trust anchor for all AWS Nitro Enclave attestations. It is
+ * stable, well-known, and never changes, so it is safe to embed. The PEM
+ * string below is byte-for-byte the same constant the website validator
+ * embeds (website/src/lib/aws-nitro-root-ca.ts); the fingerprint above
+ * matches the value AWS publishes for the Root G1 certificate.
+ *
+ * No network access: this constant exists precisely so the audit tool
+ * never fetches trust material at runtime.
+ */
+
+export const AWS_NITRO_ROOT_CA_PEM = `-----BEGIN CERTIFICATE-----
+MIICETCCAZagAwIBAgIRAPkxdWgbkK/hHUbMtOTn+FYwCgYIKoZIzj0EAwMwSTEL
+MAkGA1UEBhMCVVMxDzANBgNVBAoMBkFtYXpvbjEMMAoGA1UECwwDQVdTMRswGQYD
+VQQDDBJhd3Mubml0cm8tZW5jbGF2ZXMwHhcNMTkxMDI4MTMyODA1WhcNNDkxMDI4
+MTQyODA1WjBJMQswCQYDVQQGEwJVUzEPMA0GA1UECgwGQW1hem9uMQwwCgYDVQQL
+DANBV1MxGzAZBgNVBAMMEmF3cy5uaXRyby1lbmNsYXZlczB2MBAGByqGSM49AgEG
+BSuBBAAiA2IABPwCVOumCMHzaHDimtqQvkY4MpJzbolL//Zy2YlES1BR5TSksfbb
+48C8WBoyt7F2Bw7eEtaaP+ohG2bnUs990d0JX28TcPQXCEPZ3BABIeTPYwEoCWZE
+h8l5YoQwTcU/9KNCMEAwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUkCW1DdkF
+R+eWw5b6cp3PmanfS5YwDgYDVR0PAQH/BAQDAgGGMAoGCCqGSM49BAMDA2kAMGYC
+MQCjfy+Rocm9Xue4YnwWmNJVA44fA0P5W2OpYow9OYCVRaEevL8uO1XYru5xtMPW
+rfMCMQCi85sWBbJwKKXdS6BptQFuZbT73o/gBh1qUxl/nNr12UO8Yfwr6wPLb+6N
+IwLz3/Y=
+-----END CERTIFICATE-----`;
+
+/** Strip PEM headers/footers and whitespace, return base64 DER. */
+export function rootCaDerB64(): string {
+  return AWS_NITRO_ROOT_CA_PEM.replace(/-----BEGIN CERTIFICATE-----/, "")
+    .replace(/-----END CERTIFICATE-----/, "")
+    .replace(/\s+/g, "");
+}
+
+/** Decode the root CA PEM to raw DER bytes. */
+export function rootCaDerBytes(): Uint8Array {
+  return new Uint8Array(Buffer.from(rootCaDerB64(), "base64"));
+}

package/src/cli.ts

@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+
+/**
+ * bitgraph-audit CLI: run the full offline audit pipeline over a bundle
+ * and write audit-report.json and/or audit-report.md.
+ *
+ * Report content goes to files only; stdout carries a short completion
+ * line naming the written files and the exit meaning. The CLI performs
+ * no network access. Arguments are parsed with plain process.argv
+ * handling, no dependency.
+ *
+ * Exit codes are bit flags (documented in --help and on the ExitFlags
+ * type): 0 clean, 1 verification failures (including unsupported-version
+ * rejections), 2 chain or authority anomalies, divergences between valid
+ * proofs, or anchor witness verification failures, 3 both, 64 usage or
+ * input error (no report was produced).
+ */
+
+import { readFileSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { VerificationPolicy } from "@mikeargento/bitgraph-verify";
+import { auditToolVersion, computeExitFlags, runAudit } from "./audit.js";
+import { buildJsonReport } from "./report-json.js";
+import { buildMarkdownReport } from "./report-md.js";
+import type { ExitFlags } from "./types.js";
+
+const USAGE_EXIT_CODE = 64;
+
+/** The 14 fields of the canonical VerificationPolicy (verify package, G7). */
+const KNOWN_POLICY_FIELDS: readonly string[] = [
+  "requireEnforcement",
+  "allowedMeasurements",
+  "allowedPublicKeys",
+  "requireAttestation",
+  "requireAttestationFormat",
+  "minCounter",
+  "maxCounter",
+  "minTime",
+  "maxTime",
+  "requireEpochId",
+  "requireActor",
+  "allowedActorKeyIds",
+  "allowedActorProviders",
+  "requireSlot",
+];
+
+class UsageError extends Error {}
+
+const USAGE_LINE =
+  "Usage: bitgraph-audit <path-to-bundle> [--out <dir>] [--format json,md] [--trust-policy <path>]";
+
+function helpText(): string {
+  return [
+    `bitgraph-audit ${auditToolVersion()}: offline audit of BitGraph proof bundles.`,
+    "",
+    USAGE_LINE,
+    "",
+    "The bundle may be a directory, a .tar archive, or a .tar.gz/.tgz",
+    "archive. The audit runs entirely offline: no RPC, no HTTP, no DNS.",
+    "",
+    "Options:",
+    "  --out <dir>            Directory to write the report files into",
+    "                         (default: current directory; created if missing).",
+    "  --format <list>        Comma-separated formats to write: json, md",
+    "                         (default: json,md). json writes audit-report.json;",
+    "                         md writes audit-report.md.",
+    "  --trust-policy <path>  JSON file parsed as the canonical",
+    "                         VerificationPolicy and applied at both",
+    "                         verification tiers. Valid fields:",
+    `                         ${KNOWN_POLICY_FIELDS.join(", ")}.`,
+    "                         Any other field is an error.",
+    "  --help, -h             Print this help and exit 0.",
+    "",
+    "Exit codes (bit flags):",
+    "  0   Clean: no verification failures, no chain anomalies, no",
+    "      divergences.",
+    "  1   Verification failures: at least one proof failed its canonical",
+    "      cryptographic checks at either tier, or at least one",
+    "      proof-shaped input was rejected as an unsupported version",
+    "      (only bitgraph/1 is supported). A proof whose artifact bytes",
+    "      are absent from the bundle is NOT a failure by itself: its",
+    "      bytes-free checks decide, unless a supplied trust policy makes",
+    "      them fail (for example requireSlot), in which case it counts",
+    "      here.",
+    "  2   Chain or authority anomalies, divergences between valid proofs,",
+    "      or anchor witness verification failures: unexplained counter",
+    "      positions, chain breaks, collisions, cross-kind position reuse,",
+    "      forks, authority changes inside an epoch, epoch link anomalies,",
+    "      or a supplied anchor witness that fails its offline verification",
+    "      (block-hash mismatch, digest binding, block number, header or",
+    "      RLP malformation, an invalid candidate anchor, or an unmatched",
+    "      witness). Benign findings are reported but never set exit bits:",
+    "      duplicate copies, manifest advisories, unsafe paths, embedded",
+    "      proofHash mismatches, and informational anchor findings (unsigned",
+    "      metadata disagreements, metadata-only anchor claims, and",
+    "      unparseable anchor titles, all overridden by the signed body).",
+    "  3   Both 1 and 2.",
+    "  64  Usage or input error: unknown option, unreadable bundle, or",
+    "      invalid trust policy. No report was produced.",
+    "",
+    "Attestation validation results are always reported in full but never",
+    "change the exit code on their own: an invalid attestation document on",
+    "an otherwise verified proof is reported without affecting the exit",
+    "code, and counts under exit bit 1 only when a supplied trust policy",
+    "made verification itself fail.",
+  ].join("\n");
+}
+
+interface ParsedArgs {
+  bundlePath: string;
+  outDir: string;
+  formats: ReadonlySet<"json" | "md">;
+  trustPolicyPath?: string;
+}
+
+function parseArgs(argv: string[]): ParsedArgs | "help" {
+  let bundlePath: string | undefined;
+  let outDir = ".";
+  let formats: Set<"json" | "md"> = new Set(["json", "md"]);
+  let trustPolicyPath: string | undefined;
+
+  const takeValue = (flag: string, index: number): string => {
+    const value = argv[index + 1];
+    if (value === undefined) throw new UsageError(`${flag} requires a value.`);
+    return value;
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i] as string;
+    if (arg === "--help" || arg === "-h") return "help";
+    if (arg === "--out") {
+      outDir = takeValue(arg, i);
+      i++;
+    } else if (arg === "--format") {
+      const raw = takeValue(arg, i);
+      i++;
+      const parts = raw
+        .split(",")
+        .map((p) => p.trim())
+        .filter((p) => p.length > 0);
+      if (parts.length === 0) throw new UsageError("--format requires at least one of: json, md.");
+      formats = new Set();
+      for (const part of parts) {
+        if (part !== "json" && part !== "md") {
+          throw new UsageError(`unknown format "${part}". Valid formats: json, md.`);
+        }
+        formats.add(part);
+      }
+    } else if (arg === "--trust-policy") {
+      trustPolicyPath = takeValue(arg, i);
+      i++;
+    } else if (arg.startsWith("-")) {
+      throw new UsageError(`unknown option "${arg}".`);
+    } else if (bundlePath === undefined) {
+      bundlePath = arg;
+    } else {
+      throw new UsageError("more than one bundle path was given.");
+    }
+  }
+
+  if (bundlePath === undefined) throw new UsageError("missing bundle path.");
+  return {
+    bundlePath,
+    outDir,
+    formats,
+    ...(trustPolicyPath !== undefined ? { trustPolicyPath } : {}),
+  };
+}
+
+function loadTrustPolicy(path: string): VerificationPolicy {
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (err) {
+    throw new UsageError(
+      `cannot read trust policy file "${path}": ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new UsageError(`trust policy file "${path}" is not valid JSON.`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new UsageError("trust policy must be a JSON object.");
+  }
+  const unknown = Object.keys(parsed).filter((key) => !KNOWN_POLICY_FIELDS.includes(key));
+  if (unknown.length > 0) {
+    throw new UsageError(
+      `unknown trust policy ${unknown.length === 1 ? "field" : "fields"}: ` +
+        `${unknown.join(", ")}. Valid fields: ${KNOWN_POLICY_FIELDS.join(", ")}.`
+    );
+  }
+  return parsed as VerificationPolicy;
+}
+
+function exitMeaning(flags: ExitFlags): string {
+  if (flags.code === 0) return "clean: no verification failures, no chain anomalies, no divergences";
+  const parts: string[] = [];
+  if (flags.verificationFailures) parts.push("verification failures");
+  if (flags.chainAnomaliesOrDivergences) {
+    parts.push("chain anomalies, divergences, or anchor witness verification failures");
+  }
+  return parts.join("; ");
+}
+
+async function main(): Promise<number> {
+  let parsed: ParsedArgs | "help";
+  try {
+    parsed = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    if (err instanceof UsageError) {
+      process.stderr.write(`bitgraph-audit: ${err.message}\n${USAGE_LINE}\nSee --help for details.\n`);
+      return USAGE_EXIT_CODE;
+    }
+    throw err;
+  }
+  if (parsed === "help") {
+    process.stdout.write(helpText() + "\n");
+    return 0;
+  }
+
+  let trustAnchors: VerificationPolicy | undefined;
+  try {
+    if (parsed.trustPolicyPath !== undefined) {
+      trustAnchors = loadTrustPolicy(parsed.trustPolicyPath);
+    }
+  } catch (err) {
+    if (err instanceof UsageError) {
+      process.stderr.write(`bitgraph-audit: ${err.message}\n${USAGE_LINE}\nSee --help for details.\n`);
+      return USAGE_EXIT_CODE;
+    }
+    throw err;
+  }
+
+  let result;
+  try {
+    result = await runAudit(
+      parsed.bundlePath,
+      trustAnchors !== undefined ? { trustAnchors } : undefined
+    );
+  } catch (err) {
+    process.stderr.write(
+      `bitgraph-audit: cannot audit "${parsed.bundlePath}": ` +
+        `${err instanceof Error ? err.message : String(err)}\n`
+    );
+    return USAGE_EXIT_CODE;
+  }
+
+  await mkdir(parsed.outDir, { recursive: true });
+  const written: string[] = [];
+  if (parsed.formats.has("json")) {
+    const path = join(parsed.outDir, "audit-report.json");
+    await writeFile(path, JSON.stringify(buildJsonReport(result), null, 2) + "\n", "utf8");
+    written.push(path);
+  }
+  if (parsed.formats.has("md")) {
+    const path = join(parsed.outDir, "audit-report.md");
+    await writeFile(path, buildMarkdownReport(result), "utf8");
+    written.push(path);
+  }
+
+  const flags = computeExitFlags(result);
+  process.stdout.write(
+    `bitgraph-audit ${auditToolVersion()}: wrote ${written.join(", ")}\n` +
+      `exit ${flags.code}: ${exitMeaning(flags)}\n`
+  );
+  return flags.code;
+}
+
+main().then(
+  (code) => {
+    process.exitCode = code;
+  },
+  (err) => {
+    process.stderr.write(
+      `bitgraph-audit: unexpected error: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`
+    );
+    process.exitCode = USAGE_EXIT_CODE;
+  }
+);