Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust
13.9 KB
Raw Blame
//! Grant management for `ai-memory user grant|revoke|grants` and `ai-memory
//! project grants` (#708).
//!
//! Thin HTTP client over `/admin/users/{username}/grant|revoke|grants` and
//! `/admin/projects/grants`. The caller's bearer token must authenticate as
//! root: grants are an operator action, and the server is usually somewhere the
//! operator's laptop cannot open the database directly.

use anyhow::{Context, Result};
use serde::{Deserialize, Serialize};

use crate::cli::{ProjectGrantsArgs, UserGrantArgs, UserGrantsArgs, UserRevokeArgs};
use crate::commands::user::url_encode;
use crate::http_client::{ServerEndpoint, get_json, post_json};

#[derive(Debug, Serialize)]
struct GrantRequest<'a> {
    workspace: &'a str,
    project: &'a str,
    #[serde(skip_serializing_if = "Option::is_none")]
    level: Option<&'a str>,
}

#[derive(Debug, Deserialize, Serialize)]
struct GrantRow {
    username: String,
    workspace: String,
    project: String,
    level: String,
}

#[derive(Debug, Deserialize)]
struct GrantList {
    grants: Vec<GrantRow>,
}

fn print_grants(grants: &[GrantRow], json: bool) -> Result<()> {
    if json {
        println!("{}", serde_json::to_string_pretty(grants)?);
        return Ok(());
    }
    if grants.is_empty() {
        // Say what empty means: nothing is lost on an open project.
        println!("(no grants)");
        println!(
            "Open projects admit every user regardless; a restricted project with no \
             grants admits only root."
        );
        return Ok(());
    }
    // Written through a locked stdout handle rather than `print!` so the table
    // leaves the process in one write, as `project_init` already does for its
    // own bulk output.
    write_grants(grants, &mut std::io::stdout().lock())
}

/// Lay out the grants table using terminal display-cell widths. Workspace and
/// project names come from a checkout's directory basename or a marker's
/// `project` key, so they are free-form UTF-8.
fn write_grants(grants: &[GrantRow], out: &mut impl std::io::Write) -> Result<()> {
    let project_w = grants
        .iter()
        .map(|g| {
            unicode_width::UnicodeWidthStr::width(format!("{}/{}", g.workspace, g.project).as_str())
        })
        .max()
        .unwrap_or(7)
        .max(7);
    let user_w = grants
        .iter()
        .map(|g| unicode_width::UnicodeWidthStr::width(g.username.as_str()))
        .max()
        .unwrap_or(8)
        .max(8);
    writeln!(
        out,
        "{}  {}  LEVEL",
        pad_cell("PROJECT", project_w),
        pad_cell("USERNAME", user_w)
    )?;
    for g in grants {
        let project = format!("{}/{}", g.workspace, g.project);
        writeln!(
            out,
            "{}  {}  {}",
            pad_cell(&project, project_w),
            pad_cell(&g.username, user_w),
            g.level
        )?;
    }
    Ok(())
}

fn pad_cell(value: &str, width: usize) -> String {
    let padding = width.saturating_sub(unicode_width::UnicodeWidthStr::width(value));
    format!("{value}{}", " ".repeat(padding))
}

/// `ai-memory user grants [--user NAME]`.
///
/// # Errors
/// Transport failures, a non-root token, or an unknown user.
pub async fn list_for_user(ep: &ServerEndpoint, args: &UserGrantsArgs) -> Result<()> {
    let resp: GrantList = match &args.user {
        Some(user) => get_json(
            ep,
            &format!("/admin/users/{}/grants", url_encode(user)),
            &[],
        )
        .await
        .with_context(|| format!("listing {user}'s grants"))?,
        None => get_json(ep, "/admin/projects/grants", &[])
            .await
            .context("listing grants")?,
    };
    print_grants(&resp.grants, args.json)
}

/// `ai-memory project grants --workspace W --project P`.
///
/// # Errors
/// Empty `--workspace` or `--project`; transport failures, a non-root token,
/// or an unknown project.
pub async fn list_for_project(ep: &ServerEndpoint, args: &ProjectGrantsArgs) -> Result<()> {
    super::refuse_empty_explicit(Some(args.workspace.as_str()), "--workspace")?;
    super::refuse_empty_explicit(Some(args.project.as_str()), "--project")?;
    let resp: GrantList = get_json(
        ep,
        "/admin/projects/grants",
        &[("workspace", &args.workspace), ("project", &args.project)],
    )
    .await
    .with_context(|| format!("listing grants on {}/{}", args.workspace, args.project))?;
    print_grants(&resp.grants, args.json)
}

#[derive(Debug, Deserialize)]
struct GrantResponse {
    level: String,
    changed: bool,
    previous: Option<String>,
}

/// `ai-memory user grant --user U --workspace W --project P --level L`.
///
/// # Errors
/// Empty `--user`, `--workspace`, `--project`, or `--level`; transport
/// failures, a non-root token, an unknown user, project or level.
pub async fn grant(ep: &ServerEndpoint, args: &UserGrantArgs) -> Result<()> {
    super::refuse_empty_explicit(Some(args.user.as_str()), "--user")?;
    super::refuse_empty_explicit(Some(args.workspace.as_str()), "--workspace")?;
    super::refuse_empty_explicit(Some(args.project.as_str()), "--project")?;
    super::refuse_empty_explicit(Some(args.level.as_str()), "--level")?;
    let body = GrantRequest {
        workspace: &args.workspace,
        project: &args.project,
        level: Some(&args.level),
    };
    let resp: GrantResponse = post_json(
        ep,
        &format!("/admin/users/{}/grant", url_encode(&args.user)),
        &body,
    )
    .await
    .with_context(|| {
        format!(
            "granting {} on {}/{}",
            args.user, args.workspace, args.project
        )
    })?;
    let who = &args.user;
    let project = format!("{}/{}", args.workspace, args.project);
    match (resp.changed, resp.previous) {
        (false, _) => println!(
            "{who} already holds {} on {project}; nothing changed.",
            resp.level
        ),
        (true, Some(previous)) => println!("{who}: {previous} -> {} on {project}.", resp.level),
        (true, None) => println!("{who} now holds {} on {project}.", resp.level),
    }
    Ok(())
}

#[derive(Debug, Deserialize)]
struct RevokeResponse {
    revoked: bool,
}

/// `ai-memory user revoke --user U --workspace W --project P`.
///
/// # Errors
/// Empty `--user`, `--workspace`, or `--project`; transport failures, a
/// non-root token, an unknown user or project.
pub async fn revoke(ep: &ServerEndpoint, args: &UserRevokeArgs) -> Result<()> {
    super::refuse_empty_explicit(Some(args.user.as_str()), "--user")?;
    super::refuse_empty_explicit(Some(args.workspace.as_str()), "--workspace")?;
    super::refuse_empty_explicit(Some(args.project.as_str()), "--project")?;
    let body = GrantRequest {
        workspace: &args.workspace,
        project: &args.project,
        level: None,
    };
    let resp: RevokeResponse = post_json(
        ep,
        &format!("/admin/users/{}/revoke", url_encode(&args.user)),
        &body,
    )
    .await
    .with_context(|| {
        format!(
            "revoking {} on {}/{}",
            args.user, args.workspace, args.project
        )
    })?;
    let project = format!("{}/{}", args.workspace, args.project);
    if resp.revoked {
        println!("{} no longer holds anything on {project}.", args.user);
    } else {
        println!("{} held nothing on {project}; nothing changed.", args.user);
    }
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;

    fn grant(project: &str, username: &str) -> GrantRow {
        GrantRow {
            username: username.to_owned(),
            workspace: "default".to_owned(),
            project: project.to_owned(),
            level: "read".to_owned(),
        }
    }

    /// The display-cell offset at which `line` carries `username`, or `None`.
    fn username_column(line: &str, username: &str) -> Option<usize> {
        line.find(username)
            .map(|byte| unicode_width::UnicodeWidthStr::width(&line[..byte]))
    }

    #[test]
    fn grants_table_columns_line_up_past_ascii() {
        let rows = [grant("caf\u{e9}", "ana"), grant("web", "bob")];
        let mut buf = Vec::new();
        write_grants(&rows, &mut buf).expect("rendering to a buffer cannot fail");
        let table = String::from_utf8(buf).expect("the table is utf-8");
        let header = table.lines().next().expect("a header row");
        // The header is ASCII, so its byte offset is its character offset.
        let user_col = header.find("USERNAME").expect("a USERNAME column");
        // `café` is one byte longer than it is wide, so a byte-measured width
        // pads that row one column too far and shifts USERNAME and LEVEL.
        for (line, row) in table.lines().skip(1).zip(rows.iter()) {
            assert_eq!(
                username_column(line, &row.username),
                Some(user_col),
                "USERNAME column moved on {line:?}:\n{table}"
            );
        }
        // Control: an ASCII-only table lines up under either measure, so the
        // non-ASCII row above is what carries the assertion.
        let ascii_rows = [grant("cafe", "ana"), grant("web", "bob")];
        let mut ascii_buf = Vec::new();
        write_grants(&ascii_rows, &mut ascii_buf).expect("rendering to a buffer cannot fail");
        let ascii = String::from_utf8(ascii_buf).expect("the table is utf-8");
        for (line, row) in ascii.lines().skip(1).zip(ascii_rows.iter()) {
            assert_eq!(
                username_column(line, &row.username),
                Some(user_col),
                "ascii rows must line up as well:\n{ascii}"
            );
        }

        let cjk_rows = [grant("記憶管理", "利用者"), grant("web", "bob")];
        let mut cjk_buf = Vec::new();
        write_grants(&cjk_rows, &mut cjk_buf).unwrap();
        let cjk = String::from_utf8(cjk_buf).unwrap();
        let cjk_user_col = username_column(cjk.lines().next().unwrap(), "USERNAME").unwrap();
        for (line, row) in cjk.lines().skip(1).zip(cjk_rows.iter()) {
            assert_eq!(
                username_column(line, &row.username),
                Some(cjk_user_col),
                "{cjk}"
            );
        }
    }
    fn grants_args() -> ProjectGrantsArgs {
        ProjectGrantsArgs {
            workspace: "default".into(),
            project: "app".into(),
            json: false,
        }
    }

    fn dead_ep() -> ServerEndpoint {
        ServerEndpoint::from_pair(Some("http://127.0.0.1:1".into()), None)
    }

    #[tokio::test]
    async fn an_empty_project_flag_is_refused_before_listing_grants() {
        let mut a = grants_args();
        a.project = "   ".into();
        let error = list_for_project(&dead_ep(), &a).await.unwrap_err();
        assert!(
            error.to_string().contains("--project was passed empty"),
            "unexpected error: {error}"
        );
    }

    #[tokio::test]
    async fn an_empty_workspace_flag_is_refused_before_listing_grants() {
        let mut a = grants_args();
        a.workspace = "".into();
        let error = list_for_project(&dead_ep(), &a).await.unwrap_err();
        assert!(
            error.to_string().contains("--workspace was passed empty"),
            "unexpected error: {error}"
        );
    }
    fn grant_args() -> UserGrantArgs {
        UserGrantArgs {
            user: "ana".into(),
            workspace: "default".into(),
            project: "app".into(),
            level: "write".into(),
        }
    }

    fn revoke_args() -> UserRevokeArgs {
        UserRevokeArgs {
            user: "ana".into(),
            workspace: "default".into(),
            project: "app".into(),
        }
    }

    #[tokio::test]
    async fn an_empty_user_flag_is_refused_before_granting() {
        let mut a = grant_args();
        a.user = "   ".into();
        let error = super::grant(&dead_ep(), &a).await.unwrap_err();
        assert!(
            error.to_string().contains("--user was passed empty"),
            "unexpected error: {error}"
        );
    }

    #[tokio::test]
    async fn an_empty_workspace_flag_is_refused_before_granting() {
        let mut a = grant_args();
        a.workspace = "".into();
        let error = super::grant(&dead_ep(), &a).await.unwrap_err();
        assert!(
            error.to_string().contains("--workspace was passed empty"),
            "unexpected error: {error}"
        );
    }

    #[tokio::test]
    async fn an_empty_project_flag_is_refused_before_granting() {
        let mut a = grant_args();
        a.project = "  ".into();
        let error = super::grant(&dead_ep(), &a).await.unwrap_err();
        assert!(
            error.to_string().contains("--project was passed empty"),
            "unexpected error: {error}"
        );
    }

    #[tokio::test]
    async fn an_empty_level_flag_is_refused_before_granting() {
        let mut a = grant_args();
        a.level = "".into();
        let error = super::grant(&dead_ep(), &a).await.unwrap_err();
        assert!(
            error.to_string().contains("--level was passed empty"),
            "unexpected error: {error}"
        );
    }

    #[tokio::test]
    async fn an_empty_user_flag_is_refused_before_revoking() {
        let mut a = revoke_args();
        a.user = "   ".into();
        let error = super::revoke(&dead_ep(), &a).await.unwrap_err();
        assert!(
            error.to_string().contains("--user was passed empty"),
            "unexpected error: {error}"
        );
    }

    #[tokio::test]
    async fn an_empty_workspace_flag_is_refused_before_revoking() {
        let mut a = revoke_args();
        a.workspace = "".into();
        let error = super::revoke(&dead_ep(), &a).await.unwrap_err();
        assert!(
            error.to_string().contains("--workspace was passed empty"),
            "unexpected error: {error}"
        );
    }

    #[tokio::test]
    async fn an_empty_project_flag_is_refused_before_revoking() {
        let mut a = revoke_args();
        a.project = "  ".into();
        let error = super::revoke(&dead_ep(), &a).await.unwrap_err();
        assert!(
            error.to_string().contains("--project was passed empty"),
            "unexpected error: {error}"
        );
    }
}