Skip to main content

coven_format/
lib.rs

1//! Versioned plaintext frames and streaming sealed-object layouts (Appendix F.1).
2//!
3//! No I/O, clock, randomness or signing occurs here. File chunks compose
4//! crypto with validated headers and ranges. Plaintext frames
5//! are bounded; writes and snapshots stream without an object-size bound.
6//! `spec/format.md` specifies stored bytes.
7
8pub mod admin;
9pub mod authorship;
10pub mod chunks;
11pub mod code_fields;
12pub mod codes;
13pub mod coordinates;
14pub mod device_gone;
15pub mod dismissal;
16pub mod error;
17pub mod file;
18pub mod file_reference;
19pub mod floor;
20pub mod floor_pointer;
21pub mod handover;
22pub mod invite_end;
23pub mod key;
24mod kinds;
25pub mod loss;
26pub mod merge_fields;
27mod merge_wire;
28pub mod objects;
29pub mod path;
30mod sealed;
31pub mod sealed_floor;
32pub mod sealed_key;
33pub mod sealed_single;
34pub mod sealed_slot;
35pub mod sealed_snapshot;
36pub mod sealed_stream;
37pub mod sealed_write;
38pub mod sequence;
39pub mod snapshot;
40pub mod snapshot_rows;
41pub mod snapshot_stream;
42pub mod value;
43mod version;
44mod wire;
45pub mod write;
46pub mod write_sources;
47pub mod write_stream;
48pub mod writes_slot;
49
50#[cfg(any(test, feature = "test-utils"))]
51pub mod test_utils;
52
53pub use error::Error;
54pub use sealed::STORED_CHUNK_OVERHEAD;
55pub use version::{FormatVersion, RequiredUpdate};
56
57use admin::StoreChange;
58use error::bound;
59use objects::JoinRequest;
60use wire::{decode_frame, Encoder, Wire, MAX_OBJECT};
61
62/// The object format written and read by coven (format.md).
63pub const FORMAT_VERSION: u16 = FormatVersion::CURRENT.number();
64/// The fixed prefix length: kind, format version, payload length.
65pub const FRAME_PREFIX_LEN: usize = 7;
66
67/// Independently decoded plaintext objects. Writes use [`write_stream::WriteEncoder`];
68/// snapshots use [`snapshot::SnapshotDecoder`]
69/// with merge metadata; restore and invite codes use their zeroizing byte APIs.
70#[derive(Clone, Debug, PartialEq, Eq)]
71pub enum Object {
72    /// One membership, device, circle, version or reset entry (§10).
73    Admin(StoreChange),
74    /// A new person's public keys and device name (§13.2).
75    JoinRequest(JoinRequest),
76}
77
78impl Object {
79    /// Checks structure and returns the one canonical byte string for this value.
80    pub fn encode(&self) -> Result<Vec<u8>, Error> {
81        self.encode_in(FormatVersion::CURRENT)
82    }
83
84    /// Encode in the format recorded for an attempted object, preserving its bytes.
85    pub fn encode_in(&self, format: FormatVersion) -> Result<Vec<u8>, Error> {
86        self.validate()?;
87        let FormatVersion::V1 = format;
88        match self {
89            Self::Admin(v) => encode_frame_in(kinds::ADMIN, format, |out| v.put(out)),
90            Self::JoinRequest(v) => {
91                encode_frame_in(kinds::JOIN_REQUEST_FRAME, format, |out| v.put(out))
92            }
93        }
94    }
95    /// Decodes exactly one bounded frame, refusing unknown tags/versions, trailing
96    /// bytes, noncanonical sets and structurally invalid records. Authentication
97    /// and checks requiring other writes or a database belong to their owners.
98    pub fn decode(bytes: &[u8]) -> Result<Self, Error> {
99        let (kind, mut input) = decode_frame(bytes)?;
100        let object = match kind {
101            kinds::ADMIN => Self::Admin(Wire::get(&mut input)?),
102            kinds::JOIN_REQUEST_FRAME => Self::JoinRequest(Wire::get(&mut input)?),
103            tag => return Err(Error::UnknownTag { field: "object kind", tag }),
104        };
105        input.finish()?;
106        object.validate()?;
107        Ok(object)
108    }
109    fn validate(&self) -> Result<(), Error> {
110        match self {
111            Self::Admin(v) => v.validate(),
112            Self::JoinRequest(v) => v.validate(),
113        }
114    }
115}
116
117/// Checks the seven-byte prefix and returns the full frame length, capped at
118/// 16 MiB, before a caller allocates or fetches its payload. Extra supplied bytes
119/// are ignored here; [`Object::decode`] requires exactly one complete frame.
120pub fn frame_length(prefix: &[u8]) -> Result<usize, Error> {
121    let bytes = prefix.get(..3).ok_or(Error::Truncated)?;
122    if !kinds::is_frame(bytes[0]) {
123        return Err(Error::UnknownTag { field: "object kind", tag: bytes[0] });
124    }
125    let FormatVersion::V1 = FormatVersion::decode(bytes)?;
126    let bytes = prefix.get(..FRAME_PREFIX_LEN).ok_or(Error::Truncated)?;
127    let size = u32::from_be_bytes([bytes[3], bytes[4], bytes[5], bytes[6]]) as usize;
128    bound(size, MAX_OBJECT - FRAME_PREFIX_LEN, "frame payload")?;
129    Ok(size + FRAME_PREFIX_LEN)
130}
131
132pub(crate) fn encode_frame<T: Wire>(kind: u8, value: &T) -> Result<Vec<u8>, Error> {
133    encode_frame_with(kind, |out| value.put(out))
134}
135
136pub(crate) fn encode_frame_with(
137    kind: u8,
138    put: impl FnOnce(&mut Encoder) -> Result<(), Error>,
139) -> Result<Vec<u8>, Error> {
140    encode_frame_in(kind, FormatVersion::CURRENT, put)
141}
142
143/// The seven clear bytes that start a frame: `kind | version | payload length`.
144pub(crate) fn frame_prefix(
145    kind: u8,
146    format: FormatVersion,
147    payload: u32,
148) -> [u8; FRAME_PREFIX_LEN] {
149    let [a, b, c] = format.prefix(kind);
150    let [d, e, f, g] = payload.to_be_bytes();
151    [a, b, c, d, e, f, g]
152}
153
154fn encode_frame_in(
155    kind: u8,
156    format: FormatVersion,
157    put: impl FnOnce(&mut Encoder) -> Result<(), Error>,
158) -> Result<Vec<u8>, Error> {
159    let mut out = Encoder::new();
160    out.bytes(&frame_prefix(kind, format, 0))?;
161    put(&mut out)?;
162    let size = (out.bytes.len() - FRAME_PREFIX_LEN) as u32;
163    out.bytes[3..7].copy_from_slice(&size.to_be_bytes());
164    Ok(out.bytes)
165}
166
167#[cfg(test)]
168#[path = "lib_tests.rs"]
169mod tests;
170
171mod member_access;
172pub use member_access::{BothAccesses, MemberAccess};