From 2efb8953102847eddb591d0ceca5b75db162fd7d Mon Sep 17 00:00:00 2001 From: Ragnor Comerford Date: Mon, 16 Nov 2026 12:24:26 -0800 Subject: [PATCH 1/3] fix(cli)!: direct writes to a cluster graph obey its applied policy A direct CLI write or maintenance command on a cluster graph installed no policy, so actors the graph's applied policy refuses (and no actor at all) published on protected branches, while `omnigraph access` on the same target reported the policy's answer. Every writable embedded open now goes through admission::open_writable, which reads the bundle bound to the graph under the admission lock (ClusterAdmission::graph_policy, reading only that graph's bundles) and installs it on the handle. optimize and cleanup accept --as so maintenance can name the actor the policy judges. The engine's missing-actor refusal names the action instead of calling the case a bug. Closes #1414. --- ...uster-writes-obey-graph-policy.breaking.md | 7 + crates/omnigraph-cli/src/admission.rs | 40 +++- crates/omnigraph-cli/src/cli.rs | 5 +- crates/omnigraph-cli/src/client.rs | 18 +- .../src/commands/maintenance/mod.rs | 31 +-- crates/omnigraph-cli/src/planes.rs | 9 +- .../tests/integration/cli_cluster.rs | 61 ++++-- .../tests/integration/cli_data.rs | 192 +++++++++++++++++- .../tests/integration/cli_mcp.rs | 1 + .../tests/integration/system_local.rs | 19 +- crates/omnigraph-cli/tests/support/mod.rs | 37 +++- crates/omnigraph-cluster/src/admission.rs | 21 ++ crates/omnigraph-cluster/src/authorization.rs | 56 +++++ crates/omnigraph/src/db/omnigraph.rs | 25 +-- docs/user/cli/reference.md | 4 +- docs/user/operations/maintenance.md | 12 +- docs/user/operations/policy.md | 19 +- skills/omnigraph/SKILL.md | 3 +- skills/omnigraph/references/commands.md | 9 +- skills/omnigraph/references/server-policy.md | 13 +- 20 files changed, 456 insertions(+), 126 deletions(-) create mode 100644 changelog.d/direct-cluster-writes-obey-graph-policy.breaking.md diff --git a/changelog.d/direct-cluster-writes-obey-graph-policy.breaking.md b/changelog.d/direct-cluster-writes-obey-graph-policy.breaking.md new file mode 100644 index 000000000..b149061bf --- /dev/null +++ b/changelog.d/direct-cluster-writes-obey-graph-policy.breaking.md @@ -0,0 +1,7 @@ +- Direct CLI writes and maintenance on a cluster graph now obey the graph's + applied policy, as `omnigraph access` already reported; they used to apply + none. Pass an `--as` actor the policy admits (`optimize` and `cleanup` now + accept `--as`), or the command is refused as `forbidden` with no effects. + See [direct writes][direct-cluster-writes]. + +[direct-cluster-writes]: ../docs/user/operations/policy.md#actor-identity diff --git a/crates/omnigraph-cli/src/admission.rs b/crates/omnigraph-cli/src/admission.rs index 0473d67de..ea77be641 100644 --- a/crates/omnigraph-cli/src/admission.rs +++ b/crates/omnigraph-cli/src/admission.rs @@ -70,24 +70,49 @@ pub(crate) async fn open_read_only_with_binding( Ok(db) } +/// The one writable opener of an embedded command. A graph inside a cluster +/// is admitted first (before the opener's capability probe), and the policy +/// the applied revision binds to it is installed on the handle, so every +/// `_as` writer judges the declared actor as a server judges a served one. A +/// standalone graph has no policy. `storage` is the adapter the caller opens +/// the graph with. +pub(crate) async fn open_writable( + binding: &CapturedStorageBinding, + storage: Arc, + stderr: &mut dyn Write, +) -> Result { + let policy = match ensure_graph_with_binding(binding, stderr).await? { + Some(owner) => owner.graph_policy(binding.uri()).await.map_err(report)?, + None => None, + }; + crate::command_outcome::writable_open(); + let db = omnigraph::db::Omnigraph::open_with_storage(binding.uri(), storage).await?; + Ok(match policy { + Some(policy) => db.with_policy(policy), + None => db, + }) +} + /// Acquire before the writable opener (including its capability probe), and -/// reuse only the same canonical root's admission during this command. -pub(crate) async fn ensure_graph_with_binding( +/// reuse only the same canonical root's admission during this command. The +/// admission a cluster graph is under, or `None` for a standalone graph. +async fn ensure_graph_with_binding( binding: &CapturedStorageBinding, stderr: &mut dyn Write, -) -> Result<()> { +) -> Result> { let uri = binding.uri(); let Some(root) = omnigraph_cluster::cluster_root_for_graph_binding(binding) .await .map_err(report)? else { - return Ok(()); + return Ok(None); }; let key = binding.for_uri(&root)?.identity(); let owners = COMMAND.try_with(Arc::clone).unwrap_or_default(); let mut owners = owners.lock().await; if let Some(owner) = owners.get(&key) { - return owner.validate_graph_uri(uri).await.map_err(report); + owner.validate_graph_uri(uri).await.map_err(report)?; + return Ok(Some(owner.clone())); } if let Some(owner) = omnigraph_cluster::acquire_graph_admission_with_binding( binding, @@ -107,9 +132,10 @@ pub(crate) async fn ensure_graph_with_binding( writeln!(stderr, "{custody}") .and_then(|()| stderr.flush()) .map_err(|error| color_eyre::Report::from(error).wrap_err(custody))?; - owners.insert(key, owner); + owners.insert(key, owner.clone()); + return Ok(Some(owner)); } - Ok(()) + Ok(None) } fn report(diagnostic: omnigraph_cluster::Diagnostic) -> color_eyre::Report { diff --git a/crates/omnigraph-cli/src/cli.rs b/crates/omnigraph-cli/src/cli.rs index 3b26fe527..8d3822f40 100644 --- a/crates/omnigraph-cli/src/cli.rs +++ b/crates/omnigraph-cli/src/cli.rs @@ -63,8 +63,9 @@ pub(crate) struct Cli { /// On a served write, and on every request `mcp` relays, it is an assertion: /// the request carries `omnigraph-if-actor`, and the server refuses it /// before anything runs when the bearer token resolves to another actor. - /// With a policy configured but no actor set, a direct operation is - /// denied — see docs/user/operations/policy.md. + /// A direct write to a cluster graph is judged by the policy the cluster + /// applied to that graph, and with one but no actor set it is denied — + /// see docs/user/operations/policy.md. #[arg(long = "as", global = true, value_name = "ACTOR", value_parser = crate::invocation::single_selector("--as"))] pub(crate) as_actor: Option, diff --git a/crates/omnigraph-cli/src/client.rs b/crates/omnigraph-cli/src/client.rs index 392b83f38..805fb0916 100644 --- a/crates/omnigraph-cli/src/client.rs +++ b/crates/omnigraph-cli/src/client.rs @@ -4,7 +4,7 @@ use std::sync::Arc; use color_eyre::Result; use color_eyre::eyre::{bail, eyre}; -use omnigraph::db::{Omnigraph, ReadTarget, SnapshotId}; +use omnigraph::db::{ReadTarget, SnapshotId}; use omnigraph::settings::{SessionSettings, SettingId, SettingValue, Source}; use omnigraph::storage::CapturedStorageBinding; use omnigraph::{BLOB_READ_RANGE_MAX_BYTES, BlobContent, Session}; @@ -412,8 +412,9 @@ impl GraphClient { matches!(self, GraphClient::Remote { .. }) } - /// Writable verbs alone acquire durable cluster admission. Direct-store - /// access carries no Cedar policy (RFC-011), the actor rides the `_as` APIs. + /// Writable verbs alone acquire durable cluster admission. A cluster + /// graph's applied policy is installed on the handle, and the declared + /// actor rides the `_as` APIs into it. async fn open_write( uri: &str, binding: &CapturedStorageBinding, @@ -477,7 +478,7 @@ impl GraphClient { /// its fresh handle when given: the one way a CLI run admits a source /// outside the graph (a `load csv "file://…"` statement run directly). async fn open_write_session_with_external_blob_policy( - uri: &str, + _uri: &str, binding: &CapturedStorageBinding, base: Option<&str>, settings: &[(SettingId, SettingValue)], @@ -485,13 +486,8 @@ impl GraphClient { stderr: &mut dyn Write, ) -> Result { let (defaults, sources) = omnigraph::settings::from_env()?; - crate::admission::ensure_graph_with_binding(binding, stderr).await?; - crate::command_outcome::writable_open(); - let db = Omnigraph::open_with_storage( - uri, - crate::admission::embedded_storage(binding, base).await?, - ) - .await?; + let storage = crate::admission::embedded_storage(binding, base).await?; + let db = crate::admission::open_writable(binding, storage, stderr).await?; let db = match external_blob_policy { Some(policy) => db.with_external_blob_policy(policy)?, None => db, diff --git a/crates/omnigraph-cli/src/commands/maintenance/mod.rs b/crates/omnigraph-cli/src/commands/maintenance/mod.rs index 95bd6891a..a1e7f4914 100644 --- a/crates/omnigraph-cli/src/commands/maintenance/mod.rs +++ b/crates/omnigraph-cli/src/commands/maintenance/mod.rs @@ -3,7 +3,7 @@ use std::io::Write; use color_eyre::eyre::{Result, bail}; -use omnigraph::db::{CleanupPolicyOptions, Omnigraph}; +use omnigraph::db::CleanupPolicyOptions; use crate::app::Completion; use crate::helpers::{confirm_destructive, parse_duration_arg, resolve_actor}; @@ -61,7 +61,7 @@ pub(crate) async fn run_optimize( scope.operator, scope.target, scope.graph, - None, + scope.actor, stderr, ) .await?; @@ -95,10 +95,10 @@ pub(crate) async fn run_optimize( let uri = crate::scope::direct_graph_uri(scope.target, scope.graph).await?; let binding = crate::scope::capture_storage_binding(scope.target)?.for_uri(&uri)?; let actor = resolve_actor(scope.operator, scope.actor, stderr)?; - crate::admission::ensure_graph_with_binding(&binding, stderr).await?; - let db = Omnigraph::open_with_storage( - binding.uri(), + let db = crate::admission::open_writable( + &binding, omnigraph::storage::storage_for_binding(&binding)?, + stderr, ) .await?; let report = db.optimize_as(actor.as_deref(), request).await?; @@ -117,10 +117,10 @@ pub(crate) async fn run_index( let uri = crate::scope::direct_graph_uri(scope.target, scope.graph).await?; let binding = crate::scope::capture_storage_binding(scope.target)?.for_uri(&uri)?; let actor = resolve_actor(scope.operator, scope.actor, stderr)?; - crate::admission::ensure_graph_with_binding(&binding, stderr).await?; - let db = Omnigraph::open_with_storage( - binding.uri(), + let db = crate::admission::open_writable( + &binding, omnigraph::storage::storage_for_binding(&binding)?, + stderr, ) .await?; let result = db.ensure_indices_on_as(&branch, actor.as_deref()).await?; @@ -175,9 +175,12 @@ pub(crate) async fn rebuild_full_text_indexes( stderr: &mut dyn Write, ) -> Result<()> { let uri = binding.uri(); - crate::admission::ensure_graph_with_binding(binding, stderr).await?; - let db = Omnigraph::open_with_storage(uri, omnigraph::storage::storage_for_binding(binding)?) - .await?; + let db = crate::admission::open_writable( + binding, + omnigraph::storage::storage_for_binding(binding)?, + stderr, + ) + .await?; let result = db.rebuild_full_text_indices_on_as(branch, actor).await?; write_full_text_rebuild(uri, &result, json, stdout, stderr) } @@ -226,10 +229,10 @@ pub(crate) async fn run_cleanup( older_than: older_than_dur, }; let actor = resolve_actor(scope.operator, scope.actor, stderr)?; - crate::admission::ensure_graph_with_binding(&binding, stderr).await?; - let db = Omnigraph::open_with_storage( - binding.uri(), + let db = crate::admission::open_writable( + &binding, omnigraph::storage::storage_for_binding(&binding)?, + stderr, ) .await?; let stats = db.cleanup_as(options.clone(), actor.as_deref()).await?; diff --git a/crates/omnigraph-cli/src/planes.rs b/crates/omnigraph-cli/src/planes.rs index 41a0dadba..6b1169c21 100644 --- a/crates/omnigraph-cli/src/planes.rs +++ b/crates/omnigraph-cli/src/planes.rs @@ -327,6 +327,9 @@ fn accepts_actor(command: &Command) -> bool { | Command::Index { .. } | Command::RebuildFullTextIndexes(_) | Command::Mcp(_) => true, + // A cluster graph's applied policy judges maintenance by this actor + // (`maintain`, `reclaim`); a served optimize asserts it. + Command::Optimize(_) | Command::Cleanup(_) => true, // The actor a direct target's policy decides for. Command::Access(_) => true, Command::Branch { command } => match command { @@ -388,8 +391,6 @@ fn accepts_actor(command: &Command) -> bool { | Command::Organization { .. } | Command::Init(_) | Command::Upgrade(_) - | Command::Optimize(_) - | Command::Cleanup(_) | Command::Lint(_) | Command::Alias(_) | Command::Embed(_) @@ -835,8 +836,8 @@ mod tests { (&["diff", "--from", "a", "--to", "b"], false), (&["changes", "poll"], false), (&["changes", "baseline", "--out", "out"], false), - (&["optimize"], false), - (&["cleanup"], false), + (&["optimize"], true), + (&["cleanup"], true), (&["mcp"], true), (&["mcp", "--write"], true), // Studio's actor is its credential's; the link asserts none. diff --git a/crates/omnigraph-cli/tests/integration/cli_cluster.rs b/crates/omnigraph-cli/tests/integration/cli_cluster.rs index 543030981..cb04c4728 100644 --- a/crates/omnigraph-cli/tests/integration/cli_cluster.rs +++ b/crates/omnigraph-cli/tests/integration/cli_cluster.rs @@ -3259,7 +3259,8 @@ fn applied_knowledge_cluster() -> tempfile::TempDir { #[test] fn optimize_resolves_a_cluster_graph_by_id() { let temp = applied_knowledge_cluster(); - // No hand-typed storage path: address the graph by cluster dir + id. + // No hand-typed storage path: address the graph by cluster dir + id. The + // applied policy grants `act-operator` `maintain`. let out = output_success( cli() .arg("optimize") @@ -3267,7 +3268,7 @@ fn optimize_resolves_a_cluster_graph_by_id() { .arg(temp.path()) .arg("--graph") .arg("knowledge") - .arg("--json"), + .args(["--as", "act-operator", "--json"]), ); let payload = parse_stdout_json(&out); assert!( @@ -3441,7 +3442,14 @@ async fn successful_v2_cli_reads_preserve_admission_and_applied_state() { // Reads leave the writer door usable; writers still retain their own lock. output_success( cli() - .args(["branch", "create", "after-reads", "--target"]) + .args([ + "branch", + "create", + "after-reads", + "--as", + "act-operator", + "--target", + ]) .arg(&graph), ); assert!(lock_path.exists()); @@ -3532,11 +3540,14 @@ fn optimize_uses_only_an_explicit_or_configured_graph() { assert!(String::from_utf8_lossy(&refused.stderr).contains("graph")); let home = tempdir().unwrap(); fs::write(home.path().join("config.yaml"), format!("version: 1\ntargets:\n root:\n kind: direct\n scope: root\n uri: file://{}\n default_graph: knowledge\n", temp.path().display())).unwrap(); - let out = output_success( - cli() - .env("OMNIGRAPH_HOME", home.path()) - .args(["optimize", "--target", "root", "--json"]), - ); + let out = output_success(cli().env("OMNIGRAPH_HOME", home.path()).args([ + "optimize", + "--target", + "root", + "--as", + "act-operator", + "--json", + ])); assert!(parse_stdout_json(&out)["datasets"].is_array()); } @@ -3701,26 +3712,38 @@ fn optimize_by_cluster_works_when_catalog_payloads_are_degraded() { // pending recovery sweep) does NOT block it — unlike the full serving-snapshot // read. This is what keeps `optimize --target ROOT --graph GRAPH` usable on a degraded cluster. let temp = applied_knowledge_cluster(); - // Remove the verified catalog payloads (queries/policies) — a serving read - // would refuse with a catalog-payload diagnostic; the ledger-only resolve - // must not care. - let resources = temp.path().join("__cluster").join("resources"); - if resources.exists() { - fs::remove_dir_all(&resources).unwrap(); - } - let out = output_success( - cli() + let optimize = || { + let output = cli() .arg("optimize") .arg("--target") .arg(temp.path()) .arg("--graph") .arg("knowledge") - .arg("--json"), - ); + .args(["--as", "act-operator", "--json"]) + .output() + .unwrap(); + unlock_cluster_fixture(temp.path()); + output + }; + // Remove the stored-query payloads — a serving read would refuse with a + // catalog-payload diagnostic; the ledger-only resolve must not care. + let resources = temp.path().join("__cluster").join("resources"); + fs::remove_dir_all(resources.join("query")).unwrap(); + let out = optimize(); + assert!(out.status.success(), "{out:?}"); assert!( parse_stdout_json(&out)["datasets"].as_array().is_some(), "optimize should resolve via the ledger despite degraded catalog payloads" ); + // The graph's own policy is no unrelated payload: without it the + // maintenance cannot be judged, so it refuses rather than run unpoliced. + fs::remove_dir_all(resources.join("policy")).unwrap(); + let refused = optimize(); + assert!(!refused.status.success(), "{refused:?}"); + assert!( + String::from_utf8_lossy(&refused.stderr).contains("catalog_payload_missing"), + "{refused:?}" + ); } #[test] diff --git a/crates/omnigraph-cli/tests/integration/cli_data.rs b/crates/omnigraph-cli/tests/integration/cli_data.rs index 71848ecfb..c44f1972c 100644 --- a/crates/omnigraph-cli/tests/integration/cli_data.rs +++ b/crates/omnigraph-cli/tests/integration/cli_data.rs @@ -1323,12 +1323,6 @@ fn optimize_timeout_bounds_a_stalled_submission() { assert!(stderr.contains("stopped waiting"), "{stderr}"); } -#[test] -fn optimize_with_as_flag_errors() { - let output = output_failure(cli().args(["optimize", "--as", "act-op"])); - assert!(String::from_utf8_lossy(&output.stderr).contains("optimize does not accept --as")); -} - #[test] fn retired_address_flags_refuse_before_resolving_a_target() { for flag in ["--store", "--server", "--cluster", "--profile", "--uri"] { @@ -6549,6 +6543,192 @@ fn access_reports_what_the_caller_may_do_at_a_target() { assert_eq!(refusal["code"], "target_unknown", "{refusal}"); } +/// A graph policy where only `act-writer` may change `main`, `act-reader` +/// may only read, and only `act-maintainer` may maintain and reclaim. +const WRITER_READER_POLICY_YAML: &str = r#" +version: 1 +groups: + writers: [act-writer] + maintainers: [act-maintainer] + everyone: [act-writer, act-reader] +protected_branches: [main] +rules: + - id: maintainers-maintain + allow: + actors: { group: maintainers } + actions: [maintain] + branch_scope: any + - id: maintainers-reclaim + allow: + actors: { group: maintainers } + actions: [reclaim] + - id: everyone-reads + allow: + actors: { group: everyone } + actions: [read] + branch_scope: any + - id: writers-change + allow: + actors: { group: writers } + actions: [change] + branch_scope: any +"#; + +/// A direct write to a cluster graph is judged by the policy the cluster +/// applied to it, as `access` reports and as a server would judge it: through +/// the root target and through the graph's own store, for loads, mutations +/// and maintenance. A refused write publishes nothing; an actor the policy +/// admits writes, and the commit records it. +#[test] +fn direct_writes_to_a_cluster_graph_obey_its_applied_policy_issue_1414() { + let cluster = converged_loaded_cluster("knowledge", Some(WRITER_READER_POLICY_YAML)); + let root = cluster.path().to_path_buf(); + let store = root.join("graphs").join("knowledge.omni"); + let temp = tempdir().unwrap(); + let mutation = temp.path().join("insert.gq"); + write_query_file( + &mutation, + r#" +query insert_person($name: String, $age: I32) { + insert Person { name: $name, age: $age } +} +"#, + ); + let with_actor = |command: &mut Command, actor: Option<&str>| { + if let Some(actor) = actor { + command.args(["--as", actor]); + } + }; + let may_change_main = |actor: Option<&str>| -> bool { + let mut command = cli(); + command.arg("access").arg("--target").arg(&root).args([ + "--graph", + "knowledge", + "--branch", + "main", + "--json", + ]); + with_actor(&mut command, actor); + let report = parse_stdout_json(&output_success(&mut command)); + report["actions"] + .as_array() + .unwrap() + .iter() + .any(|action| action == "change") + }; + // One command per address: the root with `--graph`, and the store. + let addressed = |command: &mut Command, by_store: bool| { + if by_store { + command.arg("--target").arg(&store); + } else { + command + .arg("--target") + .arg(&root) + .args(["--graph", "knowledge"]); + } + }; + let mut row = 0; + let mut writes = |actor: Option<&str>, by_store: bool| -> Vec { + row += 1; + let data = temp.path().join(format!("row-{row}.jsonl")); + fs::write( + &data, + format!("{{\"type\": \"Person\", \"data\": {{\"name\": \"p{row}\", \"age\": 1}}}}\n"), + ) + .unwrap(); + let mut load = cli(); + load.arg("load"); + addressed(&mut load, by_store); + load.arg("--data") + .arg(&data) + .args(["--mode", "append", "--json"]); + with_actor(&mut load, actor); + let mut mutate = cli(); + mutate.arg("mutate"); + addressed(&mut mutate, by_store); + mutate + .arg("--query") + .arg(&mutation) + .arg("--params") + .arg(format!(r#"{{"name":"m{row}","age":2}}"#)) + .arg("--json"); + with_actor(&mut mutate, actor); + [load, mutate] + .into_iter() + .map(|mut command| { + let output = command.output().unwrap(); + // A direct write keeps its cluster admission; release it so + // the next command is admitted. + unlock_cluster_fixture(&root); + output + }) + .collect() + }; + + for actor in [Some("act-outsider"), Some("act-reader"), None] { + assert!(!may_change_main(actor), "{actor:?}"); + for by_store in [false, true] { + let before = manifest_dataset_version(&store); + for output in writes(actor, by_store) { + assert!(!output.status.success(), "{actor:?}: {output:?}"); + let refusal = parse_stdout_json(&output); + assert_eq!(refusal["code"], "forbidden", "{actor:?}: {refusal}"); + assert_eq!( + refusal["disposition"]["effects"], "none", + "{actor:?}: {refusal}" + ); + let message = refusal["error"].as_str().unwrap(); + assert!(message.contains("'change'"), "{message}"); + if actor.is_none() { + assert!(message.contains("names no actor"), "{message}"); + } + } + assert_eq!(manifest_dataset_version(&store), before, "{actor:?}"); + } + } + + assert!(may_change_main(Some("act-writer"))); + for by_store in [false, true] { + let before = manifest_dataset_version(&store); + for output in writes(Some("act-writer"), by_store) { + assert!(output.status.success(), "{output:?}"); + let report = parse_stdout_json(&output); + assert_eq!(report["commit"]["actor_id"], "act-writer", "{report}"); + } + assert_eq!(manifest_dataset_version(&store), before + 2); + } + + // Maintenance takes the same handle and names its actor with `--as`: + // changing data grants neither `maintain` nor `reclaim`. + let maintenance: [(&[&str], &str); 3] = [ + (&["index", "build", "--branch", "main"], "'maintain'"), + (&["optimize"], "'maintain'"), + ( + &["cleanup", "--keep", "100", "--confirm", "--yes"], + "'reclaim'", + ), + ]; + let maintain = |args: &[&str], actor: &str| { + let mut command = cli(); + command.args(args); + addressed(&mut command, false); + command.args(["--as", actor, "--json"]); + let output = command.output().unwrap(); + unlock_cluster_fixture(&root); + output + }; + for (args, action) in maintenance { + let before = manifest_dataset_version(&store); + let refused = maintain(args, "act-writer"); + assert!(!refused.status.success(), "{args:?}: {refused:?}"); + let stderr = String::from_utf8_lossy(&refused.stderr); + assert!(stderr.contains(action), "{args:?}: {stderr}"); + assert_eq!(manifest_dataset_version(&store), before, "{args:?}"); + let admitted = maintain(args, "act-maintainer"); + assert!(admitted.status.success(), "{args:?}: {admitted:?}"); + } +} + #[test] fn managed_access_uses_the_selected_identity_and_preserves_branch_scope() { use crate::support::managed_http::{IntentApiFixture, IntentReply}; diff --git a/crates/omnigraph-cli/tests/integration/cli_mcp.rs b/crates/omnigraph-cli/tests/integration/cli_mcp.rs index cf2e7fc60..896c7a05f 100644 --- a/crates/omnigraph-cli/tests/integration/cli_mcp.rs +++ b/crates/omnigraph-cli/tests/integration/cli_mcp.rs @@ -351,6 +351,7 @@ impl Served { output_success( cli() .arg("load") + .args(["--as", "act-agent"]) .arg("--data") .arg(fixture("test.jsonl")) .arg("--mode") diff --git a/crates/omnigraph-cli/tests/integration/system_local.rs b/crates/omnigraph-cli/tests/integration/system_local.rs index 08a9c5473..e9017629f 100644 --- a/crates/omnigraph-cli/tests/integration/system_local.rs +++ b/crates/omnigraph-cli/tests/integration/system_local.rs @@ -2110,23 +2110,7 @@ graphs: } fn seed_graph(dir: &std::path::Path, graph: &str, row: &str) { - let data = dir.join(format!("{graph}-seed.jsonl")); - std::fs::write(&data, row).unwrap(); - let output = cli() - .arg("load") - .arg("--mode") - .arg("overwrite") - .arg("--data") - .arg(&data) - .arg("--target") - .arg(dir.join(format!("graphs/{graph}.omni"))) - .output() - .unwrap(); - assert!( - output.status.success(), - "seed {graph} failed: {}", - String::from_utf8_lossy(&output.stderr) - ); + seed_as_storage_owner(&dir.join(format!("graphs/{graph}.omni")), row); unlock_cluster_fixture(dir); } @@ -2691,6 +2675,7 @@ fn local_cli_operator_alias_and_server_flag_invoke_stored_query() { output_success( cli() .arg("load") + .args(["--as", "act-op"]) .arg("--data") .arg(fixture("test.jsonl")) .arg("--mode") diff --git a/crates/omnigraph-cli/tests/support/mod.rs b/crates/omnigraph-cli/tests/support/mod.rs index edaac4e3f..4f55c29ea 100644 --- a/crates/omnigraph-cli/tests/support/mod.rs +++ b/crates/omnigraph-cli/tests/support/mod.rs @@ -809,22 +809,29 @@ pub fn converged_loaded_cluster(graph_id: &str, policy_yaml: Option<&str>) -> Cl apply_cluster_fixture(&dir); + // `POLICY_YAML` lets no actor change the protected `main`. let served_root = dir.join("graphs").join(format!("{graph_id}.omni")); - output_success( - cli() - .arg("load") - .arg("--data") - .arg(fixture("test.jsonl")) - .arg("--mode") - .arg("overwrite") - .arg("--target") - .arg(&served_root), + seed_as_storage_owner( + &served_root, + &fs::read_to_string(fixture("test.jsonl")).unwrap(), ); - unlock_cluster_fixture(&dir); ClusterFixture { _temp: temp, dir } } +/// Overwrite `graph`'s `main` with the JSONL `data` as a storage owner's +/// embedded host that installs no policy. A direct CLI load of a cluster graph +/// is judged by the graph's applied policy, which may admit no actor to `main`. +pub fn seed_as_storage_owner(graph: &Path, data: &str) { + tokio::runtime::Runtime::new().unwrap().block_on(async { + let db = Omnigraph::open(&graph.to_string_lossy()).await.unwrap(); + session_over(db) + .load_jsonl(data, omnigraph::loader::LoadMode::Overwrite) + .await + .unwrap(); + }); +} + /// Build a converged cluster with one graph `graph_id` and the policy layout /// `docs/user/operations/policy.md` documents: `graph_policy`, when given, is /// bound to the graph and `cluster_policy`, when given, to the `cluster` @@ -1023,7 +1030,12 @@ rules: - id: cluster-operators-change allow: actors: { group: cluster_operators } - actions: [change, schema_apply] + actions: [change, schema_apply, maintain] + - id: cluster-operators-branch + allow: + actors: { group: cluster_operators } + actions: [branch_create] + target_branch_scope: any "#, ) .unwrap(); @@ -1657,9 +1669,12 @@ policies: let served_root = cluster_dir .join("graphs") .join(format!("{PARITY_GRAPH_ID}.omni")); + // A direct write to the cluster graph is judged by its applied policy, + // which admits `act-parity`. output_success( fixture_cli() .arg("load") + .args(["--as", "act-parity"]) .arg("--data") .arg(fixture("test.jsonl")) .arg("--mode") diff --git a/crates/omnigraph-cluster/src/admission.rs b/crates/omnigraph-cluster/src/admission.rs index 8bad6884d..f56211231 100644 --- a/crates/omnigraph-cluster/src/admission.rs +++ b/crates/omnigraph-cluster/src/admission.rs @@ -428,6 +428,27 @@ impl ClusterAdmission { self.admitted_graph_id(graph_uri).map(|_| ()) } + /// The policy the applied revision binds to the admitted graph at + /// `graph_uri`, or `None` when it binds none. A storage owner's handle + /// installs it as a server's does, so a direct writer is refused what a + /// served one is. It is read from the state under this admission's lock, + /// which a deployment needs to change it, so it holds for the admission's + /// life. Only the bundles bound to the graph are read; one that does not + /// load refuses. + pub async fn graph_policy( + &self, + graph_uri: &str, + ) -> Result>, Diagnostic> { + let graph = self.admitted_graph_id(graph_uri)?; + let store = self.store(); + let state = store + .read_state(&mut store.observations()) + .await? + .state + .ok_or_else(missing_state)?; + crate::authorization::AppliedPolicies::load_graph(&store, &state, &graph).await + } + fn admitted_graph_id(&self, graph_uri: &str) -> Result { admitted_graph_id( self.canonical_root(), diff --git a/crates/omnigraph-cluster/src/authorization.rs b/crates/omnigraph-cluster/src/authorization.rs index a992307aa..23039e820 100644 --- a/crates/omnigraph-cluster/src/authorization.rs +++ b/crates/omnigraph-cluster/src/authorization.rs @@ -300,6 +300,62 @@ impl AppliedPolicies { }) } + /// The policy bound to `graph` alone. Only bundles that bind it are read, + /// so a damaged payload the graph does not use cannot block it, while a + /// bound bundle that is absent, oversized or invalid refuses, as does a + /// policy entry without bindings or a second bundle binding the graph. + pub(crate) async fn load_graph( + backend: &ClusterStore, + state: &ClusterState, + graph: &str, + ) -> Result>, Diagnostic> { + if state.applied_revision.resources.len() > MAX_AUTHORIZATION_RESOURCES { + return Err(refusal( + "policy_bounds_exceeded", + CLUSTER_STATE_FILE, + "applied resource count exceeds the authorization bound", + )); + } + let binding = format!("graph.{graph}"); + let mut engine = None; + for (address, entry) in &state.applied_revision.resources { + let kind = resource_kind(address); + if !matches!(kind, ResourceKind::Policy(_)) { + continue; + } + let bindings = entry.applies_to.as_ref().ok_or_else(|| { + refusal( + "applied_policy_invalid", + address, + "applied policy has no scope bindings", + ) + })?; + if !bindings.iter().any(|bound| bound == &binding) { + continue; + } + let source = backend + .read_verified_payload_bounded(&kind, &entry.digest, address, MAX_POLICY_BYTES) + .await?; + if source.len() > MAX_POLICY_BYTES { + return Err(refusal( + "policy_bounds_exceeded", + address, + "applied policy bytes exceed the authorization bound", + )); + } + let loaded = PolicyEngine::load_graph_from_source(&source, graph) + .map_err(|err| refusal("applied_policy_invalid", address, err.to_string()))?; + if engine.replace(Arc::new(loaded)).is_some() { + return Err(refusal( + "applied_policy_invalid", + address, + "more than one policy binds the graph", + )); + } + } + Ok(engine) + } + pub(crate) fn check_cluster(&self, actor: &str) -> Result<(), Diagnostic> { check( self.cluster.as_ref().ok_or_else(|| { diff --git a/crates/omnigraph/src/db/omnigraph.rs b/crates/omnigraph/src/db/omnigraph.rs index 1993698b5..31349932e 100644 --- a/crates/omnigraph/src/db/omnigraph.rs +++ b/crates/omnigraph/src/db/omnigraph.rs @@ -493,9 +493,9 @@ pub struct Omnigraph { /// (MR-725), which extends the same trait with a different method. /// Don't be tempted to add per-row enforcement here. /// - /// Set via `with_policy(checker)` after construction. Today only - /// `apply_schema_as` consults this field (PR #2 proof-of-concept); - /// PR #3 fans the `enforce()` call out to the remaining writers. + /// Set via `with_policy(checker)` after construction: the server, + /// cluster deployment and the CLI's writable opener of a cluster graph + /// install the policy the applied revision binds to the graph. policy: Option>, /// Lazily-built, reused-across-queries embedding client. Built on the first /// `nearest($v, "string")` that needs server-side embedding (so a graph that @@ -1183,11 +1183,10 @@ impl Omnigraph { /// Engine-layer policy enforcement gate (MR-722 chassis core). /// /// * If no policy is installed → no-op (returns `Ok(())`). - /// * If policy is installed AND actor is None → denial with a - /// clear "no actor for engine-layer policy check" message. - /// Forces server / CLI / SDK callers to thread an actor through - /// when policy is configured — silent bypass via "I forgot the - /// actor" is exactly the footgun this gate is here to prevent. + /// * If policy is installed AND actor is None → denial naming the + /// action. A direct CLI write on a cluster graph with a policy and + /// no `--as` reaches this, as does any embedder that names no + /// actor: no actor is never a bypass. /// * If policy is installed AND actor is Some → call /// `PolicyChecker::check(action, scope, actor)`; map denial / /// internal failure to `OmniError::Policy(...)`. @@ -1209,12 +1208,10 @@ impl Omnigraph { return Ok(()); }; let Some(actor) = actor else { - return Err(OmniError::Policy( - "no actor for engine-layer policy check (policy is configured but the call site \ - didn't thread an actor through — this is almost certainly a bug, not an \ - intended bypass)" - .to_string(), - )); + return Err(OmniError::Policy(format!( + "policy denied action '{action}': a policy is installed and the request names \ + no actor" + ))); }; checker .check(action, scope, actor) diff --git a/docs/user/cli/reference.md b/docs/user/cli/reference.md index da0746133..7cec5f950 100644 --- a/docs/user/cli/reference.md +++ b/docs/user/cli/reference.md @@ -42,7 +42,9 @@ state. Nothing in the target records its base, so pass the same `--base` on every open of that target; a clone root opened without `--base` is refused, since its marker says it is a clone and not which base it was cloned from. -`--as ACTOR` attributes supported direct operations. A served target derives its +`--as ACTOR` attributes supported direct operations; on a cluster graph the +applied graph policy judges them by it ([direct writes](../operations/policy.md#actor-identity)). +A served target derives its actor from its credential and sends `--as` as the `Omnigraph-If-Actor` assertion, exiting 4 on a mismatch ([Assert the actor](../operations/server.md#assert-the-actor)); a managed target refuses it. `--yes` supplies noninteractive consent for destructive diff --git a/docs/user/operations/maintenance.md b/docs/user/operations/maintenance.md index 08342d7f5..f1e6f6504 100644 --- a/docs/user/operations/maintenance.md +++ b/docs/user/operations/maintenance.md @@ -21,13 +21,13 @@ targets accept local files only; an inline [S3 cluster root](s3-cluster-roots.md is the one cloud-direct exception. See [operator configuration](../cli/targets.md#transport-and-capability-boundaries). -Each command acts as the operator configuration's `operator.actor`, and the -commit it publishes records that actor; `index build` and `index rebuild` also -accept `--as` in its place. Direct CLI access, including `--target`, does not -load the server's Cedar policy; storage permissions are its trust boundary. An -embedded host that installs a policy checker enforces the +Each command acts as its `--as` actor, and the commit it publishes records +that actor. On a cluster graph the CLI installs the policy the cluster applied +to it, and an embedded host may install its own; either checks the [policy actions](policy.md#actions) before any effect: `maintain` for optimize, -index builds and the full-text rebuild, and `reclaim` for cleanup. +index builds and the full-text rebuild, and `reclaim` for cleanup. A standalone +graph has no policy. The actor is self-declared, so storage permissions remain +the trust boundary. ## Optimize diff --git a/docs/user/operations/policy.md b/docs/user/operations/policy.md index 75704f0c4..424b7e1a6 100644 --- a/docs/user/operations/policy.md +++ b/docs/user/operations/policy.md @@ -52,8 +52,8 @@ operation maintains (`main` for optimize) and takes `branch_scope`; `reclaim` covers every branch's history and takes no branch scope. `change` admits no maintenance: index builds and the full-text rebuild need `maintain` on their branch. The engine checks these actions whenever a policy is installed on the -graph handle; the direct maintenance commands load no policy (see -[maintenance](maintenance.md)). +graph handle, which a direct command on a cluster graph does (see +[direct writes](#actor-identity)). ## Bind a policy @@ -234,6 +234,9 @@ decide; a server without authentication allows every graph action and reports `actor_id: null`. The MCP `access` tool returns the same body, and `omnigraph access` prints it for a server or managed target ([what you may do at a target](../cli/targets.md#what-you-may-do-at-a-target)). +For a direct cluster target it evaluates the policy the cluster applied to the +graph, which also judges the CLI's direct writes and maintenance there. Direct +reads are not judged: storage access is their trust boundary. It reports policy actions, not actor views, so a view can still refuse a `change` the policy allows. It does not report `reclaim`, since no server @@ -254,9 +257,15 @@ For direct CLI writes, actor resolution is: The version-1 operator document has no actor field. -When a policy is installed, a missing actor is denied. Only the server -resolves a served write's actor; there `--as` is an assertion the server checks -against the token ([Assert the actor](server.md#assert-the-actor)). +A direct write to a cluster graph, through its root target with `--graph` +or through its own store, installs the policy the cluster applied to that +graph, the policy `omnigraph access` reports for that target. Every write and +maintenance command is then judged by it before any effect, and a missing actor is +denied. A standalone graph has no policy. A direct actor is self-declared, so +this keeps a storage owner within the policy rather than authenticating them: +storage permissions remain the trust boundary. Only the server resolves a +served write's actor; there `--as` is an assertion the server checks against +the token ([Assert the actor](server.md#assert-the-actor)). Successful graph commits record the actor for the whole atomic change. Inspect the audit trail with: diff --git a/skills/omnigraph/SKILL.md b/skills/omnigraph/SKILL.md index 5339cec92..383ec2571 100644 --- a/skills/omnigraph/SKILL.md +++ b/skills/omnigraph/SKILL.md @@ -205,7 +205,8 @@ backend. `--config DIR` is source input only. Bare target names resolve from the operator file; use `./` for relative inline paths. `init --schema schema.pg ./graph.omni` is the sole positional backend -address convenience. `--as ACTOR` attributes supported direct operations and +address convenience. `--as ACTOR` attributes supported direct operations, is +the actor a cluster graph's applied policy judges them by, and names the actor `access` reports for direct storage; served targets derive their actor from credentials and send `--as` as the `Omnigraph-If-Actor` assertion, refusing a mismatch with `actor_mismatch` and diff --git a/skills/omnigraph/references/commands.md b/skills/omnigraph/references/commands.md index 7f67f4d9b..9f652d754 100644 --- a/skills/omnigraph/references/commands.md +++ b/skills/omnigraph/references/commands.md @@ -362,8 +362,9 @@ for that dependency change. Do not mix fleets across an incompatible analyzer transition. Rebuilds use default English analysis, replacing custom tokenizer settings; JSON `warnings` reports this for actual work. Check the selected `branch`, `graph_commit_id`, and `rebuilt_indexes`; an empty list/null commit is -a no-op, not a migration of other branches or historical snapshots. `--as` is -actor attribution and does not install server policy on direct access. +a no-op, not a migration of other branches or historical snapshots. On a +cluster graph the cluster's applied graph policy judges `--as` (`maintain` on +the branch); a standalone graph has no policy. ### `cleanup` — destructive version GC @@ -386,7 +387,9 @@ drops does not stop it; `--older-than` reads every other commit's time and stops on one it cannot read. Without `--confirm`, cleanup only echoes the policy and exits 0; it lists no candidates. Cleanup also reclaims table forks and deleted branches' refs once nothing needs them. Branch -deletion and `optimize` leave this reclamation to `cleanup`. +deletion and `optimize` leave this reclamation to `cleanup`. On a cluster +graph the applied policy judges the `--as` actor: `reclaim` for `cleanup`, +`maintain` for `optimize` and `index`. ## Stored Queries diff --git a/skills/omnigraph/references/server-policy.md b/skills/omnigraph/references/server-policy.md index 3547dbb87..2c14413b9 100644 --- a/skills/omnigraph/references/server-policy.md +++ b/skills/omnigraph/references/server-policy.md @@ -241,11 +241,14 @@ Served requests always use the server's policy engine. Embedded engine hosts can also install a policy engine, and every mutating engine entry point then enforces it. -The standalone CLI opening a direct `--target` does **not** load the -cluster server's Cedar bundle. Its `--as` value records actor attribution but -does not recreate server authorization. Protect raw graph storage with object -store IAM/ACLs and restrict who can run direct maintenance. Served writes reject -client-supplied actor identity because only the token may select it. +A direct CLI write or maintenance command on a cluster graph (a root +target with `--graph`, or the graph's own store) installs the policy the +cluster applied to that graph, the one `omnigraph access` reports. It refuses +an actor the policy does not admit, or no `--as`, with `forbidden` before any +effect, as the server would. A standalone graph has no policy. The direct actor +is self-declared, so this is not authentication: protect raw graph storage with +object store IAM/ACLs. Served writes reject client-supplied actor identity +because only the token may select it. Canonical contracts: [server operations](https://github.com/ModernRelay/omnigraph/blob/main/docs/user/operations/server.md) and [authorization](https://github.com/ModernRelay/omnigraph/blob/main/docs/user/operations/policy.md). From 4dbdfb6999ac7b232b8de64a77aac2f63fc6ad67 Mon Sep 17 00:00:00 2001 From: Ragnor Comerford Date: Mon, 16 Nov 2026 12:46:21 -0800 Subject: [PATCH 2/3] fix(cli): admit before building --base storage; served optimize actor mismatch exits 4 open_writable takes the storage future and awaits it after admission, so a write refused by a held cluster lock never builds the read-through adapter that writes a clone marker. A served optimize whose --as the credential does not match exits 4, as other served writes do. The S3 direct-root journey names an actor its graph policy admits for optimize and cleanup. --- crates/omnigraph-cli/src/admission.rs | 9 ++++---- crates/omnigraph-cli/src/client.rs | 2 +- .../src/commands/maintenance/mod.rs | 8 +++---- .../src/commands/maintenance/served.rs | 21 +++++++++++++++++++ .../tests/integration/cli_cluster.rs | 16 ++++++++++++++ .../tests/integration/cli_cluster_e2e.rs | 12 ++++++++++- crates/omnigraph-cli/tests/support/mod.rs | 4 ++++ 7 files changed, 62 insertions(+), 10 deletions(-) diff --git a/crates/omnigraph-cli/src/admission.rs b/crates/omnigraph-cli/src/admission.rs index ea77be641..073881adb 100644 --- a/crates/omnigraph-cli/src/admission.rs +++ b/crates/omnigraph-cli/src/admission.rs @@ -74,11 +74,12 @@ pub(crate) async fn open_read_only_with_binding( /// is admitted first (before the opener's capability probe), and the policy /// the applied revision binds to it is installed on the handle, so every /// `_as` writer judges the declared actor as a server judges a served one. A -/// standalone graph has no policy. `storage` is the adapter the caller opens -/// the graph with. +/// standalone graph has no policy. `storage` builds the adapter the caller +/// opens the graph with; it runs only once the graph is admitted, since +/// building a read-through adapter under `--base` writes the clone marker. pub(crate) async fn open_writable( binding: &CapturedStorageBinding, - storage: Arc, + storage: impl Future>>, stderr: &mut dyn Write, ) -> Result { let policy = match ensure_graph_with_binding(binding, stderr).await? { @@ -86,7 +87,7 @@ pub(crate) async fn open_writable( None => None, }; crate::command_outcome::writable_open(); - let db = omnigraph::db::Omnigraph::open_with_storage(binding.uri(), storage).await?; + let db = omnigraph::db::Omnigraph::open_with_storage(binding.uri(), storage.await?).await?; Ok(match policy { Some(policy) => db.with_policy(policy), None => db, diff --git a/crates/omnigraph-cli/src/client.rs b/crates/omnigraph-cli/src/client.rs index 805fb0916..2ab919225 100644 --- a/crates/omnigraph-cli/src/client.rs +++ b/crates/omnigraph-cli/src/client.rs @@ -486,7 +486,7 @@ impl GraphClient { stderr: &mut dyn Write, ) -> Result { let (defaults, sources) = omnigraph::settings::from_env()?; - let storage = crate::admission::embedded_storage(binding, base).await?; + let storage = crate::admission::embedded_storage(binding, base); let db = crate::admission::open_writable(binding, storage, stderr).await?; let db = match external_blob_policy { Some(policy) => db.with_external_blob_policy(policy)?, diff --git a/crates/omnigraph-cli/src/commands/maintenance/mod.rs b/crates/omnigraph-cli/src/commands/maintenance/mod.rs index a1e7f4914..c983b96e0 100644 --- a/crates/omnigraph-cli/src/commands/maintenance/mod.rs +++ b/crates/omnigraph-cli/src/commands/maintenance/mod.rs @@ -97,7 +97,7 @@ pub(crate) async fn run_optimize( let actor = resolve_actor(scope.operator, scope.actor, stderr)?; let db = crate::admission::open_writable( &binding, - omnigraph::storage::storage_for_binding(&binding)?, + async { Ok(omnigraph::storage::storage_for_binding(&binding)?) }, stderr, ) .await?; @@ -119,7 +119,7 @@ pub(crate) async fn run_index( let actor = resolve_actor(scope.operator, scope.actor, stderr)?; let db = crate::admission::open_writable( &binding, - omnigraph::storage::storage_for_binding(&binding)?, + async { Ok(omnigraph::storage::storage_for_binding(&binding)?) }, stderr, ) .await?; @@ -177,7 +177,7 @@ pub(crate) async fn rebuild_full_text_indexes( let uri = binding.uri(); let db = crate::admission::open_writable( binding, - omnigraph::storage::storage_for_binding(binding)?, + async { Ok(omnigraph::storage::storage_for_binding(binding)?) }, stderr, ) .await?; @@ -231,7 +231,7 @@ pub(crate) async fn run_cleanup( let actor = resolve_actor(scope.operator, scope.actor, stderr)?; let db = crate::admission::open_writable( &binding, - omnigraph::storage::storage_for_binding(&binding)?, + async { Ok(omnigraph::storage::storage_for_binding(&binding)?) }, stderr, ) .await?; diff --git a/crates/omnigraph-cli/src/commands/maintenance/served.rs b/crates/omnigraph-cli/src/commands/maintenance/served.rs index 2d6cbec05..01b792873 100644 --- a/crates/omnigraph-cli/src/commands/maintenance/served.rs +++ b/crates/omnigraph-cli/src/commands/maintenance/served.rs @@ -41,6 +41,8 @@ pub(crate) struct ServedOptimize { enum Refusal { /// The id names another request. DifferentRequest, + /// The credential resolves to another actor than `--as` asserts. + ActorMismatch, /// Another operation holds the scope's active slot. AnotherActive, /// Refused before acceptance: nothing ran. @@ -61,6 +63,9 @@ fn classify(error: &color_eyre::Report) -> Refusal { { Refusal::DifferentRequest } + 412 if remote.output.code == Some(omnigraph_api_types::ErrorCode::ActorMismatch) => { + Refusal::ActorMismatch + } 429 => Refusal::AnotherActive, // A server error that says it took no effect (routes off, admission // closed) refused the request before acceptance; any other server @@ -183,6 +188,10 @@ pub(crate) async fn run( writeln!(stderr, "error: {error}")?; return Ok(Completion::exit(DIFFERENT_REQUEST)); } + Refusal::ActorMismatch => { + writeln!(stderr, "error: {error}")?; + return Ok(Completion::exit(crate::EXIT_PRECONDITION_FAILED)); + } Refusal::AnotherActive => { writeln!(stderr, "error: {error}")?; return Ok(Completion::exit(ANOTHER_ACTIVE)); @@ -385,6 +394,18 @@ mod tests { classify(&remote(409, "conflict", "deployment d is outstanding")), Refusal::BeforeAcceptance ); + assert_eq!( + classify(&remote( + 412, + "actor_mismatch", + "the credential is another actor" + )), + Refusal::ActorMismatch + ); + assert_eq!( + classify(&remote(412, "precondition_failed", "graph moved")), + Refusal::BeforeAcceptance + ); assert_eq!( classify(&remote(429, "too_many_requests", "active")), Refusal::AnotherActive diff --git a/crates/omnigraph-cli/tests/integration/cli_cluster.rs b/crates/omnigraph-cli/tests/integration/cli_cluster.rs index cb04c4728..a1a1c8618 100644 --- a/crates/omnigraph-cli/tests/integration/cli_cluster.rs +++ b/crates/omnigraph-cli/tests/integration/cli_cluster.rs @@ -3290,10 +3290,25 @@ async fn v2_root_admission_blocks_cli_write_and_native_control_doors() { .unwrap(); let graph = temp.path().join("graphs/knowledge.omni"); let before = fs::read(temp.path().join("__cluster/state.json")).unwrap(); + // A write under `--base` builds a read-through adapter, which writes the + // clone marker, so it must be refused before that adapter is built. + let clone_base = tempdir().unwrap(); + let base_graph = clone_base.path().join("base.omni"); + init_graph(&base_graph); + let data = clone_base.path().join("row.jsonl"); + fs::write( + &data, + "{\"type\": \"Person\", \"data\": {\"name\": \"Eve\"}}\n", + ) + .unwrap(); + let (data, base_graph) = (data.to_str().unwrap(), base_graph.to_str().unwrap()); for args in [ vec!["optimize", "--json"], vec!["cleanup", "--keep", "1", "--confirm", "--json"], vec!["branch", "create", "must-not-exist"], + vec![ + "load", "--data", data, "--mode", "append", "--base", base_graph, + ], ] { let output = output_failure(cli().args(&args).arg("--target").arg(&graph).arg("--yes")); assert!( @@ -3301,6 +3316,7 @@ async fn v2_root_admission_blocks_cli_write_and_native_control_doors() { "{args:?}: {output:?}" ); } + assert!(!graph.join("__clone").exists()); assert_eq!( fs::read(temp.path().join("__cluster/state.json")).unwrap(), before diff --git a/crates/omnigraph-cli/tests/integration/cli_cluster_e2e.rs b/crates/omnigraph-cli/tests/integration/cli_cluster_e2e.rs index 2a2f4141f..2f1fc015e 100644 --- a/crates/omnigraph-cli/tests/integration/cli_cluster_e2e.rs +++ b/crates/omnigraph-cli/tests/integration/cli_cluster_e2e.rs @@ -152,8 +152,16 @@ fn cluster_e2e_s3_direct_root_deploys_unlocks_and_maintains_issue_1163() { ); assert!(status()["lock_id"].is_null()); + // The graph's applied policy judges maintenance by its actor. for maintenance in [ - vec!["optimize", "--graph", "knowledge", "--json"], + vec![ + "optimize", + "--graph", + "knowledge", + "--as", + "act-operator", + "--json", + ], vec![ "cleanup", "--graph", @@ -162,6 +170,8 @@ fn cluster_e2e_s3_direct_root_deploys_unlocks_and_maintains_issue_1163() { "1", "--confirm", "--yes", + "--as", + "act-operator", "--json", ], ] { diff --git a/crates/omnigraph-cli/tests/support/mod.rs b/crates/omnigraph-cli/tests/support/mod.rs index 4f55c29ea..233f9e960 100644 --- a/crates/omnigraph-cli/tests/support/mod.rs +++ b/crates/omnigraph-cli/tests/support/mod.rs @@ -1036,6 +1036,10 @@ rules: actors: { group: cluster_operators } actions: [branch_create] target_branch_scope: any + - id: cluster-operators-reclaim + allow: + actors: { group: cluster_operators } + actions: [reclaim] "#, ) .unwrap(); From 915ef136ed2a56172ea3036d26be05a6f76d49d4 Mon Sep 17 00:00:00 2001 From: Ragnor Comerford Date: Mon, 16 Nov 2026 17:22:23 -0800 Subject: [PATCH 3/3] fix(storage): refuse --base over a target that is not a clone root A read-through mount wrote __clone/created into any layer it had not marked, so a --base write refused after the open (by policy, say) left an ordinary graph marked as a clone, and it then refused every open without --base. The mount now refuses a layer that holds objects under its prefix but no marker, before any write. Also drops the unused uri argument of the writable openers and corrects the stale policy comment on GraphClient::Embedded. --- crates/omnigraph-cli/src/client.rs | 70 ++++++++----------- .../tests/integration/cli_data.rs | 31 ++++++++ crates/omnigraph-storage/src/read_through.rs | 44 +++++++++--- .../src/read_through_contract.rs | 41 +++++++++++ .../omnigraph/tests/integration/s3_storage.rs | 1 + docs/user/cli/reference.md | 2 + docs/user/operations/policy.md | 4 +- docs/user/operations/s3-cluster-roots.md | 7 +- 8 files changed, 145 insertions(+), 55 deletions(-) diff --git a/crates/omnigraph-cli/src/client.rs b/crates/omnigraph-cli/src/client.rs index 2ab919225..f36875acf 100644 --- a/crates/omnigraph-cli/src/client.rs +++ b/crates/omnigraph-cli/src/client.rs @@ -203,8 +203,9 @@ pub(crate) fn parse_set_flags(flags: &[String]) -> Result, @@ -416,12 +417,11 @@ impl GraphClient { /// graph's applied policy is installed on the handle, and the declared /// actor rides the `_as` APIs into it. async fn open_write( - uri: &str, binding: &CapturedStorageBinding, base: Option<&str>, stderr: &mut dyn Write, ) -> Result { - Self::open_write_session(uri, binding, base, &[], stderr).await + Self::open_write_session(binding, base, &[], stderr).await } /// Read dispatch uses no writable opener or retained writer admission. @@ -462,23 +462,19 @@ impl GraphClient { /// environment's defaults and the `--set` values, every setting accepted; /// the source's own `set` lines apply per call, on top. async fn open_write_session( - uri: &str, binding: &CapturedStorageBinding, base: Option<&str>, settings: &[(SettingId, SettingValue)], stderr: &mut dyn Write, ) -> Result { - Self::open_write_session_with_external_blob_policy( - uri, binding, base, settings, None, stderr, - ) - .await + Self::open_write_session_with_external_blob_policy(binding, base, settings, None, stderr) + .await } /// An embedded write session, with `external_blob_policy` installed on /// its fresh handle when given: the one way a CLI run admits a source /// outside the graph (a `load csv "file://…"` statement run directly). async fn open_write_session_with_external_blob_policy( - _uri: &str, binding: &CapturedStorageBinding, base: Option<&str>, settings: &[(SettingId, SettingValue)], @@ -1305,7 +1301,7 @@ impl GraphClient { remote_response_json_bounded(response, token.as_deref(), *response_limit).await } GraphClient::Embedded { - uri, + uri: _, actor, binding, base, @@ -1313,8 +1309,7 @@ impl GraphClient { refuse_noncanonical_branches([Some(branch), from])?; let data = std::fs::read_to_string(data)?; let session = - Self::open_write_session(uri, binding, base.as_deref(), settings, stderr) - .await?; + Self::open_write_session(binding, base.as_deref(), settings, stderr).await?; // A missing branch is forked first, which publishes on its // own; the engine marks a later refusal as following it. let receipt = session @@ -1391,7 +1386,7 @@ impl GraphClient { .await } GraphClient::Embedded { - uri, + uri: _, actor, binding, base, @@ -1401,8 +1396,7 @@ impl GraphClient { let params = query_params_from_json(&query_params, params_json)?; refuse_noncanonical_branches([branch])?; let session = - Self::open_write_session(uri, binding, base.as_deref(), settings, stderr) - .await?; + Self::open_write_session(binding, base.as_deref(), settings, stderr).await?; let actor = actor.as_deref(); let receipt = session .mutate_as_with_optional_branch_receipt( @@ -1516,7 +1510,7 @@ impl GraphClient { Ok(output) } GraphClient::Embedded { - uri, + uri: _, actor, binding, base, @@ -1552,14 +1546,9 @@ impl GraphClient { as_commit, } => { let target = into.unwrap_or_else(|| "main".to_string()); - let mut session = Self::open_write_session( - uri, - binding, - base.as_deref(), - settings, - stderr, - ) - .await?; + let mut session = + Self::open_write_session(binding, base.as_deref(), settings, stderr) + .await?; Self::apply_prefix(&mut session, query_source)?; let result = session .branch_merge_as_with_options( @@ -1652,15 +1641,14 @@ impl GraphClient { Ok(output) } GraphClient::Embedded { - uri, + uri: _, actor, binding, base, } => { let query_name = write.statement_name().to_string(); let mut session = - Self::open_write_session(uri, binding, base.as_deref(), settings, stderr) - .await?; + Self::open_write_session(binding, base.as_deref(), settings, stderr).await?; Self::apply_prefix(&mut session, query_source)?; let target = session .get_commit(write.graph_commit_id()) @@ -1739,7 +1727,7 @@ impl GraphClient { .await } GraphClient::Embedded { - uri, + uri: _, actor, binding, base, @@ -1747,7 +1735,6 @@ impl GraphClient { let query_name = stmt.statement_name().to_string(); let request = omnigraph::loader::CsvLoadRequest::from_statement(&stmt); let mut session = Self::open_write_session_with_external_blob_policy( - uri, binding, base.as_deref(), settings, @@ -1803,13 +1790,13 @@ impl GraphClient { .await? } GraphClient::Embedded { - uri, + uri: _, actor, binding, base, } => { let session = - Self::open_write_session(uri, binding, base.as_deref(), &[], stderr).await?; + Self::open_write_session(binding, base.as_deref(), &[], stderr).await?; commit_output( &session .publish_commit_as(commit_id, actor.as_deref()) @@ -1847,13 +1834,13 @@ impl GraphClient { .await } GraphClient::Embedded { - uri, + uri: _, actor, binding, base, } => { let session = - Self::open_write_session(uri, binding, base.as_deref(), &[], stderr).await?; + Self::open_write_session(binding, base.as_deref(), &[], stderr).await?; session .drop_commit_as(commit_id, actor.as_deref()) .await @@ -2258,7 +2245,7 @@ impl GraphClient { binding, base, } => { - let db = Self::open_write(uri, binding, base.as_deref(), stderr).await?; + let db = Self::open_write(binding, base.as_deref(), stderr).await?; let actor = actor.as_deref(); let created = db .branch_create_from_as(start, name, actor) @@ -2306,7 +2293,7 @@ impl GraphClient { binding, base, } => { - let db = Self::open_write(uri, binding, base.as_deref(), stderr).await?; + let db = Self::open_write(binding, base.as_deref(), stderr).await?; let actor = actor.as_deref(); db.branch_delete_as(name, actor).await.engine_write()?; Ok(BranchDeleteOutput { @@ -2382,14 +2369,13 @@ impl GraphClient { } } GraphClient::Embedded { - uri, + uri: _, actor, binding, base, } => { let session = - Self::open_write_session(uri, binding, base.as_deref(), settings, stderr) - .await?; + Self::open_write_session(binding, base.as_deref(), settings, stderr).await?; let actor = actor.as_deref(); let result = session .branch_merge_as_with_options(source, into, actor, as_commit) @@ -2568,7 +2554,7 @@ impl GraphClient { binding, base, } => { - let db = Self::open_write(uri, binding, base.as_deref(), stderr).await?; + let db = Self::open_write(binding, base.as_deref(), stderr).await?; let result = db .apply_schema_as_with_catalog_check(schema_source, actor.as_deref(), validate) .await @@ -2823,13 +2809,13 @@ impl GraphClient { let branch = query.branch.as_deref().unwrap_or("main"); match self { GraphClient::Embedded { - uri, + uri: _, actor, binding, base, } => { let session = - Self::open_write_session(uri, binding, base.as_deref(), &[], stderr).await?; + Self::open_write_session(binding, base.as_deref(), &[], stderr).await?; let cell = blob_write_cell(query); let outcome = match bytes { Some(bytes) => { diff --git a/crates/omnigraph-cli/tests/integration/cli_data.rs b/crates/omnigraph-cli/tests/integration/cli_data.rs index c44f1972c..d9cdf5f65 100644 --- a/crates/omnigraph-cli/tests/integration/cli_data.rs +++ b/crates/omnigraph-cli/tests/integration/cli_data.rs @@ -6687,6 +6687,37 @@ query insert_person($name: String, $age: I32) { } } + // `--base` over the graph's store is refused before the read-through + // adapter writes its clone marker: the graph is not a clone root, and a + // refused write must leave it openable without the base. + let base = temp.path().join("base.omni"); + init_graph(&base); + let before = manifest_dataset_version(&store); + let mut load = cli(); + load.arg("load").arg("--target").arg(&store); + load.arg("--base") + .arg(&base) + .arg("--data") + .arg(temp.path().join("row-1.jsonl")) + .args(["--mode", "append", "--as", "act-outsider", "--json"]); + let refused = load.output().unwrap(); + unlock_cluster_fixture(&root); + assert!(!refused.status.success(), "{refused:?}"); + let said = format!( + "{}{}", + String::from_utf8_lossy(&refused.stdout), + String::from_utf8_lossy(&refused.stderr) + ); + assert!(said.contains("not a clone root"), "{said}"); + assert!(!store.join("__clone").exists()); + assert_eq!(manifest_dataset_version(&store), before); + output_success( + cli() + .args(["schema", "show", "--target"]) + .arg(&store) + .arg("--json"), + ); + assert!(may_change_main(Some("act-writer"))); for by_store in [false, true] { let before = manifest_dataset_version(&store); diff --git a/crates/omnigraph-storage/src/read_through.rs b/crates/omnigraph-storage/src/read_through.rs index 4101d46b0..bf713d154 100644 --- a/crates/omnigraph-storage/src/read_through.rs +++ b/crates/omnigraph-storage/src/read_through.rs @@ -378,16 +378,20 @@ impl ReadThroughMount { /// own objects: the harness leaves it out of a clone root's shape proof. pub const RESERVED_DIRECTORY: &'static str = RESERVED; - /// Mask the deletes an earlier mount recorded in `layer`, and give a - /// layer that has no reserved directory yet its `__clone/created` object, - /// so every clone root carries the directory from its first build. + /// Mask the deletes an earlier mount recorded in `layer`, and give an + /// empty layer its `__clone/created` object, so every clone root carries + /// the directory from its first build. /// /// # Errors /// When the layer's listing or that first write fails, or when `frozen` /// holds the reserved directory itself: it is then a clone root, and /// reading through a clone root would lose its base and its whiteouts. /// Also when `frozen` holds an object at the directory's name, which no - /// read or listing of a clone could show. + /// read or listing of a clone could show. Also, before any write, when + /// the layer holds objects under `prefix` but no `__clone/created`: it is + /// then not a clone root (an ordinary graph, say), and marking it would + /// turn it into one, so a command refused after the open would leave it + /// unopenable without the base. pub async fn open( layer: &dyn ObjectStore, frozen: FrozenDirectory, @@ -413,6 +417,28 @@ impl ReadThroughMount { }); } let reserved = prefix.clone().join(RESERVED); + let created = reserved.clone().join(CREATED); + let first_build = match layer.head(&created).await { + Ok(_) => false, + Err(Error::NotFound { .. }) => true, + Err(error) => return Err(error), + }; + if first_build { + match layer.list(Some(&prefix)).try_next().await { + Ok(None) | Err(Error::NotFound { .. }) => {} + Ok(Some(found)) => { + return Err(Error::Generic { + store: "ReadThroughStore", + source: format!( + "the clone root already holds {} but no {RESERVED}/{CREATED}: it is not a clone root, and reading a base through it is not supported", + found.location + ) + .into(), + }); + } + Err(error) => return Err(error), + } + } let deleted = reserved.clone().join(DELETED); let mut markers = layer.list(Some(&deleted)); while let Some(marker) = markers.try_next().await? { @@ -420,13 +446,8 @@ impl ReadThroughMount { frozen.mark_deleted(key.collect()); } } - let created = reserved.clone().join(CREATED); - match layer.head(&created).await { - Ok(_) => {} - Err(Error::NotFound { .. }) => { - layer.put(&created, PutPayload::new()).await?; - } - Err(error) => return Err(error), + if first_build { + layer.put(&created, PutPayload::new()).await?; } Ok(Self { frozen: Arc::new(frozen), @@ -1354,6 +1375,7 @@ mod tests { a_durable_store_keeps_its_whiteouts_out_of_sight, durable_refuses_a_base_that_is_itself_a_clone_root, durable_refuses_a_base_that_holds_an_object_at_the_reserved_name, + durable_refuses_a_layer_that_is_not_a_clone_root, a_clone_root_carries_the_reserved_directory_from_its_first_build, a_stop_between_the_whiteout_and_the_delete_leaves_the_key_deleted_or_untouched, an_update_and_a_delete_of_one_base_object_take_turns, diff --git a/crates/omnigraph-storage/src/read_through_contract.rs b/crates/omnigraph-storage/src/read_through_contract.rs index 524be0a7c..d548b4eb6 100644 --- a/crates/omnigraph-storage/src/read_through_contract.rs +++ b/crates/omnigraph-storage/src/read_through_contract.rs @@ -219,6 +219,47 @@ pub async fn durable_refuses_a_base_that_holds_an_object_at_the_reserved_name( ); } +/// A layer that holds objects under the mount but no `__clone/created` is +/// not a clone root: it is refused before any write, so the refusal leaves +/// it as it was. Objects outside the mount do not count. +pub async fn durable_refuses_a_layer_that_is_not_a_clone_root(fixture: &dyn Fixture) { + let base = fixture.base(&[("a.txt", "base a")]).await; + let layer = fixture.clone_root().await; + layer + .put( + &Path::from("elsewhere/x.txt"), + PutPayload::from_static(b"x"), + ) + .await + .unwrap(); + drop(durable(&layer, &base).await); + assert!(layer.head(&graph("__clone/created")).await.is_ok()); + + let layer = fixture.clone_root().await; + layer + .put( + &graph("_versions/1.manifest"), + PutPayload::from_static(b"m"), + ) + .await + .unwrap(); + let frozen = FrozenDirectory::over(base).await.unwrap(); + let error = ReadThroughStore::durable(Arc::clone(&layer), frozen, Path::from(PREFIX)) + .await + .err() + .unwrap() + .to_string(); + assert!(error.contains("it is not a clone root"), "{error}"); + assert!(error.contains("graph/_versions/1.manifest"), "{error}"); + assert!( + matches!( + layer.head(&graph("__clone/created")).await, + Err(Error::NotFound { .. }) + ), + "the refusal writes no marker" + ); +} + /// A clone root carries `__clone/created` from its first build, a later /// build over it finds the same objects, and it is refused as a base. pub async fn a_clone_root_carries_the_reserved_directory_from_its_first_build( diff --git a/crates/omnigraph/tests/integration/s3_storage.rs b/crates/omnigraph/tests/integration/s3_storage.rs index 892b7a3cd..1b5b9a7e4 100644 --- a/crates/omnigraph/tests/integration/s3_storage.rs +++ b/crates/omnigraph/tests/integration/s3_storage.rs @@ -486,6 +486,7 @@ s3_contract_rows!( a_durable_store_keeps_its_whiteouts_out_of_sight, durable_refuses_a_base_that_is_itself_a_clone_root, durable_refuses_a_base_that_holds_an_object_at_the_reserved_name, + durable_refuses_a_layer_that_is_not_a_clone_root, a_clone_root_carries_the_reserved_directory_from_its_first_build, a_stop_between_the_whiteout_and_the_delete_leaves_the_key_deleted_or_untouched, an_update_and_a_delete_of_one_base_object_take_turns, diff --git a/docs/user/cli/reference.md b/docs/user/cli/reference.md index 7cec5f950..6be57cdf7 100644 --- a/docs/user/cli/reference.md +++ b/docs/user/cli/reference.md @@ -41,6 +41,8 @@ directory or prefix is a new clone; the same target again shows the clone's own state. Nothing in the target records its base, so pass the same `--base` on every open of that target; a clone root opened without `--base` is refused, since its marker says it is a clone and not which base it was cloned from. +A target that already holds objects but no clone marker, an ordinary graph +for example, is refused under `--base` before anything is written. `--as ACTOR` attributes supported direct operations; on a cluster graph the applied graph policy judges them by it ([direct writes](../operations/policy.md#actor-identity)). diff --git a/docs/user/operations/policy.md b/docs/user/operations/policy.md index 424b7e1a6..1034b3679 100644 --- a/docs/user/operations/policy.md +++ b/docs/user/operations/policy.md @@ -263,7 +263,9 @@ graph, the policy `omnigraph access` reports for that target. Every write and maintenance command is then judged by it before any effect, and a missing actor is denied. A standalone graph has no policy. A direct actor is self-declared, so this keeps a storage owner within the policy rather than authenticating them: -storage permissions remain the trust boundary. Only the server resolves a +storage permissions remain the trust boundary. A refused direct write, like +every direct writer, keeps the cluster's admission lock +([S3 cluster roots](s3-cluster-roots.md)). Only the server resolves a served write's actor; there `--as` is an assertion the server checks against the token ([Assert the actor](server.md#assert-the-actor)). diff --git a/docs/user/operations/s3-cluster-roots.md b/docs/user/operations/s3-cluster-roots.md index fa72c79ca..3910c6bfe 100644 --- a/docs/user/operations/s3-cluster-roots.md +++ b/docs/user/operations/s3-cluster-roots.md @@ -11,9 +11,14 @@ address, refuses an inline cloud target. ```bash omnigraph --target s3://bucket/company-brain cluster status --json -omnigraph optimize --target s3://bucket/company-brain --graph knowledge +omnigraph optimize --target s3://bucket/company-brain --graph knowledge --as act-operator ``` +A direct write or maintenance command on a graph with an applied policy is +judged by it, so `--as` names an actor the policy grants the command +(`maintain` for `optimize`, `reclaim` for `cleanup`); see +[direct writes](policy.md#actor-identity). + Every direct writer on a root takes the cluster's admission lock and keeps it after it finishes, as a direct `cluster apply` does. A stopped server's lock blocks the first direct command, and each command's lock blocks the next one