@mikeargento/bitgraph-verify 1.1.2 → 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
@@ -27,4 +31,29 @@ export declare function computeProofHash(proof: BitGraphProof | Record<string, u
  * @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;AAsBD;;;;;;;;;;;;;;;;;;;GAmBG;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
@@ -134,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;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,mBAAmB,GAAsB,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAA8C;IAC7E,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,IAAI,QAAQ,GAA4B,CAAC,CAAC;IAC1C,IAAI,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChF,2EAA2E;QAC3E,kCAAkC;QAClC,QAAQ,GAAG,EAAE,CAAC;QACd,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YACjC,IAAI,CAAC,mBAAmB,CAAC,QAAQ,CAAC,GAAG,CAAC;gBAAE,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;QACjE,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.2",
+  "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
@@ -144,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)));
+}