diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6ffa750..6dc7020 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,7 +10,9 @@ bun run kafka:up # optional: Kafka on localhost:9092 with demo data bun run tauri dev # first build compiles librdkafka; takes a few minutes ``` -Then add a cluster with bootstrap `localhost:9092`. +Then add a cluster with bootstrap `localhost:9092`. [docs/LOCAL_KAFKA.md](docs/LOCAL_KAFKA.md) lists the demo +topics and ACLs, explains the broker's authorizer setup, and shows how to add seed data. `bun run kafka:acl-demo` +logs in as the demo users and checks the broker enforces the seeded ACLs. The [Makefile](Makefile) wraps the common steps; on Windows, run it from Git Bash: diff --git a/README.md b/README.md index ed7685a..e80c3bf 100644 --- a/README.md +++ b/README.md @@ -71,6 +71,13 @@ Send a message with its own key and headers, or fill a topic with generated test See how far behind each consumer group is, and reset its offsets when it needs a fresh start. +### Control who can access what + +List a cluster's ACLs and filter them by principal, resource or host. Grant or deny operations on topics, +groups, transactional IDs or the cluster, and delete ACLs you no longer need. The brokers need an authorizer: +on KRaft, set `authorizer.class.name=org.apache.kafka.metadata.authorizer.StandardAuthorizer`, and add your +admin principals to `super.users` first so they aren't locked out. + ### Make it yours The Settings window diff --git a/crates/kui_desktop/src/features/acls/commands.rs b/crates/kui_desktop/src/features/acls/commands.rs new file mode 100644 index 0000000..c743c96 --- /dev/null +++ b/crates/kui_desktop/src/features/acls/commands.rs @@ -0,0 +1,26 @@ +use tauri::State; + +use super::model::AclBinding; +use super::service; +use crate::blocking::run_blocking; +use crate::error::Result; +use crate::state::AppState; + +#[tauri::command] +pub async fn list_acls(state: State<'_, AppState>, cluster_id: String) -> Result> { + let clients = state.clients(&cluster_id)?; + run_blocking(move || service::list(&clients)).await +} + +#[tauri::command] +pub async fn create_acls(state: State<'_, AppState>, cluster_id: String, acls: Vec) -> Result<()> { + let clients = state.clients(&cluster_id)?; + run_blocking(move || service::create(&clients, &acls)).await +} + +/// Deletes exactly the given ACLs; returns how many were removed. +#[tauri::command] +pub async fn delete_acls(state: State<'_, AppState>, cluster_id: String, acls: Vec) -> Result { + let clients = state.clients(&cluster_id)?; + run_blocking(move || service::delete(&clients, &acls)).await +} diff --git a/crates/kui_desktop/src/features/acls/mod.rs b/crates/kui_desktop/src/features/acls/mod.rs new file mode 100644 index 0000000..b5af92e --- /dev/null +++ b/crates/kui_desktop/src/features/acls/mod.rs @@ -0,0 +1,6 @@ +//! ACLs: who may read, write or administer which topics, groups and +//! transactional ids, and the cluster itself. + +pub mod commands; +pub mod model; +pub mod service; diff --git a/crates/kui_desktop/src/features/acls/model.rs b/crates/kui_desktop/src/features/acls/model.rs new file mode 100644 index 0000000..65f4cd4 --- /dev/null +++ b/crates/kui_desktop/src/features/acls/model.rs @@ -0,0 +1,4 @@ +//! The ACL types are plain data shared with the Kafka layer, so the UI sees +//! exactly what `kui_kafka::acl_admin` reads and writes. + +pub use kui_kafka::acls::AclBinding; diff --git a/crates/kui_desktop/src/features/acls/service.rs b/crates/kui_desktop/src/features/acls/service.rs new file mode 100644 index 0000000..c669340 --- /dev/null +++ b/crates/kui_desktop/src/features/acls/service.rs @@ -0,0 +1,73 @@ +use super::model::AclBinding; +use crate::error::{Error, Result}; +use kui_kafka::KafkaClients; +use kui_kafka::acl_admin; +use kui_kafka::acls::validate; +use kui_kafka::connection::rejection; + +/// Most ACLs one create or delete request may carry. The dialog sends one per +/// chosen operation, so a larger request didn't come from the UI. +const MAX_PER_REQUEST: usize = 100; + +/// Every ACL, ordered by resource type, resource, then principal. +pub fn list(clients: &KafkaClients) -> Result> { + let mut acls = acl_admin::describe(&clients.admin).map_err(|e| connection_error(clients, e))?; + acls.sort(); + Ok(acls) +} + +pub fn create(clients: &KafkaClients, acls: &[AclBinding]) -> Result<()> { + check_batch(acls)?; + for acl in acls { + validate(acl)?; + } + Ok(acl_admin::create(&clients.admin, acls).map_err(|e| connection_error(clients, e))?) +} + +/// Deletes exactly these ACLs and returns how many Kafka removed. +pub fn delete(clients: &KafkaClients, acls: &[AclBinding]) -> Result { + check_batch(acls)?; + let deleted = acl_admin::delete(&clients.admin, acls).map_err(|e| connection_error(clients, e))?; + if deleted == 0 { + return Err(Error::msg("No matching ACL was found. It may have been deleted already.")); + } + Ok(deleted) +} + +fn check_batch(acls: &[AclBinding]) -> Result<()> { + match acls.len() { + 0 => Err(Error::msg("No ACLs given")), + n if n > MAX_PER_REQUEST => Err(Error::msg(format!("At most {MAX_PER_REQUEST} ACLs can be changed at once"))), + _ => Ok(()), + } +} + +fn connection_error(clients: &KafkaClients, e: kui_kafka::Error) -> kui_kafka::Error { + rejection(&clients.metadata).unwrap_or(e) +} + +#[cfg(test)] +mod tests { + use super::*; + use kui_kafka::acls::{Operation, PatternType, Permission, ResourceType}; + + fn acl() -> AclBinding { + AclBinding { + resource_type: ResourceType::Topic, + resource_name: "orders".into(), + pattern_type: PatternType::Literal, + principal: "User:alice".into(), + host: "*".into(), + operation: Operation::Read, + permission: Permission::Allow, + } + } + + #[test] + fn batches_must_be_non_empty_and_bounded() { + assert!(check_batch(&[]).is_err()); + assert!(check_batch(&[acl()]).is_ok()); + assert!(check_batch(&vec![acl(); MAX_PER_REQUEST]).is_ok()); + assert!(check_batch(&vec![acl(); MAX_PER_REQUEST + 1]).is_err()); + } +} diff --git a/crates/kui_desktop/src/features/mod.rs b/crates/kui_desktop/src/features/mod.rs index c72872c..6de46c4 100644 --- a/crates/kui_desktop/src/features/mod.rs +++ b/crates/kui_desktop/src/features/mod.rs @@ -7,6 +7,7 @@ //! Features only depend on `kui_kafka` (shared infra), never on each other. //! Even `ClusterConfig`, which every feature takes as input, lives in `kafka`. +pub mod acls; pub mod brokers; pub mod clusters; pub mod consumer_groups; diff --git a/crates/kui_desktop/src/integration_tests.rs b/crates/kui_desktop/src/integration_tests.rs index a53bddc..56a7ddb 100644 --- a/crates/kui_desktop/src/integration_tests.rs +++ b/crates/kui_desktop/src/integration_tests.rs @@ -697,3 +697,41 @@ async fn a_message_above_the_retained_limit_is_matched_whole() { assert_eq!(walk("NOT value.late = 'ok'"), [2, 3]); topics::service::delete(&clients, &[topic]).await.unwrap(); } + +#[tokio::test] +#[ignore = "needs a running Kafka broker with an authorizer"] +async fn acls_are_created_listed_and_deleted_exactly() { + use crate::features::acls; + use crate::features::acls::model::AclBinding; + use kui_kafka::acls::{Operation, PatternType, Permission, ResourceType}; + + let clients = KafkaClients::connect(local_cluster()).unwrap(); + let principal = format!("User:kui-it-{}", uuid::Uuid::new_v4()); + let acl = |operation| AclBinding { + resource_type: ResourceType::Topic, + resource_name: "kui-it-".into(), + pattern_type: PatternType::Prefixed, + principal: principal.clone(), + host: "*".into(), + operation, + permission: Permission::Allow, + }; + let mine = || -> Vec { + acls::service::list(&clients).unwrap().into_iter().filter(|a| a.principal == principal).collect() + }; + + acls::service::create(&clients, &[acl(Operation::Read), acl(Operation::Describe)]).unwrap(); + // ACL changes reach the broker's cache through the metadata log, a moment after they are accepted. + for _ in 0..20 { + if mine().len() == 2 { + break; + } + tokio::time::sleep(Duration::from_millis(250)).await; + } + assert_eq!(mine(), [acl(Operation::Read), acl(Operation::Describe)]); + + // Deleting one ACL leaves its sibling, which differs only in the operation. + assert_eq!(acls::service::delete(&clients, &[acl(Operation::Read)]).unwrap(), 1); + assert!(acls::service::delete(&clients, &[acl(Operation::Read)]).is_err(), "deleting twice should fail"); + assert_eq!(acls::service::delete(&clients, &[acl(Operation::Describe)]).unwrap(), 1); +} diff --git a/crates/kui_desktop/src/lib.rs b/crates/kui_desktop/src/lib.rs index cf37d47..37c5352 100644 --- a/crates/kui_desktop/src/lib.rs +++ b/crates/kui_desktop/src/lib.rs @@ -20,7 +20,7 @@ mod security_tests; use tauri::Manager; -use features::{brokers, clusters, consumer_groups, generator, messages, topics}; +use features::{acls, brokers, clusters, consumer_groups, generator, messages, topics}; use state::AppState; #[cfg_attr(mobile, tauri::mobile_entry_point)] @@ -74,6 +74,9 @@ pub fn run() { consumer_groups::commands::delete_consumer_group, consumer_groups::commands::preview_offset_reset, consumer_groups::commands::reset_consumer_group_offsets, + acls::commands::list_acls, + acls::commands::create_acls, + acls::commands::delete_acls, ]) .run(tauri::generate_context!()) .expect("error while running tauri application"); diff --git a/crates/kui_desktop/src/security_tests.rs b/crates/kui_desktop/src/security_tests.rs index 41e6b91..7a357da 100644 --- a/crates/kui_desktop/src/security_tests.rs +++ b/crates/kui_desktop/src/security_tests.rs @@ -208,6 +208,7 @@ const READ_ONLY_COMMANDS: &[&str] = &[ "consumer_group_lags", "topic_consumer_groups", "preview_offset_reset", + "list_acls", ]; #[test] diff --git a/crates/kui_kafka/src/acl_admin.rs b/crates/kui_kafka/src/acl_admin.rs new file mode 100644 index 0000000..1c02674 --- /dev/null +++ b/crates/kui_kafka/src/acl_admin.rs @@ -0,0 +1,312 @@ +//! ACLs through librdkafka's admin API (DescribeAcls, CreateAcls and +//! DeleteAcls), which rust-rdkafka doesn't wrap. + +use std::ffi::{CString, c_char}; +use std::ptr; + +use rd::rd_kafka_AclOperation_t as RdOperation; +use rd::rd_kafka_AclPermissionType_t as RdPermission; +use rd::rd_kafka_ResourcePatternType_t as RdPattern; +use rd::rd_kafka_ResourceType_t as RdResource; +use rdkafka::bindings as rd; + +use super::acls::{AclBinding, Operation, PatternType, Permission, ResourceType}; +use super::admin_request::{Admin, request, response_error, slice}; +use super::group_offsets::cstr; +use crate::{Error, Result}; + +/// Every ACL on the cluster, in no particular order. An ACL with a value this +/// version doesn't know is left out rather than shown as something it isn't. +pub fn describe(admin: &Admin) -> Result> { + let filter = Bindings::any_filter()?; + // SAFETY: see `request`. `filter` outlives the call, which copies it. + unsafe { + request( + admin, + rd::rd_kafka_admin_op_t::RD_KAFKA_ADMIN_OP_DESCRIBEACLS, + |rk, options, queue| rd::rd_kafka_DescribeAcls(rk, filter.0[0], options, queue), + |event| { + let result = rd::rd_kafka_event_DescribeAcls_result(event); + let mut count = 0; + let acls = rd::rd_kafka_DescribeAcls_result_acls(result, &mut count); + Ok(slice(acls, count).iter().filter_map(|&a| binding(a)).collect()) + }, + ) + } +} + +/// Creates `acls` in one request. Fails if Kafka refused any of them; the others may still have been created. +pub fn create(admin: &Admin, acls: &[AclBinding]) -> Result<()> { + if acls.is_empty() { + return Ok(()); + } + let mut bindings = Bindings::new(acls, Kind::Binding)?; + // SAFETY: see `request`. `bindings` outlives the call, which copies them. + unsafe { + request( + admin, + rd::rd_kafka_admin_op_t::RD_KAFKA_ADMIN_OP_CREATEACLS, + |rk, options, queue| rd::rd_kafka_CreateAcls(rk, bindings.0.as_mut_ptr(), bindings.0.len(), options, queue), + |event| { + let result = rd::rd_kafka_event_CreateAcls_result(event); + let mut count = 0; + let results = rd::rd_kafka_CreateAcls_result_acls(result, &mut count); + let errors = slice(results, count).iter().filter_map(|&r| error(rd::rd_kafka_acl_result_error(r))); + refused(errors.collect(), acls.len(), "created") + }, + ) + } +} + +/// Deletes exactly `acls` in one request and returns how many ACLs Kafka removed. +/// +/// Each filter repeats every field of its ACL, never a wildcard (`ANY`/`MATCH`), +/// so it can't also remove other ACLs that happen to match. +pub fn delete(admin: &Admin, acls: &[AclBinding]) -> Result { + if acls.is_empty() { + return Ok(0); + } + let mut filters = Bindings::new(acls, Kind::Filter)?; + // SAFETY: see `request`. `filters` outlives the call, which copies them. + unsafe { + request( + admin, + rd::rd_kafka_admin_op_t::RD_KAFKA_ADMIN_OP_DELETEACLS, + |rk, options, queue| rd::rd_kafka_DeleteAcls(rk, filters.0.as_mut_ptr(), filters.0.len(), options, queue), + |event| { + let result = rd::rd_kafka_event_DeleteAcls_result(event); + let mut count = 0; + let responses = rd::rd_kafka_DeleteAcls_result_responses(result, &mut count); + let mut deleted = 0; + let mut errors = Vec::new(); + for &response in slice(responses, count) { + match error(rd::rd_kafka_DeleteAcls_result_response_error(response)) { + Some(e) => errors.push(e), + None => { + let mut matched = 0; + rd::rd_kafka_DeleteAcls_result_response_matching_acls(response, &mut matched); + deleted += matched; + } + } + } + refused(errors, acls.len(), "deleted").map(|()| deleted) + }, + ) + } +} + +fn refused(errors: Vec, requested: usize, verb: &str) -> Result<()> { + let Some(first) = errors.first() else { return Ok(()) }; + Err(match requested { + 1 => Error::msg(first.to_string()), + _ => Error::msg(format!("{} of {requested} ACLs were not {verb}: {first}", errors.len())), + }) +} + +enum Kind { + Binding, + Filter, +} + +/// librdkafka ACL bindings (filters are the same type), destroyed on drop. +struct Bindings(Vec<*mut rd::rd_kafka_AclBinding_t>); + +impl Bindings { + fn new(acls: &[AclBinding], kind: Kind) -> Result { + let mut bindings = Bindings(Vec::with_capacity(acls.len())); + for acl in acls { + bindings.0.push(new_binding(acl, &kind)?); + } + Ok(bindings) + } + + /// A filter matching every ACL. + fn any_filter() -> Result { + let mut errstr = [0 as c_char; 512]; + // SAFETY: null strings mean "any"; errstr is a writable buffer of the given size. + let filter = unsafe { + rd::rd_kafka_AclBindingFilter_new( + RdResource::RD_KAFKA_RESOURCE_ANY, + ptr::null(), + RdPattern::RD_KAFKA_RESOURCE_PATTERN_ANY, + ptr::null(), + ptr::null(), + RdOperation::RD_KAFKA_ACL_OPERATION_ANY, + RdPermission::RD_KAFKA_ACL_PERMISSION_TYPE_ANY, + errstr.as_mut_ptr(), + errstr.len(), + ) + }; + checked(filter, &errstr).map(|f| Bindings(vec![f])) + } +} + +impl Drop for Bindings { + fn drop(&mut self) { + for &binding in &self.0 { + // SAFETY: each pointer came from AclBinding(Filter)_new and is destroyed once, here. + unsafe { rd::rd_kafka_AclBinding_destroy(binding) } + } + } +} + +fn new_binding(acl: &AclBinding, kind: &Kind) -> Result<*mut rd::rd_kafka_AclBinding_t> { + let text = |s: &str| CString::new(s).map_err(|_| Error::msg("ACL fields cannot contain NUL characters")); + let (name, principal, host) = (text(&acl.resource_name)?, text(&acl.principal)?, text(&acl.host)?); + let new = match kind { + Kind::Binding => rd::rd_kafka_AclBinding_new, + Kind::Filter => rd::rd_kafka_AclBindingFilter_new, + }; + let mut errstr = [0 as c_char; 512]; + // SAFETY: the strings are NUL-terminated and copied by librdkafka; errstr is a + // writable buffer of the given size. + let binding = unsafe { + new( + resource_type(acl.resource_type), + name.as_ptr(), + pattern_type(acl.pattern_type), + principal.as_ptr(), + host.as_ptr(), + operation(acl.operation), + permission(acl.permission), + errstr.as_mut_ptr(), + errstr.len(), + ) + }; + checked(binding, &errstr) +} + +fn checked(binding: *mut rd::rd_kafka_AclBinding_t, errstr: &[c_char]) -> Result<*mut rd::rd_kafka_AclBinding_t> { + if binding.is_null() { + // SAFETY: librdkafka NUL-terminates errstr when it fails. + return Err(Error::msg(unsafe { cstr(errstr.as_ptr()) })); + } + Ok(binding) +} + +/// The error librdkafka reports for one item of a result, if any. +unsafe fn error(e: *const rd::rd_kafka_error_t) -> Option { + if e.is_null() { + return None; + } + unsafe { Some(response_error(rd::rd_kafka_error_code(e), cstr(rd::rd_kafka_error_string(e)))) } +} + +unsafe fn binding(a: *const rd::rd_kafka_AclBinding_t) -> Option { + unsafe { + Some(AclBinding { + resource_type: match rd::rd_kafka_AclBinding_restype(a) { + RdResource::RD_KAFKA_RESOURCE_GROUP => ResourceType::Group, + RdResource::RD_KAFKA_RESOURCE_BROKER => ResourceType::Cluster, + RdResource::RD_KAFKA_RESOURCE_TOPIC => ResourceType::Topic, + RdResource::RD_KAFKA_RESOURCE_TRANSACTIONAL_ID => ResourceType::TransactionalId, + _ => return None, + }, + resource_name: cstr(rd::rd_kafka_AclBinding_name(a)), + pattern_type: match rd::rd_kafka_AclBinding_resource_pattern_type(a) { + RdPattern::RD_KAFKA_RESOURCE_PATTERN_LITERAL => PatternType::Literal, + RdPattern::RD_KAFKA_RESOURCE_PATTERN_PREFIXED => PatternType::Prefixed, + _ => return None, + }, + principal: cstr(rd::rd_kafka_AclBinding_principal(a)), + host: cstr(rd::rd_kafka_AclBinding_host(a)), + operation: match rd::rd_kafka_AclBinding_operation(a) { + RdOperation::RD_KAFKA_ACL_OPERATION_ALL => Operation::All, + RdOperation::RD_KAFKA_ACL_OPERATION_READ => Operation::Read, + RdOperation::RD_KAFKA_ACL_OPERATION_WRITE => Operation::Write, + RdOperation::RD_KAFKA_ACL_OPERATION_CREATE => Operation::Create, + RdOperation::RD_KAFKA_ACL_OPERATION_DELETE => Operation::Delete, + RdOperation::RD_KAFKA_ACL_OPERATION_ALTER => Operation::Alter, + RdOperation::RD_KAFKA_ACL_OPERATION_DESCRIBE => Operation::Describe, + RdOperation::RD_KAFKA_ACL_OPERATION_CLUSTER_ACTION => Operation::ClusterAction, + RdOperation::RD_KAFKA_ACL_OPERATION_DESCRIBE_CONFIGS => Operation::DescribeConfigs, + RdOperation::RD_KAFKA_ACL_OPERATION_ALTER_CONFIGS => Operation::AlterConfigs, + RdOperation::RD_KAFKA_ACL_OPERATION_IDEMPOTENT_WRITE => Operation::IdempotentWrite, + _ => return None, + }, + permission: match rd::rd_kafka_AclBinding_permission_type(a) { + RdPermission::RD_KAFKA_ACL_PERMISSION_TYPE_ALLOW => Permission::Allow, + RdPermission::RD_KAFKA_ACL_PERMISSION_TYPE_DENY => Permission::Deny, + _ => return None, + }, + }) + } +} + +fn resource_type(r: ResourceType) -> RdResource { + match r { + ResourceType::Topic => RdResource::RD_KAFKA_RESOURCE_TOPIC, + ResourceType::Group => RdResource::RD_KAFKA_RESOURCE_GROUP, + ResourceType::Cluster => RdResource::RD_KAFKA_RESOURCE_BROKER, + ResourceType::TransactionalId => RdResource::RD_KAFKA_RESOURCE_TRANSACTIONAL_ID, + } +} + +fn pattern_type(p: PatternType) -> RdPattern { + match p { + PatternType::Literal => RdPattern::RD_KAFKA_RESOURCE_PATTERN_LITERAL, + PatternType::Prefixed => RdPattern::RD_KAFKA_RESOURCE_PATTERN_PREFIXED, + } +} + +fn operation(o: Operation) -> RdOperation { + match o { + Operation::All => RdOperation::RD_KAFKA_ACL_OPERATION_ALL, + Operation::Read => RdOperation::RD_KAFKA_ACL_OPERATION_READ, + Operation::Write => RdOperation::RD_KAFKA_ACL_OPERATION_WRITE, + Operation::Create => RdOperation::RD_KAFKA_ACL_OPERATION_CREATE, + Operation::Delete => RdOperation::RD_KAFKA_ACL_OPERATION_DELETE, + Operation::Alter => RdOperation::RD_KAFKA_ACL_OPERATION_ALTER, + Operation::Describe => RdOperation::RD_KAFKA_ACL_OPERATION_DESCRIBE, + Operation::ClusterAction => RdOperation::RD_KAFKA_ACL_OPERATION_CLUSTER_ACTION, + Operation::DescribeConfigs => RdOperation::RD_KAFKA_ACL_OPERATION_DESCRIBE_CONFIGS, + Operation::AlterConfigs => RdOperation::RD_KAFKA_ACL_OPERATION_ALTER_CONFIGS, + Operation::IdempotentWrite => RdOperation::RD_KAFKA_ACL_OPERATION_IDEMPOTENT_WRITE, + } +} + +fn permission(p: Permission) -> RdPermission { + match p { + Permission::Allow => RdPermission::RD_KAFKA_ACL_PERMISSION_TYPE_ALLOW, + Permission::Deny => RdPermission::RD_KAFKA_ACL_PERMISSION_TYPE_DENY, + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::acls::CLUSTER_RESOURCE_NAME; + + #[test] + fn bindings_round_trip_through_librdkafka() { + let acl = AclBinding { + resource_type: ResourceType::Cluster, + resource_name: CLUSTER_RESOURCE_NAME.into(), + pattern_type: PatternType::Literal, + principal: "User:alice".into(), + host: "10.0.0.1".into(), + operation: Operation::IdempotentWrite, + permission: Permission::Deny, + }; + for kind in [Kind::Binding, Kind::Filter] { + let built = Bindings::new(std::slice::from_ref(&acl), kind).unwrap(); + // SAFETY: `built` owns a valid binding until it is dropped below. + assert_eq!(unsafe { binding(built.0[0]) }, Some(acl.clone())); + } + } + + #[test] + fn nul_in_a_field_is_an_error_not_a_truncated_name() { + let mut acl = AclBinding { + resource_type: ResourceType::Topic, + resource_name: "orders".into(), + pattern_type: PatternType::Literal, + principal: "User:alice".into(), + host: "*".into(), + operation: Operation::Read, + permission: Permission::Allow, + }; + acl.resource_name = "or\0ders".into(); + assert!(Bindings::new(&[acl], Kind::Binding).is_err()); + } +} diff --git a/crates/kui_kafka/src/acls.rs b/crates/kui_kafka/src/acls.rs new file mode 100644 index 0000000..05e07c3 --- /dev/null +++ b/crates/kui_kafka/src/acls.rs @@ -0,0 +1,237 @@ +//! Kafka ACLs as plain data, and the checks a new ACL must pass before it is +//! sent. The librdkafka calls that read and change them are in `acl_admin`. + +use serde::{Deserialize, Serialize}; + +use crate::{Error, Result}; + +/// The name a cluster resource always has; Kafka rejects any other. +pub const CLUSTER_RESOURCE_NAME: &str = "kafka-cluster"; + +#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)] +#[serde(rename_all = "camelCase")] +pub enum ResourceType { + Topic, + Group, + Cluster, + TransactionalId, +} + +/// How `resource_name` matches resources. +#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)] +#[serde(rename_all = "camelCase")] +pub enum PatternType { + /// Exactly this name, or every resource when the name is `*`. + Literal, + /// Every resource whose name starts with it. + Prefixed, +} + +#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)] +#[serde(rename_all = "camelCase")] +pub enum Operation { + All, + Read, + Write, + Create, + Delete, + Alter, + Describe, + ClusterAction, + DescribeConfigs, + AlterConfigs, + IdempotentWrite, +} + +#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)] +#[serde(rename_all = "camelCase")] +pub enum Permission { + Allow, + Deny, +} + +/// One ACL: `principal` from `host` is allowed or denied `operation` on the resource. +#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] +#[serde(rename_all = "camelCase")] +pub struct AclBinding { + pub resource_type: ResourceType, + pub resource_name: String, + pub pattern_type: PatternType, + /// e.g. `User:alice`, or `User:*` for everyone. + pub principal: String, + /// An IP address, or `*` for any host. + pub host: String, + pub operation: Operation, + pub permission: Permission, +} + +impl ResourceType { + /// The operations Kafka checks on this kind of resource. An ACL for any other + /// is accepted by the broker but never grants or denies anything. + pub fn operations(self) -> &'static [Operation] { + use Operation::*; + match self { + ResourceType::Topic => &[All, Read, Write, Create, Delete, Alter, Describe, DescribeConfigs, AlterConfigs], + ResourceType::Group => &[All, Read, Delete, Describe], + ResourceType::Cluster => { + &[All, Create, Alter, Describe, ClusterAction, DescribeConfigs, AlterConfigs, IdempotentWrite] + } + ResourceType::TransactionalId => &[All, Write, Describe], + } + } +} + +/// Rejects an ACL that Kafka would refuse or that could never take effect. +/// Values are quoted in the messages: none of these fields are secrets. +pub fn validate(acl: &AclBinding) -> Result<()> { + let name = acl.resource_name.as_str(); + if name.trim().is_empty() { + return Err(Error::msg("Resource name is required")); + } + if name != name.trim() { + return Err(Error::msg(format!("Resource name \"{name}\" has leading or trailing spaces"))); + } + if acl.resource_type == ResourceType::Cluster + && (name != CLUSTER_RESOURCE_NAME || acl.pattern_type != PatternType::Literal) + { + return Err(Error::msg(format!("A cluster ACL must use the literal name \"{CLUSTER_RESOURCE_NAME}\""))); + } + if acl.pattern_type == PatternType::Prefixed && name == "*" { + return Err(Error::msg("\"*\" already matches every resource: use a literal pattern")); + } + let principal = acl.principal.as_str(); + let well_formed = principal.trim() == principal + && principal.split_once(':').is_some_and(|(kind, who)| !kind.trim().is_empty() && !who.trim().is_empty()); + if !well_formed { + return Err(Error::msg(format!( + "Principal \"{principal}\" must look like Type:name, e.g. User:alice or User:*" + ))); + } + if acl.host.trim().is_empty() || acl.host.trim() != acl.host { + return Err(Error::msg("Host must be an IP address, or * for any host")); + } + if !acl.resource_type.operations().contains(&acl.operation) { + return Err(Error::msg(format!( + "{:?} does not apply to a {:?} resource, so this ACL would have no effect", + acl.operation, acl.resource_type + ))); + } + let fields = [name, acl.principal.as_str(), acl.host.as_str()]; + if fields.iter().any(|f| f.contains('\0')) { + return Err(Error::msg("ACL fields cannot contain NUL characters")); + } + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn acl() -> AclBinding { + AclBinding { + resource_type: ResourceType::Topic, + resource_name: "orders".into(), + pattern_type: PatternType::Literal, + principal: "User:alice".into(), + host: "*".into(), + operation: Operation::Read, + permission: Permission::Allow, + } + } + + fn rejects(change: impl FnOnce(&mut AclBinding)) -> bool { + let mut a = acl(); + change(&mut a); + validate(&a).is_err() + } + + #[test] + fn accepts_ordinary_acls() { + assert!(validate(&acl()).is_ok()); + let mut wildcard = acl(); + wildcard.resource_name = "*".into(); + wildcard.principal = "User:*".into(); + assert!(validate(&wildcard).is_ok()); + let mut cluster = acl(); + cluster.resource_type = ResourceType::Cluster; + cluster.resource_name = CLUSTER_RESOURCE_NAME.into(); + cluster.operation = Operation::IdempotentWrite; + assert!(validate(&cluster).is_ok()); + } + + #[test] + fn rejects_malformed_principals() { + for principal in ["alice", "User:", ":alice", "", " User:alice"] { + assert!(rejects(|a| a.principal = principal.into()), "principal {principal:?}"); + } + } + + #[test] + fn rejects_blank_or_padded_names_and_hosts() { + assert!(rejects(|a| a.resource_name = " ".into())); + assert!(rejects(|a| a.resource_name = "orders ".into())); + assert!(rejects(|a| a.host = String::new())); + assert!(rejects(|a| a.host = " *".into())); + } + + #[test] + fn cluster_acls_need_the_fixed_literal_name() { + let cluster = |a: &mut AclBinding| { + a.resource_type = ResourceType::Cluster; + a.operation = Operation::Describe; + }; + assert!(rejects(|a| { + cluster(a); + a.resource_name = "prod".into(); + })); + assert!(rejects(|a| { + cluster(a); + a.resource_name = CLUSTER_RESOURCE_NAME.into(); + a.pattern_type = PatternType::Prefixed; + })); + } + + #[test] + fn rejects_a_prefixed_wildcard() { + assert!(rejects(|a| { + a.resource_name = "*".into(); + a.pattern_type = PatternType::Prefixed; + })); + } + + #[test] + fn rejects_operations_that_never_apply_to_the_resource() { + assert!(rejects(|a| a.operation = Operation::IdempotentWrite)); + assert!(rejects(|a| { + a.resource_type = ResourceType::Group; + a.operation = Operation::Write; + })); + } + + #[test] + fn rejects_nul_characters() { + assert!(rejects(|a| a.resource_name = "or\0ders".into())); + assert!(rejects(|a| a.principal = "User:al\0ice".into())); + } + + #[test] + fn every_resource_allows_all() { + for r in [ResourceType::Topic, ResourceType::Group, ResourceType::Cluster, ResourceType::TransactionalId] { + assert!(r.operations().contains(&Operation::All), "{r:?}"); + } + } + + #[test] + fn serializes_as_camel_case_for_the_ui() { + let json = serde_json::to_value(AclBinding { + resource_type: ResourceType::TransactionalId, + operation: Operation::IdempotentWrite, + ..acl() + }) + .unwrap(); + assert_eq!(json["resourceType"], "transactionalId"); + assert_eq!(json["operation"], "idempotentWrite"); + assert_eq!(json["patternType"], "literal"); + assert_eq!(json["permission"], "allow"); + } +} diff --git a/crates/kui_kafka/src/admin_request.rs b/crates/kui_kafka/src/admin_request.rs new file mode 100644 index 0000000..3e7d127 --- /dev/null +++ b/crates/kui_kafka/src/admin_request.rs @@ -0,0 +1,76 @@ +//! The plumbing shared by the librdkafka admin calls rust-rdkafka doesn't wrap +//! (consumer groups, ACLs): one request on its own queue, waited for in place. + +use std::ffi::c_char; +use std::time::Duration; + +use rdkafka::admin::AdminClient; +use rdkafka::bindings as rd; +use rdkafka::client::DefaultClientContext; + +use super::TIMEOUT; +use super::group_offsets::cstr; +use crate::{Error, Result}; + +pub(crate) type Admin = AdminClient; + +/// Sends one admin request on its own queue and hands the result event to `read`. +/// +/// SAFETY: `rk` stays valid while `admin` is borrowed. librdkafka copies the +/// options and the request arguments when the request is sent, and the queue is +/// reference counted: a reply arriving after it is destroyed (on timeout) is dropped. +pub(crate) unsafe fn request( + admin: &Admin, + op: rd::rd_kafka_admin_op_t, + send: impl FnOnce(*mut rd::rd_kafka_t, *const rd::rd_kafka_AdminOptions_t, *mut rd::rd_kafka_queue_t), + read: impl FnOnce(*mut rd::rd_kafka_event_t) -> Result, +) -> Result { + unsafe { + let rk = admin.inner().native_ptr(); + let queue = rd::rd_kafka_queue_new(rk); + let options = rd::rd_kafka_AdminOptions_new(rk, op); + let mut errstr = [0 as c_char; 256]; + rd::rd_kafka_AdminOptions_set_request_timeout( + options, + TIMEOUT.as_millis() as i32, + errstr.as_mut_ptr(), + errstr.len(), + ); + send(rk, options, queue); + rd::rd_kafka_AdminOptions_destroy(options); + + let event = rd::rd_kafka_queue_poll(queue, (TIMEOUT + Duration::from_secs(1)).as_millis() as i32); + let result = if event.is_null() { + Err(Error::msg("Timed out waiting for Kafka to answer")) + } else { + match rd::rd_kafka_event_error(event) { + rd::rd_kafka_resp_err_t::RD_KAFKA_RESP_ERR_NO_ERROR => read(event), + code => Err(response_error(code, cstr(rd::rd_kafka_event_error_string(event)))), + } + }; + if !event.is_null() { + rd::rd_kafka_event_destroy(event); + } + rd::rd_kafka_queue_destroy(queue); + result + } +} + +/// An error Kafka returned for a request, reworded where the raw text doesn't say what to do. +pub(crate) fn response_error(code: rd::rd_kafka_resp_err_t, message: String) -> Error { + match code { + rd::rd_kafka_resp_err_t::RD_KAFKA_RESP_ERR_SECURITY_DISABLED => Error::msg( + "This cluster has no authorizer, so it has no ACLs. \ + Set authorizer.class.name on the brokers to manage ACLs.", + ), + rd::rd_kafka_resp_err_t::RD_KAFKA_RESP_ERR_CLUSTER_AUTHORIZATION_FAILED => { + Error::msg(format!("This connection is not allowed to do that: {message}")) + } + _ => Error::msg(message), + } +} + +/// A C array of `count` pointers as a slice; empty when null. +pub(crate) unsafe fn slice<'a, T>(ptr: *mut *const T, count: usize) -> &'a [*const T] { + if ptr.is_null() || count == 0 { &[] } else { unsafe { std::slice::from_raw_parts(ptr, count) } } +} diff --git a/crates/kui_kafka/src/groups.rs b/crates/kui_kafka/src/groups.rs index 7e33a42..5f7b22c 100644 --- a/crates/kui_kafka/src/groups.rs +++ b/crates/kui_kafka/src/groups.rs @@ -8,18 +8,13 @@ use std::collections::BTreeMap; use std::ffi::{CString, c_char}; -use std::time::Duration; -use rdkafka::admin::AdminClient; use rdkafka::bindings as rd; -use rdkafka::client::DefaultClientContext; -use super::TIMEOUT; +use super::admin_request::{Admin, request, slice}; use super::group_offsets::cstr; use crate::{Error, Result}; -type Admin = AdminClient; - pub struct GroupDescription { pub name: String, /// e.g. `Stable`, `Empty`, `PreparingRebalance`, `Assigning`, `Dead`. @@ -158,49 +153,3 @@ unsafe fn member(m: *const rd::rd_kafka_MemberDescription_t) -> MemberDescriptio } } } - -/// Sends one admin request on its own queue and hands the result event to `read`. -/// -/// SAFETY: `rk` stays valid while `admin` is borrowed. librdkafka copies the -/// options when the request is sent, and the queue is reference counted: a -/// reply arriving after it is destroyed (on timeout) is dropped. -unsafe fn request( - admin: &Admin, - op: rd::rd_kafka_admin_op_t, - send: impl FnOnce(*mut rd::rd_kafka_t, *const rd::rd_kafka_AdminOptions_t, *mut rd::rd_kafka_queue_t), - read: impl FnOnce(*mut rd::rd_kafka_event_t) -> Result, -) -> Result { - unsafe { - let rk = admin.inner().native_ptr(); - let queue = rd::rd_kafka_queue_new(rk); - let options = rd::rd_kafka_AdminOptions_new(rk, op); - let mut errstr = [0 as c_char; 256]; - rd::rd_kafka_AdminOptions_set_request_timeout( - options, - TIMEOUT.as_millis() as i32, - errstr.as_mut_ptr(), - errstr.len(), - ); - send(rk, options, queue); - rd::rd_kafka_AdminOptions_destroy(options); - - let event = rd::rd_kafka_queue_poll(queue, (TIMEOUT + Duration::from_secs(1)).as_millis() as i32); - let result = if event.is_null() { - Err(Error::msg("Timed out reading consumer groups")) - } else if rd::rd_kafka_event_error(event) != rd::rd_kafka_resp_err_t::RD_KAFKA_RESP_ERR_NO_ERROR { - Err(Error::msg(cstr(rd::rd_kafka_event_error_string(event)))) - } else { - read(event) - }; - if !event.is_null() { - rd::rd_kafka_event_destroy(event); - } - rd::rd_kafka_queue_destroy(queue); - result - } -} - -/// A C array of `count` pointers as a slice; empty when null. -unsafe fn slice<'a, T>(ptr: *mut *const T, count: usize) -> &'a [*const T] { - if ptr.is_null() || count == 0 { &[] } else { unsafe { std::slice::from_raw_parts(ptr, count) } } -} diff --git a/crates/kui_kafka/src/lib.rs b/crates/kui_kafka/src/lib.rs index cab32c6..2765e3a 100644 --- a/crates/kui_kafka/src/lib.rs +++ b/crates/kui_kafka/src/lib.rs @@ -1,7 +1,12 @@ //! Shared Kafka infrastructure for KUI: cluster config, clients, metadata, -//! offsets and consumer groups. Every app feature builds on this crate, but +//! offsets, consumer groups and ACLs. Every app feature builds on this crate, but //! features never depend on each other. +#[allow(unsafe_code)] // librdkafka calls rust-rdkafka does not wrap +pub mod acl_admin; +pub mod acls; +#[allow(unsafe_code)] // librdkafka admin requests rust-rdkafka does not wrap +mod admin_request; mod client; mod cluster; pub mod connection; diff --git a/docker-compose.yml b/docker-compose.yml index 8ac0b1f..15165d0 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -4,8 +4,12 @@ # bun run test:e2e full end-to-end test run (own fresh Kafka) # docker compose down stop and remove everything # +# Demo data, ACLs and the authorizer setup are described in docs/LOCAL_KAFKA.md. +# # Kafka has two listeners because a broker tells clients which address to # reconnect to: your Mac must use localhost:9092, other containers kafka:29092. +# The dev broker adds a third, localhost:9094, where clients log in as the demo +# users so the seeded ACLs are enforced (see examples/acl-demo). name: kui services: @@ -14,12 +18,13 @@ services: container_name: kui-kafka ports: - "9092:9092" + - "9094:9094" environment: KAFKA_NODE_ID: 1 KAFKA_PROCESS_ROLES: broker,controller - KAFKA_LISTENERS: INTERNAL://:29092,EXTERNAL://:9092,CONTROLLER://:9093 - KAFKA_ADVERTISED_LISTENERS: INTERNAL://kafka:29092,EXTERNAL://localhost:9092 - KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: INTERNAL:PLAINTEXT,EXTERNAL:PLAINTEXT,CONTROLLER:PLAINTEXT + KAFKA_LISTENERS: INTERNAL://:29092,EXTERNAL://:9092,CONTROLLER://:9093,SASL://:9094 + KAFKA_ADVERTISED_LISTENERS: INTERNAL://kafka:29092,EXTERNAL://localhost:9092,SASL://localhost:9094 + KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: INTERNAL:PLAINTEXT,EXTERNAL:PLAINTEXT,CONTROLLER:PLAINTEXT,SASL:SASL_PLAINTEXT KAFKA_INTER_BROKER_LISTENER_NAME: INTERNAL KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER KAFKA_CONTROLLER_QUORUM_VOTERS: 1@localhost:9093 @@ -28,13 +33,26 @@ services: KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1 KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: 0 KAFKA_NUM_PARTITIONS: 3 + # ACLs need an authorizer. Every client here, the controller included, connects over + # PLAINTEXT as ANONYMOUS, which as a super user may do anything: ACLs can be managed + # without locking anyone out. + KAFKA_AUTHORIZER_CLASS_NAME: org.apache.kafka.metadata.authorizer.StandardAuthorizer + KAFKA_SUPER_USERS: User:ANONYMOUS + # Demo logins for the SASL listener, one per principal in docker/kafka-seed.sh (password: name-secret). + # They are not super users, so on this listener the ACLs decide. `nobody` has no ACLs at all. + KAFKA_SASL_ENABLED_MECHANISMS: PLAIN + KAFKA_LISTENER_NAME_SASL_PLAIN_SASL_JAAS_CONFIG: >- + org.apache.kafka.common.security.plain.PlainLoginModule required + user_billing-service="billing-service-secret" user_order-service="order-service-secret" + user_analytics="analytics-secret" user_payments="payments-secret" user_auditor="auditor-secret" + user_intern="intern-secret" user_nobody="nobody-secret"; healthcheck: test: /opt/kafka/bin/kafka-broker-api-versions.sh --bootstrap-server localhost:9092 > /dev/null interval: 5s timeout: 10s retries: 20 - # One-shot: creates demo topics, messages and a consumer group with lag. Safe to re-run. + # One-shot: creates demo topics, messages, a consumer group with lag and ACLs. Safe to re-run. kafka-seed: image: apache/kafka:latest depends_on: @@ -70,6 +88,11 @@ services: KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1 KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: 0 KAFKA_NUM_PARTITIONS: 3 + # ACLs need an authorizer. Every client here, the controller included, connects over + # PLAINTEXT as ANONYMOUS, which as a super user may do anything: ACLs can be managed + # without locking anyone out. + KAFKA_AUTHORIZER_CLASS_NAME: org.apache.kafka.metadata.authorizer.StandardAuthorizer + KAFKA_SUPER_USERS: User:ANONYMOUS healthcheck: test: /opt/kafka/bin/kafka-broker-api-versions.sh --bootstrap-server localhost:29092 > /dev/null interval: 5s diff --git a/docker/kafka-seed.sh b/docker/kafka-seed.sh index 09db49b..52be178 100755 --- a/docker/kafka-seed.sh +++ b/docker/kafka-seed.sh @@ -7,6 +7,9 @@ # demo.catalog 30 wide product documents: dynamic-key maps, arrays of arrays, mixed arrays, edge-case numbers # demo.webhooks 40 webhook envelopes whose payload is JSON encoded 2-3 levels deep, base64 or NDJSON # demo.untrusted 6 messages carrying HTML/script payloads in keys, values, JSON keys and headers (e2e: they must render inert) +# demo.payments empty; `payments` may write to it, so bun run kafka:acl-demo has a topic to produce to +# ACLs service principals covering every resource type, literal and prefixed patterns, +# wildcards, DENY rules and host restrictions # Each topic is created only if missing, so re-running adds new demo topics to an old broker. set -euo pipefail BIN=/opt/kafka/bin @@ -237,3 +240,41 @@ else --reader-property parse.key=true --reader-property key.separator='|' echo "Seeded demo.untrusted." fi + +if has_topic demo.payments; then + echo "demo.payments already seeded." +else + $BIN/kafka-topics.sh --bootstrap-server "$BOOTSTRAP" --create --topic demo.payments --partitions 1 +fi + +# Clients on the PLAINTEXT listeners are ANONYMOUS, a super user, so these ACLs only restrict the demo +# users logging in on the dev broker's SASL listener (see docker-compose.yml). +# Skipped when any seeded principal still has ACLs, so ones deleted in the UI don't come back on every start. +acl() { $BIN/kafka-acls.sh --bootstrap-server "$BOOTSTRAP" --add "$@" > /dev/null; } + +if $BIN/kafka-acls.sh --bootstrap-server "$BOOTSTRAP" --list | grep -q 'principal=User:billing-service,'; then + echo "ACLs already seeded." +else + acl --allow-principal User:billing-service --operation Read --operation Describe --topic demo.orders + acl --allow-principal User:billing-service --operation Read --group demo-billing + acl --allow-principal User:order-service --operation Write --operation Describe --topic demo.orders + acl --allow-principal User:order-service --operation Read --topic demo.customers + acl --allow-principal User:analytics --allow-principal User:data-science --operation Read --operation Describe \ + --topic demo. --resource-pattern-type prefixed + acl --allow-principal User:analytics --operation Read --group analytics- --resource-pattern-type prefixed + acl --allow-principal User:payments --operation Write --operation Describe \ + --transactional-id payments- --resource-pattern-type prefixed + acl --allow-principal User:payments --operation IdempotentWrite --cluster + acl --allow-principal User:payments --operation Write --operation Describe --topic demo.payments + acl --allow-principal User:auditor --operation Describe --operation DescribeConfigs --topic '*' + acl --allow-principal User:auditor --operation Describe --group '*' + acl --allow-principal User:auditor --operation Describe --operation DescribeConfigs --cluster + acl --allow-principal User:ops --allow-host 10.0.0.5 --operation Alter --operation AlterConfigs --cluster + # The intern may read and write every demo topic, but the DENY on all topics wins for writes and deletes. + acl --allow-principal User:intern --operation Read --operation Write --operation Describe \ + --topic demo. --resource-pattern-type prefixed + acl --allow-principal User:intern --operation Read --group intern- --resource-pattern-type prefixed + acl --deny-principal User:intern --operation Write --operation Delete --topic '*' + acl --deny-principal User:legacy-app --deny-host 192.168.1.10 --operation Read --topic demo.untrusted + echo "Seeded ACLs." +fi diff --git a/docs/CODE_STANDARDS.md b/docs/CODE_STANDARDS.md index 0812b9f..e308e41 100644 --- a/docs/CODE_STANDARDS.md +++ b/docs/CODE_STANDARDS.md @@ -30,6 +30,10 @@ - `unsafe` is denied, and `dbg!`, `todo!`, `println!` warn (clippy runs with `-D warnings`). No `unwrap`/`expect` outside tests. +- The one exception is calling librdkafka APIs that rust-rdkafka doesn't wrap (consumer groups, ACLs): those + modules in `kui_kafka` opt in with `#[allow(unsafe_code)]`, give every `unsafe` block a `SAFETY:` comment, + free what they allocate on drop, and expose only safe functions. Keep pure types and checks in a module of + their own (`acls.rs` beside `acl_admin.rs`) so they stay outside the exception. - Make invalid states unrepresentable: enums over string flags, `Option` over sentinel values, newtypes where two values of the same type are easy to swap. - Borrow rather than clone in hot paths; take `&str`/`&[T]` and return owned data only when the caller needs it. diff --git a/docs/LOCAL_KAFKA.md b/docs/LOCAL_KAFKA.md new file mode 100644 index 0000000..250ed1c --- /dev/null +++ b/docs/LOCAL_KAFKA.md @@ -0,0 +1,185 @@ +# Local Kafka + +`docker-compose.yml` runs a single-node KRaft broker for development, and a separate throwaway one for the e2e +suite. Both are seeded by [`docker/kafka-seed.sh`](../docker/kafka-seed.sh). + +```bash +bun run kafka:up # broker on localhost:9092 (+ 9094 for demo logins), then seeds it +bun run kafka:down # stop and remove everything, data included +docker compose run --rm kafka-seed # re-run the seed against the running broker +bun run kafka:acl-demo # prove the seeded ACLs are enforced (see below) +``` + +In KUI, add a cluster with bootstrap `localhost:9092` and no authentication. + +| Listener | Who you are | ACLs | +|------------------|-------------------------------------|-----------------------------------------| +| `localhost:9092` | `User:ANONYMOUS`, a super user | bypassed: use it to browse and manage | +| `localhost:9094` | a demo login, over SASL/PLAIN | enforced: use it to see what a user can | +| `kafka:29092` | `User:ANONYMOUS`, other containers | bypassed | + +## Demo data + +| Topic | What it's for | +|------------------|----------------------------------------------------------------------------------------------| +| `demo.orders` | 50 flat JSON orders. Consumer group `demo-billing` has read 30, so it shows lag | +| `demo.customers` | 7 customers on a compacted topic | +| `demo.events` | 60 nested events of six shapes, with headers, for trying the message query | +| `demo.analytics` | 40 tracking events whose `properties` is JSON written as a string | +| `demo.catalog` | 30 wide product documents: dynamic-key maps, arrays of arrays, edge-case numbers | +| `demo.webhooks` | 40 webhook envelopes with JSON encoded 2-3 levels deep, base64 or NDJSON | +| `demo.untrusted` | HTML and script payloads in keys, values and headers. The e2e suite checks they render inert | +| `demo.payments` | Starts empty. The only topic the ACL demo writes to, as `payments` | + +The seed only creates a topic, or the ACL set, when it's missing. Re-running it after pulling new seed data +adds what's new without duplicating what's there. + +## ACLs + +### How the brokers are set up + +ACLs need an authorizer on the broker. Without one, the ACLs page shows "This cluster has no authorizer". Both +compose brokers set: + +```yaml +KAFKA_AUTHORIZER_CLASS_NAME: org.apache.kafka.metadata.authorizer.StandardAuthorizer +KAFKA_SUPER_USERS: User:ANONYMOUS +``` + +On the PLAINTEXT listeners every client (KUI, the seed, the controller itself) connects as `User:ANONYMOUS`. +As a super user it skips ACL checks, so you can add any ACL, including DENY rules, and still use the cluster. + +The dev broker also has a SASL/PLAIN listener on `localhost:9094` with one login per demo principal. Those users +aren't super users, so there the ACLs decide: + +| Login | Password | +|-------------------|-------------------------------------------| +| `billing-service` | `billing-service-secret` | +| `order-service` | `order-service-secret` | +| `analytics` | `analytics-secret` | +| `payments` | `payments-secret` | +| `auditor` | `auditor-secret` | +| `intern` | `intern-secret` | +| `nobody` | `nobody-secret` (has no ACLs at all) | + +They're listed in `KAFKA_LISTENER_NAME_SASL_PLAIN_SASL_JAAS_CONFIG` in `docker-compose.yml`. They are +demo credentials, on a port bound to your machine, for a broker you throw away. Don't reuse them. The e2e broker +has no SASL listener; its specs only need ACLs to exist. + +To see the cluster through a user's eyes, add a second cluster in KUI with bootstrap `localhost:9094`, security +protocol `SASL_PLAINTEXT`, mechanism `PLAIN` and one of the logins above: + +- `auditor` sees every topic and group and can list the ACLs, but any produce or delete is refused. +- `analytics` sees only the `demo.` topics. +- `nobody` sees no topics, and the ACLs page reports it lacks Describe on the cluster. + +On a real cluster, set the same properties in each broker's `server.properties` +(`authorizer.class.name=org.apache.kafka.metadata.authorizer.StandardAuthorizer` for KRaft), and list your admin +principals in `super.users` before restarting, or you'll lock them out. + +### Seeded ACLs + +Each row of the ACLs page has one principal, operation and resource. The seed creates 30 of them, chosen so that +every column and filter has something to show, and so the [ACL demo](#proving-the-acls-are-enforced) has +something to prove: + +| Principal | Permission | Operations | Resource | Host | +|-----------------------------------|------------|-------------------------------|-----------------------------------|----------------| +| `billing-service` | Allow | Read, Describe | topic `demo.orders` | `*` | +| `billing-service` | Allow | Read | group `demo-billing` | `*` | +| `order-service` | Allow | Write, Describe | topic `demo.orders` | `*` | +| `order-service` | Allow | Read | topic `demo.customers` | `*` | +| `analytics`, `data-science` | Allow | Read, Describe | topic prefix `demo.` | `*` | +| `analytics` | Allow | Read | group prefix `analytics-` | `*` | +| `payments` | Allow | Write, Describe | txn ID prefix `payments-` | `*` | +| `payments` | Allow | IdempotentWrite | cluster | `*` | +| `payments` | Allow | Write, Describe | topic `demo.payments` | `*` | +| `auditor` | Allow | Describe, DescribeConfigs | topic `*` | `*` | +| `auditor` | Allow | Describe | group `*` | `*` | +| `auditor` | Allow | Describe, DescribeConfigs | cluster | `*` | +| `ops` | Allow | Alter, AlterConfigs | cluster | `10.0.0.5` | +| `intern` | Allow | Read, Write, Describe | topic prefix `demo.` | `*` | +| `intern` | Allow | Read | group prefix `intern-` | `*` | +| `intern` | Deny | Write, Delete | topic `*` | `*` | +| `legacy-app` | Deny | Read | topic `demo.untrusted` | `192.168.1.10` | + +All principals are `User:` principals. Some things to try in the UI: + +- Filter by `auditor` to see the wildcard (`*`) resource names. +- Filter by `demo.` to see a prefixed pattern next to the literal `demo.orders` ACLs. +- Filter by `10.0.0.5` or `192.168.1.10` to see host restrictions. +- Filter by `intern` to see an Allow and a Deny that both cover writing to `demo.payments`. The Deny wins. + +`data-science`, `ops` and `legacy-app` have no login, and the host-restricted rules can't be triggered from your +machine, so those rows are only for display. + +The seed skips the ACLs if `User:billing-service` still has any. Deleting a few seeded ACLs in the UI won't undo +itself on the next `kafka:up`. Delete all of `billing-service`'s ACLs, or run `kafka:down`, to get the full set +back. + +The e2e broker is seeded with the same ACLs. The ACL specs create their own principal with `uniqueName()` and +only count rows for it, so the seeded ACLs don't change the counts they check. Keep new specs scoped the same way. + +### Proving the ACLs are enforced + +[`examples/acl-demo`](../examples/acl-demo) is a small TypeScript project (KafkaJS, run with Bun) that logs in +on `localhost:9094` as the demo users: + +```bash +bun run kafka:acl-demo +``` + +It tries 18 actions, compares each one with what the ACLs say should happen, and exits 1 on any mismatch: + +```text +Literal topic and group ACLs + ok billing-service read demo.orders as group demo-billing allowed + ok billing-service read demo.orders as group billing-replay denied + ... +DENY beats ALLOW: the intern may use demo.*, but writes to any topic are denied + ok intern read demo.customers as group intern-onboarding allowed + ok intern write to demo.payments denied + ... +Every check matched the ACLs. +``` + +Delete an ACL in KUI (say, `billing-service`'s Read on group `demo-billing`) and run it again: that check +turns into a `FAIL`. The project also has one long-running example per service, see its +[README](../examples/acl-demo/README.md). + +### Managing ACLs from the command line + +The compose broker ships with Kafka's CLI tools. Use them to check what KUI did, or to set up a case the seed +doesn't cover: + +```bash +acls() { docker exec kui-kafka /opt/kafka/bin/kafka-acls.sh --bootstrap-server localhost:9092 "$@"; } + +acls --list # everything +acls --list --principal User:auditor # one principal +acls --list --topic demo.orders # one resource + +# Allow a consumer to read every topic starting with `audit.`, using any group starting with `audit-` +acls --add --allow-principal User:audit-reader --operation Read --operation Describe \ + --topic audit. --group audit- --resource-pattern-type prefixed + +# Deny writes from one host +acls --add --deny-principal User:batch --deny-host 10.1.2.3 --operation Write --topic demo.events + +# Remove an ACL. Without --force it asks for confirmation. +acls --remove --force --allow-principal User:audit-reader --operation Read --topic audit. \ + --resource-pattern-type prefixed +``` + +`--resource-pattern-type` defaults to `literal`, so `acls --list --topic audit.` finds nothing for the +prefixed ACL above. Pass `prefixed` to reach it, or `any` / `match` when listing. KUI's delete always repeats every field of the ACL, so it removes +exactly one ACL and never acts as a filter. + +### Adding to the seed + +ACLs live at the end of `docker/kafka-seed.sh`, inside the `billing-service` check. Add an `acl ...` line there. +It takes the same arguments as `kafka-acls.sh --add`. A new principal also needs a login in +`docker-compose.yml` and in the `DemoUser` type in `examples/acl-demo/kafka.ts`, and a check in +`examples/acl-demo/check.ts` that shows what the ACL allows and what it doesn't. Group operations on one resource into a single call, since +each call starts a JVM and adds a second or two to every fresh `kafka:up`. To get a new ACL onto an existing dev +broker, either delete `billing-service`'s ACLs or run `kafka:down` first. diff --git a/e2e/helpers.ts b/e2e/helpers.ts index 5cbee7f..007e185 100644 --- a/e2e/helpers.ts +++ b/e2e/helpers.ts @@ -33,7 +33,7 @@ export async function expectToast(text: string) { ); } -export async function goTo(page: "Topics" | "Consumer groups" | "Brokers") { +export async function goTo(page: "Topics" | "Consumer groups" | "Brokers" | "ACLs") { // A sheet or dialog that is still fading out covers the sidebar and would intercept the click. await openSheet().waitForExist({ reverse: true }); await openDialog().waitForExist({ reverse: true }); @@ -97,6 +97,8 @@ export const CHANGING_COMMANDS = [ "generate_records", "delete_consumer_group", "reset_consumer_group_offsets", + "create_acls", + "delete_acls", "install_update", ]; diff --git a/e2e/specs/08-no-unprompted-changes.e2e.ts b/e2e/specs/08-no-unprompted-changes.e2e.ts index 14c08d1..c27ff21 100644 --- a/e2e/specs/08-no-unprompted-changes.e2e.ts +++ b/e2e/specs/08-no-unprompted-changes.e2e.ts @@ -58,6 +58,9 @@ describe("Nothing changes without the user's consent", () => { await expect(openSheet()).toHaveText(expect.stringContaining("Consumed 30")); await browser.keys("Escape"); await openSheet().waitForExist({ reverse: true }); + + await goTo("ACLs"); + expect(await commandsSent()).toContain("list_acls"); }); it("ignores stray keys on a focused topic row", async () => { @@ -93,6 +96,7 @@ describe("Nothing changes without the user's consent", () => { for (const [key, heading] of [ ["1", "Brokers"], ["3", "Consumer groups"], + ["4", "ACLs"], ["2", "Topics"], ]) { await pressMod(key); @@ -294,6 +298,26 @@ describe("Nothing changes without the user's consent", () => { }); }); + describe("ACLs", () => { + before(async () => { + await goTo("ACLs"); + }); + + it("creates nothing when the create dialog is filled in and closed", async () => { + await button("New ACL").click(); + await expect(openDialog()).toBeDisplayed(); + await $("#acl-principal").clearValue(); + await $("#acl-principal").setValue("User:not-created"); + await $("#acl-resource-name").setValue("demo.orders"); + await $("#acl-op-read").click(); + // Enter in a text field submits the form, so only Escape is pressed here. + await browser.keys("Escape"); + await openDialog().waitForExist({ reverse: true }); + await $('input[aria-label="Filter ACLs"]').setValue("not-created"); + await expect($("td=User:not-created")).not.toBeExisting(); + }); + }); + it("leaves the seeded topics and group exactly as they were", async () => { await expectSeedUntouched(); }); diff --git a/e2e/specs/11-acls.e2e.ts b/e2e/specs/11-acls.e2e.ts new file mode 100644 index 0000000..0a53102 --- /dev/null +++ b/e2e/specs/11-acls.e2e.ts @@ -0,0 +1,74 @@ +import { $, $$, browser, expect } from "@wdio/globals"; + +import { button, ensureCluster, expectToast, goTo, openAlertDialog, openDialog, uniqueName } from "../helpers.js"; + +/** The e2e broker runs StandardAuthorizer with ANONYMOUS as a super user (see docker-compose.yml). */ +describe("ACLs", () => { + // A principal no other run used, so the rows below are only this run's. + const principal = `User:${uniqueName("e2e")}`; + const deleteButton = (operation: string) => $(`button[aria-label^="Delete ACL: Allow ${principal} to ${operation} "]`); + const rowCount = async () => (await $$(`td=${principal}`)).length; + + before(async () => { + await ensureCluster(); + await goTo("ACLs"); + }); + + it("creates one ACL per chosen operation", async () => { + await button("New ACL").click(); + await expect(openDialog()).toBeDisplayed(); + await $("#acl-principal").clearValue(); + await $("#acl-principal").setValue(principal); + await $("#acl-resource-name").setValue("demo.orders"); + await $("#acl-op-read").click(); + await $("#acl-op-describe").click(); + await button("Create 2 ACLs", openDialog()).click(); + + await expectToast("Created 2 ACLs"); + await openDialog().waitForExist({ reverse: true }); + await $('input[aria-label="Filter ACLs"]').setValue(principal); + await browser.waitUntil(async () => (await rowCount()) === 2, { timeoutMsg: "The 2 new ACLs were not listed" }); + }); + + it("keeps the ACL when its delete dialog is cancelled", async () => { + await deleteButton("Read").click(); + await expect(openAlertDialog()).toHaveText(expect.stringContaining(`Allow ${principal} to Read topic demo.orders`)); + await button("Cancel", openAlertDialog()).click(); + await openAlertDialog().waitForExist({ reverse: true }); + expect(await rowCount()).toBe(2); + }); + + it("deletes exactly the confirmed ACL", async () => { + await deleteButton("Read").click(); + await button("Delete", openAlertDialog()).click(); + await expectToast("Deleted ACL"); + await browser.waitUntil(async () => (await rowCount()) === 1, { timeoutMsg: "The deleted ACL is still listed" }); + // Its sibling differs only in the operation and must survive. + await expect(deleteButton("Describe")).toBeExisting(); + + await deleteButton("Describe").click(); + await button("Delete", openAlertDialog()).click(); + await browser.waitUntil(async () => (await rowCount()) === 0, { timeoutMsg: "The last ACL is still listed" }); + }); + + it("offers only the operations that apply to the chosen resource type", async () => { + await button("New ACL").click(); + await $("#acl-principal").clearValue(); + await $("#acl-principal").setValue(principal); + await $("#acl-resource-type").click(); + await $('[role="option"]=Group').click(); + // Write applies to topics but never to a group. + await expect($("#acl-op-write")).not.toBeExisting(); + await $("#acl-resource-name").setValue("demo-billing"); + await $("#acl-op-read").click(); + await button("Create", openDialog()).click(); + await expectToast("Created ACL"); + await openDialog().waitForExist({ reverse: true }); + + await browser.waitUntil(async () => (await rowCount()) === 1, { timeoutMsg: "The group ACL was not listed" }); + await expect($("span=demo-billing")).toBeExisting(); + await deleteButton("Read").click(); + await button("Delete", openAlertDialog()).click(); + await browser.waitUntil(async () => (await rowCount()) === 0, { timeoutMsg: "The group ACL is still listed" }); + }); +}); diff --git a/examples/acl-demo/README.md b/examples/acl-demo/README.md new file mode 100644 index 0000000..d80add4 --- /dev/null +++ b/examples/acl-demo/README.md @@ -0,0 +1,66 @@ +# ACL demo + +Kafka clients that log in as the demo users seeded by `bun run kafka:up`, to show the seeded ACLs being enforced. +They connect to the dev broker's SASL/PLAIN listener on `localhost:9094`. On `localhost:9092` every client is a +super user and ACLs are bypassed. [docs/LOCAL_KAFKA.md](../../docs/LOCAL_KAFKA.md) lists the users and their ACLs. + +Written in TypeScript with [KafkaJS](https://kafka.js.org), run with [Bun](https://bun.sh): + +```bash +bun run kafka:up # from the repo root, once +cd examples/acl-demo +bun install +bun run check # or `bun run kafka:acl-demo` from the repo root +``` + +## The check + +`check.ts` tries one thing per line as one user, and compares what the broker did with what the ACLs say. It +exits 1 if any line doesn't match, so it also catches an ACL that was deleted or changed by mistake. + +| Section | What it shows | +|-----------------------------|-----------------------------------------------------------------------------------------| +| Literal topic and group | `billing-service` reads `demo.orders` in group `demo-billing`, and nothing else | +| Prefixed | `analytics` reads any `demo.*` topic, but only in `analytics-*` groups | +| Transactional producer | `payments` writes in a `payments-*` transaction, not under another transactional ID | +| DENY beats ALLOW | `intern` is allowed to write `demo.*`, but the DENY on every topic wins | +| Wildcard Describe, no ACLs | `auditor` sees every topic but can't write; `nobody` sees nothing | +| Authentication | A wrong password is refused before any ACL is checked | + +A consumer needs ACLs on both the topic and the group. That's why `billing-service` reading `demo.orders` as +`billing-replay` is denied: the topic is allowed, the group isn't. + +The check never commits offsets, so `demo-billing` keeps the lag the seed gives it. It only writes to +`demo.payments`, and only as users allowed to. The groups it joins (`analytics-dashboard`, +`intern-onboarding`) stay behind as empty groups. + +## The services + +One small program per demo user, written the way that service would use Kafka. The comment at the top of each +lists the ACLs it relies on. Run one, then watch it in KUI: its group, members and lag show up on the Consumer +groups page. + +```bash +bun run billing # consumes demo.orders as group demo-billing +bun run analytics # consumes every demo.* topic, via a pattern subscription, as group analytics-dashboard +bun run payments # transactional producer: one payment every 2 s to demo.payments +bun run auditor # read-only report of every topic and group +``` + +Ctrl-C stops a service and leaves its group cleanly. The consumers don't commit offsets either, so you can run +them again and again. + +Try breaking one: delete one of its ACLs in KUI, or change the topic or group in `services/billing.ts`, and start +it again. A denied topic fails with `TOPIC_AUTHORIZATION_FAILED`. A denied group fails with "Failed to find group +coordinator" (see the notes below). + +## Notes + +- Bun prints a `TimeoutNegativeWarning` once per run. KafkaJS schedules a timer with a negative delay. It's + harmless and is clamped to 1 ms. +- When a group is denied, KafkaJS throws a generic "Failed to find group coordinator" and only logs the broker's + `GROUP_AUTHORIZATION_FAILED` at debug level. `check.ts` reads it from the log so it can report "denied". A + service you write yourself sees the generic error. +- KafkaJS is no longer actively maintained. It's used here because it's plain JavaScript and installs in a + second. Confluent's [`@confluentinc/kafka-javascript`](https://github.com/confluentinc/confluent-kafka-javascript) + offers the same API on librdkafka, but it compiles librdkafka on Node versions it has no prebuilt binary for. diff --git a/examples/acl-demo/bun.lock b/examples/acl-demo/bun.lock new file mode 100644 index 0000000..2a53989 --- /dev/null +++ b/examples/acl-demo/bun.lock @@ -0,0 +1,65 @@ +{ + "lockfileVersion": 2, + "configVersion": 1, + "workspaces": { + "": { + "name": "kui-acl-demo", + "dependencies": { + "kafkajs": "^2.2.4", + }, + "devDependencies": { + "@types/node": "^26.6.5", + "typescript": "^7.0.2", + }, + }, + }, + "packages": { + "@types/node": ["@types/node@26.6.6", "", { "dependencies": { "undici-types": "~8.9.0" } }, "sha512-MzQj+8Kx3XI40OmUAE6Qoh58ZMNstNNMwn2nfd3qWsfe7nDNSqJNzes4njhz6AHwrSHOffSLwXU6yb474Q4aog=="], + + "@typescript/typescript-aix-ppc64": ["@typescript/typescript-aix-ppc64@7.0.2", "", { "os": "aix", "cpu": "ppc64" }, "sha512-MTKKkWB7p/0E9xi1d1tHtZ5PiLkGEMIq88pK2CubZjOsLtYTLqhgIgi6zepFa+9GHZ6h05NMCkQxGKiPXMxXtQ=="], + + "@typescript/typescript-darwin-arm64": ["@typescript/typescript-darwin-arm64@7.0.2", "", { "os": "darwin", "cpu": "arm64" }, "sha512-gowzar9MwS/aRWp6f3a4KUqzRjAZjOsmGNCM6LcTgXum+dBfgsBVMN+AgvOCCbguXyick6LJhpBszxMebJ8syA=="], + + "@typescript/typescript-darwin-x64": ["@typescript/typescript-darwin-x64@7.0.2", "", { "os": "darwin", "cpu": "x64" }, "sha512-SZ9xZInqApNlNGc9s0W1VSsktYSOe9cFqNOIqmN1Gs8SmkjKZYFt017G4VwPxASInODuAdbTW7sXiFUf893RgA=="], + + "@typescript/typescript-freebsd-arm64": ["@typescript/typescript-freebsd-arm64@7.0.2", "", { "os": "freebsd", "cpu": "arm64" }, "sha512-W5NH4y/J0plIIS5b2xvTEkU7JFxyqdMAOgf+Ilhl0vHQXKO5dZoxd+C/jEtq56c4F3wk71RB4BMRQ2XdI+bwYQ=="], + + "@typescript/typescript-freebsd-x64": ["@typescript/typescript-freebsd-x64@7.0.2", "", { "os": "freebsd", "cpu": "x64" }, "sha512-UMGDx5sTpzNw3WiPebH7l90IWfJggEd+egHt/q6p7/Cm3zqoV7VxkGXt+3DxPIw8CcmvAB0j3sVVfbhX+M4Tpw=="], + + "@typescript/typescript-linux-arm": ["@typescript/typescript-linux-arm@7.0.2", "", { "os": "linux", "cpu": "arm" }, "sha512-gffT3xPz9sR7j/YJExkyPntrI0P2EP9XbOyWzth2/Gs0RstK+90RBcO0ncXoXy/beYll1SXw846Nf2zdnEz0QQ=="], + + "@typescript/typescript-linux-arm64": ["@typescript/typescript-linux-arm64@7.0.2", "", { "os": "linux", "cpu": "arm64" }, "sha512-Qh4eU4/y3yDjnfjjyPYihMj5/ODIlmt+Bzu17OI+fiSRDW57QmU5SiN63exPRNJPKUzcc1INa1NXdrJ+MqHjUQ=="], + + "@typescript/typescript-linux-loong64": ["@typescript/typescript-linux-loong64@7.0.2", "", { "os": "linux", "cpu": "none" }, "sha512-uEHck9i8hoAzXPiYRib1O7miOnz23SxIeVl6F4LXox+qov1K35jHcEW6VHKvZI+pyvl7fZEP4MCU5LYvIq1GuQ=="], + + "@typescript/typescript-linux-mips64el": ["@typescript/typescript-linux-mips64el@7.0.2", "", { "os": "linux", "cpu": "none" }, "sha512-R4KvAMnE43W5Qeqb0Ly56O3mWMWIAgsMyz36DCaycd5nbg/9kzm0liw3JocfRqyJY0KPmzFjbswozXyW0DnIYA=="], + + "@typescript/typescript-linux-ppc64": ["@typescript/typescript-linux-ppc64@7.0.2", "", { "os": "linux", "cpu": "ppc64" }, "sha512-DORx5b3sd/4S7eayxm4FQv+A7CrkUIGRaHiwI8oiHTAI1fAPWhF4J0vAlkC8biAlHSVVwxMQ3tjZ2/DVbnQiiA=="], + + "@typescript/typescript-linux-riscv64": ["@typescript/typescript-linux-riscv64@7.0.2", "", { "os": "linux", "cpu": "none" }, "sha512-wf0jqEDOjrPRnKwYRyyJDRo11KMbvMFrU+q4zqKyChODBzvlkbhNQfKvLxQCcwTpdDaXSHZTVuh0JoCrKCUMHQ=="], + + "@typescript/typescript-linux-s390x": ["@typescript/typescript-linux-s390x@7.0.2", "", { "os": "linux", "cpu": "s390x" }, "sha512-IkwJc3L7yhytWd/ewjyxNDfOmswCm9GWMJT/ue/dU4aZNbwZeYAetq42VyLmsmSjvoX7z74X6ZaYCtzAr0EuGw=="], + + "@typescript/typescript-linux-x64": ["@typescript/typescript-linux-x64@7.0.2", "", { "os": "linux", "cpu": "x64" }, "sha512-EYdf2cNg7rgCWJnxCdJ+F3V39O8ihb37eHAu1LK8oAFizgTQbPOK7zHHXbPt8rX24COqODXeI3sIf0fCXG7H/A=="], + + "@typescript/typescript-netbsd-arm64": ["@typescript/typescript-netbsd-arm64@7.0.2", "", { "os": "none", "cpu": "arm64" }, "sha512-+polYF4MF04aPpO5FTkHran9yUQDSXqy5GiSDKpsll5jy3l3+g9QLhpf39T+ePtefhXLOGrLl0QIjkQP6VnelA=="], + + "@typescript/typescript-netbsd-x64": ["@typescript/typescript-netbsd-x64@7.0.2", "", { "os": "none", "cpu": "x64" }, "sha512-8YIT0EHM/3dq10ZOVF/A7pc/YSMtbcecct4rWtexrnSCHOPcpC2KTLXfTCR6vDpnSiY12heNb1GiN/wu+T/FyA=="], + + "@typescript/typescript-openbsd-arm64": ["@typescript/typescript-openbsd-arm64@7.0.2", "", { "os": "openbsd", "cpu": "arm64" }, "sha512-APT8+ClYnuYm1u9+kgGXoMj2VzWzcymwh2gNSQVySHfkRDGOTVkoWLjCmOQSaO+PoqQ57B0flRp9SA+7GnnkzQ=="], + + "@typescript/typescript-openbsd-x64": ["@typescript/typescript-openbsd-x64@7.0.2", "", { "os": "openbsd", "cpu": "x64" }, "sha512-yX7s+Q0Dln0Dt9tEzZsAjXXR/+ytBM7AlglaqyeMPxQszJ1JhlJdZ6jLA+IzldHtflX81em7lDao1xXu+aRRkg=="], + + "@typescript/typescript-sunos-x64": ["@typescript/typescript-sunos-x64@7.0.2", "", { "os": "sunos", "cpu": "x64" }, "sha512-dLJDGaLZ1D4HPQn62u1n8mBDkJREwMsAkCdkwd4Ieqw+x3TUyTsqY0YiBCtE6H6OzzgGk3iuZ3vFWRS+E8/d1g=="], + + "@typescript/typescript-win32-arm64": ["@typescript/typescript-win32-arm64@7.0.2", "", { "os": "win32", "cpu": "arm64" }, "sha512-Gyl1Vy6OsWesLzmq+EP0Fb7b4Nid5232AvcA2SFcdYreldpNtYFFofPjnt62y9hQy7VTaZp65ICJjuAQRaVcIQ=="], + + "@typescript/typescript-win32-x64": ["@typescript/typescript-win32-x64@7.0.2", "", { "os": "win32", "cpu": "x64" }, "sha512-0BQ3HkAHHlKLSp1qRvf3SUhGpGsDuhB/jgFw75guyqbxJqEaS0Cw/VFO8i2nHglJUzQCRtMMR/IBAKE3ETMC4g=="], + + "kafkajs": ["kafkajs@2.2.4", "", {}, "sha512-j/YeapB1vfPT2iOIUn/vxdyKEuhuY2PxMBvf5JWux6iSaukAccrMtXEY/Lb7OvavDhOWME589bpLrEdnVHjfjA=="], + + "typescript": ["typescript@7.0.2", "", { "optionalDependencies": { "@typescript/typescript-aix-ppc64": "7.0.2", "@typescript/typescript-darwin-arm64": "7.0.2", "@typescript/typescript-darwin-x64": "7.0.2", "@typescript/typescript-freebsd-arm64": "7.0.2", "@typescript/typescript-freebsd-x64": "7.0.2", "@typescript/typescript-linux-arm": "7.0.2", "@typescript/typescript-linux-arm64": "7.0.2", "@typescript/typescript-linux-loong64": "7.0.2", "@typescript/typescript-linux-mips64el": "7.0.2", "@typescript/typescript-linux-ppc64": "7.0.2", "@typescript/typescript-linux-riscv64": "7.0.2", "@typescript/typescript-linux-s390x": "7.0.2", "@typescript/typescript-linux-x64": "7.0.2", "@typescript/typescript-netbsd-arm64": "7.0.2", "@typescript/typescript-netbsd-x64": "7.0.2", "@typescript/typescript-openbsd-arm64": "7.0.2", "@typescript/typescript-openbsd-x64": "7.0.2", "@typescript/typescript-sunos-x64": "7.0.2", "@typescript/typescript-win32-arm64": "7.0.2", "@typescript/typescript-win32-x64": "7.0.2" }, "bin": { "tsc": "bin/tsc" } }, "sha512-8FYau96o3NKOhbjKi/qNvG/W5jhzxkbdm5sj9AbZ/5T5sWqn3hJgLfGx27sRKZWTvyzCP8dLRBTf5tBTSRVUNA=="], + + "undici-types": ["undici-types@8.9.0", "", {}, "sha512-KTDyRTYX8sWmKXAikPHHSyc63CRPETMctyjKFupcC6OBLXT3xsN0e9aF7m+mIXutFWpUXuedtowG7iLOzp0kQg=="], + } +} diff --git a/examples/acl-demo/check.ts b/examples/acl-demo/check.ts new file mode 100644 index 0000000..9cb23fc --- /dev/null +++ b/examples/acl-demo/check.ts @@ -0,0 +1,151 @@ +// Proves the seeded ACLs are enforced: each check logs in as a demo user, tries one thing, and compares what the +// broker did with what the ACLs say. Exits 1 on any mismatch. Never commits offsets, and only writes to +// demo.payments when that's allowed. +import { type Kafka, KafkaJSGroupCoordinatorNotFound, logLevel } from "kafkajs"; + +import { type DemoUser, type Outcome, accessOutcome, kafkaAs } from "./kafka.ts"; + +const READ_TIMEOUT_MS = 20_000; + +// KafkaJS logs the broker's GROUP_AUTHORIZATION_FAILED at debug level and then throws a generic "Failed to find +// group coordinator" without it, so each check keeps the last access error its client logged. +function checkClient(user: DemoUser, password?: string) { + let logged: Outcome | undefined; + const kafka = kafkaAs(user, password, { + logLevel: logLevel.DEBUG, + logCreator: () => (entry) => { + logged = ("error" in entry.log && accessOutcome(entry.log.error)) || logged; + }, + }); + const outcomeOf = (error: unknown): Outcome | undefined => + accessOutcome(error) ?? (error instanceof KafkaJSGroupCoordinatorNotFound ? logged : undefined); + return { kafka, outcomeOf }; +} + +async function readOne(kafka: Kafka, topic: string, groupId: string): Promise { + // KafkaJS would otherwise restart a crashed consumer, retrying the denied join forever. + const consumer = kafka.consumer({ groupId, retry: { restartOnFailure: async () => false } }); + try { + await consumer.connect(); + await consumer.subscribe({ topics: [topic], fromBeginning: true }); + await new Promise((resolve, reject) => { + const timer = setTimeout(() => reject(new Error(`no message from ${topic} within ${READ_TIMEOUT_MS} ms`)), READ_TIMEOUT_MS); + // Group and topic denials surface asynchronously, after run() has returned. + consumer.on(consumer.events.CRASH, ({ payload }) => reject(payload.error)); + void consumer.run({ autoCommit: false, eachMessage: async () => (clearTimeout(timer), resolve()) }); + }); + return "allowed"; + } finally { + await consumer.disconnect(); + } +} + +async function writeOne(kafka: Kafka, topic: string, transactionalId?: string): Promise { + const producer = kafka.producer(transactionalId ? { transactionalId, idempotent: true, maxInFlightRequests: 1 } : {}); + try { + await producer.connect(); + const message = { key: "acl-demo", value: JSON.stringify({ check: true, at: new Date().toISOString() }) }; + if (transactionalId) { + const transaction = await producer.transaction(); + try { + await transaction.send({ topic, messages: [message] }); + await transaction.commit(); + } catch (error) { + await transaction.abort().catch(() => {}); + throw error; + } + } else { + await producer.send({ topic, messages: [message] }); + } + return "allowed"; + } finally { + await producer.disconnect(); + } +} + +// The broker leaves topics a user may not Describe out of the listing instead of returning an error. +async function seesTopic(kafka: Kafka, topic: string): Promise { + const admin = kafka.admin(); + try { + await admin.connect(); + return (await admin.listTopics()).includes(topic) ? "allowed" : "denied"; + } finally { + await admin.disconnect(); + } +} + +type Check = { user: DemoUser; password?: string; action: string; expect: Outcome; run: (kafka: Kafka) => Promise }; + +const read = (topic: string, group: string) => ({ action: `read ${topic} as group ${group}`, run: (k: Kafka) => readOne(k, topic, group) }); +const write = (topic: string) => ({ action: `write to ${topic}`, run: (k: Kafka) => writeOne(k, topic) }); +const writeInTransaction = (topic: string, id: string) => ({ + action: `write to ${topic} in transaction ${id}`, + run: (k: Kafka) => writeOne(k, topic, id), +}); +const list = (topic: string) => ({ action: `see ${topic} in the topic list`, run: (k: Kafka) => seesTopic(k, topic) }); + +const sections: [string, Check[]][] = [ + [ + "Literal topic and group ACLs", + [ + { user: "billing-service", expect: "allowed", ...read("demo.orders", "demo-billing") }, + { user: "billing-service", expect: "denied", ...read("demo.orders", "billing-replay") }, + { user: "billing-service", expect: "denied", ...read("demo.events", "demo-billing") }, + { user: "billing-service", expect: "denied", ...write("demo.orders") }, + // order-service may read demo.customers but has no group ACL, so it can't join any group. + { user: "order-service", expect: "denied", ...read("demo.customers", "order-service") }, + ], + ], + [ + "Prefixed ACLs: topics demo.*, groups analytics-*", + [ + { user: "analytics", expect: "allowed", ...read("demo.events", "analytics-dashboard") }, + { user: "analytics", expect: "allowed", ...read("demo.catalog", "analytics-dashboard") }, + { user: "analytics", expect: "denied", ...read("demo.events", "reporting") }, + ], + ], + [ + "Transactional producer: transactional IDs payments-*", + [ + { user: "payments", expect: "allowed", ...writeInTransaction("demo.payments", "payments-writer") }, + { user: "payments", expect: "denied", ...writeInTransaction("demo.payments", "refunds-writer") }, + { user: "payments", expect: "denied", ...write("demo.orders") }, + ], + ], + [ + "DENY beats ALLOW: the intern may use demo.*, but writes to any topic are denied", + [ + { user: "intern", expect: "allowed", ...read("demo.customers", "intern-onboarding") }, + { user: "intern", expect: "denied", ...write("demo.payments") }, + ], + ], + [ + "Wildcard Describe, and no ACLs at all", + [ + { user: "auditor", expect: "allowed", ...list("demo.orders") }, + { user: "auditor", expect: "denied", ...write("demo.payments") }, + { user: "nobody", expect: "denied", ...list("demo.orders") }, + { user: "nobody", expect: "denied", ...read("demo.orders", "nobody") }, + ], + ], + [ + "Authentication", + [{ user: "billing-service", password: "wrong-password", expect: "login failed", ...read("demo.orders", "demo-billing") }], + ], +]; + +let mismatches = 0; +for (const [title, checks] of sections) { + console.log(title); + for (const { user, password, action, expect, run } of checks) { + const { kafka, outcomeOf } = checkClient(user, password); + const got = await run(kafka).catch( + (error: unknown) => outcomeOf(error) ?? `error: ${error instanceof Error ? error.message : String(error)}`, + ); + const ok = got === expect; + if (!ok) mismatches++; + console.log(` ${ok ? "ok " : "FAIL"} ${user.padEnd(16)} ${action.padEnd(56)} ${got}${ok ? "" : `, expected ${expect}`}`); + } +} +console.log(mismatches ? `${mismatches} check(s) did not match the ACLs.` : "Every check matched the ACLs."); +process.exit(mismatches ? 1 : 0); diff --git a/examples/acl-demo/kafka.ts b/examples/acl-demo/kafka.ts new file mode 100644 index 0000000..a6a37c4 --- /dev/null +++ b/examples/acl-demo/kafka.ts @@ -0,0 +1,37 @@ +import { Kafka, type KafkaConfig, KafkaJSProtocolError, KafkaJSSASLAuthenticationError, logLevel } from "kafkajs"; + +// The dev broker's SASL listener. Clients on localhost:9092 are ANONYMOUS, a super user that bypasses ACLs. +const BROKER = process.env.KAFKA_SASL_BOOTSTRAP ?? "localhost:9094"; + +/** The logins in docker-compose.yml. Each password is `-secret`; `nobody` has no ACLs. */ +export type DemoUser = "billing-service" | "order-service" | "analytics" | "payments" | "auditor" | "intern" | "nobody"; + +export function kafkaAs(user: DemoUser, password = `${user}-secret`, config: Partial = {}): Kafka { + return new Kafka({ + clientId: `acl-demo-${user}`, + brokers: [BROKER], + sasl: { mechanism: "plain", username: user, password }, + logLevel: logLevel.WARN, + ...config, + }); +} + +export type Outcome = "allowed" | "denied" | "login failed"; + +/** What a failed call says about the ACLs, or `undefined` when the error isn't about access. */ +export function accessOutcome(error: unknown): Outcome | undefined { + // KafkaJS wraps the broker's error when a consumer crashes or retries run out. + for (let e: unknown = error; e instanceof Error; e = e.cause ?? ("originalError" in e ? e.originalError : undefined)) { + if (e instanceof KafkaJSSASLAuthenticationError) return "login failed"; + // TOPIC_, GROUP_, TRANSACTIONAL_ID_ and CLUSTER_AUTHORIZATION_FAILED + if (e instanceof KafkaJSProtocolError && e.type.endsWith("_AUTHORIZATION_FAILED")) return "denied"; + } + return undefined; +} + +/** Runs `stop` once on Ctrl-C, so a consumer leaves its group instead of waiting out the session timeout. */ +export function stopOnSignal(stop: () => Promise) { + const handler = () => void stop().finally(() => process.exit(0)); + process.once("SIGINT", handler); + process.once("SIGTERM", handler); +} diff --git a/examples/acl-demo/package.json b/examples/acl-demo/package.json new file mode 100644 index 0000000..10303f6 --- /dev/null +++ b/examples/acl-demo/package.json @@ -0,0 +1,20 @@ +{ + "name": "kui-acl-demo", + "private": true, + "type": "module", + "scripts": { + "check": "bun check.ts", + "billing": "bun services/billing.ts", + "analytics": "bun services/analytics.ts", + "payments": "bun services/payments.ts", + "auditor": "bun services/auditor.ts", + "typecheck": "tsc --noEmit" + }, + "dependencies": { + "kafkajs": "^2.2.4" + }, + "devDependencies": { + "@types/node": "^26.6.5", + "typescript": "^7.0.2" + } +} diff --git a/examples/acl-demo/services/analytics.ts b/examples/acl-demo/services/analytics.ts new file mode 100644 index 0000000..df5b8ce --- /dev/null +++ b/examples/acl-demo/services/analytics.ts @@ -0,0 +1,21 @@ +// analytics reads every demo topic, including ones created later, as group analytics-dashboard. +// ACLs it relies on: Read + Describe on topics prefixed `demo.`, Read on groups prefixed `analytics-`. +// The pattern subscription only matches topics the user may Describe, so other topics never show up. +import { kafkaAs, stopOnSignal } from "../kafka.ts"; + +const consumer = kafkaAs("analytics").consumer({ groupId: "analytics-dashboard" }); +await consumer.connect(); +await consumer.subscribe({ topics: [/^demo\./], fromBeginning: true }); +const counts = new Map(); +await consumer.run({ + autoCommit: false, + eachMessage: async ({ topic }) => { + counts.set(topic, (counts.get(topic) ?? 0) + 1); + }, +}); +const report = setInterval(() => console.log("analytics", Object.fromEntries(counts)), 2000); +console.log("analytics is consuming demo.* as group analytics-dashboard. Ctrl-C to stop."); +stopOnSignal(async () => { + clearInterval(report); + await consumer.disconnect(); +}); diff --git a/examples/acl-demo/services/auditor.ts b/examples/acl-demo/services/auditor.ts new file mode 100644 index 0000000..e6d4a3b --- /dev/null +++ b/examples/acl-demo/services/auditor.ts @@ -0,0 +1,21 @@ +// auditor is a read-only monitoring account: it sees every topic and group but can change nothing. +// ACLs it relies on: Describe + DescribeConfigs on all topics (`*`), Describe on all groups (`*`), Describe + +// DescribeConfigs on the cluster. +import { kafkaAs } from "../kafka.ts"; + +const admin = kafkaAs("auditor").admin(); +await admin.connect(); +try { + for (const topic of (await admin.listTopics()).sort()) { + const offsets = await admin.fetchTopicOffsets(topic); + // Transaction markers take offsets too, so on demo.payments this counts more than the payments. + const span = offsets.reduce((sum, p) => sum + Number(p.high) - Number(p.low), 0); + console.log(`topic ${topic.padEnd(24)} ${String(offsets.length).padStart(2)} partitions ${span} offsets`); + } + const { groups } = await admin.describeGroups((await admin.listGroups()).groups.map((g) => g.groupId)); + for (const group of groups) { + console.log(`group ${group.groupId.padEnd(24)} ${group.state}, ${group.members.length} members`); + } +} finally { + await admin.disconnect(); +} diff --git a/examples/acl-demo/services/billing.ts b/examples/acl-demo/services/billing.ts new file mode 100644 index 0000000..af83164 --- /dev/null +++ b/examples/acl-demo/services/billing.ts @@ -0,0 +1,16 @@ +// billing-service reads orders as consumer group demo-billing. +// ACLs it relies on: Read + Describe on topic demo.orders, Read on group demo-billing. +import { kafkaAs, stopOnSignal } from "../kafka.ts"; + +const consumer = kafkaAs("billing-service").consumer({ groupId: "demo-billing" }); +await consumer.connect(); +await consumer.subscribe({ topics: ["demo.orders"], fromBeginning: true }); +await consumer.run({ + // Committing would erase the lag the seed gives demo-billing; a real service leaves this on. + autoCommit: false, + eachMessage: async ({ partition, message }) => { + console.log(`billing p${partition}@${message.offset} ${message.key?.toString()} ${message.value?.toString()}`); + }, +}); +console.log("billing-service is consuming demo.orders as group demo-billing. Ctrl-C to stop."); +stopOnSignal(() => consumer.disconnect()); diff --git a/examples/acl-demo/services/payments.ts b/examples/acl-demo/services/payments.ts new file mode 100644 index 0000000..616052a --- /dev/null +++ b/examples/acl-demo/services/payments.ts @@ -0,0 +1,29 @@ +// payments writes one payment every two seconds, each in its own transaction. +// ACLs it relies on: Write + Describe on transactional IDs prefixed `payments-`, Write + Describe on topic +// demo.payments, IdempotentWrite on the cluster. +import { Partitioners } from "kafkajs"; + +import { kafkaAs, stopOnSignal } from "../kafka.ts"; + +const producer = kafkaAs("payments").producer({ + transactionalId: "payments-writer", + idempotent: true, + maxInFlightRequests: 1, + createPartitioner: Partitioners.DefaultPartitioner, +}); +await producer.connect(); +console.log("payments is producing to demo.payments as transactional ID payments-writer. Ctrl-C to stop."); + +let running = true; +stopOnSignal(async () => { + running = false; + await producer.disconnect(); +}); +for (let n = 1; running; n++) { + const transaction = await producer.transaction(); + const payment = { id: `pay-${Date.now()}`, amount: (n * 37) % 500, currency: "USD" }; + await transaction.send({ topic: "demo.payments", messages: [{ key: payment.id, value: JSON.stringify(payment) }] }); + await transaction.commit(); + console.log("payments committed", payment); + await new Promise((resolve) => setTimeout(resolve, 2000)); +} diff --git a/examples/acl-demo/tsconfig.json b/examples/acl-demo/tsconfig.json new file mode 100644 index 0000000..5cfb1fa --- /dev/null +++ b/examples/acl-demo/tsconfig.json @@ -0,0 +1,14 @@ +{ + "compilerOptions": { + "target": "ES2022", + "module": "NodeNext", + "moduleResolution": "NodeNext", + "allowImportingTsExtensions": true, + "strict": true, + "skipLibCheck": true, + "noEmit": true, + "types": ["node"] + }, + "include": ["**/*.ts"], + "exclude": ["node_modules"] +} diff --git a/frontend/app/app-sidebar.tsx b/frontend/app/app-sidebar.tsx index f00a94d..02ba001 100644 --- a/frontend/app/app-sidebar.tsx +++ b/frontend/app/app-sidebar.tsx @@ -3,6 +3,7 @@ import { SearchIcon, ServerIcon, SettingsIcon, + ShieldCheckIcon, UsersIcon, type LucideIcon, } from "lucide-react"; @@ -40,7 +41,7 @@ interface NavItem { } // Ordered the way a cluster is built up: the brokers, the topics they host, -// then the consumer groups reading those topics. +// then the consumer groups reading those topics, and who may access them. const NAV_ITEMS: NavItem[] = [ { label: "Brokers", icon: ServerIcon, page: "brokers", route: { page: "brokers" }, key: "1" }, { label: "Topics", icon: ListTreeIcon, page: "topics", route: { page: "topics" }, key: "2" }, @@ -51,6 +52,7 @@ const NAV_ITEMS: NavItem[] = [ route: { page: "consumer-groups" }, key: "3", }, + { label: "ACLs", icon: ShieldCheckIcon, page: "acls", route: { page: "acls" }, key: "4" }, ]; export function AppSidebar() { @@ -65,6 +67,7 @@ export function AppSidebar() { useShortcut("mod+1", () => navigate(NAV_ITEMS[0].route), clusterId !== null); useShortcut("mod+2", () => navigate(NAV_ITEMS[1].route), clusterId !== null); useShortcut("mod+3", () => navigate(NAV_ITEMS[2].route), clusterId !== null); + useShortcut("mod+4", () => navigate(NAV_ITEMS[3].route), clusterId !== null); return ( diff --git a/frontend/app/router.tsx b/frontend/app/router.tsx index 5ac919b..0a2be6b 100644 --- a/frontend/app/router.tsx +++ b/frontend/app/router.tsx @@ -1,3 +1,4 @@ +import { AclsPage } from "@/features/acls"; import { BrokersPage } from "@/features/brokers"; import { ConsumerGroupsPage } from "@/features/consumer-groups"; import { TopicPage, TopicsPage } from "@/features/topics"; @@ -32,5 +33,7 @@ function Page() { return ; case "consumer-groups": return ; + case "acls": + return ; } } diff --git a/frontend/app/stores/navigation-store.ts b/frontend/app/stores/navigation-store.ts index ea2cbed..9d35955 100644 --- a/frontend/app/stores/navigation-store.ts +++ b/frontend/app/stores/navigation-store.ts @@ -11,7 +11,8 @@ export type Route = | { page: "brokers" } | { page: "topics" } | { page: "topic"; topic: string } - | { page: "consumer-groups" }; + | { page: "consumer-groups" } + | { page: "acls" }; /** The page a cluster opens on: its brokers, first in the sidebar. */ const HOME_ROUTE: Route = { page: "brokers" }; diff --git a/frontend/features/acls/acl.test.ts b/frontend/features/acls/acl.test.ts new file mode 100644 index 0000000..40f4e6f --- /dev/null +++ b/frontend/features/acls/acl.test.ts @@ -0,0 +1,79 @@ +import { describe, expect, test } from "bun:test"; + +import { aclKey, aclsFromForm, describeAcl, matchesAcl, type AclForm } from "./acl"; +import { OPERATIONS, type AclBinding } from "./types"; + +const acl: AclBinding = { + resourceType: "topic", + resourceName: "orders", + patternType: "prefixed", + principal: "User:alice", + host: "*", + operation: "read", + permission: "allow", +}; + +const form: AclForm = { + principal: " User:alice ", + host: "", + resourceType: "topic", + patternType: "literal", + resourceName: " orders ", + permission: "deny", + operations: ["read", "describe"], +}; + +describe("aclKey", () => { + test("tells apart ACLs that differ in a single field", () => { + expect(aclKey(acl)).not.toBe(aclKey({ ...acl, operation: "describe" })); + expect(aclKey(acl)).not.toBe(aclKey({ ...acl, patternType: "literal" })); + expect(aclKey(acl)).toBe(aclKey({ ...acl })); + }); + + test("can't be fooled by separators inside names", () => { + const a = { ...acl, resourceName: "a", principal: "User:b|c" }; + const b = { ...acl, resourceName: "a|User:b", principal: "c" }; + expect(aclKey(a)).not.toBe(aclKey(b)); + }); +}); + +describe("describeAcl", () => { + test("reads as a sentence and marks prefixes with *", () => { + expect(describeAcl(acl)).toBe("Allow User:alice to Read topic orders* from any host"); + expect(describeAcl({ ...acl, permission: "deny", patternType: "literal", host: "10.0.0.1" })).toBe( + "Deny User:alice to Read topic orders from 10.0.0.1", + ); + }); +}); + +describe("matchesAcl", () => { + test("searches principal, resource and host, ignoring case", () => { + expect(matchesAcl(acl, "ALICE")).toBe(true); + expect(matchesAcl(acl, "ord")).toBe(true); + expect(matchesAcl(acl, "bob")).toBe(false); + expect(matchesAcl(acl, " ")).toBe(true); + }); +}); + +describe("aclsFromForm", () => { + test("makes one trimmed ACL per operation, with * as the default host", () => { + expect(aclsFromForm(form)).toEqual([ + { ...acl, resourceName: "orders", patternType: "literal", operation: "read", permission: "deny" }, + { ...acl, resourceName: "orders", patternType: "literal", operation: "describe", permission: "deny" }, + ]); + }); + + test("uses the fixed literal name for the cluster", () => { + const [cluster] = aclsFromForm({ ...form, resourceType: "cluster", patternType: "prefixed", resourceName: "x" }); + expect(cluster.resourceName).toBe("kafka-cluster"); + expect(cluster.patternType).toBe("literal"); + }); + + test("makes nothing when no operation is chosen", () => { + expect(aclsFromForm({ ...form, operations: [] })).toEqual([]); + }); +}); + +test("every resource type allows All, like the Rust table", () => { + for (const operations of Object.values(OPERATIONS)) expect(operations).toContain("all"); +}); diff --git a/frontend/features/acls/acl.ts b/frontend/features/acls/acl.ts new file mode 100644 index 0000000..2c166b9 --- /dev/null +++ b/frontend/features/acls/acl.ts @@ -0,0 +1,77 @@ +import { CLUSTER_RESOURCE_NAME, type AclBinding, type Operation, type PatternType, type Permission, type ResourceType } from "./types"; + +export const RESOURCE_LABELS: Record = { + topic: "Topic", + group: "Group", + cluster: "Cluster", + transactionalId: "Transactional ID", +}; + +export const OPERATION_LABELS: Record = { + all: "All", + read: "Read", + write: "Write", + create: "Create", + delete: "Delete", + alter: "Alter", + describe: "Describe", + clusterAction: "Cluster action", + describeConfigs: "Describe configs", + alterConfigs: "Alter configs", + idempotentWrite: "Idempotent write", +}; + +/** A stable identity for an ACL: every field, since two ACLs may differ in only one. */ +export function aclKey(acl: AclBinding): string { + return JSON.stringify([ + acl.resourceType, + acl.patternType, + acl.resourceName, + acl.principal, + acl.host, + acl.operation, + acl.permission, + ]); +} + +/** A one-line description, e.g. "Allow User:alice to Read topic orders* from any host". */ +export function describeAcl(acl: AclBinding): string { + const name = acl.patternType === "prefixed" ? `${acl.resourceName}*` : acl.resourceName; + const verb = acl.permission === "allow" ? "Allow" : "Deny"; + const host = acl.host === "*" ? "any host" : acl.host; + return `${verb} ${acl.principal} to ${OPERATION_LABELS[acl.operation]} ${RESOURCE_LABELS[acl.resourceType].toLowerCase()} ${name} from ${host}`; +} + +/** Whether the ACL's principal, resource name or host contains `query`, ignoring case. */ +export function matchesAcl(acl: AclBinding, query: string): boolean { + const q = query.trim().toLowerCase(); + if (!q) return true; + return [acl.principal, acl.resourceName, acl.host].some((field) => field.toLowerCase().includes(q)); +} + +export interface AclForm { + principal: string; + host: string; + resourceType: ResourceType; + patternType: PatternType; + resourceName: string; + permission: Permission; + operations: readonly Operation[]; +} + +/** + * The ACLs a create form asks for: one per chosen operation, which is how + * Kafka stores them. A cluster resource always has the fixed literal name. + */ +export function aclsFromForm(form: AclForm): AclBinding[] { + const cluster = form.resourceType === "cluster"; + return form.operations.map((operation) => ({ + resourceType: form.resourceType, + resourceName: cluster ? CLUSTER_RESOURCE_NAME : form.resourceName.trim(), + patternType: cluster ? "literal" : form.patternType, + principal: form.principal.trim(), + host: form.host.trim() || "*", + operation, + permission: form.permission, + })); +} diff --git a/frontend/features/acls/api.ts b/frontend/features/acls/api.ts new file mode 100644 index 0000000..9791a97 --- /dev/null +++ b/frontend/features/acls/api.ts @@ -0,0 +1,11 @@ +// Mirrors `crates/kui_desktop/src/features/acls/commands.rs`. +import { callCommand } from "@/lib/invoke"; + +import type { AclBinding } from "./types"; + +export const aclsApi = { + list: (clusterId: string) => callCommand("list_acls", { clusterId }), + create: (clusterId: string, acls: AclBinding[]) => callCommand("create_acls", { clusterId, acls }), + /** Deletes exactly these ACLs; resolves to how many were removed. */ + remove: (clusterId: string, acls: AclBinding[]) => callCommand("delete_acls", { clusterId, acls }), +}; diff --git a/frontend/features/acls/components/acls-page.tsx b/frontend/features/acls/components/acls-page.tsx new file mode 100644 index 0000000..b5d42a2 --- /dev/null +++ b/frontend/features/acls/components/acls-page.tsx @@ -0,0 +1,149 @@ +import { RotateCwIcon, SearchIcon } from "lucide-react"; +import { useMemo } from "react"; + +import { useClusterId } from "@/app/stores/navigation-store"; +import { PageHeader } from "@/components/page-header"; +import { emptyText, ErrorState } from "@/components/query-states"; +import { SortableTableHead } from "@/components/sortable-table-head"; +import { TableFrame } from "@/components/table-frame"; +import { Badge } from "@/components/ui/badge"; +import { Button } from "@/components/ui/button"; +import { Input } from "@/components/ui/input"; +import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select"; +import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow, TableStateRow } from "@/components/ui/table"; +import { useColumnResize } from "@/hooks/use-column-resize"; +import { usePagination } from "@/hooks/use-pagination"; +import { useSort, type SortColumns } from "@/hooks/use-sort"; +import { useViewSearch, useViewState } from "@/hooks/use-view-state"; + +import { aclKey, matchesAcl, OPERATION_LABELS, RESOURCE_LABELS } from "../acl"; +import { useAcls } from "../queries"; +import type { AclBinding, ResourceType } from "../types"; +import { CreateAclDialog } from "./create-acl-dialog"; +import { DeleteAclButton } from "./delete-acl-button"; + +const ANY_RESOURCE = "any"; +const RESOURCE_TYPES = Object.keys(RESOURCE_LABELS) as ResourceType[]; + +const COLUMNS: SortColumns = { + principal: (a) => a.principal, + permission: (a) => a.permission, + operation: (a) => OPERATION_LABELS[a.operation], + resource: (a) => `${RESOURCE_LABELS[a.resourceType]} ${a.resourceName}`, + host: (a) => a.host, +}; + +export function AclsPage() { + const clusterId = useClusterId(); + const acls = useAcls(clusterId); + const [searchInput, search, setSearchInput] = useViewSearch("acls.search"); + const [resource, setResource] = useViewState("acls.resource", ANY_RESOURCE); + + const visible = useMemo( + () => + (acls.data ?? []).filter( + (a) => (resource === ANY_RESOURCE || a.resourceType === resource) && matchesAcl(a, search), + ), + [acls.data, resource, search], + ); + const sorter = useSort("acls", visible, COLUMNS); + const pager = usePagination(sorter.rows, `${search}|${resource}|${sorter.key}`); + const resize = useColumnResize("acls", 6); + + return ( + <> + + + + + } + /> +
+
+
+ + setSearchInput(e.target.value)} + /> +
+ +
+ + {acls.error && acls.refetch()} />} + + + + + + Principal + + + Permission + + + Operation + + + Resource + + + Host + + + Actions + + + + + {pager.items.map((acl) => ( + + {acl.principal} + + + {acl.permission === "deny" ? "Deny" : "Allow"} + + + {OPERATION_LABELS[acl.operation]} + +
+ {RESOURCE_LABELS[acl.resourceType]} + {acl.resourceName} + {acl.patternType === "prefixed" && prefix} +
+
+ {acl.host} + + + +
+ ))} + {visible.length === 0 && {emptyText(acls, "No ACLs found.")}} +
+
+
+
+ + ); +} diff --git a/frontend/features/acls/components/create-acl-dialog.tsx b/frontend/features/acls/components/create-acl-dialog.tsx new file mode 100644 index 0000000..a92a83f --- /dev/null +++ b/frontend/features/acls/components/create-acl-dialog.tsx @@ -0,0 +1,198 @@ +import { PlusIcon } from "lucide-react"; +import { useState, type FormEvent } from "react"; +import { toast } from "sonner"; + +import { Button } from "@/components/ui/button"; +import { Checkbox } from "@/components/ui/checkbox"; +import { + Dialog, + DialogContent, + DialogDescription, + DialogFooter, + DialogHeader, + DialogTitle, + DialogTrigger, +} from "@/components/ui/dialog"; +import { + Field, + FieldDescription, + FieldError, + FieldGroup, + FieldLabel, + FieldLegend, + FieldSet, +} from "@/components/ui/field"; +import { Input } from "@/components/ui/input"; +import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select"; +import { Spinner } from "@/components/ui/spinner"; + +import { aclsFromForm, OPERATION_LABELS, RESOURCE_LABELS } from "../acl"; +import { useCreateAcls } from "../queries"; +import { CLUSTER_RESOURCE_NAME, OPERATIONS, type Operation, type PatternType, type Permission, type ResourceType } from "../types"; + +const RESOURCE_TYPES = Object.keys(RESOURCE_LABELS) as ResourceType[]; + +export function CreateAclDialog({ clusterId }: { clusterId: string }) { + const [open, setOpen] = useState(false); + const [principal, setPrincipal] = useState("User:"); + const [host, setHost] = useState("*"); + const [resourceType, setResourceType] = useState("topic"); + const [patternType, setPatternType] = useState("literal"); + const [resourceName, setResourceName] = useState(""); + const [permission, setPermission] = useState("allow"); + const [chosen, setChosen] = useState([]); + const create = useCreateAcls(clusterId); + + const cluster = resourceType === "cluster"; + // Choices that don't apply to the current resource type are kept, so switching back restores them. + const operations = OPERATIONS[resourceType].filter((o) => chosen.includes(o)); + const acls = aclsFromForm({ principal, host, resourceType, patternType, resourceName, permission, operations }); + + function toggle(operation: Operation, on: boolean) { + setChosen((current) => (on ? [...current, operation] : current.filter((o) => o !== operation))); + } + + function handleOpenChange(next: boolean) { + setOpen(next); + if (!next) create.reset(); + } + + function handleSubmit(event: FormEvent) { + event.preventDefault(); + create.mutate(acls, { + onSuccess: () => { + toast.success(acls.length === 1 ? "Created ACL" : `Created ${acls.length} ACLs`); + setOpen(false); + setChosen([]); + }, + }); + } + + return ( + + + + + + + Create ACL + One ACL is created for each operation you choose. + +
+ +
+ + Principal + setPrincipal(e.target.value)} + /> + + + Host + setHost(e.target.value)} + /> + +
+
+ + Resource type + + + + Permission + + +
+
+ + Resource name + setResourceName(e.target.value)} + /> + + + Match + + +
+
+ Operations + All covers every operation on the resource. +
+ {OPERATIONS[resourceType].map((o) => ( + + toggle(o, on === true)} + /> + + {OPERATION_LABELS[o]} + + + ))} +
+
+ {create.error && {create.error.message}} +
+ + + +
+
+
+ ); +} diff --git a/frontend/features/acls/components/delete-acl-button.tsx b/frontend/features/acls/components/delete-acl-button.tsx new file mode 100644 index 0000000..a2f34ae --- /dev/null +++ b/frontend/features/acls/components/delete-acl-button.tsx @@ -0,0 +1,62 @@ +import { Trash2Icon } from "lucide-react"; +import { toast } from "sonner"; + +import { + AlertDialog, + AlertDialogAction, + AlertDialogCancel, + AlertDialogContent, + AlertDialogDescription, + AlertDialogFooter, + AlertDialogHeader, + AlertDialogTitle, + AlertDialogTrigger, +} from "@/components/ui/alert-dialog"; +import { Button } from "@/components/ui/button"; + +import { describeAcl } from "../acl"; +import { useDeleteAcls } from "../queries"; +import type { AclBinding } from "../types"; + +interface DeleteAclButtonProps { + clusterId: string; + acl: AclBinding; +} + +/** Deletes exactly one ACL after a confirmation, since removing an Allow can cut off a running client. */ +export function DeleteAclButton({ clusterId, acl }: DeleteAclButtonProps) { + const deleteAcls = useDeleteAcls(clusterId); + const description = describeAcl(acl); + + function handleDelete() { + deleteAcls.mutate([acl], { + onSuccess: () => toast.success("Deleted ACL"), + onError: (e) => toast.error(e.message), + }); + } + + return ( + + + + + + + Delete ACL? + + Clients relying on this ACL lose that access immediately: + {description} + + + + Cancel + + Delete + + + + + ); +} diff --git a/frontend/features/acls/index.ts b/frontend/features/acls/index.ts new file mode 100644 index 0000000..89122c6 --- /dev/null +++ b/frontend/features/acls/index.ts @@ -0,0 +1 @@ +export { AclsPage } from "./components/acls-page"; diff --git a/frontend/features/acls/queries.ts b/frontend/features/acls/queries.ts new file mode 100644 index 0000000..ee16dd0 --- /dev/null +++ b/frontend/features/acls/queries.ts @@ -0,0 +1,33 @@ +import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"; + +import { clusterKeys } from "@/features/clusters"; + +import { aclsApi } from "./api"; +import type { AclBinding } from "./types"; + +export const aclKeys = { + all: (clusterId: string) => [...clusterKeys.scope(clusterId), "acls"] as const, +}; + +export function useAcls(clusterId: string) { + return useQuery({ + queryKey: aclKeys.all(clusterId), + queryFn: () => aclsApi.list(clusterId), + }); +} + +export function useCreateAcls(clusterId: string) { + const queryClient = useQueryClient(); + return useMutation({ + mutationFn: (acls: AclBinding[]) => aclsApi.create(clusterId, acls), + onSuccess: () => queryClient.invalidateQueries({ queryKey: aclKeys.all(clusterId) }), + }); +} + +export function useDeleteAcls(clusterId: string) { + const queryClient = useQueryClient(); + return useMutation({ + mutationFn: (acls: AclBinding[]) => aclsApi.remove(clusterId, acls), + onSuccess: () => queryClient.invalidateQueries({ queryKey: aclKeys.all(clusterId) }), + }); +} diff --git a/frontend/features/acls/types.ts b/frontend/features/acls/types.ts new file mode 100644 index 0000000..19a1eef --- /dev/null +++ b/frontend/features/acls/types.ts @@ -0,0 +1,44 @@ +// Mirrors `crates/kui_kafka/src/acls.rs`. + +export type ResourceType = "topic" | "group" | "cluster" | "transactionalId"; + +/** literal: exactly this name, or every resource when it is `*`. prefixed: every name starting with it. */ +export type PatternType = "literal" | "prefixed"; + +export type Operation = + | "all" + | "read" + | "write" + | "create" + | "delete" + | "alter" + | "describe" + | "clusterAction" + | "describeConfigs" + | "alterConfigs" + | "idempotentWrite"; + +export type Permission = "allow" | "deny"; + +export interface AclBinding { + resourceType: ResourceType; + resourceName: string; + patternType: PatternType; + /** e.g. `User:alice`, or `User:*` for everyone. */ + principal: string; + /** An IP address, or `*` for any host. */ + host: string; + operation: Operation; + permission: Permission; +} + +/** The name a cluster resource always has. */ +export const CLUSTER_RESOURCE_NAME = "kafka-cluster"; + +/** The operations Kafka checks on each kind of resource; mirrors `ResourceType::operations`. */ +export const OPERATIONS: Record = { + topic: ["all", "read", "write", "create", "delete", "alter", "describe", "describeConfigs", "alterConfigs"], + group: ["all", "read", "delete", "describe"], + cluster: ["all", "create", "alter", "describe", "clusterAction", "describeConfigs", "alterConfigs", "idempotentWrite"], + transactionalId: ["all", "write", "describe"], +}; diff --git a/package.json b/package.json index e6c2c28..3d42824 100644 --- a/package.json +++ b/package.json @@ -18,7 +18,8 @@ "lint": "cargo fmt --all --check && cargo clippy --all-targets --locked -- -D warnings", "audit": "bun audit --audit-level=moderate && cargo audit", "kafka:up": "docker compose up -d", - "kafka:down": "docker compose down" + "kafka:down": "docker compose down", + "kafka:acl-demo": "cd examples/acl-demo && bun install --frozen-lockfile && bun run check" }, "dependencies": { "@codemirror/autocomplete": "^6.20.4",