Skip to content
Python
24.7 KB
Raw Blame
//! Workspace selection is not an isolation boundary. The trusted host records
//! an intent before calling prepare; after delivery loss it calls inspect only.
//! This module executes inside ToolRunner for remote environments.
use anyhow::{ensure, Context, Result};
use serde::{Deserialize, Serialize};
use serde_json::{json, Value};
use std::{
    fs,
    path::{Path, PathBuf},
};
use tokio::io::{AsyncBufReadExt, AsyncReadExt, AsyncWriteExt};

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "mode", rename_all = "snake_case", deny_unknown_fields)]
pub enum Selection {
    Team {},
    Directory {
        path: String,
    },
    Worktree {
        path: String,
        repository: String,
        branch: String,
        #[serde(default = "head")]
        base: String,
    },
}
fn head() -> String {
    "HEAD".into()
}
impl Default for Selection {
    fn default() -> Self {
        Self::Team {}
    }
}
impl Selection {
    pub fn validate(&self) -> Result<()> {
        match self {
            Self::Team {} => {}
            Self::Directory { path } => {
                crate::runner::relative_path(path)?;
            }
            Self::Worktree {
                path,
                repository,
                branch,
                base,
            } => {
                crate::runner::relative_path(path)?;
                if repository != "." {
                    crate::runner::relative_path(repository)?;
                }
                for value in [branch, base] {
                    ensure!(
                        !value.is_empty()
                            && value.len() <= 128
                            && !value.starts_with(['-', '/'])
                            && !value.contains("..")
                            && !value.contains("@{")
                            && value
                                .bytes()
                                .all(|b| b.is_ascii_alphanumeric() || b"/_-.".contains(&b)),
                        "Invalid branch/base reference"
                    );
                }
            }
        }
        Ok(())
    }
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct Identity {
    volume: u64,
    file: u64,
}
pub fn identity(path: &Path) -> Result<Identity> {
    #[cfg(unix)]
    {
        use std::os::unix::fs::MetadataExt;
        let m = fs::metadata(path)?;
        Ok(Identity {
            volume: m.dev(),
            file: m.ino(),
        })
    }
    #[cfg(windows)]
    {
        let (volume, file, _, _, _) = crate::platform::windows::file_identity(path)?;
        Ok(Identity { volume, file })
    }
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Request {
    pub operation_id: String,
    pub scope_digest: String,
    pub selection: Selection,
}
impl Request {
    pub fn validate(&self) -> Result<()> {
        ensure!(
            crate::bundle::safe_name(&self.operation_id) && self.operation_id.len() <= 80,
            "Invalid workspace operation ID"
        );
        ensure!(
            self.scope_digest.len() == 64
                && self.scope_digest.bytes().all(|b| b.is_ascii_hexdigit()),
            "Invalid workspace scope digest"
        );
        self.selection.validate()
    }
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Receipt {
    pub request: Request,
    pub path: PathBuf,
    pub project_root: PathBuf,
    pub identity: Identity,
    pub repository: Option<PathBuf>,
    pub git_dir: Option<PathBuf>,
    pub git_identity: Option<Identity>,
    #[serde(default)]
    pub worktree_git_dir: Option<PathBuf>,
    #[serde(default)]
    pub worktree_git_identity: Option<Identity>,
    #[serde(default)]
    pub pointer_digest: Option<String>,
    pub branch: Option<String>,
    pub initial_commit: Option<String>,
    /// Independent artifact checkout: pins its own Git directory, with no
    /// exception for metadata outside the child's file-tool working directory.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub independent_git: Option<Identity>,
}
/// Saved in the team transaction before filesystem dispatch. A recovered
/// dispatched intent authorizes inspection only, never another mutation.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct Intent {
    pub request: Request,
    pub receipt: Option<Receipt>,
    pub error: Option<String>,
}
impl Receipt {
    /// Structural validation is safe on the trusted host even when these paths
    /// live on another machine. Filesystem identity is checked by the ToolRunner.
    pub fn validate_scope(&self, project: &Path, workspace: &Path) -> Result<()> {
        self.request.validate()?;
        ensure!(
            self.project_root == project && self.path == workspace,
            "Workspace receipt belongs to another project/directory"
        );
        for p in [&self.project_root, &self.path] {
            ensure!(
                p.is_absolute()
                    && p.components().all(|c| !matches!(
                        c,
                        std::path::Component::ParentDir | std::path::Component::CurDir
                    )),
                "Noncanonical workspace receipt"
            );
        }
        if self.independent_git.is_some() {
            ensure!(
                matches!(self.request.selection, Selection::Directory { .. })
                    && self.git_dir.is_none()
                    && self.git_identity.is_none()
                    && self.worktree_git_dir.is_none()
                    && self.worktree_git_identity.is_none()
                    && self.pointer_digest.is_none()
                    && self.branch.is_none(),
                "Independent checkout cannot inherit linked metadata exceptions"
            );
            let commit = self
                .initial_commit
                .as_ref()
                .context("Missing imported revision")?;
            ensure!(
                [40, 64].contains(&commit.len())
                    && commit
                        .bytes()
                        .all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b))
                    && commit.bytes().any(|b| b != b'0'),
                "Imported revision is not pinned"
            );
        }
        let expected = match &self.request.selection {
            Selection::Team {} => project.to_owned(),
            Selection::Directory { path } | Selection::Worktree { path, .. } => project.join(path),
        };
        ensure!(
            self.path == expected && self.path.starts_with(project),
            "Workspace selection/receipt mismatch"
        );
        Ok(())
    }
    pub fn verify(&self) -> Result<()> {
        self.validate_scope(&self.project_root, &self.path)?;
        ensure!(
            self.path.starts_with(&self.project_root) && self.path.is_dir(),
            "Workspace left its authorized project"
        );
        checked_absolute(&self.project_root)?;
        checked_absolute(&self.path)?;
        ensure!(
            identity(&self.path)? == self.identity,
            "Workspace identity changed; do not adopt replacement"
        );
        if let Some(expected) = &self.independent_git {
            let dot = self.path.join(".git");
            checked_absolute(&dot)?;
            ensure!(
                dot.is_dir() && identity(&dot)? == *expected,
                "Independent Git metadata identity changed"
            );
            for child in [
                "HEAD",
                "config",
                "objects",
                "objects/info",
                "objects/pack",
                "refs",
                "refs/heads",
                "logs",
            ] {
                checked_absolute(&dot.join(child))?;
            }
            let (private, common) = metadata_paths(&self.path, &self.path)?;
            ensure!(
                private == dot && common == dot,
                "Independent checkout acquired external metadata"
            );
            for file in ["objects/info/alternates", "objects/info/http-alternates"] {
                ensure!(
                    !dot.join(file).exists(),
                    "Independent checkout acquired external objects"
                );
            }
        }
        if let Some(git) = &self.git_dir {
            checked_absolute(git)?;
            ensure!(
                self.git_identity.as_ref() == Some(&identity(git)?),
                "Original Git metadata identity changed"
            );
            ensure!(
                git.starts_with(&self.project_root),
                "Git metadata is outside the authorized project"
            );
            let (private, common) = metadata_paths(&self.path, &self.project_root)?;
            ensure!(
                &common == git
                    && self.worktree_git_dir.as_ref() == Some(&private)
                    && self.worktree_git_identity.as_ref() == Some(&identity(&private)?)
                    && self.pointer_digest.as_ref()
                        == Some(&crate::bundle::digest(&crate::bundle::read_limited(
                            &self.path.join(".git"),
                            4096
                        )?)),
                "Original worktree metadata pointer/identity changed"
            );
            checked_absolute(&private.join("HEAD"))?;
            ensure!(
                fs::read_to_string(private.join("HEAD"))?.trim()
                    == format!(
                        "ref: refs/heads/{}",
                        self.branch.as_deref().context("Missing worktree branch")?
                    ),
                "Managed worktree branch changed"
            );
        }
        Ok(())
    }
}
fn checked_absolute(path: &Path) -> Result<()> {
    ensure!(path.is_absolute(), "Absolute workspace root required");
    let mut current = PathBuf::new();
    for p in path.components() {
        current.push(p);
        if current.exists() {
            ensure!(
                !crate::platform::linked(&fs::symlink_metadata(&current)?),
                "Workspace symlinks are refused"
            );
        }
    }
    Ok(())
}
/// Bounded local metadata bookkeeping, after the operation's durable marker.
/// Do not edit the project's tracked .gitignore or overwrite user patterns.
pub(crate) fn exclude_bookkeeping(common: &Path) -> Result<()> {
    use std::io::Write;
    const RULE: &[u8] =
        b"\n# OpenWorker private workspace bookkeeping\n/.openworker/\n/.openworker-received/\n/.openworker-processes/\n";
    let info = common.join("info");
    checked_absolute(&info)?;
    fs::create_dir_all(&info)?;
    let path = info.join("exclude");
    checked_absolute(&path)?;
    let old = match fs::symlink_metadata(&path) {
        Ok(m) => {
            ensure!(
                m.is_file() && !crate::platform::linked(&m),
                "Git exclusions must be a regular local metadata file"
            );
            crate::bundle::read_limited(&path, 65536)?
        }
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => vec![],
        Err(e) => return Err(e.into()),
    };
    if old.ends_with(RULE) {
        return Ok(());
    }
    ensure!(
        old.len() + RULE.len() <= 65536,
        "Git exclusions exceed the managed bookkeeping limit"
    );
    let mut options = fs::OpenOptions::new();
    options.append(true).create(true);
    #[cfg(unix)]
    {
        use std::os::unix::fs::OpenOptionsExt;
        options.custom_flags(libc::O_NOFOLLOW).mode(0o600);
    }
    let mut file = options.open(&path)?;
    ensure!(
        file.metadata()?.is_file(),
        "Git exclusions must remain a regular file"
    );
    file.write_all(RULE)?;
    file.sync_all()?;
    Ok(())
}
fn select_path(root: &Path, path: &str) -> Result<PathBuf> {
    if path == "." {
        Ok(root.into())
    } else {
        crate::runner::path(root, path)
    }
}
async fn git(root: &Path, args: &[&str]) -> Result<String> {
    crate::coding::git::run(root, &args.iter().map(|v| (*v).into()).collect::<Vec<_>>()).await
}
/// Resolve on-disk Git pointers without running Git or following metadata outside
/// the app-authorized project. Used before reading any repository configuration.
fn metadata_paths(root: &Path, project: &Path) -> Result<(PathBuf, PathBuf)> {
    let dot = root.join(".git");
    checked_absolute(&dot)?;
    let git = if dot.is_dir() {
        dot
    } else {
        let data = String::from_utf8(crate::bundle::read_limited(&dot, 4096)?)?;
        let path = data
            .trim()
            .strip_prefix("gitdir: ")
            .context("Invalid Git pointer")?;
        let path = root.join(path);
        checked_absolute(&path)?;
        path.canonicalize()?
    };
    ensure!(
        git.starts_with(project) && git.is_dir(),
        "Git metadata outside authorized project"
    );
    let common = git.join("commondir");
    checked_absolute(&common)?;
    let common = if common.exists() {
        let data = String::from_utf8(crate::bundle::read_limited(&common, 4096)?)?;
        let path = git.join(data.trim());
        checked_absolute(&path)?;
        path.canonicalize()?
    } else {
        git.clone()
    };
    ensure!(
        common.starts_with(project) && common.is_dir(),
        "Git common metadata outside authorized project"
    );
    checked_absolute(&common)?;
    ensure!(
        !common.join("objects/info/alternates").exists(),
        "External Git object stores are not supported during preparation"
    );
    Ok((git, common))
}
pub(crate) async fn repository(root: &Path, project: &Path) -> Result<PathBuf> {
    // Validate pointers before invoking Git: rev-parse itself reads repository
    // configuration. A linked worktree may reference metadata only in this project.
    let (_, expected) = metadata_paths(root, project)?;
    let config_path = expected.join("config");
    checked_absolute(&config_path)?;
    let config = git(
        root,
        &[
            "config",
            "--file",
            config_path.to_str().context("Git config must be UTF-8")?,
            "--no-includes",
            "--null",
            "--list",
        ],
    )
    .await?;
    for entry in config.split('\0') {
        let key = entry.split('\n').next().unwrap_or("").to_ascii_lowercase();
        ensure!(!key.starts_with("filter.") && !key.starts_with("include.") && !key.starts_with("includeif.") && !matches!(key.as_str(),"extensions.worktreeconfig"|"core.worktree"|"core.sshcommand"), "Repository helpers/included/worktree configuration are not allowed during managed preparation");
    }
    let top =
        PathBuf::from(git(root, &["rev-parse", "--show-toplevel"]).await?.trim()).canonicalize()?;
    ensure!(
        top == root,
        "Select the repository root, not a directory inside it"
    );
    let common = PathBuf::from(
        git(
            root,
            &["rev-parse", "--path-format=absolute", "--git-common-dir"],
        )
        .await?
        .trim(),
    )
    .canonicalize()?;
    checked_absolute(&common)?;
    ensure!(
        common.starts_with(project),
        "Git metadata must remain in the authorized project"
    );
    ensure!(common == expected, "Git metadata changed during inspection");
    Ok(common)
}
#[derive(Serialize, Deserialize)]
struct Marker {
    request: Request,
    repository: PathBuf,
    common: PathBuf,
    commit: String,
}
/// No mutation is replayed by this function. A recovered operation with missing
/// evidence remains unknown; it does not run git worktree add a second time.
pub async fn prepare(root: &Path, request: Request, inspect_only: bool) -> Result<Receipt> {
    request.validate()?;
    checked_absolute(root)?;
    let root = root.canonicalize()?;
    ensure!(root.is_dir(), "Project root must be a directory");
    let mut receipt = Receipt {
        request: request.clone(),
        path: root.clone(),
        project_root: root.clone(),
        identity: identity(&root)?,
        repository: None,
        git_dir: None,
        git_identity: None,
        worktree_git_dir: None,
        worktree_git_identity: None,
        pointer_digest: None,
        branch: None,
        initial_commit: None,
        independent_git: None,
    };
    match &request.selection {
        Selection::Team {} => {}
        Selection::Directory { path } => {
            let path = select_path(&root, path)?;
            ensure!(path.is_dir(), "Selected directory does not exist");
            receipt.path = path.canonicalize()?;
            receipt.identity = identity(&receipt.path)?;
        }
        Selection::Worktree {
            path,
            repository: repo,
            branch,
            base,
        } => {
            let repo = select_path(&root, repo)?.canonicalize()?;
            checked_absolute(&repo)?;
            let common = repository(&repo, &root).await?;
            git(&repo, &["check-ref-format", "--branch", branch]).await?;
            let path = select_path(&root, path)?;
            ensure!(
                !path.starts_with(&common) && path != repo,
                "Worktree overlaps repository metadata"
            );
            let markers = crate::runner::path(&root, ".openworker/workspaces")?;
            let marker = markers.join(format!("{}.json", request.operation_id));
            let already_dispatched = marker.exists();
            let persisted = if already_dispatched {
                checked_absolute(&marker)?;
                let m: Marker =
                    serde_json::from_slice(&crate::bundle::read_limited(&marker, 16000)?)?;
                ensure!(
                    m.request == request && m.repository == repo && m.common == common,
                    "Workspace intent changed"
                );
                m
            } else {
                ensure!(!inspect_only, "Workspace outcome unknown: no original preparation evidence; do not retry automatically");
                ensure!(
                    !path.exists(),
                    "Worktree target already exists; not adopting it"
                );
                let commit = git(
                    &repo,
                    &[
                        "rev-parse",
                        "--verify",
                        "--end-of-options",
                        &format!("{base}^{{commit}}"),
                    ],
                )
                .await?
                .trim()
                .to_owned();
                ensure!(
                    [40, 64].contains(&commit.len())
                        && commit.bytes().all(|b| b.is_ascii_hexdigit()),
                    "Expected a local commit"
                );
                fs::create_dir_all(&markers)?;
                let m = Marker {
                    request: request.clone(),
                    repository: repo.clone(),
                    common: common.clone(),
                    commit,
                };
                use std::io::Write;
                let mut f = fs::OpenOptions::new()
                    .write(true)
                    .create_new(true)
                    .open(&marker)?;
                f.write_all(&serde_json::to_vec(&m)?)?;
                f.sync_all()?;
                m
            };
            if !inspect_only {
                // The host's durable dispatched flag is written before entering
                // here. Existing intent evidence never authorizes replay.
                ensure!(
                    !already_dispatched,
                    "Workspace preparation was already dispatched; inspect original outcome only"
                );
                ensure!(
                    !path.exists(),
                    "Existing worktree requires read-only reconciliation"
                );
                if repo == root {
                    exclude_bookkeeping(&common)?;
                }
                let parent = path.parent().context("Worktree parent missing")?;
                checked_absolute(parent)?;
                fs::create_dir_all(parent)?;
                let target = path.to_str().context("Workspace must be UTF-8")?;
                git(
                    &repo,
                    &[
                        "worktree",
                        "add",
                        "--no-guess-remote",
                        "-b",
                        branch,
                        target,
                        &persisted.commit,
                    ],
                )
                .await?;
            }
            ensure!(
                path.is_dir(),
                "Workspace preparation outcome unknown; original worktree is absent"
            );
            checked_absolute(&path)?;
            let found = repository(&path, &root).await?;
            ensure!(
                found == common
                    && git(&path, &["symbolic-ref", "--short", "HEAD"])
                        .await?
                        .trim()
                        == branch,
                "Original worktree branch/metadata changed"
            );
            ensure!(
                git(&path, &["rev-parse", "HEAD"]).await?.trim() == persisted.commit,
                "Worktree changed before preparation was acknowledged"
            );
            receipt.path = path.canonicalize()?;
            receipt.identity = identity(&receipt.path)?;
            receipt.repository = Some(repo);
            receipt.git_identity = Some(identity(&common)?);
            receipt.git_dir = Some(common);
            let (private, _) = metadata_paths(&receipt.path, &root)?;
            receipt.worktree_git_identity = Some(identity(&private)?);
            receipt.worktree_git_dir = Some(private);
            receipt.pointer_digest = Some(crate::bundle::digest(&crate::bundle::read_limited(
                &receipt.path.join(".git"),
                4096,
            )?));
            receipt.branch = Some(branch.clone());
            receipt.initial_commit = Some(persisted.commit);
        }
    }
    receipt.verify()?;
    Ok(receipt)
}
pub async fn serve(root: &Path) -> Result<()> {
    // One canonical root for prepare, handoff and later receipt verification.
    // macOS callers may supply /var while receipts correctly pin /private/var.
    let root = root.canonicalize()?;
    checked_absolute(&root)?;
    let mut input = tokio::io::BufReader::new(tokio::io::stdin());
    let mut output = tokio::io::stdout();
    loop {
        let mut line = vec![];
        let n = (&mut input)
            .take(64001)
            .read_until(b'\n', &mut line)
            .await?;
        if n == 0 {
            break;
        }
        ensure!(n <= 64000, "Workspace frame too large");
        let v: Value = serde_json::from_slice(&line)?;
        if v.get("id").is_none() {
            continue;
        }
        let result = async {
            if v["method"] == "initialize" {
                return Ok(json!({"protocolVersion":"2025-11-25","capabilities":{},"serverInfo":{"name":"openworker-workspaces","version":"1"}}));
            }
            if v["method"] == "workspace/verify" {
                let receipt: Receipt = serde_json::from_value(v["params"].clone())?;
                receipt.validate_scope(&root, &receipt.path)?;
                receipt.verify()?;
                return Ok(serde_json::to_value(receipt)?);
            }
            if let Some(method) = v["method"].as_str().filter(|m| m.starts_with("handoff/")) {
                return crate::coding_handoff::transfer::dispatch(&root, method, v["params"].clone()).await;
            }
            let request: Request = serde_json::from_value(v["params"].clone())?;
            ensure!(
                matches!(
                    v["method"].as_str(),
                    Some("workspace/prepare" | "workspace/inspect")
                ),
                "Unknown workspace method"
            );
            Ok::<_, anyhow::Error>(serde_json::to_value(
                prepare(&root, request, v["method"] == "workspace/inspect").await?,
            )?)
        }
        .await;
        let response = match result {
            Ok(r) => json!({"jsonrpc":"2.0","id":v["id"],"result":r}),
            Err(e) => {
                json!({"jsonrpc":"2.0","id":v["id"],"error":{"code":-32000,"message":e.to_string()}})
            }
        };
        output.write_all(format!("{response}\n").as_bytes()).await?;
        output.flush().await?;
    }
    Ok(())
}

pub fn schema() -> Value {
    json!({"anyOf":[
        {"type":"object","properties":{"mode":{"type":"string","enum":["team"]}},"required":["mode"],"additionalProperties":false},
        {"type":"object","properties":{"mode":{"type":"string","enum":["directory"]},"path":{"type":"string"}},"required":["mode","path"],"additionalProperties":false},
        {"type":"object","properties":{"mode":{"type":"string","enum":["worktree"]},"path":{"type":"string"},"repository":{"type":"string"},"branch":{"type":"string"},"base":{"type":"string"}},"required":["mode","path","repository","branch"],"additionalProperties":false}
    ]})
}