"""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
[docs]class RepoError(FleetmeshError):
"""Base error for ATProto repository operations."""
[docs]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))
[docs]class Repo:
"""An ATProto account repository."""
[docs] 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)
[docs] @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
[docs] 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
[docs] 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
[docs] 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)
[docs] 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
[docs] 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),
}
[docs] 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
[docs] 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)
[docs] @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