Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .github/workflows/test-cli.yml
Original file line number Diff line number Diff line change
Expand Up @@ -56,9 +56,17 @@ jobs:
- name: Clippy without default features
run: cargo clippy -p clickhousectl --all-targets --no-default-features -- -D warnings

# Clippy only compiles all features; these tests only run with the
# experimental access-negotiation feature enabled.
- name: Clippy with experimental access negotiation
run: cargo clippy -p clickhousectl --all-targets --features experimental-access-negotiation -- -D warnings

- name: Test
run: cargo test -p clickhousectl

- name: Test with experimental access negotiation
run: cargo test -p clickhousectl --features experimental-access-negotiation

# The live tests include the API library's harness by a path outside
# this crate, so the published crate must ship its sources only.
- name: Check packaged files
Expand Down
20 changes: 20 additions & 0 deletions crates/clickhouse-cloud-api/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,26 @@ minor version; read the entries before raising it.

## Unreleased

`organization_assignable_roles_get_list(organization_id)` uses a CLI user Bearer
token to read the complete, unpaginated `ApiResponse<Vec<AssignableRole>>` array
from `/v1/organizations/{organizationId}/roles`. Basic clients fail locally with
`Error::AuthMismatch`; the server verifies the actual CLI user and organization
authority. `organization_roles_get_list` retains its administrative catalog API.
There is no catalog fallback or heuristic choice between the auth-dependent DTOs.
The analyzer allowlists the distinct typed helper for this existing route.

Assignable roles retain identity strings (including non-v4 system UUIDs), role
type, all ALLOW/DENY policies, permission/resource strings and optional tags.
`grants` strings, including REVOKE statements, are opaque; no SQL parsing or
filtering occurs. This menu describes read-time authority, not an approval promise.

Transport DTOs follow the library's all-`Option` compatibility policy: missing or
null required fields remain `None`, distinct from explicit empty arrays. Consumers
**must validate** result, role id/name/type/policies, and each policy's
allowDeny/permissions/resources before human **or JSON** success output. Never
convert absent fields into an empty/safe permission claim. Optional tags and their
fields retain absence; unknown enum strings round-trip losslessly.

Structs with a required field no longer implement `Default`: request bodies
such as `ServicePostRequest`, `ClickPipePostRequest` and
`ClickStackCreateAlertRequest`, their nested required types, the request
Expand Down
34 changes: 34 additions & 0 deletions crates/clickhouse-cloud-api/src/client/rbac.rs
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,40 @@ use crate::meta::operations;
use crate::models::*;

impl Client {
/// Discover the complete, unpaginated caller-assignable role array.
///
/// Requires Bearer authentication; the server verifies the token's CLI user
/// identity and current organization authority. This is a read-time snapshot,
/// not an approval guarantee. Never falls back to the administrative catalog.
///
/// Transport fields tolerate missing/null values. Callers must validate the
/// required discovery fields before human or JSON success output: absent
/// result/policies/permissions/resources are not empty permission guarantees.
pub async fn organization_assignable_roles_get_list(
&self,
organization_id: &str,
) -> Result<ApiResponse<Vec<AssignableRole>>, Error> {
if !matches!(&self.auth, super::Auth::Bearer { .. }) {
return Err(Error::AuthMismatch(
"organization_assignable_roles_get_list requires a CLI user Bearer token".into(),
));
}
let req = self.request(&operations::ORGANIZATION_ROLES_GET_LIST, &[organization_id])?;
let resp = req.send().await?;
let status = resp.status();
let body_text = resp.text().await?;
if !status.is_success() {
return Err(Error::Api {
status: status.as_u16(),
message: serde_json::from_str::<ApiResponse<serde_json::Value>>(&body_text)
.ok()
.and_then(|r| r.error)
.unwrap_or(body_text.clone()),
});
}
Ok(serde_json::from_str(&body_text)?)
}

/// List all available roles for an organization
pub async fn organization_roles_get_list(
&self,
Expand Down
7 changes: 4 additions & 3 deletions crates/clickhouse-cloud-api/src/models.rs
Original file line number Diff line number Diff line change
Expand Up @@ -230,9 +230,10 @@ pub use query_api_endpoints::{
};
pub use quotas::{OrganizationQuota, OrganizationQuotaQuotacode, OrganizationQuotaScope};
pub use rbac::{
RBACPolicy, RBACPolicyAllowdeny, RBACPolicyCreateRequest, RBACPolicyCreateRequestAllowdeny,
RBACPolicyTags, RBACPolicyTagsResponse, RBACPolicyTagsRolev2, RBACRole, RBACRoleType,
RoleCreateRequest, RoleUpdateRequest,
AssignableRole, AssignableRolePolicy, AssignableRolePolicyTags, RBACPolicy,
RBACPolicyAllowdeny, RBACPolicyCreateRequest, RBACPolicyCreateRequestAllowdeny, RBACPolicyTags,
RBACPolicyTagsResponse, RBACPolicyTagsRolev2, RBACRole, RBACRoleType, RoleCreateRequest,
RoleUpdateRequest,
};
pub use saved_queries::{PublicSavedQuery, PublicSavedQueryListItem, PublicSavedQueryRequest};
pub use scim::{
Expand Down
40 changes: 40 additions & 0 deletions crates/clickhouse-cloud-api/src/models/rbac.rs
Original file line number Diff line number Diff line change
Expand Up @@ -161,6 +161,46 @@ pub struct RBACRole {
pub updated_at: Option<chrono::DateTime<chrono::Utc>>,
}

/// A caller-assignable role from verified CLI user discovery, not the administrative catalog.
///
/// Fields remain optional for transport compatibility. Before presenting a successful
/// discovery result, callers must require `id`, `name`, `type`, `policies`, and each
/// policy's effect, permissions and resources. Absence is not an empty permission set.
#[derive(Debug, Clone, PartialEq, Default, Serialize, Deserialize)]
pub struct AssignableRole {
/// Opaque identity string, including system identifiers that are not UUID v4.
#[serde(skip_serializing_if = "Option::is_none")]
pub id: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub name: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub r#type: Option<RBACRoleType>,
#[serde(skip_serializing_if = "Option::is_none")]
pub policies: Option<Vec<AssignableRolePolicy>>,
}

/// A complete policy in an assignable role; no effects or resource scopes are filtered.
#[derive(Debug, Clone, PartialEq, Default, Serialize, Deserialize)]
pub struct AssignableRolePolicy {
#[serde(rename = "allowDeny", skip_serializing_if = "Option::is_none")]
pub allow_deny: Option<RBACPolicyAllowdeny>,
#[serde(skip_serializing_if = "Option::is_none")]
pub permissions: Option<Vec<String>>,
#[serde(skip_serializing_if = "Option::is_none")]
pub resources: Option<Vec<String>>,
#[serde(skip_serializing_if = "Option::is_none")]
pub tags: Option<AssignableRolePolicyTags>,
}

/// Meaningful policy tags. SQL statements are opaque, including GRANT and REVOKE text.
#[derive(Debug, Clone, PartialEq, Default, Serialize, Deserialize)]
pub struct AssignableRolePolicyTags {
#[serde(skip_serializing_if = "Option::is_none")]
pub grants: Option<Vec<String>>,
#[serde(rename = "roleV2", skip_serializing_if = "Option::is_none")]
pub role_v2: Option<RBACPolicyTagsRolev2>,
}

/// `RoleCreateRequest` from the ClickHouse Cloud API.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct RoleCreateRequest {
Expand Down
135 changes: 135 additions & 0 deletions crates/clickhouse-cloud-api/tests/client/organizations.rs
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,141 @@ async fn list_organizations() {
assert_eq!(orgs[0].name.as_deref(), Some("Test Org"));
}

#[tokio::test]
async fn organization_assignable_roles_get_list_preserves_full_policy_array() {
let server = MockServer::start().await;
let roles = serde_json::json!([
{"id": "00000000-0000-0000-0000-000000000001", "name": "System reader", "type": "system", "policies": [
{"allowDeny": "ALLOW", "permissions": ["control-plane:service:view", "future:permission"], "resources": ["*", "instance/service-a"], "tags": {"roleV2": "sql-console-readonly"}},
{"allowDeny": "DENY", "permissions": ["control-plane:service:delete"], "resources": ["instance/service-b"]}
]},
{"id": "55555555-5555-4555-8555-555555555555", "name": "Custom SQL", "type": "custom", "policies": [
{"allowDeny": "ALLOW", "permissions": ["sql-console:database:access"], "resources": ["instance/service-a"], "tags": {"roleV2": "sql-console-admin", "grants": ["GRANT SELECT ON db.* TO role", "REVOKE SELECT ON db.secret FROM role"]}}
]}
]);
Mock::given(method("GET"))
.and(path(
"/v1/organizations/11111111-1111-4111-8111-111111111111/roles",
))
.and(bearer_token("cli-user-token"))
.respond_with(ok_json(roles.clone()))
.expect(1)
.mount(&server)
.await;
let client =
Client::with_http_client_bearer(reqwest::Client::new(), server.uri(), "cli-user-token");
let response = client
.organization_assignable_roles_get_list("11111111-1111-4111-8111-111111111111")
.await
.unwrap();
assert_eq!(response.status, Some(200));
assert_eq!(response.request_id.as_deref(), Some("req-test"));
let result = response.result.unwrap();
assert_eq!(result[0].r#type, Some(RBACRoleType::System));
assert_eq!(result[1].r#type, Some(RBACRoleType::Custom));
assert_eq!(
result[0].policies.as_ref().unwrap()[1].allow_deny,
Some(RBACPolicyAllowdeny::DENY)
);
assert_eq!(serde_json::to_value(result).unwrap(), roles);
let requests = server.received_requests().await.unwrap();
assert_eq!(requests.len(), 1);
assert!(requests[0].url.query().is_none());
assert!(requests[0].body.is_empty());
}

#[tokio::test]
async fn organization_assignable_roles_get_list_rejects_basic_without_catalog_fallback() {
let (server, client) = setup().await;
assert!(matches!(
client.organization_assignable_roles_get_list("org").await,
Err(clickhouse_cloud_api::Error::AuthMismatch(_))
));
assert!(server.received_requests().await.unwrap().is_empty());

// The pre-existing administrative method still uses Basic and its legacy DTO.
Mock::given(method("GET"))
.and(path("/v1/organizations/org/roles"))
.and(basic_auth("key", "secret"))
.respond_with(ok_json(
serde_json::json!([{"id": "role", "actors": ["actor"], "ownerId": "owner"}]),
))
.expect(1)
.mount(&server)
.await;
let response = client.organization_roles_get_list("org").await.unwrap();
let result = response.result.unwrap();
assert_eq!(result[0].actors.as_ref().unwrap(), &["actor"]);
assert_eq!(result[0].owner_id.as_deref(), Some("owner"));
}

#[tokio::test]
async fn organization_assignable_roles_get_list_preserves_errors_and_incomplete_envelopes() {
for (status, body) in [
(401, r#"{"error":"login required"}"#),
(403, r#"{"error":"not authorized"}"#),
(400, r#"{"error":"RBAC v2 required"}"#),
(500, "upstream failure"),
(200, "not-json"),
(200, r#"{"result":{"roles":[]}}"#),
(200, "[]"),
(200, r#"{"result":[{"policies":"wrong-type"}]}"#),
(200, r#"{"error":"envelope error"}"#),
(200, "{}"),
(200, r#"{"result":null}"#),
(200, r#"{"result":[]}"#),
] {
let server = MockServer::start().await;
Mock::given(method("GET"))
.and(path("/v1/organizations/org/roles"))
.and(bearer_token("cli-user-token"))
.respond_with(ResponseTemplate::new(status).set_body_string(body))
.expect(1)
.mount(&server)
.await;
let client =
Client::with_http_client_bearer(reqwest::Client::new(), server.uri(), "cli-user-token");
let response = client.organization_assignable_roles_get_list("org").await;
if status != 200 {
let Err(clickhouse_cloud_api::Error::Api {
status: actual,
message,
}) = response
else {
panic!("expected API error")
};
assert_eq!(actual, status);
let expected = serde_json::from_str::<serde_json::Value>(body)
.ok()
.and_then(|body| body["error"].as_str().map(str::to_owned))
.unwrap_or_else(|| body.into());
assert_eq!(message, expected);
} else if matches!(
body,
"{}" | r#"{"result":null}"# | r#"{"error":"envelope error"}"#
) {
let response = response.unwrap();
assert!(response.result.is_none());
assert_eq!(
response.error.as_deref(),
if body.contains("envelope error") {
Some("envelope error")
} else {
None
}
);
} else if body == r#"{"result":[]}"# {
assert_eq!(response.unwrap().result, Some(vec![]));
} else {
assert!(
matches!(response, Err(clickhouse_cloud_api::Error::Json(_))),
"{body}"
);
}
assert_eq!(server.received_requests().await.unwrap().len(), 1);
}
}

#[tokio::test]
async fn get_organization() {
let mock_server = MockServer::start().await;
Expand Down
88 changes: 88 additions & 0 deletions crates/clickhouse-cloud-api/tests/models/organizations.rs
Original file line number Diff line number Diff line change
Expand Up @@ -514,3 +514,91 @@ fn organization_private_endpoints_patch_new_sends_only_required_fields() {
serde_json::json!({"remove": [{"cloudProvider": "aws", "id": "pe-1", "region": "us-east-1"}]})
);
}

#[test]
fn assignable_role_required_fields_preserve_missing_null_and_empty_distinctions() {
let role = serde_json::json!({"id": "00000000-0000-0000-0000-000000000001", "name": "role", "type": "system", "policies": []});
for field in ["id", "name", "type", "policies"] {
for null in [false, true] {
let mut wire = role.clone();
if null {
wire[field] = serde_json::Value::Null;
} else {
wire.as_object_mut().unwrap().remove(field);
}
let parsed: AssignableRole = serde_json::from_value(wire).unwrap();
match field {
"id" => assert!(parsed.id.is_none()),
"name" => assert!(parsed.name.is_none()),
"type" => assert!(parsed.r#type.is_none()),
"policies" => assert!(parsed.policies.is_none()),
_ => unreachable!(),
}
assert!(serde_json::to_value(parsed).unwrap().get(field).is_none());
}
}
let parsed: AssignableRole = serde_json::from_value(role).unwrap();
assert_eq!(parsed.policies, Some(vec![]));
let policy = serde_json::json!({"allowDeny": "DENY", "permissions": [], "resources": []});
for field in ["allowDeny", "permissions", "resources", "tags"] {
for null in [false, true] {
let mut wire = policy.clone();
if null {
wire[field] = serde_json::Value::Null;
} else {
wire.as_object_mut().unwrap().remove(field);
}
let parsed: AssignableRolePolicy = serde_json::from_value(wire).unwrap();
match field {
"allowDeny" => assert!(parsed.allow_deny.is_none()),
"permissions" => assert!(parsed.permissions.is_none()),
"resources" => assert!(parsed.resources.is_none()),
"tags" => assert!(parsed.tags.is_none()),
_ => unreachable!(),
}
assert!(serde_json::to_value(parsed).unwrap().get(field).is_none());
}
}
let parsed: AssignableRolePolicy = serde_json::from_value(policy).unwrap();
assert_eq!(parsed.permissions, Some(vec![]));
assert_eq!(parsed.resources, Some(vec![]));
for wire in [
serde_json::json!({}),
serde_json::json!({"grants": null, "roleV2": null}),
] {
let parsed: AssignableRolePolicyTags = serde_json::from_value(wire).unwrap();
assert!(parsed.grants.is_none());
assert!(parsed.role_v2.is_none());
assert_eq!(serde_json::to_value(parsed).unwrap(), serde_json::json!({}));
}
let parsed: AssignableRolePolicyTags =
serde_json::from_value(serde_json::json!({"grants": []})).unwrap();
assert_eq!(parsed.grants, Some(vec![]));
}

#[test]
fn assignable_role_preserves_unknown_enum_values_without_legacy_catalog_fields() {
let wire = serde_json::json!({"id": "role", "name": "future", "type": "future-type", "policies": [
{"allowDeny": "future-effect", "permissions": ["future:permission"], "resources": ["future/resource"], "tags": {"roleV2": "future-role", "grants": ["REVOKE ALL ON *.* FROM role"]}}
]});
let mut extra = wire.clone();
extra["actors"] = serde_json::json!(["internal"]);
extra["tenantId"] = "tenant".into();
extra["policies"][0]["id"] = "policy-db-id".into();
extra["policies"][0]["futureField"] = true.into();
let parsed: AssignableRole = serde_json::from_value(extra).unwrap();
assert_eq!(
parsed.r#type,
Some(RBACRoleType::Unknown("future-type".into()))
);
let policy = &parsed.policies.as_ref().unwrap()[0];
assert_eq!(
policy.allow_deny,
Some(RBACPolicyAllowdeny::Unknown("future-effect".into()))
);
assert_eq!(
policy.tags.as_ref().unwrap().role_v2,
Some(RBACPolicyTagsRolev2::Unknown("future-role".into()))
);
assert_eq!(serde_json::to_value(parsed).unwrap(), wire);
}
3 changes: 3 additions & 0 deletions crates/clickhouse-openapi-analyzer/src/config.rs
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,9 @@ pub fn clickhouse_cloud_config() -> AnalyzerConfig {
"run_query",
"run_query_bearer",
"run_postgres_query_bearer",
// Explicit verified-CLI auth lane of organizationRolesGetList; the
// administrative method keeps its legacy RBACRole response contract.
"organization_assignable_roles_get_list",
]),
optionality_exemptions: pairs(OPTIONALITY_EXEMPTIONS),
fractional_response_exemptions: pairs(FRACTIONAL_RESPONSE_EXEMPTIONS),
Expand Down
Loading
Loading