v0.2.5-pre.005

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

@@ -0,0 +1,682 @@
+// file: crates/ksp-wallet-lib/src/wallet.rs
+// version: 2
+
+//! In-memory native Wallet V1 create/open orchestration.
+
+use ed25519_dalek::Signer as _;
+use zeroize::Zeroize as _;
+
+pub(crate) struct OwnerStateV1 {
+    envelope: crate::KspWalletEnvelopeV1,
+    owner_root: std::option::Option<crate::crypto::SecretKeyV1>,
+    metadata_key: std::option::Option<crate::crypto::SecretKeyV1>,
+    secret_key: std::option::Option<crate::crypto::SecretKeyV1>,
+    admin_signing_key: std::option::Option<ed25519_dalek::SigningKey>,
+    solana_keypair: std::option::Option<solana_keypair::Keypair>,
+}
+
+impl OwnerStateV1 {
+    pub(crate) fn new(
+        envelope: crate::KspWalletEnvelopeV1,
+        owner_root: crate::crypto::SecretKeyV1,
+        metadata_key: crate::crypto::SecretKeyV1,
+        secret_key: crate::crypto::SecretKeyV1,
+        admin_signing_key: ed25519_dalek::SigningKey,
+        solana_keypair: solana_keypair::Keypair,
+    ) -> Self {
+        return Self {
+            envelope,
+            owner_root: std::option::Option::Some(owner_root),
+            metadata_key: std::option::Option::Some(metadata_key),
+            secret_key: std::option::Option::Some(secret_key),
+            admin_signing_key: std::option::Option::Some(admin_signing_key),
+            solana_keypair: std::option::Option::Some(solana_keypair),
+        };
+    }
+
+    pub(crate) const fn envelope(&self) -> &crate::KspWalletEnvelopeV1 {
+        return &self.envelope;
+    }
+}
+
+impl std::ops::Drop for OwnerStateV1 {
+    fn drop(&mut self) {
+        let owner_root = self.owner_root.take();
+        let metadata_key = self.metadata_key.take();
+        let secret_key = self.secret_key.take();
+        let admin_signing_key = self.admin_signing_key.take();
+        let solana_keypair = self.solana_keypair.take();
+        drop(owner_root);
+        drop(metadata_key);
+        drop(secret_key);
+        drop(admin_signing_key);
+        drop(solana_keypair);
+    }
+}
+
+pub(crate) struct ViewStateV1 {
+    envelope: crate::KspWalletEnvelopeV1,
+    metadata_key: std::option::Option<crate::crypto::SecretKeyV1>,
+}
+
+impl ViewStateV1 {
+    pub(crate) fn new(envelope: crate::KspWalletEnvelopeV1, metadata_key: crate::crypto::SecretKeyV1) -> Self {
+        return Self { envelope, metadata_key: std::option::Option::Some(metadata_key) };
+    }
+
+    pub(crate) const fn envelope(&self) -> &crate::KspWalletEnvelopeV1 {
+        return &self.envelope;
+    }
+}
+
+impl std::ops::Drop for ViewStateV1 {
+    fn drop(&mut self) {
+        let metadata_key = self.metadata_key.take();
+        drop(metadata_key);
+    }
+}
+
+/// Creates a new in-memory native `.kspwallet` V1 with a fresh Solana keypair.
+///
+/// The optional VIEW password creates an independent VIEW slot. This function performs no filesystem I/O; use the OWNER handle's
+/// `to_json_bytes()` projection for the complete locked document until `pre.006` adds atomic persistence.
+pub async fn create_wallet_v1(
+    owner_password: crate::OwnerPassword,
+    view_password: std::option::Option<crate::ViewPassword>,
+    metadata: crate::WalletCreateMetadataV1,
+) -> ksp_core_lib::Result<crate::WalletOwner> {
+    let owner_root = match crate::crypto::SecretKeyV1::random() {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+    let metadata_key = match crate::crypto::SecretKeyV1::random() {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+    let secret_key = match crate::crypto::SecretKeyV1::random() {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+
+    let mut admin_secret = match crate::crypto::random_bytes::<{ crate::crypto::SECRET_KEY_BYTES }>() {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+    let admin_signing_key = ed25519_dalek::SigningKey::from_bytes(&admin_secret);
+    let owner_auth_public_key = admin_signing_key.verifying_key().to_bytes();
+
+    let mut solana_secret = match crate::crypto::random_bytes::<32>() {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => {
+            admin_secret.zeroize();
+            return std::result::Result::Err(error);
+        },
+    };
+    let solana_keypair = solana_keypair::Keypair::new_from_array(solana_secret);
+    solana_secret.zeroize();
+    let mut solana_keypair_bytes = solana_keypair.to_bytes();
+    let pubkey_result = pubkey_from_keypair_bytes(&solana_keypair_bytes);
+    let pubkey = match pubkey_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => {
+            admin_secret.zeroize();
+            solana_keypair_bytes.zeroize();
+            return std::result::Result::Err(error);
+        },
+    };
+
+    let metadata_encoded_result = crate::payload::encode_initial_metadata_payload(pubkey, metadata);
+    let (mut metadata_plaintext, metadata_payload) = match metadata_encoded_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => {
+            admin_secret.zeroize();
+            solana_keypair_bytes.zeroize();
+            return std::result::Result::Err(error);
+        },
+    };
+    let mut owner_control_plaintext = crate::payload::encode_owner_control_payload(&admin_secret, &metadata_key, &secret_key);
+    admin_secret.zeroize();
+
+    let owner_slot_id = match crate::crypto::random_bytes::<{ crate::KSPWALLET_V1_SLOT_ID_BYTES }>() {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => {
+            return cleanup_create_error(error, &mut owner_control_plaintext, &mut metadata_plaintext, &mut solana_keypair_bytes);
+        },
+    };
+    let owner_salt = match crate::crypto::random_bytes::<{ crate::KSPWALLET_V1_DEFAULT_KDF_SALT_BYTES }>() {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => {
+            return cleanup_create_error(error, &mut owner_control_plaintext, &mut metadata_plaintext, &mut solana_keypair_bytes);
+        },
+    };
+    let owner_kdf = crate::WalletKdfParametersV1::new_creation(owner_salt.to_vec());
+    let owner_wrap_nonce = match crate::crypto::random_nonce() {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => {
+            return cleanup_create_error(error, &mut owner_control_plaintext, &mut metadata_plaintext, &mut solana_keypair_bytes);
+        },
+    };
+
+    let view_material_result = prepare_view_creation(view_password);
+    let view_material = match view_material_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => {
+            return cleanup_create_error(error, &mut owner_control_plaintext, &mut metadata_plaintext, &mut solana_keypair_bytes);
+        },
+    };
+
+    let owner_control_nonce = match crate::crypto::random_nonce() {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => {
+            return cleanup_create_error(error, &mut owner_control_plaintext, &mut metadata_plaintext, &mut solana_keypair_bytes);
+        },
+    };
+    let metadata_nonce = match crate::crypto::random_nonce() {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => {
+            return cleanup_create_error(error, &mut owner_control_plaintext, &mut metadata_plaintext, &mut solana_keypair_bytes);
+        },
+    };
+    let secret_nonce = match crate::crypto::random_nonce() {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => {
+            return cleanup_create_error(error, &mut owner_control_plaintext, &mut metadata_plaintext, &mut solana_keypair_bytes);
+        },
+    };
+
+    let provisional = provisional_envelope(
+        owner_auth_public_key,
+        owner_slot_id,
+        owner_kdf.clone(),
+        owner_wrap_nonce,
+        view_material.as_ref(),
+        owner_control_nonce,
+        metadata_nonce,
+        secret_nonce,
+    );
+
+    let owner_derived_result = derive_owner_password_key_async(owner_password, owner_kdf.clone()).await;
+    let owner_derived = match owner_derived_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => {
+            return cleanup_create_error(error, &mut owner_control_plaintext, &mut metadata_plaintext, &mut solana_keypair_bytes);
+        },
+    };
+    let owner_wrapped_result = crate::crypto::wrap_key(&owner_derived, &owner_root, &owner_wrap_nonce, provisional.owner_slot_aad().as_slice());
+    let owner_wrapped = match owner_wrapped_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => {
+            return cleanup_create_error(error, &mut owner_control_plaintext, &mut metadata_plaintext, &mut solana_keypair_bytes);
+        },
+    };
+
+    let view_slot_result = seal_view_slot(&provisional, view_material, &metadata_key).await;
+    let view_slot = match view_slot_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => {
+            return cleanup_create_error(error, &mut owner_control_plaintext, &mut metadata_plaintext, &mut solana_keypair_bytes);
+        },
+    };
+
+    let owner_control_ciphertext_result = crate::crypto::encrypt_bytes(
+        &owner_root,
+        &owner_control_nonce,
+        provisional.compartment_aad(crate::WalletCompartmentKindV1::OwnerControl).as_slice(),
+        owner_control_plaintext.as_slice(),
+    );
+    let owner_control_ciphertext = match owner_control_ciphertext_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => {
+            return cleanup_create_error(error, &mut owner_control_plaintext, &mut metadata_plaintext, &mut solana_keypair_bytes);
+        },
+    };
+    owner_control_plaintext.zeroize();
+
+    let metadata_ciphertext_result = crate::crypto::encrypt_bytes(
+        &metadata_key,
+        &metadata_nonce,
+        provisional.compartment_aad(crate::WalletCompartmentKindV1::Metadata).as_slice(),
+        metadata_plaintext.as_slice(),
+    );
+    let metadata_ciphertext = match metadata_ciphertext_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => {
+            return cleanup_create_error(error, &mut owner_control_plaintext, &mut metadata_plaintext, &mut solana_keypair_bytes);
+        },
+    };
+    metadata_plaintext.zeroize();
+
+    let secret_ciphertext_result = crate::crypto::encrypt_bytes(
+        &secret_key,
+        &secret_nonce,
+        provisional.compartment_aad(crate::WalletCompartmentKindV1::Secret).as_slice(),
+        solana_keypair_bytes.as_slice(),
+    );
+    let secret_ciphertext = match secret_ciphertext_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => {
+            return cleanup_create_error(error, &mut owner_control_plaintext, &mut metadata_plaintext, &mut solana_keypair_bytes);
+        },
+    };
+    solana_keypair_bytes.zeroize();
+
+    let owner_slot =
+        crate::WalletKeySlotV1::new(owner_slot_id, crate::WalletKeySlotRoleV1::Owner, owner_kdf, crate::WalletKeyWrapV1::new(owner_wrap_nonce, owner_wrapped));
+    let view_descriptor = match view_slot.as_ref() {
+        std::option::Option::Some(slot) => crate::WalletViewDescriptorV1::enabled(*slot.slot_id()),
+        std::option::Option::None => crate::WalletViewDescriptorV1::disabled(),
+    };
+    let owner_control = crate::WalletEncryptedCompartmentV1::new(crate::WalletCompartmentKindV1::OwnerControl, owner_control_nonce, owner_control_ciphertext);
+    let metadata_compartment = crate::WalletEncryptedCompartmentV1::new(crate::WalletCompartmentKindV1::Metadata, metadata_nonce, metadata_ciphertext);
+    let secret_compartment = crate::WalletEncryptedCompartmentV1::new(crate::WalletCompartmentKindV1::Secret, secret_nonce, secret_ciphertext);
+    let unsigned = crate::KspWalletEnvelopeV1::new_internal(
+        owner_auth_public_key,
+        view_descriptor,
+        owner_slot.clone(),
+        view_slot.clone(),
+        owner_control.clone(),
+        metadata_compartment.clone(),
+        secret_compartment.clone(),
+        crate::WalletStateSignatureV1::new([0_u8; crate::KSPWALLET_V1_ED25519_SIGNATURE_BYTES]),
+    );
+    let signature = admin_signing_key.sign(unsigned.state_transcript().as_slice()).to_bytes();
+    let envelope = crate::KspWalletEnvelopeV1::new_internal(
+        owner_auth_public_key,
+        view_descriptor,
+        owner_slot,
+        view_slot,
+        owner_control,
+        metadata_compartment,
+        secret_compartment,
+        crate::WalletStateSignatureV1::new(signature),
+    );
+    let verify_result = verify_state_signature(&envelope);
+    if let std::result::Result::Err(error) = verify_result {
+        return std::result::Result::Err(error);
+    }
+
+    let info = metadata_payload.into_info(crate::WalletCapability::Owner);
+    let state = OwnerStateV1::new(envelope, owner_root, metadata_key, secret_key, admin_signing_key, solana_keypair);
+    ksp_logging_lib::debug!(
+        target: crate::TRACING_TARGET,
+        operation = "wallet_create",
+        format_version = crate::KSPWALLET_FORMAT_VERSION_V1,
+        view_enabled = state.envelope().view_descriptor().enabled(),
+        "native wallet created in memory"
+    );
+    return std::result::Result::Ok(crate::WalletOwner::from_unlocked(info, state));
+}
+
+/// Opens the VIEW capability from a native `.kspwallet` V1 JSON document.
+pub async fn open_wallet_view_v1(source: &[u8], password: crate::ViewPassword) -> ksp_core_lib::Result<crate::WalletView> {
+    let envelope = match crate::KspWalletEnvelopeV1::parse_json(source) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+    let verify_result = verify_state_signature(&envelope);
+    if let std::result::Result::Err(error) = verify_result {
+        return std::result::Result::Err(error);
+    }
+    let view_slot = match envelope.view_slot() {
+        std::option::Option::Some(value) => value,
+        std::option::Option::None => return std::result::Result::Err(capability_error("Wallet VIEW capability is disabled")),
+    };
+    let derived_result = derive_view_password_key_async(password, view_slot.kdf().clone()).await;
+    let derived = match derived_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+    let aad = envelope.view_slot_aad();
+    let view_aad = match aad {
+        std::option::Option::Some(value) => value,
+        std::option::Option::None => return std::result::Result::Err(capability_error("Wallet VIEW capability is disabled")),
+    };
+    let metadata_key_result = crate::crypto::unwrap_key(&derived, view_slot.wrap().nonce(), view_aad.as_slice(), view_slot.wrap().ciphertext());
+    let metadata_key = match metadata_key_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return std::result::Result::Err(view_unlock_error()),
+    };
+    let metadata_plaintext_result = crate::crypto::decrypt_bytes(
+        &metadata_key,
+        envelope.metadata().nonce(),
+        envelope.compartment_aad(crate::WalletCompartmentKindV1::Metadata).as_slice(),
+        envelope.metadata().ciphertext(),
+    );
+    let mut metadata_plaintext = match metadata_plaintext_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return std::result::Result::Err(view_unlock_error()),
+    };
+    let metadata_payload_result = crate::payload::decode_metadata_payload(metadata_plaintext.as_slice());
+    metadata_plaintext.zeroize();
+    let metadata_payload = match metadata_payload_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+    let info = metadata_payload.into_info(crate::WalletCapability::View);
+    let state = ViewStateV1::new(envelope, metadata_key);
+    ksp_logging_lib::debug!(
+        target: crate::TRACING_TARGET,
+        operation = "wallet_open_view",
+        format_version = crate::KSPWALLET_FORMAT_VERSION_V1,
+        capability = "view",
+        "native wallet VIEW capability opened"
+    );
+    return std::result::Result::Ok(crate::WalletView::from_unlocked(info, state));
+}
+
+/// Opens the OWNER capability from a native `.kspwallet` V1 JSON document.
+pub async fn open_wallet_owner_v1(source: &[u8], password: crate::OwnerPassword) -> ksp_core_lib::Result<crate::WalletOwner> {
+    let envelope = match crate::KspWalletEnvelopeV1::parse_json(source) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+    let verify_result = verify_state_signature(&envelope);
+    if let std::result::Result::Err(error) = verify_result {
+        return std::result::Result::Err(error);
+    }
+    let owner_slot = envelope.owner_slot();
+    let derived_result = derive_owner_password_key_async(password, owner_slot.kdf().clone()).await;
+    let derived = match derived_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+    let owner_root_result =
+        crate::crypto::unwrap_key(&derived, owner_slot.wrap().nonce(), envelope.owner_slot_aad().as_slice(), owner_slot.wrap().ciphertext());
+    let owner_root = match owner_root_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return std::result::Result::Err(owner_unlock_error()),
+    };
+    let owner_control_plaintext_result = crate::crypto::decrypt_bytes(
+        &owner_root,
+        envelope.owner_control().nonce(),
+        envelope.compartment_aad(crate::WalletCompartmentKindV1::OwnerControl).as_slice(),
+        envelope.owner_control().ciphertext(),
+    );
+    let mut owner_control_plaintext = match owner_control_plaintext_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return std::result::Result::Err(owner_unlock_error()),
+    };
+    let control_result = crate::payload::decode_owner_control_payload(owner_control_plaintext.as_slice());
+    owner_control_plaintext.zeroize();
+    let control = match control_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+    let (mut admin_secret, metadata_key, secret_key) = control.into_parts();
+    let admin_signing_key = ed25519_dalek::SigningKey::from_bytes(&admin_secret);
+    admin_secret.zeroize();
+    if admin_signing_key.verifying_key().to_bytes() != *envelope.owner_auth_public_key() {
+        return std::result::Result::Err(authentication_error());
+    }
+
+    let metadata_plaintext_result = crate::crypto::decrypt_bytes(
+        &metadata_key,
+        envelope.metadata().nonce(),
+        envelope.compartment_aad(crate::WalletCompartmentKindV1::Metadata).as_slice(),
+        envelope.metadata().ciphertext(),
+    );
+    let mut metadata_plaintext = match metadata_plaintext_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return std::result::Result::Err(authentication_error()),
+    };
+    let metadata_payload_result = crate::payload::decode_metadata_payload(metadata_plaintext.as_slice());
+    metadata_plaintext.zeroize();
+    let metadata_payload = match metadata_payload_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+
+    let secret_plaintext_result = crate::crypto::decrypt_bytes(
+        &secret_key,
+        envelope.secret().nonce(),
+        envelope.compartment_aad(crate::WalletCompartmentKindV1::Secret).as_slice(),
+        envelope.secret().ciphertext(),
+    );
+    let mut secret_plaintext = match secret_plaintext_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return std::result::Result::Err(authentication_error()),
+    };
+    if secret_plaintext.len() != crate::KSPWALLET_V1_SECRET_PLAINTEXT_BYTES {
+        secret_plaintext.zeroize();
+        return std::result::Result::Err(key_material_error());
+    }
+    let keypair_result = solana_keypair::Keypair::try_from(secret_plaintext.as_slice());
+    let solana_keypair = match keypair_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => {
+            secret_plaintext.zeroize();
+            return std::result::Result::Err(key_material_error());
+        },
+    };
+    let secret_pubkey_result = pubkey_from_keypair_bytes(secret_plaintext.as_slice());
+    let secret_pubkey = match secret_pubkey_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => {
+            secret_plaintext.zeroize();
+            return std::result::Result::Err(error);
+        },
+    };
+    secret_plaintext.zeroize();
+    if &secret_pubkey != metadata_payload.pubkey() {
+        return std::result::Result::Err(key_material_error());
+    }
+
+    let info = metadata_payload.into_info(crate::WalletCapability::Owner);
+    let state = OwnerStateV1::new(envelope, owner_root, metadata_key, secret_key, admin_signing_key, solana_keypair);
+    ksp_logging_lib::debug!(
+        target: crate::TRACING_TARGET,
+        operation = "wallet_open_owner",
+        format_version = crate::KSPWALLET_FORMAT_VERSION_V1,
+        capability = "owner",
+        "native wallet OWNER capability opened"
+    );
+    return std::result::Result::Ok(crate::WalletOwner::from_unlocked(info, state));
+}
+
+/// Parses and verifies the OWNER-authenticated locked state without unlocking metadata or secret material.
+pub fn inspect_locked_wallet_v1(source: &[u8]) -> ksp_core_lib::Result<crate::LockedWalletInfo> {
+    let envelope = match crate::KspWalletEnvelopeV1::parse_json(source) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+    let verify_result = verify_state_signature(&envelope);
+    if let std::result::Result::Err(error) = verify_result {
+        return std::result::Result::Err(error);
+    }
+    return std::result::Result::Ok(crate::LockedWalletInfo::new(envelope.view_descriptor().enabled()));
+}
+
+pub(crate) fn verify_state_signature(envelope: &crate::KspWalletEnvelopeV1) -> ksp_core_lib::Result<()> {
+    let verifying_key_result = ed25519_dalek::VerifyingKey::from_bytes(envelope.owner_auth_public_key());
+    let verifying_key = match verifying_key_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return std::result::Result::Err(authentication_error()),
+    };
+    let signature = ed25519_dalek::Signature::from_bytes(envelope.state_signature().signature());
+    let verify_result = verifying_key.verify_strict(envelope.state_transcript().as_slice(), &signature);
+    return match verify_result {
+        std::result::Result::Ok(()) => std::result::Result::Ok(()),
+        std::result::Result::Err(_) => std::result::Result::Err(authentication_error()),
+    };
+}
+
+struct ViewCreationMaterialV1 {
+    slot_id: [u8; crate::KSPWALLET_V1_SLOT_ID_BYTES],
+    kdf: crate::WalletKdfParametersV1,
+    wrap_nonce: [u8; crate::KSPWALLET_V1_XCHACHA_NONCE_BYTES],
+    password: crate::ViewPassword,
+}
+
+fn prepare_view_creation(password: std::option::Option<crate::ViewPassword>) -> ksp_core_lib::Result<std::option::Option<ViewCreationMaterialV1>> {
+    let password = match password {
+        std::option::Option::Some(value) => value,
+        std::option::Option::None => return std::result::Result::Ok(std::option::Option::None),
+    };
+    let slot_id = match crate::crypto::random_bytes::<{ crate::KSPWALLET_V1_SLOT_ID_BYTES }>() {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+    let salt = match crate::crypto::random_bytes::<{ crate::KSPWALLET_V1_DEFAULT_KDF_SALT_BYTES }>() {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+    let wrap_nonce = match crate::crypto::random_nonce() {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+    return std::result::Result::Ok(std::option::Option::Some(ViewCreationMaterialV1 {
+        slot_id,
+        kdf: crate::WalletKdfParametersV1::new_creation(salt.to_vec()),
+        wrap_nonce,
+        password,
+    }));
+}
+
+async fn seal_view_slot(
+    envelope: &crate::KspWalletEnvelopeV1,
+    material: std::option::Option<ViewCreationMaterialV1>,
+    metadata_key: &crate::crypto::SecretKeyV1,
+) -> ksp_core_lib::Result<std::option::Option<crate::WalletKeySlotV1>> {
+    let material = match material {
+        std::option::Option::Some(value) => value,
+        std::option::Option::None => return std::result::Result::Ok(std::option::Option::None),
+    };
+    let derived_result = derive_view_password_key_async(material.password, material.kdf.clone()).await;
+    let derived = match derived_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+    let provisional_slot = crate::WalletKeySlotV1::new(
+        material.slot_id,
+        crate::WalletKeySlotRoleV1::View,
+        material.kdf.clone(),
+        crate::WalletKeyWrapV1::new(material.wrap_nonce, std::vec![0_u8; crate::crypto::SECRET_KEY_BYTES + crate::KSPWALLET_V1_AEAD_TAG_BYTES]),
+    );
+    let aad = crate::slot_aad(envelope, &provisional_slot);
+    let wrapped_result = crate::crypto::wrap_key(&derived, metadata_key, &material.wrap_nonce, aad.as_slice());
+    let wrapped = match wrapped_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+    return std::result::Result::Ok(std::option::Option::Some(crate::WalletKeySlotV1::new(
+        material.slot_id,
+        crate::WalletKeySlotRoleV1::View,
+        material.kdf,
+        crate::WalletKeyWrapV1::new(material.wrap_nonce, wrapped),
+    )));
+}
+
+fn provisional_envelope(
+    owner_auth_public_key: [u8; crate::KSPWALLET_V1_ED25519_PUBLIC_KEY_BYTES],
+    owner_slot_id: [u8; crate::KSPWALLET_V1_SLOT_ID_BYTES],
+    owner_kdf: crate::WalletKdfParametersV1,
+    owner_wrap_nonce: [u8; crate::KSPWALLET_V1_XCHACHA_NONCE_BYTES],
+    view_material: std::option::Option<&ViewCreationMaterialV1>,
+    owner_control_nonce: [u8; crate::KSPWALLET_V1_XCHACHA_NONCE_BYTES],
+    metadata_nonce: [u8; crate::KSPWALLET_V1_XCHACHA_NONCE_BYTES],
+    secret_nonce: [u8; crate::KSPWALLET_V1_XCHACHA_NONCE_BYTES],
+) -> crate::KspWalletEnvelopeV1 {
+    let owner_slot = crate::WalletKeySlotV1::new(
+        owner_slot_id,
+        crate::WalletKeySlotRoleV1::Owner,
+        owner_kdf,
+        crate::WalletKeyWrapV1::new(owner_wrap_nonce, std::vec![0_u8; crate::crypto::SECRET_KEY_BYTES + crate::KSPWALLET_V1_AEAD_TAG_BYTES]),
+    );
+    let (view_descriptor, view_slot) = match view_material {
+        std::option::Option::Some(material) => (
+            crate::WalletViewDescriptorV1::enabled(material.slot_id),
+            std::option::Option::Some(crate::WalletKeySlotV1::new(
+                material.slot_id,
+                crate::WalletKeySlotRoleV1::View,
+                material.kdf.clone(),
+                crate::WalletKeyWrapV1::new(material.wrap_nonce, std::vec![0_u8; crate::crypto::SECRET_KEY_BYTES + crate::KSPWALLET_V1_AEAD_TAG_BYTES]),
+            )),
+        ),
+        std::option::Option::None => (crate::WalletViewDescriptorV1::disabled(), std::option::Option::None),
+    };
+    return crate::KspWalletEnvelopeV1::new_internal(
+        owner_auth_public_key,
+        view_descriptor,
+        owner_slot,
+        view_slot,
+        crate::WalletEncryptedCompartmentV1::new(
+            crate::WalletCompartmentKindV1::OwnerControl,
+            owner_control_nonce,
+            std::vec![0_u8; crate::KSPWALLET_V1_AEAD_TAG_BYTES],
+        ),
+        crate::WalletEncryptedCompartmentV1::new(crate::WalletCompartmentKindV1::Metadata, metadata_nonce, std::vec![0_u8; crate::KSPWALLET_V1_AEAD_TAG_BYTES]),
+        crate::WalletEncryptedCompartmentV1::new(crate::WalletCompartmentKindV1::Secret, secret_nonce, std::vec![0_u8; crate::KSPWALLET_V1_AEAD_TAG_BYTES]),
+        crate::WalletStateSignatureV1::new([0_u8; crate::KSPWALLET_V1_ED25519_SIGNATURE_BYTES]),
+    );
+}
+
+async fn derive_owner_password_key_async(
+    password: crate::OwnerPassword,
+    kdf: crate::WalletKdfParametersV1,
+) -> ksp_core_lib::Result<crate::crypto::SecretKeyV1> {
+    let task = tokio::task::spawn_blocking(move || return crate::crypto::derive_password_key(password.as_bytes(), &kdf));
+    return match task.await {
+        std::result::Result::Ok(result) => result,
+        std::result::Result::Err(_) => std::result::Result::Err(crypto_operation_error()),
+    };
+}
+
+async fn derive_view_password_key_async(password: crate::ViewPassword, kdf: crate::WalletKdfParametersV1) -> ksp_core_lib::Result<crate::crypto::SecretKeyV1> {
+    let task = tokio::task::spawn_blocking(move || return crate::crypto::derive_password_key(password.as_bytes(), &kdf));
+    return match task.await {
+        std::result::Result::Ok(result) => result,
+        std::result::Result::Err(_) => std::result::Result::Err(crypto_operation_error()),
+    };
+}
+
+fn pubkey_from_keypair_bytes(bytes: &[u8]) -> ksp_core_lib::Result<ksp_core_lib::Pubkey> {
+    let public_slice = match bytes.get(32..64) {
+        std::option::Option::Some(value) => value,
+        std::option::Option::None => return std::result::Result::Err(key_material_error()),
+    };
+    let public_array = match <[u8; 32]>::try_from(public_slice) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return std::result::Result::Err(key_material_error()),
+    };
+    return std::result::Result::Ok(ksp_core_lib::Pubkey::new_from_array(public_array));
+}
+
+fn cleanup_create_error<T>(
+    error: ksp_core_lib::Error,
+    owner_control_plaintext: &mut [u8],
+    metadata_plaintext: &mut [u8],
+    solana_keypair_bytes: &mut [u8],
+) -> ksp_core_lib::Result<T> {
+    owner_control_plaintext.zeroize();
+    metadata_plaintext.zeroize();
+    solana_keypair_bytes.zeroize();
+    return std::result::Result::Err(error);
+}
+
+fn authentication_error() -> ksp_core_lib::Error {
+    return ksp_core_lib::Error::new(crate::ERROR_CODE_AUTHENTICATION_FAILED, "Wallet OWNER-authenticated state verification failed");
+}
+
+fn crypto_operation_error() -> ksp_core_lib::Error {
+    return ksp_core_lib::Error::new(crate::ERROR_CODE_CRYPTO_OPERATION_FAILED, "Wallet blocking cryptographic operation could not complete");
+}
+
+fn view_unlock_error() -> ksp_core_lib::Error {
+    return ksp_core_lib::Error::new(crate::ERROR_CODE_VIEW_UNLOCK_FAILED, "Wallet VIEW capability could not be unlocked");
+}
+
+fn owner_unlock_error() -> ksp_core_lib::Error {
+    return ksp_core_lib::Error::new(crate::ERROR_CODE_OWNER_UNLOCK_FAILED, "Wallet OWNER capability could not be unlocked");
+}
+
+fn capability_error(message: &'static str) -> ksp_core_lib::Error {
+    return ksp_core_lib::Error::new(crate::ERROR_CODE_CAPABILITY_INSUFFICIENT, message);
+}
+
+fn key_material_error() -> ksp_core_lib::Error {
+    return ksp_core_lib::Error::new(crate::ERROR_CODE_KEY_MATERIAL_INVALID, "Wallet Solana key material is invalid or inconsistent");
+}
+
+#[cfg(test)]
+#[path = "../unit_tests/wallet.rs"]
+mod tests;