Skip to main content

hns_wallet_host/
lib.rs

1#![doc = "Fail-closed private ABI-v2 host state for browser and mobile adapters."]
2#![forbid(unsafe_code)]
3
4use std::collections::{BTreeMap, BTreeSet, VecDeque};
5use std::time::{SystemTime, UNIX_EPOCH};
6
7use hns_wallet_ffi::{
8    APPROVAL_SCHEMA_VERSION, ApprovalDecision, ApprovalPrompt, DisconnectReason,
9    HostAuthorityFacts, HostFrame, HostHello, HostPlatform, MAX_METHOD_BYTES, MAX_ORIGIN_BYTES,
10    MAX_PROVIDER_METHODS, MAX_PROVIDER_REQUEST_BYTES, MAX_PUBLIC_ITEMS, MAX_PUBLIC_STRING_BYTES,
11    PROVIDER_SCHEMA_VERSION, ProviderBinding, ProviderCapabilitySnapshot, ProviderEventEnvelope,
12    ProviderEventPayload, ServiceCapability, ServiceErrorCode, ServiceFrame, ServiceHello,
13    ServiceLimits, ServiceRequest, ServiceResponse, SessionEnvelope, WALLET_ABI_VERSION,
14    WalletAuthorityContextRequest, WalletHnsAuthorityContext, WalletRequest, WalletResponse,
15};
16use hns_wallet_types::{
17    AccountId, HostAuthorityHandleId, HostSessionId, ModuleId, PROVIDER_METHOD_WIRE_NAMES,
18    ProviderApprovalId, ProviderRequestId, SyncPhase, WalletAsset, WalletServiceSessionId,
19};
20use serde_json::Value;
21use thiserror::Error;
22
23pub const MAX_AUTHORITIES: usize = 256;
24pub const MAX_PENDING_REQUESTS: usize = 1_024;
25pub const MAX_PENDING_APPROVALS: usize = 128;
26pub const MAX_RECENT_REQUEST_IDS: usize = 4_096;
27pub const MAX_RECENT_PROVIDER_NONCES: usize = 4_096;
28pub const MAX_ISSUED_AUTHORITY_IDS: usize = 4_096;
29pub const MAX_ISSUED_APPROVAL_IDS: usize = 4_096;
30
31const RANDOM_ATTEMPTS: usize = 16;
32
33/// A clock owned by [`WalletHost`]. Implementations must report Unix
34/// milliseconds and must not silently substitute a monotonic-process epoch.
35pub trait Clock {
36    fn now_unix_ms(&self) -> Result<u64, ClockError>;
37}
38
39/// An entropy source owned by [`WalletHost`]. A successful call must fill the
40/// complete destination with cryptographically secure random bytes.
41pub trait Entropy {
42    fn fill_bytes(&mut self, destination: &mut [u8]) -> Result<(), EntropyError>;
43}
44
45#[derive(Clone, Copy, Debug, Eq, Error, PartialEq)]
46pub enum ClockError {
47    #[error("system time is before the Unix epoch")]
48    BeforeUnixEpoch,
49    #[error("trusted wall clock is unavailable")]
50    Unavailable,
51}
52
53#[derive(Clone, Copy, Debug, Eq, Error, PartialEq)]
54pub enum EntropyError {
55    #[error("operating-system entropy is unavailable")]
56    Unavailable,
57}
58
59#[derive(Clone, Copy, Debug, Default)]
60pub struct SystemClock;
61
62impl Clock for SystemClock {
63    fn now_unix_ms(&self) -> Result<u64, ClockError> {
64        let duration = SystemTime::now()
65            .duration_since(UNIX_EPOCH)
66            .map_err(|_| ClockError::BeforeUnixEpoch)?;
67        u64::try_from(duration.as_millis()).map_err(|_| ClockError::Unavailable)
68    }
69}
70
71#[derive(Clone, Copy, Debug, Default)]
72pub struct SystemEntropy;
73
74impl Entropy for SystemEntropy {
75    fn fill_bytes(&mut self, destination: &mut [u8]) -> Result<(), EntropyError> {
76        getrandom::fill(destination).map_err(|_| EntropyError::Unavailable)
77    }
78}
79
80#[derive(Clone, Copy, Debug, Eq, PartialEq)]
81pub enum ConnectionState {
82    AwaitingHello,
83    Ready,
84    Failed,
85}
86
87#[derive(Clone, Copy, Debug, Eq, PartialEq)]
88pub enum AuthorityLifecycle {
89    Detached,
90    Registering,
91    Active { revision: u64 },
92    Replacing { revision: u64 },
93    Revoking { revision: u64 },
94    Stale { revision: u64 },
95}
96
97#[derive(Clone, Debug, Eq, PartialEq)]
98pub struct AuthoritySnapshot {
99    pub facts: HostAuthorityFacts,
100    pub lifecycle: AuthorityLifecycle,
101    pub binding: Option<ProviderBinding>,
102    pub capabilities: Option<ProviderCapabilitySnapshot>,
103}
104
105#[derive(Clone, Debug, Eq, PartialEq)]
106pub struct NegotiatedSession {
107    pub protocol_version: u16,
108    pub platform: HostPlatform,
109    pub host_session_id: HostSessionId,
110    pub service_session_id: WalletServiceSessionId,
111    pub restart_generation: u64,
112    pub capabilities: BTreeSet<ServiceCapability>,
113    pub limits: ServiceLimits,
114}
115
116#[derive(Clone, Debug, PartialEq)]
117pub struct AcceptedResponse {
118    pub request_id: ProviderRequestId,
119    pub response: ServiceResponse,
120}
121
122#[derive(Clone, Debug, Eq, PartialEq)]
123pub struct AcceptedEvent {
124    pub binding: ProviderBinding,
125    pub event_sequence: u64,
126    pub payload: ProviderEventPayload,
127}
128
129#[derive(Clone, Debug, PartialEq)]
130#[allow(
131    clippy::large_enum_variant,
132    reason = "this public output enum preserves its established by-value variant representation for downstream host integrations"
133)]
134pub enum HostOutput {
135    Negotiated(NegotiatedSession),
136    Response(AcceptedResponse),
137    Event(AcceptedEvent),
138}
139
140#[derive(Debug, Error)]
141pub enum HostError {
142    #[error(transparent)]
143    Clock(#[from] ClockError),
144    #[error(transparent)]
145    Entropy(#[from] EntropyError),
146    #[error("clock moved backwards")]
147    ClockRollback,
148    #[error("restart generation must be nonzero and strictly increase")]
149    InvalidRestartGeneration,
150    #[error("random source repeatedly returned a zero or colliding identifier")]
151    RandomIdentityUnavailable,
152    #[error("service hello is required")]
153    HandshakeRequired,
154    #[error("the host/service channel has failed and must be restarted")]
155    ChannelFailed,
156    #[error("unexpected service hello")]
157    UnexpectedHello,
158    #[error("service hello does not exactly match the host negotiation")]
159    HelloMismatch,
160    #[error("required negotiated service capability is absent")]
161    CapabilityUnavailable,
162    #[error("request is not in the exact HNS read-operations-v1 surface")]
163    InvalidHnsReadRequest,
164    #[error("request is not a valid native HNS wallet authority-context claim")]
165    InvalidHnsWalletAuthorityRequest,
166    #[error("pending request capacity is exhausted")]
167    PendingRequestCapacity,
168    #[error("authority capacity is exhausted")]
169    AuthorityCapacity,
170    #[error("authority identifier lifetime capacity is exhausted")]
171    AuthorityIdentityCapacity,
172    #[error("pending approval capacity is exhausted")]
173    ApprovalCapacity,
174    #[error("approval identifier lifetime capacity is exhausted")]
175    ApprovalIdentityCapacity,
176    #[error("channel sequence is exhausted")]
177    SequenceExhausted,
178    #[error("invalid host-owned authority facts")]
179    InvalidAuthorityFacts,
180    #[error("host-owned authority facts have expired")]
181    AuthorityExpired,
182    #[error("authority is unknown")]
183    AuthorityUnknown,
184    #[error("authority lifecycle does not permit this operation")]
185    AuthorityLifecycle,
186    #[error("authority or provider binding is stale")]
187    StaleBinding,
188    #[error("provider method is not present in the current exact capability snapshot")]
189    MethodUnavailable,
190    #[error("provider request is malformed or exceeds its ABI bound")]
191    InvalidProviderRequest,
192    #[error("pending request is unknown, duplicated, or stale")]
193    PendingRequestMismatch,
194    #[error("service response class does not match its request")]
195    ResponseClassMismatch,
196    #[error("service frame session does not exactly match the negotiated session")]
197    SessionMismatch,
198    #[error("service channel sequence mismatch: expected {expected}, received {received}")]
199    SequenceMismatch { expected: u64, received: u64 },
200    #[error("provider capability snapshot is not exact")]
201    InvalidCapabilitySnapshot,
202    #[error("approval is unknown, mismatched, already decided, or stale")]
203    ApprovalMismatch,
204    #[error("approval has expired")]
205    ApprovalExpired,
206    #[error("provider event binding is not current")]
207    EventBindingMismatch,
208    #[error("provider event is stale or replayed")]
209    EventReplay,
210    #[error("service reported a protocol-level failure")]
211    ReportedProtocolFailure,
212    #[error("JSON sizing failed")]
213    Encoding,
214}
215
216#[derive(Clone)]
217enum AuthorityPhase {
218    Detached,
219    Registering,
220    Active {
221        revision: u64,
222    },
223    Replacing {
224        revision: u64,
225        replacement: HostAuthorityFacts,
226    },
227    Revoking {
228        revision: u64,
229    },
230    Stale {
231        revision: u64,
232    },
233}
234
235#[derive(Clone)]
236struct AuthorityState {
237    facts: HostAuthorityFacts,
238    phase: AuthorityPhase,
239    binding: Option<ProviderBinding>,
240    capabilities: Option<ProviderCapabilitySnapshot>,
241}
242
243#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
244struct EventCursorKey {
245    authority_handle: HostAuthorityHandleId,
246    authority_revision: u64,
247    wallet_session_id: hns_wallet_types::WalletSessionId,
248    permission_generation: u64,
249}
250
251impl EventCursorKey {
252    fn from_binding(binding: ProviderBinding) -> Self {
253        Self {
254            authority_handle: binding.authority_handle,
255            authority_revision: binding.authority_revision,
256            wallet_session_id: binding.wallet_session_id,
257            permission_generation: binding.permission_generation,
258        }
259    }
260}
261
262#[derive(Clone, Copy)]
263enum ApprovalPhase {
264    Available,
265    Deciding { request_id: ProviderRequestId },
266}
267
268#[derive(Clone)]
269struct HostApproval {
270    prompt: ApprovalPrompt,
271    phase: ApprovalPhase,
272}
273
274#[derive(Clone)]
275enum RequestClass {
276    Register {
277        handle: HostAuthorityHandleId,
278    },
279    Replace {
280        handle: HostAuthorityHandleId,
281        expected_revision: u64,
282        replacement: HostAuthorityFacts,
283    },
284    Revoke {
285        handle: HostAuthorityHandleId,
286        expected_revision: u64,
287    },
288    Capabilities {
289        handle: HostAuthorityHandleId,
290        revision: u64,
291    },
292    Provider {
293        handle: HostAuthorityHandleId,
294        revision: u64,
295        method: String,
296    },
297    Approval {
298        handle: HostAuthorityHandleId,
299        revision: u64,
300        approval_id: ProviderApprovalId,
301        decision: ApprovalDecision,
302        method: String,
303    },
304    Wallet(WalletResponseClass),
305    HnsRead(HnsReadResponseClass),
306    HnsWalletAuthority(HnsWalletAuthorityResponseClass),
307}
308
309impl RequestClass {
310    fn authority(&self) -> Option<HostAuthorityHandleId> {
311        match self {
312            Self::Register { handle }
313            | Self::Replace { handle, .. }
314            | Self::Revoke { handle, .. }
315            | Self::Capabilities { handle, .. }
316            | Self::Provider { handle, .. }
317            | Self::Approval { handle, .. } => Some(*handle),
318            Self::Wallet(_) | Self::HnsRead(_) | Self::HnsWalletAuthority(_) => None,
319        }
320    }
321}
322
323#[derive(Clone, Copy)]
324struct HnsWalletAuthorityResponseClass {
325    request: WalletAuthorityContextRequest,
326}
327
328impl HnsWalletAuthorityResponseClass {
329    fn for_request(request: WalletAuthorityContextRequest) -> Result<Self, HostError> {
330        let WalletAuthorityContextRequest::CurrentHnsContext {
331            network,
332            network_magic,
333            namespace_id,
334            namespace_lease_generation,
335            module,
336        } = request;
337        if network_magic != network.magic()
338            || namespace_id.iter().all(|byte| *byte == 0)
339            || namespace_lease_generation == 0
340            || module != ModuleId::Handshake
341        {
342            return Err(HostError::InvalidHnsWalletAuthorityRequest);
343        }
344        Ok(Self { request })
345    }
346
347    fn matches(self, context: &WalletHnsAuthorityContext) -> bool {
348        let WalletAuthorityContextRequest::CurrentHnsContext {
349            network,
350            network_magic,
351            namespace_id,
352            namespace_lease_generation,
353            module,
354        } = self.request;
355        context.network == network
356            && context.network_magic == network_magic
357            && context.namespace_id == namespace_id
358            && context.namespace_lease_generation == namespace_lease_generation
359            && context.active_wallet.as_bytes() != &[0_u8; 16]
360            && context.account.as_bytes() != &[0_u8; 16]
361            && context.wallet_authority_revision != 0
362            && context.account_authority_revision != 0
363            && !context.locked
364            && context.module == module
365            && context.persistent_wallet_confirmed
366            && !context.recovery_pending
367            && !context.retirement_pending
368            && context.hns_reads_ready
369    }
370}
371
372#[derive(Clone, Copy)]
373enum HnsReadResponseClass {
374    Status,
375    Accounts,
376    Balance,
377    ReceiveTarget { account: AccountId },
378    Transactions,
379    ModuleStatus,
380}
381
382impl HnsReadResponseClass {
383    fn for_request(request: &WalletRequest) -> Result<Self, HostError> {
384        match request {
385            WalletRequest::Status => Ok(Self::Status),
386            WalletRequest::ListAccounts => Ok(Self::Accounts),
387            WalletRequest::Balance {
388                module: ModuleId::Handshake,
389                ..
390            } => Ok(Self::Balance),
391            WalletRequest::ReceiveTarget {
392                module: ModuleId::Handshake,
393                account,
394            } => Ok(Self::ReceiveTarget { account: *account }),
395            WalletRequest::TransactionHistory {
396                module: ModuleId::Handshake,
397                ..
398            } => Ok(Self::Transactions),
399            WalletRequest::ModuleStatus {
400                module: ModuleId::Handshake,
401            } => Ok(Self::ModuleStatus),
402            _ => Err(HostError::InvalidHnsReadRequest),
403        }
404    }
405
406    fn matches(self, response: &WalletResponse) -> bool {
407        match (self, response) {
408            (Self::Status, WalletResponse::Status { status }) => {
409                !status.mainnet_settlement_enabled
410                    && status.locked == status.active_wallet.is_none()
411                    && status
412                        .active_wallet
413                        .is_none_or(|wallet| wallet.as_bytes() != &[0_u8; 16])
414                    && status.enabled_modules.len() <= 1
415                    && status
416                        .enabled_modules
417                        .iter()
418                        .all(|module| *module == ModuleId::Handshake)
419            }
420            (Self::Accounts, WalletResponse::Accounts { accounts }) => {
421                matches!(accounts.as_slice(), [account]
422                    if account.module == ModuleId::Handshake
423                        && account.account_id.as_bytes() != &[0_u8; 16]
424                        && !account.label.is_empty()
425                        && account.label.len() <= MAX_PUBLIC_STRING_BYTES
426                        && account
427                            .label
428                            .bytes()
429                            .all(|byte| (0x20..=0x7e).contains(&byte))
430                        && account.receive_display.is_none())
431            }
432            (Self::Balance, WalletResponse::Balance { amount }) => amount.asset == WalletAsset::Hns,
433            (Self::ReceiveTarget { account }, WalletResponse::ReceiveTarget { target }) => {
434                target.module == ModuleId::Handshake
435                    && target.account == account
436                    && !target.display.is_empty()
437                    && target.display.len() <= 512
438                    && target
439                        .display
440                        .bytes()
441                        .all(|byte| (0x21..=0x7e).contains(&byte))
442            }
443            (Self::Transactions, WalletResponse::TransactionHistory { transactions }) => {
444                let mut txids = BTreeSet::new();
445                transactions.iter().all(|transaction| {
446                    transaction.module == ModuleId::Handshake
447                        && transaction.txid.as_bytes() != &[0_u8; 32]
448                        && !(transaction.net_amount.negative
449                            && transaction.net_amount.magnitude.is_zero())
450                        && txids.insert(transaction.txid)
451                })
452            }
453            (Self::ModuleStatus, WalletResponse::ModuleStatus { status }) => {
454                status.phase == SyncPhase::Ready
455                    && status.validated_height == status.scanned_height
456                    && status.target_height == Some(status.validated_height)
457                    && status.last_error.is_none()
458            }
459            _ => false,
460        }
461    }
462}
463
464#[derive(Clone, Copy)]
465enum WalletResponseClass {
466    Status,
467    Create,
468    Restore,
469    Unlock,
470    Lock,
471    Accounts,
472    Balance,
473    ReceiveTarget,
474    Transactions,
475    ModuleStatus,
476    Workflow,
477}
478
479impl WalletResponseClass {
480    fn for_request(request: &WalletRequest) -> Self {
481        match request {
482            WalletRequest::Status => Self::Status,
483            WalletRequest::CreateWallet { .. } => Self::Create,
484            WalletRequest::RestoreWallet { .. } => Self::Restore,
485            WalletRequest::Unlock { .. } => Self::Unlock,
486            WalletRequest::Lock => Self::Lock,
487            WalletRequest::ListAccounts => Self::Accounts,
488            WalletRequest::Balance { .. } => Self::Balance,
489            WalletRequest::ReceiveTarget { .. } => Self::ReceiveTarget,
490            WalletRequest::TransactionHistory { .. } => Self::Transactions,
491            WalletRequest::ModuleStatus { .. } => Self::ModuleStatus,
492            WalletRequest::WorkflowStatus { .. } => Self::Workflow,
493        }
494    }
495
496    fn matches(self, response: &WalletResponse) -> bool {
497        matches!(
498            (self, response),
499            (Self::Status, WalletResponse::Status { .. })
500                | (Self::Create, WalletResponse::WalletCreated { .. })
501                | (Self::Restore, WalletResponse::WalletRestored { .. })
502                | (Self::Unlock, WalletResponse::Unlocked)
503                | (Self::Lock, WalletResponse::Locked)
504                | (Self::Accounts, WalletResponse::Accounts { .. })
505                | (Self::Balance, WalletResponse::Balance { .. })
506                | (Self::ReceiveTarget, WalletResponse::ReceiveTarget { .. })
507                | (
508                    Self::Transactions,
509                    WalletResponse::TransactionHistory { .. }
510                )
511                | (Self::ModuleStatus, WalletResponse::ModuleStatus { .. })
512                | (Self::Workflow, WalletResponse::Workflow { .. })
513        )
514    }
515}
516
517struct SessionState {
518    service_session_id: WalletServiceSessionId,
519    capabilities: BTreeSet<ServiceCapability>,
520    next_host_sequence: u64,
521    next_service_sequence: u64,
522}
523
524enum ChannelState {
525    AwaitingHello,
526    Ready(SessionState),
527    Failed,
528}
529
530struct QueuedRequest {
531    request_id: ProviderRequestId,
532    frame: HostFrame,
533}
534
535/// Process-local host state. It deliberately does not implement `Clone` or
536/// serialization: session, authority, approval, and replay state must not be
537/// persisted or projected into a website context.
538pub struct WalletHost<C, E> {
539    platform: HostPlatform,
540    host_session_id: HostSessionId,
541    restart_generation: u64,
542    clock: C,
543    entropy: E,
544    last_now_unix_ms: Option<u64>,
545    channel: ChannelState,
546    pending: BTreeMap<ProviderRequestId, RequestClass>,
547    recent_request_ids: BTreeSet<ProviderRequestId>,
548    request_id_order: VecDeque<ProviderRequestId>,
549    aged_out_request_ids: BTreeSet<ProviderRequestId>,
550    recent_nonces: BTreeSet<(HostAuthorityHandleId, u64)>,
551    nonce_order: VecDeque<(HostAuthorityHandleId, u64)>,
552    authorities: BTreeMap<HostAuthorityHandleId, AuthorityState>,
553    issued_authority_ids: BTreeSet<HostAuthorityHandleId>,
554    approvals: BTreeMap<ProviderApprovalId, HostApproval>,
555    issued_approval_ids: BTreeSet<ProviderApprovalId>,
556    event_cursors: BTreeMap<EventCursorKey, u64>,
557}
558
559impl WalletHost<SystemClock, SystemEntropy> {
560    pub fn new_system(platform: HostPlatform, restart_generation: u64) -> Result<Self, HostError> {
561        Self::new(platform, restart_generation, SystemClock, SystemEntropy)
562    }
563}
564
565impl<C: Clock, E: Entropy> WalletHost<C, E> {
566    pub fn new(
567        platform: HostPlatform,
568        restart_generation: u64,
569        clock: C,
570        mut entropy: E,
571    ) -> Result<Self, HostError> {
572        if restart_generation == 0 {
573            return Err(HostError::InvalidRestartGeneration);
574        }
575        let host_session_id = random_host_session(&mut entropy)?;
576        Ok(Self {
577            platform,
578            host_session_id,
579            restart_generation,
580            clock,
581            entropy,
582            last_now_unix_ms: None,
583            channel: ChannelState::AwaitingHello,
584            pending: BTreeMap::new(),
585            recent_request_ids: BTreeSet::new(),
586            request_id_order: VecDeque::new(),
587            aged_out_request_ids: BTreeSet::new(),
588            recent_nonces: BTreeSet::new(),
589            nonce_order: VecDeque::new(),
590            authorities: BTreeMap::new(),
591            issued_authority_ids: BTreeSet::new(),
592            approvals: BTreeMap::new(),
593            issued_approval_ids: BTreeSet::new(),
594            event_cursors: BTreeMap::new(),
595        })
596    }
597
598    pub const fn platform(&self) -> HostPlatform {
599        self.platform
600    }
601
602    pub const fn host_session_id(&self) -> HostSessionId {
603        self.host_session_id
604    }
605
606    pub const fn restart_generation(&self) -> u64 {
607        self.restart_generation
608    }
609
610    pub fn connection_state(&self) -> ConnectionState {
611        match &self.channel {
612            ChannelState::AwaitingHello => ConnectionState::AwaitingHello,
613            ChannelState::Ready(_) => ConnectionState::Ready,
614            ChannelState::Failed => ConnectionState::Failed,
615        }
616    }
617
618    pub fn hello_frame(&self) -> Result<HostFrame, HostError> {
619        match &self.channel {
620            ChannelState::AwaitingHello => Ok(HostFrame::Hello {
621                hello: HostHello {
622                    protocol_version: WALLET_ABI_VERSION,
623                    platform: self.platform,
624                    host_session_id: self.host_session_id,
625                    restart_generation: self.restart_generation,
626                },
627            }),
628            ChannelState::Ready(_) => Err(HostError::UnexpectedHello),
629            ChannelState::Failed => Err(HostError::ChannelFailed),
630        }
631    }
632
633    /// Starts negotiation for a newer service process while retaining the
634    /// random host session. All service-derived state is invalidated first.
635    pub fn restart(&mut self, restart_generation: u64) -> Result<HostFrame, HostError> {
636        if restart_generation == 0 || restart_generation <= self.restart_generation {
637            return Err(HostError::InvalidRestartGeneration);
638        }
639        self.invalidate_service_state();
640        self.restart_generation = restart_generation;
641        self.channel = ChannelState::AwaitingHello;
642        self.hello_frame()
643    }
644
645    /// Starts a completely fresh host session. The supplied restart generation
646    /// is scoped to the new random session and therefore need only be nonzero.
647    pub fn reset(&mut self, restart_generation: u64) -> Result<HostFrame, HostError> {
648        if restart_generation == 0 {
649            return Err(HostError::InvalidRestartGeneration);
650        }
651        let host_session_id = random_host_session(&mut self.entropy)?;
652        self.invalidate_service_state();
653        self.host_session_id = host_session_id;
654        self.restart_generation = restart_generation;
655        self.last_now_unix_ms = None;
656        self.recent_request_ids.clear();
657        self.request_id_order.clear();
658        self.aged_out_request_ids.clear();
659        self.recent_nonces.clear();
660        self.nonce_order.clear();
661        self.issued_approval_ids.clear();
662        self.channel = ChannelState::AwaitingHello;
663        self.hello_frame()
664    }
665
666    pub fn negotiated_session(&self) -> Option<NegotiatedSession> {
667        let ChannelState::Ready(session) = &self.channel else {
668            return None;
669        };
670        Some(NegotiatedSession {
671            protocol_version: WALLET_ABI_VERSION,
672            platform: self.platform,
673            host_session_id: self.host_session_id,
674            service_session_id: session.service_session_id,
675            restart_generation: self.restart_generation,
676            capabilities: session.capabilities.clone(),
677            limits: ServiceLimits::default(),
678        })
679    }
680
681    pub fn authority(&self, handle: HostAuthorityHandleId) -> Option<AuthoritySnapshot> {
682        self.authorities
683            .get(&handle)
684            .map(|state| AuthoritySnapshot {
685                facts: state.facts.clone(),
686                lifecycle: lifecycle(&state.phase),
687                binding: state.binding,
688                capabilities: state.capabilities.clone(),
689            })
690    }
691
692    /// Forgets host facts that can no longer authorize work. A live,
693    /// non-expired authority must use the correlated revoke operation instead.
694    pub fn discard_authority(&mut self, handle: HostAuthorityHandleId) -> Result<(), HostError> {
695        let now = self.now()?;
696        let discardable = {
697            let state = self
698                .authorities
699                .get(&handle)
700                .ok_or(HostError::AuthorityUnknown)?;
701            matches!(
702                &state.phase,
703                AuthorityPhase::Detached | AuthorityPhase::Stale { .. }
704            ) || state.facts.valid_until_unix_ms <= now
705        };
706        if !discardable {
707            return Err(HostError::AuthorityLifecycle);
708        }
709        let cancelled = self
710            .pending
711            .iter()
712            .filter_map(|(request_id, class)| {
713                (class.authority() == Some(handle)).then_some(*request_id)
714            })
715            .collect::<Vec<_>>();
716        for request_id in cancelled {
717            self.pending.remove(&request_id);
718            if self.aged_out_request_ids.remove(&request_id) {
719                self.recent_request_ids.remove(&request_id);
720            }
721        }
722        self.invalidate_authority_derived(handle);
723        self.authorities.remove(&handle);
724        Ok(())
725    }
726
727    pub fn approval(
728        &mut self,
729        approval_id: ProviderApprovalId,
730    ) -> Result<ApprovalPrompt, HostError> {
731        let now = self.now()?;
732        let approval = self
733            .approvals
734            .get(&approval_id)
735            .ok_or(HostError::ApprovalMismatch)?;
736        if approval.prompt.expires_at_unix_ms <= now {
737            self.approvals.remove(&approval_id);
738            return Err(HostError::ApprovalExpired);
739        }
740        if !matches!(approval.phase, ApprovalPhase::Available) {
741            return Err(HostError::ApprovalMismatch);
742        }
743        Ok(approval.prompt.clone())
744    }
745
746    /// Registers facts supplied by the trusted engine/mobile policy boundary.
747    /// The returned handle is private host state and must never be page input.
748    pub fn register_authority(
749        &mut self,
750        facts: HostAuthorityFacts,
751    ) -> Result<(HostAuthorityHandleId, HostFrame), HostError> {
752        self.require_capability(ServiceCapability::OpaqueAuthorityRegistry)?;
753        if self.authorities.len() >= MAX_AUTHORITIES {
754            return Err(HostError::AuthorityCapacity);
755        }
756        if self.issued_authority_ids.len() >= MAX_ISSUED_AUTHORITY_IDS {
757            return Err(HostError::AuthorityIdentityCapacity);
758        }
759        let now = self.now()?;
760        validate_authority_facts(&facts, now)?;
761        let handle = self.random_authority_handle()?;
762        let queued = self.enqueue(
763            ServiceRequest::RegisterAuthority {
764                authority_handle: handle,
765                authority: facts.clone(),
766            },
767            RequestClass::Register { handle },
768        )?;
769        self.issued_authority_ids.insert(handle);
770        self.authorities.insert(
771            handle,
772            AuthorityState {
773                facts,
774                phase: AuthorityPhase::Registering,
775                binding: None,
776                capabilities: None,
777            },
778        );
779        Ok((handle, queued.frame))
780    }
781
782    /// Re-registers preserved host facts after [`Self::restart`] or
783    /// [`Self::reset`]. Service revisions always begin again at exactly one.
784    pub fn register_detached_authority(
785        &mut self,
786        handle: HostAuthorityHandleId,
787    ) -> Result<HostFrame, HostError> {
788        self.require_capability(ServiceCapability::OpaqueAuthorityRegistry)?;
789        let now = self.now()?;
790        let facts = {
791            let state = self
792                .authorities
793                .get(&handle)
794                .ok_or(HostError::AuthorityUnknown)?;
795            if !matches!(&state.phase, AuthorityPhase::Detached) {
796                return Err(HostError::AuthorityLifecycle);
797            }
798            validate_authority_facts(&state.facts, now)?;
799            state.facts.clone()
800        };
801        let queued = self.enqueue(
802            ServiceRequest::RegisterAuthority {
803                authority_handle: handle,
804                authority: facts,
805            },
806            RequestClass::Register { handle },
807        )?;
808        self.authorities
809            .get_mut(&handle)
810            .ok_or(HostError::AuthorityUnknown)?
811            .phase = AuthorityPhase::Registering;
812        Ok(queued.frame)
813    }
814
815    pub fn replace_authority(
816        &mut self,
817        handle: HostAuthorityHandleId,
818        replacement: HostAuthorityFacts,
819    ) -> Result<HostFrame, HostError> {
820        self.require_capability(ServiceCapability::OpaqueAuthorityRegistry)?;
821        let now = self.now()?;
822        validate_authority_facts(&replacement, now)?;
823        let (revision, current) = {
824            let state = self.active_authority(handle, now)?;
825            let revision = active_revision(state)?;
826            (revision, state.facts.clone())
827        };
828        validate_replacement(&current, &replacement)?;
829        let queued = self.enqueue(
830            ServiceRequest::ReplaceAuthority {
831                authority_handle: handle,
832                expected_authority_revision: revision,
833                authority: replacement.clone(),
834            },
835            RequestClass::Replace {
836                handle,
837                expected_revision: revision,
838                replacement: replacement.clone(),
839            },
840        )?;
841        self.invalidate_authority_derived(handle);
842        let state = self
843            .authorities
844            .get_mut(&handle)
845            .ok_or(HostError::AuthorityUnknown)?;
846        state.phase = AuthorityPhase::Replacing {
847            revision,
848            replacement,
849        };
850        Ok(queued.frame)
851    }
852
853    pub fn revoke_authority(
854        &mut self,
855        handle: HostAuthorityHandleId,
856    ) -> Result<HostFrame, HostError> {
857        self.require_capability(ServiceCapability::OpaqueAuthorityRegistry)?;
858        let now = self.now()?;
859        let revision = {
860            let state = self.active_authority(handle, now)?;
861            active_revision(state)?
862        };
863        let queued = self.enqueue(
864            ServiceRequest::RevokeAuthority {
865                authority_handle: handle,
866                expected_authority_revision: revision,
867            },
868            RequestClass::Revoke {
869                handle,
870                expected_revision: revision,
871            },
872        )?;
873        self.invalidate_authority_derived(handle);
874        self.authorities
875            .get_mut(&handle)
876            .ok_or(HostError::AuthorityUnknown)?
877            .phase = AuthorityPhase::Revoking { revision };
878        Ok(queued.frame)
879    }
880
881    pub fn request_provider_capabilities(
882        &mut self,
883        handle: HostAuthorityHandleId,
884    ) -> Result<HostFrame, HostError> {
885        self.require_capability(ServiceCapability::OpaqueAuthorityRegistry)?;
886        let now = self.now()?;
887        let revision = active_revision(self.active_authority(handle, now)?)?;
888        let queued = self.enqueue(
889            ServiceRequest::ProviderCapabilities {
890                authority_handle: handle,
891                authority_revision: revision,
892            },
893            RequestClass::Capabilities { handle, revision },
894        )?;
895        Ok(queued.frame)
896    }
897
898    pub fn provider_request(
899        &mut self,
900        handle: HostAuthorityHandleId,
901        method: String,
902        params: Value,
903    ) -> Result<HostFrame, HostError> {
904        self.require_capability(ServiceCapability::ProviderDispatch)?;
905        let now = self.now()?;
906        let revision = {
907            let state = self.active_authority(handle, now)?;
908            let revision = active_revision(state)?;
909            let binding = state.binding.ok_or(HostError::StaleBinding)?;
910            let capabilities = state.capabilities.as_ref().ok_or(HostError::StaleBinding)?;
911            if binding.authority_handle != handle
912                || binding.authority_revision != revision
913                || capabilities.wallet_session_id != binding.wallet_session_id
914                || capabilities.permission_generation != binding.permission_generation
915            {
916                return Err(HostError::StaleBinding);
917            }
918            if !capabilities.methods.contains(&method) {
919                return Err(HostError::MethodUnavailable);
920            }
921            revision
922        };
923        validate_provider_request(&method, &params)?;
924        if value_movement_method(&method) {
925            self.require_capability(ServiceCapability::ValueMovement)?;
926        }
927        let nonce = self.random_provider_nonce(handle)?;
928        let queued = self.enqueue(
929            ServiceRequest::ProviderRequest {
930                authority_handle: handle,
931                authority_revision: revision,
932                request_nonce: nonce,
933                method: method.clone(),
934                params,
935            },
936            RequestClass::Provider {
937                handle,
938                revision,
939                method,
940            },
941        )?;
942        self.remember_nonce(handle, nonce);
943        Ok(queued.frame)
944    }
945
946    pub fn decide_approval(
947        &mut self,
948        approval_id: ProviderApprovalId,
949        decision: ApprovalDecision,
950    ) -> Result<HostFrame, HostError> {
951        self.require_capability(ServiceCapability::StructuredApprovals)?;
952        let now = self.now()?;
953        let (binding, origin, method) = {
954            let approval = self
955                .approvals
956                .get(&approval_id)
957                .ok_or(HostError::ApprovalMismatch)?;
958            if approval.prompt.expires_at_unix_ms <= now {
959                return Err(HostError::ApprovalExpired);
960            }
961            if !matches!(approval.phase, ApprovalPhase::Available) {
962                return Err(HostError::ApprovalMismatch);
963            }
964            (
965                approval.prompt.binding,
966                approval.prompt.origin.clone(),
967                approval.prompt.method.clone(),
968            )
969        };
970        let handle = binding.authority_handle;
971        let revision = binding.authority_revision;
972        let state = self.active_authority(handle, now)?;
973        if active_revision(state)? != revision
974            || state.binding != Some(binding)
975            || state.facts.origin != origin
976        {
977            return Err(HostError::ApprovalMismatch);
978        }
979        let queued = self.enqueue(
980            ServiceRequest::ApprovalDecision {
981                authority_handle: handle,
982                authority_revision: revision,
983                approval_id,
984                decision,
985            },
986            RequestClass::Approval {
987                handle,
988                revision,
989                approval_id,
990                decision,
991                method,
992            },
993        )?;
994        self.approvals
995            .get_mut(&approval_id)
996            .ok_or(HostError::ApprovalMismatch)?
997            .phase = ApprovalPhase::Deciding {
998            request_id: queued.request_id,
999        };
1000        Ok(queued.frame)
1001    }
1002
1003    pub fn wallet_request(&mut self, request: WalletRequest) -> Result<HostFrame, HostError> {
1004        self.require_capability(ServiceCapability::WalletOperations)?;
1005        let class = WalletResponseClass::for_request(&request);
1006        let queued = self.enqueue(
1007            ServiceRequest::Wallet { request },
1008            RequestClass::Wallet(class),
1009        )?;
1010        Ok(queued.frame)
1011    }
1012
1013    /// Issues one request from the exact private non-value HNS read surface.
1014    ///
1015    /// This path deliberately remains separate from [`Self::wallet_request`]:
1016    /// existing trusted mobile/control callers retain the coarse ABI-v2 API,
1017    /// while a browser-native read adapter can require the frozen v1 marker
1018    /// and reject secrets, lifecycle controls, workflows, and other modules
1019    /// before allocating a request identifier.
1020    pub fn hns_read_request(&mut self, request: WalletRequest) -> Result<HostFrame, HostError> {
1021        self.require_capability(ServiceCapability::WalletOperations)?;
1022        self.require_capability(ServiceCapability::HnsReadOperationsV1)?;
1023        let class = HnsReadResponseClass::for_request(&request)?;
1024        let queued = self.enqueue(
1025            ServiceRequest::Wallet { request },
1026            RequestClass::HnsRead(class),
1027        )?;
1028        Ok(queued.frame)
1029    }
1030
1031    /// Issue the additive native-only wallet authority-context request.
1032    ///
1033    /// The returned service value remains evidence only. A product consumer
1034    /// must join it to an independently held namespace lease guard and re-read
1035    /// it around dependent use; this host does not manufacture that guard.
1036    pub fn hns_wallet_authority_context_request(
1037        &mut self,
1038        request: WalletAuthorityContextRequest,
1039    ) -> Result<HostFrame, HostError> {
1040        self.require_capability(ServiceCapability::WalletOperations)?;
1041        self.require_capability(ServiceCapability::HnsReadOperationsV1)?;
1042        self.require_capability(ServiceCapability::HnsWalletAuthorityContextV1)?;
1043        let class = HnsWalletAuthorityResponseClass::for_request(request)?;
1044        let queued = self.enqueue(
1045            ServiceRequest::WalletAuthority { request },
1046            RequestClass::HnsWalletAuthority(class),
1047        )?;
1048        Ok(queued.frame)
1049    }
1050
1051    /// Accepts one already-decoded private service frame. Any validation
1052    /// failure poisons the channel and clears every service-derived value;
1053    /// callers must explicitly start a new generation.
1054    pub fn accept_service_frame(&mut self, frame: ServiceFrame) -> Result<HostOutput, HostError> {
1055        let result = self.accept_service_frame_inner(frame);
1056        if result.is_err() {
1057            self.poison_channel();
1058        }
1059        result
1060    }
1061
1062    fn accept_service_frame_inner(&mut self, frame: ServiceFrame) -> Result<HostOutput, HostError> {
1063        match frame {
1064            ServiceFrame::Hello { hello } => self.accept_hello(hello),
1065            ServiceFrame::Response { envelope } => self.accept_response(envelope),
1066            ServiceFrame::Event { event } => self.accept_event(event),
1067        }
1068    }
1069
1070    fn accept_hello(&mut self, hello: ServiceHello) -> Result<HostOutput, HostError> {
1071        if !matches!(&self.channel, ChannelState::AwaitingHello) {
1072            return Err(HostError::UnexpectedHello);
1073        }
1074        if hello.protocol_version != WALLET_ABI_VERSION
1075            || hello.platform != self.platform
1076            || hello.host_session_id != self.host_session_id
1077            || hello.restart_generation != self.restart_generation
1078            || hello.limits != ServiceLimits::default()
1079            || hello.capabilities.len() > MAX_PUBLIC_ITEMS
1080            || !hello
1081                .capabilities
1082                .contains(&ServiceCapability::CanonicalFraming)
1083            || !hello
1084                .capabilities
1085                .contains(&ServiceCapability::RestartIsolation)
1086            || !hello
1087                .capabilities
1088                .contains(&ServiceCapability::OpaqueAuthorityRegistry)
1089            || (hello
1090                .capabilities
1091                .contains(&ServiceCapability::ValueMovement)
1092                && !hello
1093                    .capabilities
1094                    .contains(&ServiceCapability::ProviderDispatch))
1095            || (hello
1096                .capabilities
1097                .contains(&ServiceCapability::HnsReadOperationsV1)
1098                && !hello
1099                    .capabilities
1100                    .contains(&ServiceCapability::WalletOperations))
1101            || (hello
1102                .capabilities
1103                .contains(&ServiceCapability::HnsWalletAuthorityContextV1)
1104                && (!hello
1105                    .capabilities
1106                    .contains(&ServiceCapability::WalletOperations)
1107                    || !hello
1108                        .capabilities
1109                        .contains(&ServiceCapability::HnsReadOperationsV1)))
1110        {
1111            return Err(HostError::HelloMismatch);
1112        }
1113        let negotiated = NegotiatedSession {
1114            protocol_version: hello.protocol_version,
1115            platform: hello.platform,
1116            host_session_id: hello.host_session_id,
1117            service_session_id: hello.service_session_id,
1118            restart_generation: hello.restart_generation,
1119            capabilities: hello.capabilities.clone(),
1120            limits: hello.limits.clone(),
1121        };
1122        self.channel = ChannelState::Ready(SessionState {
1123            service_session_id: hello.service_session_id,
1124            capabilities: hello.capabilities,
1125            next_host_sequence: 1,
1126            next_service_sequence: 1,
1127        });
1128        Ok(HostOutput::Negotiated(negotiated))
1129    }
1130
1131    fn accept_response(
1132        &mut self,
1133        envelope: SessionEnvelope<ServiceResponse>,
1134    ) -> Result<HostOutput, HostError> {
1135        let next_sequence = self.validate_service_header(
1136            envelope.protocol_version,
1137            envelope.host_session_id,
1138            envelope.service_session_id,
1139            envelope.restart_generation,
1140            envelope.channel_sequence,
1141        )?;
1142        let class = self
1143            .pending
1144            .get(&envelope.request_id)
1145            .cloned()
1146            .ok_or(HostError::PendingRequestMismatch)?;
1147        self.validate_response_authority_time(&class)?;
1148        self.apply_response(&class, &envelope.body)?;
1149        self.pending
1150            .remove(&envelope.request_id)
1151            .ok_or(HostError::PendingRequestMismatch)?;
1152        if self.aged_out_request_ids.remove(&envelope.request_id) {
1153            self.recent_request_ids.remove(&envelope.request_id);
1154        }
1155        self.set_next_service_sequence(next_sequence)?;
1156        Ok(HostOutput::Response(AcceptedResponse {
1157            request_id: envelope.request_id,
1158            response: envelope.body,
1159        }))
1160    }
1161
1162    fn accept_event(&mut self, event: ProviderEventEnvelope) -> Result<HostOutput, HostError> {
1163        self.require_capability(ServiceCapability::TypedEvents)?;
1164        let next_sequence = self.validate_service_header(
1165            event.protocol_version,
1166            event.host_session_id,
1167            event.service_session_id,
1168            event.restart_generation,
1169            event.channel_sequence,
1170        )?;
1171        let now = self.now()?;
1172        self.validate_and_apply_event(&event, now)?;
1173        self.set_next_service_sequence(next_sequence)?;
1174        Ok(HostOutput::Event(AcceptedEvent {
1175            binding: event.binding,
1176            event_sequence: event.event_sequence,
1177            payload: event.payload,
1178        }))
1179    }
1180
1181    fn apply_response(
1182        &mut self,
1183        class: &RequestClass,
1184        response: &ServiceResponse,
1185    ) -> Result<(), HostError> {
1186        if let ServiceResponse::Failure { failure } = response {
1187            if matches!(
1188                failure.code,
1189                ServiceErrorCode::InvalidFrame
1190                    | ServiceErrorCode::VersionMismatch
1191                    | ServiceErrorCode::SessionMismatch
1192                    | ServiceErrorCode::SequenceMismatch
1193                    | ServiceErrorCode::Replay
1194                    | ServiceErrorCode::UnsupportedCapability
1195            ) {
1196                return Err(HostError::ReportedProtocolFailure);
1197            }
1198            self.apply_failure(class, failure.code);
1199            return Ok(());
1200        }
1201        match (class, response) {
1202            (
1203                RequestClass::Register { handle },
1204                ServiceResponse::AuthorityRegistered {
1205                    authority_handle,
1206                    authority_revision,
1207                },
1208            ) if handle == authority_handle && *authority_revision == 1 => {
1209                let state = self
1210                    .authorities
1211                    .get_mut(handle)
1212                    .ok_or(HostError::AuthorityUnknown)?;
1213                if !matches!(&state.phase, AuthorityPhase::Registering) {
1214                    return Err(HostError::AuthorityLifecycle);
1215                }
1216                state.phase = AuthorityPhase::Active { revision: 1 };
1217                Ok(())
1218            }
1219            (
1220                RequestClass::Replace {
1221                    handle,
1222                    expected_revision,
1223                    replacement,
1224                },
1225                ServiceResponse::AuthorityReplaced {
1226                    authority_handle,
1227                    authority_revision,
1228                },
1229            ) if handle == authority_handle
1230                && expected_revision.checked_add(1) == Some(*authority_revision) =>
1231            {
1232                let state = self
1233                    .authorities
1234                    .get_mut(handle)
1235                    .ok_or(HostError::AuthorityUnknown)?;
1236                match &state.phase {
1237                    AuthorityPhase::Replacing {
1238                        revision,
1239                        replacement: pending_replacement,
1240                    } if revision == expected_revision && pending_replacement == replacement => {}
1241                    _ => return Err(HostError::AuthorityLifecycle),
1242                }
1243                state.facts = replacement.clone();
1244                state.phase = AuthorityPhase::Active {
1245                    revision: *authority_revision,
1246                };
1247                Ok(())
1248            }
1249            (
1250                RequestClass::Revoke {
1251                    handle,
1252                    expected_revision,
1253                },
1254                ServiceResponse::AuthorityRevoked { authority_handle },
1255            ) if handle == authority_handle => {
1256                let state = self
1257                    .authorities
1258                    .get(handle)
1259                    .ok_or(HostError::AuthorityUnknown)?;
1260                if !matches!(
1261                    &state.phase,
1262                    AuthorityPhase::Revoking { revision } if *revision == *expected_revision
1263                ) {
1264                    return Err(HostError::AuthorityLifecycle);
1265                }
1266                self.invalidate_authority_derived(*handle);
1267                self.authorities.remove(handle);
1268                Ok(())
1269            }
1270            (
1271                RequestClass::Capabilities { handle, revision },
1272                ServiceResponse::ProviderCapabilities {
1273                    binding,
1274                    capabilities,
1275                },
1276            ) => self.install_capabilities(*handle, *revision, *binding, capabilities.clone()),
1277            (
1278                RequestClass::Provider {
1279                    handle,
1280                    revision,
1281                    method,
1282                },
1283                ServiceResponse::ProviderResult { binding, .. },
1284            ) if !approval_required_method(method) => {
1285                self.apply_provider_binding(*handle, *revision, method, *binding)
1286            }
1287            (
1288                RequestClass::Provider {
1289                    handle,
1290                    revision,
1291                    method,
1292                },
1293                ServiceResponse::ApprovalRequired { approval },
1294            ) if approval_required_method(method) => {
1295                self.require_capability(ServiceCapability::StructuredApprovals)?;
1296                self.install_approval(*handle, *revision, method, approval.clone())
1297            }
1298            (
1299                RequestClass::Approval {
1300                    handle,
1301                    revision,
1302                    approval_id,
1303                    decision: ApprovalDecision::Approve,
1304                    method,
1305                },
1306                ServiceResponse::ProviderResult { binding, .. },
1307            ) => {
1308                self.validate_deciding_approval(*approval_id)?;
1309                self.apply_provider_binding(*handle, *revision, method, *binding)?;
1310                self.approvals.remove(approval_id);
1311                Ok(())
1312            }
1313            (
1314                RequestClass::Approval {
1315                    approval_id,
1316                    decision: ApprovalDecision::Reject,
1317                    ..
1318                },
1319                ServiceResponse::ApprovalRejected {
1320                    approval_id: response_id,
1321                },
1322            ) if approval_id == response_id => {
1323                self.validate_deciding_approval(*approval_id)?;
1324                self.approvals.remove(approval_id);
1325                Ok(())
1326            }
1327            (RequestClass::Wallet(class), ServiceResponse::Wallet { response })
1328                if class.matches(response) =>
1329            {
1330                if matches!(
1331                    response,
1332                    WalletResponse::WalletCreated { .. }
1333                        | WalletResponse::WalletRestored { .. }
1334                        | WalletResponse::Locked
1335                        | WalletResponse::Unlocked
1336                ) {
1337                    self.invalidate_all_provider_state();
1338                }
1339                Ok(())
1340            }
1341            (RequestClass::HnsRead(class), ServiceResponse::Wallet { response })
1342                if class.matches(response) =>
1343            {
1344                Ok(())
1345            }
1346            (
1347                RequestClass::HnsWalletAuthority(class),
1348                ServiceResponse::WalletAuthority { context },
1349            ) if class.matches(context) => Ok(()),
1350            _ => Err(HostError::ResponseClassMismatch),
1351        }
1352    }
1353
1354    fn apply_failure(&mut self, class: &RequestClass, code: ServiceErrorCode) {
1355        match class {
1356            RequestClass::Register { handle } => {
1357                self.invalidate_authority_derived(*handle);
1358                self.authorities.remove(handle);
1359            }
1360            RequestClass::Replace {
1361                handle,
1362                expected_revision,
1363                ..
1364            } => {
1365                self.invalidate_authority_derived(*handle);
1366                if let Some(state) = self.authorities.get_mut(handle) {
1367                    state.phase = AuthorityPhase::Stale {
1368                        revision: *expected_revision,
1369                    };
1370                }
1371            }
1372            RequestClass::Revoke {
1373                handle,
1374                expected_revision,
1375            } => {
1376                self.invalidate_authority_derived(*handle);
1377                if let Some(state) = self.authorities.get_mut(handle) {
1378                    state.phase = AuthorityPhase::Stale {
1379                        revision: *expected_revision,
1380                    };
1381                }
1382            }
1383            RequestClass::Approval { approval_id, .. } => {
1384                self.approvals.remove(approval_id);
1385            }
1386            _ => {}
1387        }
1388        if matches!(
1389            code,
1390            ServiceErrorCode::AuthorityUnknown | ServiceErrorCode::AuthorityStale
1391        ) && let Some(handle) = class.authority()
1392        {
1393            self.mark_authority_stale(handle);
1394        }
1395    }
1396
1397    fn install_capabilities(
1398        &mut self,
1399        handle: HostAuthorityHandleId,
1400        revision: u64,
1401        binding: ProviderBinding,
1402        capabilities: ProviderCapabilitySnapshot,
1403    ) -> Result<(), HostError> {
1404        let methods_valid = capabilities.provider_schema_version == PROVIDER_SCHEMA_VERSION
1405            && capabilities.approval_schema_version == APPROVAL_SCHEMA_VERSION
1406            && capabilities.wallet_session_id == binding.wallet_session_id
1407            && capabilities.permission_generation == binding.permission_generation
1408            && capabilities.methods.len() <= MAX_PROVIDER_METHODS
1409            && capabilities.methods.iter().all(|method| {
1410                !method.is_empty()
1411                    && method.len() <= MAX_METHOD_BYTES
1412                    && method.is_ascii()
1413                    && PROVIDER_METHOD_WIRE_NAMES.contains(&method.as_str())
1414            });
1415        if binding.authority_handle != handle
1416            || binding.authority_revision != revision
1417            || revision == 0
1418            || !methods_valid
1419        {
1420            return Err(HostError::InvalidCapabilitySnapshot);
1421        }
1422        let dispatch = self.has_capability(ServiceCapability::ProviderDispatch)?;
1423        let value = self.has_capability(ServiceCapability::ValueMovement)?;
1424        let approvals = self.has_capability(ServiceCapability::StructuredApprovals)?;
1425        let wallet_operations = self.has_capability(ServiceCapability::WalletOperations)?;
1426        if (!dispatch && !capabilities.methods.is_empty())
1427            || (!approvals
1428                && capabilities
1429                    .methods
1430                    .iter()
1431                    .any(|method| approval_required_method(method)))
1432            || (!wallet_operations && capabilities.methods.contains("wallet_lock"))
1433            || (!value
1434                && capabilities
1435                    .methods
1436                    .iter()
1437                    .any(|method| value_movement_method(method)))
1438        {
1439            return Err(HostError::InvalidCapabilitySnapshot);
1440        }
1441        let current = {
1442            let state = self
1443                .authorities
1444                .get(&handle)
1445                .ok_or(HostError::AuthorityUnknown)?;
1446            if active_revision(state)? != revision {
1447                return Err(HostError::StaleBinding);
1448            }
1449            state.binding
1450        };
1451        if let Some(current) = current {
1452            if current.wallet_session_id != binding.wallet_session_id {
1453                if current.permission_generation != binding.permission_generation {
1454                    return Err(HostError::StaleBinding);
1455                }
1456                self.invalidate_all_provider_state();
1457            } else if binding.permission_generation < current.permission_generation {
1458                return Err(HostError::StaleBinding);
1459            } else if binding.permission_generation > current.permission_generation {
1460                self.invalidate_permission_scope(handle)?;
1461            }
1462        }
1463        let state = self
1464            .authorities
1465            .get_mut(&handle)
1466            .ok_or(HostError::AuthorityUnknown)?;
1467        if active_revision(state)? != revision {
1468            return Err(HostError::StaleBinding);
1469        }
1470        state.binding = Some(binding);
1471        state.capabilities = Some(capabilities);
1472        Ok(())
1473    }
1474
1475    fn install_approval(
1476        &mut self,
1477        handle: HostAuthorityHandleId,
1478        revision: u64,
1479        method: &str,
1480        approval: ApprovalPrompt,
1481    ) -> Result<(), HostError> {
1482        let now = self.now()?;
1483        self.approvals
1484            .retain(|_, pending| pending.prompt.expires_at_unix_ms > now);
1485        if self.approvals.len() >= MAX_PENDING_APPROVALS {
1486            return Err(HostError::ApprovalCapacity);
1487        }
1488        if self.issued_approval_ids.len() >= MAX_ISSUED_APPROVAL_IDS {
1489            return Err(HostError::ApprovalIdentityCapacity);
1490        }
1491        if self.issued_approval_ids.contains(&approval.approval_id) {
1492            return Err(HostError::ApprovalMismatch);
1493        }
1494        approval
1495            .validate(approval.summary.approval_kind(), now)
1496            .map_err(|_| HostError::ApprovalMismatch)?;
1497        let state = self
1498            .authorities
1499            .get(&handle)
1500            .ok_or(HostError::AuthorityUnknown)?;
1501        if active_revision(state)? != revision
1502            || state.binding != Some(approval.binding)
1503            || approval.binding.authority_handle != handle
1504            || approval.binding.authority_revision != revision
1505            || approval.origin != state.facts.origin
1506            || approval.method != method
1507        {
1508            return Err(HostError::ApprovalMismatch);
1509        }
1510        let approval_id = approval.approval_id;
1511        self.approvals.insert(
1512            approval_id,
1513            HostApproval {
1514                prompt: approval,
1515                phase: ApprovalPhase::Available,
1516            },
1517        );
1518        self.issued_approval_ids.insert(approval_id);
1519        Ok(())
1520    }
1521
1522    fn validate_deciding_approval(
1523        &mut self,
1524        approval_id: ProviderApprovalId,
1525    ) -> Result<(), HostError> {
1526        let now = self.now()?;
1527        let approval = self
1528            .approvals
1529            .get(&approval_id)
1530            .ok_or(HostError::ApprovalMismatch)?;
1531        if approval.prompt.expires_at_unix_ms <= now {
1532            return Err(HostError::ApprovalExpired);
1533        }
1534        let ApprovalPhase::Deciding { request_id } = approval.phase else {
1535            return Err(HostError::ApprovalMismatch);
1536        };
1537        if !self.pending.contains_key(&request_id) {
1538            return Err(HostError::ApprovalMismatch);
1539        }
1540        Ok(())
1541    }
1542
1543    fn apply_provider_binding(
1544        &mut self,
1545        handle: HostAuthorityHandleId,
1546        revision: u64,
1547        method: &str,
1548        binding: ProviderBinding,
1549    ) -> Result<(), HostError> {
1550        if binding.authority_handle != handle || binding.authority_revision != revision {
1551            return Err(HostError::StaleBinding);
1552        }
1553        let current = {
1554            let state = self
1555                .authorities
1556                .get(&handle)
1557                .ok_or(HostError::AuthorityUnknown)?;
1558            if active_revision(state)? != revision {
1559                return Err(HostError::StaleBinding);
1560            }
1561            state.binding.ok_or(HostError::StaleBinding)?
1562        };
1563        if permission_mutating_method(method) {
1564            if binding.wallet_session_id != current.wallet_session_id
1565                || current.permission_generation.checked_add(1)
1566                    != Some(binding.permission_generation)
1567            {
1568                return Err(HostError::StaleBinding);
1569            }
1570            self.invalidate_permission_scope(handle)?;
1571        } else if method == "wallet_lock" {
1572            if binding.wallet_session_id == current.wallet_session_id
1573                || binding.permission_generation != current.permission_generation
1574            {
1575                return Err(HostError::StaleBinding);
1576            }
1577            self.invalidate_all_provider_state();
1578        } else if binding != current {
1579            return Err(HostError::StaleBinding);
1580        } else {
1581            if capability_mutating_method(method) {
1582                self.invalidate_all_capability_snapshots();
1583            }
1584            return Ok(());
1585        }
1586        let state = self
1587            .authorities
1588            .get_mut(&handle)
1589            .ok_or(HostError::AuthorityUnknown)?;
1590        if active_revision(state)? != revision {
1591            return Err(HostError::StaleBinding);
1592        }
1593        state.binding = Some(binding);
1594        state.capabilities = None;
1595        Ok(())
1596    }
1597
1598    fn validate_and_apply_event(
1599        &mut self,
1600        event: &ProviderEventEnvelope,
1601        now: u64,
1602    ) -> Result<(), HostError> {
1603        let handle = event.binding.authority_handle;
1604        let (revision, current, expired) = {
1605            let state = self
1606                .authorities
1607                .get(&handle)
1608                .ok_or(HostError::AuthorityUnknown)?;
1609            (
1610                active_revision(state)?,
1611                state.binding.ok_or(HostError::EventBindingMismatch)?,
1612                state.facts.valid_until_unix_ms <= now,
1613            )
1614        };
1615        if event.binding.authority_revision != revision {
1616            return Err(HostError::EventBindingMismatch);
1617        }
1618        if expired
1619            && !matches!(
1620                &event.payload,
1621                ProviderEventPayload::Disconnect {
1622                    reason: DisconnectReason::AuthorityExpired
1623                }
1624            )
1625        {
1626            return Err(HostError::AuthorityExpired);
1627        }
1628
1629        let binding_changed = event.binding != current;
1630        if binding_changed {
1631            let permission_advanced = event.binding.wallet_session_id == current.wallet_session_id
1632                && current.permission_generation.checked_add(1)
1633                    == Some(event.binding.permission_generation)
1634                && matches!(
1635                    &event.payload,
1636                    ProviderEventPayload::Connect { .. }
1637                        | ProviderEventPayload::PermissionsChanged { .. }
1638                        | ProviderEventPayload::Disconnect {
1639                            reason: DisconnectReason::AuthorityRevoked
1640                        }
1641                );
1642            let wallet_rotated = event.binding.wallet_session_id != current.wallet_session_id
1643                && event.binding.permission_generation == current.permission_generation
1644                && matches!(
1645                    &event.payload,
1646                    ProviderEventPayload::WalletLocked
1647                        | ProviderEventPayload::Disconnect {
1648                            reason: DisconnectReason::WalletSessionChanged
1649                        }
1650                );
1651            if !permission_advanced && !wallet_rotated {
1652                return Err(HostError::EventBindingMismatch);
1653            }
1654            if wallet_rotated {
1655                self.invalidate_all_provider_state();
1656            } else {
1657                self.invalidate_permission_scope(handle)?;
1658            }
1659            let state = self
1660                .authorities
1661                .get_mut(&handle)
1662                .ok_or(HostError::AuthorityUnknown)?;
1663            if active_revision(state)? != revision {
1664                return Err(HostError::EventBindingMismatch);
1665            }
1666            state.binding = Some(event.binding);
1667            state.capabilities = None;
1668        }
1669
1670        match &event.payload {
1671            ProviderEventPayload::Connect {
1672                permission_generation,
1673            }
1674            | ProviderEventPayload::PermissionsChanged {
1675                permission_generation,
1676                ..
1677            } if *permission_generation != event.binding.permission_generation => {
1678                return Err(HostError::EventBindingMismatch);
1679            }
1680            ProviderEventPayload::Disconnect {
1681                reason: DisconnectReason::ServiceRestarted,
1682            } => return Err(HostError::SessionMismatch),
1683            _ if event.binding.permission_generation == 0
1684                && !matches!(&event.payload, ProviderEventPayload::Disconnect { .. }) =>
1685            {
1686                return Err(HostError::EventBindingMismatch);
1687            }
1688            _ => {}
1689        }
1690
1691        let key = EventCursorKey::from_binding(event.binding);
1692        let expected = match self.event_cursors.get(&key) {
1693            Some(sequence) => sequence
1694                .checked_add(1)
1695                .ok_or(HostError::SequenceExhausted)?,
1696            None => 1,
1697        };
1698        if event.event_sequence != expected {
1699            return Err(HostError::EventReplay);
1700        }
1701        if matches!(
1702            &event.payload,
1703            ProviderEventPayload::PermissionsChanged { .. }
1704        ) {
1705            self.invalidate_permission_scope(handle)?;
1706            let state = self
1707                .authorities
1708                .get_mut(&handle)
1709                .ok_or(HostError::AuthorityUnknown)?;
1710            if active_revision(state)? != revision {
1711                return Err(HostError::EventBindingMismatch);
1712            }
1713            state.binding = Some(event.binding);
1714            state.capabilities = None;
1715        }
1716        self.event_cursors.insert(key, event.event_sequence);
1717
1718        match &event.payload {
1719            ProviderEventPayload::Disconnect {
1720                reason:
1721                    DisconnectReason::AuthorityRevoked
1722                    | DisconnectReason::AuthorityExpired
1723                    | DisconnectReason::NavigationChanged
1724                    | DisconnectReason::PolicyChanged,
1725            } => self.mark_authority_stale(handle),
1726            ProviderEventPayload::Disconnect {
1727                reason: DisconnectReason::WalletSessionChanged,
1728            } => self.invalidate_all_provider_state(),
1729            ProviderEventPayload::WalletLocked => self.invalidate_all_provider_state(),
1730            ProviderEventPayload::ModulesChanged { .. } => {
1731                self.invalidate_all_capability_snapshots();
1732            }
1733            _ => {}
1734        }
1735        Ok(())
1736    }
1737
1738    fn enqueue(
1739        &mut self,
1740        body: ServiceRequest,
1741        class: RequestClass,
1742    ) -> Result<QueuedRequest, HostError> {
1743        if self.pending.len() >= MAX_PENDING_REQUESTS {
1744            return Err(HostError::PendingRequestCapacity);
1745        }
1746        let request_id = self.random_request_id()?;
1747        let (service_session_id, sequence, next_sequence) = {
1748            let ChannelState::Ready(session) = &self.channel else {
1749                return Err(match &self.channel {
1750                    ChannelState::Failed => HostError::ChannelFailed,
1751                    _ => HostError::HandshakeRequired,
1752                });
1753            };
1754            let next = session
1755                .next_host_sequence
1756                .checked_add(1)
1757                .ok_or(HostError::SequenceExhausted)?;
1758            (session.service_session_id, session.next_host_sequence, next)
1759        };
1760        self.pending.insert(request_id, class);
1761        self.remember_request_id(request_id);
1762        let ChannelState::Ready(session) = &mut self.channel else {
1763            return Err(HostError::HandshakeRequired);
1764        };
1765        session.next_host_sequence = next_sequence;
1766        Ok(QueuedRequest {
1767            request_id,
1768            frame: HostFrame::Request {
1769                envelope: SessionEnvelope {
1770                    protocol_version: WALLET_ABI_VERSION,
1771                    host_session_id: self.host_session_id,
1772                    service_session_id,
1773                    restart_generation: self.restart_generation,
1774                    channel_sequence: sequence,
1775                    request_id,
1776                    body,
1777                },
1778            },
1779        })
1780    }
1781
1782    fn validate_service_header(
1783        &self,
1784        protocol_version: u16,
1785        host_session_id: HostSessionId,
1786        service_session_id: WalletServiceSessionId,
1787        restart_generation: u64,
1788        channel_sequence: u64,
1789    ) -> Result<u64, HostError> {
1790        let ChannelState::Ready(session) = &self.channel else {
1791            return Err(match &self.channel {
1792                ChannelState::Failed => HostError::ChannelFailed,
1793                _ => HostError::HandshakeRequired,
1794            });
1795        };
1796        if protocol_version != WALLET_ABI_VERSION
1797            || host_session_id != self.host_session_id
1798            || service_session_id != session.service_session_id
1799            || restart_generation != self.restart_generation
1800        {
1801            return Err(HostError::SessionMismatch);
1802        }
1803        if channel_sequence != session.next_service_sequence {
1804            return Err(HostError::SequenceMismatch {
1805                expected: session.next_service_sequence,
1806                received: channel_sequence,
1807            });
1808        }
1809        channel_sequence
1810            .checked_add(1)
1811            .ok_or(HostError::SequenceExhausted)
1812    }
1813
1814    fn set_next_service_sequence(&mut self, next: u64) -> Result<(), HostError> {
1815        let ChannelState::Ready(session) = &mut self.channel else {
1816            return Err(HostError::HandshakeRequired);
1817        };
1818        session.next_service_sequence = next;
1819        Ok(())
1820    }
1821
1822    fn now(&mut self) -> Result<u64, HostError> {
1823        let now = self.clock.now_unix_ms()?;
1824        if self.last_now_unix_ms.is_some_and(|last| now < last) {
1825            self.poison_channel();
1826            return Err(HostError::ClockRollback);
1827        }
1828        self.last_now_unix_ms = Some(now);
1829        Ok(now)
1830    }
1831
1832    fn validate_response_authority_time(&mut self, class: &RequestClass) -> Result<(), HostError> {
1833        let Some(handle) = class.authority() else {
1834            return Ok(());
1835        };
1836        let now = self.now()?;
1837        let expired = self
1838            .authorities
1839            .get(&handle)
1840            .ok_or(HostError::AuthorityUnknown)?
1841            .facts
1842            .valid_until_unix_ms
1843            <= now;
1844        if expired {
1845            self.mark_authority_stale(handle);
1846            return Err(HostError::AuthorityExpired);
1847        }
1848        Ok(())
1849    }
1850
1851    fn active_authority(
1852        &mut self,
1853        handle: HostAuthorityHandleId,
1854        now: u64,
1855    ) -> Result<&AuthorityState, HostError> {
1856        let expired = self
1857            .authorities
1858            .get(&handle)
1859            .ok_or(HostError::AuthorityUnknown)?
1860            .facts
1861            .valid_until_unix_ms
1862            <= now;
1863        if expired {
1864            self.mark_authority_stale(handle);
1865            return Err(HostError::AuthorityExpired);
1866        }
1867        let state = self
1868            .authorities
1869            .get(&handle)
1870            .ok_or(HostError::AuthorityUnknown)?;
1871        if !matches!(&state.phase, AuthorityPhase::Active { .. }) {
1872            return Err(HostError::AuthorityLifecycle);
1873        }
1874        Ok(state)
1875    }
1876
1877    fn require_capability(&self, capability: ServiceCapability) -> Result<(), HostError> {
1878        if self.has_capability(capability)? {
1879            Ok(())
1880        } else {
1881            Err(HostError::CapabilityUnavailable)
1882        }
1883    }
1884
1885    fn has_capability(&self, capability: ServiceCapability) -> Result<bool, HostError> {
1886        match &self.channel {
1887            ChannelState::Ready(session) => Ok(session.capabilities.contains(&capability)),
1888            ChannelState::AwaitingHello => Err(HostError::HandshakeRequired),
1889            ChannelState::Failed => Err(HostError::ChannelFailed),
1890        }
1891    }
1892
1893    fn random_authority_handle(&mut self) -> Result<HostAuthorityHandleId, HostError> {
1894        for _ in 0..RANDOM_ATTEMPTS {
1895            let bytes = random_nonzero::<32, _>(&mut self.entropy)?;
1896            let handle = HostAuthorityHandleId::from_bytes(bytes)
1897                .map_err(|_| HostError::RandomIdentityUnavailable)?;
1898            if !self.issued_authority_ids.contains(&handle) {
1899                return Ok(handle);
1900            }
1901        }
1902        Err(HostError::RandomIdentityUnavailable)
1903    }
1904
1905    fn random_request_id(&mut self) -> Result<ProviderRequestId, HostError> {
1906        for _ in 0..RANDOM_ATTEMPTS {
1907            let bytes = random_nonzero::<16, _>(&mut self.entropy)?;
1908            let request_id = ProviderRequestId::from_bytes(bytes)
1909                .map_err(|_| HostError::RandomIdentityUnavailable)?;
1910            if !self.recent_request_ids.contains(&request_id)
1911                && !self.pending.contains_key(&request_id)
1912            {
1913                return Ok(request_id);
1914            }
1915        }
1916        Err(HostError::RandomIdentityUnavailable)
1917    }
1918
1919    fn random_provider_nonce(&mut self, handle: HostAuthorityHandleId) -> Result<u64, HostError> {
1920        for _ in 0..RANDOM_ATTEMPTS {
1921            let bytes = random_nonzero::<8, _>(&mut self.entropy)?;
1922            let nonce = u64::from_be_bytes(bytes);
1923            if nonce != 0 && !self.recent_nonces.contains(&(handle, nonce)) {
1924                return Ok(nonce);
1925            }
1926        }
1927        Err(HostError::RandomIdentityUnavailable)
1928    }
1929
1930    fn remember_request_id(&mut self, request_id: ProviderRequestId) {
1931        self.recent_request_ids.insert(request_id);
1932        self.request_id_order.push_back(request_id);
1933        if self.request_id_order.len() > MAX_RECENT_REQUEST_IDS
1934            && let Some(expired) = self.request_id_order.pop_front()
1935        {
1936            if self.pending.contains_key(&expired) {
1937                self.aged_out_request_ids.insert(expired);
1938            } else {
1939                self.recent_request_ids.remove(&expired);
1940            }
1941        }
1942    }
1943
1944    fn remember_nonce(&mut self, handle: HostAuthorityHandleId, nonce: u64) {
1945        self.recent_nonces.insert((handle, nonce));
1946        self.nonce_order.push_back((handle, nonce));
1947        if self.nonce_order.len() > MAX_RECENT_PROVIDER_NONCES
1948            && let Some(expired) = self.nonce_order.pop_front()
1949        {
1950            self.recent_nonces.remove(&expired);
1951        }
1952    }
1953
1954    fn invalidate_authority_derived(&mut self, handle: HostAuthorityHandleId) {
1955        if let Some(state) = self.authorities.get_mut(&handle) {
1956            state.binding = None;
1957            state.capabilities = None;
1958        }
1959        self.approvals
1960            .retain(|_, approval| approval.prompt.binding.authority_handle != handle);
1961        self.event_cursors
1962            .retain(|key, _| key.authority_handle != handle);
1963    }
1964
1965    fn invalidate_permission_scope(
1966        &mut self,
1967        handle: HostAuthorityHandleId,
1968    ) -> Result<(), HostError> {
1969        let (origin, namespace) = {
1970            let state = self
1971                .authorities
1972                .get(&handle)
1973                .ok_or(HostError::AuthorityUnknown)?;
1974            (state.facts.origin.clone(), state.facts.namespace)
1975        };
1976        let affected = self
1977            .authorities
1978            .iter()
1979            .filter_map(|(candidate, state)| {
1980                (state.facts.origin == origin && state.facts.namespace == namespace)
1981                    .then_some(*candidate)
1982            })
1983            .collect::<Vec<_>>();
1984        for affected_handle in affected {
1985            self.invalidate_authority_derived(affected_handle);
1986        }
1987        // The checked-in service restarts its global event sequence domain on
1988        // every permission grant or revocation. Mirror that exact reset scope.
1989        self.event_cursors.clear();
1990        Ok(())
1991    }
1992
1993    fn invalidate_all_capability_snapshots(&mut self) {
1994        for state in self.authorities.values_mut() {
1995            state.capabilities = None;
1996        }
1997    }
1998
1999    fn invalidate_all_provider_state(&mut self) {
2000        for state in self.authorities.values_mut() {
2001            state.binding = None;
2002            state.capabilities = None;
2003        }
2004        self.approvals.clear();
2005        self.event_cursors.clear();
2006    }
2007
2008    fn mark_authority_stale(&mut self, handle: HostAuthorityHandleId) {
2009        self.invalidate_authority_derived(handle);
2010        if let Some(state) = self.authorities.get_mut(&handle) {
2011            let revision = match &state.phase {
2012                AuthorityPhase::Active { revision }
2013                | AuthorityPhase::Replacing { revision, .. }
2014                | AuthorityPhase::Revoking { revision }
2015                | AuthorityPhase::Stale { revision } => Some(*revision),
2016                AuthorityPhase::Detached | AuthorityPhase::Registering => None,
2017            };
2018            if let Some(revision) = revision {
2019                state.phase = AuthorityPhase::Stale { revision };
2020            }
2021        }
2022    }
2023
2024    fn invalidate_service_state(&mut self) {
2025        let mut remove = Vec::new();
2026        for (handle, state) in &mut self.authorities {
2027            match state.phase.clone() {
2028                AuthorityPhase::Replacing { replacement, .. } => {
2029                    state.facts = replacement;
2030                    state.phase = AuthorityPhase::Detached;
2031                }
2032                AuthorityPhase::Revoking { .. } => remove.push(*handle),
2033                _ => state.phase = AuthorityPhase::Detached,
2034            }
2035            state.binding = None;
2036            state.capabilities = None;
2037        }
2038        for handle in remove {
2039            self.authorities.remove(&handle);
2040        }
2041        for request_id in &self.aged_out_request_ids {
2042            self.recent_request_ids.remove(request_id);
2043        }
2044        self.aged_out_request_ids.clear();
2045        self.pending.clear();
2046        self.approvals.clear();
2047        self.event_cursors.clear();
2048    }
2049
2050    fn poison_channel(&mut self) {
2051        self.invalidate_service_state();
2052        self.channel = ChannelState::Failed;
2053    }
2054}
2055
2056fn lifecycle(phase: &AuthorityPhase) -> AuthorityLifecycle {
2057    match phase {
2058        AuthorityPhase::Detached => AuthorityLifecycle::Detached,
2059        AuthorityPhase::Registering => AuthorityLifecycle::Registering,
2060        AuthorityPhase::Active { revision } => AuthorityLifecycle::Active {
2061            revision: *revision,
2062        },
2063        AuthorityPhase::Replacing { revision, .. } => AuthorityLifecycle::Replacing {
2064            revision: *revision,
2065        },
2066        AuthorityPhase::Revoking { revision } => AuthorityLifecycle::Revoking {
2067            revision: *revision,
2068        },
2069        AuthorityPhase::Stale { revision } => AuthorityLifecycle::Stale {
2070            revision: *revision,
2071        },
2072    }
2073}
2074
2075fn active_revision(state: &AuthorityState) -> Result<u64, HostError> {
2076    match &state.phase {
2077        AuthorityPhase::Active { revision } if *revision != 0 => Ok(*revision),
2078        _ => Err(HostError::AuthorityLifecycle),
2079    }
2080}
2081
2082fn validate_authority_facts(facts: &HostAuthorityFacts, now: u64) -> Result<(), HostError> {
2083    if facts.origin.is_empty()
2084        || facts.origin.len() > MAX_ORIGIN_BYTES
2085        || !facts.origin.is_ascii()
2086        || facts.runtime_generation == 0
2087        || facts.policy_generation == 0
2088        || facts.navigation_generation == 0
2089        || facts.valid_until_unix_ms <= now
2090    {
2091        return Err(HostError::InvalidAuthorityFacts);
2092    }
2093    Ok(())
2094}
2095
2096fn validate_replacement(
2097    current: &HostAuthorityFacts,
2098    replacement: &HostAuthorityFacts,
2099) -> Result<(), HostError> {
2100    if replacement.origin != current.origin
2101        || replacement.namespace != current.namespace
2102        || replacement.runtime_session_id != current.runtime_session_id
2103        || replacement.runtime_generation < current.runtime_generation
2104        || replacement.policy_generation < current.policy_generation
2105        || replacement.navigation_generation < current.navigation_generation
2106        || replacement.valid_until_unix_ms < current.valid_until_unix_ms
2107    {
2108        return Err(HostError::InvalidAuthorityFacts);
2109    }
2110    Ok(())
2111}
2112
2113fn validate_provider_request(method: &str, params: &Value) -> Result<(), HostError> {
2114    if method.is_empty()
2115        || method.len() > MAX_METHOD_BYTES
2116        || !method.is_ascii()
2117        || !PROVIDER_METHOD_WIRE_NAMES.contains(&method)
2118    {
2119        return Err(HostError::InvalidProviderRequest);
2120    }
2121    let encoded = serde_json::to_vec(&serde_json::json!({
2122        "method": method,
2123        "params": params,
2124    }))
2125    .map_err(|_| HostError::Encoding)?;
2126    if encoded.len() > MAX_PROVIDER_REQUEST_BYTES {
2127        return Err(HostError::InvalidProviderRequest);
2128    }
2129    Ok(())
2130}
2131
2132fn permission_mutating_method(method: &str) -> bool {
2133    matches!(
2134        method,
2135        "wallet_requestPermissions" | "wallet_revokePermissions" | "hns_requestAccounts"
2136    )
2137}
2138
2139fn capability_mutating_method(method: &str) -> bool {
2140    matches!(method, "wallet_enableModule" | "wallet_disableModule")
2141}
2142
2143fn approval_required_method(method: &str) -> bool {
2144    matches!(
2145        method,
2146        "wallet_enableModule"
2147            | "wallet_disableModule"
2148            | "wallet_requestPermissions"
2149            | "hns_requestAccounts"
2150            | "hns_send"
2151            | "asset_send"
2152            | "hns_transferName"
2153            | "hns_finalizeName"
2154            | "hns_signTypedMessage"
2155            | "nameMarket_createFixedPriceOffer"
2156            | "nameMarket_cancelOffer"
2157            | "nameMarket_acceptOffer"
2158            | "nameMarket_finalizePurchase"
2159            | "nameMarket_recoverName"
2160            | "swap_publishDirectOffer"
2161            | "swap_cancelDirectOffer"
2162            | "swap_acceptDirectOffer"
2163            | "swap_redeem"
2164            | "swap_refund"
2165    )
2166}
2167
2168fn value_movement_method(method: &str) -> bool {
2169    matches!(
2170        method,
2171        "hns_send"
2172            | "asset_send"
2173            | "hns_transferName"
2174            | "hns_finalizeName"
2175            | "nameMarket_createFixedPriceOffer"
2176            | "nameMarket_cancelOffer"
2177            | "nameMarket_acceptOffer"
2178            | "nameMarket_finalizePurchase"
2179            | "nameMarket_recoverName"
2180            | "swap_publishDirectOffer"
2181            | "swap_cancelDirectOffer"
2182            | "swap_acceptDirectOffer"
2183            | "swap_redeem"
2184            | "swap_refund"
2185    )
2186}
2187
2188fn random_host_session<E: Entropy>(entropy: &mut E) -> Result<HostSessionId, HostError> {
2189    let bytes = random_nonzero::<32, _>(entropy)?;
2190    HostSessionId::from_bytes(bytes).map_err(|_| HostError::RandomIdentityUnavailable)
2191}
2192
2193fn random_nonzero<const N: usize, E: Entropy>(entropy: &mut E) -> Result<[u8; N], HostError> {
2194    for _ in 0..RANDOM_ATTEMPTS {
2195        let mut bytes = [0_u8; N];
2196        entropy.fill_bytes(&mut bytes)?;
2197        if bytes != [0_u8; N] {
2198            return Ok(bytes);
2199        }
2200    }
2201    Err(HostError::RandomIdentityUnavailable)
2202}
2203
2204#[cfg(test)]
2205mod tests {
2206    use std::cell::Cell;
2207    use std::rc::Rc;
2208
2209    use hns_wallet_ffi::{
2210        AccountSummary, ApprovalSummary, HnsNameDisclosure, ProviderNamespace, SecretString,
2211        WalletHandshakeNetwork, WalletRuntimeStatus,
2212    };
2213    use hns_wallet_types::{
2214        Amount, BaseUnits, BrowserRuntimeSessionId, LocalTransactionStatus, PermissionCapability,
2215        ProviderAuthorityFingerprint, ReceiveTarget, SignedBaseUnits, SyncPhase, SyncStatus,
2216        TransactionHash, TransactionSummary, WalletId, WalletSessionId, WorkflowId,
2217    };
2218
2219    use super::*;
2220
2221    #[derive(Clone)]
2222    struct TestClock(Rc<Cell<u64>>);
2223
2224    impl Clock for TestClock {
2225        fn now_unix_ms(&self) -> Result<u64, ClockError> {
2226            Ok(self.0.get())
2227        }
2228    }
2229
2230    struct TestEntropy {
2231        next: u8,
2232    }
2233
2234    impl Entropy for TestEntropy {
2235        fn fill_bytes(&mut self, destination: &mut [u8]) -> Result<(), EntropyError> {
2236            destination.fill(self.next);
2237            self.next = self.next.checked_add(1).unwrap_or(1);
2238            Ok(())
2239        }
2240    }
2241
2242    type TestHost = WalletHost<TestClock, TestEntropy>;
2243
2244    fn new_host() -> (TestHost, Rc<Cell<u64>>) {
2245        let now = Rc::new(Cell::new(1_000));
2246        let host = WalletHost::new(
2247            HostPlatform::ChromiumNativeHost,
2248            1,
2249            TestClock(now.clone()),
2250            TestEntropy { next: 1 },
2251        )
2252        .expect("host");
2253        (host, now)
2254    }
2255
2256    fn service_session() -> WalletServiceSessionId {
2257        WalletServiceSessionId::from_bytes([90; 32]).expect("service session")
2258    }
2259
2260    fn wallet_session() -> WalletSessionId {
2261        WalletSessionId::from_bytes([91; 32]).expect("wallet session")
2262    }
2263
2264    fn handle() -> HostAuthorityHandleId {
2265        HostAuthorityHandleId::from_bytes([92; 32]).expect("authority handle")
2266    }
2267
2268    fn approval_id() -> ProviderApprovalId {
2269        ProviderApprovalId::from_bytes([93; 16]).expect("approval id")
2270    }
2271
2272    fn required_capabilities() -> BTreeSet<ServiceCapability> {
2273        BTreeSet::from([
2274            ServiceCapability::CanonicalFraming,
2275            ServiceCapability::RestartIsolation,
2276            ServiceCapability::OpaqueAuthorityRegistry,
2277        ])
2278    }
2279
2280    fn negotiate(host: &mut TestHost, capabilities: BTreeSet<ServiceCapability>) {
2281        let output = host
2282            .accept_service_frame(ServiceFrame::Hello {
2283                hello: ServiceHello {
2284                    protocol_version: WALLET_ABI_VERSION,
2285                    platform: host.platform(),
2286                    host_session_id: host.host_session_id(),
2287                    service_session_id: service_session(),
2288                    restart_generation: host.restart_generation(),
2289                    capabilities,
2290                    limits: ServiceLimits::default(),
2291                },
2292            })
2293            .expect("negotiate");
2294        assert!(matches!(output, HostOutput::Negotiated(_)));
2295    }
2296
2297    fn facts(valid_until_unix_ms: u64) -> HostAuthorityFacts {
2298        HostAuthorityFacts {
2299            origin: "https://wallet.example".to_owned(),
2300            namespace: ProviderNamespace::Hns,
2301            runtime_session_id: BrowserRuntimeSessionId::from_bytes([94; 16])
2302                .expect("runtime session"),
2303            runtime_generation: 1,
2304            policy_generation: 1,
2305            navigation_generation: 1,
2306            decision_fingerprint: ProviderAuthorityFingerprint::from_bytes([95; 32])
2307                .expect("authority fingerprint"),
2308            valid_until_unix_ms,
2309        }
2310    }
2311
2312    fn binding() -> ProviderBinding {
2313        ProviderBinding {
2314            authority_handle: handle(),
2315            authority_revision: 1,
2316            wallet_session_id: wallet_session(),
2317            permission_generation: 1,
2318        }
2319    }
2320
2321    fn approval_prompt() -> ApprovalPrompt {
2322        ApprovalPrompt {
2323            approval_id: approval_id(),
2324            binding: binding(),
2325            origin: "https://wallet.example".to_owned(),
2326            method: "wallet_requestPermissions".to_owned(),
2327            expires_at_unix_ms: 1_500,
2328            summary: ApprovalSummary::Permissions {
2329                capabilities: BTreeSet::from([PermissionCapability::Balance]),
2330                hns_names: Vec::new(),
2331            },
2332        }
2333    }
2334
2335    fn install_active_authority(host: &mut TestHost, valid_until_unix_ms: u64) {
2336        host.authorities.insert(
2337            handle(),
2338            AuthorityState {
2339                facts: facts(valid_until_unix_ms),
2340                phase: AuthorityPhase::Active { revision: 1 },
2341                binding: Some(binding()),
2342                capabilities: None,
2343            },
2344        );
2345    }
2346
2347    fn request_id(frame: HostFrame) -> ProviderRequestId {
2348        let HostFrame::Request { envelope } = frame else {
2349            panic!("request frame");
2350        };
2351        envelope.request_id
2352    }
2353
2354    fn response_frame(
2355        host: &TestHost,
2356        request_id: ProviderRequestId,
2357        channel_sequence: u64,
2358        body: ServiceResponse,
2359    ) -> ServiceFrame {
2360        ServiceFrame::Response {
2361            envelope: SessionEnvelope {
2362                protocol_version: WALLET_ABI_VERSION,
2363                host_session_id: host.host_session_id(),
2364                service_session_id: service_session(),
2365                restart_generation: host.restart_generation(),
2366                channel_sequence,
2367                request_id,
2368                body,
2369            },
2370        }
2371    }
2372
2373    #[test]
2374    fn exact_hello_negotiates_one_session() {
2375        let (mut host, _) = new_host();
2376        negotiate(&mut host, required_capabilities());
2377        assert_eq!(host.connection_state(), ConnectionState::Ready);
2378        assert_eq!(
2379            host.negotiated_session()
2380                .expect("negotiated session")
2381                .service_session_id,
2382            service_session()
2383        );
2384    }
2385
2386    #[test]
2387    fn mismatched_hello_poisons_the_channel() {
2388        let (mut host, _) = new_host();
2389        let result = host.accept_service_frame(ServiceFrame::Hello {
2390            hello: ServiceHello {
2391                protocol_version: WALLET_ABI_VERSION,
2392                platform: HostPlatform::Android,
2393                host_session_id: host.host_session_id(),
2394                service_session_id: service_session(),
2395                restart_generation: host.restart_generation(),
2396                capabilities: required_capabilities(),
2397                limits: ServiceLimits::default(),
2398            },
2399        });
2400        assert!(matches!(result, Err(HostError::HelloMismatch)));
2401        assert_eq!(host.connection_state(), ConnectionState::Failed);
2402    }
2403
2404    #[test]
2405    fn hns_read_marker_requires_coarse_wallet_operations_at_hello() {
2406        let (mut host, _) = new_host();
2407        let mut capabilities = required_capabilities();
2408        capabilities.insert(ServiceCapability::HnsReadOperationsV1);
2409        let result = host.accept_service_frame(ServiceFrame::Hello {
2410            hello: ServiceHello {
2411                protocol_version: WALLET_ABI_VERSION,
2412                platform: host.platform(),
2413                host_session_id: host.host_session_id(),
2414                service_session_id: service_session(),
2415                restart_generation: host.restart_generation(),
2416                capabilities,
2417                limits: ServiceLimits::default(),
2418            },
2419        });
2420        assert!(matches!(result, Err(HostError::HelloMismatch)));
2421        assert_eq!(host.connection_state(), ConnectionState::Failed);
2422    }
2423
2424    #[test]
2425    fn hns_wallet_authority_marker_requires_both_read_prerequisites_at_hello() {
2426        for capabilities in [
2427            BTreeSet::from([ServiceCapability::HnsWalletAuthorityContextV1]),
2428            BTreeSet::from([
2429                ServiceCapability::WalletOperations,
2430                ServiceCapability::HnsWalletAuthorityContextV1,
2431            ]),
2432        ] {
2433            let (mut host, _) = new_host();
2434            let mut offered = required_capabilities();
2435            offered.extend(capabilities);
2436            let result = host.accept_service_frame(ServiceFrame::Hello {
2437                hello: ServiceHello {
2438                    protocol_version: WALLET_ABI_VERSION,
2439                    platform: host.platform(),
2440                    host_session_id: host.host_session_id(),
2441                    service_session_id: service_session(),
2442                    restart_generation: host.restart_generation(),
2443                    capabilities: offered,
2444                    limits: ServiceLimits::default(),
2445                },
2446            });
2447            assert!(matches!(result, Err(HostError::HelloMismatch)));
2448            assert_eq!(host.connection_state(), ConnectionState::Failed);
2449        }
2450    }
2451
2452    #[test]
2453    fn exact_hns_wallet_authority_context_is_request_scoped_evidence_only() {
2454        let request = WalletAuthorityContextRequest::CurrentHnsContext {
2455            network: WalletHandshakeNetwork::Regtest,
2456            network_magic: WalletHandshakeNetwork::Regtest.magic(),
2457            namespace_id: [7_u8; 16],
2458            namespace_lease_generation: 9_007_199_254_740_997,
2459            module: ModuleId::Handshake,
2460        };
2461
2462        let (mut missing_marker, _) = new_host();
2463        let mut read_capabilities = required_capabilities();
2464        read_capabilities.extend([
2465            ServiceCapability::WalletOperations,
2466            ServiceCapability::HnsReadOperationsV1,
2467        ]);
2468        negotiate(&mut missing_marker, read_capabilities);
2469        assert!(matches!(
2470            missing_marker.hns_wallet_authority_context_request(request),
2471            Err(HostError::CapabilityUnavailable)
2472        ));
2473        assert!(missing_marker.pending.is_empty());
2474
2475        let capabilities = || {
2476            let mut capabilities = required_capabilities();
2477            capabilities.extend([
2478                ServiceCapability::WalletOperations,
2479                ServiceCapability::HnsReadOperationsV1,
2480                ServiceCapability::HnsWalletAuthorityContextV1,
2481            ]);
2482            capabilities
2483        };
2484        let context = WalletHnsAuthorityContext {
2485            network: WalletHandshakeNetwork::Regtest,
2486            network_magic: WalletHandshakeNetwork::Regtest.magic(),
2487            namespace_id: [7_u8; 16],
2488            namespace_lease_generation: 9_007_199_254_740_997,
2489            active_wallet: WalletId::new([8_u8; 16]),
2490            account: AccountId::new([9_u8; 16]),
2491            wallet_authority_revision: 9_007_199_254_740_993,
2492            account_authority_revision: 9_007_199_254_740_995,
2493            locked: false,
2494            module: ModuleId::Handshake,
2495            persistent_wallet_confirmed: true,
2496            recovery_pending: false,
2497            retirement_pending: false,
2498            hns_reads_ready: true,
2499        };
2500
2501        let (mut host, _) = new_host();
2502        negotiate(&mut host, capabilities());
2503        let frame = host
2504            .hns_wallet_authority_context_request(request)
2505            .expect("exact authority-context request");
2506        let HostFrame::Request { envelope } = &frame else {
2507            panic!("authority request frame")
2508        };
2509        assert_eq!(envelope.body, ServiceRequest::WalletAuthority { request });
2510        let first_request_id = request_id(frame);
2511        let response = response_frame(
2512            &host,
2513            first_request_id,
2514            1,
2515            ServiceResponse::WalletAuthority { context },
2516        );
2517        let accepted = host
2518            .accept_service_frame(response)
2519            .expect("exact authority-context response");
2520        assert!(matches!(
2521            accepted,
2522            HostOutput::Response(AcceptedResponse {
2523                response: ServiceResponse::WalletAuthority { context: accepted },
2524                ..
2525            }) if accepted == context
2526        ));
2527        assert!(host.pending.is_empty());
2528        assert_eq!(host.connection_state(), ConnectionState::Ready);
2529
2530        let (mut mismatch, _) = new_host();
2531        negotiate(&mut mismatch, capabilities());
2532        let request_id = request_id(
2533            mismatch
2534                .hns_wallet_authority_context_request(request)
2535                .expect("mismatch authority request"),
2536        );
2537        let mismatched_context = WalletHnsAuthorityContext {
2538            namespace_id: [8_u8; 16],
2539            ..context
2540        };
2541        let response = response_frame(
2542            &mismatch,
2543            request_id,
2544            1,
2545            ServiceResponse::WalletAuthority {
2546                context: mismatched_context,
2547            },
2548        );
2549        assert!(matches!(
2550            mismatch.accept_service_frame(response),
2551            Err(HostError::ResponseClassMismatch)
2552        ));
2553        assert_eq!(mismatch.connection_state(), ConnectionState::Failed);
2554
2555        let (mut malformed, _) = new_host();
2556        negotiate(&mut malformed, capabilities());
2557        assert!(matches!(
2558            malformed.hns_wallet_authority_context_request(
2559                WalletAuthorityContextRequest::CurrentHnsContext {
2560                    network: WalletHandshakeNetwork::Regtest,
2561                    network_magic: WalletHandshakeNetwork::Regtest.magic(),
2562                    namespace_id: [0_u8; 16],
2563                    namespace_lease_generation: 9_007_199_254_740_997,
2564                    module: ModuleId::Handshake,
2565                }
2566            ),
2567            Err(HostError::InvalidHnsWalletAuthorityRequest)
2568        ));
2569        assert!(malformed.pending.is_empty());
2570        assert_eq!(malformed.connection_state(), ConnectionState::Ready);
2571    }
2572
2573    #[test]
2574    fn exact_hns_read_path_requires_marker_and_rejects_every_other_request() {
2575        let account = AccountId::new([33; 16]);
2576        let (mut coarse_only, _) = new_host();
2577        let mut coarse_capabilities = required_capabilities();
2578        coarse_capabilities.insert(ServiceCapability::WalletOperations);
2579        negotiate(&mut coarse_only, coarse_capabilities);
2580        assert!(matches!(
2581            coarse_only.hns_read_request(WalletRequest::Status),
2582            Err(HostError::CapabilityUnavailable)
2583        ));
2584        assert!(coarse_only.pending.is_empty());
2585        coarse_only
2586            .wallet_request(WalletRequest::Status)
2587            .expect("legacy coarse request remains available");
2588
2589        let (mut exact, _) = new_host();
2590        let mut exact_capabilities = required_capabilities();
2591        exact_capabilities.extend([
2592            ServiceCapability::WalletOperations,
2593            ServiceCapability::HnsReadOperationsV1,
2594        ]);
2595        negotiate(&mut exact, exact_capabilities);
2596        for request in [
2597            WalletRequest::Status,
2598            WalletRequest::ListAccounts,
2599            WalletRequest::Balance {
2600                module: ModuleId::Handshake,
2601                account,
2602            },
2603            WalletRequest::ReceiveTarget {
2604                module: ModuleId::Handshake,
2605                account,
2606            },
2607            WalletRequest::TransactionHistory {
2608                module: ModuleId::Handshake,
2609                account,
2610            },
2611            WalletRequest::ModuleStatus {
2612                module: ModuleId::Handshake,
2613            },
2614        ] {
2615            exact
2616                .hns_read_request(request)
2617                .expect("frozen HNS read request");
2618        }
2619        assert_eq!(exact.pending.len(), 6);
2620
2621        let (mut rejected, _) = new_host();
2622        let mut rejected_capabilities = required_capabilities();
2623        rejected_capabilities.extend([
2624            ServiceCapability::WalletOperations,
2625            ServiceCapability::HnsReadOperationsV1,
2626        ]);
2627        negotiate(&mut rejected, rejected_capabilities);
2628        for request in [
2629            WalletRequest::CreateWallet {
2630                passphrase: SecretString::new("create secret".to_owned()),
2631            },
2632            WalletRequest::RestoreWallet {
2633                passphrase: SecretString::new("restore secret".to_owned()),
2634                recovery_phrase: SecretString::new("recovery secret".to_owned()),
2635            },
2636            WalletRequest::Unlock {
2637                passphrase: SecretString::new("unlock secret".to_owned()),
2638            },
2639            WalletRequest::Lock,
2640            WalletRequest::WorkflowStatus {
2641                workflow_id: WorkflowId::new([44; 16]),
2642            },
2643            WalletRequest::Balance {
2644                module: ModuleId::Bitcoin,
2645                account,
2646            },
2647            WalletRequest::ReceiveTarget {
2648                module: ModuleId::Ethereum,
2649                account,
2650            },
2651            WalletRequest::TransactionHistory {
2652                module: ModuleId::Bitcoin,
2653                account,
2654            },
2655            WalletRequest::ModuleStatus {
2656                module: ModuleId::Ethereum,
2657            },
2658        ] {
2659            assert!(matches!(
2660                rejected.hns_read_request(request),
2661                Err(HostError::InvalidHnsReadRequest)
2662            ));
2663        }
2664        assert!(rejected.pending.is_empty());
2665        assert_eq!(rejected.connection_state(), ConnectionState::Ready);
2666    }
2667
2668    #[test]
2669    fn exact_hns_read_responses_are_minimized_and_request_scoped() {
2670        let account = AccountId::new([33; 16]);
2671        let other_account = AccountId::new([34; 16]);
2672        let status_class =
2673            HnsReadResponseClass::for_request(&WalletRequest::Status).expect("status class");
2674        let status =
2675            |locked, active_wallet, modules, mainnet_settlement_enabled| WalletResponse::Status {
2676                status: WalletRuntimeStatus {
2677                    locked,
2678                    active_wallet,
2679                    enabled_modules: modules,
2680                    mainnet_settlement_enabled,
2681                },
2682            };
2683        assert!(status_class.matches(&status(
2684            false,
2685            Some(WalletId::new([1; 16])),
2686            BTreeSet::from([ModuleId::Handshake]),
2687            false,
2688        )));
2689        for response in [
2690            status(
2691                false,
2692                Some(WalletId::new([1; 16])),
2693                BTreeSet::from([ModuleId::Handshake]),
2694                true,
2695            ),
2696            status(
2697                false,
2698                Some(WalletId::new([1; 16])),
2699                BTreeSet::from([ModuleId::Bitcoin]),
2700                false,
2701            ),
2702            status(false, None, BTreeSet::from([ModuleId::Handshake]), false),
2703            status(
2704                true,
2705                Some(WalletId::new([1; 16])),
2706                BTreeSet::from([ModuleId::Handshake]),
2707                false,
2708            ),
2709            status(
2710                false,
2711                Some(WalletId::new([0; 16])),
2712                BTreeSet::from([ModuleId::Handshake]),
2713                false,
2714            ),
2715            status(
2716                false,
2717                Some(WalletId::new([1; 16])),
2718                BTreeSet::from([ModuleId::Handshake, ModuleId::Bitcoin]),
2719                false,
2720            ),
2721        ] {
2722            assert!(!status_class.matches(&response));
2723        }
2724
2725        let accounts_class =
2726            HnsReadResponseClass::for_request(&WalletRequest::ListAccounts).expect("accounts");
2727        let account_summary = AccountSummary {
2728            account_id: account,
2729            module: ModuleId::Handshake,
2730            label: "Handshake".to_owned(),
2731            receive_display: None,
2732        };
2733        assert!(accounts_class.matches(&WalletResponse::Accounts {
2734            accounts: vec![account_summary.clone()],
2735        }));
2736        assert!(!accounts_class.matches(&WalletResponse::Accounts { accounts: vec![] }));
2737        let mut disclosed = account_summary.clone();
2738        disclosed.receive_display = Some("hs1qprivate".to_owned());
2739        assert!(!accounts_class.matches(&WalletResponse::Accounts {
2740            accounts: vec![disclosed],
2741        }));
2742        let mut wrong_module = account_summary.clone();
2743        wrong_module.module = ModuleId::Bitcoin;
2744        assert!(!accounts_class.matches(&WalletResponse::Accounts {
2745            accounts: vec![wrong_module],
2746        }));
2747        let mut zero_account = account_summary.clone();
2748        zero_account.account_id = AccountId::new([0; 16]);
2749        assert!(!accounts_class.matches(&WalletResponse::Accounts {
2750            accounts: vec![zero_account],
2751        }));
2752        let mut empty_label = account_summary.clone();
2753        empty_label.label.clear();
2754        assert!(!accounts_class.matches(&WalletResponse::Accounts {
2755            accounts: vec![empty_label],
2756        }));
2757        let mut non_printable_label = account_summary.clone();
2758        non_printable_label.label = "Handshake\nWallet".to_owned();
2759        assert!(!accounts_class.matches(&WalletResponse::Accounts {
2760            accounts: vec![non_printable_label],
2761        }));
2762        let mut oversized_label = account_summary.clone();
2763        oversized_label.label = "H".repeat(MAX_PUBLIC_STRING_BYTES + 1);
2764        assert!(!accounts_class.matches(&WalletResponse::Accounts {
2765            accounts: vec![oversized_label],
2766        }));
2767        assert!(!accounts_class.matches(&WalletResponse::Accounts {
2768            accounts: vec![account_summary.clone(), account_summary],
2769        }));
2770
2771        let balance_class = HnsReadResponseClass::for_request(&WalletRequest::Balance {
2772            module: ModuleId::Handshake,
2773            account,
2774        })
2775        .expect("balance");
2776        assert!(balance_class.matches(&WalletResponse::Balance {
2777            amount: Amount::new(WalletAsset::Hns, 1),
2778        }));
2779        assert!(!balance_class.matches(&WalletResponse::Balance {
2780            amount: Amount::new(WalletAsset::Btc, 1),
2781        }));
2782
2783        let receive_class = HnsReadResponseClass::for_request(&WalletRequest::ReceiveTarget {
2784            module: ModuleId::Handshake,
2785            account,
2786        })
2787        .expect("receive");
2788        let receive = |module, account, display| WalletResponse::ReceiveTarget {
2789            target: ReceiveTarget {
2790                module,
2791                account,
2792                display,
2793                derivation_index: 0,
2794            },
2795        };
2796        assert!(receive_class.matches(&receive(
2797            ModuleId::Handshake,
2798            account,
2799            "hs1qread".to_owned(),
2800        )));
2801        assert!(!receive_class.matches(&receive(
2802            ModuleId::Handshake,
2803            other_account,
2804            "hs1qread".to_owned(),
2805        )));
2806        assert!(!receive_class.matches(&receive(
2807            ModuleId::Bitcoin,
2808            account,
2809            "bc1qread".to_owned(),
2810        )));
2811        for display in [
2812            String::new(),
2813            "hs1q read".to_owned(),
2814            "hs1qread\n".to_owned(),
2815            "hs1qréad".to_owned(),
2816            "h".repeat(513),
2817        ] {
2818            assert!(!receive_class.matches(&receive(ModuleId::Handshake, account, display)));
2819        }
2820
2821        let transactions_class =
2822            HnsReadResponseClass::for_request(&WalletRequest::TransactionHistory {
2823                module: ModuleId::Handshake,
2824                account,
2825            })
2826            .expect("transactions");
2827        let transaction = |module, txid_byte, negative, magnitude| TransactionSummary {
2828            module,
2829            txid: TransactionHash::new([txid_byte; 32]),
2830            status: LocalTransactionStatus::Confirmed,
2831            net_amount: SignedBaseUnits {
2832                negative,
2833                magnitude: BaseUnits::new(magnitude),
2834            },
2835            fee: None,
2836            block_height: Some(1),
2837            first_seen_unix: Some(1),
2838            confirmation_count: 1,
2839        };
2840        let valid_transaction = transaction(ModuleId::Handshake, 55, false, 1);
2841        assert!(
2842            transactions_class.matches(&WalletResponse::TransactionHistory {
2843                transactions: vec![],
2844            })
2845        );
2846        assert!(
2847            transactions_class.matches(&WalletResponse::TransactionHistory {
2848                transactions: vec![valid_transaction.clone()],
2849            })
2850        );
2851        for transactions in [
2852            vec![transaction(ModuleId::Bitcoin, 55, false, 1)],
2853            vec![transaction(ModuleId::Handshake, 0, false, 1)],
2854            vec![valid_transaction.clone(), valid_transaction],
2855            vec![transaction(ModuleId::Handshake, 56, true, 0)],
2856        ] {
2857            assert!(
2858                !transactions_class.matches(&WalletResponse::TransactionHistory { transactions })
2859            );
2860        }
2861
2862        let module_class = HnsReadResponseClass::for_request(&WalletRequest::ModuleStatus {
2863            module: ModuleId::Handshake,
2864        })
2865        .expect("module status");
2866        let successful_status = SyncStatus {
2867            phase: SyncPhase::Ready,
2868            validated_height: 1,
2869            scanned_height: 1,
2870            target_height: Some(1),
2871            last_error: None,
2872        };
2873        assert!(module_class.matches(&WalletResponse::ModuleStatus {
2874            status: successful_status.clone(),
2875        }));
2876        for status in [
2877            SyncStatus {
2878                phase: SyncPhase::Degraded,
2879                ..successful_status.clone()
2880            },
2881            SyncStatus {
2882                scanned_height: 0,
2883                ..successful_status.clone()
2884            },
2885            SyncStatus {
2886                target_height: None,
2887                ..successful_status.clone()
2888            },
2889            SyncStatus {
2890                target_height: Some(2),
2891                ..successful_status.clone()
2892            },
2893            SyncStatus {
2894                last_error: Some("not ready".to_owned()),
2895                ..successful_status
2896            },
2897        ] {
2898            assert!(!module_class.matches(&WalletResponse::ModuleStatus { status }));
2899        }
2900    }
2901
2902    #[test]
2903    fn exact_hns_read_response_scope_mismatch_poisons_the_channel() {
2904        let account = AccountId::new([33; 16]);
2905        let (mut host, _) = new_host();
2906        let mut capabilities = required_capabilities();
2907        capabilities.extend([
2908            ServiceCapability::WalletOperations,
2909            ServiceCapability::HnsReadOperationsV1,
2910        ]);
2911        negotiate(&mut host, capabilities);
2912        let request_id = request_id(
2913            host.hns_read_request(WalletRequest::ReceiveTarget {
2914                module: ModuleId::Handshake,
2915                account,
2916            })
2917            .expect("request"),
2918        );
2919        let frame = response_frame(
2920            &host,
2921            request_id,
2922            1,
2923            ServiceResponse::Wallet {
2924                response: WalletResponse::ReceiveTarget {
2925                    target: ReceiveTarget {
2926                        module: ModuleId::Handshake,
2927                        account: AccountId::new([34; 16]),
2928                        display: "hs1qwrongaccount".to_owned(),
2929                        derivation_index: 0,
2930                    },
2931                },
2932            },
2933        );
2934        assert!(matches!(
2935            host.accept_service_frame(frame),
2936            Err(HostError::ResponseClassMismatch)
2937        ));
2938        assert_eq!(host.connection_state(), ConnectionState::Failed);
2939    }
2940
2941    #[test]
2942    fn response_class_mismatch_poisons_the_channel() {
2943        let (mut host, _) = new_host();
2944        let mut capabilities = required_capabilities();
2945        capabilities.insert(ServiceCapability::WalletOperations);
2946        negotiate(&mut host, capabilities);
2947        let request_id = request_id(host.wallet_request(WalletRequest::Status).expect("request"));
2948        let frame = response_frame(
2949            &host,
2950            request_id,
2951            1,
2952            ServiceResponse::Wallet {
2953                response: WalletResponse::Locked,
2954            },
2955        );
2956        let result = host.accept_service_frame(frame);
2957        assert!(matches!(result, Err(HostError::ResponseClassMismatch)));
2958        assert_eq!(host.connection_state(), ConnectionState::Failed);
2959    }
2960
2961    #[test]
2962    fn responses_and_events_share_the_service_sequence() {
2963        let (mut host, _) = new_host();
2964        let mut capabilities = required_capabilities();
2965        capabilities.extend([
2966            ServiceCapability::TypedEvents,
2967            ServiceCapability::WalletOperations,
2968        ]);
2969        negotiate(&mut host, capabilities);
2970        let request_id = request_id(host.wallet_request(WalletRequest::Lock).expect("request"));
2971        let frame = response_frame(
2972            &host,
2973            request_id,
2974            1,
2975            ServiceResponse::Wallet {
2976                response: WalletResponse::Locked,
2977            },
2978        );
2979        host.accept_service_frame(frame).expect("response");
2980
2981        install_active_authority(&mut host, 2_000);
2982        let event = ProviderEventEnvelope {
2983            protocol_version: WALLET_ABI_VERSION,
2984            host_session_id: host.host_session_id(),
2985            service_session_id: service_session(),
2986            restart_generation: host.restart_generation(),
2987            channel_sequence: 2,
2988            binding: binding(),
2989            event_sequence: 1,
2990            payload: ProviderEventPayload::Connect {
2991                permission_generation: 1,
2992            },
2993        };
2994        assert!(matches!(
2995            host.accept_service_frame(ServiceFrame::Event { event }),
2996            Ok(HostOutput::Event(_))
2997        ));
2998    }
2999
3000    #[test]
3001    fn authority_expiry_rejects_a_delayed_response() {
3002        let (mut host, now) = new_host();
3003        negotiate(&mut host, required_capabilities());
3004        install_active_authority(&mut host, 1_100);
3005        let request_id = request_id(
3006            host.request_provider_capabilities(handle())
3007                .expect("capability request"),
3008        );
3009        now.set(1_100);
3010        let frame = response_frame(
3011            &host,
3012            request_id,
3013            1,
3014            ServiceResponse::ProviderCapabilities {
3015                binding: binding(),
3016                capabilities: ProviderCapabilitySnapshot {
3017                    provider_schema_version: PROVIDER_SCHEMA_VERSION,
3018                    approval_schema_version: APPROVAL_SCHEMA_VERSION,
3019                    wallet_session_id: wallet_session(),
3020                    permission_generation: 1,
3021                    methods: BTreeSet::new(),
3022                },
3023            },
3024        );
3025        let result = host.accept_service_frame(frame);
3026        assert!(matches!(result, Err(HostError::AuthorityExpired)));
3027        assert_eq!(host.connection_state(), ConnectionState::Failed);
3028    }
3029
3030    #[test]
3031    fn approval_decision_uses_the_stored_private_binding() {
3032        let (mut host, _) = new_host();
3033        let mut capabilities = required_capabilities();
3034        capabilities.insert(ServiceCapability::StructuredApprovals);
3035        negotiate(&mut host, capabilities);
3036        install_active_authority(&mut host, 2_000);
3037        host.approvals.insert(
3038            approval_id(),
3039            HostApproval {
3040                prompt: approval_prompt(),
3041                phase: ApprovalPhase::Available,
3042            },
3043        );
3044        let frame = host
3045            .decide_approval(approval_id(), ApprovalDecision::Reject)
3046            .expect("approval decision");
3047        let HostFrame::Request { envelope } = frame else {
3048            panic!("request frame");
3049        };
3050        assert!(matches!(
3051            envelope.body,
3052            ServiceRequest::ApprovalDecision {
3053                authority_handle,
3054                authority_revision: 1,
3055                approval_id: response_approval_id,
3056                decision: ApprovalDecision::Reject,
3057            } if authority_handle == handle() && response_approval_id == approval_id()
3058        ));
3059    }
3060
3061    #[test]
3062    fn production_followup_host_preserves_exact_sorted_name_disclosure() {
3063        let (mut host, _) = new_host();
3064        let mut capabilities = required_capabilities();
3065        capabilities.insert(ServiceCapability::StructuredApprovals);
3066        negotiate(&mut host, capabilities);
3067        install_active_authority(&mut host, 2_000);
3068        let alpha = HnsNameDisclosure {
3069            name: "alpha".to_owned(),
3070            name_hash: "271878f8a927b4566ac951fc815b18dfad8d0302d61d11d80cbe15b7a3a056af"
3071                .to_owned(),
3072        };
3073        let beta = HnsNameDisclosure {
3074            name: "beta".to_owned(),
3075            name_hash: "f0277d92062bd9a41dd26cddbaf2c41d576cf7b0173cbe96c23d5f5a4f92cc8f"
3076                .to_owned(),
3077        };
3078        let mut prompt = approval_prompt();
3079        prompt.summary = ApprovalSummary::Permissions {
3080            capabilities: BTreeSet::from([PermissionCapability::Names]),
3081            hns_names: vec![beta.clone(), alpha.clone()],
3082        };
3083        assert!(matches!(
3084            host.install_approval(handle(), 1, "wallet_requestPermissions", prompt.clone()),
3085            Err(HostError::ApprovalMismatch)
3086        ));
3087
3088        let expected = vec![alpha, beta];
3089        prompt.summary = ApprovalSummary::Permissions {
3090            capabilities: BTreeSet::from([PermissionCapability::Names]),
3091            hns_names: expected.clone(),
3092        };
3093        host.install_approval(handle(), 1, "wallet_requestPermissions", prompt)
3094            .expect("exact disclosure prompt");
3095        let stored = host.approval(approval_id()).expect("stored disclosure");
3096        assert_eq!(
3097            stored.summary,
3098            ApprovalSummary::Permissions {
3099                capabilities: BTreeSet::from([PermissionCapability::Names]),
3100                hns_names: expected,
3101            }
3102        );
3103    }
3104
3105    #[test]
3106    fn canonical_provider_account_join_capability_snapshot_is_negotiated() {
3107        let (mut host, _) = new_host();
3108        let mut service_capabilities = required_capabilities();
3109        service_capabilities.insert(ServiceCapability::ProviderDispatch);
3110        service_capabilities.insert(ServiceCapability::StructuredApprovals);
3111        negotiate(&mut host, service_capabilities);
3112        install_active_authority(&mut host, 2_000);
3113        host.install_capabilities(
3114            handle(),
3115            1,
3116            binding(),
3117            ProviderCapabilitySnapshot {
3118                provider_schema_version: PROVIDER_SCHEMA_VERSION,
3119                approval_schema_version: APPROVAL_SCHEMA_VERSION,
3120                wallet_session_id: wallet_session(),
3121                permission_generation: 1,
3122                methods: BTreeSet::from(["hns_requestAccounts".to_owned()]),
3123            },
3124        )
3125        .expect("account join capability");
3126    }
3127
3128    #[test]
3129    fn expired_authority_can_be_discarded_without_reusing_its_handle() {
3130        let (mut host, now) = new_host();
3131        negotiate(&mut host, required_capabilities());
3132        install_active_authority(&mut host, 1_100);
3133        host.issued_authority_ids.insert(handle());
3134        now.set(1_100);
3135        host.discard_authority(handle()).expect("discard");
3136        assert!(host.authority(handle()).is_none());
3137        assert!(host.issued_authority_ids.contains(&handle()));
3138    }
3139
3140    #[test]
3141    fn mandatory_approval_cannot_complete_as_a_direct_provider_result() {
3142        let (mut host, _) = new_host();
3143        negotiate(&mut host, required_capabilities());
3144        install_active_authority(&mut host, 2_000);
3145        let result = host.apply_response(
3146            &RequestClass::Provider {
3147                handle: handle(),
3148                revision: 1,
3149                method: "hns_send".to_owned(),
3150            },
3151            &ServiceResponse::ProviderResult {
3152                binding: binding(),
3153                value: Value::Null,
3154            },
3155        );
3156        assert!(matches!(result, Err(HostError::ResponseClassMismatch)));
3157    }
3158
3159    #[test]
3160    fn permission_mutation_requires_exactly_one_generation_advance() {
3161        let (mut host, _) = new_host();
3162        negotiate(&mut host, required_capabilities());
3163        install_active_authority(&mut host, 2_000);
3164        let result =
3165            host.apply_provider_binding(handle(), 1, "wallet_revokePermissions", binding());
3166        assert!(matches!(result, Err(HostError::StaleBinding)));
3167    }
3168
3169    #[test]
3170    fn wallet_locked_event_clears_current_provider_state() {
3171        let (mut host, _) = new_host();
3172        let mut capabilities = required_capabilities();
3173        capabilities.insert(ServiceCapability::TypedEvents);
3174        negotiate(&mut host, capabilities);
3175        install_active_authority(&mut host, 2_000);
3176        let event = ProviderEventEnvelope {
3177            protocol_version: WALLET_ABI_VERSION,
3178            host_session_id: host.host_session_id(),
3179            service_session_id: service_session(),
3180            restart_generation: host.restart_generation(),
3181            channel_sequence: 1,
3182            binding: binding(),
3183            event_sequence: 1,
3184            payload: ProviderEventPayload::WalletLocked,
3185        };
3186        host.accept_service_frame(ServiceFrame::Event { event })
3187            .expect("wallet locked event");
3188        assert!(
3189            host.authority(handle())
3190                .expect("authority")
3191                .binding
3192                .is_none()
3193        );
3194    }
3195
3196    #[test]
3197    fn completed_approval_identifier_cannot_be_reused() {
3198        let (mut host, _) = new_host();
3199        negotiate(&mut host, required_capabilities());
3200        install_active_authority(&mut host, 2_000);
3201        host.install_approval(handle(), 1, "wallet_requestPermissions", approval_prompt())
3202            .expect("first prompt");
3203        host.approvals.remove(&approval_id());
3204        let result =
3205            host.install_approval(handle(), 1, "wallet_requestPermissions", approval_prompt());
3206        assert!(matches!(result, Err(HostError::ApprovalMismatch)));
3207    }
3208}