feat(v2): hand-rolled NIP-44 v2 crypto + reference-vector tests (#29 v1)

LNbits ships only NIP-04 (AES-CBC) in lnbits.utils.nostr.encrypt_content,
but the locked design at #29 (paired with lamassu-next#56) wires kind-30078
cassette config with NIP-44 v2 content per the privacy-by-default
architecture (dcd0874). Hand-rolling rather than adding a Python lib dep
per the plan-approval (option A) — keeps the impl auditable inline and
avoids pulling in a non-trivial dep tree.

nip44.py covers the full envelope:
  - get_conversation_key — ECDH x-coord + HKDF-extract with salt b"nip44-v2"
  - encrypt_with_conversation_key / decrypt_with_conversation_key — low-level,
    nonce-controllable for testing pinned vectors
  - encrypt_for / decrypt_from — high-level pair-keyed API (the shape app
    code reaches for)
  - _pad / _unpad — NIP-44 v2 length-prefixed padding scheme
  - HMAC-SHA256 verification on nonce || ciphertext, constant-time compare
    via hmac.compare_digest
  - Typed errors (Nip44VersionError / Nip44MacError / Nip44LengthError)
    so callers can distinguish tamper from corruption from spec mismatch

Stack: coincurve for ECDH (already a transitive lnbits dep), cryptography
for ChaCha20 + HKDF-expand (also already there). No new pyproject deps.

34 tests in tests/test_nip44_v2.py, three layers:
  1. Pinned reference vector — conversation_key for (sec=1, sec=2) matches
     the canonical paulmillr/nip44 published value
     (c41c775356fd92eadc63ff5a0dc1da211b268cbea22316767095b2871ea1412d).
     Regression-fails loudly if key derivation drifts.
  2. Round-trip + tamper detection — encrypt/decrypt across plaintext
     lengths (1, 32, 33, 1000, 5000, 65535 bytes); flipped MAC byte;
     flipped ciphertext byte; flipped nonce byte; wrong recipient privkey;
     version-byte rejection; padding-formula spot checks.
  3. Cross-impl byte-compat — placeholder test_decrypts_bitspire_sample
     marked @pytest.mark.skip, pending bitspire posting a sample event
     encrypted on their nostr-tools side to the coord log (per the
     2026-05-30T15:55Z entry). Wire that fixture and unskip when posted.

Total: 132 passed, 1 skipped (cross-test fixture pending), 1 pre-existing
async-plugin failure unchanged.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

nip44.py

@@ -0,0 +1,271 @@
+"""
+NIP-44 v2 — versioned encrypted payloads (https://github.com/nostr-protocol/nips/blob/master/44.md).
+
+Hand-rolled because lnbits ships only NIP-04 (AES-CBC) in `lnbits.utils.nostr.encrypt_content`,
+and the locked design at aiolabs/satmachineadmin#29 (paired with lamassu-next#56) wires
+cassette config over kind-30078 with NIP-44 v2 encrypted content. Adding a Python NIP-44
+v2 lib dep was an option per the plan; chose the hand-roll path to stay dep-light and
+keep the impl auditable inline.
+
+Two safety nets keep this honest:
+  1. tests/test_nip44_v2.py runs reference vectors + round-trip + tamper-detection.
+  2. bitspire posts a sample event encrypted on their nostr-tools side to the coord log;
+     test_decrypts_bitspire_sample_event_from_coord_log cross-checks our impl against
+     theirs by decrypting that event with a known privkey.
+
+Wire format (per spec):
+    payload = base64( 0x02 || nonce (32B) || ciphertext (var) || mac (32B) )
+
+Key derivation:
+    conversation_key = HKDF-extract(salt=b"nip44-v2", IKM=ecdh_shared_x)  # 32B PRK, stable per pair
+    per-message:
+        nonce = csprng(32 bytes)
+        temp = HKDF-expand(PRK=conversation_key, info=nonce, L=76)
+        chacha_key   = temp[0:32]
+        chacha_nonce = temp[32:44]
+        hmac_key     = temp[44:76]
+
+Padding scheme (NIP-44 v2 length-prefixed, variable-chunk):
+    padded = uint16_be(len(plaintext)) || plaintext || zeros
+    such that 2 + padded_data_len matches a fixed step.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac as hmac_stdlib
+import os
+import struct
+from typing import Optional
+
+import coincurve
+from cryptography.hazmat.primitives import hashes, hmac
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms
+from cryptography.hazmat.primitives.kdf.hkdf import HKDFExpand
+
+# Spec constants.
+_VERSION = 0x02
+_HKDF_SALT = b"nip44-v2"
+_MIN_PLAINTEXT_LEN = 1
+_MAX_PLAINTEXT_LEN = 65535
+_NONCE_LEN = 32
+_MAC_LEN = 32
+_MIN_PAYLOAD_LEN = 1 + _NONCE_LEN + (2 + 32) + _MAC_LEN  # version + nonce + min padded + mac
+_MAX_PAYLOAD_LEN = 1 + _NONCE_LEN + (2 + 65536) + _MAC_LEN
+
+
+class Nip44Error(Exception):
+    """Generic NIP-44 v2 envelope error. Subclasses distinguish failure modes."""
+
+
+class Nip44VersionError(Nip44Error):
+    """First payload byte was not 0x02. Could be a NIP-04 envelope, a v1 NIP-44, or garbage."""
+
+
+class Nip44MacError(Nip44Error):
+    """HMAC verification failed — payload was tampered, wrong conversation key, or corrupted in transit."""
+
+
+class Nip44LengthError(Nip44Error):
+    """Plaintext or payload length outside the spec-allowed range, or padding header lies."""
+
+
+# =============================================================================
+# Padding (NIP-44 v2)
+# =============================================================================
+
+
+def _calc_padded_len(plaintext_len: int) -> int:
+    """Per NIP-44 v2 padding scheme:
+        if L <= 32: padded_len = 32
+        else: chunk = max(32, next_power_2(L-1) // 8); padded_len = chunk * ((L-1) // chunk + 1)
+    """
+    if plaintext_len <= 32:
+        return 32
+    next_power = 1 << (plaintext_len - 1).bit_length()
+    chunk = max(32, next_power // 8)
+    return chunk * ((plaintext_len - 1) // chunk + 1)
+
+
+def _pad(plaintext: bytes) -> bytes:
+    """Prefix uint16_be length + plaintext + zero-fill to the NIP-44 v2 boundary."""
+    n = len(plaintext)
+    if n < _MIN_PLAINTEXT_LEN or n > _MAX_PLAINTEXT_LEN:
+        raise Nip44LengthError(
+            f"plaintext length {n} outside [{_MIN_PLAINTEXT_LEN}, {_MAX_PLAINTEXT_LEN}]"
+        )
+    padded_data_len = _calc_padded_len(n)
+    zeros = b"\x00" * (padded_data_len - n)
+    return struct.pack(">H", n) + plaintext + zeros
+
+
+def _unpad(padded: bytes) -> bytes:
+    """Strip the uint16_be length prefix and zero padding. Validates that the
+    declared length is consistent with the padded payload (rejects a forged
+    length prefix that would slice past the buffer or imply a different
+    padded_data_len than what we received)."""
+    if len(padded) < 2:
+        raise Nip44LengthError("padded payload too short to hold length prefix")
+    declared_len = struct.unpack(">H", padded[0:2])[0]
+    if declared_len < _MIN_PLAINTEXT_LEN or declared_len > _MAX_PLAINTEXT_LEN:
+        raise Nip44LengthError(f"declared plaintext length {declared_len} out of range")
+    if len(padded) != 2 + _calc_padded_len(declared_len):
+        raise Nip44LengthError(
+            f"padded buffer length {len(padded)} doesn't match the calculated padding "
+            f"for declared length {declared_len}"
+        )
+    return padded[2 : 2 + declared_len]
+
+
+# =============================================================================
+# Conversation + message-key derivation
+# =============================================================================
+
+
+def get_conversation_key(privkey_hex: str, pubkey_hex: str) -> bytes:
+    """Derive the per-pair stable conversation key (PRK) used for all messages
+    between sender (privkey) and recipient (pubkey).
+
+    Steps:
+        shared_x = ECDH(privkey, pubkey).x      # 32 bytes, x-coordinate
+        prk      = HKDF-extract(salt=b"nip44-v2", IKM=shared_x)
+
+    coincurve's `.multiply(secret).format(compressed=True)[1:]` strips the
+    leading 0x02/0x03 parity byte to return the raw x-coord — same trick
+    `lnbits.utils.nostr.encrypt_content` uses for NIP-04.
+    """
+    sender = coincurve.PrivateKey(bytes.fromhex(privkey_hex))
+    recipient_pub = coincurve.PublicKey(b"\x02" + bytes.fromhex(pubkey_hex))
+    shared_x = recipient_pub.multiply(sender.secret).format(compressed=True)[1:]
+    # HKDF-extract is HMAC-SHA256(key=salt, msg=ikm) per RFC 5869.
+    return hmac_stdlib.new(_HKDF_SALT, shared_x, hashlib.sha256).digest()
+
+
+def _derive_message_keys(
+    conversation_key: bytes, nonce: bytes
+) -> tuple[bytes, bytes, bytes]:
+    """Per-message key expansion: HKDF-expand(PRK=conversation_key, info=nonce, L=76).
+    Returns (chacha_key 32B, chacha_nonce 12B, hmac_key 32B)."""
+    hkdf = HKDFExpand(algorithm=hashes.SHA256(), length=76, info=nonce)
+    okm = hkdf.derive(conversation_key)
+    return okm[0:32], okm[32:44], okm[44:76]
+
+
+def _hmac_aad(hmac_key: bytes, nonce: bytes, ciphertext: bytes) -> bytes:
+    """HMAC-SHA256(key=hmac_key, msg=nonce || ciphertext). Returns 32-byte MAC."""
+    h = hmac.HMAC(hmac_key, hashes.SHA256())
+    h.update(nonce)
+    h.update(ciphertext)
+    return h.finalize()
+
+
+def _chacha20(key: bytes, nonce: bytes, data: bytes) -> bytes:
+    """ChaCha20 stream cipher (symmetric: encrypt == decrypt). Used both directions.
+
+    The `cryptography` lib's `algorithms.ChaCha20(key, nonce)` expects a
+    16-byte nonce arg: a 4-byte little-endian initial counter prefix +
+    12-byte actual nonce. NIP-44 v2 starts the counter at 0 and uses the
+    HKDF-derived 12-byte chacha_nonce, so we prefix four zero bytes here.
+    """
+    if len(nonce) != 12:
+        raise Nip44LengthError(
+            f"chacha_nonce must be 12 bytes (NIP-44 v2), got {len(nonce)}"
+        )
+    cipher = Cipher(algorithms.ChaCha20(key, b"\x00\x00\x00\x00" + nonce), mode=None)
+    return cipher.encryptor().update(data)
+
+
+# =============================================================================
+# Public API — low-level (nonce-controllable for testability)
+# =============================================================================
+
+
+def encrypt_with_conversation_key(
+    plaintext: str,
+    conversation_key: bytes,
+    *,
+    nonce: Optional[bytes] = None,
+) -> str:
+    """Encrypt `plaintext` under a precomputed `conversation_key` (32B PRK).
+
+    `nonce` is 32 random bytes when omitted (the production path). Tests pass
+    it explicitly to assert pinned reference vectors.
+
+    Returns the base64-encoded payload string suitable as a Nostr event's
+    `content` field for kind-30078 (and any other kind that uses NIP-44 v2).
+    """
+    if nonce is None:
+        nonce = os.urandom(_NONCE_LEN)
+    elif len(nonce) != _NONCE_LEN:
+        raise Nip44LengthError(f"nonce must be exactly {_NONCE_LEN} bytes")
+
+    padded = _pad(plaintext.encode("utf-8"))
+    chacha_key, chacha_nonce, hmac_key = _derive_message_keys(conversation_key, nonce)
+    ciphertext = _chacha20(chacha_key, chacha_nonce, padded)
+    mac = _hmac_aad(hmac_key, nonce, ciphertext)
+    return base64.b64encode(
+        bytes([_VERSION]) + nonce + ciphertext + mac
+    ).decode("ascii")
+
+
+def decrypt_with_conversation_key(payload_b64: str, conversation_key: bytes) -> str:
+    """Decrypt a NIP-44 v2 payload using a precomputed `conversation_key`.
+
+    Raises:
+        Nip44VersionError — payload's first byte isn't 0x02
+        Nip44LengthError — payload too short / too long / declared length lies
+        Nip44MacError — HMAC verification failed (tamper, wrong key, corruption)
+    """
+    try:
+        raw = base64.b64decode(payload_b64, validate=True)
+    except Exception as exc:  # noqa: BLE001 — we want any base64 failure surfaced uniformly
+        raise Nip44LengthError(f"payload is not valid base64: {exc}") from exc
+
+    if len(raw) < _MIN_PAYLOAD_LEN or len(raw) > _MAX_PAYLOAD_LEN:
+        raise Nip44LengthError(f"payload length {len(raw)} outside valid range")
+    if raw[0] != _VERSION:
+        raise Nip44VersionError(f"unsupported NIP-44 version: 0x{raw[0]:02x}")
+
+    nonce = raw[1 : 1 + _NONCE_LEN]
+    mac_received = raw[-_MAC_LEN:]
+    ciphertext = raw[1 + _NONCE_LEN : -_MAC_LEN]
+
+    chacha_key, chacha_nonce, hmac_key = _derive_message_keys(conversation_key, nonce)
+    mac_expected = _hmac_aad(hmac_key, nonce, ciphertext)
+    # constant-time compare to avoid timing-leak in MAC verification
+    if not hmac_stdlib.compare_digest(mac_received, mac_expected):
+        raise Nip44MacError("HMAC verification failed")
+
+    padded = _chacha20(chacha_key, chacha_nonce, ciphertext)
+    plaintext_bytes = _unpad(padded)
+    return plaintext_bytes.decode("utf-8")
+
+
+# =============================================================================
+# Public API — high-level (pair-keyed, the call shape app code reaches for)
+# =============================================================================
+
+
+def encrypt_for(
+    plaintext: str,
+    sender_privkey_hex: str,
+    recipient_pubkey_hex: str,
+    *,
+    nonce: Optional[bytes] = None,
+) -> str:
+    """Encrypt `plaintext` from the sender (holding the privkey) to the recipient
+    (identified by pubkey). The recipient can decrypt with `decrypt_from(
+        payload, recipient_privkey_hex, sender_pubkey_hex)` — symmetric on the
+    conversation key, which is the same derived value from either side."""
+    conversation_key = get_conversation_key(sender_privkey_hex, recipient_pubkey_hex)
+    return encrypt_with_conversation_key(plaintext, conversation_key, nonce=nonce)
+
+
+def decrypt_from(
+    payload_b64: str, recipient_privkey_hex: str, sender_pubkey_hex: str
+) -> str:
+    """Decrypt a payload that the recipient (holding the privkey) received from
+    the sender (identified by pubkey)."""
+    conversation_key = get_conversation_key(recipient_privkey_hex, sender_pubkey_hex)
+    return decrypt_with_conversation_key(payload_b64, conversation_key)

tests/test_nip44_v2.py

@@ -0,0 +1,272 @@
+"""
+Tests for the hand-rolled NIP-44 v2 implementation in `nip44.py`.
+
+Three layers of validation, ordered by trust:
+  1. Pinned reference vector from the canonical paulmillr/nip44 test suite —
+     the conversation_key for (sec=1, sec=2) is widely-published as
+     c41c775356fd92eadc63ff5a0dc1da211b268cbea22316767095b2871ea1412d. If
+     our get_conversation_key() ever drifts from that value, the impl is
+     broken at the key-derivation layer.
+  2. Round-trip + tamper detection — verifies the encrypt/decrypt loop
+     under random nonces, catches HMAC + version + padding tampering.
+  3. Cross-test (TBD) — bitspire will post one sample event encrypted on
+     their nostr-tools side to the coord log; test_decrypts_bitspire_sample
+     wires it as a fixture and asserts byte-compatibility with the
+     nostr-tools NIP-44 v2 impl. Placeholder stub until the sample lands.
+"""
+
+import base64
+
+import coincurve
+import pytest
+
+from ..nip44 import (
+    Nip44LengthError,
+    Nip44MacError,
+    Nip44VersionError,
+    _calc_padded_len,
+    decrypt_from,
+    decrypt_with_conversation_key,
+    encrypt_for,
+    encrypt_with_conversation_key,
+    get_conversation_key,
+)
+
+# Helper: derive a compressed-x-coord pubkey hex string from a secret hex.
+def _pub_hex(sec_hex: str) -> str:
+    return (
+        coincurve.PrivateKey(bytes.fromhex(sec_hex))
+        .public_key.format(compressed=True)[1:]
+        .hex()
+    )
+
+
+# Canonical test keys widely used across NIP-44 reference vectors.
+_SEC_ONE = "00" * 31 + "01"  # integer 1
+_SEC_TWO = "00" * 31 + "02"  # integer 2
+_PUB_ONE = _pub_hex(_SEC_ONE)
+_PUB_TWO = _pub_hex(_SEC_TWO)
+
+
+# =============================================================================
+# Layer 1 — pinned reference vector (paulmillr/nip44)
+# =============================================================================
+
+
+class TestConversationKeyReferenceVector:
+    """Pinned reference vector from the canonical NIP-44 v2 test suite
+    (paulmillr/nip44). If get_conversation_key drifts from this value we
+    have a key-derivation regression — fail loudly."""
+
+    REFERENCE_CK_HEX = (
+        "c41c775356fd92eadc63ff5a0dc1da211b268cbea22316767095b2871ea1412d"
+    )
+
+    def test_sec_one_pub_two(self):
+        ck = get_conversation_key(_SEC_ONE, _PUB_TWO)
+        assert ck.hex() == self.REFERENCE_CK_HEX
+
+    def test_sec_two_pub_one_is_symmetric(self):
+        """Conversation key is symmetric: ck(privA, pubB) == ck(privB, pubA).
+        Both sides of a NIP-44 conversation derive the identical PRK; this
+        is what lets the recipient decrypt with their own privkey + the
+        sender's pubkey."""
+        ck_ab = get_conversation_key(_SEC_ONE, _PUB_TWO)
+        ck_ba = get_conversation_key(_SEC_TWO, _PUB_ONE)
+        assert ck_ab == ck_ba
+
+
+# =============================================================================
+# Layer 2 — round-trip + tamper detection
+# =============================================================================
+
+
+class TestRoundTrip:
+    """Encrypt then decrypt under the high-level pair-keyed API."""
+
+    @pytest.mark.parametrize(
+        "plaintext",
+        [
+            "a",  # 1 byte (minimum)
+            "hello, nip44 v2",  # short
+            "x" * 32,  # exactly the small-payload boundary
+            "x" * 33,  # just over
+            "y" * 1000,  # medium
+            "z" * 5000,  # large
+            '{"denominations": {"20": {"position": 1, "count": 49}}}',  # realistic
+        ],
+    )
+    def test_round_trip_various_lengths(self, plaintext):
+        payload = encrypt_for(plaintext, _SEC_ONE, _PUB_TWO)
+        recovered = decrypt_from(payload, _SEC_TWO, _PUB_ONE)
+        assert recovered == plaintext
+
+    def test_payloads_are_unique_under_random_nonce(self):
+        """Same plaintext + same key pair should produce different payloads
+        each time because the nonce is fresh CSPRNG bytes. Catches a
+        regression where the nonce is accidentally pinned."""
+        plaintext = "the same message"
+        p1 = encrypt_for(plaintext, _SEC_ONE, _PUB_TWO)
+        p2 = encrypt_for(plaintext, _SEC_ONE, _PUB_TWO)
+        assert p1 != p2
+        assert decrypt_from(p1, _SEC_TWO, _PUB_ONE) == plaintext
+        assert decrypt_from(p2, _SEC_TWO, _PUB_ONE) == plaintext
+
+    def test_pinned_nonce_is_deterministic(self):
+        """Same plaintext + same key pair + same nonce = byte-identical
+        payload. Regression-locks the chacha20 + hmac chain."""
+        ck = get_conversation_key(_SEC_ONE, _PUB_TWO)
+        nonce = bytes(32)  # 32 zero bytes
+        p1 = encrypt_with_conversation_key("a", ck, nonce=nonce)
+        p2 = encrypt_with_conversation_key("a", ck, nonce=nonce)
+        assert p1 == p2
+        assert decrypt_with_conversation_key(p1, ck) == "a"
+
+
+class TestTamperDetection:
+    """HMAC-SHA256 verification catches tampered envelopes. The cryptographic
+    construction depends on this — if HMAC verification ever no-ops, a
+    relay-MITM could forge ATM state events."""
+
+    def _payload(self) -> str:
+        return encrypt_for("important message", _SEC_ONE, _PUB_TWO)
+
+    def test_flipped_mac_byte_rejected(self):
+        raw = bytearray(base64.b64decode(self._payload()))
+        raw[-1] ^= 0x01
+        tampered = base64.b64encode(bytes(raw)).decode("ascii")
+        with pytest.raises(Nip44MacError):
+            decrypt_from(tampered, _SEC_TWO, _PUB_ONE)
+
+    def test_flipped_ciphertext_byte_rejected(self):
+        raw = bytearray(base64.b64decode(self._payload()))
+        # Flip a byte in the middle of the ciphertext segment
+        # (version[1] + nonce[32..32] + ciphertext[33..-32] + mac[-32..])
+        ct_start = 1 + 32
+        raw[ct_start + 5] ^= 0x01
+        tampered = base64.b64encode(bytes(raw)).decode("ascii")
+        with pytest.raises(Nip44MacError):
+            decrypt_from(tampered, _SEC_TWO, _PUB_ONE)
+
+    def test_flipped_nonce_byte_rejected(self):
+        raw = bytearray(base64.b64decode(self._payload()))
+        # Nonce starts at byte 1 (after version)
+        raw[1] ^= 0x01
+        tampered = base64.b64encode(bytes(raw)).decode("ascii")
+        with pytest.raises(Nip44MacError):
+            decrypt_from(tampered, _SEC_TWO, _PUB_ONE)
+
+    def test_wrong_recipient_privkey_rejected(self):
+        """The MAC is derived from the conversation key, so a wrong
+        recipient privkey produces a different conversation key →
+        different hmac_key → MAC verification fails. (Doesn't decrypt
+        to garbage; fails fast.)"""
+        sec_three = "00" * 31 + "03"
+        with pytest.raises(Nip44MacError):
+            decrypt_from(self._payload(), sec_three, _PUB_ONE)
+
+
+class TestVersionRejection:
+    def test_v1_byte_rejected(self):
+        raw = bytearray(base64.b64decode(encrypt_for("x", _SEC_ONE, _PUB_TWO)))
+        raw[0] = 0x01
+        bad = base64.b64encode(bytes(raw)).decode("ascii")
+        with pytest.raises(Nip44VersionError):
+            decrypt_from(bad, _SEC_TWO, _PUB_ONE)
+
+    def test_unknown_version_byte_rejected(self):
+        raw = bytearray(base64.b64decode(encrypt_for("x", _SEC_ONE, _PUB_TWO)))
+        raw[0] = 0xFF
+        bad = base64.b64encode(bytes(raw)).decode("ascii")
+        with pytest.raises(Nip44VersionError):
+            decrypt_from(bad, _SEC_TWO, _PUB_ONE)
+
+
+class TestLengthGuards:
+    def test_empty_plaintext_rejected(self):
+        with pytest.raises(Nip44LengthError):
+            encrypt_for("", _SEC_ONE, _PUB_TWO)
+
+    def test_plaintext_at_max_length_accepted(self):
+        plaintext = "x" * 65535
+        payload = encrypt_for(plaintext, _SEC_ONE, _PUB_TWO)
+        assert decrypt_from(payload, _SEC_TWO, _PUB_ONE) == plaintext
+
+    def test_plaintext_over_max_rejected(self):
+        with pytest.raises(Nip44LengthError):
+            encrypt_for("x" * 65536, _SEC_ONE, _PUB_TWO)
+
+    def test_invalid_base64_payload_rejected(self):
+        with pytest.raises(Nip44LengthError):
+            decrypt_from("not!!!base64@@@", _SEC_TWO, _PUB_ONE)
+
+    def test_payload_too_short_rejected(self):
+        # 50 bytes is well under the 99-byte minimum
+        too_short = base64.b64encode(b"\x02" + b"\x00" * 49).decode("ascii")
+        with pytest.raises(Nip44LengthError):
+            decrypt_from(too_short, _SEC_TWO, _PUB_ONE)
+
+
+class TestPaddingFormula:
+    """Spot-check the _calc_padded_len formula against hand-computed cases.
+    Locks in the NIP-44 v2 padding scheme so a refactor can't silently
+    break wire compatibility (which would only surface as cross-impl
+    decryption failures — exactly what test_decrypts_bitspire_sample is
+    meant to catch end-to-end, but a unit test here is cheaper)."""
+
+    @pytest.mark.parametrize(
+        "plaintext_len,expected_padded",
+        [
+            (1, 32),  # <= 32 → 32
+            (16, 32),
+            (32, 32),
+            (33, 64),  # > 32 → next chunk
+            (64, 64),
+            (65, 96),  # chunk = 32 for L=65 (next_power(64) = 64; 64//8 = 8; max(32, 8) = 32)
+            (100, 128),
+            (128, 128),
+            # L=129: next_power(128) = 1<<8 = 256; chunk = max(32, 256//8) = 32;
+            # padded = 32 * (128//32 + 1) = 32 * 5 = 160.
+            (129, 160),
+            (256, 256),  # chunk = 32 for L=256 (next_power(255)=256; max(32, 32) = 32)
+            (257, 320),
+            (1000, 1024),  # chunk = 128 for L=1000 (next_power(999)=1024; max(32, 128) = 128)
+        ],
+    )
+    def test_calc_padded_len(self, plaintext_len, expected_padded):
+        assert _calc_padded_len(plaintext_len) == expected_padded
+
+
+# =============================================================================
+# Layer 3 — byte-compat cross-test against nostr-tools (bitspire's impl)
+# =============================================================================
+
+
+@pytest.mark.skip(
+    reason=(
+        "Waiting on bitspire to post one sample encrypted event to "
+        "~/dev/coordination/log.md per the 2026-05-30T15:55Z entry. Once "
+        "posted, hardcode the (event_id, content, recipient_privkey, "
+        "expected_plaintext) fixture here and remove the skip — this test "
+        "is the byte-compat cross-test between our hand-rolled NIP-44 v2 "
+        "and the nostr-tools impl the ATM uses."
+    )
+)
+def test_decrypts_bitspire_sample_event_from_coord_log():
+    """Cross-impl byte-compatibility test. Bitspire generates one event on
+    their side (nostr-tools NIP-44 v2 impl), posts the raw event JSON +
+    a known throwaway recipient privkey to the coord log, and we assert
+    our `decrypt_from` recovers the expected `{"denominations": {...}}`
+    plaintext.
+
+    If this passes, both impls produce byte-identical wire format. If it
+    fails, the spec ambiguity surfaces before either side ships — exactly
+    what bitspire flagged in the plan review (`07:55Z`).
+    """
+    # event_b64_content = "..."   # paste from coord log
+    # sender_pubkey_hex = "..."
+    # recipient_privkey_hex = "..."
+    # expected_plaintext = '{"denominations": {"20": {"position": 1, "count": 49}}}'
+    # recovered = decrypt_from(event_b64_content, recipient_privkey_hex, sender_pubkey_hex)
+    # assert recovered == expected_plaintext
+    raise NotImplementedError("fixture pending — see skip reason")