Files
khadhroony-solana-project/crates/ksp-wallet-lib/src/transfer.rs
2026-08-22 08:18:38 +02:00

481 lines
22 KiB
Rust

// file: crates/ksp-wallet-lib/src/transfer.rs
// version: 4
//! Explicit OWNER-only Solana keypair import/export adapters.
use std::io::Read; // rust-rules: trait-import
use std::io::Write; // rust-rules: trait-import
#[cfg(unix)]
use std::os::unix::fs::PermissionsExt; // rust-rules: trait-import
use zeroize::Zeroize; // rust-rules: trait-import
/// Explicit secret-transfer formats supported by Wallet.
#[non_exhaustive]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum WalletTransferFormat {
/// Standard Solana CLI keypair JSON array containing exactly 64 byte values.
SolanaCliJson,
/// Canonical Base58 encoding of the complete 64-byte Solana keypair.
SolanaKeypairBase58,
}
impl WalletTransferFormat {
/// Returns every transfer format currently supported for both import and OWNER export.
#[must_use]
pub const fn supported() -> [Self; 2] {
return [Self::SolanaCliJson, Self::SolanaKeypairBase58];
}
/// Returns the stable machine-readable format code.
#[must_use]
pub const fn code(self) -> &'static str {
return match self {
Self::SolanaCliJson => "solana_cli_json",
Self::SolanaKeypairBase58 => "solana_keypair_base58",
};
}
/// Returns a human-readable label that states the exact key material carried by the format.
#[must_use]
pub const fn label(self) -> &'static str {
return match self {
Self::SolanaCliJson => "Solana CLI keypair JSON (64 bytes)",
Self::SolanaKeypairBase58 => "Solana keypair Base58 (64 bytes)",
};
}
/// Returns the conventional file extension for this transfer format.
#[must_use]
pub const fn default_extension(self) -> &'static str {
return match self {
Self::SolanaCliJson => "json",
Self::SolanaKeypairBase58 => "txt",
};
}
const fn maximum_source_bytes(self) -> usize {
return match self {
Self::SolanaCliJson => crate::KSPWALLET_TRANSFER_MAX_SOLANA_CLI_JSON_BYTES,
Self::SolanaKeypairBase58 => crate::KSPWALLET_TRANSFER_MAX_BASE58_BYTES,
};
}
}
/// Safe public projection produced after validating an external secret-transfer source.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct WalletTransferInspection {
pubkey: ksp_core_lib::Pubkey,
format: WalletTransferFormat,
}
impl WalletTransferInspection {
/// Returns the Solana public key derived from the validated external keypair.
#[must_use]
pub const fn pubkey(&self) -> &ksp_core_lib::Pubkey {
return &self.pubkey;
}
/// Returns the transfer format used for validation.
#[must_use]
pub const fn format(&self) -> WalletTransferFormat {
return self.format;
}
}
/// Validates one in-memory transfer payload and exposes only its derived public identity.
///
/// The caller retains ownership of `source`; if it contains secret key material, the caller is responsible for zeroizing that buffer when appropriate.
pub fn inspect_wallet_transfer(source: &[u8], format: WalletTransferFormat) -> ksp_core_lib::Result<WalletTransferInspection> {
let keypair = match decode_transfer_keypair(source, format) {
std::result::Result::Ok(value) => value,
std::result::Result::Err(error) => return std::result::Result::Err(error),
};
let pubkey = keypair_pubkey(&keypair);
return std::result::Result::Ok(WalletTransferInspection { pubkey, format });
}
/// Reads and validates one bounded external transfer file and exposes only its derived public identity.
pub async fn inspect_wallet_transfer_file(
source: impl std::convert::AsRef<std::path::Path>,
format: WalletTransferFormat,
) -> ksp_core_lib::Result<WalletTransferInspection> {
let bytes = match read_transfer_file_async(source.as_ref().to_path_buf(), format).await {
std::result::Result::Ok(value) => zeroize::Zeroizing::new(value),
std::result::Result::Err(error) => return std::result::Result::Err(error),
};
return inspect_wallet_transfer(bytes.as_slice(), format);
}
/// Imports one in-memory Solana keypair transfer payload into a new native Wallet using [`crate::DEFAULT_WALLET_FORMAT`].
pub async fn import_wallet_transfer(
destination: impl std::convert::AsRef<std::path::Path>,
source: &[u8],
format: WalletTransferFormat,
owner_password: crate::OwnerPassword,
view_password: std::option::Option<crate::ViewPassword>,
metadata: crate::WalletCreateMetadata,
) -> ksp_core_lib::Result<crate::WalletOwner> {
return match crate::DEFAULT_WALLET_FORMAT {
crate::WalletFormat::V1 => import_wallet_transfer_v1(destination, source, format, owner_password, view_password, metadata).await,
crate::WalletFormat::V2 => import_wallet_transfer_v2(destination, source, format, owner_password, view_password, metadata).await,
};
}
/// Imports one in-memory Solana keypair transfer payload into a new native `.kspwallet` V2 binary file.
pub async fn import_wallet_transfer_v2(
destination: impl std::convert::AsRef<std::path::Path>,
source: &[u8],
format: WalletTransferFormat,
owner_password: crate::OwnerPassword,
view_password: std::option::Option<crate::ViewPassword>,
metadata: crate::WalletCreateMetadata,
) -> ksp_core_lib::Result<crate::WalletOwner> {
let keypair = match decode_transfer_keypair(source, format) {
std::result::Result::Ok(value) => value,
std::result::Result::Err(error) => return std::result::Result::Err(error),
};
let owner = match crate::create_wallet_v2_from_keypair(owner_password, view_password, metadata, keypair).await {
std::result::Result::Ok(value) => value,
std::result::Result::Err(error) => return std::result::Result::Err(error),
};
let serialized = match owner.to_native_bytes() {
std::result::Result::Ok(value) => value,
std::result::Result::Err(error) => return std::result::Result::Err(error),
};
if let std::result::Result::Err(error) = crate::persist_new_wallet_content(destination.as_ref().to_path_buf(), serialized).await {
return std::result::Result::Err(error);
}
ksp_logging_lib::debug!(
target: crate::TRACING_TARGET,
operation = "wallet_import_transfer",
format_version = crate::KSPWALLET_FORMAT_VERSION_V2,
transfer_format = format.code(),
"external Solana keypair imported into a new native wallet"
);
return std::result::Result::Ok(owner);
}
/// Imports one in-memory Solana keypair transfer payload into a new native `.kspwallet` V1 file.
///
/// Import always creates a fresh native Wallet envelope around the validated immutable Solana keypair and publishes with the same no-clobber semantics as
/// native creation. An existing destination is never overwritten. The caller retains ownership of `source` and must zeroize it when appropriate.
pub async fn import_wallet_transfer_v1(
destination: impl std::convert::AsRef<std::path::Path>,
source: &[u8],
format: WalletTransferFormat,
owner_password: crate::OwnerPassword,
view_password: std::option::Option<crate::ViewPassword>,
metadata: crate::WalletCreateMetadataV1,
) -> ksp_core_lib::Result<crate::WalletOwner> {
let keypair = match decode_transfer_keypair(source, format) {
std::result::Result::Ok(value) => value,
std::result::Result::Err(error) => return std::result::Result::Err(error),
};
let owner = match crate::create_wallet_v1_from_keypair(owner_password, view_password, metadata, keypair).await {
std::result::Result::Ok(value) => value,
std::result::Result::Err(error) => return std::result::Result::Err(error),
};
let serialized = match owner.to_json_bytes() {
std::result::Result::Ok(value) => value,
std::result::Result::Err(error) => return std::result::Result::Err(error),
};
let persist_result = crate::persist_new_wallet_content_v1(destination.as_ref().to_path_buf(), serialized).await;
if let std::result::Result::Err(error) = persist_result {
return std::result::Result::Err(error);
}
ksp_logging_lib::debug!(
target: crate::TRACING_TARGET,
operation = "wallet_import_transfer",
transfer_format = format.code(),
"external Solana keypair imported into a new native wallet"
);
return std::result::Result::Ok(owner);
}
/// Imports one bounded external transfer file into a new native Wallet using [`crate::DEFAULT_WALLET_FORMAT`].
pub async fn import_wallet_transfer_file(
destination: impl std::convert::AsRef<std::path::Path>,
source: impl std::convert::AsRef<std::path::Path>,
format: WalletTransferFormat,
owner_password: crate::OwnerPassword,
view_password: std::option::Option<crate::ViewPassword>,
metadata: crate::WalletCreateMetadata,
) -> ksp_core_lib::Result<crate::WalletOwner> {
let bytes = match read_transfer_file_async(source.as_ref().to_path_buf(), format).await {
std::result::Result::Ok(value) => zeroize::Zeroizing::new(value),
std::result::Result::Err(error) => return std::result::Result::Err(error),
};
return import_wallet_transfer(destination, bytes.as_slice(), format, owner_password, view_password, metadata).await;
}
/// Imports one bounded external transfer file into a new native `.kspwallet` V2 binary file.
pub async fn import_wallet_transfer_file_v2(
destination: impl std::convert::AsRef<std::path::Path>,
source: impl std::convert::AsRef<std::path::Path>,
format: WalletTransferFormat,
owner_password: crate::OwnerPassword,
view_password: std::option::Option<crate::ViewPassword>,
metadata: crate::WalletCreateMetadata,
) -> ksp_core_lib::Result<crate::WalletOwner> {
let bytes = match read_transfer_file_async(source.as_ref().to_path_buf(), format).await {
std::result::Result::Ok(value) => zeroize::Zeroizing::new(value),
std::result::Result::Err(error) => return std::result::Result::Err(error),
};
return import_wallet_transfer_v2(destination, bytes.as_slice(), format, owner_password, view_password, metadata).await;
}
/// Imports one bounded external transfer file into a new native `.kspwallet` V1 file.
///
/// The source file is never modified and the destination remains no-clobber.
pub async fn import_wallet_transfer_file_v1(
destination: impl std::convert::AsRef<std::path::Path>,
source: impl std::convert::AsRef<std::path::Path>,
format: WalletTransferFormat,
owner_password: crate::OwnerPassword,
view_password: std::option::Option<crate::ViewPassword>,
metadata: crate::WalletCreateMetadataV1,
) -> ksp_core_lib::Result<crate::WalletOwner> {
let bytes = match read_transfer_file_async(source.as_ref().to_path_buf(), format).await {
std::result::Result::Ok(value) => zeroize::Zeroizing::new(value),
std::result::Result::Err(error) => return std::result::Result::Err(error),
};
return import_wallet_transfer_v1(destination, bytes.as_slice(), format, owner_password, view_password, metadata).await;
}
/// Writes one bounded OWNER export using no-clobber external transfer semantics.
pub(crate) async fn write_wallet_transfer_file(
destination: std::path::PathBuf,
content: std::vec::Vec<u8>,
format: WalletTransferFormat,
) -> ksp_core_lib::Result<()> {
let content = zeroize::Zeroizing::new(content);
if content.len() > format.maximum_source_bytes() {
return std::result::Result::Err(key_material_error(format, "encoded transfer exceeds the supported format bound"));
}
let task = tokio::task::spawn_blocking(move || return write_transfer_file_blocking(destination.as_path(), content.as_slice()));
return match task.await {
std::result::Result::Ok(result) => result,
std::result::Result::Err(error) => std::result::Result::Err(blocking_transfer_error("export_task", error)),
};
}
fn decode_transfer_keypair(source: &[u8], format: WalletTransferFormat) -> ksp_core_lib::Result<solana_keypair::Keypair> {
if source.is_empty() || source.len() > format.maximum_source_bytes() {
return std::result::Result::Err(key_material_error(format, "transfer source length is invalid"));
}
return match format {
WalletTransferFormat::SolanaCliJson => decode_solana_cli_json(source, format),
WalletTransferFormat::SolanaKeypairBase58 => decode_solana_keypair_base58(source, format),
};
}
fn decode_solana_cli_json(source: &[u8], format: WalletTransferFormat) -> ksp_core_lib::Result<solana_keypair::Keypair> {
let decoded_result = serde_json::from_slice::<std::vec::Vec<u8>>(source);
let mut decoded = match decoded_result {
std::result::Result::Ok(value) => value,
std::result::Result::Err(_) => return std::result::Result::Err(key_material_error(format, "transfer source is not a Solana CLI byte array")),
};
if decoded.len() != crate::KSPWALLET_V1_SECRET_PLAINTEXT_BYTES {
decoded.zeroize();
return std::result::Result::Err(key_material_error(format, "Solana CLI keypair must contain exactly 64 bytes"));
}
let keypair_result = solana_keypair::Keypair::try_from(decoded.as_slice());
decoded.zeroize();
return match keypair_result {
std::result::Result::Ok(value) => std::result::Result::Ok(value),
std::result::Result::Err(_) => std::result::Result::Err(key_material_error(format, "Solana CLI keypair bytes are inconsistent")),
};
}
fn decode_solana_keypair_base58(source: &[u8], format: WalletTransferFormat) -> ksp_core_lib::Result<solana_keypair::Keypair> {
let source_text = match std::str::from_utf8(source) {
std::result::Result::Ok(value) => value,
std::result::Result::Err(_) => return std::result::Result::Err(key_material_error(format, "Base58 transfer source is not UTF-8")),
};
if source_text.trim() != source_text {
return std::result::Result::Err(key_material_error(format, "Base58 transfer source must not contain surrounding whitespace"));
}
let keypair = match solana_keypair::Keypair::try_from_base58_string(source_text) {
std::result::Result::Ok(value) => value,
std::result::Result::Err(_) => {
return std::result::Result::Err(key_material_error(format, "Base58 transfer source is not a valid 64-byte Solana keypair"));
},
};
let mut canonical = keypair.to_base58_string();
let canonical_matches = canonical.as_str() == source_text;
canonical.zeroize();
if !canonical_matches {
return std::result::Result::Err(key_material_error(format, "Base58 transfer source is not canonical"));
}
return std::result::Result::Ok(keypair);
}
fn keypair_pubkey(keypair: &solana_keypair::Keypair) -> ksp_core_lib::Pubkey {
let mut keypair_bytes = keypair.to_bytes();
let mut public_bytes = [0_u8; 32];
public_bytes.copy_from_slice(&keypair_bytes[32..64]);
keypair_bytes.zeroize();
return ksp_core_lib::Pubkey::new_from_array(public_bytes);
}
async fn read_transfer_file_async(source: std::path::PathBuf, format: WalletTransferFormat) -> ksp_core_lib::Result<std::vec::Vec<u8>> {
let task = tokio::task::spawn_blocking(move || return read_transfer_file_blocking(source.as_path(), format));
return match task.await {
std::result::Result::Ok(result) => result,
std::result::Result::Err(error) => std::result::Result::Err(blocking_transfer_error("read_task", error)),
};
}
fn read_transfer_file_blocking(source: &std::path::Path, format: WalletTransferFormat) -> ksp_core_lib::Result<std::vec::Vec<u8>> {
let file = match std::fs::File::open(source) {
std::result::Result::Ok(value) => value,
std::result::Result::Err(error) => return std::result::Result::Err(transfer_io_error("source_open", error)),
};
let metadata = match file.metadata() {
std::result::Result::Ok(value) => value,
std::result::Result::Err(error) => return std::result::Result::Err(transfer_io_error("source_metadata", error)),
};
if !metadata.is_file() {
return std::result::Result::Err(key_material_error(format, "transfer source must be a regular file"));
}
let maximum = format.maximum_source_bytes();
if metadata.len() > maximum as u64 {
return std::result::Result::Err(key_material_error(format, "transfer source exceeds the supported format bound"));
}
let mut reader = file.take((maximum + 1) as u64);
let mut bytes = std::vec::Vec::with_capacity(maximum.min(metadata.len() as usize));
if let std::result::Result::Err(error) = reader.read_to_end(&mut bytes) {
bytes.zeroize();
return std::result::Result::Err(transfer_io_error("source_read", error));
}
if bytes.len() > maximum {
bytes.zeroize();
return std::result::Result::Err(key_material_error(format, "transfer source exceeds the supported format bound"));
}
return std::result::Result::Ok(bytes);
}
fn write_transfer_file_blocking(destination: &std::path::Path, content: &[u8]) -> ksp_core_lib::Result<()> {
let parent = match destination_parent(destination) {
std::result::Result::Ok(value) => value,
std::result::Result::Err(error) => return std::result::Result::Err(error),
};
if destination.file_name().is_none() {
return std::result::Result::Err(transfer_atomic_error("destination", "transfer destination has no file name"));
}
let temporary_result = tempfile::Builder::new().prefix(".kspwallet-export-").suffix(".tmp").tempfile_in(parent);
let mut temporary = match temporary_result {
std::result::Result::Ok(value) => value,
std::result::Result::Err(error) => return std::result::Result::Err(transfer_atomic_io_error("temporary_create", error)),
};
set_private_permissions_best_effort(temporary.as_file());
if let std::result::Result::Err(error) = temporary.write_all(content) {
return std::result::Result::Err(transfer_atomic_io_error("temporary_write", error));
}
if let std::result::Result::Err(error) = temporary.as_file().sync_all() {
return std::result::Result::Err(transfer_atomic_io_error("temporary_sync", error));
}
let persist_result = temporary.persist_noclobber(destination);
let persisted = match persist_result {
std::result::Result::Ok(value) => value,
std::result::Result::Err(error) => {
if error.error.kind() == std::io::ErrorKind::AlreadyExists {
return std::result::Result::Err(ksp_core_lib::Error::new(crate::ERROR_CODE_DESTINATION_EXISTS, "Wallet transfer destination already exists"));
}
return std::result::Result::Err(transfer_atomic_io_error("publish_noclobber", error.error));
},
};
if let std::result::Result::Err(error) = persisted.sync_all() {
return std::result::Result::Err(transfer_atomic_io_error("published_file_sync", error));
}
sync_parent_directory_best_effort(parent);
return std::result::Result::Ok(());
}
fn destination_parent(destination: &std::path::Path) -> ksp_core_lib::Result<&std::path::Path> {
return match destination.parent() {
std::option::Option::Some(parent) if !parent.as_os_str().is_empty() => std::result::Result::Ok(parent),
std::option::Option::Some(_) => std::result::Result::Ok(std::path::Path::new(".")),
std::option::Option::None => std::result::Result::Err(transfer_atomic_error("destination", "transfer destination has no parent directory")),
};
}
#[cfg(unix)]
fn set_private_permissions_best_effort(file: &std::fs::File) {
let permissions = std::fs::Permissions::from_mode(0o600);
if let std::result::Result::Err(error) = file.set_permissions(permissions) {
ksp_logging_lib::warn!(
target: crate::TRACING_TARGET,
operation = "wallet_transfer_permissions",
io_kind = ?error.kind(),
"wallet transfer export continues without the optional Unix 0600 hygiene hardening"
);
}
return;
}
#[cfg(not(unix))]
fn set_private_permissions_best_effort(_file: &std::fs::File) {
return;
}
#[cfg(unix)]
fn sync_parent_directory_best_effort(parent: &std::path::Path) {
let directory = match std::fs::File::open(parent) {
std::result::Result::Ok(value) => value,
std::result::Result::Err(error) => {
ksp_logging_lib::warn!(
target: crate::TRACING_TARGET,
operation = "wallet_transfer_parent_sync",
io_kind = ?error.kind(),
"wallet transfer export succeeded but parent-directory sync could not start"
);
return;
},
};
if let std::result::Result::Err(error) = directory.sync_all() {
ksp_logging_lib::warn!(
target: crate::TRACING_TARGET,
operation = "wallet_transfer_parent_sync",
io_kind = ?error.kind(),
"wallet transfer export succeeded but parent-directory sync failed"
);
}
return;
}
#[cfg(not(unix))]
fn sync_parent_directory_best_effort(_parent: &std::path::Path) {
return;
}
fn key_material_error(format: WalletTransferFormat, message: &'static str) -> ksp_core_lib::Error {
return ksp_core_lib::Error::new(crate::ERROR_CODE_KEY_MATERIAL_INVALID, message).with_context("transfer_format", format.code());
}
fn transfer_io_error(operation: &'static str, source: std::io::Error) -> ksp_core_lib::Error {
return ksp_core_lib::Error::new(crate::ERROR_CODE_IO_FAILED, "Wallet transfer filesystem I/O failed")
.with_context("operation", operation)
.with_source(source);
}
fn transfer_atomic_error(operation: &'static str, message: &'static str) -> ksp_core_lib::Error {
return ksp_core_lib::Error::new(crate::ERROR_CODE_ATOMIC_PERSISTENCE_FAILED, message).with_context("operation", operation);
}
fn transfer_atomic_io_error(operation: &'static str, source: std::io::Error) -> ksp_core_lib::Error {
return ksp_core_lib::Error::new(crate::ERROR_CODE_ATOMIC_PERSISTENCE_FAILED, "Atomic Wallet transfer export failed")
.with_context("operation", operation)
.with_source(source);
}
fn blocking_transfer_error(operation: &'static str, source: tokio::task::JoinError) -> ksp_core_lib::Error {
return ksp_core_lib::Error::new(crate::ERROR_CODE_IO_FAILED, "Wallet transfer filesystem task failed")
.with_context("operation", operation)
.with_source(source);
}
#[cfg(test)]
#[path = "../unit_tests/transfer.rs"]
mod tests;