capgrok 0.3.1

Build wallet-signable messages with capability delegations that are human- and machine-readable.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150

use crate::{
    capabilities_to_statement, translation::ToResource, Capability, Error, Namespace, Set,
};

use std::collections::{BTreeMap, HashMap};

use iri_string::types::UriString;
use serde_json::Value;
use siwe::Message;

/// Augments a SIWE message with encoded capability delegations.
#[derive(Default, Debug)]
pub struct Builder {
    capabilities: BTreeMap<Namespace, Capability>,
}

impl Builder {
    /// Initialise a new Builder.
    pub fn new() -> Builder {
        Builder::default()
    }

    /// Inspect the default actions for a namespace.
    pub fn default_actions(&self, namespace: &Namespace) -> Option<&Set<String>> {
        self.capabilities
            .get(namespace)
            .as_ref()
            .map(|cap| &cap.default_actions)
    }

    /// Inspect the targeted actions for a namespace.
    pub fn actions(&self, namespace: &Namespace) -> Option<&BTreeMap<String, Set<String>>> {
        self.capabilities
            .get(namespace)
            .as_ref()
            .map(|cap| &cap.targeted_actions)
    }

    /// Inspect the extra fields for a namespace.
    pub fn extra_fields(&self, namespace: &Namespace) -> Option<&HashMap<String, Value>> {
        self.capabilities
            .get(namespace)
            .as_ref()
            .map(|cap| &cap.extra_fields)
    }

    /// Extend the set of default actions for a namespace.
    pub fn with_default_action<S>(mut self, namespace: &Namespace, action: S) -> Self
    where
        S: Into<String>,
    {
        self.namespace(namespace).default_actions.insert(action);
        self
    }

    /// Extend the set of default actions for a namespace.
    pub fn with_default_actions<I, S>(mut self, namespace: &Namespace, actions: I) -> Self
    where
        S: Into<String>,
        I: IntoIterator<Item = S>,
    {
        self.namespace(namespace)
            .default_actions
            .insert_all(actions);
        self
    }

    /// Extend the set of actions for a target in a namespace.
    pub fn with_action<T, S>(mut self, namespace: &Namespace, target: T, action: S) -> Self
    where
        T: Into<String>,
        S: Into<String>,
    {
        let target = target.into();
        if let Some(actions) = self.namespace(namespace).targeted_actions.get_mut(&target) {
            actions.insert(action);
        } else {
            self.namespace(namespace)
                .targeted_actions
                .insert(target, Set::from_iter([action]));
        }
        self
    }

    /// Extend the set of actions for a target in a namespace.
    pub fn with_actions<I, S, T>(mut self, namespace: &Namespace, target: T, actions: I) -> Self
    where
        T: Into<String>,
        S: Into<String>,
        I: IntoIterator<Item = S>,
    {
        let target = target.into();
        if let Some(current_actions) = self.namespace(namespace).targeted_actions.get_mut(&target) {
            current_actions.insert_all(actions);
        } else {
            self.namespace(namespace)
                .targeted_actions
                .insert(target, Set::from_iter(actions));
        }
        self
    }

    /// Extend the extra fields for a namespace.
    ///
    /// This function performs a simple HashMap::extend, so does not merge [`serde_json::Value`]s.
    /// Any existing fields with a key matching the incoming fields will be overwritten.
    pub fn with_extra_fields(
        mut self,
        namespace: &Namespace,
        fields: HashMap<String, Value>,
    ) -> Self {
        self.namespace(namespace).extra_fields.extend(fields);
        self
    }

    /// Augment the SIWE message with encoded capabilities.
    pub fn build(&self, mut message: Message) -> Result<Message, Error> {
        let statement = self.statement(&message.uri);
        let resources = self
            .capabilities
            .iter()
            .map(|cap| cap.to_resource())
            .collect::<Result<Vec<UriString>, Error>>()?;

        message.statement = match (message.statement, statement) {
            (s, None) => s,
            (None, s) => s,
            (Some(s), Some(t)) => Some(format!("{} {}", s, t)),
        };

        message.resources.extend(resources);

        Ok(message)
    }

    /// Generate a CapGrok statement from capabilities and URI.
    pub fn statement(&self, uri: &UriString) -> Option<String> {
        capabilities_to_statement(&self.capabilities, uri)
    }

    fn namespace(&mut self, namespace: &Namespace) -> &mut Capability {
        if !self.capabilities.contains_key(namespace) {
            self.capabilities
                .insert(namespace.clone(), Capability::default());
        }

        // Safety: it has just been inserted or already exists, so can be safely unwrapped.
        self.capabilities.get_mut(namespace).unwrap()
    }
}