Keep each session's taint and untrusted flag in a file

Implemented-By: OpenCode session (model recorded in docs/implementer-log.md)

crates/brokerd/src/lib.rs

@@ -5,3 +5,4 @@ pub mod config;
 pub mod grants;
 pub mod policy;
 pub mod runner;
+pub mod state;

crates/brokerd/src/state.rs

@@ -0,0 +1,149 @@
+//! Where the broker keeps what it knows about a session: one JSON line per session in
+//! `<dir>/<id>.json`. A read that fails is an error, never "a new session". Neither value ever
+//! goes down: `raise` only ever raises, and it writes atomically so a crash leaves the old file.
+//!
+//! The file's format is private (`StateFile`), so `SessionState` stays free of serde.
+
+use crate::policy::{Label, SessionState};
+use proto::{DataClass, SessionId};
+use serde::{Deserialize, Serialize};
+use std::fs;
+use std::io::{self, Write};
+use std::os::unix::fs::{DirBuilderExt, OpenOptionsExt};
+use std::path::{Path, PathBuf};
+
+/// Where the owner looks when a session's state file cannot be read or written.
+pub const RUNBOOK: &str = "see docs/runbook.md#broker-state-damaged";
+
+/// A state file that exists but cannot be read, or a write that could not reach disk.
+#[derive(Debug)]
+pub enum StateError {
+    /// The file exists and cannot be read, or is not a state.
+    Unreadable(PathBuf, String),
+    /// The new state could not be put on disk.
+    Write(PathBuf, io::Error),
+}
+
+impl std::fmt::Display for StateError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            StateError::Unreadable(path, detail) => write!(
+                f,
+                "cannot read the session state {}: {}; {}",
+                path.display(),
+                detail,
+                RUNBOOK
+            ),
+            StateError::Write(path, err) => write!(
+                f,
+                "cannot write the session state {}: {}; {}",
+                path.display(),
+                err,
+                RUNBOOK
+            ),
+        }
+    }
+}
+
+impl std::error::Error for StateError {}
+
+/// The directory that holds one `<id>.json` per session.
+#[derive(Debug, Clone)]
+pub struct StateStore {
+    dir: PathBuf,
+}
+
+impl StateStore {
+    /// A store for `dir`. This does not touch the disk.
+    pub fn new(dir: &Path) -> StateStore {
+        StateStore {
+            dir: dir.to_path_buf(),
+        }
+    }
+
+    /// The path of the file for this session: `<dir>/<id>.json`.
+    pub fn path(&self, session: &SessionId) -> PathBuf {
+        self.dir.join(format!("{}.json", session.as_str()))
+    }
+
+    /// The session's current state. A missing file is a fresh session; anything else that cannot
+    /// be read is an error.
+    pub fn read(&self, session: &SessionId) -> Result<SessionState, StateError> {
+        let path = self.path(session);
+        let text = match fs::read_to_string(&path) {
+            Ok(text) => text,
+            Err(err) if err.kind() == io::ErrorKind::NotFound => return Ok(SessionState::default()),
+            Err(err) => return Err(StateError::Unreadable(path, err.to_string())),
+        };
+        let file = match serde_json::from_str::<StateFile>(&text) {
+            Ok(file) => file,
+            Err(err) => return Err(StateError::Unreadable(path, err.to_string())),
+        };
+        if file.taint == DataClass::Public {
+            return Err(StateError::Unreadable(
+                path,
+                "a session's taint is never below private".to_string(),
+            ));
+        }
+        Ok(SessionState {
+            taint: file.taint,
+            untrusted: file.untrusted,
+        })
+    }
+
+    /// The raised state and whether its results are untrusted. It trusts `current`, never reads the
+    /// file again, and always writes, so the file exists from the first result on.
+    pub fn raise(
+        &self,
+        session: &SessionId,
+        current: SessionState,
+        label: Label,
+    ) -> Result<SessionState, StateError> {
+        let next = SessionState {
+            taint: current.taint.max(label.class).max(DataClass::Private),
+            untrusted: current.untrusted || label.untrusted,
+        };
+        let path = self.path(session);
+        if let Err(err) = Self::persist(&self.dir, &path, next.taint, next.untrusted) {
+            return Err(StateError::Write(path, err));
+        }
+        Ok(next)
+    }
+
+    /// Write the new state to `<path>` atomically, in six steps. Any failure maps to an `io` error
+    /// the caller turns into `Write`; an error leaves the old file untouched.
+    fn persist(dir: &Path, path: &Path, taint: DataClass, untrusted: bool) -> io::Result<()> {
+        // 1. The directory and any missing parents, mode 0700.
+        fs::DirBuilder::new()
+            .recursive(true)
+            .mode(0o700)
+            .create(dir)?;
+        // 2. Serialise and append the final newline.
+        let json =
+            serde_json::to_string(&StateFile { taint, untrusted }).map_err(io::Error::other)?;
+        let bytes = format!("{json}\n");
+        // 3. A fresh temporary file; `truncate` replaces a leftover one.
+        let tmp = path.with_extension("json.tmp");
+        let mut file = fs::OpenOptions::new()
+            .write(true)
+            .create(true)
+            .truncate(true)
+            .mode(0o600)
+            .open(&tmp)?;
+        // 4. Write it and force it to disk.
+        file.write_all(bytes.as_bytes())?;
+        file.sync_all()?;
+        // 5. Swap it into place.
+        fs::rename(&tmp, path)?;
+        // 6. Pin the rename itself to disk.
+        fs::File::open(dir)?.sync_all()
+    }
+}
+
+/// One line on disk: the taint and the untrusted flag.
+#[derive(Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct StateFile {
+    taint: DataClass,
+    untrusted: bool,
+}