pure-mls 3.0.4.0__tar.gz

pure_mls-3.0.4.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.3
+Name: pure-mls
+Version: 3.0.4.0
+Summary: Pure Python MLS implementation with CLI. Still maturing the application messaging CLI commands.
+Author: Joan F Garcia
+Author-email: Joan F Garcia <joanfgarcia@gmail.com>
+Requires-Dist: cryptography>=46.0.5
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# pure-mls
+
+`pure-mls` is a zero-dependency, pure Python implementation of the Messaging Layer Security (MLS) protocol ([RFC 9420](https://datatracker.ietf.org/doc/rfc9420/)). This project provides a production-grade cryptographic state machine for secure group messaging.
+
+## 🚀 Features & Interoperability
+`pure-mls` has achieved full cryptographic interoperability with the IETF standard, passing 100% of the **Passive Client Welcome** and **PSK Resolution** test vectors (OpenMLS benchmark):
+- **RFC 9420 Compliant**: Full implementation of the TreeKEM and Key Schedule lifecycle.
+- **IETF Vector Verification**: 100% pass rate on interoperability suites.
+- **Transports**: Verified E2E over WebSockets, MQTT (IoT), WebRTC (P2P), and gRPC.
+
+## 🧠 Philosophy: "Sound of Silence"
+The goal is **Absolute Purity**:
+- No compiled bindings (no Rust, C++ or FFI).
+- Operates natively in any Python 3.12+ environment.
+- Suitable for zero-friction edge computing and standard backend runtimes.
+- Built on principles of [Plausible Deniability and Zero-Knowledge](docs/00_MANIFESTO.md).
+
+### The Linter Protocol
+We strictly enforce the **"Sound of Silence"** code standard via `ruff` in the `pyproject.toml` file:
+- **Zero-Warning State**: 100% clean status under Ruff's most rigorous rules.
+- Pure Tabulations (`\t`) for minimal character footprint (`W191` allowance).
+- Zero dead code allowed.
+
+## 🗺️ Architecture (Project Map)
+```text
+pure-mls/
+├── README.md               # This file
+├── CHANGELOG.md            # Version history registry
+├── pyproject.toml          # Dependencies (uv) and Sound of Silence config (Ruff)
+├── src/
+│   └── pure_mls/
+│       ├── group.py        # [API] State Machine (MLSGroup)
+│       ├── tree.py         # Nodes and RatchetTree structure
+│       ├── tls.py          # RFC 9420 / TLS 1.3 Wire Format Primitives
+│       ├── extensions.py   # MLS Extensions Framework
+│       ├── proposals.py    # Group Operations (Add, Update, Remove)
+│       ├── epoch.py        # Immutable states (Epochs)
+│       ├── keys.py         # Ed25519 Identities and X25519 KEMs
+│       ├── keyschedule.py  # Secret Derivation (Application_Key)
+│       └── hpke.py         # Hybrid Public Key Encryption Base Mode
+└── tests/
+    ├── test_ietf_vectors.py # 100% RFC 9420 Interop (IETF/OpenMLS)
+    ├── test_group.py       # State Machine unit tests
+    ├── test_e2e_websockets.py # E2E local Websockets
+    ├── test_e2e_mqtt.py    # E2E broker.hivemq.com (IoT)
+    ├── test_e2e_webrtc.py  # E2E Data Channels P2P (aiortc)
+    └── test_e2e_grpc.py    # E2E Backend Swarm (Proto Hub)
+```
+## 📚 Documentation & Guides
+We believe in making cryptography accessible. For a fast, pragmatic, and irreverent introduction to MLS, check our Primate Survival Guide:
+- 🦍 [The Primate Survival Guide to pure-mls (EN)](docs/03_MLS_FOR_PRIMATES_EN.md)
+- 🦍 [Guía del Primate Sobreviviendo a pure-mls (ES)](docs/03_MLS_FOR_PRIMATES_ES.md)
+
+For a deeper dive into the architecture, mathematics, and philosophy of the protocol, explore the Human Journey:
+- 🇺🇸 [The Human Guide to MLS: The Journey (EN)](docs/02_MLS_JOURNEY_EN.md)
+- 🇪🇸 [La Guía Humana de MLS: El Viaje (ES)](docs/02_MLS_JOURNEY_ES.md)
+
+*Contributors: We welcome translations! Feel free to PR your language following the `02_MLS_JOURNEY_XX.md` format.*
+
+## 🔌 API Quickstart
+The central state machine is `MLSGroup`. Install it in your brain:
+
+```python
+from pure_mls.group import MLSGroup
+from pure_mls.keys import SignatureKey, KemKey
+
+# 1. Each participant generates their own persistent identity keys
+alice_sig, alice_kem = SignatureKey(), KemKey()
+bob_sig, bob_kem = SignatureKey(), KemKey()
+
+# 2. Alice initializes the Sovereign Group
+alice_group = MLSGroup.create(b"grupo-soberano", alice_sig, alice_kem)
+
+# 3. Alice receives Bob's `KeyPackage` (his public keys + identity) over the network
+bob_kp = MLSGroup.create_key_package(bob_sig, bob_kem)
+alice_next, welcome, update = alice_group.add_member(bob_kp)
+
+# 4. Bob decrypts the Welcome (sealed with HPKE to his KEM key) and joins
+bob_group = MLSGroup.join(welcome, bob_sig, bob_kem)
+
+# The Underlying Mathematical Truth:
+assert alice_next.application_key == bob_group.application_key
+```
+
+## License
+This project is licensed under the GNU General Public License v3.0 (GPLv3).

pure_mls-3.0.4.0/README.md

@@ -0,0 +1,86 @@
+# pure-mls
+
+`pure-mls` is a zero-dependency, pure Python implementation of the Messaging Layer Security (MLS) protocol ([RFC 9420](https://datatracker.ietf.org/doc/rfc9420/)). This project provides a production-grade cryptographic state machine for secure group messaging.
+
+## 🚀 Features & Interoperability
+`pure-mls` has achieved full cryptographic interoperability with the IETF standard, passing 100% of the **Passive Client Welcome** and **PSK Resolution** test vectors (OpenMLS benchmark):
+- **RFC 9420 Compliant**: Full implementation of the TreeKEM and Key Schedule lifecycle.
+- **IETF Vector Verification**: 100% pass rate on interoperability suites.
+- **Transports**: Verified E2E over WebSockets, MQTT (IoT), WebRTC (P2P), and gRPC.
+
+## 🧠 Philosophy: "Sound of Silence"
+The goal is **Absolute Purity**:
+- No compiled bindings (no Rust, C++ or FFI).
+- Operates natively in any Python 3.12+ environment.
+- Suitable for zero-friction edge computing and standard backend runtimes.
+- Built on principles of [Plausible Deniability and Zero-Knowledge](docs/00_MANIFESTO.md).
+
+### The Linter Protocol
+We strictly enforce the **"Sound of Silence"** code standard via `ruff` in the `pyproject.toml` file:
+- **Zero-Warning State**: 100% clean status under Ruff's most rigorous rules.
+- Pure Tabulations (`\t`) for minimal character footprint (`W191` allowance).
+- Zero dead code allowed.
+
+## 🗺️ Architecture (Project Map)
+```text
+pure-mls/
+├── README.md               # This file
+├── CHANGELOG.md            # Version history registry
+├── pyproject.toml          # Dependencies (uv) and Sound of Silence config (Ruff)
+├── src/
+│   └── pure_mls/
+│       ├── group.py        # [API] State Machine (MLSGroup)
+│       ├── tree.py         # Nodes and RatchetTree structure
+│       ├── tls.py          # RFC 9420 / TLS 1.3 Wire Format Primitives
+│       ├── extensions.py   # MLS Extensions Framework
+│       ├── proposals.py    # Group Operations (Add, Update, Remove)
+│       ├── epoch.py        # Immutable states (Epochs)
+│       ├── keys.py         # Ed25519 Identities and X25519 KEMs
+│       ├── keyschedule.py  # Secret Derivation (Application_Key)
+│       └── hpke.py         # Hybrid Public Key Encryption Base Mode
+└── tests/
+    ├── test_ietf_vectors.py # 100% RFC 9420 Interop (IETF/OpenMLS)
+    ├── test_group.py       # State Machine unit tests
+    ├── test_e2e_websockets.py # E2E local Websockets
+    ├── test_e2e_mqtt.py    # E2E broker.hivemq.com (IoT)
+    ├── test_e2e_webrtc.py  # E2E Data Channels P2P (aiortc)
+    └── test_e2e_grpc.py    # E2E Backend Swarm (Proto Hub)
+```
+## 📚 Documentation & Guides
+We believe in making cryptography accessible. For a fast, pragmatic, and irreverent introduction to MLS, check our Primate Survival Guide:
+- 🦍 [The Primate Survival Guide to pure-mls (EN)](docs/03_MLS_FOR_PRIMATES_EN.md)
+- 🦍 [Guía del Primate Sobreviviendo a pure-mls (ES)](docs/03_MLS_FOR_PRIMATES_ES.md)
+
+For a deeper dive into the architecture, mathematics, and philosophy of the protocol, explore the Human Journey:
+- 🇺🇸 [The Human Guide to MLS: The Journey (EN)](docs/02_MLS_JOURNEY_EN.md)
+- 🇪🇸 [La Guía Humana de MLS: El Viaje (ES)](docs/02_MLS_JOURNEY_ES.md)
+
+*Contributors: We welcome translations! Feel free to PR your language following the `02_MLS_JOURNEY_XX.md` format.*
+
+## 🔌 API Quickstart
+The central state machine is `MLSGroup`. Install it in your brain:
+
+```python
+from pure_mls.group import MLSGroup
+from pure_mls.keys import SignatureKey, KemKey
+
+# 1. Each participant generates their own persistent identity keys
+alice_sig, alice_kem = SignatureKey(), KemKey()
+bob_sig, bob_kem = SignatureKey(), KemKey()
+
+# 2. Alice initializes the Sovereign Group
+alice_group = MLSGroup.create(b"grupo-soberano", alice_sig, alice_kem)
+
+# 3. Alice receives Bob's `KeyPackage` (his public keys + identity) over the network
+bob_kp = MLSGroup.create_key_package(bob_sig, bob_kem)
+alice_next, welcome, update = alice_group.add_member(bob_kp)
+
+# 4. Bob decrypts the Welcome (sealed with HPKE to his KEM key) and joins
+bob_group = MLSGroup.join(welcome, bob_sig, bob_kem)
+
+# The Underlying Mathematical Truth:
+assert alice_next.application_key == bob_group.application_key
+```
+
+## License
+This project is licensed under the GNU General Public License v3.0 (GPLv3).

pure_mls-3.0.4.0/pyproject.toml

@@ -0,0 +1,66 @@
+[project]
+name = "pure-mls"
+version = "3.0.4.0"
+description = "Pure Python MLS implementation with CLI. Still maturing the application messaging CLI commands."
+readme = "README.md"
+authors = [
+    { name = "Joan F Garcia", email = "joanfgarcia@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "cryptography>=46.0.5",
+]
+
+[project.scripts]
+pure-mls = "pure_mls.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.10.3,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "aiomqtt>=2.5.1",
+    "aiortc>=1.14.0",
+    "amqtt>=0.11.0",
+    "coverage>=7.13.5",
+    "grpcio>=1.78.0",
+    "grpcio-tools>=1.78.0",
+    "mypy>=1.19.1",
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=7.0.0",
+    "ruff>=0.15.6",
+    "websockets>=15.0",
+]
+
+[tool.ruff]
+line-length = 150
+exclude = ["tests/protos/*", ".venv/*"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "ARG", "PLC"]
+ignore = [
+    "W191", # Allow tabs (Sound of Silence protocol)
+    "E501", # Allow long lines
+    "E265", # Allow some comment variants
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["PLC0415", "ARG001", "ARG002"]  # inline imports + fixtures are valid pytest patterns
+"scripts/*" = ["PLC0415"]  # standalone scripts use inline imports intentionally
+"src/pure_mls/keyschedule.py" = ["ARG003"]  # intermediate kept for PSK audit trail
+
+[tool.ruff.format]
+indent-style = "tab"
+quote-style = "double"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+norecursedirs = ["3rdparty", ".venv", "build", "dist"]
+markers = [
+    "network: tests that require internet access to fetch live IETF vectors",
+    "interop: tests that cross-validate with external implementations (e.g. OpenMLS)",
+]
+asyncio_mode = "strict"
+asyncio_default_fixture_loop_scope = "function"

pure_mls-3.0.4.0/src/pure_mls/__init__.py

@@ -0,0 +1,37 @@
+from pure_mls.epoch import EpochState
+from pure_mls.group import (
+	EncryptedGroupSecrets,
+	FramedContent,
+	FramedContentAuthData,
+	GroupContext,
+	GroupSecrets,
+	GroupUpdate,
+	MLSGroup,
+	MLSMessage,
+	PublicMessage,
+	Welcome,
+	WireFormat,
+)
+from pure_mls.tree import KeyPackage, LeafNode, RatchetTree
+
+__all__ = [
+	# Core group management
+	"MLSGroup",
+	"EpochState",
+	"RatchetTree",
+	"KeyPackage",
+	"LeafNode",
+	# RFC 9420 message types
+	"Welcome",
+	"GroupUpdate",
+	"MLSMessage",
+	"WireFormat",
+	# RFC 9420 §6 framing (v1.1)
+	"FramedContent",
+	"FramedContentAuthData",
+	"PublicMessage",
+	# RFC 9420 internal structures
+	"GroupContext",
+	"GroupSecrets",
+	"EncryptedGroupSecrets",
+]

pure_mls-3.0.4.0/src/pure_mls/cli.py

@@ -0,0 +1,102 @@
+import argparse
+
+from cryptography.hazmat.primitives.asymmetric import ed25519, x25519
+
+from pure_mls.group import MLSGroup
+from pure_mls.keys import KemKey, SignatureKey
+from pure_mls.tree import KeyPackage
+
+
+def main() -> None:
+	parser = argparse.ArgumentParser(description="Pure-MLS Command Line Interface", prog="pure-mls")
+	subparsers = parser.add_subparsers(dest="command", help="commands")
+	subparsers.required = True
+
+	# keygen
+	p_keygen = subparsers.add_parser("keygen", help="Generate a new identity and KeyPackage")
+	p_keygen.add_argument("alias", help="Alias for the user (will create <alias>.pub and <alias>.priv)")
+
+	# create-group
+	p_create = subparsers.add_parser("create-group", help="Create a brand new MLS group")
+	p_create.add_argument("group_id", help="Name/ID of the group")
+	p_create.add_argument("founder_priv", help="Path to founder's .priv file")
+	p_create.add_argument("--out", "-o", required=True, help="Path to save the group state (.state)")
+
+	# add-member
+	p_add = subparsers.add_parser("add-member", help="Add a new member to an existing group")
+	p_add.add_argument("group_state", help="Path to the group state (.state)")
+	p_add.add_argument("invitee_pub", help="Path to the invitee's public KeyPackage (.pub)")
+	p_add.add_argument("--out-welcome", "-w", required=True, help="Path to save the Welcome message")
+	p_add.add_argument("--out-state", "-o", help="Overwrites group state by default, unless specified here")
+
+	# join-group
+	p_join = subparsers.add_parser("join-group", help="Join a group from a Welcome message")
+	p_join.add_argument("welcome", help="Path to the Welcome message")
+	p_join.add_argument("my_priv", help="Path to your private keys (.priv)")
+	p_join.add_argument("--out-state", "-o", required=True, help="Path to save your group state (.state)")
+
+	args = parser.parse_args()
+
+	if args.command == "keygen":
+		sig_key = SignatureKey(private_key=ed25519.Ed25519PrivateKey.generate())
+		kem_key = KemKey(private_key=x25519.X25519PrivateKey.generate())
+		kp = KeyPackage.create(
+			encryption_key=kem_key.public_bytes(),
+			init_key_pub=kem_key.public_bytes(),
+			signature_key=sig_key.public_bytes(),
+			identity=args.alias.encode(),
+			sign_fn=sig_key.sign,
+		)
+
+		# Simplistic serialization: 32 bytes sig priv + 32 bytes kem priv + (pubkeys inside KeyPackage)
+		priv_data = sig_key.private_bytes() + kem_key.private_bytes()
+		with open(f"{args.alias}.priv", "wb") as f:
+			f.write(priv_data)
+		with open(f"{args.alias}.pub", "wb") as f:
+			f.write(kp.to_bytes())
+		print(f"Created {args.alias}.priv (KEEP SECRET!) and {args.alias}.pub (Distribute freely)")
+
+	elif args.command == "create-group":
+		with open(args.founder_priv, "rb") as f:
+			pd = f.read()
+		sig_key = SignatureKey.from_private_bytes(pd[:32])
+		kem_key = KemKey.from_private_bytes(pd[32:64])
+
+		group = MLSGroup.create(args.group_id.encode(), sig_key, kem_key)
+		with open(args.out, "wb") as f:
+			f.write(group.to_bytes())
+		print(f"Created group '{args.group_id}' (state saved to {args.out})")
+
+	elif args.command == "add-member":
+		with open(args.group_state, "rb") as f:
+			group = MLSGroup.from_bytes(f.read())
+		with open(args.invitee_pub, "rb") as f:
+			kp, _ = KeyPackage.from_bytes_at(f.read())
+
+		new_group, welcome, commit = group.add_member(kp)
+
+		out_state = args.out_state if args.out_state else args.group_state
+		with open(out_state, "wb") as f:
+			f.write(new_group.to_bytes())
+		with open(args.out_welcome, "wb") as f:
+			f.write(welcome.to_bytes())
+		print(f"Added member! State updated at {out_state}. Distribute {args.out_welcome} to the new member.")
+
+	elif args.command == "join-group":
+		with open(args.my_priv, "rb") as f:
+			pd = f.read()
+		sig_key = SignatureKey.from_private_bytes(pd[:32])
+		kem_key = KemKey.from_private_bytes(pd[32:64])
+
+		with open(args.welcome, "rb") as f:
+			welcome_data = f.read()
+
+		group = MLSGroup.join(welcome_data, sig_key, kem_key)
+		with open(args.out_state, "wb") as f:
+			f.write(group.to_bytes())
+		gid = group.state.group_id.decode(errors="replace")
+		print(f"Successfully joined group '{gid}'! State saved to {args.out_state}")
+
+
+if __name__ == "__main__":
+	main()

pure_mls-3.0.4.0/src/pure_mls/crypto.py

@@ -0,0 +1,54 @@
+import hashlib
+
+from pure_mls.tls import tls_opaque, tls_opaque_varint
+from pure_mls.tree import LeafNode, ParentNode, RatchetTree
+
+
+def _make_hpke_info(label: str, context: bytes) -> bytes:
+	"""RFC 9420 §4.5: HPKE info = HPKELabel{label, context} (omitting length per common interop)."""
+	full_label = b"MLS 1.0 " + label.encode("ascii")
+	return tls_opaque_varint(full_label) + tls_opaque_varint(context)
+
+
+def _egs_info(egi: bytes) -> bytes:
+	"""RFC 9420 §12.4.2: HPKE info for EncryptedGroupSecrets."""
+	return _make_hpke_info("Welcome", egi)
+
+
+def _up_info(group_ctx: bytes) -> bytes:
+	"""RFC 9420 §5.1.3: HPKE info for UpdatePathNode."""
+	return _make_hpke_info("UpdatePathNode", group_ctx)
+
+
+def _subtree_hash(tree: "RatchetTree", index: int) -> bytes:
+	"""RFC 9420 §7.8: recursive subtree hash for parent_hash computation."""
+	if index < 0 or index >= len(tree.nodes):
+		return hashlib.sha256(b"").digest()
+	node = tree.get_node(index)
+	if index % 2 == 0:  # leaf
+		if node is None:
+			return hashlib.sha256(b"\x01\x00").digest()
+		assert isinstance(node, LeafNode)
+		return hashlib.sha256(b"\x01\x01" + node.to_bytes()).digest()
+
+	lvl = tree.level(index)
+	child_dist = 1 << (lvl - 1)
+	left = index - child_dist
+	right = index + child_dist
+	left_hash = _subtree_hash(tree, left)
+	right_hash = _subtree_hash(tree, right)
+
+	if node is None:
+		return hashlib.sha256(b"\x02\x00" + tls_opaque_varint(left_hash) + tls_opaque_varint(right_hash)).digest()
+
+	assert isinstance(node, ParentNode)
+	return hashlib.sha256(b"\x02\x01" + node.to_bytes() + tls_opaque_varint(left_hash) + tls_opaque_varint(right_hash)).digest()
+
+
+def _compute_parent_hash(new_public_key: bytes, parent_hash_of_parent: bytes, original_sibling_tree_hash: bytes) -> bytes:
+	"""RFC 9420 §7.9: parent_hash = SHA-256(label + ParentHashInput)."""
+	label = b"MLS 1.0 parent hash"
+
+	return hashlib.sha256(
+		tls_opaque(label) + tls_opaque(new_public_key) + tls_opaque(parent_hash_of_parent) + tls_opaque(original_sibling_tree_hash)
+	).digest()

pure_mls-3.0.4.0/src/pure_mls/epoch.py

@@ -0,0 +1,99 @@
+import copy
+from dataclasses import dataclass
+
+from pure_mls.keyschedule import KeySchedule, PreSharedKeyID
+from pure_mls.tree import RatchetTree
+
+
+@dataclass(frozen=True)
+class EpochState:
+	"""
+	The absolute definition of the Group State at any point in time.
+	If two disconnected nodes have mathematically identical EpochStates,
+	they are cryptographically synchronized.
+	"""
+
+	group_id: bytes
+	epoch_id: int
+	tree: RatchetTree
+	key_schedule: KeySchedule
+
+	def __post_init__(self) -> None:
+		# Prevent mutation of the RatchetTree through the immutable EpochState
+
+		cloned = copy.deepcopy(self.tree)
+		cloned.freeze()  # STATE-03: enforce immutability after deepcopy
+		super().__setattr__("tree", cloned)
+
+	def advance_epoch(
+		self,
+		commit_secret: bytes,
+		next_tree: RatchetTree,
+		group_context: bytes = b"",
+		psk_list: list[tuple[PreSharedKeyID, bytes]] | None = None,
+	) -> "EpochState":
+		"""Transitions the group to the next cryptographic era."""
+		next_schedule = KeySchedule.derive(
+			init_secret=self.key_schedule.init_secret,
+			commit_secret=commit_secret,
+			group_context=group_context,
+			psk_list=psk_list,
+		)
+		return EpochState(group_id=self.group_id, epoch_id=self.epoch_id + 1, tree=next_tree, key_schedule=next_schedule)
+
+	@classmethod
+	def genesis(
+		cls,
+		group_id: bytes,
+		creator_tree: RatchetTree,
+		group_context_bytes: bytes = b"",
+	) -> "EpochState":
+		"""Bootstraps Epoch 0 for a brand new sovereign group.
+
+		RFC 9420 §8.1: epoch 0 init_secret is the all-zeros vector.
+
+		group_context_bytes MUST be the TLS-serialised GroupContext for epoch 0
+		(group_id, epoch=0, tree_hash, confirmed_transcript_hash=b\"\").
+		Passing b\"\" (default) skips domain separation — use only in tests that
+		explicitly target the genesis-only code path without a full group context.
+
+		The caller (group.py) constructs the GroupContext and passes it here to
+		avoid a circular import: epoch.py → group.py → epoch.py.
+		"""
+		genesis_init = b"\x00" * 32  # RFC 9420 §8.1: epoch 0 init_secret = zeros
+		blank_commit = b"\x00" * 32
+
+		return cls(
+			group_id=group_id,
+			epoch_id=0,
+			tree=creator_tree,
+			key_schedule=KeySchedule.derive(genesis_init, blank_commit, group_context=group_context_bytes),
+		)
+
+	def to_bytes(self) -> bytes:
+		"""Full EpochState binary dump for persistence."""
+		tree_bytes = self.tree.to_bytes()
+		return (
+			len(self.group_id).to_bytes(2, "big")
+			+ self.group_id
+			+ self.epoch_id.to_bytes(8, "big")
+			+ len(tree_bytes).to_bytes(4, "big")
+			+ tree_bytes
+			+ self.key_schedule.to_bytes()
+		)
+
+	@classmethod
+	def from_bytes(cls, data: bytes) -> "EpochState":
+		offset = 0
+		gid_len = int.from_bytes(data[offset : offset + 2], "big")
+		offset += 2
+		gid = data[offset : offset + gid_len]
+		offset += gid_len
+		eid = int.from_bytes(data[offset : offset + 8], "big")
+		offset += 8
+		t_len = int.from_bytes(data[offset : offset + 4], "big")
+		offset += 4
+		tree = RatchetTree.from_bytes(data[offset : offset + t_len])
+		offset += t_len
+		ks = KeySchedule.from_bytes(data[offset : offset + KeySchedule.SIZE])
+		return cls(group_id=gid, epoch_id=eid, tree=tree, key_schedule=ks)

pure_mls-3.0.4.0/src/pure_mls/extensions.py

@@ -0,0 +1,140 @@
+"""RFC 9420 §13.4 Extensions Framework.
+
+Extensions are used to provide additional information in various MLS structures:
+- KeyPackage (§7)
+- LeafNode (§7.2)
+- GroupContext (§12.1)
+- Welcome (§12.4.3)
+"""
+
+from dataclasses import dataclass, field
+from typing import List
+
+from pure_mls.tls import (
+	_varint_decode as tls_varint_decode,
+)
+from pure_mls.tls import (
+	read_extensions,
+	read_opaque,
+	read_u8,
+	tls_extensions,
+	tls_opaque,
+	tls_u8,
+	tls_u16,
+	tls_varint,
+)
+
+
+@dataclass
+class Capabilities:
+	"""RFC 9420 §7.2: Capabilities of a client or group.
+
+	Fields are vectors (<V>) with VarInt length prefixes, as per OpenMLS interop.
+	"""
+
+	versions: List[int] = field(default_factory=lambda: [1])  # MLS 1.0 (u16 elements)
+	ciphersuites: List[int] = field(default_factory=lambda: [0x0001])
+	extensions: List[int] = field(default_factory=lambda: [1, 2, 4])  # Cap, Tree, ExtPSK
+	proposals: List[int] = field(default_factory=lambda: [1, 2, 3])  # Add, Update, Remove
+	credentials: List[int] = field(default_factory=lambda: [1])  # Basic
+
+	@classmethod
+	def default(cls) -> "Capabilities":
+		"""Returns default capabilities for MLS 1.0."""
+		return cls()
+
+	def marshal(self) -> bytes:
+		"""Standard MLS serialization using VarInt prefixes."""
+		res = b""
+
+		def tls_vec_varint(vals: List[int]) -> bytes:
+			body = b"".join(tls_u16(v) for v in vals)
+			return tls_varint(len(body)) + body
+
+		res += tls_vec_varint(self.versions)
+		res += tls_vec_varint(self.ciphersuites)
+		res += tls_vec_varint(self.extensions)
+		res += tls_vec_varint(self.proposals)
+		res += tls_vec_varint(self.credentials)
+		return res
+
+	@classmethod
+	def from_bytes_at(cls, data: bytes, offset: int = 0) -> tuple["Capabilities", int]:
+		"""Context-aware parsing matching OpenMLS wire format."""
+
+		def read_varint_vec(buf: bytes, off: int) -> tuple[List[int], int]:
+			length, off = tls_varint_decode(buf, off)
+			raw = buf[off : off + length]
+			# Elements are uint16 as per RFC 9420 Appendix B and OpenMLS impl
+			values = [int.from_bytes(raw[i : i + 2], "big") for i in range(0, len(raw), 2)]
+			return values, off + length
+
+		# In pure_mls.tls, _varint_decode is the partner to tls_varint
+
+		versions, offset = read_varint_vec(data, offset)
+		ciphersuites, offset = read_varint_vec(data, offset)
+		extensions, offset = read_varint_vec(data, offset)
+		proposals, offset = read_varint_vec(data, offset)
+		credentials, offset = read_varint_vec(data, offset)
+		return cls(versions, ciphersuites, extensions, proposals, credentials), offset
+
+	@classmethod
+	def unmarshal(cls, data: bytes) -> "Capabilities":
+		obj, _ = cls.from_bytes_at(data, 0)
+		return obj
+
+
+@dataclass
+class RatchetTreeExtension:
+	"""RFC 9420 §12.4.3.3: Provides the full ratchet tree state."""
+
+	tree_data: bytes  # vec<optional<Node>> in serialized form
+
+	def marshal(self) -> bytes:
+		return self.tree_data
+
+	@classmethod
+	def unmarshal(cls, data: bytes) -> "RatchetTreeExtension":
+		return cls(tree_data=data)
+
+
+@dataclass
+class ExternalPSKExtension:
+	"""RFC 9420 §12.4.3.4: Preshared Key ID for external PSK usage."""
+
+	psk_id: bytes
+	psk_nonce: bytes
+
+	def marshal(self) -> bytes:
+		# PreSharedKeyID psk_id;
+		# struct { psk_type=external, psk_id<V>, psk_nonce<V> }
+		res = tls_u8(1)  # external=1
+		res += tls_opaque(self.psk_id)
+		res += tls_opaque(self.psk_nonce)
+		return res
+
+	@classmethod
+	def unmarshal(cls, data: bytes) -> "ExternalPSKExtension":
+		offset = 0
+		psk_type, offset = read_u8(data, offset)
+		if psk_type != 1:
+			raise ValueError(f"Unsupported PSK type: {psk_type}")
+		psk_id, offset = read_opaque(data, offset)
+		psk_nonce, offset = read_opaque(data, offset)
+		return cls(psk_id, psk_nonce)
+
+
+@dataclass
+class GroupContextExtensions:
+	"""RFC 9420 §12.1.7: Extensions applied to the GroupContext."""
+
+	extensions: List[tuple[int, bytes]] = field(default_factory=list)
+
+	def marshal(self) -> bytes:
+		# RFC 9420 §12.1.1: Extension extensions<V>;
+		return tls_extensions(self.extensions)
+
+	@classmethod
+	def unmarshal(cls, data: bytes) -> "GroupContextExtensions":
+		exts, _ = read_extensions(data, 0)
+		return cls(extensions=exts)