Compute a Nostr Event ID, an IPFS CID, and a Blossom Hash for the Same Bytes

mkdir -p ~/nostr-ipfs/src ~/nostr-ipfs/tests
cd ~/nostr-ipfs
touch .gitignore

cd ~/nostr-ipfs
echo "3.11" > .python-version
touch pyproject.toml

[project]
name = "nostr-ipfs-addressing"
version = "0.1.0"
description = "Compute Nostr event ids, IPFS CIDs, and Blossom hashes side by side"
readme = "README.md"
requires-python = ">=3.11"
dependencies = []

[dependency-groups]
dev = [
    "multiformats>=0.3.1",
    "pytest>=8.3.0",
]

cd ~/nostr-ipfs
touch src/addressing.py

"""Three ways to name the same bytes: Nostr, IPFS, and Blossom.

A decentralized application usually needs two different kinds of identifier, and
conflating them is where the confusion starts:

* **Who said what, and when** — a Nostr event id. It names a *signed statement*.
  Change one character of the note and it is a different event by a different id,
  even though the photo it links to is untouched.
* **What these bytes are** — an IPFS CID or a Blossom hash. It names *content*.
  The same photo has the same identifier no matter who posts it, how many times,
  or which server happens to be holding a copy.

This module computes all three from first principles, with no network and no
dependencies outside the standard library. That is the point: a CIDv1 for a raw
block is a SHA-256 digest with four bytes of self-describing prefix in front of
it, and seeing that spelled out is worth more than calling a library.
"""

from __future__ import annotations

import base64
import hashlib
import json
from dataclasses import dataclass

# Multiformats table entries used here. Each is a varint in the spec; every value
# below happens to be a single byte, so the encoder stays readable.
MULTIBASE_BASE32 = "b"  # base32, RFC 4648 lowercase, no padding
CID_V1 = 0x01
CODEC_RAW = 0x55  # an opaque block of bytes
CODEC_DAG_PB = 0x70  # a UnixFS node (CIDv1 form; `ipfs add` defaults to CIDv0)
HASH_SHA2_256 = 0x12
SHA2_256_LENGTH = 0x20  # 32 bytes

CODEC_NAMES = {CODEC_RAW: "raw", CODEC_DAG_PB: "dag-pb"}
HASH_NAMES = {HASH_SHA2_256: "sha2-256"}


# --------------------------------------------------------------------------
# IPFS: content addressing
# --------------------------------------------------------------------------


def multihash_sha256(data: bytes) -> bytes:
    """Wrap a SHA-256 digest as a multihash: <algorithm><length><digest>.

    The prefix is what makes the hash self-describing — a reader can tell it is
    SHA-256 and 32 bytes long without being told out of band.
    """
    return bytes([HASH_SHA2_256, SHA2_256_LENGTH]) + hashlib.sha256(data).digest()


def encode_cid_v1(multihash: bytes, codec: int) -> str:
    """Encode a CIDv1 as a base32 string.

    Layout: ``<multibase><version><codec><multihash>``, where everything after
    the multibase character is binary and base32-encoded together.
    """
    binary = bytes([CID_V1, codec]) + multihash
    encoded = base64.b32encode(binary).decode("ascii").lower().rstrip("=")
    return MULTIBASE_BASE32 + encoded


def cid_v1_raw(data: bytes) -> str:
    """Return the CIDv1 of ``data`` addressed as a raw block.

    This is the identifier for the bytes themselves. `ipfs add --raw-leaves`
    produces this form for a small file; the resulting CID starts `bafkrei`.
    """
    return encode_cid_v1(multihash_sha256(data), CODEC_RAW)


@dataclass(frozen=True)
class DecodedCid:
    version: int
    codec: int
    codec_name: str
    hash_name: str
    digest: str

    @property
    def is_raw_block(self) -> bool:
        return self.codec == CODEC_RAW


def decode_cid(cid: str) -> DecodedCid:
    """Take a base32 CIDv1 apart again.

    Decoding matters more than encoding for understanding the format: it shows
    that every field the reader needs travels inside the identifier, which is
    exactly what "self-describing" means and exactly what a bare hex hash lacks.
    """
    if not cid.startswith(MULTIBASE_BASE32):
        raise ValueError(f"expected a base32 CID beginning {MULTIBASE_BASE32!r}")
    body = cid[1:].upper()
    padding = "=" * (-len(body) % 8)
    try:
        binary = base64.b32decode(body + padding)
    except Exception as exc:  # noqa: BLE001 - surfaced as a clear ValueError
        raise ValueError(f"not valid base32: {exc}") from exc

    if len(binary) < 4:
        raise ValueError("CID is too short to contain a version, codec, and hash")
    version, codec, hash_id, length = binary[0], binary[1], binary[2], binary[3]
    if version != CID_V1:
        raise ValueError(f"only CIDv1 is supported here, got version {version}")
    digest = binary[4:]
    if len(digest) != length:
        raise ValueError(f"multihash claims {length} bytes, found {len(digest)}")
    return DecodedCid(
        version=version,
        codec=codec,
        codec_name=CODEC_NAMES.get(codec, f"0x{codec:02x}"),
        hash_name=HASH_NAMES.get(hash_id, f"0x{hash_id:02x}"),
        digest=digest.hex(),
    )


# --------------------------------------------------------------------------
# Blossom: bare SHA-256 content addressing over HTTP
# --------------------------------------------------------------------------


def blossom_hash(data: bytes) -> str:
    """Return the identifier Blossom uses for a blob: a bare SHA-256 hex digest.

    Blossom is content-addressed like IPFS, and deliberately less than IPFS: the
    same bytes always get the same name, but the name carries no codec, no hash
    algorithm, and no version, because a Blossom server only ever speaks SHA-256
    over HTTP. Compare the digest here with `decode_cid(...).digest` — they are
    the same 32 bytes wearing different clothes.
    """
    return hashlib.sha256(data).hexdigest()


# --------------------------------------------------------------------------
# Nostr: event addressing
# --------------------------------------------------------------------------


def imeta_tag(url: str, mime: str | None = None, sha256: str | None = None,
              dim: str | None = None, alt: str | None = None,
              fallbacks: tuple[str, ...] = ()) -> list[str]:
    """Build a NIP-92 ``imeta`` tag.

    The shape is the part people get wrong. NIP-92 says the tag is *variadic and
    each entry is a space-delimited key/value pair*, so it is::

        ["imeta", "url https://…", "m image/jpeg"]

    and **not**::

        ["imeta", "url", "https://…"]

    Both are legal JSON and only the first is a valid imeta tag.

    Two rules from the spec are enforced here because both are easy to miss:
    a tag MUST carry a ``url`` *and at least one other field*, and the URL is
    expected to also appear in the event's ``content`` — the tag annotates a
    link, it does not replace one. See ``build_note``.
    """
    if not url:
        raise ValueError("an imeta tag needs a url")
    entries = [f"url {url}"]
    if mime:
        entries.append(f"m {mime}")
    if sha256:
        entries.append(f"x {sha256}")
    if dim:
        entries.append(f"dim {dim}")
    if alt:
        entries.append(f"alt {alt}")
    entries.extend(f"fallback {u}" for u in fallbacks)
    if len(entries) < 2:
        raise ValueError(
            "NIP-92 requires a url and at least one other field; got url alone"
        )
    return ["imeta", *entries]


def parse_imeta(tag: list[str]) -> dict[str, list[str]]:
    """Parse an ``imeta`` tag back into keys and values.

    Returns lists because NIP-92 allows a key to repeat — `fallback` is the
    common case, and a parser that keeps only the last one silently drops the
    redundancy that makes fallbacks worth having.
    """
    if not tag or tag[0] != "imeta":
        raise ValueError("not an imeta tag")
    out: dict[str, list[str]] = {}
    for entry in tag[1:]:
        key, _, value = entry.partition(" ")
        if not value:
            raise ValueError(
                f"malformed imeta entry {entry!r}: expected 'key value' in one element"
            )
        out.setdefault(key, []).append(value)
    return out


def event_id(event: dict) -> str:
    """Compute a NIP-01 event id: SHA-256 of a canonical serialization.

    The serialization is a six-element array with no whitespace and no ASCII
    escaping. Both `separators` and `ensure_ascii` are load-bearing; either
    default produces a different hash and every signature is then rejected.
    """
    serialized = json.dumps(
        [
            0,
            event["pubkey"],
            event["created_at"],
            event["kind"],
            event["tags"],
            event["content"],
        ],
        separators=(",", ":"),
        ensure_ascii=False,
    )
    return hashlib.sha256(serialized.encode("utf-8")).hexdigest()


def build_note(content: str, pubkey: str, created_at: int, url: str,
               data: bytes, mime: str) -> dict:
    """Assemble a kind-1 note that references content instead of embedding it.

    This is the whole architecture in one function. The note carries the words
    and the author; the bytes live somewhere addressable, and the event points
    at them. Nothing here uploads anything — that is the other half of the
    system, and keeping it separate is the design, not an omission.

    Note where the URL goes. NIP-92 attaches media by putting the URL **in the
    content**, with a matching ``imeta`` tag carrying the metadata about it.
    Clients may ignore an ``imeta`` tag that matches no URL in the content, so
    a note that carries the link only in the tag is the shape that fails to
    render — the opposite of the intuition that the tag is the carrier.
    """
    body = f"{content} {url}"
    event = {
        "pubkey": pubkey,
        "created_at": created_at,
        "kind": 1,
        "tags": [imeta_tag(url, mime=mime, sha256=blossom_hash(data))],
        "content": body,
    }
    event["id"] = event_id(event)
    return event

cd ~/nostr-ipfs
touch src/demo.py

"""Print the three identifiers for one file, side by side.

Usage:
    uv run python src/demo.py [path]

With no path it uses a built-in sample so the output is reproducible.
"""

from __future__ import annotations

import sys
from pathlib import Path

from addressing import (
    blossom_hash,
    build_note,
    cid_v1_raw,
    decode_cid,
    parse_imeta,
)

SAMPLE = b"hello world\n"
PUBKEY = "7e7e9c42a91bfef19fa929e5fda1b72e0ebc1a4c1141673e2794234d86addf4e"
CREATED_AT = 1_700_000_000  # fixed so the event id is reproducible


def main(argv: list[str] | None = None) -> int:
    args = sys.argv[1:] if argv is None else argv
    if args:
        data = Path(args[0]).read_bytes()
        source = args[0]
    else:
        data = SAMPLE
        source = "built-in sample (hello world\\n)"

    cid = cid_v1_raw(data)
    decoded = decode_cid(cid)
    note = build_note(
        "Check out this photo of my new house",
        PUBKEY,
        CREATED_AT,
        f"ipfs://{cid}",
        data,
        "image/jpeg",
    )

    print(f"source            {source}  ({len(data)} bytes)\n")
    print("WHAT THESE BYTES ARE — content addressing")
    print(f"  IPFS CIDv1      {cid}")
    print(f"    version       {decoded.version}")
    print(f"    codec         {decoded.codec_name}")
    print(f"    hash          {decoded.hash_name}")
    print(f"    digest        {decoded.digest}")
    print(f"  Blossom hash    {blossom_hash(data)}")
    print("    ^ the same 32 bytes; Blossom just does not wrap them\n")
    print("WHO SAID WHAT — event addressing")
    print(f"  Nostr event id  {note['id']}")
    print(f"  kind            {note['kind']}")
    print(f"  imeta url       {parse_imeta(note['tags'][0])['url'][0]}")
    print(f"  imeta x         {parse_imeta(note['tags'][0])['x'][0]}")
    print("\n  The event id changes if the words change; the CID does not.")
    print("  The CID changes if the bytes change; the event id does not.")
    return 0


if __name__ == "__main__":
    # No sys.path juggling: running this as a script already puts src/ first on
    # sys.path, which is what makes the `from addressing import …` above work.
    raise SystemExit(main())

cd ~/nostr-ipfs
touch tests/test_addressing.py

"""Tests for the three addressing schemes.

No network. The IPFS side is checked against the `multiformats` library, which
is a dev dependency and deliberately not a runtime one: `addressing.py` is
stdlib-only so a reader can see what a CID is made of, and the library exists
here purely to prove that hand-rolled encoder agrees with a real implementation.
"""

from __future__ import annotations

import hashlib
import sys
from pathlib import Path

import pytest

sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))

from addressing import (  # noqa: E402
    CODEC_DAG_PB,
    CODEC_RAW,
    blossom_hash,
    build_note,
    cid_v1_raw,
    decode_cid,
    encode_cid_v1,
    event_id,
    imeta_tag,
    multihash_sha256,
    parse_imeta,
)

# `hello world\n` — its SHA-256 is one of the most widely reproduced digests
# there is, which makes it a good anchor for the whole chain.
SAMPLE = b"hello world\n"
SAMPLE_SHA256 = "a948904f2f0f479b8f8197694b30184b0d2ed1c1cd2a1ec0fb85d299a192a447"
SAMPLE_CID_RAW = "bafkreifjjcie6lypi6ny7amxnfftagclbuxndqonfipmb64f2km2devei4"

PUBKEY = "7e7e9c42a91bfef19fa929e5fda1b72e0ebc1a4c1141673e2794234d86addf4e"


class TestContentAddressing:
    def test_sha256_anchor(self):
        assert hashlib.sha256(SAMPLE).hexdigest() == SAMPLE_SHA256

    def test_cid_matches_a_known_value(self):
        assert cid_v1_raw(SAMPLE) == SAMPLE_CID_RAW

    def test_cid_agrees_with_the_multiformats_library(self):
        """Cross-check the hand-rolled encoder against a real implementation.

        Without this the CID tests would only prove the encoder agrees with
        itself, which is the same circularity a bech32 vector guards against.
        """
        from multiformats import CID, multihash

        expected = CID(
            "base32", 1, "raw", multihash.wrap(hashlib.sha256(SAMPLE).digest(), "sha2-256")
        )
        assert cid_v1_raw(SAMPLE) == str(expected)

    def test_codec_changes_the_prefix_not_the_digest(self):
        """`bafkrei…` vs `bafybei…` is the codec, not a different hash.

        This is the distinction behind most "why doesn't my CID match" questions:
        `ipfs add` wraps a file in a UnixFS node, so its CID names that node
        rather than the bytes. (By default it also emits CIDv0 — a base58
        `Qm…` — so the printed string differs in version and base as well.)
        """
        mh = multihash_sha256(SAMPLE)
        raw = encode_cid_v1(mh, CODEC_RAW)
        dag_pb = encode_cid_v1(mh, CODEC_DAG_PB)
        assert raw.startswith("bafkrei")
        assert dag_pb.startswith("bafybei")
        assert raw != dag_pb
        assert decode_cid(raw).digest == decode_cid(dag_pb).digest

    def test_cid_round_trips(self):
        decoded = decode_cid(cid_v1_raw(SAMPLE))
        assert decoded.version == 1
        assert decoded.codec_name == "raw"
        assert decoded.hash_name == "sha2-256"
        assert decoded.digest == SAMPLE_SHA256
        assert decoded.is_raw_block

    def test_the_cid_and_the_blossom_hash_are_the_same_bytes(self):
        """The headline comparison: one identifier is self-describing, one is not."""
        assert decode_cid(cid_v1_raw(SAMPLE)).digest == blossom_hash(SAMPLE)

    def test_different_bytes_give_a_different_cid(self):
        assert cid_v1_raw(SAMPLE) != cid_v1_raw(SAMPLE + b" ")

    @pytest.mark.parametrize("bad", ["", "zzz", "bnotbase32!!", "b"])
    def test_rejects_malformed_cids(self, bad):
        with pytest.raises(ValueError):
            decode_cid(bad)

    def test_rejects_a_truncated_multihash(self):
        mh = multihash_sha256(SAMPLE)[:-4]  # claims 32 bytes, carries 28
        with pytest.raises(ValueError, match="claims 32 bytes"):
            decode_cid(encode_cid_v1(mh, CODEC_RAW))


class TestImetaTag:
    def test_pairs_are_space_delimited_inside_one_element(self):
        """Guards the single most common way to write this tag wrongly."""
        tag = imeta_tag("ipfs://bafkrei…", mime="image/jpeg")
        assert tag == ["imeta", "url ipfs://bafkrei…", "m image/jpeg"]
        # The shape that looks right and is not:
        assert tag != ["imeta", "url", "ipfs://bafkrei…", "m", "image/jpeg"]

    def test_round_trips(self):
        tag = imeta_tag(
            "https://example.test/a.jpg",
            mime="image/jpeg",
            sha256=SAMPLE_SHA256,
            dim="3024x4032",
            alt="a photo",
        )
        parsed = parse_imeta(tag)
        assert parsed["url"] == ["https://example.test/a.jpg"]
        assert parsed["m"] == ["image/jpeg"]
        assert parsed["x"] == [SAMPLE_SHA256]
        assert parsed["dim"] == ["3024x4032"]
        assert parsed["alt"] == ["a photo"]

    def test_keeps_repeated_keys(self):
        tag = imeta_tag("https://a.test/x", fallbacks=("https://b.test/x", "https://c.test/x"))
        assert parse_imeta(tag)["fallback"] == ["https://b.test/x", "https://c.test/x"]

    def test_rejects_the_split_element_shape(self):
        with pytest.raises(ValueError, match="expected 'key value'"):
            parse_imeta(["imeta", "url", "https://example.test/a.jpg"])

    def test_requires_a_url(self):
        with pytest.raises(ValueError, match="needs a url"):
            imeta_tag("")

    def test_requires_at_least_one_field_besides_url(self):
        """NIP-92: a tag MUST have a url *and at least one other field*."""
        with pytest.raises(ValueError, match="at least one other field"):
            imeta_tag("https://example.test/a.jpg")

    def test_rejects_a_non_imeta_tag(self):
        with pytest.raises(ValueError, match="not an imeta tag"):
            parse_imeta(["e", "abc"])


class TestEventId:
    def test_is_stable_and_content_sensitive(self):
        base = {"pubkey": PUBKEY, "created_at": 1_700_000_000, "kind": 1,
                "tags": [], "content": "hello"}
        assert event_id(base) == event_id(dict(base))
        assert event_id(base) != event_id({**base, "content": "hello "})

    def test_the_referenced_media_participates_in_the_id(self):
        """Swapping the linked CID changes the event id but not the bytes.

        This is the separation the article is about: the event names a
        statement, the CID names content, and they move independently.
        """
        common = dict(pubkey=PUBKEY, created_at=1_700_000_000,
                      content="look at this", mime="image/jpeg")
        a = build_note(url="ipfs://" + cid_v1_raw(SAMPLE), data=SAMPLE, **common)
        b = build_note(url="ipfs://" + cid_v1_raw(b"other"), data=SAMPLE, **common)
        assert a["id"] != b["id"]

    def test_the_same_content_keeps_its_cid_across_different_notes(self):
        """The other half: two authors posting the same photo agree on the CID."""
        cid = cid_v1_raw(SAMPLE)
        first = build_note("mine", PUBKEY, 1_700_000_000, "ipfs://" + cid, SAMPLE, "image/jpeg")
        second = build_note("reposted", "f" * 64, 1_700_000_999, "ipfs://" + cid, SAMPLE, "image/jpeg")
        assert first["id"] != second["id"]
        assert parse_imeta(first["tags"][0])["url"] == parse_imeta(second["tags"][0])["url"]
        assert parse_imeta(first["tags"][0])["x"] == parse_imeta(second["tags"][0])["x"]


class TestBuildNote:
    def test_the_url_appears_in_the_content(self):
        """NIP-92 attaches media by putting the URL in the content.

        The `imeta` tag annotates a URL that is already there; clients may
        ignore a tag matching no URL in the content. A note carrying the link
        only in the tag is therefore the shape that fails to render, which is
        the opposite of the intuition that the tag is the carrier.
        """
        url = "ipfs://" + cid_v1_raw(SAMPLE)
        note = build_note("look at this", PUBKEY, 1_700_000_000, url, SAMPLE, "image/jpeg")
        assert url in note["content"]
        assert parse_imeta(note["tags"][0])["url"] == [url]

    def test_produces_a_well_formed_kind_1_event(self):
        note = build_note("hi", PUBKEY, 1_700_000_000,
                          "ipfs://" + cid_v1_raw(SAMPLE), SAMPLE, "image/png")
        assert note["kind"] == 1
        assert len(note["id"]) == 64
        assert note["id"] == event_id(note)
        assert parse_imeta(note["tags"][0])["x"] == [blossom_hash(SAMPLE)]

cd ~/nostr-ipfs
touch Makefile

.DEFAULT_GOAL := help

FILE ?=

.PHONY: help demo test check-cid clean

help:  ## Show this help screen
	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) \
		| awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-12s\033[0m %s\n", $$1, $$2}'

demo:  ## Print all three identifiers (override with FILE=path/to/file)
	uv run python src/demo.py $(FILE)

test:  ## Run the unit tests
	uv run pytest -v

check-cid:  ## Re-verify the CID encoder against the multiformats library
	uv run pytest -v -k multiformats

clean:  ## Remove caches and generated output
	rm -rf .pytest_cache .ruff_cache src/__pycache__ tests/__pycache__ out

cd ~/nostr-ipfs
uv sync
make test

make demo

{
  "kind": 1,
  "content": "Check out this photo of my new house ipfs://bafkreifjjcie6lypi6ny7amxnfftagclbuxndqonfipmb64f2km2devei4",
  "tags": [
    ["imeta",
     "url ipfs://bafkreifjjcie6lypi6ny7amxnfftagclbuxndqonfipmb64f2km2devei4",
     "m image/jpeg",
     "x a948904f2f0f479b8f8197694b30184b0d2ed1c1cd2a1ec0fb85d299a192a447"]
  ]
}

["imeta", "url", "ipfs://bafkrei…"]