@mikeargento/bitgraph-audit 0.4.1 → 0.6.0

package/src/__tests__/anchors.test.ts

@@ -0,0 +1,139 @@
+// Copyright (c) 2024-2026 Argento Computing Inc.
+
+/**
+ * What counts as an anchor, and where its block is read from.
+ *
+ * This package's job is rigour about anchors, and until now it had no test at
+ * all for the discriminator it documents. The discriminator also just changed:
+ * `attribution.name === "Ethereum Anchor"` was the only test, and it is now the
+ * fallback behind the signed `commit.anchor` that enclave v7 introduced.
+ *
+ * The case that matters is the last one. An anchor fused like every other
+ * artifact needs its attribution for the `bitgraph-fuse/1` marker, so the name
+ * is gone and the block has to come from `commit.anchor`. If that stops
+ * working, fused anchors become invisible to an audit.
+ *
+ * Run: node --test packages/audit/src/__tests__/anchors.test.ts
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { identifyAnchors } from "../anchors.ts";
+import type { IngestResult, ObservedProof } from "../types.ts";
+
+const BLOCK = 25928913;
+const HASH = "0x0ce4f044093cdd272ce4d7f47903a2f77e9195c4a5267a3eb7200e3a7d9ba7fa";
+
+function observed(proof: Record<string, unknown>, proofHash: string): ObservedProof {
+  return {
+    proofHash,
+    chainHash: `chain-${proofHash}`,
+    proof: proof as never,
+    sources: [],
+    version: "bitgraph/1",
+    chainId: "bitgraph:main",
+  } as unknown as ObservedProof;
+}
+
+function ingest(proofs: ObservedProof[]): IngestResult {
+  return { bundlePath: "test", container: "directory", proofs } as unknown as IngestResult;
+}
+
+/** Pre-v7: the signed name is the only thing saying anchor. Most of the ledger. */
+const legacy = observed({
+  commit: { counter: "10956" },
+  attribution: {
+    name: "Ethereum Anchor",
+    title: `https://etherscan.io/block/${BLOCK}`,
+    message: HASH,
+  },
+  metadata: { type: "ethereum-anchor" },
+}, "legacy");
+
+/** v7 onward: both the signed mark and the name. */
+const authenticated = observed({
+  commit: { counter: "10957", anchor: { blockNumber: BLOCK, blockHash: HASH } },
+  attribution: {
+    name: "Ethereum Anchor",
+    title: `https://etherscan.io/block/${BLOCK}`,
+    message: HASH,
+  },
+  metadata: { type: "ethereum-anchor" },
+}, "authenticated");
+
+/** Fused: attribution spent on the fuse marker, block only in commit.anchor. */
+const fused = observed({
+  commit: { counter: "10958", anchor: { blockNumber: BLOCK, blockHash: HASH } },
+  attribution: { name: "bitgraph-fuse/1", title: "container/2" },
+  metadata: { type: "ethereum-anchor" },
+}, "fused");
+
+/** An unsigned claim with nothing behind it. Never an anchor. */
+const metadataOnly = observed({
+  commit: { counter: "10959" },
+  attribution: { name: "Someone" },
+  metadata: { type: "ethereum-anchor" },
+}, "metadata-only");
+
+const notAnAnchor = observed({
+  commit: { counter: "10960" },
+  attribution: { name: "Someone" },
+}, "ordinary");
+
+test("a legacy anchor is still an anchor, and its block still comes from attribution", () => {
+  const { anchors, findings } = identifyAnchors(ingest([legacy]));
+  assert.equal(anchors.length, 1, "the attribution name must keep identifying pre-v7 anchors");
+  assert.equal(anchors[0].blockHash, HASH);
+  assert.equal(anchors[0].blockNumber, String(BLOCK));
+  assert.equal(findings.length, 0);
+});
+
+test("an authenticated anchor reads its block from the signed commit.anchor", () => {
+  const { anchors, findings } = identifyAnchors(ingest([authenticated]));
+  assert.equal(anchors.length, 1);
+  assert.equal(anchors[0].blockHash, HASH);
+  assert.equal(anchors[0].blockNumber, String(BLOCK));
+  assert.equal(findings.length, 0);
+});
+
+test("a fused anchor is identified with no attribution name at all", () => {
+  // The whole point of the migration: attribution is spent on the fuse marker.
+  const { anchors, findings } = identifyAnchors(ingest([fused]));
+  assert.equal(anchors.length, 1, "commit.anchor must identify an anchor on its own");
+  assert.equal(anchors[0].blockHash, HASH, "the block must be readable without attribution");
+  assert.equal(anchors[0].blockNumber, String(BLOCK));
+  assert.equal(
+    findings.filter((f) => f.code === "anchor-title-unparseable").length,
+    0,
+    "an authenticated anchor does not need a parseable title, so absence is not a finding",
+  );
+});
+
+test("an unsigned metadata claim is recorded and refused", () => {
+  const { anchors, metadataOnlyProofHashes, findings } = identifyAnchors(ingest([metadataOnly]));
+  assert.equal(anchors.length, 0);
+  assert.deepEqual(metadataOnlyProofHashes, ["metadata-only"]);
+  assert.equal(findings.filter((f) => f.code === "anchor-metadata-only-claim").length, 1);
+});
+
+test("an ordinary proof is not an anchor and raises nothing", () => {
+  const { anchors, metadataOnlyProofHashes, findings } = identifyAnchors(ingest([notAnAnchor]));
+  assert.equal(anchors.length, 0);
+  assert.equal(metadataOnlyProofHashes.length, 0);
+  assert.equal(findings.length, 0);
+});
+
+test("a legacy anchor without a parseable title still reports that", () => {
+  const noTitle = observed({
+    commit: { counter: "1" },
+    attribution: { name: "Ethereum Anchor", message: HASH },
+  }, "legacy-no-title");
+  const { anchors, findings } = identifyAnchors(ingest([noTitle]));
+  assert.equal(anchors.length, 1);
+  assert.equal(anchors[0].blockNumber, undefined);
+  assert.equal(findings.filter((f) => f.code === "anchor-title-unparseable").length, 1);
+});
+
+test("all forms are found together, in observation order", () => {
+  const { anchors } = identifyAnchors(ingest([legacy, notAnAnchor, authenticated, metadataOnly, fused]));
+  assert.deepEqual(anchors.map((a) => a.proofHash), ["legacy", "authenticated", "fused"]);
+});

package/src/anchors.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
 
 /**
  * bitgraph-audit anchor identification (G5)
@@ -25,6 +25,7 @@
  * verification status; identification itself reads only the signed body.
  */
 
+import { anchorKindOf, anchorMarkOf } from "@mikeargento/bitgraph-verify";
 import type {
   AnchorIdentification,
   AnchorRecord,
@@ -33,7 +34,6 @@ import type {
   ObservedProof,
 } from "./types.js";
 
-const ANCHOR_ATTRIBUTION_NAME = "Ethereum Anchor";
 const ANCHOR_METADATA_TYPE = "ethereum-anchor";
 
 /**
@@ -54,11 +54,16 @@ export function identifyAnchors(ingest: IngestResult): AnchorIdentification {
   const findings: AuditFinding[] = [];
 
   for (const proof of ingest.proofs) {
-    const attributionName = readAttributionField(proof, "name");
     const metadataType = readMetadataType(proof);
-    const signedAnchor = attributionName === ANCHOR_ATTRIBUTION_NAME;
+    // ⚠️ Two forms, and they are not equally strong. "authenticated" means the
+    // enclave wrote commit.anchor after verifying the anchor service's
+    // signature over the claim; "legacy-attribution" means only the signed
+    // name says so, which is every anchor written before enclave v7
+    // (2026-09-06) and most of the ledger. Both are anchors; only one is
+    // backed by something inside the proof.
+    const kind = anchorKindOf(proof.proof);
 
-    if (!signedAnchor) {
+    if (kind === null) {
       if (metadataType === ANCHOR_METADATA_TYPE) {
         // Unsigned claim with no signed backing: recorded, never trusted.
         metadataOnlyProofHashes.push(proof.proofHash);
@@ -66,9 +71,9 @@ export function identifyAnchors(ingest: IngestResult): AnchorIdentification {
           code: "anchor-metadata-only-claim",
           ...pathOf(proof),
           message:
-            "unsigned metadata.type claims ethereum-anchor, but the signed attribution does not " +
-            "identify this proof as an anchor. Metadata is advisory and unsigned; the proof is " +
-            "not treated as an anchor.",
+            "unsigned metadata.type claims ethereum-anchor, but the proof carries neither a signed " +
+            "commit.anchor nor the signed attribution name. Metadata is advisory and unsigned; the " +
+            "proof is not treated as an anchor.",
           details: { proofHash: proof.proofHash },
         });
       }
@@ -89,16 +94,30 @@ export function identifyAnchors(ingest: IngestResult): AnchorIdentification {
         code: "anchor-metadata-disagreement",
         ...pathOf(proof),
         message:
-          `signed attribution identifies an Ethereum anchor, but unsigned metadata.type is ` +
+          `this proof is a signed Ethereum anchor, but unsigned metadata.type is ` +
           `${JSON.stringify(metadataType)}. The signed field governs; the disagreement is recorded.`,
         details: { proofHash: proof.proofHash, metadataType: metadataType as string },
       });
     }
 
-    const blockHash = readAttributionField(proof, "message");
+    // An authenticated anchor carries its block in commit.anchor, which the
+    // enclave signed. Reading it from there rather than from attribution is
+    // what lets an anchor's attribution be used for something else — a
+    // bitgraph-fuse/1 marker, for instance — without the block becoming
+    // unreadable. Legacy anchors keep the old path exactly.
+    const authenticated = anchorMarkOf(proof.proof);
+    const blockHash = authenticated?.blockHash ?? readAttributionField(proof, "message");
     const title = readAttributionField(proof, "title");
-    const blockNumber = title !== undefined ? (ETHERSCAN_BLOCK_URL.exec(title)?.[1] ?? undefined) : undefined;
-    if (blockNumber === undefined) {
+    const blockNumber =
+      authenticated !== null
+        ? String(authenticated.blockNumber)
+        : title !== undefined
+          ? (ETHERSCAN_BLOCK_URL.exec(title)?.[1] ?? undefined)
+          : undefined;
+    // Only a legacy anchor depends on the title for its block number; an
+    // authenticated one has already answered, so an absent title is not a
+    // finding against it.
+    if (blockNumber === undefined && kind === "legacy-attribution") {
       findings.push({
         code: "anchor-title-unparseable",
         ...pathOf(proof),

package/src/anomalies.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
 
 /**
  * bitgraph-audit anomaly classification

package/src/attestation.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
 
 /**
  * bitgraph-audit offline attestation validation

package/src/audit.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
 
 /**
  * Audit orchestrator: the full offline pipeline in canonical order.
@@ -37,7 +37,7 @@ import type { AuditOptions, AuditResult, ExitFlags, IngestResult } from "./types
  * this equals package.json's version, so the constant cannot drift silently
  * across releases.
  */
-export const AUDIT_VERSION = "0.4.1";
+export const AUDIT_VERSION = "0.6.0";
 
 /** The audit package's own version. */
 export function auditToolVersion(): string {

package/src/authority.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
 
 /**
  * bitgraph-audit authority analysis

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

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
 
 /**
  * AWS Nitro Enclaves Root CA G1

package/src/cli.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
 
 /**
  * bitgraph-audit CLI: run the full offline audit pipeline over a bundle
@@ -18,8 +18,10 @@
  */
 
 import { readFileSync } from "node:fs";
-import { mkdir, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { mkdir, mkdtemp, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, basename } from "node:path";
+import { parseCarrier, verifyCarrier } from "@mikeargento/bitgraph-verify";
 import type { VerificationPolicy } from "@mikeargento/bitgraph-verify";
 import { auditToolVersion, computeExitFlags, runAudit } from "./audit.js";
 import { buildJsonReport } from "./report-json.js";
@@ -57,7 +59,11 @@ function helpText(): string {
     "",
     USAGE_LINE,
     "",
-    "The bundle may be a directory, a .tar archive, or a .tar.gz/.tgz",
+    "The bundle may be a directory, a .tar archive, a .tar.gz/.tgz,",
+    "or a single bitgraph-carrier/1 file (a file with its proof inside):",
+    "a carrier is unpacked and audited as the bundle it carries, and its",
+    "own verdict (TRUE / FALSE / UNDETERMINED, with the time window) is",
+    "printed first.",
     "archive. The audit runs entirely offline: no RPC, no HTTP, no DNS.",
     "",
     "Options:",
@@ -236,10 +242,59 @@ async function main(): Promise<number> {
     throw err;
   }
 
+  /* A single carrier file: unpack it to a temp bundle (the committed bytes,
+     the proof, the floor anchor and witness, the ceiling pair when present)
+     and audit THAT, after printing the carrier's own offline verdict. The
+     temp dir is the audit's input, so the reports describe exactly what the
+     file carries; everything else about the run is unchanged. Detection is
+     from the last 8 bytes only, so no ordinary bundle path changes behaviour. */
+  let bundlePath = parsed.bundlePath;
+  let carrierFlags = 0;
+  try {
+    const info = await stat(parsed.bundlePath);
+    const lower = parsed.bundlePath.toLowerCase();
+    const isArchive = lower.endsWith(".tar") || lower.endsWith(".tar.gz") || lower.endsWith(".tgz");
+    if (info.isFile() && !isArchive && info.size >= 26) {
+      const bytes = new Uint8Array(readFileSync(parsed.bundlePath));
+      const parsedCarrier = parseCarrier(bytes);
+      if (parsedCarrier.kind !== "none") {
+        const verdict = await verifyCarrier(bytes);
+        const b = verdict.bounds;
+        const lines = [
+          `carrier: ${verdict.verdict}${verdict.carrier === "corrupt" ? " (block unreadable: corrupted, not judged)" : ""}`,
+          b ? `  not before: block ${b.notBefore.blockNumber}${b.notBefore.timestamp !== null ? ` (${new Date(b.notBefore.timestamp * 1000).toISOString()})` : ""}` : null,
+          b ? `  not after:  ${b.notAfter === null ? "NOT FETCHED (the closing anchor is not inside this file)" : `block ${b.notAfter.blockNumber}${b.notAfter.timestamp !== null ? ` (${new Date(b.notAfter.timestamp * 1000).toISOString()})` : ""}`}` : null,
+          ...verdict.reasons.map((r) => `  - ${r}`),
+        ].filter((l): l is string => l !== null);
+        process.stdout.write(lines.join("\n") + "\n");
+        if (verdict.verdict === "FALSE") carrierFlags |= 1;
+        if (verdict.carrier === "corrupt") carrierFlags |= 2;
+        if (parsedCarrier.kind === "carrier") {
+          const dir = await mkdtemp(join(tmpdir(), "bitgraph-carrier-"));
+          const name = basename(parsed.bundlePath).replace(/\.bitgraph(\.[^.]+)$/i, "$1").replace(/\.bitgraph$/i, "") || "artifact";
+          await writeFile(join(dir, name), parsedCarrier.inner);
+          await writeFile(join(dir, "proof.json"), JSON.stringify(parsedCarrier.payload.proof, null, 2));
+          const anchors = join(dir, "ethereum-anchors");
+          await mkdir(anchors);
+          await writeFile(join(anchors, "anchor-floor.json"), JSON.stringify(parsedCarrier.payload.floor.anchor, null, 2));
+          await writeFile(join(anchors, "anchor-floor.witness.json"), JSON.stringify({ version: "bitgraph-anchor-witness/1", ...parsedCarrier.payload.floor.witness }, null, 2));
+          if (parsedCarrier.payload.ceiling.status === "present") {
+            await writeFile(join(anchors, "anchor-ceiling.json"), JSON.stringify(parsedCarrier.payload.ceiling.anchor, null, 2));
+            await writeFile(join(anchors, "anchor-ceiling.witness.json"), JSON.stringify({ version: "bitgraph-anchor-witness/1", ...parsedCarrier.payload.ceiling.witness }, null, 2));
+          }
+          bundlePath = dir;
+        }
+      }
+    }
+  } catch (err) {
+    // Detection must never take down an ordinary audit: fall through whole.
+    process.stderr.write(`bitgraph-audit: carrier detection skipped: ${err instanceof Error ? err.message : String(err)}\n`);
+  }
+
   let result;
   try {
     result = await runAudit(
-      parsed.bundlePath,
+      bundlePath,
       trustAnchors !== undefined ? { trustAnchors } : undefined
     );
   } catch (err) {
@@ -264,6 +319,10 @@ async function main(): Promise<number> {
   }
 
   const flags = computeExitFlags(result);
+  // A carrier target folds its own verdict into the same two bits.
+  if (carrierFlags & 1) { flags.verificationFailures = true; }
+  if (carrierFlags & 2) { flags.chainAnomaliesOrDivergences = true; }
+  flags.code = flags.code | carrierFlags;
   process.stdout.write(
     `bitgraph-audit ${auditToolVersion()}: wrote ${written.join(", ")}\n` +
       `exit ${flags.code}: ${exitMeaning(flags)}\n`

package/src/contents-hash.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
 
 /**
  * Deterministic bundle contents hash, per docs/BUNDLE-FORMAT.md section 8.

package/src/export.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
 
 /**
  * Bundle archive builder: the producer counterpart of ingest.

package/src/index.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
 
 /**
  * @mikeargento/bitgraph-audit

package/src/ingest.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
 
 /**
  * bitgraph-audit ingest

package/src/reconstruct.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
 
 /**
  * bitgraph-audit causal reconstruction

package/src/report-json.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
 
 /**
  * JSON report builder: turns an AuditResult into the audit-report.json

package/src/report-md.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
 
 /**
  * Markdown report builder: turns an AuditResult into audit-report.md.

package/src/rlp.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
 
 /**
  * bitgraph-audit minimal RLP decoder (internal)

package/src/tar.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
 
 /**
  * Minimal streaming tar reader.

package/src/temporal.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
 
 /**
  * bitgraph-audit temporal bounds

package/src/types.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
 
 /**
  * bitgraph-audit types

package/src/validity.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
 
 /**
  * bitgraph-audit intrinsic validity (internal)

package/src/verify-tiers.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
 
 /**
  * bitgraph-audit verification tiers

package/src/witness.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
 
 /**
  * bitgraph-audit anchor witness verification