Skip to main content

coven_format/
objects.rs

1//! Signed join request frames (D8).
2
3use crate::admin::{MemberPublicKeys, NewCircle};
4use crate::codes::InviteAdmits;
5use crate::error::{require, Error, Rule};
6use crate::sealed_key::CopyBox;
7use crate::value::name;
8use crate::wire::{wire_struct, Decoder, Encoder, Wire};
9use coven_foundation::id_source::{DeviceId, InviteId, MemberId};
10use coven_merge::Audience;
11
12/// A new person's request, encrypted with the invite-derived key and signed (§13.2).
13#[derive(Clone, Debug, PartialEq, Eq)]
14pub struct JoinRequest {
15    /// The invite this request answers.
16    pub invite: InviteId,
17    /// The member id fixed by the invite: fresh for an addition, or the
18    /// existing member's for a re-binding (D8, D13).
19    pub member: MemberId,
20    /// The requested public pair; it verifies this request's signature.
21    pub keys: MemberPublicKeys,
22    /// The joining installation's own id, fixed when the join begins: the
23    /// approval registers it (D6).
24    pub device: DeviceId,
25    /// The new device's name shown to the approving admin.
26    pub device_name: String,
27    /// Who asks: a new person with the name they typed, or a member
28    /// recovering.
29    pub joiner: Joiner,
30}
31wire_struct!(JoinRequest, invite, member, keys, device, device_name => crate::wire::get_name, joiner);
32impl JoinRequest {
33    pub(crate) fn validate(&self) -> Result<(), Error> {
34        name(&self.device_name)?;
35        self.joiner.validate()
36    }
37}
38
39/// The circle a joining person's request makes, for the admission to make in
40/// its own slot (§13.2, D8): its id, name, base version and key commitment,
41/// and the key's only copy, which the joining phone sealed to its own new
42/// sealing key. The key is kept nowhere else, so the approving admin never
43/// holds it.
44#[derive(Clone, Debug, PartialEq, Eq)]
45pub struct JoiningCircle {
46    /// The circle and its key's commitment, which the admission repeats.
47    pub circle: NewCircle,
48    /// The key's copy for the joining member, sealed with the own-copy
49    /// context (D11); the admission's clear prefix carries it verbatim.
50    pub copy: CopyBox,
51}
52wire_struct!(JoiningCircle, circle, copy);
53impl JoiningCircle {
54    fn validate(&self) -> Result<(), Error> {
55        self.circle.validate()?;
56        // The copy is the key the circle commits to, for the circle it makes.
57        require(
58            self.copy.routing.audience == Audience::Circle(self.circle.circle)
59                && self.copy.routing.key == self.circle.key,
60            "joining circle copy",
61            Rule::Audience,
62        )
63    }
64}
65
66/// Who a join request is for (§13.2). The invite's kind fixes which a request
67/// may carry, and a pairing takes `OwnDevice` alone.
68#[derive(Clone, Debug, PartialEq, Eq)]
69pub enum Joiner {
70    /// A new person, with the name they typed: the admin sees it with the
71    /// request, and the admission records it for the app's joining write.
72    NewPerson {
73        /// The name, which follows the `name` rule (D2).
74        name: String,
75        /// The circle the admission makes for them.
76        circle: JoiningCircle,
77    },
78    /// An existing member, whose profile already has a name: the request
79    /// carries none, and a circle to replace the private one they can no
80    /// longer read.
81    MemberKeys {
82        /// The circle the recovery makes for them.
83        circle: JoiningCircle,
84    },
85    /// The member's own new device, asking one of their devices to pair it:
86    /// the request carries no name.
87    OwnDevice,
88}
89impl Joiner {
90    /// What the invite this request answers admits; none for a member's own
91    /// device, which no invite has.
92    pub fn admits(&self) -> Option<InviteAdmits> {
93        match self {
94            Self::NewPerson { .. } => Some(InviteAdmits::NewPerson),
95            Self::MemberKeys { .. } => Some(InviteAdmits::MemberKeys),
96            Self::OwnDevice => None,
97        }
98    }
99    /// The name the request carries, which a new person typed; none for a
100    /// member's keys and for a member's own device.
101    pub fn person(&self) -> Option<&str> {
102        match self {
103            Self::NewPerson { name, .. } => Some(name),
104            Self::MemberKeys { .. } | Self::OwnDevice => None,
105        }
106    }
107    /// The circle the request makes; none for a member's own device.
108    pub fn circle(&self) -> Option<&JoiningCircle> {
109        match self {
110            Self::NewPerson { circle, .. } | Self::MemberKeys { circle } => Some(circle),
111            Self::OwnDevice => None,
112        }
113    }
114    fn validate(&self) -> Result<(), Error> {
115        match self {
116            Self::NewPerson { name: person, circle } => {
117                name(person)?;
118                circle.validate()
119            }
120            Self::MemberKeys { circle } => circle.validate(),
121            Self::OwnDevice => Ok(()),
122        }
123    }
124}
125impl Wire for Joiner {
126    fn put(&self, out: &mut Encoder) -> Result<(), Error> {
127        match self {
128            Self::MemberKeys { circle } => {
129                0u8.put(out)?;
130                circle.put(out)
131            }
132            Self::NewPerson { name: person, circle } => {
133                1u8.put(out)?;
134                person.put(out)?;
135                circle.put(out)
136            }
137            Self::OwnDevice => 2u8.put(out),
138        }
139    }
140    fn get(input: &mut Decoder<'_>) -> Result<Self, Error> {
141        match u8::get(input)? {
142            0 => Ok(Self::MemberKeys { circle: JoiningCircle::get(input)? }),
143            1 => Ok(Self::NewPerson {
144                name: crate::wire::get_name(input)?,
145                circle: JoiningCircle::get(input)?,
146            }),
147            2 => Ok(Self::OwnDevice),
148            tag => Err(Error::UnknownTag { field: "joiner", tag }),
149        }
150    }
151}
152
153#[cfg(test)]
154#[path = "objects_tests.rs"]
155mod tests;