Skip to main content

personaldb_protocol/
projection.rs

1use std::fmt;
2
3use prost::Message;
4use serde::{Deserialize, Serialize};
5use sha2::{Digest as _, Sha256};
6
7use crate::{
8    DatabaseId, ProtocolSignable, ProtocolSigner, PublicKeyTrustStore, SignatureDomain,
9    SignatureEnvelopeV1, SignatureError, SignatureMetadata, SignaturePurpose, SignatureScope,
10    SigningPayload,
11};
12
13pub const STATE_COMMITMENT_FORMAT_VERSION_V1: u32 = 1;
14pub const PROTOCOL_EVIDENCE_FORMAT_VERSION_V2: u32 = 2;
15pub const GROUP_DESCRIPTOR_FORMAT_VERSION_V1: u32 = 1;
16pub const MAX_PROTOCOL_ID_BYTES: usize = 128;
17
18const LOG_ENTRY_CORE_HASH_DOMAIN: &[u8] = b"personaldb-log-entry-core-v2\0";
19const COMMIT_CERTIFICATE_HASH_DOMAIN: &[u8] = b"personaldb-commit-certificate-v2\0";
20
21#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
22pub struct Sha256Digest(#[serde(with = "digest_serde")] [u8; 32]);
23
24impl Sha256Digest {
25    pub const ZERO: Self = Self([0; 32]);
26
27    pub const fn from_bytes(bytes: [u8; 32]) -> Self {
28        Self(bytes)
29    }
30
31    pub fn hash(bytes: &[u8]) -> Self {
32        Self(Sha256::digest(bytes).into())
33    }
34
35    pub fn hash_domain(domain: &[u8], bytes: &[u8]) -> Self {
36        let mut hasher = Sha256::new();
37        hasher.update(domain);
38        hasher.update(bytes);
39        Self(hasher.finalize().into())
40    }
41
42    pub const fn as_bytes(&self) -> &[u8; 32] {
43        &self.0
44    }
45
46    pub const fn into_bytes(self) -> [u8; 32] {
47        self.0
48    }
49
50    pub fn to_prefixed_hex(self) -> String {
51        format!("sha256:{}", hex::encode(self.0))
52    }
53
54    pub fn from_prefixed_hex(value: &str) -> Result<Self, ProjectionProtocolError> {
55        let encoded = value.strip_prefix("sha256:").unwrap_or(value);
56        let bytes = hex::decode(encoded)
57            .map_err(|_| ProjectionProtocolError::InvalidDigestEncoding(value.to_string()))?;
58        Self::try_from(bytes.as_slice())
59    }
60}
61
62impl TryFrom<&[u8]> for Sha256Digest {
63    type Error = ProjectionProtocolError;
64
65    fn try_from(value: &[u8]) -> Result<Self, Self::Error> {
66        let bytes = value
67            .try_into()
68            .map_err(|_| ProjectionProtocolError::InvalidDigestLength(value.len()))?;
69        Ok(Self(bytes))
70    }
71}
72
73impl AsRef<[u8]> for Sha256Digest {
74    fn as_ref(&self) -> &[u8] {
75        &self.0
76    }
77}
78
79impl fmt::Display for Sha256Digest {
80    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
81        formatter.write_str(&self.to_prefixed_hex())
82    }
83}
84
85mod digest_serde {
86    use serde::{Deserialize, Deserializer, Serializer};
87
88    pub fn serialize<S>(value: &[u8; 32], serializer: S) -> Result<S::Ok, S::Error>
89    where
90        S: Serializer,
91    {
92        serializer.serialize_str(&hex::encode(value))
93    }
94
95    pub fn deserialize<'de, D>(deserializer: D) -> Result<[u8; 32], D::Error>
96    where
97        D: Deserializer<'de>,
98    {
99        let value = String::deserialize(deserializer)?;
100        let bytes = hex::decode(&value).map_err(serde::de::Error::custom)?;
101        bytes
102            .try_into()
103            .map_err(|bytes: Vec<u8>| serde::de::Error::invalid_length(bytes.len(), &"32 bytes"))
104    }
105}
106
107#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
108#[serde(rename_all = "snake_case")]
109pub enum ProtocolSecurityProfile {
110    Production,
111    Development,
112}
113
114#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
115#[serde(rename_all = "snake_case")]
116pub enum DatabaseGroupKind {
117    Source,
118    Projection,
119    Standalone,
120}
121
122impl DatabaseGroupKind {
123    pub const fn as_str(self) -> &'static str {
124        match self {
125            Self::Source => "source",
126            Self::Projection => "projection",
127            Self::Standalone => "standalone",
128        }
129    }
130
131    fn parse(value: &str) -> Result<Self, ProjectionProtocolError> {
132        match value {
133            "source" => Ok(Self::Source),
134            "projection" => Ok(Self::Projection),
135            "standalone" => Ok(Self::Standalone),
136            _ => Err(ProjectionProtocolError::InvalidGroupKind(value.to_string())),
137        }
138    }
139}
140
141#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
142pub struct StateCommitmentV1 {
143    pub database_id: DatabaseId,
144    pub log_index: u64,
145    pub log_hash: Sha256Digest,
146    pub database_state_root: Sha256Digest,
147    pub schema_hash: Sha256Digest,
148    pub projection_definition_hash: Option<Sha256Digest>,
149    pub group_kind: DatabaseGroupKind,
150}
151
152impl StateCommitmentV1 {
153    pub fn validate(&self) -> Result<(), ProjectionProtocolError> {
154        validate_id("database_id", &self.database_id.0)?;
155        Ok(())
156    }
157
158    pub fn encode_deterministic(&self) -> Result<Vec<u8>, ProjectionProtocolError> {
159        self.validate()?;
160        Ok(self.to_wire().encode_to_vec())
161    }
162
163    pub fn decode_canonical(bytes: &[u8]) -> Result<Self, ProjectionProtocolError> {
164        let wire = WireStateCommitmentV1::decode(bytes)
165            .map_err(|_| ProjectionProtocolError::MalformedProtobuf("StateCommitmentV1"))?;
166        let state = Self::from_wire(wire)?;
167        require_canonical("StateCommitmentV1", bytes, &state.encode_deterministic()?)?;
168        Ok(state)
169    }
170
171    pub fn canonical_sha256(&self) -> Result<Sha256Digest, ProjectionProtocolError> {
172        Ok(Sha256Digest::hash(&self.encode_deterministic()?))
173    }
174
175    fn to_wire(&self) -> WireStateCommitmentV1 {
176        WireStateCommitmentV1 {
177            format_version: STATE_COMMITMENT_FORMAT_VERSION_V1,
178            database_id: self.database_id.0.clone(),
179            log_index: self.log_index,
180            log_hash_sha256: self.log_hash.as_bytes().to_vec(),
181            database_state_root_sha256: self.database_state_root.as_bytes().to_vec(),
182            schema_hash_sha256: self.schema_hash.as_bytes().to_vec(),
183            projection_definition_hash_sha256: self
184                .projection_definition_hash
185                .map(|hash| hash.as_bytes().to_vec()),
186            group_kind: self.group_kind.as_str().to_string(),
187        }
188    }
189
190    fn from_wire(wire: WireStateCommitmentV1) -> Result<Self, ProjectionProtocolError> {
191        require_version(
192            "StateCommitmentV1",
193            wire.format_version,
194            STATE_COMMITMENT_FORMAT_VERSION_V1,
195        )?;
196        let commitment = Self {
197            database_id: DatabaseId::new(wire.database_id),
198            log_index: wire.log_index,
199            log_hash: Sha256Digest::try_from(wire.log_hash_sha256.as_slice())?,
200            database_state_root: Sha256Digest::try_from(
201                wire.database_state_root_sha256.as_slice(),
202            )?,
203            schema_hash: Sha256Digest::try_from(wire.schema_hash_sha256.as_slice())?,
204            projection_definition_hash: wire
205                .projection_definition_hash_sha256
206                .map(|value| Sha256Digest::try_from(value.as_slice()))
207                .transpose()?,
208            group_kind: DatabaseGroupKind::parse(&wire.group_kind)?,
209        };
210        commitment.validate()?;
211        Ok(commitment)
212    }
213}
214
215impl TryFrom<&[u8]> for StateCommitmentV1 {
216    type Error = ProjectionProtocolError;
217
218    fn try_from(value: &[u8]) -> Result<Self, Self::Error> {
219        Self::decode_canonical(value)
220    }
221}
222
223#[derive(Debug, Clone, PartialEq, Eq)]
224pub struct LogEntryCoreV2 {
225    pub database_id: DatabaseId,
226    pub group_kind: DatabaseGroupKind,
227    pub log_index: u64,
228    pub previous_entry_hash: Sha256Digest,
229    pub changeset_payload_hash: Sha256Digest,
230    pub client_proposal_hash: Sha256Digest,
231    pub database_state_root: Sha256Digest,
232    pub schema_hash: Sha256Digest,
233    pub projection_definition_hash: Option<Sha256Digest>,
234    pub membership_revision: u64,
235    pub placement_epoch: u64,
236    pub client_log_epoch: u64,
237    pub proposal_admission_hash: Sha256Digest,
238}
239
240impl LogEntryCoreV2 {
241    pub fn encode_deterministic(&self) -> Result<Vec<u8>, ProjectionProtocolError> {
242        self.validate()?;
243        Ok(self.to_wire().encode_to_vec())
244    }
245
246    pub fn entry_hash(&self) -> Result<Sha256Digest, ProjectionProtocolError> {
247        Ok(Sha256Digest::hash_domain(
248            LOG_ENTRY_CORE_HASH_DOMAIN,
249            &self.encode_deterministic()?,
250        ))
251    }
252
253    fn validate(&self) -> Result<(), ProjectionProtocolError> {
254        validate_id("database_id", &self.database_id.0)?;
255        if self.log_index == 0 {
256            return Err(ProjectionProtocolError::InvalidField {
257                object: "LogEntryCoreV2",
258                field: "log_index",
259            });
260        }
261        Ok(())
262    }
263
264    fn to_wire(&self) -> WireLogEntryCoreV2 {
265        WireLogEntryCoreV2 {
266            format_version: PROTOCOL_EVIDENCE_FORMAT_VERSION_V2,
267            database_id: self.database_id.0.clone(),
268            group_kind: self.group_kind.as_str().to_string(),
269            log_index: self.log_index,
270            previous_entry_hash_sha256: self.previous_entry_hash.as_bytes().to_vec(),
271            changeset_payload_hash_sha256: self.changeset_payload_hash.as_bytes().to_vec(),
272            client_proposal_hash_sha256: self.client_proposal_hash.as_bytes().to_vec(),
273            database_state_root_sha256: self.database_state_root.as_bytes().to_vec(),
274            schema_hash_sha256: self.schema_hash.as_bytes().to_vec(),
275            projection_definition_hash_sha256: self
276                .projection_definition_hash
277                .map(|hash| hash.as_bytes().to_vec()),
278            membership_revision: self.membership_revision,
279            placement_epoch: self.placement_epoch,
280            client_log_epoch: self.client_log_epoch,
281            proposal_admission_hash_sha256: self.proposal_admission_hash.as_bytes().to_vec(),
282        }
283    }
284
285    fn from_wire(wire: WireLogEntryCoreV2) -> Result<Self, ProjectionProtocolError> {
286        require_version(
287            "LogEntryCoreV2",
288            wire.format_version,
289            PROTOCOL_EVIDENCE_FORMAT_VERSION_V2,
290        )?;
291        let core = Self {
292            database_id: DatabaseId::new(wire.database_id),
293            group_kind: DatabaseGroupKind::parse(&wire.group_kind)?,
294            log_index: wire.log_index,
295            previous_entry_hash: Sha256Digest::try_from(
296                wire.previous_entry_hash_sha256.as_slice(),
297            )?,
298            changeset_payload_hash: Sha256Digest::try_from(
299                wire.changeset_payload_hash_sha256.as_slice(),
300            )?,
301            client_proposal_hash: Sha256Digest::try_from(
302                wire.client_proposal_hash_sha256.as_slice(),
303            )?,
304            database_state_root: Sha256Digest::try_from(
305                wire.database_state_root_sha256.as_slice(),
306            )?,
307            schema_hash: Sha256Digest::try_from(wire.schema_hash_sha256.as_slice())?,
308            projection_definition_hash: wire
309                .projection_definition_hash_sha256
310                .map(|value| Sha256Digest::try_from(value.as_slice()))
311                .transpose()?,
312            membership_revision: wire.membership_revision,
313            placement_epoch: wire.placement_epoch,
314            client_log_epoch: wire.client_log_epoch,
315            proposal_admission_hash: Sha256Digest::try_from(
316                wire.proposal_admission_hash_sha256.as_slice(),
317            )?,
318        };
319        core.validate()?;
320        Ok(core)
321    }
322}
323
324#[derive(Debug, Clone, PartialEq, Eq)]
325pub struct UnsignedCommitCertificateV2 {
326    pub entry_core: LogEntryCoreV2,
327    pub resulting_state: StateCommitmentV1,
328    pub signed_client_proposal: Vec<u8>,
329    pub signed_voter_acknowledgements: Vec<Vec<u8>>,
330    pub signed_projection_derivation: Option<Vec<u8>>,
331    pub primary_server_id: String,
332    pub signed_proposal_admission: Vec<u8>,
333}
334
335impl UnsignedCommitCertificateV2 {
336    pub fn sign(
337        self,
338        group_id: &str,
339        signer: &dyn ProtocolSigner,
340    ) -> Result<CommitCertificateV2, ProjectionProtocolError> {
341        self.validate()?;
342        let unsigned = self.encode_deterministic()?;
343        let signable = CanonicalSignable::new(
344            signature_metadata(
345                SignaturePurpose::Witness,
346                SignatureDomain::CommitCertificate,
347                &self.entry_core.database_id,
348                group_id,
349                self.entry_core.log_index,
350            ),
351            &unsigned,
352        );
353        let witness_signature = signer.sign(&signable)?;
354        Ok(CommitCertificateV2 {
355            unsigned: self,
356            witness_signature,
357        })
358    }
359
360    pub fn encode_deterministic(&self) -> Result<Vec<u8>, ProjectionProtocolError> {
361        self.validate()?;
362        Ok(self.to_wire(None)?.encode_to_vec())
363    }
364
365    fn validate(&self) -> Result<(), ProjectionProtocolError> {
366        self.entry_core.validate()?;
367        self.resulting_state.validate()?;
368        validate_id("primary_server_id", &self.primary_server_id)?;
369        let entry_hash = self.entry_core.entry_hash()?;
370        if self.resulting_state.database_id != self.entry_core.database_id
371            || self.resulting_state.group_kind != self.entry_core.group_kind
372            || self.resulting_state.log_index != self.entry_core.log_index
373            || self.resulting_state.log_hash != entry_hash
374            || self.resulting_state.database_state_root != self.entry_core.database_state_root
375            || self.resulting_state.schema_hash != self.entry_core.schema_hash
376            || self.resulting_state.projection_definition_hash
377                != self.entry_core.projection_definition_hash
378        {
379            return Err(ProjectionProtocolError::CertificateStateMismatch);
380        }
381        Ok(())
382    }
383
384    fn to_wire(
385        &self,
386        signature: Option<&SignatureEnvelopeV1>,
387    ) -> Result<WireCommitCertificateV2, ProjectionProtocolError> {
388        Ok(WireCommitCertificateV2 {
389            format_version: PROTOCOL_EVIDENCE_FORMAT_VERSION_V2,
390            entry_core: Some(self.entry_core.to_wire()),
391            resulting_state: Some(self.resulting_state.to_wire()),
392            client_proposal: self.signed_client_proposal.clone(),
393            voter_acknowledgements: self.signed_voter_acknowledgements.clone(),
394            projection_derivation: self.signed_projection_derivation.clone(),
395            primary_server_id: self.primary_server_id.clone(),
396            witness_signature: signature
397                .map(SignatureEnvelopeV1::encode_deterministic)
398                .transpose()?,
399            proposal_admission: self.signed_proposal_admission.clone(),
400        })
401    }
402}
403
404#[derive(Debug, Clone, PartialEq, Eq)]
405pub struct CommitCertificateV2 {
406    unsigned: UnsignedCommitCertificateV2,
407    witness_signature: SignatureEnvelopeV1,
408}
409
410impl CommitCertificateV2 {
411    pub fn unsigned(&self) -> &UnsignedCommitCertificateV2 {
412        &self.unsigned
413    }
414
415    pub fn witness_signature(&self) -> &SignatureEnvelopeV1 {
416        &self.witness_signature
417    }
418
419    pub fn verify(
420        &self,
421        group_id: &str,
422        trust_store: &PublicKeyTrustStore,
423    ) -> Result<(), ProjectionProtocolError> {
424        self.unsigned.validate()?;
425        let unsigned = self.unsigned.encode_deterministic()?;
426        let signable = CanonicalSignable::new(
427            signature_metadata(
428                SignaturePurpose::Witness,
429                SignatureDomain::CommitCertificate,
430                &self.unsigned.entry_core.database_id,
431                group_id,
432                self.unsigned.entry_core.log_index,
433            ),
434            &unsigned,
435        );
436        trust_store.verify(&signable, &self.witness_signature)?;
437        Ok(())
438    }
439
440    pub fn encode_deterministic(&self) -> Result<Vec<u8>, ProjectionProtocolError> {
441        self.unsigned.validate()?;
442        Ok(self
443            .unsigned
444            .to_wire(Some(&self.witness_signature))?
445            .encode_to_vec())
446    }
447
448    pub fn decode_canonical(bytes: &[u8]) -> Result<Self, ProjectionProtocolError> {
449        let wire = WireCommitCertificateV2::decode(bytes)
450            .map_err(|_| ProjectionProtocolError::MalformedProtobuf("CommitCertificateV2"))?;
451        require_version(
452            "CommitCertificateV2",
453            wire.format_version,
454            PROTOCOL_EVIDENCE_FORMAT_VERSION_V2,
455        )?;
456        let signature = wire
457            .witness_signature
458            .ok_or(ProjectionProtocolError::MissingField {
459                object: "CommitCertificateV2",
460                field: "witness_signature",
461            })
462            .and_then(|bytes| {
463                SignatureEnvelopeV1::decode_canonical(&bytes)
464                    .map_err(ProjectionProtocolError::Signature)
465            })?;
466        let unsigned = UnsignedCommitCertificateV2 {
467            entry_core: LogEntryCoreV2::from_wire(wire.entry_core.ok_or(
468                ProjectionProtocolError::MissingField {
469                    object: "CommitCertificateV2",
470                    field: "entry_core",
471                },
472            )?)?,
473            resulting_state: StateCommitmentV1::from_wire(wire.resulting_state.ok_or(
474                ProjectionProtocolError::MissingField {
475                    object: "CommitCertificateV2",
476                    field: "resulting_state",
477                },
478            )?)?,
479            signed_client_proposal: wire.client_proposal,
480            signed_voter_acknowledgements: wire.voter_acknowledgements,
481            signed_projection_derivation: wire.projection_derivation,
482            primary_server_id: wire.primary_server_id,
483            signed_proposal_admission: wire.proposal_admission,
484        };
485        let certificate = Self {
486            unsigned,
487            witness_signature: signature,
488        };
489        certificate.unsigned.validate()?;
490        require_canonical(
491            "CommitCertificateV2",
492            bytes,
493            &certificate.encode_deterministic()?,
494        )?;
495        Ok(certificate)
496    }
497
498    pub fn certificate_hash(&self) -> Result<Sha256Digest, ProjectionProtocolError> {
499        Ok(Sha256Digest::hash_domain(
500            COMMIT_CERTIFICATE_HASH_DOMAIN,
501            &self.encode_deterministic()?,
502        ))
503    }
504}
505
506#[derive(Debug, Clone, PartialEq, Eq)]
507pub struct UnsignedCommittedHeadV2 {
508    pub state: StateCommitmentV1,
509    pub commit_certificate_hash: Sha256Digest,
510    pub primary_server_id: String,
511    pub placement_epoch: u64,
512}
513
514impl UnsignedCommittedHeadV2 {
515    pub fn sign(
516        self,
517        group_id: &str,
518        signer: &dyn ProtocolSigner,
519    ) -> Result<CommittedHeadV2, ProjectionProtocolError> {
520        self.validate()?;
521        let unsigned = self.encode_deterministic()?;
522        let signable = CanonicalSignable::new(
523            signature_metadata(
524                SignaturePurpose::Witness,
525                SignatureDomain::CommittedHead,
526                &self.state.database_id,
527                group_id,
528                self.state.log_index,
529            ),
530            &unsigned,
531        );
532        let witness_signature = signer.sign(&signable)?;
533        Ok(CommittedHeadV2 {
534            unsigned: self,
535            witness_signature,
536        })
537    }
538
539    pub fn encode_deterministic(&self) -> Result<Vec<u8>, ProjectionProtocolError> {
540        self.validate()?;
541        Ok(self.to_wire(None)?.encode_to_vec())
542    }
543
544    fn validate(&self) -> Result<(), ProjectionProtocolError> {
545        self.state.validate()?;
546        validate_id("primary_server_id", &self.primary_server_id)
547    }
548
549    fn to_wire(
550        &self,
551        signature: Option<&SignatureEnvelopeV1>,
552    ) -> Result<WireCommittedHeadV2, ProjectionProtocolError> {
553        Ok(WireCommittedHeadV2 {
554            format_version: PROTOCOL_EVIDENCE_FORMAT_VERSION_V2,
555            state: Some(self.state.to_wire()),
556            commit_certificate_hash_sha256: self.commit_certificate_hash.as_bytes().to_vec(),
557            primary_server_id: self.primary_server_id.clone(),
558            placement_epoch: self.placement_epoch,
559            witness_signature: signature
560                .map(SignatureEnvelopeV1::encode_deterministic)
561                .transpose()?,
562        })
563    }
564}
565
566#[derive(Debug, Clone, PartialEq, Eq)]
567pub struct CommittedHeadV2 {
568    unsigned: UnsignedCommittedHeadV2,
569    witness_signature: SignatureEnvelopeV1,
570}
571
572impl CommittedHeadV2 {
573    pub fn state(&self) -> &StateCommitmentV1 {
574        &self.unsigned.state
575    }
576
577    pub fn commit_certificate_hash(&self) -> Sha256Digest {
578        self.unsigned.commit_certificate_hash
579    }
580
581    pub fn primary_server_id(&self) -> &str {
582        &self.unsigned.primary_server_id
583    }
584
585    pub fn placement_epoch(&self) -> u64 {
586        self.unsigned.placement_epoch
587    }
588
589    pub fn witness_signature(&self) -> &SignatureEnvelopeV1 {
590        &self.witness_signature
591    }
592
593    pub fn verify(
594        &self,
595        group_id: &str,
596        trust_store: &PublicKeyTrustStore,
597    ) -> Result<(), ProjectionProtocolError> {
598        self.unsigned.validate()?;
599        let unsigned = self.unsigned.encode_deterministic()?;
600        let signable = CanonicalSignable::new(
601            signature_metadata(
602                SignaturePurpose::Witness,
603                SignatureDomain::CommittedHead,
604                &self.unsigned.state.database_id,
605                group_id,
606                self.unsigned.state.log_index,
607            ),
608            &unsigned,
609        );
610        trust_store.verify(&signable, &self.witness_signature)?;
611        Ok(())
612    }
613
614    pub fn verify_certificate(
615        &self,
616        certificate: &CommitCertificateV2,
617    ) -> Result<(), ProjectionProtocolError> {
618        let certificate_state = &certificate.unsigned.entry_core;
619        if self.unsigned.state != certificate.unsigned.resulting_state
620            || self.unsigned.commit_certificate_hash != certificate.certificate_hash()?
621            || self.unsigned.primary_server_id != certificate.unsigned.primary_server_id
622            || self.unsigned.placement_epoch != certificate_state.placement_epoch
623        {
624            return Err(ProjectionProtocolError::HeadCertificateMismatch);
625        }
626        Ok(())
627    }
628
629    pub fn encode_deterministic(&self) -> Result<Vec<u8>, ProjectionProtocolError> {
630        self.unsigned.validate()?;
631        Ok(self
632            .unsigned
633            .to_wire(Some(&self.witness_signature))?
634            .encode_to_vec())
635    }
636
637    pub fn decode_canonical(bytes: &[u8]) -> Result<Self, ProjectionProtocolError> {
638        let wire = WireCommittedHeadV2::decode(bytes)
639            .map_err(|_| ProjectionProtocolError::MalformedProtobuf("CommittedHeadV2"))?;
640        require_version(
641            "CommittedHeadV2",
642            wire.format_version,
643            PROTOCOL_EVIDENCE_FORMAT_VERSION_V2,
644        )?;
645        let signature = wire
646            .witness_signature
647            .ok_or(ProjectionProtocolError::MissingField {
648                object: "CommittedHeadV2",
649                field: "witness_signature",
650            })
651            .and_then(|bytes| {
652                SignatureEnvelopeV1::decode_canonical(&bytes)
653                    .map_err(ProjectionProtocolError::Signature)
654            })?;
655        let head = Self {
656            unsigned: UnsignedCommittedHeadV2 {
657                state: StateCommitmentV1::from_wire(wire.state.ok_or(
658                    ProjectionProtocolError::MissingField {
659                        object: "CommittedHeadV2",
660                        field: "state",
661                    },
662                )?)?,
663                commit_certificate_hash: Sha256Digest::try_from(
664                    wire.commit_certificate_hash_sha256.as_slice(),
665                )?,
666                primary_server_id: wire.primary_server_id,
667                placement_epoch: wire.placement_epoch,
668            },
669            witness_signature: signature,
670        };
671        head.unsigned.validate()?;
672        require_canonical("CommittedHeadV2", bytes, &head.encode_deterministic()?)?;
673        Ok(head)
674    }
675}
676
677#[derive(Debug, Clone, PartialEq, Eq)]
678pub struct UnsignedGroupDescriptorV1 {
679    pub group_id: String,
680    pub database_id: DatabaseId,
681    pub group_kind: DatabaseGroupKind,
682    pub schema_hash: Sha256Digest,
683    pub projection_definition_hash: Option<Sha256Digest>,
684    pub committed_head: CommittedHeadV2,
685    pub trust_bundle_version: u64,
686}
687
688impl UnsignedGroupDescriptorV1 {
689    pub fn sign(
690        self,
691        signer: &dyn ProtocolSigner,
692    ) -> Result<GroupDescriptor, ProjectionProtocolError> {
693        self.validate()?;
694        let unsigned = self.encode_deterministic()?;
695        let signable = CanonicalSignable::new(
696            signature_metadata(
697                SignaturePurpose::GroupControl,
698                SignatureDomain::GroupManifest,
699                &self.database_id,
700                &self.group_id,
701                0,
702            ),
703            &unsigned,
704        );
705        let signature = signer.sign(&signable)?;
706        Ok(GroupDescriptor {
707            unsigned: self,
708            signature,
709        })
710    }
711
712    pub fn encode_deterministic(&self) -> Result<Vec<u8>, ProjectionProtocolError> {
713        self.validate()?;
714        Ok(self.to_wire(None)?.encode_to_vec())
715    }
716
717    fn validate(&self) -> Result<(), ProjectionProtocolError> {
718        validate_id("group_id", &self.group_id)?;
719        validate_id("database_id", &self.database_id.0)?;
720        if self.group_kind == DatabaseGroupKind::Projection
721            && self.projection_definition_hash.is_none()
722        {
723            return Err(ProjectionProtocolError::MissingField {
724                object: "GroupDescriptorV1",
725                field: "projection_definition_hash",
726            });
727        }
728        let state = self.committed_head.state();
729        if state.database_id != self.database_id
730            || state.group_kind != self.group_kind
731            || state.schema_hash != self.schema_hash
732            || state.projection_definition_hash != self.projection_definition_hash
733        {
734            return Err(ProjectionProtocolError::DescriptorHeadMismatch);
735        }
736        Ok(())
737    }
738
739    fn to_wire(
740        &self,
741        signature: Option<&SignatureEnvelopeV1>,
742    ) -> Result<WireGroupDescriptorV1, ProjectionProtocolError> {
743        Ok(WireGroupDescriptorV1 {
744            format_version: GROUP_DESCRIPTOR_FORMAT_VERSION_V1,
745            group_id: self.group_id.clone(),
746            database_id: self.database_id.0.clone(),
747            group_kind: self.group_kind.as_str().to_string(),
748            schema_hash_sha256: self.schema_hash.as_bytes().to_vec(),
749            projection_definition_hash_sha256: self
750                .projection_definition_hash
751                .map(|hash| hash.as_bytes().to_vec()),
752            committed_head: self.committed_head.encode_deterministic()?,
753            trust_bundle_version: self.trust_bundle_version,
754            group_control_signature: signature
755                .map(SignatureEnvelopeV1::encode_deterministic)
756                .transpose()?,
757        })
758    }
759}
760
761#[derive(Debug, Clone, PartialEq, Eq)]
762pub struct GroupDescriptor {
763    unsigned: UnsignedGroupDescriptorV1,
764    signature: SignatureEnvelopeV1,
765}
766
767impl GroupDescriptor {
768    pub fn group_id(&self) -> &str {
769        &self.unsigned.group_id
770    }
771
772    pub fn database_id(&self) -> &DatabaseId {
773        &self.unsigned.database_id
774    }
775
776    pub fn group_kind(&self) -> DatabaseGroupKind {
777        self.unsigned.group_kind
778    }
779
780    pub fn schema_hash(&self) -> Sha256Digest {
781        self.unsigned.schema_hash
782    }
783
784    pub fn projection_definition_hash(&self) -> Option<Sha256Digest> {
785        self.unsigned.projection_definition_hash
786    }
787
788    pub fn committed_head(&self) -> &CommittedHeadV2 {
789        &self.unsigned.committed_head
790    }
791
792    pub fn trust_bundle_version(&self) -> u64 {
793        self.unsigned.trust_bundle_version
794    }
795
796    pub fn verify(&self, trust_store: &PublicKeyTrustStore) -> Result<(), ProjectionProtocolError> {
797        self.unsigned.validate()?;
798        self.unsigned
799            .committed_head
800            .verify(&self.unsigned.group_id, trust_store)?;
801        let unsigned = self.unsigned.encode_deterministic()?;
802        let signable = CanonicalSignable::new(
803            signature_metadata(
804                SignaturePurpose::GroupControl,
805                SignatureDomain::GroupManifest,
806                &self.unsigned.database_id,
807                &self.unsigned.group_id,
808                0,
809            ),
810            &unsigned,
811        );
812        trust_store.verify(&signable, &self.signature)?;
813        Ok(())
814    }
815
816    pub fn encode_deterministic(&self) -> Result<Vec<u8>, ProjectionProtocolError> {
817        self.unsigned.validate()?;
818        Ok(self
819            .unsigned
820            .to_wire(Some(&self.signature))?
821            .encode_to_vec())
822    }
823
824    pub fn decode_canonical(bytes: &[u8]) -> Result<Self, ProjectionProtocolError> {
825        let wire = WireGroupDescriptorV1::decode(bytes)
826            .map_err(|_| ProjectionProtocolError::MalformedProtobuf("GroupDescriptorV1"))?;
827        require_version(
828            "GroupDescriptorV1",
829            wire.format_version,
830            GROUP_DESCRIPTOR_FORMAT_VERSION_V1,
831        )?;
832        let descriptor = Self {
833            unsigned: UnsignedGroupDescriptorV1 {
834                group_id: wire.group_id,
835                database_id: DatabaseId::new(wire.database_id),
836                group_kind: DatabaseGroupKind::parse(&wire.group_kind)?,
837                schema_hash: Sha256Digest::try_from(wire.schema_hash_sha256.as_slice())?,
838                projection_definition_hash: wire
839                    .projection_definition_hash_sha256
840                    .map(|value| Sha256Digest::try_from(value.as_slice()))
841                    .transpose()?,
842                committed_head: CommittedHeadV2::decode_canonical(&wire.committed_head)?,
843                trust_bundle_version: wire.trust_bundle_version,
844            },
845            signature: wire
846                .group_control_signature
847                .ok_or(ProjectionProtocolError::MissingField {
848                    object: "GroupDescriptorV1",
849                    field: "group_control_signature",
850                })
851                .and_then(|bytes| {
852                    SignatureEnvelopeV1::decode_canonical(&bytes)
853                        .map_err(ProjectionProtocolError::Signature)
854                })?,
855        };
856        descriptor.unsigned.validate()?;
857        require_canonical(
858            "GroupDescriptorV1",
859            bytes,
860            &descriptor.encode_deterministic()?,
861        )?;
862        Ok(descriptor)
863    }
864}
865
866struct CanonicalSignable<'a> {
867    metadata: SignatureMetadata,
868    bytes: &'a [u8],
869}
870
871impl<'a> CanonicalSignable<'a> {
872    fn new(metadata: SignatureMetadata, bytes: &'a [u8]) -> Self {
873        Self { metadata, bytes }
874    }
875}
876
877impl ProtocolSignable for CanonicalSignable<'_> {
878    fn signature_metadata(&self) -> SignatureMetadata {
879        self.metadata.clone()
880    }
881
882    fn signing_payload(&self) -> SigningPayload<'_> {
883        SigningPayload::ExactBytes(self.bytes)
884    }
885}
886
887fn signature_metadata(
888    purpose: SignaturePurpose,
889    domain: SignatureDomain,
890    database_id: &DatabaseId,
891    group_id: &str,
892    log_index: u64,
893) -> SignatureMetadata {
894    SignatureMetadata::for_domain(purpose, domain, log_index).with_scope(
895        SignatureScope::for_database_group(database_id.clone(), group_id.to_string()),
896    )
897}
898
899pub(crate) fn validate_id(field: &'static str, value: &str) -> Result<(), ProjectionProtocolError> {
900    if value.is_empty()
901        || value.len() > MAX_PROTOCOL_ID_BYTES
902        || !value.is_ascii()
903        || value.contains('\0')
904    {
905        return Err(ProjectionProtocolError::InvalidId { field });
906    }
907    Ok(())
908}
909
910pub(crate) fn require_version(
911    object: &'static str,
912    actual: u32,
913    expected: u32,
914) -> Result<(), ProjectionProtocolError> {
915    if actual != expected {
916        return Err(ProjectionProtocolError::UnsupportedVersion {
917            object,
918            actual,
919            expected,
920        });
921    }
922    Ok(())
923}
924
925pub(crate) fn require_canonical(
926    object: &'static str,
927    input: &[u8],
928    canonical: &[u8],
929) -> Result<(), ProjectionProtocolError> {
930    if input != canonical {
931        return Err(ProjectionProtocolError::NonCanonicalProtobuf(object));
932    }
933    Ok(())
934}
935
936#[derive(Debug, thiserror::Error)]
937pub enum ProjectionProtocolError {
938    #[error("invalid SHA-256 digest length {0}; expected 32 bytes")]
939    InvalidDigestLength(usize),
940    #[error("invalid SHA-256 digest encoding `{0}`")]
941    InvalidDigestEncoding(String),
942    #[error("invalid database group kind `{0}`")]
943    InvalidGroupKind(String),
944    #[error("invalid protocol ID field `{field}`")]
945    InvalidId { field: &'static str },
946    #[error("{object} field `{field}` is missing")]
947    MissingField {
948        object: &'static str,
949        field: &'static str,
950    },
951    #[error("{object} field `{field}` is invalid")]
952    InvalidField {
953        object: &'static str,
954        field: &'static str,
955    },
956    #[error("unsupported {object} version {actual}; expected {expected}")]
957    UnsupportedVersion {
958        object: &'static str,
959        actual: u32,
960        expected: u32,
961    },
962    #[error("malformed protobuf bytes for {0}")]
963    MalformedProtobuf(&'static str),
964    #[error("non-canonical protobuf bytes for {0}")]
965    NonCanonicalProtobuf(&'static str),
966    #[error("commit certificate state does not match its entry core")]
967    CertificateStateMismatch,
968    #[error("committed head does not match its commit certificate")]
969    HeadCertificateMismatch,
970    #[error("group descriptor does not match its committed head")]
971    DescriptorHeadMismatch,
972    #[error("a projection derivation requires at least one source head")]
973    EmptySourceHeads,
974    #[error("source heads must be strictly ordered by database ID")]
975    SourceHeadsNotStrictlyOrdered,
976    #[error("deterministic_batch_id must be lowercase sha256:<64 hex>")]
977    InvalidDeterministicBatchId,
978    #[error("projection derivation resulting database does not match")]
979    ResultingDatabaseMismatch,
980    #[error("projection derivation resulting group kind is not projection")]
981    ResultingGroupKindMismatch,
982    #[error("projection derivation resulting definition does not match")]
983    ResultingProjectionDefinitionMismatch,
984    #[error("previous projection log index cannot be incremented")]
985    ProjectionLogIndexOverflow,
986    #[error("resulting state log index is {actual}; expected {expected}")]
987    ResultingLogIndexMismatch { expected: u64, actual: u64 },
988    #[error(transparent)]
989    Signature(#[from] SignatureError),
990}
991
992#[derive(Clone, PartialEq, Message)]
993struct WireStateCommitmentV1 {
994    #[prost(uint32, tag = "1")]
995    format_version: u32,
996    #[prost(string, tag = "2")]
997    database_id: String,
998    #[prost(uint64, tag = "3")]
999    log_index: u64,
1000    #[prost(bytes = "vec", tag = "4")]
1001    log_hash_sha256: Vec<u8>,
1002    #[prost(bytes = "vec", tag = "5")]
1003    database_state_root_sha256: Vec<u8>,
1004    #[prost(bytes = "vec", tag = "6")]
1005    schema_hash_sha256: Vec<u8>,
1006    #[prost(bytes = "vec", optional, tag = "7")]
1007    projection_definition_hash_sha256: Option<Vec<u8>>,
1008    #[prost(string, tag = "8")]
1009    group_kind: String,
1010}
1011
1012#[derive(Clone, PartialEq, Message)]
1013struct WireLogEntryCoreV2 {
1014    #[prost(uint32, tag = "1")]
1015    format_version: u32,
1016    #[prost(string, tag = "2")]
1017    database_id: String,
1018    #[prost(string, tag = "3")]
1019    group_kind: String,
1020    #[prost(uint64, tag = "4")]
1021    log_index: u64,
1022    #[prost(bytes = "vec", tag = "5")]
1023    previous_entry_hash_sha256: Vec<u8>,
1024    #[prost(bytes = "vec", tag = "6")]
1025    changeset_payload_hash_sha256: Vec<u8>,
1026    #[prost(bytes = "vec", tag = "7")]
1027    client_proposal_hash_sha256: Vec<u8>,
1028    #[prost(bytes = "vec", tag = "8")]
1029    database_state_root_sha256: Vec<u8>,
1030    #[prost(bytes = "vec", tag = "9")]
1031    schema_hash_sha256: Vec<u8>,
1032    #[prost(bytes = "vec", optional, tag = "10")]
1033    projection_definition_hash_sha256: Option<Vec<u8>>,
1034    #[prost(uint64, tag = "11")]
1035    membership_revision: u64,
1036    #[prost(uint64, tag = "12")]
1037    placement_epoch: u64,
1038    #[prost(uint64, tag = "13")]
1039    client_log_epoch: u64,
1040    #[prost(bytes = "vec", tag = "14")]
1041    proposal_admission_hash_sha256: Vec<u8>,
1042}
1043
1044#[derive(Clone, PartialEq, Message)]
1045struct WireCommitCertificateV2 {
1046    #[prost(uint32, tag = "1")]
1047    format_version: u32,
1048    #[prost(message, optional, tag = "2")]
1049    entry_core: Option<WireLogEntryCoreV2>,
1050    #[prost(message, optional, tag = "3")]
1051    resulting_state: Option<WireStateCommitmentV1>,
1052    #[prost(bytes = "vec", tag = "4")]
1053    client_proposal: Vec<u8>,
1054    #[prost(bytes = "vec", repeated, tag = "5")]
1055    voter_acknowledgements: Vec<Vec<u8>>,
1056    #[prost(bytes = "vec", optional, tag = "6")]
1057    projection_derivation: Option<Vec<u8>>,
1058    #[prost(string, tag = "7")]
1059    primary_server_id: String,
1060    #[prost(bytes = "vec", optional, tag = "8")]
1061    witness_signature: Option<Vec<u8>>,
1062    #[prost(bytes = "vec", tag = "9")]
1063    proposal_admission: Vec<u8>,
1064}
1065
1066#[derive(Clone, PartialEq, Message)]
1067struct WireCommittedHeadV2 {
1068    #[prost(uint32, tag = "1")]
1069    format_version: u32,
1070    #[prost(message, optional, tag = "2")]
1071    state: Option<WireStateCommitmentV1>,
1072    #[prost(bytes = "vec", tag = "3")]
1073    commit_certificate_hash_sha256: Vec<u8>,
1074    #[prost(string, tag = "4")]
1075    primary_server_id: String,
1076    #[prost(uint64, tag = "5")]
1077    placement_epoch: u64,
1078    #[prost(bytes = "vec", optional, tag = "6")]
1079    witness_signature: Option<Vec<u8>>,
1080}
1081
1082#[derive(Clone, PartialEq, Message)]
1083struct WireGroupDescriptorV1 {
1084    #[prost(uint32, tag = "1")]
1085    format_version: u32,
1086    #[prost(string, tag = "2")]
1087    group_id: String,
1088    #[prost(string, tag = "3")]
1089    database_id: String,
1090    #[prost(string, tag = "4")]
1091    group_kind: String,
1092    #[prost(bytes = "vec", tag = "5")]
1093    schema_hash_sha256: Vec<u8>,
1094    #[prost(bytes = "vec", optional, tag = "6")]
1095    projection_definition_hash_sha256: Option<Vec<u8>>,
1096    #[prost(bytes = "vec", tag = "7")]
1097    committed_head: Vec<u8>,
1098    #[prost(uint64, tag = "8")]
1099    trust_bundle_version: u64,
1100    #[prost(bytes = "vec", optional, tag = "9")]
1101    group_control_signature: Option<Vec<u8>>,
1102}
1103
1104#[cfg(test)]
1105mod tests {
1106    use super::*;
1107
1108    #[test]
1109    fn digest_requires_exactly_32_bytes() {
1110        assert!(Sha256Digest::try_from([0_u8; 31].as_slice()).is_err());
1111        assert!(Sha256Digest::try_from([0_u8; 32].as_slice()).is_ok());
1112        assert!(Sha256Digest::try_from([0_u8; 33].as_slice()).is_err());
1113    }
1114
1115    #[test]
1116    fn entry_hash_is_domain_separated_and_stable() {
1117        let core = LogEntryCoreV2 {
1118            database_id: DatabaseId::new("db"),
1119            group_kind: DatabaseGroupKind::Projection,
1120            log_index: 1,
1121            previous_entry_hash: Sha256Digest::ZERO,
1122            changeset_payload_hash: Sha256Digest::hash(b"changeset"),
1123            client_proposal_hash: Sha256Digest::hash(b"proposal"),
1124            database_state_root: Sha256Digest::hash(b"state"),
1125            schema_hash: Sha256Digest::hash(b"schema"),
1126            projection_definition_hash: Some(Sha256Digest::hash(b"projection")),
1127            membership_revision: 1,
1128            placement_epoch: 1,
1129            client_log_epoch: 1,
1130            proposal_admission_hash: Sha256Digest::hash(b"admission"),
1131        };
1132        assert_eq!(core.entry_hash().unwrap(), core.entry_hash().unwrap());
1133        assert_ne!(
1134            core.entry_hash().unwrap(),
1135            Sha256Digest::hash(&core.encode_deterministic().unwrap())
1136        );
1137    }
1138}