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}