From 94a0b1a5a800f73041b38c92967103a8cf820351 Mon Sep 17 00:00:00 2001 From: Truc Nguyen Date: Mon, 16 Nov 2026 08:20:47 +0000 Subject: [PATCH 1/2] feat(acls): list, create and delete Kafka ACLs Adds an ACLs page: filter a cluster's ACLs by principal, resource or host, create one ACL per chosen operation, and delete a single ACL after a confirmation. rust-rdkafka 0.39 doesn't wrap librdkafka's ACL admin API, so acl_admin.rs calls it directly, following the existing groups.rs exception to the unsafe lint. The shared request plumbing moves to admin_request.rs. Delete filters repeat every field of the ACL, never ANY/MATCH, so one delete can't remove other ACLs. Pure types and validation live in acls.rs, outside the exception. The dev and e2e brokers now run StandardAuthorizer with ANONYMOUS as a super user, so ACLs can be managed without locking out existing clients. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01JJgxwKrEXCgPunVy24RExr --- README.md | 6 + .../kui_desktop/src/features/acls/commands.rs | 26 ++ crates/kui_desktop/src/features/acls/mod.rs | 6 + crates/kui_desktop/src/features/acls/model.rs | 4 + .../kui_desktop/src/features/acls/service.rs | 73 ++++ crates/kui_desktop/src/features/mod.rs | 1 + crates/kui_desktop/src/integration_tests.rs | 38 +++ crates/kui_desktop/src/lib.rs | 5 +- crates/kui_desktop/src/security_tests.rs | 1 + crates/kui_kafka/src/acl_admin.rs | 312 ++++++++++++++++++ crates/kui_kafka/src/acls.rs | 237 +++++++++++++ crates/kui_kafka/src/admin_request.rs | 76 +++++ crates/kui_kafka/src/groups.rs | 53 +-- crates/kui_kafka/src/lib.rs | 7 +- docker-compose.yml | 10 + docs/CODE_STANDARDS.md | 4 + e2e/helpers.ts | 4 +- e2e/specs/08-no-unprompted-changes.e2e.ts | 24 ++ e2e/specs/11-acls.e2e.ts | 74 +++++ frontend/app/app-sidebar.tsx | 5 +- frontend/app/router.tsx | 3 + frontend/app/stores/navigation-store.ts | 3 +- frontend/features/acls/acl.test.ts | 79 +++++ frontend/features/acls/acl.ts | 77 +++++ frontend/features/acls/api.ts | 11 + .../features/acls/components/acls-page.tsx | 149 +++++++++ .../acls/components/create-acl-dialog.tsx | 198 +++++++++++ .../acls/components/delete-acl-button.tsx | 62 ++++ frontend/features/acls/index.ts | 1 + frontend/features/acls/queries.ts | 33 ++ frontend/features/acls/types.ts | 44 +++ 31 files changed, 1569 insertions(+), 57 deletions(-) create mode 100644 crates/kui_desktop/src/features/acls/commands.rs create mode 100644 crates/kui_desktop/src/features/acls/mod.rs create mode 100644 crates/kui_desktop/src/features/acls/model.rs create mode 100644 crates/kui_desktop/src/features/acls/service.rs create mode 100644 crates/kui_kafka/src/acl_admin.rs create mode 100644 crates/kui_kafka/src/acls.rs create mode 100644 crates/kui_kafka/src/admin_request.rs create mode 100644 e2e/specs/11-acls.e2e.ts create mode 100644 frontend/features/acls/acl.test.ts create mode 100644 frontend/features/acls/acl.ts create mode 100644 frontend/features/acls/api.ts create mode 100644 frontend/features/acls/components/acls-page.tsx create mode 100644 frontend/features/acls/components/create-acl-dialog.tsx create mode 100644 frontend/features/acls/components/delete-acl-button.tsx create mode 100644 frontend/features/acls/index.ts create mode 100644 frontend/features/acls/queries.ts create mode 100644 frontend/features/acls/types.ts diff --git a/README.md b/README.md index ed7685a..a25fa18 100644 --- a/README.md +++ b/README.md @@ -71,6 +71,12 @@ 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 +(`authorizer.class.name`). + ### 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..ac2a1af 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -28,6 +28,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:9092 > /dev/null interval: 5s @@ -70,6 +75,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/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/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/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"], +}; From fc23e005acaddcc542404eaff87ce0f591ecb894 Mon Sep 17 00:00:00 2001 From: Truc Nguyen Date: Mon, 16 Nov 2026 10:59:49 +0000 Subject: [PATCH 2/2] chore(acls): seed demo ACLs and prove they are enforced The ACLs page had nothing to show on a fresh dev broker, and every local client connects as ANONYMOUS, a super user, so no ACL could ever be seen refusing anything. The seed now creates 30 ACLs covering every resource type, literal and prefixed patterns, wildcards, DENY rules and host restrictions, plus an empty demo.payments topic to produce to. The dev broker gets a SASL/PLAIN listener on localhost:9094 with one login per demo principal, where the ACLs apply. examples/acl-demo logs in as those users with KafkaJS: `bun run kafka:acl-demo` tries 18 actions and exits 1 when the broker disagrees with the ACLs, and one small program per service shows how each would use Kafka. It never commits offsets, so demo-billing keeps its seeded lag. docs/LOCAL_KAFKA.md documents the demo data, listeners, logins and ACLs. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01JJgxwKrEXCgPunVy24RExr --- CONTRIBUTING.md | 4 +- README.md | 5 +- docker-compose.yml | 21 ++- docker/kafka-seed.sh | 41 ++++++ docs/LOCAL_KAFKA.md | 185 ++++++++++++++++++++++++ examples/acl-demo/README.md | 66 +++++++++ examples/acl-demo/bun.lock | 65 +++++++++ examples/acl-demo/check.ts | 151 +++++++++++++++++++ examples/acl-demo/kafka.ts | 37 +++++ examples/acl-demo/package.json | 20 +++ examples/acl-demo/services/analytics.ts | 21 +++ examples/acl-demo/services/auditor.ts | 21 +++ examples/acl-demo/services/billing.ts | 16 ++ examples/acl-demo/services/payments.ts | 29 ++++ examples/acl-demo/tsconfig.json | 14 ++ package.json | 3 +- 16 files changed, 691 insertions(+), 8 deletions(-) create mode 100644 docs/LOCAL_KAFKA.md create mode 100644 examples/acl-demo/README.md create mode 100644 examples/acl-demo/bun.lock create mode 100644 examples/acl-demo/check.ts create mode 100644 examples/acl-demo/kafka.ts create mode 100644 examples/acl-demo/package.json create mode 100644 examples/acl-demo/services/analytics.ts create mode 100644 examples/acl-demo/services/auditor.ts create mode 100644 examples/acl-demo/services/billing.ts create mode 100644 examples/acl-demo/services/payments.ts create mode 100644 examples/acl-demo/tsconfig.json 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 a25fa18..e80c3bf 100644 --- a/README.md +++ b/README.md @@ -74,8 +74,9 @@ See how far behind each consumer group is, and reset its offsets when it needs a ### 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 -(`authorizer.class.name`). +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 diff --git a/docker-compose.yml b/docker-compose.yml index ac2a1af..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 @@ -33,13 +38,21 @@ services: # 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: 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/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/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/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",