v0.2.6-pre.016

crates/ksp-wallet-lib/src/lib.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-wallet-lib/src/lib.rs
-// version: 12
+// version: 13
 
 #![warn(missing_docs)]
 #![deny(unreachable_pub)]
@@ -16,7 +16,8 @@
 //! replacement. `0.2.5-pre.008` adds bounded Solana CLI JSON and canonical full-keypair Base58 import/export adapters with safe inspection and no-clobber
 //! native import/export publication. `0.2.5-pre.009` adds adversarial security/compliance canaries and records the final dependency/interop audit before
 //! documentation closure. `0.2.6-pre.015` defines the strict binary `.kspwallet` V2 wire and its bounded canonical codec without yet changing the public
-//! persistence default or Wallet Desk dispatch. Public keys are consumed exclusively through the [`ksp_core_lib::Pubkey`] re-export owned by KSP Core, and behavioral
+//! persistence default or Wallet Desk dispatch. `0.2.6-pre.016` adds complete V2 create/open/administration, stable version-neutral dispatch, explicit V1/V2
+//! APIs and moves the default native creation/import format to V2 without coupling that default to the latest supported version. Public keys are consumed exclusively through the [`ksp_core_lib::Pubkey`] re-export owned by KSP Core, and behavioral
 //! observability uses only
 //! `ksp-logging-lib` with the explicit crate target defined in `src/constants.rs`.
 
@@ -24,16 +25,19 @@ mod capability;
 mod constants;
 mod crypto;
 mod error;
+mod format;
 mod metadata;
 mod owner;
 mod password;
 mod payload;
 mod persistence;
+mod runtime;
 mod transcript;
 mod transcript_v2;
 mod transfer;
 mod view;
 mod wallet;
+mod wallet_v2;
 mod wire;
 mod wire_v2;
 
@@ -131,6 +135,14 @@ pub use self::constants::KSPWALLET_V1_XCHACHA_NONCE_BYTES;
 pub use self::constants::KSPWALLET_V2_AEAD_TAG_BYTES;
 /// Argon2 version serialized by `.kspwallet` V2 key slots.
 pub use self::constants::KSPWALLET_V2_ARGON2_VERSION;
+/// Default Argon2id iteration count for newly created V2 slots.
+pub use self::constants::KSPWALLET_V2_DEFAULT_ARGON2_ITERATIONS;
+/// Default Argon2id memory cost for newly created V2 slots.
+pub use self::constants::KSPWALLET_V2_DEFAULT_ARGON2_MEMORY_KIB;
+/// Default Argon2id parallelism for newly created V2 slots.
+pub use self::constants::KSPWALLET_V2_DEFAULT_ARGON2_PARALLELISM;
+/// Default KDF salt size generated for newly created V2 slots.
+pub use self::constants::KSPWALLET_V2_DEFAULT_KDF_SALT_BYTES;
 /// Byte length of the V2 Ed25519 format-authority public key.
 pub use self::constants::KSPWALLET_V2_ED25519_PUBLIC_KEY_BYTES;
 /// Byte length of the V2 Ed25519 detached state signature.
@@ -163,6 +175,8 @@ pub use self::constants::KSPWALLET_V2_OWNER_CONTROL_AAD_DOMAIN;
 pub use self::constants::KSPWALLET_V2_OWNER_SLOT_AAD_DOMAIN;
 /// Domain separator for V2 OWNER-only secret compartment AEAD AAD.
 pub use self::constants::KSPWALLET_V2_SECRET_AAD_DOMAIN;
+/// Exact Solana keypair plaintext size retained by the initial V2 secret payload profile.
+pub use self::constants::KSPWALLET_V2_SECRET_PLAINTEXT_BYTES;
 /// Byte length of every V2 key-slot identifier.
 pub use self::constants::KSPWALLET_V2_SLOT_ID_BYTES;
 /// Domain separator for the V2 OWNER state-signature transcript.
@@ -205,9 +219,27 @@ pub use self::error::ERROR_CODE_STATE_CONFLICT;
 pub use self::error::ERROR_CODE_TRANSFER_FORMAT_UNSUPPORTED;
 /// Error code used when a VIEW unlock attempt fails without exposing a finer cryptographic oracle.
 pub use self::error::ERROR_CODE_VIEW_UNLOCK_FAILED;
+/// Default native Wallet format selected by non-versioned create/import APIs.
+pub use self::format::DEFAULT_WALLET_FORMAT;
+/// Highest native Wallet format supported by this release.
+pub use self::format::LATEST_SUPPORTED_WALLET_FORMAT;
+/// Explicit native Wallet wire-format selector.
+pub use self::format::WalletFormat;
+/// Creates a new in-memory native Wallet using the explicit default format.
+pub use self::format::create_wallet;
+/// Detects V1 JSON versus V2 binary framing before strict parser dispatch.
+pub use self::format::detect_wallet_format;
+/// Inspects any supported in-memory native Wallet document.
+pub use self::format::inspect_locked_wallet;
+/// Opens OWNER from any supported in-memory native Wallet document.
+pub use self::format::open_wallet_owner;
+/// Opens VIEW from any supported in-memory native Wallet document.
+pub use self::format::open_wallet_view;
 /// Minimal non-secret information available while a native Wallet remains locked.
 pub use self::metadata::LockedWalletInfo;
-/// Protected initial metadata supplied to native Wallet creation.
+/// Protected initial metadata supplied to version-neutral native Wallet creation.
+pub type WalletCreateMetadata = self::metadata::WalletCreateMetadataV1;
+/// Protected initial metadata payload profile retained for explicit V1 compatibility.
 pub use self::metadata::WalletCreateMetadataV1;
 /// Safe metadata projection produced after VIEW or OWNER authorization.
 pub use self::metadata::WalletInfo;
@@ -219,22 +251,46 @@ pub use self::owner::WalletOwner;
 pub use self::password::OwnerPassword;
 /// Owned VIEW password material with redacted diagnostics and drop-time zeroization.
 pub use self::password::ViewPassword;
+/// Creates and no-clobber persists a native Wallet using the explicit default format.
+pub use self::persistence::create_wallet_file;
 /// Creates and no-clobber persists a new native `.kspwallet` V1 file.
 pub use self::persistence::create_wallet_file_v1;
+/// Creates and no-clobber persists a new native `.kspwallet` V2 binary file.
+pub use self::persistence::create_wallet_file_v2;
+/// Reads and verifies a locked native Wallet using V1/V2 auto-detection.
+pub use self::persistence::inspect_locked_wallet_file;
 /// Reads and verifies a locked native `.kspwallet` V1 file.
 pub use self::persistence::inspect_locked_wallet_file_v1;
+/// Reads and verifies a locked native `.kspwallet` V2 binary file.
+pub use self::persistence::inspect_locked_wallet_file_v2;
+/// Opens a native Wallet with OWNER capability using V1/V2 auto-detection.
+pub use self::persistence::open_wallet_owner_file;
 /// Opens a native `.kspwallet` V1 file with OWNER capability.
 pub use self::persistence::open_wallet_owner_file_v1;
+/// Opens a native `.kspwallet` V2 binary file with OWNER capability.
+pub use self::persistence::open_wallet_owner_file_v2;
+/// Opens a native Wallet with VIEW capability using V1/V2 auto-detection.
+pub use self::persistence::open_wallet_view_file;
 /// Opens a native `.kspwallet` V1 file with VIEW capability.
 pub use self::persistence::open_wallet_view_file_v1;
+/// Opens a native `.kspwallet` V2 binary file with VIEW capability.
+pub use self::persistence::open_wallet_view_file_v2;
 /// Explicit secret-transfer format supported by Wallet.
 pub use self::transfer::WalletTransferFormat;
 /// Safe public identity projection of one validated secret-transfer source.
 pub use self::transfer::WalletTransferInspection;
+/// Imports one in-memory transfer payload into a new no-clobber native Wallet using the explicit default format.
+pub use self::transfer::import_wallet_transfer;
+/// Imports one bounded external transfer file into a new no-clobber native Wallet using the explicit default format.
+pub use self::transfer::import_wallet_transfer_file;
 /// Imports one bounded external transfer file into a new no-clobber native Wallet V1.
 pub use self::transfer::import_wallet_transfer_file_v1;
+/// Imports one bounded external transfer file into a new no-clobber native Wallet V2.
+pub use self::transfer::import_wallet_transfer_file_v2;
 /// Imports one in-memory transfer payload into a new no-clobber native Wallet V1.
 pub use self::transfer::import_wallet_transfer_v1;
+/// Imports one in-memory transfer payload into a new no-clobber native Wallet V2.
+pub use self::transfer::import_wallet_transfer_v2;
 /// Validates one in-memory transfer payload and exposes only its derived public identity.
 pub use self::transfer::inspect_wallet_transfer;
 /// Validates one bounded external transfer file and exposes only its derived public identity.
@@ -249,6 +305,14 @@ pub use self::wallet::inspect_locked_wallet_v1;
 pub use self::wallet::open_wallet_owner_v1;
 /// Opens the VIEW capability from a native Wallet V1 document.
 pub use self::wallet::open_wallet_view_v1;
+/// Creates a new in-memory native Wallet V2.
+pub use self::wallet_v2::create_wallet_v2;
+/// Parses and verifies locked native Wallet V2 state without unlocking protected metadata.
+pub use self::wallet_v2::inspect_locked_wallet_v2;
+/// Opens the OWNER capability from a native Wallet V2 document.
+pub use self::wallet_v2::open_wallet_owner_v2;
+/// Opens the VIEW capability from a native Wallet V2 document.
+pub use self::wallet_v2::open_wallet_view_v2;
 /// Strict semantic representation of one parsed native `.kspwallet` V1 envelope.
 pub use self::wire::KspWalletEnvelopeV1;
 /// Authenticated-encryption algorithm fixed by native Wallet V1.
@@ -308,6 +372,8 @@ pub(crate) use self::crypto::SecretKeyV1;
 pub(crate) use self::crypto::decrypt_bytes;
 /// Derives one V1 password wrapping key from serialized Argon2id parameters.
 pub(crate) use self::crypto::derive_password_key;
+/// Derives one V2 password wrapping key from serialized Argon2id parameters.
+pub(crate) use self::crypto::derive_password_key_v2;
 /// Encrypts bounded plaintext bytes with XChaCha20-Poly1305 and caller-provided domain-separated AAD.
 pub(crate) use self::crypto::encrypt_bytes;
 /// Generates a fresh fixed-size byte array from the operating-system CSPRNG.
@@ -328,7 +394,9 @@ pub(crate) use self::payload::decode_owner_control_payload;
 pub(crate) use self::payload::encode_initial_metadata_payload;
 /// Encodes owner control payload.
 pub(crate) use self::payload::encode_owner_control_payload;
-/// Internal no-clobber native persistence path shared by transfer adapters.
+/// Internal no-clobber native persistence path shared by version-neutral transfer adapters.
+pub(crate) use self::persistence::persist_new_wallet_content;
+/// Internal V1 no-clobber native persistence path retained for explicit compatibility adapters.
 pub(crate) use self::persistence::persist_new_wallet_content_v1;
 /// Persists new wallet fault before publish.
 #[cfg(test)]
@@ -341,9 +409,15 @@ pub(crate) use self::persistence::persist_new_wallet_for_test;
 pub(crate) use self::persistence::replace_wallet_fault_before_publish;
 /// Replaces wallet file v1.
 pub(crate) use self::persistence::replace_wallet_file_v1;
+/// Replaces wallet file v2.
+pub(crate) use self::persistence::replace_wallet_file_v2;
 /// Replaces wallet for test.
 #[cfg(test)]
 pub(crate) use self::persistence::replace_wallet_for_test;
+/// Version-neutral OWNER runtime state shared by public Wallet handles.
+pub(crate) use self::runtime::OwnerState;
+/// Version-neutral VIEW runtime state shared by public Wallet handles.
+pub(crate) use self::runtime::ViewState;
 /// Internal deterministic compartment-AAD codec shared by Wallet crypto layers.
 pub(crate) use self::transcript::compartment_aad;
 /// Internal deterministic key-slot-AAD codec shared by Wallet crypto layers.
@@ -357,12 +431,20 @@ pub(crate) use self::transcript_v2::slot_aad_v2;
 /// Internal deterministic V2 OWNER-state transcript codec shared by Wallet crypto layers.
 pub(crate) use self::transcript_v2::state_transcript_v2;
 /// Internal no-clobber transfer-file writer used only by OWNER export.
-pub(crate) use self::transfer::write_wallet_transfer_file_v1;
+pub(crate) use self::transfer::write_wallet_transfer_file;
 /// Crate-internal `OwnerStateV1` state shared across the owning crate.
 pub(crate) use self::wallet::OwnerStateV1;
 /// Crate-internal `ViewStateV1` state shared across the owning crate.
 pub(crate) use self::wallet::ViewStateV1;
-/// Internal imported-keypair creation path shared by transfer adapters.
+/// Internal imported-keypair V1 creation path shared by transfer adapters.
 pub(crate) use self::wallet::create_wallet_v1_from_keypair;
-/// Verifies state signature.
+/// Verifies V1 state signature.
 pub(crate) use self::wallet::verify_state_signature;
+/// Crate-internal `OwnerStateV2` state shared across the owning crate.
+pub(crate) use self::wallet_v2::OwnerStateV2;
+/// Crate-internal `ViewStateV2` state shared across the owning crate.
+pub(crate) use self::wallet_v2::ViewStateV2;
+/// Internal imported-keypair V2 creation path shared by transfer adapters.
+pub(crate) use self::wallet_v2::create_wallet_v2_from_keypair;
+/// Verifies V2 state signature.
+pub(crate) use self::wallet_v2::verify_state_signature_v2;