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..073881adb 100644 --- a/crates/omnigraph-cli/src/admission.rs +++ b/crates/omnigraph-cli/src/admission.rs @@ -70,24 +70,50 @@ 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` 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: impl Future>>, + 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?).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 +133,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..f36875acf 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}; @@ -203,8 +203,9 @@ pub(crate) fn parse_set_flags(flags: &[String]) -> Result, @@ -412,15 +413,15 @@ 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, 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. @@ -461,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)], @@ -485,13 +482,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); + 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, @@ -1309,7 +1301,7 @@ impl GraphClient { remote_response_json_bounded(response, token.as_deref(), *response_limit).await } GraphClient::Embedded { - uri, + uri: _, actor, binding, base, @@ -1317,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 @@ -1395,7 +1386,7 @@ impl GraphClient { .await } GraphClient::Embedded { - uri, + uri: _, actor, binding, base, @@ -1405,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( @@ -1520,7 +1510,7 @@ impl GraphClient { Ok(output) } GraphClient::Embedded { - uri, + uri: _, actor, binding, base, @@ -1556,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( @@ -1656,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()) @@ -1743,7 +1727,7 @@ impl GraphClient { .await } GraphClient::Embedded { - uri, + uri: _, actor, binding, base, @@ -1751,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, @@ -1807,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()) @@ -1851,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 @@ -2262,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) @@ -2310,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 { @@ -2386,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) @@ -2572,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 @@ -2827,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/src/commands/maintenance/mod.rs b/crates/omnigraph-cli/src/commands/maintenance/mod.rs index 95bd6891a..c983b96e0 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(), - omnigraph::storage::storage_for_binding(&binding)?, + let db = crate::admission::open_writable( + &binding, + async { Ok(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(), - omnigraph::storage::storage_for_binding(&binding)?, + let db = crate::admission::open_writable( + &binding, + async { Ok(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, + async { Ok(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(), - omnigraph::storage::storage_for_binding(&binding)?, + let db = crate::admission::open_writable( + &binding, + async { Ok(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/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/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..a1a1c8618 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!( @@ -3289,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!( @@ -3300,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 @@ -3441,7 +3458,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 +3556,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 +3728,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_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/integration/cli_data.rs b/crates/omnigraph-cli/tests/integration/cli_data.rs index 71848ecfb..d9cdf5f65 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,223 @@ 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:?}"); + } + } + + // `--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); + 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..233f9e960 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,16 @@ 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 + - id: cluster-operators-reclaim + allow: + actors: { group: cluster_operators } + actions: [reclaim] "#, ) .unwrap(); @@ -1657,9 +1673,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-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/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/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 da0746133..6be57cdf7 100644 --- a/docs/user/cli/reference.md +++ b/docs/user/cli/reference.md @@ -41,8 +41,12 @@ 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. 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..1034b3679 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,17 @@ 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. 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)). Successful graph commits record the actor for the whole atomic change. Inspect the audit trail with: 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 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).