@mikeargento/bitgraph 1.1.0 → 1.2.0

package/src/__tests__/audit-witness.test.ts

@@ -0,0 +1,345 @@
+// Copyright (c) Mike Argento. All rights reserved. See LICENSE.
+
+/**
+ * Anchor witness verification tests (bundle spec section 10.3).
+ *
+ * The synthetic header is a 20-item RLP list with the block number at
+ * index 8 and the timestamp at index 11; its Keccak-256 hash is the
+ * "block hash", the anchor's signed attribution.message is that hash,
+ * and the anchor's artifact digest is SHA-256 over the hash STRING,
+ * exactly like bitcoin-anchor.ts. Full verification yields the header
+ * timestamp; every single-point corruption fails with its own stable
+ * reason and confers nothing.
+ */
+
+import { describe, it } from "node:test";
+import * as assert from "node:assert/strict";
+import { keccak_256 } from "@noble/hashes/sha3";
+import { sha256 } from "@noble/hashes/sha256";
+import {
+  identifyAnchors,
+  ingestBundle,
+  verifyAnchorWitness,
+  verifyAnchorWitnesses,
+  verifyObservedProofs,
+} from "@mikeargento/bitgraph-audit";
+import type { AnchorIdentification, IngestResult } from "@mikeargento/bitgraph-audit";
+import {
+  b64,
+  makeAnchorProof,
+  makeEthereumHeader,
+  makeTempDir,
+  proofJson,
+  utf8,
+  witnessJson,
+  writeBundleDir,
+} from "./audit-fixtures.js";
+
+const BLOCK_NUMBER = 24800448;
+const TIMESTAMP = 1750000000;
+
+const HEADER = makeEthereumHeader({ blockNumber: BLOCK_NUMBER, timestamp: TIMESTAMP });
+const BLOCK_HASH = `0x${Buffer.from(keccak_256(HEADER.headerBytes)).toString("hex")}`;
+
+async function pipeline(
+  files: Record<string, string | Uint8Array>
+): Promise<{ ingest: IngestResult; anchors: AnchorIdentification }> {
+  const dir = await makeTempDir("bg-audit-witness-");
+  await writeBundleDir(dir, files);
+  const ingest = await ingestBundle(dir);
+  await verifyObservedProofs(ingest);
+  return { ingest, anchors: identifyAnchors(ingest) };
+}
+
+function goodWitness(): string {
+  return witnessJson({
+    headerRlpHex: HEADER.headerRlpHex,
+    blockNumber: BLOCK_NUMBER,
+    blockHash: BLOCK_HASH,
+    network: "ethereum-mainnet",
+  });
+}
+
+describe("audit witness: full verification", () => {
+  it("passes every step and yields the header timestamp as the only wall-clock evidence", async () => {
+    const anchor = await makeAnchorProof({
+      blockHash: BLOCK_HASH,
+      blockNumber: String(BLOCK_NUMBER),
+      epochId: "E-W1",
+      counter: "4",
+      slotCounter: "3",
+    });
+    const { ingest, anchors } = await pipeline({
+      "proofs/anchor.json": proofJson(anchor.proof),
+      "witnesses/w.json": goodWitness(),
+    });
+
+    const analysis = await verifyAnchorWitnesses(ingest, anchors);
+    assert.equal(analysis.outcomes.length, 1);
+    const outcome = analysis.outcomes[0]!;
+    assert.equal(outcome.verified, true);
+    assert.equal(outcome.anchorProofHash, anchor.proofHash);
+    assert.equal(outcome.computedBlockHash, BLOCK_HASH);
+    assert.equal(outcome.blockNumber, String(BLOCK_NUMBER));
+    assert.equal(outcome.timestamp, TIMESTAMP);
+    assert.equal(outcome.reason, undefined);
+    assert.equal(analysis.findings.length, 0);
+  });
+
+  it("compares the hash case-insensitively but binds the digest to the exact signed string", async () => {
+    // The anchor signed an UPPERCASE hash string; the digest covers that
+    // exact string. Step 3 lowercases for comparison, step 4 does not.
+    const upper = `0x${BLOCK_HASH.slice(2).toUpperCase()}`;
+    const anchor = await makeAnchorProof({
+      blockHash: upper,
+      blockNumber: String(BLOCK_NUMBER),
+      epochId: "E-W2",
+      counter: "2",
+    });
+    const { ingest, anchors } = await pipeline({
+      "proofs/anchor.json": proofJson(anchor.proof),
+      "witnesses/w.json": goodWitness(),
+    });
+    const analysis = await verifyAnchorWitnesses(ingest, anchors);
+    assert.equal(analysis.outcomes.length, 1);
+    assert.equal(analysis.outcomes[0]!.verified, true);
+    assert.equal(analysis.outcomes[0]!.timestamp, TIMESTAMP);
+  });
+});
+
+describe("audit witness: single-point corruptions fail with distinct stable reasons", () => {
+  it("wrong claimed blockHash: witness-claimed-hash-mismatch", async () => {
+    const anchor = await makeAnchorProof({
+      blockHash: BLOCK_HASH,
+      blockNumber: String(BLOCK_NUMBER),
+      epochId: "E-W3",
+      counter: "2",
+    });
+    const wrongClaim = `0x${"ab".repeat(32)}`;
+    const { ingest, anchors } = await pipeline({
+      "proofs/anchor.json": proofJson(anchor.proof),
+      "witnesses/w.json": witnessJson({
+        headerRlpHex: HEADER.headerRlpHex,
+        blockNumber: BLOCK_NUMBER,
+        blockHash: wrongClaim,
+      }),
+    });
+    const analysis = await verifyAnchorWitnesses(ingest, anchors);
+    const outcome = analysis.outcomes[0]!;
+    assert.equal(outcome.verified, false);
+    assert.equal(outcome.reason, "witness-claimed-hash-mismatch");
+    assert.equal(outcome.timestamp, undefined, "a rejected witness confers nothing");
+    assert.ok(analysis.findings.some((f) => f.code === "witness-claimed-hash-mismatch"));
+  });
+
+  it("wrong artifact digest: witness-digest-mismatch", async () => {
+    // Validly signed anchor whose digest covers a different string, so the
+    // proof itself verifies but the message-to-digest binding fails.
+    const anchor = await makeAnchorProof({
+      blockHash: BLOCK_HASH,
+      blockNumber: String(BLOCK_NUMBER),
+      epochId: "E-W4",
+      counter: "2",
+      digestB64: b64(sha256(utf8("some other committed artifact"))),
+    });
+    const { ingest, anchors } = await pipeline({
+      "proofs/anchor.json": proofJson(anchor.proof),
+      "witnesses/w.json": goodWitness(),
+    });
+    const analysis = await verifyAnchorWitnesses(ingest, anchors);
+    const outcome = analysis.outcomes[0]!;
+    assert.equal(outcome.verified, false);
+    assert.equal(outcome.reason, "witness-digest-mismatch");
+    assert.equal(outcome.timestamp, undefined);
+  });
+
+  it("wrong claimed blockNumber: witness-block-number-mismatch", async () => {
+    const anchor = await makeAnchorProof({
+      blockHash: BLOCK_HASH,
+      blockNumber: String(BLOCK_NUMBER),
+      epochId: "E-W5",
+      counter: "2",
+    });
+    const { ingest, anchors } = await pipeline({
+      "proofs/anchor.json": proofJson(anchor.proof),
+      "witnesses/w.json": witnessJson({
+        headerRlpHex: HEADER.headerRlpHex,
+        blockNumber: BLOCK_NUMBER + 1,
+        blockHash: BLOCK_HASH,
+      }),
+    });
+    const analysis = await verifyAnchorWitnesses(ingest, anchors);
+    const outcome = analysis.outcomes[0]!;
+    assert.equal(outcome.verified, false);
+    assert.equal(outcome.reason, "witness-block-number-mismatch");
+    assert.match(outcome.detail as string, /witness claims blockNumber/);
+  });
+
+  it("signed Etherscan URL disagreeing with the header: witness-block-number-mismatch", async () => {
+    const anchor = await makeAnchorProof({
+      blockHash: BLOCK_HASH,
+      blockNumber: String(BLOCK_NUMBER + 7),
+      epochId: "E-W6",
+      counter: "2",
+    });
+    const { ingest, anchors } = await pipeline({
+      "proofs/anchor.json": proofJson(anchor.proof),
+      "witnesses/w.json": goodWitness(),
+    });
+    const analysis = await verifyAnchorWitnesses(ingest, anchors);
+    const outcome = analysis.outcomes[0]!;
+    assert.equal(outcome.verified, false);
+    assert.equal(outcome.reason, "witness-block-number-mismatch");
+    assert.match(outcome.detail as string, /Etherscan URL/);
+  });
+
+  it("tampered RLP header bytes: witness-hash-mismatch", async () => {
+    const anchor = await makeAnchorProof({
+      blockHash: BLOCK_HASH,
+      blockNumber: String(BLOCK_NUMBER),
+      epochId: "E-W7",
+      counter: "2",
+    });
+    // Flip content bytes in the middle: still well-formed RLP, different
+    // Keccak hash. The witness still reaches its intended anchor through
+    // the claimed hash and fails loudly at step 3.
+    const tampered =
+      HEADER.headerRlpHex.slice(0, 40) +
+      (HEADER.headerRlpHex[40] === "f" ? "e" : "f") +
+      HEADER.headerRlpHex.slice(41);
+    const { ingest, anchors } = await pipeline({
+      "proofs/anchor.json": proofJson(anchor.proof),
+      "witnesses/w.json": witnessJson({
+        headerRlpHex: tampered,
+        blockNumber: BLOCK_NUMBER,
+        blockHash: BLOCK_HASH,
+      }),
+    });
+    const analysis = await verifyAnchorWitnesses(ingest, anchors);
+    const outcome = analysis.outcomes[0]!;
+    assert.equal(outcome.verified, false);
+    assert.equal(outcome.reason, "witness-hash-mismatch");
+    assert.equal(outcome.timestamp, undefined);
+  });
+});
+
+describe("audit witness: malformed and unusable witnesses", () => {
+  it("field violations fail with witness-malformed", async () => {
+    const anchor = await makeAnchorProof({
+      blockHash: BLOCK_HASH,
+      blockNumber: String(BLOCK_NUMBER),
+      epochId: "E-W8",
+      counter: "2",
+    });
+    const { ingest, anchors } = await pipeline({
+      "proofs/anchor.json": proofJson(anchor.proof),
+      "witnesses/no-header.json": witnessJson({
+        blockNumber: BLOCK_NUMBER,
+        blockHash: BLOCK_HASH,
+        omit: ["headerRlpHex"],
+      }),
+      "witnesses/string-number.json": witnessJson({
+        headerRlpHex: HEADER.headerRlpHex,
+        blockNumber: String(BLOCK_NUMBER),
+        blockHash: BLOCK_HASH,
+      }),
+      "witnesses/bad-hash-shape.json": witnessJson({
+        headerRlpHex: HEADER.headerRlpHex,
+        blockNumber: BLOCK_NUMBER,
+        blockHash: "28ed3639",
+      }),
+    });
+    const analysis = await verifyAnchorWitnesses(ingest, anchors);
+    assert.equal(analysis.outcomes.length, 3);
+    for (const outcome of analysis.outcomes) {
+      assert.equal(outcome.verified, false);
+      assert.equal(outcome.reason, "witness-malformed");
+      assert.equal(outcome.timestamp, undefined);
+    }
+  });
+
+  it("structurally invalid RLP fails with witness-rlp-invalid", async () => {
+    const anchor = await makeAnchorProof({
+      blockHash: BLOCK_HASH,
+      blockNumber: String(BLOCK_NUMBER),
+      epochId: "E-W9",
+      counter: "2",
+    });
+    const { ingest, anchors } = await pipeline({
+      "proofs/anchor.json": proofJson(anchor.proof),
+      // 0xf9 declares a long list with a 2-byte length that never arrives.
+      "witnesses/w.json": witnessJson({
+        headerRlpHex: "0xf901",
+        blockNumber: BLOCK_NUMBER,
+        blockHash: BLOCK_HASH,
+      }),
+    });
+    const analysis = await verifyAnchorWitnesses(ingest, anchors);
+    assert.equal(analysis.outcomes[0]!.reason, "witness-rlp-invalid");
+  });
+
+  it("a witness matching no anchor is reported witness-unmatched", async () => {
+    const otherHeader = makeEthereumHeader({ blockNumber: 5, timestamp: 6 });
+    const otherHash = `0x${Buffer.from(keccak_256(otherHeader.headerBytes)).toString("hex")}`;
+    const anchor = await makeAnchorProof({
+      blockHash: BLOCK_HASH,
+      blockNumber: String(BLOCK_NUMBER),
+      epochId: "E-W10",
+      counter: "2",
+    });
+    const { ingest, anchors } = await pipeline({
+      "proofs/anchor.json": proofJson(anchor.proof),
+      "witnesses/w.json": witnessJson({
+        headerRlpHex: otherHeader.headerRlpHex,
+        blockNumber: 5,
+        blockHash: otherHash,
+      }),
+    });
+    const analysis = await verifyAnchorWitnesses(ingest, anchors);
+    const outcome = analysis.outcomes[0]!;
+    assert.equal(outcome.verified, false);
+    assert.equal(outcome.reason, "witness-unmatched");
+    assert.equal(outcome.anchorProofHash, undefined);
+  });
+
+  it("a witness cannot rescue an invalid anchor: witness-anchor-invalid", async () => {
+    const anchor = await makeAnchorProof({
+      blockHash: BLOCK_HASH,
+      blockNumber: String(BLOCK_NUMBER),
+      epochId: "E-W11",
+      counter: "2",
+    });
+    // Tamper the Ed25519 signature: the canonical identity is unchanged
+    // (the signature is outside the signed body) but the proof is invalid.
+    anchor.proof.signer.signatureB64 = `AA${anchor.proof.signer.signatureB64.slice(2)}`;
+    const { ingest, anchors } = await pipeline({
+      "proofs/anchor.json": proofJson(anchor.proof),
+      "witnesses/w.json": goodWitness(),
+    });
+    const analysis = await verifyAnchorWitnesses(ingest, anchors);
+    const outcome = analysis.outcomes[0]!;
+    assert.equal(outcome.verified, false);
+    assert.equal(outcome.reason, "witness-anchor-invalid");
+    assert.equal(outcome.timestamp, undefined);
+  });
+});
+
+describe("audit witness: direct single-pair API", () => {
+  it("verifyAnchorWitness runs the full procedure against one anchor", async () => {
+    const anchor = await makeAnchorProof({
+      blockHash: BLOCK_HASH,
+      blockNumber: String(BLOCK_NUMBER),
+      epochId: "E-W12",
+      counter: "2",
+    });
+    const { ingest } = await pipeline({
+      "proofs/anchor.json": proofJson(anchor.proof),
+      "witnesses/w.json": goodWitness(),
+    });
+    const observed = ingest.proofs.find((p) => p.proofHash === anchor.proofHash)!;
+    const witnessFile = ingest.witnesses[0]!;
+    const outcome = await verifyAnchorWitness(witnessFile, observed);
+    assert.equal(outcome.verified, true);
+    assert.equal(outcome.timestamp, TIMESTAMP);
+  });
+});

package/src/__tests__/chain-hash-anchor.test.ts

@@ -0,0 +1,67 @@
+/**
+ * Regression: computeChainHash must exclude the anchor service's `ethereum`
+ * field so that an Ethereum anchor can be resolved as a chain predecessor.
+ *
+ * Real-data fixture. `anchor-with-ethereum-112758.json` is a live Ethereum
+ * anchor (commit 112758) exactly as it ships in an export bundle: it carries a
+ * top-level `ethereum` { blockNumber, blockHash } field that the anchor service
+ * appended AFTER the enclave signed it. `successor-112760.json` is the next
+ * proof on the chain (the BitGraph whitepaper, commit 112760); its
+ * `commit.prevB64` was computed by the enclave over the anchor as the enclave
+ * saw it — before the `ethereum` field existed.
+ *
+ * The bug (latent since the anchor service began stamping `ethereum` on
+ * 2026-04-01, exposed once the audit tool resolved prevB64 via computeChainHash
+ * on 2026-07-10): computeChainHash hashed the whole proof minus only
+ * `proofHash`, so the appended `ethereum` field poisoned the hash and no
+ * successor's prevB64 could ever match. The anchor "vanished" from the chain
+ * even though it was present in the bundle. The fix excludes `ethereum` (and
+ * any ledger/service-added field) from the chain hash.
+ */
+
+import { describe, it } from "node:test";
+import * as assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { computeChainHash, type BitGraphProof } from "@mikeargento/bitgraph-verify";
+
+function loadFixture(name: string): Record<string, unknown> {
+  const url = new URL(`../../src/__tests__/real-fixtures/${name}`, import.meta.url);
+  return JSON.parse(readFileSync(fileURLToPath(url), "utf8"));
+}
+
+describe("computeChainHash: Ethereum anchor chain link (ethereum-field regression)", () => {
+  const anchor = loadFixture("anchor-with-ethereum-112758.json");
+  const successor = loadFixture("successor-112760.json");
+  const expectedPrev = (successor.commit as { prevB64: string }).prevB64;
+
+  it("the fixture is the real shape: anchor carries a top-level ethereum field", () => {
+    assert.ok(Object.prototype.hasOwnProperty.call(anchor, "ethereum"));
+    assert.equal((anchor.commit as { counter: string }).counter, "112758");
+    assert.equal((successor.commit as { counter: string }).counter, "112760");
+  });
+
+  it("resolves the successor's prevB64 to the anchor, as exported (with ethereum)", () => {
+    // The whole point: the anchor is exported WITH the ethereum field, and its
+    // chain hash must still equal the successor's prevB64.
+    assert.equal(computeChainHash(anchor as unknown as BitGraphProof), expectedPrev);
+  });
+
+  it("ignores the ethereum field entirely (with === without)", () => {
+    const withoutEth: Record<string, unknown> = { ...anchor };
+    delete withoutEth.ethereum;
+    assert.equal(
+      computeChainHash(anchor as unknown as BitGraphProof),
+      computeChainHash(withoutEth as unknown as BitGraphProof)
+    );
+  });
+
+  it("also ignores the ledger-added proofHash field (with === without)", () => {
+    const withoutHash: Record<string, unknown> = { ...anchor };
+    delete withoutHash.proofHash;
+    assert.equal(
+      computeChainHash(anchor as unknown as BitGraphProof),
+      computeChainHash(withoutHash as unknown as BitGraphProof)
+    );
+  });
+});

package/src/__tests__/declared-proof-fixture.ts

@@ -0,0 +1,65 @@
+/**
+ * The first declared recording ever made (ledger #12,010, 2026-08-18), kept
+ * as a fixture because its absence is what let two verifier bugs through that
+ * day (see dc26b5fd). A real WebAuthn assertion: origin https://bitgraph.ing,
+ * rpIdHash = SHA-256("bitgraph.ing"), flags UP|UV|BE|BS (a synced passkey).
+ * The artifact bytes are not here, so it is checked with verifyProofIntegrity.
+ * Same bytes as packages/player/src/__tests__/fixtures/declared-12010/proof.json.
+ */
+export const DECLARED_12010 = {
+  "version": "bitgraph/1",
+  "artifact": {
+    "hashAlg": "sha256",
+    "digestB64": "szEkIOHMuIaOXlqVG9uqKvaKtmnYmklfzOjEldzFP2E="
+  },
+  "commit": {
+    "nonceB64": "05pT2TUMA2mJ0iBsQPkOaKFIUa0i4Ta6wdNkqS3jef4=",
+    "counter": "12010",
+    "slotCounter": "12009",
+    "slotHashB64": "VbOoREc4tcmNwFFYmtfenUZ04LNkjP02wQN2okIi81Y=",
+    "epochId": "plJ+9/nhhVEvDE4X4rCjJI+zys0fIov3XT114+mQIpk=",
+    "prevB64": "3TzjHBZWqTMte6FE0BZ0SM7hrcRhFv29Sl4NMf/ZvBs=",
+    "chainId": "bitgraph:main"
+  },
+  "signer": {
+    "publicKeyB64": "tmp21VjPay+EhaMwmrFLfdjZo2KIjjT7VDqjmm27wHI=",
+    "signatureB64": "96dTfH4EYq1pRvS7zAhVZuiCLsfrlur0QkA4dfkRQZtbkQ8dgebEQn85TOdvvPtk2YYh9pP0k46HWrZuOOYlBg=="
+  },
+  "environment": {
+    "enforcement": "measured-tee",
+    "measurement": "6483cedffed74680ffb287507744a398b288c3fb943eb3f2e4fe889f8b60b3d575ad8942350360b69a1bd7bf713df27f",
+    "attestation": {
+      "format": "aws-nitro",
+      "reportB64": "hEShATgioFkRI79pbW9kdWxlX2lkeCdpLTA2NTAyNzM0MjNmZjY3NTY3LWVuYzAxYTAxMjJhMTNhMjliOWRmZGlnZXN0ZlNIQTM4NGl0aW1lc3RhbXAbAAABoBasgUtkcGNyc7AAWDBkg87f/tdGgP+yh1B3RKOYsojD+5Q+s/Lk/oifi2Cz1XWtiUI1A2C2mhvXv3E98n8BWDBLTVs2YbPvwSkgkAyA4Sbkzng8Ui3mwCoqW/evOiuTJ7hndvGI5L4cHEBKEp29pJMCWDAynb/jQM5eHKp3DXM2OyH3mevEVlkkmD6tdagU/IUeRoPgtSmfqkazriLTDreBBBkDWDD+UwK5y1gm9uJGWywTP7nx46KUMZGUv4pHEWPSDdx91LwKDPm88/yRbkF8pnByVT4EWDB/NnLXYAC6yWpaRfuiml8mtOMJ0c28NmxuHHZxb2qRGqxwMMGDPYSq4Peo5aubZAIFWDAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAGWDAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAHWDAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAIWDAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAJWDAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAKWDAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAALWDAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAMWDAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAANWDAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAOWDAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAPWDAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABrY2VydGlmaWNhdGVZAoAwggJ8MIICAaADAgECAhABoBIqE6KbnQAAAABqhK8tMAoGCCqGSM49BAMDMIGOMQswCQYDVQQGEwJVUzETMBEGA1UECAwKV2FzaGluZ3RvbjEQMA4GA1UEBwwHU2VhdHRsZTEPMA0GA1UECgwGQW1hem9uMQwwCgYDVQQLDANBV1MxOTA3BgNVBAMMMGktMDY1MDI3MzQyM2ZmNjc1NjcudXMtZWFzdC0yLmF3cy5uaXRyby1lbmNsYXZlczAeFw0yNjA4MTgxOTE0NTBaFw0yNjA4MTgyMjE0NTNaMIGTMQswCQYDVQQGEwJVUzETMBEGA1UECAwKV2FzaGluZ3RvbjEQMA4GA1UEBwwHU2VhdHRsZTEPMA0GA1UECgwGQW1hem9uMQwwCgYDVQQLDANBV1MxPjA8BgNVBAMMNWktMDY1MDI3MzQyM2ZmNjc1NjctZW5jMDFhMDEyMmExM2EyOWI5ZC51cy1lYXN0LTIuYXdzMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAExOq6NOiTVmOng2D3lsftqD9D8Z3BVyJKisT/kBoTg8ikZWXTK9mIliMO5mpANmZZ44ZOQdIFr8NdMO91J1XkYLT0HeXeLel1gKK/vC6p/wftvARdv/IRNuQAH6eCGZGaox0wGzAMBgNVHRMBAf8EAjAAMAsGA1UdDwQEAwIGwDAKBggqhkjOPQQDAwNpADBmAjEAvcuYYO03QWT7DFXkFCFLOf5sUFAGmzx73Xrdx4vAL+gdhHGpObgV6vpGb27VtOaRAjEA5iZjc9sFcnqNz0IJmi1+RKCpoKiG3pbRnpbmp//2wA+u6OGVy5xBCSHyoc8H9RXWaGNhYnVuZGxlhFkCFTCCAhEwggGWoAMCAQICEQD5MXVoG5Cv4R1GzLTk5/hWMAoGCCqGSM49BAMDMEkxCzAJBgNVBAYTAlVTMQ8wDQYDVQQKDAZBbWF6b24xDDAKBgNVBAsMA0FXUzEbMBkGA1UEAwwSYXdzLm5pdHJvLWVuY2xhdmVzMB4XDTE5MTAyODEzMjgwNVoXDTQ5MTAyODE0MjgwNVowSTELMAkGA1UEBhMCVVMxDzANBgNVBAoMBkFtYXpvbjEMMAoGA1UECwwDQVdTMRswGQYDVQQDDBJhd3Mubml0cm8tZW5jbGF2ZXMwdjAQBgcqhkjOPQIBBgUrgQQAIgNiAAT8AlTrpgjB82hw4prakL5GODKSc26JS//2ctmJREtQUeU0pLH22+PAvFgaMrexdgcO3hLWmj/qIRtm51LPfdHdCV9vE3D0FwhD2dwQASHkz2MBKAlmRIfJeWKEME3FP/SjQjBAMA8GA1UdEwEB/wQFMAMBAf8wHQYDVR0OBBYEFJAltQ3ZBUfnlsOW+nKdz5mp30uWMA4GA1UdDwEB/wQEAwIBhjAKBggqhkjOPQQDAwNpADBmAjEAo38vkaHJvV7nuGJ8FpjSVQOOHwND+VtjqWKMPTmAlUWhHry/LjtV2K7ucbTD1q3zAjEAovObFgWycCil3UugabUBbmW0+96P4AYdalMZf5za9dlDvGH8K+sDy2/ujSMC89/2WQLCMIICvjCCAkWgAwIBAgIRAKtsAlC6OHV9CYvTUvENcuowCgYIKoZIzj0EAwMwSTELMAkGA1UEBhMCVVMxDzANBgNVBAoMBkFtYXpvbjEMMAoGA1UECwwDQVdTMRswGQYDVQQDDBJhd3Mubml0cm8tZW5jbGF2ZXMwHhcNMjYwODE3MDE0ODA3WhcNMjYwOTA2MDI0ODA3WjBkMQswCQYDVQQGEwJVUzEPMA0GA1UECgwGQW1hem9uMQwwCgYDVQQLDANBV1MxNjA0BgNVBAMMLTQyNTI2YTFhMTRlZWI5ZDYudXMtZWFzdC0yLmF3cy5uaXRyby1lbmNsYXZlczB2MBAGByqGSM49AgEGBSuBBAAiA2IABPbYc6802oihPW8f7SrOpe6bX/VEqImWkwKuGdiCNIJw8ODlvV/g/vnbQ6iyc2D/Qso2aFsXnD0xCZKfL4gKXBgYYaIlqyw0FMzFcObLTV02DL6qoZKsRBQy57WBckcWCKOB1TCB0jASBgNVHRMBAf8ECDAGAQH/AgECMB8GA1UdIwQYMBaAFJAltQ3ZBUfnlsOW+nKdz5mp30uWMB0GA1UdDgQWBBTcEEqnhqdhAHqna/UTkRWpDZhoGjAOBgNVHQ8BAf8EBAMCAYYwbAYDVR0fBGUwYzBhoF+gXYZbaHR0cDovL2F3cy1uaXRyby1lbmNsYXZlcy1jcmwuczMuYW1hem9uYXdzLmNvbS9jcmwvYWI0OTYwY2MtN2Q2My00MmJkLTllOWYtNTkzMzhjYjY3Zjg0LmNybDAKBggqhkjOPQQDAwNnADBkAjBkm1yPVIGwMMvdEiKszwMBbivMAY2z6CKOYZucu1XvU377ZjBIPzoJUeFUaXC3HKMCMGVHmmEb5Lp4yrdECCvcjFTTb8orl3Fq/VDpQTxONuTKhjXz/RV9eTCGNsDAKKd341kDGDCCAxQwggKaoAMCAQICEBuJDj5cT8G2aNWhsnOjdNEwCgYIKoZIzj0EAwMwZDELMAkGA1UEBhMCVVMxDzANBgNVBAoMBkFtYXpvbjEMMAoGA1UECwwDQVdTMTYwNAYDVQQDDC00MjUyNmExYTE0ZWViOWQ2LnVzLWVhc3QtMi5hd3Mubml0cm8tZW5jbGF2ZXMwHhcNMjYwODE4MTEwMjA5WhcNMjYwODI0MDUwMjA5WjCBiTE8MDoGA1UEAwwzNDk2MGY5YTZkMWYxZDQ3OS56b25hbC51cy1lYXN0LTIuYXdzLm5pdHJvLWVuY2xhdmVzMQwwCgYDVQQLDANBV1MxDzANBgNVBAoMBkFtYXpvbjELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAldBMRAwDgYDVQQHDAdTZWF0dGxlMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEp5Ii0Fy/Dj72R42Umc1v26GE4a2HVU/O60BaM8vPs/Nhub4NiKvD9BRfqxcxEI3CHvEjLvYCHWsGteFWHAj8BTgo6JaAwHrAVGFvolvlfJmcbzO++0d40g4zGWmTRytVo4HqMIHnMBIGA1UdEwEB/wQIMAYBAf8CAQEwHwYDVR0jBBgwFoAU3BBKp4anYQB6p2v1E5EVqQ2YaBowHQYDVR0OBBYEFOTavrlRQIzZ1jeuQeOiXwEne9+VMA4GA1UdDwEB/wQEAwIBhjCBgAYDVR0fBHkwdzB1oHOgcYZvaHR0cDovL2NybC11cy1lYXN0LTItYXdzLW5pdHJvLWVuY2xhdmVzLnMzLnVzLWVhc3QtMi5hbWF6b25hd3MuY29tL2NybC9iMWJmZTkxYi0xMzc2LTRhOTgtYjcwNy1iMTdmYjgwN2RmNTkuY3JsMAoGCCqGSM49BAMDA2gAMGUCMCZcHgX7NUZTU9ruzZMTpr3LTVrhrqJFGv0l49i9NKW4OR/cyb5K1ik5i0dE5xASagIxALxRwuhFvuCSd7PLcbvvT553iopsomUc49zKqKx8eU8EwaHfIHxfoZMhJ6h50eEuElkCxDCCAsAwggJFoAMCAQICFQDZZTj6v+haQMmAYEs+3bFjha7AkzAKBggqhkjOPQQDAzCBiTE8MDoGA1UEAwwzNDk2MGY5YTZkMWYxZDQ3OS56b25hbC51cy1lYXN0LTIuYXdzLm5pdHJvLWVuY2xhdmVzMQwwCgYDVQQLDANBV1MxDzANBgNVBAoMBkFtYXpvbjELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAldBMRAwDgYDVQQHDAdTZWF0dGxlMB4XDTI2MDgxODE1MDg1MloXDTI2MDgxOTE1MDg1MlowgY4xCzAJBgNVBAYTAlVTMRMwEQYDVQQIDApXYXNoaW5ndG9uMRAwDgYDVQQHDAdTZWF0dGxlMQ8wDQYDVQQKDAZBbWF6b24xDDAKBgNVBAsMA0FXUzE5MDcGA1UEAwwwaS0wNjUwMjczNDIzZmY2NzU2Ny51cy1lYXN0LTIuYXdzLm5pdHJvLWVuY2xhdmVzMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEOGgwVRxvxs/kLVPc3+gCNbkCR1gXXibNxxAX3RINRZ4Lp3a1dGgyb1VdCEfSlbDwd/d2Xgcimi6Mo/d0c0MFxwnwHh0p99vBTKfb0JZk2DhtVcCS6LlpVrbs3f/oZLOco2YwZDASBgNVHRMBAf8ECDAGAQH/AgEAMA4GA1UdDwEB/wQEAwICBDAdBgNVHQ4EFgQUjcTPlUParxYbGA+mJ8bQtz8zTbMwHwYDVR0jBBgwFoAU5Nq+uVFAjNnWN65B46JfASd735UwCgYIKoZIzj0EAwMDaQAwZgIxALMlDm28+2LXsTI+vRIhxHnkiHS2Rwz+kcbbTq/8d/z00mDPAQWFa2or/5M90jsRhQIxAIlvUaKMy704VlQUXVH+vc/tkSXApqj8CoE2gKyRtHLi3JcidkykZ5wvFAqeGKIVgWpwdWJsaWNfa2V59ml1c2VyX2RhdGFYINhJ8ktMcdQVPTfz83OD2U38o0F/VIsxE4P/hR0WwtKuZW5vbmNl9v9YYFzC4t3/xAvXSMRAe4CgqOwHvm001y2bjOWlvXpELp1b6qQM3qLuK2EECbp82/x7z3RoJoWv8VgR9Ch+1K1lA80rgo7vdSPAuK59rfpvHAKPmWbuom8pSdgk7gXY2/wRmg=="
+    }
+  },
+  "slotAllocation": {
+    "version": "bitgraph/slot/1",
+    "nonceB64": "05pT2TUMA2mJ0iBsQPkOaKFIUa0i4Ta6wdNkqS3jef4=",
+    "counter": "12009",
+    "epochId": "plJ+9/nhhVEvDE4X4rCjJI+zys0fIov3XT114+mQIpk=",
+    "publicKeyB64": "tmp21VjPay+EhaMwmrFLfdjZo2KIjjT7VDqjmm27wHI=",
+    "chainId": "bitgraph:main",
+    "signatureB64": "LlqN1udFVXP9IFxsjwdF6//NMJZbm/IvBmlzDWJ7sfDAqCHD9fSH24w5AM4thFtf0YxMT/n5FedunYYwUQRgCA=="
+  },
+  "agency": {
+    "actor": {
+      "keyId": "ee0c65174625e065c18e732a226b649a138625ba49c3d7dde026957082035cde",
+      "publicKeyB64": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEVXEkwZppHxU13Ew9Ap+BQnxQcNXuMvH6KPepQe3t8t1Jh2/aEguB0Ttrzxw9WGxmB8a3AdVVv+ybchgrL8XIRg==",
+      "algorithm": "ES256",
+      "provider": "passkey"
+    },
+    "authorization": {
+      "purpose": "bitgraph/commit-authorize/v1",
+      "format": "webauthn",
+      "actorKeyId": "ee0c65174625e065c18e732a226b649a138625ba49c3d7dde026957082035cde",
+      "artifactHash": "szEkIOHMuIaOXlqVG9uqKvaKtmnYmklfzOjEldzFP2E=",
+      "challenge": "WzE2FoHLFBQhiwQCpdR8xXA0g1FfOcRCcTEG+1iOJa4=",
+      "timestamp": 1787086799013,
+      "authenticatorDataB64": "Gv0914qYXymsoynDxplniUKsvF16m3HSkeyxwvtTjnsdAAAAAA==",
+      "clientDataJSON": "{\"type\":\"webauthn.get\",\"challenge\":\"WzE2FoHLFBQhiwQCpdR8xXA0g1FfOcRCcTEG-1iOJa4\",\"origin\":\"https://bitgraph.ing\",\"crossOrigin\":false}",
+      "signatureB64": "MEUCIQDBAxBn+pAZcq9YTCVnGcoV6TX+dC1sR1R/0ufz5GSf8gIgMrlaLEPP8f4uFLfTXHT0EA+m85x1LcQNDYqf3557Ktk="
+    }
+  },
+  "proofHash": "gpbq9mzjkjy9xz7wZAsV+eLk1kwTeOtHogysF5rYS2w="
+} as const;

package/src/__tests__/fuse-roundtrip.test.ts

@@ -0,0 +1,174 @@
+// Copyright (c) Mike Argento. All rights reserved. See LICENSE.
+
+/**
+ * BitGraph Fuse: reconstruction round trips (spec 15.3). A placement enters
+ * the registry only with this test passing: original plus proof rebuilds
+ * bytes whose hash equals the artifact digest, from fixed vectors.
+ */
+
+import { describe, test } from "node:test";
+import * as assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { sha256 } from "@noble/hashes/sha256";
+import { PLACEMENTS, getPlacement, computeSlotCommitment, bytesToBase64, buildFrame, parseFrame, readFrameMarker, readFuseAttribution, fuseAttribution } from "@mikeargento/bitgraph-verify";
+import type { BitGraphProof } from "@mikeargento/bitgraph-verify";
+
+const FIX = fileURLToPath(new URL("../../src/__tests__/fuse-fixtures/", import.meta.url));
+const bytes = (name: string) => new Uint8Array(readFileSync(FIX + name));
+const proofOf = (name: string) => JSON.parse(readFileSync(FIX + name, "utf8")) as BitGraphProof;
+
+describe("registry", () => {
+  test("fixed order and ids", () => {
+    assert.deepEqual(PLACEMENTS.map((p) => p.id), ["trailer/1", "container/1", "produced/1"]);
+    assert.deepEqual(PLACEMENTS.map((p) => p.byteExact), [true, true, false]);
+    assert.equal(getPlacement("xmp/9"), undefined);
+    assert.equal(getPlacement(""), undefined);
+  });
+});
+
+describe("trailer/1", () => {
+  const p = getPlacement("trailer/1")!;
+  test("original + proof rebuilds the committed bytes", () => {
+    const proof = proofOf("trailer.proof.json");
+    const rebuilt = p.build({ original: bytes("original.txt"), commitment: computeSlotCommitment(proof.slotAllocation!) });
+    assert.deepEqual(rebuilt, bytes("fused-trailer.bin"));
+    assert.equal(bytesToBase64(sha256(rebuilt)), proof.artifact.digestB64);
+  });
+  test("locate returns the commitment and the exact original prefix", () => {
+    const proof = proofOf("trailer.proof.json");
+    const l = p.locate(bytes("fused-trailer.bin"))!;
+    assert.deepEqual(l.commitment, computeSlotCommitment(proof.slotAllocation!));
+    assert.deepEqual(l.originalBytes, bytes("original.txt"));
+    assert.equal(l.originDigest, undefined, "trailer/1 writes no origin digest");
+  });
+  test("locate refuses short input, wrong magic, non-zero reserved bytes", () => {
+    assert.equal(p.locate(new Uint8Array(47)), null);
+    const f = bytes("fused-trailer.bin");
+    const magic = f.slice(); magic[magic.length - 48] = 0x58;
+    assert.equal(p.locate(magic), null);
+    const reserved = f.slice(); reserved[reserved.length - 40] = 1;
+    assert.equal(p.locate(reserved), null);
+    assert.equal(p.locate(bytes("original.txt")), null, "an unfused file has no trailer");
+  });
+  test("build refuses a bad commitment length and a missing original", () => {
+    assert.throws(() => p.build({ commitment: new Uint8Array(32) }), /original/);
+    assert.throws(() => p.build({ original: new Uint8Array(1), commitment: new Uint8Array(31) }), /32 bytes/);
+  });
+});
+
+describe("container/1", () => {
+  const p = getPlacement("container/1")!;
+  test("original + proof rebuilds the committed archive byte for byte, twice", () => {
+    const proof = proofOf("container.proof.json");
+    const c = computeSlotCommitment(proof.slotAllocation!);
+    const a = p.build({ original: bytes("image.png"), commitment: c });
+    const b = p.build({ original: bytes("image.png"), commitment: c });
+    assert.deepEqual(a, b, "deterministic");
+    assert.deepEqual(a, bytes("fused-container.tar"));
+    assert.equal(bytesToBase64(sha256(a)), proof.artifact.digestB64);
+  });
+  test("locate returns commitment, origin digest and the original bytes", () => {
+    const proof = proofOf("container.proof.json");
+    const l = p.locate(bytes("fused-container.tar"))!;
+    assert.deepEqual(l.commitment, computeSlotCommitment(proof.slotAllocation!));
+    assert.deepEqual(l.originDigest, sha256(bytes("image.png")));
+    assert.deepEqual(l.originalBytes, bytes("image.png"));
+  });
+  test("locate refuses any deviation from the fixed layout", () => {
+    const f = bytes("fused-container.tar");
+    const mtime = f.slice(); mtime[136] = 0x31;                         // manifest header mtime
+    assert.equal(p.locate(mtime), null, "non-zero mtime");
+    const uid = f.slice(); uid[108] = 0x31;
+    assert.equal(p.locate(uid), null, "uid");
+    const truncated = f.subarray(0, f.length - 512);
+    assert.equal(p.locate(truncated), null, "missing end block");
+    const extra = new Uint8Array(f.length + 512); extra.set(f);
+    assert.equal(p.locate(extra), null, "extra trailing block");
+    // Swap entry order: rebuild with the original first is not this placement.
+    const swapped = f.slice(); swapped[0] = 0x78;                        // corrupt the manifest name
+    assert.equal(p.locate(swapped), null, "wrong entry name");
+    assert.equal(p.locate(bytes("image.png")), null, "not a tar");
+    assert.equal(p.locate(bytes("fused-trailer.bin")), null);
+  });
+  test("an archive with a wrong manifest origin does not locate", () => {
+    const proof = proofOf("container.proof.json");
+    const c = computeSlotCommitment(proof.slotAllocation!);
+    const lying = p.build({ original: bytes("image.png"), originDigest: sha256(bytes("original.txt")), commitment: c });
+    // build accepts a caller-supplied origin digest; locate returns what is written,
+    // and the verifier compares it against the marker and the original's hash.
+    const l = p.locate(lying)!;
+    assert.deepEqual(l.originDigest, sha256(bytes("original.txt")));
+    assert.notDeepEqual(l.originDigest, sha256(l.originalBytes!));
+  });
+});
+
+describe("produced/1", () => {
+  const p = getPlacement("produced/1")!;
+  test("build and locate agree, with and without an origin", () => {
+    for (const [name, proofName] of [["produced-origin.json", "produced-origin.proof.json"], ["produced-bare.json", "produced-bare.proof.json"]] as const) {
+      const proof = proofOf(proofName);
+      const l = p.locate(bytes(name))!;
+      assert.deepEqual(l.commitment, computeSlotCommitment(proof.slotAllocation!));
+      assert.equal(bytesToBase64(sha256(bytes(name))), proof.artifact.digestB64);
+    }
+    assert.equal(p.locate(bytes("original.txt")), null);
+    assert.throws(() => p.build({ original: new Uint8Array(1), commitment: new Uint8Array(32) }), /no original/);
+  });
+});
+
+describe("legacy files that carry a nonce line", () => {
+  test("a file with a 'nonce:' line and no trailer, container or payload locates nothing", () => {
+    // ~/BitGraph holds recordings whose bytes begin with a test label and a line
+    // "nonce: <hex>" (the proto pattern, minted 2026-06-27 and 2026-08-06). That
+    // line is content, not a commitment: every registered placement must miss.
+    const legacy = new TextEncoder().encode("BitGraph test subject folder-02 file-02\nnonce: e317096692576a308263bc283d66b42e\nuoJjpYb8igrEhhSlczKKTKDyw6guO2iU5iHdBRF+mPELQqBfjrO2WZYrSWyHEuKK\n");
+    for (const p of PLACEMENTS) assert.equal(p.locate(legacy), null, p.id);
+  });
+});
+
+describe("attribution and Frame", () => {
+  test("fused attribution carries placement in title and origin in message (standard base64)", () => {
+    const origin = sha256(bytes("original.txt"));
+    const a = fuseAttribution("trailer/1", origin);
+    assert.deepEqual(a, { name: "bitgraph-fuse/1", title: "trailer/1", message: bytesToBase64(origin) });
+    assert.deepEqual(fuseAttribution("produced/1"), { name: "bitgraph-fuse/1", title: "produced/1" });
+    const proof = proofOf("trailer.proof.json");
+    const m = readFuseAttribution(proof)!;
+    assert.equal(m.placement, "trailer/1");
+    assert.equal(m.placementSource, "attribution");
+    assert.equal(m.source, "attribution");
+    assert.deepEqual(m.originDigest, origin);
+    assert.equal(m.originSource, "attribution");
+    const bare = readFuseAttribution(proofOf("trailer-undeclared.proof.json"))!;
+    assert.equal(bare.originDigest, undefined);
+    assert.equal(bare.originSource, undefined);
+    assert.equal(readFuseAttribution(proofOf("recorded.proof.json")), null, "an ordinary proof has no marker");
+  });
+  test("a Frame parses regardless of outer formatting and the nested proof is untouched", () => {
+    const text = readFileSync(FIX + "trailer.bitgraph-fuse.json", "utf8");
+    const a = parseFrame(text)!;
+    const b = parseFrame(JSON.stringify(JSON.parse(text)))!;
+    assert.deepEqual(a, b);
+    assert.equal(a.manifest.placement, "trailer/1");
+    assert.deepEqual(a.proof, proofOf("trailer.proof.json"));
+    const marker = readFrameMarker(a);
+    assert.equal(marker.source, "manifest");
+    assert.equal(marker.placementSource, "manifest");
+    assert.deepEqual(marker.originDigest, sha256(bytes("original.txt")));
+    const undeclared = parseFrame({ type: "bitgraph-fuse/1", manifest: { artifact: { algorithm: "sha256", digest: "00".repeat(32) }, fusedFile: null }, proof: proofOf("trailer.proof.json") })!;
+    assert.equal(readFrameMarker(undeclared).placement, null, "a manifest may leave the placement undeclared");
+    assert.equal(parseFrame(proofOf("trailer.proof.json")), null, "a bare proof is not a Frame");
+    assert.equal(parseFrame("{not json"), null);
+    assert.equal(parseFrame({ type: "bitgraph-fuse/1", manifest: { placement: "trailer/1", artifact: { algorithm: "sha256", digest: "zz" }, fusedFile: null }, proof: {} }), null);
+  });
+  test("a Frame is never proof-shaped", () => {
+    const f = JSON.parse(readFileSync(FIX + "produced-origin.bitgraph-fuse.json", "utf8")) as Record<string, unknown>;
+    assert.equal(f.version, undefined);
+    assert.equal(f.artifact, undefined);
+    assert.equal(f.signer, undefined);
+    assert.equal(f.type, "bitgraph-fuse/1");
+    assert.ok(f.fusePayload, "Form C frames carry the parsed payload view");
+    assert.throws(() => buildFrame({ proof: proofOf("produced-origin.proof.json"), placement: "produced/1", artifactDigest: new Uint8Array(32), fusedFile: null, fusePayload: new Uint8Array([1]) }), /canonical/);
+  });
+});