@mikeargento/bitgraph-audit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Mike Argento
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,11 @@
+# @mikeargento/bitgraph-audit
+
+An Audit Bundle is a portable collection of BitGraph proofs, optionally accompanied by the original artifact bytes, anchor witness material, and a manifest, packaged as a directory, a `.tar`, or a `.tar.gz`. The premise: the operator's database is not the evidence. BitGraph proofs are self-contained objects, and this package lets an independent reader take a bundle, verify whatever evidence it contains fully offline, and reconstruct the causal record without asking the operator which history to trust. The on-disk format is specified in [docs/BUNDLE-FORMAT.md](https://github.com/mikeargento/bitgraph/blob/main/docs/BUNDLE-FORMAT.md); both this consumer and the bitgraph.ing exporter conform to it.
+
+The tool reports exactly what the evidence supports, nothing more. Incomplete input produces an incomplete reconstruction: missing proofs surface as unexplained counter positions and broken predecessor links, which means the supplied evidence cannot reconstruct those positions, not that the authority failed to create them. Divergence between valid objects is presented, never resolved; the reader adjudicates. Proofs without their artifact bytes pass through the bytes-free integrity checks and are reported as artifact-unavailable, never as fully verified. Wall-clock bounds appear only when independently verifiable offline evidence (a locally reconstructed Ethereum block header) is present in the bundle. There is no network access at runtime of any kind.
+
+Exactly one proof schema is supported: `bitgraph/1`. The legacy `occ/1` schema is pre-release beta data and is permanently out of scope; proof-shaped files with any other version are rejected at ingest with the stable code `unsupported-version`. All verification semantics come from `@mikeargento/bitgraph-verify` (MIT), the same verifier anyone can run against a single proof. The `bitgraph-audit` CLI runs the whole pipeline (ingest, verification tiers, causal reconstruction, anomaly classification, authority analysis, anchor identification, witness verification, temporal bounds, offline attestation validation) and writes `audit-report.json` and `audit-report.md`; `runAudit()` is the one-call library entry point, and every stage is also exported individually. See [docs/HOW-TO-AUDIT.md](https://github.com/mikeargento/bitgraph/blob/main/docs/HOW-TO-AUDIT.md) for the recipient walkthrough and [docs/BUNDLE-FORMAT.md](https://github.com/mikeargento/bitgraph/blob/main/docs/BUNDLE-FORMAT.md) for the on-disk format.
+
+## License
+
+MIT. See LICENSE.

package/dist/anchors.d.ts

@@ -0,0 +1,31 @@
+/**
+ * bitgraph-audit anchor identification (G5)
+ *
+ * Ethereum anchors are ordinary chain members minted by the anchor
+ * service: same counter sequence, same prevB64 links, same signing key as
+ * every other proof on the chain. What makes a proof an anchor is the
+ * SIGNED attribution:
+ *
+ *   - attribution.name === "Ethereum Anchor" is the discriminator.
+ *   - attribution.message carries the Ethereum block hash string.
+ *   - attribution.title carries the block number, only inside the signed
+ *     Etherscan URL.
+ *   - artifact.digestB64 is SHA-256 over the block-hash STRING.
+ *
+ * The unsigned metadata.type === "ethereum-anchor" is corroboration only:
+ * agreement and disagreement are recorded, and metadata alone never makes
+ * a proof an anchor. The unsigned metadata.anchor block timestamp is
+ * never read; wall-clock evidence comes exclusively from verified anchor
+ * witnesses (witness.ts). No wall-clock time is ever derived from a block
+ * number.
+ *
+ * Run after verifyObservedProofs so the records carry the run
+ * verification status; identification itself reads only the signed body.
+ */
+import type { AnchorIdentification, IngestResult } from "./types.js";
+/**
+ * Identify anchor proofs among the observed proofs. Read-only and
+ * deterministic (observation order).
+ */
+export declare function identifyAnchors(ingest: IngestResult): AnchorIdentification;
+//# sourceMappingURL=anchors.d.ts.map

package/dist/anchors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchors.d.ts","sourceRoot":"","sources":["../src/anchors.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EACV,oBAAoB,EAGpB,YAAY,EAEb,MAAM,YAAY,CAAC;AAapB;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,oBAAoB,CAsF1E"}

package/dist/anchors.js

@@ -0,0 +1,116 @@
+// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+const ANCHOR_ATTRIBUTION_NAME = "Ethereum Anchor";
+const ANCHOR_METADATA_TYPE = "ethereum-anchor";
+/**
+ * Strict Etherscan block URL, the exact form the anchor service signs
+ * (packages/hosted/src/bitcoin-anchor.ts): https://etherscan.io/block/{n}.
+ * Anything else is reported unparseable and the block number treated as
+ * absent, never guessed.
+ */
+const ETHERSCAN_BLOCK_URL = /^https:\/\/etherscan\.io\/block\/([0-9]+)$/;
+/**
+ * Identify anchor proofs among the observed proofs. Read-only and
+ * deterministic (observation order).
+ */
+export function identifyAnchors(ingest) {
+    const anchors = [];
+    const metadataOnlyProofHashes = [];
+    const findings = [];
+    for (const proof of ingest.proofs) {
+        const attributionName = readAttributionField(proof, "name");
+        const metadataType = readMetadataType(proof);
+        const signedAnchor = attributionName === ANCHOR_ATTRIBUTION_NAME;
+        if (!signedAnchor) {
+            if (metadataType === ANCHOR_METADATA_TYPE) {
+                // Unsigned claim with no signed backing: recorded, never trusted.
+                metadataOnlyProofHashes.push(proof.proofHash);
+                findings.push({
+                    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.",
+                    details: { proofHash: proof.proofHash },
+                });
+            }
+            continue;
+        }
+        // Corroboration between the signed discriminator and the unsigned
+        // metadata. Only a present-but-different type disagrees; an absent
+        // type is simply absent corroboration.
+        const corroboration = metadataType === ANCHOR_METADATA_TYPE
+            ? "agrees"
+            : metadataType === undefined
+                ? "absent"
+                : "disagrees";
+        if (corroboration === "disagrees") {
+            findings.push({
+                code: "anchor-metadata-disagreement",
+                ...pathOf(proof),
+                message: `signed attribution identifies an Ethereum anchor, but unsigned metadata.type is ` +
+                    `${JSON.stringify(metadataType)}. The signed field governs; the disagreement is recorded.`,
+                details: { proofHash: proof.proofHash, metadataType: metadataType },
+            });
+        }
+        const blockHash = readAttributionField(proof, "message");
+        const title = readAttributionField(proof, "title");
+        const blockNumber = title !== undefined ? (ETHERSCAN_BLOCK_URL.exec(title)?.[1] ?? undefined) : undefined;
+        if (blockNumber === undefined) {
+            findings.push({
+                code: "anchor-title-unparseable",
+                ...pathOf(proof),
+                message: title === undefined
+                    ? "anchor proof carries no signed attribution.title; the signed block number is absent"
+                    : "anchor attribution.title does not parse as an Etherscan block URL; the signed block number is treated as absent",
+                details: {
+                    proofHash: proof.proofHash,
+                    ...(title !== undefined ? { title } : {}),
+                },
+            });
+        }
+        const verification = proof.verification;
+        anchors.push({
+            proofHash: proof.proofHash,
+            ...(proof.epochId !== undefined ? { epochId: proof.epochId } : {}),
+            chainId: proof.chainId,
+            ...(proof.counter !== undefined ? { counter: proof.counter } : {}),
+            ...(proof.slotCounter !== undefined ? { slotCounter: proof.slotCounter } : {}),
+            ...(blockHash !== undefined ? { blockHash } : {}),
+            ...(blockNumber !== undefined ? { blockNumber } : {}),
+            metadataCorroboration: corroboration,
+            ...(verification !== undefined
+                ? {
+                    verificationTier: verification.tier,
+                    verificationStatus: verification.status,
+                    ...(verification.reason !== undefined ? { verificationReason: verification.reason } : {}),
+                }
+                : {}),
+        });
+    }
+    return { anchors, metadataOnlyProofHashes, findings };
+}
+// ---------------------------------------------------------------------------
+// Field readers (tolerant: structural problems belong to the verification
+// dimension, not to anchor identification)
+// ---------------------------------------------------------------------------
+function readAttributionField(proof, field) {
+    const attribution = proof.proof["attribution"];
+    if (attribution === null || typeof attribution !== "object" || Array.isArray(attribution)) {
+        return undefined;
+    }
+    const value = attribution[field];
+    return typeof value === "string" ? value : undefined;
+}
+function readMetadataType(proof) {
+    const metadata = proof.proof["metadata"];
+    if (metadata === null || typeof metadata !== "object" || Array.isArray(metadata)) {
+        return undefined;
+    }
+    const value = metadata["type"];
+    return typeof value === "string" ? value : undefined;
+}
+function pathOf(proof) {
+    const path = proof.sources[0]?.path;
+    return path !== undefined ? { path } : {};
+}
+//# sourceMappingURL=anchors.js.map

package/dist/anchors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchors.js","sourceRoot":"","sources":["../src/anchors.ts"],"names":[],"mappings":"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"}

package/dist/anomalies.d.ts

@@ -0,0 +1,42 @@
+/**
+ * bitgraph-audit anomaly classification
+ *
+ * Classifies the reconstructed record with stable machine-readable codes
+ * and builds divergence records for every conflict between valid proofs.
+ *
+ * The G2 two-position rule governs the gap logic: every proof consumes TWO
+ * counter positions, its slotCounter N and its commit counter M with
+ * N < M (usually M = N + 1, but the enclave guarantees only the strict
+ * inequality, and concurrent slot allocation can interleave). A position
+ * within a partition's observed [min, max] range is EXPLAINED when it
+ * appears as any observed proof's commit counter OR any observed proof's
+ * slotCounter. Only unexplained positions are reported, always as
+ * unexplained from the supplied evidence (a proof absent from the bundle
+ * OR a slot that was allocated but never committed, indistinguishable
+ * offline), never as asserted authority failure. Anchor proofs are
+ * ordinary chain members; their positions count normally.
+ *
+ * Dimension discipline: verification status and chain topology stay
+ * separate throughout. Topology anomalies are computed over all observed
+ * members regardless of verification outcome (with statuses reported
+ * alongside), a verifier failure is never reinterpreted as a chain
+ * anomaly, and a chain observation never changes a verification result.
+ * Divergence parties, however, must be valid: conflicts are declared
+ * between valid proofs only (per their definitions), and cryptographically
+ * invalid proofs appear as observed context, never as competing branches.
+ *
+ * Run after verifyObservedProofs and reconstructChains. Isolated validity
+ * rechecks reset the verify package's module-level epoch link state (see
+ * validity.ts).
+ */
+import type { AnomalyReport, IngestResult, ReconstructionResult } from "./types.js";
+/**
+ * Classify anomalies and build divergence records over a reconstructed
+ * bundle. Read-only over its inputs. Deterministic: anomalies follow
+ * partition order, then a fixed per-partition analysis order (gaps,
+ * counter collisions, slot collisions, cross-kind position reuse,
+ * predecessor reuse, chain breaks, multiple genesis, slot order), then
+ * epoch link anomalies.
+ */
+export declare function classifyAnomalies(ingest: IngestResult, reconstruction: ReconstructionResult): Promise<AnomalyReport>;
+//# sourceMappingURL=anomalies.d.ts.map

package/dist/anomalies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anomalies.d.ts","sourceRoot":"","sources":["../src/anomalies.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EACV,aAAa,EAMb,YAAY,EAGZ,oBAAoB,EAErB,MAAM,YAAY,CAAC;AAcpB;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,YAAY,EACpB,cAAc,EAAE,oBAAoB,GACnC,OAAO,CAAC,aAAa,CAAC,CAyBxB"}