@mikeargento/bitgraph-verify 1.1.1 → 1.2.0

package/dist/index.d.ts

@@ -8,6 +8,6 @@
 export type { BitGraphProof, BitGraphPolicy, VerificationPolicy, SignedBody, EnforcementTier, Attribution, PolicyBinding, SlotAllocation, ActorIdentity, AuthorizationPayload, WebAuthnAuthorization, AgencyEnvelope, } from "./types.js";
 export { verify, verifyProofIntegrity, resetEpochLinkState } from "./verifier.js";
 export type { VerifyResult, ProofIntegrityResult } from "./verifier.js";
-export { computeProofHash, computeChainHash } from "./proof-hash.js";
+export { computeProofHash, computeChainHash, buildSignedBody, computeSignedBodyHash } from "./proof-hash.js";
 export { canonicalize, canonicalizeToString, constantTimeEqual } from "./canonical.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH,YAAY,EACV,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,UAAU,EACV,eAAe,EACf,WAAW,EACX,aAAa,EACb,cAAc,EACd,aAAa,EACb,oBAAoB,EACpB,qBAAqB,EACrB,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,MAAM,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAClF,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAExE,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAErE,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH,YAAY,EACV,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,UAAU,EACV,eAAe,EACf,WAAW,EACX,aAAa,EACb,cAAc,EACd,aAAa,EACb,oBAAoB,EACpB,qBAAqB,EACrB,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,MAAM,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAClF,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAExE,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAE7G,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -1,5 +1,5 @@
 // Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
 export { verify, verifyProofIntegrity, resetEpochLinkState } from "./verifier.js";
-export { computeProofHash, computeChainHash } from "./proof-hash.js";
+export { computeProofHash, computeChainHash, buildSignedBody, computeSignedBodyHash } from "./proof-hash.js";
 export { canonicalize, canonicalizeToString, constantTimeEqual } from "./canonical.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAyBrF,OAAO,EAAE,MAAM,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAGlF,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAErE,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAyBrF,OAAO,EAAE,MAAM,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAGlF,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAE7G,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/proof-hash.d.ts

@@ -1,6 +1,10 @@
 import type { BitGraphProof } from "./types.js";
 /**
- * Compute the canonical hash of a BitGraph proof's signed body.
+ * Compute the ledger identity hash of a BitGraph proof.
+ *
+ * Hashes the frozen signed-body subset described at the top of this file.
+ * This is NOT the value the Ed25519 signature covers and NOT the attestation
+ * user_data; for that, reconstruct the full signed body (verifier.ts step 3).
  *
  * @param proof - The full BitGraphProof object (or equivalent Record)
  * @returns Base64-standard encoded SHA-256 hash
@@ -8,22 +12,48 @@ import type { BitGraphProof } from "./types.js";
 export declare function computeProofHash(proof: BitGraphProof | Record<string, unknown>): string;
 /**
  * Compute the CHAIN hash of a BitGraph proof: SHA-256 over the canonicalized
- * whole proof object, with the ledger-added `proofHash` field removed.
+ * whole proof object, with the ledger/service-added fields removed.
  *
  * This is the value the enclave writes into the NEXT proof's
  * `commit.prevB64` (and into `epochLink.prevProofHashB64` at an epoch
  * boundary): the enclave hashes the entire assembled proof, before the ledger
- * appends its convenience `proofHash` field. To link a chain, match a proof's
- * `commit.prevB64` against `computeChainHash(predecessor)`.
+ * or anchor service appends its convenience fields. To link a chain, match a
+ * proof's `commit.prevB64` against `computeChainHash(predecessor)`.
  *
  * This differs from computeProofHash, which hashes only the signed-body
- * subset. The chain hash covers every field (signer signature, attestation
- * report, slot allocation, attribution, and so on), so any change anywhere in
- * a proof breaks the link from its successor.
+ * subset. The chain hash covers every enclave-produced field (signer
+ * signature, attestation report, slot allocation, attribution, and so on), so
+ * any change anywhere in a proof breaks the link from its successor.
  *
- * @param proof - The full BitGraphProof object (or equivalent Record). A
- *   top-level `proofHash` field, if present, is excluded before hashing.
+ * @param proof - The full BitGraphProof object (or equivalent Record). Any
+ *   ledger/service-added field (see LEDGER_ADDED_FIELDS) is excluded before
+ *   hashing.
  * @returns Base64-standard encoded SHA-256 hash
  */
 export declare function computeChainHash(proof: BitGraphProof | Record<string, unknown>): string;
+/**
+ * Reconstruct the FULL canonical signed body: the bytes the Ed25519 signature
+ * actually covers, and the bytes whose SHA-256 the enclave places in the Nitro
+ * attestation's `user_data`.
+ *
+ * ⚠️ THIS IS HASH (2) IN THE LIST AT THE TOP OF THIS FILE, AND IT IS NOT
+ * computeProofHash. For a proof carrying neither `actor` nor `policy` the two
+ * coincide, which is why substituting one for the other survives every
+ * ordinary proof and fails only on agency or policy proofs — a bug that hides
+ * until the day the feature ships. That is exactly what happened: the offline
+ * auditor compared the attestation's user_data against computeProofHash and
+ * reported every declared recording as belonging to "some other proof",
+ * turning a valid proof into a FALSE (2026-08-18, found on the first real
+ * declaration, ledger position #12,010).
+ *
+ * Signature verification and attestation binding MUST both use this function
+ * so they cannot drift apart again.
+ */
+export declare function buildSignedBody(proof: BitGraphProof | Record<string, unknown>): Record<string, unknown>;
+/**
+ * base64(SHA-256(canonical full signed body)). The value the enclave writes
+ * into the attestation's user_data, and the digest the Ed25519 signature
+ * covers. See buildSignedBody for why this is never computeProofHash.
+ */
+export declare function computeSignedBodyHash(proof: BitGraphProof | Record<string, unknown>): string;
 //# sourceMappingURL=proof-hash.d.ts.map

package/dist/proof-hash.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"proof-hash.d.ts","sourceRoot":"","sources":["../src/proof-hash.ts"],"names":[],"mappings":"AA2CA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CA2BvF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAavF"}
+{"version":3,"file":"proof-hash.d.ts","sourceRoot":"","sources":["../src/proof-hash.ts"],"names":[],"mappings":"AAoEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CA2BvF;AAsBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAavF;AAcD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAqBvG;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAE5F"}

package/dist/proof-hash.js

@@ -4,28 +4,53 @@
  *
  * Canonical, deterministic proof hash computation.
  *
- * The proof hash covers the SIGNED BODY — the fields that are
- * cryptographically signed by the enclave. This matches what the
- * Ed25519 signature covers, making the hash verifiable.
- *
- * Signed body fields:
+ * This is the LEDGER IDENTITY of a proof. It hashes a fixed SUBSET of the
+ * signed body:
  *   - version, artifact, commit
  *   - publicKeyB64 (from signer)
  *   - enforcement, measurement (from environment)
  *   - attribution (if present)
  *   - attestationFormat (if attestation present)
  *
- * This hash (the signed-body hash) is used for:
- *   - S3 ledger key generation
+ * Used for:
+ *   - S3 ledger key generation — proofs/{epoch}/{counter}-{proofHash}.json
  *   - Ethereum anchor binding
  *   - Proof deduplication and canonical identity
  *
- * It is NOT the value referenced by commit.prevB64 or by
- * epochLink.prevProofHashB64. Those reference the CHAIN hash: SHA-256 over
- * the canonicalized WHOLE proof (every field, minus the ledger-added
- * proofHash), computed by computeChainHash below. Matching prevB64 against
- * computeProofHash instead of computeChainHash silently fails to link real
- * chains.
+ * ── THE FIELD LIST ABOVE IS FROZEN. DO NOT ADD TO IT. ──
+ *
+ * It is tempting to "fix" this function by adding `actor` and `policy`, which
+ * ARE in the signed body the enclave signs. Doing so is a silent, permanent
+ * break: this value is baked into every S3 object key already written, and
+ * ledger verify() compares a recomputed value against the stored `proofHash`
+ * field (packages/ledger/src/verify.ts). Widening the subset changes the hash
+ * of every existing agency-bearing or policy-bearing proof, orphaning its key
+ * and failing its hash check forever. The subset is a compatibility contract,
+ * not an approximation of the signature.
+ *
+ * BitGraph has THREE distinct proof hashes. Confusing them is the single
+ * easiest way to break the system, so they are spelled out here:
+ *
+ *   1. computeProofHash (this function) — signed-body SUBSET.
+ *      Ledger identity and S3 key. Frozen. Not a signature-equivalent value.
+ *
+ *   2. SHA-256 of the FULL canonical signed body — what the Ed25519 signature
+ *      actually covers, and what the enclave puts in the Nitro attestation's
+ *      user_data. Reconstructed by verifier.ts (step 3) and, in the browser,
+ *      by buildSignedBody()/proofHashB64() in website/src/lib/bitgraph.ts.
+ *      For a proof with no `actor` and no `policy` this coincides with (1);
+ *      for agency or policy proofs it does NOT. Use this for signature and
+ *      attestation checks. Never use (1).
+ *
+ *   3. computeChainHash (below) — the WHOLE proof, minus ledger-added fields.
+ *      This is what the enclave writes into the next proof's commit.prevB64
+ *      and into epochLink.prevProofHashB64. Matching prevB64 against (1)
+ *      silently fails to link real chains.
+ *
+ * packages/hosted/src/bitcoin-anchor.ts carries a deliberate inline copy of
+ * (1) because Railway cannot resolve the monorepo package. It mirrors this
+ * field list exactly and must continue to; if this list ever does change,
+ * that copy changes with it in the same commit.
  *
  * Algorithm:
  *   1. Extract signed body fields
@@ -40,7 +65,11 @@
 import { canonicalize } from "./canonical.js";
 import { sha256 } from "@noble/hashes/sha256";
 /**
- * Compute the canonical hash of a BitGraph proof's signed body.
+ * Compute the ledger identity hash of a BitGraph proof.
+ *
+ * Hashes the frozen signed-body subset described at the top of this file.
+ * This is NOT the value the Ed25519 signature covers and NOT the attestation
+ * user_data; for that, reconstruct the full signed body (verifier.ts step 3).
  *
  * @param proof - The full BitGraphProof object (or equivalent Record)
  * @returns Base64-standard encoded SHA-256 hash
@@ -69,34 +98,54 @@ export function computeProofHash(proof) {
     const hash = sha256(bytes);
     return base64(hash);
 }
+/**
+ * Fields that are NOT produced by the enclave. They are appended to a proof
+ * AFTER it is signed, by the ledger or the anchor service, purely as read-time
+ * convenience. The enclave computed its chain hash before any of these
+ * existed, so they MUST be excluded from computeChainHash — otherwise a
+ * successor's `commit.prevB64` (computed by the enclave over the clean proof)
+ * can never match.
+ *
+ *   proofHash — SHA-256 of the signed-body subset; added by the ledger at
+ *               write time (see computeProofHash above).
+ *   ethereum  — { blockNumber, blockHash }; added by the anchor service to
+ *               anchor records after the transaction is mined. Purely
+ *               redundant: the block hash is already in the signed
+ *               `attribution.message` and the block number in
+ *               `attribution.title`. Present only on Ethereum-anchor proofs.
+ *
+ * Any future ledger/service-added field must be added here as well.
+ */
+const LEDGER_ADDED_FIELDS = ["proofHash", "ethereum"];
 /**
  * Compute the CHAIN hash of a BitGraph proof: SHA-256 over the canonicalized
- * whole proof object, with the ledger-added `proofHash` field removed.
+ * whole proof object, with the ledger/service-added fields removed.
  *
  * This is the value the enclave writes into the NEXT proof's
  * `commit.prevB64` (and into `epochLink.prevProofHashB64` at an epoch
  * boundary): the enclave hashes the entire assembled proof, before the ledger
- * appends its convenience `proofHash` field. To link a chain, match a proof's
- * `commit.prevB64` against `computeChainHash(predecessor)`.
+ * or anchor service appends its convenience fields. To link a chain, match a
+ * proof's `commit.prevB64` against `computeChainHash(predecessor)`.
  *
  * This differs from computeProofHash, which hashes only the signed-body
- * subset. The chain hash covers every field (signer signature, attestation
- * report, slot allocation, attribution, and so on), so any change anywhere in
- * a proof breaks the link from its successor.
+ * subset. The chain hash covers every enclave-produced field (signer
+ * signature, attestation report, slot allocation, attribution, and so on), so
+ * any change anywhere in a proof breaks the link from its successor.
  *
- * @param proof - The full BitGraphProof object (or equivalent Record). A
- *   top-level `proofHash` field, if present, is excluded before hashing.
+ * @param proof - The full BitGraphProof object (or equivalent Record). Any
+ *   ledger/service-added field (see LEDGER_ADDED_FIELDS) is excluded before
+ *   hashing.
  * @returns Base64-standard encoded SHA-256 hash
  */
 export function computeChainHash(proof) {
     const p = proof;
     let hashable = p;
-    if (Object.prototype.hasOwnProperty.call(p, "proofHash")) {
-        // Shallow copy without the ledger-added field; the enclave hashed the
-        // proof before this field existed.
+    if (LEDGER_ADDED_FIELDS.some((k) => Object.prototype.hasOwnProperty.call(p, k))) {
+        // Shallow copy without the ledger/service-added fields; the enclave hashed
+        // the proof before these existed.
         hashable = {};
         for (const key of Object.keys(p)) {
-            if (key !== "proofHash")
+            if (!LEDGER_ADDED_FIELDS.includes(key))
                 hashable[key] = p[key];
         }
     }
@@ -114,4 +163,53 @@ function base64(hash) {
     }
     return btoa(binary);
 }
+/**
+ * Reconstruct the FULL canonical signed body: the bytes the Ed25519 signature
+ * actually covers, and the bytes whose SHA-256 the enclave places in the Nitro
+ * attestation's `user_data`.
+ *
+ * ⚠️ THIS IS HASH (2) IN THE LIST AT THE TOP OF THIS FILE, AND IT IS NOT
+ * computeProofHash. For a proof carrying neither `actor` nor `policy` the two
+ * coincide, which is why substituting one for the other survives every
+ * ordinary proof and fails only on agency or policy proofs — a bug that hides
+ * until the day the feature ships. That is exactly what happened: the offline
+ * auditor compared the attestation's user_data against computeProofHash and
+ * reported every declared recording as belonging to "some other proof",
+ * turning a valid proof into a FALSE (2026-08-18, found on the first real
+ * declaration, ledger position #12,010).
+ *
+ * Signature verification and attestation binding MUST both use this function
+ * so they cannot drift apart again.
+ */
+export function buildSignedBody(proof) {
+    const p = proof;
+    const signer = p.signer;
+    const env = p.environment;
+    const body = {
+        version: p.version,
+        artifact: p.artifact,
+        commit: p.commit,
+        publicKeyB64: signer?.publicKeyB64,
+        enforcement: env?.enforcement,
+        measurement: env?.measurement,
+    };
+    if (env?.attestation !== undefined)
+        body.attestationFormat = env.attestation.format;
+    const agency = p.agency;
+    if (agency !== undefined)
+        body.actor = agency.actor;
+    if (p.policy !== undefined)
+        body.policy = p.policy;
+    if (p.attribution !== undefined)
+        body.attribution = p.attribution;
+    return body;
+}
+/**
+ * base64(SHA-256(canonical full signed body)). The value the enclave writes
+ * into the attestation's user_data, and the digest the Ed25519 signature
+ * covers. See buildSignedBody for why this is never computeProofHash.
+ */
+export function computeSignedBodyHash(proof) {
+    return base64(sha256(canonicalize(buildSignedBody(proof))));
+}
 //# sourceMappingURL=proof-hash.js.map

package/dist/proof-hash.js.map

@@ -1 +1 @@
-{"version":3,"file":"proof-hash.js","sourceRoot":"","sources":["../src/proof-hash.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAG9C;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAA8C;IAC7E,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,MAAM,MAAM,GAAG,CAAC,CAAC,MAA8C,CAAC;IAChE,MAAM,GAAG,GAAG,CAAC,CAAC,WAAyG,CAAC;IAExH,MAAM,UAAU,GAA4B;QAC1C,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,YAAY,EAAE,MAAM,EAAE,YAAY;QAClC,WAAW,EAAE,GAAG,EAAE,WAAW;QAC7B,WAAW,EAAE,GAAG,EAAE,WAAW;KAC9B,CAAC;IAEF,iCAAiC;IACjC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;QAClB,UAAU,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC;IACzC,CAAC;IAED,wCAAwC;IACxC,IAAI,GAAG,EAAE,WAAW,EAAE,CAAC;QACrB,UAAU,CAAC,iBAAiB,GAAG,GAAG,CAAC,WAAW,CAAC,MAAM,CAAC;IACxD,CAAC;IAED,MAAM,KAAK,GAAG,YAAY,CAAC,UAAsC,CAAC,CAAC;IACnE,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC3B,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC;AACtB,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAA8C;IAC7E,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,IAAI,QAAQ,GAA4B,CAAC,CAAC;IAC1C,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,EAAE,WAAW,CAAC,EAAE,CAAC;QACzD,sEAAsE;QACtE,mCAAmC;QACnC,QAAQ,GAAG,EAAE,CAAC;QACd,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YACjC,IAAI,GAAG,KAAK,WAAW;gBAAE,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IACD,MAAM,KAAK,GAAG,YAAY,CAAC,QAAoC,CAAC,CAAC;IACjE,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AAC/B,CAAC;AAED,8DAA8D;AAC9D,SAAS,MAAM,CAAC,IAAgB;IAC9B,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QAClC,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC9C,CAAC;IACD,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,IAAI,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAE,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC;AACtB,CAAC"}
+{"version":3,"file":"proof-hash.js","sourceRoot":"","sources":["../src/proof-hash.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikeargento/bitgraph-verify",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Offline verification of BitGraph proofs. Permissionless by design.",
   "license": "MIT",
   "type": "module",

package/src/index.ts

@@ -26,6 +26,6 @@ export type {
 export { verify, verifyProofIntegrity, resetEpochLinkState } from "./verifier.js";
 export type { VerifyResult, ProofIntegrityResult } from "./verifier.js";
 
-export { computeProofHash, computeChainHash } from "./proof-hash.js";
+export { computeProofHash, computeChainHash, buildSignedBody, computeSignedBodyHash } from "./proof-hash.js";
 
 export { canonicalize, canonicalizeToString, constantTimeEqual } from "./canonical.js";

package/src/proof-hash.ts

@@ -5,28 +5,53 @@
  *
  * Canonical, deterministic proof hash computation.
  *
- * The proof hash covers the SIGNED BODY — the fields that are
- * cryptographically signed by the enclave. This matches what the
- * Ed25519 signature covers, making the hash verifiable.
- *
- * Signed body fields:
+ * This is the LEDGER IDENTITY of a proof. It hashes a fixed SUBSET of the
+ * signed body:
  *   - version, artifact, commit
  *   - publicKeyB64 (from signer)
  *   - enforcement, measurement (from environment)
  *   - attribution (if present)
  *   - attestationFormat (if attestation present)
  *
- * This hash (the signed-body hash) is used for:
- *   - S3 ledger key generation
+ * Used for:
+ *   - S3 ledger key generation — proofs/{epoch}/{counter}-{proofHash}.json
  *   - Ethereum anchor binding
  *   - Proof deduplication and canonical identity
  *
- * It is NOT the value referenced by commit.prevB64 or by
- * epochLink.prevProofHashB64. Those reference the CHAIN hash: SHA-256 over
- * the canonicalized WHOLE proof (every field, minus the ledger-added
- * proofHash), computed by computeChainHash below. Matching prevB64 against
- * computeProofHash instead of computeChainHash silently fails to link real
- * chains.
+ * ── THE FIELD LIST ABOVE IS FROZEN. DO NOT ADD TO IT. ──
+ *
+ * It is tempting to "fix" this function by adding `actor` and `policy`, which
+ * ARE in the signed body the enclave signs. Doing so is a silent, permanent
+ * break: this value is baked into every S3 object key already written, and
+ * ledger verify() compares a recomputed value against the stored `proofHash`
+ * field (packages/ledger/src/verify.ts). Widening the subset changes the hash
+ * of every existing agency-bearing or policy-bearing proof, orphaning its key
+ * and failing its hash check forever. The subset is a compatibility contract,
+ * not an approximation of the signature.
+ *
+ * BitGraph has THREE distinct proof hashes. Confusing them is the single
+ * easiest way to break the system, so they are spelled out here:
+ *
+ *   1. computeProofHash (this function) — signed-body SUBSET.
+ *      Ledger identity and S3 key. Frozen. Not a signature-equivalent value.
+ *
+ *   2. SHA-256 of the FULL canonical signed body — what the Ed25519 signature
+ *      actually covers, and what the enclave puts in the Nitro attestation's
+ *      user_data. Reconstructed by verifier.ts (step 3) and, in the browser,
+ *      by buildSignedBody()/proofHashB64() in website/src/lib/bitgraph.ts.
+ *      For a proof with no `actor` and no `policy` this coincides with (1);
+ *      for agency or policy proofs it does NOT. Use this for signature and
+ *      attestation checks. Never use (1).
+ *
+ *   3. computeChainHash (below) — the WHOLE proof, minus ledger-added fields.
+ *      This is what the enclave writes into the next proof's commit.prevB64
+ *      and into epochLink.prevProofHashB64. Matching prevB64 against (1)
+ *      silently fails to link real chains.
+ *
+ * packages/hosted/src/bitcoin-anchor.ts carries a deliberate inline copy of
+ * (1) because Railway cannot resolve the monorepo package. It mirrors this
+ * field list exactly and must continue to; if this list ever does change,
+ * that copy changes with it in the same commit.
  *
  * Algorithm:
  *   1. Extract signed body fields
@@ -44,7 +69,11 @@ import { sha256 } from "@noble/hashes/sha256";
 import type { BitGraphProof } from "./types.js";
 
 /**
- * Compute the canonical hash of a BitGraph proof's signed body.
+ * Compute the ledger identity hash of a BitGraph proof.
+ *
+ * Hashes the frozen signed-body subset described at the top of this file.
+ * This is NOT the value the Ed25519 signature covers and NOT the attestation
+ * user_data; for that, reconstruct the full signed body (verifier.ts step 3).
  *
  * @param proof - The full BitGraphProof object (or equivalent Record)
  * @returns Base64-standard encoded SHA-256 hash
@@ -78,34 +107,55 @@ export function computeProofHash(proof: BitGraphProof | Record<string, unknown>)
   return base64(hash);
 }
 
+/**
+ * Fields that are NOT produced by the enclave. They are appended to a proof
+ * AFTER it is signed, by the ledger or the anchor service, purely as read-time
+ * convenience. The enclave computed its chain hash before any of these
+ * existed, so they MUST be excluded from computeChainHash — otherwise a
+ * successor's `commit.prevB64` (computed by the enclave over the clean proof)
+ * can never match.
+ *
+ *   proofHash — SHA-256 of the signed-body subset; added by the ledger at
+ *               write time (see computeProofHash above).
+ *   ethereum  — { blockNumber, blockHash }; added by the anchor service to
+ *               anchor records after the transaction is mined. Purely
+ *               redundant: the block hash is already in the signed
+ *               `attribution.message` and the block number in
+ *               `attribution.title`. Present only on Ethereum-anchor proofs.
+ *
+ * Any future ledger/service-added field must be added here as well.
+ */
+const LEDGER_ADDED_FIELDS: readonly string[] = ["proofHash", "ethereum"];
+
 /**
  * Compute the CHAIN hash of a BitGraph proof: SHA-256 over the canonicalized
- * whole proof object, with the ledger-added `proofHash` field removed.
+ * whole proof object, with the ledger/service-added fields removed.
  *
  * This is the value the enclave writes into the NEXT proof's
  * `commit.prevB64` (and into `epochLink.prevProofHashB64` at an epoch
  * boundary): the enclave hashes the entire assembled proof, before the ledger
- * appends its convenience `proofHash` field. To link a chain, match a proof's
- * `commit.prevB64` against `computeChainHash(predecessor)`.
+ * or anchor service appends its convenience fields. To link a chain, match a
+ * proof's `commit.prevB64` against `computeChainHash(predecessor)`.
  *
  * This differs from computeProofHash, which hashes only the signed-body
- * subset. The chain hash covers every field (signer signature, attestation
- * report, slot allocation, attribution, and so on), so any change anywhere in
- * a proof breaks the link from its successor.
+ * subset. The chain hash covers every enclave-produced field (signer
+ * signature, attestation report, slot allocation, attribution, and so on), so
+ * any change anywhere in a proof breaks the link from its successor.
  *
- * @param proof - The full BitGraphProof object (or equivalent Record). A
- *   top-level `proofHash` field, if present, is excluded before hashing.
+ * @param proof - The full BitGraphProof object (or equivalent Record). Any
+ *   ledger/service-added field (see LEDGER_ADDED_FIELDS) is excluded before
+ *   hashing.
  * @returns Base64-standard encoded SHA-256 hash
  */
 export function computeChainHash(proof: BitGraphProof | Record<string, unknown>): string {
   const p = proof as Record<string, unknown>;
   let hashable: Record<string, unknown> = p;
-  if (Object.prototype.hasOwnProperty.call(p, "proofHash")) {
-    // Shallow copy without the ledger-added field; the enclave hashed the
-    // proof before this field existed.
+  if (LEDGER_ADDED_FIELDS.some((k) => Object.prototype.hasOwnProperty.call(p, k))) {
+    // Shallow copy without the ledger/service-added fields; the enclave hashed
+    // the proof before these existed.
     hashable = {};
     for (const key of Object.keys(p)) {
-      if (key !== "proofHash") hashable[key] = p[key];
+      if (!LEDGER_ADDED_FIELDS.includes(key)) hashable[key] = p[key];
     }
   }
   const bytes = canonicalize(hashable as unknown as BitGraphProof);
@@ -123,3 +173,53 @@ function base64(hash: Uint8Array): string {
   }
   return btoa(binary);
 }
+
+/**
+ * Reconstruct the FULL canonical signed body: the bytes the Ed25519 signature
+ * actually covers, and the bytes whose SHA-256 the enclave places in the Nitro
+ * attestation's `user_data`.
+ *
+ * ⚠️ THIS IS HASH (2) IN THE LIST AT THE TOP OF THIS FILE, AND IT IS NOT
+ * computeProofHash. For a proof carrying neither `actor` nor `policy` the two
+ * coincide, which is why substituting one for the other survives every
+ * ordinary proof and fails only on agency or policy proofs — a bug that hides
+ * until the day the feature ships. That is exactly what happened: the offline
+ * auditor compared the attestation's user_data against computeProofHash and
+ * reported every declared recording as belonging to "some other proof",
+ * turning a valid proof into a FALSE (2026-08-18, found on the first real
+ * declaration, ledger position #12,010).
+ *
+ * Signature verification and attestation binding MUST both use this function
+ * so they cannot drift apart again.
+ */
+export function buildSignedBody(proof: BitGraphProof | Record<string, unknown>): Record<string, unknown> {
+  const p = proof as Record<string, unknown>;
+  const signer = p.signer as { publicKeyB64?: string } | undefined;
+  const env = p.environment as
+    | { enforcement?: string; measurement?: string; attestation?: { format?: string } }
+    | undefined;
+
+  const body: Record<string, unknown> = {
+    version: p.version,
+    artifact: p.artifact,
+    commit: p.commit,
+    publicKeyB64: signer?.publicKeyB64,
+    enforcement: env?.enforcement,
+    measurement: env?.measurement,
+  };
+  if (env?.attestation !== undefined) body.attestationFormat = env.attestation.format;
+  const agency = p.agency as { actor?: unknown } | undefined;
+  if (agency !== undefined) body.actor = agency.actor;
+  if (p.policy !== undefined) body.policy = p.policy;
+  if (p.attribution !== undefined) body.attribution = p.attribution;
+  return body;
+}
+
+/**
+ * base64(SHA-256(canonical full signed body)). The value the enclave writes
+ * into the attestation's user_data, and the digest the Ed25519 signature
+ * covers. See buildSignedBody for why this is never computeProofHash.
+ */
+export function computeSignedBodyHash(proof: BitGraphProof | Record<string, unknown>): string {
+  return base64(sha256(canonicalize(buildSignedBody(proof) as unknown as BitGraphProof)));
+}