@mikeargento/bitgraph-audit 0.6.4 → 0.7.0

package/src/cli.ts

@@ -52,7 +52,7 @@ const KNOWN_POLICY_FIELDS: readonly string[] = [
 class UsageError extends Error {}
 
 const USAGE_LINE =
-  "Usage: bitgraph-audit <path-to-bundle> [--out <dir>] [--format json,md] [--trust-policy <path>]";
+  "Usage: bitgraph-audit <path-to-bundle> [--out <dir>] [--format json,md] [--trust-policy <path>] [--ceiling-writer <0x...>] [--ceiling-chain <id>]";
 
 function helpText(): string {
   return [
@@ -78,6 +78,14 @@ function helpText(): string {
     "                         verification tiers. Valid fields:",
     `                         ${KNOWN_POLICY_FIELDS.join(", ")}.`,
     "                         Any other field is an error.",
+    "  --ceiling-writer <0x…> The address ceilings in time must come from",
+    "                         (default: BitGraph's published writer,",
+    "                         0xf3972408D853c975F86351C311f4310220bbF2a3).",
+    "  --ceiling-chain <id>   Base chain id for ceilings (default 8453).",
+    "                         The audit never goes online, so whether each",
+    "                         ceiling's Base block is on Base's chain is",
+    "                         reported as unchecked: confirm it on basescan.org",
+    "                         or with `bitgraph ceiling verify --rpc <url>`.",
     "  --help, -h             Print this help and exit 0.",
     "",
     "Exit codes (bit flags):",
@@ -98,7 +106,10 @@ function helpText(): string {
     "      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:",
+    "      witness), or a ceiling in time (bitgraph-ceiling/1) that fails",
+    "      its check against its proof (wrong writer, root, block, header).",
+    "      A pending ceiling or a ceiling status note never sets a bit.",
+    "      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",
@@ -120,6 +131,8 @@ interface ParsedArgs {
   outDir: string;
   formats: ReadonlySet<"json" | "md">;
   trustPolicyPath?: string;
+  ceilingWriter?: string;
+  ceilingChain?: number;
 }
 
 function parseArgs(argv: string[]): ParsedArgs | "help" {
@@ -127,6 +140,8 @@ function parseArgs(argv: string[]): ParsedArgs | "help" {
   let outDir = ".";
   let formats: Set<"json" | "md"> = new Set(["json", "md"]);
   let trustPolicyPath: string | undefined;
+  let ceilingWriter: string | undefined;
+  let ceilingChain: number | undefined;
 
   const takeValue = (flag: string, index: number): string => {
     const value = argv[index + 1];
@@ -158,6 +173,15 @@ function parseArgs(argv: string[]): ParsedArgs | "help" {
     } else if (arg === "--trust-policy") {
       trustPolicyPath = takeValue(arg, i);
       i++;
+    } else if (arg === "--ceiling-writer") {
+      ceilingWriter = takeValue(arg, i);
+      i++;
+      if (!/^0x[0-9a-fA-F]{40}$/.test(ceilingWriter)) throw new UsageError("--ceiling-writer must be a 0x address.");
+    } else if (arg === "--ceiling-chain") {
+      ceilingChain = Number(takeValue(arg, i));
+      i++;
+      if (!Number.isInteger(ceilingChain) || ceilingChain <= 0) throw new UsageError("--ceiling-chain must be a chain id.");
+
     } else if (arg.startsWith("-")) {
       throw new UsageError(`unknown option "${arg}".`);
     } else if (bundlePath === undefined) {
@@ -173,6 +197,9 @@ function parseArgs(argv: string[]): ParsedArgs | "help" {
     outDir,
     formats,
     ...(trustPolicyPath !== undefined ? { trustPolicyPath } : {}),
+    ...(ceilingWriter !== undefined ? { ceilingWriter } : {}),
+    ...(ceilingChain !== undefined ? { ceilingChain } : {}),
+
   };
 }
 
@@ -209,7 +236,7 @@ function exitMeaning(flags: ExitFlags): string {
   const parts: string[] = [];
   if (flags.verificationFailures) parts.push("verification failures");
   if (flags.chainAnomaliesOrDivergences) {
-    parts.push("chain anomalies, divergences, or anchor witness verification failures");
+    parts.push("chain anomalies, divergences, or anchor witness verification failures (or a failed ceiling in time)");
   }
   return parts.join("; ");
 }
@@ -308,10 +335,15 @@ async function main(): Promise<number> {
 
   let result;
   try {
-    result = await runAudit(
-      bundlePath,
-      trustAnchors !== undefined ? { trustAnchors } : undefined
-    );
+    const ceilings = {
+      ...(parsed.ceilingWriter !== undefined ? { writer: parsed.ceilingWriter } : {}),
+      ...(parsed.ceilingChain !== undefined ? { chainId: parsed.ceilingChain } : {}),
+
+    };
+    result = await runAudit(bundlePath, {
+      ...(trustAnchors !== undefined ? { trustAnchors } : {}),
+      ceilings,
+    });
   } catch (err) {
     process.stderr.write(
       `bitgraph-audit: cannot audit "${parsed.bundlePath}": ` +
@@ -338,6 +370,13 @@ async function main(): Promise<number> {
   if (carrierFlags & 1) { flags.verificationFailures = true; }
   if (carrierFlags & 2) { flags.chainAnomaliesOrDivergences = true; }
   flags.code = flags.code | carrierFlags;
+  for (const c of result.ceilings?.checks ?? []) {
+    const width = c.window?.widthSeconds != null ? ` (window ${c.window.widthSeconds}s after the floor block)` : "";
+    process.stdout.write(c.status === "verified"
+      ? `ceiling VERIFIED ${c.path}: ${c.label ?? ""}${width}; ${c.onChainDetail ?? ""}\n`
+      : `ceiling ${c.status.toUpperCase()} ${c.path}: ${c.reason ?? ""}\n`);
+  }
+  for (const s of result.ceilings?.statuses ?? []) process.stdout.write(`ceiling ${s.status} ${s.path}: ${s.note}\n`);
   process.stdout.write(
     `bitgraph-audit ${auditToolVersion()}: wrote ${written.join(", ")}\n` +
       `exit ${flags.code}: ${exitMeaning(flags)}\n`

package/src/index.ts

@@ -101,6 +101,8 @@ export { identifyAnchors } from "./anchors.js";
 export { verifyAnchorWitnesses, verifyAnchorWitness } from "./witness.js";
 
 export { deriveTemporalBounds } from "./temporal.js";
+export { verifyCeilings, BITGRAPH_CEILING_WRITER, BASE_MAINNET_CHAIN_ID } from "./ceilings.js";
+export type { CeilingAuditOptions } from "./ceilings.js";
 
 export { validateAttestations, validateNitroAttestationDocument } from "./attestation.js";
 

package/src/ingest.ts

@@ -43,6 +43,7 @@ import { readTarEntries } from "./tar.js";
 import { combineEntryDigests } from "./contents-hash.js";
 import type {
   AnchorWitnessFile,
+  CeilingFile,
   ArtifactRecord,
   AuditFinding,
   BundleManifest,
@@ -82,6 +83,8 @@ const NUL = new Uint8Array([0]);
 const MANIFEST_PATH = "manifest.json";
 const BUNDLE_VERSION = "bitgraph-bundle/1";
 const WITNESS_VERSION = "bitgraph-anchor-witness/1";
+const CEILING_VERSION_TAG = "bitgraph-ceiling/1";
+const CEILING_STATUS_VERSION_TAG = "bitgraph-ceiling-status/1";
 
 // ---------------------------------------------------------------------------
 // Public API
@@ -336,6 +339,8 @@ function finalizeIngest(params: FinalizeParams): IngestResult {
   const proofsByHash = new Map<string, ObservedProof>();
   const unsupportedVersions: UnsupportedVersionRecord[] = [];
   const witnesses: AnchorWitnessFile[] = [];
+  const ceilings: CeilingFile[] = [];
+  const ceilingStatuses: CeilingFile[] = [];
   const artifactsByHex = new Map<string, ArtifactRecord>();
   let manifest: ManifestReport | undefined;
   let proofFiles = 0;
@@ -393,6 +398,17 @@ function finalizeIngest(params: FinalizeParams): IngestResult {
       continue;
     }
 
+    // A ceiling in time travels beside its proof: evidence, never an artifact.
+    const pv = parsed !== undefined ? (parsed as Record<string, unknown>)["version"] : undefined;
+    if (pv === CEILING_VERSION_TAG || pv === CEILING_STATUS_VERSION_TAG) {
+      (pv === CEILING_VERSION_TAG ? ceilings : ceilingStatuses).push({
+        path: entry.path,
+        fileSha256Hex: entry.sha256Hex,
+        json: parsed as Record<string, unknown>,
+      });
+      continue;
+    }
+
     indexArtifact(entry, artifactsByHex);
   }
 
@@ -420,6 +436,7 @@ function finalizeIngest(params: FinalizeParams): IngestResult {
     unsupportedVersion: unsupportedVersions.length,
     artifacts: artifacts.length,
     witnesses: witnesses.length,
+    ceilings: ceilings.length + ceilingStatuses.length,
     skippedUnsafePaths,
   };
 
@@ -432,6 +449,8 @@ function finalizeIngest(params: FinalizeParams): IngestResult {
     unsupportedVersions,
     artifacts,
     witnesses,
+    ceilings,
+    ceilingStatuses,
     ...(manifest !== undefined ? { manifest } : {}),
     computedContentsHashB64,
     findings,

package/src/report-json.ts

@@ -109,6 +109,9 @@ export function buildJsonReport(result: AuditResult): AuditJsonReport {
       groups: result.authorities.groups,
       sharedSignersAcrossEpochs: result.authorities.sharedSignersAcrossEpochs,
     },
+    ...(result.ceilings && (result.ceilings.checks.length > 0 || result.ceilings.statuses.length > 0)
+      ? { ceilings: result.ceilings }
+      : {}),
     attestations: {
       records: result.attestations.records,
       counts: result.attestations.counts,

package/src/report-md.ts

@@ -333,6 +333,26 @@ function executiveSummary(
   );
   lines.push("");
 
+  // Ceilings in time (bitgraph-ceiling/1), only when the bundle carries any.
+  const cl = report.ceilings;
+  if (cl && (cl.checks.length > 0 || cl.statuses.length > 0)) {
+    lines.push("### Ceilings in time (Base)");
+    lines.push("");
+    lines.push(`Checked against writer ${inlineCode(cl.writer)} on chain ${cl.chainId}.`);
+    lines.push("");
+    for (const c of cl.checks) {
+      if (c.status === "verified") {
+        const w = c.window!;
+        const width = w.widthSeconds != null ? `, ${w.widthSeconds} s after the floor block` : "";
+        lines.push(`- VERIFIED ${inlineCode(c.path)}: ${c.label ?? ""}${width}. ${c.onChainDetail ?? ""}.`);
+      } else {
+        lines.push(`- ${c.status.toUpperCase()} ${inlineCode(c.path)}: ${c.reason ?? ""}`);
+      }
+    }
+    for (const st of cl.statuses) lines.push(`- ${st.status} ${inlineCode(st.path)}: ${st.note}`);
+    lines.push("");
+  }
+
   // External time evidence.
   lines.push("### External time evidence");
   lines.push("");

package/src/types.ts

@@ -406,6 +406,8 @@ export interface IngestCounts {
   artifacts: number;
   /** Anchor witness files. */
   witnesses: number;
+  /** Ceiling files (bitgraph-ceiling/1) and ceiling status notes (bitgraph-ceiling-status/1). */
+  ceilings?: number;
   /** Container entries skipped for unsafe paths. */
   skippedUnsafePaths: number;
 }
@@ -467,6 +469,10 @@ export interface IngestResult {
   artifacts: ArtifactRecord[];
   /** Anchor witness files in observation order. */
   witnesses: AnchorWitnessFile[];
+  /** Ceiling files (bitgraph-ceiling/1) in observation order. Optional so older embedders' IngestResults still type. */
+  ceilings?: CeilingFile[];
+  /** Ceiling status notes (bitgraph-ceiling-status/1): a package saying why a ceiling is absent. */
+  ceilingStatuses?: CeilingFile[];
   /** Present when a root manifest.json entry existed. */
   manifest?: ManifestReport;
 
@@ -1306,6 +1312,8 @@ export interface AuditOptions {
    * explicitly non-AWS deployments.
    */
   trustedRootCaDer?: Uint8Array;
+  /** Ceilings in time: the declared writer, the chain, and an optional Base RPC for the one online check. */
+  ceilings?: import("./ceilings.js").CeilingAuditOptions;
 }
 
 /**
@@ -1325,6 +1333,48 @@ export interface AuditRunMetadata {
 }
 
 /** Everything one full audit run produced, in pipeline order. */
+/** A ceiling file or a ceiling status note, as found in the bundle. Never an artifact. */
+export interface CeilingFile {
+  path: string;
+  fileSha256Hex: string;
+  json: Record<string, unknown>;
+}
+
+/** One ceiling file checked against its proof (verifyCeiling), offline. */
+export interface CeilingCheck {
+  path: string;
+  proofHash: string | null;
+  /**
+   * verified: every offline check passed. failed: the file is present and
+   * wrong (a tampered or foreign ceiling). pending: the file says no Base
+   * transaction yet. unmatched: no proof in the bundle has its proofHash.
+   */
+  status: "verified" | "failed" | "pending" | "unmatched";
+  reason?: string;
+  /** One line for people, e.g. "Ceiling: Base block N at hh:mm:ss UTC, settled on Ethereum." */
+  label?: string;
+  window?: {
+    floorBlock: number | null;
+    floorTime: number | null;
+    ceilingChainId: number;
+    ceilingBlock: number;
+    ceilingTime: number;
+    widthSeconds: number | null;
+  };
+  /** Online check against a Base RPC: null when not asked or unreachable. */
+  onChain: boolean | null;
+  onChainDetail?: string;
+}
+
+export interface CeilingAnalysis {
+  /** The writer address the ceilings were checked against. */
+  writer: string;
+  chainId: number;
+  checks: CeilingCheck[];
+  /** Status notes carried instead of a ceiling (path and note). */
+  statuses: Array<{ path: string; status: string; note: string }>;
+}
+
 export interface AuditResult {
   runMetadata: AuditRunMetadata;
   ingest: IngestResult;
@@ -1336,6 +1386,8 @@ export interface AuditResult {
   witnesses: AnchorWitnessAnalysis;
   temporal: TemporalAnalysis;
   attestations: AttestationAnalysis;
+  /** Ceilings in time on Base. Absent from results made before this stage existed. */
+  ceilings?: CeilingAnalysis;
 }
 
 /**
@@ -1577,6 +1629,8 @@ export interface AuditJsonReport {
     groups: AuthorityGroup[];
     sharedSignersAcrossEpochs: SignerEpochSpan[];
   };
+  /** Ceilings in time on Base (bitgraph-ceiling/1). Absent when the bundle carries none. */
+  ceilings?: import("./types.js").CeilingAnalysis;
   attestations: {
     records: ProofAttestationRecord[];
     counts: AttestationAnalysis["counts"];