Skip to main content

hyprstream_pds/
hosted_repo.rs

1//! Initial atproto repository state for a hosted PDS account.
2//!
3//! A hosted account starts with a real, signed repo head even before it has
4//! application records. The empty MST root and ES256 commit are immutable
5//! blocks; the commit CID is bound into operation zero by
6//! [`HostedAccountMint::prepare_pds_genesis`](crate::HostedAccountMint::prepare_pds_genesis).
7
8use anyhow::{ensure, Result};
9use p256::ecdsa::{SigningKey, VerifyingKey};
10
11use crate::cid::Cid;
12use crate::commit::{Commit, UnsignedCommit};
13use crate::mst::Node;
14use crate::tid::Tid;
15
16/// A verified empty-MST root and signed initial repo commit.
17#[derive(Clone, Debug, Eq, PartialEq)]
18pub struct HostedRepoGenesis {
19    mst_root: Cid,
20    mst_blocks: Vec<(Cid, Vec<u8>)>,
21    /// Native commit retained for the Hyprstream repository and DID-log
22    /// binding. Its signature covers the native DAG-CBOR ordering.
23    commit: Commit,
24    commit_bytes: Vec<u8>,
25    /// Canonical AT Protocol representation of the same empty repository
26    /// state. This is an explicit dual-format bridge; it is never substituted
27    /// for the native commit or its DID-log binding.
28    public_commit: Commit,
29    public_commit_bytes: Vec<u8>,
30}
31
32impl HostedRepoGenesis {
33    pub(crate) fn seal(did: &str, signing_key: &SigningKey, rev: Tid) -> Result<Self> {
34        let tree = Node::empty();
35        let mst_root = tree.root_cid();
36        let mst_blocks = tree
37            .all_blocks()
38            .into_iter()
39            .map(|(cid, block)| (cid, block.encode()))
40            .collect::<Vec<_>>();
41        ensure!(
42            mst_blocks.iter().any(|(cid, _)| *cid == mst_root),
43            "initial hosted repo omits its MST root block"
44        );
45
46        let unsigned = UnsignedCommit::new(did, mst_root, rev, None);
47        let commit = Commit::sign(&unsigned, signing_key);
48        commit.verify(signing_key.verifying_key())?;
49        ensure!(
50            commit.did == did && commit.data == mst_root && commit.prev.is_none(),
51            "initial hosted repo commit does not describe the requested empty repo"
52        );
53        let commit_bytes = commit.to_dag_cbor();
54        let public_commit = Commit::sign_atproto(&unsigned, signing_key)?;
55        public_commit.verify_atproto(signing_key.verifying_key())?;
56        let public_commit_bytes = public_commit.to_atproto_dag_cbor()?;
57
58        Ok(Self {
59            mst_root,
60            mst_blocks,
61            commit,
62            commit_bytes,
63            public_commit,
64            public_commit_bytes,
65        })
66    }
67
68    /// CID of the canonical empty MST root block.
69    #[must_use]
70    pub fn mst_root(&self) -> Cid {
71        self.mst_root
72    }
73
74    /// Every MST block needed to materialize the initial repository.
75    #[must_use]
76    pub fn mst_blocks(&self) -> &[(Cid, Vec<u8>)] {
77        &self.mst_blocks
78    }
79
80    /// Signed ES256 initial commit.
81    #[must_use]
82    pub fn commit(&self) -> &Commit {
83        &self.commit
84    }
85
86    /// Canonical DAG-CBOR bytes of the signed initial commit.
87    #[must_use]
88    pub fn commit_bytes(&self) -> &[u8] {
89        &self.commit_bytes
90    }
91
92    /// CID of the signed initial commit bound into the genesis DID operation.
93    #[must_use]
94    pub fn commit_cid(&self) -> Cid {
95        self.commit.cid()
96    }
97
98    /// Canonical AT Protocol commit for the same empty repository state.
99    #[must_use]
100    pub fn public_commit(&self) -> &Commit {
101        &self.public_commit
102    }
103
104    /// Canonical AT Protocol bytes for the dual-format public genesis.
105    #[must_use]
106    pub fn public_commit_bytes(&self) -> &[u8] {
107        &self.public_commit_bytes
108    }
109
110    /// CID of the canonical public genesis. The native CID remains the DID
111    /// operation's bound head; callers must not conflate the two.
112    pub fn public_commit_cid(&self) -> Result<Cid> {
113        self.public_commit.cid_atproto()
114    }
115
116    /// Re-verify the stored block linkage and commit signature.
117    pub fn verify(&self, verifying_key: &VerifyingKey) -> Result<()> {
118        ensure!(
119            self.mst_blocks
120                .iter()
121                .any(|(cid, bytes)| *cid == self.mst_root && Cid::from_dag_cbor(bytes) == *cid),
122            "initial hosted repo MST root block is missing or corrupt"
123        );
124        ensure!(
125            self.commit.data == self.mst_root && self.commit.prev.is_none(),
126            "initial hosted repo commit linkage is invalid"
127        );
128        ensure!(
129            self.commit.to_dag_cbor() == self.commit_bytes,
130            "initial hosted repo commit bytes are not canonical"
131        );
132        self.commit.verify(verifying_key)?;
133        ensure!(
134            self.public_commit.did == self.commit.did
135                && self.public_commit.data == self.commit.data
136                && self.public_commit.rev == self.commit.rev
137                && self.public_commit.prev == self.commit.prev
138                && self.public_commit.to_atproto_dag_cbor()? == self.public_commit_bytes,
139            "dual-format public genesis does not match native repository state"
140        );
141        self.public_commit.verify_atproto(verifying_key)
142    }
143}
144
145#[cfg(test)]
146mod tests {
147    #![allow(clippy::unwrap_used)]
148
149    use p256::ecdsa::SigningKey;
150
151    use super::*;
152
153    #[test]
154    fn empty_repo_genesis_is_signed_and_contains_its_root_block() {
155        let key = SigningKey::from_slice(&[19; 32]).unwrap();
156        let repo = HostedRepoGenesis::seal(
157            "did:web:alice.accounts.example",
158            &key,
159            Tid::from_micros(7, 1),
160        )
161        .unwrap();
162
163        repo.verify(key.verifying_key()).unwrap();
164        assert_eq!(repo.commit().did, "did:web:alice.accounts.example");
165        assert_eq!(repo.commit().data, repo.mst_root());
166        assert_eq!(repo.mst_blocks().len(), 1);
167        assert_eq!(repo.commit_cid(), Cid::from_dag_cbor(repo.commit_bytes()));
168        assert_eq!(
169            repo.public_commit_cid().unwrap(),
170            Cid::from_dag_cbor(repo.public_commit_bytes())
171        );
172        repo.verify(key.verifying_key()).unwrap();
173    }
174}