v0.2.5-pre.003

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

@@ -1,5 +1,5 @@
 // file: crates/ksp-wallet-lib/src/lib.rs
-// version: 1
+// version: 3
 #![warn(missing_docs)]
 #![deny(unreachable_pub)]
 #![forbid(unsafe_code)]
@@ -7,9 +7,10 @@
 //! Autonomous KSP Wallet foundation.
 //!
 //! `ksp-wallet-lib` owns the native `.kspwallet` domain, VIEW/OWNER capability model, protected metadata projection, password-secret wrappers and Wallet
-//! error contract. The `0.2.5-pre.002` foundation deliberately contains no file codec, KDF/AEAD implementation, Solana secret material, persistence,
-//! network access, Config integration or execution policy. 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`.
+//! error contract. `0.2.5-pre.003` additionally freezes the strict V1 JSON envelope, canonical Base64url decoding, structural limits and deterministic
+//! state-transcript/AEAD-AAD byte codecs. It still performs no KDF, encryption, decryption, state-signature verification, Solana signing or filesystem
+//! persistence. 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`.
 
 mod capability;
 mod constants;
@@ -17,10 +18,74 @@ mod error;
 mod metadata;
 mod owner;
 mod password;
+mod transcript;
 mod view;
+mod wire;
 
 /// Authorized capability represented by an unlocked Wallet handle.
 pub use self::capability::WalletCapability;
+/// Native `.kspwallet` V1 format version.
+pub use self::constants::KSPWALLET_FORMAT_VERSION_V1;
+/// Exact magic string required by every native `.kspwallet` document.
+pub use self::constants::KSPWALLET_MAGIC;
+/// Maximum accepted `.kspwallet` document size before parsing.
+pub use self::constants::KSPWALLET_MAX_FILE_BYTES;
+/// Byte length of the AEAD authentication tag appended to V1 ciphertexts.
+pub use self::constants::KSPWALLET_V1_AEAD_TAG_BYTES;
+/// Argon2 version serialized by `.kspwallet` V1 key slots.
+pub use self::constants::KSPWALLET_V1_ARGON2_VERSION;
+/// Byte length of the Ed25519 format-authority public key.
+pub use self::constants::KSPWALLET_V1_ED25519_PUBLIC_KEY_BYTES;
+/// Byte length of the Ed25519 detached state signature.
+pub use self::constants::KSPWALLET_V1_ED25519_SIGNATURE_BYTES;
+/// Initial per-compartment protected payload version.
+pub use self::constants::KSPWALLET_V1_INITIAL_PAYLOAD_VERSION;
+/// Maximum alias size in protected metadata V1.
+pub use self::constants::KSPWALLET_V1_MAX_ALIAS_BYTES;
+/// Maximum structural Argon2 iteration count accepted by the V1 parser.
+pub use self::constants::KSPWALLET_V1_MAX_ARGON2_ITERATIONS;
+/// Maximum structural Argon2 memory cost accepted by the V1 parser.
+pub use self::constants::KSPWALLET_V1_MAX_ARGON2_MEMORY_KIB;
+/// Maximum structural Argon2 parallelism accepted by the V1 parser.
+pub use self::constants::KSPWALLET_V1_MAX_ARGON2_PARALLELISM;
+/// Maximum Argon2 salt size accepted by V1.
+pub use self::constants::KSPWALLET_V1_MAX_KDF_SALT_BYTES;
+/// Maximum number of OWNER/VIEW slots accepted by format V1.
+pub use self::constants::KSPWALLET_V1_MAX_KEY_SLOTS;
+/// Maximum wrapped-key ciphertext size accepted by V1.
+pub use self::constants::KSPWALLET_V1_MAX_KEY_WRAP_CIPHERTEXT_BYTES;
+/// Maximum protected metadata ciphertext size accepted by V1.
+pub use self::constants::KSPWALLET_V1_MAX_METADATA_CIPHERTEXT_BYTES;
+/// Maximum protected metadata plaintext size defined by V1.
+pub use self::constants::KSPWALLET_V1_MAX_METADATA_PLAINTEXT_BYTES;
+/// Maximum protected note text size defined by metadata V1.
+pub use self::constants::KSPWALLET_V1_MAX_NOTE_TEXT_BYTES;
+/// Maximum number of protected notes defined by metadata V1.
+pub use self::constants::KSPWALLET_V1_MAX_NOTES;
+/// Maximum OWNER-control ciphertext size accepted by V1.
+pub use self::constants::KSPWALLET_V1_MAX_OWNER_CONTROL_CIPHERTEXT_BYTES;
+/// Maximum password size in exact UTF-8 bytes defined by V1.
+pub use self::constants::KSPWALLET_V1_MAX_PASSWORD_BYTES;
+/// Maximum OWNER-only secret ciphertext size accepted by V1.
+pub use self::constants::KSPWALLET_V1_MAX_SECRET_CIPHERTEXT_BYTES;
+/// Domain separator for metadata-compartment AEAD AAD.
+pub use self::constants::KSPWALLET_V1_METADATA_AAD_DOMAIN;
+/// Minimum Argon2 salt size accepted by V1.
+pub use self::constants::KSPWALLET_V1_MIN_KDF_SALT_BYTES;
+/// Domain separator for OWNER-control compartment AEAD AAD.
+pub use self::constants::KSPWALLET_V1_OWNER_CONTROL_AAD_DOMAIN;
+/// Domain separator for OWNER key-slot wrapping AAD.
+pub use self::constants::KSPWALLET_V1_OWNER_SLOT_AAD_DOMAIN;
+/// Domain separator for OWNER-only secret compartment AEAD AAD.
+pub use self::constants::KSPWALLET_V1_SECRET_AAD_DOMAIN;
+/// Byte length of every V1 key-slot identifier.
+pub use self::constants::KSPWALLET_V1_SLOT_ID_BYTES;
+/// Domain separator for the OWNER state-signature transcript.
+pub use self::constants::KSPWALLET_V1_STATE_TRANSCRIPT_DOMAIN;
+/// Domain separator for VIEW key-slot wrapping AAD.
+pub use self::constants::KSPWALLET_V1_VIEW_SLOT_AAD_DOMAIN;
+/// Byte length of an XChaCha20-Poly1305 nonce.
+pub use self::constants::KSPWALLET_V1_XCHACHA_NONCE_BYTES;
 /// Error code used when an atomic Wallet persistence operation cannot publish a valid replacement.
 pub use self::error::ERROR_CODE_ATOMIC_PERSISTENCE_FAILED;
 /// Error code used when an authenticated Wallet structure cannot be verified.
@@ -61,6 +126,36 @@ pub use self::password::OwnerPassword;
 pub use self::password::ViewPassword;
 /// Authorized VIEW capability handle.
 pub use self::view::WalletView;
+/// Strict semantic representation of one parsed native `.kspwallet` V1 envelope.
+pub use self::wire::KspWalletEnvelopeV1;
+/// Authenticated-encryption algorithm fixed by native Wallet V1.
+pub use self::wire::WalletAeadAlgorithmV1;
+/// Protected compartment kind fixed by native Wallet V1.
+pub use self::wire::WalletCompartmentKindV1;
+/// One validated encrypted V1 compartment.
+pub use self::wire::WalletEncryptedCompartmentV1;
+/// Password KDF fixed by native Wallet V1.
+pub use self::wire::WalletKdfAlgorithmV1;
+/// Parsed Argon2id parameters from one V1 key slot.
+pub use self::wire::WalletKdfParametersV1;
+/// Role of one native V1 key slot.
+pub use self::wire::WalletKeySlotRoleV1;
+/// One validated OWNER or VIEW V1 key slot.
+pub use self::wire::WalletKeySlotV1;
+/// Parsed AEAD wrapped-key payload from one V1 key slot.
+pub use self::wire::WalletKeyWrapV1;
+/// State-signature algorithm fixed by native Wallet V1.
+pub use self::wire::WalletStateSignatureAlgorithmV1;
+/// Detached OWNER state signature embedded in a V1 envelope.
+pub use self::wire::WalletStateSignatureV1;
+/// OWNER-signed stable descriptor of the optional VIEW slot.
+pub use self::wire::WalletViewDescriptorV1;
 
 /// Wallet-owned tracing target used by the KSP logging facade.
 pub(crate) use self::constants::TRACING_TARGET;
+/// 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.
+pub(crate) use self::transcript::slot_aad;
+/// Internal deterministic OWNER-state transcript codec shared by Wallet crypto layers.
+pub(crate) use self::transcript::state_transcript;