Skip to main content

sapphire_framework_server/api_keys/
import.rs

1//! The one-time import of the workgroup's external devices (#199) into the workspace's API
2//! keys (#364).
3//!
4//! The ledger is read straight from the bridge's directory, read-only, so the bridge need
5//! not run. Every host imports the same records under the same ids, so hosts that import at
6//! once agree once the workspace syncs.
7
8#![allow(deprecated)]
9
10use std::path::Path;
11
12use corundum_framework_keys::{Error as KeyError, Key, KeyHash, KeyId, ProfileId};
13use sapphire_framework_keys::open_store;
14use sapphire_registry::ExternalDevices;
15
16/// The marker in the application's data directory that says this host has imported.
17pub const IMPORTED_MARKER: &str = "api_keys_imported";
18
19/// What an import did.
20#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
21pub struct ImportReport {
22    /// Records copied into the workspace.
23    pub imported: usize,
24    /// Records the workspace already had (another host imported them).
25    pub skipped: usize,
26}
27
28/// Copy the unretired external devices that may use `app_name`, from every workgroup in
29/// `bridge_dir`, into the API keys of the workspace at `root`, keeping their ids and hashes;
30/// then write [`IMPORTED_MARKER`] into `data_dir`. Does nothing when the marker is there.
31///
32/// A missing bridge directory is nothing to import yet, and writes no marker: a bridge not
33/// run since its directory moved has it later. An error leaves no marker either, so the next
34/// start tries again.
35pub fn import_external_devices(
36    app_name: &str,
37    data_dir: &Path,
38    bridge_dir: &Path,
39    root: &Path,
40) -> Result<ImportReport, String> {
41    let marker = data_dir.join(IMPORTED_MARKER);
42    if marker.exists() {
43        return Ok(ImportReport::default());
44    }
45    let mut report = ImportReport::default();
46    if !root.join(format!(".{app_name}")).is_dir() {
47        // A workspace moved away or not mounted yet: never recreate it; import into it
48        // once it is back.
49        return Ok(report);
50    }
51    let workgroups = bridge_dir.join("workgroups");
52    if !bridge_dir.exists() {
53        // No bridge here, or one not run since its directory moved: look again next time.
54        return Ok(report);
55    }
56    let entries = match std::fs::read_dir(&workgroups) {
57        Ok(entries) => entries.collect::<Result<Vec<_>, _>>(),
58        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(Vec::new()),
59        Err(err) => Err(err),
60    }
61    .map_err(|e| format!("{}: {e}", workgroups.display()))?;
62    let mut store = None;
63    // As the bridge's own `Workgroup::find`: only directories named by a grain id are
64    // workgroups (not `.DS_Store`, not a leftover temporary file).
65    let workgroups = entries.into_iter().filter(|e| {
66        e.path().is_dir()
67            && e.file_name()
68                .to_str()
69                .is_some_and(|n| n.parse::<sapphire_registry::GrainId>().is_ok())
70    });
71    for workgroup in workgroups {
72        let ledger_dir = workgroup.path().join("root").join("external_devices");
73        let ledger = ExternalDevices::open(&ledger_dir)
74            .map_err(|e| format!("{}: {e}", ledger_dir.display()))?;
75        for device in ledger
76            .entries()
77            .iter()
78            .filter(|d| !d.is_retired() && d.allows(app_name))
79        {
80            let store = match &mut store {
81                Some(store) => store,
82                None => store.insert(open_store(app_name, root).map_err(|e| e.to_string())?),
83            };
84            let key = Key {
85                id: KeyId::new(&device.id.to_string()).map_err(|e| e.to_string())?,
86                name: device.name.clone(),
87                description: device.description.clone(),
88                // The least: what a key may do is chosen again, by adding one.
89                profile: ProfileId::new(sapphire_framework_keys::MIGRATED)
90                    .map_err(|e| e.to_string())?,
91                hash: format!("sha256:{}", device.token_sha256)
92                    .parse::<KeyHash>()
93                    .map_err(|e| e.to_string())?,
94                created_at: device.created_at,
95                rotated_at: device.rotated_at,
96                retired_at: None,
97            };
98            match store.import(key) {
99                Ok(_) => report.imported += 1,
100                Err(KeyError::IdTaken(_)) => report.skipped += 1,
101                Err(err) => return Err(err.to_string()),
102            }
103        }
104    }
105    std::fs::create_dir_all(data_dir)
106        .and_then(|()| std::fs::write(&marker, ""))
107        .map_err(|e| format!("{}: {e}", marker.display()))?;
108    Ok(report)
109}
110
111#[cfg(test)]
112mod tests {
113    use super::*;
114    use sapphire_registry::GrainId;
115
116    const APP: &str = "sapphire-importtest";
117
118    struct Fixture {
119        _tmp: tempfile::TempDir,
120        data: std::path::PathBuf,
121        bridge: std::path::PathBuf,
122        root: std::path::PathBuf,
123        ledger: ExternalDevices,
124    }
125
126    fn fixture() -> Fixture {
127        let tmp = tempfile::tempdir().unwrap();
128        let data = tmp.path().join("data");
129        let bridge = tmp.path().join("bridge");
130        let root = tmp.path().join("ws");
131        std::fs::create_dir_all(&data).unwrap();
132        // A workspace: its app directory is there.
133        std::fs::create_dir_all(root.join(format!(".{APP}"))).unwrap();
134        let wg = GrainId::random();
135        let ledger = ExternalDevices::open(
136            &bridge
137                .join("workgroups")
138                .join(wg.to_string())
139                .join("root")
140                .join("external_devices"),
141        )
142        .unwrap();
143        Fixture {
144            _tmp: tmp,
145            data,
146            bridge,
147            root,
148            ledger,
149        }
150    }
151
152    fn run(f: &Fixture) -> Result<ImportReport, String> {
153        import_external_devices(APP, &f.data, &f.bridge, &f.root)
154    }
155
156    #[test]
157    fn imports_unretired_records_for_this_app() {
158        let mut f = fixture();
159        let (mine, token) = f.ledger.add("pendant", None, vec![APP.into()]).unwrap();
160        f.ledger
161            .add("other", None, vec!["sapphire-other".into()])
162            .unwrap();
163        f.ledger.add("gone", None, vec![APP.into()]).unwrap();
164        f.ledger.retire("gone").unwrap();
165
166        let report = run(&f).unwrap();
167        assert_eq!(report.imported, 1);
168        let store = open_store(APP, &f.root).unwrap();
169        let key = store
170            .authenticate(token.expose())
171            .expect("the old token works");
172        assert_eq!(key.id.as_str(), mine.id.to_string());
173        assert_eq!(key.name, "pendant");
174        assert_eq!(
175            key.profile.as_str(),
176            "read-only",
177            "the least, as before profiles"
178        );
179        assert_eq!(store.list().len(), 1);
180        assert!(f.data.join(IMPORTED_MARKER).is_file());
181    }
182
183    #[test]
184    fn second_run_does_nothing() {
185        let mut f = fixture();
186        f.ledger.add("pendant", None, vec![APP.into()]).unwrap();
187        run(&f).unwrap();
188        std::fs::remove_dir_all(sapphire_framework_keys::store_dir(APP, &f.root)).unwrap();
189        assert_eq!(run(&f).unwrap(), ImportReport::default());
190        assert!(!sapphire_framework_keys::store_dir(APP, &f.root).exists());
191    }
192
193    #[test]
194    fn existing_id_is_skipped() {
195        let mut f = fixture();
196        let (d, _) = f.ledger.add("pendant", None, vec![APP.into()]).unwrap();
197        // Another host imported it, and the workspace synced.
198        let mut store = open_store(APP, &f.root).unwrap();
199        let (mut key, _) = store
200            .add("placeholder", None, ProfileId::new("read-only").unwrap())
201            .unwrap();
202        key.id = KeyId::new(&d.id.to_string()).unwrap();
203        store.import(key).unwrap();
204
205        let report = run(&f).unwrap();
206        assert_eq!(
207            report,
208            ImportReport {
209                imported: 0,
210                skipped: 1
211            }
212        );
213        assert!(f.data.join(IMPORTED_MARKER).is_file());
214    }
215
216    #[test]
217    fn missing_bridge_dir_imports_nothing_and_tries_again_later() {
218        let f = fixture();
219        // Nothing was added, so no ledger, and no bridge directory, was ever written.
220        assert!(!f.bridge.exists());
221        assert_eq!(run(&f).unwrap(), ImportReport::default());
222        // A bridge not run since its directory moved (Windows' Roaming to Local) has it
223        // later: no marker yet.
224        assert!(!f.data.join(IMPORTED_MARKER).exists());
225    }
226
227    #[cfg(unix)]
228    #[test]
229    fn failure_leaves_no_marker() {
230        use std::os::unix::fs::PermissionsExt as _;
231        let mut f = fixture();
232        f.ledger.add("pendant", None, vec![APP.into()]).unwrap();
233        let app_dir = f.root.join(format!(".{APP}"));
234        std::fs::create_dir_all(&app_dir).unwrap();
235        std::fs::set_permissions(&app_dir, std::fs::Permissions::from_mode(0o500)).unwrap();
236        let result = run(&f);
237        std::fs::set_permissions(&app_dir, std::fs::Permissions::from_mode(0o700)).unwrap();
238        assert!(result.is_err());
239        assert!(!f.data.join(IMPORTED_MARKER).exists());
240    }
241
242    #[test]
243    fn a_missing_workspace_gets_nothing_and_no_marker() {
244        let mut f = fixture();
245        f.ledger.add("pendant", None, vec![APP.into()]).unwrap();
246        let gone = f.root.join("moved-away");
247        let result = import_external_devices(APP, &f.data, &f.bridge, &gone);
248        assert_eq!(result.unwrap(), ImportReport::default());
249        assert!(!gone.exists(), "the workspace must not be recreated");
250        assert!(!f.data.join(IMPORTED_MARKER).exists());
251    }
252
253    #[test]
254    fn a_stray_entry_in_workgroups_is_skipped() {
255        let mut f = fixture();
256        f.ledger.add("pendant", None, vec![APP.into()]).unwrap();
257        std::fs::write(f.bridge.join("workgroups").join(".DS_Store"), "x").unwrap();
258        std::fs::create_dir_all(f.bridge.join("workgroups").join("not-a-workgroup")).unwrap();
259        assert_eq!(run(&f).unwrap().imported, 1);
260        assert!(f.data.join(IMPORTED_MARKER).is_file());
261    }
262}