1use std::io::Write;
6use std::path::Path;
7
8use age::x25519::{Identity, Recipient};
9use anyhow::{Context, bail};
10use base64::Engine;
11use base64::engine::general_purpose::STANDARD;
12use serde::{Deserialize, Serialize};
13use serde_json::Value;
14
15pub const DIR_NAME: &str = "queue";
18
19const PLAIN_SUFFIX: &str = ".json";
20const SEALED_SUFFIX: &str = ".sealed";
24
25pub fn is_entry_name(name: &str) -> bool {
29 let Some(stem) = name
30 .strip_suffix(PLAIN_SUFFIX)
31 .or_else(|| name.strip_suffix(SEALED_SUFFIX))
32 else {
33 return false;
34 };
35 let Some((nanos, id)) = stem.split_at_checked(19) else {
36 return false;
37 };
38 nanos.bytes().all(|b| b.is_ascii_digit())
39 && id
40 .strip_prefix('-')
41 .is_some_and(|id| id.len() == 36 && uuid::Uuid::parse_str(id).is_ok())
42}
43
44pub fn is_sealed_name(name: &str) -> bool {
45 name.ends_with(SEALED_SUFFIX) && is_entry_name(name)
46}
47
48pub fn entry_name(nanos: u128, sealed: bool) -> String {
50 let suffix = if sealed { SEALED_SUFFIX } else { PLAIN_SUFFIX };
51 format!("{nanos:019}-{}{suffix}", uuid::Uuid::new_v4())
52}
53
54#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
56pub struct Entry {
57 pub tool: String,
58 pub method: String,
59 pub path: String,
60 #[serde(default)]
62 pub query: Option<String>,
63 #[serde(default)]
64 pub body: Option<Value>,
65}
66
67#[derive(Debug, Clone, PartialEq, Default, Serialize, Deserialize)]
69pub struct Label {
70 pub tool: String,
71 pub method: String,
72 pub path: String,
73 #[serde(default, skip_serializing_if = "Option::is_none")]
75 pub source: Option<String>,
76 #[serde(default, skip_serializing_if = "Option::is_none")]
79 pub session_id: Option<String>,
80 #[serde(default, skip_serializing_if = "Option::is_none")]
81 pub kind: Option<String>,
82}
83
84#[derive(Serialize, Deserialize)]
85struct SealedFile {
86 #[serde(flatten)]
87 label: Label,
88 sealed: String,
89}
90
91#[derive(Deserialize)]
92struct StoredFile {
93 #[serde(flatten)]
94 label: Label,
95 #[serde(default)]
96 sealed: Option<String>,
97 #[serde(default)]
98 query: Option<String>,
99 #[serde(default)]
100 body: Option<Value>,
101}
102
103#[derive(Debug)]
104pub enum OpenError {
105 NoKey,
107 Unreadable(anyhow::Error),
108}
109
110impl std::fmt::Display for OpenError {
111 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
112 match self {
113 Self::NoKey => f.write_str("the entry is sealed and the device key is unavailable"),
114 Self::Unreadable(e) => write!(f, "{e:#}"),
115 }
116 }
117}
118
119impl std::error::Error for OpenError {}
120
121impl Entry {
122 pub fn label(&self) -> Label {
123 let field = |name: &str| {
124 self.body
125 .as_ref()
126 .and_then(|b| b.get(name))
127 .and_then(Value::as_str)
128 .map(str::to_string)
129 };
130 let (source, session_id, kind) = match self.tool.as_str() {
131 "ingest" => (field("source"), None, None),
132 "note" => (None, field("session_id"), field("kind")),
133 _ => (None, None, None),
134 };
135 Label {
136 tool: self.tool.clone(),
137 method: self.method.clone(),
138 path: self.path.clone(),
139 source,
140 session_id,
141 kind,
142 }
143 }
144
145 pub fn to_plain_file(&self) -> anyhow::Result<Vec<u8>> {
146 Ok(serde_json::to_vec(self)?)
147 }
148
149 pub fn to_sealed_file(&self, recipients: &[Recipient]) -> anyhow::Result<Vec<u8>> {
152 if recipients.is_empty() {
153 bail!("sealing a queued write needs a recipient");
154 }
155 let encryptor =
156 age::Encryptor::with_recipients(recipients.iter().map(|r| r as &dyn age::Recipient))
157 .context("sealing a queued write")?;
158 let mut ciphertext = Vec::new();
159 let mut writer = encryptor.wrap_output(&mut ciphertext)?;
160 writer.write_all(&serde_json::to_vec(self)?)?;
161 writer.finish()?;
162 Ok(serde_json::to_vec(&SealedFile {
163 label: self.label(),
164 sealed: STANDARD.encode(ciphertext),
165 })?)
166 }
167}
168
169pub fn open(bytes: &[u8], identity: Option<&Identity>) -> Result<Entry, OpenError> {
171 let stored: StoredFile =
172 serde_json::from_slice(bytes).map_err(|e| OpenError::Unreadable(e.into()))?;
173 let Some(sealed) = stored.sealed else {
174 return Ok(Entry {
175 tool: stored.label.tool,
176 method: stored.label.method,
177 path: stored.label.path,
178 query: stored.query,
179 body: stored.body,
180 });
181 };
182 let identity = identity.ok_or(OpenError::NoKey)?;
183 let opened = STANDARD
184 .decode(sealed)
185 .context("decoding a sealed queued write")
186 .and_then(|ciphertext| {
187 age::decrypt(identity, &ciphertext).context("opening a sealed queued write")
188 })
189 .and_then(|plain| Ok(serde_json::from_slice(&plain)?))
190 .map_err(OpenError::Unreadable)?;
191 Ok(opened)
192}
193
194pub fn reseal_dir(dir: &Path, old: &Identity, recipients: &[Recipient]) -> anyhow::Result<usize> {
200 let items = match std::fs::read_dir(dir) {
201 Ok(items) => items,
202 Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(0),
203 Err(e) => return Err(e).with_context(|| format!("listing {}", dir.display())),
204 };
205 let mut resealed = 0;
206 for item in items {
207 let name = item?.file_name().to_string_lossy().into_owned();
208 if !is_sealed_name(&name) {
209 continue;
210 }
211 let path = dir.join(&name);
212 let bytes = match std::fs::read(&path) {
213 Ok(bytes) => bytes,
214 Err(e) if e.kind() == std::io::ErrorKind::NotFound => continue,
215 Err(e) => {
216 tracing::warn!("cannot reseal {}: {e}", path.display());
217 continue;
218 }
219 };
220 let Ok(entry) = open(&bytes, Some(old)) else {
221 continue;
222 };
223 replace_file(dir, &name, &entry.to_sealed_file(recipients)?)?;
224 resealed += 1;
225 }
226 if resealed > 0 {
227 std::fs::File::open(dir)
228 .and_then(|d| d.sync_all())
229 .with_context(|| format!("syncing {}", dir.display()))?;
230 }
231 Ok(resealed)
232}
233
234fn replace_file(dir: &Path, name: &str, bytes: &[u8]) -> anyhow::Result<()> {
235 let tmp = dir.join(format!("{name}.{}.tmp", uuid::Uuid::new_v4().simple()));
236 let mut options = std::fs::OpenOptions::new();
237 options.write(true).create_new(true);
238 #[cfg(unix)]
239 std::os::unix::fs::OpenOptionsExt::mode(&mut options, 0o600);
240 let written = options
241 .open(&tmp)
242 .and_then(|mut file| {
243 file.write_all(bytes)?;
244 file.sync_all()
245 })
246 .and_then(|()| std::fs::rename(&tmp, dir.join(name)));
247 if let Err(e) = written {
248 if let Err(cleanup) = std::fs::remove_file(&tmp)
249 && cleanup.kind() != std::io::ErrorKind::NotFound
250 {
251 tracing::warn!("cannot remove {}: {cleanup}", tmp.display());
252 }
253 return Err(e).with_context(|| format!("resealing {}", dir.join(name).display()));
254 }
255 Ok(())
256}
257
258pub fn read_label(bytes: &[u8]) -> anyhow::Result<Label> {
260 let stored: StoredFile = serde_json::from_slice(bytes)?;
261 if stored.sealed.is_some() {
262 return Ok(stored.label);
263 }
264 Ok(Entry {
265 tool: stored.label.tool,
266 method: stored.label.method,
267 path: stored.label.path,
268 query: stored.query,
269 body: stored.body,
270 }
271 .label())
272}
273
274#[cfg(test)]
275mod tests {
276 use serde_json::json;
277
278 use super::*;
279
280 fn note() -> Entry {
281 Entry {
282 tool: "note".to_string(),
283 method: "POST".to_string(),
284 path: "/v1/notes".to_string(),
285 query: None,
286 body: Some(json!({
287 "session_id": "s-1",
288 "kind": "session_end",
289 "content": "the plan for the migration",
290 })),
291 }
292 }
293
294 fn forget() -> Entry {
295 Entry {
296 tool: "forget".to_string(),
297 method: "DELETE".to_string(),
298 path: "/v1/memory/m-1".to_string(),
299 query: Some("hard=true&reason=leaked+the+password".to_string()),
300 body: None,
301 }
302 }
303
304 #[test]
305 fn only_timestamped_uuid_entry_names_count() {
306 let id = "0b5c2f9e-5d0e-4c1a-9a57-0c7f4f1f2a10";
307 assert!(is_entry_name(&format!("1793505622000000000-{id}.json")));
308 assert!(is_entry_name(&format!("1793505622000000000-{id}.sealed")));
309 for name in [
310 "projects.json".to_string(),
311 ".lock".to_string(),
312 format!("1793505622000000000-{id}.json.tmp"),
313 format!("1793505622000000000-{id}.sealed.tmp"),
314 format!("179350562200000000-{id}.json"),
315 format!("1793505622000000000-{id}.unreadable"),
316 format!("1793505622000000000-{id}.sealed.json"),
317 "1793505622000000000-not-a-uuid.json".to_string(),
318 ] {
319 assert!(!is_entry_name(&name), "{name}");
320 }
321 assert!(is_entry_name(&entry_name(7, true)));
322 assert!(is_sealed_name(&entry_name(7, true)));
323 assert!(!is_sealed_name(&entry_name(7, false)));
324 assert!(entry_name(7, true).ends_with(".sealed"));
325 assert!(entry_name(7, false).ends_with(".json"));
326 assert!(entry_name(7, false).starts_with("0000000000000000007-"));
327 }
328
329 #[test]
330 fn a_sealed_entry_shows_only_its_label_and_opens_with_the_device_key() {
331 let identity = Identity::generate();
332 for entry in [note(), forget()] {
333 let file = entry.to_sealed_file(&[identity.to_public()]).unwrap();
334 let text = String::from_utf8_lossy(&file);
335 for secret in ["migration", "password", "reason", "content"] {
336 assert!(!text.contains(secret), "{secret} in {text}");
337 }
338 assert_eq!(read_label(&file).unwrap(), entry.label());
339 assert_eq!(open(&file, Some(&identity)).unwrap(), entry);
340 assert!(matches!(open(&file, None), Err(OpenError::NoKey)));
341 assert!(matches!(
342 open(&file, Some(&Identity::generate())),
343 Err(OpenError::Unreadable(_))
344 ));
345 }
346 }
347
348 #[test]
349 fn a_plaintext_entry_from_an_older_binary_opens_without_a_key() {
350 let older = br#"{"tool":"note","method":"POST","path":"/v1/notes","query":null,"body":{"session_id":"s-1","kind":"session_end","content":"x"}}"#;
351 assert_eq!(
352 open(older, None).unwrap().body,
353 note().body.map(|mut b| {
354 b["content"] = json!("x");
355 b
356 })
357 );
358 let label = read_label(older).unwrap();
359 assert_eq!(label.session_id.as_deref(), Some("s-1"));
360 assert_eq!(label.kind.as_deref(), Some("session_end"));
361 let entry = forget();
362 assert_eq!(open(&entry.to_plain_file().unwrap(), None).unwrap(), entry);
363 }
364
365 #[test]
366 fn labels_carry_an_ingests_source_and_a_notes_session_only() {
367 let ingest = Entry {
368 tool: "ingest".to_string(),
369 method: "POST".to_string(),
370 path: "/v1/ingest".to_string(),
371 query: None,
372 body: Some(json!({ "source": "cursor", "session_id": "s-1" })),
373 };
374 let label = ingest.label();
375 assert_eq!(label.source.as_deref(), Some("cursor"));
376 assert_eq!(label.session_id, None);
377 let note = note().label();
378 assert_eq!(
379 (
380 note.source,
381 note.session_id.as_deref(),
382 note.kind.as_deref()
383 ),
384 (None, Some("s-1"), Some("session_end"))
385 );
386 let remember = Entry {
387 tool: "remember".to_string(),
388 body: Some(json!({ "session_id": "s-1", "source": "x" })),
389 ..forget()
390 };
391 assert_eq!(
392 remember.label(),
393 Label {
394 tool: "remember".to_string(),
395 method: "DELETE".to_string(),
396 path: "/v1/memory/m-1".to_string(),
397 ..Label::default()
398 }
399 );
400 }
401
402 #[test]
403 fn a_sealed_entry_opens_with_any_of_its_recipients() {
404 let (a, b) = (Identity::generate(), Identity::generate());
405 let file = forget()
406 .to_sealed_file(&[a.to_public(), b.to_public()])
407 .unwrap();
408 assert_eq!(open(&file, Some(&a)).unwrap(), forget());
409 assert_eq!(open(&file, Some(&b)).unwrap(), forget());
410 assert!(forget().to_sealed_file(&[]).is_err());
411 }
412
413 #[test]
414 fn resealing_moves_what_the_old_key_opens_to_the_new_recipients() {
415 let dir = tempfile::tempdir().unwrap();
416 let (old, fresh, stranger) = (
417 Identity::generate(),
418 Identity::generate(),
419 Identity::generate(),
420 );
421 let ours = entry_name(1, true);
422 let theirs = entry_name(2, true);
423 let plain = entry_name(3, false);
424 let write =
425 |name: &str, bytes: Vec<u8>| std::fs::write(dir.path().join(name), bytes).unwrap();
426 write(&ours, note().to_sealed_file(&[old.to_public()]).unwrap());
427 write(
428 &theirs,
429 forget().to_sealed_file(&[stranger.to_public()]).unwrap(),
430 );
431 write(&plain, forget().to_plain_file().unwrap());
432
433 let resealed = reseal_dir(dir.path(), &old, &[fresh.to_public()]).unwrap();
434 assert_eq!(resealed, 1);
435 let read = |name: &str| std::fs::read(dir.path().join(name)).unwrap();
436 assert_eq!(open(&read(&ours), Some(&fresh)).unwrap(), note());
437 assert!(open(&read(&ours), Some(&old)).is_err());
438 assert_eq!(open(&read(&theirs), Some(&stranger)).unwrap(), forget());
439 assert_eq!(open(&read(&plain), None).unwrap(), forget());
440 let names: Vec<_> = std::fs::read_dir(dir.path())
441 .unwrap()
442 .flatten()
443 .map(|e| e.file_name().to_string_lossy().into_owned())
444 .collect();
445 assert_eq!(names.len(), 3, "{names:?}");
446 assert_eq!(
447 reseal_dir(&dir.path().join("missing"), &old, &[fresh.to_public()]).unwrap(),
448 0
449 );
450 }
451
452 #[test]
453 fn a_reseal_that_cannot_write_fails_and_leaves_the_entry() {
454 use std::os::unix::fs::PermissionsExt;
455 let dir = tempfile::tempdir().unwrap();
456 let (old, fresh) = (Identity::generate(), Identity::generate());
457 let name = entry_name(1, true);
458 let sealed = note().to_sealed_file(&[old.to_public()]).unwrap();
459 std::fs::write(dir.path().join(&name), &sealed).unwrap();
460 let read_only = std::fs::Permissions::from_mode(0o500);
461 std::fs::set_permissions(dir.path(), read_only).unwrap();
462 let result = reseal_dir(dir.path(), &old, &[fresh.to_public()]);
463 std::fs::set_permissions(dir.path(), std::fs::Permissions::from_mode(0o700)).unwrap();
464 assert!(result.is_err());
465 assert_eq!(std::fs::read(dir.path().join(&name)).unwrap(), sealed);
466 }
467
468 #[test]
469 fn a_corrupt_entry_is_unreadable() {
470 assert!(matches!(open(b"{", None), Err(OpenError::Unreadable(_))));
471 let bad = br#"{"tool":"note","method":"POST","path":"/v1/notes","sealed":"!!"}"#;
472 assert!(matches!(
473 open(bad, Some(&Identity::generate())),
474 Err(OpenError::Unreadable(_))
475 ));
476 }
477}