Mobile: Deep links and push notifications are not wired into one routing system, so taps go nowhere

[Emmy123222]

Goal this serves — Donors arriving from a link or notification reaching the right screen

Why this matters

Two of the main ways a donor returns to the app — following a shared project link, and tapping a notification about a project they support — depend on routing that is only partly built. A donor who taps a notification about a milestone should land on that project; today the machinery to do so is not connected.

Both paths also accept externally supplied input, which makes them a security boundary as well as a usability one.

Evidence

mobile/utils/notifications.ts exports registerDeviceToken and setupNotificationListener, and a search across app/, src/, components/ and hooks/ finds no caller for either. So the backend never receives a device token, and no listener exists to respond to a notification tap.

Deep link parsing exists separately in mobile/hooks/useDeepLink.ts with its own validation, and the two have no shared notion of a destination. There is no Android notification channel, which that platform requires before notification presentation settings take effect.

Why this is hard

Cold start versus warm start differ. A tap on a cold app must hold the destination until navigation is ready, and getting this wrong produces a link that works only when the app is already open — a bug that reproduces inconsistently and wastes enormous debugging time.

External input reaches routing. Both a link and a notification payload are attacker-influenceable, so destinations must be validated against an allowlist rather than constructed from received data.

Permission timing. Requesting notification permission at the wrong moment gets it denied permanently, and Android and iOS differ in how a denial can be recovered.

Token lifecycle. Device tokens rotate, and must be tied to wallet connection and disconnection so notifications do not follow a device after the donor disconnects.

Testing is genuinely hard. Cold-start routing and notification taps need harnesses that do not exist here yet.

Suggested approach

Define one destination model that both entry points resolve into, validated against an allowlist so no externally supplied value becomes a route directly.

Handle cold start explicitly by holding the pending destination until navigation is ready.

Wire token registration into the wallet lifecycle, create the Android channel before any notification arrives, and request permission on explicit user intent with a rationale shown first.

Acceptance criteria

• A single destination model resolves both deep links and notification taps.
• Destinations are validated against an allowlist; no externally supplied value becomes a route directly.
• Cold start and warm start both route correctly, each covered by a test.
• Device tokens are registered with the backend and tied to wallet connect and disconnect.
• Token rotation is handled without leaving stale registrations.
• The Android notification channel is created before any notification is received.
• Permission is requested on explicit user intent with a rationale shown first, and denial is recoverable.
• Malformed and hostile link payloads are rejected safely, covered by fuzz tests.
• Tapping a donation or milestone notification lands on the correct screen on both platforms, verified on devices.

Scope

Roughly 5,000–7,000 lines, including tests.

Relevant files

• mobile/utils/notifications.ts
• mobile/hooks/useDeepLink.ts
• mobile/app/_layout.tsx
• mobile/app.json

[stayzappy]

Proposal: Unify Deep Linking and Push Notification Routing System (#509)

I would like to take on this task to build a centralized, secure navigation dispatch engine for GreenPay that bridges push notification taps and deep links across both cold and warm application lifecycles.

---

Implementation Plan

1. Unified Destination Model & Route Allowlisting

• Create a strongly typed, centralized destination schema in mobile/utils/routing/types.ts (e.g., Destination { screen, params }).
• Implement an explicit route allowlist parser that sanitizes incoming deep link URLs and notification data payloads (e.g., project milestones, donation confirmations) so externally supplied input never gets injected directly into the router.
• Reject malformed, unauthorized, or prototype-polluting payloads with safe fallback to the home feed.

2. Cold-Start vs. Warm-Start Navigation Orchestration

• In mobile/app/_layout.tsx, implement a pending-intent queue/buffer:

• Cold Start: Hold the parsed destination in memory until the root navigation container and auth state signal readiness, then execute the transition.

• Warm Start: Dispatch immediately via the navigation ref when the app is active or in background.

• Setup native Android notification channels early in the boot sequence prior to any incoming message rendering.

3. Wallet-Tied Device Token Lifecycle & Permissions

• Wire registerDeviceToken and cleanup logic directly into wallet connection and disconnection events to prevent notification leakage across accounts.
• Handle background token refresh/rotation, syncing updates to the backend and revoking stale tokens upon wallet detachment.
• Implement a pre-permission rationale modal triggered by explicit user intent rather than on initial launch, with clear recovery guidance for settings redirection if previously denied.

4. Comprehensive Testing & Security Hardening

• Fuzz & Boundary Tests: Unit test payload parsing against hostile, malformed query params and unknown route targets.
• Lifecycle Tests: Mock navigation ready states to verify cold-start buffering vs. warm-start instant resolution.
• Token Lifecycle Tests: Validate registration and deregistrations across wallet connect/disconnect triggers.

---

Acceptance Criteria Checklist

• Single destination model resolving deep links and push taps against a strict allowlist.
• Cold-start queueing ensuring reliable routing without timing race conditions.
• Android notification channel established during early app bootstrap.
• Token registration strictly linked to wallet connect/disconnect lifecycle with rotation handling.
• Contextual permission request flow with denial recovery paths.
• Full unit, fuzz, and routing lifecycle test suites included.

Estimated Timeline: 3–5 days given the cross-platform scope and test harnesses. Ready to begin immediately upon assignment!

[Nanle-code]

I’d like to take on #509.

My interest in this issue is the combination of mobile routing, asynchronous lifecycle handling, and security. The current separation between deep-link handling and notification handling creates a real reliability gap, particularly around cold starts, while both paths introduce externally controlled input into the navigation layer.

I can implement this around a single typed destination model that is shared by deep links and notification taps, with strict allowlist validation so externally supplied values can never directly become navigation routes. I’ll also handle pending destinations explicitly until the navigation tree is ready, covering both warm-start and cold-start flows.

For the notification side, I’ll wire device-token registration into the wallet lifecycle, account for token rotation and disconnect cleanup, and ensure the Android notification channel is initialized before notification delivery. Permission requests will be tied to explicit user intent with an appropriate rationale rather than being triggered unexpectedly.

I’ll place particular emphasis on the security and failure paths: malformed URLs, unexpected parameters, hostile payloads, unsupported destinations, stale notification data, duplicate events, and navigation attempts before the app is ready. These should fail closed rather than producing arbitrary navigation.

Testing will cover the complete lifecycle, including cold/warm starts, deep links, notification taps, wallet connect/disconnect, token rotation, permission denial/recovery, malformed payloads, and cross-platform behavior. I’ll also add fuzz-oriented validation around externally supplied deep-link and notification data.

I’m comfortable working across TypeScript/JavaScript application code, API integrations, state/lifecycle management, and security-sensitive validation. I’ll keep the implementation focused on the existing architecture and provide the necessary tests and documentation so the routing behavior is deterministic and maintainable.

I’m ready to start by reviewing the existing mobile navigation, notification, wallet lifecycle, and deep-link flows and then implementing the shared routing boundary incrementally.

[grantfox-oss]

🦊 GrantFox — @Nanle-code has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #509)
2. Your PR will be reviewed by the Stellar-Search maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Third Campaign campaign!

@Nanle-code's PR #547 was approved and merged by @Emmy123222.

🏆 @Nanle-code: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (885 total points). Track your full progress on GrantFox.

👏 Great work, @Nanle-code! Keep contributing to Stellar-Search.