use std::error::Error;
use std::path::PathBuf;
use std::time::Duration;
use clap::{Args, Subcommand, ValueEnum};
use pb_mapper_auth::{
KeyPage, discard_staged_admin_key, generate_admin_key, stage_admin_key_candidate,
write_admin_key_file,
};
use pb_mapper_core::checksum::set_process_msg_header_key;
use pb_mapper_core::config::pb_mapper_server_addr;
use pb_mapper_protocol::command::{
ACTION_ADMINISTRATOR_KEY_ROTATED, AdminConnectionPage, AdminRequest, AdminResponse,
AdminServicePage,
};
use crate::parse_duration;
use crate::server::LegacyProtocolArg;
#[derive(Debug, Args)]
pub(super) struct AdminArgs {
#[arg(short, long, visible_alias = "pb-mapper-server", value_name = "ADDR")]
server: Option<String>,
#[arg(long, value_enum, default_value_t = OutputFormat::Human)]
output: OutputFormat,
#[command(subcommand)]
command: AdminCommand,
}
#[derive(Debug, Subcommand)]
enum AdminCommand {
Key(AdminKeyArgs),
Namespace(AdminNamespaceArgs),
Connection(AdminConnectionArgs),
Service(AdminServiceArgs),
Status,
AuthState(AdminAuthStateArgs),
RootKey(AdminRootKeyArgs),
LegacyProtocol(AdminLegacyProtocolArgs),
}
#[derive(Debug, Args)]
struct AdminKeyArgs {
#[command(subcommand)]
command: AdminKeyCommand,
}
#[derive(Debug, Subcommand)]
enum AdminKeyCommand {
Issue {
#[arg(long, value_parser = parse_duration)]
ttl: Duration,
#[arg(long)]
label: Option<String>,
#[arg(long)]
namespace: Option<u64>,
},
List {
#[arg(long, default_value_t = 0)]
page: u32,
#[arg(long, default_value_t = 100, value_parser = clap::value_parser!(u16).range(1..=1000))]
page_size: u16,
#[arg(long, default_value_t = false)]
all: bool,
},
Show {
key_id: u64,
},
Reveal {
key_id: u64,
},
Renew {
key_id: u64,
#[arg(long, value_parser = parse_duration)]
ttl: Duration,
},
Revoke {
key_id: u64,
},
Gc,
}
#[derive(Debug, Args)]
struct AdminConnectionArgs {
#[command(subcommand)]
command: AdminConnectionCommand,
}
#[derive(Debug, Args)]
struct AdminServiceArgs {
#[command(subcommand)]
command: AdminServiceCommand,
}
#[derive(Debug, Clone, Args)]
struct AdminListArgs {
#[arg(long, visible_alias = "key-id")]
namespace: Option<u64>,
#[arg(long, default_value_t = 0)]
page: u32,
#[arg(long, default_value_t = 100, value_parser = clap::value_parser!(u16).range(1..=1000))]
page_size: u16,
#[arg(long, default_value_t = false)]
all: bool,
}
#[derive(Debug, Clone, Subcommand)]
enum AdminConnectionCommand {
List(AdminListArgs),
#[command(group = clap::ArgGroup::new("target").required(true))]
Retire {
service_name: String,
#[arg(long, visible_alias = "key-id")]
namespace: Option<u64>,
#[arg(long, group = "target")]
conn_id: Option<u32>,
#[arg(long, group = "target", default_value_t = false)]
all: bool,
},
}
#[derive(Debug, Clone, Subcommand)]
enum AdminServiceCommand {
List(AdminListArgs),
}
#[derive(Debug, Args)]
struct AdminNamespaceArgs {
#[command(subcommand)]
command: AdminNamespaceCommand,
}
#[derive(Debug, Subcommand)]
enum AdminNamespaceCommand {
Allocate,
}
#[derive(Debug, Args)]
struct AdminAuthStateArgs {
#[command(subcommand)]
command: AdminAuthStateCommand,
}
#[derive(Debug, Subcommand)]
enum AdminAuthStateCommand {
Reset {
#[arg(long, default_value_t = false)]
confirm: bool,
},
}
#[derive(Debug, Args)]
struct AdminRootKeyArgs {
#[command(subcommand)]
command: AdminRootKeyCommand,
}
#[derive(Debug, Subcommand)]
enum AdminRootKeyCommand {
Rotate {
#[arg(long)]
new_key: Option<String>,
#[arg(long)]
key_file: Option<PathBuf>,
},
}
#[derive(Debug, Args)]
struct AdminLegacyProtocolArgs {
#[command(subcommand)]
command: AdminLegacyProtocolCommand,
}
#[derive(Debug, Subcommand)]
enum AdminLegacyProtocolCommand {
Set { policy: LegacyProtocolArg },
}
#[derive(Clone, Copy, Debug, Eq, PartialEq, ValueEnum)]
enum OutputFormat {
Human,
Json,
Ndjson,
}
pub(super) async fn run_admin(args: AdminArgs) -> Result<(), Box<dyn Error>> {
let remote_addr = pb_mapper_server_addr(args.server.as_deref())?;
let remote_addr = remote_addr.as_str();
let output = args.output;
let request = match args.command {
AdminCommand::Namespace(AdminNamespaceArgs {
command: AdminNamespaceCommand::Allocate,
}) => AdminRequest::NamespaceAllocate,
AdminCommand::Key(AdminKeyArgs { command }) => match command {
AdminKeyCommand::Issue {
ttl,
label,
namespace,
} => {
let ttl_seconds = ttl.as_secs();
match namespace {
Some(namespace) => AdminRequest::KeyIssueScoped {
namespace,
ttl_seconds,
label,
},
None => AdminRequest::KeyIssue { ttl_seconds, label },
}
}
AdminKeyCommand::List {
page,
page_size,
all,
} => {
return stream_pages::<KeyPage, _>(remote_addr, output, page, all, |page| {
AdminRequest::KeyList { page, page_size }
})
.await;
}
AdminKeyCommand::Show { key_id } => AdminRequest::KeyShow { key_id },
AdminKeyCommand::Reveal { key_id } => AdminRequest::KeyReveal { key_id },
AdminKeyCommand::Renew { key_id, ttl } => AdminRequest::KeyRenew {
key_id,
ttl_seconds: ttl.as_secs(),
},
AdminKeyCommand::Revoke { key_id } => AdminRequest::KeyRevoke { key_id },
AdminKeyCommand::Gc => AdminRequest::KeyGc,
},
AdminCommand::Connection(AdminConnectionArgs { command }) => match command {
AdminConnectionCommand::List(AdminListArgs {
namespace,
page,
page_size,
all,
}) => {
return stream_pages::<AdminConnectionPage, _>(
remote_addr,
output,
page,
all,
|page| AdminRequest::ConnectionList {
key_id: namespace,
page,
page_size,
},
)
.await;
}
AdminConnectionCommand::Retire {
service_name,
namespace,
conn_id,
all,
} => {
let conn_id = if all { None } else { conn_id };
AdminRequest::ConnectionRetire {
key_id: namespace,
service_name,
conn_id,
}
}
},
AdminCommand::Service(AdminServiceArgs {
command:
AdminServiceCommand::List(AdminListArgs {
namespace,
page,
page_size,
all,
}),
}) => {
return stream_pages::<AdminServicePage, _>(remote_addr, output, page, all, |page| {
AdminRequest::ServiceList {
key_id: namespace,
page,
page_size,
}
})
.await;
}
AdminCommand::Status => AdminRequest::AuthStatus,
AdminCommand::AuthState(AdminAuthStateArgs {
command: AdminAuthStateCommand::Reset { confirm },
}) => AdminRequest::AuthStateReset { confirm },
AdminCommand::RootKey(AdminRootKeyArgs {
command: AdminRootKeyCommand::Rotate { new_key, key_file },
}) => return rotate_root_key(remote_addr, output, new_key, key_file).await,
AdminCommand::LegacyProtocol(AdminLegacyProtocolArgs {
command: AdminLegacyProtocolCommand::Set { policy },
}) => AdminRequest::LegacyProtocolSet {
policy: policy.into(),
},
};
let response = send_admin_request(remote_addr, request).await?;
print_admin_response(output, &response)
}
async fn rotate_root_key(
remote_addr: &str,
output: OutputFormat,
new_key: Option<String>,
key_file: Option<PathBuf>,
) -> Result<(), Box<dyn Error>> {
let key_file = match key_file {
Some(key_file) => key_file,
None => default_admin_recovery_key_file()?,
};
let new_key = new_key.unwrap_or_else(generate_admin_key);
let staged_key_file = stage_admin_key_candidate(&key_file, &new_key)?;
let client = admin_client(remote_addr)?;
let response = match client.admin()?.rotate_root_key(Some(new_key.clone())).await {
Ok(_) => AdminResponse::Ok {
action: ACTION_ADMINISTRATOR_KEY_ROTATED.to_string(),
},
Err(error) => {
return Err(std::io::Error::other(format!(
"root rotation request failed; the candidate key remains at `{}`: {error}",
staged_key_file.display()
))
.into());
}
};
set_process_msg_header_key(Some(&new_key))?;
client.admin()?.auth_status().await.map_err(|error| {
std::io::Error::other(format!(
"new administrator key did not pass the post-rotation status check: {error}"
))
})?;
write_admin_key_file(&key_file, &new_key, true).map_err(|error| {
std::io::Error::other(format!(
"administrator key rotated and verified, but `{}` could not be updated; recover the key from `{}`: {error}",
key_file.display(),
staged_key_file.display()
))
})?;
discard_staged_admin_key(&staged_key_file);
if output == OutputFormat::Human {
println!("administrator key rotated and verified");
println!("all temporary credentials are now invalid (temporary_key_rotated)");
println!("key file: {}", key_file.display());
} else {
print_admin_response(output, &response)?;
}
Ok(())
}
fn admin_client(remote_addr: &str) -> Result<pb_mapper_client::sdk::Client, Box<dyn Error>> {
let credential =
pb_mapper_core::checksum::get_process_credential().map_err(std::io::Error::other)?;
Ok(pb_mapper_client::sdk::Client::from_credential(
remote_addr.to_string(),
credential,
false,
None,
))
}
async fn send_admin_request(
remote_addr: &str,
request: AdminRequest,
) -> Result<AdminResponse, Box<dyn Error>> {
let client = admin_client(remote_addr)?;
Ok(client.admin()?.request(request).await?)
}
trait AdminPage {
const LABEL: &'static str;
fn from_response(response: &AdminResponse) -> Option<&Self>;
fn into_response(self) -> AdminResponse;
fn next_page(&self) -> Option<u32>;
fn print_ndjson(&self) -> Result<(), Box<dyn Error>>;
fn empty_clone(&self) -> Self;
fn absorb(&mut self, page: &Self);
}
macro_rules! impl_admin_page {
($page:ty, variant = $variant:ident, label = $label:literal) => {
impl AdminPage for $page {
const LABEL: &'static str = $label;
fn from_response(response: &AdminResponse) -> Option<&Self> {
match response {
AdminResponse::$variant(page) => Some(page),
_ => None,
}
}
fn into_response(self) -> AdminResponse {
AdminResponse::$variant(self)
}
fn next_page(&self) -> Option<u32> {
self.next_page
}
fn print_ndjson(&self) -> Result<(), Box<dyn Error>> {
for item in &self.items {
println!("{}", serde_json::to_string(item)?);
}
Ok(())
}
fn empty_clone(&self) -> Self {
let Self {
schema_version,
items: _,
next_page: _,
} = self;
Self {
schema_version: *schema_version,
items: Vec::new(),
next_page: None,
}
}
fn absorb(&mut self, page: &Self) {
let Self {
schema_version: _,
items,
next_page: _,
} = page;
self.items.extend_from_slice(items);
}
}
};
}
impl_admin_page!(KeyPage, variant = KeyList, label = "key-list");
impl_admin_page!(AdminServicePage, variant = Services, label = "service-list");
impl_admin_page!(
AdminConnectionPage,
variant = Connections,
label = "connection-list"
);
async fn stream_pages<P, F>(
remote_addr: &str,
output: OutputFormat,
mut page: u32,
all: bool,
request: F,
) -> Result<(), Box<dyn Error>>
where
P: AdminPage,
F: Fn(u32) -> AdminRequest,
{
let mut aggregated: Option<P> = None;
loop {
let response = send_admin_request(remote_addr, request(page)).await?;
let Some(current) = P::from_response(&response) else {
return Err(std::io::Error::other(format!("unexpected {} response", P::LABEL)).into());
};
match (all, output) {
(false, _) => print_admin_response(output, &response)?,
(true, OutputFormat::Ndjson) => current.print_ndjson()?,
(true, _) => aggregated
.get_or_insert_with(|| current.empty_clone())
.absorb(current),
}
match current.next_page() {
Some(next_page) if all => page = next_page,
_ => break,
}
}
if let Some(aggregated) = aggregated {
print_admin_response(output, &aggregated.into_response())?;
}
Ok(())
}
fn print_admin_response(
output: OutputFormat,
response: &AdminResponse,
) -> Result<(), Box<dyn Error>> {
match output {
OutputFormat::Json => println!(
"{}",
serde_json::to_string_pretty(&serde_json::json!({
"schema_version": 1,
"data": response,
}))?
),
OutputFormat::Ndjson => println!("{}", serde_json::to_string(response)?),
OutputFormat::Human => print_human_admin_response(response),
}
Ok(())
}
fn print_human_admin_response(response: &AdminResponse) {
match response {
AdminResponse::KeyIssued(key)
| AdminResponse::KeyShown(key)
| AdminResponse::KeyRenewed(key) => {
println!("key id: {}", key.metadata.key_id);
println!("namespace: {}", key.metadata.effective_namespace());
println!("state: {}", key.metadata.state);
println!("expires at: {}", key.metadata.expires_at);
if let Some(label) = &key.metadata.label {
println!("label: {label}");
}
if !key.credential.is_empty() {
println!("credential: {}", key.credential);
}
}
AdminResponse::KeyRevoked(key) => {
println!("key {}: {}", key.key_id, key.state);
}
AdminResponse::KeyList(page) => {
println!("KEY ID\tNAMESPACE\tSTATE\tEXPIRES\tLABEL");
for key in &page.items {
println!(
"{}\t{}\t{}\t{}\t{}",
key.key_id,
key.effective_namespace(),
key.state,
key.expires_at,
key.label.as_deref().unwrap_or("")
);
}
if let Some(next) = page.next_page {
println!("next page: {next}");
}
}
AdminResponse::NamespaceAllocated { namespace } => println!("namespace: {namespace}"),
AdminResponse::KeyGc { removed } => println!("removed {removed} inactive keys"),
AdminResponse::AuthStatus(status) => {
println!("safe mode: {}", status.safe_mode);
println!(
"keys: {} active / {} expired / {} revoked / {} capacity",
status.active_keys, status.expired_keys, status.revoked_keys, status.capacity
);
println!("legacy protocol: {:?}", status.legacy_protocol);
println!(
"active legacy connections: {}",
status.active_legacy_connections
);
println!(
"last legacy connection: {}",
status
.last_legacy_connection_at
.map(|value| value.to_string())
.unwrap_or_else(|| "never".to_string())
);
println!(
"authentication: {} succeeded / {} failed",
status.auth_successes, status.auth_failures
);
println!("server instance: {}", status.server_instance_id);
println!("capabilities: {}", status.capabilities.join(", "));
}
AdminResponse::Services(page) => {
println!("NAMESPACE\tSERVICE\tTRANSPORT\tCODEC\tCONNECTIONS");
for service in &page.items {
println!(
"{}\t{}\t{}\t{}\t{}",
service.namespace,
service.service_name,
service.transport,
service.codec_enabled,
service.connection_count
);
}
if let Some(next) = page.next_page {
println!("next page: {next}");
}
}
AdminResponse::Connections(page) => {
println!("NAMESPACE\tSERVICE\tCONN ID\tHEALTHY\tIDLE MS\tTRANSPORT\tCODEC");
for connection in &page.items {
println!(
"{}\t{}\t{}\t{}\t{}\t{}\t{}",
connection.namespace,
connection.service_name,
connection.conn_id,
connection.healthy,
connection.last_rx_age_ms,
connection.transport,
connection.codec_enabled
);
}
if let Some(next) = page.next_page {
println!("next page: {next}");
}
}
AdminResponse::ConnectionsRetired { retired } => {
println!("retired {retired} registered connections");
}
AdminResponse::Ok { action } => println!("ok: {action}"),
}
}
fn default_admin_recovery_key_file() -> std::io::Result<PathBuf> {
recovery_key_file_in(|name| std::env::var_os(name))
}
fn recovery_key_file_in(
var: impl Fn(&str) -> Option<std::ffi::OsString>,
) -> std::io::Result<PathBuf> {
let whole = |name| {
var(name)
.map(PathBuf::from)
.filter(|path| path.is_absolute())
};
let home = || {
whole("HOME")
.or_else(|| cfg!(windows).then(|| whole("USERPROFILE")).flatten())
.map(|home| home.join(".config"))
};
let config = whole("XDG_CONFIG_HOME").or_else(home).ok_or_else(|| {
std::io::Error::new(
std::io::ErrorKind::NotFound,
"no home directory to keep the new administrator key in; pass --key-file",
)
})?;
Ok(config.join("pb-mapper").join("admin.key"))
}
#[cfg(test)]
mod tests {
use std::ffi::OsString;
use super::*;
fn only(vars: Vec<(&'static str, OsString)>) -> impl Fn(&str) -> Option<OsString> {
move |name| {
vars.iter()
.find(|(var, _)| *var == name)
.map(|(_, value)| value.clone())
}
}
#[test]
fn the_recovery_key_lands_in_the_users_config_or_nowhere() {
let home = std::env::temp_dir();
let config = home.join("config");
assert_eq!(
recovery_key_file_in(only(vec![
("XDG_CONFIG_HOME", config.clone().into()),
("HOME", home.clone().into()),
]))
.unwrap(),
config.join("pb-mapper").join("admin.key")
);
let in_home = home.join(".config").join("pb-mapper").join("admin.key");
assert_eq!(
recovery_key_file_in(only(vec![("HOME", home.clone().into())])).unwrap(),
in_home
);
let from_profile = recovery_key_file_in(only(vec![("USERPROFILE", home.into())]));
if cfg!(windows) {
assert_eq!(from_profile.unwrap(), in_home);
} else {
assert!(from_profile.is_err());
}
assert!(recovery_key_file_in(only(Vec::new())).is_err());
assert!(
recovery_key_file_in(only(vec![
("XDG_CONFIG_HOME", "".into()),
("HOME", "home".into()),
]))
.is_err()
);
}
}