fix(ipfs): verify CIDs by recomputing them, not by comparing content

[maztah1]

What the issue was

#848 asked for IPFS invoice metadata pinning with CID verification, listing verifyCID(cid, content) as a requirement and "CID verification detects tampering" as an acceptance criterion.

The pinning, gateway/kubo backends and enrichInvoice were already implemented. The verification was not sound, though — and I want to be direct that this is a correctness/security fix rather than a new feature.

The bug

verifyCID() did this:

const fetchedContent = await fetchFromIPFS(cid, config);
const expectedContent = typeof content === "string" ? content : JSON.stringify(content);
return sha256(fetchedContent) === sha256(expectedContent);

It compared content against content. The CID was never validated — it was only used as a fetch key. So verifyCID("THIS-IS-NOT-A-REAL-CID", <anything the gateway returns>) returns true. The old docstring admitted the limitation: "Since we can't recompute the exact CID without the multihash library…" — but the function was still exported as the tamper check, and verifyCIDOrThrow delegated to it.

Three existing tests asserted verifyCID returned true for invented CIDs like "QmVerifyCid123456789012345678901234567890", which were never hashes of the test content. They passed because verification was broken. That is what convinced me this mattered: the test suite was pinning the bug in place.

The fix

A CID embeds the multihash of the content it names, so verification means recomputing it and comparing:

• CIDv0 (Qm…, base58btc) and CIDv1 (bafy…, base32 dag-pb) computation over a sha2-256 multihash. Both encoders implemented directly rather than pulling in a dependency — multiformats is present only transitively via WalletConnect, and depending on that would be fragile.
• Recompute in the same CID version as the one supplied. A v0 and v1 CID name identical bytes, so cross-version comparison would always fail.
• When content is supplied the check is now purely local, no network round-trip, and genuinely proves the bytes hash to the claimed address.
• verifyCID(cid) with content omitted verifies whatever the CID resolves to — that is what detects a gateway serving tampered bytes under an otherwise-valid CID.
• ipfs:// URI and /ipfs/ path forms are tolerated.
• Added verifyCIDDetailed() returning a CIDVerificationResult; verifyCIDOrThrow now reports the CID the content actually produced, so a mismatch tells you whether the address or the bytes are wrong.

I verified the encoders against an independently computed sha2-256 multihash vector before wiring them in — the CIDv0 output matched a from-scratch base58 implementation.

How it was tested

63 tests in test/ipfs.test.ts, up from 54. The three fake-CID tests are replaced with CIDs computed from the content via computeCidV0. New coverage:

• a fabricated CID rejecting content that round-trips through the gateway (the regression this PR fixes)
• CIDv1 addresses, and v0/v1 correctly not matching each other
• ipfs:// URI form
• verification of fetched bytes when content is omitted — tamper detection
• verifyCIDDetailed returning the computed CID, and reporting fetch errors as valid: false rather than throwing

Full suite: 213 passed, 1 skipped, 0 failed. tsc --noEmit diffed against base — no new errors.

Behaviour change to be aware of

verifyCID and verifyCIDOrThrow now return false for CIDs that were never real hashes of the content. That is the point of the fix, but it will surface callers who were relying on the loose check. content is now optional on both.

closes #848

[drips-wave]

@maztah1 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits