fabi/PiCloud
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(hierarchies): multi-repo single-owner ownership + structural prune (M3)

Browse Source 
§7 of the groups/project-tool design. A group node is now authoritatively
managed by exactly one project-root; `pic apply --dir` claims, conflicts,
takes over, and (with --prune) structurally reaps owned nodes.

- Migration 0052: `projects(id, key UNIQUE)` + promote the inert
  `groups.owner_project` (0047) to a real FK (ON DELETE SET NULL) + index.
- CLI mints a stable, gitignored project key in `.picloud/project.json`
  (`pic init`, or lazily on first tree plan/apply) and presents it on every
  tree request; `pic apply --dir --takeover` flag.
- Server: prepare_tree resolves ownership read-only (plan surfaces conflicts
  + prune candidates; token folds each group's owner key). apply_tree upserts
  the project in-tx, claims created groups on insert, reconciles existing-group
  ownership under the per-node advisory lock (first-commit-wins), and prunes
  owned-but-undeclared groups leaf-first (delete=RESTRICT, never another repo's
  or a UI-owned node).
- Authz (§7.4, ownership ⟂ RBAC): takeover requires GroupAdmin per contested
  node — enforced in authz_tree (pre-tx) AND re-verified in-tx at the ownership
  decision, so --force (which waives the staleness token) can't open a
  takeover-without-admin window. The attacker-supplied project key is
  length/charset-validated server-side.
- Tests: tests/ownership.rs (claim → conflict → takeover → flip; non-admin
  takeover → 403; prune-owned-only); format_conflicts unit test; schema golden
  reblessed. tree_shape M2 journey updated to reparent in-place (a fresh dir is
  now a distinct project and would correctly conflict).

Closes the M3 milestone; reviewed (4 findings: 1 authz-bypass via --force +
key validation + 2 LOW, all fixed). M4 (trigger/route templates) remains.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
MechaCat02
2026-06-26 23:04:53 +02:00
parent c18ce7c2c4
commit 193336a8a6
17 changed files with 1031 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
crates/picloud-cli/Cargo.toml
View File

@@ -34,6 +34,7 @@ toml = "0.8"
directories = "5"
rpassword = "7"
anyhow = "1"
uuid = { version = "1", features = ["v4"] }
[dev-dependencies]
assert_cmd = "2"

49
crates/picloud-cli/src/client.rs
View File

@@ -1242,27 +1242,43 @@ impl Client {
}
/// `POST /api/v1/admin/tree/plan` — diff a whole project tree (Phase 5).
pub async fn plan_tree(&self, bundle: &serde_json::Value) -> Result<TreePlanDto> {
/// `project_key` (§7, M3) lets the server report ownership conflicts and
/// structural-prune candidates for this repo.
pub async fn plan_tree(
&self,
bundle: &serde_json::Value,
project_key: Option<&str>,
) -> Result<TreePlanDto> {
let body = serde_json::json!({
"bundle": bundle,
"project_key": project_key,
});
let resp = self
.request(Method::POST, "/api/v1/admin/tree/plan")
.json(bundle)
.json(&body)
.send()
.await?;
decode(resp).await
}
/// `POST /api/v1/admin/tree/apply` — reconcile a whole project tree in one
/// transaction (Phase 5).
/// transaction (Phase 5). `project_key`/`allow_takeover` drive ownership
/// (§7, M3): the apply claims unclaimed declared groups for this project and
/// refuses (or, with `allow_takeover`, seizes) ones another project owns.
pub async fn apply_tree(
&self,
bundle: &serde_json::Value,
prune: bool,
expected_token: Option<&str>,
project_key: Option<&str>,
allow_takeover: bool,
) -> Result<ApplyReportDto> {
let body = serde_json::json!({
"bundle": bundle,
"prune": prune,
"expected_token": expected_token,
"project_key": project_key,
"allow_takeover": allow_takeover,
});
let resp = self
.request(Method::POST, "/api/v1/admin/tree/apply")
@@ -1270,12 +1286,11 @@ impl Client {
.send()
.await?;
if resp.status() == reqwest::StatusCode::CONFLICT {
// 409 covers both bound-plan staleness AND an ownership conflict; the
// server's message is self-explanatory for each, so surface it raw.
let body = resp.text().await.unwrap_or_default();
let msg = parse_error_body(&body).unwrap_or(body);
return Err(anyhow!(
"{msg}\nThe project tree changed since your last `pic plan`. Re-run \
`pic plan --dir` to review, then `pic apply --dir` — or add `--force`."
));
return Err(anyhow!("{msg}"));
}
decode(resp).await
}
@@ -1365,6 +1380,20 @@ pub struct TreePlanDto {
pub nodes: Vec<NodePlanDto>,
#[serde(default)]
pub state_token: String,
/// Declared groups owned by another project (§7, M3) — surfaced so CI sees
/// the conflict before `apply` refuses it.
#[serde(default)]
pub conflicts: Vec<OwnershipConflictDto>,
/// Slugs of owned groups absent from the manifest — what `--prune` deletes.
#[serde(default)]
pub structural_prunes: Vec<String>,
}
/// A single ownership conflict (`pic plan --dir`).
#[derive(Debug, Deserialize)]
pub struct OwnershipConflictDto {
pub slug: String,
pub owner_key: String,
}
#[derive(Debug, Deserialize)]
@@ -1421,6 +1450,12 @@ pub struct ApplyReportDto {
#[serde(default)]
pub groups_reparented: u32,
#[serde(default)]
pub groups_claimed: u32,
#[serde(default)]
pub groups_taken_over: u32,
#[serde(default)]
pub groups_pruned: u32,
#[serde(default)]
pub warnings: Vec<String>,
}

37
crates/picloud-cli/src/cmds/apply.rs
View File

@@ -118,6 +118,7 @@ pub async fn run_tree(
prune: bool,
yes: bool,
force: bool,
takeover: bool,
env: Option<&str>,
mode: OutputMode,
) -> Result<()> {
@@ -138,8 +139,19 @@ pub async fn run_tree(
.map(|l| l.state_token)
};
// This repo's stable project key (§7, M3): the server claims declared
// groups for it and refuses ones another project owns (unless --takeover).
let project_key = crate::linkstate::ensure_project_key(dir)
.context("establishing project identity in .picloud/")?;
let report = client
.apply_tree(&bundle, prune, expected_token.as_deref())
.apply_tree(
&bundle,
prune,
expected_token.as_deref(),
Some(&project_key),
takeover,
)
.await?;
crate::linkstate::clear_plan(dir, token_key);
@@ -181,14 +193,28 @@ pub async fn run_tree(
),
);
// Structural changes only happen on a tree apply; omit the line otherwise.
if report.groups_created > 0 || report.groups_reparented > 0 {
if report.groups_created > 0
|| report.groups_reparented > 0
|| report.groups_pruned > 0
|| report.groups_claimed > 0
|| report.groups_taken_over > 0
{
block.field(
"groups",
format!(
"+{} reparented {}",
report.groups_created, report.groups_reparented
"+{} reparented {} pruned {}",
report.groups_created, report.groups_reparented, report.groups_pruned
),
);
if report.groups_claimed > 0 || report.groups_taken_over > 0 {
block.field(
"ownership",
format!(
"claimed {} taken-over {}",
report.groups_claimed, report.groups_taken_over
),
);
}
}
for w in &report.warnings {
block.field("warning", w.clone());
@@ -211,7 +237,8 @@ fn confirm_prune(slug: &str) -> Result<()> {
}
eprint!(
"apply --prune will DELETE live scripts/routes/triggers on `{slug}` that are \
absent from the manifest. This cannot be undone. Continue? [y/N] "
absent from the manifest — and, for a tree apply, entire owned groups absent \
from the manifest. This cannot be undone. Continue? [y/N] "
);
std::io::stderr().flush().ok();
let mut answer = String::new();

3
crates/picloud-cli/src/cmds/init.rs
View File

@@ -87,6 +87,9 @@ pub fn run(
}
fs::write(&manifest_path, body).with_context(|| format!("writing {MANIFEST_FILE}"))?;
ensure_gitignored(dir)?;
// Mint the repo's stable project identity (§7, M3) so the first tree apply
// claims its groups under a key that survives clones/CI. Gitignored.
crate::linkstate::ensure_project_key(dir).context("minting project key in .picloud/")?;
let mut block = KvBlock::new();
block

22
crates/picloud-cli/src/cmds/plan.rs
View File

@@ -50,7 +50,10 @@ pub async fn run_tree(dir: &Path, env: Option<&str>, mode: OutputMode) -> Result
let creds = config::resolve()?;
let client = Client::from_creds(&creds)?;
let (bundle, _count) = crate::discover::build_tree(dir, env)?;
let plan = client.plan_tree(&bundle).await?;
// Mint/read this repo's project key so the server can report ownership
// (§7, M3). Best-effort: a read-only dir still plans (ownership unreported).
let project_key = crate::linkstate::ensure_project_key(dir).ok();
let plan = client.plan_tree(&bundle, project_key.as_deref()).await?;
if !plan.state_token.is_empty() {
if let Err(e) = crate::linkstate::write_plan(dir, TREE_TOKEN_KEY, &plan.state_token) {
eprintln!("warning: could not record plan state for `pic apply`: {e}");
@@ -85,6 +88,23 @@ fn render_tree(plan: &TreePlanDto, mode: OutputMode) {
}
}
table.print(mode);
// Ownership diagnostics (§7, M3) — surfaced to stderr in non-JSON output
// (JSON consumers read `conflicts`/`structural_prunes` from the payload).
if mode != OutputMode::Json {
if !plan.conflicts.is_empty() {
eprintln!("\nownership conflicts (apply blocked without --takeover):");
for c in &plan.conflicts {
eprintln!(" - {} is owned by project {}", c.slug, c.owner_key);
}
}
if !plan.structural_prunes.is_empty() {
eprintln!("\ngroups absent from the manifest (deleted only with --prune):");
for slug in &plan.structural_prunes {
eprintln!(" - {slug}");
}
}
}
}
/// Assemble the wire bundle: scripts carry inlined source (read from

53
crates/picloud-cli/src/linkstate.rs
View File

@@ -13,6 +13,59 @@ use serde::{Deserialize, Serialize};
const DIR: &str = ".picloud";
const PLAN_FILE: &str = "plan.json";
const PROJECT_FILE: &str = "project.json";
/// The repo's stable project identity (§7, M3): a random, opaque key minted on
/// first need and persisted (gitignored) in `.picloud/`. It is the server-side
/// ownership handle — the same repo keeps the same project across clones/CI
/// because the key travels in the working tree, never in a committed file.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ProjectLink {
pub key: String,
}
fn project_path(base: &Path) -> PathBuf {
base.join(DIR).join(PROJECT_FILE)
}
/// Read the project key, if one has been minted under `base/.picloud/`.
#[must_use]
pub fn read_project_key(base: &Path) -> Option<String> {
let body = fs::read(project_path(base)).ok()?;
serde_json::from_slice::<ProjectLink>(&body)
.ok()
.map(|l| l.key)
}
/// Read the project key, minting and persisting a fresh one if absent. Used by
/// the tree `plan`/`apply` paths so a repo that never ran `pic init` still gets
/// a stable ownership identity on first use. The new key is a random v4 UUID.
pub fn ensure_project_key(base: &Path) -> Result<String> {
if let Some(k) = read_project_key(base) {
return Ok(k);
}
let key = uuid::Uuid::new_v4().to_string();
write_project_key(base, &key)?;
Ok(key)
}
/// Persist `key` as the project identity, creating `.picloud/` (self-ignored)
/// if needed. Idempotent overwrite — callers usually go through
/// [`ensure_project_key`].
pub fn write_project_key(base: &Path, key: &str) -> Result<()> {
let dir = base.join(DIR);
fs::create_dir_all(&dir).with_context(|| format!("creating {}", dir.display()))?;
let ignore = dir.join(".gitignore");
if !ignore.exists() {
fs::write(&ignore, "*\n").context("writing .picloud/.gitignore")?;
}
let body = serde_json::to_vec_pretty(&ProjectLink {
key: key.to_string(),
})
.context("encoding .picloud/project.json")?;
fs::write(project_path(base), body).context("writing .picloud/project.json")?;
Ok(())
}
/// The recorded result of the last `pic plan`, scoped to the app it was for.
#[derive(Debug, Clone, Serialize, Deserialize)]

5
crates/picloud-cli/src/main.rs
View File

@@ -220,6 +220,10 @@ struct ApplyArgs {
/// since the last `pic plan`).
#[arg(long)]
force: bool,
/// Tree apply only (`--dir`): seize declared groups currently owned by
/// another project (§7). Requires group-admin on each contested node.
#[arg(long, requires = "dir")]
takeover: bool,
/// Merge the `picloud.<env>.toml` overlay (per-env slug + secrets) on
/// top of the base manifest before applying.
#[arg(long)]
@@ -1346,6 +1350,7 @@ async fn main() -> ExitCode {
args.prune,
args.yes,
args.force,
args.takeover,
args.env.as_deref(),
mode,
)

1
crates/picloud-cli/tests/cli.rs
View File

@@ -32,6 +32,7 @@ mod init;
mod invoke;
mod logs;
mod output;
mod ownership;
mod plan;
mod prune;
mod pull;

20
crates/picloud-cli/tests/common/member.rs
View File

@@ -78,6 +78,26 @@ pub fn grant_membership(fx: &Fixture, app_slug: &str, user_id: &str, role: &str)
);
}
/// `POST /api/v1/admin/groups/{slug}/members` — grant `role` on a group.
pub fn grant_group_membership(fx: &Fixture, group_slug: &str, user_id: &str, role: &str) {
let client = reqwest::blocking::Client::new();
let resp = client
.post(format!(
"{}/api/v1/admin/groups/{}/members",
fx.url, group_slug
))
.bearer_auth(&fx.admin_token)
.json(&json!({ "user_id": user_id, "role": role }))
.send()
.expect("grant group membership");
assert!(
resp.status().is_success(),
"grant group membership failed: {} {}",
resp.status(),
resp.text().unwrap_or_default(),
);
}
/// `PATCH /api/v1/admin/apps/{slug}/members/{user_id}` — promote/demote.
pub fn update_membership(fx: &Fixture, app_slug: &str, user_id: &str, role: &str) {
let client = reqwest::blocking::Client::new();

207
crates/picloud-cli/tests/ownership.rs Normal file
View File

@@ -0,0 +1,207 @@
//! M3 multi-repo single-owner ownership (§7) via `pic apply --dir`:
//! * the first repo to apply a group CLAIMS it (its `.picloud/` project key
//! becomes the owner),
//! * a SECOND repo (different project key) applying the same group is
//! REJECTED with an ownership conflict,
//! * `--takeover` lets the second repo seize it (admin-gated; the fixture
//! token is instance owner), flipping ownership — proven by the first repo
//! now being the one rejected,
//! * `--prune` deletes an owned, now-undeclared, empty group; a group owned
//! by another repo is never touched.
//!
//! Each project lives in its own `TempDir`, so `pic` mints a distinct project
//! key per repo (`.picloud/project.json`) — exactly the two-repo topology §7
//! governs.
use std::fs;
use std::path::Path;
use tempfile::TempDir;
use crate::common;
use crate::common::cleanup::GroupGuard;
use crate::common::member;
/// A single-group project dir: group `slug` under `parent`, no scripts (so a
/// structural prune can delete it — a group holding scripts is RESTRICT-pinned).
fn group_dir(slug: &str, parent: &str) -> TempDir {
let dir = TempDir::new().expect("tempdir");
fs::write(
dir.path().join("picloud.toml"),
format!("[group]\nslug = \"{slug}\"\nname = \"Owned Group\"\nparent = \"{parent}\"\n"),
)
.unwrap();
dir
}
fn apply(env: &common::TestEnv, dir: &Path, extra: &[&str]) -> std::process::Output {
let mut cmd = common::pic_as(env);
cmd.args(["apply", "--dir"]).arg(dir).args(extra);
cmd.output().expect("apply --dir")
}
fn ls_groups(env: &common::TestEnv) -> String {
String::from_utf8(
common::pic_as(env)
.args(["groups", "ls"])
.output()
.expect("groups ls")
.stdout,
)
.unwrap()
}
#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
#[test]
fn first_repo_claims_second_is_rejected_then_takeover_flips_ownership() {
let Some(fx) = common::fixture_or_skip() else {
return;
};
let env = common::admin_env(fx);
let slug = common::unique_slug("own-g");
let _g = GroupGuard::new(&env.url, &env.token, &slug);
// Repo A claims the group on first apply (it does not pre-exist → created
// AND claimed for project A in one tx).
let repo_a = group_dir(&slug, "root");
let a1 = apply(&env, repo_a.path(), &[]);
assert!(
a1.status.success(),
"repo A claim apply failed: {}",
String::from_utf8_lossy(&a1.stderr)
);
assert!(
ls_groups(&env).contains(&slug),
"group should exist after claim"
);
// Repo B (a different dir → a different project key) is rejected: the group
// is owned by project A.
let repo_b = group_dir(&slug, "root");
let b1 = apply(&env, repo_b.path(), &[]);
assert!(
!b1.status.success(),
"repo B apply must be rejected (group owned by A)"
);
let b1_err = String::from_utf8_lossy(&b1.stderr).to_lowercase();
assert!(
b1_err.contains("owned by another project") || b1_err.contains("takeover"),
"conflict message should name the ownership clash:\n{b1_err}"
);
// Repo B with --takeover succeeds (the fixture token is instance owner, so
// it holds GroupAdmin on every node) and flips ownership to project B.
let b2 = apply(&env, repo_b.path(), &["--takeover"]);
assert!(
b2.status.success(),
"repo B --takeover should succeed: {}",
String::from_utf8_lossy(&b2.stderr)
);
// Proof the flip took: repo A — formerly the owner — is now the one
// rejected without --takeover.
let a2 = apply(&env, repo_a.path(), &[]);
assert!(
!a2.status.success(),
"after takeover, repo A must now be rejected (B owns the group)"
);
}
#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
#[test]
fn takeover_without_group_admin_is_forbidden() {
// §7.4 — ownership ⟂ RBAC: `--takeover` needs GroupAdmin specifically, a
// second gate beyond the write caps. A non-admin member (editor) of the
// contested group cannot seize it for their repo.
let Some(fx) = common::fixture_or_skip() else {
return;
};
let env = common::admin_env(fx);
let slug = common::unique_slug("own-ta");
let _g = GroupGuard::new(&env.url, &env.token, &slug);
// Admin (repo A) claims the group.
let repo_a = group_dir(&slug, "root");
assert!(
apply(&env, repo_a.path(), &[]).status.success(),
"admin claim apply should succeed"
);
// A member with `editor` (not group_admin) on the group.
let m = member::member_user(fx, &common::unique_username("ta"));
member::grant_group_membership(fx, &slug, &m.id, "editor");
let member_env = common::custom_env(&fx.url, &m.token);
common::seed_credentials(&member_env, &m.username);
// The member's repo B (different project key) attempts a takeover → 403.
let repo_b = group_dir(&slug, "root");
let out = apply(&member_env, repo_b.path(), &["--takeover"]);
assert!(
!out.status.success(),
"non-admin --takeover must be forbidden"
);
let err = String::from_utf8_lossy(&out.stderr).to_lowercase();
assert!(
err.contains("forbidden") || err.contains("403"),
"takeover denial should be an authz error:\n{err}"
);
}
#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
#[test]
fn prune_deletes_owned_undeclared_group_only() {
let Some(fx) = common::fixture_or_skip() else {
return;
};
let env = common::admin_env(fx);
let parent = common::unique_slug("own-par");
let child = common::unique_slug("own-child");
// Drop order: child (registered last → dropped first), then parent.
let _gp = GroupGuard::new(&env.url, &env.token, &parent);
let _gc = GroupGuard::new(&env.url, &env.token, &child);
// Repo declares parent + child (both empty); apply claims both.
let dir = TempDir::new().expect("tempdir");
fs::write(
dir.path().join("picloud.toml"),
format!("[group]\nslug = \"{parent}\"\nname = \"Parent\"\nparent = \"root\"\n"),
)
.unwrap();
fs::create_dir_all(dir.path().join("sub")).unwrap();
fs::write(
dir.path().join("sub/picloud.toml"),
format!("[group]\nslug = \"{child}\"\nname = \"Child\"\nparent = \"{parent}\"\n"),
)
.unwrap();
let out = apply(&env, dir.path(), &[]);
assert!(
out.status.success(),
"initial claim apply failed: {}",
String::from_utf8_lossy(&out.stderr)
);
let groups = ls_groups(&env);
assert!(
groups.contains(&parent) && groups.contains(&child),
"both groups should exist"
);
// Drop the child manifest from the SAME repo (keeping its project key) so
// the child becomes owned-but-undeclared, then apply --prune: the empty
// child is deleted; the parent (still declared) is kept.
fs::remove_dir_all(dir.path().join("sub")).unwrap();
let out2 = apply(&env, dir.path(), &["--prune", "--yes"]);
assert!(
out2.status.success(),
"prune apply failed: {}",
String::from_utf8_lossy(&out2.stderr)
);
let groups = ls_groups(&env);
assert!(
groups.contains(&parent),
"parent must survive prune:\n{groups}"
);
assert!(
!groups.contains(&child),
"owned, undeclared, empty child must be pruned:\n{groups}"
);
}

14
crates/picloud-cli/tests/tree_shape.rs
View File

@@ -83,8 +83,18 @@ fn tree_apply_creates_then_reparents_a_group() {
"re-plan of an applied tree must be a no-op:\n{plan_txt}"
);
// --- Reparent: move the child under the instance root. ---
let dir2 = group_dir(&child, "root");
// --- Reparent: move the child under the instance root. Rewrite the SAME
// repo's manifest (M3: a stable `.picloud/` project key per repo — a fresh
// dir would be a different project and conflict on the owned group). ---
fs::write(
dir.path().join("picloud.toml"),
format!(
"[group]\nslug = \"{child}\"\nname = \"Child Group\"\nparent = \"root\"\n\n\
[[scripts]]\nname = \"hello\"\nfile = \"scripts/hello.rhai\"\n"
),
)
.unwrap();
let dir2 = &dir;
let out = common::pic_as(&env)
.args(["apply", "--dir"])
.arg(dir2.path())