v0.2.5-pre.003

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

@@ -1,7 +1,70 @@
 // file: crates/ksp-wallet-lib/src/constants.rs
-// version: 1
+// version: 3
 
 //! Wallet-owned constants.
 
+/// Exact magic string required by every native `.kspwallet` document.
+pub const KSPWALLET_MAGIC: &str = "KSPWALLET";
+/// Native Wallet format version implemented by the V1 codec.
+pub const KSPWALLET_FORMAT_VERSION_V1: u32 = 1;
+/// Maximum accepted `.kspwallet` document size before JSON parsing.
+pub const KSPWALLET_MAX_FILE_BYTES: usize = 1024 * 1024;
+/// Maximum protected alias size in UTF-8 bytes for metadata V1.
+pub const KSPWALLET_V1_MAX_ALIAS_BYTES: usize = 256;
+/// Maximum number of protected notes in metadata V1.
+pub const KSPWALLET_V1_MAX_NOTES: usize = 64;
+/// Maximum protected note text size in UTF-8 bytes for metadata V1.
+pub const KSPWALLET_V1_MAX_NOTE_TEXT_BYTES: usize = 8 * 1024;
+/// Maximum metadata plaintext size before V1 encryption.
+pub const KSPWALLET_V1_MAX_METADATA_PLAINTEXT_BYTES: usize = 64 * 1024;
+/// Maximum password size in exact UTF-8 input bytes.
+pub const KSPWALLET_V1_MAX_PASSWORD_BYTES: usize = 1024;
+/// Byte length of every V1 key-slot identifier.
+pub const KSPWALLET_V1_SLOT_ID_BYTES: usize = 16;
+/// Byte length of an Ed25519 public key used as Wallet format authority.
+pub const KSPWALLET_V1_ED25519_PUBLIC_KEY_BYTES: usize = 32;
+/// Byte length of an Ed25519 detached state signature.
+pub const KSPWALLET_V1_ED25519_SIGNATURE_BYTES: usize = 64;
+/// Byte length of an XChaCha20-Poly1305 nonce.
+pub const KSPWALLET_V1_XCHACHA_NONCE_BYTES: usize = 24;
+/// Byte length of the Poly1305 authentication tag appended to each ciphertext.
+pub const KSPWALLET_V1_AEAD_TAG_BYTES: usize = 16;
+/// Argon2 version serialized by V1 key slots.
+pub const KSPWALLET_V1_ARGON2_VERSION: u32 = 19;
+/// Minimum accepted Argon2 salt size in bytes.
+pub const KSPWALLET_V1_MIN_KDF_SALT_BYTES: usize = 16;
+/// Maximum accepted Argon2 salt size in bytes.
+pub const KSPWALLET_V1_MAX_KDF_SALT_BYTES: usize = 64;
+/// Structural V1 ceiling for serialized Argon2 memory cost; creation defaults are benchmarked separately.
+pub const KSPWALLET_V1_MAX_ARGON2_MEMORY_KIB: u32 = 1024 * 1024;
+/// Structural V1 ceiling for serialized Argon2 iteration cost; creation defaults are benchmarked separately.
+pub const KSPWALLET_V1_MAX_ARGON2_ITERATIONS: u32 = 64;
+/// Structural V1 ceiling for serialized Argon2 parallelism; creation defaults are benchmarked separately.
+pub const KSPWALLET_V1_MAX_ARGON2_PARALLELISM: u32 = 64;
+/// Maximum number of key slots understood by format V1: exactly one OWNER plus optional VIEW.
+pub const KSPWALLET_V1_MAX_KEY_SLOTS: usize = 2;
+/// Maximum ciphertext size of one wrapped capability payload.
+pub const KSPWALLET_V1_MAX_KEY_WRAP_CIPHERTEXT_BYTES: usize = 4096;
+/// Maximum OWNER-control ciphertext size accepted by envelope V1.
+pub const KSPWALLET_V1_MAX_OWNER_CONTROL_CIPHERTEXT_BYTES: usize = 4096;
+/// Maximum metadata ciphertext size, including the AEAD tag over the bounded 64-KiB plaintext.
+pub const KSPWALLET_V1_MAX_METADATA_CIPHERTEXT_BYTES: usize = KSPWALLET_V1_MAX_METADATA_PLAINTEXT_BYTES + KSPWALLET_V1_AEAD_TAG_BYTES;
+/// Maximum OWNER-only secret ciphertext size accepted by envelope V1.
+pub const KSPWALLET_V1_MAX_SECRET_CIPHERTEXT_BYTES: usize = 4096;
+/// Initial protected payload version used independently by control, metadata and secret compartments.
+pub const KSPWALLET_V1_INITIAL_PAYLOAD_VERSION: u32 = 1;
+/// Domain separator for the OWNER state-signature transcript.
+pub const KSPWALLET_V1_STATE_TRANSCRIPT_DOMAIN: &[u8] = b"KSPWALLET-V1-STATE";
+/// Domain separator for OWNER key-slot wrapping AAD.
+pub const KSPWALLET_V1_OWNER_SLOT_AAD_DOMAIN: &[u8] = b"KSPWALLET-V1-AAD-OWNER-SLOT";
+/// Domain separator for VIEW key-slot wrapping AAD.
+pub const KSPWALLET_V1_VIEW_SLOT_AAD_DOMAIN: &[u8] = b"KSPWALLET-V1-AAD-VIEW-SLOT";
+/// Domain separator for OWNER-control compartment AAD.
+pub const KSPWALLET_V1_OWNER_CONTROL_AAD_DOMAIN: &[u8] = b"KSPWALLET-V1-AAD-OWNER-CONTROL";
+/// Domain separator for metadata compartment AAD.
+pub const KSPWALLET_V1_METADATA_AAD_DOMAIN: &[u8] = b"KSPWALLET-V1-AAD-METADATA";
+/// Domain separator for OWNER-only secret compartment AAD.
+pub const KSPWALLET_V1_SECRET_AAD_DOMAIN: &[u8] = b"KSPWALLET-V1-AAD-SECRET";
+
 /// Owning tracing target for events emitted by the Wallet crate.
 pub(crate) const TRACING_TARGET: &str = "ksp-wallet-lib";

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;

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

@@ -0,0 +1,131 @@
+// file: crates/ksp-wallet-lib/src/transcript.rs
+// version: 1
+
+//! Deterministic `.kspwallet` V1 state-transcript and AEAD-AAD encoding.
+
+const TAG_MAGIC: u16 = 0x0001;
+const TAG_FORMAT_VERSION: u16 = 0x0002;
+const TAG_OWNER_AUTH_PUBLIC_KEY: u16 = 0x0003;
+const TAG_VIEW_ENABLED: u16 = 0x0010;
+const TAG_VIEW_ROLE: u16 = 0x0011;
+const TAG_VIEW_SLOT_ID: u16 = 0x0012;
+const TAG_SLOT_ID: u16 = 0x0100;
+const TAG_SLOT_ROLE: u16 = 0x0101;
+const TAG_KDF_ALGORITHM: u16 = 0x0102;
+const TAG_KDF_VERSION: u16 = 0x0103;
+const TAG_KDF_MEMORY_KIB: u16 = 0x0104;
+const TAG_KDF_ITERATIONS: u16 = 0x0105;
+const TAG_KDF_PARALLELISM: u16 = 0x0106;
+const TAG_KDF_SALT: u16 = 0x0107;
+const TAG_WRAP_ALGORITHM: u16 = 0x0108;
+const TAG_WRAP_NONCE: u16 = 0x0109;
+const TAG_WRAP_CIPHERTEXT: u16 = 0x010A;
+const TAG_COMPARTMENT_KIND: u16 = 0x0200;
+const TAG_COMPARTMENT_VERSION: u16 = 0x0201;
+const TAG_COMPARTMENT_ALGORITHM: u16 = 0x0202;
+const TAG_COMPARTMENT_NONCE: u16 = 0x0203;
+const TAG_COMPARTMENT_CIPHERTEXT: u16 = 0x0204;
+const TAG_STATE_SIGNATURE_ALGORITHM: u16 = 0x0500;
+
+/// Builds the normative OWNER state-signature transcript for one validated V1 envelope.
+pub(crate) fn state_transcript(envelope: &crate::KspWalletEnvelopeV1) -> std::vec::Vec<u8> {
+    let mut output = start(crate::KSPWALLET_V1_STATE_TRANSCRIPT_DOMAIN);
+    push_common(&mut output, envelope);
+    push_bool(&mut output, TAG_VIEW_ENABLED, envelope.view_descriptor().enabled());
+    push_bytes(&mut output, TAG_VIEW_ROLE, crate::WalletKeySlotRoleV1::View.as_str().as_bytes());
+    match envelope.view_descriptor().slot_id() {
+        std::option::Option::Some(slot_id) => push_bytes(&mut output, TAG_VIEW_SLOT_ID, slot_id),
+        std::option::Option::None => push_bytes(&mut output, TAG_VIEW_SLOT_ID, &[]),
+    }
+
+    push_slot(&mut output, envelope.owner_slot(), true);
+    push_compartment(&mut output, envelope.owner_control(), true);
+    push_compartment(&mut output, envelope.metadata(), true);
+    push_compartment(&mut output, envelope.secret(), true);
+    push_bytes(&mut output, TAG_STATE_SIGNATURE_ALGORITHM, envelope.state_signature().algorithm().as_str().as_bytes());
+    return output;
+}
+
+/// Builds the normative wrapping AAD for one validated OWNER or VIEW key slot.
+pub(crate) fn slot_aad(envelope: &crate::KspWalletEnvelopeV1, slot: &crate::WalletKeySlotV1) -> std::vec::Vec<u8> {
+    let domain = match slot.role() {
+        crate::WalletKeySlotRoleV1::Owner => crate::KSPWALLET_V1_OWNER_SLOT_AAD_DOMAIN,
+        crate::WalletKeySlotRoleV1::View => crate::KSPWALLET_V1_VIEW_SLOT_AAD_DOMAIN,
+    };
+    let mut output = start(domain);
+    push_common(&mut output, envelope);
+    push_slot(&mut output, slot, false);
+    return output;
+}
+
+/// Builds the normative AEAD AAD for one validated encrypted compartment.
+pub(crate) fn compartment_aad(envelope: &crate::KspWalletEnvelopeV1, compartment: &crate::WalletEncryptedCompartmentV1) -> std::vec::Vec<u8> {
+    let domain = match compartment.kind() {
+        crate::WalletCompartmentKindV1::OwnerControl => crate::KSPWALLET_V1_OWNER_CONTROL_AAD_DOMAIN,
+        crate::WalletCompartmentKindV1::Metadata => crate::KSPWALLET_V1_METADATA_AAD_DOMAIN,
+        crate::WalletCompartmentKindV1::Secret => crate::KSPWALLET_V1_SECRET_AAD_DOMAIN,
+    };
+    let mut output = start(domain);
+    push_common(&mut output, envelope);
+    push_compartment(&mut output, compartment, false);
+    return output;
+}
+
+fn start(domain: &[u8]) -> std::vec::Vec<u8> {
+    let mut output = std::vec::Vec::with_capacity(512);
+    output.extend_from_slice(domain);
+    output.push(0);
+    return output;
+}
+
+fn push_common(output: &mut std::vec::Vec<u8>, envelope: &crate::KspWalletEnvelopeV1) {
+    push_bytes(output, TAG_MAGIC, crate::KSPWALLET_MAGIC.as_bytes());
+    push_u32(output, TAG_FORMAT_VERSION, envelope.format_version());
+    push_bytes(output, TAG_OWNER_AUTH_PUBLIC_KEY, envelope.owner_auth_public_key());
+}
+
+fn push_slot(output: &mut std::vec::Vec<u8>, slot: &crate::WalletKeySlotV1, include_wrap_payload: bool) {
+    push_bytes(output, TAG_SLOT_ID, slot.slot_id());
+    push_bytes(output, TAG_SLOT_ROLE, slot.role().as_str().as_bytes());
+    push_bytes(output, TAG_KDF_ALGORITHM, slot.kdf().algorithm().as_str().as_bytes());
+    push_u32(output, TAG_KDF_VERSION, slot.kdf().version());
+    push_u32(output, TAG_KDF_MEMORY_KIB, slot.kdf().memory_kib());
+    push_u32(output, TAG_KDF_ITERATIONS, slot.kdf().iterations());
+    push_u32(output, TAG_KDF_PARALLELISM, slot.kdf().parallelism());
+    push_bytes(output, TAG_KDF_SALT, slot.kdf().salt());
+    push_bytes(output, TAG_WRAP_ALGORITHM, slot.wrap().algorithm().as_str().as_bytes());
+    if include_wrap_payload {
+        push_bytes(output, TAG_WRAP_NONCE, slot.wrap().nonce());
+        push_bytes(output, TAG_WRAP_CIPHERTEXT, slot.wrap().ciphertext());
+    }
+}
+
+fn push_compartment(output: &mut std::vec::Vec<u8>, compartment: &crate::WalletEncryptedCompartmentV1, include_ciphertext: bool) {
+    push_bytes(output, TAG_COMPARTMENT_KIND, compartment.kind().as_str().as_bytes());
+    push_u32(output, TAG_COMPARTMENT_VERSION, compartment.payload_version());
+    push_bytes(output, TAG_COMPARTMENT_ALGORITHM, compartment.algorithm().as_str().as_bytes());
+    if include_ciphertext {
+        push_bytes(output, TAG_COMPARTMENT_NONCE, compartment.nonce());
+        push_bytes(output, TAG_COMPARTMENT_CIPHERTEXT, compartment.ciphertext());
+    }
+}
+
+fn push_bool(output: &mut std::vec::Vec<u8>, tag: u16, value: bool) {
+    let byte = if value { 1_u8 } else { 0_u8 };
+    push_bytes(output, tag, &[byte]);
+}
+
+fn push_u32(output: &mut std::vec::Vec<u8>, tag: u16, value: u32) {
+    push_bytes(output, tag, value.to_be_bytes().as_slice());
+}
+
+fn push_bytes(output: &mut std::vec::Vec<u8>, tag: u16, value: &[u8]) {
+    output.extend_from_slice(tag.to_be_bytes().as_slice());
+    let length = value.len() as u64;
+    output.extend_from_slice(length.to_be_bytes().as_slice());
+    output.extend_from_slice(value);
+}
+
+#[cfg(test)]
+#[path = "../unit_tests/transcript.rs"]
+mod tests;