hpqc 0.0.1__py3-none-any.whl

hpqc/__init__.py

@@ -0,0 +1,13 @@
+# SPDX-FileCopyrightText: © 2026 David Stainton
+# SPDX-License-Identifier: AGPL-3.0-only
+"""hpqc: Python port of katzenpost/hpqc."""
+
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+try:
+    __version__ = _pkg_version("hpqc")
+except PackageNotFoundError:
+    # Running from a source checkout without an install (e.g.
+    # someone imported this directly off disk). The released
+    # version is the one in py/pyproject.toml.
+    __version__ = "0.0.0+unknown"

hpqc/bacap/__init__.py

@@ -0,0 +1,64 @@
+# SPDX-FileCopyrightText: © 2026 David Stainton
+# SPDX-License-Identifier: AGPL-3.0-only
+"""Python port of katzenpost/hpqc/bacap.
+
+The package exposes two complementary APIs:
+
+  - **Stateless** (``hpqc.bacap.stateless``): ``MessageBoxIndex``,
+    ``WriteCap`` and ``ReadCap`` are pure values; every cryptographic
+    operation is a method that takes its inputs and returns its
+    outputs without mutating the caller's state. Suitable for callers
+    that already manage the per-conversation state themselves and want
+    a thin layer over the BACAP primitives.
+
+  - **Stateful** (``hpqc.bacap.stateful``): ``StatefulReader`` and
+    ``StatefulWriter`` are mutable wrappers built on the stateless
+    layer. They carry the next-index pointer and advance it after each
+    successful read or write, mirroring the Go API.
+
+Both APIs sit on the same primitives and produce byte-identical
+output; pick whichever shape suits your application.
+"""
+from .exceptions import (
+    BACAPError,
+    BoxIDMismatch,
+    CannotRewind,
+    DecryptionFailed,
+    EmptyBox,
+    InvalidArgument,
+    SignatureVerificationFailed,
+)
+from .stateless import (
+    BoxIDSize,
+    MessageBoxIndex,
+    MessageBoxIndexSize,
+    ReadCap,
+    ReadCapSize,
+    SignatureSize,
+    WriteCap,
+    WriteCapSize,
+)
+from .stateful import StatefulReader, StatefulWriter
+
+__all__ = [
+    # exceptions
+    "BACAPError",
+    "BoxIDMismatch",
+    "CannotRewind",
+    "DecryptionFailed",
+    "EmptyBox",
+    "InvalidArgument",
+    "SignatureVerificationFailed",
+    # stateless
+    "BoxIDSize",
+    "MessageBoxIndex",
+    "MessageBoxIndexSize",
+    "ReadCap",
+    "ReadCapSize",
+    "SignatureSize",
+    "WriteCap",
+    "WriteCapSize",
+    # stateful
+    "StatefulReader",
+    "StatefulWriter",
+]

hpqc/bacap/exceptions.py

@@ -0,0 +1,63 @@
+# SPDX-FileCopyrightText: © 2026 David Stainton
+# SPDX-License-Identifier: AGPL-3.0-only
+"""Exception hierarchy for the BACAP API.
+
+All exceptions raised from ``hpqc.bacap`` derive from ``BACAPError``,
+so callers can catch the entire surface with a single ``except``. The
+distinct subclasses let a caller act on the specific failure mode:
+
+  - ``InvalidArgument``: caller-supplied input is malformed (wrong
+    size, wrong type, out of range, ``None`` where required, or the
+    object is in a state that does not permit the requested operation).
+    A bug on the caller's side.
+
+  - ``CannotRewind``: caller tried to advance a ``MessageBoxIndex`` to
+    an earlier position. Specific subclass of ``InvalidArgument``
+    because rewind is a recurring, recognisable misuse worth catching
+    on its own.
+
+  - ``EmptyBox``: a stateful reader was handed a zero-byte box ID,
+    indicating no message has been deposited at that index yet.
+    Typically a transient condition rather than a protocol violation.
+
+  - ``BoxIDMismatch``: the box ID supplied to a stateful reader does
+    not match the box ID it expected next. The caller may have read
+    out of order, or the message may belong to a different
+    conversation.
+
+  - ``SignatureVerificationFailed``: a BACAP signature did not verify
+    under the expected box-ID public key. Always a protocol failure
+    or tampering.
+
+  - ``DecryptionFailed``: AES-256-GCM-SIV authentication failed at
+    decryption time. Always a protocol failure or tampering.
+"""
+from __future__ import annotations
+
+
+class BACAPError(Exception):
+    """Base class for all BACAP-specific exceptions."""
+
+
+class InvalidArgument(BACAPError):
+    """Caller supplied invalid input (wrong size/type, None, bad state)."""
+
+
+class CannotRewind(InvalidArgument):
+    """Attempted to advance a MessageBoxIndex to an earlier position."""
+
+
+class EmptyBox(BACAPError):
+    """Box ID is all-zero; no message available at this index."""
+
+
+class BoxIDMismatch(BACAPError):
+    """Received box ID does not match the expected box ID."""
+
+
+class SignatureVerificationFailed(BACAPError):
+    """Signature did not verify under the expected box-ID public key."""
+
+
+class DecryptionFailed(BACAPError):
+    """AES-256-GCM-SIV authentication failed at decryption time."""

hpqc/bacap/stateful.py

@@ -0,0 +1,189 @@
+# SPDX-FileCopyrightText: © 2026 David Stainton
+# SPDX-License-Identifier: AGPL-3.0-only
+"""Stateful BACAP wrappers built on the stateless layer.
+
+StatefulReader and StatefulWriter carry a mutable next-index pointer
+and advance it after each successful read or write. They sit on the
+stateless API in stateless.py; everything they do is expressible as a
+sequence of stateless calls. Pick whichever shape suits your caller.
+"""
+from __future__ import annotations
+
+from typing import Optional, Tuple
+
+from .exceptions import (
+    BoxIDMismatch,
+    EmptyBox,
+    InvalidArgument,
+)
+from .stateless import (
+    BoxIDSize,
+    MessageBoxIndex,
+    ReadCap,
+    SignatureSize,
+    WriteCap,
+)
+
+
+class StatefulReader:
+    """Sequential reader over a BACAP ReadCap.
+
+    Holds the next-index pointer and the conversation context, advancing
+    the pointer after each successful decrypt_next.
+    """
+
+    def __init__(
+        self,
+        read_cap: ReadCap,
+        ctx: bytes,
+        next_index: Optional[MessageBoxIndex] = None,
+    ) -> None:
+        if read_cap is None:
+            raise InvalidArgument("read_cap is None")
+        if ctx is None:
+            raise InvalidArgument("ctx is None")
+        self.read_cap: ReadCap = read_cap
+        # Defensive copy of ctx so callers cannot mutate it under us.
+        self.ctx: bytes = bytes(ctx)
+        if next_index is None:
+            # Start at the conversation's first message box.
+            self.last_inbox_read: Optional[MessageBoxIndex] = read_cap.first_message_box_index
+            self.next_index: Optional[MessageBoxIndex] = read_cap.first_message_box_index
+        else:
+            # Resuming from a known checkpoint or starting fresh from a
+            # specific index; this instance has no prior-read history.
+            self.last_inbox_read = None
+            self.next_index = next_index
+
+    def next_box_id(self) -> bytes:
+        """Returns the box ID this reader will read next, without advancing."""
+        if self.next_index is not None:
+            cur = self.next_index
+        else:
+            if self.last_inbox_read is None:
+                raise InvalidArgument("both next_index and last_inbox_read are None")
+            cur = self.last_inbox_read.next_index()
+        return cur.box_id_for_context(self.read_cap, self.ctx)
+
+    def get_current_message_index(self) -> Optional[MessageBoxIndex]:
+        """Returns the MessageBoxIndex that will be used for the next read."""
+        return self.next_index
+
+    def get_next_message_index(self) -> MessageBoxIndex:
+        """Returns what next_index will be after a successful decrypt_next.
+
+        Does NOT advance state; useful for crash-consistency planning.
+        """
+        if self.next_index is None:
+            raise InvalidArgument("next index is None")
+        return self.next_index.next_index()
+
+    def decrypt_next(
+        self,
+        ctx: bytes,
+        box: bytes,
+        ciphertext: bytes,
+        signature: bytes,
+    ) -> bytes:
+        """Verifies, decrypts, and advances state on success.
+
+        ``ctx`` is the decryption context (passed through to the stateless
+        primitive); ``self.ctx`` is the box-ID context. They are the same
+        in normal use but the API allows them to differ, mirroring Go.
+        """
+        if len(box) != BoxIDSize:
+            raise InvalidArgument("invalid box length")
+        if all(b == 0 for b in box):
+            raise EmptyBox("empty box, no message received")
+        if self.next_index is None:
+            raise InvalidArgument("next index is None, cannot parse reply")
+        if len(signature) != SignatureSize:
+            raise InvalidArgument("invalid signature length")
+
+        expected = self.next_index.box_id_for_context(self.read_cap, self.ctx)
+        if box != expected:
+            raise BoxIDMismatch("reply does not match expected box ID")
+
+        # Do everything that can fail BEFORE mutating state.
+        plaintext = self.next_index.decrypt_for_context(box, ctx, ciphertext, signature)
+        next_idx = self.next_index.next_index()
+
+        self.last_inbox_read = self.next_index
+        self.next_index = next_idx
+        return plaintext
+
+
+class StatefulWriter:
+    """Sequential writer over a BACAP WriteCap.
+
+    Splits the per-message work into prepare_next (encrypt without
+    advancing) and advance_state (advance after the courier acks); the
+    convenience method encrypt_next does both.
+    """
+
+    def __init__(
+        self,
+        owner: WriteCap,
+        ctx: bytes,
+        next_index: Optional[MessageBoxIndex] = None,
+    ) -> None:
+        if ctx is None:
+            raise InvalidArgument("ctx is None")
+        if next_index is not None and owner is None:
+            raise InvalidArgument("owner is None")
+        self.write_cap: WriteCap = owner
+        self.ctx: bytes = bytes(ctx)
+        if next_index is None:
+            self.last_outbox_idx: Optional[MessageBoxIndex] = None
+            self.next_index: Optional[MessageBoxIndex] = owner.first_message_box_index if owner is not None else None
+        else:
+            self.last_outbox_idx = None
+            self.next_index = next_index
+
+    def next_box_id(self) -> bytes:
+        """Returns the box ID this writer will write next, without advancing."""
+        if self.next_index is None:
+            raise InvalidArgument("next index is None")
+        if self.write_cap is None:
+            raise InvalidArgument("write_cap is None")
+        return self.next_index.box_id_for_context(self.write_cap.read_cap(), self.ctx)
+
+    def get_current_message_index(self) -> Optional[MessageBoxIndex]:
+        return self.next_index
+
+    def get_next_message_index(self) -> MessageBoxIndex:
+        """Returns what next_index will be after advance_state. No mutation."""
+        if self.next_index is None:
+            raise InvalidArgument("next index is None")
+        return self.next_index.next_index()
+
+    def prepare_next(self, plaintext: bytes) -> Tuple[bytes, bytes, bytes]:
+        """Encrypts a message WITHOUT advancing state.
+
+        Returns (box_id, ciphertext, signature). Call advance_state after
+        the courier acknowledges receipt.
+        """
+        if self.next_index is None:
+            raise InvalidArgument("next index is None")
+        return self.next_index.encrypt_for_context(self.write_cap, self.ctx, plaintext)
+
+    def advance_state(self) -> None:
+        """Advances the writer's state to the next index.
+
+        Should only be called after the courier acknowledges receipt.
+        """
+        if self.next_index is None:
+            raise InvalidArgument("next index is None")
+        next_idx = self.next_index.next_index()
+        self.last_outbox_idx = self.next_index
+        self.next_index = next_idx
+
+    def encrypt_next(self, plaintext: bytes) -> Tuple[bytes, bytes, bytes]:
+        """Encrypts a message and advances state after the encrypt succeeds.
+
+        Equivalent to prepare_next + advance_state; provided for the
+        common case where you do not need to defer the advance.
+        """
+        result = self.prepare_next(plaintext)
+        self.advance_state()
+        return result

hpqc/bacap/stateless.py

@@ -0,0 +1,361 @@
+# SPDX-FileCopyrightText: © 2026 David Stainton
+# SPDX-License-Identifier: AGPL-3.0-only
+"""Stateless BACAP types and operations.
+
+Direct port of the stateless surface of bacap/bacap.go. The classes
+here are immutable values; every cryptographic operation either
+returns a new object or returns a tuple of bytes. Callers managing
+sequential state across messages can either re-derive each step from
+a known starting point on demand, or use the StatefulReader /
+StatefulWriter wrappers in stateful.py, which simply hold a mutable
+next-index pointer and advance it after each successful operation.
+"""
+from __future__ import annotations
+
+import dataclasses
+import hashlib
+import hmac
+import os
+import struct
+from typing import Callable, Optional, Tuple
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives.ciphers.aead import AESGCMSIV
+from nacl.exceptions import BadSignatureError
+from nacl.signing import VerifyKey as NaclVerifyKey
+
+from hpqc.sign.ed25519 import (
+    SigningKey as BlindableSigningKey,
+    VerifyKey as BlindableVerifyKey,
+)
+
+from .exceptions import (
+    CannotRewind,
+    DecryptionFailed,
+    InvalidArgument,
+    SignatureVerificationFailed,
+)
+
+
+# Sizes mirror those declared in bacap/bacap.go.
+MessageBoxIndexSize: int = 8 + 32 + 32 + 32  # 104
+BoxIDSize: int = 32  # ed25519 public key
+SignatureSize: int = 64  # ed25519 signature
+_Ed25519PrivateKeySize: int = 64  # seed || pubkey, matching Go's encoding
+WriteCapSize: int = _Ed25519PrivateKeySize + MessageBoxIndexSize  # 168
+ReadCapSize: int = BoxIDSize + MessageBoxIndexSize  # 136
+
+
+def _hkdf_blake2b(secret: bytes, salt: bytes, info: bytes, length: int) -> bytes:
+    """HKDF-BLAKE2b-512 per RFC 5869.
+
+    Parameter ordering matches Go's hkdf.New(blake2b.New512(nil), secret,
+    salt, info). An empty salt is replaced with a hash-length zero block,
+    per the RFC.
+    """
+    digest_size = 64
+    if not salt:
+        salt = b"\x00" * digest_size
+    prk = hmac.new(salt, secret, hashlib.blake2b).digest()
+    out = bytearray()
+    t = b""
+    counter = 1
+    while len(out) < length:
+        t = hmac.new(prk, t + info + bytes([counter]), hashlib.blake2b).digest()
+        out += t
+        counter += 1
+    return bytes(out[:length])
+
+
+@dataclasses.dataclass(frozen=True)
+class MessageBoxIndex:
+    """Position in the BACAP message-box derivation sequence.
+
+    Wire format (104 bytes, little-endian):
+      idx_64                : 8 bytes
+      cur_blinding_factor   : 32 bytes
+      cur_encryption_key    : 32 bytes
+      hkdf_state            : 32 bytes
+    """
+
+    idx_64: int
+    cur_blinding_factor: bytes  # 32 bytes
+    cur_encryption_key: bytes   # 32 bytes
+    hkdf_state: bytes           # 32 bytes
+
+    def __post_init__(self) -> None:
+        if not (0 <= self.idx_64 < 1 << 64):
+            raise InvalidArgument("idx_64 out of range for uint64")
+        for name in ("cur_blinding_factor", "cur_encryption_key", "hkdf_state"):
+            v = getattr(self, name)
+            if not isinstance(v, (bytes, bytearray)) or len(v) != 32:
+                raise InvalidArgument(f"{name} must be 32 bytes")
+
+    @classmethod
+    def empty(cls) -> "MessageBoxIndex":
+        zero = b"\x00" * 32
+        return cls(0, zero, zero, zero)
+
+    @classmethod
+    def random(cls, rng: Optional[Callable[[int], bytes]] = None) -> "MessageBoxIndex":
+        """Creates a freshly-randomized MessageBoxIndex.
+
+        Picks a random HKDF state and a random starting Idx64 in
+        roughly 0..2^63-2 (using the Irwin-Hall sum of two 2^62-bit
+        integers strategy from the Go implementation), then advances
+        once so that the returned index has properly-derived blinding
+        and encryption keys.
+        """
+        if rng is None:
+            rng = os.urandom
+        hkdf_state = rng(32)
+        idx_bytes = bytearray(rng(16))
+        idx_bytes[0] &= 0x2F
+        idx_bytes[8] &= 0x2F
+        a = int.from_bytes(idx_bytes[:8], "little")
+        b = int.from_bytes(idx_bytes[8:], "little")
+        # Go's uint64 addition wraps on overflow; mirror that.
+        idx = (a + b) & 0xFFFFFFFFFFFFFFFF
+        seed = cls(idx, b"\x00" * 32, b"\x00" * 32, hkdf_state)
+        return seed.next_index()
+
+    def to_bytes(self) -> bytes:
+        return (
+            struct.pack("<Q", self.idx_64)
+            + self.cur_blinding_factor
+            + self.cur_encryption_key
+            + self.hkdf_state
+        )
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> "MessageBoxIndex":
+        if len(data) != MessageBoxIndexSize:
+            raise InvalidArgument("invalid MessageBoxIndex binary size")
+        return cls(
+            struct.unpack("<Q", data[:8])[0],
+            bytes(data[8:40]),
+            bytes(data[40:72]),
+            bytes(data[72:104]),
+        )
+
+    # ----- index advancement -----
+
+    def advance_index_to(self, target: int) -> "MessageBoxIndex":
+        """Returns a new MessageBoxIndex stepped to the given idx via HKDF."""
+        if target < self.idx_64:
+            raise CannotRewind(
+                f"cannot rewind index: target {target} < current {self.idx_64}"
+            )
+        if target == self.idx_64:
+            return self
+        cur_idx = self.idx_64
+        hkdf_state = self.hkdf_state
+        cur_enc_key = b"\x00" * 32
+        cur_blinding = b"\x00" * 32
+        while cur_idx < target:
+            okm = _hkdf_blake2b(
+                secret=hkdf_state,
+                salt=b"",
+                info=struct.pack("<Q", cur_idx),
+                length=96,
+            )
+            hkdf_state = okm[:32]
+            cur_enc_key = okm[32:64]
+            cur_blinding = okm[64:96]
+            cur_idx += 1
+        return MessageBoxIndex(cur_idx, cur_blinding, cur_enc_key, hkdf_state)
+
+    def next_index(self) -> "MessageBoxIndex":
+        return self.advance_index_to(self.idx_64 + 1)
+
+    # ----- box-ID derivation -----
+
+    def derive_message_box_id(self, root_public_key: BlindableVerifyKey) -> bytes:
+        """Returns the blinded box-ID public key (32 bytes)."""
+        return bytes(root_public_key.blind(self.cur_blinding_factor))
+
+    def _derive_k_for_context(self, ctx: bytes) -> bytes:
+        return _hkdf_blake2b(
+            secret=self.cur_blinding_factor,
+            salt=ctx,
+            info=b"",
+            length=32,
+        )
+
+    def _derive_e_for_context(self, ctx: bytes) -> bytes:
+        return _hkdf_blake2b(
+            secret=self.cur_encryption_key,
+            salt=ctx,
+            info=b"",
+            length=32,
+        )
+
+    def box_id_for_context(self, read_cap: "ReadCap", ctx: bytes) -> bytes:
+        """Returns the box ID (32-byte blinded ed25519 pubkey) for ctx."""
+        k_ctx = self._derive_k_for_context(ctx)
+        return bytes(read_cap.root_public_key.blind(k_ctx))
+
+    # ----- sign / verify -----
+
+    def sign_box(
+        self, owner: "WriteCap", ctx: bytes, ciphertext: bytes
+    ) -> Tuple[bytes, bytes]:
+        """Signs ciphertext under the blinded private key for this index+ctx.
+
+        Returns (box_id, signature). The signature verifies under standard
+        Ed25519 against box_id, so any standards-compliant verifier works.
+        """
+        k_ctx = self._derive_k_for_context(ctx)
+        box_id = bytes(owner.root_public_key.blind(k_ctx))
+        blinded_priv = owner.root_private_key.blind(k_ctx)
+        sig = blinded_priv.sign(ciphertext)[:64]
+        return box_id, sig
+
+    @staticmethod
+    def verify_box(box: bytes, ciphertext: bytes, signature: bytes) -> bool:
+        """Returns True iff signature verifies under box (the box-ID pubkey)."""
+        if len(box) != BoxIDSize:
+            raise InvalidArgument("invalid box length")
+        try:
+            NaclVerifyKey(box).verify(ciphertext, signature)
+        except BadSignatureError:
+            return False
+        return True
+
+    # ----- encrypt / decrypt -----
+
+    def encrypt_for_context(
+        self, owner: "WriteCap", ctx: bytes, plaintext: bytes
+    ) -> Tuple[bytes, bytes, bytes]:
+        """Encrypts plaintext for this index+ctx.
+
+        Returns (box_id, ciphertext, signature). The signature is over the
+        ciphertext, made by the blinded private key whose corresponding
+        blinded pubkey is box_id.
+        """
+        k_ctx = self._derive_k_for_context(ctx)
+        box_id = bytes(owner.root_public_key.blind(k_ctx))
+        e_ctx = self._derive_e_for_context(ctx)
+        nonce = box_id[:12]
+        aad = box_id
+        ciphertext = AESGCMSIV(e_ctx).encrypt(nonce, plaintext, aad)
+        blinded_priv = owner.root_private_key.blind(k_ctx)
+        sig = blinded_priv.sign(ciphertext)[:64]
+        return box_id, ciphertext, sig
+
+    def decrypt_for_context(
+        self,
+        box: bytes,
+        ctx: bytes,
+        ciphertext: bytes,
+        signature: bytes,
+    ) -> bytes:
+        """Verifies signature, then AES-GCM-SIV-decrypts ciphertext.
+
+        An empty ciphertext is treated as a tombstone: the signature is
+        verified over the empty payload and an empty plaintext is returned
+        without any decryption.
+        """
+        if len(box) != BoxIDSize:
+            raise InvalidArgument("invalid box length")
+        try:
+            NaclVerifyKey(box).verify(ciphertext, signature)
+        except BadSignatureError as e:
+            raise SignatureVerificationFailed(
+                "signature did not verify under the box-ID public key"
+            ) from e
+        if not ciphertext:
+            return b""
+        e_ctx = self._derive_e_for_context(ctx)
+        try:
+            return AESGCMSIV(e_ctx).decrypt(box[:12], ciphertext, box)
+        except InvalidTag as e:
+            raise DecryptionFailed("AES-256-GCM-SIV authentication failed") from e
+
+
+def _seed_from_signing_key(sk: BlindableSigningKey) -> bytes:
+    """Returns the 32-byte ed25519 seed from a SigningKey."""
+    return bytes(sk)
+
+
+def _ed25519_64byte_private(sk: BlindableSigningKey) -> bytes:
+    """Returns the 64-byte (seed||pubkey) form of an ed25519 private key.
+
+    Matches Go's crypto/ed25519 marshaling so that WriteCap.to_bytes()
+    is byte-identical to the Go side's WriteCap.MarshalBinary().
+    """
+    return _seed_from_signing_key(sk) + bytes(sk.verify_key)
+
+
+@dataclasses.dataclass(frozen=True)
+class WriteCap:
+    """Holds the root private key plus the conversation's first MessageBoxIndex.
+
+    The bearer of a WriteCap can derive the full box ID sequence and the
+    corresponding signing keys; deriving a ReadCap from it gives someone
+    else the ability to read but not write.
+    """
+
+    root_private_key: BlindableSigningKey
+    first_message_box_index: MessageBoxIndex
+
+    @property
+    def root_public_key(self) -> BlindableVerifyKey:
+        return self.root_private_key.verify_key
+
+    @classmethod
+    def generate(
+        cls,
+        rng: Optional[Callable[[int], bytes]] = None,
+    ) -> "WriteCap":
+        """Returns a new WriteCap with a fresh random keypair and first index."""
+        if rng is None:
+            rng = os.urandom
+        sk = BlindableSigningKey(rng(32))
+        return cls(sk, MessageBoxIndex.random(rng))
+
+    def to_bytes(self) -> bytes:
+        return _ed25519_64byte_private(self.root_private_key) + self.first_message_box_index.to_bytes()
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> "WriteCap":
+        if len(data) != WriteCapSize:
+            raise InvalidArgument("invalid WriteCap binary size")
+        # Go stores seed||pubkey; we re-derive pubkey from seed and ignore
+        # the stored pubkey (it is implied by the seed).
+        sk = BlindableSigningKey(data[:32])
+        idx = MessageBoxIndex.from_bytes(data[_Ed25519PrivateKeySize:])
+        return cls(sk, idx)
+
+    def read_cap(self) -> "ReadCap":
+        """Returns the ReadCap derived from this WriteCap."""
+        return ReadCap(self.root_public_key, self.first_message_box_index)
+
+    def derive_box_id(self, message_box_index: MessageBoxIndex) -> bytes:
+        return message_box_index.derive_message_box_id(self.root_public_key)
+
+
+@dataclasses.dataclass(frozen=True)
+class ReadCap:
+    """Holds the root public key plus the conversation's first MessageBoxIndex.
+
+    The bearer can derive the full box-ID sequence and verify+decrypt
+    messages, but cannot sign new ones.
+    """
+
+    root_public_key: BlindableVerifyKey
+    first_message_box_index: MessageBoxIndex
+
+    def to_bytes(self) -> bytes:
+        return bytes(self.root_public_key) + self.first_message_box_index.to_bytes()
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> "ReadCap":
+        if len(data) != ReadCapSize:
+            raise InvalidArgument("invalid ReadCap binary size")
+        pk = BlindableVerifyKey(data[:BoxIDSize])
+        idx = MessageBoxIndex.from_bytes(data[BoxIDSize:])
+        return cls(pk, idx)
+
+    def derive_box_id(self, message_box_index: MessageBoxIndex) -> bytes:
+        return message_box_index.derive_message_box_id(self.root_public_key)