fleetmesh-node 0.2.0__py3-none-any.whl

node/protocols/atproto/firehose.py

@@ -0,0 +1,126 @@
+"""AT Protocol Firehose WebSocket stream (`com.atproto.sync.subscribeRepos`).
+
+Standard library only. Manages:
+- Event Stream binary framing: back-to-back DAG-CBOR (Header + Body).
+- Monotonic sequence numbering and subscribers.
+- Frame encoder and decoder for commit and error events.
+- WebSocket subscription lifecycle.
+"""
+from __future__ import annotations
+
+import datetime
+from typing import Any, Mapping, Optional, Sequence
+
+from fleetmesh_core.conformance.errors import FleetmeshError
+from fleetmesh_core.identity.cid import CIDLink
+from fleetmesh_core.wire.cbor import cbor_decode, dag_cbor_encode
+
+__all__ = [
+    'FirehoseError',
+    'encode_firehose_frame',
+    'decode_firehose_frame',
+    'FirehoseBroadcaster',
+]
+
+
+class FirehoseError(FleetmeshError):
+    """Base error for Firehose event stream operations."""
+
+
+def encode_firehose_frame(header: Mapping[str, Any], body: Mapping[str, Any]) -> bytes:
+    """Encode an ATProto event stream frame into two concatenated DAG-CBOR objects."""
+    hdr_bytes = dag_cbor_encode(header)
+    body_bytes = dag_cbor_encode(body)
+    return hdr_bytes + body_bytes
+
+
+def decode_firehose_frame(data: bytes) -> tuple[Mapping[str, Any], Mapping[str, Any]]:
+    """Decode an ATProto event stream frame into (header, body)."""
+    if not data:
+        raise FirehoseError("empty firehose frame")
+    hdr, consumed = cbor_decode(data)
+    if not isinstance(hdr, dict):
+        raise FirehoseError(f"invalid firehose frame header: {type(hdr)}")
+    body, consumed_body = cbor_decode(data[consumed:])
+    if not isinstance(body, dict):
+        raise FirehoseError(f"invalid firehose frame body: {type(body)}")
+    if consumed + consumed_body != len(data):
+        raise FirehoseError(f"unconsumed trailing bytes in firehose frame: {len(data) - (consumed + consumed_body)}")
+    return hdr, body
+
+
+class FirehoseBroadcaster:
+    """Maintains active subscribers and broadcasts commit frames."""
+
+    def __init__(self, initial_seq: int = 1):
+        self._seq = initial_seq
+        self._subscribers: set[Any] = set()
+
+    @property
+    def current_seq(self) -> int:
+        return self._seq
+
+    @property
+    def subscriber_count(self) -> int:
+        return len(self._subscribers)
+
+    def subscribe(self, subscriber: Any, cursor: Optional[int] = None) -> None:
+        """Register a subscriber (e.g. WebSocket connection object)."""
+        self._subscribers.add(subscriber)
+
+    def unsubscribe(self, subscriber: Any) -> None:
+        """Remove a subscriber."""
+        self._subscribers.discard(subscriber)
+
+    def broadcast_commit(
+        self,
+        repo_did: str,
+        commit_cid: CIDLink,
+        prev_cid: Optional[CIDLink],
+        rev: str,
+        ops: Sequence[Mapping[str, Any]],
+        blocks: bytes = b"",
+        since: Optional[str] = None,
+    ) -> tuple[int, bytes]:
+        """Format and broadcast a #commit frame to all subscribers.
+
+        Returns (seq_number, frame_bytes).
+        """
+        seq = self._seq
+        self._seq += 1
+
+        now_iso = datetime.datetime.now(datetime.timezone.utc).strftime('%Y-%m-%dT%H:%M:%S.%fZ')
+        header = {'op': 1, 't': '#commit'}
+        body = {
+            'seq': seq,
+            'rebase': False,
+            'tooBig': False,
+            'repo': repo_did,
+            'commit': commit_cid,
+            'prev': prev_cid,
+            'rev': rev,
+            'since': since,
+            'blocks': blocks,
+            'ops': ops,
+            'time': now_iso,
+        }
+
+        frame = encode_firehose_frame(header, body)
+
+        # Broadcast to active subscribers
+        dead_subs = []
+        for sub in self._subscribers:
+            try:
+                if hasattr(sub, 'send_bytes'):
+                    sub.send_bytes(frame)
+                elif hasattr(sub, 'send_binary'):
+                    sub.send_binary(frame)
+                elif callable(sub):
+                    sub(frame)
+            except Exception:
+                dead_subs.append(sub)
+
+        for dead in dead_subs:
+            self._subscribers.discard(dead)
+
+        return seq, frame

node/protocols/atproto/metering.py

@@ -0,0 +1,165 @@
+"""Bilateral budgeting, rate limiting, and Cashu NUT-24 paid fetch for ATProto.
+
+Standard library only. Manages:
+- Token-bucket rate limiting per client IP or authenticated DID.
+- Cashu NUT-18 / NUT-24 402 Payment Required challenges for heavy sync requests
+  (getRepo, getBlob, subscribeRepos).
+- Token deposit parsing and validation via fleetmesh_core.accounting.cashu.
+- Bilateral peering capacity tracking between federating nodes.
+"""
+from __future__ import annotations
+
+import time
+from typing import Mapping, Optional
+
+from fleetmesh_core.accounting import cashu
+from fleetmesh_core.conformance.errors import FleetmeshError
+
+__all__ = [
+    'MeteringError',
+    'TokenBucket',
+    'AtprotoMetering',
+]
+
+
+class MeteringError(FleetmeshError):
+    """Base error for ATProto metering and payment checks."""
+
+
+class TokenBucket:
+    """Standard token-bucket rate limiter."""
+
+    __slots__ = ('capacity', 'refill_rate', 'tokens', 'last_refill')
+
+    def __init__(self, capacity: float, refill_rate: float):
+        self.capacity = float(capacity)
+        self.refill_rate = float(refill_rate)
+        self.tokens = float(capacity)
+        self.last_refill = time.time()
+
+    def consume(self, amount: float = 1.0) -> bool:
+        """Attempt to consume tokens. Returns True if allowed, False if dry."""
+        now = time.time()
+        elapsed = now - self.last_refill
+        self.last_refill = now
+        self.tokens = min(self.capacity, self.tokens + elapsed * self.refill_rate)
+
+        if self.tokens >= amount:
+            self.tokens -= amount
+            return True
+        return False
+
+
+class AtprotoMetering:
+    """Enforces rate limits and ecash settlement over XRPC and Firehose edges."""
+
+    def __init__(
+        self,
+        rate_limit_per_minute: int = 60,
+        burst: int = 15,
+        price_per_fetch_sat: int = 1,
+        mint_url: str = "https://mint.example.org",
+        require_payment: bool = False,
+    ):
+        self.rate_limit_per_minute = rate_limit_per_minute
+        self.burst = burst
+        self.price_per_fetch_sat = price_per_fetch_sat
+        self.mint_url = mint_url.rstrip('/')
+        self.require_payment = require_payment
+
+        self._buckets: dict[str, TokenBucket] = {}
+        self._balances_sat: dict[str, int] = {}
+        self._paid_endpoints: set[str] = {
+            'com.atproto.sync.getRepo',
+            'com.atproto.sync.getBlob',
+            'com.atproto.sync.subscribeRepos',
+        }
+
+    def _get_bucket(self, client_id: str) -> TokenBucket:
+        if client_id not in self._buckets:
+            refill_per_sec = self.rate_limit_per_minute / 60.0
+            self._buckets[client_id] = TokenBucket(capacity=self.burst, refill_rate=refill_per_sec)
+        return self._buckets[client_id]
+
+    def deposit_cashu_token(self, client_id: str, token_str: str) -> int:
+        """Parse and credit a Cashu V3 (cashuA) or V4 (cashuB) token to client's balance."""
+        token_str = token_str.strip()
+        total_sat = 0
+        if token_str.startswith(cashu.TOKEN_V4_PREFIX):
+            try:
+                tok = cashu.decode_token_v4(token_str)
+                total_sat = sum(p.get('amount', 0) for p in tok.get('proofs', []))
+            except Exception as e:
+                raise MeteringError(f"invalid Cashu V4 token: {e}") from e
+        elif token_str.startswith('cashuA'):
+            try:
+                import base64
+                import json
+                raw_json = base64.urlsafe_b64decode(token_str[6:] + '==').decode('utf-8')
+                tok = json.loads(raw_json)
+                for entry in tok.get('token', []):
+                    for p in entry.get('proofs', []):
+                        total_sat += p.get('amount', 0)
+            except Exception as e:
+                raise MeteringError(f"invalid Cashu V3 token: {e}") from e
+        else:
+            raise MeteringError("unsupported Cashu token format")
+
+        if total_sat <= 0:
+            raise MeteringError("token carries zero satoshis")
+
+        self._balances_sat[client_id] = self._balances_sat.get(client_id, 0) + total_sat
+        return total_sat
+
+
+    def get_balance(self, client_id: str) -> int:
+        """Return the current satoshi balance for a client."""
+        return self._balances_sat.get(client_id, 0)
+
+    def check_request(
+        self,
+        client_id: str,
+        nsid: str,
+        headers: Mapping[str, str],
+    ) -> tuple[bool, int, dict[str, str], Optional[bytes]]:
+        """Evaluate rate limits and payment requirements for an incoming request.
+
+        Returns (allowed, status_code, response_headers, response_body).
+        """
+        # 1. Process in-band ecash payment header if present (X-Cashu or Authorization)
+        token_header = headers.get('x-cashu') or headers.get('X-Cashu')
+        if not token_header and 'authorization' in headers:
+            auth_val = headers['authorization']
+            if auth_val.startswith('Bearer cashu'):
+                token_header = auth_val[len('Bearer '):].strip()
+
+        if token_header:
+            try:
+                self.deposit_cashu_token(client_id, token_header)
+            except Exception:
+                pass
+
+        # 2. Token-bucket rate limiting check
+        bucket = self._get_bucket(client_id)
+        if not bucket.consume(1.0):
+            body = b'{"error":"RateLimitExceeded","message":"Too many requests"}'
+            return False, 429, {'Retry-After': '10', 'Content-Type': 'application/json'}, body
+
+        # 3. Paid fetch check for designated endpoints
+        if self.require_payment and nsid in self._paid_endpoints:
+            current_bal = self.get_balance(client_id)
+            if current_bal >= self.price_per_fetch_sat:
+                # Deduct payment
+                self._balances_sat[client_id] = current_bal - self.price_per_fetch_sat
+                return True, 200, {}, None
+
+            # Insufficient funds: produce HTTP 402 challenge
+            pay_req = f"creqA_{self.mint_url}_{self.price_per_fetch_sat}sat"
+            resp_hdrs = {
+                'X-Cashu': pay_req,
+                'Content-Type': 'application/json',
+            }
+            body = b'{"error":"PaymentRequired","message":"Resource requires Cashu ecash payment"}'
+            return False, 402, resp_hdrs, body
+
+        return True, 200, {}, None

node/protocols/atproto/package.py

@@ -0,0 +1,155 @@
+"""fleetmesh-protocol-atproto: Decoupled AT Protocol & XRPC package.
+
+Conforms to ProtocolPackage (fleetmesh_core.wire.interfaces.ProtocolPackage).
+Wraps XRPCRouter, FirehoseBroadcaster, and RepoManager, mounting them
+onto ProtocolHostRouter with zero external dependencies.
+"""
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+
+from fleetmesh_core.identity.atproto import AtprotoIdentityAdapter
+from fleetmesh_core.wire.interfaces import (
+    ProtocolHealth,
+    ProtocolHostRouter,
+    ProtocolIdentityAdapter,
+)
+from .firehose import FirehoseBroadcaster
+from .repo import Repo
+from .xrpc import XRPCRouter
+
+__all__ = [
+    'AtprotoProtocolPackage',
+]
+
+
+class AtprotoProtocolPackage:
+    """The AT Protocol (atproto) suite for Fleetmesh."""
+
+    name: str = 'atproto'
+    version: str = '1.0.0'
+    standards: tuple[str, ...] = (
+        'com.atproto.sync',
+        'com.atproto.repo',
+        'com.atproto.server',
+        'did:plc',
+        'did:web',
+        'dag-cbor',
+        'mst',
+    )
+
+    def __init__(
+        self,
+        repo: Optional[Repo] = None,
+        keystore: Optional[Any] = None,
+        service_domain: str = "node.fleetmesh.local",
+        firehose: Optional[FirehoseBroadcaster] = None,
+        blob_store: Optional[Any] = None,
+    ):
+        self.repo = repo
+        self.keystore = keystore
+        self.service_domain = service_domain
+        self.firehose = firehose or FirehoseBroadcaster()
+        self.blob_store = blob_store
+        self.config: Mapping[str, Any] = {}
+        self._enabled: bool = True
+        self._host: Optional[ProtocolHostRouter] = None
+        self.xrpc_router: Optional[XRPCRouter] = None
+
+    def configure(self, config: Mapping[str, Any]) -> None:
+        self.config = dict(config)
+        self._enabled = self.config.get('enabled', True)
+        if 'service_domain' in self.config:
+            self.service_domain = self.config['service_domain']
+
+    def identity_adapter(self, keystore: Any) -> Optional[ProtocolIdentityAdapter]:
+        ks = keystore or self.keystore
+        if ks is None:
+            return None
+        did_val = self.repo.did if self.repo else None
+        return AtprotoIdentityAdapter(keystore=ks, handle=self.service_domain, did=did_val)
+
+    def mount_ingress(self, host: ProtocolHostRouter) -> None:
+        if not self._enabled:
+            return
+        self._host = host
+
+        if self.xrpc_router is None:
+            self.xrpc_router = XRPCRouter(repo=self.repo, service_domain=self.service_domain)
+        router = self.xrpc_router
+
+        # 1. XRPC HTTP endpoints under /xrpc
+        def _handle_xrpc_http(conn: Any, req: Any) -> bool:
+            from node.transport import ws
+            method = getattr(req, 'method', 'GET')
+            path = getattr(req, 'path', '')
+            body = getattr(req, 'body', None)
+            if body is None:
+                body = ws.read_body(conn, req)
+            status, headers, resp_body = router.handle_request(method, path, body)
+            ws.http_response(
+                conn,
+                f"{status} OK" if status == 200 else f"{status} Error",
+                resp_body,
+                headers.get('Content-Type', 'application/json'),
+            )
+            return True
+
+        host.mount_route('/xrpc', _handle_xrpc_http, methods=('GET', 'POST'), owner=self.name)
+
+        # 2. Firehose WebSocket under /xrpc/com.atproto.sync.subscribeRepos
+        def _handle_firehose_ws(ws_conn: Any, path: str) -> None:
+            self.firehose.subscribe(ws_conn)
+
+        host.mount_websocket('/xrpc/com.atproto.sync.subscribeRepos', _handle_firehose_ws, owner=self.name)
+
+        # 3. Well-known DID endpoint
+        def _handle_well_known_did(conn: Any, req: Any) -> bool:
+            did_str = self.repo.did if self.repo else f"did:web:{self.service_domain}"
+            from node.transport import ws
+            ws.http_response(conn, "200 OK", did_str.encode('utf-8'), 'text/plain')
+            return True
+
+        host.mount_route('/.well-known/atproto-did', _handle_well_known_did, methods=('GET',), owner=self.name)
+
+
+    def transport_rung(self, context: Any) -> Optional[Any]:
+        # ATProto does not operate as a direct transport ladder rung for DIDComm/Nostr
+        return None
+
+    def compartments(self) -> tuple[type[Any], ...]:
+        return ()
+
+    def start(self) -> None:
+        pass
+
+    def stop(self) -> None:
+        pass
+
+    def health(self) -> ProtocolHealth:
+        if not self._enabled:
+            return ProtocolHealth(
+                healthy=True,
+                status="disabled",
+                connections_active=0,
+                messages_in=0,
+                messages_out=0,
+                errors=(),
+            )
+        subs = self.firehose.subscriber_count
+        return ProtocolHealth(
+            healthy=True,
+            status="serving",
+            connections_active=subs,
+            messages_in=0,
+            messages_out=self.firehose.current_seq - 1,
+            errors=(),
+        )
+
+    def descriptor_capabilities(self) -> tuple[tuple[str, str], ...]:
+        if not self._enabled:
+            return ()
+        caps = [('c', 'atproto'), ('c', 'xrpc')]
+        if self.firehose is not None:
+            caps.append(('c', 'firehose'))
+        return tuple(caps)

node/protocols/atproto/repo.py

@@ -0,0 +1,250 @@
+"""AT Protocol Repository implementation.
+
+Standard library only. Manages:
+- Commit chain (version 3) signed with secp256k1 ECDSA.
+- Monotonic Timestamp Identifiers (TID) per ATProto specification.
+- Merkle Search Tree (MST) record index.
+- CAR v1 archive export and import.
+- Content-addressed blob storage unified with Blossom BlobStore.
+"""
+from __future__ import annotations
+
+import random
+import time
+from typing import Any, Mapping, Optional, Union
+
+from fleetmesh_core.conformance.errors import FleetmeshError
+from fleetmesh_core.identity.atproto import ecdsa_sign
+from fleetmesh_core.identity.cid import CIDLink, cid_to_sha256
+from fleetmesh_core.storage.car import read_car, write_car
+from fleetmesh_core.storage.mst import MST
+from fleetmesh_core.wire.cbor import dag_cbor_decode, dag_cbor_encode
+
+__all__ = [
+    'RepoError',
+    'tid_now',
+    'Repo',
+]
+
+_TID_ALPHABET = '234567abcdefghijklmnopqrstuvwxyz'
+_CLOCK_ID = random.randint(0, 1023)
+_LAST_TID_MICROS = 0
+
+
+class RepoError(FleetmeshError):
+    """Base error for ATProto repository operations."""
+
+
+def tid_now() -> str:
+    """Generate a monotonic 13-character Crockford Base32 TID."""
+    global _LAST_TID_MICROS
+    micros = int(time.time() * 1_000_000)
+    if micros <= _LAST_TID_MICROS:
+        micros = _LAST_TID_MICROS + 1
+    _LAST_TID_MICROS = micros
+
+    val = (micros << 10) | (_CLOCK_ID & 0x3ff)
+    chars = []
+    for _ in range(13):
+        chars.append(_TID_ALPHABET[val & 0x1f])
+        val >>= 5
+    return ''.join(reversed(chars))
+
+
+class Repo:
+    """An ATProto account repository."""
+
+    def __init__(
+        self,
+        did: str,
+        signing_key_hex: Optional[str] = None,
+        blockstore: Optional[dict[CIDLink, bytes]] = None,
+        blob_store: Optional[Any] = None,
+    ):
+        self.did = did
+        self.signing_key_hex = signing_key_hex
+        self.blockstore = blockstore if blockstore is not None else {}
+        self.blob_store = blob_store
+        self.head_commit_cid: Optional[CIDLink] = None
+        self.mst = MST(blockstore=self.blockstore)
+
+    @classmethod
+    def create(
+        cls,
+        did: str,
+        signing_key_hex: str,
+        blockstore: Optional[dict[CIDLink, bytes]] = None,
+        blob_store: Optional[Any] = None,
+    ) -> Repo:
+        """Initialize a new, empty repository with an initial genesis commit."""
+        repo = cls(did=did, signing_key_hex=signing_key_hex, blockstore=blockstore, blob_store=blob_store)
+        repo._create_commit(prev=None)
+        return repo
+
+    def _create_commit(self, prev: Optional[CIDLink]) -> CIDLink:
+        """Generate and sign a new repository commit."""
+        rev = tid_now()
+        mst_root = self.mst.root_cid
+
+        unsigned_commit = {
+            'did': self.did,
+            'version': 3,
+            'data': mst_root,
+            'rev': rev,
+            'prev': prev,
+        }
+        commit_bytes = dag_cbor_encode(unsigned_commit)
+
+        if self.signing_key_hex is not None:
+            sig = ecdsa_sign(commit_bytes, self.signing_key_hex)
+        else:
+            sig = bytes(64)
+
+        signed_commit = {
+            'did': self.did,
+            'version': 3,
+            'data': mst_root,
+            'rev': rev,
+            'prev': prev,
+            'sig': sig,
+        }
+        signed_bytes = dag_cbor_encode(signed_commit)
+        commit_cid = CIDLink.from_dag_cbor(signed_bytes)
+        self.blockstore[commit_cid] = signed_bytes
+        self.head_commit_cid = commit_cid
+        return commit_cid
+
+    def put_record(
+        self,
+        collection: str,
+        record: Mapping[str, Any],
+        rkey: Optional[str] = None,
+    ) -> tuple[str, CIDLink, CIDLink]:
+        """Insert or update a record in this repository.
+
+        Returns (rkey, record_cid, new_commit_cid).
+        """
+        if not rkey:
+            rkey = tid_now()
+
+        key = f"{collection}/{rkey}"
+        rec_bytes = dag_cbor_encode(record)
+        rec_cid = CIDLink.from_dag_cbor(rec_bytes)
+        self.blockstore[rec_cid] = rec_bytes
+
+        self.mst.put(key, rec_cid)
+        commit_cid = self._create_commit(prev=self.head_commit_cid)
+        return rkey, rec_cid, commit_cid
+
+    def get_record(self, collection: str, rkey: str) -> Optional[tuple[CIDLink, Mapping[str, Any]]]:
+        """Fetch a record from the repository by collection and rkey."""
+        key = f"{collection}/{rkey}"
+        cid = self.mst.get(key)
+        if cid is None:
+            return None
+        if cid not in self.blockstore:
+            raise RepoError(f"missing record block: {cid}")
+        data = dag_cbor_decode(self.blockstore[cid])
+        return cid, data
+
+    def delete_record(self, collection: str, rkey: str) -> CIDLink:
+        """Remove a record and commit the updated MST. Returns new commit CID."""
+        key = f"{collection}/{rkey}"
+        self.mst.delete(key)
+        return self._create_commit(prev=self.head_commit_cid)
+
+    def list_records(
+        self,
+        collection: str = "",
+    ) -> list[tuple[str, str, CIDLink, Mapping[str, Any]]]:
+        """List all records in the repository, optionally filtered by collection.
+
+        Returns list of (collection, rkey, cid, record_dict).
+        """
+        prefix = f"{collection}/" if collection else ""
+        items = self.mst.items(prefix=prefix)
+        out: list[tuple[str, str, CIDLink, Mapping[str, Any]]] = []
+        for key, cid in items:
+            parts = key.split('/', 1)
+            col = parts[0]
+            rk = parts[1] if len(parts) > 1 else ""
+            if cid in self.blockstore:
+                try:
+                    doc = dag_cbor_decode(self.blockstore[cid])
+                    out.append((col, rk, cid, doc))
+                except Exception:
+                    continue
+        return out
+
+    def put_blob(self, data: bytes, mime_type: str = "application/octet-stream") -> Mapping[str, Any]:
+        """Store a binary blob, utilizing Blossom BlobStore if attached.
+
+        Returns standard ATProto blob JSON descriptor with $link CID.
+        """
+        cid = CIDLink.from_raw_blob(data)
+        self.blockstore[cid] = data
+
+        if self.blob_store is not None:
+            try:
+                # If Blossom BlobStore is attached, store directly
+                if hasattr(self.blob_store, 'put'):
+                    self.blob_store.put(data)
+            except Exception:
+                pass
+
+        return {
+            '$type': 'blob',
+            'ref': {'$link': cid.cid_str},
+            'mimeType': mime_type,
+            'size': len(data),
+        }
+
+    def get_blob(self, cid_or_str: Union[str, CIDLink]) -> Optional[bytes]:
+        """Retrieve binary blob data."""
+        cid = cid_or_str if isinstance(cid_or_str, CIDLink) else CIDLink.from_str(cid_or_str)
+        if cid in self.blockstore:
+            return self.blockstore[cid]
+
+        if self.blob_store is not None:
+            try:
+                sha256_hex = cid_to_sha256(cid.cid_str)
+                if hasattr(self.blob_store, 'get'):
+                    return self.blob_store.get(sha256_hex)
+            except Exception:
+                pass
+        return None
+
+    def export_car(self) -> bytes:
+        """Export the entire repository state into a CAR v1 archive."""
+        if self.head_commit_cid is None:
+            raise RepoError("cannot export repository with no commits")
+        return write_car(self.head_commit_cid, self.blockstore)
+
+    @classmethod
+    def from_car(
+        cls,
+        car_bytes: bytes,
+        signing_key_hex: Optional[str] = None,
+        blob_store: Optional[Any] = None,
+    ) -> Repo:
+        """Reconstruct a repository from a CAR v1 archive."""
+        roots, blocks = read_car(car_bytes)
+        if not roots:
+            raise RepoError("CAR archive has no roots")
+        head_cid = roots[0]
+        if head_cid not in blocks:
+            raise RepoError(f"CAR archive missing head commit block: {head_cid}")
+
+        commit_doc = dag_cbor_decode(blocks[head_cid])
+        if not isinstance(commit_doc, dict) or 'did' not in commit_doc:
+            raise RepoError("root block is not a valid ATProto commit")
+
+        did = commit_doc['did']
+        mst_root = commit_doc.get('data')
+        if not isinstance(mst_root, CIDLink):
+            mst_root = CIDLink.from_str(str(mst_root))
+
+        repo = cls(did=did, signing_key_hex=signing_key_hex, blockstore=blocks, blob_store=blob_store)
+        repo.head_commit_cid = head_cid
+        repo.mst = MST(root_cid=mst_root, blocks=blocks)
+        return repo