host_api/

lib.rs

//! Host API — transport-agnostic engine for the Polkadot app host-api protocol.
//!
//! Processes binary SCALE-encoded messages from Polkadot apps and returns binary
//! responses. Works over any transport: WKWebView MessagePort, PolkaVM host calls,
//! WebSocket, etc.
//!
//! See [`HostApi::handle_message`] for the main entry point.

pub mod chain;
pub mod codec;
pub mod protocol;

use protocol::{
    decode_message, encode_account_status, encode_feature_response, encode_response, Account,
    HostRequest, HostResponse, PROTOCOL_VERSION, TAG_ACCOUNT_STATUS_INTERRUPT,
    TAG_ACCOUNT_STATUS_STOP, TAG_CHAIN_HEAD_BODY_REQ, TAG_CHAIN_HEAD_CALL_REQ,
    TAG_CHAIN_HEAD_CONTINUE_REQ, TAG_CHAIN_HEAD_FOLLOW_INTERRUPT, TAG_CHAIN_HEAD_FOLLOW_STOP,
    TAG_CHAIN_HEAD_HEADER_REQ, TAG_CHAIN_HEAD_STOP_OP_REQ, TAG_CHAIN_HEAD_STORAGE_REQ,
    TAG_CHAIN_HEAD_UNPIN_REQ, TAG_CHAIN_SPEC_GENESIS_REQ, TAG_CHAIN_SPEC_NAME_REQ,
    TAG_CHAIN_SPEC_PROPS_REQ, TAG_CHAT_ACTION_INTERRUPT, TAG_CHAT_ACTION_STOP,
    TAG_CHAT_CUSTOM_MSG_INTERRUPT, TAG_CHAT_CUSTOM_MSG_STOP, TAG_CHAT_LIST_INTERRUPT,
    TAG_CHAT_LIST_STOP, TAG_JSONRPC_SUB_INTERRUPT, TAG_JSONRPC_SUB_STOP,
    TAG_PREIMAGE_LOOKUP_INTERRUPT, TAG_PREIMAGE_LOOKUP_STOP, TAG_STATEMENT_STORE_INTERRUPT,
    TAG_STATEMENT_STORE_STOP,
};

#[cfg(feature = "tracing")]
use tracing::info_span;

/// Maximum size of a single storage value (64 KB).
const MAX_STORAGE_VALUE_SIZE: usize = 64 * 1024;
/// Maximum storage key length (512 bytes).
const MAX_STORAGE_KEY_LENGTH: usize = 512;
/// Maximum push notification text length in UTF-8 bytes (1024 bytes).
/// Multi-byte characters count proportionally to their encoded size.
const MAX_PUSH_NOTIFICATION_TEXT_LEN: usize = 1024;
/// Maximum deeplink URL length in UTF-8 bytes (2048 bytes).
const MAX_DEEPLINK_URL_LEN: usize = 2048;
/// Allowed URI scheme prefixes for push notification deeplinks.
/// The SDK rejects any deeplink that does not start with one of these
/// schemes. Only `https://` is permitted.
const ALLOWED_DEEPLINK_SCHEMES: &[&str] = &["https://"];

/// Outcome of processing a host-api message.
#[derive(serde::Serialize)]
#[serde(tag = "type")]
pub enum HostApiOutcome {
    /// Send this response directly back to the app.
    Response { data: Vec<u8> },
    /// Sign request — needs wallet to produce a signature before responding.
    NeedsSign {
        request_id: String,
        request_tag: u8,
        public_key: Vec<u8>,
        payload: Vec<u8>,
    },
    /// JSON-RPC query — needs routing through the chain API allowlist + RPC bridge.
    NeedsChainQuery {
        request_id: String,
        method: String,
        params: serde_json::Value,
    },
    /// JSON-RPC subscription — needs routing through the chain API for streaming responses.
    NeedsChainSubscription {
        request_id: String,
        method: String,
        params: serde_json::Value,
    },
    /// Navigation request — the workbench should open this URL (may be a .dot address).
    NeedsNavigate { request_id: String, url: String },
    /// Push notification — host should display a toast/banner with the given text.
    ///
    /// **`deeplink` is unvalidated by the SDK.** The protocol layer passes it
    /// through as-is. Hosts must reject or sanitize values that fail URL
    /// parsing before opening them (e.g. null bytes, control characters).
    NeedsPushNotification {
        request_id: String,
        text: String,
        deeplink: Option<String>,
    },
    /// Start a chainHead_v1_follow subscription for a specific chain.
    NeedsChainFollow {
        request_id: String,
        genesis_hash: Vec<u8>,
        with_runtime: bool,
    },
    /// A chain interaction request (header, storage, call, etc.) that needs
    /// routing to smoldot via JSON-RPC. The response_tag and json_rpc_method
    /// tell the workbench how to route and encode the response.
    NeedsChainRpc {
        request_id: String,
        request_tag: u8,
        genesis_hash: Vec<u8>,
        json_rpc_method: String,
        json_rpc_params: serde_json::Value,
        /// The follow subscription ID from the product-SDK (opaque string).
        follow_sub_id: Option<String>,
    },
    /// Product-scoped storage read — the host must look up `key` in persistent
    /// storage for the current product and call `encode_storage_read_response`.
    NeedsStorageRead { request_id: String, key: String },
    /// Product-scoped storage write — the host must persist `value` under `key`
    /// for the current product and call `encode_storage_write_response`.
    NeedsStorageWrite {
        request_id: String,
        key: String,
        value: Vec<u8>,
    },
    /// Product-scoped storage clear — the host must remove `key` from persistent
    /// storage for the current product and call `encode_storage_clear_response`.
    NeedsStorageClear { request_id: String, key: String },
    /// No response needed (fire-and-forget).
    Silent,
}

/// Shared host implementation. Handles decoded requests, returns encoded responses.
pub struct HostApi {
    accounts: Vec<Account>,
    supported_chains: std::collections::HashSet<[u8; 32]>,
}

impl Default for HostApi {
    fn default() -> Self {
        Self::new()
    }
}

impl HostApi {
    pub fn new() -> Self {
        Self {
            accounts: Vec::new(),
            supported_chains: std::collections::HashSet::new(),
        }
    }

    /// Set the accounts that will be returned by host_get_non_product_accounts.
    ///
    /// SECURITY: This exposes account identifiers to any product that requests
    /// them. Will be replaced by scoped per-product identities via host-sso.
    pub fn set_accounts(&mut self, accounts: Vec<Account>) {
        self.accounts = accounts;
    }

    /// Set the chain genesis hashes that this host supports.
    /// Each hash is 32 bytes (raw, not hex-encoded).
    pub fn set_supported_chains(&mut self, chains: impl IntoIterator<Item = [u8; 32]>) {
        self.supported_chains = chains.into_iter().collect();
    }

    /// Process a raw binary message from the app.
    ///
    /// Returns `HostApiOutcome::Response` for immediate replies,
    /// `HostApiOutcome::NeedsSign` for sign requests that need wallet approval,
    /// or `HostApiOutcome::Silent` for fire-and-forget messages.
    ///
    /// `app_id` identifies the product — the host must use this value to scope
    /// storage when acting on `NeedsStorageRead`, `NeedsStorageWrite`, and
    /// `NeedsStorageClear` outcomes. It is not embedded in the outcome itself.
    pub fn handle_message(&mut self, raw: &[u8], app_id: &str) -> HostApiOutcome {
        #[cfg(feature = "tracing")]
        let _span = info_span!(
            "host_api.handle_message",
            app_id,
            request_tag = tracing::field::Empty,
            request_kind = tracing::field::Empty,
        )
        .entered();
        let _ = app_id; // used by tracing; host reads it from call-site context

        let (request_id, request_tag, req) = match decode_message(raw) {
            Ok(v) => v,
            Err(e) => {
                log::warn!(
                    "[hostapi] failed to decode message: kind={}",
                    decode_error_kind(&e)
                );
                #[cfg(feature = "tracing")]
                tracing::Span::current().record("request_kind", "decode_error");
                return HostApiOutcome::Silent;
            }
        };

        #[cfg(feature = "tracing")]
        {
            tracing::Span::current().record("request_tag", request_tag);
            tracing::Span::current().record("request_kind", request_kind(&req));
        }

        log::info!(
            "[hostapi] request: kind={} (tag={request_tag})",
            request_kind(&req)
        );

        match req {
            HostRequest::Handshake { version } => {
                if version == PROTOCOL_VERSION {
                    HostApiOutcome::Response {
                        data: encode_response(&request_id, request_tag, &HostResponse::HandshakeOk),
                    }
                } else {
                    log::warn!("[hostapi] unsupported protocol version: {version}");
                    HostApiOutcome::Response {
                        data: encode_response(
                            &request_id,
                            request_tag,
                            &HostResponse::Error("unsupported protocol version".into()),
                        ),
                    }
                }
            }

            HostRequest::GetNonProductAccounts => {
                // SECURITY: This exposes the soft-derivation root (//wallet//sso
                // pubkey) to any product that requests it, allowing enumeration
                // of all product addresses. This will be replaced by the host-sso
                // pairing flow which provides scoped, per-product identities.
                // See docs/threat-model-soft-derivation.md scenarios 1 & 2.
                // TODO: remove once host-sso is fully wired and VoxChat uses it.
                log::info!(
                    "[hostapi] returning {} non-product account(s)",
                    self.accounts.len()
                );
                HostApiOutcome::Response {
                    data: encode_response(
                        &request_id,
                        request_tag,
                        &HostResponse::AccountList(self.accounts.clone()),
                    ),
                }
            }

            HostRequest::FeatureSupported { feature_data } => {
                let feature_kind = feature_log_kind(&feature_data);
                // Check string features first (signing, navigate, etc.)
                let supported = if let Ok(s) = std::str::from_utf8(&feature_data) {
                    let r = matches!(s, "signing" | "sign" | "navigate" | "push_notification");
                    r
                } else {
                    // Binary feature: byte 0 = type, then SCALE-encoded data.
                    // Type 0 = chain: compact_length + genesis_hash (32 bytes)
                    let r = if feature_data.first() == Some(&0) {
                        codec::Reader::new(&feature_data[1..])
                            .read_var_bytes()
                            .ok()
                            .and_then(|h| <[u8; 32]>::try_from(h).ok())
                            .map(|h| self.supported_chains.contains(&h))
                            .unwrap_or(false)
                    } else {
                        false
                    };
                    r
                };
                log::info!("[hostapi] feature_supported: feature={feature_kind} -> {supported}");
                HostApiOutcome::Response {
                    data: encode_feature_response(&request_id, supported),
                }
            }

            HostRequest::AccountConnectionStatusStart => HostApiOutcome::Response {
                data: encode_account_status(&request_id, true),
            },

            HostRequest::LocalStorageRead { key } => {
                if key.len() > MAX_STORAGE_KEY_LENGTH {
                    return HostApiOutcome::Response {
                        data: encode_response(
                            &request_id,
                            request_tag,
                            &HostResponse::Error("storage key too long".into()),
                        ),
                    };
                }
                HostApiOutcome::NeedsStorageRead { request_id, key }
            }

            HostRequest::LocalStorageWrite { key, value } => {
                if key.len() > MAX_STORAGE_KEY_LENGTH {
                    return HostApiOutcome::Response {
                        data: encode_response(
                            &request_id,
                            request_tag,
                            &HostResponse::Error("storage key too long".into()),
                        ),
                    };
                }
                if value.len() > MAX_STORAGE_VALUE_SIZE {
                    return HostApiOutcome::Response {
                        data: encode_response(
                            &request_id,
                            request_tag,
                            &HostResponse::Error("storage value too large".into()),
                        ),
                    };
                }
                HostApiOutcome::NeedsStorageWrite {
                    request_id,
                    key,
                    value,
                }
            }

            HostRequest::LocalStorageClear { key } => {
                if key.len() > MAX_STORAGE_KEY_LENGTH {
                    return HostApiOutcome::Response {
                        data: encode_response(
                            &request_id,
                            request_tag,
                            &HostResponse::Error("storage key too long".into()),
                        ),
                    };
                }
                HostApiOutcome::NeedsStorageClear { request_id, key }
            }

            HostRequest::NavigateTo { url } => {
                log::info!("[hostapi] navigate_to request");
                HostApiOutcome::NeedsNavigate { request_id, url }
            }

            HostRequest::PushNotification { text, deeplink } => {
                log::info!("[hostapi] push_notification request");
                if text.len() > MAX_PUSH_NOTIFICATION_TEXT_LEN {
                    return HostApiOutcome::Response {
                        data: encode_response(
                            &request_id,
                            request_tag,
                            &HostResponse::Error("push notification text too long".into()),
                        ),
                    };
                }
                if let Some(ref dl) = deeplink {
                    if dl.len() > MAX_DEEPLINK_URL_LEN {
                        return HostApiOutcome::Response {
                            data: encode_response(
                                &request_id,
                                request_tag,
                                &HostResponse::Error("deeplink URL too long".into()),
                            ),
                        };
                    }
                    if !is_allowed_deeplink_scheme(dl) {
                        return HostApiOutcome::Response {
                            data: encode_response(
                                &request_id,
                                request_tag,
                                &HostResponse::Error(
                                    "deeplink scheme not allowed; only https:// is accepted".into(),
                                ),
                            ),
                        };
                    }
                }
                HostApiOutcome::NeedsPushNotification {
                    request_id,
                    text,
                    deeplink,
                }
            }

            HostRequest::SignPayload {
                public_key,
                payload,
            } => {
                log::info!(
                    "[hostapi] sign_payload request (pubkey={} bytes)",
                    public_key.len()
                );
                HostApiOutcome::NeedsSign {
                    request_id,
                    request_tag,
                    public_key,
                    payload,
                }
            }

            HostRequest::SignRaw { public_key, data } => {
                log::info!(
                    "[hostapi] sign_raw request (pubkey={} bytes)",
                    public_key.len()
                );
                HostApiOutcome::NeedsSign {
                    request_id,
                    request_tag,
                    public_key,
                    payload: data,
                }
            }

            HostRequest::CreateTransaction { .. } => {
                log::info!("[hostapi] create_transaction (not yet implemented)");
                HostApiOutcome::Response {
                    data: encode_response(
                        &request_id,
                        request_tag,
                        &HostResponse::Error("create_transaction not yet implemented".into()),
                    ),
                }
            }

            HostRequest::JsonRpcSend { data } => {
                // The data is a SCALE string containing a JSON-RPC request body,
                // or raw bytes we try to interpret as UTF-8 JSON.
                let json_str = parse_jsonrpc_data(&data);
                match json_str {
                    Some((method, params)) => {
                        log::info!("[hostapi] jsonrpc_send request");
                        HostApiOutcome::NeedsChainQuery {
                            request_id,
                            method,
                            params,
                        }
                    }
                    None => {
                        log::warn!("[hostapi] failed to parse JSON-RPC send data");
                        HostApiOutcome::Response {
                            data: encode_response(
                                &request_id,
                                request_tag,
                                &HostResponse::Error("invalid json-rpc request".into()),
                            ),
                        }
                    }
                }
            }

            HostRequest::JsonRpcSubscribeStart { data } => {
                let json_str = parse_jsonrpc_data(&data);
                match json_str {
                    Some((method, params)) => {
                        log::info!("[hostapi] jsonrpc_subscribe_start request");
                        HostApiOutcome::NeedsChainSubscription {
                            request_id,
                            method,
                            params,
                        }
                    }
                    None => {
                        log::warn!("[hostapi] failed to parse JSON-RPC subscribe data");
                        HostApiOutcome::Response {
                            data: encode_response(
                                &request_id,
                                request_tag,
                                &HostResponse::Error("invalid json-rpc subscribe request".into()),
                            ),
                        }
                    }
                }
            }

            HostRequest::ChainHeadFollowStart {
                genesis_hash,
                with_runtime,
            } => {
                log::info!("[hostapi] chainHead follow start (genesis={} bytes, withRuntime={with_runtime})", genesis_hash.len());
                HostApiOutcome::NeedsChainFollow {
                    request_id,
                    genesis_hash,
                    with_runtime,
                }
            }

            HostRequest::ChainHeadRequest {
                tag,
                genesis_hash,
                follow_sub_id,
                data,
            } => {
                let method = match tag {
                    TAG_CHAIN_HEAD_HEADER_REQ => "chainHead_v1_header",
                    TAG_CHAIN_HEAD_BODY_REQ => "chainHead_v1_body",
                    TAG_CHAIN_HEAD_STORAGE_REQ => "chainHead_v1_storage",
                    TAG_CHAIN_HEAD_CALL_REQ => "chainHead_v1_call",
                    TAG_CHAIN_HEAD_UNPIN_REQ => "chainHead_v1_unpin",
                    TAG_CHAIN_HEAD_CONTINUE_REQ => "chainHead_v1_continue",
                    TAG_CHAIN_HEAD_STOP_OP_REQ => "chainHead_v1_stopOperation",
                    _ => {
                        log::warn!("[hostapi] unknown chain head request tag: {tag}");
                        return HostApiOutcome::Silent;
                    }
                };
                log::info!("[hostapi] chain request: {method} (tag={tag})");
                HostApiOutcome::NeedsChainRpc {
                    request_id,
                    request_tag: tag,
                    genesis_hash,
                    json_rpc_method: method.into(),
                    json_rpc_params: data,
                    follow_sub_id: Some(follow_sub_id),
                }
            }

            HostRequest::ChainSpecRequest { tag, genesis_hash } => {
                let method = match tag {
                    TAG_CHAIN_SPEC_GENESIS_REQ => "chainSpec_v1_genesisHash",
                    TAG_CHAIN_SPEC_NAME_REQ => "chainSpec_v1_chainName",
                    TAG_CHAIN_SPEC_PROPS_REQ => "chainSpec_v1_properties",
                    _ => {
                        log::warn!("[hostapi] unknown chainSpec request tag: {tag}");
                        return HostApiOutcome::Silent;
                    }
                };
                log::info!("[hostapi] chainSpec request: {method} (tag={tag})");
                HostApiOutcome::NeedsChainRpc {
                    request_id,
                    request_tag: tag,
                    genesis_hash,
                    json_rpc_method: method.into(),
                    json_rpc_params: serde_json::Value::Array(vec![]),
                    follow_sub_id: None,
                }
            }

            HostRequest::ChainTxBroadcast {
                genesis_hash,
                transaction,
            } => {
                log::info!("[hostapi] transaction broadcast");
                let tx_hex = chain::bytes_to_hex(&transaction);
                HostApiOutcome::NeedsChainRpc {
                    request_id,
                    request_tag,
                    genesis_hash,
                    json_rpc_method: "transaction_v1_broadcast".into(),
                    json_rpc_params: serde_json::json!([tx_hex]),
                    follow_sub_id: None,
                }
            }

            HostRequest::ChainTxStop {
                genesis_hash,
                operation_id,
            } => {
                log::info!("[hostapi] transaction stop");
                HostApiOutcome::NeedsChainRpc {
                    request_id,
                    request_tag,
                    genesis_hash,
                    json_rpc_method: "transaction_v1_stop".into(),
                    json_rpc_params: serde_json::json!([operation_id]),
                    follow_sub_id: None,
                }
            }

            HostRequest::Unimplemented { tag } => {
                log::info!("[hostapi] unimplemented method (tag={tag})");
                if is_subscription_control(tag) {
                    HostApiOutcome::Silent
                } else {
                    HostApiOutcome::Response {
                        data: encode_response(
                            &request_id,
                            request_tag,
                            &HostResponse::Error("not implemented".into()),
                        ),
                    }
                }
            }

            HostRequest::Unknown { tag } => {
                log::warn!("[hostapi] unknown tag: {tag}");
                HostApiOutcome::Silent
            }
        }
    }
}

/// Parse the `data` field from a `JsonRpcSend` request.
///
/// The Product SDK encodes this as a SCALE string containing the full JSON-RPC
/// request (e.g. `{"jsonrpc":"2.0","id":1,"method":"state_getMetadata","params":[]}`).
/// We try SCALE string first, then fall back to raw UTF-8.
fn parse_jsonrpc_data(data: &[u8]) -> Option<(String, serde_json::Value)> {
    // Try SCALE string (compact length + UTF-8 bytes).
    let json_str = codec::Reader::new(data)
        .read_string()
        .ok()
        .or_else(|| std::str::from_utf8(data).ok().map(|s| s.to_string()))?;

    let v: serde_json::Value = serde_json::from_str(&json_str).ok()?;
    let method = v.get("method")?.as_str()?.to_string();
    let params = v
        .get("params")
        .cloned()
        .unwrap_or(serde_json::Value::Array(vec![]));
    Some((method, params))
}

/// Check if a tag is a subscription control message (stop/interrupt).
fn is_subscription_control(tag: u8) -> bool {
    matches!(
        tag,
        TAG_ACCOUNT_STATUS_STOP
            | TAG_ACCOUNT_STATUS_INTERRUPT
            | TAG_CHAT_LIST_STOP
            | TAG_CHAT_LIST_INTERRUPT
            | TAG_CHAT_ACTION_STOP
            | TAG_CHAT_ACTION_INTERRUPT
            | TAG_CHAT_CUSTOM_MSG_STOP
            | TAG_CHAT_CUSTOM_MSG_INTERRUPT
            | TAG_STATEMENT_STORE_STOP
            | TAG_STATEMENT_STORE_INTERRUPT
            | TAG_PREIMAGE_LOOKUP_STOP
            | TAG_PREIMAGE_LOOKUP_INTERRUPT
            | TAG_JSONRPC_SUB_STOP
            | TAG_JSONRPC_SUB_INTERRUPT
            | TAG_CHAIN_HEAD_FOLLOW_STOP
            | TAG_CHAIN_HEAD_FOLLOW_INTERRUPT
    )
}

fn decode_error_kind(err: &codec::DecodeErr) -> &'static str {
    match err {
        codec::DecodeErr::Eof => "eof",
        codec::DecodeErr::CompactTooLarge => "compact_too_large",
        codec::DecodeErr::InvalidUtf8 => "invalid_utf8",
        codec::DecodeErr::InvalidOption => "invalid_option",
        codec::DecodeErr::InvalidTag(_) => "invalid_tag",
        codec::DecodeErr::BadMessage(_) => "bad_message",
    }
}

fn feature_log_kind(feature_data: &[u8]) -> &'static str {
    match std::str::from_utf8(feature_data) {
        Ok("signing" | "sign" | "navigate" | "push_notification") => "utf8_known",
        Ok(_) => "utf8_other",
        Err(_) if feature_data.first() == Some(&0) => "binary_chain",
        Err(_) => "binary_other",
    }
}

fn request_kind(req: &HostRequest) -> &'static str {
    match req {
        HostRequest::Handshake { .. } => "handshake",
        HostRequest::GetNonProductAccounts => "get_non_product_accounts",
        HostRequest::FeatureSupported { .. } => "feature_supported",
        HostRequest::LocalStorageRead { .. } => "local_storage_read",
        HostRequest::LocalStorageWrite { .. } => "local_storage_write",
        HostRequest::LocalStorageClear { .. } => "local_storage_clear",
        HostRequest::SignPayload { .. } => "sign_payload",
        HostRequest::SignRaw { .. } => "sign_raw",
        HostRequest::CreateTransaction { .. } => "create_transaction",
        HostRequest::NavigateTo { .. } => "navigate_to",
        HostRequest::PushNotification { .. } => "push_notification",
        HostRequest::AccountConnectionStatusStart => "account_connection_status_start",
        HostRequest::JsonRpcSend { .. } => "jsonrpc_send",
        HostRequest::JsonRpcSubscribeStart { .. } => "jsonrpc_subscribe_start",
        HostRequest::ChainHeadFollowStart { .. } => "chain_head_follow_start",
        HostRequest::ChainHeadRequest { .. } => "chain_head_request",
        HostRequest::ChainSpecRequest { .. } => "chain_spec_request",
        HostRequest::ChainTxBroadcast { .. } => "chain_tx_broadcast",
        HostRequest::ChainTxStop { .. } => "chain_tx_stop",
        HostRequest::Unimplemented { .. } => "unimplemented",
        HostRequest::Unknown { .. } => "unknown",
    }
}

/// Check whether a deeplink URI has an allowed scheme.
/// Only `https://` is accepted by default (case-insensitive on the scheme).
fn is_allowed_deeplink_scheme(url: &str) -> bool {
    let lower = url.to_ascii_lowercase();
    ALLOWED_DEEPLINK_SCHEMES
        .iter()
        .any(|scheme| lower.starts_with(scheme))
}

// ---------------------------------------------------------------------------
// JS bridge script — injected into WKWebView at document_start
// ---------------------------------------------------------------------------

/// JavaScript injected before the Polkadot app loads. Sets up:
/// 1. `window.__HOST_WEBVIEW_MARK__ = true` — SDK webview detection
/// 2. `MessageChannel` with port2 as `window.__HOST_API_PORT__`
/// 3. Binary message forwarding between port1 and native (base64)
pub const HOST_API_BRIDGE_SCRIPT: &str = concat!(
    r#"
(function() {
    'use strict';
    if (window.__hostApiBridge) { return; }
    window.__hostApiBridge = true;
    window.__HOST_WEBVIEW_MARK__ = true;
    var ch = new MessageChannel();
    window.__HOST_API_PORT__ = ch.port2;
    ch.port2.start();
    var port1 = ch.port1;
    port1.start();
    if (!window.host) { window.host = {}; }
    if (!window.host.storage) { window.host.storage = {}; }
    port1.onmessage = function(ev) {
        var data = ev.data;
        if (!data) { console.warn('[host-bridge] data is falsy, dropping'); return; }
        var bytes;
        if (data instanceof Uint8Array) { bytes = data; }
        else if (data instanceof ArrayBuffer) { bytes = new Uint8Array(data); }
        else if (ArrayBuffer.isView(data)) { bytes = new Uint8Array(data.buffer, data.byteOffset, data.byteLength); }
        else { console.warn('[host-bridge] unknown data type: ' + typeof data + ' constructor=' + (data.constructor ? data.constructor.name : '?') + ', dropping'); return; }
        var binary = '';
        for (var i = 0; i < bytes.length; i++) { binary += String.fromCharCode(bytes[i]); }
        try {
            window.webkit.messageHandlers.hostApi.postMessage(btoa(binary));
        } catch(e) {
            console.error('[host-bridge] postMessage to hostApi FAILED:', e.message);
        }
    };
    window.__hostApiReply = function(b64) {
        try {
            var binary = atob(b64);
            var bytes = new Uint8Array(binary.length);
            for (var i = 0; i < binary.length; i++) { bytes[i] = binary.charCodeAt(i); }
            port1.postMessage(bytes);
        } catch(e) { console.error('[host-bridge] reply failed:', e.message); }
    };
"#,
    include_str!("js/storage_bridge.js"),
    r#"
})();
"#
);

#[cfg(test)]
mod tests {
    use super::*;
    use crate::protocol::*;
    use std::sync::atomic::{AtomicBool, Ordering};
    use std::sync::{Mutex, Once};

    const TEST_APP: &str = "test-app";
    static TEST_LOGGER_INIT: Once = Once::new();
    static TEST_LOGGER_INSTALLED: AtomicBool = AtomicBool::new(false);
    static TEST_LOG_CAPTURE_LOCK: Mutex<()> = Mutex::new(());
    static TEST_LOGGER: TestLogger = TestLogger::new();

    struct TestLogger {
        entries: Mutex<Vec<String>>,
        capture_thread: Mutex<Option<std::thread::ThreadId>>,
    }

    impl TestLogger {
        const fn new() -> Self {
            Self {
                entries: Mutex::new(Vec::new()),
                capture_thread: Mutex::new(None),
            }
        }
    }

    impl log::Log for TestLogger {
        fn enabled(&self, metadata: &log::Metadata<'_>) -> bool {
            metadata.level() <= log::Level::Info
        }

        fn log(&self, record: &log::Record<'_>) {
            if !self.enabled(record.metadata()) {
                return;
            }

            let capture_thread = self
                .capture_thread
                .lock()
                .unwrap_or_else(|e| e.into_inner());
            if capture_thread.as_ref() != Some(&std::thread::current().id()) {
                return;
            }
            drop(capture_thread);

            self.entries
                .lock()
                .unwrap_or_else(|e| e.into_inner())
                .push(record.args().to_string());
        }

        fn flush(&self) {}
    }

    fn capture_logs<T>(f: impl FnOnce() -> T) -> (T, Vec<String>) {
        TEST_LOGGER_INIT.call_once(|| {
            let installed = log::set_logger(&TEST_LOGGER).is_ok();
            if installed {
                log::set_max_level(log::LevelFilter::Info);
            }
            TEST_LOGGER_INSTALLED.store(installed, Ordering::Relaxed);
        });
        assert!(
            TEST_LOGGER_INSTALLED.load(Ordering::Relaxed),
            "test logger could not be installed"
        );

        let _guard = TEST_LOG_CAPTURE_LOCK
            .lock()
            .unwrap_or_else(|e| e.into_inner());

        TEST_LOGGER
            .entries
            .lock()
            .unwrap_or_else(|e| e.into_inner())
            .clear();
        *TEST_LOGGER
            .capture_thread
            .lock()
            .unwrap_or_else(|e| e.into_inner()) = Some(std::thread::current().id());

        let result = f();

        *TEST_LOGGER
            .capture_thread
            .lock()
            .unwrap_or_else(|e| e.into_inner()) = None;
        let logs = TEST_LOGGER
            .entries
            .lock()
            .unwrap_or_else(|e| e.into_inner())
            .clone();
        TEST_LOGGER
            .entries
            .lock()
            .unwrap_or_else(|e| e.into_inner())
            .clear();

        (result, logs)
    }

    fn assert_logs_contain(logs: &[String], needle: &str) {
        let joined = logs.join("\n");
        assert!(
            joined.contains(needle),
            "expected logs to contain {needle:?}, got:\n{joined}"
        );
    }

    fn assert_logs_do_not_contain(logs: &[String], needle: &str) {
        let joined = logs.join("\n");
        assert!(
            !joined.contains(needle),
            "expected logs not to contain {needle:?}, got:\n{joined}"
        );
    }

    #[test]
    fn host_api_bridge_script_exposes_storage_surface() {
        assert!(HOST_API_BRIDGE_SCRIPT.contains("window.host.storage.get"));
        assert!(HOST_API_BRIDGE_SCRIPT.contains("window.host.storage.set"));
        assert!(HOST_API_BRIDGE_SCRIPT.contains("window.host.storage.remove"));
    }

    /// Extract a Response from HostApiOutcome, panicking on other variants.
    fn expect_response(outcome: HostApiOutcome) -> Vec<u8> {
        match outcome {
            HostApiOutcome::Response { data: v } => v,
            other => panic!("expected Response, got {}", outcome_name(&other)),
        }
    }

    fn expect_silent(outcome: HostApiOutcome) {
        match outcome {
            HostApiOutcome::Silent => {}
            other => panic!("expected Silent, got {}", outcome_name(&other)),
        }
    }

    fn outcome_name(o: &HostApiOutcome) -> &'static str {
        match o {
            HostApiOutcome::Response { .. } => "Response",
            HostApiOutcome::NeedsSign { .. } => "NeedsSign",
            HostApiOutcome::NeedsChainQuery { .. } => "NeedsChainQuery",
            HostApiOutcome::NeedsChainSubscription { .. } => "NeedsChainSubscription",
            HostApiOutcome::NeedsNavigate { .. } => "NeedsNavigate",
            HostApiOutcome::NeedsPushNotification { .. } => "NeedsPushNotification",
            HostApiOutcome::NeedsChainFollow { .. } => "NeedsChainFollow",
            HostApiOutcome::NeedsChainRpc { .. } => "NeedsChainRpc",
            HostApiOutcome::NeedsStorageRead { .. } => "NeedsStorageRead",
            HostApiOutcome::NeedsStorageWrite { .. } => "NeedsStorageWrite",
            HostApiOutcome::NeedsStorageClear { .. } => "NeedsStorageClear",
            HostApiOutcome::Silent => "Silent",
        }
    }

    fn make_handshake_request(request_id: &str) -> Vec<u8> {
        let mut msg = Vec::new();
        codec::encode_string(&mut msg, request_id);
        msg.push(TAG_HANDSHAKE_REQ);
        msg.push(0); // v1
        msg.push(PROTOCOL_VERSION);
        msg
    }

    fn make_get_accounts_request(request_id: &str) -> Vec<u8> {
        let mut msg = Vec::new();
        codec::encode_string(&mut msg, request_id);
        msg.push(TAG_GET_NON_PRODUCT_ACCOUNTS_REQ);
        msg.push(0); // v1
        msg
    }

    fn make_storage_write(request_id: &str, key: &str, value: &[u8]) -> Vec<u8> {
        let mut msg = Vec::new();
        codec::encode_string(&mut msg, request_id);
        msg.push(TAG_LOCAL_STORAGE_WRITE_REQ);
        msg.push(0); // v1
        codec::encode_string(&mut msg, key);
        codec::encode_var_bytes(&mut msg, value);
        msg
    }

    fn make_storage_read(request_id: &str, key: &str) -> Vec<u8> {
        let mut msg = Vec::new();
        codec::encode_string(&mut msg, request_id);
        msg.push(TAG_LOCAL_STORAGE_READ_REQ);
        msg.push(0); // v1
        codec::encode_string(&mut msg, key);
        msg
    }

    fn make_storage_clear(request_id: &str, key: &str) -> Vec<u8> {
        let mut msg = Vec::new();
        codec::encode_string(&mut msg, request_id);
        msg.push(TAG_LOCAL_STORAGE_CLEAR_REQ);
        msg.push(0); // v1
        codec::encode_string(&mut msg, key);
        msg
    }

    fn make_feature_supported_request(request_id: &str, feature_data: &[u8]) -> Vec<u8> {
        let mut msg = Vec::new();
        codec::encode_string(&mut msg, request_id);
        msg.push(TAG_FEATURE_SUPPORTED_REQ);
        msg.push(0); // v1
        msg.extend_from_slice(feature_data);
        msg
    }

    fn make_navigate_request(request_id: &str, url: &str) -> Vec<u8> {
        let mut msg = Vec::new();
        codec::encode_string(&mut msg, request_id);
        msg.push(TAG_NAVIGATE_TO_REQ);
        msg.push(0); // v1
        codec::encode_string(&mut msg, url);
        msg
    }

    fn make_jsonrpc_request(request_id: &str, tag: u8, json: &str) -> Vec<u8> {
        let mut msg = Vec::new();
        codec::encode_string(&mut msg, request_id);
        msg.push(tag);
        msg.push(0); // v1
        codec::encode_string(&mut msg, json);
        msg
    }

    #[test]
    fn handshake_flow() {
        let mut api = HostApi::new();
        let req = make_handshake_request("hs-1");
        let resp = expect_response(api.handle_message(&req, TEST_APP));

        let mut r = codec::Reader::new(&resp);
        assert_eq!(r.read_string().unwrap(), "hs-1");
        assert_eq!(r.read_u8().unwrap(), TAG_HANDSHAKE_RESP);
        assert_eq!(r.read_u8().unwrap(), 0); // v1
        assert_eq!(r.read_u8().unwrap(), 0); // Result::Ok
    }

    #[test]
    fn handshake_wrong_version() {
        let mut api = HostApi::new();
        let mut req = Vec::new();
        codec::encode_string(&mut req, "hs-bad");
        req.push(TAG_HANDSHAKE_REQ);
        req.push(0); // v1
        req.push(255); // wrong version
        let resp = expect_response(api.handle_message(&req, TEST_APP));

        let mut r = codec::Reader::new(&resp);
        assert_eq!(r.read_string().unwrap(), "hs-bad");
        assert_eq!(r.read_u8().unwrap(), TAG_HANDSHAKE_RESP);
        assert_eq!(r.read_u8().unwrap(), 0); // v1
        assert_eq!(r.read_u8().unwrap(), 1); // Result::Err
    }

    #[test]
    fn request_kind_redacts_payload_variants() {
        assert_eq!(
            request_kind(&HostRequest::SignPayload {
                public_key: vec![0xAA; 32],
                payload: b"secret-payload".to_vec(),
            }),
            "sign_payload"
        );
        assert_eq!(
            request_kind(&HostRequest::NavigateTo {
                url: "https://example.com/private".into(),
            }),
            "navigate_to"
        );
        assert_eq!(
            request_kind(&HostRequest::LocalStorageWrite {
                key: "secret".into(),
                value: b"top-secret".to_vec(),
            }),
            "local_storage_write"
        );
    }

    #[test]
    fn decode_error_kind_redacts_error_details() {
        assert_eq!(
            decode_error_kind(&codec::DecodeErr::BadMessage("secret")),
            "bad_message"
        );
        assert_eq!(
            decode_error_kind(&codec::DecodeErr::InvalidTag(255)),
            "invalid_tag"
        );
    }

    #[test]
    fn feature_log_kind_redacts_feature_data() {
        assert_eq!(feature_log_kind(b"signing"), "utf8_known");
        assert_eq!(feature_log_kind(b"secret-feature"), "utf8_other");
        assert_eq!(
            feature_log_kind(&[0, 0xde, 0xad, 0xbe, 0xef]),
            "binary_chain"
        );
        assert_eq!(
            feature_log_kind(&[1, 0xde, 0xad, 0xbe, 0xef]),
            "binary_other"
        );
    }

    #[test]
    fn get_accounts_empty() {
        let mut api = HostApi::new();
        let req = make_get_accounts_request("acc-1");
        let resp = expect_response(api.handle_message(&req, TEST_APP));

        let mut r = codec::Reader::new(&resp);
        assert_eq!(r.read_string().unwrap(), "acc-1");
        assert_eq!(r.read_u8().unwrap(), TAG_GET_NON_PRODUCT_ACCOUNTS_RESP);
        assert_eq!(r.read_u8().unwrap(), 0); // v1
        assert_eq!(r.read_u8().unwrap(), 0); // Result::Ok
        assert_eq!(r.read_compact_u32().unwrap(), 0); // empty vector
    }

    #[test]
    fn get_accounts_returns_configured_accounts() {
        let mut api = HostApi::new();
        api.set_accounts(vec![Account {
            public_key: vec![0xAA; 32],
            name: Some("Test Account".into()),
        }]);

        let req = make_get_accounts_request("acc-2");
        let resp = expect_response(api.handle_message(&req, TEST_APP));

        let mut r = codec::Reader::new(&resp);
        assert_eq!(r.read_string().unwrap(), "acc-2");
        assert_eq!(r.read_u8().unwrap(), TAG_GET_NON_PRODUCT_ACCOUNTS_RESP);
        assert_eq!(r.read_u8().unwrap(), 0); // v1
        assert_eq!(r.read_u8().unwrap(), 0); // Result::Ok
        assert_eq!(r.read_compact_u32().unwrap(), 1); // 1 account
    }

    #[test]
    fn storage_read_returns_needs_storage_read() {
        let mut api = HostApi::new();
        let req = make_storage_read("r-1", "mykey");

        match api.handle_message(&req, TEST_APP) {
            HostApiOutcome::NeedsStorageRead { request_id, key } => {
                assert_eq!(request_id, "r-1");
                assert_eq!(key, "mykey");
            }
            other => panic!("expected NeedsStorageRead, got {}", outcome_name(&other)),
        }
    }

    #[test]
    fn storage_write_returns_needs_storage_write() {
        let mut api = HostApi::new();
        let req = make_storage_write("w-1", "mykey", b"myvalue");

        match api.handle_message(&req, TEST_APP) {
            HostApiOutcome::NeedsStorageWrite {
                request_id,
                key,
                value,
            } => {
                assert_eq!(request_id, "w-1");
                assert_eq!(key, "mykey");
                assert_eq!(value, b"myvalue");
            }
            other => panic!("expected NeedsStorageWrite, got {}", outcome_name(&other)),
        }
    }

    #[test]
    fn storage_clear_returns_needs_storage_clear() {
        let mut api = HostApi::new();
        let req = make_storage_clear("c-1", "clearme");

        match api.handle_message(&req, TEST_APP) {
            HostApiOutcome::NeedsStorageClear { request_id, key } => {
                assert_eq!(request_id, "c-1");
                assert_eq!(key, "clearme");
            }
            other => panic!("expected NeedsStorageClear, got {}", outcome_name(&other)),
        }
    }

    #[test]
    fn storage_clear_of_nonexistent_key_emits_outcome() {
        let mut api = HostApi::new();
        let req = make_storage_clear("c-2", "never-written");

        match api.handle_message(&req, TEST_APP) {
            HostApiOutcome::NeedsStorageClear { request_id, key } => {
                assert_eq!(request_id, "c-2");
                assert_eq!(key, "never-written");
            }
            other => panic!("expected NeedsStorageClear, got {}", outcome_name(&other)),
        }
    }

    #[test]
    fn device_permission_returns_unimplemented_error() {
        let mut api = HostApi::new();
        let mut msg = Vec::new();
        codec::encode_string(&mut msg, "unimp-1");
        msg.push(TAG_DEVICE_PERMISSION_REQ);

        let resp = expect_response(api.handle_message(&msg, TEST_APP));

        let mut r = codec::Reader::new(&resp);
        assert_eq!(r.read_string().unwrap(), "unimp-1");
        assert_eq!(r.read_u8().unwrap(), TAG_DEVICE_PERMISSION_RESP);
        assert_eq!(r.read_u8().unwrap(), 0); // v1
        assert_eq!(r.read_u8().unwrap(), 1); // Result::Err
    }

    #[test]
    fn protocol_layer_passes_through_null_byte_deeplink_host_must_validate() {
        let mut api = HostApi::new();
        let mut msg = Vec::new();
        codec::encode_string(&mut msg, "pn-null");
        msg.push(TAG_PUSH_NOTIFICATION_REQ);
        msg.push(0); // v1
        codec::encode_string(&mut msg, "Alert");
        codec::encode_option_some(&mut msg);
        codec::encode_string(&mut msg, "https://evil.com\x00@good.com");

        match api.handle_message(&msg, TEST_APP) {
            HostApiOutcome::NeedsPushNotification {
                request_id,
                text,
                deeplink,
            } => {
                assert_eq!(request_id, "pn-null");
                assert_eq!(text, "Alert");
                // The protocol passes the deeplink through as-is; host-side
                // URL validation must sanitize if needed.
                assert_eq!(deeplink.as_deref(), Some("https://evil.com\x00@good.com"));
            }
            other => panic!(
                "expected NeedsPushNotification, got {}",
                outcome_name(&other)
            ),
        }
    }

    #[test]
    fn protocol_layer_passes_through_control_char_deeplink_host_must_validate() {
        let mut api = HostApi::new();
        let mut msg = Vec::new();
        codec::encode_string(&mut msg, "pn-ctrl");
        msg.push(TAG_PUSH_NOTIFICATION_REQ);
        msg.push(0); // v1
        codec::encode_string(&mut msg, "Alert");
        codec::encode_option_some(&mut msg);
        codec::encode_string(&mut msg, "https://evil.com/\x07\x08\x1b");

        match api.handle_message(&msg, TEST_APP) {
            HostApiOutcome::NeedsPushNotification {
                request_id,
                text,
                deeplink,
            } => {
                assert_eq!(request_id, "pn-ctrl");
                assert_eq!(text, "Alert");
                assert_eq!(deeplink.as_deref(), Some("https://evil.com/\x07\x08\x1b"));
            }
            other => panic!(
                "expected NeedsPushNotification, got {}",
                outcome_name(&other)
            ),
        }
    }

    #[test]
    fn subscription_stop_returns_silent() {
        let mut api = HostApi::new();
        let mut msg = Vec::new();
        codec::encode_string(&mut msg, "stop-1");
        msg.push(TAG_ACCOUNT_STATUS_STOP);

        expect_silent(api.handle_message(&msg, TEST_APP));
    }

    #[test]
    fn malformed_input_returns_silent() {
        let mut api = HostApi::new();

        // Empty input
        expect_silent(api.handle_message(&[], TEST_APP));

        // Truncated after request_id
        let mut msg = Vec::new();
        codec::encode_string(&mut msg, "trunc");
        expect_silent(api.handle_message(&msg, TEST_APP));
    }

    #[test]
    fn unknown_tag_returns_silent() {
        let mut api = HostApi::new();
        let mut msg = Vec::new();
        codec::encode_string(&mut msg, "unk-1");
        msg.push(0xFF); // unknown tag
        expect_silent(api.handle_message(&msg, TEST_APP));
    }

    #[test]
    fn storage_write_rejects_oversized_value() {
        let mut api = HostApi::new();
        let big_value = vec![0xAA; super::MAX_STORAGE_VALUE_SIZE + 1];
        let req = make_storage_write("w-big", "key", &big_value);
        let resp = expect_response(api.handle_message(&req, TEST_APP));

        let mut r = codec::Reader::new(&resp);
        assert_eq!(r.read_string().unwrap(), "w-big");
        assert_eq!(r.read_u8().unwrap(), TAG_LOCAL_STORAGE_WRITE_RESP);
        assert_eq!(r.read_u8().unwrap(), 0); // v1
        assert_eq!(r.read_u8().unwrap(), 1); // Result::Err
    }

    #[test]
    fn storage_write_rejects_long_key() {
        let mut api = HostApi::new();
        let long_key = "k".repeat(super::MAX_STORAGE_KEY_LENGTH + 1);
        let req = make_storage_write("w-longkey", &long_key, b"v");
        let resp = expect_response(api.handle_message(&req, TEST_APP));

        let mut r = codec::Reader::new(&resp);
        assert_eq!(r.read_string().unwrap(), "w-longkey");
        assert_eq!(r.read_u8().unwrap(), TAG_LOCAL_STORAGE_WRITE_RESP);
        assert_eq!(r.read_u8().unwrap(), 0); // v1
        assert_eq!(r.read_u8().unwrap(), 1); // Result::Err
    }

    #[test]
    fn sign_payload_returns_needs_sign() {
        let mut api = HostApi::new();
        let mut msg = Vec::new();
        codec::encode_string(&mut msg, "sign-1");
        msg.push(TAG_SIGN_PAYLOAD_REQ);
        msg.push(0); // v1
        codec::encode_var_bytes(&mut msg, &[0xAA; 32]); // publicKey
        msg.extend_from_slice(b"payload-data");

        match api.handle_message(&msg, TEST_APP) {
            HostApiOutcome::NeedsSign {
                request_id,
                request_tag,
                public_key,
                payload,
            } => {
                assert_eq!(request_id, "sign-1");
                assert_eq!(request_tag, TAG_SIGN_PAYLOAD_REQ);
                assert_eq!(public_key, vec![0xAA; 32]);
                assert_eq!(payload, b"payload-data");
            }
            _ => panic!("expected NeedsSign"),
        }
    }

    #[test]
    fn sign_raw_returns_needs_sign() {
        let mut api = HostApi::new();
        let mut msg = Vec::new();
        codec::encode_string(&mut msg, "sign-2");
        msg.push(TAG_SIGN_RAW_REQ);
        msg.push(0); // v1
        codec::encode_var_bytes(&mut msg, &[0xBB; 32]); // publicKey
        msg.extend_from_slice(b"raw-bytes");

        match api.handle_message(&msg, TEST_APP) {
            HostApiOutcome::NeedsSign {
                request_id,
                request_tag,
                public_key,
                payload,
            } => {
                assert_eq!(request_id, "sign-2");
                assert_eq!(request_tag, TAG_SIGN_RAW_REQ);
                assert_eq!(public_key, vec![0xBB; 32]);
                assert_eq!(payload, b"raw-bytes");
            }
            _ => panic!("expected NeedsSign"),
        }
    }

    #[test]
    fn logging_redacts_sign_payload_requests() {
        let mut api = HostApi::new();
        let request_id = "req-id-secret-123";
        let payload_secret = "payload-secret-456";
        let pubkey_secret_hex = "abababab";
        let mut msg = Vec::new();
        codec::encode_string(&mut msg, request_id);
        msg.push(TAG_SIGN_PAYLOAD_REQ);
        msg.push(0); // v1
        codec::encode_var_bytes(&mut msg, &[0xAB; 32]);
        msg.extend_from_slice(payload_secret.as_bytes());

        let (outcome, logs) = capture_logs(|| api.handle_message(&msg, TEST_APP));

        match outcome {
            HostApiOutcome::NeedsSign {
                request_id: actual_request_id,
                request_tag,
                public_key,
                payload,
            } => {
                assert_eq!(actual_request_id, request_id);
                assert_eq!(request_tag, TAG_SIGN_PAYLOAD_REQ);
                assert_eq!(public_key, vec![0xAB; 32]);
                assert_eq!(payload, payload_secret.as_bytes());
            }
            other => panic!("expected NeedsSign, got {}", outcome_name(&other)),
        }

        assert_logs_contain(&logs, "request: kind=sign_payload (tag=36)");
        assert_logs_contain(&logs, "sign_payload request (pubkey=32 bytes)");
        assert_logs_do_not_contain(&logs, request_id);
        assert_logs_do_not_contain(&logs, payload_secret);
        assert_logs_do_not_contain(&logs, pubkey_secret_hex);
    }

    #[test]
    fn logging_redacts_sign_raw_requests() {
        let mut api = HostApi::new();
        let request_id = "req-id-secret-raw";
        let raw_secret = "raw-secret-789";
        let mut msg = Vec::new();
        codec::encode_string(&mut msg, request_id);
        msg.push(TAG_SIGN_RAW_REQ);
        msg.push(0); // v1
        codec::encode_var_bytes(&mut msg, &[0xCD; 32]);
        msg.extend_from_slice(raw_secret.as_bytes());

        let (outcome, logs) = capture_logs(|| api.handle_message(&msg, TEST_APP));

        match outcome {
            HostApiOutcome::NeedsSign {
                request_id: actual_request_id,
                request_tag,
                public_key,
                payload,
            } => {
                assert_eq!(actual_request_id, request_id);
                assert_eq!(request_tag, TAG_SIGN_RAW_REQ);
                assert_eq!(public_key, vec![0xCD; 32]);
                assert_eq!(payload, raw_secret.as_bytes());
            }
            other => panic!("expected NeedsSign, got {}", outcome_name(&other)),
        }

        assert_logs_contain(&logs, "request: kind=sign_raw (tag=34)");
        assert_logs_contain(&logs, "sign_raw request (pubkey=32 bytes)");
        assert_logs_do_not_contain(&logs, request_id);
        assert_logs_do_not_contain(&logs, raw_secret);
    }

    #[test]
    fn logging_redacts_navigation_requests() {
        let mut api = HostApi::new();
        let request_id = "req-id-secret-nav";
        let url = "https://example.com/callback?token=nav-secret-123";
        let req = make_navigate_request(request_id, url);

        let (outcome, logs) = capture_logs(|| api.handle_message(&req, TEST_APP));

        match outcome {
            HostApiOutcome::NeedsNavigate {
                request_id: actual_request_id,
                url: actual_url,
            } => {
                assert_eq!(actual_request_id, request_id);
                assert_eq!(actual_url, url);
            }
            other => panic!("expected NeedsNavigate, got {}", outcome_name(&other)),
        }

        assert_logs_contain(&logs, "request: kind=navigate_to (tag=6)");
        assert_logs_contain(&logs, "navigate_to request");
        assert_logs_do_not_contain(&logs, request_id);
        assert_logs_do_not_contain(&logs, "nav-secret-123");
    }

    #[test]
    fn logging_redacts_local_storage_write_requests() {
        let mut api = HostApi::new();
        let request_id = "req-id-secret-storage";
        let key = "storage-secret-key";
        let value = b"storage-secret-value";
        let req = make_storage_write(request_id, key, value);

        let (outcome, logs) = capture_logs(|| api.handle_message(&req, TEST_APP));

        match outcome {
            HostApiOutcome::NeedsStorageWrite {
                request_id: actual_request_id,
                key: actual_key,
                value: actual_value,
            } => {
                assert_eq!(actual_request_id, request_id);
                assert_eq!(actual_key, key);
                assert_eq!(actual_value, value);
            }
            other => panic!("expected NeedsStorageWrite, got {}", outcome_name(&other)),
        }

        assert_logs_contain(&logs, "request: kind=local_storage_write (tag=14)");
        assert_logs_do_not_contain(&logs, request_id);
        assert_logs_do_not_contain(&logs, key);
        assert_logs_do_not_contain(&logs, "storage-secret-value");
    }

    #[test]
    fn logging_redacts_feature_supported_requests() {
        let mut api = HostApi::new();
        let utf8_secret = "feature-secret-utf8";
        let utf8_req =
            make_feature_supported_request("req-id-feature-utf8", utf8_secret.as_bytes());

        let (utf8_outcome, utf8_logs) = capture_logs(|| api.handle_message(&utf8_req, TEST_APP));
        let utf8_resp = expect_response(utf8_outcome);
        let mut utf8_reader = codec::Reader::new(&utf8_resp);
        utf8_reader.read_string().unwrap();
        assert_eq!(utf8_reader.read_u8().unwrap(), TAG_FEATURE_SUPPORTED_RESP);
        utf8_reader.read_u8().unwrap();
        utf8_reader.read_u8().unwrap();
        assert_eq!(utf8_reader.read_u8().unwrap(), 0);
        assert_logs_contain(&utf8_logs, "request: kind=feature_supported (tag=2)");
        assert_logs_contain(&utf8_logs, "feature_supported: feature=utf8_other -> false");
        assert_logs_do_not_contain(&utf8_logs, utf8_secret);

        let binary_req =
            make_feature_supported_request("req-id-feature-binary", &[0, 0xde, 0xad, 0xbe, 0xef]);
        let (binary_outcome, binary_logs) =
            capture_logs(|| api.handle_message(&binary_req, TEST_APP));
        let binary_resp = expect_response(binary_outcome);
        let mut binary_reader = codec::Reader::new(&binary_resp);
        binary_reader.read_string().unwrap();
        assert_eq!(binary_reader.read_u8().unwrap(), TAG_FEATURE_SUPPORTED_RESP);
        binary_reader.read_u8().unwrap();
        binary_reader.read_u8().unwrap();
        assert_eq!(binary_reader.read_u8().unwrap(), 0);
        assert_logs_contain(
            &binary_logs,
            "feature_supported: feature=binary_chain -> false",
        );
        assert_logs_do_not_contain(&binary_logs, "deadbeef");
    }

    #[test]
    fn logging_redacts_jsonrpc_requests() {
        let mut api = HostApi::new();
        let request_id = "req-id-secret-jsonrpc";
        let json = r#"{"jsonrpc":"2.0","id":1,"method":"rpc-secret-method","params":["jsonrpc-secret-param"]}"#;
        let req = make_jsonrpc_request(request_id, TAG_JSONRPC_SEND_REQ, json);

        let (outcome, logs) = capture_logs(|| api.handle_message(&req, TEST_APP));

        match outcome {
            HostApiOutcome::NeedsChainQuery {
                request_id: actual_request_id,
                method,
                params,
            } => {
                assert_eq!(actual_request_id, request_id);
                assert_eq!(method, "rpc-secret-method");
                assert_eq!(params, serde_json::json!(["jsonrpc-secret-param"]));
            }
            other => panic!("expected NeedsChainQuery, got {}", outcome_name(&other)),
        }

        assert_logs_contain(&logs, "request: kind=jsonrpc_send (tag=70)");
        assert_logs_contain(&logs, "jsonrpc_send request");
        assert_logs_do_not_contain(&logs, request_id);
        assert_logs_do_not_contain(&logs, "rpc-secret-method");
        assert_logs_do_not_contain(&logs, "jsonrpc-secret-param");
    }

    #[test]
    fn logging_redacts_jsonrpc_subscribe_requests() {
        let mut api = HostApi::new();
        let request_id = "req-id-secret-jsonrpc-sub";
        let json = r#"{"jsonrpc":"2.0","id":1,"method":"rpc-secret-subscribe","params":["jsonrpc-secret-sub-param"]}"#;
        let req = make_jsonrpc_request(request_id, TAG_JSONRPC_SUB_START, json);

        let (outcome, logs) = capture_logs(|| api.handle_message(&req, TEST_APP));

        match outcome {
            HostApiOutcome::NeedsChainSubscription {
                request_id: actual_request_id,
                method,
                params,
            } => {
                assert_eq!(actual_request_id, request_id);
                assert_eq!(method, "rpc-secret-subscribe");
                assert_eq!(params, serde_json::json!(["jsonrpc-secret-sub-param"]));
            }
            other => panic!(
                "expected NeedsChainSubscription, got {}",
                outcome_name(&other)
            ),
        }

        assert_logs_contain(&logs, "request: kind=jsonrpc_subscribe_start (tag=72)");
        assert_logs_contain(&logs, "jsonrpc_subscribe_start request");
        assert_logs_do_not_contain(&logs, request_id);
        assert_logs_do_not_contain(&logs, "rpc-secret-subscribe");
        assert_logs_do_not_contain(&logs, "jsonrpc-secret-sub-param");
    }

    #[test]
    fn logging_redacts_decode_failures() {
        let mut api = HostApi::new();
        let malformed = b"decode-secret-123";

        let (outcome, logs) = capture_logs(|| api.handle_message(malformed, TEST_APP));

        expect_silent(outcome);
        assert_logs_contain(&logs, "failed to decode message: kind=");
        assert_logs_do_not_contain(&logs, "decode-secret-123");
    }

    // -- Push notification tests --

    fn make_push_notification_request(
        request_id: &str,
        text: &str,
        deeplink: Option<&str>,
    ) -> Vec<u8> {
        let mut msg = Vec::new();
        codec::encode_string(&mut msg, request_id);
        msg.push(TAG_PUSH_NOTIFICATION_REQ);
        msg.push(0); // v1
        codec::encode_string(&mut msg, text);
        match deeplink {
            Some(dl) => {
                codec::encode_option_some(&mut msg);
                codec::encode_string(&mut msg, dl);
            }
            None => codec::encode_option_none(&mut msg),
        }
        msg
    }

    #[test]
    fn push_notification_returns_needs_push_notification() {
        let mut api = HostApi::new();
        let req = make_push_notification_request(
            "pn-1",
            "Transfer complete",
            Some("https://app.example/tx/123"),
        );

        match api.handle_message(&req, TEST_APP) {
            HostApiOutcome::NeedsPushNotification {
                request_id,
                text,
                deeplink,
            } => {
                assert_eq!(request_id, "pn-1");
                assert_eq!(text, "Transfer complete");
                assert_eq!(deeplink.as_deref(), Some("https://app.example/tx/123"));
            }
            other => panic!(
                "expected NeedsPushNotification, got {}",
                outcome_name(&other)
            ),
        }
    }

    #[test]
    fn push_notification_without_deeplink() {
        let mut api = HostApi::new();
        let req = make_push_notification_request("pn-2", "Hello world", None);

        match api.handle_message(&req, TEST_APP) {
            HostApiOutcome::NeedsPushNotification {
                request_id,
                text,
                deeplink,
            } => {
                assert_eq!(request_id, "pn-2");
                assert_eq!(text, "Hello world");
                assert!(deeplink.is_none());
            }
            other => panic!(
                "expected NeedsPushNotification, got {}",
                outcome_name(&other)
            ),
        }
    }

    #[test]
    fn push_notification_rejects_oversized_text() {
        let mut api = HostApi::new();
        let big_text = "x".repeat(super::MAX_PUSH_NOTIFICATION_TEXT_LEN + 1);
        let req = make_push_notification_request("pn-big", &big_text, None);
        let resp = expect_response(api.handle_message(&req, TEST_APP));

        let mut r = codec::Reader::new(&resp);
        assert_eq!(r.read_string().unwrap(), "pn-big");
        assert_eq!(r.read_u8().unwrap(), TAG_PUSH_NOTIFICATION_RESP);
        assert_eq!(r.read_u8().unwrap(), 0); // v1
        assert_eq!(r.read_u8().unwrap(), 1); // Result::Err
        assert_eq!(r.read_u8().unwrap(), 0); // error variant 0
        assert_eq!(r.pos, resp.len(), "no unconsumed bytes expected");
    }

    #[test]
    fn push_notification_accepts_max_length_text() {
        let mut api = HostApi::new();
        let text_at_limit = "x".repeat(super::MAX_PUSH_NOTIFICATION_TEXT_LEN);
        let req = make_push_notification_request("pn-limit", &text_at_limit, None);

        match api.handle_message(&req, TEST_APP) {
            HostApiOutcome::NeedsPushNotification {
                request_id, text, ..
            } => {
                assert_eq!(request_id, "pn-limit");
                assert_eq!(text.len(), super::MAX_PUSH_NOTIFICATION_TEXT_LEN);
            }
            other => panic!(
                "expected NeedsPushNotification for text at limit, got {}",
                outcome_name(&other)
            ),
        }
    }

    #[test]
    fn push_notification_rejects_javascript_deeplink() {
        let mut api = HostApi::new();
        let req = make_push_notification_request("pn-js", "hi", Some("javascript:alert(1)"));
        let resp = expect_response(api.handle_message(&req, TEST_APP));

        let mut r = codec::Reader::new(&resp);
        assert_eq!(r.read_string().unwrap(), "pn-js");
        assert_eq!(r.read_u8().unwrap(), TAG_PUSH_NOTIFICATION_RESP);
        assert_eq!(r.read_u8().unwrap(), 0); // v1
        assert_eq!(r.read_u8().unwrap(), 1); // Result::Err
        assert_eq!(r.read_u8().unwrap(), 0); // error variant 0
        assert_eq!(r.pos, resp.len(), "no unconsumed bytes expected");
    }

    #[test]
    fn push_notification_rejects_file_deeplink() {
        let mut api = HostApi::new();
        let req = make_push_notification_request("pn-file", "hi", Some("file:///etc/passwd"));
        let resp = expect_response(api.handle_message(&req, TEST_APP));

        let mut r = codec::Reader::new(&resp);
        assert_eq!(r.read_string().unwrap(), "pn-file");
        assert_eq!(r.read_u8().unwrap(), TAG_PUSH_NOTIFICATION_RESP);
        assert_eq!(r.read_u8().unwrap(), 0); // v1
        assert_eq!(r.read_u8().unwrap(), 1); // Result::Err
        assert_eq!(r.read_u8().unwrap(), 0); // error variant 0
        assert_eq!(r.pos, resp.len(), "no unconsumed bytes expected");
    }

    #[test]
    fn push_notification_rejects_data_deeplink() {
        let mut api = HostApi::new();
        let req = make_push_notification_request(
            "pn-data",
            "hi",
            Some("data:text/html,<script>alert(1)</script>"),
        );
        let resp = expect_response(api.handle_message(&req, TEST_APP));

        let mut r = codec::Reader::new(&resp);
        assert_eq!(r.read_string().unwrap(), "pn-data");
        assert_eq!(r.read_u8().unwrap(), TAG_PUSH_NOTIFICATION_RESP);
        assert_eq!(r.read_u8().unwrap(), 0); // v1
        assert_eq!(r.read_u8().unwrap(), 1); // Result::Err
        assert_eq!(r.read_u8().unwrap(), 0); // error variant 0
        assert_eq!(r.pos, resp.len(), "no unconsumed bytes expected");
    }

    #[test]
    fn push_notification_rejects_plain_http_deeplink() {
        let mut api = HostApi::new();
        let req =
            make_push_notification_request("pn-http", "hi", Some("http://app.example/tx/123"));
        let resp = expect_response(api.handle_message(&req, TEST_APP));

        let mut r = codec::Reader::new(&resp);
        assert_eq!(r.read_string().unwrap(), "pn-http");
        assert_eq!(r.read_u8().unwrap(), TAG_PUSH_NOTIFICATION_RESP);
        assert_eq!(r.read_u8().unwrap(), 0); // v1
        assert_eq!(r.read_u8().unwrap(), 1); // Result::Err
        assert_eq!(r.read_u8().unwrap(), 0); // error variant 0
        assert_eq!(r.pos, resp.len(), "no unconsumed bytes expected");
    }

    #[test]
    fn push_notification_allows_https_deeplink() {
        let mut api = HostApi::new();
        let req =
            make_push_notification_request("pn-https", "hi", Some("https://app.example/tx/123"));

        match api.handle_message(&req, TEST_APP) {
            HostApiOutcome::NeedsPushNotification {
                request_id,
                deeplink,
                ..
            } => {
                assert_eq!(request_id, "pn-https");
                assert_eq!(deeplink.as_deref(), Some("https://app.example/tx/123"));
            }
            other => panic!(
                "expected NeedsPushNotification, got {}",
                outcome_name(&other)
            ),
        }
    }

    #[test]
    fn push_notification_scheme_check_is_case_insensitive() {
        let mut api = HostApi::new();
        let req = make_push_notification_request("pn-case", "hi", Some("HTTPS://app.example"));

        match api.handle_message(&req, TEST_APP) {
            HostApiOutcome::NeedsPushNotification { request_id, .. } => {
                assert_eq!(request_id, "pn-case");
            }
            other => panic!(
                "expected NeedsPushNotification, got {}",
                outcome_name(&other)
            ),
        }
    }

    #[test]
    fn push_notification_rejects_multibyte_text_exceeding_byte_limit() {
        let mut api = HostApi::new();
        // Each '🦊' is 4 UTF-8 bytes; 257 * 4 = 1028 bytes > 1024.
        let text = "🦊".repeat(257);
        assert_eq!(text.len(), 1028);
        let req = make_push_notification_request("pn-mb-big", &text, None);
        let resp = expect_response(api.handle_message(&req, TEST_APP));

        let mut r = codec::Reader::new(&resp);
        assert_eq!(r.read_string().unwrap(), "pn-mb-big");
        assert_eq!(r.read_u8().unwrap(), TAG_PUSH_NOTIFICATION_RESP);
        assert_eq!(r.read_u8().unwrap(), 0); // v1
        assert_eq!(r.read_u8().unwrap(), 1); // Result::Err
    }

    #[test]
    fn push_notification_accepts_multibyte_text_at_byte_limit() {
        let mut api = HostApi::new();
        // Each '🦊' is 4 UTF-8 bytes; 256 * 4 = 1024 bytes == limit.
        let text = "🦊".repeat(256);
        assert_eq!(text.len(), 1024);
        let req = make_push_notification_request("pn-mb-limit", &text, None);

        match api.handle_message(&req, TEST_APP) {
            HostApiOutcome::NeedsPushNotification {
                request_id,
                text: actual_text,
                ..
            } => {
                assert_eq!(request_id, "pn-mb-limit");
                assert_eq!(actual_text.len(), 1024);
            }
            other => panic!(
                "expected NeedsPushNotification for multibyte text at limit, got {}",
                outcome_name(&other)
            ),
        }
    }

    #[test]
    fn push_notification_rejects_empty_deeplink() {
        let mut api = HostApi::new();
        let req = make_push_notification_request("pn-empty-dl", "hi", Some(""));
        let resp = expect_response(api.handle_message(&req, TEST_APP));

        let mut r = codec::Reader::new(&resp);
        assert_eq!(r.read_string().unwrap(), "pn-empty-dl");
        assert_eq!(r.read_u8().unwrap(), TAG_PUSH_NOTIFICATION_RESP);
        assert_eq!(r.read_u8().unwrap(), 0); // v1
        assert_eq!(r.read_u8().unwrap(), 1); // Result::Err
    }

    #[test]
    fn push_notification_accepts_bare_https_scheme_deeplink() {
        // "https://" with no host passes the scheme check.
        // Host is responsible for further URL validation.
        let mut api = HostApi::new();
        let req = make_push_notification_request("pn-bare", "hi", Some("https://"));
        match api.handle_message(&req, TEST_APP) {
            HostApiOutcome::NeedsPushNotification { request_id, .. } => {
                assert_eq!(request_id, "pn-bare");
            }
            other => panic!(
                "expected NeedsPushNotification for bare https://, got {}",
                outcome_name(&other)
            ),
        }
    }

    #[test]
    fn push_notification_accepts_deeplink_at_byte_limit() {
        let mut api = HostApi::new();
        let base = "https://app.example/";
        let pad = super::MAX_DEEPLINK_URL_LEN - base.len();
        let url = format!("{}{}", base, "a".repeat(pad));
        assert_eq!(url.len(), super::MAX_DEEPLINK_URL_LEN);
        let req = make_push_notification_request("pn-dl-limit", "hi", Some(&url));
        match api.handle_message(&req, TEST_APP) {
            HostApiOutcome::NeedsPushNotification { request_id, .. } => {
                assert_eq!(request_id, "pn-dl-limit");
            }
            other => panic!(
                "expected NeedsPushNotification at deeplink limit, got {}",
                outcome_name(&other)
            ),
        }
    }

    #[test]
    fn push_notification_rejects_oversized_deeplink() {
        let mut api = HostApi::new();
        let long_url = format!(
            "https://app.example/{}",
            "a".repeat(super::MAX_DEEPLINK_URL_LEN)
        );
        let req = make_push_notification_request("pn-dl-long", "hi", Some(&long_url));
        let resp = expect_response(api.handle_message(&req, TEST_APP));

        let mut r = codec::Reader::new(&resp);
        assert_eq!(r.read_string().unwrap(), "pn-dl-long");
        assert_eq!(r.read_u8().unwrap(), TAG_PUSH_NOTIFICATION_RESP);
        assert_eq!(r.read_u8().unwrap(), 0); // v1
        assert_eq!(r.read_u8().unwrap(), 1); // Result::Err
    }

    #[test]
    fn storage_read_rejects_long_key() {
        let mut api = HostApi::new();
        let long_key = "k".repeat(super::MAX_STORAGE_KEY_LENGTH + 1);
        let req = make_storage_read("r-longkey", &long_key);
        let resp = expect_response(api.handle_message(&req, TEST_APP));

        let mut r = codec::Reader::new(&resp);
        assert_eq!(r.read_string().unwrap(), "r-longkey");
        assert_eq!(r.read_u8().unwrap(), TAG_LOCAL_STORAGE_READ_RESP);
        assert_eq!(r.read_u8().unwrap(), 0); // v1
        assert_eq!(r.read_u8().unwrap(), 1); // Result::Err
    }

    #[test]
    fn push_notification_serializes_to_json() {
        let outcome = HostApiOutcome::NeedsPushNotification {
            request_id: "pn-s".into(),
            text: "Hello".into(),
            deeplink: Some("https://app.example".into()),
        };
        let json = serde_json::to_value(&outcome).unwrap();
        assert_eq!(json["type"], "NeedsPushNotification");
        assert_eq!(json["request_id"], "pn-s");
        assert_eq!(json["text"], "Hello");
        assert_eq!(json["deeplink"], "https://app.example");
    }

    #[test]
    fn push_notification_serializes_null_deeplink() {
        let outcome = HostApiOutcome::NeedsPushNotification {
            request_id: "pn-n".into(),
            text: "Hi".into(),
            deeplink: None,
        };
        let json = serde_json::to_value(&outcome).unwrap();
        assert_eq!(json["type"], "NeedsPushNotification");
        assert_eq!(json["deeplink"], serde_json::Value::Null);
    }

    #[test]
    fn feature_supported_push_notification() {
        let mut api = HostApi::new();
        let req = make_feature_supported_request("fs-pn", b"push_notification");
        let resp = expect_response(api.handle_message(&req, TEST_APP));

        let mut r = codec::Reader::new(&resp);
        assert_eq!(r.read_string().unwrap(), "fs-pn");
        assert_eq!(r.read_u8().unwrap(), TAG_FEATURE_SUPPORTED_RESP);
        assert_eq!(r.read_u8().unwrap(), 0); // v1
        assert_eq!(r.read_u8().unwrap(), 0); // Result::Ok
        assert_eq!(r.read_u8().unwrap(), 1); // true
    }

    #[test]
    fn logging_does_not_leak_push_notification_content() {
        let mut api = HostApi::new();
        let request_id = "req-id-secret-pn";
        let text = "notification-secret-text-123";
        let deeplink = "https://secret-deeplink.example/foo";
        let req = make_push_notification_request(request_id, text, Some(deeplink));

        let (outcome, logs) = capture_logs(|| api.handle_message(&req, TEST_APP));

        match outcome {
            HostApiOutcome::NeedsPushNotification {
                request_id: actual_request_id,
                text: actual_text,
                deeplink: actual_deeplink,
            } => {
                assert_eq!(actual_request_id, request_id);
                assert_eq!(actual_text, text);
                assert_eq!(actual_deeplink.as_deref(), Some(deeplink));
            }
            other => panic!(
                "expected NeedsPushNotification, got {}",
                outcome_name(&other)
            ),
        }

        assert_logs_contain(&logs, "request: kind=push_notification (tag=4)");
        assert_logs_contain(&logs, "push_notification request");
        assert_logs_do_not_contain(&logs, request_id);
        assert_logs_do_not_contain(&logs, "notification-secret-text-123");
        assert_logs_do_not_contain(&logs, "secret-deeplink");
    }

    #[test]
    fn storage_clear_rejects_long_key() {
        let mut api = HostApi::new();
        let long_key = "k".repeat(super::MAX_STORAGE_KEY_LENGTH + 1);
        let req = make_storage_clear("c-longkey", &long_key);
        let resp = expect_response(api.handle_message(&req, TEST_APP));

        let mut r = codec::Reader::new(&resp);
        assert_eq!(r.read_string().unwrap(), "c-longkey");
        assert_eq!(r.read_u8().unwrap(), TAG_LOCAL_STORAGE_CLEAR_RESP);
        assert_eq!(r.read_u8().unwrap(), 0); // v1
        assert_eq!(r.read_u8().unwrap(), 1); // Result::Err
    }
}