From 85fb1be08914ae82a27da5557d91d05ca286bb40 Mon Sep 17 00:00:00 2001 From: Emanuele De Cupis Date: Thu, 12 Nov 2026 23:43:17 +0100 Subject: [PATCH 1/8] feat(api): add caller-assignable role discovery GET /v1/organizations/{organizationId}/roles answers differently by auth: an API key gets the administrative catalog (RBACRole), a CLI user Bearer token gets the roles that user may assign. Model the second as its own method, organization_assignable_roles_get_list, with AssignableRole, AssignableRolePolicy and AssignableRolePolicyTags. The method refuses Basic clients locally with AuthMismatch instead of falling back to the catalog. Fields stay Option, per the library's compatibility policy, so callers can tell a missing policy list from an empty one. The analyzer allowlists the extra typed helper for the existing route. --- crates/clickhouse-cloud-api/CHANGELOG.md | 20 +++ .../clickhouse-cloud-api/src/client/rbac.rs | 34 +++++ crates/clickhouse-cloud-api/src/models.rs | 7 +- .../clickhouse-cloud-api/src/models/rbac.rs | 40 ++++++ .../tests/client/organizations.rs | 135 ++++++++++++++++++ .../tests/models/organizations.rs | 88 ++++++++++++ .../clickhouse-openapi-analyzer/src/config.rs | 3 + 7 files changed, 324 insertions(+), 3 deletions(-) diff --git a/crates/clickhouse-cloud-api/CHANGELOG.md b/crates/clickhouse-cloud-api/CHANGELOG.md index 7c0bc6d5..b6b17c99 100644 --- a/crates/clickhouse-cloud-api/CHANGELOG.md +++ b/crates/clickhouse-cloud-api/CHANGELOG.md @@ -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>` 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 diff --git a/crates/clickhouse-cloud-api/src/client/rbac.rs b/crates/clickhouse-cloud-api/src/client/rbac.rs index 6f64712d..608de552 100644 --- a/crates/clickhouse-cloud-api/src/client/rbac.rs +++ b/crates/clickhouse-cloud-api/src/client/rbac.rs @@ -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>, 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::>(&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, diff --git a/crates/clickhouse-cloud-api/src/models.rs b/crates/clickhouse-cloud-api/src/models.rs index 10ab30c8..8ce335b1 100644 --- a/crates/clickhouse-cloud-api/src/models.rs +++ b/crates/clickhouse-cloud-api/src/models.rs @@ -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::{ diff --git a/crates/clickhouse-cloud-api/src/models/rbac.rs b/crates/clickhouse-cloud-api/src/models/rbac.rs index 968d7c24..ea261e57 100644 --- a/crates/clickhouse-cloud-api/src/models/rbac.rs +++ b/crates/clickhouse-cloud-api/src/models/rbac.rs @@ -161,6 +161,46 @@ pub struct RBACRole { pub updated_at: Option>, } +/// 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, + #[serde(skip_serializing_if = "Option::is_none")] + pub name: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub r#type: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub policies: Option>, +} + +/// 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, + #[serde(skip_serializing_if = "Option::is_none")] + pub permissions: Option>, + #[serde(skip_serializing_if = "Option::is_none")] + pub resources: Option>, + #[serde(skip_serializing_if = "Option::is_none")] + pub tags: Option, +} + +/// 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>, + #[serde(rename = "roleV2", skip_serializing_if = "Option::is_none")] + pub role_v2: Option, +} + /// `RoleCreateRequest` from the ClickHouse Cloud API. #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] pub struct RoleCreateRequest { diff --git a/crates/clickhouse-cloud-api/tests/client/organizations.rs b/crates/clickhouse-cloud-api/tests/client/organizations.rs index d6e65959..68d9a93c 100644 --- a/crates/clickhouse-cloud-api/tests/client/organizations.rs +++ b/crates/clickhouse-cloud-api/tests/client/organizations.rs @@ -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::(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; diff --git a/crates/clickhouse-cloud-api/tests/models/organizations.rs b/crates/clickhouse-cloud-api/tests/models/organizations.rs index 7bc758f6..33f019c1 100644 --- a/crates/clickhouse-cloud-api/tests/models/organizations.rs +++ b/crates/clickhouse-cloud-api/tests/models/organizations.rs @@ -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); +} diff --git a/crates/clickhouse-openapi-analyzer/src/config.rs b/crates/clickhouse-openapi-analyzer/src/config.rs index 712b4b04..ee0b436d 100644 --- a/crates/clickhouse-openapi-analyzer/src/config.rs +++ b/crates/clickhouse-openapi-analyzer/src/config.rs @@ -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), From 6d52f164e5aa1b485b3e94e33986770a13435290 Mon Sep 17 00:00:00 2001 From: Emanuele De Cupis Date: Thu, 12 Nov 2026 23:45:31 +0100 Subject: [PATCH 2/8] refactor(cloud): prepare CloudClient construction for a second OAuth lane Rename from_resolved to from_resolved_auth and pass the resolved auth straight through. Normalize the saved OAuth API URL in for_oauth_tokens, as every other construction path already does, so a record saved without the /v1 suffix resolves the same base URL. Extract print_client_diagnostics from the --debug block so a command that builds its own client can report the same credential source and API URL. --- crates/clickhousectl/src/cloud/client.rs | 20 ++++++++++++-------- crates/clickhousectl/src/cloud/mod.rs | 8 ++++++-- 2 files changed, 18 insertions(+), 10 deletions(-) diff --git a/crates/clickhousectl/src/cloud/client.rs b/crates/clickhousectl/src/cloud/client.rs index a5488382..6df5cb08 100644 --- a/crates/clickhousectl/src/cloud/client.rs +++ b/crates/clickhousectl/src/cloud/client.rs @@ -800,8 +800,7 @@ impl CloudClient { api_secret: Option<&str>, url_override: Option<&str>, ) -> Result { - let resolved = resolve_auth(api_key, api_secret, url_override)?; - Self::from_resolved(resolved, None) + Self::from_resolved_auth(resolve_auth(api_key, api_secret, url_override)?, None) } /// Like [`CloudClient::new`], but every request gives up after `timeout`, @@ -812,8 +811,10 @@ impl CloudClient { url_override: Option<&str>, timeout: std::time::Duration, ) -> Result { - let resolved = resolve_auth(api_key, api_secret, url_override)?; - Self::from_resolved(resolved, Some(timeout)) + Self::from_resolved_auth( + resolve_auth(api_key, api_secret, url_override)?, + Some(timeout), + ) } /// A client for exactly this API key pair, bypassing the precedence @@ -834,7 +835,7 @@ impl CloudClient { .map(crate::cloud::auth::normalize_api_url) .unwrap_or_else(|| DEFAULT_BASE_URL.to_string()), }; - Self::from_resolved(resolved, Some(timeout)) + Self::from_resolved_auth(resolved, Some(timeout)) } /// A client for exactly these OAuth tokens, bypassing the precedence @@ -849,12 +850,15 @@ impl CloudClient { token: tokens.access_token.clone(), }, source: AuthSource::OAuthTokens, - base_url: tokens.api_url.clone(), + base_url: crate::cloud::auth::normalize_api_url(&tokens.api_url), }; - Self::from_resolved(resolved, Some(timeout)) + Self::from_resolved_auth(resolved, Some(timeout)) } - fn from_resolved(resolved: ResolvedAuth, timeout: Option) -> Result { + fn from_resolved_auth( + resolved: ResolvedAuth, + timeout: Option, + ) -> Result { let mut builder = crate::http::clickhouse_client_builder(); if let Some(timeout) = timeout { builder = builder.timeout(timeout); diff --git a/crates/clickhousectl/src/cloud/mod.rs b/crates/clickhousectl/src/cloud/mod.rs index ef31bd04..1928039d 100644 --- a/crates/clickhousectl/src/cloud/mod.rs +++ b/crates/clickhousectl/src/cloud/mod.rs @@ -124,8 +124,7 @@ pub async fn run(args: CloudArgs, json: bool) -> Result<()> { } if args.debug { - eprintln!("[debug] auth source: {}", client.auth_source().describe()); - eprintln!("[debug] api url: {}", client.base_url()); + print_client_diagnostics(&client); } // OAuth (Bearer) tokens are read-only. Block write commands early @@ -160,6 +159,11 @@ pub async fn run(args: CloudArgs, json: bool) -> Result<()> { .map_err(cloud_error_to_top_level) } +fn print_client_diagnostics(client: &CloudClient) { + eprintln!("[debug] auth source: {}", client.auth_source().describe()); + eprintln!("[debug] api url: {}", client.base_url()); +} + fn cloud_error_to_top_level(e: CloudError) -> Error { match (e.kind, e.details) { // Auth failures own the exit code (4) and have their own remediation From 201f2a2f1c4517865214659fe8d40df23f8d6222 Mon Sep 17 00:00:00 2001 From: Emanuele De Cupis Date: Thu, 12 Nov 2026 23:48:16 +0100 Subject: [PATCH 3/8] feat(cloud): add experimental cloud access for scoped API keys `cloud access` lets an agent get a short-lived, narrowly scoped API key that a human approves in the browser, instead of reusing a long-lived key. It is compiled only with the new `experimental-access-negotiation` feature, so published binaries carry none of it; CI runs clippy and tests with it on. Identity: both subcommands refresh and use the OAuth user login (`CloudClient::for_access`), never an API key, even when one outranks it. The API URL is `--url`, else the one saved with the login. The organization comes from the user's complete membership list: one is picked automatically, otherwise `--org`/`--org-id` or `--org-name`. Selectors are reparsed without clap's global propagation, which would otherwise hide a conflict between values given at different command depths. `cloud access roles` prints the assignable-role menu. Incomplete roles or policies fail before any output instead of implying an empty permission set. `cloud access request` runs the authorization code flow with PKCE (RFC 7636) over a loopback redirect (RFC 8252): 1. bind 127.0.0.1 (or [::1]) and file the request with the redirect URI, S256 challenge, CSRF state and an optional `--perms role:` proposal; 2. print the approval URL to stderr and open the browser; 3. wait for the redirect, which carries the code or `error=access_denied`; the wait is bounded by the server's pending deadline and `--timeout-seconds` (default two minutes), and the request status is never read; 4. exchange code, verifier and redirect URI for the key, and save it to `.clickhouse/credentials.json`. The handshake client never follows redirects, so the code and verifier cannot be replayed to another origin. Server messages are bounded and scrubbed of the code and verifier. Each HTTP operation is capped at 30 seconds. Filing and the exchange are not retried. JSON stdout contains only the final result. Docs live in the authentication reference, under an experimental heading, rather than the README. --- .github/workflows/test-cli.yml | 8 + crates/clickhousectl/Cargo.toml | 7 +- crates/clickhousectl/src/cli.rs | 39 +- crates/clickhousectl/src/cloud/access.rs | 2609 +++++++++++++++++ crates/clickhousectl/src/cloud/cli.rs | 93 + crates/clickhousectl/src/cloud/client.rs | 180 +- crates/clickhousectl/src/cloud/mod.rs | 19 + crates/clickhousectl/src/cloud/permissions.rs | 7 + crates/clickhousectl/src/main.rs | 45 +- crates/clickhousectl/tests/cloud/access.rs | 1400 +++++++++ crates/clickhousectl/tests/cloud/main.rs | 2 + docs/README.md | 2 +- docs/reference/authentication.md | 61 + scripts/classify-install-integration.py | 1 + .../test_classify_install_integration.py | 1 + 15 files changed, 4435 insertions(+), 39 deletions(-) create mode 100644 crates/clickhousectl/src/cloud/access.rs create mode 100644 crates/clickhousectl/tests/cloud/access.rs diff --git a/.github/workflows/test-cli.yml b/.github/workflows/test-cli.yml index 3e73410d..8086d442 100644 --- a/.github/workflows/test-cli.yml +++ b/.github/workflows/test-cli.yml @@ -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 diff --git a/crates/clickhousectl/Cargo.toml b/crates/clickhousectl/Cargo.toml index f066db2a..290f5e49 100644 --- a/crates/clickhousectl/Cargo.toml +++ b/crates/clickhousectl/Cargo.toml @@ -37,9 +37,14 @@ deprecated-fields = ["clickhouse-cloud-api/deprecated-fields"] # pipx owns that install, so `update` points at their upgrade command instead # of replacing the binary. channel-pip = [] +# Compiles in the experimental `cloud access` flow (assignable-role discovery +# and the scoped-API-key PKCE approval handshake). Off by default so the +# published binary carries none of it; opt in locally with +# `--features experimental-access-negotiation`. +experimental-access-negotiation = [] [dependencies] -clap = { version = "4", features = ["derive"] } +clap = { version = "4", features = ["derive", "env"] } tokio = { version = "1", features = ["full"] } reqwest = { version = "0.13", default-features = false, features = ["stream", "json", "rustls"] } serde = { version = "1", features = ["derive"] } diff --git a/crates/clickhousectl/src/cli.rs b/crates/clickhousectl/src/cli.rs index 73d91d45..c3969738 100644 --- a/crates/clickhousectl/src/cli.rs +++ b/crates/clickhousectl/src/cli.rs @@ -518,25 +518,26 @@ mod tests { assert_eq!(visible_subcommands(&root), top); let cloud = root.find_subcommand("cloud").unwrap(); - assert_eq!( - visible_subcommands(cloud), - [ - "auth", - "org", - "service", - "postgres", - "query-api-endpoint", - "saved-query", - "backup", - "clickpipe", - "clickstack", - "udf", - "key", - "member", - "invitation", - "activity", - ] - ); + let mut cloud_top = vec![ + "auth", + "org", + "service", + "postgres", + "query-api-endpoint", + "saved-query", + "backup", + "clickpipe", + "clickstack", + "udf", + "key", + "member", + "invitation", + "activity", + ]; + if cfg!(feature = "experimental-access-negotiation") { + cloud_top.insert(1, "access"); + } + assert_eq!(visible_subcommands(cloud), cloud_top); let local = root.find_subcommand("local").unwrap(); assert_eq!( diff --git a/crates/clickhousectl/src/cloud/access.rs b/crates/clickhousectl/src/cloud/access.rs new file mode 100644 index 00000000..2168415d --- /dev/null +++ b/crates/clickhousectl/src/cloud/access.rs @@ -0,0 +1,2609 @@ +//! `cloud access`: discover assignable roles and obtain scoped API keys. +//! Role discovery uses the typed API client; requests use the PKCE handshake. +//! +//! The user authenticates with their existing CLI identity (OAuth Bearer from +//! `cloud auth login`) and runs the OAuth-style authorization code flow with +//! PKCE (RFC 6749, RFC 7636): +//! 1. file the request (`POST /accessRequests/authorizationCode`) with a PKCE +//! challenge, a CSRF `state` and a loopback `redirectUri`; +//! 2. a human approves it in a browser, which redirects to the loopback +//! listener with the one-time `code` and the `state` (or `error` on +//! denial); the wait is bounded only by the pending deadline, and the +//! request status is never read; +//! 3. exchange the code with the PKCE verifier and the same `redirectUri` +//! (`POST /accessRequests/authorizationCode/token`) for the key. +//! +//! The issued key id and secret are stored with the CLI's existing credential +//! storage; the secret is never printed or placed in a URL. +//! +//! The handshake endpoints are not modelled by the typed `clickhouse-cloud-api` client, +//! so the handshake calls them directly with a plain `reqwest` client carrying +//! the credentials resolved by [`CloudClient`] ([`CloudClient::request_auth`]). + +use crate::cloud::client::{CloudClient, CloudError, RequestAuth, Result as CloudResult}; +use crate::cloud::credentials; +use crate::cloud::permissions::Declaration as Permission; + +// Access negotiation runs on the user's OAuth (Bearer) identity, not an API +// key, and reaches lanes the typed client does not model as metered +// operations: `access roles` reads the verified-CLI assignable-role lane and +// `access request` runs the PKCE handshake. Declared as authorization, not API +// operations, and unscoped because org selection is resolved from the user's +// own memberships rather than the `--org-id`/organization-list API path. +pub(super) const PERMISSIONS: &[Permission] = &[ + Permission::non_api( + "access roles", + "Requires OAuth user identity (`cloud auth login`); reads the verified-CLI assignable-role lane.", + ) + .unscoped(), + Permission::non_api( + "access request", + "Requires OAuth user identity (`cloud auth login`); runs the browser PKCE approval handshake.", + ) + .unscoped(), +]; +use base64::Engine; +use base64::engine::general_purpose::URL_SAFE_NO_PAD; +use clap::{Args, Subcommand}; +use clickhouse_cloud_api::models::{AssignableRole, RBACPolicyAllowdeny, RBACRoleType}; +use serde::Serialize; +use serde::de::DeserializeOwned; +use sha2::{Digest, Sha256}; +use std::collections::{HashMap, HashSet}; +use std::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr}; +use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH}; +use tabled::{Table, Tabled, settings::Style}; +use tokio::io::{AsyncReadExt, AsyncWriteExt}; +use tokio::net::TcpListener; + +/// How long to wait for a human to approve the request before giving up. +const APPROVAL_TIMEOUT: Duration = Duration::from_secs(2 * 60); + +/// The access-operation bound: every single access HTTP request — discovery +/// through the typed client, and each handshake step — must give up after +/// this long so a server holding a response open cannot stall the command. +pub(super) const OPERATION_TIMEOUT: Duration = Duration::from_secs(30); +/// The code exchange is a single attempt bounded like any access request. +#[cfg(not(test))] +const EXCHANGE_TIMEOUT: Duration = OPERATION_TIMEOUT; +/// Unit tests exercise the exchange timeout without waiting the full bound. +#[cfg(test)] +const EXCHANGE_TIMEOUT: Duration = Duration::from_millis(500); +const MAX_EPOCH_MILLIS: i64 = 8_640_000_000_000_000; + +const MAX_PURPOSE_CHARS: usize = 200; +const MAX_KEY_NAME_CHARS: usize = 100; + +#[derive(Subcommand)] +pub enum AccessCommands { + /// List caller-assignable roles with policy scopes + #[command(after_help = "\ +CONTEXT FOR AGENTS: + Returns current assignable roles, not a guarantee of later approval. + JSON output is the complete role array, including all policies and tags.")] + Roles, + /// Request a scoped API key via browser approval + #[command(after_help = "\ +CONTEXT FOR AGENTS: + Requires OAuth from `cloud auth login`, even with a saved API key; roles are per organization: pass --org-id. + Each command's `--help` declares `API key permission:` needs; take conditionals only if their condition holds. + `Authorization:` needs have no granting role. + `cloud access roles --json` lists roles (empty: stop); policies `ALLOW`/`DENY` permissions on `*` or named resources. + Choose roles covering every need with `ALLOW`, none denied by chosen roles, and the fewest extras. + Propose with `--perms` and `--purpose`; a human approves the stderr URL before the timeout; check `grantedRoleIds`. + The approved key becomes the active credential; changing permissions means a new flow (API keys cannot read roles).")] + Request(AccessRequestArgs), +} + +impl AccessCommands { + /// The access-request flow authenticates as the user to *request* access; + /// OAuth (read-only) identity is the intended credential, so it is not a + /// write command and must not be blocked by the OAuth write gate. + pub fn is_write(&self) -> bool { + match self { + AccessCommands::Request(_) | AccessCommands::Roles => false, + } + } +} + +#[derive(Args)] +pub struct AccessRequestArgs { + /// Maximum approval wait in seconds (server expiry may be sooner) + #[arg( + long, + env = "CLICKHOUSE_CLOUD_ACCESS_TIMEOUT_SECONDS", + default_value_t = APPROVAL_TIMEOUT.as_secs() as u32, + value_parser = clap::value_parser!(u32).range(1..) + )] + pub timeout_seconds: u32, + + /// Proposed role: tokens, comma-separated or repeated (max 100) + #[arg(long, value_name = "role:UUID", value_delimiter = ',', value_parser = parse_requested_role)] + pub perms: Vec, + + /// Name to give the issued API key (1-100 characters) + #[arg(long)] + pub key_name: Option, + + /// Purpose shown to the approver (1-200 characters) + #[arg(long)] + pub purpose: Option, +} + +// Keep the token grammar narrower than Uuid::parse_str (which also accepts +// compact, braced and URN representations). UUID version is unrestricted. +fn parse_requested_role(token: &str) -> Result { + let id = token.strip_prefix("role:").ok_or("expected role:")?; + let parsed = uuid::Uuid::parse_str(id).map_err(|_| "expected role:")?; + if !id.eq_ignore_ascii_case(&parsed.hyphenated().to_string()) { + return Err("expected role: without whitespace"); + } + Ok(parsed) +} + +impl AccessRequestArgs { + /// Input the server would reject, found before OAuth or any request. + pub fn validate(&self) -> Result<(), &'static str> { + let within = |value: &Option, max: usize| { + value + .as_deref() + .is_none_or(|value| (1..=max).contains(&value.chars().count())) + }; + if !within(&self.purpose, MAX_PURPOSE_CHARS) { + return Err("--purpose must be 1 to 200 characters"); + } + if !within(&self.key_name, MAX_KEY_NAME_CHARS) { + return Err("--key-name must be 1 to 100 characters"); + } + Ok(()) + } + + pub fn requested_role_ids(&self) -> Result>, &'static str> { + if self.perms.is_empty() { + return Ok(None); + } + let mut seen = HashSet::new(); + let ids: Vec<_> = self + .perms + .iter() + .filter(|id| seen.insert(**id)) + .map(|id| id.hyphenated().to_string()) + .collect(); + if ids.len() > 100 { + return Err("--perms accepts at most 100 distinct roles"); + } + Ok(Some(ids)) + } +} + +// ── request/response bodies ──────────────────────────────────────────────── + +/// The filing body. The server rejects unknown fields, so this carries no +/// `flow` or `agent`. +#[derive(Serialize)] +#[serde(rename_all = "camelCase")] +struct CreateAccessRequestBody<'a> { + redirect_uri: &'a str, + state: &'a str, + code_challenge: &'a str, + code_challenge_method: &'a str, + #[serde(skip_serializing_if = "Option::is_none")] + requested_role_ids: Option<&'a [String]>, + #[serde(skip_serializing_if = "Option::is_none")] + key_name: Option<&'a str>, + #[serde(skip_serializing_if = "Option::is_none")] + purpose: Option<&'a str>, +} + +/// Every `/v1` response from the openapi app wraps its payload as +/// `{ "result": , "requestId": }`; the handshake reads +/// `result` and ignores the correlation id. +#[derive(serde::Deserialize)] +struct Envelope { + result: T, + error: Option, + status: Option, +} + +#[derive(serde::Deserialize)] +#[serde(rename_all = "camelCase")] +struct CreateAccessRequestResponse { + requested_role_ids: Option>, + request_id: String, + status: Option, + approval_url: String, + /// Pending approval deadline only, in epoch milliseconds. + expires_at: Option, +} + +#[derive(Serialize)] +#[serde(rename_all = "camelCase")] +struct TokenBody<'a> { + code: &'a str, + code_verifier: &'a str, + redirect_uri: &'a str, +} + +#[derive(serde::Deserialize)] +#[serde(rename_all = "camelCase")] +struct TokenResponse { + granted_role_ids: Option>, + key_id: String, + key: String, + secret: String, + /// When the key stops working, in epoch milliseconds. + key_expires_at: Option, +} + +// Server arrays are authoritative: reject duplicate identities rather than silently +// deduplicating them as we do for user proposal input. Never echo invalid values. +fn canonical_role_ids(ids: Option<&[String]>, proposal: bool) -> CloudResult> { + let field = if proposal { + "requestedRoleIds" + } else { + "grantedRoleIds" + }; + let invalid = || { + CloudError::new(format!( + "access request: missing or invalid {field}; server role reporting support is required" + )) + }; + let ids = ids.ok_or_else(invalid)?; + if (proposal && ids.len() > 100) || (!proposal && ids.is_empty()) { + return Err(invalid()); + } + let mut seen = HashSet::new(); + ids.iter() + .map(|id| { + let parsed = uuid::Uuid::parse_str(id).map_err(|_| invalid())?; + let canonical = parsed.hyphenated().to_string(); + if !id.eq_ignore_ascii_case(&canonical) || !seen.insert(parsed) { + return Err(invalid()); + } + Ok(canonical) + }) + .collect() +} + +// ── PKCE ─────────────────────────────────────────────────────────────────── + +struct Pkce { + verifier: String, + challenge: String, +} + +/// PKCE pair (RFC 7636): a random 32-byte verifier, base64url-encoded, and its +/// S256 challenge `base64url(SHA256(verifier))`. +fn generate_pkce() -> Pkce { + let verifier = URL_SAFE_NO_PAD.encode(random_bytes::<32>()); + let challenge = s256_challenge(&verifier); + Pkce { + verifier, + challenge, + } +} + +fn s256_challenge(verifier: &str) -> String { + URL_SAFE_NO_PAD.encode(Sha256::digest(verifier.as_bytes())) +} + +/// A random, URL-safe CSRF nonce tying the filed request to its redirect. +fn generate_state() -> String { + URL_SAFE_NO_PAD.encode(random_bytes::<16>()) +} + +fn random_bytes() -> [u8; N] { + use rand::Rng; + let mut bytes = [0u8; N]; + rand::rng().fill_bytes(&mut bytes); + bytes +} + +// ── entry point ───────────────────────────────────────────────────────────── + +impl CloudClient { + async fn list_assignable_roles(&self, org_id: &str) -> CloudResult> { + let response = self + .api() + .organization_assignable_roles_get_list(org_id) + .await + .map_err(|error| self.convert_error_for_organization(error, org_id))?; + if let Some(error) = &response.error { + return Err(CloudError::new(format!("Role discovery failed: {error}"))); + } + if let Some(status) = response.status.filter(|status| *status >= 400) { + return Err(CloudError::new(format!( + "Role discovery failed with envelope status {status}" + ))); + } + let roles = Self::unwrap_response(response)?; + validate_assignable_roles(&roles)?; + Ok(roles) + } + + /// Read all user memberships before auto-selection or exact-name selection. + async fn resolve_access_organization_id( + &self, + org_id: Option, + org_name: Option, + ) -> CloudResult { + if org_id.is_some() && org_name.is_some() { + return Err(CloudError::usage( + "Organization ID conflicts with --org-name", + )); + } + if let Some(id) = org_id { + return Ok(id); + } + let mut organizations = Vec::new(); + let mut cursor = None; + let mut seen_cursors = std::collections::HashSet::new(); + let mut seen_ids = std::collections::HashSet::new(); + loop { + let response = self + .api() + .organization_get_list(None, cursor.as_deref()) + .await + .map_err(|error| self.convert_error(error))?; + let next_cursor = response.next_cursor.clone(); + let page = Self::unwrap_response(response)?; + let had_rows = !page.is_empty(); + let previous_count = organizations.len(); + for organization in page { + let id = organization.id.ok_or_else(|| CloudError::new( + "Organization response is missing its id; cannot safely select an organization", + ))?; + if seen_ids.insert(id) { + organizations.push((id, organization)); + } + } + match next_cursor { + None => break, + Some(next) => { + if (had_rows && previous_count == organizations.len()) + || !seen_cursors.insert(next.clone()) + { + return Err(CloudError::new( + "Organization pagination made no progress; cannot safely select an organization", + )); + } + cursor = Some(next); + } + } + } + if let Some(name) = org_name { + // Names may collide, and an organization has no positional ID: + // only --org-id can choose one (#1200). + return crate::cloud::shared::select_named_id_or( + crate::cloud::client::ResourceKind::Organization, + crate::cloud::client::Scope::Account, + &name, + organizations + .iter() + .map(|(id, org)| (org.name.as_deref(), Some(id))), + |ids| format!("choose one with --org-id : {}", ids.join(", ")), + ); + } + match organizations.as_slice() { + [] => Err(CloudError::new( + "Your OAuth user has no organizations. Join or create an organization, then run `clickhousectl cloud org list --json`.", + )), + [(id, _)] => Ok(id.to_string()), + _ => Err(CloudError::new( + "Your OAuth user belongs to multiple organizations. Run `clickhousectl cloud org list --json` and select an ID with --org (or --org-id).", + )), + } + } +} + +pub async fn run( + command: AccessCommands, + url_override: Option<&str>, + org_id: Option, + org_name: Option, + debug: bool, + json: bool, +) -> CloudResult<()> { + match command { + AccessCommands::Request(args) => { + request(args, url_override, org_id, org_name, debug, json).await + } + AccessCommands::Roles => roles(url_override, org_id, org_name, debug, json).await, + } +} + +/// Validate the entire menu before either output mode can claim success. +fn validate_assignable_roles(roles: &[AssignableRole]) -> CloudResult<()> { + fn required(value: &Option, field: &str) -> CloudResult<()> { + if value.is_none() { + return Err(CloudError::new(format!( + "Incomplete role discovery response: missing {field}" + ))); + } + Ok(()) + } + for role in roles { + required(&role.id, "role.id")?; + if let Some(id) = &role.id { + uuid::Uuid::parse_str(id).map_err(|_| { + CloudError::new("Invalid role discovery response: role.id is not a UUID") + })?; + } + required(&role.name, "role.name")?; + required(&role.r#type, "role.type")?; + required(&role.policies, "role.policies")?; + if let Some(policies) = &role.policies { + for policy in policies { + required(&policy.allow_deny, "policy.allowDeny")?; + required(&policy.permissions, "policy.permissions")?; + required(&policy.resources, "policy.resources")?; + } + } + } + Ok(()) +} + +async fn roles( + url_override: Option<&str>, + org_id: Option, + org_name: Option, + debug: bool, + json: bool, +) -> CloudResult<()> { + let client = CloudClient::for_access(url_override).await?; + if debug { + super::print_client_diagnostics(&client); + } + let org_id = client + .resolve_access_organization_id(org_id, org_name) + .await?; + let roles = client.list_assignable_roles(&org_id).await?; + if json { + println!("{}", serde_json::to_string_pretty(&roles)?); + } else { + print_assignable_roles(&org_id, &roles); + } + Ok(()) +} + +fn print_assignable_roles(org_id: &str, roles: &[AssignableRole]) { + use crate::cloud::output::or_absent; + #[derive(Tabled)] + struct RoleRow { + id: String, + name: String, + r#type: String, + policies: String, + } + let rows = roles + .iter() + .map(|role| { + let role_type = match &role.r#type { + Some(RBACRoleType::Unknown(value)) => format!("Unknown ({value})"), + other => or_absent(other.as_ref()).to_string(), + }; + let mut summaries = Vec::new(); + if let Some(policies) = &role.policies { + if policies.is_empty() { + summaries.push("No policies".into()); + } + for policy in policies { + let effect = match &policy.allow_deny { + Some(RBACPolicyAllowdeny::Unknown(value)) => { + format!("Unknown effect ({value})") + } + other => or_absent(other.as_ref()).to_string(), + }; + if let (Some(permissions), Some(resources)) = + (&policy.permissions, &policy.resources) + { + summaries.push(format!( + "{effect}: permissions [{}]; resources [{}]", + permissions.join(", "), + resources.join(", ") + )); + } + } + } + RoleRow { + id: or_absent(role.id.as_ref()).to_string(), + name: or_absent(role.name.as_ref()).to_string(), + r#type: role_type, + policies: summaries.join("\n"), + } + }) + .collect::>(); + println!("Organization: {org_id}"); + if rows.is_empty() { + println!("No assignable roles for your user in this organization."); + } else { + println!("{}", Table::new(rows).with(Style::markdown())); + } +} + +/// The client for filing and the code exchange: like +/// `oauth_client()` in `auth.rs`, it never follows redirects. A 307/308 from +/// the token endpoint would replay the JSON body — the one-time `code` and +/// the secret PKCE `codeVerifier` — to another origin, and dropping the +/// `Authorization` header on cross-origin redirects does not protect those +/// body fields. Reject redirects instead of forwarding secrets or replaying +/// the exchange POST. +fn handshake_client() -> CloudResult { + crate::http::client_builder() + .redirect(reqwest::redirect::Policy::none()) + .build() + .map_err(|error| CloudError::new(format!("failed to build HTTP client: {error}"))) +} + +async fn request( + args: AccessRequestArgs, + url_override: Option<&str>, + org_id: Option, + org_name: Option, + debug: bool, + json: bool, +) -> CloudResult<()> { + args.validate().map_err(CloudError::usage)?; + let requested_role_ids = args.requested_role_ids().map_err(CloudError::usage)?; + // Resolve the user identity and endpoint once for organization discovery + // and every step of the PKCE handshake. + let client = CloudClient::for_access(url_override).await?; + if debug { + super::print_client_diagnostics(&client); + } + let org_id = client + .resolve_access_organization_id(org_id, org_name) + .await?; + let auth = client.request_auth(); + let base_url = client.base_url().to_string(); + + let http = handshake_client()?; + + // The redirect URI is part of the filing, so the listener comes first. + let Loopback { + listener, + redirect_uri, + state, + } = bind_loopback(TcpListener::bind).await?; + + let pkce = generate_pkce(); + + let access_url = format!("{base_url}/organizations/{org_id}/accessRequests"); + let create_body = CreateAccessRequestBody { + redirect_uri: &redirect_uri, + state: &state, + code_challenge: &pkce.challenge, + code_challenge_method: "S256", + requested_role_ids: requested_role_ids.as_deref(), + key_name: args.key_name.as_deref(), + purpose: args.purpose.as_deref(), + }; + let created: CreateAccessRequestResponse = operation( + OPERATION_TIMEOUT, + send_json( + http.post(format!("{access_url}/authorizationCode")), + &auth, + &create_body, + "file access request", + &[&state], + AUTH_STATUSES, + ), + ) + .await + .map_err(|error| { + error.into_cloud("file access request timed out; the request may have been filed") + })?; + let approval_timeout = Duration::from_secs(u64::from(args.timeout_seconds)); + let pending = PendingApproval::with_timeout(&created, approval_timeout)?; + if pending.requested_role_ids.as_slice() != requested_role_ids.as_deref().unwrap_or_default() { + return Err(CloudError::new( + "file access request: saved proposal differs from submitted proposal", + )); + } + let saved_requested_role_ids = pending.requested_role_ids.clone(); + + approval_handoff(&created.approval_url, |url| open::that(url)); + eprintln!( + "Waiting for approval (up to {} seconds; server expiry may be sooner)...", + args.timeout_seconds + ); + + let code = wait_for_redirect(pending, listener, &state).await?; + let token_url = format!("{access_url}/authorizationCode/token"); + let issued = exchange_code( + &http, + &token_url, + &auth, + &code, + &pkce.verifier, + &redirect_uri, + ) + .await?; + + if issued.key_id.is_empty() || issued.key.is_empty() || issued.secret.is_empty() { + return Err(CloudError::new( + "exchange authorization code: incomplete response", + )); + } + + let granted_role_ids = canonical_role_ids(issued.granted_role_ids.as_deref(), false)?; + let key_expires = key_expiry(issued.key_expires_at)?; + let credentials_path = credentials::credentials_path()?.display().to_string(); + // Prepare the complete output before the only credential write. Actual roles + // come only from the successful exchange, never from the proposal or status GET. + let json_result = if json { + Some(serde_json::to_string_pretty(&serde_json::json!({ + "status": "approved", + "keyId": issued.key_id, + "key": issued.key, + "keyExpiresAt": issued.key_expires_at, + "credentialsPath": credentials_path, + "requestId": created.request_id, + "organizationId": org_id, + "requestedRoleIds": saved_requested_role_ids, + "grantedRoleIds": granted_role_ids, + }))?) + } else { + None + }; + + // Never print the secret; store it with the CLI's existing credential file. + credentials::set_api_credentials(issued.key.clone(), issued.secret, &base_url)?; + + if let Some(out) = json_result { + println!("{out}"); + } else { + println!("Access approved. Scoped API key stored."); + println!(" Organization: {org_id}"); + println!(" Request ID: {}", created.request_id); + if saved_requested_role_ids.is_empty() { + println!(" Requested roles: none (manual selection)"); + } else { + println!(" Requested roles: {}", saved_requested_role_ids.join(", ")); + } + println!(" Granted roles: {}", granted_role_ids.join(", ")); + println!(" Key ID: {}", issued.key_id); + if let Some(expires) = key_expires { + println!(" Key expires: {expires}"); + } + println!(" Saved to: {credentials_path}"); + } + + Ok(()) +} + +/// The key's expiry as RFC 3339 UTC, for human output. A value outside the +/// epoch domain is an error, so it is found before the credential write. +fn key_expiry(value: Option) -> CloudResult> { + value + .map(|millis| { + Some(millis) + .filter(|millis| (1..=MAX_EPOCH_MILLIS).contains(millis)) + .and_then(chrono::DateTime::::from_timestamp_millis) + .map(|time| time.to_rfc3339_opts(chrono::SecondsFormat::Secs, true)) + .ok_or_else(|| CloudError::new("exchange authorization code: invalid keyExpiresAt")) + }) + .transpose() +} + +/// The loopback listener the browser redirects to, and the values filed with +/// it. `state` is a secret: never print it. +struct Loopback { + listener: TcpListener, + redirect_uri: String, + state: String, +} + +/// Bind an ephemeral loopback port: IPv4 first, then IPv6. The server accepts +/// only these IP literals in `redirectUri`, never `localhost`. There is no +/// other flow to fall back to, so failing both is an error. +async fn bind_loopback(bind: F) -> CloudResult +where + F: Fn(SocketAddr) -> Fut, + Fut: std::future::Future>, +{ + for ip in [ + IpAddr::V4(Ipv4Addr::LOCALHOST), + IpAddr::V6(Ipv6Addr::LOCALHOST), + ] { + let Ok(listener) = bind(SocketAddr::new(ip, 0)).await else { + continue; + }; + let Ok(address) = listener.local_addr() else { + continue; + }; + // `SocketAddr` brackets IPv6: `http://[::1]:port/callback`. + return Ok(Loopback { + listener, + redirect_uri: format!("http://{address}/callback"), + state: generate_state(), + }); + } + Err(CloudError::new( + "could not start a local redirect listener on 127.0.0.1 or [::1]", + )) +} + +fn approval_handoff(approval_url: &str, open_browser: impl FnOnce(&str) -> std::io::Result<()>) { + eprintln!("Approve this access request in your browser:\n {approval_url}"); + if open_browser(approval_url).is_err() { + eprintln!( + "Could not open a browser automatically. Open the URL above in a browser on this machine." + ); + } +} + +fn authorized(builder: reqwest::RequestBuilder, auth: &RequestAuth) -> reqwest::RequestBuilder { + match auth { + RequestAuth::Basic { key, secret } => builder.basic_auth(key, Some(secret)), + RequestAuth::Bearer { token } => builder.bearer_auth(token), + } +} + +/// HTTP statuses that mean the user's identity was refused (exit 4). A 403 is +/// not one: a missing permission or RBAC prerequisite is a refusal that logging +/// in again cannot fix, so it is a generic failure (exit 1), as elsewhere. +const AUTH_STATUSES: &[u16] = &[401]; + +async fn send_json( + builder: reqwest::RequestBuilder, + auth: &RequestAuth, + body: &impl Serialize, + action: &str, + secrets: &[&str], + auth_statuses: &[u16], +) -> CloudResult { + let response = authorized(builder, auth) + .json(body) + .send() + .await + .map_err(|error| CloudError::new(format!("{action}: {}", error.without_url())))?; + parse_response(response, action, secrets, auth_statuses).await +} + +/// The longest server error message shown, in characters. +const MAX_SERVER_ERROR_CHARS: usize = 300; + +/// The server's `error` string from a failure body, safe to show: values the +/// call carried in `secrets` are redacted (validator messages quote values), +/// control characters are dropped, and the length is capped. Anything other +/// than a JSON object with a string `error` yields nothing, so raw bodies are +/// never echoed. +fn server_error_message(bytes: &[u8], secrets: &[&str]) -> Option { + let body: serde_json::Value = serde_json::from_slice(bytes).ok()?; + let mut message = body.get("error")?.as_str()?.to_string(); + for secret in secrets.iter().filter(|secret| !secret.is_empty()) { + message = message.replace(secret, "[redacted]"); + } + let message: String = message + .chars() + .filter(|c| !c.is_control()) + .take(MAX_SERVER_ERROR_CHARS) + .collect(); + let message = message.trim(); + (!message.is_empty()).then(|| message.to_string()) +} + +async fn parse_response( + response: reqwest::Response, + action: &str, + secrets: &[&str], + auth_statuses: &[u16], +) -> CloudResult { + let status = response.status(); + let bytes = response + .bytes() + .await + .map_err(|error| CloudError::new(format!("{action}: {}", error.without_url())))?; + if !status.is_success() { + let message = match server_error_message(&bytes, secrets) { + Some(error) => format!("{action} failed ({status}): {error}"), + None => format!("{action} failed ({status})"), + }; + return Err(if auth_statuses.contains(&status.as_u16()) { + CloudError::auth(message) + } else { + CloudError::new(message) + }); + } + // Deserializer diagnostics can quote a secret-bearing unexpected value. + let envelope: Envelope = serde_json::from_slice(&bytes) + .map_err(|_| CloudError::new(format!("{action}: invalid response")))?; + if envelope.error.is_some() || envelope.status.is_some_and(|status| status >= 400) { + return Err(CloudError::new(format!( + "{action}: invalid response envelope" + ))); + } + Ok(envelope.result) +} + +// ── loopback redirect server ──────────────────────────────────────────────── + +/// Connections the loopback listener serves at once. Browsers open +/// speculative connections they may never use, so one idle connection must not +/// hold up the callback; past this many, accepting pauses until one finishes. +const MAX_CALLBACK_CONNECTIONS: usize = 16; + +/// How long one loopback connection may take to send its request line, and to +/// take the response, before it is dropped and its slot freed. +#[cfg(not(test))] +const CALLBACK_IO_TIMEOUT: Duration = Duration::from_secs(10); +/// Unit tests free a slot held by an idle connection without a long wait. +#[cfg(test)] +const CALLBACK_IO_TIMEOUT: Duration = Duration::from_millis(200); + +/// Accept loopback connections until one hits `/callback` with the matching +/// `state`, then return its `code`. Connections are served concurrently (up to +/// [`MAX_CALLBACK_CONNECTIONS`], each bounded by [`CALLBACK_IO_TIMEOUT`]), so an +/// idle or slow connection cannot block the real redirect. +async fn wait_for_callback(listener: TcpListener, expected_state: &str) -> CloudResult { + let expected_state: std::sync::Arc = expected_state.into(); + // Dropping the set on return aborts the connections still being served. + let mut connections = tokio::task::JoinSet::new(); + loop { + tokio::select! { + accepted = listener.accept(), if connections.len() < MAX_CALLBACK_CONNECTIONS => { + let (stream, _) = accepted + .map_err(|error| CloudError::new(format!("loopback accept failed: {error}")))?; + let expected_state = expected_state.clone(); + connections.spawn(async move { serve_callback(stream, &expected_state).await }); + } + Some(served) = connections.join_next() => { + if let Ok(Some(outcome)) = served { + return outcome; + } + } + } + } +} + +/// Serve one loopback connection; `None` means it was answered (or dropped) +/// and the wait goes on. A missing or mismatched `state` cannot be tied to this +/// request (a stray tab, or a forged redirect), so it is answered and ignored, +/// as are unrelated paths (e.g. `/favicon.ico`). With a matching `state`, an +/// `error` redirect (`access_denied` on denial) or a missing/unusable `code` +/// ends the wait. +async fn serve_callback( + mut stream: tokio::net::TcpStream, + expected_state: &str, +) -> Option> { + let target = + match tokio::time::timeout(CALLBACK_IO_TIMEOUT, read_request_target(&mut stream)).await { + Ok(Some(target)) => target, + Ok(None) => { + write_response(&mut stream, "400 Bad Request", BAD_REQUEST_HTML).await; + return None; + } + // Idle past the bound: drop it without a response. + Err(_) => return None, + }; + + let (path, query) = split_target(&target); + if path != "/callback" { + write_response(&mut stream, "404 Not Found", NOT_FOUND_HTML).await; + return None; + } + + let params = parse_query(query); + if params.get("state").map(String::as_str) != Some(expected_state) { + write_response(&mut stream, "400 Bad Request", BAD_REQUEST_HTML).await; + return None; + } + // An error redirect (RFC 6749 §4.1.2.1) carries no code and is final. + if let Some(error) = params.get("error") { + return Some(Err(if error == "access_denied" { + write_response(&mut stream, "200 OK", DENIED_HTML).await; + CloudError::new("access request denied") + } else { + write_response(&mut stream, "400 Bad Request", BAD_REQUEST_HTML).await; + redirect_error(error) + })); + } + Some(match params.get("code").filter(|code| valid_code(code)) { + Some(code) => { + write_response(&mut stream, "200 OK", SUCCESS_HTML).await; + Ok(code.clone()) + } + None => { + write_response(&mut stream, "400 Bad Request", BAD_REQUEST_HTML).await; + Err(CloudError::new( + "access request redirect carried no usable authorization code", + )) + } + }) +} + +/// A non-denial error redirect. The RFC 6749 error code is echoed only when it +/// is a plain token, so the message never carries arbitrary redirect input. +fn redirect_error(error: &str) -> CloudError { + let token = (1..=64).contains(&error.len()) + && error.bytes().all(|b| b.is_ascii_lowercase() || b == b'_'); + if token { + CloudError::new(format!( + "access request redirect reported an error: {error}" + )) + } else { + CloudError::new("access request redirect reported an error") + } +} + +/// The largest request line (terminator included) accepted from the loopback +/// callback before the connection is treated as malformed and ignored. +const MAX_REQUEST_LINE: usize = 8 * 1024; + +/// Read the HTTP request line and return its request target (the second token). +/// +/// A TCP read may split the request line anywhere — including midway through +/// the `state` value — so bytes are buffered through the request-line +/// terminator and only then parsed; parsing whatever a single read happened to +/// deliver would treat a partial `state` as a CSRF mismatch and abort approval. +/// An oversized line without a terminator is reported as no target. +async fn read_request_target(stream: &mut tokio::net::TcpStream) -> Option { + let mut buffer = Vec::new(); + let mut chunk = [0u8; 2048]; + loop { + let read = stream.read(&mut chunk).await.ok()?; + if read == 0 { + return None; + } + buffer.extend_from_slice(&chunk[..read]); + if let Some(line_end) = buffer.iter().position(|byte| *byte == b'\n') { + let text = String::from_utf8_lossy(&buffer[..line_end]); + let line = text.strip_suffix('\r').unwrap_or(&text); + return line.split_whitespace().nth(1).map(str::to_string); + } + if buffer.len() > MAX_REQUEST_LINE { + return None; + } + } +} + +fn split_target(target: &str) -> (&str, &str) { + match target.split_once('?') { + Some((path, query)) => (path, query), + None => (target, ""), + } +} + +fn parse_query(query: &str) -> HashMap { + query + .split('&') + .filter(|pair| !pair.is_empty()) + .filter_map(|pair| { + let (key, value) = pair.split_once('=')?; + let value = urlencoding::decode(value).ok()?.into_owned(); + Some((key.to_string(), value)) + }) + .collect() +} + +async fn write_response(stream: &mut tokio::net::TcpStream, status: &str, body: &str) { + let response = format!( + "HTTP/1.1 {status}\r\nContent-Type: text/html; charset=utf-8\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}", + body.len() + ); + // Best effort, and bounded: a client that never reads cannot hold the slot. + let _ = tokio::time::timeout(CALLBACK_IO_TIMEOUT, async { + stream.write_all(response.as_bytes()).await?; + stream.flush().await + }) + .await; +} + +const SUCCESS_HTML: &str = "Access approved

Access approved

You can return to your terminal.

"; +const DENIED_HTML: &str = "Access denied

Access denied

The request was denied. You can return to your terminal.

"; +const NOT_FOUND_HTML: &str = "Not found"; +const BAD_REQUEST_HTML: &str = "Invalid request. You can close this tab and return to your terminal."; + +// ── waiting for approval ──────────────────────────────────────────────────── + +/// An immutable wall deadline with a monotonic ceiling: clock rollback cannot +/// extend it, while a forward adjustment may shorten it. +struct Deadline { + epoch_millis: i64, + monotonic: Instant, +} + +fn epoch_millis() -> CloudResult { + SystemTime::now() + .duration_since(UNIX_EPOCH) + .ok() + .and_then(|duration| i64::try_from(duration.as_millis()).ok()) + .ok_or_else(|| CloudError::new("invalid system clock for access request")) +} + +impl Deadline { + fn new(value: Option, now: i64, instant: Instant) -> CloudResult { + let epoch_millis = value.filter(|value| (1..=MAX_EPOCH_MILLIS).contains(value)) + .ok_or_else(|| CloudError::new("access request has a missing or invalid deadline; server deadline support is required"))?; + let remaining = Duration::from_millis(epoch_millis.saturating_sub(now).max(0) as u64); + let monotonic = instant + .checked_add(remaining) + .ok_or_else(|| CloudError::new("access request deadline is not representable"))?; + Ok(Self { + epoch_millis, + monotonic, + }) + } + + fn remaining_at(&self, now: i64, instant: Instant) -> Duration { + Duration::from_millis(self.epoch_millis.saturating_sub(now).max(0) as u64) + .min(self.monotonic.saturating_duration_since(instant)) + } + + fn remaining(&self) -> CloudResult { + Ok(self.remaining_at(epoch_millis()?, Instant::now())) + } +} + +struct PendingApproval { + requested_role_ids: Vec, + deadline: Deadline, + /// Which deadline `deadline` holds, so its expiry is reported truthfully. + limit: WaitLimit, +} + +/// The deadline that bounds the wait: the server's `expiresAt`, or the +/// sooner `--timeout-seconds`. +#[derive(Clone, Copy, Debug, PartialEq)] +enum WaitLimit { + Server, + Local(Duration), +} + +impl WaitLimit { + fn expired(self) -> CloudError { + match self { + Self::Server => CloudError::new("access request expired"), + Self::Local(timeout) => CloudError::new(format!( + "access request approval wait timed out after {} seconds", + timeout.as_secs() + )), + } + } +} + +impl PendingApproval { + #[cfg(test)] + fn new(created: &CreateAccessRequestResponse) -> CloudResult { + Self::with_timeout(created, APPROVAL_TIMEOUT) + } + + fn with_timeout(created: &CreateAccessRequestResponse, timeout: Duration) -> CloudResult { + if created.request_id.trim().is_empty() + || created.approval_url.trim().is_empty() + || created.status.as_deref() != Some("pending") + { + return Err(CloudError::new("file access request: incomplete response")); + } + let now = Instant::now(); + let mut deadline = Deadline::new(created.expires_at, epoch_millis()?, now)?; + let local_deadline = now + .checked_add(timeout) + .ok_or_else(|| CloudError::usage("approval timeout is not representable"))?; + let limit = if local_deadline < deadline.monotonic { + deadline.monotonic = local_deadline; + WaitLimit::Local(timeout) + } else { + WaitLimit::Server + }; + Ok(Self { + requested_role_ids: canonical_role_ids(created.requested_role_ids.as_deref(), true)?, + deadline, + limit, + }) + } +} + +/// An authorization code from the redirect: 1 to 512 bytes of printable, +/// non-space ASCII. The server's code format is otherwise opaque. +fn valid_code(code: &str) -> bool { + (1..=512).contains(&code.len()) && code.bytes().all(|c| (0x21..=0x7E).contains(&c)) +} + +enum OperationError { + Timeout, + Failed(CloudError), +} + +impl OperationError { + fn into_cloud(self, timeout_message: &str) -> CloudError { + match self { + Self::Timeout => CloudError::new(timeout_message), + Self::Failed(error) => error, + } + } +} + +/// Covers send, body and decoding. The elapsed check also catches synchronous +/// decoding that finishes after the timeout without yielding to Tokio. +async fn operation( + budget: Duration, + future: impl std::future::Future>, +) -> Result { + if budget.is_zero() { + return Err(OperationError::Timeout); + } + let start = Instant::now(); + match tokio::time::timeout(budget, future).await { + Ok(result) if start.elapsed() < budget => result.map_err(OperationError::Failed), + _ => Err(OperationError::Timeout), + } +} + +/// The authorization code arrives only on the loopback redirect, which also +/// carries a denial. The request status is never read: the redirect and the +/// pending deadline are the only signals, so no server status field can end +/// the wait before this machine's redirect arrives. +async fn wait_for_redirect( + pending: PendingApproval, + listener: TcpListener, + state: &str, +) -> CloudResult { + let remaining = pending.deadline.remaining()?; + tokio::select! { + biased; + code = wait_for_callback(listener, state) => code, + _ = tokio::time::sleep(remaining) => Err(pending.limit.expired()), + } +} + +/// Exchange the redirect's code for the key, once. A 401 here means the code +/// or the PKCE verifier was refused, not the user's identity, and a 403 is a +/// missing permission, so every failure is a plain one (exit 1). +async fn exchange_code( + http: &reqwest::Client, + token_url: &str, + auth: &RequestAuth, + code: &str, + verifier: &str, + redirect_uri: &str, +) -> CloudResult { + operation( + EXCHANGE_TIMEOUT, + send_json( + http.post(token_url), + auth, + &TokenBody { + code, + code_verifier: verifier, + redirect_uri, + }, + "exchange authorization code", + &[code, verifier], + &[], + ), + ) + .await + .map_err(|error| { + error.into_cloud( + "exchange authorization code timed out; the exchange may have completed on the server; no credentials were installed", + ) + }) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::cli::{Cli, Commands}; + use clap::Parser; + + fn created(expires_at: i64) -> CreateAccessRequestResponse { + CreateAccessRequestResponse { + requested_role_ids: Some(vec![]), + request_id: "request-1".into(), + status: Some("pending".into()), + approval_url: "https://example.invalid/approve".into(), + expires_at: Some(expires_at), + } + } + + fn bearer() -> RequestAuth { + RequestAuth::Bearer { + token: "fake".into(), + } + } + + #[test] + fn canonical_role_ids_validate_server_arrays_without_inferring_grants() { + let system = "21111111-1111-1111-9999-000000000007".to_string(); + let upper = "AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA".to_string(); + assert_eq!( + canonical_role_ids(Some(&[system.clone(), upper.clone()]), true).unwrap(), + vec![system, upper.to_lowercase()] + ); + assert_eq!( + canonical_role_ids(Some(&[]), true).unwrap(), + Vec::::new() + ); + assert!(canonical_role_ids(Some(&[]), false).is_err()); + for proposal in [true, false] { + assert!(canonical_role_ids(None, proposal).is_err()); + assert!( + canonical_role_ids(Some(&[upper.clone(), upper.to_lowercase()]), proposal).is_err() + ); + for invalid in [ + "", + "role-name", + "*", + "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "{aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa}", + "urn:uuid:aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", + " aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", + ] { + let error = canonical_role_ids(Some(&[invalid.into()]), proposal).unwrap_err(); + assert!(!error.message.contains("aaaaaaaa")); + } + } + let many: Vec<_> = (1..=101) + .map(|id| format!("00000000-0000-0000-0000-{id:012x}")) + .collect(); + assert!(canonical_role_ids(Some(&many[..100]), true).is_ok()); + assert!(canonical_role_ids(Some(&many), true).is_err()); + assert_eq!(canonical_role_ids(Some(&many), false).unwrap().len(), 101); + } + + #[test] + fn role_response_fields_reject_malformed_types() { + for value in [ + serde_json::json!(42), + serde_json::json!("secret-value"), + serde_json::json!([null]), + serde_json::json!([1]), + serde_json::json!({}), + ] { + let create = serde_json::json!({"requestId":"request-1", "status":"pending", "approvalUrl":"https://example.invalid", "expiresAt":4102444800000_i64, "requestedRoleIds":value}); + assert!(serde_json::from_value::(create).is_err()); + let token = serde_json::json!({"keyId":"key-id", "key":"key", "secret":"secret", "grantedRoleIds":value}); + assert!(serde_json::from_value::(token).is_err()); + } + } + + #[test] + fn deadline_boundaries_clock_changes_and_epoch_domain() { + let instant = Instant::now(); + for (epoch, remaining) in [(999, 0), (1000, 0), (1001, 1)] { + let deadline = Deadline::new(Some(epoch), 1000, instant).unwrap(); + assert_eq!( + deadline.remaining_at(1000, instant), + Duration::from_millis(remaining) + ); + } + let deadline = Deadline::new(Some(2000), 1000, instant).unwrap(); + assert_eq!( + deadline.remaining_at(500, instant + Duration::from_millis(600)), + Duration::from_millis(400) + ); + assert_eq!( + deadline.remaining_at(1900, instant), + Duration::from_millis(100) + ); + for value in [ + None, + Some(-1), + Some(0), + Some(MAX_EPOCH_MILLIS + 1), + Some(i64::MAX), + ] { + assert!(Deadline::new(value, 1000, instant).is_err()); + } + // Platforms may reject a huge Instant, but must never panic or clamp. + if let Ok(deadline) = Deadline::new(Some(MAX_EPOCH_MILLIS), 1000, instant) { + assert_eq!(deadline.epoch_millis, MAX_EPOCH_MILLIS); + } + for value in [ + serde_json::json!(null), + serde_json::json!(1.5), + serde_json::json!("secret"), + serde_json::json!(18446744073709551615_u64), + ] { + let wire = serde_json::json!({"requestId":"request-1", "status":"pending", "approvalUrl":"https://example.invalid", "expiresAt":value}); + if let Ok(created) = serde_json::from_value::(wire) { + assert!(PendingApproval::new(&created).is_err()); + } + } + let future = created(4102444800000); + assert!( + PendingApproval::new(&future) + .unwrap() + .deadline + .remaining() + .unwrap() + <= APPROVAL_TIMEOUT + ); + } + + #[test] + fn valid_code_accepts_printable_non_space_ascii_up_to_512_bytes() { + for code in ["a", "_-09AZaz", "a=b.c~d/e+f", "!~", &"a".repeat(512)] { + assert!(valid_code(code), "{code}"); + } + for code in [ + "", + " a", + "a b", + "a\n", + "a\t", + "\u{7f}", + "é", + &"a".repeat(513), + ] { + assert!(!valid_code(code), "{code:?}"); + } + } + + #[test] + fn wait_limit_reports_the_deadline_that_won() { + let created = created(4102444800000); + let pending = PendingApproval::with_timeout(&created, Duration::from_secs(7)).unwrap(); + assert_eq!(pending.limit, WaitLimit::Local(Duration::from_secs(7))); + assert_eq!( + pending.limit.expired().message, + "access request approval wait timed out after 7 seconds" + ); + let soon = created_in(100); + let pending = PendingApproval::with_timeout(&soon, Duration::from_secs(7)).unwrap(); + assert_eq!(pending.limit, WaitLimit::Server); + assert_eq!(pending.limit.expired().message, "access request expired"); + } + + fn created_in(millis: i64) -> CreateAccessRequestResponse { + created(epoch_millis().unwrap() + millis) + } + + #[tokio::test] + async fn ambiguous_org_name_points_to_org_id_with_every_match() { + use wiremock::{Mock, MockServer, ResponseTemplate}; + const FIRST: &str = "00000000-0000-0000-0000-0000000000a1"; + const SECOND: &str = "00000000-0000-0000-0000-0000000000a2"; + let server = MockServer::start().await; + Mock::given(wiremock::matchers::method("GET")) + .and(wiremock::matchers::path("/v1/organizations")) + .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({ + "result": [ + {"id": FIRST, "name": "shared"}, + {"id": SECOND, "name": "shared"} + ] + }))) + .expect(1) + .mount(&server) + .await; + let client = CloudClient::new(Some("key"), Some("secret"), Some(&server.uri())).unwrap(); + let error = client + .resolve_access_organization_id(None, Some("shared".into())) + .await + .unwrap_err(); + // The advice must name a selector `cloud access` accepts. + let selector = format!("--org-id={FIRST}"); + crate::cli::Cli::try_parse_from(["clickhousectl", "cloud", "access", "roles", &selector]) + .unwrap(); + for token in ["--org-id", FIRST, SECOND] { + assert!( + error.message.contains(token), + "missing {token}: {}", + error.message + ); + } + } + + #[tokio::test] + async fn operation_timeout_covers_body_and_exchange_is_not_retried() { + use wiremock::{Mock, MockServer, ResponseTemplate}; + let server = MockServer::start().await; + Mock::given(wiremock::matchers::method("POST")) + .respond_with(ResponseTemplate::new(200).set_delay(EXCHANGE_TIMEOUT * 2)) + .expect(1) + .mount(&server) + .await; + let error = tokio::time::timeout( + EXCHANGE_TIMEOUT * 3, + exchange_code( + &reqwest::Client::new(), + &server.uri(), + &bearer(), + "secret-code", + "secret-verifier", + "http://127.0.0.1:1/callback", + ), + ) + .await + .unwrap() + .err() + .unwrap(); + assert!(error.message.contains("may have completed")); + assert!(!error.message.contains("secret")); + let result = operation::<()>(Duration::from_millis(5), async { + tokio::time::sleep(Duration::from_secs(1)).await; + Ok(()) + }) + .await; + assert!(matches!(result, Err(OperationError::Timeout))); + } + + /// A status server that answers every GET with `body`, counting calls. + /// Send one raw request target to the listener and return the response. + async fn send_callback(address: SocketAddr, target: &str) -> String { + let mut stream = tokio::net::TcpStream::connect(address).await.unwrap(); + stream + .write_all(format!("GET {target} HTTP/1.1\r\n\r\n").as_bytes()) + .await + .unwrap(); + let mut response = Vec::new(); + stream.read_to_end(&mut response).await.unwrap(); + String::from_utf8_lossy(&response).into_owned() + } + + #[tokio::test] + async fn bind_loopback_prefers_ipv4_then_ipv6_and_errors_without_either() { + let loopback = bind_loopback(TcpListener::bind).await.unwrap(); + let port = loopback.listener.local_addr().unwrap().port(); + assert_eq!( + loopback.redirect_uri, + format!("http://127.0.0.1:{port}/callback") + ); + assert!(!loopback.state.is_empty()); + + let tried = std::sync::Mutex::new(Vec::new()); + let ipv6 = bind_loopback(|address: SocketAddr| { + tried.lock().unwrap().push(address); + async move { + if address.is_ipv4() { + Err(std::io::Error::other("fake IPv4 failure")) + } else { + // Stand in for [::1] where the host has no IPv6. + TcpListener::bind(("127.0.0.1", 0)).await + } + } + }) + .await + .unwrap(); + assert_eq!( + *tried.lock().unwrap(), + [ + "127.0.0.1:0".parse::().unwrap(), + "[::1]:0".parse().unwrap() + ] + ); + assert!(ipv6.redirect_uri.starts_with("http://127.0.0.1:")); + if let Ok(listener) = TcpListener::bind("[::1]:0").await { + drop(listener); + let ipv6 = bind_loopback(|address: SocketAddr| async move { + if address.is_ipv4() { + Err(std::io::Error::other("fake IPv4 failure")) + } else { + TcpListener::bind(address).await + } + }) + .await + .unwrap(); + let port = ipv6.listener.local_addr().unwrap().port(); + assert_eq!(ipv6.redirect_uri, format!("http://[::1]:{port}/callback")); + } + + let error = bind_loopback(|_| async { Err(std::io::Error::other("fake")) }) + .await + .err() + .unwrap(); + assert_eq!( + error.message, + "could not start a local redirect listener on 127.0.0.1 or [::1]" + ); + } + + #[tokio::test] + async fn wait_for_redirect_takes_the_code_from_the_callback() { + let created = created(4102444800000); + let listener = TcpListener::bind("127.0.0.1:0").await.unwrap(); + let address = listener.local_addr().unwrap(); + let wait = wait_for_redirect(PendingApproval::new(&created).unwrap(), listener, "state"); + let notify = async { + let response = send_callback(address, "/callback?code=test-code&state=state").await; + assert!(response.starts_with("HTTP/1.1 200")); + }; + let (code, ()) = + tokio::time::timeout(Duration::from_secs(2), async { tokio::join!(wait, notify) }) + .await + .unwrap(); + assert_eq!(code.unwrap(), "test-code"); + } + + #[tokio::test] + async fn wait_for_callback_ignores_unmatched_state_and_other_paths() { + let listener = TcpListener::bind("127.0.0.1:0").await.unwrap(); + let address = listener.local_addr().unwrap(); + let wait = wait_for_callback(listener, "state"); + let notify = async { + for (target, status) in [ + ("/favicon.ico", "404"), + ("/callback?code=forged&state=other", "400"), + ("/callback?code=forged", "400"), + ("/callback?state=", "400"), + ("/callback?code=a%3Db&state=state", "200"), + ] { + let response = send_callback(address, target).await; + assert!( + response.starts_with(&format!("HTTP/1.1 {status}")), + "{target}: {response}" + ); + } + }; + let (code, ()) = + tokio::time::timeout(Duration::from_secs(2), async { tokio::join!(wait, notify) }) + .await + .unwrap(); + assert_eq!(code.unwrap(), "a=b"); + } + + #[tokio::test] + async fn wait_for_callback_with_matching_state_and_bad_code_is_an_error() { + for target in [ + "/callback?state=state", + "/callback?code=&state=state", + "/callback?code=a%20b&state=state", + "/callback?code=a%0Ab&state=state", + ] { + let listener = TcpListener::bind("127.0.0.1:0").await.unwrap(); + let address = listener.local_addr().unwrap(); + let (result, response) = tokio::time::timeout(Duration::from_secs(2), async { + tokio::join!( + wait_for_callback(listener, "state"), + send_callback(address, target) + ) + }) + .await + .unwrap(); + assert!(response.starts_with("HTTP/1.1 400"), "{target}"); + let error = result.unwrap_err(); + assert!( + matches!(error.kind, crate::cloud::client::CloudErrorKind::Generic), + "{target}" + ); + assert!(error.message.contains("no usable authorization code")); + } + } + + #[tokio::test] + async fn wait_for_callback_with_matching_state_and_error_ends_the_wait() { + for (target, status, message) in [ + ( + "/callback?error=access_denied&state=state", + "200", + "access request denied", + ), + ( + "/callback?error=server_error&state=state", + "400", + "access request redirect reported an error: server_error", + ), + ( + "/callback?error=%3Cscript%3E&state=state", + "400", + "access request redirect reported an error", + ), + ] { + let listener = TcpListener::bind("127.0.0.1:0").await.unwrap(); + let address = listener.local_addr().unwrap(); + let (result, response) = tokio::time::timeout(Duration::from_secs(2), async { + tokio::join!( + wait_for_callback(listener, "state"), + send_callback(address, target) + ) + }) + .await + .unwrap(); + assert!( + response.starts_with(&format!("HTTP/1.1 {status}")), + "{target}" + ); + let error = result.unwrap_err(); + assert!( + matches!(error.kind, crate::cloud::client::CloudErrorKind::Generic), + "{target}" + ); + assert_eq!(error.message, message, "{target}"); + } + } + + #[tokio::test] + async fn wait_for_callback_ignores_error_with_unmatched_state() { + let listener = TcpListener::bind("127.0.0.1:0").await.unwrap(); + let address = listener.local_addr().unwrap(); + let wait = wait_for_callback(listener, "state"); + let notify = async { + let forged = send_callback(address, "/callback?error=access_denied&state=other").await; + assert!(forged.starts_with("HTTP/1.1 400")); + let real = send_callback(address, "/callback?code=c&state=state").await; + assert!(real.starts_with("HTTP/1.1 200")); + }; + let (code, ()) = + tokio::time::timeout(Duration::from_secs(2), async { tokio::join!(wait, notify) }) + .await + .unwrap(); + assert_eq!(code.unwrap(), "c"); + } + + #[tokio::test] + async fn wait_for_redirect_reports_local_and_server_deadlines() { + let created = created(4102444800000); + let mut pending = PendingApproval::with_timeout(&created, Duration::from_secs(9)).unwrap(); + pending.deadline.monotonic = Instant::now() + Duration::from_millis(150); + let listener = TcpListener::bind("127.0.0.1:0").await.unwrap(); + let address = listener.local_addr().unwrap(); + let wait = wait_for_redirect(pending, listener, "state"); + // An idle connection without a request line is cut off by the deadline. + let idle = async { + let mut stream = tokio::net::TcpStream::connect(address).await.unwrap(); + let mut response = Vec::new(); + let _ = stream.read_to_end(&mut response).await; + }; + let (result, ()) = + tokio::time::timeout(Duration::from_secs(2), async { tokio::join!(wait, idle) }) + .await + .unwrap(); + assert_eq!( + result.unwrap_err().message, + "access request approval wait timed out after 9 seconds" + ); + + let created = created_in(150); + let result = tokio::time::timeout( + Duration::from_secs(2), + wait_for_redirect( + PendingApproval::new(&created).unwrap(), + TcpListener::bind("127.0.0.1:0").await.unwrap(), + "state", + ), + ) + .await + .unwrap(); + assert_eq!(result.unwrap_err().message, "access request expired"); + } + + #[tokio::test] + async fn wait_for_callback_reassembles_a_request_line_split_across_writes() { + let listener = TcpListener::bind("127.0.0.1:0").await.unwrap(); + let address = listener.local_addr().unwrap(); + let wait = wait_for_callback(listener, "state"); + let notify = async { + let mut stream = tokio::net::TcpStream::connect(address).await.unwrap(); + stream + .write_all(b"GET /callback?code=test-code&sta") + .await + .unwrap(); + // Keep the halves in separate reads; a read need not cover the + // whole line, and this split lands midway through the state value. + tokio::time::sleep(Duration::from_millis(50)).await; + stream + .write_all(b"te=state HTTP/1.1\r\n\r\n") + .await + .unwrap(); + let mut response = Vec::new(); + stream.read_to_end(&mut response).await.unwrap(); + assert!(String::from_utf8_lossy(&response).starts_with("HTTP/1.1 200")); + }; + let (code, ()) = + tokio::time::timeout(Duration::from_secs(2), async { tokio::join!(wait, notify) }) + .await + .unwrap(); + assert_eq!(code.unwrap(), "test-code"); + } + + #[tokio::test] + async fn wait_for_callback_is_not_blocked_by_an_idle_connection() { + let listener = TcpListener::bind("127.0.0.1:0").await.unwrap(); + let address = listener.local_addr().unwrap(); + // Accepted first and never sends a byte, like a browser preconnect. + let idle = tokio::net::TcpStream::connect(address).await.unwrap(); + let started = Instant::now(); + let (code, response) = tokio::time::timeout(Duration::from_secs(2), async { + tokio::join!(wait_for_callback(listener, "state"), async { + // Let the listener accept the idle connection first. + tokio::time::sleep(Duration::from_millis(20)).await; + send_callback(address, "/callback?code=c&state=state").await + }) + }) + .await + .unwrap(); + assert_eq!(code.unwrap(), "c"); + assert!(response.starts_with("HTTP/1.1 200")); + // Served while the idle connection still held its slot. + assert!(started.elapsed() < CALLBACK_IO_TIMEOUT); + drop(idle); + } + + #[tokio::test] + async fn wait_for_callback_frees_slots_held_by_idle_connections() { + let listener = TcpListener::bind("127.0.0.1:0").await.unwrap(); + let address = listener.local_addr().unwrap(); + let mut idle = Vec::new(); + for _ in 0..MAX_CALLBACK_CONNECTIONS { + idle.push(tokio::net::TcpStream::connect(address).await.unwrap()); + } + let started = Instant::now(); + let (code, response) = tokio::time::timeout(Duration::from_secs(2), async { + tokio::join!(wait_for_callback(listener, "state"), async { + tokio::time::sleep(Duration::from_millis(20)).await; + send_callback(address, "/callback?code=c&state=state").await + }) + }) + .await + .unwrap(); + assert_eq!(code.unwrap(), "c"); + assert!(response.starts_with("HTTP/1.1 200")); + // Every slot was taken, so the callback waited for an idle one to time out. + assert!(started.elapsed() >= CALLBACK_IO_TIMEOUT); + drop(idle); + } + + #[tokio::test] + async fn read_request_target_skips_an_oversized_line_without_a_terminator() { + let listener = TcpListener::bind("127.0.0.1:0").await.unwrap(); + let address = listener.local_addr().unwrap(); + let mut client = tokio::net::TcpStream::connect(address).await.unwrap(); + let (mut server, _) = listener.accept().await.unwrap(); + let oversized = "GET /".to_string() + &"a".repeat(MAX_REQUEST_LINE + 1); + let writer = tokio::spawn(async move { + // The reader may stop before the tail lands; delivery is best-effort. + let _ = client.write_all(oversized.as_bytes()).await; + }); + let target = tokio::time::timeout(Duration::from_secs(2), read_request_target(&mut server)) + .await + .unwrap(); + assert_eq!(target, None); + writer.await.unwrap(); + } + + #[tokio::test] + async fn handshake_client_never_follows_redirects() { + use wiremock::matchers::{method, path}; + use wiremock::{Mock, MockServer, ResponseTemplate}; + let token_path = "/v1/organizations/org/accessRequests/authorizationCode/token"; + for status in [301, 302, 303, 307, 308] { + let server = MockServer::start().await; + let destination = MockServer::start().await; + Mock::given(method("POST")) + .and(path(token_path)) + .respond_with( + ResponseTemplate::new(status) + .insert_header("Location", format!("{}/stolen", destination.uri())), + ) + .expect(1) + .mount(&server) + .await; + let exchanged = exchange_code( + &handshake_client().unwrap(), + &format!("{}{token_path}", server.uri()), + &bearer(), + "code-secret", + "secret-verifier", + "http://127.0.0.1:1/callback", + ) + .await; + let error = exchanged.err().unwrap(); + assert!( + !error.message.contains("secret"), + "redirect handling must not leak the verifier: {error}" + ); + assert!(destination.received_requests().await.unwrap().is_empty()); + } + } + + #[tokio::test] + async fn operation_bounds_response_body_read_and_sanitizes_envelope() { + let listener = TcpListener::bind("127.0.0.1:0").await.unwrap(); + let address = listener.local_addr().unwrap(); + let server = tokio::spawn(async move { + let (mut stream, _) = listener.accept().await.unwrap(); + let mut request = [0; 4096]; + assert!(stream.read(&mut request).await.unwrap() > 0); + stream + .write_all(b"HTTP/1.1 200 OK\r\nContent-Length: 1000\r\n\r\n{") + .await + .unwrap(); + std::future::pending::<()>().await; + }); + let client = reqwest::Client::new(); + let result = operation(Duration::from_millis(50), async { + let response = client + .get(format!("http://{address}")) + .send() + .await + .unwrap(); + parse_response::(response, "exchange", &[], &[]).await + }) + .await; + server.abort(); + assert!(matches!(result, Err(OperationError::Timeout))); + + use wiremock::{Mock, MockServer, ResponseTemplate}; + for field in ["error", "status"] { + let server = MockServer::start().await; + let mut body = serde_json::json!({"result":{"keyId":"k","key":"k","secret":"s"}}); + body[field] = if field == "error" { + serde_json::json!("secret-echo") + } else { + serde_json::json!(500) + }; + Mock::given(wiremock::matchers::method("POST")) + .respond_with(ResponseTemplate::new(200).set_body_json(body)) + .mount(&server) + .await; + let error = exchange_code( + &client, + &server.uri(), + &bearer(), + "code", + "verifier", + "http://127.0.0.1:1/callback", + ) + .await + .err() + .unwrap(); + assert!(!error.message.contains("secret-echo")); + assert!(error.message.contains("envelope")); + } + } + + #[test] + fn approval_handoff_launches_once_and_survives_launcher_failure() { + let mut calls = 0; + approval_handoff("https://example.invalid/approve", |url| { + assert_eq!(url, "https://example.invalid/approve"); + calls += 1; + Ok(()) + }); + assert_eq!(calls, 1); + // Launcher failure still permits opening the printed URL manually. + approval_handoff("https://example.invalid/approve", |_| { + Err(std::io::Error::other("fake launcher failure")) + }); + } + + #[tokio::test] + async fn exchange_maps_statuses_once_and_never_echoes_code_or_verifier() { + use crate::cloud::client::CloudErrorKind; + use wiremock::{Mock, MockServer, ResponseTemplate}; + for (status, message, kind) in [ + ( + 400, + "BAD_REQUEST: request is not approved", + CloudErrorKind::Generic, + ), + (400, "BAD_REQUEST: code expired", CloudErrorKind::Generic), + ( + 400, + "BAD_REQUEST: code already redeemed", + CloudErrorKind::Generic, + ), + ( + 400, + "BAD_REQUEST: invalid_grant: redirect URI does not match the filed value", + CloudErrorKind::Generic, + ), + ( + 400, + "BAD_REQUEST: request body property can't be validated: code secret-code", + CloudErrorKind::Generic, + ), + (401, "UNAUTHORIZED: invalid code", CloudErrorKind::Generic), + ( + 401, + "UNAUTHORIZED: PKCE verification failed secret-verifier", + CloudErrorKind::Generic, + ), + ( + 403, + "FORBIDDEN: early access API endpoint", + CloudErrorKind::Generic, + ), + ( + 403, + "FORBIDDEN: access requests require permission to create API keys", + CloudErrorKind::Generic, + ), + ( + 403, + "FORBIDDEN: access requests require an organization migrated to RBAC v2", + CloudErrorKind::Generic, + ), + ( + 403, + "FORBIDDEN: some other refusal", + CloudErrorKind::Generic, + ), + ( + 404, + "NOT_FOUND: access request not found", + CloudErrorKind::Generic, + ), + ( + 500, + "INTERNAL_SERVER_ERROR: secret-code", + CloudErrorKind::Generic, + ), + ] { + let server = MockServer::start().await; + Mock::given(wiremock::matchers::method("POST")) + .respond_with( + ResponseTemplate::new(status).set_body_json(serde_json::json!({ + "error": message, "status": status, "requestId": "corr-1" + })), + ) + .expect(1) + .mount(&server) + .await; + let error = exchange_code( + &reqwest::Client::new(), + &server.uri(), + &bearer(), + "secret-code", + "secret-verifier", + "http://127.0.0.1:1/callback", + ) + .await + .err() + .unwrap(); + assert_eq!( + std::mem::discriminant(&error.kind), + std::mem::discriminant(&kind), + "{status} {message}" + ); + assert!(error.message.contains(&format!("({status}")), "{error}"); + // The server's text is shown, minus the secrets it echoes. + let shown = message.split(" secret").next().unwrap(); + assert!( + error.message.contains(shown.trim_end_matches(": ")), + "{error}" + ); + assert!(!error.message.contains("secret-code"), "{error}"); + assert!(!error.message.contains("secret-verifier"), "{error}"); + } + } + + #[test] + fn server_error_message_surfaces_error_string_safely() { + let body = |value: serde_json::Value| serde_json::to_vec(&value).unwrap(); + assert_eq!( + server_error_message( + &body(serde_json::json!({"error":"PKCE verification failed","status":401})), + &[] + ) + .as_deref(), + Some("PKCE verification failed") + ); + let echoed = server_error_message( + &body(serde_json::json!({"error":"BAD_REQUEST: code 'code-1' verifier 'ver-1'"})), + &["code-1", "ver-1", ""], + ) + .unwrap(); + assert!(!echoed.contains("code-1") && !echoed.contains("ver-1")); + assert!(echoed.contains("[redacted]")); + let long = server_error_message( + &body(serde_json::json!({"error": format!("a\n{}", "b".repeat(1000))})), + &[], + ) + .unwrap(); + assert_eq!(long.chars().count(), MAX_SERVER_ERROR_CHARS); + assert!(!long.contains('\n')); + for raw in [ + b"not json".to_vec(), + body(serde_json::json!({"error": {"nested":"secret"}})), + body(serde_json::json!({"message":"secret"})), + body(serde_json::json!({"error":" "})), + ] { + assert_eq!(server_error_message(&raw, &[]), None); + } + } + + #[tokio::test] + async fn exchange_sends_code_verifier_and_redirect_uri() { + use wiremock::{Mock, MockServer, ResponseTemplate}; + let server = MockServer::start().await; + Mock::given(wiremock::matchers::method("POST")) + .and(wiremock::matchers::header("authorization", "Bearer fake")) + .and(wiremock::matchers::body_json(serde_json::json!({ + "code": "redirect-code", + "codeVerifier": "verifier", + "redirectUri": "http://127.0.0.1:1234/callback" + }))) + .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({ + "result": {"keyId":"key-id","key":"key","secret":"secret","keyExpiresAt":1794231456974_i64,"grantedRoleIds":["21111111-1111-1111-9999-000000000007"]} + }))) + .expect(1) + .mount(&server) + .await; + let issued = exchange_code( + &reqwest::Client::new(), + &server.uri(), + &bearer(), + "redirect-code", + "verifier", + "http://127.0.0.1:1234/callback", + ) + .await + .unwrap(); + assert_eq!(issued.key_id, "key-id"); + assert_eq!(issued.key_expires_at, Some(1794231456974)); + } + + #[test] + fn key_expiry_formats_rfc3339_utc_and_rejects_out_of_range() { + assert_eq!( + key_expiry(Some(1794231456974)).unwrap().as_deref(), + Some("2026-11-09T13:37:36Z") + ); + assert_eq!(key_expiry(None).unwrap(), None); + for value in [0, -1, MAX_EPOCH_MILLIS + 1, i64::MAX] { + assert!(key_expiry(Some(value)).is_err(), "{value}"); + } + } + + fn parse(args: &[&str]) -> AccessRequestArgs { + let cli = Cli::try_parse_from(args).expect("parse"); + let Commands::Cloud(cloud) = cli.command else { + panic!("expected cloud command"); + }; + let crate::cloud::cli::CloudCommands::Access { command, .. } = cloud.command else { + panic!("expected access command"); + }; + let AccessCommands::Request(args) = command else { + panic!("expected request") + }; + args + } + + #[test] + fn request_timeout_defaults_and_validates_positive_seconds() { + assert_eq!( + parse(&["chctl", "cloud", "access", "request"]).timeout_seconds, + 120 + ); + for seconds in ["1", "600", "4294967295"] { + assert_eq!( + parse(&[ + "chctl", + "cloud", + "access", + "request", + "--timeout-seconds", + seconds + ]) + .timeout_seconds, + seconds.parse::().unwrap() + ); + } + for seconds in ["0", "-1", "", "1.5", "5m", "4294967296"] { + assert!( + Cli::try_parse_from([ + "chctl", + "cloud", + "access", + "request", + "--timeout-seconds", + seconds + ]) + .is_err() + ); + } + assert!( + Cli::try_parse_from([ + "chctl", + "cloud", + "access", + "request", + "--timeout-seconds", + "1", + "--timeout-seconds", + "2" + ]) + .is_err() + ); + assert!( + Cli::try_parse_from([ + "chctl", + "cloud", + "access", + "roles", + "--timeout-seconds", + "1" + ]) + .is_err() + ); + } + + #[test] + fn approval_timeout_override_preserves_earlier_server_expiry() { + for seconds in [1, 300, 600] { + let timeout = Duration::from_secs(seconds); + let future = created(4102444800000); + let before = Instant::now(); + let pending = PendingApproval::with_timeout(&future, timeout).unwrap(); + let after = Instant::now(); + assert!(pending.deadline.monotonic >= before + timeout); + assert!(pending.deadline.monotonic <= after + timeout); + assert_eq!(pending.deadline.epoch_millis, 4102444800000); + + let expiry = epoch_millis().unwrap() + 100; + let sooner = created(expiry); + let pending = PendingApproval::with_timeout(&sooner, timeout).unwrap(); + assert_eq!(pending.deadline.epoch_millis, expiry); + assert!(pending.deadline.remaining().unwrap() <= Duration::from_millis(100)); + } + } + + #[test] + fn request_perms_parse_deduplicates_uuid_identity_and_preserves_order() { + let first = "abcdefab-1234-1234-1234-123456789abc"; + let system = "21111111-1111-1111-9999-000000000007"; + let args = parse(&[ + "chctl", + "cloud", + "access", + "request", + "--perms", + &format!("role:{first},role:{system}"), + "--perms", + &format!("role:{}", first.to_uppercase()), + ]); + assert_eq!( + args.requested_role_ids().unwrap(), + Some(vec![first.into(), system.into()]) + ); + assert_eq!( + parse(&["chctl", "cloud", "access", "request"]) + .requested_role_ids() + .unwrap(), + None + ); + let ids: Vec<_> = (0..100) + .map(|i| format!("role:00000000-0000-0000-0000-{i:012x}")) + .collect(); + let repeated = format!("{},{}", ids.join(","), ids.join(",")); + assert_eq!( + parse(&["chctl", "cloud", "access", "request", "--perms", &repeated]) + .requested_role_ids() + .unwrap() + .unwrap() + .len(), + 100 + ); + let oversized = format!( + "{},role:00000000-0000-0000-0000-000000000100", + ids.join(",") + ); + assert!( + parse(&["chctl", "cloud", "access", "request", "--perms", &oversized]) + .requested_role_ids() + .is_err() + ); + } + + #[test] + fn request_perms_rejects_empty_malformed_and_unsupported_tokens() { + let valid = "role:00000000-0000-0000-0000-000000000001"; + for value in [ + "".to_string(), + ",".into(), + format!("{valid},"), + format!(",{valid}"), + format!("{valid},,{valid}"), + format!(" {valid}"), + format!("{valid} "), + format!("{valid}\n"), + format!("{valid}, {valid}"), + "role:00000000-0000-0000-0000-00000000000 1".into(), + "role:00000000000000000000000000000001".into(), + "role:{00000000-0000-0000-0000-000000000001}".into(), + "role:urn:uuid:00000000-0000-0000-0000-000000000001".into(), + "Role:00000000-0000-0000-0000-000000000001".into(), + "00000000-0000-0000-0000-000000000001".into(), + "role:Admin".into(), + "control-plane:service:view".into(), + "role:*".into(), + ] { + assert!( + Cli::try_parse_from(["chctl", "cloud", "access", "request", "--perms", &value]) + .is_err(), + "{value:?}" + ); + } + assert!( + Cli::try_parse_from(["chctl", "cloud", "access", "roles", "--perms", valid]).is_err() + ); + } + + #[test] + fn roles_selectors_and_help_preserve_command_grammar() { + use clap::{CommandFactory, FromArgMatches}; + for (selectors, conflict) in [ + (vec!["--org-id=one", "access", "roles", "--org=one"], false), + (vec!["--org-id=one", "access", "roles", "--org=two"], true), + ( + vec!["--org-name=name", "access", "roles", "--org-name=name"], + false, + ), + (vec!["--org-name=name", "access", "roles", "--org=id"], true), + (vec!["access", "--org=one", "roles", "--org=two"], true), + ( + vec![ + "--json", + "access", + "roles", + "--url=http://localhost:1/v1", + "--", + ], + false, + ), + ] { + let argv: Vec = ["chctl", "cloud"] + .into_iter() + .chain(selectors) + .map(Into::into) + .collect(); + let mut cmd = Cli::command(); + let matches = cmd.try_get_matches_from_mut(&argv).unwrap(); + let cli = Cli::from_arg_matches(&matches).unwrap(); + let Commands::Cloud(args) = cli.command else { + panic!("cloud expected") + }; + let result = args.validate_access_selectors(&argv); + if conflict { + assert_eq!( + result.unwrap_err().kind(), + clap::error::ErrorKind::ArgumentConflict + ); + } else { + result.unwrap(); + } + assert!(!args.command.is_write_command()); + } + for args in [ + vec!["chctl", "cloud", "access", "--help"], + vec!["chctl", "cloud", "access", "roles", "--help"], + ] { + assert_eq!( + Cli::try_parse_from(args).err().unwrap().kind(), + clap::error::ErrorKind::DisplayHelp + ); + } + assert!(Cli::try_parse_from(["chctl", "cloud", "org", "list", "--org=id"]).is_err()); + assert!( + Cli::try_parse_from(["chctl", "cloud", "access", "roles", "--purpose=test"]).is_err() + ); + } + + #[test] + fn access_organization_selectors_validate_original_command_depths() { + use clap::{CommandFactory, FromArgMatches}; + fn validate(args: &[&str]) -> Result<(), clap::Error> { + let argv: Vec = std::iter::once("chctl") + .chain(args.iter().copied()) + .map(Into::into) + .collect(); + let mut command = Cli::command(); + let matches = command.try_get_matches_from_mut(&argv)?; + let cli = Cli::from_arg_matches(&matches)?; + let Commands::Cloud(args) = cli.command else { + panic!("cloud expected") + }; + args.validate_access_selectors(&argv) + } + for args in [ + vec!["cloud", "access", "request", "--org", "id"], + vec!["cloud", "access", "request", "--org=id", "--org-id=id"], + vec!["cloud", "access", "--org=id", "request", "--org=id"], + vec!["cloud", "access", "--org=id", "request"], + vec!["cloud", "--org-id=id", "access", "request", "--org=id"], + vec!["cloud", "--org-id=id", "access", "request", "--org-id=id"], + vec![ + "cloud", + "--org-name=name", + "access", + "request", + "--org-name=name", + ], + vec![ + "cloud", + "access", + "request", + "--purpose=--org=other", + "--org=id", + ], + vec![ + "cloud", + "access", + "request", + "--purpose", + "text --org=other", + "--org=id", + ], + vec!["cloud", "access", "request", "--org=id", "--"], + vec![ + "cloud", + "--json", + "--url=http://localhost:1/v1", + "--org-id=id", + "access", + "request", + "--org=id", + ], + vec![ + "cloud", + "access", + "request", + "--json", + "--url=http://localhost:1/v1", + "--org=id", + ], + vec!["cloud", "--org-id=first", "org", "list", "--org-id=second"], + ] { + validate(&args).unwrap_or_else(|error| panic!("{args:?}: {error}")); + } + for args in [ + vec![ + "cloud", + "access", + "request", + "--org=first", + "--org-id=second", + ], + vec!["cloud", "access", "request", "--org=first", "--org=first"], + vec![ + "cloud", + "--org-id=first", + "access", + "request", + "--org-id=second", + ], + vec![ + "cloud", "access", "--org", "first", "request", "--org", "second", + ], + vec![ + "cloud", + "--org-id=first", + "access", + "request", + "--org=second", + ], + vec![ + "cloud", + "access", + "--org=first", + "request", + "--org-id=second", + ], + vec![ + "cloud", + "--org-name=first", + "access", + "request", + "--org-name=second", + ], + vec![ + "cloud", + "--org-name=same", + "access", + "request", + "--org=same", + ], + vec![ + "cloud", + "--org-id=same", + "access", + "request", + "--org-name=same", + ], + vec![ + "cloud", + "access", + "--org=same", + "request", + "--org-name=same", + ], + ] { + let error = validate(&args).expect_err("conflict"); + assert_eq!( + error.kind(), + clap::error::ErrorKind::ArgumentConflict, + "{args:?}: {error}" + ); + assert_eq!(error.exit_code(), 2); + } + for args in [ + vec!["cloud", "access", "--help"], + vec!["cloud", "access", "request", "--help"], + ] { + assert_eq!( + validate(&args).unwrap_err().kind(), + clap::error::ErrorKind::DisplayHelp + ); + } + assert!(validate(&["cloud", "access", "request", "--", "--org=id"]).is_err()); + assert!(validate(&["cloud", "org", "list", "--org=id"]).is_err()); + } + + #[test] + fn request_flags_drop_agent_fields_and_validate_lengths_in_characters() { + for flag in ["--tool", "--version", "--session-id"] { + assert!( + Cli::try_parse_from(["chctl", "cloud", "access", "request", flag, "x"]).is_err(), + "{flag}" + ); + } + assert!( + parse(&["chctl", "cloud", "access", "request"]) + .validate() + .is_ok() + ); + for (flag, max) in [("--purpose", 200), ("--key-name", 100)] { + for (length, ok) in [(0, false), (1, true), (max, true), (max + 1, false)] { + // Multi-byte characters: the limit counts characters, not bytes. + let value = "é".repeat(length); + let args = parse(&["chctl", "cloud", "access", "request", flag, &value]); + assert_eq!(args.validate().is_ok(), ok, "{flag} {length}"); + } + } + } + + #[test] + fn pkce_verifier_is_unreserved_and_challenge_matches_rfc7636_vector() { + // RFC 7636 appendix B. + assert_eq!( + s256_challenge("dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"), + "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM" + ); + let pkce = generate_pkce(); + assert_eq!(pkce.challenge, s256_challenge(&pkce.verifier)); + assert_eq!(pkce.challenge.len(), 43); + // 32 random bytes base64url-encode (no pad) to 43 chars. + assert_eq!(pkce.verifier.len(), 43); + assert!( + pkce.verifier + .bytes() + .all(|c| c.is_ascii_alphanumeric() || b"-._~".contains(&c)) + ); + } + + #[test] + fn pkce_and_state_are_unique_per_call() { + assert_ne!(generate_pkce().verifier, generate_pkce().verifier); + assert_ne!(generate_state(), generate_state()); + } + + #[test] + fn split_target_separates_path_and_query() { + assert_eq!( + split_target("/callback?code=a&state=b"), + ("/callback", "code=a&state=b") + ); + assert_eq!(split_target("/callback"), ("/callback", "")); + } + + #[test] + fn parse_query_url_decodes_values() { + let params = parse_query("code=ab%20cd&state=xyz"); + assert_eq!(params.get("code").map(String::as_str), Some("ab cd")); + assert_eq!(params.get("state").map(String::as_str), Some("xyz")); + assert!(parse_query("").is_empty()); + } + + fn keys(value: &serde_json::Value) -> Vec { + let mut keys: Vec<_> = value.as_object().unwrap().keys().cloned().collect(); + keys.sort(); + keys + } + + #[test] + fn create_body_is_flat_and_omits_absent_optional_fields() { + let minimal = CreateAccessRequestBody { + redirect_uri: "http://127.0.0.1:1234/callback", + state: "state", + code_challenge: "challenge", + code_challenge_method: "S256", + requested_role_ids: None, + key_name: None, + purpose: None, + }; + assert_eq!( + serde_json::to_value(&minimal).unwrap(), + serde_json::json!({ + "redirectUri": "http://127.0.0.1:1234/callback", + "state": "state", + "codeChallenge": "challenge", + "codeChallengeMethod": "S256" + }) + ); + let roles = vec!["21111111-1111-1111-9999-000000000007".to_string()]; + let maximal = CreateAccessRequestBody { + requested_role_ids: Some(&roles), + key_name: Some("agent-key"), + purpose: Some("ci"), + ..minimal + }; + let value = serde_json::to_value(&maximal).unwrap(); + assert_eq!( + keys(&value), + [ + "codeChallenge", + "codeChallengeMethod", + "keyName", + "purpose", + "redirectUri", + "requestedRoleIds", + "state" + ] + ); + assert_eq!(value["purpose"], "ci"); + assert_eq!(value["keyName"], "agent-key"); + assert_eq!(value["requestedRoleIds"], serde_json::json!(roles)); + } + + #[test] + fn token_body_carries_only_code_verifier_and_redirect_uri() { + let body = TokenBody { + code: "code", + code_verifier: "verifier", + redirect_uri: "http://[::1]:1/callback", + }; + assert_eq!( + keys(&serde_json::to_value(&body).unwrap()), + ["code", "codeVerifier", "redirectUri"] + ); + } + + #[test] + fn request_is_classified_read_only() { + // OAuth (read-only) identity is the intended credential for filing. + assert!( + !AccessCommands::Request(parse(["chctl", "cloud", "access", "request"].as_slice())) + .is_write() + ); + } + + fn unwrap_result(body: &str) -> T { + serde_json::from_str::>(body) + .expect("deserialize envelope") + .result + } + + #[test] + fn file_response_reads_payload_from_result_envelope() { + // `/v1` responses wrap the payload: { "result": , "requestId": ... }. + let created: CreateAccessRequestResponse = unwrap_result( + r#"{ + "result": { + "requestId": "req-1", + "status": "pending", + "approvalUrl": "https://console.example.com/approve/req-1", + "expiresAt": 1739000000000 + }, + "requestId": "corr-1" + }"#, + ); + assert_eq!(created.request_id, "req-1"); + assert_eq!(created.status.as_deref(), Some("pending")); + assert_eq!( + created.approval_url, + "https://console.example.com/approve/req-1" + ); + // expiresAt is epoch millis (a number), not a string. + assert_eq!(created.expires_at, Some(1_739_000_000_000)); + } + + #[test] + fn token_response_reads_key_secret_and_expiry_from_result_envelope() { + let issued: TokenResponse = unwrap_result( + r#"{ + "result": { "keyId": "mgmt-1", "key": "PUBLICKEY", "secret": "SH_secret", "keyExpiresAt": 1794231456974 }, + "requestId": "corr-4" + }"#, + ); + assert_eq!(issued.key_id, "mgmt-1"); + assert_eq!(issued.key, "PUBLICKEY"); + assert_eq!(issued.secret, "SH_secret"); + assert_eq!(issued.key_expires_at, Some(1_794_231_456_974)); + let without: TokenResponse = + unwrap_result(r#"{"result":{"keyId":"k","key":"k","secret":"s"}}"#); + assert_eq!(without.key_expires_at, None); + } +} diff --git a/crates/clickhousectl/src/cloud/cli.rs b/crates/clickhousectl/src/cloud/cli.rs index 59aae8a3..736d7227 100644 --- a/crates/clickhousectl/src/cloud/cli.rs +++ b/crates/clickhousectl/src/cloud/cli.rs @@ -1,3 +1,5 @@ +#[cfg(feature = "experimental-access-negotiation")] +pub(crate) use crate::cloud::access::AccessCommands; pub(crate) use crate::cloud::activity::ActivityCommands; pub(crate) use crate::cloud::api_keys::KeyCommands; pub(crate) use crate::cloud::auth::AuthCommands; @@ -48,6 +50,75 @@ pub struct CloudArgs { } impl CloudArgs { + /// Reparse only access invocations without selector propagation so clap + /// cannot erase conflicting values supplied at different command depths. + #[cfg(feature = "experimental-access-negotiation")] + pub fn validate_access_selectors( + &self, + argv: &[std::ffi::OsString], + ) -> Result<(), clap::Error> { + if !matches!(self.command, CloudCommands::Access { .. }) { + return Ok(()); + } + fn without_selector_globals( + mut command: clap::Command, + inherited: &[clap::Arg], + ) -> clap::Command { + for arg in inherited { + if !command + .get_arguments() + .any(|local| local.get_id() == arg.get_id()) + { + command = command.arg(arg.clone()); + } + } + let selectors: Vec<_> = command + .get_arguments() + .filter(|arg| { + ["org", "org_id", "org_name"].contains(&arg.get_id().as_str()) + && arg.is_global_set() + }) + .cloned() + .collect(); + for arg in &selectors { + command = command.mut_arg(arg.get_id().clone(), |arg| arg.global(false)); + } + for child in command.get_subcommands_mut() { + *child = without_selector_globals(child.clone(), &selectors); + } + command + } + // Never mutate a built clap command: its cached parser indexes would + // describe the old globals. Reuse fresh derive definitions instead. + use clap::CommandFactory; + let mut validation = without_selector_globals(crate::cli::Cli::command(), &[]); + let matches = validation.try_get_matches_from_mut(argv)?; + let mut current = &matches; + let mut selected: Option<(&str, &str)> = None; + loop { + for id in ["org", "org_id", "org_name"] { + if current.try_get_one::(id).ok().flatten().is_none() + || current.value_source(id) != Some(clap::parser::ValueSource::CommandLine) + { + continue; + } + let value = current.get_one::(id).expect("explicit selector"); + let kind = if id == "org_name" { "name" } else { "id" }; + if selected.is_some_and(|previous| previous != (kind, value.as_str())) { + return Err(validation.error( + clap::error::ErrorKind::ArgumentConflict, + "Conflicting organization selectors: use one organization ID (--org or --org-id) or one exact --org-name", + )); + } + selected = Some((kind, value)); + } + match current.subcommand() { + Some((_, child)) => current = child, + None => return Ok(()), + } + } + } + /// Clap validates conflicts before propagating globals from other depths. pub fn has_organization_selector_conflict(&self) -> bool { self.org_id.is_some() && self.org_name.is_some() @@ -104,6 +175,26 @@ pub enum CloudCommands { command: AuthCommands, }, + /// Discover roles and request scoped API keys + #[cfg(feature = "experimental-access-negotiation")] + #[command(after_help = "\ +CONTEXT FOR AGENTS: + Requires user OAuth identity from `cloud auth login`, even when an API key is saved. + Discover assignable roles with `cloud access roles`; policies describe current authority. + Request a scoped key with `cloud access request --perms role:`; a human approves it. + Approve in a browser on this machine; it redirects to a local listener. + The approval URL goes to stderr. The issued key is short-lived; see keyExpiresAt. + API URL: explicit --url, then saved OAuth login environment, then the normal Cloud default. + Exactly one user organization is selected automatically; otherwise choose --org or --org-name. + Organization IDs: `cloud org list --json`. --org-id remains supported.")] + Access { + /// Organization ID (conflicts with --org-name) + #[arg(long, global = true, value_name = "ID", conflicts_with = "org_name")] + org: Option, + #[command(subcommand)] + command: AccessCommands, + }, + /// Manage organizations #[command(after_help = "\ CONTEXT FOR AGENTS: @@ -273,6 +364,8 @@ impl CloudCommands { pub fn is_write_command(&self) -> bool { match self { CloudCommands::Auth { command } => command.is_write(), + #[cfg(feature = "experimental-access-negotiation")] + CloudCommands::Access { command, .. } => command.is_write(), CloudCommands::Org { command } => command.is_write(), CloudCommands::Service { command } => command.is_write(), CloudCommands::Backup { command } => command.is_write(), diff --git a/crates/clickhousectl/src/cloud/client.rs b/crates/clickhousectl/src/cloud/client.rs index 6df5cb08..e7741f17 100644 --- a/crates/clickhousectl/src/cloud/client.rs +++ b/crates/clickhousectl/src/cloud/client.rs @@ -144,8 +144,27 @@ impl From for CloudError { pub type Result = std::result::Result; enum AuthMode { + Basic { + key: String, + secret: String, + }, + // The token is read only by `request_auth` (experimental-access-negotiation), + // but both builds keep the same variant shape. + #[cfg_attr(not(feature = "experimental-access-negotiation"), allow(dead_code))] + Bearer { + token: String, + }, +} + +/// The authentication a bespoke control-plane request (one made with a plain +/// `reqwest` client, outside the typed Cloud API client) should carry. Mirrors +/// [`AuthMode`] but owns its values so callers can build request headers after +/// the borrow on the client ends. Used by the access-request PKCE flow +/// (`cloud access request`), which talks to endpoints the library does not model. +#[cfg(feature = "experimental-access-negotiation")] +pub(crate) enum RequestAuth { Basic { key: String, secret: String }, - Bearer, + Bearer { token: String }, } /// The resolved credential source that won precedence for a `CloudClient`. @@ -855,6 +874,57 @@ impl CloudClient { Self::from_resolved_auth(resolved, Some(timeout)) } + /// Access negotiation identifies the user, never a previously issued API key. + #[cfg(feature = "experimental-access-negotiation")] + pub(super) async fn for_access(url_override: Option<&str>) -> Result { + // Suppress the normal refresh warning's API-key fallback advice: this + // lane requires OAuth even when other credentials are configured. + crate::cloud::auth::ensure_fresh_tokens(true) + .await + .map_err(|error| { + CloudError::auth(format!( + "Unable to refresh OAuth identity: {error}. Run `clickhousectl cloud auth login` to re-authenticate." + )) + })?; + Self::from_access_tokens( + crate::cloud::auth::load_tokens() + .map_err(|_| CloudError::auth(crate::cloud::auth::OAUTH_LOGIN_REQUIRED))?, + url_override, + // Membership and assignable-role discovery use the typed client + // directly, outside the handshake's `operation` wrapper, so this + // client carries the same 30-second access-operation bound; a + // server holding a response open must not stall either command. + Some(crate::cloud::access::OPERATION_TIMEOUT), + ) + } + + #[cfg(feature = "experimental-access-negotiation")] + fn from_access_tokens( + tokens: Option, + url_override: Option<&str>, + timeout: Option, + ) -> Result { + let tokens = tokens + .filter(crate::cloud::auth::is_token_valid) + .ok_or_else(|| { + CloudError::auth( + "Access negotiation requires OAuth identity. Run `clickhousectl cloud auth login` to authenticate. API keys cannot be used for access negotiation.", + ) + })?; + Self::from_resolved_auth( + ResolvedAuth { + creds: ResolvedCreds::Bearer { + token: tokens.access_token, + }, + source: AuthSource::OAuthTokens, + base_url: crate::cloud::auth::normalize_api_url( + url_override.unwrap_or(&tokens.api_url), + ), + }, + timeout, + ) + } + fn from_resolved_auth( resolved: ResolvedAuth, timeout: Option, @@ -879,8 +949,8 @@ impl CloudClient { AuthMode::Basic { key, secret }, ), ResolvedCreds::Bearer { token } => ( - clickhouse_cloud_api::Client::with_http_client_bearer(http, lib_url, token), - AuthMode::Bearer, + clickhouse_cloud_api::Client::with_http_client_bearer(http, lib_url, token.clone()), + AuthMode::Bearer { token }, ), }; @@ -926,7 +996,7 @@ impl CloudClient { /// Returns true if the client is using OAuth Bearer token authentication. /// Bearer auth is read-only and cannot perform write operations. pub fn is_bearer_auth(&self) -> bool { - matches!(&self.auth_mode, AuthMode::Bearer) + matches!(&self.auth_mode, AuthMode::Bearer { .. }) } /// The active API key pair, for authenticating directly to a Query API @@ -934,7 +1004,23 @@ impl CloudClient { pub(crate) fn basic_auth_credentials(&self) -> Option<(&str, &str)> { match &self.auth_mode { AuthMode::Basic { key, secret } => Some((key, secret)), - AuthMode::Bearer => None, + AuthMode::Bearer { .. } => None, + } + } + + /// The resolved credentials in a form a bespoke `reqwest` request can carry, + /// for control-plane endpoints the typed library client does not model (the + /// access-request PKCE flow). Clones so the value outlives the client borrow. + #[cfg(feature = "experimental-access-negotiation")] + pub(crate) fn request_auth(&self) -> RequestAuth { + match &self.auth_mode { + AuthMode::Basic { key, secret } => RequestAuth::Basic { + key: key.clone(), + secret: secret.clone(), + }, + AuthMode::Bearer { token } => RequestAuth::Bearer { + token: token.clone(), + }, } } @@ -1270,6 +1356,82 @@ mod tests { const DEFAULT_LIB_BASE_URL: &str = "https://api.clickhouse.cloud"; + /// The access client's per-request bound must actually reach reqwest and + /// classify as a timeout: a response held open past the bound fails with + /// `FailureKind::Timeout` instead of stalling. `for_access` supplies + /// `access::OPERATION_TIMEOUT`; a short bound here keeps the test fast. + #[tokio::test] + #[cfg(feature = "experimental-access-negotiation")] + async fn access_client_applies_the_access_operation_bound_to_discovery() { + use std::time::Duration; + use wiremock::matchers::{method, path}; + use wiremock::{Mock, MockServer, ResponseTemplate}; + let server = MockServer::start().await; + Mock::given(method("GET")) + .and(path("/v1/organizations")) + .respond_with(ResponseTemplate::new(200).set_delay(Duration::from_secs(60))) + .mount(&server) + .await; + let tokens = serde_json::from_value(serde_json::json!({ + "access_token": "test-token", "refresh_token": "unused", + "expires_at": 4102444800_i64, + "api_url": format!("{}/v1", server.uri()), + "auth_config": {"auth_url": server.uri(), "client_id": "test-client"}, + })) + .unwrap(); + let client = + CloudClient::from_access_tokens(Some(tokens), None, Some(Duration::from_millis(300))) + .unwrap(); + let error = client + .api() + .organization_get_list(None, None) + .await + .map(|_| ()) + .map_err(|error| client.convert_error(error)) + .unwrap_err(); + assert!( + matches!( + error.failure.as_ref().map(|f| &f.kind), + Some(crate::failure::FailureKind::Timeout) + ), + "expected a timeout classification: {error}" + ); + } + + #[test] + #[cfg(feature = "experimental-access-negotiation")] + fn access_client_uses_explicit_or_saved_api_base() { + // Records are complete: both `api_url` and `auth_config` are required + // at deserialization (rejection covered by the authentication tests), + // and endpoint selection only runs on a loaded record. + for (saved, explicit, expected) in [ + ( + "https://saved.example/v1/", + None, + "https://saved.example/v1", + ), + ( + "https://saved.example/v1", + Some("http://localhost:2023/"), + "http://localhost:2023/v1", + ), + (DEFAULT_BASE_URL, None, DEFAULT_BASE_URL), + ] { + let value = serde_json::json!({ + "access_token": "test-token", "refresh_token": "unused", + "expires_at": 4102444800_i64, + "api_url": saved, + "auth_config": {"auth_url": "https://auth.example.com", "client_id": "test-client"}, + }); + let tokens = serde_json::from_value(value).unwrap(); + let client = CloudClient::from_access_tokens(Some(tokens), explicit, None).unwrap(); + assert_eq!(client.base_url(), expected); + assert_eq!(client.auth_source(), AuthSource::OAuthTokens); + assert!(client.is_bearer_auth()); + assert!(client.basic_auth_credentials().is_none()); + } + } + #[test] fn typed_udf_dependency_error_keeps_message_and_http_classification() { let error = @@ -1350,7 +1512,9 @@ mod tests { organization_id: None, organization_name: None, resolved_organization_id: tokio::sync::OnceCell::new(), - auth_mode: AuthMode::Bearer, + auth_mode: AuthMode::Bearer { + token: "test_token".into(), + }, auth_source: AuthSource::OAuthTokens, base_url: DEFAULT_BASE_URL.to_string(), }; @@ -1613,7 +1777,9 @@ mod tests { organization_id: None, organization_name: None, resolved_organization_id: tokio::sync::OnceCell::new(), - auth_mode: AuthMode::Bearer, + auth_mode: AuthMode::Bearer { + token: "test_token".into(), + }, auth_source: AuthSource::OAuthTokens, base_url: DEFAULT_BASE_URL.to_string(), }; diff --git a/crates/clickhousectl/src/cloud/mod.rs b/crates/clickhousectl/src/cloud/mod.rs index 1928039d..69045cf9 100644 --- a/crates/clickhousectl/src/cloud/mod.rs +++ b/crates/clickhousectl/src/cloud/mod.rs @@ -1,3 +1,5 @@ +#[cfg(feature = "experimental-access-negotiation")] +pub mod access; pub mod activity; pub mod api_keys; pub mod auth; @@ -71,6 +73,21 @@ pub async fn run(args: CloudArgs, json: bool) -> Result<()> { ) .await; } + // Access negotiation refreshes and uses only the OAuth user identity, + // bypassing normal API-key precedence and the ordinary OAuth write gate. + #[cfg(feature = "experimental-access-negotiation")] + CloudCommands::Access { command, org } => { + return access::run( + command, + args.url.as_deref(), + org.or(args.org_id), + args.org_name, + args.debug, + json, + ) + .await + .map_err(cloud_error_to_top_level); + } command => command, }; @@ -190,6 +207,8 @@ fn cloud_error_to_top_level(e: CloudError) -> Error { async fn dispatch(client: &CloudClient, command: CloudCommands, json: bool) -> client::Result<()> { match command { CloudCommands::Auth { command } => auth::run_with_client(client, command, json).await, + #[cfg(feature = "experimental-access-negotiation")] + CloudCommands::Access { .. } => unreachable!("handled above"), CloudCommands::Org { command } => organizations::run_org(client, command, json).await, CloudCommands::Service { command } => services::run(client, command, json).await, CloudCommands::Member { command } => organizations::run_member(client, command, json).await, diff --git a/crates/clickhousectl/src/cloud/permissions.rs b/crates/clickhousectl/src/cloud/permissions.rs index 1b7079b7..040c3226 100644 --- a/crates/clickhousectl/src/cloud/permissions.rs +++ b/crates/clickhousectl/src/cloud/permissions.rs @@ -122,6 +122,12 @@ impl Declaration { } fn declarations() -> impl Iterator { + // Feature-gated declarations stay a compile-time constant in both builds + // so the iterator's shape is feature-agnostic. + #[cfg(feature = "experimental-access-negotiation")] + const ACCESS_DECLARATIONS: &[&[Declaration]] = &[super::access::PERMISSIONS]; + #[cfg(not(feature = "experimental-access-negotiation"))] + const ACCESS_DECLARATIONS: &[&[Declaration]] = &[]; [ super::activity::PERMISSIONS, super::api_keys::PERMISSIONS, @@ -138,6 +144,7 @@ fn declarations() -> impl Iterator { super::udfs::PERMISSIONS, ] .into_iter() + .chain(ACCESS_DECLARATIONS.iter().copied()) .flatten() } diff --git a/crates/clickhousectl/src/main.rs b/crates/clickhousectl/src/main.rs index aa4adcf3..a4ab6a70 100644 --- a/crates/clickhousectl/src/main.rs +++ b/crates/clickhousectl/src/main.rs @@ -91,18 +91,26 @@ async fn run_main() { let cli = Cli::from_arg_matches(&matches) .expect("Cli::from_arg_matches must accept matches from Cli::command()"); let read_only_telemetry_status = is_read_only_telemetry_status(&cli.command); - let run_result = match validate_post_parse(&cli, &mut cmd) { - Ok(()) => run_parsed(cli, read_only_telemetry_status).await, - Err(e) => { - stdout::record(e.print()); - RunOutcome { - exit_code: e.exit_code(), - is_child_exit: false, - defer_telemetry_notice: false, - local_failure: None, - } - } + #[cfg(feature = "experimental-access-negotiation")] + let access_validation = match &cli.command { + Commands::Cloud(args) => args.validate_access_selectors(&argv), + _ => Ok(()), }; + #[cfg(not(feature = "experimental-access-negotiation"))] + let access_validation = Ok::<(), clap::Error>(()); + let run_result = + match access_validation.and_then(|()| validate_post_parse(&cli, &mut cmd)) { + Ok(()) => run_parsed(cli, read_only_telemetry_status).await, + Err(e) => { + stdout::record(e.print()); + RunOutcome { + exit_code: e.exit_code(), + is_child_exit: false, + defer_telemetry_notice: false, + local_failure: None, + } + } + }; let RunOutcome { exit_code, is_child_exit, @@ -226,6 +234,21 @@ fn validate_post_parse(cli: &Cli, cmd: &mut clap::Command) -> std::result::Resul )); } + #[cfg(feature = "experimental-access-negotiation")] + if let cloud::cli::CloudCommands::Access { + command: cloud::cli::AccessCommands::Request(request), + .. + } = &args.command + && let Err(message) = request.requested_role_ids() + { + let command = cmd + .find_subcommand_mut("cloud") + .and_then(|cloud| cloud.find_subcommand_mut("access")) + .and_then(|access| access.find_subcommand_mut("request")) + .expect("cloud access request command must exist"); + return Err(command.error(ErrorKind::ValueValidation, message)); + } + // Login's credentials are global arguments. Validate after propagation so // a pair split across command levels remains valid. if let cloud::cli::CloudCommands::Auth { command } = &args.command diff --git a/crates/clickhousectl/tests/cloud/access.rs b/crates/clickhousectl/tests/cloud/access.rs new file mode 100644 index 00000000..683892ed --- /dev/null +++ b/crates/clickhousectl/tests/cloud/access.rs @@ -0,0 +1,1400 @@ +//! `cloud access`, the experimental access-negotiation flow (src/cloud/access.rs). Compiled only +//! with `--features experimental-access-negotiation`. +#![allow(clippy::too_many_lines)] + +use std::path::{Path, PathBuf}; +use std::process::{Command, Stdio}; + +use serde_json::Value; +use wiremock::matchers::{header, method, path, query_param}; +use wiremock::{Mock, MockServer, ResponseTemplate}; + +use crate::support::*; +// ── Access negotiation's OAuth-only identity lane ────────────────────────── + +fn access_roles_command(dir: &Path, json: bool) -> Command { + let mut command = Command::new(clickhousectl_binary()); + command + .env_clear() + .env("DO_NOT_TRACK", "1") + .env("HOME", dir.join("home")) + .current_dir(dir) + .args(["cloud", "access", "roles"]); + if json { + command.arg("--json"); + } + command +} + +fn assignable_roles_fixture() -> Value { + serde_json::json!([ + {"id": "00000000-0000-0000-0000-000000000001", "name": "System reader", "type": "system", "policies": [ + {"allowDeny": "ALLOW", "permissions": ["service:view"], "resources": ["*"], "tags": {"roleV2": "sql-console-readonly"}}, + {"allowDeny": "DENY", "permissions": ["service:delete"], "resources": ["instance/private"]} + ]}, + {"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"]}}, + {"allowDeny": "future-effect", "permissions": [], "resources": [], "tags": {"roleV2": "future-role", "grants": []}} + ]}, + {"id": "22222222-2222-2222-2222-222222222222", "name": "Future type", "type": "future-type", "policies": []} + ]) +} + +#[tokio::test] +async fn access_roles_outputs_complete_oauth_menu_with_selected_organization() { + const ORG: &str = "11111111-2222-3333-4444-555555555555"; + for selector in ["explicit", "auto", "name"] { + for json in [false, true] { + let server = MockServer::start().await; + Mock::given(method("GET")) + .and(path("/v1/organizations")) + .and(header("authorization", "Bearer test-bearer-token")) + .respond_with(ResponseTemplate::new(200).set_body_json( + serde_json::json!({"result": [{"id": ORG, "name": "Selected org"}]}), + )) + .expect(if selector == "explicit" { 0 } else { 1 }) + .mount(&server) + .await; + let roles = assignable_roles_fixture(); + Mock::given(method("GET")).and(path(format!("/v1/organizations/{ORG}/roles"))) + .and(header("authorization", "Bearer test-bearer-token")) + .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({"result": roles, "requestId": "correlation", "nextCursor": "must-not-page"}))) + .expect(1).mount(&server).await; + let dir = tempfile::tempdir().unwrap(); + let tokens = access_credentials(dir.path()); + write_oauth_tokens(&tokens, &server.uri()); + let mut command = access_roles_command(dir.path(), json); + let debug = selector != "explicit"; + if debug { + command.arg("--debug"); + } + if selector == "explicit" { + command.args(["--org", ORG]); + } + if selector == "name" { + command.args(["--org-name", "Selected org"]); + } + let output = command.output().unwrap(); + assert_eq!( + output.status.code(), + Some(0), + "{}", + String::from_utf8_lossy(&output.stderr) + ); + assert_access_output_has_no_credentials(&output); + if debug { + assert_access_debug_diagnostics(&output, &server.uri()); + } else { + assert!(!String::from_utf8_lossy(&output.stderr).contains("[debug]")); + } + if json { + assert_eq!( + serde_json::from_slice::(&output.stdout).unwrap(), + roles + ); + } else { + let text = String::from_utf8_lossy(&output.stdout); + for value in [ + ORG, + "System reader", + "Custom SQL", + "DENY", + "instance/private", + "Unknown effect (future-effect)", + "Unknown (future-type)", + "00000000-0000-0000-0000-000000000001", + ] { + assert!(text.contains(value), "missing {value}: {text}"); + } + } + assert_eq!( + server.received_requests().await.unwrap().len(), + if selector == "explicit" { 1 } else { 2 } + ); + } + } +} + +#[tokio::test] +async fn access_roles_empty_and_optional_tags_are_valid() { + for roles in [ + serde_json::json!([]), + serde_json::json!([ + {"id": "00000000-0000-0000-0000-000000000001", "name": "empty", "type": "system", "policies": [ + {"allowDeny": "DENY", "permissions": [], "resources": [], "tags": null}, + {"allowDeny": "ALLOW", "permissions": [], "resources": [], "tags": {"grants": null, "roleV2": null}} + ]} + ]), + ] { + for json in [false, true] { + let server = MockServer::start().await; + Mock::given(method("GET")) + .and(path("/v1/organizations/org/roles")) + .respond_with( + ResponseTemplate::new(200).set_body_json(serde_json::json!({"result": roles})), + ) + .expect(1) + .mount(&server) + .await; + let dir = tempfile::tempdir().unwrap(); + write_oauth_tokens(&access_credentials(dir.path()), &server.uri()); + let output = access_roles_command(dir.path(), json) + .args(["--org", "org"]) + .output() + .unwrap(); + assert_eq!( + output.status.code(), + Some(0), + "{}", + String::from_utf8_lossy(&output.stderr) + ); + if json { + let expected: Vec = + serde_json::from_value(roles.clone()).unwrap(); + assert_eq!( + serde_json::from_slice::(&output.stdout).unwrap(), + serde_json::to_value(expected).unwrap() + ); + } else if roles.as_array().unwrap().is_empty() { + assert!(String::from_utf8_lossy(&output.stdout).contains("No assignable roles")); + } + } + } +} + +#[tokio::test] +async fn access_roles_rejects_incomplete_menus_before_any_success_output() { + let fixture = assignable_roles_fixture(); + let mut invalid = vec![ + serde_json::json!({}), + serde_json::json!({"result": null}), + serde_json::json!({"result": fixture, "error": "envelope failure"}), + serde_json::json!({"result": fixture, "status": 500}), + serde_json::json!({"result": {"roles": []}}), + ]; + for field in ["id", "name", "type", "policies"] { + for null in [false, true] { + let mut roles = fixture.clone(); + if null { + roles[1][field] = Value::Null; + } else { + roles[1].as_object_mut().unwrap().remove(field); + } + invalid.push(serde_json::json!({"result": roles})); + } + } + for field in ["allowDeny", "permissions", "resources"] { + for null in [false, true] { + let mut roles = fixture.clone(); + if null { + roles[1]["policies"][0][field] = Value::Null; + } else { + roles[1]["policies"][0] + .as_object_mut() + .unwrap() + .remove(field); + } + invalid.push(serde_json::json!({"result": roles})); + } + } + let mut roles = fixture.clone(); + roles[1]["id"] = "not-a-uuid".into(); + invalid.push(serde_json::json!({"result": roles})); + for response in invalid { + for json in [false, true] { + let server = MockServer::start().await; + Mock::given(method("GET")) + .and(path("/v1/organizations/org/roles")) + .and(header("authorization", "Bearer test-bearer-token")) + .respond_with(ResponseTemplate::new(200).set_body_json(response.clone())) + .expect(1) + .mount(&server) + .await; + let dir = tempfile::tempdir().unwrap(); + write_oauth_tokens(&access_credentials(dir.path()), &server.uri()); + let output = access_roles_command(dir.path(), json) + .args(["--org", "org"]) + .output() + .unwrap(); + assert_eq!( + output.status.code(), + Some(1), + "{response}: {}", + String::from_utf8_lossy(&output.stderr) + ); + assert!( + output.stdout.is_empty(), + "partial success: {}", + String::from_utf8_lossy(&output.stdout) + ); + assert!(!output.stderr.is_empty()); + assert_access_output_has_no_credentials(&output); + assert_eq!(server.received_requests().await.unwrap().len(), 1); + } + } +} + +#[tokio::test] +async fn access_roles_preserves_server_denials_without_fallback() { + for (status, message, exit) in [ + (401, "non-CLI identity", 4), + // A 403 is not an auth failure (#1225). + (403, "cross-org denial", 1), + (400, "RBAC prerequisite", 1), + (500, "upstream error", 1), + ] { + for json in [false, true] { + let server = MockServer::start().await; + Mock::given(method("GET")) + .and(path("/v1/organizations/other-org/roles")) + .and(header("authorization", "Bearer test-bearer-token")) + .respond_with( + ResponseTemplate::new(status) + .set_body_json(serde_json::json!({"error": message})), + ) + .expect(1) + .mount(&server) + .await; + let dir = tempfile::tempdir().unwrap(); + write_oauth_tokens(&access_credentials(dir.path()), &server.uri()); + let output = access_roles_command(dir.path(), json) + .args(["--org", "other-org"]) + .output() + .unwrap(); + assert_eq!(output.status.code(), Some(exit)); + assert!(output.stdout.is_empty()); + assert!(String::from_utf8_lossy(&output.stderr).contains(message)); + assert_eq!(server.received_requests().await.unwrap().len(), 1); + } + } +} + +#[tokio::test] +async fn access_roles_requires_and_refreshes_oauth_despite_basic_credentials() { + for state in ["missing", "unrefreshable", "refresh"] { + let issuer = MockServer::start().await; + let target = MockServer::start().await; + let dir = tempfile::tempdir().unwrap(); + let tokens = access_credentials(dir.path()); + if state != "missing" { + std::fs::write(tokens.join("tokens.json"), serde_json::to_vec(&serde_json::json!({ + "access_token": "test-bearer-token", "refresh_token": "refresh-secret", "expires_at": 1, + "api_url": format!("{}/v1", issuer.uri()), + "auth_config": {"auth_url": issuer.uri(), "client_id": "test-client"} + })).unwrap()).unwrap(); + Mock::given(method("POST")).and(path("/oauth/token")) + .respond_with(if state == "refresh" { + ResponseTemplate::new(200).set_body_json(serde_json::json!({"access_token": "refreshed-bearer-token", "expires_in": 3600, "token_type": "Bearer"})) + } else { ResponseTemplate::new(401).set_body_string("refresh-secret") }) + .expect(1).mount(&issuer).await; + } + Mock::given(method("GET")) + .and(path("/v1/organizations/org/roles")) + .and(header("authorization", "Bearer refreshed-bearer-token")) + .respond_with( + ResponseTemplate::new(200).set_body_json(serde_json::json!({"result": []})), + ) + .expect(if state == "refresh" { 1 } else { 0 }) + .mount(&target) + .await; + let output = access_roles_command(dir.path(), true) + .args([ + "--org", + "org", + "--url", + &target.uri(), + "--api-key", + "flag-basic-key", + "--api-secret", + "flag-basic-secret", + ]) + .env("CLICKHOUSECTL_AUTH_URL", issuer.uri()) + .env("CLICKHOUSECTL_CLIENT_ID", "test-client") + .output() + .unwrap(); + assert_eq!( + output.status.code(), + Some(if state == "refresh" { 0 } else { 4 }) + ); + assert_access_output_has_no_credentials(&output); + if state == "refresh" { + assert_eq!( + serde_json::from_slice::(&output.stdout).unwrap(), + serde_json::json!([]) + ); + } else { + assert!(output.stdout.is_empty()); + assert!(String::from_utf8_lossy(&output.stderr).contains("cloud auth login")); + } + assert_eq!( + target.received_requests().await.unwrap().len(), + usize::from(state == "refresh") + ); + } +} + +#[test] +fn access_roles_selector_conflicts_exit_usage_before_oauth() { + for args in [ + vec!["cloud", "--org-id=one", "access", "roles", "--org=two"], + vec![ + "cloud", + "--org-name=one", + "access", + "roles", + "--org-name=two", + ], + vec!["cloud", "access", "--org=one", "roles", "--org-id=two"], + vec!["cloud", "--org-name=one", "access", "roles", "--org=one"], + ] { + let dir = tempfile::tempdir().unwrap(); + access_credentials(dir.path()); + let output = Command::new(clickhousectl_binary()) + .env_clear() + .env("DO_NOT_TRACK", "1") + .env("HOME", dir.path().join("home")) + .current_dir(dir.path()) + .args(args) + .output() + .unwrap(); + assert_eq!(output.status.code(), Some(2)); + assert!(output.stdout.is_empty()); + } +} + +#[tokio::test] +async fn access_request_authorization_code_handoff_keeps_stdout_final_and_credentials_safe() { + use base64::Engine as _; + use sha2::{Digest as _, Sha256}; + const A: &str = "21111111-1111-1111-9999-000000000007"; + const B: &str = "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"; + const C: &str = "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"; + const FILE_PATH: &str = "/v1/organizations/org/accessRequests/authorizationCode"; + const TOKEN_PATH: &str = "/v1/organizations/org/accessRequests/authorizationCode/token"; + const STATUS_PATH: &str = "/v1/organizations/org/accessRequests/request-1"; + let mut tasks = Vec::new(); + for json in [false, true] { + for scenario in [ + "success", + "success-proposed", + "success-no-expiry", + "tampered-state", + "callback-no-code", + "callback-bad-code", + "callback-denied", + "create-401", + "create-403", + "server-expiry", + "pending-expired", + "timeout-env", + "timeout-flag", + "exchange-replay", + "exchange-redirect-mismatch", + "exchange-401", + "exchange-403", + "exchange-echo", + "exchange-malformed", + "exchange-empty", + "exchange-expiry-invalid", + "exchange-301", + "exchange-302", + "exchange-303", + "exchange-307", + "exchange-308", + "create-deadline-missing", + "create-envelope-error", + "create-proposal-missing", + "create-proposal-null", + "create-proposal-malformed", + "create-proposal-duplicate", + "create-proposal-oversized", + "create-proposal-mismatch", + "create-proposal-unexpected", + "grants-missing", + "grants-null", + "grants-empty", + "grants-malformed", + "grants-duplicate", + "grants-many", + ] { + tasks.push(tokio::spawn(async move { + let server = MockServer::start().await; + let dir = tempfile::tempdir().unwrap(); + let tokens = access_credentials(dir.path()); + write_oauth_tokens(&tokens, &server.uri()); + let credentials_path = dir.path().join(".clickhouse/credentials.json"); + let before = std::fs::read(&credentials_path).unwrap(); + let oauth_before = std::fs::read(tokens.join("tokens.json")).unwrap(); + // An absent local path makes the best-effort opener fail without + // launching a real browser; the test plays the browser's redirect. + let approval_url = dir.path().join("absent-browser-target").to_string_lossy().into_owned(); + let now = std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_millis() as i64; + let pending_expiry = match scenario { + "pending-expired" => 1_i64, + "server-expiry" => now + 1500, + _ => 4102444800000_i64, + }; + let proposed = scenario == "success-proposed" || scenario.starts_with("create-proposal"); + let proposal = if proposed {serde_json::json!([A, B.to_uppercase()])} else {serde_json::json!([])}; + let mut create = serde_json::json!({"result": { + "requestedRoleIds":proposal, "requestId":"request-1", "status":"pending", "approvalUrl":approval_url, "expiresAt":pending_expiry + }}); + match scenario { + "create-deadline-missing" => create["result"]["expiresAt"] = Value::Null, + "create-envelope-error" => create["error"] = serde_json::json!("secret-envelope-error"), + "create-proposal-missing" => { create["result"].as_object_mut().unwrap().remove("requestedRoleIds"); }, + "create-proposal-null" => create["result"]["requestedRoleIds"] = Value::Null, + "create-proposal-malformed" => create["result"]["requestedRoleIds"] = serde_json::json!(["secret-invalid-role"]), + "create-proposal-duplicate" => create["result"]["requestedRoleIds"] = serde_json::json!([B, B.to_uppercase()]), + "create-proposal-oversized" => create["result"]["requestedRoleIds"] = serde_json::json!((1..=101).map(|id| format!("00000000-0000-0000-0000-{id:012x}")).collect::>()), + "create-proposal-mismatch" => create["result"]["requestedRoleIds"] = serde_json::json!([B, A]), + _ => {}, + } + let filing = match scenario { + "create-401" | "create-403" => ResponseTemplate::new(scenario[7..].parse::().unwrap()).set_body_string("auth-code-secret"), + _ => ResponseTemplate::new(200).set_body_json(create), + }; + Mock::given(method("POST")).and(path(FILE_PATH)) + .and(header("authorization", "Bearer test-bearer-token")) + .respond_with(filing).expect(1).mount(&server).await; + + // Scenarios that complete the browser redirect, and those that then exchange. + let redirects = scenario.starts_with("success") || scenario.starts_with("exchange-") || scenario.starts_with("grants-") + || matches!(scenario, "tampered-state" | "callback-no-code" | "callback-bad-code" | "callback-denied"); + let exchanges = redirects && !scenario.starts_with("callback-"); + let successful = scenario.starts_with("success") || matches!(scenario, "tampered-state" | "grants-many"); + let redirect_status = scenario.strip_prefix("exchange-").and_then(|code| code.parse::().ok()) + .filter(|status| (300..400).contains(status)); + let stolen = format!("{}/stolen", server.uri()); + Mock::given(method("POST")).and(path(TOKEN_PATH)) + .and(header("authorization", "Bearer test-bearer-token")) + .respond_with(move |request: &wiremock::Request| { + let error = |status: u16, message: &str| ResponseTemplate::new(status) + .set_body_json(serde_json::json!({"error":message,"status":status,"requestId":"corr-1"})); + if let Some(status) = redirect_status { + return ResponseTemplate::new(status).insert_header("Location", stolen.as_str()); + } + match scenario { + "exchange-replay" => return error(400, "BAD_REQUEST: code already redeemed"), + "exchange-redirect-mismatch" => return error(400, "BAD_REQUEST: invalid_grant: redirect URI does not match the filed value"), + "exchange-401" => return error(401, "UNAUTHORIZED: PKCE verification failed"), + "exchange-403" => return error(403, "FORBIDDEN: access requests require permission to create API keys"), + "exchange-echo" | "exchange-malformed" => { + // Deliberately echo the submitted code and verifier. + let echoed = String::from_utf8_lossy(&request.body).to_string(); + return ResponseTemplate::new(if scenario == "exchange-echo" {401} else {200}) + .set_body_json(serde_json::json!({"error":echoed,"result":echoed})); + }, + _ => {}, + } + let mut issued = serde_json::json!({"result": { + "keyId":"issued-id", "key":"issued-key", "secret":if scenario == "exchange-empty" {""} else {"issued-secret"}, + "keyExpiresAt":1794231456974_i64, "grantedRoleIds":[B.to_uppercase(), C] + }}); + match scenario { + "success-no-expiry" => {issued["result"].as_object_mut().unwrap().remove("keyExpiresAt");}, + "exchange-expiry-invalid" => issued["result"]["keyExpiresAt"] = serde_json::json!(-1), + "grants-missing" => {issued["result"].as_object_mut().unwrap().remove("grantedRoleIds");}, + "grants-null" => issued["result"]["grantedRoleIds"] = Value::Null, + "grants-empty" => issued["result"]["grantedRoleIds"] = serde_json::json!([]), + "grants-malformed" => issued["result"]["grantedRoleIds"] = serde_json::json!(["secret-invalid-role"]), + "grants-duplicate" => issued["result"]["grantedRoleIds"] = serde_json::json!([B, B.to_uppercase()]), + "grants-many" => issued["result"]["grantedRoleIds"] = serde_json::json!((1..=101).map(|id| format!("00000000-0000-0000-0000-{id:012x}")).collect::>()), + _ => {}, + } + ResponseTemplate::new(200).set_body_json(issued) + }).expect(u64::from(exchanges)).mount(&server).await; + + let mut command = Command::new(clickhousectl_binary()); + command.env_clear().env("DO_NOT_TRACK", "1").env("HOME", dir.path().join("home")) + .env("PATH", dir.path().join("empty-path")).current_dir(dir.path()) + .args(["cloud", "access", "request", "--org", "org", "--debug"]) + .stdout(Stdio::piped()).stderr(Stdio::piped()); + if json { command.arg("--json"); } + match scenario { + "timeout-env" => { command.env("CLICKHOUSE_CLOUD_ACCESS_TIMEOUT_SECONDS", "1"); }, + "timeout-flag" => { + command.env("CLICKHOUSE_CLOUD_ACCESS_TIMEOUT_SECONDS", "invalid") + .args(["--timeout-seconds", "1"]); + }, + _ => {}, + } + if proposed && scenario != "create-proposal-unexpected" { command.args(["--perms", &format!("role:{A},role:{B}")]); } + let started = std::time::Instant::now(); + let child = command.spawn().unwrap(); + let output_task = tokio::task::spawn_blocking(move || { + let mut child = child; + let deadline = std::time::Instant::now() + std::time::Duration::from_secs(12); + while child.try_wait().unwrap().is_none() { + if std::time::Instant::now() >= deadline { + child.kill().unwrap(); + let output = child.wait_with_output().unwrap(); + panic!("request failed to terminate promptly: {}", String::from_utf8_lossy(&output.stderr)); + } + std::thread::sleep(std::time::Duration::from_millis(20)); + } + child.wait_with_output().unwrap() + }); + if redirects { + let filed = tokio::time::timeout(std::time::Duration::from_secs(5), async { + loop { + if let Some(request) = server.received_requests().await.unwrap().first() { + break serde_json::from_slice::(&request.body).unwrap(); + } + tokio::time::sleep(std::time::Duration::from_millis(10)).await; + } + }).await.unwrap(); + let redirect_uri = filed["redirectUri"].as_str().unwrap(); + let state = filed["state"].as_str().unwrap(); + let http = reqwest::Client::new(); + if scenario == "tampered-state" { + // A forged redirect is refused and the wait goes on. + let forged = http.get(redirect_uri).query(&[("code", "forged-code"), ("state", "wrong-state")]).send().await.unwrap(); + assert_eq!(forged.status().as_u16(), 400); + } + let query: Vec<(&str, &str)> = match scenario { + "callback-no-code" => vec![("state", state)], + "callback-bad-code" => vec![("code", "bad\u{1}code"), ("state", state)], + // The approval page's denial redirect (RFC 6749 §4.1.2.1). + "callback-denied" => vec![("error", "access_denied"), ("state", state)], + _ => vec![("code", "auth-code-secret"), ("state", state)], + }; + let response = http.get(redirect_uri).query(&query).send().await.unwrap(); + let expected = if matches!(scenario, "callback-no-code" | "callback-bad-code") {400} else {200}; + assert_eq!(response.status().as_u16(), expected, "{scenario}"); + } + let output = output_task.await.unwrap(); + if scenario.starts_with("timeout-") { + assert!(started.elapsed() >= std::time::Duration::from_secs(1)); + } + // A 403 is a missing permission, not missing authentication (#1225). + let expected_exit = if successful {0} else if scenario == "create-401" {4} else {1}; + let stderr = String::from_utf8_lossy(&output.stderr); + assert_eq!(output.status.code(), Some(expected_exit), "{scenario}: {stderr}"); + assert_eq!(stderr.contains(&approval_url), !scenario.starts_with("create-"), "{scenario}: {stderr}"); + assert!(!String::from_utf8_lossy(&output.stdout).contains(&approval_url)); + assert_access_output_has_no_credentials(&output); + assert_access_debug_diagnostics(&output, &server.uri()); + let combined = format!("{}{}", String::from_utf8_lossy(&output.stdout), stderr); + let expected_message = match scenario { + "callback-denied" => Some("access request denied"), + "server-expiry" | "pending-expired" => Some("access request expired"), + "timeout-env" | "timeout-flag" => Some("access request approval wait timed out after 1 seconds"), + "callback-no-code" | "callback-bad-code" => Some("no usable authorization code"), + "exchange-replay" => Some("code already redeemed"), + "exchange-redirect-mismatch" => Some("redirect URI does not match"), + "exchange-401" => Some("PKCE verification failed"), + "exchange-403" => Some("permission to create API keys"), + "exchange-expiry-invalid" => Some("invalid keyExpiresAt"), + _ => None, + }; + if let Some(message) = expected_message { + assert!(stderr.contains(message), "{scenario}: {stderr}"); + } + // A refused code or verifier is not an identity problem, so it never suggests login. + if matches!(scenario, "exchange-replay" | "exchange-401" | "exchange-echo") { + assert!(!stderr.contains("cloud auth login"), "{scenario}: {stderr}"); + } + assert!(!combined.contains("secret-envelope-error")); + assert!(!combined.contains("secret-invalid-role")); + let requests = server.received_requests().await.unwrap(); + assert!(requests.iter().all(|r| r.url.path() != "/stolen"), "{scenario}: followed a redirect"); + // Only this machine's redirect and the deadline end the wait. + assert!(requests.iter().all(|r| r.url.path() != STATUS_PATH), "{scenario}: read the request status"); + let filed: Value = serde_json::from_slice(&requests[0].body).unwrap(); + assert_eq!(requests[0].url.path(), FILE_PATH); + assert!(filed.get("flow").is_none() && filed.get("agent").is_none(), "{filed}"); + assert_eq!(filed["codeChallengeMethod"], "S256"); + assert_eq!(filed["codeChallenge"].as_str().unwrap().len(), 43); + let redirect = filed["redirectUri"].as_str().unwrap(); + assert!(redirect.starts_with("http://127.0.0.1:") && redirect.ends_with("/callback"), "{redirect}"); + let state = filed["state"].as_str().unwrap(); + assert!((1..=512).contains(&state.len())); + assert!(!combined.contains(state)); + let token_requests: Vec<_> = requests.iter().filter(|r| r.url.path() == TOKEN_PATH).collect(); + assert_eq!(token_requests.len(), usize::from(exchanges), "{scenario}"); + for token in token_requests { + let body: Value = serde_json::from_slice(&token.body).unwrap(); + assert_eq!(body.as_object().unwrap().len(), 3); + assert_eq!(body["code"], "auth-code-secret"); + // Byte for byte the value filed. + assert_eq!(body["redirectUri"], filed["redirectUri"]); + let verifier = body["codeVerifier"].as_str().unwrap(); + assert!((43..=128).contains(&verifier.len())); + assert!(!combined.contains(verifier)); + assert_eq!(base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(Sha256::digest(verifier.as_bytes())), filed["codeChallenge"]); + } + if successful { + let expiry = scenario != "success-no-expiry"; + if json { + let result: Value = serde_json::from_slice(&output.stdout).unwrap(); + assert_eq!(result.as_object().unwrap().len(), 9); + assert_eq!(result["requestId"], "request-1"); + assert_eq!(result["organizationId"], "org"); + assert_eq!(result["credentialsPath"], credentials_path.canonicalize().unwrap().display().to_string()); + assert_eq!(result["requestedRoleIds"], if proposed {serde_json::json!([A, B])} else {serde_json::json!([])}); + if scenario == "grants-many" { + assert_eq!(result["grantedRoleIds"].as_array().unwrap().len(), 101); + } else { assert_eq!(result["grantedRoleIds"], serde_json::json!([B, C])); } + assert_eq!(result["status"], "approved"); + assert_eq!(result["keyId"], "issued-id"); + assert_eq!(result["key"], "issued-key"); + assert_eq!(result["keyExpiresAt"], if expiry {serde_json::json!(1794231456974_i64)} else {Value::Null}); + } else { + let stdout = String::from_utf8_lossy(&output.stdout); + assert!(stdout.contains("Organization: org")); + assert!(stdout.contains("Request ID: request-1")); + if proposed { assert!(stdout.contains(&format!("Requested roles: {A}, {B}"))); } + else { assert!(stdout.contains("Requested roles: none (manual selection)")); } + if scenario != "grants-many" { assert!(stdout.contains(&format!("Granted roles: {B}, {C}"))); } + assert_eq!(stdout.contains("Key expires: 2026-11-09T13:37:36Z"), expiry, "{stdout}"); + } + let stored: Value = serde_json::from_slice(&std::fs::read(&credentials_path).unwrap()).unwrap(); + assert_eq!(stored["api_key"], "issued-key"); + assert_eq!(stored["api_secret"], "issued-secret"); + } else { + assert!(output.stdout.is_empty()); + assert_eq!(std::fs::read(&credentials_path).unwrap(), before); + } + assert_eq!(std::fs::read(tokens.join("tokens.json")).unwrap(), oauth_before); + })); + } + } + for task in tasks { + task.await.unwrap(); + } +} + +#[test] +fn access_request_invalid_timeout_environment_fails_before_authentication() { + for value in ["0", "-1", "", "1.5", "5m", "4294967296"] { + let dir = tempfile::tempdir().unwrap(); + let output = access_command(dir.path()) + .env("CLICKHOUSE_CLOUD_ACCESS_TIMEOUT_SECONDS", value) + .output() + .unwrap(); + assert_eq!(output.status.code(), Some(2), "{value:?}"); + assert!(output.stdout.is_empty()); + assert!(!dir.path().join(".clickhouse").exists()); + } +} + +fn access_command(dir: &Path) -> Command { + let mut command = Command::new(clickhousectl_binary()); + command + .env_clear() + .env("DO_NOT_TRACK", "1") + .env("HOME", dir.join("home")) + .current_dir(dir) + .args(["cloud", "access", "request", "--json", "--debug"]); + command +} + +fn access_credentials(dir: &Path) -> PathBuf { + let project = dir.join(".clickhouse"); + std::fs::create_dir_all(&project).unwrap(); + std::fs::write( + project.join("credentials.json"), + r#"{"api_key":"saved-basic-key","api_secret":"saved-basic-secret"}"#, + ) + .unwrap(); + let tokens = dir.join("home/.clickhouse"); + std::fs::create_dir_all(&tokens).unwrap(); + tokens +} + +fn assert_access_debug_diagnostics(output: &std::process::Output, api_url: &str) { + let stderr = String::from_utf8_lossy(&output.stderr); + assert_eq!( + stderr + .matches("[debug] auth source: OAuth tokens (") + .count(), + 1, + "{stderr}" + ); + assert!(stderr.contains("home/.clickhouse/tokens.json)"), "{stderr}"); + assert_eq!(stderr.matches("[debug] api url:").count(), 1, "{stderr}"); + assert!( + stderr + .lines() + .any(|line| line == format!("[debug] api url: {api_url}/v1")), + "{stderr}" + ); + assert!(!String::from_utf8_lossy(&output.stdout).contains("[debug]")); +} + +fn assert_access_output_has_no_credentials(output: &std::process::Output) { + let text = format!( + "{}{}", + String::from_utf8_lossy(&output.stdout), + String::from_utf8_lossy(&output.stderr) + ); + for secret in [ + "saved-basic-key", + "saved-basic-secret", + "flag-basic-secret", + "env-basic-secret", + "test-bearer-token", + "refreshed-bearer-token", + "refresh-secret", + // Access handshake fixtures: the authorization code and the issued + // secret. Per-run values (verifier, state) are checked by their callers. + "auth-code-secret", + "issued-secret", + ] { + assert!( + !text.contains(secret), + "credential leaked in command output" + ); + } +} + +#[tokio::test] +async fn access_request_perms_files_canonical_proposal_once_without_grant_or_subset() { + let first = "abcdefab-1234-1234-1234-123456789abc"; + let system = "21111111-1111-1111-9999-000000000007"; + for json in [false, true] { + let server = MockServer::start().await; + Mock::given(method("POST")) + .and(path( + "/v1/organizations/selected/accessRequests/authorizationCode", + )) + .and(header("authorization", "Bearer test-bearer-token")) + .respond_with( + ResponseTemplate::new(403).set_body_json( + serde_json::json!({"error": "role selection is not assignable"}), + ), + ) + .expect(1) + .mount(&server) + .await; + let dir = tempfile::tempdir().unwrap(); + let tokens = access_credentials(dir.path()); + write_oauth_tokens(&tokens, &server.uri()); + let credentials_path = dir.path().join(".clickhouse/credentials.json"); + let before = std::fs::read(&credentials_path).unwrap(); + let mut command = Command::new(clickhousectl_binary()); + command + .env_clear() + .env("DO_NOT_TRACK", "1") + .env("HOME", dir.path().join("home")) + .current_dir(dir.path()) + .args([ + "cloud", + "access", + "request", + "--debug", + "--org", + "selected", + "--perms", + &format!("role:{first},role:{system}"), + "--perms", + &format!("role:{}", first.to_uppercase()), + "--key-name", + "proposed-key", + "--purpose", + "bounded proposal", + ]); + if json { + command.arg("--json"); + } + let output = command.output().unwrap(); + // A 403 is a refusal, not missing authentication. + assert_eq!(output.status.code(), Some(1)); + assert!(output.stdout.is_empty()); + let stderr = String::from_utf8_lossy(&output.stderr); + assert!(stderr.contains("role selection is not assignable")); + if json { + // `--debug` diagnostics precede the pretty-printed envelope. + let envelope = &stderr[stderr.rfind("\n{").map_or(0, |start| start + 1)..]; + let error: Value = serde_json::from_str(envelope).unwrap(); + assert!(error["error"]["message"].is_string(), "{stderr}"); + assert_ne!(error["error"]["code"], "auth_required", "{stderr}"); + } + assert_access_output_has_no_credentials(&output); + assert_eq!(std::fs::read(&credentials_path).unwrap(), before); + let requests = server.received_requests().await.unwrap(); + assert_eq!(requests.len(), 1, "no role catalog lookup or subset retry"); + let body: Value = serde_json::from_slice(&requests[0].body).unwrap(); + assert_eq!(body["requestedRoleIds"], serde_json::json!([first, system])); + assert_eq!(body["keyName"], "proposed-key"); + assert_eq!(body["purpose"], "bounded proposal"); + assert_eq!(body["codeChallengeMethod"], "S256"); + assert_eq!(body["codeChallenge"].as_str().unwrap().len(), 43); + assert!(!body["state"].as_str().unwrap().is_empty()); + assert!( + body["redirectUri"] + .as_str() + .unwrap() + .starts_with("http://127.0.0.1:") + ); + assert!(body["redirectUri"].as_str().unwrap().ends_with("/callback")); + assert!(body.get("flow").is_none()); + assert_eq!(body.as_object().unwrap().len(), 7); + for field in ["codeChallenge", "state"] { + assert!( + !String::from_utf8_lossy(&output.stderr).contains(body[field].as_str().unwrap()) + ); + } + } +} + +#[tokio::test] +async fn access_request_perms_usage_validation_precedes_oauth_and_network() { + let server = MockServer::start().await; + let dir = tempfile::tempdir().unwrap(); + let tokens = access_credentials(dir.path()); + // Expired identity would attempt refresh if usage validation were late. + std::fs::write( + tokens.join("tokens.json"), + serde_json::to_vec(&serde_json::json!({ + "access_token": "test-bearer-token", "refresh_token": "refresh-secret", "expires_at": 1, + "api_url": format!("{}/v1", server.uri()) + })) + .unwrap(), + ) + .unwrap(); + let oversized = (0..101) + .map(|i| format!("role:00000000-0000-0000-0000-{i:012x}")) + .collect::>() + .join(","); + for value in [ + "", + ",", + "role:Admin", + "Role:00000000-0000-0000-0000-000000000001", + "role:00000000-0000-0000-0000-000000000001,", + "role:00000000-0000-0000-0000-000000000001 ,role:*", + &oversized, + ] { + let output = access_command(dir.path()) + .args(["--perms", value]) + .env("CLICKHOUSECTL_AUTH_URL", server.uri()) + .env("CLICKHOUSECTL_CLIENT_ID", "test-client") + .output() + .unwrap(); + assert_eq!( + output.status.code(), + Some(2), + "{}", + String::from_utf8_lossy(&output.stderr) + ); + assert!(output.stdout.is_empty()); + assert_access_output_has_no_credentials(&output); + } + let output = Command::new(clickhousectl_binary()) + .env_clear() + .env("DO_NOT_TRACK", "1") + .env("HOME", dir.path().join("home")) + .current_dir(dir.path()) + .args([ + "cloud", + "--org-id=one", + "access", + "request", + "--org=two", + "--perms", + "role:00000000-0000-0000-0000-000000000001", + ]) + .output() + .unwrap(); + assert_eq!(output.status.code(), Some(2)); + assert!(server.received_requests().await.unwrap().is_empty()); +} + +/// Empty or over-long `--purpose` or `--key-name` fail as usage errors +/// before OAuth and the network. +#[tokio::test] +async fn access_request_length_limits_fail_before_oauth_and_network() { + let server = MockServer::start().await; + let dir = tempfile::tempdir().unwrap(); + let tokens = access_credentials(dir.path()); + // Expired identity would attempt refresh if usage validation were late. + std::fs::write( + tokens.join("tokens.json"), + serde_json::to_vec(&serde_json::json!({ + "access_token": "test-bearer-token", "refresh_token": "refresh-secret", "expires_at": 1, + "api_url": format!("{}/v1", server.uri()) + })) + .unwrap(), + ) + .unwrap(); + let purpose = "p".repeat(201); + let key_name = "k".repeat(101); + for (args, message) in [ + ( + vec!["--purpose", ""], + "--purpose must be 1 to 200 characters", + ), + ( + vec!["--purpose", &purpose], + "--purpose must be 1 to 200 characters", + ), + ( + vec!["--key-name", ""], + "--key-name must be 1 to 100 characters", + ), + ( + vec!["--key-name", &key_name], + "--key-name must be 1 to 100 characters", + ), + ] { + let output = access_command(dir.path()) + .args(&args) + .env("CLICKHOUSECTL_AUTH_URL", server.uri()) + .env("CLICKHOUSECTL_CLIENT_ID", "test-client") + .output() + .unwrap(); + let stderr = String::from_utf8_lossy(&output.stderr); + assert_eq!(output.status.code(), Some(2), "{args:?}: {stderr}"); + assert!(stderr.contains(message), "{args:?}: {stderr}"); + assert!(output.stdout.is_empty()); + assert_access_output_has_no_credentials(&output); + } + assert!(server.received_requests().await.unwrap().is_empty()); +} + +/// Discovery runs on the typed client directly, outside the handshake's +/// `operation` wrapper, so `for_access` must hand the client the 30-second +/// access-operation bound itself: a server holding the response open +/// fails the command near the bound instead of stalling until the mock's +/// delay elapses. The mock delays longer than the bound; without the +/// client timeout the command would only finish after it. +#[tokio::test] +async fn access_roles_discovery_gives_up_within_the_operation_bound() { + let started = std::time::Instant::now(); + let server = MockServer::start().await; + Mock::given(method("GET")) + .and(path("/v1/organizations/org/roles")) + .respond_with( + ResponseTemplate::new(200) + .set_body_json(serde_json::json!([])) + .set_delay(std::time::Duration::from_secs(90)), + ) + .mount(&server) + .await; + let dir = tempfile::tempdir().unwrap(); + let tokens = access_credentials(dir.path()); + write_oauth_tokens(&tokens, &server.uri()); + let output = access_roles_command(dir.path(), true) + .args(["--org", "org"]) + .output() + .unwrap(); + assert_eq!( + output.status.code(), + Some(1), + "{}", + String::from_utf8_lossy(&output.stderr) + ); + assert!( + started.elapsed() < std::time::Duration::from_secs(60), + "discovery must give up within the operation bound, not wait out the mock" + ); + let stderr = String::from_utf8_lossy(&output.stderr); + assert!(!stderr.contains("test-bearer-token")); + assert_access_output_has_no_credentials(&output); +} + +#[tokio::test] +async fn access_request_uses_oauth_for_discovery_and_filing_with_saved_or_explicit_url() { + for explicit_url in [false, true] { + let selected = MockServer::start().await; + let saved = MockServer::start().await; + Mock::given(method("GET")) + .and(path("/v1/organizations")) + .and(header("authorization", "Bearer test-bearer-token")) + .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({ + "result": [{"id": "11111111-2222-3333-4444-555555555555", "name": "Only org"}] + }))) + .expect(1) + .mount(&selected) + .await; + // Stop before browser launch, while exercising the real PKCE POST. + Mock::given(method("POST")) + .and(path( + "/v1/organizations/11111111-2222-3333-4444-555555555555/accessRequests/authorizationCode", + )) + .and(header("authorization", "Bearer test-bearer-token")) + .respond_with(ResponseTemplate::new(403).set_body_json(serde_json::json!({ + "error": "fixture rejection" + }))) + .expect(1) + .mount(&selected) + .await; + let dir = tempfile::tempdir().unwrap(); + let token_dir = access_credentials(dir.path()); + write_oauth_tokens( + &token_dir, + &if explicit_url { + saved.uri() + } else { + selected.uri() + }, + ); + let mut command = access_command(dir.path()); + // Even explicit/environment Basic credentials cannot change the user lane. + command + .args(["--api-key", "flag-key", "--api-secret", "flag-basic-secret"]) + .env("CLICKHOUSE_CLOUD_API_KEY", "env-key") + .env("CLICKHOUSE_CLOUD_API_SECRET", "env-basic-secret"); + if explicit_url { + command.args(["--url", &format!("{}/v1/", selected.uri())]); + } + let output = command.output().unwrap(); + assert_eq!( + output.status.code(), + Some(1), + "{}", + String::from_utf8_lossy(&output.stderr) + ); + assert_access_output_has_no_credentials(&output); + assert_access_debug_diagnostics(&output, &selected.uri()); + assert!(saved.received_requests().await.unwrap().is_empty()); + let requests = selected.received_requests().await.unwrap(); + assert_eq!(requests.len(), 2); + let body: Value = serde_json::from_slice(&requests[1].body).unwrap(); + assert_eq!(body["codeChallengeMethod"], "S256"); + assert_eq!(body["codeChallenge"].as_str().unwrap().len(), 43); + assert!(!body["state"].as_str().unwrap().is_empty()); + assert!( + body["redirectUri"] + .as_str() + .unwrap() + .starts_with("http://127.0.0.1:") + ); + assert!(body.get("codeVerifier").is_none()); + assert!(body.get("flow").is_none()); + assert_eq!(body.as_object().unwrap().len(), 4); + let credentials = + std::fs::read_to_string(dir.path().join(".clickhouse/credentials.json")).unwrap(); + assert!(credentials.contains("saved-basic-secret")); + assert!(token_dir.join("tokens.json").exists()); + } +} + +#[tokio::test] +async fn access_request_missing_or_unrefreshable_identity_never_falls_back_to_basic() { + for token_state in ["missing", "no-refresh", "unknown-host", "rejected"] { + let server = MockServer::start().await; + let dir = tempfile::tempdir().unwrap(); + let token_dir = access_credentials(dir.path()); + if token_state != "missing" { + // `auth_config` is required for the record to load at all. The + // saved config only drives refresh for the states that must + // reach it; `unknown-host` keeps a legacy record without one, + // which no environment can repair. + let mut record = serde_json::json!({ + "access_token": "test-bearer-token", + "refresh_token": if token_state == "no-refresh" { "" } else { "refresh-secret" }, + "expires_at": 1, + "api_url": format!("{}/v1", server.uri()), + }); + if token_state != "unknown-host" { + record["auth_config"] = + serde_json::json!({"auth_url": server.uri(), "client_id": "test-client"}); + } + std::fs::write( + token_dir.join("tokens.json"), + serde_json::to_vec(&record).unwrap(), + ) + .unwrap(); + } + let mut command = access_command(dir.path()); + command.args([ + "--url", + &server.uri(), + "--org-id", + "11111111-2222-3333-4444-555555555555", + ]); + if token_state == "rejected" { + Mock::given(method("POST")) + .and(path("/oauth/token")) + // Even an identity provider echoing a secret must not leak it. + .respond_with(ResponseTemplate::new(401).set_body_string("refresh-secret")) + .expect(1) + .mount(&server) + .await; + command + .env("CLICKHOUSECTL_AUTH_URL", server.uri()) + .env("CLICKHOUSECTL_CLIENT_ID", "test-client"); + } + let output = command.output().unwrap(); + assert_eq!(output.status.code(), Some(4), "{token_state}"); + let error: Value = serde_json::from_slice(&output.stderr).unwrap(); + assert!( + error["error"]["message"] + .as_str() + .unwrap() + .contains("cloud auth login") + ); + assert_access_output_has_no_credentials(&output); + let requests = server.received_requests().await.unwrap(); + assert_eq!(requests.len(), usize::from(token_state == "rejected")); + assert!(dir.path().join(".clickhouse/credentials.json").exists()); + // A failed refresh never removes the saved login (#1224). + assert_eq!( + token_dir.join("tokens.json").exists(), + token_state != "missing", + "{token_state}" + ); + } +} + +#[tokio::test] +async fn access_request_refreshes_oauth_despite_stored_basic_and_preserves_login_environment() { + let issuer = MockServer::start().await; + let target = MockServer::start().await; + Mock::given(method("POST")) + .and(path("/oauth/token")) + .and(header("content-type", "application/x-www-form-urlencoded")) + .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({ + "access_token": "refreshed-bearer-token", "expires_in": 3600, "token_type": "Bearer" + }))) + .expect(1) + .mount(&issuer) + .await; + Mock::given(method("POST")) + .and(path( + "/v1/organizations/11111111-2222-3333-4444-555555555555/accessRequests/authorizationCode", + )) + .and(header("authorization", "Bearer refreshed-bearer-token")) + .respond_with(ResponseTemplate::new(403)) + .expect(1) + .mount(&target) + .await; + let dir = tempfile::tempdir().unwrap(); + let token_dir = access_credentials(dir.path()); + std::fs::write( + token_dir.join("tokens.json"), + serde_json::to_vec(&serde_json::json!({ + "access_token": "test-bearer-token", "refresh_token": "refresh-secret", + "expires_at": 1, "api_url": format!("{}/v1", issuer.uri()), + "auth_config": {"auth_url": issuer.uri(), "client_id": "test-client"}, + })) + .unwrap(), + ) + .unwrap(); + let output = access_command(dir.path()) + .args([ + "--url", + &target.uri(), + "--org-id", + "11111111-2222-3333-4444-555555555555", + ]) + .env("CLICKHOUSECTL_AUTH_URL", format!("{}/", issuer.uri())) + .env("CLICKHOUSECTL_CLIENT_ID", "test-client") + .output() + .unwrap(); + assert_eq!( + output.status.code(), + Some(1), + "{}", + String::from_utf8_lossy(&output.stderr) + ); + assert_access_output_has_no_credentials(&output); + let requests = issuer.received_requests().await.unwrap(); + assert_eq!(requests.len(), 1); + let form: std::collections::HashMap<_, _> = url::form_urlencoded::parse(&requests[0].body) + .into_owned() + .collect(); + assert_eq!(form["grant_type"], "refresh_token"); + assert_eq!(form["client_id"], "test-client"); + assert_eq!(form["refresh_token"], "refresh-secret"); + let tokens: Value = + serde_json::from_slice(&std::fs::read(token_dir.join("tokens.json")).unwrap()).unwrap(); + assert_eq!(tokens["access_token"], "refreshed-bearer-token"); + assert_eq!(tokens["refresh_token"], "refresh-secret"); + assert_eq!(tokens["api_url"], format!("{}/v1", issuer.uri())); + assert!(tokens["expires_at"].as_i64().unwrap() > chrono::Utc::now().timestamp() + 60); +} + +#[tokio::test] +async fn access_organization_resolution_reads_complete_user_memberships() { + const ONE: &str = "11111111-2222-3333-4444-555555555555"; + const TWO: &str = "22222222-2222-3333-4444-555555555555"; + for scenario in [ + "zero", + "one", + "multi", + "paged-single", + "paged-multi", + "named", + "case-mismatch", + "ambiguous-name", + "repeat", + "no-progress", + "page-error", + "missing-result", + "missing-id", + "explicit", + ] { + let server = MockServer::start().await; + let first_rows = match scenario { + "zero" | "explicit" => serde_json::json!([]), + "multi" => { + serde_json::json!([{"id": ONE, "name": "First"}, {"id": TWO, "name": "Second"}]) + } + _ => serde_json::json!([{"id": ONE, "name": "First"}]), + }; + let paged = [ + "paged-single", + "paged-multi", + "named", + "case-mismatch", + "ambiguous-name", + "repeat", + "no-progress", + "page-error", + "missing-result", + "missing-id", + ] + .contains(&scenario); + let mut first = serde_json::json!({"result": first_rows}); + if paged { + first["nextCursor"] = "opaque+/= &?".into(); + } + Mock::given(method("GET")) + .and(path("/v1/organizations")) + .and(header("authorization", "Bearer test-bearer-token")) + .and(|request: &wiremock::Request| request.url.query().is_none()) + .respond_with(ResponseTemplate::new(200).set_body_json(first)) + .expect(if scenario == "explicit" { 0 } else { 1 }) + .mount(&server) + .await; + if paged { + let second = match scenario { + "paged-single" => serde_json::json!({"result": [], "nextCursor": null}), + "repeat" => serde_json::json!({"result": [], "nextCursor": "opaque+/= &?"}), + "no-progress" => { + serde_json::json!({"result": [{"id": ONE}], "nextCursor": "different"}) + } + "missing-result" => serde_json::json!({"nextCursor": null}), + "missing-id" => serde_json::json!({"result": [{"name": "Second"}]}), + "ambiguous-name" => { + serde_json::json!({"result": [{"id": TWO, "name": "First"}]}) + } + _ => serde_json::json!({"result": [{"id": TWO, "name": "Second"}]}), + }; + Mock::given(method("GET")) + .and(path("/v1/organizations")) + .and(query_param("cursor", "opaque+/= &?")) + .and(header("authorization", "Bearer test-bearer-token")) + .respond_with( + ResponseTemplate::new(if scenario == "page-error" { 500 } else { 200 }) + .set_body_json(second), + ) + .expect(1) + .mount(&server) + .await; + } + let files = ["one", "paged-single", "named", "explicit"].contains(&scenario); + let selected = if ["named", "explicit"].contains(&scenario) { + TWO + } else { + ONE + }; + Mock::given(method("POST")) + .and(path(format!( + "/v1/organizations/{selected}/accessRequests/authorizationCode" + ))) + .and(header("authorization", "Bearer test-bearer-token")) + .respond_with(ResponseTemplate::new(403)) + .expect(if files { 1 } else { 0 }) + .mount(&server) + .await; + let dir = tempfile::tempdir().unwrap(); + let token_dir = access_credentials(dir.path()); + write_oauth_tokens(&token_dir, &server.uri()); + let mut command = access_command(dir.path()); + match scenario { + "named" => { + command.args(["--org-name", "Second"]); + } + "case-mismatch" => { + command.args(["--org-name", "second"]); + } + "ambiguous-name" => { + command.args(["--org-name", "First"]); + } + "explicit" => { + command.args(["--org", TWO]); + } + _ => {} + } + let output = command.output().unwrap(); + assert_eq!( + output.status.code(), + Some(1), + "{scenario}: {}", + String::from_utf8_lossy(&output.stderr) + ); + assert_access_output_has_no_credentials(&output); + if ["zero", "multi", "paged-multi"].contains(&scenario) { + assert!(String::from_utf8_lossy(&output.stderr).contains("cloud org list --json")); + } + let requests = server.received_requests().await.unwrap(); + assert_eq!( + requests.len(), + usize::from(scenario != "explicit") + usize::from(paged) + usize::from(files), + "{scenario}" + ); + } +} + +#[test] +fn access_organization_conflicts_fail_usage_before_authentication() { + let dir = tempfile::tempdir().unwrap(); + for args in [ + vec![ + "cloud", + "--org-id=first", + "access", + "request", + "--org-id=second", + ], + vec![ + "cloud", + "--org-id=first", + "access", + "request", + "--org=second", + ], + vec![ + "cloud", + "access", + "--org=first", + "request", + "--org-id=second", + ], + vec![ + "cloud", + "--org-name=first", + "access", + "request", + "--org-name=second", + ], + vec![ + "cloud", + "--org-name=same", + "access", + "request", + "--org=same", + ], + ] { + let output = Command::new(clickhousectl_binary()) + .env_clear() + .env("DO_NOT_TRACK", "1") + .env("HOME", dir.path()) + .current_dir(dir.path()) + .args(args) + .output() + .unwrap(); + assert_eq!( + output.status.code(), + Some(2), + "{}", + String::from_utf8_lossy(&output.stderr) + ); + assert!(output.stdout.is_empty()); + } +} diff --git a/crates/clickhousectl/tests/cloud/main.rs b/crates/clickhousectl/tests/cloud/main.rs index c92c371c..7a910a40 100644 --- a/crates/clickhousectl/tests/cloud/main.rs +++ b/crates/clickhousectl/tests/cloud/main.rs @@ -8,6 +8,8 @@ mod support; +#[cfg(feature = "experimental-access-negotiation")] +mod access; mod activity; mod api_keys; mod auth; diff --git a/docs/README.md b/docs/README.md index e1407c01..e80ef052 100644 --- a/docs/README.md +++ b/docs/README.md @@ -15,7 +15,7 @@ Start with the [README](../README.md) for installation and product examples. The ## Reference -- [Cloud authentication and access](reference/authentication.md): scopes, credential precedence, selectors, keys, roles, logout. +- [Cloud authentication and access](reference/authentication.md): scopes, credential precedence, selectors, keys, roles, experimental access negotiation, logout. - [SQL and Query API behavior](reference/query-api.md): key binding, input formats, timeouts, keys from earlier versions, named endpoints. - [ClickPipe configuration](reference/clickpipe-configuration.md): partial updates, mappings, source authentication, private connectivity. - [Automation and output contracts](reference/automation.md): JSON shapes, stderr, exit codes, asynchronous operations. diff --git a/docs/reference/authentication.md b/docs/reference/authentication.md index dfd739da..d3dded55 100644 --- a/docs/reference/authentication.md +++ b/docs/reference/authentication.md @@ -41,6 +41,8 @@ Supplying only one credential flag blocks fallback. So does a `.clickhouse/crede A saved API key works only against the API it was saved for. When `auth login --api-key` verifies a key against a non-production API (`--url`), that API is saved with the key as `api_url`; a key with no `api_url` is for production. Later commands without `--url` use the saved API, print a note naming it to stderr, and derive the Query API host for `cloud service query` from it unless `CLICKHOUSE_CLOUD_QUERY_HOST` is set. A `--url` naming any other API exits 4 without sending the key or falling back to environment or OAuth credentials: pass the saved URL, or save a key for that API. `auth status` shows the API each saved source uses. Flag and environment keys carry no URL; they use `--url` or production. +`cloud access roles --debug` and `cloud access request --debug` report their OAuth credential source and resolved API URL on stderr, including with `--json`. These experimental commands use OAuth even when higher-priority API keys are configured; the diagnostics describe the identity actually used for access negotiation. + `cloud postgres query` accepts **OAuth only**, unlike `cloud service query`. Remove higher-priority API key sources before using that route. Clearing a saved key file alone is insufficient if exported variables or `.env` still supply a key. ## Select an organization and resource @@ -83,6 +85,65 @@ Replace the example IP. **Omitting `--ip-allow` on key creation denies all netwo Save the generated authentication key ID and secret securely; the secret is returned only at creation. The management resource `id` used by `get`, `update`, `delete`, and endpoint bindings differs from the authentication `keyId`/`keySecret`. Pre-hashed key creation does not return a secret. +## Experimental: negotiate a scoped API key + +> **Experimental.** `cloud access` is compiled only into builds with the `experimental-access-negotiation` feature. Published binaries (install script, npm, `cargo install clickhousectl`) do not include it and report `unrecognized subcommand 'access'`. Build it from a checkout: +> +> ```bash +> cargo install --path crates/clickhousectl --features experimental-access-negotiation +> ``` +> +> The command surface and behavior may change without notice. + +### Discover assignable roles + +```bash +clickhousectl cloud access roles +clickhousectl cloud access roles --org --json +``` + +Discovery uses your refreshed OAuth user identity even when an API key is saved, with the same organization selectors and endpoint precedence as `cloud access request`. Human output identifies the selected organization and lists role IDs/names with policy effects and resource scopes. `--json` returns exactly the complete role array, including all ALLOW/DENY policies and optional SQL tags; an eligible empty menu is `[]`. SQL grant/revoke strings and unknown values remain opaque. Incomplete required discovery data fails before any menu is printed, rather than implying empty permissions or falling back to the administrative catalog. Discovery describes current authority, not a guarantee of later approval or a role recommendation. + +### Request a scoped API key + +`cloud access request` obtains a scoped API key through the control plane's PKCE approval handshake, so an agent can get a narrowly-scoped key that a human approves in a browser rather than reusing a long-lived one. + +```bash +clickhousectl cloud access request +clickhousectl cloud access request --key-name agent-key --purpose "CI deploy" +clickhousectl cloud access request --org --perms role:,role: +clickhousectl cloud access request --json +``` + +Use IDs from `cloud access roles` to propose roles with `--perms role:` (repeat the flag or separate tokens with commas). UUIDs are normalized to lowercase and deduplicated by identity in first-seen order; at most 100 distinct roles are allowed. Empty tokens, whitespace, wrong prefixes and malformed UUIDs fail before authentication or network access. Role names, raw permissions and resource overrides are not supported. Omit `--perms` for manual browser selection; an explicitly empty value is invalid. A proposal is not a grant: the server validates the whole proposal atomically, and the human's eventual selection may differ. The CLI neither filters rejected proposals nor retries a subset. + +The command requires your OAuth user identity from `cloud auth login` and refreshes it when needed; API keys from flags, saved credentials, or environment variables are never used for negotiation. Missing or expired identity that cannot be refreshed fails with authentication exit code 4 and login guidance. It runs the authorization code flow with PKCE: it starts a loopback redirect server on `127.0.0.1` (or `[::1]` when IPv4 loopback is unavailable), generates a PKCE verifier/challenge and a CSRF `state`, files the request, and opens the approval URL (always printed in case the browser does not open). After you approve, the browser redirects to the CLI with a one-time authorization code. The CLI exchanges that code, the PKCE verifier and the same redirect URI for the issued key, and stores the key id and secret in `.clickhouse/credentials.json`. The secret is never printed or placed in a URL. A redirect with a missing or wrong `state` is refused and the wait continues. If no loopback listener can be started, the command fails. + +The code arrives only on the browser redirect, so the browser must run on this machine. The CLI does not read the request status while waiting: only the redirect or the deadline ends the wait. A denial in the approval page redirects back with `error=access_denied` and ends the wait at once; a denial or cancellation that never reaches this browser waits until the deadline. Pending approval waits until the server pending deadline (ten minutes after filing) or two minutes by default, whichever comes first; the error says which one ended the wait. See [approval timeout configuration](#approval-timeout). + +The approval URL and progress always go to stderr, including with `--json`; JSON stdout contains only the final success object. Denial, expiry and authentication failures never replace saved credentials. A rejected authorization code or PKCE verifier (HTTP 400 or 401 from the exchange) exits 1 with the server's message; it does not ask you to log in again. Each access HTTP operation is bounded to 30 seconds. Filing and the exchange are not retried: a timeout may leave a filed request or a completed server exchange without local credentials. + +Successful requests report the organization and request IDs, the server-saved proposal, the actual roles returned by the exchange, and when the key expires (issued keys are short-lived). JSON retains `status`, `keyId`, `key`, and `credentialsPath`, and adds `requestId`, `organizationId`, `requestedRoleIds`, `grantedRoleIds`, and `keyExpiresAt` (epoch milliseconds, or `null` when the server sends none). With no proposal, `requestedRoleIds` is `[]` (manual selection); the human may trim or add roles, so actual grants need not match the proposal. Missing or invalid server role arrays fail before local credential installation; older servers without this reporting contract are unsupported. + +The API URL comes from `--url` when provided, otherwise the API URL saved with your OAuth login. Token records without a saved API URL are rejected; run `cloud auth login` again. Local development requires an explicit local URL at login or through `--url`; there is no implicit localhost default. Other Cloud commands retain their normal credential precedence, so a saved negotiated key remains available for subsequent operations. Optional `--purpose` (1–200 characters, shown to the approver) and `--key-name` (1–100 characters) are sent with the request; the calling agent is identified by the CLI User-Agent and agent-session headers. + +Access organization selection uses your OAuth user's complete, paginated membership list, not the saved API key's organization. A single membership is selected automatically; zero or multiple memberships require action (no remembered default or prompt). Find IDs with `cloud org list --json` and select `cloud access request --org ` (`--org-id` remains supported), or use exact `--org-name`. Conflicting selectors, including across command depths, are usage errors. + +### Approval timeout + +`cloud access request` waits up to **two minutes** for human approval. Override it with `--timeout-seconds` or `CLICKHOUSE_CLOUD_ACCESS_TIMEOUT_SECONDS` (positive whole seconds, at most 4294967295): + +```bash +clickhousectl cloud access request --org-id --timeout-seconds 600 + +export CLICKHOUSE_CLOUD_ACCESS_TIMEOUT_SECONDS=600 +clickhousectl cloud access request --org-id +``` + +Precedence is flag, environment, then the 120-second default. This setting is not read from `.env` (the CLI uses that file only for credential configuration). Invalid values fail with usage exit code 2 before authentication or filing a request. The CLI reports the configured wait on stderr. + +An earlier server pending deadline still wins; increasing this setting cannot extend server expiry. The error names the deadline that ended the wait: "access request expired" for the server deadline, "approval wait timed out after N seconds" for this setting. The authorization code arrives only on the browser redirect, and the CLI never reads the request status. The 30-second bound per HTTP operation is unchanged. This setting does not extend OAuth token validity or the issued key lifetime. + ## Inspect all keys and change access ```bash diff --git a/scripts/classify-install-integration.py b/scripts/classify-install-integration.py index 306a9077..e28ba792 100644 --- a/scripts/classify-install-integration.py +++ b/scripts/classify-install-integration.py @@ -83,6 +83,7 @@ "crates/clickhousectl/src/telemetry.rs", "crates/clickhousectl/src/udf.rs", "crates/clickhousectl/src/update.rs", + "crates/clickhousectl/tests/cloud/access.rs", "crates/clickhousectl/tests/cloud/activity.rs", "crates/clickhousectl/tests/cloud/api_keys.rs", "crates/clickhousectl/tests/cloud/auth.rs", diff --git a/scripts/tests/test_classify_install_integration.py b/scripts/tests/test_classify_install_integration.py index f37e4819..8a6d510c 100644 --- a/scripts/tests/test_classify_install_integration.py +++ b/scripts/tests/test_classify_install_integration.py @@ -164,6 +164,7 @@ def test_exact_path_mappings(self): "crates/clickhousectl/src/telemetry.rs", "crates/clickhousectl/src/udf.rs", "crates/clickhousectl/src/update.rs", + "crates/clickhousectl/tests/cloud/access.rs", "crates/clickhousectl/tests/cloud/activity.rs", "crates/clickhousectl/tests/cloud/api_keys.rs", "crates/clickhousectl/tests/cloud/auth.rs", From 1b0fe5a9a7ce34e07c25b4737c950e117d22e2a1 Mon Sep 17 00:00:00 2001 From: Emanuele De Cupis Date: Fri, 13 Nov 2026 13:16:34 +0100 Subject: [PATCH 4/8] feat(cloud): style access request approved and denied callback pages Serve dedicated approved and denied loopback pages styled like the console's access-request confirmation view, with a 5-second countdown that tries to close the tab. --- crates/clickhousectl/src/cloud/access.rs | 21 +++- .../src/cloud/access_approved.html | 107 ++++++++++++++++++ .../src/cloud/access_denied.html | 107 ++++++++++++++++++ 3 files changed, 232 insertions(+), 3 deletions(-) create mode 100644 crates/clickhousectl/src/cloud/access_approved.html create mode 100644 crates/clickhousectl/src/cloud/access_denied.html diff --git a/crates/clickhousectl/src/cloud/access.rs b/crates/clickhousectl/src/cloud/access.rs index 2168415d..99600a12 100644 --- a/crates/clickhousectl/src/cloud/access.rs +++ b/crates/clickhousectl/src/cloud/access.rs @@ -901,7 +901,7 @@ async fn serve_callback( } Some(match params.get("code").filter(|code| valid_code(code)) { Some(code) => { - write_response(&mut stream, "200 OK", SUCCESS_HTML).await; + write_response(&mut stream, "200 OK", APPROVED_HTML).await; Ok(code.clone()) } None => { @@ -990,8 +990,11 @@ async fn write_response(stream: &mut tokio::net::TcpStream, status: &str, body: .await; } -const SUCCESS_HTML: &str = "Access approved

Access approved

You can return to your terminal.

"; -const DENIED_HTML: &str = "Access denied

Access denied

The request was denied. You can return to your terminal.

"; +/// Loopback page for an approved request; mirrors the console's confirmation +/// view and tries to close its tab after a short countdown. +const APPROVED_HTML: &str = include_str!("access_approved.html"); +/// Loopback page for a denied request, styled like [`APPROVED_HTML`]. +const DENIED_HTML: &str = include_str!("access_denied.html"); const NOT_FOUND_HTML: &str = "Not found"; const BAD_REQUEST_HTML: &str = "Invalid request. You can close this tab and return to your terminal."; @@ -1204,6 +1207,18 @@ mod tests { } } + #[test] + fn approved_and_denied_pages_are_distinct_and_autoclose() { + assert_ne!(APPROVED_HTML, DENIED_HTML); + assert!(APPROVED_HTML.contains("class=\"banner success\"")); + assert!(DENIED_HTML.contains("class=\"banner warning\"")); + for html in [APPROVED_HTML, DENIED_HTML] { + assert!(!html.contains("{{")); + assert!(html.contains("var seconds = 5;")); + assert!(html.contains("window.close()")); + } + } + #[test] fn canonical_role_ids_validate_server_arrays_without_inferring_grants() { let system = "21111111-1111-1111-9999-000000000007".to_string(); diff --git a/crates/clickhousectl/src/cloud/access_approved.html b/crates/clickhousectl/src/cloud/access_approved.html new file mode 100644 index 00000000..276e401c --- /dev/null +++ b/crates/clickhousectl/src/cloud/access_approved.html @@ -0,0 +1,107 @@ + + + + + +Access approved · ClickHouse + + + +
+ +
+

Access approved

+ +
+ +
+
+ + + diff --git a/crates/clickhousectl/src/cloud/access_denied.html b/crates/clickhousectl/src/cloud/access_denied.html new file mode 100644 index 00000000..68f0664e --- /dev/null +++ b/crates/clickhousectl/src/cloud/access_denied.html @@ -0,0 +1,107 @@ + + + + + +Access denied · ClickHouse + + + +
+ +
+

API access request denied

+ +
+ +
+
+ + + From 158a627a39a9d139e5758db0e33408d03c7c5a57 Mon Sep 17 00:00:00 2001 From: Emanuele De Cupis Date: Tue, 17 Nov 2026 14:12:32 +0100 Subject: [PATCH 5/8] feat(access request): trace agent headers on agentic access requests --- crates/clickhousectl/src/cloud/access.rs | 6 +++++- crates/clickhousectl/tests/cloud/access.rs | 24 +++++++++++++++++++++- 2 files changed, 28 insertions(+), 2 deletions(-) diff --git a/crates/clickhousectl/src/cloud/access.rs b/crates/clickhousectl/src/cloud/access.rs index 99600a12..cbf813b3 100644 --- a/crates/clickhousectl/src/cloud/access.rs +++ b/crates/clickhousectl/src/cloud/access.rs @@ -528,8 +528,12 @@ fn print_assignable_roles(org_id: &str, roles: &[AssignableRole]) { /// `Authorization` header on cross-origin redirects does not protect those /// body fields. Reject redirects instead of forwarding secrets or replaying /// the exchange POST. +/// +/// Both steps go only to the Cloud API, so like every other Cloud call it +/// carries the agent session/trace headers; with redirects disabled they +/// cannot be forwarded to another host. fn handshake_client() -> CloudResult { - crate::http::client_builder() + crate::http::clickhouse_client_builder() .redirect(reqwest::redirect::Policy::none()) .build() .map_err(|error| CloudError::new(format!("failed to build HTTP client: {error}"))) diff --git a/crates/clickhousectl/tests/cloud/access.rs b/crates/clickhousectl/tests/cloud/access.rs index 683892ed..9b49ceb9 100644 --- a/crates/clickhousectl/tests/cloud/access.rs +++ b/crates/clickhousectl/tests/cloud/access.rs @@ -795,8 +795,15 @@ async fn access_request_perms_files_canonical_proposal_once_without_grant_or_sub "--purpose", "bounded proposal", ]); + let traceparent = "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01"; if json { - command.arg("--json"); + // Under a detected agent (which also forces JSON), the handshake + // carries the agent session/trace headers like other Cloud calls. + command + .arg("--json") + .env("AGENT", "claude-code") + .env("CLAUDE_CODE_SESSION_ID", "sess-access") + .env("TRACEPARENT", traceparent); } let output = command.output().unwrap(); // A 403 is a refusal, not missing authentication. @@ -815,6 +822,21 @@ async fn access_request_perms_files_canonical_proposal_once_without_grant_or_sub assert_eq!(std::fs::read(&credentials_path).unwrap(), before); let requests = server.received_requests().await.unwrap(); assert_eq!(requests.len(), 1, "no role catalog lookup or subset retry"); + let agent_header = |name: &str| { + requests[0] + .headers + .get(name) + .map(|value| value.to_str().unwrap().to_string()) + }; + if json { + assert_eq!( + agent_header("agent-session-id").as_deref(), + Some("sess-access") + ); + assert_eq!(agent_header("traceparent").as_deref(), Some(traceparent)); + } else { + assert_eq!(agent_header("agent-session-id"), None); + } let body: Value = serde_json::from_slice(&requests[0].body).unwrap(); assert_eq!(body["requestedRoleIds"], serde_json::json!([first, system])); assert_eq!(body["keyName"], "proposed-key"); From b28bab58e70bca1f10d65609a7ed2a3cf24152e4 Mon Sep 17 00:00:00 2001 From: Emanuele De Cupis Date: Tue, 17 Nov 2026 14:21:51 +0100 Subject: [PATCH 6/8] fix(access request): fail org pagination on pages that add no organization --- crates/clickhousectl/src/cloud/access.rs | 8 ++++---- crates/clickhousectl/tests/cloud/access.rs | 3 +++ 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/crates/clickhousectl/src/cloud/access.rs b/crates/clickhousectl/src/cloud/access.rs index cbf813b3..0bf861f0 100644 --- a/crates/clickhousectl/src/cloud/access.rs +++ b/crates/clickhousectl/src/cloud/access.rs @@ -347,7 +347,6 @@ impl CloudClient { .map_err(|error| self.convert_error(error))?; let next_cursor = response.next_cursor.clone(); let page = Self::unwrap_response(response)?; - let had_rows = !page.is_empty(); let previous_count = organizations.len(); for organization in page { let id = organization.id.ok_or_else(|| CloudError::new( @@ -359,10 +358,11 @@ impl CloudClient { } match next_cursor { None => break, + // Every page that promises more must add an organization: an + // empty or all-duplicate page with a fresh cursor would + // otherwise page forever. Some(next) => { - if (had_rows && previous_count == organizations.len()) - || !seen_cursors.insert(next.clone()) - { + if previous_count == organizations.len() || !seen_cursors.insert(next.clone()) { return Err(CloudError::new( "Organization pagination made no progress; cannot safely select an organization", )); diff --git a/crates/clickhousectl/tests/cloud/access.rs b/crates/clickhousectl/tests/cloud/access.rs index 9b49ceb9..ac9f4c3a 100644 --- a/crates/clickhousectl/tests/cloud/access.rs +++ b/crates/clickhousectl/tests/cloud/access.rs @@ -1245,6 +1245,7 @@ async fn access_organization_resolution_reads_complete_user_memberships() { "ambiguous-name", "repeat", "no-progress", + "empty-progress", "page-error", "missing-result", "missing-id", @@ -1266,6 +1267,7 @@ async fn access_organization_resolution_reads_complete_user_memberships() { "ambiguous-name", "repeat", "no-progress", + "empty-progress", "page-error", "missing-result", "missing-id", @@ -1290,6 +1292,7 @@ async fn access_organization_resolution_reads_complete_user_memberships() { "no-progress" => { serde_json::json!({"result": [{"id": ONE}], "nextCursor": "different"}) } + "empty-progress" => serde_json::json!({"result": [], "nextCursor": "different"}), "missing-result" => serde_json::json!({"nextCursor": null}), "missing-id" => serde_json::json!({"result": [{"name": "Second"}]}), "ambiguous-name" => { From 110b8a08889826d243514b6568d139da3bf379d6 Mon Sep 17 00:00:00 2001 From: Emanuele De Cupis Date: Tue, 17 Nov 2026 14:48:46 +0100 Subject: [PATCH 7/8] fix(access request): refresh the OAuth identity before the code exchange --- crates/clickhousectl/src/cloud/access.rs | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/crates/clickhousectl/src/cloud/access.rs b/crates/clickhousectl/src/cloud/access.rs index 0bf861f0..1f7c4644 100644 --- a/crates/clickhousectl/src/cloud/access.rs +++ b/crates/clickhousectl/src/cloud/access.rs @@ -613,6 +613,14 @@ async fn request( ); let code = wait_for_redirect(pending, listener, &state).await?; + // The approval wait can outlast the Bearer captured at filing, so refresh + // it when near expiry. The code is single-use and already approved: any + // refresh failure, or a login now for another API URL, keeps the filing + // Bearer rather than dropping the code without trying the exchange. + let auth = match CloudClient::for_access(url_override).await { + Ok(fresh) if fresh.base_url() == base_url => fresh.request_auth(), + _ => auth, + }; let token_url = format!("{access_url}/authorizationCode/token"); let issued = exchange_code( &http, From fa0a2cae37ded3a9b172fd2c0a97813d16ad6ea1 Mon Sep 17 00:00:00 2001 From: Chloe Carasso Date: Wed, 18 Nov 2026 01:06:48 -0800 Subject: [PATCH 8/8] feat(cloud): point agents at cloud access when a write hits read-only OAuth (#1495) --- crates/clickhousectl/src/cloud/mod.rs | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/crates/clickhousectl/src/cloud/mod.rs b/crates/clickhousectl/src/cloud/mod.rs index 69045cf9..552149da 100644 --- a/crates/clickhousectl/src/cloud/mod.rs +++ b/crates/clickhousectl/src/cloud/mod.rs @@ -147,8 +147,7 @@ pub async fn run(args: CloudArgs, json: bool) -> Result<()> { // OAuth (Bearer) tokens are read-only. Block write commands early // to avoid fail loops where agents repeatedly hit 403 errors. if client.is_bearer_auth() && command.is_write_command() { - return Err(Error::AuthRequired( - "This command requires API key authentication. \ + const BASE: &str = "This command requires API key authentication. \ OAuth (browser login) provides read-only access.\n\n\ To authenticate with an API key:\n \ clickhousectl cloud auth login --api-key YOUR_KEY --api-secret YOUR_SECRET\n\n\ @@ -156,9 +155,19 @@ pub async fn run(args: CloudArgs, json: bool) -> Result<()> { export CLICKHOUSE_CLOUD_API_KEY=your-key\n \ export CLICKHOUSE_CLOUD_API_SECRET=your-secret\n\n\ Learn how to create API keys:\n \ - https://clickhouse.com/docs/cloud/manage/openapi?referrer=clickhousectl" - .into(), - )); + https://clickhouse.com/docs/cloud/manage/openapi?referrer=clickhousectl"; + // The scoped-access flow exists only when compiled with the + // `experimental-access-negotiation` feature, so a default binary must + // not advertise commands it does not carry. + #[cfg(feature = "experimental-access-negotiation")] + const ACCESS_HINT: &str = "\n\n\ + Or request a short-lived, human-approved scoped key, with no \ + long-lived API key to manage:\n \ + clickhousectl cloud access roles # list the roles you can request\n \ + clickhousectl cloud access request --perms role:"; + #[cfg(not(feature = "experimental-access-negotiation"))] + const ACCESS_HINT: &str = ""; + return Err(Error::AuthRequired(format!("{BASE}{ACCESS_HINT}"))); } // `service client` ends in an `exec()` of the local client, and its