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
33pub trait Clock {
36 fn now_unix_ms(&self) -> Result<u64, ClockError>;
37}
38
39pub 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
535pub 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 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 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 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 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 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(¤t, &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, ¶ms)?;
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 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 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 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 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}